add-new-faction

name	add-new-faction
description	BoardGame 新增派系/角色/英雄端到端流程。用于 Smash Up、Dice Throne、SummonerWars 从素材、数据、资源、规则到审计、E2E 与截图验收。

新增派系/角色完整交付工作流

核心原则

新增派系/角色不是单纯“能显示图”或“能进入游戏”。只有同时完成以下六条，才能说“新增完成”：

1. 数据录入完成：逐对象真相源、结构化字段、i18n、代码定义都可追溯。
2. 资源链完成：正式资源压缩、manifest、运行时引用、服务器素材主源发布和远端回查完成。
3. 机制完成：规则文本中的技能、Token、状态、卡牌效果、时机、目标、可选/强制语义已实现或明确冻结；规则文本必须先拆成可编号子句，不能用对象级一句“已实现”覆盖多句能力。
4. 审计完成：evidence/<gameId>/ 有逐项审计文档，且默认按对象级彻底审计执行。每个新增对象都必须有独立矩阵行、规则子句表、L0/L1/L2/L3/L4 结论、测试/截图证据与残余范围；只有在已经登记为“共享链路完全同构，仅配置不同”的合法复用时，才允许复用另一对象的 L3/L4，且必须写清复用对象与判等依据。
5. 端到端完成：真实入口 E2E 覆盖新增对象可选、可初始化、关键 UI 可见，涉及交互的机制有成功路径截图链；凡是“你可以 / 可选 / 至多 / 任意数量”的对象，必须额外补一条合法候选存在时的跳过/空选否定路径，证明“能做”也“能不做”。只要本轮出现新的交互类型或新的 UI 表现 / 新的交互组件 / 新的操作方式，必须至少补 1 条该新类型 / 新 UI 的 direct E2E，不得只借旧对象 shared 证据代替首条真实入口验证。
6. 剩余风险清空或显式冻结：任何未实现/未验证项都必须写成 blocked 或 scoped-debt，不得混入“完成”结论。

默认执行口径（强制）

• 新派系 / 新角色 / 新英雄默认就是全面审计留档：只要任务语义是“新增派系/新增角色/新增英雄/从素材做到可玩/新对象接入”，且用户没有明确把范围缩成“只录入 / 只修一个 bug / 只做静态接入”，就默认必须把对象级全面审计 + evidence 留档作为交付物的一部分执行完，不需要再次询问“要不要补审 / 要不要审计 / 要不要留文档”。
• 新增任务里的“全面审计”不得由执行者自定义缩写：只要在新增派系/新英雄任务里对外使用“审计 / 全面审计 / 深入审计 / 收口审计 / 做到底 / 已审计完成”这些口径，具体要审什么、做到哪一层、什么情况下才算完成，必须回到 docs/ai-rules/testing-audit.md、docs/ai-rules/testing-audit-core-principles.md、docs/ai-rules/testing-audit-dimensions.md、docs/ai-rules/audit-evidence-template.md 和对应游戏专项 workflow 执行；不得由执行者自己口头定义成“我这轮补了几条测试 / 看了几张截图 / 跑了几条代表链，所以这就算全面审计”。
• 全面审计的最小交付清单必须服从审计文档：至少要按审计文档要求落到对象全集、规则子句表、完整技能流程矩阵、命中 D 维度、L0/L1/L2/L3/L4 证据层级、必要时的 L4 共享链判等矩阵、旧 evidence / 旧结论回写；缺任一项，只能降级成“专项审计 / 抽样审计 / 代表性验证 / 仍有残余范围”，不得继续叫“全面审计完成”。
• 修出漏项后必须自动扩审兄弟对象：如果在新增批次中发现某个对象存在录入错、共享消费合同错、实现漏项、L3/L4 证据缺口或旧审计失效，默认必须继续按同维度扩审同批兄弟对象，并同步回写 evidence；不能只修用户点名对象后停下来，把“剩下要不要继续”再抛回用户。
• direct E2E 不能拿中间态冒充收口：凡新增对象的真实入口链路包含变体选择、simple-choice、奖励骰、防御重投、response window、pendingDamage、deferred/finalize 或其他中间态，L3/L4 证据都必须继续打到最终权威状态；prompt/modal 出现、slot 可点、pendingAttack.sourceAbilityId 命中、pendingBonusDiceSettlement 存在、customAction 被调起 只能算入口或中间态证据，不能写成玩法收口。
• 旧 evidence 被当前代码/测试推翻时必须先回写：若当前实现、合同测试或 direct E2E 已证明旧 rule/、旧 evidence/、旧截图结论失效，必须先回写原文档，明确失效结论、替代证据与当前残余范围；未完成回写前，不得继续把该对象或整批新增任务对外表述成“已审计完成”。
• 停止条件只能是矩阵收口或显式缩范围：新增批次任务中，只有两种情况可以停止推进：
  1. 批次矩阵已经收口到 passed / blocked / scoped-debt(经用户确认冻结)；
  2. 用户当轮明确改口，把范围缩成局部修复、局部录入或局部验证。 只要这两条都不满足，就不得把“已修一个问题”表述成“新增任务已完成”。
