# cowboy-harness **Repository Path**: zyh-soft/cowboy-harness ## Basic Information - **Project Name**: cowboy-harness - **Description**: Harness工程开发模式技能包 - 端到端的软件工程开发流程管理体系。包含设计、编码、测试、质量、部署全生命周期，集成CI/CD能力和代码-设计一致性验证。适用场景：(1) 新项目启动；(2) 功能开发；(3) 代码重构；(4) 质量提升。触发关键词：harness开发模式、工程化、软件开发流程、DevOps、CI/CD、质量门禁 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 27 - **Forks**: 4 - **Created**: 2026-06-03 - **Last Updated**: 2026-09-18 ## Categories & Tags **Categories**: ai **Tags**: None ## README --- name: harness-loop description: Harness工程化开发多Agent协作系统 - 端到端的软件工程开发流程管理体系。Harness Agent统筹调度8个子Agent（Preprocess/SA/Design/Coder/Tester/Showcase/CMO + Evaluate），覆盖预处理(PRD生成)→规格编写→架构设计→编码实现→质量评估→质量验证→设计一致性验证全生命周期。适用场景：(1) 新项目启动；(2) 功能开发；(3) 代码重构；(4) 质量提升。触发关键词：harness开发模式、工程化开发、多Agent协作、软件开发流程、DevOps、CI/CD、质量门禁、showcase、设计验证 --- # Harness工程化开发 - 多Agent协作系统 ## 概述 Harness工程化开发是一套完整的多Agent协作软件工程开发体系，融合了**Harness工程开发模式**和**规范驱动开发(SDD)**的核心能力。通过Harness主Agent编排8个子Agent（7个执行+1个评估评分），实现从需求到交付的全链路闭环管理。 ## 系统架构 ``` 用户需求 │ ▼ ┌──────────┐ │ Harness │ 主Agent（primary）- 统筹编排调度 │ 编排者 │ └────┬─────┘ │ Task 工具调度 ├──▶ @preprocess-agent → 代码概览提取 + 人工审核清单生成 ├──▶ @sa-agent → 融合输入 → PRD编写（prd.md） ├──▶ @design-agent → 读取Preprocess产出 → 组件规格 → 架构设计 → 接口设计 → 结构设计 → 流程设计 ├──▶ @coder-agent → 阅读设计 → 编码实现 ├──▶ @evaluate-agent → 独立会话评估+打分（每个执行Agent完成后新起） ├──▶ @tester-agent → 测试用例生成 → 运行用例 → 修代码 → 检查 └──▶ @showcase-agent → 基于LLD生成白盒UT + 基于HLD生成白盒IT + 契约验证 → 设计-代码一致性矩阵 ``` ## 核心特性 ### 1. 全生命周期管理 ``` 预处理(代码概览+审核清单) → PRD编写 → 架构设计 → 编码实现 → 质量评估 → 质量验证 → 设计一致性验证 → 交付 ``` ### 2. 规范驱动开发(SDD)融合 - PRD与Design严格分离："功能是什么" vs "如何构建" - EARS格式验收条件 - 需求→设计→代码→测试全链路可追溯 - **PRD回溯边界明确**：Coder的PRD回溯仅限UI细节（按钮/表格/区域/布局），后端业务逻辑/校验/状态流转以Design(LLD §5)+contracts(BRC/STC)为准；Design强制产出"PRD细节对照表"供Coder对照 ### 3. 质量左移 - 每个阶段产出后自动触发质量评估（Evaluate Agent） - 代码-设计一致性验证 - 安全漏洞检测和架构合规检查 ### 4. 闭环修复 - Tester Agent发现功能缺陷时回退至Coder修复代码（Tester不修改源代码） - Showcase Agent发现设计-实现不一致时回退Coder（代码问题）或Design（设计问题） - 修复后重新验证，确保问题解决 - **回退震荡检测**：连续同类回退或A-B-A循环时提前BLOCKED（第4次即终止，不等7次上限），防止空转 ### 5. 设计-实现一致性验证（Showcase阶段） - 基于LLD生成白盒UT（每个接口/分支/异常/数据结构都有对应测试） - 基于HLD生成白盒IT（每个跨组件接口/时序/组件边界都有对应测试） - 契约一致性验证（STC/BRC/DFC逐条验证代码实现） - 产出设计-代码一致性矩阵，穷举核对每个设计元素的代码实现 - **测试去重**：入场先做覆盖度gap分析，扫描Coder UT/Tester IT已覆盖的设计元素，只对未覆盖项生成SWC测试，避免重复 ### 6. 预处理阶段（PRD增强） - 融合PM粗略PRD、产品原型和历史代码工程约束 - 支持外部输入直通（已有分析结果或已有完整PRD时跳过对应生成） - 全流程唯一PRD产出者，SA阶段直接使用 ### 7. 穷举核对分层化 - P0功能涉及的条目全量穷举核对，P1/P2抽样核对（≥70%/50%） - 增量穷举：回退修复后只核对本次变更涉及的条目，未变更条目沿用上次结论 - 追溯矩阵可缓存复用，增量评估只更新变更行 - 安全编码(C-2)/状态机(C-8)/编译验证(T-0/SC-0)维度始终全量核对，不适用分层 ### 8. 执行成本优化 - **Evaluate快速通道**：执行Agent自检全维度≥4且无阻断项时，Evaluate仅穷举P0+抽查，其余采纳自检 - **步数动态分配**：Design步数不足时自动拆为HLD生成+LLD生成两次会话；Coder单批次超步数按COMP-XX细分 - **成本预估**：流程裁剪后向用户告知预计LLM会话数和耗时，累计回退过多时主动提醒简化需求 ### 9. 评估维度全覆盖 - Coder阶段：C-1~C-10（含C-9性能实现验证、C-10可观测性实现验证，条件性） - CMO阶段：M-1~M-6（含M-5数据迁移验证[补丁项目条件性]、M-6构建产物完整性） - Design阶段：D-1~D-9（含D-9工程约束对齐度，条件性） - 所有条件性维度按项目复杂度启用，简单CRUD不增加评估负担 ### 10. 固定技能加载 每个Agent根据任务类型和项目语言，固定加载对应的技能： - **Preprocess**：加载 project-overview-generator + preprocess 技能 - **Coder**：根据语言加载编码规范技能（Python/Java/C++/C） - **Evaluate**：根据语言加载代码质量技能（可读性、可维护性、安全性） - **Design**：根据设计阶段加载设计技能（架构设计、详细设计、接口设计） - **Tester**：加载测试验证技能（已整合测试用例生成） - **Showcase**：加载展示验证技能（LLD→UT、HLD→IT、契约验证、一致性矩阵） ## Agent配置 | Agent | 角色 | 模式 | 职责 | Skill | |-------|------|------|------|-------| | harness-agent | Harness Agent | primary | 统筹编排调度8个子Agent，根据scorecard JSON做pass/fail决策 | harness-orchestrator | | preprocess-agent | Preprocess Agent（预处理工程师） | subagent | 代码概览提取+人工审核清单生成（原型/PRD冲突、含糊需求、功能重复、关键假设） | preprocess + project-overview-generator | | sa-agent | SA Agent（需求分析师） | subagent | 融合Preprocess产出的代码概览+审核清单→PRD编写（prd.md）（全流程唯一PRD产出者） | analyst-prd | | design-agent | Design Agent（设计工程师） | subagent | 读取Preprocess产出→组件规格→架构设计→接口/结构/流程设计 | design-engineering | | coder-agent | Coder Agent（编码工程师） | subagent | 阅读设计→编码实现 | coding-skill | | tester-agent | Tester Agent（测试工程师） | subagent | 测试用例生成→运行用例→检查 | test-verify | | showcase-agent | Showcase Agent（展示验证工程师） | subagent | 基于LLD生成白盒UT、基于HLD生成白盒IT、契约一致性验证→设计-代码一致性矩阵 | showcase-verify | | cmo-agent | CMO Agent（配置管理工程师） | subagent | 入库前门禁→版本构建→发布部署→发布验证 | config-management | | evaluate-agent | Evaluate Agent（评估工程师） | subagent | 每次执行Agent完成后新起独立会话，评估产出物质量并直接量化打分，输出评估报告+scorecard JSON。coder阶段含完整代码审查 | evaluate-check | ## 工作流程 Harness Agent编排顺序（每个执行Agent完成后新起evaluate独立会话评估+打分，pass=false则循环回退）： 1. **需求确认与预处理模式识别** — Harness确认需求，识别 code_overview_mode，提取R-XXX写入 `docs/requirements.md` 2. **预处理（代码概览+审核清单）** — 调用 `@preprocess-agent` → 新起 `@evaluate-agent`(phase=preprocess) → 产出 `docs/preprocess/code-overview.md`（条件性）+ `docs/preprocess/review-checklist.md` + `docs/preprocess/decision-preprocess.md` + `docs/preprocess/evaluate-preprocess-report.md` + `docs/preprocess/scorecard-preprocess.json` 3. **PRD编写** — 调用 `@sa-agent` → 新起 `@evaluate-agent`(phase=sa) → 产出 `docs/sa/prd.md` + `docs/sa/decision-sa.md` + `docs/sa/evaluate-sa-report.md` + `docs/sa/scorecard-sa.json` 4. **系统设计** — 调用 `@design-agent` → 新起 `@evaluate-agent`(phase=design) → 产出 `docs/design/HLD.md` + `docs/design/LLD-{COMP-XX}.md` + `docs/design/tasks.md` + `docs/design/contracts.md` + `docs/design/evaluate-design-report.md` + `docs/design/scorecard-design.json` 5. **编码实现与代码审查** — 调用 `@coder-agent` → 新起 `@evaluate-agent`(phase=coder, 含代码审查) → 产出源代码 + `docs/coder/evaluate-coder-report.md`（含代码审查发现）+ `docs/coder/scorecard-coder.json` 6. **质量验证** — 调用 `@tester-agent` → 新起 `@evaluate-agent`(phase=tester) → 产出 `docs/tester/qa-report.md` + `docs/tester/evaluate-tester-report.md` + `docs/tester/scorecard-tester.json` 7. **设计-实现一致性验证** — 调用 `@showcase-agent` → 新起 `@evaluate-agent`(phase=showcase) → 产出 `docs/showcase/showcase-report.md` + `docs/showcase/design-code-matrix.md` + `docs/showcase/decision-showcase.md` + `docs/showcase/evaluate-showcase-report.md` + `docs/showcase/scorecard-showcase.json` + `tests/showcase/` 白盒测试代码 8. **配置管理与发布** — 调用 `@cmo-agent` → 新起 `@evaluate-agent`(phase=cmo) → 产出 `docs/cmo/deploy-report.md` + `docs/cmo/evaluate-cmo-report.md` + `docs/cmo/scorecard-cmo.json` 9. **交付汇总** — Harness汇总产出物，向用户报告 ## 产出物 完整流程执行后产出（按角色组织，每个角色文件夹包含该角色的全部产出物）： ``` docs/ ├── requirements.md # 原始需求清单（Harness Agent产出，R-XXX编号） ├── preprocess/ # 预处理阶段文件夹 │ ├── code-overview.md # 历史代码概览（条件性，code_overview_mode≠none时产出） │ ├── review-checklist.md # 人工审核清单（原型/PRD冲突、含糊需求、功能重复、关键假设） │ ├── decision-preprocess.md # 预处理决策日志 │ ├── evaluate-preprocess-report.md # 预处理阶段评估报告 │ └── scorecard-preprocess.json # 预处理阶段评分卡 ├── sa/ # SA角色文件夹 │ ├── prd.md # 产品需求文档（SA Agent产出） │ ├── decision-sa.md # SA决策日志 │ ├── evaluate-sa-report.md # SA阶段评估报告 │ └── scorecard-sa.json # SA阶段评分卡 ├── design/ # Design角色文件夹 │ ├── HLD.md # 高层设计文档 │ ├── LLD-{COMP-XX}.md # 组件详细设计文档（每个组件一份） │ ├── tasks.md # 实现任务清单 │ ├── contracts.md # 实现契约（STC/BRC/DFC） │ ├── decision-design.md # Design决策日志 │ ├── evaluate-design-report.md # Design阶段评估报告 │ └── scorecard-design.json # Design阶段评分卡 ├── coder/ # Coder角色文件夹（源代码在src/） │ ├── decision-coder.md # Coder决策日志 │ ├── evaluate-coder-report.md # Coder阶段评估报告（含代码审查） │ └── scorecard-coder.json # Coder阶段评分卡 ├── tester/ # Tester角色文件夹 │ ├── qa-report.md # 质量验证报告 │ ├── decision-tester.md # Tester决策日志 │ ├── evaluate-tester-report.md # Tester阶段评估报告 │ └── scorecard-tester.json # Tester阶段评分卡 ├── showcase/ # Showcase角色文件夹（设计-实现一致性验证） │ ├── showcase-report.md # 验证报告（SWC测试结果+一致性问题+评级） │ ├── design-code-matrix.md # 设计-代码一致性矩阵 │ ├── decision-showcase.md # Showcase决策日志 │ ├── evaluate-showcase-report.md # Showcase阶段评估报告 │ └── scorecard-showcase.json # Showcase阶段评分卡 └── cmo/ # CMO角色文件夹 ├── deploy-report.md # 部署报告 ├── decision-cmo.md # CMO决策日志 ├── evaluate-cmo-report.md # CMO阶段评估报告 └── scorecard-cmo.json # CMO阶段评分卡 src/ # 源代码（coder-agent产出） tests/ # 测试代码（coder-agent产出单元测试，tester-agent产出E2E测试，showcase-agent产出白盒UT/IT） └── showcase/ # Showcase白盒测试（showcase-agent产出，与unit/integration/e2e物理隔离） ├── unit/ # LLD驱动的白盒UT ├── integration/ # HLD驱动的白盒IT └── contract/ # 契约一致性验证测试 ``` ## 安装部署 ### ⚠️ 重要：配置 model ID `opencode.json` 中的 `model` 字段默认值为 `"zhipuai-coding-plan/glm-5.2"`，**你必须将其替换为你自己 opencode 配置中实际使用的 model ID**。 查看你的 model ID：打开 `~/.config/opencode/opencode.json`（全局配置），找到 `provider` 下你使用的模型名称，格式通常为 `provider名/model名`（如 `zhipuai-coding-plan/glm-5.2`）或直接是 `model名`。 将 `opencode.json` 中所有 9 个 agent 的 `model` 字段替换为你的实际 model ID。 ### 方式一：项目级安装（推荐） 1. 复制 `agents/` 目录到项目 `.opencode/agents/`： ``` 你的项目/.opencode/agents/ ├── harness-agent.md ├── preprocess-agent.md ├── sa-agent.md ├── design-agent.md ├── coder-agent.md ├── tester-agent.md ├── showcase-agent.md ├── cmo-agent.md └── evaluate-agent.md ``` 2. 复制 `skills/` 目录到项目 `.opencode/skills/`： ``` 你的项目/.opencode/skills/ ├── harness-orchestrator/SKILL.md ├── preprocess/SKILL.md ├── project-overview-generator/SKILL.md ├── analyst-prd/SKILL.md ├── design-engineering/ ├── coding-skill/ ├── test-verify/ ├── showcase-verify/ ├── config-management/SKILL.md ├── evaluate-check/SKILL.md └── templates/ ``` 3. 复制 `opencode.json` 到项目根目录，**并修改 model ID** > 注意：`opencode.json` 中共有 9 个 agent（harness + 7个执行 + evaluate），所有 `model` 字段需替换为你的实际 model ID。 ### 方式二：全局安装 1. 复制 Agent 定义到全局目录： - Windows: `%USERPROFILE%\.config\opencode\agents\` - Linux/macOS: `~/.config/opencode/agents/` 2. 复制 Skills 定义到全局目录： - Windows: `%USERPROFILE%\.config\opencode\skills\` - Linux/macOS: `~/.config/opencode/skills/` 3. 将 `opencode.json` 中的 agent 配置合并到全局 `~/.config/opencode/opencode.json`，**并修改 model ID** ### ⚠️ 注意事项 - **permission 必须使用扁平格式**（如 `"bash": "allow"`），不要使用嵌套格式（如 `"bash": {"git *": "allow", "*": "ask"}`），OpenCode Desktop 不支持嵌套 permission，会导致子 Agent 启动失败 - **agent md 文件只保留 description 和 system prompt**，不要在 frontmatter 中重复配置 model/permission/mode 等字段，这些由 opencode.json 统一控制 - **model ID 必须与你的 provider 配置匹配**，否则子 Agent 无法连接 LLM ## 使用方式 ### 启动Harness Agent 在OpenCode中按 `Tab` 键切换到 `harness-agent` Agent ### 直接使用子Agent ``` @sa-agent 帮我写一个用户登录功能的PRD @design-agent 分析当前项目代码结构并设计用户认证架构 @coder-agent 实现用户登录接口 @evaluate-agent 检查代码与设计的一致性 @tester-agent 运行测试并检查质量 @showcase-agent 基于LLD生成白盒UT，验证设计-实现一致性 ``` ### 触发完整流程 向Harness提出需求： ``` 我需要开发一个用户注册登录功能，支持手机号和邮箱两种注册方式 ``` Harness自动编排所有子Agent完成全流程。 ### 可用技能列表 #### 编码规范技能（支持Python/Java/C++/C） - **基础规范**：命名、格式、注释、异常处理、并发 - **安全规范**：输入校验、加密安全、序列化安全 - **Clean Code特征**：可读性、可维护性、可靠性、可测试性、性能、可移植性 #### 设计技能 - **design-engineering**：综合设计技能，整合架构设计、详细设计、接口设计 - `architecture-design/`：分层架构、模块划分、技术选型、依赖管理 - `detailed-design/`：数据库设计、业务流程设计、安全设计 - `interface-design/`：RESTful API设计、入参出参、错误码体系 #### 测试技能 - **test-verify**：质量验证，测试用例生成，修复代码问题，验证修复结果 - **showcase-verify**：设计-实现一致性验证，LLD→白盒UT生成，HLD→白盒IT生成，契约一致性验证，设计-代码一致性矩阵 ### 技能加载示例 ``` # Coder编码时自动加载编码规范技能 @coder-agent 实现用户登录接口（Python项目） # 加载：coding-skill（自动检测项目语言并加载对应编码规范） # Review审查时自动加载代码质量技能 @evaluate-agent 检查用户登录接口代码 # 加载：evaluate-check（自动检测项目语言并加载对应代码质量规范） # Design设计时自动加载设计技能 @design-agent 设计用户认证系统架构 # 加载：design-engineering（整合所有设计子规范） # Tester测试时自动加载测试技能 @tester-agent 生成用户登录功能的测试用例 # 加载：test-verify（已整合测试用例生成功能） # Showcase验证时自动加载展示验证技能 @showcase-agent 基于LLD生成白盒UT，验证用户登录模块的设计-实现一致性 # 加载：showcase-verify（LLD→UT、HLD→IT、契约验证、一致性矩阵） ``` ## 模型配置建议 | Agent | 推荐模型类型 | 原因 | |-------|-------------|------| | harness-agent | 强推理模型 | 需理解需求、编排任务 | | preprocess-agent | 强推理模型 | 需分析代码、融合多方输入、生成结构化PRD | | sa-agent | 强推理模型 | 需深度理解PRD并结构化输出Spec | | design-agent | 强推理模型 | 需分析代码、设计架构、SDD流程 | | coder-agent | 代码能力强模型 | 需高质量代码输出 | | evaluate-agent | 严谨模型 | 需细致审查、不遗漏问题 | | tester-agent | 代码+测试模型 | 需运行测试并修复代码 | | showcase-agent | 代码+设计模型 | 需理解设计文档并生成白盒测试，验证设计-实现一致性 | | cmo-agent | DevOps模型 | 需构建部署、配置管理 |