docs: update existing docs with new pack references and governance rules

codefromkarl · codefromkarl · commit d41f6aa4d96a · 2026-05-06T14:27:24.000+08:00
- README.md: localize to Chinese, add quickstart.sh and dependency graph
- plugin-catalog.md: add ai-testing and dialogue pack descriptions
- plugin-integration-standard.md: add autoload naming isolation spec
- rpg-experience-review.md: add completion language rules and session schema
- rpg-template-absorption-plan: mark dialogue/inventory as done
- rpg-template-quickstart, rpg-pack-recipes: link to new playable sample recipe
- open-source-architecture-links: add art/audio asset sources section
- game-architecture-template-plan: update dialogue status to landed pack
- rpg-vendor-license-notice: add dialogue pack notice references
diff --git a/README.md b/README.md
diff --git a/docs/game-architecture-template-plan.md b/docs/game-architecture-template-plan.md
@@ -54,7 +54,7 @@ This prevents future projects from hiding core game truth inside a third-party p
 | --- | --- | --- | --- |
 | `input` | `G.U.I.D.E` | Non-default optional pack | Good fit for unified input across devices. Bootstrap injection contract now exists. |
 | `quest` | `QuestSystem` | Non-default optional pack | Good resource-based quest model. Bootstrap contract now exists; project truth still needs save/event adapters. |
-| `dialogue` | `Dialogue Manager` | Candidate, wait for v4 maturity | Strong stateless dialogue model. Do not promote until Godot 4.6+ requirement and release status are acceptable. |
+| `dialogue` | `Dialogue Manager` | Non-default optional pack (v3.10.4) | Vendored as opt-in dialogue pack. Requires `data-core`, `save-core`, `rules-events-core` adapters. |
 | `inventory` | `GLoot` | Non-default optional pack | Useful for RPG/sim projects. Keep out of base and bridge through project-owned item/save adapters. |
 | `save` | `SaveState Lite`, GDQuest resource save pattern, Godot docs | Optional pack plus references | Save correctness is core truth; SaveState Lite is opt-in tooling/reference, while `save-core` owns the contract. |
 | `data` | `Pandora`, Godot Resource pattern | Reference only initially | Pandora is alpha and RPG-scoped. Build a smaller generic registry/resource scaffold first. |
@@ -288,6 +288,7 @@ Exit criteria:
 Deliverables:
 
 - Evaluate `dialogue` once Dialogue Manager 4 maturity is acceptable.
+- `Dialogue Manager` has been vendored as a non-default `dialogue` pack (v3.10.4); adapter tests for dialogue events crossing `rules-events-core`/`data-core`/`save-core` remain a follow-up task.
 - `GLoot` has been vendored as a non-default `inventory` pack.
 - `SaveState Lite` has been vendored as a non-default `save-state-lite` pack.
 - Add `rules-events-core` before integrating quest/dialogue deeply.
@@ -327,7 +328,7 @@ Exit criteria:
 
 ## Current Recommendation
 
-The next useful repository work is not adding `dialogue`, `inventory`, or `quest` immediately.
+The next useful repository work is not adding `inventory` or `quest` immediately (both are done).
 
 The next useful work is:
 
