hoshuchiu/Contious

Fork 0

Files

hoshuchiu 470e122388 docs

2026-06-09 00:41:55 +08:00

35 KiB

Raw Permalink Blame History

人机协作 Agent 原型 —— 系统架构总览

本文档提供系统级的全景视图，描述各子系统的职责、边界、交互方式以及数据流动路径。阅读前建议先浏览 DESIGN_DECISIONS.md 了解设计动机。

1. 系统总体架构

系统由五个核心子系统构成，围绕"中央路由"呈星型拓扑：

┌─────────────────────────────────────────────────────────────┐
│                      可视化与交互层                           │
│         (树状图 · 模块关系图 · 评审会界面 · 配置面板)         │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│                      中央路由 (Central Router)               │
│         (消息转发 · 权限过滤 · 日志审计 · 路由策略)            │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
        ┌──────────┬──────────┼──────────┬──────────┐
        ↑↓         ↑↓         ↑↓         ↑↓         ↑↓
   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ 产品    │ │ 测试    │ │Supervisor│ │  人类   │ │  其他   │
   │ Agent   │ │ Agent   │ │/知识库  │ │(Supervi-│ │ 工具    │
   │         │ │         │ │ Agent   │ │sory)    │ │ 服务    │
   └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
        └───────────┴───────────┴───────────┴───────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│                    工作台与快照系统                           │
│    (工作区隔离 · 快照管理 · 分支Fork · 树状存储 · 存档检索)     │
└─────────────────────────────────────────────────────────────┘

设计原则：任何两个 Agent（含人类）不直接通信，所有交互必须经过中央路由。任何 Agent 不直接操作文件系统，所有持久化必须经过工作台快照系统。

2. 核心子系统详解

2.1 中央路由 (Central Router)

职责

消息转发：根据路由规则将消息从发送方递送到接收方/组。
权限过滤：在转发前检查"发送方是否有权向接收方发送此类消息"。
日志审计：记录所有经过的消息元数据（不含 payload 内容，只记录谁发给谁、消息类型、时间戳、引用 ID）。
路由策略执行：当前为硬编码规则，未来可替换为 LLM 动态决策。

内部结构

Central Router
├── Inbound Queue（入站队列，所有 Agent 提交消息至此）
├── Routing Engine（路由引擎，决定消息去向）
│   └── 当前：代码规则表
│   └── 未来：LLM 策略模型
├── Permission Gate（权限门，拦截越权消息）
├── Outbound Dispatcher（出站分发器）
└── Audit Log（审计日志，只存元数据）

消息格式（标准信封）

所有经过中央路由的消息必须遵守统一格式：

{
  "msg_id": "uuid",
  "timestamp": "ISO8601",
  "from": "agent_id",
  "to": "agent_id | group_id | broadcast",
  "msg_type": "QUERY | RESPONSE | NOTIFY | DECISION | MEETING_CALL",
  "payload_ref": "snapshot_id#object_path",
  "payload_summary": "人类可读摘要（用于日志和通知）",
  "session_id": "当前任务会话 ID",
  "branch_id": "所属分支 ID（主干为 main）",
  "priority": "LOW | NORMAL | HIGH | CRITICAL"
}

注意：payload_ref 指向工作台快照系统中的对象，消息本身不携带内容。接收方凭引用 ID 和自身权限向工作台申请拉取。

通信模式实现

模式	路由行为
点对点	`to` 填目标 Agent ID，直接投递
点对组	`to` 填 group_id，Router 查询组成员列表后分别投递
组内广播	特殊消息类型 `BROADCAST`，Router 向组内所有成员投递，并标记"同一条消息的副本"便于关联

2.2 工作台与快照系统 (Workbench & Snapshot System)

职责

为每个 Agent 提供隔离的工作区（独立的文件系统视图）。
提供**快照（Snapshot）**的创建、读取、对比、回溯能力。
维护树状的快照历史（支持分支、合并、差异对比）。
提供**存档（Archive）**的写入和检索（工作过程存档 + 评审会存档）。
作为中央路由的内容存储后端：Agent 通过引用 ID 向工作台申请拉取内容。

