From 1099583b0782a207d66a8145814b086c5a9ac309 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Sat, 17 Oct 2026 16:36:11 +0800 Subject: [PATCH] docs(10): rewrite 10-01 to clear legacy docs + register intermediate; refresh 10-06/10-CONTEXT/ROADMAP --- .planning/ROADMAP.md | 6 +- .../phases/10-docs-restructure/10-01-PLAN.md | 114 +++++++++++------- .../phases/10-docs-restructure/10-06-PLAN.md | 28 +++-- .../phases/10-docs-restructure/10-CONTEXT.md | 14 ++- 4 files changed, 100 insertions(+), 62 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 84a16c1..673ea90 100644 --- 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 "..."` 执行。 diff --git a/.planning/phases/10-docs-restructure/10-01-PLAN.md b/.planning/phases/10-docs-restructure/10-01-PLAN.md index c57d7de..c32eaa3 100644 --- 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 人工审阅不通过）" --- -在中级教程正文成批编写之前，先把 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/`。 @@ -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]`），故零页面时构建仍可成功。 - Task 0: 向用户汇报本计划并申请 D-13 命名批准 - 在写入任何文件之前，向用户汇报本计划内容并停下等待。汇报须包含：**要做什么**（在 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 的任何一步，也不得派发执行子代理。 - 本计划内容：在 VitePress 站点注册中级教程的顶栏入口与 `'/intermediate/'` 侧边栏分组（4 组 / 24 条），并生成本地构建前置文件 `apiSidebar.ts`；申请 D-13 命名的批准。 - 阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段；逐条审阅 nav 显示名 `中级教程`、四个分组标题、24 条显示名，确认或提出修改。 - 回复「可以执行」以继续；如对命名有修改，请一并给出，待修正后再回复「可以执行」。其它回复视为未批准，本计划停在此处。 + Task 0: 向用户汇报本计划（清空旧内容 + 站点注册）并等待「可以执行」 + 在删除或写入任何文件之前，向用户汇报本计划并停下等待。汇报须包含：**要做什么**（① 删除旧文档树 `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 的任何一步，也不得派发执行子代理。 + 本计划内容：清空旧文档内容（guide / dev / logger / api 与首页）、清理站点配置并保留 API 生成机制、注册 24 篇中级教程的 nav 入口与侧边栏分组。 + 阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认删除范围与站点注册做法无异议。 + 回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。 - 用户已回复「可以执行」，并对 nav 显示名、四个分组标题、24 条显示名给出确认或修改意见。 + 用户已回复「可以执行」。 - 用户回复「可以执行」且命名经批准（含修改）；未获批准前本计划不得继续。 + 用户回复「可以执行」。 - Task 1: 生成 apiSidebar.ts 并创建 docs/intermediate/ 目录 - docs/.vitepress/apiSidebar.ts, docs/intermediate/ - 先生成构建前置文件，再准备正文目录。执行 `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）。 + Task 1: 删除旧文档树与首页，清理 config.ts，并为 apiSidebar 生成加缺失目录守卫 + docs/index.md, docs/guide/, docs/dev/, docs/logger/, docs/api/, docs/.vitepress/config.ts, docs/.vitepress/api.ts + 工作树中的 `docs/.vitepress/config.ts` 处于 HEAD 基线，即不含被本计划取代的未提交 `'/intermediate/'` 编辑；若 `git status --porcelain docs/.vitepress/config.ts` 非空，先 `git restore docs/.vitepress/config.ts` 回到 HEAD 再开始。 + 分三步执行，且保持站点可构建。 + + (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 失败」。 - 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 } - non-zero exit, or output lacks "W0-PREP-OK", or docs/.vitepress/apiSidebar.ts / docs/intermediate/ 不存在 + $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' + 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" - `docs/.vitepress/apiSidebar.ts` 已生成且非空，`docs/intermediate/` 目录已存在；两文件之外的仓库内容零改动。 + 旧文档树与首页已删除；`config.ts` 不再含旧 nav/sidebar 键与 apiSidebar/api 导入；`api.ts` 含缺失目录守卫；`tsx docs/.vitepress/init.ts` 不抛错且 `docs:build` 打印 build complete、无 dead link / import 错误；输出 W0-CLEAR-OK。 Task 2: 在 config.ts 注册 nav 入口与 '/intermediate/' 侧边栏分组 - docs/.vitepress/config.ts - 用**就地编辑（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: '', link: '/intermediate/<文件名>' }`（绝对路径、不带 `.md`，写法和 `config.ts:64-124` 既有条目一致；分组嵌套写法参照 `config.ts:70-86`）。`'/guide/'`、`'/logger/'`、`'/api/'` 三个键与其中全部内容**逐字保留**。新增后运行构建命令确认站点可通过（命令本身先跑 init.ts，避免 `config.ts:3` 的 import 失败）。 + docs/.vitepress/config.ts, docs/intermediate/ + 用**就地编辑（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/` 缺失时安全跳过）。 - cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" - non-zero exit, or output contains "dead link(s) found.", or "Failed to resolve import", or the build does not print "build complete" + $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' + 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" - config.ts 仅新增 nav 一条与 `'/intermediate/'` sidebar 键（24 条 link、4 个分组，顺序 4/8/9/3）；既有 guide/logger/api 键与 nav 条目零 diff；`docs:build` 通过并打印 build complete。 + `config.ts` 新增 nav 一条与 `'/intermediate/'` sidebar 键（去重后恰 24 条 link、4 个分组，顺序 4/8/9/3）；`docs/intermediate/` 目录存在；`docs:build` 通过并打印 build complete；输出 W0-REGISTER-OK。 @@ -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/`