# 工具与新人物：业务用途、实际执行与接入缺口

本文件与主导读相应章节同步。教学例子不是生产记录；固定代码版本与接入边界见各章。

## 14. 工具全景：Agent 已在用什么，还能接入什么

玩家说“查一下北塔规定”“让一个新人接剧情并配图”“以后让角色少说两句”，用到的并不是同一组工具。**读这一节，你应该能判断一个需求现在走得通哪几步、结果落到哪里，以及还差哪段接入。**

Harness 是组织这一轮的程序；模型只会看见业务为它提供的菜单。世界书选择、记忆召回等能力则由程序在指定时机安排。还有一些封装虽然已经写好，当前 RP 根本没有注册。**仓库里有，不等于这个用户发一句话就会自动调用。**

主阅读依据本次核对的 Harness `13c481b`；展开项保留原 `77a1537`、世界书固定源及 9 月 17 日候选分支核查证据。这里说“已接线”只表示代码存在调用路径；具体会话是否启用，还取决于业务选的方案和部署配置。

### 先看业务能力：它解决什么，结果交给谁

下面按用途分组。**先看具体需求，再看系统动作和结果。** 每行单独演示一种能力，是否启用由业务选择的方案决定；表里的对话和资料均为教学例子。

**当前这一句：写回复、补资料、配图**

| 用户或产品需要什么 | 系统具体怎样做 | 结果是什么，什么时候用 |
| --- | --- | --- |
| 用户说：“继续北塔门口的对话。”<br>**写回复（Actor）** | 程序把角色设定、保留的历史、本轮输入等交给回复模型；模型写人物对白、动作和环境 | 例如“艾琳望向守卫，等他答复”。**正文直接交付本轮用户**；普通路径直接生成，前台编排可分段写，多段共用本轮输出额度 |
| 用户提到铜钥匙，回复需要遵守它的设定。<br>**选世界书资料** | 在启用世界书的方案里，程序先按本轮话题和规则选出已有条目，把正文放入回复模型输入 | 模型本轮读到“铜钥匙不能替代手令”，再据此写回复。**这批原文没有自动送给并行后台**；后台菜单也没有主动查书工具 |
| 聊天很长，仍要接上“昨天借的钥匙”。<br>**压缩旧对话（Compact）** | 启用后，程序在回复前检查输入容量；必要时把较早对话整理成摘要，保留近期原文 | 本轮模型可读到“钥匙是借来的”及最近对话；程序尝试保存摘要供以后复用。**它发生在回复前，会占准备时间** |
| 用户说：“让守卫举起钥匙，并配图。”<br>**给当前消息配图** | 图文前台先让 Actor 写出这一段，再把段落、外观和参考资料交给绘图流程 | **正文可以先到，图稍后补到同一条消息**。图片任务要关联已保存的助手消息；安排成功还要等实际生成、审核和写回 |
| 产品希望玩家能点选下一句话。<br>**生成回复选项** | 业务另发快捷回复请求，生成几条供玩家选择的话 | 例如“我出示手令”“我先离开”。返回的是可选文本，**不会替用户自动发送或改变剧情事实** |

**后续还要用的资料：剧情笔记、记忆和长期要求**

| 用户或产品需要什么 | 系统具体怎样做 | 结果是什么，什么时候用 |
| --- | --- | --- |
| 用户让陌生使者出场，希望之后身份和关系接得上。<br>**普通 Agentic 后台** | 回复同时，分工模型按需找人物等专家检查；Director 根据旧材料和建议整理完整剧情笔记，程序检查后提交 | 例如留下“使者身份待证实”。**保存成功、被以后请求读到才影响后续回复**；六种检查不必全跑，也不自动建立独立 NPC 卡 |
| 今天仍要记得昨天借钥匙、尚未归还。<br>**日记与记忆表** | 启用的记忆流程在回复前取回旧资料，回复后按各自条件生成经历摘要或更新表格 | 可分别保存“借钥匙的经历”和“归还状态”。**以后取回且放入模型输入，才会被那轮使用**；各份资料不会自动全部同步 |
| 用户这次扮演“外乡学徒”。<br>**用户人设（Persona）** | 程序读取已配置的用户身份资料，由相应模板放入本轮输入 | 模型有依据按“外乡学徒”回应用户。它描述用户的扮演身份，**不等于某件剧情已经发生，也不是自动提取全部用户偏好** |
| 用户说：“以后艾琳说话简短一些。”<br>**长期指令（DIO）** | 有接线的前台提交原始要求和艾琳的角色身份；外部服务随后生成新的角色指令 | **后续请求读到有效新指令后**，才按新要求准备艾琳的回复。当前已经开始的正文继续使用原材料；收到任务回执不等于新指令已生效 |

**另一种玩法与业务接入：需要产品另行选择**

| 产品需要什么 | 系统具体怎样做 | 结果是什么，什么时候用 |
| --- | --- | --- |
| 希望记住世界变化，并推进“取得通行许可”等剧情目标。<br>**剧情推进模块（Story）** | 回复前准备当前场景和可推进目标；Actor 写正文；下一次请求读取上轮实际保存的正文，核对发生了什么 | 例如区分“守卫接了钥匙”与“已经允许进塔”。**世界变化和目标进度供后续准备使用，仍须提交成功才持久保留**。这套模式有计划步骤，替代普通六专家后台；下方直接展开完整过程 |
| 希望整段聊天按连续图文的玩法运行。<br>**Sumi 图文模式** | 产品选用独立 Sumi 流程；每轮把上次保存的外观、场景资料连同聊天交给 Sumi 主模型，再从输出中取出正文、新资料和绘图描述 | 用户收到本条文字与后续图片；按消息保存例如“艾琳穿蓝斗篷、仍在塔门外”的资料，**下一轮主模型据此继续写人物与画面**。这套流程不使用普通六专家后台 |
| 已有业务需要在生成前补材料，或生成后处理正文。<br>**业务前后处理（hooks）** | 开发先接好要调用的外部处理；Harness 到约定时机执行它 | 返回的材料或处理结果交回当前业务。**具体改什么、存什么由接入方实现**，工具名本身不代表已完成记忆或世界更新 |
| 另一产品只想借用“存一份人物资料”或“生成一张图”。<br>**复用工具与 SDK** | 开发把 JSON 读写、图片、专家或外部工具适配接进自己的流程，并提供所需参数 | 工具交回保存回执、图片或建议；**新业务仍要决定谁使用、哪里保存、之后怎么读取**。有封装不代表当前 RP 菜单已经注册；十项工具另有独立试跑入口 |

**Story 这一行，具体怎么跑？**

Story 是项目里可选的**剧情推进模块**，由程序调度模型和工具。它同时维护“世界里已经发生什么”和“剧情目标推进到哪里”。例如，钥匙在谁手里是世界事实，“取得进塔许可”是一个尚待完成的剧情目标。

其中，**模型负责理解用户行动、分析正文，以及在需要时生成剧情目标；程序负责按规则挑本轮目标、组织材料、核对消息和保存结果。**

本例由产品另选 Story 模式。**用户输入：“我把铜钥匙递给守卫，请他开门。”**

1. **回复前准备材料。** 程序读取角色、已有聊天和旧 Story 状态，准备给 Actor 的说明，例如：“仍在塔外，先回应递钥匙；可以争取许可，但不能先认定获准进入。”本轮回复需要等这些材料准备好。
2. **Actor 写出本轮正文。** 例如：“守卫接过钥匙，但没有开门。”用户看到的是这段回复。
3. **先保存待核对记录。** 本轮生成成功后，程序尝试保存准备好的世界与剧情状态，并记下对应回复的消息编号。此时保留的是“等下次读取实际保存的正文再核对”的记录，尚不能把进塔目标算成完成。
4. **下一次请求核对真实结果。** 程序读取上一条实际保存的正文，依照它处理“钥匙已被接收、门仍未开”，再准备新的回复；涉及的剧情事件另按条件判断目标是否完成。该次回复和状态提交成功后，更新才会持久保留。

