nexus/wiki/concepts/SharedStateCoordination.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
Shared State Coordination	concept	multi-agent coordination architecture	autonomous-project-management	2026-04-22

定义

多 Agent 通过读写共享状态文件（而非消息传递）实现协调的通信范式。在 autonomous-project-management 中具体实现为共享的 STATE.yaml 文件。

核心机制

• 单一真相来源（Single Source of Truth）：STATE.yaml 作为项目协调的单一事实来源
• 文件读写协调：各子 Agent 读取自己被分配的任务，写入进度/完成状态
• 轮询自驱动：Agent 主动轮询 STATE.yaml，发现任务解锁后自动拾取
• 无需消息队列：避免引入额外的消息传递中间件依赖

STATE.yaml 结构示例

project: website-redesign
updated: 2026-02-10T14:30:00Z

tasks:
  - id: homepage-hero
    status: in_progress
    owner: pm-frontend
    notes: "Working on responsive layout"

  - id: api-auth
    status: done
    owner: pm-backend
    output: "src/api/auth.ts"

  - id: content-migration
    status: blocked
    owner: pm-content
    blocked_by: api-auth

next_actions:
  - "pm-content: Resume migration now that api-auth is done"

优势

• 去中心化：无中心协调器，单点故障风险低
• 版本可控：Git 作为审计日志，完整可追溯
• 简单可靠：无需额外的消息队列或 RPC 中间件
• 持久化：状态天然持久，支持断点恢复

与消息传递模式对比

维度	共享文件协调	消息传递协调
中间件依赖	仅文件系统	需要 MQ/Pub-Sub
状态持久性	天然持久	需要额外存储
并发控制	文件锁	队列ACK
调试难度	高（需读文件）	中（需追踪消息流）
适用场景	并行独立任务	有序依赖链

衍生概念

• Git-as-Audit-Log：将所有 STATE.yaml 变更提交至 Git，获得完整历史