feedback-closeout

name	feedback-closeout
description	BoardGame 线上反馈批量收口流程。用于未关闭反馈、排重、真假 bug 分诊、并行修复、状态回写、关闭误报/重复反馈。

反馈收口

单一真相（强制）

• 本文件是 BoardGame 反馈收口 workflow 的唯一规范真相源。
• 正式留档只允许一个地方：线上真实反馈记录本身。
• 只要涉及：
  • 处理线上反馈
  • open / in_progress / resolved / closed
  • closedReason / resolvedMethod
  • 本地分诊板是否需要写
  • HTTP 回写与 SSH / Mongo 回写切换
  • 反馈状态与部署状态拆轴 都只以本文件为准。
• 其他相关文档只允许承担两类职责：
  • references/feedback-open-api.md：描述 HTTP 接口路径、认证方式、字段形状
  • C:\Users\zhuagenbao\docs\服务器连接与生产部署入口.md：提供 SSH / Mongo 入口和最小操作路径
• 本地 temp/feedback-closeout/**、evidence/feedback-closeout/**、截图、诊断包、导出文本都只能算临时诊断材料，不是正式留档。
• 禁止在其他文档再写一套等价的反馈收口规则、状态时机、字段要求或双写口径；若发现冲突，一律以本文件为准，并回头删掉重复规则。

概览

这个 skill 负责把“看反馈”收敛成一条固定流水线：先从开放接口抓取未收口反馈，再排重、分类、挑出可并行的非冲突候选，最后由多个子 agent 分别判断真假 bug、修复代码并回写状态。

优先使用本 skill 自带脚本，不要手工拼 URL、手工拷贝 JSON、手工维护重复组。

“处理反馈”的含义（强制）

当用户说“处理反馈/收口反馈/修复反馈”时，默认必须同时覆盖下面这些动作，不能只做其中一部分就对外宣称“已处理”：

1. 拉取最新线上真实反馈（或明确获得用户许可改用生产库直连），必要时可同步到本地分诊板。
2. 排重与代表项归并，只对代表项进行分诊与处理。
3. 分诊与结论：判定是真 bug / 误报 / 建议 / 已修复待回写 / 证据不足等。
4. 若是真 bug：修复 + 验证 + 证据（测试、截图或日志证据），不得只改状态。
5. 状态回写：把正式状态与关闭/解决理由回写到远端真实反馈记录。
6. 更新正式留档：默认只更新线上真实反馈记录本身；若需要说明真实写入口或阻塞，只写最小临时诊断材料，不额外产出第二份正式收口档。

注意：仅回写状态 ≠ 修复完成；仅本地验证但未回写 ≠ 已收口。对外汇报时必须清楚说明本轮到底完成了哪些步骤。

完成门禁（强制）

• 处理反馈任务默认视为处理线上真实反馈全量未收口项；除非用户明确限定范围（例如只处理指定 ID、只处理某个游戏、或只处理某个状态）。
• 只要目标范围内仍有未收口项（open / in_progress / resolved 任一 > 0），就不得宣称“已完成/已收口”，必须继续迭代处理。
• “数量很多”不是停止理由；默认要持续批量处理直到清零，或遇到真实阻塞（权限、接口不可达、关键上下文缺失）并明确上报。
• 每次阶段汇报与最终汇报都必须带上“口径 + 时间”：明确写“线上”或“本地”，并给出绝对时间戳。
• 面向用户的阶段汇报与最终汇报，默认用“反馈内容 / 现实症状”作为条目标题，再直接写“处理结果 / 回写状态”；不要把反馈 ID 放成主展示字段，除非用户明确要求按 ID 对表。
• 若条目是系统自动反馈，而不是玩家手动写的反馈内容，可以不写“反馈内容”；改用“系统检测到的触发场景 / 自动反馈类型 / 现实影响”作为条目标题，再直接写处理结果。
• 反馈 ID 仍然是内部排重、状态回写、审计与定位证据；如确需展示，只能放在括号、证据句或末尾追溯信息里，不要让用户先读 ID 再猜是哪条问题。

默认优先级（强制）

• 默认处理顺序是：人类反馈 > 系统自动反馈。
• 只要当前范围内仍有 feedback-modal、人工工单或其他人类来源的未收口项，就不得把 online-ai-watchdog、unsatisfiable-interaction-auto-skipped、force-end-turn-* 这类系统自动反馈当成主队列排在前面。
• 系统自动反馈的默认定位是：
  • 为人类反馈补现场、补根因线索；
  • 在人类反馈清空后继续做残余 cleanup；
  • 或在它正在持续制造新故障/刷屏/资源风险时，作为并行止血支线处理。
• 即使存在“系统单在持续刷新”的情况，对外汇报时也必须明确区分：
  • 哪些动作属于“按规范的人类反馈主线”；
  • 哪些动作只是“为了止血的系统反馈支线”。
• 若用户没有明确改口，禁止把“系统单更容易查”或“系统单更多”当成默认理由，挤占人类反馈的主优先级。

系统自动反馈的最低分诊义务（强制）

• 即使本轮主线仍是人类反馈，也不得把系统自动反馈完全跳过不看。至少要先做一次最小分诊，再决定是并行止血还是延后。
• 对每条 online-ai-watchdog、unsatisfiable-interaction-auto-skipped、force-end-turn-* 这类系统单，最低要读出并记录：
  1. autoReportKind
  2. errorContext.message
  3. stateSnapshot / actionLog 里的 reason
  4. 当前是否存在 interaction、legalActions、aiDecisionPreview
• 最低分类至少要落成下面三类之一：
  • 共享/私有视图不一致
  • 0 个合法动作 / legal_action_unavailable
  • 恢复/跳过动作被服务端拒绝
• 只有做完上面这一步，才允许把系统单标记为“暂缓到人类反馈之后”。

延后系统单时的汇报义务（强制）

• 当用户说“修线上反馈/处理反馈”，而当前范围内同时存在人类反馈和系统自动反馈时，阶段汇报里必须显式写出：
  • 当前人类反馈主线在处理哪几条
  • 哪些系统自动反馈被暂缓
  • 暂缓理由是“按默认优先级”，还是“已确认只是伴随线索”
• 禁止只汇报“已开始修反馈”，却不说明系统单其实仍未处理，造成用户误以为所有 open 项都在同一轮被覆盖。

本地临时产物（默认不留档）

• temp/feedback-closeout/**、evidence/feedback-closeout/**、本地截图、导出文本、诊断包，默认都只算临时工作材料，不是正式留档。
• 正式状态、closedReason（关闭理由）、resolvedMethod（解决方式）的唯一留档入口，统一以线上真实反馈记录为准。
• 默认动作：
  • 不创建本地 status-board
  • 不额外写本地 feedback closeout 文档
  • 不把本地 evidence 当成“收口已完成”的依据
• 允许例外：
  • 远端真实写入口阻塞，必须临时记阻塞证据
  • 需要并行分派，且远端状态不足以支撑分工
  • 用户当轮明确要求保留本地文档/截图/复盘材料
• 即使出现这些例外，本地材料也仍然只是临时诊断，不升级为第二正式留档点。
• 旧的 status-board、历史 evidence 文档若已存在，只按历史辅助材料看待；不得继续把它们当默认入口或必经留档步骤。

同轮流程缺口回填（强制，2026-06-10 新增）

• 当某条反馈在处理过程中暴露出“当前 skill / 项目规范 没有把动作时机、状态同步、证据门禁或收口顺序写死”，并且该缺口已经导致重复处理、状态滞后、同类误判或需要用户再次提醒时，必须在同一轮任务内补回项目 skill 或对应项目文档。
• 默认落点优先级：
  1. ./.codex/skill/feedback-closeout/：反馈处理流程、状态时机、脚本顺序、证据门禁
  2. 相关专项项目 skill：仅当缺口只属于某个游戏/某条专用 workflow
  3. 根 AGENTS.md：仅当这是跨任务、跨 workflow 的总不变量
• 禁止把“这次记住了”“下次注意”当成收口；如果本轮已经证明存在流程缺口，而正确落点也明确，就必须顺手补上。
• 若当前轮次因用户权限、目录缺失或落点未锁定而无法立即回填，阶段汇报里必须直接说明“哪个缺口还没固化、卡在哪一层”，不能只汇报业务修复结果。

修复后立刻回写（强制，2026-05-07 新增）

• 反馈状态与发布状态必须拆轴（强制，2026-06-16 补强）：
  • 反馈状态 只回答“这条反馈当前是否已经被定位、修复、验证并正式回写”
  • 发布/部署状态 只回答“修复代码是否已经 push / 已上线 / 已部署 / 已观察”
  • 两条轴都要记录，但不得把“还没发布/还没部署”当成“不能回写反馈状态”的理由
  • 如果本轮已确认“修复 + 验证 + 证据”成立，就必须先把反馈推进到 resolved/closed；发布、部署、观察属于后续单独事项
• 只要某条反馈已经满足“修复 + 验证 + 证据”三件套，就不得继续长时间停留在“本地已修 / 远端未回写”的中间态。
• 修复完毕后立刻收口（强制，2026-05-25 补强）：当代码修复、定向验证和 evidence 已经证明原始反馈链路被覆盖时，必须立即把对应反馈推进到 resolved/closed 回写流程；不得再用“还没部署”“还没在线上复测”“等线上不再复发”作为继续保留 open/in_progress 的理由。
• 这条规则的理由是：AI 在本地修复后无法在未部署新代码的线上生产环境验证修复后行为；生产环境仍运行旧代码时，“线上复测不复发”不是可取得证据。若把线上复测当成回写前置条件，会把所有已修反馈永久卡在中间态，造成状态板和真实修复进度失真。
• 默认动作应是：
  1. 立刻执行远端正式状态回写，并同时写入 closedReason/resolvedMethod
  2. 立刻复核远端状态与剩余未收口数量
  3. 默认不再补本地留档；只有在需要临时阻塞说明、并行认领或用户明确要求时，才生成最小本地诊断材料
• 只有在以下场景才允许暂不回写，并且必须在当轮汇报里显式写明阻塞：
  • 真实写入口不可用；
  • 用户明确要求“先别回写”；
  • 结论仍存在证据缺口，尚不能判为 resolved/closed。
• resolved 的判定不以生产部署、线上复测或未来复发观察为前置条件。部署状态、CI 状态、发布窗口、线上后续观察只能作为后续待办单独记录；只要当前反馈已经有“根因定位 + 修复 + 验证 + evidence”，就必须回写 resolved。如果部署后再次出现同根因，应按新反馈/聚合项重新处理，而不是用不可证明的“等不复发”提前阻塞当前回写。
• 对外汇报时若修复尚未部署，必须直说“反馈状态已回写，但部署状态未完成/未核对”；禁止把两件事混成一句“还不能回写”。
• 禁止把“先记到本地，等攒几条一起回写”当作默认流程；除非用户明确要求批量统一回写。

旧的本地状态板脚本仅保留为阻塞场景 fallback，不再是默认流程：

node .codex/skill/feedback-closeout/scripts/sync-feedback-status-board.mjs temp/feedback-closeout/<timestamp>/summary.json
node .codex/skill/feedback-closeout/scripts/update-local-feedback-board.mjs --id <feedbackId> --status in_progress --owner codex --notes "<仅在阻塞/并行分派时使用>"
node scripts/verify/verify-feedback-status.mjs temp/feedback-closeout/status-board.json

默认目标

• 默认目标必须是线上真实反馈。
• 对外口径默认也必须是线上真实反馈；若本轮使用本地/离线视图，必须显式标注“本地口径”，禁止混说成线上结果。
• 本地开发 API、本地 Mongo、本地导出目录、feedbacks.repaired.json、temp/*.json、网页域名上返回的 SPA HTML，都只能用于辅助诊断、证据整理和人审，不得默认视为“已经改到真实反馈状态”。
• 只要要执行 in_progress / resolved / closed 这类正式状态回写，必须先确认当前连接的就是线上真实反馈源。
• 如果当前拿到的是本地开发库、测试库、历史导出快照，必须明确标成“本地/离线视图”，禁止对外宣称“已回写”。

回写前强制核对

在第一次读或写状态前，必须先核对下面四件事：

1. 当前目标是线上真实反馈，而不是本地开发库。
2. 当前接口返回的是反馈 JSON，而不是前端 SPA fallback HTML。
3. 当前样本数量或目标反馈 ID 与用户给的导出/列表能对上。
4. 如果发现 HTTP 接口并不指向真实线上数据，或 HTTP 写路径虽然存在但当前拿不到可用管理凭证，允许切换到其他已确认的真实线上写入口，例如生产机上的 Mongo 直连脚本。

如果上面任一项不能确认，就先停在分诊和证据阶段，不要写状态。

先读

• 仓库根 AGENTS.md
• docs/ai-rules/testing-audit.md
• docs/testing-best-practices.md
• 本 skill 的 feedback-open-api.md

工作流

1. 拉取并排重

先确认 --base-url 真的是线上真实反馈接口，再运行：

node .codex/skill/feedback-closeout/scripts/triage-open-feedback.mjs --base-url <真实反馈接口基址> --slots 4

如果要把挑出的并行候选立即认领成 in_progress：

node .codex/skill/feedback-closeout/scripts/triage-open-feedback.mjs --base-url <真实反馈接口基址> --token <BearerToken> --slots 4 --mark-in-progress

禁止把 http://127.0.0.1:* 当成默认正式目标，除非用户明确说这次就是要处理本地测试反馈。 当前线上正式列表/回写接口默认是 https://api.easyboardgame.top/admin/feedback...；旧的 /feedback/open 若返回 404，视为过期入口，不得继续沿用。

脚本会：

• 默认抓取 open,in_progress
• 按内容与错误签名做重复组归并
• 产出 temp/feedback-closeout/<timestamp>/summary.json
• 把反馈中的内嵌截图落到本地 images/ 临时目录
• 为每个代表项生成一份 Markdown 诊断包
• 选出一组 parallelCandidates，用于后续并行分派
• 可选把 parallelCandidates 立即改成 in_progress

拉取完成后，默认直接进入分诊与远端回写；只有在本轮确实需要本地并行认领/阻塞备注时，才允许把本批 summary.json 同步到本地分诊板：

node .codex/skill/feedback-closeout/scripts/sync-feedback-status-board.mjs temp/feedback-closeout/<timestamp>/summary.json

2. 先分类，再决定真假 bug

按 summary.json 中的代表项处理，不要把重复项当独立问题并行开工。

分类规则：

• bug_candidate
  • 进入真实排查流程。
• non_bug
  • 优先检查是否只是建议、体验意见、已知行为、或重复上报。
• needs_owner_decision
  • 反馈指向体验偏好、性能取舍、默认开关、动画强度、交互节奏、规则口径、商业/产品策略等业务决策；不得自动改代码。
• needs_review
  • 证据不足，先人工阅读诊断包再决定。

判断真假 bug 时，必须先检查：

1. 用户描述和现有实现是否真的冲突。
2. 反馈是否只是重复、误用、环境噪音、历史已修复问题。
3. 若是 bug，最小可复现链路和可疑模块是什么。

2.0C 体验反馈 / 业务策略改动必须先让用户决策（强制）

• 触发条件：反馈内容主要描述“卡 / 慢 / 太重 / 不舒服 / 建议改默认 / 希望更快 / 动画太多 / 开关怎么设 / 交互节奏不好”等体验偏好，且当前没有证据证明存在功能错误、页面崩溃、流程阻塞或规则冲突。
• 先查既有能力：动手前必须先核对当前是否已经有开关、降级策略、最近优化、用户偏好、设备自适应或已有业务约定；如果已有开关或近期已优化，不得直接把“默认值改掉”当成 bug 修复。
• 业务语义升级门禁：只要拟议改动会改变默认表现、默认开关、动画有无、等待时长、交互节奏、规则口径、用户可见文案或产品体验取舍，就必须先停下向用户说明：反馈原文、反馈时间、当前已有能力、准备改动的现实影响、可选方案。
• 禁止行为：禁止把“体验可以更好”“用户觉得卡”“移动端可能更稳”直接包装成 bug 并实施；禁止在未取得用户当轮明确决策前，把已有可选开关改成全体默认、删掉完整表现、改变业务流程或回写 resolved。
• 允许动作：可以做只读分诊、性能证据收集、复现脚本、日志/指标补充、候选方案说明；只有用户明确选择“按方案改”后，才允许进入实现与 resolved 回写。
• 最低汇报：如果归类为 needs_owner_decision，必须用用户听得懂的话写清“这不是已证实的程序错误，而是体验/产品取舍，需要你决定是否改默认或保持开关方案”。不得用内部分类名替代结论。

2.0B 卡死类反馈必须回到真实状态继续跑（强制）

• 只要反馈原始症状是“卡死 / 阻塞 / 不能继续 / 卡住 / 一直选 / 一直弹 / 操作后没下文”，默认排查目标就是真实卡死链路，不是先替玩家或系统脑补一个“可能卡死”的局面。
• 必须优先使用该条反馈自带的真实状态材料，例如 stateSnapshot、完整 core/sys 快照、真实操作日志、事件尾部、截图或同批诊断包，注入到当前代码后继续执行后续流程。
• 最低回放要求：
  1. 说明真实快照里到底有哪些关键对象、在哪些位置、当前交互是否阻塞；
  2. 从真实状态触发或恢复到用户描述的原始位点；
  3. 至少跑一条用户本可选择的正常收口路径；
  4. 若怀疑某个分支会卡死，必须实际跑该分支到“继续卡住 / 能收口 / 证据不足”三者之一。
• 禁止行为：
  • 禁止把“某种假设局面会卡死”当成该反馈的真实根因。
  • 禁止在未核对真实状态前说“没有可选目标”“所有目标都被占了”“一定是某对象导致卡死”。
  • 禁止只看代码推导、只写构造单测、只看一个 prompt 出现，就宣称这条真实反馈已复现或已修。
• 若真实状态注入后能自然跑通原始后续流程，默认结论应降级为“当前树未复现 / 当前树已恢复 / 原反馈未证实现存 bug”，不得继续把它包装成已定位 bug。
• 若本轮只补了防循环、兜底、跳过或诊断能力，但没有让真实反馈状态回放到原始失败位点，必须归入“仅修了相关风险或通用防线”，不得写成“这条反馈已修复”。

2.0A 审计/实现与录入数据冲突时，先反查录入合同（强制）

• 审计结论、现有实现、locale、旧测试、旧 evidence，默认都可能只是消费了同一份旧录入数据；它们彼此一致，不等于录入本身正确。
• 只要反馈症状与当前录入数据、文案、卡图合同、atlas/slot 合同出现不一致，默认第一反应不是“玩家错了”或“实现肯定有 bug”，而是先质疑录入数据/录入合同是否有误。
• 默认顺序必须是：
  1. 先锁反馈命中的具体对象和现实症状；
  2. 再看当前实现和审计依据是不是都建立在同一份录入数据上；
  3. 若是，再回到主真相源图片/规则书/正式图集，重查录入合同；
  4. 只有录入合同被重新确认无误后，才把矛头转向实现 bug 或玩家误解。
• 若当前证据显示“实现、审计、测试、文案都一致，但都一致地偏离图面/规则真相源”，必须把结论写成“录入合同候选错误，审计与实现只是沿用了旧错”，不得继续表述成“审计已证明实现正确”。
• 处理这类反馈时，最低汇报必须同时说明：
  • 当前反馈挑战的是哪一条录入数据/录入合同；
  • 当前实现/审计依赖了哪些旧数据；
  • 是否已经回到主真相源重查；
  • 结论最终落在录入错、实现错，还是两者都错。

2.0 带图反馈优先核图与录入真相（强制）

• 只要反馈自带截图、牌面图、局面图、录像首帧、内嵌图片或可直接观察的图面证据，就不得先按“玩家理解偏差 / 误报 / 看错了”收口。
• 默认顺序必须是：
  1. 先看图上实际写了什么、显示了什么、发生了什么；
  2. 再核对当前录入数据、文案、规则真相源和实现链；
  3. 最后才判断是不是玩家误解、重复反馈或证据不足。
• 若图面本身已经能直接证明“牌面文本/图面效果”和当前录入或实现矛盾，默认先判为“录入/实现候选错误”，而不是优先质疑玩家。
• 这类反馈的最低结论必须同时说明：
  • 图上看到的现实内容是什么；
  • 当前录入/实现写的是什么；
  • 两者是相符还是冲突。
• 禁止行为：
  • 没打开截图，就引用“玩家可能记错了”“应该是他看错了”这类结论。
  • 图上已经出现明确牌面/按钮/数值/状态证据，仍跳过图面只按旧实现判断真伪。
  • 已经发现图面与录入冲突，还把反馈按误报关闭。

只要结论已确认，就先回写远端正式状态与理由，再继续处理下一条反馈；默认不要再额外补本地收口文档。

2.1 真实反馈真相门禁（强制）

每条反馈在进入“已修 / 已收口 / 已回写”口径前，必须先明确落到下面四类之一，禁止混说：

1. 已用真实反馈状态复现
   • 指已经使用该条反馈自带的真实 stateSnapshot、actionLog、eventStream、截图或同批真实导出，在本地成功回放到用户报错位点。
   • 只有这类，才允许表述成“这条反馈已复现并修复”。
2. 当前树已恢复 / 已失效
   • 指已经用该条反馈自带真实证据做过注入/回放，且在当前代码下该链路已正常，无法再重现原症状。
   • 这类默认口径应是“当前树已恢复，不再作为现存 bug 继续推进”，而不是继续挂成 active bug。
   • 强制收口：只要真实状态注入/回放已经证明当前树不复现，就不得继续保留在 open / in_progress；默认应直接归档收口。
   • 默认优先回写 closed；若团队需要保留“当前树已恢复”的可见记录，也可用 resolved，但无论哪种都不得继续留在未收口队列。
   • 说明里必须写清“当前代码验证通过”“不是本轮再次复现后修复”。
3. 证据不足 / 未证实
   • 指反馈只剩事后快照、文本描述、截图，或现有证据不足以把状态回退到症状位点。
   • 这类只能表述成“未证实 / 证据不足”，不能硬说“已修好”，也不能硬挂成“现存 bug 已定位”。
4. 仅修了相关风险或通用防线
   • 指本轮确实顺手修到了邻近共享风险、通用恢复链、保护逻辑或诊断能力，但没有用这条反馈本体成功复现过原症状。
   • 这类必须单独写成“修了相关风险”，禁止表述成“该反馈已修好”。

最低汇报格式至少要带：

• 反馈内容 / 用户看到的现实症状（主展示；例如“DiceThrone 在线 AI 在进攻掷骰阶段卡住”）
• 系统自动反馈可替代为：系统检测到的触发场景 / 自动反馈类型 / 现实影响，不强制补“反馈内容”
• 处理结果 / 状态回写结论：已修复、已关闭、当前树已恢复、证据不足等用户能懂的结论
• 归类结果：已复现 / 当前树已恢复 / 证据不足 / 仅修相关风险
• 使用的真实证据：stateSnapshot / actionLog / eventStream / 截图 / 其他
• 反馈 ID（仅作内部追溯证据；默认不作为用户汇报主字段，需要展示时放括号或证据句）
• 结论句里明确区分“反馈本体”与“顺手修的相关风险”

禁止行为：

• 只因为新增了测试、补了 watchdog、防住了相邻 bug，就把原反馈写成“已修”
• 只因为当前代码跑不出老错误，就一边说“已修好”，一边还继续把它当现存 bug 挂着不收
• 把“修了共享层通用问题”与“这条用户反馈本体已证实修复”混成一句话

2.2 复现证据分流（强制）

• 系统自动反馈
  • 默认要求直接消费它自带的 stateSnapshot、actionLog、reason、autoReportKind
  • 能注入就先注入，能直跑命令就先直跑命令
  • 若当前树下验证通过且无法复现，默认转 当前树已恢复 / 已失效，并直接归档收口；不再继续按现存 bug 主线推进
  • 不能因为它曾经报过错，就在当前树验证通过后继续机械地把它当 active bug
• 人类手工反馈
  • 若反馈里已经带了可回放快照或足够事件窗口，必须先按真实快照回放
  • 若真实状态注入/回放已经证明当前树不复现，同样直接归档收口，不再继续按现存 bug 挂着
  • 若只有“事后板面 + 文本描述”，而缺少触发前后的关键时序证据，只能记为“证据不足 / 未证实 / 未复现”
  • 这类场景允许顺手补反馈采集或诊断能力，但补采集能力 ≠ 原反馈已修

2.3 反馈采集缺口的处理口径（强制）

当结论是“当前树已恢复”或“证据不足”时，必须再补一句判断依据或缺口在哪：

• 是实现 bug 已不存在
• 是当前反馈只保留了事后状态，缺少触发前证据
• 是截图/日志不足以锁定位点
• 是需要额外的机器诊断窗口（例如最近 eventStream、interaction、responseWindow、触发前 checkpoint）

如果本轮顺手补了反馈采集能力，最终汇报必须写成：

• 该反馈本体：当前树已恢复 或 证据不足 / 未证实
• 本轮额外改动：补了 xxx 诊断能力，方便下次同类反馈直接注入

2.4 批量修复前先检查“最近是否已经顺手修过”

很多开放反馈会落在“代码其实已经修了，但状态还没回写”的阶段；批量开工前必须先做一次最近更新核对，避免重复修同一个问题。

强制检查顺序：

1. 先看线上真实反馈状态
   • 先确认目标反馈当前在真实线上记录里是不是已经 resolved/closed
   • 若线上已经收口，禁止再次当成待修 bug 派单
2. 必要时再看本地分诊板
   • temp/feedback-closeout/status-board.json
   • 只把它当交接/并行认领线索，不得覆盖线上正式状态；若本轮没显式使用它，默认跳过
3. 再看最近证据与最近改动
   • 优先看线上真实反馈记录里的 closedReason / resolvedMethod / status
   • 如仓库里已有历史 evidence/，只把它当辅助参考，不再要求新建同类文档
   • 再按反馈关键词、卡牌名、错误文案、游戏模块 grep 最近改过的源码/测试
4. 最后才决定是否真的进入“修复”
   • 若代码与证据已经覆盖用户描述，只差状态没回写：应走“补验证/补证据/回写状态”流程，而不是重新改实现
   • 若只能确认“可能已修”，但缺少证据：先补最小验证，再决定 resolved 还是继续 in_progress

推荐核对项：

• 线上真实反馈记录里的最新 status / closedReason / resolvedMethod
• 最近修改的目标模块、测试、E2E 文件
• 当前反馈关键词是否已出现在最近提交说明、审计文档、状态板 notes 中
• 是否存在“同根因已修”的其他反馈条目，可直接复用证据或沿同一修复链收口

禁止：

• 不看最近更新就机械重修整批反馈
• 明明已有修复证据，却再次让多个子 agent 改同一批文件
• 看到“像是修过”就直接改 resolved，但不补验证与证据

2.5 SmashUp 计分响应类反馈的专项门禁（BoardGame 项目专用）

当反馈属于 SmashUp 的 scoreBases / Me First / afterScoring / smashup_reaction_choose 链路，且用户描述里出现“让过又出现”“计分后卡死”“以前是手牌承接”“中间弹窗/提示层”“没有可选目标”“同一基地重复触发”时，必须额外执行下面这组门禁：

1. 先锁定是不是同一基地同一响应帧

   • 至少同时说明：基地索引/基地对象、reaction frameId、当前响应玩家、当前 sourceId
   • 必须分清到底是：
     • 同一个 afterScoring 帧被重复续链
     • 还是 Me First 结束后又进入 afterScoring
   • 这两种链路在结论里不得混称成“又弹了一次让过”

2. 先锁定交互载体，不得把提示壳当成交互对象

   • 必须先确认真正承接点击的是手牌、基地、随从还是系统 interaction
   • MeFirst / 顶部横幅 / 中间提示层默认只当提示 UI；未证实前不得把它们当作真正的点击承载层

3. 修复后必须同时补两层回归

   • 一条最窄源码测试：锁 pass 粘性、同一 frameId 的续链、或无目标自动收口等真实根因
   • 一条真实 E2E：必须回到用户原始链路位点，产出截图并看图确认

4. E2E 断言必须直接命中“不会再卡 / 不会再重开 / 不会再二次让过”

   • 不得只断言 phase 最终离开 scoreBases
   • 至少还要覆盖：
     • interactionSourceId
     • responseWindow.current
     • 当前玩家是否被重新拉回
     • 原始卡牌是否仍在手/是否已进弃牌堆（按场景选）

5. 看图结论必须落回用户语言

   • 例如“0 号位让过后，1 号位出完牌，0 号位没有再被拉回让过”
   • 禁止只写“interaction 已清空 / window closed”，不翻译成用户能直接判断的现象结论

3. 只并行不冲突的代表项

并行前必须满足：

• 每个子 agent 只接一个代表项。
• 只挑 parallelCandidates，或你自己确认 conflictKey 不冲突。
• 多个子 agent 不能同时写同一批关键文件。
• 同一重复组只允许一个 agent 处理代表项。

使用子 agent 时必须显式固定模型配置：

• model: gpt-5.4
• reasoning_effort: high

给 worker 的任务必须包含：

• 反馈 ID（内部任务分派、排重与回写定位用；不作为用户汇报主字段）
• 诊断包路径
• 该 worker 负责的文件或模块边界
• 明确要求先判断“是不是真 bug”
• 如果不是 bug，禁止改代码，直接回传结论
• 如果是 bug，修复后必须跑匹配验证，再回写状态

4. 状态回写规则

只在拿到明确结论后改状态：

• 误报、建议、已失效
  • 改 closed
• 确认为 bug，且代码与验证已完成
  • 改 resolved
• 重复、合并、同根因反馈
  • 不单独按“重复”决定状态，必须跟随代表项 / 同根因问题的最终结论
  • 如果同根因问题是已修复 bug，同组所有反馈都改 resolved
  • 只有当代表项本身是误报、建议、已失效、证据不足且需要关闭时，同组反馈才改 closed
• 预计要持续处理较久，且已经明确接手
  • 可先改 in_progress

状态语义补强：

• 只要本轮结论是“这条真实 bug 已经修复”，默认只能回写 resolved，不得改成 closed。
• 同根因 / 重复反馈不改变 bug 的状态语义：如果代表项是已解决 bug，同组反馈也是 resolved；不得因为它是重复上报就降级成 closed。
• closed 只用于：误报、建议、旧样本已失效、当前树已恢复但本轮没有再次做该 bug 的正式修复、或同组代表项本身就是这类关闭结论。
• resolved 的现实含义必须是：
  • 这条反馈本体是 bug；
  • 本轮已经完成根因定位、代码修复、匹配验证和 evidence；
  • 因此正式标记为“已修复”。
• 禁止把“修过了但顺手关掉”“真实 bug 已修好但写成 closed”“已解决的重复反馈按 closed 处理”“因为想减少 open 数量就用 closed 代替 resolved”当成可接受口径。

字段要求：

• closed
  • 必填 closedReason（关闭理由）
• resolved
  • 必填 resolvedMethod（解决方式）

字段必填补强：

• resolvedMethod 与 closedReason 都视为正式收口理由字段，默认必须填写完整。
• resolvedMethod 与 closedReason 默认都是给最终用户看的，不是给研发/当前操作者看的。
• 写这两个字段时，默认口径必须是：
  • 直接回答用户“现在是什么情况 / 为什么这样处理 / 你接下来该怎么理解”
  • 用现实语言写结论，不要把内部分诊判断、研发归因、流程标签直接丢给用户
• 禁止把下面这类内部口径直接写进正式理由字段：
  • 这不是 bug
  • 不是当前代码缺陷
  • 证据不足
  • 当前树已恢复
  • 按非现存业务 bug 关闭
  • 其他主要服务研发自我解释、而不是服务用户理解的句子
• 如果内部真实结论确实是“建议/误报/当前无法复现/缺少设备/旧现场已恢复”，正式理由字段也必须先翻译成用户能懂的现实结论，再把内部归类留在 agent 汇报、evidence 或诊断材料里；不要直接把内部裁定原文写给用户。
• 当目标状态是 resolved 时：
  • 必须填写 resolvedMethod
  • 若当前真实库/接口支持 closedReason，也应同步填写一句面向人能读懂的收口结论；不得只写状态不写结论
• 当目标状态是 closed 时：
  • 必须填写 closedReason
• 这里的“完整”至少要回答：
  • 这条反馈为什么被判成 resolved 或 closed
  • 若是 resolved，修的是哪条现实规则/链路、用了什么验证
  • 若是 closed，为什么它不是需要按“已解决”展示的 bug（如误报、当前树已恢复、证据不足、已失效）
• 禁止只写空字符串、占位词、只写“已处理”“已修复”“当前正常”“close”这类无信息密度文本。
• 推荐自检：
  • 把 closedReason / resolvedMethod 单独读一遍，假设看到它的人只有最终用户而不知道仓库、测试、状态机、worktree、当前树这些背景；如果这句话在这种前提下仍然成立，才算合格。
  • 如果一句话里出现了“bug、代码缺陷、当前树、证据不足、归档、收口、误报、候选、现存”等明显内部裁定词，默认先重写成用户语言。

面向玩家回复口径（强制）

• closedReason / resolvedMethod 是可能直接展示给反馈提交者看的回复，不是研发备注、排重备注、任务交接、测试结论或 agent 自我解释。
• 重复、合并、同根因反馈也必须写成玩家能理解的现实结论；允许说“同一问题已合并处理”，但必须同时说明玩家遇到的现实影响、为什么合并处理、玩家是否还需要额外操作。
• 重复、合并、同根因反馈的状态必须跟随代表项最终结论：代表项已修复则同组都写 resolved + resolvedMethod；代表项关闭才同组写 closed + closedReason。
• 禁止把下面这类内部流程词直接写进玩家可见理由字段：代表反馈、重复项、排重、收口、归档、验证通过、当前树、现存 bug、候选、状态回写、研发已处理。
• 对重复/合并反馈，推荐写法是：
  • “你提交的这次页面崩溃和同一局里的另一条崩溃记录属于同一个问题，我们已合并处理。”
  • “问题来自某条具体游戏链路/页面状态，后续版本会按修复后的逻辑处理；你不需要重复提交同一场景。”
• 写完后必须做最终用户视角自检：如果这句话直接出现在玩家反馈详情页，玩家应能看懂“发生了什么、为什么这样处理、自己是否还要做什么”；如果只能让研发看懂，就必须重写。
• 内部追溯信息只能留在 agent 汇报、诊断包、临时 evidence 或真实库的内部字段（若 schema 明确存在），不得塞进 closedReason / resolvedMethod 这类玩家可见字段。

执行顺序硬规则：

1. 决定接手该条反馈的当下，就把线上真实记录改成 in_progress
2. 一旦结论变成“已修好”或“确认不是 bug”，立刻把线上真实记录推进到 resolved/closed
3. 推进到 resolved/closed 时，必须同时回写对应理由字段；若真实写入口支持两种理由字段并且不会引入歧义，默认补齐结论字段，不得留空
4. 不得等“这一批都看完再一起改状态”
5. 不得出现“代码已经改完、测试已经跑过、但线上状态还停在 open/in_progress”的长时间滞留
6. 若因为远端回写阻塞导致无法同步正式状态，必须当场记录阻塞；需要交接时可补到本地分诊板，不得静默留待下一轮

本地分诊板不是默认双写目标：

1. 默认只回写线上真实状态，不再同步第二份本地留档
2. 只有远端回写阻塞、需要并行认领或需要交接时，才临时补 temp/feedback-closeout/status-board.json
3. 若远端回写失败且要继续交接，必须在本地分诊板补 notes 说明阻塞原因，任务结束后仍不得把它当正式留档

使用：

node .codex/skill/feedback-closeout/scripts/update-feedback-status.mjs <feedbackId> closed --base-url <真实反馈接口基址> --token <BearerToken> --closed-reason "<关闭理由>"

node .codex/skill/feedback-closeout/scripts/update-feedback-status.mjs <feedbackId> resolved --base-url <真实反馈接口基址> --token <BearerToken> --resolved-method "<解决方式>"

收口代表项并顺带关闭重复项：

node .codex/skill/feedback-closeout/scripts/finalize-feedback-group.mjs temp/feedback-closeout/<timestamp>/summary.json <feedbackId> resolved --base-url <真实反馈接口基址> --token <BearerToken>

finalize-feedback-group.mjs 的同组反馈默认必须同步为同一个最终状态：代表项 resolved 时，同组反馈也必须 resolved；代表项 closed 时，同组反馈才 closed。禁止再把“同组重复反馈”固定写成 closed。

补充规则：

• 如果开放反馈接口实际上指向本地开发库或空库，禁止因为“脚本能通”就把本地结果当成线上已回写。
• 如果当前 HTTP 回写失败是 401 缺少登录凭证，这代表“正式接口存在，但缺 Bearer 凭证”；不得再把它误判成“只能 Mongo 直写”。
• 如果线上 HTTP 接口不可用、HTTP 写接口缺少可用 Bearer 凭证、或当前项目未保存可复用管理员 token，但本轮任务本身就是“处理线上反馈 / 回写反馈状态”，则可直接改走生产机脚本或生产 Mongo 作为真实写入口；这属于反馈收口动作本身，不需要再向用户二次确认。
• 这里的默认授权只覆盖反馈状态回写所需的最小生产写操作，不扩展为任意生产数据库改数、部署、清理或旁路修复。
• 一旦改走生产机 / Mongo，必须在交付里明确写明“本轮不是通过 HTTP 接口，而是通过生产机真实数据源回写”，并记录为什么没有走 HTTP（例如 401 缺少登录凭证、生产机未保存管理员 token、接口返回非真实线上数据）。
• 走生产机 / Mongo 时，若当前真实库支持 closedReason/resolvedMethod，默认也必须一并写入；不得只改状态不写理由。
• 不得只改本地状态板就口头宣称“已收口”。
• 缺的只是关闭理由/解决方式时也直接补远端（强制）：如果线上真实记录已经是 closed/resolved，但 closedReason 或 resolvedMethod 仍为空，而本轮结论已经锁定，则默认动作不是停下确认，也不是只记本地板，而是直接对同一条线上真实记录补写缺失字段，然后继续主任务。
• 回写阻塞不得抢占主 bug 处理（强制）：当用户主目标仍是继续修 bug / 继续排查，而反馈回写这里只是缺最后一笔 closedReason/resolvedMethod 时，agent 应先用最小真实写入口补齐并继续主线；不得因为“HTTP 没 token”“要不要走 Mongo”这种已在本 skill 授权范围内的选择，再额外停下来征求用户确认。

5. 交付口径

最终汇报必须明确：

• 对用户展示问题列表时，条目标题必须是反馈内容/现实症状，不得以反馈 ID 作为标题或第一列；每条后面直接写处理结果。反馈 ID 只在用户要求或需要追溯时附在末尾。
• 对系统自动反馈展示问题列表时，允许用“系统检测场景 / 自动反馈类型 / 现实影响”代替反馈内容，不要硬编玩家反馈文案。
• 这次处理的是不是线上真实反馈
• 实际回写走的是 HTTP 真实接口，还是其他经确认的真实写入口
• 统计口径对应的绝对时间戳（例如 2026-04-21 23:34:00 +08:00）
• 总共抓到了多少条未收口反馈
• 目标范围内当前剩余多少条未收口反馈（open/in_progress/resolved 分项）
• 归并成多少个代表项
• 哪些被判定为重复并关闭
• 哪些不是 bug 并关闭
• 哪些是真 bug，改了什么，验证了什么，状态已改为 resolved
• 哪些还未处理，以及为什么不能并行

6. 提交规范（新增）

• 同一批次反馈默认合并为一个提交，除非用户明确要求拆分提交。
• 禁止把“单条小修复”拆成多个琐碎提交。
• 若同批包含多个反馈修复与对应测试，优先一个提交统一落盘。

资源

scripts/

• triage-open-feedback.mjs
  • 拉取开放反馈、排重、分类、生成诊断包与并行候选。
• update-feedback-status.mjs
  • 用开放接口回写状态。
• finalize-feedback-group.mjs
  • 按 summary.json 收口代表项，并默认把同组反馈同步为代表项的最终状态。
• sync-feedback-status-board.mjs
  • 仅在阻塞/并行认领时，从 summary.json 初始化临时本地状态板。
• update-local-feedback-board.mjs
  • 仅在阻塞/并行认领时，临时更新单条反馈的本地备注。

references/

• feedback-open-api.md
  • 开放接口与状态语义。