# 业务如何接入原子能力

给已有的聊天产品增加能力，要把它放进实际的对话流程。例如，世界书需要在回复前查出设定，再交给模型；人物分析可以在当前回复之后执行，把采用的建议留给下一轮；图片生成结束后，还要让聊天页面显示图片，并在需要时保存人物外观。

这些能力有的已经接在 Agent V2 或 Story 中，有的需要研发加入自己的后端。下面先介绍各自的改动位置，再用世界书和人物分析展示一次完整接入。

## 先看你的业务现在从哪里运行

| 目前使用的程序 | 修改位置 | 需要完成的工作 | 使用条件 |
| --- | --- | --- | --- |
| 用户消息已交给本仓库的聊天服务 `apps/emochi`，由它执行 Agent V2、Story 等流程 | 研发修改该入口的 `config/scenarios/<入口名>.json`，启用应用已接好的能力，再让服务加载新设置 | 例如在 JSON 顶层合入 `worldbook`；连接 Axon／世界书服务；保存角色与书籍关联；业务请求选中该设置 | 这份 JSON 在代码里叫 Scenario。它不替你创建书籍、部署服务；不同产品也不能任意叠加 |
| 你已有自己的聊天后端：读取资料、请求模型、保存正文都由自己的代码完成 | 研发在已有代码的指定步骤调用能力。例如请求模型前调用世界书 HTTP；正文采用后调用记忆写工具 | 准备真实输入、处理返回／失败，把原文放进模型消息或把新状态写进自己的存储 | 每项能力的交付不同：可能是 npm 函数、HTTP 服务或需搬用的应用源码；对应页明确哪一种 |
| 你已有自己的聊天后端，还希望让一个模型决定下一步调用什么 | 研发将能力包装为该模型能选的工具：提供名称、用途、参数定义，并注册实际执行函数 | 执行函数从后端取有权使用的资料，调用能力，将结果交回模型；另按业务规则采用和保存 | 仅在 Prompt 中提工具名不能让程序执行；注册给自己的 Agent 也不会修改普通 V2 的工具菜单 |

每次回复都需要的资料，可以由程序固定查询，例如世界书。只有部分时候才需要的人物分析，则可以按业务规则调用，也可以交给模型决定。选哪种方式，取决于这项工作是否每次必做，以及结果需要赶在当前回复之前，还是可以留到之后使用。

