template/.planning/phases/02-pathfinding/02-01-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	estimate	must_haves
02-pathfinding	01	execute	1		.planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md packages-user/data-common/src/common/mover.test.ts	false	PATH-01 PATH-02	tokens raw_tokens tasks confidence 45000 45000 3 low	truths artifacts key_links assumptions prohibitions 接口草案文档存在，含完整可拍板的签名清单（寻路系统接口、损失函数、回退策略、通行性谓词类型）与文件归属层提案，生产代码零改动 (D-01, D-02, D-03, D-04, D-05, D-06) 草案显式并列 D-08 OnTouch 派发方案 A（直派 executor，构造 IBlockEventEnv）与方案 B（撞击步，注明对 inPass=0 目标不生效）供用户拍板 (D-08) 草案含打断时序两个选项（stop 后 await 兑现 vs onEnd 回调驱动）与图方向性选项（4 向默认 vs 8 向）(D-10) 草案声明本阶段只交付数据端移动入口，渲染端点击接线属 Phase 4 (D-11) mover.ts:651 坐标回写条件缺陷（&& 疑为 ||）的调查结论与 go/no-go 问题已呈现在草案中 (D-07) 执行在本计划末尾的 checkpoint 处停止，用户逐项拍板前不开始任何实现任务 (D-07) .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md packages-user/data-common/src/common/mover.test.ts 02-02 与 02-03 的全部实现任务依赖本计划 checkpoint 的用户拍板结果；拍板修改由执行者逐字应用 PATH-01（flagged assumption，spec-less probe 未分类）：引擎支持自动寻路——本阶段以数据端寻路系统实现且 Node 可验证，覆盖于 02-02/02-03 PATH-02（flagged assumption，spec-less probe 未分类）：移动端点击地图触发自动寻路——本阶段仅交付数据端移动入口供渲染端调用，点击接线按 D-11 延迟至 Phase 4 渲染适配 不得为寻路引入任何新 npm 依赖（零依赖约束，Dijkstra 自写约 40 行） 不得把渲染端点击处理接进数据端代码 (D-11) 未经用户拍板不得实现 D-08 OnTouch 派发方案或 mover.ts:651 修复 (D-07)

为寻路系统产出可拍板的接口草案（含全部待决选项），实证确认 L0 mover.ts:651 坐标回写缺陷并铺设其回归测试脚手架，然后在 checkpoint 处停止，等待用户对接口签名、文件归属、P1 修复 go/no-go、D-08 方案 A/B、打断时序与图方向性逐项拍板。

Purpose: D-07 明锁「AI 起草 → 用户修改拍板后才实现」；本计划是全阶段唯一的 Wave 1，是后续所有实现计划的闸门。 Output: 02-INTERFACE-DRAFT.md（草案 + 决策问题清单）、mover.test.ts 回归脚手架（skip 状态）、用户拍板记录。

<execution_context> @C:/Users/book/.config/opencode/gsd-core/workflows/execute-plan.md @C:/Users/book/.config/opencode/gsd-core/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/02-pathfinding/02-CONTEXT.md @.planning/phases/02-pathfinding/02-RESEARCH.md @.planning/phases/02-pathfinding/02-PATTERNS.md

草案要引用的既有接口面（只读，不修改）

@packages-user/data-common/src/common/mover.ts @packages-user/data-common/src/store/types.ts @packages-user/data-common/src/common/types.ts @packages-user/data-common/src/event/types.ts @packages-user/data-base/src/map/types.ts @packages-user/data-base/src/hero/types.ts @packages-user/data-state/src/hero/moverImpl.ts @dev.md

