Scope / 建议范围

knowledge-query / knowledge-ingest / knowledge-lint

Background / 背景与问题

在两轮 micro-cann-bench 知识库 A/B 实验（16 算子 × 2 版本 = 32 个 cannbot agent 单元，模型 glm-5.3，知识库经官方 install.sh opencode consumer 安装）中，统计了 agent 发起的全部检索调用：

• 共 242 次 knowledge_query.py search，其中 66 次（27%）因漏传 --platform 失败（主线 da6d4e6c 批 34/145，PR #55 头 82e5ca7d 批 32/97）。两个版本比例一致，说明是长期存在的易用性问题，与近期检索改动无关
• 失败模式：错误 JSON 输出到 stderr、退出码 2；而 agent 的常见管线是 search ... | python3 -c "json.load(...)" 只解析 results 字段——错误被静默吞掉，agent 看不到失败原因，基本不重试，直接放弃该次检索
• 极端案例：quant_matmul 单元 13 次检索中 5 次因漏 platform 无效（含一次 SetQuantVector 查询——实测该查询在两个版本下都能 rank 5-6 命中目标算子卡），该算子最终 10 次远评预算耗尽失败；对照批次同算子 4 次提交通过

Desired outcome / 期望结果

1. 漏传 --platform 时不再直接失败，有可用回退
2. 检索失败对管道消费方可见（不被 json 解析静默吞掉）

Proposal / 建议方案（可选，供讨论）

• .cannbot/knowledge.env（install.sh 已写入 ROOT/PROFILE）增加 CANNBOT_KNOWLEDGE_PLATFORM，search 未传 --platform 时回退该默认值；无默认值再报错
• 错误 JSON 同时输出到 stdout（当前仅 stderr）
• SKILL.md / cli.md 面向 agent 的示例命令把 --platform 放进第一条示例

Impact / 影响与兼容性

• 显式传 --platform 的调用不受影响（默认值仅作回退）；平台/知识根定位已有 .cannbot/knowledge.env 机制，复用同一文件与现有设计一致
• 按实测口径，可挽回约 27% 的 agent 检索调用