IMA笔记知识库同步

这个技能解决什么问题

IMA 的「个人笔记」和「个人知识库」在产品上是两套入口。笔记负责日常随手记录，知识库则是筛选后的沉淀集合。但两边状态很容易漂移：新笔记写完忘了挂进知识库，旧笔记删掉之后知识库里还留着失效关联。本技能做的事情很收敛——以笔记为真相源，把知识库补成一份镜像索引：笔记侧存在的条目，知识库必须有对应关联；笔记已删除的条目，知识库里的关联要能被识别并清理。

工作原理

匹配键与同步规则

同步以 note_id 作为唯一匹配键。知识库中 media_type=11 的条目，其 note_info.content_id 就是笔记 ID。两侧数据拉取完整后做集合差集，得到两类差异：

• 待新增：笔记存在、知识库无关联 → 调用 add_knowledge 建立引用
• 待清理：笔记已删除、知识库仍有关联 → 列出标题并等待用户确认后移除
• 已同步：两边都存在 → 直接跳过，因为知识库存的是笔记 ID 引用，内容变更实时生效，无需重复同步

三种执行模式

通过 --mode 参数控制行为边界：

• diff：只统计差异，不调用任何写入 API，适合先看清现状
• sync：只做新增、不涉及删除，安全无风险
• full：新增 + 清理，必须显式传 --confirm 才会执行删除

关键约束

前置依赖不可跳过：需要 ima-skills 父级 Skill 的 ima_api.cjs，以及 ~/.config/ima/client_id 与 ~/.config/ima/api_key 凭证配置。批量写入时每批 10 条、间隔 500ms，遇到 20002 限频错误自动退避 2 秒重试。鉴权失败（20004）直接终止同步，无权限（100005）则跳过并汇总进失败列表。

适用边界

• 清理操作只移除知识库中的关联条目，不会删除笔记本身——笔记仍留在「我的笔记」里
• 目标知识库用 --kb-name 模糊匹配，命中第一个结果；重名场景建议改用 --kb-id 精确指定
• 本技能是 ima-skills 的扩展子技能，编码规则、凭证配置等强制约束继承自父级，未独立实现鉴权