mini-harness

KO | EN

gitlite — search

#javascript #golang #android #machine-learning #deep-learning #linux #awesome #cli #kubernetes #vue #awesome-list #pytorch #ios #open-source

(★ 11)

最小驾驭系统 - Agent驱动的自动化研发框架

mini-harness Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Mini-Harness - AI Agent 驱动的研发流程框架

从需求到高质量交付的自动化生产。三个 AI Agent 角色 + 一个编排器协作，四层递进防线保障质量。

---

## 核心理念

**四层递进防线**，每层弥补上层的固有缺口：

1. **Rules** — 行为约束（CLAUDE.md，精简纪律）
2. **Skills** — 标准操作规程（固定步骤的 SOP，不依赖记忆）
3. **Agents + Workflow** — 角色制衡（写需求的人不审需求，写代码的人不做终验）
4. **Scripts + 人工** — 硬校验（退出码为唯一判据，Agent 说啥都不算）

**设计原则：** 脚本硬约束优先于自然语言软约束。契约即文档，模板即标准，脚本即验证。

---

## 三角色 + 编排器

| 角色 | 职责 |
|------|------|
| Orchestrator | 流程调度 + 质量门禁 + 人机交互 + 经验采集（主会话，不计被派发角色） |
| Thinker | 需求规格 → 技术设计/视觉设计（track 激活相位） |
| Worker | TDD 编码 + 精装交付 |
| Verifier | 独立验证 + 缺陷报告（不产验收标准） |

---

## 研发流程

### 外部项目交付：双 Track

| Track | 命令 | 流水线 |
|-------|------|--------|
| code | `/mh-run` | clarify → Thinker[needs→design] → SR1 → Worker → Verifier → SR3 → archive |
| ppt | `/mh-ppt` | clarify → Thinker[needs→visual] → SR1(wireframe) → Worker → Verifier[verify-ppt.sh] → SR3 → archive |

### 框架自身开发：/mh-dev

`/mh-dev` 专门开发、治理、验证和准备发布 **Mini-Harness 自身**。它直接修改本仓库的角色、技能、脚本、工作流、模板、文档与测试；运行态位于 `tools/mh-dev/.mh-dev/`，与 `/mh-run` 的外部项目产出隔离。

mh-dev 使用 fast/light/formal 轨道、开发者变更快照、机械预检、独立 Tester/Auditor 结论和 release candidate。它不会自动 commit、tag、push 或发布；这些外发操作始终需要人工显式授权。

---

## 产出类型

框架支持任意类型开发，在 clarify 阶段通过 track 选择确定流水线：
- `/mh-run` → code track（代码交付）
- `/mh-ppt` → ppt track（PPT 类 HTML 页面）

---

## 使用方式

### 支持平台

- Claude Code CLI（终端）
- VSCode Cline 插件
- VSCode Claude Code 插件

### 前置准备

1. 将需求相关参考资料放入 `reference/` 目录
2. 在对话框输入 `/mh-run`

`/mh-run` 的对外项目生命周期是 `clarify → propose → apply → archive`。开发本框架自身时改用 `/mh-dev`，不要把框架变更作为外部项目产出。

### 命令一览

| 命令 | 作用 |
|------|------|
| `/mh-run` | 外部项目/功能的全流程自动推进（推荐） |
| `/mh-dev` | Mini-Harness 自身的开发、治理、验证与候选发布 |
| `/mh-ppt` | PPT 类 HTML 开发快捷入口 |

### 最终产出

归档完成后，所有交付物位于 `deliverables/{project}/` 目录（以项目标识符命名，产出即归档，不存两份）：

```
deliverables/
├── .state.md               全局指针（project: {slug}）
└── {project}/              项目标识符命名（^[a-z][a-z0-9-]{0,63}$，澄清阶段确认后只读）
    ├── .engine/            引擎运行态与流程证据（不归档）
    │   ├── .state.md handoffs/ reports/ baselines/ process.log
    │   ├── proposal.md              Orchestrator 产出（init 阶段）
    │   ├── verify-strategy.md       Thinker 产出（集成预检策略）
    │   ├── code-report-t{N}.md      Worker 产出（每 Task 一份）
    │   └── final-test-report.md     Verifier 产出（测试报告）
    ├── README.md           项目说明
    ├── docs/               项目文档（spec/、metrics、lessons-learned、kb/）
    ├── src/ tests/ deploy/ 项目代码（按设计文档规划）
    ├── assets/             设计稿、wireframes、静态资源
    └── reference/          参考资料归档
```