核心概念

工作区（Workspace）

每个 Agent 拥有一个独立工作区目录。
工作区之间默认不可见（文件系统级别隔离）。
人类（Supervisory Agent）拥有跨工作区读取权限（但写入需显式授权）。
工作区的"当前状态"随时可以被快照捕获。

快照（Snapshot）

快照是工作区某一时刻的只读副本。
快照只在决策节点创建：分叉点（Fork）和挂起点（Suspend）。中间运行过程不创建快照。
快照不可修改，只能通过"基于快照创建新工作区"来延续。
每个快照包含：
- 文件系统哈希树（保证完整性）
- Agent 上下文引用（推理历史 ID）
- 父快照 ID（支持回溯）
- 分支 ID（支持多线历史）
- 节点类型（FORK 或 SUSPEND）
- 创建原因（详细枚举见数据模型）

快照树（Snapshot Tree）

快照之间通过 parent_id 形成树结构。
main 分支是主时间线。
树节点按语义分为两类：
- 分叉节点（Fork Node）：新分支的起点，表示"AI 在这里做了一个选择"。
- 挂起节点（Suspend Node）：分支暂停的断点，表示"AI 在这里停下来了"。
Fork 操作强制要求原因：Agent 调用 fork() 时必须提供结构化原因说明（观察到的现象、假设的根因、尝试的方向），否则工作台拒绝执行。
Fork 操作创建新分支：基于某快照创建新工作区，新工作区的首次快照是分叉节点，指向父快照，但携带新的 branch_id。
挂起操作在当前分支末端创建一个挂起节点，标记该分支进入暂停状态。
树节点支持以下查询：
- trace(node_id)：返回从根到该节点的快照链（即 AI 的完整思考链）。
- diff(node_a, node_b)：返回两个节点从最近公共祖先开始的差异（即分叉后的不同路径）。
- checkout(node_id)：基于该快照创建新工作区，供人类或 Agent 继续工作。

平级链（Side Chain）

每个主树节点可以挂载一条平级链，记录到达该节点之前的中间操作快照。
平级链上的快照不参与树的拓扑结构，只是该节点的历史附件。
典型内容：危险操作前备份、开发阶段中间状态、挂起被打回后的重试记录。
挂起被打回时：原挂起节点的快照被挂载到"下一个推演起点"的平级链头部。
查询：side_chain(node_id) 返回该节点的平级链快照列表（按时间倒序）。

存档（Archive）

存档是"业务事件"的持久化记录，与快照（技术状态）分离存储。
两类存档：
1. 工作存档：每次快照创建时的原因、触发者、关联的消息 ID 列表。
2. 评审会存档：评审会的完整记录（见 2.5 节）。
存档支持按 session_id、branch_id、timestamp、event_type 检索。

数据模型

Session（任务会话）
├── session_id: UUID
├── requirement: 原始需求文本（人类输入）
├── current_req_version_id: 当前有效需求版本 ID
├── strategy_config: 挂起策略配置（允许哪些挂起类型）
├── supervisor_permissions: Supervisor 当前解锁的权限列表
├── status: ACTIVE | SUSPENDED | ABORTED
├── root_snapshot_id: 初始快照
├── current_main_snapshot_id: main 分支最新快照
├── branch_registry: { branch_id → { parent_snapshot_id, status, owner_agent_id } }
└── meeting_history: [meeting_id, ...]

RequirementSnapshot（需求版本）
├── req_version_id: UUID
├── session_id: 所属会话
├── version_number: 整数版本号（v1, v2, v3...）
├── parent_version_id: 父版本（v1 为 null）
├── content: 结构化需求规格
│   ├── 功能描述
│   ├── 验收标准
│   ├── 边界条件
│   └── 已知歧义点
├── status: DRAFT | ACTIVE | SUPERSEDED | SUSPENDED
├── created_by: 创建者 Agent ID（产品经理或人类）
├── created_at: 时间戳
└── code_snapshots_based_on: [snapshot_id, ...]  // 基于该需求的代码快照列表

