Short Drama Agent Front

短剧 Agent 的前端工作台。第一阶段支持 create-drama 与 breakdown，使用真实后端 API，不包含演示数据或浏览器端模型调用。

启动

需要 Node.js >= 22.18 和 pnpm 11。

pnpm install
cp .env.example .env
pnpm dev

浏览器访问 http://localhost:5173。先在后端仓库启动 pnpm dev，默认监听 3412。

VITE_API_BASE_URL=/api
API_PROXY_TARGET=http://localhost:3412

更改环境变量后重启 Vite。后端若运行在其他机器或端口，请修改 API_PROXY_TARGET。不能把 API Key、数据库密码等秘密写入任何 VITE_* 变量。

功能

工作区	已实现
项目列表	真实项目读取、搜索、状态筛选、新建剧本
剧本创作	主题／风格／集数配置、剧集目录与正文、角色、世界观、审核、执行记录、正文导出
创作恢复	恢复剧集生成、恢复改写，操作前确认
拆解配置	每组集数、人物／场景／道具模块选择、后端分组预览
拆解结果	主体、别名、视觉形态、Episode → Beat → Shot、主体绑定、抽取任务状态、校验问题、JSON 导出
拆解恢复	失败抽取重试、缺失剧集镜头补齐、分镜引用与 Form 绑定修复

本阶段没有实现：手工编辑剧本（后端暂无对应写接口）、StoryboardDirection graph、图像或视频生成、用户登录。正文中的模型输出按纯文本显示，避免执行不可信 HTML。

技术与规范

Vite 8、Vue 3、TypeScript、Vue Router
Tailwind CSS 4，通过 @tailwindcss/vite 集成
Reka UI：Dialog、Tabs、Checkbox、Progress 等无样式基础组件
Oxlint：脚本质量检查；ESLint：补充 Vue 模板语义
Oxfmt（不是 oxformat）：沿用后端四空格、单引号、无分号、无尾逗号的风格
Vitest + Vue Test Utils + happy-dom：API 契约、组件交互和异步生命周期测试
Lefthook + Commitlint：提交前执行检查，提交信息使用 feat:、fix:、refactor: 等

pnpm check         # lint + format:check + typecheck + test
pnpm format        # 格式化
pnpm lint:fix      # 修复可自动处理的问题
pnpm build         # Vue 类型检查 + 生产构建
pnpm preview       # 预览 dist，不含开发代理

Oxfmt 不负责代码质量，Oxlint 不负责 Vue 的完整类型推导；Vue SFC 的类型检查由 vue-tsc 承担。未照搬后端 --type-aware 来冒充完整 Vue 类型检查。

目录	职责
`src/features/projects`	项目接口、类型、列表、新建弹窗、项目布局与共享上下文
`src/features/create-drama`	剧本创作 graph 页面
`src/features/breakdown`	拆解 graph 的 API、类型、配置页面、主体与分镜组件
`src/features/workflows`	checkpoint 选择、执行记录、长请求互斥与操作确认
`src/components/ui`	跨业务使用的 Reka UI 封装与公共展示组件
`src/composables`	具备取消和竞态保护的轮询
`src/lib`	HTTP、错误格式、日期和导出工具
`src/router`	按 graph 拆分的懒加载路由

每个功能模块通过 index.ts 暴露公共入口。业务类型和行为函数均添加中文职责注释。不要把下一条 graph 的服务继续堆进 App.vue。

接口基线

对齐后端 qianlanse/short-drama-agent 的 dev： de47d42eddd5acdbd32a8b4ed3044f9155d18508。

