# Dayu Harness

> 大禹治库 Skill（Dayu Harness Skill）是帮助项目低成本接入 Harness Engineering 理念的一次性部署工具。将以 AGENTS.md 为根的渐进式披露治理体系部署到目标项目。仅通过 /dayu-harness 显式命令激活。

- **Type:** Skill
- **Install:** `agentstack add skill-kinoward-dayu-harness-skill-dayu-harness-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kinoward](https://agentstack.voostack.com/s/kinoward)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kinoward](https://github.com/kinoward)
- **Source:** https://github.com/kinoward/dayu-harness-skill

## Install

```sh
agentstack add skill-kinoward-dayu-harness-skill-dayu-harness-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Dayu Harness Skill

## 定位

大禹治库 Skill 是管理和维护项目治理体系的**一次性部署工具**，不是治理体系本身。Skill 目录中的模板、脚本和资产只是部署来源；被部署到目标项目中的 AGENTS.md、docs/ 文档、hooks、CI 与维护脚本，才是 Harness Engineering 治理体系的实际载体。以 AGENTS.md 为根的渐进式披露文档体系是最终权威。初始化完成后，Skill 可安全删除——项目的治理体系已独立运行。

“大禹”取自大禹治水：不把洪流堵在一处，而是疏导、分流并建立长期秩序。被部署到目标项目的治理体系，其设计哲学源自 [Harness Engineering](https://openai.com/zh-Hans-CN/index/harness-engineering/)：工程师不再手写每行代码，而是设计约束环境、明确意图边界、构建反馈回路，让 AI 智能体可靠工作。目标项目内的文档和资产对应 HE 六大概念——AGENTS.md 是「地图而非手册」、docs/ 目录是「仓库即记录系统」、hooks + CI 是「机械化执行」、CLAUDE.md 渐进式路由是「智能体可读性」、archive/ + `docs/harness/maintenance.md` 是「熵管理」、ai-execution.md + ai-memory.md 是「人类掌舵，智能体执行，并把经验沉淀回项目」。

直接把治理规则只做成 Skill，只能让某个 Agent 在当前环境中按规则工作，属于 Agent-centric 约束。大禹治库 Skill 的目标是 Project-centric：把长期规则、项目知识/经验和机械化反馈部署进目标仓库，使它们可版本化、可审查、可迁移，并且不依赖某个 Skill、会话或工具长期存在。

## 激活条件

Skill 仅通过显式命令激活：用户输入 `/dayu-harness`。

Skill 不在日常 AI 协作中自动介入。Skill 删除后，治理体系的维护由 AI 读取项目中的 `docs/harness/maintenance.md` 自行处理。

为兼容 Claude、Codex 和通用 Agent Skills 客户端，canonical `SKILL.md` 不使用工具专属 frontmatter。具体适配策略见 [references/agent-compatibility.md](references/agent-compatibility.md)。

## 边界规则

- Skill 仅在用户显式调用 `/dayu-harness` 时工作
- 项目无 AGENTS.md → 进入脚手架模式
- 项目已有文档体系但不完整 → 进入融合模式
- 项目已有完整体系，用户要求增删改约束 → 进入维护模式
- 项目已有完整体系，用户要求检查完整性 → 进入诊断模式
- 所有操作前先分析项目现状，基于 [Q&A-TEMPLATE.md](Q&A-TEMPLATE.md) 适配提问；默认治理与 Git 能力不作为是否启用的问题，只在已有配置需要合并策略时确认
- 所有面向用户的提问和选项必须中英双语展示，格式为中文在前、英文在后；选项使用 `[1] 中文 / English`，默认项写明 `（默认，推荐）/ (default, recommended)`
- 初始化第一个阻塞问题必须是部署内容语言（中文 / English）。不得先询问项目编程语言、技术栈或项目类型；这些信息由 Skill 根据文件自动判断，空项目默认按 Node.js 治理工具链基线处理。
- 问答交互规则只约束 Skill 运行时，不写入目标项目部署产物。若宿主客户端暴露了可调用的原生交互机制（如选择器、确认对话或计划审批控件），必须优先使用；若当前客户端没有暴露可调用的结构化交互能力，则采用兼容降级：一次只提出一个阻塞问题，立即结束当前回复并等待用户输入，不得在同一轮继续运行命令、不得合并多个阻塞问题、不得假装已经进入交互控件
- 可选的 `github.repository-settings` 在用户选择启用、部署验证通过且本次流程明确追加 `--github-remote apply` 后，才调用 GitHub API 同步 `allow_auto_merge=true` 与 `delete_branch_on_merge=true`；dry-run 只预览，不修改远端。Issue/PR/TDD/发布能力仍以配置、策略文件、工作流和说明为主。
- 部署/融合前统一执行 `scripts/ensure-environment.sh  --check --capabilities ""`；尚未确定可选能力时不传 `--capabilities`，脚本按默认必选能力检查。若返回 `needs_install`、`needs_initialization` 或 `needs_user_action`，先向用户展示安装/初始化建议并确认；若用户拒绝，当前流程终止
- 任何涉及已有配置的操作，按能力清单中的可管理项/联动组件逐项处理：installer-backed 组件（如 husky hook 片段、`.gitignore`）先走 manifest installer 的 `--check`；静态模板/资产文件组件（如 `commitlint.config.cjs`、ESLint/Prettier/lint-staged 配置文件、`.github/workflows`、ruleset JSON）改用 `scaffold.sh --dry-run` 输出变更预览；若可提供现有文件与目标文件对，优先调用 `diff-helper.sh merge-plan  `；否则继续基于 `scaffold.sh --dry-run` 做人工确认
- **不覆盖已有配置**，必须经用户确认

### 结构化提问约束（全流程）

以下阻塞场景必须以单问题块输出，一轮只问一个问题，且不得要求用户手输命令：

- 版本冲突（`package.json`/`package-lock.json`/`VERSION`/`CHANGELOG.md`/`.release-please-manifest.json` 版本不一致）：提示冲突类型并给出 `[1]` 回到 `0.1.0`、`[2]` 采用某个现有版本源、`[3]` 暂停本次流程三类选项。
- GitHub 远端创建：仅在用户选择开启时执行 `gh auth status`、`scripts/github-remote.sh --check/--apply`；若未登录或可见性冲突，先给出 `[1]` 重试登录、`[2]` 暂不创建远端、`[3]` 跳过 GitHub 相关能力。
- hooks/workflows merge：当 `.husky`、`.github/workflows` 已存在且 `manual_required` 时，必须提供 `[1] 保留现有`、`[2]` 合并策略、`[3]` 替换、`[4]` 跳过该项的选择。
- 已跟踪 `.claude` 或 `CLAUDE.md`：若仓库已跟踪本地 Agent 路由目录/文件，必须先确认 `[1]` 保留本地配置、`[2]` 使用 Skill 模板合并后继续、`[3]` 从 Git 索引移除但保留本地文件后继续、`[4]` 跳过该能力。
- 受保护分支：启用 `github.branch-protection` 且检测到既有保护策略时，必须先确认策略继承关系与合并策略（合并/替换/仅保留现有），不允许自动默认覆盖。
- 部署、融合、维护或生成操作完成后，必须执行收尾验证，并按 [docs/completion-report-template.md](docs/completion-report-template.md) 用自然语言向用户汇报结果

## 5 个模式

### 1. 脚手架

触发：项目无 AGENTS.md

1. 若用户未提供部署语言，先通过交互门禁确认部署语言并等待回答；这必须是第一个问题。随后执行 `scripts/ensure-environment.sh  --check --capabilities ""`，由脚本自动判断技术栈、Git/Node 治理工具链初始化需求和 `.gitignore` 模板（见 Q&A 前置问题；尚未确定可选能力时使用默认必选能力检查）
2. 分析项目现状（读取文件结构、已有配置）
3. 按 [Q&A-TEMPLATE.md](Q&A-TEMPLATE.md) 的交互门禁询问 GitHub、发布、代码工具等可选能力（默认治理与 Git 能力直接纳入部署）
4. 展示确认汇总
5. 用户确认后：调用 `scaffold.sh --dry-run --enable ` 预览变更 → 对已有配置确认策略 → `scaffold.sh --apply --finalize-git auto --enable `（如有冲突再加 `--strategy`，如用户已确认远端同步再加 `--github-remote apply`；启用 GitHub Issue/PR 且需跳过目标仓库 E2E 时必须显式追加 `--github-e2e skip`）复制默认与可选模板文档 + 安装联动的脚本资产 + 始终部署核心维护脚本
6. `scaffold.sh --apply` 必须先完成 `validate/audit/check-consistency/capability-smoke`，通过后再精确 stage managed paths、创建初始化提交，并按远端状态推送默认分支或创建初始化 PR；启用 GitHub Issue/PR 且远端同步成功后，必须创建测试 Issue、测试分支和测试 PR，等待 `issue-lint.yml` 与 `pr-lint.yml` 成功；验证通过后关闭测试 PR、关闭测试 Issue 并删除测试分支，避免目标仓库残留测试产物；随后使用完成报告模板向用户汇报

### 2. 诊断

触发：已有项目，检查完整性

1. 优先执行 `audit.sh --json` 获取结构化诊断报告
2. 将报告中的 `description_nl` 和 `results` 以自然语言呈现给用户
3. 若 audit.sh 不可用，按 `docs/harness/maintenance.md` 诊断清单手动逐项检查
4. 报告缺失/冲突，给出修复建议

### 3. 融合

触发：已有文档体系，需要合并

1. 诊断现有状态（调用 `audit.sh --json`）
2. 对每个已有组件按能力 manifest 中的联动项区分：
   - 有 manifest installer 的组件：调用对应 installer 脚本 `--check` 获取结构化 merge plan
   - 无 installer 的组件（静态模板/资产文件）：先用 `scaffold.sh --dry-run` 获取差异说明；若有源文件和目标文件对可用，再补充 `diff-helper.sh merge-plan  ` 的结构化说明，再展示给用户
3. 将 merge plan 或差异说明中的 `description_nl` 以自然语言呈现给用户
4. 逐项双语询问：[1] 保留现有 / Keep existing [2] 替换 / Replace [3] 合并 / Merge [4] 跳过 / Skip
5. 用户逐项确认后，按组件类型执行：
   - installer-backed 组件：调用对应 installer `--apply `
   - 无 installer 组件：按用户确认方案，用 `scaffold.sh --apply` 或手工更新
6. 按「执行收尾验证」流程检查融合结果，并使用完成报告模板向用户汇报

### 4. 维护

触发：用户要求增删改约束或更新文档

子功能：
- **删除约束**：按联动组件逐项处理：installer-backed 组件先调用相关 installer 的 `--check` 获取影响范围；无 installer 组件先用 `scaffold.sh --dry-run` 标注待删差异并确认（如有源文件与目标文件对可用，再调用 `diff-helper.sh merge-plan  `） → 展示 → 确认 → 移除 → 更新 AGENTS.md 索引
- **修改约束**：有现有/目标文件对时调用 `diff-helper.sh merge-plan  ` 获取变更描述；无可用对时回退到 `scaffold.sh --dry-run` 的人工审核输出 → 展示 → 确认 → 更新
- **完整性检查**：同诊断模式
- **更新项目文档**：按 `docs/harness/maintenance.md` 流程 → 更新内容 → 同步索引

### 5. 生成

触发：需要特定文档或配置

根据项目特征和 `docs/harness/maintenance.md` 中的 Q&A 决策参考，智能生成适配内容。

## 执行收尾验证

Skill 完成任何写入类操作后，不能只告诉用户“已完成”。必须先验证目标项目中的治理体系是否能正常使用，再用自然语言收尾。

收尾验证优先使用目标项目内已部署的脚本：

1. `docs/harness/sensors/scripts/validate.sh --json `：检查已启用的 hooks、配置和 workflow 是否可用。
2. `docs/harness/sensors/scripts/audit.sh --json `：检查 `AGENTS.md`、`CLAUDE.md`、docs 索引和维护脚本是否完整。
3. `docs/harness/sensors/scripts/check-consistency.sh --json `：检查文档链接、索引和孤儿文档。
4. `scaffold.sh --apply` 输出中的 `post_apply_checks.capability-smoke`：必须覆盖本次所有已部署能力的 manifest 文件存在性和关键行为，包括 `.gitignore`、commitlint CLI、Git commit hook、pre-commit lint-staged hook、pre-push 保护、Node linter/formatter CLI、PR/Issue body validators、TDD policy 和 release-please policy。不能只测试 GitHub 相关能力。

以上本地检查属于结构/配置/关键行为验证，不能把它们表述成 GitHub Actions 已经端到端生效。启用 GitHub Issue/PR 能力并完成远端同步后，还必须运行目标仓库 Issue -> PR E2E：创建测试 Issue，再基于该 Issue 创建测试分支和测试 PR，等待 `issue-lint.yml` 与 `pr-lint.yml` 成功；验证通过后关闭测试 PR、关闭测试 Issue 并删除测试分支。需要验证合并后自动关闭 Issue 时，使用 `tests/smoke/dayu-harness-profile.sh --profile remote-smoke` 的 disposable repo 流程。

负向测试只能证明门禁会拦截错误输入，不能替代合规路径通过。若只观察到失败的 PR Lint、Issue Lint 或 release-please workflow，不得汇报为远端 E2E 成功；必须同时完成合规 Issue/PR/release 正向验证。

如果脚本不存在或暂时不可执行，按目标项目中的 `docs/harness/maintenance.md` 手动检查关键路径。

验证后处理规则：

- 检查通过：按 [docs/completion-report-template.md](docs/completion-report-template.md) 汇报已启用能力、已确认事项和未启用事项。
- 检查发现可确定修复的问题：先修复，再重新运行检查。
- 检查发现需要用户取舍的问题：说明影响，按交互门禁获取用户选择，不输出大段原始日志。
- `partial`、`failed`、`needs_user_action`、`skipped` 不能被改写成成功；必须说明对应影响。未启用的能力出现 skip 或可选缺失时，不作为失败汇报，只说明这次没有安装相关内容。

## 部署后的项目知识/经验沉淀约定

该约定会写入目标项目的 `ai-memory.md`。每次 AI 协作会话中，如产生可复用的项目知识、经验或上下文，主动建议沉淀到对应位置：

| 类型 | 沉淀位置 |
|---------|---------|
| 架构/技术决策 | `docs/design-docs/` |
| 问题排障 | `docs/troubleshooting/` |
| 研究发现 | `docs/references/research/` |
| 约束变更 | `docs/harness/guides/` + AGENTS.md |
| 项目背景和产品上下文 | `docs/product-specs/` |

写入目标项目后，该约定确保 Skill 删除后 AI 仍能自主沉淀项目知识/经验。

沉淀边界：
- 只沉淀经过归纳的可复用结论，不把完整对话记录、临时假设、未确认方案或敏感信息写入长期目录。
- 目标项目中的 `AGENTS.md` 与 `docs/` 是项目级长期记忆的单一事实源；外部 Agent memory、LangChain/LangGraph store、向量库或产品内置记忆只能作为检索缓存或运行时辅助，不作为权威规则来源。
- 外部记忆系统产生的有价值内容，必须整理成决策、排障、研究、项目上下文或约束文档后回写项目，并同步对应 `AGENTS.md` 索引。

## 部署策略

- 必选默认能力始终部署：`core`、Git 提交/.gitignore 约束、AI 执行/记忆规则、ADR、排障、研究、项目上下文和归档入口
- `--enable` 只表示在必选默认集上追加可选能力；GitHub、发布自动化、Node.js 工具等能力未选择时不复制到项目
- 未启用的可选资产不复制到项目
- `docs/harness/sensors/scripts/`（audit.sh、validate.sh、diff-helper.sh、check-consistency.sh）始终部署
- 后续需要新增约束时，重新安装 Skill 执行

## 结构化输出约定

本 Skill 所有脚本遵循统一的分工协议——脚本负责确定性分析，LLM 负责语义增强和用户交互：

| 脚本层职责 | LLM 层职责 |
|-----------|-----------|
| 检测已有配置状态 | 读取结构化报告 |
| 生成 diff 和行数统计 | 将 `description_nl` 以自然语言呈现给用户 |
| 输出结构化 JSON（含 `description_nl`） | 确认用户选择 |
| 执行写入操作（--apply 模式） | 调用脚本执行 |
| smoke test / audit / consistency 验证 | 按完成报告模板呈现自然语言结果 |

关键约定：
- 所有脚本 `--json` 模式输出纯 JSON 到 stdout，诊断日志到 stderr
- 每个 JSON 响应必须包含 `description_nl` 字段（自然语言描述，LLM 可直接使用）
- 环境前置脚本 `ensure-environment.sh --check [--capabilities ""]` 必须输出统一字段：`status`、`items`、`summary`、`description_nl`；其中 `status` 至少支持 `ok/needs_install/needs_initialization/needs_user_action/error`
- 退出码：0=成功/无变更，1=检测到冲突/失败，2=脚本自身错误
- LLM 不应自行解析原始 diff 或文件内容来替代脚本的结构化输出
- PR body、Issue body、commit message 等固定格式内容必须优先由 `docs/harness/sensors/scripts/dayu-format.mjs`、GitHub CLI `--body-file`、Commitizen/cz-git、commitlint、release-please、changesets 或项目内同类确定性工具生成/校验；LLM 只负责结构化输入字段和结果解释。

## 能力清单约定

- `capabilities/*.json` 是治理能力的单一事实源，定义 `id`、依赖、模板文件、资产文件、installer、安全策略和 acceptance criteria。
- `default=true` 的 manifest 是无须用户选择的必选部署集：`core`、Git 提交/.gitignore 约束、AI 执行/记忆规则和知识库/项目上下文目录。通用质量实践、GitHub CI、release-please、Node.js 工具和发布/分支保护类能力仍按 capability 显式启用。
- Q&A、dry-run plan、安装清单和测试断言应从 manifest 字段生成或校验，避免手工维护重复计数。

## 辅助文件

Skill 目录中的其他文件按需加载：

- **[AGENTS.md](AGENTS.md)**：Skill 自身渐进式披露入口，路由到各模块。
- **[Q&A-TEMPLATE.md](Q&A-TEMPLATE.md)**：Q&A 参考模板，提问内容以 `capabilities/*.json` 为准，包含融合模式提问和兼容化处理流程。脚手架和融合模式时读取。
- **[docs/completion-report-template.md](docs/completion-report-template.md)**：Skill 执行完成后的验证流程和自然语言收尾模板。部署、融合、维护或生成操作完成后读取。
- **[references/agent-compatibility.md](references/agent-compatibility.md)**：Claude、Codex 和通用 Agent Skills 客户端的兼容说明。需要安装、分发或调整触发策略时读取。
- **[capabilities/](capabilities/)**：治理能力 manifest，作为脚手架、Q&A、部署清单、依赖关系和验收标准的单一事实源。
- **[templates/](templates/)**：文档模板（CLAUDE.md、AGENTS.md、docs/ 完整层级结构），部署到目标项目的 `docs/` 目录。
- **[assets/](assets/)**：脚本和配置资产（husky hooks、commitlint、GitHub workflows、ESLint、Prettier、lint-staged、gitignore），默认 Git 资产和用户选择的可选资产会部署到项目对应位置。
- **[scripts/](scripts/)**：Skill 内部初始化脚本（`scaffold.sh`、`install-husky.sh`、`install-gitignore.sh`；其余能力按 manifest 指定 `installer.script` 调用），由各模式按需调用。`ensure-environment.sh` 负责环境依赖完整性与初始化确认。
- **[tests/](tests/)**：Skill 自身测试（维护者可选 bats 单元测试 + fixture 项目）；非运行时依赖，不会部署到目标项目。
- **[docs/plan.md](docs/plan.md)**：Skill 设计计划和架构文档，仅供 Skill 维护者参考。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kinoward](https://github.com/kinoward)
- **Source:** [kinoward/dayu-harness-skill](https://github.com/kinoward/dayu-harness-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kinoward-dayu-harness-skill-dayu-harness-skill
- Seller: https://agentstack.voostack.com/s/kinoward
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.