AI 团队不是科幻：STATE.yaml 自主项目管理深度报告

一句话总结 ：用 OpenClaw 的 sessions_spawn 把 AI 主智能体变成"CEO"，通过共享的 STATE.yaml 文件协调一群子智能体并行干活。有人已经用它实现了"睡前一想法，起床已部署"------这不是画饼，是社区跑通了的真场景。

一、案例概述

为什么要"AI 团队"，而不是一个 AI？

先说个常识：任何做过项目的人都知道，一个人干所有事，就是项目崩塌最快的路径。

单一 AI 智能体的困境也是一样的：上下文窗口有限（Claude 的 200K token 听着多，真用起来做个复杂项目根本不够）、工具调用链一长就容易跑偏、单线程执行让你等半天才能看到下一个步骤的结果。

传统做法是用一个"编排器"（Orchestrator）来控制所有流程------但这本质上还是单点瓶颈。编排器本身的上下文会被喂满，决策会变慢，而且一个环节卡住全队瘫痪。

OpenClaw 社区的解决思路很反直觉：去掉编排器，用文件做协调。

核心机制：文件即契约

整个模式的核心就一个概念：

STATE.yaml 不是配置文件，它是你和 AI 团队之间的合同。

子智能体不靠消息队列通信，不靠 RPC 调用，它们读写同一个 YAML 文件
每个任务的状态（pending / in_progress / done）写在这个文件里，谁看一眼就知道该干什么
所有变更通过 Git 提交，天然获得完整的审计历史

这就好比一个分布式团队不用 Slack 不用 Jira，所有人盯着同一块白板干活------听起来原始，但效果出奇的好。

典型效果：Overnight Mini-App Builder

这个模式最出圈的代表案例是 Overnight Mini-App Builder。流程极其简单：

你给 OpenClaw 做一次"大脑倾卸"------把职业目标、个人计划、业务需求全部告诉它
设置一个规则：每天早上 8 点生成 4-5 个可执行的日常任务
再加一条：每天晚上挑一个想法，做成一个小应用 MVP

结果就是：你睡前描述了一个 SaaS 想法，AI 团队晚上拆成前端、后端、部署三个子任务并行执行，早起你已经能看到一个能跑的 Web 应用了。

社区里已经有人晒过结果------一个 AI 教育培训网站的 MVP，一个竞品分析工具，一个自动化内容发布器。不是花架子 Demo，是真能用的东西。

二、工作流拆解

下面把整个流程拆成 5 个步骤，每一步都有明确的触发条件。

less 复制代码

graph TB
    USER["👤 用户提交任务"] --> MAIN["🧠 主智能体 (CEO)\n仅做协调\n0-2步工具调用"]

    MAIN --> REGISTRY["📋 PROJECT_REGISTRY.md\n检查是否已有 PM"]

    REGISTRY -->|"新项目"| SPAWN["🚀 sessions_spawn\n创建 PM 子智能体\n独立工作空间"]
    REGISTRY -->|"已有 PM"| SEND["📩 sessions_send\n发送任务消息"]

    SPAWN --> STATE["📄 STATE.yaml\n任务分解\n状态追踪\n文件即契约"]
    SEND --> STATE

    STATE -->|"并行执行"| SUB1["子任务 1\n独立子智能体"]
    STATE -->|"并行执行"| SUB2["子任务 2\n独立子智能体"]
    STATE -->|"并行执行"| SUB3["子任务 3\n独立子智能体"]

    SUB1 -->|"更新状态"| STATE
    SUB2 -->|"更新状态"| STATE
    SUB3 -->|"更新状态"| STATE

    STATE -->|"全部完成"| REPORT["📊 主智能体汇总\n→ 向用户报告"]

    style USER fill:#e7f5ff,stroke:#1971c2,color:#000
    style MAIN fill:#d3f9d8,stroke:#2f9e44,color:#000
    style REGISTRY fill:#fff4e6,stroke:#e67700,color:#000
    style SPAWN fill:#d3f9d8,stroke:#2f9e44,color:#000
    style SEND fill:#d3f9d8,stroke:#2f9e44,color:#000
    style STATE fill:#fff4e6,stroke:#e67700,color:#000
    style REPORT fill:#d3f9d8,stroke:#2f9e44,color:#000

步骤详解

第 1 步：主智能体接收任务 → 检查注册表

用户在微信/Telegram/Discord 里发一条消息，比如：

"重构认证模块，更新文档"

