重构世界模拟器为模块化配方架构，完善创作编排、会话运行时与 Web UI，并清理过时技能。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/architecture.md

@@ -1,150 +1,301 @@
-# 整体架构
+# 本地多 Agent 文本创作系统架构
 
-## 1. 方向
+## 1. 文档定位
 
-**标签驱动黑板** + **agent tool loop** + **5 相位阶段机** + **skill 能力库**。
+本文档描述**系统级运行内核**：模块边界、创作定义与运行实例如何分离、总管 / Worker / Skill / 上下文如何协作、数据如何持久化，以及外部项目按层借鉴的原则。
 
-```text
-Skill 包（orchestrator manifest + workers/*/SKILL.md）  静态能力定义
-Session + 黑板 tag                                     一次运行的实参
-Book                                                     跨 Session 的项目与资产
-
-Agent（总管）   running 相位内 tool loop，调度 invoke 哪个 skill
-Runtime         拼接上下文、校验 tool、写黑板、驱动阶段机边界
-阶段机          谁可动、何时等用户、产物生命周期——不是流水线剧本
-```
-
-核心文档：
-
-```text
-docs/tag-blackboard.md          黑板、标签、分工
-docs/context-assembly.md        ★ 上下文拼接（上半固定、下半动态）
-docs/tool-contracts.md          总管 / worker tool
-docs/runtime-state-machine.md   5 相位、tool 边界
-docs/book-storage.md            长期存储（过程 / 资产 / 游玩）
-docs/skill-design-guide.md      新 skill 包设计方法
-docs/implementation-guide.md    代码文件职责
-```
+本文档**不**设计具体剧本 Skill 的提示词、步骤或字段。剧本与创作方法见独立文档（如 `design-orchestrator-guide.md`）；Skill 包格式见 `skill-format.md` 系列。
 
 ---
 
