dkh

dkod Harness — 自主并行构建系统

这是什么

一个完全自主的构建 Harness。用户只需提供一条提示词（“构建一个……的 Web 应用”）。 Harness 会完成其他所有工作——规划、并行实现、测试、修复和交付——无需用户进一步参与。

这是 Anthropic 的 Planner → Generator → Evaluator Harness 模式的一种实现， 专为 dkod 的并行执行能力打造。Anthropic 的参考架构按顺序运行生成器，而本 Harness 会同时运行 N 个生成器， 因为 dkod 的 AST 级合并可以消除虚假冲突。

此技能的触发条件

• 用户说“构建一个……”“创建一个……”“制作一个……”
• 用户调用 /dkh <prompt>
• 用户描述要从头构建的完整应用或功能集
• 任何足够复杂、可通过并行拆分和评估获益的任务

处理 /dkh continue

当用户发送 /dkh continue（或仅发送“继续”）时：

═══ 必须：恢复状态并清理，然后再继续 ═══

重新分派任何生成器之前，先恢复中断会话的状态，并仅清理未完成的部分。不要批量关闭所有内容——已提交的变更集代表已完成的工作，必须予以保留。

第 1 步：查询 dkod 中现有的变更集 调用 dk_status 或通过 API 列出变更集，查看中断的会话遗留了哪些内容。 对每个变更集进行分类：

• submitted 状态 → 保留。此生成器已完成工作。记录其 changeset_id。 不要关闭它。不要重新分派此单元。
• approved 状态 → 保留。此变更集已通过审核，可以合并。 记录其 changeset_id。在第 3 阶段继续合并。
• draft 状态 → 未完成。此生成器在执行 dk_submit 之前中断。 标记此单元以便重新分派。
• conflicted 状态 → 卡住。标记此单元以便重新分派。
• rejected 状态 → 失败。标记此单元以便重新分派。

第 2 步：关闭未完成或失败的变更集，并释放其符号声明

# Close draft/conflicted/rejected — preserve submitted and approved
Bash: curl -sf -X POST "https://api.dkod.io/api/repos/<owner>/<repo>/changesets/bulk-close" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DKOD_API_KEY" \
  -d '{"states": ["draft", "conflicted", "rejected"], "created_before": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'  \
  || { echo "Bulk-close failed — aborting resume. Check DKOD_API_KEY and repo path."; exit 1; }

第 3 步：重建 Harness 状态

• changeset_ids = 第 1 步中 submitted + approved 状态的 changeset_id 列表
• active_units = 生成器未完成的单元（draft/conflicted/rejected/missing）
• 拥有 submitted 或 approved 变更集的单元已完成——跳过它们

第 4 步：仅继续处理未完成的单元 仅重新分派 active_units（未完成单元）的生成器。已完成生成器提交的变更集会被保留——20 分钟的工作不会丢失。

输出：“正在恢复 Harness——中断前已完成 N/M 个生成器。正在重新分派 K 个未完成单元。”

然后继续：

1. 如果存在活跃的 Harness 会话（Agent 保留了上一轮的状态）：

   • 输出当前 Harness 状态和阶段
   • 显示哪些 Agent 已完成（已提交），哪些需要重新分派
   • 恢复 Harness 循环，跳过已完成的单元

2. 如果不存在活跃的 Harness 会话（应用重启后的全新上下文）：

   • 确认收到命令：“在此上下文中未找到活跃的 Harness 会话。”
   • 通过 dk_status 检查是否存在任何活跃的 dkod 会话
   • 如果发现活跃会话，按上述说明恢复状态
   • 如果没有发现会话，告知用户使用 /dkh <prompt> 启动新的构建

绝不能默默忽略 /dkh continue。 始终确认收到命令并提供当前状态。

前置条件检查

开始前，请确认以下内容可用：

1. dkod MCP 工具：dk_connect、dk_context、dk_file_write、dk_submit、dk_verify、 dk_review、dk_approve、dk_merge、dk_push、dk_status、dk_watch

2. 浏览器测试（任选其一 — 优先使用 Playwright）：

   • playwright-cli（优先）：使用 playwright-cli --version 检查。适用于无需技能的浏览器自动化的独立 CLI — 截图、脚本执行、PDF 生成。无需 Node.js 脚本，无需 MCP 服务，默认以无头模式运行。 参见：https://github.com/microsoft/playwright-cli
   • chrome-devtools MCP（备用）：navigate_page、take_screenshot、click、 evaluate_script、list_console_messages、lighthouse_audit。仅在未安装 Playwright 时使用。
   • 如果未找到，请输出安装说明并使用备用方案。不要询问用户，也不要安装。
   • 如果 Playwright 和 chrome-devtools 均不可用，则评估改为使用 dk_verify 和代码审查（不进行实时 UI 测试）。

3. 设计系统（任选其一 — 优先使用 DESIGN.md）：

   • DESIGN.md（优先）：项目根目录中的设计系统文件，来源于 awesome-design-md。如果存在， 它将成为权威设计参考 — 规划器会将其纳入规范，生成器直接遵循它（无需调用技能），评估器则依据它进行评分。 与通用技能相比，这样能打造更具特色、更符合品牌形象的 UI。
   • frontend-design skill（备用）：如果不存在 DESIGN.md，生成器在实现 UI 组件前会调用 Skill(skill: "frontend-design")。规划器仍会在规范中生成 Design Direction 部分。评估器仍会对设计质量进行评分。 如果未找到，请输出安装说明并使用备用方案。不要询问用户，也不要安装。
   • 如果两者均不可用，生成器应手动遵循规划器的 Design Direction 部分。

