Civitai Comics 模块反馈修复清单深度解析：@mention 解析、References 作用域与 Buzz 计费-创锋一号

Civitai Comics 模块反馈修复清单深度解析：@mention 解析、References 作用域与 Buzz 计费

【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai

本文基于仓库内的 docs/comic-feedback-tasks.md 展开。该文档是对 Civitai 漫画（Comics）功能一轮 QA 反馈的 17 项任务拆解，涵盖 @mention 字符边界解析、项目 References 作用域隔离、Buzz 计费币种、PDF 导出可靠性、管理员权限等核心问题。读完后，你可以掌握这份修复清单的完整脉络：每一项缺陷的根因、对应源码位置、建议的修复模式，以及如何用当前仓库源码验证这些修复是否已落地。

文档概览：17 项任务的主题分布与优先级

comic-feedback-tasks.md 是一份外部 QA 任务工单的结构化拆解，每项任务都标注了涉及文件、问题描述（含大致行号）与 Fix 建议。按主题归并后，17 项任务可分为五类：

@mention 解析（#1、#2）：撇号导致角色名匹配截断，进而使 AI 增强提示词丢失 @ 标记；
References 作用域（#3、#8、#6、#7）：文档明确指出 #3 与 #8 同根同源，均由getProject的“无 junction 行时回退到用户全部 references”逻辑导致；#6 是 Smart Create 拉取了用户级而非项目级的 references；#7 是移除 reference 后前端未正确失效缓存；
Buzz 计费（#5、#15）：所有生成调用硬编码currencies: ['yellow']，在 Civitai Green 域上扣费币种错误；#15 是 Green 域的端到端验证；
前端交互与可靠性（#10、#9、#12、#14、#17、#13、#11、#4）：PDF 导出静默丢面板、面板数输入只接受最后一位、布局选择高亮不突出、迭代编辑无加载反馈、横版漫画黑边、预览页空白、管理员下载/评级权限、宽高比不持久化；
独立规划项（#16）：在漫画系统内直接生成封面图。

文档给出的建议优先级如下（原文继承）：

高优先级（核心功能损坏）

3 + 8：References 作用域（一处修复同时解决两个问题）
1 + 2：撇号/mention 检测（一处修复同时解决两个问题）
7：从项目移除 reference
6：Smart Create 的 references 作用域
5：Buzz 币种（改用getAllowedAccountTypes）
10：PDF 导出缺面板

中优先级（管理员工具、UX）

11：管理员下载 + 评级权限
9：Smart Create 面板数输入 UX
13：预览/阅读页空白
14：迭代编辑加载状态
12：布局选择器选中态样式
4：宽高比持久化
17：横版布局留白

大工作量（需单独规划）

16：封面/主视觉生成弹窗
15：Civitai Green 端到端测试（手工）

@mention 解析：撇号与连字符必须属于名字的一部分（任务 #1、#2）

缺陷根因

反馈报告指出，mention-resolver.ts 第 22 行附近的 mention 正则把撇号当作边界字符，导致@O'Brien只匹配到@O；prompt-enhance.ts 第 126 行附近的/@([\w\p{L}]+)/gu字符类同样不含撇号。

当前源码的修复模式

当前仓库中的mention-resolver.ts已完整体现了文档建议的修复。核心逻辑见 mention-resolver.ts#L16-L32：

// 按名字长度降序排序，让长名先匹配（如 @MayaWarrior 先于 @Maya） const sorted = [...references].sort((a, b) => b.name.length - a.name.length); for (const ref of sorted) { const escaped = ref.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // 用 lookahead 做 mention 末尾边界而非 \b（\b 对非 ASCII 失效）。 // 边界字符集绝不能包含名字内部可出现的字符 // （撇号、连字符），这样 O'Brien 和 May-Lee 才能完整匹配。 const pattern = new RegExp(`@${escaped}(?=$|[\\s.,!?;:\\)\\]])`, 'gi'); ... }

三个设计要点值得注意：

lookahead 替代\b：\b以“词字符”判定边界，对重音字母等非 ASCII 字符会失效；改用(?=$|[\s.,!?;:\)\]])这种显式边界集，且边界集刻意排除了撇号和连字符——这正是任务 #1 的修复本质：让'与-成为名字的一部分而非终止符。
长度降序匹配：防止@Maya先吃掉@MayaWarrior的前缀。
匹配后剥离@前缀：resolveReferenceMentions会把@Name替换为纯Name，并返回mentionedIds供下游判断挂了哪些 reference 图。

增强管道的完整链路（任务 #2）

