docs: 美图 Agent 可视化界面设计文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-07 02:01:34 +08:00
parent 4e03ed7197
commit b230a418a7
54 changed files with 10700 additions and 356 deletions
--- a/docs/superpowers/specs/2026-05-07-pi-agent-video-workflow-design.md
+++ b/docs/superpowers/specs/2026-05-07-pi-agent-video-workflow-design.md
@@ -0,0 +1,111 @@
+# 美图 Agent — 视频创作可视化界面设计
+
+## 概述
+
+基于 pi-agent 为 video-from-script 工作流构建现代 Web 可视化界面。
+独立 React SPA + Express 后端 + pi-agent-core SDK 引擎。
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+| 前端 | Vite + React 18 + Tailwind CSS + shadcn/ui |
+| 后端 | Express + WebSocket (ws) + pi-agent-core |
+| 数据库 | SQLite (better-sqlite3) |
+| 语言 | TypeScript 全栈 |
+
+## 布局
+
+三栏布局 1:3:6：
+
+```
+┌──┬───────────────────────┬────────────────────────────────────────────────┐
+│💬│  搜索对话...           │  主区域：聊天 / 账户编辑 / 资产画廊            │
+│📁│  最近对话              │                                                │
+│🖼️│  历史列表...           │                                                │
+│⚙️│  [+ 新对话]           │  [输入框]                                      │
+└──┴───────────────────────┴────────────────────────────────────────────────┘
+```
+
+| 图标 | 中间栏 | 右侧主区域 |
+|------|--------|-----------|
+| 💬 对话 | 对话历史列表 + 新对话 | 聊天界面 |
+| 📁 账户 | 账户列表 | 账户编辑表单 / 提示词分屏编辑器 |
+| 🖼️ 资产 | 筛选：按账号/日期/类型 | 图片+视频画廊（瀑布流、预览、删除） |
+| ⚙️ 设置 | — | 全局配置表单 |
+
+## 后端架构
+
+```
+Express Server
+├── pi-agent-core (SDK)
+│   ├── 对话编排 + 流式输出
+│   └── 工具注册 (createAccount, editPrompt, runPipeline, deleteAsset...)
+├── Tool Layer → 调用 pipeline.js + 文件系统操作
+├── Data Layer → SQLite + FS (accounts/, output/)
+└── WebSocket → 聊天流 + pipeline 进度推送
+```
+
+### 核心数据流
+
+| 流 | 协议 | 内容 |
+|----|------|------|
+| 对话 | WebSocket | 流式 LLM 回复 + 工具调用进度 + pipeline 状态 |
+| CRUD | REST | 账户/提示词/资产的增删改查 |
+| Pipeline | 工具调用 | Agent 调用工具 → 后端执行 pipeline.js → WebSocket 推送进度 |
+
+### 数据库表
+
+| 表 | 存什么 | 关键字段 |
+|----|--------|---------|
+| conversations | 对话会话 | id, title, account_id, created_at |
+| messages | 消息记录 | id, conversation_id, role, content, tool_calls, created_at |
+| assets | 产物记录 | id, account_id, manifest_path, type, file_path, url, shot_index, created_at |
+| pipeline_runs | 执行记录 | id, manifest_path, phase, status, started_at, finished_at |
+| configs | 全局配置 | id, key, value (JSON), updated_at |
+
+## 分阶段实施
+
+| 阶段 | 内容 | 产出 |
+|------|------|------|
+| P0 | 项目脚手架 | Vite + React + Tailwind + shadcn/ui + Express + SQLite 初始化，三栏布局壳子 |
+| P1 | 账户管理 | 账户 CRUD + account.json 表单 + references 上传 + 配置页 |
+| P2 | 提示词编辑器 | 分屏 Markdown 编辑 + 模板变量高亮 + 示例数据预览 |
+| P3 | 聊天 + Pipeline | pi-agent-core 集成 + 工具注册 + WebSocket 流式 + 进度内嵌 |
+| P4 | 资产画廊 | SQLite 资产记录 + 瀑布流展示 + 预览/删除 + 按账号筛选 |
+| P5 | 对话历史 | 会话持久化 + 搜索 + 断点续跑 |
+
+## 目录结构
+
+```
+web/
+├── package.json
+├── server/
+│   ├── index.ts              # Express + WebSocket 入口
+│   ├── agent/
+│   │   ├── index.ts          # pi-agent-core 初始化
+│   │   └── tools.ts          # 自定义工具注册
+│   ├── routes/
+│   │   ├── accounts.ts       # 账号 CRUD
+│   │   ├── prompts.ts        # 提示词文件读写
+│   │   └── pipeline.ts       # Pipeline 触发/状态
+│   ├── db/
+│   │   ├── schema.ts         # SQLite 建表
+│   │   └── queries.ts        # 查询函数
+│   └── ws/
+│       └── chat.ts           # 聊天 WebSocket
+├── client/
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── ui/           # shadcn/ui 组件
+│   │   │   ├── chat/         # 聊天面板
+│   │   │   ├── accounts/     # 账户表单
+│   │   │   ├── prompts/      # Markdown 编辑器
+│   │   │   ├── assets/       # 资产画廊
+│   │   │   └── layout/       # 三栏布局壳
+│   │   ├── hooks/            # useWebSocket, useAccounts 等
+│   │   ├── lib/              # API client
+│   │   └── App.tsx
+│   └── vite.config.ts
+└── tsconfig.json
+```