-## 2. 术语
+## 2. 产品目标
+
+本地运行的多 Agent 文本生成平台，兼容多种创作模式（角色扮演、长短篇小说、仿写扩写、思想实验、信息隔离模拟、世界观/角色卡/模板创作、动态表与长期状态、存档分支等）。
+
+这些模式共享同一运行内核，区别来自：
+
+- 装载哪些 Skill / 能力包
+- 实例规格（Worker 声明）如何配置
+- 上下文如何按契约编译
+- 对状态读写实施什么权限
+
+不为每一种创作模式各实现一套固定工作流。
+
+---
+
+## 3. 核心架构原则
+
+### 3.1 创作定义与运行实例分离
+
+| 层 | 当前实现对应 | 含义 |
+|----|--------------|------|
+| **创作定义 / 规格** | accept 后的 `设计.worker集`、静态设定 tag；可存为 `instance` / `opening` 快照 | 可复用的「函数声明」：Worker、表、常驻上下文、权限与能力边界 |
+| **运行实例** | Book + Session + 黑板 + `run` 快照 | 一次具体创作/游玩过程：对话、变量、轮次、中间产物 |
+
+同一规格可多次开档；实例应**钉住**某次规格截面。规格更新后，已有实例不自动跟随；需显式加载/迁移到新截面。
+
+语义上：`instance` 快照 ≈ 已发布的规格版本；`run` 快照 ≈ 运行过程存档。正式 `DefinitionVersion` 发布与迁移协议在现有快照之上增量补齐，不另起一套推倒重写。
+
+### 3.2 总管只负责任务调配
+
+总管 Agent（Main Agent）负责：判断目标是否完成、决定下一项任务、选择 Worker、必要时询问用户或结束。
+
+总管**不**负责：直接创作最终正文、临场拼接完整上下文、绕过权限读私有信息、直接改正式状态、同时兼创作与评测、把隐藏推理写入长期状态。
+
+任务所需信息由总管**声明意图**（如 invoke 哪个 worker）；真正发给 Worker 的上下文由 Runtime 的上下文编译器按 Skill / 声明契约生成。
+
+### 3.3 Agent 决策与程序控制分离
+
+| Agent（非确定） | Runtime（确定） |
+|-----------------|-----------------|
+| 下一步做什么 | 权限与声明校验 |
+| 调用哪个能力 | 上下文装载与 Token 裁剪 |
+| 是否返工 / 问用户 | 状态提交、表 `rev` 合并 |
+| | 相位边界、burst、失败处理 |
+
+不能依赖提示词保证权限与信息隔离；访问限制在 Tool 与 Context Compiler 层执行。
+
+### 3.4 动态调度，不用固定创作 DAG
+
+「下一步 invoke 哪个 skill」由 agent tool loop 决定。
+
+**5 相位阶段机**（`idle` / `running` / `waiting_user` / `done` / `error`）是并发与权限模型——谁可动、何时等用户、产物何时算事实——**不是**流水线剧本。详见 `runtime-state-machine.md`、`tool-contracts.md`。
+
+确定性后台流程（导入导出、索引、迁移、批量评测）可用固定步骤；整场 AIRP / 小说创作流程不固化为完整 DAG。
+
+---
+
+## 4. 总体架构
+
+```text
+┌─────────────────────────────────────────────┐
+│           Web / Electron Frontend           │
+│     创作 / 游玩 / 存档 / 检查器 / 调试         │
+└─────────────────────┬───────────────────────┘
+                      │ HTTP（+ 流式事件）
+┌─────────────────────▼───────────────────────┐
+│              Application API                │
+│     Book、Session、快照、资源、模型配置        │
+└─────────────────────┬───────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────┐
+│              Agent Runtime                  │
+│  Main Agent（tool loop）                    │
+│  Phase Machine + Phase Runtime              │
+│  Skill Registry / Worker 声明校验           │
+│  Context Compiler（assembleWorkerContext）  │
+│  Commit：黑板写入、表 rev、acceptance        │
+└─────────────────────┬───────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────┐
+│           Domain / Storage                  │
+│  Book · Session · Blackboard · Snapshots    │
+│  Artifacts · RuntimeEvent history           │
+│  文件资源（books/…）；向量检索可插拔           │
+└─────────────────────────────────────────────┘
+```
+
+合成边界：
+
+> Book/规格描述可以运行什么，Session/快照保存实际发生了什么，相位机决定谁可动，总管决定下一步 invoke 谁，Context Compiler 决定 Worker 看见什么，Runtime 决定哪些修改正式生效。剧本 Skill 是可装载能力，不是系统固定流水线。
+
+---
+
+## 5. 系统核心模块
+
+### 5.1 规格与 Book（Definition 侧）
+
+- Book：长期项目容器（过程、资产、游玩状态）
+- `设计.worker集` accept 后 → 本实例 Worker 声明
+- `instance` / `opening` 快照：规格与可选开局截面
+- 导入导出、复制、从截面新开 play 线
+
+细节：`book-storage.md`、`run-snapshot.md`。
+
+### 5.2 Session 与 Instance Manager（运行侧）
+
+- 按规格创建 / 加载 Session
+- 自动续作 `session.json` 与手动 `run-snapshots/`
+- 消息 swipe / branch checkpoint
+- 从 earlier 快照恢复后重 roll
+
+### 5.3 Main Agent（Supervisor）
+
+接收压缩后的任务视图（目标、相位、可调用能力、最近产物摘要等），经 tool loop 输出调度意图；Runtime 校验后执行。
+
+### 5.4 Phase Runtime（Dynamic Scheduler 的具体形态）
+
+执行总管决定并维护相位边界：
+
+1. 校验 Worker id ∈ 声明
+2. 编译上下文
+3. 短生命周期执行 Worker
+4. 收集写入请求 → 校验 / 合并 / 提交
+5. 按 acceptance 可能进入 `waiting_user`
+6. 预算：`maxBurst`；后续补齐嵌套深度、重复任务检测、Token/调用预算
+
+实现：`src/runtime/phase-machine.ts`、`phase-runtime.ts`。
+
+### 5.5 Worker
+
+按任务实例化的短生命周期调用。保留的是事件、产物与状态修改，不是 Agent 对象。
+
+### 5.6 Skill Registry
+
+架构层两种能力层级：
+
+- **包 / Orchestrator manifest**：能力发现、验收与进 play 门槛
+- **Worker 契约**：声明驱动的输入输出、上下文段、工具边界
+
+注册、加载、版本与磁盘格式见 Skill 系列文档；**具体剧本步骤不在本文**。
+
+### 5.7 Context Compiler
+
+确定性模块：按任务、Worker 权限与实例状态构建 Context View。
+
+当前实现：`inputTags` / `contextSegments` + `assembleWorkerContext()`（`context-assembly.md`）。
+
+演进契约：
+
+- **Context Trace**：记录装载了什么、来源、权限依据、因预算/权限排除了什么
+- 逻辑分区语义（public / narrative / characters / tables / artifacts / runtime）可映射到 tag 与可见范围；实现仍以 tag 黑板为主
+
+### 5.8 Blackboard
+
+带类型与来源的运行状态（tag 条目），不是全体 Agent 共享的大字符串。表字段使用 `value + rev + source`；正式写入经 Runtime。见 `tag-blackboard.md`。
+
+### 5.9 Artifact 与验收
+
+较长或需反复编辑的内容以黑板 tag / 产物记录保存；`drafted → under_review → accepted|rejected|revision_requested`；accepted 前不得当下游事实。
+
+### 5.10 Commit and Validation
+
+Worker 不直接改「当前事实」。路径：输出 → 声明/schema 校验 → 权限与 rev 合并 → 提交事件 → 更新黑板。结构化状态用受控写入；正文类产物仍记录来源与版本。
+
+---
+
+## 6. 数据持久化
+
+当前以**状态快照为主**，会话内保留 `RuntimeEvent` history；完整领域事件溯源（投影 + 事件日志 + 周期快照）按分支/迁移/审计痛点再加深。
+
+| 需求 | 机制 |
+|------|------|
+| 续作 | `session.json` |
+| 规格截面 | `instance` / `opening` 快照 |
+| 游玩存档 / 重 roll | `run` 快照；load = 恢复到该档 |
+| 同开局多线 | 保留 opening/instance 层，清空或分支 run 层 |
+| 调试回放 | `RuntimeSession.history` |
+
+分支不要求复制整库；记录父档 / 基准快照即可。
+
+---
+
+## 7. 信息隔离
+
+隔离由 Runtime 强制：Worker 只看到契约允许的 tag / 段。多角色模拟时，角色 Worker 不得看到他角私有记忆、未公开事件、总管隐藏调度信息。
+
+Context Trace 是排查泄漏的主工具（契约已定，实现渐进）。
+
+---
+
+## 8. 技术栈（现状与边界）
+
+| 层 | 现状 | 边界 |
+|----|------|------|
+| 语言 | TypeScript / Node.js | — |
+| Agent Runtime | 自研（main-agent、phase-runtime、llm） | 领域对象不绑定外部 Agent 框架内部类型；Mastra 等仅可作按层参考或远期适配 |
+| 前端 | `web/` + Electron | 不强制 Next.js / assistant-ui；可借鉴交互模式 |
+| 存储 | 文件系统 Book JSON | SQLite/Drizzle 非近端前提 |
+| Skill | `skills/` + registry | 包内剧本与系统内核分离 |
+
+外部仓库按模块借鉴，见 `references.md`；许可证见仓库根 `THIRD_PARTY_NOTICES.md`。
+
+---
+
+## 9. 术语对照
+
+| 规划用语（抽象） | 本仓库用语（实现） |
+|------------------|-------------------|
+| CreationDefinition / DefinitionVersion | `设计.worker集` 截面；`instance` / `opening` 快照 |
+| RunInstance | Book + Session + 黑板 + `run` 快照 |
+| 导演 Skill / 能力包 | `orchestrator.md` 包（UI 可选；registry 一项） |
+| 剧本层（动态） | 对话谈成的 Worker 集 + play 期 tool loop 调度（非死板选单） |
+| Supervisor | Main Agent（tool loop） |
+| Dynamic Scheduler | Phase Machine + Phase Runtime |
+| Worker Factory | `run_worker` → 声明校验 → executor |
+| Context Compiler | `assembleWorkerContext` / contextSegments |
+| Blackboard | tag 黑板（`BlackboardItem`） |
+| Commit Layer | 写入校验、表 rev 合并、acceptance |
+| Skill Registry | `skills/` loader + orchestrator manifest |
+
+用户可见中文口径（禁止裸露内部 id）见 `ui-glossary.md`。
 
 | 词 | 含义 |
 |----|------|
