# 美图 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
```