RRoleplay 产品与能力
查看本次更新巡检同步 · 10.19 14:51变更记录下载全文
完整产品
本章定位
完整产品 / 持续角色对话

Agent V2|持续角色对话与后台连续性维护

10/19 更新 · 本章 9 处从第一处开始看 →
用户发来消息后,程序读取角色资料和已保存笔记,分别准备前后台输入。Actor 生成回复,后台同时按需分析并决定是否更新笔记。新笔记通过检查后保存,后续请求读取当时已保存的版本。

回复和后台同时进行。下一句到来时,如果后台还没保存新笔记,回复模型仍使用当时读到的旧笔记。具体强制分析条件见下文。

可左右滑动查看 放大查看流程图 ↗下载 SVG

用户发来一句话后,Agent V2 一边生成角色回复,一边在后台检查人物关系、谁知道哪些事、剧情、承诺和当前场景。需要留到以后使用的信息会整理成笔记,保存后交给后续回复使用。它适合角色陪伴、角色扮演和开放式互动故事;故事的题材、人物和表达方式由角色资料及模型提示词决定。

本章介绍仓库中的普通 Agentic V2 应用。每轮回复时,后台模型会先判断需不需要进一步分析,再选择咨询哪些专家、是否更新笔记。六位专家各有分工,不会每轮全部运行。图片、世界书、日记记忆和 Story 剧情流程需要分别配置。

接入后,你的聊天后端先确认登录用户、当前角色和聊天会话,取出聊天记录,再把这些信息与本轮消息发给 Agent V2 服务。Agent V2 准备模型要读的材料、生成角色回复,并在后台整理笔记。聊天页面负责展示回复,聊天后端负责保存用户和角色的原文。下一句到来时,后端再次传入已保存的对话,Agent V2 再读取最新笔记,供这一轮回复使用。

研发需要先部署 apps/emochi 聊天服务,让它能从 Axon 读取角色、提示词配置和已保存的状态,并通过 Kaon 调用模型。角色资料决定“这个角色是谁”;各岗位的模型配置和提示词决定“哪个模型来做、按什么要求做”。这些资料和服务连接都要提前准备,单在聊天提示词里写“Agent V2”不会启用这套程序。应用依赖与装配 · 实际角色与状态读取

本次更新本章更新到 2026 年 10 月 19 日已完成的巡检,Harness 主线为 f9b26a9。这次为已接记忆的入口增加了故障选择:默认仍报错,研发可显式允许缺少本轮召回记忆继续回复;开启 Compact 的入口也修复了日记更新误使旧摘要失效的问题。六专家与 Director 的前后台分工保持不变。另有“完整回复后判断长期需求,再交 DIO 修改后续角色正文”的候选 #303,仍未合入,不能当作普通 V2 默认行为。

本次更新下文保留各段已核对的固定源码,Fusion 的状态锚点和并发恢复仍按分支版本说明。10 月 19 日有最新主线的 Sumi 生产部署记录,但未验证普通 V2 的运行镜像、有效配置和实际流量,不能由同一仓库镜像推断这些选项已经用于 Emochi。若所选入口启用了 storyV1,请求会改走 Story,不再启动本章的普通 V2 专家后台。应用装配与分流

先看一次真实机制下的两轮演示 #

下面用两轮对话说明材料怎样进入模型、结果怎样保存。台词和工具选择是为说明机制拟写的示例;程序必须调用工具的条件另列在后文。

角色卡描述“守卫莉娅谨慎,负责旧城城门”;已保存的历史记录说明“用户借了一把铜钥匙,答应天黑前归还”。目前仍在城门前。

时机 系统实际处理什么 本例可能得到的结果 谁接着使用
用户发送第 N 句 业务后端传来 我把铜钥匙递给莉娅,告诉她明早再来。、这段聊天原文和所选莉娅的角色 ID;仓库服务按 ID 读取角色资料、旧笔记及配置好的模型提示词 得到本轮回复所需的输入,以及另一份供后台判断的输入;不是让模型自己查找“用户指哪个莉娅” 回复模型和后台分别读取各自的材料
当前回复开始 Actor,即负责写正文的回复模型,读取已经准备好的角色、历史和旧状态 莉娅接过钥匙,指尖抚平铜环上的细痕。“明早城门初开时,我还在这里。” 通过流式输出交给聊天业务,由业务完成展示和消息保存
后台判断同时开始 Orchestrator,即负责决定请谁分析的后台模型,看本轮用户输入和此前材料 可能请求 manage_callbacks,理由是“钥匙归还及新的会面约定影响后续连续性” 程序解析工具名称和参数,启动对应专家模型
专家完成 承诺与伏笔专家根据已有材料分析,而不是直接改数据库 “用户已递出钥匙;此前归还承诺应核对;用户表达了明早再来,莉娅是否同意尚未在本轮初始材料中出现。” 回给 Orchestrator 第二阶段,也可成为 Director 的参考
后台决定需要保存 Orchestrator 选择 update_director_state;程序启动 Director,即整理持续笔记的模型 生成一整份新的状态草稿,保留此前事实,补充“用户递出钥匙、表示明早再来”等已被材料支持的信息 程序检查格式、长度与是否发生变化,再向存储服务提交
保存成功 存储服务接受带旧版本号的更新,返回新版本号 状态从版本 12 变成 13,并记录来源轮次、关联回复 ID、调用过的工具及专家分析账目 之后开始准备的对话请求可以读到版本 13
用户发送第 N+1 句 第二天,我又来到城门。;业务传回已保存的前轮正文,程序重新读取当前持续状态 Actor 同时看到“莉娅上一轮说她还在这里”的聊天原文,以及已保存的约定信息 可自然接着写莉娅认出用户,而不重新演一次初次相遇

Actor 开始写回复时,后台也已经拿着本轮开始时的材料工作。两边同时运行,所以后台此时知道“用户递出钥匙”,还没看到 Actor 随后写出的“莉娅接过钥匙、答应明早见面”。聊天后端保存并在下一次请求中传回这段正文后,后台才会读到它。程序虽然记录 Actor 是否完成,但这条记录只用于观察运行情况,不会把新正文补进已经启动的本次后台。轮初材料 · 前后台同时启动 · Actor 完成后的处理

如果用户很快发出下一句,版本 13 尚未保存,下一轮就先使用实际读到的旧版本 12,加上当时能取得的聊天历史。普通 V2 不会为了等上一轮后台而把下一句整体排队。

一轮内部怎样运转 #

1. 程序先确认这次请求应进入普通 V2 #

聊天后端提交本轮消息,以及会话、用户、角色和场景标识。服务先按场景标识查找已加载的配置。选中了 agenticV2,并由服务准备模型输入、执行回复的请求,才会启动本文的后台。请求中的 roleplay-harness/v2 表示扩展协议版本;配置中的 agenticV2 才规定正文和后台用哪些模型、允许多少工具调用。

这里的“场景”是服务配置的名称。例如研发为一个聊天入口维护 config/scenarios/<入口名>.json,在里面填写正文和后台的模型配置,服务启动时读取这个文件。聊天后端随后在每次请求的 extensions.scenario_id 中选择它。普通 V2 要启用 agenticV2、不启用 storyV1。这些字段由研发填写;用户是否能在页面上选择型号,由你的产品决定,与故事发生在城门还是档案馆无关。启动配置来源 · 请求选择配置

服务随后把三部分程序组合到回复流程中:状态适配器负责读取和保存笔记,Planner 运行后台分析,Coordinator 安排回复与后台何时开始。这些实现分布在 dispatch.ts、planning/runtime.ts、planning/agentic-v2.ts;查代码时需要沿这几个文件查看。场景校验 · 普通 V2 装配

2. 分别准备回复模型和后台的输入 #

回复模型和后台共用本轮开始时读到的剧情笔记。它由此前的 Director 整理,程序检查后才保存;专家分析记录也随成功的状态提交一起保存。本轮读回这些内容后,程序再分别准备 Actor 与后台需要的其他材料。如果上一轮后台还没保存完,读到的可能是更早的版本;首次没有记录时使用默认笔记。

用户原话和聊天历史随请求传来。服务用 promptId 从 Axon 读取角色名、简介、设定和开场白,再按账号、聊天会话和所选配置查询之前保存的笔记;第一次聊天还没有笔记时,程序使用默认内容。各模型的岗位提示词则从对应 ModelConfig 关联的 PromptManager 中读取。这里 promptId 指向“莉娅这份角色资料”,ModelConfig 指向模型及其参数,研发需要分别准备。

材料 Actor:本轮写正文 Orchestrator/专家/Director:后台
角色是谁 按 Actor 的 ModelConfig/PromptManager 展开角色变量和模板 角色名、简介、定义;专家与 Director 还会收到角色开场白
用户这次说什么 本轮输入作为回复材料 独立列出的 LATEST USER QUERY
聊过什么 按 Actor 模板中的历史插入规则与上下文预算保留消息 编译器只抽取最近 9 条非空 user/assistant 消息;不是 9 轮
此前保存的剧情笔记(Director 整理)及专家分析记录 程序在本轮开始时读回已保存版本,把笔记与选中的分析记录加入系统消息 使用同一个已读回版本,整理成后台输入文字;常规上限为 6,500 字符
用户 Persona 如果接入和模板提供,则参与回复材料 从组装结果取得有效 Persona,截取至 4,000 字符;明确告诉模型这是用户身份,不是角色或 NPC 身份
本轮选中的世界书 普通 V2 场景显式配置 worldbook 后,以当前 promptId 作为 entity_id 逐轮解析绑定、选出条目并按位置注入 Actor;不再限定专用 Worldbook 场景 当前后台材料构造没有复制本轮世界书条目;专家名叫“知识审计”也不代表自动有世界书检索权限
日记摘要、记忆表、外部 Hook 补充内容 取决于所选记忆来源、Hook 和模板是否接入 不会自动复制 Actor 的全部模板变量;不能仅凭 Actor 看到它,就认为后台也看到了
Compact 压缩摘要 默认同步准备新摘要;显式后台模式获准时,本轮用已有摘要/原文,后台新摘要成功保存后供后续请求用 contextGovernance.mode=enforce 时使用本轮实际返回的保留历史和摘要;后台压缩未完成时不会凭空拿到新摘要。shadow 仅作对照,后台仍取原请求历史
本轮专家结果 不会自动追加入已经发出的本轮 Actor 请求 第二阶段 Orchestrator 和 Director 可读取
本轮新生成正文 Actor 自己生成 本次后台初始快照不含该正文,之后也不会自动补入

例如 Axon 返回“阿宁,初到灰港的信使”,普通 V2 的程序已将非空 axon.userPersona 放进后台输入,模型用它解释用户身份;它不等于“守卫已经认识阿宁”,也不能仅凭这段人设把关系写成已发生事实。这是已经接通的普通 V2 路径。Story 工具虽也支持可选 Persona,现成 StoryV1 协调器还没有传入,不能从这里推断两套产品采用相同。普通 V2 实际传入 Persona · Story 的采用缺口

上述字符数是应用主动截取的材料长度,不等于模型的 token 窗口。后台历史与输入 · 专家输入 · 前台模板和预算来源

如果配置了 worldbook,服务每轮会核验会话身份,查询这段聊天绑定了哪些世界书,再选择条目。同一轮模型重试时复用这次结果,下一轮重新查询。没有配置,或查询发现没有绑定时,就沿用原来的历史和预算处理,不再选条目。选出的原文只按当前接法进入回复模型,不会自动写进聊天历史、V2 笔记、日记或后台专家的输入。当前入口与空绑定分支 · 接入参数及完整链路

本次新增读取日记等外部记忆失败时,默认在进入生成前就停止;为该入口显式设置 failurePolicy.memoryRecall:"continue_without_memory" 后,符合条件时可以少带这份记忆继续。它不改变 Director 笔记的读写规则,也不保证角色仍能答出缺失的旧事。普通来源在正文成功后仍尝试原有写入;Hinos 若因 prepare 故障而没有取得本轮 claim,则跳过该轮 commit。完整配置位置和不能放过的错误见记忆服务失败时的选择。

3. Actor 写回复时,后台先判断要不要调用工具 #

普通 V2 每次进入 generate(),都会为这一逻辑轮安排一次后台,协调器会避免同一轮重复启动。它不需要累计 X 轮;如果准备材料时就失败、还没进入生成,后台也不会启动。自动回复建议使用另一入口,不按这条普通 RP 生成规则计算。

后台先把岗位提示词、上表中的材料和可用工具说明发给 Orchestrator。请求中的 toolChoice: auto 允许模型决定是否调用工具,也允许一次选择多个工具。例如它可能返回:

{
  "name": "manage_callbacks",
  "arguments": {
    "reason": "用户递还借用物品并提出新的会面约定",
    "focus": "区分已经发生的递出动作、待确认的接收动作和新的承诺"
  }
}

示例只展示工具名和参数;真实模型消息放在 tool_calls 中,function.arguments 是 JSON 字符串。程序解析后,按工具名找到已经注册的执行代码,再调用对应专家模型。这里执行的是程序已有的工具,模型没有直接运行脚本或访问数据库。

普通 V2 注册表固定装配六位专家与 update_director_state;场景 enabledTools 从这七个名字中选择。它没有在这条后台默认装上生图、世界书查找、独立 NPC 卡保存、任意 HTTP 请求等工具。公共 SDK 能扩展 Registry,不等于普通 V2 的场景 JSON 可以直接填任意新工具名。工具注册 · 模型请求 · 参数解析与执行

4. 程序有少量强制分析规则 #

情况 程序做什么 生效条件与限制
首轮 补上人物审查 judge_npc 和场面指导 direct_scene 对应工具必须存在于 enabledTools;目的是逐个识别人和建立场面尺度
近期出现旧状态未记载的名字 补上 judge_npc 从最近 4 条可见消息和本轮问题,用多语言规则识别候选名字,再检查旧状态;这不是能识别所有新人物的语义模型
上述强制专家被安排过 第二阶段补上 update_director_state 状态工具必须启用,仍需通过后续模型调用、内容校验和保存检查
其他普通继续聊天 由 Orchestrator 决定是否需要专家或状态更新 不调用专家、不更新状态都是正常分支

因此“每轮后台都会跑”不等于“每轮六位专家都会跑”,也不等于“每轮都保存一个新状态”。强制规则与名字识别 · 第二阶段补状态调用

5. 六位专家究竟分别做什么 #

每位专家本质上是一次带有专门提示词的文本模型调用,使用该岗位配置的 ModelConfig。它先返回分析建议,是否保存要等后续处理。下表用示例说明建议的内容;这些句子不是固定 JSON 字段。

工具与岗位 解决什么问题 本例或相近场景的建议结果 不能把它理解成什么
analyze_plot 剧情分析 现在是否需要改变可选主线、当前情节或故事方向 “用户只想归还钥匙,本轮结束借物情节;明早可以留一个低压力的相遇机会。” 不是强制执行十几轮完整剧本,也不是 Story 产品的世界事件调度器
judge_npc 人物审查 谁是谁、几个人、动机、知道什么、在哪、如何进入或离开 “新出现的商人艾登是一名独立人物;与莉娅的关系尚未建立,不应当作旧友。” 不是一个直接创建独立角色卡并保存的 NPC 服务
audit_knowledge 知识审计 事实、猜测、谎言、秘密与证据分别被谁知道 “用户只说钥匙归还,莉娅没有依据知道用户昨晚去过地下室。” 不会因名称含知识而自动搜索世界书或联网
simulate_world 世界时间与场外生活分析 经过了多少时间、位置是否合理、日程和期限如何变化 “用户明确说第二天,时间可推进;莉娅是否仍值守需要结合已建立班次。” 不是自动把世界书设定或世界数据库全面修改
manage_callbacks 承诺、物品与伏笔管理 哪些约定、线索、物品、伤势、义务和后果尚未处理 “核对铜钥匙归还状态;保留用户说明早再来的意向。” 不意味着伏笔必须立即兑现,也不直接更新物品表
direct_scene 场面指导 视角与描写重心怎样分配,角色允许主动做多少事 “以莉娅反应和城门环境为主;她可以提出一个话题,不替用户决定留下。” 不是后面写完整持续状态的 Director;这是六位专家之一

所有成功专家先返回 { ok: true, tool, result, usage? };result 是分析文本。常规模式最多保留 5,000 字符。开启严格上下文治理后,结果超出配置长度会成为失败结果,不静默截成一份貌似完整的建议。工具职责与 schema · 模型执行与结果限制

6. 第二阶段决定是否把建议变成持续状态 #

已选中的专家并行执行。程序把工具调用与结果重新交给 Orchestrator;这一阶段只提供 update_director_state 一个工具,模型选择更新或结束。这是看完分析后的再次决策,并没有无限的“再叫专家、再分析”循环。

如果第一阶段没有咨询专家,但直接请求了状态更新,程序可以直接运行 Director,省略第二阶段;如果什么都不需要,保留旧状态。如果第一阶段同时请求专家和 Director,Director 被延后,不能在还没得到专家建议时与专家一起写状态。第一阶段执行和第二阶段工具范围 · 延后 Director 的消息

7. Director 生成整份笔记,程序校验后保存 #

Director 会读角色资料与开场白、用户 Persona、旧状态、近期历史、本轮输入、更新理由,以及已经完成的专家分析。然后它重新写出整份笔记,格式名叫 Agentic RP State。程序用这份完整文本替换旧笔记;用户看到的角色回复由 Actor 另行生成。

这份持续笔记包含固定栏目:当前场景、角色生活与近期目标、柔性主线、未来发展备选、人物关系和代词归属、知识边界、位置与进入限制、新人物安排、时间与场外生活、待兑现承诺与物品、场面重心、角色主动程度、必须保持的事实、用户拒绝过的方向等。它允许提出后续方向,但这些方向不是已经发生的故事事实,也不是必须照做的工作流。

保存前,程序检查新笔记是否为空、是否至少 500 字符、是否超过配置上限(最多 8,000 字符)、栏目及顺序是否正确、是否混入内部推理标签,再比较它与旧笔记有没有变化。Director 的提示词要求保留原有事实,只记录有材料支持的变化;不过,程序这里只检查文本结构和能否写入,没有另请一个模型逐条复核事实是否正确。Director 输入与输出要求 · 程序校验

保存什么、何时保存、下次取回什么 #

聊天后端通过流式事件和最终结果收到角色正文,再决定展示、保存哪份文字。后台则独立处理专家分析,需要时把它们整理成笔记并提交 Axon,不会把六份分析直接发给用户。正文已经生成完,笔记仍可能没保存;页面若要显示“记忆已更新”,需要检查状态版本或后台提交记录,角色说“我记住了”不能作为保存成功的依据。

数据 什么时候产生或保存 保存/读取通道 实际用途
用户与角色聊天原文 由聊天业务在自己的消息生命周期中保存 Chat Service 的消息系统;后续请求传入历史 让下一轮知道实际说过什么,包括 Actor 本轮新写的内容
Agentic RP State Director 给出有效、与旧状态不同的候选,且存储检查通过时 Axon roleplay.state.compare_and_set 后续轮初通过 roleplay.state.get 取回,加入 Actor 与后台输入
专家分析账目 ledger 与成功状态提交一起写入;不是专家一完成就单独保存 同一状态提交携带 ledgerEntries 保留该轮分析、来源工具和用户问题;之后只选有限的活动账目投影到上下文
已调用工具与来源 状态提交时 toolsCalled、sourceTurn、sourceMessageId、historyRevision 识别状态来自哪个轮次和回复,协助版本检查和追踪
调试节点与完成状态 各阶段异步、尽力记录 markPlanning、markDebugNode、markProcessed 观察走到哪、为什么没有更新;不是持久业务状态的替代品

程序按用户、会话和场景查找同一份持续状态。提交新笔记时,它会同时告诉存储服务“这次是在版本 12 上修改的”。如果存储中已经有更新版本,Axon 返回冲突,本次 Planner 记录 stale_write_rejected,不再自动改用新版本重写。这个仓库能看到的是对 Axon 的调用;数据库表、事务和多个服务实例之间如何协调,需要查看 Axon 实现才能确认。状态读取与提交适配器 · RPC 字段

下一轮取回的是已经保存的版本号、笔记文本和分析账目。应用内部得到的数据如下;其中 state 只节选两行,实际保存时必须包含 Director 要求的完整栏目:

{
  "found": true,
  "revision": 13,
  "sourceTurn": 8,
  "sourceMessageId": "assistant-turn-8",
  "historyRevision": 16,
  "state": "[Agentic RP State]\nCurrent scene: 旧城城门;用户已递出铜钥匙,表示明早再来。\nOpen callbacks, promises, items, injuries, and deadlines: 核对钥匙交接;用户表达了明早再来的意向。",
  "toolsCalled": ["manage_callbacks", "update_director_state"],
  "ledger": [
    {
      "type": "callback",
      "key": "manage_callbacks:turn:8",
      "status": "active",
      "payload": {
        "analysis": "区分用户递出、对方接收与双方同意会面,不能把未看到的回应补成事实。",
        "sourceTool": "manage_callbacks",
        "sourceTurn": 8,
        "userQuery": "我把铜钥匙递给莉娅,告诉她明早再来。"
      },
      "sourceTool": "manage_callbacks",
      "sourceTurn": 8
    }
  ]
}

程序从这个对象中取出 state 和选中的分析账目,整理成文字后放进模型消息。Actor 这部分材料最多取 maxStateChars + 2000 字符,后台常规调用最多取 6,500 字符,之后还要分别检查是否符合各自模型的输入预算。

分析账目按 event / npc / knowledge / world / callback / camera / agency 分类。下轮准备输入时,程序先选最近 60 个活动项,再从每类中最多取 6 条,每条最多 900 字符,最后按总字符上限裁切。账目与状态一起提交:专家即使成功返回,只要 Director 没执行、新笔记没变化或无效、提交发生冲突,这些分析就没有沿这次提交成为下轮可读的资料。账目形成 · 读回时的账目选择

首次没有状态时,程序先用一份默认笔记,要求模型从角色开场和可见对话继续,保留用户的决定权,不凭空确定尚未出现的人物、秘密和场外事件。这份默认内容此时只用于生成,之后完成有效提交才会写入存储。初始状态

PR #209 已合入 fusion-harness 的固定版本 c75dabb942bcf5ab00e2cadbabd95ef961203e69,让同一条助手回复追加新段落后仍能读取其关联的后台笔记。快照不再绑定保存当时整段助手正文的 hash,仍核对消息 ID、场景、状态引用和用户锚点,读取时也核对数据库正文与当前可见正文一致。因此聊天服务在编辑、重新生成时必须分配新的消息 ID;若直接替换正文却沿用原 ID,就可能读取改写前的笔记。这项修复仍属于 Fusion,不能作为普通 main V2 的默认保证。9 月 24 日已取得包含该读取实现的 Fusion 后续版本 c8fc61c 的生产 rollout 记录;实际编辑/重新生成时的消息 ID 规则仍需业务验证。后续分支实现 · 后续部署 · 状态读取检查 · 保存锚点与外部合同 · 同一条回复续写后的笔记读取

模型开始工作前,系统到底给了什么提示词 #

服务会从 Axon 获取各 ModelConfig 关联的 PromptManager,再按岗位名读取模板。因此要看一个环境实际用了什么提示词,需要查那个环境的配置,Planner 文件里没有一条覆盖所有角色的固定 system prompt。

模型岗位 提示词来源 程序另加的业务材料
Actor 本轮有效 Actor ModelConfig 的 PromptManager/Preset;按各 prompt 的角色和顺序展开 角色、用户、历史、接入的记忆/世界书、V2 持续状态
Orchestrator orchestrator 命名模板;升级模型可以有自己的版本 轮次、旧状态版本、角色、Persona、近期对话、本轮输入;结尾明确允许普通继续聊天不选工具
六位专家 specialist_analyze_plot 等六个命名模板,各自从配置的 ModelConfig 读取 岗位共有材料加 reason/focus
Director director 命名模板;加载时必须含明确的状态开头与栏目 旧状态、角色、历史、问题、更新理由、专家结果;要求生成完整替换文本

调用模型前,程序展开语言、角色等模板变量,把岗位系统提示词、用户和角色的材料、本阶段工具定义一起发出。源码能确认这个组装过程,但测试中的假提示词、旧 Demo 模板和工具介绍都不能代替生产配置;完整原文仍需从目标环境的 ModelConfig/PromptManager 读取。模板加载与岗位名称 · 后台首条业务材料

可配置什么,默认值意味着什么 #

产品确定需要的能力、等待时间和成本额度后,研发修改两处设置:Scenario JSON 规定这一入口怎样运行,ModelConfig/PromptManager 规定各岗位的模型参数和提示词。服务启动后按这些设置安排前后台,Orchestrator 再逐轮选择需要的专家,运营不必手动点选。下表是代码在未填写对应值时采用的默认设置,具体部署可以覆盖它们。

配置 默认/范围 开启或修改以后
agenticV2 缺省不启用;内部 enabled:false 也不启用 装配本文的后台;普通模式需不启用 storyV1
本次新增入口顶层 failurePolicy.memoryRecall 默认 fail_turn;可选 continue_without_memory 记忆读取失败时是否允许缺少召回材料继续。普通来源与 Hinos 的故障范围、后续写入规则不同;取消、Actor/Axon 失败不靠它放过
modelConfigs.actor 必填,并必须等于该场景 modelConfigRef 选择写正文的模型配置;同时需要有效 PromptManager/Preset
modelConfigs.orchestrator、specialists、director 均需提供引用;六位专家分别配置 可以替换不同岗位模型及其 prompt;即使限制 enabledTools,当前加载仍要求六专家配置与模板齐全
enabledTools 默认六专家 + update_director_state 限制 Orchestrator 可选工具;只能填当前七个名字。删掉 Director 后,专家咨询结果不会沿本文流程写成新状态
routingMode manual 指固定编排模型,不是人工手动点选工具;auto 在达到阈值时可换升级模型重新作选择
escalationToolCallThreshold 3;可配 1–20 自动路由时模型请求工具数达到阈值会触发升级;需同时设置 escalationModelConfigId
maxToolCalls 7;可配 1–20 参与第一阶段的选取预算;第一阶段实际执行上限同时受并行上限控制,Director 在后续独立处理。不能把 7 理解成整轮最多只有 7 次模型请求
maxParallelTools 6;可配 1–20 限制第一阶段并行专家选择;模型重试、编排判断和 Director 不等于这六个并行名额
maxStateChars 8,000;可配 800–8,000 限制完整持续状态候选长度;不是聊天历史长度或模型窗口大小
modelCallTimeoutMs 180,000 ms;可配 10,000–300,000 后台单次模型调用超时;不是用户一定要等待三分钟,也不是整个后台统一三分钟截止
contextGovernance 缺省不启用 shadow 记录预算对照;enforce 严格约束并要求配置 Compact。V2 与 Compact 同时配置时必须显式指定该项
contextGovernance.safetyMarginTokens 开启治理时默认 256;可配 1–8,192 在模型可用预算内预留空间
contextGovernance.maxToolResultChars 开启治理时默认 5,000;可配 512–20,000 控制专家结果大小;严格模式过长则按失败结果处理
jevOrchestration.argumentModelConfigId 缺省不用 Jev 可把两阶段工具选择交给 Jev 决策端点;专家和 Director 仍用文本模型,工具自由文本参数由指定文本模型补全
recovery.transientRetryModelConfigId 可选;未填不启用专用恢复 指定允许的备用 DeepSeek ModelConfig;未发正文时可重新生成一次,首次 Gemini 已发部分正文但未完成时可在满足预算等条件后续写一次。每次 Actor 生成最多主模型与一次备用,不叠加普通 retryCount;即时流式主尝试有下文的输出缓冲
recovery.tolerateMissingStreamMetadata 仅显式 true 时启用 容许特定缺失流元信息情形;不是忽略一切模型错误
modelConfigs.autoReply、autoReplyWaitMs AutoReply 模型可选;等待默认 30,000 ms,范围 0–120,000 供自动回复建议的独立请求使用,不是控制普通后台每隔多少轮触发

配置解析还要求自动路由有升级模型;Jev 的参数模型不能填写 Orchestrator/升级 Orchestrator 的配置;Actor 引用要与场景一致。这些不匹配会在配置解析或依赖就绪检查时失败。默认值 · 配置范围与校验 · V2 与 Compact 组合条件

仓库部分 JSON 还留着 actorControlEnabled,但这版 AgenticV2Config 和解析返回值没有使用它,修改它不会关闭后台控制。让前台模型选择写正文、配图或提交长期修改任务的开关是 preActorDirector,控制的是另一套工具循环,详见对应原子能力。实际解析返回值 · 独立前台循环接线

上下文窗口能不能改 #

可以改,但不在 maxStateChars 上改。Actor 的窗口上限来自有效 ModelConfig 的 context_limit,或服务接受的 runtime_decision.context_limit;模型的输出预算来自生成参数。历史实际保留多少还受 PromptManager 的历史插入规则、Compact 和最终预算计算影响。旧路径会保留系统消息,按剩余空间从较近消息向前选择;严格治理路径在最终请求上计数和检查。

后台仍按自己的规则取最近 9 条可见消息,并限制状态材料和专家结果的长度。调大 Actor 的窗口不会改变这些规则。如果希望后台读到更长的材料,研发还要修改对应的输入编译代码,或使用已经实现的 Compact 严格模式;单换一个长上下文模型不会自动传入全部历史。Actor 窗口来源 · 旧 V2 补状态与滑动历史

9 月 22 日增加了世界书参与回复时的重试预算检查。Actor 每次进入前台循环或换模型重试,都重新展开输入,按目标模型的窗口计数。空间不足时,只能裁掉最老的历史;角色固定提示、本轮输入、世界书、Story 等不可压缩材料,以及续写边界、循环控制和累计正文都保留。仍放不下就放弃这个目标模型;普通重试队列还有目标时再试,而且会重新从原材料计算,不沿用上次失败时裁短的历史。这项检查不改变普通后台每轮安排一次的规则。重渲染与受保护材料 · 目标窗口检查及重试处理

开启 Compact 的入口现在可以设置 compact.scheduling:"async_preferred" 和明确可靠性额度:当前材料仍能放下时,先安排后台压缩,本轮继续用旧摘要与原文;新摘要保存后才供后续请求读取。硬超限默认同步处理,显式 asyncOverflowPolicy:"trim_history" 则可在严格条件下临时少带旧原文。这条摘要任务与普通 V2 的专家/Director 后台互相独立,开启其中一个不会自动开启另一个。

有界压缩还会优先给摘要预留空间,真实摘要过大时尝试继续总结额外闭合历史。角色定义本身仍占满窗口时,显式 compact.rolePromptFallback 可以最后尝试压短本轮角色字段,采用前再次计数;不修改原角色卡,也不保证所有超长输入都能恢复。完整启用字段、保存时机和失败条件见 Compact。后台准入和本轮返回 · 角色卡兜底

10 月 12 日的 #295 修的是这条角色精简路径中的误拦。例如原文使用合格本地计数,压短后恢复原生计数,程序现在分别检查两次是否合格,不再要求来源完全一样。最终 Actor 输入仍必须严格计数、放得下且比原输入更短。只有精简模型自己开始生成前的预检可以使用符合元数据要求的未验证估算;最终 Actor 请求不能用这项估算放行。修复没有默认打开 compact.rolePromptFallback,成功也只影响当前回复,不新写角色卡或摘要。角色精简的完整条件 · 最终 Actor 采用检查

本次新增10 月 14 日的 #302 又区分了“最新日记”和“判断旧摘要是否兼容的角色开场白”。例如日记从“答应还钥匙”变成“已经归还”,本轮仍读新日记,但不再仅因此作废旧历史摘要。真正的角色背景、开场白、配置或历史改变仍触发原检查;角色来源没核实时,不使用不可靠资料改写旧检查点。后台也要比较本轮完整输入,不能因旧摘要仍可用,就拿仍在运行的旧日记任务当作相同输入。日记变化与摘要复用

回复什么时候开始显示,早期拒答怎样处理 #

假设用户刚看到“莉娅接过钥匙,低头看了看——”,Gemini 连接便中断。配置 recovery.transientRetryModelConfigId 后,当前 main 可以在符合条件时保留这段文字,再请 DeepSeek 续写一次;如果还没有发出任何正文,则丢弃未发片段,改为一次完整重生成。这些处理只属于 Actor,不会额外启动一轮专家后台,也不表示聊天消息或后台状态已经保存。

主模型原本能即时流式输出时,程序先暂存正文,到正常完成或首个非空片段到达满 4 秒时释放,以先到者为准。完全空响应在结束时直接进入 router.empty_response 判断,不另等 4 秒。有整段后处理的调用沿用原有缓冲;未配置专用恢复的场景也不增加这段等待。4 秒是源码常量,从首个正文片段到达起算,不能当作整个请求的首字延迟或超时。缓冲条件

实际情况 这次回复怎样处理 必须满足的条件或失败结果
主模型正常完成,缓冲尚未到 4 秒 释放完整正文,再走正常后处理 不必等满 4 秒
尚未发出可见正文,出现空响应或符合资格的上游失败 丢弃未发片段,由备用 ModelConfig 重新生成一次 Gemini 按 Kaon 上游错误来源判断,涵盖 HTTP/SSE/Google error envelope;其他模型仍按内容过滤、空响应及 429/500/503 等既有规则
首次 Gemini 已发可见正文,在可信完成前中断 原输入加已有 assistant prefix,改用 deepseek-beta/deepseek-v4-flash 接着写一次 已配恢复;实际模型未被参数另行覆写;没有 finish reason 或已完成标志;未取消;纯文本输入可计数,剩余额度与备用窗口足够
已正常结束后才报错,或不符合续写条件 返回失败,不补一次无条件续写 可见片段不能代替完整成功结果
备用重生成/续写失败,或续写未增加可见正文 本次 Actor 生成最终失败 不再叠加普通 retryCount,也不递归切换第三次
用户取消或相应生成超时 中止本次生成 普通后台仍按自己的任务生命周期处理,正文恢复不会替它续跑

程序排除本地校验/预算错误、已恢复过的错误和 DeepSeek Flash/0731 自身再次恢复;不会把普通角色台词中的“我不能”猜成供应商拒答。重新生成只允许配置的 kaon/deepseek-v4-flash 或 kaon/deepseek-v4-flash-0731。续写另使用 beta 路由,但参数、计数 profile 和窗口仍来自这个备用 ModelConfig。原输出额度要先扣除 Gemini 已消耗的正文及可计量 reasoning;原输入加前缀放不下、计数失败或预算耗尽时直接失败。两次请求沿用同一个正文过滤器与后缀保护,用量合并;缺用量时可记录观察文本的估算,任一次 cost 未知就不把小计冒充完整账单。主干恢复资格 · 续写条件、预算与结果

旧式流实际收到 [DONE] 且满足既有兼容设置时,仍可接受缺 finish reason 的完成流,不会一律触发续写;显式 tolerateMissingStreamMetadata 也只在 DONE、有正文且事件可靠时推断 stop。DeepSeek 续写关闭宽松兼容,要求可靠结束。这些机制已有受控测试;真实两模型语气、接缝重复、时延和费用,以及当前 workload 的启用情况仍未确认。每次 Actor 调用最多主模型与一次备用;前台循环如果多次调用 Actor,不能把“两次”当作整轮所有模型的总数。DONE 兼容 · 完整恢复合同

Fusion 的恢复参数为什么不能直接照搬 #

Fusion 固定分支 c75dabb942bcf5ab00e2cadbabd95ef961203e69 的 agentic-v2-luna 方案另配 hedgeDelayMs:5000 和 retryOnAnyUpstreamError:true。前者让慢主请求与备用请求并行,先取得可用结果的一方获胜并取消另一方;后者缺省为 false,开启后扩大符合来源条件的上游错误与超时恢复,并排除 router.content_filter。main 43332d8 不接受这两个字段;main 对 Gemini 的恢复使用上表的错误来源规则,复制 Fusion 配置会在解析阶段失败。Fusion 的具体配置 · Fusion 错误条件 · main 接受的字段

Fusion 的 Narrative incremental 入口还会在执行前开始 20 秒正文等待计时,只有新的 actor_text 重置;planner 活动不会延长它。正文完成后关闭文字流,再做图片准备;图片准备失败独立处理相关 pending 图片。生成失败仅在 generating/reserved 阶段自动回滚。这个计时器不属于普通 main V2 或 Story;当前还缺真实误杀率、败方取消前费用和运行 digest 证据。后续巡检已取得包含这些实现的 Fusion c8fc61c 在 9 月 24 日 03:16–03:19 的生产 rollout 记录;同次版本还包含 DIO 免计费请求标记,实际费用见 DIO 分支说明。计时与正文完成 · Fusion 完整失败和成本边界

怎么接入这个完整产品 #

普通 V2 的完整实现位于 apps/emochi,通过 Agent Router 服务接收请求。研发需要运行这套应用;公共 SDK 没有提供一个可直接创建完整产品的 createAgentV2()。

请求从你的聊天后端发出,Agent Router 按请求选中的配置进入 Harness 应用。应用从 Axon 读取资料和状态,通过 Kaon 调用模型,再把流式事件与最终结果返回聊天后端。你的系统继续处理用户权限、额度、消息保存、展示、计费和通知;模型输入的准备与 V2 笔记处理由这套应用完成。

接入要准备的数据和服务 #

下列 ID 来自业务实际记录,user-42 / conversation-8 / lia-character 仅为教学例值。ID 帮程序找到资料,角色设定和聊天内容本身仍要能取到。

需要准备 谁提供、实际上是什么 缺少时会怎样
turn_context.user_id 登录/业务后端给账号 ID,例如 user-42;不是故事里的玩家名 无法按账号查询对应资料,也无法确认这份聊天笔记属于哪个用户
conversationId、promptId 聊天业务给当前聊天 conversation-8 与所选角色资源 lia-character;后者用来读“莉娅谨慎、负责城门”等实际文字 角色或会话查询无法正常执行;只有一个名字不能代替真实记录
requestId 业务为这次生成分配追踪 ID,例如 rp-turn-101 不能正确关联这次模型、工具与保存调用
turn_context.input_question、messages 业务传本轮“我把铜钥匙递给莉娅……”及当前聊天路径上已保留的 user/assistant 原文和消息 ID 服务不能还原未传回的对话;重生成后传错历史会把错误内容当材料
turn_context.assistant_message_id 业务提前分配这轮将保存的助手消息 ID,例如 assistant-101;服务用它记录后台来源 普通 V2 prepare 明确报错,不能省略。ID 已分配也不代表正文已落库
extensions.scenario_id、turn_context.model_alias 与语言 后端选择已加载的普通 V2 方案;提供有效业务模型别名与如 language:"zh" 的请求语言 未注册方案、缺少必需别名等会失败;不是模型自己猜应采用哪份配置
Actor、Orchestrator、六专家、Director 的 ModelConfig 和 PromptManager 研发在接入环境准备各岗位模型引用与实际提示词;角色资料仍是另一份数据 模型配置、岗位模板或 provider 不合要求时失败
Axon 研发连接资料/状态接口:角色卡、角色 Prompt、模板变量、对话长度、状态读取与条件保存 完整应用当前不能脱离这些依赖直接运行
Kaon 模型服务与凭证 研发连接真正执行文字推理的服务,凭证在服务端配置 没有可用路由就不能生成
聊天消息保存与下一轮历史读取 业务后端保存真正采用的正文;下一句将它连同原消息 ID 传回来 V2 状态不能代替完整聊天记录,下一轮可能不知道角色刚才说了什么
后台任务生命周期与关停处理 研发部署的进程内任务执行器应允许后台正常完成或处理关停 普通进程内 runner 不是可在重启后自动恢复的持久任务队列

请求身份到应用字段 · V2 所需回复身份与材料

研发可以把下面这段服务配置放进 config/scenarios/<入口名>.json,或已有 AGENT_ROUTER_SCENARIOS_JSON 中对应入口的对象。填写前要先创建实际的 ModelConfig,再替换占位值,并补齐服务要求的其他配置。modelConfigRef 与 agenticV2.modelConfigs.actor 必须引用同一个正文模型配置;presetRef 引用回复模板,角色资源 ID 则是前文的 lia-character。这段由服务读取,不是公共 SDK 的 options:

{
  "upstreamModel": "<该场景允许的模型路由>",
  "defaultTimeoutMs": 580000,
  "modelConfigRef": "<actor-model-config>",
  "presetRef": "<actor-preset>",
  "agenticV2": {
    "modelConfigs": {
      "actor": "<actor-model-config>",
      "orchestrator": "<orchestrator-model-config>",
      "specialists": {
        "analyze_plot": "<plot-model-config>",
        "judge_npc": "<npc-model-config>",
        "audit_knowledge": "<knowledge-model-config>",
        "simulate_world": "<world-model-config>",
        "manage_callbacks": "<callback-model-config>",
        "direct_scene": "<scene-model-config>"
      },
      "director": "<director-model-config>"
    }
  }
}

聊天后端发请求时,再把下面的扩展字段放进 Agent Router 请求。外层仍须提供协议要求的项目、版本、会话、角色、消息及 generation.n=1 等字段,下面只展示扩展部分:

{
  "extensions_version": "roleplay-harness/v2",
  "extensions": {
    "scenario_id": "<服务端已启用的普通-v2-场景>",
    "turn_context": {
      "user_id": "user-example",
      "model_alias": "<业务侧有效模型别名>",
      "assistant_message_id": "assistant-next-message",
      "language": "zh",
      "input_question": "我把铜钥匙递给莉娅,告诉她明早再来。"
    }
  }
}

服务按 ConnectRPC AgentService/Agent Router 协议解析这些字段。普通 OpenAI /chat/completions 不识别这套产品配置,请使用对应的服务协议发送请求。请求扩展解析 · 完整服务接入说明

研发还要在部署参数 HARNESS_ENABLED_SCENARIOS 中选中这个文件;如果文件不在默认目录,用 HARNESS_SCENARIOS_DIR 指定目录。服务在启动时读取配置,不会每次请求重新读文件。旧配置表 AGENT_ROUTER_SCENARIOS_JSON 仍可使用,同名时会整项覆盖文件定义。聊天后端发送的 extensions.scenario_id 必须对应服务已经加载的入口,请求才会进入这套 V2。场景启用与合并规则 · 当前实际加载器

失败、取消和并发时会发生什么 #

本次更新模型调用失败时,10 月 13 日合入的 #298 可以在日志里保留已识别的 TLS、DNS、连接、socket 或超时错误码,帮助研发定位底层原因。它不改变原来的重试次数、HTTP 错误分类和取消优先级,也不代表模型服务已经恢复;最新 Sumi 镜像已包含相关代码,普通 V2 的实际部署与采用仍未独立验证。连接错误具体怎样记录

情况 当前行为 对业务接入的含义
本次新增外部记忆召回失败 默认停止本轮;显式允许继续时按对应运行时规则用空记忆或已准备材料继续,记录降级 本轮缺少召回记忆;Hinos 配置/鉴权/协议错误仍失败,普通来源与 Hinos 的后续写入不能混为一谈
Orchestrator 决定不用工具 本次后台结束,旧状态保留 正常的成本控制分支,不是漏跑后台
某位专家失败 返回失败结果,其他并行专家仍可完成;结果交给后续阶段 后续模型可能仍决定更新,不能把“有一位专家失败”说成整轮必定回滚
Director 输出不合法 有限重试后仍失败则拒绝该候选,旧状态保留 文本回复可以已经成功;观察后台 outcome 才知道状态是否更新
Director 输出与原状态相同 不创建新版本 后台执行过不代表写库过
状态提交发现旧版本过时 本次结果记为 stale_write_rejected 不覆盖新状态,也不在这次后台自动换材料重跑
保存请求失败但是否写入不明确 有限重试;若后续出现冲突,会读回并对版本、来源回复 ID、状态全文核对是否其实已经成功 处理不明确结果,不能简单把重试次数当成功次数
用户取消/Actor 报错 已安排的后台没有绑定 Actor 请求取消信号,仍可能完成并尝试保存 若业务要求“正文已接受才允许状态生效”,需要额外接入接受机制;普通后台本身没有这个保证
下一句到来时上一轮后台仍运行 可以并发,以各自轮初材料工作 下一轮可能先用旧状态;不存在必然在下一句前完成的 SLA
进程退出 runner 依赖进程内任务与关停信号 不承诺重启后自动恢复这次后台

后台模型层有有限失败重试(通常原调用加两次),并对中止、上下文治理错误及明确不应重试的错误提前停止。整个后台任务此处未设置统一超时,但各模型调用有自己的超时;界面状态使用的 timeoutSeconds:900 是规划状态记录字段,不能当成后台运行器一定在 15 分钟停止的保证。模型和保存重试 · 保存 outcome · 后台任务生命周期

二开时哪些可以直接修改,哪些需要补代码 #

  • 换模型、岗位提示词或预算,可以修改现有配置,但仍要符合岗位模板、状态格式和模型 provider 的要求。
  • 本次更新要让回复使用世界书或某种记忆,研发可以配置已有应用并连好对应服务;后台是否也需要这些资料,要另外检查它实际收到的输入。记忆服务失败时是否继续,可以按入口配置,但默认严格失败。
  • 要让前台模型选择写正文、配图或提交长期修改任务,需要启用独立的前台工具循环并连接相关服务,后台专家名单不控制这三个动作。
  • 要把新人物做成独立、可编辑的 NPC 卡,还需定义卡片字段、归属和读写代码。现有 judge_npc 只给分析,普通 V2 保存的是笔记与分析账目。
  • 要让后台查世界书或根据剧情改写设定,研发需增加检索和写入工具,规定可读写范围,再决定哪些结果可以记成事实。现有六专家没有自动完成这些操作。
  • 如果必须等业务接受正文后才能改状态,研发需要明确哪条消息算已接受、它来自哪个版本,以及取消后如何处理,再把这些检查接到提交之前。普通 V2 的快慢并行本身不提供这项保证。
  • 要把专家模型工具用于其他业务,可以分别复用原子能力。普通 V2 的两阶段调用、强制 NPC 规则和笔记格式只属于这个应用,公共 SDK 没要求其他业务照搬。

本次新增开发中的 #303 DIO 后处理 另提供一种长期要求处理方式:完整回复后先判断,再交外部 DIO 发布会话专属角色正文,后续回合读取;替换在 Compact 和最终计数之前发生,本轮版本冻结,不改共享 Preset。它默认关闭、仍为草稿,依赖外部 DIO 的版本发布、串行和持久防重,不能直接算作普通 V2 已交付的能力。新增的 #305 摘要质量检查 也尚未合入,当前评审要求修改,离线复核尚无明确通过的修复结果。

需要沿用自己已有的 Pi Agent 时,SDK 还有原生 Pi 慢任务入口:#244 已合 main,SDK 0.5.0 已发布,0.6.0 继续包含。研发可在 SlowTurnRuntime 的 agent 工厂中提供自己的消息、工具与本次任务,再处理返回结果和业务保存。它不会自动替换本章普通 V2 的两阶段专家后台,不能把“SDK 支持 Pi”写成“线上 V2 已切 Pi”。接法和独立保存职责见 原生 Pi 慢任务。可选原生入口

代码入口与当前交付核对点 #

要定位的内容 固定源码位置
普通 V2 与 Story 如何分流、应用怎样装配 dispatch.ts 1160
前后台材料、逐轮调度、Actor 完成与取消关系 planning/runtime.ts 350
工具选择、首轮强制规则、第二阶段、Director 和提交 planning/agentic-v2.ts 792
实际岗位提示词从哪里加载 prompt-manager.ts 75
六专家共有执行、输入和结果 memory/advisory.ts 218
配置字段是否真的被解析 server.ts 114

源码中已经实现普通 V2,也可选择接入 Jev 来做工具决策,但仓库配置没有默认开启 Jev。agentic-v2-luna-gemini38-pov-v1 虽然名字带 V2,实际启用了 Story,不能拿它代表本章的普通后台;Pioneer 等开发分支也需单独查看。要确认某个环境今天实际运行什么,应一起核对加载的配置、运行镜像、各岗位 ModelConfig/PromptManager,以及真实的状态读写、取消和并发结果。Jev 接线 · Story 场景文件

完整产品 / 互动剧情

Story|Branches 的互动剧情产品

收到用户消息后,Story 先核对上一轮待确认的实际回复,再准备本轮场景与目标,交给 Actor 写正文。本轮结束后保存剧情安排和待核对的回复 ID;聊天后端保存实际回复,下一正常请求再读取核对。

首次没有待核对的回复时,程序跳过这一项。后续核对读取的是聊天后端实际保存的回复,用户无需另外点击确认。

可左右滑动查看 放大查看流程图 ↗下载 SVG

Story 用来让互动故事随着用户的选择继续发展。用户发来一句话后,程序先准备当前场景、已经埋下的场外事件和适合推进的剧情目标,再让角色回复。用户可以继续眼前的事、回应邀请,也可以改变方向。之后,结算模型根据正式保存的聊天正文判断实际发生了什么;程序核对消息身份、允许修改的事件、目标依赖和结果格式,再保存世界与剧情进度。

这是 Branches 业务的剧情方案,实现在 roleplay-harness / main。本章更新至 10 月 9 日巡检,主干固定为 82e0169。Omen 事件提示牌已随 #250 合入,公共剧情工具随 Core Tools 0.2.3 发布;下面将它作为现有 Story 的可配置扩展介绍。代码中的请求分流、状态读写和配置均有源码依据,发布包不代表某个线上 Story 入口已经启用。

Story 已经把六个剧情工具和写正文的 Actor 组合成一套流程,由程序根据当前状态安排调用。启用 storyV1 后,请求会进入这套流程:正文仍由 Actor 生成,也沿用它的模型恢复能力;后台则不再调用普通 Agent V2 的 Orchestrator、六位咨询专家和 Director。路由中的 if (storyV1) … else if (agenticV2) 决定了这次请求走哪一套。应用接线

这套程序位于 apps/emochi/story,通过 apps/emochi 聊天服务运行。你的聊天后端确认登录账号、当前角色和会话,把用户原话与已保留的聊天记录发给它。Story 准备剧情要求、调用 Actor 写回复,并保存以后推进故事要用的状态。聊天页面仍由你的产品提供,返回的角色正文也由你的后端保存;Story 状态不能代替整段聊天记录。

研发部署时,需要让服务能从 Axon 读取角色资料、模型提示词配置、正式聊天消息和已保存状态,并写回新状态;模型调用通过 Kaon 执行。角色的真实设定、开场和已有聊天记录由业务提供。首次还没有 Story 状态时,程序就用这些资料建立故事;以后再据此准备方向、判断进展。角色是谁、按什么方式表达,仍由角色资料和提示词决定。Story 实际读取的材料 · 完整产品的装配

1. 用户实际得到什么 #

以“玩家和守卫莉娅在城门核对铜钥匙”为例:

  • 用户说“我把铜钥匙递给莉娅,但先不进城”,正文可以写莉娅核对钥匙、提出下一步,不能代替用户决定进入城内。
  • 先前已确立的“巡逻队即将返回”可以在后续产生影响;程序控制它何时只是远处动静,何时进入当前场景。
  • 剧情目标可以是“让钥匙上的旧徽记得到辨认”,但目标被放进模型输入不等于已经完成。只有后来保存的正文实际表现了辨认结果,才能记入进度。
  • 用户持续改为追查失踪商队时,主线可以调整;已经发生的事实和未完成承诺需要继续承接。

正文仍是用户日常看到的回复。世界快照、剧情目标、计数器,以及尚在进行或等待结算事件的消息引用,由程序保存与使用,不要求用户阅读。可选的 Auto Reply 入口提供三条“用户下一句可以怎么说”的建议,建议本身不等于用户已经作出选择。正文约束 · 建议回复输入与输出

2. 一次请求怎样运行 #

研发先在服务启动时加载启用了 storyV1 的 JSON 配置。聊天后端在请求的 extensions.scenario_id 中选中这份配置后,服务就按下图运行。这里的 Scenario 是一套服务运行设置的名称,与故事发生在哪个地点无关;用户只需正常发消息。

新请求:本轮输入 + 带消息 ID 的历史 + 角色与会话身份
  ↓
读取该用户 / 会话 / Story 场景的已保存状态
  ↓
有上轮等待确认的正文?
  ├─ 有且证据匹配:从聊天服务读取正式保存正文,先结算上轮
  └─ 首次或历史已改变:按真实角色资料与可见历史初始化 / 重建
  ↓
理解本轮行动 → 推进场景规则 → 必要时规划剧情目标
  ↓
选择本轮可推进的目标,组成“场景材料 + 剧情指导”
  ↓
Actor 结合原有角色提示词与聊天材料,生成本轮正文
  ↓
Harness 成功后:CAS 保存准备态和本轮消息 ID,等待正文被业务保存
  ↓
下一次正常请求:读回正式正文,再确认这轮实际发生了什么

Actor 要等 Story 准备完成后才开始写正文。这段等待中可能包含初始化、结算上一轮、理解本轮行动和规划剧情。生成完成后,settle() 主要保存本轮准备好的状态;等下一次正常请求到来,程序才取回这一轮正式保存的正文,判断世界实际发生了哪些变化。因此 Story 的剧情准备会影响本轮等待时间,不能全部放到回复之后再做。准备顺序 · 生成后保存

这里说的“采用正文”,是 Story 读取并认可业务正式保存的那条回复,用户不需要另点确认按钮。聊天后端先保存最终保留的版本,再在下一正常请求中带回消息 ID。Story 按账号、会话和消息 ID 取到全文,核对来源后才用它结算。之所以重新读取,是因为模型原始输出、界面临时显示的片段和最后保存的文字可能不同;如果读不到,或身份、内容对不上,就进入本章后面的恢复处理。

这套产品产生的结果 交给谁、什么时候用 什么时候保存和影响后续
本轮场景与剧情要求 stage / narrative 交给 Actor,例如“守卫核对铜钥匙,本轮尝试辨认徽记,用户尚未同意进城” 立即影响这次正文的输入;目标只是写作要求,不等于故事事实已经发生
本轮角色正文 通过生成流和最终结果交给聊天业务;用户阅读的是这一份 业务把实际采用的版本保存到消息系统,下一次请求再提供它的身份和历史
Story 持续状态与本轮待核对消息身份 程序在本轮成功后保存世界/叙事状态、准备态和 pendingActor.messageId waiting_for_acceptance 表示准备态已存,等待下次请求取正式正文;下次结算结果与新的准备态在那一轮成功后一起提交
状态提交结果和诊断 应用通过 story_turn_completed 等观测记录交给运维/接入研发 用于确认保存成功、冲突或只读;不是默认塞进角色台词或自动展示给用户的内容

正式消息读取 · 等待采用的保存与报告 · 报告接到应用日志

3. 三轮完整实例:每一步拿什么、产出什么、何时保存 #

以下是说明机制的示例内容,名字、台词和剧情目标不是固定生成结果。消息 ID 用 u1 / a1 等表示;实际由业务系统分配。

第一轮:用户把钥匙递给守卫 #

用户发来 u1:“我把铜钥匙递给莉娅,但先不进城。”

  1. 程序从 Axon 读取角色卡、角色 Prompt 和对话长度,再从请求取用户输入和带 ID 的历史。角色资料可能写着“莉娅负责城门登记”“不得泄露内城秘密”,开场消息交代两人站在城门。还没有 Story 状态时,初始化模型用这些资料建立世界和剧情快照,也就是之后要持续保存、更新的故事记录。
  2. 初始化后,当前世界事件可以是“莉娅正在核验用户提供的钥匙”,主线是“查明钥匙对应的旧城设施”,支线是“建立与莉娅的合作”。这些目标仍是以后要尝试推进的事,不会在初始化时就记成已经发生。
  3. pov_prepare_turn 调用行动分类模型理解用户这句话。本例还留在当前事件,可以返回 normal;“先不进城”没有允许程序切换场景。
  4. 新剧情快照中的 needPlan=true 表示需要准备目标。程序调用 narrative_plan_cycle 创建一组目标,再用无需模型的 narrative_deal_beat 选出本轮适用的一项,例如“让旧徽记得到辨认”。
  5. 程序在 Actor 原有的角色提示词、历史和本轮输入中,加上一条 [CURRENT STORY STAGE] 系统消息。里面的 stage 和 narrative 说明当前事件、阶段、应回应的动作、可见场外线索、剧情目标、主副线方向与情绪指导。隐藏世界的完整记录不会原样发给 Actor。
  6. Actor 生成 a1,用户可能看到:“莉娅接过钥匙,指尖停在柄端的旧徽记上。‘这是旧档案馆的标记。你可以先在门外等,我去核对登记。’”
  7. 本轮 Harness 成功后,Story 保存世界准备态、剧情快照、pendingActor.messageId=a1、u1 的 ID 与内容哈希,以及当时交给 Actor 的场景材料,报告 waiting_for_acceptance。正文由聊天后端保存到消息系统;此时 Story 只记下以后要核对 a1,还没有直接把 result.output.text 判作故事事实,也没有把整篇正文复制进状态。

角色与请求材料 · 初始化提示词 · Actor 新增输入 · 保存内容

第二轮:先采用上一句,再处理新要求 #

用户接着发来 u2:“不用去核对了,先把钥匙还我。”

  1. 程序检查历史中最近一条 assistant 是否就是 a1,再通过 conversationMessage,按用户、会话和消息 ID 读取正式保存的 a1,同时核对 u1 与更早已接受正文的位置。
  2. pov_advance_world 用保存后的 a1 全文、u1、当时准备态,以及截至 a1 的材料结算上一轮。u2 中“还我钥匙”的新要求不会混进来。如果聊天后端最终把 a1 保存为“莉娅只看了一眼,没有接过钥匙”,结算就以这个版本为准。
  3. 程序记下已发生的结果、尚未完成的场外事务和已传达邀请,增加世界轮数,再把 a1 与用户行动的消息引用加入当前事件的证据。等事件结束或被打断时,才调用 narrative_settle_event 判断目标完成和主副线进度,每句话不会都重算整个事件。
  4. 程序用更新后的世界和 u2 准备本轮场景。“用户要求归还钥匙”是这次要回应的动作,还不能算作上一轮已经归还。
  5. Actor 生成 a2,用户可能看到:“莉娅停下脚步,把钥匙递回给你。‘好,我们就在这里谈。’”
  6. a2 生成成功后,程序一次提交“按 a1 更新的状态”和“为 a2 准备的状态”。这次提交用 CAS 检查旧版本是否仍有效;保存后 acceptedMessage 指向 a1,pendingActor 改为 a2。如果 Actor 失败,前面算出的 a1 结算仍只在这次请求的内存中,没有单独保存,下次可以从旧准备态重新恢复。

采用与切分证据 · 世界采用与事件证据 · 对应回归测试

第三轮:结果怎样真正用于后续 #

用户再发来 u3:“我留在原地,问她档案馆为什么被封了。”

程序先读正式保存的 a2,采用其中“归还钥匙”等事实,再准备 u3。Actor 获得的当前事件与写作要求已经承接这些事实;它也会读取当前请求提供的聊天历史。若此前的事件在此时结束或被用户改道打断,事件结算模型读取这个事件累计的完整已接受正文和用户行动,判断哪些目标完成、主副线各自推进到哪里、是否需要更换方向。

“钥匙归还了”这样的具体事实先保留在正式聊天正文中,再进入后续历史和故事材料。Story 快照没有内置“铜钥匙持有人”字段。如果产品要提供可查询的物品栏或 NPC 小卡,研发还要另外定义并保存这些数据,让后续请求能读到它们。

结算时,“确认徽记来源”已经有正文依据,可以记为完成;“进入档案馆”还没发生,即使列在原计划里也不能记为完成。程序再根据新的主副线进度选择后续目标,交给之后的 Actor 调用,故事就这样继续向前推进。事件判定与后续动作

4. 内部有哪些工作,分别由谁决定 #

工作 谁决定何时执行 输入 输出及用途
初始化世界与故事方向 Story 协调器:首次没有状态,或历史变化需要重建 角色定义、开场、近期可见历史、本轮输入 世界快照与主副线;给后续工具使用
准备当前场景 PovPrepareTurnTool 每次可正常推进的 Story 请求 上轮已结算世界、本轮行动、故事材料 世界准备态、行动意图、时钟变化、当前可见场景
制订一批剧情目标 NarrativePlanCycleTool cycle.needPlan=true,且没有未解决事件阻塞 主副线、已有进度、欠缺回报、旧目标、设定 新增 5–7 个目标,保留未完成目标;不生成正文
选本轮目标 NarrativeDealBeatTool 每轮准备,且无未解决事件阻塞 叙事快照、当前事件 start/develop/end 一个目标及情绪和方向指导;纯程序计算
写本轮正文 Actor 上述准备完成后由 Harness 调用 原角色回复材料 + 场景与剧情指导 用户可见回复
采用正文并推进世界 PovAdvanceWorldTool 下一正常请求核对上轮正式保存正文后 对应准备态、完整正文、上轮用户动作、当时材料 世界结算候选;确认本轮表现与场外后果
结算一个事件 NarrativeSettleEventTool 当前事件结束或被改道打断;或重试待结算事件 同一事件累计的已接受正文、用户行动、叙事快照 目标完成情况、主副线进度、情绪观察、下一步指令
调整剧情线 NarrativeRebranchTool 协调器执行上一步返回的 rebranch 当前主副线、已确认用户新方向或长期未推进支线 新方向与承接说明;保留已发生事实和欠账
持久化 本轮 Harness 成功后由 Story 协调器调用 Axon CAS 完整 Story 状态与消息身份 下轮能读回的状态版本

程序按上表的条件选择何时调用哪个工具,没有让通用主 Agent 在六个工具之间自由循环。模型负责理解行动、提出剧情目标、判断世界变化和事件结果;程序处理计时、容量、去重、字段检查和保存。NarrativePlanCycleTool 一次准备的是一批可推进目标,后续仍会根据用户选择调整,并不预先写死整段对话。工具调用位置 · 剧情规划规则

5. 世界与剧情到底记录什么 #

世界记录:当前发生什么,场外还有什么 #

记录 业务含义 例子 怎样进入正文
foreground 当前事件 用户所在场景中正在处理的具体事情 莉娅核对铜钥匙 每轮作为当前场景;start/develop/end 约束展开节奏
backgrounds 场外事务 已确立、之后可能影响当前场景的独立事务 巡逻队正在返回城门 倒计时到期后按当前场景阶段延后、加入障碍或接过场景
undercurrents 隐藏发展 尚未完整进入用户视野的变化 某个既有敌对组织正在追查钥匙 先只表现氛围或迹象,随后影响条件或给出可拒绝邀请;不自动变成角色已知事实
seedPool / seedQueue 未来可能事件 与已有世界一致的后续素材 既有商队可能送来城外消息 规则允许时进入隐藏事件;不能作为已发生事实
pendingSignalDemand 待传达邀请 需要让用户实际收到的线索邀请 信使请用户查看某处 Actor 要实际表现“邀请已到达”,用户仍可拒绝;结算确认传达后才更新记录
pendingInjections / pendingNextForeground 后续结果与下一事件 已有机制产生的场外后果、已结束事件之后的候选场景 巡逻队带回报告;准备转向核对档案 进入后续的场景材料,以观察或通信方式呈现

程序从完整世界记录里选出本轮需要的部分,组成 stage 发给 Actor:当前事件、要回应的动作、选中的场外影响,以及数量预算允许的隐藏线索和待传达邀请。其他暗线、未来事件和计数器不会直接变成角色已知的信息。初始化时,程序用主角色的实际名字设置受保护的 owner,防止把主角色放进隐藏发展或未来事件里;转场时若不能直接确定同伴是否跟随,再请模型判断。世界结构 · 投影选择 · 角色保护

剧情记录:为什么推进,进展到了哪里 #

  • main / sub:主副线各保存主题、方向、预期体验、尚未兑现的回报、当前进度 cursor,以及连续多少个已结算事件没有推进 starve。
  • cycle.pending:当前要尝试推进的目标。每项注明服务主线还是支线、属于人物/关系/冲突/揭示/回报、前置目标、是否完成和优先级。回报类目标必须有明确铺垫依赖。
  • emotion:目标与已观察的情绪轨迹。三个轴分别描述好坏感受、平静或紧张、视角方掌握主动权的程度;供后续节奏调整,不是修改用户真实情绪。
  • clock:已结算事件 ID、已完成目标、最近用户方向、本轮已发放内容等,负责恢复与去重。

narrative_settle_event 要分别判断“目标完成了没有”和“剧情线推进到哪里”,两者可以得到不同结果。以辨认钥匙徽记为例,模型先判断正文有没有写出辨认结果,并给出依据;程序再检查目标是否存在、是否尚未完成、前置目标是否满足,以及依据是否为空。至于这段依据是否真的得到正文支持,当前没有另一个模型或程序复核,需要用实际故事案例检验判断质量。判定提示词 · 程序实际校验

保存后,快照中可以查到目标完成情况、主副线进度和事件计数,但查不到模型为每项目标和进度变化给出的依据。成功结算的事件也会从待结算队列移除。如果运营需要点击“为什么完成”查看当时正文、模型理由和采用版本,研发还要单独保存这份审计记录;正式聊天消息仍保留在聊天服务中。判定结果写入哪些字段 · 结算后移除事件引用

6. 默认什么时候触发,哪些参数能改 #

产品接入配置 storyV1 #

确定采用 Story 后,研发把 storyV1 写进服务启动时读取的 Scenario JSON 顶层,与正文模型的 modelConfigRef 并列。下列字段规定剧情模型、等待时间和状态大小;每轮具体要准备目标、结算还是调整方向,由程序按后面的规则安排,用户照常对话即可。

字段 默认与范围 影响
enabled 对象存在且未设 false 时启用;整个 storyV1 不提供则关闭 是否进入 Story 专属流程
modelConfigId 必填非空字符串 行动解释、世界与叙事工具使用的模型配置
initializerModelConfigId 可省略,使用 modelConfigId 可单独指定初始化模型
modelCallTimeoutMs 45,000 ms;允许 1,000–180,000 每次 Story JSON 任务的时间预算;该任务的首次响应与一次格式修复共享计时,不是整个 Story 准备阶段的总预算
postTurnTimeoutMs 90,000 ms;允许 1,000–180,000 本轮 Actor 完成后保存准备态的时间预算,不是“下一轮世界结算最多 90 秒”的开关
maxStateBytes 60,000 UTF-8 字节;允许 4,000–60,000 Story envelope 保存上限;超出会失败,不静默剪掉证据
seed 731;允许 0–2³²−1 机械随机过程的初始种子,随快照保存与恢复

这些是主干应用配置实际接受的字段;未知字段会报错。当前 main 同时接受 omenDeck,具体牌组格式和旧会话处理见下文。主干配置解析

例如准备一个场景时,程序可能先请模型判断用户是否转场,再判断同伴是否跟随。两个 JSON 任务各自有 45 秒预算,前面还可能执行上轮结算、初始化或规划。因此,整个工具调用和用户等到首字的时间都可能超过 45 秒,整轮另受请求自身的取消与超时控制。JSON 任务的计时边界 · 行动与同伴的两次调用

Omen:一个事件共用一张氛围提示牌 #

PR #250 已于 9 月 24 日合入 main,相关公共工具随 Core Tools 0.2.3 发布。Omen 让程序从预先写好的提示语中抽一条,供 Actor 在同一事件中采用相应的叙述角度、氛围和节奏。它沿用 Story 准备、正文和结算流程,不增加第七个模型工具。本轮核到合入与发包,未核具体 Story 生产入口的采用效果。

例如,“守卫核对铜钥匙”这个事件可以获得“表面安静,隐藏的变化正在形成”这样的提示。Actor 可以把同一场核验写得更克制、有悬念,但不能因此凭空认定守卫背叛、增加一个没有铺垫的人物,或替用户作决定。这个例子说明用法,不是代码保证产生的台词。提示只影响表达;事实仍以正式保存的正文和后续结算为准。

程序在创建剧情状态时洗牌、抽出第一张,并把牌组指纹、剩余牌、弃牌、当前牌 ID 和随机数状态一起放进 Story 快照。本事件连续几轮都会取回同一张牌,放入 Actor 的 narrative.omen;只有事件成功结算才抽下一张,重复结算或无法判断结果时不消耗牌。候选状态仍要等本轮正常提交成功后才成为下次可读的版本。

主干的 storyV1.omenDeck 省略时采用内置 142 张提示牌(64 个易经卦象、78 张塔罗牌);新会话传 [] 可以不启用,传自定义数组则整体替换。仓内 Story 配置的 seed 是 731,同一牌组和种子会得到相同的洗牌顺序,不能理解为每个新会话都会随机得到完全不同的次序。

已有会话换牌组仍需处理保存过的状态。当前 82e0169 的协调器只自动为“尚未启用提示牌”的旧快照启用非空牌组;已经保存牌组指纹后,直接设 [] 或换另一副牌,后续发放/结算仍会因牌组不匹配而报错。研发需要用迁移函数重建抽牌状态并保存,再启用新配置。这个限制已重新对照当前源码,旧版本的失败复现不算本轮重新跑过的测试。具体传参见Story 工具中的 Omen 接法。

主干配置及默认牌组 · 向 Actor 传入提示 · 结算后换牌 · 快照与牌组核对

内部默认规则:不等于都有业务配置开关 #

规则 默认行为 可修改的位置
前景事件节奏 start 后进入 develop;developMax=2 控制发展阶段;end 后等待合法后继事件 独立世界工具通过初始 snapshot 的 policy;现有 Story 场景配置未暴露
场外容量 background 最多 3;undercurrent 最多 5、目标下限 2;每轮选最多 2 条暗流进舞台 同上;缺少已存在种子时不会为了凑下限凭空制造事实
暗流发展 各阶段按确定性骰子和阈值推进;maxStageRounds=6;阶段 3 的邀请未送达时暂停进一步推进 世界 policy;不能解释为每 6 轮必有新剧情
新剧情目标 每次规划新增 5–7 项,至少一项服务副线;保留未完成项 独立 narrative 工具构造参数 options.policy
发放目标 每个正常准备轮都计算;dealEveryTurns=3 参与强制轮换判定 narrative policy;不是三轮才启动 Story
周期进阶 已完成目标达到当轮 ceil(总数×2/3) 门槛后,先给晋级考验;完成或等待 2 个已结算事件后推进周期 narrative policy
主线改向 连续 3 个已结算事件出现同一个明确的新追求,才请求主线重定向 narrative policy.branchConsecutiveEvents
支线长期无进展 连续 5 个已结算事件未推进,可更换支线;主线 3 个未推进先记录诊断,不擅自改用户追求 narrative policy

当前 Story 应用直接使用工具默认的世界和剧情策略,只在初始化时另外设置主角色保护与随机种子。若希望客户能调整上表规则,研发还要修改应用的配置读取和参数传递代码。现有 storyV1 不接受 dealEveryTurns 等字段,直接写进 JSON 会报错。世界默认值 · 世界规则 · 叙事默认值 · 主副线改向触发

7. 模型上下文如何组装,窗口在哪里控制 #

Story 会按模型的任务分别准备输入:写正文需要当前场景,做结算则需要已保存的正式消息和当时的状态。

使用者 实际材料 输出
初始化模型 实际角色名;定义前 12,000 字符;开场前 3,000;最近 18 条 user/assistant 各前 3,000;当前输入;主角色保护规则 世界初始事件、场外事务、暗流、种子、主副线
行动解释模型 当前输入、当前事件、可转向的背景和阶段 2–3 暗流、上轮实际传达的邀请、同伴身份、故事材料 normal/cue/signal,必要时目标 ID 与同伴邀请
规划与重定向模型 叙事快照 + 同一份裁切后的故事材料;明确任务提示词 新目标或主副线方向;不直接写正文
Actor 正文模型 原业务的角色与聊天输入 + 不可压缩系统消息中的 stage/narrative 角色正文
世界结算模型 已恢复且校验的准备态、规则标记、骰子、对应用户动作、已接受完整正文、截至该正文的故事材料 世界变化提案;程序检查合法 ID、阶段、容量与可写范围
事件结算模型 叙事快照、整个事件已接受正文拼接、对应用户行动、是否被打断 有证据的目标完成、剧情进度和情绪观察

用户人设目前只接到了哪里 #

假设用户选择的身份资料是“阿宁,初到灰港的信使,不认识莉娅”。Core Tools 0.2.2 已为五类调用模型的 Story 工具增加可选 userPersona:接入方传入后,工具去掉首尾空白、最多取 4,000 字符,放在模型 JSON 输入前的 CURRENT USER PERSONA 块里。它帮助解释“我”是谁,不能仅凭资料就认定“莉娅已认识阿宁”或把身份说明复制成已发生的世界事实。后台计划、状态、总结与后果字段统一以 “the user” 指代用户,要求姓名的字段、用户原话和角色台词除外;空人设保持旧输入行为。人设文本、上限与称谓规则

现成 StoryV1 仍没有把这段资料传给准备、世界推进、剧情规划、事件结算和重定向工具。Actor 模板若已引用用户人设,正文模型可以读到,但上表的剧情模型不会因此自动读到;普通 Agent V2 已从 Axon 给后台传 Persona,也不能证明 Story 已接通。接入方若要让剧情模型也理解用户身份,需要补这五处调用的真实资料来源,并验证同一人设只作为身份上下文、未被无依据写入持久状态。Persona 本身不保存在 Story 快照里,下次调用仍须由资料服务提供。准备调用 · 结算、规划、重定向与世界推进 · 普通 V2 已有输入

Core Tools 0.2.2 的 release/tag 和发布任务已经存在,说明独立接入方可以取得接口;它不等于 StoryV1 业务采用,也不代表当前生产模型已经读取这些身份资料。独立传参例子和六工具的输入定义见 Story 原子能力。0.2.2 发布

表中的 12,000 / 3,000 / 18 是 compileStorySource 写在代码里的裁切值,当前不能通过场景配置修改,也不表示模型有多大的 token 窗口。事件结算会按消息 ID 另外取回正式全文,不使用裁短的历史代替它。Actor 的窗口、历史截断和压缩仍由原模型配置及输入准备代码控制;Story 通过 nonCompressibleSystemMessages 加入的场景材料也占用这个窗口。材料裁切 · Actor 注入方式 · 完整事件证据读取

Story 也可以使用世界书来写本轮正文。例如选出的条目写着“铜钥匙只能在城门开启时使用”,Actor 会同时读到这条设定和 Story 准备的场景、剧情目标。9 月 22 日主干移除了二者不能同时配置的限制;研发还要连接世界书服务,在 worldbook.tenantId 中填写创建这些书时使用的 tenant_id,并把当前角色的资源 ID prompt_id 与所用书籍及版本关联。这个值由维护世界书服务的研发提供;角色 ID 则来自业务已有的角色记录。没有绑定时,就按原来的 Story 输入继续,不选取或加入条目。当前配置与接线 · 逐轮绑定与空绑定处理

规划和结算模型目前读不到这次选中的同批原文:StorySource 没有相应字段,而且 Story 准备先于 Actor 的基础输入组装。Actor 写出的正文以后可以成为故事证据,其中可能已经用上这些设定,但规划模型仍没有直接读到原条目、版本和全部规则。若剧情准备阶段就要依据世界书作判断,研发需要再把条目和版本传给它。Story 准备顺序

加入世界书后,程序仍检查“最后一个非世界书材料是不是本轮用户输入”,防止把用户行动的位置弄乱。只有由这次 WorldbookTurn 创建、带进程内来源标记的消息才作为世界书注入识别,客户端写一个同名字段不能冒充。Actor 换模型重试时按该目标窗口重新计数,只试裁老历史;当前输入、世界书及 Story 的不可压缩场景约束保留。材料仍放不下就拒绝该目标,不会为了通过预算删除本轮剧情约束。来源与用户位置检查 · 每个目标重新渲染与预算

8. 接入完整 Story 产品,需要准备什么 #

服务端装配 #

  1. 研发部署仓库聊天服务,让业务后端通过 Agent Router 协议发送请求,扩展版本填写 roleplay-harness/v2。普通模型的 /chat/completions 请求不识别 storyV1,不能用它代替这个入口。
  2. 研发为当前入口准备 config/scenarios/<入口名>.json,填写正文模型 modelConfigRef、回复模板 presetRef、当前解析器要求的 agenticV2 配置,并启用 storyV1。modelConfigRef 与 agenticV2.modelConfigs.actor 必须一致;Story 的 modelConfigId 另外指定剧情分析模型。这里填的是模型或模板配置的引用,角色设定从角色资料中读取。
  3. 服务需要能通过 Axon 读取角色卡、角色 Prompt、对话长度、正式消息全文和角色扮演状态,并按版本检查结果写回状态。模型适配器则要能解析 Actor 和 Story 的配置,调用真实模型。这些数据接口和模型调用都可用后,完整流程才能运行。
  4. 聊天后端提前分配本轮助手消息 ID,保存最终采用的正文,并在下一请求中传回实际保留的消息历史。Story 会按这些 ID 读取文字进行结算,不另存一份完整聊天。
  5. 研发检查 Actor 模板展开后的实际输入,确保角色资料、聊天记录和 Story 剧情要求能一起放入模型,且最后一个非世界书消息仍是当前 user 输入;Story adapter 会检查这一点。

保存文件后,研发还要在部署参数 HARNESS_ENABLED_SCENARIOS 中选中它,服务才会在启动时读取;目录可用 HARNESS_SCENARIOS_DIR 修改。旧的 AGENT_ROUTER_SCENARIOS_JSON 也能提供配置,同名时会整项覆盖文件定义。最后,聊天后端在每次请求中填写对应的 extensions.scenario_id。这样请求才会用上新配置,仅增加文件不会改变其他聊天的运行方式。文件加载与覆盖 · 请求选取方案 · Actor 引用与产品组合校验

仓库提供完整配置样例 config/scenarios/agentic-v2-luna-gemini38-pov-v1.json。其中保留了 agenticV2.modelConfigs.orchestrator / specialists / director 等字段,但路由不会因为字段存在就执行普通 V2 后台。该样例的 580,000 ms 请求超时和具体模型名称是这个样例的配置,不是所有 Story 接入的固定值。配置样例 · 配置互斥检查

研发把下面的 Story 配置放进上述 JSON 文件的顶层,同时保留原有正文模型、模板和其他必要配置。这只是文件的一部分,不应作为聊天内容发给角色:

{
  "storyV1": {
    "enabled": true,
    "modelConfigId": "your-story-model-config",
    "initializerModelConfigId": "your-story-initializer-config",
    "modelCallTimeoutMs": 45000,
    "postTurnTimeoutMs": 90000,
    "maxStateBytes": 60000,
    "seed": 731
  }
}

每次请求要带哪些编号,分别从哪里来 #

继续用莉娅的例子:下面的 ID 和文字只是教学示意,真实值由已有账号、角色和聊天记录确定。

字段 / 材料 谁提供、具体是什么 为什么需要
requestId 业务为本次生成分配的追踪 ID,如 story-turn-1 关联本次准备、模型、结算和保存调用;不是聊天 ID
conversationId 业务中的当前 RP 聊天 ID,如 conversation-8 后续从这一段聊天读取正式消息和状态
promptId 用户选中的角色资源 ID,如 lia-character 服务用它读取“莉娅负责城门”等设定;不是模型配置 ID,也不是完整设定文本
extensions.scenario_id 后端选择服务已加载的 Story 入口配置名 确定使用哪套模型与 Story 设置;读取状态时也按这个配置名区分记录,不是让用户选择一个具体剧情事件
extensions.turn_context.user_id 登录/业务后端提供真人账号 ID,如 user-42 确定消息与状态属于哪个账号,不是玩家的故事名字;闭环请求必需
extensions.turn_context.model_alias、外层模型配置身份 后端按 Router 协议提供有效业务模型别名和要求的 modelConfigId 满足请求合同;实际 Actor 与剧情模型仍由已加载配置和允许的选择决定
extensions.turn_context.assistant_message_id 业务预分配本轮要保存的回复 ID,本例 a1 Story 用它标记本轮准备态,下一请求按这个 ID 找正式正文;必需
extensions.turn_context.input_question 用户这次原话,如“我把铜钥匙递给莉娅,但先不进城” 作为当前行动;未指定时入口取最后一条 user 内容,否则用 continue。Continue 也需正确表达本次继续要求
带消息 ID 的 user/assistant 历史 业务会话服务提供当前保留路径的原文,例如 u1、正式保存的 a1 对齐已发生事实和原用户动作;重生成或分支后不能混入未保留的候选正文
语言与 generation.n=1 后端传 turn_context.language,如 zh,以及单候选生成设置 语言参与角色与 Story 模型请求;当前 Router 一次仅支持一个生成候选

聊天后端按上表提供正确的身份、消息和可读取的正式全文即可。Story 会按账号、聊天和所选配置取回 world、narrative 快照,首次才初始化,后端不用每轮重新创建这些对象。消息 ID 和正式正文用于核对故事事实,因此只传“我们已经聊到档案馆”这样的摘要还不够。角色资料、历史及正式全文来源 · 原始请求解析与输入回退

字段名称须按所用 Router SDK/协议序列化;上表的 requestId 等是 TypeScript 接收字段,扩展对象内使用代码列出的下划线名称。请求校验 · 闭环扩展解析

与其他能力的组合边界 #

  • Story 自己安排 Actor 生成,不能同时配置 preActorDirector,也就不能在同一配置下再用另一套前台协调器选择 Actor、图片和 DIO。
  • Story 不能同时配置 sumiV1。Router 会把 Sumi 请求提前送到独立图文应用,它不是 Story 内置的一组工具。
  • Story 默认不调用普通 V2 的咨询专家。研发可以单独复用某位专家,但要自己安排何时调用,以及把结果放进 Story 的哪一步。
  • 可以配置 worldbook,让本轮 Actor 读取选中的条目。Story 准备、世界结算和事件结算模型不会自动收到同批原文,详见本章上下文部分和世界书接入。
  • Compact 和记忆仍需分别准备输入、保存方式并启用对应配置。Story 保存主副线进度,不能代替用户长期记忆。

当前保留的互斥条件 · Sumi 独立入口

9. 保存、重生成、失败与恢复 #

Story 的正文沿用 main Actor 的恢复。配置 recovery.transientRetryModelConfigId 后,原本能即时流式的主尝试先暂存文字,到正常完成或首个非空片段满 4 秒时释放,以先到者为准。未发出可见正文时,空响应、符合条件的 provider 错误可以触发一次备用重生成;Gemini 现在按 Kaon 标明的上游错误来源判断,覆盖 HTTP、SSE、嵌套 Google error envelope 等,不再只限 429/500/503。程序排除本地错误、取消、已经恢复过的错误和 DeepSeek Flash/0731 自身再恢复。完全空响应没有首个片段,不另等 4 秒;其他模型仍按内容过滤、空响应及特定状态码等原条件处理。缓冲启用 · 主干恢复资格

如果用户已看到“莉娅接过钥匙,低头看了看——”,首次 Gemini 流随后在可信完成前中断,程序可以把已有正文作为 assistant prefix,只向 deepseek-beta/deepseek-v4-flash 请求一次续写。条件是已配备用 ModelConfig、实际 Gemini 没被参数改成其他模型、已发可见正文、未取得明确 finish reason 或完成标志、未取消,且原消息可计数。只有 reasoning 或尚未释放的正文时仍按重新生成处理。程序先扣除 Gemini 已消耗的输出,再核对备用窗口能否容下原输入、前缀及剩余输出;窗口不明、预算不足、计数失败或恢复时间耗尽时直接失败。严格流与续写条件 · 前缀、预算和真实请求

续写沿用正文过滤器和后缀保护,必须增加可见正文并正常结束;失败后不再切第三次。普通重生成只允许配置的 kaon/deepseek-v4-flash/kaon/deepseek-v4-flash-0731;续写使用 beta 路由但沿用备用配置的参数、计数 profile 和窗口。两次 usage 合并,估算会注明来源,任一次 cost 未知就不作为完整费用返回。一次 Actor 调用最多主模型加一次备用,不叠加普通 retryCount;未配置恢复时仍用原有重试规则。续写完成和用量 · 失败后停止

旧式 SSE 实际收到 [DONE] 且符合已有兼容设置时,仍可接受缺 finish reason 的完整流;显式 tolerateMissingStreamMetadata 只在 DONE、有正文且没有畸形事件或未知结束原因时推断 stop。续写请求关闭宽松兼容,必须可靠结束。Fusion 分支另有 retryOnAnyUpstreamError、5 秒并发备用和 20 秒正文 watchdog;main 的 Story 配置不接受这些字段,也没有因此获得那个计时器。完整条件见 Actor 恢复。DONE 兼容 · main 配置字段

这些恢复只处理写正文,不重试剧情结算、不替聊天后端保存消息。续写成功后仍须完成正常的本轮收尾和 Story CAS;失败时,即使界面已显示“接过钥匙”,也不能宣告对应 Story 准备态或世界后果已经保存。受控测试证明恢复、预算与兼容机制,未证明真实两模型语气衔接、时延、当前生产采用或剧情质量;下表的 Actor 成败与状态保存规则仍适用。

程序通过 AxonAgenticStateRuntime,按 userId + conversationId + scenarioId 读取和保存 Story 状态。读取时还会核对状态中的 promptId,确保仍是同一角色。提交使用读到的 expectedRevision 和来源位置做 CAS 检查,避免旧请求覆盖新版本。读写适配器

状态里有三种计数,推进时机不同:sourceTurn 按会话中的消息位置变化;world.round 在成功采用正文后增加;narrative.clock.eventCount 则在一个剧情事件完成有证据的结算后增加。因此看进度时要先确定正在查看哪个字段。

情况 当前代码行为 对产品的影响
正常新消息 先采用上轮权威正文,再准备当前输入;当前 Actor 成功后 CAS 保存 后续上下文承接实际保存的故事
Continue 使用会话消息位置推进,并把继续指令作为合成行动 不因用户消息条数没增加而卡住;与真人用户动作的证据类型区分
Regenerate / edit_regenerate 使用继承 Actor 回复;不运行 Story 准备、模型调用或状态写入 当前重生成没有 Story 新增舞台指导;下次普通请求再核对保留下来的历史
上轮消息 ID 对不上、历史被改或截断 普通前进请求根据可见历史重新初始化;不是沿用旧事实硬接 业务应尽量提供稳定历史与正式消息读取
历史回退到已存来源水位之前 Actor 继续回复,Story 只读不写 当前存储不支持把旧来源当成新版本替换
初始化暂时不可用或两次 JSON 均不合格 可恢复情况退回原 Actor,本轮不写 Story;记录诊断 可有回复,但没有新增 Story 指导与进度;权限/程序错误等不被统一吞掉
上轮世界结算没有有效结果 保留旧 prepared;不继续准备新 Story 轮 当前正常请求会失败并等待恢复,不能伪造“无变化”然后推进
结算输入身份、快照或准备态校验失败;世界模型出现未被识别为可恢复的错误 工具直接抛出错误,不统一转换为 pending;外部取消同样中止执行 业务需要修复身份、数据或服务问题,不能把所有异常都当作等待模型再试一次
事件结算未知,或旧事件证据丢失/变化 保留引用并跨请求重试;未解决期间暂停新增剧情发放 世界准备可以继续,但不能假设该事件目标完成
未解决事件达到 3 个不同来源位置上的尝试,或距首次尝试达到 12 个来源位置 生成 story_event_quarantine,与队列移除一起 CAS 保存 留给人工恢复;没有假装事件已完成。来源位置不是墙钟时长,也不是 world.round
Actor 失败或被取消 不保存本轮 Story 候选 前面模型调用可能已有成本,已保存状态保持旧版本
保存冲突或状态超限 report 标记 stale_write_rejected 或 failed 已生成正文不因这个报告自动撤销;业务需要观察保存结果,不能把“收到正文”当“Story 保存成功”

Story 状态保存上限默认 60,000 UTF-8 字节,事件证据采用消息 ID 和哈希,结算时再取完整文本。隔离记录单项上限 64 KiB;代码注明 Axon ledger 有 60 条、512 KiB 的保留界限,因此不是永久审计档案。保存与报告 · 恢复分支 · 事件隔离

程序根据最新快照中保留的 ID 识别重复调用:剧情工具默认记住最近 128 个已结算事件,世界工具记住最近完成轮的 ID。完整 Story 应用还会检查已处理到哪条消息,并用 CAS 防止旧请求覆盖新状态。如果单独调用这些工具,你的程序也必须先读最新状态再提交;若要永久防止旧事件重放,还需另外长期保存去重记录。异常的实际返回边界 · 128 项默认窗口 · 世界轮身份检查

10. 可以拿什么二开 #

采用完整 Story 应用时,角色读取、模型调用、聊天读取和状态保存的程序已经写好,你需要准备它实际连接的服务与资料。如果仍由自己的聊天后端调用回复模型,只想加入剧情处理,也可以从 @flowgpt/agent-core-tools/story 导入六个工具及快照创建、解析函数:回复前调用工具准备目标,正式正文被采用后再调用工具结算。工具返回新快照,但不自带数据库,也不自动调用其他工具;你的后端要安排调用顺序、把结果加入模型输入,并保存状态。

单独接入工具时,研发可以调整世界与剧情规则、Narrative 提示词、模型实现、哪份正文算正式采用,以及如何保存。现有 Story 应用等下一请求才采用上一正文;如果你的后端在同一请求中就能拿到最终采用的正文,也可以当轮调用推进、结算并保存。后一种时序需要自己实现,不是仓库完整应用当前的默认行为。公开导出 · 独立组合示例

11. 接入验收看什么 #

  • 连续两次正常请求后,能看到上次 pendingActor 被正式保存正文采用,新请求的 pendingActor 接替;读到的正文来自正确会话和消息 ID。
  • 下游实际保存正文与 Harness 原始结果不同,下一次结算依据保存后的版本;下一次用户的新要求不能反向污染上轮事实。
  • 看 story_turn_completed 的 outcome、状态版本、工具调用列表、诊断与 prepare/settle 耗时,区分正文成功与状态成功。
  • 检查重生成、Continue、删改历史、Actor 失败、世界模型失败及 CAS 冲突时是否符合上表。
  • 工具机制测试与真实模型体验分开验收;固定断言可以证明保存顺序与隔离,不能证明实际模型总能合理推进剧情。

本次已阅读源码,并运行固定快照自带编译产物的四组既有测试:story-deferred-review、story-scenario、story-scenario-dispatch、story-settlement-recovery,38 项通过。这不是生产验证,也没有重新编译或修改产品源码。关键测试源

原子能力 / 从需求找入口

原子能力:可以拿什么做二次开发

10/19 更新 · 本章 8 处从第一处开始看 →

已有的聊天产品可以按需要增加世界书、记忆、图片或剧情分析。下面列出了仓库里可以复用的能力,以及它们通常在对话的什么时候使用。点击名称后,可以查看具体输入、返回结果和接入代码。

如果产品已经使用 Agent V2 或 Story,研发可以在现有配置中开启应用支持的能力,并补上相应服务和资料。继续使用自己聊天后端的产品,则要在原有代码中调用对应函数或接口。各页分别介绍这两种做法;需要组合多项能力时,可参考 接入步骤与完整案例。Agent 编排与扩展 另外介绍如何让模型选择工具,以及如何自己安排快慢任务或固定流程。

能力目录 #

表里的输入由业务程序准备。用户通常只发送一句话;账号和聊天 ID 由后端提供,角色介绍从角色资料中读取,历史从聊天记录中读取,模型和工具由研发配置。具体字段的格式、例值和可省略条件都在对应页面。

能力 什么时候使用 输入和结果 研发需要做什么
角色正文与前台工具 回复材料准备好之后;前台工具循环还可分段安排正文、图片与长期指令 角色提示词实际文本、已保存消息、本轮输入+模型配置;拿回正文流、最终文本及相应调用结果 复用仓内 Actor 运行时;前台自主选动作需配置 preActorDirector 和依赖,不是安装 SDK 后默认获得
六类分析工具 在需要分析的地方调用;普通 V2 把它们放在与正文并行的后台 分析目标 reason/focus+角色/历史/当前输入/已有笔记的具体材料;返回专家分析文本,供协调模型或业务采用 公共 Core Tools 可直接调用,或由自己的 Agent 注册;普通 V2 已有选择、Director 整理和保存接线
Story 六个工具 正文前准备剧情目标;业务确认采用完整正文后结算。现成 Story 在下一请求核对已保存正文 当前世界/剧情快照、事件和用户行动,结算时另交正式正文;返回写作材料或更新后的状态 可复用 /story 工具;Branches 的 Story 应用已有完整调度,正文是否已正式保存,仍由调用工具的聊天后端核对
世界书 用户发来消息后,先选出相关设定,再连同角色资料和聊天记录一起发给回复模型 允许的书籍 ID/版本、本轮查询文本、最近聊天和条件字段;返回原文 blocks、放置位置与选择原因 使用仓库聊天服务时,修改入口 JSON 的 worldbook,并关联角色与书籍;使用自己的后端时,通过 HTTP 或 SDK /worldbook 选择资料,再把返回原文加入模型消息
记忆与状态读写 回复前读取;有新资料需要留下时写入;下轮再次读取 后端按登录账号与当前聊天选定记录,读取时取得原数据,修改时提交完整新对象及旧版本号;JSON 工具返回数据/新版本,日记与表格返回各自文本 /memory 提供 JSON 读写;应用另有 Personalization、Axon、Hinos 接法,字段、保存时机与最终读取者分别说明
历史压缩 Compact 拿到历史后按长度条件判断;可同步压缩,或提前后台压缩供后续请求使用 有消息 ID/分组的原始聊天、旧摘要检查点、模型窗口与压缩配置;返回摘要+保留的最近历史 配置应用的 compact,并提供计数、压缩模型与检查点存储;不是主 Agent 自己选择的工具
上下文组装 世界书/记忆等资料已经取回后,真正调用 LLM 前 既有 messages、角色/对话区域下标,以及资料块的文字和位置;返回新的 messages 和放置记录 调 SDK placeContextBlocks,再把返回消息交给自己的模型;它不替你读取世界书或数据库
图片与视觉连续性 需要独立图片时调用;聊天配图可在正文已有片段后安排 图片描述、已有角色/场景视觉资料、参考图及任务参数;拿回任务/图片资产与状态,按入口处理展示和保存 公共 /image 与应用 Imagine 是不同接口;前台循环需配后端,Sumi 另有完整图文流程
长期指令 DIO 当前前台提交长期修改;后续回复准备时取有效角色提示词 真人账号 ID、这段聊天 ID、目标角色资源 ID、用户原始要求;先返回受理身份,稍后读取完整 compiledPrompt 配前台循环与 DIO 服务;后续 Actor 模板必须有可替换的角色提示词位置
下一句建议 角色回复后、用户发送下一句前;Story 需要正式正文已保存 目标助手消息 ID、对应的真实聊天及角色材料,另用建议模型配置;返回三个用户可选的发言 调应用的 auto_reply 入口,前端显示选项,选中后再按普通用户消息发送

一次回复前可能会用到好几项能力:世界书提供作者设定,记忆提供之前保存的记录,Compact 压缩过长的历史,最后由组装函数把这些文字放进模型消息。业务可以选择其中需要的部分,按各页说明配置或调用;这些步骤不会因为下载了仓库或安装了 SDK 就全部开启。

本次新增本次更新至 10 月 19 日已完成巡检。记忆新增可配置的故障处理:读取失败时,默认仍停止回复,研发也可以允许缺少这份记忆继续生成;Hinos 只对指定的服务故障允许这样处理。历史压缩修正了日记变化导致旧摘要失效的问题,回复模型仍使用本次取到的新日记。Sumi可以沿用聊天后端选定的模型,并按入口选择图文或纯文字;新图片任务的描述编译失败时,在满足条件且请求未取消的情况下,改用原始图片标签继续生成。

本次更新运行监控 #296与 Sumi 初始化追踪 #289 已进入主干,不再列为待合入;Sumi 已有 10 月 19 日 f9b26a9 的成功生产部署记录,实际开关和线上业务效果另行核验。SDK 最新发布仍为 0.6.0;Story 事件提示牌与原生 Pi 慢任务的已有能力保留,Core Tools 0.2.3 沿用此前发布核对记录。新的 DIO 跨轮更新、摘要质量检查和 #297 监控方案仍在开发分支,见本页下方。Worldbook 本轮没有新代码或部署记录。

包、源码与服务怎样对应 #

入口 这次固定源码中的版本或位置 使用方式
SDK @flowgpt/roleplay-harness;最新核到 0.6.0 已发布 在调用方进程执行。提供通用 Agent、原生 Pi 慢任务、注册表、上下文放置、观测,以及独立 /worldbook 客户端
本次更新Core Tools @flowgpt/agent-core-tools,此前已核 0.2.3 发布,本轮未重核最新 Release 可直接调用分析工具;/memory、/story、/image、/pi 按子入口导入。Story 工具支持 Omen 和 userPersona;现成 StoryV1 应用尚未传入 userPersona
Agent V2 / Story 应用实现 apps/emochi+adapters 仓内应用接线,需相应业务服务和配置。两个 npm 包没有整体导出这套产品
Worldbook worldbook-service 独立仓库 部署服务或接入已授权服务地址,经 REST / 业务适配调用;已有运行监控需另接抓取与看板

本次更新两个包发布到 https://npm.pkg.github.com,访问级别为 restricted,运行环境要求 Node.js ≥22。SDK 0.4.0、0.5.0 的 Release 和成功发包在 10 月 8 日已核到,0.6.0 于 10 月 9 日发布;Core Tools 沿用已核的 0.2.3 记录。安装前需要取得包的读取权限,按所需功能选择版本,再提供模型或世界书等依赖服务。SDK 0.6.0 的标签为 5e7c191,早于本次核对的主干 f9b26a9;安装这个包不会自动更新仓内应用的记忆、历史压缩和 Sumi 代码。SDK 0.6.0 · Core Tools 0.2.3

仓库、包与应用的归属 · SDK 包入口 · Core Tools 子入口与安装条件 · SDK 真实导出

开关写在它控制的能力下面 #

preActorDirector 控制前台工具编排,compact 控制历史压缩,storyV1 选择 Story 产品流程。它们是研发写进仓库聊天服务 config/scenarios/<入口名>.json 的设置字段,不在“模型可以调用的工具名”里。服务启动读取启用的入口文件,业务每次请求用 extensions.scenario_id 选其中一份;若使用环境变量提供设置,则依对应页的加载规则修改。每个能力页列出准确位置、默认行为、开启条件、互斥限制和生效时机。

如果希望工具按固定顺序执行,可以在仓内 ScenarioProfile 的 executionGraph 中定义步骤和依赖,并注册每一步实际执行的函数。现有 Router 不会直接运行粘贴进场景配置表的任意工具图;完整的代码接法见 编排与扩展。工具返回的内容也需要由调用代码放进模型输入。

接入后,用实际业务数据调用一次,检查返回内容是否正确,以及正文模型、聊天页面或存储是否收到了需要的结果。需要长期保存的内容,再发一条消息验证能否读回。工具返回 ok:true 只说明该次调用成功,正文是否被采用、图片是否展示、状态是否保存,还要检查后续代码的执行结果。

实验分支:可以参考什么,还没接进哪些地方 #

本次新增本轮新增核对的是 DIO #303、摘要质量检查 #305,并确认 #297 仍开放。下面的群聊和 Fusion 说明保留此前固定版本的结果;本轮没有重新逐项审查这些分支的最新代码。

项目 已写出的流程 当前所在位置与接入边界
GroupChat 群聊参考 先验证访问权限、选定故事和语言版本;用业务正式保存的消息确认上轮候选,再由 route 选发言安排、writer 写正文、ledger 整理状态。程序按旧版本条件保存新的 pending;下一轮再用正式消息确认 #261、#262 已合入 group-chat-spike,没有合入 main。真实业务的数据读取与保存接口仍须接入,跨章节推进的状态条件也有缺口;实验运行器不是现成上线的群聊产品
Fusion 的 Jev 编排 Actor 写一段后,规划模型再次判断;正常结束时明确选择 over。逐段写作指令已有参数合同,但当前 Jev 转换器尚未实际传入 #255 固定 e8b003c,仍未合入 fusion-harness;旧 finishResponse 被拒绝,预算、步数或失败仍可终止。已有图片槽重绘和可选 Narrative JWT 直连接法也在此分支;构建成功的运行跳过了实际部署步骤
Fusion 图片提示与 Rian 分镜工具 #292 在图片 Hook 接管且满足条件时移除重复生图提示;#293 提供 generate_storyboard_image,确定人物、准备分镜、编译图片描述后提交一张图 两者都是 draft,依次叠加在 #255、#292 上,均未合入目标分支。Rian 未找到业务服务调用入口;返回图片和分镜后,保存、费用、通知和跨次防重仍由接入方处理
本次新增回复完成后的 DIO 跨轮更新 完整回复结束后,由 Jev 判断是否有需要留下的长期要求,再提交 DIO;后续请求读取这段聊天的最新有效角色提示词 #303 仍是未合入草稿,默认关闭。已有构建与推送记录,没有应用镜像或等待服务就绪的部署记录;外部 DIO 的跨实例串行与去重仍是依赖。见长期指令
本次新增Compact 摘要质量检查 对已有摘要的增量更新进行检查;可只记问题,或在明确发现问题后重做一次并再次检查 #305 未合入、评审要求修改,默认关闭;作者离线报告的修复结果没有明确通过案例。见历史压缩
本次更新应用操作监控候选 #297 提议统计应用内操作、实际模型请求尝试与重试,并提供看板定义 仍未合入。主干已采用 #296,但两者统计口径不同,不能把 #297 的按请求尝试计数当成当前能力。详见运行记录与候选说明

群聊参考执行 · 群聊实验运行器 #262 · Fusion 当前动作转换 · DIO 候选 #303 · 摘要检查候选 #305 · 监控候选 #297

原子能力 / 应用模块

Actor:生成正文与前台工具编排

10/19 更新 · 本章 1 处从第一处开始看 →

用户说“让守卫接过钥匙,并配一张图”时,Actor 先根据角色资料和对话写出守卫的反应。需要配图时,程序可以把这轮回复分成几段,再把适合画出来的片段交给图片服务。用户最终收到的是角色正文,以及回填到对应消息里的图片。

负责这件事的代码在 apps/emochi/actor/roleplay-runtime.ts。启用前台工具循环后,控制模型通过调用 actor 来要求它写正文;写什么话由正文模型生成,接下来调用哪个工具由控制模型选择。代码中的 beforeHooks 则由程序在执行 Actor 前运行,用于准备或覆盖参数。

这套正文生成和前台编排属于仓库的聊天应用。接入它需要 Router 入口、Axon 资料服务、模型调用和聊天交付等依赖;也可以集成应用源码,自行实现这些适配。公共 SDK 根入口没有可直接导入并完成上述工作的 Actor 类。

已有聊天后端可以把请求交给配置好的 Router,由仓库应用读取角色、运行前台循环,再把正文交回自己的界面。如果继续使用自己的模型调用代码,就仍由自己的后端读取角色与聊天记录、构造消息、调用模型,并保存返回的正文;需要前台编排时,再集成下文的运行时。

下面先说明 Router 要收到哪些请求字段,以及应用如何把它们整理成模型输入。聊天界面仍由接入方负责:接收正文增量、展示最终回复,并把业务采用的消息存下来。

放在自己业务的哪一步,真正需要交给它什么 #

一次请求进入 RP 服务后,程序先用账号和角色 ID 读取资料,再按本轮实际延续的聊天路径整理历史,最后把组装好的消息交给 Actor。开启前台循环后,控制模型可以决定分几次写、何时配图或提交 DIO 长期修改;账号、历史和角色设定仍来自业务请求与资料服务。

下面用账号 user-42 与守卫莉娅的聊天说明请求怎么准备。ID 和文本都是教学数据,需要换成接入业务里的真实值。

接入方提供的字段 指什么、从哪里来 本例与必选条件
ChatRequest.requestId 本次调用的追踪 ID,业务生成;同一聊天的下一次调用是另一个请求 "rp-turn-101";用于生成、日志及派生工具请求
extensions.scenario_id 选择已部署的业务方案;程序据此取 Actor 模型、模板、记忆和可选前台循环配置 如接入方配置的 "my-roleplay";不是用户说“请用快慢系统”就能切换
extensions.turn_context.user_id 使用产品的真实账号 ID;用于读取这个用户的资料和调用外部服务 "user-42";闭环入口必填,不是角色名字
ChatRequest.conversationId 本次 RP 聊天 ID;用于资料和保存结果归属 "conversation-8";不能拿角色 ID 代替
ChatRequest.promptId 角色 Prompt 资源 ID;程序通过 Axon 读取对应资料 "lia-character";本字段不是角色设定全文,也不是模型配置 ID
extensions.turn_context.model_alias 业务侧对当前型号的别名,交给 Axon 构造模板变量 由接入方的型号映射给出;闭环入口必填。实际推理模型仍由允许的 ModelConfig 决定
extensions.turn_context.input_question 用户本轮实际原文;业务传入 "让守卫接过钥匙,并配一张图。";未提供时取请求中最后一条 user 内容,再否则用 "continue"
ChatRequest.messages 业务选定的当前聊天路径消息,每条有消息 ID、角色和文本内容;程序保留顺序后参与渲染 如 user“我来到城门。”、assistant“莉娅伸手拦住你。”;发生重生成/分支时,应传这次实际延续的路径,不是所有分支混在一起
extensions.turn_context.assistant_message_id 本轮将保存的助手消息 ID,业务提前分配并负责落库 如 "assistant-101";普通文字生成可没有,但当前聊天配图挂载需要它
turn_context.language / use_native_language 请求语言及语言选择标记,交给模型配置和提示词准备 如 "zh" / true;language 缺失默认 "en",use_native_language 仅显式 true 才开启
turn_context.persona_id 用户在故事中扮演的人设资源 ID,供 Axon 查资料;与使用产品的账号 ID 不同 可选正整数,如 17;不是自动创建人设的请求
turn_context.extra_set_vars / template_set_vars 接入方补充的字符串变量。前者传入 Axon 构造变量,后者在取回后合入模板变量 可选,例如模板约定的 user;必须有实际模板引用,填进去不代表一定进入模型

这是业务材料表;传输仍使用 Router 的完整 ChatRequest 合同,还要匹配服务的 agentProjectId / agentProjectVersion,指定 protocolVersion:"v1"、本页闭环接法的 extensionsVersion:"roleplay-harness/v2",并提供非空 modelConfigId、至少一条 message 和 generation.n=1。这些是请求能否进入服务的检查;请求中的 modelConfigId 不能代替 Scenario 的实际正文 ModelConfig 选择。表中字段按 TypeScript 合同名称书写,extensions 内的下划线字段保持原样。

程序用身份 ID 查找资料,再把取回的文本放进提示词。模型只能读到这次组装进消息的内容;记忆与世界书需要先配置相应读取流程,Actor 不会凭角色 ID 自行联网补查。

协议与目标检查 · 入口字段的读取与校验 · 本轮原文的选择 · 角色、变量与模型资料准备

程序准备之后,Actor 实际收到什么 #

仓内 generate(options) 使用 RPRuntimeOptions,并非接受一个“角色卡+问题”的裸字符串。下表把各字段拆开;采用现成入口时由应用填写,自建这条运行时接线时则要实现这些准备职责。

内部输入 实际内容和来源 谁使用
request Harness 传入的本轮请求:requestId 是调用编号,input 是用户原话,scenarioId 是所选入口配置名;本页 Router 接法中的 actorId 填真人账号 ID 前台控制模型直接读 request.input;生成及工具请求沿用身份
profile 聊天服务按请求中的 extensions.scenario_id 选定并加载的 Scenario,包括 id、modelConfigRef、presetRef、超时与失败政策 程序选模型和执行规则;这不是向模型提交的角色设定正文
axon.history 已经渲染过的模型消息数组,不是只有聊天历史。可包含 system 的控制/角色提示、实际保留的 user/assistant 历史和模板中的本轮问题 正文运行时作为主体输入;模板展开、必要的历史裁剪已在准备阶段执行
axon.roleplay 已解析的 modelConfigId、model、contextLimit、parameters、后处理、重试信息等 程序控制模型调用、输出额度、窗口和失败处理;缺少它不能运行当前 Actor
context 通用运行时接口保留的编译结果,含补充块及插入位置 当前这条闭环 Actor 的实际模型消息取自已准备的 axon.history;PreparedKaonRouter 不再把 context.blocks 自动拼进消息。二开只填这个字段,不能认为工具结果已经进入 Actor
signal 本轮取消/超时信号 中止进行中的生成;已经受理的外部任务另有生命周期
onDelta 聊天服务提供的回调函数,逐次接收正文增量,部分模式也接收 reasoning 增量 上层决定怎样发给聊天客户端;最终正文仍以结果 text 为准

采用 Compact 的入口,还要区分这组输入来自哪次处理:默认同步压缩会等待新摘要;显式优先后台模式获准时,本轮先用旧摘要与原文,后台成功保存的新摘要供后续请求采用。超限后显式选择 trim_history 时,本轮可能临时少带未总结的旧原文。角色卡兜底也只压短本次已渲染的角色定义,不回写角色卡。这些判断在 Actor 收到 axon.history 之前完成,详见 历史压缩。提交给本轮 Actor 的输入

教学示意:渲染后的 axon.history 可能是 system:"你扮演灰港守卫莉娅……" → user:"我来到城门。" → assistant:"莉娅伸手拦住你。" → user:"让守卫接过钥匙,并配一张图。"。具体还有哪些 system 消息、问题放在哪里、保留多少历史,由实际 PromptManager 和本轮准备结果决定;这段示意不是所有场景固定采用的模板。

运行时输入及结果类型 · 渲染后消息及执行配置 · Actor 实际创建的模型消息 · Router 使用已准备消息

两种实际运行方式 #

Actor 根据是否配置前台控制模型,采用下面两种运行方式。普通 V2 的后台专家、Story 的剧情调度仍在这段正文流程之外工作,因此即使 Actor 选择直接生成,完整产品也可能调用其他模型。

方式 谁决定执行 拿什么输入 返回什么
直接生成 程序调用 generate;没有 functionLoop 时进入 generateOnce 已准备的角色 Prompt、聊天材料、模型参数、本轮输入 流式正文、最终文本、模型使用信息
前台工具循环 前台控制模型每次选择一个动作,程序执行并把回执交回 控制模型先读工具政策与本轮用户输入;实际 Actor 使用自己准备的正文上下文 一段或多段正文组成一轮回复;图片/DIO 返回调度回执

控制模型的系统提示明确要求:通过函数控制一轮 RP,不直接写用户可见正文;读实际工具结果再选下一步,不按固定顺序机械调用。代码变量叫 planner,这里实施的是逐步选工具的循环,不需要先生成一个完整长期计划。它和普通 V2 后台的 Orchestrator 是两个不同接线。

在前台循环里,控制模型先选择 actor,程序再执行正文运行时,由正文模型写回复。Harness 还会在创建和执行 Actor 节点前依次运行 options.actor.beforeHooks,以准备或覆盖参数;这些 Hook 由程序安排,不出现在控制模型的工具菜单里。

是否开启前台循环 · 控制提示词与逐步调用

控制模型和写正文的模型,分别拿到了什么 #

以“让守卫接过钥匙,并配一张图”为例,两个模型的输入由程序分别准备;不是把完整聊天上下文复制给两边。

接收者 第一次收到的材料 后续增加的材料 这份材料用于什么
前台控制模型(代码名 planner) 工具选择政策、整轮 Actor 输出额度、步骤限制、本轮用户原话,以及实际挂载的工具定义 自己先前的工具请求、执行回执;自动配图时收到图片已安排的通知 决定接下来写正文、安排图片、提交长期指令或结束。不会因为 Actor 读过角色卡、历史、世界书,就自动获得同一份资料
Actor 正文模型 应用已经渲染的角色 Prompt、历史、本轮输入,以及该路径实际装入的记忆、状态、世界书等材料 本轮此前生成的正文;需要续写时加续写要求;每次调用重新设置剩余输出额度 写出用户实际阅读的守卫台词和动作;不负责在前台菜单里选择下一工具

因此,如果控制模型必须依据某条世界书规则决定是否调用工具,需要另外为它接入该材料;仅给 Actor 注入条目不够。Actor 的具体资料也以实际配置和最终 messages 为准,不能把表里所有来源理解成每个场景默认全开。

控制模型的完整初始消息 · Actor 累计正文与续写输入

模型真正可以调用什么 #

工具 参数 程序执行与回执 结果何时使用
actor responseMode 可省略,默认 complete;也可为 visual_beat 执行原有正文生成器,返回片段与消耗等信息 正文本轮流式交付;控制模型据回执决定继续或结束
generate_image {} 使用最新 Actor 片段安排图片,返回 scheduled 等调度信息 图片完成后回填聊天;调度成功不是图片已生成
schedule_dio {} 聊天程序将本轮用户原始长期要求交给 DIO,返回 accepted 外部编译完成且后续请求读到有效 Prompt 后才影响回复
over {} 在 Actor 至少执行过一次后结束前台循环 不生成正文,不保存角色状态

菜单至少包含 Actor 与结束;图片、DIO 只有相应执行能力接好才提供。循环最多 12 步,有 DIO 接线时额外允许 1 步。所有 Actor 片段共享有效 ModelConfig 的整轮输出额度。旧分支 actor({maxTokens:...}) 的接口不是当前主干参数。

前台循环的工具定义、参数解析和执行分支都写在应用代码中。扩展上表四个动作时,需要同时修改这三处;向公共 SDK 注册工具或在提示词里提到工具名,不会改变这个菜单。需要自己定义完整工具名单的业务可以采用 公共 Agent 接入。普通 V2 后台另外使用专家菜单和后台调度。

整轮 Actor 额度读取有效参数 max_tokens,缺失时使用 2,048。控制模型调用本身另有成本,不能把这个额度理解为所有模型的总 token 上限。某个 Actor 片段没有返回输出 token 计量时,程序按当时剩余额度全部消耗记账。正文是否能逐 token 显示还受整轮 after-hook、正则后处理与 visual_beat 缓冲影响;不能承诺所有配置都即时逐 token 透出。

visual_beat 是 Actor 参数,不是另一项工具。片段形成合格的完整视觉情节且循环还有下一步时,程序可以自动安排图片;已经配过图的片段不能重复调度。正好用尽步骤时,不能保证还有一次自动排图机会。

工具定义与参数解析 · 执行、步骤与预算

执行后交回什么,是否有再次检查 #

执行动作 交回控制模型的真实结果 用户与业务实际得到什么
actor 成功时含 ok、本片段 text、finishReason、本次及整轮 token 计量、剩余额度;部分失败返回 ok:false 正文按流式/缓冲规则交付;程序最终汇总为本轮回复
generate_image 调度成功时为 ok:true, scheduled:true, imageIndex 正文中产生图片占位,图片后端继续执行并回填;回执中没有已完成图片的质量验收
schedule_dio 受理回执;重复提交或服务失败时有失败回执 长期指令交给外部服务;不等于新 Prompt 已生效
over 程序检查是否已有正文及是否还有待配图情节,通过后结束 结束本次循环,不产生另一次回复或状态保存

控制模型读完回执后决定下一步,程序则检查动作、顺序、图片次数和预算。这里的检查到此为止:没有另一个 Review Agent 全面验收正文事实、图片质量和长期状态。例如收到“图片已安排”后,循环可以继续或结束,不会等待模型看过最终图片。需要图片审核的产品应再接入实际图片结果和审核步骤。

图片与 DIO 回执 · Actor 回执字段

怎样接入和配置 #

使用 apps/emochi 聊天服务时,研发在该入口实际加载的 JSON 文件中维护运行设置;代码把这一份设置叫作 Scenario。其中的 modelConfigRef、presetRef 等决定正文模型和模板,真实角色、会话、消息与历史则由业务请求和 Axon 提供。前台模型不能通过工具参数随意修改这些设置。

当前配置可以放在 config/scenarios/<场景ID>.json,由 HARNESS_ENABLED_SCENARIOS 选择加载,目录可用 HARNESS_SCENARIOS_DIR 指定;也支持既有 AGENT_ROUTER_SCENARIOS_JSON。两种同时使用且场景同名时,JSON 中的整项场景覆盖文件配置,不是逐字段合并。服务启动时加载,因此改了文件但未让部署加载新配置,不代表运行行为已经改变。

现成应用里的配置入口 接入时具体决定什么
对应 Scenario 的 modelConfigRef 指向 Axon 已存在的正文 ModelConfig;它再提供实际模型名、参数和关联 PromptManager。填一个新字符串不会创建模型配置
presetRef 与实际 prompt_manager presetRef 是方案中的模板引用;正常准备使用 ModelConfig 返回的 PromptManager。显式切换 PromptManager 时,必须通过 allowedPromptManagerRefs 等允许范围检查
ModelConfig 的 parameters.max_tokens 与 context_limit 前者控制正文输出额度,后者控制模型窗口;前台多次 Actor 共用整轮输出额度,历史裁剪/世界书计数另按实际路径执行
preActorDirector.modelConfigId 可选的前台控制模型;不填 preActorDirector 时直接正文生成。填了它也不会替换正文模型
defaultTimeoutMs、retryPolicy、后处理与恢复配置 研发在聊天入口配置中规定整轮时限、允许的普通重试、后处理及专用恢复;具体失败范围见本章原有说明

如果选择前文的“保留自己的聊天代码”,还要搬用仓库前台循环,研发需要在代码中接入 ClosedLoopRoleplayRuntime、RoleplayAxonAdapter 与 Harness 装配,并实现上面的模型、资料与服务依赖;这属于应用源码集成。若只是让自己的主 Agent 选择“生成一次正文”,也可以将自己的正文生成代码包装为一个工具执行器,再注册给主 Agent。应用里的 actor 函数名不是公共 SDK 已自动注册的工具;公共 SDK 的自定义工具名单与这里四动作菜单是两条接法。

Scenario 文件选择与覆盖 · Scenario 配置解析 · 模型与模板覆盖的允许范围 · 当前应用装配运行时

配置 preActorDirector 后,当前 dispatch 装配前台 functionLoop。其 modelConfigId 是前台控制模型,skills 含已授权预设;配置含 afterActorTools: ["generate_image"] 的图片预设、imagePromptProducerPrompt、图片后端依赖,以及本轮 assistantMessageId,才形成当前图片调度接线。DIO 也需要独立服务接线。不能只向模型展示工具名,却不给程序实际执行器。

已有配置能正常生成角色正文后,可以加入以下片段,让程序创建前台循环。示例只列出新增设置;模型配置 ID 要替换为接入方的实际值,原有正文模型、模板、超时等设置继续保留。

{
  "preActorDirector": {
    "modelConfigId": "your-front-control-model",
    "skills": [{
      "name": "roleplay",
      "description": "继续当前角色对话",
      "actorParameters": {}
    }]
  }
}

先验证它能经 actor 返回正文并结束,再按业务需要增加 聊天配图 或 长期指令 的执行依赖。skills 必须是非空配置数组,actorParameters:{} 是合法空对象;这里没有启用图片。DIO 是否进入菜单还取决于部署是否提供其服务依赖。完整应用的请求入口、正文模型和角色模板继续使用已有配置。前台配置校验

聊天服务的配置字段与 Hook 执行位置
位置 字段或接口 改变什么
Scenario preActorDirector.modelConfigId 选择前台控制模型,不替换 Actor 模型
Scenario preActorDirector.skills 已授权技能预设;当前 dispatch 从其中识别图片接线
Scenario preActorDirector.imagePromptProducerPrompt 图片描述生产的系统提示;不是 Scenario 根级字段
调用 Actor 时传入的参数 options.actor.parameters 聊天程序指定本次要覆盖的模型、Prompt 或模板变量,仍需通过实际允许范围校验
Actor 执行前 options.actor.beforeHooks 程序依次运行 Hook,将返回字段合入 Actor 参数
仓内另一可复用实现 selectPreActorSkill / createPreActorDirectorHook 提供 actor({skill}) 的单次预选方案;不是当前 dispatch 使用的前台循环协议

Story 配置仍明确排斥 preActorDirector;Sumi 仍排斥这套前台循环、普通 V2、Compact 和其他记忆 Hook。9 月 22 日主干已允许前台循环显式配置 worldbook:条目进入 Actor 正文材料,控制模型不会因此自动读到同一份原文。世界书同样可以接普通 RP、Compact、普通 V2、Story 与 Sumi 各自的正文路径;是否已接世界书和采用哪种协调器是不同配置判断。当前兼容条件 · Worldbook 与前台循环接线顺序

图片预设与前台循环装配 · 预设选择接口 · Actor 参数与 beforeHooks

世界书放入后,循环和换模型怎样控制窗口 #

同一轮先解析角色 Prompt 绑定,再选择一次所需条目;每次 actor 调用和重试都沿用这次选取,却要按实际目标模型、剩余输出额度、累计正文和循环指令重新渲染、计数。条目没有写回聊天历史,因此不会因为循环执行多次就变成多条新的正式聊天消息。

预算不足时只试裁最老历史,固定提示、本轮输入、世界书、不可压缩系统材料、续写边界和循环控制保留。某个重试模型放不下时拒绝该目标;普通重试队列有后续目标时再尝试,失败目标的试裁不会削减下一目标本来能用的历史。只增大世界书选条目额度不保证最终模型容得下全部输入。重新渲染和历史试裁 · 每次目标预算检查

早期拒答恢复:为什么第一段可能稍晚出现 #

用户可能先看到“莉娅接过钥匙,低头看了看——”,随后模型连接中断。主干现在按是否已经向用户发出正文,选择两种恢复:尚未显示时,可以丢弃失败尝试并用备用模型重新生成;已经显示了 Gemini 的部分正文时,满足流完成与预算条件才用 DeepSeek 接着写。下面按固定 main 43332d8616b4e24874915a69cdea7bdaa0429aba 说明,恢复都需要配置 recovery.transientRetryModelConfigId,不会因普通请求自动开启。

原本能即时流式输出的主尝试,会先暂存正文。正常完成,或首个非空正文片段到达满 4 秒,满足任一条件就释放。完全空响应没有首个片段,所以结束时立即进入空响应判断,不额外等 4 秒。有整段后处理的调用仍遵循自己的缓冲方式;没有配置备用模型时,不增加这段恢复缓冲。4 秒是源码常量,从首个正文片段而非用户发送请求起算,也不代替整轮超时。缓冲启用条件 · 恢复常量

当时发生了什么 程序怎样处理 用户收到什么
主模型在缓冲中正常完成 释放正文,再完成原有后处理 短回复可能一次出现,不必等满 4 秒
尚未发出可见正文,出现空响应、识别出的 provider 拒答或符合资格的上游错误 丢弃未发内容,按备用 ModelConfig 重新准备参数和输入,最多重新生成一次 备用模型成功后交付完整回复
首次 Gemini 尝试已发出可见正文,在可信完成前中断,且满足下文条件 保留已写正文作为 assistant prefix,只请求一次 DeepSeek 续写 已有正文后接上新后缀;不会先撤回原文
已有明确结束标记后才失败,或不满足 Gemini 续写条件 向外报告失败 可能已看到部分内容,仍不能当成完整成功
备用重生成或续写也失败、续写没有新可见正文 结束恢复并标记已经尝试过,不再循环换模型 返回失败;已发出的文字不会因此自动撤销
用户取消或相应生成时限已到 停止生成,不因取消另开备用请求 按取消/超时路径结束

尚未显示正文时,Gemini 恢复已经覆盖由 Kaon 标明来源的 HTTP、SSE、嵌套 Google error envelope 等上游失败,不再只看 429/500/503 或供应商是否标为可重试。程序仍拒绝本地校验/预算错误、已执行过恢复的错误,以及 DeepSeek Flash/0731 自身再发起恢复。其他模型仍按 router.content_filter、router.empty_response 或 429/500/503 等既有条件判断。普通角色台词中的“我不能”不会被猜成供应商错误。备用 ModelConfig 的实际模型只允许 kaon/deepseek-v4-flash 或 kaon/deepseek-v4-flash-0731。错误来源与恢复资格 · 未发正文时的切换

已显示的 Gemini 正文怎样接着写 #

程序必须确认首次实际模型为 Gemini、已配置备用 ModelConfig,并且请求参数没有另覆写成其他模型,才为该请求启用严格流完成检查。续写还要求已经发出可见正文、尚未收到明确的 finish reason、错误没有标记流已完成,并且请求与本次尝试都未取消。只有 reasoning、正文仍全部留在缓冲中或尚未出现可见正文时,走上面的重新生成分支。原始模型消息必须是可计数的 system/user/assistant 纯文本消息,否则续写失败关闭。严格检查入口 · 可见前缀和未完成条件 · 纯文本消息检查

例如“莉娅接过钥匙,低头看了看——”已经发出,程序保留原始模型输入,再追加带 prefix:true 的 assistant 消息。续写请求使用固定路由 deepseek-beta/deepseek-v4-flash,请求 ID 加 :deepseek-continuation;配置的备用 ModelConfig 仍提供参数、tokenizer 与窗口。程序先从原输出额度扣除 Gemini 已消耗的输出,包括可计量的 reasoning,再取备用输出上限与剩余额度中较小值。没有剩余额度、目标窗口不明确、原输入加前缀放不下、计数失败或恢复时间预算已用尽,都不会冒险继续。发送给计数接口的消息只有 role/content,prefix:true 只发给生成供应商。剩余额度与目标检查 · 实际续写请求

续写沿用同一个正文过滤器和后缀保护,避免交接处半个标签或空白被当成两份独立回复处理;成功必须增加可见正文且正常结束。两次请求的 usage 合并;缺用量时按已观察到的输入、正文和 reasoning 计数,并记录估算来源,未观察到的 reasoning 仍未知。任一次没有可靠 cost,就不提供仿佛完整账单的合计 cost。续写成功也不会替聊天服务保存正文,最终结果仍按下节交付和提交。后缀、成功条件与用量合并

旧式 SSE 的 [DONE] 兼容仍保留:同时启用既有 allowMissingFinishReason、ignoreMalformedStreamEvents 且实际收到 DONE 的流,不会仅因缺 finish reason 就被改判为未完成。另一个显式选项 tolerateMissingStreamMetadata:true 只会在收到 DONE、有正文、没有畸形事件或未知结束原因时补出 stop。既没有可信结束标记又中断的流不走此兼容;DeepSeek 续写请求明确关闭这三项宽松选项,要求可靠结束。DONE 兼容和元数据推断 · 续写的严格设置

配置备用模型后,每次 Actor 生成最多使用主模型与一次重生成或续写,不再叠加普通 retryCount;前台循环若多次调用 Actor,各次分别受此限制。没有配置备用模型时,仍走原有普通重试。受控测试覆盖中断续写、预算、取消、过滤器和旧流兼容;真实 Gemini→DeepSeek 的语气衔接、重复内容、时延与成本,以及当前 workload 是否已采用这些提交,尚未验证。次数分流 · 续写后不递归恢复

Fusion 分支的并发备用请求与正文等待上限 #

fusion-harness 的固定版本 c75dabb942bcf5ab00e2cadbabd95ef961203e69 另外实现了并发备用请求和 Narrative 正文 watchdog。这两个机制属于 Fusion 入口,不能从它们推断上述 main 或 Story 的行为。Fusion 的 narrative-fusion/agentic-v2-luna.json 显式配置 hedgeDelayMs:5000、retryOnAnyUpstreamError:true:主请求迟迟没有可用结果时,5 秒后另发 DeepSeek,先成功的一方获胜并取消另一方;可恢复错误也能提前触发备用。Actor 先过正文过滤和后缀保护,即时流式时以首个可见正文取得资格,缓冲模式则等流完成。双方失败或外部取消会结束竞争。只取消败方不能证明它没有产生费用;当前调用链只消费赢家 stream,用量不能当作两边完整账单。Fusion 配置 · 并发与取消 · Actor 可用结果判定

Fusion 的 retryOnAnyUpstreamError 缺省为 false;启用后扩大 TypeError、SyntaxError、TimeoutError,以及符合来源条件的上游错误/轮次超时的恢复,但明确排除 router.content_filter。main 43332d8 没有这个配置字段,解析器只接受 transientRetryModelConfigId 与 tolerateMissingStreamMetadata;main 对 Gemini 的扩大恢复依据前文的错误来源规则,复制 Fusion 字段到 main 会被拒绝。Fusion 错误条件 · main 的配置校验

Narrative 的 incremental 入口在执行生成前开始计时,20 秒内没有新的 actor_text 就取消;planner 活动不会重置,所以较慢的规划也可能用掉这段时间。正文完成后立即清计时器并关闭文字流,随后图片准备失败只将相关 pending 图片改为 failed,保留已完成正文。生成失败时只有 receipt 处于 generating/reserved 才自动回滚;保存或提交结果未知时留待对账。9 月 24 日最新巡检已取得 Fusion 后续版本 c8fc61c 的生产 rollout 记录,包含这些恢复机制及后续改动;当前运行 digest、20 秒误杀率和真实费用仍未核实。后续部署记录 · 计时与活动 · 正文完成后关闭 · 图片失败回写 · 回滚条件

Fusion 仍在开发的 Jev 工具决策 #

本次更新本节沿用 10 月 13 日的分支核对记录;10 月 19 日巡检未重新审查其 head 和部署状态。截至该次核对,PR #255 仍未合入目标分支 fusion-harness;本节按当前候选 e8b003cc1e64541803a60b3e22c30e558747b7f1 说明。它的正常回复过程已经改为:Actor 写一段 → 前台控制模型读实际结果 → 决定再写、调用可用工具,或用 over 结束。 over 采用已经生成的文字,不再多调一次 Actor。此前用 finishResponse 告诉 Actor“这一段写完即结束”的接口已被拒绝。

例如用户说“让莉娅带我进城”。Actor 先写出莉娅核对手令的结果,控制模型看完这段,再判断是否需要写开门的动作;完成这轮需要的内容后选择 over。这仍不代表程序一定等到 over 才停止:输出预算耗尽、步骤达到上限、失败或取消都有独立出口。多段正文共用整轮 Actor 输出额度,不能把每一段当成一次完整新额度。

候选也给通用循环增加了 instruction,让控制模型可以说明“这一段角色要做什么、怎样承接上一段的结果”。它作为临时要求进入该次 Actor 请求,后续段落以实际已写正文为基础,不把前一段指令混成正式聊天历史。当前 Jev 适配器尚未生成这段指令:它仍只选择动作,并在图片工具可用时给出 generateImageAfter。因此可以说循环已经能接逐段指令,不能说 Jev 已经实际为每段安排了因果导演文本。Jev 实际返回字段 · 工具合同与参数检查

菜单里有 schedule_dio 时,模型仍被要求检查本轮工具轨迹,同一原始用户要求最多提交一次。受理成功后程序会阻止再次调度;提交失败后,程序仍可能接受重试,所以“失败也不再调用一次”依赖模型遵守指令,不是新增硬计数器。受理只表示后台排队,本轮继续用已经准备好的 Actor 提示词,后续请求读到新版本后才采用。此约束在 10 月 9 日基线已存在,不能再次列作本次首次新增。DIO 的提交、保存和生效

依赖这条分支的 #292 还在调整图片分工:已有图片 Hook 决定插图、且用户未明确要求每段配图时,从前台菜单和自动附加的提示中移除重复图片要求;不满足条件时保留原合同。它和后续 Rian 分镜工具 #293 都尚未合入,具体输入、返回和接线范围见 Fusion 图片候选。

同一候选还允许 Narrative API 显式切换为用户 JWT 直连:接入程序发送用户 Bearer,服务验证后采用其中的用户身份,不信任同时传入的 x-user-id。默认仍使用 gateway 接法;开启 NARRATIVE_AUTH_MODE=jwt 需要配置公钥,有 Origin 时还检查允许来源。复用 Pioneer 的鉴权函数不表示新增会员周期限制。模式配置与实际鉴权

本次核到 #255 的 staging 运行虽然显示 success,但只有构建和镜像推送成功,kubectl、EKS 鉴权和实际部署步骤全部跳过。因此这里仍按未合入候选描述,不据此宣称已部署或被业务采用。运行与跳过的部署步骤

候选的执行次数、兼容字段和失败出口

前台最多 12 次决策,接好 DIO 时为 13 次;总可见输出读取有效 ModelConfig 的 max_tokens,缺省 2,048。over 要求已有至少一段 Actor 输出;旧 finishResponse 不在允许参数中。instruction 若提供必须非空且不超过 1,000 字符,兼容的 responseMode 仍只接受 complete / visual_beat。

非法控制模型回执有一次纠正机会。已有正文时,部分控制模型/Actor 可恢复错误可以保留正文;首段失败、取消等继续按各自错误规则处理。尚未生成任何片段且预算仍允许时,有直接 Actor 兜底。这些分支解释了为什么最终停止不一定对应一次成功的 over 调用。

循环与出口 · 临时逐段指令

保存、失败与下一轮 #

Actor 完成后会返回最终正文和执行信息。下面是一次成功调用的教学结果,token 与耗时仅作示意;聊天服务随后还要决定是否采用并保存这段正文。

{
  "text": "莉娅接过铜钥匙,低头确认齿纹。\"钥匙没错。你的手令呢?\"",
  "finishReason": "stop",
  "artifacts": [],
  "durationMs": 1200,
  "tokenUsage": {"inputTokens": 600, "outputTokens": 48, "totalTokens": 648}
}
返回给谁的字段 怎样使用、是否保存
text 后处理后的最终正文,交给聊天服务展示并决定是否落库;下一句由业务把已采用正文放回 messages,角色才会读到这次“接过钥匙”
rawText / reasoning(可选) 原始生成/推理内容,可能交给已配置的记忆写入或诊断;不应直接当作用户可见正文。各模式不保证都有
finishReason / partialResponse(可选) 区分正常停止、长度截止、内容过滤及部分返回等情况;不等于图片或后台状态都成功
tokenUsage / durationMs / promptMessageCount / promptByteLength / promptSha256(部分可选) 消耗、耗时及本次输入追踪信息,供成本与排障;不是要塞回下一轮角色记忆的内容
artifacts 统一返回结构中的资产引用数组。当前图片动作返回调度回执,最终图由消息回填链路交付,不能假定 Actor 的 artifacts 已包含成图 URL

聊天界面可以先显示 onDelta 收到的增量,生成完成后以最终 text 为准。业务按原有采用规则,将它绑定到预分配的助手消息 ID 并保存;下一句再把这条正文放回当前路径的历史中。用户取消、重生成或切换分支时,保存记录和下一次 messages 都要跟随实际选择。图片继续等待对应消息的资产回填,专家状态和记忆则按各自流程写入。

前台循环还会把每次片段结果交回控制模型,例如 ok:true, text:"莉娅接过铜钥匙。", outputTokens:20, remainingActorTokens:2028;这是供它决定是否续写/配图的中间回执,与上面的最终正文结果不同。输出计量缺失时的记账规则、循环失败及恢复边界仍按前文执行。

Actor 的保存职责限于把整轮后处理后的正文交回聊天服务;NPC 卡片、世界书和普通 V2 的持久状态各有自己的写入流程。前台控制失败时是否回退或保留已有片段,取决于失败发生前有没有得到可用正文,具体规则如下。

走完整 TurnHarness 时,程序取得最终正文后,还会等待配置的 memory.ingest:传入本轮输入、最终输出、可用的原始输出/reasoning、身份及版本信息。写入失败按 memoryIngest 的 fail_turn 或 best_effort 处理,然后才决定是否发出 turn.completed。具体写到哪里由选中的记忆适配器负责;这个阶段与聊天正文落库、普通 V2 后台状态保存是不同接线。下一轮要读回所保存内容并放进模型输入,才会产生持续作用,详见 记忆读写。

正文完成到记忆写入及完成事件

具体而言:控制模型报错、返回非法工具请求或用尽步骤,而没有任何可用 Actor 结果时,进入直接生成回退;已有结果时结束循环并后处理已有片段。Actor 调用先按自身配置完成允许的重试或恢复;若后续调用仍发生空回复或超时、且前面已有完整片段,会把失败回执交给控制模型继续决定。首次 Actor 调用最终失败、其他不可恢复错误或外部取消会传播;不能统一理解成“所有失败都返回已有正文”。已被外部图片或 DIO 服务接受的任务,也不因这段文字生成后来失败而自动撤销。

接入后可以用“守卫接过钥匙,并配一张图”走一遍完整流程:确认正文先可用、只安排一张图、图片绑定正确消息,并观察图片失败时界面如何展示。再发下一句,检查模型读取的历史确实包含业务已保存的那段正文。

控制失败与正文回退 · 整轮后处理

原子能力 / 公共工具包

六类分析工具:给出建议,由业务决定采用

角色突然知道了没见过的秘密、答应过的事没有下文、场面迟迟不转换,这些问题可以交给对应的分析工具检查。你的产品可以保留现有角色与对话流程,只在需要时调用这一组工具。

六个工具由 @flowgpt/agent-core-tools 导出,使用接入方提供的模型与资料生成分析文字,并返回模型使用信息。它们都标记为 advisory: true:分析完成后,要由业务决定把建议交给写作模型、整理为状态还是不采用;工具自身不修改聊天、人物卡、世界书或数据库。

这里的“公共”指包的可复用导出 API。仓库发布配置是 GitHub Packages、restricted 访问,接入发布包需要相应读取权限,并不代表公共 npm 可匿名安装。

例如用户说“我把未拆封的信递给 Mira”。程序先取出角色卡、已有对话和保存状态,再调用 audit_knowledge 检查信息边界。它可能返回“Mira 没有依据知道信中内容”,程序随后把这段意见交给写作模型,或者留给后续状态整理。信件数据库的读取和用户回复仍由原业务负责。

接法 谁决定调用 结果交给谁、何时生效
已有普通 Agent V2 后台 后台调度中的 Orchestrator 按规则和模型判断选择专家;应用已绑定各专家模型与岗位提示词 结果交回 Orchestrator;若选择 Director,再由它整理完整状态,程序校验并按版本保存。后续请求读到新状态才采用;本轮并行 Actor 不会自动收到这份新建议
保留自己的聊天代码,增加一次固定检查 研发在原有“调用回复模型”之前插入 execute;原聊天接收、模型调用、展示与保存代码继续使用 等结果后,把分析文字加入本次回复模型输入;若放在回复后的后台执行,就用于之后的步骤或下一轮
自建可选工具 Agent 二开方注册工具后,由主模型从允许的工具菜单选择 工具结果回到主模型的工具消息,它据此继续回答或调用别的工具;持久化仍由二开方另接

这六个工具只负责分析。完整应用还会使用 Director 整理状态、Actor 写正文,以及图片、长期指令等能力;这些分别有自己的配置和执行流程。 普通 V2 的专家接线 · Director 采用与保存 · 前台工具

每个工具具体干什么 #

工具与导出类 检查什么 业务输入例子 结果怎样采用
analyze_plot / PlotTool 主线、当前情节和分支是否需要变化 “用户拒绝了原定任务,接下来怎么办?” 返回推进建议;产品决定是否写入剧情计划或下一轮约束
judge_npc / CharacterTool 人物身份、数量、动机、知识、位置、出入场与连续性 “一个新守卫出现,他凭什么认识用户?” 给人物连续性建议;不自动生成独立 NPC ID 或完整卡片
audit_knowledge / KnowledgeTool 事实、秘密、谎言、猜测、证据,以及谁知道什么 “信封没打开,Mira 能否知道信里内容?” 明确信息边界,供写作或状态整理采用;不会自动搜索世界书
simulate_world / WorldTool 时间经过、位置、期限与镜头外活动 “用户离开酒馆三天,约定是否过期?” 给出需要考虑的世界变化建议;不等于 Story 的事件状态引擎
manage_callbacks / CallbackTool 承诺、线索、物件、伤势、义务、伏笔和延迟影响 “借的钥匙还没还,要记住哪件事?” 提醒持续追踪,不强制马上让伏笔发生
direct_scene / SceneTool 视角、镜头、场面与角色自主行动尺度 “守卫能主动拦路,但能替用户作决定吗?” 输出场面建议,提示词要求保留用户行动自主权

六工具定义 · 公共导出与工厂

调用前究竟要准备什么 #

普通 V2 已经实现了专家调用前的准备工作,接入方主要维护模型配置与岗位提示词。自己的聊天后端则需要实现模型调用,并从现有角色、消息和状态存储中取得材料。对应改动如下。

接法 研发实际要做的事 完成后得到什么
已有普通 V2 在该入口实际加载的 config/scenarios/<ID>.json(或环境 JSON 对应场景)维护 agenticV2.modelConfigs.specialists。六个键就是下表工具名,值是 Axon 已有 ModelConfig ID;各 ModelConfig 的 PromptManager 要有对应 specialist_<工具名> 岗位提示词,例如 specialist_audit_knowledge。保留原有 Actor、Orchestrator、Director 及其他必要配置,重新加载部署 应用取回正确模型和岗位说明,供后台选择。只改一段角色卡文字不会替换专家岗位;配置齐全也不代表每轮六个全部调用
自己的后端直接调用 取得工具包权限并导入工厂;实现 model.complete,传专家 system prompt;从自己的角色/消息/状态来源整理下表 context 调一次分析,收到结果后接回自己的写作或保存流程。无需为了这一项迁移到普通 V2,也不需要伪造公司的 Scenario 配置
自己的主 Agent 按需选择 先完成上一行,再提供工具包装并注册到该 Agent 的实际工具列表;包装负责将这次已认证的会话资料绑定给工具 主模型只填写 reason/focus,程序补齐材料并执行。仅把函数名写进主模型提示词没有执行能力

例如普通 V2 的配置字段 agenticV2.modelConfigs.specialists.audit_knowledge="knowledge-model-1",表示去找名为 knowledge-model-1 的模型配置;专家真正的检查职责来自其 specialist_audit_knowledge 提示词。独立直调则直接传 prompt 字符串,不会自己去找 PromptManager。model.complete 要把收到的 messages 发给你实际接通的模型,并返回 {content,modelConfigId,model,usage?};只传一个模型名称字符串不满足这个接口。应用配置读取 · 岗位提示词读取 · 独立模型适配契约

模型可见参数是 reason(为什么咨询)和可选 focus(这次重点)。调用工具的聊天后端负责取出角色卡、已保存对话和旧笔记,并按当前登录账号及聊天 ID 提供材料;专家不会因为收到工具名称就自动查询数据库。

默认 RP 接法需要下表这些材料。身份应来自已认证请求,剧情事实应来自实际角色、历史和状态记录;必填字段也要传真实值。表中的值只用于说明格式。

字段 谁准备、是什么意思 例值与必选条件
arguments.reason、arguments.focus 主模型选择工具时给调用理由;固定流程由程序填写 必填 reason:核查未拆封信件的信息边界;可选 focus:Mira 能否知道信中内容。不把长历史塞进这两个字段
context.character 聊天后端读取当前角色卡;name 名称、description 简介、definition 原始设定、openingMessage 开场白 四个字符串字段必填,例如 Mira/城门信使/只能知道亲眼所见或被告知的事实/“你找我?”
context.question 本轮真实用户输入,不是专家的分析题目 必填:我把未拆封的信递给 Mira。
context.history 聊天后端按当前聊天路径取回已保存的对话,元素为 {role, content} 数组必填;例如 [{role:'assistant',content:'Mira 在门口等你。'}]。没有历史可传空数组;工具不会自己查聊天库
context.state 聊天后端从状态存储读出的旧笔记对象:state 是状态正文,ledger 是结构化连续性记录;revision 是存储版本 必填。首次没有状态可用 {found:false,revision:0,sourceTurn:0,state:'',toolsCalled:[],ledger:[]};后续应传实际读取值,不能一直重置为零
context.userPersona 用户本次扮演的身份,不是角色卡 可选:用户是第一次来城里的学徒;默认提示要求不把 Persona 直接当作剧情已证实的事实
context.compactSummaryText 或 context.compactSummary 聊天后端从摘要存储或 Compact 本次结果取得的较早对话摘要 可选、二选一。前者是文字;后者为 {canonical,interaction,open_threads},分别放稳定事实、互动摘要、未完事项。工具不负责先生成摘要
requestId / scenarioId / userId / conversationId / sourceMessageId / sourceTurn 都由聊天后端填入 context:本次调用编号、所选入口配置名、真人账号 ID、当前聊天 ID、此次分析关联的角色回复消息 ID,以及本次分析对应的轮号。sourceTurn 例如第 7 轮填 7;普通 V2 根据用户消息数量和服务返回的对话长度推导,自建后端按自己的轮次规则提供。工具不自行数轮,也不据此决定累计几轮才触发 必填,例如 req-7 / my-rp / user-1 / chat-1 / assistant-7 / 7。供后端将分析关联到对应账号、聊天和回复;工具不会凭这些 ID 自动取得数据库内容
context.language / useNativeLanguage 聊天后端指定的输出语言与 useNativeLanguage 标记;仓库应用把两者交给 Axon,查询适用于该语言的模型配置 必填,例如 zh-CN / false;可选 historyRevision 标记历史版本、trace 传追踪信息
prompt / model / signal prompt 是这个专家的 system 岗位说明;model 是真实模型调用适配器;signal 控制取消 每次调用必填。只有一个工具名或一段角色设定,还不能执行专家模型调用

默认编译器把角色资料、开场白、Persona、旧状态、摘要和最近对话、本轮用户输入、reason/focus拼成一条 user message,再配上研发传入的 system prompt 发给专家模型。默认历史投影只取过滤后的最后 9 条 user/assistant 消息;Persona 最多 4,000 字符;状态投影使用 6,500 字符预算。这些是字符投影规则,不是模型完整上下文窗口。身份 ID 主要用于调用关联,不是把数据库内容带入模型的捷径。

如果你的业务需要完整世界书条目、外部事实或更长历史,先由聊天后端查询并取回原文,再通过 compileContext 自定义 user message。系统岗位提示词由调用者另行传入。编译器是同步格式化函数,本身不做网络检索。

上下文与模型适配接口 · 默认输入投影

调用专家工具的代码示例 #

下面在自己的聊天代码中直接调用一次知识检查。context 按上表读取,model 使用已经接通的模型适配器,signal 沿用本次请求。示例岗位提示词用于展示调用方法,正式业务应补上自己的知识边界规则。

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

const systemPrompt = '检查人物知道哪些事实。只依据给出的角色资料和可见历史,区分已知、猜测与未知;返回写作建议,不编造缺失证据。';
const tool = createAgentCoreTool({
  name: 'audit_knowledge',
  modelConfigId: 'your-knowledge-model',
  modelCallTimeoutMs: 15_000,
});

const result = await tool.execute({
  context, model, prompt: systemPrompt,
  arguments: { reason: '核查信息边界', focus: 'Mira 是否看过未打开的信' },
  signal,
});
if (!result.ok) throw new Error(result.error);
// result.result 是分析文本。这里交给业务采用,不会自动写数据库。

让主 Agent 按需选择时,可以用 /pi 的 toPiTool(tool, prepare) 包装默认 RP context 工具,再把它放进 Pi Agent 的 tools 列表。prepare 绑定真实上下文、模型和提示词,包装层校验 {reason, focus} 并将执行失败转成工具异常。固定流程直接调用即可;使用自定义 compileContext 和业务 context 的 Agent,则应按 SDK 示例编写相应包装,不能直接套用要求角色与状态字段的默认 RP 包装。

参数校验由 toPiTool 包装执行,prepare 负责准备业务材料;如果绕过包装直接调用 .execute,应在直接调用它的代码中检查工具参数,不要把暴露给模型的 JSON Schema 当作该直调入口已自动执行的校验。

完整假模型直调示例 · 模型选择工具的完整示例 · Pi 工具适配

拿回的到底是什么,如何交给下一步 #

直接调用会拿到下面这种对象。例中的 result 是模型生成的分析文字,措辞每次可能不同;它没有 NPC 卡或状态补丁的固定字段。

{
  "ok": true,
  "tool": "audit_knowledge",
  "result": "Mira 只看见了未拆封的信,没有依据知道信中内容。后续可以询问信件来源,或等用户拆封后再获知秘密。"
}

实际还可能附 usage。用 Pi 包装时,主模型收到的工具内容是 content:[{type:'text',text:分析文字}],原始结果对象放在 details;因此主模型读的是建议文字,不会自动得到一份可直接写库的状态补丁。普通 V2 则把各专家的成功分析/失败原因汇总到后续模型输入,Director 若被调用,会结合旧状态重新生成完整状态文本。

如果检查安排在正文生成前,就把分析结果加入原来的模型请求。例如在“控制说明+角色资料+历史+本轮问题”中,插入“本轮知识检查意见:Mira 未读信件,不知道内容”,再调用原回复模型。这样意见才会影响角色的话;只记日志不会改变生成,把分析文字直接显示给用户也还没有完成角色回复。若分析在回复后运行,就由业务保存采用后的约束,在后续请求里读回使用。

信件检查返回时,程序得到的是一次分析;加入写作输入后,它才影响那次生成;写入持久状态后,之后读到该版本的请求才可能继续使用。已有 V2 会让 Director 结合旧状态整理候选,检查通过后按版本条件保存状态、调用记录和连续性条目。专家成功并不保证这次提交成功,也不会把意见另存成世界书条目。 返回契约 · Pi 给主模型的内容 · 普通 V2 汇总专家文字 · 通过检查后的实际保存字段

配置、保存和失败边界 #

项 实际行为
调哪个模型 modelConfigId 填你实现的 model.complete 能识别的配置 ID;这个适配器负责按 ID 选真实模型与参数。仓库应用由 Axon 查询配置,独立 SDK 不会自动查询
岗位提示词 每次调用的 prompt;不是六工具包内自带完整产品提示词
模型重试 通常最多初次+2次重试;取消、内容过滤、已发生恢复或特定上下文错误可提前停止
超时范围 modelCallTimeoutMs 随每次模型请求传给你实现的 model.complete;重试仍传同一个值。工具没有用它建立覆盖全部尝试的总计时器;整项等待预算由调用方的 signal 控制
结果长度 默认整理为最多 5,000 字符。contextGovernance 的 enforce 下超出结果额度会返回失败,而非照常采用
返回 {ok, tool, result?, error?, usage?};Promise 正常 resolve 仍可能 ok:false。contextGovernance: enforce 的计数不可用/上下文溢出错误会向上抛出,调用 .execute 的代码还需要处理 Promise reject
何时保存 工具不保存。产品可以把建议给 Director、给下一步工具、给人工,或自行校验后写库
何时生效 取决于聊天后端何时把建议加入后续模型输入,或保存后再读回;不会自动影响正在并行生成的回复

在这个例子里,持续生效的内容可以是“Mira 未读信件,不知道信中秘密”。业务保存并在下一次写作时读回这条约束后,后续回复才有依据保持一致。

例如上面的 15_000 不承诺整项分析在 15 秒内结束:发生重试时会再次提交带 15 秒配置的模型请求,实际计时依赖你实现的 model.complete。若业务要求“这一项分析连重试在内最多等 15 秒”,需给整次 execute 传入覆盖全部尝试的超时 signal,并让适配器遵守取消。逐次尝试与共享取消信号 · 超时参数传递

重试与失败 · 输出、长度与保存边界

独立工具配置的必填项与治理边界

name、modelConfigId、modelCallTimeoutMs 都是 AgentCoreToolConfig 的必填项。这里没有独立工具默认 180 秒的构造规则;180 秒是普通 V2 应用配置的默认值,客户直调用多少必须自己提供。compileContext、contextGovernance、onDiagnostic、shouldStopRetries、isContextGovernanceFailure 可选。

contextGovernance 若启用,需给出 mode: "shadow" | "enforce"、safetyMarginTokens、maxToolResultChars。工具把输入窗口预算要求传给你实现的 model.complete;这个适配器需要在发出模型请求前计数,并按预算决定是否拒绝发送,不能因为传了对象就认定第三方模型端已经受控。工具自己会检查返回文本长度:shadow 仅记录诊断,仍按默认最多 5,000 字符整理;enforce 超配额返回 tool_result_oversized,未超限则保留完整结果。

类导出分别为 PlotTool、CharacterTool、KnowledgeTool、WorldTool、CallbackTool、SceneTool,根入口同时导出 createAgentCoreTool;createAgentCoreToolWithContext 要求提供 compileContext。角色型默认 context 的限制是材料投影,并不限制客户自定义编译器可提供的全部业务字段。

独立工具必填配置 · enforce和shadow输出处理 · 类与工厂导出 · 根入口、Pi适配与发布边界

原子能力 / 公共工具包

Story 原子能力|六个可单独组合的剧情工具

开发互动故事、游戏对话或剧情型角色产品时,可以用这六个工具准备场景、安排剧情目标,再按实际发生的正文更新进度。它们在 roleplay-harness / main 的 @flowgpt/agent-core-tools/story 入口导出,由业务程序调用;与提供咨询意见的六专家是不同的工具,也需要另写包装才能成为主 Agent 可选择的函数菜单。

Core Tools 0.2.3 已发布到受限的 GitHub Packages,包含事件提示牌 Omen;接入方需要包读取权限和模型访问权限。本章按 10 月 9 日主干 82e0169 补充发布状态和 Omen 配置,原有工具流程沿用各段固定依据。公共工具支持 userPersona,现成 StoryV1 应用仍未传入它;工具能接收某项资料,不表示产品已经接好这项资料。0.2.3 发布记录 · 包配置

1. 能拿走什么 #

能力与类型 客户可以做什么 当前 Story 产品什么时候使用
PovPrepareTurnTool:有状态输入输出的世界准备工具 根据用户行动决定是否转场,运行场景计时与事件规则,准备本轮写作材料 每次正常请求,先采用上轮正文,再准备当前行动
PovAdvanceWorldTool:有状态输入输出的世界结算工具 根据实际被接受的完整正文更新世界、后果和待传达邀请 下一正常请求取得上一轮正式保存正文后
NarrativePlanCycleTool:调用 LLM 的目标规划工具 根据主副线与未完成事项,新增一批有因果前提的目标 cycle.needPlan=true 且未解决事件没有阻塞时
NarrativeDealBeatTool:纯程序目标选择工具 在已有可用目标中选一个,配上情绪与节奏指导 每轮准备时;不是每轮新建整批计划
NarrativeSettleEventTool:调用 LLM 的证据结算工具 判断一段已完成或被打断的事件到底完成了什么 事件结束或转场打断,及必要的重试
NarrativeRebranchTool:调用 LLM 的剧情方向调整工具 按持续的新追求改主线,或替换长期未发展的支线 协调器收到 rebranch 下一步指令后

业务程序安排工具调用,收到结果后保存会话状态、确认是否采用正文,并执行结果要求的后续动作。这些工作可以自行实现,也可以交给仓库已有的 Story 协调器;六工具本身没有数据库,也不会递归执行返回的下一步。 应用组合入口

在一次回复前,程序先准备当前场面,安排或选择本轮目标,再把这些材料交给原有的正文模型。正文被业务采用后,程序再根据实际写出的内容结算世界与剧情。只需要给现有对话增加剧情目标时,可以单独使用叙事工具;采用完整 Story 产品时,则由已有协调器管理世界、叙事两份状态,以及正文采用和失败恢复。

例如用户说“我把铜钥匙递给守卫,问能否进城”。准备工具给出“仍在城门盘查、应承接递钥匙”,目标工具可能给出“让守卫辨认钥匙徽记”,随后 Writer(负责生成角色正文的模型)写出“守卫接过钥匙,却仍要求手令”。现成 Story 由 Actor 写正文,自建产品可以用自己的模型。结算时要以业务实际采用的完整正文为准:即使准备时希望用户获准进城,正文尚未发生这件事,就不能记录为已通行。现成产品会等到之后取回正式保存的正文再结算。

你的业务准备怎么接 从哪里开始改 哪些代码继续由谁负责
聊天已经交给仓库应用,希望整套按 Story 运转 研发修改这条入口实际加载的 Scenario,启用 storyV1 并提供 Story 模型配置;本页第 5 节列出前置配置和互斥条件 仓库协调器负责准备、调用六工具、待采用正文核对和状态提交;上游聊天业务仍负责正式消息保存
已有自己的聊天后端,只增加剧情目标 导入 /story 中的叙事工具;在自己的正文模型前接 Plan/Deal,在事件被业务认定结束后接 Settle,按返回要求接 Rebranch 原有角色模型、聊天消息、界面继续使用;自己存 narrative,自己把 packet 放入模型输入,无需接世界快照工具
已有自己的聊天后端,同时需要世界事件与剧情目标 在上一行基础上增加 Prepare/Advance,分别保存 world 和 narrative,并用正文采用记录把前后步骤关联 自己负责完整调度、读写存储、正文版本和重试;下文第 4 节给出组合顺序

storyV1 是仓库应用读取的配置项。使用自己的聊天后端时,需要在代码里实际调用所选工具,将结果加入写作请求,并保存下一次要读取的状态。

2. 公共调用形状 #

import type { AgentCoreModelRuntime } from '@flowgpt/agent-core-tools';
import {
  createStoryWorldSnapshot, parseStoryWorldSnapshot,
  initNarrativeSnapshot, parseNarrativeSnapshot,
  PovPrepareTurnTool, PovAdvanceWorldTool,
  NarrativePlanCycleTool, NarrativeDealBeatTool,
  NarrativeSettleEventTool, NarrativeRebranchTool,
  projectStoryStage, restoreStoryPreparedTurn,
  POV_WRITER_STAGE_INSTRUCTIONS,
  type StoryContext, type StoryModelConfig,
} from '@flowgpt/agent-core-tools/story';

每次调用都要提供 context,用来关联请求、轮次、语言和取消信号。角色卡、历史、世界书等写作材料则分别通过 snapshot / setting / worldContext / prose 传入,下面会逐项说明。

字段 谁提供、实际要求与例值
requestId 必填。调用工具的后端生成本次请求编号,例如 req-7,用于模型调用标记
turnId 必填。聊天后端提供正在准备或结算的那一轮 ID,例如目标回复 assistant-7;恢复这轮不能换 ID;采用上一轮时不能误填当前新回复 ID
language 必填。聊天后端指定输出语言,例如 zh-CN
signal 必填。调用工具的代码传 AbortSignal,请求取消或整体超时时停止相关调用
trace 可选模型调用追踪信息,不是剧情事实

用户扮演谁,怎样交给剧情模型 #

假设账号中的用户人设是“阿宁,初到灰港的信使,不认识城门守卫”。接入方先从自己的用户资料服务取回这段文字,再在 Prepare、Advance、Plan、Settle 或 Rebranch 的 .execute() 输入中传 userPersona。工具不根据账号 ID 自动读取它,也不把它存进返回的世界或叙事快照。下次调用仍由接入方提供当前有效资料。

程序去掉首尾空白,最多保留 4,000 个字符,在模型 user 消息的 JSON 材料之前放置 CURRENT USER PERSONA 文本块。模型据此理解“我”是谁以及用户的视角;例如它可以理解“我把信递过去”是信使的动作,却不能只凭人设就写成“守卫已认识阿宁”。提示词要求后台的计划、状态、总结和后果字段统一以 “the user” 指代用户;明确要求姓名的字段、用户原话和角色直接台词不受这项称谓规则替换。缺省或全空白时不生成这个块,仍使用原来的 JSON 输入。

const planned = await new NarrativePlanCycleTool(modelConfig).execute({
  context, snapshot: narrative, setting,
  userPersona: '阿宁,初到灰港的信使,不认识城门守卫。',
});

这项参数已经进入五类模型工具的调用链。NarrativeDealBeatTool 的共享输入类型也允许 userPersona,但它只运行程序选择规则,不调用模型,因此传入该字段不会改变目标选择。现成 StoryV1 协调器的五处模型工具调用尚未传 userPersona;只升级到 Core Tools 0.2.2 或给 Actor 模板配置人设,不能让剧情准备和结算模型自动读到它。普通 Agent V2 已另外从 Axon 准备结果取得非空 Persona 并传入后台,两套接线需要分别判断。

文本块、长度与称谓规则 · 世界工具输入 · 叙事工具输入与模型传递 · StoryV1 准备调用 · StoryV1 结算、规划与重定向调用 · 普通 V2 的 Persona 接线

“snapshot” 具体是什么,要从哪里拿 #

Story 分别保存世界状态和叙事进度,两份 JSON 的字段与用途如下。它们采用 Story 自己的数据结构,不沿用普通 V2 的 Director 笔记。

材料 包含什么,例子是什么 谁准备、哪些工具用
世界快照 StoryWorldSnapshot foreground 当前镜头事件,如“城门盘查”;backgrounds 镜头外有倒计时的事件;undercurrents 未完全浮现的事情;另有选择项、随机数状态、轮数和 pendingTurn 准备记录 首次由业务给初始设定并用 createStoryWorldSnapshot 补全程序字段,之后从自己的存储读最新对象。Prepare 用它准备当前轮;Advance 通过 prepared 中的同一份状态结算
叙事快照 NarrativeSnapshot main / sub 主副线方向与进度;cycle.pending 待完成目标;emotion 节奏情绪;clock 上次选目标与已结算事件等记录 首次用 initNarrativeSnapshot 建立,之后从存储读取。Plan/Deal/Settle/Rebranch 都传这份对象,采用每次返回的新 snapshot
worldContext、setting 人物设定与当时有效事实的文字材料,例如“守卫负责核验手令;用户持铜钥匙,尚未获得通行许可” 二开方读取角色卡、允许使用的历史/设定后组织。世界工具的 worldContext 可选;Plan/Rebranch 的 setting 必填且需非空。传入材料不会自动执行世界书检索

会话第一次开始时,可以用下面两个工厂建立初态,并分别保存返回对象。后续轮次要读回已保存的快照继续处理;“城门盘查”这样的场景文字只是初始材料,还需要工厂补全程序字段。

const world = createStoryWorldSnapshot({
  foreground: {
    id: 'gate-check', event: '守卫在城门检查通行凭证',
    kind: 'conflict', owner: 'guard',
  },
});
const narrative = initNarrativeSnapshot({
  main: { thread: '寻找失踪商队', direction: '获取进城调查的机会' },
  sub: { thread: '与守卫建立信任', direction: '用可信线索换取合作' },
});
// 下一轮读取保存后的 world / narrative;不要再次执行初始化覆盖进度。

owner 填事件属于哪个故事人物或势力,由初始化这份快照的代码提供;这里用 guard 表示守卫,不是账号 ID;kind 只能是 conflict 或 progress。完整 Story 产品已额外实现“从角色和故事材料调用初始化模型”这一步,单独导入六工具不会自动读取你的角色卡。世界初态与工厂 · 叙事结构与初始化 · 完整应用初始化接线

需要模型时注入 StoryModelConfig:model 是实现 AgentCoreModelRuntime.complete 的对象,modelConfigId 填这个 model.complete 实现能识别的配置 ID,timeoutMs 可选,isRecoverableModelError 可选。研发在 model.complete 中按配置 ID 选择实际模型与参数,并连接已授权的模型服务。每个 JSON 任务校验不通过最多修复一次,首次响应与修复共享该任务的 timeoutMs 和取消信号。一个工具可能包含多个任务:例如 Prepare 的行动解释与同伴判断分别计时;这个参数不是工具整体或整轮的总超时,调用工具的后端还应提供覆盖整项任务的总取消信号。省略 timeoutMs 时,工具不额外创建这层计时器。调用契约与计时 · 同一工具内的两次 JSON 任务

工具在无法可靠结算时,可能正常返回 pending / unknown,让程序保留证据、按规则恢复。非法参数、损坏快照、轮次不匹配、准备态被改动和外部取消则直接抛出异常;世界结算遇到未经 isRecoverableModelError 识别的非超时服务错误,也会继续抛出。因此调用方既要检查 outcome,也要处理异常,并保留失败原因。 世界输入和准备态校验 · 模型错误捕获与继续抛出条件

3. 六个工具:准确参数、结果与使用例子 #

A. 准备本轮场景 PovPrepareTurnTool #

构造: new PovPrepareTurnTool(modelConfig?, hooks?)。

输入: { context, snapshot, action, worldContext?, userPersona? }。snapshot 是 StoryWorldSnapshot;worldContext 填聊天后端取回的角色设定和已发生故事事实的文字;userPersona 填用户已有身份资料,按前文规则只进入模型输入。action 三选一:

{ type: 'free', text: '我把钥匙给她,但先不进城。' }
{ type: 'intent', text: '我留在城门询问。', intent: { kind: 'normal' } }
{ type: 'choice', index: 0 }
  • free + 有 modelConfig:调用模型判断 normal(留在当前事件)、cue(主动转向已有事件)或 signal(回应上轮确实传达的邀请);需要时判断同伴是否跟随。
  • intent:聊天程序已经判断用户是留在原事件、转向另一事件还是回应邀请,直接提供这一判断;targetId 必须匹配可用事件,不能靠任意字符串创建一个目标。
  • choice:索引来自快照已保存的 choices。
  • 不提供模型且用自由输入时,采用 normal;工具不会自己理解一个自由文本转场意图。

输出 StoryPreparedTurn: snapshot、intent、userText、flags、stage、surfacing、dice、events、diagnostics、usage。给 Writer 的主要是 stage:当前事件与阶段、应承接动作、可见的场外影响、选中的暗流线索、待传达邀请。全快照用于恢复,不宜原样作为角色已知信息。

下面是 Writer 可能收到的一份 stage 教学示例,具体值以本轮准备结果为准。background / undercurrent 为空,表示这次没有向写作模型交付相应线索;完整世界快照里仍可能保留场外事件。

{
  "foreground": {
    "id": "gate-check",
    "event": "守卫在城门检查通行凭证",
    "phase": "start",
    "payBeat": "我把铜钥匙递给守卫,问能否进城。"
  },
  "background": [],
  "undercurrent": [],
  "signalDemand": null
}

payBeat 包含本轮要承接的用户行动/所选动作的预期,也可能并入已准备的场外结果和消退事项;这些场外内容需要通过合理的观察或传信进入当前场景。signalDemand 若非空,是本轮需要尝试在正文里传达的邀请,不代表已经传达成功。程序保留 snapshot 与 flags 做后续结算,保留 dice / events 追踪机械处理,diagnostics / usage 供排错和用量统计。Writer 不应把这些程序记录都说给用户。写作投影与准备结果字段 · payBeat 的实际组装

保存时机: 这是尚未结算的准备结果。聊天后端应保留完整对象,直到对应正文被正式采用后,再交给 Advance;同一 turnId + action 可恢复准备,不重复推进骰子和时钟。不同轮不能在未解决的 pending 上继续 prepare。输入与分支 · 数据结构

B. 根据正式正文推进世界 PovAdvanceWorldTool #

构造: new PovAdvanceWorldTool(modelConfig?, hooks?)。

输入: { context, prepared, writer, worldContext?, userPersona? }。context.turnId 必须匹配 prepared。writer 至少含完整的已接受 prose,也可含 choices 和 nextForeground;这两个字段供能同时产生可选动作和下一事件的写作程序使用,现有 Story 应用主要交 { prose }。可选 userPersona 帮助模型解释用户身份,不能替代正式正文证据。

prepared 直接来自 A 的完整返回值或恢复函数,不能只传给 Writer 的 stage;prose 从业务已采用的完整正文取得,不能用 user query 或计划文字代替。choices 若提供,是下一轮可选动作的 {text, expect, isSignal?} 数组;nextForeground 若提供,描述后继事件的 event / kind / owner / important / worsensIfLeft,必须与正式内容及工具校验相容。

writer: {
  prose: '莉娅把钥匙递还,示意你可以留在门外等消息。',
  // 可选 choices: [{ text: '我留在门外等。', expect: '等待', isSignal: false }]
}

输出: { outcome, snapshot, events, diagnostics, usage }。

  • committed:工具算法已经计算新世界快照;不代表数据库写成功。
  • duplicate:输入的最新快照记录该轮已完成、且没有 pending,因而不重复结算。它只检查该快照的 lastCompletedTurnId,不查询一份永久调用记录。
  • pending:没有可靠世界提案,保留原 prepared;聊天后端保留已采用正文及其消息 ID,再按同一个 turnId 重试,不能把它当成“无变化成功”。

使用模型时,由模型判断邀请是否实际传达、场外结果与后继事件;程序检查允许修改的 ID、时钟、容量和机械阶段等。committed 表示提案通过这套处理,不代表程序独立复核了全部语义事实。公开构造允许不传模型,但这时没有模型解释世界内容,只使用已有机械材料和显式 Writer 输出,不能与完整产品的语义结算能力画等号。执行与 outcome

C. 创建剧情目标 NarrativePlanCycleTool #

构造: new NarrativePlanCycleTool(modelConfig, options?, hooks?),options 可含 { policy, prompt }。

输入: { context, snapshot, setting, userPersona? }。snapshot 是 NarrativeSnapshot,setting 是设定和当前已知故事材料字符串,userPersona 是接入方另行提供的用户身份文字。

例如 setting 写“用户要寻找商队;目前停在城门;守卫要求手令;铜钥匙的来历尚未被辨认”,而 snapshot 保留已存在的主副线和未完成目标。Plan 用两者生成目标;它并不从 conversationId 自动取聊天,也不会把目标当成已发生事件。

输出: { snapshot, nextActions, diagnostics, usage }。新增目标写入 snapshot.cycle.pending;包含 id / serves / angle / gist / reward / core / done / priority / prerequisites。例如“让守卫辨认钥匙徽记”是 reveal 目标,“守卫给予通行许可”若作为回报,须引用已经发生或安排中的铺垫目标。

工具只在 needPlan=true 且本轮未规划过时调用模型。默认新增 5–7 项、至少一项服务副线;原未完成事项保留。无效输出修复后仍失败,则仍保持 needPlan,不能假定已有可用计划。实现与验证

返回的某一个目标可长这样(教学示例,不是只返回一项目标的完整结果):

{"id":"recognize-key","serves":"main","angle":"reveal","gist":"让守卫辨认铜钥匙上的徽记","reward":null,"core":false,"done":false,"priority":0,"prerequisites":[]}

serves 指服务主线还是副线;angle 指人物、关系、冲突、揭示或回报;gist 是希望发生的推进;reward 只对回报目标有内容;prerequisites 是必须先完成的目标 ID。done:false 明确它尚未完成,core / priority 供后续机械选择使用。保存/继续传递的是整个返回 snapshot,下一步 Deal 从目标集合里选择,不需要二开方再把自由文字猜回这些字段。目标字段与计划归一化

D. 选本轮剧情目标 NarrativeDealBeatTool #

构造: new NarrativeDealBeatTool({ policy }?, hooks?)。不接受模型配置,不调用 LLM。

输入: { context, snapshot, phase, userPersona? },phase 为 start / develop / end。共享类型允许可选 userPersona,但本工具不调用模型,也不使用这段文字改变选择规则。

phase 应来自当前事件阶段,例如 A 返回的 prepared.snapshot.foreground.phase,分别表示事件开场、发展、收尾;它不是用户输入或主线周期的 build / develop / turn / climax。二开方若单独使用叙事工具,需要自己提供真实的事件阶段。

输出: 通用结果加 packet:

{
  pending: { id, serves, angle, gist, reward, fresh } /* 或 null */,
  emotionGuide: { enabled, valence, arousal, dominance, label, beat },
  mainDirection,
  subDirection,
  bias: { preferBackgroundKind: 'conflict' /* 或 'progress' / null */ }
}

程序按前置目标是否完成、优先级、欠缺回报、情绪匹配与主副线多久没推进来选择。没有满足前置条件的目标就返回 pending:null;不会硬塞一个未铺垫回报。将 packet 与世界 stage 一起交给 Writer,模型才有机会采用它。返回快照也要保存,因为里面记录了本轮选择和轮换计数。选择机制

Writer 收到 pending.gist=让守卫辨认铜钥匙上的徽记 时,应把它当本轮可争取的推进;fresh 告诉它是否刚选出;mainDirection / subDirection 给出整体方向。emotionGuide 的三个数值分别是情绪正负、激烈程度和掌控感,配合 label 与 lead-in / full / pay-off 节拍指导表达。bias 给世界投影选择同等候选时使用,并不直接强迫正文制造冲突。已有应用把 {stage, narrative:packet} 序列化成 JSON,连同 Writer 使用说明加入 Actor 输入;既有角色、语言、风格要求仍由 Actor 原提示词承担。完整应用实际交给 Actor 的文字

E. 判断一个事件实际完成了什么 NarrativeSettleEventTool #

构造: new NarrativeSettleEventTool(modelConfig, options?, hooks?),支持 { policy, prompt }。

输入: { context, snapshot, eventId, prose, userActions, interrupted?, userPersona? }。可选人设帮助解释对应用户行动,不是事件已经发生的证据。

  • eventId 是本次剧情事件的唯一 ID,由调用程序提供;例如一次城门盘查自开始到结束沿用同一个值;不同发生次数不能复用同一个 ID。
  • prose 是该事件累计的完整已接受正文,不一定只有一条回复。
  • userActions 是对应用户行动数组;不要把事件结束后的新输入混进来。
  • interrupted=true 表示事件被打断,不代表已完成所有目标。

例如 eventId:'gate-visit-1'、prose:'守卫看见钥匙徽记,但没认出来源,仍要求手令。'、userActions:['我递出铜钥匙。','我问能否进城。']。这里的正文和行动必须来自同一次城门事件;之后再次回城是另一次事件,不能复用这个 eventId。这次城门事件何时结束或被打断,由调用这些工具的剧情程序判断;工具不是每收到一句就默认整件事已经结束。

输出: 通用结果加 outcome: 'settled' | 'unknown' | 'duplicate'。成功快照更新目标完成、主副线进度、情绪观察及事件计数;nextActions 可能要求 plan-cycle 或 rebranch。未知评估不记作“剧情没有推进”,也不增加未推进计数;剧情程序要保留该事件的正式正文和用户行动,供之后重试。

例如正式正文只是“守卫看见徽记,但没有认出”,模型按提示应判定“辨认来源”尚未完成。程序检查完成目标 ID、前置依赖、completionEvidence 和游标移动 evidence 是否非空;依据是否真正符合正文仍由这次模型判断,没有独立事实复核。 这些依据文字不会进入返回的 snapshot,快照只更新完成标记、游标和计数等字段。若二开需要保存“为什么完成”的理由,须在模型适配层或新增结果字段接住它,再与正文版本一同保存。依据字段校验 · 实际快照更新

duplicate 只覆盖当前快照保留的 settledEventIds。默认 idempotencyWindow=128,成功后保留最近 128 个已结算事件 ID;更早事件移出窗口后,不再因这个列表被识别为重复。这个策略可以通过独立工具的 options.policy 修改,已有 Story 产品配置未暴露它。命中与裁切 · 默认窗口

F. 调整主副线 NarrativeRebranchTool #

构造: new NarrativeRebranchTool(modelConfig, options?, hooks?),支持 { policy, prompt }。

输入: { context, snapshot, setting, scope, direction?, userPersona? }。可选人设进入这次模型请求,不会自动成为新主副线或持久事实。

  • scope:'main':必须提供非空 direction。例如用户持续转向“寻找失踪商队”;模型调整主线与相配副线,承接已有进度与承诺。
  • scope:'sub':只替换副线,主线保持;无需 direction。

输出: 新 snapshot、nextActions、diagnostics、usage;连续性说明放在 narrative_rebranched 诊断中。工具本身不决定“用户是不是该改主线”:现有 Story 协调器依据已结算事件中的连续方向触发,自己的剧情程序也可按预先定义的业务规则调用。rebranch 是剧情方向调整,不是创建 Git 分支或自动复制会话。实现

它仍需拿到当前叙事 snapshot 和非空 setting,例如最新已知材料“用户已获得通行机会,并持续追问失踪商队”。模型在旧主副线、未偿还承诺和新方向之间整理新的叙事状态;返回后,调用程序把新 snapshot 交给下一次 Plan/Deal。仅调用 Rebranch 而继续把旧 snapshot 传下去,后续剧情仍会按旧方向运行。

4. 独立组合:哪些东西一定由二开方提供 #

自己的程序可以导入所需类,为调用 LLM 的工具传入模型适配器,再在写作前、正文采用后分别调用 .execute(input)。这些类的 Tool 基类负责执行前后的 hooks,不会自动向主模型提供工具菜单。要让主模型选择调用,研发还需定义函数名、参数 schema 和执行包装,由包装绑定真实快照、模型与存储,将结果交回主模型。程序继续检查状态版本和正文采用条件;六专家的 toPiTool 不能直接用于这六个 Story 类。 Story 工具生命周期 · 六专家 Pi 适配器所接的接口

下面演示如何给已有聊天增加剧情目标。程序先按会话读回 narrative,首次则用前文的工厂初始化;setting 填本轮实际设定,eventPhase 填当前事件的 start/develop/end,context 与 modelConfig 按第 2 节准备。这段调用只返回目标和更新后的叙事状态,正文仍由原有模型生成,也无需读取世界快照。

const planned = await new NarrativePlanCycleTool(modelConfig).execute({
  context, snapshot: narrative, setting,
}); // needPlan 为 false 时保留已有计划,不再请求规划模型
const dealt = await new NarrativeDealBeatTool().execute({
  context, snapshot: planned.snapshot, phase: eventPhase,
});
const writingDirection = JSON.stringify(dealt.packet);
// 研发将 writingDirection 放入自己原有的正文模型请求。
// 保留 dealt.snapshot,事件结束后把它与实际采用的 prose / userActions 交给 Settle。

使用这段代码前,研发需要实现按会话读取、保存 narrative,并明确事件 ID 及结束规则。已有剧情系统可以沿用自己的事件边界;事件结束后,程序才能调用 Settle 判断目标完成了多少。状态保存、正文采用和失败恢复也由下表所列代码承担。 Plan 的条件执行 · Deal 返回材料与新状态

二开方需要实现的部分 必须完成的事
模型 提供 model.complete、配置 ID 与语言,处理凭证/路由;按实际需要提供模型失败分类
初始化 用 createStoryWorldSnapshot 与 initNarrativeSnapshot 建立真实初态,或自建初始化模型。完整应用的角色卡读取和初始化器没有因导入工具包而自动出现
Writer 把 stage + narrative packet + 自己的角色/风格/历史放入写作模型;Story 工具不输出最终 RP 正文
调度 调用 prepare、条件 plan、deal、Writer、accept、advance、事件 settle,以及执行 nextActions;工具之间不会自动调用
接受正文 明确哪个完整结果被业务采用,只有它才能用于结算。中间 token、候选草稿与下游尚会变更的正文不等价
状态存储 每次先读最新快照,保留准备态及正式正文证据,通过事务/CAS 防止旧请求覆盖新进度;只重复传入同一个 turnId、却使用旧快照,不能获得数据库级防重。若需长期防止同一事件被重复结算,后端还要保存已处理事件的记录
恢复 返回 pending / unknown 时保留证据按规则重试;抛出的身份、数据、取消或服务异常须分别处理。存储大小上限、删改历史后怎样恢复、重生成采用哪份正文,由接入方在聊天后端实现
呈现与查询 角色只能看到允许表现的内容;若需审计“为什么推进”,先补保存模型依据与正文版本,再提供查询界面;现有 snapshot 没有逐项结算理由

最小组合顺序:

读已保存 world / narrative
→ PovPrepareTurnTool
→ 如果 needPlan:NarrativePlanCycleTool
→ NarrativeDealBeatTool
→ 把 stage / packet 交给自己的 Writer
→ 业务接受完整正文
→ PovAdvanceWorldTool
→ 事件到达边界:NarrativeSettleEventTool
→ 根据 nextActions 调整主副线或安排下一次规划
→ 校验 outcome 并事务/CAS 保存

已有完整应用把“接受完整正文”推迟到下一请求;公开工具不强制这样做。源码示例 examples/sdk/04-story-turn.ts 演示同一次调用内接受正文并存储,使用假模型验证控制流,没有调用真实模型或数据库。可运行组合示例

实际保存什么,下一句如何使用 #

时刻 已有 Story 产品 单独二开需要接的动作
回复前各工具完成 协调器在本次请求内更新 world/narrative,交出本轮写作材料;尚不能把本轮正文算作已发生 每一步接住新 snapshot,不能继续传旧对象;把 stage/packet 真正加入 Writer 请求
Harness 正文成功生成后 把 world、narrative、事件记录及 pendingActor 序列化为 emochi-pov-story 状态,通过注入的 state store 按旧版本 CAS 保存;成功结果是 waiting_for_acceptance。pendingActor 记录待确认的回复 ID、用户消息锚点与本轮投影 保存 prepared 与相关叙事选择,关联正文 ID/版本。若你的业务此时已能确认完整正文正式采用,也可马上结算;保存权威正文的动作仍由业务完成
下一句到来 读回保存状态,用 pendingActor 的回复 ID 查上轮正式正文;验证消息锚点后,才把该正文交给 Advance,必要时 Settle,并准备当前新输入 取回已接受正文、对应 prepared 和最新快照;执行结算并检查 outcome。不能用新的用户输入去结算上一轮
结算结果进入后续写作 已更新的世界事件、已完成目标和新方向成为后续 prepare/deal 的输入;再随本次状态提交保存 把新 world/narrative 保存回同一会话版本;下一次再从此读取。数据不自动回写世界书或普通 V2 的 Director 笔记

拿到结果后,程序按 nextActions 继续调度,例如 [{kind:'plan-cycle'}] 表示还要安排一次规划。更新后的 snapshot 用于保存和继续执行,stage / packet 用于指导 Writer,Writer 生成的 prose 才是用户看到的正文。 已有产品保存字段与时机 · 采用正式正文后更新世界与事件 · 工具通用返回结构

5. 配置和扩展边界 #

使用完整 Story 应用时,在聊天入口实际加载的 config/scenarios/<ID>.json 或 AGENT_ROUTER_SCENARIOS_JSON 对应对象中加入以下配置,保留原有 Actor、模型和模板设置。HARNESS_ENABLED_SCENARIOS 决定加载哪些文件,HARNESS_SCENARIOS_DIR 可指定目录;同名环境 JSON 会整项覆盖文件内容。修改后需要让部署重新加载。

{
  "storyV1": {
    "enabled": true,
    "modelConfigId": "your-story-model-config",
    "modelCallTimeoutMs": 45000,
    "postTurnTimeoutMs": 90000
  }
}

这段配置应合入已有的完整入口设置。modelConfigId 决定 Story 理解行动、规划和结算使用的模型,初始化默认也用它,或通过 initializerModelConfigId 另选;Actor 仍使用自己的正文模型。当前入口还必须具备 modelConfigRef、presetRef 和完整 agenticV2 配置,且不能同时设置 preActorDirector 或 sumiV1。Story 会使用 agenticV2 中的 Actor 与恢复配置,再由自己的协调器接管剧情流程,不额外运行普通六专家后台。

配置之外,服务还要能通过 Axon 取得角色、模型和状态,能读取聊天业务最终保存的正文。否则即使 Story 选项写对,下一请求也没有可靠的正文可以采用。仓库已有 POV 场景文件可作为字段组合参考,其中各模型配置 ID 要能在自己连接的 Axon 中查到。若使用示例的世界书部分,worldbook.tenantId 应填写创建或导入所用书籍时的 tenant_id,向维护世界书服务的研发取得;示例里的 production-default 不是任意新部署都能照抄的值。现成配置示例 · Story 配置解析 · 入口前置条件 · 配置文件选择

层次 怎么配置 当前可改变什么
已接好的 Story 产品 场景 storyV1 enabled、模型、初始化模型、模型调用超时、生成后保存超时、状态字节上限、随机 seed
独立世界能力 createStoryWorldSnapshot({ policy }) 当前事件发展长度、场外容量、暗流阶段阈值、表露预算、种子注入节奏、保护角色
独立叙事能力 各工具 options.policy 新目标数量、剧情轮换、主副线饥饿阈值、持续新方向阈值、情绪调节、依赖与去重窗口等
三个叙事模型工具 options.prompt 替换 PlanCycle / SettleEvent / Rebranch 的任务说明;结果仍须满足相应 schema
工具生命周期 hooks.beforeExecute / afterExecute / afterTurn 输入前处理、执行结果观察或后处理、整轮处理;afterTurn 必须由调用工具的后端在整轮结束时显式调用
Writer 输入 POV_WRITER_STAGE_INSTRUCTIONS + 自己的角色提示词 控制舞台如何被写入正文;导出的说明不包含你的角色设定或说话风格,研发仍需在写作提示词中提供

当前 storyV1 没有直接暴露 world/narrative 的所有内部 policy,不能把公共工具构造参数与应用 JSON 开关混为一谈。世界工具也没有 options.prompt 参数;它们的语义提示词在源码中,不能照抄叙事工具的构造方式来修改。

projectStoryStage(prepared, bias?) 可在 Writer 前改变同等候选间的 conflict / progress 偏好;结果应保存。restoreStoryPreparedTurn(snapshot, bias?) 是恢复,bias 仅用于断言一致,不重新选择、不再次消耗随机数。新 prepared 会记录独立准备基线,校验时重放机械决策,防止保存的舞台与标记被一起改写后冒充合法结果。世界投影与恢复 · 生命周期 · 应用配置

默认关键值为 dealEveryTurns=3、每次新增目标 5–7、主线持续新方向 3 个已结算事件、副线 5 个已结算事件未推进触发替换、世界 surfaceBudget=2、background 最多 3、undercurrent 最多 5。它们的单位不同,不能统一解释成“累积 X 轮启动慢系统”。叙事默认策略 · 世界默认策略

Omen:给同一事件持续提供一种叙述提示 #

Omen 是预先写好的一副提示语,由程序抽取,附在 NarrativeDealBeatTool 返回的 packet.omen 中。你的回复模型读到它后,可以调整这一事件的氛围、角度和节奏。例如“在平静表面下表现逐渐累积的压力”,可以改变守卫核验钥匙时的描写方式,但不会新增“守卫已经背叛”这样的事实,也不覆盖用户行动、当前场景或剧情目标。

PR #250 已于 9 月 24 日合入 main,随 Core Tools 0.2.3 发布。下面的字段和调用方式已对照 10 月 9 日 82e0169 源码;它扩展原有快照和两个叙事工具,不是新增一个让 LLM 选择的工具。使用 0.2.2 的接入方需升级到包含 Omen 的版本,完整 Story 应用还要部署相应应用代码。

独立接入时,研发先准备固定牌组和初始随机种子,创建剧情快照;随后把同一副牌传给“选目标”和“事件结算”工具。选目标返回当前牌的 {id, text},业务代码把它与 packet 的其他写作要求交给回复模型。事件成功结算后,工具在返回的新快照里换下一张牌;业务保存整个快照,下次读回后继续使用。工具不另存一份牌库,也不替你写数据库。

牌组具体填什么、工具怎么传、已有状态如何处理
数据或调用 需要提供什么 返回与保存
牌组 omens {id, text} 数组;id 区分每张牌,text 是给回复模型的抽象提示;可以导入工具包提供的 NARRATIVE_OMEN_DECK 内置牌组有 142 张;快照保留牌组指纹和牌 ID,牌面正文仍来自本次传入的同一牌组
initNarrativeSnapshot({omens, omenSeed}) 初始主副线等资料,以及牌组和种子;独立函数省略牌组时为关闭,种子默认为 1 返回已洗牌、抽好当前牌的 snapshot.omen;这与完整 Story 应用默认启用内置牌组、seed 731 的接法不同
new NarrativeDealBeatTool({omens}) 每次仍提供本页前述 context / snapshot / phase packet.omen 为当前 {id, text} 或 null;同一事件跨轮不重新抽牌
new NarrativeSettleEventTool(modelConfig, {omens}) 最新快照、同一牌组、已接受的完整事件正文、用户行动与事件 ID 成功结算才换牌;unknown 或 duplicate 不消耗牌;保存返回的整个 snapshot
configureNarrativeOmens(snapshot, cards, seed) 业务明确决定为旧快照启用、替换或关闭的牌组 返回重建抽牌状态的新快照,清除旧的发放缓存;业务仍须决定迁移时机并保存,不是自动合并旧牌进度

完整 Story 应用的配置写在 storyV1.omenDeck:省略采用内置牌组,[] 为关闭,自定义数组整体替换。应用校验最多 256 张,id 唯一、1–96 字符、无空白;text 为 1–1,000 字符;两者都不能有首尾空白,卡片不能带其他字段。例如以下只是一张自定义提示牌的数据,不是完整运行配置:

{
  "id": "quiet-pressure",
  "text": "让压力通过细微动作逐渐显露;不要凭空添加事实,也不要替用户决定下一步。"
}

快照中的 omen 保存 deckFingerprint、rngState、drawPile、discardPile、currentId。抽完后会重洗弃牌;牌组大于一张时避免紧接着重复上一张。相同牌组与种子产生相同顺序,用户多开会话不会自动得到独立随机种子。

当前主干 82e0169 的 Story 协调器只在“当前牌组非空、旧快照尚未启用”时自动调用迁移函数。已保存牌组指纹的会话,直接把配置改成 [] 或另一副牌,后续发放/结算会抛出 Omen deck does not match the narrative snapshot。业务需要显式调用 configureNarrativeOmens 并保存迁移后的快照,不能只改配置后重启。本轮复核了上述调用条件和指纹校验,没有重新运行此前关闭/替换牌组的复现测试,也没有做真实模型剧情质量验收。

应用配置校验 · 快照字段 · 洗牌与迁移函数 · Deal 返回当前牌 · 结算成功后推进 · 协调器迁移条件

原子能力 / 独立服务

世界书:保存设定,并在每次生成前选择需要交给模型的原文

10/19 更新 · 本章 3 处从第一处开始看 →
运营事先保存世界书并关联角色。用户发来消息后,聊天程序检查身份、查角色关联;没有关联书籍则沿用原回复流程,有关联才选择条目,把设定原文加入模型请求并检查长度,再生成回复。下一轮重新选择。

这张图画的是仓库已有聊天服务的处理顺序。世界书先参与本轮回复的输入准备;后台专家和 Director 不会自动收到同一批设定原文。

可左右滑动查看 放大查看流程图 ↗下载 SVG

世界书保存作者事先写好的地点、人物、规则和背景。例如,作者可以在书里写下“灰港没有电力”“铜钥匙只能开侧门”“守卫放行前要核对手令”,供角色对话时使用。

用户发来“我把铜钥匙递给守卫”后,聊天程序会先查当前角色关联的世界书,从中选出这次对话需要的设定。假设选中了“放行前必须核对手令”,程序就把这段原文放到角色介绍前面,保留原有控制说明、聊天记录和用户刚发的话,一起发给回复模型。模型读到规则后,可能让守卫回答:“钥匙没错。手令呢?”

如果用户只说“那这个呢”,使用 hybrid 的聊天入口还会让世界书服务参考最近两条用户/角色的话,帮助查找“这个”可能指向的设定。例如,上一句正在谈铜钥匙,相关性搜索就不只拿“那这个呢”这几个字去找资料。作者写的关键词触发规则仍按自己的扫描范围执行;这次调整不会把整段历史、角色 Prompt 或后台剧情笔记全部拿去搜索。短历史的实际取法

查世界书发生在生成回复之前,所以会增加这一轮的准备时间。服务返回的是设定原文和放置位置,代码字段为 blocks[];聊天程序将它们加入发给模型的 messages[],检查完整输入的长度,再开始生成。用户最终看到的台词仍由回复模型来写,并由聊天业务展示和保存。下一次用户发消息时,程序会重新选取设定;这次选中过的原文不会因此永久写入聊天记录。

两种接法,分别是在改哪套程序 #

如果你的产品已经使用仓库里的 Agent V2 或 Story,读取世界书、把设定放进模型输入的代码已经写好了。研发需要开启这项功能,设置世界书服务的连接方式,并告诉程序去读哪一批书;运营再选择哪些角色使用哪些书。

研发保存书时会指定一个分组编号,服务按这个编号区分不同业务或不同环境的资料,代码把它叫作 tenantId(接口里写作 tenant_id)。例如,创建“灰港世界设定”时用了 greyport-demo,后来给角色关联这本书、聊天时读取这本书,也都要使用 greyport-demo。这个值由负责接入的研发提供,运营沿用即可;它不是聊天用户的账号,也不是角色名字。文档里的 your-tenant 是占位文字,实际配置要换成保存这些书时使用的编号。

这些设置通常写在 config/scenarios/<聊天入口名>.json,由研发维护。代码把这一份 JSON 称为 Scenario,服务读取它来决定用哪个模型、哪套提示词模板,以及启用哪些能力。仓库已有 agentic-v2-worldbook.json 作为例子:modelConfigRef 引用正文模型配置,agenticV2 设置 V2 的正文与后台模型及运行规则,worldbook 指定从哪一批书里查资料、怎样选取设定,以及最多给模型多少文字。其中 agenticV2.modelConfigs.actor 必须与顶层 modelConfigRef 一致。作者写的设定原文另外保存在世界书服务里。

研发修改设置后,需要让服务重新加载。后续聊天请求选用这份设置,程序才会在回复前查询世界书。这个选择由业务后端随请求填写,聊天界面不必增加一个用户开关。配置时应沿用业务实际使用的入口和模型,示例文件只用于说明字段写法。

如果你的产品有自己的聊天后端,也可以只使用世界书服务,继续由原来的代码调用模型。读取角色设定和聊天记录后,程序先查世界书,再把选中的原文一并交给回复模型;这部分由研发加入现有代码,不需要迁移到 Agent V2 或 Story。

研发可以直接调用 HTTP 接口,也可以使用 SDK 0.6.0 新增的 @flowgpt/roleplay-harness/worldbook 客户端。两种方式最终都调用 POST /v1/context/select,提交允许使用的书籍 ID、版本和用户输入等材料。接口返回 blocks 后,你的代码需要按其中的位置要求,把设定原文加入模型请求。例如,把“守卫必须核对手令”放到“你扮演守卫莉娅”的角色介绍前,然后继续原来的回复生成流程。

世界书以独立 HTTP 服务和源码提供,也有已发布的 TypeScript SDK 客户端。当前普通 RP、Compact、Agent V2、Story 和 Sumi 都已有使用它的代码,通过各自的 worldbook 设置启用。查询通常由程序在回复前执行;主 Agent 的工具菜单不会默认多出一个世界书工具。统一接线入口 · 现行配置解析

接现成 Harness:具体开关、每轮读取与模型边界 #

使用仓库聊天服务时,需要在原有的 Scenario JSON 中增加 worldbook 设置。普通 RP、Compact、Agent V2、Story、前台工具循环和 Sumi 都支持,不限于名称为 agentic-v2-worldbook 的示例。请求必须使用 roleplay-harness/v2 协议,旧 v1 预编译请求会被拒绝。原来的产品选择和组合限制继续有效,添加世界书不会额外开启 Story、Sumi 或 Agent V2。闭环协议校验 · 产品组合校验与世界书配置

下面这段 JSON 要合入当前聊天入口对应的 config/scenarios/<入口名>.json 顶层,与原来的 modelConfigRef 等字段并列;保留原有模型和产品设置,不要用下面这段把整个文件覆盖。它只是文件中的世界书部分:

{
  "worldbook": {
    "tenantId": "your-tenant",
    "strategy": "hybrid",
    "tokenBudget": 2400
  }
}

tenantId 必填,1–200 字符且不能含首尾空格;strategy 在 Harness 默认 hybrid;tokenBudget 默认 2400,允许整数 0–32000。若进程设置 WORLDBOOK_TENANT_ID,它覆盖已有 worldbook 对象中的 tenantId,不会为原本未配置世界书的场景凭空打开此能力。选择配置在请求真正使用时校验。独立服务的 SelectRequest 默认仍为 rules/1500;Harness 不直接开放 constant_budget_ratio、scan_depth、max_entries 等全部服务参数,如需修改,要扩展适配层或直接调用服务。字段校验 · 通过环境变量修改分组编号

服务在启动时按 HARNESS_ENABLED_SCENARIOS 读取要使用的配置文件,目录默认是 config/scenarios,也可用 HARNESS_SCENARIOS_DIR 修改。名单可以逐个写入口名,也支持 agentic-v2-* 这样的末尾星号匹配;只有末尾星号有效,前缀不能为空,匹配不到文件会报错。如果还设置了 HARNESS_EXPERIMENT_SCENARIOS_DIR,同名文件优先从这个实验目录读取,找不到才使用基础目录。它们都只在启动时加载,修改文件后要重新启动或发布服务。文件选择与实验目录优先级

如果部署使用环境变量 AGENT_ROUTER_SCENARIOS_JSON,就在其中对应的方案对象里添加 worldbook。同名的环境配置最后会替换整份文件配置,而不是逐字段合并,因此需要检查服务最终读取的是哪一份;原有模型、角色模板和产品设置也要一并保留。使用实验目录并不代表其中的配置已经用于生产请求。实际配置加载及覆盖

以仓库的 agentic-v2-worldbook.json 为例:研发将 agentic-v2-worldbook 加进 HARNESS_ENABLED_SCENARIOS,保留其他仍在使用的入口;业务后端发聊天请求时填写 extensions.scenario_id: "agentic-v2-worldbook"。前者让服务读到文件,后者让这次请求使用文件里的设置。实际接入时,把示例名称换成业务自己的入口名。请求怎样选择设置

配置完成后,管理端调用 PUT /v1/entity-bindings,把书关联到正在使用的角色 ID。接口把这个 ID 称为 entity_id:意思是“哪一个业务对象使用这些书”,例如一张角色卡或一部故事。现成 RP 入口仍从聊天请求的 promptId 取这个值;假设角色 ID 是 guard-role-1,关联时就必须填同一个 guard-role-1,不能自行改成另一个名称。

10 月 9 日,Harness 已把世界书 RPC 字段改为 entity_id。会话、角色等其他接口仍使用原来的 promptId;世界书服务也仍兼容旧 Prompt 路由。研发升级时需要依次核对世界书数据库迁移、Service、Axon 的 RPC 转接和 Harness 版本,不能只改前端参数。当前已确认两仓合入,并补核到 Worldbook Entity 版本 ad38dce 在 10 月 9 日成功部署;数据库 007 迁移和 Axon 转接仍未取得业务运行证据。当前 RP 取 ID 的位置 · RPC 参数与返回检查

聊天请求中的账号、会话和角色 ID,分别告诉程序“谁在用、正在进行哪段聊天、聊的是哪个角色”。下表列出各自的来源和用途,例值需要替换为业务里的真实记录。Harness 用这些 ID 检查会话、查找角色关联的书;直接调用世界书的选择接口时,程序要先确定允许读取的书,再提交书籍版本和查询材料,并在请求地址中带上保存书时使用的 tenant_id。

名称与准确字段 它到底指什么;示例 谁提供,当前代码用在哪
这批书的分组编号 worldbook.tenantId → REST/RPC tenant_id 例如创建灰港的书时用了 greyport-demo,查这批书也填 greyport-demo 负责接入的研发提供;创建书、关联角色和读取书时必须一致。服务不会凭这个编号判断调用者是否有权限
登录用户 extensions.turn_context.user_id → context.userId 当前真人账号 ID,例如 user-42;不是角色“莉娅”,也不是玩家在故事里的名字 可信业务后端从登录身份带入;Harness 以 X-User-ID 传给 Axon 做会话身份检查
RP 会话 ChatRequest.conversationId → context.sessionId 用户与角色正在进行的这段聊天记录 ID,例如 conversation-8;不是本轮句子或消息 ID 聊天业务创建并在这段对话后续请求中继续使用;传给会话身份检查
角色/作品 ChatRequest.promptId → context.promptId → 世界书 entity_id 本次对话选中的角色资源 ID,例如 guard-role-1;不是角色描述原文,不是模型的 PromptManager 模板 ID 业务提供所选角色;管理端用同一个 ID 关联世界书,每轮据此解析允许的书籍
聊天入口名 scenarioId 选择哪份 Scenario JSON 设置,例如 agentic-v2-worldbook 业务请求的 extensions.scenario_id 指定这个名字;Router 据此找到服务启动时已加载的设置。它不选择某本书,书籍由角色绑定决定
本轮请求 requestId 本次生成操作的追踪 ID,例如 rp-turn-101 请求发起方提供;用于 RPC 追踪和选择的 seed,不替代会话 ID
角色/玩家称呼 template_vars.char/user 守卫莉娅、旅人;这是允许替换条目中 {{char}}/{{user}} 的显示文字 Harness 从角色名及用户模板变量取值;与前面的真人账号 ID 分开

请求字段如何转为上下文 · 会话检查与角色关联解析 · 身份与显示名称的使用位置

用户每发来一条消息,仓库聊天程序会按下面的顺序处理世界书:

顺序 程序做什么 使用的具体材料
1 worldbook.conversation.check 校验身份 配置的 tenantId,加可信用户 ID、会话、角色 ID(以 entity_id 传送)和场景;不是固定世界书版本
2 worldbook.bindings.resolve 读取该角色 ID 的关联 返回最多 20 本的具体 book_id + revision;本轮保留此快照
3 关联为空时直接走原产品链路 不创建 WorldbookTurn,不调用 select、不执行世界书位置装配、不改变原产品历史和预算处理;身份检查与 resolve 仍已执行,后续新增关联能在下一轮生效
4 有关联才准备 query、history 和条件 state,调用一次 worldbook.select query 只传本轮用户输入,最多 8000 字符;先从聊天历史排除这条当前消息,再传最近最多 20 条 user/assistant 历史,每条最多 16000 字符。hybrid 相关性搜索另参考其中最近两条非空消息;作者关键词仍默认扫描“history+query”末尾 4 条,条目可覆盖
5 按位置装原文,并在完整模型请求上复核预算 本轮 Actor/Sumi 主模型读到 blocks;前台循环或模型重试复用选书结果,但每次请求重新装配和计数
6 后续新一轮再次解析与选择 同一逻辑轮的重试复用已解析版本与选择结果;下一轮重新计算

身份检查、resolve、select 与 Actor 都受整轮 deadline 和取消信号约束;当前失败会向上报告,不会自动把读取失败冒充空关联。整轮时限 · 空关联与创建时点

不同产品交给条件判断的 state 不一样。代码只解析实际交来的 state.state JSON,不会自动把故事文本转成字段。当前主干已经取消“把公开场景拼到 query”的旧做法;所有产品的 query 都只取本轮输入,state 只用于条件判断:

运行链路 世界书本轮条件 state 从哪来 原文交给谁
普通 Agent V2 先读取此前已保存的 Agent V2 剧情笔记;若为 JSON 对象,整份对象作为 state。普通栏目文本不能解析时,条件为 {};不再提取 current_scene 或 Current scene: 拼进 query Actor;后台 Orchestrator、六专家、Director 不自动收到这批原文
未叠加普通 V2 后台的 RP/Compact/前台工具循环 基础 Actor 适配器交空状态,query 使用当前输入;不会自行读取另外的任务数据库。若组合普通 V2,则由 V2 先用此前已保存的剧情笔记完成选择 本轮 Actor;不因此给选工具模型增加世界书读取工具
Story 现有基础 Actor 接口交空状态;Story 的 world snapshot、事件/任务状态没有自动转换成世界书 conditions Story 的 Actor 正文请求;不是 Story 准备/结算模型的共享资料包
Sumi 明确传空状态;不会把 Sumi 场景/人物持久状态自动转成世界书条件 Sumi 生成正文与配图描述的主模型;不进入 VLM 初始化/恢复请求,也不把 lore 原文存成 Sumi 状态

例如 Director 笔记写“守卫已接过铜钥匙”,不等于选择器收到 keyHolder:"守卫";Story 有任务进度也不等于条件 quest.started 已接好。如果要按这些值过滤条目,二开必须明确提供对应结构化字段。当前 query 与 state 的分工 · V2先读状态 · 基础链路空状态 · Story走基础Actor · Sumi选择与预算

排除当前消息时,Harness 优先按请求的消息 ID 找到那条 user 消息;旧调用方没有提供可匹配 ID 时,才把末尾“role 为 user、内容与本轮输入完全相同”的消息视为当前消息。这一步只生成发给世界书的历史副本,不改动真实聊天记录。空输入在现成接线中用 continue 作为查询;自己直连接口仍需提供非空 query。当前消息去重

**每次真正调用模型前都要再算总窗口。**非 Compact 的世界书 Actor 路径会从最老历史开始缩短;当前用户输入、固定 Prompt、世界书、状态 overlay、assistant suffix、前台循环控制和已生成正文都保留。某个重试模型仍装不下,就跳过该目标;试裁失败不把后续目标本可容纳的历史一起删掉。启用 Compact 时沿压缩路径把装配后的完整请求纳入预算。Sumi 则在自己的主模型 fitMessages 中加入 lore 后计数。选择预算 2400 不是完整模型窗口。重装与历史裁剪 · Compact最终装配

Actor 与后台没有自动共享这批原文。 WorldbookTurn 只用于本轮 Actor;慢通道 planner 的输入独立组装,并不会自动收到本轮入选的世界书条目。“知识专家”这个名字也不会额外授予世界书访问能力。若客户希望后台根据同一份规则做校验,需要明确把条目传给后台,或给后台另外接一个带书籍范围的读取工具;这是二开工作。本轮持有与 Actor 注入 · Actor 状态与查询准备

日记生成路径也明确剥离本轮 worldbook;未来若已保存的聊天正文包含设定,后台/日记可以从那段聊天间接读到,但这与转发本轮原文不同。日记排除本轮世界书

能拆出来使用的能力 #

能力 交什么进去 拿到什么 谁继续处理
世界书创建与版本管理 一本书的名称、条目原文及触发规则 book_id、不可变 revision;可读取旧版本 内容管理后台保存 ID;发布修改时提交新版本
角色卡/世界书文件导入 CCv2/v3 JSON 或 PNG 中的世界书、SillyTavern 世界书 JSON 归一化条目、支持范围报告;保存后得到书籍 ID 运营检查被阻止的动态内容,再决定使用或改写
业务对象与世界书关联 角色、故事或作品的 entity_id、书籍 ID、固定或跟随最新的版本策略 已保存关联;运行时解析出的具体版本 聊天程序每轮重新读取关联,确定这次用哪个版本选条目
词法/向量搜索 查询文本、允许查询的书籍范围 排序结果、分数、最多 600 字符的原文摘录 搜索页面或自己的召回程序;它不是最终模型上下文
本轮条目选择 本轮输入、历史、状态条件、书籍版本、预算 原文 blocks、聚合 context、每条入选/排除理由 模型输入组装程序按位置放入条目
指定版本索引构建 书籍 ID、版本、是否强制重建 索引状态、分块数量、Embedding 版本 部署/运营侧维护;规则选择不需要向量索引
原文位置装配 条目返回的 position、role、depth 等 按角色资料、历史或指定区域装好的模型消息 仓库的 Actor 已有处理代码;自有聊天后端可以调用 SDK 的放置函数,或自行实现

一次使用从准备到生效 #

  1. 运营准备设定:把独立规则写成条目。为“灰港基本设定”标记常驻;为“铜钥匙与城门守卫”填写关键词“铜钥匙、城门”。原文由作者/运营提供,不是服务自动生成。
  2. 保存一本书:调用原生创建接口。服务把原文、条目和版本写入 PostgreSQL,返回书籍 ID 与版本 1。以后修改是发布版本 2,不覆盖版本 1。
  3. 决定谁使用它:若使用仓库已有的聊天服务,将请求里的角色 promptId 作为 entity_id 关联书籍;若走独立服务,可以关联自己的角色/故事 ID,再逐轮解析,也可以直接提供书籍 ID 与版本。
  4. 用户发来一句话:“我把铜钥匙递给守卫。”聊天程序取得这次允许使用的书籍版本,向世界书服务提交本轮输入与状态。
  5. 服务选出本轮原文:“灰港基本设定”因常驻进入候选,“铜钥匙与城门守卫”因关键词进入候选;通过条件与预算后返回两段原文。返回原因分别是 constant、keyword。
  6. 生成角色回复:聊天程序把这两段文字放到角色资料前,连同聊天历史和用户输入一起发给模型。模型据此生成守卫的回应;是否遵守了规则,还需要通过实际回复检查。
  7. 下一轮再算:书籍原文继续留在数据库;本轮选中的两段原文不会因此变成永久聊天历史。下一次输入重新选择,已关联的固定版本/最新版本策略决定用哪份书。

原文选择和位置装配发生在生成前,会占用本轮准备时间。它不是等后台累计若干轮再执行的记忆任务。逐轮请求与选择

运营准备什么数据 #

运营可以按下面的 JSON 格式准备世界书:name 填书名,entries 的每一项写一条设定,content 填希望模型读到的原文。整个对象可以直接提交给 POST /v1/books。运营准备这个文件时不用填写书籍 ID、tenant_id 或角色 ID:书籍 ID 在保存成功后由服务返回;研发在请求地址里指定这批书使用的 tenant_id,再通过关联接口选择使用它的角色。

{
  "name": "灰港世界设定",
  "description": "演示:常驻世界规则与按铜钥匙触发的城门规则。",
  "entries": [
    {
      "id": "greyport-background",
      "title": "灰港基本设定",
      "content": "灰港是一座蒸汽城市,城内没有电力,夜晚依靠煤气灯照明。",
      "constant": true,
      "position": "before_character",
      "audience": ["actor"]
    },
    {
      "id": "copper-key",
      "title": "铜钥匙与城门守卫",
      "content": "铜钥匙只能开启灰港城门的侧门。守卫在放行前必须核对来访者的手令,不能仅凭钥匙放人。",
      "keys": ["铜钥匙", "城门"],
      "position": "before_character",
      "audience": ["actor"],
      "priority": 20
    }
  ]
}

运营首先需要填好 条目名称、原文、何时使用。常驻条目用 constant: true;动态条目用 keys。每项给一个稳定且不重复的 id,方便后续修改与定位。同一条目可以写多条触发词,命中任意主关键词就有机会进入本轮候选。

上面的示例使用原生格式,单本提交到 /v1/books,多本可组成 {"books":[上述对象]} 提交到 /v1/imports。已有的 SillyTavern 世界书或角色卡文件则走 /v1/imports/files,由文件导入程序转换格式。两个入口的字段和保存规则不同,原生 JSON 不应作为 ST 文件上传。原生模型 · 两个导入入口

原生数据格式、校验与字段默认值
字段 含义、默认值与边界
name 必填,1–300 字符;description 默认空,最多 10,000 字符
entries 默认空数组,一本最多 5,000 条;原生批量入口一次 1–10 本
id 同一版本内唯一,最多 150 字符;建议明确填写。省略时程序按顺序补 entry-0 等
title/content 标题默认空,最多 500 字符;原文 content 必填,最多 200,000 字符。空原文不进入本轮上下文
enabled 默认 true;关闭后仍可保存、查询,默认不参与本轮选择
constant/required 均默认 false;常驻和必需的实际规则见后文,二者并非同义
keys/secondary_keys 主/次关键词数组,分别最多 200 个,每项最多 500 字符;默认空
selective/logic 默认 false/and_any;开启且有次关键词时,在主关键词命中后额外按次关键词条件过滤
case_sensitive/match_whole_words 默认均 false;可选择区分大小写、匹配完整词;支持有限正则
probability 默认 100,范围 0–100;依赖请求 seed 与条目 ID 作确定性抽选
scan_depth 条目自己的扫描深度;默认 null,使用请求层的深度;范围 0–100
conditions 最多 20 项,按调用方 state 的路径检查;操作为 eq、ne、in、exists
requires 最多 20 个同一本书同一版本内的条目 ID;发布时拒绝缺失依赖、自依赖及循环依赖
priority/order 默认 0,范围 ±1,000,000;前者影响优先选择,后者参与选择排序与最终装配顺序
conflict_key 同一冲突组只能选一个条目;默认 null
audience 默认 ["actor"];请求的 audience 必须在条目允许列表内,它不会主动把内容发给该模型
kind lore、character、rule 可作为静态资料;template、state_update、presentation 被默认选择器排除
position/depth/role 默认 before_character/0/system;实际可用位置由组装模型请求的聊天程序声明,见后文
exclude_recursion/prevent_recursion 原生条目默认均 true:不被递归内容激活,也不把本条内容用于激活别人;ST 导入有其映射默认值
runtime_requirements 默认空;非空表示需要尚未提供的运行环境,本轮不会直接注入
metadata/source 书籍附加信息/条目来源信息;不会替代 content 自动成为模型上下文

数据模型拒绝未知字段。把 tenant_id、book_id、entity_id、prompt_id 随意混入创建书籍 JSON,会触发校验错误,而不是自动建立绑定。完整契约

已有 ST/角色卡资料怎样导入 #

ST 是 SillyTavern 的简称。服务支持导入它的静态世界书,包括独立的 world-info JSON,以及 CCv2/CCv3 角色卡 JSON 或 PNG 中的 character_book。导入程序只提取世界书资料,角色卡的其他字段仍由原来的角色系统管理;SillyTavern 的动态功能也不会随文件一起运行,具体限制见下文。解析格式与报告

顺序 入口 结果与操作
1. 预览 POST /v1/imports/preview,multipart 字段为 file 返回 book 和 import_report,不落库。先看条目数、被阻止的条目和 warning
2. 保存 原文件走 POST /v1/imports/files,multipart 字段为 files;若已修改归一化 book,走原生 /v1/books 一批文件全部解析成功才进入同一保存事务,返回书籍 ID 和 revision
3. 建索引(需要向量时) POST /v1/books/{book_id}/index 显式构建本次精确版本的向量索引;规则/词法使用不依赖这步
4. 关联或调用 保存业务对象与书籍的关联,或自己的程序直接传书籍版本 保存文件不自动关联某个角色,也不自动修改已有聊天

预览报告中的 runtime_blocked_count 是需要额外运行环境的条目数。EJS 模板、MVU 状态更新、CharInfo 人物生成协议、脚本/前端面板、sticky/cooldown/delay 等动态功能,不会因为导入成功就执行;带这类要求的条目会被默认上下文选择排除。普通 {{char}}、{{user}} 可以替换,但调用方必须传入对应变量。动态能力识别

文件上传请求、重复导入和发布新版本

以下命令运行在能访问内网服务的开发环境。示例用 tenant_id=local 把书保存在编号为 local 的一组资料中;后面读取这些书时继续使用同一个值。实际接入要换成研发提供的编号,WB_BASE 换成实际世界书服务地址。

WB_BASE='http://127.0.0.1:8876'
curl --fail-with-body -sS "$WB_BASE/v1/imports/preview?tenant_id=local" \
  -F 'file=@world-info.json'
curl --fail-with-body -sS "$WB_BASE/v1/imports/files?tenant_id=local" \
  -H 'Idempotency-Key: greyport-file-import-v1' \
  -F 'files=@world-info.json'

单文件默认上限 16 MiB,批量文件和整个 HTTP body 默认各 48 MiB;一次 1–10 个文件。PNG 只读取支持的内嵌卡片元数据,不执行脚本,也不抓取其中的远程链接。

创建/导入接口支持 Idempotency-Key,用来避免重复提交创建多本书:tenant_id、key 和内容都相同时返回第一次的结果;在同一 tenant_id 下沿用 key 却换了内容,会返回 409。原生 JSON 不传 key,每次会新建一本书。原文件按文件 SHA-256 去重;重复上传同一个原文件返回最初的 revision 1,而不是后来编辑出的最新版。

编辑已有书要调用 POST /v1/books/{book_id}/revisions,提交新版本全量书籍内容,并加 expected_revision。例如当前版本 1,则提交 expected_revision: 1,成功返回版本 2;如果别人先改过,返回 revision_conflict,重新读取后再发布。此接口不是单条条目 PATCH;省略的旧条目不会自动继承进新版本。创建与去重 · 全量修订

用 SDK 接自己的聊天后端:创建、关联、选择,再发给模型 #

@flowgpt/roleplay-harness/worldbook 是世界书的 HTTP 客户端,SDK 0.6.0 已发布到 GitHub Packages。它可以在你现有的 Node.js 后端里使用,不要求先创建一个 Agent,也不会接管原有聊天流程。你的后端仍负责验证登录与资料权限、调用回复模型、展示和保存对话。0.6.0 Release · 成功发包记录

研发提供两个连接值:baseUrl 是自己部署的世界书服务地址;tenantId 是创建与读取同一批书时共用的资料分组编号。例如 greyport-demo 表示本例的灰港资料,不能从聊天用户随意输入的文字中取值。安装包需要 GitHub Packages 访问权限;本轮核到 Release 和发布流水线,未把独立安装或真实业务联调算作已经完成。

研发要做的事 客户端方法 回来什么,接下来如何使用
创建或导入资料 createBook、importBooks、previewImport、importFiles 创建/导入返回 books[] 中的 book_id、revision、导入报告;预览只给待保存内容与报告,不等于已存入数据库
读取并更新资料 listBooks、getBook、listEntries、createRevision 读到书籍/条目和版本;修订时提供 expected_revision,成功返回新版本,冲突后先读回再决定如何合并
准备向量搜索 buildIndex、getIndexStatus 指定书籍版本的构建结果或状态;需要向量能力时检查 ready,规则模式不要求调用
让某张角色卡或故事使用书籍 getBindings(entityId)、replaceBindings(entityId, {bindings})、resolveBindings(entityId) 配置接口读写关联;每轮 resolve 返回具体 books 版本。SDK 返回键名是 entityId,HTTP 返回键名是 entity_id
搜索或为模型选择原文 search、select search 给候选摘录;select 给 blocks 原文与位置、版本快照、选择原因和预算诊断。只有业务程序把 blocks 放进模型请求,模型才读得到
管理端查看多批资料 client.admin 下的查询、导入、选取和索引方法 返回对应管理结果;网络/网关与宿主后端仍负责限制管理权限,客户端不是权限系统

下面分成资料发布时和聊天时两段。例值只说明字段来源:character:guard-1 是自有业务约定的角色资源 ID;现成 Harness RP 接法则必须沿用聊天请求里的 promptId。

import { WorldbookClient } from '@flowgpt/roleplay-harness/worldbook';
import { getPlacementCapabilities, placeContextBlocks,
  type ContextMessage, type ContextLayout } from '@flowgpt/roleplay-harness';

const worldbook = new WorldbookClient({
  baseUrl: 'https://worldbook.example.com', // 换成研发已部署的服务地址
  tenantId: 'greyport-demo',               // 保存灰港资料时约定的分组编号
});

// 资料发布时执行一次;相同发布操作重试保留同一幂等键与相同内容。
const created = await worldbook.createBook({
  name: '灰港城门规则',
  entries: [{ id: 'gate-order', content: '守卫放行前必须核对手令。',
    keys: ['铜钥匙', '城门'], position: 'before_character', role: 'system' }],
}, { requestId: 'publish-greyport-1', idempotencyKey: 'greyport-book-v1' });
const book = created.books[0];
if (!book) throw new Error('创建结果缺少书籍');
await worldbook.replaceBindings('character:guard-1', {
  bindings: [{ book_id: book.book_id, revision: null, position: 0, enabled: true }],
}, { requestId: 'bind-guard-1' });

// 后续每次聊天:这里的两条消息来自已读取的角色资料和本轮用户输入。
const messages: ContextMessage[] = [
  { role: 'system', content: '你扮演灰港守卫莉娅。' },
  { role: 'user', content: '我递出铜钥匙。' },
];
const layout: ContextLayout = {
  character: { start: 0, end: 1 },
  conversation: { messageIndices: [1], emptyIndex: 1 },
};
const call = { requestId: 'rp-turn-101', signal: new AbortController().signal };
const resolved = await worldbook.resolveBindings('character:guard-1', call);
let modelMessages = messages;
if (resolved.books.length > 0) {
  const selected = await worldbook.select({
    books: resolved.books, query: '我递出铜钥匙。', history: [], state: {},
    strategy: 'rules', token_budget: 1500, seed: 'rp-turn-101',
    placement_capabilities: getPlacementCapabilities(layout),
  }, call);
  modelMessages = placeContextBlocks({
    messages, layout, blocks: selected.blocks, createMessage: m => m,
  }).messages;
}
// 业务后端检查 modelMessages 的完整 token 长度,再交给原有回复模型。
// 原有聊天业务继续展示和保存回复;下一轮重新 resolve / select。

这段示例中的 history: [] 表示没有之前的对话,并非要求正式业务丢弃历史。有历史时,把已保存且有权使用的对话同时放入原有模型输入,并按前文规则给选择器提供历史副本;不要把本轮输入重复算进去。selected.blocks 中的“守卫放行前必须核对手令”会排在“你扮演灰港守卫莉娅”之前,原有角色与用户消息都保留。书籍为空则跳过 select,因为选择接口要求至少一本书;这时继续原有模型输入。返回数据、网络失败或位置无法放置会报错,接入方需要明确处理,不能把错误当作没有设定。

客户端默认每次 HTTP 调用最多 30 秒,可在构造时或单次调用的 timeoutMs 修改,并用 signal 取消。requestId 写入请求追踪 Header;idempotencyKey 只用于创建/导入操作,不会从连接的公共 Header 偷带上一次操作的键。客户端没有自动重试、缓存或剧情调度:如果网络断开、超时或返回 WorldbookHttpError,远端写入仍可能已经发生,后端先按操作身份读回或使用原幂等键核对,再决定重试。replaceBindings 会替换整组关联,不能在不了解现有内容时把它当“追加一本”。

HTTP 方法、超时与失败处理 · 输入与返回类型 · 位置装配函数

怎样独立接入:一次创建与选择的最小请求 #

这条路径不依赖 Agent V2、Story 或 Axon。你的后端调用世界书 HTTP API,再负责把结果装进自己的模型请求。

第一步:创建。 将前面的原生 JSON 保存为 worldbook-native-example.json,提交:

WB_BASE='http://127.0.0.1:8876'
curl --fail-with-body -sS "$WB_BASE/v1/books?tenant_id=local" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: greyport-native-v1' \
  --data-binary @worldbook-native-example.json

返回的结构如下。UUID 是示意,实际使用服务返回的值:

{
  "books": [{
    "book_id": "00000000-0000-0000-0000-000000000001",
    "revision": 1,
    "deduplicated": false,
    "import_report": {"format": "native", "entry_count": 2}
  }],
  "replayed": false
}

第二步:选择。 把真实 book_id 替换进下列请求,保存为 select.json。书籍可固定 revision;为了同轮结果稳定,接入方应先解析出具体版本,再在同一轮中复用。

本轮选择请求每一项到底是什么:

字段 需要提供的具体值与来源 不填/填错的影响
URL 的 tenant_id 创建这批书时使用的编号,例如 local;由负责接入的研发提供,读取时沿用 普通 REST 接口必须填写;只有书籍 ID 正确还不够,分组编号也必须与保存时一致。访问权限由业务后端检查
books[] 已保存或关联解析返回的书籍引用,例如 {"book_id":"…","revision":1};不要传书名或全文 必须 1–20 本;本例明确版本,以免同一轮前后读到不同内容
query 本次要回应的具体文字,例如“我把铜钥匙递给守卫。”;由聊天后端从当前消息取出 必填非空,最多 8000 字符。它是选资料的查询文本,不是完整角色 Prompt
history[] 查询之前真实保存的聊天,按时间从旧到新;每条为 role(谁说的)+content(说了什么),见下方两条样例;不要再次放入已经作为 query 提交的当前消息 默认空;接口最多 100 条,每条 16000 字符。现成 Harness 排除当前消息后,只上传最近最多 20 条 user/assistant 消息
state 后端明确掌握的结构化事实,例如 {"quest":{"started":true}},用于匹配条目的 conditions 默认 {}。不是自由文本摘要,服务不自行查数据库或从聊天提取此字段。现成不同产品的实际传值见前表
template_vars 替换称呼用的字符串表,例如 {"char":"守卫","user":"旅人"} 默认空;这里的 user 是故事里的称呼,不是账号 ID
audience 本次选择允许哪个用途的条目,默认 actor 是筛选标签,不是发送目标;改为其他值不会自动给后台 LLM 注入
strategy rules 用常驻/关键词等规则;hybrid 另外把 query 和最近两条非空 user/assistant 历史用于相关性召回 原生接口默认 rules,Harness 默认 hybrid;需要向量时另准备对应版本索引。hybrid 的短历史不会改变作者 scan_depth
scan_depth 本次在“history+query”的末尾扫描多少条消息,例如 4;query 自己也占一条 默认 4,不是 4 轮对话;本例只有两条历史+当前 query
token_budget 本次世界书返回文本允许占的 token 上限,例如 1500 不是模型总窗口、输出上限或付费额度;整份模型输入仍需后端再计数
seed 本次选择使用的稳定字符串,例如 example-turn-1,用于可重复的概率抽选 原生默认 "0";现成 Harness 用 requestId,同逻辑轮复用结果
placement_capabilities 你实际能组装的位置;本例能在角色前后及聊天深度插入,因此声明这三项 没有实现 examples/outlet 就不要声明支持。服务会先过滤放不了的位置;必需条目放不了会报错

表中 ID 和文字均为教学数据。原生选择接口不收 user_id、conversation_id、entity_id 或 prompt_id 作为本轮选择字段;独立接入方先自己做权限、会话与角色到书籍的映射,再提交允许的 books。实际选择输入类型与默认值

{
  "books": [{"book_id": "00000000-0000-0000-0000-000000000001", "revision": 1}],
  "query": "我把铜钥匙递给守卫。",
  "history": [
    {"role": "user", "content": "我来到灰港城门。"},
    {"role": "assistant", "content": "莉娅拦住去路:你有通行许可吗?"}
  ],
  "state": {},
  "audience": "actor",
  "strategy": "rules",
  "scan_depth": 4,
  "token_budget": 1500,
  "seed": "example-turn-1",
  "template_vars": {"char": "守卫", "user": "旅人"},
  "placement_capabilities": {
    "positions": ["before_character", "after_character", "at_depth"],
    "outlets": []
  }
}
curl --fail-with-body -sS "$WB_BASE/v1/context/select?tenant_id=local" \
  -H 'Content-Type: application/json' \
  --data-binary @select.json

下面是返回中一条 blocks 元素的完整形状。真实响应还包含另一条常驻设定和整体诊断:

{
  "id": "00000000-0000-0000-0000-000000000001:1:copper-key",
  "book_id": "00000000-0000-0000-0000-000000000001",
  "revision": 1,
  "entry_id": "copper-key",
  "title": "铜钥匙与城门守卫",
  "content": "铜钥匙只能开启灰港城门的侧门。守卫在放行前必须核对来访者的手令,不能仅凭钥匙放人。",
  "position": "before_character",
  "depth": 0,
  "role": "system",
  "order": 0,
  "reason": "keyword"
}

拿到结果后,你的后端按 blocks 中的 position 放置设定,再加入角色资料、聊天历史和本轮输入,调用回复模型。content 保留作者原文,没有经过另一个模型总结。如果所有设定都放在同一个位置,也可以使用已经合并好的 context;如果条目指定了不同深度或插槽,就需要逐条按位置放置。

返回字段 接入方怎样使用
blocks 正式装配材料:书籍/版本/条目 ID、原文、角色、位置、原因
context 已转义并用 <worldbook-entry> 包装的聚合文本;适合诊断或单一位置注入
decisions 每条是否入选、最终原因、最初激活原因、关键词来自哪条消息或哪条递归原文;有预算尝试时,还包含依赖包和装入前后的 token 数
snapshot 本次实际书籍版本与内容哈希;与本轮请求关联,方便复现
token_count、token_budget、tokenizer、token_scope 本服务返回文本的预算,不是整个回复模型请求的 token 数
degraded 混合检索发生了什么降级;空数组表示未记录降级
diagnostics.retrieval 服务实际用于相关性搜索的 query、短历史取法与截断情况、词法/向量/合并排名,供排查“为什么搜到了这些候选”
diagnostics.budget 本次总预算、常驻配额与已花费数量、最终原文 token 数和条目上限,供排查“搜到了为什么仍未选中”
policy_version、prompt_hash、selection_fingerprint 选择策略及结果/输入条件的诊断标识
duration_ms 服务处理耗时;不包含后续 RP 模型生成

例如“铜钥匙与城门守卫”已经进入相关候选,但装入后超过预算,decisions 会说明它因 budget_dropped 未入选;它最初是如何被激活的,仍保留在 activation_reason。这样可以区分“没有搜到”和“搜到了但没有空间”,不用仅凭最终回复猜原因。诊断不改变 blocks 的用途,给回复模型的正式材料仍是选中的原文。召回诊断 · 选择与预算诊断

以铜钥匙的对话为例,原来的模型请求包含控制说明、角色资料、两条聊天历史和当前问题。加入一条选中的设定后,消息顺序如下;实际请求应包含所有返回的 blocks。

最终消息位置 role 模型读到的文字(教学例) 来源
控制说明 system “按角色设定回应,不替玩家决定行动。” 你已有的应用提示词
新插入的世界书原文 system “铜钥匙只能开启灰港城门的侧门。守卫在放行前必须核对来访者的手令,不能仅凭钥匙放人。” blocks[].content,本例要求 before_character
角色资料 system “你是城门守卫莉娅,谨慎地核对来访者身份。” 已有角色卡/角色模板
上一句用户的话 user “我来到灰港城门。” 已保存聊天历史
上一句角色回复 assistant “莉娅拦住去路:你有通行许可吗?” 已保存聊天历史
本轮输入 user “我把铜钥匙递给守卫。” 当前用户消息

表中第二行来自世界书,其余内容由原有聊天程序准备。回复模型读完这些消息,才会生成“手令呢?”这样的台词。仓库的 Harness 会为世界书原文加上 <worldbook-entry> 标记并转义;自己的聊天后端可以复用下面的放置函数,并决定是否使用同样的文本包装。

自建 Agent:把 HTTP 返回的 blocks 真正变成 messages 的代码

这是组装阶段的 TypeScript 片段,selection 指上一节 HTTP 请求已经拿到的真实 JSON 返回,不是示例中单个 block。代码不发送模型请求,也不保存聊天;得到 placed.messages 后,业务继续执行原有的完整窗口检查和模型调用。

import {
  placeContextBlocks,
  type ContextBlock,
  type ContextMessage,
} from "@flowgpt/roleplay-harness";

const messages: ContextMessage[] = [
  { role: "system", content: "按角色设定回应,不替玩家决定行动。" },
  { role: "system", content: "你是城门守卫莉娅,谨慎地核对来访者身份。" },
  { role: "user", content: "我来到灰港城门。" },
  { role: "assistant", content: "莉娅拦住去路:你有通行许可吗?" },
  { role: "user", content: "我把铜钥匙递给守卫。" },
];
// selection: 上面的 POST /v1/context/select 返回。
// 此例在请求中只声明 before_character / after_character / at_depth。
const blocks: ContextBlock[] = selection.blocks.map(block => ({
  id: block.id,
  content: block.content,
  role: block.role,
  position: block.position,
  depth: block.depth,
  order: block.order,
}));
const placed = placeContextBlocks({
  messages,
  layout: {
    character: { start: 1, end: 2 },
    conversation: { messageIndices: [2, 3, 4], emptyIndex: 5 },
  },
  blocks,
  createMessage: message => message,
});
// placed.messages:交给你自己的回复模型的完整消息数组。
// placed.placements:每条世界书原文最终落在哪个消息下标,供联调检查。

下标从 0 开始,character: {start:1,end:2} 表示只有原消息第 1 项是角色资料,右端 2 不包含;conversation.messageIndices 只列真实对话消息。SDK 不会猜哪条是角色资料,也不会自己获取世界书或计算 token。如果你的消息顺序不同,要按实际输入生成这两个位置描述,不能照抄下标。返回支持更多位置时也必须提供对应位置容器。

公开导出 · 放置函数的实际输入与返回 · Harness 对返回原文的包装和装配

此前已用固定 fafdb8d 源码的 BookCreate、SelectRequest、实际选择函数与 OpenAPI 校验本页创建/选择 JSON:两条设定入选,原因分别是关键词与常驻,返回聚合文本为 191 tokens。上面的组装片段也已用 ccaaa46e 的实际 SDK 函数离线执行:单条示例原文插在消息下标 1,得到 6 条消息。这些是样例原有的离线验证记录;本次同步的新选择器另有 70 项选择、召回诊断和位置测试通过,未把它们冒充成重跑本页全部样例。检查没有调用真实聊天模型,不等于线上权限、服务链路或模型遵循效果验收。样例当时的选择器 · 当前选择器

常驻、动态、必需:谁决定本轮读哪些条目 #

作者在条目中设置触发词、条件和优先级,聊天程序提交本轮输入、历史及文字预算,世界书服务再按这些规则选择。这个过程由程序完成,不需要另一个 LLM 阅读整本书。

类型 作者怎样设置 实际行为
常驻 constant: true 不要求关键词命中,每轮进入候选;仍受启用、受众、条件、概率、位置、预算约束,并不保证每次一定放入
动态 普通条目填写 keys;请求使用 rules 或 hybrid 关键词命中,或 hybrid 召回相关条目,再经过统一的过滤和预算;没有命中不代表资料被删除
必需 required: true 在通过资格过滤后优先完整装入;依赖、冲突、位置或预算无法满足时可报错。它不是绕过所有过滤的强制开关

执行次序:

  1. 排除停用、受众不符、状态条件不符、不支持动态运行环境、概率未通过、空内容或无法放置的条目。
  2. 首轮激活必需、常驻、直接关键词命中和 hybrid 召回的条目。
  3. 展开同版本内的显式依赖,把“条目+依赖”作为一组,检查冲突、条目数和预算;先录取必需,其次可选常驻,再处理其他候选。默认可选常驻发起的包最多消耗总预算的 35%。
  4. 只有已经录取且允许向外递归的条目/依赖正文,才能触发下一次关键词扩展;下一次扩展再检查依赖、冲突和剩余预算。默认最多额外扩展 2 次。已录取的直接相关项不因后续递归候选而被挤掉。
  5. 返回完整原文和实际选择原因。装不下的可选条目整条被排除,不自动缩写成摘要。返回 policy_version: native-bounded-v3。

例如“北塔风俗”虽然命中了,但太长而被预算排除,它正文里的“南港”不会再把南港条目带进来;只有北塔条目真正入选,且允许递归,才会继续带出相关设定。每轮先录取再递归 · v3 返回标识

例如“守卫手令规则”命中了,但被标记为仅在 state.quest.started = true 时允许使用;聊天程序这次没有提交这项状态,规则仍不会进入。state 必须由调用接口的聊天程序提供,服务不自行查询剧情数据库。选择步骤

扫描、混合召回、预算与递归的具体控制参数
参数 服务接口默认值 作用
strategy rules rules 走作者规则;hybrid 加入同范围词法+向量召回,再经相同条件和预算选择
scan_depth 4,范围 0–100 扫描“history 的内容+本轮 query”末尾多少条消息;query 也算一条。4 是消息数,不是四轮对话;0 关闭关键词扫描
token_budget 1500,范围 0–32000 返回原文包装后的总预算;不是整个模型上下文窗口
constant_budget_ratio 0.35,范围 0–1 可选常驻条目的预算上限占比;必需条目不受此常驻配额限制,但受总预算限制
max_entries 50,范围 1–200 最多放入多少条,依赖也计数
max_recursion_rounds 2,范围 0–5 首次匹配后额外进行的有限递归轮数;需条目双方允许,不等于默认递归所有内容
seed "0",最多 200 字符 概率抽选的稳定种子;相同输入下便于复现。Harness 使用 request ID
audience actor 只有条目的 audience 包含它,才有资格参与;不是权限认证
template_vars 空对象 内容中 {{char}}、{{user}} 的替换来源;未提供所需变量则排除该条
history 空,最多 100 条 每条必须有 role/content;每条 content 最多 16,000 字符
query 必填,1–8000 字符 本轮查询文字;不等于整个系统 Prompt
books 必填,1–20 本 明确限定书籍范围;单次快照还受条目数量和原文总量上限约束

当前 v3 在每次扩展中先放必需组,再放常驻组,再放其他候选;组内依次看 required、高 priority、关键词命中、混合得分、高 order、稳定 ID。装配输出另按位置、深度及 order 排序,不能把“优先入选”理解为“最后放在 Prompt 哪儿”。

次关键词逻辑仅在主关键词已命中、selective=true 且有次关键词时参与:and_any 至少命中一个;and_all 全部命中;not_any 一个都不能命中;not_all 不能全部命中。

hybrid 在同一本书版本范围内结合词法和向量排序;不是 LLM reranker。向量不可用或指定版本索引没就绪时,hybrid 在 degraded 标注原因并退回词法候选;纯 vector 搜索会直接返回错误。规则选择无需 Embedding。

hybrid 的查询先保留完整的 query,再从 history 中取最近两条非空 user/assistant 消息。每条历史最多取末尾 2000 字符,查询加历史和换行合计不超过 8000 字符;空间不够时优先留下更新的一条,当前 query 已占满 8000 时就不加历史。它返回的策略名是 current-input-recent-history-v1,并记录实际用了哪些 history 下标、是否截断。system 消息与 state 不参与这一步,rules 和独立 /v1/search 也不会使用这套短历史增强。查询组装 · 仅在 context hybrid 调用

作者关键词扫描继续读原始 history+query,遵守请求或条目自己的 scan_depth。因此“hybrid 最多参考两条历史”与“关键词默认扫描末尾四条消息”是两个不同的范围;诊断会分别给出相关性搜索候选和关键词命中来源。selection_fingerprint 也加入了查询策略及实际用于搜索的文字,方便对照同一次选取所用的材料。关键词窗口与命中来源 · 选择指纹

**中文词法召回也已调整。**例如查询“铜钥匙”,词法排名使用连续二字“铜钥”“钥匙”,不会仅因其他资料包含孤立的“铜”或“匙”就增加一次相关性排名贡献;文档仍保留单字索引,明确输入一个汉字时仍可搜。这个变化影响词法排名及 hybrid 合并结果,不改变作者 keys 的子串/全词/正则匹配规则,也不是新增一次模型调用。CJK 查询分词

服务的计数默认 cl100k_base,只计算返回的 context。接入方仍须计算角色、聊天历史、工具消息和输出预留组成的完整请求。当前 Harness 在世界书装配之后、发模型之前做最终 Actor 请求预算检查;超出时会以 agent.context_overflow 失败,世界书 1500/2400 tokens 的小预算不能替代模型总窗口配置。接口默认值 · 混合降级 · 最终请求预算

9 月 22 日合入的 Worldbook #17 减少了这里的重复工作:一次请求中已经选中的原文和精确 token 数会暂存下来,候选真正进入预算尝试时才生成转义后的包装文本;相邻条目使用相同扫描深度时,也复用本次扫描材料。每次尝试仍对“原来选中的内容+这次候选”的完整文本精确计数,不把条目 token 简单相加,也不改用近似估算。缓存只存在于这次选择里,下一轮、另一批书或另一种 tokenizer 不共用。选择顺序、依赖、冲突、常驻配额和 native-bounded-v3 规则不变;目前没有真实流量数据能说明具体快了多少。请求内文本与精确计数复用 · 完整候选仍精确计数

原文放进模型输入的哪里 #

“本轮注入”就是把选中的条目原文装成这次模型请求中的消息。它不表示永久改写角色卡、给模型训练新知识,或把整本世界书塞进历史。

条目 position 模型实际看到的位置 聊天程序需要准备什么
before_character/after_character 角色资料之前/之后 角色资料区域;默认可用
at_depth 真实聊天历史按消息深度定位的位置 聊天消息位置,默认可用;不把示例和世界书条目当作聊天轮次
before_examples/after_examples 对话示例区域前/后 明确提供结构化 examples;不能靠猜角色卡内的小标题定位
author_note_top/author_note_bottom 作者注释容器内的顶部/底部 聊天程序提供作者注释 authorNote;加入的设定沿用这段注释的消息角色
outlet 聊天程序在模板里预留的位置,例如名为 scene_lore 的段落 条目填 outlet_name,聊天程序提供相同名称的模板位置与标记

服务根据 placement_capabilities 先排除聊天程序无法插入原文的位置。普通条目被排除并记录原因;必需条目找不到位置则报错。服务不声明位置能力时只允许前三种默认位置。当前 Harness 会明确声明本次真实具备的区域,而不是把所有 8 种位置都声称可用。位置资格 · Harness 位置装配

哪些资料什么时候保存,什么时候生效 #

对象 谁触发保存 保存到哪里 什么时候使用/生效
世界书原文、规则、导入报告 运营通过内容管理后台调用创建/导入/修订 API,或由研发编写程序调用 PostgreSQL 的书籍、不可变版本、条目记录 成功后可用具体版本执行规则选择;不是等用户聊天才保存
当前版本指针 发布新 revision 的同一事务 书籍 head 跟随最新的关联在下次 resolve 读到新版本;固定旧版不变
业务对象与书籍关联 管理端/可信后端调用 PUT 迁移后的 entity_worldbook_bindings;entity_id 标识角色/故事等对象 下一逻辑轮 resolve 生效;本轮已取得的快照不重算
向量索引 明确调用 index 构建 PostgreSQL 中的向量、索引状态和 Embedding 版本 对应精确 revision ready 后可参与向量检索;新原文版本不自动沿用旧索引
本轮选择结果 世界书程序生成 Harness 当前 WorldbookTurn 内存 本轮 Actor 和同轮重试使用;不自动写入规范聊天历史
选择诊断 trace Demo 的 onTrace 接收 Demo 可按回复 ID 保存在浏览器缓存 用于查看本轮实际装配了哪些条目;不是持久化的世界事实
Worldbook RPC 观测 开启并被采样的 Harness telemetry Langfuse,包含请求/返回的有限正文预览 用于排查、超时和取消定位;不会回灌模型或作为下一轮记忆
用户正文、模型回复、剧情/人物状态 聊天后端和各产品自己的保存程序 各自聊天与状态存储 世界书服务不代替它们保存,也不自动把剧情变化回写世界书

关联保存示例(书籍 ID 替换为实际返回值):

{
  "bindings": [{
    "book_id": "00000000-0000-0000-0000-000000000001",
    "revision": null,
    "position": 0,
    "enabled": true
  }]
}

提交到 PUT /v1/entity-bindings?tenant_id=local&entity_id=guard-role-1。这里的 guard-role-1 是外部角色资源的 ID,不是角色名字或 PromptManager 模板 ID。revision: null 表示跟随最新版;正整数表示固定版本;bindings: [] 清空。PUT 原子替换这个业务对象的全部关联,不是只追加本次列表;最多 20 本,不能重复。

每轮 GET /v1/entity-bindings/resolve?tenant_id=local&entity_id=guard-role-1 返回:

{
  "tenant_id": "local",
  "entity_id": "guard-role-1",
  "books": [{"book_id": "00000000-0000-0000-0000-000000000001", "revision": 1}]
}

这是逐轮解析角色关联,不是“建会话时永久 pin 一版书”。无启用关联返回空 books,Harness 不创建世界书运行对象,保留原产品的渲染和预算;显式关联的书或版本失效,整次 resolve 返回 409 binding_book_not_found,不会只取剩余正常书继续。修改书或关联会影响已有会话的下一轮,不会重写已经产生的历史消息。关联保存与全有或全无解析 · Harness空绑定处理

新接口也可关联 story:123 这样的故事 ID。服务只按“资料分组编号+业务对象 ID”存关联,没有角色/故事类型枚举,也不会查这个对象是否存在。宿主业务决定命名规则和编辑权限;若角色 123 和故事 123 是不同对象,应在 ID 中区分它们。旧 Prompt 接口原本也能接收宿主定义的 ID,因此这次变化是把合同名称统一为 Entity,不是首次允许故事复用资料。

HTTP 调用 ID 怎么传 返回哪个字段
GET /v1/entity-bindings、PUT /v1/entity-bindings、GET /v1/entity-bindings/resolve 查询参数至少提供 entity_id 或兼容名 prompt_id 中的一个;两者同时传时必须相等 entity_id
旧 GET /v1/prompt-bindings、PUT /v1/prompt-bindings、GET /v1/prompt-bindings/resolve 同样接受两个名称,遵守同一校验与存储规则;路由已标记 deprecated,仍可调用 prompt_id

两组路由都必须传 tenant_id,服务没有默认分组;ID 为 1–200 字符且不能带首尾空格。书籍 ID 和关联列表仍放在 {"bindings":[...]} JSON 中,不把 entity_id 混进创建书籍内容。以服务实现为准,旧的三个 Prompt 路由仍保留;新版 SDK 和 Harness 已采用新 Entity 合同。

升级已有数据库时,要执行 007_entity_bindings.sql:把 prompt_worldbook_bindings 表改名为 entity_worldbook_bindings,将其中 prompt_id 字段及相关约束改名,保留已有数据。005/006 历史迁移保持不变。生产说明要求协调手工迁移并维持 AUTO_MIGRATE=false;迁移之后再核对 Service、Axon 与 Harness 的调用,避免新代码查询尚未改名的表。代码已合入不代表这一步在生产完成,本轮没有生产迁移回执。

新旧路由与 ID 校验 · 整组验证、保存与解析 · 007 保留数据的迁移 · 升级顺序

索引、异常处理、独立部署与身份接入

索引。 POST /v1/books/{book_id}/index?tenant_id=local,请求 {"revision":1,"force":false}。这是同步构建接口;已有相同 Embedding 版本的 ready 索引会复用。正文每 1000 字符取最多 1200 字符块,存在重叠;按批生成 Embedding。生成索引不会改变原文和条目 enabled。失败记录 failed,重试该版本;单版本同时构建冲突返回 index_busy。索引实现

部署。 服务需要 Python 3.12–3.13、PostgreSQL;仓库提供依赖锁文件、Dockerfile、迁移和本地 Compose。仅规则模式 VECTOR_BACKEND=none 不调用 Embedding;启用 pgvector 后需要对应向量配置和 Embedding 服务/本地后端。原文与向量同在 PostgreSQL,向量可由原文重建。依赖与启动配置

每次调用普通 REST 接口,都要在请求地址里填写 tenant_id,服务没有默认值。这个参数只决定去查哪一批资料,服务不会验证请求者是否有权读它。因此,面向用户的产品应由聊天后端或网关先检查登录身份、可读的资料范围以及管理权限,再调用世界书服务。/v1/admin/* 可以查看不同分组的资料,也要限制谁能访问。自带 Python client 虽会发送 Bearer Header,当前服务代码不会据此校验用户。实际分组参数 · 无认证测试

通过 Harness 使用世界书时,业务后端先向 Harness 发聊天请求,Harness 再通过 Axon 调用世界书服务。Harness 把业务后端核实过的用户账号 ID 放进 X-User-ID 交给 Axon,用来检查用户、会话和角色是否对应;不能由最终用户随意填写这个 Header。Worldbook Service 本身无需 Axon;直接通过 HTTP 使用时,由自己的后端检查权限并管理书籍版本。Axon 属于外部依赖,本文对 RPC 的说明以 Harness 调用端为准,不把外部仓库实现当作本次已扫描代码。

Demo。 Harness 的世界书 Demo 提供查看关联、聊天和注入诊断;共享导入和关联修改不对 Demo 开放。不能把 Demo 的页面包装直接当成完整对外的世界书管理产品。Demo 接口边界

情况 当前结果 接入方应做的事
该业务对象没有关联书籍 空书籍列表,现成 Harness 跳过选择继续生成 可展示“没有关联资料”,无需伪造选中结果
无动态条目命中 对应条目 not_triggered;其他合格条目照常选择 检查 query、扫描窗口、关键词、条件与预算
普通常驻装不下 constant_budget_dropped 或 budget_dropped 缩短/拆分资料,调整常驻配额或总预算
必需条目无法容纳、依赖失效、冲突 明确错误 修复资料/预算;不要悄悄删掉必需规则继续
向量索引未就绪 hybrid 标注降级;纯 vector 搜索报错 检查精确 revision 的索引;明确是否接受词法退化
修订并发冲突 409 revision_conflict 重新读取 head,合并修改后再发布
同幂等 key 用了不同内容 409 idempotency_conflict 新操作使用新 key;同操作重试保留原 key 和原内容
分组编号、书籍 ID 或版本不匹配 404 或明确绑定错误 核对保存这本书时使用的 tenant_id、返回的书籍 ID 和实际存在的版本
最终 Actor 输入超模型窗口 agent.context_overflow 调整完整输入预算或模型配置,不只看世界书 token_count
服务调用失败 当前世界书解析/选择接线向上抛错 明确产品错误提示与重试;不要描述成现成的“自动无世界书继续”

运行排查:怎样观察请求、选择和索引的变化 #

研发排查“最近回复变慢了”时,可以先看世界书服务是不是收到了更多请求、请求是否在等待检索、向量查询是否失败后改用文本相关性继续查找,以及数据库连接是否不够用。Worldbook #18 在 9 月 24 日合入的 005e19c 为这些步骤增加了 Prometheus 指标和 Grafana 看板。程序仍按原来的规则保存资料、构建索引、召回和选择条目;指标记录发生过的操作与结果,不会改变给回复模型的原文,也不会把监控结果写成剧情状态。请求观测 · 检索、选择与索引中的记录位置

例如,业务方可以查看过去十分钟是否出现了更多“角色没有关联书”的解析结果,以及成功选择带回的原文条目数分布。但这些是按接口、策略和结果汇总的数量,不带角色、用户、书籍或请求正文,不能从中还原某一位用户为什么没有读到“守卫必须核对手令”。核对这一轮的具体版本、选择理由和最终模型输入,仍使用本页后面的 Langfuse 记录或接口诊断。空关联时 Harness 会跳过选择,所以“没有关联书”和“执行选择后得到零条原文”也是两个不同的统计。关联解析的计数

想查什么 服务记录什么 解读时要保留的区别
哪类接口变慢或失败 HTTP 方法、路由模板、状态码、完成次数、耗时和处理中请求数;search/select 等待四个检索并发槽的耗时 /metrics 抓取本身不计入;接口耗时到响应建立为止,不包括完整网络传输。看板的 API 总量限定 /v1/*
角色有没有关联资料 关联解析的 empty、bound、error 次数,以及成功解析得到的启用书籍版本数 只统计进入解析处理函数的请求;空关联是有效结果,不直接等于服务故障
选择带回了多少原文、为什么没选中 成功 select 返回的 blocks 数、世界书文本 token 数、预算使用比例,以及每条条目的决定原因,如 keyword、not_triggered、budget_dropped token 数不是整个模型请求长度;预算为零时不记录比例。决定原因按条目计数,一次选择会增加多个计数;当前“空选择比例”面板还有下述查询缺陷
查资料卡在哪一步 读取书籍版本快照的耗时和原始条目数、成功 search 的返回数、向量查询耗时与成功/错误、hybrid 降级次数和原因 快照条目尚未过滤禁用、受众或运行要求;向量耗时包括索引检查、查询 Embedding 和向量查询。hybrid 可降级为词法结果,纯 vector 失败仍报错
指定版本的索引是否构建成功 索引 built、reused、failed 次数、完整构建耗时,新建成功时的 chunk 数 普通/管理接口和启动 Embedding 重建共用这些记录;复用或失败不增加新建 chunk 数,状态查询接口本身也不代表发生过构建
数据库或服务进程是否吃紧 PostgreSQL 连接池大小、可用连接与等待数,进程资源,以及启动 Embedding reset 的状态和已处理/计划版本数 连接池与 reset 状态在抓取时读取;看见 reset 仍在运行,不会自动改变现有 readiness 的通过条件

这些指标保存在各服务进程自己的 registry 中,Counter 会随进程重启归零;Prometheus 定期抓取后保存时间序列,Grafana 再读取它们画图。世界书数据库不会因此多保存一份聊天或逐轮监控记录。服务用路由模板(如 /v1/books/{book_id})和有限的结果名称作为标签,避免为每本书、每位用户创建一组指标;这就是本次“低基数”的具体含义。指标定义与抓取时取值 · 完整指标字典与计数口径

负责世界书部署和监控的研发/运维需要接通整条读取路径:运行包含指标代码的镜像,让 Prometheus 抓取服务同一端口的 GET /metrics(8876),再把仓库的 deploy/grafana/worldbook-service-dashboard.json 导入 Grafana,选中对应的 Prometheus 数据源。看板共有 36 个面板、34 条查询,覆盖上表中的 API、选择、绑定、向量降级、索引、连接池、进程与启动重建;导入看板本身不会建立告警规则。运营无需为此改书籍内容或角色关联。指标 HTTP 入口 · 看板文件

部署、抓取与看板变量需要怎样接通

服务启动时为每个应用进程创建独立 registry,并把同一组指标对象传给 WorldbookService;当前 Dockerfile 只启动一个 Uvicorn worker。/metrics 输出 Prometheus text,不额外查询书籍数据库;抓取时读取 psycopg 连接池统计和内存中的 Embedding reset 状态。部署改成多个 worker 时不能直接假定一次抓取代表所有进程。应用构造 · 容器启动

staging 与 agent-production 的 Deployment 清单都新增了 prometheus.io/scrape: "true"、prometheus.io/port: "8876"、prometheus.io/path: /metrics。负责部署的人还要把注解实际应用到运行中的 Pod 模板,并确认 Prometheus 的 Pod discovery 会采用这些注解。production 发布工作流只执行 kubectl set image 和 rollout 验证,不会自动 apply 清单,所以只发新镜像不足以完成首次抓取配置。production 抓取注解 · staging 抓取注解 · 发布实际更新字段

Grafana 的 Namespace、Pod 选项从 kube_pod_info 读取,因而下拉菜单出现目标 Pod 也不证明世界书指标已被抓取。Prometheus 数据源需要包含这组 Kubernetes 数据,并给抓取到的世界书指标附加 namespace、pod 标签;看板查询依赖这两个标签筛选服务。接入后应读回实际 Pod imageID 和注解,确认 Prometheus target 为 UP、相应时间序列存在,再用确实有结果与确实空选择的请求检查面板。多 Pod 的耗时分位数应先按 le 聚合直方图桶;低流量时 p95/p99 只是容易跳动的估计值,不能据此直接承诺时延。看板变量与标签前提 · 发布后检查说明

/metrics 没有应用鉴权,应由部署方限制为监控网络可访问,并确认 Grafana 数据源、看板的访问权限。仓库的 Service 使用集群内部服务形式,但本轮没有读回实际 NetworkPolicy 或入口配置,不能从仓库未见公网入口推断运行环境已经隔离。入口与部署边界

当前“空选择比例”面板有一个已复现的查询问题。对固定源码中的 Metrics 记录一次零条选择后,服务实际导出 worldbook_selection_entries_bucket{le="0.0",strategy="rules"} 1.0;看板却用 le="0" 查这个桶。标签按字符串精确匹配,分子因此没有序列,面板会无数据,不能把它当作“空选择为 0%”的验收证据。需要先把查询改为实际的 le="0.0" 或经过验证的兼容写法,并核对实际导出与查询是否匹配;这项修正尚未包含在 005e19c 中。错误查询 · 条目数直方图

现有测试会核对看板 JSON 与生成器一致、面板有说明;它没有把实际 registry 导出的标签交给 PromQL 验证。PR 作者记录的“34 条查询可解析”也只能证明语法可解析,不能证明查询命中了预期数据。005e19c 的 main CI 已成功;巡检固定快照本地为 132 passed、35 skipped,跳过项因缺少 TEST_DATABASE_URL,这些测试结果均不能代替真实抓取和业务请求验收。现有测试边界 · main CI

运行排查:哪些内容会记录到 Langfuse #

研发可以用这些记录检查“本轮到底查询了什么、选中了什么、在哪一步失败”。当 HARNESS_TELEMETRY_ENABLED=true、凭据齐全且本轮被采样时,程序把 worldbook.conversation.check、worldbook.bindings.resolve、worldbook.select 三个 RPC 的输入、返回及成功/失败/超时/取消状态记录到 Langfuse;原 RPC 的参数、返回与取消原因不因观测而改变。

记录 包含什么 用来回答什么
identity check 资料分组编号 tenant_id、角色 ID(entity_id)、聊天会话 ID、所选配置名;RPC 名称和 requestId 是否核对了正确会话与角色
binding resolve 资料分组编号 tenant_id、角色 ID(entity_id)、具体 books 与 revision;bookCount、emptyBindings 本轮是否未绑定、是否用了期望版本
select 输入 当前输入 query、排除当前消息后的最多 20 条已截取历史、结构化 state、books、预算、位置能力、变量 为什么某个条目可能被触发或被条件排除
select 返回 diagnostics 中的实际搜索文字、词法/向量/合并排名和预算汇总;decisions 中的匹配来源、激活/排除理由及依赖包;blocks 原文、快照、耗时和降级 哪一步找到了候选,为什么最终入选/被排除,以及准备阶段怎样耗时
失败/取消 error 类型、消息、可用错误码和 Axon error data 是服务失败、整轮超时还是调用取消

Langfuse 总开关默认 false;开启时还要提供 LANGFUSE_BASE_URL、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、HARNESS_TELEMETRY_ENVIRONMENT。HARNESS_TELEMETRY_SAMPLE_RATE 默认 1,可设 0–1。当前没有独立的“只记指标、不记世界书正文”开关:开启 telemetry 就允许记录由程序封装的 Worldbook 请求/返回。9 月 30 日合入的 #273 已取消普通模型/工具正文只在 staging 记录的限制;启用 telemetry、配置有效且该调用被采样时,所有环境均可导出程序实际传入的内容。字段遮罩、长度上限继续有效;没有埋点或没有交给观测程序的内容不会因此自动出现。当前配置与内容范围 · 三种 RPC 的观测

每份输入/输出最多保留 16,000 个 JSON 字符;超出后保留结构化 preview,并标记 truncated、originalChars。authorization、cookie、password、secret、API key、access/refresh token 等精确键名会脱敏,HTTP 凭据 headers 本就没有送入观测;聊天、剧情 state 和 lore 原文本身会保留。现在程序优先放入 diagnostics 和 decisions,再放较大的设定原文,所以即使 lore 被截断,诊断里的本轮输入和最近两条对话仍可能留在预览中。有限预览不能保证完整重放一轮,也不能作为“没有保存聊天内容”的依据。脱敏与结构化截取 · 诊断优先顺序

还要区分 Langfuse 和服务自己的运行日志。主干 #236 会把世界书读取的开始、结束等阶段写到 stdout,部署环境可将它收集到 Loki;关闭 HARNESS_TELEMETRY_ENABLED 不会关闭这组日志。Agent Router 的请求开始日志还会保存原始用户输入,最多 16,000 字符,以及输入长度和哈希;模型、工具、Memory 的错误消息最多保留 300 字符。这些 stdout 字段不经过 Langfuse 的凭据键脱敏,production 也没有自动关闭它们。发布前需要分别确认两条日志路径的访问、保留和删除安排,不能只看 Langfuse 总开关。当前已确认该代码合入 main;10 月 11 日 Sumi ebab290 有成功生产部署记录,但不能据此推断所有 Harness 服务实例或最新改动已经更新。世界书运行阶段记录 · 原始输入日志 · 日志写入与错误内容

目前交付到哪一层:代码、镜像与运行证据 #

Worldbook #20 与 Harness #288 已合入,SDK 0.6.0 已发布。10 月 12 日巡检补核到:Entity 关联版本 ad38dce 已在 10 月 9 日 10:59 成功部署到生产环境,测试、镜像构建推送、固定镜像和等待服务就绪步骤均成功。这是补齐此前遗漏的部署证据,不是 10 月 12 日新增上线。数据库 007 迁移、Axon 转接和真实业务调用效果仍需单独确认。Entity 版本生产部署记录

本次更新10 月 19 日巡检再次核对主线与部署列表,Worldbook 没有更晚的主线或部署增量;本轮未重新展开 10 月 9 日的部署日志,沿用此前已核记录。随后同 SHA 的一次运行取消且没有执行部署步骤,不能据此认为前一次部署被回滚。下面保留旧版本的变化与验证范围,便于区分功能何时加入。

9 月 22 日发布到世界书生产环境的更新有两项:hybrid 查询开始参考最近两条对话,并返回候选排名、命中来源和预算诊断;随后又减少了一次选取中的重复文本组装与精确计数。前者随 88c99e99 在 18:04–18:06 发布,后者随 fca57b8 在 21:13–21:15 发布,后一次包含前一次的功能。这两项保留了原有导入、绑定、关键词规则和返回原文的合同,不是新增世界事件或自动修改角色卡。短历史版本的部署 · 9/22 历史部署

fca57b8 的工作流已通过 PostgreSQL 检查、Ruff、全量 pytest,完成镜像构建/推送、固定镜像 digest、更新生产镜像和 rollout;deployment 6591512315 为 success。这次成功发布的历史证据继续有效。9 月 24 日 11:27,Worldbook #18 的监控代码随后以 005e19c 合入 main;当时 9 月 24 日 14:26 收口,没有这个 SHA 对应的 GitHub production deployment;这份旧检查不覆盖 10 月 9 日的 Entity 发布状态。监控 PR #18

9 月 24 日的 PR 作者记录称已把看板导入 production Grafana,并读回 36 个面板、34 条可解析查询;当时记录镜像和抓取注解尚未部署。后续 10 月 9 日 ad38dce 的成功镜像部署已确认,但工作流只更换镜像,不会自动应用新增注解。巡检没有直连 Grafana、Prometheus 或集群确认当前抓取状态。实际 Pod imageID、注解、target 是否 UP 和真实流量序列仍需查验;真实聊天选择效果和 Harness 流量采用也未验收。

对象 本次已经确认 接入/发布时还要完成
Entity 接口与数据库 Worldbook #20 新旧接口共用 Entity 存储,Harness #288 已改用 Entity RPC;旧关联由 007 改名迁移保留 服务版本 ad38dce 已有生产部署记录;仍须取得 007 迁移回执并联调 Axon,当前 RP 的实体 ID 仍来自 context.promptId
独立 SDK 客户端 SDK 0.6.0 已有 Release 和成功 GitHub Packages 发包记录 配置服务地址与资料分组编号,核验访问权限并完成创建/关联/选取/模型输入的联调;发布不等于业务采用
多产品世界书接线与本轮输入 Harness main 已含普通 RP、Compact、Agent V2、Story、Sumi 接线和空关联跳过;#223 已把 query 改为当前输入,并在 history 中排除当前消息,state 只作条件材料 仍需读取正在运行的服务,核实实际镜像、聊天配置、资料分组编号、Axon 连接与访问权限
Selection v3、hybrid 短历史与诊断 Worldbook 在 fca57b8 已保留先录取后递归、CJK bigram,并包含短历史查询、候选排名、匹配来源和预算诊断;当时选择/召回诊断/位置定向测试 70/70 通过。005e19c 新增观测,不改这些行为 真实“那这个呢”等省略输入是否选对资料,以及规则、向量/混合检索和产品采用,仍需业务请求验证
请求内计数与文本复用 Worldbook #17 已合入 main 并包含在 21:15 完成发布的版本中;同一候选完整文本仍精确计数,不改选择合同 真实延迟和 CPU 改善没有量化结果;需要按同一请求对照选择结果及运行耗时
Prometheus 指标与 Grafana 看板 Worldbook #18 已合入,后续 ad38dce 镜像有生产部署记录;看板导入属于作者记录,当前抓取注解与数据仍未独立查验。固定快照可复现“空选择比例”查询未匹配实际零桶 修正 le="0" 与 le="0.0" 的不匹配;核实实际镜像、Pod 注解、target、序列及访问范围后,才可用来验收服务运行情况
关联失效处理 main #13 已把不存在的书/版本统一作为整次 resolve 的 409;migration 006 删除关联表两条外键,完整性改由服务校验 生产默认 AUTO_MIGRATE=false;发布 workflow 不执行 006,需数据库执行回执及孤儿数据检查。旧 SQL 镜像回滚到无外键库需特别核对
Worldbook 已核的最近生产部署 10 月 9 日 ad38dce 的 run 37876956192/deployment 6951845283 成功,含实际更新镜像与 rollout;9/22 两次成功部署作为历史保留 当前 Pod digest、007 迁移、有效配置及真实流量尚未独立读回,部署事件不能代替关联与选择结果的验收
Harness 9/23 已核镜像构建事件 43332d8 的 main CI 35770764488 和镜像工作流 35771926336 成功;代码已含世界书诊断优先记录、staging 内容记录和常开 stdout 生命周期日志 镜像 job 只有构建/推送,没有 apply、rollout 或 readiness。其 deployment 6598612800 标为 success 仍不等于 Agent Router workload 已更新
staging 配置交付 内置 Worldbook 示例使用的资料分组编号为 production-default,staging manifest 写 staging-default Worldbook staging workflow 只 patch 镜像和 Demo JSON;Sumi 只 set image。新的资料分组编号和环境变量不会因此自动进入正在运行的服务,必须核对实际配置再联调

Worldbook 实际部署步骤 · 带数据库的检查 · Harness 镜像工作流 · 关联校验 SQL · 006迁移 · Worldbook staging 实际更新字段 · Sumi staging 实际动作

本次更新**尚在开发分支:PR #15 的滚动发布策略。**这项修改希望更新世界书服务时先启动新实例,等它就绪后再回收旧实例,减少发布期间的服务空窗。巡检固定 head 仍为 be19065bb5507f5856f78e51a6b662632f51b477,PR 仍开放,10 月 19 日列表仍显示开放;本轮未重新核对 head 与评论,不能把它算进已部署的 ad38dce 主干功能。它不改变条目选择算法、导入格式或世界书关联接口。PR #15

滚动发布候选、当前 readiness 和运行证据怎样区分

主干生产清单仍为 Recreate,005e19c 增加抓取注解时没有改变这项策略。PR #15 改成 RollingUpdate,配置 maxSurge:1、maxUnavailable:0、minReadySeconds:10:允许先多起一个新实例,在新实例就绪后维持 10 秒,再逐步替换旧实例。但现有发布工作流只更新镜像,不会自动 apply 这份部署策略;合并清单与改变线上策略是两步。主干清单 · 候选清单

当前 /health/ready 会连接数据库并检查 book_revisions、vector_chunks 两张表;它把 embedding_reset 状态写在返回中,但该后台任务 pending 或 failed 不会让 readiness 失败。若这次启动需要重建/重置 Embedding,旧实例可能在新实例仅满足数据库和表检查时被替换,向量与混合检索尚未证明可用。因此候选的发布验收需要覆盖真实检索、更新期间请求和失败回滚,不能仅用 Pod Ready 代替这些结果。实际 readiness · 后台 Embedding reset

生产清单还把 /cache 放在每个服务实例自己的临时目录中,代码中叫 emptyDir。新实例不会继承旧实例的这份缓存,因此发布验证不能假定“旧实例已准备好,新实例就能直接沿用”。这说的是实例内的临时缓存,不是数据库里的书籍和条目。缓存挂载与目录定义

PR 作者另有“手工 patch production 并读回 1/1 Ready、镜像未变”的运维记录;巡检未直接读集群,这条保留为作者记录,不当作主干已合入或本次独立确认。另一方面,10 月 9 日 ad38dce 的生产部署工作流成功是已取得的直接事件证据,不能因上述后续验收尚缺而改写成“未部署”。工作流使用固定 digest 发布,也不等于巡检已经独立读回当前 Pod 的 imageID;本页不补写未取得的实际值。

二开时能直接复用什么,还需自己补什么 #

世界书服务已经实现资料保存和版本管理、静态文件导入、角色与书籍关联、规则/混合选择、指定版本索引和诊断。自己的聊天后端可以直接使用这些接口:search 用于浏览和搜索资料,context/select 用于回复前选择设定,无需先采用整套 Agent V2。

接入之后,聊天后端仍负责把返回原文放进模型请求,检查总长度,确认用户有权读取这批书,并保存聊天和业务状态。如果希望让主 Agent 自己决定何时查询,研发还需要注册查询工具,限定它能访问的书籍,定义参数,并把结果交回主模型。

目前,Story/Sumi 的状态还不会自动转换成世界书选择条件,后台专家也不会自动收到回复模型使用的同一批条目。剧情变化回写世界书、新 NPC 自动建卡并保存、运行完整 ST 动态功能,以及独立服务的公网用户鉴权,都需要另外开发。

本次更新截至 2026 年 10 月 19 日,Worldbook main 仍为 ad38dce1de7ccd291d702a67b92c06a966fddf85,本次没有新增世界书代码;Harness 最新核对主干为 f9b26a919965f471756cdacf0f5b2e596cd5991d。原有 Entity 关联、SDK 客户端、导入和选择规则继续有效。Worldbook #15 滚动发布与 #19 urllib3 2.8.0 升级在列表中仍开放,本轮没有重新核对两个分支的代码和评论;主线依赖仍为 urllib3 2.7.0。ad38dce 的生产部署事件已补齐;生产数据库迁移、当前运行实例和真实请求效果没有独立验收。

原子能力 / 工具与应用接线

记忆与状态:什么时候写,下一轮拿回什么

10/19 更新 · 本章 16 处从第一处开始看 →
新消息到来后读取旧笔记,后台按需咨询专家并决定是否更新;需要更新时由 Director 整理完整笔记,程序校验后按版本保存。Actor 同时用旧笔记生成当前回复,后续请求读取已保存的新版本。

这里只画普通 Agent V2 的后台笔记。聊天原文、日记和表格各有保存规则,后文分别说明;下一句不会为了等新笔记而暂停。

可左右滑动查看 放大查看流程图 ↗下载 SVG

用户说“钥匙已经还给守卫了”。要让角色在下一句记得这件事,后端先要保存已确认的归还事实,下次生成回复前再读出来,交给模型。项目里的文字记忆、记忆表和 V2 后台笔记各自读写;改了一份,其他记录仍保留原来的内容。

你的业务怎么运行 在 Agent 的哪一步接入 谁配置、交什么、回来以后谁用
自己的 Agent/Workflow,要读写自己的 JSON 数据 回复前直接读,或把读工具提供给模型;写入放在业务认可变更的时刻 研发用 createMemoryTools 绑定自己的存储和用户范围。读回 revision + memory,由业务转为模型材料;调用写工具时即提交新对象
使用仓内 RP 应用,要复用外部记忆、日记或表格 应用在 Actor 回复前召回,生成后调用对应写入/通知路径 研发选择 memoryRuntime 和 memorySources,配置服务与 Actor 模板。结果是日记文字、表格文字或外部服务返回的变量;模板引用后才参与回复
使用普通 Agent V2 的后台持续状态 由该产品的后台分析、Director 与版本提交链路维护 这是 V2 产品自身的处理流程,不因添加 get_memory 就自动共用一份数据库;实际输入、提交和下轮投影见 Agent V2
使用 Sumi 图文聊天的场景与人物状态 每轮先对照当前角色资料和用户选中的聊天历史,生成后保存本轮新快照 材料或历史分叉不匹配时从可见正文重建;仅用户参考图改变且历史指纹、父链全部匹配时,可只更新用户外观并复用剧情状态。它与 V2 的 Director 笔记分别保存,详见 Sumi 的状态与图片流程

聊天已经交给本仓库的 apps/emochi 服务时,研发修改该入口的 config/scenarios/<入口名>.json:用 memoryRuntime 选择记忆实现,用 memorySources 指定来源,连接对应服务,并在 Actor 模板中引用返回的变量。如果聊天和模型调用仍由自己的后端处理,可以使用下面的 createMemoryTools,在原有代码中读记录、组装模型输入,再按产品规则决定何时写入。

聊天服务在启动时读取配置,修改文件后需要重启或重新发布。实际文件目录由 HARNESS_SCENARIOS_DIR 决定,启用的文件由 HARNESS_ENABLED_SCENARIOS 选择;同 ID 的 AGENT_ROUTER_SCENARIOS_JSON 会整份覆盖文件设置。上线时需要核对服务实际加载的是哪份配置。配置加载与覆盖

独立 JSON 记忆工具 #

后端从 @flowgpt/agent-core-tools/memory 导入 createMemoryTools,把只允许访问当前产品、用户和会话的存储交给它。模型调用工具时使用这份已绑定的存储,参数中没有让模型改查另一个用户、聊天或其他产品记录的 ID。

动作 输入 直接结果 何时保存、谁用
get_memory {} {revision, memory};没有记录时 revision:0, memory:null 只读;模型或程序接着使用返回对象,不调用 LLM
update_memory {expectedRevision, memory} 写成功后的 {revision} 调用时就执行存储提交,不是只生成候选;下次 get_memory 返回新对象

例:业务后端已确认当前是用户 user-42 在聊天 conversation-8 中与城门守卫对话。这两个 ID 由登录结果和聊天记录提供,后端据此创建只访问这份记忆的 scopedStore;**它们不由模型填进 get_memory / update_memory 参数。**以下数值和文字是教学示例:

顺序 实际输入/返回 接下来谁处理
回复前读取 调 get_memory({}),返回 details:{revision:7,memory:{scene:"城门",keyHolder:"用户"}} 后端把对象整理成“当前在城门;钥匙持有人是用户”,放入本轮模型输入;或由选中此工具的模型直接读工具结果
业务认可本次变化 已采用的正文确认“守卫接过铜钥匙” 接入方决定这是可以保存的事实;如果产品要求用户接受正文后才改,需在此等待接受事件
提交完整新对象 调 update_memory({expectedRevision:7,memory:{scene:"城门",keyHolder:"守卫"}}) 工具先校验,调用绑定存储执行版本检查与写入;成功返回 details:{revision:8},不要再额外写一次
下一句生成前 同一份绑定存储再次读取,得到版本 8、keyHolder:"守卫" 后端重新整理并交给本轮模型;旧请求已发送的 Prompt 不会被数据库更新追溯修改

expectedRevision 填上次读取的存储版本,用来防止基于旧记录覆盖后来的修改;它与聊天轮数无关。memory 的完整字段由产品定义,scene/keyHolder 仅用于本例。没有记录时返回版本 0 和 memory:null,首次写入用 expectedRevision:0。产品需要按角色或聊天分支隔离时,由后端存储实现这些范围,工具只使用绑定好的存储。

这里是完整替换,不是字段合并。如果新对象只写 {"keyHolder":"守卫"},原来的 scene 会被删除。expectedRevision 必须使用产生该修改时依据的版本;冲突后重新读和重新判断,不能拿旧提议配一个新版本强行覆盖。

记忆必须是普通 JSON 对象,不能把数组、null、函数或循环对象当成整份记忆。序列化后最多 64 KiB,嵌套深度上限 32;版本是非负安全整数且小于 Number.MAX_SAFE_INTEGER。空记录严格对应 revision:0, memory:null,已有记录必须是正版本和对象。beforeUpdate 可以做业务字段检查,检查通过后才调用后端绑定的存储;写入后若返回的版本不是旧版本+1,工具报错,此时要先读回确认,不能当作一定未写入而盲目重试。

参数、写入与结果 · JSON范围、大小和深度校验 · 完整读取、冲突和业务接受示例

自己的后端怎样调用记忆工具 #

把下面的代码放进后端原有的聊天处理流程。生成回复前,后端读取记录并把字段整理成模型输入;等产品确认本轮发生了需要保留的变化,再执行写入。例子中的两次调用分别发生在这两个时刻。createMemoryTools 只负责读写,新的 memory 对象由业务规则或另一次模型调用产生;“钥匙还了”如何变成 keyHolder:"守卫",也由这一步决定。

import { createMemoryTools } from '@flowgpt/agent-core-tools/memory';

const [getMemory, updateMemory] = createMemoryTools({
  store: {
    get: signal => scopedStore.get(signal),
    compareAndSet: (commit, signal) => scopedStore.compareAndSet(commit, signal),
  },
  beforeUpdate(memory) {
    if (typeof memory.scene !== 'string') throw new Error('scene 必填');
  },
});
// 回复模型调用前:读取本次已绑定用户和会话的记录。
const current = (await getMemory.execute('read-1', {}, signal)).details;
// 在你的原模型请求中加入 current.memory 对应的文字,再生成回复。
// ……业务确认“钥匙已交给守卫”后,再执行下面的完整替换……
const saved = await updateMemory.execute('write-1', {
  expectedRevision: current.revision,
  memory: { scene: '城门', keyHolder: '守卫' },
}, signal);

例子中的 scopedStore 需要研发实现:数据库在同一次原子操作中检查版本并写入,成功后返回原版本+1。产品若要求用户接受正文后才保存事实,后端就先保留修改提议,收到接受事件再调用写工具。工具设置了 replay: "never";遇到结果不确定的写入,应先查回记录,再决定后续处理。

例如 current.memory 是 {scene:"城门",keyHolder:"用户"},后端可将“当前地点:城门;铜钥匙持有人:用户”加入这次回复模型的消息。scene 这些字段本身不会自动成为 Prompt;如果后端既没有转换成消息,也没有把工具返回交回正在选工具的模型,读取虽然成功,回复仍用不上。消息实际放在哪一条见 上下文组装。

/memory 是工具包的正式导出入口。仓库的发布配置为 GitHub Packages、restricted 访问;使用发布包还需要相应包读取权限,不能默认从公共 npm 匿名安装。若按源码构建,也需安装该入口使用的 TypeBox 等依赖。

memory导出与发布权限配置

产品里已经接好的几种资料 #

仓库应用从聊天请求和配置的服务中取得材料。假设用户 user-42 在 conversation-8 中与角色 guard-role-1 对话,各种记忆实现会分别用到下面这些字段:

材料 谁提供、这个例子里是什么 哪条接法实际使用
用户与聊天身份 登录/业务后端确认 userId:"user-42"、sessionId:"conversation-8" Personalization Hook 接收这两个字段;Axon Go 按用户与会话召回;Hinos 当前适配器把会话 ID 放入请求头,不能据此推断它已有独立鉴权
当前角色 角色/作品记录的 promptId:"guard-role-1",对应“灰港城门守卫”的角色资料 Hook 收到 Prompt ID;Hinos prepare 收到渲染后的角色 system 文本及来源 Prompt ID。Prompt ID 是取资料的引用,模型要读的仍是实际角色文字
聊天与本轮输入 消息服务提供原始消息顺序,如上句“天黑前还钥匙”,本句“我回来了” Hook 收到 messages,并取得末条用户消息作为 question;Hinos 要求正式 user/assistant 对话最后一条为本轮用户。Axon Go 的日记/表格召回 RPC 不传这句 query 做语义搜索
本次调用标识 后端生成 requestId:"turn-21" 用于关联召回、通知和诊断;不能用它替代用户身份、会话或数据库版本
选择哪个记忆来源 研发填写 memorySources,例如 id:"shared-experience"、agentRef:"your-memory-service"、variable:"compassMemory" id 是研发为该来源起的区分名称;variable 要与 Actor 模板引用的变量名一致。Personalization 的 agentRef 填 Axon 中已有记忆服务配置的 ID,由维护该服务的研发提供;Axon Go 用日记来源的这个值作为缓存引用。Hinos 的地址由 HINOS_MEMORY_URL 提供,不能把 agentRef 当 URL

下表列出仓库应用各类资料的保存时机。自行调用公共 JSON 工具的后端,则按上一节实现存储和写入条件;字段名称相同,也仍是分别保存的记录。Hook 的实际身份与聊天字段 · Axon Go 召回参数 · Hinos 的实际材料

资料 什么条件下处理 什么时候存 下次取回什么、怎样用
聊天正文 聊天业务接受并保存消息 聊天服务自己的保存流程 原始消息;业务作为历史提供给生成链路
V2 后台状态 普通 V2 后台决定更新并产出有效候选 状态校验和版本检查后,通过 Axon CAS 提交 文本状态+分类记录,再投影为 Actor / 后台各自的上下文;详见 V2 产品
Personalization 外部记忆 不指定 memoryRuntime 或选择 personalization,且配置记忆来源 正文生成后通知来源服务;具体提炼和落库由该服务实现 回复前调用来源的 Hook,取回模板变量;下面给出完整接法
Axon 日记 配置 compassMemory 来源、相应运行时与日记编排器;轮次、额度等策略允许 回复完成事件安排后台;规划允许后生成、解析并 appendDiary 摘要取为 compassMemory;需要模板实际引用才会进入正文模型
Axon 记忆表 配置 memoryTable 来源;回复里有可应用的表格编辑 回复完成后提取编辑,确有变化才替换表格;版本冲突至多重读重试一次 表格提示文本 memoryTable,版本另留供后续写入
本次更新Hinos 外部记忆 选择 memoryRuntime:"hinos" 并配置 hinosMemory 来源 本轮取得有效 claim_id、Actor 成功产出正文并通过取消检查后,提交用户输入和正文;要求返回 committed:true。若本轮读取故障后选择继续回复,因没有有效 claim 而跳过提交 下轮重新 prepare;服务恢复后可取得新的 claim 和记忆。正常返回空记忆仍有 claim,仍提交本轮对话
Compact 历史摘要 预算或检查点边界触发;默认同步,可显式选择优先后台 同步路径在 Actor 前检查并提交;后台路径独立完成后才提交,不等待本轮正文被接受 读取当时已保存的摘要+剩余原文;后台未保存就沿用旧版本,详见 Compact
Story 世界/叙事快照 Story 自己的准备、正文确认与结算流程 按 Story 对消息锚点和存储版本的检查提交 世界事实、事件和叙事状态;详见 Story

Compact 的后台压缩与 V2 的 Director 后台是两种任务:前者压缩已存在的聊天原文,后者更新剧情笔记。async_preferred 获准时,程序复制本轮开始时的材料让压缩继续,Actor 使用本轮已准备的旧摘要/原文;只有后来成功提交的压缩存档才供后续请求读取。若显式采用 trim_history,本轮还可能临时省略尚未进入摘要的旧原文,不能把省略理解成已保存。后台压缩与当前输入

Axon Go 一次召回会返回日记摘要、表格文字和表格版本。应用分别处理它们;下表中的铜钥匙文字是教学示例,实际内容由记忆服务返回:

服务返回 应用怎样处理 最终给谁
merged_summary,例如“用户曾向莉娅借铜钥匙,答应天黑前归还。” 转为 compassMemory 变量 Actor 模板引用后成为实际输入文字,帮助角色承接以前发生的事情
table_prompt,例如表格文字中写“物品:铜钥匙;持有人:用户” 转为 memoryTable 变量 Actor 模板引用后可以读到现有表格;回复后若有可应用编辑,走表格保存流程
tables、table_version、table_found 应用留存原表格及版本,例如版本 7,供本轮编辑解析和版本替换使用 保存程序使用;不能把版本号当成角色应该说的内容

应用收到摘要后,Actor 模板引用 compassMemory,才能把摘要写进本轮输入。下一句会重新召回当时的资料。召回返回的实际转换

研发要在这条聊天入口所用 Actor 的 ModelConfig/PromptManager 提示词中引用记忆。例如加入 已知共同经历:{{getvar::compassMemory}};表格使用 {{getvar::memoryTable}},Hinos 使用 {{getvar::hinosMemory}}。收到示例摘要后,第一句就会展开成“已知共同经历:用户曾向莉娅借铜钥匙,答应天黑前归还。”,随角色提示词一起发给 Actor。memorySources 负责选择服务,这些模板负责把服务返回的内容写进模型输入,用户聊天原文保持原样。角色模板实际渲染入口 · 日记/表格变量模板测试 · Hinos 变量模板测试

日记有自己的轮次规则:节点默认 min_rounds=20、免费周期 free_rounds_per_diary=10;另一组 memory_v2 配置默认首次 20、后续 10。是否生成、只存摘要还是同时存日记,还要看 planDiary 返回及免费/付费策略。这些条件只用于日记,普通 V2 后台和其他记忆实现各自决定执行时机。

日记和表格此处收到的是回复完成事件,代码没有在这里额外等待“用户接受这段正文”的确认事件。业务若需要接受之后再保存,应在接入层明确实现该条件,不能用“后台保存”替代产品的接受规则。

取回摘要和表格 · 何时安排写入 · 日记节点默认参数 · 规划、生成和实际保存

已合入 Fusion 分支:一条回复分段续写后,怎样继续使用后台笔记 #

一条角色回复可能分几次生成。例如,先显示“守卫接过钥匙”,接着在同一条消息末尾追加“又伸手向你要手令”;聊天页面仍把它们保存为同一条消息,编号都是 assistant-101。如果后台在第一段生成后已经保存了一份笔记,续写使正文变长,不应仅因此认定这份笔记属于另一条回复。

Harness 的 PR #209 针对这种情况修改了笔记读取检查:只要消息、用户输入和所选聊天配置等检查通过,追加段落后仍可读回这条回复关联的后台笔记。它不负责重新分析追加的文字,也不保证旧笔记已经包含后来续写的内容。截至 9 月 24 日 08:29 的巡检,它已合入 fusion-harness,包含该实现的后续版本 c8fc61c86883fb2e9fceefab721b45f0829760f2 已有生产 rollout 记录;普通 main 没有因此获得同样保证。这里更新的是分支及部署状态,业务是否遵守重新生成时更换消息 ID 的规则仍需检查。分支读取实现

采用这项修改还有一个前提:用户编辑或重新生成回复时,聊天服务必须为新版本分配新的消息 ID。比如把“守卫接过钥匙”改成“守卫拒绝收下钥匙”,如果仍保留 assistant-101,分支代码可能继续读到改写前的笔记,让后续剧情沿用已经不成立的事实。正常追加与改写旧内容是两种操作,所有客户端和聊天后端都需要一致地区分;这轮巡检尚未取得这项跨端行为的完整验证。

Fusion 分支保留哪些检查,接入前还需核实什么

读取时,程序先比较本次请求里可见的助手消息与消息服务中保存的版本:消息 ID、角色和当前正文必须一致。随后检查笔记关联的 scenarioId、messageId、snapshotRef,以及此前用户输入的 ID 和正文校验值,再按引用取回笔记。PR 删除的是“保存笔记时那版助手正文”的 contentSha256 校验,没有删除当前请求与消息服务之间的正文核对,也没有移除状态写入的版本冲突检查。读取检查 · 消息关联及编辑前提 · 提交前的版本检查

因此,即使当前请求与消息服务中的改写后正文完全相同,只要改写沿用了原消息 ID,仍不足以证明旧笔记适用于新正文。接入验证需要分别覆盖同一消息追加、编辑、重新生成及切换聊天分支,确认每次读回的笔记对应用户正在继续的那条对话。

9 月 22 日早一轮曾记录候选 CI run 35688099954 失败,这是当时版本的历史结果。后续巡检已核对合入后的分支源码;9 月 24 日 03:16–03:19,包含这项修改的 c8fc61c 完成 Narrative Fusion 生产 rollout。当前实例镜像没有独立再次读回,客户端编辑/重新生成的消息编号规则也仍需跨服务验收。后续版本的读取检查 · 部署记录

表格已经保存,后续提炼失败时,日志可能仍显示“写入失败” #

Axon 记忆表的顺序是:先把修改后的整张表写回,并拿到新版本;如果业务开启了表格样本提炼,再生成和上传提炼样本。后一步失败不会撤销前面已经写入的表格。例如“钥匙持有人”已从用户改成守卫,随后上传样本超时,下一轮仍可能读到“守卫持有钥匙”。

#236 合入后的统一日志把这两个步骤放进同一段成功/失败判断:只有表格替换和后续提炼都完成,才记录 memory_write_completed;提炼失败则记录 memory_write_failed。因此看到失败日志,不能直接认定表格没写进去,更不能直接把同一修改再执行一遍。应先按当前用户和聊天读回表格及版本,确认主写入是否完成,再处理失败的提炼步骤。实际保存和提炼顺序

9 月 23 日巡检的离线复现确认了“表格替换成功、提炼失败,最终只有 started → failed 日志”这一情况。它是当前实现中的状态表达问题,不是已经确认的线上事故;拆分主写入与提炼结果仍是待修项。日志记录的内容与开关见请求、模型、工具和记忆日志。

默认 Personalization:让外部记忆服务参与回复前后 #

假设用户上一轮答应归还铜钥匙,这一轮说“我回到城门”。Harness 先向配置的外部记忆服务读取资料。服务若返回“用户答应今天归还铜钥匙”,Actor 模板就能把这件事交给回复模型,让守卫接着追问钥匙。回复生成后,Harness 再把本轮输入和回复发给同一个服务,由它决定如何更新记忆。

不指定 memoryRuntime 时使用这条路径;仍需配置 memorySources 和真实服务。没有来源就不会自动出现一套长期记忆。这里的外部 Agent 是带地址、参数和启用状态的服务配置,不是普通 V2 的六位专家。默认运行时的选择

时机 Harness 实际做什么 拿到什么、结果怎样使用
读取来源 按 memorySources[].agentRef 从 Axon 取外部 Agent 配置,同一引用只加载一次 服务地址、是否启用、参数、超时及凭据引用;不是这位用户的记忆正文
回复前召回 并行向启用来源的 /update 发 event:"beforeChat",附用户、会话、角色 Prompt ID、聊天、本轮问题及订阅/语言信息 来源返回 setvars 字符串数组,例如 {{setvar::compassMemory::用户答应今天归还铜钥匙。}}
准备模型输入 提取与来源 variable 同名的内容,并把返回的变量交给基础上下文组装 模板实际引用该变量,正文模型才会读到;没有匹配值或返回空白时,这项没有可用记忆文本
本轮正文生成后 通过取消检查后,并行向这些来源发 event:"chatResponse" 发送用户/会话、输入聊天、最终正文、原始正文与 reasoning;外部服务决定是否提炼、保存什么、怎样落库
对外报告完成 等本次通知调用返回,再发送 turn.completed;Agent Router 对写入通知采用 best_effort 通知失败会发 memory.ingest_failed,但正文仍可完成。通知 HTTP 成功也没有提供统一的数据库版本/提交回执
下一轮 再次走 beforeChat,读取当时服务返回的内容 不直接沿用上一轮内存里的变量;新资料是否已出现,需要检查这次返回及最终 Actor 输入

Harness 在这里负责请求和通知,累计多少轮提炼一次、何时写入数据库、冲突后怎样重试,都由外部服务决定。这条路径没有调用 Axon Go 的 planDiary。验收时除了确认服务收到对话,还要向服务查回记录,核实归还事实是否已经保存。

本次更新研发需要让两端配合:聊天服务配置 memorySources 和 Actor 模板,记忆服务实现下面的 /update 协议,按用户和会话读写资料。已有服务满足协议时,直接填入其配置即可。Router 默认在召回失败时停止本轮生成;10 月 14 日合入的 #301 允许研发为指定入口选择“没有召回记忆也继续回复”。回复后的通知失败仍记录错误并允许正文完成,读取与写入各按自己的规则处理。

召回与变量提取 · 正文完成后的通知 · 生成、通知和完成事件的顺序

Personalization 的配置、Hook 协议和失败处理含 1 处更新

如果聊天已由仓库应用处理,研发在该入口的 config/scenarios/<入口名>.json 顶层合入以下记忆来源设置;保留原有模型等字段,再让服务重新加载。例如:

{
  "memoryRuntime": "personalization",
  "memorySources": [{
    "id": "shared-experience",
    "agentRef": "your-memory-service",
    "variable": "compassMemory"
  }]
}

id 由研发命名,用来区分这份配置中的多个来源;agentRef 填 Axon 已保存的记忆服务配置 ID,Axon 据此返回服务地址和参数,不能填一个未注册的工具名或直接填 URL;variable 要与服务返回变量及 Actor 模板引用保持同名。上例只选择通路,接入者还需配置服务、凭据、返回格式和模板。

Hook 请求都发到 api_url 去掉末尾 / 后的 /update。有对应 API key 时附 Authorization: Bearer …;API key 由聊天服务按配置的 api_key_env_name 或 Agent 引用提供。请求超时取来源配置与聊天服务的 Hook 时限的较小值,并传递取消信号。来源加载 · HTTP 地址、凭据与时限

回复前的有效返回示例:

{
  "setvars": [
    "{{setvar::compassMemory::用户答应今天归还铜钥匙。}}"
  ]
}

setvars 缺失、不是数组或混有非字符串时,适配器只保留其中的字符串;匹配 variable 的宏需是完整 {{setvar::变量名::内容}},同一来源中重复赋同一变量取最后一个。没有匹配正文时记忆项为空,不能拿“HTTP 200”代替材料采用检查。通知接口则没有类似 Hinos 的 committed:true 或 JSON 记忆工具的 revision 确认,不能共用那两套成功判定。返回处理与宏匹配 · 两种 Hook 的真实请求

本次更新live:false 的来源会跳过,不报作调用失败。加载配置失败或任一回复前 Hook 明确失败,会使普通召回失败;未配置新策略时仍按 memoryRecall:"fail_turn" 停止本轮。显式设置 continue_without_memory 后,程序记录失败并改用空记忆继续 Actor,不把部分来源成功当成整份记忆成功。正文生成成功后,普通来源仍尝试原有写入/通知;memoryIngest:"best_effort" 没有改变,通知失败可记录后完成,整轮取消仍向外传播。多个来源并行执行,某个来源失败不等于其他来源没有完成外部写入。axon_shadow 的正式返回和写入仍使用 Personalization,只额外比较 Axon Go 的召回结果。普通召回失败与空记忆替代 · 入口实际失败策略 · Shadow 的采用与写入

Hinos:外部记忆服务怎样参加一轮 #

仓库应用还可以把记忆交给 Hinos 服务处理。研发需要先部署或连接 Hinos;应用通过它的 prepare 和 commit 接口读写,独立 JSON 工具 get_memory / update_memory 和 V2 的 Director 状态不参与这份记忆的保存。

时机 Harness 发送什么 服务返回什么、接下来怎么用
Actor 回复前 调用 /v1/memory/prepare,发送已渲染的角色 system 消息、业务提供的 user/assistant 正式聊天(末条必须是当前用户),以及本次请求编号、所选入口配置名、模型配置 ID 和角色资源 prompt_id 等来源字段 校验协议后取得 claim_id、memory 文本、turn、state_through_round。claim_id 标识本次准备;它不是 JSON 记忆工具的版本号
本轮组装 Actor 输入 memory 非空时,把它设为 hinosMemory,再执行基础上下文准备 模板实际引用 hinosMemory 后,Actor 才能读到这段资料;返回空文本则继续使用原有准备结果
本次更新Actor 正文生成完成后 本轮取得有效 claim 时调用 /v1/memory/commit,发送同一 claim_id、本轮 user 输入和 assistant 正文;读取故障后选择继续的本轮没有 claim,跳过 commit 要求响应协议正确且 committed:true;这是 Hinos 接收本轮对话的回执,其内部如何提炼、存储不在本仓实现。正常空记忆不等于读取故障,仍会提交
下一轮 再次调用 prepare,提供新的正式聊天 取得服务为新一轮准备的 memory;不保证上一轮输入每个字都出现在返回记忆中

例如,本轮用户说“我答应明天归还铜钥匙”,Actor 回应“守卫点头,记下了约定”。Harness 把这两段文字提交给 Hinos,下一轮再读取它返回的记忆。服务可能返回“用户答应明天归还铜钥匙”,也可能按自己的提炼规则组织其他文字;Harness 将实际返回内容放进模板。

prepare 的有效返回还必须包含协议名 schema:"hinos.external_memory.prepare.v1"。例如返回 claim_id:"claim-21"、memory:"用户答应明天归还铜钥匙。"、整数 turn:21 和 state_through_round:20:真正进入模板的是 memory;claim-21 由程序带回本轮 commit,用于匹配同一次准备;两个轮次字段是服务报告的轮次信息,当前适配器校验其为安全整数,并不用它们决定“累计多少轮才写”。这些是教学值,不是客户端应自行指定的固定结果。

本次更新正常取得 claim 时,应用等待 commit 返回后才发出 turn.completed,期间没有另等用户接受正文。prepare 失败默认阻止本轮生成;显式开启下面的容错策略后,只有可恢复的服务故障才允许缺少 Hinos 记忆继续。该轮没有有效 claim,因此不发 commit,也不会沿用上轮 claim。正常 commit 失败仍发记忆写入失败事件,Router 的 memoryIngest:"best_effort" 允许正文完成;用户可能已经看到正文而记忆未保存,须另查提交结果。

使用仓库聊天服务接 Hinos 时,研发在该入口的 config/scenarios/<入口名>.json 顶层加入以下字段,并在服务部署参数中设置 HINOS_MEMORY_URL,然后让服务重新加载。HINOS_MEMORY_TIMEOUT_MS 默认 10000 ms。memorySources 中必须恰好有一项 variable:"hinosMemory";id、agentRef 仍是这份 JSON 中记忆来源的必填字段。若实际使用环境变量 AGENT_ROUTER_SCENARIOS_JSON 提供入口设置,应修改其中对应对象,避免它覆盖文件中的新设置。

{
  "memoryRuntime": "hinos",
  "memorySources": [{
    "id": "external-memory",
    "agentRef": "your-hinos-source",
    "variable": "hinosMemory"
  }]
}

服务收到 x-flow-conversation-id 与 x-request-id 请求头。当前适配器不附带独立认证凭证,接入部署需要自行配置受信服务访问及其权限边界;这里不能把会话 ID 当成鉴权。

当前 prepare、claim 与提交规则 · 调用失败分类与输入复用 · 服务地址与超时

本次新增记忆服务暂时不可用时,要不要继续这一句 #

本次新增例如用户问“我上次答应过你什么”,日记服务却超时。默认行为是这轮报错,不让角色在缺少记忆时继续回答。研发可以为某个聊天入口选择继续:程序记录 memory.recall_failed 和 degraded:true,去掉本轮召回记忆,再按已有角色资料和聊天历史生成。代价是角色这次确实可能答不出早前的约定;这项策略不保证回答仍然完整。

本次新增这项选择已随 #301 合入主线,默认仍是 fail_turn。研发在实际加载的 config/scenarios/<入口名>.json 顶层加入下面的片段;通过环境变量维护配置的部署,则放在 AGENT_ROUTER_SCENARIOS_JSON.<入口名> 中。它与 memoryRuntime、memorySources 同级,不放在 Actor 提示词或 agenticV2 内。

本次新增
{
  "failurePolicy": {
    "memoryRecall": "continue_without_memory"
  }
}

本次新增删除这项设置、使用空 failurePolicy,或显式填 fail_turn,都会恢复严格失败。解析器拒绝拼错的字段、错误类型和其他策略值。配置按前文启动加载规则生效;10 月 19 日虽有包含这些代码的 Sumi 镜像部署,尚没有证据证明 Emochi 的某个实际聊天入口已选择该策略。配置解析 · 默认值与实际传入

发生什么 显式选择继续后,本轮怎样处理 回复成功后是否仍写入
本次新增普通 Memory recall 抛错 先检查本轮是否已取消;未取消才记录失败,用空 Memory snapshot 继续 普通日记/Hook 等仍走既有 ingest,不因读取降级统一跳过
本次新增Hinos prepare 的连接/读取超时、响应体传输失败,或 HTTP 429/5xx 使用已经完成的 Axon 准备结果继续,不重新执行 Axon 和 Hooks;清空 Hinos 来源记录 本轮没有有效 claim,核对本轮身份后跳过 commit;下一轮服务恢复可重新 prepare
本次新增Hinos 正常返回空 memory 正常的空召回,不记作失败,也不需要容错 仍有有效 claim,仍提交本轮用户输入与回复
本次新增Hinos 地址不合法、包含用户名密码或使用 fetch 禁止端口;401/403/其他 4xx;成功响应是坏 JSON/协议不符 仍报错,不能用“继续回复”掩盖配置、鉴权或协议错误 不靠容错提交
本次新增缺角色来源、正式聊天末条不是当前用户;整轮取消/超时;Actor 或 Axon 失败 不属于允许跳过的 Hinos 服务故障,仍走原失败/取消规则 按原流程停止,不创建可提交的假 claim

本次新增Hinos 的实际 prepare 发生在 Axon 已生成角色材料之后,程序新增了回调把这个较晚的失败也记进同一轮事件。continue_without_memory 只改变上述读取失败后的选择,不改变正文成功条件、写入确认协议或普通 V2 的 Director 状态提交规则。普通失败记录 · Hinos 故障范围与复用

应用接入开关与需要接通的依赖

Scenario 的 memorySources 每项包含 id、agentRef、variable,可有 priority。Axon Go 接法只支持 compassMemory 和 memoryTable,没有配置相应来源就不发对应召回请求。当前召回 RPC 按用户、会话和来源取资料,没有把本轮“铜钥匙”这个 query 传去做语义搜索。

memoryRuntime 可以选 personalization、axon_shadow、axon_go、hinos。axon_shadow 只比较两套召回,正式返回和写入仍使用原 Personalization 服务;axon_go 按配置的来源装配日记编排器;Hinos 使用自己的服务地址和超时。研发需要按所选实现配置这些依赖。

不指定 memoryRuntime 时,当前 Router 使用 personalization 路径。Axon Go 的日记召回条数还受 subscriptionCategory 影响:默认 1、plus 2、ultra 3、max 5;这是召回资料量,不是生成/保存日记的轮数。表格与日记返回的是本次可用的提示文本,日记缓存 agentRef 来自所配来源,不能把它误当成模型自动选择的检索工具。

日记生成会依次涉及额度、锁、轮次规划、模型、解析、保存和可选通知;表格写入涉及编辑解析、版本替换和可选提炼上传。表格替换后即使提炼失败,已经写入的表格仍可能存在,需要查回确认。日记和表格的返回文字都要经模板引用,才能进入模型输入。

多种记忆运行时装配 · 来源与运行时配置校验 · 表格保存与后续副作用

二开时的最小验收 #

连续执行三步:读取旧值 → 触发一次明确修改并检查保存回执 → 新请求读回新值并确认真正放入模型输入。同时测一次版本冲突和一次保存失败。若接日记/表格,还要验证“不满足轮次/没有编辑”时确实不产生相应写入。

原子能力 / 应用模块

历史压缩:对话变长以后,模型怎样继续读材料

10/19 更新 · 本章 32 处从第一处开始看 →
默认同步压缩流程:程序读取聊天历史与旧摘要,计算完整模型输入。触发压缩时将较早历史生成摘要,保留最近原文,再组装并检查总长度;符合条件才保存摘要供后续复用。未触发或压缩失败时检查可用输入,仍超出模型窗口则报错。

上图是默认同步流程:先完成压缩再调用回复模型。显式启用 async_preferred 后,符合条件时本轮先用现有材料回复,后台保存的新摘要供后续请求读取;具体准入、临时裁历史与失败处理见下文。图中的“本轮可用”不等于检查点已经保存。

可左右滑动查看 放大默认同步流程图 ↗下载 SVG

用户与角色聊久以后,早期聊天会逐渐挤满模型一次能读取的窗口。Compact 把较早的一段历史总结成摘要,保留近期原文,再检查本次输入能否放下。它帮助模型继续这次对话;需要长期检索或完整保留旧事时,还要使用相应的记忆和聊天存储。

Compact 目前在仓库应用内实现,包括压缩程序、Scenario 配置和检查点读写。使用仓库应用可以沿用这套实现;保留自己的后端则需要集成源码,提供模型、计数、稳定消息 ID 和存储。两个公共 npm 包尚未导出整套服务。

本次更新本章更新到 2026 年 10 月 19 日的已完成巡检,对应主线 f9b26a9。这次修复了“日记更新后,旧历史摘要被误判失效”的问题:生成仍读取最新日记,但判断旧摘要能不能接着用时,不再把日记内容变化算成角色设定变化。真正的角色资料、配置或已覆盖聊天变了,原来的失效检查仍然执行。

本次更新后台压缩、为摘要预留空间、角色卡临时精简及 #295 的计数修复也已在主线。10 月 19 日部署的是包含这些代码的 Sumi 镜像,不能据此认定 Emochi 的 Compact 入口已采用。后台执行和角色卡兜底仍需研发显式配置,历史过滤默认关闭,边界搜索默认仍为 binary。新增的摘要质量检查 #305 仍在开发分支,尚未合入。

下文先说明本轮与下一轮的材料和保存时机,再展开模型分工、摘要位置、边界搜索和过滤与保存。这些是仓库应用实现;SDK 0.6.0 已发布不代表 npm 包导出了整套 Compact 服务。

配置契约 · SDK 公开导出范围

先看压缩前后真正拿到什么 #

RP 应用先读取角色、记忆和已有压缩记录,再准备本轮模型输入。默认同步模式下,需要压缩就先等待摘要,把新摘要和保留原文一起交给 Actor。显式选择后台模式后,当前输入仍放得下时,本轮可以先使用旧摘要与原文;新摘要在后台完成并保存,后续请求再读取。两种模式使用同一份压缩存档,但不在同一个时刻采用新结果。

举例:前面几十条聊天交代了“莉娅借给用户铜钥匙,约定天黑前归还”;最近四条原文仍在讨论城门。用户现在说:“我回来还钥匙了。”研发需要为 Compact 准备以下输入。示例 ID、文字及窗口数值仅演示各字段含义:

输入 从哪里来、本例交什么 必须满足什么
sourceHistory:真实聊天原文 聊天服务按顺序提供,例如 {id:"m-101",role:"user",content:"我会在天黑前还钥匙。"}、{id:"m-102",role:"assistant",content:"莉娅把铜钥匙交给你。"},再接后面的真实消息 这是消息数组,不是“双方借过钥匙”一句概括。每条保留角色与原文;要持久保存摘要,受覆盖的消息还必须有可跨请求识别的稳定 ID
upcomingQuery:本轮问题 从这次聊天请求取得 我回来还钥匙了。 必填,供压缩模型判断哪些旧事值得保留;它不能被当成此前已发生的历史事实
roleCard:摘要模型理解的角色资料 应用从角色模板变量整理出 characterName:"莉娅"、scenario:"灰港城门"、角色背景 background 和开场白 welcome 必须提供角色卡对象;名字与场景是该对象的字段,背景/开场白可选。它是实际文字,不是只有 promptId 的数据库引用;应用会合并角色设定、性格、场景等材料
本次新增checkpointWelcome 与 roleIdentityVerified:检查旧摘要所需的角色依据 仓库适配器另传日记替换前的开场白,并确认 Axon 和多语言角色来源均已就绪 前者只用于判断摘要兼容性,不替换本轮要读的最新日记;角色来源未核实,本轮不采用、失效或覆盖旧检查点,也不启动后台压缩
用户、会话和运行方案 登录后端给 userId:"user-42",聊天给 conversationId:"conversation-8",所用 Scenario 给 scenarioId:"rp-demo" 应用用这三个字段查找和保存同一份压缩存档;不能让模型自行选另一个用户或聊天
模型与本轮预算 实际 Actor 配置给 model、contextLimit,本次生成参数给 maxOutputTokens;例如上限 8,192、预留输出 2,048 这些是本次真实预算,不是历史条数。压缩模型的配置由 compactorModelConfigId 另行选择;两种模型的窗口分别检查
render(history, summary?):重新组装正文输入 应用提供函数,把挑选后的历史重新带入同一套角色、记忆与本轮问题模板;使用模板摘要位置时还接收本次摘要 必填。返回实际消息及历史来源标记,才能准确计数。自建适配声明 summaryInPreset 后,必须把第二个参数中的摘要实际渲染进去;固定世界书/状态等材料再由 finalizeRendered 加入最终输入计数
后台专用组装函数 backgroundRenderer 自建适配返回独立的 render 与可选 finalizeRendered;仓库应用已复制模型配置、模板变量及不可压缩资料,继续使用本轮已选的世界书 只在优先后台模式的准入中需要;必须使用后台自己的取消信号,不能继续引用前台会修改的输入或临时重新选择世界书。缺失时本轮不安排异步任务
本次执行控制 后端生成 requestId:"turn-21",传取消 signal,按请求类型决定 checkpointMutationAllowed requestId 是调用追踪号,不是持久消息 ID。允许改检查点也不等于一定能保存,还需历史身份与版本等检查通过

使用本仓库 apps/emochi 聊天服务时,研发在对应的 config/scenarios/<入口名>.json 中加入下文的 compact 设置,接通 Axon、模型配置和计数服务。应用会读取聊天资料、填入上表参数,并在回复前判断是否需要压缩。入口若通过 AGENT_ROUTER_SCENARIOS_JSON 配置,则修改其中的对应对象。

服务在启动时加载这些设置,所以需要重启/重新发布;保存文件不会热更新当前进程。部署的文件目录由 HARNESS_SCENARIOS_DIR 决定,文件入口由 HARNESS_ENABLED_SCENARIOS 选择;同 ID 的 AGENT_ROUTER_SCENARIOS_JSON 是整份覆盖,不能把文件与环境配置当成逐字段叠加。配置何时被读取

自己的聊天后端也可以集成 Compact 源码,在原来的模型输入准备代码中调用它。后端需要提供上表的完整聊天记录、消息组装函数、token 计数、摘要模型和检查点存储,再用返回的缩短消息调用原回复模型。compact:true 并不是任意 Agent 都能识别的通用设置,这些工作需要研发在后端完成。

具体入口是 apps/emochi/memory/compact-runtime.ts 的 RoleplayCompactRuntime.prepare(...)。现成类的构造依赖是 Compact 设置、AxonRpcClient、主摘要模型执行器,以及可选的 Jev 筛选依赖;启用初始化或备用模型时,还要提供对应的 bootstrap / fallback 执行器。apps/emochi/integrations/roleplay-axon-adapter.ts 展示了在模型输入组装处怎样调用它。自建后端若不使用 Axon,必须为计数、检查点读取和版本提交等操作提供等价适配;仅实现上一页的 get_memory / update_memory,还没有满足这里的依赖。运行时构造依赖

应用如何逐项传入 · 运行时完整输入与返回 · 角色资料实际取哪些文字

材料 压缩前 压缩后
角色、规则、本轮输入 按既有模板组装 继续参与本轮;压缩历史不意味着可以删除这些固定材料
较早历史 多条逐字消息,占用较多窗口 例如“用户向莉娅借铜钥匙,承诺天黑前归还;归还尚未在历史中确认”
最近原文 最新的 user/assistant 消息 按配置保留最近若干完整历史组,继续逐字交给模型
已保存摘要 若曾压缩,会读取可继续衔接的检查点 与新候选历史一起参与摘要更新,不能重复把已覆盖的历史加入
提交给 Actor 的东西 一组模型消息 重新渲染后的模型消息,包含摘要和保留原文;通过 token 计数后才继续

本次更新这里的摘要是解释性示例。压缩模型会读取当前用户输入以判断重要性,但“用户说要还钥匙”不能仅因此被叙述成“历史中已经归还”。主线运行时重点校验格式、长度、历史覆盖与版本关系,摘要事实质量仍需验收。开发中的 #305 尝试另外检查遗漏、矛盾和无依据事实;它还不是当前主线的保证。

prepare 返回后,应用把 rendered.messages 发给 Actor,用 promptTokens 和 promptBudget 检查用量。compacted 表示本次是否新生成了摘要;后台任务已安排但本轮继续用旧材料时仍为 false,不能据此判断后台最终是否保存;historyWindowSlid 表示用了摘要或裁剪后的历史,也可能只是沿用旧摘要。projection 另外保留摘要、近期原文 retainedHistory 和可用的检查点版本。后台若也要使用这些材料,需要明确读取该结果;普通 V2 由下文的 contextGovernance 控制。

应用用 rendered.messages 替换原先准备发送的消息数组。如果保留全量历史后再附摘要,旧内容就会重复,窗口也不会减少。聊天服务仍保存原始消息,后续重新压缩或核对覆盖时继续读取这些原文。

何时执行:按窗口预算,而不是固定聊天轮数 #

默认 scheduling:"sync" 按以下顺序处理;后台模式的分流见紧接着的说明。

  1. 开启 Compact 的请求先取得压缩模型配置,并读取检查点。即使请求只带较短的近期历史,也先检查能否接上之前的摘要。
  2. 计算这次可容纳输入的预算:模型上下文上限 − 最大输出预留 − 安全余量。
  3. 把实际角色提示词、历史、旧摘要、最终注入内容组装起来,计数;不能只估算历史字符数。
  4. 超过配置的触发比例时尝试压缩。若旧摘要的覆盖末端即将离开请求携带的历史窗口,也会尝试提前推进检查点。
  5. 选择可压缩的已闭合历史组,排除配置要求保留的最近组,调用压缩模型;再将新摘要和保留原文组装成 Actor 输入,重新计数。
  6. 只有实际输入放得下,才采用这次压缩结果;具备持久化条件时还会在 Actor 生成之前保存检查点。后台模式则在自己的任务完成检查后提交,供后续请求采用。

例如模型窗口假设为 8,192 tokens,输出预留 2,048,安全余量 512,则输入预算是 5,632;触发比例设为 0.8 时,普通长度触发线为 4,505。这组数字只演示计算方法,不是所有场景的默认模型窗口。窗口取自模型配置,输出预算取自本轮实际配置;调大配置不能扩大模型服务自身支持的上限。

输入预算 · 先读取检查点 · 触发及保留历史 · 压缩后重新计数

提前在后台压缩:本轮先回复,后续请求读取新摘要 #

研发在已启用的 compact 对象中设置 scheduling:"async_preferred",并提供 reliability.maxCompactionMs 等明确额度。应用仍先计数、读取旧摘要并核对历史。如果输入超过提前触发线但还没超过硬上限,或者摘要覆盖的末条消息已经进入本次历史的前 16 条位置,就尝试提前安排后台任务;若已进入前 2 条位置,则按紧急情况同步推进。这里数的是本次携带的历史消息,不是聊天轮数。

例如本轮带来的旧历史还放得下,程序可让 Actor 继续用“上次摘要+尚未总结的原文”回复,同时把这批原文、角色资料、本轮问题、模型预算与已读取的存档版本复制给后台。后台独立组装消息、生成摘要、核对覆盖范围并按版本提交。它不会把尚未完成的摘要塞进已经发出的 Actor 请求。用户很快发下一句时,新摘要可能还没保存;那一句仍使用当时实际读到的旧存档。

当前发生了什么 本轮 Actor 用什么 压缩与保存怎样处理
输入仍放得下,后台任务获准 旧摘要和本次未压缩原文 后台按固定输入处理;完成全部检查后才提交新存档
输入仍放得下,但没有可压缩旧组、历史身份/配置/存档不满足保存条件,或没有独立组装函数 当前能放下的原输入 记录不符合后台条件,本轮继续;不会为此强行同步生成摘要
输入仍放得下,但同一记忆链已有任务,或本实例四个位置已满 当前能放下的原输入 不再新建任务,不排队;下次请求重新判断
输入已经超过硬上限,未启用临时裁历史策略 等同步处理后的输入 取消同链旧后台工作,走同步压缩/恢复;不能让超限请求直接发给模型
已存摘要的末端消息即将失去可衔接的锚点,达到紧急推进条件 等同步推进后的输入 优先同步,不采用临时裁历史;避免新请求已无法证明旧摘要接在哪里
后台后来失败、取消、配置改变或存档已被别人更新 已经发出的本轮回复不重跑 本次后台不成为新的有效存档;下一次请求重新读取当前记录并判断

这里的“同一记忆链”按 userId+conversationId+scenarioId 区分。每条链最多一个后台任务,每个应用依赖实例最多四个、不排队;多个服务实例不是共享一个全局四任务额度。取消后,要等实际工作结束才释放位置。后台有独立生命周期,前台回复正常结束或用户取消不会自动撤销已经获准的后台压缩;关停、后台自己的取消或超时仍可能使它失败。

准入、满额与本轮返回 · 任务身份、容量和结果 · 应用复制独立输入

已经超限时,可选先少带旧原文,但不能把省略当成已记住 #

后台模式另有 asyncOverflowPolicy:"trim_history"。它只在输入已超硬上限、模板有历史位置且不需要紧急推进摘要锚点时尝试。程序从可压缩的最早闭合消息组开始试裁,保留旧摘要及受保护的近期组,每次重新组装完整 Actor 输入并计数。试裁使用同一 Compact 总时限和候选次数额度。

本轮确实能放下,而且后台成功接收完整原始快照,才采用这份临时输入;已经有任务时,还必须证明任务的角色/配置、存档版本、全部历史、本轮问题、模型预算和实际 Actor 输入与本次完全相同。只有“同一个会话”不够。试裁放不下、计数失败、时间/候选额度不足、容量满、已有任务被取消或快照不同,都会回到同步处理并取消同链旧任务。

假设旧原文里有“守卫特别讨厌铜铃”,这段还没进入旧摘要,却被临时省略:本轮 Actor 可能看不到它。后台保留完整来源,成功总结并保存后,后续请求才有机会读到新摘要;后台失败则没有这项保证。聊天原文仍在聊天存储中,这条策略只改变本次发给模型的消息,不删除原始聊天,也不会把省略的历史直接标为已总结。

临时裁历史与计数 · 硬超限和紧急锚点分流 · 完整快照相同才承接

保存什么、什么时候保存、下一轮拿什么 #

时机 产物及保存行为
压缩模型刚完成 新摘要暂时只在本次准备过程里,尚未证明最终 Actor 输入放得下
重新计数通过 采用摘要及保留历史。若允许修改检查点、覆盖历史具备持久消息身份、旧版本仍可提交,则 CAS 保存检查点
检查点内容 摘要、覆盖历史的首尾消息 ID 和历史指纹、版本/链路信息,以及模型/模板/计数等审计信息;不是再保存一遍所有聊天正文
本轮 Actor 写正文 同步路径使用已压缩输入,检查点此前已可能保存;后台路径使用本轮准备时的旧材料,不能等待中途换入新摘要。两者都不以用户接受本轮正文作为压缩提交条件
后台提交 后台核对配置及所依据的存档版本未改变,再经过格式、覆盖和最终预算检查提交;不允许丢掉未覆盖历史后假造连续摘要
下一次请求 读取当时已保存的检查点,核对角色/配置投影与历史锚点;可用时读出摘要,再衔接未覆盖的近期原文。后台仍未完成就继续读旧记录
历史删改、重生成或窗口跳跃 无法证明旧摘要能与当前历史衔接时,不应继续当成可靠前缀;由代码失效/重建或降级路径处理

同步压缩成功而保存失败时,本轮仍可能使用内存中的摘要继续回复;以后请求不保证能读回这次摘要。后台开始、摘要已生成与检查点已保存也是三个不同结果;后台失败不会让已经返回的本轮再执行一次同步压缩。需要看本次压缩日志的 persisted 或返回的检查点提交结果,不能把“本轮压缩成功”与“以后一定记住”合成一个状态。

检查点按 用户+会话+Scenario 读取和保存。应用适配器只在 chat、continue、auto_reply 类型允许修改检查点,其他类型不能借这条路径改写旧摘要;这是组装器收到请求后的权限条件,不表示独立 Auto Reply 建议入口一定会执行 Compact。调用方若直接复用运行时,须明确传入 checkpointMutationAllowed。

检查点保存在 Axon 对应服务中。仓库通过 adapters/axon/client.ts 的 roleplay.context_compaction.get 读取、roleplay.context_compaction.compare_and_set 提交,通过 roleplay.context_compaction.invalidate 将旧存档失效。下次请求按同一个用户、会话和 Scenario 查回存档,接着处理尚未覆盖的历史。这个过程不修改 Scenario JSON、世界书条目或聊天正文;Axon 内部数据库表的实现不在本页源码中。检查点读、写与失效接口

程序把可供下次继续使用的压缩存档称为“检查点”,其中用稳定的消息 ID 标记摘要覆盖到哪里。这些 ID 就是“消息锚点”。下面用示例值说明实际字段,省略了完整写入请求还需要的指纹和审计结构:

检查点/投影内容 本例可能是什么 下一轮为什么要它
检查点中的 summary 纯文本模式也存为对象,例如 {canonical:"用户向莉娅借铜钥匙,承诺天黑前归还;尚未确认归还。",interaction:"",open_threads:[]} 读取后,纯文本模式投影为 {format:"plain_text",text:"…摘要原文…"};结构化模式保留事实、互动和未完事项三项,不能把两种格式混用
coverage.first_segment_id / last_segment_id m-101 / m-180 确认摘要描述的是哪段已保存消息,避免把同一段原文与摘要重复提供
source.source_message_id m-180 指向此次摘要覆盖的末条消息;下一请求必须能证明旧摘要与随后原文接得上
coverage.covered_message_count 80 配合首尾 ID 和指纹检查覆盖是否被删改;它不代表存储版本或聊天轮数
检查点返回的 revision / lineage 例如版本 7、摘要链 1 版本用于提交时防止覆盖别人的新记录;链路号用于区分摘要链重建,均不交由模型凭空编造
projection.retainedHistory m-181 起仍被保留的 user/assistant 原文 这部分仍以聊天消息交给 Actor;不是把全量原文再次写入检查点

例如下次聊天携带的正式消息能接上 m-180,且角色/配置及内容检查都通过,应用才可采用这份旧摘要,再带上 m-181 之后的原文和新问题。若业务每次把旧消息换一批随机 ID,就不能靠“内容看起来差不多”承诺跨轮衔接;没有持久 ID 的请求可有本次临时分组,但不具备相同的检查点保存条件。selected_turns 用 user 开始、已有 assistant 回应的消息组识别可压缩旧对话;使用 explicit_groups 则由业务给真实的 canonicalGroupId,分组必须连续、不能交错。

消息分组与临时身份 · 检查点实际保存字段 · 纯文本的存储转换 · 读回后的输出格式 · 最终结果结构

本次更新读取检查点后,程序先检查格式版本、角色/配置的语义指纹、摘要大小和压缩协议。覆盖的首尾消息都还在本次历史中时,还会检查条数和内容指纹;至少要找到覆盖末端,才能将摘要与后续原文接上。读取失败、角色来源或配置无法核实、格式未知时,本次不继续写这个检查点。若确认角色资料、配置或历史已变,且请求允许修改,程序先按版本将旧记录失效,再考虑重建。日记更新本身不再算作角色变化,具体区别如下。

保存前提及覆盖信息 · 版本提交 · 本轮返回的投影

请求身份与修改权限 · 读回、校验与失效

本次新增日记变了,旧历史摘要还能不能接着用 #

本次新增例如旧日记是“用户答应归还钥匙”,新日记变为“用户已经归还钥匙”。角色仍然是同一个守卫,之前保存的长聊摘要也仍有用。旧接法会把日记填进 welcome,再用这个字段判断角色是否变化,因而可能把日记更新误当成角色变更,作废旧摘要。10 月 14 日合入的 #302 把这两个用途拆开:本轮模型继续读最新日记;检查摘要时使用作者原来的开场白或业务显式提供的覆盖值。

本次与上次相比 旧摘要怎样处理 本轮和后台实际读什么
本次新增只更新日记,或日记暂时缺失 其他兼容性与历史检查通过后,仍可复用旧摘要 Actor 与压缩模型使用本轮实际准备的日记/角色材料,不能为了复用而强行保留旧日记
本次新增作者开场白、角色背景、压缩配置或已覆盖历史真的改变 仍按原规则判定不兼容,符合权限时失效/重建 采用已确认的新资料,不能把所有变化都豁免
本次新增角色来源暂时没核实 不采用、不失效、不覆盖旧检查点,不启动后台压缩;来源恢复后仍可核对并复用旧记录 本轮新生成的临时结果也不能凭此写成持久摘要
本次新增日记变了,但上轮后台压缩还没结束 两轮摘要可以属于同一条链,但后台任务的输入已经不同 不把旧任务视为相同输入。trim_history 的承接检查不通过时转同步恢复,使用新日记
本次新增日记替换、角色来源与后台快照的具体字段含 4 处更新

本次新增只有启用 Compact 时,适配器才临时向 Axon buildSetVars 传 enableSummary:false,先取得日记替换前的 welcome;共享请求本身不改。接着在本地恢复原日记行为:调用方没有关闭 summary、没有显式 extra welcome,且日记按同样规则去除空白后非空,才用日记替换本轮 welcome。模板、Actor、记忆本地变量和来源 Hook 的既有覆盖顺序保留,显式空 welcome 也有效。

本次新增适配器把稳定的 checkpointWelcome 和实际生成用的 roleCard.welcome 分别传给 Compact。摘要指纹使用前者;自建旧调用者不传前者时仍沿用旧算法,不能只更新运行时就期待所有自建接法自动修复。roleIdentityVerified 由 built.sources_ready && i18nCharacterCard.sourcesReady 得到;为 false 时禁止使用不可靠的角色依据改写检查点。

本次新增后台任务匹配还包含完整 input.roleCard、历史、问题、模型预算、当前存档版本及实际 Actor 消息。持久摘要的身份相同,不代表这些本轮输入相同。最终 Actor 预算、允许写入的请求类型、持久消息身份和 CAS 版本检查均保持不变。

日记替换与覆盖顺序 · 摘要角色指纹 · 未核实来源的处理 · 后台输入匹配

本次新增开发分支 #305:检查新摘要有没有漏掉或改错事实 #

本次新增例如旧摘要记着“用户答应明天归还钥匙”,新摘要却写成“用户已经归还”,就把承诺写成了完成。这个候选在摘要生成后,另外请 Jev 或 Luna 对照旧摘要、此次覆盖的完整聊天原文和角色背景,检查重要信息是否遗漏、前后是否矛盾、是否增加了没有依据的事实。角色设定只是背景,不能证明故事里的事件已经发生;措辞不同或省略装饰性描写不算错误。

本次新增截至 10 月 19 日 14:51,PR #305 仍未合入,评审状态为 Changes requested,没有部署记录。固定候选为 8d66caa40b321e22f4ba2d0d5e715e40f17f590d。CI 显示通过,但作者的离线结果中,6 份重做摘要共进行了 8 次复核,全部为 uncertain,没有明确 pass;这轮巡检未复现这些实验,不能据此宣布摘要质量已经提升。

配置模式 何时检查与处理 是否改变本次摘要
本次新增不配置,或 off 不增加检查调用 沿用既有压缩流程
本次新增shadow 对符合条件的新候选做检查,记录结果 即使指出问题也不重做,不要求先通过检查才保存
本次新增repair 首次明确判出问题,且判断概率达到门槛时,用备用压缩模型重新总结一次 新结果必须放进 Actor 完整预算,并在第二次检查得到明确 pass 才采用;否则拒绝这份修复,进入原有失败恢复

本次新增它只检查“已有旧摘要、正在做增量更新、最终由主摘要模型产生、没有重建摘要链、Actor 预算已通过”的候选。首次总结、已有 fallback 产物和超预算候选都跳过。第一次检查超时、不可用、证据太大或不确定时,记录原因后仍沿用原候选流程;这与“所有摘要必须审核通过”有区别。

本次新增修复从旧摘要+此次要覆盖的全部原始消息重新生成,不拿错误候选做局部补词,也不为凑预算截掉证据。最多重做一次、检查两次,共用原 Compact 的模型调用次数、候选次数和总时限。修复或二次检查失败时,不保存那份修复结果;后台同样要完成检查后才能进入版本提交。

本次新增候选配置、结果字段及尚未解决的问题含 9 处更新

本次新增以下字段放在候选版本的 compact.summaryAudit 中,不能复制进不认识它的主线配置。非 off 模式要求已经设置 executionPolicy:"bounded_recent"、profile:"configurable-v2"、outputFormat:"plain_text" 和 reliability;repair 还需要配置 fallback Compactor。

字段 值与作用
本次新增mode off/shadow/repair;整个对象省略时不启用
本次新增provider、model 选择 jev 或 luna 及对应决策模型路由;这里选择检查模型,不替换原摘要模型
本次新增timeoutMs 默认 5,000 ms,范围 1–30,000;单次检查时限信号
本次新增maxInputBytes 默认 80,000 bytes,范围 1,024–100,000;检查证据与问题的序列化大小门槛,超过则不调用
本次新增minDecisionProbability 默认 0.85,范围 0.5–1;明确 issue 或 pass 要达到的概率门槛,低于门槛按不确定处理

本次新增诊断记录 summaryAudit 中的 checks、repairCalls、repairValid、repairAdopted 和 repairFailure。checked 表示执行过检查,repairValid 只说明新摘要格式有效;只有预算、复核和后续采用均通过,才能认定修复已采用。即使采用成功,也还要分别看检查点保存结果和下一轮实际读回。

本次新增当前评审要求继续处理三处已被源码支持的边界:超时仅向依赖传 AbortSignal,无法保证不响应取消的调用会结束;Luna 实际请求会再次 JSON 编码,预检 bytes 不等于最终发送 bytes;离线 telemetry 使用特殊场景键时可能访问未初始化对象。另有文档矛盾的修改请求,本轮没有全面定位。它们不能被一项 CI 通过或作者实验记录替代。

候选配置与三项检查 · 完整证据重做与预算 · 触发、二审与采用 · 作者离线结果

怎样确认是排了任务、生成了摘要,还是已经保存 #

后台日志 roleplay_compact_background 使用独立任务 ID,关联原请求与压缩运行 ID。scheduled / started 只表示已安排/已开始;committed 才对应提交成功或写超时后读回确认。conflict 是版本冲突,unknown 是写入结果仍不确定,uncommitted / failed / superseded 则需要查看具体原因。后续请求是否真正采用,还要看它读回的存档版本和历史衔接检查。

Compact 另记录初始输入、摘要后输入与恢复阶段的预算,并可采集相应材料快照,帮助定位到底是角色、历史还是摘要占满窗口。HARNESS_COMPACT_TRACE_ENABLED 默认 true,但仍需请求有 Kaon trace、telemetry 可用且命中采样;并非默认所有聊天正文都上传。单快照上限 512 KiB,整次最多 2 MiB、12 个快照、256 块;被限额省略会带 omitted 原因。完整快照清单提供块数、长度和 hash,需所有块一致才可还原;complete 表示交给 exporter,不证明远端已经收到。

Actor 前缀观测还会在符合条件的相邻成功调用之间比较最终提供方请求的文本前缀,并关联 TTFT、token 用量与 Compact 阶段。它给的是文本相同前缀范围,不是模型服务的 GPU KV/cache 命中证明;重试、续写、多模态、同轮或并发重叠等不符合比较条件的请求需查看排除原因。

后台结果事件 · 快照开关、限额与完整性 · 文本前缀与耗时观测

接入和配置:实际字段放在哪里 #

聊天入口的 JSON 决定何时压缩、保留多少原文;compactorModelConfigId 指向的模型配置及 PromptManager 决定用哪个模型、怎样总结。Actor 自身的窗口则来自实际模型配置中的 context_limit 等预算输入。这几项分别生效,调整摘要长度时仍需核对它们。

以下保留 compact-automemory-v0-native.json 在原固定基线中的 Compact 配置例子。它展示基础字段,后台调度和角色卡兜底需要再按下表显式加入;研发需先在所连接的 Axon 中创建或确认摘要模型配置,再把它的 ID 填入 compactorModelConfigId;应用按这个 ID 读取实际模型和提示词。该场景样例并非普通 V2 的统一默认值,也不是打开整个记忆系统的开关。

{
  "compact": {
    "enabled": true,
    "boundaryMode": "selected_turns",
    "compactorModelConfigId": "RP-Harness-Compact-AutoMemory-v0-Native",
    "triggerRatio": 0.8,
    "keepLastCanonicalGroups": 2,
    "checkpointMutationTimeoutMs": 5000,
    "safetyMarginTokens": 512,
    "maxSummaryTokens": 700,
    "reliability": {
      "version": "v1.1",
      "minGenerationTokens": 256,
      "maxCandidateAttempts": 24,
      "maxModelCalls": 2,
      "maxCompactionMs": 120000
    },
    "profile": "configurable-v2",
    "inputProtocol": "dream_text_v0",
    "outputFormat": "plain_text",
    "lengthPolicy": "accept_bounded",
    "executionPolicy": "bounded_recent"
  }
}
配置 控制什么 修改后的实际影响
enabled 是否启用整条压缩准备链 未配置或关闭不等于模型窗口无限,也不会自动有持久摘要
scheduling 省略或 sync 为同步;async_preferred 为优先后台 后台模式必须提供 reliability,实际接入需有后台运行器及独立的消息组装函数;缺少运行器是配置错误
asyncOverflowPolicy 后台模式下省略或 sync 为硬超限同步;可选 trim_history 仅能与 async_preferred 配合;试裁和后台承接都通过才让本轮先回复
rolePromptFallback 可选的角色卡临时压缩配置 三字段为 modelConfigId / timeoutMs / maxOutputTokens;下面说明允许范围及失败处理
boundaryMode selected_turns 从所选消息推导完整轮次;explicit_groups 使用显式历史分组 决定哪些历史能作为一个整体压缩;身份/边界不正确会影响安全覆盖与持久化
triggerRatio 长度触发比例,必须大于 0 且小于 1 越小越早尝试;不是后台每隔多少轮执行
keepLastCanonicalGroups 至少保留多少近期历史组,0–100 不是字符数。设为 0 要用 configurable-v2
safetyMarginTokens 输入预算中额外留的空间 增大会减少给输入的预算;不能扩大模型窗口
maxSummaryTokens 摘要最终长度上限 摘要还需和其他材料合起来放得下
compactorModelConfigId 摘要使用的模型和提示词配置 与 Actor 模型是两个岗位;内容提炼规则由该配置提供
profile、inputProtocol、outputFormat、lengthPolicy 压缩请求和输出的协议 当前属于 Scenario 的 compact 配置,不能随意塞到 ModelConfig 当运行开关
executionPolicy: bounded_recent 限定近期候选的处理和降级方式 需要显式可靠性配置;可能放弃未覆盖历史,不承诺全历史永久保存
boundarySearch binary、measured 或 cumulative;未填沿用 binary,显式设置必须同时采用 bounded_recent 改变怎样寻找能装下的连续近期区间;cumulative 已合入但现有配置未开启,最终仍须完整计数
checkpointMutationTimeoutMs 检查点失效/写入操作的超时;未配置时已有 2,000 毫秒默认值,可显式设 1,000–10,000 毫秒 显式设置后,写入超时会做一次有界读回确认;重建时失效旧检查点与写新检查点分别使用该时限,避免把不确定写入盲目重放

compact.contentPolicy 已被明确拒绝;代码要求移除旧字段,通过压缩用 PromptManager/Preset 表达内容提炼策略。本轮问题始终进入压缩材料。普通 V2 同时启用 Compact 时还需要 contextGovernance,其中 enforce 才让后台采用受控的压缩投影;shadow 是观测对照。Sumi 配置当前不允许这个 Compact 开关。

摘要生成失败后,程序先看原输入能否放下;能放下就继续使用,放不下则可能裁掉旧的完整对话组并重新计数,仍超窗才报错。可用摘要保存失败时,本轮仍可能继续回复,但下一轮读不到这次新摘要。因此验收还需要核对实际使用的历史和检查点保存结果。

真实配置样例 · 字段校验 · 协议支持范围 · 旧字段处理

协议、可靠性预算与失败行为
  • generic-json-v1 与 configurable-v2 是当前支持的 profile。只有 configurable-v2 接受自选输入/输出协议,且必须显式提供 reliability。
  • 输入协议支持 harness_json_v1、dream_text_v0、automemory_recursive_v1;输出支持 structured_json、plain_text。
  • 结构化摘要包含 canonical(可延续事实)、interaction(互动关系)、open_threads(未完事项);纯文本投影为 {format:"plain_text",text:...}。不是所有输出格式都返回同一业务对象。
  • lengthPolicy 默认 reject;accept_bounded 仅允许纯文本。无论采用哪一种,最终还要通过摘要及 Actor 的总预算检查。
  • maxCandidateAttempts 限制尝试候选,maxModelCalls 限制真正发给压缩模型的调用,maxCompactionMs 限制候选压缩阶段的时长。它不是整轮请求时限:最终 Actor 输入计数及检查点保存另按请求/存储时限执行。候选次数不等于付费模型次数。
  • 可选递归切片 recursive.segmentContentTokens 需要 configurable-v2 与 automemory_recursive_v1;中间摘要不逐片保存成最终检查点,整个结果通过后再提交。
  • 模型出错但原输入仍在窗口内时,可以沿用已有输入;否则逐步裁掉可移除的旧完整组,再计数。bounded_recent 裁掉未覆盖历史、破坏旧摘要连接时,也会放弃该次旧摘要。仍超窗则返回上下文溢出错误。
  • 配了检查点独立超时时,写超时后最多用 2 秒读回,核对版本、链路及完整提交内容;匹配才认定已保存。版本冲突不通过覆盖来“强行成功”。

输出投影与格式 · 可靠性策略 · 保存失败与确认 · 历史裁剪降级

新摘要生成后还超限,程序先尝试保住什么 #

bounded_recent 路径在调用摘要模型之前,先把一个非空摘要占位放进真实 Actor 模板,激活模板中“有摘要才显示”的提示,再额外预留 maxSummaryTokens。如果“角色等固定材料+最近原文+摘要预留”放不下,程序会扩大需要总结的旧历史范围。这个阶段只是规划:摘要模型和 Actor 的 tokenizer 可能不同,真实输出仍必须重新计数。

如果真实摘要生成后仍超限,程序先保留这份已经成功生成的摘要,再寻找一段可连续衔接的额外闭合历史,用“刚生成的摘要+这些原文”继续总结,减少 Actor 直接携带的历史。额外原文必须真的经过总结,才能推进覆盖范围;不能只把它删除,再声称记忆已经包含了它。最后通过完整输入计数和存储检查才提交一次,中间结果不逐阶段提交。

没有额外闭合组、已经使用过备用摘要模型、剩余调用/时间/候选额度不足或新结果仍放不下时,这条恢复会停止。同步路径仍可能进入既有的有损恢复,放弃部分未覆盖历史,必要时放弃无法衔接的旧摘要;因此不能保证所有情况下记忆都不会丢。后台路径不允许靠丢弃未覆盖前缀或重置摘要链来形成一份看似连续的存档。

生成前为摘要预留空间 · 保留成功摘要后继续总结 · 后台覆盖保护

角色卡本身占满窗口时,可以临时压短本轮角色定义 #

有时长的不是聊天,而是“角色设定+性格+场景”本身。普通历史处理仍无法让 Actor 输入放下时,显式配置的 compact.rolePromptFallback 可以调用另一个模型,压短本次请求使用的角色定义。它只替换这次已经渲染的模型消息;不会改角色卡原件、用户 Persona、聊天原文或已保存的摘要,也不会创建新的历史覆盖或检查点。

研发把以下对象加入已可工作的 compact 配置。your-role-card-compressor 要换成 Axon 中真实存在、使用 Kaon Router 的模型配置 ID;数字是接入示例,不是默认开启:

{
  "rolePromptFallback": {
    "modelConfigId": "your-role-card-compressor",
    "timeoutMs": 15000,
    "maxOutputTokens": 1000
  }
}

timeoutMs 必填,范围 1–60,000 毫秒;maxOutputTokens 必填,范围 1–8,192。还需配置 reliability,其总时限不得小于此超时,且至少允许一次模型调用。角色压缩与前面的历史压缩共享总时间、候选次数和模型调用额度;前面已花完额度,就不会额外赠送一次兜底请求。

程序只处理能证明对应到实际 system 消息的直接角色变量:initPrompt、personality、scenario。多字段按严格 JSON 分别返回,再放回各自原位置。personality 前面若拼接了能够精确识别的 systemPrompt 或 userCustomPersona,这些固定前缀留在原处,不交给压缩模型改写。新文字在原模板完成渲染之后替换,其中出现宏语法也不会再执行一遍。

采用前要证明替换位置与原始消息完全一致,先测移除角色正文后的剩余空间,再生成并重新计数完整 Actor 请求。原输入、移除角色后的输入、精简后的输入,每一次都必须取得合格计数;三个来源可以不同。最终输入同时满足“不超过 Actor 输入预算”和“严格小于原输入”才采用。动态/条件宏、写变量的模板、无法证明的 Persona 拼接、字段缺失、错误 JSON、计数不可靠、取消或预算不足都会跳过或拒绝结果,继续原来的失败/恢复处理。计数通过说明这次输入能放下,角色设定是否保真还要通过实际角色测试检查。

配置范围与输出校验 · 角色字段与固定前缀 · 同一预算内生成和采用

多字段支持随 #291 合入本次 main,晚于 SDK 0.6.0 的打包提交 5e7c191;不要把仓库当前应用源码与已发布 SDK 包当成同一个交付物。

10 月 12 日修复了哪些误拦,哪些检查仍然保留 #

例如角色卡原文很长,模型服务的原生计数暂时不可用,但本地已有经过确认的计数规则;压短后又能取得原生计数。此前程序要求前后计数来源和元数据完全相同,会把这种情况一起拒绝。#295 改为逐次检查计数是否合格,让符合条件的角色卡可以继续尝试精简。

另一处发生在角色精简模型开始生成之前。以前它也必须取得原生或已验证的本地计数;现在,这一步允许使用元数据完整、明确标为“尚未验证”的本地估算,先判断这次精简请求有没有尝试空间。估算的输入加上输出额度和 256 token 余量仍不能超出该模型的窗口,计数失败、估算已超窗或模型服务拒绝时都会停止。这个例外只用于精简模型自己的输入预检;它不能批准后面真正发给 Actor 的请求。

要检查的材料 现在接受什么 不通过时怎样处理
原 Actor 完整输入、临时移除角色后的输入、精简后重新组装的完整输入 每次分别接受 provider_native,或元数据完整且质量为 exact / compatible 的 local_profile;允许前后切换来源 not_validated、旧 token.count 或不合格证据不能放行角色兜底
发给角色精简模型的专用请求 除上述计数外,仅此处允许元数据完整的 not_validated 本地估算;保留原质量标签 输入+有效输出上限+256 超窗,或计数/生成失败,停止本次精简
精简结果放回原位置后的 Actor 请求 重新对全部消息严格计数,必须不超过 contextLimit − maxOutputTokens − safetyMarginTokens,且小于原输入 不能仅凭“角色文字看起来短了”继续回复;超限或没有变短仍按原失败路径结束

一次恢复最多调用一次角色精简模型,继续共用 Compact 的时间、候选计数和模型调用额度,不增加角色重试。成功只替换本次请求里的角色字段,返回 compacted:false;不修改角色卡,不新写摘要检查点,也不把本轮尚未发生的事记成历史。用户取消或处理超时后,迟到结果不能再被采用。

研发可以从 rolePrompt 日志的 originalCountSource / withoutRoleCountSource / finalCountSource 看出三次 Actor 计数分别来自哪里,inputCount 保留精简模型预检的完整计数证据。前后来源不一致时,程序不会把两种方法的差值统计为精确的 token 节省量。该修复已合主线,尚未核实生产入口是否启用、计数规则是否齐备及真实角色的效果。

每次计数的合格条件 · 只有精简模型预检允许估算 · 完整 Actor 重新计数与采用 · 计数来源诊断

可以分别选择第一次总结、后续更新和失败兜底的模型 #

假设一段聊天已经有 100 条历史,但还没有摘要。研发可以让一个模型先总结这批历史;以后每多出一批需要压缩的聊天,换另一个模型更新已有摘要。若后者迟迟不返回,或者在剩余额度内无法处理全部待压历史,程序可以改用配置好的备用模型接着完成。这是 #231 已合入 main 的 Hybrid Compact,未配置时继续使用原来的单模型方式。

本次读到什么 程序选择谁 实际交给它什么
已确认没有摘要(missing),或确认投影改变/历史无法接续(projection_changed/history_unproven)需要重建 配置了 bootstrap 就用初始化模型,否则仍用主模型 本次能取得的待压历史、角色和当前问题等原有材料;不能恢复后端没传来的聊天。读取失败等状态未明情况不按正常初始化处理
已有有效摘要,且后续历史能够接上 compactorModelConfigId 指定的主模型 旧摘要和本次待处理历史;可按 Jev 设置先筛选候选
主模型规划不能覆盖全部待压材料、生成超时,或用完为它分配的处理时间 符合剩余时间、调用和输入预算时,切换一次 fallback 最后一份成功的中间摘要,加失败阶段及余下阶段的筛选前原文;已完成阶段不重跑,近期直接留给 Actor 的原文不塞进兜底输入
用户取消、整体超时、没有剩余调用额度,或兜底输入仍放不下 停止或走原有失败处理 不额外申请新额度,也不偷偷删去兜底材料再宣称完整接管

例如主模型已经完成第一批历史、第二批超时,备用模型接收“第一批得到的摘要+第二批及以后的原文”。超时主模型被取消,迟到的结果不能再覆盖备用模型结果。全部处理完成、最终 Actor 输入计数通过且允许保存时,程序才提交一次检查点;中间摘要不逐份落库。下一轮仍从主模型的增量路径开始,并非永久改用备用模型。运行与接管 · 兜底预算及原文

研发填写的字段、共享预算和运行结果

字段放在聊天入口 JSON 的顶层 compact 对象内:compact.compactorModelConfigId 是主模型,compact.bootstrap 与 compact.fallback 是另外两个可选角色。没有一个供业务填写的 memory.compact.routing 开关。

字段 填什么、有什么约束
主配置 executionPolicy/profile/outputFormat 必须分别为 bounded_recent、configurable-v2、plain_text;显式提供 reliability.version:"v1.1"
bootstrap.modelConfigId / fallback.modelConfigId Axon 中实际存在的模型配置 ID,各自提供模型、提示词和窗口。未配置整个 bootstrap 或 fallback 对象时,不启用对应角色;一旦配置了对象,ID 就必须非空,缺失会报错
每个角色的 profile/inputProtocol/outputFormat/lengthPolicy configurable-v2;输入协议从 harness_json_v1、dream_text_v0、automemory_recursive_v1 选择;输出为 plain_text;长度策略为 reject 或 accept_bounded,默认 reject
recursive.segmentContentTokens 只用于该角色选择递归协议时;正整数,提供递归对象但省略该值时默认 16000
fallback.primaryAttemptTimeoutMs 正整数,从主模型真正开始生成计时,不含前面的 Jev 和计数;不得大于总压缩时限
fallback.reserveMs 为兜底预留的处理时间,正整数且小于总压缩时限;共用 maxCompactionMs,切换不重新计时
reliability.maxModelCalls 启用兜底至少为 2;为兜底保留一次调用。已花费的调用、候选次数和时间都不清零
jev.historyFilter.scope:"incremental_only" 只在已有有效摘要的增量路径筛选。只要配置了 bootstrap 或 fallback,非增量阶段就跳过 Jev,即使填写 all_compactions 或 bootstrap_only 也如此;未配置 Hybrid 的单模型路径仍按这三个 scope 各自的规则运行

一套完整 JSON 示例和模型配置要求见仓内 Hybrid 示例。其中 20 秒主模型时限、30 秒兜底预留、120 秒总时限都是示例值,不是默认生效值。服务准备就绪前会核实已配置角色;需要先准备真实的 ModelConfig 和提示词,再启用对应聊天入口。字段校验

每次处理会记录 compact_run_id,区分 bootstrap/primary/fallback 的调用次数、回退原因、备用模型有没有返回有效结果、最终有没有采用,以及 persisted 保存结果。备用模型返回有效摘要、Actor 用上摘要、检查点成功保存,是三个不同结果。primary_timeout、primary_plan_budget、primary_time_budget 分别表示生成超时、规划额度不足和主路径时间耗尽。没有证据的用量保持未知,不能按零费用统计。诊断初始化与最终结果

这套配置和实现已在主干,巡检记录了定向工程测试;尚未验证生产聊天的模型切换质量、事实保留与实际延迟。仓内 production 目录中存在两份原生 Compact 覆盖文件,但它们本身没有配置 bootstrap/fallback,不能据此认定生产已经开启 Hybrid。

摘要可以放进回复模型提示词中指定的位置 #

之前没有声明摘要位置的 Actor 提示词继续沿用旧注入方式:结构化摘要作为 system 消息,纯文本摘要放进保留的 user 消息。#218 合入后,研发还可以在 Actor 使用的 PromptManager 模板里指定位置,例如把“以前借过钥匙、答应归还”放在角色资料后、聊天历史前。它改变模型在哪里读到摘要,不改变摘要数据库中的内容。

研发在一个启用的 system 模板片段中加入下面的区块,并让实际 Actor ModelConfig 的 promptManagerId 指向这套模板。不是在用户消息里填入这些文字,也不新增 Scenario 开关。

{{#if compactMemory}}
<compact_memory>
{{getvar::compactMemory}}
</compact_memory>
{{/if}}

有摘要时,程序把当前摘要中的 &、<、> 转义,再作为变量传入;无摘要或本次放弃摘要时传空字符串。getter 必须只出现一次、属于 system,不能放入由欢迎语、当前问题或用户记忆这些特殊变量控制的模板条目,也不能用 setvar/addvar/incvar/decvar 修改它。上面“有摘要才显示”的条件可用;如果其他条件把已经存在的摘要藏掉,实际渲染检查会报错。

程序先渲染这一份模板,再做原有 suffix、Agentic 和世界书处理,最后对完整 Actor 输入计数。配置不合法或实际没有渲染出当前摘要时,终止本轮并不提交新检查点;不会把配置错误当作压缩失败,偷偷丢掉历史继续回答。有声明的位置后不再重复执行旧摘要注入,避免摘要出现两遍。位置与变量检查 · 实际渲染

这项代码已合入主干。仓内 A/B 材料属于实验配置准备,尚不能据此认定线上已经切换或记忆质量已经改善。

新增累计计数搜索:减少寻找历史边界的重复计数 #

旧聊天太多时,Compact 要先找出一段能放进摘要模型的连续近期历史。累计计数搜索减少了寻找起点时对大段重叠文字的重复计数。它在已经需要压缩、且采用 bounded_recent 时才运行;哪些剧情重要仍由原有摘要/筛选流程判断,Compact 的触发时机也保持不变。

例如原候选有几十组旧聊天,完整请求计数显示超过压缩模型窗口。程序仍按完整对话组寻找近期连续范围,再交给摘要模型;累计搜索只是改变寻找这个起点的办法。它可能跳到比原办法更靠后的起点,少带一些历史、留出更多预算空隙,所以“最终放得下”不等于“已找出保留最多历史的最优边界”。

boundarySearch 怎样找边界 当前状态与结果边界
未填或 binary 二分选择候选,每次完整计数判断能否放下 默认行为
measured 用已实测的预算占用比例指导下一次探测,并保持搜索范围约束 #198 已合入;在原有单调性假设下寻找与 binary 相同的首个可用起点
cumulative 先依据完整计数压力和组的字符量跳到候选;临近边界仍超限时,仅累计待移除完整组的片段 token,随后再次完整计数 #207 已合入;找到已验证可用的近期后缀即可返回,不保证与其他算法选择同样的历史

开启后,每一步拿什么、产出什么 #

  1. 程序继续使用已经选出的完整历史组,同时带上旧摘要、角色材料、本轮问题、压缩模型配置、摘要预留和可靠性预算。近期原文仍按原配置保留。
  2. 程序先对完整候选计数。已经能放下就直接继续;需要裁选时,用实际占用比例确定下一次探测位置,字符量仅辅助定位,最终是否可用仍由完整计数决定。
  3. 临近边界且仍略微超限时,程序只计算待移除的完整组。JSON 协议按真实消息片段渲染,文本协议保留 user:/assistant: 标记,一组内容先连成字符串再计数。已有 Jev 筛选结果时按该结果计算;需要恢复完整来源时仍按原规则处理,无需逐条扫描全部历史。
  4. 找到区间后,每个采用的候选仍执行完整 countInput,计入角色、旧摘要、问题、模板、摘要预留和安全余量;递归模式还检查每段正文容量。片段 token 之和不能保证是完整请求用量的上界。
  5. 摘要模型按计划生成后,程序检查格式和长度,重新组装并计数 Actor 的全部输入。满足持久化条件才在回复前 CAS 保存摘要、原始覆盖和指纹。片段计数缓存仅供本次计算,下轮仍读取正式检查点。

配置和约束 · 片段与完整输入渲染 · 完整检查与算法选择 · 累计定位算法 · 最终 Actor 输入及保存条件

接入片段、计数降级、诊断与实验范围

在已有可工作的 Scenario.compact 中加入以下两字段,同时保留摘要模型、协议和显式 reliability。这份片段只调整边界搜索,既不替换完整场景,也不启用 Jev:

{
  "executionPolicy": "bounded_recent",
  "boundarySearch": "cumulative"
}

当前 config/、deploy/ 没有开启 cumulative 的实例。接入应先确认 Axon 支持文本计数,并已配置所用模型的本地计数规则(text profile),再采用支持新枚举的 Harness,最后显式改 Scenario;字段存在或镜像构建成功都不能替代有效配置核对。关闭时改回 measured 或 binary;回滚到不识别 cumulative 的旧 Harness 前,先移除或改掉该值。

计数或执行情况 实际处理
文本计数可用 调 token.context_count,载荷为 {model,mode:"text",texts};必须返回 mode=text、source=local_profile 和合法逐项计数。本请求内按精确字符串缓存
批次大小 Counter 支持每批最多 16 个字符串、模型名与文本合计最多 2 MiB UTF-8;当前边界搜索按一完整组调用,不能据批次上限宣称每次都合并 16 组或只发一次下游请求
文本模式失败、profile 不可用或返回不合法 本次 Counter 改用旧 token.count 的逐项 breakdown,后续片段不再反复尝试新模式
新旧片段计数都失败、单片段超限,或自定义 compactor 没有 tokenParts 此次规划改用 measured 搜索;最终完整计数若也不可用,仍可能走既有失败/降级路径
请求取消 立即沿取消路径结束,不借机改算法继续工作
摘要生成失败、最终预算不通过 不能仅凭累计估算或候选计划写入新检查点;沿原有恢复、舍组或失败流程处理,已经消耗的预算不返还

diagnostics.cumulative 记录 fragments/textBatches/legacyBatches、片段计数耗时 precomputeMs、完整检查 fullChecks/fullCountMs、边界微调次数 backtracks 和是否改用 measured 的 measuredFallback。完整检查可能命中已有缓存,RPC 批次数也不是底层 tokenizer 请求总数;性能对比要同时看实际下游请求、提交文本字节、耗时与最终覆盖。摘要是否采用、是否保存继续看原 adoption/persistence,不是看计数成功。

仓库最终版实验用三个既有会话各做三轮交替对照,摘要生成使用冻结响应,检查点只写内存。三组计数阶段中位耗时分别下降 17.5%/23.1%/19.1%;三个案例每轮合计下游请求从 39 降到 35,提交文本字节下降 38.7%,摘要仍覆盖 42/58/34 条消息。实验中 AutoMemory 的新文本 profile 不可用,实际回退到了旧片段计数,因此这些数据反映的是这三个案例的准备开销。新接口在其他模型上的收益、生产 p95、真实摘要遗漏率和实际生成费用仍待验证;早期算法版本的数字需另行对照。

研发用 count-search-replay.ts 重放计数实验时,现在必须同时提供 --cumulative-axon-url,才能用 --legacy-axon-url 指定旧计数回退地址。只填后者会在读取实验数据、创建输出目录或发请求之前报错,避免以为自己测了累计算法,实际却跑成旧算法对照。这是 #211 修正的实验入口校验,不是聊天请求新增参数。参数检查

Counter 和降级 · Axon 文本 RPC · 诊断与回退 · 最终版回放及限制

新增可选步骤:摘要前筛历史,摘要仍由原压缩模型生成 #

Compact 决定需要压缩后,可以先让 Jev 判断哪些候选历史可以省略。程序检查省下的 token,或在显式选择完整计划比较时核对覆盖范围和摘要调用阶段,再决定是否把筛选后的材料交给原摘要模型。Jev 在这里负责分类,不写摘要、不选择角色工具,也不更新 Director 状态;普通 Agent V2 使用 Jev 选择工具是另一处实现。

例如,用户曾说“铜钥匙借给你,天黑前还”。助手的一条长回复分为两段:第一段只反复描写同一片月光;第二段写“我答应天黑前还钥匙”。本轮用户问:“你答应我的事还记得吗?”

时点 程序与模型实际做什么 本轮和下一轮得到什么
本轮回复前,Compact 已触发 保留配置要求的近期完整组,把其他已闭合历史交入筛选;Jev 得到角色背景、旧摘要、本轮问题、近期原文,以及目标与相邻组 分类对象来自本次收到的历史,不去聊天库找回全部旧消息
Jev 返回判断 选用自然段策略时,每段返回 keep/drop/uncertain 和三类分数。承诺段应保留;仅装饰段可能满足省略条件 这是解释性例子,不是对真实模型判断的保证
程序生成投影并检查收益 只按程序切好的原文范围替换为 […],用户消息保持原文;用完整真实请求比较同一来源区间过滤前后的 token 默认至少省 512 token 且达到 10% 才采用;显式 reduce_input_or_stages 还可按完整覆盖或更少摘要阶段采用,详见下文。单个短例子不保证达到门槛
原压缩模型生成摘要 真正采用时,收到保留正文、省略标记与程序提供的说明,例如产出“已承诺天黑前归还铜钥匙”;它读不到被省略段落 摘要与保留近期原文重新进入 Actor 输入,仍需格式、大小和最终窗口检查
摘要与完整输入检查通过后保存 同步路径在回复前提交;异步路径在后台完成后,沿 CAS 保存摘要和完整原始覆盖范围、历史指纹、用量审计 保存后下一轮复用摘要与未覆盖原文。聊天原文没有被修改;被省略内容不会因下一句追问而自动回补

自然段筛选保留用户消息原文,但后续预算处理仍可能舍弃放不下的早期区间。检查点的覆盖记录表示该区间经过了筛选和摘要,并不逐条证明其中的事实都保留在摘要中。自然段筛选与投影 · 最终采用和保存

三种模式和三种筛选策略 #

开关 谁等待、是否改变摘要 当前默认
historyFilter.mode=off 不发 Jev 请求,继续原有压缩 默认;只配置 policy 不会启用
shadow 旁路做分类,真正的压缩仍用原文;不改变摘要输入或检查点,也不生成第二份摘要 每个缓存的应用依赖实例最多两个分类任务,不排队,满额跳过;仍有额外请求和费用
apply 执行压缩的任务等待分类;满足触发、规则与收益门槛才采用,否则在剩余预算内恢复原文规划。任务在前台还是后台由 scheduling 另行决定 需要主动启用并提供 compact.reliability
policyVersion 处理单位和省略条件 保留边界
retention-conservative-v1(默认策略) 每个完整对话组问八题;仅当纯寒暄分数 >=0.95、其余七项均 <=0.1 才成为可省略候选 七项是长期事实、状态变化、承诺更新、纠正、依赖、当前相关性、上下文不足;候选与批次首尾、重要或不确定组的一跳邻居保留。它按整组判断,不具备“所有用户原文永不省略”的段落策略规则
paragraph-memory-experimental-v1(#198 新增实验) 按较新组向较旧组扫描 assistant 原文,以空行分段;去首尾空白后至少 40 个 JavaScript 字符长度单位的段落才参加判断。必须选择 drop、三类分数完整合法且和约等于 1、drop>=0.8 才能省略 用户消息、不足 40 的短段落、未检查、缺失/非法结果和 uncertain 均保留;用 […] 留出省略位置。0.8 是返回分数门槛,不是经过校准的“只有 20% 误删率”
paragraph-memory-experimental-v2(#205 已合入,需显式选择) 仍只检查助手段落;调整保留/省略判断说明,缩批后最多再尝试一次补入更多段落,并重新估算是否放得下 保留 V1 的用户原文、短段落和不确定结果保护;采用后的检查点指纹包含这版规则,修改规则可能需要重建摘要。不能仅凭 V2 名称认定效果全面优于 V1

任何批次失败、超时或单目标也装不下,会放弃本次全部筛选建议;请求取消继续向上传播。达到调用次数上限而没检查到的旧内容保留。分类输入本身也有预算,过大会缩批;不是每段都单独请求一次模型。完整组规则 · 自然段门槛与失败处理 · Shadow 容量

实际接入片段、全部默认参数、计数和回滚

在前文已经可工作的 Scenario.compact 中合入下面字段,保留原有摘要模型、协议、预算和 reliability。这个演示配置先用 shadow 观察自然段策略,会发送真实分类请求,需要 Kaon 地址、鉴权和 Axon 计数服务。它只展示增量字段,不能替换完整 Scenario;当前也没有据此确认生产已启用。

{
  "executionPolicy": "bounded_recent",
  "boundarySearch": "measured",
  "jev": {
    "model": "openrouter/~typesafe/jev-latest",
    "historyFilter": {
      "mode": "shadow",
      "scope": "all_compactions",
      "activation": { "strategy": "min_pending_tokens", "minPendingTokens": 2048 },
      "policyVersion": "paragraph-memory-experimental-v1",
      "adoption": { "goal": "reduce_input", "minSavedInputTokens": 512, "minSavedInputRatio": 0.1 }
    },
    "budget": { "maxInputTokens": 28000, "maxQuestionsPerCall": 128, "maxCalls": 2, "maxTotalMs": 3000 }
  }
}

上例只显式改变模式、策略和搜索方式;数字沿解析器默认值。达到业务质量门槛后,要真正改变摘要输入才设置 mode=apply;这项改动应使用独立 Scenario 做对照,因为改变筛选策略可能使旧摘要的配置校验不再匹配,导致原检查点失效。latest 名称不能冻结背后的权重,可复现实验应选 Router 已支持的稳定版本。

参数 省略时的值 怎样生效
historyFilter.mode / policyVersion off / retention-conservative-v1 模式和策略独立;未知字段/策略报错,即使 mode 为 off 也会校验配置
scope all_compactions 单模型配置下,首次和增量都可分类;bootstrap_only 仅无可用旧摘要时,incremental_only 仅已有有效摘要的增量阶段。启用 Hybrid 时非增量阶段统一跳过 Jev
activation.strategy min_pending_tokens 待压原文至少 2048 token 才分类;只在 Compact 已触发且存在候选之后检查
另两种 activation every_compaction、over_single_call_budget 前者每次实际压缩尝试;后者未过滤完整摘要请求超单次预算才尝试,也检查递归正文上限
minPendingTokens 2048,范围 0–1000000 只允许配 min_pending_tokens;0 有效,不等于每条聊天都触发 Compact
adoption.goal reduce_input 可以仍需多阶段摘要;fit_single_call 额外要求只需一次摘要调用且预算通过;reduce_input_or_stages 只用于 bounded_recent,另比较完整覆盖与阶段数
minSavedInputTokens / minSavedInputRatio 512 / 0.1 token 收益路径要求两项同时达到,分别可设 0–1000000、0–1;reduce_input_or_stages 可另按下述完整计划收益采用。不能把丢弃的旧前缀算成节省
budget.maxInputTokens 28000,范围 1–32000 Jev 的完整 state+questions 请求预算,另受实际解析出的 Jev 模型上下文上限约束
maxQuestionsPerCall 128 组策略范围 8–1024,每组八题,默认最多 16 组/次;段落策略范围 1–1024,每段一题
maxCalls / maxTotalMs 2 / 3000 范围 1–10 次、1–30000ms;apply 模式下查询 Jev 模型配置也消耗此时间,分类还受整个 Compact 时限约束
model 或 modelConfigId 不填时直接用 openrouter/~typesafe/jev-latest,程序按 32000 的模型窗口处理 两者互斥。显式 ModelConfig 必须解析到 Kaon Jev 及合法上下文;它选择分类器,不替换摘要模型

Jev 调用的是原生 Decisions:{model,state,questions}。#205 合入后,分类请求在本地按序列化文本的加权 UTF-8 长度估算,再留出 256 的固定余量;该步骤不再请求远端 token.count。这是决定分类批次大小的估算,不能保证高于模型实际用量。摘要模型和最终 Actor 输入仍使用各自的完整请求计数;有界多阶段收益比较中的未来摘要仍是占位估算,不是已经生成的摘要。当前本地估算入口 · 估算公式

boundarySearch 与 Jev 筛选是独立开关,可以关闭 Jev 后单独选择 binary/measured/cumulative。三者的选择、输入计数与失败回退见本章边界搜索;开启搜索优化不等于开启语义筛选。Jev 配置解析 · 分类模型身份和计数估计

停止采用设置 mode=off。若回滚到不认识新 policy 的旧镜像,应删除新 policy 或改回旧策略;仅设 off 不能绕过未知策略校验。配置变更不会自动启动 A/B 或恢复旧摘要里的缺失事实。

不只比较 token:也可以比较完整覆盖和摘要阶段数 #

显式选择 historyFilter.adoption.goal:"reduce_input_or_stages" 时,程序仍先检查原有 token 节省门槛;没有达到时,再比较同一批候选原文的完整处理计划。如果筛选后的计划没有丢弃候选前缀,而未筛选的计划在剩余额度内无法完整覆盖,可以记录 full_coverage 并采用;两边都能完整覆盖、筛选后需要更少摘要阶段时,可记录 fewer_stages 并采用。筛选后的计划本身已丢前缀,就不能靠这两项理由通过。

这次比较复用同一内容的完整计数证据及正文计数缓存,减少重复计数。它仍要做最终完整 Actor 输入计数,未来阶段的摘要占位也仍是估算。观察时应一起看 adoptionReason、sourcePlannedStages / filteredPlannedStages、sourcePlanFullCoverage 与最终保存结果,而不是只凭 Jev 成功返回就认定节省了费用或没有漏事实。

采用理由与同源计数 · 计数复用 · 完整计划比较

已合入主干:本地估算分类请求长度,以及段落筛选 V2 #

截至 9 月 23 日 08:31 的巡检,PR #205 已合入 main;昨天较早版本中的“尚在分支”状态到此更新。程序在本地估算分类请求长度,减少分类前对远端计数服务的依赖。paragraph-memory-experimental-v2 需要主动选择,Jev 历史筛选默认仍为关闭;已合入不代表所有聊天都切换到了 V2。当前适配代码 · 策略与默认值 · V2 规则与批次调整

本地估算不能保证每次都高于模型的实际用量。例如程序判断一批历史放得下,但 Jev 收到后判定超长,用户可能多等一次被拒绝的请求和后续回退。分类失败时,程序放弃本次省略建议,把未经过筛选的原文交回原有压缩流程;这不等于最终摘要一定保留全部原文,后续仍受摘要窗口和预算限制。估算方法及限制 · 分类失败处理

巡检记录的 186 个请求中没有发生低估,估算比实际用量高约 12.7%–22.84%;这只是有限样本,不能作为所有聊天都安全的保证。段落 V2 的质量实验有改善也有退步,尚不能写成整体升级。后续已核对合入主干的实现,先前 b285ed03 待复核记录不再代表当前状态;生产长聊的事实保留、总耗时和费用效果仍未验收。

保存、故障恢复和仍需验证的语义质量 #

#196 最终合入版修复了一个恢复错误:提供方报告上下文溢出后,程序曾继续使用过滤后的摘要,却把完整原文范围记为已覆盖。现在遇到过滤计划的本地/提供方溢出时,会清除已采用的收益记录,恢复原 source。有界路径从原摘要重新规划整个已选区间,废弃过滤后已生成的前缀,并保留这些已选消息;普通路径恢复当前阶段及后续原文。已经花费的候选次数、模型调用和时间仍计入预算,剩余额度不足时不写 checkpoint。当前恢复实现 · 普通路径恢复

程序校验通过后,仍可能留下语义遗漏。例如 Jev 返回合法的高分 drop,却错误省略“答应天黑前还钥匙”,程序可能正常生成并保存一个缺少承诺的摘要。格式、预算和 CAS 检查无法发现这类错误;当前尚无 summaryAudit、maxRepairAttempts、生成后事实对账或自动重写恢复。

要核对的结果 现有记录及边界
本轮提出了多少省略建议 CompactDiagnostics.jev 或 roleplay_compact_jev_shadow 中有模式、状态、调用/检查数、分数、耗时和用量;段落策略新增 checkedParagraphs/omittedParagraphs,它的 omittedGroups=0 不表示没筛选
本轮是否真的采用 要看 status=adopted 和实际节省诊断。分类建议数量不等于最终采用数,shadow 也没有真实摘要节省结果
能否事后还原省略正文 普通诊断和 checkpoint 仍不是完整省略清单。新 jev_filter 快照可记录各阶段原始消息及筛选投影,但要求命中采样且所有快照块完整;受限额省略、未采样或远端缺块时无法据此还原。需要逐轮完整审计的业务仍须自行实现存储和保留规则
下一轮是否复用同一规则 apply 的语义指纹含配置、模型身份与 renderer;完整组版本后缀 +jev-retention-v1,自然段版本后缀 +jev-paragraph-memory-experimental-v1。off/shadow 沿用未采用筛选时的摘要配置指纹;变策略可能使旧摘要失效并重新压缩
暂时无法查到用于核对旧摘要的模型/提示词配置 不失效或覆盖旧 checkpoint;可退回原文压缩供本轮使用,但不持久化这次结果。取消、Regenerate 只读、CAS 冲突和超时确认沿原机制

启用 apply 的业务验收应覆盖承诺/取消、纠正、伏笔、状态变化、短答依赖与情绪连续性;同时比较包含分类成本的总耗时、费用和事实保留,并确定可追溯审计与回滚阈值。Shadow 只证明旁路分类,不能代替实际摘要和多轮继续聊天的质量验证。观测字段 · 身份与保存保护

9 月 22 日早间巡检记录了 #196 最终版定向测试、受控旧/新复现和专用 Staging 21/21;随后 #198 相关七个文件 109/109、远端 main Actions 成功。下午固定 ccaaa46e 的报告另记录 cumulative 22/22、suffix search 10/10、paragraph runtime 12/12 定向检查通过。这些是已完成巡检的工程验证记录,本次文档更新未重跑测试或调用真实模型。新策略是否在现网启用,以及质量、延迟、费用有无净收益,还需生产配置和实际业务结果确认。

原子能力 / 公共函数

上下文组装:把资料放到模型真正看得见的位置

10/19 更新 · 本章 2 处从第一处开始看 →

用户输入“我递出铜钥匙”。守卫既需要记得“用户昨天答应还钥匙”,也要遵守“进入禁区需要手令”的规则。聊天后端先取回记忆和世界书条目,再把这些文字与角色设定、聊天历史、本轮输入一起发给回复模型。模型读的是这组最终消息。

SDK 提供 placeContextBlocks 和 getPlacementCapabilities 来安排这些文字的位置。它们接收已有消息和资料块,返回新消息数组及放置记录。资料查询、模型调用和长期保存仍由聊天后端完成。

已有聊天后端可以在创建模型请求 messages 的地方调用 placeContextBlocks:等世界书和记忆查询完成,用返回的新数组继续原来的模型调用、流式显示和回复保存。这是后端直接执行的函数,无需交给模型选工具,也不要求配置 Scenario。

在回复的哪一步 谁做什么 交到下一步的实际结果
1. 取得材料 业务后端读取当前角色、按顺序取聊天;按启用的接法召回记忆、调用世界书选择 例如角色文字、三条历史消息、记忆对象/文字、本轮选中的手令规则。各服务的原始返回不必相同
2. 决定给哪个模型 研发在调用该模型的代码或提示词模板中指定要用哪些资料、放在何处;程序把取回的对象整理成文字 本例准备给 Actor 的角色文本、记忆文本和规则;是否也给后台模型,需要另为那个调用准备
3. 组装消息 自建 Agent 调用 placeContextBlocks,传基础 messages、位置 layout、待插入 blocks 新 messages 是模型将要读的内容;placements 记录每份资料最后位于第几条消息
4. 计数并生成 后端检查最终输入与输出预留是否放得进模型窗口,再调用模型 Actor 根据实际发送的消息写本轮正文;模型不会凭资料 ID 自己去数据库取原文
5. 后续保存 正文、记忆、世界书状态按各自业务流程保存 本组装器只返回数组,不保存上述任何数据;下轮需再次取材料、重新组装

仓库的 apps/emochi 已经做了这部分工作:integrations/roleplay-axon-adapter.ts 处理角色模板和记忆变量,worldbook/runtime.ts 的 decorate 把选中条目放进消息,普通 V2 还会加入后台保存的状态。使用这套应用时,研发修改对应的记忆/世界书设置和 Actor 提示词即可,重复手动插入会让资料出现两次。单独使用公共 SDK 的后端则需要自行查询资料、整理文字、计数并调用模型。

记忆变量进入角色模板 · 应用内固定状态与世界书装配 · 世界书实际调用公共组装器

Actor 的 Compact 摘要现在也可以在提示词模板里明确放置:研发在一个 system 片段中加入规定的 compactMemory 区块,程序将本次摘要渲染到那里,再处理世界书等材料并检查完整输入预算;没有该区块的旧模板继续沿用旧注入方式。这个位置不由 placeContextBlocks 自动创建,也不能重复手工追加同一摘要。格式、转义、空摘要和渲染失败的处理见指定摘要位置。应用实际渲染分支

这里的“本次摘要”取决于压缩何时完成。默认同步模式先生成、检查新摘要,再把它放进本轮消息;显式 async_preferred 获准时,Actor 先使用这次准备阶段实际读取的旧摘要与原文,后台新结果留给后续请求。即使后台在 Actor 写到一半时保存成功,也不会修改已经发给模型的消息。后台模式的实际返回

本次新增日记和历史摘要还需要分开看。例如,旧摘要已经记下“用户借走铜钥匙”,今天取回的日记更新为“用户答应明晚归还”。10 月 14 日合入的修复会保留仍然适用的旧摘要,同时把新日记交给本次回复和压缩模型;不会再仅因日记文字变化就误判为作者修改了角色。程序另外用作者原始开场白判断摘要属于哪份角色资料;作者实际修改开场白、背景或相关配置时,仍会重新检查旧摘要能否使用。已经在后台运行的压缩也不会中途换成新日记,下一请求需要按自己的输入重新判断。角色原文与本次日记分别准备 · 完整条件与保存规则

本次新增如果记忆服务这次读不回来,研发可以在该聊天入口设置 failurePolicy.memoryRecall:"continue_without_memory",允许程序继续准备回复;缺省仍是 fail_turn,读取失败就停止。普通记忆召回整体抛错时,本轮得到的是空记忆,并不逐个保留已经成功的记忆来源;角色资料、聊天历史和不经过这次召回的其他材料仍按原流程准备。Hinos 另有故障分类,身份、协议等错误不能当成“没有记忆”继续;具体允许范围与回复后的写入规则见记忆故障处理。配置值与默认处理

一次具体调用 #

下面用一段自建 Agent 代码演示。后端已经取回手令条目,并把记忆整理成“用户昨天答应归还铜钥匙;尚未记录归还”。这个例子将两份资料放在角色说明之后,同时保留上一句守卫原话和本轮用户原话;仓库中的其他模板可以采用不同排列。

必须交给组装器的输入 从哪来、实际填什么 条件与含义
messages 模板生成角色 system 消息;聊天服务提供原始 user/assistant 消息 必填数组。role 是消息的用途,content 是模型真正读到的文字;“角色 Prompt”在这里就是 你扮演城门守卫。,不是角色 ID
layout 研发依据插入前的消息数组标记区域 本例 character:{start:0,end:1} 表示只有索引 0 是角色说明。只声明本次需要的位置,不能让组装器猜哪条算角色、哪条算历史
blocks 程序将已经选定的世界书/记忆/工具结果转换为资料块 每块必填唯一 id、position、role、content。id 用于追踪,不会触发读取;order 可省略,默认 0;深度和插槽字段按所选位置提供
createMessage 研发提供消息转换函数,本例直接返回传入对象 必填函数,把新增资料变成后端采用的消息格式;无需 LLM 来完成这个转换

下方 content 填的是后端已经取回的文字。gate-rule 和 key-memory 只是用于追踪资料的名称,SDK 不会根据这些名称发起查询:

import { placeContextBlocks } from '@flowgpt/roleplay-harness';

const result = placeContextBlocks({
  messages: [
    { role: 'system', content: '你扮演城门守卫。' },
    { role: 'assistant', content: '守卫看着你:你回来了。' },
    { role: 'user', content: '我递出铜钥匙。' },
  ],
  layout: { character: { start: 0, end: 1 } },
  blocks: [{
    id: 'gate-rule', position: 'after_character', order: 0,
    role: 'system', content: '进入禁区需要手令;铜钥匙不能替代手令。',
  }, {
    id: 'key-memory', position: 'after_character', order: 1,
    role: 'system', content: '用户昨天答应归还铜钥匙;尚未记录归还。',
  }],
  createMessage: message => message,
});
// 将 result.messages 交给模型,规则和记忆才会参与本轮生成。

函数返回的 messages 如下:

新数组索引 消息角色 模型看到的内容
0 system 你扮演城门守卫。
1 system 进入禁区需要手令;铜钥匙不能替代手令。
2 system 用户昨天答应归还铜钥匙;尚未记录归还。
3 assistant 守卫看着你:你回来了。
4 user 我递出铜钥匙。

函数同时返回两条放置记录:gate-rule → messageIndex:1,key-memory → messageIndex:2,两条都是 position:"after_character"、role:"system"。程序和调试页面用它们核对资料的位置,发给模型的则是上表文字。索引 3 的 assistant 仍是上一句守卫原话。

后端把这个新数组发给 Actor,模型才有材料承接“还钥匙”,并判断钥匙与入城手令的关系。具体台词仍由模型生成。发送前,后端还需确认资料来自获准使用的来源、适用于本轮,并检查总 token 数;用户自由输入要按产品规则处理后,才能放进 system 消息作为规则。

这次插入只影响收到该数组的模型调用,聊天记录和世界书原条目保持原样。下一轮,后端根据新的 query 和记忆返回重新组装;其他模型如果也要用手令规则,需要在它们自己的输入中加入这段文字。

位置、资料块与布局定义 · 组装函数 · 完整组装示例

位置可以改,但需要对应锚点 #

位置 放在哪里 后端必须提供什么
before_character / after_character 角色描述前/后 layout.character 的半开区间
before_examples / after_examples 示例对话前/后 layout.examples
at_depth 真实聊天历史的指定深度 layout.conversation: {messageIndices, emptyIndex};前者是原消息数组中真实历史的有序索引,后者是无历史时的插入点。不要把样例、作者备注或 lore 算成聊天历史
author_note_top / author_note_bottom 作者备注顶部/底部 layout.authorNote 是原消息数组索引;继承该消息的 role
outlet 模板中显式的 {{outlet::name}} 插槽 layout.outlets: {name: 消息索引},block 提供 outlet_name:name;每个对应标记恰好一次。内容嵌进该消息,继承该消息的 role

depth:0 在最后一条真实对话之后,depth:1 在最后一条真实对话之前;深度超过历史条数时放在最早一条真实对话前。order 控制同类放置的顺序,同值再按 ID 排序;相邻区域共享插入点时先遵守区域顺序,不能用一个更小的 order 任意跨越角色/示例区域。没有对应锚点、重复 ID、非法角色或嵌套 outlet 时会报错,不悄悄丢掉已经选择的条目。

getPlacementCapabilities(layout) 只按你声明的布局列出可用位置与 outlet 名称;完整的边界、索引和模板标记校验在 placeContextBlocks 执行。调用方可以用 renderBlock 格式化内容,或用 renderMessages 将独立资料块转换成多条消息;作者备注和 outlet 是嵌入原有消息,不按独立消息的格式转换。

SDK 支持八种位置,应用实际开放哪些位置取决于它提供的布局。世界书选择条目时也要知道这些可用位置,才能返回匹配的结果,详见 世界书。

自建 Agent 在调用函数时设置 layout 和 blocks[].position。仓库应用则把世界书条目的位置与 Scenario 的 worldbook.prompt 配合使用。例如,使用作者备注位置时,研发配置 worldbook.prompt.authorNote 的 role/content/depth;使用 scene_rules 插槽时,配置 worldbook.prompt.outlets.scene_rules,让其中的文字恰好包含一次 {{outlet::scene_rules}},再把条目指向该插槽。应用会根据实际消息和这份配置生成 SDK 所需的 layout,因此无需在 Scenario 中另填同名参数。应用位置设置及校验 · 从实际消息生成布局

资料块若要求 position:"outlet", outlet_name:"scene_rules",而后端没有提供这个位置,组装器就会抛错,不返回新 messages。研发需要补齐插槽配置或调整条目位置。应用中的 decorate 也要求先完成世界书选择;调用顺序反了,会在组装前报错。

分析工具的上下文是另一个入口 #

六类分析工具用 compileContext 生成整条 user message,系统岗位说明由 prompt 提供。这个函数同步整理已有材料,外部查询应在调用工具前完成。普通 V2 的 Actor、Orchestrator、专家和 Director 分别准备自己的输入,Actor 读过的世界书只在它那次调用中生效。

例如要让知识检查工具判断“铜钥匙是否可以代替手令”,后端先取回手令条目,再用创建工具时配置的 compileContext,把本轮问题、条目原文和要检查的事项写成完整文字。工具随后发出两条消息:system 是岗位要求,user 是这份全文。自定义回调会替换默认 user 内容,所需角色和历史也要一并写入;它只影响这个工具,不会修改其他 Agent 的输入。

自定义编译器的职责 · 系统提示和 user 材料的组合

窗口在哪里改,超了怎么办 #

仓库 RP 应用从 Actor 的 ModelConfig.context_limit 读取窗口上限;本次请求经过允许的参数覆盖后已有 runtimeDecision.contextLimit 时,采用这个值,再按实际生成参数预留输出空间。研发可以修改 Axon 中对应 ModelConfig 的 context_limit,或由聊天后端在本次请求的 extensions.turn_context.runtime_decision.context_limit 中提交窗口覆盖值,仍须遵守模型服务支持的上限。资料字符截断和世界书 token 预算则分别限制对应资料的用量。应用预算的实际来源

placeContextBlocks 只安排消息,token 计数在返回之后进行。即使示例中的 5 条消息组装成功,内容太长仍可能超窗。仓库应用可使用 Compact 和相应 contextGovernance;自建 Agent 则在发送前计数,再按产品规则减少材料、压缩历史或停止生成。计数必须包含刚插入的资料。

10 月 9 日主干中的 Compact 还会在有界处理时先为摘要留空间;真实摘要过大时,尝试继续总结额外闭合历史。角色定义本身过长时,显式配置 compact.rolePromptFallback 才可尝试压短本次 initPrompt / personality / scenario,并保留能精确识别的固定前缀。只有完整输入重新计数通过才采用,不修改角色卡原件;这属于应用的恢复处理,placeContextBlocks 本身不会执行。10 月 12 日合入的修复允许精简前后分别使用合格的计数来源,并允许角色压缩模型的输入预检采用带完整元数据的估算;最终 Actor 请求仍必须严格计数、符合预算且比原输入更短,不能仅凭估算放行。具体额度、不能处理的模板和失败分支见 历史压缩。角色定义的请求内兜底

验收时检查最终 messages 和 placements,确认每份规则的消息位置、role、出现次数及接收它的模型,再测试缺少锚点和预算超限时的处理。世界书接口返回条目之后,到模型真正收到条目之前,这几步都需要验证。

原子能力 / 工具与应用接线

图片:独立图片资产、聊天配图与视觉连续性

10/19 更新 · 本章 41 处从第一处开始看 →

给一段描述并取得图片,可以直接使用 generate_image_asset。要让角色先说一段、给其中一段配图,再把图片显示在对应聊天消息里,则需要应用安排正文分段、生成图片描述、保存消息中的待完成图片位置,并等待图片服务回填。本页分别说明这两种用法。

仓库还提供 Sumi 图文应用,由它自己的流程生成正文、描述图片并保存状态。它通过独立路由运行,使用方式见下文;普通 Agent V2 的聊天配图则使用这里介绍的前台工具循环。完整 Agent V2 与 Story 分别有自己的产品页。

先选要复用的能力 #

已有产品只需要图片资产时,可以在自己的后台调用独立工具,再把返回的 URL 保存到消息或道具资料里。需要复用仓库的正文分段、图片位置和视觉状态时,使用仓库聊天服务的业务可以修改配置;保留自己后端的业务则需要集成相应源码,并适配消息读写。

需求 代码提供什么 输入 输出与后续动作
为自己的产品生成一张图片资产 Core Tools /image 的 createImageAssetTool 描述、可选参考图、数量与尺寸;接入者绑定图片模型配置 任务 ID、图片 URL、逐图审核证据;接入者决定保存在哪、展示给谁
为当前角色正文配图 应用内 ImagineSkill、ImageMcpTool 与前台 generate_image 账号 ID、当前 RP 聊天 ID、角色 Prompt 资源 ID、本轮助手消息 ID、要配图的那段正文、图片序号 先保存该消息的 pending 图片位置,再调用图片服务;不是同步返回可展示图片的承诺
后续图片维持人物外貌与场景 prepare_visual_world / commit_visual_world 及仓内视觉状态运行时 角色、此前消息锚点;本轮完成后再提供正文和旧视觉状态 本轮画图的视觉材料,及后续请求可以读取的视觉状态
使用 Sumi 的整套图文生成 apps/sumi 独立路由与应用 Sumi 所需角色、历史、状态和模型配置 该应用自己的正文、图像描述、状态与图片归档流程;不是本页独立工具的默认效果

独立图片工具 · 聊天配图模块 · Sumi 独立入口

独立图片资产:怎样接入 #

例如运营输入“灰港城门的铜钥匙,桌面静物特写”,工具生成道具插图,业务后台再把它保存到道具资料。这条流程无需创建 RP 会话,也不负责建立 NPC 或世界书条目。

研发先实现 generate,把图片服务的账号、鉴权和等待任务完成的过程接好;再由按钮或 Agent 调用工具。返回结果通过审核后,继续使用原产品的素材或消息保存代码,记录图片属于哪个对象并展示。工具工厂本身不提供可直接使用的图片服务。

import { createImageAssetTool } from "@flowgpt/agent-core-tools/image";

// 调用方实现图片后端;工具本身没有默认服务地址或账号。
const imageTool = createImageAssetTool({
  configRef: { source: "image-model", id: "your-image-config" },
  generate: async (input, { toolCallId, signal }) => {
    return yourImageBackend.generate(input, { toolCallId, signal });
  },
});

const result = await imageTool.execute("image-call-1", {
  prompt: "灰港城门的铜钥匙,桌面静物特写,黄铜材质与旧徽记清晰可见。",
  count: 1,
});
// result.details 是后端生成结果与审核证据;检查后再采用和保存。

yourImageBackend 是客户需要实现的传输适配,不是包内对象。适配必须返回工具规定的结构;仅返回 {url: ...} 不符合协议。研发在创建工具时传入 configRef,并在 yourImageBackend 中把它对应到获准使用的图片模型和账号;模型不能通过工具参数自行切换账户或配置。

程序或上游模型确定画面描述后,就可以调用 execute。需要由主 Agent 选择生图时,把创建的工具对象加入 AgentOptions.initialState.tools,如示例中的 tools:[tool],主模型便能调用 generate_image_asset。角色外貌、消息安排等仍需业务提前准备;仓库 RP 前台循环的菜单则由另一处应用代码定义。

参数/配置 真实约束 谁提供、例值与业务含义
prompt 必填,非空;执行校验最多 32,768 UTF-8 字节 运营填描述,或上游模型先生成,例如“铜钥匙放在木桌上,特写旧徽记”;工具不会先替你生成描述
reference_images 可选,最多 9 个 HTTP(S) URL,不能带用户名密码 后端从角色或素材记录中取出的参考图 URL,或 Agent 从业务已提供的图片中选择;不是上传文件本体。顺序要与描述匹配;多参考图是否生效取决于图片模型
count 可选,1–8;schema 标注默认 1 业务或模型提出图片数量,例如 1;工具不会把缺失值主动补进后端请求,后端也应约定默认数量
width / height 可选,正安全整数 业务或模型要求像素尺寸,例如 1024 / 1024;工具仅校验整数,支持哪些分辨率由后端决定
configRef 创建工具时绑定;source 为 multimodal 或 image-model,id 非空且不超过 256 字节 研发填写图片后端已经能识别且允许使用的配置引用,如 {source:"image-model",id:"your-image-config"};id 要与自己实现的 generate 中的配置映射对应,不能只填图片模型的显示名称期待自动接通;传给后端时字段为 config_ref,不属于模型可选参数
execute 的 toolCallId 方法第一个参数;传给后端调用上下文 程序直调时自己分配,如 "image-call-1";模型工具调用时由运行循环传入。用来关联一次调用,工具本身不据此保证去重
execute 的 signal 可选第三参数,未传则创建未取消信号 调用工具的后端提供取消/截止时间,例如沿用当前任务 signal;工具没有另设自己的整体超时,也不会取消后自动重发
创建工具时的 generate 必须实现的异步后端函数 接入方负责实际 URL、服务账号、传输、任务完成查询和结果映射;本包没有默认图片后端。若服务只回“已排队”,须由适配层取得符合合同的最终证据再返回

返回格式、采用条件与失败处理 #

返回包含顶层 moderation_status 和 1–8 个 jobs;每个任务含 task_id、image_urls、与每张图片一一对应的 moderation。审核项的 asset_url 必须对应图片 URL。

例如,后端可以提供如下结构(任务、地址和审核字段是业务示例):

{
  "moderation_status": "COMPLETED",
  "jobs": [{
    "task_id": "image-task-1",
    "image_urls": ["https://assets.example.com/copper-key.png"],
    "moderation": [{
      "asset_url": "https://assets.example.com/copper-key.png",
      "status": "COMPLETED",
      "classification": "SFW",
      "blocked": false
    }]
  }]
}

工具会校验任务、URL、逐图证据是否配对,以及状态值是否合法;结构合法的 COMPLETED 或 ERROR 都能通过这一层。展示前,业务还要像仓库示例一样检查顶层 moderation_status="COMPLETED",逐张确认 status="COMPLETED"、classification="SFW"、blocked=false,并核对 asset_url 与准备采用的图片 URL 一致。这些采用条件需要业务执行,工具校验器不验证 classification 和 blocked。

程序收到的是 {content:[{type:"text",text:"上述结果的JSON字符串"}], details:上述结果对象}:content 供 Agent 继续理解工具结果,details 供业务提取任务 ID、图片 URL 和审核证据。工具不会把 URL 自动插入 RP 正文,也不会把图保存成角色头像或世界书插图。业务需在采用后自行保存资产与目标对象的关联;下一次想拿这张图做参考,还要明确传回 reference_images。

例如这张铜钥匙图用于道具卡:接入方从 details.jobs[0].image_urls[0] 取得本次示例的 URL,检查对应审核证据,使用自己的存储把它关联到那张道具卡。下一次用户说“画钥匙的另一面”时,业务先读回这张已保存图片,将 URL 加入新调用的 reference_images,并在新 prompt 中说明“保持同一枚钥匙”。工具不会根据“铜钥匙”这个名称自行查到上次图片;多任务/多图片结果也应逐项配对处理,不能永远只取第零项。

本基线公开示例使用的审核分类字段是 classification,不是 label 或 decision。如果客户的图片后端采用其他字段,应在传输适配层转换或实现对应的采用检查;不要只看工具调用没有抛错便放行图片。

这是计费且非幂等的操作,工具声明 replay: "never"。调用只提交一次;超时或返回证据不完整时,不能自动重提并假定第一次没发生。接入方的后端仍需自行记录和追踪这次生成、处理重复请求;结果不明时,要根据图片服务实际提供的接口确认结果并恢复已生成的资产。

结果校验与执行 · 独立图片接入示例

实际 Agent 工具注册与结果采用 · 可调用方法、后端参数与返回

聊天配图:从用户请求到消息里的图片 #

Actor 写出一段正文后,前台控制模型可以调用 generate_image({})。程序将本次请求的账号、会话、角色与消息身份,连同最新正文片段和图片序号交给配图流程;控制模型无需填写这些 ID,也不会在这里拿到图片地址。沿用守卫与铜钥匙的例子,实际输入如下。

配图流程会先按 ID 找到业务保存的助手消息,在该消息的 narrative 图文记录中写入一个待完成图片位置,然后让图片服务回填。前端读取更新后的消息才有图片可展示。因此自己的聊天后端需要支持按 ID 读取、修改消息,或实现等价的图片与消息关联。这里的 narrative 保存这条消息的正文、图片和视觉状态,与 Story 用于主副线进度的 NarrativeSnapshot 是两份数据。

ImagineSkill.run 字段 现成入口从哪里拿、谁决定 例值与条件
userId turn_context.user_id,使用产品的账号 ID "user-42";必填,用于读写这个用户的消息
conversationId ChatRequest.conversationId,当前 RP 聊天 ID "conversation-8";必填,不能传外部 DIO 的处理会话 ID
promptId ChatRequest.promptId,当前角色 Prompt 资源 ID "lia-character";必填。角色文字与参考图由其他读取步骤准备,不在这个 ID 字符串中
messageId turn_context.assistant_message_id,本轮由业务保存的助手消息 ID "assistant-101";必填。图片会放进这条消息,业务必须让这条消息实际存在
output 聊天程序从这次 Actor 返回中取出的刚生成正文片段 "莉娅抬起头,窗外的光落在她的脸上。";必填,不是整个聊天历史
imagePromptOutput 可选,图片描述模型返回的完整 <image ...>JSON</image> 块 本轮图的具体画面描述。现成应用优先用它;缺失时从 output 提取图片块,再否则用整段 output 作简单描述
imageIndexOffset 可选,当前要放入消息的起始图片序号,前台程序计数 第一张 0,第二张 1;默认 0。是图片位置,不是消息在聊天中的序号
requestId 聊天程序为这次图片调度派生的请求 ID 如 "rp-turn-101:image:0";必填,用于追踪后续消息编辑和图片提交
language 当前请求语言,来自 turn_context 可选,本例 "zh",继续传给图片后端
visualState 可选,前面 prepareVisualWorld 取得的本轮旧视觉状态对象 聊天程序保留准备步骤的返回对象并传入,供消息记录 stateBefore;不是让前台模型自行构造任意世界状态
方法第二参数 signal 当前图片后台任务的取消/超时信号 必填;现成应用使用图片后台任务信号,不要求用户等图片生成完才拿到文字

配图描述模型拿到的资料也有具体来源:character.name/nickname/permanent/personality/summary/scenario 来自角色卡与 Prompt 读取;visualWorld.state 来自视觉状态恢复;persistentState 来自已有角色状态并补入永久视觉身份;people/threads/world 来自 Axon 的角色扮演资料投影。再加本次 userInput、actorSegment、零起始 imageIndex 和程序给的构图参考。这不是自动把 Actor 完整聊天 Prompt 原样复制给画图模型。

Imagine 输入合同 · 图片资料读取与描述模型材料 · 实际 run 字段映射

示例输入:“莉娅抬头看我,给这个瞬间配张图。”当前应用接线按以下顺序执行:

  1. 前台控制模型先调用 actor 生成正文片段,再选择 generate_image 配图。它也可以在调用 actor 时指定 responseMode="visual_beat",由程序在该片段成功后自动安排图片,同一段无需再调用一次 generate_image。具体选择由控制提示词和模型决定,用户提供的是要求与画面意图。
  2. 首次实际安排配图时,程序读取或初始化视觉状态,并取得角色卡、角色 Prompt、持久角色状态,以及已整理的人物、线索和世界材料。
  3. 图片描述模型读取原用户要求、这段正文、图片序号、人物永久外貌和当前视觉状态,生成带镜头、比例等属性、正文结构符合要求的 <image> 块。用户指定的画面重点优先于默认构图。
  4. ImagineSkill 按助手消息 ID 等待业务保存消息,默认每 200 毫秒检查一次,最多等 120 秒。消息存在后才能写入图片位置。
  5. 程序在 narrative.sections[index] 写入 type:image、status:pending 和空 URL,将描述存入 narrative.imagePrompts[index];写入失败就停止这次图片提交。
  6. ImageMcpTool 通过 MCP 的 generate_image,或已配置的 Image Agent HTTP 接口,提交消息身份与图片位置。下游图片服务负责生成、审核和回填。
  7. 本轮确实准备过视觉状态且 Harness 成功完成后,程序在后台调用 commit_visual_world,结合整轮正文更新旧视觉状态。它按整轮结算,不会在每张图片之后重复处理同一轮。

用户可能先看到正文,再等到图片回填;视觉状态也有自己独立的保存过程。界面要分别根据正文、图片任务、最终图片和视觉状态的实际结果展示进度。普通 V2 的 Director 另存导演笔记,不使用这里的图片位置或视觉状态字段。

接线与任务调度 · 图片模型材料 · 图片提示词生成与校验 · 消息位置保存 · 整轮视觉状态结算

前台两种配图触发及重复限制见 前台配图决策与自动安排。前台工具结果返回图片序号或任务受理信息,让控制模型继续当前正文;最终图片 URL 由下游生成和消息回填链路提供。

这次调用返回什么,消息里先出现什么 #

前台控制模型先收到 {"ok":true,"scheduled":true,"imageIndex":0},含义是已安排第一张图。后台 ImagineSkill.run 则在写好位置、完成其图片提交调用后返回数量,如 1;它不是图片 URL,也不保证下游已完成生成和审核。某个提交失败时会抛错,并可汇总为 AggregateError。

这时助手消息的 narrative 里先有以下内容(教学示意,省略其他已有字段);imagePrompts[0] 与 sections[0] 对应同一张图:

{
  "sections": [{
    "type": "image", "ratio": "16:9", "status": "pending",
    "url": null, "moderationLabel": null, "dominantColor": null
  }],
  "imagePrompts": ["<image ratio=\"16:9\">莉娅抬头,窗光落在她脸上。</image>"]
}

上面演示的是程序允许的简单描述回退,不是描述模型的完整镜头 JSON。真实描述模型成功时,保存的是它生成的结构化图片块。下游图片服务再读取材料、生成并更新对应消息;聊天端根据实际更新后的消息展示图片。当前仓库的调用端没有实现图片后端内部的出图、审核和最终回填状态机,不能把 pending 或 HTTP 成功当作成图验收。

所以聊天接入方要保留同一组“助手消息 ID+图片序号”贯穿占位、提交、回填和显示。例如第一张是 assistant-101 / imageIndex=0,后端更新的是这个位置,客户端也应刷新这个位置;把任务 ID 当成聊天消息 ID,或每次刷新都追加一个新位置,会破坏这一关联。最终图片是否显示,应以消息中实际回填的状态/资产为准,不以主控模型收到的 scheduled:true 为准。

直接 Image Agent 接法发送 POST /v1/chat/image-generation,请求体只有 userId / conversationId / promptId / messageId / imageIndex / requestId:**画面描述已经先写入消息,下游据消息和图片序号读取。**MCP 接法则调用 generate_image,另外直接传 originalMessage / selectedParagraph / imagePrompt / aspectRatio 等画面字段。两种传输不能只替换服务 URL 就假定请求合同一样。

先写消息再提交 · 两种图片服务请求

视觉连续性:新人物怎样被记住,下次画图从哪里接着用 #

用户说“一个穿红衣的商人走进城门”时,Actor 先写出角色出场。本轮实际安排配图、准备过视觉状态,并且整轮成功完成后,后台模型才根据旧状态和正文提出“新增红衣商人、把他列为在场人物”等修改。程序把修改后的名字、外貌、场景和在场情况保存到本轮助手消息。下次画图沿当前聊天路径读回状态,商人仍在场时,他的外观就会进入新的图片描述材料。

配置 IMAGE_AGENT_URL 时,视觉状态由仓内 AxonVisualWorldToolRuntime 按下表处理。配置 IMAGE_MCP_URL 时,程序把 prepare_visual_world 和 commit_visual_world 交给外部 MCP 服务,恢复与保存细节由外部实现决定。两个地址同时存在时,当前应用优先使用直接 Image Agent 路径。 两种运行时的选择 · 外部 MCP 调用边界

时机 程序和模型怎样处理 具体拿到什么、保存在哪里
本轮第一次实际安排配图 程序按请求提供的历史助手消息 ID,从近到远读回消息 优先取 narrative.stateStatus="applied" 的 stateAfter;返回本轮 stateBefore 与画图用文本 renderedState
最近几轮没有成功状态 程序收集这些消息的正文,交给状态更新模型补算;找不到成功 stateAfter 时还可尝试已有 stateBefore 从已知状态推到本轮之前;多个漏掉的消息正文合并为一次模型调用,不是逐轮重放
从来没有可用视觉状态 初始化模型读取角色卡、角色 Prompt、开场白和可用参考图,再补算请求所提供的历史正文 创建 world、characters、scenes、counters 等状态;这次准备本身不发布独立角色卡
图片提示词生成 将旧视觉状态渲染成 <KAON_STATE>,配合角色和本轮正文交给图片描述模型 包含画风、时间/天气、在场人物外貌和当前场景;离场人物保留在状态内,但不全量渲染到这个画图文本
整轮成功后的后台结算 程序先保存 pending;状态更新模型读取旧状态和整轮正文,返回 JSON 修改;程序校验并应用 在本轮助手消息的 narrative 写入 stateBefore、statePatch、stateAfter、stateStatus:"applied"
下一次有配图请求 再沿这次请求提供的历史消息 ID 恢复;不直接使用进程中上一请求碰巧留下的对象 读到新人物/外观后重新渲染,交给这次图片描述;前提是业务提供了正确聊天路径的消息锚点

这里的恢复锚点是 prepareVisualWorld.beforeMessageIds:现成入口从请求 messages 中提取有 ID 的 assistant 消息,运行时从近到远查找;不是只传 conversationId 就能保证找到当前分支状态。自建 Agent 调用准备方法时,至少要提供 userId / conversationId / promptId / requestId / beforeMessageIds;返回 initialized / stateBefore / renderedState。其中 initialized 表示这次是否初始化,stateBefore 是可供后续结算的对象,renderedState 是可供图片描述使用的文本。

结算方法 commitVisualWorld 接收同一组账号/聊天/角色身份、本轮 messageId、requestId、准备时的 stateBefore、本轮完成的 rawRoleplayOutput,以及可选语言参数;返回 void,结果通过助手消息上的 narrative 状态保存。现成应用传入的是 Harness 最终 result.output.text,字段名带 raw 不代表这里一定传未后处理草稿。自建接法必须保留准备结果并在整轮采用时主动结算,不能只调用 prepare 就期待人物资料自动持久化。

准备与结算方法合同 · 现成请求的历史锚点 · 整轮最终正文交给结算

红衣商人的名字、永久外观、当前外观和在场状态,会保留在这条消息的视觉状态中。独立 NPC 卡、人物性格与完整身世、世界书、V2 导演笔记和其他产品的角色库,仍要通过各自业务流程维护。没有实际配图、没有准备视觉状态或整轮失败时,这个 afterTurn 不启动结算。

按历史恢复与初始化 · 画图材料的实际渲染 · 结算触发与正文来源 · 未准备或未完成时跳过

视觉状态的修改格式、保存字段、补算与失败边界

假设本例画面中只有红衣商人,状态更新模型可以返回下面这样的修改(演示数据,不保证模型每次都这样提取):

{
  "newcomers": [{
    "type": "character",
    "name": "红衣商人",
    "owner": "story",
    "permanent": "棕色卷发,右眉有一道浅疤"
  }],
  "state_changes": [{
    "type": "character",
    "target": "红衣商人",
    "group": "clothing",
    "op": "set",
    "value": "穿红色外套"
  }],
  "present_cast": {"characters": ["红衣商人"]}
}

程序先处理 newcomers,给新人物分配未占用的 C… ID,再应用 state_changes,最后按 present_cast 更新谁在场。上例把外貌放入人物的 permanent,把红色外套放入 current.clothing。present_cast.characters 是本次完整在场名单,不是追加名单;未列出的已有角色会被标为离场。只创建 newcomers 而未把人物列为在场时,新人物默认不会进入本轮之后的在场画图文本。

修改或保存字段 实际含义
newcomers 新增人物或场景,按名字检查已有记录;不会每次遇到同名人物都建新 ID
state_changes 对已知人物/场景的分组状态做 set 或 clear;不存在的目标被跳过;人物 condition 写到临时状态,其余写到当前状态
world_change 更新世界状态字段;程序不允许通过此 patch 修改 style
present_cast / scene_change 更新在场人物与当前场景,不是正文台词
stateBefore 这次结算依据的旧视觉状态,保留恢复起点
statePatch 模型本次提出、程序已应用的 JSON 修改
stateAfter 应用修改后的完整状态,供后续恢复
stateStatus pending → applied;更新失败时尽力改为 failed
stateSchemaVersion / firstTurn 当前写入版本为 2;firstTurn 依据旧状态 turn===0

模型提出变化,程序执行字段校验和补丁规则,没有另外固定调用一个质量 Review Agent。condition 可带 decay_after,按视觉状态的 turn 衰减;每次应用 patch 加一。多轮历史合成一次补算也只加一,因此不能把这里的衰减次数等同于真实聊天轮数。当前调用不自动写一份全局最新状态;数据与这条助手消息绑定,正确的历史消息 ID 决定恢复哪条路径。补丁应用及人物状态 · 更新模型的材料与返回 · 合并补算

结算先等助手消息存在,再写 pending,调用状态模型,成功后写 applied。等消息默认最多 120 秒、每 200 毫秒检查;没有消息、模型返回不能解析的对象、非法 patch 或消息编辑失败,均可能阻止结算。失败标记也是一次外部写入,可能因相同取消/服务故障写不进去,所以不能保证所有失败最终都显示 failed。下一次准备只优先采用标记 applied 的成功快照,也可以从旧 stateBefore 加历史正文恢复;补算不是已经完成写入的证明。消息读写 · pending、成功与失败保存

当前直接接法绑定初始化模型配置 image-agent-init-visual-world-anime-v2 与更新模型配置 image-agent-visual-world-producer-anime-v1;这些配置的 PromptManager 由 Axon 提供,不能只部署 TypeScript 代码就假定模型/提示词都已配置。底层运行时构造参数接受相应配置 ID,仓内二开可在装配处替换。当前模型配置引用 · 加载模型提示词

开启需要什么,不能只填一个工具名 #

条件 当前应用要求
前台工具控制 场景有 preActorDirector 和对应控制模型配置
生图技能 skills 至少一项的 afterActorTools 包含 generate_image
图片描述生成 提供 imagePromptProducerPrompt,由控制模型配置执行描述生成
下游依赖 接好 ImagineSkill、图片服务、角色资料与消息读写服务
消息归属 请求提供真实的 assistantMessageId,业务会保存对应消息
兼容关系 Story 仍与这个前台控制开关互斥;Sumi 走独立路由。前台循环现在可以显式配置世界书,选中原文进入 Actor,不自动复制给图片描述模型

这些是应用内部接法,generate_image 不是 Core Tools /image 子入口里 generate_image_asset 的别名。如果客户只需要图片资产,直接用独立工具;如果需要沿用这套聊天交付,需要接好上表依赖或自行实现同等职责。

使用 apps/emochi 聊天服务时,研发修改入口的 config/scenarios/<入口名>.json;使用 AGENT_ROUTER_SCENARIOS_JSON 的部署则修改其中对应对象。在 preActorDirector 内填写 modelConfigId、skills 和 imagePromptProducerPrompt,每个 skill 提供 name / description / actorParameters,图片项再加 afterActorTools:["generate_image"]。图片描述模型使用 preActorDirector.modelConfigId,实际生图服务通过 IMAGE_AGENT_URL 或 IMAGE_MCP_URL 配置,此外需要 AXON_URL。MCP 可选凭证为 IMAGE_MCP_API_KEY;直接 Image Agent 调用会发送账号、请求与语言头。仓库 staging 文件提供了配置示例,其他产品入口是否启用仍取决于各自加载的配置。

文件场景由 HARNESS_ENABLED_SCENARIOS 选择,HARNESS_SCENARIOS_DIR 可改目录;与 legacy JSON 同名时,JSON 整项覆盖文件场景。配置在启动时加载,改完还需让对应部署实际加载新配置。配置来源和覆盖规则

自己的聊天后端可以集成应用模块 ImagineSkill,创建 ImagineSkill(narrative, image)。narrative 要实现 conversationMessage 与 editConversationMessage,按用户、会话和消息 ID 读写已有聊天消息;image 要实现 generate(input, signal),请求实际图片服务。正文生成后,程序按上表提供身份和片段并调用 run,图片服务随后通过消息接口回填。下面演示调用形状,两个服务适配对象需要研发实现。

// 仓内模块 apps/emochi/tools/imagine-skill.ts;不是 Core Tools 公共导出。
const imagine = new ImagineSkill(narrative, image);
const submittedCount = await imagine.run({
  userId: "user-42", conversationId: "conversation-8", promptId: "lia-character",
  messageId: "assistant-101", requestId: "rp-turn-101:image:0",
  output: "莉娅抬起头,窗外的光落在她的脸上。",
  imageIndexOffset: 0, language: "zh"
}, signal);
// 这段未接图片描述模型,会按正文构造简单 <image> 块;结果是提交数量。

要取得现成应用同样的图文效果,研发还要在自己的聊天后端中,先调用 ImageMcpTool.prepareVisualWorld 取回旧视觉状态,再调用 produceImagePrompt 生成图片描述,并在整轮完成后调用 afterTurn/commitVisualWorld 更新视觉状态。只复用 ImagineSkill.run 会得到“按已提供材料保存图片位置并提交”的能力,不会自动替你调用这些前后步骤。自己的 Agent 程序负责决定何时调用,聊天后端和页面负责展示最终消息并处理失败状态。

前台字段校验 · 部署依赖 · staging 配置示例 · 可替换的消息读写与图片执行接口

Sumi 加世界书后,哪些模型实际看得到 #

9 月 22 日主干允许 sumi-v1 显式配置 worldbook。本轮先按角色 Prompt 解析书与版本,Sumi 取得自身历史和视觉状态后选择条目,再把条目放进生成正文、画面描述和状态输出的主模型请求;最终完整请求仍要经过 Sumi 的预算和精确计数检查。

例如条目规定“灰港守卫统一佩戴铜色胸针”,主模型能用这条设定描述本轮画面。同批原文没有自动传给 Sumi 的视觉初始化或历史恢复模型,也没有原样写进视觉状态快照。 Sumi 保存的仍是本轮主模型实际产出的正文、状态和图片描述;不能据此声称所有视觉阶段都已核对同一本世界书,或世界书自动成了图片工具的永久资料库。

Sumi 自身的组合限制没有消失:仍不能同时配置普通 agenticV2、Compact、preActorDirector、额外记忆来源或 before/after Hook;它不是普通 V2 的前台循环配图模式。Actor 的 4 秒恢复缓冲也属于另一条正文运行时,不能直接套用到 Sumi。世界书先于独立 Sumi 分流 · Sumi 主模型注入、计数与快照 · 保留的组合限制

Sumi 主干已支持用户参考图、图片描述编译和调用追踪 #

本次更新假设角色有一张立绘,用户也为自己扮演的人物设置了一张参考图。Sumi 会读取两张图和两个人物的文字资料,建立初始视觉状态;主模型再根据聊天写出正文、图片标签和更新后的状态。图文模式会继续生成、保存和通知图片;纯文本模式只交付正文,仍保留看参考图和更新状态的过程。启用了图片描述编译服务时,程序先让它整理完整图片标签;本次新图片的编译失败,只要整个任务没有取消或超时,便使用原始标签继续尝试生图。

本次更新截至 10 月 19 日巡检,上述模式选择、编译失败兜底和初始化追踪都已合入 main。此前的历史恢复、用户参考图有条件复用和流式 loading 继续保留。最新核实的 Sumi 生产部署是 10 月 19 日 13:26 的 f9b26a9;具体业务选了哪个模型、是否启用纯文本实验,以及真实用户体验,仍要查看生效配置与业务结果。接入字段和部署依据分别放在下面。

事情发生的顺序 谁提供什么 结果与下一步
取得用户扮演人物的参考图 聊天后端提供已确认的用户、角色和可选 personaId;程序调用 Axon persona.get 只采用已启用且地址为 HTTP(S) 的人设图片,与角色图共同参与初始化;没有有效用户图时继续单角色图路径
本次更新准备本轮主模型 优先接收 Chat Service 已选定的 ModelConfig ID,否则用当前 Sumi 配置的默认 ID;Axon 返回对应模型参数和 Prompt Manager 程序渲染人物变量与 kaonState,再加入历史、本轮输入和选中的世界书条目;新版模型没有有效的系统提示词时直接报错
本次更新主模型流式给出完整 <image> 标签 其中包含画面描述、比例及引用图片的标记;程序保留这一刻已输出的正文 图片开启且已配置生图时,后台先校准正文段落,保存占位并通知客户端 loading;此时不编译图片描述、不发起收费生图
本次更新主模型完成且本轮快照保存成功 本轮快照保存正文、状态、实际主模型配置 ID 和图片开关;图文模式还保存图片标签、参考图和生图配置 图片开启时才安排最终交付;配置了 sumiV1.imageGeneration.promptCompilerUrl 时,把完整标签交给编译服务,单独最长等待 15 秒
编译服务返回描述 返回 prompt、referenceRoles 等结构;程序核对格式、图片比例、角色引用合法且不重复 mode 不为 null 时按 referenceRoles 安排参考图;为 null 时保留原有参考图数组。没有用户图时移除不可用的 picture2 绑定
本次更新发起图片生成 编译成功用返回描述;编译失败且任务仍有效时用完整原始图片标签;未配置编译服务则沿用原图片描述路径 程序在编译、生图之前就保存这张图的执行记录;已有结果直接复用,不因本次兜底再次付费。最终仍检查图片和审核结果,再存档、通知

角色立绘来自角色 Prompt 的 thumbnail_url,必须为有效的 HTTP(S) 地址;用户参考图来自已启用 Persona 的 image_url,不存在、禁用或地址不合法时省略。初始化状态时两张图的顺序固定为角色图、用户图;生成开场图片描述时仍只用角色图。参考图还随图片配置写入本轮快照,后续交付按这份快照继续,不会临时换成另一套素材。资料读取与初始化 · 完整图片标签与参考图排序 · 本轮快照

角色名、图片引用标记应怎样写,由关联的 Prompt Manager 提示词规定。PR #239 已移除运行时另外追加的 Role bindings / Image references 系统消息,因此研发接入新版 Sumi 时,需要核对实际关联的提示词是否包含这些规则。只更换镜像不会替外部 Prompt Manager 补齐内容。程序按 Axon 返回的顺序逐段渲染系统提示词;仅旧 Demo 模型在没有托管提示词时保留内置模板。系统提示词的实际组装

本次新增业务怎样选择正文模型,以及要不要交付图片 #

本次新增例如同一款产品想让一部分用户收到图文回复,另一部分只收到文字,同时比较两个正文模型。Chat Service 先决定这次请求分到哪一组,再把已经选好的模型配置交给 Sumi。Harness 接收这个结果,不在这里再次随机分组。PR #300 已合入 main;模型选择和图片开关分别控制正文调用与图片交付。

研发在哪提供什么 程序怎样采用 接入时实际要填写或核对什么
本次新增Chat Service 传来的 runtime_decision,解析为 targetModelConfigId 优先加载这个 ID 对应的 Axon ModelConfig、Prompt Manager 和模板变量;没有时使用 Sumi 配置中的 modelConfigRef 填已存在的内层模型配置 ID,不能只填显示名;该配置的 provider 必须为 kaon-router
本次新增已解析的 temperature / maxTokens / contextLimit 提供了哪个值,就覆盖所选 ModelConfig 中的对应参数;其他参数保留 maxTokens 必须为正安全整数;完整输入额度仍按 contextLimit - 353 计算。最终计数使用实际选中的模型及其提示词
本次新增实际服务配置 AGENT_ROUTER_SCENARIOS_JSON 中的 sumiV1.imagesEnabled 缺省或 true 开图;false 关闭 Sumi 的新图片、loading 占位及历史图片补发 使用布尔值 false,字符串 "false" 会在加载配置时被拒绝。要实际生成新图,还需提供可用的 imageGeneration 配置和图片服务;只开图片开关不会自动接通图片模型
本次新增Sumi 入口及视觉模型 入口名可为 sumi-v1 或 sumi-v1-*;仍要求明确的 modelConfigRef、presetRef 和 visionModelConfigRef 不能同时配置 Agent V2、Compact、另一套协调器、memorySources 或前后记忆 Hook。主模型 A/B 不会替换初始化和历史恢复使用的视觉模型

本次新增纯文本仍然是 Sumi 的完整正文和状态流程。 程序仍读取角色参考图、可选用户参考图,必要时调用视觉模型初始化、恢复历史,并让主模型生成正文与新状态。它也继续按配置读取世界书。图片标签不会展示给用户;内部模型全文和状态保留,但新快照中的 images 是空数组,也不保存用于后续生图的 imageGeneration。因此,关图不等于停止所有看图模型调用,也不能直接推算为省掉了整条视觉链路的费用。

本次新增同一条已完成回复再次进入时,程序按助手消息 ID 和原输入找到快照,直接回放旧正文,发生在读取新模型配置之前。切换模型实验不会重写这条已提交回复。图片行为同样尊重保存结果:旧快照没有 imagesEnabled 字段时保留旧图文语义,但当前场景已关图就不补发;在纯文本模式生成的快照,以后重新开图也不会补出本来没有保存的图片。开关变化不撤回已展示的图片,也不取消此前已启动的后台任务。

本次新增保留图片、却没有 imageGeneration 的旧 Demo 路径仍用快照里的角色图填入图片位置,不调用新的收费生图。这与纯文本模式完全不交付图片不同;接入者不能只看到 imagesEnabled=true 就认定已经在生成新图。旧路径与真实生图的分支

模型选择和参数覆盖 · 入口与布尔配置校验 · 图片开关与快照保存 · 回放与图片调度

本次新增图文/纯文本配置示例与实验接线范围含 4 处更新

本次新增仓库提供的 deploy/config/sumi-v1/image-modes.example.json 中,full 与 text-only 两份示例只在 imagesEnabled 上不同。实际接入时,在服务加载的对应 Sumi 配置中填写布尔开关,保留该业务真实可用的模型、预设和视觉模型 ID;示例文件存在,不表示生产已读取了它。

本次新增
{
  "sumiV1": {
    "visionModelConfigRef": "已配置好的视觉模型ID",
    "imagesEnabled": false
  }
}

本次新增这是配置片段,需放入已经具备 modelConfigRef / presetRef 的 Sumi 场景条目,不能单独作为完整服务配置启动。实验文档还要求 Chat Service 配合处理独立的主动生图设置;Sumi 关图只约束经过本页这条路径的图片,不能替外部 Chat Service 关闭另一条主动生图路径。本轮没有独立审查 Chat Service 的分桶代码或读取生产实验配置。

两种图片模式示例 · 分桶和分阶段接入说明

文字还在输出时,图片位置怎样先显示 loading #

本次更新例如模型已经输出“莉娅站在城门前”,并闭合了紧接着的 <image>…</image> 标签,后面的台词还在生成。imagesEnabled 没有关掉图片、且配置了 sumiV1.imageGeneration 时,程序立即把这张图与当时已输出的正文交给段落校准任务,确定 loading 应放在哪一段。标签必须完整且内容非空;没有有效图片标签,不会凭空出现占位。

顺序 程序做什么 保存或通知的东西
图片标签闭合 捕获图片内容、序号、原始段落和当时可见正文,后台校准对应段落 最多四个校准任务并行,每个任务 20 秒;文字流不等待校准完成
占位准备好 按版本先保存占位,再调用 notify.push chatImageGenerationStartedV2 带账号、聊天、角色、助手消息、通知请求 ID、selectedParagraph 与比例;客户端可据此显示 loading
正文与状态完成 保存 turn:<助手消息ID> 的完整 Sumi 快照 只有保存成功才安排最终图片交付;loading 已出现不表示收费图片请求已经发出
本次更新最终图片交付 等占位任务结束,先保存图片执行记录,再编译图片描述并调用图片服务 成功/失败沿同一图片通知身份交付,并关闭占位;段落位置变化时先处理旧占位再通知新位置
正文失败或取消 撤销本次请求对占位的使用,安排清理 没有其他拥有者或已成功保存的同图快照时,发错误通知并关闭;不会因失败流清理而关闭另一个成功流的 loading

占位记录用助手消息 ID、图片序号以及图片内容和原始段落签名区分,保存 requestId / selectedParagraph / closed / owners 等字段。多个重复或并发流可以共用同一图的占位;已取消记录被后来的新流复用时,会更换通知身份,避免迟到错误关闭新 loading。通知属于尽力交付,网关失败不表示收费生图失败,也不能保证客户端已经渲染;本轮没有实际验收客户端 loading 展示。

流式标签完成条件 · 占位身份与通知 · 共享占位取消保护 · 流式启动与保存后交付

用户换了设定、参考图或聊天分支,下一轮怎么继续 #

例如用户把自己的人设从“第一次进城的学徒”改成“守卫认识的旧友”,并更换了参考图。下一轮程序会发现当前人设、图片与此前保存状态所依据的材料不同。它先用新材料建立初始状态,再让视觉模型从这次选中的历史正文恢复场景、动作和情绪,最后把恢复结果交给本轮主模型。这样不必删除整个会话,但旧画面中的镜头、姿势等未写在历史里的细节无法保证还原。

如果只是换了用户参考图,角色文字、开场白、用户人设文字与角色图都没变,程序会另走一条有条件的复用路径:旧快照的完整历史前缀指纹、精确父消息链都与当前选择相符时,继承旧 stateAfter,只用当前初始化结果替换 USER_ANCHOR(用户外观描述)。这样保留已经核实的剧情状态;旧快照没有完整历史指纹,或路径对不上,就仍从可见历史重建。

用户重新生成某条回复、选回另一条聊天路径时,也会触发类似检查:程序核对每条 Sumi 快照的父消息和此前历史的摘要;对不上当前选择的历史,就从当前材料和这条路径上的可见正文重建。尚未回答的本轮用户输入不会先混进“此前已经发生”的状态,仍留给本轮主模型处理。

程序检查的内容 检查结果会改变什么
角色文字、开场白、用户人设、角色图地址、用户图地址各自的 hash 只有用户参考图变化且历史/父链证据完整时,可以只换用户外观描述;其他材料变化、旧快照缺材料记录则恢复状态。图片 URL 相同但远端文件内容替换,不是这组字符串 hash 能检测的变化
parentMessageId 与 historyDigest 父消息或完整历史前缀改变时,按当前选择的聊天路径恢复;只有材料、父链和历史前缀都匹配的新快照,才能结束此前的恢复要求
持久化消息的 ID、role 和正文 快照缺失或正文不一致时,按当前账号和会话向 Axon 查原消息;采用核实后的已保存正文,消息不存在或身份/角色无效时只从本轮材料排除。查询报错、权限错误和取消仍失败,不当作消息已删除
sumiV1.historyImportEnabled 默认关闭。它决定普通历史能否只提取最近可信快照之后的片段;关闭时也允许从当前初始化状态完整重建,不等于关闭所有历史提取

例如 Sumi 生成“莉娅接过钥匙,并带你进入城门”,聊天服务实际只保存了“莉娅接过钥匙”。下一轮不能继续假定用户已经进城。程序发现正文与快照不同后,会按当前账号、聊天和消息编号查询真正保存的正文,再从这份正文重建状态。PR #294 也覆盖历史来源不符和原生 Sumi 快照缺失;这些情况不再直接拒绝继续聊天。

已经有快照、且快照正文与请求一致的历史仍沿用已有证明,不会每次逐条重查数据库。需要查询的旧消息,只有返回了同一消息 ID、assistant 角色和字符串正文才可采用;缺少模型名称的旧记录也能在核实正文后使用。消息不存在或这些字段不符时,只把它排除出本轮材料,不删除原会话。来源服务故障、无权读取或用户取消会停止本轮;程序不会把“暂时查不到”当作“已经删除”。

程序根据核实后的历史重新检查父消息、完整历史前缀和素材。确实需要重建时,从当前初始化状态出发,只提取到最后一条已经回答的 assistant;本轮尚未回答的用户话仍交给正文模型,不提前记作已发生的事实。如果后面已有完整快照能够证明同一段历史,程序可以采用它,减少重复重建。

恢复时保留新材料确定的角色身份、用户外观和风格,不让旧正文覆盖;修改后的开场白也不会被当作旧会话刚刚发生的新事件。新状态只供接下来生成使用,旧消息、旧快照和已完成图片保持原样。被标记为正文变化、来源不符等恢复情况的旧回复,只用核实后的可见正文,不再使用原快照的内部全文 modelText,也不继续安排那条旧回复的未完成图片。仅父链、历史前缀或素材改变,并不一律禁用旧全文或图片恢复,仍按原图片规则判断。

重建缓存与核实后的历史、当前材料和起始状态绑定,写入前检查存储版本;因此正文改变后,旧缓存不会被直接当作当前结果。主模型成功后,再按本轮助手消息 ID 保存 stateBefore / stateAfter / materials / historyDigest,其中历史指纹来自核实后的内容。提取、查询、存储失败或取消都可能停止本轮;已完成且身份仍匹配的缓存可供重试复用。恢复需要额外模型调用和时间,不能承诺所有历史问题都无感解决,也不能从文字精确还原旧图片的镜头细节。

核实正文和排除无效来源 · 快照采用、完整重建和旧图处理 · 缓存身份和完成校验 · 本轮按核实后的历史保存

本轮能放多少材料,超出以后怎么办 #

本次更新Sumi 从本轮选中的 ModelConfig 读取 context_limit,有 runtime_decision.contextLimit 时采用已解析的覆盖值。这个值表示给输入的额度,在仓内 Shiki 配置文件中对应 contextLimit。程序扣除 350 token 安全余量和 3 token 回复前缀余量,得到本轮完整输入上限;max_tokens 单独限制输出,不再从输入额度里扣一次。例如仓内 Shiki 配置的 contextLimit=5000、max_tokens=2048,允许最多 4,647 token 输入+2,048 token 输出,推理后端的总窗口至少要容纳约 6,695 token。业务换了模型或覆盖值,要按实际值重算,不能把 4,647 当作所有 Sumi 的固定上限。原输入额度调整 #247 · 当前模型和预算选择

本次更新输入计数包含实际渲染的系统提示词、当前状态、保留历史、本轮输入和世界书。超过本轮额度时,程序删除最早的完整历史轮次后重新计数;所有历史都删完仍超限,就在主模型调用前报错,不截掉本轮输入或固定提示词。计数必须来自 provider 原生结果,或与实际 tokenizer 和提示词渲染完全一致的计数实现;返回值还必须是正安全整数,0、负数、小数或非有限值都会报错。完整输入计数与校验

历史状态恢复使用视觉模型自己的 ModelConfig,预算与上面的主回复分开计算。当前抽取器总窗口按 8,192 token 限制,先为输出留 1,200 token,再与模型配置允许的输入额度取较小值:min(8192 - 1200, context_limit - 353)。例如输入额度允许时,抽取请求最多使用 6,992 token 输入,加最多 1,200 token 输出;不能再按旧的 8,192 输入额度外加 1,200 输出。

程序先把历史按最多 4,000 个 Unicode 字符拆成片段,再实际渲染“已有状态+待恢复原文”,用 provider 原生或 tokenizer/模板完全一致的计数扩张和二分,选出本次能装下的前缀。因此不是固定八块历史,也不是固定每次只读一条消息。最多八次额度只计算本次新发出的模型抽取;已完成的缓存结果,包括并发请求已经完成的同一结果,不再占新调用额度。

每次抽取必须正常结束,完整状态和缓存身份校验通过才保存;失败或取消不会留下可复用的成功状态。单次缓存等待/抽取流程最多 40 秒,整次恢复最多 90 秒;选中历史还受 500 条、256 KiB 限制。最小片段仍超窗、没有合格计数、八次新调用用尽或恢复不完整都会报错,不能悄悄把未处理的历史当成已恢复。后续重试可复用已经完成且身份仍一致的缓存步骤。

抽取窗口和次数上限 · 缓存命中不占新调用次数 · 按真实 token 组织历史 · 输入预算与切片 · 整次恢复时限

编译图片描述失败后,重试会不会重新生成 #

本次新增本次新图片的编译失败,会在同一次执行里用原始图片标签继续生图;已保存过结果的图片,不会因刷新重新生成。 例如编译服务临时返回 503,程序记下这一步失败,把原来的完整 <image ...>…</image> 标签交给图片服务,继续等待真实生图与审核结果。PR #304 已于 10 月 19 日合入 main。

遇到什么情况 当前程序接下来做什么
本次新增新图片:编译 HTTP 4xx/5xx、网络错误、编译器独立 15 秒超时或输出格式不合法 保留编译失败原因;整个任务还有效时,用原始图片标签继续一次生图
本次新增调用方已经取消,或整次图片后台任务达到截止时间 不执行兜底生图;在兜底、开始通知之后及收费请求之前再次检查取消信号
本次更新同一助手消息、图片序号已有相同参数的最终结果 直接回放已保存结果;旧版本保存的 prompt_compilation_failed 也不会自动重跑
本次新增已有执行记录但尚未结束 仍在有效期限内等待原执行;超过期限则保存 unknown / interrupted_generation,不再提交一次付费请求
本次新增图片服务返回审核拦截或无法确认的结果 继续保存 blocked / unknown 等真实结果;不会因为编译兜底就放宽审核或制造可展示 URL

本次新增兜底保留外层图片标签的属性和 JSON 内容,只规范化 <img> 别名;旧记录没有完整标签时才使用旧 image.prompt。没有用户参考图时移除不可用的 [picture2] 绑定。编译成功按返回的角色顺序选图,编译失败则沿用原来的“角色图 → 用户图”顺序,不猜测新的排列。它可能失去编译器原本提供的修复和画面整理,但仍给图片后端一次处理原始描述的机会;生成质量不因此得到保证。

本次更新收费去重依赖编译前已经保存的 image:<messageId>:<index> 执行记录。只有取得新记录的执行者会继续编译、生图;描述、参考图或编译配置与旧记录不一致时会拒绝复用,不能用相同图片身份悄悄换参数。取得终态后,程序另用 10 秒保存信号写入结果,避免调用方此时取消导致下一次重复付费。结果不明确时仍保守保留未知状态,没有新增自动重试队列。

本次新增编译失败和图片失败分开记录:失败的编译步骤仍保留;后续生图步骤标记 promptSource="compiler_fallback"。sumi_prompt_compile_errors_total{reason} 只统计实际发生的编译错误,原因使用固定名单,其他归为 OTHER;取消和旧结果回放不额外增加编译失败数。日志记录原因与 HTTP 状态,不直接记录编译服务的响应正文。图片最终是否成功,继续看生图/审核结果;兜底成功后使用原 loading 的通知身份交付。

原始标签与编译校验 · 先保存执行记录,再编译和生图 · 失败兜底与取消检查 · 终态保存 · 编译错误指标

哪一步出了问题,日志里怎么看 #

主干已经把初始化/历史恢复模型、主模型 sumi.reply、图片编译、生图、快照保存、图片归档和通知关联到同一次请求。图片后台任务在前台正文结束后继续运行,沿用父 trace 和业务请求 ID;缓存复用不会伪造一次新的生图调用。#273 已移除这些已插桩输入输出的“仅 staging”限制。telemetry 总开关默认仍关闭;启用、配置有效且请求命中采样时,各环境都允许记录实际传入埋点的内容,仍执行字段脱敏和大小限制。没有埋点的阶段不会因此自动有正文,exporter 接收也不等于远端已收到。当前配置与内容采集规则

本次更新现在的步骤指标也会检查业务返回。函数正常返回 {ok:false},或者 status=failed / blocked / unknown,仍记为失败;不再因为没有抛异常或关闭了 Langfuse 就在指标里记成成功。部分 stdout 的 model_call_completed 仍只说明函数返回,不能与指标的业务成功口径混用。展示图片还要检查 ready 和审核证据,图库保存与消息通知也分别看对应结果,不能由“正文已返回”推断图片交付完成。当前业务失败识别 · 图片审核和结果投影

本次新增PR #289 已于 10 月 19 日合入,为初始化补上统一的 sumi.init 记录:能一起看到角色/用户参考图、人物资料、开场白、缓存是否命中,以及最后得到的初始状态和开场材料。没有缓存时,两次视觉模型调用分别挂在这条初始化记录下面。阶段标记还能区分读取缓存、取模型配置、描述开场图、生成状态、校验状态和保存失败,避免两次模型都成功便误判初始化已经成功。

本次新增这次增加的是排查记录;看参考图、调用两次视觉模型、校验和保存初始状态本来就存在。缓存命中时不会再伪造两次视觉模型调用,已完成回复直接回放时跳过初始化;历史恢复和正文生成也不属于这个初始化记录内部。查看内容仍需要启用 telemetry 并命中采样,沿用脱敏和大小限制,当前生产是否采到了具体记录未独立核实。初始化父记录、缓存与子调用

Sumi 还向 Axon 上报模型和图片 Clickstream 事件,用来核对调用量、用量和结果。图片开始事件为 chat_image_generate,结束事件为 chat_image_generate_result;事件 ID 根据聊天、助手消息和图片序号生成,带图片配置、段落相关信息、成功/失败/审核结果与时长。请求携带真实用户的 x-user-id,这个统计上报与给客户端的 loading 通知是两件事。

上报失败或 7 秒超时不改变已保存的图片结果,也不会因此重做收费生图。accepted 只表示 Axon 接受事件,不证明统计平台已经入库;图片结果属性里的 rawCost=durationMs/1000*0.0001 是时长估值,不能当实际账单。LLM 事件使用调用响应提供的用量或成本字段,缺失值也不能补成已经确认的真实费用。

图片请求现在由后端写入 caller_service:"roleplay-harness-sumi";工具调试入口使用 roleplay-harness-tool-debug。它标明图片调用来自哪条后端路径,不是用户登录身份。Sumi 的来源标记不参与原有图片执行签名,升级前已完成的任务仍可回放,不能因多了这个字段再次生图。

LLM 事件身份与主回复统计 · 图片结果属性和事件上报 · 后端写入图片调用来源

PR #240 另外尝试把前台用户输入和最终可见正文写到根 trace,便于直接从整轮入口查看。它与主干已有的各步骤 trace 是不同改动:9 月 24 日核对的 main 3b6ba5f 未包含该根 trace 输入输出接线;该分支 0dad1d6 有 9 月 23 日 staging 部署记录,不能写成主干已经提供。分支根 trace 接线 · 固定 main 的前台入口

Sumi 哪些代码已部署,哪些配置还要确认 #

本次更新最新核实的生产部署为 10 月 19 日 13:26,Sumi f9b26a919965f471756cdacf0f5b2e596cd5991d。 流水线 13:24 启动,在 agent-production/roleplay-harness-sumi-v1 执行固定镜像更新和等待就绪,展开日志包含更新成功与 rollout 成功;部署 job 最终成功。该版本包含本页模型选择/图片开关、编译失败兜底、初始化追踪,以及此前的历史恢复和流式 loading。生产部署与实际步骤

本次新增该次部署使用的镜像 digest 为 sha256:5be481f299287a7b4e8f0a0b77846fb9de40e2077e2bd71c54456b2cdd890662。日志也有 watch forbidden,表示执行身份没有 watch deployments 的权限;最终 rollout 和 job 仍成功,不能据此改写为部署失败。本轮未读取此刻 Pod、有效场景、外部 Prompt Manager 或真实业务流量,不能从一次镜像更新推出某个模型实验、纯文本模式或图片编译地址已启用。

本次更新这份镜像也含有主线的 Memory、Compact 代码,但 Sumi 路由与 Emochi 的记忆/压缩接线不同,不能据此说其他业务已经采用相应策略。服务部署和 npm 包发布也分开记录:本轮没有观察到新 SDK 发布,SDK 仍为 0.6.0;Core Tools 0.2.3 沿用上次已核发布记录。

本次新增此前 10 月 11 日 ebab290 部署已包含历史正文不一致时的恢复;10 月 13 日 19:47、10 月 14 日 20:16 还各有一次 success,本轮只核对了这两次的列表状态,未展开步骤。最新 10 月 19 日这次则核到实际部署日志。10 月 11 日部署 · 10 月 13 日运行 · 10 月 14 日运行

此前 10 月 5 日 a119b8b 的生产部署已包含历史 token 组织、抽取输出预留和用户参考图条件复用,现在作为历史记录保留,不再当作最新上线版本。10 月 5 日部署记录。以下为更早的 staging 记录,供追溯来源。

用户参考图、图片编译接线和步骤 trace 随 83013e6 于 9 月 23 日 11:01–11:03 部署到 Sumi staging,移除额外角色绑定提示的 72e13d7 随后于 12:12–12:15 部署。输入预算改动的较早版本 bd7f980 也有当日 19:57–19:59 的 staging 部署记录。这些是代码镜像更新;发布流程只更新镜像,不会应用部署清单里的配置,也不会更新外部 Prompt Manager,所以不能从镜像更新推出 promptCompilerUrl 已实际启用或角色规则已补齐。Sumi 镜像部署 · 输入预算版本部署 · 镜像与配置的部署约定

9 月 24 日巡检当时,最新可见的 Sumi staging 部署事件是 9 月 23 日 21:41–21:43 的 46383d3,来自随后关闭、未合并的 PR #251。它增加进程级 SUMI_IMAGE_FAILURE_MODE,用于模拟审核拦截、模型错误或生成失败;默认关闭,影响同一进程的所有 Sumi 入口。测试分支部署过,并不表示失败模拟开关已打开:本次未读回当前容器版本、实际环境变量或真实业务请求。该分支的 staging 部署

失败模拟分支接受哪些值,关闭后旧结果怎样处理

SUMI_IMAGE_FAILURE_MODE 未设置、空字符串或 off 时不模拟;可选值为 moderation_blocked、model_error、generation_failed,其他值使配置加载失败。启用后,新的图片执行记录直接得到模拟结果,不调用编译服务、图片模型、审核或图片存档接口。结果会持久保存;同一张图再进来时复用它,即使随后把开关关闭也不会重新生成。已有成功或未知结果不会被这个开关覆盖。因此它用于演练客户端失败展示,不是图片重试或历史修复开关,也不是已合入 main 的产品能力。配置解析 · 模拟结果保存

Fusion 图片失败后,怎样让客户端结束等待 #

Fusion 的 PR #241 已合入 fusion-harness,不属于 main 的普通 Imagine 接线。某一段已经显示“图片生成中”却在图片准备或生成时失败,程序会等这段的开始通知处理完,再保留原来的失败通知,并额外发送一个没有图片 URL 的 chatImageGeneratedV2。事件继续使用同一张图的请求 ID、助手消息 ID 和正文段落,让 Android 2.2.8 按自己的失败路径结束 LOADING。

这个事件名字里虽然有 Generated,内容仍表示失败,不会制造一张成功图片;客户端要识别 type="generate-image-error"、空 URL 和相应审核标记。其他客户端还需能处理原失败事件与这个兼容事件同时到达,避免重复追加失败卡片。通知被网关接受也不代表已安装客户端一定正确展示。

本次更新该逻辑保留在此前核对的 Fusion c8fc61c 中,这个版本已于 9 月 24 日 03:16–03:19 完成 production 镜像更新和滚动部署。定向测试覆盖一张成功、一张失败时的顺序和关联 ID,但当前容器版本、Android 实际展示及 Web/iOS 的双事件兼容未被业务验收。10 月 19 日沿用这份历史记录,没有重新核对 Fusion 当前 head 或生产实例。失败通知实现 · 图片准备失败后的处理 · 包含该逻辑的 production 部署

Fusion 正在开发的图片接法 #

本次更新下面三项沿用 10 月 13 日已核的未合入记录,依次叠加为 #255 → #292 → #293;10 月 19 日未重新核对这些分支的 head 和逻辑。#255 以 fusion-harness 为目标;#292、#293 是依赖前一分支的草稿 PR。它们与上文已部署过的 Fusion 图片失败通知分开看。

重画已保存的图片,继续使用原来的消息位置 #

例如用户要重画聊天里第二张图,#255 的候选实现会找到那条消息、第二张图和原先选中的正文段落,调用已配置的 Image Tool,成功后替换同一个图片位置。失败时保留原来已批准的图片,不把聊天里其他图片挪位。这补上了手工生图/重绘使用 Image Tool 的接法,普通自动生图仍沿用已有流程。

程序先保存并认领这次重绘记录,同一请求完成后重来可直接取已有结果;提交后结果不明则留下 unknown,不盲目再次生图。找不到原正文段落时,在提交前失败;最终只允许仍拥有这次记录的任务修改图片位置。外层不再重复扣费,实际图工具的生成、审核与计费仍要按下游合同处理。固定重绘实现

已有程序判断何时插图时,避免模型收到两套图片要求 #

#292 清理的是重复指令。例如程序已经会在每段 Actor 写完后调用图片 Hook,判断这一段是否值得画图,就可以由它负责插图选择;前台控制模型继续决定正文如何推进。这样图片仍可生成,主模型不必同时再决定一次同样的配图动作。

这项清理只在以下条件同时满足时生效:用户没有明确要求“写几段且每段配图”,已经接好图片 Hook 和图片调度函数,图片数量上限也不是零。此时前台菜单不再提供 generate_image,Actor 工具不再要求 generateImageAfter,程序也不自动附加那套图片政策。没有 Hook 或用户明确要求逐段配图时,保留原图片合同;调用方自写的 plannerPrompt 会原样保留,不会自动删除其中的旧指令。启用条件与工具菜单

Rian 分镜图片工具:给一段正文,设计镜头并生成一张图 #

#293 提供 createRianImageTool,创建出的工具叫 generate_storyboard_image。例如接入方给它“莉娅推开城门,回头示意你跟上”这一段、人物外貌和前一张图的镜头记录,它先确定画面里有哪些人物和场景,再安排这一张图的景别、视角与构图,整理图片模型需要的描述和参考图,最后提交一张图。

当前能确认的是工具实现和测试源码,仓内尚未发现业务服务、Fusion 循环或 Pi 的实际调用接线。研发需要集成这段应用源码,提供模型与生图服务,再自行安排何时调用、怎样保存和怎样给用户展示;没有一个已核实的开关能让现有聊天自动切换到 Rian。

调用方准备的内容 具体含义与例子
要画的正文和这轮要求 segment 是这张图对应的完整段落,如“莉娅推开城门……”;userMessage 是本轮用户原话,如“带我进城,给开门配张图”
人物与当前视觉资料 botName、userName 是角色与用户扮演人物的名字;state 为工具规定的 v3 视觉状态或 null,记录人物外貌、衣服、在场情况、场景与参考图版本;工具不自行读取会话或升级旧状态
风格与随机种子 styleAnchor 提供本次画风约束;seed 为接入程序提供的 0–4294967295 整数。当前工具面向其动漫分镜方案,不代表所有画风都已接通
可选的前文和镜头 storySoFar、previousBot、turnCasts、priorShots 分别补充本轮前文、前轮回复、已抽取人物和已使用镜头,用来保持人物关联并减少连续同构图
创建工具时的依赖 接入方提供 model、两阶段 modelConfigIds.cast / design、图片 configRef 和 generate;还需让随仓提供的 AOI Python 编译器及规则文件可运行

一次执行只提交一张图。工具结果的 content 给上游模型一份 images / taskId;details 另外保留分镜结果 storyboard 和原始生成证据 generation。只有审核完成、分类为 SFW 且未拦截,images 才包含地址;审核不通过时是空数组。接入程序要根据这份结果保存图片、记录镜头,并在下一次调用时重新提供相关记录。

工具本身不保存会话或视觉状态,不处理用户扣费、不发送消息通知,也不创建图片 loading。一次执行不会自动重试结果不明的收费生图;两次独立调用之间的防重复提交仍由接入方实现,replay:"never" 声明不能代替持久化去重。输入和结果合同

Rian 的阶段预算、参考图和失败回退

输入 JSON 最多 1 MiB,正文不能为空;非 v3 状态和非法随机种子会被拒绝。第一阶段抽取人物和场景,最多初次加一次修复,每次提供 15 秒取消信号;第二阶段设计镜头,最多两次尝试,使用 25 秒阶段取消信号。第二阶段可以先执行接入方的 beforeT2 等待前一镜,再通过 getPriorShots 读取最新记录;这两个回调不是工具自带的持久队列。

模型结果不可用时会尝试规则选人和构图,必要时退到纯文字场景。镜头与最近一镜重复且不属于允许连续使用的镜头时,会尝试改变相邻景别,不保证每张图都完全不同。只给前/中景人物分配最多两个不同的人物参考图位置,按角色、用户、故事人物的顺序使用当前 ref_asset_version;缺图或名额不足时保留文字描述。

整理好描述后调用图片工具,count=1,当前默认 16:9、1392×768,steps=4、true_cfg_scale=1、guidance_scale=1。必须返回一个任务、一张图;合同错误或编译失败会停止。取消信号传入模型和图片请求,实际终止仍需要下游遵守信号。宿主需要保存阶段记录、结果和未知状态后再决定恢复,不能直接重发所有失败调用。

阶段串联与参考图 · 镜头调整 · 单图提交和审核

异常时读者应该预期什么 #

  • 图片描述模型失败时,应用记录降级原因,改用正文里的现成 <image> 块;正文没有图片块时,就把整段文字包成 <image ratio="16:9">正文</image>。这一步不再调用另一个描述模型,不应承诺仍有完整镜头结构。
  • 多图片任务按顺序交接,已有任务的等待会影响后续图片到达;代码中的后台超时预算不是对客户承诺的图片出图时间。
  • pending 已保存之后,下游提交仍可能失败。这段 Imagine 接线没有在所有失败路径里自动把该位置改为终态;业务需读取任务及消息状态,不能把 pending 当作成功。
  • 没有配置图片依赖时,普通 Actor 回复和后台专家分析不自动获得生图能力。

描述失败的降级 · 提交错误处理 · 当前场景兼容规则

原子能力 / 服务适配

DIO:把明确的长期要求用于后续角色回复

10/19 更新 · 本章 24 处从第一处开始看 →

用户说“从现在起莉娅都用短句回答,少用比喻”,这是一条希望持续生效的角色要求。现有 DIO 接线把这类要求提交给外部指令服务处理;后续 RP 请求再读取服务产出的有效提示词,让回复模型使用。

仓库提供 DioTool 服务适配器,以及前台工具循环里的 schedule_dio 动作,负责提交要求、查询任务、读取有效提示词并交给 Actor。实际编译和保存新提示词的是外部 DIO 服务;它的编辑、审核实现不在这两个仓库中。

本次更新本页的 DIO 服务也把这类处理称为 Director 任务,但它与普通 Agent V2 后台的 Director 不同:这里修改的是后续使用的角色提示词,V2 后台 Director 整理的是聊天中的剧情笔记。下文先说明主线已有的前台提交与后续读取;10 月 19 日新核到的 #303 则尝试在完整回复之后判断长期需求,仍为未合入草稿。Fusion 已有免计费请求标记和另一个尚未合入的 Jev 调用候选,也在各自段落标明。

已经使用仓库聊天应用时,研发启用前台控制、连接 DIO 服务地址,并为角色提示词指定正确的替换位置。保留自己的聊天后端时,也可以集成 DioTool:收到长期修改就提交,以后每次调用回复模型前读取有效提示词。原有模型和界面可以继续使用,但两种方式都需要接通真实的外部 DIO 服务。

服务适配器 · 前台提交接线

接到 Agent 的哪一步,要提供哪些数据 #

在现成应用中,本轮前台控制模型选择 schedule_dio 后,程序提交用户的长期要求;后续请求准备 Actor 输入时,再查询处理结果并采用。提交和读取要同时接好,角色才能持续使用新要求。自己的产品如果已经有“修改长期要求”按钮,可以由按钮直接提交,再在原有回复流程里加上读取步骤。

下面用一组教学数据说明请求:账号 user-42 在与莉娅的聊天 conversation-8 中提出长期要求;角色 Prompt 资源 ID 是 lia-character,本次 RP 请求编号是 rp-turn-101。实际调用时,这些 ID 都由业务系统提供。

DioTool.schedule 的字段 是什么、由谁提供 本例值与条件
userId 使用产品的账号 ID,不是扮演的角色名。现成入口取 ChatRequest.extensions.turn_context.user_id "user-42";必填;接入方须提供真实账号身份
rpConversationId 用户正在和莉娅聊的这一段 RP 会话 ID。现成入口取 ChatRequest.conversationId,内部也叫 context.sessionId "conversation-8";必填;换一个聊天会话,后续查询条件也不同
targetPromptId 当前角色的 Prompt 资源 ID。现成入口取 ChatRequest.promptId;外部 DIO 用它知道要修改哪个角色对象 "lia-character";必填。它不是角色设定全文,也不是 Actor 的 modelConfigRef 或编排模板 presetRef
instruction 要交给 DIO 处理的原始用户消息。现成应用优先取 turn_context.input_question,否则取请求消息中最后一条 user 内容,再否则用 "continue" "从现在起莉娅都用短句回答,少用比喻。";必填。控制模型只选 schedule_dio({}),不填写或改写这段文本
actorTurnRequestId 这一次 RP 请求的追踪编号,取 ChatRequest.requestId "rp-turn-101";必填。不同新请求应有各自编号,用于派生 DIO 请求和消息身份
language 本请求的语言值,现成入口取 turn_context.language,未提供时为 "en" 本例 "zh";适配器方法要求传入。它被传给服务,不代表适配器会自行翻译角色文本
userAuthorization 允许代表当前用户访问 DIO 的 Bearer 授权头,由上游聊天后端随请求提供、Router 转发;不是 userId 字符串,也不是图片或模型服务的 API Key 可选,如 "Bearer …"。Router 优先取 x-flow-user-authorization;未配置 Router API Key 时才可回退取 authorization,且只接受合法 Bearer 形式
方法第二参数 signal 取消/超时控制对象,由调用代码创建或沿用当前请求 必须传 AbortSignal,不是 JSON 字段。提交沿用本轮取消信号;受理后的后台查询使用另一个后台任务信号

本轮提交带的是角色资源 ID targetPromptId 和用户的新要求,没有上传角色卡全文、全部聊天历史或 Actor 上下文。外部 DIO 服务负责取得原角色资料并合成新版文本;后续查询得到的 compiledPrompt 才是交给 Actor 的完整角色提示词。

业务身份与原始输入来源 · 提交映射 · 用户授权头的来源

从一句要求到后续生效 #

时机 谁做什么 输入与结果 保存与生效
用户提出长期要求 前台控制模型按提示词判断是否调用 schedule_dio 本轮原文:“从现在起莉娅都用短句回答,少用比喻。” 仅模型选择,不等于要求已修改成功
提交 程序调用 DIO POST /v1/chat 本例传 userId="user-42"、rpConversationId="conversation-8"、targetPromptId="lia-character"、instruction="从现在起莉娅都用短句回答,少用比喻。";适配器把 instruction 写成 HTTP 的 question。回执含 accepted:true、requestId="rp-turn-101:dio"、taskMessageId="rp-turn-101:dio:assistant" 外部任务已受理;当前 RP 回复继续,不能把 accepted 当成修改成功
后台执行 程序每秒查询任务,直到终态或后台超时 processing → succeeded / failed / timed_out;附 promptChanged 等 指令编译与持久化由 DIO 服务负责
后续请求准备 开启相同接线的 RP 入口查询有效提示词 按 userId="user-42"、rpConversationId="conversation-8"、targetPromptId="lia-character" 查询;取得 compiledPrompt 完整文本,例如“你扮演灰港守卫莉娅,负责守门。保持既有身份;回答用短句,少用比喻。”,以及 sourceVersionId / changeSetId / compiledPromptSha256 校验全文的 SHA-256 后,写入这次请求的 dioCompiledPrompt;未找到时仍用原有角色材料
后续 Actor 回复 回复组装器用有效提示词替换指定的角色提示词位置,再展开模型消息 控制说明、历史与本轮问题仍按原模板保留;替换位置放入 DIO 编译后的完整角色提示词 影响这次新生成;已经输出的旧正文不重写

受理回执里的 appliesFrom: "next_turn" 表示修改将通过后续请求的读取流程使用。如果下一句到来时任务还没完成,或者任务没有产出新 Prompt,回复仍使用服务当时已有的有效版本。

前台控制提示词要求模型只在用户明确提出长期变化时选择 schedule_dio。选中后,程序提交用户原文,模型不再另写一份要求;执行端检查工具是否可用、参数是否有效以及是否重复调用,不再调用另一个语义模型审核用户意图。

提交原始输入及后台查询 · 下一轮读取 · 有效内容与哈希校验

一次真实合同长什么样:提交、受理、终态、读取 #

下面按适配器合同构造一组教学数据,展示提交到读取的过程。schedule 会将上表字段转换成以下 HTTP 请求体;promptId:"dio" 指 DIO 入口,targetPromptId:"lia-character" 指这次要修改的角色,二者各有用途。

{
  "userId": "user-42",
  "dioConversationId": "dio_conversation-8",
  "rpConversationId": "conversation-8",
  "promptId": "dio",
  "messageId": "rp-turn-101:dio:user",
  "assistantMessageId": "rp-turn-101:dio:assistant",
  "requestId": "rp-turn-101:dio",
  "question": "从现在起莉娅都用短句回答,少用比喻。",
  "targetPromptId": "lia-character",
  "language": "zh"
}

请求发往 DIO_URL + /v1/chat。dioConversationId 是程序从 RP 会话派生出的处理会话;派生的两条 message ID 属于 DIO 任务,不是这轮 RP 正文的助手消息 ID。请求头还带 x-user-id、x-request-id;若提供用户授权,则带 authorization;配置 demo service token 时,额外带 x-dio-demo-token。

上述 demo token 是主干 3b6ba5f 的接法;Fusion c8fc61c 已移除该构造参数,改为每次提交都发送 x-dio-skip-billing:true。两份代码的请求头不同,不能把其中一份部署设置直接套到另一份。主干请求组装 · Fusion 请求组装

服务受理后会返回以下 HTTP 响应。适配器核对其中的会话、消息与请求身份,确认匹配后,再把后一段较小的回执交给前台控制模型。此时任务刚被受理,新提示词还可能在处理中。

{
  "ok": true,
  "accepted": true,
  "conversationId": "dio_conversation-8",
  "promptId": "dio",
  "messageId": "rp-turn-101:dio:assistant",
  "assistantMessageId": "rp-turn-101:dio:assistant",
  "requestId": "rp-turn-101:dio"
}
{
  "accepted": true,
  "dioConversationId": "dio_conversation-8",
  "requestId": "rp-turn-101:dio",
  "taskMessageId": "rp-turn-101:dio:assistant",
  "appliesFrom": "next_turn"
}

后台程序随后用受理回执中的 requestId 查询 /v1/director/tasks/by-request/rp-turn-101%3Adio。下面表示处理成功,但判断无需修改,也属于合法成功。如果 promptChanged:true,响应还必须带非空 sourceVersionId 和 64 位十六进制 compiledPromptSha256,分别标明新版本与内容指纹;这一步不返回完整提示词。

{
  "requestId": "rp-turn-101:dio",
  "messageId": "rp-turn-101:dio:assistant",
  "status": "succeeded",
  "promptChanged": false
}

任务可以先返回 processing;waitForTerminal 持续查到 succeeded、failed 或 timed_out 才结束。失败可附 errorCode、errorMessage。应用还会核对终态 messageId 与受理回执是否一致;适配器异常、非成功终态和后台查询超时会记为后台任务失败。

后续请求真正准备回复时,会再查询当前有效文本。例如 rp-turn-102 在准备 Actor 输入前,使用原来的账号、会话和角色身份发出以下请求:

GET /v1/director/active-prompt?userId=user-42&conversationId=conversation-8&targetPromptId=lia-character
x-request-id: rp-turn-102:dio-prompt

服务没有有效版本时返回 {"found":false},适配器返回 undefined。有版本时,响应结构如下;哈希必须由实际 UTF-8 文本计算,不能填版本号或占位字符串:

// 教学示例:模拟外部服务响应,不是 Harness 在本地编译角色 Prompt。
const compiledPrompt = "你扮演灰港守卫莉娅,负责守门。保持既有身份;回答用短句,少用比喻。";
const response = {
  found: true,
  sourceVersionId: "lia-version-2",
  changeSetId: "change-101",
  compiledPrompt,
  compiledPromptSha256: createHash("sha256").update(compiledPrompt).digest("hex"),
};
// createHash 来自 node:crypto;实际服务应返回编译后的完整角色文本。

任务终态用于确认处理是否结束,activePrompt 用于取得现在有效的文本。应用会把 compiledPrompt 放到角色提示词位置,保留本轮用户消息。现有 task 与 activePrompt 查询只发送 accept 和追踪头,不转发提交时的用户 Bearer 或 demo token;接入方因此需要分别对齐外部服务的查询鉴权、网络访问与持久化要求。

提交与受理校验 · 有效 Prompt 与任务返回合同 · 请求头与单次 HTTP 超时

Fusion 调用 DIO 时,怎样请求免计费 #

Fusion 的 #253 已合入 fusion-harness,包含它的 c8fc61c86883fb2e9fceefab721b45f0829760f2 于 9 月 24 日 03:16–03:19 完成 Narrative Fusion 生产镜像更新和 rollout。它改变的是提交任务时的请求头,任务输入、受理回执、后台查询及后续读取提示词的步骤不变;普通 main 尚未包含这项改动。合入记录 · 当次部署

例如用户仍发送“从现在起莉娅都用短句回答”,前台模型选中 schedule_dio 后,程序把这句原话提交到 DIO。Fusion 的适配器自动加上下面的请求头,业务不用让模型生成这个标记,也没有另一个按会话开关:

POST /v1/chat
x-dio-skip-billing: true
x-user-id: user-42
x-request-id: rp-turn-101:dio

原请求有用户 Bearer 时继续转发 authorization;Fusion 不再发送 x-dio-demo-token,也没有附加 x-dio-harness-key 或其他 Harness 专用服务凭据。已有入口仍需配置前台控制与 dio skill,并连接 DIO_URL;受理后由后台每秒查询,最长等待 16 分钟。这不会让所有普通 V2 对话自动启动 DIO,也不会因为带了请求头就立即改好角色提示词。调度与轮询 · 请求头及测试

目前确认的是免计费标记已进入这次生产部署的代码;是否真的免扣费,由外部 DIO 的计费判断决定。巡检没有调用真实 DIO 或核对钱包,所以还不能写成“用户已不扣费”。接入方需让 DIO 验证请求确实来自获准的服务,并核对一条实际请求的计费决定和钱包记录;单凭用户可填写的 header 不能证明调用者身份。当前运行镜像也没有再次从集群读回。

有效提示词怎样真正进入 Actor #

下一轮查询得到有效 compiledPrompt 后,入口把它放到请求的 dioCompiledPrompt。随后 Actor 组装器执行 applyDioCompiledPrompt,并把原文放入模板变量 dioCompiledPrompt,再由原有模板展开流程生成 Actor 的实际消息。

组装器按下面顺序寻找角色提示词的位置:

  1. 如果 PromptManager 有且只有一个 name="roleplay" 的提示词,替换它的整个内容,角色和顺序保持不变。
  2. 如果没有 roleplay 提示词,则要求所有提示词合计只有一个 {{getvar::systemPrompt}} 占位,把该占位改为 {{getvar::dioCompiledPrompt}}。
  3. 重复的 roleplay、没有可用位置、或没有 roleplay 却有多个 systemPrompt 占位,均会抛出错误;程序不随意挑一个位置,也不把长期要求追加到整份上下文末尾。

例如,原 Actor 模板为“控制说明 → 角色提示词 → 历史 → 本轮问题”,新一轮变为“控制说明 → DIO 编译后的完整角色提示词 → 历史 → 本轮问题”。这意味着 DIO 交付的是可替换该角色位置的完整编译提示词,不能只交一句“少用比喻”并假定原角色设定仍然保留在这个被替换的位置。

仓库测试已经检查最终 prepared.history 包含 DIO 文本,同时保留控制说明、历史和当前问题。生成这份新文本所需的旧角色资料读取与编译工作,仍由外部 DIO 服务完成。

角色提示词替换规则 · 绑定变量并继续组装 · 最终 Actor 消息与歧义失败测试

如何接入 #

使用 apps/emochi 时,研发在聊天入口实际加载的 config/scenarios/<入口名>.json 中加入下表的 preActorDirector 设置,连接 DIO 服务,再让请求携带前文的账号、聊天和角色资源 ID。Actor 模板要保留一个符合上述规则的角色提示词替换位置。配置修改后,需要重新加载聊天服务才会生效。

接入方要设置的位置 具体设置与作用
应用部署环境 DIO_URL 指向真实 DIO 服务,另需已有 AXON_URL;DIO_TIMEOUT_MS 默认 3,000 毫秒,控制每一次 HTTP 请求,不是整个任务只允许运行 3 秒
业务 Scenario 在实际加载的 config/scenarios/<ID>.json 或既有 AGENT_ROUTER_SCENARIOS_JSON 对应场景配置 preActorDirector.modelConfigId 和非空 skills。前台模型配置必须可用;提供 DIO 依赖后,当前 dispatch 才挂上 schedule_dio 执行器,没有单独的 dio:true 开关
角色正文模板 检查唯一 roleplay 提示词,或唯一 {{getvar::systemPrompt}} 占位;DIO 返回内容才能替换到指定位置
请求身份与授权 按上表传真实账号、聊天、角色 ID;Router 内部凭证和用户授权不要混填。可选 DIO_DIRECTOR_DEMO_SERVICE_TOKEN 由部署方提供,不是用户对话字段
后续生效 后续请求仍经过已启用 DIO 的入口,用相同账号/RP 会话/目标 Prompt 查询。换一个入口或不执行 activePrompt 读取,就不会自动采用

部署字段及校验 · 前台配置格式 · 依赖实例化

文件场景由 HARNESS_ENABLED_SCENARIOS 选择,HARNESS_SCENARIOS_DIR 可改目录;同名场景若又出现在 legacy JSON 中,JSON 会整项覆盖文件。配置在启动时加载,需确认实际加载的是你改过的那份。配置来源和覆盖规则

9 月 22 日主干允许这套前台循环另外显式配置世界书。DIO 继续替换指定角色提示词位置,世界书继续按本轮绑定和选取注入,两条通路各自生效;DIO 任务不会因为同时启用世界书就自动编辑书籍内容或绑定。Story 与 Sumi 仍不接这套前台循环,不能据世界书兼容范围扩大就推断它们也已支持 schedule_dio。当前组合约束 · 世界书和 DIO 读取接线

客户若在仓内二开,可以复用适配器。它是应用源码模块,当前不是 Core Tools 的公共子入口:

// 仓库内代码位置:apps/emochi/tools/dio-skill.ts
const dio = new DioTool(dioServiceUrl, requestTimeoutMs);
const accepted = await dio.schedule({
  actorTurnRequestId: "rp-turn-101",
  userId: "user-42",
  rpConversationId: "conversation-8",
  targetPromptId: "lia-character",
  instruction: "从现在起莉娅都用短句回答,少用比喻。",
  language: "zh",
  userAuthorization: userAuthorizationHeader,
}, signal);

示例中服务地址、超时、授权头和 signal 由接入者提供。适配器派生 dio_conversation-8 作为 DIO 会话,rp-turn-101:dio 作为请求 ID,rp-turn-101:dio:assistant 作为任务消息 ID;收到的受理身份必须与这次提交一致,否则抛错。

自己的聊天后端接入 DioTool 后,在用户明确提交长期修改或主 Agent 选中该动作时调用 schedule,发送“从现在起莉娅都用短句回答”这样的原始要求。受理后用 waitForTerminal 在后台跟踪;以后准备回复时,按同一账号、会话和角色 ID 查询 activePrompt。适配器会检查版本字段和文本哈希,再由业务用完整文本替换原角色设定。响应体不回显账号、会话和角色,所以调用前必须绑定正确身份与服务访问权限。任务尚未完成时,继续使用当时已有的有效设定。

下面演示下一轮怎样把查询结果交给自己的回复模型。dio 是前面创建的适配器;originalCharacterPrompt、controlPrompt、acceptedHistory 和 currentInput 来自现有聊天业务,分别是原角色设定、控制说明、已采用的历史和本轮输入。

// 在下一次 RP 请求准备模型输入时执行,不在 schedule 受理后立即替换。
const active = await dio.activePrompt({
  userId: "user-42",
  rpConversationId: "conversation-8",
  targetPromptId: "lia-character",
  requestId: "rp-turn-102:dio-prompt",
}, signal);
const characterText = active?.compiledPrompt ?? originalCharacterPrompt;
const messages = [
  { role: "system", content: controlPrompt },
  { role: "system", content: characterText },
  ...acceptedHistory,
  { role: "user", content: currentInput },
];
// 将 messages 交给自己原有的回复模型调用;保存本轮正式回复仍走原聊天链路。

示例完成了查询和提示词替换;正式代码还需要按业务规则处理查询异常,不能将错误当作 found:false 丢弃。现成应用的降级规则见下方展开项。为便于追溯某次回复采用了哪份设定,可以把 sourceVersionId / changeSetId / compiledPromptSha256 与请求关联记录;长期提示词的生成和持久保存仍由 DIO 服务负责。

这条接法由研发实现提交时机、后台跟踪、提示词替换和版本记录;也可以把提交代码包装成自己主 Agent 的工具执行器。DioTool 对象不能直接塞进 Core 工具列表期待自动识别。沿用仓内 Actor 适配器的业务则使用前述 dioCompiledPrompt 接线。

适配器的确定性请求 ID 便于关联,但这个仓库没有证明外部服务对重复提交一定幂等。提交超时可能发生在服务受理之后;产品不能仅因没收到回执就承诺“没有修改”或无条件重提。

接口、返回字段及失败边界
方法 接口 关键返回
schedule POST /v1/chat 验证 ok、accepted、会话、Prompt、消息、请求 ID;转换为 {accepted:true,dioConversationId,requestId,taskMessageId,appliesFrom:"next_turn"}
waitForTerminal GET /v1/director/tasks/by-request/{requestId} 任务状态、promptChanged、可选 sourceVersionId / compiledPromptSha256 / 错误码与信息
activePrompt GET /v1/director/active-prompt?userId=…&conversationId=…&targetPromptId=… 没找到返回 undefined;找到则返回版本、变更集、完整编译提示词及 SHA-256

应用后台轮询任务预算为 16 分钟;不是每次 RP 都等 16 分钟,也不是服务处理时效承诺。成功终态仍可能 promptChanged:false,不能据“任务成功”就宣布角色要求已改变。

有效提示词查询或哈希校验失败时,入口记录降级事件,继续使用正常 RP 材料;显式取消仍向外传播。与此不同,已经读到有效内容,但后续发现 Actor 模板缺少或重复替换位置时,组装器会报错,不走上述查询失败降级。接入验收需要同时验证“服务能返回有效内容”和“Actor 模板能够正确采用”。

长期要求不是普通 V2 的持续笔记,不保存在 update_director_state 里,也不自动写世界书或创建独立角色小卡。

受理请求与字段校验 · 终态返回校验 · 读取失败的处理

本次新增开发分支 #303:完整回复后,再判断哪些要求应持续生效 #

本次新增用户说“以后叫我阿宁,回答简短一点”,Actor 先完成当前回复。后台 Jev 再读用户原话和这份完整回复,判断有没有值得跨轮保留的偏好、稳定事实、纠正或撤销;命中才提交 DIO。DIO 可以决定不改,也可以生成一份属于这名用户、这段聊天、这个角色的新正文。以后开始的回合读取最新成功版本,替换原角色正文;已经开始的回合继续用自己开始时选定的版本。

本次新增截至 10 月 19 日 14:51,PR #303 是 Draft、未合入,固定 head 111b91260185bffb4f95dfff2635171a44f46d19。该 head 有 CI 通过与批准记录,但对应 staging job 实际只有镜像构建推送,没有 apply/rollout/readiness,不能写成已部署。外部 DIO 配套服务与迁移仍是接入前提。

顺序 程序拿到什么、做什么 当前回复与后续结果
本次新增回合开始 按账号、RP 会话和角色 Prompt ID 查询有效版本,校验版本 ID、变更集、非空正文和 SHA-256 读到后冻结版本;查询失败且未取消时用基础正文。查询本身有 HTTP 耗时,但不等待尚未完成的新版本生成
本次新增准备模型输入 在本次运行时副本中替换唯一 system 角色正文位置,然后再做 Compact、组装和最终 token 计数 Actor、普通 V2 后台角色定义及本轮重试采用同一正文;不保存或修改多人共用的 Preset
本次新增完整回复结束 只在 status=completed 且不是 partialResponse 时安排独立后台任务 当前结果立即返回,不等待 Jev 判断或 DIO 改写;失败、中断和 auto_reply 建议不触发
本次新增Jev 判断 读取用户原话、完整可见回复、操作类型和请求/消息身份;只返回 none 或 schedule_dio 普通续聊、临时情绪、单轮指令可跳过;长期偏好和稳定事实不要求用户必须说“记住”。Actor 自己编出的内容不能代替用户授权长期修改
本次新增DIO 处理 选中后提交整份结构化材料,按稳定任务 ID 查询终态,核对消息身份 受理不等于完成;成功也可能 promptChanged:false。后台失败不撤销已完成回复
本次新增后续回合开始 再次查询当时最新成功版本 新版本已完成才采用;仍在处理就用已有版本。某轮进行中生成的新版本,不会插入该轮或它的重试

本次新增这里“完整回复结束”的检查来自 Harness 返回结果,代码没有另外读取 Chat Service 的消息落库回执。后台读取完整正文的时机也与普通 V2 六专家后台不同:六专家仍在 Actor 生成时就开始工作;这个候选新增的是回复结束后的独立判断,未替换六专家和 Director。

本次新增候选实际提交的材料,与当前前台方式有什么不同 #

本次新增主线前台 schedule_dio 提交用户原文;#303 后处理把下列对象序列化成 JSON 字符串,放入 DIO 请求的 question。用户原话和 Actor 回复分别保留,模型不能把两者混成同一人的要求。以下是字段示例:

本次新增
{
  "original_user_input": "以后叫我阿宁,回答简短一点。",
  "visible_actor_output": "莉娅点点头:好,阿宁。",
  "operation": "chat",
  "request_id": "rp-turn-101",
  "user_id": "user-42",
  "conversation_id": "conversation-8",
  "target_prompt_id": "lia-character",
  "source_message_id": "user-message-101",
  "assistant_message_id": "assistant-message-101"
}

本次新增这些 ID 仍由聊天后端提供,含义见本页开头;两个消息 ID 有值才发送。operation 区分 chat、continue、regenerate、edit_regenerate。候选只使用最终可见正文,不交隐藏推理或中断的部分正文;DIO 原角色资料如何取得、如何生成和发布版本,仍由外部服务实现。判断输入和实际提交 · 完整回复门槛与后台调度

本次新增候选怎样配置、如何确认采用,以及仍缺哪些外部保障含 9 处更新

本次新增只有在 #303 候选版本中,研发才可以在聊天入口 JSON 顶层添加 postTurnDio。省略或 enabled:false 时不增加这套 Jev/DIO 调用。下面 ID 是待研发创建并确认的配置引用,不能原样用于生产:

本次新增
{
  "modelConfigRef": "example-actor-dio",
  "presetRef": "example-actor-dio-preset",
  "postTurnDio": {
    "enabled": true,
    "jevModelConfigId": "example-dio-trigger-jev",
    "promptManagerId": "example-dio-trigger-policy",
    "timeoutMs": 3000
  }
}

本次新增modelConfigRef 是回复模型配置,必须实际关联 presetRef 指定的 Actor 模板。jevModelConfigId 是单独的 Kaon Jev 模型配置,要有明确窗口;promptManagerId 指向判断策略,必须有唯一非空的 dio_trigger 条目。策略按语言展开并记录 hash。timeoutMs 默认 3,000 ms、范围 1–30,000,控制判断阶段;提交和等待 DIO 终态另属最长 16 分钟的后台任务。服务需配置 AXON_URL 与 DIO_URL,这条候选不允许与 Sumi 配在同一个入口。

本次新增模板须有唯一 system roleplay 条目,或唯一旧式 system {{getvar::systemPrompt}} 位置。候选拒绝非 system、重复位置和其他位置残留的原角色正文 getter,避免新旧角色文字同时生效。替换发生在 Compact 之前,但现有角色精简兜底不能自动识别 dioCompiledPrompt getter;过长的新正文仍可能超预算失败,不能承诺自动压短。

本次新增Jev 超时、策略不可用、答案非法或超预算都会记为判断失败,不伪装成正常 none,也不提交 DIO。回复完成后的客户端断开不取消已安排的后台;后台自己的超时/失败仍会结束任务。开启此后处理时,程序移除同一轮旧前台 schedule_dio 入口,避免两个触发者。

本次新增验证要分别看到 dio_active_prompt_loaded(读取)、dio_post_turn_selected(判断)、dio_task_succeeded(处理完成)以及 dio_actor_prompt_dispatched(实际派发)。最后一项记录所用版本、角色正文 hash、Actor 消息 hash 和完整上游 body hash;前三项成功不能代替“真正发给回复模型”。

本次新增稳定 request/task/message ID 便于防重,但 Harness 的 runner 只有进程内 Set/Promise,不提供跨 Pod 持久队列和会话串行锁。外部 DIO 还须提供会话内串行、持久幂等、未决执行保护、编译及版本发布。作者报告配套服务 PR、数据库迁移和隔离环境问题仍待完成;本轮没有审查第三仓或验证这些环境故障。候选 job:只有 build/push

本次新增配置与决策校验 · 冻结版本读取 · 角色正文替换规则 · 实际派发记录 · 进程内 runner

Fusion 的 Jev 候选:如何避免同一要求重复提交 #

截至 10 月 13 日,PR #255 仍未合入目标分支 fusion-harness,当前核对的候选为 e8b003cc1e64541803a60b3e22c30e558747b7f1。前台模型会收到本轮已经发生的工具调用和回执;提示词要求同一原始用户请求最多选择一次 schedule_dio,无论先前成功还是失败,都先看轨迹再决定下一步。只有用户明确要求长期改写角色、世界、风格或扮演方式时才使用它,普通的本轮剧情动作不会因此成为长期设定修改。

例如用户说“以后莉娅都用短句”,DIO 返回受理回执后,前台继续完成这轮回复,不等待后台编译,也不轮询改写结果;当轮 Actor 仍使用进入循环前已经准备好的提示词。后台成功后,后续请求通过前文的 activePrompt 查询取得并采用新版本。任务受理、处理成功和下一轮真正读取是三步,不能用一个 accepted 回执代替全部结果。

程序在一次提交被受理后会记录 dioScheduled,拒绝再次调度;但提交失败时这个标记没有置上,代码仍可能接受下一次尝试。因此候选要求“本轮只选一次”的范围比成功去重更广,失败后的限次仍依赖模型遵守提示词,没有一个统计所有失败尝试的硬计数器。这段提示和成功去重在 10 月 9 日基线已经存在,本次只是更新候选源码与边界,不能再算首次新增。主线仍按本页前面独立的接法运行。固定模型指令 · 循环中受理成功后的去重

原子能力 / 应用接口

下一句建议:给用户三个可选择的回应

守卫问“手令呢?”之后,页面可以给用户三个回应建议:“我翻找随身的手令”“我问他去哪里补办”“我先退到旁边等候”。Auto Reply 负责生成这些候选,用户选择或修改后再发送;角色此时不会再回复三次,程序也不会替用户自动发送。

普通 Agent V2 和 Story 都已实现 Auto Reply,通过单独的 AUTO_REPLY 请求调用。这部分代码属于 Harness 应用,没有作为 @flowgpt/agent-core-tools 的独立工具导出,也不在 Orchestrator 默认选择的专家列表里。单独复用时,需要集成应用函数,并提供模型、提示词和它所需的状态/消息查询。

聊天已经由后端经 Agent Router 发给 apps/emochi 时,研发先配置建议模型,再让后端在角色回复后另发一次建议请求。前端负责展示候选,并把用户选中的一句按正常聊天发送;按钮和输入框由产品自行实现。自己的后端若直接调用模型,则按本页后半段集成应用函数及依赖,AUTO_REPLY 请求类型本身不会增加这些功能。

调用输入与普通V2实现 · Story实现 · 产品请求分流和返回

用户看到什么,业务拿回什么 #

角色回复生成后,后端用这条消息的 assistantMessageId 请求建议。Harness 找到对应对话,调用建议模型,把结果解析成三条不同的短文本,再交给页面显示。

产品可以让用户点按钮请求建议,也可以在正文结束后自动请求;随后把候选展示成选项或填进输入框,等待用户选择并发送。这是与普通聊天分开的请求,主 Agent 无需选择 auto_reply 工具,普通回复也不会默认附带三条建议。Story 还要求先把目标正文保存到聊天服务。

用同一条消息看输入(教学例子,下面是函数使用的消息材料,不是完整 Router 请求):

{
  "assistantMessageId": "assistant-7",
  "characterName": "城门守卫",
  "characterDescription": "负责核验入城凭证,不知道用户是否携带手令。",
  "language": "zh-CN",
  "messages": [
    {"id":"user-7","role":"user","content":"我把铜钥匙递给守卫,问能否进城。"},
    {"id":"assistant-7","role":"assistant","content":"守卫看了看钥匙,伸出手:手令呢?"}
  ]
}

普通 V2 会再取同一回复 ID 的 auto_reply_guidance,例如“用户尚未证明有手令,保留询问和退出的选择”(示例文字,实际由状态服务返回)。Story 会再取 assistant-7 在聊天库里的正式正文;即使消息材料里误写“已经获准进城”,也以查回的“手令呢?”为准。两条路径补的材料不同,不能只交一句用户输入就得到等价结果。普通 V2 的上下文选取 · Story 的权威正文读取

应用函数返回:

{
  "options": [
    "我翻找随身的手令。",
    "如果没带手令,我该去哪里补办?",
    "我先退到旁边等候。"
  ],
  "usage": {"inputTokens": 800, "outputTokens": 60, "totalTokens": 860}
}

这里是结构示例,具体文案与 token 数由模型实际返回。现成 Agent Router 把三个选项转为单个结果中的编号文本:

1: 我翻找随身的手令。
2: 如果没带手令,我该去哪里补办?
3: 我先退到旁边等候。

后端调用 AgentService.chat 后,先检查 response.outcome.case。值为 result 时,从 response.outcome.value.choices[0].content 取编号文字,从 value.usage 取用量;值为 error 时按错误处理。Router 返回的是一个 choice,里面包含三条建议,应用函数原来的 options 数组已转成这段文字。页面要展示三个按钮,需要先解析编号;使用 chatStream 的客户端则沿用流事件协议读取结果。Router 的实际响应包装 · 注册的聊天接口

用户选中、编辑并发送后,聊天后端才保存那句话并发起下一轮。在此之前,产品可以把候选显示为按钮、填入输入框,也可以自行保存建议记录;Auto Reply 本身只生成候选,不写用户聊天,不更新 V2 状态,也不结算 Story 剧情。普通 V2 可能留下建议调试记录,它们仍属于日志。

例如用户最终发送第二条“如果没带手令,我该去哪里补办?”,下一轮 Agent 应收到这句真实用户消息,而不是整个 options 数组;未选的“翻找手令”和“退到旁边”没有发生。Auto Reply 也不负责把这次选择回写成已拥有手令、已移动位置或已完成剧情目标。

调试记录与options返回 · 编号文本、空artifacts与stateVersion0

普通 Agent V2 怎样生成 #

步骤 具体做什么 输入/结果
1. 定位那一条回复 在请求给出的非空 user/assistant 消息里找到目标 assistant ID 取该回复及它前面最多 6 条可见消息;之后已经发生的消息不会加入此次建议
2. 取得对应轮次的指导材料 调用 Axon roleplay.state.get,在 pending 或 planning_settlements 中查找同一个 source_message_id 必须有非空 auto_reply_guidance;不能随便拿当前最新 state 顶替
3. 准备模型输入 角色名称/描述、后端在 turn_context.language 中指定的输出语言、最近用户输入、上述指导文字、最近可见对话 系统提示词来自单独 Auto Reply ModelConfig 关联的 PromptManager
4. 生成候选 调用模型,要求三个不同方向 1 可以顺着当前剧情,2 关注情绪/关系/好奇,3 保留其他或中立方向;这是提示词指导,不是三个硬编码答案
5. 解析和检查 清理编号/空白、去重、最多取 3 条、每条最多 160 字符;部分语言有文字检查 凑足 3 条且通过检查才返回,否则尝试重新生成

等待的是什么状态 #

普通 V2 的后台开始工作时,会把这一轮开始时读到的状态及其版本,连同目标回复 ID、轮次和阶段,通过 markPlanning 发给 Axon。Auto Reply 随后读取状态接口里与这个回复 ID 匹配的 auto_reply_guidance。

Auto Reply 要等到这条回复对应的 auto_reply_guidance 可读。记录可能在 pending,也可能已经进入 planning_settlements;六位专家和 Director 可以仍在工作。指导文字由外部状态服务提供,Harness 在这里读取已有内容,两个仓库未包含这段文字的转换算法。

默认最多等待窗口为 30,000ms,两次读取之间等 250ms;配置范围 0–120,000ms。设为 0 仍会读取一次,不表示完全跳过检查。该数值控制查快照的轮询窗口,不是包括网络请求与模型生成的完整响应时限。

后台单独写入阶段记录,写入失败仍允许 RP 正文继续。因此角色回复成功后,建议也可能因指导资料尚未就绪而失败。当前实现会返回这个失败,不会以三条固定建议替代。

轮初快照随阶段写入 · mark_planning传输字段 · 按回复ID轮询指导

Story 怎样生成 #

Story 根据聊天服务已保存的目标正文生成建议,不读取普通 V2 的 pending/planning_settlements,也无需等待那份后台快照。

步骤 具体做什么 业务意义
1. 检查回复锚点 请求中必须有且只有一条目标 ID 的 assistant 消息,前面还要有用户消息 防止把其他轮次的结果混进建议
2. 读取真正保存的正文 用后端核验过的登录账号 ID、当前聊天 ID 和目标回复 ID 调 Axon conversationMessage 正文以聊天服务保存的内容为准,不以请求中可能过时或截断的文本为准
3. 组织上下文 使用目标回复前最多 6 条非空可见消息,加入查回的完整正文、角色信息和指定语言 目标回复之后的消息不加入;不读取 Story 整个世界/叙事状态快照
4. 生成三种选择 提示词要求三个适合当前时刻的不同策略,允许暂停、澄清或换方向 不固定“选项1推进、2情绪、3其他”的分槽,也不替用户宣布行动成功或其他角色反应
5. 严格检查结果 JSON 中必须恰好 3 条,非空、不同、每条不超过 160 字符,符合相关语言文字要求 失败时可带格式修正要求再次调用;不把超长条目直接截断采用

例如请求里缓存的是“守卫让你通过”,但聊天服务保存的正式正文是“守卫伸手索要手令”,Story 会按后者生成建议。如果正式正文尚未保存、查不到、角色不对或为空,流程失败;它不会退回请求里的旧文本继续生成,也没有在此实现等待正文落库的轮询。

直接调用源码函数时,可以额外传 pendingStage,把尚未完成阶段的建议交给模型;提示词要求将其视为建议而非已发生事实。当前统一 Router 没有传入这个字段,所以默认 Story Auto Reply 输入中没有这份剧情计划。

唯一锚点与正式正文读取 · 输入与用户自主权要求 · 严格结果解析

如何在现成产品里开启和调用 #

先配置专用模型和提示词 #

前提是这条聊天入口本身已经能正常运行普通 V2 或 Story。研发修改对应的 config/scenarios/<入口名>.json,在现有 agenticV2.modelConfigs 中补 autoReply;普通 V2 可同时调整 autoReplyWaitMs。部署使用的目录由 HARNESS_SCENARIOS_DIR 指定,使用旧 AGENT_ROUTER_SCENARIOS_JSON 的入口则修改其中同名对象。以下是要合入的字段片段:

{
  "agenticV2": {
    "modelConfigs": {
      "autoReply": "your-auto-reply-model-config-id"
    },
    "autoReplyWaitMs": 30000
  }
}

把上面的字段合入现有配置,保留 actor、orchestrator、specialists 和 director。Router 按 autoReply 的 ModelConfig 选择建议模型;缺少这项配置就拒绝请求,不会改用 Actor 模型。

这个 ModelConfig 关联的 PromptManager 需要一段名为 auto_reply 的系统提示词,其中必须有 {{getvar::language}}。程序渲染时填入输出语言和 characterName,缺少模板或语言变量就会失败。提示词保存在关联的 PromptManager 中,Scenario 只引用模型配置 ID。

研发先在 Axon 提供的模型配置/PromptManager 中创建或确认 your-auto-reply-model-config-id,再把这个 ID 填进 JSON。提示词要求模型依据角色刚说的话,给出指定语言的三条用户回应建议;两种应用实现分别补入所需材料和格式要求。Scenario 在服务启动时加载,改完后需要重启或重新发布,并确认文件在启用列表内。同名旧 JSON 环境配置会整份覆盖文件,也需要一并核对。启动时读取及覆盖规则

Story 仍通过同一个 agenticV2.modelConfigs.autoReply 指定建议模型;程序根据场景是否存在 storyV1 选择 Story 实现。autoReplyWaitMs 虽会作为通用输入传入,但 Story 当前路径不使用这个等待值。

autoReply模型字段读取 · 等待范围校验 · auto_reply模板要求 · 普通V2/Story分流

再由业务发起 AUTO_REPLY 请求 #

后端沿用向 Agent Router 发送 ChatRequest 的代码,将这次请求的 chatType 设为 AUTO_REPLY,发给已接通的 AgentService.chat 或 chatStream。它仍走原聊天接口,既不新增 /auto_reply HTTP 地址,也不把这个值写进用户文本。仓库由 adapters/agent-router/dispatch.ts 的 executeAgenticAutoReplyRequest 处理,所需字段如下:

字段 谁提供、用于什么 教学例值/检查条件
conversationId/promptId 业务提供已有会话和角色/作品身份;Router 用 promptId 读取角色名称与简介 chat-1 / character-guard。普通路径只会得到这次读取的名称与简介,不自动加入角色全部定义或整本世界书
extensions.scenario_id 填服务已加载且配置了 autoReply 的入口名;它对应 config/scenarios/<入口名>.json 或同名环境配置 your-enabled-v2-or-story-scenario;场景要能解析出专用建议模型
extensions.turn_context.user_id 上游认证后得到的用户身份;不能由不可信前端任意代填 当前已登录用户的真实 ID,用于读取其状态/消息
extensions.turn_context.assistant_message_id 为哪条角色回复生成建议,必须与 messages 内目标 ID 一致 assistant-7;不是本次新建的建议请求 ID,也不能填写最新用户消息 ID
extensions.turn_context.language 聊天后端明确指定本次建议要用的语言;不是让模型从用户上一句猜语言 zh-CN;即使角色设定或上一句话是英文,也按指定语言生成
messages 业务提供带 ID 和角色的消息序列,含目标 assistant 消息及此前用户内容 例如上面的 user-7/assistant-7;真实 Router 使用其协议消息类型,进入生成函数后才是 {id,role,content}
modelConfigId、项目/协议字段 沿用已接通的 Agent Router 请求契约,不是直接把建议模型 ID 当作任意上游模型绕过场景 与正常有效请求一起保留;实际建议模型由 agenticV2.modelConfigs.autoReply 确定

下例修改一份已有且有效的 ChatRequest。后端已准备好原请求 request 和登录用户的 userId;其他项目与协议字段沿用原请求:

import { ChatType } from '@flowgpt/agent-router-sdk/agent_pb.js';

request.chatType = ChatType.AUTO_REPLY;
request.extensions = {
  ...request.extensions,
  scenario_id: 'your-enabled-v2-or-story-scenario',
  turn_context: {
    user_id: userId,
    model_alias: 'your-model-alias',
    language: 'zh-CN',
    assistant_message_id: 'assistant-7',
    extra_set_vars: {},
    template_set_vars: {},
  },
};
// request.messages 需要包含目标 assistant-7 和它之前的用户消息。
// 通过现有 Agent Router client 发给 Harness;不要再发一条普通聊天来代替。

Router 生成编号建议并返回 usage 后就结束这次请求,不再生成 Actor 正文或执行其后的记忆写入。上游仍按原聊天接口完成鉴权、提供消息和展示结果。Sumi 拒绝这个 auto_reply 请求,使用 Chat Service 自己的独立建议流程。

后端用刚保存或正在展示的角色消息 ID 作为 assistant-7,前端也按同一个 ID 显示结果。用户切换聊天或继续发送后,晚到的建议仍属于原回复。普通 V2 指导尚未可读、Story 正文尚未保存或候选未通过检查时,接口会返回失败;页面可以暂不显示建议,并按错误决定是否重试,接口本身不补固定选项。

真实AUTO_REPLY请求构造示例 · 提前返回分支 · Sumi调用边界

自建 Agent 想复用这一项,需要接什么 #

普通 V2 的源码函数是 generateAgenticAutoReplies,Story 的是 generateStoryAutoReplies。自己的后端需要集成应用源码,并提供下表依赖;已经使用仓库产品的后端可以直接调用前面的 Router,它会准备这些材料。这两个函数没有单独的公共工具包安装入口。

接入项 你需要提供的具体东西 谁会用它
执行身份 必填 requestId 当前建议调用、parentRequestId 关联调用;userId / conversationId / promptId / assistantMessageId / scenarioId 分别是用户、会话、角色、被建议的回复与运行场景 用于查询、调用追踪和结果归属。Router 当前将 requestId 同时作为 parentRequestId;自行封装时应保持关联清楚
模型与语言 必填 modelConfigId / language,以及 model.complete 适配器;可选 temperature 建议专用模型接收一条 system 岗位提示词和一条拼好的 user 材料,返回三条候选,不调用 Actor 来再写一轮正文
角色与消息 必填 characterName / characterDescription / messages;直接调用函数时由你读数据,函数不代替 Router 获取角色 Prompt 作为建议模型的具体场景输入。普通 V2 的 messages 提供目标回复文字;Story 的目标文字再由正式消息读取覆盖
Axon 读取依赖 普通 V2:能查询匹配回复的指导状态;Story:能查询已保存消息;两者:能解析 Auto Reply ModelConfig 的 PromptManager 获取前文解释的额外材料与系统提示词,不能以空对象代替 Axon 来调用
等待与取消 waitMs 在通用输入契约中必填;普通路径控制等待指导快照,Story 不使用;另传整项 signal 例如 waitMs 为 30000。只配置该数值没有控制完整模型生成耗时;signal 才负责调用方总取消
用量与观察 可选 requireUsage / tolerateInvalidUsage / trace;依赖中可选 observeAutoReply。要求 usage 而模型未给时,还需要 Axon token 计数 费用统计和日志。它们不承担保存用户选择或推进剧情

函数返回 {options, usage?} 后,产品可自行保存建议记录。真正进入下一轮聊天的是用户确认发送的那一句,由正常聊天流程保存并生成回复;三条候选不会自动写入下一轮状态。实际函数契约 · Router 如何填入这些材料

单独二开、返回校验、重试、费用与失败细节

普通函数位于 apps/emochi/planning/auto-reply.ts,Story 函数位于 apps/emochi/story/auto-reply.ts;依赖对象为 {axon, model, observeAutoReply?}。下表说明前述接法里的校验与失败规则。

参数或行为 普通 Agent V2 Story
默认温度 应用请求未指定时,显式覆盖为 0.7 未指定时不覆盖,让 ModelConfig 决定
每次模型调用超时 180,000ms 180,000ms
本地生成尝试 最多 3 次;取消、内容过滤或已尝试模型恢复等情况可能提前结束 最多 3 次;无效结构会把先前输出和修正要求带到下一次;同样可能提前结束
普通输出解析 支持数组、options 对象及 {content} 选项;去重、清理、截为每条最多160字符,再取前三条 必须恰好3条;超长、空、重复即无效;不会截断超长内容后当成功
语言检查 中文要求含汉字,日文含假名,韩文含韩文;其他语言当前没有同等文字校验 同类检查;不等于完整语义语言质量验证
usage Router 要求 usage;上游未提供时用 token 计数补算;多次模型结果可累计 同样累计;缺失时计数补算,计数失败可向上抛错
保存 可写 best-effort 调试节点与日志;不写聊天/V2事实状态 完成观察日志;不写聊天/Story状态

最多 3 次指 Auto Reply 自己的生成循环。如果后端的模型适配器还配置了独立恢复,它可能在一次调用内继续尝试,因此总网络请求数可能超过 3 次。

失败 用户业务如何理解 当前处理
场景未配置 autoReply 模型,或没传目标回复 ID 接入材料不完整 Router agent.invalid_argument
角色 Prompt 不存在或没有名称 没有足够角色材料生成 router.unavailable,可重试
普通 V2 指导未就绪/对应用户或回复文字缺失 暂不能为这条回复提供建议 turn_start_snapshot_not_ready;Router 映射为可重试 router.unavailable
Story 正式正文未保存或查不到 缺少权威依据 auto_reply_generation_failed;不回退请求侧正文,不等旧状态
三条结果仍无法通过检查 本次没有有效建议 agentic_auto_reply.failed;不补固定兜底文案
用户取消 不再继续该请求 取消向依赖调用传播;业务不用显示过期建议

autoReplyWaitMs=30000 控制普通 V2 等待指导快照的时间。网络请求、单次模型调用以及 Router/Story 请求总超时还有各自的限制,整体返回可能超过 30 秒。

此外,main 里还保留 Pioneer API 包装:它先查已保存最近历史,支持请求体 enabled,返回 {enabled, options, fallback:false, parentRequestId, usage?},有自己的 JWT/来源和模型配置。这个入口的字段不能与统一 Router 混用;统一 Router 没有要求请求体 enabled:true。本能力页以 Router 的普通 V2/Story 接法为主。

普通重试与usage · 普通解析和语言检查 · Story重试和修正 · Pioneer独立包装 · SDK公共导出范围 · 工具包公共导出范围

二开验收应看到的结果 #

先保存一条角色回复,再对它请求建议:得到三个文本,并确认聊天里没有因此多出用户消息。接着让用户选择其中一条,验证它才按正常聊天入口成为下一轮输入。

普通 V2 再测同一回复指导尚未就绪、目标回复之后已有新消息这两种情况;Story 再测请求侧旧正文与已保存正文不一致、正式正文未保存这两种情况。检查候选建议依据了正确的一轮,且失败时没有从其他轮次捡一个状态继续。

原有源码引用固定在 Harness fa41d220d48327e58d994f936517b23f2f15f658,补充的接口和配置细节按 main ccaaa46e6fd16544481284bb1388fc78cc177009 核对。文中分别注明了应用函数、公共包和产品接口的范围;各线上入口是否开启,仍以实际配置为准。

业务接入 / 接入步骤与完整案例

业务如何接入原子能力

10/19 更新 · 本章 5 处从第一处开始看 →

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

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

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

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

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

公共 Agent 与直调示例 · 应用世界书配置入口

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

研发修改了某个聊天入口的 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 覆盖,以及整份配置与各入口的哈希,便于确认到底用了哪一版。选择、优先级和实际加载 · 加载来源与指纹

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

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

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

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

记忆失败配置解析 · Sumi 图片开关解析 · Sumi 接收模型选择

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

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

因此联调时,管理端保存成功后,如果马上发请求仍读到旧的角色或模型配置,要分别检查保存结果、当前进程缓存和实际聊天入口;这不是世界书关联的永久固定,也不是聊天状态丢失。缓存过期后程序重新请求 Axon。它只存于当前进程,不能代替数据库,也不能保证不同副本在同一毫秒拿到一致的新配置。缓存覆盖的资料与默认时长 · 过期、大小和淘汰处理

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

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

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

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

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

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

  1. 运营按 世界书原生格式 准备条目并保存,获得真实的 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。
{
  "worldbook": {
    "tenantId": "your-tenant",
    "strategy": "rules",
    "tokenBudget": 2400
  }
}

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

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

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

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

配置校验与产品组合 · 每轮身份检查与书籍解析 · 条目选择输入

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

步骤 你的后端提交什么 拿回来什么 接下来做什么
管理资料 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 请求和返回样例均在 世界书,组装代码在 上下文组装。客户端默认每次调用 30 秒,支持单次超时与取消,不自动缓存或重试;网络失败时仍须核对远端是否已经写入。REST 的 tenant_id 是保存和读取同一批世界书的分组编号;创建书籍、绑定角色和选择条目必须使用对应的同一个值。已有书籍沿用创建时的值,由接入研发提供,不能让聊天用户随意切换。你的后端或网关还需核验登录用户能否使用这些书籍;填对 tenant_id 本身不等于通过用户认证。

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

世界书 HTTP 接口 · SDK 消息放置函数

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

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

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

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

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

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

展开调用片段、输入准备与失败处理

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

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

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 秒字段的作用范围见 分析工具的超时规则。仓库提供的 完整直调示例 使用假模型,适合验证接线与返回处理,实际模型质量要另外验证。自定义材料编译入口

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

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

使用默认 RP 上下文与 Pi Agent 时,可复用 /pi 包装器:

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 包装对象直接当成所有运行时通用格式;可参照 快慢运行时完整示例。不同工具之间存在依赖时,先完成前一项,再把结果交给后一项。

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

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

Pi 包装的参数检查与结果回传 · 主 Agent 真实工具列表

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

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

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

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

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

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

业务接入 / 公共 SDK

编排与扩展:做自己的 Agent、工具循环和快慢协作

10/19 更新 · 本章 26 处从第一处开始看 →

如果你已有自己的聊天后端,希望让模型调用工具后再回答,或者一边生成当前回复、一边在后台分析剧情,可以使用这一页介绍的 SDK。你决定模型的任务和可用工具,SDK 负责执行模型与工具之间的调用,结果仍交给你的业务代码处理。

研发需要修改原来的请求处理代码,在收到消息、读取聊天记录之后,调用下面的 SDK 对象,并提供模型客户端、数据库读写和工具函数。参数在 TypeScript/JavaScript 代码中传入。普通 V2 的六位专家、Director 和 Story 的剧情策略属于另外的应用实现,需要使用那些产品时,应查看对应产品页。

三个可以单独使用的公共入口 #

入口 你提供什么 程序实际做什么 得到什么
Agent<TInput, TResult>:让一个模型在工具之间选择 研发写 prepare(input):从业务输入准备模型、初始消息和可用工具(Pi options),给出本次任务 prompt,再写 result 从结束后的消息中取业务需要的内容 每次 run 新建一个 Pi Agent,执行对话/工具循环,传递取消 你在 result 中选择的结果,例如最终回答文字;没有默认状态写入
SlowTurnRuntime:单独运行一次后台分析 后端已取出的聊天、本轮问题和状态;分析模型、任务提示词、允许的工具、调用额度,以及状态读写代码 运行受限制的模型—工具循环,可等待完成 final 是最终模型响应,toolResults 是工具回执;另返回调用量与状态保存结果。业务代码继续采用这些内容
FastSlowRuntime:同时写当前回复、分析后续状态 正文模型调用代码+上述慢路参数+绑定当前聊天的状态读写代码 先读同一份状态并冻结本轮材料,再启动慢路及快路 fast 交给聊天展示;slow 交给后台结果处理;另有起始状态快照和取消函数 cancel

Agent 已经支持让模型选择工具、读取执行结果,再决定下一步。普通 V2 使用的是应用自己实现的两阶段调度,两种实现各自独立。

本次更新这三个对象都从 @flowgpt/roleplay-harness 导入。Actor、应用协调器和 Profile 节点执行器位于仓库的 apps/emochi,没有随 SDK 一起导出。SDK 要求 Node.js ≥22,发布到需要访问权限的 GitHub Packages。10 月 19 日核对页面仍显示最新 SDK 0.6.0,没有观察到新包发布;0.4.0 和 0.5.0 已于 10 月 8 日发布。原生 Pi 慢任务接法已随 #244 合入并进入 0.5.0,0.6.0 继续包含;0.6.0 还新增可独立使用的世界书 HTTP 客户端。Core Tools 0.2.3 沿用 10 月 13 日已核的发布记录,本轮未重新打开其独立 release 页;它是另一份工具包,包含 Story Omen 相关工具。

本次更新研发可以只从 @flowgpt/roleplay-harness/worldbook 导入 WorldbookClient,在自己的模型调用前读取设定;不需要采用上面三个运行时。客户端返回原文、位置与选择诊断,业务自己将原文放入模型输入,具体请求与示例见 世界书独立 SDK 接法。这些发布记录证明包已发出,不证明你的业务已安装、已配置或完成生产联调。SDK 0.6.0 标签对应 5e7c191;10 月 19 日 main 已到 f9b26a9。标签之后新增的应用逻辑要按实际服务版本采用,不能因为主线更新,就算进已经发布的 SDK。

SDK 0.4.0 · SDK 0.5.0 · SDK 0.6.0 · 0.6.0 成功发布运行 · Core Tools 0.2.3

通用 Agent 的 prepare/run · 独立慢路实际循环 · 读取状态与启动快慢两路

实际公开导出 · 包范围、运行环境与发布目标

代码示例:怎样运行回复和后台处理 #

下面的例子让守卫先回复用户,同时在后台检查剧情连续性。示例中的模型、存储和检查函数,需要由研发接到自己的服务:

示例变量 研发具体接什么;材料从哪里来
replyModel/analysisModel 连接自己的模型服务,实现 complete(request, signal);一个用于正文,一个用于分析。modelConfigId 是交给这个适配器识别的配置名,需要由它解析成真实模型与参数
scopedStateStore 登录结果确定真人账号,例如 user-42;聊天记录确定会话,例如 conversation-8。后端先绑定这两个范围,再提供 get 读取和 compareAndSet 写入;后者要在旧版本仍匹配时才写,防止旧任务覆盖新结果
registeredTools 本次分析允许调用的名称、用途、参数格式与实际函数。例如要用人物分析,研发导入分析工具并适配执行接口;空名单就只让慢路模型分析文字
validateStateProposal 你写的检查函数:从模型最终文字和工具回执中选出允许保存的内容,返回 {state: "要保存的文字"} 或 undefined;不能把任意模型输出直接当成已确认事实

发起调用时,后端把用户刚发的话填入 input,把已保存的对话填入 history。sourceMessageId 填这条用户消息的 ID,sourceTurn 填业务维护的逻辑轮序号,requestId 用于追踪这次生成。下面的 ID 和轮号都是例值,实际请求应使用同一段聊天中的真实数据。

import { FastSlowRuntime } from '@flowgpt/roleplay-harness';

const runtime = new FastSlowRuntime({
  fast: { model: replyModel, modelConfigId: 'reply-config' },
  slow: {
    model: analysisModel, modelConfigId: 'analysis-config',
    prompt: '检查连续性;把已确认事实与后续建议分开。',
    capabilities: registeredTools,
    state: scopedStateStore,
    prepareCommit: (final, results, context) =>
      validateStateProposal(final, results, context),
  },
});

const turn = await runtime.run({ context: {
  requestId: 'turn-2', sourceTurn: 2, sourceMessageId: 'user-message-2',
  language: 'zh', input: '我递出铜钥匙。',
  history: [{ role: 'assistant', content: '莉娅站在城门旁,等你归还钥匙。' }],
}});
const reply = await turn.fast;    // reply.content 交给自己的聊天业务
const background = await turn.slow; // 检查 status 和 stateOutcome

该例使用 run(),返回完整快路结果。若前端需要流式正文,改用 stream() 并提供真实流式快路执行器。validateStateProposal 只能返回符合契约的候选或 undefined,不能直接返回任意数据库对象。复用 runtime 实例时,必须保证其状态存储仍指向正确的用户/聊天范围,不能把绑定某一段聊天的实例拿去处理所有用户;服务关闭时调用 shutdown(),并处理尚未完成任务的结果。

快路完成后,reply.content 中会有角色台词,例如“莉娅接过钥匙:手令呢?”。你原有的聊天代码负责展示和保存这句话。后台稍后完成,background.final.content 中可能包含连续性建议,由检查函数决定保存哪些内容。只有 stateOutcome 返回 committed,才能确认新状态已经提交,后续请求重新读取后才能使用;已经发出的台词不会因此重写。示例中的台词和建议用于说明两份结果的用途,真实文字由模型生成。

模型适配器实现 complete(request, signal),返回 content、toolCalls、模型身份和所需 usage;状态仓库提供 get / compareAndSet。仓库的完整示例连同假模型、工具适配与存储实现可以直接查看并运行,示例里的固定文本不代表真实模型质量。

完整工具接线与快慢调用 · 上下文与状态仓库示例 · 通用 Agent 的 prepare 与 result 示例

主模型实际收到什么 #

SlowTurnRuntime 给主模型的消息依次是:你配置的系统提示词、已保存状态的 system 消息、传入的历史、本轮 user 输入;提供给模型的工具列表来自你传入的 capabilities。没有自动读取业务数据库、世界书或角色卡的步骤。

模型要扮演莉娅,还需要读到她的角色设定。上面的代码只传递了历史和状态;研发需要另外读取“莉娅是城门守卫”等角色文字,放进慢路的 prompt 或模型消息。快路需要的角色资料、世界书也由自己的执行器或模型适配代码加入。这个通用接口不根据角色 ID 查询角色卡。

每次模型返回工具请求,程序解析参数、验证这一批请求,再调用已注册执行器。结果回到模型消息中,模型可以继续选择工具或输出最终内容。调用方必须解释 final.content 与 toolResults,不能把任意文字直接当作一份合格的业务状态。

一次选择多个工具时,谁先执行 #

同一次模型响应里的工具请求会并行执行。这一批开始前,程序先检查全部工具名、调用 ID、参数和数量;有一项不合法,整批都不会开始。合法的一批执行完后,程序才把结果按工具请求顺序交回模型,让它决定下一步。

例如接入者自己提供了“查询城门规则”和“查询守卫资料”两个工具,它们可以在同一批运行;如果还要“根据查到的规则修改守卫资料”,这个修改必须等下一次模型决策再调用。每个工具拿到的 dependencyResults 只有此前已经完整收集的批次结果,没有同批另一个工具刚查到的资料,也没有自动按依赖排序的步骤。

当前情况 程序怎样处理 接入方怎样使用
模型一次请求 2 个独立查询 两个查询并行;整批完成后都回给模型 模型下一步可以综合两份资料
默认上限为 4,模型一次请求 5 个工具 整批校验失败,慢路返回失败;不会自动分成 4+1 排队 在工具政策中约束调用数量,并处理失败结果
同批一个工具抛异常 慢路失败并发出取消;其他已启动工具可能已产生外部效果 不自动重跑整批;先查已发生的写入,依靠业务幂等键避免重复

toolsCalled 和 toolResults 是已完整收集的批次记录。一个并行批次中途失败时,已执行的同批工具不一定出现在这两个数组里;有写入行为的执行器需要自己的操作记录,不能仅凭“返回数组里没有它”判断没有执行。

整批校验与前序结果 · 并行执行、结果收集与异常中止 · 超出数量限制直接失败

SimpleFastRuntime 使用同一份起始状态、历史和输入调用快模型。它的默认 stream() 先等待 complete() 再输出一个完整块;要真正逐 token 交付,需要提供自己的流式快路执行器。

快照、历史与本轮消息组装 · 主模型输入及工具回传 · 默认快路的流式行为

结果何时保存 #

SlowTurnRuntime 可以只做分析。未配置 prepareCommit 时,不自动写状态;配置后由该回调检查模型结果,返回 {state, toolsCalled?, ledgerEntries?},或返回 undefined 表示本次不改。

检查函数返回允许保存的新状态后,SDK 才会调用业务提供的 state.compareAndSet。这个方法需要检查本轮读取的旧版本、来源消息和轮次,确认没有被更新的任务抢先修改;版本冲突时返回 stale_write_rejected。数据库、权限和原子写入检查由研发实现,SDK 本身不提供持久数据库。下一轮 FastSlowRuntime 会重新读取当时已保存的版本。

例如,用户要求角色以后说话简洁。快路先回复,慢路再分析是否需要记录这个偏好。业务的 prepareCommit 检查结果,只允许修改约定的字段,通过后才提交存储。下一轮重新读出这份偏好并交给模型,才能影响之后的说话方式。如果没有实现提交和下轮读取,建议就只留在这次调用的返回值里。因此在保存确认前,聊天界面也不应把“永久记住了”显示为已经完成的操作。

默认 prepareCommit 收到的是慢路最终模型响应、工具结果和开始执行时的材料,其中没有本轮快路生成的正文,也没有正文是否已被业务采用的标志。如果产品要求先采用正文、再改状态,可以单独调用并等待 SlowTurnRuntime,先保留分析结果,等业务确认正文后再提交状态。FastSlowRuntime 默认不会替你等待这个确认。

完成、工具成功、状态保存,要分别判断 #

工具返回 {ok:false, tool:"read_gate_rule", error:"规则服务不可用"} 时,这仍是一份正常返回的工具结果。程序把它交回模型,模型可以继续选工具或结束;慢路最终仍可能是 completed,也仍会执行已配置的 prepareCommit。程序不会因为某个结果 ok:false 自动禁止保存。上面这条失败回执中的工具名是接入示例,不是 SDK 自带工具。

返回结果 业务上可以确认什么 下一步
status:"completed",但某个 toolResults[].ok 为 false 模型循环正常结束;所需资料或操作仍可能失败 prepareCommit 检查这份失败是否影响候选;例如规则未查到,就不能把“守卫已获准放行”保存为确定事实
status:"completed" 且 stateOutcome:"retained" 本次没有提交新状态:可能是 gate 跳过、未配置提交或回调决定不改 沿用原状态;若 gate 跳过,final 也不存在
status:"completed" 且 stateOutcome:"committed" 你提供的 state.compareAndSet 已检查旧版本并写入,返回了新版本 后续请求重新读取后才能使用;不代表聊天正文或图片等其他产物也已被业务接受
status:"completed" 且 stateOutcome:"stale_write_rejected" 分析结束,但候选因版本冲突没有写入 不能展示“已保存”;由业务决定是否基于新状态重做分析
工具抛异常、取消或超时 慢路返回相应失败状态,本轮不继续正常完成与提交链路 检查已发生的工具副作用;取消发生在外部提交期间时,也需向存储确认实际结果

因此,消费慢路结果时至少联合读取 status、每项工具结果的 ok 和 stateOutcome。candidateState 也是工具结果中的建议字段,不会自行写入;只有研发实现的 prepareCommit 从结果中选出允许保存的内容、验证后返回候选,才进入状态提交。

工具失败回执仍交回模型及进入提交 · 状态提交与版本冲突 · 失败返回字段 · 工具结果契约

候选到 CAS 保存 · 状态快照与写入字段

预算、gate、取消和工作流接入参数
配置 源码默认或要求 影响
limits.maxSteps 4 慢路模型步骤上限
limits.maxToolCalls 8 整轮工具调用上限
limits.maxParallelTools 4 一批允许的工具调用数量上限
limits.timeoutMs 180,000 慢路期限
limits.maxTotalTokens / maxCostUsd 可选 调用前检查已累计值,调用后检查本次 usage;缺少所需计量时失败。一次调用仍可能使累计超额,不能理解成供应商绝不超支的硬上限
gate(context, signal) slow.gate 可选;每次慢路 run 开始评估一次 返回 {run:false} 跳过慢模型循环、工具与提交;结果为 completed、保留状态、慢循环调用计数 0
prepareCommit 可选 解释结果与决定是否更新状态
cancel() / 外部 signal 显式取消 传播到两路与相关任务;快路失败本身不能当作慢路保存已取消的保证

gate 如果自身调用模型,这次额外模型调用及费用需要由实现 gate 的后端记录;慢循环计数为 0 不代表整项业务毫无开销。gate 抛错、取消或返回非法对象会进入失败路径。它没有自动接入普通 V2 应用,也不能当作“普通 V2 现在累计 X 轮才运行”的证据。该能力在本次主干中有实现,使用发布包前需核实具体版本是否包含。

gate 的合法结果必须有 boolean run,另可含 reason、0–1 的 confidence 与非负 latencyMs;跳过时没有 final,读取结果前需要判空。FastSlowRuntime 仍先读状态、再调度慢任务和快路;它不是让 gate 在快路之前统一决定本轮是否执行。

费用额度不会自动整理上下文 #

maxTotalTokens 累计受预算包装的模型调用所报告的 usage,maxCostUsd 累计这些调用的费用;它们不是某一次模型输入的窗口大小。当前慢路先放入完整的状态文本、所传历史与本轮输入,之后持续追加模型工具请求和工具返回的 JSON;这里没有自动裁剪历史、截短工具结果或调用 Compact 的步骤。

例如查询工具返回很长的世界设定,即使累计消耗还没有达到 maxTotalTokens,下一次模型调用也可能因输入过长而失败。接入方应在工具返回前筛选必要内容,并由自己的模型适配层计数和执行窗口策略;需要放置资料的方式见上下文组装,长历史处理见Compact。

工具执行器会收到 invocation.model,通过它调用模型会计入同一份慢路预算。若执行器另行调用自己的模型客户端或外部服务,这些调用不会自动纳入这里的累计;仅在工具结果里填 usage 也不会被慢路预算自动加总。需要统一费用限制时,执行器应使用传入的模型,或由后端另外记录这些外部调用的消耗,并执行费用限制。

消息原样组装 · 工具结果追加进下一次输入 · 传给工具的预算模型 · usage 累计范围

两路是同一进程中的异步任务,不是各自创建一个系统线程。快路失败、用户停止读取快路迭代器,不会自动等价于 cancel();需要取消整轮时显式触发 cancel 或外部 signal。取消会终止等待并传递信号,但不能撤销已经发生的外部工具副作用或数据库提交;后端仍需配合取消和幂等。drain() 只等现有后台任务,shutdown() 发出取消再等;两者到等待期限都可返回,不能作为“所有外部写入一定停止”的证明。

后台任务是进程内执行,不是可跨进程恢复的持久任务队列。需要可靠工作流时,把 SlowTurnRuntime.run 作为可等待的步骤,持久化任务输入、结果与业务接受状态,再由外部工作流决定重试和提交。status:'failed' 是返回结果,不一定抛异常,工作流步骤应主动检查。

预算与 gate 定义 · 默认限制 · 跳过与失败行为 · 等待分析与业务接受后提交的完整示例

drain、shutdown 与共享取消 · 进程内异步任务 · 按模型响应计量预算

工具注册和 Hook 怎样接 #

注册表保存的是工具定义和执行器;不会扫描仓库把所有函数自动挂给模型。AgenticCapabilityRegistry 直接构造时参数校验默认关闭,设置 validateArguments:true 才按 Schema 强校验;SlowTurnRuntime 使用自己的受控注册与调用校验。通用 Pi Agent 则由 options.initialState.tools 明确提供工具。

工具可以扩展,当前慢路的名单何时确定 #

SlowTurnRuntime 在创建实例时复制 capabilities 并固定工具名称;之后每次模型决策都得到这份名单。它没有在 run() 中按本轮输入自动加载、收起或替换工具的参数。修改最初传入的数组,不会给已经创建的 runtime 自动增加工具。

例如一类业务只允许查询规则,另一类还允许修改规则,研发应在创建各自 runtime 时传入相应的 capabilities;需要随用户身份或请求改变名单时,可创建对应配置的 runtime,或采用自行组装的 Agent 循环。长时间复用同一个实例时,不能只在本轮 Prompt 写“不要修改”就当作撤销了修改能力。

接入动作 实际控制范围
向公共注册表 register() 增加一份工具定义和执行器;名称重复或 Schema 不合法会失败。它不会自动修改已创建的 SlowTurnRuntime 私有注册表
definitions(allowlist) 返回指定名称的模型可见定义;这是提取定义的接口,不是外部服务的访问授权
设置 advisory:true 标记这是建议类工具;当前慢路没有据此禁止执行器写数据库或调用外部服务
执行器校验身份、资源范围与允许操作 决定本次真实调用是否被业务允许;不能由工具描述或 JSON 参数格式校验代替

工具名称、描述、参数 Schema、执行器和返回回执需要成套提供。后端创建 Agent 时确定可用工具,模型只在这份菜单中选择。实际执行函数还要用已核验的登录账号、聊天 ID 和资料权限检查本次访问;例如查询守卫记忆时,只能读取该账号在这段聊天中的记录,不能相信模型自填的另一个用户 ID。

实例创建时固定工具名单 · 每次模型调用提供完整名单 · 注册、定义筛选和 advisory 标签

Core Tools 基类的生命周期是 validate → beforeExecute → 再次 validate → perform → afterExecute。afterExecute 失败时底层副作用可能已经完成,不自动重跑。afterTurn 必须由调用工具的后端在整轮结束后显式调用,execute 不会自动触发它。

已有 Workflow 可以在一个节点直接 await 工具,也可以把 SlowTurnRuntime.run 作为一个节点;依赖执行顺序由该 Workflow 决定。仓内另有下面这套 Profile 固定流程,可以按业务规定的顺序串联工具。

注册与参数校验开关 · 工具生命周期 · Hook 接口 · 完整通用 Agent 示例 · 完整快慢协作示例

原生 Pi 慢任务:保留现有 Agent 的消息和工具 #

如果业务已经用 Pi 的消息、图片和工具接口写好了 Agent,PR #244 允许把这套 Agent 放进 SlowTurnRuntime,继续使用原来的工具调用 ID、执行钩子和动态工具更新。研发在 new SlowTurnRuntime({agent: ...}) 中提供工厂函数,接收本次聊天材料、已读状态和取消信号,返回 Pi 的 options 与本次任务 prompt。这是 SDK 的另一种慢路接法,不会自动替换普通 Agent V2 的后台,也不自带 Story 策略。

这项实现已于 9 月 24 日随 #244 合入 main,并进入已发布的 SDK 0.5.0;0.6.0 继续包含。下面按 10 月 9 日固定 main 82e0169ab2f59f38a11cbdc7e874deec720b0620 说明使用合同。它与前面的 model/capabilities 模式使用不同的结果保存方式;包已发布不代表普通 V2 已改用它,本轮没有确认具体业务的生产采用。

原生模式返回模型与工具调用的统计、toolsCalled、ioSettled,以及在全部受管调用结束时才提供的 agentState。业务从 agentState.messages 中取出最终回复和工具结果,再自行核验、保存。这里的 toolResults 是空数组,stateOutcome 始终为 retained;它不接受 state 或 prepareCommit,不会自动把分析写入数据库。若需要下轮继续使用,业务必须挑出允许保存的字段,检查旧版本并提交,之后再读回。

原生慢路的用量、超时、取消和结果字段
配置或返回 实际含义
agent(context, signal, controls) 后端根据本次材料创建 Pi options 和任务 prompt;工具及消息可以使用 Pi 的原生形式。选择原生模式后,不能同时提供旧模式的 model / modelConfigId / prompt / capabilities / state / prepareCommit
controls.wrapModel(model) 工具内部还要请专家模型分析时,用这层包装后再调用,才能和主模型共用本轮用量与费用额度;绕过它直接调用外部客户端不会自动计入
limits.timeoutMs / modelCallTimeoutMs 分别限制整次慢路和单次模型;前者可以用 null 取消总期限,单模型期限仍有效
maxSteps / maxToolCalls / maxParallelTools 限制模型步骤、整轮工具数与单批调用数;onCallRejected 默认为失败,设 skip 时超限工具返回未执行回执。它仍须遵守原有工具权限和副作用检查
abortDrainTimeoutMs 取消或失败后等待受管调用收尾的时长:默认 0,立即返回;正数有限等待;null 一直等到结束,底层不返回时可能一直等
ioSettled 受管模型与工具的等待是否全部结束;为 false 时不返回 agentState,业务不能把它当作已经安全停止所有远端操作
status / agentState / stateOutcome 循环可以 completed/failed/cancelled/timed_out;有 agentState 也要检查最终状态与工具回执。业务状态由接入方保存,runtime 返回的 stateOutcome 为 retained

程序在请求边界累计主模型和显式包装的专家模型用量。工具调用本身失败可以由 Pi 继续处理,预算超限、重复工具 ID、截断的工具调用等错误则中止。当一个模型在本地超时后才返回,运行仍在收尾期间时,它的有效用量也会加入累计;超额会阻止后续执行。有限等待已经结束、ioSettled=false 时,返回的统计不能证明所有远端费用或副作用已经结清。

调用前后有预算检查,不代表供应商绝不会产生超额账单;执行器已发生的外部写入也不会因取消而撤销。接入方要处理版本检查、幂等、实际计费和取消后的恢复。9 月 24 日候选审查记录过 22 项定向测试与编译通过;本轮核对了合入与发包状态,没有重跑测试,也未做真实 provider 用量、远端取消及业务恢复验收。

原生入口选择 · 工厂与参数 · 专家模型包装与迟到用量 · 取消收尾和实际返回 · 共享用量记录

固定 Workflow:先查资料,再形成写作要求 #

有些业务希望每次都按同样的顺序处理,例如先查询规则,再准备写作要求。这时可以使用仓库中的 StaticPlanner、CapabilityExecutor 和 RPPromptCompiler:第一个读取预先定义的步骤,第二个按依赖调用工具,第三个把工具返回的指定文本放进模型输入。这些组件目前没有从公共 npm SDK 导出,需要使用仓库源码。

具体接法是:研发在自己的后端代码中导入下面这些仓内模块,创建 profile 对象和工具执行器,再在收到请求时调用规划、执行和组装方法。这里的 Profile 是代码传入的流程定义;不能将示例的 executionGraph 直接贴进现成聊天入口的 Scenario JSON,就认为 Router 会执行任意新增流程。下面的可运行例子使用源码构建后的模块路径,并展示结果怎样成为模型消息。

比如用户说“我递出铜钥匙”,你希望每次都先查询城门通行规则,再结合规则形成写作要求,最后交给正文模型。业务可以定义:查规则 → 准备场面要求 → 组装模型输入 → 调用自己的正文模型。这套组件负责前三步的节点执行和材料整理;模型调用、正文保存与接受规则仍由接入者或选用的应用运行时负责。

组件 接入位置 负责什么
StaticPlanner.plan(request, profile) apps/emochi/planning/static-planner.ts 校验请求与 Profile 对应、节点可见性、重复节点、依赖缺失及环;输出按依赖排序的 ExecutionPlan
CapabilityExecutor.execute(plan, request, signal, emit, additionalCapabilities?, parallel?) apps/emochi/capabilities/executor.ts 调用已注册的节点执行器,传递本轮请求、节点参数和已完成输出;返回 {outputs, traces}
RPPromptCompiler.compile({axon, memory, plan, capabilities}) apps/emochi/prompt/compiler.ts 将基础材料、记忆与节点的 promptContent 组成 blocks,并生成 foundation_context / turn_context 两个文本区域
McpCapability apps/emochi/capabilities/mcp-capability.ts 把研发实现、用于请求已接通 MCP 服务的 MCPAdapter.invoke 包装成一个 Capability;提供工具名、节点参数、本轮 query 和已完成的 dependencies,再由回调提取提示文本/资产

McpCapability 没有默认 MCP 服务地址、账号或网络客户端。接入者实现适配器并绑定允许使用的服务;如果只是调用本地函数,直接实现下面示例的 Capability.execute 即可。

固定图的校验与排序 · 执行入口 · 编译结果 · 外部工具包装

Profile 和节点里分别填什么 #

字段 作用与条件
profile.id 本次流程标识,必须等于 request.scenarioId
modelConfigRef / presetRef 完整 ScenarioProfile 的模型/提示词引用;单独规划及执行节点时不会读取这两个配置,也不会调用模型
visibleCapabilities 此 Profile 允许节点引用的能力名称;还必须为名称注册实际执行器,名字本身不会加载代码
executionGraph.nodes 业务定义的固定节点列表;程序根据 dependsOn 排序
节点 id / capability id 是本流程内唯一节点 ID,供依赖与结果定位;capability 是执行器的注册名称,可以多次调用同一能力但要使用不同节点 ID
节点 input 可选参数对象,原样交给执行器;这条执行器不会自动按 JSON Schema 校验它,应在能力内部校验
节点 dependsOn 必须先完成的节点 ID 列表;依赖失败时怎样处理见下表
节点 required 该工具抛错时是否把流程判为必需步骤失败;不能代替输入、权限和存储校验
节点 projectTo foundation_context、turn_context 或 none;只决定该节点明确返回的 promptContent 放在哪个编译区域
defaultTimeoutMs / failurePolicy 完整 TurnHarness.run 采用的轮次默认超时及记忆读取/写入失败策略;单独调用 Planner/Executor 不会自动读取它们来设定时限或保存记忆

failurePolicy 的实际字段为 memoryRecall: "fail_turn" | "continue_without_memory"、memoryIngest: "fail_turn" | "best_effort"。这是记忆步骤的策略;工具节点失败由 required 处理。能力元数据中的 readOnly、idempotent 等描述性质,执行器不会据此自动撤销写入或保证幂等。

能力、节点与 Profile 字段 · Capability 调用与返回契约 · 完整 Harness 的超时与记忆策略

最小可运行示例:看到工具结果进入最终 messages #

下面两个工具是示例里由接入者新定义的工具,不冒充仓库自带的世界书 API。它们使用内存资料演示接口;换成真实世界书或其他服务时,在各自 execute 内完成调用和校验。

在已安装依赖并完成 npm run build 的源码仓库根目录,将此段保存为 workflow-demo.mjs,运行 node workflow-demo.mjs。使用的是仓内构建产物路径,不是公共 SDK 的导入路径:

import { StaticPlanner } from './dist/apps/emochi/planning/static-planner.js';
import { CapabilityExecutor } from './dist/apps/emochi/capabilities/executor.js';
import { RPPromptCompiler } from './dist/apps/emochi/prompt/compiler.js';

const request = {
  requestId: 'workflow-1', scenarioId: 'gate-workflow',
  actorId: 'guard', input: '我递出铜钥匙。', stateVersion: 0,
};
const profile = {
  id: 'gate-workflow', modelConfigRef: 'actor-config', presetRef: 'actor-preset',
  defaultTimeoutMs: 30000,
  failurePolicy: { memoryRecall: 'fail_turn', memoryIngest: 'best_effort' },
  visibleCapabilities: ['read_gate_rule', 'prepare_scene'],
  executionGraph: { nodes: [
    { id: 'rule', capability: 'read_gate_rule', dependsOn: [],
      required: true, projectTo: 'none', input: { location: '城门' } },
    { id: 'scene', capability: 'prepare_scene', dependsOn: ['rule'],
      required: true, projectTo: 'turn_context' },
  ] },
};
const metadata = name => ({ name, readOnly: true, idempotent: true,
  longRunning: false, streaming: false, cancellable: true });
const tools = [
  {
    metadata: metadata('read_gate_rule'),
    async execute({ input }, signal) {
      signal.throwIfAborted();
      if (input.location !== '城门') throw new Error('未知地点');
      return { value: { rule: '进入禁区需要手令;铜钥匙不能替代手令。' } };
    },
  },
  {
    metadata: metadata('prepare_scene'),
    async execute({ dependencyOutputs }, signal) {
      signal.throwIfAborted();
      const rule = dependencyOutputs.get('rule')?.value?.rule;
      if (typeof rule !== 'string') throw new Error('缺少已查到的规则');
      const instruction = `${rule} 守卫应检查手令,不把递出钥匙写成已经获准通行。`;
      return { value: { instruction }, promptContent: instruction };
    },
  },
];
const plan = new StaticPlanner().plan(request, profile);
const capabilities = await new CapabilityExecutor(tools).execute(
  plan, request, AbortSignal.timeout(30000), () => {},
);
const compiled = new RPPromptCompiler().compile({
  axon: { history: [], foundationBlocks: [] },
  memory: { version: '0', items: [] }, plan, capabilities,
});
const messages = [
  { role: 'system', content: '你扮演城门守卫,承接用户动作。' },
  ...compiled.blocks.map(({ role, content }) => ({ role, content })),
  { role: 'user', content: request.input },
];
console.log(JSON.stringify({ outputs: capabilities.outputs, messages }, null, 2));
// 自己的模型适配器接收 messages 后,材料才真正参与生成。

执行后,outputs 中有原始规则对象与场面要求对象;messages 是“角色岗位 → 场面要求(内含手令规则)→ 用户输入”。rule 节点设为 none,所以它不会被重复直接注入;scene 节点显式返回 promptContent,才产生模型可读的文本块。这段示例不调用真实模型,也不写数据库。

执行结果、失败及进入模型的边界 #

情况 实际行为 二开时需要做什么
默认执行 parallel 默认为 false,按排好序的节点逐个执行 有独立慢查询时,可显式传 true;声明依赖的节点仍等待前置节点
节点读取前序结果 dependencyOutputs 是以节点 ID 为键的已完成输出 Map,并不限于自身 dependsOn 中的节点 只读取声明过的依赖 ID;并行时不要依赖另一个无依赖关系节点碰巧先完成
required:true 节点失败 串行立即失败,后面尚未开始的节点不运行;并行时阻断它的依赖节点,其他已启动的独立节点仍可能完成,最终执行抛错 业务明确哪些步骤不可缺;并行失败不等于所有外部副作用已取消
required:false 节点失败 记录失败 trace,没有该节点输出;依赖它的节点仍可继续 下游明确处理“缺少结果”,不能直接读取不存在字段
工具没有注册、依赖无效 返回/抛出执行或规划错误;未注册工具不会因 required:false 自动变成可忽略步骤 配对校验 Profile 和执行器注册表
执行完成 outputs 含 nodeId/capability/value,可有 promptContent/artifacts;traces 含耗时、状态和失败信息 单独使用执行器时由业务保存/展示;它不会持久化任务、自动重试或合并长期状态
取消/超时 执行器传递并检查传入的 signal;正在运行的外部调用也必须配合信号 单独使用时显式设置请求期限;取消不能撤销已经写出的数据
整理成 Prompt 仅非 none 且有 promptContent 的输出会进入编译块,role 为 system;value、artifacts 不自动转成 Prompt 验证/筛选工具文本后再投影;还要由下游模板或消息适配器真正采用,完成计数再发给模型

编译器按区域、priority 和来源等字段排序;它不是直接把所有结果按工具完成先后追加在末尾。TurnHarness 负责把 compiledContext 交给所选正文运行时,具体运行时仍必须使用它。例如 ChatKernel 接法写入 harnessFoundationContext / harnessTurnContext 模板变量;当前闭环 Actor 主要发送 axon.history 中已准备好的消息,不能仅把工具结果放进 compiledContext 就假定已经注入了这个 Actor。上面的示例显式构造 messages,正是为了让采用动作可见。

当前 Agent Router 的普通入口与闭环入口会构造空的 visibleCapabilities 和 executionGraph.nodes。所以这项能力的交付方式是在仓内二开组装 Profile、执行器和模型材料接法,不是往现有 Scenario JSON 随意加一个 executionGraph 就能加载任意工具。通用 SDK 的工具名单、这个固定节点图、普通 V2 的后台专家名单,是三种不同接线。

依赖、并行及失败 · 只投影明确的提示文本 · 模板采用编译区域 · 闭环 Actor 的实际消息来源 · 闭环入口构造的空节点图 · 普通入口构造的空节点图

观测与接入验证 #

可以接入 HarnessTelemetry、observeModel 和 /langfuse 子入口,记录一次调用的模型、工具、状态步骤;createAgentBuildMetadata 描述构建和配置身份。观测用于核对“实际执行了什么”,不代替业务接受或存储成功的检查。

先用仓库公开示例中的假模型和假存储跑通:模型请求工具 → 执行器收到正确参数 → 结果回到模型 → 后端检查并选出允许保存的内容 → CAS 写入 → 下一轮读回;再替换真实后端。安装包不会自动获得 Axon、Kaon 或其他业务凭证。

世界书与普通模型的调用记录 #

使用通用 SDK 时,研发在自己的后端决定记录哪些调用和内容。Emochi 应用的 HARNESS_TELEMETRY_ENABLED 默认 false;设为 true 并提供 Langfuse 地址、公私钥和环境名后,程序才建立导出连接。HARNESS_TELEMETRY_SAMPLE_RATE 默认 1,可在 0–1 之间配置。

9 月 30 日合入的 #273 取消了普通模型/工具正文只在 staging 采集的限制。只要这次调用已接观测、配置有效且被采样,production 等其他环境也允许导出程序交来的输入/输出;没有埋点的调用不会被自动补齐。原有凭据键遮罩和长度限制继续执行,环境名用于区分记录,不再作为正文开关。当前仍没有单独关闭普通正文、同时保留其他内容的配置开关。当前配置与采集范围

世界书 trace 包含会话身份检查、Entity 关联解析和条目选择,包括当前 query、最多 20 条历史、传入 state、绑定、返回 lore 和检索诊断。每项最多 16,000 JSON 字符,超出时保留标记为截断的结构化 preview;新增诊断放在 preview 前部,其中的检索 query 含本轮输入与近期对话。authorization/cookie/password/secret/api_key 等精确键名会被遮蔽,故事内容并不自动匿名化。接入时需要确认这些正文的采集授权、访问和保存期限;记录被导出不等于业务状态已保存,也不会自动回注下一轮。

仓库三份 staging manifest 已设总开关为 true;本轮没有核实各个生产实例的环境变量、采样结果或远端实际入库。因此“代码允许记录生产正文”与“某次生产请求确已被记录”要分别核对。

三类 RPC 的输入、返回与错误 · 允许内容、脱敏与预览上限。

Sumi 已有步骤记录,整次请求的输入输出仍在分支 #

Sumi 的主模型、图片提示词编译、生图、快照保存和通知等步骤记录已随 #237 合入 main。排查时可以沿同一请求看耗时和失败阶段;图片未 ready、快照未保存、通知未确认,需要分别看各自返回,后台函数结束并不自动等于图片交付成功。Sumi 图片处理与结果

#240 codex/sumi-run-root-io 另外给整次 Sumi 前台请求补一份根记录:输入是 turn_context.input_question,没有时取最后一条用户文字,并带 promptId;输出是本次返回的正文 result.output.text 和 status。这样在 Langfuse 的一次请求页面就能对照“用户说了什么、实际返回了什么”,不用先找内部模型调用。后台任务会清掉继承的根输入,避免误标成又处理了一次用户消息。

#240 候选在 9 月 23 日的部署使用了当时仅 staging 采集普通正文的规则;当前 main 的 #273 已取消这一环境限制,但没有因此把 #240 的根输入输出埋点合入。升级时必须同时检查“埋点是否存在”和“采集配置是否启用”,不能只看环境名。根记录只是排查用的正文副本,不是聊天消息的保存位置,也不会成为下一轮模型上下文。

本次更新10 月 13 日已核记录中,#240 仍开放,固定 head 为 0dad1d6;10 月 19 日未重新核对该分支,继续按历史候选展示,不能算作本轮确认已合入的根输入输出记录。该版本在 9 月 23 日 14:16–14:18 有 Sumi staging rollout 成功记录,后来 staging 又有其他分支更新;不能据此认定当前实例仍有这项功能。输入与输出实际写入 · 根输出与后台继承处理 · 对应 staging 更新记录

Sumi 图文事件、调用来源与指定版本部署 #

主线 #267/#269 扩展了 Sumi 的 LLM 和图片 Clickstream 事件。图片开始和结果通过 analytics.report 报告,带会话、消息与图片序号组成的稳定事件 ID,以及图片配置、段落位置、成功/失败/审核结果和耗时。上报失败或 7 秒超时不会回滚已经保存的图片结果,也不会因此再生成一张;接口返回 accepted 只说明 Axon 接受事件,统计平台是否最终入库仍需查询。图片属性里的 rawCost 当前按时长估算,不能当作真实生图账单。图片事件内容与上报

调用图片后端时,Sumi 程序会覆盖设置 caller_service: "roleplay-harness-sumi",工具调试服务则设置 roleplay-harness-tool-debug。这是请求来源标记,用于图片服务识别调用方或兼容路由;它不验证聊天用户身份,也不是新增登录功能。Sumi 调用位置 · 工具调试调用位置

本次更新目前最新可核实的 Sumi 生产部署是 10 月 19 日 13:26 的 f9b26a9。 已展开固定镜像部署和等待就绪步骤,日志有更新成功和 rollout 成功,目标为 agent-production/roleplay-harness-sumi-v1。它包含此前的历史恢复、loading 通知与图文事件,也包含新合入的模型/图片模式选择、图片描述编译失败兜底、初始化追踪和 #296 指标接线。日志还出现 watch forbidden 权限诊断,但最终 rollout 和 job 成功。当前 Pod、有效配置、前端展示和真实业务效果未独立验收。生产部署及就绪步骤 · Sumi 模式和图片链路

本次更新Sumi 的固定镜像包含主线代码,不代表 Emochi 的 Memory/Compact 配置已经启用,也不代表 Prometheus 已抓到实际样本。Worldbook 本轮主线仍为 ad38dce,部署概览没有新进展,沿用 10 月 9 日 10:59 的生产部署成功记录;本轮未重读该 job、数据库 007 迁移、当前实例配置或真实业务调用。两者各自部署,不能用 Sumi 部署成功证明世界书新接口完成联调。Worldbook 历史部署

本次更新Sumi #289 已于 10 月 19 日合入。sumi.init 把参考图 URL、人物资料、初始状态输出、缓存命中及失败阶段放进同一条初始化记录;没有缓存时,两次视觉模型调用作为子记录。原来的两次看图、校验和保存早已存在,这次补齐的是观测。缓存命中不重复产生模型子调用,已完成回合直接回放也不再初始化;历史恢复和正文调用在这个记录之外。实际内容仍要求开启 telemetry 且命中采样,本轮未查看线上 trace。初始化追踪实现

怎样判断模型输入前缀是否稳定 #

#260 已在 Actor 调用处记录实际发给模型供应商的请求前缀、首 token 延迟、输入 token 和供应商返回的缓存 token 用量,并关联 Compact 所处阶段。它比较同一进程内、已验证的前一次成功 Actor 调用;重试、续写、同轮调用、并发重叠或多模态等情况会排除或标为不可比较。

日志里的前缀比较按 256 字节块给出相同部分的上下界,使用 HMAC 摘要,不输出原始前缀。它可以帮助研发检查“为什么这次上下文变化大、首字变慢”,但文本前缀相似不等于供应商 GPU 的 KV 缓存命中。供应商没有返回 usage 时,日志不会补一个零;判断成本或缓存收益时应读实际 usage 和可比较状态。Actor 观测入口 · 前缀比较与排除条件

请求、模型、工具和记忆的执行日志始终输出 #

#236 已合入 main。程序会把请求开始/结束、模型调用、工具调用、记忆读取/写入的事件输出为 JSON 日志,供 Loki 等系统按请求 ID、聊天 ID、配置和阶段串联排查。它和上面的 Langfuse 导出是两条路径:关闭 HARNESS_TELEMETRY_ENABLED 不会关闭这些执行日志,production 也会执行这段代码。

请求开始日志优先读取 extensions.turn_context.input_question,没有时取消息数组里最后一条用户文字,写入最多 16,000 字符原文、完整长度和哈希。模型、工具和记忆错误会写入最多 300 字符的 error_message,同时保留旧 code 和新 error_code。这条 stdout 路径不经过上文的凭据键脱敏,也没有单独关闭原文的开关。用户输入来源 · 日志输出及错误字段

当前记录已经能回答“请求进入了哪一步”,但事件里的 completed/failed 还不能一概当作业务成功/失败。例如记忆表已保存、后续提炼失败时仍会记 memory_write_failed,详见保存后的部分失败。排查和重试需结合数据版本、实际返回和读回结果。

这项内容记录行为经过仓库负责人明确接受后合入,原先提出的问题并未通过缩小采集范围解决。接入这版代码的业务需要据此确定原文访问、保存/删除、采样与错误脱敏方式。已有的 Loki 看板复用这批日志,不会替日志补上脱敏或删除规则;生产是否实际采集了某次输入,要查对应实例和日志记录。

模型连不上时,日志能保留具体是哪类连接问题 #

原来底层连接错误经过包装后,研发可能只看到一次笼统的模型调用失败,不容易分辨是域名解析、TLS 证书、连接、socket 还是超时。10 月 13 日合入的 #298 会保留已识别的安全错误码和类别,写进错误详情及应用日志。例如日志可以附上 transport_error_code 与 transport_error_category,帮助研发沿具体原因继续排查。

它没有改变原来的 HTTP 错误分类和重试规则。例如服务返回 403,随后读取错误正文又遇到 socket 故障,仍按不可重试的权限错误处理,另外记录 socket 诊断;不会因多了一个连接错误字段而自动重试。Actor 的流中断也继续按原来的不完整响应处理,取消与超时优先级不变。

本次更新新增提取只接受固定的 Node/Undici 错误码,不复制底层地址、证书或凭据;未知错误可以没有这两个字段,也不会靠解析错误正文猜原因。它帮助定位故障,不负责更换证书或恢复模型服务。#298 已合入 main 6a108dd,后续 10 月 19 日部署到 Sumi 的 f9b26a9 包含该代码;这不证明其他业务已更新,也没有独立确认某次生产错误已输出这些新字段。

允许记录的错误码与原因查找 · HTTP 分类仍由原状态决定 · 应用日志增加诊断字段

请求变慢、工具失败和图片未交付,分别从哪里看 #

本次更新看板用于帮助研发查清“请求慢在哪一步、模型调用有没有失败、图片是否真的保存和通知”。#296 已于 10 月 13 日 19:32 合入 main,当前应用服务已提供 GET /metrics。 它记录请求、内部步骤、模型用量,以及 Sumi 的历史恢复和图片交付。10 月 19 日 Sumi 的固定镜像部署包含这些代码,但本轮没有查看 Prometheus 是否抓到样本、Grafana 是否显示实时数据。

本次新增#297 仍是另一份未合入候选,不能把它的统计口径和主线 #296 拼成一套现成能力。下面对 #296 使用本轮固定 main f9b26a9 说明;#297 本轮只更新开放状态,逻辑沿用 10 月 13 日的固定源码。更早的 Fusion、#252、#254 看板沿用历史核验,不冒充本轮重新检查了生产数据。

代码位置与状态 已实现的记录与看板 看到结果后可以怎样判断
Fusion #249:已合 fusion-harness;9 月 23 日 23:35–23:38 有 production rollout 成功记录 进程内 Prometheus 指标,记录请求接收、Actor、工具、后台、文本流、图片阶段、Axon RPC、通知与恢复;配套 21 个 Grafana 面板 找出耗时/失败集中在哪一步。notify 成功只代表通知服务应答,不能证明客户端显示了图片;后台 completed 也不能替代图片 ready
本次更新主 Agent Router #252:沿用 10 月 13 日未合入、未部署记录,本轮未重核分支 提议增加 /metrics 和进程内指标,记录整次请求耗时、首个流式 delta、最大间隔、终态、工具、后台、模型与恢复;配套 17 个面板 当前 main 已有后来的 #296 接法,不能把 #252 的字段、首字口径和看板自动视为兼容,需逐项核对查询
本次更新主 Agent Router #254:沿用历史开放记录;作者称已手工导入 production Grafana,本轮未读回看板 直接查询现有 Loki 容器日志,不增加指标收集器,不需要服务重新部署;10 个面板、17 条查询 看请求数、最终失败、耗时、模型配置、失败步骤、错误码,并按请求 ID 查最近失败日志。这和 Prometheus 指标接法分开部署和验证
Worldbook #18:已合主线;包含该实现的 ad38dce 有 10 月 9 日生产部署成功记录,实际抓取和看板数据未验 世界书 HTTP、绑定、搜索/选择、向量降级、索引和数据库连接池指标;36 个面板、34 条查询 帮助排查世界书请求与选条目过程;不改变召回或选择结果。“空选择比例”查询已复现无数据问题,不能当作 0% 或业务成功证据。接法、部署状态与缺陷
本次更新Harness+Sumi #296:已合 main;10 月 19 日 Sumi f9b26a9 部署包含,真实抓取和看板样本未验 HTTP/RPC、内部步骤、模型用量和进程指标;Sumi 另记新生成/回放、缓存、历史恢复、输入预算、图片生成、通知受理与入库 可以分辨请求在进入业务前就失败,还是业务步骤失败;即使关闭 Langfuse,也按返回内容识别业务失败。计数源是已有观察点,未合入 #297 的逐次 provider 尝试方案
本次更新应用指标 #297:本轮页面仍开放;逻辑沿用 10 月 13 日 6cceff5 候选 记录应用执行、模型、工具、后台、Planner、状态、Worldbook 和 Compact 步骤,附 Grafana 定义;候选把部分模型统计放到实际 provider 请求尝试处 能区分预检没发请求、主模型失败和备用模型成功;这份能力尚未进入 main,也不等于已经运行的生产看板

Fusion 的部署记录证明指标代码已更新到那次 production workload,不证明 Prometheus 已采到完整数据、告警已触发或看板上的数字已验收。后续 9 月 24 日 03:16–03:19 的 Fusion 更新还合入了 DIO 免计费传参,但当前 Pod 的镜像未独立读回;业务结果见 DIO 分支说明。主 Router 的 Loki 看板可以先于其 JSON 文件合入 main 被手工导入;现有证据是作者记录,不写成已独立验证生产监控。

本次更新主线方案与另一份候选,分别能看什么 #

本次新增当前应用启动时会注册独立的指标收集器,GET /metrics 返回 Prometheus 文本,设置 Cache-Control: no-store。这条路径不依赖 Langfuse 开关,也没有应用 Bearer 校验;运维需要在实际部署网络中限定谁能访问、配置采集目标,然后核对 up 和指标样本。只是安装通用 SDK,不会自动给客户自己的服务加上这个 HTTP 地址。

本次更新程序从 HTTP 和 RPC 两层记录请求:HTTP 层能看到畸形请求、连接关闭与传输状态;RPC 层记录实际聊天完成、失败、超时、取消和鉴权拒绝。即使 HTTP 返回 200,也不能直接计为业务成功。流式首字只认第一段非空可见正文,不把仅推理内容当作用户已看到回复。

实际发生的情况 主线指标怎样记录、排查时怎样使用
本次新增工具返回 {ok:false};图片返回 blocked / unknown;Planner 返回 stateOutcome=failed / invalid 即使函数没有抛异常,也记为失败。关闭 Langfuse 时仍执行同一套业务结果检查
本次新增Axon 内部请求达到 deadline、用户主动取消、普通服务器错误 超时、取消和普通失败分别统计。内部超时用 AxonRequestTimeoutError 等明确类型识别,不因错误文字恰好包含“timed out”就改判超时
本次新增Sumi 准备阶段内部 RPC 超时 返回 turn.timed_out 和 status=timed_out,Chat/ChatStream 据此返回 TIMEOUT 并记超时;不为了分类主动取消调用方的 signal,也不会继续保存成功回合快照
本次新增世界书调用失败 只记录原来那一次 RPC,保留原错误和原取消原因;指标包装不会为了排查再请求一次或自动重试
本次更新Sumi 回放旧回复、复用缓存、生成图片、推送通知或图片入库 分阶段记录,回放不再算一次新生成。图片 ready、通知网关 accepted 和归档成功是不同结果;accepted 不证明用户手机收到图片
本次新增流式模型多次返回累计 usage 保存最后一份用量,在步骤结束时计入;不把每个累计 chunk 相加,也不把回放或估算补成真实新消耗

本次新增当前主线沿已有观察点计时与收取模型用量;SDK model.complete 是其中一个包裹边界,不能把它当成底层网络重试的逐次计数。后来加入的 sumi_prompt_compile_errors_total{reason} 专门记录图片描述编译失败;编译失败后可能兜底生图成功,所以这一计数不能直接当最终图片失败数。编译兜底与最终结果

本次更新计数留在服务进程内,重启归零,历史趋势和跨副本汇总依靠外部采集;它们不是持久化费用账本。上游没返回用量就保持缺失,不能按零费用理解;输入、输出、推理和缓存字段可能重叠,也不能直接全部相加成账单。主线还包含 Node/进程指标,以及 Sumi 精确 token 计数必须为正安全整数的检查,非法值会让请求失败。当前步骤指标能正确识别业务失败,但部分 stdout 的 model_call_completed 仍只说明函数返回,读日志时还要看图片/状态的实际结果,不能混用两者口径。

本次更新#297 从已通过鉴权后的应用执行开始统计,重点是内部步骤;不覆盖完整 HTTP 生命周期和鉴权前拒绝。其 10 月 13 日版本把使用新模型工厂的统计放到 provider 请求尝试处:没有实际发请求不记模型尝试,主模型失败与备用模型成功分别结算。本轮页面仍为开放状态,未重读分支变动;这些行为沿用固定 6cceff5 的历史核验,没有因 #296 合入而进入主线。

本次更新两套实现都改到 apps/emochi/metrics.ts,部分指标同名而标签、分桶和统计边界不同,不能把 #297 的看板直接指向 #296 后就当作已接通。是否采用候选,需要先核对具体指标合同;生产是否已有实时监控,则必须另查采集和看板数据。本轮只读了主线关键实现与相关测试源码,没有执行测试或访问生产 Prometheus/Grafana。

主线服务启动及采集入口 · 主线请求、步骤和模型指标 · 无 Langfuse 时的业务失败识别 · Sumi 超时结算 · 世界书保持原请求和错误 · Sumi 分阶段指标 · #297 历史候选的逐次请求统计

看板接法、指标口径及固定源码

Fusion 与 #252 的指标留在服务进程内,重启会清零,跨副本总量和历史趋势需要外部 Prometheus 持续抓取和汇总。标签采用固定名单;会话或请求身份留在日志,不作为无限增长的指标标签。#252 的 GET /metrics 没有应用鉴权;当前生产清单使用 ClusterIP,Pioneer Ingress 只转发 /v1/pioneer,本轮证据不能据此称指标公网暴露。运维接入前仍需确认实际网络可达范围、抓取目标、多副本汇总和告警规则。

#254 的部署说明要求把 deploy/grafana/roleplay-harness-main.json 导入 Grafana,使用 UID roleplay-harness-main;重复导入更新同一看板。JSON 中绑定现有 Loki datasource UID be19dkyg8tw5cf,查询 mobile-production / roleplay-harness 容器日志。另一套环境需要替换成能读取相应日志的 datasource 和标签;导入 JSON 本身不会创建日志采集器或赋予数据权限。

Loki 看板将 agent_router_request_failed 以及 completed 事件中 status 不是 completed 的记录计为最终失败。内部步骤失败只是诊断,可能已经在同一请求中恢复。P95 展示“各 Pod 的五分钟 P95 中最慢的那个”,不是全部请求合并计算的全局 P95;首 token 图只统计带 first_token_latency_ms 的记录。请求开始日志仍含最多 16,000 字符用户原文,Grafana/Loki 的访问权限、留存和删除处理依然需要单独落实。

此前已核对 Fusion 21 面板、#252 17 面板、#254 10 面板/17 查询,以及 9 月 24 日 Worldbook #18 的 36 面板/34 查询。已有编译、定向测试或 CI 记录;未直接查询生产 Prometheus、Grafana、Loki,不能把这些检查替代真实数据和告警验收。

Fusion 指标与固定标签 · Fusion 21 面板 · Fusion 指标部署记录 · 主 Router 指标候选 · 候选 metrics 入口 · Loki 看板导入与统计口径 · Loki 10 面板/17 查询