mirror of
https://github.com/motajs/template.git
synced 2026-10-29 12:20:17 +08:00
docs(10): sync phase 10 after advanced I gap docs
This commit is contained in:
parent
3dd91a8654
commit
2f1e3f5b70
@ -547,14 +547,14 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
|
||||
| 7. 数据端缺陷修复 | 15/16 | Complete（07-16 superseded） | - |
|
||||
| 8. 测试重构与接口对齐 | 11/11 | Complete | 2026-10-08 |
|
||||
| 9. 最小浏览器可运行版本 | 15/16 | In Progress| |
|
||||
| 10. 文档重构 | 24/27 | In Progress | - |
|
||||
| 10. 文档重构 | 29/32 | In Progress | - |
|
||||
|
||||
### Phase 10: 文档重构
|
||||
|
||||
**Goal:** 重构过老、结构不佳、新人难懂的项目文档，面向多背景读者（完全新手 / 不懂代码的作者 / 有基础的作者 / AI Agent）提供分层指南。本阶段采用「伞阶段 + 增量派发」：每次只规划执行一个已派发的具体小任务。**第一批已派发 = 中级教程（`docs/intermediate/`，24 篇中文 markdown）+ 在 VitePress 站点注册它们 + 旧内容清空（D-04 并入本批）**（D-01..D-44）。**第二批已派发 = 高级教程 I（`docs/advanced/`，7 篇数据端文档）+ 站点注册 + 独立读者人格审阅 + 用户主导修订循环**（D-53..D-57）。**第三批已完成 = 高级教程 II「深入定制」（`docs/advanced/ii/`，10 篇数据端文档）+ 站点注册 + 独立读者人格审阅 + 用户主导修订循环**（D-67，2026-10-23 收尾）。
|
||||
**Requirements**: （无专属需求 ID；以 `10-CONTEXT.md` 的 D-01..D-74 为需求基线，验收锚在 D-09：用户人工审阅 + 链接全部有效 + 构建通过）
|
||||
**Goal:** 重构过老、结构不佳、新人难懂的项目文档，面向多背景读者（完全新手 / 不懂代码的作者 / 有基础的作者 / AI Agent）提供分层指南。本阶段采用「伞阶段 + 增量派发」：每次只规划执行一个已派发的具体小任务。**第一批已派发 = 中级教程（`docs/intermediate/`，24 篇中文 markdown）+ 在 VitePress 站点注册它们 + 旧内容清空（D-04 并入本批）**（D-01..D-44）。**第二批已派发 = 高级教程 I（`docs/advanced/`，7 篇数据端文档）+ 站点注册 + 独立读者人格审阅 + 用户主导修订循环**（D-53..D-57）。**第三批已完成 = 高级教程 II「深入定制」（`docs/advanced/ii/`，10 篇数据端文档）+ 站点注册 + 独立读者人格审阅 + 用户主导修订循环**（D-67，2026-10-23 收尾）。**第四批已完成 = 高级 I 补写（移动 Mover + FaceHandler 系列，`docs/advanced/`，2 篇）+ 站点注册 + 读者/用户修订**（D-75，2026-10-24 收尾）。
|
||||
**Requirements**: （无专属需求 ID；以 `10-CONTEXT.md` 的 D-01..D-83 为需求基线，验收锚在 D-09：用户人工审阅 + 链接全部有效 + 构建通过）
|
||||
**Depends on:** Phase 9
|
||||
**Plans:** 24/32 completed（第一批：中级教程 24 篇 + 站点注册 + D-09 复审修订；第二批：高级 I 7 篇 + 注册 + 读者审阅 + 用户修订循环；第三批：高级 II 10 篇 + 注册 + 读者审阅 + 用户修订循环；第四批：高级 I 补写 2 篇 + 注册 + 读者审阅 + 用户修订循环，待执行）。**未完成 3 个**（第一批遗留）：`10-06`（中级全批验收）、`10-11`（中级读者审阅）、`10-12`（中级最终验收）——其范围已被后续 D-09 修订与高级 I/II 期间的最终状态覆盖，缺独立 SUMMARY，待补跑或并入后续验收。
|
||||
**Plans:** 29/32 completed（第一批：中级教程 24 篇 + 站点注册 + D-09 复审修订；第二批：高级 I 7 篇 + 注册 + 读者审阅 + 用户修订循环；第三批：高级 II 10 篇 + 注册 + 读者审阅 + 用户修订循环；第四批：高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订，已完成）。**未完成 3 个**（第一批遗留）：`10-06`（中级全批验收）、`10-11`（中级读者审阅）、`10-12`（中级最终验收）——其范围已被后续 D-09 修订与高级 I/II 期间的最终状态覆盖，缺独立 SUMMARY，待补跑或并入后续验收。
|
||||
|
||||
Plans:
|
||||
- [x] 10-01-PLAN.md — Wave 0：旧内容清空 + 站点注册（删除 `docs/guide`、`docs/dev`、`docs/logger`、`docs/api` 与首页 `docs/index.md`；清理 `config.ts` 旧 nav/sidebar 键并解除 apiSidebar/api 依赖；`api.ts` 加缺失目录守卫；新增 nav 入口 + `sidebar['/intermediate/']` 4 组/24 条；报告并等待 checkpoint）
|
||||
@ -584,11 +584,11 @@ Plans:
|
||||
- [x] 10-25-PLAN.md — 高级 II 导览 + 侧边栏注册（`/advanced/ii/` 九篇、分组名待用户确认）+ 互链与全量构建
|
||||
- [x] 10-26-PLAN.md — 高级 II 独立读者人格审阅（高代码能力人格，不同于高级 I）→ 问题清单 → 迭代修正（≤3 轮）→ 复审清零
|
||||
- [x] 10-27-PLAN.md — 高级 II 用户主导修订循环 → 用户确认 → 最终格式 / 构建 / SUMMARY 收尾
|
||||
- [ ] 10-28-PLAN.md — 高级 I 补写：移动 Mover（三件套 / 移动计划与执行 / 控制器 / 步骤类型 / 钩子 / 自定义移动器）
|
||||
- [ ] 10-29-PLAN.md — 高级 I 补写：FaceHandler 系列（`FaceDirection` / `FaceGroup` / `IFaceHandler` / 内置处理器 / 自定义处理器 / `IRoleFaceBinder`）
|
||||
- [ ] 10-30-PLAN.md — 高级 I 导览 7 → 9 + 侧边栏注册 + 两篇互链收口 + 全量构建
|
||||
- [ ] 10-31-PLAN.md — 两篇补写内容的独立读者审阅（沿用高级 I 人格）→ 问题清单 → 迭代修正（≤3 轮）→ 复审清零
|
||||
- [ ] 10-32-PLAN.md — 两篇补写内容的用户主导修订循环 → 用户确认 → 最终格式 / 构建 / SUMMARY 收尾
|
||||
- [x] 10-28-PLAN.md — 高级 I 补写：移动 Mover（三件套 / 移动计划与执行 / 控制器 / 步骤类型 / 钩子 / 自定义移动器）
|
||||
- [x] 10-29-PLAN.md — 高级 I 补写：FaceHandler 系列（`FaceDirection` / `FaceGroup` / `IFaceHandler` / 内置处理器 / 自定义处理器 / `IRoleFaceBinder`）
|
||||
- [x] 10-30-PLAN.md — 高级 I 导览 7 → 9 + 侧边栏注册 + 两篇互链收口 + 全量构建
|
||||
- [x] 10-31-PLAN.md — 两篇补写内容的独立读者审阅（沿用高级 I 人格）→ 问题清单 → 迭代修正（≤3 轮）→ 复审清零
|
||||
- [x] 10-32-PLAN.md — 两篇补写内容的用户主导修订循环 → 用户确认 → 最终格式 / 构建 / SUMMARY 收尾
|
||||
|
||||
**说明：** 每篇中级教程遵循 `10-CONTEXT.md` D-21..D-44 的逐篇要点与阅读顺序（4/8/9/3）。**旧内容删除已并入本批（D-04，Wave 0 / 10-01）**：删除 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`、`docs/api/*` 与首页 `docs/index.md`，并清理 `docs/.vitepress/config.ts` 的旧 `nav`/`sidebar` 键。文档改动为 `docs/intermediate/*.md`（新增）、`docs/.vitepress/config.ts` 与 `docs/.vitepress/api.ts`（缺失目录守卫，保留按包生成机制）。构建命令 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`；`init.ts` 在 `docs/api/` 缺失时安全跳过。本机 PowerShell 禁止 `pnpm.ps1`，命令经 `cmd /c "..."` 执行。
|
||||
|
||||
|
||||
@ -4,16 +4,16 @@ milestone: v1.0
|
||||
current_phase: 10
|
||||
current_phase_name: 文档重构
|
||||
status: executing
|
||||
stopped_at: Phase 10 进行中：中级 24 篇 + 高级 I 7 篇 + 高级 II 10 篇已收尾；10-06/10-11/10-12 待补
|
||||
last_updated: "2026-10-23T00:00:00.000Z"
|
||||
last_activity: 2026-10-23
|
||||
last_activity_desc: 高级 II（docs/advanced/ii 10 篇）完成并经用户确认收尾
|
||||
stopped_at: Phase 10 进行中：中级 24 篇 + 高级 I 9 篇 + 高级 II 10 篇已收尾；10-06/10-11/10-12 待补
|
||||
last_updated: "2026-10-24T00:00:00.000Z"
|
||||
last_activity: 2026-10-24
|
||||
last_activity_desc: 高级 I 补写（Mover + FaceHandler）完成并经用户确认收尾
|
||||
state_head: dbbcf533dce2f22078a82d26817f36b85865da62
|
||||
progress:
|
||||
total_phases: 10
|
||||
completed_phases: 3
|
||||
total_plans: 129
|
||||
completed_plans: 121
|
||||
total_plans: 134
|
||||
completed_plans: 126
|
||||
milestone_name: milestone
|
||||
---
|
||||
|
||||
@ -29,11 +29,11 @@ See: .planning/PROJECT.md (updated 2026-09-17)
|
||||
## Current Position
|
||||
|
||||
Phase: 10 (文档重构) — IN PROGRESS
|
||||
Plan: 第一批（中级 24 篇）、第二批（高级 I 7 篇）、第三批（高级 II 10 篇）已收尾；10-06 / 10-11 / 10-12 待补
|
||||
Plan: 第一批（中级 24 篇）、第二批（高级 I 7 篇）、第三批（高级 II 10 篇）、第四批（高级 I 补写 Mover/FaceHandler 2 篇）已收尾；10-06 / 10-11 / 10-12 待补
|
||||
Status: In Progress
|
||||
Last activity: 2026-10-23 — 高级 II 完成并经用户确认收尾
|
||||
Last activity: 2026-10-24 — 高级 I 补写完成并经用户确认收尾
|
||||
|
||||
Progress: Phase 10 · 24/27 plans（中级 + 高级 I + 高级 II 已收尾；总览 / 初级 / 高级 III / API / Agent 参考仍待推进）
|
||||
Progress: Phase 10 · 29/32 plans（中级 + 高级 I 9 篇 + 高级 II 已收尾；总览 / 初级 / 高级 III / API / Agent 参考仍待推进）
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
@ -266,7 +266,7 @@ Recent decisions affecting current work:
|
||||
- Phases 4/5/6 marked obsolete (2026-10-08): 渲染适配与双布局 / Legacy 移植 / 单元测试 的原规划不再合理，由 Phase 9 承接；仅文本标注，未删除阶段目录、已执行 PLAN/SUMMARY 或代码
|
||||
- Phase 9 added (2026-10-08): 最小浏览器可运行版本（在已完成且 Node 可运行/回放验证的数据端之上完成渲染端框架，并验证可在浏览器上运行）；Depends on Phase 8
|
||||
- Phase 10 added (2026-10-14): 文档重构（重构过老、结构不佳、新人难懂的项目文档，面向新人/不懂代码的作者/有基础作者等多背景读者提供分层指南，并专门为 AI Agent 编写参考文档）；Depends on Phase 9
|
||||
- Phase 10 第一批（中级教程 24 篇 + 旧内容清空 + 站点注册 + D-09 修订 + 读者/用户修订循环）已完成并收尾（2026-10-20）；第二批（高级 I 7 篇 + 站点注册 + 独立读者审阅 + 用户 6 轮修订）已完成并经用户确认收尾（2026-10-20）；第三批（高级 II 10 篇 + 站点注册 + 独立读者审阅 + 用户 3 轮修订）已完成并经用户确认收尾（2026-10-23）。遗留 `10-06` / `10-11` / `10-12` 缺独立 SUMMARY，其范围已被后续修订覆盖
|
||||
- Phase 10 第一批（中级教程 24 篇 + 旧内容清空 + 站点注册 + D-09 修订 + 读者/用户修订循环）已完成并收尾（2026-10-20）；第二批（高级 I 7 篇 + 站点注册 + 独立读者审阅 + 用户 6 轮修订）已完成并经用户确认收尾（2026-10-20）；第三批（高级 II 10 篇 + 站点注册 + 独立读者审阅 + 用户 3 轮修订）已完成并经用户确认收尾（2026-10-23）；第四批（高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订）已完成并经用户确认收尾（2026-10-24）。遗留 `10-06` / `10-11` / `10-12` 缺独立 SUMMARY，其范围已被后续修订覆盖
|
||||
|
||||
### Pending Todos
|
||||
|
||||
|
||||
@ -193,9 +193,25 @@
|
||||
- **D-69（纯内部实现章节，长期规范）：** 讲解**纯内部实现**的章节，开头必须写明「此章节讲解一下 XXX 的内部实现」；这类章节应放在文档**靠后**位置，文档前面以「如何使用」为主。适用于后续所有文档写作。
|
||||
- **D-70（代码块完整类上下文，长期规范）：** 代码块必须包裹**完整的类上下文**（尤其是类的方法），确保语法高亮正确；不要单独展示脱离类的方法体。适用于后续所有文档写作。
|
||||
- **D-71（高级 I 待补内容）：** 高级 I 还有未讲内容，待后续补写：**移动 Mover**、**FaceHandler 系列接口**。当前先完成高级 II，之后再补。
|
||||
- **D-72（注释优先，长期规范）：** 当引擎源码的**注释与实现不一致**时，文档**一律以方法注释为准**，并在对话中**向用户报告**该不一致。不得按实现去改写注释的语义。适用于后续所有文档写作。
|
||||
- **D-72（注释优先，长期规范）：** 当引擎源码的**注释与实现不一致**时，文档**一律以方法注释为准**，并在对话中**向用户报告**该不一致。不得按实现去改写注释的语义。**该不一致只在对话中报告，不写进文档正文。** 适用于后续所有文档写作。
|
||||
- **D-73（假定编辑器已完成，长期规范）：** 文档**假定编辑器已经完成**。涉及编辑器 / `.jsonc` 内容配置的地方，只写「需要编辑器」的占位标识；**不要讲「编辑器未就位时改文件、就位后用编辑器」**这类过渡做法。所有 `.jsonc` 均由编辑器负责。适用于后续所有文档写作。
|
||||
- **D-74（章节锚点链接，长期规范）：** 引用其他文档的**具体章节**时，使用 `./xxx.md#标题` 直接定位到该标题（如 `./static-vs-dynamic-tiles.md#双向转换`）。适用于后续所有文档写作。**待办：** 高级 II 完成后，回头检查高级 I 与中级教程是否存在同类未定位的链接。
|
||||
- **D-75（高级 I 补写主题）：** 高级 I 需补两篇数据端文档，接入 `docs/advanced/` 与高级 I 侧边栏：
|
||||
1. **移动 Mover**（`mover.md`）：`IObjectMover` / `IObjectMovable` / `IMoveController`、移动计划与执行、异步移动、`step` / `forward` / `backward` / `tp` / `face` / `jump` / `speed` / `animDir`、`IObjectMoverHooks` 钩子；讲怎么用、怎么改/扩展。
|
||||
2. **FaceHandler 系列**（`face-handler.md`）：`FaceDirection` / `FaceGroup`、`IFaceHandler` / `IFaceDescriptor`、`Dir4FaceHandler` / `Dir8FaceHandler`、`degrade` / `next` / `opposite` / `mapMovement`、`IRoleFaceBinder`；讲怎么用、怎么改/扩展。
|
||||
两篇按高级 I 读者水平（D-57：了解基本语法、代码能力一般）与库文档风格（D-59..D-74）编写；渲染端 / 编辑器内容按 D-47 占位。补写完成后同样走独立读者审阅 + 用户修订循环（D-46 / D-57）。
|
||||
- **D-76（面朝朝向 vs 移动朝向）：** 文档必须明确区分**面朝朝向（`faceDirection`）**与**移动朝向（`moveDirection`）**。`IObjectMover.forward` 的「沿当前移动方向」指的是**面朝朝向**走（不是 `moveDirection`）；`onSetMoveDir` 的「设置朝向」指设置**移动朝向**。源码实现正确，不得把此处注释当作 bug。
|
||||
- **D-77（文档重心由内容性质决定）：** 文档重心**不是一律讲「怎么用」**，而由所讲内容的性质决定：
|
||||
- 样板**已提供、只需使用**的内容 → 重点讲**怎么用**（自定义概率极低，最多一两节带过）；
|
||||
- 内容本身就是**靠自定义 / 扩展**实现的 → 重点讲**怎么自定义**。
|
||||
二者不冲突。写作后自问：**这篇文档每个章节被使用的概率有多大？** 通篇低概率说明写得不好（除非文档本身就是讲底层自定义）。**若无法判断重心，先问用户，不得自行决定。**
|
||||
适用于后续所有文档。
|
||||
- **D-78（审阅须给出章节使用概率）：** 独立读者审阅时**必须为每个章节给出「被使用的概率」**（高/中/低，并简述理由），让修订者知道哪些重要、哪些可以删减或后置。适用于后续所有读者审阅。
|
||||
- **D-79（不写使用概率元信息）：** **不要在文档正文写「本节使用概率很低」之类的元信息**。但若某章看起来很有用、实际根本用不到，可以适当提示。适用于后续所有文档。
|
||||
- **D-80（不写源码叙述）：** **不要在文档里写「源码怎么怎么样」**。文档是给人看的，源码级叙述对读者无用。适用于后续所有文档。
|
||||
- **D-81（不把用户问题写进文档）：** 用户提出的是**问题**；**不要把问题本身或「为了解决该问题所以这样写」写进文档**。文档面向读者，不是写给用户看的复盘。适用于后续所有文档。
|
||||
- **D-82（先讲系统模型）：** 讲一个系统时，**先讲清它的模型是什么**（概念、组成、数据流），再讲接口与用法；不要一上来就讲怎么获取、怎么调用。适用于后续所有系统类文档。
|
||||
- **D-83（高级教程不写模板/需改标记）：** 高级教程中**不再写「模板」「[需改]」等标记或模板章节名**；示例代码只需用**注释说明下一行在做什么**。注意区分：游戏数据领域的「怪物模板 / 原始模板 / 默认模板」等术语不受此限。适用于高级 I / II / III。
|
||||
|
||||
</decisions>
|
||||
|
||||
|
||||
@ -57,7 +57,7 @@
|
||||
"next": {
|
||||
"command": "/gsd:progress --next",
|
||||
"label": "Advance to the next step",
|
||||
"reason": "Phase 10 of 10 · in progress（中级 + 高级 I + 高级 II 已收尾）"
|
||||
"reason": "Phase 10 of 10 · in progress（中级 + 高级 I 9 篇 + 高级 II 已收尾）"
|
||||
},
|
||||
"updated_at": "2026-10-23T00:00:00.000Z"
|
||||
"updated_at": "2026-10-24T00:00:00.000Z"
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user