data-entry-workflow

name	data-entry-workflow
description	BoardGame 数据录入与核对流程。用于图片、规则书、Wiki、PDF、截图、裁图、资源索引和文案同步；先零猜测锁真相源。

数据录入工作流

何时使用

• 用户要求“录入数据”“根据图片补卡牌/技能/Token”“核对图片和代码”“整理真相源”“补 atlas 索引”“根据规则书/PDF/Wiki 更新文案或静态数据”时使用。
• 这不是实现 skill；它先收紧数据录入纪律，再把任务路由到对应游戏的 workflow。

先读

• 通用门禁：docs/ai-rules/data-entry.md
• 涉及图片文字读取、OCR、卡图/房间图规则录入，或当前线程已因读图卡死时：.codex/skill/safe-image-reading/SKILL.md
• 涉及图片资源路径、manifest、服务器素材主源时：docs/ai-rules/asset-pipeline.md
• 录入后要进入机制实现时：docs/ai-rules/engine-systems.md
• 不确定还要看什么时：docs/ai-rules/doc-index.md

强制门禁

1. 先确认 gameId、本轮 scope、对应 git worktree，禁止在错工作区里看素材和下结论。
2. 先锁定主真相源和对照源，并把“谁负责什么字段”写清楚。
   • 用户提供的本地外部素材、下载素材、TTS/Mod 图片、临时搬运图或非项目内原生资源，只要被用于录入、裁图、OCR、manifest、运行时资源或审计结论，必须同时登记：原始绝对路径或来源链接、原始文件名、文件大小、尺寸、hash、发现/获取时间、覆盖对象、采集方式、运行时落点、压缩产物和远端回查结果。缺这些来源字段时，只能说“素材已发现/候选接入”，不得说“数据已录入 / 已锁定 / 已审计完成”。
   • 如果用户反馈的是“卡图不对 / 贴图和效果不一致 / 怀疑录入错误 / 怀疑索引用错”，必须先回到当前对象的主真相源图片（完整单卡、玩家板、提示板或原始图集），按 .codex/skill/safe-image-reading/SKILL.md 取得能服务本轮需求的图片判断结果，再判断是不是录入问题。
   • 桌游数据默认有唯一官方真相源：正式卡图、玩家板、提示板、规则书或用户明确指定的权威来源。用户反馈与现有录入不一致时，用户说法只能作为定位线索，不能直接变成卡名、分支名、规则字段、测试期望或实现常量；必须先回主真相源重新录入，再决定是录入错还是实现消费错。
   • 如果用户指出“这一个有问题说明同类也可能有问题”，不得只按用户点名字段做点修。必须先建立同类对象清单，至少覆盖同一角色、同一图集、同一槽位消费链或同一数据来源批次；每一项按 locked / blocked / disputed 标状态。
   • 录入过程中可以使用从正式原图/正式图集切出的 temp/ 裁片；但若要裁定冲突、否定玩家反馈或决定 atlas/运行时语义，必须以正式原图/正式图集或其单对象完整裁图为主真相源。
   • Wiki、网页文本、在线文本包、旧脚本 bundle 或第三方数据库只能作为对照源/候选线索，不得高于本地清晰卡图、完整单对象图、用户当轮截图或已锁合同主真相源。若替代来源与主图源冲突，合同状态必须标为 disputed；若主图源不可读或缺失，只能标 blocked/partial 并说明缺口，不得把替代来源直接升级为 locked 主真相源，除非用户明确指定该来源就是本轮权威来源。
   • 代码、现有 rule 文档、测试、旧 evidence 只能辅助定位；在主真相源图片未形成需求结果或录入合同前，禁止下“不是录入错误”的最终结论。
   • 如果这次是从“线上反馈 / 审计 finding / 现有实现异常”反查到录入层，且反馈与当前录入数据不一致，默认先把它当成录入合同候选错误处理：先复查录入真相源，再决定是不是实现 bug；不要因为实现、文案、测试、审计彼此一致，就跳过对录入本体的怀疑。
   • 重新录入时必须记录“用户口径 vs 主真相源”的差异，尤其是用户提到但图面没有的标题、分支、数值或效果；这类词不得作为分支 ID、展示名或断言期望保留，除非主真相源或用户指定权威来源能证明它存在。
