不是给智能体下指令的工具。
是人机共生协作的工程框架。
瓶颈从来不是代码生成的速度。
瓶颈是：人和智能体之间，有没有一套使双方对等参与、共同决策、可追溯验证的协作协议。
设计哲学 · 核心模型 · 快速开始 · 设计原则 · 反馈闭环 · 命令速览
OpenHarness 不是一个 Prompt 合集，也不是一个技能库。它的底层是一组工程设计原则，这些原则共同构成了智能体协作的"控制论骨架"。
1960 年，J.C.R. Licklider 发表了《人机共生》（Man-Computer Symbiosis），开篇写道：
人机共生的希望在于，在不太多年内，人的大脑与计算机将被紧密耦合在一起，由此产生的协作将让人的大脑以前所未有的方式思考，以我们从未见过的能力处理信息。
Licklider 描述的不是一个"输入指令—输出结果"的主仆模型。他描述的是一个对等的协作系统——人和机器各自做自己擅长的事，在一个共享的工作空间里协同推进。
六十年后，AI 编程智能体出现了。但大多数人对智能体的用法，仍然停留在指令-执行模式：
人：帮我实现一个用户登录功能
智能体：好，这是代码
人：不对，要加双因素认证
智能体：好，改好了
人：还不对，不应该用 JWT，换成 session
...
这不是协作。这是用自然语言做命令行操作。
OpenHarness 的设计第一性原理是：智能体不是工具，是协作方。这意味着整个系统不能围绕"如何让智能体听话"来设计，而必须围绕"如何让人和智能体成为一个高效的联合认知系统"来设计。
这个转向需要回答四个问题：
| 问题 | 指令-执行模式 | OpenHarness 的协作模式 |
|---|---|---|
| 谁知道"要做什么"？ | 只有人知道，人负责描述完整需求 | 人和智能体共同收敛需求，任务包是共享的认知产物 |
| 谁判断"做得对不对"？ | 人肉判断，每次输出都要人 Review | 三级验证谱系：自动化测试（unit_test）、语义审核（qualitative，子 Agent + 人类审阅者双轨审核）、运行时观察（rwp）——验证手段由任务性质决定，证据写入任务包 |
| 工作状态存在哪里？ | 聊天记录，散落，不可检索 | 任务包，版本化，可 git diff，可审计 |
| 智能体学到什么？ | 零积累，每次会话从零开始 | 归档任务包成为项目结构化记忆，反哺未来任务 |
OpenHarness 不是让智能体"更听话"。它是让智能体成为一个双向可问责的协作方：人需要对需求提出足够明确的验收标准；智能体需要产出可验证、可追溯的证据。双方的贡献都被记录在同一套文档里，对等可见。
这个思想直接继承自三个学术传统：
- 人机共生（Licklider, 1960）— 人与计算机的紧密耦合，不是替代，是增强
- 增强人类智能（Engelbart, 1962）— 计算技术的目标是放大人的认知能力
- 联合认知系统（Woods & Hollnagel, 2006）— 人和机器应被视为一个整体的认知单元，各有所长
OpenHarness 做的事，本质上是把这些已经存在半个多世纪的学术洞见，翻译成一套工程上可落地的协议。任务包是共享工作空间。阶段门禁是协作的 Handoff 点。证据记录是双向可追溯的审计日志。AGENTS.md 是人和智能体之间的协作接口规范。
1948 年，Norbert Wiener 在《控制论》中奠定了理论基础：通过反馈回路让系统自我修正。但真正把控制论从数学理论变成可落地的工程学科的，是钱学森 1954 年的《工程控制论》——它回答了"如何在真实系统中设计反馈、门禁和自修正机制"。
把这个工程化思想翻译到 AI 编程场景：
没有反馈的智能体 = 开环系统
一次 Prompt → 一次输出 → 人肉判断对错 → 再 Prompt → 再输出 → ...
有反馈的智能体 = 闭环系统
提出需求 → 设计 → 实现 → 按设计验证 → 证据写入 → 阶段门禁 → 推进或回退
OpenHarness 做的事，本质上是钱学森式的工程化：把反馈原理翻译成每个阶段之间可检查的门禁。不通过门禁，不能进入下一阶段。这不是靠人肉感觉判断，而是靠预先设计、事后有据的验证。
软件架构里有一个著名原则：信息应该在最需要的时刻才被拉取，而不是在入口处全部推送。
OpenHarness 把这个原则做成了三层：
| 层级 | 内容 | 触发时机 |
|---|---|---|
| 入口层 | AGENTS.md — 仓库地图 |
会话启动，一次性 |
| 任务层 | 任务包详情 + 当前阶段 Skill | 进入具体任务 |
| 执行层 | RWP 运行时工作流 | 需要运行时验证时才加载 |
智能体不用一次性加载整个知识库。它只看到当前阶段需要的上下文。这既控制 Token 消耗，也控制认知负荷。
香农的信息论告诉我们：不确定性越高，信息熵越高。
AI 编程场景的熵源：
- 需求藏在聊天记录里 → 高熵，无法检索
- 设计决策在人的脑子里 → 高熵，智能体不可见
- 验证结果在终端历史里 → 高熵，无法追溯
OpenHarness 做的是信息熵减工程：
聊天记录（高熵） → 需求文档（低熵，结构化）
人的脑内决策（高熵） → 设计文档（低熵，可 Review）
终端输出（高熵） → 证据记录（低熵，可追溯）
每次阶段 Transition 都是一次熵减操作：把散落在各处的信息收敛到一个版本化、可检索、可验证的结构中。
Barry Schwartz 在《选择的悖论》里论证过：选项越多，决策质量越差。
给智能体完全的自由度，它会在每个节点重新发明工作流。OpenHarness 的做法相反：
- 每个阶段只有明确的入口和出口
- 每个门禁只有明确的通过条件
- 每个产物只有明确的模板边界
这些约束消除了"接下来该做什么"的决策成本。智能体不需要在每个节点重新思考流程——它只需要在当前阶段的边界内，做到最好。
┌──────────────────────┐
│ AGENTS.md │
│ 项目事实地图 │
│ (入口层，渐进式披露) │
└──────────┬───────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ 任务包 │ │ 技能库 │ │ RWP 运行时 │
│ │ │ │ │ 工作流包 │
│ 需求 (SSOT) │ │ 过程约束 │ │ │
│ 概要设计 │ │ 阶段指引 │ │ 按需发现 │
│ 详细设计 │ │ 角色注入 │ │ 按需加载 │
│ 验证设计 │ │ │ │ 按需执行 │
│ 证据记录 │ │ │ │ │
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 阶段门禁（反馈回路） │
│ │
│ proposing ──→ overview_designing │
│ │ │ │
│ ▼ ▼ │
│ requirements_ overview_ │
│ designed designed │
│ │
│ detailed_designing ──→ implementing │
│ │ │ │
│ ▼ ▼ │
│ detailed_ implemented │
│ designed │
│ │
│ verification_ ──→ verifying │
│ designing │ │
│ │ ▼ │
│ ▼ verified ──→ archived│
│ verification_ │
│ designed │
└──────────────────────────────────────┘
这是一个自修正系统。每个门禁都是一次反馈检查：产物是否符合上一阶段的要求？如果不符合，回退修正。如果符合，推进。
Linux / macOS：
curl -fsSL https://raw.githubusercontent.com/Krual-T/OpenHarness/refs/heads/main/install.sh | bashWindows（PowerShell）：
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Krual-T/OpenHarness/refs/heads/main/install.ps1" | Invoke-Expression在你的项目中初始化：
openharness init --agent all目录创建、技能链接、会话 Hook 全部自动完成。详见 INSTALL.md。
OpenHarness 的每一个功能模块都不是随意堆砌的——它们各自对应一条明确的设计原则。
原则：每项工作有且只有一个权威事实源。
任务包 docs/task-packages/<任务名>/ 是一套固定结构：
任务名/
├── task-info.yaml ← 状态机（机器可读）
├── requirements.md ← 需求（问题 + 目标 + 约束）
├── overview-design.md ← 概要设计（架构决策）
├── detailed-design.md ← 详细设计（实现路径 + 测试计划）
├── verification-design.md ← 验证设计（如何证明完成）
└── evidence.md ← 证据（实际执行结果）
人和智能体共享这同一套文件。可以 git diff、可以 Review、可以归档、可以审计。
原则：不同性质的工作不应混在同一个步骤里完成。
OpenHarness 把任务生命周期拆解为 6 个阶段，每个阶段只关注一件事：
| 阶段 | 关注点 | 产物 |
|---|---|---|
proposing |
明确要解决什么问题 | 需求文档 |
overview_designing |
架构方向是否正确 | 概要设计 |
detailed_designing |
实现路径是否可行 | 详细设计 |
verification_designing |
如何证明完成 | 验证设计 |
implementing |
编码实现 | 代码变更 |
verifying |
是否达到验收标准 | 证据记录 |
每个阶段都有独立的完成标准，不达标准不能 Transition 到下一阶段。这确保了智能体不会"边设计边实现边验证"——那是最容易产生隐蔽错误的模式。
原则：不加载当前不需要的信息。
不是所有调试场景都一样。API 调试需要 HTTP 客户端和 Mock 服务，前端调试需要 headless 浏览器，数据迁移需要数据库快照——各自需要的运行时环境完全不同。
RWP 的设计遵循三级渐进式披露：
# 第一级：只看摘要（几乎零 Token 成本）
openharness rwp list
# 第二级：选定候选后才加载详情
openharness rwp view <工作流>
# 第三级：确定执行后才运行
openharness rwp run <工作流> <脚本.py>智能体不会一次性把所有工作流说明塞进上下文。它按需拉取。
原则：仓库结构必须对智能体友好，否则信息等价于不存在。
这个原则很残酷但也很真实：如果智能体从项目文件里读不到某个信息，那对智能体来说这个信息就不存在。这意味着：
- 关键决策必须从聊天记录搬到版本化文档
- 仓库目录结构必须让智能体凭直觉就能导航
- 命名必须遵循可预测的约定，不能靠人类背景知识补充
AGENTS.md 不是写给新人看的 README，它是智能体的入口路由器。它回答的是：什么东西在哪里、该走哪个流程、做完该写回什么。
原则：不是给智能体更多选项，而是给智能体更少但更清晰的选择。
skills/ 目录下的技能不教智能体"怎么写代码"——那它本来就会。技能教的是"在当前阶段，你应该关注什么、产出什么、不做什么"。
每个阶段技能都有明确的边界：
- 入口条件（什么时候进入这个阶段）
- 产出标准（阶段结束时必须交付什么）
- 禁止行为（这个阶段不要做什么）
- 出口条件（推进到下一阶段的前提）
这消除了智能体在每个节点"接下来该干什么"的决策疲劳。
把以上原则组合在一起，形成的是工程控制论意义上的反馈闭环：
需求 ──→ 概要设计 ──→ 详细设计 ──→ 实现 ──→ 验证
│ │ │
│ ←─── 证据驱动修正 ←──────┴─────────┘
│
└──→ 归档（知识积累，反哺未来任务）
- 向前：每个阶段只依赖上一阶段的产物作为输入
- 向后：验证阶段用证据匹配需求，不匹配则回退
- 积累：归档的任务包成为项目的结构化记忆，新任务可以检索历史决策
这不是线性的瀑布模型——它是带反馈的闭环。验证失败就回退修正，而不是假装通过。
| 命令 | 控制论语义 |
|---|---|
openharness task-package new <名称> |
创建新的反馈回路 |
openharness task-package list |
列出所有活跃回路 |
openharness task-package view <任务> |
查看回路当前状态 |
openharness task-package transition <任务> <状态> |
执行门禁检查并推进 |
openharness rwp list |
渐进式披露：一级摘要 |
openharness rwp view <工作流> |
渐进式披露：二级详情 |
openharness rwp run <工作流> <脚本> |
执行运行时验证 |
openharness init --agent <claude|codex|all> |
在项目中部署控制论骨架 |
openharness update |
强制同步安装源码目录并更新到最新版本 |
openharness update --mode dev-source |
跳过 Git 同步，从当前开发源码重新安装 |
AGENTS.md # 智能体入口路由器
skills/using-openharness/
├── SKILL.md # 会话入口：判断是否需要任务包
├── states/ # 阶段技能（按状态加载）
│ ├── proposing/ # 需求收敛
│ ├── exploring-solution-space/ # 方案探索
│ ├── detailed-design/ # 详细设计
│ ├── implementing/ # 编码实现
│ ├── verification-designing/ # 验证设计
│ └── verifying/ # 执行验证
└── references/ # 模板和协议文档
docs/
├── task-packages/<任务>/ # 活跃任务包
└── archived/task-packages/ # 已归档任务包（结构化记忆）
openharness_cli/ # CLI 工具
tests/ # 测试
install.sh / install.ps1 # 跨平台安装脚本
OpenHarness 的设计思想受多个源头的启发：
- 人机共生（J.C.R. Licklider, 1960）— 人与计算机的紧密耦合协作
- 增强人类智能（Douglas Engelbart, 1962）— 计算技术放大而非替代人的认知
- 联合认知系统（David Woods & Erik Hollnagel, 2006）— 人与机器作为统一的认知单元
- 控制论（Norbert Wiener, 1948）— 反馈回路与自修正系统的理论基础
- 工程控制论（钱学森, 1954）— 将控制论从数学理论落地为工程学科
- 渐进式披露（Jakob Nielsen, 1995）— 信息按需呈现
- 信息论（Claude Shannon, 1948）— 熵减作为结构化工程
- OpenAI Harness Engineering（2025）— 智能体时代的注意力经济学
代码层面，OpenHarness 是衍生作品，直接复用并改编了 obra/superpowers 的源码。技能库经由 openrelay 孵化而来。
分发本仓库的实质性部分时，请保留上游版权和许可声明。
MIT，包含上游 obra/superpowers 的 MIT 许可归属声明。
智能体不是用来使唤的。
给它一张地图、一个反馈回路、一套对等协作的协议。
然后，一起工作。