feat: initial commit

2026-09-07 09:57:33 +08:00
commit f39f6ac881
66 changed files with 9859 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Architecture
+
+## Component map
+
+```mermaid
+flowchart TB
+  subgraph Browser
+    C[assistant-ui Composer]
+    T[Thread + Tool UI]
+    E[Event Timeline]
+    S[HarnessClientStore]
+    C --> S
+    S --> T
+    S --> E
+  end
+  subgraph Server
+    F[Fastify protocol layer]
+    R[SessionRegistry]
+    ES[EventStore]
+    AB[ApprovalBroker]
+    AS[AttachmentStore]
+    MS[ModelConnectionStore]
+    P[Pi AgentSession]
+    L[DefaultResourceLoader]
+    W[SafeWorkspace]
+  end
+  S -->|JSON / multipart| F
+  F -->|SSE| S
+  F --> R
+  F --> AS
+  F --> MS
+  R --> P
+  R --> ES
+  P --> L
+  P --> AB
+  P --> W
+```
+
+`apps/server` 只做请求校验、错误映射、SSE framing 与对象组合。`packages/harness` 拥有 Agent 生命周期和所有核心状态接口。`packages/shared` 不依赖 Node，定义前后端唯一协议。`apps/web` 不拥有另一套 Agent 状态机，只用 sequence reducer 投影 EventStore。
+
+## Session creation and run
+
+1. Web 创建 Harness Session；服务器建立独立 cwd、事件序列、附件和凭证命名空间。
+2. 服务启动时严格加载并缓存 `.env` 默认模型；新 Session 优先使用该配置。没有环境配置时，Web 可把 localStorage 中通过 strict Zod 校验的非敏感模型元数据恢复到该 Session。API Key 不参与浏览器持久化，来自环境变量或服务器 AES-256-GCM 凭证库。
+3. 首次 Run 使用精确模型创建独立 Pi `AgentSession`、`SessionManager.inMemory(cwd)` 与安全 extension。
+4. message 立即得到 202；后台调用 `prompt`，Pi 事件由单一 adapter 映射并写 EventStore。
+5. SSE 将历史和实时事件交给 `HarnessClientStore`；assistant-ui External Store Runtime 只负责呈现。
+
+## Storage replacement seams
+
+`EventStore`、`ApprovalBroker`、`AttachmentStore`、`ModelConnectionStore`、`SessionRegistry` 都有接口。内存/本地临时文件实现可分别替换为 Redis streams、Postgres、对象存储、KMS 与分布式 worker，而不改变 Web 协议。
+
+## Failure and shutdown
+
+Run timeout 和用户 cancel 使用不同 reason；Approval wait 监听同一 AbortSignal。删除先 abort，再 cancel pending approval，关闭订阅与 SSE，调用 Pi `dispose()`，清凭证/附件，最后在 canonical sessions root 校验后删除 cwd。单个 SSE 断开不取消 Run。