docs(10): rewrite 10-01 to clear legacy docs + register intermediate; refresh 10-06/10-CONTEXT/ROADMAP

2026-10-18 04:20:17 +08:00 · 2026-10-17 16:36:11 +08:00 · 2026-10-17 16:36:11 +08:00 · 1099583b07
commit 1099583b07
parent 6a42bf42d4
4 changed files with 100 additions and 62 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -551,17 +551,17 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →

 ### Phase 10: 文档重构

-**Goal:** 重构过老、结构不佳、新人难懂的项目文档，面向多背景读者（完全新手 / 不懂代码的作者 / 有基础的作者 / AI Agent）提供分层指南。本阶段采用「伞阶段 + 增量派发」：每次只规划执行一个已派发的具体小任务。**第一批已派发 = 中级教程（`docs/intermediate/`，24 篇中文 markdown）+ 在 VitePress 站点注册它们**（D-01..D-44）。
+**Goal:** 重构过老、结构不佳、新人难懂的项目文档，面向多背景读者（完全新手 / 不懂代码的作者 / 有基础的作者 / AI Agent）提供分层指南。本阶段采用「伞阶段 + 增量派发」：每次只规划执行一个已派发的具体小任务。**第一批已派发 = 中级教程（`docs/intermediate/`，24 篇中文 markdown）+ 在 VitePress 站点注册它们 + 旧内容清空（D-04 并入本批）**（D-01..D-44）。
 **Requirements**: （无专属需求 ID；以 `10-CONTEXT.md` 的 D-01..D-44 为需求基线，验收锚在 D-09：用户人工审阅 + 链接全部有效 + 构建通过）
 **Depends on:** Phase 9
 **Plans:** 6 plans（第一批：中级教程 24 篇 + 站点注册）

 Plans:
- [ ] 10-01-PLAN.md — Wave 0：站点前置与注册（`tsx docs/.vitepress/init.ts` 生成 `apiSidebar.ts`、建 `docs/intermediate/`、`config.ts` 新增 nav 入口 + `sidebar['/intermediate/']` 4 组/24 条；D-13 命名 checkpoint）
+- [ ] 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）
 - [ ] 10-02-PLAN.md — 概念与导航 4 篇（`data-vs-render` / `src-tour` / `code-basics` / `hooks`）
 - [ ] 10-03-PLAN.md — 基础接口 8 篇（`data-state-overview` … `flags`）
 - [ ] 10-04-PLAN.md — 战斗 9 篇（`combat-overview` + 8 篇子系统；N-1/N-2/N-3/N-7 留余地）
 - [ ] 10-05-PLAN.md — 其他 3 篇（`events` / `replay-commands` / `data-plugins`）
 - [ ] 10-06-PLAN.md — 全批验收（构建通过 + 链接有效 + 交付 D-09 人工审阅）

-**说明：** 每篇中级教程遵循 `10-CONTEXT.md` D-21..D-44 的逐篇要点与阅读顺序（4/8/9/3）。文档仅新增 `docs/intermediate/*.md` 与修改 `docs/.vitepress/config.ts`；**不**触碰 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`（旧内容删除为 D-04 的后续派发）。构建命令须先跑 `tsx docs/.vitepress/init.ts`（`config.ts:3` 静态 import `./apiSidebar`，该文件 gitignored 且当前缺失）。本机 PowerShell 禁止 `pnpm.ps1`，命令经 `cmd /c "..."` / `pnpm.cmd` 执行。
+**说明：** 每篇中级教程遵循 `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 "..."` 执行。
--- a/.planning/phases/10-docs-restructure/10-01-PLAN.md
+++ b/.planning/phases/10-docs-restructure/10-01-PLAN.md
@ -6,32 +6,45 @@ wave: 1
 depends_on: []
 files_modified:
  - docs/.vitepress/config.ts
+  - docs/.vitepress/api.ts
+files_deleted:
+  - docs/index.md
+  - docs/guide/**
+  - docs/dev/**
+  - docs/logger/**
+  - docs/api/**
 autonomous: false
 requirements: []
 user_setup: []
 estimate:
  tokens: 22000
-  raw_tokens: 15000
+  raw_tokens: 22000
  tasks: 2
  confidence: low
 must_haves:
  truths:
-    - "顶栏 `nav` 出现「中级教程」入口，指向 `/intermediate/data-vs-render`，且既有 `主页/指南/API/错误代码` 四条逐字不变"
+    - "旧文档树 `docs/guide/`、`docs/dev/`、`docs/logger/`、`docs/api/` 与首页 `docs/index.md` 已从仓库删除"
+    - "`docs/.vitepress/config.ts` 不再含指向已删内容的旧 nav 条目（主页 / 指南 / API / 错误代码），也不再含指向已删章节的旧 sidebar 键（guide / logger / api 三个路径前缀）"
+    - "`docs/.vitepress/config.ts` 不再静态 import `./apiSidebar`，也不再 import `./api` 的 `generateSidebar`；构建不再依赖生成物"
+    - "`docs/api/` 侧边栏生成机制在目录缺失时安全跳过：`tsx docs/.vitepress/init.ts` 不再抛错（`docs:dev` 与构建前置命令均可运行）"
+    - "顶栏 `nav` 出现「中级教程」入口，指向 `/intermediate/data-vs-render`"
    - "侧边栏新增 `'/intermediate/'` 键，含 4 个分组（概念与导航 / 基础接口 / 战斗 / 其他）、共 24 条链接，顺序为 D-20 的 4/8/9/3"
-    - "既有 `'/guide/'`、`'/logger/'`、`'/api/'` 三个 sidebar 键与既有 nav 条目零改动"
-    - "`docs:build` 在生成 `apiSidebar.ts` 后成功通过"
+    - "旧内容删除后 `cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\"` 通过（打印 build complete，无 dead link / import 错误）"
  artifacts:
-    - "docs/.vitepress/config.ts（仅新增 nav 一条 + sidebar['/intermediate/'] 键）"
+    - "docs/.vitepress/config.ts（移除旧 nav/sidebar 键与 apiSidebar/api 依赖；新增 nav 一条 + sidebar['/intermediate/'] 键）"
+    - "docs/.vitepress/api.ts（generateSidebar 缺失目录守卫）"
+    - "docs/intermediate/（空目录，供后续写作计划落点）"
  key_links:
-    - "config.ts:3 静态 import './apiSidebar' ← 依赖 docs/.vitepress/init.ts 生成（否则构建起步即失败）"
-    - "config.ts:59-156 既有 guide/logger/api sidebar 键必须逐字保留"
+    - "config.ts 曾静态 import './apiSidebar'（依赖 init.ts 生成）——本计划移除该依赖，构建不再依赖生成物"
+    - "docs/.vitepress/api.ts 的 generateSidebar() 扫描 docs/api/；目录删除后须加守卫，否则 init.ts / docs:dev 抛 ENOENT"
+    - "24 条 sidebar link ⇄ D-20 的 24 个文件名（一一对应，缺一即 D-09 人工审阅不通过）"
 ---

 <objective>
