从 Skill 到 Team Run：一种可插拔的 Agent 协作软件架构

单个 Agent 能够调用工具，并不等于多个 Agent 能稳定组成团队。多 Agent 系统真正困难的部分，不是把几个模型串起来，而是回答下面的问题：

• 哪些对象是可复用定义，哪些对象是一次性运行实例？
• 用户如何像安装插件一样安装 Skill，并在几分钟内创建一个带 System Prompt 的 Agent？
• 多个现成 Agent 如何快速组成团队，并获得独立 Workspace、任务目标和协作标准？
• Team Definition 更新后，正在运行的 Team Run 是否跟着变化？
• Pipeline、并行竞争和 Review Loop 如何共享同一个调度内核？
• PPT、代码和音乐拥有完全不同的 Artifact，系统怎样自动生成可浏览、可操作的团队工作台？
• 系统崩溃后，如何从持久化状态继续运行，而不是从头猜测？

这套架构的产品主线不是“预先写好一批固定 Agent 和固定页面”，而是让用户从基础能力开始组装：

Skill 是可快速安装的基础能力单元；Agent 是 Skill 与 System Prompt 的载体；Team 是用户选取多个 Agent 后形成的协作定义；Workspace、任务目标和协作协议让 Team 具备可执行边界；Team Workbench 则由通用界面规范与 Artifact 协议自动生成。

从 Skill 到 Team Workbench：完整主链

Skill Revision
      ↓
Agent Definition Revision
  = System Prompt + Skill Set + Model / Tool Policy
      ↓
Team Definition Revision
  = Agent Roster + Collaboration Pattern
      │
      ├── Workspace
      ├── Task Goal / Input Snapshot
      └── Collaboration Contract
            ├── Agent Input / Output Schema
            ├── Artifact Protocol
            ├── Routing / Review / Completion Rules
            └── Action Descriptors
                         │
                         ├── compile ──→ Team Run ──→ Agent Run
                         │                              │
                         │                              └── Artifact / Review / Event
                         │
                         └── project ─→ Workbench Schema ─→ Team Workbench

这条主链同时包含三种状态：

定义态对象描述“以后怎样运行”，运行态对象记录“这一次实际发生了什么”，体验态则把运行事实投影为用户能够理解和操作的界面。三者必须通过版本化协议连接，而不是互相越权。

下面这张白板漫画从产品使用视角展示了完整路径：安装能力、创建 Agent、组建团队、分配 Workspace、制定协议，最后生成 Team Workbench。

图：Team Workbench 不是预先写死的页面，而是 Team Definition、协作标准、Artifact 协议和通用界面规范的可视化投影。

Skill Revision：可安装的能力单元

Skill 是独立版本化能力，例如 React、Python、Vision、PPT Generation 或 Code Review。一个 Skill Revision 至少应声明：

name: playwright
version: 5
capabilities:
  - browser.read
  - browser.interact
runtime:
  type: node
entrypoint: run.mjs
permissions:
  network: restricted
  filesystem: workspace
inputs:
  - browser_task@1
outputs:
  - browser_evidence@1

Skill 的安装体验应接近插件或软件包：

Search Registry
      ↓
Inspect Capability / Permission / Version
      ↓
Install into Workspace or Personal Library
      ↓
Lock Skill Revision
      ↓
Attach to Agent Definition

“快速安装”不等于跳过治理。安装动作至少要验证包来源、依赖、权限声明、输入输出 Schema 和版本兼容性。Agent 也不能因为装载了一个 Skill，就默认获得无限网络、文件系统或凭据权限；真正授权仍应受 Workspace Policy 约束。

Agent Definition Revision：角色与能力的快照

Agent 是 Skill 的载体。用户创建一个 Agent 时，不需要从底层 Runtime 开始编程，而是完成四个选择：

1. 设定角色与名称；
2. 编写或生成 System Prompt；
3. 从已安装能力库中装载 Skill；
4. 选择模型、工具、权限和资源限制。

这些配置共同形成不可变的 Agent Definition Revision：

name: frontend-engineer
revision: 7
system_prompt: |
  你是一名负责实现与验证前端功能的工程师。