diff --git a/docs/open-source-architecture-links.md b/docs/open-source-architecture-links.md
@@ -13,16 +13,22 @@ The links are also mirrored in `packs.manifest.json` under `open_source_referenc
 | `inventory` | GLoot | <https://github.com/peter-kish/gloot> | Landed as non-default `inventory` pack; RPG item/equipment truth stays project-owned. |
 | `ai` | Beehave | <https://github.com/bitbrain/beehave> | Landed as non-default `ai-behavior` pack; optional for complex behavior authoring. |
 | `save` | SaveState Lite | <https://github.com/youssof20/savestate> | Landed as non-default `save-state-lite` pack; isolated from `save-core` due to `SaveSlot` class conflict. |
+| `dialogue` | Dialogue Manager | <https://github.com/nathanhoad/godot_dialogue_manager> | Landed as non-default `dialogue` pack; requires adapters before owning project dialogue state. |
 
 Specialized gameplay packs remain non-default. Promotion to default is not allowed unless the toolbox owns the corresponding data, save, event, and verification contract.
 
+## Art And Audio Asset Sources
+
+RPG demo art/audio candidates are tracked separately in `docs/rpg-art-asset-sources.md`. They are source links only until a concrete optional asset pack is imported with license/NOTICE records.
+
 ## Candidate Optional Packs
 
 | Direction | Upstream | Link | Current repository action |
 | --- | --- | --- | --- |
-| `dialogue` | Dialogue Manager | <https://github.com/nathanhoad/godot_dialogue_manager> | Deferred candidate; watch Godot 4.6+ v4 maturity. |
 | `dialogue` | Dialogic | <https://github.com/dialogic-godot/dialogic> | Reference candidate for heavier dialogue/VN workflows. |
 
+Dialogic candidate governance is tracked in `docs/dialogue-pack-candidate-plan.md`; these links remain reference/candidate only and do not grant campaign truth, save schema, event truth, vendoring, or default bootstrap authority.
+
 ## Reference-Only Inputs
 
 | Direction | Upstream | Link | Current repository action |
@@ -45,4 +51,4 @@ The current small functional integration is toolbox-owned rather than direct ven
 - `flow-test-kit` provides a runner-agnostic smoke fixture for mode/result payload checks.
 - `rules-events-core` provides event/condition/effect execution boundaries for future quest, dialogue, inventory, and simulation hooks.
 - `ui-game-shell` provides app-shell primitives without adopting the candidate Maaack template as runtime truth.
-- `inventory`, `quest`, `ai-behavior`, and `save-state-lite` provide opt-in third-party addon surfaces, while RPG combat/character/save adapters remain self-owned.
+- `inventory`, `quest`, `ai-behavior`, `save-state-lite`, and `dialogue` provide opt-in third-party addon surfaces, while RPG combat/character/save adapters remain self-owned.
diff --git a/docs/plugin-catalog.md b/docs/plugin-catalog.md
@@ -55,6 +55,15 @@
 - 适合：需要从外部进程启动 Godot、等待节点/信号、断言运行中 UI 或主流程的项目
 - 边界：只提供测试自动化入口，不接管玩法、存档、数据或主场景真相
 
+### `ai-testing`
+
+- 插件：无，自研 architecture-test-kit
+- 状态：可选 pack，默认不启用
+- 用途：策略驱动探索测试、覆盖率追踪和 Bug 发现模板
+- 适合：需要 AI 驱动的游戏机制探索、覆盖率引导的自动化测试或策略驱动的压力测试的项目
+- 边界：提供测试框架和策略原语，不接管 gameplay 真相、存档、数据或主场景；消费者实现自己的 `TestEnvironment` 和 `HeuristicPolicy`
+- 依赖：`automation` pack（提供 godot-e2e TCP 桥接）
+
 ### `input`
 
 - 插件：`G.U.I.D.E`
@@ -79,6 +88,7 @@
 - 用途：菜单、暂停、modal、loading shell primitives
 - 适合：需要 app shell 起点但不能让第三方模板接管主场景和业务状态的项目
 - 边界：不接管 `run/main_scene`、FlowCore stack、save truth 或项目 UI 文案
+- Recipe：`docs/ui-game-shell-recipe.md` 定义从 shell candidate 吸收菜单/暂停/设置/加载思路的受控路线
 
 ### `inventory`
 
@@ -122,6 +132,18 @@
 
 ## Candidate Packs
 
+Dialogic is tracked only as a future dialogue candidate/reference input in `docs/dialogue-pack-candidate-plan.md`; it is not vendored, not default-enabled, and cannot own campaign truth, save schema, or event truth.
+
+### `dialogue`
+
+- 插件：`Dialogue Manager`
+- 版本：`v3.10.4`
+- 状态：可选 pack，默认不启用
+- 来源：<https://github.com/nathanhoad/godot_dialogue_manager>
+- 用途：对话图/文本资源 authoring、运行时 line playback、choices 和 conversation-local variables
+- 适合：需要对话 authoring/runtime，但仍希望通过 `rules-events-core`、`data-core` 和 `save-core` 持有项目真相的 RPG/冒险项目
+- 边界：不接管 campaign truth、全局剧情进度、存档格式、持久事件历史或 quest/inventory 真相
+
 ### `shell`
 
 - 插件：`Maaack's Game Template`
@@ -130,6 +152,7 @@
 - 用途：主菜单、设置菜单、暂停菜单、Credits、加载页、开场页、输入映射和持久设置参考
 - 适合：已有项目选择性吸收 app shell 能力，或新项目评估菜单/设置壳层起步方案
 - 边界：不接管业务运行时、主场景、autoload、存档真相或玩法状态