3. 先裁图到单对象可读粒度，再开始正式录入。
   • 卡牌/技能牌/升级牌必须先保留一张完整单卡主裁图，半张卡或局部放大图只能辅助读字，不能直接当正式录入依据。
   • 低分辨率 contact sheet、缩略图、整页预览或降采样合图只能用于定位对象和槽位，不得作为费用、阶段、类型、生命、战力、数量、限定词、触发时机或效果数值的定稿依据；这些字段必须回到完整单卡主裁图或同一正式来源的高清局部裁图逐项锁定。
   • 所有为录入生成的裁图都必须只写到 temp/**；禁止写到 public/assets/**、public/assets/**/crops/**、manifest 或服务器素材主源发布链。
   • 若同一卡面出现多个标题、上下子区或分支块，必须先对照同系统旧实现，裁定它是同一卡的 variants/子效果 还是独立对象；在裁定前禁止自行拆成多个运行时对象。
4. 先写 Markdown 核对契约，再改运行时代码。
5. 若图片能直接判定槽位/区域/atlas/布局，必须在录入阶段先写可视合同表；没有这张表，不得进入实现或审计收口。
6. 录入阶段退出门禁：进入实现审计、机制修复或测试补证前，必须先把本批次录入合同标成 locked / blocked / disputed 三选一。
   • locked：完整单对象图、局部裁图、字段表、子句表、索引/atlas 表、对照源差异都已登记，可作为后续实现审计真相源。
   • blocked：主真相源不可读、缺图、缺页、缺索引或无法定位，后续只能登记缺口，不得凭实现文案补规则。
   • disputed：主真相源与现有数据、规则书、Wiki、旧实现或用户故事冲突，必须先裁定冲突；未裁定前不得实施机制修复。
   • locked 不能为赶进度提前打标；录入阶段必须把主真相源、可读裁图、对象归属、规则原文/原子子句和索引入口做扎实。后续审计依赖这份合同继续推进，不能靠实现阶段临时补猜。
   • locked 前必须逐项检查最小字段：对象/实体标识、主真相源定位、完整单对象图或可读裁图、对象归属、规则原文、原子子句、索引/atlas/槽位入口、对照源差异、未决项、合同状态。任一字段缺失时不得标 locked，只能标 blocked 或 disputed。
7. 阶段不得倒退：若某对象已在本轮合同中标为 locked，后续“继续”默认进入实现对照、测试补证或缺口登记；不得无故重新 OCR、重新读图或重新录入。只有发现合同缺字段、合同互相冲突、用户明确要求复核，才允许回到录入层。
   • 这条规则不是降低录入门槛，而是防止在合同已锁后反复重录。若后续实现审计暴露合同缺字段、来源冲突或对象归属不清，必须先把对象回写为 blocked 或 disputed，补齐录入合同后再继续；不得在实现审计里边猜边改。
   • “录入要做好”的验收点在 locked 之前：完整图源、可读裁图、对象归属、规则原文、原子子句、索引入口和对照差异都要一次性写进合同。locked 之后再次读图只允许用于修合同缺口，不能作为普通续跑动作；普通续跑必须直接消费合同，进入实现对照、最小补证或最小修复。
   • 已有 locked 合同和实现矩阵时，续跑入口只能先做字段完整性核对；字段齐全就继续实现审计，不得再启动图片/OCR/裁图链路。若字段不齐，必须点名缺失字段并回写 blocked；若来源或归属冲突，必须点名冲突并回写 disputed。
   • 不能用“数据录入可能有问题”作为泛化理由倒退阶段；录入问题必须具体到合同字段、来源冲突或对象归属，否则就是实现审计要继续消费的已锁规则。
8. 任意名称、数字、限定词、索引不可读时，只阻塞对应字段或交付点，禁止猜；其他已锁字段继续入表和复用。
9. 涉及规则、文案、资源映射时，先同步文档，再进入实现。
10. 发现资源 404、白卡面、CardPreview 异常时，必须按最终请求 URL 排查 compressed/、manifest 和服务器素材主源，不得只看本地原图。
11. 录入完成后，只要动到了运行时资源，就默认由 AI 主动完成上传和远端回查；如果没传成，最终必须明确告知用户哪些资源还没上传以及当前影响。
12. 若任务被标记为“长期任务/持续推进”，默认进入连续执行模式：按 S0→S4 逐层推进，除非遇到不可继续的硬阻塞（权限/环境/真相源缺失），否则不得在中间层提前收口。
13. 若任务语义是“批量派系重审 / 全部重新录入 / 三个新派系全部对照 / 有差别的都修”，必须先建立批次清单（至少到单卡/单基地粒度），并把当前批次剩余项写入 planning；在当前批次未清空前，不得因为“刚补了 1-2 张”就停下汇报。
14. 涉及 Token / 状态 / 标记图标或 atlas JSON 时，必须区分媒体资源和配置 JSON：

• 媒体资源按资源链路压缩、manifest、上传、远端回查。
• 配置 JSON 按对应游戏专项 workflow 的运行时加载规则核对；若专项 workflow 规定本地加载，不得把远端 JSON 404 当作资源缺失。
• 录入结论必须证明 frame key、atlas id、运行时路径和真实 UI 消费一致；只看到徽章可见或文件存在，不得判定图标录入通过。

15. 图片读取默认走需求交接式安全图片处理流程：主线程先把用户当前需求、业务对象、图片路径、图片需要补足的判断点和结果用途交给图片处理方（子代理或本地 OCR）；图片处理方只按需求返回最小有用结果。若当前需求是数据/规则录入，才把图片文字转成可录入的官方原文、原子子句和结构化规则字段，并写回 evidence / 合同表 / 真相表。禁止主线程在同一长线程里反复 view_image 原图，也禁止把“看过图”但未落文档的临时结论当作录入合同。

• 批量卡牌/房间/事件规则录入优先使用能直接看裁图的短子代理按需求提取字段；OCR 只能作为排序、候选标题、粗定位或失败兜底，不能作为官方原文或效果子句的定稿来源。若已有可读单对象裁图和子代理能力，不得继续把 OCR 当主录入路径。
• 读图结果按当前需求返回。验收/对比需求只返回是否满足用户预期、失败点和最小证据；排障需求只返回链路事实和下一步；录入需求才返回详细字段。
• 输出必须落到具体字段或交付点；不可读字段、缺失图源、待裁定来源只能作为 blocked/disputed/partial/failed 原因，不得变成过程报告或整轮暂停理由。
• 对房间图，读图目标是房间效果真相表：房间名、房间文字、触发时机、检定/支付、分支、抽卡标记、清理和索引。
• 对卡图，读图目标是逐卡子句表：卡名、类型、官方原文、使用时机、目标、常驻/特殊行动/武器/场景特例、消耗/弃置和结果分支。
• 能锁定的字段必须立即入表并供后续实现/审计复用；不能因为局部字段未锁定，就让整张图“白读”。
• 图片链路失败不得反复硬试：子代理不支持本地图片、读图导致上下文溢出、OCR 不可用或裁图不可读时，改走官方文本、现有合同、图集索引、代码配置或本地轻量脚本；只把确实缺失的字段标为 blocked/partial，不得因此暂停整个用户需求或批次。

资源基操清单（强制，不再省略）

只要本轮新增/替换了图片资源，必须按这个最小链路执行并回报结果：

1. npm run compress:images -- <目标目录>
2. npm run assets:upload
3. 对本轮新增资源 URL 做 HEAD 回查，要求 200
4. 最终汇报必须写清：
   • 本地压缩产物路径
   • 远端 URL
   • 上传结果（上传/跳过数量）
   • HEAD 状态码

不得以“本地看得到图”替代上传与远端验证。

Spec 驱动拆解模板（跨游戏通用，强制）

这是通用拆解能力，不需要用户每个游戏都重新教怎么拆。

当任务不只是“录入”，还包含实现/重构/验证时，默认按以下层级拆任务并逐层收口：

1. S0 - 合同层（Contract）
   • 锁定真相源、命名裁定、atlas/索引、范围边界、未决项
   • 若图片可直接判定图面/槽位/atlas 合同，必须在这一层写成正式可视合同表
   • 产出可复查合同文档（未完成不得进入 S1）
   • 退出时每个对象必须标注 locked / blocked / disputed；只有 locked 对象能进入 S1/S2，blocked/disputed 只能进入缺口登记或用户裁定
2. S1 - 配置复用层（Config-first）
   • 先接入可通过配置直接完成的一批（ids、静态数据、metadata、locale、可直接复用 handler）
   • 目标是先压缩不确定性，不在此阶段发明新机制
3. S2 - 机制扩展层（Mechanism）
   • 处理共享抽象缺口：新增/重构 shared helper、domain 机制、交互链路
   • 默认面向后续扩展，禁止临时代码；发现可复用缺口可直接扩展重构
4. S3 - UI 与 E2E 层（UX & E2E）
   • 补真实入口交互、可视反馈、关键端到端链路
   • 同步 evidence 与截图核验
5. S4 - 统一收口层（Closeout）
   • 回归测试、资源上传与远端验证、审计结论、剩余风险
   • 审计必须显式区分：
     • 本任务新增范围（必须达标）
     • 历史基线债务（可单列，不得混写成“本任务失败”）
   • 对“历史基线债务”类审计建议使用显式基线清单（allowlist/snapshot）治理：当前基线允许存在，但新增漂移必须阻断

拆解纪律（强制）

• 单派系/单模块内也要拆成 S1/S2/S3 子批次，不能“一把梭”。
• 任何阶段若仍有未实现项，必须显式留在待办，不得误报“已完成”。
• 若实现中发现共享缺口，默认直接走 S2 做可复用重构；不要把问题拖到“以后再说”。
• 若问题根因属于通用录入方法失守（例如没先保留完整单卡、没先判定一卡多能力的共享合同、先猜结构再写代码），必须先回补通用录入规范/skill，再继续当前业务录入。
• 若本轮排查还没直接看主真相源图片，只能汇报“代码/测试层暂未发现分叉”；不得把这种辅助结论包装成“已经证明不是录入错误”。
• 只有当当前层的交付门槛达标后，才能进入下一层。
• 进入 S1/S2 后，locked 录入合同就是后续实现审计的真相源；除非合同缺失、冲突或用户明确要求复核，禁止把“继续”理解成重新读图、重新 OCR 或重新录入。
• 任何“已审计/审计完成”结论都必须有 evidence/ 文档落地；禁止口头收口。
• 对“继续/continue”类指令，默认语义是“继续按当前 S 层级推进下一批任务”，而不是重复汇报上一次结果。
• 对“继续/continue”出现在批量派系重审任务里时，默认语义是“继续处理批次清单中下一个未完成对象”，不是“汇报刚做完的 1-2 项就暂停”。

批量派系重审附加门禁（强制）

当任务满足以下任一语义时：

• “三个新派系全部重新对照”
• “三个新派系全部重新录入”
• “有差别的要修复并重审”
• “继续把这批卡都做完”

必须额外执行以下门禁：

1. 先建批次清单
   • 至少列到单卡/单基地/单对象粒度
   • 每项标注当前层级：L0 卡图/中文名/索引、L1 locale/静态数据、L2 领域行为、L3 真实入口 E2E、L4 finalState/triggerQueue/reaction session
2. 先做场景 defId 真值预检
   • 凡是要写 E2E/状态注入，必须先确认测试中用到的 defId 在 src/games/<gameId>/config 或运行时 card registry 中真实存在
   • 未通过预检不得启动 E2E
3. 当前批次未清空不得停
   • 除非遇到硬阻塞，否则不得因为“新补了 1-2 条证据”就暂停到下一轮
   • 若必须暂停，必须在 planning / evidence 中明确写出“剩余哪些对象、卡在哪一层”
4. 对象证据不得外推整包收口
   • 单卡或单对象补证只能提升对象级结论，不能自动把整派系或整批派系改判为“已收口”
5. 流程维度强制保留
   • 至少持续覆盖：finalState / triggerQueue / reaction session / 真实入口 E2E
   • 不能因前面几张卡“看起来只是录入问题”就降级回只查 卡图 / locale / defId / 注册

Workflow 路由

通用新增派系 / 新增角色 / 新增英雄

• 适用：用户说“新增派系”“新增角色”“新增英雄”“从素材做到可玩”“数据录入、上传、审计、端到端全流程”“彻底完成才停”等语义。
• 必须先读 .codex/skill/add-new-faction/SKILL.md，把批次矩阵、L0-L4、资源上传、审计 evidence、真实入口 E2E 作为统一交付门禁。
• 然后再进入下方游戏专用 workflow。
• 禁止只完成选角、静态数据、资源显示或 smoke 测试后就宣称新增完成。

Smash Up

• 仅 intake / 仅录入资源
  • 适用：用户只要求核图、切 atlas、录静态数据、补 locale、补 faction metadata、上传资源
  • 读 docs/games/smashup/workflows/smashup-faction-intake.md
• intake + 派系玩法实施
  • 适用：用户明确要求“把新派系做进游戏”“继续实现玩法”“从图片一路做到正式可玩”
  • 先读 docs/games/smashup/workflows/smashup-faction-intake.md
  • intake 收口后继续读 docs/games/smashup/workflows/smashup-faction-implementation.md
• Smash Up 旧派系 / 新派系整批重审、重录、补证
  • 适用：用户明确要求“全部重新对照 / 全部重新录入 / 有差别就修 / 继续把三派系都做完”
  • 仍归入现有 Smash Up 派系 workflow，不单开“新增游戏”路线
  • 先读 docs/games/smashup/workflows/smashup-faction-intake.md
  • 再读 docs/games/smashup/workflows/smashup-faction-implementation.md
  • 并强制套用上面的“批量派系重审附加门禁”
• 禁止误路由
  • Smash Up 新派系任务不是“新增游戏”，默认不要改走 .codex/skill/create-new-game/SKILL.md
  • 除非用户真的要新增一个全新的 gameId，否则应以 Smash Up 专用 workflow 为准
• 额外硬规则： 涉及 Wiki 核对时，必须按仓库根 AGENTS.md 使用项目爬虫，不能凭记忆。
  • 若 intake 文档已经明确“不包含 gameplay ability handler”，则不得把“资源接入完成”误报成“派系完成”
  • intake 阶段的输出必须形成 handoff 包，再交给 implementation 阶段；不能把两阶段混成一团不留痕

Dice Throne

• 单角色 / 新英雄的图片、骰面、Token、卡牌、裁图、资源上传、规则文档录入： 读 docs/games/dicethrone/workflows/dicethrone-hero-intake.md

其他游戏

• 若还没有专用 workflow： 以 docs/ai-rules/data-entry.md 为主流程，再补读该游戏自己的 src/games/<gameId>/rule/ 文档。
• 不得把某个游戏的字段结构、抓取站点或索引习惯提升成全局默认。

交付要求

• 至少产出：真相源表、切图表、核对合同表、对照表、冲突待裁定表。
• 最终汇报必须明确：
  • 主真相源是什么
  • 对照源是什么
  • 哪些字段已确认
  • 哪些字段仍待裁定
  • 改动是否已经同步到文档、资源、代码
  • 资源是否已经上传到服务器素材主源；若没有，具体缺口是什么