model_policy: coding-high
skills:
  - react@3
  - playwright@5
  - code-review@2
limits:
  max_steps: 80
  max_runtime_minutes: 30

产品层可以提供 Agent 模板、Skill 推荐和 System Prompt 向导，让用户快速得到所需角色；但保存后仍要生成 Revision。修改 System Prompt、增删 Skill 或更换模型都应创建新 Revision，而不是就地覆盖。这样，旧 Run 才能准确回答自己使用了哪组角色设定与能力。

Team Definition Revision：可编译的协作声明

用户可以从 Agent Library 中勾选多个 Agent，快速组成团队。但 Team Definition 不是几个 Agent 名字的数组。组队时还要明确：

• 角色节点与所引用的 Agent Definition Revision；
• 节点之间的依赖；
• 协作模式；
• Workspace 模板和资源策略；
• 协作协议与输入输出标准；
• 终止条件；
• Review 门；
• 失败与重试策略。

例如：

name: article-team
revision: 12
pattern: pipeline
nodes:
  - id: planner
    agent: planner@4
  - id: writer
    agent: writer@9
  - id: reviewer
    agent: reviewer@3
workspace_template: article-project@2
contract:
  inputs: [task_goal@1]
  artifacts: [outline@1, draft@2, review@1]
  routing: planner_to_writer_to_reviewer
completion:
  when: review.decision == approved

Workspace：团队的共享工作边界

Team 创建后必须分配 Workspace。Workspace 不只是文件夹，而是这支团队的隔离边界，至少包含：

• 文件、Artifact 与上下文；
• 可使用的 Skill 与凭据引用；
• 网络、文件系统和外部服务权限；
• 预算、资源配额与保留策略；
• Team Run、Agent Run、Event 和 Review 历史。

同一个 Team Definition 可以在不同 Workspace 中复用，但不应默认跨 Workspace 共享私有上下文或凭据。

任务目标与协作标准

任务目标属于一次具体的 Team Run 输入，而不是永久写死在 Agent 的 System Prompt 中。创建 Team Run 时，用户提交目标、约束和初始材料，系统将它们冻结为 Input Snapshot。

在正式运行前，平台还要生成或加载 Collaboration Contract。它可以由用户手工制定，也可以根据 Agent 的能力声明、输入输出 Schema、选择的 Collaboration Pattern 和组织通用规范自动起草，再交给用户确认。

一个 Collaboration Contract 至少回答：

自动生成只能作为起草器，不能默默决定高风险规则。涉及发布、付款、合并代码、发送消息等外部副作用时，协议必须显式声明权限与确认门。

启动执行时，系统把 Team Definition Revision、Workspace Policy、Input Snapshot 和 Collaboration Contract 一起编译成 Team Run 的运行图。编译后的图应被冻结，避免定义更新改变正在运行的拓扑。

Team Run 与 Agent Run

Team Run 是一次团队级执行实例，负责全局状态：

Created → Running → Waiting Review → Completed
              ├──→ Failed
              └──→ Cancelled

Agent Run 是其中一个节点的一次执行尝试：

Pending → Ready → Claimed → Running → Succeeded
                              ├──────→ Failed
                              └──────→ Timed Out

二者必须分离，因为一个 Team Run 可能包含：

• 多个 Agent Run 并行执行；
• 同一节点的多次重试；
• 等待人工输入的暂停阶段；
• Reviewer 拒绝后产生的新 Agent Run。

Team Run 完成条件由运行图判断，不能简单地写成“所有 Agent Run 都结束”。

Docker / Kubernetes 类比：Definition 不是实例

理解这套模型最直接的方法，是先区分“可复用定义”和“正在运行的实例”。Agent Definition 更接近镜像，Team Definition 更接近一份部署声明；真正开始一次协作时，系统才创建 Team Run 和 Agent Run。

这个类比最关键的结论不是名词一一对应，而是：

Agent Definition 像 Image，Agent Run 才像正在运行的 Container；Team Definition 是声明，Team Run 才是一次不可混淆的执行事实。