• 旧审计结论必须先和当前代码/测试对账：继续实施、扩审或判定“未实现/已实现”前，必须先把旧 rule/、旧 evidence/、旧截图结论与当前代码 + 当前自动化测试 + 当前真实入口证据对账。旧文档里写“未实现”“已对齐”“已收口”都不能直接当成当前结论。
• 旧结论失效时必须先回写，再继续外推：一旦确认旧文档的对象级结论已被当前代码、当前测试或新真相源推翻，必须先回写原文档，标明失效结论、失效原因、替代证据与当前残余范围；未完成回写前，不得把该对象或该批次继续表述成“已审计完成”。
• 旧文档回写必须改到高风险正文行（强制）：凡旧 rule/、旧 evidence/ 内部仍保留会误导当前状态的对象矩阵、残余范围、只到入口、仍待补 L3/L4、对象级未实现 等句子，必须把对应正文行一并改掉，或在行内直接注明“历史快照/当前以某文档为准”。只在文首补一段“以新文档为准”而正文旧结论不动，不能算回写完成。
• 对象级缺口已收敛为批次治理尾项时不得继续沿用旧残余（强制）：如果当前最新证据已经证明对象级 L3/L4 已补齐，剩余只在批次级 L4 判等矩阵、外围旧文档统一收口或治理口径，那么所有旧文档中仍把这些对象写成“未实现/只到入口/仍待补关键 L4”的行，都必须同步降级为历史轨迹；否则新增批次任务不得宣称“当前只剩治理尾巴”。
• 代表链与单对象修复都不能替代批次收口：若当前只修了某个对象的实现 bug、只补了代表性 E2E、或只补了对象级 L2/L3，而批次矩阵里仍有缺行、旧结论未回写、兄弟对象未扩审或对象级 L4 未说明残余，就只能汇报到对应层级，不能把整批新增任务说成“完成”。

先读

• 根规范：AGENTS.md
• 数据录入：docs/ai-rules/data-entry.md
• 资源链路：docs/ai-rules/asset-pipeline.md
• 机制/引擎：docs/ai-rules/engine-systems.md
• 审计入口：docs/ai-rules/testing-audit.md
• 审计核心原则与矩阵：docs/ai-rules/testing-audit-core-principles.md
• 审计维度：docs/ai-rules/testing-audit-dimensions.md
• 测试规范：docs/testing-best-practices.md、docs/automated-testing.md
• UI 改动：docs/ai-rules/ui-ux.md

游戏专用路由

• Smash Up 新派系：读 docs/games/smashup/workflows/smashup-faction-intake.md，若包含玩法实现再读 docs/games/smashup/workflows/smashup-faction-implementation.md。
• Dice Throne 新英雄/角色：读 docs/games/dicethrone/workflows/dicethrone-hero-intake.md。
• 其他游戏暂无专用 workflow：以本 skill + docs/ai-rules/data-entry.md + 该游戏 rule/ 为准，并补专用 workflow，不要把临时口径写进全局规则。