任务 #2 关注的是：LLM 输出会经过一次“剥离未识别 @mention”的清洗，若撇号名字匹配失败就会被剥掉，甚至留下碎片。当前 prompt-enhance.ts 的完整管道为：

入站解析：enhanceComicPrompt先调用resolveReferenceMentions，把用户输入中的@ReferenceName归一化为精确名字（prompt-enhance.ts#L51-L67）。只有真正被 mention 的角色才会告诉模型，注释明确说明“列出全部项目角色会导致模型注入未被提及的角色”。
LLM 调用：经 orchestratorChatCompletion 使用gpt-4o-mini、temperature: 0.4、maxTokens: 512（prompt-enhance.ts#L109-L119）；SYSTEM_PROMPT明确要求“保留角色名原样，包括撇号、连字符和特殊字符（如 O'Brien 保持 O'Brien）”。
回注@前缀：模型输出不含@，代码按长度降序用 lookbehind/lookahead 把已知名字重新加上@（prompt-enhance.ts#L133-L143）。这里的注释同样强调“边界字符绝不能包含撇号或引号”。
清洗幻觉 mention：/@([\w\p{L}'-]+)/gu捕获所有 @mention，凡不在已知角色集合（不区分大小写）中一律剥掉@保留单词（prompt-enhance.ts#L145-L150）。注意该字符类已包含'和-，即任务 #2 所指的第 126 行正则的修复形态。
兜底路径：LLM 失败或返回空时，回退为“trained words 前缀 + 原始提示词（保留 @mention）”，保证生成不中断（prompt-enhance.ts#L69-L73）。

文档建议“为含撇号、连字符、Unicode 字符的名字增加测试用例”——对应的测试位置是 src/server/services/comics/tests/。

References 作用域：一处根因，四个任务（#3、#8、#6、#7）

数据模型

漫画项目的角色参考图（reference）与项目之间通过comicProjectReference中间表关联。文档指出的核心缺陷是：getProject查询中存在向后兼容回退——当项目没有任何 junction 行时，返回该用户的全部 references。由于createProject不创建 junction 行，新漫画会“继承”所有旧漫画的 references（#8）；而当用户添加第一条 junction 行后，回退逻辑失效，只剩那一条，表现为“加了一条 reference 后其他 reference 消失”（#3）。修复方向是删掉回退，只返回项目作用域内的 references。

当前源码中的实现

当前 comics.router.ts 的getProjectShell查询（comics.router.ts#L991-L1015）已无全量回退：先按projectId查comicProjectReference，无行时references直接为空数组，再按refIds批量取comicReference并附带排序后的 reference 图。此外还有两点细节：

管理员视角的作用域放宽：mod 查看他人漫画时，comicReference查询去掉userId约束（只按id in refIds），否则项目属主约束会隐藏该漫画的全部 references（comics.router.ts#L996-L1015）。
Green 域过滤：ctx.features.isGreen时，逐张过滤掉不满足hasSafeBrowsingLevel的 reference 图（comics.router.ts#L1017-L1023），这是任务 #15（Green 域端到端）在代码侧的落点之一。

Smart Create 的项目作用域（#6）

smartCreateChapter（comics.router.ts#L4509-L4588）当前实现与文档修复建议一致：

只从comicProjectReference取当前项目的 reference 行，构造projectRefIds集合；
显式传入的referenceIds若不属于本项目，直接抛throwAuthorizationError()；
再在“项目 references ∩ Ready 状态”中，按故事文本的@mention（复用resolveReferenceMentions）与显式参数做交集，得到真正参与生成的relevantRefs。

这样就杜绝了文档描述的“其他项目的 reference 因名字恰好出现在故事文本里而被拉进来”的泄漏。

增删 mutation（#7）

addReferenceToProject用upsert写 junction 行（对projectId_referenceId复合键幂等），removeReferenceFromProject用deleteMany删除（comics.router.ts#L6389-L6433）；两者都挂在isProjectOwner中间件后。文档指出移除操作“后端看起来正确、问题大概率在前端调用或缓存失效”，排查方向是 tRPC query invalidation / 乐观更新。配套查询 getImportableReferences 还会反向计算“用户有、但不在本项目中”的 reference 列表，供导入弹窗使用。

Buzz 计费：从硬编码`'yellow'`到`getAllowedAccountTypes`（任务 #5、#15）

文档描述的缺陷：面板创建、迭代、增强等所有生成调用硬编码currencies: ['yellow']，在 Civitai Green 域（.green）上会按 Yellow 扣错币种/金额。修复建议是改用与 orchestrator router 相同的getAllowedAccountTypes(ctx.features, ['blue'])模式，按用户上下文返回 green/yellow，NSFW 限制则通过既有 feature flag 自然生效。

当前源码可印证该模式已经全面铺开：

comics.router.ts#L102 从~/server/utils/buzz-helpers导入domainSpendType与getAllowedAccountTypes；
多处生成路径统一使用currencies: getAllowedAccountTypes(ctx.features, ['blue'])（如 L2127、L2148、L2223、L2242、L4501 等），文件中已检索不到硬编码的currencies: ['yellow']；
增强管道 enhanceComicPrompt 也把currencies?: BuzzSpendType[]作为入参透传给 orchestrator chat 调用，使 LLM 增强这一步同样按正确币种计费。

任务 #15（Green 域完整走查）在文档中被定位为“以手工 E2E 测试为主”：验证 Green Buzz 币种与金额、R 级面板在 Green 的拦截/过滤、以及整体端到端行为；代码侧的主要缺口由 #5 的币种修复覆盖。

导出可靠性与前端交互修复（任务 #10、#9、#12）

PDF 导出：并行抓取 + 显式跳过告警（#10）

原缺陷是导出函数串行抓取面板图，失败即catch { /* skip */ }静默丢弃，最后几格超时就会“无声消失”。当前 ComicExportButton.tsx 已按文档建议改造：用Promise.allSettled并行抓取（ComicExportButton.tsx#L34），统计失败数量并抛出N panel(s) were skipped due to fetch errors的错误信息（ComicExportButton.tsx#L69），让用户明确知道哪些面板被跳过，而不是得到一份残缺却“成功”的 PDF。

面板数输入：clamp 时机与上限提示（#9）

原缺陷是NumberInput配clampBehavior="strict"，输入“12”只登记最后一位“2”。当前 SmartCreateModal.tsx 的修复与文档建议完全对应（SmartCreateModal.tsx#L165-L171）：max={20}、clampBehavior="blur"（失焦时再钳制，输入过程中不截断），并在输入框旁展示 “Max 20 panels per chapter. Leave empty to let AI decide.”，把 20 格上限明确传达给用户。

布局选择器选中态（#12）

文档指出选中布局仅border-blue-500 bg-blue-500/10，深色模式下不够醒目。当前 LayoutPicker.tsx 的选中态已加强为border-blue-500 bg-blue-500/20 ring-1 ring-blue-500/40（LayoutPicker.tsx#L50-L51）：背景不透明度翻倍并叠加 ring 描边，即文档建议的“更粗边框 + 更强背景”方向。

管理员权限、页面状态与其余条目（#11、#13、#14、#17、#4）

管理员下载与评级权限（#11）

comic-chapter.utils.ts 中的useChapterPermission钩子已把isModerator纳入授权判断：管理员恒得canDownload: true（见 comic-chapter.utils.ts#L33-L66）。文档给出的剩余工作是：确认阅读页在canDownload为真时确实渲染下载按钮、为 mod 增加 NSFW 等级选择器（复用现有setTosViolation或新的 rating mutation，并复用代码库已有的 NSFW 徽章色板）。公开阅读页对应 src/pages/comics/[id]/ 下的路由页面。

预览页空白与迭代编辑加载态（#13、#14）

#13：/comics/project/{id}/read出现空白页，可能来自查询报错、鉴权失败或项目无已发布且 Ready 的面板。修复要求在 read.tsx 中为getProjectForReader增加明确的空态/错误态，保证页面“不出现无解释的空白”。
#14：iterate.tsx 在iterateGenerateMutation执行期间应展示 loading 遮罩并阻止/警告导航（刷新会丢失进行中的工作）；同时 Nano 全尺寸图较大，建议先用缩略图预览，待全图加载完成再替换。

横版漫画留白（#17）

文档方向：检查阅读页面板图的 CSS——横版面板需要与竖版不同的max-width/aspect-ratio处理，避免两侧大片黑边。

宽高比持久化（#4）

文档建议把用户上次使用的宽高比按项目存入localStorage或项目meta字段。从当前源码看，PanelModal.tsx 中仍存在多处'3:4'硬编码默认值（如 L516、L533、L572），且该文件中未见 localStorage 持久化逻辑——也就是说，此项在清单中仍属“待办”，与 #16 一样是需要独立规划的能力项。

系统内直接生成封面图（#16）

原问题：创建漫画时需先去主 Generator 生成封面/主视觉再导入。文档建议 v1 用一个“Generate Image”弹窗：输入 prompt → 提交一次 workflow → 等待结果 → 用作 cover/hero，复用既有 orchestrator 提交逻辑。值得注意的是，当前组件目录中已存在 GenerateImageModal.tsx，从文件命名与所在目录结构看，与该项修复方向一致（具体交互细节需结合组件源码确认）。

企业官网建设流程全解析