189 lines
11 KiB
Markdown
189 lines
11 KiB
Markdown
# Agent Studio Mini
|
||
|
||
基于 React、assistant-ui、Fastify 和 Pi Coding Agent SDK 的本地 Agent 工作台。通过网页调用模型和真实 Skill，观察工具执行过程，并在图片外传、视频生成等操作前逐项审批。
|
||
|
||
> 当前定位是单用户、本地运行的开发与验收版本，不是可直接暴露到公网的多租户产品。图生视频仍依赖 SW Ads / H3；历史成功样片不代表所有任务都已实现无人干预稳定出片。
|
||
|
||
## 功能与状态
|
||
|
||
| 功能 | 当前状态 |
|
||
| --- | --- |
|
||
| 模型聊天 | 流式回复、HTTP + SSE 事件、取消运行；支持 OpenAI、Anthropic 和兼容网关配置 |
|
||
| 图片输入 | JPEG / PNG / WebP 上传、规范化和图片能力校验；视觉能力需按实际模型验证 |
|
||
| Skill 调用 | 展示目录元信息，执行时读取真实 SKILL.md 和允许的参考资源 |
|
||
| 工具审批 | 服务端管理审批、超时与拒绝；浏览器不能伪造执行成功 |
|
||
| 图生视频 | 本机草稿 → 上传审批 → SW Ads 入库 → H3 生成审批 → 查询、校验、播放、下载 MP4 |
|
||
| 旧任务接续 | 重启后，经明确确认将草稿或待生成任务接续到新会话；不重复上传、不自动生成 |
|
||
| Drama Minis 报告 | 真实指标查询与 HTML / JSON 报告；PDF 需要 Chrome / Chromium |
|
||
| CMS 剪辑 | 已有连接、素材准备和受控预览工具；完整剪辑验收仍有限制 |
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- 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
|
||
git clone https://git.mincode.cn/wenxinduan50/agent.git
|
||
cd agent
|
||
pnpm install --frozen-lockfile
|
||
pnpm build
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 .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` 才负责读取文件。
|
||
|
||
## 配置模型
|
||
|
||
可以使用服务端环境变量，也可以在网页右上角“模型设置”中配置当前会话。优先级：当前会话配置 → 环境变量 → 明确提示未配置；不会自动切换模型。
|
||
|
||
| 变量 | 用途 |
|
||
| --- | --- |
|
||
| 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 毫秒 |
|
||
|
||
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/ 可选诊断和真实服务验证工具
|
||
```
|
||
|
||
```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
|
||
```
|
||
|
||
## 数据与安全
|
||
|
||
- .agent-studio-runtime/image-video/ 保存持久任务、冻结参考图、私有回执和已校验 MP4。备份时视为私有业务数据；回执可能含签名 URL。
|
||
- .agent-studio-sessions/ 是临时会话工作区；模型凭证、审批和事件主要驻留内存。不要依赖刷新页面恢复聊天。
|
||
- 图片外传、视频生成分开审批；服务端保留幂等键、回执和原 job ID，结果未知时停止重投。
|
||
- 媒体访问有 HTTPS、DNS / 地址校验、大小边界和文件哈希检查。本地任务接口限制 loopback 和同源访问。
|
||
- .env 文件、运行目录、依赖、构建产物、日志和一次性本机恢复脚本不进入 Git。
|
||
- **不要把本地端口直接暴露到公网。** 目前没有生产级身份认证、租户隔离或分布式锁。
|
||
- Pi 和扩展继承 Node 进程权限；工具白名单和路径校验不是操作系统沙箱。
|
||
|
||
## 开发与验证
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
2026-09-16 的验收基线为 **236 项测试**：shared 13、harness 152、server 25、web 46。默认测试使用隔离的临时数据与模拟远端，不提交真实视频任务；部分媒体检查会调用本机 FFmpeg。
|
||
|
||
scripts/verify-*.mjs 是可选的真实环境验证工具，部分会访问模型、上传素材或生成视频，可能产生费用。先阅读脚本并核对目标和副作用，不要作为默认安装步骤。start-private-server.mjs 是当前本机联调启动器，含特定网关和模型配置；通用部署请用环境变量和上面的启动方式。
|
||
|
||
## 已知限制与验收口径
|
||
|
||
- SW Ads 上传曾返回 HTTP 500；原猫图经受控恢复后入库成功，但历史 500 的服务端根因尚未确认。
|
||
- 既往 2 秒、10 秒样片测试有过人工恢复，不应描述成全程无人干预的稳定性验证。
|
||
- 猫图已验证网页接续成功，生成仍需单独审批；接续通过不等于已经生成视频。
|
||
- 模型、网络、共享 GPU 排队、存储和第三方接口都会影响完成时间。重启后能查询任务，不代表旧 Agent 运行能自动重放。
|
||
- 当前不是完整 CMS 自动剪辑产品；画面质量、连续性和声音仍需检查。
|
||
- 尚无多用户鉴权、跨设备同步、分布式任务调度和完整生产监控。
|
||
|
||
## 文档
|
||
|
||
- [架构](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)
|