# 架构与数据流

## 设计目标

Agent Studio Mini 把课堂上最容易被隐藏的 Agent 行为变成可观察事件：模型流式输出、Skill 渐进加载、工具生命周期、写操作审批和 Session 清理。浏览器是投影，服务端 Harness 才是状态权威。

```mermaid
flowchart LR
  subgraph Browser
    Composer
    Thread[assistant-ui Thread]
    ToolUI[Tool UI / Approval Dialog]
    Timeline
    Store[HarnessClientStore]
  end

  subgraph Fastify
    Routes[HTTP Routes]
    SSE[SSE Connection]
  end

  subgraph Harness
    Registry[SessionRegistry]
    Session[HarnessSession]
    Events[EventStore]
    Broker[ApprovalBroker]
    Attachments[AttachmentStore]
    Models[ModelConnectionStore]
    Skills[SkillCatalog / Inference]
    Workspace[SafeWorkspace]
  end

  subgraph Pi
    Agent[AgentSession]
    Loader[DefaultResourceLoader]
    Runtime[ModelRuntime]
    Tools[Pi Tools + Extension]
  end

  Composer -->|multipart / JSON| Routes
  Routes --> Registry --> Session --> Agent
  Store -->|EventSource| SSE --> Events
  Events --> Store --> Thread
  Store --> Timeline
  Store --> ToolUI
  Session --> Attachments
  Session --> Models --> Runtime
  Session --> Skills
  Agent --> Loader
  Agent --> Tools --> Workspace
  Tools --> Broker --> ToolUI
```

## 一次消息的生命周期

1. Web 创建 Session，读取 Skill Catalog，并建立 SSE。
2. 图片由 `AttachmentAdapter` 先上传，Composer 只保留 `attachmentId`。
3. Web 提交文本和 attachment IDs；Server 校验后立即返回 `202 + runId`。
4. `HarnessSession` 显式解析当前模型，转换图片，创建或复用对应模型指纹的 Pi Session。
5. Pi 事件由 `PiEventAdapter` 串行映射。异步 Skill 路径识别完成之前不会越过后续 read-completed 或 `run.completed`。
6. `InMemoryEventStore` 分配单调 sequence；SSE 支持 cursor replay、heartbeat 和断线清理。
7. Web reducer 去重并拒绝 sequence gap，映射为 assistant-ui 外部 Runtime、工具卡、审批框和时间线。
8. run 完成、取消或失败后释放订阅；删除 Session 时取消审批、终止 run、删除附件和工作区。

## 核心所有权

| 状态 | 权威组件 | Web 的角色 |
| --- | --- | --- |
| Session / active run | `SessionRegistry` / `HarnessSession` | 发起命令、展示结果 |
| Event sequence | `EventStore` | 去重、检测缺口、重连 |
| Approval | `ApprovalBroker` | 提交一次决策、等待事件确认 |
| API Key | `ModelConnectionStore` + Pi 内存凭证 | 仅在 password input 中临时持有 |
| Attachment bytes | `AttachmentStore` | 上传阶段持有 File/object URL |
| Tool write target | `SafeWorkspace` | 不参与路径选择 |

## 进程与存储模型

课堂版只有一个 Node 进程。EventStore、ApprovalBroker 和模型配置均在内存；Session 工作区位于 `.agent-studio-sessions/<sessionId>`。这种结构便于展示边界和清理行为，但不提供横向扩展、崩溃恢复或多租户隔离。