如果直接修改 Agent Definition，并让正在运行的 Agent 随之变化，就相当于容器启动后又悄悄替换其镜像内容：历史无法解释，失败无法复现，重试也不再是同一次语义上的重试。因此，Team Run 创建时必须固定完整版本闭包：

Team Definition Revision
├── Agent Definition Revision A
│   ├── Skill Revision 1
│   └── Skill Revision 2
├── Agent Definition Revision B
│   └── Skill Revision 3
├── Collaboration Pattern Revision
├── Workspace Policy Revision
├── Collaboration Contract Revision
├── Input Snapshot
├── Artifact / Event Schema Version
└── Workbench Schema Revision

控制循环：从一次调用变成持续协调

Kubernetes 的另一个有用启发，是控制面不把“命令已发送”当成“目标已实现”，而是持续比较期望状态与实际状态。Agent 协作系统也应采用类似的协调循环：

Team Definition
      │ compile
      ▼
Desired Run Graph
      │
      ├── observe: Agent Run / Artifact / Review / Lease
      │
      ├── compare: 哪些节点应当 Ready、Retry 或 Blocked
      │
      └── reconcile: 创建 Agent Run、回收租约、推进状态

调度器每轮只执行可幂等的状态推进。例如，只有当所有依赖 Artifact 都存在且通过契约校验时，节点才能从 blocked 进入 ready；只有持有有效租约的 Worker 才能把 Agent Run 从 claimed 推进到 running。即使调度器崩溃重启，它也能从持久化运行图重新计算下一步，而不是依赖内存中的回调链。

类比的边界

Agent 系统不能照搬 Kubernetes，因为二者判断“完成”的方式不同：

• 容器健康通常可以由退出码、探针和资源状态判断；Agent 产物往往需要语义 Review；
• Pod 重建通常追求同构副本；Agent 重试可能使用反馈生成新的 Artifact Revision；
• Agent 会调用邮件、发布、支付或代码合并等外部系统，副作用未必天然幂等；
• Team Run 的拓扑可能由 Leader 动态扩展，也可能包含 Review Loop，而不是固定副本数。

因此，Agent 控制面除了调度与健康检查，还必须拥有 Artifact 血缘、Review Gate、预算与终止条件、外部动作幂等键，以及不可逆操作的人工确认边界。

从 Definition 编译成运行图

调度器不应每次都解释高层 DSL。创建 Team Run 时，可以把定义编译成持久化 DAG：

Node A: planner
  dependencies: []
  state: ready

Node B: writer
  dependencies: [A]
  state: blocked

Node C: reviewer
  dependencies: [B]
  state: blocked

当 A 成功并产生满足契约的 Artifact 后，调度器将 B 从 blocked 迁移到 ready。状态迁移应由事务完成：

BEGIN;

INSERT INTO artifacts (...);
UPDATE run_nodes
SET state = 'succeeded'
WHERE id = :node_id
  AND state = 'running';

UPDATE run_nodes
SET state = 'ready'
WHERE id = :next_node
  AND NOT EXISTS (
    SELECT 1
    FROM run_edges e
    JOIN run_nodes parent ON parent.id = e.from_node
    WHERE e.to_node = :next_node
      AND parent.state <> 'succeeded'
  );

COMMIT;

这样，进程崩溃后可以从数据库中的运行图恢复，而不是依赖内存里的链式回调。

Collaboration Pattern 是调度语义

协作模式不只是 UI 模板，它决定 Ready 条件、完成条件和失败传播规则。

Leader / Worker

Leader 动态拆分任务，Worker 并行执行：

             Leader
          /     |     \
      Worker1 Worker2 Worker3
          \     |     /
             Merge

技术难点是动态扩展运行图。Leader 创建子任务时必须使用幂等键，否则重放 Leader 输出可能重复创建 Worker 节点。

Pipeline

Planner → Developer → Tester → Reviewer

后继节点只有在前驱成功且 Artifact 通过 Schema 校验后才能 Ready。Pipeline 的失败传播清晰，适合阶段稳定的流程。

Review Loop

Developer → Reviewer
    ↑          │
    └─ reject ─┘

