# 本地多 Agent 文本创作系统架构

## 1. 文档定位

本文档描述**系统级运行内核**：模块边界、创作定义与运行实例如何分离、编排器 / 执行单元 / Skill / 上下文如何协作、数据如何持久化，以及外部项目按层借鉴的原则。

本文档**不**设计具体技能包的提示词、步骤或字段。工作流计划与创作方法见独立文档（如 `design-orchestrator-guide.md`）；Skill 包格式见 `skill-format.md` 系列。

---

## 2. 产品目标

本地运行的多 Agent 文本生成平台，兼容多种创作模式（角色扮演、长短篇小说、仿写扩写、思想实验、信息隔离模拟、世界观/角色卡/模板创作、动态表与长期状态、存档分支等）。

这些模式共享同一运行内核，区别来自：

- 装载哪些 Skill / 技能包
- 实例规格（Worker 声明）如何配置
- 上下文如何按契约编译
- 对状态读写实施什么权限

不为每一种创作模式各实现一套固定工作流。

---

## 3. 核心架构原则

### 3.1 创作定义与运行实例分离

| 层 | 当前实现对应 | 含义 |
|----|--------------|------|
| **创作定义 / 规格** | accept 后的 `设计.worker集`、静态设定 tag；可存为 `instance` / `opening` 快照 | 可复用的「函数声明」：Worker、表、常驻上下文、权限与能力边界 |
| **运行实例** | Book + Session + 黑板 + `run` 快照 | 一次具体创作/游玩过程：对话、变量、轮次、中间产物 |

同一规格可多次开档；实例应**钉住**某次规格截面。规格更新后，已有实例不自动跟随；需显式加载/迁移到新截面。

语义上：`instance` 快照 ≈ 已发布的规格版本；`run` 快照 ≈ 运行过程存档。正式 `DefinitionVersion` 发布与迁移协议在现有快照之上增量补齐，不另起一套推倒重写。

### 3.2 编排器只负责任务调配

编排器（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 决定执行单元看见什么，Runtime 决定哪些修改正式生效。技能包是可装载能力，不是系统固定流水线。

---

## 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` 快照 |
| Recipe / 配方 | `recipes/`（UI 选一层）；黑板 `创作.选用配方` |
| Orchestrator / 编排器 | Main Agent（tool loop）+ `orchestrator.md` manifest |
| Workflow Plan / 工作流计划 | `设计.创作流程`（增量 DAG；非死板选单） |
| Skill / 技能 | `modules/` 工序池 |
| Worker / 执行单元 | 一次 `run_worker` invoke |
| 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`。

| 词 | 含义 |
|----|------|
| **Worker 声明 / 运行规格** | accept 后的 `设计.worker集` |
| **worker / 执行单元** | 一次 `run_worker` invoke |
| **stage** | `design` → `play` → `done`（创作 → 游玩 → 已完成） |
| **phase** | `idle` \| `running` \| `waiting_user` \| `done` \| `error` |

---

## 10. 文档地图

| 层级 | 文档 |
|------|------|
| **系统架构（本文）** | `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`、`world-simulator-modules.md` |
| **Skill 包格式（非系统架构）** | `skill-format.md`、`orchestrator-skill-format.md`、`worker-skill-format.md`、`skill-design-guide.md`、`preset-format.md` |
| **技能撰写交接** | `briefs/capability-authoring-brief.md` |

---

## 11. 在现有内核上补齐（路线）

已具备：相位机、Agent tool loop、Skill loader、design-flow/step（modules/recipes）、Worker 声明、上下文拼装、表 rev、Web UI、快照 API。

1. **PX0**：配方选择 UI；AIRP + 长文/爽文主路径；**存档/续作硬稳定**；工作流计划保持动态
2. **PX1–PX2**：创作/游玩体验（可抄 UI）；副作用与多 run 线
3. **PX3**：Context Trace、调度预算、规格钉版本、E2E
4. **PX4–PX5**：长文加深；隔离模拟 + 调试（新方法边界可用新配方）
5. SQLite / 框架适配仅当痛点单开，不插入 PX0 关键路径

权威表：[`px-roadmap.md`](./px-roadmap.md)。

---

## 12. 主要技术风险

| 风险 | 解决边界 |
|------|----------|
| 上下文污染 | 全部经 Context Compiler；补 Trace |
| 自然语言误改状态 | 结构化状态只走受校验写入 / Patch |
| 调度死循环 | burst、后续嵌套/重复/预算限制 |
| 规格更新污染旧档 | 实例钉规格截面；显式迁移 |
| 框架耦合 | 领域与持久化不保存外部 Agent 框架内部对象 |

---

## 13. 实现进度（摘要）

```text
✅ phase-machine、phase-runtime、skills loader
✅ design-flow / design-step + modules/recipes + Worker 声明校验
✅ 声明驱动 worker 执行 + acceptance
✅ 表字段格 rev 合并
✅ Book session / run-snapshots / message branch
✅ 配方选择 UI（新建作品）；instance/run 存档人话 kind
✅ 长文模板 outline / chapter-writer；引导覆盖爽文/分段
✅ 失败/revision/error 出口；黑板用户手改 API
🟡 Context Trace（有基础 trace UI；编译器装载检查未齐）
⬜ 规格版本发布与迁移协议
⬜ 调度嵌套 / 重复任务 / Token 预算补齐
🟡 边沿副作用（有 table-side-effects；完整可观测 fixture 未齐）
⬜ 标准 fixture E2E（双线黄金路径自动化）
```