Snapshot
├── snapshot_id: UUID
├── session_id: 所属会话
├── branch_id: 所属分支
├── parent_snapshot_id: 父快照（根节点为 null，平级链快照为 null）
├── node_type: 节点类型枚举
│   └── FORK（分叉节点）| SUSPEND（挂起节点）| SIDECHAIN（平级链节点）
├── is_sidechain: bool  // 是否为平级链快照（不参与主树拓扑）
├── attached_to: Option<snapshot_id>  // 平级链快照挂载在哪个主树节点上
├── created_by: 创建者 Agent ID
├── created_at: 时间戳
├── reason: 创建原因枚举
│   └── FORK_BRANCH（开新分支）| SUSPEND_TECHNICAL（技术性挂起）
│       SUSPEND_COGNITIVE（认知性挂起）| SUSPEND_RISK（风险性挂起）
│       SUSPEND_ALL_BRANCHES（所有分支挂起触发评审会）
│       PRE_DANGER（危险操作前备份）| ATTEMPT_RETRY（挂起被打回后的重试）
├── filesystem_hash: 文件系统 Merkle Tree 根哈希
├── context_ref: Agent 上下文存储位置
└── tags: [废弃标记等]

ArchiveEntry
├── archive_id: UUID
├── session_id: 所属会话
├── snapshot_id: 关联快照（可选）
├── event_type: WORK | MEETING | DECISION
├── content: 事件详情（JSON）
└── searchable_text: 用于全文检索的文本摘要

2.3 Agent 运行时

产品 Agent (Product Agent)

生命周期状态：

IDLE → PLANNING → CODING → TESTING → REVIEWING → SUSPENDED

PLANNING：基于需求生成实现方案（不允许分支，单线程）。生成Todo List作为开发路线图。
CODING：按 Todo List 线性推进，逐项完成。Todo 项状态流转：TODO → DOING → DONE。遇到阻碍时可标记为 BLOCKED。
- 此阶段禁止分叉：即使遇到多种实现思路，也必须先选一条路走到底。
- 遇到危险操作前通知工作台创建快照（但开发阶段的快照不进入快照树，只作为工作区备份）。
TESTING：将代码提交给测试 Agent（通过中央路由发送测试请求，附带代码快照引用）。等待测试结果。
REVIEWING：测试返回结果后，分析是否通过。
- 通过：请求进入评审会（挂起）。
- 未通过：进入修复阶段，此时允许开分支探索多种修复方案（必须提供分叉原因）。
SUSPENDED：任务挂起，等待外部事件。

输出物：

代码文件（在工作区中）。
Todo List（开发路线图，供人类查看进度）。
模块关系图描述（用于可视化）。
逐模块阐释文本（用于评审会）。

测试 Agent (Test Agent)

生命周期状态：

IDLE → RECEIVING_REQ → ANALYZING → GENERATING_TESTS → EXECUTING → REPORTING → SUSPENDED

RECEIVING_REQ：通过中央路由接收测试请求。
ANALYZING：只读取需求规格（不读产品代码），分析测试点。
GENERATING_TESTS：基于需求写测试用例和测试代码。
EXECUTING：运行测试（在自己的工作区中，可能需要向工作台申请"基于产品快照创建只读副本"来运行，但不读取内容只执行）。
REPORTING：生成测试报告，通过中央路由发送给产品 Agent 和人类。
SUSPENDED：等待下一个测试请求。

关键约束：

测试 Agent 的工作区对代码内容的访问是"盲执行"：它可以运行编译和测试命令，但设计上不能"阅读"源代码的逻辑（通过工具链限制实现，如只提供编译后的二进制或接口定义）。
如果测试需要接口定义，由产品 Agent 在提交测试请求时单独提供接口契约文件（interface.json 等），不包含实现细节。

Supervisor / 知识库 Agent

生命周期状态：

