| name | python3 documents/scripts/documents.py |
| display_name | 문서 검색 및 생성 |
| description | Search, read, save, and generate documents in the knowledge base (문서 검색, 파일 찾아줘, 문서에서 정보 찾아줘, 업로드한 파일, 지식베이스에 저장, 파일 저장, 문서 만들어줘, 문서 생성, 보고서 작성, 워드 문서 생성, Word 파일 만들어줘, 마크다운 파일 생성, PDF 만들어줘, 엑셀 파일 만들어줘, PPT 만들어줘, 한글 파일 만들어줘, hwp 만들어줘, hwpx 만들어줘) — vector + full-text search over indexed documents; save chat/Telegram file attachments; generate AI-written documents (docx/pdf/xlsx/pptx/hwpx/hwp/md/txt) uploaded to MinIO |
| version | 1.5.0 |
| emoji | 📄 |
| category | knowledge |
| enabled_by_default | true |
| requires_api_key | optional |
| platforms | web, telegram, api |
| uses_provider | false |
| requires | {"bins":["python3 documents/scripts/documents.py"]} |
| allowed-tools | ["Bash","exec"] |
| triggers | {"keywords":["문서","파일","문서 검색","파일 찾아줘","지식베이스","업로드한","저장된","보고서","워드","엑셀","PDF","PPT","한글","HWP","마크다운","문서 만들어","문서 생성","document","report","search files","knowledge base","generate document","docx","xlsx","pptx"],"when_to_use":["User uploads a file or asks to save/index a file","User wants to search for documents in the knowledge base","User asks to create or generate a document (Word, PDF, Excel, PPT, HWP)","User asks \"파일 찾아줘\" or \"문서에서 정보 찾아줘\"","User references previously uploaded documents"]} |
Document Search & Knowledge Base
Use python3 documents/scripts/documents.py to search, read, and save documents into the knowledge base. Works for both web chat and Telegram — no platform distinction needed.
Always pass --user-id {user_id} (extract from [Context: user_id=...] at the top of the message).
API Key & Search Mode
문서 색인(indexing)과 검색은 API 키 설정 여부에 따라 동작 방식이 다릅니다:
| 상태 | 색인 | 검색 방식 |
|---|
| Gemini API 키 있음 | 텍스트 + 벡터 임베딩 저장 | 시멘틱 검색 (의미 유사도) + 전문 검색 |
| API 키 없음 | 텍스트만 저장 (임베딩 없음) | 전문 검색 (키워드 매칭)만 가능 |
Gemini API 키는 Settings → Integrations에서 설정합니다.
API 키 없이도 문서 업로드·색인·검색은 모두 가능하지만, 의미 기반 검색은 제공되지 않습니다.
When to use Document skill
| User intent | Use |
|---|
| User wants to find information inside their uploaded documents | search |
| User wants to see a list of their uploaded documents | list |
| User wants to read the contents of a specific document | read |
| User attaches a file and wants it saved to the knowledge base | save |
| User wants a new document created/written/generated in any file format (Word, PDF, Excel, PPT, Hangeul, markdown, etc.) | generate |
| General knowledge question not about their files | Use websearch or answer directly |
중요: LLM이 문서 내용을 직접 작성한 뒤 파일로 저장할 때는 반드시 generate 커맨드를 사용하세요.
절대로 로컬에 .md 파일을 직접 만들지 마세요 — 모든 파일은 MinIO에 업로드되어야 합니다.
File Attachment Flow (Web & Telegram)
When a user attaches a file ([file:name:URL] or [image:URL]) and asks a question:
- Use the file for the immediate response (text extraction, context injection)
- After answering, proactively suggest saving:
"이 파일을 지식베이스에 저장해 드릴까요? 저장하면 나중에도 '파일에서 ~ 찾아줘'로 검색할 수 있어요."
- If user confirms → run the
save command with the file URL
This flow applies uniformly to web chat and Telegram — no platform-specific handling needed.
Trigger phrases for save suggestion: 파일 첨부, 문서 전송, 이미지/PDF/Word 파일 수신
Commands
List uploaded documents
python3 documents/scripts/documents.py --user-id {user_id} list
Search documents by keyword or phrase
python3 documents/scripts/documents.py --user-id {user_id} search \
--query "{search query}"
Optionally limit results:
python3 documents/scripts/documents.py --user-id {user_id} search \
--query "{search query}" \
--limit 5
Read sections of a specific document
python3 documents/scripts/documents.py --user-id {user_id} read \
--doc-id {document_id}
Save a chat/Telegram file attachment to the knowledge base
python3 documents/scripts/documents.py --user-id {user_id} save \
--url "{file_url}" \
--filename "{original_filename}"
Extract {file_url} from the [file:name:URL] or [image:URL] tag in the message.
Extract {original_filename} from the name part of the tag.
Generate a document from AI-written content and upload to MinIO
Use this whenever the user asks you to create, write, or save a document.
Format inference — no need to ask the user
Match user intent to format semantically, regardless of language:
| User intent | --format |
|---|
| Word processor document (Word, 워드, Documento Word, Wortdokument, etc.) | docx |
| PDF file | pdf |
| Spreadsheet / tabular data (Excel, 엑셀, tableur, Tabelle, etc.) | xlsx |
| Presentation / slides (PowerPoint, 발표자료, diapositivas, etc.) | pptx |
| Hangeul XML format (hwpx, 한글 문서 XML) | hwpx |
| Hangeul binary format (hwp — requires LibreOffice) | hwp |
| Markdown / plain markup file | md |
| Plain text file | txt |
| Not specified or ambiguous | docx (default) |
The table above describes intent categories, not keyword lists.
"워드 문서", "Word document", "documento de Word" all map to docx —
no need to enumerate every language variant.
printf '%s' "{markdown content}" | \
python3 documents/scripts/documents.py --user-id {user_id} generate \
--title "{document title without extension}" \
--format docx
--format accepts docx (default), pdf, xlsx, pptx, hwpx, hwp, md, txthwpx: 한글 XML 포맷 (LibreOffice 불필요, stdlib만 사용)hwp: LibreOffice 변환 방식 (서버에 LibreOffice 필요; 없으면 hwpx 권장)- Content is piped via stdin as markdown (the script converts automatically — no pandoc required)
- The script uploads to MinIO, inserts into the
documents table, auto-indexes for search, and prints the download link
Expected output (last line):
[📄 {filename}.docx](/api/files/users/{user_id}/docs/{year}/{uuid}.docx)
The agent must include this output link in the response so the user can download the document. It will render as a download card in the web chat and be sent as a file in Telegram.
Examples
User: "내가 업로드한 파일 목록 보여줘"
python3 documents/scripts/documents.py --user-id abc123 list
User: "계약서에서 해지 조항 찾아줘"
python3 documents/scripts/documents.py --user-id abc123 search \
--query "해지 조항"
User: "2번 문서 내용 읽어줘"
python3 documents/scripts/documents.py --user-id abc123 read \
--doc-id 2
User sends [file:계약서.pdf:https://files.example.com/abc.pdf], then says "저장해줘"
python3 documents/scripts/documents.py --user-id abc123 save \
--url "https://files.example.com/abc.pdf" \
--filename "계약서.pdf"
User: "바이브코딩에 대해 웹검색해서 문서로 만들어줘" → docx (기본값)
printf '%s' "# 바이브코딩 (Vibe Coding)\n\n## 개요\n바이브코딩은..." | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "바이브코딩 가이드" \
--format docx
User: "스타트업 사업계획서 PDF로 만들어줘" → pdf
printf '%s' "# 스타트업 사업계획서\n\n## 1. 회사 개요\n..." | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "스타트업 사업계획서" \
--format pdf
User: "분기별 매출 데이터 엑셀로 만들어줘" → xlsx
printf '%s' "분기|매출|전년비\nQ1|1억|+10%\nQ2|1.2억|+15%" | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "분기별 매출 현황" \
--format xlsx
User: "발표자료 만들어줘" → pptx
printf '%s' "# 2024 사업 전략\n\n## 핵심 목표\n- 매출 성장 20%\n- 신규 고객 100명" | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "2024 사업 전략 발표" \
--format pptx
User: "마크다운 파일로 정리해줘" → md
printf '%s' "# 정리 내용\n\n..." | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "정리 문서" \
--format md
User: "한글 문서로 만들어줘", "hwpx 파일로" → hwpx (LibreOffice 불필요)
printf '%s' "# 제목\n\n## 내용\n한글 문서 내용..." | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "한글 문서" \
--format hwpx
User: "hwp 파일로 만들어줘" → hwp (LibreOffice 필요, 없으면 hwpx 권장)
printf '%s' "# 제목\n\n## 내용\n..." | \
python3 documents/scripts/documents.py --user-id abc123 generate \
--title "한글 문서" \
--format hwp
