mirror of
https://github.com/motajs/template.git
synced 2026-10-20 05:40:18 +08:00
docs(10): add D-09 review revision plans (10-07..10-12)
This commit is contained in:
parent
36d38907ff
commit
49ecbfb89e
@ -547,14 +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/6 | Planned | - |
|
||||
| 10. 文档重构 | 0/12 | Planned | - |
|
||||
|
||||
### Phase 10: 文档重构
|
||||
|
||||
**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:** 12 plans（第一批：中级教程 24 篇 + 站点注册 + D-09 复审修订）
|
||||
|
||||
Plans:
|
||||
- [ ] 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）
|
||||
@ -563,5 +563,11 @@ Plans:
|
||||
- [ ] 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-07-PLAN.md — 目标性修正：D-09 复审 finding 1/3/4（讲清 `state` 获取、清除 legacy 泄漏 + 全批扫描、纠正修饰器定位；仅改 4 篇）
|
||||
- [ ] 10-08-PLAN.md — 战斗组引导式·入门友好重写 finding 2/5（`combat-overview` 讲清「计算后怪物 / 为什么要 buildup / 为什么分阶段」+ 7 篇子系统；8 篇）
|
||||
- [ ] 10-09-PLAN.md — 概念组 + 「其他」组引导式重写 finding 5（`src-tour`/`code-basics`/`hooks`/`events`/`replay-commands`/`data-plugins`；6 篇）
|
||||
- [ ] 10-10-PLAN.md — 基础接口组引导式重写 finding 5（`hero-items`/`hero-equipment`/`hero-location`/`map-structure`/`map-tiles`/`flags`；6 篇）
|
||||
- [ ] 10-11-PLAN.md — 读者视角审阅（persona 子代理）→ 问题清单 → 迭代修正（≤3 轮）→ 复审清零
|
||||
- [ ] 10-12-PLAN.md — 最终验收：修订后重跑全批验收 + D-09 复审（重跑 10-06 Task 2 门禁）
|
||||
|
||||
**说明：** 每篇中级教程遵循 `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 "..."` 执行。
|
||||
|
||||
152
.planning/phases/10-docs-restructure/10-07-PLAN.md
Normal file
152
.planning/phases/10-docs-restructure/10-07-PLAN.md
Normal file
@ -0,0 +1,152 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 07
|
||||
type: execute
|
||||
wave: 7
|
||||
depends_on: [10-06]
|
||||
gap_closure: true
|
||||
files_modified:
|
||||
- docs/intermediate/data-state-overview.md
|
||||
- docs/intermediate/data-vs-render.md
|
||||
- docs/intermediate/hero-attribute.md
|
||||
- docs/intermediate/enemy-map-damage.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 24000
|
||||
raw_tokens: 16000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "`data-state-overview` 用平实语言解释主对象 `state` 是什么，并列出获取 `state` 的常见方式：框架作为参数传入（道具效果 `useEffect(item, state)`、插件 `awake(state, ...)` / `initialize` / `afterLoad`、事件环境 `env.state`）、从处理对象上取（`handler.state`）、存到自身对象上（`this.state`）；不假定读者已懂「主对象」"
|
||||
- "`data-vs-render` 不再出现 legacy 全局包裹接口的名称与示例（那段 `:::info` 被移除，或改写为不含该 legacy 接口名的表述，指引改为指向 `state` 与数据端本身）"
|
||||
- "`enemy-map-damage` 不再出现旧主对象全局前缀的对象访问（第 52 行 `BetweenDamageView` 读取全局 flag `betweenAttackMax` 的表述改为不含旧全局前缀，仅保留 flag 名或改指 `state.flags`）"
|
||||
- "全 24 篇经 legacy 扫描：除已修正处外，无其它 legacy 全局包裹接口（`Mota`）或旧主对象全局前缀对象访问；`core.jsonc` 等文件名不计入"
|
||||
- "`hero-attribute` 的修饰器小节不再把修饰器框定为『临时』：标题与正文明确修饰器既可用于临时、也可用于永久加成；临时效果的做法是『不再需要时移除该修饰器』；保留原有正确的永久示例"
|
||||
- "4 个被改文件仍为 kebab-case、CRLF、单 H1；构建通过且 dead-link 为 0"
|
||||
artifacts:
|
||||
- "docs/intermediate/data-state-overview.md"
|
||||
- "docs/intermediate/data-vs-render.md"
|
||||
- "docs/intermediate/hero-attribute.md"
|
||||
- "docs/intermediate/enemy-map-damage.md"
|
||||
key_links:
|
||||
- "本计划是对 D-09 人工审阅 5 条 finding 中第 1、3、4 条的目标性修正（10-06 Task 2 未通过）"
|
||||
- "`state` 获取方式的统一表述是本计划新增的口径，后续 10-08/10-09/10-10 的引导式重写须沿用，不得与之冲突"
|
||||
- "保留 10-CONTEXT.md D-21（data-vs-render 不提反向推送）与 D-26（hero-attribute 的修饰器、save 语义）等已锁定内容"
|
||||
---
|
||||
|
||||
<objective>
|
||||
修正 D-09 人工审阅提出的第 1、3、4 条问题（`state` 获取方式未讲清、legacy 内容泄漏、修饰器被误框定为「临时」），并对这 4 个文件顺带做一次引导式表述调整，避免后续重写计划重复触碰。
|
||||
|
||||
Purpose: 让读者能真正看懂「`state` 从哪来」；清除 `docs/intermediate` 中的 legacy 痕迹；把修饰器的定位纠正为「临时与永久皆可」。这三条是**目标性**修正，不改变 D-21..D-44 锁定的内容范围。
|
||||
Output: 4 个修正后的 `docs/intermediate/*.md`；legacy 扫描结论。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/10-docs-restructure/10-CONTEXT.md
|
||||
@.planning/phases/10-docs-restructure/10-RESEARCH.md
|
||||
@.planning/phases/10-docs-restructure/10-PATTERNS.md
|
||||
|
||||
**修正来源（D-09 复审 5 条 finding，本计划负责第 1、3、4 条）：**
|
||||
- **finding 1（`state` 获取）**：`data-state-overview` 未说清「数据端主对象 `state` 如何获取」；不同地方获得 `state` 的方式不同（函数参数传入 / `this.state` / `handler.state`）。必须用平实语言讲清常见获取方式，且不假定读者理解「主对象」是什么。
|
||||
- **finding 3（legacy 泄漏）**：`data-vs-render` 第 46 行写了 legacy 的全局包裹接口示例；该接口属 legacy，**不得出现在教程中**。并须扫描其它页面，清除任何其它 legacy 全局包裹接口或旧主对象全局前缀的对象访问。
|
||||
- **finding 4（修饰器被误标「临时」）**：`hero-attribute` 的标题「修饰器：临时的加减与百分比」与「如果只想施加一段**临时**的加成，应使用修饰器」表述有误——修饰器**既可用于临时、也可用于永久**；想实现临时效果，应在不再需要时**移除**该修饰器。保留原有正确的永久示例。
|
||||
|
||||
**写作约定与前置：**
|
||||
- 骨架、kebab-case、CRLF、单 H1、无元叙述（D-16）、跳转链接 2–5 处/篇，沿用 10-PATTERNS 的约定。
|
||||
- 只改 `docs/intermediate/*.md`；**不**触碰 `docs/.vitepress/config.ts`（侧边栏已正确）与任何 `src/`、`packages/`、`packages-user/` 生产代码。
|
||||
- 本计划只处理这 4 个文件；其余文件由 10-08/10-09/10-10 处理，互不重叠。
|
||||
- 命令一律经 `cmd /c "..."` 执行（本机 PowerShell 禁止 `pnpm.ps1`）。
|
||||
- 越界项只记录、不实施（D-14）。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本修正计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（对 D-09 复审第 1、3、4 条做目标性修正：讲清 `state` 获取方式、清除 legacy 泄漏、纠正修饰器定位）、**为什么**（10-06 Task 2 的 D-09 审阅未通过，这三条是明确缺陷）、**大致怎么做**（在 `data-state-overview` 用平实语言补「state 从哪来」；在 `data-vs-render` 移除 legacy 全局包裹接口示例并全批扫描其它 legacy 痕迹；在 `hero-attribute` 改写修饰器小节标题与表述；`enemy-map-damage` 去除旧主对象全局前缀引用；四篇顺带做引导式表述调整）、**影响范围**（仅改这 4 个 `docs/intermediate/*.md`，不改站点配置与生产代码）。停下等待用户明确回复「可以执行」四个字；未收到前不得改任何文件。</action>
|
||||
<what-built>本计划内容：修正 D-09 复审第 1、3、4 条（state 获取 / legacy 泄漏 / 修饰器定位），仅改动 4 个 `docs/intermediate/*.md`。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认修正范围与做法无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 讲清 state 获取方式（data-state-overview）</name>
|
||||
<files>docs/intermediate/data-state-overview.md</files>
|
||||
<action>重写/扩写 `data-state-overview.md`，落实 finding 1。要点：(1) 用平实语言解释「主对象 `state`」是什么——不要假定读者懂「主对象」这个概念，先说明它就像游戏的一个总开关/总目录，勇士、地图、怪物、战斗、Flag 等都挂在它下面。(2) 明确列出「`state` 从哪来」的常见方式，至少覆盖三类：① **框架作为参数传入**——道具效果 `useEffect(item, state)`、数据插件 `awake(state, ...)` / `initialize(state, ...)` / `afterLoad(state, ...)`、事件的 `env.state`；② **从处理对象上取**——如 `handler.state`（怪物/战斗上下文里的 handler 带 `state`）；③ **存到自己的对象上**——自己写的类在构造函数里接收并保存 `state`，之后用 `this.state`。(3) 明确一句：教程后续代码示例里的 `state` 都假设它已在当前作用域中（由上述任一方式获得），因此示例不再重复来源。(4) 保留原有「常用对象与获取方式」表与 L0–L3 轻量分组标注（D-25）。顺带做引导式表述调整（finding 5 的手法：概念引导式书写，而非罗列）。遵守 kebab-case、CRLF、单 H1、无元叙述。Commit：`docs(10-07): 讲清 state 获取方式`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; $p='docs/intermediate/data-state-overview.md'; if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" }; foreach($k in @('handler\.state','this\.state','env\.state')){ if($raw -notmatch $k){ Write-Error "NO-STATE-ACQ $k" } }; if($raw -notmatch 'state'){ Write-Error "NO-STATE" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-STATE-ACQ", or "NO-STATE"</fails_when>
|
||||
</verify>
|
||||
<done>`data-state-overview` 用平实语言解释 `state` 并列出三条常见获取方式（参数传入 / `handler.state` / `this.state`，含 `env.state` 与插件参数）；保留对象表与 L0–L3 标注；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 清除 legacy 泄漏（data-vs-render、enemy-map-damage）+ 全批扫描</name>
|
||||
<files>docs/intermediate/data-vs-render.md, docs/intermediate/enemy-map-damage.md</files>
|
||||
<action>落实 finding 3。(1) `data-vs-render.md`：移除第 46 行附近那段 `:::info`（内容为「数据端需调用渲染端时要用某个 legacy 全局包裹接口包裹」的提示）。该 legacy 接口名**不得出现在正文任何位置**。改写方式：删掉该提示，或改为一句不含 legacy 接口名的平实说明（例如「数据端代码不应依赖渲染端内容；两端各自独立」），并保持 D-21（**不提**「渲染端不能反向推送」）。(2) `enemy-map-damage.md`：第 52 行 `BetweenDamageView` 读取全局 flag `betweenAttackMax` 的表述里带有旧主对象全局前缀（旧全局对象名以字母 `c` 开头）；改为不含该前缀的表述——仅以 flag 名 `betweenAttackMax` 描述该行为，或改述为「读取全局 flag `betweenAttackMax`」。全句语义与 D-39 一致，不臆造新行为。(3) **全批 legacy 扫描**：对 `docs/intermediate/` 全部 24 篇逐篇扫描，找出任何其它 legacy 全局包裹接口名（`M` 开头的旧全局）与旧主对象全局前缀对象访问；文件名性质的出现（如 `core.jsonc`、`ICoreState`）**不算** legacy。发现的其它命中**只记录、报告给用户**（D-14），不在本计划擅自改写。两篇顺带做引导式表述调整。遵守 kebab-case、CRLF、单 H1、无元叙述。Commit：`docs(10-07): 清除 legacy 泄漏`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/data-vs-render.md','docs/intermediate/enemy-map-damage.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $d=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/data-vs-render.md')); if($d -match 'Mota'){ Write-Error "LEGACY-MOTA data-vs-render" }; $m=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-map-damage.md')); if($m -match 'core\.flags'){ Write-Error "LEGACY-COREFLAGS enemy-map-damage" }; if($m -notmatch 'betweenAttackMax'){ Write-Error "LOST-FLAG enemy-map-damage" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "LEGACY-MOTA", "LEGACY-COREFLAGS", or "LOST-FLAG"</fails_when>
|
||||
</verify>
|
||||
<done>`data-vs-render` 无 legacy 全局包裹接口名；`enemy-map-damage` 无旧主对象全局前缀、保留 flag 名 `betweenAttackMax`；全 24 篇 legacy 扫描结论已记录；两篇 CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 纠正修饰器定位（hero-attribute）</name>
|
||||
<files>docs/intermediate/hero-attribute.md</files>
|
||||
<action>修正 `hero-attribute.md` 的 finding 4。(1) 标题 `## 修饰器：临时的加减与百分比` 改为不把修饰器等同于「临时」的表述（例如 `## 修饰器：属性加成` 或 `## 修饰器：数值与百分比加成`）。(2) 把「如果只想施加一段**临时**的加成，应使用**修饰器**」这句改写为正确表述：**修饰器既可用于永久加成、也可用于临时加成**（是否临时取决于你何时移除它）；直接改基础属性会永久改变数值，而修饰器把加成独立出来、便于随时挂上或移除。(3) 明确「想要临时效果」的做法：先 `addModifier(...)`，在不再需要时用 `deleteModifier(...)` 移除，效果即消失。(4) **保留**原有正确的**永久示例**（攻击永久 +5 的 `ValueModifier`）。(5) 保留 D-26 的既有内容：`ValueModifier` / `PercentageModifier`、`getModifiableAttribute()`、`addModifier` / `deleteModifier`、`save` 参数与读档一致性 `:::warning`、`getAttribute()` / `getIsolatedAttribute()`、回指 `./hooks.md`。示例区那句「防御 -20% 临时：挂一个百分比修饰器，战斗结束后再删除」可保留为**临时用法**的示例（它是移除式临时的正例），但需与新表述一致。顺带做引导式表述调整。遵守 kebab-case、CRLF、单 H1、无元叙述。Commit：`docs(10-07): 纠正修饰器定位`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; $p='docs/intermediate/hero-attribute.md'; if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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($raw -match '修饰器：临时的加减与百分比'){ Write-Error "BAD-MODIFIER-HEADING" }; if($raw -match '如果只想施加一段\*\*临时\*\*的加成'){ Write-Error "BAD-TEMP-FRAMING" }; foreach($k in @('ValueModifier','PercentageModifier','deleteModifier','addModifier')){ if($raw -notmatch $k){ Write-Error "NO-$k" } }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "BAD-MODIFIER-HEADING", "BAD-TEMP-FRAMING", or "NO-"</fails_when>
|
||||
</verify>
|
||||
<done>`hero-attribute` 不再把修饰器框定为「临时」；明确修饰器临时/永久皆可，临时效果靠移除修饰器实现；保留永久示例与 `save` 语义；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 构建期 markdown → 静态站点 | 正文由构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面（本篇不引入新外链） |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-19 | Tampering / XSS | 4 篇 markdown 正文 | low | mitigate | 只写文本、代码块、表格；不引入原始 `<script>`/内联 HTML |
|
||||
| T-10-20 | Spoofing | 外链 | low | mitigate | 本计划不引入任何新外链（唯一获批外链仍在 `code-basics`） |
|
||||
| T-10-21 | 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 错误）。
|
||||
- 结构门禁：4 个文件均 kebab-case、CRLF、单 H1。
|
||||
- 修正门禁：`data-state-overview` 含三种 state 获取方式；`data-vs-render` 无 legacy 全局包裹接口名；`enemy-map-damage` 无旧主对象全局前缀；`hero-attribute` 无「临时」误框定。
|
||||
- 越界门禁：`git status` 仅含这 4 个 `docs/intermediate/*.md` 的修改。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- finding 1、3、4 全部落实；D-21..D-44 锁定内容未被削减。
|
||||
- 构建通过；无越界改动（不改 `config.ts` 与任何生产代码）。
|
||||
- 4 篇保持 kebab-case、CRLF、单 H1；无元叙述。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-07-SUMMARY.md` when done
|
||||
</output>
|
||||
159
.planning/phases/10-docs-restructure/10-08-PLAN.md
Normal file
159
.planning/phases/10-docs-restructure/10-08-PLAN.md
Normal file
@ -0,0 +1,159 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 08
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: [10-07]
|
||||
gap_closure: true
|
||||
files_modified:
|
||||
- docs/intermediate/combat-overview.md
|
||||
- docs/intermediate/enemy-specials.md
|
||||
- docs/intermediate/enemy-aura.md
|
||||
- docs/intermediate/enemy-query.md
|
||||
- docs/intermediate/enemy-final.md
|
||||
- docs/intermediate/enemy-calculator.md
|
||||
- docs/intermediate/enemy-combat-script.md
|
||||
- docs/intermediate/enemy-status-hooks.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 48000
|
||||
raw_tokens: 32000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "`combat-overview` 用平实语言解释「计算后怪物」是什么：怪物在数据里只存基础属性与特殊属性，进入战斗前需要重建为一份属性已算准的怪物对象（计算后怪物），用于后续伤害计算"
|
||||
- "`combat-overview` 讲清「为什么要 buildup」——为得到准确的怪物属性（光环/查询/最终效果都要先把它们的作用算进属性里）；并讲清「为什么分阶段」——不同阶段各管一事：光环/查询/最终负责把属性算准，伤害计算负责把属性变成伤害与回合数，战前/战后脚本与状态钩子负责结算与持续状态"
|
||||
- "`combat-overview` 保留 D-33 的 mermaid 流程与「流程步骤 → 对应文档」对照表；临界值不在本篇提"
|
||||
- "战斗组 8 篇（含 `combat-overview`）整体改为引导式书写（先建立直觉、再引出概念与接口），而非概念罗列；保留 D-33..D-41 的全部锁定要点与示例"
|
||||
- "战斗组接口名/字段名与源码一致（RESEARCH Pitfall 5 / 10-04 已核对口径）；N-1/N-2/N-3/N-7 未内置/待补齐项继续留余地"
|
||||
- "战斗组 8 篇均 kebab-case、CRLF、单 H1、无元叙述（D-16）；构建通过且 dead-link 为 0"
|
||||
artifacts:
|
||||
- "docs/intermediate/combat-overview.md"
|
||||
- "docs/intermediate/enemy-specials.md"
|
||||
- "docs/intermediate/enemy-aura.md"
|
||||
- "docs/intermediate/enemy-query.md"
|
||||
- "docs/intermediate/enemy-final.md"
|
||||
- "docs/intermediate/enemy-calculator.md"
|
||||
- "docs/intermediate/enemy-combat-script.md"
|
||||
- "docs/intermediate/enemy-status-hooks.md"
|
||||
key_links:
|
||||
- "本计划负责 D-09 复审 finding 2（对新手过难，尤以 `combat-overview`）与 finding 5（引导式书写）在战斗组的落实"
|
||||
- "`enemy-map-damage` 已由 10-07 单独修正，不在本计划（战斗组因此为 8 篇）"
|
||||
- "沿用 10-07 建立的「state 从哪来」口径：战斗示例里出现的 `state` / `handler.state` / `env.state` 不得与之一致性冲突"
|
||||
---
|
||||
|
||||
<objective>
|
||||
按 D-09 复审 finding 2、5，对战斗组 8 篇做**引导式、入门友好**的重写：先让读者看懂「计算后怪物」「为什么要 buildup」「为什么分阶段」这些动机，再引出接口与示例；避免以术语罗列的方式开篇。
|
||||
|
||||
Purpose: 战斗是作者最常改的部分（10-CONTEXT 用户原话），但当前写法对新手过难。本计划不缩减 D-33..D-41 的内容范围，只改**讲法**——把动机讲清楚、把概念引导出来。
|
||||
Output: 8 个重写后的战斗组 markdown 文件。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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-04-PLAN.md
|
||||
|
||||
**修正来源（本计划负责 finding 2 与 finding 5 在战斗组的落实）：**
|
||||
- **finding 2**：整体对新手过难，尤以 `combat-overview`。ⓐ「计算后怪物」等术语未做新手能懂的说明；ⓑ「为什么要 buildup」未解释；ⓒ「为什么分阶段」未解释。必须用平实语言说明：buildup 是为了**获得准确的怪物属性**；分阶段是因为**不同阶段各管一事**（光环/查询/最终把手上的属性算准 → 伤害计算把属性变成伤害 → 战前/战后脚本与状态钩子负责结算与持续状态）。举证页：`combat-overview` 及其兄弟页。
|
||||
- **finding 5**：概念列举 → 引导式书写；可参考官方 Vue 文档的风格（先引导读者「遇到」概念，再展开）。中级教程不深挖设计原理，但仍可给浅白解释。
|
||||
|
||||
**写作约定与前置（沿用 10-04 的口径，内容范围不变）：**
|
||||
- 保留 D-33..D-41 的全部要点：`combat-overview` 的流程图与对照表；`enemy-specials` 的两类定义/属性实现位置表/编辑器识别约定；`enemy-aura` 先讲优先级、基础光环 + 特殊光环两例、`apply`/`applySpecial` 差别；`enemy-query` 标注「引擎未内置」+ 三示例（抱团/同化/号角）；`enemy-final` 三方对比 + 仿攻；`enemy-calculator` 讲 `f(enemy, hero)`、支援怪可跳过、临界不讲二分；`enemy-combat-script` 的「脚本 vs 钩子」选型表 + 两示例；`enemy-status-hooks` 强调一个状态可能用多个钩子并串起 `enemy-calculator`。
|
||||
- 接口名/字段名以 10-04 已核对源码的口径为准（RESEARCH Pitfall 5），**只改讲法、不改接口事实**。
|
||||
- N-1（查询未内置）/ N-2·N-3（地图伤害 code↔视图不一致，本页已在 10-07，不涉及）/ N-7（地图伤害结算待补齐）相关篇目继续留余地。
|
||||
- kebab-case、CRLF、单 H1、无元叙述（D-16）；跳转链接 2–5 处/篇。
|
||||
- 只改这 8 个 `docs/intermediate/*.md`；不触碰 `config.ts` 与生产代码。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本重写计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（按 finding 2/5 对战斗组 8 篇做引导式、入门友好重写，重点是让新手看懂「计算后怪物」「为什么要 buildup」「为什么分阶段」）、**为什么**（D-09 复审指出战斗组对新手过难、且整体写法偏概念罗列）、**大致怎么做**（逐篇先建立直觉与动机、再引出接口与示例；保留 D-33..D-41 全部要点与示例，只改讲法，不改接口事实；`combat-overview` 重点重写动机段落）、**影响范围**（仅改这 8 个 `docs/intermediate/*.md`；`enemy-map-damage` 已由 10-07 修正、不在本计划；不改站点配置与生产代码）。停下等待用户明确回复「可以执行」四个字；未收到前不得改任何文件。</action>
|
||||
<what-built>本计划内容：战斗组 8 篇的引导式、入门友好重写（不含已由 10-07 处理的 `enemy-map-damage`）。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认重写范围与做法无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 重写 combat-overview 与 enemy-specials</name>
|
||||
<files>docs/intermediate/combat-overview.md, docs/intermediate/enemy-specials.md</files>
|
||||
<action>按 finding 2/5 重写，保留 D-33/D-34 要点。(1) `combat-overview.md` 重点重写开篇与「计算后怪物」段落：先给新手一个直观场景——怪物在数据里只保存**基础属性**（血/攻/防）与**特殊属性**（先攻、连击、光环等），但光环、查询、最终效果都会改动这些属性；为了在开打前拿到一份「属性已经算准」的怪物，引擎会把每个怪物**重建**为一份计算后怪物（`enemyContext.buildup()`）。用平实语言补上：**为什么要重建**（为了得到准确的怪物属性，否则光环/查询/最终效果的作用不会体现到伤害里）与**为什么分四步**（不同步骤各管一事：①光环与特殊查询先决定「拥有哪些特殊属性」；②普通光环改基础属性；③常规查询读外部信息后改自身基础属性；④最终效果做收尾调整）。四步与优先级、与查询/光环共用优先级的说法保持 D-33 原样。保留伤害 `f(enemy, hero)` 的说明、mermaid 流程图、末尾「流程步骤 → 对应文档」对照表；**不提**临界值。(2) `enemy-specials.md` 保持 D-34 全部要点（两类定义、属性实现位置表、编辑器识别约定、多个示例、怪物比较简单说），把开篇与过渡改为引导式：先说「怪物的基础属性决定血与攻防，可它还会先攻、连击、光环——这些『还会做什么』就是特殊属性」，再引出 `code` + `value` 的结构，而非直接罗列接口。两篇遵守写作约定；示例接口名与 10-04 口径一致。Commit：`docs(10-08): 重写 combat-overview、enemy-specials（引导式）`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/combat-overview.md','docs/intermediate/enemy-specials.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $c=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/combat-overview.md')); if($c -notmatch 'mermaid'){ Write-Error "NO-MERMAID combat-overview" }; if($c -notmatch 'buildup'){ Write-Error "NO-BUILDUP combat-overview" }; if($c -notmatch '计算后怪物'){ Write-Error "NO-COMPUTED-ENEMY combat-overview" }; $s=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-specials.md')); if($s -notmatch 'defineCommonSerializableSpecial'){ Write-Error "NO-FACTORY enemy-specials" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-MERMAID", "NO-BUILDUP", "NO-COMPUTED-ENEMY", or "NO-FACTORY"</fails_when>
|
||||
</verify>
|
||||
<done>`combat-overview` 讲清「计算后怪物是什么、为什么要 buildup、为什么分四步」，保留 mermaid 与对照表；`enemy-specials` 引导式开篇且保留 D-34 要点；两篇 CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 重写 enemy-aura、enemy-query、enemy-final</name>
|
||||
<files>docs/intermediate/enemy-aura.md, docs/intermediate/enemy-query.md, docs/intermediate/enemy-final.md</files>
|
||||
<action>按 finding 5 做引导式重写，保留 D-35/D-36/D-37 要点。(1) `enemy-aura.md`：开篇先引导——「有些怪物不直接改自己，而是影响周围的怪物，这就是光环」，再引出优先级（高优先级可影响低优先级；与查询共用）；保留内置光环表、基础光环示例（减少周围怪物金币与经验）、特殊光环示例（给周围怪物上光环、优先级高于特殊光环）、`apply` 与 `applySpecial` 差别、四种范围只列名。(2) `enemy-query.md`：开篇引导——「有些特殊属性需要先看看周围有什么，再决定自己怎么变，这叫查询」；保留「引擎未内置」的 `:::warning`、常规查询与特殊查询的接口/注册、共用优先级、三示例（抱团/同化/号角）与「抱团用光环实现更麻烦」的对比。(3) `enemy-final.md`：开篇引导——「一切外部影响都算完后，还可能要对怪物自己再收个尾，这就是最终效果」；保留接口、内置坚固/模仿、光环/查询/最终三方对比表、仿攻示例、`priority` 一句带过、回指 `./combat-overview.md`。三篇示例接口名与 10-04 口径一致；`enemy-query` 继续标注未内置（N-1）。遵守写作约定。Commit：`docs(10-08): 引导式重写 enemy-aura/query/final`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/enemy-aura.md','docs/intermediate/enemy-query.md','docs/intermediate/enemy-final.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $a=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-aura.md')); if($a -notmatch 'applySpecial'){ Write-Error "NO-APPLYSPECIAL enemy-aura" }; $q=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-query.md')); if($q -notmatch 'registerCommonQueryEffect'){ Write-Error "NO-REGISTER enemy-query" }; $f=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-final.md')); if($f -notmatch 'registerFinalEffect'){ Write-Error "NO-REGISTER enemy-final" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-APPLYSPECIAL", "NO-REGISTER"</fails_when>
|
||||
</verify>
|
||||
<done>三篇引导式开篇并保留 D-35/D-36/D-37 要点与示例；`enemy-aura` 含 `applySpecial`；`enemy-query` 含注册接口且标注未内置；`enemy-final` 含注册接口与三方对比；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 重写 enemy-calculator、enemy-combat-script、enemy-status-hooks</name>
|
||||
<files>docs/intermediate/enemy-calculator.md, docs/intermediate/enemy-combat-script.md, docs/intermediate/enemy-status-hooks.md</files>
|
||||
<action>按 finding 5 做引导式重写，保留 D-38/D-39（本页不涉）/D-40/D-41 要点。(1) `enemy-calculator.md`：开篇引导——「属性算准之后，还要有人把它们换算成『扣多少血、打几回合』，这就是伤害计算器」；保留 `IDamageCalculator`（`calculate` → `{damage, turn}`、`getCriticalLimit`）、注册 `useCalculator`、内置公式逐段导读、支援怪「实在理解不了可暂时跳过」、等差数列示例、临界只讲定义与单调递减约定、不讲二分。(2) `enemy-combat-script.md`：开篇引导——「战斗前后常有一些规则要跑，比如『不许打』或『打完回血』，这些交给战斗脚本」；保留 `before` 返回 `bool` 拦截 / `after` 结算、内置 `MainCombatScript`、`addCombatScript`、「脚本 vs 钩子」选型表、两个示例、`priority` 一句。(3) `enemy-status-hooks.md`：开篇引导——「中毒、衰弱、重生这类状态不会一次算完，要在多个时机反复生效，所以要挂钩子」；保留「一个状态可能用多个钩子」、三类内置状态表、注册、时序、自定义示例（下次战斗伤害乘二，串起 `./enemy-calculator.md`）。三篇接口名与 10-04 口径一致；遵守写作约定。Commit：`docs(10-08): 引导式重写 calculator/script/status-hooks`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/enemy-calculator.md','docs/intermediate/enemy-combat-script.md','docs/intermediate/enemy-status-hooks.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $c=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-calculator.md')); if($c -notmatch 'getCriticalLimit'){ Write-Error "NO-CRITICAL enemy-calculator" }; $sc=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-combat-script.md')); if($sc -notmatch 'addCombatScript'){ Write-Error "NO-REGISTER enemy-combat-script" }; $h=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-status-hooks.md')); if($h -notmatch 'onAfterTeleportTo'){ Write-Error "NO-MULTIHOOK enemy-status-hooks" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-CRITICAL", "NO-REGISTER", or "NO-MULTIHOOK"</fails_when>
|
||||
</verify>
|
||||
<done>三篇引导式开篇并保留 D-38/D-40/D-41 要点；`enemy-calculator` 含 `getCriticalLimit` 与临界约定；`enemy-combat-script` 含选型表与 `addCombatScript`；`enemy-status-hooks` 强调多钩子协同并串起 `./enemy-calculator.md`；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 构建期 markdown → 静态站点 | 正文由构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面（本篇不引入外链） |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-22 | Tampering / XSS | 8 篇 markdown 正文 | low | mitigate | 只写文本、代码块、mermaid、表格；不引入原始 `<script>`/内联 HTML |
|
||||
| T-10-23 | Spoofing | 外链 | low | mitigate | 本组不引入任何外链 |
|
||||
| T-10-24 | 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 错误）。
|
||||
- 结构门禁：8 个文件均 kebab-case、CRLF、单 H1。
|
||||
- 内容门禁（人工，随 D-09 复审）：finding 2 的「为什么要 buildup / 为什么分阶段」已用平实语言解释；finding 5 的引导式书写已落实；D-33..D-41 要点齐全。
|
||||
- 越界门禁：`git status` 仅含这 8 个 `docs/intermediate/*.md` 的修改。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 战斗组 8 篇改为引导式、入门友好，`combat-overview` 讲清动机；D-33..D-41 内容范围未缩减。
|
||||
- 构建通过；无元叙述；无越界改动。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-08-SUMMARY.md` when done
|
||||
</output>
|
||||
153
.planning/phases/10-docs-restructure/10-09-PLAN.md
Normal file
153
.planning/phases/10-docs-restructure/10-09-PLAN.md
Normal file
@ -0,0 +1,153 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 09
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: [10-07]
|
||||
gap_closure: true
|
||||
files_modified:
|
||||
- docs/intermediate/src-tour.md
|
||||
- docs/intermediate/code-basics.md
|
||||
- docs/intermediate/hooks.md
|
||||
- docs/intermediate/events.md
|
||||
- docs/intermediate/replay-commands.md
|
||||
- docs/intermediate/data-plugins.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 36000
|
||||
raw_tokens: 24000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "概念组 3 篇（`src-tour` / `code-basics` / `hooks`）与「其他」组 3 篇（`events` / `replay-commands` / `data-plugins`）改为引导式书写：先建立直觉与使用场景，再引出接口与示例，而非概念罗列（finding 5）"
|
||||
- "各篇 D-22/D-23/D-24/D-42/D-43/D-44 的锁定要点与示例全部保留：`src-tour` 的「该不该改」表；`code-basics` 的三段式与 D-23 外链；`hooks` 的「需求→钩子」对照表；`events` 的自定义事件两示例；`replay-commands` 的核心原则与装饰器（不给示例）；`data-plugins` 的时机次序与占位示例（N-4）"
|
||||
- "`data-vs-render`、`data-state-overview`、`hero-attribute`、`enemy-map-damage` 不在本计划（分别由 10-07 处理），6 篇互不重叠"
|
||||
- "6 篇均 kebab-case、CRLF、单 H1、无元叙述（D-16）；唯一外链仍为 `code-basics` 的 D-23 链接；构建通过且 dead-link 为 0"
|
||||
artifacts:
|
||||
- "docs/intermediate/src-tour.md"
|
||||
- "docs/intermediate/code-basics.md"
|
||||
- "docs/intermediate/hooks.md"
|
||||
- "docs/intermediate/events.md"
|
||||
- "docs/intermediate/replay-commands.md"
|
||||
- "docs/intermediate/data-plugins.md"
|
||||
key_links:
|
||||
- "本计划负责 finding 5（引导式书写）在概念组与「其他」组的落实"
|
||||
- "`hooks` 是战斗/基础组引用最多的页（`addHook`/`removeHook`、需求→钩子对照表），其表述改动须保持被引用口径稳定"
|
||||
- "沿用 10-07 建立的「state 从哪来」口径：`events` 的 `env.state`、`data-plugins` 的 `awake(state, ...)` 表述须与之一致"
|
||||
---
|
||||
|
||||
<objective>
|
||||
按 D-09 复审 finding 5，对概念组 3 篇（`src-tour` / `code-basics` / `hooks`）与「其他」组 3 篇（`events` / `replay-commands` / `data-plugins`）做引导式重写；不缩减 D-22..D-24 / D-42..D-44 的内容范围，只改讲法。
|
||||
|
||||
Purpose: 当前多篇读起来像概念清单；改为「先让读者遇到概念、再展开」的引导式书写（参考官方 Vue 文档风格）。概念组是读者入口，钩子对照表又被后续页面反复引用，表述需稳。
|
||||
Output: 6 个重写后的 markdown 文件。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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-02-PLAN.md
|
||||
@.planning/phases/10-docs-restructure/10-05-PLAN.md
|
||||
|
||||
**修正来源（finding 5）：**
|
||||
- 概念列举 → 引导式书写。先用场景/直觉引导读者「遇到」概念，再展开接口、字段与示例；允许做浅白解释（中级不深挖设计原理）。
|
||||
|
||||
**写作约定与前置：**
|
||||
- 保留 D-22（`src-tour` 详讲 data/client/content/constant.ts，一句带过其余，不讲已弃用项，含「该不该改」表）、D-23（`code-basics` 三段式、泛型比作「类型的函数」、结尾 D-23 外链）、D-24（`hooks` 的常用钩子族一览 + 「需求→钩子」对照表 + `addHook`/`removeHook`）。
|
||||
- 保留 D-42（`events` 只讲如何自定义、两示例、编辑器识别留余地）、D-43（`replay-commands` 核心原则、主动/被动、`@shouldReplay`/`@ignoreReplay`、**不给示例**）、D-44（`data-plugins` 时机次序、注册、`addSaveableContent`、示例占位 N-4）。
|
||||
- 接口名/路径与 10-02 / 10-05 已核对源码的口径一致（RESEARCH Pitfall 5）。
|
||||
- kebab-case、CRLF、单 H1、无元叙述（D-16）；跳转链接 2–5 处/篇；`code-basics` 仍是全批唯一外链来源。
|
||||
- 只改这 6 个 `docs/intermediate/*.md`；不触碰 `config.ts` 与生产代码。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本重写计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（按 finding 5 对概念组 3 篇 + 「其他」组 3 篇做引导式重写）、**为什么**（D-09 复审指出整体写法偏概念罗列，需改为引导式）、**大致怎么做**（逐篇先建场景/直觉再引出接口；保留 D-22..D-24 / D-42..D-44 全部要点与示例，只改讲法）、**影响范围**（仅改这 6 个 `docs/intermediate/*.md`；不改站点配置与生产代码）。停下等待用户明确回复「可以执行」四个字；未收到前不得改任何文件。</action>
|
||||
<what-built>本计划内容：概念组 + 「其他」组共 6 篇的引导式重写。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认重写范围与做法无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 引导式重写 src-tour 与 code-basics</name>
|
||||
<files>docs/intermediate/src-tour.md, docs/intermediate/code-basics.md</files>
|
||||
<action>按 finding 5 重写，保留 D-22/D-23。(1) `src-tour.md`：开篇引导——「要动手改代码，先得知道东西放在哪」，再带读者认识 `src/data`（数据端、本教程重点）、`src/client`（渲染端）、`src/content`（内容层）、`src/constant.ts`（常量）；`src/bootstrap.ts`/`src/data.ts`/`src/package.json`/`src/styles.less` 各一句带过；不含 `src/main.ts`/`src/App.vue`/`src/types/`；保留「该不该改」表。(2) `code-basics.md`：保持三段式（简明语法 → 模块与引入 → 类型入门）与引导口吻（声明「只懂一点也能读懂」），泛型比作「类型的函数」，`interface`→`implements` 为建议但非强制；结尾保留 D-23 唯一外链 `https://h5mota.com/bbs/thread/?tid=1018&p=3#p41`。两篇遵守写作约定。Commit：`docs(10-09): 引导式重写 src-tour、code-basics`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/src-tour.md','docs/intermediate/code-basics.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $t=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/src-tour.md')); if($t -notmatch 'constant\.ts'){ Write-Error "NO-CONSTANT src-tour" }; if($t -match 'main\.ts'){ Write-Error "DEPRECATED-MAINTs src-tour" }; $b=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/code-basics.md')); if($b -notmatch 'https://h5mota\.com/bbs/thread/\?tid=1018'){ Write-Error "NO-APPROVED-LINK code-basics" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-CONSTANT", "DEPRECATED-MAINTs", or "NO-APPROVED-LINK"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`src-tour` 保留「该不该改」表且不含已弃用项；`code-basics` 保留三段式与 D-23 外链（且仅此一处外链）；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 引导式重写 hooks 与 events</name>
|
||||
<files>docs/intermediate/hooks.md, docs/intermediate/events.md</files>
|
||||
<action>按 finding 5 重写，保留 D-24/D-42。(1) `hooks.md`：开篇引导——「游戏里某个动作发生时，你想插一手，怎么办？这就是钩子」，再引出「钩子对象 = 一组按时机命名的方法」；保留常用钩子族一览、**「需求→钩子」对照表**（该表被战斗/基础组引用，方法名保持不变）、`addHook`/`removeHook`（含控制器 `unload`）、`hook/initialize.ts` 一笔带过、异步钩子标注、「钩子可能被非本对象触发」一段。(2) `events.md`：开篇引导——「地图事件里能调用一批内建动作；你也能照着加自己的动作」，保留 `BuiltInFunction`（`name` + `func(param, env)`）、事件环境 `env` 常用字段（`state` 等，与 10-07 的 state 口径一致）、参数接口在 `types.ts`、注册在 `createEventRegistrations()`、两个自定义示例（设置 flag / 勇士回血）、编辑器识别方式留余地（N-6）。两篇遵守写作约定。Commit：`docs(10-09): 引导式重写 hooks、events`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/hooks.md','docs/intermediate/events.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $h=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/hooks.md')); if($h -notmatch 'addHook'){ Write-Error "NO-ADDHOOK hooks" }; if($h -notmatch '需求'){ Write-Error "NO-NEED-TABLE hooks" }; $e=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/events.md')); if($e -notmatch 'createEventRegistrations'){ Write-Error "NO-REGISTRATION events" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-ADDHOOK", "NO-NEED-TABLE", or "NO-REGISTRATION"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`hooks` 保留需求→钩子对照表与 `addHook`；`events` 保留 `createEventRegistrations` 与两示例；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 引导式重写 replay-commands 与 data-plugins</name>
|
||||
<files>docs/intermediate/replay-commands.md, docs/intermediate/data-plugins.md</files>
|
||||
<action>按 finding 5 重写，保留 D-43/D-44。(1) `replay-commands.md`：开篇引导——「录像验证要能重放出同样的结果，前提是把该记的都记下来」，再引出核心原则「玩家直接产生、会影响最终成绩的行为必须计入录像」并解释两个条件；保留主动/被动录像（`ReplayCommandType.Active`/`Passive`）、新增自定义录像需改 `packages-user` 引擎内容的三步、`@shouldReplay`/`@ignoreReplay` 的 `begin`/`end` 区间检测与 `:::warning`；**不给示例**（后续其它教程链接过来）。(2) `data-plugins.md`：开篇引导——「一组相关功能想打包挂到数据端并按时初始化，就成了插件」，保留 `IDataPluginDefine`（`id`/`dependencies`/`awake`/`initialize`/`afterLoad`）、时机次序 `awake`→`initialize`→`afterLoad`、注册在 `src/data/plugin/list.ts`、`state.addSaveableContent`、示例**占位 / 待提供**（N-4）并写明「是否纳入本篇取决于示例难度」；`awake(state, ...)` 等参数名与 10-07 的 state 口径一致。两篇遵守写作约定。Commit：`docs(10-09): 引导式重写 replay-commands、data-plugins`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/replay-commands.md','docs/intermediate/data-plugins.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $r=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/replay-commands.md')); if($r -notmatch '@shouldReplay'){ Write-Error "NO-DECORATOR replay-commands" }; if($r -notmatch '核心原则|记录的|计入录像'){ Write-Error "NO-PRINCIPLE replay-commands" }; $p=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/data-plugins.md')); if($p -notmatch 'afterLoad'){ Write-Error "NO-LIFECYCLE data-plugins" }; if($p -notmatch '占位|待提供'){ Write-Error "NO-PLACEHOLDER data-plugins" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-DECORATOR", "NO-PRINCIPLE", "NO-LIFECYCLE", or "NO-PLACEHOLDER"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`replay-commands` 保留核心原则与装饰器且不给示例；`data-plugins` 保留 `afterLoad` 时机与占位示例；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 构建期 markdown → 静态站点 | 正文由构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面（仅 `code-basics` 的 D-23 链接） |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-25 | Tampering / XSS | 6 篇 markdown 正文 | low | mitigate | 只写文本、代码块、表格；不引入原始 `<script>`/内联 HTML |
|
||||
| T-10-26 | Spoofing | 外链 | low | mitigate | 全批唯一外链仍为 `code-basics` 的 D-23 链接 |
|
||||
| T-10-27 | 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 错误）。
|
||||
- 结构门禁：6 个文件均 kebab-case、CRLF、单 H1。
|
||||
- 内容门禁（人工，随 D-09 复审）：引导式书写已落实；D-22..D-24 / D-42..D-44 要点齐全。
|
||||
- 越界门禁：`git status` 仅含这 6 个 `docs/intermediate/*.md` 的修改。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 6 篇改为引导式书写，锁定要点与示例未缩减。
|
||||
- 构建通过；无元叙述；唯一外链不变；无越界改动。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-09-SUMMARY.md` when done
|
||||
</output>
|
||||
151
.planning/phases/10-docs-restructure/10-10-PLAN.md
Normal file
151
.planning/phases/10-docs-restructure/10-10-PLAN.md
Normal file
@ -0,0 +1,151 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 10
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: [10-07]
|
||||
gap_closure: true
|
||||
files_modified:
|
||||
- docs/intermediate/hero-items.md
|
||||
- docs/intermediate/hero-equipment.md
|
||||
- docs/intermediate/hero-location.md
|
||||
- docs/intermediate/map-structure.md
|
||||
- docs/intermediate/map-tiles.md
|
||||
- docs/intermediate/flags.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 36000
|
||||
raw_tokens: 24000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "基础接口组 6 篇（`hero-items` / `hero-equipment` / `hero-location` / `map-structure` / `map-tiles` / `flags`）改为引导式书写：先给读者一个使用场景，再引出接口清单与示例，而非直接罗列接口（finding 5）"
|
||||
- "各篇 D-27/D-28/D-29/D-30/D-31/D-32 的锁定要点与示例全部保留：`hero-items` 四类道具与常用接口；`hero-equipment` 装备槽 + 实例仓库 + `compareEquip`（不讲排序器）；`hero-location` 只讲获取位置与楼层；`map-structure` 楼层集合/楼层/图层（事件层归本篇）；`map-tiles` 六个常用接口（`getLocationData` 留高级）；`flags` 全部接口含 `occupied`"
|
||||
- "`data-state-overview`、`hero-attribute`、`enemy-map-damage` 不在本计划（由 10-07 处理），6 篇互不重叠"
|
||||
- "6 篇均 kebab-case、CRLF、单 H1、无元叙述（D-16）；接口名与 10-03 已核对源码口径一致；构建通过且 dead-link 为 0"
|
||||
artifacts:
|
||||
- "docs/intermediate/hero-items.md"
|
||||
- "docs/intermediate/hero-equipment.md"
|
||||
- "docs/intermediate/hero-location.md"
|
||||
- "docs/intermediate/map-structure.md"
|
||||
- "docs/intermediate/map-tiles.md"
|
||||
- "docs/intermediate/flags.md"
|
||||
key_links:
|
||||
- "本计划负责 finding 5（引导式书写）在基础接口组的落实"
|
||||
- "`hero-equipment` 回指 `./hero-attribute.md`（修饰器）；`map-tiles` 回指 `./map-structure.md`；这些链接目标已存在，构建可解析"
|
||||
- "沿用 10-07 建立的「state 从哪来」口径：本组示例里的 `state.hero...` / `state.maps...` 表述须与之配套（在 `data-state-overview` 已统一，本组不重复来源）"
|
||||
---
|
||||
|
||||
<objective>
|
||||
按 D-09 复审 finding 5，对基础接口组 6 篇做引导式重写；不缩减 D-27..D-32 的内容范围，只改讲法。`data-state-overview` 与 `hero-attribute` 已由 10-07 处理，本计划不含。
|
||||
|
||||
Purpose: 基础接口组是作者日常查表用的手册，当前写法偏接口罗列；改为「先给场景、再给接口」的引导式，降低新手上手难度。
|
||||
Output: 6 个重写后的基础接口组 markdown 文件。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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-03-PLAN.md
|
||||
|
||||
**修正来源（finding 5）：**
|
||||
- 概念列举 → 引导式书写。先给使用场景/直觉，再展开接口、字段与示例；允许浅白解释。
|
||||
|
||||
**写作约定与前置：**
|
||||
- 保留 D-27（`hero-items` 四类道具 + `addItem`/`getItemState`/`iterateItems`/`useItem`/`itemCount`，道具效果属内容层）、D-28（`hero-equipment` 装备槽/实例仓库/`IEquipmentState` 的 value/percentage，`compareEquip` 简单讲，**不讲排序器**）、D-29（`hero-location` 只讲获取，移动/切层留高级）、D-30（`map-structure` 三层结构，事件层归本篇）、D-31（`map-tiles` 六接口，`getLocationData` 留高级）、D-32（`flags` 全部接口含 `occupied`，建议不滥用）。
|
||||
- 接口名/字段名与 10-03 已核对源码的口径一致（RESEARCH Pitfall 5）。
|
||||
- kebab-case、CRLF、单 H1、无元叙述（D-16）；跳转链接 2–5 处/篇。
|
||||
- 只改这 6 个 `docs/intermediate/*.md`；不触碰 `config.ts` 与生产代码。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本重写计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（按 finding 5 对基础接口组 6 篇做引导式重写）、**为什么**（D-09 复审指出整体写法偏概念罗列，需改为引导式）、**大致怎么做**（逐篇先给场景/直觉再引出接口；保留 D-27..D-32 全部要点与示例，只改讲法）、**影响范围**（仅改这 6 个 `docs/intermediate/*.md`；`data-state-overview`、`hero-attribute` 已由 10-07 处理、不在本计划；不改站点配置与生产代码）。停下等待用户明确回复「可以执行」四个字；未收到前不得改任何文件。</action>
|
||||
<what-built>本计划内容：基础接口组 6 篇的引导式重写（不含已由 10-07 处理的 `data-state-overview`、`hero-attribute`）。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认重写范围与做法无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 引导式重写 hero-items 与 hero-equipment</name>
|
||||
<files>docs/intermediate/hero-items.md, docs/intermediate/hero-equipment.md</files>
|
||||
<action>按 finding 5 重写，保留 D-27/D-28。(1) `hero-items.md`：开篇引导——「勇士背包里能放哪些东西？它们被捡起或使用时会发生什么？」，再引出四类道具 `Constant`/`Consumable`/`Pick`/`Equipment` 的区分与常用接口；保留 `addItem`（可传负数、`Pick` 立刻生效）、`getItemState`、`iterateItems`、`useItem`（仅 Constant/Consumable）、`itemCount`、迭代背包示例、道具效果属内容层（`src/content/item.ts` + `IItemEffect`，可调用 `state`）的说明。(2) `hero-equipment.md`：开篇引导——「装备是特殊的道具：它要穿到某个槽位上，并给属性加成」，区分装备槽（`state.hero.equip`）与实例仓库（`state.hero.items.equipment`）；保留 `slots`/`canEquipTo`/`equip`（含 `autoUnload`）/`unequip`/`equipped`/`getEquipped`/`getEquips`、实例仓库 `add`/`delete`/`get`/`instancesOf`/`instances`/`count`、`IEquipmentState` 的 value/percentage（本质是修饰器，回指 `./hero-attribute.md`）、`compareEquip` 简单讲；**不讲排序器**。两篇遵守写作约定。Commit：`docs(10-10): 引导式重写 hero-items、hero-equipment`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/hero-items.md','docs/intermediate/hero-equipment.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $i=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/hero-items.md')); if($i -notmatch 'Consumable'){ Write-Error "NO-CATEGORY hero-items" }; $e=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/hero-equipment.md')); if($e -notmatch 'autoUnload'){ Write-Error "NO-AUTOUNLOAD hero-equipment" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-CATEGORY", or "NO-AUTOUNLOAD"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`hero-items` 保留四类区分与常用接口；`hero-equipment` 保留 `autoUnload` 且不讲排序器；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 引导式重写 hero-location 与 map-structure</name>
|
||||
<files>docs/intermediate/hero-location.md, docs/intermediate/map-structure.md</files>
|
||||
<action>按 finding 5 重写，保留 D-29/D-30。(1) `hero-location.md`：开篇引导——「很多逻辑要知道勇士此刻站在哪一层、哪一格、朝哪个方向」，再引出获取坐标/朝向/楼层；**只讲获取**（`hero.location` 的 `x`/`y`、`getCurrentFaceDirection()`、`hero.getLocation()`、`floorId`/`map`）；移动与切换楼层留高级、不展开。(2) `map-structure.md`：开篇引导——「地图不是一张大图，而是分层的」，引出三层：楼层集合（`state.maps`）→ 楼层（`IGameMap`）→ 图层（`IMapLayer`）；保留 `maps`/`getMap`/`getActiveMap`/`isMapActive`/`setMapActiveStatus`/`iterateAllMaps`、楼层激活（只有激活楼层进存档）、`IGameMap`（`layerList`/`eventLayer`/`tileStore`/宽高/`active`）、`IMapLayer`（`alias`/宽高）；强调**事件层本质就是个图层**。两篇遵守写作约定；回指 `./map-tiles.md` / `./data-state-overview.md` 链接目标已存在。Commit：`docs(10-10): 引导式重写 hero-location、map-structure`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/hero-location.md','docs/intermediate/map-structure.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $l=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/hero-location.md')); if($l -notmatch 'floorId'){ Write-Error "NO-FLOORID hero-location" }; $m=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/map-structure.md')); if($m -notmatch 'eventLayer'){ Write-Error "NO-EVENTLAYER map-structure" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-FLOORID", or "NO-EVENTLAYER"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`hero-location` 只讲获取且含 `floorId`；`map-structure` 含三层结构与事件层；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 引导式重写 map-tiles 与 flags</name>
|
||||
<files>docs/intermediate/map-tiles.md, docs/intermediate/flags.md</files>
|
||||
<action>按 finding 5 重写，保留 D-31/D-32。(1) `map-tiles.md`：开篇引导——「想在地图上摆一格、擦掉一格、或整片读写，该找谁？」，引出图块存在图层上；保留 `getBlock`/`setBlock`/`removeBlock`/`putMapData`/`getMapData`/`iterateBlocks` 六个常用接口与示例；`getLocationData` 仅一句说明属低级需求、留高级，不展开。(2) `flags.md`：开篇引导——「有些状态要跨事件、跨楼层保留，还要跟着存档走，放哪？」，引出全局可存档变量；保留字段概念、`IFlagSystem` 全部接口（含 `occupied`、`getOrInsertComputed`、`getFieldValueDefaults` 等）、会进存档的提醒与「不滥用、及时 `deleteField`」建议、记录开关与计数示例。两篇遵守写作约定。Commit：`docs(10-10): 引导式重写 map-tiles、flags`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in @('docs/intermediate/map-tiles.md','docs/intermediate/flags.md')){ if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $t=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/map-tiles.md')); if($t -notmatch 'iterateBlocks'){ Write-Error "NO-ITERATEBLOCKS map-tiles" }; $f=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/flags.md')); if($f -notmatch 'getOrInsertComputed'){ Write-Error "NO-GETORINSERTCOMPUTED flags" }; if($f -notmatch 'occupied'){ Write-Error "NO-OCCUPIED flags" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-ITERATEBLOCKS", "NO-GETORINSERTCOMPUTED", or "NO-OCCUPIED"</fails_when>
|
||||
</verify>
|
||||
<done>两篇引导式重写；`map-tiles` 保留六接口且不展开 `getLocationData`；`flags` 保留全部接口含 `occupied`、`getOrInsertComputed`；CRLF、单 H1。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 构建期 markdown → 静态站点 | 正文由构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面（本篇不引入外链） |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-28 | Tampering / XSS | 6 篇 markdown 正文 | low | mitigate | 只写文本、代码块、表格；不引入原始 `<script>`/内联 HTML |
|
||||
| T-10-29 | Spoofing | 外链 | low | mitigate | 本组不引入任何外链 |
|
||||
| T-10-30 | 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 错误）。
|
||||
- 结构门禁：6 个文件均 kebab-case、CRLF、单 H1。
|
||||
- 内容门禁（人工，随 D-09 复审）：引导式书写已落实；D-27..D-32 要点齐全；未越界讲排序器/移动切换楼层/`getLocationData`。
|
||||
- 越界门禁：`git status` 仅含这 6 个 `docs/intermediate/*.md` 的修改。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 6 篇改为引导式书写，锁定要点与示例未缩减。
|
||||
- 构建通过；无元叙述；无越界改动。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-10-SUMMARY.md` when done
|
||||
</output>
|
||||
170
.planning/phases/10-docs-restructure/10-11-PLAN.md
Normal file
170
.planning/phases/10-docs-restructure/10-11-PLAN.md
Normal file
@ -0,0 +1,170 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 11
|
||||
type: execute
|
||||
wave: 9
|
||||
depends_on: [10-08, 10-09, 10-10]
|
||||
gap_closure: true
|
||||
files_modified:
|
||||
- docs/intermediate/data-vs-render.md
|
||||
- docs/intermediate/src-tour.md
|
||||
- docs/intermediate/code-basics.md
|
||||
- docs/intermediate/hooks.md
|
||||
- docs/intermediate/data-state-overview.md
|
||||
- docs/intermediate/hero-attribute.md
|
||||
- docs/intermediate/hero-items.md
|
||||
- docs/intermediate/hero-equipment.md
|
||||
- docs/intermediate/hero-location.md
|
||||
- docs/intermediate/map-structure.md
|
||||
- docs/intermediate/map-tiles.md
|
||||
- docs/intermediate/flags.md
|
||||
- docs/intermediate/combat-overview.md
|
||||
- docs/intermediate/enemy-specials.md
|
||||
- docs/intermediate/enemy-aura.md
|
||||
- docs/intermediate/enemy-query.md
|
||||
- docs/intermediate/enemy-final.md
|
||||
- docs/intermediate/enemy-calculator.md
|
||||
- docs/intermediate/enemy-map-damage.md
|
||||
- docs/intermediate/enemy-combat-script.md
|
||||
- docs/intermediate/enemy-status-hooks.md
|
||||
- docs/intermediate/events.md
|
||||
- docs/intermediate/replay-commands.md
|
||||
- docs/intermediate/data-plugins.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 42000
|
||||
raw_tokens: 28000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "以「不懂代码的游戏作者」人格的独立子代理（persona）通读 24 篇，产出一份**理解性问题清单**（读者读完后会有的问题 / 看不懂的点），落在 `.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md`"
|
||||
- "问题清单区分**阻断性理解问题**（读者按文档无法完成操作或误解概念）与**非阻断问题**；只有阻断性问题必须在迭代中消除，非阻断问题记录供用户判断"
|
||||
- "针对阻断性问题的修正被实施（迭代上限 3 轮；达到上限仍余阻断问题时，停下向用户汇报，不无限循环）"
|
||||
- "每轮修正后仍有 `cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\"` 通过（green / dead-link = 0）"
|
||||
- "迭代结束时，阻断性理解问题为 0（或已把余项交给用户），且 `10-11-READER-REVIEW.md` 记录了每轮问题与处置"
|
||||
- "只改 `docs/intermediate/*.md`；不改 `config.ts` 与生产代码；被改文件保持 kebab-case、CRLF、单 H1"
|
||||
artifacts:
|
||||
- ".planning/phases/10-docs-restructure/10-11-READER-REVIEW.md"
|
||||
- "docs/intermediate/*.md（仅存在阻断性问题的篇目）"
|
||||
key_links:
|
||||
- "本计划把用户要求的「读者视角审阅」机制固化为显式步骤：独立子代理 + 人格化阅读 + 问题清单 + 迭代（同 plan-checker 的复审循环思路）"
|
||||
- "问题清单是后续迭代与最终 D-09 验收的输入；persona 提示词必须逐字包含用户给定的设定（见 Task 1）"
|
||||
- "本计划在 10-08/10-09/10-10 的三组重写之后执行，审阅对象是重写后的 24 篇"
|
||||
---
|
||||
|
||||
<objective>
|
||||
按用户明确要求，把「读者视角审阅」建成本计划的显式步骤：派发一个**独立子代理**，以「不懂代码的游戏作者」人格通读全部 24 篇中级教程，产出理解性问题清单；再据此迭代修正，直到无阻断性理解问题（或达到上限 3 轮），最后复跑审阅确认。
|
||||
|
||||
Purpose: finding 2/5 的实质是「新手读不懂」。仅靠作者视角无法自知；需要一个假想读者的反向审阅来暴露「读者实际会卡在哪」。这与 plan-checker 的复审循环同构。
|
||||
Output: `10-11-READER-REVIEW.md`（人格审查结论 + 迭代记录）与针对阻断问题的文档修正。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/10-docs-restructure/10-CONTEXT.md
|
||||
@.planning/phases/10-docs-restructure/10-RESEARCH.md
|
||||
@.planning/phases/10-docs-restructure/10-PATTERNS.md
|
||||
|
||||
**机制来源（用户明确要求）：**
|
||||
> 文档写完后，派发一个**独立子代理**，模拟一个不懂代码的游戏作者来阅读文档，问它「读完后有哪些问题」，再用这些问题迭代文档。人格设定逐字为：**「假设你是一个不懂代码的游戏作者，你正在阅读这个样板的使用文档，现在看到了中级教程，你了解魔塔游戏的基本概念」**。
|
||||
|
||||
**写作与流程约定：**
|
||||
- 迭代上限 **3 轮**；每轮后跑构建门禁；达到上限仍有阻断问题时，停下向用户汇报（不得无限循环）。
|
||||
- 只改 `docs/intermediate/*.md`；不触碰 `config.ts` 与任何生产代码。
|
||||
- 被改文件保持 kebab-case、CRLF、单 H1、无元叙述（D-16）。
|
||||
- 命令一律经 `cmd /c "..."` 执行（本机 PowerShell 禁止 `pnpm.ps1`）。
|
||||
- 修正须守住 10-CONTEXT.md D-21..D-44 的锁定内容范围与接口准确性（RESEARCH Pitfall 5）。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本审阅计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（派发一个独立子代理，以「不懂代码的游戏作者」人格通读 24 篇，产出理解性问题清单，据此迭代修正文档）、**为什么**（finding 2/5 的实质是新手读不懂；需读者视角反向审阅）、**大致怎么做**（Task 1 派发 persona 子代理并落清单文件；Task 2 按清单修阻断问题，最多 3 轮、每轮跑构建；Task 3 复跑 persona 审阅确认阻断问题清零）、**影响范围**（可能修改 `docs/intermediate/*.md` 中确有阻断问题的篇目 + 新增一个 `.planning` 下的审查记录文件；不改站点配置与生产代码）。停下等待用户明确回复「可以执行」四个字；未收到前不得派发子代理或改任何文件。</action>
|
||||
<what-built>本计划内容：读者视角审阅（persona 子代理）→ 问题清单 → 迭代修正 → 复审确认。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认机制与迭代上限（3 轮）无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 派发 persona 子代理并产出理解性问题清单</name>
|
||||
<files>.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md</files>
|
||||
<action>派发一个**独立子代理**（不与执行者共享上下文），其人格与任务设定逐字为：**「假设你是一个不懂代码的游戏作者，你正在阅读这个样板的使用文档，现在看到了中级教程，你了解魔塔游戏的基本概念」**。让子代理按 `docs/intermediate/` 的阅读顺序（4/8/9/3）通读全部 24 篇，然后回答：「读完后你有哪些问题？哪里看不懂？哪一步你照做会卡住或会做错？」子代理**只以读者身份提问**、不修改文件、不代入实现者视角。把子代理的原始提问与执行者的归类（**阻断性理解问题** / 非阻断问题）写进 `.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md`，每条附上对应文件名与定位（章节/行）。阻断性判定口径：读者据此无法完成操作、或会对概念产生实质误解。**本轮不改文档**。Commit：`docs(10-11): 记录读者视角问题清单`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md'; if(-not(Test-Path $f)){ Write-Error "MISSING $f" }; $raw=[IO.File]::ReadAllText((Resolve-Path $f)); if($raw -notmatch '阻断'){ Write-Error "NO-CLASSIFICATION" }; if($raw -notmatch '问题|看不懂|卡'){ Write-Error "NO-QUESTIONS" }; Write-Output 'STATIC-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "NO-CLASSIFICATION", or "NO-QUESTIONS"</fails_when>
|
||||
</verify>
|
||||
<done>`10-11-READER-REVIEW.md` 存在，含 persona 子代理的问题清单，且每条已按阻断/非阻断归类并定位到文件。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: 按问题清单迭代修正（上限 3 轮）</name>
|
||||
<files>docs/intermediate/*.md（仅存在阻断性问题的篇目）</files>
|
||||
<action>逐个消除 `10-11-READER-REVIEW.md` 中的**阻断性理解问题**：对每个阻断问题，修改对应 `docs/intermediate/*.md` 的相应段落，使一个不了解代码的游戏作者也能读懂（补前提、补“为什么”、把术语讲清、必要时重排顺序）。只改确有阻断问题的篇目。每轮修正后：(a) 跑构建门禁 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，须 green、dead-link = 0；(b) 在 `10-11-READER-REVIEW.md` 追加该轮记录（本轮修了哪些问题、依据、构建结论）。迭代**最多 3 轮**：3 轮后仍有阻断问题时，停下把这些余项列给用户，不继续循环。非阻断问题**不修**、仅在清单中记录供用户判断（D-14）。不改 `config.ts` 与生产代码；守住 D-21..D-44 内容范围与接口准确性。每轮 Commit：`docs(10-11): 迭代修正读者阻断问题（第N轮）`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; foreach($p in (Get-ChildItem -LiteralPath 'docs/intermediate' -Filter *.md)){ $raw=[IO.File]::ReadAllText($p.FullName); if($raw -match "(?<!`r)`n"){ Write-Error ("LF-ONLY " + $p.Name) }; if(([regex]::Matches($raw,'(?m)^# ')).Count -ne 1){ Write-Error ("H1-COUNT " + $p.Name) } }; $f='.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md'; if(([IO.File]::ReadAllText((Resolve-Path $f))) -notmatch '轮|round|迭代'){ Write-Error "NO-ROUND-LOG" }; $ErrorActionPreference='Continue'; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; $ec=$LASTEXITCODE; $ErrorActionPreference='Stop'; if($ec -ne 0){ $out | Write-Output; exit 1 }; $txt = ($out | ForEach-Object { $_.ToString() }) -join "`n"; if($txt -notmatch 'build complete'){ Write-Error "NO-BUILD-COMPLETE" }; if($txt -match 'dead link'){ Write-Error "DEAD-LINK" }; Write-Output 'ITERATE-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "LF-ONLY", "H1-COUNT", "NO-ROUND-LOG", "NO-BUILD-COMPLETE", "DEAD-LINK", or output lacks "ITERATE-OK"</fails_when>
|
||||
</verify>
|
||||
<done>阻断性问题按最多 3 轮迭代修正完毕（余项已交用户）；每轮记录进 `10-11-READER-REVIEW.md`；构建 green、dead-link = 0。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 复跑 persona 审阅确认阻断问题清零</name>
|
||||
<files>.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md</files>
|
||||
<action>再次派发一个**独立子代理**（同一人格设定，逐字同 Task 1：「假设你是一个不懂代码的游戏作者，你正在阅读这个样板的使用文档，现在看到了中级教程，你了解魔塔游戏的基本概念」），让它重新通读全部 24 篇并回答「现在还有哪些看不懂的地方？」。把复审结果追加进 `10-11-READER-REVIEW.md`：对照首轮清单，逐条标注「已消除」或「仍存在」；若仍有**阻断性**问题，即回到 Task 2 再修（受 3 轮上限约束），否则记「阻断问题 = 0，审阅通过」。最后跑一次构建门禁确认 green。本任务**不引入新功能**，仅收敛理解性问题。Commit：`docs(10-11): 复审读者视角（阻断问题清零）`。</action>
|
||||
<verify>
|
||||
<automated>$ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md'; $raw=[IO.File]::ReadAllText((Resolve-Path $f)); if($raw -notmatch '已消除|仍存在'){ Write-Error "NO-RECHECK" }; $ErrorActionPreference='Continue'; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; $ec=$LASTEXITCODE; $ErrorActionPreference='Stop'; if($ec -ne 0){ $out | Write-Output; exit 1 }; $txt = ($out | ForEach-Object { $_.ToString() }) -join "`n"; if($txt -notmatch 'build complete'){ Write-Error "NO-BUILD-COMPLETE" }; if($txt -match 'dead link'){ Write-Error "DEAD-LINK" }; Write-Output 'RECHECK-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "NO-RECHECK", "NO-BUILD-COMPLETE", "DEAD-LINK", or output lacks "RECHECK-OK"</fails_when>
|
||||
</verify>
|
||||
<done>复审结果记录进 `10-11-READER-REVIEW.md`（逐条已消除/仍存在）；阻断性理解问题为 0（或余项已交用户）；构建 green、dead-link = 0。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 执行者 → 子代理 | persona 子代理以独立上下文阅读文档并提问，不修改文件 |
|
||||
| 构建期 markdown → 静态站点 | 正文由构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面 |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-31 | Tampering / XSS | 被改 markdown 正文 | low | mitigate | 只写文本、代码块、表格；不引入原始 `<script>`/内联 HTML |
|
||||
| T-10-32 | Spoofing | 外链 | low | mitigate | 不引入新外链；唯一获批外链仍在 `code-basics` |
|
||||
| T-10-33 | Information Disclosure | 审阅记录/正文 | low | mitigate | 只引用仓库已公开的路径与接口名；不写密钥、账号 |
|
||||
| T-10-SC | Tampering | npm/pip/cargo installs | low | accept | 本阶段不安装任何包，无供应链安装面 |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- 机制门禁：存在 `10-11-READER-REVIEW.md`，含 persona 提示词、首轮问题清单（按阻断/非阻断归类）、每轮迭代记录、复审对照结果。
|
||||
- 迭代门禁：上限 3 轮；结束状态为阻断性理解问题 = 0（或余项已交用户）。
|
||||
- 构建门禁：每轮及收尾均 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 通过（green / dead-link = 0）。
|
||||
- 结构门禁：24 篇仍 kebab-case、CRLF、单 H1。
|
||||
- 越界门禁：`git status` 仅含 `docs/intermediate/*.md` 的修改与新增的 `.planning` 审查记录。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 读者视角审阅机制按用户要求落地：独立 persona 子代理 + 问题清单 + 迭代 + 复审。
|
||||
- 阻断性理解问题清零（或余项已明确交用户）；构建通过。
|
||||
- 无越界改动（不改 `config.ts` 与生产代码）。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-11-SUMMARY.md` when done
|
||||
</output>
|
||||
129
.planning/phases/10-docs-restructure/10-12-PLAN.md
Normal file
129
.planning/phases/10-docs-restructure/10-12-PLAN.md
Normal file
@ -0,0 +1,129 @@
|
||||
---
|
||||
phase: 10-docs-restructure
|
||||
plan: 12
|
||||
type: execute
|
||||
wave: 10
|
||||
depends_on: [10-11]
|
||||
gap_closure: true
|
||||
files_modified: []
|
||||
autonomous: false
|
||||
requirements: []
|
||||
user_setup: []
|
||||
estimate:
|
||||
tokens: 18000
|
||||
raw_tokens: 12000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "修订后重跑全量构建：`cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\"` 打印 build complete、dead-link = 0、无 import 失败，且产物 `public/_docs` 生成"
|
||||
- "24 篇文件齐全、CRLF、单 H1；sidebar 的 24 条 link 仍与 24 个文件名一一对应（本批未改 `config.ts`，侧边栏应保持正确）"
|
||||
- "复查 D-09 复审 5 条 finding 均已处置：① state 获取讲清；② 战斗组对新手友好；③ legacy 无泄漏；④ 修饰器定位更正；⑤ 引导式书写"
|
||||
- "交付构建产物供用户做 D-09 复审；本次复审是 10-06 Task 2 那条未通过的 D-09 门禁的重跑"
|
||||
- "全批唯一外链仍为 D-23 的 `h5mota.com` 链接；无元叙述（D-16）"
|
||||
artifacts:
|
||||
- ".planning/phases/10-docs-restructure/10-12-SUMMARY.md"
|
||||
key_links:
|
||||
- "本计划重跑 10-06 Task 2 的 D-09 人工审阅门禁（该门禁在首轮返回了 5 条 finding，由 10-07..10-11 修正）"
|
||||
- "验收基线 = 修订后的 24 篇 + 未变的站点配置；10-06 Task 1 的构建 / 完整性 / 外链门禁在此重跑"
|
||||
- "本计划只做验收，不新增/修改任何文档或配置；发现遗漏只报告并回到对应计划修复"
|
||||
---
|
||||
|
||||
<objective>
|
||||
修订完成后重跑全批验收与 D-09 人工审阅：确认 5 条 finding 已处置、24 篇落位、注册完整、构建通过、链接有效，并交付用户做复审。
|
||||
|
||||
Purpose: 首轮 D-09 审阅（10-06 Task 2）未通过；本计划在 10-07..10-11 修订后重跑该门禁，闭合本轮修订循环。
|
||||
Output: 验收摘要 `10-12-SUMMARY.md`；站点构建产物 `public/_docs`（gitignored）。
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/10-docs-restructure/10-CONTEXT.md
|
||||
@.planning/phases/10-docs-restructure/10-RESEARCH.md
|
||||
@.planning/phases/10-docs-restructure/10-VALIDATION.md
|
||||
@.planning/phases/10-docs-restructure/10-06-PLAN.md
|
||||
@docs/.vitepress/config.ts
|
||||
|
||||
**约定：** 本计划只做验收，不新增/修改任何文档或配置；如发现缺页或链接错误，只报告并回到对应计划修复（D-14）。
|
||||
|
||||
**复审判据（D-09 复审 5 条 finding）：** ① `state` 获取方式已讲清（10-07）；② 战斗组对新手友好、buildup/分阶段有解释（10-08）；③ legacy（`Mota` 全局 / 旧主对象前缀）无泄漏（10-07）；④ 修饰器定位更正为临时/永久皆可（10-07）；⑤ 引导式书写（10-08/10-09/10-10）。另：读者视角审阅阻断问题清零（10-11）。
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 向用户汇报本验收计划并等待「可以执行」</name>
|
||||
<action>向用户汇报：**要做什么**（对修订后的 24 篇做全批重验收：文件齐全、注册完整、构建通过、链接有效，并交付人工复审）、**为什么**（首轮 D-09 审阅未通过，需在修订后重跑该门禁）、**大致怎么做**（跑全量构建 + 静态核对 24 文件与 24 条 sidebar、复查 5 条 finding、单 H1/CRLF、外链白名单，然后请用户复审构建产物）、**影响范围**（不改任何文件，仅生成 SUMMARY 与 gitignored 构建产物）。停下等待用户明确回复「可以执行」四个字；未收到前不得执行任何检查。</action>
|
||||
<what-built>本计划内容：修订后的全批重验收 + D-09 复审。</what-built>
|
||||
<how-to-verify>阅读上面的「要做什么 / 为什么 / 大致怎么做 / 影响范围」四段，确认验收范围与做法无异议。</how-to-verify>
|
||||
<resume-signal>回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已回复「可以执行」。</human-check>
|
||||
</verify>
|
||||
<done>用户回复「可以执行」。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 全量构建 + 静态重验收，并复查 5 条 finding</name>
|
||||
<files>docs/.vitepress/config.ts（只读核对；本计划不改动仓库文件，产物仅 SUMMARY）</files>
|
||||
<action>(1) 构建：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，确认打印 build complete、无 dead link、无 `Failed to resolve import`，产物 `public/_docs` 生成。(2) 静态核对 24 文件：`docs/intermediate/` 下恰存在 D-20 的 24 个文件名，各 CRLF、单 H1。(3) 核对 `config.ts` 的 `'/intermediate/'` 键去重后恰含 24 个目标且与文件名一一对应。(4) 外链白名单：全 24 篇内出现的外链仅为 `https://h5mota.com/bbs/thread/?tid=1018&p=3#p41`。(5) 复查 5 条 finding：grep 断言 `data-state-overview` 含 state 获取方式（`handler.state`/`this.state`/`env.state`）、`data-vs-render` 无 `Mota`、`enemy-map-damage` 无 `core.flags`、`hero-attribute` 不含「临时的加减与百分比」旧标题、`combat-overview` 含「计算后怪物」「buildup」并解释分阶段。(6) 读者视角审阅记录 `10-11-READER-REVIEW.md` 存在且阻断问题为 0（或余项已交用户）。发现任何缺页/错链只报告，不擅自补写。</action>
|
||||
<verify>
|
||||
<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'); foreach($n in $names){ $p="docs/intermediate/$n.md"; if(-not(Test-Path $p)){ Write-Error "MISSING $p" }; $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" } }; $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 ',')) }; $ds=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/data-state-overview.md')); if($ds -notmatch 'handler\.state' -or $ds -notmatch 'this\.state'){ Write-Error "STATE-ACQ-MISSING" }; if(([IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/data-vs-render.md'))) -match 'Mota'){ Write-Error "LEGACY-MOTA" }; if(([IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/enemy-map-damage.md'))) -match 'core\.flags'){ Write-Error "LEGACY-COREFLAGS" }; if(([IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/hero-attribute.md'))) -match '临时的加减与百分比'){ Write-Error "BAD-MODIFIER-HEADING" }; $co=[IO.File]::ReadAllText((Resolve-Path 'docs/intermediate/combat-overview.md')); if($co -notmatch '计算后怪物' -or $co -notmatch 'buildup'){ Write-Error "COMBAT-INTRO-MISSING" }; if(-not (Test-Path '.planning/phases/10-docs-restructure/10-11-READER-REVIEW.md')){ Write-Error "NO-READER-REVIEW" }; $ext=@(); foreach($n in $names){ $p="docs/intermediate/$n.md"; $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 ',')) }; $ErrorActionPreference='Continue'; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; $ec=$LASTEXITCODE; $ErrorActionPreference='Stop'; if($ec -ne 0){ $out | Write-Output; exit 1 }; $txt = ($out | ForEach-Object { $_.ToString() }) -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 'REACCEPT-OK'</automated>
|
||||
<fails_when>non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "SIDEBAR-TARGETS", "STATE-ACQ-MISSING", "LEGACY-MOTA", "LEGACY-COREFLAGS", "BAD-MODIFIER-HEADING", "COMBAT-INTRO-MISSING", "NO-READER-REVIEW", "EXT-LINK-NOT-APPROVED", "NO-BUILD-COMPLETE", "DEAD-LINK", "IMPORT-FAIL", or output lacks "REACCEPT-OK"</fails_when>
|
||||
</verify>
|
||||
<done>构建通过且产物生成、dead-link = 0；24 文件齐全、CRLF、单 H1；sidebar 24 目标一一对应；5 条 finding 复查通过；读者视角审阅记录存在；无非白名单外链；输出 REACCEPT-OK。</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 2: 交付构建产物供用户 D-09 复审（重跑 10-06 Task 2 门禁）</name>
|
||||
<action>向用户交付验收结果并请求 D-09 复审。提供审阅方式：本地 `cmd /c "pnpm docs:preview"` 预览 `public/_docs`，或自行浏览构建产物；附上 Task 1 的核对结果摘要（文件数、sidebar 目标数、外链白名单命中、构建结论、5 条 finding 复查结果）。请用户逐条确认：**finding ①** `state` 获取已讲清；**②** 战斗组对新手友好（buildup / 分阶段已解释）；**③** 无 legacy 泄漏；**④** 修饰器定位正确；**⑤** 引导式书写到位；并核对**内容正确且可读**、**侧边栏分组与顺序符合 4/8/9/3**、**无元叙述（D-16）**。说明首页 `docs/index.md` 本批随旧内容删除、**有意缺省**，不作为问题。等待用户确认通过；若指出需修改项，记录并转交对应修订计划（10-07..10-11）修复，不在本计划内擅自补写。本任务与 `/gsd-verify-work 10` 的收尾互为补充，不替代阶段级验证。</action>
|
||||
<what-built>已构建的站点产物 `public/_docs`（含修订后的 24 篇与注册好的侧边栏/导航）与 Task 1 的验收结果摘要。</what-built>
|
||||
<how-to-verify>本地运行 `cmd /c "pnpm docs:preview"` 预览，或浏览构建产物；逐条核对 5 条 finding 与三项（内容正确且可读、侧边栏 4/8/9/3、无元叙述）。如有需修改项请指出。</how-to-verify>
|
||||
<resume-signal>回复「通过」表示 D-09 复审通过；如给出修改意见，请一并说明，待修正对应计划后再回复「通过」。其它回复视为未通过。</resume-signal>
|
||||
<verify>
|
||||
<human-check>用户已完成复审并对 24 篇内容、5 条 finding、侧边栏结构、链接给出通过或具体修改意见。</human-check>
|
||||
</verify>
|
||||
<done>用户确认 D-09 复审通过（或产出的修改意见已登记并转交对应计划）。</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| 构建期 markdown → 静态站点 | 构建期静态渲染，无运行时输入 |
|
||||
| 站点 → 浏览器读者 | 外链是唯一对外指向面 |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-10-34 | Tampering / XSS | 构建产物 | low | mitigate | 构建为纯静态 markdown 渲染；无原始 `<script>` 注入 |
|
||||
| T-10-35 | Spoofing | 外链 | low | mitigate | Task 1 断言全批唯一外链为 D-23 批准的 `h5mota.com` 链接 |
|
||||
| T-10-36 | Information Disclosure | 构建产物/摘要 | low | mitigate | 构建产物 gitignored；正文不含密钥/账号 |
|
||||
| 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"` 通过且 dead-link = 0。
|
||||
- 完整性门禁：24 文件齐全 + sidebar 去重后 24 个目标 + 文件/目标一一对应。
|
||||
- 修正门禁：5 条 finding 的静态复查断言全部通过。
|
||||
- 外链门禁：全批唯一外链为 D-23 批准的链接。
|
||||
- 人工门禁：用户完成 D-09 复审。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- D-09 复审的三项（人工审阅 + 链接有效 + 构建通过）在修订后全部满足。
|
||||
- 5 条 finding 与读者视角审阅阻断问题均确认处置。
|
||||
- 24 篇落位、注册、可构建、可预览；无越界改动。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/10-docs-restructure/10-12-SUMMARY.md` when done
|
||||
</output>
|
||||
Loading…
Reference in New Issue
Block a user