Task 1: 起草寻路系统接口草案与决策问题清单 .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md packages-user/data-common/src/common/mover.ts, packages-user/data-common/src/store/types.ts, packages-user/data-common/src/common/types.ts, packages-user/data-common/src/event/types.ts, packages-user/data-base/src/map/types.ts, packages-user/data-base/src/hero/types.ts, packages-user/data-state/src/hero/moverImpl.ts, .planning/phases/02-pathfinding/02-RESEARCH.md, .planning/phases/02-pathfinding/02-PATTERNS.md, dev.md 创建 02-INTERFACE-DRAFT.md（中文，含 TS 声明代码块），全部命名标注「DRAFT 待拍板」。内容六节： (1) 接口签名草案——按 dev.md 命名/注释/类型规范书写完整 interface/type 声明：寻路系统主接口（绑定 `IMapLayer` 与 `IObjectMovable` 的 `useXxx()` 注入槽位，per D-03；仅取路径方法 per D-06；逐步/瞬移两种移动方式入口 per D-04；打断入口 per D-10）、损失函数类型（默认每格损失 1，per D-01）、回退策略函数类型（入参为路径及每步到达位置，per D-05）、通行性谓词类型（L2 不 import L3，谓词由 L3 注入，per RESEARCH 分层论证）。绑定面直接引用既有 `IObjectMovable`/`IMapLayer`/`ITileLocator`/`ObjectMoveStep`/`EventTrigger`，勿重定义。 (2) 文件归属提案——L2 `packages-user/data-system/src/pathfinding/`（types/graph/system/index）+ L3 `packages-user/data-state/src/pathfinding/heroPathfinding.ts`（RESEARCH 建议，用户可改）。 (3) D-08 两方案并列——方案 A：到达相邻格后直接构造 `IGameEventInvocation`（trigger=`EventTrigger.OnTouch`，heroLocator=相邻格，triggerLocator=目标格），env 构造逐字复刻 moverImpl.ts:206-222 `commonTrigger` 形态调 `executor.execute`；方案 B：追加朝向目标的撞击步复用 hit 链，并注明 P2 结论——`inPass=0` 真 no-pass 格走 `CannotMove`（`cannotEnter` 为空实现），方案 B 对本场景不生效。推荐 A，由用户拍板 (D-08)。 (4) P1 缺陷调查——逐字引用 mover.ts:651 条件 `this.tile.x !== loc.x && this.tile.y !== loc.y`，给出「正交步永不回写坐标 → 多步寻路自第二步起以陈旧原点计算」的推理链，提出修复为 `||`，列出 go/no-go 问题（若非缺陷须由用户提供替代回写语义）。 (5) 打断时序两选项——选项 1：`stop()` 后 await 兑现再查新位置起新寻路；选项 2：`onEnd` 回调驱动。注明 mover.start() 移动中返回 null（mover.ts:669-670）与 stop 在当前步完成后兑现的语义约束 (D-10)。 (6) 图方向性选项——默认仅 4 正交向（与 PassBit 四位掩码一致，moverImpl canPass 对斜向直接放行不做图边）vs 含 8 向；列利弊供拍板。 禁止在本任务修改任何 packages/ 或 packages-user/ 下的生产代码；草案是唯一交付物（per D-07，实现待拍板）。 if (!(Test-Path ".planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md")) { exit 1 }; $c = Get-Content -Raw ".planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md"; if (!($c -match "IPathfindingSystem")) { exit 1 }; if (!($c -match "方案 A")) { exit 1 }; if (!($c -match "方案 B")) { exit 1 }; if (!($c -match "mover\.ts:651")) { exit 1 } 命令以退出码 1 结束——草案文件不存在，或正文中找不到 IPathfindingSystem 签名、D-08 方案 A/B 并列、或 mover.ts:651 缺陷引用任一项 - 草案文件存在且含完整 interface/type 声明代码块，覆盖绑定槽位、仅取路径、两种移动方式、打断入口（行为断言） - D-08 方案 A 与方案 B 同时出现且各有语义说明与推荐标注（行为断言） - P1 缺陷含逐字代码引用、推理链与 go/no-go 问题（行为断言） - 生产源码目录无任何本任务改动：`git status --porcelain packages-user packages` 输出为空（CLI 断言） 02-INTERFACE-DRAFT.md 完整覆盖六节内容，生产代码零改动。 Task 2: 铺设 L0 mover 坐标回写回归测试脚手架（skip 状态） packages-user/data-common/src/common/mover.test.ts packages-user/data-common/src/common/mover.ts, packages-user/data-system/src/event/eventDispatch.test.ts, packages-user/data-common/src/store/types.ts, dev.md 新建 L0 回归测试文件，完整编写 4 个用例但以 `it.skip` 状态提交（套件保持绿色，待 02-02 修复后翻绿）：(a) 正交步（仅 x 变化）后 `setPos` 回写 x；(b) 正交步（仅 y 变化）后回写 y；(c) 斜向步后双轴回写；(d) 传送步（`ObjectMoveType.Teleport`）后双轴回写。测试桩逐字复刻 eventDispatch.test.ts:19-33 模式：`vi.hoisted` 内 `vi.stubGlobal('main', { replayChecking: true })` 与 `vi.stubGlobal('location', { origin: 'http://localhost' })`、`Map.prototype.getOrInsertComputed` polyfill、动态 import 被测模块。每个 `it` 前必须有单行中文注释说明覆盖内容（dev.md 硬规则）；CRLF 换行；普通引入无 `import type`。用例构造最小 ObjectMover 子类驱动 `moveProgress` 所需的步骤与钩子，不引入任何新依赖。本任务不改 mover.ts 生产代码——缺陷修复属 02-02，须经用户 go/no-go（D-07）。 pnpm exec vitest run "packages-user/data-common/src/common/mover.test.ts" vitest 输出出现 "failed" 字样或非零退出码；或 4 个用例未以 skipped 状态出现（说明 skip 脚手架写错导致用例实际执行并失败） - 测试文件存在且含 4 个 skip 用例，分别覆盖 x 正交、y 正交、斜向、传送步的坐标回写（行为断言） - 测试桩包含 main.replayChecking stub、location stub 与 getOrInsertComputed polyfill（行为断言） - `git status --porcelain packages-user/data-common/src/common/mover.ts` 输出为空——生产代码未被修改（CLI 断言） mover.test.ts 以 4 个 skip 用例通过 vitest（0 failed），生产代码零改动。 Task 3: 用户拍板接口草案与全部待决选项（D-07 关卡） .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md 停止执行，向用户逐项呈现并等待拍板（用户可直接编辑草案文件，执行者须逐字应用其修改）： 1. 接口签名清单——主接口命名、方法签名、注入槽位命名、损失/回退/谓词函数类型签名（D-01…D-06 的接口面）； 2. 文件归属层——L2/L3 文件放置提案或用户调整； 3. P1 修复 go/no-go——mover.ts:651 条件是否确认为缺陷并授权改为 `||`（若否，用户提供替代坐标回写语义）； 4. D-08 OnTouch 派发——方案 A（直派 executor）或方案 B（撞击步）； 5. 打断时序——stop 后 await 兑现，或 onEnd 回调驱动； 6. 图方向性——仅 4 正交向，或含 8 向。 将用户每项决定（含「按草案原样」）追加记录到草案文件末尾「拍板记录」节。未获全部六项拍板前，不得开始 02-02/02-03 的任何实现任务。 寻路系统接口草案（含签名清单、文件归属、D-08 两方案、P1 go/no-go、打断时序、图方向性六项待决事项）已就绪，等待用户逐项拍板 阅读 .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md 全文，对文中六个决策项逐一给出结论（可直接编辑草案文件修改签名/命名/归属，执行者将逐字应用） 逐项回复六项决策结论（或「按草案原样」），或直接修改草案文件后回复 approved $c = Get-Content -Raw ".planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md"; if (!($c -match "拍板记录")) { exit 1 }; if (!($c -match "go/no-go")) { exit 1 }; if (!($c -match "方案 [AB]")) { exit 1 } 命令以退出码 1 结束——草案文件末尾没有「拍板记录」节，或六项决策中任一项缺少用户的明确结论 - 用户对六项决策（接口签名、文件归属、P1 go/no-go、D-08 方案、打断时序、图方向性）各给出明确结论（人工确认） - 拍板记录节完整记录每项结论及用户对草案的直接修改（行为断言） 六项决策全部经用户拍板并记录在案，02-02/02-03 可依拍板结果执行。