主智能体（Main Agent）做的第一件事：不是开始写代码，而是查看 PROJECT_REGISTRY.md。

注册表文件长这样：

yaml 复制代码

# PROJECT_REGISTRY.md - Active Project Managers

| Project Label | Created | Status | PM Agent ID |
|--------------|---------|--------|-------------|
| pm-auth-refactor | 2026-02-10 | active | pm-auth-refactor |
| pm-website-redesign | 2026-02-08 | active | pm-website-redesign |
| pm-blog-migration | 2026-02-05 | completed | pm-blog-migration |

这是一个极简的项目管理器注册表。主智能体只干一件事：读一行，决定下一步。

第 2 步：新项目 → sessions_spawn

如果注册表里没有匹配的 PM（项目管理器），主智能体调用：

ini 复制代码

sessions_spawn(
  label="pm-auth-refactor",
  task="Refactor auth module, update docs. Track in STATE.yaml."
)

sessions_spawn 是 OpenClaw 的核心子智能体工具。它的行为是：

创建一个完全隔离的子会话（agent:main:subagent:<uuid>）
子会话有自己的上下文窗口、工具权限、工作空间
非阻塞执行 ------sessions_spawn 立即返回一个 runId
子智能体完成后，自动向主会话"汇报"结果

主智能体在 spawn 之后，回复用户一句话："已分配 pm-auth-refactor，完成后汇报。"------然后就闭嘴了。

第 3 步：已有项目 → sessions_send

如果注册表里已经有活跃的 PM（比如用户说"昨天的重构再加一个测试用例"），主智能体调用：

ini 复制代码

sessions_send(
  label="pm-auth-refactor",
  message="Add test coverage requirement to the auth refactor task"
)

sessions_send 是向已有会话发送消息的工具。可以"发完即忘"（fire-and-forget），也可以等待回复。

这意味着同一个 PM 子智能体可以持续接收增量任务，不需要每次重建上下文。

第 4 步：PM 子智能体创建 STATE.yaml 并并行执行

PM 子智能体被 spawn 后，第一件事就是创建/读取 STATE.yaml：

yaml 复制代码

# STATE.yaml - Project coordination file
project: auth-module-refactor
updated: 2026-02-10T14:30:00Z

tasks:
  - id: refactor-auth-code
    title: "Refactor authentication logic into separate modules"
    status: in_progress
    owner: pm-auth-1
    started: 2026-02-10T12:00:00Z
    notes: "Extracting OAuth2 and JWT into /lib/auth/"

  - id: update-docs
    title: "Update API documentation with new module structure"
    status: done
    owner: pm-auth-2
    completed: 2026-02-10T14:00:00Z
    output: "docs/api/auth-v2.md"

  - id: run-tests
    title: "Run test suite and fix regressions"
    status: blocked
    owner: pm-auth-3
    blocked_by: refactor-auth-code
    notes: "Waiting for refactor to complete"

next_actions:
  - "pm-auth-1: Continue refactoring, aim for EOD"
  - "pm-auth-2: Review docs after refactor is done"
  - "pm-auth-3: Stand by for unblock"

关键设计理念：

owner 字段：每个任务明确归属一个子智能体，避免争抢
blocked_by 字段：YAML 里显式标记依赖关系，其他智能体看到就知道该不该动
next_actions 字段：给所有智能体的"行动建议"，降低决策成本
时间戳：每条变更都带时间戳，方便 Git 追踪

PM 子智能体还可以进一步 spawn 子-子智能体（嵌套深度 2），实现真正的并行执行。比如：

ini 复制代码

sessions_spawn(label="pm-auth-1", task="Refactor OAuth2 code")
sessions_spawn(label="pm-auth-2", task="Update docs for new structure")
sessions_spawn(label="pm-auth-3", task="Write unit tests for new modules")

三个子-子智能体各干各的，通过共享 STATE.yaml 了解彼此进展。

第 5 步：完成后主智能体汇总

当 PM 子智能体完成所有任务后，向主智能体汇报。主智能体做最后一步------聚合摘要，回复用户：

"认证模块重构完成：

✅ OAuth2 和 JWT 已分离到独立模块

✅ 文档已更新到 docs/api/auth-v2.md

✅ 测试通过，覆盖率达 87%

总共花费约 4 分钟。"

注意主智能体只做了 2 件事：spawn + 回复。 这就是"Thin main session"哲学------主智能体干活越少，响应越快。

三、核心技术解析

