Files

为可重复技能补充参数校验与展示，统一配方、编排器和执行单元术语。

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

2026-07-30 17:59:20 +08:00

14 KiB

Raw Blame History

本地多 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. 总体架构

┌─────────────────────────────────────────────┐
│           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 的具体形态）

执行编排器决定并维护相位边界：

校验 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 契约：声明驱动的输入输出、上下文段、工具边界

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。

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-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（双线黄金路径自动化）

14 KiB Raw Blame History Unescape Escape