Agent Studio Mini

可运行的内部培训 Harness：assistant-ui 负责交互呈现，Fastify 负责 HTTP/SSE，Harness 管理 Session、事件、审批、图片和安全边界，Pi Coding Agent SDK 执行真实 Agent Loop。截图可在首次启动后补入 docs/screenshot.png。

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 或真实模型。更多内容见架构、事件映射、安全边界、课堂演示和生产路线。

4.3 KiB Raw Permalink Blame History Unescape Escape

Agent Studio Mini

快速开始

职责与行为

版本与 API 核对

安全边界与限制

验证

4.3 KiB

Raw Permalink Blame History