sofa + agent = 沙发特工——希望有一天，我们能躺在沙发上，Agent 就把活干完了。 v0.72 · 2026-06-27
我叫孔放勋，一个完全不懂代码的产品经理。所有设计决策来自大半年的真实使用经验，文档由 DeepSeek V4 Pro 和 GLM-5.2 配合生成。欢迎大佬进来改。
给 Agent 配了个「指导员」——不是让它更聪明，是让它别乱来。
| 角色 | 怎么干 |
|---|---|
| Skill（判断） | MD 文件当规则书，Agent 加载后照做——三层加载链、复杂度预判、反思沉淀 |
| 脚本（执行） | bash 脚本处理机械活——读写文件、调 API，Agent 调 shell 跑（非 bash 平台降级为 Read/Edit 工具） |
| 平台兜底 | 加载链 + 断路器 + 死循环检测——OpenClaw 系由 Hook 和配置层兜底，其他平台依赖自身安全机制 |
⚠️ sofagent 是软约束层——靠 Agent 读取并自觉遵守，不是硬编码强制执行。执行率受上下文长度、模型能力影响。详见 Design §三。
| 你是谁 | 看哪个 | 一句话 |
|---|---|---|
| 普通用户 | HANDBOOK.md（443 行） | 怎么装、怎么用、什么是铁律 |
| 开发者 | DEVELOPMENT.md（599 行） | Skill 怎么协同、编排怎么跑、反思怎么闭环 |
| 设计爱好者 | ARCHITECTURE.md（585 行） | 为什么选这些设计、已知局限 |
| 技术 VP 推广 | docs/team-deploy.md（3 页） | 装、试、回顾三阶段落地指南 |
三层加载链（常驻地基：宪法 → 反思区 → 你的规则）
↓
A0 复杂度预判
├── 🟢🟡 简单 → 快速响应（地基在线）
└── 🔴 复杂 → 任务编排引擎点火
│
┌────┴────┐
智能拆解 → 分批执行 → Loop 检查（子任务间 · 60%预算 · 重大操作前）
│ │
└─── 闭环反思 ←─────────┘
↓
下次参考上次经验
| 做什么 | 怎么做 |
|---|---|
| 地基 | 三层加载链——宪法（4底线+10铁律）→ 反思区（自动错题本）→ 你的规则。整个会话期间永远在线 |
| 引擎 | 任务编排引擎——🔴 复杂任务时点火，智能拆解 + Loop 检查 + 闭环反思 |
| 进化 | 渐进减薄——同类任务根据历史成功率调整编排深度，跑崩了恢复完整编排 |
💡 核心理念：厚在治理，薄在复用。 约束自己定，模板和 Skills 从社区取。为 AI Agent 提供纪律层与反思循环（效果待社区验证）。 💰 安装成本：约 3,000 token 地基常驻（128K 窗口的 2.5%）。编排引擎仅 🔴 复杂任务时额外 ~800 token。详见 Token 预算。
⚠️ 已知局限：核心效果尚无第三方实测数据；复盘是 LLM 自评，无客观基准；Loop Agent 非独立进程；纯文件约束依赖 Agent 配合；数据明文存储（task/logs + think.md 含任务记录，无加密）；不是多用户系统（共享 .sofagent/ 会交叉污染经验）。详见 DESIGN §三。
| 平台 | 加载链 | 编排引擎 | 自动化程度 |
|---|---|---|---|
| OpenClaw | 第 1 层 Hook 注入，第 2/3 层 Agent 自觉（有 Hook 辅助提醒） | ao compose 完整可用 | 高 — 安装即生效 |
| WorkBuddy | 第 1 层 @skill 注入，第 2/3 层 Agent 自觉 | ao compose 可用（需 npm 安装） | 中 — 需手动 @skill:sofagent |
| Claude Code / Codex / Hermes | 第 1 层通过种子指令加载，第 2/3 层 Agent 自觉（无机制保障） | 不可用（降级为手工拆解） | 低 — 核心约束仍生效，编排引擎缺失 |
⚠️ 以上为作者实测结论。如果你在某个平台上跑出了不同的结果——那才是真实数据，欢迎告诉我们。
📎 「种子指令」是什么：写在 Agent 记忆文件（如 CLAUDE.md / AGENTS.md / SOUL.md）里的一句话，告诉 Agent 启动时先读 sofagent 约束文件。这不是自动化——是人手动贴的纸条。 OpenClaw 和 WorkBuddy 通过各自的 skill 机制自动加载，不需要种子指令。
效果？我们诚实地说不知道。 目前仅有作者自己的日常使用感受，没有第三方长期数据。v0.72 新增了 benchmark.sh 可复现对比测试——欢迎你跑一下，然后把结果告诉我们。
详见 EVIDENCE.md——社区用户的实际使用数据。
- ❌ 不是 AI 框架——不管模型 API、不写 prompt，那是 Model 层的事
- ❌ 不是 Skills 商店——不维护可复用 Skills（内置 task-aware 等核心治理 Skill 除外），外部 Skills 从社区获取
- ✅ 是一套治理方法——靠 Skill + 脚本 + 配置三层落地，告诉 Agent 什么能做、什么不能做、什么时候该收手。OpenClaw first，其他平台仅宪法层约束（详见 Design §三 平台依赖 能力表）
选你的平台，5 步，10 分钟。
| 依赖 | 版本要求 | 为什么需要 | 检查命令 |
|---|---|---|---|
| bash | ≥4 | install.sh / task-record.sh | bash --version |
| git | 任意 | clone 仓库、task/logs 追溯、worktree 隔离 | git --version |
| node | ≥18 | ao compose 编排引擎（agency-orchestrator） |
node --version |
| npm | ≥9 | 全局安装 agency-orchestrator | npm --version |
⚠️ WorkBuddy 用户若不跑编排引擎（只用宪法层约束），node/npm 可不带。OpenClaw / Claude Code / Codex / Hermes 跑复杂任务（🔴）必须有 node + npm。
⚠️ 编排引擎依赖第三方 npm 包agency-orchestrator。若 npm install 失败或未配置 API Key，编排引擎降级为 Agent 手工拆解（模板匹配和角色分配不可用）。约束层不受影响。
git clone https://github.com/KongFangXun/sofagent.git
cd sofagentbash sofagent/scripts/install.sh --platform 你的平台| 平台 | 命令 | 说明 |
|---|---|---|
| OpenClaw | bash sofagent/scripts/install.sh |
自动探测，完整部署（宪法 + Hook + 断路器） |
| WorkBuddy | bash sofagent/scripts/install.sh --platform workbuddy 或通过技能市场安装 |
部署 SKILL.md 到 ~/.workbuddy/skills/sofagent/ |
| Claude Code | bash sofagent/scripts/install.sh --platform claude |
部署宪法 + 输出种子指令（需手动粘贴到 CLAUDE.md） |
| Codex | bash sofagent/scripts/install.sh --platform codex |
部署宪法 + 输出种子指令（需手动粘贴到 AGENTS.md） |
| Hermes | bash sofagent/scripts/install.sh --platform hermes |
部署宪法 + 输出种子指令（需手动粘贴到 SOUL.md） |
未指定
--platform时自动探测。
install.sh 会改什么文件：
- OpenClaw：写入
~/.openclaw/rules.md、~/.openclaw/rules.md、~/.openclaw/skills/sofagent/（含 6 个 Skill .md + scripts/ + data/ + constitution/） - WorkBuddy：写入
~/.workbuddy/skills/sofagent/（含 SKILL.md + 子目录） - Claude Code / Codex / Hermes：写入
~/.claude/（或~/.codex/、~/.hermes/）的宪法文件，并输出种子指令让你手动贴到 CLAUDE.md / AGENTS.md / SOUL.md
bash sofagent/scripts/verify.sh预期：9 类 24+ 检查项全 pass。加
--json可集成到 CI/CD。如果 fail，看 Handbook §六 排查。
打开你的 Agent 客户端，试一个需要多步拆解的任务（这样才能看出 sofagent 的编排能力）：
/goal是 Claude Code 的自主执行命令；OpenClaw 用户可直接描述复杂任务，Agent 会自动触发编排引擎。详见 Handbook §四。
/goal 帮我分析一下这个项目的代码质量，生成一份改进建议报告
Agent 会自动拆解任务 → 匹配 Skill → 执行 → 反思沉淀。在 OpenClaw 上全程自动；在其他平台部分能力需手动触发（详见 Design §三 平台依赖 能力表）。
跑完看结果：
ls .sofagent/task/logs/ # 按「年-月」分目录的执行日志
cat .sofagent/think.md # Agent 自动提炼的反思摘要OpenClaw 上全自动，其他平台需手动触发闭环。
跑通了？ HANDBOOK.md 教你怎么调，DEVELOPMENT.md 讲内部怎么跑，ARCHITECTURE.md 说为什么这么设计。想看这个项目怎么开发的？开发日志 是作者的 dogfooding 实录。
├── README.md
├── LICENSE ← CC-BY-4.0 + MIT 双许可
├── CHANGELOG.md ← 版本历史
├── CODE_OF_CONDUCT.md ← 行为准则
├── CONTRIBUTING.md ← 贡献指南
├── SECURITY.md ← 安全策略
├── HANDBOOK.md ← 用户手册：怎么用
├── DEVELOPMENT.md ← 开发者文档：Skill 结构、编排、反思、数据架构
├── ARCHITECTURE.md ← 设计哲学：为什么这么设计
├── ROADMAP.md ← 路线图：下一步计划和参与方式
├── workflows/ ← ao compose 编排工作流
│ └── 审查-sofagentscriptsinstallsh-的安全性.yaml
├── docs/ ← 文档
│ ├── EVIDENCE.md ← 社区用户实际使用数据
│ ├── TESTING.md ← 标准化测试用例
│ ├── enterprise-deploy.md ← 企业级部署指南
│ ├── team-deploy.md ← 技术 VP 落地指南
│ ├── system_design.md ← v0.7x 企业合规三件套系统设计
│ ├── class-diagram.mermaid ← 系统设计类图
│ ├── sequence-diagram.mermaid← 系统设计时序图
│ ├── changelog/ ← 开发日志（每版本开发过程，dogfooding 实录）
│ └── cases/ ← 第三方使用案例
│ ├── codex-stability-2026-06-20/ ← Case 004: Codex 稳定性测试
│ ├── italy-travel-2026-06-18/ ← Case 001: 首次全流程跑通
│ ├── openclaw-e2e-2026-06-19/ ← Case 002: OpenClaw E2E 回归
│ └── workbuddy-self-test-2026-06-18/ ← Case 003: WorkBuddy 自测
├── .github/ ← GitHub 配置
│ ├── ISSUE_TEMPLATE.md ← Issue 模板
│ ├── PULL_REQUEST_TEMPLATE.md← PR 模板
│ └── workflows/ ← CI/CD
│ └── verify.yml ← verify.sh 自动验证
├── sofagent/ ← 核心部署文件
│ ├── SKILL.md ← 🌟 主入口——加载这个就启动整套体系
│ ├── engine.md ← 完整入口引擎（A→D 初始化 + 子 Skill 索引）
│ ├── entry-gate.md ← 入境闸门：内部初始化检查
│ ├── task-aware.md ← 每任务闸门：边界→判级→澄清
│ ├── task-closure.md ← 离境闸门：调 Loop Check 收口
│ ├── loop-check.md ← 循环检查：三模式五触发点
│ ├── constitution/ ← 宪法文件
│ │ └── rules.md ← 执行层：模型偏好 + 行为规则
│ ├── data/ ← 数据模板（格式参考）
│ │ ├── IDENTITY.md ← Agent 身份声明
│ │ ├── think.md
│ │ ├── scoring.md
│ │ ├── orchestrator.md
│ │ └── task.md
│ ├── hooks/ ← OpenClaw 内部 hook
│ │ └── sofagent-load-chain/← 加载链（agent:bootstrap 注入第 2、3 层）
│ │ ├── HOOK.md
│ │ └── handler.ts
│ ├── scripts/ ← 安装和运行脚本
│ │ ├── install.sh ← 一键安装（多平台兼容）
│ │ ├── verify.sh ← 验证脚本
│ │ ├── uninstall.sh ← 卸载脚本
│ │ ├── task-record.sh ← 任务记录（含脱敏 + 审计）
│ │ ├── task-orchestrate.sh ← 编排引擎适配
│ │ ├── cleanup.sh ← 数据保留清理
│ │ ├── audit.sh ← 审计日志
│ │ └── lib/ ← 共享函数库
│ │ └── config.sh ← 配置解析
│ └── images/ ← Skill 资源
│ └── sofagent.png ← Logo
└── images/ ← 项目资源
└── sofagent.png ← Logo
安装后自动生成的 .sofagent/ 数据目录：
.sofagent/ ← 运行时数据（Agent 自动维护）
├── think.md ← 反思摘要（加载链第 2 层）
├── orchestrator/ ← 编排最优配置沉淀
│ └── workflows/ ← ao compose 生成的 YAML
├── scoring.md ← Skill 使用评分记录
└── task/ ← 任务计划 + 执行日志 + 审计
├── plans/ ← 澄清阶段产出的任务计划
├── logs/ ← 闭环后按天归档的执行记录
└── audit/ ← 审计日志（v0.71 起自动记录关键操作）
💡
.sofagent/是 Agent 的「工作笔记」——每次任务自动记录，跨任务自动反思沉淀。
💡 你看到的 6 个 Skill 文件（1 主 Skill + 5 子 Skill）+ 6 个脚本不是「堆文件」——Skill 文件各管一件事（入境/每任务/离境/Loop），脚本处理确定性操作（安装/验证/记录/编排）。复用了 4 个开源项目做编排、岗位匹配、Skills 发现，自己只写了治理层。详见 用了哪些外部项目。
| 依赖 | 干什么 |
|---|---|
| OpenClaw | Agent 运行时——加载链、Hook、Session 管理 |
| agency-orchestrator（Apache-2.0） | 任务编排引擎——ao compose 一行拆任务、匹配角色 |
| agency-agents-zh | 215 个中文岗位模板 |
| ClawHub / 各平台技能市场 | 外部 Skills 的发现来源——不内置，按需从社区获取 |
欢迎提 Issue 和 PR，尤其是挑刺的那种。详见 CONTRIBUTING.md。
- OpenClaw by Peter Steinberger — 整个 sofagent 的基石
- DeepSeek V4 Pro — 所有文件都是它与 GLM-5.2 配合生成的
- GLM-5.2 — 配合 DeepSeek V4 Pro 完成代码生成、审查与测试
- Andrej Karpathy Skills — 4 条编码原则是 10 则铁律的根基
- agency-orchestrator + agency-agents-zh — 任务编排引擎 + 中文岗位库
- Anthropic Skills — 官方 SKILL.md 格式规范
- Anthropic Managed Agents — 四层架构的设计哲学源头
- Loop Engineering by Addy Osmani — 循环工程五大件，sofagent 编排层的理论源头
- superpowers — Skill 作为 Harness 杠杆的思路