-| **skill** | `SKILL.md` 定义的能力（设计期能力库中的一条） |
-| **worker** | 某 skill 被 invoke 的一次执行 |
-| **stage** | 业务阶段：`design`（实例化）→ `play`（运行）→ `done` |
-| **phase** | 运行相位：`idle` \| `running` \| `waiting_user` \| `done` \| `error` |
-
-不使用 **step** 指代设计步骤编号，避免与管道混淆。
+| **Worker 声明** | accept 后的 `设计.worker集` |
+| **worker** | 一次 `run_worker` invoke |
+| **stage** | `design` → `play` → `done`（创作 → 游玩 → 已完成） |
+| **phase** | `idle` \| `running` \| `waiting_user` \| `done` \| `error` |
 
 ---
 
-## 3. Agent tool loop
+## 10. 文档地图
 
-```text
-用户硬事件（输入 / 确认 / 验收）
-  → phase = running，toolLoopBurst 计数归零
-  → while running && burst < N:
-        LLM(messages, tools)
-        → 循环 tool（read_blackboard …）→ 结果 append 到 messages
-        → 边界 tool（run_worker / ask_user / finish）→ 退出 burst
-  → 若需用户 → waiting_user
-```
-
-- **burst 上限 N**：两次用户操作之间的最大推理轮数，非 Session 终身额度。  
-- **循环 tool**：不改 phase，只追加 agent 对话。  
-- **边界 tool**：触发阶段机转移（等用户、跑 worker、结束）。
-
-代码：`src/main-agent/tool-loop.ts`、`src/runtime/phase-runtime.ts`。
-
-目标态：worker 执行也用 tool loop（`submit` / `ask_user`），上下文仍由 Runtime 拼接，见 `docs/tool-contracts.md`。
+| 层级 | 文档 |
+|------|------|
+| **系统架构（本文）** | `architecture.md` |
+| 运行内核 | `runtime-state-machine.md`、`tool-contracts.md`、`context-assembly.md`、`tag-blackboard.md` |
+| 持久化 | `book-storage.md`、`run-snapshot.md` |
+| UI | `ui-design.md`、`ui-glossary.md` |
+| 实现顺序 | `implementation-guide.md` |
+| **产品体验路线** | **`px-roadmap.md`**（PX0–PX5 交付与 DoD） |
+| **日常场景 → P0** | **`daily-use-p0.md`**（场景、功能表、P0 工作包） |
+| 外部参考 | `references.md` |
+| **剧本 / 创作方法（非系统架构）** | `design-orchestrator-guide.md`、`creation-playbook.md` |
+| **Skill 包格式（非系统架构）** | `skill-format.md`、`orchestrator-skill-format.md`、`worker-skill-format.md`、`skill-design-guide.md`、`preset-format.md` |
 
 ---
 
