Widget 开发

适用读者：前台 Widget 和主题兼容开发者

注入方式

ChatWidgetFilter 实现 Halo AdditionalWebFilter，拦截 HTML 响应并在第一个 </body> 前注入聊天和脑图资源。Console、登录、UC、API 和 actuator 路径不会注入。

静态资源通过 ReverseProxy 暴露在：

/plugins/ai-suite/assets/res/**

对应目录为 src/main/resources/static/。

资源

• js/chat-widget.js：聊天、搜索、SSE 和反馈。
• js/mindmap-widget.js：文章脑图、折叠和原文跳转。
• css/chat-widget.css：聊天与搜索样式。
• css/mindmap-widget.css：脑图样式。

每次插件启动生成资源版本参数，用于刷新浏览器缓存。

内置交互宠物皮肤

在 Console「浮窗外观」中选择「交互宠物」，再选择内置皮肤并保存配置。 薄荷机器人（mint-robot）、奶油橘猫（cream-cat）与星云小精灵（star-sprite）均提供待机、眨眼、开心、委屈和思考五张透明 PNG， 每张 384×384，适合默认 96px 及高像素密度屏幕。仅保留这三套内置皮肤，原有四套 SVG 已移除。 仍引用旧皮肤 ID 的配置会回退静态图标，请在后台重新选择皮肤并保存。

• 待机：轻微呼吸、间歇眨眼。
• 悬停或打开浮窗：开心表情；悬停时显示已配置的宠物语录。
• 请求回答：思考表情与状态动画；完成回答或点赞后短暂显示开心表情。
• 点踩：短暂显示委屈表情。
• 缺少皮肤或主图加载失败：回退静态图标；减少动态效果偏好沿用既有回退逻辑。

皮肤注册在 BuiltinPets，图片位于 static/pets/<name>/。 BuiltinPet.imageUrl(state) 统一生成 Console 预览与访客 manifest 的地址， 后缀由皮肤声明决定，不能在调用处写死为 .svg。 新增皮肤后运行 BuiltinPetsTest 与 ConsolePetPresetsTest，检查资源打包、 透明通道、尺寸以及预览和 manifest 的一致性。橘猫与星云小精灵各自的五帧共用同一透明轮廓， 表情仅改变面部区域，避免切换时身体抖动；测试同时检查透明面积与轮廓一致性。

AI 生成宠物流程

Console 中的 AI 宠物采用「上传参考图 → 生成母版 → 检查背景 → 生成表情」流程。第一阶段只调用一次图像模型生成待机母版，默认的「精致立体」风格强调柔和材质、参考图姿态和 96px 小尺寸辨识度。上传图片不强制使用浅色背景；界面建议选择主体与背景反差明显、边界清楚的照片，以提高模型理解和后续抠图效果。

新建页面只提供「精致立体（推荐）」和「复古像素」两种画风。旧宠物的 chibi、flat 风格记录与服务端提示词继续兼容，移除页面选项不会改变已有图片或表情重生成。

提示词采用「固定质量约束 + 风格模板 + 管理员补充要求」的半开放模式。管理员可以编辑母版补充要求并查看服务端组合后的完整提示词；系统总是在最后追加单角色、完整身体、均匀白底、无地面/底座/接触阴影和小尺寸等约束，避免自定义文本破坏抠图条件。母版不满意时可在保留当前版本的情况下修改要求并重新生成；只有新图生成和上传都成功后才原子替换记录，替换后清空旧表情。宠物记录保存用户补充要求和实际完整提示词快照。

新生成或重做的母版必须先通过背景检查。预览可以切换透明棋盘格、浅色和深色背景，便于识别白斑、黑边和半透明残影；未确认背景时，服务端拒绝生成表情，前端也不允许把该宠物应用到访客浮窗。历史记录没有背景状态字段时按已确认处理，避免升级后中断现有宠物。

背景检查页提供确定性的「清理白底/阴影」橡皮擦。管理员在残留区域拖动后，服务端只降低母版笔刷范围内的 Alpha，未涂抹区域和全部 RGB 像素保持不变；柔边笔刷避免硬锯齿，最多接收 300 个归一化笔画。界面支持撤销一笔、清空笔画和恢复最初母版。每次应用清理或恢复母版都会清除旧表情并回到待确认状态；点击「确认背景并继续」后才进入表情步骤。该操作不调用图像模型。

表情区域是相对画布的柔边椭圆，可以在预览图上拖动，并调整宽度、高度和羽化比例。表情阶段以已确认的母版为参考调用图像模型生成眨眼、开心、委屈和思考候选图，服务端只把椭圆内的候选像素合成回母版。椭圆外 RGB 与母版保持一致，所有状态强制使用母版 Alpha，因此不依赖供应商提供 mask 参数。区域参数随宠物记录保存，后续重做表情时自动复用。

表情阶段另有最多 300 字的补充要求，但服务端仍在每个状态的最终提示词中强制「只改变眼睛、眉毛和嘴巴」。模型候选图必须与母版同尺寸；四个状态按顺序生成，全部成功后才上传并更新宠物记录，任一状态失败都会让任务明确失败。管理员验收表情后再保存浮窗配置，避免生成结果未经检查直接影响访客端。

「无地面/底座/接触阴影」属于提示词预防措施，边缘连通的近白色背景会继续由服务端自动抠除；图像模型画进角色轮廓内的接触阴影无法仅靠颜色阈值安全区分，因此必须在母版阶段人工检查并按需擦除。确认后的透明轮廓会被所有表情帧继承，避免每一帧重复抠图或产生不同的脚底残影。

主题兼容原则

• 使用语义 DOM 与响应式布局，不按主题名称或 User-Agent 写分支。
• 避免覆盖主题全局变量和通用类名。
• 对 PJAX/局部导航重复检测并幂等初始化。
• 移动端保留文章阅读上下文，避免不必要的强制全屏。
• 插入 HTML 前使用 DOMPurify 或受控模板。
• 高亮摘要只允许受控 <mark>。

文章识别

过滤器优先从 data-target="Post" 和 data-id 检测文章上下文，也兼容评论区域标识。非文章页由脚本自行跳过脑图渲染。

验证矩阵

• 首页、归档、搜索、文章、登录和 Console。
• 普通导航与 PJAX 导航。
• 亮色、暗色和自动主题。
• 桌面、窄屏和触摸设备。
• 登录访客与匿名访客。
• 功能开关关闭和配置读取失败。
• HTML 有 Content-Length、chunked 和多个代码示例 </body> 的情况。

复古像素处理

新pixel母版自动统一96网格和最多24色，保存384PNG。背景确认后四表情共用母版色板、硬边区域和二值透明度。pixelGridSize=96区分新旧流程，manifest新增imageRendering=pixelated；Console预览和前台保持像素边缘，像素编辑器隐藏羽化滑杆。已有图片不会自动迁移，重做母版才启用。

表情完成与防误触

四表情成功后自动进入第4步结果预览，展示眨眼/开心/委屈/思考，主按钮为完成，仅关闭弹窗。已有四表情的宠物列表入口改为查看表情；调整表情返回区域编辑。重新生成是次要按钮，必须通过费用确认才能提交；取消和完成均不提交模型请求，pending期间拒绝重复提交。图片已保存与前台配置保存分别提示，原有外观配置保存行为不变。

模型验证范围提示

新建和表情编辑弹窗提供轻量模型使用提示，说明当前用Qwen Image 2.0 Pro/3.0 Pro及豆包Seedream 5（doubao-seedream5）验证过；其他模型需参考图能力，建议先连通性测试和母版验收。提示不等同供应商白名单，不阻止使用其他模型、不新增确认步骤；后台原始错误提示保持原样。

生图模型预检查（2026-10-02）

宠物弹窗打开时通过 GET /pets/model-status 解析本插件选择的生图模型；未选择时沿用 AI Foundation 默认生图模型。预检查不发起模型调用，也不记录用量。模型必须声明文生图及图生图能力；未配置、能力未就绪或检查失败时显示中文配置指导、配置入口与重试，并禁用实际模型生成动作。查看现有结果、背景清理/确认仍可操作。此检查不保证额度、连通性或生成质量，实际生成错误仍保留原始信息。

母版姿态（2026-10-02）

精致立体不再固定坐姿，所有母版风格共用姿态规则：管理员明确姿态优先，其次保留参考图可辨识姿态/朝向/四肢关系；头像或姿态不明确时补全符合主体结构的自然姿态。新建、重做及完整提示词预览使用同一构造函数。表情阶段仍锁定母版身体姿态；已有宠物不会自动修改，改变姿态需重做母版、重新检查背景并生成表情。

表情与轻动作候选（2026-10-02）

生成方式默认“仅变表情”，保留原四帧局部合成。精致立体新增“表情＋轻动作”：开心小幅挥手、委屈收拢双手、思考托腮；眨眼仍局部合成并锁定身体。像素风暂不开放轻动作。轻动作使用2048方形参考画布，候选统一回母版尺寸，但不套用母版Alpha裁剪新手势；身体位置由提示词约束，角色一致性和脚底位置需人工验收。

POST /pets/{id}/expressions/generate 支持mode(face/motion)和可选state；省略state按固定顺序生成四张，指定state只调用一次。候选写入expressionCandidates，不改变公开images；批次中途失败保留已完成候选。每张候选可通过approve/cleanup/reset接口审核，携带candidateUrl版本令牌。确认只替换对应状态；清理仅修改该候选Alpha，可恢复本次原始候选。母版地址和清理修订号变化时拒绝旧候选；母版重做/清理会清除候选。相同宠物禁止同时生成表情。

界面提供逐张预览、背景检查和单张重试，生成前显示费用确认。逐张确认之后才生效，清理和确认不调用模型。已有四帧结果页主按钮仍为“完成”；切入“调整表情”保留当前模式与编辑要求。豆包响应选择URL以避开Foundation大Base64缓冲限制，其他供应商保持BASE64；每次请求n=1、maxRetries=0，避免隐式重复付费。替换下来的附件由带归属标记的保守回收流程处理，见下文发布收尾约定；历史无标记附件仍保留。

生图任务阶段进度（2026-10-02）

任务轮询保留原status/error/petId，新增progress：stage、currentState、completed、total、completedStates、elapsedSeconds。阶段为preparing/model/processing/saving/frame-complete/done，不代表供应商内部百分比。服务通过请求专属Reactor上下文观察事件，异步任务保留认证上下文并注入观察器，不增加调用或重试。终态冻结耗时和计数，失败保留原始错误。

母版及单帧total=1，四表情total=4；仅表情整组计数表示已经生成并本地合成的帧，全部成功才原子保存；轻动作/单帧候选计数表示已持久化候选，轮询增量刷新候选预览。模型等待显示动画、已用时和勿重复提交提示，超过90秒追加等待说明；下载/抠图统一为图片处理阶段，保存阶段单独显示。前端每秒更新耗时，终态/卸载停止计时；旧服务没有progress时仍显示等待并保持旧轮询兼容。

宠物聊天头像（2026-10-02）

宠物模式的顶部和assistant回复头像固定使用idle母版的同一头部裁切，不跟随四种表情变化；右下角触发宠物仍保留完整身体和既有状态机。静态模式、缺宠物图片或头像加载失败时沿用静态图标/文字标签。错误监听忽略旧图片的迟到失败，避免切换宠物后覆盖新头像。

chat组新增widgetPetAvatarCrops JSON字符串，按pet:id和preset:name分别保存centerX/centerY/size归一坐标；公开petManifest增加avatarCrop。默认自AI宠物expressionRegion推算，内置三套使用各自默认位置；不产生新附件或模型调用。坐标和裁切尺寸在服务端、Console与访客端均限制有效范围，裁切保持在方形母版内。后台顶部/回复预览与iframe实时同步，水平/垂直/缩放可调，恢复默认只清除当前宠物覆盖；保存外观配置后生效，不改变其他聊天配置或原图片。

发布收尾约定（2026-10-02）

宠物记录区分正在编辑的 images 和 publishedVersion。新建 pending 母版不公开；已有宠物重做、清理、恢复期间，前台及后台实时预览继续使用最后确认的快照。母版确认和单帧确认发布新的对应结果；旧记录没有快照且背景已确认时兼容原 images。删除或找不到宠物时保留完整配置响应并回退静态入口。

背景 approve/reset 请求必须提交 JSON {masterUrl, masterRevision}；cleanup 在此基础上增加 strokes。所见母版与服务端地址/修订号不符时拒绝并要求刷新。所有宠物修改及删除共享按宠物互斥；写入采用最新记录的原子修改，失败或取消释放锁。候选继续使用 candidateUrl 及所依赖的母版版本校验。

内存任务最多 16 个运行中、128 条历史，终态保留 30 分钟；服务停止取消执行，任务整体最长 25 分钟，图片下载/上传各 60 秒。任务丢失返回 JOB_GONE，前端停止等待并重新读取结果，不自动重试模型；连续 5 次查询失败或等待超过 30 分钟也停止轮询。任务不持久化，刷新后需从宠物列表检查已保存结果。

新上传图片在附件创建前标记 generated-pet 归属和创建时间。每 10 分钟扫描超过 1 小时保护期的无引用附件，逐条重新读取宠物引用后交由 Halo 删除；公开快照、草稿、恢复图片及全部候选均受保护。配置损坏时停止回收，失败保留待重试。历史无标记附件不自动删除。

pnpm --dir ui build 必须先通过正式类型检查与版本化宠物流程/头像回归，再构建资源。Vite 使用官方配置入口，构建不注入整个 process.env；verify-build-env.mjs 用无敏感性的标记检查产物隔离。Java 测试支持 -PfoundationTestVersion=1.1.0 检查正式 API 运行时兼容；CI 对旧 beta.4 与 1.1.0 执行完整构建。结构化文本输出使用两版共有的 OutputSpec API。

按颜色快速选择背景（2026-10-03）

母版及单帧候选背景页新增“按颜色选择”。点击取原始 RGBA 颜色，只选相连的相近像素；从残留内部拖动框选限制区域，0–60% 容差调整，多个选区累加（最多 20 次）。透明像素、棋盘格和预览背景不参与取色。红色覆盖显示实际清除的像素，支持撤销、清空及恢复原图；尚未应用选区时阻止确认。橡皮擦用于边缘修补，两者可合并应用。

前端游程编码选区，服务端核对原图尺寸及范围，只清除选中 Alpha，原 RGB 与其他像素保持；颜色清理不再次采样像素风母版。相连且同色的角色与阴影仍可能一起选中，需要预览后降低容差或限制框选范围。跨域图片不能读取像素时提示使用橡皮擦，本地图片支持取色。选区仅在编辑会话内保存，应用并确认前不改变已发布版本；旧橡皮擦请求及恢复逻辑保持兼容。

算法回归由 ui/scripts/test-pet-color-selection.mjs 执行，已加入 test:unit。当前开发基线升级至 Halo 2.26.1 / Foundation 1.1.1，构建及 CI 版本以升级记录为准。

生成宠物改名（2026-10-03）

“我的宠物”卡片增加“改名”入口。弹窗回填当前名称，支持最多20个Unicode字符，空白/超长/未变化时禁用保存；保存中阻止重复提交，失败保留输入并显示错误，成功即刷新卡片及预览，无需再次保存浮窗配置。改名不触发卡片选用操作，不更改图片或调用模型，也不改变独立的“AI 助手”聊天标题。

服务端通过按宠物互斥和PetStore原子修改，单独更新name和已存在publishedVersion.name，禁止通过publish发布未审核图片。只有草稿时不建立公开版本。生成处理中提示等待后重试；旧ID、审核和候选记录保持。

生成宠物卡片操作（2026-10-03）

生成宠物卡片将选择区与操作区分开，主按钮按状态显示查看表情、生成表情或检查背景，文字保持单行。改名和删除位于更多菜单，删除继续使用既有确认提示。生成卡片宽136px，名称单行省略并可通过选择按钮title查看完整名称，上传入口与生成卡片保持相同宽度。

单张表情操作按钮（2026-10-03）

逐张结果下方采用独立按钮：检查背景为浅紫底，重新生成为白底描边，统一高度、12px间隔、窄列自动换行。重新生成继续复用单张确认流程，取消不调用模型；背景检查与生成禁用条件保持原行为。

橡皮擦圆形范围预览（2026-10-03）

橡皮擦模式显示随指针移动的圆形范围，直径随笔刷大小变化，以图像短边为基准，与后端擦除半径一致。黑白双边框适配深浅背景，离开图片或切换工具/图片时隐藏；触屏保留系统输入，笔画仍显示范围。圈内边缘仍按既有柔边规则擦除。

背景编辑视口与边缘优化（2026-10-03）

背景编辑支持滚轮/触摸板在指针位置缩放（50–600%）、按钮缩放与适应窗口、空格拖动/移动画面模式；所有选择及笔刷仍通过变换后图片矩形映射回原图坐标，原图分辨率不变。缩放不影响网页其他区域。

每张当前表情也保留检查背景入口：以带当前URL校验的editingExisting副本进入候选审核，清理和优化仅修改副本，保存并使用才发布该状态；取消编辑/关闭时移除副本，当前状态保持。模型生成的未确认候选继续保留，以便之后检查。并发生成/清理共享互斥与母版版本校验。

边缘优化提供0–2原图像素收边与0–100%去白边，参数变更后需重新预览；预览只返回PNG数据，不上传或修改记录。去白边仅调整半透明像素RGB，不改不透明主体，收边仅降低Alpha；精细毛发或半透明浅色材质仍需深浅背景人工验收，不保证一键完美。显式应用上传到副本或待审核母版，可恢复本次原图；预览期间禁止确认，取消预览不修改图像。网络失败保留旧图。