-在中级教程正文成批编写之前，先把 24 篇的**站点注册**落地：生成构建前置文件 `docs/.vitepress/apiSidebar.ts`、创建 `docs/intermediate/` 目录、在 `docs/.vitepress/config.ts` 新增顶栏入口与 `'/intermediate/'` 侧边栏分组。
+把「旧内容清空 + 站点注册」作为一个 Wave 0 计划落地：删除过老、与当前实现脱节的旧文档树（`docs/guide`、`docs/dev`、`docs/logger`、`docs/api`）与首页 `docs/index.md`；清理 `docs/.vitepress/config.ts` 中指向这些内容的旧 `nav`/`sidebar` 键，并解除它对 API 侧边栏生成物的静态依赖；在 `docs/api/` 目录缺失时让 `generateSidebar()` 安全跳过，保证站点仍可构建；随后注册 24 篇中级教程的顶栏入口与 `'/intermediate/'` 侧边栏分组。

-Purpose: 没有侧边栏注册，24 篇会「写了但看不见」，D-09 的人工审阅将直接不通过（RESEARCH Pitfall 1）；没有 `apiSidebar.ts`，`docs:build` 会因 `config.ts:3` 的静态 import 失败（RESEARCH Pitfall 2）。本计划是后续全部写作计划的硬前置（Wave 0）。
-Output: 已注册的 `docs/.vitepress/config.ts` + 已生成的 `docs/.vitepress/apiSidebar.ts`（gitignored，不提交）+ 空目录 `docs/intermediate/`。
+Purpose: D-04（旧内容全部删除重写）**已并入本批**——这是后续全部写作计划的硬前置（Wave 0）。删除后站点才摆脱既有的 dead-link 构建失败（原为 `docs/dev/store/tile-store.md` 的 3 处死链），构建转绿；没有侧边栏注册，24 篇会「写了但看不见」，D-09 的人工审阅将直接不通过（RESEARCH Pitfall 1）；没有 `apiSidebar.ts` / 生成守卫，`docs:build` 或 `docs:dev` 会在起步即因 import / ENOENT 失败（RESEARCH Pitfall 2）。
+Output: 已清空的 `docs/`（无旧内容）+ 已清理并注册好的 `docs/.vitepress/config.ts` + 带缺失目录守卫的 `docs/.vitepress/api.ts` + 空目录 `docs/intermediate/`。
 </objective>

 <execution_context>
