astrbot_plugin_imagestudio/docs/project-migration-handoff-2026-07-18.md

1195 行
37 KiB
Markdown

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# AstrBot ImageStudio 项目迁移与 Codex 交接文档
> 更新时间:2026-07-18(Asia/Shanghai)
> 当前工作区:`C:\Users\Administrator\Documents\AstrBot ImageStudio`
> 当前开发版本:`1.0.32`
> 1.0.32 代码快照提交:`937ee73`
> 目标读者:迁移后的新 Codex 账号、新工作区维护者、后续开发者
> 文档目的:只读取本文件即可恢复当前开发背景、代码状态、实机环境、最新问题和下一步修复任务。
---
## 0. 必须首先阅读的迁移警告
Forgejo 的 `main` 分支和正式标签仍停在 **v1.0.20**,但完整的 1.0.21~1.0.32 开发成果已经提交并推送到:
```text
origin/codex/ui-navigation-s130-s145
```
1.0.32 代码快照提交为:
```text
937ee73 release: complete ImageStudio 1.0.32 advanced material workflows
```
该提交已经包含:
- 进阶素材主服务;
- 多图片画风工作流;
- 新数据库迁移;
- 新仓储层;
- 新前端页面;
- 新测试;
- 1.0.21~1.0.31 发布包;
- 1.0.32 最新算法修改。
因此迁移时可以直接从 Forgejo 恢复,但必须切换到正确分支:
1. 可以重新 `git clone` Forgejo 仓库。
2. 克隆后必须执行 `git checkout codex/ui-navigation-s130-s145`。
3. 必须确认 HEAD 至少包含提交 `937ee73`。
4. 不要直接停留在 `main`,否则只会得到 v1.0.20。
5. `.tmp` 中的视觉审计副本没有推送,但它不是源码真相;真实测试图片和数据库仍在 NAS `plugin_data`。
推荐恢复命令:
```powershell
git clone ssh://git@forgejo-nas:18086/YokiiroBW/astrbot_plugin_imagestudio.git
cd astrbot_plugin_imagestudio
git checkout codex/ui-navigation-s130-s145
git pull --ff-only
git status --short --branch
git log -3 --oneline --decorate
```
也可以复制整个本地项目目录(包括 `.git`),但现在已经不再是唯一安全方式。
---
## 1. 当前 Git 状态
### 1.1 分支和远端
- 当前分支:`codex/ui-navigation-s130-s145`
- 跟踪分支:`origin/codex/ui-navigation-s130-s145`
- 1.0.32 代码快照:`937ee73`
- 当前 HEAD 可能在其后包含仅交接文档同步的提交
- `origin/main` 也位于 `176ee24`
- Forgejo 远端:
```text
ssh://git@forgejo-nas:18086/YokiiroBW/astrbot_plugin_imagestudio.git
```
### 1.2 最近提交
```text
937ee73 release: complete ImageStudio 1.0.32 advanced material workflows
176ee24 release: add ImageStudio 1.0.20 install package
7cfa01b docs: record ImageStudio 1.0.20 deployment verification
2212800 merge: synchronize Forgejo main before 1.0.20
11b4cda release: complete ImageStudio 1.0.20 workflow audit
b5dd6c5 release: publish ImageStudio 1.0.8
```
### 1.3 重要结论
- 当前本地代码版本是 `1.0.32`。
- 1.0.21~1.0.32 已提交到 `937ee73`。
- `codex/ui-navigation-s130-s145` 已推送并与远端同步。
- 提交后的工作树干净。
- `main` 尚未合并,v1.0.32 尚未建立正式 tag/release。
### 1.4 1.0.32 提交的主要修改范围
提交中包含但不限于:
- `CHANGELOG.md`
- `_conf_schema.json`
- `config.yaml`
- `main.py`
- `metadata.yaml`
- `core/config_service.py`
- `core/astrbot_provider_bridge.py`
- `database/models.py`
- `engines/vision_provider.py`
- `engines/single_flow.py`
- 多个 `backend/routes/`、`backend/services/` 文件
- 多个前端设置、工作流、素材页面
- `pages/imagestudio/` 和 `web/` 的构建产物
- AstrBot provider bridge 相关测试
### 1.5 已纳入版本控制的关键新增文件
这些文件已经包含在 `937ee73` 中,切换到正确分支后应当存在:
```text
backend/dto/advanced_material_dto.py
backend/routes/advanced_material_routes.py
backend/services/advanced_material_service.py
backend/services/advanced_material_worker_runtime.py
backend/services/advanced_style_set_service.py
backend/services/material_catalog_resolver.py
core/model_route_chain.py
database/migrations/0016_advanced_materials.sql
database/migrations/0017_advanced_wardrobe_items.sql
database/migrations/0018_advanced_style_sets.sql
database/repositories/advanced_material_repository.py
frontend/shared/types/advanced-material.ts
frontend/standalone-web/src/features/materials/
frontend/standalone-web/src/features/settings/model-route-chain.ts
frontend/tests/advanced-material-upload.test.mjs
tests/test_advanced_material_boundary_services.py
tests/test_advanced_material_migrations.py
tests/test_advanced_material_repository.py
tests/test_advanced_material_worker_recovery.py
tests/test_advanced_material_workflow.py
tests/test_advanced_style_set_workflow.py
tests/test_advanced_style_vision.py
tests/test_material_catalog_resolver.py
tests/test_model_route_chain.py
```
发布包 `release/astrbot_plugin_imagestudio-1.0.21.zip` 至 `1.0.31.zip` 已包含在 `937ee73` 中。
目前没有正式生成 `release/astrbot_plugin_imagestudio-1.0.32.zip`;1.0.32 是通过临时 tar 包直接部署到 NAS,NAS 临时包已删除。
---
## 2. 当前版本状态
版本已经统一为 `1.0.32`:
```text
metadata.yaml: version: 1.0.32
core/config_service.py: PLUGIN_VERSION = "1.0.32"
config.yaml: plugin.version = 1.0.32
frontend/package.json: version = 1.0.32
frontend/package-lock.json: version = 1.0.32
```
`CHANGELOG.md` 已新增并提交 1.0.21~1.0.32 的开发记录。
---
## 3. 实机环境与部署方式
### 3.1 AstrBot 测试环境
- NAS 地址:`192.168.31.210`
- AstrBot WebUI:`http://192.168.31.210:26385`
- 容器名:`astrbot-ops-pro`
- NAS 共享目录:`\\YokiiroNAS\Dockers\qqbot\astrbot-ops-pro`
- NAS 插件目录:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio
```
- 插件数据目录:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio
```
- SQLite 数据库:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio/db/imagestudio.db
```
- 进阶素材文件根:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio/advanced_materials
```
### 3.2 SSH
- SSH 用户:`agent`
- SSH 端口:`77`
- SSH 私钥路径:
```text
C:\Users\Administrator\.ssh\codex_yokiiro_nas_ed25519
```
- 当前使用的 SSH 客户端:
```text
C:\Program Files\Git\usr\bin\ssh.exe
```
基本连接命令:
```powershell
& 'C:\Program Files\Git\usr\bin\ssh.exe' `
-i 'C:\Users\Administrator\.ssh\codex_yokiiro_nas_ed25519' `
-p 77 `
-o BatchMode=yes `
agent@192.168.31.210
```
公钥已经加入 NAS。不要在文档或提交中写入私钥内容、API Key、Forgejo Token 或 AstrBot API Key。
### 3.3 部署约定
用户明确要求:
- 不使用 AstrBot 浏览器插件安装 UI;
- 直接覆盖 NAS 插件文件;
- 通过 SSH 重启 Docker 容器;
- 修改后在 `astrbot-ops-pro` 实机验证;
- 没有明确授权时,不触发真实付费生图。
部署时要注意:
1. 备份目录不能放在 `data/plugins/` 内,即使目录以 `.` 开头,AstrBot 仍会把它当插件扫描。
2. 备份应放在:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups
```
3. 当前 1.0.31 备份位置:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups/astrbot_plugin_imagestudio-1.0.31-pre-1.0.32
```
4. 插件源码目录可以整体替换,但绝对不要删除 `plugin_data/astrbot_plugin_imagestudio`,数据库、用户设置、进阶素材和生成图片都在那里。
### 3.4 当前实机状态
- 实际插件目录版本:`1.0.33`
- 日志确认:
```text
Plugin astrbot_plugin_imagestudio (1.0.33) by YokiiroBW
```
- AstrBot 主页面返回 HTTP 200。
- 插件 Web 路径直接无认证访问会返回 `Missing API key`,这是正常鉴权行为。
- 插件数据库文件仍存在,启动日志未出现导入失败、`no such table` 或 Traceback。
- 1.0.32 部署前备份:
```text
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups/astrbot_plugin_imagestudio-1.0.32-pre-1.0.33-20260719-202040
```
- 本轮部署没有触发真实生图。
### 3.5 Docker Health 已知问题
容器进程正常运行,WebUI、OneBot、MCP 和插件均已启动,但 Docker 状态显示 `unhealthy`。
原因是容器自带 `/usr/local/bin/healthcheck.py` 固定探测:
```python
PORTS = [6185, 6195, 6199]
```
实际监听端口为:
```text
6185 AstrBot WebUI
6190 desktop assistant WebSocket
6199 另一个 AstrBot HTTP 服务
```
`6195` 未监听,导致健康探针失败。此问题不是 ImageStudio 1.0.32 导致,目前没有修改容器 Healthcheck。
另外,启动日志有 `faiss.swigfaiss_avx2` 加载失败后自动回退到普通 faiss,并最终加载成功;这是 LivingMemory/FAISS 环境日志,也不是 ImageStudio 错误。
---
## 4. 项目开发历史总览
以下内容是当前长对话中已经完成或反复修复的主要功能线。
### 4.1 UI 与设置页早期建设
- 建立设置页和日志页大框架。
- 适配器卡片改为两列摘要卡,展开后使用独立悬浮配置卡。
- 适配器卡片边角颜色表示连接状态。
- 增加 API 地址、Key、模型和生成 endpoint 配置。
- 增加连接测试、模型发现和 1K/2K/4K 能力测试。
- 分辨率测试定义:
- 1K:1920×1080
- 2K:2560×1440
- 4K:3840×2160
- V1 地址测试支持自动寻找模型/生图 endpoint。
- 增加数据备份、导入和导出。
- 增加模型分工设置、推荐说明和多路交叉审核路由。
- 增加素材识别提示词选择集和分类下拉限制。
- 增加群聊白名单、用户白名单与命中规则。
- 适配器模型选择支持输入和下拉选择。
- 增加适配器复制能力。
- 多次修复暗色主题、模态框、下拉框和图标布局。
- 多次修复鼠标拖选文本越过模态框边界时误关闭的问题。
### 4.2 AstrBot 命令工作流
- 设计并实现 `/影棚` 和 `/yp` 命令框架。
- 帮助和状态支持图片化返回。
- 单图、快速角色、角色工作流接入白名单策略。
- 完成命令开发队列,并曾发布/推送早期版本。
### 4.3 适配器、安装与持久化修复
- 修复 AstrBot 插件环境中的绝对 import 路径问题。
- 修复初次安装数据库表不存在,例如 `material_categories`。
- 修复插件启动后前端需要手动点击连接的问题。
- 将测试改为“保存并测试”,确保使用服务端已持久化配置。
- 修复适配器名称、endpoint 自动回填以及 API Key 无法输入/保存。
- 修复 401 授权头、endpoint 探测和模型发现兼容性。
- 修复设置保存后弹回设置页、信息消失等问题。
### 4.4 生成页、队列和快速角色
- 图片生成支持直接提示词和可选 LLM 扩写。
- 模型选择统一显示“适配器名称/模型”。
- 深色主题模型下拉背景修复。
- 生成后增加素材选择、上传/粘贴和识别入口。
- 修复队列失败任务不能重试、删除或清理的问题。
- 快速角色四张图拆成独立并发任务,避免共享超时。
- 队列标题从裸 UUID 优化为任务概览,例如“快速角色/名字/头像”。
- 修复快速角色、角色档案和角色工作流之间的数据串线。
- 修复工作流头像池混入普通单图的问题。
- 增加快速角色统一度和性别一致性检查。
### 4.5 角色工作流二次审计
- 依据 `对工作流的二次审计.md` 对现有 `character_gradual` 主线做增量优化。
- 没有新建平行工作流。
- 工作流允许进入查看,但仅第一个节点可用。
- 完成人设导入后依次解锁后续节点。
- 相关文件:
```text
docs/workflow-secondary-audit-2026-07-15.md
docs/workflow-secondary-audit-development-queue.md
```
### 4.6 进阶素材与多图画风工作流
从 1.0.21 开始新增:
- 普通素材和进阶素材数据库/文件库隔离。
- 进阶素材先识别,再使用文字提示词生成验证图。
- 用户确认还原度后才入库。
- 不还原时可以追加文字调整并生成新轮次。
- 进阶素材具有更高使用优先级。
- 画风分类允许 2~8 张图片并发识别。
- 各图片独立任务、超时、错误和重试。
- 多图交叉共识区分:
- 核心共同画风
- 可变特征
- 内容污染
- 离群样本
- 代表样本
- 生成 compact/standard/detailed 三档胶囊。
- 使用头像、全身、跨场景三张纯文字验证图。
- 验证生图不携带源图,专门测试文字胶囊的迁移能力。
- 三张验证图独立并发、独立队列、独立重试。
- 历史轮次保留完整三张图。
- 图片支持点击放大。
- 删除队列记录后父导入会自动对账为可重试失败。
详细设计文档:
```text
docs/advanced-material-workflow-1.0.21.md
docs/advanced-style-set-workflow-1.0.22.md
```
---
## 5. 1.0.30~1.0.32 画风算法演进
### 5.1 1.0.30
- 复验时同时提交代表源图和上一轮三张验证图。
- 用户文字反馈解析成 increase/decrease/remove/preserve。
- 增加方向防反转,例如“对比太强”不能被 LLM 改成更高对比。
- 三张图使用 detailed 胶囊,而不是短共识提示词。
### 5.2 1.0.31
- 识别维度增加脸型、眼睛、鼻口、头身比、发束、线条拓扑、阴影色相、高光形状和色彩关系。
- 归一化层保留 attributes,并自动生成 `must_preserve`。
- 内容污染清单不再原样加入负面提示词。
- 修复 detailed 胶囊被逗号拆碎和重复拼接。
- 每张验证图生成后自动使用代表源图进行画风审核。
- 前端显示自动还原度和主要偏差。
### 5.3 1.0.32 已完成内容
核心实现:
```text
backend/services/advanced_style_set_service.py
```
已经增加:
- 固定审核协议 `STYLE_REVIEW_SCHEMA_VERSION = 2`。
- 固定维度:
- face_structure
- eye_design
- hair_rendering
- linework
- palette_global
- palette_local
- shading
- highlights
- anatomy_scale
- texture_detail
- background_rendering
- 头像、全身和跨场景使用不同维度权重。
- 复验聚合上一轮自动审核结果。
- 至少两个场景重复的问题归类为公共画风问题。
- 单场景问题归类为尺度特定问题。
- 共识请求新增:
- `prompt_priority_groups`
- `scale_capsules`
- `semantic_risk_audit`
- detailed 胶囊按核心、结构、渲染优先级编译。
- 公共胶囊限制为 14 条,尺度附加限制为 5 条。
- 近义提示词尝试去重。
- 语义风险可以将危险短语替换为安全改写并追加负面保护。
- 当前轮与上一轮计算总分和场景差值,给出 adopt/keep previous/human review 建议。
专项测试位置:
```text
tests/test_advanced_style_set_workflow.py
```
新增测试包括:
- 固定维度映射与服务端加权。
- 语义风险改写和尺度胶囊。
- 公共问题与尺度问题聚合。
---
## 6. 最近一次本地测试结果
使用 Codex 内置 Python:
```text
C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe
```
完整测试命令:
```powershell
& 'C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' `
-m pytest tests -q `
--basetemp '.tmp\pytest-full-1032'
```
结果:
```text
211 passed in 158.00s
```
Windows 默认 `%TEMP%\pytest-of-Administrator` 可能遇到权限错误,因此必须把 `--basetemp` 指向工作区 `.tmp`。
前端脚本:
```text
cd frontend
npm run build
npm run typecheck
npm run test:contracts
```
当前前端构建产物已经存在:
```text
pages/imagestudio/assets/index-1rjaQ0Bx.css
pages/imagestudio/assets/index-Dmf_ucVG.js
web/assets/index-Cj5Y2axI.css
web/assets/index-D_8_bZ04.js
```
---
## 7. 最新实机画风测试记录
这是切换账号前最后一次完成的真实导入审计。
### 7.1 导入基本信息
- 名称:`鹰乃`
- import ID:
```text
advimp_08c2bfec70f946c79c3012eed683ff39
```
- 状态:`awaiting_review`
- 当前 attempt:
```text
advattempt_2982f5af0e984d9d83b1315d461ad153
```
- 当前 consensus:
```text
advconsensus_6aa557c4d53447b8a8adc0fc708fb818
```
- 共识 revision:`1`
- 源图数量:`8`
- 视觉识别/审核路由:`BD 1X/c-gemini-3.5-flash-low`
- 生图路由:`wy-gpt-image-2`
### 7.2 八张源图 ID
```text
advsrc_316d0b444c6246488b2b835d6a7c4ccf
advsrc_22b9554920ac4ca68a37ab94d0c520e7
advsrc_aa10adbb8f134148b6ada680beb51c53
advsrc_cddc0cc93f544acfadb1899185faf5b0
advsrc_591d29f0eb664e6e8f8881bd47e35a0a
advsrc_eed35e846abe453b8a18aceec6711b44
advsrc_b23ebff9d23d4545a23cd7f8e69f3e3e
advsrc_c173ad81306c48b4a765cb3d07f0e4ea
```
自动审核使用的三张代表源图:
```text
advsrc_cddc0cc93f544acfadb1899185faf5b0
advsrc_eed35e846abe453b8a18aceec6711b44
advsrc_c173ad81306c48b4a765cb3d07f0e4ea
```
### 7.3 三张验证图
头像:
```text
advcase_be6613f946144cc99250e5730229c319
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_be6613f946144cc99250e5730229c319/portrait__advcase_be6613f946144cc99250e5730229c319__task_8270b54fe0f04d0cbfb549c0be943bac_01.png
```
全身:
```text
advcase_077d7c955c094d148a389cc6dd699f74
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_077d7c955c094d148a389cc6dd699f74/fullbody__advcase_077d7c955c094d148a389cc6dd699f74__task_0acaa58ebb434786ad5e060114d5a719_01.png
```
跨场景:
```text
advcase_489905c4d5914a649ae4645945370874
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_489905c4d5914a649ae4645945370874/novel_scene__advcase_489905c4d5914a649ae4645945370874__task_7142736df675413488910fd49bd82259_01.png
```
临时只读审计副本位于:
```text
.tmp/latest_style_audit
```
迁移时该目录不是源码必需项;真实数据以 NAS `plugin_data` 为准。
### 7.4 肉眼评价
这一轮比 1.0.31 前的结果明显更好:
- 脸型、眼睛、多层虹膜、彩色线稿和腮红已经接近目标风格。
- 角色与背景的整体完成度提高。
- 仍未达到系统所显示的 100% 还原度。
- 肉眼综合约为 72%~78%。
主要残留问题:
1. 头像发顶出现明显粗白色锯齿光带,用户称为“头发光环”。
2. 跨场景背景蓝粉饱和过强,出现 HDR、镜头光晕和体积光倾向。
3. 全身角色身体过于娇小、幼态,头身比不足。
4. 自动审核三张全部给出 `1.0`,但审核文字又承认多项 mismatch,评分自相矛盾。
---
## 8. 最新问题的精确根因
### 8.1 头发光环/白色发带
共识提示词反复写入:
```text
bright horizontal band highlight across the hair crown
prominent bright horizontal band highlight across the crown
bright horizontal highlight across the crown
```
该特征同时出现在:
- 公共共识提示词;
- detailed 胶囊;
- `must_preserve`;
- `prompt_priority_groups.rendering`;
- portrait/fullbody/novel_scene 三个尺度胶囊。
负面提示词已经包含:
```text
floating halo
crown above head
literal ring floating in the air
```
所以模型没有生成悬浮在头顶上的圆环,而是生成贴在头发表面的实体粗白条。当前负面保护没有覆盖:
```text
solid white stripe
continuous luminous band
geometric zigzag bar
uniform horizontal block
```
共识的 `semantic_risk_audit` 已把 `angel ring highlight` 改成 `bright horizontal band highlight`,但安全改写本身仍含有强烈的物体化几何词 `band`。
这说明 1.0.32 缺少“安全改写的二次审计”。
正确方向不是针对某张图硬编码,而是建立通用规则:
- 如果 safe rewrite 仍包含 ring/band/bar/stripe/halo/crown 等物体或几何实体词,则必须二次改写。
- 改写必须包含:
- 附着面;
- 材质;
- 透明度;
- 曲率关系;
- 非均匀边缘;
- 不连续性。
建议表达:
```text
broken, semi-transparent satin sheen painted directly across selected hair strands,
following the curved hair volume, with irregular tapered edges and variable opacity
```
### 8.2 背景高饱和和强光效
当前算法错误地把以下内容提升为核心画风:
```text
high-key pastel-dominated color palette
soft-focus background with circular bokeh
bright diffused lighting
warm rim lighting
```
并且又在尺度胶囊中重复。
跨场景内容本身还指定:
```text
rooftop garden at dawn
atmospheric scene composition
soft-focus depth of field background with circular bokeh light particles
```
这些词叠加后,生图模型自然产生:
- 蓝粉高饱和天空;
- HDR 逆光;
- 镜头光晕;
- 体积光;
- 大量花瓣/光粒子;
- 背景过度写实和复杂。
真实源图更加准确的共性应该是:
- 全局高明度;
- 饱和度随场景变化;
- 人物局部色差清晰;
- 紫、粉、桃色阴影关系;
- 背景通常柔化,但不是固定圆形散景;
- 明亮区域和深色服装仍保留层次。
`soft-focus background with circular bokeh` 更接近可变的构图/光效,不应进入核心 `must_preserve`。
### 8.3 全身角色体型过于娇小
这不是主要由随机种子造成,实际提示词明确包含:
```text
highly stylized youthful moe aesthetic
pre-adolescent to early adolescent bishoujo style
youthful bishoujo proportions
extremely large eyes
wide face, short vertical length, rounded cheeks
```
又要求保持:
```text
head-to-body ratio
anatomy abstraction
```
组合结果是:
- 头部偏大;
- 四肢偏短;
- 肩胯偏窄;
- 约 4.5~5.5 头身;
- 身体明显幼态。
根因是视觉模型把“萌系幼态脸部画法”错误地等同为“实际年龄较小”,再把 `apparent_age` 写入可迁移画风。
源图实际是幼态萌系脸,但身体比例、胸腰胯、四肢长度更加成熟。
此问题还涉及安全风险:参考图存在内衣/性感服装时,绝不能生成 `pre-adolescent` 或 `early adolescent` 之类未成年年龄词。
正确算法应该:
- 分离 facial age stylization 和 actual subject age;
- `apparent_age` 默认不能进入画风核心胶囊;
- 移除所有未成年年龄词;
- 验证角色明确为 adult heroine/adult character;
- 全身胶囊明确 6.5~7.5 头身和成年四肢比例;
- 允许保留萌系脸型,但不得因此缩短身体。
### 8.4 自动审核评分虚高
三张验证图当前所有维度都被记录为 `1.0`。
但同一份审核结果又明确写出:
- 头像眼睛青色过饱和;
- 全身发顶高光形状不正确;
- 全身虹膜细节不足;
- 跨场景存在过度体积光、镜头光晕和大气散射。
当前服务端在维度覆盖完整时直接采用加权维度总分,模型把所有维度写成 1.0 后就得到 1.0;没有检查分数与文字、delta、prompt patch 是否矛盾。
另外:
- `style_deltas.severity` 如果视觉模型返回 `low/moderate/high` 字符串,当前 `_score()` 无法解析,结果可能变成 `null`。
- 视觉模型 `provider_fidelity_score` 可能为 0.94,但服务端维度加权会提高到 1.0。
---
## 9. 后续修复队列(建议版本 1.0.33)
以下内容尚未实现,是迁移后应优先完成的任务。
### P0-1:年龄、脸部幼态和身体比例解耦
涉及:
```text
backend/services/advanced_style_set_service.py
backend/services/material_normalization_service.py
engines/vision_provider.py
tests/test_advanced_style_set_workflow.py
```
需要实现:
1. 视觉识别协议明确输出:
- facial_age_stylization
- actual_age_evidence
- body_maturity_proportions
2. 画风胶囊禁止直接使用 `pre-adolescent`、`early adolescent`、`child` 等年龄词。
3. 对性感/内衣/成人身体内容增加硬性安全约束:不得与未成年年龄描述共同进入提示词。
4. 默认验证人物明确为成年角色。
5. fullbody 尺度指令明确:
- adult proportions
- 6.5–7.5 heads tall
- adult limb length
- youthful stylized face without childlike body proportions
6. 增加测试,确保萌系脸不会把全身缩成幼女比例。
### P0-2:评分、文字结论和修正补丁一致性校验
当前函数:
```text
_weighted_style_fidelity_score
_normalize_style_deltas
_review_validation_image
```
需要增加:
1. 如果存在 `mismatches`,总分不能为 1.0。
2. 如果存在 `prompt_patch`,对应维度不能为 1.0。
3. 如果存在 `semantic_risks`,对应维度必须封顶。
4. 服务端最终分数不得高于 provider 总分,建议:
```text
final_score <= min(weighted_dimension_score, provider_fidelity_score)
```
5. 根据 delta severity 扣分。
6. 支持 severity:
```text
low -> 0.2
minor -> 0.25
moderate -> 0.5
high -> 0.75
critical -> 1.0
```
7. 若模型返回全部维度 1.0,但文字存在修正要求,自动标记 `review_inconsistent`。
8. 不一致审核需要降权或发起一次低成本复核,而不是展示 100%。
### P0-3:核心特征证据门控
当前服务端保存 `feature_evidence`,但没有用证据约束 `must_preserve`、优先级组和尺度胶囊。
需要实现:
1. 核心特征必须有 `feature_evidence` 支持。
2. 建议阈值:
- `support_ratio >= 0.6`
- `confidence >= 0.7`
3. 除了样本数量,还要验证跨角色、跨场景和跨色盘支持,防止“所有樱花图都有粉色”被误认为画风。
4. 没有证据的 `prompt_priority_groups.core` 项目降级到 variable 或删除。
5. 背景、散景、黎明、花瓣、具体色盘默认视为可变项。
6. `consensus_style` 为空、`variable_style_features` 为空但仍输出大量核心词时,应判定结构不完整,而不是直接接受。
### P0-4:语义风险安全改写的二次审查
当前只把 `original_phrase` 替换为 `safe_rewrite`。
需要实现:
1. 对 safe rewrite 再运行一次规则检查。
2. 对以下词组建立通用物体化风险检测:
```text
ring
halo
band
bar
stripe
crown
orb
ribbon
frame
glow line
```
3. 如果描述的是渲染特征,必须说明附着关系和非实体性。
4. 自动追加针对改写后剩余风险的负面约束。
5. 测试应覆盖“悬浮光环已消失但头发变成实体白条”的情况。
### P0-5:公共胶囊与尺度胶囊真正去重
当前公共提示词与 scale capsule 仍重复:
```text
high-key pastel
bright horizontal highlight
soft-focus background
circular bokeh
large detailed irises
```
需要实现:
1. 编译尺度胶囊前,以公共胶囊为基准做近义消重。
2. 尺度胶囊只写该尺度容易丢失的内容。
3. 头像重点:脸部比例、虹膜、睫毛、鼻口、局部发丝。
4. 全身重点:身体成熟度、头身比、四肢、轮廓线、服装阴影。
5. 跨场景重点:人物线稿与背景层次的分离,不重复指定整体色盘和散景。
### P0-6:中性验证场景
当前 `novel_scene` 使用 `at dawn`,天然诱导蓝粉天空、逆光和高饱和。
建议:
- 头像:中性灰/米色漫射背景。
- 全身:普通白天或柔和室内光。
- 跨场景:阴天屋顶、普通街道或室内公共空间,避免 sunrise/sunset/dawn/neon/festival。
- 验证内容不得自带强烈风格词、镜头光效词和情绪色盘。
### P1-1:层级色彩模型
不要再用单一 `high saturation` 或 `pastel` 描述全部色彩。
建议拆成:
- global_value_range
- global_saturation_range
- local_color_separation
- shadow_hue_relationship
- highlight_temperature
- character_background_contrast
审核时不能因为局部眼睛颜色过饱和,就要求整个画面降饱和。
### P1-2:背景与人物渲染分别审核
当前 `background_rendering` 可能被模型随意给 1.0。
建议分别审核:
- 人物线稿;
- 人物上色;
- 背景线稿/细节;
- 背景色彩;
- 人物与背景的风格统一度;
- 光效是否掩盖风格。
### P1-3:前端展示评分可信度
前端当前主要显示自动还原度和摘要。
建议增加:
- 分数是否经过一致性校验;
- 维度覆盖率;
- 是否存在 mismatch;
- 是否存在语义风险;
- 当前分数是 provider、服务端加权还是降权结果;
- “100% 但仍有修正项”时显示警告,不显示绿色满分。
### P2:自动回归和候选采用策略
当前已经计算新旧轮次差值,但没有完全阻止退步版本成为当前候选。
可以增加:
- 新版平均分下降超过 0.02 时默认保留上一候选;
- 任一关键维度明显下降时禁止自动推荐采用;
- 只有公共维度提升且没有新增安全风险时才标记 adopt candidate;
- 用户仍保留最终人工确认权。
---
## 10. 推荐的 1.0.33 实现顺序
建议严格按以下顺序,避免再次只修表象:
1. 写失败测试:未成年年龄词、全身娇小、满分矛盾、safe rewrite 二次物体化、核心特征无证据、尺度重复。
2. 修改识别/共识协议,拆分脸部年龄风格和实际年龄。
3. 增加核心特征证据过滤器。
4. 修改提示词编译器,增加二次风险审查和跨层消重。
5. 修改验证默认场景,去除 dawn 等强诱导词。
6. 修改评分器,加入一致性惩罚和 provider 上限。
7. 补充前端可信度提示。
8. 跑专项测试。
9. 跑完整 211+ 测试。
10. 版本提升到 `1.0.33`。
11. 通过 SSH 部署 NAS,重启容器。
12. 只检查加载和 HTTP,不主动触发付费生成。
13. 用户重新导入同一批源图后,再读取新旧图片和数据库进行对照。
---
## 11. 关键代码导航
### 11.1 后端主流程
```text
backend/services/advanced_style_set_service.py
```
重点位置/符号:
```text
STYLE_REVIEW_SCHEMA_VERSION
STYLE_REVIEW_DIMENSIONS
STYLE_REVIEW_WEIGHTS
AdvancedStyleSetService._review_validation_image
_consensus_instruction
_style_fidelity_review_instruction
_normalize_style_dimension_scores
_weighted_style_fidelity_score
_normalize_style_deltas
_normalize_style_prompt_patch
_normalize_semantic_risks
_aggregate_style_review_feedback
_style_attempt_comparison
_detailed_style_prompt
_detailed_style_negative_prompt
_scale_specific_style_prompt
_scale_transfer_instruction
_apply_semantic_risk_rewrites
_compact_style_prompt_parts
```
### 11.2 其他相关后端
```text
backend/services/advanced_material_service.py
backend/services/advanced_material_worker_runtime.py
backend/services/material_normalization_service.py
backend/services/model_provider_runtime.py
backend/services/prompt_governance_service.py
database/repositories/advanced_material_repository.py
database/models.py
engines/vision_provider.py
engines/single_flow.py
```
### 11.3 数据库迁移
```text
database/migrations/0016_advanced_materials.sql
database/migrations/0017_advanced_wardrobe_items.sql
database/migrations/0018_advanced_style_sets.sql
```
### 11.4 前端
```text
frontend/standalone-web/src/features/materials/AdvancedMaterialImportPage.vue
frontend/standalone-web/src/features/materials/advanced-material-state.ts
frontend/shared/types/advanced-material.ts
frontend/shared/api/endpoints.ts
```
### 11.5 测试
```text
tests/test_advanced_style_set_workflow.py
tests/test_advanced_style_vision.py
tests/test_advanced_material_workflow.py
tests/test_advanced_material_repository.py
tests/test_advanced_material_boundary_services.py
tests/test_advanced_material_worker_recovery.py
tests/test_advanced_material_migrations.py
tests/test_material_catalog_resolver.py
tests/test_model_route_chain.py
```
---
## 12. 新 Codex 会话启动提示词
迁移完成后,可以直接把以下内容发给新 Codex:
```text
请先完整读取 docs/project-migration-handoff-2026-07-18.md。
这是 AstrBot ImageStudio 的当前开发交接文档。1.0.33 后端算法修复已经提交并推送到
origin/codex/ui-navigation-s130-s145,代码提交为 a828f02,并已部署到 NAS 的 astrbot-ops-pro。
main 仍停留在 v1.0.20,因此克隆后必须切换到 codex/ui-navigation-s130-s145,不能直接使用 main 开发。
先执行只读检查:
1. git checkout codex/ui-navigation-s130-s145
2. git pull --ff-only
3. git log -3 --oneline --decorate,并确认历史包含 a828f02
4. git status --short --branch,并确认工作树干净
5. 确认 backend/services/advanced_style_set_service.py 存在
6. 确认 metadata.yaml 和 core/config_service.py 均为 1.0.33
7. 阅读交接文档第 7~10 节
1.0.33 的年龄/身体解耦、审核一致性、证据门控、safe rewrite 二次审查、公共/尺度胶囊去重、
中性验证场景、提交、推送和 NAS 部署均已完成。下一步由用户手动重新导入参考图并进行真实效果验收;
不要由自动化流程触发付费生图。
```
---
## 13. 迁移后验收清单
### 文件完整性
- [ ] 已复制完整 `.git`,或已经从 Forgejo 重新克隆仓库。
- [ ] `backend/services/advanced_style_set_service.py` 存在。
- [ ] `database/migrations/0016_advanced_materials.sql` 存在。
- [ ] `database/migrations/0018_advanced_style_sets.sql` 存在。
- [ ] `frontend/standalone-web/src/features/materials/` 存在。
- [ ] 所有进阶素材测试文件存在。
- [ ] release 1.0.21~1.0.31 文件未丢失。
### Git 状态
- [ ] 当前分支仍为 `codex/ui-navigation-s130-s145`,或已明确创建新的 `codex/` 分支。
- [ ] Git 历史包含 `a828f02`。
- [ ] `git status --short` 没有意外修改或未跟踪源码。
- [ ] 没有把 `origin/main` 的 v1.0.20 当成当前代码。
### 版本
- [ ] `metadata.yaml` 为 1.0.33。
- [ ] `core/config_service.py` 为 1.0.33。
- [ ] `frontend/package.json` 为 1.0.33。
### 测试
- [ ] 使用工作区 `.tmp` 作为 pytest basetemp。
- [ ] 完整测试通过。
- [ ] 前端 typecheck、contracts 和 build 通过。
### 实机
- [ ] SSH 能连接 `agent@192.168.31.210:77`。
- [ ] 不使用浏览器安装插件。
- [ ] 备份放在 `data/plugin_backups`,不放在 `data/plugins`。
- [ ] 重启 `astrbot-ops-pro` 后日志显示正确版本。
- [ ] 不删除 `plugin_data/astrbot_plugin_imagestudio`。
- [ ] 未经授权不触发付费生图。
---
## 14. 当前任务停止点
当前本地代码、Forgejo 功能分支和 NAS 实机均停在 `1.0.33`。
已经完成:
- 画风固定维度评分框架;
- 多场景问题聚合;
- 提示词优先级与尺度胶囊;
- 初版语义风险改写;
- 提示词压缩;
- 新旧轮次比较;
- 211 项测试;
- NAS 实机部署与加载确认;
- 最新导入图片、提示词和数据库的只读审计。
- 年龄、脸部幼态与身体成熟度解耦,正向画风提示词不再携带未成年身体措辞;
- 核心特征及背景、光效、色盘的多图证据门控;
- 审核分数、偏差、修正补丁和语义风险的一致性校准;
- 发丝高光等物体化措辞的服务器侧二次改写与负向形状约束;
- 公共 detailed 胶囊与尺度胶囊跨层去重;
- 成年且中性光照的三组验证场景;
- 新增 6 组算法回归,完整测试为 217 passed。
尚未完成:
- 由用户手动重新导入参考图并进行真实付费生图验收,重点观察发丝高光、背景饱和度/光效和全身体型。
- 正式 release zip、功能分支合并到 `main` 以及 v1.0.33 tag/release。
1.0.33 已同时保存在本地 Git、Forgejo 功能分支和 NAS 实机。新账号切换到正确分支并读取本文件后,
即可从真实效果验收与正式发布阶段继续。
---
## 15. 2026-07-19:1.0.34 进阶画风验证超时修复
用户在真实进阶画风验证中遇到网页显示 `timeout`,但中转站 API 侧没有失败记录。根因不是生图请求必然失败,
而是慢速验证任务的后端 Provider 与前端插件桥没有共享同一套长任务时间预算,且任务卡把 SQLite 无时区 UTC
时间当成本地时间解析,导致页面可能提前报错或显示错误的数小时耗时。
本轮已经完成:
- 版本提升为 `1.0.34`;
- 仅进阶画风 `portrait`、`fullbody`、`novel_scene` 三路迁移验证使用独立 `900` 秒生图超时;
- `900` 秒同时写入验证 case、队列 request、队列 metadata 和实际 `ImageGenerationRequest`;
- `OpenAIImageProvider` 支持单次请求覆盖适配器默认超时,安全范围为 `10~3600` 秒;
- 普通快速生图和其他任务仍使用各自适配器超时,没有被全局提高到 900 秒;
- AstrBot 插件页面桥与前端 API 客户端共同引用 `frontend/shared/config/timeouts.ts` 中的 900 秒常量;
- 任务卡优先读取后端 request/metadata 中的 `timeout_seconds`,显示为“耗时 / 后端时限”;
- 无时区后端时间按 UTC 解析,终态任务耗时固定为 `updated_at - created_at`,不再持续增长或错误显示 8 小时;
- 已重新构建插件页与 standalone web 产物;
- 后端超时专项 `25 passed`,前端契约 `19 passed`,前端 typecheck 通过;
- 完整 pytest 共收集 219 项;首轮 9 个失败均为当前 Windows 主机上旧 Worker 测试自身的短等待阈值,
放宽测试等待和 Barrier 容差后,所有失败项均已逐项复验通过,但没有再次运行约 38 分钟的整套测试;
- 已通过 SSH 覆盖部署到 NAS 的 `astrbot-ops-pro`,AstrBot 日志成功加载 `1.0.34`;
- 实机备份目录:
`/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups/astrbot_plugin_imagestudio-1.0.33-pre-1.0.34-20260719-215744`;
- 浏览器只读验收确认页面显示 `ImageStudio · 1.0.34`、后端已连接,历史任务耗时恢复为秒级;
- 未由自动化触发真实付费生图。
当前 Git 状态:`1.0.34` 修改仍在本地分支 `codex/ui-navigation-s130-s145` 的工作树中,尚未提交或推送。
下一步应由用户手动重试画风验证;确认真实生成不再出现前端提前超时后,再提交、推送并制作正式发布包。