[公共 Agent 与直调示例](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/examples/sdk/03-agent-tools.ts#L13) · [应用世界书配置入口](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/adapters/agent-router/dispatch.ts#L796)

<a id="integration-scenario-loading"></a>

## 服务怎样选中研发修改的那份配置

研发修改了某个聊天入口的 JSON，还要让实际运行的服务选中它。#232 合入后的读取顺序如下；配置仍只在启动时读取，改文件后需要重新加载服务或重新发布。

1. `HARNESS_ENABLED_SCENARIOS` 选择文件名，不带 `.json`，多个名称用逗号隔开。现在也能填 `compact-test-*`，匹配以 `compact-test-` 开头的配置；只支持非空前缀后面的 `*`，没有匹配文件就报错。
2. 稳定配置目录由 `HARNESS_SCENARIOS_DIR` 指定，缺省为 `config/scenarios`。另设 `HARNESS_EXPERIMENT_SCENARIOS_DIR` 时，同名配置先从实验目录读取，找不到才读稳定目录；不会逐字段混合这两份文件。
3. 如果还设置了旧的 `AGENT_ROUTER_SCENARIOS_JSON`，同 ID 的对象最后整份覆盖文件结果；只修改文件可能因此没有改变实际设置。
4. 聊天后端把所选入口 ID 填进请求的 `extensions.scenario_id`。服务使用已经加载的那份对象执行这轮请求，不能把文件路径作为 ID 发过去。

例如研发做一个“长聊摘要试验”，可以把独立配置 `compact-test-a.json` 放进实验目录，启动时选择它，并让试验请求使用 `scenario_id:"compact-test-a"`。其他聊天仍选自己的入口。加载结果会记录文件来自 base 还是 experiment、是否被旧 JSON 覆盖，以及整份配置与各入口的哈希，便于确认到底用了哪一版。[选择、优先级和实际加载](https://github.com/FlowGPT/roleplay-harness/blob/43332d8616b4e24874915a69cdea7bdaa0429aba/apps/emochi/scenario-files.ts#L18) · [加载来源与指纹](https://github.com/FlowGPT/roleplay-harness/blob/43332d8616b4e24874915a69cdea7bdaa0429aba/apps/emochi/scenario-files.ts#L65)

仓内另有 production 配置目录和覆盖文件；这些文件本身不证明运行实例已加载，也不代表所有新开关都已打开。接入验收要对照实际部署使用的目录、选中 ID 和有效配置。Hybrid Compact 的字段直接放在顶层 `compact.bootstrap/fallback`，详见[模型分工与兜底](#compact-hybrid)。

Sumi 的图片编译接入就是一个实际例子：研发需要在该入口的 `sumiV1.imageGeneration.promptCompilerUrl` 填编译服务地址，让实际服务加载这份设置，再检查一次图片描述是否经过编译。10 月 19 日的生产部署已采用 `f9b26a9` 镜像，里面包含编译失败后有条件使用原始图片标签继续生成的逻辑；这份部署记录没有提供生产配置读回，不能据此认定某个入口已经启用编译。Sumi 也不再额外补角色名和参考图规则，运营维护的 Prompt Manager 要提供这些内容。图片页列出了[所需资料、编译返回和失败处理](atoms-images.md)。

本轮新增设置分别影响不同的决定，研发应修改实际选中的入口，而不是只把字段写进一个未加载的文件：

| 想改变的行为 | 实际修改什么 | 不填写时怎样；怎样确认生效 |
| --- | --- | --- |
| 记忆服务故障时继续回复 | 在入口 JSON 顶层合入 `"failurePolicy":{"memoryRecall":"continue_without_memory"}`；保留入口原有的其他产品与模型设置。这个 `failurePolicy` 对象只支持 `memoryRecall` 字段 | 默认 `fail_turn`。联调记忆召回故障，检查是否记录 `memory.recall_failed`，以及回复是否在空记忆下继续；Hinos 只允许规定的临时服务故障，详见[记忆](#memory-recall-failure-policy) |
| 用 Sumi 生成文字，不生成图片 | 在该 Sumi 入口的 `sumiV1` 对象设置 `"imagesEnabled":false`，用 JSON 布尔值，不能填字符串 `"false"` | 默认 `true`。关闭后不发图片 loading、不创建或重放图片；参考图仍可能用于初始化，详见[Sumi 文字与图片](atoms-images.md) |
| 让 Sumi 使用聊天后端选定的模型 | 聊天后端在请求的 `extensions.turn_context.runtime_decision` 中提交 `target_model_config_id`；Harness 用它读取对应的模型配置 | 没有该选择时用 Sumi 的 `modelConfigRef`。检查实际 `mainModelConfigId` 与最终输入预算；不会因此更换初始化和历史导入用的视觉模型 |

[记忆失败配置解析](https://github.com/FlowGPT/roleplay-harness/blob/f9b26a919965f471756cdacf0f5b2e596cd5991d/apps/emochi/server.ts#L691) · [Sumi 图片开关解析](https://github.com/FlowGPT/roleplay-harness/blob/f9b26a919965f471756cdacf0f5b2e596cd5991d/apps/emochi/server.ts#L816) · [Sumi 接收模型选择](https://github.com/FlowGPT/roleplay-harness/blob/f9b26a919965f471756cdacf0f5b2e596cd5991d/apps/sumi/runtime.ts#L92)

### 刚修改角色资料或模型设置，为什么下一次未立即更新

现成应用通过 Axon 读取模型配置、角色卡、Prompt、PromptManager 和 Agent 配置时，会在当前服务进程中暂存结果，默认 30 秒。主线 #258 为这份缓存增加过期清理和容量上限：最多 1,024 项、约 4 MiB 的键与序列化内容；超过单项容量的返回仍可使用，只是不存入缓存。再次命中会更新淘汰顺序，不会把原定过期时间继续往后延。

因此联调时，管理端保存成功后，如果马上发请求仍读到旧的角色或模型配置，要分别检查保存结果、当前进程缓存和实际聊天入口；这不是世界书关联的永久固定，也不是聊天状态丢失。缓存过期后程序重新请求 Axon。它只存于当前进程，不能代替数据库，也不能保证不同副本在同一毫秒拿到一致的新配置。[缓存覆盖的资料与默认时长](https://github.com/FlowGPT/roleplay-harness/blob/82e0169ab2f59f38a11cbdc7e874deec720b0620/adapters/axon/client.ts#L343) · [过期、大小和淘汰处理](https://github.com/FlowGPT/roleplay-harness/blob/82e0169ab2f59f38a11cbdc7e874deec720b0620/adapters/axon/client.ts#L409)

## 一项接入，要连起来的六个环节

| 环节 | 产品需要定什么 | 研发实际要接什么 | 用“新增人物分析”举例 |
| --- | --- | --- | --- |
| **触发** | 每次执行、规则触发，还是允许模型选择；结果服务本轮还是下一轮 | 调用位置／触发规则／模型工具名单 | 当前回复先让商人出场，回复正式采用后再分析，为后续使用 |
| **准备输入** | 哪些资料可以作为已确认事实，哪些只是待补建议 | 登录账号与聊天 ID、已保存对话、实际正文、相关世界观、旧记录及其消息 ID／版本 | 提供已采用的“红衣商人拦住去路”及世界观，不能只传“分析一下商人” |
| **执行** | 可等待多久、是否允许额外模型成本 | 模型或服务适配器、超时与取消、参数检查、预算 | 调用 `judge_npc`，接收人物连续性建议 |
| **采用结果** | 谁决定将建议用于哪一步 | 检查失败、解析返回；需要时限制能更新的字段 | “可以是本地商贩”仍是建议；不能直接当成正文已发生的事实 |
| **保存** | 保存建议、确认事实还是完整实体；以什么事件为准 | 业务数据库／状态仓库、消息归属、版本冲突处理 | 业务可以保存待采用建议；完整 NPC 卡需要自己的数据结构与保存接口 |
| **再次使用** | 哪个角色／会话／聊天分支使用，什么时候失效 | 下轮读取、选择、放入模型输入或后续工具参数 | 下一轮回复模型读到已采用的人物约束，才有机会保持连续性 |

公共分析工具只完成表中的分析调用，其余工作由调用它的业务负责。普通 V2、Story 和图片应用已经各自实现了一部分，可以沿用对应产品的代码；它们的保存方式不同，具体规则见各产品页面。

## 例一：已有聊天业务，给角色加世界书

作者在世界书里写了“守卫放行必须核对手令”。用户说“我递出铜钥匙”时，程序需要把这条规则交给回复模型，模型才可能让守卫回答：“钥匙没错。手令呢？”下面按使用仓库应用和保留自己后端两种情况说明。

### 已经用现成 RP 应用：配置、绑定、检查正文输入

1. 运营按 [世界书原生格式](atoms-worldbook.md) 准备条目并保存，获得真实的 `book_id` 与版本。需要向量检索时，为使用的版本准备索引。
2. 管理端调用 `PUT /v1/entity-bindings`，将书关联到角色 ID。现成 RP 入口把聊天请求的 `promptId` 原样作为世界书 `entity_id`，因此关联时必须使用同一个值；选择固定版本或跟随最新。书存在但没有关联，不会被这张角色自动使用。旧 Prompt HTTP 接口仍兼容，但升级到新的 Entity RPC 前，要完成数据库 007 迁移并接通相应 Axon 转接。本轮已核两仓合入，世界书服务 `ad38dce` 也有 10 月 9 日成功生产部署记录；007 迁移、Axon 转接和真实关联查询仍需联调核验。
3. 研发在**该聊天入口的 `config/scenarios/<入口名>.json` 顶层**合入下面的片段，保留原有模型与产品设置；并确保 Harness 到 Axon、Axon 到世界书服务的调用已接通。`your-tenant` 必须替换为创建或导入这些书时使用的 `tenant_id`：这是保存和读取同一批世界书的分组编号，由接入研发约定并提供，不是服务自动生成。例如书是在 `tenant_id="production-default"` 下导入的，这里就填同一个 `production-default`；不能另起一个产品名或填当前用户 ID。

```json
{
  "worldbook": {
    "tenantId": "your-tenant",
    "strategy": "rules",
    "tokenBudget": 2400
  }
}
```

这里用 `rules` 展示静态规则接入；Harness 未指定策略时默认 `hybrid`。`tokenBudget` 只管世界书材料，整个模型请求仍需检查窗口。`HARNESS_ENABLED_SCENARIOS` 要包含该文件的入口名，服务在启动时加载；业务请求通过 `extensions.scenario_id` 选择同名设置。若部署已用 `AGENT_ROUTER_SCENARIOS_JSON` 提供同名设置，应改那里：它会整项覆盖文件。准确字段与覆盖规则见 [世界书配置](atoms-worldbook.md)。

4. 每次请求中，程序校验会话身份、用角色 ID（`entity_id`）解析关联版本；有书时选择本轮条目，把原文按位置装入 Actor。没有关联书时保留原业务回复路径。
5. 接入验收直接看这次 Actor 最终输入：是否出现“必须核对手令”、位置是否正确、版本是否对应。仅看到选择接口成功，还不能证明正文模型用了它。

研发还可以接入[世界书运行看板](#worldbook-metrics)，持续观察关联为空、选择条目数、耗时和 hybrid 降级等变化。Worldbook #18 已把指标与看板合入 main；看板导入属于作者记录；10 月 9 日后续版本的镜像部署已确认，但抓取注解不会随镜像自动应用，当前采集数据与真实流量未经查验。看板汇总值不带具体角色或正文，不能替代上面的模型输入核对；其中“空选择比例”还存在 `le="0"` 未匹配实际 `le="0.0"` 的查询缺陷，无数据不能作为空选择为 0% 的证据。

这一轮结束后，设定原文和角色与书籍的关联仍保存在世界书服务中。聊天程序只保存实际采用的对话，不会把刚才取出的设定原文也当成聊天内容。下一轮会重新读取关联、选择条目。普通 V2 的后台和专家使用另一份模型输入；如果也要让它们检查这条手令规则，研发需要另外把原文传过去。

[配置校验与产品组合](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/apps/emochi/server.ts#L770) · [每轮身份检查与书籍解析](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/adapters/agent-router/dispatch.ts#L796) · [条目选择输入](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/apps/emochi/worldbook/runtime.ts#L59)

### 自己的聊天后端：调服务，再把结果交给自己的模型

| 步骤 | 你的后端提交什么 | 拿回来什么 | 接下来做什么 |
| --- | --- | --- | --- |
| 管理资料 | `POST /v1/books?tenant_id=…`，提交名称和条目原文 | `books[]` 中的书籍 ID、版本等 | 保存业务角色与书籍的对应关系；也可使用服务的 Entity 关联接口 |
| 选择本轮资料 | `POST /v1/context/select?tenant_id=…`，提供允许的书籍版本、query、历史、state、预算与位置能力 | `blocks` 原文及位置、`decisions` 选择理由、`snapshot` 版本、预算诊断 | 检查返回，再按各条位置组装 |
| 组装模型输入 | 原有角色／历史／本轮输入，以及选中的 blocks | 自己构造的新消息数组；可复用 SDK `placeContextBlocks` | 检查完整输入预算，再发给自己的回复模型 |
| 交付与后续 | 模型生成正文 | 用户看到的回复 | 由原聊天业务保存正文；下一轮重新选择世界书 |

SDK 0.6.0 已提供 `@flowgpt/roleplay-harness/worldbook` 的 `WorldbookClient`，研发也可以调用 `createBook`、`replaceBindings`、`resolveBindings` 和 `select` 完成表中 HTTP 步骤，无需采用整套 Agent。完整 TypeScript、原生 HTTP 请求和返回样例均在 [世界书](atoms-worldbook.md)，组装代码在 [上下文组装](atoms-context.md)。客户端默认每次调用 30 秒，支持单次超时与取消，不自动缓存或重试；网络失败时仍须核对远端是否已经写入。REST 的 `tenant_id` 是保存和读取同一批世界书的分组编号；创建书籍、绑定角色和选择条目必须使用对应的同一个值。已有书籍沿用创建时的值，由接入研发提供，不能让聊天用户随意切换。你的后端或网关还需核验登录用户能否使用这些书籍；填对 `tenant_id` 本身不等于通过用户认证。

独立调用时，程序也要处理查询失败。关联的书籍或版本失效，需要先修复关联；查询超时或必需条目放不下，需要按产品约定返回错误或降级。返回空条目时，先查触发词、条件和预算诊断：没有选中资料，也可能是这次输入确实不需要它。

[世界书 HTTP 接口](https://github.com/FlowGPT/worldbook-service/blob/fafdb8d866a8956927d4b6142683221e7cb89a96/src/worldbook/app.py#L216) · [SDK 消息放置函数](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/packages/sdk/src/context-placement.ts#L50)

## 例二：给自己的业务加人物分析

用户让一个红衣商人突然出现，当前回复先接着写剧情。后台可以随后调用 `judge_npc`，根据实际写出的内容和世界设定，分析这个人物的身份与行为是否合理。它返回人物建议；如果产品还需要一张可以编辑、长期保存的 NPC 卡，研发要另外定义卡片字段、ID 和保存接口。

下表展示自有后端的一种实现：等业务采用本轮正文后，再分析新人物。触发和保存代码需要自己编写；普通 V2 现有后台与正文同时启动，时序与本例不同。

| 时间 | 业务动作 | 具体输入或产物 |
| --- | --- | --- |
| 本轮回复 | 现有回复模型承接出场 | “一个红衣商人挡住去路，举起一张泛黄的地图。” |
| 正文采用后 | 后端用已采用正文准备分析材料 | 商人刚出现；尚未确认名字、来历与动机；附上这座城市的相关规则与已有角色资料 |
| 调用人物工具 | 固定调用 `judge_npc`，或由自己的后台 Agent 选择它 | 返回人物连续性建议，例如“不要默认他认识用户；身份可考虑本地地图贩子”。这是示例，不是固定输出 |
| 采用与保存 | 业务检查建议，保留建议与确认事实的区别 | 若需保存 NPC 卡，另行生成／校验卡片字段并调用自己的存储；若只需写作约束，可保存经采用的约束 |
| 下一轮 | 后端读出本次采用结果，送给回复模型 | 模型获得“商人尚不认识用户”等约束；丢弃分析结果就不会改变后续回复 |

若分析必须影响本轮正文，把调用放到回复前并等待；这会增加本轮等待时间。若放到后台，当前已经生成的正文不会被工具结果自动改写；下一句来得过快时，也可能读不到尚未完成的分析。

### 研发接法 A：在已有流程里直接调用

<details>
<summary>展开调用片段、输入准备与失败处理</summary>

下面是**一次请求中的调用片段**，不是完整应用。`context.character` 填当前被扮演角色的真实资料，`context.question` 填用户原话，`context.history` 填已保存的对话，`context.state` 填读取到的旧笔记；具体结构见 [分析工具的输入表](atoms-specialists.md)。这里不会先编一张新商人小卡作为已知事实。

本例另外准备 `acceptedReplyText`：业务已经采用的这次角色回复原文，例如“一个红衣商人挡住去路，举起一张泛黄的地图”；以及 `relevantWorldRules`：研发从角色设定或世界书取到、允许本次分析使用的规则原文数组。下面的 `compileContext` 明确把它们放进专家的输入；仅在 `reason` 中写“已有正文”，不会自动把正文传进去。`model` 是研发已实现的 `complete(request, signal)` 模型适配器，`signal` 控制这次请求取消。

```ts
import { createAgentCoreTool } from '@flowgpt/agent-core-tools';

const npcTool = createAgentCoreTool({
  name: 'judge_npc',
  modelConfigId: 'your-npc-model',
  modelCallTimeoutMs: 15_000,
  compileContext: ({ context, arguments: args }) => JSON.stringify({
    character: context.character,
    question: context.question,
    history: context.history,
    savedState: context.state,
    acceptedReply: acceptedReplyText,
    worldRules: relevantWorldRules,
    reason: args.reason,
    focus: args.focus,
  }),
});

const advice = await npcTool.execute({
  context, model, signal,
  prompt: '检查人物连续性。将材料中已确认事实与待采用建议分开。',
  arguments: {
    reason: '本次正式正文中出现一个新商人，需要后续保持一致',
    focus: '身份、动机、是否认识用户；不要把建议说成已发生事实',
  },
});
if (!advice.ok) throw new Error(advice.error ?? '人物分析失败');
// advice.result 是建议文本。调用方决定采用什么、何时保存、交给谁。
```

这个工具实例和额外材料绑定本次请求，不应拿去复用其他用户的聊天。自定义编译器会替换默认的材料投影，业务要在提交前处理材料长度；它不会再自动套用默认历史截取规则。这段没有实现数据库保存。业务调用层还要处理异常、返回失败和超时，并验证模型实际收到的材料；15 秒字段的作用范围见 [分析工具的超时规则](atoms-specialists.md)。仓库提供的 [完整直调示例](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/examples/sdk/02-direct-tools.ts#L7) 使用假模型，适合验证接线与返回处理，实际模型质量要另外验证。[自定义材料编译入口](https://github.com/FlowGPT/roleplay-harness/blob/ccaaa46e6fd16544481284bb1388fc78cc177009/packages/tools/src/modules/memory/advisory.ts#L244)

</details>

### 研发接法 B：让自己的主 Agent 按需选择

<details>
<summary>展开工具注册、身份绑定与不同运行时的接法</summary>

使用默认 RP 上下文与 Pi Agent 时，可复用 `/pi` 包装器：

```ts
import { toPiTool } from '@flowgpt/agent-core-tools/pi';

const npcForAgent = toPiTool(npcTool, async (_args, call) => ({
  context: await loadAuthorizedNpcContext(call.signal),
  model,
  prompt: '检查人物连续性，明确区分事实与建议。',
}));
// 把 npcForAgent 加入本次 Agent options.initialState.tools。
// 主 Agent 的任务提示说明何时咨询它、收到建议后要完成什么。
```

`loadAuthorizedNpcContext` 是研发要实现的取资料函数：按已登录账号和当前聊天 ID，读取该用户有权查看的角色、对话与旧笔记。模型只提交 `reason/focus`，不能用工具参数改查另一个用户的记录。包装器把工具分析文本回传给主模型，程序侧还能拿到原始结果；主模型再决定下一动作或最终回答。

已有其他 Agent 框架时，按其工具协议封装同一个 `.execute` 即可。若用 SDK `SlowTurnRuntime`，通过自己的 `capabilities` 执行器适配，不能把 Pi 包装对象直接当成所有运行时通用格式；可参照 [快慢运行时完整示例](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/examples/sdk/07-fast-slow.ts#L18)。不同工具之间存在依赖时，先完成前一项，再把结果交给后一项。

原生 Pi 慢任务接法已随 #244 合入，并进入 SDK 0.5.0／0.6.0。宿主可以保留 Pi 自己的 Agent、消息和工具执行，并统一核算显式包裹的模型调用。它返回 Agent 消息与用量，业务仍要自己检查和保存结果，不会自动替换普通 V2 的后台。输入、预算、取消收尾和结果使用见 [原生 Pi 慢任务](#runtime-native-pi-candidate)。

**普通 V2 和现成前台循环的工具名单也要分别看。**给自己新建的 SDK Agent 注册工具，不会同时扩展普通 V2 的专家调度或前台 `actor/generate_image/schedule_dio/over` 菜单。扩展后两条应用链需要改对应接线，见 [Agent V2](product-agent-v2.md) 和 [前台工具](atoms-generation.md)。

[Pi 包装的参数检查与结果回传](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/packages/tools/src/pi.ts#L9) · [主 Agent 真实工具列表](https://github.com/FlowGPT/roleplay-harness/blob/a4f5bb83cdab7aed6113ffe4b6859378887c5d91/examples/sdk/03-agent-tools.ts#L28)

</details>

## 其他业务需求，接在哪一步

| 业务想加什么 | 已有入口及调用位置 | 返回之后必须接上的一步 |
| --- | --- | --- |
| 读取／更新自己的结构化记忆 | `/memory` 的 `get_memory`、`update_memory`，直接调用或提供给模型；后端先按登录账号和当前聊天选定要读写的记录，并提供存储函数及字段校验 | `update_memory` 调用内即提交完整对象，成功后返回新 revision；不要再额外写一次。下轮读回并交给模型，冲突或结果不明时先读回确认。应用默认 Hook、Axon 日记／表格、Hinos 是另一些接法，见 [记忆](atoms-memory.md) |
| 长对话自动压缩 | 仓内 `compact` 应用运行时与配置，生成前检查历史与预算 | 保存检查点并按真实历史锚点恢复；自己的外部聊天后端需要适配原文与存储，见 [Compact](atoms-compact.md) |
| 一次生成图片资产 | `/image` 公共工具＋图片后端，业务或自己的 Agent 调用 | 把任务归属、生成状态、最终资产与业务对象关联；处理失败／审核／展示，见 [图片](atoms-images.md) |
| 聊天分段配图与人物外观延续 | 仓内前台循环＋已接好的图片/视觉运行时 | 把图片回填到对应助手消息；视觉记录按聊天历史保存和恢复。它与单次资产工具是不同接线，见 [图片](atoms-images.md) |
| 长期修改角色说话风格 | 仓内 DIO 适配与 `schedule_dio` | 受理后查询完成状态，后续请求读取有效 Prompt；一次 accepted 不等于已生效，见 [长期指令](atoms-instructions.md) |
| 按事件推进剧情 | 采用完整 Story 产品流程，或独立使用 `/story` 六工具 | 独立接法要自己安排准备、正文采用、结算、保存及恢复。`storyV1` 选择的是产品运行流程，不是任意产品旁边附加一个工具，见 [Story](product-story.md) |
| 给用户提供下一句候选 | 已有 `auto_reply` 应用入口，指定要承接的角色回复；普通 V2 使用请求内目标正文，Story 要核对已保存的正式正文 | 前端展示，用户选择后再作为新消息发送；生成候选本身不推进剧情，见 [下一句建议](atoms-auto-reply.md) |
| 自己定义流程、工具与快慢协作 | 公共 `Agent` / `SlowTurnRuntime` / `FastSlowRuntime`，或仓内固定 Profile 流程 | 自己提供任务提示词、执行器、输入预算、采用和保存规则，见 [编排与扩展](atoms-runtime.md) |

## 联调时怎样确认真的加上了

用同一会话连续执行两轮，并保留请求 ID 与消息 ID，逐项检查：

1. **到达了正确接入点。**规则调用的步骤确实执行；模型选择模式下，工具实际出现在该模型的名单里，执行器收到真实参数。
2. **模型看到了需要的材料。**检查最终输入，例如守卫手令规则是否进入 Actor，商人分析是否收到已采用正文；不能只看“取资料成功”。
3. **结果到了使用者。**正文、建议、资产或状态分别交给对应消费者；工具回执没有被误当成给用户的最终结果。
4. **保存与读取闭合。**核对写入的对象、会话／消息归属、版本，再发下一句观察实际取回内容。无需持久化的世界书注入，不强行写成长期记忆。
5. **失败有明确结果。**至少覆盖工具返回失败、调用抛错、用户取消、重复请求，以及后一轮早于后台完成；检查是否错误宣称成功、重复写入或用了不属于当前分支的记录。

需要持久保存的业务，用自己的数据库或可靠任务系统落实。SDK 的进程内后台任务、模型文本、`completed` 状态、工具 `ok:true` 各自只说明相应阶段，不能相互替代。具体执行与状态采用规则见 [编排与扩展](atoms-runtime.md)。