S0：范围与批次矩阵

先锁定：

• gameId
• 新增对象 ID 与中文/英文名
• 素材目录 / 规则书 / Wiki / 用户指定真相源
• 当前 worktree / 分支职责
• 是否要求“彻底可玩”还是只做 intake

必须建立批次矩阵：

objectId	数据录入	资源链	机制实现	审计	E2E	状态

每格只能填：

• pending
• in_progress
• passed
• blocked:<原因>
• scoped-debt:<明确冻结范围>

没有证据不得填 passed。

S1：数据录入门禁

每个新增对象至少落三类文档：

• 真相源表：素材、路径、用途、获取日期、对照源。
• 录入核对：技能/单位/Token/状态/基础规则逐项结构化。
• 卡牌/对象核对：每张卡/每个单位/每个子对象逐行记录。

若图片能直接判定槽位/区域/atlas/布局，还必须在 S1 数据录入阶段 同步产出可视合同表：

• visualRegion/slotId -> 图上对象 -> 运行时对象 -> 允许状态(active/passive/defense/display-only/empty) -> 是否可交互
• 这张表属于录入交付物，不属于审计临时补工；没有它，数据录入不得填 passed。

最低粒度：

• 每个技能 / Token / 状态 / 卡牌 / 单位 / 建筑 / 基地都必须单独一行。
• 每行必须包含：来源定位、原文要点、结构化字段、实现状态、疑点。
• 每个对象必须再拆“规则子句表”：C1/C2/C3... 分别记录时机、入口、主效果、替代入口、额外触发、例外/否则、清理或 once/turn。任一子句缺实现或缺证据时，该对象不得填 passed。
• 对于存在可选语义的能力，行内必须额外记录“合法候选存在时的 skip/空选证据”；成功路径只能证明已实现，不能替代拒绝路径。
• 实现状态使用 L0-L4：
  • L0：仅素材定位。
  • L1：静态数据/i18n/图片索引。
  • L2：领域行为有单测或等价逻辑验证。
  • L3：真实 UI/E2E 成功路径。
  • L4：复杂交互、响应窗、finalState/triggerQueue/reaction session 或等价闭环。

禁止：

• 只录名称/费用/图片索引就写“录完”。
• 看不清数字、目标、时机时靠猜。
• 把临时裁图当正式运行时资源。
• 对大 atlas / 扫描图 / 拼图直接整张视觉读取。单边超过 2500px、总像素超过 8MP、或文件超过 8MB 时，必须先生成低清总览、分块图和必要的单格裁图；总览只判布局，字段录入必须看分块或单格。

S2：资源链门禁

必须区分：

• 原始素材
• 临时核对/裁图中间产物
• 正式运行时压缩资源
• atlas/config 资源

强制步骤：