循环必须有硬终止条件，例如：

• 最大迭代次数；
• 总 Token 或时间预算；
• 连续两次无实质变化；
• 人工终止。

每次修改都应产生新的 Artifact Revision，Review 必须绑定具体 Revision，不能覆盖旧稿。

Parallel Competition

多个 Agent 接收相同输入并独立产出，Selector 根据评分规则选择：

Input
 ├── Candidate A
 ├── Candidate B
 └── Candidate C
          ↓
       Selector

如果只保留获胜结果，系统会失去成本分析和模型比较数据。所有 Candidate、评分与选择理由都应保留。

Blackboard

多个 Agent 通过共享状态协作。Blackboard 不能等同于“所有 Agent 随便改同一份共享内容”，否则会出现覆盖和不可解释冲突。

更安全的做法是：

• 使用版本化 Artifact；
• 通过 Compare-and-Swap 更新共享指针；
• 对结构化区域设置写入权限；
• 把冲突作为显式事件交给协调器处理。

一次 Team Run 只绑定一种主模式

产品可以支持多种 Collaboration Pattern，但一个 Team Run 应在创建时固定主模式。

原因是不同模式拥有不同状态语义：

• Pipeline 依赖静态前后关系；
• Leader / Worker 允许动态扩图；
• Review Loop 允许受控回边；
• Blackboard 依赖共享状态版本。

运行中切换模式，相当于替换状态机。若业务确实需要切换，更可靠的做法是结束当前阶段，创建一个带新 Definition Revision 的子 Team Run，并显式传递 Artifact。

Artifact 必须是一等公民

Agent 之间不应只通过自然语言消息传递结果。每个关键输出都应成为 Artifact：

Artifact
├── id
├── type
├── schema_version
├── revision
├── uri
├── content_hash
├── producer_run_id
├── parent_artifact_ids
└── created_at

content_hash 用于完整性与去重，producer_run_id 和 parent_artifact_ids 构成血缘图。这样可以回答：

• 这份 PPT 使用了哪版大纲和图片？
• 这次代码 Review 针对哪个 Commit？
• Reviewer 的意见是否已应用到当前 Revision？

Artifact 大文件应存对象存储，数据库只保存元数据与稳定引用。

统一协作协议，不统一业务模型

PPT、代码、音乐和图片的领域结构差异很大。核心平台只需要统一协作层对象：

一种最小事件信封可以是：

{
  "eventId": "evt_01...",
  "eventType": "artifact.produced",
  "workspaceId": "ws_01...",
  "teamRunId": "tr_01...",
  "agentRunId": "ar_01...",
  "sequence": 42,
  "occurredAt": "2026-07-23T10:00:00Z",
  "payload": {
    "artifactId": "art_01...",
    "type": "presentation.slide-deck",
    "revision": 3,
    "schemaVersion": "1.0"
  }
}

关键约束包括：

• eventId 全局唯一，用于幂等消费；
• sequence 在 Team Run 内单调递增，用于排序；
• Payload 通过 eventType + schemaVersion 解释；
• Event 不携带大文件，只保存 Artifact 引用。

Action 是命令，不是按钮

UI 中的“重新生成”“批准”“发布”不能只是一段前端回调。它们应映射为带权限和前置条件的命令：

{
  "action": "artifact.regenerate",
  "target": {
    "artifactId": "art_01...",
    "revision": 3
  },
  "parameters": {
    "instruction": "压缩第三部分"
  },
  "idempotencyKey": "user_7:art_01:rev3:regen:1"
}

Server 校验：

1. 用户是否拥有操作权限；
2. 目标 Revision 是否仍是当前版本；
3. Team Run 是否允许该动作；
4. 幂等键是否已经执行。

通过后，Server 创建新的 Agent Run，而不是让浏览器直接调用底层 Runtime。

生成式 Team Workbench：协议驱动，不是页面写死

不同 Team 需要不同界面：

PPT:  Outline → Slides → Images → Animation → Export
Code: Commit → Diff → Review → PR
Music: Lyrics → Arrangement → Preview → Export

