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

34 KiB

AstrBot ImageStudio 项目迁移与 Codex 交接文档

更新时间:2026-07-18(Asia/Shanghai) 当前工作区:C:\Users\Administrator\Documents\AstrBot ImageStudio 当前开发版本:1.0.32 目标读者:迁移后的新 Codex 账号、新工作区维护者、后续开发者 文档目的:只读取本文件即可恢复当前开发背景、代码状态、实机环境、最新问题和下一步修复任务。


0. 必须首先阅读的迁移警告

当前 Forgejo 远端、远端分支和 Git 提交历史只到 v1.0.20。

本地工作区中从 1.0.21 到 1.0.32 的大量核心代码尚未提交,其中很多文件仍是 ?? 未跟踪状态,包括:

  • 进阶素材主服务;
  • 多图片画风工作流;
  • 新数据库迁移;
  • 新仓储层;
  • 新前端页面;
  • 新测试;
  • 1.0.21~1.0.31 发布包;
  • 1.0.32 最新算法修改。

因此迁移时:

  1. 不能只在新地址重新 git clone Forgejo 仓库。
  2. 不能执行 git reset --hard、git clean -fdx 或删除所有未跟踪文件。
  3. 必须复制当前项目完整目录,包括 .git、未跟踪文件和当前工作树。
  4. 迁移完成后先执行 git status --short --branch,确认下面列出的修改与未跟踪文件仍存在。
  5. 在完成备份、审查和提交前,不要把远端 v1.0.20 当作当前源码真相。

最安全的迁移方式是复制整个目录:

C:\Users\Administrator\Documents\AstrBot ImageStudio

包括隐藏的 .git 目录。复制完成后再切换 Codex 账号或更改项目地址。


1. 当前 Git 状态

1.1 分支和远端

  • 当前分支:codex/ui-navigation-s130-s145
  • 跟踪分支:origin/codex/ui-navigation-s130-s145
  • 当前 HEAD:176ee24
  • 当前 HEAD 标签:v1.0.20
  • origin/main 也位于 176ee24
  • Forgejo 远端:
ssh://git@forgejo-nas:18086/YokiiroBW/astrbot_plugin_imagestudio.git

1.2 最近提交

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。
  • Git 历史仍停留在 1.0.20。
  • 1.0.21~1.0.32 尚未 commit/push。
  • 本轮没有执行 Git 暂存、提交、推送或发布。
  • 后续必须先审查并保存当前脏工作树,再决定如何整理提交历史。

1.4 当前主要修改文件

已有文件的修改包括但不限于:

  • 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 当前关键未跟踪文件

这些文件绝对不能在迁移时丢失:

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 也仍是未跟踪文件。

目前没有正式生成 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 的开发记录,但这些记录仍未提交到 Git。


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 实机验证;
  • 没有明确授权时,不触发真实付费生图。

部署时要注意:

  1. 备份目录不能放在 data/plugins/ 内,即使目录以 . 开头,AstrBot 仍会把它当插件扫描。
  2. 备份应放在:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups
  1. 当前 1.0.31 备份位置:
/volume2/Dockers/qqbot/astrbot-ops-pro/data/plugin_backups/astrbot_plugin_imagestudio-1.0.31-pre-1.0.32
  1. 插件源码目录可以整体替换,但绝对不要删除 plugin_data/astrbot_plugin_imagestudio,数据库、用户设置、进阶素材和生成图片都在那里。

3.4 当前实机状态

  • 实际插件目录版本:1.0.32
  • 日志确认:
Plugin astrbot_plugin_imagestudio (1.0.32) by YokiiroBW
  • AstrBot 主页面返回 HTTP 200。
  • 插件 Web 路径直接无认证访问会返回 Missing API key,这是正常鉴权行为。
  • 本轮部署没有触发真实生图。

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_groups
    • scale_capsules
    • semantic_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%。

