game-audit-workflow

star 15

全游戏通用审计流程与证据链工作流。用于规则/卡牌/技能/状态/交互的“描述-实现”对照，按 D1-D52 审计维度出具审计报告与测试证据；当用户要求“审计/核对/对照规则/补审/审计报告”时触发。

zhuanggenhua By zhuanggenhua schedule Updated 6/6/2026
play_arrow Run Skill in Manus View GitHub

name: game-audit-workflow description: 全游戏通用审计流程与证据链工作流。用于规则/卡牌/技能/状态/交互的“描述-实现”对照，按 D1-D52 审计维度出具审计报告与测试证据；当用户要求“审计/核对/对照规则/补审/审计报告”时触发。

全游戏审计流程（Game Audit Workflow）

概览

本技能用于所有游戏的审计工作：从权威规则/图片/说明出发，对实现做全链路对照，并按 D1-D52 维度输出可复查审计证据（含测试/截图链路）。

必读权威维度表：docs/ai-rules/testing-audit.md（D1-D52）。

  • 需要时可先打开本技能 references：references/dimensions.md（索引/提示）。

默认执行口径（强制）

  • 审计默认就是全量审计当前范围：用户或文档只说“审计 / 补审 / 重审 / 收口审计”时，默认含义是把当前明确范围内的对象、子句、共享链路和适用维度做完整审计，而不是只做抽样、代表链或局部核对。若实际只做专项或抽样，必须显式写明“专项审计 / 抽样审计 / L1-L2 静态审计”。
  • “全面审计”具体做什么必须服从审计文档，不得口头缩写：只要任务、evidence 标题或对外汇报里用了“审计 / 全面审计 / 深入审计 / 收口审计 / 做到底 / 已审计完成”，就必须以 docs/ai-rules/testing-audit.md 和 docs/ai-rules/audit-evidence-template.md 作为动作清单真相源；执行者不得自行发明“链审计”“代表链差不多看过了”“我这轮主要补了几条测试所以算全面审计”之类缩写口径来替代对象全集、子句矩阵、D 维度、L1-L4、共享链判等和旧结论回写。
  • 新增批次默认全面审计留档，不再追问：如果任务语义是“新增派系 / 新英雄 / 新角色 / 新对象接入 / 从素材做到可玩”，且用户没有明确把范围缩成“只录入 / 只修一个 bug / 只做静态接入”，则默认交付就包含对象级全面审计 + evidence 留档。不得再反问“要不要补审 / 要不要留档 / 要不要做全面审计”。
  • 不能拿局部证据冒充全面审计完成：如果当前只有代表性 E2E、局部截图、局部对象修复、单维度专项复核或少量自动化测试补齐，而没有达到审计文档要求的对象级和批次级收口，结论只能如实降级为“专项审计 / 抽样审计 / 代表性玩法已验证 / 仍有残余范围”，不得继续使用“全面审计完成”口径。
  • 发现同维度漏项后必须继续扩审兄弟对象：如果当前审计命中的是共享消费合同、同类技能 family、同类 UI 入口、同类时机或同类资源链的漏项，默认必须把同批兄弟对象一起纳入复审，并同步回写旧 evidence / rule。不得只修用户点名对象后停下，再把“其余对象要不要继续补审”抛回用户。
  • 状态/token 家族不能只凭对象级直证收口：如果同一新英雄/新派系里有多个对象写入同一状态/token，或用户反馈集中在某个状态 family，默认必须继续拆出该状态的 写入 seam -> 共享消费者 -> 清理/后续 -> 已验证入口。只证明“多张牌都能写这个状态”不等于状态家族已到 L4；至少要继续查 stack limit / accept-decline / upkeep / passiveTrigger / transfer / cleanup 这些共享消费者。
  • 点入口 / 点变体不等于已结算：对真实玩家板槽位、变体 modal、simple-choice、攻击修正或其他交互入口，看到 SELECT_ABILITY、按钮点击或 modal 选择，只能证明对象进入了流程，不能直接算对象级 L3。若真合同是“先建 pendingAttack，再由 ADVANCE_PHASE / Continue / 选择确认收口”，审计必须把这两段都补齐。
  • 不可防御必须同时审“声明层 + 共享消费层”：看到 damage(unblockable=true) 或文案写“不可防御”时，不能直接判定收口。还必须反查 isDefendable 的共享来源是 ability/variant tags、choice effect patch、ATTACK_MADE_UNDEFENDABLE 还是其他 seam，并补证据证明真实流程不会误开防御窗口。
  • 停止条件只能是收口或用户显式缩范围：只要当前范围内还存在未回写旧结论、未补对象矩阵、未补关键 L3/L4、或未澄清的共享链判等，就不能把任务表述成“已审完”。只有矩阵收口，或用户明确把范围缩小，才允许停止推进。