@ -45,50 +58,62 @@ Output: 已注册的 `docs/.vitepress/config.ts` + 已生成的 `docs/.vitepress
@.planning/STATE.md
@.planning/phases/10-docs-restructure/10-CONTEXT.md
@.planning/phases/10-docs-restructure/10-RESEARCH.md
-@.planning/phases/10-docs-restructure/10-PATTERNS.md
-@.planning/phases/10-docs-restructure/10-VALIDATION.md
@docs/.vitepress/config.ts
@docs/.vitepress/init.ts
+@docs/.vitepress/api.ts

-**约定（dev.md / AGENTS.md）：**
- 本批只改 `docs/intermediate/*`（新增）与 `docs/.vitepress/config.ts`（注册）；**禁止**删除或修改 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`，**禁止**改动既有 `nav`/`sidebar` 的 guide/logger/api 键（D-14）。
- 本机 PowerShell 禁止运行 `pnpm.ps1`/`npx.ps1`，命令一律经 `cmd /c "..."` 或 `pnpm.cmd` 执行（RESEARCH Environment Availability）。
+**约定（dev.md / AGENTS.md / D-14）：**
+- 本批范围经用户明确扩展：**旧内容删除并入本批**（D-04 已更新）。删除对象仅限 `docs/guide/`、`docs/dev/`、`docs/logger/`、`docs/api/`、`docs/index.md`；不改动 `src/`、`packages/`、`packages-user/` 任何生产代码。
+- 保留 `docs/.vitepress/api.ts` 的按包生成机制（D-03）——本次仅加「`docs/api/` 缺失即跳过」的守卫，**不改扫描逻辑**，供后续 API 参考重建使用。
+- 24 条显示名（nav `中级教程`、四个分组标题「概念与导航 / 基础接口 / 战斗 / 其他」、24 条条目标题）**已在此前获批**（D-13），本计划不再重复申请；本计划不新增任何公共 / 受保护 / 私有方法或字段命名。
+- 本机 PowerShell 禁止运行 `pnpm.ps1`/`npx.ps1`，命令一律经 `cmd /c "..."` 执行（RESEARCH Environment Availability）。
+- 说明：`docs/` 下旧内容删除后已无 markdown 页面；VitePress 在构建期总会注入一个虚拟 `404.md` 页面（`node_modules/vitepress/dist/node/chunk-*.js` 中 `["404.md", ...siteConfig.pages]`），故零页面时构建仍可成功。
 </context>

 <tasks>

 <task type="checkpoint:human-verify" gate="blocking-human">
-  <name>Task 0: 向用户汇报本计划并申请 D-13 命名批准</name>
-  <action>在写入任何文件之前，向用户汇报本计划内容并停下等待。汇报须包含：**要做什么**（在 VitePress 站点注册中级教程的顶栏入口与侧边栏分组，并生成本地构建前置文件）、**为什么**（24 篇正文没有侧边栏注册会「写了但看不见」，且缺 `apiSidebar.ts` 会导致构建失败）、**大致怎么做**（先 `tsx docs/.vitepress/init.ts` 生成 `apiSidebar.ts`、创建 `docs/intermediate/` 目录，再在 `config.ts` 的 `nav` 新增一条、`sidebar` 新增 `'/intermediate/'` 键）、**影响范围**（仅 `docs/.vitepress/config.ts` 一个受跟踪文件被修改，外加一个 gitignored 生成文件）。同时按 D-13 **申请新增命名的批准**，逐条列出：(a) `nav` 新条目显示名 `中级教程`（`link: '/intermediate/data-vs-render'`）；(b) 四个分组标题 `概念与导航` / `基础接口` / `战斗` / `其他`；(c) 24 条侧边栏显示名——`数据端与渲染端` / `src 导览` / `代码基础` / `钩子` / `数据端总览` / `勇士属性` / `勇士道具` / `勇士装备` / `勇士位置` / `地图结构` / `地图图块` / `Flag 变量` / `战斗总览` / `怪物特殊属性` / `光环` / `查询效果` / `最终属性` / `伤害计算` / `地图伤害` / `战斗脚本` / `状态钩子` / `自定义事件` / `录像指令` / `数据插件`（分别对应 D-20 文件名 `data-vs-render` / `src-tour` / `code-basics` / `hooks` / `data-state-overview` / `hero-attribute` / `hero-items` / `hero-equipment` / `hero-location` / `map-structure` / `map-tiles` / `flags` / `combat-overview` / `enemy-specials` / `enemy-aura` / `enemy-query` / `enemy-final` / `enemy-calculator` / `enemy-map-damage` / `enemy-combat-script` / `enemy-status-hooks` / `events` / `replay-commands` / `data-plugins`）。在收到用户明确回复「可以执行」四个字、且对上述命名给出（可含微调的）确认之前，不得开始 Task 1 的任何一步，也不得派发执行子代理。  </action>
-  <what-built>本计划内容：在 VitePress 站点注册中级教程的顶栏入口与 `'/intermediate/'` 侧边栏分组（4 组 / 24 条），并生成本地构建前置文件 `apiSidebar.ts`；申请 D-13 命名的批准。</what-built>
-  <how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段；逐条审阅 nav 显示名 `中级教程`、四个分组标题、24 条显示名，确认或提出修改。</how-to-verify>
-  <resume-signal>回复「可以执行」以继续；如对命名有修改，请一并给出，待修正后再回复「可以执行」。其它回复视为未批准，本计划停在此处。</resume-signal>
+  <name>Task 0: 向用户汇报本计划（清空旧内容 + 站点注册）并等待「可以执行」</name>
+  <action>在删除或写入任何文件之前，向用户汇报本计划并停下等待。汇报须包含：**要做什么**（① 删除旧文档树 `docs/guide`、`docs/dev`、`docs/logger`、`docs/api` 及首页 `docs/index.md`；② 清理 `docs/.vitepress/config.ts` 中指向这些内容的旧 `nav`/`sidebar` 键，并解除它对 API 侧边栏生成物的静态依赖；③ 给 `docs/.vitepress/api.ts` 的 `generateSidebar()` 加缺失目录守卫，使 `docs/api/` 不存在时生成逻辑安全跳过、站点仍可构建；④ 注册 24 篇中级教程的顶栏入口与 `'/intermediate/'` 侧边栏分组（4 组 / 24 条，顺序 4/8/9/3））、**为什么**（D-04 旧内容删除已并入本批：删除后站点摆脱既有 dead-link 构建失败、构建转绿；且没有侧边栏注册，24 篇会「写了但看不见」，D-09 人工审阅不通过；没有生成守卫，`init.ts` 会因 `docs/api` 缺失抛 ENOENT）、**大致怎么做**（先删旧文档，再就地编辑 `config.ts` 去掉旧键与 apiSidebar/api 依赖，给 `api.ts` 加守卫，最后新增 intermediate 注册；以 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 验证）、**影响范围**（仅 `docs/**` 文档与站点配置；不动 `src/`、`packages/`、`packages-user/`；`docs/.vitepress/apiSidebar.ts` 为 gitignored 生成物；被删文件受 git 跟踪，误删可回滚）。
+命名状态：24 条显示名已于此前获批（D-13），本计划不新增任何方法 / 字段命名，故无需再申请命名批准。在收到用户明确回复「可以执行」四个字之前，不得开始 Task 1 / Task 2 的任何一步，也不得派发执行子代理。</action>
+  <what-built>本计划内容：清空旧文档内容（guide / dev / logger / api 与首页）、清理站点配置并保留 API 生成机制、注册 24 篇中级教程的 nav 入口与侧边栏分组。</what-built>
+  <how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认删除范围与站点注册做法无异议。</how-to-verify>
+  <resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
  <verify>
-    <human-check>用户已回复「可以执行」，并对 nav 显示名、四个分组标题、24 条显示名给出确认或修改意见。</human-check>
+    <human-check>用户已回复「可以执行」。</human-check>
  </verify>
-  <done>用户回复「可以执行」且命名经批准（含修改）；未获批准前本计划不得继续。</done>
+  <done>用户回复「可以执行」。</done>
 </task>

 <task type="auto">
-  <name>Task 1: 生成 apiSidebar.ts 并创建 docs/intermediate/ 目录</name>
-  <files>docs/.vitepress/apiSidebar.ts, docs/intermediate/</files>
-  <action>先生成构建前置文件，再准备正文目录。执行 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts"`，它会运行 `docs/.vitepress/api.ts` 的 `generateSidebar()` 并写出 `docs/.vitepress/apiSidebar.ts`（该文件被 `.gitignore:54` 忽略，属本地生成物，不提交）。随后创建目录 `docs/intermediate/`（`New-Item -ItemType Directory -Force -Path docs/intermediate`）——它在第一次写入正文前是空的，git 不跟踪空目录，本步仅为让后续写作计划与本地预览有落点。不要触碰 `docs/.vitepress/api.ts`、`init.ts` 或既有 `apiSidebar.ts` 的生成逻辑（D-14 越界红线；RESEARCH Anti-Patterns）。</action>
+  <name>Task 1: 删除旧文档树与首页，清理 config.ts，并为 apiSidebar 生成加缺失目录守卫</name>
+  <files>docs/index.md, docs/guide/, docs/dev/, docs/logger/, docs/api/, docs/.vitepress/config.ts, docs/.vitepress/api.ts</files>
+  <precondition>工作树中的 `docs/.vitepress/config.ts` 处于 HEAD 基线，即不含被本计划取代的未提交 `'/intermediate/'` 编辑；若 `git status --porcelain docs/.vitepress/config.ts` 非空，先 `git restore docs/.vitepress/config.ts` 回到 HEAD 再开始。</precondition>
+  <action>分三步执行，且保持站点可构建。
+
+  (1) 删除旧内容：删除文件 `docs/index.md`，并递归删除目录 `docs/guide/`、`docs/dev/`、`docs/logger/`、`docs/api/`（连同其中全部文件与子目录，例如 `docs/guide/img/`、`docs/api/*/` 等）。用文件系统删除（如 `Remove-Item -Recurse -Force`），使 git 把这些受跟踪路径记为删除；不要遗留空目录。删除白名单严格限定为上述五个路径，绝不触碰 `docs/intermediate/`、`docs/.vitepress/`。
+
+  (2) 就地编辑 `docs/.vitepress/config.ts`（最小作用域 Edit）：从首部静态 import 中删除两条属 API 侧边栏机制的导入——从 `./apiSidebar` 导入的默认值（第 3 行），以及从 `./api` 导入的 `generateSidebar`（第 5 行）；删除仅在开发期调用 `generateSidebar` 的 `listenSidebar()` 函数定义及其在 `vite.plugins` 数组中的调用（`MermaidPlugin()` 保留、`optimizeDeps.include` 与 `ssr.noExternal` 保留）。从 `themeConfig.nav` 删除四条指向已删内容的旧入口（主页 / 指南 / API / 错误代码），nav 数组留待 Task 2 写入「中级教程」一条。从 `themeConfig.sidebar` 删除三个指向已删章节的旧键（分别对应 guide、logger、api 三个路径前缀）及其中全部内容。其余配置（`title` / `description` / `base` / `markdown` / `outDir` / `socialLinks` / `search` / `locales`）逐字保留。
+
+  (3) 编辑 `docs/.vitepress/api.ts`：在 `generateSidebar()` 入口处加一个「`docs/api` 目录不存在时直接 `return`」的守卫，使 `docs/api/` 被删除后 `tsx docs/.vitepress/init.ts`（以及依赖它的 `docs:dev`）不再因对缺失目录 `readdir` 抛错。守卫用 `node:fs` 的 `existsSync` 判断（dev.md 禁止 try-catch）；新增的 `import { existsSync } from 'node:fs';` 放在文件首部既有 import 之后、import 之间不得插注释或空行。**不改动** `generateSidebar()` 的扫描 / 命名 / 排序 / 写文件逻辑（D-03：保留按包生成机制，供后续 API 参考重建）。若工作区残留 gitignored 的 `docs/.vitepress/apiSidebar.ts`，一并删除（已无消费者，且为会被覆盖的生成物）。
+
+  完成三步后运行构建命令确认站点通过。删除后 `docs/` 下已无 markdown 页面，VitePress 总会注入虚拟 `404.md`，故零页面时构建仍可成功；本步只需验证「无 import / dead-link 失败」。</action>
  <verify>
-    <automated>cmd /c "pnpm exec tsx docs/.vitepress/init.ts"; if ($?) { if (-not (Test-Path docs/.vitepress/apiSidebar.ts)) { exit 1 }; if (-not (Test-Path docs/intermediate)) { exit 1 }; echo "W0-PREP-OK" } else { exit 1 }</automated>
-    <fails_when>non-zero exit, or output lacks "W0-PREP-OK", or docs/.vitepress/apiSidebar.ts / docs/intermediate/ 不存在</fails_when>
+    <automated>$ErrorActionPreference='Stop'; $gone=@('docs/guide','docs/dev','docs/logger','docs/api','docs/index.md'); foreach($p in $gone){ if(Test-Path $p){ Write-Error "STILL-PRESENT $p" } }; $cfg=[IO.File]::ReadAllText((Resolve-Path 'docs/.vitepress/config.ts')); if($cfg -match "'/guide/'"){ Write-Error "CFG-OLD-GUIDE-KEY" }; if($cfg -match "'/logger/'"){ Write-Error "CFG-OLD-LOGGER-KEY" }; if($cfg -match "'/api/'"){ Write-Error "CFG-OLD-API-KEY" }; if($cfg -match "apiSidebar"){ Write-Error "CFG-APISIDEBAR-IMPORT" }; if($cfg -match "listenSidebar"){ Write-Error "CFG-LISTENSIDEBAR" }; if($cfg -match "generateSidebar"){ Write-Error "CFG-GENERATESIDEBAR" }; $api=[IO.File]::ReadAllText((Resolve-Path 'docs/.vitepress/api.ts')); if($api -notmatch "existsSync"){ Write-Error "API-NO-GUARD" }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; exit 1 }; $txt = $out -join "`n"; if($txt -notmatch 'build complete'){ Write-Error "NO-BUILD-COMPLETE" }; if($txt -match 'dead link'){ Write-Error "DEAD-LINK" }; if($txt -match 'Failed to resolve import'){ Write-Error "IMPORT-FAIL" }; Write-Output 'W0-CLEAR-OK'</automated>
+    <fails_when>non-zero exit, or output contains "STILL-PRESENT", "CFG-OLD-", "CFG-APISIDEBAR-IMPORT", "CFG-LISTENSIDEBAR", "CFG-GENERATESIDEBAR", "API-NO-GUARD", "NO-BUILD-COMPLETE", "DEAD-LINK", or "IMPORT-FAIL", or output lacks "W0-CLEAR-OK"</fails_when>
  </verify>
