agent/docs/architecture.md

架构与数据流

设计目标

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

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>。这种结构便于展示边界和清理行为，但不提供横向扩展、崩溃恢复或多租户隔离。