{"id":50864164,"url":"https://github.com/sumo1/dev-agent-harness","last_synced_at":"2026-06-14T23:34:09.456Z","repository":{"id":364048070,"uuid":"1257788673","full_name":"sumo1/dev-agent-harness","owner":"sumo1","description":"面向开发者的 agent harness。 它站在 dev-roleplay-harness 的基础上，把原本散落在 Claude Code、Codex、角色文件、任务文档和人工调度里的流程，收进一个可视化、可编排、可验证、可沉淀的任务系统。","archived":false,"fork":false,"pushed_at":"2026-06-12T05:42:12.000Z","size":17650,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T23:34:06.827Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumo1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-03T02:27:06.000Z","updated_at":"2026-06-12T05:42:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sumo1/dev-agent-harness","commit_stats":null,"previous_names":["sumo1/multica-sumo","sumo1/dev-agent-harness"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sumo1/dev-agent-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumo1%2Fdev-agent-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumo1%2Fdev-agent-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumo1%2Fdev-agent-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumo1%2Fdev-agent-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumo1","download_url":"https://codeload.github.com/sumo1/dev-agent-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumo1%2Fdev-agent-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34342089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-14T23:34:08.577Z","updated_at":"2026-06-14T23:34:09.433Z","avatar_url":"https://github.com/sumo1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dev-agent-harness\n\n面向开发者的 agent harness。\n\n它站在 `dev-roleplay-harness` 的基础上，把原本散落在 Claude Code、Codex、角色文件、任务文档和人工调度里的流程，收进一个可视化、可编排、可验证、可沉淀的任务系统。\n\n## 核心判断\n\n`dev-roleplay-harness` 解决的是一件关键问题：\n\n**研发知识和角色协作不能只活在一次性会话里，它们应该进入工程仓库，成为可 review、可 diff、可复用的工程资产。**\n\n但直接使用这套 harness 仍然有门槛。\n\n开发者需要自己记住：\n\n- 当前任务该用哪个角色\n- 什么时候让 coder 做，什么时候让 evaluator 做\n- 哪些角色定义在 `.claude/agents/`，哪些在 `roles/` 或 `agents/`\n- Claude Code 和 Codex 分别适合跑哪类任务\n- 子任务结果在哪里看\n- 任务完成后哪些判断要沉淀回仓库\n\n这些事情不应该一直靠人脑调度。\n\ndev-agent-harness 的目标，是把这套角色协作方法变成一个面向开发者的运行系统：\n\n\u003e 用户只输入目标，系统读取工程角色，生成动态任务图，选择合适角色和运行时，追踪所有执行过程，并把关键知识沉淀回工程仓库。\n\n## 什么时候用\n\n适合：\n\n- 你已经有或准备引入 `dev-roleplay-harness`\n- 工程里有预定义角色，例如 coder、evaluator、code-reviewer、doc-refresher、dreamer\n- 一个目标需要多阶段执行、独立验收、审查或知识沉淀\n- 你希望 Claude Code、Codex 等不同运行时都能参与同一个目标\n- 你希望看到每个子任务谁在跑、用什么运行时、输出了什么、是否通过验证\n\n不适合：\n\n- 一次性问答\n- 单文件小修\n- 不需要角色切分的小脚本\n- 不关心验证和沉淀的临时任务\n\n最后一种不需要 harness。直接开一个 agent 聊天更省事。\n\n## 设计立场\n\n### 1. 工程仓库是角色和知识的来源\n\n角色不应该只存在于平台配置里。\n\n在 harness 工程里，角色通常已经写在：\n\n```text\n.claude/agents/*.md\nroles/*.md\nagents/*.md\n```\n\n这些文件是工程知识的一部分，应该跟代码一起进入 Git。\n\ndev-agent-harness 的做法是：\n\n```text\nproject.local_directory\n→ 扫描 .claude/agents / roles / agents\n→ 同步成平台里的 Agent\n→ 作为当前目标的可选角色池\n→ 由目标运行时按任务需要选择角色\n```\n\n平台里的 Agent 是投影，不是唯一真相。\n\nrepo 里的角色文件才是可 review、可演进、可被其他工具接力的源头。\n\n### 2. 目标驱动，而不是人肉挑 agent\n\n原始 harness 的使用方式偏手工：\n\n1. 打开 Claude Code 或 Codex\n2. 判断当前任务该用哪个角色\n3. 手动告诉模型该扮演 coder、evaluator 或 dreamer\n4. 在不同工具之间切换上下文\n5. 自己追踪每个阶段的结果\n\n这套方式可用，但门槛高。\n\ndev-agent-harness 把入口改成目标：\n\n```text\n用户目标\n→ 选择关联工程\n→ 同步工程角色\n→ 目标运行时拆任务\n→ 自动选择角色\n→ 派发到 Claude Code / Codex 等运行时\n→ 汇总结果\n```\n\n开发者不需要每次手动决定“现在该叫哪个 agent”。\n\n系统应该根据目标、工程角色和任务阶段来选择。\n\n### 3. 多运行时是同一目标里的执行资源\n\nClaude Code、Codex 不是两套割裂工作流。\n\n它们应该是同一个目标运行时里的不同执行资源。\n\n一个目标里的不同节点可以由不同运行时执行：\n\n```text\n需求澄清       → Claude Code\n代码实现       → Codex\n端到端验证     → Claude Code + computer-use\n代码审查       → Codex\n文档沉淀       → 任意可写 repo 的 agent\n```\n\n关键不是“支持多少 CLI”，而是每个子任务都能明确看到：\n\n- 使用哪个角色\n- 使用哪个运行时\n- 当前状态是什么\n- 实时输出是什么\n- 最终结果是什么\n\n### 4. 动态工作流，不是固定模板\n\n一个真实研发目标通常不是线性步骤。\n\n目标运行时应该能动态决定：\n\n- 哪些任务并行\n- 哪些任务串行\n- 哪些产物需要验证\n- 哪些失败可以重试\n- 哪些失败需要改写任务\n- 哪些阶段需要沉淀文档\n\n核心数据结构是目标任务图：\n\n```text\ngoal_run\n  └── goal_subtask[]\n        ├── assignee agent\n        ├── runtime\n        ├── depends_on\n        ├── kind: execute / verify\n        ├── verdict\n        └── result\n```\n\n后端不直接调用 LLM。\n\n所有 AI 行为都表现为 task，由 daemon/runtime 认领并执行。\n\n### 5. 子任务只接收任务合同\n\nDAG 是系统内部控制结构。\n\n执行者看到的应该是任务合同。\n\n坏的 prompt：\n\n```text\n在 seq3 审查通过的前提下，把 seq1 与 seq2 的内容整合成文章。\n```\n\n好的 prompt：\n\n```text\n把下面两份已产出的材料整合成一篇文章；遵守审查结论中的约束，不引入与审查结论冲突的说法。\n```\n\n执行节点需要的是：\n\n- 目标背景\n- 当前任务\n- 验收标准\n- source material\n\n它不应该被迫理解：\n\n- `seq1`\n- `seq2`\n- 上游节点\n- 下游节点\n- “前两个节点”\n- “第三步之后”\n\n调度结构属于系统内部，任务合同属于执行者。\n\n### 6. source material 替代文件中转\n\n子任务之间传递数据，不能默认靠“去读上一步文件”。\n\n文件可以是产物，但不应该成为隐式 handoff 协议。\n\n当前设计是在派发任务时直接注入必要输入：\n\n```text\nTask inputs:\n\nTask objective: 汇总成可读文章\nThe runtime has embedded the source material this task needs.\n\nSource material:\n### 核心机制说明\nResult: ...\n\n### 误解澄清\nResult: ...\n\n### 审查结论\nVerdict: pass\nResult: ...\n```\n\n这样页面上能直接看到每个子任务拿到了什么。\n\n失败时也能判断：到底是输入不够，还是执行者做错。\n\n### 7. 验证是工作流节点\n\n执行者自报完成不够。\n\n复杂研发任务需要独立验证节点：\n\n- 复核产物是否满足任务合同\n- 检查遗漏、边界和质量问题\n- 输出 pass / reject\n- reject 时触发返工\n\n验证节点不是总结节点，它必须做判断。\n\n下游节点消费的不只是“验证通过”，还必须拿到被验证过的原始产物。\n\n否则汇总节点只知道“通过了”，却不知道“通过的是什么”。\n\n### 8. 知识要沉淀回仓库\n\n平台负责实时状态：\n\n- 聊天流\n- 调度态\n- task 状态\n- 实时消息\n\n仓库负责长期知识：\n\n- 目标\n- 施工图\n- 双契约\n- 里程碑\n- 关键判断\n- memory\n\n用户可以把一次目标任务持久化回工程：\n\n```text\ndocs/task/{task-id}/\n  ├── progress.md\n  ├── plan/step-*.md\n  └── memory/*.md\n```\n\n这是快照式沉淀，不做双向同步。\n\nDB 是运行态真相，repo 是可接力的工程化投影。\n\n### 9. 改造自己时，控制平面必须稳定\n\ndev-agent-harness 可以 dogfood 自己，但不能让正在派发任务的实例成为被重启的目标。\n\n正确拓扑是：\n\n```text\nstable control plane\n→ 创建 candidate worktree\n→ agent 修改 candidate worktree\n→ 启动 candidate server / daemon / desktop\n→ verify 节点验证 candidate 实例\n→ 通过后再合并并显式重启控制平面\n```\n\n控制平面负责调度和观察；候选 worktree 负责被改、被测、被丢弃。\n\n这不是流程洁癖，是自举系统的安全边界。\n\n## 运转模型\n\n```text\n             工程仓库\n   .claude/agents / roles / agents\n                 │\n                 ▼\n          同步成平台角色池\n                 │\n                 ▼\n用户目标 ─→ 目标运行时生成任务图 ─→ 按角色和运行时派发子任务\n                 │                         │\n                 │                         ▼\n                 │                 Claude Code / Codex / ...\n                 │                         │\n                 ▼                         ▼\n           状态树 + 实时输出        execute / verify / summary\n                 │                         │\n                 └────────── source material ──────────┐\n                                                        ▼\n                                            最终交付 + repo 文档沉淀\n```\n\n```mermaid\nflowchart TD\n  Repo[\"工程仓库角色文件\"] --\u003e Sync[\"角色同步\"]\n  Sync --\u003e Pool[\"平台角色池\"]\n  Goal[\"用户目标\"] --\u003e Runtime[\"目标运行时\"]\n  Pool --\u003e Runtime\n  Runtime --\u003e DAG[\"动态任务图\"]\n  DAG --\u003e A[\"执行节点\"]\n  DAG --\u003e V[\"验证节点\"]\n  DAG --\u003e S[\"汇总节点\"]\n  A --\u003e V\n  A --\u003e S\n  V --\u003e S\n  S --\u003e Persist[\"沉淀到 docs/task\"]\n```\n\n## 三个硬协议\n\n### 角色同步协议\n\n角色来源优先级：\n\n1. `.claude/agents/*.md`\n2. `roles/*.md`\n3. `agents/*.md`\n\n同步规则：\n\n- 读 frontmatter 中的 name / description / color\n- 正文可解引用完整角色说明\n- 按 name 幂等创建或更新 Agent\n- repo → 平台单向同步\n- 平台 Agent 不自动回写 repo\n\n这样既能接入 Claude Code 的角色格式，也能接入普通 harness 的散文角色文件。\n\n### 任务合同协议\n\n子任务 prompt 禁止暴露 workflow topology。\n\n禁止把这些写进执行合同：\n\n- `seq1`\n- `seq2`\n- node number\n- upstream / downstream node\n- previous / next node\n\n应该写成语义化输入：\n\n- API contract\n- 审查结论\n- 页面验证证据\n- 已产出的核心材料\n- 端到端运行结果\n\n### 仓库沉淀协议\n\n沉淀不是把所有聊天倒进 repo。\n\n只沉淀会改变未来判断的内容：\n\n- 目标和范围\n- 施工图\n- 双契约\n- 被否决方案\n- 验证经验\n- 踩坑和修正\n\n聊天流、实时调度和临时状态留在平台。\n\n## 端到端验证\n\n开发者 agent harness 不能只验证代码静态正确。\n\n很多真实任务的终点是：\n\n- 桌面端页面真的可用\n- 浏览器交互真的跑通\n- 本地 daemon 真的认领任务\n- Claude Code / Codex 子进程真的拿到正确 prompt\n- task message 真的实时出现在 UI\n\n所以端到端验证要工具化：\n\n- 启动 server\n- 启动 daemon\n- 启动桌面端\n- 操作页面或客户端\n- 抓截图、AX 树、日志\n- 用机制测试锁住状态机\n\n这里继承了 computer-use-harness 的判断：\n\n\u003e 端到端验证应该是 agent 可调用的动作，而不是人肉确认。\n\n## 当前关键能力\n\n- 从工程 repo 同步角色到平台 Agent\n- 通过目标创建动态任务图\n- 由模型根据目标和角色池选择执行角色\n- 子任务可运行在不同 runtime，例如 Claude Code / Codex\n- 状态树和实时输出展示每个任务的执行过程\n- verify 节点支持 pass / reject 和返工\n- 下游任务通过 source material 拿到真实上游产物\n- summary 节点生成最终交付\n- goal_persist 将任务资料按 harness 结构沉淀回 repo\n- self-dogfooding 时用独立候选 worktree 隔离控制平面\n\n## 代码入口\n\n- `server/internal/service/goal.go`：目标任务状态机、DAG 调度、verify、summary、persist、decision\n- `server/internal/daemon/prompt.go`：规划、执行、验证、汇总、持久化 prompt\n- `server/internal/service/role_sync.go`：工程角色同步\n- `packages/views/tasks/`：任务页、状态树、实时输出、成员/角色选择\n- `docs/step-multi-agent-orchestration/`：多智能体编排经验\n- `docs/step-project-role-sync/`：工程角色同步经验\n- `docs/step-repo-docs-persistence/`：任务沉淀到仓库经验\n- `docs/step-e2e-testing/`：端到端验证经验\n- `docs/step-self-dogfooding/`：用当前 harness 改造当前工程的隔离流程\n- `scripts/create-dogfood-worktree.sh`：创建候选 worktree 和 `.env.worktree`\n- `.agents/skills/dev-agent-harness-self-dogfooding/` / `make agent-skills`：模型可发现的自举改造 Skill\n\n## 一句话\n\ndev-agent-harness 不是要重新发明 `dev-roleplay-harness`。\n\n它要做的是：\n\n\u003e 把 role-play harness 变成一个开发者可以低门槛使用的、多运行时、多角色、可视化、可验证、可沉淀的 agent harness。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumo1%2Fdev-agent-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumo1%2Fdev-agent-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumo1%2Fdev-agent-harness/lists"}