+- Recipe：`docs/ui-game-shell-recipe.md` 明确其仅为 candidate/reference，默认产品化路线是 `ui-game-shell`
 
 ## Excluded
 
diff --git a/docs/plugin-integration-standard.md b/docs/plugin-integration-standard.md
@@ -66,4 +66,49 @@
 
 - 默认不改 vendor 行为代码
 - 若必须 patch，要记录原因、范围和升级时的重放方式
-- 一旦出现行为 patch，就按“受维护 fork”看待
+- 一旦出现行为 patch，就按"受维护 fork"看待
+
+## Autoload 命名隔离规范
+
+### 问题
+
+Godot 4.6 headless/CLI 模式下，autoload 注册名与 `class_name` 同名会触发硬性 Parse Error
+（"Class X hides an autoload singleton"），阻塞 gdUnit4 等测试框架的脚本加载。
+
+Editor 模式仅警告，headless 模式直接报错——这是 Godot 解析器在不同上下文中的行为差异。
+
+### 规则
+
+**autoload 注册名 ≠ class_name**
+
+| 层面 | 命名策略 | 示例 |
+|------|---------|------|
+| Autoload 注册名 | 业务用途，短小精悍 | `FlowCore`, `DataCore` |
+| `class_name` | 注册名 + 后缀 | `FlowCoreService`, `DataCoreService` |
+
+### 已有实践
+
+Toolbox 的 8 个 autoload 单例已遵循此模式：
+- `FlowCore` → `class_name FlowCoreService`
+- `SimulationCore` → `class_name SimulationCoreService`
+- `DataCore` → `class_name DataCoreService`
+- ...
+
+项目自研 autoload 必须遵循相同模式。
+
+### 检测工具
+
+- 脚本：`scripts/autoload_name_check.py`（扫描 `project.godot` + `.gd` 文件的 `class_name`）
+- 集成：pre-commit hook（`autoload-name-check`）
+- CI：作为测试前置步骤
+
+### 调用方式
+
+业务代码无需改动——autoload 注册名不变：
+```gdscript
+# 正常调用 autoload 实例方法
+ContentBridge.get_tile("meadow")
+
+# 类型提示使用 class_name
+var bridge: ContentBridgeService = get_node("/root/ContentBridge")
+```
diff --git a/docs/rpg-experience-review.md b/docs/rpg-experience-review.md
@@ -20,6 +20,26 @@ Not allowed from automation alone:
 
 Experience review must add human or AI-assisted playtest notes that inspect clarity, usability, pacing, affordances, sample-content usefulness, and issue reproducibility. Screenshots or video may be attached when captured, but this initial record does not fabricate visual artifacts.
 
+## Completion Language
+
+Allowed completion language for this document:
+
+- `Experience evidence carrier exists`
+- `Experience session schema exists`
+- `Experience review is not_claimed`
+- `Experience review is partial`
+- `human/AI-assisted Experience review remains required`
+
+Forbidden completion language unless a later real session record includes reviewer notes and actual artifacts:
+
+- `playable`
+- `release-ready`
+- `Experience-complete`
+- `Release-ready`
+- `ready to ship`
+
+The current document may describe how to collect those claims, but it must not state that they have been achieved.
+
 ## Evidence Schema
 
 Each review evidence record must include these fields:
@@ -35,6 +55,10 @@ artifact_paths:
 notes: "short reviewer notes, including what was and was not observed"
 ```
 
+Minimum Experience session fields are `timestamp`, `session_id`, `phase`, `actor`, `status`, `artifact_paths`, `notes`, and `claim_boundary`. A session is incomplete when any of those fields are missing or blank after the review is recorded.
+
+`artifact_paths` must only contain repository-relative paths such as `docs/rpg-final-acceptance-receipt.md`, `docs/artifacts/rpg/session-001-ui-tree.json`, or `packs/rpg-test-kit/...`. Do not use local absolute paths, local URL references, home-directory paths, or temporary machine paths in repository documents. If an artifact cannot be committed, record a relative placeholder path and mark the session `blocked` or `needs_followup` instead of claiming completion.
+
 ## Playtest Issue Schema
 
 Each issue found during human or AI-assisted playtest must include these fields:
@@ -78,6 +102,8 @@ claim_boundary:
   release_ready_claim: "not_claimed"
 ```
 