-  <done>`docs/.vitepress/apiSidebar.ts` 已生成且非空，`docs/intermediate/` 目录已存在；两文件之外的仓库内容零改动。</done>
+  <done>旧文档树与首页已删除；`config.ts` 不再含旧 nav/sidebar 键与 apiSidebar/api 导入；`api.ts` 含缺失目录守卫；`tsx docs/.vitepress/init.ts` 不抛错且 `docs:build` 打印 build complete、无 dead link / import 错误；输出 W0-CLEAR-OK。</done>
 </task>

 <task type="auto">
  <name>Task 2: 在 config.ts 注册 nav 入口与 '/intermediate/' 侧边栏分组</name>
-  <files>docs/.vitepress/config.ts</files>
-  <action>用**就地编辑（Edit，最小作用域）**修改 `docs/.vitepress/config.ts`，只做两处新增、不动任何既有键。(1) 在 `nav` 数组（现为 `config.ts:53-58`）末尾追加一条 `{ text: '中级教程', link: '/intermediate/data-vs-render' }`，保留既有 `主页`/`指南`/`API`/`错误代码` 四条逐字不变。(2) 在 `sidebar` 对象（现为 `config.ts:59-156`）中新增 `'/intermediate/'` 键，其值为一个 `{ text: '中级教程', collapsed: false, items: [...] }`，`items` 内按 D-20 顺序嵌套四个分组：`概念与导航`（`data-vs-render` / `src-tour` / `code-basics` / `hooks`）、`基础接口`（`data-state-overview` / `hero-attribute` / `hero-items` / `hero-equipment` / `hero-location` / `map-structure` / `map-tiles` / `flags`）、`战斗`（`combat-overview` / `enemy-specials` / `enemy-aura` / `enemy-query` / `enemy-final` / `enemy-calculator` / `enemy-map-damage` / `enemy-combat-script` / `enemy-status-hooks`）、`其他`（`events` / `replay-commands` / `data-plugins`）。每条写为 `{ text: '<Task 0 已批准的显示名>', link: '/intermediate/<文件名>' }`（绝对路径、不带 `.md`，写法和 `config.ts:64-124` 既有条目一致；分组嵌套写法参照 `config.ts:70-86`）。`'/guide/'`、`'/logger/'`、`'/api/'` 三个键与其中全部内容**逐字保留**。新增后运行构建命令确认站点可通过（命令本身先跑 init.ts，避免 `config.ts:3` 的 import 失败）。</action>
+  <files>docs/.vitepress/config.ts, docs/intermediate/</files>
+  <action>用**就地编辑（Edit，最小作用域）**修改 `docs/.vitepress/config.ts`，只做两处新增，并对 Task 1 已清空的 nav/sidebar 收尾。(1) 在 `nav` 数组写入一条 `{ text: '中级教程', link: '/intermediate/data-vs-render' }`（Task 1 已移除四条旧入口，此处之后 nav 仅此一条）。(2) 在 `sidebar` 对象中新增 `'/intermediate/'` 键，其值为一个 `{ text: '中级教程', collapsed: false, items: [...] }`，`items` 内按 D-20 顺序嵌套四个分组：`概念与导航`（`data-vs-render` / `src-tour` / `code-basics` / `hooks`）、`基础接口`（`data-state-overview` / `hero-attribute` / `hero-items` / `hero-equipment` / `hero-location` / `map-structure` / `map-tiles` / `flags`）、`战斗`（`combat-overview` / `enemy-specials` / `enemy-aura` / `enemy-query` / `enemy-final` / `enemy-calculator` / `enemy-map-damage` / `enemy-combat-script` / `enemy-status-hooks`）、`其他`（`events` / `replay-commands` / `data-plugins`）。每条写为 `{ text: '<已获批显示名>', link: '/intermediate/<文件名>' }`（绝对路径、不带 `.md`，写法与既有条目一致；分组嵌套写法参照 `'/guide/'` 原嵌套形状），显示名沿用此前获批的：`数据端与渲染端` / `src 导览` / `代码基础` / `钩子` / `数据端总览` / `勇士属性` / `勇士道具` / `勇士装备` / `勇士位置` / `地图结构` / `地图图块` / `Flag 变量` / `战斗总览` / `怪物特殊属性` / `光环` / `查询效果` / `最终属性` / `伤害计算` / `地图伤害` / `战斗脚本` / `状态钩子` / `自定义事件` / `录像指令` / `数据插件`（依次对应上述 24 个文件名）。创建目录 `docs/intermediate/`（`New-Item -ItemType Directory -Force -Path docs/intermediate`），本步仅为后续写作计划与本地预览提供落点（git 不跟踪空目录）。新增后运行构建命令确认站点通过（命令先跑 init.ts，init.ts 现已在 `docs/api/` 缺失时安全跳过）。</action>
  <verify>
