docs: 阶段十文档更新

.planning/ROADMAP.md

@@ -547,3 +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. 文档重构 | 0/0 | Not Planned | - |
+
+### Phase 10: 文档重构
+
+**Goal:** [To be planned]
+**Requirements**: TBD
+**Depends on:** Phase 9
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd-plan-phase 10 to break down)

.planning/STATE.md

@@ -265,6 +265,7 @@ Recent decisions affecting current work:
 - Phase 8 added (2026-10-04): 测试重构与接口对齐（测试文件迁入 `__test__` + 按数据端当前接口重对齐 + 细节修复）；承接已 SUPERSEDED 的 07-16；需求 TEST-02
 - 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
 
 ### Pending Todos
 

.planning/phases/10-docs-restructure/.gitkeep

@@ -0,0 +1 @@
+

.planning/phases/10-docs-restructure/10-CONTEXT.md

@@ -0,0 +1,119 @@
+# Phase 10: 文档重构 - Context
+
+**Gathered:** 2026-10-14
+**Status:** Discussion only — 待引擎整体完工后再规划/执行
+
+<domain>
+## Phase Boundary
+
+重构过老、结构不佳、新人理解难度过高的项目文档。面向多背景读者（完全新手 / 不懂代码的作者 / 有基础的作者 / AI Agent）提供分层指南，并专门为 AI Agent 编写参考文档。
+
+**执行时机（本阶段关键）：** 本阶段当前**只记录讨论共识，不规划、不执行**。引擎仍在收尾、部分内容（编辑器、部分重构）尚未完工，文档尚不具备编写条件；待引擎整体完工后再进入 Plan → Execute → Verify。
+
+文档分为六大部分：
+
+1. **总览**：如何正确地看文档、查文档；不同背景的作者应如何阅读；AI Agent 应如何阅读。
+2. **初级文档**：面向完全新手，**不含任何代码**，教学编辑器基本操作，并提供一些**仅使用编辑器的非代码编辑功能**即可实现的效果。因编辑器尚未实装，**待编辑器实装后再规划**。
+3. **中级教程**：面向读完初级文档的作者及有一定经验的作者，讲解**必须使用代码**才能完成的内容，简单讲解顶层接口的使用，**不深挖底层逻辑**。读完本部分，作者理应能完成绝大多数需求。
+4. **高级教程**：面向有高度定制需求、以及需要理解底层逻辑的作者，**系统讲解引擎的设计理念**。**待引擎整体完工后再规划**。
+5. **API 参考**：列出引擎的所有 API 接口并给出解释，**重点接口详细解释**。
+6. **Agent 参考**：面向 AI Agent，包含引擎快速总览、需求接口定位、游戏数值设计、游戏地图设计等参考文档。
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### 载体与整体形式
+
+- **D-01:** 文档载体沿用现有 **VitePress** 站点（`docs/.vitepress/`）；**不要求**脱离 VitePress 的纯 markdown 兼容，按 VitePress 语法书写即可（`:::info`、`mermaid` 等可用）。
+- **D-02:** 六大块各建**独立文件夹**，命名已获用户批准：
+  - `docs/overview`（总览）
+  - `docs/beginner`（初级文档）
+  - `docs/intermediate`（中级教程）
+  - `docs/advanced`（高级教程）
+  - `docs/api`（API 参考，已存在）
+  - `docs/agent`（Agent 参考）
+  - 按 `dev.md`，目录 / 文件名一律使用连字符英文命名。
+
+### API 参考（第 5 部分）
+
+- **D-03:** 继续按包生成 API 列表（保留 `docs/api/` 现有生成机制），但**正文讲解由人手写**，不是自动生成；对**重点接口额外详细讲解**。
+
+### 旧内容处置
+
+- **D-04:** 现有旧文档内容**全部删除、重写**，不保留——旧接口设计与当前实现差距较大。范围包括 `docs/guide/*`、`docs/dev/*`、`docs/logger/*` 等既有旧内容。
+
+### 范围界定
+
+- **D-05:** API 参考**不含 legacy 包**（`@motajs/legacy-*`、`@user/legacy-*`、`@user/data-fallback`）——这部分尚未重构完。
+- **D-06:** **初级文档**本期不规划，待**编辑器实装后**再规划；具体范围后续另行说明。
+- **D-07:** **高级教程**本期不规划，待**引擎整体完工后**再规划。
+- **D-08:** **Agent 参考**放 `docs/agent`，具体内容后续再讨论。
+
+### 验收与流程
+
+- **D-09:** 验收标准 = **用户人工审阅** + **链接全部有效** + **构建通过**。
+- **D-10:** 本阶段当前**仅讨论**；待引擎整体完工后再进入 GSD 的 Plan → Execute → Verify。
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- 用户原话（目标）：「现在的项目使用文档过老，而且文档编写的结构也不够好，对于新人来说理解难度过高……目标是能让新人、不怎么懂代码的作者、有一定基础的作者等各种背景的作者都能获取到合理的指南，并且专门为 AI Agent 编写文档，让 Agent 有文档参考。」
+- 用户原话（时机）：「目前来看，文档可能还无法开始编写，因此本阶段先进行大致的讨论，待引擎整体完工后再进行规划执行。」
+
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### 项目与阶段定义
+- `.planning/PROJECT.md` — 项目核心价值与项目级决策
+- `.planning/ROADMAP.md` — Phase 10 目标与依赖（Depends on: Phase 9）
+- `.planning/REQUIREMENTS.md` — 需求基线
+- `dev.md` — 项目开发规范（命名、流程、约束）
+- `AGENTS.md` — AI 行为约束（执行前须获批、命名须先反馈等）
+
+### 文档站点现状（重构对象）
+- `docs/index.md` — VitePress 首页（hero / features）
+- `docs/.vitepress/config.ts`、`docs/.vitepress/api.ts`、`docs/.vitepress/init.ts` — 站点配置与 API 构建
+- `docs/api/index.md` — 按包 API 列表（现含 legacy 包，本阶段将排除）
+- `docs/guide/*`、`docs/dev/*`、`docs/logger/*` — 待删除重写的旧内容
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### 文档站点结构（已核实）
+- VitePress 站点位于 `docs/`，配置在 `docs/.vitepress/`。
+- `docs/api/` 按包生成（`motajs-*` / `user-*` 各一目录 + `index.md` 列表）。
+- `docs/guide/` 为面向作者的使用指南（quick-start、coding、diff、audio、system、implements、ui）。
+- `docs/dev/` 为引擎接口设计文档（如 `template.md` 的「需求综述 → 需求理解 → 接口设计分析 → 实现思路」方法论）。
+- `docs/logger/` 为 logger 相关文档。
+
+### 相关约定
+- `dev.md`：Markdown 文档文件名使用连字符命名法。
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+- **初级文档**（第 2 部分）完整范围与内容 —— 待编辑器实装后再规划。
+- **高级教程**（第 4 部分）完整范围与内容 —— 待引擎整体完工后再规划。
+- **中级教程**（第 3 部分）范围细化与具体篇章。
+- **Agent 参考**（第 6 部分）——「游戏数值设计、游戏地图设计」的具体内涵与内容来源。
+- 各部分内部的具体文件命名与篇章划分。
+- 旧内容删除的具体时机与清单核对。
+
+</deferred>
+
+---
+
+*Phase: 10-docs-restructure*
+*Context gathered: 2026-10-14*

