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 单元回归
bash
复制代码
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
bash
复制代码
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 业务逻辑？（禁止）