工作流总览（Workflow-Based）

Step 0：前置检查（必须）

  1. 读取根 AGENTS.md（项目级规则）。
  2. 明确游戏范围（gameId）、模块范围（卡牌/技能/状态/交互/UI/系统）。
  3. 如果当前审计对象属于新增派系 / 新英雄 / 新角色 / 新批次接入，默认必须按对象级全面审计 + evidence 留档 + 批次矩阵收口执行，不能退化成抽样核对或只审用户点名单对象；除非用户当轮明确把范围缩成局部修复/局部录入。对这类任务，不需要再次追问“要不要补审 / 要不要把其他能力一起审 / 要不要留档”。
  4. 若已有审计文档：必须回写同一文档（见 Step 5），禁止新建重复审计。

Step 1：权威来源与真相源

  1. 明确权威来源：
    • src/games/<gameId>/rule/*.md（规则/录入核对/真相源表）
    • 本地图片/提示板/规则书截图（若用户指定优先级）
  2. 图片可判定合同时的职责边界：
    • 只要真相源里有清晰图片、玩家板、棋盘、卡图、图集、布局图，且这些材料能直接回答“对象在哪个槽/区域、哪格是空、哪格 display-only、哪格可交互”，审计必须先读取录入阶段已经建立的可视合同表。
    • 如果合同表不存在、缺字段，或与权威图片矛盾，判定为数据录入缺陷；审计应记录这一缺陷并停止把该对象判为已收口，而不是把“补建合同表”误写成审计本职。
    • 审计仍要直接看图核对合同是否可信，但角色是“复核描述/合同”，不是替代录入建合同。
  3. 权威来源优先级（强制）：
    • 用户当前对话给出的卡牌/技能/token 原文（含清晰截图或原文描述） > 卡牌/英雄技能/指示物（token/status）自身的描述文本 > 通用规则文档 > 项目“默认裁定/历史实现”。
    • 若“技能/卡牌/token 描述”与规则文档或代码行为冲突：默认以描述文本为准，并在审计文档写清：
      1. 冲突点（不超过 25 字引用）
      2. 你的裁决（以描述为准的原因）
      3. 对应代码落点与需要补的测试/证据链
    • 这条优先级必须在审计文档的“权威来源清单”里显式写出来，避免后续复盘争议。
  4. 特殊游戏规则：
    • smashup：若需校对数据/描述，必须按 scripts/scrape-wiki-with-descriptions.mjs → scripts/final-wiki-code-comparison.mjs 流程执行（除非用户指定以本地图为准）。
  5. 记录“权威来源清单”，写入审计文档。

Step 2：全链路对照（D3 强制）

逐项核对：定义 → 注册 → 执行 → 状态 → 验证 → UI → i18n → 测试。

  • 定义：卡牌/技能/状态配置
  • 注册：registry / customAction handler / 事件定义
  • 执行：execute / reducer / systems
  • 验证：validate/commandValidation
  • UI：渲染/交互/门控逻辑
  • i18n：文案一致性
  • 测试：已有用例覆盖情况

代词/指代消歧（强制，D1/D5/D15/D18 高频漏审点）：

  • 当权威描述包含“此/该/那/其/本次/这个/那个/this/that/it”等代词或省略主语时，必须输出一张指代消歧表，并写入审计文档：
    • 原文片段（不超过 25 字）
    • 指代对象裁决（例如：主攻击骰盘第几颗骰 / 奖励骰特写中的骰 / 目标玩家 / 原攻击者）
    • 在代码里的落点（字段/事件/handler）
  • 禁止在审计文档里写“应该是…”但不落到“指代对象 + 代码落点 + 证据”。

时机正确性语义核对（强制，D1/D5/D18 高频漏审点）：

  • 遇到“当…时 / 每当 / 在…之后 / 直到…为止 / 本回合内 / 结算后 / 关闭后 / 花费/消耗/支付” 等触发语义，必须完成 时机四问：
    1. 触发动作：究竟是哪一个“动作/状态变化”触发（例如：花费资源、结算完成、交互关闭、目标选择确认）。
    2. 触发时点：发生在“打出/宣告时”、还是“后续行为发生时”、还是“结算完成后”。
    3. 消耗发生点：若触发依赖消耗/支付，必须明确“消耗在何时发生”，并在代码里找到对应扣减点。
    4. 范围与持续：仅本次/本回合/持续直到条件满足？是否会“挂载等待”？
  • 代码落点必须落在具体 handler / event / reducer，禁止只写“逻辑上应该如此”。
  • 常见误审模式：把“依赖消耗/支付/结算后触发”的语义，误实现成“打出即触发/立即消耗/提前结算”。
  • 重投/再投语义拆分（强制，D1/D3/D5/D23 高频漏审点）：
    • 遇到“可重掷其中 1 颗 / 可重掷至多 N 颗 / 可重投 1 次 / 可以同一颗掷 2 次 / 奖励骰可再掷”时，必须先拆成两层独立合同：
      1. 总共还能触发几轮重投
      2. 每一轮最多能重投几颗骰子
    • 审计文档必须分别写出真实消费者，不得只写一个抽象“重投上限”：
      • rollLimit：还能再投几轮
      • selectCount：本轮允许选择多少颗骰子
      • maxRerollCount：奖励骰总共还能重投几次
      • rerollDieLimit：像防御重投这类“下一轮至多可重投几颗”的共享校验
    • 禁止只看到 prompt/overlay 打开、rollLimit 提高、或 bonusDiceSettlement 存在，就把“可重掷至多 N 颗”判成已实现；必须继续追到真实 commandValidation / interaction consumption / UI 锁定态。
    • 阶段推进合同补充（强制）：
    • 若对象运行在 offensiveRoll / targetingRoll，并且玩家动作后还存在 pendingAttack、currentChoiceSourceAbilityId、bonus settlement 或其他 continuation，必须继续追到真实 ADVANCE_PHASE / Continue / 选择确认后的收口。
    • 若对象是在 CHOICE_RESOLVED / token 响应后才改写“不可防御 / 目标 / 伤害范围”，必须同时验证“选择前中间态正确”和“选择后共享合同已改写并成功收口”。
  • 状态 family 对照补充（强制）：
    • 遇到“多张卡/多条技能都在写同一状态/token”时，必须继续画出一张最小状态矩阵：
      1. 写入 seam：是 direct grantStatus、customAction、choiceResolved、phase hook 还是其它特殊入口
      2. 共享消费者：是哪一层真正消费该状态（stack limit、accept/decline、upkeep、passiveTrigger、cleanup、transfer、damage gate）
      3. 已验证入口：当前哪几条真实入口或 L2/L3 证据已经打穿
      4. 不可外推差异：哪些兄弟入口只是共用写入 helper，哪些才共用完整生命周期
    • 禁止只因为“多个入口都能把状态写上去”就把整个状态 family 判成 L4 或“只差治理尾项”。
  • 升级/替换 family 对照补充（强制）：
    • 遇到 replaceAbility、升级牌写槽、双面切换能力集或其它“先替换定义，再由新定义继续运行”的对象时，必须拆成两层：
      1. 替换壳：打牌/翻面/扣费/离手后，abilityLevel、upgradeCardByAbilityId 或能力集切换是否真实成立
      2. 被替换后的能力 seam：新的 trigger / variants / customAction / tags / postDamage continuation 是否真实成立
    • 禁止只因为“升级牌写进升级槽”或“角色翻面切到新能力集”就把整条 family 判成 L4；这只能证明壳层成立，不能替代 replacement ability 本体审计。
  • 奖励骰/特写壳与消费者拆分（强制）：
    • 遇到多个对象都经过 rollDie、BONUS_DIE_ROLLED、奖励骰特写或 displayOnlySettlement 时，必须继续拆成三层：
      1. 触发/展示壳：overlay 是否真实打开、关闭、阶段是否可继续
      2. 分支消费者：不同骰面最终落到 drawCard / grantToken / damage / status / extraAttack / selectPlayer / damageShield 哪一类消费者
      3. 收口 continuation：是否还要经过 postDamage、额外进攻、选择确认或其它后续时序
    • 禁止只因为多个对象都能看到奖励骰特写，或都写了 BONUS_DIE_ROLLED / displayOnlySettlement，就把它们判成同一 L4 family；真正的判等边界必须落在后续消费者与 continuation。

Step 3：D1-D52 维度审计（必须）

  • 强制打开 docs/ai-rules/testing-audit.md。
  • 按 D1-D52 逐项检查，命中维度必须在审计文档里标注（如 D1/D5/D8/D34/D49/D52）。
  • 若发现“同类语义分叉/绕过共享抽象”，必须按 D3/D23/D33 记录为 finding。
  • 维度落地门禁（强制）：
    1. 每个对象至少命中 1 个维度，不得只写“✅一致”而不标维度。
    2. 对出现“可选/至多/任意/必须/不可防御/不可响应/归属玩家”字样的描述，必须覆盖 D1 + D5 + D10 的检查。
    3. 自定义事件（custom action）必须执行 D10 元数据一致 检查（事件类型 ↔ categories 对齐）。
    4. 涉及 UI 展示归属/绑定的字段，必须覆盖 D15 UI 状态同步（如 playerId/targetId 归属）。
    5. 对“点击入口后仍需推进阶段/确认选择才结算”的对象，必须显式标注 D5 + D8 + D50，不得只拿入口截图当收口。
    6. 对“不可防御”或“选择后才改写攻击合同”的对象，必须显式标注 D1 + D5 + D22 + D55，并写出 声明值 -> 消费点 -> 证据。
    7. 若任一强制维度未覆盖，审计不得收口。

Step 4：证据与验证

测试策略必须与问题类型匹配：

  • UI/交互：E2E 优先（Playwright）。
  • 逻辑/规则：GameTestRunner / Vitest。

E2E 证据链门禁（强制）

  • 涉及“改投/重掷/分步确认/阶段推进”的交互，必须提供至少 2 张连续截图（触发前/改投后），无证据链不得宣告完成。
  • 涉及“奖励骰/骰子特写”的交互，必须包含特写出现截图 + 改投后特写更新截图；若规则要求主骰盘不变，截图中必须能看到主骰盘仍保持原值。

4.1 成功路径截图链（强制）

  • 当你在审计里声称“某交互/某卡牌已验证”，则证据链必须包含成功路径：
    • 禁止只提供“失败提示/不可用提示”的截图就宣告完成。
    • 失败提示截图只能作为“否定路径”补充证据，不能替代成功链路证据。

4.2 奖励骰/特写交互：四段式闭环（强制）

凡出现“骰子特写/奖励骰特写/重掷入口/显示-only 结算（displayOnly）”，E2E 证据必须满足最小闭环：

  1. 特写出现（Spotlight Open）：能看到骰面/提示文案/关键入口；若规则要求“不改主攻击骰盘”，截图必须包含主骰盘区域。
  2. 重投/关键操作（Reroll / Action）：至少执行一次关键操作（点击重掷/确认/跳过），并截图证明 UI/状态发生变化。
  3. 关闭特写（Close）：必须截图证明特写已关闭（或被确认按钮关闭）。
  4. 收口证明（Settle）：必须证明“状态已收口且可继续推进”：
    • 临时/pending 状态已清空（例如 pendingSettlement/pendingInteraction/responseWindow 不残留）
    • 阶段可继续推进（下一阶段按钮出现/流程不阻塞）
    • 取消/消耗语义正确：必须明确并证明“本次关闭/确认”是否应消耗卡牌/资源/指示物：
      • 若规则/校验要求“条件不足则不可用”：应被门禁阻止，且不消耗卡牌/资源，并给出正确原因提示
      • 若规则要求“使用即消耗”：必须能在弃牌堆/日志/手牌变化中追溯到消耗结果

        缺任一段，只能标“待补证据”，不得写“已收口/已一致”。

判定门槛补充（强制）：

  • 失败提示不等于成功证据：如果出现“改投失败/不可重掷/条件不满足”等 toast/提示，这只能作为失败路径证据；不能替代上述 1-4 的成功闭环证据。
  • 对外口径门禁：只要你在对用户的回复里写了“已验证成功/已跑 E2E 且通过/已修复”，你就必须在证据文档里给出上述 1-4 的截图绝对路径（至少覆盖关键截图），否则不得使用该口径收口。

生效时机判定（强制，避免把 Wild West 与 Righteousness/Zanshin 混为一谈）：

  • “特写/奖励骰”只是 UI 展示形态，不等价于“数值一定延迟到关闭才生效”。
  • 以“技能/卡牌/token 自己的描述”为准：
    • ✅ 若描述是“掷 1/5 颗骰子并获得该骰面的效果”（例如 Righteousness / Zanshin）：掷骰发生时效果即已确定，数值/状态允许在特写打开期间就写入权威状态（随后 UI 再展示、再关闭）。
    • ✅ 若描述是“当你花费 X 时…然后…”或明确写了“结算后/关闭后/花费后才追加”（例如 Wild West 挂载到 Loaded 的 postSettle）：必须证明数值不会在特写阶段提前写入，只能在实际触发点/收口点写入。

4.2.1 选择玩家目标（selectPlayer / 多目标）交互：三段式闭环（强制）

凡出现“选择 1/多名目标玩家”“至多 N 名目标玩家”“目标玩家/敌方玩家/任意玩家”等交互，E2E 证据必须满足最小闭环：

  1. 目标列表出现（Target List Open）：截图中能同时看到全部候选目标玩家卡（用于验证目标集合语义：self/ally/enemy 是否正确）。
  2. 选择态变化（Selection Changed）：至少选择 1 名目标玩家并截图证明“已选中/计数变化/确认按钮 enable”。
  3. 结算落地（Resolved）：确认后截图证明交互已关闭且效果落到被选目标（同时不应误作用到未选目标）。

    缺任一段，只能标“待补证据”，不得写“已完成/已验证”。

4.3 UI 归因一致性门禁（强制，D12/D15/D20）

审计必须明确区分“资源/指示物（token）”与“攻击修正汇总（attack modifier / bonus damage）”的 UI 归因，避免把 token 的变化误当作伤害修正已展示：

  • Token 不等于攻击修正：token 的获得/消耗只能证明资源变化，不能替代“攻击修正区可见”的证据。
  • 攻击修正徽章是“效果提示”，不是“结果证明”：徽章/提示出现只能证明“攻击修正已打出/已激活”，不能证明伤害数值已提前计入。
    • 若卡牌效果为“延迟结算/分段生效”（例如依赖奖励骰特写收口后再追加加伤），必须额外用状态断言证明“数值仅在实际生效时才进入 bonusDamage/attackModifierBonusDamage”。
  • 卡牌加伤必须可见：凡通过事件/reducer 进入“攻击/伤害结算汇总”的加伤（例如 BONUS_DAMAGE_ADDED / attackModifierBonusDamage / pendingAttack.bonusDamage），必须在以下至少一个位置可见并被证据覆盖：
    1. 攻击修正区域（徽章/列表/tooltip）
    2. 战斗日志/结算日志（能区分来源）
    3. 结算数值展示（最终伤害拆解/来源标注）
  • 若产品设计明确“不展示某类修正”，必须在审计文档写明：
    • 设计裁决（为什么不展示）
    • 替代证据（用何处证明玩家仍能理解/仍可复查）
    • 对应 D 维度（至少 D12 + D15 + D20）

4.4 分段生效/延迟结算（强制）

若同一张卡/同一交互包含“立即生效 + 延迟结算后再生效”的两段效果（如固定加伤 + 奖励骰结算加伤）：

  • E2E 必须分别证明：
    1. 特写/交互打开阶段只体现“立即生效”部分
    2. 收口结算后才体现“延迟结算”部分
  • 证据文档必须写清两段生效时机与 UI 展示位置，避免把“提前显示/提前计入”误审成正确。

4.5 截图与证据书写格式（强制）

  • 截图路径必须为绝对路径。
  • 每张关键截图必须写 1-3 条“肉眼观察结论”，直接回答本轮验收点（禁止只写“正常/通过”）。
  • 最终回复门禁：如果最终回复中提到“已跑 E2E / E2E 通过 / 已验证成功”，则至少要给出 1 张你实际核对过的关键截图的完整绝对路径；否则不得使用该口径。
  • 详见 docs/automated-testing.md 的截图规范。

Step 5：审计文档落地（强制）

  • 审计文档必须落在 evidence/<gameId>/。
  • 无文档 = 未审计。
  • 推荐结构见 references/evidence-template.md。
  • 若本轮对象存在图片可判定合同，审计文档必须显式引用录入阶段的“图片合同表”或等价分区表；没有这张表，不得说该对象的图面/槽位/atlas/区域合同已审完。

修订记录门禁（强制，防止“审计完了但旧结论还在误导”）

  • 若发现旧结论失效：必须在“修订记录”写明以下四件事（缺一不可）：
    1. 旧结论是什么（建议引用原文句子或表格行的标题）
    2. 为何失效（指代消歧错误/证据链不闭环/否定路径遗漏/UI 归因不一致等）
    3. 新证据路径（至少 1 条绝对路径：E2E 截图/测试产物/对照裁图）
    4. 新结论（以及命中的 D 维度编号）
  • 用语规范：避免“新增遗漏”这类模糊表述，统一写为“旧结论失效/先前未覆盖的维度/本轮补检结果”，并明确关联到具体维度。
  • 正文同步回写（强制）：若旧文档内部仍保留会误导当前状态的对象矩阵行、残余范围、只到入口、仍待补 L3/L4、对象级未实现 等句子，必须把这些高风险正文行一并改掉，或在对应行内直接标成“历史轨迹/当前以某文档为准”。只在文首追加“以新文档为准”但正文旧结论不动，不算完成回写。
  • 对象级缺口已收敛为批次治理尾项时必须改旧矩阵（强制）：如果最新证据已经证明对象级关键 L3/L4 已补齐，当前残余只在批次级判等矩阵、外围旧文档统一收口或治理口径，那么旧文档中仍把这些对象写成“未实现/只到入口/仍待补关键 L4”的矩阵行和总结段都必须同步改口；否则审计不得按“当前只剩治理尾巴”收口。

Step 6：输出与收口

  • 输出：发现列表（Findings）+ 风险 + 证据路径 + 未覆盖项。
  • 任何未覆盖风险必须显式保留，禁止“默认通过”。

何时需要额外规则文档

  • 动画/特效：docs/ai-rules/animation-effects.md
  • UI/布局：docs/ai-rules/ui-ux.md
  • 引擎/系统：docs/ai-rules/engine-systems.md
  • 数据录入：docs/ai-rules/data-entry.md

Resources

  • references/dimensions.md：D1-D52 使用提示与索引
  • references/evidence-template.md：审计文档模板
Install via CLI
npx skills add https://github.com/zhuanggenhua/BoardGame --skill game-audit-workflow
Repository Details
star Stars 15
call_split Forks 6
navigation Branch main
article Path SKILL.md
More from Creator
zhuanggenhua
zhuanggenhua Explore all skills →