.planning/state.json

@@ -36,7 +36,7 @@
     {
       "number": "7",
       "name": "数据端缺陷修复",
-      "status": "pending"
+      "status": "complete"
     },
     {
       "number": "8",
@@ -46,7 +46,7 @@
     {
       "number": "9",
       "name": "最小浏览器可运行版本",
-      "status": "pending"
+      "status": "in_progress"
     }
   ],
   "next": {
@@ -54,5 +54,5 @@
     "label": "Advance to the next step",
     "reason": "Phase 9 of 9 · executing"
   },
-  "updated_at": "2026-10-09T06:58:38.764Z"
+  "updated_at": "2026-10-14T06:06:22.109Z"
 }

AGENTS.md

@@ -16,4 +16,4 @@
 - 任何公共、受保护、私有方法、字段等内容的命名必须先向我反馈，我同意后才可以使用，不得擅自使用我未同意的命名。
 - 在 GSD 流程的 Discuss 讨论阶段中，全部由我主导，而不是由你主导。进入讨论阶段的第一件事不是开子代理探索这一阶段的需求，也不是自己分析需求并提问问题，而是让我先说这一阶段的计划。
 - **GSD 流程最高优先级（豁免）**：GSD 标准流程自身要求的内容，以及其要求派发的子代理（如 `gsd-phase-researcher`、`gsd-pattern-mapper`、`gsd-planner`、`gsd-plan-checker`、`gsd-executor`、`gsd-verifier` 等），**一律按流程直接执行/派发，无需逐次征得我同意**。上文「任何操作都必须先经过我同意」与「不得派发任何（执行）子代理」两条，**仅约束你在 GSD 流程之外主动额外派发的子代理**。GSD 流程具有最高豁免权：除非我明确说明，否则不受本文件其它任何规则的约束。上述豁免的**唯一例外**是：任何计划的执行，其第一个 block 点仍须先向我汇报计划内容并等待我确认（见「任何计划的执行」条）。
-- **修改方式须预先声明**：每当需要进行文件修改时，无论采取哪种方式，都必须在动手前明确说明本次修改是「**内联执行**」还是「**派发子代理执行**」，并说明具体范围；声明后方可开始修改。
+- **修改方式须预先声明**：每当需要进行文件修改时，无论采取哪种方式，都必须在动手前明确说明本次修改是「**内联执行**」还是「**派发子代理执行**」，并说明具体范围；声明后方可开始修改。注意，内联执行仅允许修改 GSD 流程中允许内联执行的部分，绝对不允许修改诸如计划文件、代码、测试文件等内容。