这里不应要求开发者为每支新 Team 手写一套前端。更符合这套架构的做法，是让 Workbench Generator 读取四类输入：

1. 平台通用界面规范：布局、导航、状态、错误、权限和可访问性；
2. Team Definition：角色、阶段、协作模式和完成条件；
3. Artifact Protocol：每类产物的 Schema、Revision、预览方式和可比较字段；
4. Action Descriptor：允许用户执行的重新生成、Review、批准、导出或发布动作。

生成器不必直接输出并执行任意 JavaScript。更安全的中间结果是一份声明式 Workbench Schema：

workbench: article-team
revision: 8
layout:
  type: stage-board
  stages: [outline, draft, review]
views:
  - artifact: outline@1
    component: structured-document
  - artifact: draft@2
    component: markdown-diff
  - artifact: review@1
    component: review-panel
actions:
  - artifact.regenerate
  - review.submit
  - artifact.export
bindings:
  team_run: tr_01...
  workspace: ws_01...

Platform Shell 使用可信组件库渲染 Schema，并负责鉴权、路由、主题、事件订阅和错误边界。这样，新 Team 只要给出合法 Artifact 与 Action 协议，就能快速得到一个可用面板：

Collaboration Contract
       +
Artifact Schemas
       +
Action Descriptors
       +
Generic UI Standard
       ↓
Workbench Generator
       ↓
Workbench Schema
       ↓
Team Workbench

生成的工作台至少要支持：

• 查看 Team Run、Agent Run 和阶段状态；
• 按类型预览 Artifact，并在不同 Revision 间 Diff；
• 阅读 Review 意见和失败原因；
• 只展示当前状态允许且用户有权执行的 Action；
• 订阅 Event 流并恢复到一致视图；
• 从任何界面操作追溯到对应命令与审计记录。

UI Plugin 是可选扩展，不是默认前提

当 Artifact 可以映射到 Markdown、表格、时间线、图片、音频、Diff、表单和 Review Panel 等通用组件时，声明式 Workbench Schema 已足够。只有遇到 3D 场景编辑器、专业音轨、复杂幻灯片画布等通用组件无法表达的体验时，才加载受控 UI Plugin。

Plugin 必须声明支持的 Artifact Schema、Action 和最小权限，并经过来源签名、版本兼容和沙箱检查。它仍然只能通过 Action API 写入，不能直接读取平台凭据、修改数据库或调用 Runtime。否则，“UI 热插拔”会变成任意前端代码执行入口。

恢复、重放与幂等

Team Run 的状态不能只存在于编排进程内存中。每次有意义的变化都要持久化：

NodeReady
AgentRunCreated
AgentRunClaimed
ArtifactProduced
ReviewSubmitted
NodeCompleted
TeamRunCompleted

调度器重启后读取状态快照，再从最后一个已提交 Sequence 继续消费事件。

外部副作用需要独立的幂等键。例如创建 PR、发送邮件、发布文章不能因为事件重放而执行两次。运行恢复策略必须区分：

• 可安全重算的纯计算步骤；
• 可幂等调用的外部动作；
• 必须人工确认的不可逆动作。

版本一致性

启动 Team Run 时，应固定：

• Team Definition Revision；
• 每个 Agent Definition Revision；
• 每个 Skill Revision；
• Workspace Policy Revision；
• Collaboration Contract Revision；
• Input Snapshot；
• Artifact / Event Schema Version；
• Workbench Schema Revision 与 Renderer 兼容范围。

运行期间发布新版本，不应改变已有 Team Run。要升级，应创建新的 Run 或显式迁移，并记录迁移前后的 Revision。

常见反模式

选了多个 Agent，却没有制定协作标准

Agent 名单只能说明“谁在团队里”，不能说明它们怎样协作。没有 Input、Artifact、Routing、Review 和 Completion 协议时，多个 Agent 仍然只是彼此发送自然语言的孤岛。

把任务目标写死在 System Prompt

System Prompt 定义长期角色，任务目标属于一次 Team Run。混在一起会让 Agent 无法复用，也会让历史执行难以区分“角色变了”还是“任务变了”。