-    <automated>cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"</automated>
-    <fails_when>non-zero exit, or output contains "dead link(s) found.", or "Failed to resolve import", or the build does not print "build complete"</fails_when>
+    <automated>$ErrorActionPreference='Stop'; $names=@('data-vs-render','src-tour','code-basics','hooks','data-state-overview','hero-attribute','hero-items','hero-equipment','hero-location','map-structure','map-tiles','flags','combat-overview','enemy-specials','enemy-aura','enemy-query','enemy-final','enemy-calculator','enemy-map-damage','enemy-combat-script','enemy-status-hooks','events','replay-commands','data-plugins'); $cfg=[IO.File]::ReadAllText((Resolve-Path 'docs/.vitepress/config.ts')); if($cfg -notmatch "text: '中级教程'"){ Write-Error "NO-NAV-ENTRY" }; if($cfg -notmatch "link: '/intermediate/data-vs-render'"){ Write-Error "NO-NAV-TARGET" }; if($cfg -notmatch "'/intermediate/'"){ Write-Error "NO-INTERMEDIATE-KEY" }; $targets=[regex]::Matches($cfg,"link:\s*'/intermediate/([a-z-]+)'") | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; $want=$names | Sort-Object -Unique; if(($targets -join ',') -ne ($want -join ',')){ Write-Error ("SIDEBAR-TARGETS " + ($targets -join ',')) }; foreach($g in @('概念与导航','基础接口','战斗','其他')){ if($cfg -notmatch [regex]::Escape("text: '$g'")){ Write-Error "NO-GROUP $g" } }; if(-not (Test-Path 'docs/intermediate')){ Write-Error "NO-INTERMEDIATE-DIR" }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; exit 1 }; $txt = $out -join "`n"; if($txt -notmatch 'build complete'){ Write-Error "NO-BUILD-COMPLETE" }; if($txt -match 'dead link'){ Write-Error "DEAD-LINK" }; if($txt -match 'Failed to resolve import'){ Write-Error "IMPORT-FAIL" }; Write-Output 'W0-REGISTER-OK'</automated>
+    <fails_when>non-zero exit, or output contains "NO-NAV-ENTRY", "NO-NAV-TARGET", "NO-INTERMEDIATE-KEY", "SIDEBAR-TARGETS", "NO-GROUP", "NO-INTERMEDIATE-DIR", "NO-BUILD-COMPLETE", "DEAD-LINK", or "IMPORT-FAIL", or output lacks "W0-REGISTER-OK"</fails_when>
  </verify>
-  <done>config.ts 仅新增 nav 一条与 `'/intermediate/'` sidebar 键（24 条 link、4 个分组，顺序 4/8/9/3）；既有 guide/logger/api 键与 nav 条目零 diff；`docs:build` 通过并打印 build complete。</done>
+  <done>`config.ts` 新增 nav 一条与 `'/intermediate/'` sidebar 键（去重后恰 24 条 link、4 个分组，顺序 4/8/9/3）；`docs/intermediate/` 目录存在；`docs:build` 通过并打印 build complete；输出 W0-REGISTER-OK。</done>
 </task>

 </tasks>
