45 lines
4.3 KiB
Markdown
45 lines
4.3 KiB
Markdown
# Agent Studio Mini
|
||
|
||
可运行的内部培训 Harness：assistant-ui 负责交互呈现，Fastify 负责 HTTP/SSE，Harness 管理 Session、事件、审批、图片和安全边界，Pi Coding Agent SDK 执行真实 Agent Loop。截图可在首次启动后补入 `docs/screenshot.png`。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI[assistant-ui Composer/Thread/Tool UI] -->|HTTP + SSE| API[Fastify API]
|
||
API --> R[SessionRegistry]
|
||
R --> P[Pi AgentSession]
|
||
R --> E[EventStore / ApprovalBroker]
|
||
P --> L[DefaultResourceLoader / Tools]
|
||
E --> UI
|
||
L --> S[Skills / Workspace / ModelRuntime]
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
要求 Node.js 20+ 与 pnpm。运行 `pnpm install`，复制 `.env.example` 为 `.env` 并按需填写，然后 `pnpm dev`；Web 为 <http://localhost:5173>，API 为 <http://localhost:3001>。也可不写环境密钥，在顶部“模型设置”中提交 Provider、API、Base URL、Model ID、Vision 能力与 API Key。密钥只在当前服务进程的 Session 内存中保存，不回传、不写 Web Storage 或 Pi 全局文件。
|
||
|
||
课堂 Demo：配置模型，发送“请使用 ads-analysis Skill，分析账户 demo-account 最近 7 天数据，找出异常 Campaign，并输出账户总结、关键指标和 3 条优化建议。最后使用 report-writer Skill 生成一份报告草稿。”可再附图并说明图片仅为辅助信号。`save_report_draft` 会暂停并等待批准；Approve 写入 Session 固定 `report.md`，Deny/Timeout 不写文件。
|
||
|
||
## 职责与行为
|
||
|
||
- Pi `AgentSession` 与 Harness Event Store 是事实来源；`useExternalStoreRuntime` 只是投影层，不请求模型。
|
||
- Skills 由 `DefaultResourceLoader.reload()` 发现，Catalog 仅显示元数据；正文保留 progressive disclosure。
|
||
- `.agents/skills`、`.pi/skills` 和按操作系统 `path.delimiter` 解析的 `AGENT_SKILLS_DIRS` 会 canonicalize、去重和诊断。
|
||
- `skill.requested`/`skill.loaded` 是 Harness 根据 canonical `SKILL.md` read 请求/成功结果推导的事件，不是 Pi 原生事件。（当前教学实现保留索引边界，完整 read preflight 映射见路线图。）
|
||
- Tool 白名单为 `read/grep/find/ls/mock_ads_metrics/save_report_draft`；未知 Tool deny，shell/edit/write 不注册。
|
||
- 上传只接受 magic bytes 与 MIME 一致的 JPEG/PNG/WebP，Sharp 自动旋转、限制像素并重编码去元数据；结构化图片传入 `session.prompt(text,{images})`。
|
||
- SSE 支持 sequence、Last-Event-ID、补发、15 秒 heartbeat、去重所需 ID 与断开清理。
|
||
|
||
## 版本与 API 核对
|
||
|
||
2026-08-26 核对 Pi 官方 SDK/Skills/Extensions/Security/Models/Providers 文档及 assistant-ui Custom Runtime/External Store/Tools/Tool UI/Attachments 文档，并检查安装包类型。实际锁定：`@earendil-works/pi-coding-agent` 0.84.3、`@assistant-ui/react` 0.15.16、`@assistant-ui/react-markdown` 0.14.12、Fastify 5.12.1、TypeBox 0.34.x。Pi 当前公开 `createAgentSession`、`DefaultResourceLoader`、`ModelRuntime.registerProvider/setRuntimeApiKey`、`SessionManager.inMemory`、`defineTool`/TypeBox；assistant-ui 当前公开 `useExternalStoreRuntime`、Toolkit 与 Attachment 类型。独立 markdown 包没有 0.15.x，故按注册表实际稳定版 0.14.12。未使用 `unstable_*`、`makeAssistantTool` 或 `useAssistantToolUI`。
|
||
|
||
## 安全边界与限制
|
||
|
||
Pi **没有内置 Sandbox**，Project Trust 只是项目资源加载防线，不是执行隔离；Pi 与 Extension 继承 Node 进程权限。本课堂版用显式工具 allowlist、随机 Session cwd、路径守卫、固定报告路径、审批、SSRF/DNS 检查、图片重编码与事件脱敏降低风险，但不等于 OS Sandbox。不可信 Skill、脚本、仓库或无人值守任务必须运行在 Docker、VM、micro-VM 或远程 Sandbox。
|
||
|
||
状态是单进程内存，重启丢失；没有用户鉴权、CSRF、速率限制、分布式协调或对象存储。生产化应加入 Redis/Postgres、对象存储、KMS、身份与租户鉴权、CSRF/限流、容器隔离、不可变审计日志和分布式 SSE。
|
||
|
||
## 验证
|
||
|
||
`pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`。默认测试使用 fake/内存边界，不需要真实 API Key 或真实模型。更多内容见 [架构](docs/architecture.md)、[事件映射](docs/event-mapping.md)、[安全边界](docs/security-boundaries.md)、[课堂演示](docs/classroom-demo.md)和[生产路线](docs/production-roadmap.md)。
|