1. 生成或确认正式 compressed/*.webp。
2. 确认代码引用不硬编码 compressed/。
3. 先对照新素材与旧版/既有合同：如果规格、语义、索引模型一致，复用既有共享合同；如果不一致，再为新增对象建立独立合同或按对象分流。
4. 重建 manifest。
5. 运行资源校验。
6. 先预检本轮资源发布范围：
   • 单派系 / 单角色 / 单英雄优先用 node scripts/assets/upload-to-server.js --check --asset-prefix <public/assets 相对路径前缀>。
   • 只有任务本身就是全仓资源发布，或用户明确授权全仓发布时，才直接用无过滤的 npm run assets:check。
7. 上传到服务器素材主源：
   • 单派系 / 单角色 / 单英雄优先用 node scripts/assets/upload-to-server.js --asset-prefix <public/assets 相对路径前缀>。
   • 不得为了一个新增对象直接跑无过滤的全仓 npm run assets:upload，除非预检结果和用户授权确认影响范围可接受。
8. 对本轮代表 URL 做 HEAD 回查。

新增 atlas 的额外强制门禁：

• 只要本轮新增的是实际运行时会请求的 i18n/<locale>/<gameId>/... 资源，除了游戏级 public/assets/i18n/<locale>/<gameId>/assets-manifest.json，还必须确认根级 public/assets/i18n/assets-manifest.json 也出现对应新键。
• 不能把 node scripts/assets/generate_asset_manifests.js --validate 的 incremental 通过，误当成“根级 manifest 已补齐”。对已存在 manifest 来说，incremental validate 不会因为“漏了新键”报错；必须显式重建 manifest，并 grep/合同测试确认新键实际写入。
• 若某张 atlas 最终不进入运行时合同，只能留在 temp/、docs/ 或 evidence；一旦发现它只是候选/错图/参考图，必须从 public/assets/** 删除后再上传，不能让它继续留在正式资源树等待误传。
• 图集配置 JSON 与图集媒体必须分开判定：如果项目专项 workflow 规定某类 JSON 是本地配置文件，就不得把远端 JSON 404 直接判成资源缺失，也不得用“远端已上传/未上传”替代本地 JSON 真实消费验证。必须回到运行时消费链，证明 frame key、atlas id、资源路径和 UI 命中结果一致。

若 .gitignore 忽略正式 WebP，必须在 evidence 写清“本地必须存在但不进 git”的资源清单和远端 URL。

共享资源禁令：

• 新增对象接入必须先比较新素材与旧版/既有合同是否一致；一致时复用旧合同，不一致时新增独立合同或按对象分流。
• 新增对象素材不一致，只能证明“新增对象不能直接复用旧合同”，不能证明既有共享运行时合同应该被替换。
• 禁止用新增对象的新素材、新尺寸、新索引模型反向覆盖既有对象已经依赖的共享 atlas、sprite、索引、公共资源路径、资源解析函数或渲染合同。
• 如果确实怀疑共享合同本身错误，必须把任务升级为“共享合同迁移/修复”，不再按新增对象普通资源接入处理。
• 共享合同迁移/修复必须先证明旧合同失效，列出所有既有消费者和预期影响，获得明确授权，并提供代表性老对象回归证据。
• 移动端与 PC 表现不一致时，先排除浏览器缓存、服务器素材主源缓存、manifest hash 和实际请求 URL/响应体；缓存或分发问题不能通过改共享合同来修。

S3：机制实现门禁

从真相源逐项裁定：

• 子句：每一句/每个分号/每个“特殊能力、持续、否则、而不是、额外、每回合一次、其余、任意顺序”都必须拆成独立验收项。
• 目标：self/opponent/any/player/unit/card/base 等。
• 时机：打出时、结算前、防御前、结算后、回合结束、响应窗。
• 强制/可选：必须有对应交互或自动结算理由。
• 可选/至多/任意数量：有合法候选时必须允许跳过或空选；行为测试必须同时覆盖“选择后生效”和“跳过后不改变权威状态”。
• 消耗：资源/手牌/token 是否消耗，何时消耗。
• 状态：core / sys.interaction / EventStream / UI 派生的正确归属。

每个可执行对象必须建立“完整技能流程矩阵”，不能只测触发点：

objectId	真相源	静态定义	候选/入口	命令/执行	消耗/限制	主效果	分支/否定	后续清理	证据层级	状态

矩阵要求：

• 技能、Token、状态、卡牌、被动按钮、攻击修正都必须入表；不能只列“新机制代表项”。
• 矩阵必须按规则子句逐项核销：主效果、替代入口、额外额度、额外触发、放回/不弃牌、每回合一次、否则分支、清理时机都要分别有证据。
• “可触发 / 可点 / prompt 出现”只能填候选/入口，不能替代命令、主效果、后续清理。
• 若对象走的是奖励骰、变体选择、防御重投或其他分段交互，pending/sourceAbilityId/prompt 一类中间态只能写在“候选/入口”；主效果 或 后续清理 必须落回 HP、token、手牌、资源、状态，以及 pendingAttack/pendingDamage/pendingBonusDiceSettlement/interaction 的最终收口。
• 有分支、可选、响应窗、防御、不可防御、奖励骰、跨阶段或回合结束的对象，必须单独写分支/否定路径证据。
• 任何对象缺少 L2 权威状态验证或 L3 真实入口证据时，状态只能写 blocked 或 scoped-debt，不得填 passed。
• 使用共享框架字段时必须做“消费合同反查”：
  • 先找实际 resolver / system / pipeline 消费点，而不是只看类型定义允许什么。
  • 逐项证明 timing、phaseId、customActionId、targetType、status timing、command payload 等字段值会被对应消费点读取。
  • 新增对象命中共享消费点时，必须跑或补自动合同测试；例如 DiceThrone 防御技能必须证明 effect timing 能被 defense resolver 消费。
  • 若 DiceThrone 防御技写了“可重掷 / 可再投 / 至多 N 颗”，还必须单独验证共享防御投掷合同是否真的消费了该语义：至少覆盖 rollLimit 或等价字段的 L2 合同测试，以及 1 条真实 UI 里“保留部分骰子后继续重投”的 L3 证据。
  • 如果合同测试命中旧对象，必须把旧对象纳入同轮修复/降级审计，不能把它当作“与新增无关”跳过。

未实现项必须进入 blocked 或 scoped-debt。用户要求“彻底完成”时，scoped-debt 不能作为收口，必须继续实现或说明硬阻塞。

S4：审计门禁

审计文档必须落到 evidence/<gameId>/，无文档等于未审计。

用户、任务名或 evidence 标题只说“审计 / 全面审计 / 深入审计 / 收口审计 / 做到底”时，默认含义都是：

• 当前批次每个新增对象都有独立审计行；
• 每个对象都按规则子句逐项写明实现入口、共享消费点、L0/L1/L2/L3/L4 证据或阻塞原因；
• 只有“共享链路完全同构，仅配置不同”的对象，才允许复用代表链；
• 仍存在对象级 L3/L4 缺口时，结论只能写“代表性玩法已验证”或“仍有残余范围”，不得写“已审计完成 / 当前发布口径已收口 / 没有死角”。

审计文档至少包含：

• 全面审计自检表：必须逐项列出 对象全集、规则子句表、完整技能流程矩阵、L0/L1/L2/L3/L4 证据层级、命中 D 维度、框架消费合同矩阵、L4 共享链判等矩阵、旧 evidence/旧结论对账回写、真实入口 E2E 与截图核验、残余范围声明 的状态。任一项缺失、证据不足或只覆盖代表对象时，批次结论必须自动降级为“代表性玩法已验证”或“仍有残余范围”，不得写“全面审计完成 / 当前发布口径已收口 / 没有死角”。
• 批次矩阵最终状态。
• 权威来源清单。
• 逐对象数据录入结果。
• 逐对象机制实现结果。
• 逐对象规则子句表：C1/C2/C3... 写清时机、主效果、替代入口、额外触发、例外/否则、once/turn、清理。
• 逐对象完整技能流程矩阵，覆盖“触发前条件、真实入口、命令/handler、消耗、主效果、分支/否定路径、后续清理、证据层级”。
• 逐对象 L0/L1/L2/L3/L4 结论；若复用别的对象的 L3/L4，必须单列“复用对象 / 共享链路 ID / 判等依据 / 本对象剩余差异”。
• 若当前批次准备复用代表链、或口径写成“对象级 L3 已齐，剩余只差 L4/治理层”，必须额外单列 L4 共享链判等矩阵：对象名、共享链名称、代表对象、是否满足“仅配置不同”、判等依据、剩余差异/残余风险缺一不可。
• 框架消费合同矩阵：列出本轮对象复用的共享 resolver/system、消费的字段枚举、允许值与实际消费值、自动合同测试名、命中旧对象及处理结论。
• 命中的 D1-D52 维度。
• 测试命令和结果。
• 截图绝对路径和肉眼观察。
• 若本轮有“新交互类型 / 新 UI”，必须单列验收表：新类型/新UI -> 首条 direct E2E 对象 -> E2E 文件路径 -> 截图绝对路径 -> 人工观察结论。
• 未覆盖风险与冻结依据。
• 若对象复用代表链，必须逐对象写清：代表对象、共享链名称、判等依据、仅剩哪些配置差异、是否还有额外子句待补。只要差异不止配置项，就不得复用深层证据。

全面审计自检表必须放在 evidence 前三屏内，且必须使用可搜索状态词：passed、representative_only、blocked、scoped_debt。禁止把自检结果藏在总结段里；禁止只写“已按审计文档审过”而不列逐项状态。

若新增对象的权威来源里存在可直接判定槽位/区域/atlas/布局的图片、玩家板、棋盘或图集，审计文档还必须引用 S1 已建立的可视合同表，并验证实现与其一致：

• 命中的 D52 权威可视合同一致性 结论。
• 至少 1 条合同测试 + 1 条真实截图证据，证明特殊区域没有被旧共享语义误占。

禁止：

• 只写“已核对正常”。
• 用一个对象的 E2E 外推整个新增批次，除非已登记为“共享链路完全同构，仅配置不同”的合法复用。
• 保留旧错误结论不修订。

S5：端到端门禁

E2E 必须来自真实入口。

最低要求：

• 新对象能在真实选择/组建入口出现。
• 新对象能被真实玩家选择/使用。
• 能进入真实游戏或真实交互场景。
• UI 中能看到新增对象本体：面板、卡图、单位、Token、状态或对应关键识别特征。
• 如果新增对象包含 Token / 状态 / 标记图标，不能只证明“徽章可见”。必须证明真实 UI 使用了预期 sprite/atlas，而不是纯色、文字、加载态或兜底样式；检查方式按游戏专项 workflow 执行，至少包含 DOM 样式断言或等价截图证据。

涉及复杂交互时，必须补成功路径截图链：

• 触发前/入口
• 交互出现
• 执行关键动作后状态变化
• 收口后可继续推进

若本轮出现新的交互类型或新的 UI 表现 / 新的交互组件 / 新的操作方式，额外强制：

• 至少补 1 条该新类型 / 新 UI 的 direct E2E；
• 该条 E2E 不能只复用旧对象的 shared 证据；
• 验收与最终汇报必须同时输出：
  • E2E 文件完整路径
  • 至少 1 张本轮实际核对过的截图绝对路径
  • 该截图对应的新交互 / 新 UI 名称与观察结论

最终回复若说 E2E 通过，必须给至少一张本轮实际核对过的截图绝对路径。

S6：完成判定

只有当批次矩阵所有格为 passed，且 evidence 中没有未冻结风险，才能说“已完成”。

完成判定还必须回查最新 evidence 的 全面审计自检表：

• 只要自检表中仍有 representative_only、blocked、scoped_debt，或结论段仍写着“仍有残余范围”，就不得把新增派系/新英雄目标汇报为完成。
• 只要真实入口 E2E 只覆盖代表对象，且 L4 共享链判等矩阵没有证明其余对象“仅配置不同”，就不得用该代表链替代批次完成。
• 如果本轮动作只是把旧误称降级、补自检表、列残余范围或修正 evidence 口径，只能汇报为“已完成降级留档 / 已完成重审记录”，不得汇报为“全面审计完成”或“新增派系完成”。
• 若任务管理或对外状态需要标记完成，必须先确认 evidence 自检表所有完成必需项均为 passed，且残余范围为空或已由用户明确冻结；否则该目标必须继续保持未完成状态。

如果仍有 blocked 或 scoped-debt：

• 只能说“完成到某层级”。
• 必须列剩余对象与层级。
• 用户要求“重来/彻底完成/做完再停”时，继续执行，不得停在总结。