sessions_spawn vs sessions_send

这两个工具是这个模式的基石。

特性	`sessions_spawn`	`sessions_send`
用途	创建新子智能体会话	向已有会话发消息
执行模型	非阻塞，立即返回 runId	可 fire-and-forget，可等待回复
上下文	默认隔离（`isolated`），可 fork	共享目标会话的上下文
适合场景	新项目、大任务	增量指令、任务追加
嵌套支持	支持（需 `maxSpawnDepth >= 2`）	不支持嵌套

一个重要的区别 ：sessions_spawn 创建的是全新的会话环境，子智能体的上下文不会污染主智能体；sessions_send 则是向已有会话"投递消息"，适合持续沟通。

STATE.yaml 结构设计的哲学

为什么选 YAML 而不是 JSON 或 SQLite？

人类可读：你不需要特殊工具就能看懂项目状态
Git 友好：YAML 的 diff 比 JSON 更清晰
无模式约束：想加什么字段就加什么字段，不需要 migration
零依赖：不需要数据库，不需要消息队列

社区里有一个共识：STATE.yaml > Orchestrator。 文件协调比消息传递更可扩展。原因很简单------文件不会"满"，不会成为瓶颈，不会因为你 spawn 了 50 个子智能体就崩溃。

PROJECT_REGISTRY.md 的作用

这个文件是整个模式的"入口索引"。它解决了一个实际问题：当用户说"继续昨天那个项目"的时候，主智能体怎么知道哪个子智能体在负责？

没有注册表的话，主智能体每次都得去翻历史记录，或者每次都 spawn 一个新的子智能体------那就失去了"持续上下文"的价值。

Git 版本控制集成

所有 STATE.yaml 的变更都通过 Git 提交，这带来了几个意外的收益：

审计日志：谁在什么时候改了哪个任务的状态，一清二楚
回溯能力：项目出了问题，可以 git blame 看看哪一步出了问题
恢复点：如果子智能体跑偏了，可以回退 STATE.yaml 到上一个稳定版本
无需额外基础设施：Git 本身就装着，不需要搭 ELK 或者 Grafana

四、竞态条件与局限

并发写入冲突：这是个真实的问题

诚实地说，这个模式有硬伤。

当两个子智能体同时写入 STATE.yaml 时，edit 工具依赖的 oldText 匹配策略会失效------A 读的时候文件是 V1，B 也读的是 V1，A 改完写回 V2，B 基于 V1 改完写回去的时候，V2 被静默覆盖了。

OpenClaw 社区已经有人在 GitHub 上提交了 issue（#29947），讨论的就是这个问题。

解决办法：任务切片不重叠

Overnight Mini-App Builder 案例给出了一个实用的解决策略：拆分文件 + 追加模式。

AUTONOMOUS.md ：只有目标和待办事项，只有主智能体能编辑，子智能体只读
memory/tasks-log.md ：子智能体只能追加新行，不能修改已有内容

bash 复制代码

# tasks-log.md --- Completed Tasks (append-only)
# Sub-agents: always append to the END. Never edit existing lines.

### 2026-02-24
- ✅ TASK-001: Research competitors → research/competitors.md
- ✅ TASK-002: Draft blog post → drafts/post-1.md

这个模式借鉴了 Git commit log：每条记录都是追加写入，永远不会冲突。配合 YAML 文件里互不重叠的任务 ID（每个子智能体的 owner 字段不同），文件级的竞态基本可以避免。

「把事情说清楚」仍然是你的工作

这是最重要的一条认知修正。

STATE.yaml 模式不是"AI 自己管理 AI"。它放大的是你的任务分解能力。

如果你自己都没想清楚一个项目该拆成哪些任务、依赖关系是什么、交付标准是什么，那不管 spawn 多少个子智能体，结果都是一团乱麻。

社区里的成功案例都有一个共同点：用户在输入阶段已经做了大量的脑力工作。 AI 团队只是执行的放大器------它不能替代你思考。

其他已知局限

子智能体上下文受限 ：子智能体默认不会加载 SOUL.md、IDENTITY.md、USER.md，只加载 AGENTS.md + TOOLS.md
最大嵌套深度 5：虽然推荐深度 2，理论上限是 5，但超过 3 层之后管理成本急剧上升
超时兜底 ：sessions_spawn 可以设置 runTimeoutSeconds，如果不设默认不超时------一个死循环的子智能体可以跑到天荒地老
最佳努力投递：子智能体的完成通知是 best-effort 的，如果 gateway 重启，通知可能丢失

