CLI-Anything + Gear 最佳实践与踩坑修复沉淀

1. 目标与边界

1.1 目标

• 让用户通过自然语言输入（中文为主）生成可执行的 gear-plan-v1。
• 全链路保持可审计：NL -> plan -> validate -> dry-run -> run -> report。
• 支持工业电检高频场景（绝缘/耐压/功能）并可持久化到 CSV/SQLite。

1.2 边界

• cli-anything-gear 负责语义规划与编排，不复制 Gear 业务执行逻辑。
• GearCLI 负责严格执行与结果输出。
• 原业务代码最小改动，优先在 agent-harness/cli_anything/gear 层完成能力增强。

---

2. 最终确认的最佳实践（已落地）

2.1 分层职责（强约束）

1. 语义层：NL -> Plan（结构化）。
2. 能力层：工位需求与场景能力对齐（capability taxonomy）。
3. 执行层：GearCLI 只接 plan / 强类型参数，严格执行。

2.2 strict 原则

• strict 模式不猜测：信息不足/能力缺口/低置信度直接失败。
• 失败必须返回可修复信息：候选、分数、原因、能力缺口。

2.3 可扩展原则

• 不做“关键词硬编码大全”。
• 用“工位意图 + 能力模型 + 动态场景索引”替代设备/命令硬绑定。

---

3. 关键实现（已完成）

3.1 taxonomy

• 工位词典：
  • agent-harness/cli_anything/gear/scenarios/station_taxonomy.json
• 能力词典：
  • agent-harness/cli_anything/gear/scenarios/capability_taxonomy.json

3.2 核心模块

• 能力定义与推断：
  • agent-harness/cli_anything/gear/core/capability_taxonomy.py
• 场景动态索引（含 capabilities/riskFlags）：
  • agent-harness/cli_anything/gear/core/scenario_index.py
• NL 编译（能力约束前置评分）：
  • agent-harness/cli_anything/gear/core/plan_intent.py
• Plan 解析（strict 缺口报告 + 持久化检查）：
  • agent-harness/cli_anything/gear/core/plan_resolver.py
• CLI 命令扩展：
  • agent-harness/cli_anything/gear/gear_cli.py

3.3 新增/增强命令

• scenario-index：输出 tokens/actionKeys/nodeTypes/capabilities/riskFlags。
• station-taxonomy：输出工位语义映射。
• capability-taxonomy：输出能力需求映射。
• plan-from-nl：受控阶段执行（compile->resolve->audit->validate->dry-run->optional run）。

---

4. 典型踩坑与修复闭环

坑 1：生成三站 plan 但三站场景雷同或不可执行

• 现象：多站都指向同一个低质量场景，执行失败或超时。
• 根因：早期仅关键词匹配，未纳入执行风险与能力缺口。
• 修复：
  1. 引入 capabilities 打标。
  2. 引入 riskFlags（如 sampling:stability_quantity_zero, timeout:long）降权。
  3. 非 strict 模式允许回退到 taxonomy 首选可运行场景。
• 预防：每次改动后执行中文冒烟测试。

坑 2：plan-compile --strict 通过，但 plan-from-nl --strict 在 resolve 失败

• 现象：前后阶段结果不一致。
• 根因：compile 与 resolver 评分模型不一致。
• 修复：统一 resolver 能力加权逻辑，前后模型对齐。
• 预防：新增“同一提示词 strict 全链路”回归。

坑 3：strict 对真实可复用场景过度惩罚

• 现象：重复使用同一可执行场景被强罚，导致低置信失败。
• 根因：重复路径惩罚过重（-10）。
• 修复：调整为温和惩罚（-3），允许合理复用。
• 预防：保留惩罚但不阻断真实工艺复用。

坑 4：能力识别漏判（如 MeasureVoltage/ResTester_1）

• 现象：出现“能力缺口”误报。
• 根因：仅精确词命中。
• 修复：改为“精确 + 子串”识别。
• 预防：固定样例覆盖不同表达和 token 形式。

坑 5：测试环境不一致导致假失败

• 现象：python -m cli_anything.gear 报 click 缺失。
• 根因：解释器/虚拟环境不一致。
• 修复：E2E 默认调用 cli-anything-gear 二进制（支持 GEAR_CLI_BIN 覆盖）。
• 预防：统一 .venv + pip install -e .。

---

5. 标准门禁（每次改动必须执行）

5.1 单元回归

PYTHONPATH=agent-harness pytest -q agent-harness/cli_anything/gear/tests/test_core.py

5.2 中文冒烟回归（新增）

• 样例集文件：
  • agent-harness/cli_anything/gear/scenarios/SMOKE_PROMPTS.zh-CN.json
• 冒烟测试：
  • agent-harness/cli_anything/gear/tests/test_full_e2e.py::test_chinese_prompt_smoke_e2e

RUN_GEAR_E2E=1 pytest -q agent-harness/cli_anything/gear/tests/test_full_e2e.py::test_chinese_prompt_smoke_e2e

---

6. 规范化流程（建议固定）

1. commands --json（能力边界）
2. plan-from-nl --strict --no-execute（语义到计划）
3. plan-audit（路径/证据审计）
4. plan-validate（schema）
5. plan-dry-run（执行预演）
6. plan-run（真实执行）
7. report-compare（回归对比）

---

7. 防跑偏清单（执行前自检）

• 是否把自由文本直接交给 GearCLI 执行？（禁止）
• 是否绕过 strict 且没有人工审查？（禁止）
• 是否新增能力但未更新 taxonomy？（禁止）
• 是否修改匹配逻辑但未跑中文冒烟？（禁止）
• 是否在 harness 里复制 Gear 业务逻辑？（禁止）

---