用自然语言消息代替 Artifact

消息缺少稳定 Schema、版本和血缘，后续无法可靠 Review、Diff 或重放。

修改 Definition 影响正在运行的实例

这会让同一个 Run 前后使用不同规则，破坏审计和恢复。

把所有协作模式写进一个巨大状态机

条件分支持续膨胀，任何新模式都可能破坏旧流程。更好的方式是共享调度原语，让 Pattern 提供 Ready、Complete 与 Failure Propagation 规则。

为每个 Team 手写一套页面

这会把新增 Team 变成前端开发项目，破坏“快速组队”的产品目标。优先从 Artifact Schema 和 Action Descriptor 生成 Workbench Schema，只在通用组件无法表达时使用 Plugin。

让生成面板或 UI Plugin 直接写数据库、调用 Runtime

这绕过权限、幂等和审计。所有写操作都应通过 Action API。

只保存最终结果

没有 Candidate、Artifact Revision、Review 和事件链，就无法解释系统为何得到当前结果。

总体架构

Capability Registry
└── Installable Skill Revisions
              │
              ▼
Agent Builder
├── Role / System Prompt
├── Skill Set
└── Model / Tool / Permission Policy
              │
              ▼
Agent Library
              │ select & compose
              ▼
Team Builder
├── Agent Roster
├── Collaboration Pattern
├── Workspace Assignment
├── Task Goal / Input Snapshot
└── Collaboration Contract
    ├── Input / Output Standards
    ├── Artifact Protocol
    ├── Routing / Review / Completion
    └── Action Descriptors
              │
        ┌─────┴────────────────────┐
        │                          │
        ▼                          ▼
Execution Control Plane       Workbench Generator
├── Team Run Compiler         ├── Generic UI Standard
├── Persistent Run Graph      ├── Artifact Schemas
├── Pattern Controller        ├── Action Descriptors
└── Team Run                  └── Workbench Schema
    ├── Agent Run A                    │
    ├── Agent Run B                    ▼
    └── Review Gate              Team Workbench
        │                        ├── Browse / Diff
        ▼                        ├── Review / Approve
Daemon / Worker Pool            └── Regenerate / Export
└── Claude Code / Codex                 │
        │                               │ Action API
        └───────────┬───────────────────┘
                    ▼
       Artifact / Event / Review Store

这张图把产品组装路径和执行架构放在同一张图里。上半部分回答用户如何快速得到一支团队：安装 Skill、创建 Agent、选择 Agent、分配 Workspace、填写任务目标，并自动或人工确认 Collaboration Contract。下半部分则分成两条受同一协议约束的投影：

• 执行投影：把 Team Definition、任务目标和协作协议编译为持久化 Team Run；
• 体验投影：把 Artifact、Action 和通用界面规范编译为 Workbench Schema。

Runtime 只负责获得租约、准备环境并执行任务，不拥有 Team Run 的完成判定权；Team Workbench 只负责呈现事实和发送 Action，也不能绕过 Server 直接改变状态。二者通过 Artifact、Event、Review 和 Action API 汇合。

跨越整条主链的核心约束是：

• Skill 可以快速安装，但权限与版本必须显式；
• Agent 可以快速创建，但 System Prompt 与 Skill Set 必须形成可追踪 Revision；
• Team 可以快速组装，但必须拥有 Workspace、任务目标和 Collaboration Contract；
• Run 冻结当时使用的 Definition、Skill、输入、Workspace Policy 和协议版本；
• Pattern 决定 Ready、Complete、Retry 与 Failure Propagation 语义；
• Artifact 与 Event 提供血缘、审计和崩溃恢复基础；
• Review Gate 决定语义上的完成，而不是只看 Runtime 退出码；
• Workbench 从协议生成，Action API 统一所有写操作；
• UI Plugin 只是复杂体验的可选扩展，不能绕过平台治理。

只有这些边界稳定，“快速安装 Skill、快速创建 Agent、快速组成 Team、快速获得可视化面板”才不会停留在演示层，而能演进为可恢复、可审计、可扩展的软件平台。