{"id":"7fc214ab-407f-4338-b847-23e06945e27f","entityType":"agent","slug":"clawhub-cookfish1979-wiki-compiler","name":"知识库 Wiki 编译器","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cookfish1979-wiki-compiler","canonicalPath":"/agent/clawhub-cookfish1979-wiki-compiler","generatedAt":"2026-10-10T14:44:48.565Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":null},"description":"腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。 Skill: 知识库 Wiki 编译器 Owner: cookfish1979 Summary: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。 Tags: api-fix:5.0.2, cascade:5.0.2, compiler:5.0.2, folder-organization:4.1.0, ima:5.0.2, ingest:5.0.1, karpathy:5.0.2, knowledge:5.0.2, latest:5.0.2, lint:5.0.1, openclaw:4.1.0, ref","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s178t9xr86vm0kwcccj0rhw50h8472yc:wiki-compiler","sourceUrl":"https://clawhub.ai/cookfish1979/wiki-compiler","homepage":"https://clawhub.ai/cookfish1979/skills/wiki-compiler","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cookfish1979/wiki-compiler","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cookfish1979/skills/wiki-compiler","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":null},"stars":null,"forks":null,"downloads":1449,"packageName":null,"latestVersion":"5.0.2","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T11:55:50.613Z","lastCrawledAt":"2026-10-10T11:55:50.613Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T11:55:50.613Z","lastVerifiedAt":null,"highlights":[{"version":"5.0.2","createdAt":"2026-09-28T11:57:15.214Z","changelog":"v5.0.2 patch：Cascade 算法修正为 IMA 实际可实现版 【核心修正】 v5.0.0/v5.0.1 的 Cascade 算法假设可以修改 frontmatter，但 IMA 平台不允许。本次修正： 之前（不可行）： - 用 append_doc 修改导览的 frontmatter（version/changelog/updated） - 用 update_note 修改 frontmatter - 删除旧版本（API 不支持） 现在（实际可实现）： - 每次 Cascade = 创建新 note_id（import_doc） - 旧笔记保留为历史版本 - 用 append_doc 在旧笔记末尾追加'已被替代'标记 【算法变化】 - 相关性计算：纯 API Jaccard 算法（不再依赖 LLM 评分） - 用户确认：必选（不再自动执行，避免误更新） - 数量限制：最多 3 个导览/次 【IMA 限制明确化】 - frontmatter 是'创建时设定'，不可后续修改 - delete_note API 不支持 - 优势：版本历史天然保留，符合 Karpathy 'git 提交'哲学 详见 references/ingest.md 第 7 节完整可工作代码","fileCount":19,"zipByteSize":58029},{"version":"5.0.1","createdAt":"2026-09-28T11:42:42.429Z","changelog":"v5.0.1 patch：修正与 IMA 最新文档不一致问题 【修正错误端点（5 处）】 - 删除 get_media_info（IMA 不存在） - list_knowledge_bases → search_knowledge_base - list_notebooks → list_notebook（单数） - list_notes → list_note（单数） - create_notebook → add_notebook 【更新错误码（v4.x 全部过时）】 - 220001 文件名称不匹配 → 210001 PARAM_ERROR - 220004 → 210002 REQ_WITH_INVALID_UID - 220030 → 210005 NOTE_NOT_OWNER 或权限错误 - 404 → 210003 SERVICE_ERROR - 完整错误码表（21xxx 系列 + 20xxx apiKey）见 references/troubleshooting.md 【补充缺失端点（11 个）】 知识库：search_knowledge / search_knowledge_base_in_square / create_knowledge_base / update_knowledge_base_basic_info / rename_knowledge / set_knowledge_top / import_urls / add_knowledge / update_knowledge_base_permission / join_knowledge / update_knowledge_access_status 笔记：move_notes（复数）/ push_note / rename_note / rename_notebook / list_notebook（单数） 【修正说明】 - security.md：用 list_note（单数）替代 list_notes - troubleshooting.md：错误码章节按 ima-note api.md 重新对齐 - api-reference.md：完全重写为基于 IMA 真实端点列表（30+ 个端点） 【保留的不变】 - SKILL.md 的 Karpathy 三大操作架构不变 - ingest.md / lint.md / schema.md 三个新文档不变 - 11 个触发词不变（向后兼容）","fileCount":19,"zipByteSize":55298},{"version":"5.0.0","createdAt":"2026-09-28T09:15:58.103Z","changelog":"v5.0.0 Karpathy 三大操作重构（major 升级）：7 阶段 → Ingest/Lint/Schema 三大操作；SKILL.md 精简 499→306 行；新增 3 个 references（ingest.md/lint.md/schema.md）；引入 Cascade 级联算法（知识复利）；强制 frontmatter 契约（confidence/sources[]/related_guides[]/changelog[]）；触发词保持 11 个不变。","fileCount":19,"zipByteSize":52327},{"version":"4.1.0","createdAt":"2026-09-28T03:46:37.980Z","changelog":"v4.1.0 IMA 原生格式升级： 【frontmatter 升级（核心）】 - 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组 - 顶层 env: { ... } → 合并到 metadata.openclaw.requires.env - 新增 emoji: 🔧 / primaryEnv: IMA_OPENAPI_APIKEY / homepage - IMA 平台原生识别格式，加载时自动检查环境变量 【删除笔记 API 修正（重要）】 - 原 v4.0.0 附录 B 的 delete_note 安全删除流程已失效（IMA 平台当前 API 不支持） - 改为：客户端手动删除 + 推荐创建新笔记替代模式 - 更新 references/security.md（175 → 194 行）：新增删除能力演进追踪 - 更新 references/api-reference.md：标注 delete_note 已不支持 【向后兼容】 - 11 个触发词保持不变 - 7 阶段法操作流程不变 - v3.x 用户的升级无破坏性变化 【文档变化】 - SKILL.md: 492 → 499 行 - references/security.md: 175 → 194 行 - 总文件: 14 → 14（无新增）","fileCount":16,"zipByteSize":41093},{"version":"4.0.0","createdAt":"2026-07-08T09:39:42.997Z","changelog":"v4.0.0 完全重构（major 升级）： 【结构调整】 - 重新组织为 7 阶段法（诊断→收集→检查→链接→编译→写入→维护） - SKILL.md 精简至 492 行（原 1379 行），作为操作手册 - 详细内容拆分到 references/ 子目录 【references/ 子目录化】 新增 13 个文档： - folder-organization.md (212行) - 阶段 0 详细 - tagging.md (162行) - 标签体系 - security.md (175行) - 安全准则（统一） - api-reference.md (208行) - API 速查 - guide-template.md (129行) - 笔记撰写规范 - versioning.md (60行) - 版本控制 - incremental-update.md (82行) - 增量更新 - link-handling.md (130行) - 链接处理 - write-and-verify.md (135行) - 写入与验证 - maintenance.md (103行) - 维护 - troubleshooting.md (221行) - 故障排查 - cases/quantitative-investing.md (140行) - 实战案例 - reference.md (83行) - 索引页 【解决问题】 + 章节编号混乱 → 7 阶段清晰流程 + 4 处内容重复 → 统一到 references/ + 量化个案污染 → cases/ 单独目录 + 元信息缺失 → version/license/author/last_updated + 无快速开始 → 新增 5 个场景 + 无故障排查 → troubleshooting.md (221 行) + 无变更日志 → SKILL.md 末尾 + 文档结构图 【v3 → v4 主要差异】 - SKILL.md: 1379 → 492 行（-64%） - 总文件: 2 → 14 个 - 关键警告: 重复 4 次 → 统一到 security.md - 章节数: 13 → 7 阶段 向后兼容：v3.x 用户升级无破坏性变化，11 个触发词保持不变。","fileCount":16,"zipByteSize":40550},{"version":"3.0.2","createdAt":"2026-07-08T07:39:35.315Z","changelog":"v3.0.2 description 优化： 【优化 description 与实际能力的匹配】 调整前的问题： - description 仅提到标签体系管理，未提到按文件夹层级结构归类（v3.0.0 新增核心能力） - 缺少新能力对应的触发词 本次调整： + 第一句补充按文件夹层级结构归类能力描述 + 新增 2 个触发词： + 按文件夹归类 + 整理散落文件 现有 11 个触发词覆盖： - 编译类：建知识库、编译知识库、搭建wiki、知识体系化 - 整理类：整理资料库、把资料整理成wiki - 标签类：给知识库打标签、按标签分类、标签整理 - 归类类（新增）：按文件夹归类、整理散落文件 description 总字符数: 174 → 198（+14.4%） 完全保留 v3.0.1 的能力（1379 行 SKILL.md）和安全机制，仅调整触发匹配的精确度。","fileCount":5,"zipByteSize":23935},{"version":"3.0.1","createdAt":"2026-07-06T12:04:31.150Z","changelog":"v3.0.1 安全修复版本：修复附录B 笔记删除指令的误删风险。新增备份机制、三重确认门、删除前预览、操作日志记录，推荐保留旧版+创建新版的替代方案。SKILL.md 1279 → 1379 行。","fileCount":5,"zipByteSize":23864},{"version":"3.0.0","createdAt":"2026-07-01T00:17:48.905Z","changelog":"v3.0.0 重大更新： ★ 新增「3.0 知识库结构诊断」章节 - 诊断流程（4 个步骤） - 关键警告：add_knowledge ≠ move_knowledge - 诊断输出模板 ★ 新增「6.5 多层文件夹归类」章节 - 推荐目标文件夹关键词映射 - move_knowledge 批量操作（每批≤10） - 标签备份与恢复模式 - 多层结构设计原则 ★ 附录 C 补充 move_knowledge 接口模板 ★ 附录 D 追加实战经验 8-12（核心经验沉淀） ★ reference.md 新增「IMA 知识库文件夹机制」章节 文档规模：SKILL.md 1000→1279 行，reference.md 138→219 行 基于量化投资知识库（135 文件 / 7 文件夹 / 3 子文件夹 / 244 标签）的完整实战验证。","fileCount":5,"zipByteSize":22699}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s178t9xr86vm0kwcccj0rhw50h8472yc:wiki-compiler","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T14:44:48.562Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cookfish1979-wiki-compiler/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":null},"readme":"Skill: 知识库 Wiki 编译器\n\nOwner: cookfish1979\n\nSummary: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。\n\nTags: api-fix:5.0.2, cascade:5.0.2, compiler:5.0.2, folder-organization:4.1.0, ima:5.0.2, ingest:5.0.1, karpathy:5.0.2, knowledge:5.0.2, latest:5.0.2, lint:5.0.1, openclaw:4.1.0, refactor:4.1.0, safety:4.1.0, schema:5.0.1, tagging:4.1.0, wiki:5.0.2\n\nVersion history:\n\nv5.0.2 | 2026-09-28T11:57:15.214Z | user\n\nv5.0.2 patch：Cascade 算法修正为 IMA 实际可实现版\n\n【核心修正】\nv5.0.0/v5.0.1 的 Cascade 算法假设可以修改 frontmatter，但 IMA 平台不允许。本次修正：\n\n之前（不可行）：\n- 用 append_doc 修改导览的 frontmatter（version/changelog/updated）\n- 用 update_note 修改 frontmatter\n- 删除旧版本（API 不支持）\n\n现在（实际可实现）：\n- 每次 Cascade = 创建新 note_id（import_doc）\n- 旧笔记保留为历史版本\n- 用 append_doc 在旧笔记末尾追加'已被替代'标记\n\n【算法变化】\n- 相关性计算：纯 API Jaccard 算法（不再依赖 LLM 评分）\n- 用户确认：必选（不再自动执行，避免误更新）\n- 数量限制：最多 3 个导览/次\n\n【IMA 限制明确化】\n- frontmatter 是'创建时设定'，不可后续修改\n- delete_note API 不支持\n- 优势：版本历史天然保留，符合 Karpathy 'git 提交'哲学\n\n详见 references/ingest.md 第 7 节完整可工作代码\n\nv5.0.1 | 2026-09-28T11:42:42.429Z | user\n\nv5.0.1 patch：修正与 IMA 最新文档不一致问题\n\n【修正错误端点（5 处）】\n- 删除 get_media_info（IMA 不存在）\n- list_knowledge_bases → search_knowledge_base\n- list_notebooks → list_notebook（单数）\n- list_notes → list_note（单数）\n- create_notebook → add_notebook\n\n【更新错误码（v4.x 全部过时）】\n- 220001 文件名称不匹配 → 210001 PARAM_ERROR\n- 220004 → 210002 REQ_WITH_INVALID_UID\n- 220030 → 210005 NOTE_NOT_OWNER 或权限错误\n- 404 → 210003 SERVICE_ERROR\n- 完整错误码表（21xxx 系列 + 20xxx apiKey）见 references/troubleshooting.md\n\n【补充缺失端点（11 个）】\n知识库：search_knowledge / search_knowledge_base_in_square / create_knowledge_base / update_knowledge_base_basic_info / rename_knowledge / set_knowledge_top / import_urls / add_knowledge / update_knowledge_base_permission / join_knowledge / update_knowledge_access_status\n笔记：move_notes（复数）/ push_note / rename_note / rename_notebook / list_notebook（单数）\n\n【修正说明】\n- security.md：用 list_note（单数）替代 list_notes\n- troubleshooting.md：错误码章节按 ima-note api.md 重新对齐\n- api-reference.md：完全重写为基于 IMA 真实端点列表（30+ 个端点）\n\n【保留的不变】\n- SKILL.md 的 Karpathy 三大操作架构不变\n- ingest.md / lint.md / schema.md 三个新文档不变\n- 11 个触发词不变（向后兼容）\n\nv5.0.0 | 2026-09-28T09:15:58.103Z | user\n\nv5.0.0 Karpathy 三大操作重构（major 升级）：7 阶段 → Ingest/Lint/Schema 三大操作；SKILL.md 精简 499→306 行；新增 3 个 references（ingest.md/lint.md/schema.md）；引入 Cascade 级联算法（知识复利）；强制 frontmatter 契约（confidence/sources[]/related_guides[]/changelog[]）；触发词保持 11 个不变。\n\nv4.1.0 | 2026-09-28T03:46:37.980Z | user\n\nv4.1.0 IMA 原生格式升级：\n\n【frontmatter 升级（核心）】\n- 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组\n- 顶层 env: { ... } → 合并到 metadata.openclaw.requires.env\n- 新增 emoji: 🔧 / primaryEnv: IMA_OPENAPI_APIKEY / homepage\n- IMA 平台原生识别格式，加载时自动检查环境变量\n\n【删除笔记 API 修正（重要）】\n- 原 v4.0.0 附录 B 的 delete_note 安全删除流程已失效（IMA 平台当前 API 不支持）\n- 改为：客户端手动删除 + 推荐创建新笔记替代模式\n- 更新 references/security.md（175 → 194 行）：新增删除能力演进追踪\n- 更新 references/api-reference.md：标注 delete_note 已不支持\n\n【向后兼容】\n- 11 个触发词保持不变\n- 7 阶段法操作流程不变\n- v3.x 用户的升级无破坏性变化\n\n【文档变化】\n- SKILL.md: 492 → 499 行\n- references/security.md: 175 → 194 行\n- 总文件: 14 → 14（无新增）\n\nv4.0.0 | 2026-07-08T09:39:42.997Z | user\n\nv4.0.0 完全重构（major 升级）：\n\n【结构调整】\n- 重新组织为 7 阶段法（诊断→收集→检查→链接→编译→写入→维护）\n- SKILL.md 精简至 492 行（原 1379 行），作为操作手册\n- 详细内容拆分到 references/ 子目录\n\n【references/ 子目录化】\n新增 13 个文档：\n- folder-organization.md (212行) - 阶段 0 详细\n- tagging.md (162行) - 标签体系\n- security.md (175行) - 安全准则（统一）\n- api-reference.md (208行) - API 速查\n- guide-template.md (129行) - 笔记撰写规范\n- versioning.md (60行) - 版本控制\n- incremental-update.md (82行) - 增量更新\n- link-handling.md (130行) - 链接处理\n- write-and-verify.md (135行) - 写入与验证\n- maintenance.md (103行) - 维护\n- troubleshooting.md (221行) - 故障排查\n- cases/quantitative-investing.md (140行) - 实战案例\n- reference.md (83行) - 索引页\n\n【解决问题】\n+ 章节编号混乱 → 7 阶段清晰流程\n+ 4 处内容重复 → 统一到 references/\n+ 量化个案污染 → cases/ 单独目录\n+ 元信息缺失 → version/license/author/last_updated\n+ 无快速开始 → 新增 5 个场景\n+ 无故障排查 → troubleshooting.md (221 行)\n+ 无变更日志 → SKILL.md 末尾 + 文档结构图\n\n【v3 → v4 主要差异】\n- SKILL.md: 1379 → 492 行（-64%）\n- 总文件: 2 → 14 个\n- 关键警告: 重复 4 次 → 统一到 security.md\n- 章节数: 13 → 7 阶段\n\n向后兼容：v3.x 用户升级无破坏性变化，11 个触发词保持不变。\n\nv3.0.2 | 2026-07-08T07:39:35.315Z | user\n\nv3.0.2 description 优化：\n\n【优化 description 与实际能力的匹配】\n调整前的问题：\n- description 仅提到标签体系管理，未提到按文件夹层级结构归类（v3.0.0 新增核心能力）\n- 缺少新能力对应的触发词\n\n本次调整：\n+ 第一句补充按文件夹层级结构归类能力描述\n+ 新增 2 个触发词：\n + 按文件夹归类\n + 整理散落文件\n\n现有 11 个触发词覆盖：\n- 编译类：建知识库、编译知识库、搭建wiki、知识体系化\n- 整理类：整理资料库、把资料整理成wiki\n- 标签类：给知识库打标签、按标签分类、标签整理\n- 归类类（新增）：按文件夹归类、整理散落文件\n\ndescription 总字符数: 174 → 198（+14.4%）\n\n完全保留 v3.0.1 的能力（1379 行 SKILL.md）和安全机制，仅调整触发匹配的精确度。\n\nv3.0.1 | 2026-07-06T12:04:31.150Z | user\n\nv3.0.1 安全修复版本：修复附录B 笔记删除指令的误删风险。新增备份机制、三重确认门、删除前预览、操作日志记录，推荐保留旧版+创建新版的替代方案。SKILL.md 1279 → 1379 行。\n\nv3.0.0 | 2026-07-01T00:17:48.905Z | user\n\nv3.0.0 重大更新：\n\n★ 新增「3.0 知识库结构诊断」章节\n- 诊断流程（4 个步骤）\n- 关键警告：add_knowledge ≠ move_knowledge\n- 诊断输出模板\n\n★ 新增「6.5 多层文件夹归类」章节\n- 推荐目标文件夹关键词映射\n- move_knowledge 批量操作（每批≤10）\n- 标签备份与恢复模式\n- 多层结构设计原则\n\n★ 附录 C 补充 move_knowledge 接口模板\n★ 附录 D 追加实战经验 8-12（核心经验沉淀）\n★ reference.md 新增「IMA 知识库文件夹机制」章节\n\n文档规模：SKILL.md 1000→1279 行，reference.md 138→219 行\n\n基于量化投资知识库（135 文件 / 7 文件夹 / 3 子文件夹 / 244 标签）的完整实战验证。\n\nv2.0.2 | 2026-05-15T16:14:55.962Z | auto\n\n- 文档说明添加了“腾讯 IMA”品牌定位，强调技能的适用场景为腾讯 IMA 知识库。\n- 明确技能用于腾讯 IMA 平台相关“Wiki 编译”“整理资料库”等系统化组织任务。\n- 其余说明内容和流程未改动，维持原有编译方法、结构规划和维护规范。\n\nv2.0.1 | 2026-05-15T16:12:24.986Z | auto\n\nwiki-compiler v2.0.1\n\n- 全面重写和简化了流程说明，聚焦为三大步骤（需求收集、结构编译、主动维护）。\n- 大量压缩/移除实现细节（如 OpenAPI 调用示例、增量更新算法、版本号管理、复杂表格编译规范）。\n- 明确强调仅用编号列表导览，规避 Markdown 表格的解析问题，并处理标题特殊字符。\n- 清晰说明如何获取知识库文件的真实可链接 URL 并嵌入导览笔记。\n- 增加知识库健康检查、增量补充、产出回流等主动维护场景的操作规范。\n- 移除环境变量与技能依赖规范，将技能文档合并为更精炼通用说明。\n\nv2.0.0 | 2026-05-13T07:47:12.544Z | user\n\n错误修复版本：修正API参数名(count→limit)、响应字段(list→knowledge_list)、添加分页逻辑、修正笔记写入流程(import_doc+add_knowledge)、统一步骤编号\n\nArchive index:\n\nArchive v5.0.2: 19 files, 58029 bytes\n\nFiles: references/api-reference.md (15955b), references/cases/quantitative-investing.md (5448b), references/folder-organization.md (7169b), references/guide-template.md (5737b), references/incremental-update.md (3046b), references/ingest.md (19909b), references/link-handling.md (5230b), references/lint.md (8436b), references/maintenance.md (2784b), references/reference.md (5668b), references/schema.md (7314b), references/security.md (7279b), references/tagging.md (5136b), references/troubleshooting.md (6727b), references/versioning.md (2096b), references/write-and-verify.md (4794b), skill-card.md (2122b), SKILL.md (12848b), _meta.json (132b)\n\nFile v5.0.2:SKILL.md\n\n---\nname: wiki-compiler\nversion: 5.0.0\ndescription: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。\nlicense: MIT-0\nauthor: cookfish\nlast_updated: 2026-09-28\nhomepage: https://github.com/cookfish/wiki-compiler\n\nmetadata:\n openclaw:\n emoji: 🔧\n requires:\n primaryEnv: IMA_OPENAPI_APIKEY\n env:\n - IMA_OPENAPI_CLIENTID\n - IMA_OPENAPI_APIKEY\n---\n\n# 知识库 Wiki 编译器 v5.0.0\n\n> **技能版本**：v5.0.0 | 最后更新：2026-09-28 | 上一版：v4.1.0\n> **核心理念**：基于 Karpathy 的 LLM Wiki 模式 —— **\"Human curates, LLM maintains\"**\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n> **IMA 平台依赖**：需配置 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。获取方式：访问 https://ima.qq.com/agent-interface\n\n---\n\n## 快速开始\n\n### 场景 1：建新知识库\n用户：\"建一个关于 XXX 的知识库\" → **Ingest**（完整流水线）\n\n### 场景 2：导入新资料\n用户：\"导入这个网页\" / \"上传这个 PDF\" → **Ingest**（自动级联）\n\n### 场景 3：整理散落文件\n用户：\"按文件夹归类\" / \"整理散落文件\" → **Ingest 前置**（Folder Pre-Ingest）\n\n### 场景 4：维护知识库\n用户：\"检查知识库\" / \"健康检查\" → **Lint**（4 类标准检查）\n\n### 场景 5：增量更新导览\n用户：\"更新导览\" / \"导览新增了 N 篇文章\" → **Ingest**（增量模式）\n\n### 场景 6：标签管理\n用户：\"给知识库打标签\" / \"审查标签\" → **Ingest** 子任务（Schema 辅助）\n\n---\n\n## 核心理念\n\n### Karpathy 三大操作\n\n| 操作 | 职责 | 触发词 | 详见 |\n|------|------|--------|------|\n| **Ingest**（摄取） | 资料入库，编译/更新导览，级联多个相关导览 | \"建知识库\"\"导入网页\"\"上传文件\"\"更新导览\" | [ingest.md](references/ingest.md) |\n| **Lint**（健康检查） | 4 类标准检查：结构/矛盾/孤立/过期 | \"检查知识库\"\"健康检查\" | [lint.md](references/lint.md) |\n| **Schema**（契约） | 强制 frontmatter 规范（自动应用） | （无需用户触发）| [schema.md](references/schema.md) |\n\n**Query（查询）由 IMA search/fetch 完成，不归本 skill 管。**\n\n### 为什么这样设计\n\n- **Ingest**：知识库是\"会复利的资产\"，不是\"可检索的语料库\"\n- **Lint**：通过定期检查防止 wiki 衰败（类比代码世界的 `eslint`）\n- **Schema**：没有 schema，LLM 会天马行空；有了 schema，LLM 才守纪律\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n\n---\n\n## Ingest（摄取）\n\n### 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n### 关键子任务\n\n| 子任务 | 核心动作 | API |\n|--------|---------|-----|\n| **Collect** | 上传文件 / 导入网页 / 拉取已有 | `upload_file`, `import_urls`, `get_knowledge_list` |\n| **Check** | 搜索旧导览 | `search_note`（标题=\"主题导览\"）|\n| **Link** | 获取链接特性表 | `export_media_for_ima_sandbox` |\n| **Compile** | 新建/增量更新 | LLM 5 步法或 6 步法 |\n| **Write** | 创建/追加/编辑笔记 | `import_doc`, `append_doc`, `update_note` |\n| **Cascade** | **创建新版本导览 + 旧版保留历史**（知识复利）| `search_note` + Jaccard 算法 |\n\n详见 [references/ingest.md](references/ingest.md)\n\n### ⚠️ Karpathy 核心机制：知识复利（Cascade）\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）\n\n**IMA 实际可实现方式**：每个 Cascade 创建新 note_id（frontmatter 完整可控），旧版笔记保留作为历史。\n\n```\n新文件被上传\n ↓\n计算与每个现有导览的相关性（标签 Jaccard + 文件夹归属 + 标题关键词）\n ↓\n相关度 > 0.5 的导览 → 加入\"待更新列表\"\n ↓\n用户确认（必选）\n ↓\n对每个候选导览：\n 1. export_note 读旧版\n 2. LLM 生成新版本正文\n 3. import_doc 创建新笔记（新 frontmatter：version/updated/changelog）\n 4. append_doc 在旧笔记末尾追加\"已被替代\"标记\n```\n\n**示例**：上传\"遗传算法在量化交易中的应用\" → 1 个新导览笔记创建（v1.6）+ 1 个旧版标记追加。\n\n详见 [references/ingest.md 第 7 节](references/ingest.md)\n\n---\n\n## Lint（健康检查）\n\n### 4 类标准检查（Karpathy 完整版）\n\n| 检查 | 触发频率 | 检查内容 |\n|------|---------|---------|\n| **结构** | 每周 | 散落文件、空文件夹、文件错放 |\n| **矛盾** | 每月 | 不同导览对同一概念说法冲突 |\n| **孤立** | 每月 | 导览未被任何文件引用 |\n| **过期** | 每月 | 低 confidence + 长期未更新 |\n\n详见 [references/lint.md](references/lint.md)\n\n### 触发词\n\n- \"检查知识库\" / \"知识库体检\" / \"健康检查\"\n- \"审查标签\" / \"整理标签\"（仅标签部分）\n\n### 输出\n\n`outputs/lint-YYYY-MM-DD.md` —— 包含总体评分、4 类检查详情、修复建议。\n\n---\n\n## Schema（契约）\n\n### 强制 frontmatter（每篇主题导览）\n\n```yaml\n---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本\nsources:\n - [《文章1》](URL)\nrelated_guides:\n - [《另一导览》](URL)\n---\n```\n\n详见 [references/schema.md](references/schema.md)\n\n### 核心字段说明\n\n| 字段 | Karpathy 对应 | 作用 |\n|------|-------------|------|\n| `confidence` | LLM 把握度 | 让用户知道哪些导览可信 |\n| `sources[]` | 资料溯源 | 每个论断追到 raw（防止幻觉）|\n| `related_guides[]` | `[[wikilinks]]` | 网状结构而非树状 |\n| `changelog[]` | `git log` | 审计追踪 |\n| `version` | 语义化版本 | 变更管理 |\n\n---\n\n## 安全准则（破坏性操作）\n\n| 操作 | 风险 | 保护 |\n|------|------|------|\n| ~~`delete_note`~~ | ❌ API 不支持 | 客户端手动 |\n| `tag_delete` | 关联自动解除 | 列影响文件→用户确认 |\n| `tag_rename` | 重名自动合并 | 检查新名→用户确认 |\n| `move_knowledge` | 标签可能清空 | 备份标签→移动后恢复 |\n\n详见 [references/security.md](references/security.md)\n\n---\n\n## API 速查\n\n### 核心端点\n\n| 功能 | 端点 |\n|------|------|\n| 上传文件 | `openapi/wiki/v1/upload_file` |\n| 导入网页 | `openapi/wiki/v1/import_urls` |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` |\n| 重命名 | `openapi/wiki/v1/rename_knowledge` |\n| 添加标签 | `openapi/wiki/v1/tag_add` |\n| 列出知识库 | `openapi/wiki/v1/get_knowledge_list` |\n| 获取媒体信息 | `openapi/wiki/v1/get_media_info` |\n| 创建笔记 | `openapi/note/v1/import_doc` |\n| 追加笔记 | `openapi/note/v1/append_doc` |\n| 导出笔记 | `openapi/note/v1/export_note` |\n| 搜索笔记 | `openapi/note/v1/search_note` |\n| 按 block 编辑 | `openapi/note/v1/update_note` |\n| ~~删除笔记~~ | ❌ API 不支持 |\n\n详见 [references/api-reference.md](references/api-reference.md) 和 [references/troubleshooting.md](references/troubleshooting.md)\n\n---\n\n## 编译质量标准\n\n1. **原子化**：每个知识节点围绕单一主题\n2. **关联性**：知识卡片之间通过超链接形成网状结构\n3. **大纲化**：每个卡片内部有完整的章节结构\n4. **可溯源**：每篇文章有来源出处（sources[]）\n5. **可读性**：结构清晰、信息密度适中\n6. **confidence 标注**：每个论断有可信度（Karpathy 特色）\n\n---\n\n## 重要提醒\n\n- **预获取链接是编译前的必做步骤**（Link 子任务）—— 先建立链接特性表，再基于表编译\n- **增量优先**——每次 Ingest 前必须 Check 旧版本，优先增量更新而非重新创建\n- **schema 强制**——所有导览必须遵守 [references/schema.md](references/schema.md)\n- **级联需确认**——Cascade 是 Karpathy 核心机制，但首次使用应告知用户\n- **导出笔记是 COS URL**——`export_note` 返回 `content_url`（3 小时时效），需二次下载\n- **删除笔记不支持**——IMA 平台当前 API 不支持，请用户在客户端操作\n\n---\n\n## 变更日志\n\n### v5.0.2 (2026-09-28) - Cascade 算法修正\n\n- **Cascade 算法改为 IMA 实际可实现版**：每次级联 = 创建新 note_id + 旧笔记追加\"已被替代\"标记\n- 移除 LLM 评分依赖（改为纯 API Jaccard 算法）\n- 强调\"frontmatter 不可修改\"的 IMA 限制\n- Cascade 用户确认变成必选（不再自动执行）\n\n详见 [references/ingest.md 第 7 节](references/ingest.md)\n\n### v5.0.1 (2026-09-28) - API 端点对齐 patch\n\n- 修正 5 处错误端点（get_media_info 删除、list_knowledge_bases → search_knowledge_base、list_notebooks → list_notebook、list_notes → list_note、create_notebook → add_notebook）\n- 补充 14 个缺失端点\n- 更新错误码（220001 → 210001 等）\n\n### v5.0.0 (2026-09-28) - Karpathy 重构（major 升级）\n\n**架构重组**：\n- 7 阶段 → Karpathy **三大操作**（Ingest / Lint / Schema）\n- SKILL.md 精简到 ~450 行（v4.1.0 是 499 行）\n- 新增 3 个核心 references：ingest.md / lint.md / schema.md\n- 引入 Karpathy 核心机制：**知识复利（Cascade 级联更新）**\n\n**Schema 强制化**：\n- 主题导览 frontmatter 强化：必填 confidence / sources[] / related_guides[] / changelog\n- confidence 字段：每篇导览标注可信度（high/medium/low）\n- sources[] 强制：每个论断追到 raw 资料\n\n**Ingest 增强**：\n- Cascade 算法改为 IMA 实际可实现版：每次级联创建新 note_id + 旧笔记追加\"已被替代\"标记\n- 移除 LLM 评分依赖（改为纯 API Jaccard 算法）\n- 新增 update_note（按 block 编辑）\n\n**Lint 强化**：\n- 从\"基础健康检查\"升级到 Karpathy 标准的 4 类检查（结构/矛盾/孤立/过期）\n- Lint 报告输出到 `outputs/lint-YYYY-MM-DD.md`\n\n**触发词保持 11 个不变**\n\n**复杂度反思**：\n- 之前 v4.2.0 加 14 项功能会让 SKILL.md 增长到 700+ 行\n- v5.0.0 重组为三大操作，结构更清晰\n- 11 个触发词保持不变，description 不变（向后兼容）\n\n### v4.1.0 (2026-09-28) - IMA 原生格式升级\n\n- 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组\n- 删除笔记 API 修正：v4.0.0 附录 B 的 `delete_note` 安全删除流程已失效\n\n### v4.0.0 (2026-07-08) - 完全重构\n\n- 7 阶段法操作流程\n\n### v3.0.2 (2026-07-08) - 描述优化\n### v3.0.1 (2026-07-08) - 安全修复\n### v3.0.0 (2026-05-13) - 多层结构\n### v1.0 (2026-05-07) - 初版\n\n---\n\n## 文档结构\n\n```\nwiki-compiler/\n├── SKILL.md ← 本文件（操作手册）\n└── references/\n ├── reference.md ← references/ 索引\n ├── ingest.md ← 🆕 Ingest 完整操作 + 级联算法\n ├── lint.md ← 🆕 Lint 4 类标准检查\n ├── schema.md ← 🆕 强制 frontmatter 契约\n ├── folder-organization.md ← Ingest 前置：文件夹整理\n ├── tagging.md ← Ingest 子任务：标签管理\n ├── security.md ← 破坏性操作保护\n ├── api-reference.md ← API 速查\n ├── guide-template.md ← 笔记撰写规范（含新 frontmatter）\n ├── versioning.md ← 版本控制\n ├── write-and-verify.md ← 写入与验证\n ├── link-handling.md ← 链接处理\n ├── troubleshooting.md ← 故障排查\n └── cases/\n └── quantitative-investing.md ← 实战案例\n```\n\n> ⚠️ **IMA 平台注意**：IMA 平台会周期性向 `/sandbox/workspace/skills//` 添加软链接 ` -> /root/.skills//`，可能导致打包时混入旧版本。打包前务必用 `find ... -type l` 检查并清理。\n> 详见 [references/troubleshooting.md](references/troubleshooting.md) 第 10 节。\n\nFile v5.0.2:_meta.json\n\n{\n \"ownerId\": \"kn7b60cvvedv8jkxs5gy3m9c0d837e9f\",\n \"slug\": \"wiki-compiler\",\n \"version\": \"5.0.2\",\n \"publishedAt\": 1790596635214\n}\n\nFile v5.0.2:references/api-reference.md\n\n# API 速查\n\n> IMA OpenAPI 完整参考（基于 ima-knowledge 和 ima-note 最新文档对齐）。\n> 所有调用都依赖 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。\n\n## 1. 环境变量配置\n\n```bash\n# 必需的环境变量\nexport IMA_OPENAPI_CLIENTID=\"你的ClientID\"\nexport IMA_OPENAPI_APIKEY=\"你的APIKey\"\n\n# 获取地址：https://ima.qq.com/agent-interface\n```\n\n## 2. 通用调用函数（Python）\n\n```python\nimport urllib.request\nimport json\n\ndef ima_api(path, data=None):\n \"\"\"IMA OpenAPI 通用调用函数\"\"\"\n headers = {\n \"ima-openapi-clientid\": \"你的ClientID\",\n \"ima-openapi-apikey\": \"你的APIKey\",\n \"Content-Type\": \"application/json\"\n }\n url = f\"https://ima.qq.com/{path}\"\n req = urllib.request.Request(\n url,\n data=json.dumps(data or {}).encode('utf-8'),\n headers=headers,\n method=\"POST\"\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n return json.loads(resp.read().decode(\"utf-8\"))\n```\n\n## 3. 知识库 API（wiki/v1/*）\n\n### 3.1 读取类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 搜索知识库（含角色信息） | `openapi/wiki/v1/search_knowledge_base` | `query`, `cursor`, `limit` (1-20) | **推荐** 替代不存在的 `list_knowledge_bases` |\n| 列出知识库内容 | `openapi/wiki/v1/get_knowledge_list` | `knowledge_base_id`, `cursor`, `limit` (1-50) | 不带 folder_id 列出根目录 |\n| 按名称定位文件/文件夹 | `openapi/wiki/v1/search_knowledge` | `query`, `knowledge_base_id` | 获取位置和类型信息 |\n| 发现广场公开知识库 | `openapi/wiki/v1/search_knowledge_base_in_square` | `question`, `cursor`, `limit` (1-20) | 与 search_knowledge_base 不同 |\n| 导出媒体内容（COS URL）| `openapi/wiki/v1/export_media_for_ima_sandbox` | `media_id` | **返回 COS 链接需二次下载** |\n\n### 3.2 写入类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 创建知识库 | `openapi/wiki/v1/create_knowledge_base` | `name`, `type` (1001个人/1002共享/1004订阅) | - |\n| 更新知识库信息 | `openapi/wiki/v1/update_knowledge_base_basic_info` | `id`, `update_fields` | 可选更新字段：1-名称, 2-封面, 3-简介, 4-推荐问题 |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` | `knowledge_base_id`, `name`, `parent_folder_id` | - |\n| 重命名文件/文件夹 | `openapi/wiki/v1/rename_knowledge` | `media_id`, `new_name` | - |\n| 置顶/取消置顶 | `openapi/wiki/v1/set_knowledge_top` | `media_id`, `is_top` | - |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` | `src_kb_id`, `dst_kb_id`, `dst_folder_id`, `infos` | **每次最多 10 个文件** |\n| 导入网页链接 | `openapi/wiki/v1/import_urls` | `knowledge_base_id`, `urls[]` | 批量导入 URL |\n| 上传文件 | `openapi/wiki/v1/upload_file` | `knowledge_base_id`, `file` | 走 COS 上传流程 |\n| 把已有笔记加入知识库 | `openapi/wiki/v1/add_knowledge` | `knowledge_base_id`, `media_id` | 虚拟关联（不改 parent_folder_id） |\n\n### 3.3 权限管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 改知识库权限 | `openapi/wiki/v1/update_knowledge_base_permission` | `knowledge_base_id`, `permission` |\n| 加入知识库 | `openapi/wiki/v1/join_knowledge` | `knowledge_base_id` |\n| 改文件访问状态 | `openapi/wiki/v1/update_knowledge_access_status` | `media_id`, `access_status` |\n\n### 3.4 标签管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 给文件打标签 | `openapi/wiki/v1/tag_add` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| 从文件移除标签 | `openapi/wiki/v1/tag_remove` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| 列出标签 | `openapi/wiki/v1/tag_list` | `kb_id`, `cursor`, `limit` (1-100) |\n| 删除标签 | `openapi/wiki/v1/tag_delete` | `kb_id`, `tag_name` |\n| 重命名标签 | `openapi/wiki/v1/tag_rename` | `kb_id`, `old_tag_name`, `new_tag_name` |\n\n## 4. 笔记 API（note/v1/*）\n\n### 4.1 读取类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 搜索笔记 | `openapi/note/v1/search_note` | `search_type` (0=标题/1=正文), `query_info`, `start`, `end` | start-end 差值 ≤ 20 |\n| 列出笔记 | `openapi/note/v1/list_note` | `folder_id`, `sort_type`, `cursor`, `limit` (≤20) | **注意是单数 list_note，不是 list_notes** |\n| 列出笔记本 | `openapi/note/v1/list_notebook` | `cursor`, `limit` | **单数 list_notebook** |\n| 导出笔记 | `openapi/note/v1/export_note` | `note_id`, `target_content_format` (0/1/2) | **返回 COS URL 需二次下载** |\n| 导出笔记 block 结构 | `openapi/note/v1/export_note_blocks` | `note_id` | update_note 的前置步骤 |\n\n### 4.2 写入类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 创建笔记 | `openapi/note/v1/import_doc` | `content_format` (固定 1), `content`, `title`, `folder_id` | 第一行文本会被自动提取为标题 |\n| 追加内容到笔记 | `openapi/note/v1/append_doc` | `note_id`, `content_format`, `content` | 适合短内容直接追加 |\n| 按 block 编辑笔记 | `openapi/note/v1/update_note` | `note_id`, `block_id`, `content` | 需先 export_note_blocks 定位 |\n| 创建笔记本 | `openapi/note/v1/add_notebook` | `name` | **注意是 add_notebook，不是 create_notebook** |\n| 重命名笔记本 | `openapi/note/v1/rename_notebook` | `folder_id`, `new_name` | - |\n| 重命名笔记 | `openapi/note/v1/rename_note` | `note_id`, `new_title` | - |\n| 移动笔记 | `openapi/note/v1/move_notes` | `note_ids[]`, `dst_folder_id` | **复数 move_notes** |\n| push 笔记 | `openapi/note/v1/push_note` | `note_id`, `content_cos_key` | 长内容走 COS 上传路径 |\n| ~~删除笔记~~ | ~~`openapi/note/v1/delete_note`~~ | ❌ **API 已不支持（2026-09）** | 需用户在 IMA 客户端手动删除 |\n\n## 5. 错误代码参考（基于 ima-note api.md）\n\n| code | 名称 | 说明 | 解决方案 |\n|------|------|------|---------|\n| 0 | OK | 成功 | - |\n| 210001 | PARAM_ERROR | 参数错误 | 检查参数值 |\n| 210002 | REQ_WITH_INVALID_UID | 携带无效的 UID | 检查 UID 有效性 |\n| 210003 | SERVICE_ERROR | 服务器内部错误 | 告知用户稍后再试，**无需重试** |\n| 210004 | SPACE_NOT_ENOUGH | 用户空间不够 | 清理空间或升级 |\n| 210005 | NOTE_NOT_OWNER | 不是笔记的作者 | 仅作者可操作 |\n| 210006 | NOTE_IS_DELETE | 笔记已被删除 | 检查 note_id |\n| 210007 | COS_CRED_ERROR | COS 上传凭证出错 | 重试或联系 IMA |\n| 210008 | VERSION_CONFLICT | 版本冲突 | 重新拉取最新版本 |\n| 210009 | CONTENT_SIZE_OVERLOAD | 单篇笔记超限 | **拆分写入** |\n| 210010 | EXIST_GUIDE | 新手引导笔记重复 | 跳过或改名 |\n| 210011 | SHARE_DOC_NOPERM | 共享知识库无权访问 | 联系知识库管理员 |\n| 210012 | USER_IS_DELETE | 用户已注销 | - |\n| 210030 | NOTEBOOK_NAME_EXIST | 笔记本名称重复 | 改名 |\n| 210031 | NOTEBOOK_NUM_LIMIT | 笔记本数量达上限 | 清理 |\n| 210032 | BATCH_EXEC_FAIL | 批量部分失败 | 检查 `data.failed_list` |\n| 210033 | BATCH_EXEC_ALL_FAIL | 批量全部失败 | 重试 |\n| 210034 | PRIVATE_NOTE_NOT_OWNER | 私有笔记非作者 | 无权访问 |\n| 210035 | FOLDER_NOT_EXIST | 笔记本不存在 | 检查 folder_id |\n| 20002 | - | apiKey 超过最大限频 | 降低调用频率 |\n| 20004 | - | apiKey 鉴权失败 | 检查 IMA_OPENAPI_CLIENTID/IMA_OPENAPI_APIKEY |\n\n## 6. 关键 API 详解\n\n### 6.1 `get_knowledge_list`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"cursor\": \"\", \"limit\": 50}'\n```\n\n| 参数 | 必填 | 说明 |\n|------|:----:|------|\n| `knowledge_base_id` | ✅ | 知识库 ID |\n| `cursor` | ✅ | 首次为空字符串，翻页用 `next_cursor` |\n| `limit` | ✅ | 1-50 |\n| `folder_id` | ❌ | 文件夹 ID（不传=根目录）|\n| `tags` | ❌ | 按标签筛选（数组）|\n\n**返回结构**（注意是 `knowledge_list` 不是 `list`）：\n```json\n{\n \"knowledge_list\": [\n {\"media_id\": \"...\", \"title\": \"...\", \"parent_folder_id\": \"...\", \"tags\": [...], \"media_type\": 99},\n ...\n ],\n \"is_end\": false,\n \"next_cursor\": \"...\",\n \"current_path\": [{\"folder_id\": \"...\", \"name\": \"...\"}]\n}\n```\n\n### 6.2 `move_knowledge`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}]\n }'\n```\n\n**注意**：\n- `infos` 最多 10 个文件\n- 返回的 `data.move_results[media_id].ret_code` 表示单文件结果\n\n### 6.3 `tag_add` / `tag_remove`\n\n**`item_name` 必须严格匹配 `get_knowledge_list` 返回的完整标题**（含扩展名和括号内容）。简化标题会导致 **220001** 错误（注意：220001 来自旧文档，实际 IMA 平台可能改用 210001）。\n\n### 6.4 `export_note` 返回 COS URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"\",\"target_content_format\":1}' | python3 -c \"\nimport sys, json, urllib.request\nd = json.load(sys.stdin)\nif d['code'] == 0:\n url = d['data']['content_url']\n req = urllib.request.Request(url)\n resp = urllib.request.urlopen(req)\n print(resp.read().decode('utf-8'))\nelse:\n print(d)\n\"\n```\n\n**关键**：`data.content_url` 是 COS 链接，**约 3 小时时效**，需要二次 `curl` 请求获取内容。\n\n### 6.5 `import_doc` 创建笔记\n\n```bash\n# 第一行文本会被自动提取为笔记标题\npython3 -c \"\nimport json\nwith open('guide_content.md', 'r') as f:\n content = f.read()\nwith open('note_request.json', 'w') as f:\n json.dump({\n 'content_format': 1,\n 'content': content,\n 'title': '📖 主题导览：[主题名称]',\n 'folder_id': '<目标笔记本 ID>'\n }, f, ensure_ascii=False, indent=2)\n\"\n\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/import_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d @note_request.json | python3 -m json.tool\n```\n\n**注意**：`title` 参数会被忽略，**第一行 `content` 文本**会成为标题。\n\n### 6.6 `append_doc` 追加内容\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/append_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\", \"content_format\": 1, \"content\": \"<追加内容>\"}'\n```\n\n### 6.7 `export_note_blocks` + `update_note` 精细编辑\n\n```bash\n# 第一步：获取 block 结构\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note_blocks\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\"}'\n\n# 第二步：按 block_id 修改\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/update_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\", \"block_id\": \"\", \"content\": \"<新内容>\"}'\n```\n\n### 6.8 `search_note` 按标题/正文搜索\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/search_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"search_type\": 0, \"query_info\": {\"title\": \"主题导览\"}, \"start\": 0, \"end\": 20}'\n```\n\n**返回**：\n```json\n{\n \"search_note_infos\": [\n {\n \"note_book_info\": {\n \"note_id\": \"...\",\n \"title\": \"...\",\n \"summary\": \"...\",\n \"note_ext_info\": {\"folder_id\": \"...\", \"folder_name\": \"...\"}\n },\n \"highlightInfo\": {\"doc_title\": \"包含高亮的标题\"}\n }\n ],\n \"is_end\": true,\n \"total_hit_num\": 3\n}\n```\n\n### 6.9 `list_note` 列出笔记\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/list_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"folder_id\": \"\", \"sort_type\": 0, \"cursor\": \"\", \"limit\": 20}'\n```\n\n**注意**：cursor 翻页用偏移量（已获取条目数）。\n\n### 6.10 `export_media_for_ima_sandbox` 获取永久 URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"<文件media_id>\"}'\n```\n\n**返回结构**：\n```json\n{\n \"media_type\": 2,\n \"media_content_url_info\": {\n \"url\": \"https://...\",\n \"headers\": {\"key\": \"value\"} // 如果非空需要传入 header\n }\n}\n```\n\n**`media_type` 速查表**（从 ima-knowledge knowledge_base_read.md 完整版）：\n\n| 值 | 类型 | 链接策略 |\n|----|------|---------|\n| 1 | PDF 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 2 | 网页 | ✅ 获取真实 URL |\n| 3 | Word 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 4 | PPT 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 5 | Excel 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 6 | 公众号文章 | ✅ 获取真实 URL |\n| 7 | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| 9 | 图片 | ⚠️ 标注\"请在知识库查看\" |\n| 11 | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| 12 | QA 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 13 | TXT 文本 | ⚠️ 不内嵌链接，写为纯文本 |\n| 14 | Xmind | ⚠️ 标注\"请在知识库查看\" |\n| 15 | 录音 | ⚠️ 标注\"请在知识库查看\" |\n| 16 | 网页视频 | ⚠️ 标注\"请在知识库查看\" |\n| 17 | 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 18 | 视频 | ⚠️ 标注\"请在知识库查看\" |\n| 19 | 播客 | ⚠️ 标注\"请在知识库查看\" |\n| 20 | HTML | ⚠️ 标注\"请在知识库查看\" |\n| 21 | EPUB 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 99 | 文件夹 | ❌ 不可链接 |\n\n## 7. IMA 平台已知限制（2026-09）\n\n| 操作 | 状态 |\n|------|:----:|\n| ❌ 删除笔记 | API 不支持，需客户端手动 |\n| ❌ 删除知识库 | API 不支持 |\n| ❌ 删除文件夹 | API 不支持 |\n| ❌ 删除文件 | API 不支持 |\n| ✅ 删除标签 | API 支持 |\n| ✅ 修改笔记 frontmatter | API 不支持（创建时设定）|\n| ✅ 向量搜索 | 由 IMA search/fetch 处理，不归本 skill |\n\n---\n\n## 8. v5.0.0 → v5.0.1 变更总结\n\n### 修正的错误\n\n| v5.0.0 错误 | v5.0.1 正确 |\n|------------|------------|\n| `get_media_info` | ❌ 删除（不存在）|\n| `list_knowledge_bases` | `search_knowledge_base` |\n| `list_notebooks` | `list_notebook` |\n| `list_notes` | `list_note` |\n| `create_notebook` | `add_notebook` |\n| `220001` 等旧错误码 | `210001`-`210035` + `20002`/`20004` |\n\n### 补充的缺失端点（11 个）\n\n- `search_knowledge`\n- `search_knowledge_base_in_square`\n- `create_knowledge_base`\n- `update_knowledge_base_basic_info`\n- `rename_knowledge`\n- `set_knowledge_top`\n- `import_urls`\n- `add_knowledge`\n- `update_knowledge_base_permission`\n- `join_knowledge`\n- `update_knowledge_access_status`\n- `move_notes`（note/v1，复数）\n- `push_note`\n- `rename_note`\n- `rename_notebook`\n\nFile v5.0.2:references/cases/quantitative-investing.md\n\n# 实战案例：量化投资知识库\n\n> 基于 2026-06-29 至 2026-07-01 在量化投资知识库（kb_id: `I_49nAThDICNno0gyhjl4dU1zUFtkNWv0X7mhlBQID8=`）的试跑总结。\n\n## 1. 知识库概况\n\n| 维度 | 数据 |\n|------|------|\n| 主题 | 量化投资（因子模型、机器学习、情绪分析等）|\n| 资料类型 | PDF、笔记、公众号文章、网页 |\n| 初始规模 | 35 个根目录散落文件 |\n| 最终规模 | 135 个文件，7 个顶层文件夹 |\n| 标签总数 | 244 个 |\n| 主题导览 | 7 个 |\n\n## 2. 阶段成果\n\n| 阶段 | 文件数 | 散落文件 | 标签 | 主题导览 |\n|------|:------:|:--------:|:----:|:-------:|\n| 初始 | 35 | 35 | 0 | 1 |\n| 演示后 | 36 | 35 | 20 | 1 |\n| 6 导览+30 打标 | 66 | 35 | 264 | 7 |\n| 归类后（move_knowledge）| 101 | 0 | 264 | 7 |\n| 多层归类后（PDF 单独处理）| 135 | 0 | 264 | 7 |\n\n**关键收获**：\n- 35 个根目录文件归类 → 0 散落\n- 14 个父文件夹文件移到子文件夹 → 结构清晰\n- 所有 244 个标签保留（移动文件前无标签，零风险）\n\n## 3. 最终文件夹结构\n\n```\n量化投资/\n├── 数据工具与入门/ （AkShare、聚宽、JQData 等）\n├── 金融情绪分析/ （情绪温度计、市场情绪等）\n├── 因子与资产定价/ （Fama-French、Alpha 因子等）\n├── 高频交易与微观结构/ （HFT、订单流等）\n├── 交易策略与系统/ （策略设计、回测等）\n├── AI 量化与深度学习/ （顶层）\n│ ├── 机器学习理论方法/\n│ ├── 大模型与智能体/\n│ └── 深度学习与预测模型/\n└── 主题导览（位于各文件夹）/\n ├── 📖 主题导览：数据工具与入门\n ├── 📖 主题导览：金融情绪分析\n ├── ...\n```\n\n**特点**：\n- 7 个顶层文件夹\n- AI 量化与深度学习含 3 个子文件夹（多层结构）\n- 父文件夹放主题导览，子文件夹不需要各自导览\n\n## 4. 关键词映射表\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n## 5. 试跑经验教训\n\n### 5.1 `item_name` 必须严格匹配完整标题\n\n完整标题包括扩展名（如 `.pdf`）和括号内容。\n\n```json\n// ❌ 简化标题（失败，code=220001）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易\"}\n\n// ✅ 完整标题（成功）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易 (伊夫-希尔皮斯科) (z-library.sk, 1lib.sk, z-lib.sk).pdf\"}\n```\n\n### 5.2 `limit` 参数范围 (0, 50]\n\n最大 50，超过会返回 51 错误。\n\n### 5.3 API 幂等性\n\n`tag_add` 重复打、`tag_remove` 移除不存在的——均直接返回成功。可放心重试和断点续传。\n\n### 5.4 `tag_remove` 完全可逆\n\n`tag_remove` 后文件 `tags` 字段变为 `[]`，不留痕迹。**`tag_delete` 才是不可逆的**。\n\n### 5.5 媒体类型覆盖建议\n\n试跑中覆盖了 PDF/笔记/公众号/网页（4 种）。未覆盖 Word/PPT/Excel/Markdown/视频/图片等。**真实场景使用前**建议覆盖完整 14 种类型。\n\n### 5.6 标签数量预期\n\n文章级标签每篇 3-5 个，128 篇内容的知识库预计产生 384-640 个标签。**标签总数 > 100 时建议人工审查命名规范**。\n\n### 5.7 `add_knowledge` ≠ `move_knowledge`（最关键）\n\n| 操作 | 行为 | parent_folder_id |\n|------|------|:----------------:|\n| `add_knowledge` | 文件\"展示\"在文件夹中（虚拟关联）| ❌ 不变 |\n| `move_knowledge` | 真正改变 `parent_folder_id` | ✅ 变为目标文件夹 |\n\n**仅调用 `add_knowledge` 不调用 `move`，文件会永远挂在根目录**。\n\n### 5.8 `move_knowledge` 会清空标签\n\n**应对模式**：\n1. 移动前备份标签\n2. 执行 `move_knowledge`\n3. 移动后逐个重新打标\n\n### 5.9 根目录调用 ≠ 知识库全貌\n\n不带 `folder_id` 调 `get_knowledge_list` 会返回**所有项目**（含 7 个文件夹 + 35 个散落文件 + 60 个已分配文件的\"虚拟副本\"）。\n\n**真正判断散落的方法**：比较文件的 `parent_folder_id` 与知识库根目录 ID。\n\n### 5.10 多层文件夹结构诊断\n\n复杂知识库需要**递归扫描**：\n\n```python\nfor folder in root_folders:\n items = get_knowledge_list(folder_id=folder.id)\n sub_folders = [f for f in items if f.type == 99]\n files = [f for f in items if f.type != 99]\n \n for sub in sub_folders:\n sub_items = get_knowledge_list(folder_id=sub.id)\n # 继续递归\n```\n\n判断标准：\n- 父文件夹下的\"直接挂载文件\"如果主题匹配子文件夹，**应该移到子文件夹**\n- 导览应放父级，**不需要**给每个子文件夹单独生成导览\n\nFile v5.0.2:references/folder-organization.md\n\n# 文件夹组织（阶段 0 详细）\n\n> 适用于：知识库结构混乱、文件散落在根目录、需要多层结构整理。\n\n## 0.1 三种\"文件夹\"操作\n\n| 操作 | API | 效果 | 何时使用 |\n|------|-----|------|---------|\n| **创建文件夹** | `create_folder` | 在知识库根目录建一个新文件夹 | 建立分类骨架 |\n| **虚拟归类** | `add_knowledge` | 让文件\"看起来\"在文件夹中（**parent_folder_id 不变**）| 临时展示 |\n| **物理归类** | `move_knowledge` | 真正修改 `parent_folder_id` 为目标文件夹 | 真正整理 |\n\n**关键警告**：\n- `add_knowledge` 创建的是\"虚拟关联\"，**不改变 `parent_folder_id`**\n- 仅用 `add_knowledge` 而不调用 `move_knowledge`，文件永远挂在根目录\n- 根目录调用 `get_knowledge_list` 会返回所有文件（包括已\"虚拟关联\"的），但这不代表它们真正归属于文件夹\n\n## 0.2 诊断流程\n\n### 步骤 1：拉取知识库根目录\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"limit\": 50}'\n```\n\n### 步骤 2：识别散落文件\n\n```python\nROOT_FOLDER_ID = \"<知识库根目录 ID>\" # 通常通过 get_knowledge_base 获取\n\norphans = [f for f in root_items\n if f.get(\"media_type\") != 99\n and f.get(\"parent_folder_id\") == ROOT_FOLDER_ID]\n```\n\n### 步骤 3：递归扫描文件夹层级\n\n对每个文件夹调用 `get_knowledge_list(folder_id=...)`，记录：\n- 子文件夹（`media_type == 99`）\n- 文件数\n- 每个文件的 `parent_folder_id` 是否等于当前 `folder_id`\n\n### 步骤 4：分类汇总\n\n| 状态 | 含义 | 处理方式 |\n|------|------|---------|\n| 文件 `parent_folder_id` 是根目录 | 真正散落 | 用 `move_knowledge` 归类 |\n| 文件 `parent_folder_id` 是文件夹 ID | 已归类 | 仅检查是否需要打标签 |\n| 文件仅在根目录返回但 parent 是文件夹 | 虚拟关联 | 已正确处理 |\n\n## 0.3 诊断输出模板\n\n```markdown\n## 知识库结构诊断报告\n\n### 顶层文件夹\n| 文件夹 | 文件数 | 含子文件夹 |\n|--------|:------:|:----------:|\n| ... | ... | ... |\n\n### 散落文件\n- 共 X 个文件 `parent_folder_id` 是根目录\n- 列出每个文件的标题和推荐目标文件夹\n\n### 多层结构\n- AI 量化与深度学习/\n - 机器学习理论方法/（Y 个文件）\n - 大模型与智能体/（Y 个文件）\n - ...\n\n### 处理建议\n- 散落文件：调用 `move_knowledge` 归类\n- 多层结构：导览放父级，子文件夹不需要各自导览\n```\n\n## 0.4 归类流程\n\n### 步骤 1：列出待归类文件\n\n```python\n# 从诊断报告中获取散落文件\norphans = [(f[\"media_id\"], f[\"title\"]) for f in orphan_files]\n```\n\n### 步骤 2：推荐目标文件夹\n\n关键词匹配模式（参考实战案例）：\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n> 关键词表针对量化投资领域；其他领域需重新设计。\n\n### 步骤 3：批量调用 `move_knowledge`\n\n```bash\n# 移动到目标文件夹（src_kb_id == dst_kb_id 表示知识库内移动）\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}, {\"media_id\": \"\"}]\n }'\n```\n\n**注意**：每次最多 10 个文件，分批调用。\n\n### ⚠️ `move_knowledge` 的副作用\n\n| 副作用 | 说明 |\n|--------|------|\n| `parent_folder_id` 改变 | ✅ 这是目标行为 |\n| **文件标签可能丢失** | ⚠️ 移动前若有标签，先备份！|\n\n**标签备份与恢复模式**：\n\n```python\n# 1. 移动前：备份标签\nbackup = {f[\"media_id\"]: f.get(\"tags\", []) for f in to_move_files}\n\n# 2. 执行 move_knowledge\napi_call(\"openapi/wiki/v1/move_knowledge\", {...})\n\n# 3. 移动后：恢复标签\nfor media_id, tags in backup.items():\n for tag in tags:\n tag_add(kb_id, media_id, real_title, tag)\n```\n\n### 步骤 4：验证归类效果\n\n```python\n# 验证根目录为空\nroot_items = get_knowledge_list(kb_id, limit=50) # 不带 folder_id\nremaining = [f for f in root_items if f.get(\"media_type\") != 99]\nassert len(remaining) == 0, f\"根目录仍有 {len(remaining)} 个散落文件\"\n\n# 验证每个文件夹的文件数符合预期\n```\n\n## 0.5 多层结构设计原则\n\n- **导览放父级**：父文件夹放主题导览，子文件夹**不需要**各自的导览\n- **MECE 划分**：子文件夹之间互斥、覆盖完整\n- **层级不超过 3 层**：超过 3 层说明分类需要重新设计\n- **避免\"其他\"类子文件夹**：用语义命名而非兜底类\n\n## 0.6 文件夹层级模式\n\n**模式 A：扁平**（推荐用于中等规模）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2\n└── 文件夹 3\n```\n\n**模式 B：2 层嵌套**（推荐用于复杂领域）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2（复杂主题）\n│ ├── 子文件夹 A\n│ ├── 子文件夹 B\n│ └── 子文件夹 C\n└── 文件夹 3\n```\n\n## 0.7 与标签的协同\n\n| 维度 | 文件夹 | 标签 |\n|------|:---:|:---:|\n| 主导维度 | 主题分类 | 多维关联 |\n| 结构 | 树状（一文件一父） | 网状（一文件多标签）|\n| 人类友好 | 高（导览） | 低（API）|\n| 机器友好 | 低 | 高 |\n| 一致性要求 | 文件归属唯一 | 一文件多标签 |\n| 创建方式 | 必须事先规划 | 可渐进添加 |\n\n**核心原则**：文件夹负责\"内容组织\"，标签负责\"维度标记\"，二者互为补充。\n\n## 0.8 实战案例\n\n详见 [cases/quantitative-investing.md](cases/quantitative-investing.md)\n\n## 0.9 与 `add_knowledge` 的对比使用场景\n\n| 场景 | 用什么 API |\n|------|----------|\n| 临时把笔记\"展示\"在文件夹中 | `add_knowledge` |\n| 把已有文件真正归类 | `move_knowledge` |\n| 新建文件时指定归属 | `add_knowledge`（创建时即关联）|\n| 把根目录散落文件归位 | `move_knowledge` |\n| 调整多层结构 | `move_knowledge` |\n\nFile v5.0.2:references/guide-template.md\n\n# 主题导览笔记撰写规范\n\n> 适用于：Ingest 操作中的 Compile 子任务。所有导览笔记应遵循统一的 4 章节结构 + schema frontmatter。\n\n## 1. 完整 frontmatter（强制）\n\n> 详见 [schema.md](schema.md) — 这是强制契约，所有导览必须遵守。\n\n```yaml\n---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本，基于知识库资料编译\nsources:\n - [《文章1》](URL)\n - 《文章2》\n - 《文章3》— 请在知识库查看\nrelated_guides:\n - [《主题导览：相关主题》](URL)\n---\n```\n\n## 2. 结构模板\n\n> 模板来源：基于\"交易策略与系统\"主题导览的专业实践版本\n\n```markdown\n# 主题导览：[主题名称]\n\n**版本**：v1.0 | 创建于 YYYY-MM-DD | 更新于 YYYY-MM-DD\n**更新日志**：v1.0 - 初始版本，基于知识库资料编译\n\n## 一、主题定位\n（主题定义 + 解决问题 + 核心逻辑 + 依赖链条）\n\n本主题是XX的XX层，位于XX与XX之间。它解决的核心问题是：如何XX。\n本主题涵盖XX、XX、XX三个关键环节，是XX的桥梁。其核心逻辑遵循清晰的依赖链条：XX → XX → XX → XX。\n\n## 二、核心概念与关键要素\n\n### （一）[核心概念A]\n**核心思想**：一句话概括该概念的本质。\n\n**关键要素**：\n• 要素1：详细说明。相关文章[《文章标题》](链接)指出，具体内容...\n• 要素2：详细说明。相关文章[《文章标题》](链接)进一步说明...\n• 要素3：详细说明。\n\n**实践建议**：\n• 建议1：具体可操作的实践指导\n• 建议2：具体可操作的实践指导\n\n### （二）[核心概念B]\n（同上结构）\n\n## 三、学习路径（融合知识网络）\n\n（以下学习路径以主线展示知识网络的连接关系，每个步骤标注了所需的核心知识储备和与之相关的概念。可根据主题实际需要设置1-N条路径，不必固定为两条）\n\n（如有多条路径，在此展示）\n\n## 四、相关主题\n\n以下主题与\"本主题名称\"紧密关联，构成了更宽广的知识网络：\n\n| 相关主题 | 与本主题的关系 | 关键连接点 |\n|---------|--------------|-----------|\n| XX | XX | XX |\n| XX | XX | XX |\n```\n\n## 2. 4 章节结构规范\n\n| 章节 | 内容详略 | 内容要求 | 写作要点 |\n|------|---------|---------|---------|\n| **一、主题定位** | **略写** 一段话（约 100 字）| 定义 + 解决问题 + 核心逻辑 + 依赖链条 | 用\"是...的 XX 层，位于 XX 与 XX 之间\"句式；依赖链条用箭头链展示 |\n| **二、核心概念与关键要素** | **详写** 每概念约 200-300 字 | 核心思想 + 关键要素（引用文章）+ 实践建议 | 每个关键要素都要引用知识库文章；实践建议要具体可操作 |\n| **三、学习路径（融合知识网络）** | **中等** 表格 + 一段话 | 两条路径 + 表格形式 + 最终整合 | 表格内容精简，最终整合一段话点明闭环逻辑 |\n| **四、相关主题** | **略写** 表格形式 | 主题 + 关系 + 连接点 | 说明每个关联主题的具体连接点，无需展开 |\n\n## 3. 关键要素写作规范\n\n每个关键要素的写作采用以下结构：\n\n```markdown\n• 要素名称：详细说明。相关文章《文章标题》指出，具体内容...\n• 要素名称：详细说明。相关文章《文章标题》进一步说明...\n```\n\n**要点**：\n- 冒号前是要素名称（简洁短语）\n- 冒号后是详细说明（1-2 句话）\n- 末尾用\"相关文章[《标题》](链接)指出/进一步说明/提供了...\"格式引用\n- 引用来源必须是知识库中的实际文章\n- **必须提供可点击的链接**，不能只写文章标题\n\n## 4. 实践建议写作规范\n\n每个核心概念卡片末尾，用编号列表展示 2-3 条具体可操作的实践建议：\n\n```markdown\n**实践建议**：\n• 先有逻辑，后有回测：策略设计应先论证底层投资逻辑，回测只是验证工具，不能替代逻辑思考。\n• 动态适应：策略参数需随市场环境变化而调整，融入宏观前瞻和状态感知可增强跨周期表现。\n• 简单性优先：优先选择参数少、逻辑清晰的简单策略，减少过拟合风险。\n```\n\n**要点**：\n- 建议要具体可操作，不是空泛原则\n- 每条建议都有明确的行动指引\n- 可以引用具体文章中的实践方法\n\n## 5. 学习路径表格规范\n\n**表格列定义**：\n\n| 列名 | 内容 |\n|------|------|\n| 步骤 | 第 X 步：具体步骤名称 |\n| 核心知识 | 需要掌握的核心概念 |\n| 知识网络连接 | 与其他主题的关联（用 → 表示递进，用 → 需要表示依赖）|\n\n**最终整合**：在表格后用一段话总结闭环流程。\n\n## 6. 链接处理规则\n\n> **前置要求**：链接处理必须在**第三步（预获取链接信息）**中完成，不得在编译阶段临时获取。\n\n详见 [link-handling.md](link-handling.md)\n\n## 7. 特殊字符处理\n\n文章标题中可能含有干扰 Markdown 渲染的字符：\n- `|` → 替换为全角 `｜` 或省略\n- `[` `]` `_` `*` → 需转义或省略\n\n## 8. 内容必须基于知识库实际文件\n\n导览笔记的文章列表必须从 `get_knowledge_list` 返回的实际文件生成，不能依赖本地缓存文件。\n\n## 9. 编译质量标准\n\n1. **原子化**：每个知识节点围绕单一主题，避免东拉西扯\n2. **关联性**：知识卡片之间通过超链接形成网状结构\n3. **大纲化**：每个卡片内部有完整的章节结构\n4. **可溯源**：标注每篇文章的来源出处\n5. **可读性**：结构清晰、信息密度适中、美观易读\n\nFile v5.0.2:references/incremental-update.md\n\n# 增量更新（阶段 4 详细）\n\n> 适用于：知识库已有该主题旧版本导览，需要增量更新。\n\n## 1. 读取旧版本\n\n```bash\n# 导出旧版本笔记内容\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"<旧版note_id>\",\"target_content_format\":1}' | \\\npython3 -c \"import sys,json,urllib.request; d=json.load(sys.stdin); url=d['data']['content_url']; req=urllib.request.Request(url); resp=urllib.request.urlopen(req); print(resp.read().decode('utf-8'))\"\n```\n\n## 2. 提取版本信息\n\n从标题下方的版本行提取：\n\n```\n**版本**：v1.0 | 创建于 2026-05-08 | 更新于 2026-05-08\n**更新日志**：v1.0 - 初始版本\n```\n\n## 3. 对比知识库增量\n\n获取文件夹最新文件列表，与旧版本对比：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"folder_id\": \"\", \"count\": 100}' | \\\npython3 -c \"import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('list',[])])\"\n```\n\n## 4. 识别增量内容\n\n| 类型 | 判断方式 | 更新方式 |\n|------|---------|---------|\n| 新增文章 | 旧版本\"四、知识卡片\"中不存在 | 补充到对应核心概念的关键要素中 |\n| 删除文章 | 旧版本提及但知识库中已不存在 | 从列表中移除 |\n| 概念变化 | 知识库中出现新的核心概念分类 | 新增核心概念卡片 |\n\n## 5. 更新导览内容\n\n更新原则：\n- **保留原有结构**：不改变核心概念划分方式\n- **更新关键要素**：补充/移除文章引用\n- **更新实践建议**：根据新增内容调整实践建议\n- **更新学习路径**：如有新的依赖关系\n\n**链接格式要求**（必须严格遵守，引用格式：`[《标题》](URL)`）：\n- 所有引用必须提供**可点击的有效链接**\n- 链接来源参考**第三步生成的链接特性表**，选择正确的写法：\n - 云文档类：使用相对路径格式 `[《标题》](路径)`\n - 网页链接：使用完整 URL 格式 `[《标题》](URL)`\n - 纯本地文件：使用文件路径格式并标注来源\n- 禁止使用裸链接或纯 URL 文本，必须包装为引用格式\n\n## 6. 版本号更新\n\n```yaml\n---\nversion: 1.1 # patch+0.0.1 或 minor+0.1 或 major+1.0\ncreated: 2026-05-08\nupdated: 2026-05-08\nchangelog:\n - v1.1: 增量更新，补充了X篇新文章，更新了关键要素描述\n - v1.0: 初始版本\n---\n```\n\n详见 [versioning.md](versioning.md) 的版本号规则。\n\n## 7. 写入新版本\n\n详见 [write-and-verify.md](write-and-verify.md)\n\n> 💡 推荐使用\"创建新笔记 + 标注替代旧版\"模式，保留旧笔记作为历史版本（详见 [security.md](security.md) 第 3 节）。\n\nFile v5.0.2:references/ingest.md\n\n# Ingest（摄取）操作\n\n> Karpathy 三大操作之首。完整覆盖\"资料入库到 Wiki 演化\"的全部过程。\n> 核心理念：**一次 Ingest 可能级联更新多个导览（知识复利）**。\n\n## 1. 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n## 2. Collect（收集）\n\n### 2.1 资料来源\n\n- 用户上传的文件（PDF/DOCX/PPTX/XLSX 等）\n- 已有 IMA 知识库的内容\n- 联网搜索（用 `search(source=\"web\")`）\n- 网页链接（用 `import_urls`）\n\n### 2.2 收集方式\n\n| 来源 | API | 说明 |\n|------|-----|------|\n| 用户上传文件 | `upload_file` | 上传到指定知识库 |\n| 导入网页 | `import_urls` | 批量导入 URL |\n| 已有知识库 | `get_knowledge_list` | 逐级浏览 |\n| 用户上传笔记 | `add_knowledge` | 关联到知识库 |\n| 联网搜索 | `search(source=\"web\")` | 补充资料 |\n\n### 2.3 资料完整性原则\n\n> \"此阶段追求完整性，不追求结构\" — 所有资料都是后续编译的\"原材料\"\n\n详见 [link-handling.md](link-handling.md) 第 1 节和 [api-reference.md](api-reference.md) 第 5.1 节\n\n## 3. Check（检查）\n\n### 3.1 是否有旧导览？\n\n```bash\n# 在目标文件夹搜索标题包含\"主题导览\"的笔记\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/search_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"search_type\": 0, \"query_info\": {\"title\": \"主题导览\"}, \"start\": 0, \"end\": 20}'\n```\n\n或者用标签筛选（推荐）：\n```bash\n# 列出所有带\"状态:已编译\"标签的导览\nget_knowledge_list(kb_id=X, tags=[\"状态:已编译\"])\n```\n\n### 3.2 判断\n\n| 情况 | 处理方式 |\n|------|---------|\n| 有旧导览（目标主题） | **增量更新**：Compile 模式 2 |\n| 有其他主题导览 | **新建**：Compile 模式 1 |\n| 没有任何知识导览 | **新建**：Compile 模式 1 |\n\n详见 [versioning.md](versioning.md) 第 4 节\n\n## 4. Link（链接特性）\n\n每个文件能否在导览中链接？这是 Karpathy **\"可追溯到 raw\"** 的核心要求。\n\n### 4.1 media_type 速查表（IMA 完整版）\n\n| 值 | 类型 | 链接策略 |\n|----|------|---------|\n| 1 | PDF 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 2 | 网页 | ✅ 获取真实 URL |\n| 3 | Word 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 4 | PPT 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 5 | Excel 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 6 | 公众号文章 | ✅ 获取真实 URL |\n| 7 | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| 9 | 图片 | ⚠️ 标注\"请在知识库查看\" |\n| 11 | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| 12 | QA 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 13 | TXT 文本 | ⚠️ 不内嵌链接，写为纯文本 |\n| 14 | Xmind | ⚠️ 标注\"请在知识库查看\" |\n| 15 | 录音 | ⚠️ 标注\"请在知识库查看\" |\n| 16 | 网页视频 | ⚠️ 标注\"请在知识库查看\" |\n| 17 | 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 18 | 视频 | ⚠️ 标注\"请在知识库查看\" |\n| 19 | 播客 | ⚠️ 标注\"请在知识库查看\" |\n| 20 | HTML | ⚠️ 标注\"请在知识库查看\" |\n| 21 | EPUB 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 99 | 文件夹 | ❌ 不可链接 |\n\n详见 [link-handling.md](link-handling.md) 第 2 节\n\n### 4.2 链接特性表模板\n\n```markdown\n| media_id | title | media_type | 链接策略 | URL/备注 |\n|---------|-------|-----------|---------|---------|\n| xxx | 文章A | 2 | ✅ 可内嵌 | https://... |\n| xxx | 文章B | 6 | ✅ 可内嵌 | https://... |\n| xxx | 文章C | 7 | ⚠️ 不内嵌 | 请在知识库中查看 |\n```\n\n## 5. Compile（编译）\n\n### 5.1 模式 1：新建（5 步法）\n\n1. **明确主题** — 确定核心概念（主题定位、核心概念、边界范围）\n2. **梳理关键词** — 提取关键要素（每概念 3-5 个子主题）\n3. **发现关系** — 找出逻辑关联（层级、并列、因果、对立）\n4. **呈现结构** — 可视化知识网络（表格 + 学习路径）\n5. **美化优化** — 提升可读性（标题规范、排版、信息密度）\n\n### 5.2 模式 2：增量更新（6 步法）\n\n1. **读旧版** — `export_note` 获取旧版本内容\n2. **提取版本信息** — 从 frontmatter 读取 version/changelog\n3. **对比增量** — 比对文件夹中文件与导览 sources[]\n4. **识别变化** — 新增/删除/概念变化\n5. **更新导览** — `append_doc`（推荐）或 `update_note`（精细）\n6. **更新版本号** — patch/minor/major\n\n详见 [guide-template.md](guide-template.md) 和 [versioning.md](versioning.md)\n\n## 6. Write（写入）\n\n### 6.1 选项 A：新建笔记（最简单）\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/import_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content_format\": 1,\n \"content\": \"<完整 Markdown>\",\n \"title\": \"📖 主题导览：[主题名称]\",\n \"folder_id\": \"<目标笔记本 ID>\"\n }'\n# 返回: {\"code\": 0, \"data\": {\"note_id\": \"xxx\"}}\n```\n\n### 6.2 选项 B：追加内容（增量推荐）\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/append_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"note_id\": \"<已有导览 ID>\",\n \"content_format\": 1,\n \"content\": \"<追加内容>\"\n }'\n```\n\n**优势**：不破坏原有结构，原子化操作。\n\n### 6.3 选项 C：按 block 编辑（精细修改）\n\n```bash\n# 第一步：导出 block 结构\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note_blocks\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\"}'\n\n# 第二步：按 block_id 修改\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/update_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"note_id\": \"\",\n \"block_id\": \"\",\n \"content\": \"<新内容>\"\n }'\n```\n\n详见 [write-and-verify.md](write-and-verify.md)\n\n### 6.4 立即验证\n\n> **重要**：笔记创建接口返回成功不代表内容完整，必须立即验证。\n\n```bash\n# 导出并比对\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"\",\"target_content_format\":1}' | \\\npython3 -c \"\nimport sys, json, urllib.request\nd = json.load(sys.stdin)\nif d['code'] == 0:\n url = d['data']['content_url'] # COS 链接，3 小时时效\n req = urllib.request.Request(url)\n resp = urllib.request.urlopen(req)\n print(resp.read().decode('utf-8'))\n\"\n```\n\n## 7. Cascade（级联）— **Karpathy 核心机制（IMA 实际可实现版）**\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）— 这是 wiki 知识复利的关键。\n\n### 7.1 ⚠️ IMA 平台实际限制（2026-09）\n\n> **v5.0.1 的 Cascade 算法与 IMA 平台实际能力有差距**。本节是修正版。\n\n| 操作 | IMA 支持 | 说明 |\n|------|---------|------|\n| 修改导览 frontmatter（version / updated / changelog）| ❌ **不支持** | frontmatter 是\"创建时设定\"，不可后续修改 |\n| `append_doc` 改 frontmatter | ❌ | 只能追加正文内容 |\n| `update_note` 改 frontmatter | ❌ | 只能改 block，不改 frontmatter |\n| `delete_note` 删除旧版本 | ❌ **不支持** | 只能客户端手动 |\n| `import_doc` 创建新笔记 | ✅ | **唯一的版本演进方式** |\n| `append_doc` 在旧笔记末尾追加标记 | ✅ | 用于\"已被新版本替代\"提示 |\n\n**结论**：每次 Cascade 必须**创建新笔记**（不是修改旧笔记）。\n\n### 7.2 Cascade 触发条件\n\n- 新文件被 Ingest 后\n- 自动计算它与所有现有导览的相关性\n- 相关度 > 阈值 的导览加入\"待更新列表\"\n\n### 7.3 Cascade 算法（纯 IMA API 可实现版）\n\n```python\ndef cascade_update_imap(new_file, all_guides, kb_id):\n \"\"\"Cascade 算法：纯 IMA API 实现\"\"\"\n affected = []\n\n # === 阶段 1：标签 Jaccard 粗筛（纯 API）===\n new_tags = set(new_file.get(\"tags\", []))\n candidate_guides = []\n\n for guide in all_guides:\n guide_tags = set(guide.get(\"tags\", []))\n if not (new_tags | guide_tags):\n continue\n # Jaccard 相似度\n jaccard = len(new_tags & guide_tags) / len(new_tags | guide_tags)\n\n # 文件夹归属加分（权重 0.3）\n folder_bonus = 0.3 if new_file.get(\"parent_folder_id\") == guide.get(\"parent_folder_id\") else 0\n\n # 标题关键词匹配加分（权重 0.3）\n keyword_bonus = 0.3 if any(\n kw in guide[\"title\"] for kw in extract_keywords(new_file[\"title\"])\n ) else 0\n\n total_score = jaccard + folder_bonus + keyword_bonus\n if total_score > 0.5: # 阈值\n candidate_guides.append({\n \"guide\": guide,\n \"score\": total_score,\n \"reason\": \"tag_overlap\" if jaccard >= 0.4 else (\"folder_match\" if folder_bonus else \"title_match\")\n })\n\n # 排序 + 限制\n candidate_guides.sort(key=lambda x: -x[\"score\"])\n candidate_guides = candidate_guides[:3] # 最多 3 个导览\n\n # === 阶段 2：用户确认（必选）===\n print(f\"📋 Cascade 候选导览：{len(candidate_guides)} 个\")\n for c in candidate_guides:\n print(f\" - {c['guide']['title']} (相关度: {c['score']:.2f}, 原因: {c['reason']})\")\n\n if not user_confirms():\n print(\"❌ 用户未确认，跳过 Cascade\")\n return []\n\n # === 阶段 3：创建新版本导览（关键）===\n affected = []\n for candidate in candidate_guides:\n old_guide = candidate[\"guide\"]\n new_guide = create_new_guide_version(old_guide, new_file)\n affected.append({\n \"old_note_id\": old_guide[\"note_id\"],\n \"new_note_id\": new_guide[\"note_id\"],\n \"score\": candidate[\"score\"]\n })\n\n return affected\n\n\ndef create_new_guide_version(old_guide, new_file):\n \"\"\"创建新版本导览（旧笔记保留作为历史）\"\"\"\n from datetime import datetime\n today = datetime.now().strftime(\"%Y-%m-%d\")\n\n # 1. 读旧导览（从 COS URL 下载）\n old_content = download_note(old_guide[\"note_id\"])\n\n # 2. 提取旧 frontmatter\n old_fm = parse_frontmatter(old_content)\n old_version = old_fm.get(\"version\", \"1.0.0\")\n old_changelog = old_fm.get(\"changelog\", [])\n old_confidence = old_fm.get(\"confidence\", \"medium\")\n old_created = old_fm.get(\"created\", today)\n\n # 3. 计算新版本号（patch）\n new_version = bump_patch_version(old_version) # v1.5 → v1.6\n\n # 4. LLM 生成新正文（增量更新 + 包含新文章引用）\n new_body = llm_generate_updated_body(old_content[\"body\"], new_file)\n\n # 5. 构建新 frontmatter\n new_frontmatter = f\"\"\"---\ntitle: {old_fm.get(\"title\", \"📖 主题导览\")}\ntype: guide\nconfidence: {reassess_confidence(old_confidence, new_file)}\ncreated: {old_created}\nupdated: {today}\nversion: {new_version}\nchangelog:\n - v{new_version}: [Ingest {today}] Cascade 级联更新，新增《{new_file[\"title\"]}》\n{chr(10).join(f\" - {entry}\" for entry in old_changelog)}\nsources:\n - 《{new_file[\"title\"]}》{(\"(\" + new_file.get(\"url\", \"\") + \")\") if new_file.get(\"url\") else \"\"}\n{chr(10).join(f\" - {s}\" for s in old_fm.get(\"sources\", []))}\n---\"\"\"\n\n # 6. 创建新笔记（关键步骤）\n result = ima_api(\"openapi/note/v1/import_doc\", {\n \"content_format\": 1,\n \"content\": new_frontmatter + \"\\n\\n\" + new_body,\n \"folder_id\": old_guide.get(\"folder_id\", \"\")\n })\n new_note_id = result[\"data\"][\"note_id\"]\n\n # 7. 在旧笔记末尾追加\"已被替代\"标记（可逆操作）\n ima_api(\"openapi/note/v1/append_doc\", {\n \"note_id\": old_guide[\"note_id\"],\n \"content_format\": 1,\n \"content\": f\"\"\"\n\n---\n\n> ⚠️ **本导览已被新版本替代**\n> 新版本：note_id={new_note_id} (v{new_version}, {today})\n> 旧版本保留作为历史记录。请在新版本基础上继续编辑。\n\"\"\"\n })\n\n return {\n \"note_id\": new_note_id,\n \"version\": new_version,\n \"old_note_id\": old_guide[\"note_id\"]\n }\n\n\ndef download_note(note_id):\n \"\"\"从 COS URL 下载笔记内容\"\"\"\n result = ima_api(\"openapi/note/v1/export_note\", {\n \"note_id\": note_id,\n \"target_content_format\": 1 # Markdown\n })\n if result[\"code\"] != 0:\n raise Exception(f\"export_note failed: {result}\")\n content_url = result[\"data\"][\"content_url\"]\n\n # 二次下载（3 小时时效）\n import urllib.request\n req = urllib.request.Request(content_url)\n with urllib.request.urlopen(req) as resp:\n markdown = resp.read().decode(\"utf-8\")\n\n return parse_note(markdown) # 解析 frontmatter + body\n\n\ndef bump_patch_version(version_str):\n \"\"\"v1.5 → v1.6, v1.0.1 → v1.0.2\"\"\"\n parts = version_str.split(\".\")\n if len(parts) == 2:\n # v1.5 → v1.6\n return f\"{parts[0]}.{int(parts[1]) + 1}\"\n elif len(parts) == 3:\n # v1.5.0 → v1.5.1\n return f\"{parts[0]}.{parts[1]}.{int(parts[2]) + 1}\"\n else:\n return \"1.0.1\"\n```\n\n### 7.4 Cascade 完整示例\n\n**场景**：用户上传\"遗传算法在量化交易中的应用\"到\"AI 量化与深度学习\"文件夹。\n\n**已有导览清单**：\n- 📖 主题导览：AI 量化与深度学习（v1.5, confidence: medium）\n- 📖 主题导览：因子与资产定价（v2.3, confidence: high）\n- 📖 主题导览：高频交易与微观结构（v3.0, confidence: high）\n\n**Cascade 过程**：\n\n| 导览 | 标签匹配 | Jaccard | 文件夹 | 总分 | 是否 Cascade |\n|------|---------|---------|--------|------|-------------|\n| AI 量化与深度学习 | ✅ `机器学习` `AI` | 0.7 | ✅ 同文件夹 | 1.3 | ✅ |\n| 因子与资产定价 | ❌ 不匹配 | 0 | ❌ | 0 | ❌ |\n| 高频交易 | ❌ 不匹配 | 0 | ❌ | 0 | ❌ |\n\n**执行结果**：\n- 创建新笔记 \"📖 主题导览：AI 量化与深度学习\"（v1.6）\n - 新 frontmatter（version 1.6, updated 2026-09-28, changelog 新增 v1.6 条目）\n - 新 body 包含\"遗传算法在量化交易中的应用\"文章引用\n- 在旧笔记（v1.5）末尾追加\"已被 v1.6 替代\"标记\n- **旧笔记保留**，作为历史版本\n\n### 7.5 Cascade 的产物\n\n**新笔记的 frontmatter**：\n```yaml\n---\ntitle: 📖 主题导览：AI 量化与深度学习\ntype: guide\nconfidence: medium # 可能因新文章加入而调整\ncreated: 2026-05-13 # 保留原创建日期\nupdated: 2026-09-28 # 更新\nversion: 1.6 # patch\nchangelog:\n - v1.6: [Ingest 2026-09-28] Cascade 级联更新，新增《遗传算法在量化交易中的应用》\n - v1.5: 之前的更新...\nsources:\n - 《遗传算法在量化交易中的应用》(URL)\n - [原有 sources...]\n---\n```\n\n**旧笔记末尾追加**：\n```markdown\n---\n\n> ⚠️ **本导览已被新版本替代**\n> 新版本：note_id=xxx (v1.6, 2026-09-28)\n> 旧版本保留作为历史记录。\n```\n\n### 7.6 Cascade 的成本控制\n\n| 控制项 | 措施 |\n|--------|------|\n| 阈值 | Jaccard + 文件夹 + 标题匹配，阈值 0.5 |\n| 范围 | 仅\"有标签交集\"的候选导览（避免遍历全部） |\n| 数量限制 | 最多 3 个导览 |\n| 用户确认 | 必选，不自动执行（避免误更新） |\n| 可关闭 | 用户可设置 `cascade_enabled: false` 关闭 |\n\n### 7.7 IMA 限制下的取舍\n\n| 取舍 | 原因 |\n|------|------|\n| **每次 Cascade = 创建新笔记** | IMA 不允许修改 frontmatter，必须新建才能准确记录 version/changelog |\n| **旧笔记保留不删除** | IMA 不支持删除 API（用户可在客户端手动清理） |\n| **每次 Cascade 成本较高** | 创建笔记 + 在旧笔记追加标记 = 2 次 API 调用 |\n| **可能产生\"笔记碎片\"** | 同一导览可能有多个历史版本（v1.4, v1.5, v1.6 都存在） |\n\n**优势**：版本历史天然保留，符合 Karpathy \"git 提交\"哲学，且不影响 Lint 检查（看 updated 字段）。\n\n### 7.8 为什么不修改旧笔记？\n\n> 因为 IMA 平台 frontmatter 是\"创建时设定\"，**没有任何 API 可以修改它**。\n\n这意味着：\n- ❌ 不能更新旧笔记的 `version: 1.5` → `1.6`\n- ❌ 不能在旧笔记的 `changelog:` 里追加新条目\n- ❌ 不能修改旧笔记的 `updated:` 字段\n\n只能：\n- ✅ 在旧笔记**正文**末尾追加标记（`append_doc`）\n- ✅ 创建新笔记（新 frontmatter 完全可控）\n\n**这就是为什么 Cascade = 创建新笔记 + 旧笔记追加标记**。\n\n## 8. 导览清单（Index）\n\n> Karpathy 的 `index.md` 在 IMA 平台没有等价物，但我们用\"主题导览清单\"代替。\n\n### 8.1 如何获取\n\n```bash\n# 方法 1：用标签筛选所有\"已编译\"导览\nget_knowledge_list(kb_id=X, tags=[\"状态:已编译\"])\n\n# 方法 2：用 search_note 按标题定位\nsearch_note(search_type=0, query_info={title: \"主题导览\"})\n```\n\n### 8.2 清单示例\n\n| 主题导览 | 位置 | 版本 | 最后更新 | confidence |\n|---------|------|:----:|:--------:|:----------:|\n| 📖 主题导览：因子与资产定价 | 因子与资产定价/ | v2.3 | 2026-08-01 | high |\n| 📖 主题导览：AI 量化与深度学习 | AI 量化与深度学习/ | v1.5 | 2026-07-15 | medium |\n| 📖 主题导览：高频交易 | 高频交易与微观结构/ | v3.0 | 2026-06-20 | high |\n\n### 8.3 清单的用途\n\n- LLM 评估新文件该更新哪些导览（Cascade 算法输入）\n- Lint 报告展示知识库全貌\n- 用户了解\"我有哪些导览\"\n\n## 9. 完整工作流示例\n\n**场景**：用户在\"AI 量化与深度学习\"知识库上传一篇新文章\"遗传算法在量化交易中的应用\"。\n\n```\n[Ingest 触发]\n ↓\n[Collect] upload_file 上传文件 → 等待完成\n ↓\n[Check] 在该文件夹搜索\"主题导览\"：\n - 找到 \"📖 主题导览：AI 量化与深度学习\"（v1.5）\n - 找到 \"📖 主题导览：高频交易\"（v3.0）— 但不在该文件夹，跳过\n ↓\n[Link] export_media_for_ima_sandbox 获取永久 URL（如适用）\n ↓\n[Compile] 增量更新模式：\n - 读旧版 → 提取版本信息（v1.5）\n - 对比增量 → 1 篇新增\n - 在\"机器学习理论方法\"核心概念的关键要素中补充遗传算法文章\n - 评估 confidence：medium → medium（无变化）\n ↓\n[Write] 用 append_doc 追加内容（不重建整个笔记）\n - note_id: xxx\n - content: <新的关键要素块>\n ↓\n[Cascade] 检查其他导览：\n - \"因子与资产定价\" → 相关度 0.3，不更新\n - \"高频交易\" → 相关度 0.4，不更新\n - 没有其他受影响导览\n ↓\n[报告] 告诉用户：\n - 主更新：1 个导览更新（v1.5 → v1.6）\n - 级联：0 个其他导览受影响\n - 下次建议：可考虑建\"遗传算法\"独立导览\n```\n\n## 10. 关键原则总结\n\n1. **可追溯**：每个导览的 sources[] 必须能追到 raw 资料\n2. **复利**：一次 Ingest 影响多个导览（不只一个）\n3. **原子化**：用 append_doc 而非重建整个笔记\n4. **schema 强制**：frontmatter 必填字段（confidence/sources/version）\n5. **人类策展**：用户决定收录什么，LLM 维护导览\n\nFile v5.0.2:references/link-handling.md\n\n# 链接处理（阶段 3 详细）\n\n> **前置要求**：链接处理必须在编译前完成，不得在编译阶段临时获取。\n\n## 1. 链接特性预获取流程\n\n### 步骤 1：收集文件列表\n\n获取文件夹中的所有文件，提取每个文件的 `media_id`、`media_type`、`title`：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"folder_id\": \"\", \"count\": 100}' | \\\npython3 -c \"import sys,json; data=json.load(sys.stdin); [print(f\\\"{f['media_id']}|{f['media_type']}|{f['title']}\\\") for f in data.get('data',{}).get('list',[])]\"\n```\n\n### 步骤 2：批量获取链接特性\n\n对每个文件调用 `export_media_for_ima_sandbox`：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"\"}'\n```\n\n### 步骤 3：生成链接特性表\n\n根据返回结果，建立如下表格：\n\n| media_id | title | media_type | 链接策略 | URL/备注 |\n|---------|-------|-----------|---------|---------|\n| xxx | 文章A | 2 (网页) | ✅ 可内嵌 | https://... |\n| xxx | 文章B | 6 (公众号) | ✅ 可内嵌 | https://... |\n| xxx | 文章C | 7 (Markdown) | ⚠️ 不内嵌 | 请在知识库中查看 |\n| xxx | 文章D | 11 (笔记) | ⚠️ 不内嵌 | 请在知识库中查看 |\n\n### 步骤 4：按类型分类编译\n\n编译导览笔记时，根据链接特性表选择正确的写法：\n\n| 文件类型 | 编译写法 |\n|---------|---------|\n| type 2/6 | `[标题](永久URL)` |\n| type 7/11 | `标题`（纯文本，不加链接）|\n| type 1/3/4/5 | `标题 — 请在知识库中查看` |\n\n## 2. 链接策略表\n\n| media_type | 类型 | 链接策略 |\n|-----------|------|---------|\n| **2** | 网页链接 | ✅ 获取真实 URL，格式：`[《标题》](URL)` |\n| **6** | 公众号文章 | ✅ 获取真实 URL，格式：`[《标题》](URL)` |\n| **7** | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| **11** | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| **1** | PDF | ⚠️ 标注\"请在知识库中查看\" |\n| **3** | Word | ⚠️ 标注\"请在知识库中查看\" |\n| **4** | PPT | ⚠️ 标注\"请在知识库中查看\" |\n| **5** | Excel | ⚠️ 标注\"请在知识库中查看\" |\n\n## 3. 引用格式示例\n\n```markdown\n# 可链接的类型（type 2/6）\n• 多维度指标体系：A股情绪温度计采集12个维度指标...[《A股情绪温度计》](https://...)详细阐述了...\n\n# 不可直接链接的类型（type 7/11/1/3/4/5）\n• 系统化执行：（请在知识库中查看）\n```\n\n## 4. 获取公众号/网页的永久 URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"<文件media_id>\"}'\n```\n\n返回的 `data.media_content_url_info.url` 即为永久可跳转链接。\n\n## 5. 特殊字符处理\n\n文章标题中可能含有干扰 Markdown 渲染的字符：\n- `|` → 替换为全角 `｜` 或省略\n- `[` `]` `_` `*` → 需转义或省略\n\n详见 [guide-template.md](guide-template.md) 第 7 节。\n\n## 6. 反模式教训\n\n### 反模式 1：Markdown 表格中包含 `|` 字符\n\n**问题**：知识库文章标题常含 `|`（如\"实务 | 审计抽样实操总结\"），在 Markdown 表格中 `|` 是列分隔符，导致表格解析错乱——一个单元格的内容会被拆成多列。\n\n**错误示例**：\n```markdown\n| # | 文章 | 关键词 |\n|---|------|--------|\n| 1 | 实务 | 审计抽样实操总结 | ← \"实务\"和\"审计抽样实操总结\"被拆成两列\n```\n\n**正确做法**：使用编号列表替代表格：\n```markdown\n1. **实务｜审计抽样实操总结** — 审计抽样实操、统计抽样方法\n```\n\n### 反模式 2：通过 `push_note` + `content_cos_key` 写入短内容\n\n**问题**：COS 上传路径对内容格式敏感，中间环节多（本地文件 → COS 上传 → API 读取），任何一环出错都会导致笔记内容丢失或被系统自动删除（`export_note` 返回 \"doc is delete\"）。\n\n**正确做法**：对于 < 3KB 的内容，直接使用 `import_doc` + `curl -d @filepath` 写入，跳过 COS 中间环节。\n\n### 反模式 3：创建笔记后不验证\n\n**问题**：笔记创建接口返回成功不代表内容完整。可能出现：标题正确但正文为空、内容被截断、笔记被系统自动清理等情况。\n\n**正确做法**：创建笔记后立即调用 `export_note` 导出内容，与原始内容比对。\n\n### 反模式 4：导览内容基于本地缓存而非知识库实际状态\n\n**问题**：本地 `.md` 文件可能被其他任务覆盖或已过时，基于本地文件生成的导览与知识库实际文章不匹配。\n\n**正确做法**：导览笔记的文章列表必须从 `get_knowledge_list` 返回的实际文件生成。\n\nFile v5.0.2:references/lint.md\n\n# Lint（健康检查）\n\n> Karpathy 三大操作之二。完整覆盖知识库的\"健康体检\"。\n> 核心理念：**通过定期检查防止 wiki 衰败**，类比代码世界的 `eslint`。\n\n## 1. 4 类标准检查\n\n| 检查 | 内容 | 触发频率 |\n|------|------|---------|\n| **结构检查** | 文件夹散落、空文件夹、文件错放 | 每周 1 次 |\n| **矛盾检查** | 不同导览对同一概念说法冲突 | 每月 1 次 |\n| **孤立检查** | 导览未被任何文件引用 | 每月 1 次 |\n| **过期检查** | 低 confidence + 长期未更新 | 每月 1 次 |\n\n详见 [maintenance.md 第 6.5 节](maintenance.md)\n\n## 2. 触发条件\n\n| 触发词 | 行为 |\n|--------|------|\n| \"检查知识库\" / \"知识库体检\" | 完整 4 类检查 |\n| \"审查标签\" / \"整理标签\" | 仅标签审查（属于结构检查的子集） |\n| \"健康检查\" | 完整 4 类检查 |\n\n## 3. 结构检查（Structure）\n\n### 3.1 检查项\n\n| 项目 | 检查方法 | 输出 |\n|------|---------|------|\n| 散落文件 | `get_knowledge_list` 不带 `folder_id`，找 `parent_folder_id == ROOT` 的文件 | 文件清单 |\n| 空文件夹 | `get_knowledge_list` 找 `media_type=99` 且子项为空的文件夹 | 文件夹清单 |\n| 文件错放 | LLM 比对文件标签和文件夹主题 | 错放文件清单 |\n\n详见 [folder-organization.md](folder-organization.md)\n\n### 3.2 自动建议\n\n```\n检测到 35 个散落文件\n推荐归类：\n- AkShare/BaoStock... → 数据工具与入门/\n- 情绪... → 金融情绪分析/\n- AI 量化... → AI 量化与深度学习/\n```\n\n## 4. 矛盾检查（Contradiction）\n\n### 4.1 检查项\n\n- 不同导览对同一概念说法冲突\n- 同一文件夹内文件观点冲突\n\n### 4.2 检查方法\n\n```python\ndef check_contradictions(guides):\n \"\"\"LLM 读取多个导览，识别冲突\"\"\"\n # 1. 提取所有导览的\"核心思想\"和\"关键论断\"\n claims_by_guide = {}\n for guide in guides:\n claims_by_guide[guide.id] = extract_key_claims(guide)\n\n # 2. LLM 配对比较\n contradictions = []\n guide_ids = list(claims_by_guide.keys())\n for i, id_a in enumerate(guide_ids):\n for id_b in guide_ids[i+1:]:\n pair_contradictions = llm_compare_claims(\n claims_by_guide[id_a],\n claims_by_guide[id_b]\n )\n contradictions.extend(pair_contradictions)\n\n return contradictions\n\n\ndef llm_compare_claims(claims_a, claims_b):\n prompt = f\"\"\"比较以下两组论断，识别直接冲突的项。\n\n导览 A 的论断：\n{format_claims(claims_a)}\n\n导览 B 的论断：\n{format_claims(claims_b)}\n\n如果存在直接矛盾（同一概念，结论互斥），返回：\n{{\n \"topic\": \"<冲突的概念>\",\n \"claim_a\": \"<导览 A 的说法>\",\n \"claim_b\": \"<导览 B 的说法>\",\n \"severity\": \"high | medium | low\",\n \"suggestion\": \"<如何解决>\"\n}}\n\n如果没有冲突，返回 {{\"topic\": null}}\"\"\"\n # 调用 LLM...\n```\n\n### 4.3 示例\n\n```\n矛盾：关于\"因子有效性衰减\"\n- 导览 A（因子与资产定价 v2.3）: \"Fama-French 三因子模型在 A 股市场有效性较弱\"\n- 导览 B（量化策略 v1.5）: \"Fama-French 三因子在 A 股仍有显著 alpha\"\n- 严重度: medium\n- 建议: 检查两份资料的发表时间和市场环境，可能需要分时段讨论\n```\n\n## 5. 孤立检查（Orphan）\n\n### 5.1 检查项\n\n| 维度 | 检查内容 |\n|------|---------|\n| 孤立导览 | 该导览的 `related_guides[]` 为空，且没有文件在 sources[] 中 |\n| 孤立文件 | 文件未被任何导览的 sources[] 引用 |\n| 孤立章节 | 导览某个章节只有 1 篇文章 |\n\n### 5.2 检查方法\n\n```python\ndef check_orphans(kb_id, all_guides, all_files):\n orphans = {\"guides\": [], \"files\": []}\n\n # 1. 找出被任何导览引用的文件\n referenced_files = set()\n for guide in all_guides:\n for src in guide.sources:\n referenced_files.add(src.media_id)\n\n # 2. 找出孤立文件（未被任何导览引用）\n for file in all_files:\n if file.media_id not in referenced_files:\n orphans[\"files\"].append(file)\n\n # 3. 找出孤立导览（没有 related_guides[]，也没有任何 sources 引用）\n for guide in all_guides:\n if not guide.related_guides and not any(\n f for f in all_files if any(src.media_id == f.media_id for src in guide.sources)\n ):\n orphans[\"guides\"].append(guide)\n\n return orphans\n```\n\n### 5.3 修复建议\n\n```\n孤立文件：\n- 《文章A》.pdf — 未被任何导览引用\n - 建议：纳入\"主题导览：XXX\"（相关度 0.85）\n - 或：新建独立导览（如果内容丰富）\n\n孤立导览：\n- 📖 主题导览：XXX — 没有相关导览也没有引用文件\n - 建议：补充 related_guides[]，加入交叉引用\n```\n\n## 6. 过期检查（Freshness）\n\n### 6.1 检查项\n\n| 项目 | 阈值 | 标记 |\n|------|------|------|\n| 低 confidence 导览 | confidence == \"low\" | 待更新 |\n| 长期未更新（medium） | updated > 30 天前 AND confidence == \"medium\" | 可能过时 |\n| 关键文章已更新但导览未跟进 | 文件 updated > 导览 updated | 待同步 |\n\n### 6.2 检查方法\n\n```python\ndef check_freshness(guides, files):\n from datetime import datetime, timedelta\n\n today = datetime.now()\n stale = []\n\n for guide in guides:\n days_since_update = (today - guide.updated).days\n\n # 规则 1: 低 confidence\n if guide.confidence == \"low\":\n stale.append((guide, \"low_confidence\", \"高优先级\"))\n\n # 规则 2: medium + 长期未更新\n elif guide.confidence == \"medium\" and days_since_update > 30:\n stale.append((guide, \"stale_medium\", \"中优先级\"))\n\n # 规则 3: 关键文章已更新但导览未跟进\n guide_files = [f for f in files if any(\n src.media_id == f.media_id for src in guide.sources\n )]\n newer_files = [f for f in guide_files if f.updated > guide.updated]\n if newer_files:\n stale.append((guide, \"files_updated_guide_stale\", \"高优先级\"))\n\n return stale\n```\n\n## 7. Lint 输出：标准报告\n\n### 7.1 报告路径\n\n```\noutputs/lint-YYYY-MM-DD.md\n```\n\n例如：`outputs/lint-2026-09-28.md`\n\n### 7.2 报告模板\n\n```markdown\n# Wiki 健康检查报告\n\n**生成时间**：2026-09-28\n**知识库**：[知识库名称] (kb_id: ...)\n**检查导览数**：X 个\n**检查文件数**：Y 个\n\n## 总体评分\n\n| 维度 | 评分 | 状态 |\n|------|:----:|:----:|\n| 结构 | ⭐⭐⭐⭐ | 良好 |\n| 矛盾 | ⭐⭐⭐ | 一般 |\n| 孤立 | ⭐⭐⭐⭐ | 良好 |\n| 过期 | ⭐⭐⭐ | 一般 |\n| **综合** | **⭐⭐⭐⭐** | **良好** |\n\n## 1. 结构检查\n\n- 散落文件：X 个\n- 空文件夹：X 个\n- 文件错放：X 个\n\n**修复建议**：\n- [P1] 调用 `move_knowledge` 把 X 个散落文件归类\n- [P2] 删除/重组 X 个空文件夹\n\n## 2. 矛盾检查\n\n- 矛盾论断对：X 对\n\n**示例**：\n- [导览A] vs [导览B] 对 \"XXX\" 概念说法冲突\n - A: ...\n - B: ...\n - 建议: ...\n\n## 3. 孤立检查\n\n- 孤立导览：X 个\n - [导览1]: 建议补充交叉引用\n- 孤立文件：X 个\n - [文件1]: 建议纳入相关导览\n\n## 4. 过期检查\n\n- 低 confidence 导览：X 个\n- 长期未更新（medium）：X 个\n- 关键文章已更新但导览未跟进：X 个\n\n**修复建议**：\n- [P0] 更新低 confidence 导览：XXX\n- [P1] 跟进已更新但导览未更新的：YYY\n\n## 总体改进建议\n\n按优先级排序：\n1. [P0] ...\n2. [P1] ...\n3. [P2] ...\n```\n\n## 8. 自动 Lint 调度（可选）\n\n### 8.1 每周定时\n\n```bash\n# 每周日 0 点跑 Lint，输出到 outputs/lint-YYYY-MM-DD.md\n0 0 * * 0 cd /workspace && \\\n python3 lint.py --kb_id --output outputs/lint-$(date +%Y-%m-%d).md\n```\n\n### 8.2 历史对比\n\n```bash\n# 比较最近 4 周的 Lint 报告\ndiff outputs/lint-2026-09-07.md outputs/lint-2026-09-28.md\n```\n\n跟踪指标：\n- 散落文件数变化（应持续下降）\n- 矛盾数变化（应 < 5）\n- 孤立文件率变化（应 < 20%）\n\n## 9. 与 Ingest 的协同\n\n| Lint 发现 | 触发 Ingest |\n|---------|------------|\n| 低 confidence 导览 | 自动增量更新（带 confidence 提升） |\n| 孤立文件 | 建议纳入相关导览 |\n| 文件错放 | 调用 `move_knowledge` 归类 |\n| 矛盾论断 | 用户确认后增量更新相关导览 |\n\n**核心理念**：Lint 不只是发现问题，而是**驱动 Ingest 解决问题**。\n\nFile v5.0.2:references/maintenance.md\n\n# 维护与迭代（阶段 6 详细）\n\n知识库需要\"活\"起来，而非一次性建好就搁置。\n\n## 6.1 健康检查（\"体检\"）\n\n**触发词**：\"检查知识库\"、\"知识库体检\"\n\n### 检查项\n\n1. 扫描整个知识库，检查：\n - 是否有空文件夹（有待补充内容）\n - 是否有文件放错了分类\n - 主题之间是否有信息矛盾或重复\n - 是否有重要概念缺少覆盖\n2. 生成健康检查报告，列出发现的问题和修复建议\n3. 用户确认后执行修复\n\n### 报告模板\n\n```markdown\n## 知识库健康检查报告\n\n### 文件夹结构\n- 空文件夹：X 个\n - [列出文件夹名]\n- 散落文件：X 个\n - [列出文件名]\n\n### 内容覆盖\n- 核心概念覆盖度：X%\n- 缺少覆盖的概念：[列出]\n\n### 重复与矛盾\n- 重复文章：X 组\n - [列出]\n- 矛盾信息：X 处\n - [列出位置]\n\n### 修复建议\n1. [优先级 P0] ...\n2. [优先级 P1] ...\n```\n\n## 6.2 知识补充\n\n**触发词**：\"补充知识库\"、\"更新知识库\"\n\n### 流程\n\n1. 识别知识库中的薄弱环节（空文件夹、内容过时的主题）\n2. 通过联网搜索补充最新资料\n3. 将新资料编译后归入对应位置\n4. 更新相关的交叉引用和索引\n5. **更新知识导览**：触发增量更新流程（参见 [incremental-update.md](incremental-update.md)）\n\n## 6.3 输出与回流\n\n用户可基于 Wiki 生成各类产出（研究报告、总结、幻灯片大纲等），这些产出保存回笔记本后，实现知识的\"增量训练\"——系统持续演化，而非一次性消耗。\n\n### 典型产出\n\n- 研究报告（用 [ima-report skill]）\n- 总结笔记（用 [ima-note skill]）\n- 播客（用 [ima-podcast skill]）\n- PPT（用 [ima-ppt skill]）\n\n### 回流机制\n\n每次产出的\"知识副产品\"都应回流到知识库：\n1. 产出的笔记 → 添加到对应主题文件夹\n2. 在主题导览的\"相关主题\"中补充\n3. 给文件打主题标签\n\n## 6.4 标签审查\n\n**触发词**：\"审查标签\"、\"整理标签\"\n\n详见 [tagging.md](tagging.md) 第 7 节。\n\n### 检查项\n\n- 命名规范（无近似标签）\n- 孤儿标签（关联文件数 = 0）\n- 弱标签（关联文件数 < 3）\n- 热门标签（关联文件数 > 100）\n\n### ⚠️ 破坏性操作\n\n详见 [security.md](security.md)：\n- `tag_delete` 不可逆\n- `tag_rename` 会自动合并\n- 必须先列影响文件数 + 用户显式确认\n\n## 6.5 维护节奏建议\n\n| 维护类型 | 频率 | 触发条件 |\n|---------|------|---------|\n| 健康检查 | 每月 1 次 | 时间周期 |\n| 知识补充 | 按需 | 用户上传新资料 |\n| 标签审查 | 每季度 1 次 | 标签数 > 100 时 |\n| 增量更新导览 | 每周 1 次 | 文件数增加 > 10% |\n| 深度重构 | 每半年 1 次 | 主题边界变化 |\n\nFile v5.0.2:references/reference.md\n\n# Wiki 编译参考（v5.0.0 重构版）\n\n> 索引页：基于 Karpathy 三大操作重新组织。从这里跳转到各专题详情。\n\n## 🎯 核心理念\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n\n## 📚 Karpathy 三大操作文档\n\n| 操作 | 文档 | 适用场景 |\n|------|------|---------|\n| **Ingest** | [ingest.md](ingest.md) | 资料入库、编译导览、自动级联 |\n| **Lint** | [lint.md](lint.md) | 4 类标准检查（结构/矛盾/孤立/过期）|\n| **Schema** | [schema.md](schema.md) | 强制 frontmatter 契约 |\n\n## 📚 子流程文档\n\n| 文档 | 适用场景 | 说明 |\n|------|---------|------|\n| [folder-organization.md](folder-organization.md) | Ingest 前置 | 知识库结构诊断 + 文件归类 |\n| [tagging.md](tagging.md) | Ingest 子任务 | 标签设计 + 应用 + 审查 |\n| [security.md](security.md) | 全流程 | 破坏性操作保护 |\n| [api-reference.md](api-reference.md) | 全流程 | IMA OpenAPI 端点 + 错误码 |\n| [guide-template.md](guide-template.md) | Ingest 子任务 | 主题导览 4 章节结构 + 写作规范 |\n| [versioning.md](versioning.md) | Ingest 子任务 | 主题导览的版本控制 |\n| [write-and-verify.md](write-and-verify.md) | Ingest 子任务 | 写入笔记 + 验证流程 |\n| [link-handling.md](link-handling.md) | Ingest 子任务 | 链接特性预获取 + 链接策略 |\n| [troubleshooting.md](troubleshooting.md) | 全流程 | 常见错误 + 解决方案 |\n| [cases/quantitative-investing.md](cases/quantitative-investing.md) | 案例 | 量化投资知识库试跑经验 |\n\n## 🎯 Karpathy 三大操作 vs wiki-compiler 7 阶段（v4.x）\n\n| Karpathy 三大操作 | wiki-compiler v4.x 7 阶段 | v5.0.0 重构 |\n|------------------|---------------------------|------------|\n| Ingest（摄取）| 阶段 1+2+3+4+5 | 6 个子任务：Collect/Check/Link/Compile/Write/Cascade |\n| Lint（健康检查）| 阶段 6（部分）| 4 类标准检查 |\n| Schema（契约）| （软约束）| 强制 frontmatter |\n\n## 🚀 快速跳转\n\n- 不知道从哪开始？→ 看 SKILL.md 的\"快速开始\"章节\n- 触发词困惑？→ SKILL.md \"核心理念\"章节\n- 遇到错误？→ [troubleshooting.md](troubleshooting.md)\n- 不知道 API 怎么调用？→ [api-reference.md](api-reference.md)\n- 担心破坏性操作？→ [security.md](security.md)\n- 想看实际案例？→ [cases/quantitative-investing.md](cases/quantitative-investing.md)\n- 主题导览怎么写？→ [guide-template.md](guide-template.md) + [schema.md](schema.md)\n\n## 📊 与 Karpathy 原始模式的对应\n\n| Karpathy 原始模式 | wiki-compiler v5.0 实现 |\n|------------------|----------------------|\n| `CLAUDE.md` 模式核心 | `references/schema.md` |\n| frontmatter 约定 | 强制 frontmatter 字段 |\n| `[[wikilinks]]` 引用 | `related_guides[]` 数组 |\n| `git log` 审计 | `changelog[]` 数组 |\n| 资料溯源 | `sources[]` 数组 |\n| LLM 把握度 | `confidence` 字段 |\n| 三层架构（raw/wiki/CLAUDE.md）| IMA 知识库 / 主题导览 / Schema 文档 |\n| 三大操作（Ingest/Query/Lint）| Ingest / 不归我管 / Lint |\n\n## 🔄 Karpathy vs IMA 平台差异\n\n| 维度 | Karpathy 原始 | IMA 平台 |\n|------|--------------|---------|\n| 存储 | 本地 Markdown 文件 | 云端笔记 + 知识库 |\n| 触发 | 手动操作 UI | 自然语言触发词 |\n| 版本控制 | Git 提交 | 笔记版本号 + changelog |\n| 反向链接 | `[[wikilinks]]` 自动建立 | `related_guides[]` 手动维护 |\n| 删除笔记 | 完全支持 | ❌ 不支持（需客户端） |\n| 向量搜索 | LanceDB（可选） | 平台内置（不归我管）|\n\n## 📖 核心理念速查\n\n### 传统 RAG vs Karpathy LLM Wiki\n\n| 特性 | Karpathy LLM Wiki | 传统 RAG |\n|------|------------------|----------|\n| **状态** | 有状态——知识持续积累 | 无状态——每次查询独立 |\n| **基础设施** | 一堆 `.md` 文件 | 向量库 + embedding |\n| **交叉引用** | 预建（`related_guides[]`）| 临时发现 |\n| **可追溯性** | 强（每个论断追到 raw）| 弱（chunk 级引用） |\n| **规模甜区** | < 100-200 个源 | 百万级文档 |\n\n### 文件夹设计模式\n\n详见 [folder-organization.md 第 6 节](folder-organization.md)\n\n**模式 A：扁平**（中等规模）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2\n└── 文件夹 3\n```\n\n**模式 B：2 层嵌套**（复杂领域）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2（复杂主题）\n│ ├── 子文件夹 A\n│ ├── 子文件夹 B\n│ └── 子文件夹 C\n└── 文件夹 3\n```\n\n### 标签与文件夹的协同\n\n详见 [folder-organization.md 第 7 节](folder-organization.md) 和 [tagging.md](tagging.md)\n\n| 维度 | 文件夹 | 标签 |\n|------|:---:|:---:|\n| 主导维度 | 主题分类 | 多维关联 |\n| 结构 | 树状（一文件一父）| 网状（一文件多标签）|\n| 人类友好 | 高（导览）| 低（API）|\n| 机器友好 | 低 | 高 |\n\n**核心原则**：\n- 职责不重叠：文件夹负责\"内容组织\"，标签负责\"维度标记\"\n- 互为补充：标签给文件夹扩展维度，文件夹给标签赋予语义\n- 低耦合：任一失效，另一方仍可独立工作\n\n## 📝 文档维护说明\n\n**当前版本**：v5.0.0（2026-09-28）\n\n**重构原则**：\n- Karpathy 三大操作作为顶层架构\n- 子流程文档按 Ingest 子任务组织\n- Lint 和 Schema 各自独立\n\n**演进原则**：\n- 新增功能 → 在对应 Karpathy 操作下扩展\n- 避免重新发明轮子（不归我管的由 IMA 处理）\n\nArchive v5.0.1: 19 files, 55298 bytes\n\nFiles: references/api-reference.md (15955b), references/cases/quantitative-investing.md (5448b), references/folder-organization.md (7169b), references/guide-template.md (5737b), references/incremental-update.md (3046b), references/ingest.md (12863b), references/link-handling.md (5230b), references/lint.md (8436b), references/maintenance.md (2784b), references/reference.md (5668b), references/schema.md (7314b), references/security.md (7279b), references/tagging.md (5136b), references/troubleshooting.md (6727b), references/versioning.md (2096b), references/write-and-verify.md (4794b), skill-card.md (2121b), SKILL.md (11638b), _meta.json (132b)\n\nFile v5.0.1:SKILL.md\n\n---\nname: wiki-compiler\nversion: 5.0.0\ndescription: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。\nlicense: MIT-0\nauthor: cookfish\nlast_updated: 2026-09-28\nhomepage: https://github.com/cookfish/wiki-compiler\n\nmetadata:\n openclaw:\n emoji: 🔧\n requires:\n primaryEnv: IMA_OPENAPI_APIKEY\n env:\n - IMA_OPENAPI_CLIENTID\n - IMA_OPENAPI_APIKEY\n---\n\n# 知识库 Wiki 编译器 v5.0.0\n\n> **技能版本**：v5.0.0 | 最后更新：2026-09-28 | 上一版：v4.1.0\n> **核心理念**：基于 Karpathy 的 LLM Wiki 模式 —— **\"Human curates, LLM maintains\"**\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n> **IMA 平台依赖**：需配置 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。获取方式：访问 https://ima.qq.com/agent-interface\n\n---\n\n## 快速开始\n\n### 场景 1：建新知识库\n用户：\"建一个关于 XXX 的知识库\" → **Ingest**（完整流水线）\n\n### 场景 2：导入新资料\n用户：\"导入这个网页\" / \"上传这个 PDF\" → **Ingest**（自动级联）\n\n### 场景 3：整理散落文件\n用户：\"按文件夹归类\" / \"整理散落文件\" → **Ingest 前置**（Folder Pre-Ingest）\n\n### 场景 4：维护知识库\n用户：\"检查知识库\" / \"健康检查\" → **Lint**（4 类标准检查）\n\n### 场景 5：增量更新导览\n用户：\"更新导览\" / \"导览新增了 N 篇文章\" → **Ingest**（增量模式）\n\n### 场景 6：标签管理\n用户：\"给知识库打标签\" / \"审查标签\" → **Ingest** 子任务（Schema 辅助）\n\n---\n\n## 核心理念\n\n### Karpathy 三大操作\n\n| 操作 | 职责 | 触发词 | 详见 |\n|------|------|--------|------|\n| **Ingest**（摄取） | 资料入库，编译/更新导览，级联多个相关导览 | \"建知识库\"\"导入网页\"\"上传文件\"\"更新导览\" | [ingest.md](references/ingest.md) |\n| **Lint**（健康检查） | 4 类标准检查：结构/矛盾/孤立/过期 | \"检查知识库\"\"健康检查\" | [lint.md](references/lint.md) |\n| **Schema**（契约） | 强制 frontmatter 规范（自动应用） | （无需用户触发）| [schema.md](references/schema.md) |\n\n**Query（查询）由 IMA search/fetch 完成，不归本 skill 管。**\n\n### 为什么这样设计\n\n- **Ingest**：知识库是\"会复利的资产\"，不是\"可检索的语料库\"\n- **Lint**：通过定期检查防止 wiki 衰败（类比代码世界的 `eslint`）\n- **Schema**：没有 schema，LLM 会天马行空；有了 schema，LLM 才守纪律\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n\n---\n\n## Ingest（摄取）\n\n### 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n### 关键子任务\n\n| 子任务 | 核心动作 | API |\n|--------|---------|-----|\n| **Collect** | 上传文件 / 导入网页 / 拉取已有 | `upload_file`, `import_urls`, `get_knowledge_list` |\n| **Check** | 搜索旧导览 | `search_note`（标题=\"主题导览\"）|\n| **Link** | 获取链接特性表 | `export_media_for_ima_sandbox` |\n| **Compile** | 新建/增量更新 | LLM 5 步法或 6 步法 |\n| **Write** | 创建/追加/编辑笔记 | `import_doc`, `append_doc`, `update_note` |\n| **Cascade** | **级联更新多个相关导览**（知识复利）| `search_note` + LLM 评分 |\n\n详见 [references/ingest.md](references/ingest.md)\n\n### ⚠️ Karpathy 核心机制：知识复利\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）\n\n```\n新文件被上传\n ↓\n计算与每个现有导览的相关性（标签粗筛 + LLM 精评）\n ↓\n相关度 > 0.7 的导览 → 加入\"待更新列表\"\n ↓\n逐个执行增量更新（append_doc）\n ↓\n记录到 changelog（标 [Ingest 日期]）\n```\n\n**示例**：上传\"遗传算法在量化交易中的应用\" → 1 个导览更新（v1.5 → v1.6）+ 0 个级联。\n\n---\n\n## Lint（健康检查）\n\n### 4 类标准检查（Karpathy 完整版）\n\n| 检查 | 触发频率 | 检查内容 |\n|------|---------|---------|\n| **结构** | 每周 | 散落文件、空文件夹、文件错放 |\n| **矛盾** | 每月 | 不同导览对同一概念说法冲突 |\n| **孤立** | 每月 | 导览未被任何文件引用 |\n| **过期** | 每月 | 低 confidence + 长期未更新 |\n\n详见 [references/lint.md](references/lint.md)\n\n### 触发词\n\n- \"检查知识库\" / \"知识库体检\" / \"健康检查\"\n- \"审查标签\" / \"整理标签\"（仅标签部分）\n\n### 输出\n\n`outputs/lint-YYYY-MM-DD.md` —— 包含总体评分、4 类检查详情、修复建议。\n\n---\n\n## Schema（契约）\n\n### 强制 frontmatter（每篇主题导览）\n\n```yaml\n---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本\nsources:\n - [《文章1》](URL)\nrelated_guides:\n - [《另一导览》](URL)\n---\n```\n\n详见 [references/schema.md](references/schema.md)\n\n### 核心字段说明\n\n| 字段 | Karpathy 对应 | 作用 |\n|------|-------------|------|\n| `confidence` | LLM 把握度 | 让用户知道哪些导览可信 |\n| `sources[]` | 资料溯源 | 每个论断追到 raw（防止幻觉）|\n| `related_guides[]` | `[[wikilinks]]` | 网状结构而非树状 |\n| `changelog[]` | `git log` | 审计追踪 |\n| `version` | 语义化版本 | 变更管理 |\n\n---\n\n## 安全准则（破坏性操作）\n\n| 操作 | 风险 | 保护 |\n|------|------|------|\n| ~~`delete_note`~~ | ❌ API 不支持 | 客户端手动 |\n| `tag_delete` | 关联自动解除 | 列影响文件→用户确认 |\n| `tag_rename` | 重名自动合并 | 检查新名→用户确认 |\n| `move_knowledge` | 标签可能清空 | 备份标签→移动后恢复 |\n\n详见 [references/security.md](references/security.md)\n\n---\n\n## API 速查\n\n### 核心端点\n\n| 功能 | 端点 |\n|------|------|\n| 上传文件 | `openapi/wiki/v1/upload_file` |\n| 导入网页 | `openapi/wiki/v1/import_urls` |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` |\n| 重命名 | `openapi/wiki/v1/rename_knowledge` |\n| 添加标签 | `openapi/wiki/v1/tag_add` |\n| 列出知识库 | `openapi/wiki/v1/get_knowledge_list` |\n| 获取媒体信息 | `openapi/wiki/v1/get_media_info` |\n| 创建笔记 | `openapi/note/v1/import_doc` |\n| 追加笔记 | `openapi/note/v1/append_doc` |\n| 导出笔记 | `openapi/note/v1/export_note` |\n| 搜索笔记 | `openapi/note/v1/search_note` |\n| 按 block 编辑 | `openapi/note/v1/update_note` |\n| ~~删除笔记~~ | ❌ API 不支持 |\n\n详见 [references/api-reference.md](references/api-reference.md) 和 [references/troubleshooting.md](references/troubleshooting.md)\n\n---\n\n## 编译质量标准\n\n1. **原子化**：每个知识节点围绕单一主题\n2. **关联性**：知识卡片之间通过超链接形成网状结构\n3. **大纲化**：每个卡片内部有完整的章节结构\n4. **可溯源**：每篇文章有来源出处（sources[]）\n5. **可读性**：结构清晰、信息密度适中\n6. **confidence 标注**：每个论断有可信度（Karpathy 特色）\n\n---\n\n## 重要提醒\n\n- **预获取链接是编译前的必做步骤**（Link 子任务）—— 先建立链接特性表，再基于表编译\n- **增量优先**——每次 Ingest 前必须 Check 旧版本，优先增量更新而非重新创建\n- **schema 强制**——所有导览必须遵守 [references/schema.md](references/schema.md)\n- **级联需确认**——Cascade 是 Karpathy 核心机制，但首次使用应告知用户\n- **导出笔记是 COS URL**——`export_note` 返回 `content_url`（3 小时时效），需二次下载\n- **删除笔记不支持**——IMA 平台当前 API 不支持，请用户在客户端操作\n\n---\n\n## 变更日志\n\n### v5.0.0 (2026-09-28) - Karpathy 重构（major 升级）\n\n**架构重组**：\n- 7 阶段 → Karpathy **三大操作**（Ingest / Lint / Schema）\n- SKILL.md 精简到 ~450 行（v4.1.0 是 499 行）\n- 新增 3 个核心 references：ingest.md / lint.md / schema.md\n- 引入 Karpathy 核心机制：**知识复利（Cascade 级联更新）**\n\n**Schema 强制化**：\n- 主题导览 frontmatter 强化：必填 confidence / sources[] / related_guides[] / changelog\n- confidence 字段：每篇导览标注可信度（high/medium/low）\n- sources[] 强制：每个论断追到 raw 资料\n\n**Ingest 增强**：\n- 新增 Cascade（级联）算法：一次操作影响多个导览\n- 新增 append_doc（增量追加，不重建）\n- 新增 update_note（按 block 编辑）\n\n**Lint 强化**：\n- 从\"基础健康检查\"升级到 Karpathy 标准的 4 类检查（结构/矛盾/孤立/过期）\n- Lint 报告输出到 `outputs/lint-YYYY-MM-DD.md`\n\n**触发词保持 11 个不变**\n\n**复杂度反思**：\n- 之前 v4.2.0 加 14 项功能会让 SKILL.md 增长到 700+ 行\n- v5.0.0 重组为三大操作，结构更清晰\n- 11 个触发词保持不变，description 不变（向后兼容）\n\n### v4.1.0 (2026-09-28) - IMA 原生格式升级\n\n- 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组\n- 删除笔记 API 修正：v4.0.0 附录 B 的 `delete_note` 安全删除流程已失效\n\n### v4.0.0 (2026-07-08) - 完全重构\n\n- 7 阶段法操作流程\n\n### v3.0.2 (2026-07-08) - 描述优化\n### v3.0.1 (2026-07-08) - 安全修复\n### v3.0.0 (2026-05-13) - 多层结构\n### v1.0 (2026-05-07) - 初版\n\n---\n\n## 文档结构\n\n```\nwiki-compiler/\n├── SKILL.md ← 本文件（操作手册）\n└── references/\n ├── reference.md ← references/ 索引\n ├── ingest.md ← 🆕 Ingest 完整操作 + 级联算法\n ├── lint.md ← 🆕 Lint 4 类标准检查\n ├── schema.md ← 🆕 强制 frontmatter 契约\n ├── folder-organization.md ← Ingest 前置：文件夹整理\n ├── tagging.md ← Ingest 子任务：标签管理\n ├── security.md ← 破坏性操作保护\n ├── api-reference.md ← API 速查\n ├── guide-template.md ← 笔记撰写规范（含新 frontmatter）\n ├── versioning.md ← 版本控制\n ├── write-and-verify.md ← 写入与验证\n ├── link-handling.md ← 链接处理\n ├── troubleshooting.md ← 故障排查\n └── cases/\n └── quantitative-investing.md ← 实战案例\n```\n\n> ⚠️ **IMA 平台注意**：IMA 平台会周期性向 `/sandbox/workspace/skills//` 添加软链接 ` -> /root/.skills//`，可能导致打包时混入旧版本。打包前务必用 `find ... -type l` 检查并清理。\n> 详见 [references/troubleshooting.md](references/troubleshooting.md) 第 10 节。\n\nFile v5.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7b60cvvedv8jkxs5gy3m9c0d837e9f\",\n \"slug\": \"wiki-compiler\",\n \"version\": \"5.0.1\",\n \"publishedAt\": 1790595762429\n}\n\nFile v5.0.1:references/api-reference.md\n\n# API 速查\n\n> IMA OpenAPI 完整参考（基于 ima-knowledge 和 ima-note 最新文档对齐）。\n> 所有调用都依赖 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。\n\n## 1. 环境变量配置\n\n```bash\n# 必需的环境变量\nexport IMA_OPENAPI_CLIENTID=\"你的ClientID\"\nexport IMA_OPENAPI_APIKEY=\"你的APIKey\"\n\n# 获取地址：https://ima.qq.com/agent-interface\n```\n\n## 2. 通用调用函数（Python）\n\n```python\nimport urllib.request\nimport json\n\ndef ima_api(path, data=None):\n \"\"\"IMA OpenAPI 通用调用函数\"\"\"\n headers = {\n \"ima-openapi-clientid\": \"你的ClientID\",\n \"ima-openapi-apikey\": \"你的APIKey\",\n \"Content-Type\": \"application/json\"\n }\n url = f\"https://ima.qq.com/{path}\"\n req = urllib.request.Request(\n url,\n data=json.dumps(data or {}).encode('utf-8'),\n headers=headers,\n method=\"POST\"\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n return json.loads(resp.read().decode(\"utf-8\"))\n```\n\n## 3. 知识库 API（wiki/v1/*）\n\n### 3.1 读取类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 搜索知识库（含角色信息） | `openapi/wiki/v1/search_knowledge_base` | `query`, `cursor`, `limit` (1-20) | **推荐** 替代不存在的 `list_knowledge_bases` |\n| 列出知识库内容 | `openapi/wiki/v1/get_knowledge_list` | `knowledge_base_id`, `cursor`, `limit` (1-50) | 不带 folder_id 列出根目录 |\n| 按名称定位文件/文件夹 | `openapi/wiki/v1/search_knowledge` | `query`, `knowledge_base_id` | 获取位置和类型信息 |\n| 发现广场公开知识库 | `openapi/wiki/v1/search_knowledge_base_in_square` | `question`, `cursor`, `limit` (1-20) | 与 search_knowledge_base 不同 |\n| 导出媒体内容（COS URL）| `openapi/wiki/v1/export_media_for_ima_sandbox` | `media_id` | **返回 COS 链接需二次下载** |\n\n### 3.2 写入类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 创建知识库 | `openapi/wiki/v1/create_knowledge_base` | `name`, `type` (1001个人/1002共享/1004订阅) | - |\n| 更新知识库信息 | `openapi/wiki/v1/update_knowledge_base_basic_info` | `id`, `update_fields` | 可选更新字段：1-名称, 2-封面, 3-简介, 4-推荐问题 |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` | `knowledge_base_id`, `name`, `parent_folder_id` | - |\n| 重命名文件/文件夹 | `openapi/wiki/v1/rename_knowledge` | `media_id`, `new_name` | - |\n| 置顶/取消置顶 | `openapi/wiki/v1/set_knowledge_top` | `media_id`, `is_top` | - |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` | `src_kb_id`, `dst_kb_id`, `dst_folder_id`, `infos` | **每次最多 10 个文件** |\n| 导入网页链接 | `openapi/wiki/v1/import_urls` | `knowledge_base_id`, `urls[]` | 批量导入 URL |\n| 上传文件 | `openapi/wiki/v1/upload_file` | `knowledge_base_id`, `file` | 走 COS 上传流程 |\n| 把已有笔记加入知识库 | `openapi/wiki/v1/add_knowledge` | `knowledge_base_id`, `media_id` | 虚拟关联（不改 parent_folder_id） |\n\n### 3.3 权限管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 改知识库权限 | `openapi/wiki/v1/update_knowledge_base_permission` | `knowledge_base_id`, `permission` |\n| 加入知识库 | `openapi/wiki/v1/join_knowledge` | `knowledge_base_id` |\n| 改文件访问状态 | `openapi/wiki/v1/update_knowledge_access_status` | `media_id`, `access_status` |\n\n### 3.4 标签管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 给文件打标签 | `openapi/wiki/v1/tag_add` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| 从文件移除标签 | `openapi/wiki/v1/tag_remove` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| 列出标签 | `openapi/wiki/v1/tag_list` | `kb_id`, `cursor`, `limit` (1-100) |\n| 删除标签 | `openapi/wiki/v1/tag_delete` | `kb_id`, `tag_name` |\n| 重命名标签 | `openapi/wiki/v1/tag_rename` | `kb_id`, `old_tag_name`, `new_tag_name` |\n\n## 4. 笔记 API（note/v1/*）\n\n### 4.1 读取类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 搜索笔记 | `openapi/note/v1/search_note` | `search_type` (0=标题/1=正文), `query_info`, `start`, `end` | start-end 差值 ≤ 20 |\n| 列出笔记 | `openapi/note/v1/list_note` | `folder_id`, `sort_type`, `cursor`, `limit` (≤20) | **注意是单数 list_note，不是 list_notes** |\n| 列出笔记本 | `openapi/note/v1/list_notebook` | `cursor`, `limit` | **单数 list_notebook** |\n| 导出笔记 | `openapi/note/v1/export_note` | `note_id`, `target_content_format` (0/1/2) | **返回 COS URL 需二次下载** |\n| 导出笔记 block 结构 | `openapi/note/v1/export_note_blocks` | `note_id` | update_note 的前置步骤 |\n\n### 4.2 写入类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 创建笔记 | `openapi/note/v1/import_doc` | `content_format` (固定 1), `content`, `title`, `folder_id` | 第一行文本会被自动提取为标题 |\n| 追加内容到笔记 | `openapi/note/v1/append_doc` | `note_id`, `content_format`, `content` | 适合短内容直接追加 |\n| 按 block 编辑笔记 | `openapi/note/v1/update_note` | `note_id`, `block_id`, `content` | 需先 export_note_blocks 定位 |\n| 创建笔记本 | `openapi/note/v1/add_notebook` | `name` | **注意是 add_notebook，不是 create_notebook** |\n| 重命名笔记本 | `openapi/note/v1/rename_notebook` | `folder_id`, `new_name` | - |\n| 重命名笔记 | `openapi/note/v1/rename_note` | `note_id`, `new_title` | - |\n| 移动笔记 | `openapi/note/v1/move_notes` | `note_ids[]`, `dst_folder_id` | **复数 move_notes** |\n| push 笔记 | `openapi/note/v1/push_note` | `note_id`, `content_cos_key` | 长内容走 COS 上传路径 |\n| ~~删除笔记~~ | ~~`openapi/note/v1/delete_note`~~ | ❌ **API 已不支持（2026-09）** | 需用户在 IMA 客户端手动删除 |\n\n## 5. 错误代码参考（基于 ima-note api.md）\n\n| code | 名称 | 说明 | 解决方案 |\n|------|------|------|---------|\n| 0 | OK | 成功 | - |\n| 210001 | PARAM_ERROR | 参数错误 | 检查参数值 |\n| 210002 | REQ_WITH_INVALID_UID | 携带无效的 UID | 检查 UID 有效性 |\n| 210003 | SERVICE_ERROR | 服务器内部错误 | 告知用户稍后再试，**无需重试** |\n| 210004 | SPACE_NOT_ENOUGH | 用户空间不够 | 清理空间或升级 |\n| 210005 | NOTE_NOT_OWNER | 不是笔记的作者 | 仅作者可操作 |\n| 210006 | NOTE_IS_DELETE | 笔记已被删除 | 检查 note_id |\n| 210007 | COS_CRED_ERROR | COS 上传凭证出错 | 重试或联系 IMA |\n| 210008 | VERSION_CONFLICT | 版本冲突 | 重新拉取最新版本 |\n| 210009 | CONTENT_SIZE_OVERLOAD | 单篇笔记超限 | **拆分写入** |\n| 210010 | EXIST_GUIDE | 新手引导笔记重复 | 跳过或改名 |\n| 210011 | SHARE_DOC_NOPERM | 共享知识库无权访问 | 联系知识库管理员 |\n| 210012 | USER_IS_DELETE | 用户已注销 | - |\n| 210030 | NOTEBOOK_NAME_EXIST | 笔记本名称重复 | 改名 |\n| 210031 | NOTEBOOK_NUM_LIMIT | 笔记本数量达上限 | 清理 |\n| 210032 | BATCH_EXEC_FAIL | 批量部分失败 | 检查 `data.failed_list` |\n| 210033 | BATCH_EXEC_ALL_FAIL | 批量全部失败 | 重试 |\n| 210034 | PRIVATE_NOTE_NOT_OWNER | 私有笔记非作者 | 无权访问 |\n| 210035 | FOLDER_NOT_EXIST | 笔记本不存在 | 检查 folder_id |\n| 20002 | - | apiKey 超过最大限频 | 降低调用频率 |\n| 20004 | - | apiKey 鉴权失败 | 检查 IMA_OPENAPI_CLIENTID/IMA_OPENAPI_APIKEY |\n\n## 6. 关键 API 详解\n\n### 6.1 `get_knowledge_list`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"cursor\": \"\", \"limit\": 50}'\n```\n\n| 参数 | 必填 | 说明 |\n|------|:----:|------|\n| `knowledge_base_id` | ✅ | 知识库 ID |\n| `cursor` | ✅ | 首次为空字符串，翻页用 `next_cursor` |\n| `limit` | ✅ | 1-50 |\n| `folder_id` | ❌ | 文件夹 ID（不传=根目录）|\n| `tags` | ❌ | 按标签筛选（数组）|\n\n**返回结构**（注意是 `knowledge_list` 不是 `list`）：\n```json\n{\n \"knowledge_list\": [\n {\"media_id\": \"...\", \"title\": \"...\", \"parent_folder_id\": \"...\", \"tags\": [...], \"media_type\": 99},\n ...\n ],\n \"is_end\": false,\n \"next_cursor\": \"...\",\n \"current_path\": [{\"folder_id\": \"...\", \"name\": \"...\"}]\n}\n```\n\n### 6.2 `move_knowledge`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}]\n }'\n```\n\n**注意**：\n- `infos` 最多 10 个文件\n- 返回的 `data.move_results[media_id].ret_code` 表示单文件结果\n\n### 6.3 `tag_add` / `tag_remove`\n\n**`item_name` 必须严格匹配 `get_knowledge_list` 返回的完整标题**（含扩展名和括号内容）。简化标题会导致 **220001** 错误（注意：220001 来自旧文档，实际 IMA 平台可能改用 210001）。\n\n### 6.4 `export_note` 返回 COS URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"\",\"target_content_format\":1}' | python3 -c \"\nimport sys, json, urllib.request\nd = json.load(sys.stdin)\nif d['code'] == 0:\n url = d['data']['content_url']\n req = urllib.request.Request(url)\n resp = urllib.request.urlopen(req)\n print(resp.read().decode('utf-8'))\nelse:\n print(d)\n\"\n```\n\n**关键**：`data.content_url` 是 COS 链接，**约 3 小时时效**，需要二次 `curl` 请求获取内容。\n\n### 6.5 `import_doc` 创建笔记\n\n```bash\n# 第一行文本会被自动提取为笔记标题\npython3 -c \"\nimport json\nwith open('guide_content.md', 'r') as f:\n content = f.read()\nwith open('note_request.json', 'w') as f:\n json.dump({\n 'content_format': 1,\n 'content': content,\n 'title': '📖 主题导览：[主题名称]',\n 'folder_id': '<目标笔记本 ID>'\n }, f, ensure_ascii=False, indent=2)\n\"\n\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/import_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d @note_request.json | python3 -m json.tool\n```\n\n**注意**：`title` 参数会被忽略，**第一行 `content` 文本**会成为标题。\n\n### 6.6 `append_doc` 追加内容\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/append_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\", \"content_format\": 1, \"content\": \"<追加内容>\"}'\n```\n\n### 6.7 `export_note_blocks` + `update_note` 精细编辑\n\n```bash\n# 第一步：获取 block 结构\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note_blocks\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\"}'\n\n# 第二步：按 block_id 修改\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/update_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\", \"block_id\": \"\", \"content\": \"<新内容>\"}'\n```\n\n### 6.8 `search_note` 按标题/正文搜索\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/search_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"search_type\": 0, \"query_info\": {\"title\": \"主题导览\"}, \"start\": 0, \"end\": 20}'\n```\n\n**返回**：\n```json\n{\n \"search_note_infos\": [\n {\n \"note_book_info\": {\n \"note_id\": \"...\",\n \"title\": \"...\",\n \"summary\": \"...\",\n \"note_ext_info\": {\"folder_id\": \"...\", \"folder_name\": \"...\"}\n },\n \"highlightInfo\": {\"doc_title\": \"包含高亮的标题\"}\n }\n ],\n \"is_end\": true,\n \"total_hit_num\": 3\n}\n```\n\n### 6.9 `list_note` 列出笔记\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/list_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"folder_id\": \"\", \"sort_type\": 0, \"cursor\": \"\", \"limit\": 20}'\n```\n\n**注意**：cursor 翻页用偏移量（已获取条目数）。\n\n### 6.10 `export_media_for_ima_sandbox` 获取永久 URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"<文件media_id>\"}'\n```\n\n**返回结构**：\n```json\n{\n \"media_type\": 2,\n \"media_content_url_info\": {\n \"url\": \"https://...\",\n \"headers\": {\"key\": \"value\"} // 如果非空需要传入 header\n }\n}\n```\n\n**`media_type` 速查表**（从 ima-knowledge knowledge_base_read.md 完整版）：\n\n| 值 | 类型 | 链接策略 |\n|----|------|---------|\n| 1 | PDF 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 2 | 网页 | ✅ 获取真实 URL |\n| 3 | Word 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 4 | PPT 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 5 | Excel 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 6 | 公众号文章 | ✅ 获取真实 URL |\n| 7 | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| 9 | 图片 | ⚠️ 标注\"请在知识库查看\" |\n| 11 | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| 12 | QA 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 13 | TXT 文本 | ⚠️ 不内嵌链接，写为纯文本 |\n| 14 | Xmind | ⚠️ 标注\"请在知识库查看\" |\n| 15 | 录音 | ⚠️ 标注\"请在知识库查看\" |\n| 16 | 网页视频 | ⚠️ 标注\"请在知识库查看\" |\n| 17 | 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 18 | 视频 | ⚠️ 标注\"请在知识库查看\" |\n| 19 | 播客 | ⚠️ 标注\"请在知识库查看\" |\n| 20 | HTML | ⚠️ 标注\"请在知识库查看\" |\n| 21 | EPUB 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 99 | 文件夹 | ❌ 不可链接 |\n\n## 7. IMA 平台已知限制（2026-09）\n\n| 操作 | 状态 |\n|------|:----:|\n| ❌ 删除笔记 | API 不支持，需客户端手动 |\n| ❌ 删除知识库 | API 不支持 |\n| ❌ 删除文件夹 | API 不支持 |\n| ❌ 删除文件 | API 不支持 |\n| ✅ 删除标签 | API 支持 |\n| ✅ 修改笔记 frontmatter | API 不支持（创建时设定）|\n| ✅ 向量搜索 | 由 IMA search/fetch 处理，不归本 skill |\n\n---\n\n## 8. v5.0.0 → v5.0.1 变更总结\n\n### 修正的错误\n\n| v5.0.0 错误 | v5.0.1 正确 |\n|------------|------------|\n| `get_media_info` | ❌ 删除（不存在）|\n| `list_knowledge_bases` | `search_knowledge_base` |\n| `list_notebooks` | `list_notebook` |\n| `list_notes` | `list_note` |\n| `create_notebook` | `add_notebook` |\n| `220001` 等旧错误码 | `210001`-`210035` + `20002`/`20004` |\n\n### 补充的缺失端点（11 个）\n\n- `search_knowledge`\n- `search_knowledge_base_in_square`\n- `create_knowledge_base`\n- `update_knowledge_base_basic_info`\n- `rename_knowledge`\n- `set_knowledge_top`\n- `import_urls`\n- `add_knowledge`\n- `update_knowledge_base_permission`\n- `join_knowledge`\n- `update_knowledge_access_status`\n- `move_notes`（note/v1，复数）\n- `push_note`\n- `rename_note`\n- `rename_notebook`\n\nFile v5.0.1:references/cases/quantitative-investing.md\n\n# 实战案例：量化投资知识库\n\n> 基于 2026-06-29 至 2026-07-01 在量化投资知识库（kb_id: `I_49nAThDICNno0gyhjl4dU1zUFtkNWv0X7mhlBQID8=`）的试跑总结。\n\n## 1. 知识库概况\n\n| 维度 | 数据 |\n|------|------|\n| 主题 | 量化投资（因子模型、机器学习、情绪分析等）|\n| 资料类型 | PDF、笔记、公众号文章、网页 |\n| 初始规模 | 35 个根目录散落文件 |\n| 最终规模 | 135 个文件，7 个顶层文件夹 |\n| 标签总数 | 244 个 |\n| 主题导览 | 7 个 |\n\n## 2. 阶段成果\n\n| 阶段 | 文件数 | 散落文件 | 标签 | 主题导览 |\n|------|:------:|:--------:|:----:|:-------:|\n| 初始 | 35 | 35 | 0 | 1 |\n| 演示后 | 36 | 35 | 20 | 1 |\n| 6 导览+30 打标 | 66 | 35 | 264 | 7 |\n| 归类后（move_knowledge）| 101 | 0 | 264 | 7 |\n| 多层归类后（PDF 单独处理）| 135 | 0 | 264 | 7 |\n\n**关键收获**：\n- 35 个根目录文件归类 → 0 散落\n- 14 个父文件夹文件移到子文件夹 → 结构清晰\n- 所有 244 个标签保留（移动文件前无标签，零风险）\n\n## 3. 最终文件夹结构\n\n```\n量化投资/\n├── 数据工具与入门/ （AkShare、聚宽、JQData 等）\n├── 金融情绪分析/ （情绪温度计、市场情绪等）\n├── 因子与资产定价/ （Fama-French、Alpha 因子等）\n├── 高频交易与微观结构/ （HFT、订单流等）\n├── 交易策略与系统/ （策略设计、回测等）\n├── AI 量化与深度学习/ （顶层）\n│ ├── 机器学习理论方法/\n│ ├── 大模型与智能体/\n│ └── 深度学习与预测模型/\n└── 主题导览（位于各文件夹）/\n ├── 📖 主题导览：数据工具与入门\n ├── 📖 主题导览：金融情绪分析\n ├── ...\n```\n\n**特点**：\n- 7 个顶层文件夹\n- AI 量化与深度学习含 3 个子文件夹（多层结构）\n- 父文件夹放主题导览，子文件夹不需要各自导览\n\n## 4. 关键词映射表\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n## 5. 试跑经验教训\n\n### 5.1 `item_name` 必须严格匹配完整标题\n\n完整标题包括扩展名（如 `.pdf`）和括号内容。\n\n```json\n// ❌ 简化标题（失败，code=220001）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易\"}\n\n// ✅ 完整标题（成功）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易 (伊夫-希尔皮斯科) (z-library.sk, 1lib.sk, z-lib.sk).pdf\"}\n```\n\n### 5.2 `limit` 参数范围 (0, 50]\n\n最大 50，超过会返回 51 错误。\n\n### 5.3 API 幂等性\n\n`tag_add` 重复打、`tag_remove` 移除不存在的——均直接返回成功。可放心重试和断点续传。\n\n### 5.4 `tag_remove` 完全可逆\n\n`tag_remove` 后文件 `tags` 字段变为 `[]`，不留痕迹。**`tag_delete` 才是不可逆的**。\n\n### 5.5 媒体类型覆盖建议\n\n试跑中覆盖了 PDF/笔记/公众号/网页（4 种）。未覆盖 Word/PPT/Excel/Markdown/视频/图片等。**真实场景使用前**建议覆盖完整 14 种类型。\n\n### 5.6 标签数量预期\n\n文章级标签每篇 3-5 个，128 篇内容的知识库预计产生 384-640 个标签。**标签总数 > 100 时建议人工审查命名规范**。\n\n### 5.7 `add_knowledge` ≠ `move_knowledge`（最关键）\n\n| 操作 | 行为 | parent_folder_id |\n|------|------|:----------------:|\n| `add_knowledge` | 文件\"展示\"在文件夹中（虚拟关联）| ❌ 不变 |\n| `move_knowledge` | 真正改变 `parent_folder_id` | ✅ 变为目标文件夹 |\n\n**仅调用 `add_knowledge` 不调用 `move`，文件会永远挂在根目录**。\n\n### 5.8 `move_knowledge` 会清空标签\n\n**应对模式**：\n1. 移动前备份标签\n2. 执行 `move_knowledge`\n3. 移动后逐个重新打标\n\n### 5.9 根目录调用 ≠ 知识库全貌\n\n不带 `folder_id` 调 `get_knowledge_list` 会返回**所有项目**（含 7 个文件夹 + 35 个散落文件 + 60 个已分配文件的\"虚拟副本\"）。\n\n**真正判断散落的方法**：比较文件的 `parent_folder_id` 与知识库根目录 ID。\n\n### 5.10 多层文件夹结构诊断\n\n复杂知识库需要**递归扫描**：\n\n```python\nfor folder in root_folders:\n items = get_knowledge_list(folder_id=folder.id)\n sub_folders = [f for f in items if f.type == 99]\n files = [f for f in items if f.type != 99]\n \n for sub in sub_folders:\n sub_items = get_knowledge_list(folder_id=sub.id)\n # 继续递归\n```\n\n判断标准：\n- 父文件夹下的\"直接挂载文件\"如果主题匹配子文件夹，**应该移到子文件夹**\n- 导览应放父级，**不需要**给每个子文件夹单独生成导览\n\nFile v5.0.1:references/folder-organization.md\n\n# 文件夹组织（阶段 0 详细）\n\n> 适用于：知识库结构混乱、文件散落在根目录、需要多层结构整理。\n\n## 0.1 三种\"文件夹\"操作\n\n| 操作 | API | 效果 | 何时使用 |\n|------|-----|------|---------|\n| **创建文件夹** | `create_folder` | 在知识库根目录建一个新文件夹 | 建立分类骨架 |\n| **虚拟归类** | `add_knowledge` | 让文件\"看起来\"在文件夹中（**parent_folder_id 不变**）| 临时展示 |\n| **物理归类** | `move_knowledge` | 真正修改 `parent_folder_id` 为目标文件夹 | 真正整理 |\n\n**关键警告**：\n- `add_knowledge` 创建的是\"虚拟关联\"，**不改变 `parent_folder_id`**\n- 仅用 `add_knowledge` 而不调用 `move_knowledge`，文件永远挂在根目录\n- 根目录调用 `get_knowledge_list` 会返回所有文件（包括已\"虚拟关联\"的），但这不代表它们真正归属于文件夹\n\n## 0.2 诊断流程\n\n### 步骤 1：拉取知识库根目录\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"limit\": 50}'\n```\n\n### 步骤 2：识别散落文件\n\n```python\nROOT_FOLDER_ID = \"<知识库根目录 ID>\" # 通常通过 get_knowledge_base 获取\n\norphans = [f for f in root_items\n if f.get(\"media_type\") != 99\n and f.get(\"parent_folder_id\") == ROOT_FOLDER_ID]\n```\n\n### 步骤 3：递归扫描文件夹层级\n\n对每个文件夹调用 `get_knowledge_list(folder_id=...)`，记录：\n- 子文件夹（`media_type == 99`）\n- 文件数\n- 每个文件的 `parent_folder_id` 是否等于当前 `folder_id`\n\n### 步骤 4：分类汇总\n\n| 状态 | 含义 | 处理方式 |\n|------|------|---------|\n| 文件 `parent_folder_id` 是根目录 | 真正散落 | 用 `move_knowledge` 归类 |\n| 文件 `parent_folder_id` 是文件夹 ID | 已归类 | 仅检查是否需要打标签 |\n| 文件仅在根目录返回但 parent 是文件夹 | 虚拟关联 | 已正确处理 |\n\n## 0.3 诊断输出模板\n\n```markdown\n## 知识库结构诊断报告\n\n### 顶层文件夹\n| 文件夹 | 文件数 | 含子文件夹 |\n|--------|:------:|:----------:|\n| ... | ... | ... |\n\n### 散落文件\n- 共 X 个文件 `parent_folder_id` 是根目录\n- 列出每个文件的标题和推荐目标文件夹\n\n### 多层结构\n- AI 量化与深度学习/\n - 机器学习理论方法/（Y 个文件）\n - 大模型与智能体/（Y 个文件）\n - ...\n\n### 处理建议\n- 散落文件：调用 `move_knowledge` 归类\n- 多层结构：导览放父级，子文件夹不需要各自导览\n```\n\n## 0.4 归类流程\n\n### 步骤 1：列出待归类文件\n\n```python\n# 从诊断报告中获取散落文件\norphans = [(f[\"media_id\"], f[\"title\"]) for f in orphan_files]\n```\n\n### 步骤 2：推荐目标文件夹\n\n关键词匹配模式（参考实战案例）：\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n> 关键词表针对量化投资领域；其他领域需重新设计。\n\n### 步骤 3：批量调用 `move_knowledge`\n\n```bash\n# 移动到目标文件夹（src_kb_id == dst_kb_id 表示知识库内移动）\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}, {\"media_id\": \"\"}]\n }'\n```\n\n**注意**：每次最多 10 个文件，分批调用。\n\n### ⚠️ `move_knowledge` 的副作用\n\n| 副作用 | 说明 |\n|--------|------|\n| `parent_folder_id` 改变 | ✅ 这是目标行为 |\n| **文件标签可能丢失** | ⚠️ 移动前若有标签，先备份！|\n\n**标签备份与恢复模式**：\n\n```python\n# 1. 移动前：备份标签\nbackup = {f[\"media_id\"]: f.get(\"tags\", []) for f in to_move_files}\n\n# 2. 执行 move_knowledge\napi_call(\"openapi/wiki/v1/move_knowledge\", {...})\n\n# 3. 移动后：恢复标签\nfor media_id, tags in backup.items():\n for tag in tags:\n tag_add(kb_id, media_id, real_title, tag)\n```\n\n### 步骤 4：验证归类效果\n\n```python\n# 验证根目录为空\nroot_items = get_knowledge_list(kb_id, limit=50) # 不带 folder_id\nremaining = [f for f in root_items if f.get(\"media_type\") != 99]\nassert len(remaining) == 0, f\"根目录仍有 {len(remaining)} 个散落文件\"\n\n# 验证每个文件夹的文件数符合预期\n```\n\n## 0.5 多层结构设计原则\n\n- **导览放父级**：父文件夹放主题导览，子文件夹**不需要**各自的导览\n- **MECE 划分**：子文件夹之间互斥、覆盖完整\n- **层级不超过 3 层**：超过 3 层说明分类需要重新设计\n- **避免\"其他\"类子文件夹**：用语义命名而非兜底类\n\n## 0.6 文件夹层级模式\n\n**模式 A：扁平**（推荐用于中等规模）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2\n└── 文件夹 3\n```\n\n**模式 B：2 层嵌套**（推荐用于复杂领域）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2（复杂主题）\n│ ├── 子文件夹 A\n│ ├── 子文件夹 B\n│ └── 子文件夹 C\n└── 文件夹 3\n```\n\n## 0.7 与标签的协同\n\n| 维度 | 文件夹 | 标签 |\n|------|:---:|:---:|\n| 主导维度 | 主题分类 | 多维关联 |\n| 结构 | 树状（一文件一父） | 网状（一文件多标签）|\n| 人类友好 | 高（导览） | 低（API）|\n| 机器友好 | 低 | 高 |\n| 一致性要求 | 文件归属唯一 | 一文件多标签 |\n| 创建方式 | 必须事先规划 | 可渐进添加 |\n\n**核心原则**：文件夹负责\"内容组织\"，标签负责\"维度标记\"，二者互为补充。\n\n## 0.8 实战案例\n\n详见 [cases/quantitative-investing.md](cases/quantitative-investing.md)\n\n## 0.9 与 `add_knowledge` 的对比使用场景\n\n| 场景 | 用什么 API |\n|------|----------|\n| 临时把笔记\"展示\"在文件夹中 | `add_knowledge` |\n| 把已有文件真正归类 | `move_knowledge` |\n| 新建文件时指定归属 | `add_knowledge`（创建时即关联）|\n| 把根目录散落文件归位 | `move_knowledge` |\n| 调整多层结构 | `move_knowledge` |\n\nFile v5.0.1:references/guide-template.md\n\n# 主题导览笔记撰写规范\n\n> 适用于：Ingest 操作中的 Compile 子任务。所有导览笔记应遵循统一的 4 章节结构 + schema frontmatter。\n\n## 1. 完整 frontmatter（强制）\n\n> 详见 [schema.md](schema.md) — 这是强制契约，所有导览必须遵守。\n\n```yaml\n---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本，基于知识库资料编译\nsources:\n - [《文章1》](URL)\n - 《文章2》\n - 《文章3》— 请在知识库查看\nrelated_guides:\n - [《主题导览：相关主题》](URL)\n---\n```\n\n## 2. 结构模板\n\n> 模板来源：基于\"交易策略与系统\"主题导览的专业实践版本\n\n```markdown\n# 主题导览：[主题名称]\n\n**版本**：v1.0 | 创建于 YYYY-MM-DD | 更新于 YYYY-MM-DD\n**更新日志**：v1.0 - 初始版本，基于知识库资料编译\n\n## 一、主题定位\n（主题定义 + 解决问题 + 核心逻辑 + 依赖链条）\n\n本主题是XX的XX层，位于XX与XX之间。它解决的核心问题是：如何XX。\n本主题涵盖XX、XX、XX三个关键环节，是XX的桥梁。其核心逻辑遵循清晰的依赖链条：XX → XX → XX → XX。\n\n## 二、核心概念与关键要素\n\n### （一）[核心概念A]\n**核心思想**：一句话概括该概念的本质。\n\n**关键要素**：\n• 要素1：详细说明。相关文章[《文章标题》](链接)指出，具体内容...\n• 要素2：详细说明。相关文章[《文章标题》](链接)进一步说明...\n• 要素3：详细说明。\n\n**实践建议**：\n• 建议1：具体可操作的实践指导\n• 建议2：具体可操作的实践指导\n\n### （二）[核心概念B]\n（同上结构）\n\n## 三、学习路径（融合知识网络）\n\n（以下学习路径以主线展示知识网络的连接关系，每个步骤标注了所需的核心知识储备和与之相关的概念。可根据主题实际需要设置1-N条路径，不必固定为两条）\n\n（如有多条路径，在此展示）\n\n## 四、相关主题\n\n以下主题与\"本主题名称\"紧密关联，构成了更宽广的知识网络：\n\n| 相关主题 | 与本主题的关系 | 关键连接点 |\n|---------|--------------|-----------|\n| XX | XX | XX |\n| XX | XX | XX |\n```\n\n## 2. 4 章节结构规范\n\n| 章节 | 内容详略 | 内容要求 | 写作要点 |\n|------|---------|---------|---------|\n| **一、主题定位** | **略写** 一段话（约 100 字）| 定义 + 解决问题 + 核心逻辑 + 依赖链条 | 用\"是...的 XX 层，位于 XX 与 XX 之间\"句式；依赖链条用箭头链展示 |\n| **二、核心概念与关键要素** | **详写** 每概念约 200-300 字 | 核心思想 + 关键要素（引用文章）+ 实践建议 | 每个关键要素都要引用知识库文章；实践建议要具体可操作 |\n| **三、学习路径（融合知识网络）** | **中等** 表格 + 一段话 | 两条路径 + 表格形式 + 最终整合 | 表格内容精简，最终整合一段话点明闭环逻辑 |\n| **四、相关主题** | **略写** 表格形式 | 主题 + 关系 + 连接点 | 说明每个关联主题的具体连接点，无需展开 |\n\n## 3. 关键要素写作规范\n\n每个关键要素的写作采用以下结构：\n\n```markdown\n• 要素名称：详细说明。相关文章《文章标题》指出，具体内容...\n• 要素名称：详细说明。相关文章《文章标题》进一步说明...\n```\n\n**要点**：\n- 冒号前是要素名称（简洁短语）\n- 冒号后是详细说明（1-2 句话）\n- 末尾用\"相关文章[《标题》](链接)指出/进一步说明/提供了...\"格式引用\n- 引用来源必须是知识库中的实际文章\n- **必须提供可点击的链接**，不能只写文章标题\n\n## 4. 实践建议写作规范\n\n每个核心概念卡片末尾，用编号列表展示 2-3 条具体可操作的实践建议：\n\n```markdown\n**实践建议**：\n• 先有逻辑，后有回测：策略设计应先论证底层投资逻辑，回测只是验证工具，不能替代逻辑思考。\n• 动态适应：策略参数需随市场环境变化而调整，融入宏观前瞻和状态感知可增强跨周期表现。\n• 简单性优先：优先选择参数少、逻辑清晰的简单策略，减少过拟合风险。\n```\n\n**要点**：\n- 建议要具体可操作，不是空泛原则\n- 每条建议都有明确的行动指引\n- 可以引用具体文章中的实践方法\n\n## 5. 学习路径表格规范\n\n**表格列定义**：\n\n| 列名 | 内容 |\n|------|------|\n| 步骤 | 第 X 步：具体步骤名称 |\n| 核心知识 | 需要掌握的核心概念 |\n| 知识网络连接 | 与其他主题的关联（用 → 表示递进，用 → 需要表示依赖）|\n\n**最终整合**：在表格后用一段话总结闭环流程。\n\n## 6. 链接处理规则\n\n> **前置要求**：链接处理必须在**第三步（预获取链接信息）**中完成，不得在编译阶段临时获取。\n\n详见 [link-handling.md](link-handling.md)\n\n## 7. 特殊字符处理\n\n文章标题中可能含有干扰 Markdown 渲染的字符：\n- `|` → 替换为全角 `｜` 或省略\n- `[` `]` `_` `*` → 需转义或省略\n\n## 8. 内容必须基于知识库实际文件\n\n导览笔记的文章列表必须从 `get_knowledge_list` 返回的实际文件生成，不能依赖本地缓存文件。\n\n## 9. 编译质量标准\n\n1. **原子化**：每个知识节点围绕单一主题，避免东拉西扯\n2. **关联性**：知识卡片之间通过超链接形成网状结构\n3. **大纲化**：每个卡片内部有完整的章节结构\n4. **可溯源**：标注每篇文章的来源出处\n5. **可读性**：结构清晰、信息密度适中、美观易读\n\nFile v5.0.1:references/incremental-update.md\n\n# 增量更新（阶段 4 详细）\n\n> 适用于：知识库已有该主题旧版本导览，需要增量更新。\n\n## 1. 读取旧版本\n\n```bash\n# 导出旧版本笔记内容\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"<旧版note_id>\",\"target_content_format\":1}' | \\\npython3 -c \"import sys,json,urllib.request; d=json.load(sys.stdin); url=d['data']['content_url']; req=urllib.request.Request(url); resp=urllib.request.urlopen(req); print(resp.read().decode('utf-8'))\"\n```\n\n## 2. 提取版本信息\n\n从标题下方的版本行提取：\n\n```\n**版本**：v1.0 | 创建于 2026-05-08 | 更新于 2026-05-08\n**更新日志**：v1.0 - 初始版本\n```\n\n## 3. 对比知识库增量\n\n获取文件夹最新文件列表，与旧版本对比：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"folder_id\": \"\", \"count\": 100}' | \\\npython3 -c \"import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('list',[])])\"\n```\n\n## 4. 识别增量内容\n\n| 类型 | 判断方式 | 更新方式 |\n|------|---------|---------|\n| 新增文章 | 旧版本\"四、知识卡片\"中不存在 | 补充到对应核心概念的关键要素中 |\n| 删除文章 | 旧版本提及但知识库中已不存在 | 从列表中移除 |\n| 概念变化 | 知识库中出现新的核心概念分类 | 新增核心概念卡片 |\n\n## 5. 更新导览内容\n\n更新原则：\n- **保留原有结构**：不改变核心概念划分方式\n- **更新关键要素**：补充/移除文章引用\n- **更新实践建议**：根据新增内容调整实践建议\n- **更新学习路径**：如有新的依赖关系\n\n**链接格式要求**（必须严格遵守，引用格式：`[《标题》](URL)`）：\n- 所有引用必须提供**可点击的有效链接**\n- 链接来源参考**第三步生成的链接特性表**，选择正确的写法：\n - 云文档类：使用相对路径格式 `[《标题》](路径)`\n - 网页链接：使用完整 URL 格式 `[《标题》](URL)`\n - 纯本地文件：使用文件路径格式并标注来源\n- 禁止使用裸链接或纯 URL 文本，必须包装为引用格式\n\n## 6. 版本号更新\n\n```yaml\n---\nversion: 1.1 # patch+0.0.1 或 minor+0.1 或 major+1.0\ncreated: 2026-05-08\nupdated: 2026-05-08\nchangelog:\n - v1.1: 增量更新，补充了X篇新文章，更新了关键要素描述\n - v1.0: 初始版本\n---\n```\n\n详见 [versioning.md](versioning.md) 的版本号规则。\n\n## 7. 写入新版本\n\n详见 [write-and-verify.md](write-and-verify.md)\n\n> 💡 推荐使用\"创建新笔记 + 标注替代旧版\"模式，保留旧笔记作为历史版本（详见 [security.md](security.md) 第 3 节）。\n\nFile v5.0.1:references/ingest.md\n\n# Ingest（摄取）操作\n\n> Karpathy 三大操作之首。完整覆盖\"资料入库到 Wiki 演化\"的全部过程。\n> 核心理念：**一次 Ingest 可能级联更新多个导览（知识复利）**。\n\n## 1. 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n## 2. Collect（收集）\n\n### 2.1 资料来源\n\n- 用户上传的文件（PDF/DOCX/PPTX/XLSX 等）\n- 已有 IMA 知识库的内容\n- 联网搜索（用 `search(source=\"web\")`）\n- 网页链接（用 `import_urls`）\n\n### 2.2 收集方式\n\n| 来源 | API | 说明 |\n|------|-----|------|\n| 用户上传文件 | `upload_file` | 上传到指定知识库 |\n| 导入网页 | `import_urls` | 批量导入 URL |\n| 已有知识库 | `get_knowledge_list` | 逐级浏览 |\n| 用户上传笔记 | `add_knowledge` | 关联到知识库 |\n| 联网搜索 | `search(source=\"web\")` | 补充资料 |\n\n### 2.3 资料完整性原则\n\n> \"此阶段追求完整性，不追求结构\" — 所有资料都是后续编译的\"原材料\"\n\n详见 [link-handling.md](link-handling.md) 第 1 节和 [api-reference.md](api-reference.md) 第 5.1 节\n\n## 3. Check（检查）\n\n### 3.1 是否有旧导览？\n\n```bash\n# 在目标文件夹搜索标题包含\"主题导览\"的笔记\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/search_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"search_type\": 0, \"query_info\": {\"title\": \"主题导览\"}, \"start\": 0, \"end\": 20}'\n```\n\n或者用标签筛选（推荐）：\n```bash\n# 列出所有带\"状态:已编译\"标签的导览\nget_knowledge_list(kb_id=X, tags=[\"状态:已编译\"])\n```\n\n### 3.2 判断\n\n| 情况 | 处理方式 |\n|------|---------|\n| 有旧导览（目标主题） | **增量更新**：Compile 模式 2 |\n| 有其他主题导览 | **新建**：Compile 模式 1 |\n| 没有任何知识导览 | **新建**：Compile 模式 1 |\n\n详见 [versioning.md](versioning.md) 第 4 节\n\n## 4. Link（链接特性）\n\n每个文件能否在导览中链接？这是 Karpathy **\"可追溯到 raw\"** 的核心要求。\n\n### 4.1 media_type 速查表（IMA 完整版）\n\n| 值 | 类型 | 链接策略 |\n|----|------|---------|\n| 1 | PDF 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 2 | 网页 | ✅ 获取真实 URL |\n| 3 | Word 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 4 | PPT 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 5 | Excel 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 6 | 公众号文章 | ✅ 获取真实 URL |\n| 7 | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| 9 | 图片 | ⚠️ 标注\"请在知识库查看\" |\n| 11 | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| 12 | QA 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 13 | TXT 文本 | ⚠️ 不内嵌链接，写为纯文本 |\n| 14 | Xmind | ⚠️ 标注\"请在知识库查看\" |\n| 15 | 录音 | ⚠️ 标注\"请在知识库查看\" |\n| 16 | 网页视频 | ⚠️ 标注\"请在知识库查看\" |\n| 17 | 对话 | ⚠️ 标注\"请在知识库查看\" |\n| 18 | 视频 | ⚠️ 标注\"请在知识库查看\" |\n| 19 | 播客 | ⚠️ 标注\"请在知识库查看\" |\n| 20 | HTML | ⚠️ 标注\"请在知识库查看\" |\n| 21 | EPUB 文件 | ⚠️ 标注\"请在知识库查看\" |\n| 99 | 文件夹 | ❌ 不可链接 |\n\n详见 [link-handling.md](link-handling.md) 第 2 节\n\n### 4.2 链接特性表模板\n\n```markdown\n| media_id | title | media_type | 链接策略 | URL/备注 |\n|---------|-------|-----------|---------|---------|\n| xxx | 文章A | 2 | ✅ 可内嵌 | https://... |\n| xxx | 文章B | 6 | ✅ 可内嵌 | https://... |\n| xxx | 文章C | 7 | ⚠️ 不内嵌 | 请在知识库中查看 |\n```\n\n## 5. Compile（编译）\n\n### 5.1 模式 1：新建（5 步法）\n\n1. **明确主题** — 确定核心概念（主题定位、核心概念、边界范围）\n2. **梳理关键词** — 提取关键要素（每概念 3-5 个子主题）\n3. **发现关系** — 找出逻辑关联（层级、并列、因果、对立）\n4. **呈现结构** — 可视化知识网络（表格 + 学习路径）\n5. **美化优化** — 提升可读性（标题规范、排版、信息密度）\n\n### 5.2 模式 2：增量更新（6 步法）\n\n1. **读旧版** — `export_note` 获取旧版本内容\n2. **提取版本信息** — 从 frontmatter 读取 version/changelog\n3. **对比增量** — 比对文件夹中文件与导览 sources[]\n4. **识别变化** — 新增/删除/概念变化\n5. **更新导览** — `append_doc`（推荐）或 `update_note`（精细）\n6. **更新版本号** — patch/minor/major\n\n详见 [guide-template.md](guide-template.md) 和 [versioning.md](versioning.md)\n\n## 6. Write（写入）\n\n### 6.1 选项 A：新建笔记（最简单）\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/import_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content_format\": 1,\n \"content\": \"<完整 Markdown>\",\n \"title\": \"📖 主题导览：[主题名称]\",\n \"folder_id\": \"<目标笔记本 ID>\"\n }'\n# 返回: {\"code\": 0, \"data\": {\"note_id\": \"xxx\"}}\n```\n\n### 6.2 选项 B：追加内容（增量推荐）\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/append_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"note_id\": \"<已有导览 ID>\",\n \"content_format\": 1,\n \"content\": \"<追加内容>\"\n }'\n```\n\n**优势**：不破坏原有结构，原子化操作。\n\n### 6.3 选项 C：按 block 编辑（精细修改）\n\n```bash\n# 第一步：导出 block 结构\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note_blocks\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\": \"\"}'\n\n# 第二步：按 block_id 修改\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/update_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"note_id\": \"\",\n \"block_id\": \"\",\n \"content\": \"<新内容>\"\n }'\n```\n\n详见 [write-and-verify.md](write-and-verify.md)\n\n### 6.4 立即验证\n\n> **重要**：笔记创建接口返回成功不代表内容完整，必须立即验证。\n\n```bash\n# 导出并比对\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"\",\"target_content_format\":1}' | \\\npython3 -c \"\nimport sys, json, urllib.request\nd = json.load(sys.stdin)\nif d['code'] == 0:\n url = d['data']['content_url'] # COS 链接，3 小时时效\n req = urllib.request.Request(url)\n resp = urllib.request.urlopen(req)\n print(resp.read().decode('utf-8'))\n\"\n```\n\n## 7. Cascade（级联）— **Karpathy 核心机制**\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）— 这是 wiki 知识复利的关键。\n\n### 7.1 级联触发条件\n\n- 新文件被 Ingest 后\n- 自动计算它与所有现有导览的相关性\n- 相关度 > 阈值 的导览加入\"待更新列表\"\n\n### 7.2 级联算法\n\n```python\ndef cascade_update(new_file, all_guides, kb_id):\n \"\"\"级联更新：一次 Ingest 可能影响多个导览\"\"\"\n affected = []\n\n # 阶段 1：标签粗筛\n candidate_guides = [\n g for g in all_guides\n if any(tag in new_file.tags for tag in g.tags)\n ]\n\n # 阶段 2：LLM 精评\n for guide in candidate_guides:\n relevance = compute_relevance(new_file, guide)\n if relevance > 0.7: # 阈值\n affected.append((guide, relevance))\n\n # 阶段 3：执行增量更新\n for guide, relevance in affected:\n update_guide_incrementally(guide, new_file)\n\n return affected\n\n\ndef compute_relevance(file, guide):\n \"\"\"LLM 评分：0-1 之间\"\"\"\n prompt = f\"\"\"评估这篇文章与导览\"{guide.title}\"的主题契合度（0-1）。\n\n文章：{file.title}\n摘要：{file.summary or 'N/A'}\n\n导览当前涵盖的核心要素：\n{chr(10).join(f'- {e}' for e in guide.key_elements)}\n\n要求：\n1. 0 表示完全无关\n2. 1 表示高度契合，应纳入\n3. 0.7-1.0 表示应纳入\n4. 仅返回数字（如 0.85）\"\"\"\n return float(call_llm(prompt))\n```\n\n### 7.3 级联示例\n\n**场景**：用户上传\"遗传算法在量化交易中的应用\"到\"AI 量化与深度学习\"知识库。\n\n**现有导览清单**：\n- 📖 主题导览：因子与资产定价（confidence: high）\n- 📖 主题导览：AI 量化与深度学习（confidence: medium）\n- 📖 主题导览：高频交易与微观结构（confidence: high）\n\n**级联过程**：\n\n| 导览 | 标签匹配 | LLM 相关度 | 是否更新 |\n|------|---------|-----------|---------|\n| AI 量化与深度学习 | ✅ 匹配 | 0.92 | ✅ 更新 |\n| 高频交易与微观结构 | ❌ 不匹配 | — | — |\n| 因子与资产定价 | ❌ 不匹配 | — | — |\n\n**最终操作**：1 个导览更新（v1.5 → v1.6）\n\n### 7.4 级联产物\n\n每个受影响导览的 changelog 新增一行：\n\n```yaml\nchangelog:\n - v2.4: [Ingest 2026-09-28] 自动级联更新，新增 1 篇遗传算法文章（来源：《XXX》）\n - v2.3: 之前的手动更新\n```\n\nfrontmatter 更新：\n\n```yaml\nupdated: 2026-09-28\nversion: 1.6 # patch +0.0.1\n```\n\n### 7.5 级联的成本控制\n\n| 控制项 | 措施 |\n|--------|------|\n| 阈值 | 0.7（避免误更新） |\n| 范围 | 仅\"标签匹配\"的候选导览（避免遍历全部） |\n| 用户确认 | 第一次级联前告知用户\"将自动更新 X 个导览\" |\n| 可关闭 | 用户可设置 `cascade_enabled: false` 关闭自动级联 |\n\n## 8. 导览清单（Index）\n\n> Karpathy 的 `index.md` 在 IMA 平台没有等价物，但我们用\"主题导览清单\"代替。\n\n### 8.1 如何获取\n\n```bash\n# 方法 1：用标签筛选所有\"已编译\"导览\nget_knowledge_list(kb_id=X, tags=[\"状态:已编译\"])\n\n# 方法 2：用 search_note 按标题定位\nsearch_note(search_type=0, query_info={title: \"主题导览\"})\n```\n\n### 8.2 清单示例\n\n| 主题导览 | 位置 | 版本 | 最后更新 | confidence |\n|---------|------|:----:|:--------:|:----------:|\n| 📖 主题导览：因子与资产定价 | 因子与资产定价/ | v2.3 | 2026-08-01 | high |\n| 📖 主题导览：AI 量化与深度学习 | AI 量化与深度学习/ | v1.5 | 2026-07-15 | medium |\n| 📖 主题导览：高频交易 | 高频交易与微观结构/ | v3.0 | 2026-06-20 | high |\n\n### 8.3 清单的用途\n\n- LLM 评估新文件该更新哪些导览（Cascade 算法输入）\n- Lint 报告展示知识库全貌\n- 用户了解\"我有哪些导览\"\n\n## 9. 完整工作流示例\n\n**场景**：用户在\"AI 量化与深度学习\"知识库上传一篇新文章\"遗传算法在量化交易中的应用\"。\n\n```\n[Ingest 触发]\n ↓\n[Collect] upload_file 上传文件 → 等待完成\n ↓\n[Check] 在该文件夹搜索\"主题导览\"：\n - 找到 \"📖 主题导览：AI 量化与深度学习\"（v1.5）\n - 找到 \"📖 主题导览：高频交易\"（v3.0）— 但不在该文件夹，跳过\n ↓\n[Link] export_media_for_ima_sandbox 获取永久 URL（如适用）\n ↓\n[Compile] 增量更新模式：\n - 读旧版 → 提取版本信息（v1.5）\n - 对比增量 → 1 篇新增\n - 在\"机器学习理论方法\"核心概念的关键要素中补充遗传算法文章\n - 评估 confidence：medium → medium（无变化）\n ↓\n[Write] 用 append_doc 追加内容（不重建整个笔记）\n - note_id: xxx\n - content: <新的关键要素块>\n ↓\n[Cascade] 检查其他导览：\n - \"因子与资产定价\" → 相关度 0.3，不更新\n - \"高频交易\" → 相关度 0.4，不更新\n - 没有其他受影响导览\n ↓\n[报告] 告诉用户：\n - 主更新：1 个导览更新（v1.5 → v1.6）\n - 级联：0 个其他导览受影响\n - 下次建议：可考虑建\"遗传算法\"独立导览\n```\n\n## 10. 关键原则总结\n\n1. **可追溯**：每个导览的 sources[] 必须能追到 raw 资料\n2. **复利**：一次 Ingest 影响多个导览（不只一个）\n3. **原子化**：用 append_doc 而非重建整个笔记\n4. **schema 强制**：frontmatter 必填字段（confidence/sources/version）\n5. **人类策展**：用户决定收录什么，LLM 维护导览\n\nFile v5.0.1:references/link-handling.md\n\n# 链接处理（阶段 3 详细）\n\n> **前置要求**：链接处理必须在编译前完成，不得在编译阶段临时获取。\n\n## 1. 链接特性预获取流程\n\n### 步骤 1：收集文件列表\n\n获取文件夹中的所有文件，提取每个文件的 `media_id`、`media_type`、`title`：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"folder_id\": \"\", \"count\": 100}' | \\\npython3 -c \"import sys,json; data=json.load(sys.stdin); [print(f\\\"{f['media_id']}|{f['media_type']}|{f['title']}\\\") for f in data.get('data',{}).get('list',[])]\"\n```\n\n### 步骤 2：批量获取链接特性\n\n对每个文件调用 `export_media_for_ima_sandbox`：\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"\"}'\n```\n\n### 步骤 3：生成链接特性表\n\n根据返回结果，建立如下表格：\n\n| media_id | title | media_type | 链接策略 | URL/备注 |\n|---------|-------|-----------|---------|---------|\n| xxx | 文章A | 2 (网页) | ✅ 可内嵌 | https://... |\n| xxx | 文章B | 6 (公众号) | ✅ 可内嵌 | https://... |\n| xxx | 文章C | 7 (Markdown) | ⚠️ 不内嵌 | 请在知识库中查看 |\n| xxx | 文章D | 11 (笔记) | ⚠️ 不内嵌 | 请在知识库中查看 |\n\n### 步骤 4：按类型分类编译\n\n编译导览笔记时，根据链接特性表选择正确的写法：\n\n| 文件类型 | 编译写法 |\n|---------|---------|\n| type 2/6 | `[标题](永久URL)` |\n| type 7/11 | `标题`（纯文本，不加链接）|\n| type 1/3/4/5 | `标题 — 请在知识库中查看` |\n\n## 2. 链接策略表\n\n| media_type | 类型 | 链接策略 |\n|-----------|------|---------|\n| **2** | 网页链接 | ✅ 获取真实 URL，格式：`[《标题》](URL)` |\n| **6** | 公众号文章 | ✅ 获取真实 URL，格式：`[《标题》](URL)` |\n| **7** | Markdown | ⚠️ 不内嵌链接，写为纯文本 |\n| **11** | 笔记 | ⚠️ 不内嵌链接，写为纯文本 |\n| **1** | PDF | ⚠️ 标注\"请在知识库中查看\" |\n| **3** | Word | ⚠️ 标注\"请在知识库中查看\" |\n| **4** | PPT | ⚠️ 标注\"请在知识库中查看\" |\n| **5** | Excel | ⚠️ 标注\"请在知识库中查看\" |\n\n## 3. 引用格式示例\n\n```markdown\n# 可链接的类型（type 2/6）\n• 多维度指标体系：A股情绪温度计采集12个维度指标...[《A股情绪温度计》](https://...)详细阐述了...\n\n# 不可直接链接的类型（type 7/11/1/3/4/5）\n• 系统化执行：（请在知识库中查看）\n```\n\n## 4. 获取公众号/网页的永久 URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"<文件media_id>\"}'\n```\n\n返回的 `data.media_content_url_info.url` 即为永久可跳转链接。\n\n## 5. 特殊字符处理\n\n文章标题中可能含有干扰 Markdown 渲染的字符：\n- `|` → 替换为全角 `｜` 或省略\n- `[` `]` `_` `*` → 需转义或省略\n\n详见 [guide-template.md](guide-template.md) 第 7 节。\n\n## 6. 反模式教训\n\n### 反模式 1：Markdown 表格中包含 `|` 字符\n\n**问题**：知识库文章标题常含 `|`（如\"实务 | 审计抽样实操总结\"），在 Markdown 表格中 `|` 是列分隔符，导致表格解析错乱——一个单元格的内容会被拆成多列。\n\n**错误示例**：\n```markdown\n| # | 文章 | 关键词 |\n|---|------|--------|\n| 1 | 实务 | 审计抽样实操总结 | ← \"实务\"和\"审计抽样实操总结\"被拆成两列\n```\n\n**正确做法**：使用编号列表替代表格：\n```markdown\n1. **实务｜审计抽样实操总结** — 审计抽样实操、统计抽样方法\n```\n\n### 反模式 2：通过 `push_note` + `content_cos_key` 写入短内容\n\n**问题**：COS 上传路径对内容格式敏感，中间环节多（本地文件 → COS 上传 → API 读取），任何一环出错都会导致笔记内容丢失或被系统自动删除（`export_note` 返回 \"doc is delete\"）。\n\n**正确做法**：对于 < 3KB 的内容，直接使用 `import_doc` + `curl -d @filepath` 写入，跳过 COS 中间环节。\n\n### 反模式 3：创建笔记后不验证\n\n**问题**：笔记创建接口返回成功不代表内容完整。可能出现：标题正确但正文为空、内容被截断、笔记被系统自动清理等情况。\n\n**正确做法**：创建笔记后立即调用 `export_note` 导出内容，与原始内容比对。\n\n### 反模式 4：导览内容基于本地缓存而非知识库实际状态\n\n**问题**：本地 `.md` 文件可能被其他任务覆盖或已过时，基于本地文件生成的导览与知识库实际文章不匹配。\n\n**正确做法**：导览笔记的文章列表必须从 `get_knowledge_list` 返回的实际文件生成。\n\nFile v5.0.1:references/lint.md\n\n# Lint（健康检查）\n\n> Karpathy 三大操作之二。完整覆盖知识库的\"健康体检\"。\n> 核心理念：**通过定期检查防止 wiki 衰败**，类比代码世界的 `eslint`。\n\n## 1. 4 类标准检查\n\n| 检查 | 内容 | 触发频率 |\n|------|------|---------|\n| **结构检查** | 文件夹散落、空文件夹、文件错放 | 每周 1 次 |\n| **矛盾检查** | 不同导览对同一概念说法冲突 | 每月 1 次 |\n| **孤立检查** | 导览未被任何文件引用 | 每月 1 次 |\n| **过期检查** | 低 confidence + 长期未更新 | 每月 1 次 |\n\n详见 [maintenance.md 第 6.5 节](maintenance.md)\n\n## 2. 触发条件\n\n| 触发词 | 行为 |\n|--------|------|\n| \"检查知识库\" / \"知识库体检\" | 完整 4 类检查 |\n| \"审查标签\" / \"整理标签\" | 仅标签审查（属于结构检查的子集） |\n| \"健康检查\" | 完整 4 类检查 |\n\n## 3. 结构检查（Structure）\n\n### 3.1 检查项\n\n| 项目 | 检查方法 | 输出 |\n|------|---------|------|\n| 散落文件 | `get_knowledge_list` 不带 `folder_id`，找 `parent_folder_id == ROOT` 的文件 | 文件清单 |\n| 空文件夹 | `get_knowledge_list` 找 `media_type=99` 且子项为空的文件夹 | 文件夹清单 |\n| 文件错放 | LLM 比对文件标签和文件夹主题 | 错放文件清单 |\n\n详见 [folder-organization.md](folder-organization.md)\n\n### 3.2 自动建议\n\n```\n检测到 35 个散落文件\n推荐归类：\n- AkShare/BaoStock... → 数据工具与入门/\n- 情绪... → 金融情绪分析/\n- AI 量化... → AI 量化与深度学习/\n```\n\n## 4. 矛盾检查（Contradiction）\n\n### 4.1 检查项\n\n- 不同导览对同一概念说法冲突\n- 同一文件夹内文件观点冲突\n\n### 4.2 检查方法\n\n```python\ndef check_contradictions(guides):\n \"\"\"LLM 读取多个导览，识别冲突\"\"\"\n # 1. 提取所有导览的\"核心思想\"和\"关键论断\"\n claims_by_guide = {}\n for guide in guides:\n claims_by_guide[guide.id] = extract_key_claims(guide)\n\n # 2. LLM 配对比较\n contradictions = []\n guide_ids = list(claims_by_guide.keys())\n for i, id_a in enumerate(guide_ids):\n for id_b in guide_ids[i+1:]:\n pair_contradictions = llm_compare_claims(\n claims_by_guide[id_a],\n claims_by_guide[id_b]\n )\n contradictions.extend(pair_contradictions)\n\n return contradictions\n\n\ndef llm_compare_claims(claims_a, claims_b):\n prompt = f\"\"\"比较以下两组论断，识别直接冲突的项。\n\n导览 A 的论断：\n{format_claims(claims_a)}\n\n导览 B 的论断：\n{format_claims(claims_b)}\n\n如果存在直接矛盾（同一概念，结论互斥），返回：\n{{\n \"topic\": \"<冲突的概念>\",\n \"claim_a\": \"<导览 A 的说法>\",\n \"claim_b\": \"<导览 B 的说法>\",\n \"severity\": \"high | medium | low\",\n \"suggestion\": \"<如何解决>\"\n}}\n\n如果没有冲突，返回 {{\"topic\": null}}\"\"\"\n # 调用 LLM...\n```\n\n### 4.3 示例\n\n```\n矛盾：关于\"因子有效性衰减\"\n- 导览 A（因子与资产定价 v2.3）: \"Fama-French 三因子模型在 A 股市场有效性较弱\"\n- 导览 B（量化策略 v1.5）: \"Fama-French 三因子在 A 股仍有显著 alpha\"\n- 严重度: medium\n- 建议: 检查两份资料的发表时间和市场环境，可能需要分时段讨论\n```\n\n## 5. 孤立检查（Orphan）\n\n### 5.1 检查项\n\n| 维度 | 检查内容 |\n|------|---------|\n| 孤立导览 | 该导览的 `related_guides[]` 为空，且没有文件在 sources[] 中 |\n| 孤立文件 | 文件未被任何导览的 sources[] 引用 |\n| 孤立章节 | 导览某个章节只有 1 篇文章 |\n\n### 5.2 检查方法\n\n```python\ndef check_orphans(kb_id, all_guides, all_files):\n orphans = {\"guides\": [], \"files\": []}\n\n # 1. 找出被任何导览引用的文件\n referenced_files = set()\n for guide in all_guides:\n for src in guide.sources:\n referenced_files.add(src.media_id)\n\n # 2. 找出孤立文件（未被任何导览引用）\n for file in all_files:\n if file.media_id not in referenced_files:\n orphans[\"files\"].append(file)\n\n # 3. 找出孤立导览（没有 related_guides[]，也没有任何 sources 引用）\n for guide in all_guides:\n if not guide.related_guides and not any(\n f for f in all_files if any(src.media_id == f.media_id for src in guide.sources)\n ):\n orphans[\"guides\"].append(guide)\n\n return orphans\n```\n\n### 5.3 修复建议\n\n```\n孤立文件：\n- 《文章A》.pdf — 未被任何导览引用\n - 建议：纳入\"主题导览：XXX\"（相关度 0.85）\n - 或：新建独立导览（如果内容丰富）\n\n孤立导览：\n- 📖 主题导览：XXX — 没有相关导览也没有引用文件\n - 建议：补充 related_guides[]，加入交叉引用\n```\n\n## 6. 过期检查（Freshness）\n\n### 6.1 检查项\n\n| 项目 | 阈值 | 标记 |\n|------|------|------|\n| 低 confidence 导览 | confidence == \"low\" | 待更新 |\n| 长期未更新（medium） | updated > 30 天前 AND confidence == \"medium\" | 可能过时 |\n| 关键文章已更新但导览未跟进 | 文件 updated > 导览 updated | 待同步 |\n\n### 6.2 检查方法\n\n```python\ndef check_freshness(guides, files):\n from datetime import datetime, timedelta\n\n today = datetime.now()\n stale = []\n\n for guide in guides:\n days_since_update = (today - guide.updated).days\n\n # 规则 1: 低 confidence\n if guide.confidence == \"low\":\n stale.append((guide, \"low_confidence\", \"高优先级\"))\n\n # 规则 2: medium + 长期未更新\n elif guide.confidence == \"medium\" and days_since_update > 30:\n stale.append((guide, \"stale_medium\", \"中优先级\"))\n\n # 规则 3: 关键文章已更新但导览未跟进\n guide_files = [f for f in files if any(\n src.media_id == f.media_id for src in guide.sources\n )]\n newer_files = [f for f in guide_files if f.updated > guide.updated]\n if newer_files:\n stale.append((guide, \"files_updated_guide_stale\", \"高优先级\"))\n\n return stale\n```\n\n## 7. Lint 输出：标准报告\n\n### 7.1 报告路径\n\n```\noutputs/lint-YYYY-MM-DD.md\n```\n\n例如：`outputs/lint-2026-09-28.md`\n\n### 7.2 报告模板\n\n```markdown\n# Wiki 健康检查报告\n\n**生成时间**：2026-09-28\n**知识库**：[知识库名称] (kb_id: ...)\n**检查导览数**：X 个\n**检查文件数**：Y 个\n\n## 总体评分\n\n| 维度 | 评分 | 状态 |\n|------|:----:|:----:|\n| 结构 | ⭐⭐⭐⭐ | 良好 |\n| 矛盾 | ⭐⭐⭐ | 一般 |\n| 孤立 | ⭐⭐⭐⭐ | 良好 |\n| 过期 | ⭐⭐⭐ | 一般 |\n| **综合** | **⭐⭐⭐⭐** | **良好** |\n\n## 1. 结构检查\n\n- 散落文件：X 个\n- 空文件夹：X 个\n- 文件错放：X 个\n\n**修复建议**：\n- [P1] 调用 `move_knowledge` 把 X 个散落文件归类\n- [P2] 删除/重组 X 个空文件夹\n\n## 2. 矛盾检查\n\n- 矛盾论断对：X 对\n\n**示例**：\n- [导览A] vs [导览B] 对 \"XXX\" 概念说法冲突\n - A: ...\n - B: ...\n - 建议: ...\n\n## 3. 孤立检查\n\n- 孤立导览：X 个\n - [导览1]: 建议补充交叉引用\n- 孤立文件：X 个\n - [文件1]: 建议纳入相关导览\n\n## 4. 过期检查\n\n- 低 confidence 导览：X 个\n- 长期未更新（medium）：X 个\n- 关键文章已更新但导览未跟进：X 个\n\n**修复建议**：\n- [P0] 更新低 confidence 导览：XXX\n- [P1] 跟进已更新但导览未更新的：YYY\n\n## 总体改进建议\n\n按优先级排序：\n1. [P0] ...\n2. [P1] ...\n3. [P2] ...\n```\n\n## 8. 自动 Lint 调度（可选）\n\n### 8.1 每周定时\n\n```bash\n# 每周日 0 点跑 Lint，输出到 outputs/lint-YYYY-MM-DD.md\n0 0 * * 0 cd /workspace && \\\n python3 lint.py --kb_id --output outputs/lint-$(date +%Y-%m-%d).md\n```\n\n### 8.2 历史对比\n\n```bash\n# 比较最近 4 周的 Lint 报告\ndiff outputs/lint-2026-09-07.md outputs/lint-2026-09-28.md\n```\n\n跟踪指标：\n- 散落文件数变化（应持续下降）\n- 矛盾数变化（应 < 5）\n- 孤立文件率变化（应 < 20%）\n\n## 9. 与 Ingest 的协同\n\n| Lint 发现 | 触发 Ingest |\n|---------|------------|\n| 低 confidence 导览 | 自动增量更新（带 confidence 提升） |\n| 孤立文件 | 建议纳入相关导览 |\n| 文件错放 | 调用 `move_knowledge` 归类 |\n| 矛盾论断 | 用户确认后增量更新相关导览 |\n\n**核心理念**：Lint 不只是发现问题，而是**驱动 Ingest 解决问题**。\n\nFile v5.0.1:references/maintenance.md\n\n# 维护与迭代（阶段 6 详细）\n\n知识库需要\"活\"起来，而非一次性建好就搁置。\n\n## 6.1 健康检查（\"体检\"）\n\n**触发词**：\"检查知识库\"、\"知识库体检\"\n\n### 检查项\n\n1. 扫描整个知识库，检查：\n - 是否有空文件夹（有待补充内容）\n - 是否有文件放错了分类\n - 主题之间是否有信息矛盾或重复\n - 是否有重要概念缺少覆盖\n2. 生成健康检查报告，列出发现的问题和修复建议\n3. 用户确认后执行修复\n\n### 报告模板\n\n```markdown\n## 知识库健康检查报告\n\n### 文件夹结构\n- 空文件夹：X 个\n - [列出文件夹名]\n- 散落文件：X 个\n - [列出文件名]\n\n### 内容覆盖\n- 核心概念覆盖度：X%\n- 缺少覆盖的概念：[列出]\n\n### 重复与矛盾\n- 重复文章：X 组\n - [列出]\n- 矛盾信息：X 处\n - [列出位置]\n\n### 修复建议\n1. [优先级 P0] ...\n2. [优先级 P1] ...\n```\n\n## 6.2 知识补充\n\n**触发词**：\"补充知识库\"、\"更新知识库\"\n\n### 流程\n\n1. 识别知识库中的薄弱环节（空文件夹、内容过时的主题）\n2. 通过联网搜索补充最新资料\n3. 将新资料编译后归入对应位置\n4. 更新相关的交叉引用和索引\n5. **更新知识导览**：触发增量更新流程（参见 [incremental-update.md](incremental-update.md)）\n\n## 6.3 输出与回流\n\n用户可基于 Wiki 生成各类产出（研究报告、总结、幻灯片大纲等），这些产出保存回笔记本后，实现知识的\"增量训练\"——系统持续演化，而非一次性消耗。\n\n### 典型产出\n\n- 研究报告（用 [ima-report skill]）\n- 总结笔记（用 [ima-note skill]）\n- 播客（用 [ima-podcast skill]）\n- PPT（用 [ima-ppt skill]）\n\n### 回流机制\n\n每次产出的\"知识副产品\"都应回流到知识库：\n1. 产出的笔记 → 添加到对应主题文件夹\n2. 在主题导览的\"相关主题\"中补充\n3. 给文件打主题标签\n\n## 6.4 标签审查\n\n**触发词**：\"审查标签\"、\"整理标签\"\n\n详见 [tagging.md](tagging.md) 第 7 节。\n\n### 检查项\n\n- 命名规范（无近似标签）\n- 孤儿标签（关联文件数 = 0）\n- 弱标签（关联文件数 < 3）\n- 热门标签（关联文件数 > 100）\n\n### ⚠️ 破坏性操作\n\n详见 [security.md](security.md)：\n- `tag_delete` 不可逆\n- `tag_rename` 会自动合并\n- 必须先列影响文件数 + 用户显式确认\n\n## 6.5 维护节奏建议\n\n| 维护类型 | 频率 | 触发条件 |\n|---------|------|---------|\n| 健康检查 | 每月 1 次 | 时间周期 |\n| 知识补充 | 按需 | 用户上传新资料 |\n| 标签审查 | 每季度 1 次 | 标签数 > 100 时 |\n| 增量更新导览 | 每周 1 次 | 文件数增加 > 10% |\n| 深度重构 | 每半年 1 次 | 主题边界变化 |\n\nFile v5.0.1:references/reference.md\n\n# Wiki 编译参考（v5.0.0 重构版）\n\n> 索引页：基于 Karpathy 三大操作重新组织。从这里跳转到各专题详情。\n\n## 🎯 核心理念\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n\n## 📚 Karpathy 三大操作文档\n\n| 操作 | 文档 | 适用场景 |\n|------|------|---------|\n| **Ingest** | [ingest.md](ingest.md) | 资料入库、编译导览、自动级联 |\n| **Lint** | [lint.md](lint.md) | 4 类标准检查（结构/矛盾/孤立/过期）|\n| **Schema** | [schema.md](schema.md) | 强制 frontmatter 契约 |\n\n## 📚 子流程文档\n\n| 文档 | 适用场景 | 说明 |\n|------|---------|------|\n| [folder-organization.md](folder-organization.md) | Ingest 前置 | 知识库结构诊断 + 文件归类 |\n| [tagging.md](tagging.md) | Ingest 子任务 | 标签设计 + 应用 + 审查 |\n| [security.md](security.md) | 全流程 | 破坏性操作保护 |\n| [api-reference.md](api-reference.md) | 全流程 | IMA OpenAPI 端点 + 错误码 |\n| [guide-template.md](guide-template.md) | Ingest 子任务 | 主题导览 4 章节结构 + 写作规范 |\n| [versioning.md](versioning.md) | Ingest 子任务 | 主题导览的版本控制 |\n| [write-and-verify.md](write-and-verify.md) | Ingest 子任务 | 写入笔记 + 验证流程 |\n| [link-handling.md](link-handling.md) | Ingest 子任务 | 链接特性预获取 + 链接策略 |\n| [troubleshooting.md](troubleshooting.md) | 全流程 | 常见错误 + 解决方案 |\n| [cases/quantitative-investing.md](cases/quantitative-investing.md) | 案例 | 量化投资知识库试跑经验 |\n\n## 🎯 Karpathy 三大操作 vs wiki-compiler 7 阶段（v4.x）\n\n| Karpathy 三大操作 | wiki-compiler v4.x 7 阶段 | v5.0.0 重构 |\n|------------------|---------------------------|------------|\n| Ingest（摄取）| 阶段 1+2+3+4+5 | 6 个子任务：Collect/Check/Link/Compile/Write/Cascade |\n| Lint（健康检查）| 阶段 6（部分）| 4 类标准检查 |\n| Schema（契约）| （软约束）| 强制 frontmatter |\n\n## 🚀 快速跳转\n\n- 不知道从哪开始？→ 看 SKILL.md 的\"快速开始\"章节\n- 触发词困惑？→ SKILL.md \"核心理念\"章节\n- 遇到错误？→ [troubleshooting.md](troubleshooting.md)\n- 不知道 API 怎么调用？→ [api-reference.md](api-reference.md)\n- 担心破坏性操作？→ [security.md](security.md)\n- 想看实际案例？→ [cases/quantitative-investing.md](cases/quantitative-investing.md)\n- 主题导览怎么写？→ [guide-template.md](guide-template.md) + [schema.md](schema.md)\n\n## 📊 与 Karpathy 原始模式的对应\n\n| Karpathy 原始模式 | wiki-compiler v5.0 实现 |\n|------------------|----------------------|\n| `CLAUDE.md` 模式核心 | `references/schema.md` |\n| frontmatter 约定 | 强制 frontmatter 字段 |\n| `[[wikilinks]]` 引用 | `related_guides[]` 数组 |\n| `git log` 审计 | `changelog[]` 数组 |\n| 资料溯源 | `sources[]` 数组 |\n| LLM 把握度 | `confidence` 字段 |\n| 三层架构（raw/wiki/CLAUDE.md）| IMA 知识库 / 主题导览 / Schema 文档 |\n| 三大操作（Ingest/Query/Lint）| Ingest / 不归我管 / Lint |\n\n## 🔄 Karpathy vs IMA 平台差异\n\n| 维度 | Karpathy 原始 | IMA 平台 |\n|------|--------------|---------|\n| 存储 | 本地 Markdown 文件 | 云端笔记 + 知识库 |\n| 触发 | 手动操作 UI | 自然语言触发词 |\n| 版本控制 | Git 提交 | 笔记版本号 + changelog |\n| 反向链接 | `[[wikilinks]]` 自动建立 | `related_guides[]` 手动维护 |\n| 删除笔记 | 完全支持 | ❌ 不支持（需客户端） |\n| 向量搜索 | LanceDB（可选） | 平台内置（不归我管）|\n\n## 📖 核心理念速查\n\n### 传统 RAG vs Karpathy LLM Wiki\n\n| 特性 | Karpathy LLM Wiki | 传统 RAG |\n|------|------------------|----------|\n| **状态** | 有状态——知识持续积累 | 无状态——每次查询独立 |\n| **基础设施** | 一堆 `.md` 文件 | 向量库 + embedding |\n| **交叉引用** | 预建（`related_guides[]`）| 临时发现 |\n| **可追溯性** | 强（每个论断追到 raw）| 弱（chunk 级引用） |\n| **规模甜区** | < 100-200 个源 | 百万级文档 |\n\n### 文件夹设计模式\n\n详见 [folder-organization.md 第 6 节](folder-organization.md)\n\n**模式 A：扁平**（中等规模）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2\n└── 文件夹 3\n```\n\n**模式 B：2 层嵌套**（复杂领域）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2（复杂主题）\n│ ├── 子文件夹 A\n│ ├── 子文件夹 B\n│ └── 子文件夹 C\n└── 文件夹 3\n```\n\n### 标签与文件夹的协同\n\n详见 [folder-organization.md 第 7 节](folder-organization.md) 和 [tagging.md](tagging.md)\n\n| 维度 | 文件夹 | 标签 |\n|------|:---:|:---:|\n| 主导维度 | 主题分类 | 多维关联 |\n| 结构 | 树状（一文件一父）| 网状（一文件多标签）|\n| 人类友好 | 高（导览）| 低（API）|\n| 机器友好 | 低 | 高 |\n\n**核心原则**：\n- 职责不重叠：文件夹负责\"内容组织\"，标签负责\"维度标记\"\n- 互为补充：标签给文件夹扩展维度，文件夹给标签赋予语义\n- 低耦合：任一失效，另一方仍可独立工作\n\n## 📝 文档维护说明\n\n**当前版本**：v5.0.0（2026-09-28）\n\n**重构原则**：\n- Karpathy 三大操作作为顶层架构\n- 子流程文档按 Ingest 子任务组织\n- Lint 和 Schema 各自独立\n\n**演进原则**：\n- 新增功能 → 在对应 Karpathy 操作下扩展\n- 避免重新发明轮子（不归我管的由 IMA 处理）\n\nArchive v5.0.0: 19 files, 52327 bytes\n\nFiles: references/api-reference.md (7668b), references/cases/quantitative-investing.md (5448b), references/folder-organization.md (7169b), references/guide-template.md (5737b), references/incremental-update.md (3046b), references/ingest.md (12863b), references/link-handling.md (5230b), references/lint.md (8436b), references/maintenance.md (2784b), references/reference.md (5668b), references/schema.md (7314b), references/security.md (7269b), references/tagging.md (5136b), references/troubleshooting.md (6133b), references/versioning.md (2096b), references/write-and-verify.md (4477b), skill-card.md (2114b), SKILL.md (11638b), _meta.json (132b)\n\nFile v5.0.0:SKILL.md\n\n---\nname: wiki-compiler\nversion: 5.0.0\ndescription: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。\nlicense: MIT-0\nauthor: cookfish\nlast_updated: 2026-09-28\nhomepage: https://github.com/cookfish/wiki-compiler\n\nmetadata:\n openclaw:\n emoji: 🔧\n requires:\n primaryEnv: IMA_OPENAPI_APIKEY\n env:\n - IMA_OPENAPI_CLIENTID\n - IMA_OPENAPI_APIKEY\n---\n\n# 知识库 Wiki 编译器 v5.0.0\n\n> **技能版本**：v5.0.0 | 最后更新：2026-09-28 | 上一版：v4.1.0\n> **核心理念**：基于 Karpathy 的 LLM Wiki 模式 —— **\"Human curates, LLM maintains\"**\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n> **IMA 平台依赖**：需配置 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。获取方式：访问 https://ima.qq.com/agent-interface\n\n---\n\n## 快速开始\n\n### 场景 1：建新知识库\n用户：\"建一个关于 XXX 的知识库\" → **Ingest**（完整流水线）\n\n### 场景 2：导入新资料\n用户：\"导入这个网页\" / \"上传这个 PDF\" → **Ingest**（自动级联）\n\n### 场景 3：整理散落文件\n用户：\"按文件夹归类\" / \"整理散落文件\" → **Ingest 前置**（Folder Pre-Ingest）\n\n### 场景 4：维护知识库\n用户：\"检查知识库\" / \"健康检查\" → **Lint**（4 类标准检查）\n\n### 场景 5：增量更新导览\n用户：\"更新导览\" / \"导览新增了 N 篇文章\" → **Ingest**（增量模式）\n\n### 场景 6：标签管理\n用户：\"给知识库打标签\" / \"审查标签\" → **Ingest** 子任务（Schema 辅助）\n\n---\n\n## 核心理念\n\n### Karpathy 三大操作\n\n| 操作 | 职责 | 触发词 | 详见 |\n|------|------|--------|------|\n| **Ingest**（摄取） | 资料入库，编译/更新导览，级联多个相关导览 | \"建知识库\"\"导入网页\"\"上传文件\"\"更新导览\" | [ingest.md](references/ingest.md) |\n| **Lint**（健康检查） | 4 类标准检查：结构/矛盾/孤立/过期 | \"检查知识库\"\"健康检查\" | [lint.md](references/lint.md) |\n| **Schema**（契约） | 强制 frontmatter 规范（自动应用） | （无需用户触发）| [schema.md](references/schema.md) |\n\n**Query（查询）由 IMA search/fetch 完成，不归本 skill 管。**\n\n### 为什么这样设计\n\n- **Ingest**：知识库是\"会复利的资产\"，不是\"可检索的语料库\"\n- **Lint**：通过定期检查防止 wiki 衰败（类比代码世界的 `eslint`）\n- **Schema**：没有 schema，LLM 会天马行空；有了 schema，LLM 才守纪律\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n\n---\n\n## Ingest（摄取）\n\n### 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n### 关键子任务\n\n| 子任务 | 核心动作 | API |\n|--------|---------|-----|\n| **Collect** | 上传文件 / 导入网页 / 拉取已有 | `upload_file`, `import_urls`, `get_knowledge_list` |\n| **Check** | 搜索旧导览 | `search_note`（标题=\"主题导览\"）|\n| **Link** | 获取链接特性表 | `export_media_for_ima_sandbox` |\n| **Compile** | 新建/增量更新 | LLM 5 步法或 6 步法 |\n| **Write** | 创建/追加/编辑笔记 | `import_doc`, `append_doc`, `update_note` |\n| **Cascade** | **级联更新多个相关导览**（知识复利）| `search_note` + LLM 评分 |\n\n详见 [references/ingest.md](references/ingest.md)\n\n### ⚠️ Karpathy 核心机制：知识复利\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）\n\n```\n新文件被上传\n ↓\n计算与每个现有导览的相关性（标签粗筛 + LLM 精评）\n ↓\n相关度 > 0.7 的导览 → 加入\"待更新列表\"\n ↓\n逐个执行增量更新（append_doc）\n ↓\n记录到 changelog（标 [Ingest 日期]）\n```\n\n**示例**：上传\"遗传算法在量化交易中的应用\" → 1 个导览更新（v1.5 → v1.6）+ 0 个级联。\n\n---\n\n## Lint（健康检查）\n\n### 4 类标准检查（Karpathy 完整版）\n\n| 检查 | 触发频率 | 检查内容 |\n|------|---------|---------|\n| **结构** | 每周 | 散落文件、空文件夹、文件错放 |\n| **矛盾** | 每月 | 不同导览对同一概念说法冲突 |\n| **孤立** | 每月 | 导览未被任何文件引用 |\n| **过期** | 每月 | 低 confidence + 长期未更新 |\n\n详见 [references/lint.md](references/lint.md)\n\n### 触发词\n\n- \"检查知识库\" / \"知识库体检\" / \"健康检查\"\n- \"审查标签\" / \"整理标签\"（仅标签部分）\n\n### 输出\n\n`outputs/lint-YYYY-MM-DD.md` —— 包含总体评分、4 类检查详情、修复建议。\n\n---\n\n## Schema（契约）\n\n### 强制 frontmatter（每篇主题导览）\n\n```yaml\n---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本\nsources:\n - [《文章1》](URL)\nrelated_guides:\n - [《另一导览》](URL)\n---\n```\n\n详见 [references/schema.md](references/schema.md)\n\n### 核心字段说明\n\n| 字段 | Karpathy 对应 | 作用 |\n|------|-------------|------|\n| `confidence` | LLM 把握度 | 让用户知道哪些导览可信 |\n| `sources[]` | 资料溯源 | 每个论断追到 raw（防止幻觉）|\n| `related_guides[]` | `[[wikilinks]]` | 网状结构而非树状 |\n| `changelog[]` | `git log` | 审计追踪 |\n| `version` | 语义化版本 | 变更管理 |\n\n---\n\n## 安全准则（破坏性操作）\n\n| 操作 | 风险 | 保护 |\n|------|------|------|\n| ~~`delete_note`~~ | ❌ API 不支持 | 客户端手动 |\n| `tag_delete` | 关联自动解除 | 列影响文件→用户确认 |\n| `tag_rename` | 重名自动合并 | 检查新名→用户确认 |\n| `move_knowledge` | 标签可能清空 | 备份标签→移动后恢复 |\n\n详见 [references/security.md](references/security.md)\n\n---\n\n## API 速查\n\n### 核心端点\n\n| 功能 | 端点 |\n|------|------|\n| 上传文件 | `openapi/wiki/v1/upload_file` |\n| 导入网页 | `openapi/wiki/v1/import_urls` |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` |\n| 重命名 | `openapi/wiki/v1/rename_knowledge` |\n| 添加标签 | `openapi/wiki/v1/tag_add` |\n| 列出知识库 | `openapi/wiki/v1/get_knowledge_list` |\n| 获取媒体信息 | `openapi/wiki/v1/get_media_info` |\n| 创建笔记 | `openapi/note/v1/import_doc` |\n| 追加笔记 | `openapi/note/v1/append_doc` |\n| 导出笔记 | `openapi/note/v1/export_note` |\n| 搜索笔记 | `openapi/note/v1/search_note` |\n| 按 block 编辑 | `openapi/note/v1/update_note` |\n| ~~删除笔记~~ | ❌ API 不支持 |\n\n详见 [references/api-reference.md](references/api-reference.md) 和 [references/troubleshooting.md](references/troubleshooting.md)\n\n---\n\n## 编译质量标准\n\n1. **原子化**：每个知识节点围绕单一主题\n2. **关联性**：知识卡片之间通过超链接形成网状结构\n3. **大纲化**：每个卡片内部有完整的章节结构\n4. **可溯源**：每篇文章有来源出处（sources[]）\n5. **可读性**：结构清晰、信息密度适中\n6. **confidence 标注**：每个论断有可信度（Karpathy 特色）\n\n---\n\n## 重要提醒\n\n- **预获取链接是编译前的必做步骤**（Link 子任务）—— 先建立链接特性表，再基于表编译\n- **增量优先**——每次 Ingest 前必须 Check 旧版本，优先增量更新而非重新创建\n- **schema 强制**——所有导览必须遵守 [references/schema.md](references/schema.md)\n- **级联需确认**——Cascade 是 Karpathy 核心机制，但首次使用应告知用户\n- **导出笔记是 COS URL**——`export_note` 返回 `content_url`（3 小时时效），需二次下载\n- **删除笔记不支持**——IMA 平台当前 API 不支持，请用户在客户端操作\n\n---\n\n## 变更日志\n\n### v5.0.0 (2026-09-28) - Karpathy 重构（major 升级）\n\n**架构重组**：\n- 7 阶段 → Karpathy **三大操作**（Ingest / Lint / Schema）\n- SKILL.md 精简到 ~450 行（v4.1.0 是 499 行）\n- 新增 3 个核心 references：ingest.md / lint.md / schema.md\n- 引入 Karpathy 核心机制：**知识复利（Cascade 级联更新）**\n\n**Schema 强制化**：\n- 主题导览 frontmatter 强化：必填 confidence / sources[] / related_guides[] / changelog\n- confidence 字段：每篇导览标注可信度（high/medium/low）\n- sources[] 强制：每个论断追到 raw 资料\n\n**Ingest 增强**：\n- 新增 Cascade（级联）算法：一次操作影响多个导览\n- 新增 append_doc（增量追加，不重建）\n- 新增 update_note（按 block 编辑）\n\n**Lint 强化**：\n- 从\"基础健康检查\"升级到 Karpathy 标准的 4 类检查（结构/矛盾/孤立/过期）\n- Lint 报告输出到 `outputs/lint-YYYY-MM-DD.md`\n\n**触发词保持 11 个不变**\n\n**复杂度反思**：\n- 之前 v4.2.0 加 14 项功能会让 SKILL.md 增长到 700+ 行\n- v5.0.0 重组为三大操作，结构更清晰\n- 11 个触发词保持不变，description 不变（向后兼容）\n\n### v4.1.0 (2026-09-28) - IMA 原生格式升级\n\n- 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组\n- 删除笔记 API 修正：v4.0.0 附录 B 的 `delete_note` 安全删除流程已失效\n\n### v4.0.0 (2026-07-08) - 完全重构\n\n- 7 阶段法操作流程\n\n### v3.0.2 (2026-07-08) - 描述优化\n### v3.0.1 (2026-07-08) - 安全修复\n### v3.0.0 (2026-05-13) - 多层结构\n### v1.0 (2026-05-07) - 初版\n\n---\n\n## 文档结构\n\n```\nwiki-compiler/\n├── SKILL.md ← 本文件（操作手册）\n└── references/\n ├── reference.md ← references/ 索引\n ├── ingest.md ← 🆕 Ingest 完整操作 + 级联算法\n ├── lint.md ← 🆕 Lint 4 类标准检查\n ├── schema.md ← 🆕 强制 frontmatter 契约\n ├── folder-organization.md ← Ingest 前置：文件夹整理\n ├── tagging.md ← Ingest 子任务：标签管理\n ├── security.md ← 破坏性操作保护\n ├── api-reference.md ← API 速查\n ├── guide-template.md ← 笔记撰写规范（含新 frontmatter）\n ├── versioning.md ← 版本控制\n ├── write-and-verify.md ← 写入与验证\n ├── link-handling.md ← 链接处理\n ├── troubleshooting.md ← 故障排查\n └── cases/\n └── quantitative-investing.md ← 实战案例\n```\n\n> ⚠️ **IMA 平台注意**：IMA 平台会周期性向 `/sandbox/workspace/skills//` 添加软链接 ` -> /root/.skills//`，可能导致打包时混入旧版本。打包前务必用 `find ... -type l` 检查并清理。\n> 详见 [references/troubleshooting.md](references/troubleshooting.md) 第 10 节。\n\nFile v5.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7b60cvvedv8jkxs5gy3m9c0d837e9f\",\n \"slug\": \"wiki-compiler\",\n \"version\": \"5.0.0\",\n \"publishedAt\": 1790586958103\n}\n\nFile v5.0.0:references/api-reference.md\n\n# API 速查\n\n> IMA OpenAPI 完整参考。所有调用都依赖 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。\n\n## 1. 环境变量配置\n\n```bash\n# 必需的环境变量\nexport IMA_OPENAPI_CLIENTID=\"你的ClientID\"\nexport IMA_OPENAPI_APIKEY=\"你的APIKey\"\n\n# 或使用配置文件\nmkdir -p ~/.config/ima\necho \"你的ClientID\" > ~/.config/ima/client_id\necho \"你的APIKey\" > ~/.config/ima/api_key\nchmod 600 ~/.config/ima/*\n```\n\n## 2. 通用调用函数（Python）\n\n```python\nimport urllib.request\nimport json\n\ndef ima_api(path, data=None):\n \"\"\"IMA OpenAPI 通用调用函数\"\"\"\n headers = {\n \"ima-openapi-clientid\": \"你的ClientID\",\n \"ima-openapi-apikey\": \"你的APIKey\",\n \"Content-Type\": \"application/json\"\n }\n url = f\"https://ima.qq.com/{path}\"\n req = urllib.request.Request(\n url,\n data=json.dumps(data or {}).encode('utf-8'),\n headers=headers,\n method=\"POST\"\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n return json.loads(resp.read().decode(\"utf-8\"))\n```\n\n## 3. 常用 API 端点\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| **获取知识库列表** | `openapi/wiki/v1/get_knowledge_list` | `knowledge_base_id`, `limit` |\n| **搜索知识库** | `openapi/wiki/v1/search_knowledge_base` | `query`, `cursor`, `limit` |\n| **获取媒体信息** | `openapi/wiki/v1/get_media_info` | `media_id`, `knowledge_base_id` |\n| **导出媒体内容** | `openapi/wiki/v1/export_media_for_ima_sandbox` | `media_id` |\n| **创建文件夹** | `openapi/wiki/v1/create_folder` | `knowledge_base_id`, `folder_name`, `parent_folder_id` |\n| **移动文件** | `openapi/wiki/v1/move_knowledge` | `src_kb_id`, `dst_kb_id`, `dst_folder_id`, `infos` |\n| **添加标签** | `openapi/wiki/v1/tag_add` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| **移除标签** | `openapi/wiki/v1/tag_remove` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| **列出标签** | `openapi/wiki/v1/tag_list` | `kb_id`, `cursor`, `limit` |\n| **删除标签** | `openapi/wiki/v1/tag_delete` | `kb_id`, `tag_name` |\n| **重命名标签** | `openapi/wiki/v1/tag_rename` | `kb_id`, `old_tag_name`, `new_tag_name` |\n| **创建笔记** | `openapi/note/v1/import_doc` | `content_format`, `content`, `title` |\n| **导出笔记** | `openapi/note/v1/export_note` | `note_id`, `target_content_format` |\n| ~~**删除笔记**~~ | ~~`openapi/note/v1/delete_note`~~ | ❌ **API 已不支持（2026-09）**，需用户在 IMA 客户端手动删除 |\n| **列出笔记本** | `openapi/note/v1/list_notebooks` | - |\n| **创建笔记本** | `openapi/note/v1/create_notebook` | `name` |\n| **列出笔记** | `openapi/note/v1/list_notes` | `notebook_id`, `count` |\n\n## 4. 错误代码参考\n\n| code | 说明 | 解决方案 |\n|------|------|---------|\n| 0 | 成功 | - |\n| 51 | 参数错误（如 `limit` 超出范围） | 检查参数值 |\n| 220001 | 文件名称不匹配（`item_name` 未用完整标题） | 从 `get_knowledge_list` 取原标题 |\n| 220004 | 无效的 `knowledge_base_id` | 检查 kb_id |\n| 220030 | 无写权限（普通成员调用 `tag_add` 等写操作） | 联系知识库创建者加权限 |\n| 404 | API 端点不存在 | 检查 path |\n\n## 5. 关键 API 详解\n\n### 5.1 `get_knowledge_list`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"folder_id\": \"\", \"count\": 50}'\n```\n\n| 参数 | 必填 | 说明 |\n|------|:----:|------|\n| `knowledge_base_id` | ✅ | 知识库 ID |\n| `folder_id` | ❌ | 文件夹 ID（不传=根目录，返回所有项目含散落文件视图）|\n| `count` / `limit` | ❌ | 返回数量（最大 50，超出需 cursor 分页）|\n| `cursor` | ❌ | 分页游标 |\n| `tags` | ❌ | 按标签筛选（数组）|\n\n### 5.2 `move_knowledge`\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}]\n }'\n```\n\n| 参数 | 必填 | 说明 |\n|------|:----:|------|\n| `src_knowledge_base_id` | ✅ | 原知识库 ID |\n| `dst_knowledge_base_id` | ✅ | 目标知识库 ID（同库移动时与 src 相同）|\n| `dst_folder_id` | ❌ | 目标文件夹 ID（不传=根目录）|\n| `dst_folder_name` | ❌ | 目标文件夹名称（二次校验）|\n| `infos` | ✅ | 移动列表，每项含 `media_id`，**最多 10 个**|\n\n**注意**：返回的 `data.move_results[media_id].ret_code` 表示单文件结果，需检查每个文件的 ret_code 而非顶层 code。\n\n### 5.3 `tag_add` / `tag_remove`\n\n**`item_name` 必须严格匹配**——使用 `get_knowledge_list` 返回的**完整标题**（含扩展名和括号内容）。简化标题会导致 `220001 文件名称不匹配` 错误。\n\n```bash\n# 添加标签\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/tag_add\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"knowledge_base_id\": \"\",\n \"item_id\": \"\",\n \"item_name\": \"\",\n \"tag_name\": \"<标签名>\"\n }'\n\n# 移除标签\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/tag_remove\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"knowledge_base_id\": \"\",\n \"item_id\": \"\",\n \"item_name\": \"<完整标题>\",\n \"tag_name\": \"<标签名>\"\n }'\n```\n\n**特性**：\n- 重复操作不报错（幂等）\n- 文件夹不支持打标签（`media_type=99`）\n\n### 5.4 `import_doc` 创建笔记\n\n```bash\n# 1. 构建请求 JSON\npython3 -c \"\nimport json\nwith open('guide_content.md', 'r') as f:\n content = f.read()\nwith open('note_request.json', 'w') as f:\n json.dump({\n 'content_format': 1,\n 'content': content,\n 'title': '📖 主题导览：[主题名称]'\n }, f, ensure_ascii=False, indent=2)\n\"\n\n# 2. 发送请求\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/import_doc\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d @note_request.json | python3 -m json.tool\n# 返回: {\"code\": 0, \"data\": {\"note_id\": \"xxx\"}}\n```\n\n### 5.5 `export_note` 导出笔记\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/note/v1/export_note\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"note_id\":\"\",\"target_content_format\":1}' | python3 -c \"\nimport sys,json\nd=json.load(sys.stdin)\nif d['code']==0:\n print(d['data']['content'])\nelse:\n print(d)\n\"\n```\n\n### 5.6 `export_media_for_ima_sandbox` 获取永久 URL\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"media_id\": \"<文件media_id>\"}'\n```\n\n返回的 `data.media_content_url_info.url` 即为永久可跳转链接（仅 type 2/6 可用）。\n\nFile v5.0.0:references/cases/quantitative-investing.md\n\n# 实战案例：量化投资知识库\n\n> 基于 2026-06-29 至 2026-07-01 在量化投资知识库（kb_id: `I_49nAThDICNno0gyhjl4dU1zUFtkNWv0X7mhlBQID8=`）的试跑总结。\n\n## 1. 知识库概况\n\n| 维度 | 数据 |\n|------|------|\n| 主题 | 量化投资（因子模型、机器学习、情绪分析等）|\n| 资料类型 | PDF、笔记、公众号文章、网页 |\n| 初始规模 | 35 个根目录散落文件 |\n| 最终规模 | 135 个文件，7 个顶层文件夹 |\n| 标签总数 | 244 个 |\n| 主题导览 | 7 个 |\n\n## 2. 阶段成果\n\n| 阶段 | 文件数 | 散落文件 | 标签 | 主题导览 |\n|------|:------:|:--------:|:----:|:-------:|\n| 初始 | 35 | 35 | 0 | 1 |\n| 演示后 | 36 | 35 | 20 | 1 |\n| 6 导览+30 打标 | 66 | 35 | 264 | 7 |\n| 归类后（move_knowledge）| 101 | 0 | 264 | 7 |\n| 多层归类后（PDF 单独处理）| 135 | 0 | 264 | 7 |\n\n**关键收获**：\n- 35 个根目录文件归类 → 0 散落\n- 14 个父文件夹文件移到子文件夹 → 结构清晰\n- 所有 244 个标签保留（移动文件前无标签，零风险）\n\n## 3. 最终文件夹结构\n\n```\n量化投资/\n├── 数据工具与入门/ （AkShare、聚宽、JQData 等）\n├── 金融情绪分析/ （情绪温度计、市场情绪等）\n├── 因子与资产定价/ （Fama-French、Alpha 因子等）\n├── 高频交易与微观结构/ （HFT、订单流等）\n├── 交易策略与系统/ （策略设计、回测等）\n├── AI 量化与深度学习/ （顶层）\n│ ├── 机器学习理论方法/\n│ ├── 大模型与智能体/\n│ └── 深度学习与预测模型/\n└── 主题导览（位于各文件夹）/\n ├── 📖 主题导览：数据工具与入门\n ├── 📖 主题导览：金融情绪分析\n ├── ...\n```\n\n**特点**：\n- 7 个顶层文件夹\n- AI 量化与深度学习含 3 个子文件夹（多层结构）\n- 父文件夹放主题导览，子文件夹不需要各自导览\n\n## 4. 关键词映射表\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n## 5. 试跑经验教训\n\n### 5.1 `item_name` 必须严格匹配完整标题\n\n完整标题包括扩展名（如 `.pdf`）和括号内容。\n\n```json\n// ❌ 简化标题（失败，code=220001）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易\"}\n\n// ✅ 完整标题（成功）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易 (伊夫-希尔皮斯科) (z-library.sk, 1lib.sk, z-lib.sk).pdf\"}\n```\n\n### 5.2 `limit` 参数范围 (0, 50]\n\n最大 50，超过会返回 51 错误。\n\n### 5.3 API 幂等性\n\n`tag_add` 重复打、`tag_remove` 移除不存在的——均直接返回成功。可放心重试和断点续传。\n\n### 5.4 `tag_remove` 完全可逆\n\n`tag_remove` 后文件 `tags` 字段变为 `[]`，不留痕迹。**`tag_delete` 才是不可逆的**。\n\n### 5.5 媒体类型覆盖建议\n\n试跑中覆盖了 PDF/笔记/公众号/网页（4 种）。未覆盖 Word/PPT/Excel/Markdown/视频/图片等。**真实场景使用前**建议覆盖完整 14 种类型。\n\n### 5.6 标签数量预期\n\n文章级标签每篇 3-5 个，128 篇内容的知识库预计产生 384-640 个标签。**标签总数 > 100 时建议人工审查命名规范**。\n\n### 5.7 `add_knowledge` ≠ `move_knowledge`（最关键）\n\n| 操作 | 行为 | parent_folder_id |\n|------|------|:----------------:|\n| `add_knowledge` | 文件\"展示\"在文件夹中（虚拟关联）| ❌ 不变 |\n| `move_knowledge` | 真正改变 `parent_folder_id` | ✅ 变为目标文件夹 |\n\n**仅调用 `add_knowledge` 不调用 `move`，文件会永远挂在根目录**。\n\n### 5.8 `move_knowledge` 会清空标签\n\n**应对模式**：\n1. 移动前备份标签\n2. 执行 `move_knowledge`\n3. 移动后逐个重新打标\n\n### 5.9 根目录调用 ≠ 知识库全貌\n\n不带 `folder_id` 调 `get_knowledge_list` 会返回**所有项目**（含 7 个文件夹 + 35 个散落文件 + 60 个已分配文件的\"虚拟副本\"）。\n\n**真正判断散落的方法**：比较文件的 `parent_folder_id` 与知识库根目录 ID。\n\n### 5.10 多层文件夹结构诊断\n\n复杂知识库需要**递归扫描**：\n\n```python\nfor folder in root_folders:\n items = get_knowledge_list(folder_id=folder.id)\n sub_folders = [f for f in items if f.type == 99]\n files = [f for f in items if f.type != 99]\n \n for sub in sub_folders:\n sub_items = get_knowledge_list(folder_id=sub.id)\n # 继续递归\n```\n\n判断标准：\n- 父文件夹下的\"直接挂载文件\"如果主题匹配子文件夹，**应该移到子文件夹**\n- 导览应放父级，**不需要**给每个子文件夹单独生成导览\n\nFile v5.0.0:references/folder-organization.md\n\n# 文件夹组织（阶段 0 详细）\n\n> 适用于：知识库结构混乱、文件散落在根目录、需要多层结构整理。\n\n## 0.1 三种\"文件夹\"操作\n\n| 操作 | API | 效果 | 何时使用 |\n|------|-----|------|---------|\n| **创建文件夹** | `create_folder` | 在知识库根目录建一个新文件夹 | 建立分类骨架 |\n| **虚拟归类** | `add_knowledge` | 让文件\"看起来\"在文件夹中（**parent_folder_id 不变**）| 临时展示 |\n| **物理归类** | `move_knowledge` | 真正修改 `parent_folder_id` 为目标文件夹 | 真正整理 |\n\n**关键警告**：\n- `add_knowledge` 创建的是\"虚拟关联\"，**不改变 `parent_folder_id`**\n- 仅用 `add_knowledge` 而不调用 `move_knowledge`，文件永远挂在根目录\n- 根目录调用 `get_knowledge_list` 会返回所有文件（包括已\"虚拟关联\"的），但这不代表它们真正归属于文件夹\n\n## 0.2 诊断流程\n\n### 步骤 1：拉取知识库根目录\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"limit\": 50}'\n```\n\n### 步骤 2：识别散落文件\n\n```python\nROOT_FOLDER_ID = \"<知识库根目录 ID>\" # 通常通过 get_knowledge_base 获取\n\norphans = [f for f in root_items\n if f.get(\"media_type\") != 99\n and f.get(\"parent_folder_id\") == ROOT_FOLDER_ID]\n```\n\n### 步骤 3：递归扫描文件夹层级\n\n对每个文件夹调用 `get_knowledge_list(folder_id=...)`，记录：\n- 子文件夹（`media_type == 99`）\n- 文件数\n- 每个文件的 `parent_folder_id` 是否等于当前 `folder_id`\n\n### 步骤 4：分类汇总\n\n| 状态 | 含义 | 处理方式 |\n|------|------|---------|\n| 文件 `parent_folder_id` 是根目录 | 真正散落 | 用 `move_knowledge` 归类 |\n| 文件 `parent_folder_id` 是文件夹 ID | 已归类 | 仅检查是否需要打标签 |\n| 文件仅在根目录返回但 parent 是文件夹 | 虚拟关联 | 已正确处理 |\n\n## 0.3 诊断输出模板\n\n```markdown\n## 知识库结构诊断报告\n\n### 顶层文件夹\n| 文件夹 | 文件数 | 含子文件夹 |\n|--------|:------:|:----------:|\n| ... | ... | ... |\n\n### 散落文件\n- 共 X 个文件 `parent_folder_id` 是根目录\n- 列出每个文件的标题和推荐目标文件夹\n\n### 多层结构\n- AI 量化与深度学习/\n - 机器学习理论方法/（Y 个文件）\n - 大模型与智能体/（Y 个文件）\n - ...\n\n### 处理建议\n- 散落文件：调用 `move_knowledge` 归类\n- 多层结构：导览放父级，子文件夹不需要各自导览\n```\n\n## 0.4 归类流程\n\n### 步骤 1：列出待归类文件\n\n```python\n# 从诊断报告中获取散落文件\norphans = [(f[\"media_id\"], f[\"title\"]) for f in orphan_files]\n```\n\n### 步骤 2：推荐目标文件夹\n\n关键词匹配模式（参考实战案例）：\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n> 关键词表针对量化投资领域；其他领域需重新设计。\n\n### 步骤 3：批量调用 `move_knowledge`\n\n```bash\n# 移动到目标文件夹（src_kb_id == dst_kb_id 表示知识库内移动）\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}, {\"media_id\": \"\"}]\n }'\n```\n\n**注意**：每次最多 10 个文件，分批调用。\n\n### ⚠️ `move_knowledge` 的副作用\n\n| 副作用 | 说明 |\n|--------|------|\n| `parent_folder_id` 改变 | ✅ 这是目标行为 |\n| **文件标签可能丢失** | ⚠️ 移动前若有标签，先备份！|\n\n**标签备份与恢复模式**：\n\n```python\n# 1. 移动前：备份标签\nbackup = {f[\"media_id\"]: f.get(\"tags\", []) for f in to_move_files}\n\n# 2. 执行 move_knowledge\napi_call(\"openapi/wiki/v1/move_knowledge\", {...})\n\n# 3. 移动后：恢复标签\nfor media_id, tags in backup.items():\n for tag in tags:\n tag_add(kb_id, media_id, real_title, tag)\n```\n\n### 步骤 4：验证归类效果\n\n```python\n# 验证根目录为空\nroot_items = get_knowledge_list(kb_id, limit=50) # 不带 folder_id\nremaining = [f for f in root_items if f.get(\"media_type\") != 99]\nassert len(remaining) == 0, f\"根目录仍有 {len(remaining)} 个散落文件\"\n\n# 验证每个文件夹的文件数符合预期\n```\n\n## 0.5 多层结构设计原则\n\n- **导览放父级**：父文件夹放主题导览，子文件夹**不需要**各自的导览\n- **MECE 划分**：子文件夹之间互斥、覆盖完整\n- **层级不超过 3 层**：超过 3 层说明分类需要重新设计\n- **避免\"其他\"类子文件夹**：用语义命名而非兜底类\n\n## 0.6 文件夹层级模式\n\n**模式 A：扁平**（推荐用于中等规模）\n\n```\n知识库根\n├── 文件夹 1\n├── 文件夹 2\n└── 文件夹 3\n```\n\n**模式 B：2 层嵌\n\nArchive v4.1.0: 16 files, 41093 bytes\n\nFiles: references/api-reference.md (7668b), references/cases/quantitative-investing.md (5448b), references/folder-organization.md (7169b), references/guide-template.md (5211b), references/incremental-update.md (3046b), references/link-handling.md (5230b), references/maintenance.md (2784b), references/reference.md (3511b), references/security.md (7269b), references/tagging.md (5136b), references/troubleshooting.md (6133b), references/versioning.md (2096b), references/write-and-verify.md (4477b), skill-card.md (1905b), SKILL.md (17413b), _meta.json (132b)\n\nArchive v4.0.0: 16 files, 40550 bytes\n\nFiles: references/api-reference.md (7591b), references/cases/quantitative-investing.md (5448b), references/folder-organization.md (7169b), references/guide-template.md (5211b), references/incremental-update.md (3046b), references/link-handling.md (5230b), references/maintenance.md (2784b), references/reference.md (3511b), references/security.md (6455b), references/tagging.md (5136b), references/troubleshooting.md (6133b), references/versioning.md (2096b), references/write-and-verify.md (4477b), skill-card.md (3088b), SKILL.md (16935b), _meta.json (132b)\n\nArchive v3.0.2: 5 files, 23935 bytes\n\nFiles: ERROR_FIXES_REPORT.md (1906b), references/reference.md (8491b), skill-card.md (2356b), SKILL.md (49027b), _meta.json (132b)\n\nArchive v3.0.1: 5 files, 23864 bytes\n\nFiles: ERROR_FIXES_REPORT.md (1906b), references/reference.md (8491b), skill-card.md (2476b), SKILL.md (48993b), _meta.json (132b)\n\nArchive v3.0.0: 5 files, 22699 bytes\n\nFiles: ERROR_FIXES_REPORT.md (1906b), references/reference.md (8491b), skill-card.md (2533b), SKILL.md (45423b), _meta.json (132b)\n\nArchive v2.0.2: 5 files, 11353 bytes\n\nFiles: references/reference.md (3950b), SKILL.md (9372b), wiki-compiler/references/reference.md (1940b), wiki-compiler/SKILL.md (6154b), _meta.json (132b)\n\nArchive v2.0.1: 5 files, 11350 bytes\n\nFiles: references/reference.md (3950b), SKILL.md (9357b), wiki-compiler/references/reference.md (1940b), wiki-compiler/SKILL.md (6154b), _meta.json (132b)","readmeExcerpt":"Skill: 知识库 Wiki 编译器 Owner: cookfish1979 Summary: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。 Tags: api-fix:5.0.2, cascade:5.0.2, compiler:5.0.2, folder-organization:4.1.0, ima:5.0.2, ingest:5.0.1, karpathy:5.0.2, knowledge:5.0.2, latest:5.0.2, lint:5.0.1, openclaw:4.1.0, ref","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Collect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6"},{"language":"text","snippet":"新文件被上传\n ↓\n计算与每个现有导览的相关性（标签 Jaccard + 文件夹归属 + 标题关键词）\n ↓\n相关度 > 0.5 的导览 → 加入\"待更新列表\"\n ↓\n用户确认（必选）\n ↓\n对每个候选导览：\n 1. export_note 读旧版\n 2. LLM 生成新版本正文\n 3. import_doc 创建新笔记（新 frontmatter：version/updated/changelog）\n 4. append_doc 在旧笔记末尾追加\"已被替代\"标记"},{"language":"yaml","snippet":"---\ntitle: 📖 主题导览：[主题名称]\ntype: guide\nconfidence: high | medium | low\ncreated: YYYY-MM-DD\nupdated: YYYY-MM-DD\nversion: 1.0\nchangelog:\n - v1.0: 初始版本\nsources:\n - [《文章1》](URL)\nrelated_guides:\n - [《另一导览》](URL)\n---"},{"language":"text","snippet":"wiki-compiler/\n├── SKILL.md ← 本文件（操作手册）\n└── references/\n ├── reference.md ← references/ 索引\n ├── ingest.md ← 🆕 Ingest 完整操作 + 级联算法\n ├── lint.md ← 🆕 Lint 4 类标准检查\n ├── schema.md ← 🆕 强制 frontmatter 契约\n ├── folder-organization.md ← Ingest 前置：文件夹整理\n ├── tagging.md ← Ingest 子任务：标签管理\n ├── security.md ← 破坏性操作保护\n ├── api-reference.md ← API 速查\n ├── guide-template.md ← 笔记撰写规范（含新 frontmatter）\n ├── versioning.md ← 版本控制\n ├── write-and-verify.md ← 写入与验证\n ├── link-handling.md ← 链接处理\n ├── troubleshooting.md ← 故障排查\n └── cases/\n └── quantitative-investing.md ← 实战案例"},{"language":"bash","snippet":"# 必需的环境变量\nexport IMA_OPENAPI_CLIENTID=\"你的ClientID\"\nexport IMA_OPENAPI_APIKEY=\"你的APIKey\"\n\n# 获取地址：https://ima.qq.com/agent-interface"},{"language":"python","snippet":"import urllib.request\nimport json\n\ndef ima_api(path, data=None):\n \"\"\"IMA OpenAPI 通用调用函数\"\"\"\n headers = {\n \"ima-openapi-clientid\": \"你的ClientID\",\n \"ima-openapi-apikey\": \"你的APIKey\",\n \"Content-Type\": \"application/json\"\n }\n url = f\"https://ima.qq.com/{path}\"\n req = urllib.request.Request(\n url,\n data=json.dumps(data or {}).encode('utf-8'),\n headers=headers,\n method=\"POST\"\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n return json.loads(resp.read().decode(\"utf-8\"))"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: wiki-compiler\nversion: 5.0.0\ndescription: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。\nlicense: MIT-0\nauthor: cookfish\nlast_updated: 2026-09-28\nhomepage: https://github.com/cookfish/wiki-compiler\n\nmetadata:\n openclaw:\n emoji: 🔧\n requires:\n primaryEnv: IMA_OPENAPI_APIKEY\n env:\n - IMA_OPENAPI_CLIENTID\n - IMA_OPENAPI_APIKEY\n---\n\n# 知识库 Wiki 编译器 v5.0.0\n\n> **技能版本**：v5.0.0 | 最后更新：2026-09-28 | 上一版：v4.1.0\n> **核心理念**：基于 Karpathy 的 LLM Wiki 模式 —— **\"Human curates, LLM maintains\"**\n> **三大操作**：Ingest（摄取）/ Lint（健康检查）/ Schema（契约）\n> **IMA 平台依赖**：需配置 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。获取方式：访问 https://ima.qq.com/agent-interface\n\n---\n\n## 快速开始\n\n### 场景 1：建新知识库\n用户：\"建一个关于 XXX 的知识库\" → **Ingest**（完整流水线）\n\n### 场景 2：导入新资料\n用户：\"导入这个网页\" / \"上传这个 PDF\" → **Ingest**（自动级联）\n\n### 场景 3：整理散落文件\n用户：\"按文件夹归类\" / \"整理散落文件\" → **Ingest 前置**（Folder Pre-Ingest）\n\n### 场景 4：维护知识库\n用户：\"检查知识库\" / \"健康检查\" → **Lint**（4 类标准检查）\n\n### 场景 5：增量更新导览\n用户：\"更新导览\" / \"导览新增了 N 篇文章\" → **Ingest**（增量模式）\n\n### 场景 6：标签管理\n用户：\"给知识库打标签\" / \"审查标签\" → **Ingest** 子任务（Schema 辅助）\n\n---\n\n## 核心理念\n\n### Karpathy 三大操作\n\n| 操作 | 职责 | 触发词 | 详见 |\n|------|------|--------|------|\n| **Ingest**（摄取） | 资料入库，编译/更新导览，级联多个相关导览 | \"建知识库\"\"导入网页\"\"上传文件\"\"更新导览\" | [ingest.md](references/ingest.md) |\n| **Lint**（健康检查） | 4 类标准检查：结构/矛盾/孤立/过期 | \"检查知识库\"\"健康检查\" | [lint.md](references/lint.md) |\n| **Schema**（契约） | 强制 frontmatter 规范（自动应用） | （无需用户触发）| [schema.md](references/schema.md) |\n\n**Query（查询）由 IMA search/fetch 完成，不归本 skill 管。**\n\n### 为什么这样设计\n\n- **Ingest**：知识库是\"会复利的资产\"，不是\"可检索的语料库\"\n- **Lint**：通过定期检查防止 wiki 衰败（类比代码世界的 `eslint`）\n- **Schema**：没有 schema，LLM 会天马行空；有了 schema，LLM 才守纪律\n\n> \"Human curates, LLM maintains\" — 人类决定收录什么，LLM 维护导览\n\n---\n\n## Ingest（摄取）\n\n### 子任务流水线\n\n```\nCollect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）\n ↓ ↓ ↓ ↓ ↓ ↓\n 阶段 1.1 阶段 1.2 阶段 1.3 阶段 1.4 阶段 1.5 阶段 1.6\n```\n\n### 关键子任务\n\n| 子任务 | 核心动作 | API |\n|--------|---------|-----|\n| **Collect** | 上传文件 / 导入网页 / 拉取已有 | `upload_file`, `import_urls`, `get_knowledge_list` |\n| **Check** | 搜索旧导览 | `search_note`（标题=\"主题导览\"）|\n| **Link** | 获取链接特性表 | `export_media_for_ima_sandbox` |\n| **Compile** | 新建/增量更新 | LLM 5 步法或 6 步法 |\n| **Write** | 创建/追加/编辑笔记 | `import_doc`, `append_doc`, `update_note` |\n| **Cascade** | **创建新版本导览 + 旧版保留历史**（知识复利）| `search_note` + Jaccard 算法 |\n\n详见 [references/ingest.md](references/ingest.md)\n\n### ⚠️ Karpathy 核心机制：知识复利（Cascade）\n\n> 一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）\n\n**IMA 实际可实现方式**：每个 Cascade 创建新 note_id（frontmatter 完整可控），旧版笔记保留作为历史。\n\n```\n新文件被上传\n ↓\n计算与每个现有导览的相关性（标签 Jaccard + 文件夹归属 + 标题关键词）\n ↓\n相关度 > 0.5 的导览 → 加入\"待更新列表\"\n ↓\n用户确认（必选）\n ↓\n对每个候选导览：\n 1. export_note 读旧版\n 2. LLM 生成新版本正文\n 3. import_doc 创建新笔记（新 frontmatter：version/updated/changelog）\n 4. append_doc 在旧笔记末尾"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b60cvvedv8jkxs5gy3m9c0d837e9f\",\n \"slug\": \"wiki-compiler\",\n \"version\": \"5.0.2\",\n \"publishedAt\": 1790596635214\n}"},{"path":"references/api-reference.md","content":"# API 速查\n\n> IMA OpenAPI 完整参考（基于 ima-knowledge 和 ima-note 最新文档对齐）。\n> 所有调用都依赖 `IMA_OPENAPI_CLIENTID` 和 `IMA_OPENAPI_APIKEY` 环境变量。\n\n## 1. 环境变量配置\n\n```bash\n# 必需的环境变量\nexport IMA_OPENAPI_CLIENTID=\"你的ClientID\"\nexport IMA_OPENAPI_APIKEY=\"你的APIKey\"\n\n# 获取地址：https://ima.qq.com/agent-interface\n```\n\n## 2. 通用调用函数（Python）\n\n```python\nimport urllib.request\nimport json\n\ndef ima_api(path, data=None):\n \"\"\"IMA OpenAPI 通用调用函数\"\"\"\n headers = {\n \"ima-openapi-clientid\": \"你的ClientID\",\n \"ima-openapi-apikey\": \"你的APIKey\",\n \"Content-Type\": \"application/json\"\n }\n url = f\"https://ima.qq.com/{path}\"\n req = urllib.request.Request(\n url,\n data=json.dumps(data or {}).encode('utf-8'),\n headers=headers,\n method=\"POST\"\n )\n with urllib.request.urlopen(req, timeout=15) as resp:\n return json.loads(resp.read().decode(\"utf-8\"))\n```\n\n## 3. 知识库 API（wiki/v1/*）\n\n### 3.1 读取类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 搜索知识库（含角色信息） | `openapi/wiki/v1/search_knowledge_base` | `query`, `cursor`, `limit` (1-20) | **推荐** 替代不存在的 `list_knowledge_bases` |\n| 列出知识库内容 | `openapi/wiki/v1/get_knowledge_list` | `knowledge_base_id`, `cursor`, `limit` (1-50) | 不带 folder_id 列出根目录 |\n| 按名称定位文件/文件夹 | `openapi/wiki/v1/search_knowledge` | `query`, `knowledge_base_id` | 获取位置和类型信息 |\n| 发现广场公开知识库 | `openapi/wiki/v1/search_knowledge_base_in_square` | `question`, `cursor`, `limit` (1-20) | 与 search_knowledge_base 不同 |\n| 导出媒体内容（COS URL）| `openapi/wiki/v1/export_media_for_ima_sandbox` | `media_id` | **返回 COS 链接需二次下载** |\n\n### 3.2 写入类\n\n| 功能 | 端点 | 关键参数 | 说明 |\n|------|------|---------|------|\n| 创建知识库 | `openapi/wiki/v1/create_knowledge_base` | `name`, `type` (1001个人/1002共享/1004订阅) | - |\n| 更新知识库信息 | `openapi/wiki/v1/update_knowledge_base_basic_info` | `id`, `update_fields` | 可选更新字段：1-名称, 2-封面, 3-简介, 4-推荐问题 |\n| 创建文件夹 | `openapi/wiki/v1/create_folder` | `knowledge_base_id`, `name`, `parent_folder_id` | - |\n| 重命名文件/文件夹 | `openapi/wiki/v1/rename_knowledge` | `media_id`, `new_name` | - |\n| 置顶/取消置顶 | `openapi/wiki/v1/set_knowledge_top` | `media_id`, `is_top` | - |\n| 移动文件 | `openapi/wiki/v1/move_knowledge` | `src_kb_id`, `dst_kb_id`, `dst_folder_id`, `infos` | **每次最多 10 个文件** |\n| 导入网页链接 | `openapi/wiki/v1/import_urls` | `knowledge_base_id`, `urls[]` | 批量导入 URL |\n| 上传文件 | `openapi/wiki/v1/upload_file` | `knowledge_base_id`, `file` | 走 COS 上传流程 |\n| 把已有笔记加入知识库 | `openapi/wiki/v1/add_knowledge` | `knowledge_base_id`, `media_id` | 虚拟关联（不改 parent_folder_id） |\n\n### 3.3 权限管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 改知识库权限 | `openapi/wiki/v1/update_knowledge_base_permission` | `knowledge_base_id`, `permission` |\n| 加入知识库 | `openapi/wiki/v1/join_knowledge` | `knowledge_base_id` |\n| 改文件访问状态 | `openapi/wiki/v1/update_knowledge_access_status` | `media_id`, `access_status` |\n\n### 3.4 标签管理\n\n| 功能 | 端点 | 关键参数 |\n|------|------|---------|\n| 给文件打标签 | `openapi/wiki/v1/tag_add` | `kb_id`, `item_id`, `item_name`, `tag_name` |\n| 从文件移除标签 | `openapi/wiki/v1/tag_rem"},{"path":"references/cases/quantitative-investing.md","content":"# 实战案例：量化投资知识库\n\n> 基于 2026-06-29 至 2026-07-01 在量化投资知识库（kb_id: `I_49nAThDICNno0gyhjl4dU1zUFtkNWv0X7mhlBQID8=`）的试跑总结。\n\n## 1. 知识库概况\n\n| 维度 | 数据 |\n|------|------|\n| 主题 | 量化投资（因子模型、机器学习、情绪分析等）|\n| 资料类型 | PDF、笔记、公众号文章、网页 |\n| 初始规模 | 35 个根目录散落文件 |\n| 最终规模 | 135 个文件，7 个顶层文件夹 |\n| 标签总数 | 244 个 |\n| 主题导览 | 7 个 |\n\n## 2. 阶段成果\n\n| 阶段 | 文件数 | 散落文件 | 标签 | 主题导览 |\n|------|:------:|:--------:|:----:|:-------:|\n| 初始 | 35 | 35 | 0 | 1 |\n| 演示后 | 36 | 35 | 20 | 1 |\n| 6 导览+30 打标 | 66 | 35 | 264 | 7 |\n| 归类后（move_knowledge）| 101 | 0 | 264 | 7 |\n| 多层归类后（PDF 单独处理）| 135 | 0 | 264 | 7 |\n\n**关键收获**：\n- 35 个根目录文件归类 → 0 散落\n- 14 个父文件夹文件移到子文件夹 → 结构清晰\n- 所有 244 个标签保留（移动文件前无标签，零风险）\n\n## 3. 最终文件夹结构\n\n```\n量化投资/\n├── 数据工具与入门/ （AkShare、聚宽、JQData 等）\n├── 金融情绪分析/ （情绪温度计、市场情绪等）\n├── 因子与资产定价/ （Fama-French、Alpha 因子等）\n├── 高频交易与微观结构/ （HFT、订单流等）\n├── 交易策略与系统/ （策略设计、回测等）\n├── AI 量化与深度学习/ （顶层）\n│ ├── 机器学习理论方法/\n│ ├── 大模型与智能体/\n│ └── 深度学习与预测模型/\n└── 主题导览（位于各文件夹）/\n ├── 📖 主题导览：数据工具与入门\n ├── 📖 主题导览：金融情绪分析\n ├── ...\n```\n\n**特点**：\n- 7 个顶层文件夹\n- AI 量化与深度学习含 3 个子文件夹（多层结构）\n- 父文件夹放主题导览，子文件夹不需要各自导览\n\n## 4. 关键词映射表\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n## 5. 试跑经验教训\n\n### 5.1 `item_name` 必须严格匹配完整标题\n\n完整标题包括扩展名（如 `.pdf`）和括号内容。\n\n```json\n// ❌ 简化标题（失败，code=220001）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易\"}\n\n// ✅ 完整标题（成功）\n{\"item_name\": \"金融人工智能：用Python实现AI量化交易 (伊夫-希尔皮斯科) (z-library.sk, 1lib.sk, z-lib.sk).pdf\"}\n```\n\n### 5.2 `limit` 参数范围 (0, 50]\n\n最大 50，超过会返回 51 错误。\n\n### 5.3 API 幂等性\n\n`tag_add` 重复打、`tag_remove` 移除不存在的——均直接返回成功。可放心重试和断点续传。\n\n### 5.4 `tag_remove` 完全可逆\n\n`tag_remove` 后文件 `tags` 字段变为 `[]`，不留痕迹。**`tag_delete` 才是不可逆的**。\n\n### 5.5 媒体类型覆盖建议\n\n试跑中覆盖了 PDF/笔记/公众号/网页（4 种）。未覆盖 Word/PPT/Excel/Markdown/视频/图片等。**真实场景使用前**建议覆盖完整 14 种类型。\n\n### 5.6 标签数量预期\n\n文章级标签每篇 3-5 个，128 篇内容的知识库预计产生 384-640 个标签。**标签总数 > 100 时建议人工审查命名规范**。\n\n### 5.7 `add_knowledge` ≠ `move_knowledge`（最关键）\n\n| 操作 | 行为 | parent_folder_id |\n|------|------|:----------------:|\n| `add_knowledge` | 文件\"展示\"在文件夹中（虚拟关联）| ❌ 不变 |\n| `move_knowledge` | 真正改变 `parent_folder_id` | ✅ 变为目标文件夹 |\n\n**仅调用 `add_knowledge` 不调用 `move`，文件会永远挂在根目录**。\n\n### 5.8 `move_knowledge` 会清空标签\n\n**应对模式**：\n1. 移动前备份标签\n2. 执行 `move_knowledge`\n3. 移动后逐个重新打标\n\n### 5.9 根目录调用 ≠ 知识库全貌\n\n不带 `folder_id` 调 `get_knowledge_list` 会返回**所有项目**（含 7 个文件夹 + 35 个散落文件 + 60 个已分配文件的\"虚拟副本\"）。\n\n**真正判断散落的方法**：比较文件的 `parent_folder_id` 与知识库根目录 ID。\n\n### 5.10 多层文件夹结构诊断\n\n复杂知识库需要**递归扫描**：\n\n```python\nfor folder in root_folders:\n items = get_knowledge_list(folder_id=folder.id)\n sub_folders = [f for f in items if f.type == 99]\n files = [f for f in items if f.type != 99]\n \n for sub in sub_folders:\n sub_items = get_knowled"},{"path":"references/folder-organization.md","content":"# 文件夹组织（阶段 0 详细）\n\n> 适用于：知识库结构混乱、文件散落在根目录、需要多层结构整理。\n\n## 0.1 三种\"文件夹\"操作\n\n| 操作 | API | 效果 | 何时使用 |\n|------|-----|------|---------|\n| **创建文件夹** | `create_folder` | 在知识库根目录建一个新文件夹 | 建立分类骨架 |\n| **虚拟归类** | `add_knowledge` | 让文件\"看起来\"在文件夹中（**parent_folder_id 不变**）| 临时展示 |\n| **物理归类** | `move_knowledge` | 真正修改 `parent_folder_id` 为目标文件夹 | 真正整理 |\n\n**关键警告**：\n- `add_knowledge` 创建的是\"虚拟关联\"，**不改变 `parent_folder_id`**\n- 仅用 `add_knowledge` 而不调用 `move_knowledge`，文件永远挂在根目录\n- 根目录调用 `get_knowledge_list` 会返回所有文件（包括已\"虚拟关联\"的），但这不代表它们真正归属于文件夹\n\n## 0.2 诊断流程\n\n### 步骤 1：拉取知识库根目录\n\n```bash\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/get_knowledge_list\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"knowledge_base_id\": \"\", \"limit\": 50}'\n```\n\n### 步骤 2：识别散落文件\n\n```python\nROOT_FOLDER_ID = \"<知识库根目录 ID>\" # 通常通过 get_knowledge_base 获取\n\norphans = [f for f in root_items\n if f.get(\"media_type\") != 99\n and f.get(\"parent_folder_id\") == ROOT_FOLDER_ID]\n```\n\n### 步骤 3：递归扫描文件夹层级\n\n对每个文件夹调用 `get_knowledge_list(folder_id=...)`，记录：\n- 子文件夹（`media_type == 99`）\n- 文件数\n- 每个文件的 `parent_folder_id` 是否等于当前 `folder_id`\n\n### 步骤 4：分类汇总\n\n| 状态 | 含义 | 处理方式 |\n|------|------|---------|\n| 文件 `parent_folder_id` 是根目录 | 真正散落 | 用 `move_knowledge` 归类 |\n| 文件 `parent_folder_id` 是文件夹 ID | 已归类 | 仅检查是否需要打标签 |\n| 文件仅在根目录返回但 parent 是文件夹 | 虚拟关联 | 已正确处理 |\n\n## 0.3 诊断输出模板\n\n```markdown\n## 知识库结构诊断报告\n\n### 顶层文件夹\n| 文件夹 | 文件数 | 含子文件夹 |\n|--------|:------:|:----------:|\n| ... | ... | ... |\n\n### 散落文件\n- 共 X 个文件 `parent_folder_id` 是根目录\n- 列出每个文件的标题和推荐目标文件夹\n\n### 多层结构\n- AI 量化与深度学习/\n - 机器学习理论方法/（Y 个文件）\n - 大模型与智能体/（Y 个文件）\n - ...\n\n### 处理建议\n- 散落文件：调用 `move_knowledge` 归类\n- 多层结构：导览放父级，子文件夹不需要各自导览\n```\n\n## 0.4 归类流程\n\n### 步骤 1：列出待归类文件\n\n```python\n# 从诊断报告中获取散落文件\norphans = [(f[\"media_id\"], f[\"title\"]) for f in orphan_files]\n```\n\n### 步骤 2：推荐目标文件夹\n\n关键词匹配模式（参考实战案例）：\n\n| 关键词模式 | 推荐目标文件夹 |\n|-----------|---------------|\n| AkShare、BaoStock、OpenClaw、JQData、MooTdx、聚宽、a-stock-data、数据源、入门 | 数据工具与入门 |\n| HFT、harris、Athena、净订单、信息差、微观结构、高频 | 高频交易与微观结构 |\n| 情绪、a-share-sentiment | 金融情绪分析 |\n| Fama-French、因子、融资融券、IF基差、基差、散户、定价、动量、反转、隔夜、华尔街 | 因子与资产定价 |\n| Qlib、AI、Claude、智能体、遗传算法、深度学习、神经网络、图神经网络、LLM | AI 量化与深度学习（顶层）|\n| 多层 AI 量化子文件夹 | 机器学习理论方法 / 大模型与智能体 / 深度学习与预测模型 |\n| 其他（兜底） | 交易策略与系统 |\n\n> 关键词表针对量化投资领域；其他领域需重新设计。\n\n### 步骤 3：批量调用 `move_knowledge`\n\n```bash\n# 移动到目标文件夹（src_kb_id == dst_kb_id 表示知识库内移动）\ncurl -s -X POST \"https://ima.qq.com/openapi/wiki/v1/move_knowledge\" \\\n -H \"ima-openapi-clientid: $IMA_OPENAPI_CLIENTID\" \\\n -H \"ima-openapi-apikey: $IMA_OPENAPI_APIKEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"src_knowledge_base_id\": \"\",\n \"dst_knowledge_base_id\": \"\",\n \"dst_folder_id\": \"\",\n \"dst_folder_name\": \"\",\n \"infos\": [{\"media_id\": \"\"}, {\"media_id\": \"\"}]\n }'\n```\n\n**注意**：每次最多 10 个文件，分批调用。\n\n### ⚠️ `move_knowledge` 的副作用\n\n| 副作用 | 说明 |\n|--------"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。 Skill: 知识库 Wiki 编译器 Owner: cookfish1979 Summary: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说\"建知识库\"\"整理资料库\"\"编译知识库\"\"搭建wiki\"\"知识体系化\"\"把资料整理成wiki\"\"给知识库打标签\"\"按标签分类\"\"标签整理\"\"按文件夹归类\"\"整理散落文件\"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。 Tags: api-fix:5.0.2, cascade:5.0.2, compiler:5.0.2, folder-organization:4.1.0, ima:5.0.2, ingest:5.0.1, karpathy:5.0.2, knowledge:5.0.2, latest:5.0.2, lint:5.0.1, openclaw:4.1.0, ref","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1074,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T11:55:50.613Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:44:48.565Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}