# harness-opencode **Repository Path**: stargc/harness-opencode ## Basic Information - **Project Name**: harness-opencode - **Description**: 本项目是一个 **Harness 模板**,定义了 OpenCode 环境下多 Agent 协同开发的标准化工作流。它不包含具体业务代码,而是提供一套**角色体系、合同分级、设计先行门禁、动态 skill 绑定、架构约束与自动化流程**,帮助单人 + AI 或小团队在 AI 辅助编程中保持代码质量与一致性。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-07-15 - **Last Updated**: 2026-07-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🚀 opencode-harness-template > **OpenCode 多 Agent 协同开发工作流模板** — 为基于 OpenCode AI 编程助手的项目提供开箱即用的多 Agent 协作基础设施。 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) --- ## 📋 项目概览 本项目是一个 **Harness 模板**,定义了 OpenCode 环境下多 Agent 协同开发的标准化工作流。它不包含具体业务代码,而是提供一套**角色体系、合同分级、设计先行门禁、动态 skill 绑定、架构约束与自动化流程**,帮助单人 + AI 或小团队在 AI 辅助编程中保持代码质量与一致性。 --- ## 🎯 核心设计理念 ### 1. 🧑‍🤝‍🧑 多 Agent 角色分离(7 个) | Agent | 类型 | 职责 | |-------|------|------| | **Coordinator** | 主代理 | 唯一入口/出口:任务拆分、分级、合同、委派、用户审核门禁、验证 | | **Designer** | 子代理 | 整体技术方案:DB/后端/前端设计 + 接口契约(不连库、不写实现码) | | **Executor-Java** | 子代理 | 写 Java/Spring + 自测(ehl-javaer 规约) | | **Executor-Python** | 子代理 | 写 Python 后端 + 自测 | | **Executor-Vue** | 子代理 | 写 Vue/React/Next + 自测 | | **Tester** | 子代理 | 唯一可运行完整验证;coverage 闭环 + UI 冒烟(客观产物) | | **Reviewer** | 子代理 | 每次必审;只审代码(不审测试/UI),按级别+类型分流深度 | ### 2. 📜 合同分级(Contract Tiers) 按任务规模与风险自动分三级,coordinator 判定,无需手动选择: | 级别 | 触发 | designer | 用户审核 | 合同 | tester | reviewer | |------|------|:--------:|:--------:|:----:|:------:|:--------:| | **L0 微改** | 1 文件/文案/类型/注释 | 跳过 | 否 | 免 | 跳过 | 秒级 sign-off | | **L1 小改** | ≤3 文件、非核心 | 跳过 | 否 | 轻量 | 全量 | 标准清单 | | **L2 大改** | >3 文件/架构/鉴权/数据迁移/跨层 | 必经 | **强制** | 完整+trace_id | 全量+E2E | 深度审查 | 合同存放于 `.opencode/contracts/YYYYMMDD/`,遵循 `contract-schema.json` 校验。 ### 3. 🎨 设计先行 + 用户审核门禁(L2) L2 大改必须先经 **Designer** 出整体技术方案,**用户审核通过才允许编码**: - 详细设计文档 → `.opencode/contracts/YYYYMMDD/design/DESIGN-<模块>.md` - 接口契约 → `.opencode/contracts/YYYYMMDD/api/<模块>.md` - 未获用户确认,coordinator 不生成编码合同。 ### 4. 🔌 动态 skill 绑定 所有 skill 均为**动态绑定**:Agent frontmatter 不静态声明,由 coordinator 在委派前按 `executor_type` 与场景用 `skill` 工具加载注入。避免无关 skill 占用上下文。 ### 5. 🏗️ 三层架构约束 强制单向依赖,禁止反向与平层交叉: ``` Layer 3: 前端/接口层 → Layer 2: 业务逻辑层 → Layer 1: 运行时/数据层 ``` ### 6. 🔗 全链路 Trace ID(L2) L2 任务生成全局唯一 UUID,贯穿 designer → 合同 → executor → tester → reviewer → 修复循环,全链路可追溯。 ### 7. 🔄 自动修复循环 tester/reviewer 发现问题 → coordinator 汇总「修复指令」→ executor 修复并重自测 → tester 重跑 → reviewer 再审,最多 **3 次**,超过升级失败。 --- ## 🔧 完整工作流(L2) ``` 用户任务 │ ▼ Coordinator 定级 L2 + 拆分 │ ▼ Designer 出整体技术方案(DB/后端/前端/接口契约) │ ▼ 【用户审核门禁】用户确认设计文档+接口契约 │ (提意见 → Designer 修订 → 再确认) ▼ 用户 PASS Coordinator 拆合同(指定 executor_type)+ 流转接口契约 │ ▼ Executor-X 写码 + 自测(自修到过) │ ▼ Tester 全量验证 + coverage 闭环 + UI 冒烟(客观产物) │ ▼ Reviewer 审代码(按级别+类型分流) │ ┌─┴──────────────┐ │ PASS │ FAIL(≤3 次修复循环) ▼ ▼ completed Coordinator 汇总修复指令 → Executor 修+自测 → Tester → Reviewer │ ▼ Git(/commit) / 复盘(/retro):按需触发,不强制 ``` > L0/L1 跳过 Designer 与用户审核,直接走合同 → 编码 → Tester → Reviewer。 --- ## 📁 项目目录结构 ``` opencode-harness-template/ ├── AGENTS.md # 工作流规范入口 ├── LICENSE # MIT 许可证 ├── README.md # 本文件 ├── .gitignore # Git 忽略规则 └── .opencode/ ├── agents/ # Agent 提示词(7 个 + _executor-base 公共片段) ├── constraints/ # 约束规则文档 │ ├── contract-mechanism.md # 合同机制与生命周期、护栏 │ ├── contract-tiers.md # 合同分级标准与字段 │ ├── arch-layering.md # 三层架构依赖规则 │ └── {java,python,vue,dba}.md # 各技术栈约束 ├── contracts/ # 任务合同(运行时) │ ├── contract-schema.json # 合同 JSON Schema │ └── YYYYMMDD/ │ ├── design/ # Designer 详细设计文档 │ ├── api/ # 接口契约 │ └── fix/ # 修复指令留痕 ├── commands/ # 斜杠命令(hinit/buildmode/gen-uuid/gen-contract/build/lint/test/typecheck) ├── skills/ # 技能文档(动态绑定) └── rules/ # 规则文件 R-01~R-08 ``` --- ## ⌨️ 斜杠命令 | 命令 | 用途 | 执行角色 | |------|------|---------| | `/hinit` | 初始化/刷新项目根 `AGENTS.md`(扫描目录结构、技术栈、约束、Agent 摘要) | coordinator | | `/buildmode on\|off` | 切换 build 模式(合同门禁开关):on=关闭门禁直接干活,off=恢复门禁;无参查询状态 | tester | | `/gen-uuid` | 生成 32 位 trace_id | — | | `/gen-contract` | 生成合同 JSON 骨架 | — | | `/build` `/lint` `/test` `/typecheck` | 构建 / ESLint / 测试 / 类型检查 | tester | > **build 模式**:`/buildmode on` 会向 `.opencode/.build-mode` 写入 `on`,contract-enforcer 插件检测到后放行所有 edit/write(跳过合同门禁),适合直接干活的场景;`/buildmode off` 写入 `off`,恢复合同门禁。coordinator 直接用 write 工具操作,无需启动 subagent。 --- ## 🚀 快速开始 1. **安装 [OpenCode](https://opencode.ai/)**(如果尚未安装) 2. 将本模板 `.opencode/` 与 `AGENTS.md` 放入你的项目 3. 按需调整 `.opencode/constraints/` 中的约束规则与各 executor 的自测/验证命令 4. 所有任务自动通过 **Coordinator** 委派,无需手动调用子 Agent > ⚠️ 本模板为通用工作流,具体技术栈命令(构建/测试/lint)请在项目初始化后按实际填充。 --- ## 📖 核心规则索引 规则存放于 `.opencode/rules/`: | 编号 | 概要 | |:----:|------| | R-0 | 语言强制规范 — 简体中文(见 AGENTS.md) | | R-01 | 源码修改前必须有合同(L0 除外) | | R-02 | executor 写完先自测,通过才交 tester | | R-03 | 每次任务必须经 reviewer 审查 | | R-04 | 修复循环 ≤3 次 | | R-05 | L2 必须先经 designer 设计 + 用户审核,未确认不得编码 | | R-06 | L2 全链路 trace_id | | R-07 | 后台进程记录 PID、按 PID 清理 | | R-08 | 禁止无差别杀进程 | --- ## 📄 许可证 本项目采用 **MIT License** 开源。完整内容请参见 [LICENSE](LICENSE) 文件。 --- ## 🏷️ 相关资源 - [OpenCode 官方文档](https://opencode.ai/docs) - [AGENTS.md](AGENTS.md) — 工作流规范详细定义 - `.opencode/agents/` — 各 Agent 提示词定义 - `.opencode/skills/` — 技能文档集合(动态绑定)