HTTP	路径（以 /api 为前缀）	用途
GET / POST	`/projects`	项目列表 / 创建剧本
GET	`/projects/:id`	正式数据库详情、剧集、角色、世界观与审核
GET	`/projects/:id/checkpoints`	两条 graph 的 checkpoint；前端按 workflowName 过滤
POST	`/projects/:id/resume-generation`	继续生成未完成剧集
POST	`/projects/:id/resume-rewrite`	恢复审核与改写
GET	`/projects/:id/breakdown-preview?groupSize=3&modules=character,scene,prop`	真实分组与任务预览
POST	`/projects/:id/breakdown/start`	启动拆解
POST	`/projects/:id/breakdown/retry`	仅重试失败的抽取 Task
POST	`/projects/:id/breakdown/resume-shots`	复用已成功剧集镜头，生成缺失剧集
POST	`/projects/:id/breakdown/resume-storyboard`	修复已有镜头的 SubjectRef / Form，再持久化

API 层也提供 state 与 breakdown/latest 方法。页面通过共享 checkpoint 查询取得阶段状态，避免重复拉取同样内容。

异步与恢复约定

POST /projects 返回顶层 202 { projectId, status }，其他接口通常返回 { data }；HTTP 层分别兼容。
Breakdown 和恢复接口目前是长 HTTP 请求。不设客户端短超时，不自动重试 POST。关闭页面只会丢失请求连接，不会取消后端任务。
项目列表每 12 秒、项目详情每 6 秒串行刷新。隐藏页面暂停自动查询。切换项目或离开布局时取消查询，旧响应不会覆盖新项目。
抽取任务进度不是全流程进度。抽取完成之后还需要主体合并、形态、节拍、镜头和持久化。
后端失败 checkpoint 可能只有错误。页面回看最近可用的完整快照以保留成果，同时使用最新记录的 execution 状态。显示的是最近可用快照，并不保证全部成果来自最后一次执行。
后端并不为每个阶段提供持久化的 running 状态。没有明确终态时，页面显示“阶段快照 · 执行状态待确认”，不会猜测成功或失败。
恢复操作要求确认后台已停止。当前只做浏览器会话内、项目级互斥，不能替代后端跨浏览器／跨用户的任务锁。断网后先检查后台和 checkpoint，不要立即重复点击。
修改分组或模块后，必须重新预览再启动；重新拆解会调用完整流程，可能替换旧的主体和分镜。

后端限制

目前 checkpoints 接口返回完整历史与 state，没有分页或轻量状态接口。长篇剧本会增加轮询流量。下一步建议后端增加：

持久化 executionId、运行状态、跨请求互斥和幂等键；
精简的进度接口及按 graph 分页的 checkpoint；
将 Breakdown 改为 202 异步任务提交，再以轮询或 SSE 读取进度。

前端没有假装这些能力已经存在，也没有为了显示进度去调用 stream-test 等测试接口。

部署

pnpm build 生成 dist，使用 Nginx 等静态服务器部署。SPA 深层路由需要回退到 index.html。开发代理只存在于 Vite dev server，vite preview 与生产环境需配置独立后端地址或反向代理。

server {
    listen 80;
    root /var/www/short-drama-agent-front/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        # 保留 /api 前缀，不在 proxy_pass 后追加斜杠。
        proxy_pass http://127.0.0.1:3412;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffering off;
    }
}

实际生成时间可能超过代理限制，仍建议将后端改为异步提交协议。部署前应给应用加访问控制；当前后端没有身份认证，不建议直接对公网开放。

本地联调验收

后端启动成功，前端项目列表能显示数据库项目。
新建 3 集剧本，确认获取项目 ID 后进入创作页，完成后能读到正文。
查看角色、世界观与审核，再进入拆解页；预览分组与模块。
启动拆解，查看 checkpoint、主体、形态、每集 Beat / Shot 和绑定。
在可控测试项目中触发故障，确认 retry / resume-shots / resume-storyboard 各自对应正确失败阶段。

自动测试使用模拟 API，只验证前端契约与交互，不等同于真实模型、MySQL 或浏览器视觉联调。请勿用正式项目随意制造失败以测试恢复。

7.9 KiB Raw Blame History Unescape Escape