Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/agents/card_tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
- 构造时挂载 `publicZones`、`constraints`、`movement` 三个行为模块;这些模块只持有 `room` 引用,不拥有独立推断状态。
- 高频主入口保留在 `Room` 中,便于快速查看引用和主流程;低频阶段细节委托给挂载模块。
- `registerPlayers()` / `setMySeatID()` / `setFirstHand()` / `updateFixedViewIds()` 维护玩家集合、主视角座位与固定视图位序。
- `initDeck(cardIDs)` 创建本局物理牌池、`cardIndex`、公共 `pile` Zone 与 `CardCounter`,并重建 `locationIndex`。
- `initDeck(cardIDs)` 创建等量匿名牌堆槽,将真实身份登记到 `deckIdentities` 与
`unlocatedIdentities`,初始化 `CardCounter` 并重建 `locationIndex`;真实 ID 首次揭示时才物化到实体。
- `moveCards(cardIDs, toZone, options)` 是主动状态更新入口:
- `cardIDs` 中大于 0 的 ID 视为已知物理牌。
- `cardCount - knownIDs.length` 视为暗牌占位数。
Expand Down Expand Up @@ -231,7 +232,8 @@
- 若新增会影响手牌槽 known/candidate 计数的收敛路径,必须确保相关座位进入 `Room.resolveTouchedSeats`;E1 会复用未触碰座位的手牌槽统计缓存。
- 新增或修改 `this.cards.filter(...)` 等全牌池扫描前,必须先判断能否改用现有增量快照、索引、脏事件集合,或在入口一次性归组后复用结果;尤其避免把全牌池扫描放进玩家、约束组或收敛轮循环中,意外放大为 O(玩家数 × 全牌数) 或更高复杂度。若确认全量扫描确有必要,必须使用 `recordTraversal(...)` 对该扫描站点显式插桩,并在 `tests/tracker/traversalBaseline.test.ts` 中新增或更新对应场景与内联快照,使后续遍历量增长可见且可解释;不得以未插桩的隐藏扫描绕过基线护栏。
- [`tests/tracker/traversalBaseline.test.ts`](../../tests/tracker/traversalBaseline.test.ts) 的内联快照是遍历量回归护栏:结构性优化使数字下降属预期(`vitest run -u` 刷新),无关改动使数字上升需要先解释原因再更新快照。
- DEV 真实回放可通过 `window.__DXC_TRAVERSAL__` 开启长生命周期遍历会话:`start()` 开始新局,`snapshot()` 查看中途累计值,`stop()` 获取最终 JSON 并停止,`reset()` 清空后继续;G0 直接读取快照的 `g0.totals` 与固定五项 `g0.sites`。
- 匿名槽 G0/G1 真实回放已经完成并决定 NO-GO / 收缩;临时浏览器回放探针已退役。历史数据见阶段
0 基线与阶段 1 对照报告。
- 初始牌堆初始化后,`pile.cards` 顺序应独立于 `room.cards`。
- 摸暗牌、摸明牌时手牌额度及状态维护应保持准确。
- 洗牌时协议 `cardCount` 与本地可枚举牌堆不一致属于高风险路径:需要确认匿名暗占位账本、剩余牌堆顶部顺序、暂停追踪候选展示和暗标记账本迁移。
Expand Down Expand Up @@ -267,3 +269,5 @@
- 2026-07-05:完成测试重构与合并,抽取 `locationCandidates` 与 `trackerController` 公共测试辅助,精简测试冗余,提升测试维护性。

- 2026-07-15:文档对齐代码结构——去除文档行号锚点;开局路径以 `handleRecordStartGame` 为主、`GsCModifyUserseatNtf` 分发暂注释;`GameState` 纯状态与 `BrowserGameState` 钩子拆分;视图脏渲染与 `trackerVisibility` 已落地。
- 2026-07-20:匿名牌堆阶段 1 完成;牌堆槽与身份解耦,G1 最终决定 NO-GO / 收缩,阶段
2–7 不执行,临时真实回放探针进入退役范围。
31 changes: 8 additions & 23 deletions docs/agents/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,31 +128,16 @@ CI(`.github/workflows/ci.yml`)在 `dev` / `main` 的 PR 与 push 上会跑
- 远端 `Config_w.sgs` / HTML 资源加载
- 录像 UI 与宿主页面耦合行为

### 真实回放冲突计数
### 匿名槽回放决策记录

阶段 0 的五个匿名占位冲突站点支持 Vite 开发服务器脚本累计采集。通过 `pnpm dev` 安装脚本并打开目标页面后,在 DevTools Console 执行:
匿名槽阶段 0/1 的 G0、G1 回放采集已经结束,最终决定为 NO-GO / 收缩:保留匿名牌堆,不推进
阶段 2–7。临时浏览器回放探针与固定 G0 五站点 schema 已从运行时移除。

```js
window.__DXC_TRAVERSAL__.start()
```

完整播放一局后,用以下命令导出最终快照:

```js
copy(JSON.stringify(window.__DXC_TRAVERSAL__.stop(), null, 2))
```

从 `g0.totals` 和 `g0.sites` 读取五站点累计值;`g0.sites` 会固定输出以下 key,即使没有触发也明确为零:

```text
anonymousSlot:swapKnownCardWithPublicSourcePlaceholder
anonymousSlot:swapKnownCardWithPlayerSourcePlaceholder
anonymousSlot:recoverPlayerOccupiedIdentityForPublicReveal
anonymousSlot:insertUnknownPlaceholderIntoPile
anonymousSlot:createExternalCardsFallback
```

每局应独立保存 JSON,并记录回放来源、局号、采集日期和代码提交。`snapshot()` 可在回放中途查看累计值,`reset()` 可在不关闭会话的情况下开始新的采集段。
历史采集方法与阶段 0 数据保存在
[`anonymous-slot-stage-0-conflict-baseline.md`](../anonymous-slot-stage-0-conflict-baseline.md),阶段 1 三段回放
及最终决策保存在
[`anonymous-slot-stage-1-comparison.md`](../anonymous-slot-stage-1-comparison.md)。通用性能变更仍必须使用
`recordTraversal(...)` 和 `tests/tracker/traversalBaseline.test.ts` 维护自动化遍历护栏。

---

Expand Down
Loading