docs: 添加 Agent Skill 到项目仓库

- 复制 reader-digest-flow skill 到 skills/ 目录（含 SKILL.md + references/） - README 新增 Agent Skill 章节说明供 Agent 使用的工作流
2026-07-28 18:38:54 +08:00
parent 7b791ac947
commit 5eb390e3ed
16 changed files with 2112 additions and 0 deletions
@@ -0,0 +1,80 @@
+# IMA Upload API Reference
+
+Full API flow for uploading markdown articles to the IMA `daily` knowledge base. Used in Phase 7 of the reader-digest-flow.
+
+## Credentials
+
+```
+IMA_OPENAPI_CLIENTID  - from reader .env or user-provided
+IMA_OPENAPI_APIKEY    - from reader .env or user-provided
+IMA_DAILY_KNOWLEDGE_BASE_ID - daily KB UUID
+```
+
+The `ima-skill` v1.1.7+ ships with `ima_api.cjs` for credential loading.
+Legacy auth header: `ima-openapi-ctx: skill_version=1.1.7`.
+
+Do NOT export the full API key in shell commands — use `execute_code` with `subprocess.run` and Python string variables.
+
+## Flow (3 steps)
+
+### 1. create_media
+
+```
+POST https://ima.qq.com/openapi/wiki/v1/create_media
+Headers: ima-openapi-clientid, ima-openapi-apikey, Content-Type: application/json
+Body: { file_name, file_size, content_type, knowledge_base_id, file_ext }
+Returns: { code: 0, data: { media_id, cos_credential: { secret_id, secret_key, token, bucket_name, region, cos_key, start_time, expired_time } } }
+```
+
+`file_ext` is without the dot (e.g. `md` not `.md`).
+`file_name` must be the user-facing article title + `.md`.
+`content_type` for markdown is `text/markdown`; media_type=7.
+
+### 2. COS upload
+
+Use `cos-upload.cjs` from `ima-skill/knowledge-base/scripts/`:
+
+```
+node <skill_dir>/knowledge-base/scripts/cos-upload.cjs \
+  --file <local_md_file> \
+  --secret-id <from create_media> \
+  --secret-key <from create_media> \
+  --token <from create_media> \
+  --bucket <bucket_name> \
+  --region <region> \
+  --cos-key <cos_key> \
+  --content-type text/markdown \
+  --start-time <start_time> \
+  --expired-time <expired_time>
+```
+
+⚠️ Must use Python `subprocess.run(args=[...])` to avoid shell parameter mangling.
+⚠️ Always capture `returncode` and `stderr` — COS may return exit 0 on HTTP 500.
+
+### 3. add_knowledge
+
+```
+POST https://ima.qq.com/openapi/wiki/v1/add_knowledge
+Headers: same as create_media
+Body: { media_type: 7, media_id, title: "<file_name>", knowledge_base_id, file_info: { cos_key, file_size, file_name } }
+```
+
+`media_type=7` for markdown. `title` MUST equal `file_name`.
+
+## Article Markdown reformatting (before upload)
+
+Generated summaries from `reader` have `Source:` and `Category:` header lines.
+Before uploading, reformat to IMA style:
+
+```
+原文链接：<original article URL>
+
+## 核心结论
+...
+
+## 主要论点
+...
+```
+
+Remove `Source:`, `Category:` lines. Keep `原文链接:` at top with the URL on the next line.
+Break long prose (>200 chars per paragraph) into shorter paragraphs for IMA readability.