<threat_model>

Artifacts this phase produces

• .planning/phases/02-pathfinding/02-INTERFACE-DRAFT.md — 接口草案文档（含 IPathfindingSystem 等全部草案 interface/type 声明、文件归属提案、D-08 两方案、P1 调查、打断时序与图方向性选项、拍板记录节）
• packages-user/data-common/src/common/mover.test.ts — L0 坐标回写回归测试（4 个 skip 用例脚手架；02-02 翻绿）
• 本计划不新建任何生产符号（D-07：拍板前零实现）

Trust Boundaries

Boundary	Description
地图/存档数据 → 寻路图构建	不可信或损坏的地图数据（越界坐标、缺失图层、畸形掩码）将进入图构建与搜索（02-02/02-03 消费）

STRIDE Threat Register

Threat ID	Category	Component	Severity	Disposition	Mitigation Plan
T-02-01	Tampering/DoS	图构建入口（02-02 graph.ts）	medium	mitigate	草案中明确边界守卫要求：IMapLayer.inMap 守卫 + isNil 判空 + 非法输入 logger.warn 数字码后返回空路径（本任务落草案，实现落 02-02）
T-02-02	Tampering	自定义损失函数（02-02 system.ts）	medium	mitigate	草案中明确损失值守卫：非有限数/负数 → logger.warn 新码并按默认损失 1 处理（实现落 02-02）
T-02-SC	Tampering	npm/pip/cargo installs	low	accept	本阶段零新依赖（RESEARCH Package Legitimacy Audit：无安装对象），无供应链面
</threat_model>

- 草案文件存在且六节齐备，D-08 两方案、打断时序、图方向性均已并列呈现 - mover.test.ts 4 用例 skip 通过，生产代码零改动 - 「拍板记录」节含全部六项用户结论

<success_criteria> 用户在 checkpoint 处完成六项拍板；接口草案与 P1 调查成为 02-02/02-03 的执行依据；本计划全程未修改任何生产代码。 </success_criteria>

Create `.planning/phases/02-pathfinding/02-01-SUMMARY.md` when done