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,97 @@
+# IMA Markdown 文件上传流程（media_type=7）
+
+## 什么时候用此流程
+
+当用户说"沉淀到 IMA"时，必须用此文件上传流程，而不是 URL 导入或笔记导入。
+
+## 完整流程
+
+### 1. 写 .md 文件
+
+```bash
+mkdir -p /tmp/ima_upload
+cat > /tmp/ima_upload/文章标题.md << 'EOF'
+# 文章标题
+
+> 来源：XXX
+
+## 摘要
+
+...
+
+## 核心亮点
+
+- ...
+
+[原文链接](url)
+EOF
+```
+
+### 2. preflight 检查
+
+```python
+pf = subprocess.run(
+    ["node", f"{SKILL_DIR}/knowledge-base/scripts/preflight-check.cjs",
+     "--file", filepath],
+    capture_output=True, text=True
+)
+meta = json.loads(pf.stdout)
+# meta = {pass, file_name, file_ext, file_size, media_type, content_type}
+```
+
+### 3. create_media（获取 COS 凭证）
+
+```python
+r = ima_api("openapi/wiki/v1/create_media", {
+    "file_name": fname,
+    "file_size": meta["file_size"],
+    "content_type": meta["content_type"],
+    "knowledge_base_id": kb_id,
+    "file_ext": meta["file_ext"]
+})
+cos = r["data"]["cos_credential"]
+media_id = r["data"]["media_id"]
+```
+
+### 4. COS 上传
+
+```python
+cu = subprocess.run([
+    "node", f"{SKILL_DIR}/knowledge-base/scripts/cos-upload.cjs",
+    "--file", filepath,
+    "--secret-id", cos["secret_id"],
+    "--secret-key", cos["secret_key"],
+    "--token", cos["token"],
+    "--bucket", cos["bucket_name"],
+    "--region", cos["region"],
+    "--cos-key", cos["cos_key"],
+    "--content-type", meta["content_type"],
+    "--start-time", str(cos["start_time"]),
+    "--expired-time", str(cos["expired_time"]),
+    "--timeout", "300000"
+], capture_output=True, text=True, timeout=30)
+# 非0退出 = 上传失败
+```
+
+### 5. add_knowledge
+
+```python
+r = ima_api("openapi/wiki/v1/add_knowledge", {
+    "media_type": 7,
+    "media_id": media_id,
+    "title": title,  # 文章中文标题
+    "knowledge_base_id": kb_id,
+    "file_info": {
+        "cos_key": cos["cos_key"],
+        "file_size": meta["file_size"],
+        "file_name": fname
+    }
+})
+```
+
+## 注意事项
+
+- **COS 凭证不能通过 terminal() 读取**（Hermes redact_secrets 会把 token 替换成 `***`）。必须用 Python `subprocess.run()` 捕获原始 stdout。
+- **create_media 的 content_type 不能带 charset 参数**（如 `text/markdown; charset=utf-8` 会被拒）。用纯 MIME 类型 `text/markdown`。
+- **文件命名 = `<文章中文标题>.md`**。不要用英文 slug 或 temp name。
+- **media_type=7** 是 Markdown 文件。**绝对不要用 media_type=11**（笔记）或 `import_urls`。