-## 4. 阶段机做什么
+## 11. 在现有内核上补齐（路线）
 
-阶段机 **不是** 编排表执行器，而是：
+已具备：相位机、Agent tool loop、Skill loader、design-intake、Worker 声明、上下文拼装、表 rev、Web UI、快照 API。
 
-```text
-1. Actor 门禁     此刻用户 / agent / worker 谁在场
-2. Tool 边界      当前态允许哪些 tool
-3. 事实生命周期   draft → accepted；用户才能 accept
-4. 等待原因       waitingReason 细分等什么
-```
+1. **PX0**：导演选择 UI；AIRP + 长文/爽文主路径；**存档/续作硬稳定**；剧本层保持动态
+2. **PX1–PX2**：创作/游玩体验（可抄 UI）；副作用与多 run 线
+3. **PX3**：Context Trace、调度预算、规格钉版本、E2E
+4. **PX4–PX5**：长文加深；隔离模拟 + 调试（新方法边界可用新导演包）
+5. SQLite / 框架适配仅当痛点单开，不插入 PX0 关键路径
 
-业务「先跑哪个 skill」由 **agent 在 tool loop 里决定**，不由 orchestrator 逐步剧本写死。
+权威表：[`px-roadmap.md`](./px-roadmap.md)。
 
 ---
 
