docs: add Agent Studio Mini design spec
This commit is contained in:
Wenxin Duan
@@ -0,0 +1,221 @@
|
||||
# Agent Studio Mini 设计规格
|
||||
|
||||
日期：2026-09-07
|
||||
状态：待用户复核
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 `agent-studio-mini/` 中构建一个可运行的内部培训项目，以 Pi Coding Agent SDK 为 Agent Harness 核心，以 Fastify 提供 HTTP/SSE 服务，以 assistant-ui 提供聊天交互层。系统展示 Skill 渐进式加载、Agent Loop、工具事件、服务器权威审批、多模型配置和图片多模态输入。
|
||||
|
||||
完成标准不是静态原型：根目录的安装、lint、类型检查、测试、构建和开发启动命令都必须真实工作。默认测试使用 Fake AgentSession，不访问外网或真实模型。
|
||||
|
||||
## 2. 范围与非目标
|
||||
|
||||
### 本期范围
|
||||
|
||||
- pnpm workspace，包含 Web、Server、Harness 和 Shared 四个边界清晰的包。
|
||||
- 每个 Web Session 对应独立的 Pi AgentSession、临时工作区、事件序列、模型凭证、附件与审批状态。
|
||||
- 加载 `.agents/skills`、`.pi/skills` 和 `AGENT_SKILLS_DIRS` 中的标准 Agent Skills。
|
||||
- 只开放只读工具、`mock_ads_metrics` 和需审批的 `save_report_draft`。
|
||||
- 支持 OpenAI Responses、OpenAI Completions 和 Anthropic Messages 三类模型连接配置。
|
||||
- 支持 JPEG、PNG、WebP 上传、规范化、预览和 Pi 图片输入。
|
||||
- assistant-ui 聊天界面、Tool UI、审批交互和完整事件时间线。
|
||||
|
||||
### 非目标
|
||||
|
||||
- 不提供用户账号、组织权限、计费或多租户能力。
|
||||
- 不引入数据库、对象存储或分布式事件系统。
|
||||
- 不允许 Shell、任意文件写入、自定义请求头或浏览器直接调用模型。
|
||||
- 不声称提供 OS Sandbox；生产隔离仅在路线图中说明。
|
||||
- 不保证任意 OpenAI-compatible 服务都支持安全的连接测试。
|
||||
|
||||
## 3. 实现策略
|
||||
|
||||
采用完整纵向实现。先固化共享协议和 Harness 核心，再接入 Fastify，最后由 assistant-ui 消费同一套服务器事件。真实 Pi 适配器和测试 Fake 适配器共享 `AgentSessionPort`，避免测试依赖密钥，同时保证生产代码使用 Pi 的精确公开类型。
|
||||
|
||||
依赖使用安装时的当前稳定版本。编码前核对官方文档，安装后再以 `node_modules` 的类型定义、导出和包内示例为最终依据。若 API 与原始构建 Prompt 不一致，采用公开稳定等价实现并在 README 记录。
|
||||
|
||||
已核对的关键方向：Pi SDK 当前公开 Session 工厂、ResourceLoader、ModelRuntime、工具工厂和 `defineTool`；Pi 的 `tool_call` 在工具实际执行前触发且可以阻止；assistant-ui 提供 External Store Runtime 与附件适配器机制。精确签名将在安装依赖后确认。
|
||||
|
||||
## 4. 仓库结构
|
||||
|
||||
```text
|
||||
agent-studio-mini/
|
||||
├─ apps/
|
||||
│ ├─ server/src, tests
|
||||
│ └─ web/src, tests
|
||||
├─ packages/
|
||||
│ ├─ shared/src, tests
|
||||
│ └─ harness/src, tests
|
||||
├─ .agents/skills/ads-analysis/SKILL.md
|
||||
├─ .pi/skills/report-writer/SKILL.md
|
||||
├─ fixtures/ads-account.json
|
||||
├─ workspace/sessions/.gitkeep
|
||||
├─ docs/
|
||||
├─ package.json
|
||||
├─ pnpm-workspace.yaml
|
||||
├─ tsconfig.base.json
|
||||
└─ README.md
|
||||
```
|
||||
|
||||
`shared` 不依赖 Node 专属模块；`harness` 不依赖 React 或 assistant-ui；Server 只做协议、组合和生命周期管理；Web 不执行服务端工具。
|
||||
|
||||
## 5. 总体架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI[assistant-ui Composer / Thread / Tool UI] -->|HTTP| API[Fastify API]
|
||||
API --> REG[SessionRegistry]
|
||||
REG --> PI[Pi AgentSession Adapter]
|
||||
PI --> RL[DefaultResourceLoader]
|
||||
PI --> TOOLS[Read-only + Custom Tools]
|
||||
REG --> ES[EventStore]
|
||||
REG --> AB[ApprovalBroker]
|
||||
REG --> AS[AttachmentStore]
|
||||
REG --> MS[ModelConnectionStore]
|
||||
ES -->|SSE| STORE[HarnessClientStore]
|
||||
STORE --> UI
|
||||
AB -->|approval events| ES
|
||||
AS -->|validated images| PI
|
||||
MS -->|session-scoped runtime| PI
|
||||
```
|
||||
|
||||
Pi AgentSession 和 Harness EventStore 是运行事实来源。`HarnessClientStore` 只按服务器事件做确定性投影，assistant-ui Runtime 只负责把投影映射为聊天呈现状态。
|
||||
|
||||
## 6. 核心组件
|
||||
|
||||
### Shared 协议
|
||||
|
||||
- Zod discriminated union 定义全部 `HarnessEvent`。
|
||||
- Zod 严格校验模型配置、消息、附件引用与统一错误响应。
|
||||
- 每种事件 payload 使用专用类型，不在业务代码传播 `any`。
|
||||
- 事件禁止包含密钥、Authorization、图片 base64 和绝对敏感路径。
|
||||
|
||||
### EventStore
|
||||
|
||||
- `append` 在同一个同步原子边界内分配 sequence 并持久到内存环形历史。
|
||||
- 每 Session sequence 从 1 开始单调递增，最多保留最近 1000 条。
|
||||
- 支持按 eventId 或 sequence 回放、订阅、去重和过期游标 gap/reset 语义。
|
||||
- 高频 `assistant.delta` 保留原始顺序，由 Web reducer 合并。
|
||||
|
||||
### SessionRegistry
|
||||
|
||||
- 创建随机 Session ID 和 `workspace/sessions/<sessionId>` 独立目录。
|
||||
- 每个 Session 维护运行锁、AbortController、Pi unsubscribe、SSE 客户端、附件、审批和模型 Runtime。
|
||||
- 消息接收后立即返回 202；后台运行 prompt。同 Session 并发请求返回 409。
|
||||
- 取消与超时使用不同事件语义；删除按 cancel → resolve approvals → close SSE → unsubscribe → dispose → safe remove 的顺序执行。
|
||||
|
||||
### Skills
|
||||
|
||||
- 由 Pi `DefaultResourceLoader` 或安装版本中的公开等价接口进行发现与 reload。
|
||||
- 额外目录使用 `path.delimiter` 解析，canonicalize、验证、去重并输出 diagnostics。
|
||||
- Catalog 只展示元信息；完整正文由 Pi 通过 `read` 按需加载。
|
||||
- 对已发现 Skill 的 canonical `SKILL.md` 路径建立索引。从成功的 read 请求/结果推导 `skill.requested` 和 `skill.loaded`，不冒充 Pi 原生事件。
|
||||
|
||||
### Tools 与 ApprovalBroker
|
||||
|
||||
- 显式 allowlist：`read`、`grep`、`find`、`ls`、`mock_ads_metrics`、`save_report_draft`。
|
||||
- `mock_ads_metrics` 使用 Pi 当前要求的 TypeBox schema，读取固定 fixture 并返回结构化指标。
|
||||
- `save_report_draft` 只接收标题与正文，只能写当前 Session 的固定 `report.md`。
|
||||
- Pi extension 的 `tool_call` preflight 在执行前根据策略 allow/ask/deny。
|
||||
- ask 创建服务器权威审批并等待；Approve、Deny、Timeout、Cancel 均生成 resolution 事件。重复相同决定幂等，冲突决定返回 409。
|
||||
|
||||
### SafeWorkspace
|
||||
|
||||
- 所有路径基于 canonical Session root 校验，拒绝绝对路径逃逸、`..`、符号链接和受保护路径。
|
||||
- 报告使用同目录临时文件、排他打开和原子 rename。
|
||||
- Session 删除前验证目标确实位于专属 sessions 根目录。
|
||||
- 工具 allowlist、固定 cwd、路径守卫与审批只降低风险，不构成 Sandbox。
|
||||
|
||||
### ModelConnectionStore
|
||||
|
||||
- 配置优先级为 Session 内存配置 → 环境变量 → `MODEL_NOT_CONFIGURED`，绝不隐式选择“第一个可用模型”。
|
||||
- API Key 只保存在 Session 级内存凭证存储，不写入 Pi 全局文件或浏览器存储。
|
||||
- GET 只返回来源、configured、模型信息、安全 base URL 和 keyHint。
|
||||
- 配置替换时清除旧凭证；运行中修改返回 409；清除凭证幂等。
|
||||
- Base URL 默认只允许 HTTPS；开发环境例外允许显式 localhost。拒绝 userinfo、fragment、密钥 query、metadata IP、loopback/private/link-local 解析结果，除非环境变量明确允许私网。
|
||||
- DNS 解析和请求发送之间仍以固定解析结果或禁用跨主机重定向降低 DNS rebinding 风险。
|
||||
|
||||
### AttachmentStore
|
||||
|
||||
- multipart 流式接收并限制字节数；校验扩展名、声明 MIME 和 magic bytes。
|
||||
- 使用 sharp 检查尺寸/像素上限、自动旋转、移除元数据并重新编码。
|
||||
- 文件使用随机名写入 Session 的 `attachments/`，不进入 Web public。
|
||||
- 消息发送前验证归属、状态、数量和模型 image capability；不支持图片时返回 422，不做静默 OCR 或模型切换。
|
||||
- 传给 Pi 时才读取规范化文件并转换为 `ImageContent[]`，前端全局状态和 SSE 都不保存 base64。
|
||||
|
||||
## 7. HTTP 与 SSE 数据流
|
||||
|
||||
### 消息路径
|
||||
|
||||
1. Web 先通过 AttachmentAdapter 上传图片并持有安全元数据。
|
||||
2. `POST /messages` 校验文本/附件、Session 状态和模型能力。
|
||||
3. Server 获取运行锁，创建 runId，追加 `user.message` 与 `run.started`，返回 202。
|
||||
4. 后台调用 Pi `session.prompt(text, { images })`。
|
||||
5. 集中式 Pi Event Adapter 映射 assistant delta、tool request/result 和 run 结束事件。
|
||||
6. EventStore 同步广播到 SSE；Web reducer 按 sequence 去重并投影为 assistant-ui 消息、Tool UI 和 Timeline。
|
||||
|
||||
### 审批路径
|
||||
|
||||
1. `save_report_draft` 的 `tool_call` preflight 创建 `approval.required`。
|
||||
2. Tool 卡片和 Dialog 展示同一 approvalId。
|
||||
3. 用户操作只调用 approve/deny API；UI 等待服务器 SSE 权威状态。
|
||||
4. Broker 恢复 Pi handler：批准则执行安全写入，否则返回 Pi 官方 block 结果。
|
||||
5. Harness 追加 `approval.resolved` 和对应 tool/run 事件。
|
||||
|
||||
### SSE
|
||||
|
||||
- `id` 为 eventId，`event` 为事件类型，`data` 为 JSON。
|
||||
- `Last-Event-ID` 优先于 `afterSequence`；未知 eventId 返回可识别 gap/reset 控制事件。
|
||||
- 15 秒 heartbeat；每连接使用有界发送队列，超过上限主动断开以保护进程。
|
||||
- 监听连接关闭并清理 heartbeat、订阅与队列；SSE 断开不取消 Agent Run。
|
||||
|
||||
## 8. Web 设计
|
||||
|
||||
桌面端为 Skills、Chat、Timeline 三栏；平板可折叠侧栏；手机使用 Chat/Skills/Events tabs。顶栏展示 Session、Provider/Model、Vision 和设置入口。
|
||||
|
||||
- 左栏只显示 Skill 名称、描述、来源、diagnostics 和当前请求/加载状态。
|
||||
- 中栏使用 assistant-ui Thread/Composer primitives，支持 streaming、附件、停止、重置和 Demo Prompt 填充。
|
||||
- Tool UI 与 Pi tool name 精确一致，处理参数未完成、待审批、运行、成功、拒绝、过期、取消和失败状态。
|
||||
- 右栏按 sequence 呈现 HarnessEvent，可按类别筛选；只有用户位于底部时自动滚动。
|
||||
- Settings 使用 password input，不持久化密钥；测试连接不创建 Agent Run，也不记录返回正文。
|
||||
- 深色主题使用 `#111111`、`#25F4EE`、`#FE2C55`，通过 CSS tokens 控制层级；高饱和色仅用于状态和关键动作。
|
||||
- 所有交互支持键盘、可见 focus、ARIA 名称和至少约 44px 触控目标；流式 token 不逐个打断屏幕阅读器。
|
||||
|
||||
## 9. 错误处理与安全日志
|
||||
|
||||
- Fastify 统一返回 `{ error: { code, message, requestId, details } }`，生产环境隐藏 stack、绝对路径与内部原因。
|
||||
- Zod 错误为 400，缺失资源为 404，busy/冲突为 409，不支持图片为 422，上传超限为 413。
|
||||
- 日志使用字段 allowlist 与 redaction；不记录完整 request body。
|
||||
- Pi 未识别事件安全忽略或 debug 记录，不导致 Run 崩溃。
|
||||
- Tool preflight 抛错按 fail-closed 阻止执行。
|
||||
- Session shutdown、AbortSignal 和 Approval timer 均保证清理，避免悬挂 Promise。
|
||||
|
||||
## 10. 测试策略
|
||||
|
||||
- Shared：全部协议 schema、事件联合、错误结构。
|
||||
- Harness：Skill discovery/diagnostics、事件推导、工具、路径安全、序列、审批、并发、取消、dispose、模型无 fallback 和日志脱敏。
|
||||
- Attachment：格式、magic bytes、资源限制、跨 Session、清理、vision 映射和事件无 base64。
|
||||
- Server：API 状态码、202 异步语义、SSE 初连/回放/heartbeat/gap/关闭、模型和审批接口、SSRF、multipart。
|
||||
- Web：External Store Runtime 映射、delta 合并、Tool 状态、审批、设置脱敏、附件生命周期、三栏/响应式状态和基础可访问性。
|
||||
- 集成测试：Fake AgentSession 驱动从建 Session、配置假模型、文本+图片、delta、两个工具、审批、报告写入到 run complete 和清理的完整路径。
|
||||
- 完成前真实运行 `pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`，随后启动本地应用并人工检查桌面和手机关键路径。
|
||||
|
||||
## 11. 文档与交付
|
||||
|
||||
README 记录实际安装版本、API 核对差异、启动和配置、Demo 流程、密钥生命周期、Skill 渐进加载、推导事件以及 Sandbox 边界。另提供架构、事件映射、安全边界、课堂演示和生产路线图文档。
|
||||
|
||||
最终报告只陈述真实结果：若任一验证命令失败，明确失败原因和完成范围，不声称项目已经完成。
|
||||
|
||||
## 12. 官方资料基线
|
||||
|
||||
- Pi SDK：https://pi.dev/docs/latest/sdk
|
||||
- Pi Skills：https://pi.dev/docs/latest/skills
|
||||
- Pi Extensions：https://pi.dev/docs/latest/extensions
|
||||
- Pi Security：https://pi.dev/docs/latest/security
|
||||
- Pi Models：https://pi.dev/docs/latest/models
|
||||
- Pi Providers：https://pi.dev/docs/latest/providers
|
||||
- assistant-ui External Store：https://www.assistant-ui.com/docs/runtimes/custom/external-store
|
||||
- assistant-ui Tools：https://www.assistant-ui.com/docs/tools
|
||||
- assistant-ui Attachments：https://www.assistant-ui.com/docs/guides/attachments
|
||||
|
||||
Reference in New Issue
Block a user