58 lines
5.6 KiB
Markdown
58 lines
5.6 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：配置模型，发送“请使用 demo-report Skill，读取 demo-account 最近 7 天演示数据，分析 Campaign，生成含 3 条建议的报告草稿。保存后读取报告并核对指标，明确验收是否通过。”该流程只使用固定演示数据，不查询客户账户。`save_report_draft` 会暂停并等待批准；Approve 写入 Session 固定 `report.md`，Deny/Timeout 不写文件。自动验收可在 apps/server 目录执行 `pnpm exec tsx ../../scripts/verify-demo.mts`；脚本仅自动批准自己新建会话的演示报告写入。
|
||
|
||
## 页面与功能展示
|
||
|
||
|
||
|
||
- **任务详情页**：历史任务可查看当前会话中的用户指令与 Agent 结果；所有详情页均提供“返回工作台”、右上角关闭、点击外部关闭和 `Esc` 退出。
|
||
- **日报 / 周报**：Agent 完成 `save_report_image` 后，报告图片会直接出现在对话和对应报告页；支持页面内预览及打开大图。
|
||
- **转化漏斗**：日报和周报按“曝光 → 点击 → 访问 → 加购 → 购买”展示关键指标，商品曝光包含所有视频与商品页曝光的汇总口径。
|
||
- **快捷任务**：日报、周报、投放分析和素材策划卡片点击后仅带入指令，不会自动提交固定问题。
|
||
- **运行详情**：右侧展示接收任务、分析规划、工具执行、人工确认和结果整理状态，并保留工具调用与错误诊断信息。
|
||
- **技能目录**：展示已加载 Skill 及诊断状态，支持关闭按钮和点击外部退出。
|
||
|
||
> 仓库展示图不包含 API Key、真实账户凭据或浏览器记录。模型凭据只允许放入本机 `.env` 或当前服务进程，不提交到 Git。
|
||
|
||
## 职责与行为
|
||
|
||
- 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)。
|