Harness 设计指导
任务目标
- 本 Skill 用于：指导工程师在设计 AI Agent 系统时，让架构符合 Harness 思想
- 能力：
- 诊断 AI 系统的 Harness 成熟度（M0-M4）
- 逐层逐项检查六大原则对齐情况
- 识别典型 Harness 反模式
- 输出分层补全建议与 P0/P1/P2 行动清单
- 支持迭代诊断，追踪改进轨迹
- 触发：用户设计 AI 系统、排查 Agent 问题、评审架构方案、询问 Harness 落地方法
前置准备
- 依赖说明：Python 3.x（诊断脚本运行环境）
- 非标准文件准备：无
操作步骤
阶段一：信息采集与现状理解
- 智能体主动提问，逐步收集用户的 AI 系统现状信息（遵循渐进披露原则，不让用户一次全量倾倒）
- 采集项及引导话术：
- 系统定位：询问"你的 Agent 要解决什么问题？服务什么业务场景？"
- 当前架构组件：询问"目前系统里有哪些组件？比如工具调用、记忆机制、验证环节、权限控制等"
- 已知痛点：询问"目前遇到过什么问题？比如跑偏、烂尾、自评失真、上下文过长等"
- 模型与规模：询问"用的什么模型？任务一般多长？并发规模多大？"
- 基于采集结果，智能体整理出结构化的现状描述
阶段二：Harness 成熟度诊断
- 智能体将采集信息映射为诊断输入（遵循以下映射启发规则）：
架构层（L1-L6）映射启发：
- 用户提到"有工具调用/API 接入" → L2 工具系统层 covered
- 用户提到"有任务拆解/分步执行/工作流" → L3 执行编排层 covered
- 用户提到"有记忆/上下文管理/进度文件/AGENTS.md" → L4 记忆与状态层 covered
- 用户提到"有独立验证/质检/评估环节/测试" → L5 评估与观测层 covered
- 用户提到"有权限控制/沙箱/回滚/安全边界" → L6 约束、校验与恢复层 covered
- 用户提到"有角色定义/信息过滤/任务聚焦" → L1 信息边界层 covered
- 无法判断的层 → 不标记（脚本视为 missing）
原则映射启发：
- 用户说"出问题先查环境不是换模型" → env-first: true
- 用户说"有独立评估/不让 Agent 自己判" → gen-eval-decouple: true
- 用户说"有任务拆解和结构化交接" → structured-ctrl: true
- 用户说"模型升级后会调整 Harness" → dynamic-adapt: true
- 用户说"按需给信息/分层文档" → progressive-info: true
- 用户说"犯错改环境不是改 Prompt" → debug-env: true
- 用户明确说"没有"或"不是" → 对应原则 false
- 无法判断 → 对应原则 unknown（不参与评分）
反模式映射启发：
- 用户说"靠 Prompt 约束权限" → prompt-permission: true
- 用户说"把所有信息塞进上下文" → context-dump: true
- 用户说"让 Agent 自己评估结果" → self-eval: true
- 用户说"中断后只能重来" → no-recovery: true
- 用户说"工具很多很细" → over-tool: true
- 用户说"没有明确的完成定义" → no-sprint: true
- 用户明确说"没有这个问题" → 对应反模式 false
- 无法判断 → 对应反模式 unknown（不参与扣分）
- 调用诊断脚本进行参考评分：
```
python3 ./scripts/harness-diagnose.py --layers L1,L2,L3 --principles env-first:true,gen-eval-decouple:false,structured-ctrl:unknown --antipatterns prompt-permission:true,context-dump:false,self-eval:unknown
```
注：principles 和 antipatterns 支持 true/false/unknown 三种值，unknown 项不参与评分
- 脚本输出 JSON 格式的诊断结果，包含：
- 六层架构覆盖度评分
- 六大原则对齐度评分（排除 unknown 项）
- 反模式扣分（排除 unknown 项）
- 综合评分（0-100）
- 成熟度等级（M0-M4）
- 诚实对待评分：脚本是参考评分工具，提供一致的评分公式和可复现的计算，但输入本身来自智能体的主观映射，因此评分应定位为"参考指标"而非"客观诊断"。向用户呈现时需说明此局限。
阶段三：诊断解读与指导建议
- 逐层解读诊断结果：
- 对每层架构，说明覆盖/缺失意味着什么、具体风险是什么
- 对每条原则，说明对齐/不对齐/未知的实际影响
- 对每个反模式，说明危害和正确做法
- 输出分层补全方案：
- 针对缺失/薄弱层，给出"应该加什么、怎么加"的方向性建议
- 参考 references/ 中的三角色架构和行业实践
- 遵循渐进披露：先输出最关键的缺口，不一次全量输出
- 输出 P0/P1/P2 行动清单：
- P0（马上能做）：写 AGENTS.md、建立独立验证、加权限分层、自定义 Linter、知识进仓库
- P1（稳了再补）：上下文压缩重置、多 Agent 协作交接、Sprint 契约、端到端测试、进度文件
- P2（有余力再考虑）：可观测性体系、自动化合规、全链路审计、动态适配审查、弹性伸缩
- 动态适配提醒：提示用户哪些组件随模型升级可能需要调整或剥离
阶段四：迭代优化与验证闭环
- 建议用户将诊断结果和补全方案纳入 AGENTS.md 或项目文档
- 建议建立"错误→规则"反馈机制（Harness 第 6 条原则：每次 Agent 犯错，改 Harness 而非改 Prompt）
- 建议用户调整架构后再次触发诊断，对比前后成熟度变化
- 当模型升级时，提醒用户重新审视 Harness 组件的承重/可剥离标记
资源索引
脚本工具
- scripts/harness-diagnose.py
- 用途：提供一致的评分公式，计算 Harness 成熟度参考评分，输出结构化诊断结果（JSON）
- 触发时机：阶段二诊断环节，当智能体完成信息采集并映射为诊断输入后调用
- 脚本使用说明：
- 诊断评分：
python3 ./scripts/harness-diagnose.py --layers L1,L2,L3 --principles env-first:true,gen-eval-decouple:false --antipatterns prompt-permission:true,self-eval:false - 支持 unknown：
python3 ./scripts/harness-diagnose.py --principles env-first:true,gen-eval-decouple:unknown（unknown 项不参与评分） - 查看评分标准：
python3 ./scripts/harness-diagnose.py --json - 参数说明：
--layers：已覆盖的架构层，逗号分隔，可选值 L1-L6--principles：原则对齐情况，格式 key:true/false/unknown，可选键：env-first, gen-eval-decouple, structured-ctrl, dynamic-adapt, progressive-info, debug-env--antipatterns：反模式检测，格式 key:true/false/unknown，可选键：prompt-permission, context-dump, self-eval, no-recovery, over-tool, no-sprint
参考文档
注意事项
- 附件读取规则：阶段三输出指导建议前，必须读取 references/harness-principles.md 获取原则定义和架构细节，确保建议准确且有据可依
- 脚本调用规则：阶段二诊断评分建议调用 scripts/harness-diagnose.py，脚本提供一致的评分公式和可复现的计算，但输入来自智能体主观映射，评分是参考指标而非客观诊断
- 渐进披露原则：信息采集时分步提问，指导输出时先给最关键的缺口和建议，不一次全量倾倒
- 评分局限性：脚本的输入（层覆盖/原则对齐/反模式检测）由智能体根据用户描述映射，不同智能体可能映射出不同结果，评分仅供参考，向用户呈现时需说明此局限
- 不替代人工决策：关键架构决策（如权限分级策略、Sprint 契约设计、模型选型）由工程师拍板，Skill 只提供诊断和建议
- 不写具体代码：Skill 输出的是架构层面的方向性指导，不替用户写 Agent 代码或工具实现代码
- 简单场景可跳过脚本：如果用户只是简单咨询（如"我的 Agent 老跑偏怎么办"），可以直接基于 references/ 给出建议，不必走完整的四阶段诊断流程