产品区（`.engine/` 之外）的文件与目录名**不含引擎角色名与相位名**——流程证据内聚到 `.engine/`，交付物读者看到的是一个正常的项目目录。可追溯性由引擎态承载：`.engine/reports/<handoff-basename>.report.md` 的 basename 已含阶段与轮次，`.engine/process.log` 记录时序。

---

## 质量保障

三层脚本硬校验，不依赖 Agent 自述：

| 脚本 | 职责 |
|------|------|
| verify.sh | 结构校验（文件、流程、契约） |
| verify-qa.sh | 内容质量校验（模糊词、测试结果、报告完整性） |
| verify-ppt.sh | PPT 专项（字号底线、导航、视口） |

role-guard.sh 覆盖 `Write`/`Edit`/`NotebookEdit`，归一化后按路径归属路由：`deliverables/`（目录前缀语义）归角色白名单，其余归 mh-dev 框架治理，无活跃 mh-dev 授权时框架路径放行（默认会话透明）。

活跃交付物以全局指针 `deliverables/.state.md` 的 `project` 字段定位，**不扫描文件系统**——多项目并存是常态形态，扫描取首个命中项会让任意一个项目的状态决定另一个项目的写权。指针缺失、`project` 为空、指向的交付物或其 state 不存在、`current_role` 空或畸形时放行；`project` 非法（不满足字符集，见 `scripts/validate-slug.sh`）时拦截——合法流程不会写入非法标识符，出现即状态被污染。

产品区授权是**肯定式路径归属表**，不以「不含其他角色前缀」作为判据（去掉角色前缀后那种否定式谓词会退化为产品区全通）：THINKER 写 `docs/spec/`、`assets/`、`.archiveignore`；WORKER 写 `src/`、`tests/`、`deploy/`、`assets/` 与产品区根文件全名白名单；VERIFIER 写 `tests/`；ORCHESTRATOR 写 `docs/`、`tests/regression-suite.md` 与全局指针。归属表每条均双向锚定，目录前缀条目形如 `^…/src/.+$`（尾部 `.+` 使目录自身不命中，左锚拒嵌套伪造路径）。

THINKER/WORKER/VERIFIER 另有交还例外，写本交付物 `.engine/.state.md` 且该次写入内容的首个 `current_role:` 行值恰为 `ORCHESTRATOR` 时放行（判据与读取端同源，非存在性量词；且只接受 `Write`——`Edit` 只暴露片段，守卫看不到合并结果）（须单次完整写入；路径正则双向锚定 `.state.md` 全名，后缀/嵌套伪造路径不命中；不放大到其他引擎态文件）。完成回报独立落盘到 `deliverables/{project}/.engine/reports/<handoff-basename>.report.md`，THINKER/WORKER/VERIFIER/ORCHESTRATOR 四者均可写本交付物的回报，`handoffs/` 仍 ORCHESTRATOR 独占——白名单与回报分处两套写权，质量门禁比较的两侧无法自洽伪造。

全局路径穿越检测拒绝包含 `..` 组件的写入路径；mh-dev 分支采用双向归一化匹配 `approved_scope`（两侧统一转绝对形态后比较，兼容 scope 的相对/绝对两种存储形态），以 `/` 结尾的 scope 条目按目录前缀放行，仓库外绝对路径直接拦截，仓库根由脚本自身位置推导而非 cwd；`tests/` 与 `tools/mh-dev/tests/` 作为 Tester 专属路径按目录前缀放行，无需列入 `approved_scope`。守卫判据存放在被治理方可写的文件中（自授权），`Bash` 通道不受覆盖，定位是防误撞而非安全边界。

---

## 经验记忆

框架内置经验沉淀机制——每次执行中的调教和纠正自动采集，跨需求累积：

- 执行过程中 Orchestrator 自动采集（SR驳回、用户纠正、修复根因）
- 归档时用户补充改进建议
- 下次执行自动加载历史经验
- 框架开发者可将共性经验固化为规则

---

## 文档

| 文档 | 说明 |
|------|------|
| CLAUDE.md | 全局规则（最高约束） |
| docs/designs/design.md | 架构设计文档 |
| docs/designs/workflow.md | 流程总览 + 状态机 |
| docs/designs/source-of-truth.md | 权威源映射 |
| docs/retrospectives/ | 复盘报告（执行数据 + 问题分析） |
| docs/requirements/ | 变更请求（框架改进方案） |
| agents/*.md | 角色契约定义（thinker/worker/verifier/orchestrator） |
| skills/*.md | 执行规程 |

---

> 详细架构设计见 `docs/designs/design.md`

mini-harness

mini-harness Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

mini-harness

mini-harness Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README