GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prune stale docs and update .hermes content

Browse Source 
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
高物
2026-05-15 06:24:07 +08:00
parent 2eded08bc7
commit 3cb3efb4d0
708 changed files with 4033 additions and 142328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
docs/technical/ASSET_EXTERNAL_GENERATION_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md
View File

@@ -1,316 +0,0 @@
# 图片、视频、动作外部生成手动验证运行手册
日期：`2026-04-23`
## 1. 文档目的
这份文档用于冻结 `验证清单.md` 第四项“图片、视频、动作的生成要真实走到外部服务的生成服务上，而不是用占位符来敷衍”的验证口径。
本次先解决两个问题：
1. 当前仓库里“真实外部生成链”和“Stage 1 占位兼容链”同时存在，若不先写清楚，很容易把占位产物误记为通过。
2. 现有技术设计文档描述了多条资产链，但没有一份面向人工联调的统一运行手册，导致每次验证都要重新猜入口、猜日志、猜通过标准。
## 2. 当前结论总览
截至 `2026-04-23` 当前代码状态，第 4 项仍不能整体直接判定“已通过”，原因是不同资产链状态不同。
### 2.1 当前已经接入真实外部图片生成的入口
以下入口当前会真实请求外部图片生成服务，而不是只生成本地占位图：
1. `Big Fish` 结果页：
- `生成背景`
- `生成并应用正式图` -> `Lv.x 主图`
- `生成并应用正式图` -> `Lv.x 动作工坊`
2. `custom world / RPG 创作`：
- 场景图生成
- 作品封面 AI 生成
这些入口当前统一会走 Rust `api-server`，并向 DashScope 图片生成接口发起请求，再落到 OSS 与兼容读路径。
### 2.2 当前仍未完全闭环的入口
以下入口当前仍不能直接判定为“动作资产全后端闭环”：
1. 角色资产工坊 `image-sequence`
- 当前生成的是服务端 SVG 帧，不是真实外部序列图模型结果。
2. 角色资产工坊 `motion-transfer / reference-to-video`
- 当前仍未接入真实外部模型主链。
3. 角色资产工坊 `image-to-video`
- 当前已真实请求 Ark 生成 OSS 草稿区 `preview.mp4`。
- 但正式帧抽取和去绿幕仍在前端浏览器完成，再回传后端发布。
因此：
1. 第 4 项里“图片真实外部生成”目前可以做人工验证。
2. 第 4 项里“视频真实外部生成”已有 `image-to-video` 主链证据，但“动作正式资产全后端闭环”仍需要继续验证与收口，不能把前端抽帧回传链直接记成完全通过。
## 3. 代码级判定依据
### 3.1 已接真实外部图片服务的依据
#### 3.1.1 Big Fish 正式图片链
`server-rs/crates/api-server/src/big_fish.rs`
当前 `generate_big_fish_formal_asset(...)` 会执行：
1. 读取 Big Fish 草稿 prompt
2. 调用 `require_big_fish_dashscope_settings(...)`
3. 调用 `create_big_fish_text_to_image_generation(...)`
4. 向 DashScope `text2image/image-synthesis` 发起异步任务请求
5. 下载远端生成图片
6. 上传 OSS
7. 确认 `asset_object`
8. 绑定到 Big Fish 槽位
这条链已经不是占位图写盘。
#### 3.1.2 Custom World 场景图与封面图
`server-rs/crates/api-server/src/custom_world_ai.rs`
当前 `create_text_to_image_generation(...)` 与 `create_reference_image_generation(...)` 会：
1. 真实请求 DashScope 图片生成接口
2. 轮询任务状态或解析生成结果
3. 下载远端图片
4. 上传 OSS
5. 生成 `asset_object` 与实体绑定
因此场景图、AI 封面图当前属于“真实外部图片生成”。
### 3.2 仍未完全闭环的依据
#### 3.2.1 角色动作资产工坊
`server-rs/crates/api-server/src/character_animation_assets.rs`
当前链路现状：
1. `image-to-video` 已真实请求 Ark 生成视频
2. 成功结果会下载并写入 `generated-character-drafts/*/preview.mp4`
3. `publish` 当前仍读取前端传入的 `framesDataUrls`
4. 前端仍通过 `HTMLVideoElement + canvas` 自行抽帧并做去绿幕
因此当前状态应判定为“真实外部视频生成主链已完成，但正式动作资产后端闭环尚未完成”。
## 4. 本次验证范围
本次人工验证分成两部分。
### 4.1 可直接操作并验证通过/失败的范围
1. Big Fish 主图生成是否真实打到 DashScope
2. Big Fish 动作工坊静态关键帧图是否真实打到 DashScope
3. Big Fish 背景图是否真实打到 DashScope
4. Custom World 场景图是否真实打到 DashScope
5. Custom World AI 封面图是否真实打到 DashScope
### 4.2 本次要明确记录为“未通过”的范围
1. 角色资产工坊 `生成角色形象`
2. 角色资产工坊 `生成动作`
3. 任何依赖仓库内占位视频或 SVG 帧的动作生成入口
这些入口本次可以操作，但只能用于确认“当前仍未完全闭环”的具体断点，不能把前端抽帧回传链计入“动作资产全后端闭环”通过证据。
## 5. 前置条件
开始验证前，必须同时满足以下条件：
1. 仓库根目录 `.env.local` 已配置：
- `DASHSCOPE_API_KEY`
- `ALIYUN_OSS_BUCKET`
- `ALIYUN_OSS_ENDPOINT`
- `ALIYUN_OSS_ACCESS_KEY_ID`
- `ALIYUN_OSS_ACCESS_KEY_SECRET`
2. 本机已安装：
- `cargo`
- `node`
- `spacetime`
- `ffmpeg`
- `ffprobe`
3. 本地端口可用或已有可复用 Rust 栈：
- Web：`3000`
- Rust API：`8082`
- SpacetimeDB：`3101`
4. 必须使用 Rust 栈，而不是旧 Node 栈。
说明：
1. 当前 Vite 前端必须指向 Rust `api-server`，否则会把验证结果混入旧链路。
2. 验证时必须能实时查看 Rust `api-server` 日志。
## 6. 启动方式
推荐统一使用：
```powershell
npm run dev:rust
```
该命令会完成以下动作：
1. 启动本地 `SpacetimeDB standalone`
2. 发布 `server-rs/crates/spacetime-module`
3. 启动 Rust `api-server`
4. 启动 Vite Web 开发服务器
若已有栈在运行，至少确认：
1. Web 可访问：`http://127.0.0.1:3000`
2. Rust API 为当前前端的实际代理目标
3. `api-server` 正在输出日志
## 7. 手动验证入口
### 7.1 Big Fish 正式图片链
前端路径：
1. 打开 `http://127.0.0.1:3000`
2. 进入平台创作入口
3. 选择 `Big Fish`
4. 先完成草稿编译
5. 进入结果页
6. 在结果页依次操作：
- `生成背景`
- 打开某个等级的 `主图工坊`，点击 `生成并应用正式图`
- 打开某个等级的 `动作工坊`，点击 `生成并应用正式图`
期望日志特征：
1. Rust `api-server` 中出现 `provider = dashscope`
2. 有 Big Fish 正式图片生成请求
3. 有 DashScope 任务创建或轮询相关日志
4. 生成成功后出现 OSS 写入或正式路径返回
前端期望结果：
1. 资源 URL 不再是 `/generated-big-fish/...`
2. 而是 `/generated-big-fish-assets/...`
3. 结果页状态显示为 `已生成`，而不是 `占位已生成`
4. `Lv.x 主图` 与 `idle_float / move_swim` 正式图若下载结果为 PNG，后端会在写 OSS 前复用 RPG 角色主图透明背景 alpha 后处理；`生成背景` 不走该处理
### 7.2 Custom World 场景图
前端路径：
1. 进入 RPG / Custom World 创作流程
2. 打开场景或地标编辑入口
3. 点击场景图生成相关操作
期望日志特征：
1. Rust `api-server` 中出现 `provider = dashscope`
2. 有图片生成任务创建与轮询
3. 成功后有 OSS 对象写入和读取兼容路径
前端期望结果：
1. 返回图片不是本地 SVG 占位
2. 保存后场景主图可稳定显示
### 7.3 Custom World AI 封面图
前端路径：
1. 进入作品编辑页
2. 打开 `编辑作品封面`
3. 选择 `AI 生成作品封面`
4. 输入封面氛围提示词
5. 点击生成并保存
期望日志特征：
1. Rust `api-server` 中出现 `provider = dashscope`
2. 有封面图生成任务
3. 成功后有 OSS 上传与对象确认日志
前端期望结果：
1. 生成结果可预览
2. 保存后作品封面更新为正式图
### 7.4 角色资产工坊反向验证
前端路径：
1. 打开任一角色的 AI 资产工坊
2. 点击 `生成角色形象`
3. 再点击 `生成动作`
本入口的验证目标不是“通过”，而是确认它当前仍未接真实外部视频/图片服务。
期望证据：
1. `生成角色形象` 返回的是 SVG 草稿候选
2. `生成动作` 若未导入参考视频，会回退预置占位视频
3. 日志或结果模型字段不应被当作真实外部视频生成通过证据
## 8. 通过标准
第 4 项只有在以下条件全部满足时，才能勾成通过：
1. 至少一条图片生成入口已拿到真实外部服务调用证据。
2. 至少一条视频或动作生成入口已拿到真实外部服务调用证据。
3. 这些证据不能依赖 SVG 占位、仓库内预置视频或本地占位文件。
4. 前端结果能与日志中的正式链路一一对应。
换言之：
1. 仅图片链通过，不代表第 4 项整体通过。
2. 仅 Big Fish 动作工坊生成出一张静态图，也不等于“视频/动作真实生成”通过。
## 9. 当前预判结论
按当前代码基线，本次更可能得到以下结论：
1. 图片真实外部生成：可以拿到通过证据。
2. 视频、动作真实外部生成：`image-to-video` 主链已可拿到真实外部视频生成证据，但正式动作资产后端闭环仍需要继续收口。
因此本次人工验证完成后，建议把第 4 项拆成至少两条独立清单：
1. 图片生成真实外部服务验证
2. 视频生成真实外部服务验证
3. 动作正式资产后端闭环验证
否则会把“已完成的图片链 / 视频生成链”与“仍未完成的正式动作发布后端闭环”混成一个模糊状态。
## 10. 失败判定与排查
### 10.1 图片入口失败
优先看 Rust `api-server` 日志中的错误文本：
1. `dashscope api key 未配置`
- 说明环境变量缺失。
2. `构造 DashScope HTTP 客户端失败`
- 说明本地网络或 TLS 运行环境异常。
3. `读取生成响应失败`
- 说明上游请求已发出，但响应解析失败。
4. `下载远端图片失败`
- 说明上游已生成图片，但下载或签名读链出错。
5. OSS 相关错误
- 说明生成已成功，但落 OSS 或确认对象失败。
### 10.2 角色资产工坊“看起来成功”
若角色工坊前端看起来成功，不应立刻视为通过，需要先核对：
1. 当前策略是否是 `image-sequence / motion-transfer / reference-to-video`
2. 若是 `image-to-video`，`preview.mp4` 是否来自真实 Ark 生成
3. 正式发布是否仍要求前端回传 `framesDataUrls`
若只是“后端出真实视频、前端再抽帧回传”，则只能记为“视频生成主链通过，正式动作发布后端闭环未完成”，不能直接把整条动作资产链记为完全通过。
## 11. 关联文档
1. [BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md](./BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md)
2. [M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](./M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)
3. [M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md](./M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md)
4. [M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](./M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)
5. [AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md](./AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md)
6. [M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md](./M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md)