@ -99,29 +124,34 @@ Output: 已注册的 `docs/.vitepress/config.ts` + 已生成的 `docs/.vitepress
 | Boundary | Description |
 |----------|-------------|
 | 构建期 markdown/config → 静态站点 | 配置与文档内容由构建期静态处理，无运行时用户输入 |
+| 仓库工作树 → 版本历史 | 本计划删除受 git 跟踪的旧文档，属可回滚的工作树改动 |
 | 站点 → 浏览器读者 | 外链是唯一的对外指向面 |

 ## STRIDE Threat Register

 | Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
 |-----------|----------|-----------|----------|-------------|-----------------|
-| T-10-01 | Tampering | `docs/.vitepress/config.ts` 新增内容 | low | mitigate | 只新增 `nav`/`sidebar` 静态文本条目，不写原始 HTML/`<script>`；不改动构建插件与 api 生成逻辑 |
-| T-10-02 | Spoofing | 本计划不引入任何外链 | low | accept | 唯一获批外链（D-23 的 `h5mota.com` 论坛）在后续正文计划引入；本计划无外链面 |
-| T-10-03 | Information Disclosure | 配置示例 | low | mitigate | 不写入任何密钥/内部账号；只引用仓库已公开的路径与接口名 |
+| T-10-01 | Tampering | `docs/.vitepress/config.ts` / `api.ts` 编辑 | low | mitigate | 仅编辑站点配置：移除旧 nav/sidebar 键、加缺失目录守卫；不写原始 HTML/`<script>`；不改 `generateSidebar()` 扫描逻辑 |
+| T-10-02 | Tampering / 误删（可用性） | 旧文档树删除 | low | mitigate | 删除路径为显式白名单（guide/dev/logger/api/index.md），步骤中不触碰 `src`/`packages*`/`docs/intermediate`；删除经 git 跟踪，误删可 `git restore` 回滚 |
+| T-10-03 | Spoofing | 本计划不引入任何外链 | low | accept | 唯一获批外链（D-23 的 `h5mota.com` 论坛）在后续正文计划引入；本计划无外链面 |
+| T-10-04 | Information Disclosure | 配置示例 | low | mitigate | 不写入任何密钥 / 内部账号；只引用仓库已公开的路径与接口名 |
 | T-10-SC | Tampering | npm/pip/cargo installs | low | accept | 本阶段**不安装任何包**（纯文档 + 站点配置），无供应链安装面 |
 </threat_model>

 <verification>
 - 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 通过（打印 build complete，无 dead link / import 错误）。
- 结构门禁（静态）：`docs/.vitepress/config.ts` 的 `'/intermediate/'` 键恰含 4 个分组、24 条 `link`，与 D-20 顺序一一对应。
- 越界门禁：`git diff --name-only` 中仅出现 `docs/.vitepress/config.ts`（外加 gitignored、未跟踪的 `apiSidebar.ts` 与本地空目录）。
+- 删除门禁：`docs/guide/`、`docs/dev/`、`docs/logger/`、`docs/api/`、`docs/index.md` 均不存在。
+- 配置门禁：`config.ts` 无旧 nav/sidebar 键、无 apiSidebar/api 依赖；`api.ts` 含缺失目录守卫。
+- 结构门禁（静态）：`config.ts` 的 `'/intermediate/'` 键去重后恰含 24 条 `link` 与 4 个分组标题，与 D-20 顺序一一对应。
+- 越界门禁：`git status` 中仅出现 `docs/**` 的删除与 `docs/.vitepress/config.ts`、`docs/.vitepress/api.ts` 的修改（外加 gitignored、未跟踪的生成物与本地空目录）。
 </verification>

 <success_criteria>
- `docs/.vitepress/config.ts` 已注册 `nav` 入口与 `'/intermediate/'` 侧边栏（4 组 / 24 条，顺序 4/8/9/3），既有键零改动。
- `docs/.vitepress/apiSidebar.ts` 已生成，`docs/intermediate/` 目录已存在。
- `docs:build` 通过。
- 显示名经用户 D-13 批准。
+- 旧文档树与首页已删除；`docs/` 下不再残留旧内容。
+- `config.ts` 已注册 nav 入口与 `'/intermediate/'` 侧边栏（4 组 / 24 条，顺序 4/8/9/3），旧键已清除。
+- `api.ts` 生成机制在 `docs/api/` 缺失时安全跳过；`docs:build` 通过。
+- `docs/intermediate/` 目录存在。
+- 无越界改动（不改 `src/`、`packages/`、`packages-user/`）。
 </success_criteria>

 <output>
--- a/.planning/phases/10-docs-restructure/10-06-PLAN.md
+++ b/.planning/phases/10-docs-restructure/10-06-PLAN.md
@ -16,8 +16,9 @@ estimate:
 must_haves:
  truths:
    - "`docs/intermediate/` 下恰有 D-20 的 24 个 kebab-case markdown 文件"
-    - "`docs/.vitepress/config.ts` 的 `'/intermediate/'` 侧边栏含 4 分组、24 条 link，顺序为 4/8/9/3 且与 24 个文件名一一对应"
-    - "`docs:build` 通过且无 dead link；构建产物出现在 `public/_docs`"
+    - "`docs/.vitepress/config.ts` 的 `'/intermediate/'` 侧边栏含 4 分组、24 条 link（去重后恰 24 个目标），顺序为 4/8/9/3 且与 24 个文件名一一对应"
+    - "旧内容删除基线成立：`docs/guide/`、`docs/dev/`、`docs/logger/`、`docs/api/` 与首页 `docs/index.md` 均不存在（首页本批有意缺省）"
+    - "`docs:build` 通过且 dead-link 数为 0；构建产物出现在 `public/_docs`"
    - "站内链接全部可解析；唯一外链为 D-23 指定的 `h5mota.com` 论坛链接"
    - "用户完成人工审阅（D-09：内容正确、可读、无元叙述）"
  artifacts:
@ -25,12 +26,13 @@ must_haves:
  key_links:
    - "24 篇正文 ⇄ config.ts 的 24 条 sidebar link（一一对应，缺一即人工审阅不通过）"
    - "构建期 VitePress 链接解析覆盖所有正文互链（RESEARCH A3）"
+    - "本批构建基线 = 旧内容删除后的零 dead-link（10-01 清空 guide/dev/logger/api 与首页）"
 ---

 <objective>
-全批验收：确认 24 篇中级教程全部落位、站点注册完整、构建通过、链接有效，并把站点交付用户做 D-09 人工审阅。
+全批验收：确认旧内容删除基线成立（`docs/guide`、`docs/dev`、`docs/logger`、`docs/api` 与首页 `docs/index.md` 均已移除）、24 篇中级教程全部落位、站点注册完整、构建通过、链接有效，并把站点交付用户做 D-09 人工审阅。

-Purpose: 满足 D-09 验收标准（用户人工审阅 + 链接全部有效 + 构建通过）的机器可核部分，并为人工审阅提供明确入口。
+Purpose: 满足 D-09 验收标准（用户人工审阅 + 链接全部有效 + 构建通过）的机器可核部分，并为人工审阅提供明确入口。旧内容删除后 dead-link 数为 0，构建应转绿（删除前为 `docs/dev/store/tile-store.md` 的 3 处死链）。
 Output: 验收摘要 `10-06-SUMMARY.md`；站点构建产物 `public/_docs`（gitignored）。
 </objective>

@ -46,6 +48,8 @@ Output: 验收摘要 `10-06-SUMMARY.md`；站点构建产物 `public/_docs`（gi
@docs/.vitepress/config.ts

 **约定：** 本计划只做验收，不新增/修改任何文档或配置；如发现缺页或链接错误，只报告并回到对应写作计划修复，不在本计划内擅自补写。
+
+**验收基线（本批随 10-01 变更）：** 旧内容（`docs/guide`、`docs/dev`、`docs/logger`、`docs/api` 与首页 `docs/index.md`）已于 10-01 随本批删除，本批 dead-link 数应为 0；首页 `docs/index.md` 本批**有意缺省**，不作为缺页问题。
 </context>

 <tasks>
@ -65,17 +69,17 @@ Output: 验收摘要 `10-06-SUMMARY.md`；站点构建产物 `public/_docs`（gi
 <task type="auto">
  <name>Task 1: 全量构建 + 静态验收核对</name>
  <files>docs/.vitepress/config.ts</files>
-  <action>先跑全量构建，再做静态核对。(1) 构建：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，确认打印 build complete、无 `dead link(s) found.`、无 `Failed to resolve import`，且产物目录 `public/_docs` 已生成。(2) 静态核对 24 个文件：`docs/intermediate/` 下恰存在 D-20 的 24 个文件名（`data-vs-render`/`src-tour`/`code-basics`/`hooks`/`data-state-overview`/`hero-attribute`/`hero-items`/`hero-equipment`/`hero-location`/`map-structure`/`map-tiles`/`flags`/`combat-overview`/`enemy-specials`/`enemy-aura`/`enemy-query`/`enemy-final`/`enemy-calculator`/`enemy-map-damage`/`enemy-combat-script`/`enemy-status-hooks`/`events`/`replay-commands`/`data-plugins`，各加 `.md`）；每个文件 CRLF、单 H1。(3) 核对 `config.ts` 的 `'/intermediate/'` 键恰含 24 条 `link: '/intermediate/<名>'`，且与 24 个文件名一一对应。(4) 外链白名单：全 24 篇内出现的外链仅为 `https://h5mota.com/bbs/thread/?tid=1018&p=3#p41`（若文本中还出现其它 `http`，逐一报告供用户判断，不擅自删改）。发现任何缺页/错链只报告，不擅自补写。</action>
+  <action>先跑全量构建，再做静态核对。(1) 构建：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，确认打印 build complete、无 dead link、无 `Failed to resolve import`，且产物目录 `public/_docs` 已生成；旧内容已于 10-01 随本批删除，本批 dead-link 数应为 0。(2) 旧内容删除基线：确认 `docs/guide`、`docs/dev`、`docs/logger`、`docs/api`、`docs/index.md` 均不存在（首页 `docs/index.md` 本批**有意缺省**，不作为缺页问题）。(3) 静态核对 24 个文件：`docs/intermediate/` 下恰存在 D-20 的 24 个文件名（`data-vs-render`/`src-tour`/`code-basics`/`hooks`/`data-state-overview`/`hero-attribute`/`hero-items`/`hero-equipment`/`hero-location`/`map-structure`/`map-tiles`/`flags`/`combat-overview`/`enemy-specials`/`enemy-aura`/`enemy-query`/`enemy-final`/`enemy-calculator`/`enemy-map-damage`/`enemy-combat-script`/`enemy-status-hooks`/`events`/`replay-commands`/`data-plugins`，各加 `.md`）；每个文件 CRLF、单 H1。(4) 核对 `config.ts` 的 `'/intermediate/'` 键：去重后恰含 24 个 `/intermediate/<名>` 目标，且与 24 个文件名一一对应（导航入口 `中级教程` 复用其中一个目标，去重后仍为 24）。(5) 外链白名单：全 24 篇内出现的外链仅为 `https://h5mota.com/bbs/thread/?tid=1018&p=3#p41`（若文本中还出现其它 `http`，逐一报告供用户判断，不擅自删改）。发现任何缺页/错链只报告，不擅自补写。</action>
  <verify>
-    <automated>cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"; if (-not $?) { exit 1 }; $names=@('data-vs-render','src-tour','code-basics','hooks','data-state-overview','hero-attribute','hero-items','hero-equipment','hero-location','map-structure','map-tiles','flags','combat-overview','enemy-specials','enemy-aura','enemy-query','enemy-final','enemy-calculator','enemy-map-damage','enemy-combat-script','enemy-status-hooks','events','replay-commands','data-plugins'); $missing=@(); foreach($n in $names){ $p="docs/intermediate/$n.md"; if(-not(Test-Path $p)){ $missing+=$p; continue }; $raw=[IO.File]::ReadAllText((Resolve-Path $p)); if($raw -match "(?<!`r)`n"){ Write-Error "LF-ONLY $p" }; if(([regex]::Matches($raw,'(?m)^# ')).Count -ne 1){ Write-Error "H1-COUNT $p" } }; if($missing.Count -gt 0){ Write-Error ("MISSING: " + ($missing -join ',')) }; $cfg=[IO.File]::ReadAllText((Resolve-Path 'docs/.vitepress/config.ts')); $links=([regex]::Matches($cfg,"link:\s*'/intermediate/")).Count; if($links -ne 24){ Write-Error "SIDEBAR-COUNT $links" }; $ext=@(); foreach($n in $names){ $p="docs/intermediate/$n.md"; if(-not(Test-Path $p)){continue}; $m=[regex]::Matches([IO.File]::ReadAllText((Resolve-Path $p)),'https?://[^\s\)]+'); foreach($x in $m){ if($x.Value -notmatch '^https://h5mota\.com/bbs/thread/\?tid=1018'){ $ext+=$x.Value } } }; if($ext.Count -gt 0){ Write-Error ("EXT-LINK-NOT-APPROVED: " + (($ext | Select-Object -Unique) -join ',')) }; Write-Output 'ACCEPTANCE-OK'</automated>
-    <fails_when>non-zero exit, or output contains "dead link(s) found.", "Failed to resolve import", "MISSING:", "LF-ONLY", "H1-COUNT", "SIDEBAR-COUNT", or "EXT-LINK-NOT-APPROVED"; or output lacks "ACCEPTANCE-OK"</fails_when>
+    <automated>$ErrorActionPreference='Stop'; $names=@('data-vs-render','src-tour','code-basics','hooks','data-state-overview','hero-attribute','hero-items','hero-equipment','hero-location','map-structure','map-tiles','flags','combat-overview','enemy-specials','enemy-aura','enemy-query','enemy-final','enemy-calculator','enemy-map-damage','enemy-combat-script','enemy-status-hooks','events','replay-commands','data-plugins'); $missing=@(); foreach($n in $names){ $p="docs/intermediate/$n.md"; if(-not(Test-Path $p)){ $missing+=$p; continue }; $raw=[IO.File]::ReadAllText((Resolve-Path $p)); if($raw -match "(?<!`r)`n"){ Write-Error "LF-ONLY $p" }; if(([regex]::Matches($raw,'(?m)^# ')).Count -ne 1){ Write-Error "H1-COUNT $p" } }; if($missing.Count -gt 0){ Write-Error ("MISSING: " + ($missing -join ',')) }; foreach($o in @('docs/guide','docs/dev','docs/logger','docs/api','docs/index.md')){ if(Test-Path $o){ Write-Error "OLD-CONTENT-PRESENT $o" } }; $cfg=[IO.File]::ReadAllText((Resolve-Path 'docs/.vitepress/config.ts')); $targets=[regex]::Matches($cfg,"link:\s*'/intermediate/([a-z-]+)'") | ForEach-Object { $_.Groups[1].Value } | Sort-Object -Unique; $want=$names | Sort-Object -Unique; if(($targets -join ',') -ne ($want -join ',')){ Write-Error ("SIDEBAR-TARGETS " + ($targets -join ',')) }; $ext=@(); foreach($n in $names){ $p="docs/intermediate/$n.md"; if(-not(Test-Path $p)){continue}; $m=[regex]::Matches([IO.File]::ReadAllText((Resolve-Path $p)),'https?://[^\s\)]+'); foreach($x in $m){ if($x.Value -notmatch '^https://h5mota\.com/bbs/thread/\?tid=1018'){ $ext+=$x.Value } } }; if($ext.Count -gt 0){ Write-Error ("EXT-LINK-NOT-APPROVED: " + (($ext | Select-Object -Unique) -join ',')) }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; exit 1 }; $txt = $out -join "`n"; if($txt -notmatch 'build complete'){ Write-Error "NO-BUILD-COMPLETE" }; if($txt -match 'dead link'){ Write-Error "DEAD-LINK" }; if($txt -match 'Failed to resolve import'){ Write-Error "IMPORT-FAIL" }; Write-Output 'ACCEPTANCE-OK'</automated>
+    <fails_when>non-zero exit, or output contains "LF-ONLY", "H1-COUNT", "MISSING:", "OLD-CONTENT-PRESENT", "SIDEBAR-TARGETS", "EXT-LINK-NOT-APPROVED", "NO-BUILD-COMPLETE", "DEAD-LINK", or "IMPORT-FAIL"; or output lacks "ACCEPTANCE-OK"</fails_when>
  </verify>
-  <done>构建通过且产物生成；24 个文件齐全、CRLF、单 H1；sidebar 恰 24 条并与文件一一对应；无非白名单外链；输出 ACCEPTANCE-OK。</done>
+  <done>旧内容删除基线成立（guide/dev/logger/api 与首页均不存在）；构建通过且产物生成、dead-link 为 0；24 个文件齐全、CRLF、单 H1；sidebar 去重后恰 24 个目标并与文件一一对应；无非白名单外链；输出 ACCEPTANCE-OK。</done>
 </task>

 <task type="checkpoint:human-verify" gate="blocking-human">
  <name>Task 2: 交付构建产物供用户人工审阅（D-09）</name>
-  <action>向用户交付验收结果并请求 D-09 人工审阅。提供审阅方式：本地 `cmd /c "pnpm docs:preview"` 预览 `public/_docs`，或让用户自行浏览构建产物；并附上 Task 1 的核对结果摘要（文件数、sidebar 条目数、外链白名单命中、构建结论）。请用户核对三项：**内容正确且可读**、**侧边栏分组与顺序符合 4/8/9/3**、**无元叙述（D-16）**。等待用户确认通过；若用户指出缺页/错链/需修改项，记录并转交对应写作计划（10-02..10-05）修复，不在本计划内擅自补写。本任务与 `/gsd-verify-work 10` 的收尾互为补充，不替代阶段级验证。  </action>
+  <action>向用户交付验收结果并请求 D-09 人工审阅。提供审阅方式：本地 `cmd /c "pnpm docs:preview"` 预览 `public/_docs`，或让用户自行浏览构建产物；并附上 Task 1 的核对结果摘要（文件数、sidebar 目标数、外链白名单命中、删除基线、构建结论）。请用户核对三项：**内容正确且可读**、**侧边栏分组与顺序符合 4/8/9/3**、**无元叙述（D-16）**；并说明首页 `docs/index.md` 本批随旧内容一并删除、**有意缺省**（站点暂无 hero 首页），不作为问题。等待用户确认通过；若用户指出缺页/错链/需修改项，记录并转交对应写作计划（10-02..10-05）修复，不在本计划内擅自补写。本任务与 `/gsd-verify-work 10` 的收尾互为补充，不替代阶段级验证。  </action>
  <what-built>已构建的站点产物 `public/_docs`（含 24 篇中级教程与注册好的侧边栏/导航）与 Task 1 的验收结果摘要。</what-built>
  <how-to-verify>本地运行 `cmd /c "pnpm docs:preview"` 预览，或浏览构建产物；核对三项：内容正确且可读、侧边栏分组与顺序符合 4/8/9/3、无元叙述。如有缺页/错链/修改项请指出。</how-to-verify>
  <resume-signal>回复「通过」表示 D-09 人工审阅通过；如给出修改意见，请一并说明，待修正对应计划后再回复「通过」。其它回复视为未通过。</resume-signal>
@ -106,14 +110,16 @@ Output: 验收摘要 `10-06-SUMMARY.md`；站点构建产物 `public/_docs`（gi
 </threat_model>

 <verification>
- 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 通过。
- 完整性门禁：24 文件齐全 + sidebar 24 条 + 文件/条目一一对应。
+- 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 通过且 dead-link 数为 0。
+- 删除基线门禁：`docs/guide`、`docs/dev`、`docs/logger`、`docs/api`、`docs/index.md` 均不存在（首页有意缺省）。
+- 完整性门禁：24 文件齐全 + sidebar 去重后 24 个目标 + 文件/目标一一对应。
 - 外链门禁：全批唯一外链为 D-23 批准的链接。
 - 人工门禁：用户完成 D-09 审阅。
 </verification>

 <success_criteria>
 - D-09 三项（人工审阅 + 链接有效 + 构建通过）全部满足。
+- 旧内容删除基线成立（guide/dev/logger/api 与首页均已移除），本批 dead-link 为 0。
 - 24 篇中级教程全部落位、注册、可构建、可预览。
 - 无越界改动（仅 `docs/intermediate/*` 与 `docs/.vitepress/config.ts`）。
 </success_criteria>
--- a/.planning/phases/10-docs-restructure/10-CONTEXT.md
+++ b/.planning/phases/10-docs-restructure/10-CONTEXT.md
@ -1,7 +1,7 @@
 # Phase 10: 文档重构 - Context

 **Gathered:** 2026-10-14
-**Updated:** 2026-10-14（改为增量派发；补录中级教程第一批讨论结果）
+**Updated:** 2026-10-17（旧内容删除并入本批 Wave 0 / 10-01）
 **Status:** Incremental dispatch — 可先行部分先规划执行，其余待引擎完工

 <domain>
@ -22,6 +22,8 @@

 **第一批已派发内容 = 中级教程（`docs/intermediate`，24 篇）**，详见下方 `### 中级教程（第一批派发内容）`。

+**旧内容删除并入本批（Wave 0 / 10-01）：** 本批除注册 24 篇外，还执行 D-04 的旧内容清空——删除 `docs/guide`、`docs/dev`、`docs/logger`、`docs/api` 与首页 `docs/index.md`；同时清理 `docs/.vitepress/config.ts` 中指向这些内容的旧 `nav`/`sidebar` 键、保留 `docs/api/` 的生成机制（`api.ts`）并在目录缺失时安全跳过。删除后站点不再有既有 dead link，构建应转绿。
+
 </domain>

 <decisions>
@ -35,17 +37,17 @@
  - `docs/beginner`（初级文档）
  - `docs/intermediate`（中级教程）
  - `docs/advanced`（高级教程）
-  - `docs/api`（API 参考，已存在）
+  - `docs/api`（API 参考；旧内容已随本批删除，生成机制保留，正文待后续重建）
  - `docs/agent`（Agent 参考）
  - 按 `dev.md`，目录 / 文件名一律使用连字符英文命名。

 ### API 参考（第 5 部分）

- **D-03:** 继续按包生成 API 列表（保留 `docs/api/` 现有生成机制），但**正文讲解由人手写**，不是自动生成；对**重点接口额外详细讲解**。
+- **D-03:** 继续按包生成 API 列表（保留 `docs/api/` 现有生成机制），但**正文讲解由人手写**，不是自动生成；对**重点接口额外详细讲解**。（本批先删除 `docs/api/` 旧内容，生成机制 `docs/.vitepress/api.ts` 保留并向「目录缺失」场景加固，新的 API 正文待后续派发重建。）

 ### 旧内容处置

- **D-04:** 现有旧文档内容**全部删除、重写**，不保留——旧接口设计与当前实现差距较大。范围包括 `docs/guide/*`、`docs/dev/*`、`docs/logger/*` 等既有旧内容。
+- **D-04:** 现有旧文档内容**全部删除、重写**，不保留——旧接口设计与当前实现差距较大。**删除已并入本批执行（Wave 0 / 10-01）**，范围包括 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`、`docs/api/*` 及首页 `docs/index.md`；同时清理 `docs/.vitepress/config.ts` 中指向这些内容的旧 `nav`/`sidebar` 键，并让 `docs/api/` 侧边栏生成机制在目录缺失时安全跳过（保留 `docs/.vitepress/api.ts` 生成机制，供后续 API 参考重建）。

 ### 范围界定

@ -182,7 +184,7 @@
 - **总览**（第 1 部分）—— 待文档整体做完后最后写。
 - **Agent 参考**（第 6 部分）——「游戏数值设计、游戏地图设计」的具体内涵与内容来源。
 - 中级教程中标注「占位 / 待提供」的示例（`data-plugins` 的简单插件示例）。
- 旧内容删除的具体时机与清单核对。
+- **API 参考（第 5 部分）正文重建** —— `docs/api/` 旧内容已随本批（Wave 0 / 10-01）删除，生成机制 `docs/.vitepress/api.ts` 保留；新的按包 API 正文待后续派发重建。

 </deferred>

@ -190,4 +192,4 @@

 *Phase: 10-docs-restructure*
 *Context gathered: 2026-10-14*
-*Context updated: 2026-10-14（增量派发 + 中级教程第一批 24 篇讨论结果）*
+*Context updated: 2026-10-17（旧内容删除并入本批 Wave 0 / 10-01；中级教程第一批 24 篇讨论结果沿用）*