IDLE → RECEIVING_QUERY → ANALYZING → RETRIEVING → INJECTING → FOLLOWUP → SUSPENDED

RECEIVING_QUERY：通过中央路由接收认知型支援请求。
ANALYZING：分析问题类型（缺文档？缺上下文？缺业务规则？）。
RETRIEVING：查询知识库（本地文档、历史存档、外部资源等）。
INJECTING：将检索到的信息通过消息发送回请求方。
FOLLOWUP：记录本次支援的尝试次数。如果同一问题被多次查询且超上限，升级通知。
SUSPENDED：等待下一个查询。

权限边界：

当前：只能响应 COGNITIVE_SUPPORT 类型的请求。
未来可解锁：TECHNICAL_APPROVAL、RISK_APPROVAL、BRANCH_LIFE_DECISION 等。

产品经理 Agent (PM Agent)

生命周期状态：

IDLE → RECEIVING_REQ → STRUCTURING → REVIEWING → SUSPENDED

RECEIVING_REQ：接收人类的原始需求（可能是一句模糊的话）。
STRUCTURING：将原始需求转化为结构化需求规格（功能描述、验收标准、边界条件、已知歧义点）。
REVIEWING：组织需求对齐评审会，确认产品 Agent 和测试 Agent 对需求的理解一致。
- 对齐通过：需求规格标记为 ACTIVE，进入编码阶段。
- 对齐不通过：需求规格挂起（走统一评审会流程）。
SUSPENDED：等待人类反馈或新需求输入。

工作空间：

与产品/测试 Agent 使用同一套快照系统，但没有分叉权。
维护内容：原始需求、需求规格 v1/v2/v3...、概要设计、详细设计、接口契约定义。

人类 (Supervisory Agent)

特殊之处：

在系统中以特殊 Agent ID（如 human://user_id）注册。
权限列表为 ALL，但实际操作受前端 UI 的显式确认保护（防止误触）。
可以加入任意组，可以接收所有类型的通知。
可以通过可视化界面直接操作工具（如打开编辑器修改代码、运行测试、创建快照）。
操作同样经过中央路由（人类的前端视为一个 Agent 客户端），确保所有操作可追溯。
小挂起响应：当工具层发送 PERMISSION_REQUEST 时，人类可以直接在通知栏输入密码或点击授权，不需要进入评审会。

2.4 分支管理引擎

职责

管理分支的生命周期：创建、运行、监控、挂起、废弃。
执行 BFS 调度：并行推进多条活跃分支，收集各分支状态。
触发全局事件：当所有活跃分支都挂起时，向中央路由发送 ALL_BRANCHES_SUSPENDED 事件。

分支状态机

CREATED → RUNNING → SUSPENDED ──→ ABANDONED（由人类在评审会上标记）
    ↑         │         │
    └─────────┴─────────┘（人类或 Supervisor 决策后可恢复为 RUNNING）

BFS 调度逻辑

while 存在 RUNNING 分支:
  for 每个 RUNNING 分支:
    推进一步（执行一个 Agent 动作或等待外部响应）
    if 分支挂起:
      发送分支挂起通知
  if 所有分支都 SUSPENDED:
    发送 ALL_BRANCHES_SUSPENDED 事件
    触发评审会
    break

注意："推进一步"的粒度是可配置的。可以是"一个 LLM 调用"，也可以是"一个完整的测试周期"。MVP 阶段建议以"一个完整的修复-测试循环"为一步。

2.5 评审会系统 (Meeting System)

职责

组织评审会议程。
收集并展示评审材料（模块关系图、接口定义、测试报告、逐模块阐释）。
记录完整会议过程。
将会议结论转化为系统动作（恢复分支、废弃分支、调整策略、修改需求等）。

评审会触发条件

强制触发（代码穷尽）：所有代码分支都挂起时，系统自动创建评审会。
强制触发（需求挂起）：需求规格被标记为挂起（需求对齐不通过）时，系统自动创建评审会。
手动触发：人类在任意时刻通过 UI 发起。
定时触发：某条分支挂起超过设定时间未处理，系统提醒人类"是否开会"。

