mirror of
https://github.com/motajs/template.git
synced 2026-10-24 08:30:16 +08:00
docs(10-25): complete advanced II overview plan
This commit is contained in:
parent
31f89f8b66
commit
f3c4726edd
198
.planning/phases/10-docs-restructure/10-25-SUMMARY.md
Normal file
198
.planning/phases/10-docs-restructure/10-25-SUMMARY.md
Normal file
@ -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` 存在
|
||||
Loading…
Reference in New Issue
Block a user