diff --git a/.planning/phases/10-docs-restructure/10-21-PLAN.md b/.planning/phases/10-docs-restructure/10-21-PLAN.md index 1772d63..abcf2bc 100644 --- a/.planning/phases/10-docs-restructure/10-21-PLAN.md +++ b/.planning/phases/10-docs-restructure/10-21-PLAN.md @@ -83,7 +83,7 @@ Output: 两篇可构建的 `docs/advanced/ii/*.md` 正文。 - D-47：指向高级 III 或尚不存在的页面时，只用代码 span（如 `高级 III · 范围性能`）或 `` 注释。 **写法口径：** -- 两篇都面向「有较好代码能力、能读懂引擎源码、想做系统级定制，但不熟悉具体系统实现」的读者。 +- 两篇都面向「已经理解了绝大多数常用语法；认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白」的数据端读者（D-68：不预设资深开发者水平，也不要求通读引擎源码）；想做系统级定制，但对具体系统实现还不熟悉。 - 需要读者实现接口时给完整骨架，并用 `[需改]` 标出改动点；纯接口调用只给短示例。 - 每一篇结尾给「怎么验证」段：给出可执行的调用或控制台检查方式，并说明预期现象。 @@ -96,7 +96,7 @@ Output: 两篇可构建的 `docs/advanced/ii/*.md` 正文。 1. 目录 `docs/advanced/ii/`； 2. 九篇文件名：`index.md`、`custom-range.md`、`static-vs-dynamic-tiles.md`、`equipment-system.md`、`custom-replay-command.md`、`pathfinding.md`、`adding-hero-attribute.md`、`adding-enemy-attribute.md`、`enemy-context-and-combat.md`； 3. 侧边栏分组显示名由「高级 II · 系统实现」改为「高级 II · 深入定制」（D-53 的分层是难度标签，不是领域分类）； -4. 高级 II 读者人格：「你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现；你已经读完高级 I，正在读高级 II。」 +4. 高级 II 读者人格（D-68）：「你已经理解了绝大多数常用语法；认真阅读样板后，你能把一部分简单系统和中等复杂度的系统读明白。你是一位想做系统级定制的数据端作者，但还不熟悉具体系统实现；你已经读完高级 I，正在读高级 II。」不预设资深开发者水平，也不要求通读引擎源码。 汇报中明确：本计划的修改方式为**派发子代理执行**，范围严格限于 `files_modified` 列出的两篇文档，执行者不内联修改文件。停下等待用户明确回复「可以执行」四个字；未收到前不得创建目录、不得写任何文档、不得派发子代理。 本计划内容：高级 II 两篇基础文档 + 整套高级 II 的命名与流程基线。 阅读上面的四段说明，重点确认九篇文件名、侧边栏分组名与读者人格；如要改名请直接给出替代名称。 diff --git a/.planning/phases/10-docs-restructure/10-25-PLAN.md b/.planning/phases/10-docs-restructure/10-25-PLAN.md index a631d05..5a3226e 100644 --- a/.planning/phases/10-docs-restructure/10-25-PLAN.md +++ b/.planning/phases/10-docs-restructure/10-25-PLAN.md @@ -80,7 +80,7 @@ Output: `docs/advanced/ii/index.md`、侧边栏注册、跨篇链接与构建产 - `nav` 保持现状（中级教程、高级教程），不新增导航项。 **导览口径：** -- 定位：高级 II 是「深入定制」难度层；读者需要能读懂引擎源码，目标是把某个具体系统改到自己的需求上。 +- 定位：高级 II 是「深入定制」难度层；读者已经理解了绝大多数常用语法，认真阅读样板后能把一部分简单系统和中等复杂度的系统读明白（D-68：不预设资深开发者水平，也不要求通读引擎源码）；目标是把某个具体系统改到自己的需求上。 - 前置：高级 I 全部（尤其 `declarative-vs-imperative`、`plugin-system`、`saveable-content`、`replay-consistency`）+ 中级相关篇目（`enemy-aura`、`enemy-query`、`enemy-final`、`enemy-calculator`、`enemy-map-damage`、`hero-equipment`、`hero-attribute`、`replay-commands`、`map-tiles`）。 - 阅读路径建议三条：系统定制（范围 → 图块 → 装备 → 勇士属性 → 怪物属性 → 上下文与战斗）、行为扩展（录像指令 → 寻路）、按需查阅（哪篇解决什么问题）。 - 边界：只写数据端；渲染端、编辑器、状态栏、怪物图鉴按 D-47 占位；原理与架构留给高级 III。 @@ -108,7 +108,7 @@ Output: `docs/advanced/ii/index.md`、侧边栏注册、跨篇链接与构建产 Task 1: 编写高级 II 导览 ii/index.md docs/advanced/ii/index.md 写 `docs/advanced/ii/index.md`，单 H1「高级 II 导览」。正文顺序： -1. **高级 II 是给谁的**：面向能读懂引擎源码、想把某个具体系统改到需求上的数据端作者；不是引擎编写者；本层只写数据端。 +1. **高级 II 是给谁的**：面向已经理解了绝大多数常用语法、认真阅读样板后能把一部分简单系统和中等复杂度的系统读明白的数据端作者（D-68：不预设资深开发者水平，也不要求通读引擎源码）；目标是把某个具体系统改到需求上；不是引擎编写者；本层只写数据端。 2. **难度层定位**：用一段说明 I / II / III 的区别（I 扩展基础、II 深入定制、III 原理与架构），并强调分层是难度标签，不是领域分类；高级 III 只用代码 span `高级 III · ...` 或 `` 占位，不写真实链接。 3. **前置**：列出高级 I 的六篇（真实链接 `../declarative-vs-imperative.md` 等）与中级相关篇目（`../../intermediate/...`）；说明至少要读过高级 I 的声明式、插件、可存档、录像一致性四篇。 4. **本层包含什么**：一张九行表（导览 + 八篇），每行写「篇名 / 一句话能让你做什么 / 前置」；八篇都给真实相对链接（`./custom-range.md`、`./static-vs-dynamic-tiles.md`、`./equipment-system.md`、`./custom-replay-command.md`、`./pathfinding.md`、`./adding-hero-attribute.md`、`./adding-enemy-attribute.md`、`./enemy-context-and-combat.md`）。 diff --git a/.planning/phases/10-docs-restructure/10-26-PLAN.md b/.planning/phases/10-docs-restructure/10-26-PLAN.md index daff2e2..57a9331 100644 --- a/.planning/phases/10-docs-restructure/10-26-PLAN.md +++ b/.planning/phases/10-docs-restructure/10-26-PLAN.md @@ -25,7 +25,7 @@ estimate: confidence: low must_haves: truths: - - "读者人格是「有较好代码能力、能读懂引擎源码、想做系统级定制，但还不熟悉具体系统实现」的数据端作者——标准高于高级 I，且不复用高级 I 或中级教程的人格（D-46 第 1 阶段 / D-57）" + - "读者人格按 D-68 设定：数据端作者，已经理解了绝大多数常用语法；认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白——不预设高代码水平，且不复用高级 I 或中级教程的人格（D-46 第 1 阶段 / D-57 / D-68）" - "`10-26-READER-REVIEW.md` 逐字记录人格提示词、审阅范围（高级 II 九篇）、问题清单，并按阻断性与非阻断归类、定位到文件与章节" - "阻断性问题被迭代修正（上限 3 轮）；每轮后构建 green、`build complete`、dead link = 0；达到上限仍有阻断问题时停下交用户" - "迭代结束再派发一个独立子代理（同一人格）复审，记录逐条标注「已消除」或「仍存在」；结束标记为「阻断性问题 = 0」或「阻断性问题余项：已交用户」" @@ -36,15 +36,15 @@ must_haves: - "docs/advanced/ii/*.md（仅存在阻断性问题的篇目）" - ".planning/phases/10-docs-restructure/10-26-SUMMARY.md" key_links: - - "执行 D-46 第 1 阶段：独立的高代码能力读者人格 → 问题清单 → 迭代修正 → 复审" + - "执行 D-46 第 1 阶段：按 D-68 设定、独立于高级 I / 中级的读者人格 → 问题清单 → 迭代修正 → 复审" - "复审通过后，10-27 才进入用户主导的修订循环；本计划不替用户收尾" - "审阅对象是 10-25 已接入侧边栏的九篇，而不是未注册草稿" --- -执行高级 II 的独立读者审阅：派发一个与高级 I、中级教程都**不同人格**的独立子代理（有较好代码能力、能读懂引擎源码、想做系统级定制、但还不熟悉具体系统实现的数据端作者），通读九篇高级 II，产出问题清单；据此迭代修正阻断性问题，最后再派一个同人格独立子代理复审，直到阻断问题为零或把余项交给用户。 +执行高级 II 的独立读者审阅：派发一个与高级 I、中级教程都**不同人格**的独立子代理（不预设高代码水平：已理解绝大多数常用语法，认真阅读样板后能把一部分简单系统和中等复杂度的系统读明白的数据端作者），通读九篇高级 II，产出问题清单；据此迭代修正阻断性问题，最后再派一个同人格独立子代理复审，直到阻断问题为零或把余项交给用户。 -Purpose: 高级 II 的读者会真的去改接口、接系统、调优先级，所以问题不再是「这段代码放哪」，而是「这条链路是否成立」「改完之后为什么没生效」「优先级/脏标记/存档是否被写反」。这批问题只能由具备源码阅读能力的读者视角发现。 +Purpose: 高级 II 的读者会真的去改接口、接系统、调优先级，所以问题不再是「这段代码放哪」，而是「这条链路是否成立」「改完之后为什么没生效」「优先级/脏标记/存档是否被写反」。按 D-68，这批问题应由「已理解常用语法、能读懂样板与一部分中等复杂度系统、但对具体系统实现还不熟悉」的读者视角发现，而不是由资深引擎开发者视角发现。 Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对阻断问题的文档修正。 @@ -67,19 +67,21 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 @docs/advanced/ii/adding-enemy-attribute.md @docs/advanced/ii/enemy-context-and-combat.md -**人格设定（D-46 / D-57，不得复用高级 I 或中级人格）：** -> 你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现。你已经读完高级 I，正在读高级 II，想判断自己能不能按文档完成一次真正的系统改造。 +**人格设定（D-46 / D-57 / D-68，不得复用高级 I 或中级人格）：** +> 你已经理解了绝大多数常用语法；认真阅读本样板后，你能把一部分简单系统和中等复杂度的系统读明白。你正在读高级 II，想做更深入的定制，但对具体系统实现还不熟悉。 -**与高级 I 审阅的区别：** -- 高级 I 人格是「了解基本语法但代码能力一般」；本计划**禁止**复用该人格或其提示词，也不使用中级的「不懂代码」人格。 -- 高级 II 读者能读源码、能判断接口调用是否成立；问题应落在「流程/时序是否讲对」「改了接口后还有哪些地方必须同步」「优先级与脏标记是否会导致不生效」「存档/录像/装备的恢复路径是否自洽」。 +**与高级 I / 中级审阅的区别：** +- 高级 I 人格是「了解基本语法但代码能力一般」；中级人格是「不懂代码的游戏作者」。本计划**禁止**复用其中任何一种人格或其提示词。 +- 高级 II 人格**不预设高代码水平**（不是资深引擎开发者，也不要求能通读引擎源码），但要求「已理解绝大多数常用语法」且「认真阅读样板后能读懂一部分简单与中等复杂度的系统」——标准高于高级 I，但明显低于「资深引擎开发者」。 +- 因此问题应落在「流程/时序是否讲对」「这个系统到底由哪几个部分组成」「改了接口后还有哪些地方必须同步」「优先级与脏标记是否会导致不生效」「存档/录像/装备的恢复路径是否自洽」；读者可以按文档打开被引用的样板与源码核对，但不能假定他自行通读引擎。 - 审阅对象是 `docs/advanced/ii/` 的九篇，不是高级 I 的七篇。 **流程约定：** - 迭代上限 **3 轮**；每轮后跑构建门禁；达到上限仍有阻断问题时停下向用户汇报。 +- 文档难度同样按 D-68：不假设读者能读懂整个引擎，也不把「必须读过源码才能看懂某段」当成可接受前提；被引用的样板与源码可作为核对材料，但正文需能支撑「已理解常用语法 + 认真读样板」的读者完成改造。 - 只改 `docs/advanced/ii/*.md`；不触碰 `config.ts`、生产代码与渲染端内容。 - 命令一律经 `cmd /c "..."` 执行（本机 PowerShell 禁止 `pnpm.ps1`）。 -- 修正须守住 D-53..D-67 与 D-59..D-66；不因读者提问删掉要求覆盖的内容。 +- 修正须守住 D-53..D-68 与 D-59..D-66；不因读者提问删掉要求覆盖的内容。 - 阻断性判定口径：读者据此**无法完成系统改造**，或会对**流程/时序/系统边界产生实质误解**。 - 非阻断问题只记录，不修（D-14），留给 10-27 的用户循环决定。 @@ -88,9 +90,9 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 Task 0: 向用户汇报读者审阅计划并确认人格 - 向用户汇报：**要做什么**（派发独立子代理，以「有较好代码能力、能读懂引擎源码、想做系统级定制，但还不熟悉具体系统实现」的人格通读高级 II 九篇，产出问题清单，据此迭代修正并复审）、**为什么**（D-46 第 1 阶段要求子代理自审；D-57 允许高级 II 提高标准，且不能复用高级 I / 中级教程的人格）、**大致怎么做**（Task 1 派发 persona 子代理并落清单；Task 2 按清单修阻断问题，最多 3 轮、每轮构建；Task 3 复跑同人格审阅确认阻断清零）、**影响范围**（可能修改 `docs/advanced/ii/*.md` 中确有阻断问题的篇目 + 新增 `.planning` 下的审阅记录；不改站点配置与生产代码）。请用户逐字确认人格提示词：「你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现。你已经读完高级 I，正在读高级 II，想判断自己能不能按文档完成一次真正的系统改造。」汇报中明确：该人格标准高于高级 I（要求能读源码），但不是引擎作者；本计划的修改方式为**派发子代理执行**，范围严格限于 `docs/advanced/ii/*.md` 与 `.planning/.../10-26-READER-REVIEW.md`。停下等待用户明确回复「可以执行」四个字；未收到前不得派发子代理或改任何文件。 - 本计划内容：高级 II 独立高代码能力读者审阅 → 问题清单 → 迭代修正 → 复审确认。 - 阅读上面的四段说明；确认人格提示词高于高级 I、审阅范围是高级 II 九篇、迭代上限 3 轮；如对人格有修改请直接给出。 + 向用户汇报：**要做什么**（派发独立子代理，以「已经理解了绝大多数常用语法；认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白，但对具体系统实现还不熟悉」的人格通读高级 II 九篇，产出问题清单，据此迭代修正并复审）、**为什么**（D-46 第 1 阶段要求子代理自审；D-68 明确不给高级 II 读者预设高代码水平，且不能复用高级 I / 中级教程的人格）、**大致怎么做**（Task 1 派发 persona 子代理并落清单；Task 2 按清单修阻断问题，最多 3 轮、每轮构建；Task 3 复跑同人格审阅确认阻断清零）、**影响范围**（可能修改 `docs/advanced/ii/*.md` 中确有阻断问题的篇目 + 新增 `.planning` 下的审阅记录；不改站点配置与生产代码）。请用户逐字确认人格提示词：「你已经理解了绝大多数常用语法；认真阅读本样板后，你能把一部分简单系统和中等复杂度的系统读明白。你正在读高级 II，想做更深入的定制，但对具体系统实现还不熟悉。」汇报中明确：该人格**不预设高代码水平**（不是资深引擎开发者，不要求能通读引擎源码），但要求已理解常用语法、认真读样板后能读懂一部分简单与中等复杂度系统；与高级 I 人格（代码能力一般）和中级人格（不懂代码）都不同。本计划的修改方式为**派发子代理执行**，范围严格限于 `docs/advanced/ii/*.md` 与 `.planning/.../10-26-READER-REVIEW.md`。停下等待用户明确回复「可以执行」四个字；未收到前不得派发子代理或改任何文件。 + 本计划内容：高级 II 独立读者审阅（D-68 人格：不预设高代码水平）→ 问题清单 → 迭代修正 → 复审确认。 + 阅读上面的四段说明；确认人格提示词与高级 I / 中级都不同、不预设高代码水平、审阅范围是高级 II 九篇、迭代上限 3 轮；如对人格有修改请直接给出。 回复「可以执行」以继续；其它回复视为未批准，本计划停在此处。 用户已确认人格提示词并回复「可以执行」。 @@ -101,9 +103,9 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 Task 1: 派发独立读者子代理并产出问题清单 .planning/phases/10-docs-restructure/10-26-READER-REVIEW.md - 派发一个**独立子代理**（不与执行者共享上下文），其人格与任务设定逐字为：「你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现。你已经读完高级 I，正在读高级 II，想判断自己能不能按文档完成一次真正的系统改造。」让子代理按 `docs/advanced/ii/index.md` 的推荐顺序通读九篇（导览、范围、图块、装备、录像、寻路、勇士属性、怪物属性、上下文与战斗），允许它打开文档引用的源码核对，然后回答：「读完后你有哪些问题？哪些地方你照做会卡住、会改错接口、会把流程/时序理解反，或者会让存档/录像/伤害结果不一致？」子代理**只以读者身份提问**、不修改文件、不代入引擎作者视角。把原始提问与执行者的归类写进 `.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md`：开头逐字记录高级 II 人格提示词与九篇范围，并单独写一行「未复用高级 I 人格」标记；每条问题附文件与章节定位；按**阻断性**与**非阻断**分组。阻断性口径：读者据此无法完成系统改造，或会对流程/时序/系统边界产生实质误解。**本轮不改文档**。Commit：`docs(10-26): 记录高级 II 读者问题清单`。 + 派发一个**独立子代理**（不与执行者共享上下文），其人格与任务设定逐字为：「你已经理解了绝大多数常用语法；认真阅读本样板后，你能把一部分简单系统和中等复杂度的系统读明白。你正在读高级 II，想做更深入的定制，但对具体系统实现还不熟悉。」让子代理按 `docs/advanced/ii/index.md` 的推荐顺序通读九篇（导览、范围、图块、装备、录像、寻路、勇士属性、怪物属性、上下文与战斗），可以打开文档中被引用的样板/源码核对，但**不假定它已通读引擎**，然后回答：「读完后你有哪些问题？哪些地方你照做会卡住、会改错接口、会把流程/时序理解反，或者会让存档/录像/伤害结果不一致？」子代理**只以读者身份提问**、不修改文件、不代入引擎作者视角。把原始提问与执行者的归类写进 `.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md`：开头逐字记录高级 II 人格提示词与九篇范围，并单独写一行「未复用高级 I 人格」标记；每条问题附文件与章节定位；按**阻断性**与**非阻断**分组。阻断性口径：读者据此无法完成系统改造，或会对流程/时序/系统边界产生实质误解。**本轮不改文档**。Commit：`docs(10-26): 记录高级 II 读者问题清单`。 - $ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $f)){ Write-Error "MISSING $f" }; $raw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $f)); foreach($needle in @('较好代码能力','能读懂引擎源码','系统级定制','不熟悉具体系统实现','已读完高级 I','未复用高级 I 人格','阻断','非阻断','docs/advanced/ii/index.md')){ if($raw -notmatch [regex]::Escape($needle)){ Write-Error "MISSING-CONTENT $needle" } }; $flat=$raw -replace '\s',''; $persona='你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现。你已经读完高级I，正在读高级II，想判断自己能不能按文档完成一次真正的系统改造。'; if(-not $flat.Contains($persona)){ Write-Error "MISSING-PERSONA-PROMPT" }; Write-Output 'REVIEW-II-OK' + $ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $f)){ Write-Error "MISSING $f" }; $raw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $f)); foreach($needle in @('绝大多数常用语法','认真阅读本样板后','一部分简单系统和中等复杂度的系统','想做更深入的定制','对具体系统实现还不熟悉','未复用高级 I 人格','阻断','非阻断','docs/advanced/ii/index.md')){ if($raw -notmatch [regex]::Escape($needle)){ Write-Error "MISSING-CONTENT $needle" } }; $flat=$raw -replace '\s',''; $persona='你已经理解了绝大多数常用语法；认真阅读本样板后，你能把一部分简单系统和中等复杂度的系统读明白。你正在读高级II，想做更深入的定制，但对具体系统实现还不熟悉。'; if(-not $flat.Contains($persona)){ Write-Error "MISSING-PERSONA-PROMPT" }; Write-Output 'REVIEW-II-OK' non-zero exit, or output contains "MISSING" or "MISSING-CONTENT"; or output lacks "REVIEW-II-OK" 审阅记录存在；逐字含高级 II 人格提示词与九篇范围；问题按阻断/非阻断归类并定位到文件章节；标记未复用高级 I 人格。 @@ -112,7 +114,7 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 Task 2: 按清单迭代修正阻断问题（上限 3 轮） docs/advanced/ii/*.md（仅存在阻断性问题的篇目）, .planning/phases/10-docs-restructure/10-26-READER-REVIEW.md - 逐个消除 `10-26-READER-REVIEW.md` 中的**阻断性问题**：对每个阻断问题，修改对应 `docs/advanced/ii/*.md` 的相应段落，使一个「能读源码但不熟悉具体系统实现」的读者也能完成改造——补「这条链路还缺哪一步」「改完要标脏/刷新才生效」「优先级为什么会拦住新光环」「读档/录像时哪条路径负责恢复」；必要时补完整示例或调整章节顺序。只改确有阻断问题的篇目；非阻断问题不修、仅保留在清单中供用户判断（D-14）。每轮修正后：(a) 跑构建门禁 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，须 green、`build complete`、dead link = 0；(b) 在 `10-26-READER-REVIEW.md` 追加该轮记录（本轮修了哪些问题、依据、构建结论）。迭代**最多 3 轮**：3 轮后仍有阻断问题时，停下把余项列给用户，不继续循环。守住 D-53..D-67 与 D-59..D-66，不因读者提问删掉要求覆盖的内容；不改 `config.ts`、生产代码与渲染端内容。每轮 Commit：`docs(10-26): 迭代修正高级 II 阻断问题（第N轮）`。 + 逐个消除 `10-26-READER-REVIEW.md` 中的**阻断性问题**：对每个阻断问题，修改对应 `docs/advanced/ii/*.md` 的相应段落，使一个「已理解绝大多数常用语法、认真读样板后能读懂一部分简单与中等复杂度系统，但对具体系统实现还不熟悉」的读者也能完成改造——补「这条链路还缺哪一步」「这个系统由哪几个部分组成」「改完要标脏/刷新才生效」「优先级为什么会拦住新光环」「读档/录像时哪条路径负责恢复」；必要时补完整示例或调整章节顺序。只改确有阻断问题的篇目；非阻断问题不修、仅保留在清单中供用户判断（D-14）。每轮修正后：(a) 跑构建门禁 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`，须 green、`build complete`、dead link = 0；(b) 在 `10-26-READER-REVIEW.md` 追加该轮记录（本轮修了哪些问题、依据、构建结论）。迭代**最多 3 轮**：3 轮后仍有阻断问题时，停下把余项列给用户，不继续循环。守住 D-53..D-68 与 D-59..D-66，不因读者提问删掉要求覆盖的内容；不改 `config.ts`、生产代码与渲染端内容。每轮 Commit：`docs(10-26): 迭代修正高级 II 阻断问题（第N轮）`。 $ErrorActionPreference='Stop'; $names=@('index','custom-range','static-vs-dynamic-tiles','equipment-system','custom-replay-command','pathfinding','adding-hero-attribute','adding-enemy-attribute','enemy-context-and-combat'); foreach($n in $names){ $p="docs/advanced/ii/$n.md"; if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $raw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($raw -match "(?&1; $ec=$LASTEXITCODE; $ErrorActionPreference='Stop'; if($ec -ne 0){ $out | Write-Output; Write-Error "BUILD-FAIL" }; $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-II-OK' non-zero exit, or output contains "MISSING", "LF-ONLY", "H1-COUNT", "NO-ROUND-LOG", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "ITERATE-II-OK" @@ -123,9 +125,9 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 Task 3: 复跑同人格审阅确认阻断清零 .planning/phases/10-docs-restructure/10-26-READER-REVIEW.md - 再次派发一个**独立子代理**（人格提示词逐字同 Task 1，不得换回高级 I 或中级人格），让它重新通读九篇并回答「现在还有哪些看不懂、照做会卡住、会把流程/时序理解反，或会让存档/录像/伤害结果不一致的地方？」。把复审结果追加进 `10-26-READER-REVIEW.md`：对照首轮清单，逐条标注「已消除」或「仍存在」；若仍有**阻断性**问题，回到 Task 2 再修（受 3 轮上限约束）。收敛时二选一写结构化结束标记：阻断问题清零记「阻断性问题 = 0，审阅通过」；3 轮上限后仍有阻断问题记「阻断性问题余项：已交用户」并列出余项与用户处置。复审记录同样保留「未复用高级 I 人格」标记。最后跑一次构建门禁确认 green。本任务不引入新功能，只收敛理解性问题。Commit：`docs(10-26): 复审高级 II 读者视角（收敛）`。 + 再次派发一个**独立子代理**（人格提示词逐字同 Task 1（D-68 标准），不得换回高级 I 或中级人格），让它重新通读九篇并回答「现在还有哪些看不懂、照做会卡住、会把流程/时序理解反，或会让存档/录像/伤害结果不一致的地方？」。把复审结果追加进 `10-26-READER-REVIEW.md`：对照首轮清单，逐条标注「已消除」或「仍存在」；若仍有**阻断性**问题，回到 Task 2 再修（受 3 轮上限约束）。收敛时二选一写结构化结束标记：阻断问题清零记「阻断性问题 = 0，审阅通过」；3 轮上限后仍有阻断问题记「阻断性问题余项：已交用户」并列出余项与用户处置。复审记录同样保留「未复用高级 I 人格」标记。最后跑一次构建门禁确认 green。本任务不引入新功能，只收敛理解性问题。Commit：`docs(10-26): 复审高级 II 读者视角（收敛）`。 - $ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $f)){ Write-Error "MISSING $f" }; $raw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $f)); foreach($needle in @('较好代码能力','能读懂引擎源码','系统级定制','不熟悉具体系统实现','已读完高级 I','已消除','仍存在','未复用高级 I 人格')){ if($raw -notmatch [regex]::Escape($needle)){ Write-Error "MISSING-CONTENT $needle" } }; $flat=$raw -replace '\s',''; $persona='你是一位有较好代码能力、能读懂引擎源码的数据端作者，想做系统级定制，但还不熟悉具体系统实现。你已经读完高级I，正在读高级II，想判断自己能不能按文档完成一次真正的系统改造。'; if(-not $flat.Contains($persona)){ Write-Error "MISSING-PERSONA-PROMPT" }; if($raw -notmatch '阻断性问题 = 0' -and $raw -notmatch '阻断性问题余项：已交用户'){ Write-Error "NO-TERMINAL-MARKER" }; $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; Write-Error "BUILD-FAIL" }; $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-II-OK' + $ErrorActionPreference='Stop'; $f='.planning/phases/10-docs-restructure/10-26-READER-REVIEW.md'; if(-not(Test-Path -LiteralPath $f)){ Write-Error "MISSING $f" }; $raw=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $f)); foreach($needle in @('绝大多数常用语法','认真阅读本样板后','一部分简单系统和中等复杂度的系统','想做更深入的定制','对具体系统实现还不熟悉','已消除','仍存在','未复用高级 I 人格')){ if($raw -notmatch [regex]::Escape($needle)){ Write-Error "MISSING-CONTENT $needle" } }; $flat=$raw -replace '\s',''; $persona='你已经理解了绝大多数常用语法；认真阅读本样板后，你能把一部分简单系统和中等复杂度的系统读明白。你正在读高级II，想做更深入的定制，但对具体系统实现还不熟悉。'; if(-not $flat.Contains($persona)){ Write-Error "MISSING-PERSONA-PROMPT" }; if($raw -notmatch '阻断性问题 = 0' -and $raw -notmatch '阻断性问题余项：已交用户'){ Write-Error "NO-TERMINAL-MARKER" }; $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; Write-Error "BUILD-FAIL" }; $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-II-OK' non-zero exit, or output contains "MISSING", "MISSING-CONTENT", "NO-TERMINAL-MARKER", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "RECHECK-II-OK" 复审结果记录进 `10-26-READER-REVIEW.md`（逐条已消除/仍存在）；结束标记为「阻断性问题 = 0」或「阻断性问题余项：已交用户」；构建 green、`build complete`、dead link = 0。 @@ -154,7 +156,7 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 - 机制门禁：`10-26-READER-REVIEW.md` 含高级 II 人格提示词（按空白归一化后逐字包含完整提示词）、九篇范围、首轮问题清单、每轮迭代记录、复审对照结果。 -- 人格门禁：记录含「较好代码能力」「能读懂引擎源码」「系统级定制」「不熟悉具体系统实现」「已读完高级 I」与「未复用高级 I 人格」标记。 +- 人格门禁：记录含「绝大多数常用语法」「认真阅读本样板后」「一部分简单系统和中等复杂度的系统」「想做更深入的定制」「对具体系统实现还不熟悉」与「未复用高级 I 人格」标记。 - 迭代门禁：上限 3 轮；结束标记为「阻断性问题 = 0」或「阻断性问题余项：已交用户」。 - 构建门禁：每轮及收尾均 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` 通过。 - 结构门禁：九篇仍 kebab-case、CRLF、单 H1。 @@ -162,7 +164,7 @@ Output: `10-26-READER-REVIEW.md`（人格、问题、迭代、复审）与针对 -- 高级 II 的读者人格审阅按 D-46 第 1 阶段落地：独立子代理 + 更高标准人格 + 问题清单 + 迭代 + 复审。 +- 高级 II 的读者人格审阅按 D-46 第 1 阶段落地：独立子代理 + D-68 人格（不预设高代码水平）+ 问题清单 + 迭代 + 复审。 - 阻断性问题清零（或余项已明确交用户）；构建通过。 - 没有复用高级 I / 中级人格，没有越界改动。 diff --git a/.planning/phases/10-docs-restructure/10-CONTEXT.md b/.planning/phases/10-docs-restructure/10-CONTEXT.md index b192266..0aafc41 100644 --- a/.planning/phases/10-docs-restructure/10-CONTEXT.md +++ b/.planning/phases/10-docs-restructure/10-CONTEXT.md @@ -189,6 +189,7 @@ 8. **新增怪物属性**：修改 `IEnemyAttr`；同样用攻速/护甲举例；接入战斗/光环/查询；编辑器新增项、怪物手册（图鉴）修改按 D-47 **留空**； 9. **怪物上下文与战斗深入**：buildup 管线、优先级、缓存/脏标记、伤害系统与光环/查询/最终的交互。 推荐顺序：导览 → 范围对象 → 图块（含点事件/图块事件）→ 装备 → 录像指令 → 寻路 → 勇士属性 → 怪物属性 → 怪物上下文与战斗。仍以数据端为主；渲染端与编辑器内容按 D-47 占位。 +- **D-68（高级 II 读者水平）：** 不要给高级 II 读者预设过高的代码水平。目标读者应设定为：**已经理解了绝大多数常用语法；认真阅读样板后，能把一部分简单系统和中等复杂度的系统读明白**。审阅人格与文档难度均按此标准，而不是按「资深引擎开发者」预设。