评审会流程

1. 创建会议（生成 meeting_id，创建会议组，邀请相关 Agent 和人类）
2. 分配临时工作区（工作台为评审会创建独立的临时工作区，所有会议期间的代码修改仅限于此）
3. 冻结材料（基于当前各分支快照锁定评审材料，防止会议期间正式工作区代码变动）
4. 材料展示（通过可视化层展示模块关系图、接口、测试报告）
5. 逐模块阐释（产品 Agent 依次阐释每个模块，提供证据）
6. 质询环节（测试 Agent、人类、Supervisor 提出问题）
7. 临时修改（如人类想在会议中试改代码，只能在临时工作区进行，不影响正式分支）
8. 决策（人类做出最终决策：操作哪些分支、注入什么新提示词、是否调整需求等）
9. 执行决策（工作台根据结论向分支管理引擎下发指令，不直接修改代码）
10. 存档（完整会议记录作为独立存档写入 Archive，通过 trigger_snapshot_id 关联到触发节点）

会议结论类型（通用，适用于代码分支和需求规格）

RESUME_WITH_PROMPT(target_id, prompt)：给挂起对象注入新提示词后恢复。
- 对代码分支：给分支新的修复思路，继续运行。
- 对需求规格：澄清歧义后，重新组织需求对齐评审。
ABANDON(target_id)：废弃挂起对象。
- 对代码分支：废弃该修复路线。
- 对需求规格：废弃当前版本，由产品经理重新撰写。
FORK_NEW_BRANCH(parent_snapshot_id, strategy)：基于某代码快照开新分支尝试新方案。（仅适用于代码）
ADJUST_REQUIREMENT(new_requirement_spec)：发布新需求版本。
- 旧版本标记为 SUPERSEDED。
- 所有基于旧版本的活跃代码分支标记为 STALE_REQUIREMENT。
ADJUST_STRATEGY(new_strategy_config)：调整挂起策略（如临时开放认知型挂起）。
ESCALATE：升级给更高权限的人类（如当前审阅者权限不足）。
TERMINATE：终止整个任务（保留存档，但不再运行）。

2.5.1 小挂起处理机制（执行时阻塞）

职责

在工具层拦截操作系统级别的权限/环境阻塞。
向人类发送轻量级权限请求，不需要进入评审会。
记录授权历史，支持"记住本次选择"。

处理流程

Agent 调用工具（如 run_command("sudo apt install ...")）
    │
    ▼
工具层执行命令
    │
    ▼
操作系统返回 Permission denied / 需要密码
    │
    ▼
工具层发送 PERMISSION_REQUEST 给中央路由
    │
    ▼
人类收到通知（弹窗/消息栏）
    │
    ├────→ 输入密码 / 点击"允许一次"
    │        │
    │        ▼
    │    工具层重新执行命令（带上授权）
    │        │
    │        ▼
    │    Agent 继续运行，状态不变
    │
    └────→ 点击"拒绝"
             │
             ▼
         工具层返回错误给 Agent
         Agent 自行决定下一步（可能进入大挂起）

授权缓存

AuthorizationCache
├── tool_name: "run_command"
├── pattern: "sudo *"
├── granted_by: "human://user_id"
├── grant_type: ONCE | SESSION | PERMANENT
└── expires_at: 时间戳（可选）

2.6 可视化与交互层

职责

渲染快照树（树状图）。
渲染模块关系图（方框+连线，点击穿透接口详情）。
提供评审会的交互界面。
提供配置面板（挂起策略、Supervisor 权限、通知偏好等）。
提供工具的统一操作入口（代码编辑、测试运行、快照操作）。

核心视图

视图 A：需求时间线（Requirement Timeline View）

