--- name: arsip-document description: "Analyzes, archives, and indexes uploaded documents. Automatically saves files to /home/ubuntu/holomoc-file/YYYY/MM/DD/ and maintains a searchable JSON index at /home/ubuntu/holomoc-file/arsip-index.json. NOTE: MoM (Minutes of Meeting) has its own separate index at mom-index.json — handled by skill 'mom'." metadata: version: 3.3.0 category: document-automation --- --- # RESPONSE FORMAT RULES (WAJIB) **Setiap kali merespon user di chat, GUNAKAN FORMAT LIST (bullet/numbered).** - ✅ Tampilkan data sebagai **numbered list** atau **bullet list** yang rapi - ✅ Gunakan emoji untuk memperjelas konteks (📋, 👤, 💰, 📝, 📌, dll) - ❌ JANGAN gunakan format **tabel markdown** (`| kolom | kolom |`) - ❌ JANGAN gunakan `plt.table()` atau representasi tabel apapun - ❌ JANGAN buat tabel visual di chat — chat adalah teks, bukan spreadsheet - Jika data memiliki banyak field per item, gunakan format indentasi per item seperti contoh di workflow masing-masing --- # Document Archive Specialist ## Folder Structure ``` /home/ubuntu/holomoc-file/ └── YYYY/ └── MM/ └── DD/ ├── original_filename.ext └── ... ``` File disimpan berdasarkan tanggal arsip (bukan tanggal dokumen). ## Index File ``` /home/ubuntu/holomoc-file/arsip-index.json ``` Index ini WAJIB di-update setiap kali file diarsipkan. Index ini juga menjadi sumber utama saat user mencari file. **⚠️ BOUNDARY: JANGAN menulis entry finance (cashbon/reimburse) ke arsip-index.json.** Finance memiliki index sendiri di `/home/ubuntu/holomoc-file-finance/finance-index.json`. Jika user mengajukan cashbon atau reimburse, gunakan skill `finance` (referensi di `references/cashbon-workflow.md` dan `references/reimburse-workflow.md`), BUKAN skill ini. **⚠️ BOUNDARY: MoM (Minutes of Meeting) memiliki index TERPISAH** di `/home/ubuntu/holomoc-file-mom/mom-index.json`. MoM dibuat via skill `mom`, BUKAN skill ini. Jangan tambahkan entry MoM ke arsip-index.json. NOTE: Jangan pakai `~` karena HOME di-override oleh profile. Selalu gunakan absolute path `/home/ubuntu/holomoc-file/arsip-index.json`. --- ## Workflow 1: Arsipkan File Saat user mengirim file atau berkata "arsipkan dokumen ini": ### Step 1: Terima File - Ambil file dari pesan user (attachment/link/path) - Catat nama file asli dan ekstensi ### Step 2: Analisis Konten — Ekstraksi Teks per Tipe File Ekstrak isi dokumen menggunakan metode yang sesuai dengan tipe file: | Tipe File | Metode | Perintah | |-----------|--------|---------| | **PDF (text-based)** | `pymupdf` | `python3 -c "import pymupdf; doc=pymupdf.open('file.pdf'); [print(p.get_text()) for p in doc]"` | | **PDF (scanned/OCR)** | `marker-pdf` (via skill `ocr-and-documents`) | Butuh ~5GB untuk model. Gunakan hanya jika pymupdf tidak menghasilkan teks. | | **DOCX** | `python-docx` | `python3 -c "from docx import Document; d=Document('file.docx'); [print(p.text) for p in d.paragraphs]"` | | **Gambar (JPG/PNG)** | vision_analyze / nama file | Gunakan `vision_analyze` atau ekstrak konteks dari nama file dan pesan user. | | **XLSX** | `openpyxl` | `python3 -c "import openpyxl; wb=openpyxl.load_workbook('file.xlsx'); [print(ws.title) for ws in wb.worksheets]"` | | **PPTX** | `python-pptx` (via skill `powerpoint`) | `python3 -c "from pptx import Presentation; prs=Presentation('file.pptx'); [s.text for slide in prs.slides for s in slide.shapes if hasattr(s,'text')]"` | | **TXT/CSV/JSON** | `read_file` langsung | `read_file(path)` | **Penting:** - `pip install pymupdf python-docx openpyxl` jika belum terinstall (pakai `-q` untuk silent install). - Untuk PDF yang tidak menghasilkan teks dengan pymupdf, file mungkin scanned — set `confidential: true` dan catat di summary bahwa isi perlu review manual. - Jika file tidak bisa diekstrak sama sekali, tetap simpan file dan buat entry dengan summary dari nama file + konteks chat. Setelah teks didapatkan, tentukan: judul, kategori, ringkasan (maks 3 kalimat), keywords, extracted_entities. ### Step 3: Update Index JSON via Script (DULUAN — sebelum copy file) **⚠️ PENTING: Jalankan add_arsip.py SEBELUM copy file.** Jika file di-copy dulu, `add_arsip.py` akan mendeteksi file sudah ada di path tujuan dan salah menganggapnya duplikat, sehingga menambahkan suffix `_2` yang tidak perlu. Gunakan script `add_arsip.py` untuk menambahkan entry ke index. Script otomatis generate id, date_archived, correct saved_path (handle duplikat), dan update total_files/last_updated. ```bash # Kirim metadata sebagai argumen JSON — JANGAN isi saved_path, biarkan auto-generate python3 /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/arsip-document/scripts/add_arsip.py '{ "original_name": "nama_asli_file.pdf", "category": "Finance", "summary": "Ringkasan isi dokumen maksimal 3 kalimat.", "keywords": ["invoice", "hosting", "juni 2026"], "file_size": "245KB", "sender_context": "User berkata: tolong arsipkan invoice hosting", "extracted_entities": { "persons": ["Budi Santoso"], "organizations": ["PT Hosting Indonesia"], "amounts": ["Rp 500.000"] } }' ``` Required fields: `original_name`, `category`. Optional: `summary`, `keywords`, `file_size`, `confidential`, `sender_context`, `extracted_entities`. **JANGAN isi `saved_path`** — biarkan script auto-generate agar duplicate-handling bekerja benar. **Ekstrak path dari output script:** Setelah menjalankan `add_arsip.py`, output akan mencantumkan path yang dihasilkan: ``` OK: file.pdf ditambahkan ke arsip ID: arsip_20260607_001 Path: /home/ubuntu/holomoc-file/2026/06/07/file.pdf ← ambil path ini Kategori: Technical ``` Catat path tersebut untuk Step 4. Tidak perlu baca/tulis JSON index secara manual — script handle semua otomatis. ### Step 4: Simpan File ke Path yang Dihasilkan Script Gunakan path yang keluar dari output `add_arsip.py` di Step 3. ```bash # Buat direktori parent (jika belum ada) mkdir -p "$(dirname /home/ubuntu/holomoc-file/2026/06/07/file.pdf)" # Copy file ke path persis yang dihasilkan script cp /home/ubuntu/holomoc-file/2026/06/07/file.pdf ``` Jika nama file sudah ada, `add_arsip.py` sudah otomatis menambahkan suffix angka (misal `_2`) di Step 3 — jadi tidak perlu manual handle duplikat lagi. ### Step 5: Konfirmasi Kirimkan konfirmasi ke user: ``` File berhasil diarsipkan: - Nama: nama_asli_file.pdf - Lokasi: /home/ubuntu/holomoc-file/2026/06/06/ - Kategori: Finance - Ringkasan: [ringkasan singkat] ``` --- ## Workflow 2: Cari Arsip Saat user berkata "cari file X", "cari arsip tentang Y", "file invoice bulan lalu dimana?": ### ⛔ LARANGAN MUTLAK - JANGAN gunakan `search_files` atau `find`/`ls`/`grep` untuk mencari file arsip. - JANGAN scan folder `/home/ubuntu/holomoc-file/` secara manual. - WAJIB gunakan arsip-index.json sebagai SATU-SATUNYA sumber pencarian. - Alasan: Index berisi metadata lengkap (kategori, ringkasan, keywords, entitas) yang TIDAK ada di filesystem. ### Step 1: Jalankan Search Script ```bash python3 /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/arsip-document/scripts/search_arsip.py "" ``` Atau baca langsung index JSON: ```bash cat /home/ubuntu/holomoc-file/arsip-index.json ``` ### Step 2: Filter & Cari Cari di index berdasarkan: - Nama file (`original_name`) - Ringkasan (`summary`) - Keywords (`keywords`) - Kategori (`category`) - Entitas (`extracted_entities` - persons, organizations, amounts) - Konteks pengiriman (`sender_context`) - Tanggal arsip (`date_archived`) Gunakan fuzzy matching - user mungkin tidak ingat nama persis. ### Step 3: Tampilkan Hasil & Kirim File **WAJIB dalam format LIST (bullet/numbered), JANGAN gunakan format tabel markdown.** ``` Ditemukan 2 arsip: 1. invoice_hosting_juni.pdf Lokasi: /home/ubuntu/holomoc-file/2026/06/01/ Kategori: Finance Ringkasan: Invoice hosting bulan Juni dari PT Hosting Indonesia, Rp 500.000 2. kwitansi_pembayaran.pdf Lokasi: /home/ubuntu/holomoc-file/2026/05/28/ Kategori: Finance Ringkasan: Kwitansi pembayaran hosting Q2, Rp 1.500.000 ``` Jika tidak ditemukan, sarankan kata kunci alternatif atau cek apakah file sudah diarsipkan. ### Step 4: Kirim File via MEDIA (jika user minta "lihat file") **⚠️ DELIVERY CLARITY — WAJIB sebut nomor tujuan di respons pertama.** Saat user minta "lihat file X" dan Anda kirim via `send_message` dengan MEDIA, user sering bingung file dikirim ke mana. Hindari dengan pola berikut: **✅ BENAR (respons pertama setelah kirim):** > ✅ File **nama.pdf** sudah terkirim ke nomor WhatsApp **+628xxxxxxxx** Anda saat ini. Silakan cek chat WhatsApp kita. **❌ SALAH (hanya bilang "sudah terkirim" tanpa nomor):** > ✅ File sudah terkirim ke chat WhatsApp Anda. **Penyebab kebingungan:** User tidak melihat notifikasi langsung di WhatsApp dan bertanya-tanya "dikirim ke nomor siapa?" atau "dikirim kemana?". Selalu sebutkan nomor tujuan secara eksplisit. **Catatan:** Sistem hanya bisa mengirim ke nomor WhatsApp user yang sedang berinteraksi (home channel). Jika user minta dikirim ke nomor lain, jelaskan keterbatasan ini dan tawarkan alternatif (email, atau user forward sendiri). --- ## Workflow 3: Rekap & Ekspor Arsip Saat user berkata "rekap arsip", "lihat semua file", "arsip bulan ini", "buatkan list arsip", "buatkan excel", "buatkan gambar / png", "buatkan pdf": ### ⚙️ Aturan Default Output **📝 Chat text (inline list) adalah format DEFAULT.** - ✅ Tampilkan data sebagai bullet/numbered list di chat - ❌ Jangan generate gambar/PNG kecuali user minta eksplisit ("buatkan gambar", "buat png") - ❌ Jangan generate Excel kecuali user minta eksplisit ("buatkan excel", "buatkan xlsx") - ❌ Jangan generate PDF kecuali user minta eksplisit ("buatkan pdf", "bikin pdf", "jadiin pdf") ### ⚙️ Sumber Data - **Arsip dokumen:** baca `/home/ubuntu/holomoc-file/arsip-index.json` - **Arsip keuangan (cashbon/reimburse):** baca `/home/ubuntu/holomoc-file-finance/finance-index.json` - **Arsip MoM (Minutes of Meeting):** baca `/home/ubuntu/holomoc-file-mom/mom-index.json` - Gabungkan data dari ketiga sumber jika user minta rekap komprehensif. ### 📋 Output ke Chat (default) Baca index, filter sesuai permintaan, **tampilkan dalam bentuk LIST (bukan tabel markdown)** menggunakan format bullet/numbered dengan detail: Nama file, Kategori/Tipe, Ringkasan. ### 📊 Output ke Excel (.xlsx) **Gunakan script `generate_excel.py` dari skill `generate-format`.** 1. Baca data dari index (`arsip-index.json` dan `finance-index.json`) 2. Buat dua file JSON sementara sesuai format yang dibutuhkan: - `/tmp/arsip_data.json` — untuk data arsip dokumen - `/tmp/finance_data.json` — untuk data keuangan (cashbon & reimburse) 3. Jalankan script: ```bash python3 /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/generate-format/scripts/generate_excel.py /tmp/arsip_data.json /tmp/finance_data.json ``` 4. Kirim file via `MEDIA:/home/ubuntu/holomoc-file/List_Arsip_Holomoc.xlsx` Untuk detail format JSON input, lihat skill `generate-format`. ### 🖼️ Output ke Gambar (.png) **Gunakan script `generate_png.py` dari skill `generate-format`.** 1. Baca data dari index (`arsip-index.json` dan `finance-index.json`) 2. Buat dua file JSON sementara sesuai format yang dibutuhkan: - `/tmp/arsip_data.json` — untuk data arsip dokumen - `/tmp/finance_data.json` — untuk data keuangan (cashbon & reimburse) 3. Jalankan script: ```bash python3 /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/generate-format/scripts/generate_png.py /tmp/arsip_data.json /tmp/finance_data.json ``` 4. File PNG yang dihasilkan: - `/home/ubuntu/holomoc-file/List_Arsip_Dokumen.png` — gambar arsip dokumen - `/home/ubuntu/holomoc-file/List_Arsip_Keuangan.png` — gambar arsip keuangan 5. Kirim file via `MEDIA:` dengan path yang sesuai Untuk detail format JSON input, lihat skill `generate-format`. ### 📄 Output ke PDF (.pdf) **Gunakan script `generate_pdf.py` dari skill `generate-format`.** 1. Baca data dari index (`arsip-index.json` dan `finance-index.json`) 2. Buat dua file JSON sementara sesuai format yang dibutuhkan: - `/tmp/arsip_data.json` — untuk data arsip dokumen - `/tmp/finance_data.json` — untuk data keuangan (cashbon & reimburse) 3. Jalankan script: ```bash python3 /home/ubuntu/.hermes/profiles/holomoc-admin/skills/holomoc/generate-format/scripts/generate_pdf.py /tmp/arsip_data.json /tmp/finance_data.json ``` 4. File PDF yang dihasilkan: - `/home/ubuntu/holomoc-file/List_Arsip_Holomoc.pdf` — laporan landscape A4 lengkap 5. Kirim file via `MEDIA:/home/ubuntu/holomoc-file/List_Arsip_Holomoc.pdf` Untuk detail format JSON input, lihat skill `generate-format`. --- ## Categories - `Finance` - Invoice, kwitansi, laporan keuangan, faktur - `Legal` - Kontrak, perjanjian, surat kuasa, akta - `Technical` - Dokumentasi teknis, spesifikasi, laporan - `HR` - Kontrak kerja, slip gaji, dokumen karyawan - `Operational` - SOP, laporan operasional, inventaris - `Correspondence` - Surat masuk/keluar, email penting - `General` - Lainnya --- ## MCP Integration Patterns ### Sequential Orchestration Workflow Arsip Dokumen memiliki 5 langkah berurutan yang WAJIB diikuti: **Step 1 (Terima File)** → **Step 2 (Analisis Konten)** → **Step 3 (Update Index via Script — DULUAN)** → **Step 4 (Simpan File ke Path Hasil Script)** → **Step 5 (Konfirmasi)**. Jika salah satu step gagal, jangan lanjut ke step berikutnya. Catat error dan laporkan ke user. ### Multi-MCP (Cross-Skill Coordination) Kolaborasi dengan skill lain yang sudah terdefinisi: - **arsip-document → finance**: Jika user mengirim file atau berkata tentang cashbon/reimburse, JANGAN proses di skill ini. Arahkan ke skill `finance`. - **arsip-document → generate-format**: Saat user minta export Excel/PNG, gunakan script `generate-format` dengan data yang sudah diformat dari index. - **arsip-document → mom**: Jika user mengirim file meeting notes atau berkata "buat mom", arahkan ke skill `mom`. ### Iterative Refinement - Jika hasil ekstraksi teks memiliki confidence rendah (dokumen scanned/OCR gagal ekstrak): set `confidential: true` dan `needs_manual_review: true`, informasikan ke user. - Jika dokumen tidak bisa dianalisis sama sekali: tetap simpan file dengan summary minimal dari nama file + konteks chat user. - Untuk pencarian yang tidak menemukan hasil (search_arsip.py mengembalikan kosong): coba variasi kata kunci — sinonim, Bahasa Inggris/Indonesia, kata dasar tanpa imbuhan — sebelum menyimpulkan tidak ada. ## Agent Iteration & Evaluation Guidance ### Trigger Phrase Testing Skill ini akan terpanggil saat user menggunakan kata/frasa berikut. Jika skill terlalu sering aktif di luar konteks (overtriggering), persempit deskripsi di frontmatter dan tambahkan negative triggers. - ✅ "arsipkan", "simpan file", "arsipkan dokumen", "simpan dokumen" - ✅ "cari arsip", "cari file", "cari dokumen", "file where", "dimana file" - ✅ "rekap arsip", "lihat semua file", "arsip bulan ini" - ✅ "buatkan excel", "buatkan gambar", "buat png", "buatkan pdf", "buatkan list arsip" - ✅ Saat user mengirim file/attachment ### Failure Recovery - **File tidak bisa dibaca (Step 2 gagal)**: Set `confidential: true`, buat summary dari nama file + konteks chat, tetap simpan dan buat entry di index. - **Script add_arsip.py gagal**: Cek apakah index JSON valid (backup dulu jika curiga corrupt), cek permission direktori `/home/ubuntu/holomoc-file/`. - **Symptom spesifik: `AttributeError: 'list' object has no attribute 'get'`** — berarti isi index adalah bare array `[]` bukan objek `{"files": [...]}`. Solusi: tulis ulang index dengan format yang benar: `write_file(path="/home/ubuntu/holomoc-file/arsip-index.json", content='{"version":"1.0","last_updated":"","total_files":0,"files":[]}')` lalu jalankan ulang `add_arsip.py`. - **Path file di index punya suffix `_2` padahal file asli tanpa suffix**: Penyebab — file di-copy dulu (Step 4 lama) sebelum add_arsip.py jalan (Step 3 seharusnya). Solusi: baca index, perbaiki `saved_path` entry terakhir ke path file yang benar, lalu hapus file `_2` jika ada. - **Script search_arsip.py tidak menemukan hasil**: Coba kata kunci alternatif, atau tampilkan semua arsip tanpa filter. - **Index JSON corrupt**: Backup ke `arsip-index.json.bak`, buat index baru, rebuild dengan scan folder arsip. ### Precondition Verification Sebelum menjalankan workflow apa pun, WAJIB verifikasi: 1. ✅ File yang akan diarsipkan masih bisa diakses (belum dihapus/dipindah) 2. ✅ Index JSON bisa dibaca (bukan corrupt) 3. ✅ Folder tujuan (`/home/ubuntu/holomoc-file/YYYY/MM/DD/`) bisa ditulisi --- ## Troubleshooting **Error:** File tidak bisa dibaca atau terpotong **Solution:** Set `confidential: true` dan catat di summary bahwa file perlu review manual. Tetap simpan file dan buat entry di index. **Error:** Nama file duplikat **Solution:** Tambahkan suffix angka: `file_2.pdf`, `file_3.pdf`, dst. **Error:** Index JSON corrupt / invalid **Solution:** Backup file lama ke `arsip-index.json.bak`, buat index baru, lalu scan ulang folder `/home/ubuntu/holomoc-file/` untuk rebuild index. **Error:** Script `add_arsip.py` error `'list' object has no attribute 'get'` — index file berisi `[]` (empty array) bukan struktur JSON objek. **Cause:** File index baru dibuat secara manual dengan `[]` atau diinisialisasi oleh proses lain sebagai array kosong, padahal script mengharapkan `{"version": "1.0", "files": []}`. **Immediate fix:** Tulis ulang index dengan struktur yang benar: ```bash echo '{"version":"1.0","last_updated":"","total_files":0,"files":[]}' > /home/ubuntu/holomoc-file/arsip-index.json ``` Kemudian jalankan ulang `add_arsip.py`. **Prevention:** Saat pertama kali inisialisasi, selalu gunakan struktur objek, bukan array. Script `add_arsip.py` sudah auto-create direktori parent saat `save_index()`, tapi tidak auto-create file — jadi pastikan file index sudah ada dengan struktur yang benar sebelum pertama kali digunakan. **Error:** `AttributeError: 'list' object has no attribute 'get'` saat menjalankan `add_arsip.py` **Cause:** File `arsip-index.json` berisi `[]` (bare array) bukan format objek yang diharapkan `{"version":"1.0", "files": [...]}`. Ini bisa terjadi jika index baru dibuat manual dengan `[]` atau file index corrupt menjadi array. **Solution:** Tulis ulang index dengan struktur yang benar menggunakan write_file: ``` write_file(path="/home/ubuntu/holomoc-file/arsip-index.json", content='{"version":"1.0","last_updated":"","total_files":0,"files":[]}') ``` Lalu jalankan ulang `add_arsip.py`. Jangan lupa verifikasi file index bisa dibaca setelahnya. **Error:** `MEDIA attachments were omitted` untuk WhatsApp saat kirim file **Solution:** Ini sudah diperbaiki di code `send_message_tool.py`. WhatsApp sekarang mendukung pengiriman file via `MEDIA:/path/to/file` di send_message tool. Pastikan WhatsApp bridge sedang berjalan dan terkoneksi. Jika masih gagal, cek log gateway: `grep -i "whatsapp" ~/.hermes/logs/gateway.log | tail -10` **Error:** Pencarian dengan kata kunci Bahasa Indonesia tidak ketemu, padahal file ada. **Cause:** search_arsip.py melakukan keyword matching (bukan NLP). Contoh: user cari "report progres" tapi di index tertulis "progress report" (Bahasa Inggris). **Solution:** Jika hasil pencarian kosong, coba kata kunci alternatif: sinonim, Bahasa Inggris/Indonesia, kata dasar tanpa imbuhan. Gunakan search_arsip.py dengan beberapa variasi kata kunci sebelum menyimpulkan file tidak ada.