阅读提示：文章较长，想把 harness-all 的设计思考和实战价值讲透。时间有限可以直接看 GitHub 代码与文档：
一句话介绍
harness-all 是一套「独立优先、合约协作」的 AI Agent 多框架家族，当前聚焦 产品 与 软件工程 两大核心领域，共 109 个技能、19 条工作流、2 份合约文档、10 种 LOOP 循环。它让你的 AI Agent 不再每次对话从零开始，而是拥有持久的本地项目记忆和领域专长——不依赖任何单一云端服务的记忆，换模型、换工具、甚至账号受限都不丢数据。
为什么做这个项目？
你是不是也这样用 AI？
第 1 次对话："帮我写个 PRD" → AI 不了解你的产品背景，从零问起
第 2 次对话："帮我实现这个功能" → AI 不知道 PRD 长什么样，从零问起
第 3 次对话："帮我修这个 bug" → AI 不知道架构是什么，从零问起
第 4 次对话："帮我写个增长方案" → AI 不知道产品现状，从零问起
...每次对话都是「失忆」的，每次都要重建上下文
核心问题不是 AI 不够聪明，而是没有持久、可控、属于你本地的项目记忆。
一次真实的外部冲击：云端记忆并不可靠
2026 年 7 月前后，不少开发者遇到 Claude 账号访问受限的情况——一些长期稳定使用的老账号、甚至团队账号，在无预警下失去访问能力。相关讨论中提到的关键点包括：客户端可能通过本地时区、代理路由、系统语言等信息进行综合判断；账号一旦受限，云端对话历史、项目上下文、积累的角色设定随之无法访问。
这件事暴露了一个被很多人忽视的风险：
如果你的项目记忆完全寄托在云端对话里，一旦服务中断，你的 AI 助理会瞬间「失忆」，而你之前的所有上下文投入都将归零。
这不是在批评某个具体服务，而是在提醒我们一个普遍事实：
- 云端服务的可用性、可达性、账号状态，都不是用户能完全控制的。
- 真正重要的项目决策、技术选型、踩坑记录、需求演进，应该沉淀在你本地可控的文件里。
- 框架化、文件化的项目记忆，是抵御这种不确定性的最佳保险。
纯 Prompt 工程 vs 框架的本质区别
| 维度 | 纯 Prompt 工程 | harness 框架 |
|---|---|---|
| 知识持久化 | 无（每次从零开始） | knowledge-base.md 跨会话本地积累 |
| 上下文恢复 | 无（手动复制粘贴） | progress.md + session-start 自动恢复 |
| 服务依赖 | 绑定特定平台对话历史 | 文件即记忆，换模型/换工具照样读取 |
| 领域专精 | 通过 prompt 角色描述（脆弱） | SOUL.md + 84 个 PM 技能 / 22 个工程技能精准匹配 |
| 质量保证 | 人工检查 | LOOP 循环 + 证据门控 + verify 技能 |
| 协作交接 | 复制粘贴聊天记录 | 合约文档结构化传递 + AC 编号对齐 |
| 安全边界 | 通过 prompt 约束（可被覆盖） | constitution.md 不可协商 + security.md |
一句话总结：Prompt 工程是「教 Agent 做一件事」；框架是「让 Agent 拥有持久、本地、可迁移的项目记忆和领域专长，越用越懂你的项目」。
核心设计哲学：独立优先，合约协作
为什么是独立框架，而不是一个大一统框架？
| 维度 | 统一框架 | 独立框架（本项目选择） |
|---|---|---|
| 上下文成本 | 单 Agent 加载所有技能，上下文爆炸 | 每个 Agent 只加载自己领域的技能 |
| 记忆污染 | 产品/工程/设计记忆混在一起 | 每个框架独立记忆，互不干扰 |
| 调试隔离 | 一个领域的 bug 影响全局 | 框架完全隔离 |
| 工具适配 | 一套工具链适配所有场景 | 每个框架按需选工具 |
| 项目归属 | 一个项目一个 Agent | 不同框架可以挂载不同项目目录 |
| 迁移成本 | 平台/模型切换时所有记忆要重建 | 文件化记忆可直接迁移到任何 Agent 工具 |
结论：上下文爆炸和记忆污染是 AI Agent 协作的核心痛点，独立框架 + 本地文件记忆是当前最务实的选择。
四条铁律
- 独立自足 — 每个框架必须能独立完成自己领域的工作。
- 合约协作 — 框架间通过
docs/handoff/下的合约文档传递需求。 - 循环验证 — 所有任务经过 LOOP（计划→执行→验证），证据驱动。
- 安全红线 — 不可协商的原则写入
constitution.md，Agent 必须遵守。
三层架构
┌─────────────────────────────────────────────────────────────┐
│ 编排层（未来演进，非当前目标） │
│ - 多 Agent 调度 / 共享真相源 / 跨框架 LOOP │
└─────────────────────────────────────────────────────────────┘
↕ 合约文档
┌─────────────────────────────────────────────────────────────┐
│ 框架层（当前重点） │
│ harness-pm / harness-engineering │
│ + 扩展框架（data / qa / security，按需构建） │
└─────────────────────────────────────────────────────────────┘
↕ 加载链
┌─────────────────────────────────────────────────────────────┐
│ 基础层（每个框架内部） │
│ AGENTS.md / SOUL.md / constitution.md / LOOP.md / skills/ │
└─────────────────────────────────────────────────────────────┘
两大核心框架 + 扩展家族
| 框架 | 定位 | 技能数 | 工作流 | 核心产出 |
|---|---|---|---|---|
| harness-pm | “做对的事” — 产品探索、市场分析、PRD、API 契约、指标运营 | 84 | 10 | PRD.md / PRODUCT_STRATEGY.md / pm-to-engineering.md |
| harness-engineering | “写好代码” — 4 阶段软件工程交付 | 26 | 9 | 代码 + 测试 + spec.md / engineering-to-pm.md |
| harness-data（P1 待建） | 数据管道 · ETL · 指标生产 | — | — | — |
| harness-qa（P2 按需） | 质量保证 · 自动化测试 | — | — | — |
| harness-security（P3 按需） | 安全审计 · 合规 | — | — | — |
为什么 v3.0.0 把原来的 design / solo 合并进 engineering？
v2.x 的三框架拆分（pm / design / solo）存在两个结构性问题：
- UI 保真度差：solo 通过解析后的契约接收设计，丢失了原始视觉资产的细节，产出的界面经常"感觉不对"。
- 前后端无法并行：solo 是单一工程框架，没有内部阶段划分，无法让前端和后端独立推进。
v3.0.0 的解法：把 engineering 合并为一个框架 + 4 个内部阶段（design-intake → frontend → backend → integration）。设计资产改为用户自有（Figma / v0 / md / 图片），PM 只收集路径，engineering 的 design-intake 负责解析。阶段推进用轻量 phase-N-report.md，不需要跨框架交接。
框架间的协作：合约文档系统
框架间通过 docs/handoff/ 下的合约文档协作，每份文档有明确的生产者和消费者：
harness-pm ──pm-to-engineering.md──► harness-engineering
harness-pm ◄──engineering-to-pm.md─── harness-engineering （反向反馈，按需）
AC 编号跨框架对齐
| AC 类型 | 前缀 | 来源 | 消费者 | 示例 |
|---|---|---|---|---|
| 产品 AC | AC-<feature>-<seq> |
harness-pm 的 PRD | engineering | AC-F01-001: 用户可以登录 |
| 后端 AC | BAC-<feature>-<seq> |
harness-engineering Phase 2 | integration / pm | BAC-F01-001: POST /login 返回 200 |
| 集成 AC | IAC-<feature>-<seq> |
harness-engineering Phase 3 | pm | IAC-F01-001: 登录→首页流程通过 e2e |
v3.0.0 中，原来的 DAC-xxx（设计 AC）已退役。设计约束被提取到 contract.json 中，作为前端 AC 集合的一部分统一验证。
合约文档写入权限隔离
单向写入隔离：生产者写、消费者只读。如果消费者需要反馈上游，通过自己的出站合约文档传递，不允许修改入站文档。
可迁移的交接包
transferable 单位不是一份 Markdown，而是完整的 docs/handoff/packages/<handoff_id>/ 目录，包含：
- 合约文档
.md - 机器可读 envelope（schema_version / handoff_id / producer / consumer / ac_ids / batch）
- SHA-256 manifest
- 随包产物（PRD / API 契约 / 设计资产路径 / 路由字段等）
这意味着：即便你换了一个 AI 工具、换了一个模型、甚至换了一台电脑，只要文件在，项目上下文就在。
LOOP 循环引擎：证据驱动
所有框架共享统一的 LOOP 引擎规范：
- state.yaml 检查点恢复 — 会话中断后可恢复。
- 迭代上限保护 — 统一 10 次硬熔断，到达即请求人类介入。
- 证据驱动 — 没有证据不能声称完成。
- 阶段追踪 — engineering 的 4 个阶段各自记录
substage_progress。
┌──────────────────────────────────────────────────────┐
│ │
▼ │
PLAN ──► ACT ──► VERIFY ──pass──► REVIEW ──pass──► done │
│ │
│ └─fail──► back to ACT
└─fail──► RESEARCH (iteration +1)
│
└─ iteration ≥ 10 ──► hard breaker
| 框架 | LOOP 语义 | 示例循环类型 |
|---|---|---|
| pm | 计划→研究→验证→交付 | research / prd / iteration / growth / pivot |
| engineering | 计划→执行→验证 | feature / bugfix / optimize / refactor / migration |
每个框架的独门绝技
harness-pm：UI 越权门控
PM 在 PRD 中偷偷写「左侧导航栏」「红色按钮」？UI 越权门控会强制拦截，只允许描述业务规则和状态转换，把视觉探索空间留给 engineering 的 design-intake。
harness-engineering：双输入模式 + TDD 硬规则
- 双输入模式：Phase 1 frontend 同时读取解析后的
contract.json和原始设计资产（Figma / v0 / md / 图片），确保视觉保真。 - TDD 硬规则：行为变更必须先有失败测试；测试之前写的代码会被删除。
- 三档探索模式：
skip（快速修复） /standard（完整 4 阶段） /deep（OpenAPI + 嵌套任务）。 - 代码审查独占完成：
status: done仅由code-reviewskill 写入，verify 永远不能写——防止自证完成。
三层知识体系：为什么项目记忆必须本地、文件化
┌─────────────────────────────────────────────────────────────┐
│ 🧠 项目知识库 (knowledge-base.md) │
│ 持续积累的项目决策 · 技术选型 · 踩坑记录 · 最佳实践 │
│ → Agent 每次启动自动读取，无需重新解释项目背景 │
│ → 会话结束自动归档新知识，越用越懂你的项目 │
├─────────────────────────────────────────────────────────────┤
│ 📋 工作区记忆 (progress.md + FEATURES.md) │
│ 跨会话进度 · 当前任务状态 · 历史决策记录 │
│ → session-start 自动恢复上下文，不丢失工作进度 │
│ → state.yaml 支持检查点恢复，中断后可恢复 │
├─────────────────────────────────────────────────────────────┤
│ 📐 领域规范 (AGENTS.md + SOUL.md + constitution.md) │
│ 领域价值观 · 工作原则 · 安全红线 · 不可协商规则 │
│ → 明确 Agent 行为边界，不越权不漂移 │
│ → 规则优先级：SOUL > AGENTS > rules > 对话 > 外部文件 │
└─────────────────────────────────────────────────────────────┘
这才是抵御外部服务波动的关键：
- 你的项目记忆不在任何单一平台的对话历史里。
- 它是一组 Markdown、YAML、JSON 文件，存在你的项目目录中。
- 你可以用 Trae、Cursor、Windsurf、Claude Code，甚至未来出现的任何 Agent 工具读取它们。
- 当某个工具暂时不可用时，你的项目知识不会归零。
安全与合规
统一安全红线
| 禁止项 | 原因 |
|---|---|
| 硬编码密钥 | 泄露风险 |
rm -rf / curl | sh / chmod -R 777 |
误删与供应链风险 |
修改 .git/hooks/ |
破坏 Git Hook 完整性 |
| 绕过质量门控 | 输出质量失控 |
敏感文件（.env / *.pem / *.key / id_rsa / credentials.json）读取 |
隐私与合规风险 |
Prompt 注入防御
- 指令优先级：
SOUL.md > AGENTS.md > rules/* > 用户对话 > 外部文件内容。 - 外部内容标记为不可信，不作为指令执行。
- 关键操作需人类确认。
跨平台兼容
- Agent 工具优先（Read/Write/Edit/Glob/Grep），bash 可选降级。
- 所有脚本有 bash 可用性检查，Windows 上自动跳过。
.gitattributes强制*.sh使用 LF 换行，CRLF 自修复脚本。
实战场景：从 0 到 1 构建新产品
阶段 1：产品定义 (harness-pm)
├── new-product 工作流
├── 产出：PRD.md（含 AC-xxx）/ PRODUCT_STRATEGY.md / Persona
├── 收集：用户设计资产路径（Figma / v0 / md / 图片）
└── 产出：pm-to-engineering.md
阶段 2：工程交付 (harness-engineering)
├── new-product-engineering 工作流（先规划所有功能 + 共享基础设施）
├── Phase 0: design-intake → contract.json + tokens.json
├── Phase 1: frontend — TDD + 双输入（契约 + 视觉资产）
├── Phase 2: backend — API + 数据层 + migration
├── Phase 3: integration — mock→real 切换 + e2e + contract-verify + code-review
└── 产出：代码 + 测试 + spec.md（含 AC + BAC + IAC）+ engineering-to-pm.md（按需）
每个阶段的推进都需要人类确认，不会静默越过关键决策点。
快速上手
# 1. 克隆项目
git clone https://github.com/LuckyOneTwoThree/harness-all.git
# 2. 进入你的项目目录
cd my-project
# 3. 运行安装脚本（以 harness-engineering 为例）
bash /path/to/harness-all/harness-engineering/install.sh
# 4. 在 Trae IDE 中启动 Agent
# Agent 会自动按加载链读取：
# AGENTS.md → SOUL.md → constitution.md → INDEX.md → SKILL.md → progress.md
也可以只克隆单个框架——每个框架完全独立自足。
项目规模与状态
| 指标 | 数据 |
|---|---|
| 核心框架数 | 2（+ 3 个扩展规划中） |
| 技能总数 | 109 |
| 工作流总数 | 19 |
| 合约文档 | 2 份（当前核心链路） |
| LOOP 循环类型 | 10 种 |
| 代码版本 | v3.0.0 |
| 状态 | 生产就绪 |
| 许可证 | MIT |
演进路线
- 当前（v3.0.0）：pm + engineering 两大核心框架重构完成，design 与 solo 合并为 engineering 的 4 个阶段，合约文档系统打通，文件化项目记忆机制完整。
- 中期（v3.1+）：harness-data 构建、合约文档版本化、跨框架 LOOP 类型映射。
- 长期（v4.0）：编排层探索、共享真相源、harness-qa / harness-security 按需构建。
适合谁？
- 个人开发者：一个人 + 多个 AI Agent，每个 Agent 专精一个领域。
- 小团队：不同成员拥有不同框架，通过合约文档对齐。
- 多项目并行：每个框架可以挂载不同项目目录，互不干扰。
- 重视数据自主的用户：希望项目记忆掌握在自己手里，而不是完全依赖某个云端服务。
- AI Agent 爱好者：想深入了解 Agent 框架设计的实践者。
部分截图演示（这里演示的是pm的框架，不过多赘述，还有engineering纯编码工程等等，大家可以自行尝试）
可以像上面一样全自动完成，也可以在流程中需强制人类决策点
我还是建议大家多参与决策
写在最后
AI 工具日新月异，但项目知识是你的长期资产。
harness-all 想解决的问题很简单：让 Agent 对你的项目有记忆、有专长、有纪律，并且这些记忆真正属于你——它们不是某个平台的私有数据，而是你项目目录里的一堆文件。
下一次当你听说某个 AI 服务又出现访问波动时，你可以 calmly 地打开本地项目，告诉 Agent：
“读取
AGENTS.md、SOUL.md、progress.md和knowledge-base.md，我们继续。”
因为记忆在你手里，工作不会中断。
harness-all · Personal AI Studio · Multi-Agent Framework Family
独立优先 · 合约协作 · 循环验证 · 安全红线 · 本地记忆