垂直时间轴布局，需求版本按时间顺序从上到下排列：v1 → v2 → v3 → ...
当前有效版本高亮显示，已替代版本灰显但可点击查看历史。
每个版本节点显示：版本号、创建者、状态（ACTIVE / SUPERSEDED / SUSPENDED）。
点击版本节点：右侧面板显示该版本的完整需求规格内容。
点击版本节点：代码树中高亮所有基于该版本的代码节点，其他节点变灰。
需求规格挂起时，对应版本节点闪烁红色，并显示"等待评审会"标记。

视图 B：快照树（Snapshot Tree View）

垂直时间轴布局，根在上，叶子在下。
主干（main）居中高亮，分支向两侧展开。
节点颜色编码：绿色（运行中）、黄色（挂起-认知）、橙色（挂起-风险）、红色（挂起-技术）、灰色（废弃）。
点击节点：右侧面板显示从根到该节点的思考链（时间线形式）。
点击节点旁的"历史"图标：展开该节点的平级链，显示到达此节点之前的所有中间操作（危险操作、重试记录等）。
Ctrl+点击两个节点：显示差异对比视图（公共祖先 + 分叉后的不同路径）。
双击节点：checkout 该快照，打开对应工作区内容。

视图 C：模块关系图（Module Graph View）

力导向图或层次布局：方框 = 模块，连线 = 接口依赖。
点击方框：展开模块详情（职责描述、代码位置、所属分支）。
点击连线：弹出接口定义面板（输入/输出类型、契约、变更历史）。
红色虚线 = 未通过测试的接口。
黄色闪烁 = 当前评审会正在讨论的模块。

视图 D：评审会界面（Meeting Room View）

左侧：参会成员列表（在线状态）。
中间：当前展示的材料（模块图 / 代码 diff / 测试报告）。
右侧：批注面板（人类的实时批注、历史批注）。
底部：决策操作栏（恢复/废弃/开分支/调整策略等按钮）。

3. 数据流全景

3.1 正常任务执行流（无分支）

人类提交需求 ──→ 中央路由 ──→ 产品 Agent
                                     │
                                     ▼
                              [PLANNING 阶段]
                                     │
                                     ▼
                              [CODING 阶段]
                              （危险操作前：工作台自动快照）
                                     │
                                     ▼
                         提交测试请求（元数据消息）
                                     │
                                     ▼
                              中央路由 ──→ 测试 Agent
                                                │
                                                ▼
                                         [GENERATING_TESTS]
                                                │
                                                ▼
                                         [EXECUTING]
                                                │
                                                ▼
                                         测试报告 ──→ 中央路由
                                                            │
                                                            ▼
                                                    产品 Agent + 人类
                                                            │
                                                            ▼
                                                    请求进入评审会
                                                            │
                                                            ▼
                                                    评审会系统
                                                    （会议前：工作台快照）
                                                            │
                                                            ▼
                                                    人类决策：挂起 / 继续
                                                            │
                                                            ▼
                                                    存档 + 任务挂起

3.2 分支探索流（测试发现问题后）

测试报告：失败 ──→ 产品 Agent 分析
                           │
                           ▼
                  决定开 3 条修复分支
                           │
                           ▼
           分支管理引擎创建 3 个 Fork
           （基于当前快照，各新建工作区）
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
      分支 A           分支 B           分支 C
      方案：重构       方案：补丁       方案：绕开
           │               │               │
           ▼               ▼               ▼
      运行测试       运行测试       运行测试
           │               │               │
      ┌────┴────┐     ┌────┴────┐     ┌────┴────┐
      ▼         ▼     ▼         ▼     ▼         ▼
   通过      挂起   挂起      挂起   通过      挂起
   (技术)    (风险) (认知)    (技术) (技术)    (风险)
      │         │     │         │     │         │
      ▼         ▼     ▼         ▼     ▼         ▼
   继续     通知   通知    通知   继续    通知
   运行     人类   Supervisor 人类   运行    人类

                           │
                           ▼
              分支 A 和 C 还在运行，B 已挂起
                           │
                           ▼
              （假设 A 和 C 后续也挂了）
                           │
                           ▼
              ALL_BRANCHES_SUSPENDED 事件
                           │
                           ▼
                     强制触发评审会