检测流程（在 PRE-FLIGHT 期间运行一次）：

# 1. Detect playwright-cli (standalone CLI, skills-less operation)
HAS_PLAYWRIGHT=false
playwright-cli --version 2>/dev/null && HAS_PLAYWRIGHT=true

# 2. Detect DESIGN.md (check all paths the planner searches)
HAS_DESIGN_MD=false
( [ -f DESIGN.md ] || [ -f design.md ] || [ -f docs/DESIGN.md ] || [ -f docs/design.md ] ) && HAS_DESIGN_MD=true

# Pass both flags to all agent dispatches:
# - Planner: HAS_DESIGN_MD
# - Generators: HAS_DESIGN_MD
# - Evaluators: HAS_PLAYWRIGHT
# - Smoke test: HAS_PLAYWRIGHT

如果缺少 dkod，请提供安装指导：

claude mcp add --transport http dkod https://api.dkod.io/mcp

模型配置

当前配置：quality

每个 Agent 都使用适合其任务的模型运行。编排器读取当前配置，并在每次 Agent 调度调用中传递 model: 和 effort:。

Agent	quality	balanced	budget	effort
编排器*	opus	opus	sonnet	high
规划器	opus	opus	sonnet	max
生成器	opus	sonnet	sonnet	high
评估器	opus	sonnet	haiku	max

* 编排器模型由发起调用的 Claude Code 会话设置，而非由此表设置。此行是对会话模型的建议，不由执行框架强制执行。

Effort 级别为必填项。 规划器和评估器使用 max（复杂推理 — 任务分解、评分）。生成器使用 high（快速执行 — 写入文件，而非深入分析）。调度 Agent 时务必传递 effort:。

• quality — 全部使用 Opus。能力最强。适用于复杂或高风险的构建任务。
• balanced（默认）— 规划和编排使用 Opus，实现和评估使用 Sonnet。成本与质量的最佳平衡。
• budget — 规划和实现使用 Sonnet，评估使用 Haiku。速度最快、成本最低。适用于简单构建或迭代。

如需切换配置，请修改上方的 Active profile:。编排器会在每次运行开始时读取此值。

自主循环

该框架运行一个严格的阶段门控循环：PLAN → BUILD → LAND → File Sync → Smoke Test → EVAL → SHIP/FIX/REPLAN。每个阶段都有进入／退出门槛，只有产物齐备后才能继续推进。

agents/orchestrator.md 是所有阶段详情、门槛检查、状态跟踪、调度模板和转换逻辑的唯一事实来源。开始前请先阅读。

关键约束：

• 未完成评估报告时，不得调用 dk_push(mode:"pr")（仅限 Phase 5）
• 代码未合并且未通过冒烟测试时，不得运行评估器
• 计划未经验证时，不得运行生成器
• dk_verify 不属于评估——Phase 4 通过 chrome-devtools 测试在线应用
• 所有代码变更都必须通过 dkod 完成——绝不可对源文件使用 Write/Edit/Bash
• 绝不向用户提问——所有决策都必须自主完成
• 评估轮次最多 3 轮，之后带着已记录的问题发布

关键设计原则

0. 最大化并行度——首要原则

默认并行执行；只有存在硬性数据依赖时才串行。 使用 Claude Code Agent 团队（在一条消息中调用多个 Agent）+ dkod 会话隔离 （每个 Agent 都有自己的覆盖层）。两者结合可将串行构建转为并行构建。

适用于每个阶段： 同时调度生成器、并行运行 dk_verify、 并行重新调度失败的生成器。唯一例外：评估器必须按顺序运行 （共用 chrome-devtools 浏览器会话）。

1. 按符号拆分，而不是按文件

dkod 在 AST 层级合并。在同一文件中编辑不同函数的两个生成器 不会产生冲突。

2. 每个生成器使用一个 dkod 会话

每个生成器调用一次 dk_connect。合并前，各会话彼此隔离。

3. 评估器必须独立且持怀疑态度

根据 Anthropic 的研究：“事实证明，将独立评估器调整为持怀疑态度， 比让生成器批判自己的工作容易得多。”默认判定为 FAIL，除非有证据证明应判定为 PASS。

4. 基于文件的通信

计划和评估报告是结构化产物，即使上下文重置也会保留。

5. 自主性不容妥协

该框架绝不向用户征求输入。冲突 → 自动解决。评估失败 → 自动修复。框架 → 根据提示词推断。包管理器 → bun。

6. 评估轮次最多 3 轮

防止无限循环。3 轮之后，发布可用的成果，并记录未解决的问题。

工作单元结构

规划器在此结构中生成工作单元（嵌入计划产物中）：

## Work Unit: <id>
**Title:** <descriptive title>
**OWNS (exclusive):** <list of qualified symbol names this unit solely owns>
**Creates:** <list of new symbols with file paths>
**Acceptance criteria:**
- <testable criterion 1>
- <testable criterion 2>
**Complexity:** low | medium | high

Agent 定义

• 规划器：agents/planner.md — 将提示词扩展为规范和并行工作单元
• 生成器：agents/generator.md — 通过 dkod 会话实现单个工作单元
• 评估器：agents/evaluator.md — 通过 chrome-devtools + dk_verify 测试合并后的结果
• 编排器：agents/orchestrator.md — 驱动自主循环（就是你）

参考指南

• references/planning-guide.md — 符号级拆分详解
• references/evaluation-guide.md — 持怀疑态度的评估技巧和 chrome-devtools 模式
• references/dkod-patterns.md — dkod 会话生命周期和合并模式