+Use `experience_claim: "not_claimed"` for a schema-only or artifact-only setup session. Use `experience_claim: "partial"` only when real reviewer notes or artifacts exist for at least one phase. Do not use `playable_claim: "reviewed"` without a specific session record explaining what was reviewed and which relative artifacts support it. `release_ready_claim` remains `not_claimed` in this evidence carrier.
+
 ## Initial Review Record
 
 ```yaml
diff --git a/docs/rpg-pack-recipes.md b/docs/rpg-pack-recipes.md
@@ -2,7 +2,7 @@
 
 These recipes are executable dry-run entrypoints for RPG project assembly. Use them before generating a real project so dependencies, autoloads, project settings, verification entries, and conflicts are visible.
 
-For the minimal productized RPG template path, start with `docs/rpg-template-quickstart.md`; this page keeps the individual pack combination recipes.
+For the minimal productized RPG template path, start with `docs/rpg-template-quickstart.md`; for the current automated Interaction sample and future Experience/playable sample route, see `docs/rpg-playable-sample-recipe.md`. This page keeps the individual pack combination recipes.
 
 ## Minimal RPG Battle Shell
 
@@ -59,3 +59,13 @@ Use when project enemy/NPC AI needs Beehave behavior-tree authoring. The default
 ```
 
 `save-state-lite` conflicts with `save-core`; do not combine it with the default RPG save path unless one side is adapted or namespaced.