3.3 认知型挂起处理流（Supervisor 介入）

产品 Agent 遇到认知盲区
        │
        ▼
策略检查：认知型挂起是否被允许？
        │
   ┌────┴────┐
   ▼         ▼
  否        是
   │         │
   ▼         ▼
硬撑继续   发送 COGNITIVE_SUPPORT 请求
（到测试阶段    │
 再暴露）       ▼
           中央路由
                │
                ▼
           Supervisor Agent
                │
           ┌────┴────┐
           ▼         ▼
      查知识库    找不到
           │         │
           ▼         ▼
      返回信息    尝试次数 +1
           │      超上限？
           │    ┌────┴────┐
           │    ▼         ▼
           │   否        是
           │   │         │
           │   ▼         ▼
           │ 继续等待   升级为真正挂起
           │            （通知人类）
           ▼
      产品 Agent 基于新信息继续

4. 状态机总览

4.1 任务级状态机（Session）

                    ┌─────────────────────────────────────┐
                    │                                     │
                    ▼                                     │
CREATED ──→ PLANNING ──→ EXECUTING ──→ MEETING ──→ SUSPENDED
              │            │    ↑         │              │
              │            │    │         │              │
              │            ▼    │         ▼              │
              │         CHECKPOINT          ABORTED      │
              │            │    │         │              │
              │            └───┘         └──────────────┘
              │                                            │
              └────────────────────────────────────────────┘
                    （人类或 Supervisor 决策后恢复）

CREATED：需求已接收，尚未开始。
PLANNING：产品 Agent 生成方案阶段（线性，无分支）。
EXECUTING：编码 + 测试 + 分支探索阶段。
CHECKPOINT：执行过程中的暂停点（检查点），可能由挂起触发。
MEETING：评审会进行中，材料冻结，等待人类决策。
SUSPENDED：任务挂起，保留完整上下文，可随时恢复或终止。
ABORTED：任务被终止（仍保留存档，只是不再运行）。

4.2 分支级状态机（Branch）

FORKED ──→ ACTIVE ──→ SUSPENDED ──→ [评审会决策]
                                    │
                          ┌─────────┼─────────┐
                          ▼         ▼         ▼
                       RESUMED  ABANDONED  MERGED
                          │                   │
                          └───────────────────┘
                                    │
                                    ▼
                              （回到 ACTIVE 或结束）

FORKED：刚创建，尚未开始运行。
ACTIVE：正在运行中（BFS 调度的一环）。
SUSPENDED：挂起，等待外部决策。
RESUMED：决策后恢复运行。
ABANDONED：被废弃（在快照树上标记为灰色，但记录保留）。
MERGED：被合并到另一分支或主干（记录合并关系）。

5. 接口契约（子系统间）

5.1 中央路由 ↔ Agent

Agent.register(agent_id, role_card_id, capabilities, permission_list)
Agent.send(message_envelope)
Agent.receive() → message_envelope
Agent.join_group(group_id)
Agent.leave_group(group_id)

身份牌（Role Card）： Agent 注册时必须绑定一个身份牌，身份牌定义了该 Agent 的决策模型、可用工具集和工作区权限。身份牌本身由工作台系统统一管理，支持动态切换（如人类可以临时给某个 Agent 换一张更保守/更激进的身份牌）。

5.2 中央路由 ↔ 工作台

Router.request_content(snapshot_id, object_path, requester_id)
  → { allowed: bool, content_ref: string }

Router.log_audit(event_metadata)

5.3 Agent ↔ 工作台

Workspace.create(agent_id) → workspace_id
Workspace.snapshot(workspace_id, reason) → snapshot_id
Workspace.fork(snapshot_id, new_agent_id) → new_workspace_id
Workspace.checkout(snapshot_id) → workspace_id
Workspace.read(workspace_id, path) → content
Workspace.write(workspace_id, path, content) → { success, new_snapshot_id }
Workspace.diff(snapshot_a, snapshot_b) → diff_object
Workspace.trace(snapshot_id) → [snapshot_id, ...]  // 从根到该节点

