37 KiB
AstrBot ImageStudio 项目迁移与 Codex 交接文档
更新时间:2026-07-18(Asia/Shanghai) 当前工作区:
C:\Users\Administrator\Documents\AstrBot ImageStudio当前开发版本:1.0.321.0.32 代码快照提交:937ee73目标读者:迁移后的新 Codex 账号、新工作区维护者、后续开发者 文档目的:只读取本文件即可恢复当前开发背景、代码状态、实机环境、最新问题和下一步修复任务。
0. 必须首先阅读的迁移警告
Forgejo 的 main 分支和正式标签仍停在 v1.0.20,但完整的 1.0.21~1.0.32 开发成果已经提交并推送到:
origin/codex/ui-navigation-s130-s145
1.0.32 代码快照提交为:
937ee73 release: complete ImageStudio 1.0.32 advanced material workflows
该提交已经包含:
- 进阶素材主服务;
- 多图片画风工作流;
- 新数据库迁移;
- 新仓储层;
- 新前端页面;
- 新测试;
- 1.0.21~1.0.31 发布包;
- 1.0.32 最新算法修改。
因此迁移时可以直接从 Forgejo 恢复,但必须切换到正确分支:
- 可以重新
git cloneForgejo 仓库。 - 克隆后必须执行
git checkout codex/ui-navigation-s130-s145。 - 必须确认 HEAD 至少包含提交
937ee73。 - 不要直接停留在
main,否则只会得到 v1.0.20。 .tmp中的视觉审计副本没有推送,但它不是源码真相;真实测试图片和数据库仍在 NASplugin_data。
推荐恢复命令:
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 远端:
ssh://git@forgejo-nas:18086/YokiiroBW/astrbot_plugin_imagestudio.git
1.2 最近提交
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.jsonconfig.yamlmain.pymetadata.yamlcore/config_service.pycore/astrbot_provider_bridge.pydatabase/models.pyengines/vision_provider.pyengines/single_flow.py- 多个
backend/routes/、backend/services/文件 - 多个前端设置、工作流、素材页面
pages/imagestudio/和web/的构建产物- AstrBot provider bridge 相关测试
1.5 已纳入版本控制的关键新增文件
这些文件已经包含在 937ee73 中,切换到正确分支后应当存在:
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:
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 插件目录:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugins/astrbot_plugin_imagestudio
- 插件数据目录:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio
- SQLite 数据库:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio/db/imagestudio.db
- 进阶素材文件根:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_data/astrbot_plugin_imagestudio/advanced_materials
3.2 SSH
- SSH 用户:
agent - SSH 端口:
77 - SSH 私钥路径:
C:\Users\Administrator\.ssh\codex_yokiiro_nas_ed25519
- 当前使用的 SSH 客户端:
C:\Program Files\Git\usr\bin\ssh.exe
基本连接命令:
& '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实机验证; - 没有明确授权时,不触发真实付费生图。
部署时要注意:
- 备份目录不能放在
data/plugins/内,即使目录以.开头,AstrBot 仍会把它当插件扫描。 - 备份应放在:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups
- 当前 1.0.31 备份位置:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups/astrbot_plugin_imagestudio-1.0.31-pre-1.0.32
- 插件源码目录可以整体替换,但绝对不要删除
plugin_data/astrbot_plugin_imagestudio,数据库、用户设置、进阶素材和生成图片都在那里。
3.4 当前实机状态
- 实际插件目录版本:
1.0.33 - 日志确认:
Plugin astrbot_plugin_imagestudio (1.0.33) by YokiiroBW
- AstrBot 主页面返回 HTTP 200。
- 插件 Web 路径直接无认证访问会返回
Missing API key,这是正常鉴权行为。 - 插件数据库文件仍存在,启动日志未出现导入失败、
no such table或 Traceback。 - 1.0.32 部署前备份:
/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 固定探测:
PORTS = [6185, 6195, 6199]
实际监听端口为:
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主线做增量优化。 - 没有新建平行工作流。
- 工作流允许进入查看,但仅第一个节点可用。
- 完成人设导入后依次解锁后续节点。
- 相关文件:
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 三档胶囊。
- 使用头像、全身、跨场景三张纯文字验证图。
- 验证生图不携带源图,专门测试文字胶囊的迁移能力。
- 三张验证图独立并发、独立队列、独立重试。
- 历史轮次保留完整三张图。
- 图片支持点击放大。
- 删除队列记录后父导入会自动对账为可重试失败。
详细设计文档:
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 已完成内容
核心实现:
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_groupsscale_capsulessemantic_risk_audit
- detailed 胶囊按核心、结构、渲染优先级编译。
- 公共胶囊限制为 14 条,尺度附加限制为 5 条。
- 近义提示词尝试去重。
- 语义风险可以将危险短语替换为安全改写并追加负面保护。
- 当前轮与上一轮计算总分和场景差值,给出 adopt/keep previous/human review 建议。
专项测试位置:
tests/test_advanced_style_set_workflow.py
新增测试包括:
- 固定维度映射与服务端加权。
- 语义风险改写和尺度胶囊。
- 公共问题与尺度问题聚合。
6. 最近一次本地测试结果
使用 Codex 内置 Python:
C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe
完整测试命令:
& 'C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' `
-m pytest tests -q `
--basetemp '.tmp\pytest-full-1032'
结果:
211 passed in 158.00s
Windows 默认 %TEMP%\pytest-of-Administrator 可能遇到权限错误,因此必须把 --basetemp 指向工作区 .tmp。
前端脚本:
cd frontend
npm run build
npm run typecheck
npm run test:contracts
当前前端构建产物已经存在:
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:
advimp_08c2bfec70f946c79c3012eed683ff39
- 状态:
awaiting_review - 当前 attempt:
advattempt_2982f5af0e984d9d83b1315d461ad153
- 当前 consensus:
advconsensus_6aa557c4d53447b8a8adc0fc708fb818
- 共识 revision:
1 - 源图数量:
8 - 视觉识别/审核路由:
BD 1X/c-gemini-3.5-flash-low - 生图路由:
wy-gpt-image-2
7.2 八张源图 ID
advsrc_316d0b444c6246488b2b835d6a7c4ccf
advsrc_22b9554920ac4ca68a37ab94d0c520e7
advsrc_aa10adbb8f134148b6ada680beb51c53
advsrc_cddc0cc93f544acfadb1899185faf5b0
advsrc_591d29f0eb664e6e8f8881bd47e35a0a
advsrc_eed35e846abe453b8a18aceec6711b44
advsrc_b23ebff9d23d4545a23cd7f8e69f3e3e
advsrc_c173ad81306c48b4a765cb3d07f0e4ea
自动审核使用的三张代表源图:
advsrc_cddc0cc93f544acfadb1899185faf5b0
advsrc_eed35e846abe453b8a18aceec6711b44
advsrc_c173ad81306c48b4a765cb3d07f0e4ea
7.3 三张验证图
头像:
advcase_be6613f946144cc99250e5730229c319
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_be6613f946144cc99250e5730229c319/portrait__advcase_be6613f946144cc99250e5730229c319__task_8270b54fe0f04d0cbfb549c0be943bac_01.png
全身:
advcase_077d7c955c094d148a389cc6dd699f74
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_077d7c955c094d148a389cc6dd699f74/fullbody__advcase_077d7c955c094d148a389cc6dd699f74__task_0acaa58ebb434786ad5e060114d5a719_01.png
跨场景:
advcase_489905c4d5914a649ae4645945370874
storage://advanced_materials/style-validations/advimp_08c2bfec70f946c79c3012eed683ff39/advattempt_2982f5af0e984d9d83b1315d461ad153/advcase_489905c4d5914a649ae4645945370874/novel_scene__advcase_489905c4d5914a649ae4645945370874__task_7142736df675413488910fd49bd82259_01.png
临时只读审计副本位于:
.tmp/latest_style_audit
迁移时该目录不是源码必需项;真实数据以 NAS plugin_data 为准。
7.4 肉眼评价
这一轮比 1.0.31 前的结果明显更好:
- 脸型、眼睛、多层虹膜、彩色线稿和腮红已经接近目标风格。
- 角色与背景的整体完成度提高。
- 仍未达到系统所显示的 100% 还原度。
- 肉眼综合约为 72%~78%。
主要残留问题:
- 头像发顶出现明显粗白色锯齿光带,用户称为“头发光环”。
- 跨场景背景蓝粉饱和过强,出现 HDR、镜头光晕和体积光倾向。
- 全身角色身体过于娇小、幼态,头身比不足。
- 自动审核三张全部给出
1.0,但审核文字又承认多项 mismatch,评分自相矛盾。
8. 最新问题的精确根因
8.1 头发光环/白色发带
共识提示词反复写入:
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 三个尺度胶囊。
负面提示词已经包含:
floating halo
crown above head
literal ring floating in the air
所以模型没有生成悬浮在头顶上的圆环,而是生成贴在头发表面的实体粗白条。当前负面保护没有覆盖:
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 等物体或几何实体词,则必须二次改写。
- 改写必须包含:
- 附着面;
- 材质;
- 透明度;
- 曲率关系;
- 非均匀边缘;
- 不连续性。
建议表达:
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 背景高饱和和强光效
当前算法错误地把以下内容提升为核心画风:
high-key pastel-dominated color palette
soft-focus background with circular bokeh
bright diffused lighting
warm rim lighting
并且又在尺度胶囊中重复。
跨场景内容本身还指定:
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 全身角色体型过于娇小
这不是主要由随机种子造成,实际提示词明确包含:
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
又要求保持:
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:年龄、脸部幼态和身体比例解耦
涉及:
backend/services/advanced_style_set_service.py
backend/services/material_normalization_service.py
engines/vision_provider.py
tests/test_advanced_style_set_workflow.py
需要实现:
- 视觉识别协议明确输出:
- facial_age_stylization
- actual_age_evidence
- body_maturity_proportions
- 画风胶囊禁止直接使用
pre-adolescent、early adolescent、child等年龄词。 - 对性感/内衣/成人身体内容增加硬性安全约束:不得与未成年年龄描述共同进入提示词。
- 默认验证人物明确为成年角色。
- fullbody 尺度指令明确:
- adult proportions
- 6.5–7.5 heads tall
- adult limb length
- youthful stylized face without childlike body proportions
- 增加测试,确保萌系脸不会把全身缩成幼女比例。
P0-2:评分、文字结论和修正补丁一致性校验
当前函数:
_weighted_style_fidelity_score
_normalize_style_deltas
_review_validation_image
需要增加:
- 如果存在
mismatches,总分不能为 1.0。 - 如果存在
prompt_patch,对应维度不能为 1.0。 - 如果存在
semantic_risks,对应维度必须封顶。 - 服务端最终分数不得高于 provider 总分,建议:
final_score <= min(weighted_dimension_score, provider_fidelity_score)
- 根据 delta severity 扣分。
- 支持 severity:
low -> 0.2
minor -> 0.25
moderate -> 0.5
high -> 0.75
critical -> 1.0
- 若模型返回全部维度 1.0,但文字存在修正要求,自动标记
review_inconsistent。 - 不一致审核需要降权或发起一次低成本复核,而不是展示 100%。
P0-3:核心特征证据门控
当前服务端保存 feature_evidence,但没有用证据约束 must_preserve、优先级组和尺度胶囊。
需要实现:
- 核心特征必须有
feature_evidence支持。 - 建议阈值:
support_ratio >= 0.6confidence >= 0.7
- 除了样本数量,还要验证跨角色、跨场景和跨色盘支持,防止“所有樱花图都有粉色”被误认为画风。
- 没有证据的
prompt_priority_groups.core项目降级到 variable 或删除。 - 背景、散景、黎明、花瓣、具体色盘默认视为可变项。
consensus_style为空、variable_style_features为空但仍输出大量核心词时,应判定结构不完整,而不是直接接受。
P0-4:语义风险安全改写的二次审查
当前只把 original_phrase 替换为 safe_rewrite。
需要实现:
- 对 safe rewrite 再运行一次规则检查。
- 对以下词组建立通用物体化风险检测:
ring
halo
band
bar
stripe
crown
orb
ribbon
frame
glow line
- 如果描述的是渲染特征,必须说明附着关系和非实体性。
- 自动追加针对改写后剩余风险的负面约束。
- 测试应覆盖“悬浮光环已消失但头发变成实体白条”的情况。
P0-5:公共胶囊与尺度胶囊真正去重
当前公共提示词与 scale capsule 仍重复:
high-key pastel
bright horizontal highlight
soft-focus background
circular bokeh
large detailed irises
需要实现:
- 编译尺度胶囊前,以公共胶囊为基准做近义消重。
- 尺度胶囊只写该尺度容易丢失的内容。
- 头像重点:脸部比例、虹膜、睫毛、鼻口、局部发丝。
- 全身重点:身体成熟度、头身比、四肢、轮廓线、服装阴影。
- 跨场景重点:人物线稿与背景层次的分离,不重复指定整体色盘和散景。
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 实现顺序
建议严格按以下顺序,避免再次只修表象:
- 写失败测试:未成年年龄词、全身娇小、满分矛盾、safe rewrite 二次物体化、核心特征无证据、尺度重复。
- 修改识别/共识协议,拆分脸部年龄风格和实际年龄。
- 增加核心特征证据过滤器。
- 修改提示词编译器,增加二次风险审查和跨层消重。
- 修改验证默认场景,去除 dawn 等强诱导词。
- 修改评分器,加入一致性惩罚和 provider 上限。
- 补充前端可信度提示。
- 跑专项测试。
- 跑完整 211+ 测试。
- 版本提升到
1.0.33。 - 通过 SSH 部署 NAS,重启容器。
- 只检查加载和 HTTP,不主动触发付费生成。
- 用户重新导入同一批源图后,再读取新旧图片和数据库进行对照。
11. 关键代码导航
11.1 后端主流程
backend/services/advanced_style_set_service.py
重点位置/符号:
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 其他相关后端
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 数据库迁移
database/migrations/0016_advanced_materials.sql
database/migrations/0017_advanced_wardrobe_items.sql
database/migrations/0018_advanced_style_sets.sql
11.4 前端
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 测试
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:
请先完整读取 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 的工作树中,尚未提交或推送。
下一步应由用户手动重试画风验证;确认真实生成不再出现前端提前超时后,再提交、推送并制作正式发布包。