diff --git a/.planning/phases/10-docs-restructure/10-19-READER-REVIEW.md b/.planning/phases/10-docs-restructure/10-19-READER-REVIEW.md index 427fbaf..736fdb7 100644 --- a/.planning/phases/10-docs-restructure/10-19-READER-REVIEW.md +++ b/.planning/phases/10-docs-restructure/10-19-READER-REVIEW.md @@ -105,4 +105,29 @@ - `cmd /c "pnpm exec prettier --write docs/advanced/*.md"`：通过。 - `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`：`build complete`，无 dead link。 +--- + +## 读者审阅 · 第 2 轮（复审） + +**结论：阻断性问题 = 0，审阅通过。** + +5 项旧阻断问题均判「已消除」： +- B-01：插件注册示例改为追加 + 新文件 import 说明； +- B-02：`compression` 形参补齐； +- B-03：注册/验证 id 统一为 `@plugin/my-store`； +- B-04：补 `state.saveState` / `state.loadState` 可执行入口； +- B-05：练习目标改为未标记的 `getOrInsert`。 + +### 残留（非阻断，供用户与后续处理） + +1. **录像标记练习对普通作者的可验证性偏弱**：收集区间目前只在测试中调用，正文已说明，但读者仍缺乏生产环境下的可观察入口。 +2. **目标楼层/图层的注册时机**：文档提示 `afterLoad` 时可能 `getMap` 为 `null`，但没有给出「楼层创建」的可订阅事件/时机。 +3. **命名一致性**：`setField` vs `setFieldValue`、`@plugin/my-plugin` vs `@plugin/my-store` 跨篇不一致；`bindSaveableExecuter` 与 `ISaveableExecutor` 拼写差异易被误认为笔误；`revert()` 名称易误解。 +4. **`Mota.require(...)`** 在验证示例中出现但未解释。 +5. **`data-stores.md`** 只有图块定义骨架，道具/地图/事件的原始数据形状缺示例。 +6. **钩子示例** 地图级 `addHook` 的控制器未保存，后续 `unload` 无句柄。 + +以上均为「能写、但验证/细节仍有落差」的项，不影响读者照文档写出可注册代码；留待用户修订循环（10-20）决定是否处理。 + + diff --git a/.planning/phases/10-docs-restructure/10-19-SUMMARY.md b/.planning/phases/10-docs-restructure/10-19-SUMMARY.md new file mode 100644 index 0000000..8f1f42d --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-19-SUMMARY.md @@ -0,0 +1,162 @@ +--- +phase: 10-docs-restructure +plan: 19 +subsystem: docs-site +tags: + - vitepress + - markdown + - advanced-tutorial + - reader-review + +requires: + - phase: 10-docs-restructure + plan: 18 + provides: 高级 I 七篇已接入站点、可导航、可互相跳转 + +provides: + - 10-19-READER-REVIEW.md：高级 I 读者人格、首轮问题清单、第 1 轮修复记录与第 2 轮复审结论 + - 六篇高级 I 文档的阻断性问题修复（插件注册、存档形状、验证入口、录像标记练习等） + - 阻断性问题 = 0 的复审结论，以及 6 条留待用户决定是否处理的非阻断残项 + +affects: + - 10-20 用户主导修订循环 + +actuals: + tokens: 14100 + tasks: 4 + commits: 3 + +tech-stack: + added: [] + patterns: + - 读者人格审阅：独立子代理只提问、不改文件，执行者按问题清单归类并修正 + - 阻断性口径：读者据此无法完成操作，或会对概念/系统边界产生实质误解 + - 非阻断问题只记录、不擅自扩大范围（D-14） + +key-files: + created: + - .planning/phases/10-docs-restructure/10-19-READER-REVIEW.md + modified: + - docs/advanced/declarative-vs-imperative.md + - docs/advanced/plugin-system.md + - docs/advanced/saveable-content.md + - docs/advanced/replay-consistency.md + - docs/advanced/data-stores.md + - docs/advanced/hooks-in-depth.md + +key-decisions: + - 复用 D-57 指定的高级 I 人格——「了解基本语法、代码能力一般、不熟悉引擎内部架构、已读完中级教程」，明确不复用中级教程的「不懂代码」人格 + - 按 D-58 允许高级 I 视内容决定是否保留模板章节，取舍原则继续按 D-55（新增系统优先用插件） + - 5 项阻断问题用 1 轮修复解决，第 2 轮由同人格独立子代理复审判定全部「已消除」 + - 6 条非阻断残项不擅自修复，留给 10-20 的用户修订循环决定 + +patterns-established: + - 审阅记录同时保存人格提示词原文、问题定位、修复落点、构建结论与复审对照 + - 修复以「可照做」为准：补可执行入口、统一示例 id、替换会冲突的练习对象 + +requirements-completed: [] + +coverage: + - id: D1 + description: 独立读者人格审阅记录，含逐字人格提示词、七篇范围、5 项阻断问题与若干非阻断问题，均定位到文件与章节 + requirement: + verification: + - kind: other + ref: "10-19-READER-REVIEW.md 第 1 轮问题清单（B-01..B-05）" + status: pass + human_judgment: true + rationale: 人格是否贴合 D-57、问题归类是否符合「阻断性」口径，需人工判断 + - id: D2 + description: 5 项阻断性问题全部修复，六篇文档可照文档完成插件、存档与录像扩展 + verification: + - kind: other + ref: "10-19-READER-REVIEW.md 第 1 轮修复记录；同人格第 2 轮复审结论「阻断性问题 = 0」" + status: pass + human_judgment: true + rationale: 复审为独立子代理的同人格判断，最终是否可接受由用户在 10-20 确认 + - id: D3 + description: 七篇高级 I 保持 kebab-case、CRLF、单 H1，prettier 与 VitePress 构建通过 + verification: + - kind: integration + ref: "cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\" -> build complete，无 dead link" + status: pass + human_judgment: false + +duration: ~40min（估算） +completed: 2026-10-20 +status: complete +--- + +# Phase 10 Plan 19: 高级 I 读者审阅 Summary + +**以「了解基本语法但代码能力一般」的独立读者人格通读高级 I，修复 5 项阻断问题并由同人格复审判定阻断清零** + +## Performance + +- **Duration:** ~40min（估算） +- **Started:** 2026-10-20（审阅与修正在同一会话内完成） +- **Completed:** 2026-10-20 +- **Tasks:** 4（Task 0 人格确认、Task 1 首轮审阅、Task 2 阻断修复、Task 3 复审） +- **Files modified:** 7（1 份审阅记录 + 6 篇文档） + +## Accomplishments + +- 按 D-57 派发独立读者子代理，以与中级教程不同的人格（了解变量/函数/类/import、代码能力一般、不熟悉引擎内部架构、已读完中级教程）通读 `docs/advanced/` 七篇，产出按阻断/非阻断归类且定位到文件章节的问题清单。 +- 确认并修复 5 项阻断问题：插件注册会覆盖 `DataShopPlugin`、`loadState` 使用未定义的 `compression`、注册与验证 id 不一致、缺少最外层存读档入口、给已有标记的方法重复加装饰器。 +- 第 2 轮由同人格独立子代理复审，5 项旧阻断问题均判「已消除」，结论为「阻断性问题 = 0，审阅通过」。 +- 6 条非阻断残项（录像标记的可观察入口、楼层注册时机、命名一致性、`Mota.require` 未解释、Store 原始数据形状不足、地图级钩子无 unload 句柄）只记录、不擅自修复，留给 10-20。 + +## Task Commits + +Each task was committed atomically: + +1. **Task 0-1: 人格确认、D-58 模板与定位调整、审阅记录初稿** - `f1c0f8b` (docs) +2. **Task 2: 修复高级 I 读者阻断问题（第 1 轮）** - `b8afe95` (docs) +3. **Task 3: 复审记录与收尾** - 本次 SUMMARY 提交 (docs) + +_注：复审结论记录随收尾一并提交；本计划无代码改动。_ + +## Files Created/Modified + +- `.planning/phases/10-docs-restructure/10-19-READER-REVIEW.md` - 人格提示词、首轮问题清单、修复记录、第 2 轮复审与残留项 +- `docs/advanced/plugin-system.md` - 注册示例改为保留 `DataShopPlugin` 并追加新插件，补新文件 `import` 与验证取回写法 +- `docs/advanced/saveable-content.md` - 补 `compression` 形参、统一 `@plugin/my-store`、补 `state.saveState` / `state.loadState` 入口与跨对象引用说明 +- `docs/advanced/declarative-vs-imperative.md` - 补 `getCriticalLimit`、补 `view` 获取方式与存读档入口 +- `docs/advanced/replay-consistency.md` - 练习对象改为未标记的 `getOrInsert`，装饰器表补 message/reason，说明标记不产生录像步 +- `docs/advanced/data-stores.md` - 补 `tileStore.num` 判空、`effect` / `equip` 必填、`fromRaw` / `addLayer` 时机 +- `docs/advanced/hooks-in-depth.md` - 说明 `afterLoad` 时楼层可能为 `null`，修正卸载转发器表述并补 `import` 说明 + +## Decisions Made + +- 人格按 D-57 原文逐字使用，明确「未复用中级人格」；不预设高代码水平，但排除「完全不懂代码」。 +- 按 D-58，高级 I 是否设模板章节视内容决定：插件、可存档、Store 保留，导览、声明式、录像、钩子移除。 +- 阻断性判定以「照文档能否完成操作」与「是否会把系统边界理解错」为准，不把措辞偏好升级为阻断。 +- 第 2 轮复审只收敛理解性问题，不引入新内容。 + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +- 复审记录在会话结束时仍留在工作区未提交，随 10-19/10-20 收尾提交一并入库；内容本身在复审时已完成。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 高级 I 已无阻断性阅读问题，可进入 10-20 用户主导修订循环。 +- 6 条非阻断残项已写入审阅记录，供用户在 10-20 决定是否处理；未阻塞收尾。 + +--- + +*Phase: 10-docs-restructure* +*Completed: 2026-10-20* + +## Self-Check: PASSED + +- `10-19-READER-REVIEW.md` 存在，含人格提示词、七篇范围、B-01..B-05 与第 2 轮复审结论 +- 6 篇被修改文档存在且保持单 H1、CRLF +- `f1c0f8b`、`b8afe95` 可在 git 历史中查到 diff --git a/.planning/phases/10-docs-restructure/10-20-SUMMARY.md b/.planning/phases/10-docs-restructure/10-20-SUMMARY.md new file mode 100644 index 0000000..5f2dd1b --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-20-SUMMARY.md @@ -0,0 +1,210 @@ +--- +phase: 10-docs-restructure +plan: 20 +subsystem: docs-site +tags: + - vitepress + - markdown + - advanced-tutorial + - user-review + - d-59 + +requires: + - phase: 10-docs-restructure + plan: 19 + provides: 高级 I 阻断性问题清零的读者审阅结论 + +provides: + - 用户主导的六轮修订记录（10-20-USER-REVIEW.md） + - 按 D-59 库文档风格重写的七篇高级 I 文档 + - D-60..D-66 的长期文档规范（简洁优先、边界后置、代码块完整、模板顺序、模板范围、注释密度、示例按功能拆分） + - 用户最终确认（用户最终确认：通过）与最终格式/构建结论 + +affects: + - 高级 II / 高级 III 的写作规范 + - 后续所有教程文档的模板与示例写法 + +actuals: + tokens: 47900 + tasks: 5 + commits: 10 + +tech-stack: + added: [] + patterns: + - 库文档风格：带注释的完整示例 + 叙述式解释，替代中级教程的六步实操块（D-59） + - 模板三段结构：引导语 → 模板 → 说明声明了什么、实现了什么接口、需要改什么（D-63） + - 只有需要读者实现接口或注册内容时才给模板；纯接口使用只给示例（D-64） + - 示例注释宁多勿少（D-65）；杂项功能示例按功能分开写（D-66） + +key-files: + created: + - .planning/phases/10-docs-restructure/10-20-USER-REVIEW.md + - .planning/phases/10-docs-restructure/10-20-SUMMARY.md + modified: + - docs/advanced/index.md + - docs/advanced/declarative-vs-imperative.md + - docs/advanced/plugin-system.md + - docs/advanced/saveable-content.md + - docs/advanced/replay-consistency.md + - docs/advanced/data-stores.md + - docs/advanced/hooks-in-depth.md + +key-decisions: + - 按 D-59 删除全部六步实操块，改为「完整示例 + 注释 + 叙述」，验证不再手把手分步 + - 按 U2-04/U3-01/U4-02/U4-04 把数据端与渲染端插件并列成章，渲染端插件同样给出目录、注册与取用示例 + - 存档按 U2-05 明确顶层不再自动 `structuredClone`，`saveState` 必须返回独立对象；按 U4-09 明确存读档顺序不做保证 + - 录像按 U2-07..U2-10 改为「给自己的方法加 `@shouldReplay`」，只讲「记录缺失」告警，不展开底层收集机制 + - 按 U2-11..U2-16、U4-11/U4-12、U5-05/U5-06、第 6 轮把 Store 改为五个独立小节，各讲「存什么 + 自身接口」并各配一个示例 + - 按 U2-17、U4-13 把钩子统一为「建议一个对象一个实例」，不展开共享实例 + - 按 U3-05 导览改为高级教程同时覆盖数据端与渲染端，渲染端未完工只影响当前收录范围 + +patterns-established: + - 模板不放在文首：先讲理念与能解决什么问题，再给模板，再围绕模板解释（D-63） + - 代码块必须是完整结构（import / 完整类 / 完整声明），不单独放方法成员或顶层语句（D-62） + - 边界与常见错误统一收敛到文末「边界与注意」，主干只讲正常路径（D-61） + - Store 这类纯接口只讲能做什么与存什么，不给模板（D-64） + +requirements-completed: [] + +coverage: + - id: D1 + description: 七篇高级 I 按 D-59 改为库文档风格，删除六步实操块，示例带完整注释 + verification: + - kind: other + ref: "10-20-USER-REVIEW.md 第 1 轮处置表；docs/advanced/*.md" + status: pass + human_judgment: true + rationale: 风格是否符合读者预期只能由用户判断，用户已在第 1 轮与最终确认中认可 + - id: D2 + description: 用户六轮意见（D-59、U2-01..U2-17、U3-01..U3-05、U4-01..U4-13、U5-01..U5-07、Store 扩充）逐条落地 + verification: + - kind: other + ref: "10-20-USER-REVIEW.md 各轮处置表与状态行" + status: pass + human_judgment: true + rationale: 条目是否真正解决用户所指问题由用户逐轮验收，最终以「没问题了」确认 + - id: D3 + description: 七篇 prettier 检查通过，VitePress 全量构建 green、build complete、无 dead link + verification: + - kind: integration + ref: "cmd /c \"pnpm exec prettier --check docs/advanced/*.md\" -> All matched files use Prettier code style" + status: pass + - kind: integration + ref: "cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\" -> build complete in 16.61s，无 dead link" + status: pass + human_judgment: false + - id: D4 + description: 用户明确确认收尾 + verification: [] + human_judgment: true + rationale: D-46 第 2 阶段 / D-57 要求必须由用户确认，不能由 AI 自行收尾 + +duration: 未精确计时（六轮修订跨多个会话） +completed: 2026-10-20 +status: complete +--- + +# Phase 10 Plan 20: 高级 I 用户修订循环 Summary + +**用户六轮逐条修订后确认「没问题了」，高级 I 七篇以库文档风格收口并通过最终 prettier 与全量构建** + +## Performance + +- **Duration:** 未精确计时（六轮修订跨多个会话） +- **Started:** 2026-10-20 +- **Completed:** 2026-10-20 +- **Tasks:** 5（Task 0 汇报确认、Task 1 收集意见、Task 2 逐条修订、Task 3 回报确认、Task 4 收尾） +- **Files modified:** 9（7 篇文档 + 用户修订记录 + 本 SUMMARY） + +## Accomplishments + +- 执行 D-46 第 2 阶段 / D-57 的用户主导修订循环，共六轮，全部意见在 `10-20-USER-REVIEW.md` 中留有意见、落点、处置与构建结论。 +- 第 1 轮按 D-59 删除中级教程式六步实操块，七篇改为「完整示例 + 解释性注释 + 叙述式概念」的库文档风格。 +- 第 2 轮落地 17 条意见（U2-01..U2-17）：去除 `src/content` 举例、数据端/渲染端插件依赖方向、存档顶层不自动深拷贝、录像改为给自己方法加标记且不展开底层收集、Store 改列表与补 `enemyStore`、钩子改「一个对象一个实例」。 +- 第 3 轮落地 5 条（U3-01..U3-05）：补渲染端插件接口与注册、补 Store 自定义极少见的边界说明、修代码块完整结构、保留录像 logger 调用、导览覆盖渲染端。 +- 第 4 轮落地 13 条（U4-01..U4-13）：删除手写特殊属性示例、数据端与渲染端并列、依赖直接解构、注册与目录前移、接口 `I` 前缀、先模板后解释、插件可在钩子中调用、存读档顺序不保证、`@shouldReplay` 仅数据端、Store 讲存什么、钩子建议一对象一实例。 +- 第 5 轮落地 7 条（U5-01..U5-07）：插件理念前置、补 `getClientPlugin`、模板三段结构、模板不置文首、Store 不给模板、Store 讲清对象类型、示例注释补足；沉淀 D-63..D-65。 +- 第 6 轮扩充 `data-stores.md`：五个 Store 各自独立成节，讲清 `ITileRawData` / `IItemRawData` / `IMapRawData` / `IEnemyRawData` / `IReadonlyGameEvent` 与常用成员，并各配一个独立示例；沉淀 D-66。 +- 用户确认「没问题了」，记录为独占一行的 `用户最终确认：通过`；最终 prettier 七篇通过，构建 `build complete`（16.61s）且无 dead link。 + +## Task Commits + +Each task was committed atomically: + +1. **第 1 轮：高级 I 改为库文档风格（示例 + 注释，D-59）** - `68e1f6f` (docs) +2. **第 1 轮补遗：补充插件示例的导入与放置说明** - `d35f830` (docs) +3. **第 2 轮：修订插件 / 存档 / 录像** - `8912f5d` (docs) +4. **第 2 轮：修订 Store / 钩子 / 声明式** - `74116b8` (docs) +5. **第 3 轮：插件渲染端 / Store 边界 / 代码块** - `6351cfe` (docs) +6. **第 4 轮 A：声明式 / 插件** - `b451da2` (docs) +7. **第 4 轮 B：存档 / 录像 / Store / 钩子** - `c578990` (docs) +8. **第 5 轮：模板结构与注释** - `2f181c8` (docs) +9. **第 6 轮：扩充 Store 内容与分项示例** - `4bd1665` (docs) +10. **收尾：最终格式、构建与 SUMMARY** - 本次提交 (docs) + +## Files Created/Modified + +- `.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md` - 六轮用户意见、处置、构建结论与最终确认 +- `.planning/phases/10-docs-restructure/10-20-SUMMARY.md` - 本文件 +- `docs/advanced/index.md` - 导览同步：高级教程覆盖两端、Store 数量与钩子建议、阅读路径措辞 +- `docs/advanced/declarative-vs-imperative.md` - 删除手写特殊属性示例，改为叙述 + 完整伤害计算器/钩子模板 +- `docs/advanced/plugin-system.md` - 数据端与渲染端并列、注册与目录前移、完整模板与逐项解释、插件外调用 +- `docs/advanced/saveable-content.md` - 完整可存档模板、顶层不深拷贝、存读档顺序不保证、执行器示例 +- `docs/advanced/replay-consistency.md` - `@shouldReplay` 用于自己的方法、仅数据端、记录缺失告警 +- `docs/advanced/data-stores.md` - 五个 Store 独立小节（存什么 + 接口 + 独立示例） +- `docs/advanced/hooks-in-depth.md` - 建议一个对象一个实例、图层级与地图级钩子完整示例 + +## Decisions Made + +- 高级教程不再沿用中级教程的六步实操结构；示例完整、注释充分、概念用叙述讲（D-59）。 +- 数据端与渲染端插件是平等关系，文档并列覆盖；渲染端未完工只影响当前能写的内容范围。 +- 存档返回值独立性由 `saveState` 实现负责，顶层不做自动深拷贝；存读档顺序不作为契约。 +- 录像侧只教作者给自己的数据端方法补 `@shouldReplay`，底层收集与细节留给高级 II / III。 +- Store 以「存什么 + 能做什么」为主，纯接口不给模板；每个 Store 的示例独立，不与其它 Store 混写（D-64 / D-66）。 +- 模板遵循「理念 → 引导语 → 模板 → 解释」顺序，且不放在文档开头（D-63）。 + +## Deviations from Plan + +### User-directed plan adjustments + +**1. [Rule 4 - Architectural] 最终结构断言与用户第 3 轮意见冲突，按用户后发指令执行** +- **Found during:** Task 4（收尾） +- **Issue:** `10-20-PLAN.md` 的收尾 verify 含 `RENDERER-CONTENT` 断言（要求 `docs/advanced/*.md` 不出现 `src/client`），但用户第 3 轮 U3-01/U3-05 明确要求高级教程覆盖渲染端插件与渲染端内容。 +- **Fix:** 以用户后发指令为准，保留 `plugin-system.md` 的渲染端插件章节与 `index.md` 的渲染端表述；收尾只执行用户要求的 prettier 与构建门禁，不执行该条已过时的结构断言。 +- **Files modified:** `docs/advanced/plugin-system.md`、`docs/advanced/index.md` +- **Verification:** prettier 七篇通过；`pnpm docs:build` 输出 `build complete`，无 dead link。 +- **Committed in:** 用户第 3 轮提交 `6351cfe` 与本次收尾提交 + +--- + +**Total deviations:** 1（用户指令覆盖计划中的过时断言） +**Impact on plan:** 无范围扩张；最终文档与用户最后一轮明确要求一致。 + +## Issues Encountered + +- 第 4 轮记录结束时状态写作「处理中」，系该轮分批提交（A/B）造成；后续轮次已全部处理，最终确认时无 `状态：待处理` 条目。 +- 构建时出现既有的 chunk 大于 500 kB 警告，与文档改动无关，未处理。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 高级 I 七篇内容、格式与构建均已收口，用户已确认，可作为 D-09 人工验收依据。 +- 高级 II / III 仍只保留代码 span 与 HTML 注释占位，无死链；后续写作沿用 D-59、D-62..D-66 规范。 +- 10-19 的 6 条非阻断残项中，Store 原始数据形状已在第 6 轮补齐；其余命名与观察入口类问题未阻塞收尾，可作为后续打磨项。 + +--- + +*Phase: 10-docs-restructure* +*Completed: 2026-10-20* + +## Self-Check: PASSED + +- `10-20-USER-REVIEW.md` 含独占一行的 `用户最终确认：通过`，且无 `状态：待处理` 条目 +- `10-20-SUMMARY.md` 存在并含用户确认、构建与七篇清单 +- 七篇文档存在、单 H1、CRLF；prettier `--check` 通过 +- 构建 `build complete`（16.61s），无 dead link +- 9 个修订提交均可在 git 历史中查到 diff --git a/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md b/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md index d5f5408..d6e2614 100644 --- a/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md +++ b/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md @@ -254,4 +254,18 @@ **状态：已处理** +--- + +## 最终确认 + +**时间：** 2026-10-20 +**用户原文：** 「没问题了」 +**依据：** D-46 第 2 阶段 / D-57——用户主导修订循环的收尾出口，必须由用户明确确认。 + +用户最终确认：通过 + +**最终状态：** 高级 I 七篇完成六轮用户修订（D-59 库文档风格改写、17 条、5 条、13 条、7 条、Store 内容扩充），最终 prettier `--check` 七篇通过，`pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build` 输出 `build complete`（16.61s）且无 dead link；10-19 读者审阅的 5 项阻断问题已全部消除。 + +**状态：已处理** +