5.4 评审会系统 ↔ 其他子系统

Meeting.create(session_id, trigger_reason, branch_ids) → meeting_id
Meeting.freeze_materials(meeting_id) → { snapshot_refs }
Meeting.add_annotation(meeting_id, agent_id, target_module, text)
Meeting.make_decision(meeting_id, agent_id, decision_type, params)
Meeting.archive(meeting_id) → archive_id
Meeting.get_transcript(meeting_id) → full_record

5.5 可视化层 ↔ 其他子系统

Visual.get_snapshot_tree(session_id) → tree_data
Visual.get_module_graph(snapshot_id) → graph_data
Visual.get_diff_view(snapshot_a, snapshot_b) → diff_data
Visual.get_meeting_room(meeting_id) → meeting_state
Visual.execute_tool(tool_name, params, user_id) → result

6. 关键技术选型建议（非约束，供参考）

层面	当前建议	理由
工作区隔离	文件系统目录 + 权限掩码	MVP 阶段足够轻量，无需 Docker
快照系统	基于 Git 对象模型，但自定义索引	利用 Git 的 diffs 和 Merkle Tree，但绕过工作区限制
消息队列	内存通道（单进程多线程）	原型阶段足够，未来可替换为 Redis/RabbitMQ
存档存储	SQLite + 文件系统	结构化查询 + 大文件（代码快照）分离存储
可视化	TUI（ratatui）或轻量 Web（Leptos）	取决于团队前端能力，两者都支持树状图和模块图
LLM 接口	预留 OpenAI/Claude 兼容层	MVP 先用硬编码模拟，接口保持一致

7. 未解决问题（需在原型中验证）

快照树的规模上限：复杂任务可能产生数百个快照，树状渲染性能如何？
盲执行的实现细节：测试 Agent 如何在"看不到源代码"的情况下编译和运行测试？（可能需要产品 Agent 提供预编译产物或接口桩）
Supervisor 知识库的范围和更新机制：知识库是静态文件还是可动态写入？谁负责维护？
多人类协作的并发控制：如果两个人类同时加入评审会并做出矛盾决策，系统如何处理？
BFS 的"一步"粒度：以"修复-测试循环"为一步可能太慢，以"单个 LLM 调用"为一步可能太快，需在原型中调参。

文档版本：2026-06-08 状态：等待审阅

35 KiB Raw Permalink Blame History Unescape Escape

人机协作 Agent 原型 —— 系统架构总览

1. 系统总体架构

2. 核心子系统详解

2.1 中央路由 (Central Router)

职责

内部结构

消息格式（标准信封）

通信模式实现

2.2 工作台与快照系统 (Workbench & Snapshot System)

职责

核心概念

数据模型

2.3 Agent 运行时

产品 Agent (Product Agent)

测试 Agent (Test Agent)

Supervisor / 知识库 Agent

产品经理 Agent (PM Agent)

人类 (Supervisory Agent)

2.4 分支管理引擎

职责

分支状态机

BFS 调度逻辑

2.5 评审会系统 (Meeting System)

职责

评审会触发条件

评审会流程

会议结论类型（通用，适用于代码分支和需求规格）

2.5.1 小挂起处理机制（执行时阻塞）

职责

处理流程

授权缓存

2.6 可视化与交互层

职责

核心视图

3. 数据流全景

3.1 正常任务执行流（无分支）

3.2 分支探索流（测试发现问题后）

3.3 认知型挂起处理流（Supervisor 介入）

4. 状态机总览

4.1 任务级状态机（Session）

4.2 分支级状态机（Branch）

5. 接口契约（子系统间）

5.1 中央路由 ↔ Agent

5.2 中央路由 ↔ 工作台

5.3 Agent ↔ 工作台

5.4 评审会系统 ↔ 其他子系统

5.5 可视化层 ↔ 其他子系统

6. 关键技术选型建议（非约束，供参考）

7. 未解决问题（需在原型中验证）

35 KiB

Raw Permalink Blame History