# 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` 的工作树中,尚未提交或推送。 下一步应由用户手动重试画风验证;确认真实生成不再出现前端提前超时后,再提交、推送并制作正式发布包。