# Gameplay Room Secret Markers

> 在项目指定的进度解锁后，按权威发现记录显示哪些房间仍有未发现的秘密；每房间只传达有无，不泄露秘密坐标、数量或类别分布，不接管地图浏览、世界目标提示或进度系统。

- Skill: `ziyou-lu/gameplay-room-secret-markers` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add ziyou-lu/gameplay-room-secret-markers`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ziyou-lu/gameplay-room-secret-markers/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: ziyou-lu (https://skillmd.com/u/ziyou-lu)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/ziyou-lu/gameplay-room-secret-markers

---


# 进度解锁的房间剩余秘密标记

## 效果预览

先未解锁无提示，解锁后A/C各一个标记；A非最后发现保留，最终权威记录清空后移除。无数量、坐标、类别泄露。

左侧为使用前，右侧为使用后；斜视 2.5D 短循环，用途示意（非引擎实测；音频相关预览仅示意触发关系，不含声音）。

![只告诉你哪个房间还有秘密：使用前后对比](assets/before-after.webp)

## 触发与边界

完成收集阶段需要缩小搜索范围，又不希望地图直接给出秘密位置或剩余数量时使用。此入口只负责解锁门控、房间级剩余秘密存在性聚合，以及受限信息的地图呈现；二维和三维地图均可接入。它不决定秘密如何被发现、解锁物如何获得、房间如何连接，也不添加自动寻路、世界内定位或收集逻辑。

## 输入与前置条件

- 权威秘密目录与发现记录：稳定 secretId、项目认定的所属 roomId、类别、当前存档下是否已发现，以及记录是否完整有效。明确本模式统计哪些类别、任务阶段或分支中的秘密；尚未生成、暂时不可达、可错过和重复生成内容如何纳入，均沿用项目规则。
- 项目房间注册表与地图锚点：稳定 roomId、可展示状态、已探索状态、二维坐标或三维地图坐标。锚点必须表示房间，而非秘密物体位置；跨房间对象由项目明确归属，不从距离、连接线或画面猜房间关系。
- 进度系统提供的权威解锁条件及变化通知；地图打开/关闭、存档切换/读取完成和发现记录更新接口；目录、房间归属及纳入/展示政策若可在运行期改变，也需取得其版本或变更通知。此层只读取解锁结果，不另存一份任务完成事实。
- 明确未探索房间政策：是否允许显示该房间、房间名称及秘密存在性。若尚未决定，先保留关闭状态并请求项目决策，不以提示层默认揭露地图。还需确认类别纳入规则与地图现有筛选是否一致。
- 明确信息预算：对每个允许展示的房间只提供一个“仍有未发现秘密”的信号。图标、动画、文本、工具提示、读屏名称及选中反馈全部遵守同一预算。

## 实施步骤

1. 建立只读数据适配器，读取当前存档的秘密目录、发现记录、房间归属和解锁状态。检测重复 secretId、无效 roomId、缺失发现记录、未知类别及目录未就绪；不能把查不到记录解释成已发现，也不能把场景中没加载出对象解释成没有秘密。用项目完整性标识确认当前快照可用于判断空集合。
2. 按项目统计政策筛出本模式覆盖的秘密，并按提供的房间归属建立 roomId 到 secretId 的索引。同一秘密在同一房间只参与一次；多个房间归属仅在项目明确要求时使用。不要借此生成房间邻接图、推断隐藏房间或扫描当前加载的拾取物来补数据。
3. 对每个房间计算三种内部结果：Remaining 表示完整有效记录中至少一个纳入秘密未发现；Cleared 表示完整有效记录中所有纳入秘密均已发现，包括经确认的空集合；Unknown 表示目录、归属、纳入政策或发现记录不足。实现可在完整快照上对未发现条件做 OR，找到真值即可停止搜索；不必把数量传给界面。先校验该房间的数据完整性，再发布结果，避免部分遍历冒充完整判断。
4. 将数据有效性与玩家信号分开。只有有效结果才产生 hasRemaining 布尔值；Unknown 不得作为 false 发布，或按“已收集完”静默移除标记。可先采用保守策略：任何允许展示房间为 Unknown 时，整个提示层进入统一的“提示数据暂不可用”状态，不展示本次剩余/清空结论。若项目需要局部可用，须另行设计不被误读为清空、且不突破探索政策的未知态，不能静默省略未知房间。
5. 用权威解锁条件、地图开启状态及房间展示政策共同门控输出。未解锁时不生成秘密提示、工具提示或无障碍节点；已解锁且数据可用时，仅在允许展示且 hasRemaining 为 true 的房间放置一个标记。Cleared 不显示秘密标记，但不能把这种显示当作房间所有玩法目标都已完成。房间浏览选中、缩放或剖切不能改变聚合结果。
6. 将图标固定到项目提供的房间地图锚点；必要的避让偏移只由房间布局、视口和 UI 碰撞决定，不能随秘密位置或剩余数量变化。一个房间无论剩一个还是多个都只有一个标记；不按秘密实例、类别或高度层重复生成图标，也不使用叠层数量、大小、亮度、脉冲频率或排序编码剩余量。重叠房间需要辨认时，使用房间焦点或既有楼层浏览，不展开秘密坐标。
7. 工具提示和读屏可使用“此房间仍有未发现的秘密”，仅在房间名称已获准公开时包含名称。不要附加数量、类别清单、精确坐标、方向箭头或距离。使用不依赖颜色的形状/文本线索并提供静止样式；高对比、减少运动和读屏模式保留同一信息量，不能在替代文本中泄露被视觉隐藏的内容。
8. 在打开地图、解锁变化、权威发现更新和存档读取完成时刷新。目录、房间归属或纳入/展示政策变化时，先使旧索引与结果失效，再从同一当前权威快照重建索引并重新聚合；秘密由 A 房间移到 B 时必须更新两边，即使发现状态未变。若项目没有这些变更通知，明确把相关输入限定为当前地图会话内不变，修改后必须触发显式重建，不能默默继续使用旧索引。简单项目先从完整记录重新聚合；若改为受影响房间增量刷新，以 secretId 找到既定归属，再重读权威状态，而非每收一次事件就盲减计数。剩多个时发现其中一个应保留原标记，发现最后一个后才移除。重复或乱序通知不得反转已确认结果；使用当前存档标识及数据版本拒绝旧结果，跨版本读取得到不一致数据时重新读取。
9. 关闭地图时撤销本会话订阅及表现对象；重开从权威快照重建。存档切换、读档期间或解锁失效时立即隐藏旧提示并作废未完成刷新，直到新存档的解锁与发现记录同时就绪。发现写入失败时维持权威未发现状态，不因拾取动画、地图关闭或存档请求已发出而提前清空。

## 调参与失败定位

先校验纳入类别、房间归属和记录完整性，再验证解锁/刷新时序，最后调图标尺寸、对比、房间锚点避让和动画。刷新节奏按项目响应要求决定，不用闪烁或数量变化暗示聚合进度；提示清楚不等于秘密本身更易找到。

- 未加载房间被判清空：移除场景对象枚举依赖，接回完整权威目录与发现记录。
- 最后一个秘密发现后图标不消失：核对 secretId、所属房间、纳入类别和权威写入结果，再检查刷新订阅；不要直接删 UI 掩盖数据不一致。
- 同一房间出现多个标记或能猜出数量：将渲染键收敛为 roomId，审查类别拆分、工具提示、读屏、图标样式及排序；比较一个与多个剩余的呈现是否等价。
- 读档后短暂出现旧标记：作废旧存档请求及缓存，等待同一存档的解锁与发现数据就绪；缺数据期间显示不可用而非完成。
- 标记泄露未探索房间或精确位置：在输出前执行房间政策，删除秘密坐标依赖；不靠遮一层画面保留仍可被点击或读屏访问的泄露节点。

## 验收

- [ ] 同一已展示房间有零、一个和多个纳入秘密时，分别为无标记、一个标记、同样的一个标记；一个与多个的锚点、样式、提示文字及无障碍输出不泄露差别。
- [ ] 发现非最后一个秘密不改变剩余标记；发现最后一个后移除。重复通知、乱序结果和失败的发现提交均不造成错误清空或旧标记复活。
- [ ] 两类秘密按既定纳入政策共同聚合；排除类别不影响信号，纳入类别之间不生成额外类别标记。跨房间归属、重复 ID 和无效 roomId 能被发现，不能靠猜测修复；地图保持打开时将秘密从 A 改归 B，或改变纳入/展示政策后，两房间按新快照更新，旧索引不再生效。
- [ ] 未加载房间与已加载房间产生相同判定；完整空房间可判 Cleared，缺记录或未完成加载的数据不能判 Cleared，未知态不会被玩家误解为收集完成。
- [ ] 未解锁、刚解锁、解锁失效、关闭重开和切换存档均符合门控；地图 UI 不能自行解锁、收集、保存发现结果或修改探索状态。
- [ ] 未探索房间严格遵守已选政策；点击、焦点、工具提示与读屏都不会绕过隐藏规则。相同地图在二维或三维呈现中保持同一房间布尔结果。
- [ ] 多层重叠、缩放、不同屏幕尺寸及减少运动/非颜色识别下，可将标记归属到正确房间；改善可读性时没有新增秘密坐标、距离、类别分布或剩余数量。

## 相邻工作流

需要房间选择、环绕和缩放时组合[房间地图导航](../gameplay-room-map-navigation/SKILL.md)，仅让它提供浏览与房间焦点，不让它拥有剩余秘密状态。世界中目标的尺寸、局部提示或方向线索属于[世界目标发现性](../gameplay-world-readability/SKILL.md)；菜单焦点、按下与提交反馈属于[交互状态反馈](../gameplay-contextual-ui/SKILL.md)。这两个入口都不替代本层的权威记录聚合，也不因加入地图标记而自动启用世界内提示。

需要核查出处和实现选择边界时，读取[来源参考](references/sources.md)。

