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.json3.2 核心模块能力定义与推断agent-harness/cli_anything/gear/core/capability_taxonomy.py场景动态索引含 capabilities/riskFlagsagent-harness/cli_anything/gear/core/scenario_index.pyNL 编译能力约束前置评分agent-harness/cli_anything/gear/core/plan_intent.pyPlan 解析strict 缺口报告 持久化检查agent-harness/cli_anything/gear/core/plan_resolver.pyCLI 命令扩展agent-harness/cli_anything/gear/gear_cli.py3.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 首选可运行场景。预防每次改动后执行中文冒烟测试。坑 2plan-compile --strict通过但plan-from-nl --strict在 resolve 失败现象前后阶段结果不一致。根因compile 与 resolver 评分模型不一致。修复统一 resolver 能力加权逻辑前后模型对齐。预防新增“同一提示词 strict 全链路”回归。坑 3strict 对真实可复用场景过度惩罚现象重复使用同一可执行场景被强罚导致低置信失败。根因重复路径惩罚过重-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 单元回归PYTHONPATHagent-harness pytest -q agent-harness/cli_anything/gear/tests/test_core.py5.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_e2eRUN_GEAR_E2E1 pytest -q agent-harness/cli_anything/gear/tests/test_full_e2e.py::test_chinese_prompt_smoke_e2e6. 规范化流程建议固定commands --json能力边界plan-from-nl --strict --no-execute语义到计划plan-audit路径/证据审计plan-validateschemaplan-dry-run执行预演plan-run真实执行report-compare回归对比