五、复制建议

最简起步：先用 Proactive Agent Skill

不要一上来就搞复杂的多智能体架构。最简单的起步方式是直接从 ClawHub 安装 Proactive Agent Skill：

arduino 复制代码

https://clawhub.ai/halthelobster/proactive-agent

这个 Skill 提供了：

WAL Protocol（Write-Ahead Logging）：在回复用户之前先写文件，保证信息不丢失
Working Buffer：上下文窗口紧张时的安全网
三层次记忆：SESSION-STATE.md（短期）→ daily logs（中期）→ MEMORY.md（长期）

先把单智能体用熟，理解怎么通过文件管理状态，再扩展到多智能体。

从单 PM 开始，逐步扩展

推荐的成长路径：

sql 复制代码

阶段 1：单智能体 + STATE.yaml
  → 一个智能体自己拆任务、更新 STATE.yaml、完成工作
  → 体会文件即状态的设计

阶段 2：主智能体 + 1 个 PM 子智能体
  → 学会 sessions_spawn 的基本用法
  → 主智能体负责拆任务，PM 负责执行

阶段 3：主智能体 + 多个 PM
  → 利用 PROJECT_REGISTRY.md 管理多个并行项目
  → 学会标签命名惯例（pm-{project}-{scope}）

阶段 4：嵌套子智能体
  → PM 再 spawn 子-子智能体实现真正的并行执行
  → 注意竞态问题，采用追加模式

AGENTS.md 配置模板

sql 复制代码

## PM Delegation Pattern

Main session = coordinator ONLY. All execution goes to subagents.

Workflow:
1. New task arrives
2. Check PROJECT_REGISTRY.md for existing PM
3. If PM exists → sessions_send(label="pm-xxx", message="[task]")
4. If new project → sessions_spawn(label="pm-xxx", task="[task]")
5. PM executes, updates STATE.yaml, reports back
6. Main agent summarizes to user

Rules:
- Main session: 0-2 tool calls max (spawn/send only)
- PMs own their STATE.yaml files
- PMs can spawn sub-subagents for parallel subtasks
- All state changes committed to git

Label Convention: pm-{project}-{scope}
Examples:
  - pm-auth-refactor
  - pm-website-redesign
  - pm-blog-content-migration

STATE.yaml Structure:
  project: <name>
  updated: <ISO timestamp>
  tasks:
    - id: <unique-task-id>
      title: <description>
      status: pending | in_progress | done | blocked
      owner: <subagent-label>
      blocked_by: <other-task-id>  # if applicable
  next_actions:
    - "<subagent>: <action>"

Race Condition Prevention:
- Sub-agents never edit the same YAML field simultaneously
- Use task ID scoping to ensure non-overlapping writes
- For append-only data, use memory/tasks-log.md instead of STATE.yaml

关键配置项

在 OpenClaw 的 openclaw.json 或 openclaw.config.json 中：

yaml 复制代码

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,        // 允许 PM 再 spawn 子智能体
        maxConcurrent: 8,        // 最大并行子智能体数
        maxChildrenPerAgent: 5,  // 每个会话最多 5 个活跃子智能体
        runTimeoutSeconds: 900,  // 子智能体默认超时 15 分钟
        model: "claude-3-haiku", // 子智能体用便宜模型省钱
      },
    },
  },
}

关键洞察速览

洞察	具体含义
STATE.yaml > Orchestrator	文件协调比消息传递更可扩展，无单点瓶颈
Git 即审计日志	每次 STATE.yaml 变更都提交，天然获得完整历史
标签约定即架构	`pm-{project}-{scope}` 的命名规则直接决定了系统的可维护性
主智能体越瘦越好	0-2 步工具调用，不亲自干活------响应速度取决于主智能体做多少事
追加模式胜于编辑	竞态问题的根本解决方案是让子智能体只追加、不修改
工具人还是主脑	STATE.yaml 模式放大的不是 AI 的能力，是你的任务拆解能力

后记：这个模式最吸引人的地方不在技术细节，而在于它的思维方式------用文件系统做分布式协调。听起来像 1970 年代的 Unix 哲学，但在 AI 智能体时代被重新发明了。它简单、可靠、可审计，而且不依赖任何第三方基础设施。下次如果你需要同时跑 5 个 AI 智能体做不同的事，别急着搭消息队列------先试试一个 YAML 文件加 Git 提交。