野生码农
IMA 知识库打通终局:误推 34 条换来的探针先行铁规
背景与目标
本地 kb 知识库(sqlite + FTS5,1700+ 条)是事实主库,腾讯 IMA 定位是云端语义检索前端——手机上随时用自然语言问自己的知识。
通道代码 2026-07 就建好了(kb/sync_ima.py),但本人一问三不知:"是不是已经打通了?这个一直没有用起来。"
目标:查清断在哪、修通、把全量本地知识按目录规划推进 IMA「军师天团」知识库。
过程回顾
尝试 1:现状核查。结果:1680 条只推过 3 条(2026-07-21,全走笔记降级通道,主通道当时就没跑顺);实测旧凭据调 API 返回 401——不是"没用起来",是"想用也用不了"。
尝试 2:换凭据+定目标库。本人发来新 Client ID/API Key,setx 持久化,实测连通;本人新建「军师天团」知识库,kb.toml 固定 knowledge_base_id 指向它。
尝试 3:目录规划。本人要求"先建对应目录再推送"。查明 IMA OpenAPI 十个接口里没有创建文件夹接口——文件夹只能客户端手建。分工:本人建 9 个文件夹,军师派单 coder 给 sync_ima.py 加 folder_map 路由(本地路径前缀→文件夹名,最长前缀优先,未命中推根目录)。dry-run 验收通过。
尝试 4:归档收口。本人裁定「个人工作计划总结」不跟踪、不写入、归档,"其他地方一并设置"。三通道(evernote pull/push、IMA)一致收口,新增 archived_mirror 机制。
尝试 5:全量推送。开跑 30 秒内日志全量刷"找不到文件夹,推根目录"警告——急停。此时已有 34 条误推根目录。
尝试 6:修复+探针+放量。修 bug → 单条探针 → 本人手动删 34 条 → 9 文件夹全探针 → 全量 1336 条零失败 → 对账 1345=1345 全平。
关键踩坑
坑 1:API 文档与现实两层偏差(本次最大翻车)
- 现象:folder_map 代码逻辑全对、dry-run 全绿,一上真实 API 全部"找不到文件夹"。
- 根因:文档写文件夹是 FolderInfo(
folder_id/name字段);实际返回里文件夹混在knowledge_list中,media_type=99、media_id="folder_<数字id>"、名字在title字段——字段名、结构全对不上。更阴的是第二层:add_knowledge的folder_id传纯数字部分报222000 文件夹不存在,必须传完整"folder_..."形式。 - 解决:按实测结构重写
_fetch_root_folders,单条探针(id=1908)实测落「工作」文件夹,再 API 复核在库。 - 教训:dry-run 覆盖不到远端数据结构。对接外部 API 的改动,dry-run 全绿只证明本地逻辑对,不证明能跑通。
坑 2:归档方案差点引爆 371 条远端删除
- 现象:把归档目录加进 evernote
push_exclude,dry-run 立刻显示 371 条[retract]。 - 根因:这些文件是当年从印象笔记拉下来的镜像,带远端 GUID;
push_exclude语义是"撤回"=删除远端笔记进废纸篓。真实执行会把本人印象笔记"工作"笔记本的原件全删掉。 - 解决:新增
archived_mirror配置(不拉不推、保留远端),config.py镜像判定并集归档目录。改后 dry-run 撤回 0。 - 教训:排除≠撤回。同一个"不上云"诉求,在不同同步语义下一个是跳过、一个是删除。
坑 3:stdout 块缓冲,进度黑盒
首次推送管道接 tee | tail,Python stdout 块缓冲,警告(stderr)看得见、"完成"(stdout)全卡在缓冲区,误判"0 完成"。重跑统一 python -u。
最终方案
- 推送链:
python -m kb push ima→ 哈希幂等(未变跳过)→ folder_map 路由到 9 文件夹 → create_media + COS 直传(HMAC-SHA1 签名)→ add_knowledge(folder_id传完整folder_形式),COS 失败降级笔记通道; - 隐私闸:
ima.exclude= 个人档案 + 个人工作计划总结(372 条不上云); - 放量前四道闸:根目录预检 → 旧库 3 条解绑(7 月推到旧库的条目 hash 未变会被跳过、永远进不了新库)→ 9 文件夹全探针逐库 API 复核 → 开跑 30 秒健康检查(0 警告才继续)。
做得好的地方
- 急停果断:警告刷屏 30 秒内停任务,损失锁定在 34 条而不是 1343 条;
- 本人"目录先行"的要求逼出了 folder_map 机制,知识库不是一坨堆进去的;
- "其他地方一并设置"一句话触发全通道扫描,抓出 retract 雷;
- 收尾对账走到最终动作:逐文件夹 API 点数与本地 SQL 计数全平,不是"脚本报成功就算完"。
复盘与改进
最大失分在军师:coder 子代理交付只跑了 dry-run 就放行放量,本人为此手动删了 34 条("我一条一条删的,你可千万不要再传错了")。
改进一条(立为铁规):派单改外部 API 对接代码,验收标准必须含"真实 API 单条探针实测",dry-run 不算验证。 已落 docs/config-ledger.md(2026-09-25 sync_ima 修复行)。
次要失分:台账编辑误吞一行(当场修复);归档初版方案差一步引爆 retract(自己 dry-run 抓到,未造成损失)。
成长评估
| 维度 | 分 | 证据 |
|---|---|---|
| 指令与提示词质量 | 8 | "设置以后推送到这个知识库""先建目录再推送"短指令零歧义直执行;"其他地方一并设置"五字触发全通道收口。纠偏仅 1 次(误推后要求不再传错) |
| 判断与结论 | 8.5 | 新建独立「军师天团」库分流(不混个人库)、「个人工作计划总结」归档裁定果断且正确(371 条历史不该上云) |
| 思维方式 | 8.5 | "目录没有规划,先建目录再推送"=结构先行,拒绝一坨堆;归档意识超前于推送动作 |
| 最终结果与产出 | 9 | 1345/1345 逐库全平、0 失败、0 残留;通道从"7 月推过 3 条"到全量启用 |
| AI 协作能力 | 8 | 配合完成客户端手建 9 文件夹、手删 34 条;"千万不要再传错"明确了信任修复条件,而不是泛泛抱怨 |
AI 自评失分点:①coder 交付未要求真实 API 探针就放量(最大失分,成本=本人手删 34 条);②归档初版方案险触 retract;③首跑 stdout 缓冲致进度黑盒。
指令实证:
- "个人工作计划总结 这个文件夹不跟踪,不写入,归档了,其他地方一并设置"——"一并"二字把动作从单点配置升级为全通道一致性扫描,直接抓出"push_exclude=retract 删远端 371 条"的隐藏雷,产出
archived_mirror新机制。证据:kb.tomlevernote/ima 两段、kb/config.pypull_extra_local_names、docs/config-ledger.md2026-09-25 归档收口行。 - "你可千万不要再传错了,再传错我这个吃不消"——把放量流程从"修完就跑"改写为四道闸(预检/全探针/逐库复核/健康检查),直接结果是 1336 条零失败、对账全平。证据:
data/ima_push_20260925.log(0 警告)、逐文件夹对账输出 9/9 OK。
单次分数 ±0.5 为噪声,只看跨期趋势;本期指令质量与上期(欠账清理批 9 分)同档,短指令高杠杆的特征稳定。
素材点
- "API 文档和现实有两层偏差,dry-run 全绿也照翻"——可做技术踩坑媒体稿;
- "排除≠撤回:一个配置项差点删掉 371 条云端笔记"——同步语义陷阱,通用性强;
- "1345 条个人知识上云,逐文件夹对账全平"——知识管理双库体系(本地关键词库+云端语义库)可做教程稿;
- "探针先行"铁规的诞生现场——成本是本人手动删 34 条,故事性足。