Harness Coding

@renransy/repository-harness-kit 提供全局维护工具 harness-cli，并在项目中安装 Oh My Pi /harness 会话命令，按 docs/ 管理 Git 版本化的 AI 工程控制层。

当前组件边界、生命周期、Skill 编排、学习闭环和所有权见 Harness 架构。

安装

bun add --global @renransy/repository-harness-kit
harness-cli --version

要求 Bun >=1.3.0。

初始化项目

进入目标项目根目录：

harness-cli init
harness-cli doctor --ci
harness-cli check --ci

项目名默认从 package.json#name 或目录名推导，也可显式指定：

harness-cli init --project my-project --root /path/to/repository

init 首次创建：

.omp/
├── commands/harness.md
├── commands/harness-gate.md
├── commands/harness-session.md
└── commands/harness-learn.md
.harness/
├── manifest.json
├── harness.yaml
├── project.json
├── feature_list.json
├── progress.md
├── session-handoff.md
├── agents/{_builtin,project}/
├── rules/{_builtin,project}/
├── skills/{_builtin,project}/
├── workflows/{_builtin,project}/
├── context/{_builtin,project,candidates}/
├── specs/
├── learnings/{candidates,resolved}/
├── templates/change/
├── schema/
└── changes/{active,archive}/

_builtin、Schema、模板和 .omp/commands/*.md 归 CLI 管理；所有 project/、specs/、learnings/、context/candidates/ 和 changes/ 归项目管理。重复 init 会拒绝覆盖。

维护命令

harness-cli version
harness-cli doctor --ci
harness-cli check --ci
harness-cli upgrade
harness-cli update --dry-run
harness-cli update

• upgrade：查询 npm 最新 CLI，只提供安装命令，不修改项目。
• update --dry-run：预览同一 Schema 下的受管文件变化。
• update：只同步同一 Schema 下的 CLI 受管内容，保留项目目录、候选 Context 和全部 Change；不执行历史版本或 Schema 迁移。
• 受管内容发生本地漂移时，update 拒绝覆盖。

Change 生命周期

用户只提供工作类型和自然语言描述；AI 负责推导 Change ID、Feature、标题、标签、执行等级和 Owner，并自动编排阶段。命令按职责拆分，避免让一个会话配置同时承担启动、Gate、恢复和学习治理：

| 会话命令 | 用途 | | ------------------------ | ------------------------------------------------------------- | | /harness <意图> <描述> | 启动 Feature、Bugfix、Change、Refactor、Visual 或 Performance | | /harness-gate specify | acceptance ... | 处理 Requirements 或 Acceptance Gate | | /harness-session status | resume | cancel | 查看、恢复或取消当前 Change | | /harness-learn list | approve | reject | 审核项目学习候选 |

意图命令仍按内部类型路由：

| 会话命令 | 内部类型 | 专属工作流重点 | | ----------------------------- | ---------------------- | -------------------------------------- | | /harness feat <描述> | feature | 拆解用户结果，完成端到端实现和验收场景 | | /harness bugfix <描述> | fix | 先复现和定位根因，再修复并保留回归检查 | | /harness change <描述> | change | 明确新旧行为、兼容影响和回归范围 | | /harness refactor <描述> | refactor | 建立行为基线，改善结构并证明行为等价 | | /harness visual <描述> | change + visual | 验证真实 UI、关键状态和响应式行为 | | /harness performance <描述> | change + performance | 同条件测量基线、瓶颈优化并比较结果 |

典型用户流程：

/harness feat 实现结账流程

# AI 完成风险分级、Skill 路由、决策树、条件化根因诊断、Delta Spec 和需求评审后等待确认
/harness-gate specify approve

# AI 自动签署隔离工作区，执行 Plan → RED/GREEN Implement → 双审 Validate → Deliver 后等待确认
/harness-gate acceptance approve

# AI 自动完成 Retrospective/Learnings/Closure、更新状态并归档 Change

Requirements 或 Acceptance 不通过时：

/harness-gate specify reject <反馈>
/harness-gate acceptance reject <反馈>

恢复与学习治理：

/harness-session status
/harness-session resume
/harness-session cancel <原因>
/harness-learn list
/harness-learn approve <learning-id> <原因>
/harness-learn reject <learning-id> <原因>

用户不需要也不能传入 Change ID、Feature ID、标题、标签、执行等级、Owner 或 Gate Note。不存在面向用户的 Plan、Implement、Validate、Deliver、Close 或通用 Gate 命令。

内部状态仍按以下顺序持久化：

open → specifying → Requirements Gate → planning → implementing → validating → delivering → Acceptance Gate → closing → closed

只有两个用户确认点：

• /harness-gate specify approve：确认分级依据、Skill 路由、产品意图、范围、拆解、需求评审和验收标准；随后 AI 自动执行至 Acceptance Gate。
• /harness-gate acceptance approve：确认开发与需求验收结果；随后 AI 自动关闭并归档。

这些是 Oh My Pi 会话命令，不是公开的全局 harness-cli 子命令。公开 CLI 只负责初始化、更新、版本、完整性和项目检查；会话 Agent 通过不出现在普通帮助中的 harness-cli session 机器接口执行状态变更，避免手写状态、Gate 哈希和学习决策。

团队闭环

面向 5–10 人团队的完整设计见团队 Harness 设计。核心约束是：

• Triage、Product、Grill、Contract、Experience、Requirements Review、Implement、Test、QA、Review、Diagnose 十一条 Skill 链按等级和任务表面组合，而不是依赖单一万能 Agent。
• specify/assessment.json 的八因子评分、关键触发器、表面和 Skill 计划由机器重算；等级只能从 provisional quick 向上升级。
• Change 根目录只保留 change.json、change.md、handoff.md 三个控制文件；阶段产物分别进入 specify/、plan/、validate/、deliver/、close/。
• DEC-* → REQ-* → AC-* → TASK-* → EVD-* 构成机器校验的追踪链；决策未解决、需求评审覆盖缺失、证据过期或高风险发现开放时，Gate 不能通过。
• Change 关闭通过 spec-updates.json 原子演进能力 Spec；规则、Context、Skill、Workflow 和 Pitfall 仍只产生带来源与目标摘要的候选，需显式审核后晋升。

跨会话恢复

/harness-session resume

恢复信息来自 active Change 的状态、阶段产物和 handoff.md，不依赖聊天记录。

项目验证命令

在 .harness/project.json 的 verification.commands 中配置 executable 和 argv，然后执行：

harness-cli project-init

所有命令通过 spawnSync 和 shell:false 顺序运行。

开发

bun install --frozen-lockfile
bun run dev
bun run check

技术栈：Bun、TypeScript、Commander.js、Vite/OXC/Rolldown、Oxlint、Oxfmt。