# 故事工程与多人物写作流水线

故事工程把跨回合剧情资料保存为玩家可直接编辑的 Markdown，并在被角色会话选中后启用固定顺序的写作流水线。它用于同一篇故事中的多人物认知与分区正文，不创建多个并列的顶层聊天 Agent，也不替代角色卡、世界书或普通会话历史。

## 使用入口

从 Agent RP 侧栏打开「故事工程」，可以新建、编辑或删除工程，并为当前角色会话启用一个工程。选择结果写入 Session；清除选择后，后续回合恢复普通角色流程，工程文件仍保留。保存使用 revision 检查，页面基于旧 revision 提交时会明确拒绝覆盖较新的编辑。

工程默认保存在 `~/.dsh/agent-rp/story-workspaces/<story-id>/`：

```text
manifest.json
outline.md
foreshadowing.md
proposals.md
history.md
characters/<character-id>/persona.md
characters/<character-id>/knowledge.md
sections/<section-id>.md
sources/<source-id>.md
```

`manifest.json` 保存工程名、revision、人物、资料、正文分区和流水线设置。`outline.md` 与 `foreshadowing.md` 始终由玩家编辑；回合后的模型建议只追加到 `proposals.md`，不会静默改写大纲或伏笔。文件写入使用同目录临时文件替换，标识经过校验，不能逃逸工程目录。

## 认知范围

每个阶段只接收完成本职工作所需的资料：

| 阶段 | 可以读取 | 不直接读取 |
|---|---|---|
| 研究 | 公开历史、最近会话、相关本地资料、网络检索结果、当前玩家输入 | 人物私有认知、未来正文草稿 |
| 人物 | 该人物 Persona、该人物 `knowledge.md`、当前玩家输入 | 公开历史、最近完整会话、其他人物资料、大纲、伏笔、原著资料全文 |
| 导演 | 大纲、伏笔、公开历史、研究简报、各人物独立提案、分区定义、当前玩家输入 | 人物私有文件原文 |
| 分区 | 对应分区参考、导演方案、当前玩家输入 | 其他分区草稿与工程文件原文 |
| 编辑 | 按工程顺序排列的分区草稿 | 工程文件原文与人物私有文件 |
| 连续性 | 最终可见正文、当前大纲与伏笔、参与人物标识 | 会话中没有进入最终正文的内部草稿 |

人物只有在工程中启用时才参与当前场景推演与回合后观察沉淀。导演可以综合人物提案安排事件，但提示要求未知情人物不得表现出全知；角色 Worker 本身不会因导演拥有全局资料而获得其他人物的知识。

## 回合顺序

故事工程只在 Agent 模式的第一步准备正文：

1. 本地检索从启用的资料 Markdown 中选出与当前输入和近期会话相关的有界片段；可用时还会调用 DSH Web Provider。网络失败只移除网络结果。
2. 研究 Worker 从公开资料形成事实与连续性简报。
3. 启用的人物 Worker 分别依据自己的私有认知提出行动；同阶段最多并行 `maxParallel` 个请求。
4. 导演 Worker 根据研究、人物提案、大纲和伏笔制定本轮方案。
5. 启用的正文分区分别写作；同阶段并行度同样受 `maxParallel` 限制。
6. 编辑 Worker 删除复读、八股句式和正文外解释，同时保留事实、对白归属、视角、标题、顺序与分区职责。
7. 顶层角色 Agent 收到编辑后的草稿，只能为角色口吻和既有格式做局部适配，再产生玩家可见回复。
8. 原有正文审阅与状态结算完成后，连续性 Worker 读取最终可见正文并沉淀公开历史、人物观察与待审提案。

阶段顺序固定；只有同阶段人物和同阶段分区可以并行。`maxParallel` 默认为 4，可设为 1–8。故事 Worker 默认跟随当前会话模型，也可以为整个故事流水线指定独立 provider 和 model；该设置不改变顶层角色 Agent 的模型。

故事流水线失败时按最近可用结果降级：研究失败时继续使用本地与网络片段，单个人物或分区失败时忽略该项，导演失败时使用输入资料组成的有界后备方案，编辑失败时保留分区草稿。整个准备阶段异常时，顶层角色 Agent 仍按普通角色流程运行。连续性结果无法解析时，只把最终可见正文写入公开历史，不猜测人物观察或大纲、伏笔提案。

## 正文分区

- `prose` 写叙事、环境、行动和对白。
- `character` 聚焦一个指定人物或全部参与人物，但仍只能呈现导演允许公开的内容。
- `history` 向读者展示时间线、前情或档案，只能使用已经公开的事实。

多个启用分区按 manifest 顺序生成，并以各自的二级标题交给编辑 Worker；编辑不得合并或重排。只有一个 `prose` 分区时保留自然正文，不额外插入标题。编辑器删除人物时，引用该人物的分区自动退回“全部参与人物”。

## 回合沉淀与重放

连续性 Worker 使用实际展示给玩家的回复，而不是导演方案或编辑前草稿。公开事件追加到 `history.md`；每个人物只把正文中明确亲历或可感知的事实追加到自己的 `knowledge.md`；大纲与伏笔建议追加到 `proposals.md`。同一回合带有稳定 marker，重试不会重复写入，同时保存会基于最新工程 revision，保留玩家在回合期间完成的其他编辑。

故事阶段的完整模型请求和成功文本或稳定失败分别写入 `agent-rp/story-stage-request` 与 `agent-rp/story-stage-result`；网络检索、最终准备稿和回合沉淀也各自写入 ignorable Session 事件。相同 turn、step、工程及 revision 的准备稿可以从 Session 重放复用，导出、分支与重载不依赖进程内缓存。