docs: add architecture and classroom guide

2026-09-08 10:47:42 +08:00
parent da7558ab49
commit 8fa006344d
6 changed files with 459 additions and 9 deletions
@@ -0,0 +1,78 @@
+# 架构与数据流
+
+## 设计目标
+
+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>`。这种结构便于展示边界和清理行为，但不提供横向扩展、崩溃恢复或多租户隔离。