79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# 架构与数据流
|
||
|
||
## 设计目标
|
||
|
||
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>`。这种结构便于展示边界和清理行为，但不提供横向扩展、崩溃恢复或多租户隔离。
|