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 分层职责（强约束）

• 语义层：NL -> Plan（结构化）。
  
• 能力层：工位需求与场景能力对齐（capability taxonomy）。
  
• 执行层：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 但三站场景雷同或不可执行

• 现象：多站都指向同一个低质量场景，执行失败或超时。
  
• 根因：早期仅关键词匹配，未纳入执行风险与能力缺口。
  
• 修复：
  
  
  • 引入 capabilities 打标。
    
  • 引入 riskFlags（如 sampling:stability_quantity_zero, timeout:long）降权。
    
  • 非 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 单元回归

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
    
  
  

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

复制代码

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

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

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

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！