主要残留问题:

  1. 头像发顶出现明显粗白色锯齿光带,用户称为“头发光环”。
  2. 跨场景背景蓝粉饱和过强,出现 HDR、镜头光晕和体积光倾向。
  3. 全身角色身体过于娇小、幼态,头身比不足。
  4. 自动审核三张全部给出 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

需要实现:

  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:评分、文字结论和修正补丁一致性校验

当前函数:

_weighted_style_fidelity_score
_normalize_style_deltas
_review_validation_image

需要增加:

  1. 如果存在 mismatches,总分不能为 1.0。
  2. 如果存在 prompt_patch,对应维度不能为 1.0。
  3. 如果存在 semantic_risks,对应维度必须封顶。
  4. 服务端最终分数不得高于 provider 总分,建议:
final_score <= min(weighted_dimension_score, provider_fidelity_score)
  1. 根据 delta severity 扣分。
  2. 支持 severity:
low -> 0.2
minor -> 0.25
moderate -> 0.5
high -> 0.75
critical -> 1.0
  1. 若模型返回全部维度 1.0,但文字存在修正要求,自动标记 review_inconsistent。
  2. 不一致审核需要降权或发起一次低成本复核,而不是展示 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. 对以下词组建立通用物体化风险检测:
ring
halo
band
bar
stripe
crown
orb
ribbon
frame
glow line
  1. 如果描述的是渲染特征,必须说明附着关系和非实体性。
  2. 自动追加针对改写后剩余风险的负面约束。
  3. 测试应覆盖“悬浮光环已消失但头发变成实体白条”的情况。

P0-5:公共胶囊与尺度胶囊真正去重

当前公共提示词与 scale capsule 仍重复:

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 后端主流程

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 的当前开发交接文档。当前工作树从远端 v1.0.20
继续开发到了本地 1.0.32,但 1.0.21~1.0.32 仍有大量未提交和未跟踪文件。
禁止 git reset --hard、git clean 或用远端重新覆盖本地。

先执行只读检查:
1. git status --short --branch
2. 确认 backend/services/advanced_style_set_service.py 存在
3. 确认 metadata.yaml 和 core/config_service.py 均为 1.0.32
4. 阅读交接文档第 7~10 节

下一项开发目标是完成文档中的 1.0.33 修复队列:
- 年龄与身体比例解耦
- 审核分数一致性
- 核心特征证据门控
- safe rewrite 二次语义审查
- 公共与尺度胶囊去重
- 中性验证场景

要求先写测试,再增量修改现有工作流;不要创建平行工作流,不破坏现有前端结构,
不要触发真实付费生图。完成全部本地测试后,再通过 SSH 部署到 astrbot-ops-pro。

13. 迁移后验收清单

文件完整性

  • .git 已复制。
  • 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 status 中。
  • 没有执行 destructive reset/clean。

版本

  • metadata.yaml 为 1.0.32。
  • core/config_service.py 为 1.0.32。
  • frontend/package.json 为 1.0.32。

测试

  • 使用工作区 .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. 当前任务停止点

当前代码和实机均停在 1.0.32。

已经完成:

  • 画风固定维度评分框架;
  • 多场景问题聚合;
  • 提示词优先级与尺度胶囊;
  • 初版语义风险改写;
  • 提示词压缩;
  • 新旧轮次比较;
  • 211 项测试;
  • NAS 实机部署与加载确认;
  • 最新导入图片、提示词和数据库的只读审计。

尚未完成:

  • 1.0.33 修复队列中的年龄/身体、安全、证据门控、评分一致性、二次语义审查、跨层消重和中性验证场景。
  • 1.0.32 正式 release zip。
  • 1.0.21~1.0.32 的 Git 整理、commit、push 和 Forgejo 发布。

不要把“插件已部署到实机”等同于“代码已保存到 Forgejo”。当前最重要的迁移动作仍然是完整保存本地工作树。