-## 5. 实例化：skill 能力库
+## 12. 主要技术风险
 
-实例化 = agent 在 `design` stage 按需 invoke **instantiate skill**（原「设计步骤」），不是固定 1→14 管道。
-
-```text
-交互范式 skill → 产出 设计.run_skill清单（run 阶段需要哪些 skill）
-每个 run skill 倒推 → 缺什么 instantiate skill → agent invoke
-declare_instance_ready → 进入 play stage
-```
-
-orchestrator.md = **manifest**（有哪些 skill、约束、验收策略），不是逐步思维链。
+| 风险 | 解决边界 |
+|------|----------|
+| 上下文污染 | 全部经 Context Compiler；补 Trace |
+| 自然语言误改状态 | 结构化状态只走受校验写入 / Patch |
+| 调度死循环 | burst、后续嵌套/重复/预算限制 |
+| 规格更新污染旧档 | 实例钉规格截面；显式迁移 |
+| 框架耦合 | 领域与持久化不保存外部 Agent 框架内部对象 |
 
 ---
 
-## 6. 上下文拼接
-
-**上半固定、下半动态**。规则在 skill 定义 + 实例 contextProfile；Runtime 执行。  
-见 `docs/context-assembly.md`。
-
----
-
-## 7. 模块
-
-```text
-phase-machine.ts       纯函数：event → phase（边界规则）
-phase-runtime.ts       Session IO、tool loop 驱动、worker 执行
-main-agent/            tool loop、tool 定义
-worker/executor.ts     assembleWorkerContext、run skill
-blackboard.ts          tag 池
-skills/loader.ts       解析 orchestrator + SKILL.md
-book/                  Book、快照、持久化
-```
-
----
-
-## 8. 数据流（目标态）
-
-```text
-选 orchestrator 包
-  → design：agent burst → invoke instantiate skills → 设计.* tag
-  → declare ready → play
-  → play：用户输入 → agent burst → invoke run skills → 运行.* tag
-  → 过程/资产/游玩 归档 Book（见 book-storage.md）
-```
-
----
-
-## 9. 边界
-
-```text
-Agent        调度 skill；read_blackboard；不传 inputTags；不写黑板（边界 tool 除外）
-Runtime      拼接上下文；校验 tool；写黑板；执行 worker
-Worker LLM   在拼接后的 prompt 内产出；submit 写 declared outputTags
-用户         approve、accept、输入
-阶段机       只响应 event，不调 LLM
-```
-
----
-
-## 10. 实现进度（摘要）
+## 13. 实现进度（摘要）
 
 ```text
 ✅ phase-machine、phase-runtime、skills loader
-✅ 总管 tool loop（read_blackboard、run_worker、…）
-⬜ toolLoopBurst 按用户事件归零
-⬜ assembleWorkerContext（contextSegments）
-⬜ worker tool loop
-⬜ Book：designTrace / CardAsset / PlayBook
-⬜ orchestrator 从编排表迁为 manifest
+✅ design-intake + Worker 声明校验
+✅ 声明驱动 worker 执行 + acceptance
+✅ 表字段格 rev 合并
+✅ Book session / run-snapshots / message branch
+✅ 导演选择 UI（新建作品）；instance/run 存档人话 kind
+✅ 长文模板 outline / chapter-writer；引导覆盖爽文/分段
+✅ 失败/revision/error 出口；黑板用户手改 API
+⬜ Context Trace
+⬜ 规格版本发布与迁移协议
+⬜ 调度嵌套 / 重复任务 / Token 预算补齐
+⬜ 边沿副作用完整调度器
+⬜ 标准 fixture E2E（双线黄金路径自动化）
 ```