这里的“核对”是读取业务保存的消息及其关联记录，**不要求用户额外点击接受**。Story 包含明确的剧情计划步骤；当前世界书专用方案不允许与 Story 组合，不能把普通并行后台、世界书和 Story 当作默认每轮连跑的流程。[Story 准备与正文核对](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/story/coordinator.ts#L195-L259) · [待核对记录与版本提交](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/story/coordinator.ts#L390-L418) · [Sumi 读取前轮资料与保存本轮记录](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/sumi/runtime.ts#L129-L192)

完整接口清单和候选实现放在本节展开项。下面三个请求再分别演示世界书、新人物配图和长期风格修改，按各自可用的方案阅读。

### 例一：用户拿铜钥匙请求开门，为什么不是先叫知识专家查书

假设业务选择的是当前世界书专用方案。用户说：“我把铜钥匙递给北塔守卫，请他开门。”

**回复前准备。** 程序取得这段会话绑定的书版本，把这句话、公开场景、近期历史等交给世界书服务。服务选择“持钥匙仍需手令”这类原文，程序放进回复模型输入。这一步得到的是既有设定，不是临时编的新规则。

**本轮回应。** Actor 根据角色、历史、旧状态和这次原文，可能写：“守卫接过钥匙，仍问你要手令。”这段文字直接给玩家。

**后台维护。** 同时开始的普通后台可检查“用户已经递出”“不能仅因请求就记成已经放行”。它读的是独立准备的材料，本轮新正文和那批世界书原文没有自动送进去。人物、知识检查的结果是建议；Director 把值得保留的内容整理成完整新状态，程序检查后尝试保存。

**下一次使用。** 新请求准备时，已保存正文能提供“守卫接住并问手令”；重新选中的世界书能提供办理规则；后台状态保留连续性约束。存好状态不是修改世界书。这个方案未配图片、日记或 Compact，不能因为用户再说“配张图”就描述成所有其他能力自动开启。

### 例二：用户让陌生人出场并配图，三种产物各去哪里

这次假设业务选的是允许前台图文与普通后台的方案。用户说：“一位陌生使者走进北塔岗亭，让他接着说话，并配张图。”已有设定中没有完整人物卡。

**前台先承接。** 控制模型选择 Actor 写一段，如“来客停在门槛外，亮出封蜡信件，等待守卫回应”。不需要先补全童年、性格和所有来历，才能继续剧情。

**图片沿着这段文字走。** 前台安排配图，程序取得这段正文、角色外观和可用视觉资料，生成绘图描述并调用图片服务。结果属于这一条消息的图片位置，可能晚些补回来。后续画面要保持衣着等一致，用的是视觉状态。

**人物分析沿着会话材料走。** 后台可能调用人物或知识检查，提出“用户安排一位陌生使者来到岗亭；具体身份与代表谁尚未证实”等建议。信件是 Actor 在刚才正文里新增的，后台本轮尚未看到，不能在这次分析里把它写成已知物品。Director 是整理连续性状态的模型岗位；它结合旧稿写出完整新稿，程序保存后供之后回复读取。

这三个落点要分清：**正文让剧情继续，图片让本条消息可视化，后台状态帮助以后保持一致。** 一次人物分析并不等于创建了一张能独立编辑、检索、跨会话复用的 NPC 卡。若是 Actor 自己在这次正文中临时创造新人，后台还得等那段正文进入以后历史才看得见；它没有一边盯着新正文一边自动补卡。

### 例三：“以后简洁一点”为什么不是一次记忆表更新

有 DIO 接线时，用户明确说：“以后艾琳说话简短一些，保持这个风格。”艾琳是这段 RP 绑定的主角色，本例修改的是她的角色指令。前台可把用户原始要求、会话和艾琳的角色身份提交给外部长效指令服务。返回“已接收”后当前正文继续；服务处理完成、形成有效新指令后，后续请求才会读取它。

这里改变的是以后给角色的工作说明，不是向通用 JSON 记忆随意写一个字段，也不是修订世界书。普通 Agentic 的 Director 整理剧情状态，DIO 的 Director 编译长期指令，**同样叫 Director，不是一份保存结果。**

如果只是“这句短一点”，不应仅凭名字相近就认为要长期修改；具体选择仍由菜单、调用条件和实际模型决定。服务没完成或失败，也不能对玩家宣称以后已经永久改好。

### 没调用、调用失败、调试成功，各能说明什么

后台可以判断这轮没有值得更新的内容，保留旧状态。某位专家失败也不必然使整次后台停止：后续仍可能依据其他材料整理；但失败分析不能当成成功事实。Director 失败、候选不合法或版本提交冲突，则不能宣称这份新状态存好了。

图片安排成功不等于图片已生成或允许展示；DIO 接收成功不等于长期指令已生效。每种能力应看最终落点，而不是只统计“工具调用了一次”。

想先判断工具能否解决问题，可以走独立调试入口：给人物检查一份角色与对话，看它能否区分事实和猜测；给 JSON 工具一份测试对象，看修改前后差异。目录现有六专家、Director、两个 JSON 记忆工具及一个图片资产工具，共十项。模型和图片会真实请求外部服务；测试记忆及 Director 状态在本次隔离环境里，**测试通过不会直接改玩家会话或发布生产配置**。

### 已开发但还没接通，具体还缺什么

目前能复用“先接剧情、后台维护连续性”的基础；要做独立 NPC 卡，还缺明确的数据结构、人物标识、保存/修改入口及读取位置。要让后台严格依赖本轮世界书，还缺把这些原文按合适范围和预算送入后台的接线；后台菜单也没有主动查书工具。要让聊天自动扩展世界书，还缺把临时剧情事实变成作者设定的发布与版本流程。

候选分支里另有 AOI 图文、图片执行与消息分支状态绑定，9 月 17 日核查时仍未全部进入 main。它们主要解决图片与状态如何落到正确的回复和分支，不能补成“完整人物小卡已经实现”。代码存在、进入 main、当前方案启用、生产验证，要分别判断。

[本轮核源：后台保存链](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/agentic-v2.ts#L879)；[前台四动作](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/actor/roleplay-runtime.ts#L87)；[世界书输入与选择](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/runtime.ts#L47)；[场景组合限制](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/server.ts#L751)；[十项调试目录](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/catalog.ts#L15)。

<details>
<summary>完整调用清单：模型可选菜单、程序固定调用、十项独立调试</summary>

#### 先看使用方式：谁有权调用，决定它怎样参与 RP

| 使用方式 | 具体含义 | 当前例子 |
| --- | --- | --- |
| 模型选用 | 程序先把工具名单提供给某个模型，模型选择名字和参数，程序执行 | 前台选 `actor`、配图、DIO；后台选六位专家与 Director |
| 程序按流程调用 | 场景开启后，业务代码在指定时机执行；模型无需再决定是否调用 | 回复前选世界书、召回记忆、必要的 Compact、Story 准备与结算 |
| 业务另行接入 | 有封装或示例，但当前 RP 没把它注册或装配进这条流程 | 通用 JSON 记忆工具、独立图片资产工具、预选 skill hook、静态 MCP 能力示例；前两项现已另接独立调试入口，见下文 |

所以，**“Agent 的工具菜单”和“系统为这轮 RP 使用的全部能力”是两张不同的清单。** PM 需要后者理解产品能做什么；技术接入时，还要明确其中哪些能由模型自由选择。也没有一个总 Agent 自动看到两个仓库里的所有函数。

| 当前模型菜单 | 菜单中的名字 | 由谁使用 |
| --- | --- | --- |
| 普通 Agentic 后台 | 从 `analyze_plot`、`judge_npc`、`audit_knowledge`、`simulate_world`、`manage_callbacks`、`direct_scene`、`update_director_state` 按 `enabledTools` 生成菜单；执行层没有再完整核对该名单 | 后台协调器；专家内部是专项模型分析，Director 产出候选状态 |
| 前台工具循环 | `actor`、`over`；有对应接线时加入 `generate_image`、`schedule_dio` | 组织本轮文字与图片交付的控制模型 |
| Story、世界书、记忆流程 | 不因此自动出现在上述两份菜单 | 对应业务代码按各自生命周期调用 |

依据：[实际应用装配](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts#L940)、[前台函数定义](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/actor/roleplay-runtime.ts#L87)、[后台注册与执行](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L335)。


#### 独立试跑：十项工具现在怎样调试

**想判断一个工具能不能解决业务问题，可以先给它一份测试材料，单独看结果。** 主线 `13c481b` 新接的 Tool Debug worker 支持这件事：调试客户端明确指定要试哪项工具，不必先建一个完整 RP 场景，也不会为了测试人物判断把整条快慢流程都跑起来。它的十项目录与前面两份在线 RP 模型菜单分开。

| 可以单独试什么 | 输入后会做什么 | 一个业务例子与结果去向 |
| --- | --- | --- |
| 六位专家：`analyze_plot`、`judge_npc`、`audit_knowledge`、`simulate_world`、`manage_callbacks`、`direct_scene` | 使用提供的角色、历史、问题和旧状态，真实调用相应岗位模型，返回建议 | 检查“守卫答应日落前归还钥匙”是否被伏笔工具识别；建议返回调试结果，不自动保存为玩家事实 |
| `update_director_state` | 真实调用 Director，再用生产同源规则校验完整候选；成功才形成测试状态的前后对比 | 看“钥匙待归还”怎样被整理进状态；只改变本次运行的隔离状态，正式 RP 的下一轮不会因此变化 |
| `get_memory`、`update_memory` | 读取输入的 JSON 记忆种子，或按预期版本完整替换它 | 测试把 `preferredName` 改成“阿林”，看 before/after 和版本变化；每次运行新建内存，下一次要继续就显式传入上次 after |
| `generate_image_asset` | 把图片 Prompt、可选参考图/数量/尺寸交给真实 staging 生图后端 | 测试“雨后灯塔”能画成什么，返回任务、图片 URL 和审核证据。**会产生外部请求、可能计费并生成图片资产**；不修改聊天、角色或发送聊天通知 |

例如 PM 想比较两种“承诺跟进”的写法：先选 `manage_callbacks`，准备灯塔与钥匙的测试上下文，分别调整岗位 Prompt 并执行，再比较建议是否保留“尚未归还”。如果接着测试 `update_memory`，要明确给它要保存的 JSON；专家输出不会自行串成一次生产写入。六专家和 Director 会真实调用模型，试跑也可能发生模型费用。

操作顺序是 **看目录 → 准备输入与配置 → 执行并查看结果 → 必要时取消**。依赖缺失时目录仍会告诉你该工具暂时不能运行的原因；看到工具名字，不代表当前环境已经可调用。代码已有这些入口，也不证明调试页面、服务部署或生产接入已验收。

依据：[十项目录与可用条件](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/catalog.ts#L15-L24)、[目录用途与禁用原因](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/catalog.ts#L82-L149)、[隔离记忆与真实图片执行](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/host-tools.ts#L70-L139)、[Director 校验及隔离结果](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L811-L851)。

<details>
<summary>接入细节：四个接口、冻结来源和保存边界</summary>

| 接口 | 实际作用 |
| --- | --- |
| `GET /tools` | 返回十项描述、参数 schema、示例、构建版本，以及 `runnable / disabledReason` |
| `POST /prepare` | 指定 `toolId`，生成输入 `draft`，冻结本次来源配置并返回带签名的 `snapshot / snapshotHash`；此步不调用生成模型 |
| `POST /execute` | 提交 `runId + snapshot + snapshotHash + draft`，核验后执行。允许在规则内修改草稿的参数、上下文、Prompt 和主模型名/参数；结果的 `configHash` 绑定冻结来源与实际执行草稿 |
| `POST /cancel` | 按 `runId` 取消本进程中的运行；已发生的模型费用或外部图片任务不会因此自动撤销 |

冻结的是可核对的配置来源；模型工具执行时从准备阶段保留的 ModelRuntime 映射读取，不按 ID 悄悄换成后来修改的配置。它不冻结模型权重或所有下游服务，不能保证重跑得到相同答案。记忆和 Director 成功结果带 `sandboxState`，其中有 `before / after` 与 `committedToProduction:false`；每次运行的测试状态不会自动延续到下一次或正式会话。图片不是纯内存测试：会产生真实资产，完成也不等于审核允许展示。

worker 供业务后台调用，要求 bearer 并拒绝浏览器直接带 `Origin` 访问；用户权限、运行记录持久化和跨副本取消由调用方接好。当前返回 `saveSupported:false`，worker 没有配置发布接口；“试跑成功”不会直接修改生产 Prompt、绑定场景或上线新版本。第 21 章进一步列出请求和结果字段。

依据：[接口路由与鉴权](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/server.ts#L58-L101)、[准备结果](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L313-L345)、[执行时使用冻结模型](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L647-L662)、[图片外部影响及审核边界](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/docs/tool-debug-worker.md#L63-L74)、[冻结与保存范围](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/docs/tool-debug-worker.md#L86-L98)。

</details>

</details>

<details>
<summary>逐项核对输入、保存位置与生效轮次：交付、资料、记忆、剧情和视觉</summary>

#### 当前交付能力：回复、配图、长期修改

| 业务上要做什么 | 实际工具或能力 / 谁调用 | 输入与产出 | 怎么用，以及什么时候生效 |
| --- | --- | --- | --- |
| 写角色回复 | 普通 Actor 直接生成；开启前台循环后，由控制模型调用 `actor` | 已准备的角色、历史、query、状态等 → 用户可见正文；循环参数 `responseMode=complete/visual_beat` | 例：先让新来的总统在酒馆开口。本轮交付；各段共用整轮正文预算 |
| 给当前情节配图 | 前台 `generate_image`，以及 `visual_beat` 后的自动安排；必须有图片接线 | 前台参数为空，程序使用最新 Actor 段落 → 图片任务；后台取得消息 ID 后生成并写回 | 例：为刚写出的酒馆会面配一张图。文字可先到，图片稍后补进同一条消息 |
| 让后续角色持续改变表现 | 前台 `schedule_dio` → DIO 服务 | 程序取用户原始长期指令、会话与角色身份 → accepted，后台等待编译完成 | 例：“以后艾琳说话更简洁，保持这种风格。”本轮不半途换 Prompt，后续加载有效版本 |
| 结束本轮前台编排 | 前台 `over` | 空参数；须已有 Actor 输出，且满足未完成配图等检查 | 表示这轮前台动作结束；不代表剧情已结算、所有图片已完成或后台状态已保存 |
| 接入既有业务的回复前后处理 | `before_chat`、`before_chat_prompt_source`、`after_chat` hooks；宿主按配置调用 | 前置材料/变量 → 当前上下文；后置处理可返回替换后的正文 | 例：前置补入业务资料，后置按业务规则处理展示文本。外部 hook 的额外行为由对应服务实现，不能从名称推定 |
| 给玩家几个下一步回复选项 | 独立 `auto_reply` 请求 → `generateAgenticAutoReplies` / `generateStoryAutoReplies` | 对应消息与相关状态 → 建议回复选项 | 供玩家下一步选择，不自动替玩家发言，也不更新世界状态；需相应模型配置，Sumi 要走 Chat Service 独立路由 |

这里要分清两个同名的 `generate_image`：前台这个是“为刚写的一段安排图”的空参数动作；后端 MCP 同名接口接收消息和图片位置等参数，执行具体生图与回写。`visual_beat` 是 Actor 参数，不是第五个工具。DIO 修改后续有效 Prompt；普通剧情状态、世界书版本和 JSON 记忆不会因此自动同步改写。

依据：[前台调用条件与执行](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/actor/roleplay-runtime.ts#L447)、[图片任务与消息回写](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/imagine-skill.ts#L321)、[DIO 接收与等待](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/dio-skill.ts#L65)、[图文与 DIO 的装配条件](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts#L949)。

回复前后处理与快捷回复依据：[前置材料](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/integrations/roleplay-axon-adapter.ts#L368)、[后置正文处理](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/actor/roleplay-runtime.ts#L1087-L1109)、[快捷回复生成](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/auto-reply.ts#L54-L123)。


#### 当前资料能力：世界书怎样参与，谁负责维护它

| 业务上要做什么 | 实际接口 / 谁调用 | 输入与产出 | 当前能力和缺口 |
| --- | --- | --- | --- |
| 本轮参考正确的世界设定 | `worldbook.select`；世界书场景由程序在 Actor 前调用 | 已绑定书版本、query、历史、状态与预算 → 入选原文 blocks、选择理由 | 例：问北塔门禁时取出“需要摄政官手令”。本轮加入 Actor；后台 Planner 没自动收到同批原文 |
| 避免聊到一半设定版本悄悄变化 | `worldbook.conversation.pin/get`；会话创建及后续核对 | 会话与书的 revision → 固定绑定 | 当前 Demo 只能绑定配置允许的版本。作者发布新版本不会自动迁移这段对话 |
| 查看当前书里有什么 | `worldbook.book.get/book.entries/index.get`；管理页面的程序调用 | 配置的书与版本 → 元数据、条目与索引状态 | 当前 Demo 开放的是查看；不是让 RP 模型自行挑书、编辑或发布 |
| 导入、建立或修订世界资料 | 世界书服务的导入预览、创建、修订与索引 API；需作者/管理业务调用 | PNG/JSON 或原生条目 → 导入报告、不可变修订；按需显式建索引 | 后端能力已存在，当前 RP 没有“剧情里出现新人物就自动发布世界书”的调用链 |

“常驻/动态”是选条目的策略，不是 Agent 的两种工具。常驻可以免关键词匹配，仍受资格、冲突和预算约束；动态条目按规则或检索取得候选。选书不负责创作缺失人物，更不负责把聊天事实变成作者设定。若要把人物沉淀进世界书，需要另外定义条目生成、发布权限、版本和会话生效方式。第 10–13 节展开这套生命周期。

依据：[本轮选择与注入](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/runtime.ts#L41)、[Demo 读取白名单](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/demo-config.ts#L39)、[会话版本绑定](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/debug-api.ts#L103)、[服务导入与创建](https://github.com/FlowGPT/worldbook-service/blob/3a11e333afd335aeff165e0ccc3654af8e1897d1/src/worldbook/app.py#L178)、[修订和索引入口](https://github.com/FlowGPT/worldbook-service/blob/3a11e333afd335aeff165e0ccc3654af8e1897d1/src/worldbook/app.py#L281)。


#### 当前记忆能力：记住经历、表格事实、用户材料和长历史

| 业务上要做什么 | 当前实现 / 谁调用 | 输入、保存与后续使用 | 一个实际用法 |
| --- | --- | --- | --- |
| 记住较早的共同经历 | Axon Go 日记召回与 `diary-orchestrator`；宿主在回复前后安排 | 回复前召回日记交模板；回复后经轮数、额度、冷却、锁等条件判断是否摘要并存入 Axon | 后续提到“上次救援”，能召回已有日记；不是每轮都写，也不等同六专家的分析 |
| 维护物品或关系表 | Axon Go 表格召回与编辑处理；宿主调用 | 读表和版本；完成回复后解析约定格式的编辑，按版本保存 | 例：将钥匙持有人由莉娅改成用户。正文里提了一句不等于必然形成有效表格编辑 |
| 使用既有 Personalization 记忆 | `personalization` runtime 的外部前后 hooks | 外部服务提供本轮材料、处理完成后的回合 | 已有接入；召回与整理的内部算法在外部服务，不能由 Harness 代码推定 |
| 对照两种记忆后端 | `axon_shadow` runtime | 同时召回 Personalization 和 Go 作对照，实际使用与写入仍走 Personalization | 用于观察差异；不能说已经切到 Go 写入 |
| 使用 Hinos 记忆服务 | `hinos` runtime 的 prepare/提交流程 | 基础上下文渲染后向外部服务准备材料，非空时重渲染；回复后按 claim 提交 | 是另一套记忆接入方式，不能与其他后端默认为同时全开 |
| 让长对话装进模型 | Compact；准备阶段按上下文预算与历史检查点触发 | 较早历史 → 摘要，保留近期原文，保存覆盖范围和检查点 | 例：保留借钥匙约定同时压缩旧闲聊。它会影响本轮材料；不是固定 X 轮的后台专家 |
| 让模型理解用户扮演的身份 | Persona / 角色模板变量；材料准备时提供 | 已配置用户人设 → 模板或专家输入 | 用于理解“用户是谁”；并不自动把用户聊天中新说的偏好抽取成永久档案 |

**召回成功，还要看模板有没有引用材料。** 当前世界书专用场景的 `memorySources=[]`，也没有 Compact；不能把上表所有步骤都画进它每一轮。Agentic state、日记、表格、Compact 和通用 JSON memory 有不同存储与触发规则，目前没有一个自动同步它们的“总记忆工具”。

依据：[Axon Go 与 shadow 读写](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/axon-memory-runtime.ts#L98)、[Personalization hooks](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/personalization-memory-runtime.ts#L36)、[Hinos](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/hinos-memory-runtime.ts#L165)、[日记触发](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/diary-orchestrator.ts#L91)、[Compact](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/compact-runtime.ts#L888)、[世界书场景配置](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/config/scenarios/agentic-v2-worldbook.json#L1)。


#### 当前剧情能力之一：后台分析与连续性状态

普通 Agentic 把当前正文交给 Actor，同时在后台分析轮初材料。六位专家是这里的一组专项 LLM 工具：每位有自己的 Prompt 和模型配置，通常用一次模型请求给出建议，失败可能重试；它们不要求六种不同底层模型，也不各自拥有独立长期记忆。

| 业务问题 | 工具 | 如何用 / 可能产出 |
| --- | --- | --- |
| 用户改变了调查方向 | `analyze_plot` 剧情分析 | 问“拒绝进塔后，如何继续寻找失踪者” → 保留主目标、改用城门登记簿线索的建议 |
| 新人如何融入当前故事 | `judge_npc` 人物分析 | 问“新总统是谁、与谁有关、知道什么” → 身份、位置、关系和待揭示来历的建议；不直接建独立 NPC 卡 |
| 角色有没有突然全知 | `audit_knowledge` 知识检查 | 问“守卫从何知道钥匙位置” → 区分已知、猜测和缺少的知情依据 |
| 场外人物和时间是否该变化 | `simulate_world` 世界进展 | 问“两小时会谈对城门期限有何影响” → 基于既有日程的时间、位置、期限建议 |
| 承诺和伏笔有没有被忘掉 | `manage_callbacks` 连续性跟踪 | 问“明日文书承诺是否已兑现” → 保留待兑现事项，不强行当场触发 |
| 这一幕该怎么表现 | `direct_scene` 场面指导 | 问“让守卫主动回应，保留玩家决定权” → 视角、镜头和主动性建议 |
| 把值得保留的意见整理成状态 | `update_director_state` | Director 读取旧状态、轮初材料和专家结果 → 完整候选状态；程序校验并按版本保存 |

调用每个专家时，模型传 `reason` 和可选 `focus`，程序补入角色卡、开场、轮初状态与记录、近期对话、query 等材料。不是让模型在参数里自己凭空补齐背景。专家结果先给后台协调器与 Director；候选有效、有变化且版本写入成功，后续 Actor 才能读取到新的状态投影。

这组能力已接入普通 Agentic，但不是每轮六个全跑。首轮、新名字有特定补审计规则，其余按需选择；工具执行仍受配置与额度影响。后台看不到 Actor 本轮刚生成的正文，世界书入选原文也不自动传给它。逐个参数和更长例子保留在第 21 节的专家详解里。

依据：[专家职责、输入和结果](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L31)、[按需选择与强制规则](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L671)、[Director 后的保存](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L979)。


#### 当前剧情能力之二：Story 按世界与事件推进

Story 是另一套已实现的业务模式，由宿主按步骤使用世界与叙事工具，替换普通六专家后台分支。它有世界/叙事快照、玩家视角与正文采用过程，因此不能把它简化为六位专家中 `simulate_world` 的另一个名字。

| 业务阶段 | 工具或应用步骤 | 怎么用 / 产出什么 |
| --- | --- | --- |
| 建立开局或重建状态 | `initializeStory`（应用函数） | 角色与开场、可见历史、query → 当前世界/事件、主副线和线索的初始快照 |
| 为本轮准备世界 | `PovPrepareTurnTool` | 世界快照 + 玩家行动 → 本轮可见舞台与机械阶段；例：询问塔内情况不等于玩家已进入塔 |
| 安排待推进剧情 | `NarrativePlanCycleTool` | 需要新计划时，结合故事与快照 → 带前提的目标；例：先证明来客身份，再谈结盟 |
| 给本轮分配情节重点 | `NarrativeDealBeatTool` | 程序确定性选取满足前提的节拍，不调用 LLM；例：本幕先试探来意，不直接庆祝结盟 |
| 依据采用过的正文推进世界 | `PovAdvanceWorldTool` | 已采用正文 + 对应准备快照 → 世界进展、场外结果与信号；不是看到计划就记作已发生 |
| 判断事件结果 | `NarrativeSettleEventTool` | 完整事件正文与用户行动证据 → 达成情况、主副线推进和下一动作 |
| 必要时调整线路 | `NarrativeRebranchTool` | 机制要求重分支时 → 指定主线/副线的新安排与衔接 |

这些工具给出候选快照与结果，Story 协调器负责保存和采用。当前 Emochi Story 会在后续准备阶段核对已保存正文，再结算上一轮；具体接受与重建规则见第 9 节。它不是同一轮随意把未来计划写成事实。

依据：[Story 实际调度](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/story/coordinator.ts#L247)、[World 两类工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/story/world.ts#L114)、[Narrative 四类工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/story/narrative.ts#L48)。


#### 当前视觉能力：画得出来，还要画面保持一致

| 能力 | 谁调用 / 材料怎么走 | 保存什么、解决什么问题 |
| --- | --- | --- |
| `prepare_visual_world` | 选中配图后，宿主通过图片接线准备；读取角色、会话分支与既有视觉状态 | 让图片提示词有外观和场景依据，例如衣着、道具和布局 |
| 图片提示词生成 | 程序调用模型，输入 Actor 片段及视觉资料；此请求关闭自由工具选择 | 生成本次画面的描述，交给图片服务；不是交给六位专家来画 |
| MCP `generate_image` | 后端图片执行路径使用消息 ID、图槽位等信息请求图片服务 | 生图并补到对应消息，完成与前台文字不是同一时刻 |
| `commit_visual_world` | 本轮成功且做过视觉准备后，宿主回合结束 hook 后台调用 | 依据本轮最终输出文本维护视觉连续性，写到已保存 assistant 消息的 narrative 数据；例如后续画面保留被雨淋湿的衣服 |
| Sumi 初始视觉状态 | 宿主让视觉模型读取角色参考图与相关设定，建立初始锚点 | 按材料 fingerprint 保存初始状态供复用；不调用普通 NPC 专家 |
| Sumi 逐轮图文与状态 | 主模型生成 Sumi 协议，宿主解析正文、状态和图片描述 | 保存每条 assistant 对应的前后快照、模型文本、可见正文和图片信息；这不是前台四工具的 function call |
| Sumi 历史恢复 | 启用 history import 时，宿主校验历史与已存快照 | 选取正确分支的起点；不能把不兼容历史随意合并到当前状态 |
| Sumi 图片交付 | 宿主等待正文保存并校验消息锚点，再生成、保存和通知 | 配置 imageGeneration 才走真实生图；参考图占位不能当作已经生成新图。图片交付记录与本轮状态分开维护 |

**图片里的外观状态、Story 世界快照、普通 Agentic 连续性状态是三份不同用途的数据。** “工具都在同一个仓库”不等于“人物换衣服后，三份数据自动同步”。Sumi 的初始化、逐轮状态和存储范围另见第 15 节。

依据：[视觉准备与整轮提交](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/imagine-skill.ts#L199)、[图片 MCP 菜单](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/compat/image-mcp/server.ts#L425)、[Sumi 逐轮运行](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/sumi/runtime.ts#L64)、[Sumi 状态保存](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/sumi/store.ts#L35)。

视觉保存与交付依据：[实际传入的本轮文本](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts#L1225-L1235)、[Visual World 消息存储](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/image/visual-world.ts#L395-L411)、[Sumi 图片交付](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/sumi/images.ts#L27-L148)。

</details>

<details>
<summary>接入储备、原业务例子与产品缺口对照</summary>

#### 可复用工具：换一个业务时怎样接

| 已有封装 | 可以拿来做什么 | 接入时要提供什么 | 当前 RP 的接入事实 |
| --- | --- | --- | --- |
| `get_memory` / `update_memory` | 让自建 Agent 读写一份 JSON 记忆，例如用户偏好或 NPC 草稿 | 授权范围内的 store、版本、完整新对象与业务校验；更新是整对象替换 | Pi 工具工厂和示例已存在；`13c481b` 另有独立隔离调试接线，仍未自动注册进 Emochi 在线菜单，也不替代日记或导演状态 |
| `AxonJsonMemoryStore` | 为新业务把独立 JSON 数据存到 Axon | 用户、会话、namespace、key，再按 get/CAS 读写 | 存储适配器已存在，当前应用未见实例化；它与普通 Agentic state 使用不同的存储范围 |
| `generate_image_asset` | 独立生成头像、道具等图片资产 | prompt、可选参考图/数量/尺寸，以及宿主注入的图片生成接口 | 有独立封装、可选 MCP 暴露；`13c481b` 调试 worker 可真实调用 staging 生图。它不是前台 `generate_image` 的另一种参数，会话归属和展示仍需接入 |
| 六专家的独立调用与 `toPiTool` | 在已有业务里只复用人物/剧情等一种分析 | 模型、岗位 Prompt、授权上下文；自定义材料可用上下文编译接口 | 专家已在普通 Agentic 使用；把它装进另一个 Agent 的 Pi 适配、保存和调度仍须业务明确接入 |
| `ReadMemoryTool` / `WriteMemoryTool` 与 `Tool` hooks | 复用存储读写、执行前后校验与整轮收尾 | 宿主 store 的 get/CAS、授权范围和相应生命周期调用 | 普通 Agentic 内部用存储封装；不是其模型菜单里的额外两个函数，也没有自带数据库。整轮 hook 须由宿主显式调用 |
| `selectPreActorSkill` / `createPreActorDirectorHook` | 先让模型选一个预设，再按预设运行 Actor 与后处理 | skill 列表、Actor 参数、afterActorTools 与 hook 装配 | 仓库有 `actor({skill})` 的预选实现，但当前 dispatch 的 `preActorDirector` 配置实际装配的是前台 function loop；不能据相似名称认定此 hook 已运行 |
| `McpCapability` / `CapabilityExecutor` | 把指定 MCP 能力接进静态执行图 | 服务、操作、输入映射、依赖和结果投影 | `aoi.observe_scene` 是仓内示例；当前 closed-loop 是空执行图/空 capability 列表，不是已经运行中的场景观察或查书工具 |
| SDK Agent、Slow、FastSlow | 为另一项业务自定义模型与工具循环，或复用已有快路 Workflow | 工具/capabilities、模型、状态 store、需要时的提交回调与持久任务封装 | 这是运行框架，不是新增业务工具；不会自动获得 Emochi 的全套能力与配置 |

这里的“可以拿来”表示具备可复用基础，不代表无需开发。比如 JSON store 能放 NPC 对象，但仍缺人物的字段设计、身份与分支范围、生成/修改规则、读入模型的位置；不能把通用存储能力直接当成完整 NPC 产品。

依据：[包的公开入口](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/package.json#L12)、[JSON 记忆](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/memory-tool.ts#L14)、[图片资产](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/image-tool.ts#L18)、[Pi 桥接](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/pi.ts#L9)、[预选 hook 实现](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/pre-actor-director.ts#L39)、[当前实际装配](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts#L940)、[静态能力示例](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/examples/aoi.ts#L6)。

存储与生命周期依据：[读写封装](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/storage.ts#L1)、[Tool 生命周期](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/tool.ts#L10)。

独立 JSON 适配依据：[AxonJsonMemoryStore](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/axon/json-memory.ts#L1)。


#### 连起来怎么用：三个具体业务请求

**场景一：“美国总统出现了，让他承接剧情，并配张图。”** 假设业务选的是允许前台图文循环与普通 Agentic 的场景。前台调用 Actor 写他的出场，依据这一段安排图片，必要时继续写正文；后台同时从 query 发现新人物，可能调用人物、知识或其他专家。图片完成后补到这条消息；Director 成功保存的分析供后续轮次使用。这两种“后台”产出的落点不同。不存在必须先完整生成一张人物卡，才能开始写他出场的固定步骤。

要补出“具体性格和怎样来到这个世界”，NPC 分析可以提供与角色材料相容的方向，但工具没有固定完整小卡 schema，实际 Prompt 也在外部。若角色世界观只在 Actor 本轮收到的世界书里，不能假定后台也知道。若新人物不是用户点名、而是 Actor 本轮临时创造，后台要等后续历史才能看到。**这一用例真正需要验收的是：出场能及时承接、后续人物能保持一致、未确定设定与既定事实有区别。** 只统计“NPC tool 调了没有”不能证明这些目标都达成。

**场景二：“我拿皇室铜钥匙，请守卫开北塔门。”** 在世界书专用场景，程序先选出有关门禁的原文，Actor 再结合“钥匙不能代替手令”等设定回复；后台独立分析请求与旧状态。当前该场景不与前台工具循环、Story 或 Sumi 随意叠加，而且未启用日记/Compact。不能因为请求里有“配图”两字，就描述成它会自动切到场景一的所有工具。

**场景三：“以后艾琳说话更简洁，保持这个设定。”** 在有 DIO 接线的前台场景，模型可调用 `schedule_dio`；当前回复继续生成，后台等待长期 Prompt 编译，后续请求读取生效结果。这不等于同时向 `update_memory` 写了用户偏好，也不等于修订世界书。业务若希望同一个要求同步到多种资料，必须明确哪个是正式来源、哪些要同步、何时生效。

上述都是按已存在的配置组合解释调用，不是一个总 Agent 根据句子自动启用所有模块。场景选择和组合限制由业务入口控制。[场景组合限制](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/server.ts#L718)、[并行后台的轮初输入](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L569)。


#### 从这份清单能做哪些产品判断

下面是基于接线事实作出的业务判断；“还需补什么”是实现该产品目标所需的工作，不是仓库已经保证的能力。

| 你想达到的业务结果 | 当前已经有的基础 | 还不能直接承诺什么 / 需要补哪一环 |
| --- | --- | --- |
| 新角色先出场，后台逐步完善 | Actor 与人物分析并行，Director 可保存连续性状态 | 不能直接承诺独立、可编辑、可检索、可跨会话复用的 NPC 卡；需要定义实体、字段、保存与读取链路 |
| 后台分析严格遵循本轮世界书 | 世界书选择和 Actor 注入已存在 | 后台没自动收到同批原文；需明确哪些世界观材料进入 Planner/专家，及其预算和权限 |
| Planner 缺资料时自己决定查世界书 | 世界书有检索/选择服务，宿主已能按轮调用 | 当前后台菜单没有主动查书函数；若需要“分析到一半再查”，还要注册相应工具、限定书与版本、把返回材料接回分析过程 |
| 从聊天自动扩展世界书 | 有世界书创建/修订接口，有人物与剧情分析 | 没有自动发布链路；需区分临时剧情事实与作者设定，定义发布、冲突、版本及旧会话生效规则 |
| 用户只管提要求，系统自动挑全部工具 | 各场景有自己的菜单与程序调用链 | 目前先选场景、且有互斥组合；跨场景能力组合与路由仍需设计，不能靠名字齐全来保证 |
| 所有长期内容永不矛盾 | 有 Agentic state、Story、记忆、视觉状态和世界书各自的保存机制 | 未自动合成一份总状态；需明确各类事实的保存归属，以及跨模块何时读、何时同步 |
| 使用现成工具就能保证任务完成 | 有执行结果、版本提交、观测及可复用参数校验能力；普通 Agentic 未开启严格参数校验 | 还要分别确认调用成功、数据存好、正确版本被读取、正文实际采用；工具返回成功只覆盖其中一段 |

因此，评估一个新需求时，先沿着“用户希望发生什么 → 当前哪条场景能做 → 哪些步骤已接 → 输入是否够 → 结果放哪 → 什么时候被用到”检查。再决定复用哪个工具或补哪段接线。第 21 节保留接口与专家细节，第 22 节展开人物时序；本节已经给出判断整个 RP 能力范围所需的全貌。

</details>

<details>
<summary>9 月 17 日未合并实现核查：AOI/Pioneer、PR 状态及验证范围</summary>

#### 已经开发、尚未合入 main 的工具：9 月 17 日补查

**有。最明确的一组是 AOI 图文与状态工具链，代码在 Fusion / Pioneer 候选分支中。** 它补的是“正文怎样配图、图怎样落到消息上、状态怎样跟随正确的对话分支”。不是新增加六个咨询专家，也不能把所有未关闭 PR 都算作待上线工具。

本段实时核查以 Harness main `13c481b`、Worldbook main `b0af622` 为参照；候选完整源码固定在 Pioneer `61039e5` 和图文消息格式分支 `44ffcf1`。下方其余能力表保留原 `77a1537 / 3a11e333` 的固定基线。本段补充合并状态与对应实现，不表示整本导读已按新 main 全量重审，也不把合并状态当作部署状态。

#### 真正还在候选分支里的能力，业务上有什么用

| 已开发的工具或能力 | 谁调用，拿什么做什么 | 保存在哪里、影响哪一步 | 一个 PM 能理解的例子 |
| --- | --- | --- | --- |
| **图片准备：`prepare_image_asset` → `prepare_image`**；另有 `parse_image_prompt` 校验绘图块 | 图片执行程序传入图像描述块、视觉状态、角色参考图和画风；复用 AOI 解析器，编译成生图 Prompt、参考图列表、比例和尺寸 | 本身是准备与解析，不把新人物写入世界书；结果交给当前图片任务 | “总统坐在酒馆里”先变成可画的镜头描述。只对应该人物的参考图进入任务，避免拿主角头像画成总统 |
| **视觉状态操作：`initialize_state`、`apply_state_patch`、`render_state`** | Visual World 程序先取得初始化模型或 Producer 的输出，再交 AOI 代码解析、应用变化并渲染状态 | 宿主保存 visual state / 前后状态；用于当前准备和后续视觉连续性，操作函数本身不负责持久化 | 记住谁还在场、衣着和场景发生什么变化。这里的视觉人物记录不等于具有身世、性格、发布版本的完整 NPC 卡 |
| **本轮图片工具：`AoiImageTool`** | 前台的配图动作或 visual beat 后的自动安排进入它；读取刚完成的 Actor 段落、角色卡、视觉状态和资产投影，调用图片 Prompt Producer | 按图片槽位组织准备与生成；回合完成后安排视觉状态收尾。与当前回复配图相关 | 正文先让总统坐下，再为这一幕准备图；启用相应图文生成与交付时，特定 AOI 解析、初始化或状态补丁错误可记录为失败槽位，保住正文及其他图，不要求先丰满人物再开口 |
| **生成、审核和消息回写：`AoiImageExecution` + `EmochiImageAssetTools`** | 程序用准备好的 Prompt 调已有 `createImageAssetTool` 和 Axon `image.generate`，检查图片审核结果，再回写并推送 | 图片尝试记录在 Axon JSON memory；图片结果关联所属消息和槽位。重复请求复用已记录结果，结果不确定时不盲目再次生图 | 第二张图超时后，保留失败/未知状态；重试不能让第一张图重复生成或串到另一条回复。现有通用生图工具已在 main，候选新增的是这套业务执行与交付链 |
| **图文正文解析与独立聊天入口：`parse_narrative` / Narrative API** | 程序把 Actor 的图文输出拆成可见正文、段落与图片 Prompt；入口另外调用历史准备、消息保存、通知及按配置执行的正文计费接口 | 保存并核对消息后交付；独立支持 chat、continue、regenerate、edit-regenerate | 重生成一条回复时，文字、图片和后续补发围绕同一条新消息组织。它是业务入口，不是让 LLM 任意调用消息删除或钱包接口 |
| **后台状态跟随回复分支**（接线能力，不是新模型工具） | 加载状态时核对可见 assistant、正文 hash、用户锚点和 snapshotRef；后台计算后等待正文已保存，再按版本提交与挂接 | Axon 状态快照 + 消息关联；主要影响后续轮读取哪份状态 | 玩家把“总统离开”重生成“总统留下”，后续不应继续拿被替换回复所属的旧状态。这只绑定保存结果，没有给已启动的 Planner 追加本轮新正文 |
| **图片主色提取：`createNodeImageColorTool`** | 图片交付程序把生成且审核通过的图片 URL 交给已有 Node 接口取主色 | 用于图片交付展示；失败用默认颜色，不把已生成图片判为失败 | 图片出现时给客户端提供匹配的背景颜色。它不参与人物判断或剧情推进 |

这些是**一组工具与业务接线**，不是“七个新的慢系统工具”。前台可选菜单仍围绕 `actor`、`generate_image`、`schedule_dio`、`over`；AOI 的解析、状态、存储和通知主要由宿主程序调用。视觉状态能力本来在 main 就有，候选新增的是复用 AOI 实现及把它纳入这条生命周期，不能说 main 原来完全没有世界状态或生图。

依据：[AOI 工具名与调用封装](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/compat/aoi-tools/client.ts#L41)、[六种内部操作及编译](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/compat/aoi-tools/worker.py#L114)、[本轮图片工具](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/aoi-image-tool.ts#L58)、[实际生成与尝试保存](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/aoi-image-execution.ts#L45)、[资产交付](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/image-asset-tools.ts#L23)、[Narrative 入口](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/narrative-api.ts)、[状态绑定](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/planning/runtime.ts)、[主色工具](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/image-color-tool.ts#L11)。

#### 分支和 PR 到底是什么状态

| 对象 | 核查时的状态 | 该怎样理解 |
| --- | --- | --- |
| **PR #147**：AOI state / image 接入 Agentic V2 | **Draft，未合并**；head `28989d9`；目标是 `codex/aoi-fusion-integration`，不是 main | 是功能集成中的实现，不能认为“这个 PR 合完就自动进入 main” |
| **`codex/pioneer-actor-progress`** | head **`61039e5`**，仍与 main 分叉；比旧导读的 `071eb76` 更新 | 已下载完整源码核对上表；当前增加了图片参考图归属等修正，不是又增加一套专家 |
| **`codex/fusion-sumi-message-format`** | head **`44ffcf1`**，仍与 main 分叉；分支表未关联开放 PR | 同一类 Fusion 能力的另一条接法：文字用 `chatStream/chat`，图片按段落锚定，落入 `generate_image_list_v2` 等原生消息字段；私有图片状态放 Axon memory。不能与 Pioneer 当成已串好的一条唯一链路 |

图文格式分支附有 staging 验证记录，但它同时明确：**原生单图重试没有进入 Fusion，端到端验收仍未完成**；chat 与 edit-regenerate 也没有在那次最终原生运行中重新验收。本次只核对记录和代码，没有重跑或确认生产。未合入 main 和曾在独立 staging 验证，可以同时成立。

依据：[PR #147 实时状态与目标分支](https://github.com/FlowGPT/roleplay-harness/pull/147)、[Pioneer 固定提交](https://github.com/FlowGPT/roleplay-harness/commit/61039e588e8c786f5fef07b1d35125016b84a678)、[格式分支固定提交](https://github.com/FlowGPT/roleplay-harness/commit/44ffcf1dd5ef58503709f5da080ce3590c442063)、[格式实现与验收缺口](https://github.com/FlowGPT/roleplay-harness/blob/44ffcf1dd5ef58503709f5da080ce3590c442063/docs/decisions/2026-09-16-fusion-sumi-format.md)、[原生格式消息保存](https://github.com/FlowGPT/roleplay-harness/blob/44ffcf1dd5ef58503709f5da080ce3590c442063/apps/emochi/tools/narrative-tools.ts#L10)。

<details>
<summary>有代码但候选本身也没接用：图片钱包，以及已关闭的旧方案</summary>

候选中保留 `ImageWalletTool.reserve / commit / rollback` 和测试，可调用已有 Node 图片额度/扣费接口。但当前 AOI 图片执行已经移除它的实际调用，只兼容读取旧尝试里的 wallet 状态；应用源码未发现创建该类的生产接线。因此应标为 **“候选中已开发、当前候选执行链未使用”**，不能画成当前每次生图必经的钱包工具。正文的 `wallet.charge` 是另一条流程，不能混为一谈。[钱包实现](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/image-wallet-tool.ts#L21)、[图片执行中的旧记录兼容](https://github.com/FlowGPT/roleplay-harness/blob/61039e588e8c786f5fef07b1d35125016b84a678/apps/emochi/tools/aoi-image-execution.ts#L14)。

旧 [PR #115](https://github.com/FlowGPT/roleplay-harness/pull/115) 的 Pi 专家适配方案有实现，但已 **Closed / unmerged**。关闭说明指出旧根包方案与现行分包结构冲突，需要按新边界重做。当前 main 已有 `toPiTool` 与 `/pi` 导出，所以这是被关闭的旧接法，不能把它当成正在等待合并的新专家能力。[main 现有 Pi 适配](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/packages/tools/src/pi.ts)。

</details>

#### 这些容易被误算，其实已经进入 main

| 容易误读的项目 | 实际结论 |
| --- | --- |
| **PR #78** 仍 Open：Actor planning / Image Agent MCP | `actor`、DIO、Imagine、生图 MCP 等核心能力已通过 **#108** 整合，并在当前 main 找到实际实现。Open 是旧 PR 状态，不代表这整套功能仍缺席 |
| **世界书管理匹配调试、八种插入位置** | Worldbook **#7 / #8 已合并**；Harness 的配套位置接入 **#168 也已合并**。新增位置需要宿主声明能放哪里，以及书的 revision 与模板配合；不自动适用于所有旧会话 |
| **Core Tools 隔离调试、Pi 调用观测** | 已有相应 main 实现；调试/观测帮助接入和排错，不等于给 RP 新增一位会创作人物的专家 |
| **通用 JSON 记忆工具、Story 工具、六位专家** | 已在 main；某条 RP 流程尚未注册或开启，与“开发分支没合并”是两种不同缺口 |
| 另两个开放 PR **#159 / #110** | 分别是 SDK 技术主题文档、移除生产 AutoMemory 场景配置，不能算两件新增工具 |

世界书仓库核查时 **0 个开放 PR、8 条远端分支**；7 条功能分支的关联 PR 均为 Merged。本次没有发现可列为“仍待合并 main”的世界书工具。这个判断不覆盖开发者未推送的本地代码。

依据：[PR #78](https://github.com/FlowGPT/roleplay-harness/pull/78)、[已合并的 #108](https://github.com/FlowGPT/roleplay-harness/pull/108)、[当前 main 前台工具菜单](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/actor/roleplay-runtime.ts#L87)、[世界书 #7](https://github.com/FlowGPT/worldbook-service/pull/7)、[世界书 #8](https://github.com/FlowGPT/worldbook-service/pull/8)、[Harness #168](https://github.com/FlowGPT/roleplay-harness/pull/168)、[文档 #159](https://github.com/FlowGPT/roleplay-harness/pull/159)、[配置清理 #110](https://github.com/FlowGPT/roleplay-harness/pull/110)。

**回到“总统突然出场”的例子：** 这批候选主要能在出场后把镜头画好、把图片和状态存对位置，并让后续读取跟随正确的消息分支。它没有补齐“依据完整世界观自动建立、校验、保存并发布总统 NPC 小卡”的业务闭环。若你要判断还有哪些能力可拿来接入产品，应把这批列为 **已开发的图文/状态集成储备**；NPC 卡仍需要单独定义事实来源、结构、保存位置与后续读取入口。

</details>

## 21. 工具接口：调用参数、返回与专家详解

这一章解释：**检查人物、查已有设定、保存一个偏好、推进剧情、配图或提交长期要求，分别怎样发生，结果交给谁。** 先用人物检查走通模型选工具的完整过程，再用五个具体调用例子看其他能力。工具菜单只是入口；程序何时调用、结果保存在哪、谁再读取，才决定它能改变哪一轮聊天。

主层按 Harness `13c481b` 核对；所有请求与回复文字都是教学例子。完整参数、较早固定基线证据及六位专家长例在对应展开项里，主流程不需要先读那些表。

### 从一句话开始：先确认谁会拿到哪份工具菜单

用户说：“陌生使者来到北塔门口，请继续。”业务选定普通 Agentic 方案后，当前回复交给 Actor；后台协调器的菜单从六种专项检查和一个整理状态入口中，按 `enabledTools` 生成。**这是模型看到的名单，不是执行权限保证：当前注册表仍登记全部七项，执行时没有再完整核对本阶段允许名单。** 未注册的名称会查找失败；完整执行边界见第 24 章。

因此它可以选“人物检查”“知识检查”，不能因为想知道世界设定就凭空调用一个没提供的查书功能。另一种前台图文方案有“写正文、配图、提交长期指令、结束”动作；世界书和记忆则主要由程序在固定时机处理。**每个模型的菜单不同；系统拥有某项能力，不代表所有模型都能随时选它。**

后台也可以认为没有必要调用工具。普通后台会随逻辑生成安排分析，但不等于每轮六位专家全跑。首轮和可见新名字可能触发程序补人物等检查；名字识别是启发式，不保证所有新角色句式都识别。

### 第一步：模型交的不是一句建议，而是一张可执行任务单

协调器可能这样申请：

> 调用功能：人物检查（`judge_npc`）。  
> 为什么调用：用户让此前未记录的使者出场。  
> 重点检查：他现在在哪里、与谁有关系、什么身份已知、哪些来历应保留未知。

“为什么”在接口里叫 `reason`，“重点”叫 `focus`。这些是给检查模型看的任务说明。程序还会收到任务编号、工具准确名称和编码后的参数；它据此查找登记的实现。模型只在普通文字里说“最好检查一下”，不会自动发生同样的工具调用。

需要区分文字约束和程序保证：“不要编造人物身世”是下游模型应遵守的要求，不是程序已建立一条能够识别所有虚构内容的校验。当前普通后台也没有开启严格参数 schema 校验，不能仅因菜单标了必填，就认定每次缺参都会被拦住。

### 第二步：程序补齐资料，专家给出有范围的建议

任务单没有让模型自己填写整张角色卡。Harness 会补入当前角色的原始设定与开场、用户人物资料（如果有）、此前状态和有限长度记录、近期对话、本轮输入，再加这位专家专用的工作说明，才调用它的模型配置。

例如这次材料写着“用户说来了一位陌生使者”，旧状态没有这个人，角色卡设定为旧城与北塔。人物检查可能返回：

> 已知：来客在北塔门口，被用户称为使者。  
> 未知：姓名、代表谁、信件是否真实。  
> 建议：先保持身份待证实，通过问答逐步建立来历；不要直接记成守卫的老朋友。

这个工具没有因此读到世界书全库，也没有自动看到并行 Actor 刚写出的台词。它提供的是**在收到材料范围内的分析**，没有直接创建人物卡或保存正式状态。

六种检查的分工是：剧情看路线与情节，人物看身份和进退场，知识看事实与知情证据，世界进展看已有时间安排与场外变化，伏笔看承诺与未了事项，场面看视角与主动性。它们都是不同工作说明下的模型调用，不要求六家底层模型，也不各自拥有独立长期数据库。

### 第三步：读回执时，要知道这次究竟成功了什么

专家交回的回执可以用人话读成：

> 这项检查完成了（`ok: true`）。  
> 来源是人物检查（`tool: judge_npc`）。  
> 分析文字是上面那三段（`result`）。

还可能有模型用量 `usage`；失败时会有 `ok:false` 和原因 `error`。**成功说明工具返回了结果，不说明分析一定正确，更不说明资料已经保存。** 某位专家失败后，普通后台仍可能把失败说明和其他结果送入后续决定；不是任何一位失败就必然全停。

分析完成且启用状态工具时，协调器读整批结果，决定是否请 Director 整理。第二阶段只开放整理状态入口，不能无限再开新的专家批次；没有专家时也可直接请求整理，不需要先写一份重型执行计划。

### 第四步：结果怎样真正进入以后回复

Director 是“整理剧情状态”的模型岗位。它收到旧状态、这轮材料、专家建议与更新理由，交回一整份待采用的新稿，字段叫 `candidateState`。它可以写“来客身份待证实”，也可以保留有依据的旧关系和后续软建议，不能只丢掉旧稿返回一句检查完成。

程序检查长度、标题和内容变化，再按读到的旧版本尝试保存。例如基于第 12 版写出的稿子，只能在存储仍符合该版本时提交，避免覆盖别人先写好的状态。成功后保存新状态和相应成功分析的分类记录；未来准备一轮时，再将有长度限制的状态与记录文字交给 Actor。

这时 Actor 才有材料继续维持“同一位使者、身份仍待证实”。当前已经开始的正文不因此重写；下一句话来得很快时，也可能仍读到旧版。Director 失败、候选无效、内容未变或版本冲突，分别可能导致没有这次新版本。**工具返回、状态保存、后续模型采用，必须分别看。**

### 按实际用途：查设定、存字段、推进剧情、配图和长期修改

**查北塔规则：宿主先选世界书，Actor 直接使用原文。** 在世界书方案里，程序在 Actor 前调用 `worldbook.select`，带上本会话绑定的书版本、当前输入形成的 `query`、近期 `history`、能从旧状态解析出的 JSON 条件 `state`，以及 `token_budget`。普通后台保存的是分标题文本时，这里的条件 `state` 通常是空对象，不能把它理解为已发送旧状态全文。例如用户问“能借铜钥匙进北塔吗”，查询文字还可补入旧状态里的公开场景描述；条目若被选中并成功放入模板，返回的 `blocks` 原文就供当前 Actor 回答。它不需要后台模型再申请查书，也不经过 Director 保存。没有命中时不能假定模型已知道规则。[查询和固定调用接口](#ch21-host-tools)

**把称呼改成阿林：先读 JSON，再完整替换。** 接入方先为工具绑定用户或会话存储，再由它安排的调用方执行 `get_memory({})`。假设读到 `{revision:12,memory:{preferredName:"小林",keyReturned:false}}`，要保留钥匙状态，就提交 `update_memory({expectedRevision:12,memory:{preferredName:"阿林",keyReturned:false}})`；成功返回 `{revision:13}`。漏掉 `keyReturned` 会删除它，版本冲突要先重读。后续模型能否叫“阿林”，仍取决于业务有没有再次读取并注入这份 JSON。普通 Emochi 菜单未接这两项；独立调试只改本次隔离副本。[存储契约与接入范围](#ch21-host-tools)

**递钥匙后剧情怎样推进：Story 宿主按步骤调用。** 在 Story 方案里，`PovPrepareTurnTool` 接收世界快照、设定材料和 `action:{type:"free",text:"我递出钥匙，请开门"}`，返回准备后的快照与可见舞台。没有待结算事件阻挡时，宿主再把叙事快照和当前阶段交给 `NarrativeDealBeatTool`，取得情节方向 `packet`，与舞台一起送给当前 Actor。正文生成后先保存等待采用的状态；后续请求确认已保存正文及分支，再把对应准备结果和 `writer:{prose:已采用正文}` 交给 `PovAdvanceWorldTool` 结算，宿主负责最终保存。工具返回候选并不代表已持久化；结算仍为 `pending` 时，本次准备会报错终止，之前已保存的待处理记录留给以后重试，不能宣布世界已推进，也不能继续当作本次已准备好。[六个步骤的完整接口](#ch21-host-tools)

**给守卫接钥匙的这一幕配图：前台动作与独立资产是两种用法。** 已接生图的前台可以先调用 `actor({responseMode:"complete"})` 写出片段，再调空参数的 `generate_image({})`；程序补入该片段和消息归属，返回 `{ok:true,scheduled:true,imageIndex:0}` 这样的调度回执，图片生成及相应交付成功后，结果才补回所属消息；`scheduled` 不是图片已生成。若选 `visual_beat` 并形成可用完整片段，且循环仍有下一步可执行，程序会自动安排配图，不需要模型再为同一段重复调用；恰好用尽步数时不能保证这次自动调度发生。另一个需求“单独制作人物头像”可由接入方调用 `generate_image_asset({prompt:"蓝斗篷守卫的头像",count:1})`，获得任务、URL 与审核证据；宿主决定资产展示和归属，仍须按审核结果筛选，不能把返回 URL 当作已准许展示。[前台动作](#ch21-front-tools) · [图片资产接口](#ch21-host-tools)

**以后都说得简洁：前台提交原始长期要求给 DIO。** 用户明确说“以后让艾琳说话更简洁，保留这个风格”且 DIO 已接线时，前台模型可选 `schedule_dio({})`；参数为空，程序补入原始用户要求、用户、RP 会话、目标角色指令 ID 与语言。回执含 `accepted:true` 和 `appliesFrom:"next_turn"`，表示已接受任务；外部服务编译成功，后续请求读到有效版本并装入角色模板时才会生效，不保证紧接着的一轮已经读到。本轮 Actor 继续使用已准备的指令。[前台及 DIO 接口](#ch21-front-tools)

这些例子使用各自的接线，不是一轮必跑五项。建议文字交给继续判断的模型，世界书原文和 Story 舞台交给 Actor，图片资产交给展示流程，写入回执由程序确认。接入工具时，需要把结果的接收方一并接好。

### 想单独验证一个工具，就用隔离试跑

现有调试 worker 可以明确选一项执行：六位专家、Director、JSON 读取/替换、独立图片资产，共十项。先看目录与可用原因，准备本次材料和配置，再执行、查看结果与步骤；需要时取消。

例如给人物检查两种角色设定，比较它是否都保留“使者身份未证实”；再给 Director 测试完整状态如何变化。Director 和 JSON 记忆的 before/after 只在本次隔离运行里，下一次要继续必须显式带上结果，正式聊天不会随之修改。模型和图片会真实请求外部服务，图片会产生实际资产；取消不能撤销已发生的费用或外部任务。

目录可见不等于当前环境依赖已齐。试跑成功也不等于保存生产 Prompt：worker 没有配置发布接口。真正接入仍需业务把权限、调用时机、正式保存和下一轮读取接好。

[专家任务参数与共享材料](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/packages/tools/src/modules/memory/advisory.ts#L63)；[第二阶段与保存](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/agentic-v2.ts#L879)；[JSON 替换契约](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/packages/tools/src/memory-tool.ts#L14)；[调试目录](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/catalog.ts#L15)。

<details id="ch21-debug-tools">
<summary>核对在线菜单与十项调试的参数、返回和保存范围</summary>

#### 先确定这一轮的工具菜单

| 运行路径 | 谁控制 | 实际可用的工具/机制 | 用户等待的是什么 |
| --- | --- | --- | --- |
| 普通 Agentic RP | 场景开启 `agenticV2`，后台 Orchestrator 选专家 | 六个咨询专家 + `update_director_state`；菜单按 `enabledTools` 生成，执行层未再完整核对允许名单 | 当前 Actor 正文。后台分析在 Actor 启动时并行调度，不等分析完成再回复 |
| 前台简单编排 | 开启前台 function loop 的控制模型 | `actor`、`over`；有生图/DIO接线才额外提供 `generate_image`、`schedule_dio` | 控制模型选动作、Actor 生成片段；图片与 DIO 的完成在后台 |
| Story RP | `storyV1` 的宿主协调器 | 初始化 + 六个 World/Narrative 类 | 必要准备完成后才开始 Actor；采用过的正文在后续准备阶段结算 |
| 世界书 RP | 宿主在 Actor 前固定选条目 | `worldbook.select` RPC，不是后台 Orchestrator 的函数工具 | 选条目完成、注入后，Actor 才能回复 |
| 通用 SDK / Pi | 接入业务自己传入 tools/capabilities | 没有自动配齐的 RP 全家桶；可挑选任意已封装能力 | 完全由接入业务安排同步、后台或 Workflow |

Story 分支虽然也要求 Actor 的 Agentic 配置，但 dispatch 使用 `if storyV1 … else if agenticV2`，因此不会再同时启动普通六专家后台。当前 closed-loop 构建的是 `CapabilityExecutor([])`；旧式执行图能力不是已经默认塞进这条 RP 链路。

依据：[实际分支与注册](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts#L1135)、[普通后台启动点](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L569)。


#### 独立工具调试：十项能力怎样准备、执行与看结果

这是调用方明确选一项工具的测试入口。比如先单独检查“日落前归还钥匙”的承诺是否被识别，再单独测试一个 JSON 记忆更新。它不启动普通 RP 的 Planner/Actor 链，也不会自动把测试结果变成下一轮角色事实。

| 工具目录 | 执行类型与输入 | 返回与保存范围 |
| --- | --- | --- |
| `analyze_plot`、`judge_npc`、`audit_knowledge`、`simulate_world`、`manage_callbacks`、`direct_scene` | `model`；`arguments` 为 `reason` 和可选 `focus`，另给上下文、岗位 Prompt、模型及参数 | 真实模型的咨询结果及可用 usage；不写生产状态 |
| `update_director_state` | `model`；使用 `director` Prompt slot、输入状态与本次材料，复用生产同源生成和最终校验 | 合法候选才应用于本次隔离 state，返回前后状态与增加后的 revision；不调用生产 CAS |
| `get_memory` | `sandbox`；`arguments={}`，`context.memory={revision,memory}` 提供隔离种子 | 读取这次输入的副本；不去查玩家真实记忆 |
| `update_memory` | `sandbox`；`arguments={expectedRevision,memory}`，其中 `memory` 是完整替换对象 | 对本次内存副本做真实 CAS 校验；版本冲突失败。每次执行新建内存，跨运行延续需显式传入上次 after |
| `generate_image_asset` | `image`；`arguments` 为 `prompt`，可选 `reference_images/count/width/height` | 真实 staging Axon `image.generate`，返回任务、URL 和审核证据；可能计费、生成 CDN 资产，但不写聊天/角色、不发通知 |

例如读取 `{revision:1,memory:{preferredName:"小林"}}`，再测试替换为 `{preferredName:"阿林"}`：成功的 `update_memory` 可返回 revision 2 的 after。这里测试的是工具的版本与替换行为，**正式用户称呼不会因此改变**。真正接入 RP 还要绑定生产 store、授权范围和把记忆送入上下文的读取入口。

依据：[完整目录](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/catalog.ts#L15-L24)、[隔离 store 与 CAS](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/host-tools.ts#L23-L59)、[工具执行及 before/after](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/host-tools.ts#L70-L139)、[Director 最终校验](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L811-L851)。

<details>
<summary>技术接入：HTTP 顺序、配置快照与返回字段</summary>

| 顺序 / 接口 | 请求与返回 | 需要读懂的边界 |
| --- | --- | --- |
| 1. `GET /tools` | 返回 `{tools,businesses,build}`；每项含 `id/name/inputSchema/examples/executionKind/runnable/disabledReason` | 十项有入口，不代表本环境依赖齐全；不可执行项仍返回明确原因 |
| 2. `POST /prepare` | `{toolId,exampleId?,modelName?,modelConfigId?,preview?,previewDraft?}` → `draft`、签名 `snapshot`、`snapshotHash`、`configHash`、来源和模型选项 | 不调用生成模型；模型工具冻结主/恢复 ModelRuntime、原 Prompt 模板、语言、构建与允许模型；记忆/图片用 host snapshot，无须伪造聊天 ModelConfig |
| 3. `POST /execute` | `{runId,snapshot,snapshotHash,draft}` → `status/output/steps/modelAttempts/durationMs/build`、实际草稿及 hash 等 | 核验签名和构建；在规则内允许改草稿的参数、上下文、Prompt、主模型名/参数。执行用冻结模型映射，`configHash` 绑定冻结来源和实际草稿 |
| 4. `POST /cancel` | `{runId}` → `{runId,cancelled}` | 只找到并取消本进程的活动运行；执行结果另报 `cancelled/timed_out`。跨副本由 BFF 取消等待中的 execute 连接，不承诺外部任务或费用回滚 |

`draft` 统一保留 `{arguments,context,prompt,modelName,parameters}`。记忆和图片的 `prompt/modelName` 固定为空串，`parameters={}`；图片真实 Prompt 在 `arguments.prompt`。模型的语言/native 选择属于准备时冻结内容，改变它需要重新 prepare。模型权重、宏服务和图片配置引用背后的下游版本并未完全冻结，不应承诺严格复现相同输出。

执行结果要分两层看：外层 `status` 是 `completed/failed/cancelled/timed_out`；内层 `output` 有 `{ok,tool,result?,error?,usage?,details?,sandboxState?}`。`steps` 和 `modelAttempts` 可用于查看真实调用和耗时，作为这次 `tool_debug` 运行结果返回；没有自动导出到 Langfuse。响应内容可能有明确的截断标记，实际执行草稿不会为了展示而被静默截断。

成功记忆/Director 的隔离结果会包含以下结构。下例只展开 `sandboxState`，是接口示意，不是一次真实执行记录；Director 的 before/after 则是它自己的状态对象：

```json
{
  "isolated": true,
  "before": {"revision": 1, "memory": {"preferredName": "小林"}},
  "after": {"revision": 2, "memory": {"preferredName": "阿林"}},
  "committedToProduction": false
}
```

Director 候选最终校验失败时返回 `ok:false`，不会产生一次成功隔离状态更新。六位专家和图片不因目录统一就获得这份 before/after。图片的 `details.jobs` 带原任务和审核信息；**工具执行完成不代表图片审核已通过**。当前文档要求总审核和单图审核均完成、单图为 SFW 且 `blocked=false` 才展示对应 URL。断连或取消前可能已经产生模型费用/图片任务，不自动重提不确定的请求。

所有接口都要求 bearer，worker 拒绝带浏览器 `Origin` 的请求；面向用户的 BFF 负责用户授权、run 所有权、持久记录和去重。worker 的 run ID 去重是进程内的，不是跨重启持久队列。当前 `saveSupported:false`：worker 没有配置写入/发布接口；调用方若另外支持保存 staging 预览，也与修改生产配置、绑定场景和迁移流量分开。

依据：[路由/鉴权/取消请求](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/server.ts#L58-L101)、[请求及输出类型](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/contracts.ts#L107-L134)、[准备的签名快照和草稿](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L313-L345)、[执行校验与进程内去重](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L438-L508)、[冻结模型读取](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/tool-debug/worker.ts#L647-L662)、[图片审核与外部影响](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/docs/tool-debug-worker.md#L63-L74)、[观测/取消/保存协议](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/docs/tool-debug-worker.md#L80-L98)。

</details>

</details>

<details id="ch21-front-tools">
<summary>普通后台与前台接口：六专家、Director、正文/配图/长期指令</summary>

#### 普通慢通道：六位专家分别管什么

Orchestrator 发给每个专家的函数参数是 `reason`（为什么调用）和可选 `focus`（重点查什么）。角色卡、开场、用户设定、轮初状态、最近九条有效对话、当前 query 由宿主另外组装；这些材料不是模型在工具参数里自己补齐的。每个专家内部再调用一个配置好的模型，返回文字建议及 usage，**六个都不直接写正式状态**。

| 工具名 | 专门解决的问题 / 输入重点 | 结果和业务例子 |
| --- | --- | --- |
| `analyze_plot` | 当前事件、主线、分支是否需要调整；看用户最新选择与已有故事方向 | 剧情建议。“用户拒绝进塔，保留找失踪者目标，把下一步改成查城门登记簿”，不是直接宣告用户已经去查 |
| `judge_npc` | 人物身份、人数、动机、知情范围、位置、进入场景的条件、进出场连续性 | NPC 建议。“新来的‘美国总统’是一名外来者，目前只知道用户公开告诉他的事；来历尚未交代，不能当成早有宫廷关系” |
| `audit_knowledge` | 哪些是事实、猜测、谎言、秘密；各角色如何获得信息 | 知识边界建议。“总统听见了钟声，但没看见密室里的钥匙；下一轮不能准确指出藏钥匙的人” |
| `simulate_world` | 时间流逝、日程、位置、期限和不在镜头内的角色生活 | 世界进展建议。“会谈持续很久，城门关闭时间将近；远处卫兵可按已知日程换岗”，不是无限创造场外事实 |
| `manage_callbacks` | 承诺、伏笔、物品、伤势、欠账与延迟后果 | 待回收事项。“总统答应次日带通行文书，这个承诺待兑现；现在不能把文书记成已取得” |
| `direct_scene` | 镜头、视角占比、角色主动性；不代替用户决定行为 | 场面建议和 0–4 主动性预算。“守卫可主动追问身份，但不替用户回答，也不擅自写用户跟着走” |

普通轮次由 Orchestrator 判断需要哪些专家，不是每轮六位全跑。第一逻辑轮会在已启用的情况下强制 `judge_npc`、`direct_scene`；最近四条可见历史与当前 query 的正则识别人名若未出现在轮初 state，也会强制 `judge_npc`。这是启发式检测，不是对所有自然语言新增人物的完备识别。首轮/新人物这种强制审核会在 state 工具启用时强制要求 Director 更新。

#### 建议怎样变成下一轮能用的内容

| 工具/步骤 | 输入 → 输出 | 谁保存 / 什么时候生效 |
| --- | --- | --- |
| `update_director_state` | 轮初 state + 本轮材料 + 专家结果 + 更新 reason → 一份完整候选 state | Director 仅生成候选；Planner 校验长度/结构并通过 state runtime 的版本检查提交到 Axon。成功保存后的后续轮次读取 |
| `ReadMemoryTool` / `WriteMemoryTool` | 宿主 store 的读取/CAS | 这是内部存储封装，不在上述 Orchestrator 的七项模型菜单里。数据库、会话隔离及原子写入由宿主存储提供 |

专家建议可以追加进连续性 ledger；Actor 后续读取的是有长度限制的 state/ledger 投影，不是把全部历史专家回复原封不动塞回 Prompt。若 Director 失败、校验不通过或提交发生版本冲突，不能宣称新设定已保存。

依据：[六个工具定义和共享输入](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L18)、[首轮/新人规则](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L640)、[Director 生成及注册](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L397)、[后续汇总和提交](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L879)。

人物例子请接着看第 22 章：它区分“用户已经点名”与“Actor 本轮才创造”的时序，也给出一次 NPC 调用及可能的分析结果。


#### 前台编排：模型看到四个动作

| 工具 | 输入和触发 | 输出、保存与例子 |
| --- | --- | --- |
| `actor` | `responseMode` 可为 `complete` 或 `visual_beat`，省略时为 `complete`；前台控制模型调用 | 生成当前用户可见正文片段，总输出额度由这一轮共享。有生图接线、`visual_beat` 形成可用完整片段且循环还有下一步时，由程序自动安排图片；`complete` 片段可再由模型选 `generate_image`。例：写出走进会客厅的一幕再配图 |
| `generate_image` | 空参数，使用最近一段 Actor 正文；只有生图接线存在才列进菜单 | 立即返回已调度，后台实际生图并写回已保存的消息。例：为会客厅会面场景配图；不能在 Actor 前调用，也不能重复给同一片段配图 |
| `schedule_dio` | 空参数，宿主取原始用户指令；仅用户明确要求持续修改角色/世界/风格/行为时调用 | 返回 accepted；后台 DIO 编译替换 Prompt，成功后供后续轮次使用。例：“之后总统说话请更克制”，本轮仍继续 Actor；收到任务不代表已改好 |
| `over` | 空参数；至少已有一段 Actor 输出，且没有待完成的 visual beat 图片 | 结束本轮前台编排，不是角色退出、剧情结算或保存世界状态 |

`visual_beat` 是 Actor 参数。主线 dispatch 的 `preActorDirector` 配置实际装配上表这套前台 function loop。仓库另有 `selectPreActorSkill` / `createPreActorDirectorHook`，向模型提供 `actor({skill})` 预选接口，但当前入口未使用该 hook，引用来自实现与测试。它应归到可复用能力，不能写成已经运行的第二条前台路径。`skill` 是参数值，`afterActorTools` 是配置字段，两者都不是新的模型工具。

依据：[四个函数定义](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/actor/roleplay-runtime.ts#L87)、[执行限制](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/actor/roleplay-runtime.ts#L447)、[DIO 任务协议](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/dio-skill.ts#L65)、[预选 skill 的 Actor schema](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/pre-actor-director.ts#L39)。

</details>

<details id="ch21-host-tools">
<summary>Story、图片资产、可复用封装及程序固定调用的完整接口</summary>

#### Story：是宿主安排的世界/叙事步骤

这里的名称是执行日志名，后面对应工具类。这六步不是普通后台七工具菜单的扩容。工具返回候选快照、诊断和用量；Story 宿主负责保存整个 Story envelope、采用正文、版本冲突和恢复。

| 日志名 / 实现 | 何时输入什么 | 产出 / 例子 |
| --- | --- | --- |
| `initialize` / `initializeStory` | 无可用状态或需要重建时；角色卡、开场、最近可见历史、query | 初始化当前事件、已知场外事件、潜在线索、主副线。它是应用函数，不是工具包第七个 Story 类。例：建立“学院门口迎接求助者”，不把未来阴谋写成既成事实 |
| `pov_prepare_turn` / `PovPrepareTurnTool` | Actor 前；世界快照和玩家当前行动 | 识别 normal/cue/signal，必要时判断同伴跟随；机制控制时钟、阶段和可见舞台。例：用户只问塔内情况，不应被推断为已走进塔 |
| `narrative_plan_cycle` / `NarrativePlanCycleTool` | `needPlan` 时；叙事快照、世界/故事材料 | 生成有依赖的待推进事项，保留未清偿事项。例：先建立总统的可信证据，再安排盟友支持的回报 |
| `narrative_deal_beat` / `NarrativeDealBeatTool` | 本轮准备；叙事快照和当前事件阶段 | 确定性选择符合前提的情节目标、情绪及主副线方向；本步骤不调用 LLM。例：当前仍是试探会谈，给“追问来意”而不是直接庆祝结盟 |
| `pov_advance_world` / `PovAdvanceWorldTool` | 已采用的完整 Writer 正文 + 对应 prepared 快照 | 结算世界推进、场外结果与可见信号；模型只能补内容，不能随意改机械时钟。例：正文确实送达邀请后，才记录玩家已收到信号 |
| `narrative_settle_event` / `NarrativeSettleEventTool` | 一个事件结束/被打断；完整事件正文和用户行动证据 | 判断目标达成、主副线推进、情绪变化，返回下一步动作；证据不明保留。例：只是提议结盟，不能按已经结盟发奖励 |
| `narrative_rebranch` / `NarrativeRebranchTool` | 机制返回重分支动作时；main/sub scope、设定、主线所需 direction | 调整指定线并给衔接；例：玩家持续明确转向寻找回家通道，调整主线，而非一次闲聊就擅自换目标 |

当前 Emochi Story 会在后续请求准备阶段核对上一轮已保存正文再结算；不等于“本轮流式输出结束就全部变成世界事实”。改写/缺失的历史会影响采用与重建。

依据：[Story 协调器调用顺序](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/story/coordinator.ts#L247)、[World 工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/story/world.ts#L114)、[Narrative 工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/story/narrative.ts#L48)、[初始化](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/story/initializer.ts#L22)。


#### 图文服务：前台的“配张图”背后还有什么

| 能力 | 已有调用位置 | 输入 → 输出 / 保存与例子 |
| --- | --- | --- |
| `prepare_visual_world` | Imagine 路径通过 MCP 或直接 VisualWorld runtime 调用；选中图片后才准备 | 会话/分支、角色外观、参考图等 → 读取或初始化视觉状态，交图片提示词使用。例：固定总统衣着和会客厅布局 |
| 图片提示词模型 | 宿主调用，不是让普通六专家来画图 | Actor 片段 + 视觉材料 → 图片描述；`toolChoice:none`，不再自由发工具调用 |
| MCP `generate_image` | 兼容图片服务；与前台同名但参数完全不同 | 已保存的 messageId、imageIndex 等 → 外部 Image Agent 生成并回写消息、通知前端；前台那层只是调度入口 |
| `commit_visual_world` | 完整回合成功且本轮做过视觉准备，宿主 whole-turn hook 后台调用 | 轮前视觉状态 + 本轮最终输出文本 → 持久化视觉变化；不负责生成图片。例：衣服被雨淋湿，后续图保留这一变化 |
| `generate_image_asset` | 已封装为 `/image` Pi 工具，并可选暴露到图片 MCP；`13c481b` 独立调试 worker 也已接入；当前前台 loop 不注册此名称 | prompt + 可选参考 URL/数量/尺寸 → task IDs、图片 URL、审核证据。不要求 RP 会话或消息，资产保存/展示由宿主决定。例：独立为新NPC绘制头像 |

Sumi 走自己独立的状态/正文/图片标记协议与后台生图流程，不能据此声称也调用这套 Orchestrator、`judge_npc` 或前台四工具循环。它的存储和恢复在 Sumi 分支独立完成。

依据：[Imagine 的 MCP 调用与回合后保存](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/tools/imagine-skill.ts#L199)、[MCP 暴露菜单](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/compat/image-mcp/server.ts#L425)、[独立图片工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/image-tool.ts#L18)、[Sumi](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/sumi/runtime.ts#L19)。


#### 有现成封装，业务还需主动接入的工具

| 名称 | 怎么用 / 存什么 | 当前接入边界 |
| --- | --- | --- |
| `get_memory` | 空参数 → 当前授权范围 `{revision,memory}`；缺省 `revision=0,memory=null`。例：读取用户偏好的称呼 | `/memory` 原生 Pi 工厂提供；`13c481b` 独立调试已接隔离 store，仍没有在 Emochi Orchestrator/前台注册 |
| `update_memory` | `{expectedRevision,memory}` → 完整替换 JSON 后的 revision。例：保存 `{preferredName:"阿林",…其余要保留的字段}` | 独立调试只改本次内存；生产接入仍需宿主绑定用户/会话 store 和 `beforeUpdate` 业务校验。漏写字段会删除，不是局部 merge，也不是日记系统的别名 |
| `toPiTool` | 包装六专家：业务 prepare 提供授权上下文、模型、Prompt；Pi 接收 `content/details` | 适配函数，不是业务工具新名字；默认 RP context 有类型边界，自定义世界数据不能无条件硬套 |
| `createAgentCoreToolWithContext` | 宿主同步编译自己的上下文供同一专家分析 | 可让 NPC 专家分析自定义剧本/项目，不会自动检索世界书或继承 Actor 的完整 Prompt |
| SDK `SlowTurnRuntime` / `FastSlowRuntime` | 业务传 `capabilities`，模型调用后由业务解释结果；持久化需显式 `prepareCommit`/store | 两种 runtime 是执行框架，不是工具。默认能力列表可为空；不会因为包里导出就把全部工具注册 |
| `McpCapability` / `CapabilityExecutor` | 按静态执行图调用指定 MCP、传依赖结果、投影 prompt/artifact | 通用接线类已存在；`aoi.scene-observer → aoi.observe_scene` 是仓内示例，当前 closed-loop executor 空列表，不能写成线上自带场景观察工具 |

依据：[JSON 两工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/memory-tool.ts#L14)、[Pi 适配](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/pi.ts#L9)、[SDK 注册入口](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/sdk/src/slow-runtime.ts#L31)、[静态 MCP 示例](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/examples/aoi.ts#L6)、[工具包 exports](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/package.json#L12)。


#### 看起来也是“能力”，但当前不是由 Agent 随机挑选的 tool

| 模块 | 谁触发 / 输入输出 | 对当前 RP 的作用与例子 |
| --- | --- | --- |
| 世界书选择 | 宿主固定调用 `worldbook.select`；绑定书版本、query、历史、状态、预算 → 条目 blocks 与决策记录 | Actor 前注入；例：用户问北塔时检索北塔规则。没有提供给 Orchestrator 一个“想查再查”的 worldbook 函数 |
| 世界书配置与检查 | Demo 管理接线调用 `worldbook.book.get`、`worldbook.book.entries`、`worldbook.index.get`；只能查看配置好的书与修订 | 例：查看“北塔规则”原文和索引状态；页面的查看操作不是 RP 模型发出的工具调用 |
| 世界书会话绑定 | 创建会话时调用 `worldbook.conversation.pin`，后续用 `worldbook.conversation.get` 读取/核对绑定 | 例：这一段故事固定使用书的第 3 版，作者新发第 4 版不会自动改掉当前会话；Demo 当前绑定受配置限制 |
| Compact | 上下文预算/检查点治理；历史 → 压缩摘要和保留窗口 | 在需压缩的准备阶段发生，影响当轮上下文；不是慢通道六专家中的一个，也不是固定累积X轮后必调用 |
| 日记召回与写入 | 选定 memory runtime/sources 后宿主 recall；完成事件后 diary orchestrator 调度 ingest | 召回摘要交模板变量；之后经额度/锁/冷却等规则判断是否写日记。例：长期记住一起救援的经历 |
| 表格记忆 | recall 表与版本；完成回复后解析编辑并按版本保存 | 例：物品表更新钥匙归属。Go 路径可后台 ingest；这不是模型调用 `update_memory` 的任意 JSON store |
| Persona / Personalization / Hinos | 相应 memory runtime 或 hook 的准备/回合后生命周期 | 给当前上下文提供用户材料或把本轮送到外部记忆处理；具体外部服务算法不是 Harness 六工具实现 |

“世界状态”也要具体区分：`simulate_world` 返回场外发展建议，Story World 按快照与机制推进事件，Visual World 保存外观/画面连续性；它们没有自动合并成同一份 state。

日记、表格召回结果成为 external setvars，只有模板实际引用相应变量才进入 Actor 提示词。世界书、Compact、专家 ledger、JSON memory 都有各自生命周期；不能把其中任何一个的保存说成自动同步其余所有模块。

依据：[世界书调用](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/runtime.ts#L41)、[日记/表格召回与写入](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/axon-memory-runtime.ts#L99)、[Compact](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/memory/compact-runtime.ts)、[记忆模式接线](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/adapters/agent-router/dispatch.ts)、[世界书只读接口](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/demo-config.ts#L39)、[会话版本绑定](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/worldbook/debug-api.ts#L103)。

</details>


<details id="ch21-specialist-examples">
<summary>展开六位专家的职责、调用示例与保存过程</summary>

**这里的“六位专家”，就是六种分工明确的 LLM 分析工具：剧情、人物、知识、世界进展、伏笔和场面。** 每调用一位，程序就拿它对应的岗位说明（Prompt）、模型配置和这轮材料，请模型专门分析一个问题，再把分析意见交回来。

可以把它理解为“给大模型六份不同的岗位说明书”。同一底层模型可以承担多个岗位，也可以给不同岗位配置不同模型。六个名字代表六种职责，不意味着一定有六种底层模型，也不意味着它们各自常驻、各有一份独立长期记忆。正常成功时，一次专家分析通常对应一次模型请求；失败或空结果可能重试。**真正对玩家写正文的是 Actor，协调器负责选专家，Director 负责把意见整理成候选状态。**

本补充展开六位专家的实际用法。范围是已核验主线 `77a1537` 的普通 Agentic RP；Story 和 Sumi 有各自流程，其他工具清单见第 21 节。下面的对话、调用原因和结果都是帮助理解的虚构示例，不是线上执行记录。

#### 先认清六位专家

| 可以怎样叫它 | 代码里的工具名 | 它专门回答的问题 |
| --- | --- | --- |
| 剧情顾问 | `analyze_plot` | 用户这么选之后，故事接下来往哪走？主线、当前情节、分支要不要调整？ |
| 人物顾问 | `judge_npc` | 这个人是谁、为何在这里、与谁有关、知道什么、怎样进场或退场？ |
| 知识审计员 | `audit_knowledge` | 哪些是事实、猜测或谎言？每个角色究竟凭什么知道某件事？ |
| 世界进展顾问 | `simulate_world` | 玩家忙着眼前的事时，时间、期限、日程和场外人物发生了什么？ |
| 伏笔与承诺管理员 | `manage_callbacks` | 哪个承诺、线索、物品、伤势或欠账还没处理？什么时候值得重新提起？ |
| 场面导演 | `direct_scene` | 这一幕重点写谁、从什么视角写、角色该主动到什么程度？ |

六位都给**分析建议**。它们的共同工具定义明确不直接写正式状态；“场面导演” `direct_scene` 也要和后面整理状态的 Director / `update_director_state` 分清。[六位的职责定义](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L18-L37)、[每位专家怎样调用模型](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L239-L273)

#### 一轮里怎么叫专家，专家拿到什么

用户发来 query 后，普通 Agentic 在 Actor 开始生成时并行安排后台工作。协调器先看这轮需要解决什么问题，从本场景启用的专家中选择；程序补上必要的强制检查，选中的专家再并行执行。**本轮 Actor 不等这几份分析全部完成才开口。**

工具 schema 向协调器声明的参数是：必填 `reason`（为什么找你）与可选 `focus`（这次重点看什么）。当前普通 Agentic 没有开启注册表的严格参数校验，因此“schema 必填”不等于执行时一定拦住缺参；详见第 24 章。其余材料由程序补入：主角色的名字、描述、原始设定和开场白；轮初状态与连续性记录；最近 9 条有效消息；当前 query；如有则带用户人设与较早历史的 Compact 摘要。9 条是消息数，不是 9 轮；状态与记录会按长度裁剪。

因此它能“基于角色卡已有世界观”分析，但前提是世界观确实出现在这些材料中。**Actor 本轮刚收到的世界书条目，不会自动同步给专家；Actor 本轮正在写的新正文，后台此时也还看不到。** 同批专家共享轮初材料，各自回答各自的问题，不是剧情专家先写完、NPC 专家再接着读它的结果。

普通 Agentic 每次逻辑生成安排一次后台分析，没有统一“攒满 X 轮再叫六位专家”的规则；但也不是每次把六位全调用。首逻辑轮会补上已启用的人物顾问和场面导演；近期文本的名字检测发现轮初状态里没有的名字时，会补人物顾问。名字检测使用启发式规则，可能漏检；实际执行还受工具额度等设置约束。其他表述中的“适合调用”是协调器可据以选择的业务理由，不是每句话都有硬编码关键词触发器。

依据：[共享输入与长度处理](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L169-L236)、[参数格式](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L63-L79)、[强制检查与额度](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L671-L739)、[选中专家并行分析](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L841-L875)、[Actor 启动时安排后台](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L700-L716)。

#### ① 剧情顾问：用户改变选择后，故事怎样继续

`analyze_plot` 负责分析主线、当前情节和分支是否需要改变。它适合处理“用户拒绝原来的路线”“当前目标卡住”“用户主动提出新方向”等情况，帮助故事承接玩家选择。

**例子。** 原目标是进北塔找失踪者，用户说：“我不进塔了，先去城门问问昨天的出入记录。”协调器可以给它 `reason`：“用户改变了调查路线”；`focus`：“保留寻找失踪者的目标，检查当前情节是否应转向城门调查”。

**可能给出的意见：**“目标仍是寻找失踪者；接下来可以询问登记官，塔内线索暂时挂起。如果用户继续追问，再引出出入记录中的异常。”这是一份剧情方向建议；用户刚说想去城门，不能据此记录为他已经到达、已经问完并拿到了答案。

**后续怎样用：** Director 可以把“待推进：查城门记录”“暂缓：进入北塔”整理进状态。后续 Actor 读到后，更容易沿着用户选的方向写下去。

#### ② 人物顾问：让新人物逐步站得住脚

`judge_npc` 负责人物身份、人数、动机、关系、知识范围、位置，以及合理的进出场路径。新人物出现、同名人物混淆、人物忽然知道不该知道的事，都是它适合检查的问题。

**例子。** 主角色卡描述一个异世界酒馆，世界书里没有这个人物。用户说：“美国总统出现了，站在酒馆门口，请接着演。”Actor 可以先写他观察四周、与店主搭话；后台则围绕“这个陌生来客怎样在当前世界中成立”分析。下面是一次示意调用，工具名为 `judge_npc`：

```json
{
  "reason": "用户安排了当前状态中没有的新人物：美国总统。",
  "focus": "整理已知身份、当前所在位置、关系和知情范围；给出与角色设定相容的性格或来历方向，区分已发生事实与待揭示建议。"
}
```

**可能给出的意见：**“已知他是用户称作‘美国总统’的外来者，刚到酒馆；尚不认识店内人物。可考虑让他擅长谈判、表面镇定，但担心身份在异世界失去作用；来路暂留为待揭示线索。”这些性格与来历方向是创作建议，不是代码规定每次都要生成的字段，也不能把‘可能被召唤’直接记成已发生的事实。

**后续怎样用：** Director 选择应保留的人物事实、关系、待解问题与扮演方向，保存成功后供后续 Actor 使用。当前工具返回分析文字，没有独立的“创建 NPC 小卡”接口，也不会自动新增世界书条目。可以通俗地理解为后台整理人物档案的材料，但本轮回复无需等待一份完整身世。

用户已在 query 点名的人物，本轮后台就能看到；如果是 Actor 本轮临场创造了人物，要等这段正文进入之后的历史，后台才有机会分析。第 22 节另有两种情况的完整时序。

#### ③ 知识审计员：防止角色突然全知

`audit_knowledge` 负责区分事实、秘密、谎言、猜测与证据，并检查每个角色通过什么途径知道什么。它看的是**信息归谁知道、依据是否成立**；人物顾问则还要兼顾人物身份和进出场等更广的问题。

**例子。** 已有历史写明：只有用户和莉娅在密室见过钥匙，守卫当时不在场。用户问：“守卫怎么知道钥匙在我手里？”协调器可以把重点设为：“核对守卫的知情来源，区分亲眼见到、听说和猜测”。

**可能给出的意见：**“目前没有守卫获知钥匙归属的证据。他可以怀疑或试探，但不能把确切位置当作自己已经知道的事实；用户的提问也不能替代此前缺失的知情过程。”

**后续怎样用：** 状态可以保留“莉娅知情、守卫未知或仅怀疑”。后续 Actor 让守卫追问，比直接报出密室细节更符合现有材料。专家给出审计意见本身并不能保证模型之后绝不犯错。

#### ④ 世界进展顾问：镜头之外的世界怎样继续

`simulate_world` 负责因时间流逝或人物分离而需要考虑的日程、位置、期限和场外活动。它让故事里的世界不只随着眼前一句对话静止，但分析仍应建立在已有时间和安排上。

**例子。** 先前已经说明城门日落关闭，莉娅下午去码头打探。用户现在说：“我和这位总统在酒馆谈了两个小时。”协调器可以要求：“检查谈话时长对城门期限、莉娅的既定行程有什么影响”。

**可能给出的意见：**“若当前时间已接近日落，应保留赶赴城门的紧迫感；莉娅仍在场外执行此前安排，没有证据证明她已找到线索或已回到酒馆。”如果材料不足以算出准确时间，可以给条件判断，而不是编一个精确时刻。

**后续怎样用：** Director 可整理期限提醒、场外人物所在位置与待确认进度，让后续 Actor 适时提及暮色或等候中的同伴。这是普通 Agentic 的世界进展建议；Story 有另一套按快照推进事件的世界机制，Visual World 则保存画面外观连续性，三者不是同一份状态。

#### ⑤ 伏笔与承诺管理员：把尚未处理的事记住

`manage_callbacks` 负责承诺、线索、物品、伤势、义务、伏笔和延迟后果。重点是跟踪“还有什么没兑现、没解释、没归还”，而非每次提到伏笔就必须马上揭晓。

**例子。** 已有对话中，总统答应“明天带来通行文书”，用户手中还有向莉娅借的钥匙。用户说：“先不说通行证了，今晚休息。”协调器可以让它检查：“哪些承诺需要保留，哪些事情还未完成”。

**可能给出的意见：**“通行文书承诺仍待兑现，不能记成用户已拿到；借来的钥匙尚未归还。当前休息场景可以暂不追问，在明日会面或再次需要钥匙时再提起。”

**后续怎样用：** 成功保存的待办与伏笔能帮助后续 Actor 自然回收线索。它不是日历提醒服务，不会仅因账本里有‘明天’就在现实世界自动发消息；是否在某轮提起，还要结合剧情和后续生成。

#### ⑥ 场面导演：这一幕怎么写，谁可以主动

`direct_scene` 负责视角平衡、镜头方式和角色主动性，工具说明还包含 0–4 的主动性预算。这个数字表达角色主动行动程度的建议，不是回复轮数或 token 数，也不授予角色替玩家决定行动的权力。具体文字指导取决于实际专家 Prompt。

**例子。** 用户说：“我沉默地看着守卫，等他开口。”协调器可以让它重点看：“让守卫主动回应，但保留用户对下一步行动的决定权”。

**可能给出的意见：**“镜头留在守卫与用户之间；守卫可以注意到用户没有回答、提出一个问题，或指出当前选择。不要替用户写出‘我承认偷了钥匙’，也不要擅自让用户跟着走进塔。”

**后续怎样用：** Director 可把场面重点、视角与主动性约束整理进状态，供后续 Actor 控制叙事节奏。它给写作方向；实际正文仍由 Actor 生成。

上面六种用法对应代码中的职责描述；各专家更详细的岗位 Prompt 从 Axon PromptManager 读取，并绑定各自的模型配置。只凭这两个仓库，能确认职责、参数和执行过程，不能把示例输出当成线上 Prompt 保证执行的固定模板。[职责和输出约定](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L31-L37)、[专家 Prompt 的加载](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/prompt-manager.ts#L195-L252)

#### 几位专家一起用时，意见怎么合成结果

继续“新总统进入酒馆”的例子：如果本轮主要需要解释新人身份与知情范围，协调器可以选择人物顾问和知识审计员；如果用户同时明确说会谈过去两小时，也可能需要世界进展顾问。**这取决于启用清单、协调器选择、强制规则和执行预算，没有要求为了一个新人把六个工具全跑一遍。**

| 环节 | 实际做什么 | 在这个例子里怎样理解 |
| --- | --- | --- |
| 专家执行 | 各自调用模型，返回 `ok`、工具名、分析文本，以及可获得的用量或错误 | 人物顾问提出身份与扮演建议，知识审计员检查哪些秘密他还不知道 |
| 协调器复核 | 执行了专家且启用状态工具时，读取整批结果，决定是否请求 `update_director_state`；首轮/新人物规则可补调用 | 判断这次变化是否值得整理入状态，不直接把六份文字拼进 Actor 的本轮 Prompt |
| Director 整理 | 用轮初材料和专家结果，生成完整候选状态 | 合并“新来者在酒馆”“尚不认识店内人物”“来历待揭示”等信息，保留其他已有状态 |
| 校验与版本写入 | 候选有效、有变化，且版本检查通过，才保存状态与本轮成功专家分析的账本 | 不能用过时的候选覆盖另一轮已写入的新状态 |
| 后续回复使用 | 下一次准备时读取已经保存成功的状态及有限长度的记录投影 | Actor 逐步维持同一个人物的性格、关系与知情边界 |

**专家分析完、Director 整理完、状态保存完，是三个结果。** 某位专家失败时，其建议不会作为成功分析保存，但 Director 仍可能依据其他材料更新。Director 未执行、候选无效或没有变化、版本冲突，则可能让这次整理无法成为新的持久状态。已经开始的本轮正文不会因为后台提交而重写；如果后台赶在下一轮准备前存好，下一轮可读，否则要更晚。

这里按主线说明。第 23 节的候选分支另外增加“等待本轮正文保存、将状态挂到消息分支”的处理；它仍保留并行分析与上述六个专家的分工。

依据：[专家的成功和失败结果](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L315-L341)、[协调器复核与 Director](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L878-L956)、[候选检查和提交](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L979-L1008)。

#### 业务单独调用一位专家时，怎么接

已有业务也可以只接其中一位。例如原有 RP 系统只想增加 NPC 分析，就给 `judge_npc` 准备角色与授权范围内的对话、起始状态、模型、Prompt 和本次问题，执行后读取分析文本，再由业务决定怎样使用、怎样保存。工具包还提供 Pi 适配和自定义上下文编译入口，便于接进已有 Agent。

**是否让玩家等待，由调用位置决定。** 把专家放在 Writer 前并等待返回，它就增加本轮生成前的等待；像当前普通 Agentic 一样安排到后台，则先让 Actor 承接剧情，后续再消费保存好的结果。仅仅安装这个工具，不会自动获得当前应用的后台调度、世界书输入或持久化链路。

工具说明中的 `advisory`、`readOnly` 等属性也不替业务提供权限隔离或事务。调用外部服务、读写存储时，执行代码和宿主仍须落实各自的用户范围与保存规则。[专家的上下文编译与模型调用](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L239-L273)、[Pi 适配](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/pi.ts#L9)、[Registry 校验边界](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/sdk/src/registry.ts#L38)。

#### 其他工具的结果，何时进入当前回复

应用可以把某项工具返回的材料放进当轮 Prompt，例如先查到“桥已封闭”，再让 Actor 写抵达桥头的反应。这个调用位置和材料投放要由场景接好；普通 Agentic 的六专家后台并没有自动采用这条用法。图片资产、诊断或保存回执，也可以只供程序处理，不必全塞进 Prompt。[工具结果进入当轮 Prompt](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/prompt/compiler.ts#L33)

另有可单独复用的 JSON 记忆读写：读取返回内容和版本，更新接收完整新对象及预期版本，由宿主绑定的存储保存。它是整对象替换，未携带的旧字段会被删除；它不会自动接管 Emochi 的日记、表格或导演状态。工具还可以有执行前、执行后和整轮结束处理，但整轮回调需要宿主主动调用；外部写入已成功后，不能仅因后续日志失败就盲目重复写入。[JSON 记忆工具](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/memory-tool.ts#L14)、[工具生命周期](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/tool.ts#L10)

</details>

## 22. 新人物突然出现：本轮先接住，后台整理人物

用户说：“一位陌生使者站在北塔门口，请让他接着说话。”世界书里没有这位人物。产品要同时满足两件事：**这一句能继续演，之后又不能每次都把他写成不同的人。** 当前普通 Agentic 的接法是回复与后台并行，不要求先生成完整身世再开口。

下面用一位虚构使者走完；同样适用于用户之前举的“美国总统进入异世界”例子。身份名称变了，工具的输入、保存与时序不会因此自动增加一张人物卡。主层按固定 main `13c481b` 核对，候选分支另列。

### 本轮先让人物做什么，哪些内容还不能认定

假设角色卡已经设定“旧城北塔；守卫谨慎核验来访者”，用户只明确了使者出场。Actor 是负责用户当前正文的模型，它收到角色设定、历史、旧状态、本轮输入及这个场景提供的其他材料，可以先写：

> 陌生来客停在门槛外，抬手示意自己没有敌意。“我来找值守的人。”守卫没有立刻让路。

这样已经承接用户安排，不必先解释他出生在哪、为什么跨越世界或与谁有多年旧识。这是一种可能的生成结果，不是固定模板。新的人物动作以写出的实际正文为准，后台不会提前保证它一定这样演。

同时，后台拿到的是本轮开始时的材料。用户已说的“使者在门口”它能看到；Actor 刚临场写出的“抬手示意、要求见值守者”它这次看不到。因此后台应区分：用户已经确认的人物位置、尚未确认的身份来历、之后可以采用的创作建议。

### 谁决定找人物专家，它拿到什么

普通后台协调器会根据本轮材料和可用工具菜单选择检查。程序也有首轮、新名字补人物检查的规则，前提是这项能力已启用并能在执行预算内安排。它不是每出现任意新称谓就必定识别；这次例子假设协调器选中了人物检查。

发给 `judge_npc` 的任务可以用人话读成：

> 为什么找你：用户安排了此前状态中没有的来客。  
> 重点检查：他是谁、在哪、与现有人物有什么依据支持的关系、知道什么；来历不明就保留未知。

Harness 再补入角色设定与开场白、可选用户人设、旧状态与有限记录、近期对话、本轮输入，加上人物专家的专项工作说明，调用模型。**“基于世界观”意味着世界观必须真实出现在这些材料中。** 当前 Actor 收到的世界书原文不自动同步给专家；工具也不会因为人物缺资料就自行查世界书或网络补完。

### 专家交出的不是小卡，而是一份分清事实与建议的分析

本例可能交回：

> **已有依据：** 用户称他为使者，目前站在北塔门口。  
> **仍然未知：** 姓名、代表谁、为何来到这里、与守卫是否认识。  
> **连续性要求：** 后续继续当作同一名来客；没有依据就不要突然说他是守卫的老朋友。  
> **可选创作方向：** 可通过下一次问答逐渐透露任务；保持谨慎举止，但不要把尚未发生的问答当成既成事实。

“可选方向”帮助以后扮演，并不是世界事实。人物专家的能力是分析身份、关系、知识、位置与进退场，不是保证每次填写固定姓名、性格、背景字段；详细岗位提示来自外部配置，仓库本身不能证明线上一定使用“完整小卡生成”模板。

### 分析怎样变成下一次可以读的材料

有检查结果且允许更新状态时，协调器再决定是否整理。Director 是整理剧情状态的模型岗位，负责把旧状态和有用建议写成一整份新稿。例如保留旧塔门状态，再加入：“新使者在门外；身份与来意待证实；不要重复新增同一个人。”

程序检查格式、长度、内容是否变化，再按旧版号尝试保存。成功时，当前会话状态更新，还可留下人物分析的分类记录；未来准备回复时，程序会把有限长度的状态与记录文字放入 Actor 输入。Actor 因而有机会继续同一人物，而不是每轮重新发明。

这不是改世界书，也不是建立一个可独立编辑、检索、跨会话复用的 NPC 实体。后台新稿未采用或保存失败时，没有这份新记录；某位专家失败时，Director 仍可能利用其他材料更新，只是失败分析不能作为成功记录。即使存好了，下一句来得比后台快，也可能先读旧版本。

**当前可以描述的能力是“先承接出场，后台为后续一致性整理人物”。** 如果产品要一张真正可管理的小卡，还需明确人物 ID、字段、事实与候选设定、保存范围、修改权限，以及哪一步将卡片交给模型。

### 如果新人是 Actor 自己临时写出来的，什么时候才轮到后台知道

换一种输入：用户只说“我走进岗亭”。Actor 这一轮自己写出一位从未出现的使者。因为后台已经使用起始材料启动，它不能可靠地分析自己尚未收到的人物。

这时通常需要：**本轮正文先保存 → 下一轮把它带入历史 → 后台才有机会识别并分析 → 整理保存成功后，更后面的回复读到新状态。** 下一轮 Actor 已能从历史承接使者出场，但那不等于人物审计已经完成。若后台更晚保存，采用也会更晚。

名字检测只扫描有限的近期消息与本句，使用规则提取候选名并与状态文本对照；别名、称谓和句式可能漏检，协调器也可能自行选人物检查。它不是一个能保证所有人物都有唯一档案的识别系统。

### 候选分支补了什么，还没有补什么

此前核对的候选分支把后台状态提交与已保存的助手正文、正确消息分支挂接，试图避免重生成后读到另一条回复所属的旧状态。它保留并行分析，没有把本轮新正文自动追送进已启动的后台，也没有让 Actor 等完整 NPC 卡。

“已保存正文”也不等于玩家点击接受。候选接线应单独验收，不能作为当前 main 已有完整建卡与人物事实审查的证明。

[普通后台并行调度](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/runtime.ts#L569)；[人物检查职责与输入](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/packages/tools/src/modules/memory/advisory.ts#L31)；[首轮和新名规则](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/agentic-v2.ts#L671)；[Director 整理与提交](https://github.com/FlowGPT/roleplay-harness/blob/13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/agentic-v2.ts#L879)。

<details>
<summary>原“美国总统”例子：两种时序、名字检测样例与固定证据</summary>

历史固定依据：[并行调度与固定输入](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L569-L586)、[Actor 开始即调度](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L700-L716)。

#### 情况一：用户已经明确安排“美国总统”出场

以下是虚构剧情示例：角色卡设定为“异世界的边境酒馆，偶有异乡人出现”，世界书没有“美国总统”这条资料。用户在第 N 轮说：“美国总统出现了。他站在酒馆门口，请接着演。”

| 发生在哪一步 | 这一轮实际做什么 | 玩家感受到什么 |
|---|---|---|
| 本轮准备 | 读角色设定、历史与起始状态；快慢各自组装材料 | 还没有等待 NPC 专家建档 |
| Actor 生成 | 可以写“门口的陌生来客整理衣领，先观察四周”，承接已给出的出场安排 | 剧情继续，不必先交代童年、性格全貌和穿越机制 |
| 并行后台 | 协调器选择专家；代码也会检查近期可见文本中的新名字，命中时补上 `judge_npc` | 后台审计不阻塞这段回复 |
| 整理与保存 | 专家给建议；Director 生成完整候选状态；格式与版本校验通过才保存 | 本轮已开始生成的正文不会因此重写 |
| 后续轮准备 | 读取当时已经保存成功的状态 | 如果保存赶在 N+1 轮准备之前，该轮可使用新整理；否则更晚 |

这条链路不是每隔 X 轮才启动。普通 Agentic 的慢规划随该次逻辑生成启动一次；协调器决定哪些专家值得用。第一轮、以及检测到起始状态没有的新名字时，代码会补上人物审计，前提是 `judge_npc` 已启用。第一轮还会补上已启用的 `direct_scene`。执行仍受工具预算约束：在 enforce 模式下，强制工具优先排入，但极低预算仍可能截去后面的调用。[强制条件与执行顺序](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L639-L739)


#### 情况二：用户没点名，是 Actor 在正文中临时创造了人物

用户只说“我推开酒馆的门”。第 N 轮 Actor 自己写出“美国总统坐在角落”。**这一轮后台不知道刚写出的这句话。** 它不能针对尚未出现在自己输入中的人物，可靠地开展补全。

时序因此是：**N 轮 Actor 写出人物 → 业务保存这段正文 → N+1 轮把它带进历史，后台才有机会识别并审计 → 保存成功后，N+2 或更晚的 Actor 才读到这份后台整理。** N+1 的 Actor 仍能直接从聊天历史知道这个人已经出现，只是还没有这次新审计的持久状态。

“有机会”有具体含义：代码用多语言正则扫描最近 4 条 user/assistant 消息加当前 query，再看候选名称是否已出现在起始 state 文本中。它不是完整的语义人物识别器，称谓、别名和句式都可能导致漏检或误判；没命中强制规则，协调器仍可自行选择人物工具。对最新函数直接运行样例：`美国总统出现了`、`这是美国总统`能提取到“美国总统”；`让美国总统承接剧情`没有命中。`I meet John Smith`只提取 John。这里也没有查询世界书来确认“这个人是否已经建卡”的步骤。[名字检测](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L639-L687)

</details>

<details>
<summary>人物工具准确参数、输入范围、分析与账本格式</summary>

#### NPC 工具怎么调用，它到底得到什么

`judge_npc` 的接口声明要求 `reason`，可选 `focus`；角色卡、历史、状态由运行时补入。不过普通 Agentic 后台没有开启严格参数 schema 校验，不能把“声明必填”理解为缺参一定在执行前被拒绝。下面是**虚构调用示例**，不是线上抓取：

```json
{
  "reason": "用户安排了起始状态中没有的新人物：美国总统。",
  "focus": "确认身份称谓、所在位置、与酒馆人物的关系和已知信息；来历未明时保留未知，不把猜测写成既成事实。"
}
```

它实际获得：当前主角色的名字、描述、原始定义、开场白；当前 Agentic 状态及账本投影；最近 9 条有效可见消息；最新 query；上面的 reason/focus；若存在，还包括用户 persona 与 Compact 摘要。它没有收到“全仓库工具”“世界书全库”，当前选中的世界书原文也不会因 Actor 已收到就自动传给专家。[参数定义](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L63-L79)、[专家材料组装](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L168-L237)

“基于这个卡的世界观”也有明确来源：优先取业务返回的 `prompt.init_prompt`；没有时才拼接角色卡的 personality、scenario、summary、system_prompt，另带 description 与 opening message。**世界观若只存在于本轮世界书注入、没有进入这些材料，不能假定 NPC 专家也知道。** 专家具体写作要求从 Axon 的 PromptManager 读取；这两份仓库本身不能证明线上一定使用某份“生成完整 NPC 小卡”模板。[角色设定来源](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/runtime.ts#L388-L489)、[运行时专家提示词](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/prompt-manager.ts#L195-L252)


#### “补小卡”在代码里对应什么结果

`judge_npc` 返回的是分析文本，**没有独立 NPC 卡的固定字段，也不会直接创建世界书条目或写状态**。下面仍是虚构输出：

```text
已确定：用户称其为美国总统；现在站在酒馆门口。
身份待确认：具体姓名、任期、是否为真实本人均未说明。
关系与知识：尚不认识店内人物；不能默认知道当地秘密。
可选性格方向：擅长谈判，表面镇定，但担心身份在陌生世界不再有用。
可选来历方向：把来路作为待揭示线索，后续用一次询问或事件建立。
后续扮演建议：先以陌生来客的谨慎观察接话，通过后续互动逐步建立细节。
未知：如何来到这个世界；不要直接写成“昨晚被法师召唤”。
```

上例的性格、来历方向是虚构的创作建议，说明分析可以怎样帮助后续扮演；它们不是必填字段，也不是这次出场已经证明的事实。是否提出、采用和怎样采用，取决于实际专家 Prompt、模型结果与 Director 的整理。

这份建议交给 Director，与原状态及其他专家结果合并。Director 产出完整候选状态，可能更新“Active relationships and NPCs”“Social graph and NPC lifecycle”“Knowledge boundaries”等段落。只有候选有效、有变化且版本写入成功，才同时保存状态与本轮成功专家的账本记录；NPC 分析记录形如 `type=npc`、`key=judge_npc:turn:N`、`payload.analysis=分析文本`。它是“供后续回复维持人物一致性的记录”，可以通俗叫人物小档案，但不能理解为已经有了一张可独立编辑、检索和复用的 NPC 实体卡。[工具只给建议](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L31-L37)、[Director 的合并要求](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L364-L399)、[保存状态与账本](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L942-L1008)、[账本结构](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/apps/emochi/planning/agentic-v2.ts#L742-L760)

如果 NPC 专家失败，可能返回 `ok:false`；Director 仍可能依据已有材料整理状态，失败专家不会生成成功分析账本。如果 Director 没启用、候选无效或没变化、版本冲突或保存失败，就没有这次新人物整理的完整落库保证。即使保存成功，Actor 读的是有长度上限的投影，并非无限量人物档案。产品上应承诺“先让剧情继续，后台维护后续一致性”，不能承诺“每个新人物当场自动生成完整身世，并保证下一句马上采用”。[专家失败返回](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/modules/memory/advisory.ts#L320-L345)、[下一轮使用的投影限制](https://github.com/FlowGPT/roleplay-harness/blob/77a153779c1a3baf5c02af96366b252ec4cc3e22/packages/tools/src/context-compiler.ts#L32-L58)


#### 候选分支改变了什么

第 23 章核验的候选分支保留上述并行分析和 NPC 工具契约，但把状态提交与已保存的 assistant 正文、可见消息分支绑定。它仍不会让 Actor 先等一张完整 NPC 卡，也没有让已经启动的 Planner 自动看到本轮新正文。此处“已保存”不等于用户点击接受。

</details>
