mirror of
https://github.com/motajs/template.git
synced 2026-10-30 21:30:17 +08:00
docs(10-31..10-32): 收尾高级 I 补写（Mover + FaceHandler）
- 记录用户最终确认：通过（两篇补写内容与导览三轮用户循环收敛） - 写 10-31-SUMMARY：读者审阅 4 个阻断问题消除、复审 9 个非阻断项落地、阻断性问题 = 0 - 写 10-32-SUMMARY：用法优先重构（D-77）、系统模型与元信息清理（D-79..D-82）、模板/需改移除（D-83） - 审阅记录补复审收敛结论、D-72 差异报告与收尾构建结论
This commit is contained in:
parent
6846c211c7
commit
3dd91a8654
@ -95,3 +95,35 @@
|
||||
|
||||
- `pnpm exec prettier --write docs/advanced/mover.md docs/advanced/face-handler.md docs/advanced/index.md`：通过（mover、index 有格式变动）。
|
||||
- `pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build`：`build complete in 19.98s`，无 dead link 报错。
|
||||
|
||||
## 复审收敛结论（收尾）
|
||||
|
||||
对照首轮清单、第 1 轮修复记录、第 2 轮复审表与两篇正文现状，逐条核对结论如下。
|
||||
|
||||
| # | 首轮问题 | 复审结论 | 依据 |
|
||||
| --- | --- | --- | --- |
|
||||
| B-01 | `start()` 返回 `null` 时该等谁、该停谁 | 已消除 | 「边界与注意」只用上一次 `start()` 保存的 `controller` 等 `onEnd` 或对它 `stop()`，写明 `IHeroMover` 没有 `stop()`；返回 `null` 时队列未被消费也一并说明 |
|
||||
| B-02 | 勇士 `useTopImplementation` 缺契约与示例 | 已消除 | 「勇士的顶层实现」列出 `IHeroMoveTopImpl` 六个方法与 `IHeroMoveTopHandler` 携带的字段，说明与 `DefaultHeroMoveTopImpl` 的关系，并给出包装默认实现的完整类 |
|
||||
| B-03 | `MapTileBase.setFaceDirection` 的降级语义与源码不一致 | 已消除 | 第 1 轮按方法注释口径改写；第 2 轮按 D-80 把实现差异移出正文，正文只留使用结论 |
|
||||
| B-04 | `Dir4FaceHandler.dirOf` 遍历八方向表 | 已消除 | 正文不再断言 Dir4 只返回上下左右；`dirOf` 收敛为「实现特例，可复现但不是接口承诺，不能用于四方向判定」 |
|
||||
|
||||
- 非阻断项：首轮 13 项已全部在正文落地（见第 1 轮修复记录）；第 2 轮复审另提 9 项，全部已处理（见第 2 轮表格）。复审未新增阻断项。
|
||||
- 覆盖自查：两篇仍覆盖 D-75 要求的内容——移动三件套、步骤类型、控制器、钩子、`degrade` / `next` / `opposite` / `mapMovement`、`IRoleFaceBinder`、`useTopImplementation` 均仍在正文中。
|
||||
- 无「仍存在」的阻断项。
|
||||
|
||||
**阻断性问题 = 0，审阅通过**
|
||||
|
||||
**未复用中级人格**：本记录全程使用上文的高级 I 人格提示词（假设读者已读完中级教程、正在阅读高级教程 I），未复用 `10-11-READER-REVIEW.md` 的中级教程人格（该人格「不懂代码」，与本篇的前提不同）。
|
||||
|
||||
### D-72 源码 / 注释差异（只在对话中报告，正文不保留）
|
||||
|
||||
按 D-80，正文不写实现与注释的差异；以下三项在执行期间向用户报告过，未写进 `mover.md` / `face-handler.md`：
|
||||
|
||||
1. `MapTileBase.setFaceDirection`：注释描述「降级后查到映射就换图」，实现降级分支只返回 `next.identifier`，未写回图块。
|
||||
2. `Dir4FaceHandler.dirOf`：遍历 `DIR8_MOVEMENTS`，`dirOf(1, 1)` 返回 `RightDown`；接口注释未承诺只返回本组方向。
|
||||
3. `Dir8FaceHandler.degrade`：原样返回入参，`degrade(999)` 为 `999`，与接口注释「无法降级时返回 `Unknown`」不一致。
|
||||
|
||||
### 收尾构建
|
||||
|
||||
- `node node_modules/prettier/bin/prettier.cjs --write docs/advanced/mover.md docs/advanced/face-handler.md`：两篇均 `unchanged`。
|
||||
- `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`：退出码 0，`build complete in 14.31s`，无 dead link。
|
||||
|
||||
171
.planning/phases/10-docs-restructure/10-31-SUMMARY.md
Normal file
171
.planning/phases/10-docs-restructure/10-31-SUMMARY.md
Normal file
@ -0,0 +1,171 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 31
|
||||
subsystem: docs
|
||||
tags: [vitepress, markdown, advanced-i, mover, face-handler, reader-review, persona]
|
||||
|
||||
requires:
|
||||
- phase: 10-docs-restructure
|
||||
provides: 10-30 已接入导览与侧边栏的 docs/advanced/mover.md 与 docs/advanced/face-handler.md
|
||||
- phase: 10-docs-restructure
|
||||
provides: 10-19 已获用户确认的高级 I 读者人格提示词（D-57，逐字沿用）
|
||||
provides:
|
||||
- 两篇补写内容经独立读者审阅收敛：首轮 4 个阻断问题全部消除，复审无遗留阻断项
|
||||
- .planning/phases/10-docs-restructure/10-31-READER-REVIEW.md：人格、首轮清单、两轮修复与复审、收敛结论与结束标记
|
||||
- 两篇文档在阻断问题处的实质补写（start 返回 null 的等待入口、勇士顶层实现契约、Dir4 的 dirOf 口径）
|
||||
affects: [10-32 user revision loop]
|
||||
|
||||
actuals:
|
||||
tokens: 10306
|
||||
tasks: 4
|
||||
commits: 2
|
||||
plan_head_before: f317446aa7d3532c4d8a87e73c8c0afd8765fab1
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- 补写内容走「独立读者子代理 → 问题清单 → 迭代 → 复审」的固定链路（D-46 第 1 阶段 / D-57）
|
||||
- 阻断性口径：读者据此无法完成操作，或会对执行时序、状态归属、两层朝向模型产生实质误解
|
||||
- 实现与注释不一致时以注释语义为准（D-72），差异只报告、不写进正文（D-80）
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- .planning/phases/10-docs-restructure/10-31-READER-REVIEW.md
|
||||
- .planning/phases/10-docs-restructure/10-31-SUMMARY.md
|
||||
modified:
|
||||
- docs/advanced/mover.md
|
||||
- docs/advanced/face-handler.md
|
||||
- docs/advanced/index.md
|
||||
|
||||
key-decisions:
|
||||
- B-03 / B-04 按注释与接口语义改写正文，源码与注释的差异按 D-72 只在对话中报告，不写进正文
|
||||
- 首轮 13 个非阻断项中与「照做会不会卡住」直接相关的（异常路径、`config` / `speed` / `animDir` 持久性、`push` 形状差异、`mapMovement` 的 `Unknown` 零偏移）全部落到正文，其余只记录
|
||||
- 迭代两轮即收敛（第 1 轮修 4 个阻断 + 13 个非阻断，第 2 轮复审再修 9 个非阻断），未触及 3 轮上限
|
||||
- 复审人格逐字沿用 10-19 已确认提示词，未复用 `10-11-READER-REVIEW.md` 的中级教程人格
|
||||
|
||||
patterns-established:
|
||||
- 读者审阅记录的结构：人格逐字 → 首轮清单（阻断 / 非阻断分类 + 文件章节定位）→ 每轮修复表 → 复审对照 → 结束标记 → 构建结论
|
||||
- 审阅对象包含「两篇在导览与侧边栏中的接入方式」，不只正文
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: 两篇补写内容完成独立读者审阅，首轮 4 个阻断问题全部消除，复审无遗留阻断项
|
||||
verification:
|
||||
- kind: other
|
||||
ref: '10-31-READER-REVIEW.md 的「复审收敛结论」表与结束标记「阻断性问题 = 0，审阅通过」'
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: 两篇与导览仍可构建、无死链、CRLF 单 H1 无渲染端内容，D-75 要求的内容未被读者提问削掉
|
||||
verification:
|
||||
- kind: other
|
||||
ref: 'pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build（build complete in 14.31s，无 dead link）与 prettier --check'
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: 目标读者「照着文档能排出一次移动、换一个朝向处理器、取到朝向图块」的可操作性
|
||||
verification: []
|
||||
human_judgment: true
|
||||
rationale: 可读性与「照做能否成功」是判断，只能由目标读者与用户主导的修订循环确认；自动化只能保证结构、链接与构建
|
||||
|
||||
duration: 约 35 分钟（跨两次会话）
|
||||
completed: 2026-10-24
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 10 Plan 31: 高级 I 补写（Mover / FaceHandler）读者审阅 Summary
|
||||
|
||||
**用 10-19 已确认的高级 I 人格对 `mover.md` / `face-handler.md` 做独立读者审阅：首轮 4 个阻断问题（`start` 返回 `null` 的等待入口、勇士顶层实现契约、`setFaceDirection` 降级语义、`dirOf` 八方向特例）全部消除，复审再收 9 个非阻断项，最终阻断性问题 = 0。**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 约 35 分钟（跨两次会话：首轮修复 + 复审）
|
||||
- **Started:** 2026-10-24（本会话）
|
||||
- **Completed:** 2026-10-24
|
||||
- **Tasks:** 4/4（Task 0 汇报关卡已获用户「可以执行」）
|
||||
- **Files modified:** 3 篇文档 + 1 份审阅记录 + 本 SUMMARY
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- 派发独立读者子代理（不与执行者共享上下文），逐字沿用 10-19 已确认的高级 I 人格提示词，通读两篇及其在导览 / 侧边栏中的接入方式，产出 4 个阻断 + 13 个非阻断问题清单，逐条定位到文件与章节。
|
||||
- 4 个阻断问题全部在正文落地解决：
|
||||
- `start()` 返回 `null` 时没有新控制器，只能用上一次 `start()` 保存的 `controller` 等 `onEnd` 或 `stop()`，并写明 `IHeroMover` 没有 `stop()`。
|
||||
- 新增「勇士的顶层实现」：`IHeroMoveTopImpl` 六方法、`IHeroMoveTopHandler` 字段、与 `DefaultHeroMoveTopImpl` 的关系，以及包装默认实现的完整类。
|
||||
- `setFaceDirection` 按方法注释口径描述降级语义，并报告与实现的差异。
|
||||
- 正文不再断言 `Dir4` 只返回上下左右，`dirOf` 收敛为「实现特例，不能用于四方向判定」。
|
||||
- 复审（第 2 轮）另提 9 个非阻断项并全部处理：`predicate()` / `IPassPredicate` 独立成节、`start()` 返回 `null` 时队列仍留在移动器、异常后无恢复路径、`prepareStep` 与受保护成员边界、自定义分组的键与 `const enum`、`dirOf` 内置特例统一口径、`cannotEnter(handler)` 签名、`@shouldReplay` 标记位置、导览主要主题补两篇。
|
||||
- 结论记录为「阻断性问题 = 0，审阅通过」，并保留「未复用中级人格」标记与 D-72 三项源码 / 注释差异（只在对话中报告）。
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1 + Task 2（首轮）：记录读者问题清单并修复 4 个阻断项 + 13 个非阻断项** - `b243c51`（docs）
|
||||
2. **Task 3（复审）：修复复审提出的 9 个非阻断项** - `73d1a04`（docs）
|
||||
|
||||
**Plan metadata:** 由 10-32 收尾提交统一带走（本 SUMMARY 与 10-32-SUMMARY 同一次提交）。
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `.planning/phases/10-docs-restructure/10-31-READER-REVIEW.md` — 人格逐字、首轮清单、两轮修复表、复审收敛结论、结束标记、构建结论
|
||||
- `docs/advanced/mover.md` — 移动器模型细化、拿到移动器的三种来源、`predicate()` 与 `IPassPredicate`、异常路径与恢复边界、勇士顶层实现契约与示例、验证改为四步计划
|
||||
- `docs/advanced/face-handler.md` — 朝向模型、`get` 泛型与分组键、`dirOf` 口径收敛、重复 `malloc` 与 `mapMovement` 的 `Unknown` 零偏移、六边形自定义示例的前置
|
||||
- `docs/advanced/index.md` — 「目标双端覆盖、当前只写数据端」的统一表述，阅读路径与「读完这一层」补入两篇
|
||||
- `.planning/phases/10-docs-restructure/10-31-SUMMARY.md` — 本执行总结
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **D-72 差异只报告不落正文**：`setFaceDirection` 降级分支未写回图块、`Dir4FaceHandler.dirOf` 遍历八方向表、`Dir8FaceHandler.degrade(999)` 返回 `999` 三处，按注释语义写正文，差异在审阅记录与对话中报告（后经 D-80 进一步要求正文不写实现差异）。
|
||||
- **阻断性判定口径**：读者据此无法完成操作，或会对执行时序、状态归属、两层朝向模型产生实质误解；「最大非阻断缺口」（自定义 mover / handler 接进插件与真实对象的生命周期）留在非阻断组，不擅自扩为正文主题。
|
||||
- **迭代未用满上限**：两轮收敛，第 1 轮修阻断、第 2 轮复审只余非阻断，未出现「阻断性问题余项：已交用户」的分支。
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - 缺失关键说明] 复审时补 `predicate()` / `IPassPredicate` 独立一节**
|
||||
- **Found during:** Task 3（复审）
|
||||
- **Issue:** 原文只在顶层实现示例里顺带出现 `canPass` / `shouldHit`，读者不知道判定顺序、字段名与「寻路要单独注入谓词」。
|
||||
- **Fix:** 新增「改通行规则：`predicate()` 与 `IPassPredicate`」，讲职责、`IPassCheckHandler` 字段、判定顺序、`ignoreTerrain` 的副作用与谓词实例稳定性。
|
||||
- **Files modified:** `docs/advanced/mover.md`
|
||||
- **Verification:** 构建 green、无死链；复审记录第 2 轮表格第 1 条
|
||||
- **Committed in:** `73d1a04`
|
||||
|
||||
**2. [Rule 2 - 缺失关键说明] 异常路径与「无恢复入口」写进边界**
|
||||
- **Found during:** Task 2 / Task 3
|
||||
- **Issue:** 钩子或步进方法抛错后 `onEnd` 不兑现、`moving` 恒真、后续 `start()` 恒 `null`，读者会把「已经卡死」误当成「正在移动」。
|
||||
- **Fix:** 「边界与注意」写明成因、后果与唯一处置（重建数据端），并建议把预期失败转成结果码。
|
||||
- **Files modified:** `docs/advanced/mover.md`
|
||||
- **Verification:** 复审记录第 2 轮表格第 3 条；构建 green
|
||||
- **Committed in:** `73d1a04`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed（均属读者「照做会卡住」类，Rule 2）
|
||||
**Impact on plan:** 都属于计划允许的「消除阻断 / 高危非阻断问题」，未扩大章节范围，未触碰 `config.ts` 与其它正文。
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- 本计划两次提交的区间内，`docs/advanced/ii/static-vs-dynamic-tiles.md` 有一笔链接改动（来自 10-30 的收口提交），不属于本计划的审阅对象。
|
||||
- 工作区有与本计划无关的既有改动（`packages-user/*`、`src/client/*`、`.planning/.../09-*` 等），全程未暂存、未提交。
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - 无外部服务配置。
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- 阻断问题清零，10-32 可以进入用户主导的修订循环（D-46 第 2 阶段），不需要先回头补文档。
|
||||
- 非阻断残项已在记录中保留，是否处理交给 10-32 的用户循环决定。
|
||||
- 两篇在审阅后仍 kebab-case、CRLF、单 H1，构建 green、dead link = 0。
|
||||
|
||||
---
|
||||
|
||||
_Phase: 10-docs-restructure_
|
||||
_Completed: 2026-10-24_
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- 文件存在：`.planning/phases/10-docs-restructure/10-31-READER-REVIEW.md`、`docs/advanced/mover.md`、`docs/advanced/face-handler.md`、`docs/advanced/index.md`、`.planning/phases/10-docs-restructure/10-31-SUMMARY.md`
|
||||
- 提交存在：`b243c51`（首轮修复）、`73d1a04`（复审修复）
|
||||
- 门禁存在：REVIEW-OK（人格逐字 + 未复用中级人格）、阻断性问题 = 0、prettier unchanged、`build complete`、无 dead link
|
||||
197
.planning/phases/10-docs-restructure/10-32-SUMMARY.md
Normal file
197
.planning/phases/10-docs-restructure/10-32-SUMMARY.md
Normal file
@ -0,0 +1,197 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 32
|
||||
subsystem: docs
|
||||
tags: [vitepress, markdown, advanced-i, mover, face-handler, user-review, usage-first]
|
||||
|
||||
requires:
|
||||
- phase: 10-docs-restructure
|
||||
provides: 10-31 已消除独立读者阻断问题的 docs/advanced/mover.md 与 docs/advanced/face-handler.md
|
||||
provides:
|
||||
- 两篇补写内容改为「用法优先」结构：先讲系统模型，再讲怎么拿、怎么用，自定义压到末尾
|
||||
- 用户主导修订循环三轮收敛（D-77、D-79..D-82、D-83），最终确认「通过」
|
||||
- .planning/phases/10-docs-restructure/10-32-USER-REVIEW.md：逐轮用户意见、落点、处置、最终确认与收尾记录
|
||||
affects: [10 phase close-out]
|
||||
|
||||
actuals:
|
||||
tokens: 25764
|
||||
tasks: 5
|
||||
commits: 3
|
||||
plan_head_before: 73d1a04fbe02ba25cbfc6ec1e70377282074534e
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- 教程正文「用法优先」：能做什么 → 怎么拿到 → 怎么用 → 用在哪里 → 自定义（末尾一两节）
|
||||
- 系统类文档先给「系统模型」再给接口与用法（D-82），模型节只讲有哪些角色与两条数据流
|
||||
- 正文不写使用概率元信息、源码路径、实现与注释差异、也不写「用户问过什么」（D-79 / D-80 / D-81）
|
||||
- 教程不出现「模板」「[需改]」标记；提示只写成注释说明下一行做什么（D-83）
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- .planning/phases/10-docs-restructure/10-32-USER-REVIEW.md
|
||||
- .planning/phases/10-docs-restructure/10-32-SUMMARY.md
|
||||
modified:
|
||||
- docs/advanced/mover.md
|
||||
- docs/advanced/face-handler.md
|
||||
- docs/advanced/index.md
|
||||
- docs/advanced/ii/adding-enemy-attribute.md
|
||||
- docs/advanced/ii/adding-hero-attribute.md
|
||||
- docs/advanced/hooks-in-depth.md
|
||||
- docs/advanced/plugin-system.md
|
||||
- docs/advanced/declarative-vs-imperative.md
|
||||
- docs/advanced/replay-consistency.md
|
||||
- docs/advanced/saveable-content.md
|
||||
- docs/advanced/data-stores.md
|
||||
|
||||
key-decisions:
|
||||
- 文档重心是「怎么用」：`mover.md` 把「拿到现成的移动器」提到第 2 节，自定义压到末尾 2 节；`face-handler.md` 同理压到 1 节（D-77）
|
||||
- 两篇先讲系统模型再讲接口（D-82）：`移动器模型` 与 `朝向模型` 各占首节，只讲角色与数据流，不展开实现
|
||||
- 朝向组的自定义示例改为六边形布局（六个邻接方向），因为需要自定义的真实场合是「坐标系不是方格」，而非「斜向归并不同」
|
||||
- 删除正文中的使用概率、源码路径、实现 / 注释差异与「用户问题」框架（D-79..D-82）；这些差异只留在审阅记录与对话里
|
||||
- 高级教程移除「模板」「[需改]」标记，但保留游戏领域术语「怪物模板 / 原始模板 / 默认模板」（D-83）
|
||||
|
||||
patterns-established:
|
||||
- 用户修订循环的记录结构：轮次 → 用户意见 → 条目表（落点 / 处置 / 状态）→ 执行记录 → 验证
|
||||
- 收尾只认独占一行的 `用户最终确认：通过`，且条目级 `状态：待处理` 必须为 0
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: 两篇补写内容按用法优先重构，正文约一半是高概率用法章节，自定义仅末尾一两节
|
||||
verification:
|
||||
- kind: other
|
||||
ref: '10-32-USER-REVIEW.md 第 1 轮执行记录（章节顺序与行数变化）与 D-77 / D-78 自评'
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: 两篇先讲系统模型；正文无使用概率、源码路径、实现差异与用户问题框架；模板 / 需改标记清除
|
||||
verification:
|
||||
- kind: other
|
||||
ref: '10-32-USER-REVIEW.md 第 2 / 3 轮条目表（M1、M2、F1、F2、F3 与全量标记清理）'
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: 最终产物可构建、可预览、无死链、结构正确，用户明确确认通过
|
||||
verification:
|
||||
- kind: other
|
||||
ref: 'pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build（build complete in 14.31s，无 dead link）＋ prettier --check ＋ 用户最终确认：通过'
|
||||
status: pass
|
||||
human_judgment: true
|
||||
rationale: 「通过」是用户对本领域内容的判断，按 D-46 第 2 阶段只能由用户给出；自动化只能保证构建、格式、结构与链接
|
||||
|
||||
duration: 约 60 分钟（跨三轮循环）
|
||||
completed: 2026-10-26
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 10 Plan 32: 高级 I 补写（Mover / FaceHandler）用户修订循环 Summary
|
||||
|
||||
**把两篇补写内容从「怎么自定义」翻成「怎么用」：`mover.md` 先把移动器模型与「拿到现成移动器」前置（775 → 533 行）、`face-handler.md` 先讲朝向模型与取用（447 → 356 行），自定义压到末尾一两节；三轮用户意见收敛，用户最终确认「通过」。**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 约 60 分钟（三轮用户意见 + 收尾）
|
||||
- **Started:** 2026-10-24（本会话首轮）
|
||||
- **Completed:** 2026-10-26（收尾）
|
||||
- **Tasks:** 5/5（Task 0 / Task 1 / Task 3 的汇报与确认关卡均已获用户明确回复）
|
||||
- **Files modified:** 两篇主体 + 导览 + 高级 I / II 共 8 篇标记清理 + 审阅记录 + 本 SUMMARY
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- **第 1 轮 · 用法优先重构（D-77）**：用户指出重心应是「怎么使用」而不是「怎么自定义」——游戏里需要自定义移动器 / 朝向组的概率几乎为 0。
|
||||
- `mover.md`（775 → 525 行）：新顺序为 能做什么 → 拿到移动器（勇士 `state.hero.location.mover`、动态图块 `tile.mover`、如何取到动态图块）→ 排计划 → 开始与等待（`start` → `IMoverController` → `onEnd`）→ 执行中控制 → 勇士配置 → 钩子 → 读取与设置状态 → 自定义（2 节）→ 边界 → 验证；删掉独立的「内部执行流程」整节与三段装配示例。
|
||||
- `face-handler.md`（447 → 350 行）：新顺序为 三个概念 → 拿到处理器（`get` / `getById` + 判空）→ 常用方法 → 用在哪里（移动器 / 寻路、图块朝向、`roleFace` 映射）→ 内置 Dir4 / Dir8 → 自定义（1 节）→ 边界 → 验证。
|
||||
- **第 2 轮 · 系统模型与元信息清理（D-79..D-82）**：先讲系统模型再讲接口；删除正文中的使用概率、源码叙述、实现 / 注释差异与「用户问题」框架。
|
||||
- `mover.md` 新增首节「移动器模型」（可移动对象、移动计划、执行与控制器、面朝 / 移动两个方向，接口分工表并入）。
|
||||
- `face-handler.md` 首节改为「朝向模型」，补齐 `IFaceDescriptor` 与 `IRoleFaceBinder`，先讲移动与显示两条数据流。
|
||||
- 自定义示例改为六边形布局 `HexFaceHandler`（六个邻接方向、字符串 id `hex`），理由是需要自定义的真实场合是坐标系不是方格。
|
||||
- **第 3 轮 · 模板 / 需改标记移除（D-83）**：清除全部 `[需改]` 与「模板」措辞，提示改为注释说明下一行做什么；保留游戏领域术语「怪物模板 / 原始模板 / 默认模板」。
|
||||
- **收尾**：用户确认「可以，整体没有问题」→ 记录 `用户最终确认：通过`；两篇 prettier `unchanged`，最终构建 `build complete in 14.31s`、无 dead link；侧边栏高级 I 仍 9 个目标。
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **第 1 轮：重构 Mover / FaceHandler 为用法优先（D-77）** - `c0b3e58`（docs）
|
||||
2. **第 2 轮：补系统模型并清理元信息（D-79..D-82）** - `f4edda6`（docs）
|
||||
3. **第 3 轮：移除高级教程模板 / 需改标记（D-83）** - `6846c21`（docs）
|
||||
|
||||
**Plan metadata:** 收尾提交 `docs(10-31..10-32): 收尾高级 I 补写（Mover + FaceHandler）`（含本 SUMMARY、10-31-SUMMARY 与两份审阅记录的最终确认）
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `docs/advanced/mover.md` — 用法优先重排（533 行）、移动器模型、拿到移动器的三种来源、执行中控制、勇士配置与钩子用法、自定义压到末尾两节
|
||||
- `docs/advanced/face-handler.md` — 用法优先重排（356 行）、朝向模型（五个组件 + 两条链路）、取用与八个常用方法、用在哪里、六边形自定义示例
|
||||
- `docs/advanced/index.md` — 「高级 I · 扩展基础」主要主题补入「移动 Mover、FaceHandler 系列」，与九篇清单一致
|
||||
- `docs/advanced/hooks-in-depth.md`、`plugin-system.md`、`declarative-vs-imperative.md`、`replay-consistency.md`、`saveable-content.md`、`data-stores.md` — 模板措辞清理（D-83）
|
||||
- `docs/advanced/ii/adding-enemy-attribute.md`、`ii/adding-hero-attribute.md` — `[需改]` 标记移除（D-83）
|
||||
- `.planning/phases/10-docs-restructure/10-32-USER-REVIEW.md` — 三轮用户意见、处置表、执行记录、最终确认与收尾记录
|
||||
- `.planning/phases/10-docs-restructure/10-32-SUMMARY.md` — 本执行总结
|
||||
|
||||
## 三轮用户循环的处置摘要
|
||||
|
||||
| 轮次 | 用户意见 | 落点 | 处置 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 重心应是「怎么用」，自定义概率几乎为 0 | 两篇整体结构 | 用法优先重排；自定义压到 `mover.md` 末尾 2 节、`face-handler.md` 末尾 1 节 |
|
||||
| 2 | 先讲系统模型再讲接口；删使用概率 / 源码叙述 / 用户问题框架；朝向示例改六边形 | 两篇首节 + 全文 + 自定义节 | M1 / M2 / F1 / F2 / F3 全部 `状态：已处理` |
|
||||
| 3 | 高级教程不写「模板」「[需改]」 | 高级 I / II 共 8 篇 | 全部标记清除；游戏领域术语保留 |
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **D-77 / D-78**：文档重心是「怎么用」；写作与审阅都要自问每个章节的使用概率，通篇低概率说明文档不好。
|
||||
- **D-79 / D-80 / D-81**：正文不写「使用概率很低」这类元信息、不写源码路径与实现差异、不把「用户问过什么」写进文档；差异只留在审阅记录与对话。
|
||||
- **D-82**：讲一个系统时先讲系统模型（有哪些角色、怎么组成、两条链路），再讲接口与用法。
|
||||
- **D-83**：高级教程不出现「模板」「[需改]」标记或模板章节，提示只写成注释；游戏领域术语不在此列。
|
||||
- 收尾只认独占一行的 `用户最终确认：通过`；AI 未自行宣布完成。
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - 缺失关键内容] `mover.md` 补「勇士排好计划也不一定真走」的用法提示**
|
||||
- **Found during:** 第 1 轮重排
|
||||
- **Issue:** 通行失败时 `HeroMover` 会调用 `controller.stop()`，重排后若只讲 `start` / `onEnd`，读者会以为 `onEnd` 一定对应「走到了」。
|
||||
- **Fix:** 在用法区补一句：通行失败时移动由 `HeroMover` 提前 `stop` 收尾，`onEnd` 只表示整次结束。
|
||||
- **Files modified:** `docs/advanced/mover.md`
|
||||
- **Verification:** 构建 green、无死链；用户第 2 轮未再就此提问
|
||||
- **Committed in:** `c0b3e58`
|
||||
|
||||
**2. [Rule 2 - 缺失关键内容] 导览主要主题与九篇清单对齐**
|
||||
- **Found during:** 10-31 复审
|
||||
- **Issue:** 导览分层表「高级 I · 扩展基础」的主要主题漏了新增两篇。
|
||||
- **Fix:** 主要主题补入「移动 Mover、FaceHandler 系列」。
|
||||
- **Files modified:** `docs/advanced/index.md`
|
||||
- **Verification:** 与「高级 I 包含什么」篇目表一致；构建 green
|
||||
- **Committed in:** `73d1a04`（10-31）
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed（均属内容正确性，Rule 2）
|
||||
**Impact on plan:** 只补说明与对齐，未改结构、未扩大章节、未触碰 `config.ts` 与渲染端内容。
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- 第 3 轮按 D-83 清理标记时波及的篇目多于本计划 `files_modified` 的字面范围（`hooks-in-depth.md`、`plugin-system.md`、`declarative-vs-imperative.md`、`replay-consistency.md`、`saveable-content.md`、`data-stores.md` 与两篇属性篇），均为用户在同一条意见中点名的「高级教程」范围，已在审阅记录里逐篇列出。
|
||||
- 第 1 轮记录的标题保留为「（2026-10-24，待执行）」，其末尾保留原有一处 `\*\*`；均为历史文本，未改动。
|
||||
- 工作区有与本计划无关的既有改动（`packages-user/*`、`src/client/*`、`.planning/.../09-*` 与 `10-CONTEXT.md`），收尾提交未暂存它们。
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - 无外部服务配置。
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- 高级 I 九篇在站点上可浏览、可预览，两篇新页从导览篇目表、继续阅读与侧边栏三处进入。
|
||||
- D-09 的人工验收依据齐备：审阅记录 + 最终确认 + 构建产物。
|
||||
- 无待处理项；遗留的只有用户明确不实施的越界内容与按 D-75 保留的低概率示例。
|
||||
|
||||
---
|
||||
|
||||
_Phase: 10-docs-restructure_
|
||||
_Completed: 2026-10-26_
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- 文件存在：`docs/advanced/mover.md`、`docs/advanced/face-handler.md`、`docs/advanced/index.md`、`.planning/phases/10-docs-restructure/10-32-USER-REVIEW.md`、`.planning/phases/10-docs-restructure/10-32-SUMMARY.md`
|
||||
- 提交存在：`c0b3e58`（第 1 轮）、`f4edda6`（第 2 轮）、`6846c21`（第 3 轮）
|
||||
- 门禁存在：`用户最终确认：通过`、无 `状态：待处理`、prettier unchanged、`build complete`、无 dead link、侧边栏 9 个目标
|
||||
@ -73,3 +73,19 @@
|
||||
- 移除文档模板措辞：`hooks-in-depth.md`、`plugin-system.md`（含两个章节标题与代码注释）、`declarative-vs-imperative.md`、`replay-consistency.md`、`saveable-content.md`、`data-stores.md`；改用「示例」或直接去掉标签。
|
||||
- 保留游戏领域术语：`怪物模板`、`原始模板`、`默认模板`、`怪物属性模板` 等。
|
||||
- 验证：`prettier --write` 十篇 unchanged；`pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build` 输出 `build complete in 18.62s`，无 dead link；CRLF 与单 H1 保持。
|
||||
|
||||
## 最终确认（2026-10-24）
|
||||
|
||||
**用户原文：**「可以，整体没有问题」
|
||||
|
||||
**最终状态：** 两篇补写内容与高级 I 导览经三轮用户意见收敛（用法优先重构 → 系统模型与元信息清理 → 模板 / 需改标记移除），无待处理项，用户确认通过。
|
||||
|
||||
用户最终确认：通过
|
||||
|
||||
### 收尾记录
|
||||
|
||||
- 待处理项：0。第 1 轮标记为 `状态：已执行`（2026-10-24）；第 2 轮 M1 / M2 / F1 / F2 / F3 全部 `状态：已处理`；第 3 轮为全量模板 / 需改标记清理。
|
||||
- 格式：`node node_modules/prettier/bin/prettier.cjs --write docs/advanced/mover.md docs/advanced/face-handler.md` 两篇均 `unchanged`。
|
||||
- 构建：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 退出码 0，`build complete in 14.31s`，无 dead link。
|
||||
- 结构：两篇 CRLF、单 H1、kebab-case；各有「返回高级 I 导览」结尾；侧边栏高级 I 仍 9 个目标；正文无渲染端内容，渲染端 / 编辑器 / 高级 III 仍为占位。
|
||||
- 非阻断残项：无新增。低概率但按 D-75 仍须覆盖的内容（自定义处理器模板、勇士顶层实现示例、`IRoleFaceBinder` 细节）保留在末尾。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user