14 KiB
本地多 Agent 文本创作系统架构
1. 文档定位
本文档描述系统级运行内核：模块边界、创作定义与运行实例如何分离、总管 / Worker / Skill / 上下文如何协作、数据如何持久化，以及外部项目按层借鉴的原则。
本文档不设计具体剧本 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 总管只负责任务调配
总管 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. 总体架构
┌─────────────────────────────────────────────┐
│ 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 的具体形态）
执行总管决定并维护相位边界：
- 校验 Worker id ∈ 声明
- 编译上下文
- 短生命周期执行 Worker
- 收集写入请求 → 校验 / 合并 / 提交
- 按 acceptance 可能进入
waiting_user - 预算：
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。
| 词 | 含义 |
|---|---|
| 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 |
| Skill 包格式（非系统架构） | skill-format.md、orchestrator-skill-format.md、worker-skill-format.md、skill-design-guide.md、preset-format.md |
11. 在现有内核上补齐（路线）
已具备：相位机、Agent tool loop、Skill loader、design-intake、Worker 声明、上下文拼装、表 rev、Web UI、快照 API。
- PX0：导演选择 UI；AIRP + 长文/爽文主路径；存档/续作硬稳定；剧本层保持动态
- PX1–PX2：创作/游玩体验（可抄 UI）；副作用与多 run 线
- PX3：Context Trace、调度预算、规格钉版本、E2E
- PX4–PX5：长文加深；隔离模拟 + 调试（新方法边界可用新导演包）
- SQLite / 框架适配仅当痛点单开，不插入 PX0 关键路径
权威表：px-roadmap.md。
12. 主要技术风险
| 风险 | 解决边界 |
|---|---|
| 上下文污染 | 全部经 Context Compiler；补 Trace |
| 自然语言误改状态 | 结构化状态只走受校验写入 / Patch |
| 调度死循环 | burst、后续嵌套/重复/预算限制 |
| 规格更新污染旧档 | 实例钉规格截面；显式迁移 |
| 框架耦合 | 领域与持久化不保存外部 Agent 框架内部对象 |
13. 实现进度（摘要）
✅ phase-machine、phase-runtime、skills loader
✅ 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（双线黄金路径自动化）