From f3c4726edd71fa15d33ee4530cdb6a05d0adbd8c Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Wed, 21 Oct 2026 19:10:20 +0800 Subject: [PATCH] docs(10-25): complete advanced II overview plan --- .../10-docs-restructure/10-25-SUMMARY.md | 198 ++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 .planning/phases/10-docs-restructure/10-25-SUMMARY.md diff --git a/.planning/phases/10-docs-restructure/10-25-SUMMARY.md b/.planning/phases/10-docs-restructure/10-25-SUMMARY.md new file mode 100644 index 0000000..64b1719 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-25-SUMMARY.md @@ -0,0 +1,198 @@ +--- +phase: 10-docs-restructure +plan: 25 +subsystem: docs +tags: [vitepress, sidebar, advanced-ii, overview, cross-links, build-gate] + +# Dependency graph +requires: + - phase: 10-docs-restructure + provides: "10-21..10-24 的八篇高级 II 正文（范围、图块、装备、录像指令、寻路、勇士/怪物属性、战斗上下文）" +provides: + - "docs/advanced/ii/index.md：高级 II 导览（定位、前置、九篇表、三条阅读路径、边界、D-55、自检）" + - "docs/.vitepress/config.ts：侧边栏「高级 II · 深入定制」组，挂 9 个链接" + - "八篇正文的返回导览链接与 docs/advanced/index.md 的高级 II 入口" +affects: [10-26] + +# Actuals (#2632) +actuals: + tokens: 4501 + tasks: 4 + commits: 3 + plan_head_before: 3d8cfdfff23d5231778d762e886f11f37cbf9297 + +# Tech tracking +tech-stack: + added: [] + patterns: + - "侧边栏分组按难度层组织，链接使用绝对路径且不带 .md" + - "高级 II 导览承担 D-67 的定位、前置与推荐顺序；高级 III 仍用代码 span 占位" + - "层级导览互相链接：高级 II 文末返回高级 I 导览，正文文末返回高级 II 导览" + +key-files: + created: + - docs/advanced/ii/index.md + modified: + - docs/.vitepress/config.ts + - docs/advanced/index.md + - docs/advanced/ii/custom-range.md + - docs/advanced/ii/static-vs-dynamic-tiles.md + - docs/advanced/ii/equipment-system.md + - docs/advanced/ii/custom-replay-command.md + - docs/advanced/ii/pathfinding.md + - docs/advanced/ii/adding-hero-attribute.md + - docs/advanced/ii/adding-enemy-attribute.md + - docs/advanced/ii/enemy-context-and-combat.md + +key-decisions: + - "侧边栏分组名采用用户已确认的「高级 II · 深入定制」，折叠状态设为展开" + - "高级 II 导览给出三条阅读路径：系统定制、行为扩展、按需查阅，并建议先读范围对象" + - "高级 III 仍不提供页面入口，只用代码 span `高级 III · 原理与架构` 与 `TODO(advanced-III)` 占位" + - "docs/advanced/index.md 只替换过时说明与高级 II 入口，不重写整篇导览" + - "保留 nav、`/intermediate/` 侧边栏、高级 I / III 组、base、outDir、搜索与 mermaid 配置不变" + +patterns-established: + - "层导览结构：给谁 → 难度定位 → 前置 → 篇目表 → 阅读路径 → 边界 → 取舍原则 → 自检 → 返回" + - "新增层接入顺序：先写导览，再注册侧边栏，最后互链与全量构建收口" + +requirements-completed: [] + +coverage: + - id: D1 + description: "高级 II 导览：定位、前置、九篇索引、三条阅读路径、边界、优先插件与自检清单" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "导览措辞、难度定位与阅读路径需按 D-46/D-68 由用户审阅（10-26 读者审阅）" + - id: D2 + description: "侧边栏「高级 II · 深入定制」组注册 9 个链接，导览 + 八篇正文" + verification: + - kind: automated_ui + ref: "docs/.vitepress/config.ts 正则断言：/advanced/ii/* 目标数 = 9；pnpm docs:build" + status: pass + human_judgment: false + - id: D3 + description: "八篇正文返回导览链接；docs/advanced/index.md 指向高级 II 并移除过时说明" + verification: + - kind: automated_ui + ref: "八篇 ./index.md 断言 + 相对链接可达性检查 + pnpm docs:build" + status: pass + human_judgment: true + rationale: "高级 I 导览中高级 II 的描述改写需用户确认口径" + - id: D4 + description: "prettier 格式与全量构建门禁：build complete、dead link = 0" + verification: + - kind: automated_ui + ref: "node node_modules/prettier/bin/prettier.cjs --check docs/advanced/index.md docs/advanced/ii/*.md" + status: pass + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: false + +# Metrics +duration: 25min +completed: 2026-10-21 +status: complete +--- + +# Phase 10 Plan 25: 高级 II 导览与站点注册 Summary + +**高级 II 以「深入定制」接入站点：九篇在侧边栏可达，导览讲清定位、前置与三条阅读路径，全量构建无死链** + +## Performance + +- **Duration:** 约 25 分钟 +- **Started:** 2026-10-21T18:44:00Z（约） +- **Completed:** 2026-10-21T19:09:11Z +- **Tasks:** 4（Task 0 审批门已由派发上下文放行） +- **Files created:** 1 +- **Files modified:** 10 + +## Accomplishments + +- 新增 `docs/advanced/ii/index.md`：说明高级 II 面向的读者、I/II/III 的难度分层、高级 I 与中级前置、九篇索引表、三条阅读路径、边界、D-55 优先插件表与五条自检清单。 +- `docs/.vitepress/config.ts` 的 `/advanced/` 侧边栏新增「高级 II · 深入定制」组并展开，挂满导览与八篇正文共 9 个链接；nav、`/intermediate/`、高级 I / III 组与其它配置未动。 +- 八篇正文末尾统一补「返回[高级 II 导览](./index.md)」；`docs/advanced/index.md` 移除「只收录高级 I」的过时说明，把高级 II 行与继续阅读改为真实链接，高级 III 仍保持占位。 +- prettier 对十篇 `--check` 通过；`pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build` 输出 `build complete`，无 dead link。 + +## Task Commits + +1. **Task 1: 编写高级 II 导览** - `635badf` (docs) +2. **Task 2: 注册高级 II 侧边栏** - `6b4e02f` (docs) +3. **Task 3: 互链收口、格式与全量构建** - `31f89f8` (docs) + +**Plan metadata:** 本 SUMMARY 提交（docs） + +## Files Created/Modified + +- `docs/advanced/ii/index.md` - 高级 II 导览：定位、前置、九篇表、三条阅读路径、边界、D-55 与自检。 +- `docs/.vitepress/config.ts` - `/advanced/` 侧边栏的高级 II 组，9 个链接。 +- `docs/advanced/index.md` - 高级 II 入口与过时说明更新。 +- `docs/advanced/ii/custom-range.md` - 文末返回导览。 +- `docs/advanced/ii/static-vs-dynamic-tiles.md` - 文末返回导览。 +- `docs/advanced/ii/equipment-system.md` - 文末返回导览。 +- `docs/advanced/ii/custom-replay-command.md` - 文末返回导览。 +- `docs/advanced/ii/pathfinding.md` - 文末返回导览。 +- `docs/advanced/ii/adding-hero-attribute.md` - 文末返回导览。 +- `docs/advanced/ii/adding-enemy-attribute.md` - 文末返回导览。 +- `docs/advanced/ii/enemy-context-and-combat.md` - 文末返回导览。 + +## Decisions Made + +- 分组名与九篇文件名按用户确认执行：「高级 II · 深入定制」，导览在前，八篇按 D-67 推荐顺序排列。 +- 导览把三条阅读路径明确为系统定制、行为扩展、按需查阅，并统一建议先读范围对象。 +- 高级 III 只用代码 span 占位，不添加真实链接，避免死链与提前承诺页面。 +- `docs/advanced/index.md` 的层级表把「高级 II · 系统实现」同步为「高级 II · 深入定制」，并把主题列改为本层实际收录内容，保证站点口径一致。 +- 导航栏保持不变，仍为「中级教程 / 高级教程」，高级 II 通过侧边栏进入。 + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 2 - 一致性] 同步高级 I 导览中的旧层级名与旧主题列表** +- **Found during:** Task 3（互链收口） +- **Issue:** `docs/advanced/index.md` 的层级表仍写「高级 II · 系统实现」，主题列含渲染层、加载生命周期等本层未收录内容；「本层不覆盖什么」也沿用了旧主题，与已确认的分组名和实际八篇不一致。 +- **Fix:** 表格行改为「高级 II · 深入定制」并链接 `./ii/`，主题列改为范围、图块、装备、录像指令、寻路、属性与战斗上下文；不覆盖条目改为指向高级 II 导览。 +- **Files modified:** `docs/advanced/index.md` +- **Verification:** prettier `--check` 通过；构建无 dead link。 +- **Committed in:** `31f89f8`（Task 3 提交） + +--- + +**Total deviations:** 1 auto-fixed (1 一致性问题) +**Impact on plan:** 仅修正站点口径，未扩大范围；其余严格按计划执行。 + +## Issues Encountered + +- 构建通过 `cmd /c` 执行，PowerShell 会把 vitepress 的 stderr 输出包装成 RemoteException；以 `$LASTEXITCODE` 与输出中的 `build complete` 为准判定成功。 +- 工作区存在与本计划无关的既有修改 `packages/system/src/hotkey/type.ts`，未纳入任何提交。 + +## Known Stubs + +- 高级 III 在导览与高级 I 导览中仍使用代码 span `高级 III · 原理与架构` 与 `高级 III · <专题>` 占位，按 D-47 不提供页面入口。 +- 八篇正文中的 `TODO(renderer)` / `TODO(editor)` / `TODO(advanced-II)` 为既有 D-47 占位，分别指向渲染端、编辑器/状态栏与怪物图鉴，不属于本计划要接入的数据端内容。 + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- 高级 II 九篇已在站点可见、可导航、可互相跳转，可作为 10-26 读者审阅的入口。 +- 导览的阅读路径是 D-67 推荐顺序的唯一入口，后续若调整篇目顺序需同步本页与侧边栏。 +- 高级 III 页面仍待规划；当前占位不会造成死链。 + +--- + +*Phase: 10-docs-restructure* +*Completed: 2026-10-21* + +## Self-Check: PASSED + +- `docs/advanced/ii/index.md` 存在，提交 `635badf` +- `docs/.vitepress/config.ts` 高级 II 组 9 个链接，提交 `6b4e02f` +- 八篇正文与 `docs/advanced/index.md` 已更新，提交 `31f89f8` +- `.planning/phases/10-docs-restructure/10-25-SUMMARY.md` 存在