+
+## RPG With Dialogue Authoring
+
+```bash
+./scripts/bootstrap_toolbox_project.sh ../godot-toolbox-rpg-preview \
+  --packs=dialogue,data-core,save-core,rules-events-core,rpg-save-adapter,rpg-core \
+  --dry-run-report
+```
+
+Use when a project wants Dialogue Manager resources for dialogue graph/text authoring and runtime line playback. Dialogue state must bridge through `rules-events-core` and `rpg-save-adapter` before becoming project truth.
diff --git a/docs/rpg-template-absorption-plan.md b/docs/rpg-template-absorption-plan.md
@@ -14,6 +14,7 @@ The target is not to turn `godot-toolbox` into one fixed RPG framework. The targ
 | `quest` | [QuestSystem](https://github.com/shomykohai/quest-system) | `2.0.1.4_4` | Resource-based quest system with a clear addon subtree and tests upstream. | Campaign truth, quest event mapping, and quest persistence must bridge through `rules-events-core` and `save-core`. |
 | `ai-behavior` | [Beehave](https://github.com/bitbrain/beehave) | `v2.9.2` | Mature behavior-tree addon for projects needing explicit AI authoring. | Basic turn-based enemy AI should start self-owned; behavior trees are optional once behavior complexity justifies them. |
 | `save-state-lite` | [SaveState Lite](https://github.com/youssof20/savestate) | `v1.2.0` | Useful SaveManager, atomic writer, save browser, and component patterns. | It is an isolated alternative save tooling pack because it defines `SaveSlot`, which conflicts with `save-core`; `save-core` remains the default RPG persistence contract. |
+| `dialogue` | [Dialogue Manager](https://github.com/nathanhoad/godot_dialogue_manager) | `v3.10.4` | Mature dialogue graph/text resource authoring and runtime line playback. | Dialogue state must bridge through `rules-events-core`, `data-core`, and `save-core` before becoming project truth. |
 
 All absorbed packs are non-default. They only enter a generated project through explicit `--packs=...` selection.
 
@@ -26,7 +27,7 @@ All absorbed packs are non-default. They only enter a generated project through
 | `beehave` | <https://github.com/bitbrain/beehave> | `v2.9.2` | `addons/beehave` | `packs/ai-behavior/godot/addons/beehave` | `ai-behavior` | Vendored optional pack, explicit opt-in. |
 | `savestate_lite` | <https://github.com/youssof20/savestate> | `v1.2.0` | `addons/savestate` | `packs/save-state-lite/godot/addons/savestate` | `save-state-lite` | Vendored optional pack, explicit opt-in, conflicts with `save-core`. |
 | `pandora` | <https://github.com/bitbrain/pandora> | Reference only | Not vendored | `packs/data-core` references only | none | Reference for RPG data taxonomy; no runtime dependency. |
-| `dialogue_manager` | <https://github.com/nathanhoad/godot_dialogue_manager> | Reference only | Not vendored | future `packs/dialogue` candidate | none | Deferred dialogue candidate. |
+| `dialogue_manager` | <https://github.com/nathanhoad/godot_dialogue_manager> | `v3.10.4` | `addons/dialogue_manager` | `packs/dialogue/godot/addons/dialogue_manager` | `dialogue` | Vendored optional pack, explicit opt-in. |
 | `dialogic` | <https://github.com/dialogic-godot/dialogic> | Reference only | Not vendored | future dialogue/VN candidate | none | Reference for heavier dialogue/VN workflows. |
 | `gdquest_open_rpg` | <https://github.com/gdquest-demos/godot-open-rpg> | Reference only | Not vendored | design reference only | none | Reference for simple RPG scene/data/combat organization. |
 | `gdquest_save_guide` | <https://www.gdquest.com/library/save_game_godot4/> | Reference only | Not vendored | `save-core` references only | none | Reference for save resource patterns. |
@@ -39,7 +40,7 @@ All absorbed packs are non-default. They only enter a generated project through
 | Direction | Source | Why reference-only |
 | --- | --- | --- |
 | RPG data taxonomy | [Pandora](https://github.com/bitbrain/pandora) | Useful data-management ideas, but too RPG-scoped and not the generic `data-core` truth. |
-| Dialogue | [Dialogue Manager](https://github.com/nathanhoad/godot_dialogue_manager) | Strong candidate, but should remain deferred until the target Godot version and release maturity are acceptable for this template. |
+| Dialogue | [Dialogue Manager](https://github.com/nathanhoad/godot_dialogue_manager) | Absorbed as non-default `dialogue` pack (v3.10.4). Dialogue state must bridge through `rules-events-core`, `data-core`, and `save-core` before becoming project truth. |
 | Dialogue/VN | [Dialogic](https://github.com/dialogic-godot/dialogic) | Powerful but heavier than the current RPG battle template goal; keep as a future dialogue/VN candidate. |
 | Save design | [GDQuest save guide](https://www.gdquest.com/library/save_game_godot4/) and [Godot save docs](https://docs.godotengine.org/en/4.0/tutorials/io/saving_games.html) | Good persistence cautions and patterns, but `save-core` should own the minimal facade. |
 | Flow transitions | [Scene Manager](https://github.com/glass-brick/Scene-Manager) | Good transition reference, but `flow-core` owns game mode/result semantics. |
@@ -122,7 +123,7 @@ Own evidence that the template is actually usable:
 
 The repository can claim `RPG-ready shell` when:
 
-- `inventory`, `quest`, `ai-behavior`, and isolated `save-state-lite` bootstrap as opt-in packs.
+- `inventory`, `quest`, `ai-behavior`, `dialogue`, and isolated `save-state-lite` bootstrap as opt-in packs.
 - `rpg-core` and `rpg-battle-core` have runnable smoke tests.
 - A generated project can run one complete battle, grant rewards, save, reload, and preserve party state.
 
diff --git a/docs/rpg-template-quickstart.md b/docs/rpg-template-quickstart.md
@@ -23,6 +23,14 @@ Optional packs:
 - `quest`: QuestSystem resources. Persist quest progress through `rpg-save-adapter` and `save-core`.
 - `ai-behavior`: Beehave authoring for behavior-tree AI. The default deterministic battle core must still work without it.
 - `save-state-lite`: alternative save tooling/reference only. It is not part of the default RPG save path.
+- `dialogue`: Dialogue Manager authoring/runtime for dialogue graphs, text resources, and line playback. Dialogue state must bridge through `rules-events-core`, `data-core`, and `save-core` adapters.
+
+Art/audio status:
+
+- The minimal RPG recipe supplies first-party RPG state, battle, save, UI smoke, and example gameplay data.
+- It does not vendor a complete RPG art/audio library for characters, monsters, scenes, tilesets, battle backgrounds, fonts, SFX, or BGM.
+- Candidate CC0/open-source art/audio sources are recorded in `docs/rpg-art-asset-sources.md`.
+- RPG example content authoring boundaries are recorded in `docs/rpg-content-authoring.md`; sample content is teaching/fixture data, not balance or release content.
 
 Install order:
 
@@ -86,4 +94,4 @@ Not allowed from this quickstart alone:
 - Human playtest claims.
 - Release claims.
 
-Use `docs/rpg-experience-review.md` if separate human or AI-assisted Experience review evidence is needed.
+Use `docs/rpg-experience-review.md` if separate human or AI-assisted Experience review evidence is needed. Use `docs/rpg-playable-sample-recipe.md` for the route that separates the current automated Interaction sample from the future Experience/playable sample plan.
diff --git a/docs/rpg-vendor-license-notice.md b/docs/rpg-vendor-license-notice.md
