Feishu Knowledge Ingest

Use this skill to turn a Feishu folder or a single shared attachment into structured, reviewable knowledge outputs.

What this skill does

• Accept a Feishu folder link/token or a single shared attachment.
• Classify files into direct-read, download-and-parse, manual-review, or permission-blocked.
• Parse .docx and .pdf in v0.1.
• Produce report-first outputs instead of writing MEMORY.md directly.
• Preserve failures and uncertainty instead of guessing content.

Supported v0.1 scope

Inputs

• Feishu folder link or folder_token
• Single shared attachment link or token

Parsing

• .docx
• .pdf

Outputs

• ingest-report.md
• kb-items.jsonl
• failed-items.jsonl
• MEMORY.candidate.md

Required behavior

1. Distinguish Feishu native docs from uploaded attachments.
   • Native docs: doc, sheet, wiki, bitable
   • Uploaded attachments: .docx, .pdf, .pptx, other files
2. Do not claim attachment content was learned unless text was actually extracted.
3. Default to report-first. Do not write MEMORY.md in v0.1.
4. Record every failed file with a concrete reason.
5. Prefer plain-text summaries over complex Feishu cards when reporting progress.

File routing rules

Direct-read

Treat these as direct-read only when the runtime has a reliable native-reader path:

• doc
• sheet
• wiki
• bitable

Download-and-parse

Treat these as download-and-parse:

• .docx
• .pdf

Manual-review

Route here when the file is out of scope or low-confidence in v0.1:

• .pptx
• images
• scans with no extractable text
• archives
• unusual file types

Permission-blocked

Route here when listing is possible but the file cannot be downloaded or read.

Standard workflow

1. Resolve input type.
   • Folder link/token -> enumerate files.
   • Single file link/token -> build a one-file manifest.
2. Create a batch record.
   • Generate batch_id.
   • Record started_at.
3. Build a manifest.
   • File name
   • File token/link
   • file type
   • route decision
4. Attempt extraction.
   • .docx -> use parsers/parse_docx.py
   • .pdf -> use parsers/parse_pdf.py
5. Produce structured outputs.
   • success -> append to kb-items.jsonl
   • failure -> append to failed-items.jsonl
6. Summarize the batch.
   • Write ingest-report.md
   • Write MEMORY.candidate.md
7. Finish the batch.
   • Record finished_at
   • Never auto-write MEMORY.md

Output contracts

kb-items.jsonl

Write one JSON object per successfully extracted knowledge item with at least:

• batch_id
• source_file
• source_token
• file_type
• topic
• content_type
• summary
• extracted_at
• confidence

failed-items.jsonl

Write one JSON object per failed or blocked file with at least:

• batch_id
• source_file
• source_token
• file_type
• failure_reason
• error_detail
• suggested_action
• failed_at

MEMORY.candidate.md

Include:

• batch header (batch_id, started_at, finished_at, source_directory or source_file)
• grouped knowledge summaries
• source references
• confidence notes
• items needing review

ingest-report.md

Include:

1. Batch summary
2. Input scope
3. File counts and routing counts
4. Successful extraction summary
5. Failures and risks
6. Recommended next actions

Safety rules

• Never invent text that was not extracted.
• If parsing fails, say so plainly and log it.
• Treat filenames as hints only, never as proof of document contents.
• Keep sensitive data out of MEMORY.candidate.md unless the workflow explicitly allows it.

Included files

• run.py: minimal batch runner for local testing
• parsers/parse_docx.py: docx text extraction helper
• parsers/parse_pdf.py: pdf text extraction helper
• references/output_examples.md: sample output shapes and field guidance
• README.md: setup and usage notes