wenxinduan50/agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: publish Agent Studio integrations and setup guide

Browse Source
This commit is contained in:
Wenxin Duan
2026-09-16 16:32:16 +08:00
parent 2ad089d68a
commit 05e6060490
106 changed files with 4942 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+153 -122
View File
@@ -1,135 +1,163 @@
# Agent Studio Mini
一个面向课堂演示的可观察 Agent Harness。它把 Pi Coding Agent SDK 放在 Fastify 服务端，通过 HTTP + SSE 将 Session、流式回复、Skills、工具调用、审批与图片附件映射到 assistant-ui 三栏工作台。
基于 React、assistant-ui、Fastify 和 Pi Coding Agent SDK 的本地 Agent 工作台。通过网页调用模型和真实 Skill，观察工具执行过程，并在图片外传、视频生成等操作前逐项审批。
> 截图占位说明：仓库不提交与本机配置绑定的截图。启动后打开 `http://127.0.0.1:5173`，即可看到左侧 Skills、中央 Streaming Chat、右侧 Event Timeline 的完整界面。
> 当前定位是单用户、本地运行的开发与验收版本，不是可直接暴露到公网的多租户产品。图生视频仍依赖 SW Ads / H3；历史成功样片不代表所有任务都已实现无人干预稳定出片。
## 架构
## 功能与状态
```mermaid
flowchart TD
UI[assistant-ui Composer / Thread / Tool UI]
API[Fastify API]
REG[SessionRegistry]
PI[Pi AgentSession]
EVT[EventStore / ApprovalBroker]
RES[ResourceLoader / Tools]
VIEW[Timeline / Approval]
CORE[Skills / Workspace / Model]
| 功能 | 当前状态 |
| --- | --- |
| 模型聊天 | 流式回复、HTTP + SSE 事件、取消运行；支持 OpenAI、Anthropic 和兼容网关配置 |
| 图片输入 | JPEG / PNG / WebP 上传、规范化和图片能力校验；视觉能力需按实际模型验证 |
| Skill 调用 | 展示目录元信息，执行时读取真实 SKILL.md 和允许的参考资源 |
| 工具审批 | 服务端管理审批、超时与拒绝；浏览器不能伪造执行成功 |
| 图生视频 | 本机草稿 → 上传审批 → SW Ads 入库 → H3 生成审批 → 查询、校验、播放、下载 MP4 |
| 旧任务接续 | 重启后，经明确确认将草稿或待生成任务接续到新会话；不重复上传、不自动生成 |
| Drama Minis 报告 | 真实指标查询与 HTML / JSON 报告；PDF 需要 Chrome / Chromium |
| CMS 剪辑 | 已有连接、素材准备和受控预览工具；完整剪辑验收仍有限制 |
UI -->|HTTP + SSE| API
API --> REG
REG --> PI
API --> EVT
PI --> RES
EVT --> VIEW
RES --> CORE
```
## 快速开始
```mermaid
sequenceDiagram
participant U as 用户
participant W as assistant-ui
participant H as Harness
participant P as Pi AgentSession
U->>W: 发送文字和可选图片
W->>H: POST message
H-->>W: 202 + runId
H->>P: prompt(text, images)
P-->>H: 文本、Skill read、Tool 事件
H-->>W: SSE HarnessEvent
P->>H: save_report_draft
H-->>W: approval.required
U->>H: Approve 或 Deny
H-->>P: 审批结果
P-->>H: tool/result + message end
H-->>W: run.completed
```
### 环境要求
职责边界：assistant-ui 只负责交互和渲染；Harness 是 Session、事件、附件、模型与审批的权威；Pi 负责 Agent loop、模型调用、ResourceLoader 与工具执行。浏览器不直接持有 Pi Session，也不能自行把写工具标为已批准。
更详细的组件和数据流见 [docs/architecture.md](docs/architecture.md)，事件对应关系见 [docs/event-mapping.md](docs/event-mapping.md)。
## 目录
```text
apps/server Fastify API、SSE、启动装配
apps/web React + assistant-ui 三栏工作台
packages/shared 浏览器与服务端共享的 Zod 协议
packages/harness Pi adapter、Session、事件、审批、附件和安全边界
.agents/skills 示例 ads-analysis Skill
fixtures 确定性的模拟广告账户数据
docs 架构、安全、事件、课堂演示和生产路线
```
## 环境与安装
- Node.js 22.19 或更高版本。Pi 0.85.1 的实际要求高于原始需求中的 Node.js 20。
- pnpm 11.7.0。
- Node.js **22.19+**；建议使用受支持的 LTS 版本。
- pnpm **11.7.0**，版本见 package.json。
- 可调用的 LLM API Key；仅启动界面和运行默认测试不需要真实 Key。
- 图生视频额外需要 SW Ads MCP Token、完整的 swads-image-to-video Skill 和 Python 3。
- FFmpeg / FFprobe 使用项目依赖中的二进制；安装时需要允许相关依赖构建和下载。
```bash
pnpm install
pnpm dev
git clone https://git.mincode.cn/wenxinduan50/agent.git
cd agent
pnpm install --frozen-lockfile
pnpm build
cp .env.example .env
```
Web 默认地址是 `http://127.0.0.1:5173`，Fastify 默认监听 `http://127.0.0.1:3001`。根命令会同时启动两者，Vite 将 `/api` 和 `/health` 代理到 Fastify。
编辑 .env，填写自己的配置。**不要提交 .env、API Key、Token 或 CMS 密码。**
在项目根目录启动后端：
```bash
node --env-file=.env apps/server/dist/index.js
```
另开一个终端，在同一目录启动网页：
```bash
pnpm --filter @agent-studio/web dev
```
- 网页：<http://127.0.0.1:5173/>
- 后端：<http://127.0.0.1:3001/>
- Vite 将 /api 和 /health 代理到后端。
首次构建不能省略，工作区包通过 dist 导出。后端源码变化后重新构建并重启；网页开发服务支持热更新。
如果已经通过 shell / IDE 注入环境变量，也可使用 `pnpm dev` 同时启动前后端。**pnpm dev 不会自动加载 .env**；上面的 `node --env-file` 才负责读取文件。
## 配置模型
模型解析优先级为：当前 Session 的 Settings 配置、服务器环境变量、明确的 `MODEL_NOT_CONFIGURED` 错误。没有“第一个可用模型”的隐式回退。
可以使用服务端环境变量，也可以在网页右上角“模型设置”中配置当前会话。优先级：当前会话配置 → 环境变量 → 明确提示未配置；不会自动切换模型。
`.env.example` 是变量清单；服务端只读取启动进程的环境，不会自动加载 `.env`。可以由 shell、IDE 或进程管理器注入，例如：
| 变量 | 用途 |
| --- | --- |
| AGENT_PROVIDER | openai、anthropic 或 compatible |
| AGENT_MODEL | 提供商支持的准确模型 ID |
| LLM_API | openai-responses、openai-completions 或 anthropic-messages |
| LLM_BASE_URL | 自定义兼容接口地址；默认限制为安全的 HTTPS 目标 |
| OPENAI_API_KEY / ANTHROPIC_API_KEY | 对应模型凭证 |
| AGENT_MODEL_SUPPORTS_IMAGES | 显式声明图片能力，不是检测结果 |
| SESSION_RUN_TIMEOUT_MS | 单次 Agent 运行上限，默认 120000 毫秒 |
| APPROVAL_TIMEOUT_MS | 审批有效时间，默认 60000 毫秒 |
```bash
export AGENT_PROVIDER=openai
export AGENT_MODEL=gpt-5-mini
export LLM_API=openai-responses
export OPENAI_API_KEY='your-key'
export AGENT_MODEL_SUPPORTS_IMAGES=true
pnpm dev
OpenAI 兼容服务通常使用 `AGENT_PROVIDER=compatible`、`LLM_API=openai-completions`，具体以所用服务契约为准。聊天模型与 H3 视频模型是独立链路，聊天 API Key 不能代替视频凭证。
网页填写的凭证只保存在服务端内存，接口返回脱敏提示；重启或清除会话后失效。网页“连接测试”可能仅返回“首次运行验证”，不能据此声称真实调用成功。
## 安装真实 Skills
仓库自带 ads-analysis、report-writer 演示 Skill。三个业务 Skill 的原始文件**不随本仓库分发**，需另行取得完整且获授权的目录，包括 references、scripts、assets 等资源。
| Skill | 默认位置 | 覆盖变量 |
| --- | --- | --- |
| swads-image-to-video | ~/.codex/skills/swads-image-to-video | IMAGE_VIDEO_SKILL_DIR |
| drama-minis-diagnosis | ~/.codex/skills/drama-minis-diagnosis | DRAMA_MINIS_SKILL_DIR |
| swads-short-drama-editor | ~/.codex/skills/swads-short-drama-editor | DRAMA_EDITOR_SKILL_DIR |
覆盖变量填写 **Skill 目录的绝对路径**，不是 SKILL.md 文件路径。其他 Skill 可使用 AGENT_SKILLS_DIRS 配置，多个目录用操作系统路径分隔符连接（macOS / Linux 为冒号）。
图生视频和剪辑还需将 PYTHON_EXECUTABLE 设置为 Python 3 可执行文件的绝对路径，可用 `command -v python3` 查询。代码中的默认路径面向本机 Codex 运行时，其他电脑不一定存在。
仅复制 Skill 文件，不等于自动接通它引用的所有工具。工具仍须经过 Harness 白名单、参数校验和审批策略适配；缺少资源或后端能力时应明确报告不可用。
## 在网页生成视频
1. 配置 SWADS_MCP_TOKEN、图生视频 Skill 和 Python，并启动服务。当前 MCP 地址由代码固定为 https://ads.mincode.cn/mcp。
2. 在 Skills 区域的“图片 → 有声视频”表单选择参考图，填写标题、动作与声音、目标秒数。
3. 点击“准备本地任务”。这一步只保存在本机并填写聊天框，**不会自动发送**。
4. 点击“发送”。Agent 读取 Skill，并申请参考图上传审批。
5. 核对图片、提示词和时长，勾选确认后批准上传。该操作会产生 SW Ads 中待审核、未分配账户的参考素材，不是完全无入库副作用。
6. 参考图就绪后，另行确认 H3 生成审批。费用以服务和账户为准，不假定免费。
7. 网页按原任务轮询。成片通过技术检查后，任务卡显示播放器和“下载 MP4”。
当前使用 H3 ref2va、9:16、768p。成片检查时长、尺寸、帧率、完整解码和音轨；符合约束的少量超长尾帧会按原速裁齐，不通过降速、循环或定格伪造时长。**技术检查通过不等于画面、声音和提示词效果已经人工验收。**
### 重启后继续任务
在原任务卡点击“继续此任务”，核对信息并确认接续到当前会话。已入库任务复用原图和回执，聊天框只准备生成审批请求，不重新上传、不自动生成。
- 只允许本地草稿和“参考图已入库 · 待生成审批”的任务接续。
- 原会话仍有效时，请回原页面继续，不能由其他会话接管。
- 排队或生成中的任务按原 job ID 查询，不重新提交。
- unknown_upload / unknown_submission 必须核实回执，不能盲目重试。
- 接续恢复任务操作权，不恢复旧聊天历史或 API Key。
当前表单要求提供图片；未传图时自动 AI 生图尚未作为完整链路交付。
## 其他工作流
- **课堂 Demo**：分析内置 demo-account 的模拟广告数据，经审批保存报告。fixtures 不是真实账户。
- **Drama Minis**：需要业务 Skill 和 SW Ads Token；真实指标查询、报告生成均受审批控制。PDF 依赖 Chrome / Chromium，失败时保留 HTML / JSON。
- **CMS 剪辑**：需要独立 CMS 配置与授权素材；图生视频不需要 CMS。详见 [CMS 接入说明](docs/editor-cms-web.md)。
## 项目结构
```text
apps/web/ React + assistant-ui，聊天、任务卡、审批、事件界面
apps/server/ Fastify API、SSE、本地任务与媒体路由
packages/harness/ Pi 适配、Skills、模型、工具策略、审批和任务状态机
packages/shared/ 前后端共享协议与 Zod 校验
.agents/skills/ ads-analysis 演示 Skill
.pi/skills/ report-writer 演示 Skill
fixtures/ 测试与演示数据
docs/ 架构、安全、接入和验收说明
scripts/ 可选诊断和真实服务验证工具
```
Anthropic 使用 `AGENT_PROVIDER=anthropic`、`LLM_API=anthropic-messages` 和 `ANTHROPIC_API_KEY`。自定义兼容服务可设置 `LLM_BASE_URL`；默认仅接受安全的 HTTPS 地址，开发环境可接受 localhost，内网地址仅在明确设置 `ALLOW_PRIVATE_LLM_BASE_URLS=true` 后允许。
```mermaid
flowchart LR
Web[网页工作台] -->|HTTP / SSE| API[Fastify + Harness]
API --> Agent[Pi Agent + 聊天模型]
Agent --> Skills[Skill 与受控工具]
Skills --> Approval[服务端审批]
Approval --> SW[SW Ads MCP / H3]
SW --> Tasks[本机任务记录与 MP4 校验]
Tasks --> Web
```
也可以在页面右上角打开 Settings，填写 Provider、API 类型、Base URL、API Key、Model 和图片能力。保存后配置只属于当前 Session。连接测试在当前实现中安全地返回“首次运行验证”，不会编造一次真实调用成功。
## 数据与安全
API Key 从同源请求提交后只驻留服务器进程内存，并在 Pi `InMemoryCredentialStore` 中注入；不会写入 localStorage、sessionStorage、IndexedDB、SSE、事件、响应或用户目录。GET 只返回脱敏的 `keyHint`。使用页面“重置训练会话”、清除凭证或重启进程会清除对应内存配置。
- .agent-studio-runtime/image-video/ 保存持久任务、冻结参考图、私有回执和已校验 MP4。备份时视为私有业务数据；回执可能含签名 URL。
- .agent-studio-sessions/ 是临时会话工作区；模型凭证、审批和事件主要驻留内存。不要依赖刷新页面恢复聊天。
- 图片外传、视频生成分开审批；服务端保留幂等键、回执和原 job ID，结果未知时停止重投。
- 媒体访问有 HTTPS、DNS / 地址校验、大小边界和文件哈希检查。本地任务接口限制 loopback 和同源访问。
- .env 文件、运行目录、依赖、构建产物、日志和一次性本机恢复脚本不进入 Git。
- **不要把本地端口直接暴露到公网。** 目前没有生产级身份认证、租户隔离或分布式锁。
- Pi 和扩展继承 Node 进程权限；工具白名单和路径校验不是操作系统沙箱。
## 图片链路
Composer 支持选择、拖拽和粘贴 JPEG、PNG、WebP，默认单图最大 5 MiB、每条消息最多 4 张。上传采用 multipart 流，服务端同时校验文件名扩展、MIME、magic bytes、尺寸与像素数，再用 Sharp 自动旋转和重新编码。规范化文件仅保存在当前 Session 临时目录。
浏览器状态和 SSE 只保存 `attachmentId` 与安全元数据。真正调用 Pi 时，服务端才读取规范化图片并构造 `ImageContent[]`。如果显式模型是 text-only，发送图片会返回 `MODEL_DOES_NOT_SUPPORT_IMAGES`，不会静默丢图或切换模型。
## 课堂 Demo
1. 打开页面并配置模型。
2. 点击“填入演示任务”，得到：`请分析 demo-account 最近 7 天广告数据，并生成一份简短报告草稿。`
3. 可选：附加一张广告素材截图，并补充“请结合图片解释创意表现，但不要从图片猜测账户指标”。
4. 点击发送。POST 会立即返回 202；中央区域流式显示回复，左右两栏显示 Skill 和事件。
5. 观察 `mock_ads_metrics` 只读工具卡。数据来自 `fixtures/ads-account.json`，不是实时广告平台。
6. `save_report_draft` 出现时选择 Approve 或 Deny。Approve 只会在当前 Session 工作区原子写入固定的 `report.md`；Deny 或超时不会创建文件。
7. 删除或重置 Session 后，附件、报告和内存凭证一起清理。
完整 10–15 分钟讲解脚本见 [docs/classroom-demo.md](docs/classroom-demo.md)。
## Skill 渐进披露
启动时 `SkillCatalog` 使用 Pi `DefaultResourceLoader` 发现 Skills，并向页面只展示名称、描述、来源、安全显示路径和 diagnostics。Skill 正文不会塞入初始前端状态。
当 Pi 的 `read` 工具成功读取一个已索引的规范化 `SKILL.md` 路径时，Harness 推导 `skill.requested` 和 `skill.loaded`。它们不是 Pi 原生事件：requested 表示已识别目标 Skill，loaded 只在 read 成功后发出。示例 Skill 要求在分析任何账户指标前调用 `mock_ads_metrics`。
## Approval 与安全边界
- 工具策略：`read`、`grep`、`find`、`ls`、`mock_ads_metrics` 允许；`save_report_draft` 必须审批；其余工具拒绝。
- 审批状态和超时由服务器 `ApprovalBroker` 决定。重复或冲突决策被拒绝。
- Session 工作区经过 realpath、路径包含关系、符号链接和保护路径检查；报告只能写固定文件。
- Base URL 做协议、userinfo、fragment、端口、DNS、私网、loopback、link-local 和云 metadata 检查。
- 上传图片不作为静态资源公开，也不把 base64 放入事件。
Pi 没有内置 Sandbox，Project Trust 也不是 Sandbox。Pi 和 Extension 继承当前 Node 进程的操作系统权限。本项目的路径校验、工具 allowlist 和审批是应用层约束，不能替代容器、VM、系统用户或网络隔离。完整说明见 [docs/security-boundaries.md](docs/security-boundaries.md)。
## 验证
## 开发与验证
```bash
pnpm lint
@@ -138,20 +166,23 @@ pnpm test
pnpm build
```
最近一次完整测试包含 123 条测试：shared 13、harness 68、server 17、web 25。默认测试使用可编程 Fake AgentSession，不需要真实 API Key、真实模型或外网。最终交付前还会重新运行以上四个命令并以实际结果为准。
2026-09-16 的验收基线为 **236 项测试**：shared 13、harness 152、server 25、web 46。默认测试使用隔离的临时数据与模拟远端，不提交真实视频任务；部分媒体检查会调用本机 FFmpeg。
## 当前依赖与 API 核对
scripts/verify-*.mjs 是可选的真实环境验证工具，部分会访问模型、上传素材或生成视频，可能产生费用。先阅读脚本并核对目标和副作用，不要作为默认安装步骤。start-private-server.mjs 是当前本机联调启动器，含特定网关和模型配置；通用部署请用环境变量和上面的启动方式。
- TypeScript 5.9.3，typescript-eslint 8.69。
- Pi Coding Agent SDK / Pi AI 0.85.1，当前公开 API 使用 `ModelRuntime.create`、`registerProvider`、`InMemoryCredentialStore`、`setRuntimeApiKey`、`createAgentSession`、`DefaultResourceLoader` 与 `defineTool`。
- Pi 0.85.1 的 schema 包是 `typebox` 1.3.7，不是 `@sinclair/typebox`。
- assistant-ui React 0.15.18，外部 Harness 状态通过 `useExternalStoreRuntime` 映射，附件通过自定义 `AttachmentAdapter` 上传。
- React 19.2.8、Fastify 5.12.3、Vite 8.2.2、Zod 4.5.4、Sharp 0.35.4。
## 已知限制与验收口径
实现只使用安装包导出的公开类型；没有修改用户目录下的 Pi 配置，也没有依赖已废弃的 Runtime 示例。
- SW Ads 上传曾返回 HTTP 500；原猫图经受控恢复后入库成功，但历史 500 的服务端根因尚未确认。
- 既往 2 秒、10 秒样片测试有过人工恢复，不应描述成全程无人干预的稳定性验证。
- 猫图已验证网页接续成功，生成仍需单独审批；接续通过不等于已经生成视频。
- 模型、网络、共享 GPU 排队、存储和第三方接口都会影响完成时间。重启后能查询任务，不代表旧 Agent 运行能自动重放。
- 当前不是完整 CMS 自动剪辑产品；画面质量、连续性和声音仍需检查。
- 尚无多用户鉴权、跨设备同步、分布式任务调度和完整生产监控。
## 已知限制与生产化
## 文档
课堂版是单进程、单实例、内存 EventStore / ApprovalBroker / ModelConnectionStore；进程退出不会恢复运行，报告和附件只是本机临时文件。浏览器直接刷新会丢失旧 Session 的 UI 引用，旧 Session 要到 Server 重启时统一清理，因此正常操作应使用页面“重置训练会话”。它没有用户身份、跨设备同步、分布式事件总线或操作系统级隔离。
生产化需要 Redis/Postgres 持久化、对象存储、KMS/Secret Manager、身份鉴权、授权与租户隔离、CSRF 和速率限制、容器或 microVM Sandbox、出站网络策略、不可篡改审计日志、分布式锁与可重放 SSE。路线见 [docs/production-roadmap.md](docs/production-roadmap.md)。
- [架构](docs/architecture.md) · [事件映射](docs/event-mapping.md) · [安全边界](docs/security-boundaries.md)
- [课堂演示](docs/classroom-demo.md) · [生产化路线](docs/production-roadmap.md)
- [图生视频说明](docs/image-to-video-web.md) · [验收清单](docs/image-to-video-acceptance.md)
- [任务接续与猫图恢复记录](docs/image-to-video-cat-recovery.md)
- [Drama Minis 报告](docs/drama-minis-web.md) · [CMS 接入](docs/editor-cms-web.md)