01 · Roleplay 项目全貌
这个项目把角色资料、模型和工具接成连续聊天:Agent 提供角色回复与剧情玩法,Harness 组织执行,Worldbook 提供世界设定。
- 用户输入 → 业务带上角色、聊天历史和已选玩法。
- 准备资料 → 读取状态/记忆;已接世界书时,选出本轮适用条目,装入对应模型输入。
- 回复与后台 → Actor 写本轮正文;启用普通后台时,模型按需调用专家、整理后续要用的状态。Story、Sumi 各有自己的流程。
- 保存到下一句 → 正文和各类状态分别保存;下次请求重新读取,模型才会用到。后台未完成时,可能仍读到旧状态。
能力按玩法和配置启用,并非所有工具默认全开。下面同页查看现状、代码位置和工具;完整案例与条件可按需展开。
放在一张图里,各部分的位置是这样
一段聊天怎样跑完:具体输入、回复、保存和下一句
图的中间一行是当前正文,下方是已启用时才运行的普通后台与后续读取。上方“角色与已保存资料”具体包括角色设定、聊天原文,以及所选玩法使用的持续状态/记忆;它们各自读取,再组成这一次模型调用的材料。不是一个包含所有资料、永久留在模型里的公共窗口。世界书在回复前选取。
图上几次交接还包含具体处理:资料进入模型前要选择、展开模板和检查容量;模型写出的文字交给用户前可能要过滤或改写;保存后的记录进入下一句前还要重新读取。例如,屏幕先出现的一段流式文字可能在完成时被最终正文替换;用户随后修改旧消息,也不会让普通后台自动撤销所有已保存后果。下面沿一段聊天把这些交接连起来,具体处理保留在对应章节。
先看完整过程:用户说完这一句,系统到底办了什么
用户选择角色艾琳,发来:“我把铜钥匙递给北塔守卫,请他开门。”用户只需要说这句话;聊天业务还要把用户、会话、角色、已有聊天,以及本次采用的执行方式交给 Harness。例如业务已经为这段聊天选定“世界书+普通 Agentic 后台”,程序才会按这套接法执行。它没有先问模型这句话够不够复杂,再把整条请求二选一送往快通道或慢通道。
第一件事是让回复有依据。程序取到艾琳的角色资料、近期聊天和已保存状态;在这套接法里,还会请世界书服务按本轮问题和相关材料选条目。假设选回的原文写着“铜钥匙能表明旧王室身份,但进塔仍需城主手令”,程序把这段文字放进回复模型的输入。此时模型拿到的是具体资料,不只是“请遵守世界观”一句空要求。
接着,当前回复和后台工作从各自准备好的材料出发,并行运行。写正文的模型叫 Actor,它可以写:“守卫接过钥匙看了一眼,仍挡在门口:‘城主的手令呢?’”这段文字经过本方案启用的过滤与生成后处理,成为交给业务的最终正文。聊天业务展示并保存这一份;若协议启用了预览与最终替换,完成时要用最终整段替换屏幕预览,不能把两份接在一起。正文如何交付。当前回复不需要等后台把新状态存完。后台的协调模型则判断这一轮是否需要人物、知识、剧情等检查,必要时调用专家。专家交回分析建议;需要更新时,再由 Director——负责整理持续状态的模型——写出一份新状态稿,交程序检查和保存。
这两条路径拿到的材料并不完全相同。本轮选给 Actor 的世界书原文没有自动复制给普通后台;后台也没有自动收到 Actor 正在写的“守卫接过钥匙”这段新正文。因此本轮后台不能仅凭用户说“递出”,就把“守卫已经接收、同意开门”都当成已发生。它可以记录用户的动作和仍待确认的事项,也可以判断暂时没有值得保存的变化。
下一句才把这些结果重新接起来。用户再问:“手令该找谁开?”新请求重新准备材料:上一段正文已保存且被带回,模型才能读到“守卫接住了,但还在要手令”;后台新状态已保存且此时读得到,才会替换旧状态进入后续输入;世界书则针对新问题重新选取办手令的资料。于是下一次回复有了继续往下写的依据。若后台尚未完成,下一轮可能先读到旧状态;若某项保存失败,也不能把模型曾经写出的内容当成已经长期记住。
上面的设定与台词是用于说明机制的例子。当前回复、后台分析、资料保存、下次读取,共同构成连续聊天;其中任何一步都不能由“工具已经调用过”代替。
这段聊天继续使用时,产品还会遇到下面这些操作。它们会改变刚才的闭环,不能只看“下一句仍能正常生成”就认为处理完整了。
| 聊天发生的变化 | 当前实现对这段故事的实际影响 | 产品需要明确的行为与完整细节 |
|---|---|---|
| 用户不满意,重新生成;或把“递钥匙”改成“收回钥匙” | 普通主线使用请求交入的历史,同时读取已有持续状态;重生成仍可能启动后台。“守卫已拿到钥匙”的旧记录不会因改一句话就自动撤销 | 业务要定义替换哪条消息、哪些后续消息作废,以及哪些状态需恢复;逐个操作看输入与保存 |
| 运营把艾琳的门禁规则改了 | Actor 与后台分别读取和组装角色资料;后台可能优先使用另一份非空角色 Prompt。原会话的持续状态也不会自动重建 | 核对改动实际进入哪份模型输入,以及旧剧情是否保留;改角色后的实际读取 |
| 人设、世界书、旧状态对“能否开门”说法不同 | 这些资料可能同时进入 Actor。条目优先级和版本检查各管自己的规则,没有一个已接好的跨来源语义裁决程序替产品选定哪份设定作准 | 应定义设定修改与冲突处理方式,再核对模板/接线;具体冲突案例与现有边界 |
| 用户想重新玩一次故事 | 世界书 Demo 点回角色会优先恢复已有会话;新对话才创建新的会话 ID;清浏览器资料不删除远端聊天与状态 | 界面要区分继续旧局、另开一局、删除记录;当前三个操作分别做什么 |
接入时选择什么:默认提供、业务责任与可支持场景含 1 处更新
默认给业务的是什么:先确定接入哪个入口
| 你接入的东西 | 一开始已经提供什么 | 一开始没有自动提供什么 | 要让用户真正用起来,还要交什么 |
|---|---|---|---|
| 通用 Agent SDK:自己定义 Agent | 基于 Pi 的执行循环、工具执行与结果回传、取消与观测等组件;可选快慢协作运行器 | 没有统一 RP 主提示词,没有自动挂上的世界书/记忆/六专家;一次创建不等于拥有长期记忆库 | 业务自己的 system prompt、模型、输入、工具名单与具体实现;需要跨轮记忆时提供读取、提交和下次采用逻辑 |
| Core Tools 工具包:只借用能力 | 六类分析、JSON 读写、图片资产、Story 工具及通用读写包装;可单独调用 | 安装包不会自动开启对应玩法,也不会自动获得业务用户、数据库或服务授权 | 给选中的工具传真实材料,注入模型/存储/服务;决定什么时候调用、结果交给谁 |
| 仓内角色聊天应用:使用现成请求入口 | 按 scenario_id 选择已经编写的 Actor、后台、记忆等接线 |
不能因用户说“加记忆、加图片”就临时安装新能力;没有“所有模块默认全开” | 启用合法方案并接通依赖;聊天业务先处理用户登录、会话归属与受理,再交入身份、历史和动作;接收并保存最终正文。入口与业务责任 |
| Worldbook Service:管理和取用作者设定 | 导入预览/落库、不可变修订、规则选择、可选混合检索、索引与选择诊断 | 不负责角色聊天、NPC 自动建卡、聊天记忆同步;服务默认不启动向量后端 | 运营准备书条目;接入方负责租户和权限,绑定版本、选择时机及原文注入位置;用向量检索还要启用并建立对应索引 |
这里还有一个容易遗漏的代码默认值:若服务启动时没有指定场景文件列表或旧 JSON 配置,server.ts 只提供 cookie-diary 和 clove-diary-table 两个默认场景,分别配置日记、日记+表格来源;两者都没有默认开启普通 Agentic 后台。每个闭环聊天请求仍必须明确带一个有效 scenario_id。这是闭环聊天服务的默认装配;仓内另有使用 scenarioId 的冻结记忆试跑接口,不能因方案同名就套用相同读写行为。这也不是所有环境的线上默认。
目前能支持哪些业务场景,做到哪一步
看 KAS/Roleplay 开发进度,先区分“能做到什么”和“在哪个环境已经跑通”。 下表沿用现有业务能力目录,在最后一列标出实现状态;各章开头还会写这项能力的接线、开启条件和部署证据。全篇使用同一口径:
| 状态标记 | 已经确认什么 | 还需要什么才可用于具体产品 |
|---|---|---|
| 主线已接线 · 按配置启用 | 固定 main 能追到输入、执行与结果的应用路径 | 目标环境加载对应方案,模型、模板、服务和存储可用;再验证该产品的真实请求 |
| 已有组件 · 业务需装配 | SDK 或工具有公开实现,可以被接入方调用 | 接入方提供材料、工具菜单、依赖,以及采用、保存和回读规则;不是安装后自动全开 |
| 候选已读/候选待审 | 前者读过标明的实现范围;后者仅有提案或文件清单 | 先确认目标分支与准确版本,再完成缺失核验。是否合入、是否部署、是否业务验收,分别记录 |
| 尚无完整接线 | 已读路径没有形成所描述业务的输入到保存、回用闭环 | 仍需业务规则和实现;不能用相似工具的存在代替完成 |
本次更新“代码已合入”“包已发布”“指定版本已部署”“真实业务已验收”分别记录。截至 10/19 14:51,Harness main 为 f9b26a9,Worldbook main 为 ad38dce。本轮新合入六项:记忆召回容错、日记更新后的 Compact 摘要复用、Sumi 模型与图文模式选择、初始化追踪、绘图提示编译失败兜底,以及服务监控。Sumi 的固定版本已于今天 13:26 完成生产镜像更新和就绪步骤;这不证明 Emochi 已采用新记忆策略或实验配置。Worldbook 沿用 10/09 成功部署证据。SDK Latest 仍是 0.6.0,Core Tools 0.2.3 只是前次已核基线。本次变化 · 分支各自状态。
下表的“主线已接线”不是保证模型效果,也不是承诺所有能力可以同时开启。某项外部依赖尚未验证,表示未确认,不表示已经确认它没有部署。
| 用户希望发生什么 | 当前怎样实现 | 当前交付、保存与下一次使用 | 接入阶段与条件 |
|---|---|---|---|
| 与已有角色连续文字聊天:“继续刚才的对话。” | 角色与历史组装 → Actor 生成 → 业务保存正文 | 当前回复;下次由聊天业务带回已保存历史 | 主线已接线 · 按配置启用;具体输入与交付。模型、角色、模板、消息保存服务必须可用 |
| 人物、关系、秘密和承诺保持连续:“记着我明天还钥匙。” | Actor 写正文时,普通 Agentic 后台按需咨询、整理状态 | 后台通过检查并保存后,后续轮读取 state+有限 ledger 投影;当前正文不等它 | 主线已接线 · 按配置启用;后台触发与产物。每次进入生成安排后台,并非全局累计 X 轮才启动 |
| 遵循一本已存在的世界书:“进北塔有什么规矩?” | 回复前按已绑定版本选条目,原文进入 Actor | 当轮看到门禁原文;下轮重新选择,没有自动把同批原文交后台 | 主线已接线 · 按配置启用;绑定与启用。已支持显式配置的前台工具循环、Story、Sumi;条目不自动进入后台或长期状态 |
| 聊天更长,同时保留旧经历或字段:“之前借的东西呢?” | 按选择的记忆后端取摘要/表格;必要时 Compact 压缩旧聊天 | 取回摘要文本、表格文本或压缩摘要;模板实际引用后才进入模型。写入时点各不相同 | 主线多种接线 · 按来源启用;保存与回读。需选来源和后端,不能把日记、表格、Compact 当成同一机制 |
| 当前故事配图:“写见面这一幕,配两张图。” | 前台控制模型调用 Actor;按已启用图片策略安排任务 | 正文先交付,图片稍后关联同一消息;视觉资料另存供后续一致性使用 | 主线已接线 · 依赖图片服务;调用与保存。需要对应 Skill 配置和图片服务,不是六专家负责生图 |
| 以后持续改变角色表现:“以后她说话更简洁。” | 前台 schedule_dio 交外部 DIO 编译长期修改 |
本轮拿到受理回执;后续读取有效的 compiledPrompt 才改变角色提示 | 主线已接线 · 依赖外部编译;DIO 的输入输出。外部编译与启用必须完成,不承诺本轮立刻改写 |
| 按世界事件、情节推进文字剧情:“等到天亮再出城。” | Story 处理世界/叙事快照,准备当前可写内容,之后核对实际保存的正文 | 世界和叙事快照、待核对正文记录;下一次先采用可靠后果,再处理新动作 | 主线已接线 · 可选玩法;Story 如何启用和保存。替代普通六专家后台,不能叠在它后面当每轮必经模块 |
| 连续图文叙事、重生成和分支延续:“接着画刚才那一幕。” | Sumi 独立协议、消息快照与图片交付 | 消息前后状态、可见正文、图片尝试/交付进度;按选定历史消息恢复 | 主线已接线 · 外部归档发布待核;快照与归档。本次固定 main 还调用图片 History/Gallery 归档,依赖外部接口发布;不直接继承普通 RP 的全套记忆 |
| 既有业务只想用一个专家或工具:“帮我检查人物知情范围。” | 直接调用 Core Tool,或自行挂入 SDK Agent/已有 Workflow | 分析建议、JSON 对象、新快照或图片资产;业务自行采用并保存 | 已有组件 · 业务需装配;可复用名单。“单工具能运行”与“完整产品已接好”分开 |
| 新人物先出场,后面不要写乱:“陌生使者走进来。” | 普通 RP 先承接;后台可能调人物分析,再整理持续状态 | 当前正文+后续人物连续性材料;没有独立 NPC 卡 | 已有接线的组合案例 · 无独立人物卡闭环;从出场到后续使用。这是上面“文字回复+连续性”的专项案例,不是新模式,也不会动态安装一个 NPC 工具 |
尚无完整接线:进一步的“统一 Agent 自动找遍所有工具、缺资料自己查世界书、陌生人自动建可编辑卡、所有记忆同步一份真相”,目前还需要业务接线和数据规则。已有基础能力不等于这些跨模块产品已经完成。
角色、历史、状态与记忆:取出什么,下一句怎样用
世界书和记忆,都在支撑这段聊天,但保存的是不同东西
图上的“角色与已保存资料”具体指下面几份资料。先看本页使用的“普通 Agentic+世界书”接法:角色设定说明谁在演,聊天原文保留以前说过的话,持续状态记录后台认为后续要沿用的事实与要求,世界书提供作者设定。日记、记忆表和 Compact 是有对应配置时才加入的其他来源。
| 你在图里看到的词 | 实际取回的是什么;给模型看什么 | 直接查看具体过程 |
|---|---|---|
| 角色资料 | 按角色 ID 读取名字、描述、角色卡、开场等。例:“艾琳谨慎、少言”;普通 Actor 通过模板使用,后台另外组织角色定义。它不是这个模型以前聊过后永久记住的人格 | 从哪里读取,怎样装进本轮 |
| 聊天历史 | 这次请求带回或相应入口读取的消息 ID、角色、原文。例:“守卫说:手令呢?”;模板和容量处理后留下的原文才能被本次模型看到 | 消息从哪来 · 保留条数与容量 |
| 普通 Agentic 持续状态(Director 整理、程序保存) | Axon 读回 Director 整理且程序成功保存的 state 剧情笔记、版本、来源和部分专家分析记录 ledger。例:“仍在门外;用户递出了钥匙,交接未确认”;程序选取并裁剪状态/记录文字,再给 Actor 和后台,二者长度不同 |
真实回包、初始状态、保存与下次采用 · 完整状态格式示例 |
| 世界书 | 每轮按 Prompt 关联解析出的具体书籍版本,经本轮选择后返回条目原文;关联改变影响既有会话下一轮。例:“入塔需要手令”;原文按允许位置进入 Actor,不自动复制给同轮后台 | 怎么选 · 原文放到哪里 |
| 日记、表格、用户资料 | 所选后端可能交回经历摘要、表格文字或用户设定;模板实际引用后才成为输入。这些不是普通 Agentic state 的别名,也不是全仓默认全开 |
取回对象与模型文字对照 · 各后端接法 |
| 历史压缩摘要 | 启用 Compact 后,把一段旧对话变成已知事实、互动摘要和未完事项,连同保留原文使用。摘要有独立检查点,不会因此重写世界书或持续状态 | 什么时候压缩、如何保存和复用 |
| 换成 Story/Sumi 时的状态 | Story 读世界/叙事快照再组织当前场景;Sumi 读对应消息分支的 stateAfter 等资料。它们替换运行方式,各自有保存链路,不是普通后台每轮还必读的两份额外资料 |
Story 状态 · Sumi 状态 |
“现在用哪份”,程序按本次业务选择的运行方式、用户/会话和相关记录读取。普通后台成功保存了新版,且下一次准备时已读到,下一次才使用新版;它还没存完,模型本轮就可能继续读到旧版。资料已取回也不等于已入模——模板没引用、容量处理删掉或选书未命中,模型就没有这部分内容。具体保存时点见一轮到下一轮的时间线。
例如“钥匙已归还”先出现在一条消息里;后台状态、记忆表是否也更新,要看各自流程。当前没有一个会自动把所有资料同步为同一份内容的“总记忆”。本文解释固定源码的读取规则;某次线上请求实际用了哪个模型窗口和状态版本,需要该次有效配置及最终输入,不能从总览例子推定。
能力怎样组合:已有接线、组合限制与尚未完成部分
其余能力怎样加入整体:增强当前链路,或者换一套玩法
上面用“世界书+普通后台”说明闭环,它是一套已接线的组合,不是所有 Roleplay 的默认配置。从整个项目看,业务可以先采用普通角色回复;需要连续性分析时启用普通 Agentic 后台;需要作者设定、额外经历或长历史处理时,再选择允许这些资料能力的接法。参数、模板和保存链路必须相互匹配,不是勾选越多就自然组合成功。
要让这一轮主动安排正文、配图或长期角色修改,已有前台工具循环:先由控制模型选择已注册动作,程序执行并交回结果,再决定下一步;后台连续性分析仍可以按配置另行运行。这里“安排图片”返回的是任务已调度,图片还要生成并写回消息;“修改长期角色指令”返回的是任务受理,后续请求读到已启用的新指令才生效。它们不是调用一下就同步完成所有业务结果。
模型收到的工作要求,与程序执行时的硬性检查,也各有作用。例如 DIO 的工具说明要求“用户明确提出长期修改时才调用”,当前执行层检查接线与重复调度,但没有另做一次“这句话究竟是临时要求还是永久修改”的语义判定。因此业务若要“本次说短点绝不改永久人设”的强保证,仍需补对应采用规则。图片的数量要求也要分别看提示词与程序限制,详见模型选择与程序保证的范围。
Story 与 Sumi 则是其他运行方式,不能接在上面整条流程末尾,当作每轮还要跑的两个模块。Story 维护世界事件和叙事进度,核对实际保存的上轮正文后采用其后果,再准备本轮剧情;当前应用接线替代普通六专家后台。Sumi 使用独立图文协议,按消息和分支保存状态、正文及图片资料,用自己的方式让图文继续。
**世界书现在可以给多种玩法补充本轮设定:**显式配置后,普通 RP、Compact、Agent V2、Story、Sumi 和前台工具循环都可在回复模型调用时使用选中的条目;它不会因此自动进入后台专家或长期保存资料。Sumi 仍不直接继承普通 Agentic、额外日记/表格来源和 Compact 历史压缩;Story 仍替代普通专家后台。实际组合与注入位置。
对产品而言,目前整体做到了哪里
已经有的,是能交付回复、能按选定流程延续资料的应用,以及可供其他业务复用的模型执行和工具能力。普通文字 RP、世界书参与回复、并行连续性分析、前台图文动作、Story 和 Sumi 都能找到对应实现与接线。要采用哪一种,先确定用户体验和这套流程的输入、交付与保存责任。
仍需要具体接入设计的,是跨这些流程的自动协作。例如“后台缺资料时自己再查世界书”“陌生人物一出场就自动建立可编辑、跨会话复用的人物卡”“聊天变化同时同步世界书、表格、人设和剧情状态”,都不能只凭仓库里有相关工具就承诺完成。缺的通常是资料权限与输入、调用时机、结果采用、持久化以及下次读取之间的接线,而不只是再写一个工具名称。
两仓库在这个整体里的分工也由此确定:Harness 组织回复、模型判断、工具执行和资料使用;Worldbook Service 管理作者设定版本,并返回本轮适用的原文。聊天记录、普通状态及部分记忆/图片数据还要通过对应外部业务服务保存。整个产品闭环跨这些服务完成,没有一个统一的“本轮成功”可以替代所有保存与交付结果。
继续查看实现细节、核查范围与源码依据含 1 处更新
这两个仓库目前交付的是一套可组合的文字娱乐基础能力,以及几套已经接好的聊天玩法。用户输入一句话后,先由业务指定采用哪套玩法;程序读取这套玩法需要的角色、历史和资料,把不同工作交给对应模型或工具;当前正文先交付,需要延续的记录按各自规则保存,后续请求再取出并放进模型输入。世界书服务负责作者设定的版本和选择,Harness 负责资料使用、模型与工具执行;聊天、部分记忆及图片还依赖外部服务完成保存。
目前没有一个开箱后就拥有全部工具、全部记忆、全部世界书的统一主 Agent。已经做好的部分包括:通用模型工具循环、固定流程接线、文字回复、并行连续性分析、世界书参与回复、长历史压缩、记忆后端、剧情推进和连续图文。它们的接入程度不同,部分组合还被程序明确禁止。下面先说明“接入后拿到什么、能做什么”,再沿一轮对话看实际运行。
本次更新更新至 2026-10-19 14:51 已完成巡检。本轮补入记忆读取失败时的可选容错、日记变化不再误使压缩摘要失效、Sumi 模型与图文模式接入、生图编译失败后的原始描述兜底,以及已合入的初始化追踪和服务指标。Sumi 今天的生产部署有实际步骤依据;DIO 后台长期修改和摘要质量检查仍在开发分支。查看本次变更;查看待合分支。
整体读完后,再按这条链下探
| 总览中已经出现的环节 | 继续看对应细节 |
|---|---|
| 业务选择执行方式;两个仓库各自负责什么 | 运行方式与组合 · Agent 的运行方式 · Harness 的执行能力 · Worldbook 的资料服务 |
| 准备角色、历史、状态和本轮世界书 | 本次输入长什么样 · 容量与可改参数 · 各岗位的提示词 · 世界书导入、选择、注入 |
| 写当前回复;并行检查;保存后供后续使用 | 模型原文到最终交付 · 后台调用 · 状态保存与生效 |
| 记住经历、维护字段、处理长历史 | 记忆与资料的完整生命周期 |
| 已有聊天中改输入、换回复、更新人设或重开 | 消息操作与旧状态 · 角色更新 · 资料冲突 · 世界书 Demo 会话操作 |
| 前台图片/长期修改,以及 Story、Sumi 玩法 | 图片与图文运行 · Story |
| 工具能完成什么,具体怎么调用 | 业务能力与接线 · 精确工具接口 |
| 把示例走到每一个输入、输出和失败分支 | 两轮完整运行案例 · 异常与重试 |
| 接入、成本及版本核对 | 业务接入 · 成本与记录 · 已核变更 · 候选实现 |
总览的固定代码依据与核查范围
正文概括自已审两仓代码与各章完整链路,不以单个型号配置代替项目范围。本轮按上述固定源码基线及已完成巡检复核文档,没有刷新远端 main、运行模型或验证生产部署。源码存在、应用接线、运行配置启用和实际效果验证分别判断。
业务请求选择方案[1];资料准备与后台独立输入[2];后台与Actor开始生成[3];专家执行、Director与保存[4];聊天业务保存正文[5];世界书当前选择服务[6]。
前台动作与条件[7];Story分支与普通后台分支[8];Story采用与提交[9];Sumi运行与消息快照[10];组合限制[11]。
SDK Agent公开执行入口[12];SDK源码包版本[13];Core Tools公开入口和版本[14];未指定加载项时的应用默认方案[15];启动加载条件[16];世界书默认向量设置[17]。
各项资料的保存与回读详见第9章;工具是否已接、只是可复用封装或属于候选实现,详见第14、21、24章。同名产品、SDK工具和代码分支不作为同一层并列。
核验范围与开发状态
先对上名字:这些代码具体在做什么
main 看合并后的整体能力;分支看研发新增或修改的逻辑。下表直接标明名称、运行方式和代码位置。
工具索引:Agent/剧情人物与图文 · Harness/上下文、记忆与接入 · Worldbook/导入、绑定与召回。完整分支目录。
主干、分支与需求索引的阅读口径含 1 处更新
main(主干)看合并后的整体结果:已经合入的新增、修复和调整,共同构成这一版主干的运行逻辑。下表说明这套代码现在有什么、怎样工作;后续改动合入时,更新这份整体说明。
分支看研发的具体改动:研发从一个代码版本另开分支,增加或修改逻辑,再把提交推到仓库。表中写明它改哪里、产生什么效果、处于候选还是已有合并记录;已经进入主干的能力,同时体现在 main 栏。分支起点和合入目标按实际记录填写,例如 #170 的目标是 Fusion 分支。
本次更新本页按 10/19 已完成增量巡检回填,状态截到 14:51:Harness main f9b26a9,Worldbook main ad38dce。记忆容错、日记与摘要身份分离、Sumi 模型/图文模式、初始化追踪、编译失败兜底和服务指标已进入主干。Sumi 今天的生产步骤成功;Worldbook 保留 10/09 历史部署证据。DIO #303、摘要审计 #305 仍未合入,#297 仍开放;Fusion 三层分支未重新核 head。旧分支目录保留原读取日期,新进展在对应现状与候选章节区分;本次未重跑远端巡检、产品测试或生产业务。
索引对照 KAS 需求List&优先级(9 月 21 日读取),列出工具名字、类型、用途、产物和现有接线。飞书的一/二/三期是交付计划;这里按代码说明已有部分和仍需接通的部分,不按名字相似就判定完成。
每张表先看两列:“名称与执行方式”说明它是什么、由谁决定下一步;“代码位置”直接写明仓库和 main/开发分支。基础功能在 main、增强仍在分支的项目,在同一格分别标出。后面继续说明运行过程、研发改动和进展;详细分支目录保留一条真实分支一条记录。
这里的 RP 代码仓库正式名称是 roleplay-harness,下文使用这个名字;世界书的独立仓库是 worldbook-service。代码位置按本 Wiki 已核版本填写。
Agent:RP Agent V2、Story、Sumi 与前台工具|现状、工具与分支含 3 处更新
Agent:收到用户输入后,怎样回复、推进剧情并延续记录
Agent 主干的整体情况:已有普通 RP Agent V2、Story 和 Sumi 三种运行方式;回复、后台、图文和状态处理按所选方式执行。前台 Actor/图片/DIO 工具按配置接入。Story、Sumi 都由代码编排流程;普通 V2 后台则允许分工模型选择工具。下表同时标明能力所在仓库与主干/分支;普通链路沿用已核固定源码,Jev 新增按 fa41d220 定向核对。
| 名称与执行方式(谁决定步骤) | 代码位置(主干/开发分支) | 现在 main 已经怎样运行 | 相关分支与具体改动 | 目前到哪一步 |
|---|---|---|---|---|
| RP Agent V2(角色扮演 Agent 应用) 程序调度+模型选工具。程序安排前后台;后台分工模型在两阶段内选择专家与 Director。 |
主干:普通 V2roleplay-harness / main开发分支:Pioneer 增强 roleplay-harness / codex/pioneer-actor-progress固定候选 61039e5 |
Actor(回复模型)写本轮正文。Jev 决策适配已合入、仓库场景尚未开启;默认后台不因此改变。普通 V2 启用后,每个进入生成的逻辑轮先启动后台分工模型;再按需选择剧情、人物、知识、世界时间、承诺与伏笔、场面六类分析工具。首轮/新名字另有必需检查规则。Director(笔记整理模型)按需整理笔记,程序校验出有效变化后才尝试保存;不是每轮都调用六专家或写入新版。 六类专家的职责和结果 · 完整一轮 |
Pioneer 增强(状态关联与图文接入改造):codex/pioneer-actor-progress 按当前可见回复寻找对应状态,等正文保存后再关联状态,改善重生成后的状态归属;同时增加图文输出、消息保存和图片回填的接线。展开分支变化 |
普通 V2 已在主干;这组 Pioneer 增强为已读源码的候选。主干另有 Pioneer 查询、调试接口;候选新增内容以此行列出的改造为准。 |
| Story(代码编排的剧情工作流) 程序定步骤和触发条件。内部六个工具分别准备场面、安排剧情目标和结算;部分步骤调用 LLM。 |
已在主干roleplay-harness / main包含 Story 应用流程和公共 Story 工具。 |
接入方启用 storyV1 后,程序协调器安排工具执行:回复前准备场面和剧情目标,交给 Actor 写正文;回复后保存待核对记录;下一请求读取上一条实际保存正文,确认后果并推进事件。启用时接替普通 V2 后台。查看组成、谁调用及完整过程 |
历史开发分支:codex/pov-story-tools/#134。当前主干已有两层实现:公共的六个世界/叙事工具,以及调用这些工具、连接 Actor 和状态保存的 Story 应用代码。 |
主干已实现,按 storyV1 配置启用。#134 在分支清单中的记录为 Merged;本行说明主干现有能力。事件提示牌 #250 已合入并随 Core Tools 0.2.3 发包;当前仍需留意旧会话关闭/更换牌组的限制。提示牌实际作用 |
| 本次更新Sumi(代码编排的图文工作流) 模型生成正文、状态与绘图描述;程序解析、保存,再异步生图。 |
已在主干roleplay-harness / main,固定 f9b26a9。 |
Chat Service 选择本轮主模型,Sumi 使用该配置生成正文与状态;可通过开关只交文字。图文模式先发 loading,快照提交后才生图;编译器失败时,新图片尝试可使用完整原标签继续。历史不一致仍先核实已存正文再重建。 输入、状态与图片交付 |
#300 模型/图文模式、#289 初始化观测、#304 原始标签兜底和 #296 指标均已合入;旧候选按历史日期保留。 | 10/19 13:26 已完成 f9b26a9 production 镜像更新与就绪步骤。有效实验配置、当前 Pod 和客户端体验未独立验收。版本与部署 |
| 本次更新Fusion(Narrative 图文业务接线) 程序将正文和图片关联到聊天消息,并分别处理回复、后台和交付结果。 |
业务分支roleplay-harness / fusion-harness,9/24 已核历史固定 c8fc61c;未并入 main。 |
正文先交付,图片失败独立收尾;20 秒正文停顿保护和配置的 5 秒模型对冲;同一消息追加正文可继续关联后台状态;DIO 请求携免计费标记,运行指标另供采集。 当前行为与实际部署 |
早期 codex/fusion-sumi-message-format/44ffcf1 与 Yuzu #170 保留为历史开发记录;新的图片失败通知 #241、指标 #249、DIO 标记 #253 均进入 Fusion。早期交付改造 |
9/24 03:16–03:19 已有 c8fc61c production rollout。没有独立读取当前 Pod;图片在客户端是否收尾、指标是否采到、DIO 钱包是否免扣分别待验证,不能只看请求完成。 |
| Actor/图片/DIO(模型可选的前台工具组) 控制模型选下一步。在已挂载的工具和额度内,选择写正文、安排图片、长期修改或结束。 |
已在主干roleplay-harness / main当前前台工具循环与工具接线。 |
前台控制模型从已挂载菜单选择动作:actor 写正文,generate_image 安排配图,schedule_dio 向外部服务提交长期修改。DIO 接单后本轮仍继续回复,完成后的有效提示词供后续请求读取。 |
codex/actor-tool-hooks/#78 是早期工具化分支,主要能力已通过 #108 进入 main。这里列的是模型可调用的工具;分支名里的 hooks 不是这组能力的类型。展开旧版与当前区别 |
主要能力已在主干,按所接服务提供工具菜单。#78 在记录时仍 Open;当前参数以主干实现为准。 |
本次更新同一行按能力区分位置:普通 V2 在 main,Pioneer 所列增强在开发分支;Sumi 图文流程、#289 初始化追踪和 #296 指标已在 main;其他观测/部署候选按各自日期保留。Pioneer 是对现有 RP 接入的增强,Fusion 是图文交付改造;它们不因名字不同就变成几套互不相关的产品。Story、Sumi 的工作流步骤写在应用代码里,包含条件判断、失败处理和异步任务;它们没有通过下方通用 profile 工作流配置来定义步骤。日记、记忆表和历史压缩的完整说明仍在记忆章节,真实分支仍在本页完整目录。
Agent 工具索引:从需求里的名字,找到实际做事的模块
下表对应飞书的“剧情与角色”“世界状态”“角色档案”“多模态”需求。同一个需求可能要几个工具合作;同一个工具也可能参与几项需求。“当前接线”指已核主干实现,不代表某个生产入口已经启用。
| 飞书需求/想得到的结果 | 实际工具或模块(类型) | 当前怎样用、交出什么 | 对应程度与详情 |
|---|---|---|---|
| Actor 直返与工具调用:该回复时直接写,需要配图或长期修改时再调用 | actor、generate_image、schedule_dio、over(前台模型可选动作);普通 Actor(正文生成器) |
不启用前台控制器时,Actor 直接写正文;启用 preActorDirector 后,控制模型选动作,程序执行并把回执交回,直到结束。正文本轮交付,图片与 DIO 各走后续流程 |
**已有接线,按配置启用。**菜单没有默认附带世界书补查或 NPC 建卡。实际菜单 · 参数与回执 |
| 角色推演、角色档案与在场名单:人物按身份、动机和知情范围行动 | judge_npc(人物分析工具)+audit_knowledge(知情检查工具)+update_director_state(笔记整理工具) |
后台拿角色、历史、新输入和旧笔记,分析谁在场、知道什么、为何这样反应;Director 按需整理成新笔记,经校验保存,后续 Actor 读取 | **有分析与笔记接线;不是独立人物档案库。**分析不会自动生成可单独编辑、检索的 NPC 卡。人物实例 · 知情实例 · 保存 |
| 新角色生成:新 NPC 出场后,补全身份并保存,下次仍是同一个人 | Actor+judge_npc+Director;可另接 generate_image_asset(独立图片资产工具) |
Actor 可以先承接新人出场;后台依据已有材料整理身份与待揭示信息。人物分析经采用后进入持续笔记;单独生图只得到图片资产 | **现有部分可组合,完整建卡链未接通。**没有自动执行“创建人物 ID/卡片→发布世界书→下一轮按卡召回”。Actor 本轮临时创造的人物,后台通常要到后续历史里才能看到。完整新人案例 · 独立图片工具 |
| 当轮导演工具:先排本条回复的人物、动作、台词、内心和顺序,再让 Actor 演 | direct_scene(后台场面顾问);update_director_state(后台笔记整理);preActorDirector(前台控制器);Story 的当前剧情包 |
三个含“导演”的名字做不同工作:场面顾问给建议;笔记 Director 整理跨轮记录;前台控制器选择正文/图/DIO 动作。Story 则在正文前给当前场面和目标 | **不能一比一等同飞书的当轮导演。**普通后台与 Actor 并行,建议不保证用于正在写的这一条;前台控制器也不等于人物动作排演工具。场面顾问 · 前台四动作 · Story 准备 |
| 场景分类与动态 preset、叙事节奏:日常、悬疑、战斗有不同写法 | Scenario/presetRef(接入配置);selectPreActorSkill/createPreActorDirectorHook(可复用预选实现);analyze_plot、direct_scene;Story 剧情包 |
业务先选配置与 Prompt;另有模型选择 actor({skill})、返回预配 Actor 参数的实现,但当前主入口未调用此 hook。后台可建议推进/停留/镜头,Story 可交当前目标 |
**已有配置、节奏建议和未接主入口的预选实现;不是统一自动切 preset 的已运行链。**改长期风格另走 DIO,不等于当轮场景分类。路由与装配 · 剧情建议 · DIO |
| 视角投影:玩家能看到什么,各角色知道什么 | audit_knowledge+direct_scene(后台建议);PovPrepareTurnTool(Story 场面准备) |
普通 V2 分析知情限制与镜头侧重,保存后用于后续写作;Story 在 Actor 前准备该视角可用的场面资料 | **两种运行方式各有实现。**后台建议不是强制过滤玩家信息的权限系统;Story 也没有自动读取本轮世界书条目。知情范围 · Story 输入输出 |
| 叙事债务:伏笔、承诺和期限后续能接回来 | manage_callbacks(承诺与伏笔分析工具)+Director |
例如“日落前还钥匙”:检查未履行承诺,给后续提醒,采用后存入笔记;下一轮再次作为材料 | **已有后台接线。**提醒不等于立刻触发事件,也不保证每条伏笔按时兑现。触发、产物与例子 |
| 故事时间推进、世界事件推进、事件状态与时间线 | 普通 V2 的 simulate_world(建议工具);Story 的 PovPrepareTurnTool、PovAdvanceWorldTool、NarrativeSettleEventTool(工作流内工具) |
V2 对时间经过/场外活动提建议。Story 从保存的世界快照准备场面;后续请求读取上条实际保存正文,推进世界并结算事件,写入新的快照 | **两个不同策略。**普通建议与 Story 事件结算不能算同一份世界状态;不能把未来计划当已发生事实。世界顾问 · Story 过程 · 快照保存 |
| 多备选规划与选优:选择剧情方向,用户改主意后调整 | analyze_plot(建议);NarrativePlanCycleTool、NarrativeDealBeatTool、NarrativeRebranchTool(Story 计划、当前目标、调整分支工具) |
Story 对已有合格、未完成目标评分选一个并交当前剧情包;主线调整要求最近指定数量的已结算事件给出同一非空用户方向,支线另按停滞阈值处理。普通后台只交剧情分析建议 | **已有目标评分和有条件改线;不等于生成几份完整剧情、评分选一份。**用户一句偏离不保证立即改线。六个 Story 工具 |
| 多模态信息存储与召回:图片、角色参考和场景资料后续可用 | prepare_visual_world/commit_visual_world(视觉状态步骤)、roleplay.state.project_assets(宿主资料读取)、generate_image_asset(资产工具)、Sumi(图文工作流) |
Imagine 按会话投影人物/线索/世界资料,并准备外观和场景材料供图片描述;本轮实际准备过视觉资料且完成回合,才安排后台更新。Sumi 按消息保存图文状态,图片另可归档 | **已有图片链路;视频按人物/事件/场景存储与召回没有已核闭环。**当前画面、参考图、图库、聊天图片是不同产物。Imagine 失败的 pending 问题与 Sumi 恢复机制分别看。视觉目录 · 图片与保存 |
| 其他已接能力:下一句建议、长期修改(补齐实际工具目录) | auto_reply(业务请求入口);schedule_dio(前台动作) |
前者按当前消息与已保存材料生成三条候选供用户选,不代发;后者受理长期风格/角色修改,由外部服务生成有效 Prompt,后续请求读取 | **已有入口,依赖各自配置。**快捷回复是宿主请求,不是后台第八个专家;DIO accepted 不等于完成。下一句建议 · 长期修改 |
补充源码:预选 skill 的可复用实现[1] · 图片使用已有资料的接线[2]。project_assets 是按会话投影已有资料,不是按 query 搜全库;JSON 记忆工具也只是宿主范围内整对象读写,不是素材检索系统。
RP Agent V2 里的六类专家:各检查什么,交回什么
“专家”是六种带专门岗位提示词的 LLM 分析工具。被选中时,程序把角色资料、旧剧情笔记、近期对话、用户新输入,以及这次要检查的问题交给对应模型。每种岗位的模型和提示词按配置读取;返回的是分析建议文字和执行结果。
| 专家/实际工具名 | 负责什么问题 | 会交回怎样的建议(教学例子) |
|---|---|---|
剧情顾问 analyze_plot |
用户改变选择后,主线、当前情节或支线是否要调整,接下来怎样承接 | 用户说“先不进塔,去城门查记录”:建议保留寻找失踪者的目标,把当前方向改为城门调查;不把“想去”记成已经到达 |
人物顾问 judge_npc |
配角是谁、有几人、动机与关系、知道什么、在哪、怎样合理进出场 | 用户安排一个陌生使者出场:整理其已知身份与所在位置,指出来历和关系仍未知;给出后续可揭示方向。返回的是人物分析,尚不是一张已创建的 NPC 小卡 |
知识检查员 audit_knowledge |
哪些是事实、秘密、谎言或猜测;每个人究竟知道哪一部分 | “守卫见到了钥匙,但没人告诉他钥匙的来源”:建议保留这条知情限制。它依据传入材料分析,没有自动检索整本世界书 |
世界时间与场外活动顾问 simulate_world |
时间确实经过或人物分开后,日程、位置、期限和场外人物活动应如何变化 | 历史写明过了两小时且接近换岗:分析原守卫是否仍在岗、期限是否临近,给后续写作建议;这些建议仍需被采用和保存 |
承诺与伏笔顾问 manage_callbacks |
跟踪承诺、线索、物品、伤势、义务、伏笔与延迟后果,提醒尚未收尾的事 | “钥匙是借来的,用户承诺日落前归还”:建议保留归还义务与期限;不强迫本轮立即触发追债或归还 |
场面顾问/Scene Director direct_scene |
选择视角、镜头侧重和角色主动程度,给用户保留选择空间 | “让守卫先回应递钥匙这件事,艾琳只提醒风险,把是否解释来历留给用户”:返回写法建议与主动程度建议,不代替用户决定 |
谁来分工:Orchestrator(后台分工模型)先读取材料和工具菜单,选择本轮需要的检查;程序执行被选中的工具,同批可并行。首轮会在工具启用时补人物、场面检查,有限的新名字识别规则也会补人物检查。六类都在菜单里,不代表每轮六类全跑。
结果谁来用:建议先回到 Orchestrator;需要改笔记时,它调用 update_director_state,由 Director(整份剧情笔记的整理模型)综合旧材料与建议,写出新版。这里的 Director 与上表只提镜头/场面建议的 Scene Director 是两个岗位。程序随后检查内容格式、长度及保存版本,提交成功后,后续 Actor 才能读到新笔记。
保存的“状态”具体是什么:一份跨轮剧情笔记,记录当前场景、人物关系、谁知道什么、物品与承诺、后续方向等。例如“用户已经递出钥匙;后台尚未看到守卫的新回应,是否接收仍待确认”。后台启动时没有 Actor 正在生成的新正文,也没有自动收到本轮给 Actor 选中的世界书原文;它只能按实际收到的材料提出建议。
依据:六工具的名字与职责[3] · 岗位提示词装配[4] · 分工与工具执行[5] · Director 读取建议并生成笔记[6]。完整的调用、失败与保存时序见慢通道,各专家长例见工具职责与例子。
展开 Agent 各项完整过程:输入、执行、保存、下次使用与源码
重点分支:从一句用户输入到下一次使用
以下保留完整运行过程与固定源码依据。示例台词用于解释机制,不是模型实测结果。
main:现在主干里的 RP Agent V2 怎样回复和延续剧情
这一项看主干已经有的普通 RP Agent V2。 它让角色及时回复,同时在后台维护后续需要的剧情资料。main 还包含 Story、Sumi、SDK 和其他能力;“主干有代码”不代表每条 RP 对话都同时启用它们。本卡保留 3b99f4c 的普通运行路径证据;新增的可选 Jev 决策与 Prompt 世界书解析,分别见慢通道更新与取书更新,不改变本卡的默认后台启动规则。
**拿什么进来:**业务提供用户、会话、角色和运行配置,以及当前输入和选定历史。例:“我把铜钥匙递给守卫,请他开门。”程序再读取角色资料和这个会话已保存的 Agent 状态;若这条配置接了世界书,还要为本轮选资料。回复模型和后台分别组装输入,不是把同一个大包发给所有模型。
**这一轮怎样运行:**回复模型 Actor 根据自己的材料写守卫的反应。进入生成的同一逻辑轮,程序安排 Orchestrator(后台分工模型)选择需要的分析工具:剧情、人物、知识、世界时间与场外活动、承诺与伏笔、场面六类,逐项职责见本页专家表。程序并行执行选中的分析;需要保存变化时,再由 Director(笔记整理模型)综合结果,写一整份跨轮剧情笔记。程序检查格式、长度、是否变化及保存版本,符合条件才提交。可以不咨询,也可以没有值得保存的变化。后台不等 Actor 这轮的新正文,因此不能把刚生成的台词当成它已经检查过的证据。
**会拿到两种结果:**用户拿到角色正文,例如“守卫看过钥匙,却仍在索要手令”;后台可能保存“用户已递出钥匙,交接和通行结果在本次后台材料里尚未确认”等状态。正文由接入业务按聊天协议保存,持续状态经 Axon 状态接口保存。二者分别完成,不是一笔同时成功的事务。
**下一句怎么用:**用户说“那我去申请手令”,程序重新取得这次传入的聊天历史和当时已成功保存的状态,供 Actor 继续写。如果后台还没完成,可能仍读旧状态;普通主干不会因为用户点了重生成,就自动撤销之前已经保存的后台状态。
**与其他分支的关系及边界:**这张卡说明普通 RP 的已接链路;默认菜单、实际使用的模型和是否启用图片/DIO/世界书由对应配置决定。没有把仓库里每个工具都自动挂给普通 RP,也没有验证所有线上环境都运行这个固定版本。
codex/pov-story-tools:先安排当前场景,再根据保存的正文结算后果
**Story(代码编排的剧情工作流,内部调用六个世界/叙事工具)。代码位置:roleplay-harness / main。**接入开发者通过 storyV1 启用;程序中的 StoryTurnCoordinator 负责决定各步骤何时执行,Actor 负责写给用户看的正文。条件、顺序和恢复处理写在应用代码里;部分工具调用模型分析剧情。这里的 Story 名称指整套运行方式,codex/pov-story-tools 指其历史开发分支,分支清单中的 #134 状态为 Merged。以下运行过程依据主干 3b99f4c。
**工具具体在里面怎么用:**回复前,程序用 PovPrepareTurnTool 准备场面;需要新的剧情目标时调用 NarrativePlanCycleTool,再用不调用模型的 NarrativeDealBeatTool 挑本轮目标。下一次取到已保存正文后,PovAdvanceWorldTool 更新世界后果;事件结束或中断时用 NarrativeSettleEventTool 核对目标完成情况,满足调整条件时再用 NarrativeRebranchTool 改剧情方向。六个工具由程序按阶段和条件调用,逐项输入输出见 Story 工具表。
**它与 hook 的关系:**Story 通过专用应用适配器接入回复前准备和回复后保存。公共工具的 beforeExecute、afterExecute、afterTurn 是执行前后可挂的回调;这些回调是 hook,Story 本身是使用工具和状态存储的业务运行模式。工具生命周期定义[13]。
**它在解决什么:**让事件、人物所在位置、可见线索和剧情目标有各自进度,并区分“准备让剧情往哪走”和“正文里真正发生了什么”。这与普通 V2 并行维护一份文字状态的时序不同。
**拿什么进来:**同样是“我把铜钥匙递给守卫,请他开门”,加上角色、可见历史以及已保存的 Story 世界/叙事状态。首次没有状态时先初始化;已经有上一轮待核对记录时,先取上一条实际保存的正文和消息关联。
**这一轮怎样运行:**World 部分判断当前在哪、谁在场、用户是在继续眼前事件还是转场;Narrative 部分在需要时规划目标周期,由程序挑满足前提的当前目标。程序把本轮场景与可选方向放进 Actor 输入,准备好后才生成正文。比如先交给 Actor“仍在门口,可以核验身份,不要直接认定进塔”。
**回复之后存什么:**假设 Actor 写出“守卫接过钥匙,但没有开门”。本轮成功后先尝试保存 Story 状态和 pendingActor——对应哪条回复、哪句用户输入、当时准备的场面。它不是已完成的事件结算,也不是让用户点一个“接受”按钮;聊天正文仍由聊天链路保存。这里的状态保存仍可能冲突或失败,程序记录到 Story 报告,不撤销已经完成的角色回复。
**下一句怎么用:**用户说“我想把钥匙拿回来”,Story 先读上一条权威保存正文,核对消息和历史关联,再据此确认“钥匙曾被接收,门没有开”。若关联用户输入或更早已采用正文已经变化、不再匹配,就按当前可见的权威历史重新初始化,不继续套用旧后果。随后处理这句新要求。推进先发生在当前执行内存中,仍要等当前回复成功并完成状态提交,才持久保留。下一次再从保存状态继续。
**与 main 的已知关系及边界:**main 当前装配选择 Story 时,不再同时启动普通 V2 六专家后台;9/22 主干已允许显式配置世界书,条目注入当前 Actor;Story 规划工具不会自动拿到同一批原文。重生成/编辑后重生成在当前接法中走基础 Actor,跳过 Story 准备和写入。不能把 Story 的正文核对机制说成所有 RP 都默认拥有;没有本卡对应部署的生产验收。
Story 当前主干证据与旧分支阅读范围
完整分支名和 #134 的 Merged 状态来自既有 99 分支清单;本卡运行行为依据以下 main 固定文件。旧分支 head 与当前 main 的完整差异比较尚未完成,因此本卡只描述已读主干实现,不列“旧分支独有功能”。Git 名字、PR 标签和当前实现是不同证据,未据此补出旧分支 SHA。
codex/pioneer-actor-progress:图文回复之外,把剧情状态绑回实际回复分支
**固定候选:61039e5,9 月 17 日核查时未进入对应 main 基线。**这个分支的关键变化之一是处理“重生成后,下一轮到底应该拿哪条回复留下的状态”,同时扩展图文生成和交付接线。
**拿什么进来:**用户、角色、会话、选中的消息历史,以及 chat/continue/regenerate/edit-regenerate 这次操作。例:旧回复说“守卫已收下钥匙”;用户改写或重生成后,新回复变成“守卫拒绝接收”。它不能继续无条件沿用旧回复所属状态。
**这一轮怎样运行:**状态读取程序从当前可见助手消息向前查,核对正文内容、用户锚点和状态快照引用,选到对应分支的状态。启用这套图文路径时,Actor 生成正文片段,图片准备工具取这些已写出的片段、角色参考图和视觉资料,编译绘图任务。Narrative 入口处理消息保存、正文交付和图片后续回填;图片结果不要求先于正文全部完成。
**回复之后存什么:**保存用户看到的正文及图片关联,图片任务另外保存尝试和生成结果。后台状态在提交前等待指定的非空助手正文确实已保存;成功提交后,再把状态快照引用挂回该消息;如果这一轮正常结束但没有提交新状态,也会尝试把本轮使用的旧快照引用挂回消息,让下一轮知道沿用了哪份状态。这里等的是“这条正文已经存在”,不是把它重新交给已启动的后台逐句复核。
**下一句怎么用:**用户说“那钥匙还在我手里”,程序沿这次可见消息寻找相符的状态引用,避免把已经换掉的旧回复状态直接当成当前分支状态。视觉资料和图片归属也供对应的后续图文流程使用。如果所有可见消息都找不到合格锚点,读取结果是“未找到状态”,随后用预设的初始文字状态准备 Actor/后台;这不是再调用一个模型重建完整人物。如果已经找到引用、但服务返回的快照引用不一致,则报错,不会当作普通无状态静默继续。
**与 main 的已知关系及边界:**这组候选增强不能当主干默认保证;main 本来就有 pioneer/api.ts 的读状态、调试和建议回复接口,不能笼统说“Pioneer 全部未合并”。正文保存、状态提交、挂接仍是多次操作,可能部分成功。候选也没有自动建立并发布完整 NPC 人物卡的闭环;本卡没有重跑线上验收。
codex/fusion-sumi-message-format:让融合生成的图文按现有聊天消息格式交付
**固定候选:44ffcf1,9 月 17 日核查时未进入对应 main 基线。**它着重解决“生成了一段文字和几张图,现有聊天客户端如何接收、存储和显示”,分支名里的 Sumi 指格式对齐,不能据此说内部生成已经换成 Sumi。
**拿什么进来:**融合图文请求及选中的消息历史。例:“让守卫检查钥匙,给这一幕配一张图。”实际绘图仍要等正文中有对应片段,图片还需要角色参考、提示词、所属消息和段落位置。
**这一轮怎样运行:**保留融合生成与独立图片任务。开启增量模式时,先把解析出的部分正文保存到助手消息,再推 chatStream,图片可提前启动;没有开启增量模式时,这条入口等生成结果后才交付。最终先核对保存正文,再发末尾 chatStream 和最终 chat。图片程序确定正文段落锚点,生成成功或失败后发对应图片事件;消息使用原生图片字段持久化。它要让客户端知道“这一张图属于这条回复的这一段”,而不是只交一个没有归属的 URL。
**回复和保存产物:**用户得到文字和异步出现的关联图片;聊天消息保存正文、图片列表及段落关联。私有图片状态和任务元数据留在 Axon memory,不把内部状态直接作为可见对白。增量模式下后续即使失败,先前保存的部分正文仍可能存在,不能把“没收到最终 chat”理解为“消息完全没落库”。既有 Narrative 历史需要兼容读取,不能假设旧消息都已经变成新字段格式。
**下一句怎么用:**后续请求准备历史时,通过兼容投影读到实际选中的文字与图片关联,后续交付沿消息和段落继续定位。它改变消息协议和保存投影,没有由此增加“世界事实自动结算”或“新人物自动建卡”的机制。
**与 main 的已知关系及边界:**这是有固定源码的图文消息候选。所附 staging 记录验证过部分原生继续和重生成交付,但原生单图重试当时没有进入 Fusion;最终那次运行也没有重验 chat 和 edit-regenerate。不能把测试覆盖等同全操作真实验收。它与 Pioneer 的业务内容相近,本卡不据此画出未经 Git 图验证的祖先关系。
codex/actor-tool-hooks(#78):早期把 Actor、配图和 DIO 接成可调用工具
**原记录:#78 仍 Open,固定旧头 7c368ec。**这是需要保留历史状态的一条:主要能力已经经另一个 PR #108 进入 main 并继续变化,不能把“旧 PR 没关”解释成这套功能还没进主干。
**它在做什么:**让前台控制模型决定何时调用正文生成、何时安排图片、何时请求长期修改,以及何时结束,而不是所有请求永远只有一次固定的正文生成调用。
**拿什么进来:**原有角色、历史、输入和已授权工具。例:“继续守卫查验钥匙的情节,并配一张图。”另一个独立意图例子是“以后把守卫长期改成克制、讲规则的性格”,这对应 DIO 长期修改的业务用途;当前 main 的工具说明进一步限制到用户主动提出长期变化,不能反过来声称旧头已经有完全相同的语义约束。
**旧分支的一轮怎样运行:**控制模型选 actor,程序调用原有 RP 生成器,取得正文片段;需要插图时选 generate_image,程序安排后台绘图,拿回已安排的结果,不等待图片完成;需要长期修改时选 schedule_dio,向外部 DIO 请求接单;最后通过 over 结束。旧版 actor 要求传 maxTokens 分配额度,不能拿这个旧示例直接调用当前 main。
**回复和持久产物:**Actor 片段构成用户正文,沿原有后处理和聊天交付保存。图片经 Imagine 和外部 Image Agent 回写对应消息。DIO 先返回任务回执;真正长期 prompt 由独立 DIO 服务处理,接单不等于改写已经生效,也不是修改当前已生成正文。
**下一句怎么用:**下一轮读取聊天业务带回的历史;如果 DIO 已生成有效的 active prompt,Harness 的对应路径会读回并用于后续准备。图片任务按消息槽位回填。这个分支本身没有“所有工具结果都统一写入一份万能记忆”的机制。
**与 main 的已知关系及边界:**已核对的 Actor/Imagine/DIO/图片接口主要能力已在 main。当前 main 的 actor 参数改为 responseMode,加入符合条件的视觉片段自动排图,图片 MCP 菜单也继续扩展。因此应读成旧实现与合入沿革,而不是待接入新工具包;外部服务和实际场景是否启用仍要另核。
Harness:SDK、快慢运行器、Workflow 与工具包|现状、工具与分支
Harness:怎样把模型、工具和业务流程组织起来执行
Harness 主干的整体情况:已有通用执行 SDK、可复用工具包,以及观测和调试入口。接入开发者用这些组件组织模型与工具;业务提供提示词、可用工具、上下文和存储依赖。
| 名称与执行方式(谁决定步骤) | 代码位置(主干/开发分支) | main 已形成的能力 | 相关分支的工作 | 目前到哪一步 |
|---|---|---|---|---|
| SDK Agent(通用模型工具循环) 模型选择下一步。根据工具返回结果继续选择工具或结束。 |
已在主干roleplay-harness / main通用 SDK 的 Agent 封装。 |
业务提供模型、提示词和工具,SDK 执行工具循环并交回结果;业务负责解释结果及保存。SDK 与 Workflow 接法 | feat/kas-sdk-runtime 等历史分支对应 SDK 建设;当前能力以本行主干说明为准 |
主干已有。SDK 0.6.0 已发布;新增独立世界书客户端。Pi 慢执行器自 0.5.0 发布,安装版本与应用源码分别查看 |
| SlowTurnRuntime(可独立执行的分析工具循环) 模型选工具,程序管限制。可单独等待分析结果。 |
已在主干roleplay-harness / mainSDK 独立慢路。 |
在业务提供的菜单内调用工具、读取结果,受步骤与预算限制;可按调用方规则提交状态。新增 options.gate 可在调用前决定跳过慢路,查看实际返回 |
codex/slow-runtime 对应独立慢路的历史开发记录 |
主干已有;gate 已合入 fa41d220,SDK 0.3.0 不含此增量。普通 V2 尚未使用该 gate,需宿主主动注入 |
| FastSlowRuntime(快慢通道组合器) 程序安排两路并行。快路与慢路内部可以采用不同执行方式。 |
已在主干roleplay-harness / mainSDK 快慢协作运行时。 |
读取状态后安排快路回复与慢路分析。默认快路调用一次模型,也能接入业务自己实现的快流程 | 属于通用 SDK 主干能力;开发沿革见 feat/kas-sdk-runtime 等记录 |
主干已有。可以接已有 Workflow;组合器本身不等于通用 Workflow 引擎 |
| 固定 profile Workflow(配置节点的工作流执行机制) 程序按节点与依赖执行。节点调用什么能力由接入方预先配置。 |
已在主干roleplay-harness / main应用内固定 profile 执行代码。 |
profile 声明节点、依赖和结果注入位置,StaticPlanner/CapabilityExecutor 按图执行;Story、Sumi 的专用流程另写在各自应用代码里 |
本行列主干现有基础机制;与上面 SDK 模型工具循环是不同接法 | 仓内已有。普通 RP 当前使用空执行图;V2/Story/Sumi 的业务顺序由各自应用代码安排。内部 profile 类型未作为 npm 根入口公开 API |
| Core Tools(可复用工具包与接口适配器) 调用者安排执行。可由程序直接调用,或适配后供 Agent 模型选择。工具本身各有模型或程序实现。 |
已在主干roleplay-harness / main公共工具包与 Agent 接口适配代码。 |
封装咨询、JSON 记忆读写和 Story 世界/叙事等工具。程序可直接调用,接入方也可通过适配器挂到 Agent 菜单。工具目录与实际菜单 | feat/kas-core-tools、codex/core-tools-pi-adapter、codex/json-memory-tools 等历史分支对应工具封装、接口适配和记忆读写 |
主干已有实现。每个业务按自己的依赖和用途装载工具 |
| Compact(历史压缩与检查点保存流程) Harness 计算本次输入占用,达到配置门槛后让摘要模型整理旧对话。 |
已在主干roleplay-harness / main;#295 修复已合入 47fb054 |
保存摘要与覆盖到哪条消息,供后续读取;可显式启用后台提前压缩。超长角色设定的请求内精简仍需配置,最终完整 Actor 输入必须更短且不超预算。完整过程 | #196/#198 过滤、#207 累计计数及后台压缩均已有;#295 允许分别合格的计数来源切换,修复误拒,不默认开启角色精简。 | 代码已合入,按配置启用。#295 的 CI 与镜像构建成功,未见部署步骤;语义保留、费用、P95 和当前配置另验。精简的输入和边界 |
| Worldbook SDK 客户端(HTTP 调用封装) 业务程序直接调用。 |
已在主干并发布roleplay-harness / main,SDK 0.6.0 |
创建、导入、修订、建索引、关联业务对象、检索和选择原文;业务自己把结果放入模型输入。接法 | #287 增加独立 @flowgpt/roleplay-harness/worldbook 入口,#288 对齐 Entity 合同 |
10/9 发包成功;服务部署、数据库迁移和产品采用分别确认。 |
| 观测/调试/发布(工程代码与管理接口) 程序或操作者触发。记录运行、试跑工具、执行构建与发布任务。 |
已在主干roleplay-harness / main观测、工具调试和包发布相关实现。 |
记录模型与工具执行,提供工具输入试跑入口,并支持包版本与发布。观测规则、调试与工具 | codex/agent-tracing、codex/agent-sdk-debug-telemetry 对应执行记录;codex/tool-debug-all-tools 扩展工具调试;release/sdk-0.3.0 对应发布工作 |
主干已有观测接线和十项工具调试目录。观测需启用;测试部署与生产配置按各自证据记录 |
Harness 工具与运行能力索引:上下文、记忆和接入分别找哪里
这一组里有工具,也有程序固定调用的流程、存储接口和配置。类型写在名字后;例如 Compact 是程序按预算安排的压缩流程,默认同步,也可显式后台执行,不是六位专家之一。
| 飞书需求/想得到的结果 | 实际工具或模块(类型) | 当前怎样用、交出什么 | 对应程度与详情 |
|---|---|---|---|
| 本轮上下文组装:把适用设定、状态与必要历史交给模型 | 模板渲染、世界书选择、memory recall、上下文预算处理(程序准备流程) | 程序按所选方案取资料、填入模板、检查相应预算,形成此次模型的 messages。Actor、后台、专家分别组装 |
已有多条接线。“信息不足时主动补查”还要求模型菜单真有查询工具;普通后台目前没有默认的世界书/聊天原文搜索工具。每个模型拿到什么 · 实际工具菜单 |
| 记忆状态稳定维护:人物、物品、资源和进度变化延续到下一句 | 普通持续笔记;Axon Go 记忆表;get_memory/update_memory(JSON 工具) |
普通 Director 整理笔记,程序校验并按版本提交;表格路径在回复后解析编辑、按版本保存;JSON 工具从宿主提供的 store 读取或整体替换对象 | **三种已有机制,不能当作自动同步的一张总表。**何时保存、冲突处理和下一次模板采用各自不同;JSON 工具不会默认挂到普通 RP。跨轮保存时序 · 表格 · JSON |
| 上下文 compact 优化:长聊天仍能接续目标和未决事项 | Compact(预算触发的历史压缩流程) | 回复前按容量、旧检查点和历史组决定是否压缩;支持配置化输入协议、结构/文本摘要及递归。同步时摘要+保留原文用于本轮;显式后台模式下本轮用现有输入,任务成功保存后供后续请求读取 | **主干已升级,策略在 Scenario。**bounded_recent 与保存超时确认有实际条件;摘要不会自带“丢失原文随时查回”的工具。#196/#198 已合入 main,摘要前 Jev 对话组/助手段落过滤和边界搜索默认关闭;属于应用压缩流程,不是模型菜单工具。模式、恢复与误省略边界。输入与产物 · 配置 · 保存 |
| 原文存储与召回:按人物、事件、关键词、回合找出处与前后文 | 聊天消息存储/历史读取;记忆 recall(现有宿主接口) | 聊天业务保存已交付正文,后续请求带回历史;已接的记忆后端返回其材料。现有 Axon Go recall 以用户/会话/来源取摘要或表格,没有传本轮 query 做原文搜索 | **原文保存与历史读取已有;需求中的统一检索工具未接成普通 RP 菜单。**不能拿世界书检索代替聊天原文检索。原话与进度 · 实际 recall |
| 记忆效果细化:日记、表格、Compact 各管自己的事 | diary-orchestrator(日记流程)、表格更新、Compact |
日记在生成后按轮数/冷却/额度等判断是否整理;表格记录字段变化;Compact 管本轮窗口。取出后还要经模板采用,才被模型读到 | **现有能力有各自生命周期。**效果优化要分别检查漏记、写入失败、读回和模板采用;不是再增加一个“记忆专家”即可完成。日记 · 完整排查 |
| 业务扩展与自助调测:启停、替换或新增能力,加前后处理 | SDK Agent、Core Tools、toPiTool(接口适配);工具 hooks;Tool Debug(调试服务) |
业务提供 Prompt、工具和依赖,模型循环调用;beforeExecute/afterExecute/显式 afterTurn 可做处理。调试服务选单个工具、输入材料并看返回 |
**机制已在 main。**10 项调试目录不等于线上 Agent 自动有 10 项工具;需安装版本实际导出并完成业务接线。可复用目录 · 调试 · SDK 示例 |
| 控制后台何时跑、怎样选工具(需求落地时的执行策略) | SlowTurnRuntime.options.gate(调用前策略点);FastSlowRuntime(快慢组合);Jev(可选决策适配器) |
SDK 宿主的 gate 返回是否运行慢路;Jev 在启用后负责普通 V2 的工具选择与结构参数,选中工具缺失的必需开放参数另由文本模型补全。二者不是同一个功能 | **已进 main,启用状态不同。**gate 未接普通 V2,SDK 0.4.0 及后续已发布;旧 0.3.0 不含;Jev 仓内场景未开启。普通 V2 仍每逻辑轮安排后台。SDK gate · Jev 与慢通道 |
| 保存二开成果供团队复用;版本发布、升级与回退 | apps/SDK/Core Tools/示例与发布配置(仓库组织及工程流程) |
通用能力放包中,业务接线放应用中,示例演示装配;接入方固定包/镜像及配置,验证后升级,失败时回退对应版本 | **已有代码、示例和发布记录;不是完整的业务认领/成果审核平台。**主干合入、npm 发包、镜像部署和业务验收分别判断;保留原版及数据兼容条件才谈得上回退。接入责任 · 发布与观测 · 版本记录 |
这里的 Harness 分类不等于整个 roleplay-harness 仓库。该仓库还放了上面的 Agent 应用和下面的世界书接入代码。整仓 main、集成和包布局分支可能涉及多类,目录会显示多个标签及原因。
Worldbook:导入、绑定、本轮选取与调试|现状、工具与分支
Worldbook:作者准备哪些设定,本轮选哪些、怎样交给模型
Worldbook 主干的整体情况:世界书服务负责导入、保存、索引和本轮条目选择;Harness 的接入代码负责绑定书籍并把条目放进模型输入;管理员另有匹配调试接口。服务现在还会累计请求、绑定、选择和索引指标,供监控系统读取;这些记录用于排查,不会自动进入下一轮剧情或改写书籍。两仓配合完成从资料到聊天的这条链。
| 名称与执行方式(谁决定步骤) | 代码位置(主干/开发分支) | main 已形成的能力 | 相关分支的工作 | 目前到哪一步 |
|---|---|---|---|---|
| 世界书资料服务(独立检索与资料管理服务) 调用方提交本轮查询,服务筛选条目并返回原文。 |
已在主干worldbook-service / main,ad38dce;10/12–10/13 无新代码 |
导入、规范化、保存版本、建立索引;按输入和条件选条目,返回原文及理由。Entity 关联兼容旧 Prompt 接口;指标不参与条目选择。数据与导入、本轮选择 | #15 滚动部署策略、#19 urllib3 升级仍开放;具体历史分支见目录。 | 已核到 10/09 ad38dce production 部署成功。这是本次补查的旧部署事实。007 数据迁移、Axon 兼容、当前指标采集和业务效果仍未独立确认。部署边界 |
| 世界书聊天接入(程序适配代码与位置协议) 聊天程序在回复前调用。绑定书、取条目、按模板位置装入模型输入。 |
两仓主干都有代码 聊天装配: roleplay-harness / main选取与位置协议: worldbook-service / main |
接入程序每轮核对会话,按 Prompt 解析书籍到具体版本,再向服务取条目;聊天端声明模板可放位置,将返回原文装入模型输入。原文怎样进入模型 | 两仓的 boyn/worldbook-placement:服务 #8 负责位置保留与协商,Harness #168 负责装配;Harness 的 boyn/worldbook-integration 对应聊天接入;后续 #188/服务 #12 改为逐轮解析;#288/服务 #20 再统一 Entity 调用并保留旧 Prompt 服务接口 |
两仓主干已有对应实现。业务仍须配置书籍绑定、服务与模板位置 |
| 世界书匹配调试(管理员 API) 管理员发请求触发。服务返回测试输入对应的条目及理由。 |
已在主干worldbook-service / main |
管理员提交测试输入,查看所选条目及选取原因,帮助调整书中规则。管理范围 | 服务 boyn/worldbook-admin-match-debug/#7 增加管理员匹配调试能力 |
服务主干已有实现。调用需相应管理权限 |
| Entity 世界书关联(业务对象关联 API+Demo 读取) 管理接入修改、聊天程序逐轮读取。决定角色、故事或作品编号使用哪些书与版本;现有 RP 仍以 promptId 作为对象编号。 |
两仓主干已有 Harness #288;Worldbook #20 定向核验 82e0169/ad38dce |
保存业务对象与书籍的关联;每轮 conversation.check 后 bindings.resolve,固定版本或跟随 latest,清空绑定可无书聊天;同轮重试复用已选结果。关联接口与Demo读取 |
boyn/worldbook-demo-associations/#172 为早期提案记录;现行实现按后续 #188/服务 #12 核验,不能仍把整个能力列为候选。 |
代码已进主干。既有会话下一轮也读取新关联;生产新表迁移、实际 RPC 与业务验收未由主干代码证明。 |
Worldbook 工具与接口索引:从设定文件,到本轮实际使用
飞书写的“世界书构建与召回”在实现中横跨两个仓库:服务保存并选择原文,Harness 负责每轮找书和组装输入。下面的接口通常由业务程序调用,不是普通后台模型自由选择的工具。
| 飞书需求/想得到的结果 | 实际工具或模块(类型) | 当前怎样用、交出什么 | 对应程度与详情 |
|---|---|---|---|
| 世界书数据设计和业务接入格式:运营准备资料,业务知道传什么 | 导入预览、书籍创建/修订、条目读取、索引 API(Worldbook 服务接口) | 运营将设定转换成支持的 JSON/角色卡数据,预览问题后保存书籍及不可变 revision,按所用检索方式建立索引。输出 book ID、revision、条目及索引状态 | **已有数据结构和导入接口。**来源元数据、原卡关系与本局变化不能靠一个标题替代;具体必填项、规范化和示例见正文。重开对话不会自动恢复被运营改掉的 Prompt 绑定。准备数据 · 原始规则与本局变化 |
| 绑定角色并决定哪一版生效:换规则后哪一轮看到 | Entity 世界书关联 API(兼容旧 Prompt 路由);worldbook.conversation.check+worldbook.bindings.resolve(每轮准备接口) |
可信管理接入保存资料分组+业务对象对应的书籍/版本;现有 RP 对象编号仍来自 promptId(当前 Demo 只读关联,不提供保存按钮);本轮先核会话,再 resolve 成具体 revision。固定 revision 保持该版,latest 下轮跟随新 head;同轮重试复用已选结果 | **两仓 main 已更新。**与旧会话 pin 机制不同:改 Prompt 关联可影响旧会话下一轮,清空关联则无书继续聊天。生产迁移和真实 RPC 接通另需验证。绑定与版本 · 谁控制、生效时间 |
| 世界书规则召回与上下文管理:找有效条目、排序、去重、预算、模板变量 | worldbook.select(服务选择)+Harness placement/模板组装(程序流程) |
query、历史、条件 state、具体书版本与预算 → 入选原文 blocks 和选取/舍弃记录;程序按位置放入当前 Actor 的输入 | **已有选择与注入链路。**资格、常驻/动态、优先级及预算共同生效;state 要调用方提供。没有自动把同批原文送给后台或允许后台任意补查。条目怎样选 · 模型实际收到什么 |
| 世界书效果细化:复杂查询、冲突、大卡更稳定 | 规则/关键词/hybrid 检索、索引状态、匹配调试、选择 trace(服务能力及诊断接口) | 管理者提交真实输入,查看命中、舍弃和预算原因;检查向量索引是否 ready,按结果调整数据与策略 | **有诊断与检索基础,效果仍需真实大卡验收。**服务 ready 不等于索引完成;hybrid 降级不等于语义召回已生效;未内置所有来源之间的语义裁决。匹配规则 · 调试与验收 |
| 世界书规则更新与生效:时间、地点和剧情后果改变后,后续规则随之变化 | 世界书修订/Prompt 绑定/选择条件;另有普通持续状态和 Story 快照 | 服务能保存新版本、按条件筛选,绑定能使新版本在下一轮被读取;普通 RP 或 Story 各自保存剧情进展 | 基础环节已有,业务闭环仍未自动接通。“正文确认的变化→改世界书条目→处理与原始规则冲突→下一轮统一采用”没有成为默认流程;不能把下一轮重新 resolve 当作自动写回剧情。冲突与写回边界 · 状态来源 |
分类不改变核查结论。上面的相关分支用于定位该方向;具体差异核到哪一步,仍以完整目录的逐条记录为准。仅有名称的分支暂按主题归类,不因此升级成“源码已验证”。
分支目录的记录时间与核查范围
这份目录覆盖到哪里
完整列表快照来自 2026-09-17 下午:Harness 14:25–14:27 的五页共 99 条;Worldbook 14:23 共 8 条。随后记录里可确认的分支另外补录,各自保留时间。9/21 补录 codex/compact-jev-history-filter,9/22 更新其 #196 状态为已合入 main;现共 113 条已记录分支,不表示今天远端只有这些。
这不是今天的实时全量扫描,也不是每条分支都已完成源码审阅。Harness 当晚 21:15 的页面已经显示 109 条,但未留下该时刻完整分支表;当前远端读取受限,尚不能补齐并确认最新全集。已保存的完整快照、后来确认的名字、已读实现和待核内容在下表分开显示。读者可以看到缺口,不需要把“有名字”误当“已读透”。
PR 的 Merged/Open/Draft/Closed 是记录时的状态。Merged 不单独证明合进 main;Open 也不单独证明能力不在 main。是否已进入本 Wiki 主干基线,需要合并目标、提交记录或对应实现证据;部署和线上启用还需各自验证。
完整分支目录:按名称、业务或状态查找
两个仓库的全部已记录分支:逐条查业务与证据
“主线对应源码已读”表示核实了主干里同主题的实现,没有自动证明该历史分支的全部差异。“仅名称/仅列表”的条目保留在目录中,具体行为待核;不会为了填满表格而编造。
分类按业务作用,不按仓库名字。一条分支可以有多个标签;筛选显示所有带该标签的记录,原始分支不重复计数。只凭名称暂归类的原因可在该行“依据与范围”中查看。
roleplay-harness:99 条快照+6 条后续补录
| 真实 Git 分支 | 做什么、对应什么业务变化 | PR 记录 | 核查程度 |
|---|---|---|---|
Harness Agent Worldbookmain9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 主线 主干包含普通 Agentic V2、Story、Sumi 及工具/SDK/世界书接线等具体实现;这些是同一分支里的路径,不应伪造成独立 Git 分支。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 主线 | 源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 后续已读主线源码基线(与上述列表时点分开): 22 条非 Merged 的统计来自较早 13c481b 时点;3b99f4c 为后续主干基线,不将旧 ahead/behind 重算或移用为新时点差异。 分类依据:整仓主线同时包含 RP/Story/Sumi、SDK/工具和世界书接线;放在 Harness 目录用于容纳跨层代码,不代表它仅属于基础框架。 |
Worldbook Harness Agentboyn/worldbook-placement9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 让本轮选中的世界书条目进入指定的角色、范例、作者注、对话深度或命名位置;保留消息边界,并在 Demo 显示最终落位。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #168 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据该PR已留存正文;状态仍采用9月17日历史分支页,本轮没有刷新远端。 分类依据:业务目标是让世界书条目落到本轮模型输入的指定位置;SDK 组装器是实现载体,Actor 是使用方。 packages/sdk/src/context-placement.ts apps/emochi/worldbook/runtime.ts 历史列表 ahead / behind:0 / 1;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/tool-debug-all-tools9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 把调试目录里原先仅部分可运行的工具扩到全部10项:六专家、导演候选、两记忆工具和独立生图;保存预览后可重载重跑。记忆和导演状态隔离,生图可真实计费。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #169 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据该PR已留存正文;状态仍采用9月17日历史分支页,本轮没有刷新远端。 分类依据:独立调试目录使共用工具可准备输入、执行和重跑;虽涵盖六专家及导演等 RP 工具,主体是通用工具试运行能力。 apps/emochi/tool-debug/worker.ts apps/emochi/tool-debug/host-tools.ts 历史列表 ahead / behind:0 / 5;这是提交图计数,不是新增功能数。 |
Harnesscodex/tool-debug-staging-config9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 部署 让独立 staging 工具调试服务使用已经验证的模型 Router,修正“配置来源环境等于模型路由环境”的错误;保留原模型默认值和业务流量绑定。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #167 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据该PR已留存正文;状态仍采用9月17日历史分支页,本轮没有刷新远端。 分类依据:修正独立工具调试服务的模型路由与 staging 配置,服务对象是工具调试设施,不是某个玩家 Agent 的运行流程。 历史列表 ahead / behind:3 / 7;这是提交图计数,不是新增功能数。 |
Agentcodex/pioneer-actor-progress9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 图文生成与交付增强,并让后台状态按可见消息及内容锚点归属到回复分支。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 根任务已深审,关联 fusion/pioneer 主线 分类依据:增强具体图文 Agent 的回复交付,并按可见消息和内容锚点维护后台状态归属。 历史列表 ahead / behind:45 / 56;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/tool-debug-playground9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 主干现有独立工具调试入口:查看目录、准备输入、执行与取消;可脱离玩家会话试工具配置。该历史分支最初开放哪些工具,不能由今日10项倒推。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #166 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:提供脱离玩家会话的共用工具目录、输入准备、执行和取消入口。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/tool-debug/server.ts apps/emochi/tool-debug/catalog.ts 历史列表 ahead / behind:3 / 8;这是提交图计数,不是新增功能数。 |
Agentperf/sumi-parallel-image-delivery9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 同一 Sumi 回复最多4张图并行生成,仍按正文图序逐张保存和通知,第一张无需等待整批完成。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #162 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:调整 Sumi 单次回复中多张图片的并行生成与按序交付。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 9;这是提交图计数,不是新增功能数。 |
Harnessrelease/sdk-0.3.09/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 部署 SDK 0.3.0 对应变更包括可区分业务请求与运行实例的观测身份、Debug schema,以及显式包装原生 Pi 模型/工具调用;发布状态另以发布记录判断。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #164 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:SDK 版本发布及通用观测、Debug schema、Pi 调用包装,属于可供应用复用的运行组件。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 15;这是提交图计数,不是新增功能数。 |
Harnesscodex/sdk-topics9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 文档 增加 SDK 跨组件技术专题文档;已查 PR 范围没有运行时代码、新工具或部署修改。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #159 | 定向已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 本次打开 PR;40 个 docs Markdown,12 篇跨组件技术专题,无运行时代码、新工具、发布或部署 分类依据:SDK 跨组件技术文档,不是独立 Agent 产品流程。 历史列表 ahead / behind:5 / 19;这是提交图计数,不是新增功能数。 |
Harnessperf/publish-ci-gate9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 部署 发布工作流要求当前精确 main 提交已有成功 CI,再执行包关联校验和发布,减少未经该提交验证就对外发包的情况。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #165 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:通用包发布前的精确提交 CI 门禁,属于发布基础设施。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 .github/workflows/publish-packages.yml 历史列表 ahead / behind:0 / 18;这是提交图计数,不是新增功能数。 |
Agentcodex/fusion-sumi-message-format9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 将融合图文交付接到 chatStream/chat 及原生段落图片字段,保留独立图片任务和私有状态。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 根任务已深审 fusion 家族 分类依据:融合图文 Agent 的聊天协议、段落图片交付和私有状态接线。 历史列表 ahead / behind:47 / 21;这是提交图计数,不是新增功能数。 |
Agentfix/actor-usage9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 修复 名称指向 Actor 用量统计修复,具体差异未核;不能据名称认定哪一种 token 或费用计算已修正。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #163 | 仅名称依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向具体 Actor 回复阶段的用量统计修复。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 20;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/agent-tracing9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 接入方可显式包装原生 Pi Agent,记录真实模型请求和工具执行,包括后续轮次替换的工具;观测不替业务接受或保存结果。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #160 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:显式包装原生 Pi Agent 的模型与工具调用观测;提供通用观察接口,由各 Agent 应用接入。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 22;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/agent-sdk-debug-telemetry9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 为应用运行与步骤记录增加明确的 scenario、业务请求和 run 身份,帮助区分当前正文与独立后台工作;仅在配置开启观测后采集。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #161 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:SDK 运行及步骤身份观测,同时含 RP 应用的接入适配;以共用观测能力为主归类。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:3 / 26;这是提交图计数,不是新增功能数。 |
Agentcodex/fusion-existing-production9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 集成 现有正式产品融合接入主题;筛查记录称相关实现已深审,但没有留下此分支独立固定头,不能套用其他 Fusion 头的所有行为。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 保守标为仅列表:当前依据没有该分支的可独立复核 SHA/差异;不能用同族源码已读替代。 分类依据:名称及已留存说明指向已有正式产品的融合图文接入,具体业务 Agent 为主要对象。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:42 / 56;这是提交图计数,不是新增功能数。 |
Harness Agent Worldbookstaging9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 集成 集成和部署分支;列表记录 194 ahead 不能解释成 194 项业务能力,也不能证明其全部内容已进 main。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 集成/部署分支,不能把 194 提交当成 194 个功能 分类依据:整仓集成和部署分支,可能承载多个应用与基础组件;以 Harness 作跨层目录位置,不按提交数伪造业务能力。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:194 / 56;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/main-staging-unification9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 集成 PR #147 的 AOI state/image 与 Agentic V2 集成;记录目标为 codex/aoi-fusion-integration,不是 main。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Draft #147 | 定向已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 原记录目标: SHA 为 PR #147 在既有巡检中固定的 head;未重新查询该名字当前指向。 分类依据:已留存定向审阅范围是 AOI state/image 与 Agentic V2 的集成,归具体 Agent 交付;名称虽叫主干统一,不按名字扩大成整仓统一已完成。 历史列表 ahead / behind:40 / 56;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-deploy-preflight9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 部署 名称指向世界书部署前检查,具体差异未核;不能据此声称当前环境已发布或全部依赖可用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #153 | 仅名称依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向世界书接入的部署前检查,服务于世界书业务能力落地。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:3 / 32;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-safe-trace-labels9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 修复 修复世界书 Demo 恢复缓存诊断时,__proto__ 等继承属性名被误当标签而导致 React 渲染崩溃;未知标签按原文展示,保留旧记录。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #155 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据该PR已留存正文;状态仍采用9月17日历史分支页,本轮没有刷新远端。 分类依据:修复世界书 Demo 的诊断记录标签渲染,属于世界书管理与调试体验。 历史列表 ahead / behind:0 / 33;这是提交图计数,不是新增功能数。 |
Worldbook Agentboyn/worldbook-turn-traces9/17 14:25–14:27 完整列表记录:09/17 14:25:02 北京时间 | 功能 主干会记录本轮选择的世界书条目和最终消息位置,便于判断资料是否真的进入 Actor;记录发生在最终装配与预算处理之后。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #154 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:25:02(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:跟踪本轮世界书选条及最终落入 Actor 的位置,业务目标是确认世界书资料是否实际被使用。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/worldbook/runtime.ts 历史列表 ahead / behind:1 / 35;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-mingding-demo9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 名称指向名为 mingding 的世界书 Demo,具体差异未核;不能仅凭名称补造其角色、运营能力或部署状态。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #152 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向世界书 Demo;没有根据 Demo 名称推定具体角色或运营流程。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 36;这是提交图计数,不是新增功能数。 |
Worldbook Agentboyn/worldbook-integration9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 把会话绑定的世界书接到 RP:按本句、公开场景、近期历史和条件选择条目,再把原文放进 Actor;不会自动把同批原文送给普通后台。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #138 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:将会话世界书绑定、选条和原文注入接到 RP 回复;按世界书业务归类,Agent 是消费方。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/worldbook/runtime.ts adapters/agent-router/dispatch.ts 历史列表 ahead / behind:0 / 37;这是提交图计数,不是新增功能数。 |
Harnesscodex/release-0.2.19/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 名称指向0.2.1版本发布,具体差异未核;当前 changelog 中同版本的 SDK/工具包内容不能替代该分支发布记录。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #151 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向通用版本发布,未见足以归属单一 Agent 应用的证据。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 50;这是提交图计数,不是新增功能数。 |
Harnesscodex/sdk-docs9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 文档 名称指向 SDK 文档整理,具体差异未核;不能将文档增补当作同名运行能力的新开发。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #150 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向可复用 SDK 的文档整理。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 53;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/slow-runtime9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 提供可被业务完整等待的独立 Slow 执行:自带模型/工具循环和可选 CAS 提交,便于放入持久 Workflow 步骤;不强制同启当前回复。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #149 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:提供可独立等待、可放入持久 Workflow 的慢路执行与可选 CAS 提交;具体业务由调用方装配。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/sdk/src/slow-runtime.ts 历史列表 ahead / behind:0 / 57;这是提交图计数,不是新增功能数。 |
Agentboyn/sumi-paragraph-alignment9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 修复 Sumi 在付费生图前向业务服务解析真实段落锚点,并校验锚点属于保存正文,再持久化供图片回填使用,减少图片挂错段落。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #148 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:让 Sumi 图片对应真实保存正文的段落,解决具体图文回复落位问题。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 59;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/aoi-tool-staging-release9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 集成 AOI domain/image asset 的 staging 集成与发布,记录涉及钱包结算及明确图片拒绝后的退款边界。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 定向已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 本次打开树与提交信息;AOI domain + image asset 调用及钱包结算/拒绝退款,交根任务按 fusion 家族核对,不另算一套 NPC 工具 分类依据:已留存范围是 AOI domain/image asset 的应用集成、钱包结算及拒绝退款;属于 AOI/Fusion Agent 的专用发布边界。 历史列表 ahead / behind:154 / 60;这是提交图计数,不是新增功能数。 |
Agentcodex/aoi-fusion-integration9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 集成 AOI 融合集成分支;该次分支表为 0 ahead,不能据此列成一项还待合并的新能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 0 ahead,不能列为尚未合并的新能力 分类依据:名称及列表说明指向 AOI 与 Fusion 应用接线,不能把 0 ahead 当成新增未合并能力。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 60;这是提交图计数,不是新增功能数。 |
Harnesscodex/sdk-release9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 名称指向 SDK 发布工作,具体差异未核;具体发布版本、包含能力和外部可安装性不能仅从该名称推出。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #146 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 SDK 包发布,不属于某个 Agent 的功能配置。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 61;这是提交图计数,不是新增功能数。 |
Harnesscodex/github-token-only9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 当前发布与 CI 使用 GitHub Actions 的 GITHUB_TOKEN 访问包服务,并显式提供读写权限;该历史分支取消了哪些旧凭证入口未复核。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #145 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:共用 CI 与包发布凭证、权限接线,属于仓库发布设施。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 .github/workflows/publish-packages.yml 历史列表 ahead / behind:2 / 64;这是提交图计数,不是新增功能数。 |
Harnesscodex/package-linkage9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 发布前先检查包与仓库的关联,减少构建成功但发布到错误归属或不可访问包的风险;未核该历史分支完整改动。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #144 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:发布包与仓库归属校验,是可复用组件的发布保障。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 .github/workflows/publish-packages.yml 历史列表 ahead / behind:3 / 65;这是提交图计数,不是新增功能数。 |
Harnessfix/package-repository-validation9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 修复 名称指向包与仓库归属的校验修复,具体差异未核;不能据名称指定是哪条校验或权限规则发生变化。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #143 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向包与仓库归属的发布校验修复。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:2 / 66;这是提交图计数,不是新增功能数。 |
Harness Agentfeat/langfuse9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 通过独立、可选的 Langfuse/OTLP 适配记录运行、模型、工具和状态操作;凭证、采样、正文采集和 flush 仍由接入方控制。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #139 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:可选 Langfuse/OTLP 观测适配由调用方配置,适用于多种运行和工具,不限定具体 RP 产品。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:4 / 67;这是提交图计数,不是新增功能数。 |
Harnesscodex/release-current9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 名称指向发布当时当前版本,具体差异未核;名称没有提供版本号,不能当成某次已成功发包的证明。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #141 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称只指向某次版本发布,以通用发布暂放 Harness,不能推定具体版本或发包成功。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 68;这是提交图计数,不是新增功能数。 |
Agentcodex/pov-initializer-recovery9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 修复 Story 对指定的真实 Kaon 临时失败、过滤/协议错误允许进入缺证据处理,保留待结算材料;鉴权、配置、未知错误和外部取消不会统统吞掉。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #137 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:处理 Story 初始化中的指定模型失败与证据缺失,属于事件剧情运行的恢复规则。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/story/model-failure-policy.ts apps/emochi/story/axon-adapter.ts 历史列表 ahead / behind:5 / 73;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/shared-agent-memory9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 共享工具有统一执行生命周期和注入式记忆读写接口,业务可复用这些基础件;会话字段、存储和整轮 afterTurn 时机仍由宿主负责。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #136 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:共用工具生命周期与注入式记忆接口供业务装配;并非某种 Agent 已默认启用的记忆方案。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/modules/memory/json.ts 历史列表 ahead / behind:7 / 74;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/scenario-image9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署 应用容器 CI 验证镜像内已包含场景 JSON,且服务能逐项加载,避免只发布代码却缺少实际运行方案。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #135 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:已读对应范围验证 RP 应用镜像含实际场景文件并可加载;它保障应用运行方案交付,不因使用 CI 就归成通用包发布。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:1 / 75;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/pov-story-tools9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 提供世界准备/推进及叙事规划、节拍派发、事件结算、重分支机制;主干 Story 应用先保存待采用正文记录,下一请求核对实际保存正文后采用后果。它不是六咨询专家。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #134 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:业务对象是 Story 的世界推进、剧情规划、节拍、结算与重分支;实现同时含可复用 Story 工具及已接应用,按具体剧情运行归 Agent。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/modules/story/world.ts packages/tools/src/modules/story/narrative.ts apps/emochi/story/coordinator.ts 历史列表 ahead / behind:1 / 76;这是提交图计数,不是新增功能数。 |
Harnesscodex/package-release9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 部署/配置 已关闭的包发布主题;现有记录仅分支表,不据此列出独有业务能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #132 | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 分支表筛查;包发布主题,不作为独立 RP 业务工具 分类依据:历史记录仅显示包发布主题,属于通用发布目录,不推定有独立 RP 能力。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:5 / 77;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/json-memory-tools9/17 14:25–14:27 完整列表记录:09/17 14:26:39 北京时间 | 功能 给业务显式注册 get_memory/update_memory:读取 JSON 和版本,写入整份替换对象,按 expectedRevision 防止旧结果覆盖新值;字段规则和存储作用域由业务提供。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #133 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:39(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:get_memory/update_memory 是业务显式注册的共用 JSON 读写工具,具体字段、存储和使用时机由宿主决定。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/memory-tool.ts 历史列表 ahead / behind:1 / 77;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/scenario-files9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 服务启动时按白名单读取场景文件,并记录来源与配置 hash;旧环境 JSON 可以整条覆盖同名方案,修改文件不代表运行进程热更新。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #131 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:当前对应实现为 RP 应用启动时加载可运行场景及覆盖规则;以具体应用配置归 Agent,同时关联基础装配机制。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:2 / 78;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/app-package-layout9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 当前仓库把可复用 SDK/工具与应用代码分层:packages/sdk、packages/tools 供复用,apps/emochi 和 apps/sumi 负责具体业务装配;并非安装包即开启应用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #128 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:整仓应用与共用包的边界调整,横跨 SDK/工具和 RP/Sumi 应用;以 Harness 作结构性跨层目录,不冒充单一业务。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 adapters/agent-router/dispatch.ts 历史列表 ahead / behind:0 / 79;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/atomic-image-mcp9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 名称指向独立图片资产工具与 MCP 接入,具体差异未核;不能把 atomic 一词解读成跨服务生图、计费、保存都具备原子事务。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #126 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向独立图片资产工具与 MCP 接入,暂按可复用工具归类;未证明只服务某个图文 Agent,也未证明跨服务原子事务。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 89;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/core-tools-pi-adapter9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 将 Core 咨询工具包装成原生 Pi tool,交回工具内容与细节;业务提供可信上下文、模型和提示词,Pi 执行循环。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #125 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:把共用咨询能力包装成原生 Pi 工具,由各业务提供上下文及模型后使用。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 91;这是提交图计数,不是新增功能数。 |
Agentcodex/vanilla-v3-compact-scenarios9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 部署/配置 已关闭的三个 Vanilla V3 Compact 实验场景部署清单,作者说明已被后续场景文件及 Compact V2 集合替代。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #130 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 本次读 PR,旧部署 manifest 实验方案,作者明确被 scenario-file 迁移与更新 Compact V2 集合取代 分类依据:历史 Vanilla V3 Compact 场景部署实验,针对具体回复方案,且旧方案已被后续配置替代。 历史列表 ahead / behind:2 / 100;这是提交图计数,不是新增功能数。 |
Harness Agentcodex/context-compiler9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 把 RP 角色、用户 Persona、近期对话、旧状态和咨询原因编成专家输入;也允许业务提供自定义上下文,避免为非RP业务硬凑角色字段。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #129 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:共享工具包内的上下文编译器,既有 RP 材料整理也允许自定义上下文;按可复用组件归 Harness。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/context-compiler.ts 历史列表 ahead / behind:1 / 100;这是提交图计数,不是新增功能数。 |
Harnesscodex/ci-boundary-handoff9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 部署 名称指向 CI 边界与交接调整,具体差异未核;未把它归成新增玩家能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #127 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向仓库 CI 边界与交接约定,未显示某个具体 Agent 的用户流程。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:4 / 101;这是提交图计数,不是新增功能数。 |
Harnessfeat/kas-package-releases9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 部署 当前工作流可单独发布 Core Tools 或 SDK,并区分验证预览与正式发布,保留独立版本和发布验证产物。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #124 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:Core Tools 与 SDK 独立版本、预览和正式包发布,属于通用组件发布体系。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 .github/workflows/publish-packages.yml 历史列表 ahead / behind:0 / 102;这是提交图计数,不是新增功能数。 |
Harness Agentfeat/kas-sdk-runtime9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 可复用快慢运行:快路可替换成已有 Workflow,慢路使用调用方工具和同轮快照执行,可选版本提交;不自动安装应用工具或外部数据库。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #123 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:提供调用方可替换快路、注册慢路工具的通用 SDK 运行能力,不等同现成 RP Agent 版本。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/sdk/src/slow-runtime.ts 历史列表 ahead / behind:2 / 111;这是提交图计数,不是新增功能数。 |
Harness Agentfeat/kas-core-tools9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 抽取可复用的六类咨询能力,业务显式提供模型、提示词和材料;专家返回建议,产品编排和正式状态保存由调用方掌握。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #122 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:六类咨询能力被抽为可复用工具,业务另行提供材料、编排和保存逻辑。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/context-compiler.ts 历史列表 ahead / behind:2 / 112;这是提交图计数,不是新增功能数。 |
Harnessfeat/kas-collaboration9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 文档 名称指向 KAS 协作约定,具体差异未核;不能当作新增 Agent 调度或多智能体业务能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #121 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 KAS 协作约定,暂放基础框架协作目录,不视为已实现多 Agent 调度。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 113;这是提交图计数,不是新增功能数。 |
Agentboyn/sumi-real-images9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 Sumi 可按图片配置调用真实生图,记录生成结果和审核证据,再向对应消息交付;外观参考图占位不等于已生成新图。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #120 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:Sumi 的真实图片生成、审核证据及对应消息交付,属于具体图文 Agent 能力。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:0 / 115;这是提交图计数,不是新增功能数。 |
Agentboyn/sumi-existing-conversation9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 把已有普通聊天的可见历史提取为 Sumi 可继续使用的场景状态,保存独立导入检查点和历史指纹;不为旧正文补造图片或镜头事实。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #119 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:把已有聊天导入为 Sumi 可继续使用的场景状态,服务具体图文会话迁移。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 历史列表 ahead / behind:2 / 121;这是提交图计数,不是新增功能数。 |
Harness Agentboyn/kaon-image-runtime9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 名称指向 Kaon 图片运行接口接线,具体差异未核;尚不能把它与 Sumi 或前台所有生图入口完全等同。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #117 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Kaon 图片运行接口,暂按底层可复用图片接线放 Harness;尚未确认它是共用适配器还是某个 Agent 的专用实现。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 125;这是提交图计数,不是新增功能数。 |
Agentcodex/compact-session-ab-release9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 评测 名称指向按会话比较 Compact 方案的 A/B 发布,具体差异未核;不据此宣布某方案生产效果胜出。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #118 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向会话级 Compact 方案 A/B 发布,属于 RP 长对话策略实验,不能推定实验效果或生产默认。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:3 / 132;这是提交图计数,不是新增功能数。 |
Agentcodex/compact-v2a-experiment9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 评测 名称指向 Compact V2A 实验,具体差异未核;不把实验名称视作当前生产默认压缩策略。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #116 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Compact V2A 对话压缩实验,按 RP 上下文处理方案暂归 Agent。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:22 / 133;这是提交图计数,不是新增功能数。 |
Agentcodex/compact-v1-19/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 修复 Compact 已有受限候选次数、模型调用次数与准备时限等可靠性参数;压缩输出保留事实、互动及未完线索,并按规范校验后才使用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #114 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:已读对应实现位于 RP 应用 Compact 运行,约束压缩候选、模型调用及准备时间。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/memory/compact-runtime.ts 历史列表 ahead / behind:7 / 134;这是提交图计数,不是新增功能数。 |
Agentcodex/fix-streaming-response-regex9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 修复 正文正则后处理会影响流式策略:可安全处理时边写边过滤,否则先缓冲或由最终完整内容替换预览,避免直接把未处理原文当最终回复。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #113 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:修正具体 RP Actor 正文流式处理与最终替换策略,直接影响用户收到的回复。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/actor/roleplay-runtime.ts 历史列表 ahead / behind:9 / 135;这是提交图计数,不是新增功能数。 |
Harness Agentfeat/pi-specialist-tools9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 功能 已关闭且未合并的旧根包 Pi 专家绑定方案;当前 main 已有新包边界的 toPiTool,不能算缺失的六专家工具。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #115 | 历史 PR 内容已读依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 本次读 PR、关闭说明,并核 current main 的 Pi 适配器;旧 root-package 实现未合并且被关闭 分类依据:旧的共用专家工具 Pi 适配方案,虽未合并且已被新版包适配替代,分类仍属可复用工具接线。 历史列表 ahead / behind:1 / 135;这是提交图计数,不是新增功能数。 |
Harness Agentfeat/content-filter-recovery9/17 14:25–14:27 完整列表记录:09/17 14:26:48 北京时间 | 修复 名称指向内容过滤后的恢复处理,具体差异未核;主干确有恢复代码,但未确定此历史分支负责的具体错误种类和回退规则。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #112 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:48(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称仅指向内容过滤恢复,缺少足以判断共用模型适配还是 Actor 专用恢复的分支证据;暂放基础执行恢复并关联 Agent,待核边界。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 136;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/image-wire-contract-fix9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复/调整 历史 Image 接线合同修复主题;目前只有列表,未证明相同修复仍未进入 main。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 分支表筛查;老 Image / staging 家族,交根任务关联审查,未独立断言能力未入 main 分类依据:现有列表说明指向旧 Image/staging 图文接线合同,暂以图文 Agent 的交付集成归类;是否另含通用接口变更未核。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:145 / 177;这是提交图计数,不是新增功能数。 |
Agentcodex/dio-user-persona-trigger9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 功能 历史 DIO/user Persona 触发相关分支;已看固定头及 staging image 边界发布记录,未独立证明当前新增能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 定向已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 本次打开分支固定头;老 DIO / image 边界发布家族,未将其重复计为新 DIO 工具 分类依据:DIO 与用户 Persona 的触发及图文边界,针对角色对话应用的具体行为。 历史列表 ahead / behind:142 / 177;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/image-anchor-demo-release9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署 名称指向图片锚点 Demo 的发布,具体差异未核;不能从发布分支名称认定图片已在当前用户环境正确落位。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #109 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向图片锚点 Demo 发布,暂以图文回复的图片落位场景归类;未确定其是否仅为共用工具演示。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:3 / 138;这是提交图计数,不是新增功能数。 |
Agentcodex/agentic-transient-fallback9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复 Actor 在满足恢复条件且配置了备选模型时,可对指定临时错误尝试备用配置;已交付的可见文本、取消和不可恢复错误影响是否允许重试。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #111 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:指定临时错误下 Actor 的备选模型恢复及可见正文约束,属于 RP 回复流程。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/actor/roleplay-runtime.ts 历史列表 ahead / behind:4 / 138;这是提交图计数,不是新增功能数。 |
Agentcodex/remove-production-auto-memory-scenario9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署/配置 移除生产 AutoMemory 实验场景配置;是配置清理,不是新增工具。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #110 | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 分支表筛查;移除生产实验场景主题,不是新增业务工具;PR 详情由根任务处理 分类依据:现有记录指向删除生产 AutoMemory 实验场景配置,属于应用方案清理而非删除通用记忆工具。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 138;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/dio-imagine-main9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 功能 将当前正文、配图和长期角色修改接成前台动作流程:控制模型可安排 Actor、图片及 DIO;图片补当前消息,DIO 编译后的修改供后续轮使用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #108 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:将 Actor、图片和长期角色修改接成具体前台动作流程,影响当前图文回复及后续轮角色表现。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/actor/roleplay-runtime.ts adapters/agent-router/dispatch.ts 历史列表 ahead / behind:2 / 139;这是提交图计数,不是新增功能数。 |
Agentcodex/dio-prompt-slot-fix9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复/调整 历史 DIO prompt slot 修复主题;目前只有列表,不能推断当下主线还缺此修复。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 分支表筛查;DIO prompt slot 修复家族,未独立断言新增工具 分类依据:名称及列表说明指向 DIO 在角色对话中的提示词插槽修复。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:144 / 141;这是提交图计数,不是新增功能数。 |
Agentcodex/agentic-v2-dsflash-profile9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署 名称指向 Agentic V2 的 DeepSeek Flash 运行配置,具体差异未核;不能据配置分支名声称快慢机制或工具清单另成一种 Agent。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #105 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Agentic V2 的模型运行配置;是既有 Agent 的配置变体,不另立一种框架。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 142;这是提交图计数,不是新增功能数。 |
Agentcodex/compact-latency-observability9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复/调整 Compact 的选中历史使用和准备阶段耗时观测,已查两提交四文件范围,无新增独立工具注册。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 定向已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 本次读 compare 的 2 提交/4 文件范围及可见差异;历史选择窗口与准备耗时观察,没有新增独立 tool 注册文件 分类依据:观察 RP Compact 选中历史及准备耗时,针对具体对话压缩流程。 历史列表 ahead / behind:2 / 149;这是提交图计数,不是新增功能数。 |
Agentcodex/remove-compact-conversation-dependency9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复/调整 Compact 使用已选请求历史、调整会话历史依赖;列表与相邻 compare 有对应提交,未单独固定本分支头。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 未显示 PR | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 分支表;对应上一分支 compare 中的 selected-request-history 提交,属于 Compact 历史依赖调整 分类依据:现有列表及相邻差异记录指向 RP Compact 对已选请求历史的使用,按具体上下文准备归类。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 149;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/actor-tool-hooks9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 功能 早期 Actor/图片/DIO 工具化分支,PR 仍 Open;主要能力已通过 #108 进入 main,旧 PR 状态不等于全部能力待合并。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #78 | 源码已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 独立子任务已深审,不在本次重复 分类依据:Actor/图片/DIO 工具化后用于具体前台 Agent 运行;可复用工具边界为关联层,不把旧 Open PR 误作全部功能未入 main。 历史列表 ahead / behind:50 / 182;这是提交图计数,不是新增功能数。 |
Agentcodex/add-compact-scenarios-to-deployments9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署 名称指向把 Compact 场景加入部署配置,具体差异未核;添加可选场景不代表所有请求自动启用压缩。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #98 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向具体 Compact 对话方案的部署配置,不能视为通用 SDK 发布。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 150;这是提交图计数,不是新增功能数。 |
Agentcodex/fallback-compact-token-count9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复 名称指向 Compact 回退时 token 计数修复,具体差异未核;不能补猜触发条件和数值变化。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #96 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 RP Compact 回退时的 token 计数,按应用上下文压缩归类。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 152;这是提交图计数,不是新增功能数。 |
Agentcodex/remove-compact-config9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署 名称指向移除某项 Compact 配置,具体差异未核;不等于删除整个压缩实现,也不等于当前主干没有 Compact。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #84 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向清理某项对话 Compact 配置,按具体运行方案归类,不据此判定整个压缩能力被删除。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:3 / 154;这是提交图计数,不是新增功能数。 |
Agent Harnessfix/multi-profile-project-versions9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复 主干校验请求项目版本时接受当前版本及显式配置的兼容版本集合,便于多份运行配置协调迁移;该支具体版本组合未复核。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #94 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:已读对应位置为应用服务器及 Agent Router 的请求项目版本兼容,服务多份 RP 运行配置迁移;并非 SDK 包版本发布。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 adapters/agent-router/dispatch.ts 历史列表 ahead / behind:0 / 155;这是提交图计数,不是新增功能数。 |
Agentfix/main-respect-actor-prompt-manager9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复 名称指向 main 中尊重 Actor 指定 PromptManager 的修复,具体差异未核;不能仅按名称确定覆盖优先级变化。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #93 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Actor 提示词选择修复,作用对象是具体回复模型的输入配置。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:0 / 157;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/dio-actor-tool-staging9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署 名称指向 DIO 与 Actor 工具在 staging 的集成,具体差异未核;历史列表 Merged 不证明其目标为 main,也不证明仍有一套独立的新工具待接。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #88 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 DIO 与 Actor 工具在 staging 的应用集成,按角色对话动作流程归类。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:68 / 177;这是提交图计数,不是新增功能数。 |
Harness Agentci/hinos-staging-image9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 部署/配置 已关闭的 Hinos staging CI 镜像主题;现有记录仅列表。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #87 | 仅列表依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 分支表;CI 镜像主题,不列为新增工具 分类依据:仅列表显示 Hinos staging CI 镜像主题,无法确认是否为具体 Agent 专用部署;暂放发布设施目录,若证实专用应用镜像再改归 Agent。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 163;这是提交图计数,不是新增功能数。 |
Agentfix/respect-actor-prompt-manager9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 修复 名称指向尊重 Actor PromptManager 选择的修复,具体差异未核;需与 main 对应修复及其合并目标区分。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #86 | 仅名称依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向具体 Actor 的 PromptManager 选择修复。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:66 / 177;这是提交图计数,不是新增功能数。 |
Agentcodex/agentic-v2-context-governance9/17 14:25–14:27 完整列表记录:09/17 14:26:56 北京时间 | 功能 普通 Agentic 可与 Compact 配合治理上下文:enforce 才让后台使用压缩摘要及保留历史,shadow 主要观察而仍按原历史规划。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #69 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:26:56(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:普通 Agentic V2 与 Compact 的上下文治理接线,决定后台实际使用原始历史还是压缩材料。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/planning/runtime.ts 历史列表 ahead / behind:1 / 164;这是提交图计数,不是新增功能数。 |
Agentcodex/roleplay-compact-v19/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 长对话在预算触发时可把早期历史压成事实、互动与未完线索摘要,为当前回复保留近期消息和输出空间;不是完整聊天永久记忆。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #68 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:针对 RP 长对话触发历史压缩、保留近期消息与回复空间,是具体应用上下文策略。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/memory/compact-runtime.ts 历史列表 ahead / behind:0 / 165;这是提交图计数,不是新增功能数。 |
Agentcodex/roleplay-compact-evidence-eval9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 评测 已关闭的 Compact 证据和评估主题;未全文阅读,不推断新增工具。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #83 | 仅列表依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 分支表;Compact 证据/评估主题,未全文审,不作为已确认新工具 分类依据:名称及列表说明指向 RP Compact 证据评估,属于该对话策略的评测工作。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:15 / 167;这是提交图计数,不是新增功能数。 |
Agentfix/agentic-state-budget-80009/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 普通 Director 状态候选默认及校验上限为8000字符;这是持续状态块的限制,不是模型完整上下文窗口或所有记忆总容量。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #82 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:约束普通 Agentic Director 状态候选长度,针对具体持续状态流程。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/planning/agentic-v2.ts 历史列表 ahead / behind:1 / 178;这是提交图计数,不是新增功能数。 |
Agent Harnessagent/npc-persona-context9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 专家输入明确区分主角色定义与当前用户 Persona,帮助判断人物身份和视角;Persona 不自动成为 NPC 资料,也不应无证据写成持久事实。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #81 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:业务目标是让 RP 专家正确区分主角色和用户 Persona;实现落在共享 context-compiler,主归角色业务修复并关联 Harness 组件。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/context-compiler.ts 历史列表 ahead / behind:0 / 179;这是提交图计数,不是新增功能数。 |
Agentagent/keep-latest-ledger9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 状态投影读取最近的有效 ledger 记录并按类型选取有界条目,使后续模型能看到较新的连续性建议;不保证所有历史记录都进入本轮。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #80 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:普通 Agentic 状态投影使用最近有效 ledger,影响后续角色回复可见的连续性资料。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 packages/tools/src/context-compiler.ts 历史列表 ahead / behind:1 / 181;这是提交图计数,不是新增功能数。 |
Agentagent/fix-autoreply-global-turn9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 快捷回复按目标 sourceMessageId 查匹配的后台 guidance 并短暂等待,不只取一个会话级最新轮次,减少给旧消息生成建议时错用其他轮状态。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #79 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:按目标消息匹配后台 guidance,避免给旧消息生成快捷回复时使用其他轮状态。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/planning/auto-reply.ts 历史列表 ahead / behind:1 / 182;这是提交图计数,不是新增功能数。 |
Agentcodex/agentic-debug-progress9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 后台运行可报告规划阶段与调试节点,帮助看到协调/专家/提交的进展;这些观测写入失败不应阻断正文或正式状态保存。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #75 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:报告普通 Agentic 后台的协调、专家与提交阶段,观测对象是具体 RP 状态流程。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/planning/runtime.ts 历史列表 ahead / behind:2 / 185;这是提交图计数,不是新增功能数。 |
Agentfix/agentic-short-language-codes9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 语言宏同时识别完整地区代码与基础语言代码,找不到映射时回到 English,减少短语言码被错误当作默认语言。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #74 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:修正 Agentic 语言宏对短语言码的识别,影响应用回复语言输入。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/planning/prompt-template.ts 历史列表 ahead / behind:1 / 185;这是提交图计数,不是新增功能数。 |
Agentdocs/agentic-actor-prompt-manager-id9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 文档 已关闭的 Actor PromptManager ID 文档主题;现有记录仅列表。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #71 | 仅列表依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 分支表;文档主题 分类依据:名称及列表说明指向 Agentic Actor 的 PromptManager ID 文档,说明对象是具体应用配置。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 187;这是提交图计数,不是新增功能数。 |
Agentcodex/production-pioneer-ingress-topology9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 部署 名称指向生产 Pioneer 入口拓扑调整,具体差异未核;不能据分支名补造路由、集群或当前暴露方式。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #58 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Pioneer Agent 生产入口拓扑,按专用应用部署归类;不推定实际路由和启用状态。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 206;这是提交图计数,不是新增功能数。 |
Agentcodex/pioneer-ingress-timeout9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 部署 名称指向 Pioneer 入口超时设置,具体差异未核;未确认具体超时数值和对慢请求的实际效果。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #57 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Pioneer Agent 入口超时配置,属于专用应用运行维护。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 207;这是提交图计数,不是新增功能数。 |
Agentcodex/agentic-parity-remediation9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复 名称指向 Agentic 与已有基线行为的对齐整改,具体差异未核;不能将“parity”当作所有线上行为已完全一致的验证结论。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #56 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向具体 Agentic 与已有产品基线的行为对齐,不据名称认定全部行为已验证一致。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:17 / 208;这是提交图计数,不是新增功能数。 |
Agentfix/agentic-director-repair-cost-telemetry9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 修复/调整 已关闭的 Director 修复及费用观测主题;未全文阅读,不证明其差异尚未进 main。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Closed #54 | 仅列表依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 分支表;Director 修复/费用观测主题,未全文审,不作为已确认新工具 分类依据:名称及列表说明指向普通 Agentic Director 修复及其费用观测,归具体后台状态流程。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:3 / 209;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/go-diary-orchestrator9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 对启用日记来源的完整对话安排后台日记任务,读取日记生成策略与轮次条件,生成并保存记录,再按规则处理合并摘要等后续工作。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #25 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:当前对应实现按启用的会话日记来源生成并保存日记,属于 RP 应用的记忆业务编排;不是通用 Workflow 引擎。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/memory/diary-orchestrator.ts apps/emochi/memory/axon-memory-runtime.ts 历史列表 ahead / behind:4 / 240;这是提交图计数,不是新增功能数。 |
Agent Harnesscodex/go-memory-workflow-client9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 按启用的来源从 Axon 召回日记摘要及记忆表;完成回复后按接线安排日记和表格写入,不因模块存在就每轮查询所有记忆。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #24 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:当前对应实现为 RP 应用显式召回日记/记忆表并安排写入,按具体记忆接线归类;名字含 Workflow 不代表共用工作流运行时。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 apps/emochi/memory/axon-memory-runtime.ts 历史列表 ahead / behind:1 / 241;这是提交图计数,不是新增功能数。 |
Agent Harnessagent/consume-closed-loop-context9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 闭环请求携带用户、会话、角色及对话材料后,应用按选中方案装配角色输入、记忆、Actor和所选状态流程;与上游已经准备好消息的直接模型路径分开。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #10 | 主线对应源码已读依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 用途依据已读main对应实现/既有源码审阅,未核该分支完整diff及合并目标;不是分支独有增量的断言。 分类依据:闭环 RP 请求由应用装配角色、记忆、Actor 及状态流程;路由和输入适配为基础组件关联。 归类依据已留存主线对应实现说明,不替代该分支历史差异核验。 adapters/agent-router/dispatch.ts 历史列表 ahead / behind:1 / 257;这是提交图计数,不是新增功能数。 |
Agenteval/cookie-clove-rp-memory9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 评测 名称指向 Cookie/Clove RP 记忆评测,具体差异未核;这是评测主题,不应被作为当前全项目默认记忆能力。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #3 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Cookie/Clove RP 记忆评测,属于角色对话应用效果验证。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:27 / 264;这是提交图计数,不是新增功能数。 |
Harnessagent/update-actions-v79/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 部署 名称指向 GitHub Actions v7 更新,具体差异未核;不对应新增玩家功能。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #2 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向通用 GitHub Actions 升级;前缀 agent 不把仓库 CI 变成玩家 Agent 能力。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 265;这是提交图计数,不是新增功能数。 |
Harness Agentagent/phase-1-harness9/17 14:25–14:27 完整列表记录:09/17 14:27:06 北京时间 | 功能 名称指向 Harness 第一阶段框架,具体差异未核;今日完整快慢、Story和世界书能力不能倒推为这一初始分支已具备。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #1 | 仅名称依据与范围分支/PR 记录时点:09/17 14:27:06(北京时间)。 仅根据精确分支名解释主题;没有声称读过该分支提交或实现。 分类依据:名称指向 Harness 初期框架阶段,以基础组件归类;不倒推其已经包含后来全部业务。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:2 / 266;这是提交图计数,不是新增功能数。 |
Agentfix/yuzu-narrative-staging9/17 后续补录记录:09/17 19:36:01 北京时间 | 功能 融合图文聊天增加 Yuzu 模型选择及回执隔离;钱包 model_tier 仍为 Aoi。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #170 | 定向差异已读依据与范围分支/PR 记录时点:09/17 19:36:01(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 原记录目标: 分支名由原始 PR/合并记录恢复;代码阅读范围及部署边界见对应章节。 分类依据:融合图文聊天中的 Yuzu 模型选择、回执隔离与钱包层级边界,属于具体 Agent 运行方案。 |
Agentboyn/sumi-image-persistence9/17 后续补录记录:09/17 19:33:02 北京时间 | 功能 Sumi 每张图完成后另存图片历史;符合审核条件的成功图再进入图库。聊天显示图片与图库归档分别完成,外部归档接口仍需可用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #171 | 主线实现已读依据与范围分支/PR 记录时点:09/17 19:33:02(北京时间)。 原记录目标: 分支名由原始 PR/合并记录恢复;代码阅读范围及部署边界见对应章节。 分类依据:Sumi 图片历史保存及符合审核条件后的图库归档,属于该图文应用结果持久化。 |
Worldbook Agentboyn/worldbook-demo-associations9/17 后续补录记录:09/17 19:35:31 北京时间 | 功能 提案:浏览器按用户管理 Prompt 与世界书绑定,同时保留会话固定版本。尚未逐读实现。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #172 | 仅 PR 描述与清单依据与范围分支/PR 记录时点:09/17 19:35:31(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 原记录目标: 分支名由原始 PR/合并记录恢复;代码阅读范围及部署边界见对应章节。 分类依据:已留存提案是用户 Prompt 与世界书的浏览器绑定及会话版本规则;按世界书关联管理归类,尚未逐读实现。 此处按已留存 PR 提案暂归类,不代表实现已核验。 |
Agentcodex/persist-sumi-telemetry9/17 后续补录记录:09/17 19:35:40 北京时间 | 部署 Sumi 测试部署更新镜像时同时保留观测开关并检查配置;不代表生产观测已启用。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Open #173 | 工作流差异已读依据与范围分支/PR 记录时点:09/17 19:35:40(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 原记录目标: 分支名由原始 PR/合并记录恢复;代码阅读范围及部署边界见对应章节。 分类依据:Sumi 测试部署保留观测开关的专用发布修复,不能因使用工作流就归成通用 Harness 发布。 |
Agentboyn/sumi-image-event-dimensions9/17 后续补录记录:09/17 21:14:51 北京时间 | 修复 给客户端发送图片开始生成的信号,并在完成通知里带上本次请求的图片宽高;尺寸来自请求,非重新测量成品像素。复用旧结果不补发开始事件。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #176 | 主线实现已读依据与范围分支/PR 记录时点:09/17 21:14:51(北京时间)。 原记录目标: 分支名由原始 PR/合并记录恢复;代码阅读范围及部署边界见对应章节。 分类依据:Sumi 图片开始通知与完成通知尺寸字段,属于客户端图文交付协议。 |
Harness Agentcodex/compact-jev-history-filter9/22 已完成巡检更新记录:09/22 08:42:00 北京时间 | 功能 Compact 摘要前可用 Jev 筛完整对话组;#196 已合入 main,默认 off;#198 另加助手段落过滤与边界搜索。供应商超限回退恢复原输入;语义误省略需验收。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #196 | 合入主干及当前调用链已读依据与范围分支/PR 记录时点:09/22 08:42:00(北京时间)。 已核源码版本(不据此推定列表当时的分支指针): 原记录目标: 保留原分支名;合入63d27c40,当前a4f5bb83定向核对。旧2dc1cbe8仅为9/21 Draft版本,不代表当前状态。 分类依据:应用 Compact 的上下文准备与检查点治理;Jev 分类供角色回复前的压缩流程使用,非专家菜单或通用 SDK 新接口。 |
worldbook-service:8 条完整快照
| 真实 Git 分支 | 做什么、对应什么业务变化 | PR 记录 | 核查程度 |
|---|---|---|---|
Worldbook Harness Agentmain9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 主线 世界书导入、保存、修订、检索、条目选择及上下文块输出的主线,另有可选向量索引和管理接口。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | 主线 | 固定主干代码已审依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 后续已读主线源码基线(与上述列表时点分开): 14:23 主干为 b0af622;同日 21:15 已核主干前进至 9edea528。晚间 #9/#10 不计入 14:23 的分支清单。 分类依据:整个仓库主线的业务对象就是世界书导入、修订、检索、选条和上下文块输出,因此归 Worldbook;Harness/Agent 是接入方,不把专门服务主线误当跨三类总仓。 |
Worldbook Harness Agentboyn/worldbook-placement9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 上下文装配协议 保留八种条目插入位置,并让宿主声明本轮可用位置/插槽;服务据此筛选并返回可组装进 Prompt 的 blocks。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #8 | PR 与相关实现已定向审读依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 已于 11:16 合入 b0af622;9edea528 的相关 models/selection/importer 页面仍以 b0af622 为最近修改,主线行为亦已复核。 分类依据:服务保留条目插入位置并按宿主可用插槽筛选、输出 blocks,属于世界书数据和选条合同;宿主负责后续组装。 原有角色前、角色后、at_depth,加上示例前、示例后、作者注释顶部/底部、命名 outlet,共八种。原生条目与导入器保留位置,outlet_name 必须合法。 placement_capabilities 由宿主声明可用位置与 outlet。可选条目无处可放返回 placement_unavailable;通过其余资格检查的 required 条目无处可放则报 required_placement_unavailable。 不传 capabilities 按旧三种位置处理;显式空 positions 表示没有位置。 服务返回 blocks 及位置,宿主负责实际 messages/模板组装;聚合 context 顺序不是最终 Prompt 顺序。选择/导入策略标识为 native-bounded-v2/st-inert-v2。 旧 revision 不自动迁移。重新 preview 原文件、发布完整新 revision,必要时建索引,再显式升级 pin;重复文件上传会去重,不能代替迁移。 历史列表 ahead / behind:2 / 1;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-admin-match-debug9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 管理调试接口 管理端显式指定租户、书、版本和测试输入,查看本轮会选中哪些条目及其原因。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #7 | PR 与相关实现已定向审读依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 已于 01:14 合入 f8d05b1,早于清单基线;晚间 9edea528 固定 app.py 也保留此接口。 分类依据:世界书管理端的选条测试与命中原因查看,属于资料管理和诊断能力。 POST /v1/admin/context/select 接收 {tenant_id, selection: SelectRequest},调用已有 service.context(body.tenant_id, body.selection)。 按同一套 rules/hybrid 选择,返回 blocks、context、选择理由、预算及降级信息;普通接口仍使用服务配置的 tenant。 它调试已保存条目,不生成 NPC 小卡、不写世界状态、不建索引、不生成聊天正文;hybrid 仍可能调用 query embedding。 历史列表 ahead / behind:1 / 2;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-cd-image-only9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 发布流程 发布流程修复:提交标题明确为仅更新 worldbook 镜像;具体工作流步骤未逐行复核。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #6 | 列表与 main 提交标题已核;该分支实现未全读依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 14:23 列表显示 #6 已合并;9/16 main 已是 #6 的 3a11e333。不能据此宣称实际部署已验证。 分类依据:发布工作流专门更新世界书服务镜像,按世界书服务运维归类,不扩大为通用 Harness 发布机制。 归类依据列表及提交标题,不代表完整实现已核验。 历史列表 ahead / behind:1 / 3;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-service-cd9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 发布流程(按名称归类) 分支名指向 worldbook-service 持续部署。仅确认名称和 #5 已合并,未恢复具体新增工作流/部署步骤。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #5 | 仅历史分支列表依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 14:23 关联 PR #5 为 Merged。未复核该分支完整历史 diff 或当前 head;ahead 不表示仍有待合并功能。 分类依据:名称及历史列表指向世界书专用持续部署,按服务自身运维归类。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 4;这是提交图计数,不是新增功能数。 |
Worldbookboyn/worldbook-no-auth9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 认证接入(按名称归类) 分支名指向服务认证处理。仅确认名称和 #3 已合并,未复原原始 diff,不能将当前所有认证行为都归因于这个 PR。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #3 | 仅历史分支列表;当前 main 认证边界另有源码审计依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 14:23 关联 PR #3 为 Merged。9edea528 本身无请求认证是另行核实的主干事实,不能冒充已经完整审读 #3。 分类依据:名称及历史列表指向世界书服务认证处理,按世界书访问边界归类;当前 main 审计不能替代该分支 diff。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 6;这是提交图计数,不是新增功能数。 |
Worldbookboyn/remove-worldbook-traces9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 观测清理(按名称归类) 分支名指向移除 worldbook traces。仅确认名称和 #2 已合并;未确认具体删除了哪些字段、调用或采集。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #2 | 仅历史分支列表依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 14:23 关联 PR #2 为 Merged。未复核该分支完整历史 diff、当前 head 或生产可观测性配置。 分类依据:名称及历史列表指向世界书 traces 清理,属于世界书服务观测范围,具体删改未核。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:1 / 7;这是提交图计数,不是新增功能数。 |
Worldbook Harness Agentboyn/worldbook-integration9/17 14:23 完整列表记录:09/17 14:23:00 北京时间 | 集成(按名称归类) 分支名指向世界书集成。仅确认名称和 #1 已合并;主干能力另有审计,但未重建这条分支五个提交的具体边界。相关实现/历史说明(按该章基线,非自动等同旧分支增量) | Merged #1 | 仅历史分支列表依据与范围分支/PR 记录时点:09/17 14:23:00(北京时间)。 14:23 关联 PR #1 为 Merged。不能把后来主干的所有世界书能力都归为这个 PR,也不据 ahead=5 判断有五项未合并能力。 分类依据:名称及历史列表指向世界书服务集成,按世界书业务目录归类;不能将后来主干全部能力归入这条历史分支。 此处仅依现有名称/列表主题暂归类,不代表已完成该分支代码核验。 历史列表 ahead / behind:5 / 8;这是提交图计数,不是新增功能数。 |
后续变更还有尚未恢复完整分支名的项目:Harness #177 已进入固定主干,保存 Sumi 图片归档时的正文快照;Worldbook #9/#10 已进入固定主干,分别涉及向量配置与重索引、管理端按租户导入和索引。它们继续保留在原实现章节、世界书章节和唯一变更记录,不猜一个分支名填表。
下载本目录的数据记录。记录包含名字、PR 状态、核查程度、业务说明、已知版本和来源范围;不包含私人会话原文。
继续下探:这些分支中的代码分别由哪个仓库、应用和外部服务负责
Roleplay 现状总览已经把输入、回复、保存和后续使用连成整体。本章进一步说明:这条业务链中的哪些工作由 Harness 完成,哪些来自世界书服务,哪些需要外部业务保存和提供。
两个仓库分别交付什么
| 项目 | 已有内容 | 业务怎样用它 |
|---|---|---|
| roleplay-harness | 通用 Agent 执行组件、可调用工具,以及仓内已经组合好的文字 RP、剧情和图文应用 | 可以取一个工具、组织自己的 Agent 或 Workflow,也可以采用仓内应用的现成执行流程 |
| worldbook-service | 世界书文件导入与规范化、书籍和不可变内容版本、索引、搜索、本轮条目选择 | 作者先准备和发布设定;聊天接入方指定书籍版本及本轮材料,服务返回应交给模型的条目原文和选取说明 |
两者合作时,世界书服务负责找出适用资料,Harness 负责把返回内容放到正确的模型输入位置,再执行本轮回复。聊天中发生的新事件,不会因为这轮查询了世界书就自动写回作者的条目。
Axon、聊天服务、模型网关及部分外部记忆/图片服务不属于这两个仓库的全部源码范围。下面会区分“仓库里已有实现”和“仓库只调用外部接口”,不把接口存在当作外部功能已经逐项验证。
Harness 内部有三层,不是一个固定流程
**第一层是通用执行组件。**业务提供输入准备、模型、工具和结果解释方式,可以让模型判断下一步并调用工具;也可以把一次 Agent 调用放入既定 Workflow。SDK 还提供现成的单次文本调用、受约束的分析执行,以及当前输出与后台处理并行的组合。这些是可选用法,没有要求所有业务先走快慢系统。
**第二层是工具。**仓库封装了人物与剧情分析、读取/写入 JSON 记录、世界与叙事操作、图像等能力。工具需要实际注册,并得到相应材料、模型或存储接口,才会被某次执行使用。某个工具内部可以再调用模型;某些操作直接访问存储。工具名不决定它一定在本轮前台还是后台执行。
**第三层是现成应用。**这些应用把输入准备、工具调用、保存及产品结果接到一起。文字 RP 相关实现在 apps/emochi,独立图文实现在 apps/sumi;目录名说明代码位置,不代表用户必须先理解或接入同名产品。
| 现成运行方式 | 用户输入之后主要做什么 | 交付与保存 |
|---|---|---|
| 直接回复 | 使用准备好的角色和对话材料调用回复模型 | 当前正文;消息保存由对应聊天接入负责 |
| 回复+普通 Agentic 后台 | 当前回复与后台分析从同轮材料出发;后台按需咨询专家、整理状态 | 本轮正文;经检查和保存的持续状态供后续读取 |
| 前台工具循环 | 本轮控制模型安排写正文、图片或长期指令等已注册动作,并读取结果决定后续动作 | 本轮文字/图片任务等;可与普通后台按配置协作 |
| Story 剧情流程 | 读取已采用的上轮正文,维护世界与叙事进度,再准备本轮可推进的事件 | 当前正文、待核对正文记录、世界/叙事快照;当前接线替换普通六专家后台 |
| Sumi 图文流程 | 用历史及已有场景/人物资料生成新正文、更新资料和绘图描述 | 按消息保存的图文状态及图片交付;有自己的协议和生命周期 |
世界书、日记、记忆表和历史压缩属于可以接入执行流程的资料能力;它们各有调用条件。**一张能力清单不能被当成一次请求的必经步骤。**哪些组合允许、入口怎样选择,集中在执行方式与组合;本轮每个模型实际拿到的内容集中在上下文组装。
从业务结果追到具体记录
用同一个世界说明不同内容的归属:作者设定“北塔需要城主手令”,用户在聊天中借走铜钥匙,后来又归还。三件事会进入不同的资料流程。
| 需要保留的内容 | 属于哪条资料流程 | 什么时候再次产生作用 |
|---|---|---|
| “北塔需要城主手令” | 作者发布的世界书条目及内容版本 | 本轮被选中、放进模型请求后,影响这次生成 |
| “用户刚才说已归还钥匙” | 已保存的聊天消息 | 后续请求带回且保留这段原文时,模型能读到 |
| “钥匙已归还,找人约定未完成” | 选用的状态/记忆流程:普通 Agentic、Story、Sumi、日记或表格各有自己的产物 | 对应流程成功保存,并由后续消费者读取;它们不会自动互相同步 |
| “哪些旧对话已经被压成摘要” | Compact 压缩记录 | 通过覆盖与内容检查后,用于后续输入准备 |
| “本轮为什么选了手令规则、没选其他条目” | 本次世界书选择结果与诊断记录 | 用于本轮装配与排查;本次核对的世界书版本没有将它保存成跨轮冷却或持续激活状态 |
记忆与资料生命周期逐项说明这些记录的输入、产物、保存位置、读取者和失败结果。世界书导入、选择、注入的完整流程在世界书主题组;不会要求读者从一个型号的部署配置推断整个项目的能力。
实现入口与证据
| 要找的内容 | 仓库中的位置 |
|---|---|
| 通用 Agent、快慢组合、工具目录、任务与观测 | roleplay-harness/packages/sdk |
| 可复用工具及其模型/存储接口 | roleplay-harness/packages/tools |
| 文字 RP 的角色、回复、后台、记忆、Story 与世界书接线 | roleplay-harness/apps/emochi、adapters/agent-router |
| 独立图文状态与图片交付 | roleplay-harness/apps/sumi |
| 世界书导入、内容版本、选择规则、索引与选择诊断 | worldbook-service/src/worldbook |
本 Wiki 按固定源码解释已有行为,候选分支和历史变更单独列出。配置文件是应用的一种使用实例,实际某段会话是否加载并运行它,需要运行配置及结果记录确认。
整体闭环的代码证据 · 17 处
能力与工具目录的代码证据 · 44 处
- 预选 skill 的可复用实现 ↗
- 图片使用已有资料的接线 ↗
- 六工具的名字与职责 ↗
- 岗位提示词装配 ↗
- 分工与工具执行 ↗
- Director 读取建议并生成笔记 ↗
- 普通 Agentic V2 的装配入口 ↗
- 读取状态并分别准备材料 ↗
- 每个逻辑轮安排后台 ↗
- 协调器执行专家并读回结果 ↗
- 校验和提交状态 ↗
- 状态读取和保存接口 ↗
- 工具生命周期定义 ↗
- Story 与普通后台二选一装配 ↗
- 读取上一条保存正文并准备本轮场景 ↗
- 采用正文推进世界及保存 pendingActor ↗
- 基础 Actor 回退、重生成和状态接线 ↗
- World 实际工具 ↗
- Narrative 计划、派发和结算 ↗
- 按可见消息、正文及用户锚点选状态 ↗
- 等待正文保存、挂接快照及版本提交 ↗
- 图文请求入口和交付 ↗
- 图片准备 ↗
- 实际生成与尝试记录 ↗
- 无匹配锚点后的初始状态回退 ↗
- 没有提交新状态时挂接旧快照 ↗
- main 原有 Pioneer 接口 ↗
- 格式变更范围、实现文件及 staging 操作记录 ↗
- 文字流与最终消息入口 ↗
- 增量正文先保存再推送 ↗
- 最终保存与交付 ↗
- 原生消息读写与私有元数据 ↗
- 图片保存和事件交付 ↗
- #78 固定旧头的 Actor 循环 ↗
- 旧参数与预算执行 ↗
- 旧 DIO 接入 ↗
- 旧 Imagine 接入 ↗
- main 当前前台工具 schema ↗
- 当前 DIO 的后续读取 ↗
- 仓库交付与目录 ↗
- 通用执行组件导出 ↗
- 普通回复与后台接线 ↗
- 世界书应用组合限制 ↗
- 世界书选择服务 ↗
2. 两轮完整演示:用户递出钥匙以后,回复、后台记录和下一句怎样接起来
这章只走一套已经有代码接线的组合:回复前选世界书,回复模型写当前正文,普通 Agentic 后台并行维护后续状态。 艾琳是用户选择的主角色;北塔守卫是此前已出现的配角。回复模型可以描写艾琳、守卫和环境,不替用户决定下一步。
本例的第一句是“我把铜钥匙递给北塔守卫,请他开门”,第二句是“手令该找谁开”。我们逐步跟踪:程序拿到的原材料、给不同模型的输入、工具返回、保存记录,以及第二句实际如何使用它们。
**角色、世界书原文、台词、工具选择和版本号都是教学示例,不是线上实测。**普通后台与 Actor 保留原固定源码依据;世界书取书环节当前按 Entity 接口逐轮解析,现有 RP 仍使用 promptId 作为对象编号,见当前绑定过程。它不是对所有配置或生产部署的承诺。本例没有开启外部日记、表格记忆、历史压缩、图片、前台工具循环或 Story;仍然会使用聊天历史和普通后台状态。
1. 点击发送前:业务已经选好执行方式,聊天也有旧记录
用户发来:
我把铜钥匙递给北塔守卫,请他开门。
接入业务同时提供用户、会话、所用角色和执行方案,程序才能取到这段聊天对应的资料。这里的执行方案是“世界书+普通后台”,代码名称为 agentic-v2-worldbook。它是产品事先选择的功能组合;不是先让一个模型读这句话,再决定整条请求只走快路或只走慢路。
这套方案已经配置:写回复的模型、决定后台检查任务的模型、六类专家检查、需要时整理状态的 Director,以及世界书选择服务。六类检查都可供选择,不代表每轮都要执行。世界书组合还受代码约束,不能直接同时叠加前台工具循环、Story 或 Sumi;未配置额外记忆和压缩只是这份方案的事实,不能推出世界书从原理上排斥一切记忆能力。
本轮准备时,取得以下已存在内容:
| 材料从哪来 | 这次实际内容 | 用来回答什么问题 |
|---|---|---|
| 作者的艾琳角色设定 | “艾琳是旧城向导,谨慎、话不多,正陪用户前往北塔;不替用户决定行动,不凭空知道秘密。” | 谁在陪用户,应该怎样表现 |
| 本会话已保存的状态,第 12 版 | “用户与艾琳在北塔门外;铁门关闭;门口是此前交谈过的同一名守卫。铜钥匙在用户手中;没有证据说明守卫知道钥匙的来源。” | 已经确认的地点、人物和物品关系是什么 |
| 请求提供的近期聊天原文 | 用户:“我们又回到北塔门口了,铜钥匙还在我这里。”上一条回复:“守卫认出了你,在岗亭旁站直。‘又来了?’艾琳停在你身侧。” | 刚才实际说过什么、怎么接这句话 |
| 用户本轮输入 | “我把铜钥匙递给北塔守卫,请他开门。” | 用户现在已经做了什么、希望得到什么回应 |
第 12 版是记录的保存版本,不是第 12 轮聊天。 这份后台状态在下文称为“笔记”:既可记录连续性事实和未知事项,也可保存后续怎么演的软建议,不能把建议当成已经发生的剧情。
本例没有另设用户 Persona。若提供“用户扮演外乡学徒”,那是用户身份资料,不能抄成艾琳或守卫的身份,更不能据此编出两人已经经历的事件。角色开场白也是一份已有材料;专家和 Director 会单独收到它,不等于本轮新正文。
2. 回复前:选回世界书原文,分别给回复与后台准备材料
程序先核对会话身份,再按本轮角色 Prompt 的关联解析出书籍及具体版本(同轮重试复用,下一轮重新解析),把本轮原始输入、排除当前消息后的近期历史、可用条件和预算交给世界书服务。服务端hybrid只为相关性排名补入最近两条非空历史,不把旧状态的公开场景拼进query。服务决定哪些已有条目本轮适用,Harness 再将返回原文放进回复模型的输入。
假设这次选回三条:
| 条目 | 实际加入本轮回复材料的文字 |
|---|---|
| 常驻的地点背景 | “北塔是旧城封闭区域的入口。塔门是铁栅门,门外设有守卫岗亭。” |
| 本轮选中的通行规则 | “持有铜钥匙仍须出示加盖城主印章的手令;手令在市政厅登记处申请。这项守门规则已告知当班守卫。” |
| 本轮选中的秘密及知情边界 | “北塔封存着危险的回声装置。真正用途只有城主和塔内书记知道;门口守卫不知道装置的存在。” |
三条是本例的选择结果,不是每轮固定选三条,也不是回复模型临时编三条资料。 “注入”就是将这些文字加入本次模型请求;没有训练模型永久记住整本书。条目选中后,还要符合放置位置与完整输入预算,才能真的进入模型材料。
随后形成两份用途不同的输入:
| 谁读取 | 收到什么 | 尚未收到什么 |
|---|---|---|
| 回复模型 Actor:写用户看得到的正文 | 自己的写作说明、模板实际使用的角色资料/历史/本轮输入、程序放入的旧状态、三条世界书原文 | 后台还没生成的新状态 |
| 后台分工模型 Orchestrator:决定检查哪些问题 | 自己的岗位说明、角色资料、旧状态和已有分类记录、保留的历史、本轮输入,以及可选工具菜单 | 本轮三条世界书原文;Actor 尚未生成的新正文 |
两边的历史长度和状态投放范围不保证相同。角色等资料成为模板变量,不等于模板必然使用了全部字段;本例假设回复模板确实引用了艾琳设定和当前问题。要查看这张表背后真正发出的材料,可直接看模型请求示例、每个岗位拿到什么和窗口及裁剪由谁配置,不用从“准备材料”自行猜下一层。
后台没有复制那份已装好世界书的回复请求。 如果“还需手令”只存在于本轮选中的条目,它就不能被描述成后台已经知道的规则。若同一规则早已出现在角色定义或历史里,则属于另一份来源,本例没有作这个假设。回复模型能读到回声装置秘密,也不代表故事里的守卫知道;条目同时限制了谁有知情资格。
3. 开始生成:当前回复与后台分析并行,产物各不相同
准备成功、实际进入正文生成时,程序安排一次后台工作,再开始 Actor 生成。这里的“快”“慢”表示当前回复与后续连续性两种职责,不保证哪边先完成;当前正文不需要统一等待后台保存。
Actor 用刚才那份材料接住递钥匙动作。本例选择这一种可能回复:
守卫接住你递来的铜钥匙,看了一眼,却没有转身开门。
“手令呢?光有钥匙还不行。”
艾琳停在你身侧,等着你回应。
这段正文交给聊天业务展示和保存。允许直接流式交付时,用户可能边生成边看到;需要后处理的路径也可能先缓冲。模型写完、用户看到、聊天服务保存成功,是不同的完成事件。
与此同时,后台只知道:用户已经递出钥匙并请求开门;旧材料尚未提供守卫本次的回应。用户明确做了“递出”,不能降格为“只是打算递”;但守卫是否接收、是否放行,不能由用户的请求自动推定。
Actor 新增的“守卫接住”及“要求手令”此时没有自动进入后台。后台这趟工作也不是等正文完成后再总结。它每个成功进入生成的逻辑轮都会被安排,但可以无须专家、无须更新而结束,不是攒满固定若干轮才统一唤醒。
4. 后台执行:先选具体检查,再把检查结果交回来
本例不是首轮,也没有新名字。假设后台分工模型认为钥匙交接和知情范围值得检查,提出两项任务:
| 准备调用谁 | 为什么调用 | 具体要检查什么 |
|---|---|---|
人物检查工具 judge_npc |
旧人物参与了新的交接动作 | 仍是原来的守卫;用户已递出,但不能提前替守卫接收或开门;不补无依据的身世和性格 |
知识检查工具 audit_knowledge |
需要分清看见钥匙与知道来历、请求与获准 | 守卫知道钥匙来源吗;有放行证据吗;本次材料是否提供了完整通行规则 |
模型交的是程序能解析的工具名和参数。只在普通文字中写“最好检查一下”,不会自动执行工具。Harness 读取任务、找到已登记实现,再补入角色和开场、用户资料(如有)、旧状态、历史、本轮输入以及专项岗位说明,发起专家模型调用。两个专家可以并行,各自做分析,不自动共享尚未返回的另一位专家结果。
人物检查可能交回:
沿用此前的北塔守卫,不新增人物。用户本轮已向他递出钥匙并请求开门;本次检查材料还没有守卫接收或放行的回应。没有足够资料新增其性格、身世或隐藏动机。
知识检查可能交回:
已确认用户递出钥匙。守卫知道来历、用户获准通行都缺少证据。本次材料未提供完整通行规则,不能断言“有钥匙就能进”,也不能凭空补出“还要手令”。
这些是给后续判断用的建议。专家调用没有让守卫实际开门,也没有创建永久人物卡、编辑世界书或直接保存正式状态。回执显示“成功”,表示工具交回了结果,不表示建议已经被证明正确或被数据库采用。
两项工具是本例的模型选择,不是“出现钥匙就必叫两位专家”的规则。首轮或程序识别到新名字时,还可能强制补入检查;需要保留这一条件,不能将实际调用全部归为模型自由选择。
5. 看过结果后:决定是否请 Director 整理整份新状态
本例执行了专家,且允许使用状态整理工具,所以程序让分工模型再看一次:原来的本轮材料、刚才两项调用、各自的成功或失败结果。第二次菜单只剩状态整理入口,不再任意打开下一批专家。
假设它决定更新,给出理由:
把“用户持有钥匙”推进为“用户已递出钥匙并请求开门”。保留守卫回应尚未进入本次材料的边界,不新增无依据的人物身份、知识和通行规则。
程序通过 update_director_state 调用 Director——负责整理剧情状态的模型岗位。Director 由专用工作说明、配置选定的模型和这个工具入口共同实现,不是故事里的导演人物,也不是存储服务。它收到角色与开场、可选用户身份、旧状态、历史、本轮输入、更新理由及专家结果,写出一整份可以替换旧状态的新稿。
专家各自只分析一个方面。Director 要保留仍有效的旧内容,把零散建议整理成统一状态,而不只是把两份建议拼接,或返回“检查完成”。这一稿同时区分三类内容:
| 类型 | 本例新稿中的节选 | 留给后续回复的作用 |
|---|---|---|
| 已知事实与未知事项 | “仍是同一名守卫;用户已递出钥匙并请求开门;本次分析尚未见守卫回应,未确认已经入塔。” | 接住用户行动,防止把请求误记为成功 |
| 人物约束与仍有效目标 | “艾琳谨慎,不替用户做决定;尚无证据说明守卫知道钥匙来源。” | 保持人物和知识连续性 |
| 后续演绎的软建议 | “围绕当前通行请求自然继续;用户改变方向时跟随用户。” | 供模型参考,不自动安排必演剧情 |
这里只节选变化,真实提交需满足完整状态的格式和栏目。Director 不是只做聊天摘要:它还维护目标、未知事项和未来可选方向。新稿没有写“守卫已接住、已要求手令”,因为当前后台还没收到那段 Actor 新正文;这表示材料范围有限,不表示世界里不存在手令规则。
这一步的“复核”是分工模型看专家结果、决定是否整理。Director 写完后没有另一位 LLM 逐句检查剧情真伪;稍后的校验由程序执行。其他正常分支包括:无需专家而直接请 Director、咨询后决定不更新、没有工具而结束。不是每轮都必须跑完本例所有节点;完整分支条件放在下方展开项。
6. 分别交付:正文、状态和执行回执不是同一次保存
Director 交出的字段叫 candidateState,意思是待检查的新状态。Harness 检查长度、必需标题与顺序、内部标签及内容是否变化,再向存储提交。检查格式并不等于保证每条剧情判断正确。
这份稿子基于第 12 版。程序提交时要求存储仍符合原版本条件;如果另一份更新已经抢先保存,就不能拿旧稿直接覆盖。假设本次有效、有变化、提交成功,状态成为第 13 版:
| 这次交付的东西 | 保存或处理在哪里 | 何时真正有作用 |
|---|---|---|
| Actor 正文 | Harness 返回或流式交给聊天业务,由聊天链路保存助手消息;世界书 Demo 有保存消息接线 | 展示后用户能读;保存后还要由未来请求带回,才成为可再读的聊天历史 |
| 第 13 版持续状态 | 通过接入的 Axon 会话状态服务保存,由当前用户、会话和执行方案定位记录 | 后续请求准备时读到它,再放进模型输入;不倒灌当前已开始的正文 |
| 成功专家分析的分类记录 | 程序可随有效状态提交附属 ledger,标出来源;它不是另一个人物数据库 |
后续按规则筛选、裁剪后,才可能成为状态旁的参考材料 |
| 调用与结果、状态处理结果、用量 | 相应执行报告、诊断或记录通路,持久范围依字段和接线 | 用于判断调用完成、有没有保存,以及资源消耗;不是第二条角色回复 |
普通主线后台提交不先等待正文保存。 正文可能已经展示,后台还在分析;后台也可能先保存,正文稍后结束。不能把它想成读完用户已看到的台词后统一结算。
没走到保存成功时,应分别解释:
| 发生在哪一步 | 留下什么结果 |
|---|---|
| 准备失败,尚未进入生成 | 不会按本例开始当前回复与普通后台;不是每个到达 HTTP 接口的请求都会启动后台 |
| 无需更新,或新稿与旧稿相同 | 保留现有状态;“没有新版本”可能是正常结果 |
| 某专家正常返回失败说明 | 失败说明可以与其他结果一起交回;Director 仍可能基于剩余材料更新。若异常直接中断整批,则不能假定继续复核 |
| Director 调用失败或最终稿无效 | 没有这份有效的新状态提交,旧记录不会自动变成新稿 |
| 版本冲突被拒绝,或保存报错/超时 | 版本冲突被拒绝时不会覆盖较新记录;保存报错或超时需核对存储结果,不能仅凭失败回包认定已写入或完全没写入 |
| 正文失败、取消或尚未保存 | 正文交付与持久化需要单独确认;已启动的普通后台不因 Actor 取消而保证一同停止,也不能反过来用后台完成证明正文完成 |
| 新问题来得太快 | 下一轮可能仍读到第 12 版;保留的近期历史可能提供补充,但不能宣称已用上第 13 版 |
新状态不会改角色卡、世界书或 Persona,也不会凭一个人物工具调用变成可独立编辑的 NPC 小卡。候选分支增加的等待正文与消息关联属于另一版本边界,不纳入本例的主线成功条件。
7. 第二句到来:旧状态、已保存正文和本轮资料一起决定怎么接
假设第一轮的助手正文与第 13 版状态都已经保存成功。用户接着问:
我问守卫:手令该找谁开?
这是一次新请求。程序重新读取记录,也为这句新话重新选择世界书;不是让模型凭空记住上一次调用的全部材料。本轮得到:
| 本轮重新拿到什么 | 能知道什么 | 不能混淆的来源 |
|---|---|---|
| 第 13 版状态与允许带入的分类记录 | 同一名守卫;用户上一轮已递出钥匙;当时后台未收到回应 | “当时未收到”是上次分析的材料边界,不是后来仍未发生 |
| 上轮已保存并由新请求带回的正文 | 守卫已经接住钥匙,仍未开门,并问了“手令呢” | 这是上一轮 Actor 新写出的剧情,现在才通过历史进入后台也可见的材料 |
| 假设本轮再次选中的通行条目 | 手令在市政厅登记处申请,守卫被告知这项规则 | 办理地点来自本轮世界书,不是第 13 版自动学会了整本书 |
Actor 因此可以承接“守卫已经接收”,不重演用户递钥匙,也不擅自把用户写进塔内。可能回复:
“市政厅登记处。”守卫看着你,“拿到盖着城主印章的手令,再来找我。”
这轮后台现在也有机会从上一条保存正文读到“接住钥匙、要求手令”,据此整理上一版的待确认内容。它仍没自动拿到本轮世界书原文,也没拿到正在生成的第二轮答复;不能据此认定它已经知道市政厅办理地点。
程序负责把可用文字接回模型输入,模型决定如何使用。没有一个通用剧情语义校验器保证模型永远正确处理“较旧状态+较新历史”,或逐字遵守每项软建议。记录存在、成功进入本轮输入、模型实际采用,仍要分别判断。
8. 另外两种条件,不要拼进同一条主案例
分支 A:第一轮守卫没有接钥匙。 另一种同样可能的回复是:“守卫没有伸手。‘入塔要有城主印章的手令,去市政厅办理。’艾琳看着塔门:‘看来光有钥匙还不够。’”这一分支的用户接话可以是“那我收好钥匙,先去市政厅”。后续历史应带回的是“没有接”,不能同时套用上面主案例的“守卫已接住”。后台在第一轮仍因没有收到新正文而保留接收状态待确认;下一轮才有具体回应证据。
分支 B:第二轮没有选回办理地点。 如果当轮材料没有市政厅信息,历史或角色设定也没提供它,就不能保证 Actor 能回答那个地点。世界书是每轮按规则重新选择;上一轮用过,不等于以后每次永久带入。
普通状态没有变化、后台来不及、消息没成功保存,也都会改变第二轮的实际材料。图片、Story、人物卡和自动扩写世界书不是这条案例完成后自动获得的附赠能力;要改变组合,需要另接对应的输入、保存和回读流程。
同章展开:准确字段、执行条件与源码
查字段:请求怎样选方案,哪些是实际配置开关?
| 名称 | 用人话说 | 当前页面所依据的例子 | 谁提供 / 谁用 |
|---|---|---|---|
scenario_id |
产品为这一请求指定的执行方案编号,不是剧情地点名称 | agentic-v2-worldbook |
接入方随请求传入;Harness 查对应配置。不是协调器读完用户句子才决定这个编号 |
| scenario / 场景配置 | 这条执行方案到底启用了哪些能力、各岗位用哪份配置 | 启用回复、普通后台 Agentic V2、世界书;未配置压缩等能力 | 产品/开发维护;程序读取 |
| ModelConfig | 某个模型岗位该怎么调用模型的配置资源,服务会解析模型、提示词相关配置和生成参数 | roleplay-harness-agentic-v2-director 是 Director 使用的配置引用 |
运维/开发配置,程序解析;这个名称本身不能证明底层是哪个厂商模型、也不能证明生产可用 |
enabledTools |
交给协调器的可选工具菜单,以及部分强制规则/第二阶段是否允许更新的依据 | 此场景没单独写名单,解析后的默认菜单含六位专家和 Director | 配置/默认值提供;程序组工具菜单。菜单可选不等于每轮都会调用,也不能在此版本把它宣传成执行端再次校验的权限墙 |
hybrid |
世界书“混合选择方式”的配置名称 | Harness 把 strategy:"hybrid" 传给世界书服务 |
产品配置、世界书服务执行选择。仅凭 Harness 本地代码不能声称具体条目必然命中或每次一定调用某种外部检索 |
| token | 模型/检索计量文本长度的单位,不等于汉字数或条目数 | 同样 2400 token,可以容纳多少条取决于原文长短 | 按模型规则给文本计数的程序负责计量;用于限制输入长度 |
tokenBudget:2400 |
为本轮选回的世界书内容预留的长度预算 | 三条原文能否都放进来,仍取决于条目、选择和预算结果 | 产品配置;世界书服务控制返回内容。它不是整个模型请求总预算,也不是回复最多 2400 字 |
memorySources:[] |
这条方案没有打开额外的日记/表格等记忆来源 | 空列表 | 产品配置;程序按配置取材料。不是把聊天历史、Agentic 笔记或世界书一起关闭 |
| Compact / 对话压缩 | 对过长对话进行压缩整理的一套能力 | 当前这份场景未配置 | 产品/开发接入并配置才会使用;没开它仍可读取已有对话和笔记 |
| CAS / compare-and-set | 保存前先比旧版号:只有存储仍是我读的那一版,才能写入 | 基于第 12 版写稿,保存时若已是第 13 版,就拒绝这个旧稿覆盖 | 程序和存储执行;不是模型判断“我感觉版本没变” |
| review / 复核 | 必须说明“谁复核什么” | 本流程是协调器读专家建议,再决定是否叫 Director;Director 出稿后由程序检查格式/长度/版本 | 分别由模型和程序执行。这里没有一个额外模型逐句复审本轮玩家正文或最终笔记是否合乎世界观 |
| ReAct | 对“选动作→执行→读取结果→再决定下一步”这种工作方式的概括 | 先选专家,读结果后决定是否整理笔记 | 解释思路的词,不是此场景一个叫 ReAct 的开关。普通实现限制为两阶段,不能描述成无限工具循环 |
| Plan | 先产出多步任务计划,再按计划执行的做法 | 当前这条普通流程不要求先输出一份完整多步执行计划 | 解释思路的词。状态中即使有“未来剧情方向”,也不等于代码在执行这种计划系统 |
routingMode:"manual" |
在这份实现里不启用按工具调用量自动换更强协调器配置 | 当前场景为 manual | 开发配置;程序决定是否模型升级。不是让人每轮手动选专家 |
maxStateChars:8000 |
完整笔记的字符长度上限配置 | 超限的候选稿不能直接保存 | 产品/开发配置;程序校验。不是 8000 token |
maxToolCalls / maxParallelTools |
控制本阶段选择和同时处理的工具数量的配置 | 当前是 7 和 6;不能直接推成整轮总模型调用数最多 6 | 程序处理所选任务;后续 Director 和模型重试等另有调用 |
查材料名称:Prompt、Context、State、版本和来源记录分别是什么?
| 名称 | 用人话说 | 钥匙例子 | 谁提供 / 谁用 |
|---|---|---|---|
| prompt / 工作说明 | 告诉模型这次扮演什么岗位、应该怎样工作的文字 | “你负责知识检查;不要把猜测写成事实” | 配置/提示词管理提供,程序装进模型请求;模型读 |
| context / 上下文 | 这次真正发给某个模型的整包材料;不是它能访问的一切数据 | 卡片+旧笔记+历史+本句输入;Actor 还收到选中的世界书 | Harness 组装;每个模型收到的包可能不同 |
| query / 本轮输入 | 用户当前说的这句话;Harness单独发送,世界书服务只为hybrid排名补最近两条历史 | “我把铜钥匙递给北塔守卫,请他开门” | 用户提供;程序送去回复与后台,并组装世界书检索 query |
| 角色卡 / character | 作者提供的角色基本设定;两边按各自规则组织,不能当作全卡原样复制 | “艾琳是旧城向导,谨慎、话不多……” | 后台的角色正文优先取非空 init_prompt;没有时,才合并卡片的性格、场景、摘要和 system_prompt。名称、简介、开场白另行选取;Actor 则由自己的模板引用材料 |
| Persona / 用户身份资料 | 用户在聊天里使用的身份说明;描述用户,不是描述 AI 角色 | “我扮演一名第一次来旧城的旅人” | 接入方提供用户资料;模型用来理解身份。提示词要求:不能仅凭这段资料就把它全写成已经发生的剧情事实 |
| openingMessage / 开场白 | 这次角色卡的开场内容 | “艾琳带你来到旧城门口” | 角色卡提供;专家和 Director 的输入会包含它 |
| history / 历史 | 请求中已有的过去对话文字 | 上一轮用户说“钥匙还在我这里”;守卫认出了用户 | 会话/接入方提供;模型用于衔接已发生内容 |
| 世界书 / worldbook | 作者或维护者写好的世界设定条目库;本轮先选条目,再把选中原文给回复模型 | “持钥匙仍需手令,手令在市政厅申请” | 世界书维护者写、服务选择、Harness 放入 Actor 输入;本例不自动给后台同一批原文 |
state / 连续性笔记 |
存在会话后台的一整段状态文字,记录当前情境、人物、知识边界等 | “用户在门外,持有钥匙,尚未进塔” | 初始可由程序保守补底稿,后由 Director 产出新稿、程序保存;后续模型读取 |
candidate / candidateState / 候选笔记 |
Director 刚写完、尚待程序决定是否保存的新稿 | “用户已递出钥匙,请求开门;回应尚待确认” | Director 产出;程序检查,成功保存后才成为新版 state |
ledger / 分类记录 |
附在主笔记旁的一组有来源的记录,保留某次专家分析等信息;不是独立人物数据库 | npc 类型记录保存“同一名守卫,不能重复新增”的分析 |
程序在正式状态提交时组织并一并提交;后续上下文可能挑选、截短其中内容 |
revision / 笔记版本 |
这份已保存笔记更新到第几版 | “目前是第 12 版”;成功写入后成为第 13 版 | 存储服务维护;程序据此避免旧稿覆盖新稿 |
sourceTurn / 来源回合 |
这次工作所依据的是第几个用户回合 | 第 20 个用户回合生成了笔记第 13 版 | 程序依据可见用户消息数与可用会话长度计算;用于标明记录来源。它不必等于笔记版本 |
sourceMessageId |
当前普通链路关联的本轮助手回复记录编号 | 用来关联这次正在生成的守卫回应记录;不是“递钥匙”那条用户消息编号 | 普通 runtime 从 requestContext.assistantMessageId 取值;随状态提交记录关联来源 |
historyRevision |
标记这次工作看到了哪一份历史的数字 | 本轮准备时传入的历史位置 | 程序依据消息数和会话长度记录;不是 Director 自己编的剧情内容 |
toolsCalled |
这次实际执行过的工具名称列表 | judge_npc、audit_knowledge、update_director_state |
程序记录;便于解释这份笔记怎么来的 |
found |
有没有找到已经保存的后台笔记 | false 表示没有持久化旧稿,会使用保守起始材料 |
存储读取结果;程序使用 |
state 里也有一个叫 “Entity, pronoun, and relationship ledger” 的文字小节。它和状态外层的 ledger 数组不是同一个字段:前者是完整笔记内部的一个标题;后者是额外保存的结构化分类记录。
查任务单字段:工具名、参数、reason、focus 怎么读?
模型没有真的“走过去叫另一个模型”。它返回一张程序能识别的任务单,程序再执行。
| 字段 | 用人话说 | 例子 | 谁提供 / 谁用 |
|---|---|---|---|
| tool call / 工具调用 | 模型提交给程序的一张任务单 | “请调用人物检查,重点核对钥匙交接” | 通常由协调器模型生成,也可能由程序强制规则补入;程序执行 |
id |
这张任务单的编号,用于把结果对应回来 | call_npc |
模型或补任务的程序提供;程序匹配任务和结果,不是人物 ID |
type |
任务单的调用类别 | 当前示例是 function |
模型返回;程序按函数工具调用处理 |
function |
装着“调用哪个功能、传什么参数”的那一层 | {name: ..., arguments: ...} |
模型返回;程序读取,不是一个故事人物 |
name |
已登记功能的准确名字 | judge_npc |
模型从菜单选择;程序查找对应实现 |
arguments |
交给功能的参数。在模型工具调用协议里它是一段 JSON 字符串,程序会尝试解析成对象 | {"reason":"人物正在交接钥匙","focus":"确认是同一个守卫"} |
模型生成;程序解析后交给工具。不要把这串字当玩家正文 |
reason |
为什么这次要用这个工具,给下游模型看的文字理由 | “用户向老相识守卫递出钥匙,需要检查连续性” | 协调器或强制规则提供;专家/Director 读 |
focus |
这次特别想让专家检查哪一点 | “保持同一人物,不提前替守卫开门” | 协调器提供,可省略;专家读。当前 Director 输入使用 reason,没有单独拼入 focus |
role:tool |
包装结果时标记“这段来自工具返回” | 人物检查的建议作为 tool 消息交回协调器 | 程序组装;协调器第二次调用时读 |
tool_call_id |
结果属于哪张任务单 | call_npc |
程序填写;把建议对应回原调用 |
reason/focus 是提示文字,不是程序开关。例如 focus 写了“不新增人物”,并不代表程序建立了一条强制数据库禁止新增规则。当前普通应用没有开启严格参数 schema 校验;菜单里 reason 标必填,不等于执行器已经保证模型每次都正确提供。
这份“完整状态”到底写哪些内容?逐项看用途和例子
这些是一段长文本里的栏目标题,不是 23 个分别存入数据库、分别被代码执行的变量。第一项是整份笔记的标记,余下 22 项为内容。下面是白话解释和可以填入的例句;解释是根据栏目名、代码任务要求及保守默认状态归纳,不冒充线上 Director prompt 的完整规则。
| 原栏目 | 给普通读者的名字 | 北塔例子 | 用途/证据性质 |
|---|---|---|---|
[Agentic RP State] |
这是一份跨轮剧情笔记 | 整份笔记开头放这个标记 | 格式标记,程序会检查 |
Current scene |
现在在哪里、正在发生什么 | “用户在北塔门外,已递出铜钥匙并要求开门;守卫是否接收和开门尚待确认。” | 已知事实 + 明确未知 |
Character's current life |
角色本来在过什么生活 | “艾琳正陪用户前往北塔,谨慎、少言;沿用角色卡已有生活背景。” | 角色卡或既有剧情支持的背景;不可凭空加生平 |
Character's near-term goals |
角色眼下想完成什么 | “回应眼前的通行交涉,不替用户决定如何争取入塔。” | 角色动机/短期意图,不保证成功 |
Soft mainline direction |
可以往哪条故事方向接 | “可围绕进塔请求继续交涉;若用户离开,就顺着离开的选择继续。” | 可改的建议,不能强迫用户 |
Long-horizon outline (10-20 user turns) |
再往后可能怎么发展 | “若用户持续调查铜钥匙,可逐渐展开来历;暂不锁定真相或结局。” | 10–20 轮是展望范围文字,不是倒计时/触发频率/必跑剧本 |
Current story beat |
这一小段戏进行到哪一步 | “提出通行请求,等待守卫回应。” | 对当前进展的概括 |
Possible developments for the next five user turns |
接下来几句有哪些可选接法 | “可询问入塔条件、解释来意或离开;等待用户选择。” | 五轮不是固定五步计划,不自动替用户行动 |
Active relationships and NPCs |
现在要记住哪些人、是什么关系 | “用户与北塔守卫正在交涉;尚无已建立的信任关系。” | 已出现人物与已建立关系 |
Entity, pronoun, and relationship ledger |
‘他/我/那个人’到底是谁,谁的东西 | “‘我’是用户;‘他’是北塔守卫;用户递出的铜钥匙不因此自动变成守卫所有。” | 防止代词、所有权、身份串线的记录 |
Knowledge boundaries and hidden facts |
每个人知道什么、不知道什么 | “守卫能看到钥匙;没有证据证明他知道钥匙如何到用户手中。” | 知识范围约束,禁止角色全知 |
Locations, separation, and tracking constraints |
人在哪里,隔多远,能不能碰到彼此 | “用户与守卫在塔门处;没有确认进塔,不应直接写用户已经在塔内。” | 位置/可达性等已知约束 |
Allowed introductions |
如果需要加人,怎样的人才合理 | “只有剧情确有需要时,才考虑与守门事务有关的人物。” | 合理性建议,不表示此人已经存在/已经出场 |
NPC introduction decision |
这次要不要加新人物 | “现在不新增人物,先处理用户与守卫的交涉。” | 本次建议,不会自行生成 NPC 实体 |
Viewpoint balance for next beats |
下几段主要跟着谁看 | “以艾琳可见的交涉和塔门环境为主,不编造用户心里在想什么。” | 写作视角建议 |
World clock and off-screen life |
时间有没有过去,离开镜头的人在做什么 | “当前动作未证明明显时间流逝;不能据此宣布换班或远处事件已发生。” | 时间事实 + 后台事件约束 |
Social graph and NPC lifecycle |
人物之间的联系、谁还在场或暂时退场 | “守卫仍在塔门当值;没有新人物进场或退场的证据。” | 关系/在场状态记录;不是另外创建角色数据库 |
Open callbacks, promises, items, injuries, and deadlines |
还有什么承诺、物品或期限不能忘 | “铜钥匙已经递出;是否接收未确认。如旧剧情已约定归还原主人,该承诺仍保留。” | 已有未结事项;无依据就写未建立,不能为了填表造承诺 |
Camera mode for next beat |
下一段文字把注意力放在哪里 | “以近距离交涉为主,少量写钥匙和门口环境。” | 文学镜头建议,不控制摄像机;默认示例 45/35/20 也是文本,没有按字数强制分配 |
Character agency budget (0-4) |
允许角色主动推动多少,而不替用户决定 | “1:艾琳可以主动问一个问题或提一个轻量建议,但不替用户答应、离开或感到害怕。” | 0–4 是模型参考的主动性档位;代码只明确给出默认 1 的例义,没有各档严格枚举/扣点程序 |
Facts that must remain consistent |
后面绝不能写反的已知事项 | “递出不等于接收;请求开门不等于已放行;用户动作与决定由用户掌握。” | 已知事实/连续性与自主权约束 |
Directions the user rejected |
用户已拒绝过什么,不要反复逼他走 | “当前无已记录的拒绝;之后若用户明确说不想调查钥匙,不继续强推调查。” | 已有拒绝记录;后半句为使用示例 |
Guidance strength |
这些剧情引导要用多大力 | “light:只轻轻给可能的接法,先回应用户当前行为。” | 文本中的引导强度建议,代码没有枚举验证/独立开关 |
看似参数的数字,也要分清实际作用。 “未来 10–20 轮”“接下来 5 轮”“主动性 0–4”“镜头占比”“引导强度 light”在这条普通接线中都是随状态交给模型参考的文字。程序没有据此创建 20 个任务、扣减主动性点数、按比例分配正文。它们表达希望模型怎样演;是否真的遵守,不能由格式校验替代确认。
Scene Director(工具名 direct_scene)只是六种检查之一,给场面写法和主动性建议;本步 Director(入口 update_director_state)负责综合整份状态。另一个前台 Director 属于不同接线,不是本例后台这次调用。
线上岗位说明的边界: 程序会从配置服务加载 Director 的系统提示词,并追加材料和完整状态要求。这里核实了本地代码中的输入、栏目与校验;没有取得线上完整提示词,不能把这些教学文字冒充实际运行 Prompt。
查结果字段:ok、result、candidateState、stateOutcome 有什么不同?
| 字段 | 用人话说 | 例子 | 谁提供 / 谁用 |
|---|---|---|---|
ok |
这次工具有没有按实现规则返回可用结果 | true:人物检查返回了非空文本;false:请求失败或返回空内容 |
工具实现填写;协调器和程序处理结果。它不是事实正确性的保证,也不是已保存标志 |
tool |
这份回执来自哪个功能 | judge_npc |
工具实现填写;程序及协调器辨认来源 |
result |
专家给出的分析文字 | “沿用同一名守卫;用户已递出钥匙,守卫回应未见于本次材料” | 专家模型生成、工具包装;协调器/Director 使用 |
candidateState |
Director 交出的完整待保存笔记文字 | 完整 [Agentic RP State],包括当前场景、人物关系、知识边界等要求的小节 |
Director 模型生成、工具包装;保存程序使用 |
usage |
这次模型调用的用量记录 | 输入/输出 token 数、模型名、调用目的;有些字段可能没返回 | 模型服务/程序记录;调试、成本和运行观察使用,不送给玩家当剧情 |
error |
这次工具失败的说明 | “返回空内容”“调用失败”等 | 工具实现填写;程序/调试界面处理,不是一条世界事实 |
stateOutcome |
最终处理笔记的结果 | committed 保存成功;retained 没选更新;unchanged 内容没变;invalid 格式不合格;stale_write_rejected 版本过期;failed 失败 |
后台程序填写;用它区分“工具跑完”和“状态真存下来了” |
普通专家通常返回 result;Director 返回 candidateState。两者用途不同,不能统称为“工具已更新状态”。
入口成功结束也有自己的协议条件。 某些流式片段可以先展示,随后生成仍可能失败;即使已有正文,若结束信息或必要用量元数据缺失,入口仍可能返回协议错误。不能只看“已经收到几个字”就认定本次生成和上游交付已完整结束。正文生成、入口完成、消息保存、后台状态提交需分别确认。流式完成与协议错误[5]
内部 TurnHarness 结果的 stateVersion 也不能直接当作后台存储中的 revision:前者是内部轮次结果字段,实际持久化仍需查看对应状态存储的提交结果。对保存报错或超时,同样需要核对存储结果,不能从失败回包推断写入一定已经发生或一定没发生。内部轮次结果字段[6]
技术核对:解析、校验、额度和重试,当前究竟保证到哪一步
| 环节 | 固定主线的实际处理 |
|---|---|
| 从模型协议取调用 | Kaon 适配器读取 JSON 或流式 tool_calls,拼接函数名/参数;缺 ID 可补,空函数名过滤;不从正文猜函数。部分 SSE payload 解析失败会跳过,不统一改成“让模型修复” |
| 参数 JSON | registry 默认 validateArguments=false,当前普通应用没打开;非法 JSON 或非对象退成 {}。菜单里的 required reason 不等于执行器已严格校验 |
| 启用范围 | enabledTools 控制给模型的菜单,启动时检查配置名称;registry 仍装全部六专家和 Director,执行处没有完整的二次启用名单检查,不能当成严格权限隔离 |
| 未知工具名 | 第一阶段若保留进入执行名单,会在查注册表时报错,整次规划 failed;第二阶段只找 Director,其余名字不执行 |
| 重复调用与调用 ID | 按工具名去重;ID 校验在治理关闭时不执行,shadow 记诊断、enforce 才阻断空/重复 ID。这不是参数 schema 校验 |
| 本批调用上限 | 默认 min(7,6)=6;enforce 优先强制工具再截断,并为超额项回 budget_not_executed;非 enforce 的强制调用可超过过低的配置上限。后续 Director 另算,不是整轮最多 6 次 LLM 请求 |
| Director 格式校验 | 检查必需标题的首次出现位置和顺序,未强制标题只出现一次;Prompt 的“恰好一次”要求不是程序完整保证 |
| Director 重试 | 通常初始加最多 2 次重试,恢复标记可提前停止;当前主线复用原输入,没有把具体校验错误追加回去逐项纠错。最终无效仍不保存;候选的反馈改进不能写进 main |
第二阶段复核要求整批执行没有抛出中断;工具正常返回 ok:false 则可继续。协调器重试、模型升级与专家内部调用会增加实际请求量,“两阶段”不表示只有两次模型调用。
依据:Kaon 协议适配[7] · 注册表参数与未知名[8] · 普通注册构造[9] · 交换与去重[10] · 额度处理[11] · 重试[12] · 重复标题测试[13]
接入合同:预组装与闭环、准备失败、额外记忆收尾分别有什么差别?
先区分三种名称中的“版本”。 两种入口外层均为 protocol_version=v1;模型材料由谁准备,取决于 extensions_version 使用 roleplay-harness/v1 还是 roleplay-harness/v2。是否启用普通后台,则是另一项 agenticV2 配置。它们不是快、慢两条通道的版本号,不能仅从字符串里有 v2 判断后台已经开启。
- 使用
roleplay-harness/v1时,接入方已经组好模型messages。Harness 复用这些消息,按服务端方案指定的模型调用网关并处理正文、结束信息和用量;该路径不在这里重复召回或写入由聊天服务负责的记忆,也不会自动接上六专家后台。“预组装”并非绕过全部 Harness,也不是没有真正的模型调用。 - 使用
roleplay-harness/v2时,请求交来会话、角色、用户身份、本轮问题与历史等,Harness 按已加载方案通过 Axon 获取模型配置和 PromptManager 等资料、处理预算并组装输入。并行后台或前台工具循环要看相应配置;不是所有 v2 请求都拥有这些动作。
本例随请求传入 extensions.scenario_id=agentic-v2-worldbook。conversation_id 定位会话,prompt_id 定位主角色设定,request_id 追踪当前调用;助手消息还有自己的标识,不能替换成用户消息 ID。入口检查必填信息、支持版本和合法方案,失败时不能默认自动切换为另一种玩法。实际入口分流[14] · 请求与方案校验[15] · 预组装消息调用模型[16]
- 当前 closed-loop 构造空执行图,不能把通用节点图能力当成当前普通 RP 的现成 Workflow。
- 准备中会读取角色、状态、必要的后台提示词配置。只有准备成功并进入生成,普通 Agentic 才启动后台;不是所有进入 HTTP 接口的失败请求都启动它。 当前配置解析仍要求 Actor、协调器、Director 和六位专家各自的模型配置;准备时也会加载协调器、Director 和全部六位专家的模板,未按
enabledTools缩减。因此,仅从模型菜单关闭某位专家,并不能省掉它的配置与模板要求;缺失仍可能让准备失败。这是加载工作说明,不是已经把六位专家都调用分析了一遍。配置必需项[17] · 全部岗位模板的加载[18] - 世界书已可显式配置到普通 RP/Agentic V2/Compact/Story/Sumi/前台工具循环;旧 v1 预组装协议仍拒绝 worldbook 配置。本例文件的
memorySources=[]、未配置 Compact 仅是这份案例配置的事实。 - 本例没有记忆写入任务。其他启用记忆的场景,Harness 等待
memory.ingest返回:日记通常只是安排处理;表格有 background runner 时安排后返回,没有时等待实际表格处理。达到日记生成阈值、记忆完成和正文保存各有时机。
代码组件与远程请求也需要分开。 SDK / Tools / LLM 是可复用代码,不是必须依次访问的三个后端服务。本例实际分别进行资料读取、模型调用、经 Axon 选世界书和状态提交:世界书服务返回条目原文及放置信息,由 Harness 加进 Actor 请求;LLM 网关返回正文或结构化工具调用及可用结束/用量信息;状态接口处理版本条件提交;Agent Router 将正文交回上游聊天业务。某一服务调用成功不能替代其他产物的保存结果。装配与空执行图[19] · 工具选择模型的请求与回包[20] · 返回上游业务[21] · 聊天保存责任[22]
后台有哪些跳过与复核分支?不是每轮都咨询后整理
有一次“看专家结果、决定要不要整理状态”的模型复核,但不是每个工具执行完都再审一遍,也不是不停重选新专家。 当前代码的具体分支是:
| 本次发生的情况 | 下一步是什么 |
|---|---|
执行了专家,并且启用了 update_director_state |
整批结束后,第二次调用协调器:读原材料和工具结果,菜单只剩 Director;决定是否整理状态 |
| 专家返回失败,但没有抛异常中断整批 | 失败结果也会作为材料交回;不要求所有专家成功才进入上述判断 |
| 执行了专家,但没启用 Director | 没有第二次协调器复核,也不因此保存新状态 |
| 第一阶段没有专家,直接选 Director | 直接整理状态,省去专家后复核 |
| 没有选任何工具,也没有被规则补调用 | 保留旧状态,结束本次后台工作 |
| 首轮/新名字触发了强制审计,且进入第二阶段 | 程序会补 Director 更新尝试;不能说这里完全由第二次模型自由决定 |
如果第一阶段同时选专家和 Director,Director 会延后,等第二阶段重新决定;它不能一边读尚未返回的专家建议,一边生成最终候选。第二阶段不会再打开第三批、第四批专家。因此这里更准确的业务表述是:选必要专家 → 并行分析 → 有条件地汇总判断 → 可选地整理状态。第二阶段条件、唯一菜单与强制补调用[23] · 零专家直接 Director[24]
工程调度参考:两阶段、前台循环、SDK 与静态 Workflow 有什么不同?
先分清你要表达的产品原则与现在的执行方式。 如果“ReAct”指模型根据当前材料选择必要动作、看到结果后再判断,而不先排一份庞大步骤表,你的方向与当前普通后台的部分机制一致。可是代码中的 AgenticV2Planner 是一个类名,既不能据此认定为重型 Plan,也不能反过来说它已经是任意循环的 ReAct。
| 当前路径 | 实际组织方式 | 对业务的含义 |
|---|---|---|
| 普通 Agentic 后台 | 第一阶段选专家;有条件地第二阶段看结果选 Director;程序校验保存 | 可称“有边界的两阶段工具调度”。分支有限,工具按需;没有反复选择任意新工具的开放循环 |
| 前台工具循环 | 控制模型调用 Actor 等动作,看到工具结果后可继续选下一步,直到 over 或预算结束 | 更接近本轮内的行动/观察循环;会影响本轮等待和交付,与后台不是同一个循环 |
| 通用 SDK Slow / Pi Agent | 有可复用的模型—工具循环及停止/额度机制,业务自行提供工具、材料和保存接线 | 是框架能力,不代表普通 RP 自动改用它的全部行为 |
| 静态 Workflow | 接入方事先定义节点与依赖,由程序执行 | 固定流程也不等于 LLM 先生成一个大计划;当前闭环不能凭“支持执行图”就补出一条实际未配置的链路 |
慢状态里的“未来 10–20 轮方向”也是文本建议,并非执行引擎已经排好了 20 轮任务;后续仍可能重新判断。判断系统是否过重,应看这一轮实际等待了几次模型、哪些步骤必做、是否卡首字,以及能否无事就结束,不要只看名字里有没有 plan。
产品建议,尚非代码承诺: 可以把希望坚持的原则写成“当前回复先交付;后台按需选择少量工具;观察结果后有限复核;满足条件再保存;没有必要就结束”。当前主线已经具备其中一部分,但强制首轮/新名规则、有限两阶段、参数解析和状态提交边界仍须如实保留。若以后改成更通用的 ReAct 循环,需要另定可选工具、停止条件、调用额度和持久化条件,不能通过修改文档名称当作已经实现。前台循环[25] · 独立 Slow[26] · 静态图[27] · 长期方向只是状态文本[28]
请求与回执的真实字段形状:任务单如何对应工具结果?
协调器的调用示例(具体字句为教学编写):
{
"id": "call_npc",
"type": "function",
"function": {
"name": "judge_npc",
"arguments": "{\"reason\":\"老相识守卫正在参与钥匙交接,需要检查人物与动作是否接得上。\",\"focus\":\"保持同一人物,承认用户已递出,不提前替守卫接收或开门。\"}"
}
}
专家回执示例:
{
"ok": true,
"tool": "judge_npc",
"result": "沿用同一名守卫;用户已递出钥匙,本次材料尚未提供守卫的回应。"
}
程序向第二次协调器调用交回原 assistant 工具调用记录,并用 role:tool 消息包装各项结果;tool_call_id 对应原任务单 id。不是把专家建议直接当成一条新用户消息。
协调器的输入分为:岗位说明 system、装有角色/旧状态/记录/近期历史/最新输入的本轮 user 材料,以及配置生成的 tools 菜单。默认状态投影约 6500 字符,内置 transcript 取最后 9 条非空 user/assistant 消息;这不是 9 轮,也不是触发周期。模板还可能引用其他历史变量。Actor 另行编译自己的请求,不能由这个数字推定两边看到完全相同材料。
启用相应 Compact 上下文治理时,摘要和保留历史的处理另有差别;本例没有配置 Compact。确切来源与可见差异见第 7、9 章。没有找到已保存状态时可以使用保守底稿;“没找到”不应与存储读取失败混为一谈。
固定源码与历史证据:原第 1、2、19、24 章的全部源码引用
正文以 13c481b 固定主线为依据。以下保留合并前各章的全部唯一源码 URL;世界书选择入口保留 b0af622 固定版本;旧 77a1537/3a11e333 链接用于追溯已审范围,不证明当前生产启用,也不把教学台词当作运行日志。不同锚点指向同一文件的不同位置,故不按文件名合并。
固定主线 13c481b
- 配置必需项[29](原第 2 章)
- 全部岗位模板的加载[30](原第 2 章)
- closed-loop 的输入、记忆来源和空执行图[31](原第 2 章)
- Story 与世界书的组合限制[32](原第 2 章)
- 世界书当前配置[33](原第 2 章)
- Actor 的状态与世界书准备[34](原第 2 章)
- 后台输入与 Actor 注入[35](原第 2 章)
- 一次后台调度[36](原第 2 章)
- 正文生成入口与返回[37](原第 2 章)
- 记忆收尾[38](原第 2 章)
- 后台材料[39](原第 19 章)
- 完整新稿输入[40](原第 19 章)
- 版本条件提交[41](原第 19 章)
- 精确标题清单[42](原第 24 章)
- 保守默认笔记[43](原第 24 章)
- 岗位提示词加载[44](原第 24 章)
- 业务请求先指定执行方案[45](原第 24 章)
- 附属专家记录筛选与编译[46](原第 24 章)
- 工具及结果字段合同[47](原第 24 章)
- 状态的不同处理结果[48](原第 24 章)
- 实际世界书场景文件[49](原第 24 章)
- 默认启用菜单[50](原第 24 章)
- 世界书绑定[51](原第 24 章)
- 普通后台装配[52](原第 24 章)
- 生成正文时调度后台[53](原第 24 章)
- 检查模型输入与返回[54](原第 24 章)
- 首轮/新名字规则[55](原第 24 章)
- 并行检查、第二阶段条件及补 Director[56](原第 24 章)
- Director 的材料与候选[57](原第 24 章)
- 格式检查[58](原第 24 章)
- 状态提交[59](原第 24 章)
- 场景解析[60](原第 24 章)
- 实际装配普通 Agentic[61](原第 24 章)
- 生成时安排后台[62](原第 24 章)
- 轮初准备[63](原第 24 章)
- 协调器材料[64](原第 24 章)
- 最终岗位与工具请求[65](原第 24 章)
- 调用格式与注册表[66](原第 24 章)
- 参数解析与执行[67](原第 24 章)
- 强制规则与去重/额度[68](原第 24 章)
- 专家实际输入与返回[69](原第 24 章)
- 并行执行与结果记录[70](原第 24 章)
- 工具交换消息[71](原第 24 章)
- 第二阶段条件、唯一菜单与强制补调用[72](原第 24 章)
- Director 输入与输出[73](原第 24 章)
- 程序校验[74](原第 24 章)
- 保存与报告[75](原第 24 章)
- 前台循环[76](原第 24 章)
- 独立 Slow[77](原第 24 章)
- 静态图[78](原第 24 章)
- 长期方向只是状态文本[79](原第 24 章)
- Kaon 协议适配[80](原第 24 章)
- 普通注册构造[81](原第 24 章)
- 交换与去重[82](原第 24 章)
- 额度处理[83](原第 24 章)
- 重试[84](原第 24 章)
- 重复标题测试[85](原第 24 章)
历史固定源码与其他原始依据
- 两种接入的分流[86](原第 2 章)
- 组合约束[87](原第 2 章)
- 世界书场景配置[88](原第 2 章)
- 材料准备与两份上下文[89](原第 2 章)
- 记忆收尾的真实分支[90](原第 2 章)
- 世界书请求与临时消息[91](原第 19 章)
- 候选状态提交[92](原第 19 章)
- Demo 保存正文[93](原第 19 章)
从原第 1 章继承的独有源码位置
这些位置补充入口协议、服务职责与完成条件。目录边界与世界书存储的旧依据保留供追溯,不扩展本例普通主线行为,也不构成生产部署验证。
- 应用上下文和配置[94](原第 1 章)
- 世界书组合约束[95](原第 1 章)
- 状态与资料准备[96](原第 1 章)
- Actor 模板展开[97](原第 1 章)
- 世界书选择及装配[98](原第 1 章)
- 同轮后台调度[99](原第 1 章)
- 选择与执行[100](原第 1 章)
- 工具内部的模型输入[101](原第 1 章)
- Director 输入与产物[102](原第 1 章)
- 格式、变化及提交结果[103](原第 1 章)
- 状态保存接口[104](原第 1 章)
- Demo 保存正文[105](原第 1 章)
- 读取会话状态[106](原第 1 章)
- Demo 读取历史并加入新问题[107](原第 1 章)
- 固定版本服务选择入口[108](原第 1 章)
- 两种入口的实际分流[109](原第 1 章)
- 请求与方案校验[110](原第 1 章)
- 准备好的消息如何发给模型[111](原第 1 章)
- 应用装配与空执行图[112](原第 1 章)
- 工具选择模型的请求和回包[113](原第 1 章)
- 返回上游业务[114](原第 1 章)
- 聊天保存责任[115](原第 1 章)
- 流式完成与协议错误[116](原第 1 章)
- 内部轮次结果字段[117](原第 1 章)
- 仓库与包边界[118](原第 1 章)
- 接入架构[119](原第 1 章)
- 应用装配[120](原第 1 章)
- 世界书服务接口[121](原第 1 章)
- 此前状态材料与保存接口依据[122](原第 1 章)
代码证据 · 122 处
- 精确标题清单 ↗
- 保守默认笔记 ↗
- 岗位提示词加载 ↗
- 状态进入后续 Actor ↗
- 流式完成与协议错误 ↗
- 内部轮次结果字段 ↗
- Kaon 协议适配 ↗
- 注册表参数与未知名 ↗
- 普通注册构造 ↗
- 交换与去重 ↗
- 额度处理 ↗
- 重试 ↗
- 重复标题测试 ↗
- 实际入口分流 ↗
- 请求与方案校验 ↗
- 预组装消息调用模型 ↗
- 配置必需项 ↗
- 全部岗位模板的加载 ↗
- 装配与空执行图 ↗
- 工具选择模型的请求与回包 ↗
- 返回上游业务 ↗
- 聊天保存责任 ↗
- 第二阶段条件、唯一菜单与强制补调用 ↗
- 零专家直接 Director ↗
- 前台循环 ↗
- 独立 Slow ↗
- 静态图 ↗
- 长期方向只是状态文本 ↗
- 配置必需项 ↗
- 全部岗位模板的加载 ↗
- closed-loop 的输入、记忆来源和空执行图 ↗
- Story 与世界书的组合限制 ↗
- 世界书当前配置 ↗
- Actor 的状态与世界书准备 ↗
- 后台输入与 Actor 注入 ↗
- 一次后台调度 ↗
- 正文生成入口与返回 ↗
- 记忆收尾 ↗
- 后台材料 ↗
- 完整新稿输入 ↗
- 版本条件提交 ↗
- 精确标题清单 ↗
- 保守默认笔记 ↗
- 岗位提示词加载 ↗
- 业务请求先指定执行方案 ↗
- 附属专家记录筛选与编译 ↗
- 工具及结果字段合同 ↗
- 状态的不同处理结果 ↗
- 实际世界书场景文件 ↗
- 默认启用菜单 ↗
- 世界书绑定 ↗
- 普通后台装配 ↗
- 生成正文时调度后台 ↗
- 检查模型输入与返回 ↗
- 首轮/新名字规则 ↗
- 并行检查、第二阶段条件及补 Director ↗
- Director 的材料与候选 ↗
- 格式检查 ↗
- 状态提交 ↗
- 场景解析 ↗
- 实际装配普通 Agentic ↗
- 生成时安排后台 ↗
- 轮初准备 ↗
- 协调器材料 ↗
- 最终岗位与工具请求 ↗
- 调用格式与注册表 ↗
- 参数解析与执行 ↗
- 强制规则与去重/额度 ↗
- 专家实际输入与返回 ↗
- 并行执行与结果记录 ↗
- 工具交换消息 ↗
- 第二阶段条件、唯一菜单与强制补调用 ↗
- Director 输入与输出 ↗
- 程序校验 ↗
- 保存与报告 ↗
- 前台循环 ↗
- 独立 Slow ↗
- 静态图 ↗
- 长期方向只是状态文本 ↗
- Kaon 协议适配 ↗
- 普通注册构造 ↗
- 交换与去重 ↗
- 额度处理 ↗
- 重试 ↗
- 重复标题测试 ↗
- 两种接入的分流 ↗
- 组合约束 ↗
- 世界书场景配置 ↗
- 材料准备与两份上下文 ↗
- 记忆收尾的真实分支 ↗
- 世界书请求与临时消息 ↗
- 候选状态提交 ↗
- Demo 保存正文 ↗
- 应用上下文和配置 ↗
- 世界书组合约束 ↗
- 状态与资料准备 ↗
- Actor 模板展开 ↗
- 世界书选择及装配 ↗
- 同轮后台调度 ↗
- 选择与执行 ↗
- 工具内部的模型输入 ↗
- Director 输入与产物 ↗
- 格式、变化及提交结果 ↗
- 状态保存接口 ↗
- Demo 保存正文 ↗
- 读取会话状态 ↗
- Demo 读取历史并加入新问题 ↗
- 固定版本服务选择入口 ↗
- 两种入口的实际分流 ↗
- 请求与方案校验 ↗
- 准备好的消息如何发给模型 ↗
- 应用装配与空执行图 ↗
- 工具选择模型的请求和回包 ↗
- 返回上游业务 ↗
- 聊天保存责任 ↗
- 流式完成与协议错误 ↗
- 内部轮次结果字段 ↗
- 仓库与包边界 ↗
- 接入架构 ↗
- 应用装配 ↗
- 世界书服务接口 ↗
- 此前状态材料与保存接口依据 ↗
3. 路由与组合:这一轮到底启用哪套流程
“快慢分流”先有业务选择,再有本轮模型判断。 接入方先指定这次会话按哪套方案运行;Harness 读取方案,才知道有没有世界书、普通后台或前台工具循环。之后,后台模型才从已经开放的菜单中决定本轮查什么。
这里的“场景配置”是一套功能开关与模型选择,不是故事里的北塔地点。比如请求指定“世界书+普通后台”,程序就先准备本轮资料,再安排回复与后台;它不会先请模型猜“递钥匙复杂不复杂”,然后把整句话二选一送去快或慢。
“默认装好了”必须说清是哪个入口的默认
SDK 默认没有业务工具菜单;应用的默认菜单是在选中具体运行方式后才出现。例如普通 Agentic 的默认配置会启用六专家+状态整理;这不能推出新建一个 SDK Agent 也自动得到七个工具,更不能推出 Sumi、普通单模型回复会跑这七个工具。
| 入口/运行方式 | 启动这条路径时已有的东西 | 模型真正能选什么 | 哪些重要工作由程序安排 |
|---|---|---|---|
SDK 自定义 Agent |
宿主 prepare() 交给 Pi 的模型、systemPrompt、tools、prompt |
宿主给出的工具数组;无统一业务默认名单 | 宿主准备输入和处理结果;SDK不替业务默认保存 |
SDK SlowTurnRuntime |
宿主传 prompt、上下文、状态与 capabilities;capabilities省略为[] | 构造时注册的工具;单次运行内不会自动扫描新工具 | 使用宿主传入的状态快照、处理工具结果;有 prepareCommit 时尝试版本保存。自动读 store 的是 FastSlowRuntime |
| 普通 Actor | 角色/历史/模板及启用的资料 | 这条基础路径不是一个开放全工具的主循环 | 回复前取资料;回复成功后执行所选记忆后处理 |
| 普通 Agentic 后台 | 独立组装后台资料,读取岗位 PromptManager,注册七项 | 第一阶段默认六专家+update_director_state;咨询后第二阶段只提供状态整理 |
首轮/新名字补审计、执行、候选检查与保存 |
| 前台 function loop | 程序内置控制提示词+用户本句,按接线过滤菜单 | actor、over;图片接好才加generate_image,DIO接好才加schedule_dio |
Actor内部准备正文输入;图生成、消息回写、DIO后续生效另有流程 |
| Story | 世界/叙事工具、持久快照与剧情协调程序 | 现有接线由Story程序安排工具,不能等同给普通后台再塞六个function | 上轮正文采用、当前场景准备、回复成功后保存pending与快照 |
| Sumi | 独立Prompt和图文协议、分支状态、图片任务与恢复代码 | 不继承普通后台菜单;模型按Sumi协议输出正文/状态/图片标记 | 程序解析、存消息快照、等待正文落库、生成和交付图片 |
他们可以动态装载什么:有四个不同时间点
“动态”不是一句话就能概括。先看是谁在什么时候更换了什么,再判断下一次模型是否真的能用。
| 时间点 | 可以变化的内容 | 谁控制,怎样生效 | 不能据此推断的能力 |
|---|---|---|---|
| 服务启动时 | 启用的方案文件、模型引用、记忆来源、前后hooks、允许的组合 | HARNESS_ENABLED_SCENARIOS选文件;AGENT_ROUTER_SCENARIOS_JSON可整条覆盖同名方案。加载器明确是startup-only |
修改文件不会证明运行中的进程已热更新;更不能让用户随意传一段代码当工具执行 |
| 每次业务请求时 | 选哪个已启用scenario、角色、用户与会话、chat/continue/regenerate等动作 | 接入业务传请求;程序查表验证。缺scenario或未启用会报错 | 没有通用LLM先自由发明一套新玩法或跨互斥方案合并 |
| 本轮准备模型输入时 | 外部ModelConfig/PromptManager内容、角色卡、历史、状态、选中的世界书条目、记忆材料;配置引用的hooks | 程序按既有接口取回再渲染;例如loadAgents(refs)按预先给出的refs读取外部hook配置;DIO可读已启用的新版角色Prompt |
“加载Agent配置”不是扫描全部Agent/插件;“选世界书原文”不是安装新tool,也不执行条目里的脚本 |
| 模型执行循环中 | 从当次菜单选择哪个工具、传什么参数、是否继续调用 | SDK Pi loop或前台loop读取工具返回后再决定;普通后台按两阶段限定菜单 | 模型不能仅凭工具包里有一个导出就调用它。普通应用没有通用“发现工具→安装→授权→挂入本轮”的自动链 |
如果另一个团队要给自己的 SDK Agent 加“查世界书”或“写 NPC 卡”,现在能做的是:在宿主代码中提供工具定义和执行器,绑定可访问的书/存储范围,把返回资料交回模型,并实现确认采用后的保存。SDK执行这份菜单的能力已经有;上述两个产品动作自动出现在当前RP菜单的接线没有因此自动完成。
同样,Profile 固定工作流在仓内有静态planner与capability执行器;当前普通closed-loop应用构造的是空的通用executionGraph,实际RP顺序写在应用代码里。SDK公开入口没有直接导出一套“写Profile即可运行所有仓内能力”的通用产品。接入者已有Workflow时,可以把一次SDK运行或单个Core Tool作为其步骤。
默认与装载的代码依据
SDK Agent准备与每次新建实例[1];SDK slow菜单与输入[2];普通后台默认七项[3];前台菜单过滤与prompt[4];启动加载与覆盖[5];空executionGraph与各路径装配[6];hook配置按refs读取[7];SDK公开导出[8]。
同一句话,为什么会有不同的处理
| 业务选择的方案 | 用户递钥匙之后的主要动作 | 最终得到什么 |
|---|---|---|
| 普通回复 | 准备角色和对话材料,调用回复模型 | 当前聊天正文 |
| 回复+普通后台 | 写正文,同时让后台判断是否检查、更新状态 | 正文,以及可能保存成功的后续剧情状态 |
| 世界书+普通后台 | 回复前多做一次世界书选择与注入,再按普通后台方式并行 | 参考了本轮入选设定的正文,以及独立整理的状态 |
| 前台工具循环 | 前台控制模型在本轮内选择写正文、配图或已接入的其他动作 | 由多次工具动作组织的当前交付;后台是否另开仍看配置 |
| Story 或 Sumi | 改走各自的剧情结算或图文应用流程 | 各自定义的正文、世界/剧情状态或图片交付结果 |
**世界书已可显式配置到 Story、Sumi、前台工具循环和 Compact 接法;不同玩法仍有自己的状态与保存流程。**本例只演示普通 Agentic+世界书;示例模板没配额外日记来源或长历史压缩,仍会读聊天历史和普通后台状态。其他合法方案可以有不同组合。
一轮里谁真正作决定
产品/开发事先配置“这个方案允许什么”;请求指定“本次使用哪个方案”;Harness 按方案安排程序步骤;进入后台后,Orchestrator 才选择必要的专家。模型可以不选专家、直接请 Director 整理,也可以没有值得更新的内容而结束;首轮或新名字等规则还可能由程序补检查。
有些配置名容易误解。例如 routingMode=manual 关闭的是后台协调模型自动升级,并非让人每轮手选专家。已有 Workflow 也需要明确接入;把用户的话送进 Harness,不会自动发现并运行另一套工作流。
缺配置或想换方案时会怎样
请求指定了不存在的方案、没有所需运行依赖,或者组合不被允许,不能当作“自动退回一个差不多的模式”。需要先由接入方完成配置和装配,程序才能按约定运行。文件中有一个方案,也不证明线上加载了它;运行环境还可能覆盖同名配置。
因此 PM 确认接入时,最先要确定的不是“用快还是慢”,而是:当前这类聊天究竟选择哪套合法方案,它的当前交付和跨轮保存分别由谁负责。 依据:按请求查方案[9] · 方案加载[10] · 实际世界书方案[11] · 装配限制[12]。
实现细节、参数及固定代码依据
请求先选定业务场景,场景再决定执行哪套流程。当前没有一个通用模型先判断 query 复杂度,然后自动把任务分到快、慢通道。
场景从哪里来
服务启动时加载启用的 scenario 配置。请求携带 scenario_id,入口查到对应设置,再选择 Actor、记忆后端、Agentic、Story、世界书等实现。场景文件描述的是已有业务链路的配置;它本身不会生成新工具,也不会自动发现一份用户已有的 Workflow。
服务启动时,HARNESS_ENABLED_SCENARIOS 选择文件ID,允许非空前缀加末尾 *;例如 compact-* 展开后加载匹配文件,匹配不到会报错。基础目录由 HARNESS_SCENARIOS_DIR 指定,另设 HARNESS_EXPERIMENT_SCENARIOS_DIR 时同名实验文件优先;随后 AGENT_ROUTER_SCENARIOS_JSON 仍按整个场景替换同名配置,不是字段合并。config/scenarios-production 中的两个native Compact文件只是可供装配的生产覆盖;须核对实际目录、启用ID及每场景hash,不能仅凭文件存在宣称生效。这是启动时加载,改文件不会热更新正在执行的请求。加载、覆盖与hash[13]
仓库里实际存在的组合
| 产品模式 | 用户发一句话后发生什么 | 这套模式的特点 |
|---|---|---|
| 普通 Actor | 准备角色与对话材料,生成正文,执行相应后处理 | 可以没有后台 Agentic |
| Actor + 普通 Agentic | Actor 写正文,同时后台按需分析并尝试保存状态 | 后台使用开轮材料,结果供后续读取 |
| 世界书 + 普通 Agentic | 先选世界书,装进 Actor,再正文与后台并行 | 可显式配置到 Story/Sumi/前台控制器;各自仍按原有状态和后台流程运行 |
| Actor + Compact | 准备时按预算检查历史,必要时压缩,再写正文 | 压缩会影响本轮首字前的准备 |
| Agentic + Compact | 快慢都可结合摘要,但由治理模式决定 | enforce 才让后台采用摘要和保留历史;shadow 仍用原历史规划 |
| 前台工具循环 + 普通 Agentic | 前台调度文字/图片/长期指令;后台另做持续规划 | 两个控制循环各有输入和工具名单 |
| Story V1 | 核对上轮采用的正文,准备世界与剧情,生成本轮并保存待复核记录 | 替换普通 Agentic 后台分支 |
| Sumi | 走独立图文生成、状态与图片交付流程 | 不自动继承普通 Emochi 的全部模块 |
世界书当前场景文件设定 memorySources=[],也没有 Compact;因此分析这个具体场景时,不能再画上“每轮日记召回、自动压缩”两步。通用 Agentic 可以采用其他配置,但那是另一条实际接线。
同一句话为何可能走不同路径
“我递上铜钥匙”在世界书场景里会触发资料选择;在 Story 场景里可能被解析成当前世界行动;在普通 Actor 场景里则直接作为角色对话材料。决定差异的是业务选择的模式。系统没有因为这句话同时提到物品与地点,就自动把三套模式全部运行。
配置中的 routingMode=manual 也不是要求人来选专家。两种模式都由模型选工具;manual 关闭的是后台协调模型的自动升级。auto 可以在达到工具调用数量阈值等条件时换模型重新选择。
4. 快通道:单模型、Workflow与前台工具循环
快通道就是“这次要给用户看的回复”所在的路径。 回复可能由一次模型调用写完,也可能被拆成几段、夹入图片;用户都在等这条路径交付,所以“快”并不等于“永远只调用一次模型”。
沿用例子:艾琳陪用户站在北塔门外。用户说:“我把铜钥匙递给北塔守卫,请他开门。”本章先讲实际常见的普通回复,再区分代码支持的其他接法。
普通回复:模型拿到什么,用户拿到什么
这里先用已经接上世界书和普通后台状态,而且回复模板引用了角色、历史和本轮问题的配置展示实际输入。本轮回复模型——代码称 Actor,意思是负责写角色对白与动作的模型岗位——会读到类似这些材料:
你写艾琳及场景中人物的表现。艾琳是谨慎的旅伴,不替用户做决定。
上一轮:艾琳与用户来到北塔,守卫在门口。
旧笔记:铜钥匙在用户手里;守卫尚无依据知道钥匙来历。
本轮世界书:入塔需要带城主印章的手令,在市政厅办理;铜钥匙不能代替手令。
用户现在说:我把铜钥匙递给北塔守卫,请他开门。
模型可能交出:
守卫没有伸手接钥匙。“带城主印章的手令呢?先去市政厅办理。”
艾琳看了看紧闭的塔门,低声说:“看来光有钥匙还不够。”
上面这份输入不是所有 Actor 的固定套餐。没有世界书接线,就没有这批条目;角色资料取到了但模板没有引用,也不能算模型已经看过。旧笔记按这条 Agentic 接线加入;各类输入怎样分别组成每次模型请求,见实际模型输入。
这就是快通道的主要成果:可以展示的正文。 它没有自动建立“守卫人物小卡”,没有自动修改世界书,也不等于后台笔记已经更新。业务保存这段正文后,它才有机会作为后续聊天历史再次使用。
不过,模型写出的第一份文字,不一定就是产品最后展示和保存的那份。 当前 Actor 的完整输出链是:
- 模型生成正文,程序保留处理前文字。 例如生成了守卫的台词;某些已配置的记忆表接法还会让模型同时输出表格编辑内容。程序先处理不应泄漏的续写边界片段,保留这份尚未经过正文过滤和后处理的文字,供后续需要它的机制使用。
- 按这套模型配置的规则整理正文。 有正文替换规则时,程序调用 Axon 过滤;若规则判定阻止该结果,本次处理报错,不能把之前流出的预览当作已经通过。没有这类规则则跳过这一步。
- 有“生成后处理”配置时,再把同一份过滤后正文交给各处理器。 它们同时工作,不是前一个改完再交下一个。假设两个处理器都交回整段改写,程序按配置顺序采用最后一个非空改写;不是看谁最后完成。一个处理器没有改写结果,就不替换正文。它们可以改变最终文字,但这里没有再自动跑一遍正文正则,也不代表完成了剧情事实的通用审核。
- 交付最终正文,再由聊天业务保存为这条助手消息。 这份文字才是普通非流式结果里的正文;流式交付还要按下面的完成协议收口。模型原文、当前预览和最后交付内容可能不同,不能随便选其中一份存成“用户最终看到的聊天”。
能直接流式输出时,程序在生成中逐段交出正文;但如果配置了生成后的处理,或正文替换规则不能安全地边收边处理,就会先缓冲,再处理并交付。使用流式模型接口,不等于用户一定边生成边看到每个字。 当前代码只为匹配的特定 Green Apple 规则提供过滤预览,并要求接入方明确支持“结束时替换全文”;不能把任意新正则都当成安全流式处理。立即输出或缓冲的判断[1]
9 月 22 日主干增加了有条件的正文暂存,并把空响应纳入一次性恢复。 已配置备用恢复模型的 Actor 主尝试,先暂存可流式正文,到生成正常完成或首个正文片段后满 4 秒才交出;尚未露出文字时遇到符合条件的 provider 拒答,可以丢弃未发片段并切一次备用模型。下午合入的 #208 还允许主模型报 router.empty_response 时走同一恢复入口。没有配置该恢复模型,不会因此统一增加 4 秒;完全空完成也不另等满 4 秒。已显示正文不能撤回后重新生成;后续主线增加了符合条件的流中断接续,保留原前缀后最多补写一次。正常结束后才判出的拒答仍不能冒充完整成功,见本章恢复缓冲和流中断续写。
先显示的片段叫 delta;完成事件里的 Done.finalContent 是需要整体采用的最终正文。 例如用户先看到预览“守卫看着你……”,结束时收到“守卫没有接过钥匙,只问你是否带了手令。”,支持这项协议的聊天业务应把整条预览替换成后者,再按产品流程保存;不能将后者追加在省略号后。若最终字段明确给出空字符串,也要用空结果替换,不能因它“没有字”就留下旧预览。这里讲的是生成结果的采用规则,不替产品决定空结果如何提示用户。
这项能力由接入请求的 acceptsFinalContent 声明。未声明时不会收到上述最终全文字段,也不会走依赖它的 Green Apple 预览路径;需要完整处理的正文会先缓冲。未声明不等于所有回复都禁用流式:没有这些处理要求时仍能直接交片段。 正常完成还需要结束和用量信息;已经收到片段但随后报错、缺必要结束信息或用量,不能自行改判为完整成功。详细字段与异常见同章输出合同。
最终还返回结束原因、耗时和可用的用量。比如因为输出上限停止,不代表故事自然写完。图片等附属内容也有自己的交付状态。另有一条与展示不同的去向:Harness 将最终正文和可用的处理前文字一起交给所选记忆收尾;AxonGo 记忆表优先从处理前文字提取编辑内容,所以“界面只剩台词”不等于表格编辑内容没有被使用。具体接法仍见记忆的保存与回读。
三种实现,谁决定用哪一种
不是用户提到“钥匙”就临时自动切换。接入方先配置或实现这段聊天用哪一种,再由程序按该接法运行。
| 接法 | 本轮怎么执行 | 交出的结果 | 目前能说明到哪一层 |
|---|---|---|---|
| 普通 Actor | 已组装的材料交给回复模型,生成一次正文;应用可有重试等处理 | 用户可读的回复文本 | 当前普通 Agentic、世界书路径使用的基础能力 |
| 接入方已有 Workflow | 开发者提供既定步骤,例如先做某项业务处理、再调用正文模型;由这套实现接管快路径 | 仍需交回正文和约定产物 | SDK 允许替换快运行时;不会扫描到“有 Workflow”就替你接好 |
| 前台工具循环 | 一个控制模型看用户要求,调用正文模型,查看已经写出的内容,再决定续写、安排图片或结束 | 一段或多段正文,可能含图片占位 | 需单独启用;当前可显式配置世界书进入 Actor,控制模型不自动收到同批原文 |
因此,普通 Agentic 后台与快通道并行,并不要求快通道一定是单次调用;但也不能把“仓库能替换快路径”写成“现有业务已经运行自定义 Workflow”。
决定权分两层:开发接入先决定可用接法和工具,模型只在这套接法允许的范围里处理本轮。 请求里的方案标识选择已经装配的配置,不是让正文模型自行安装世界书、切换 Story 或创造一个 Workflow。前台循环的配置名、菜单与额度见本章执行限制。
另一种配置:前台控制模型怎样一步步干活
这里换到已配置前台工具循环的场景。开发者需要提供控制模型和允许使用的技能配置;省略这项配置,不会仅因用户说“配图”就启动该循环。角色、人物和剧情仍用北塔例子,但不假定这一场景也自动拥有上面的世界书接线。
- 它先读“怎么调工具”的说明和用户原话。 例如看到“我把铜钥匙递给北塔守卫,请他开门;给这段场景配图”。它初始并没有直接读到回复模型那整套角色、历史和状态。
- 它调用
actor,也就是请正文模型写。 正文模型这时使用自己的完整材料,交回“守卫俯身查看钥匙……”和本段文本用量。 - 它看实际结果再决定下一步。 可以让正文继续,可以安排图片,也可以结束。不是先给出一个长计划,再强制照单执行。
- 需要续写时,上一段作为材料带给正文模型。 下一段才能接着守卫的动作写;各段共同使用这轮的总输出额度,不是每段重新获得完整预算。
- 结束后收拢各段。 用户拿到同一轮回复;控制模型自己的解释不直接当角色台词显示。
这一套控制模型与后台分工模型不是同一个岗位:前台控制模型看着这次刚写出的正文继续调工具,后台普通 Agentic 仍用启动时准备好的材料整理后续笔记。
图片和“以后都这样”的要求,各自改哪里
- 图片:例如给“守卫俯身查看钥匙”配图。先向当前回复放图片占位,图像任务完成后可以补入当前这条助手消息。任务已安排不代表图片已经生成。
- 长期指令 DIO:用于用户明确要求长期改变设定或写作方式,例如“以后艾琳都称呼我为队长”。前台工具只等任务被接收;任务完成后的结果供后续轮加载,不会倒回去替换本轮已经准备好的角色材料。具体持久改变由该任务负责,不是普通六专家自动处理。
- 普通后台笔记:用于保留“钥匙递出但是否接收尚待确认”之类的连续性。它和图片、长期设定任务使用不同的处理与保存通路。
出错时,用户这一轮会怎样
前台控制器在尚未得到有效正文前失败或给出无效调用,代码可回到基础正文生成。已经有正文片段时,循环可能以已有内容和对应结束状态收尾;不能统一宣称“任何失败都会重新生成完整回复”。
流中断后保留半条正文,是有条件的恢复行为。 某些 Actor 接法在符合条件时可保留已有非空文字,标成 partialResponse,继续后处理和记忆收尾;它不是“半句已经流到屏幕上就自动算成功”。当前 Agentic V2 接线启用了另一套流兼容行为,不进入这条保留分支;带恢复模型的失败路径也另有规则。判断某次中断结果,应看实际执行分支和返回状态,不能拿基础运行时的能力承诺所有普通 V2 都会保留半句。准确条件见部分结果的范围。
普通正文生成失败,不等于已开始的普通 Agentic 后台也取消;反过来,后台没有更新,也不等于正文失败。产品若显示状态,需要分别表达“回复是否完成”“图片是否完成”“笔记是否保存”,不能用一个成功标记代表全部。
输入放不下,也不等于必然启动“总结旧历史”。 是否做 Compact 压缩由配置决定;没有压缩时,基础 Actor、普通 Agentic 与世界书接法的裁剪或拒绝规则各不相同。输出最多写多少、历史保留几条、模型能容纳多少内容,是不同控制项,具体见窗口、历史与输出额度。
有世界书的 Actor 会按每次实际调用重新检查最终输入。 前台循环累计了更多正文,或重试换成窗口不同的模型时,重新渲染和计数;只试裁最老历史,固定 Prompt、本轮输入、条目、Story 等不可压缩材料、续写边界、循环控制与已生成正文保留。当前目标仍放不下就拒绝;普通重试队列还有目标时再尝试,失败目标的试裁不会污染下一目标可保留的历史。这不是“世界书预算以内就一定装得下”,也不会自动删除 lore 来让调用成功。重渲染与受保护材料[2] · 目标预算与重试[3]
首段输出暂存后,恢复成功和失败分别是什么
例如主模型已经生成“守卫抬起头……”,但随后返回供应商拒答。未把这段文字交给用户时,系统还有机会整次换模型;已经交出时,当前协议不能把它收回来再冒充另一份完整结果。 因此缓冲是一项输出容错,不是后台导演先审一遍正文。
另一个情况是主模型完成调用,却没有可用正文。9 月 22 日 #208 已将运行时的 router.empty_response 加入既有恢复条件:配置了恢复目标、主尝试未发可见正文且未取消时,可以改用一次允许的 DeepSeek。它没有新增一条后台链路,也没有把普通重试次数叠加进来。新增空响应条件[4]
| 条件或结果 | 当前代码怎么做 | 用户或接入方要怎样理解 |
|---|---|---|
配置 recovery.transientRetryModelConfigId,且这次 Actor 调用本来可即时流式 |
仅主尝试暂存非空正文 delta;生成正常完成或首个 delta 后 4 秒先到即释放 | 不是从用户发送起固定等 4 秒;每次前台循环 Actor 调用分别适用,不是整轮总延迟上限 |
| 主模型在未输出可见正文前正常完成 | 释放暂存正文,继续原后处理和完成协议 | 短回复可能一次出现,但不需要等满 4 秒 |
未输出可见正文,出现 provider content_filter、精确供应商拒答模板,或符合条件的 429/500/503 |
丢弃未发片段;最多切到一次允许的备用 DeepSeek | 最终应只出现恢复结果;角色台词中的普通“我不能”不自动触发 |
主模型空完成,报 router.empty_response 且符合恢复条件 |
使用独立请求 ID 调用备用模型,按该目标的参数和窗口检查输入 | 完全空完成没有首个非空正文片段,不会为了缓冲另等满 4 秒 |
| 备用模型也空完成或失败 | 这次 Actor 生成调用失败,不再切第三次模型 | 单次 Actor 最多主模型+备用两次推理;前台循环的外层收尾仍取决于是否已有可用片段及错误类型 |
| 已输出可见正文,之后生成中断或被判拒答 | 已有结束信息或不符合恢复资格时抛错;没有正常结束且满足新续写条件时可保留前缀接续一次 | 不撤回已有正文,不从头重写;具体条件见下方流中断续写 |
| 用户取消或整轮超时 | 中止生成,不因中止尝试备用;错误处理取消未释放缓冲 | 普通 V2 已安排后台仍可能继续,不能将取消 Actor 当作后台笔记必然回滚 |
目前的 4 秒是源码常量,没有 Scenario 调节字段;备用 ModelConfig 必须解析为 kaon/deepseek-v4-flash 或 kaon/deepseek-v4-flash-0731。源模型已经是 DeepSeek Flash/0731,或错误标记已执行恢复时,不再切换。配置恢复目标后,单次 Actor 生成最多两次推理;未配置时仍按原有普通 retryCount 等规则处理。如果前台循环多次调用 Actor,各次分别受这个上限约束,不能把它说成整轮总调用数。次数与普通重试分流[5] · 空响应判定与恢复 catch[6]
9/22 14:40报告已记录早晚拒答受控测试及三项空响应定向验证通过,覆盖两个允许目标及备用仍空时两次后失败。POV 样例已配置 recovery,因此有可触达的业务入口,但不能把它当成普通 V2 的统一默认。该次 Harness 记录证明镜像构建成功,未直接核验对应 workload 部署、真实首字时间、恢复命中率与备用质量。缓冲类[7] · 空响应定向测试[8] · POV 已有恢复配置[9] · 镜像构建记录
技术对齐:实现边界与代码证据
SDK、图执行与应用路径
SimpleFastRuntime.complete 是一次 model.complete;默认 stream 也是先完成再 yield 一块内容,不可宣称 SDK 默认逐 token 流式。自定义 fast runtime 是接口能力,不是已有 Workflow 的自动发现功能。应用 StaticPlanner 只校验、排序已配置节点依赖;当前 closed-loop 的 executionGraph.nodes 为空。
RPGenerationResult.text 为交付正文;artifacts 为产物引用,另外有 finishReason、durationMs、tokenUsage、partialResponse 等可选信息。没有正文保存确认或普通 Agentic 已提交的统一含义。
正文处理、流式完成和记忆原文的合同
基础生成器保留的 rawText 已经过 stripAssistantSuffixLeak,不能严格等同上游最原始的 token 流;但它还没有经过 postProcess 的正文正则和 after-chat 改写。postProcess 先执行 axon.filterText,blocked 即抛错,再 loadAgents(afterHookAgentRefs)。处理器引用去重保序;Promise.all 并行调用,每个都收到相同的过滤后 text、rawText 和 reasoning。收齐后按配置顺序扫描结果,最后一个非空 postProcess.data.mainContent 覆盖整段正文。空值、空串或纯空白不会在这个 after-hook 覆盖规则里清空正文;后面直接返回,没有第二次正则过滤。
这也不是一道必然拒绝坏结果的 review:不 live 的 hook 被跳过;hook 客户端把执行或 HTTP 错误转成失败诊断、没有改写结果时,Actor 不根据这份诊断强制拒绝原正文。加载 hook 配置失败等直接异常仍可能阻断。只要配置了 after-hook 引用,就会关闭即时流式输出,即使其中某项后来因不 live 而跳过。
acceptsFinalContent 是上游调用方的能力声明,不是让最终使用者点“接受”。createResponseStreamFilter 默认不启用;只有能力声明为真且规则数量、顺序、pattern 及空替换值都匹配内置 Green Apple 规则,才提供该预览过滤器。无 after-hook 且无规则可以直接流;没有可用过滤器的规则或有 after-hook,则缓冲处理。原普通 Actor 的 after-hook 整段改写与这个预览协议不能混为“所有后处理都可边做边发”。
Agent Router 流事件先交 contentDelta;当结果 completed 且 finishReason、usage 可用时,交 done,再交 usage。请求声明能力时,done 包含 finalContent=result.output.text,包括显式 ""。消费者应按字段是否存在处理整段替换,不能按 truthy 判断,也不能当新 delta 追加。未声明时不附带该字段。执行异常、非 completed 或缺必要结束/用量信息时走 error,不能仅凭已经出现过 delta 自行补一个成功 done。非流式则直接使用 choices[0].content。这里只确认 Harness 输出合同,外部聊天服务是否按合同显示与保存仍需各自验收。
TurnHarness 把 generation.text 放进最终 output,同时将 output 和可用的 generation.rawText 作为 rawOutput 传给 memory.ingest。AxonGo 表格处理用 event.rawOutput ?? event.output 执行 applyMemoryTableEdits,再根据变化和版本条件写表;不是从屏幕预览解析。其他记忆后端有各自处理,本段不意味着所有日记或所有 hook 都写入同一份原文。
依据:生成原文与后处理入口[10] · 正则、并行 after-chat 和最后非空覆盖[11] · 处理器按引用顺序加载[12] · hook 跳过与失败诊断[13] · 过滤预览能力协商[14] · 流完成、error 及最终全文[15] · 空串替换的契约测试[16] · 最终/原文分别交记忆[17] · 记忆表优先解析处理前文字[18]。
已显示半句话后,Gemini 中断会怎样接上
例如用户已看到“守卫接过铜钥匙,低声说——”,Gemini 的流却在可信完成标志前断开。main #214及后续兼容、预算修复让这次调用保留已经写出的前缀,再由 deepseek-beta/deepseek-v4-flash 接一次后文。它要求场景已配置 recovery.transientRetryModelConfigId,首模型为Gemini,调用参数没有另换成别的模型,当前主尝试已经发出可见正文、没有正常完成且未被取消。
程序将原模型收到的消息和已写正文一起交给备用模型,把正文作为assistant prefix。备用可用输出额度扣除主模型已经消耗的输出;还用备用ModelConfig窗口完整计数,计数材料只传普通role/content,供应商专用的 prefix:true 只用于实际续写请求。放不下、没有剩余额度、计数不可靠或备用也未完成时都会失败,不会再次循环切模型。续写沿用同一过滤器与后缀处理;主、备用usage相加,但任一成本缺失时不会把部分费用冒充整轮账单。完整流条件[19] · 前缀、预算、过滤与用量[20]
没有可见正文时走普通的一次性备用恢复。main #230按Gemini错误的上游来源扩大判断,包含HTTP、SSE和嵌套Google错误;本地错误、取消、恢复模型和已经恢复过的请求不递归。旧式DONE结束流仍有兼容处理,不能把缺一项metadata统一当成未完成。测试验证了机械续写、取消、预算和旧流兼容;是否会重复上一句、换语气,以及真实延迟,都还没有生产端到端验收。恢复资格[21]。这与下面保留一段partial结果的旧分支分别判断,不能互相替代。
partialResponse 的这条保留分支有具体前提:没有进入 fallbackId 的专用恢复分支;deployed0819StreamCompatibility=false;异常属于可重试上游错误或 TypeError;去掉续写边界后的正文非空;已经发出过内容/推理或尝试次数已用尽;且请求尚未取消。满足时保留正文,将缺失结束原因补为 stop 并标记 partial。之后仍要过正文后处理;缺用量时还要计数,计数失败仍抛错。只有这些步骤及外围完成条件都通过,Harness 才可能正常交付并执行记忆收尾;partial 标记本身没有禁止 ingest。
当前 dispatch 构造 Actor 时,将 target.agenticV2 !== undefined 传作该兼容开关。因此已配置普通 Agentic V2 及使用其 Actor 设置的 Story 接线为 true,不走上述 preservePartial 分支;不能把构造器缺省 false 或通用运行时测试当成这两套应用的默认行为。前台工具循环已有片段后的收尾又是另一层逻辑。
依据:专用恢复与部分结果条件[22] · 后处理、用量补计与返回[23] · 应用实际传入兼容开关[24] · 正常结果进入记忆收尾[25]。
前台循环的实际限制
控制器启用点是 preActorDirector;名称中虽有 Director,此处是前台工具编排配置,不是慢路的 update_director_state。控制器初始 system + 当前问题,工具包括 actor、可选 generate_image、可选 schedule_dio、over。最多 12 步,DIO 接线存在时 13 步;over 前需有 Actor 段落。所有 Actor 段落共用整轮有效输出 token 额度。
visual_beat 指适合配图的一段正文;成功且非空时自动安排图片,再进入下一次控制决策。不要对同一段重复请求图片。图片任务返回“已安排”及编号,不是图像本身。DIO 每轮最多成功接收一次;失败回传工具结果,控制器可继续决定。普通前台循环可与普通 Agentic 并存,也可显式配置世界书;Story 和 Sumi 仍不与这套前台循环组合。当前组合限制[26]
本章前台生成与工具循环保留 13c481b/3b99f4c 的固定源码依据;9/21 新增 Jev 属于后台选工具的可选接线,见慢通道。
固定主线 13c481b 的核源位置
配置前台技能及 Actor 参数[27]
普通正文结果类型[28]
SDK 默认快路径与替换入口[29]
静态图执行范围[30]
当前业务构造空图[31]
前台控制器输入、预算和工具执行[32]
普通 Agentic 调度不阻塞原正文返回[33]
世界书的组合限制[34]
原审阅锚点(保留追溯,不作为线上启用证明)
旧稿的全部代码链接保留于此;其中 77a1537 是历史基线,61039e5 是单独的候选分支。上面正文以本章固定主线核源为准。
代码证据 · 41 处
- 立即输出或缓冲的判断 ↗
- 重渲染与受保护材料 ↗
- 目标预算与重试 ↗
- 新增空响应条件 ↗
- 次数与普通重试分流 ↗
- 空响应判定与恢复 catch ↗
- 缓冲类 ↗
- 空响应定向测试 ↗
- POV 已有恢复配置 ↗
- 生成原文与后处理入口 ↗
- 正则、并行 after-chat 和最后非空覆盖 ↗
- 处理器按引用顺序加载 ↗
- hook 跳过与失败诊断 ↗
- 过滤预览能力协商 ↗
- 流完成、error 及最终全文 ↗
- 空串替换的契约测试 ↗
- 最终/原文分别交记忆 ↗
- 记忆表优先解析处理前文字 ↗
- 完整流条件 ↗
- 前缀、预算、过滤与用量 ↗
- 恢复资格 ↗
- 专用恢复与部分结果条件 ↗
- 后处理、用量补计与返回 ↗
- 应用实际传入兼容开关 ↗
- 正常结果进入记忆收尾 ↗
- 当前组合限制 ↗
- 配置前台技能及 Actor 参数 ↗
- 普通正文结果类型 ↗
- SDK 默认快路径与替换入口 ↗
- 静态图执行范围 ↗
- 当前业务构造空图 ↗
- 前台控制器输入、预算和工具执行 ↗
- 普通 Agentic 调度不阻塞原正文返回 ↗
- 世界书的组合限制 ↗
- 正文结果字段 ↗
- 后台启动与正文返回 ↗
- SDK 默认快运行时与替换入口 ↗
- 静态执行图的工作范围 ↗
- 当前应用的空执行图 ↗
- 前台输入、工具与整轮预算 ↗
- DIO 与图片的独立调度 ↗
5. 慢通道:当前回复继续写,后台整理后续约束
慢通道做的是“给后续聊天留下有用笔记”,不是再写一条给用户看的回复。 当前正文可以先写;后台检查哪些人、物品、秘密、承诺容易写乱,必要时保存一份新的剧情笔记。
本章讲普通 Agentic V2。9/21 对主干 fa41d220 定向复核了后台调度和新合入的 Jev 可选编排;下面五步仍是普通后台的业务流程,原有保存与专家细节继续保留固定源码依据。先记住三个岗位:分工模型挑检查项;专家给建议;Director 把旧材料和建议整理成整份新笔记。 程序负责调用、收结果、校验和保存。
**这里的“专家”具体指六个 LLM 分析工具:**剧情顾问 analyze_plot 分析故事方向;人物顾问 judge_npc 检查身份、关系和出入场;知识检查员 audit_knowledge 检查谁知道什么;世界顾问 simulate_world 分析时间与场外活动;承诺与伏笔顾问 manage_callbacks 跟踪承诺、物品、伤势和伏笔;场面顾问 direct_scene 建议视角、镜头与角色主动程度。它们交回建议文字,正式笔记由后面的 Director 整理,再由程序保存。六类职责与具体产物对照。
后台一开始知道什么,不知道什么
用户说:“我把铜钥匙递给北塔守卫,请他开门。”本轮开始的材料是:
**主角色:**艾琳,谨慎的旅伴,不替用户做决定。
**旧笔记版本 12:**艾琳和用户在北塔门外;守卫正在当值;铜钥匙在用户手中;尚无证据证明守卫知道钥匙的来历。
**近期对话:**两人到达塔门,守卫要求说明来意。
**新动作:**用户已递出钥匙并请求开门。
后台因此知道用户的新动作。它此时不知道 Actor 随后会写“守卫拒绝接收”还是“守卫接过检查”。 也没有自动收到本轮给 Actor 选中的“城主印章手令、市政厅办理”那批世界书原文。除非同样信息已在角色资料、旧笔记或历史里,不能假定后台刚核验过这条世界书规则。
先由接入方给这套聊天配置普通 agenticV2:指定各岗位用哪个模型、可供选择的工具和执行限制;程序才会装配这个后台。没配置普通后台,或者当前选择的是 Story 等另一条编排,就不能套用下面的调用顺序。 启用字段和默认菜单见本章输入与调度展开。
在这条已启用接线上,每个实际进入生成的逻辑轮安排一次后台工作,同轮重试或分段不会因此反复安排。不是累计 X 轮才启动;启动也不是所有专家必跑。 若在准备角色或读取状态时已经失败,尚未进入生成,就不能说后台本轮已安排。
9/21 新增的 Jev 选工具能力没有改变这个启动规则。SDK 另有可让宿主跳过整次慢循环的 gate,但普通 V2 没有接入该 gate;不能把“Jev 本轮没选专家”理解成“本轮没有启动后台”。普通后台当前仍先启动分工,再决定是否需要工具。
第一步:分工模型决定这句要查什么
后台分工模型,代码称 Orchestrator,会结合上述材料和可用工具说明作判断。本例可能给出两个请求:
| 请求的工具 | 把名字翻成人话 | 传给工具的理由和关注点示例 |
|---|---|---|
judge_npc |
检查配角身份、关系与行为是否连贯 | “检查北塔守卫是不是原来那个人、是否仍在门口;递钥匙后不要凭空变成朋友。” |
audit_knowledge |
检查谁知道什么、有没有把猜测当事实 | “守卫看到钥匙,是否就能知道来历?请求开门能否记成已放行?” |
这不是两个真正在世界里执行的动作。“检查守卫”不会创建角色数据库;“检查知识”也不会搜完世界书。它们是专门的模型分析,收到角色、旧笔记、近期对话、当前问题,以及这次为什么请它来。
模型也可以认为本轮无须工具,保留旧笔记。例如用户只说“嗯,我知道了”,没有新的连续性问题,后台并不一定产生任何更新。
可选的 Jev:把“挑工具”和“写调用理由”分开
这里是已合入 main 的普通 V2 工具选择适配(#195)。截至 9/22,Compact 的 #196 历史过滤与 #198 助手段落过滤也已合入主干,默认关闭。它们使用 Jev 判断“哪些旧聊天或助手段落送去做摘要”,由 Compact 流程触发;不选择六专家、不直接更新剧情状态,也不改变普通 V2 每轮启动后台的规则。Compact 过滤的模式、作用与边界。
Jev 是工具选择模型的适配器,不是第七位专家。 普通 V2 原来由文本模型同时选工具并写调用参数;启用这个选项后,Jev 判断该选谁,另一个文本模型补出“为什么查、重点查什么”。后面的六专家、Director 和保存流程仍照常执行。fa41d220 已包含这条接线,仓库的场景及部署配置里没有找到启用项,不能把它当作所有 V2 当前都在用的默认模式。
接入方需要显式配置 agenticV2.jevOrchestration.argumentModelConfigId,指定补写参数的文本模型。继续用铜钥匙例子,实际过程如下;工具选择与建议内容为流程示例,不是线上执行记录。
| 发生在哪一步 | 收到什么 | 交出什么、下一步怎么用 |
|---|---|---|
| 分工前,程序准备请求 | 本章前述角色、旧笔记、近期历史、用户递钥匙原话,以及可选工具及使用条件 | 把这些材料交给 Jev;不会另外补入 Actor 正在写的新正文或同批世界书原文 |
| Jev 判断工具选择 | “这次需要人物检查、知识检查,还是都不需要?”以及对应材料 | 返回工具选项的选择/概率。普通 V2 接线按排名选出排在 none(不调用)之前的工具;没有有效概率分布时采用返回的单一选项 |
| 文本模型补参数 | 已经选定的 judge_npc、audit_knowledge,原有材料、原工具参数定义 |
补出例如“检查守卫是否已接钥匙”的 reason/focus;不得改选工具。程序合并参数并检查参数格式,成功才交执行器 |
| 原来的专家执行器 | 确定的工具名、参数和后台材料 | 人物/知识模型返回分析建议;Jev 本身不写专家报告、不创建人物档案 |
| 专家后再次判断 | 专家结果、已有材料,此阶段只开放 update_director_state |
同样由 Jev 决定是否请 Director,再由文本模型补理由;Director 仍用自己的文本模型交整份笔记,程序随后校验并提交 |
因此,本例新增的是选工具的实现方式。它没有增加新的业务工具,没有提前完成 NPC 小卡,也没有将整条普通后台改成无限循环的 Agent。首轮/新名字的补调用规则、调用额度和第二阶段规则仍由原来的程序处理;Jev 选择不调用后,程序仍可能按这些规则补必需检查。启用前还需处理预算、并列选择与追踪限制。
第二步:程序执行工具,拿回可读建议
选中的专家可以同时工作。本例可能交回:
**人物检查建议:**仍是塔门前那位当值守卫。用户已经递出钥匙,但还没有守卫回应的材料;不要擅自认定接收成功、关系变亲近或已获通行。
**知识检查建议:**守卫能够看到钥匙外观;没有证据表明他知道用户如何获得它。后续只能依据已展示或已告知的信息写他的反应。
程序拿回的是“哪个工具执行了、是否成功、分析文字是什么”等结果,再交给分工模型和可能调用的 Director。专家交回建议时还没有把它保存为正式笔记。 工具结果会带“成功/失败”。一个专家失败,不一定让整条后台停止。 普通的失败结果可以交回分工模型,后面仍可能根据其余材料决定不更新,或继续请 Director 整理。失败的检查不能在界面上被描述成“该项已经确认”。
程序另外有明确规则:工具启用时,首轮补做人物检查和场面建议;有限的名称识别规则发现旧笔记没出现的新名字时,补做人物检查。用户这句话里的新名字可以被发现;Actor 本轮刚写出来的新名字不在启动时材料里,不能立即保证被本轮后台检查。
第三步:看过建议,再决定要不要更新
如果刚执行了专家,且保存笔记的工具已启用,分工模型会再看一次专家结果。它此时只决定一件事:请 Director 整理新笔记,还是保留已有笔记。
本例它可以决定:
“需要更新:旧笔记还写钥匙在用户手里,现在用户已经递出;应记下物品交接尚待对方回应,不把请求通行误记成成功。”
这里的“再看一次”是检查工具结果后的决策,不是无限循环地再请一批专家。没有需要专家的情况,也可直接请 Director;没有值得长期保留的变化,则不用它。首轮或新人物触发了上述强制检查时,状态工具已启用的话,程序还会确保尝试一次 Director 更新。
第四步:Director 交出整份新笔记
Director 是“剧情笔记整理员”这个模型岗位。 它读旧笔记、角色与历史、用户新动作、专家建议和更新理由,把它们综合成一整份新的笔记。具体模型与提示词由配置提供;Director 不是某个固定模型产品。
它交出的东西同时包含三类内容:
| 类别 | 本例会写什么 | 以后怎么用 |
|---|---|---|
| 已有事实与明确未知 | “用户已递出铜钥匙并请求开门;现有后台材料未确认守卫接收或放行。” | 防止后续直接写成钥匙归守卫、用户已在塔内 |
| 连续性约束 | “守卫不能凭空知道钥匙来历;艾琳不替用户决定是否交代秘密。” | 给之后写人物反应时参考 |
| 软建议 | “下一段先回应当前交涉,给用户继续解释或离开的空间;暂不必新增人物。” | 可采用、可调整的写法,不是必须执行的剧情命令 |
“完整新笔记”意味着既保留未变的旧内容,也纳入这轮变化,不是只追加三句新话,更不是把几个专家报告原样粘贴。 代码把未保存的新稿叫“候选状态”。Director 自己说“已更新”也不算落库,仍需程序提交成功。
六专家里另有一个 direct_scene,界面名可能叫 Scene Director。它只提视角、镜头和角色主动程度的建议;本节这个 Director 才负责综合整份笔记。 两个名字像,岗位不同。
第五步:程序检查、保存,后续才读到
程序检查新稿是否有要求的栏目、顺序、长度,是否有不允许的内部标记、是否与旧稿不同。这些检查能挡住格式问题,不能证明“守卫已经开门”在故事里是真的。 Director 之后没有另一个模型自动把所有事实再审一遍。
通过后,程序向状态保存服务提交:“这是基于版本 12 整理的新稿。”服务若发现已经被别的轮次更新,就拒绝旧稿覆盖。成功后才成为例如版本 13。
用户当前看到的正文继续完成。后续请求准备时,若已经读到版本 13,才把新笔记交给回复模型;如果用户发下一句很快,后台还没存好,那次仍可能使用旧版。正在生成中的本轮正文不会被热更新。
没更新,也要说清到底发生了什么
| 结果 | 用户/产品应怎样理解 |
|---|---|
| 分工模型没有选工具或 Director | 没有新的笔记,不是模型故障 |
| 专家有建议,但没形成有效提交 | 做了检查;不能显示成“人物已补全并保存” |
| Director 新稿和旧稿一样 | 无须新版本 |
| 专家局部失败 | 该项未检查成功;其余材料仍可能继续参与决策 |
| Director 生成失败、稿件无效或已确认版本冲突 | 本次未取得有效新提交;后续使用当时实际可读的已保存版本 |
| 保存请求报错或超时,尚未核对结果 | 不知道服务端究竟写没写入;程序会在支持的重试路径核对,仍不明确时不能把异常等同“肯定没保存” |
| 提交成功 | 后续请求可读取新版;不保证本轮正文已保存,也不保证内容语义全部正确 |
普通 Agentic 的成果是跨轮剧情笔记,不是自动建立可独立编辑的 NPC 小卡,不是修改世界书,更不是后台所有新想法都已经变成世界事实。
技术对齐:实现边界与代码证据
输入与两阶段工具调度
agenticV2 未配置或显式 enabled:false 时不装配普通后台。配置解析要求 Actor、Orchestrator、六类专家和 Director 的 ModelConfig;即使缩减 enabledTools,此处仍要求那组专家模型引用齐全。默认菜单提供六专家及 update_director_state,不是默认执行全部。岗位提示词从各 ModelConfig 所关联的 PromptManager 加载;不能直接在该配置塞一段 directorPrompt 来替换。
后台分工输入含角色定义、可选用户人设、旧状态文本投影、最近最多 9 条有效 user/assistant 消息,以及当前问题。Compact 摘要只有在相应 enforce 接线时进入。当前世界书示例没有启用 Compact。Director 还读开场白、更新理由和专家结果。专家收到 reason 和 focus;Director 输入组装只读取 reason,不读取工具 schema 中的 focus。
菜单中列出哪些工具与执行阶段的校验不是一件事:普通应用创建专家注册表时没有开启通用 validateArguments 严格 schema 校验;默认文本编排的坏 JSON 参数会退为空对象,也没有把 enabledTools 再作为执行阶段的逐项 allowlist。Jev 可选适配层另外对选中工具及补全参数做严格解析和 schema 校验,不能用这句概括它的参数处理。不能把“提供模型菜单”宣传成“所有调用都已通过严格参数和白名单验证”。程序仍会按已注册的工具类型、去重和执行额度处理调用;完整解析边界见工具选择与执行。
普通专家的 ok:false 会加入结果并参与第二阶段;某些强制上下文治理错误等异常仍可终止本次规划,不能泛化成所有失败均降级成功。只有“有专家调用且 update_director_state 启用”才进入第二阶段;第二阶段工具菜单只有更新状态工具。首轮/新名字必需调用在该条件下补上 Director。没有专家可在第一阶段直接选 Director。
Jev 请求、输出、参数补全与失败合同
普通 V2 通过 JevOrchestratedModelRuntime 分派模型请求:Orchestrator 与可配置的 escalation 模型引用走 Jev,其他模型引用走原文本运行时;第二阶段仍使用协调器引用,因此也进入 Jev。默认文本运行时在没有 jevOrchestration 时保持原接法。参数模型必须指定文本模型引用,配置解析拒绝它与协调器/升级协调器引用相同。
Jev 的请求发往 Kaon POST /api/alpha/decisions。当前 V2 用 selectionMode="ranked":协调器 system 消息成为选择问题的 instructions,其他消息成为 state;工具名与工具描述构成选项,再加入 none。必需 boolean 和 string-enum 参数可以直接作为封闭问题询问 Jev;开放文字等缺失的必需参数,才触发一次文本模型补全请求。可选参数没填不会单独触发补全。适配器的 content 是程序拼出的“选了哪些工具”说明,不是模型生成的 RP 正文或专家意见。
补参数请求包含原 messages、被选中且缺必需参数的工具定义、Jev 已给出的调用,以及“不得改选工具”的说明。返回数量、名称不匹配会失败;合并时保留 Jev 已给出的封闭参数,再用开启 validateArguments:true 的临时注册表检查。这个注册表只验证参数,不执行工具。真实执行仍由普通 V2 原来的专家执行器完成。
决策与参数补全共享同一个取消/超时范围;上游错误、未知或重复工具、非法参数、参数模型改选工具都不能当作成功建议继续落库。普通 V2 仍按自己的模型重试和规划失败合同处理。只有决策阶段与实际发生的补参阶段都返回 usage,适配器才给出合计 token;cost 等可选数值也必须每阶段齐全才汇总,缺值代表未知而非 0。适配器本身不保存正式剧情状态。
这条可选接线当前还缺哪几项保障
| 已由固定源码与 9/21 离线复现确认的边界 | 影响哪一段 |
|---|---|
Jev send() 没读取请求里的 contextBudget,没有调用既有输入 token 计数和 enforce 阻断 |
启用 Jev 后,协调器/升级协调器的决策请求不能沿用原 Axon 文本路径的输入预算保证;参数补全、专家和 Director 仍走文本路径,不能泛化成所有 V2 预算都失效 |
工具与 none 的概率相等时,仅按概率排序并保留原 JSON 属性顺序 |
{none:0.5,工具:0.5} 与反序可能分别得到不调用/调用。当前没有独立的并列优先规则,影响的是真实工具选择,而不只是显示排序 |
已转发 OTel telemetryContext,但没有把 request.trace 转成既有 X-Kaon-LLM-Trace-* 业务标签 |
决策请求的按场景、会话、用户归因与排障信息不完整;不能写成完全没有 trace,也不能宣称与文本路径完全一致 |
这三项是当前可选接线的代码边界和启用前检查项。仓库没有启用该配置,巡检也没有真实 Jev/Axon 连续会话或生产运行证据;它们不代表已经发生线上事故。
依据:配置和实际接线[1] · 配置参数校验[2] · Jev 选择与请求体[3] · 补参数、严格校验与用量聚合[4] · 并列排序实现[5] · 仍按原规则补调用[6] · 普通 V2 每轮调度[7]。
状态格式、额度与路由
状态是带 23 个标题(总标记 + 22 项)的完整文本。包含事实、未知、约束和未来方向;“10–20 user turns”“next five user turns”是展望文字。agency 0–4、camera 比例和 guidance strength 均作为给模型的建议文本,普通运行时没有按这些值逐项执行或扣额度。
模型输入要求每个标题恰好一次;实际校验通过 indexOf 检查存在及顺序,没有严格检查重复次数。状态至少 500 字符;配置上限钳制到 800–8000 字符,默认 8000。
默认 maxToolCalls=7、maxParallelTools=6,第一批执行取两者较小值;不是整轮最多 7 次模型调用。协调器、第二阶段、Director 和失败重试都有模型请求。单次模型调用默认 180 秒,失败最多再试两次。routingMode=manual 表示不自动升级模型,不表示人工选工具;auto 需额外模型配置,默认选工具数阈值 3。
主线与候选的正文保存门槛
主线后台使用独立任务信号,不等 Actor 新正文生成或保存,也不会因为 Actor 取消就自动撤销。后台资料固定在开始时;调试记录里出现本轮正文不代表本轮专家重新读取过。
候选 61039e5 的已接入普通 Agentic,在提交前等待指定 ID 的非空助手消息保存,并绑定状态快照及正文锚点,后续按可见分支选择快照。它增加的是正文存在/分支归属门槛,仍没有等待结束后把正文重新交给专家分析;也不等于用户点了接受。候选不能当主线能力。
本章 Jev 与启动规则已按 fa41d220 定向复核;下面的 13c481b/3b99f4c 链接保留原有专家和保存机制的固定证据,不表示最新两仓所有文件已完成全量审查。
固定主线 13c481b 的核源位置
普通后台的启用、模型引用与菜单配置[8]
工具调用分类、并行与后续决策[11]
后台材料与一次调度[12]
分工模型输入[13]
专家工具的职责[14]
专家输入编译[15]
首轮与新人物规则[16]
并行专家、第二阶段和 Director[17]
Director 的完整输入输出[18]
模型角色由远端 PromptManager 定义[19]
状态栏目与校验[20]
默认工具和模型限制[21]
原审阅锚点(保留追溯,不作为线上启用证明)
旧稿的全部代码链接保留于此;其中 77a1537 是历史基线,61039e5 是单独的候选分支。上面正文以本章固定主线核源为准。
- 轮初状态、历史与当前问题的准备[22]
- 协调器实际收到的材料[23]
- 一次调度与 Actor 并行[24]
- 在生成入口启动后台[25]
- 专家实际输入[26]
- 首轮与新名字的强制规则[27]
- 专家并行执行[28]
- 专家复核与 Director 选择[29]
- Director 的输入和完整替换要求[30]
- 候选校验[31]
- 有效提交与冲突结果[32]
- Axon 状态写入边界[33]
- 后续读取与 Actor 材料注入[34]
- 状态和专家记录的文本投影[35]
- 后台独立信号[36]
- 主线提交路径[37]
- 候选普通 Agentic 的实际接线[38]
- 按可见分支选快照、等待与绑定正文[39]
- 候选提交前等待及 CAS[40]
- 默认限制与路由配置[41]
代码证据 · 41 处
- 配置和实际接线 ↗
- 配置参数校验 ↗
- Jev 选择与请求体 ↗
- 补参数、严格校验与用量聚合 ↗
- 并列排序实现 ↗
- 仍按原规则补调用 ↗
- 普通 V2 每轮调度 ↗
- 普通后台的启用、模型引用与菜单配置 ↗
- 普通应用的注册表装配及默认参数校验 ↗
- 注册表参数解析与执行 ↗
- 工具调用分类、并行与后续决策 ↗
- 后台材料与一次调度 ↗
- 分工模型输入 ↗
- 专家工具的职责 ↗
- 专家输入编译 ↗
- 首轮与新人物规则 ↗
- 并行专家、第二阶段和 Director ↗
- Director 的完整输入输出 ↗
- 模型角色由远端 PromptManager 定义 ↗
- 状态栏目与校验 ↗
- 默认工具和模型限制 ↗
- 轮初状态、历史与当前问题的准备 ↗
- 协调器实际收到的材料 ↗
- 一次调度与 Actor 并行 ↗
- 在生成入口启动后台 ↗
- 专家实际输入 ↗
- 首轮与新名字的强制规则 ↗
- 专家并行执行 ↗
- 专家复核与 Director 选择 ↗
- Director 的输入和完整替换要求 ↗
- 候选校验 ↗
- 有效提交与冲突结果 ↗
- Axon 状态写入边界 ↗
- 后续读取与 Actor 材料注入 ↗
- 状态和专家记录的文本投影 ↗
- 后台独立信号 ↗
- 主线提交路径 ↗
- 候选普通 Agentic 的实际接线 ↗
- 按可见分支选快照、等待与绑定正文 ↗
- 候选提交前等待及 CAS ↗
- 默认限制与路由配置 ↗
6. 后台状态如何真正影响后续回复
后台笔记只有保存成功,并在后续请求准备时被读到,才有机会影响新的回复。 “专家说了一段话”“Director 写完一份稿”“服务器存成新版”“下一轮真的读到新版”,是四个不同状态。
这一章专门看最后一段接力:新版到底保存了什么,下一句怎样用起来。仍用普通 Agentic 当前固定主线 3b99f4c;所引 13c481b 的状态接线文件未变,不把 Story 的正文核对规则混进来。
先把四种东西分清楚
| 名字 | 本例实际内容 | 谁使用、是否已保存生效 |
|---|---|---|
| 专家建议 | “用户请求开门,不等于守卫已经放行。” | 分工模型和 Director 用来判断;建议返回不等于存入正式笔记 |
| Director 新稿 | “保留艾琳和守卫已有关系;记下递钥匙动作;接收和放行尚待确认;后续先回应交涉。” | 程序检查并尝试保存,仍可能被拒绝 |
| 已保存笔记 | 整份状态笔记文字(不是助手聊天正文)+ 保存版本 13 + 来源轮次/消息 + 本次工具记录 | 状态服务按这位用户、这个会话和这套场景保存;后续请求可以读取 |
| 执行报告 | “读取版本12,尝试更新,成功保存版本13;人物和知识工具执行成功。” | 日志、监控或调试界面使用;不会当成角色台词发给用户 |
“状态”就是这里的剧情工作笔记;“快照”就是把某一保存版本连同来源一起取出来;“ledger”是随有效提交保留的部分专家记录。不用记住英文也能理解:正文是聊了什么,笔记是后面还要留心什么,执行报告是这次程序办得怎么样。
新笔记为什么不能直接盖掉旧笔记
假设这一轮从版本 12 开始。后台交来新稿后,程序先检查格式,接着向服务请求:
“我这份新稿根据版本 12 写成。请检查是否仍允许它成为当前笔记;不要让过期稿覆盖别人刚保存的内容。”
如果没人先更新,成功后得到例如版本 13。若另一轮已经先保存了更新,本次旧稿会被拒绝,不会直接覆盖,也不会自动拿新版重新做一遍规划。这是防止并发聊天互相覆盖的版本检查,代码称 CAS。
版本号不是聊了几轮。 用户可能已经发了第 20 句话,笔记仍是版本 12,因为前面有些轮不需要更新;也可能这一轮没写入,新版来自另一轮。来源轮次回答“这份笔记依据哪次输入”,保存版本回答“这份记录更新到哪一版”。
下一句,回复模型到底重新拿到什么
上一轮用户问过开门。假设聊天产品已经保存了这一条正文:
守卫没有伸手接钥匙。“入塔要有城主印章的手令,去市政厅办理。”艾琳低声说:“看来光有钥匙还不够。”
现在用户发来:
“那我收好钥匙,先去市政厅。”
下面继续使用已启用世界书、普通后台及相应回复模板的例子;没有世界书接线的方案少的是该行资料,不是靠后台自动补回。程序不是把上一轮执行报告贴给模型,而是重新组织以下文字:
| 这次的材料 | 本例内容 | 用它回答哪个问题 |
|---|---|---|
| 角色设定 | 艾琳是谨慎旅伴,不替用户选择 | 她应该怎样表达和行动 |
| 已保存的聊天历史 | 守卫明确没接钥匙,要求去市政厅办手令 | 上一句到底发生了什么;钥匙是否仍能被用户收回 |
| 新读到的笔记13 | 用户曾递出钥匙、后台当时未确认接收;守卫不能凭空知道来历;保留已有关系 | 哪些事项不要写乱;哪些旧未知应结合新历史重新判断 |
| 本轮重新选中的世界书 | 先重新解析该 Prompt 当前关联的书和具体版本,再从中选手令/市政厅条目 | 管理员更新 Prompt 绑定或跟随最新版时,既有会话下一轮也会采用新解析结果;相关条目是否入选仍取决于选择规则 |
| 用户现在这句 | 收好钥匙,先去市政厅 | 当下要回应的新动作 |
模型可能写:
艾琳看了眼仍紧闭的塔门,跟上你的脚步:“先把手令办妥,我们再回来。”
这里“守卫没接钥匙”来自已保存的正文;“不能无依据知道来历”来自笔记约束;“手令怎么办”来自适用设定和已说过的对话。后台笔记保留的“尚未确认”不会自动把后来保存的正文删除,模型需要结合全部新材料理解。
代码没有证明模型一定正确解决所有冲突;如果笔记与聊天写反,版本检查不能帮它判断哪个剧情更可信。产品不应把“保存成功”展示成“全部设定已核实”。
下一句来得太快,或者后台没成功,会怎样
| 准备下一轮时的实际情况 | 这次使用什么 | 应怎样描述 |
|---|---|---|
| 新笔记13已保存,而且被读到 | 新笔记13 + 此轮其他材料 | 新约束可以参与本轮回复 |
| 后台仍在工作,先读到笔记12 | 笔记12 + 已有历史等 | 先用旧笔记,不中途热替换 |
| 没必要更新、或新稿与旧稿相同 | 当前已有笔记 | 无更新;并不代表出错 |
| 新稿无效、Director 调用失败或发生版本冲突 | 当时可读的已保存版本 | 这次未产生有效新状态,不能说人物补全已落库 |
| 用户停止正文,但主线后台后来提交成功 | 后续仍可能读到它 | 主线并未以“用户接受了正文”为统一保存条件 |
这里“没有新笔记”指没有新增版本,但旧记录可正常读取;这时后续仍有角色资料和聊天历史,模型不是突然失忆。状态服务明确返回“还没有记录”时,程序会准备初始笔记;服务报错或超时则不是“无记录”,会使这一轮准备失败,不能假装空白状态继续。 读取前后的准确字段见保存与读取结构。
笔记的价值是把容易被长历史冲淡的连续性约束持续带入;它不代替正文,也不是完美记忆。后续是否真的收到某条专家记录,还取决于投影的筛选和长度限制。
它保存在哪里,哪些事还没有接通
普通 Agentic 通过 Axon 的 RP 状态接口保存这份笔记及相应记录,使用用户、会话、执行方案共同定位。换会话或方案后不会自动沿用原来的那份记录。仓库提供调用和读写合同,Axon 服务实际使用哪种数据库及生产记录是否写入,不能仅凭这段接线证明。它不会在这一步自动改角色卡、世界书、日记或 Story 世界状态。
例如后台写“新增一位谨慎的北塔守卫”只是笔记文字。若业务想获得一张可独立打开、编辑、检索、复用的人物小卡,还要接专门的数据结构和保存/读取流程;不能把专家提过人物信息就算作小卡已创建。
专家记录也不是全部永久注入:只有随有效状态提交保存的记录,后续才可能被选取、编成文本并受长度限制。调试页面上曾经显示过一份建议,不代表每轮回复模型都能再次读到它。
技术对齐:实现边界与代码证据
保存结构与正文展示是两套结果
快照字段 found 表示是否有保存记录,revision 为保存版本,sourceTurn 是来源轮次,sourceMessageId 关联本轮助手消息,historyRevision 为历史位置,state 为整份笔记文本,toolsCalled 为调用名单,ledger 为附属连续性记录。没有独立 contextPatch/director_notes 合并协议。Axon 接口的 source_turn/source_message_id/history_revision/tools_called 在适配层映射为这里的驼峰字段;返回缺省时 revision/sourceTurn 取 0、state 取空字符串、记录列表取空数组,但没有把远端异常吞成 found:false。业务后续调用先读取这份快照,再把 state 与选中的 ledger 编成模型能读的文字,不把整个快照 JSON 原样当剧情输入。
候选校验要求文本非空、至少500字符、长度限制、标题存在/顺序、没有指定内部标签,并对空白归一化后比较是否改变;不是知识事实校验。有效变化才走 compareAndSet。规划报告 stateOutcome 的 retained、unchanged、invalid、failed、stale_write_rejected、committed 各有含义,不能合并为一个成功状态。
专家记录如何投影到后续输入
成功专家结果随有效提交进入 ledger。按工具映射为 event、npc、knowledge、world、callback、camera;有 camera 时附加 agency 原则。其内容仍可能是建议和推断。
编译器先取状态,再把 active 或未标状态的 ledger 中最近最多60项分组,每类最多6条,每条文本最多900字符;整体再按长度裁剪。Actor 通常使用 maxStateChars+2000(默认10000字符),后台状态段6500字符。长状态会挤掉后面的账本内容。这是文字投影,不是完整数据库下发,也不是按隐藏事实逐字段做访问控制。
失败、取消与候选分支
模型失败默认最多再试两次。保存请求结果不明确后重试,遇冲突可读回核对版本、消息ID和内容,以识别实际上已成功的写入;正常竞争冲突不会无限覆盖。
Emochi 普通 Agentic 的后台未绑定 Actor 取消信号;Actor取消或失败仍可能留下后台成功保存的状态。通用 SDK有不同的信号接线,不能把此结论泛化到所有 SDK接入。
候选61039e5普通接法提交前增加等待已保存非空助手正文,并绑定状态快照和正文锚点。它没有在等待后重新把正文送入专家/Director,也不等于用户手动确认。当前固定主线 3b99f4c 的这条普通接线仍无此门槛,详情仍单独按候选理解;本章没有核对该候选的发布或线上部署。
下方保留普通状态格式、提交与读取的固定源码依据;新增 Jev 选工具方式没有将保存改为等待本轮正文,也没有给普通 V2 接入 SDK gate。
固定主线 13c481b 的核源位置
远端状态字段映射及异常传播[1]
无记录初始化与实际读取失败的区别[2]
状态快照和提交的全部字段[3]
Director 候选到最终报告[4]
保存到哪个业务接口[5]
后续读取并注入 Actor[6]
状态与账本文本编译[7]
账本构造[8]
重试与不明确保存结果的核对[9]
后台使用独立调度[10]
原审阅锚点(保留追溯,不作为线上启用证明)
旧稿的全部代码链接保留于此;其中 77a1537 是历史基线,61039e5 是单独的候选分支。上面正文以本章固定主线核源为准。
7. 上下文组装:每个模型实际拿到哪份材料
这些“节点”就在 Harness 处理一轮请求的程序里:Actor 负责写当前回复;后台先由协调器选工具,程序调用专家,必要时再由 Director 写新状态,最后交程序检查和保存。 原表的“后台分工及检查模型”实际上包含多个步骤,不能当成一个模型。
本章先看每次输入和上下文容量,再区分各控制入口的提示词;下半部分逐段对照 Harness 固定 main 3b99f4c,展开“普通 Agentic V2+世界书”这一套接线。下面的台词、工具参数和状态片段是教学例子,不是实际运行日志,也不是从线上导出的完整 Prompt。 Story、Sumi、前台工具循环各有不同流程,不暗中叠进这张图。
材料准备完以后,模型这一回实际收到什么
**在当前角色聊天接线里,Harness 会为每次模型调用重新交一份输入。**上一次聊天、以前保存的状态,不会因为“以前用过这个模型”就自动出现在这一份输入里。程序要重新取得本次需要的内容,按模板和容量整理,再发给模型。Actor、协调器、专家、Director 是不同调用,各自收到一份输入;并行并不意味着共享一个正在增长的窗口。
拿“用户向北塔守卫递钥匙”这一轮来说,普通 Actor 的输入可能包含下面这些实际文字。这是示意内容清单,展示资料如何变成模型可读文本;精确消息顺序、system/user角色与段落位置由当前模板和世界书位置配置决定,不是线上 Prompt 导出。
写作要求和角色资料:艾琳谨慎、少言,不替用户决定行动。
已保留的聊天原文:用户与艾琳来到北塔门口。
读取的旧状态文字:用户持有铜钥匙,尚未进塔;交接未确认。
本轮入选世界书原文:进入北塔仍需要城主手令。
最新用户消息:我把铜钥匙递给北塔守卫,请他开门。
**这份输入放在一次模型请求的 messages 中;模型配置和输出额度另作为请求参数。**这个 Actor 调用完成后返回正文,交给聊天业务展示和保存;后台则按自己的输入和规则更新持续状态。用户下一句到来,再重新取资料、重新组装一份 messages。因此“保存了但这次没读到”“读到了但没装进去”“已经装入但模型没遵守”是三个不同问题。输入来源与组装 · 保存对象如何变成模型文字
**调工具时,循环增长的是相应调用链的输入记录。**例如协调器请求人物专家后,Harness 执行专家,将工具调用及结果交回后续协调请求;这不会把专家建议瞬间塞进正在输出的 Actor。普通后台当前只有特定的两阶段协调;SDK/前台工具循环另有自己的继续条件。各控制入口的首轮输入与后续用法
这一页讨论的是代码会怎样组装。要回答“刚刚那次线上请求到底拿到几条历史、哪个状态版本、多少 tokens”,需要核对那一次的有效模型配置、最终发出的消息和相关读取记录;源码里的配置样例不能当成那一次请求的实测值。
上下文窗口能不能改:改哪里、能装多少、超了怎么办
**可以调整,但“多看几条旧聊天”“一次装更多材料”“这句回复写得更长”是三件不同的事。**当前没有一个所有 Agent 共用的窗口数值。底层模型实际支持的容量由模型服务决定;Harness 另读取配置,用它选择历史、处理超限和请求生成。把配置数字改大,不会扩展底层模型本身。
**先看一段历史怎么被选进来。**假设聊天业务带来 60 条旧消息和本次问题,模板单独放本轮问题,并选择最近 40 条旧历史,程序就从已收到的材料里展开这 40 条,再加角色、状态、世界书等。数据库即使存了 1000 条,这次没传来的也不会因“40 改成 80”自动补齐;传够了,仍可能因总容量不够而被后续裁剪。这里的“条”是消息,不是完整对话轮数;token 是模型的计数单位,也不等于汉字数。
| 想调整什么 | 实际由谁、改什么 | 修改后能改变什么;不能保证什么 |
|---|---|---|
| 带来更早的聊天 | 聊天接入程序控制交给 Harness 的 request.messages |
多给一段可用原文。世界书 Demo 先取最多 200 条,再追加本句;这个 200 只属于该 Demo,不是全项目的历史上限 |
| 这轮采用多少条 | 提示词维护者改 PromptManager 的历史宏,例如 {{getvar::history::40}} |
从收到的历史取最近最多 40 条;没设正整数 N 就用本次可展开历史。模板没有历史插入点,不会自动全部追加;后面仍有预算处理 |
| 用于预算的总容量 | 模型配置的 context_limit;接入程序也可经本轮 runtime_decision.context_limit 覆盖 |
改变 Harness 本轮处理使用的容量值;没有全仓固定的 16K/32K 默认值。要真实扩容还须模型服务支持,必要时换允许接入的模型 |
| 本轮最多写多长 | ModelConfig 的 maxTokens/max_tokens,本轮运行参数,以及宿主传给 Actor 的明确额度 |
调整输出 token 上限。普通 Actor 的参数规范化在省略额度时默认 2048;这不是历史长度,也不是所有专家的共同默认 |
| 太长时先总结还是丢掉旧消息 | 维护运行方案的人决定是否启用 Compact,并配置压缩阈值、保留组数、摘要上限等 | 改变旧历史处理方式;没配置 Compact 不会自动调用摘要模型。具体结果及保存见历史压缩,可改参数见配置表 |
**用一份教学配置算一次容量:**假设有效容量是 16000 token,给回复预留 2048,已启用 Compact 且安全余量为 256,那么可用输入预算就是 16000 − 2048 − 256 = 13696 token。角色规则、状态、世界书、保留历史和本句共用这份输入空间;角色规则多占 1000,给其他材料剩下的空间就少 1000。将回复预留改成 4096,输入预算再减少 2048。这些是算例,不是项目默认配置;这个完整扣除公式也不能直接套在所有无 Compact 的旧处理上。
**这些改动由接入程序或配置维护者实施。**普通玩家说“你多记一点”不会直接修改运行参数。已经发送给模型的那次输入不会因外部配置随后改变而自动变大;之后重新准备的调用才可能使用新的有效配置。前台分段生成也有自己的后续调用与整轮共享输出额度,不能给每段重复算一份完整预算。
**改 Actor 的设置,不会同步修改所有后台模型。**各岗位读取自己的模型配置。Sumi 主链已改为读取托管模型参数,输入额度按 context_limit - 353 计算,输出另看 max_tokens;它不再统一锁死在旧版 16384/2000,但供应商真实窗口仍需同时容纳输入与输出。各模型的窗口归属 · Sumi 当前预算实例
继续下探:参数优先级、四种超限处理、准确代码位置
配置是怎样选出来的
闭环先把请求的 messages 映射为本次上下文,保留 ID、角色、正文和可选分组。Actor 的 ModelConfig 先看宿主明确参数,再看本轮 runtime_decision.target_model_config_id,最后用方案 modelConfigRef;目标必须在方案允许列表中。
用于容量计算的值是 runtimeDecision.contextLimit ?? runtime.model_config.context_limit。请求端准确位置为 extensions.turn_context.runtime_decision.context_limit,必须是正整数。源码没有为所有 Actor 填一个统一容量缺省值。回复额度先取 ModelConfig 的 parameters.maxTokens,没有再看 parameters.max_tokens;均未提供有效有限数字时规范化默认 2048,再由本轮 runtimeDecision.maxTokens、宿主明确 Actor maxTokens 依次覆盖。显式非正数与省略参数不是同一个处理分支,不能据此宣称所有坏值都会自动恢复 2048。
这些是业务程序传入的结构化参数;接口支持覆盖,不等于当前前台工具菜单允许模型任意扩容。已核对的世界书体验页面没有窗口、回复 token 或历史条数设置,发送时只交角色、会话和消息;要给用户这样的控制,还需产品页面与服务接线。独立工具调试允许调整部分草稿参数,属于单工具试跑。世界书页面发送内容[1] · 页面设置项[2]
请求消息来源[3] · 本轮参数解析[4] · 模型选择与允许列表[5] · 容量及额度[6] · 输出缺省值[7] · 本轮额度覆盖[8]
模板里的“40 条”还经过哪些处理
history::N 只限制本次收到的尾部消息。无正整数 N 不设这道条数限制;historySwapRoles 采用同一取数逻辑,但交换 user/assistant 角色。模板同时引用历史和独立 question/lastUserMessage 时,会从历史展开源去掉最后一项,再单独渲染问题。一个模板可以多处引用历史,因此某个宏标 40,也不代表最终 messages 永远恰好 40 条。
Demo 取最多 200 条并追加本句[9] · 历史选择与宏展开[10] · 旧宏服务回退接法[11]
四条实际处理路径,不能统称“自动管理窗口”
| 当前接法与条件 | 超长时程序实际做什么 | 这条路径的边界 |
|---|---|---|
| 已启用 Compact | 以容量减输出预留、再减 safetyMarginTokens 得到输入预算;按触发条件压旧对话组,生成摘要并重新计算输入 |
需要有效正整数容量。摘要、保留原文、固定资料仍须一起装得下;失败可能降级丢旧组,也可能阻断。保存摘要是独立步骤,完整规则沿用第 9 章 |
| 基础 Actor,无 Compact,且没有委托后续预算处理 | 调用 token 计数,以 contextLimit − 350 − 3 为目标,从较早的已渲染历史块开始移除;有独立问题时可以删全部历史,否则尽量保留末尾历史块 |
这一步没有完整扣除实际 max_tokens;无有效容量、无消息或明确 defer 时跳过。没有历史插入点时不会任意删除人设;本函数结尾没有一律强制拒绝超限,因此不能保证任何输入都自动安全装下 |
| 普通 Agentic,未走 enforce,且未预先装入状态 | 基础适配器延后预算;程序追加状态并合并 system,估算长度后保留全部 system,再从最新对话向前取,遇到下一条放不下就停止 | 估算为非 ASCII 每字符约 1、ASCII 每 4 字符约 1,每消息另加 4;不是严格 tokenizer,也没有完整预留回复额度。system 本身过大不会自动删小;无有效容量时保留。shadow 只记录精确计数和 would_block,不会因此变为强制裁剪 |
| 世界书接法的最终检查 | 预先加入状态和条目;无 Compact 时发送前按实际模型容量扣输出预留及 1000 token 安全余量,再检查全部输入 | 此路径避开上行旧状态追加/估算分支。无有效容量或超限可报 agent.context_overflow,不是自动删几条世界书就必能继续。已启用 Compact 也有最终发送校验;换模型重试要重新确认是否装得下 |
基础预算与移除[12] · 普通后台装配延后预算[13] · 旧估算算法[14] · 状态追加与 shadow 检查[15] · 世界书预算元数据[16] · 最终发送前检查[17] · Compact 预算与触发[18]
**Compact 的新配置与输入(9/21 定向更新):**执行策略现在放在 Scenario 的 compact,包括 profile、inputProtocol、outputFormat、lengthPolicy、递归及 bounded_recent;ModelConfig 继续提供所选模型、容量、参数和 Prompt。generic-json-v1 使用角色名/scenario 与待压历史等 JSON;configurable-v2 还可用清理过的角色背景、开场白和 query 组成文本,或按完整对话组顺序递归。结构摘要作为 system 材料,纯文本摘要放在 user 历史/本轮问题的安全插入位置;后台 enforce 也分别接收结构或文本摘要。不能再把所有压缩都说成“三字段摘要统一插进 system”。实际输入和输出 · 参数与示例值。
**容量够不够与记忆还在不在,也要分别看。**bounded_recent 只规划本次预算承受得起的连续近期覆盖,可能舍弃更早未覆盖组;旧摘要末消息锚点已滑出、当前历史又不足重建时,可能旧摘要先失效而没有新摘要接替。短历史边界。
**角色设定本身太长时,压缩历史可能仍不够。**显式启用 compact.rolePromptFallback 后,程序可尝试只压短本次请求的角色正文。10/12 的 #295 修复了计数来源不同导致的误拒,但精简后仍重算完整 Actor 输入,必须更短且装得下;原角色卡和摘要记录不因此改变。完整触发和计数条件。
已合入 main 的 #196/#198 改变的是“摘要模型会看到哪些旧对话”,不是扩大模型窗口。默认关闭。完整对话组过滤提供 off/shadow/apply;另可启用助手自然段过滤,段落至少 40 字且 drop 概率达到 0.8 才省略,不删除用户消息。两种策略都在 Compact 实际处理历史时参与;不是每次用户输入都调用 Jev。参数、输入和实际返回。
必须分清两份材料:摘要模型收到的是过滤后正文和缺口说明;检查点标记的是完整原始覆盖范围。若“我答应明天归还钥匙”被高置信误省略,程序不会自动从缺口数量恢复这条承诺,原始聊天数据库里的原话也不会被删除。另一个工程问题已修:供应商报输入超限时,程序清掉已采用的过滤诊断,恢复完整原始输入和原摘要,在剩余额度内重规划;预算不够就不保存新检查点。工程回退成功仍不等于分类从不误省略。完整机制和源码 · 合入与验证记录。
其他模型各用谁的窗口:不会共享 Actor 的配置
| 模型/入口 | 用什么配置 | 当前实际处理与修改边界 |
|---|---|---|
| 普通后台协调器 | orchestratorModelConfigId;升级阶段可以换配置 |
用本岗位的容量和输出额度;近期段默认最后 9 条、状态段约 6500 字符。默认文本协调器显式开启预算治理后计数,enforce 超限拒绝;可选 Jev 请求暂未执行该预算检查。没有自动套 Actor 的滑窗算法 |
| 专家与 Director | 专家各自 specialistModelConfigIds[name];Director 用 directorModelConfigId |
各自调用模型,各自预算。专家结果默认截到 5000 字符、Director 完整状态还受最多 8000 字符等校验;这些是输出材料的限制,不是模型窗口大小 |
| Story 工具模型 | storyV1.modelConfigId,初始化可另用 initializerModelConfigId |
工具发送自己的岗位要求和 JSON;callStoryJson 此处没传 contextBudget,也没覆盖 max_tokens,沿用所选模型配置。不能假定它自动执行 Actor 的历史压缩;快照 maxStateBytes 管存储体积 |
| Sumi 主模型与视觉模型 | 主链 modelConfigRef,视觉另用 visionModelConfigRef |
当前主链要求有效的 kaon-router 模型配置、正整数 max_tokens 和大于 353 的 context_limit;输入预算为后者减 353。主回复与历史提取使用同一预算规则。初始化视觉模型的开场图描述/状态提取仍另限输出 200/600;修改普通 Actor 参数不会同步改这里。当前读取与校验[19] |
| 通用 SDK 自建/快慢 Agent | 自建由宿主提供模型和 options,Fast/Slow 有各自 modelConfigId |
不默认继承 RP 的裁剪与全部资料;窗口校验取决于宿主模型适配器。Slow 的 maxTotalTokens 是累计运行用量上限,不是单次上下文容量;Fast 可传自己的生成参数 |
后台模型配置与计数治理[20] · 协调器与专家配置[21] · Director 配置及调用[22] · 专家输出处理[23] · Story 工具模型请求[24] · Sumi 固定配置与视觉额度[25] · Sumi 历史窗口处理[26] · SDK 输入和参数[27] · Slow 累计预算[28]
还有哪些数字只管其中一小块
世界书 tokenBudget 只限制选取的条目预算,不是模型总容量;普通状态 maxStateChars 管字符数;后台内置最近 9 条是近期消息范围,不是 Actor 的总窗口。Compact 的 maxSummaryTokens 管摘要输出,keepLastCanonicalGroups 管保留的完整组数,均不改变模型硬容量。前台多段 Actor 共用这一轮的输出额度,不能把一次完整额度乘以段数。前台整轮输出额度[29]
**检查某次真实请求时,应核对:**上游带来的历史 → 实际模板采用的条数/资料 → 生效 ModelConfig 和本轮覆盖值 → 走了哪条预算处理 → 最终 messages/计数与输出额度。保存了更多资料或提高其中一个数字,都不能单独证明本次模型看到了更多旧内容。
主 Agent 在循环开始时,到底读到了哪份提示词
仓库有多种控制入口,必须分别看system prompt、用户/历史材料和tools数组。这三者共同决定“模型知道什么、该做什么、能调用什么”。把它们合称“上下文”会漏掉最重要的权限和行为差别。
| 控制入口 | 提示词从哪里来,要求它做什么 | 第一次模型调用实际收到什么 | 后续输出如何被程序使用 |
|---|---|---|---|
| SDK 自建Agent | 宿主的prepare()交initialState.systemPrompt;SDK无统一RP岗位文字 |
宿主给的initialState、prompt与tools;是否含历史、角色和记忆由宿主准备 | Pi负责工具循环;宿主result()解释结果。工具返回不自动成为已保存剧情 |
| SDK slow Agent | 宿主的options.prompt是system消息 |
system岗位指令 → system状态快照(revision/sourceTurn/state)→ 历史消息 → 当前user输入;另带capabilities菜单 | 工具结果作为tool消息再次给模型;模型不再请求工具时正常完成;超出调用/步骤预算会失败,不进入prepareCommit。只有正常完成且配置prepareCommit才可能产生待保存状态 |
| 普通RP后台协调器 | 通过Axon按orchestrator ModelConfig读取外部PromptManager里名为orchestrator的模板,再替换语言/人物变量 |
system=渲染后的岗位Prompt;user=轮次、状态版本、角色定义、可选Persona、状态/有限账本、近期对话和本句;tools=本阶段菜单 | 解析tool_calls;程序补必要审计并执行;实际执行专家且启用状态工具时,再用同岗位Prompt+结果,只开放Director工具让它决定是否整理;无专家也可直接请求Director,必要审计可补状态整理 |
| 前台控制模型 | roleplay-runtime.ts直接构造system:控制本轮动作、共享正文预算、遵守图片策略、读完每次结果再决定、必须调用Actor后才能结束、自己不写RP正文 |
第一步只有这份控制system+用户原句+被过滤的工具菜单;没有把Actor的角色、整段历史、世界书和全部状态再复制一份给控制器 | 一次接受一个工具请求;执行后放入tool消息,继续判断。Actor自己使用已经准备好的完整正文输入 |
| 普通Actor | 由ModelConfig/PromptManager、角色卡、宏和已启用的资料形成实际messages;Agentic状态另按接法追加或预先计入 | 角色规则、历史、用户输入、模板引用的记忆、本轮入选世界书、选定状态等;不是上面的精简前台控制输入 | 生成用户可见正文;后置hook/正则可处理展示结果;不默认承担挑所有工具的任务 |
| Story/Sumi模型 | 各自模块提供提示词和材料协议 | Story按当前任务交世界/叙事快照与任务材料;Sumi交角色、初始化/消息状态、选中历史等 | 输出受各自schema或标记协议约束;由对应程序解析采用。不能拿普通后台Prompt说明这两条路径 |
**普通后台的岗位Prompt完整正文不保存在当前两仓的场景JSON里。**代码能确认:它从哪份ModelConfig读取、取哪个命名模板、注入哪些变量、缺什么会拒绝运行;不能把文档作者概括的“你是导演”当成线上实际system prompt。下面展示的是源码明确拼出的输入与指令;线上配置完整原文仍需对应环境的PromptManager快照,不能用测试用的假模板代替。
对着代码看:普通后台第一次实际拼出的任务材料
以下是保持源码段落顺序的教学填值,省略号仅代表此例的角色原文与状态正文,结构由程序决定:
system:从该协调器 ModelConfig 的 PromptManager 读取并渲染的 orchestrator 模板
user:
ORCHESTRATION SNAPSHOT
User turn: 12
Current Agentic State version: 8
Persisted state exists: yes
TARGET CHARACTER
Name: 艾琳
Description: 北塔守卫
Original definition:
[这张角色卡的实际定义]
CURRENT USER PERSONA
[有用户人设时才加入;明确这是用户,不是艾琳或NPC]
CURRENT AGENTIC STATE N
[程序从版本8提取的状态与有限记录,最多6500字符投影]
RECENT VISIBLE ROLEPLAY
[该路径准备的近期历史;enforce模式可带Compact摘要]
LATEST USER QUERY
我把铜钥匙递给北塔守卫,请他开门。
Choose only tools whose model calls are genuinely necessary.
A no-tool response is expected for ordinary continuation.
这份材料中的“本轮问题”是用户递出钥匙;并没有“守卫已经收下并开门”的本轮新正文。它也没有自动包含Actor这轮选中的世界书条目。后台会给出怎样的建议,首先受这些实际材料限制。
前台控制Prompt实际规定了什么
源码里的控制指令要求它:本轮正文调用共享一个token预算;按工具说明选择动作;每拿到一次结果,查看实际输出token数再决定下一步;先有Actor正文才能over;不直接输出角色台词。有图片接线时,再加入“明确图片数量优先、visual_beat成功后程序自动安排图、同一段不要重复安排”等规则。DIO的工具说明要求用户原句明确提出长期改变,受理后继续本轮Actor,不等待或轮询编译。
例如用户说“写一段会面并配图”,控制器的作用是选actor和图片动作;具体“会面的人是谁、衣服是什么、前文发生了什么”仍由Actor和图片准备流程读取各自材料。第一次控制器没拿到角色历史,不能在产品说明中把它描述为“读取全部现状后统筹整个世界的总导演”。
Review 到底在哪里,有没有每次act后都审一次
- SDK Pi loop/前台loop:工具结果回到控制模型,模型可以据此继续;这是再次决策,代码没有默认另插一个“事实审稿专家”。
- 普通后台:实际执行专家且Director已启用时,有一次协调器复看,决定是否请Director;没有专家也可直接请求Director,必要审计可补状态整理。Director交完整状态稿后程序检查格式、长度、是否变化与版本。它没有拿本轮新正文做事实复核。
- Story:下一次请求会取实际保存的上轮正文,与pending记录及其锚点核对后采用后果;它有自己的正文采用机制。
- 图片:独立的生成结果、审核证据、所属消息和写回检查;不能把“审过图”当成“所有剧情事实审过”。
因此可以说项目同时存在模型驱动的工具循环和程序固定的业务阶段;不能把所有路径统称为无限ReAct,也不能把代码里叫Planner的类都理解成“先生成一份长计划,再照表执行”。
岗位Prompt读取、必需条件与原始代码
普通后台每轮会解析协调器、Director和六专家对应配置,升级模型存在时也解析其协调模板;“这一轮没有调用某专家”不代表无需满足其配置依赖。模板按order排序,名字重复会报错,缺岗位名会报错。岗位模板须引用{{getvar::language}};Director还必须包含明确状态标题,不能只留下未展开的${STATE_HEADINGS}。语言宏还可提供characterName与characterReferenceContract,后者根据定义中明确性别标记设置称谓约束,不能可靠判断时要求使用名字或角色称谓。
普通后台协调器的精确user拼接见orchestrationInput();Director的user输入增加开场、协调器更新理由及每个专家的成功/失败结果,并要求保留不变事实、输出完整替换状态、不得把用户决定写成已发生。focus虽在通用参数schema里可出现,Director专用输入直接使用的是reason,不能宣称所有岗位都原样消费每个可选参数。
外部Prompt解析[30];语言与人物宏[31];协调器实际任务材料[32];Director实际材料及模型调用[33];前台真实system指令[34];SDK自建Agent[35];SDK slow[36]。
这些节点在哪里:先看一轮的位置图
业务请求先指定运行方案,例如世界书+普通后台。配置文件指定 Actor、协调器、专家、Director 各用哪份模型配置;Harness 的程序负责安排先后。这条应用路径的通用执行图目前是空的,岗位顺序写在 TypeScript 代码里。 因此不是去某个 Workflow 编辑器里找同名的几块节点。文末有“图上编号 → 文件与函数”的定位表。
读图先抓住两个时间点: ① 的准备完成后,程序启动后台,同时让 ② 写本轮正文;② 不等待 ⑦ 的新状态。⑦ 保存成功之后,未来请求重新读取状态,才有机会使用它。它不会回头改正在输出的这句话。
后台有三种常见走法,不能认为图上所有模型每轮都执行:
- 需要咨询再更新:③ → ④ → ⑤ → ⑥ → ⑦。 例如先核对谁知道什么,再保存知识边界。
- 无须咨询、直接整理:③ → ⑥ → ⑦。 不调用专家,也没有第二次协调。
- 没有值得保存的变化:③ 或 ⑤ 结束。 保留已有状态;本轮正文仍由 ② 生成。
依据:应用装配与空执行图[37] · 岗位装配[38] · 先调度后台,再生成正文[39]。
① 程序准备输入:具体从哪里拿、装进去什么
用户输入:“我把铜钥匙递给北塔守卫,请他开门。”聊天主角色是向导艾琳,守卫是配角。程序先拿到以下资料,再分别组装两边的请求。
| 材料从哪里来 | 本例实际文字 | 用来解决什么 |
|---|---|---|
| 角色服务中的角色定义和模板 | “艾琳谨慎、少言,不替用户决定行动。”;如有开场白,也单独取得 | 谁在演、原本怎样说话做事 |
| 业务传来的已有聊天记录 | “用户与艾琳到了北塔门口。” | 之前实际说过、发生过什么 |
| Axon 保存的这次会话状态 | 假设版本 12:“用户持有铜钥匙,尚未进塔。” | 上轮留下的连续性信息;没有存档时用程序的保守初始状态 |
| 本轮请求 | “我把铜钥匙递给北塔守卫,请他开门。” | 用户此刻的新动作与诉求 |
| 本轮按 Prompt 关联解析的世界书,经选择 | 假设入选:“开门须有盖城主印章的手令;可在市政厅登记处申请。” | 本轮相关的世界规则,只有选中并成功插入的内容才进入 Actor |
| 各岗位的模型配置与 PromptManager 模板 | Actor 的写作要求;协调器的分工要求;各专家的分析要求;Director 的状态格式要求 | 同样读到“递钥匙”,各模型要完成的任务仍不同 |
如业务提供用户人设,也会按相应接线加入。它描述用户,不是艾琳或守卫的设定。源码能确认模板在哪里加载、材料怎样拼接;完整岗位提示词由外部 PromptManager 提供,不能把本页教学文字当作线上原文。
交给 Actor 的一份: 动态写作模板展开的消息+程序插入的旧状态文字+本轮选中世界书原文。角色卡、用户人设、问题与历史先成为模板可用的资料,哪些段落实际出现,还取决于模板怎样引用;不能看到“变量已读取”就认定整张卡已经发给模型。本例假设模板包含上表所列的人设、历史和新输入。世界书选择发生在 Actor 生成前;不是后台专家先研究完再把结果递给它。
交给后台的一份: 各自岗位说明+角色资料+新输入+已有历史+同一轮起点的旧状态;各步骤再追加自己的工具参数或专家结果。后台另行组装,没有自动复制 Actor 本轮的世界书原文,也没有此刻尚未生成的新台词。 “知识专家”“世界专家”的名字不附带查书权限;这批后台工具本身没有主动检索该世界书的动作。
两份材料还可能被裁成不同长度:后台内置近期对话取最后 9 条有效用户/助手消息,不是 9 轮;旧状态及专家记录这一块,后台最多 6500 字符,Actor 当前默认最多 10000 字符。这些只是指定文本块的上限,不能当作整份请求的总预算或完整历史保证。当前世界书配置没有额外日记来源,也没有 Compact 摘要;其他方案不能照搬这个结论。
依据:状态及世界书准备[40] · 后台另建输入对象[41] · 世界书插入 Actor[42] · 实际配置[43]。
运营改了角色,下一句会怎样? 假设把艾琳从“见到铜钥匙就放行”改成“必须先查手令”。首先要确认改动进入了哪一份输入;然后要确认旧剧情记录是否仍写着“已经放行”。这两步分别发生,不会因为改了角色资料就一起完成。
| 你做的修改 | 当前普通接线实际怎样读取 | 下一句可能出现什么;要核对哪份实物 |
|---|---|---|
| 修改角色卡中的性格、背景或系统说明 | 后台准备时读取角色卡及对应 Prompt;角色定义优先采用非空的 prompt.init_prompt,为空才拼卡片的性格、场景、摘要与 system_prompt |
如果旧 init_prompt 仍非空,后台可能继续读到旧定义。应看实际选出的角色定义,不能只看角色卡编辑已成功 |
| 修改给回复模型使用的变量或模板 | Actor 经自己的变量构造、请求覆盖项、前置处理和模板渲染形成输入;与后台定义的选择路径不同 | Actor 和后台可能在这次修改后看到不同描述。应分别核对两边最终输入,不能只验证 Actor 的回复就认定后台也已更新 |
| 修改角色后继续原会话 | 普通后台仍按用户、会话与执行方案读取持续状态;这一处没有因角色文字发生变化而自动清空或重建旧状态 | 新人设可能与旧状态“已经放行”一起进入模型。更新角色资料本身不完成“重新开局”;已有剧情怎样保留或重置需要接入业务明确处理 |
这是当前准备输入的代码行为,不推断外部角色服务的缓存刷新时间。世界书也可能与角色或旧状态冲突,具体见同一轮收到互相矛盾的资料;改旧消息与重新生成对已保存结果的影响,见聊天操作与状态。
依据:后台读取角色来源[44] · 角色定义优先级与沿用旧状态[45] · Actor 变量、覆盖与前置处理[46] · 普通状态读取身份[47]。
②—⑦ 每一步拿什么、做什么、交出什么
② Actor:把本轮材料写成用户看得到的正文
它读到用户递钥匙,也读到世界书的手令规则,可以写:“守卫看了一眼钥匙:‘手令呢?光有钥匙还不行。’艾琳示意你先别急。”这是当前聊天回复,交给业务展示;正文的聊天保存由相应业务链路负责。是否边生成边展示,还取决于后处理:例如某些正则变换或生成后 hook 要先收完整正文,程序就会缓冲,不能保证第一段生成后立即送到用户。
与此同时,后台还在处理同一轮开始时的材料。Actor 不等待它写完新状态,也不会自动收到刚产生的专家建议。模型岗位名 Actor 不等于只演一个故事人物;这里同一份正文可以描写艾琳和守卫。
③ 第一次协调器:决定这次要咨询谁
Orchestrator 就是这里负责分工的模型。它收到后台材料和工具菜单。例如看见“用户递出了钥匙,但现有材料没有守卫接收的回应”,可能选择咨询 audit_knowledge(知识边界检查)。
它交出的关键结果是结构化工具调用:工具名+这次要检查的问题,不是发给用户的对白,也不是一份必须执行十几步的大计划。
本例任务单:找知识专家;理由是“递出钥匙不代表完成交接”;重点是“哪些行动已经由用户说出,哪些结果还没有证据”。
选哪位专家通常由这次模型判断;程序还会补首轮、新名字等必需检查。没有这些强制项时,模型也可以不叫专家。
④ 程序执行调用:被选中的专家各做一次分析
Harness 读取工具名和 JSON 参数,找到已注册的实现,处理重复和调用额度,再调用该工具对应的模型。多个专家可并行运行;同一批专家各看自己的材料,不先读其他专家刚生成的答案。
知识专家本例拿到:后台原有材料+自己的分析说明+上面的“理由/重点”。它可能返回:“用户已表达递出钥匙;材料未确认守卫接收、放行,也未提供手令规定;不要把请求结果写成已发生。”程序把这段建议连同成功或失败标记交回后台。
专家交的是分析建议,没有在这一步直接改世界书、写 NPC 数据库小卡或覆盖正式状态。 选中专家也不等于选中了它本来没有的资料:本例不能把 Actor 读到的手令条目算作知识专家已经核对的证据。
⑤ 第二次协调器:看过咨询结果,再决定要不要保存变化
只有这一批实际有专家调用,而且 Director 工具已启用,才进行第二次协调。输入是原后台材料+刚才的工具调用记录+各专家的成功/失败回包。
这次提供给协调器的菜单只有 update_director_state(请 Director 整理状态)。它可以决定“应保留交接尚未确认的边界”,并写一条更新理由;也可以判断没有需要长期保存的新内容。它不会在这个阶段无限再选一批专家循环下去。 首轮或新名字的必需检查还会促使程序补一次 Director 调用尝试。
这就是本路径里明确存在的一次模型复看:复看的是专家工具结果,而不是 Actor 刚写的正文。
⑥ Director:把旧状态和这轮有效信息写成整份新状态稿
Director 是负责整理跨轮状态的模型岗位。它收到旧状态、角色与开场、已有历史、新输入、协调器给的更新理由,以及专家建议或失败说明。它的任务是写完整替换稿,不是自己决定数据库已经保存。
本例可能形成下面这些内容:
当前场景:仍在北塔门外。
物品与未决事项:用户已递出铜钥匙;这趟后台尚未见到守卫接收的回应。
必须保持的事实:不要提前写成已经放行,也不要替用户决定下一步行动。
这是便于阅读的内容摘录,不是可直接提交的完整状态格式;实际稿件还必须带全套规定标题。它可以保留“后续可继续交涉”等软建议,但建议不能当作已发生的事实。
这里没有手令细节,正是因为本例后台没有收到那条世界书;也没有把 Actor 刚写的“手令呢”偷偷放进来。Director 不会凭岗位名称获得缺失资料。
⑦ 程序检查和保存:把“模型写了”变成“以后能读取”
Harness 检查状态稿的长度、规定标题及顺序、禁用内部标记,并比较内容是否变化。格式不合格可能触发有限重试;无效、未变化或 Director 失败都不形成这次新提交。这里没有另一个模型逐条证明剧情事实正确。
通过后,程序带上“我基于版本 12 写的”向 Axon 提交新状态,以及本次工具记录、成功专家建议等信息。只有版本检查通过、保存返回成功,才可视为形成新版本,例如 13;如果已有更近的工作更新过状态,旧稿可能被拒绝,不能覆盖过去。
依据:第一次调用、专家执行与第二次协调[48] · Director 实际输入与输出[49] · 状态校验[50] · 提交结果分支[51]。
④ 里面有哪些专家:具体查什么、交什么
六位专家是六种咨询任务,不是每轮同时存在的六个故事人物。它们各自拿“后台材料+专属说明+本次理由和重点”,输出分析建议;是否需要调用看协调器选择和程序规则。
| 需要检查的问题 | 工具名/岗位 | 本例可能交回的建议 |
|---|---|---|
| 情节该继续、转向还是放慢 | analyze_plot/剧情分析 | 先承接用户提出的开门请求,不立刻跳到塔内下一幕 |
| 守卫是谁,有无必要补充人物关系 | judge_npc/人物检查 | 先按已出现的守卫处理;没有材料就不把他补成艾琳的旧识 |
| 谁知道什么,什么事情已经确定 | audit_knowledge/知识检查 | “递出”不等于“已接收”,更不等于“已获准进入” |
| 时间、地点、门外人物如何保持一致 | simulate_world/世界状态分析 | 材料未显示放行和移动,不能把众人直接挪到塔内 |
| 道具、承诺和未完成事项是否遗漏 | manage_callbacks/未决事项追踪 | 保留铜钥匙交接是否完成这一未决事项 |
| 下一段关注谁、角色能主动做多少 | direct_scene/场面安排 | 可描写艾琳观察守卫,给用户回应空间,不代替用户下一步行动 |
最后一位 direct_scene 和 ⑥ Director 是两件事: 前者建议下一段怎么演;后者把需要延续的信息整理成整份状态稿。这些示例说明各工具的用途,不保证外部模型每次逐字返回同样内容。专家实现与输入拼接[52]
下一句怎么用,以及哪些情况不会生效
假设用户下一句说:“那我先问问他需要什么手续。”如果这句开始准备输入时已经保存了版本 13,Harness 会读取新状态,把“仍在门外、交接尚未确认”等内容整理给这一轮 Actor;同时,上一轮已经保存的守卫对白若进入历史窗口,这轮模型也能读到“手令呢”。它们是两个来源,不能把上一轮对白说成上一次后台已经知道。
如果后台还没保存,下一句已经读完版本 12,这句仍使用读到的旧版本;后台后来成功也不会中途替换材料。之后某次重新读取才可能使用新版。保存成功、模型收到、正文正确采用,是三个需要分别观察的结果。
本章还需保留这些实际边界:
- “每轮安排后台”不等于“每轮调齐所有专家”。 普通路径每个成功进入生成的逻辑轮安排一次后台,没有累计 X 轮才启动的总开关;首轮会在工具启用时补人物和场面检查,新名字启发式命中会补人物检查,但不保证识别所有新角色。
- 准备失败和后台失败不是一个时间点。 查询成功但没有已保存状态,可以用初始状态;状态服务请求失败、必要模板缺失等发生在生成前,可能阻断本轮。世界书绑定或选择请求失败,也没有一律当作空书继续;其向量能力的特定降级由世界书服务处理。某位专家正常返回失败说明,后续仍可能用其他结果继续。
- 当前正文没有成为这趟后台的事实审核材料。 主线也不等正文保存后才允许提交后台状态;取消 Actor 后,已启动的后台仍可能继续。这是当前实现边界,不是产品已经保证“正文采用后才记账”。
- 工具菜单不等于完整的执行校验。 当前应用没有开启严格参数校验;坏参数 JSON 可退成空对象。菜单控制给模型看哪些工具,但执行阶段没有再次逐项检查启用名单;已注册但不在菜单里的工具不能据此认定一定会被拦住。文末列了对应代码,不能在图上写成“已严格校验权限和参数”。
以上是源码可确认的接线与限制,不证明线上选用了这份配置,也不证明某次真实回复遵守了全部资料。排查一次实际运行,要分别核对最终模型输入、工具回包、状态提交结果和后续读到的版本。
对着代码找节点:实际文件、逐次输入差异、参数与既有证据
对着代码找节点:图上编号、调用函数和实际文件
这些是当前应用程序里的调用阶段,不是通用 Workflow JSON 的节点定义。调试页面显示的 Actor / Orchestrator / Director 是观测标签;同一岗位可能被调用多次。世界书方案使用哪些模型配置,见 agentic-v2-worldbook.json[53]。
| 图上位置 | 对应代码 | 这里真正完成的动作 |
|---|---|---|
| 进入这套应用 | dispatch.ts:1152[54] | 构建工具注册表、Planner、TurnCoordinator,再包装 Actor 与材料适配器;通用 executionGraph.nodes 在同文件741行为空 |
| ① 读取状态、选世界书 | planning/runtime.ts:349[55] 的 prepareActorOverlay |
读本轮旧状态;没有存档才生成初始状态;调用世界书 prepare,准备状态系统消息 |
| ① 世界书真正插入输入 | worldbook/runtime.ts:79[56] 的 decorateActorContext |
将返回的 blocks 按位置组装到 Actor 消息;并非拿整个返回 context 字符串统一拼到每个模型后面 |
| ① 后台材料另行组装 | planning/runtime.ts:453[57] | 创建 planningContext:角色、开场、问题、历史、状态、岗位模板等;没有同批世界书 blocks 或当前新正文 |
| ② 与③的并行起点 | planning/runtime.ts:706[58] 的 generate |
先 coordinator.schedule() 安排后台,再等待 base.generate() 的 Actor 正文;没有等待后台结果 |
| ② Actor 真正请求模型 | actor/roleplay-runtime.ts:877[59] | 交出整理后的 Actor 消息,并接收流式输出 |
| ③ 第一次协调 | planning/agentic-v2.ts:789[60] 的 AgenticV2Planner.run |
调 callOrchestrator,读取结构化调用;合并必需检查、处理去重/额度,并区分专家与 Director |
| ④ 执行所选专家 | planning/agentic-v2.ts:847[61];registry.ts:79[62] | Promise.all 并行执行本批;注册表解析工具参数并找到实现;advisory.ts[63] 组装专家材料并调模型 |
| ⑤ 第二次协调 | planning/agentic-v2.ts:879[64] | 有专家且状态工具启用时,追加工具调用/结果,再请求协调器;提供的菜单只有 Director |
| ⑥ Director | planning/agentic-v2.ts:364[65] 的 directorInput / createDirectorCapability |
组装旧材料、更新理由和专家结果;调用模型,交回 candidateState 完整状态文字 |
| ⑦ 校验与保存 | planning/agentic-v2.ts:978[66];planning/runtime.ts:116[67] | 决定无效/未变化/提交,向 Axon 发送预期旧版本、新状态、工具与账本;返回成功或冲突等结果 |
| 后续输入使用 | planning/runtime.ts:349[68] | 新逻辑轮重新读状态;成功读取到哪个版本,就准备哪一版材料 |
“后台”不能合成同一个输入框:四次调用的实际差异
| 模型调用 | 在已有角色、问题、历史和旧状态之外,具体追加什么 | 哪些没有直接追加 |
|---|---|---|
| ③ 第一次协调器 | 协调模板、逻辑轮数、状态版本/是否存在存档,以及本轮工具定义 | 显式拼接正文没有单独列开场白;没有本轮专家结果 |
| ④ 每位专家 | 该专家模板、开场白、本次 reason 和 focus |
同批其他专家结果;每次的 dependencyResults 为空 |
| ⑤ 第二次协调器 | 原协调输入,以及第一阶段 assistant.tool_calls 和对应 role:tool JSON 结果;工具失败说明也可进入 |
没有因为时间过去就重取 Actor 新正文;不会把所有世界书自动补上 |
| ⑥ Director | Director 模板、开场白、更新 reason、专家成功或失败结果 |
不消费参数中的 focus,也不自动接收协调器整段自由回答 |
四者都没有自动接入本轮入选世界书原文。外部模板可能另用宏引用材料,以上说的是这些输入编译函数明确追加的内容,不能据此声称已看到线上最终 Prompt。Director 写稿、程序保存也不是同一动作。
在当前 Demo 中,messages 已含本轮 user,后台又单列 LATEST USER QUERY,因此当前输入可能在近期段和新问题段各出现一次;Actor 模板同时含历史与问题时,历史处理会去掉最后这一条再展开。两边甚至不能画成逐条一致的“历史复印件”。协调器实际文本[69] · Demo 构造消息[70] · Actor 历史展开[71]
上下文就是这一次调用真正发给模型看的材料。程序读取了数据,并不等于每个模型都收到了它。
把它放回一轮执行里看: 业务请求先指定场景,Harness 按配置装配 Actor 与后台;不是先让一个 LLM 任意决定所有模块。两路各自拿到准备好的输入。普通后台先让协调器选工具,Harness 解析调用、执行选中的专家;满足条件时把结果交回协调器决定是否调用 Director,最后由程序校验和保存候选。这里的 Planner 类名不等于“先生成一份大计划再逐步执行”。本章已在上方逐步展开;其他运行方式的完整接口和复核边界见:Harness 怎样调度一轮。

原有接入与 Harness 闭环,组装工作放在哪里
预组装入口由 chat-service 准备 messages,Harness 接收并调用模型;相应日记、表格前后处理仍归 chat-service。闭环入口则由 Harness 协同 Axon 读取角色、模板、配置、历史与记忆,构造模板变量,再渲染和检查预算。后者接管了更多准备工作。
闭环中的典型材料是:角色卡与开场白、用户 Persona、最新问题、历史窗口、模板引用的记忆变量,以及已启用的状态或世界书。模板决定变量放在哪;预算处理决定保留多少。正文真正使用的是准备后的 Actor 消息,不应把另一个通用 Prompt 编译器生成过的所有块都假定再追加一次。
三类模型分别看什么
| 材料 | Actor 正文模型 | 前台控制器(若启用) | 普通 Agentic 后台 |
|---|---|---|---|
| 人设与任务 | 写作用角色模板、人设、示例 | 当前控制说明与可用工具;不等于整份 Actor 人设 | 单独组织的角色定义、分析说明 |
| 最新 query | 在对话/模板中使用 | 作为本轮要完成的请求 | 单独列为最新用户输入 |
| 已有历史 | 经模板窗口、整理及预算处理 | 根据前台循环自己的请求组织 | 默认用原请求历史组织近期 transcript |
| 已保存 Agentic 状态 | 转成写作用系统材料 | 不自动等于后台状态包 | 同一开轮快照的分析投影 |
| 世界书入选正文 | 世界书场景直接加入 | 显式配置世界书时,每次 Actor 调用和重试都会重新放置同轮选中条目并核预算;仅裁旧历史 | 没有自动加入同批正文 |
| 日记/表格召回 | 模板引用变量后才进入 | 不自动收到全部召回材料 | 没有直接复制同批 memory.items |
| 本轮 Actor 已写出的段落 | 分段续写可以使用 | Actor 工具结果会返回控制器 | 并行规划看不到 |
| 本轮新专家建议 | 不会中途自动改写当前正文 | 不自动共享后台结果 | 后台内部供协调和 Director 使用 |
世界书这一行还要拆成“选资料”和“装输入”。 现行世界书服务收到本轮原始问题、近期历史和条件;#223已移除旧版公开场景拼接,服务端只为hybrid排名补最近两条历史;角色卡全文不是世界书的检索输入。服务返回原文块后,Harness 才按宿主开放的位置插入 Actor 完整消息。现在共有八类可支持位置,但当前标准 worldbook 场景默认只开放原三类;额外位置需要模板声明,不会自动塞进 Planner。第 12 章给出完整组装图和本轮实际材料例子。本轮检索材料[72] · 位置组装[73]
“同一份状态”也会被裁成不同的材料
普通 Agentic 的 Actor 状态投影上限为 maxStateChars + 2000,默认 10000 字符;后台相关模型的投影上限为 6500 字符。它们是这一部分文本的字符上限,不是整个请求的 token 预算。
状态后附的专家记录先取有效记录窗口,再按类型限制条数与每条长度,最后还要一起截断。内置后台近期 transcript 取最后 9 条非空 user/assistant 消息,不是 9 轮;可配置模板若另引用历史宏,实际输入还可能包含更多历史信息。
普通状态投影主要做文本长度和窗口处理,没有 Story 那种按 POV 可见范围组织字段的同等机制。“写了秘密”与“秘密不会进入角色模型”不能直接画等号。
对北塔例子的实际影响
Actor 读到了世界书“铜钥匙不能代替手令”,可以据此拒绝放行。后台若没有从人设、旧状态或历史中读到同样规则,就没有收到这项判断依据。即使后台调用了知识专家,也不能说它已经核对这条世界书。
若 Actor 把门禁规则说进最终保存的对话,未来后台在历史窗口内看到这段话,才可能间接获知;Actor 只是默默参考、没有说出的其他设定不会自动传过去。
依据:预组装与闭环入口[74]、模板变量构造[75]、后台材料构造[76]、状态投影[77]、前台收到 Actor 工具结果[78]。
代码证据 · 80 处
- 世界书页面发送内容 ↗
- 页面设置项 ↗
- 请求消息来源 ↗
- 本轮参数解析 ↗
- 模型选择与允许列表 ↗
- 容量及额度 ↗
- 输出缺省值 ↗
- 本轮额度覆盖 ↗
- Demo 取最多 200 条并追加本句 ↗
- 历史选择与宏展开 ↗
- 旧宏服务回退接法 ↗
- 基础预算与移除 ↗
- 普通后台装配延后预算 ↗
- 旧估算算法 ↗
- 状态追加与 shadow 检查 ↗
- 世界书预算元数据 ↗
- 最终发送前检查 ↗
- Compact 预算与触发 ↗
- 当前读取与校验 ↗
- 后台模型配置与计数治理 ↗
- 协调器与专家配置 ↗
- Director 配置及调用 ↗
- 专家输出处理 ↗
- Story 工具模型请求 ↗
- Sumi 固定配置与视觉额度 ↗
- Sumi 历史窗口处理 ↗
- SDK 输入和参数 ↗
- Slow 累计预算 ↗
- 前台整轮输出额度 ↗
- 外部Prompt解析 ↗
- 语言与人物宏 ↗
- 协调器实际任务材料 ↗
- Director实际材料及模型调用 ↗
- 前台真实system指令 ↗
- SDK自建Agent ↗
- SDK slow ↗
- 应用装配与空执行图 ↗
- 岗位装配 ↗
- 先调度后台,再生成正文 ↗
- 状态及世界书准备 ↗
- 后台另建输入对象 ↗
- 世界书插入 Actor ↗
- 实际配置 ↗
- 后台读取角色来源 ↗
- 角色定义优先级与沿用旧状态 ↗
- Actor 变量、覆盖与前置处理 ↗
- 普通状态读取身份 ↗
- 第一次调用、专家执行与第二次协调 ↗
- Director 实际输入与输出 ↗
- 状态校验 ↗
- 提交结果分支 ↗
- 专家实现与输入拼接 ↗
- agentic-v2-worldbook.json ↗
- dispatch.ts:1152 ↗
- planning/runtime.ts:349 ↗
- worldbook/runtime.ts:79 ↗
- planning/runtime.ts:453 ↗
- planning/runtime.ts:706 ↗
- actor/roleplay-runtime.ts:877 ↗
- planning/agentic-v2.ts:789 ↗
- planning/agentic-v2.ts:847 ↗
- registry.ts:79 ↗
- advisory.ts ↗
- planning/agentic-v2.ts:879 ↗
- planning/agentic-v2.ts:364 ↗
- planning/agentic-v2.ts:978 ↗
- planning/runtime.ts:116 ↗
- planning/runtime.ts:349 ↗
- 协调器实际文本 ↗
- Demo 构造消息 ↗
- Actor 历史展开 ↗
- 本轮检索材料 ↗
- 位置组装 ↗
- 预组装与闭环入口 ↗
- 模板变量构造 ↗
- 后台材料构造 ↗
- 状态投影 ↗
- 前台收到 Actor 工具结果 ↗
- 原审阅锚点 1 ↗
- 原审阅锚点 2 ↗
8. Story:世界推进、剧情计划与正文采用
**Story(代码编排的剧情工作流,内部调用六个世界/叙事工具),已在 roleplay-harness / main。**程序先准备本轮场面和剧情目标,交给 Actor 写回复;生成完成后保存待核对记录,下一次请求再读取实际保存的正文,确认世界发生了什么。接入开发者通过 storyV1 选择这套运行方式,由 StoryTurnCoordinator 程序协调器按阶段和条件调用内部工具。流程步骤写在应用代码中,部分步骤内部调用 LLM;它没有使用通用 profile 的节点配置来编排这套流程。
它适合需要维护世界事件、时间和主副线进度的文字剧情业务。**应用里的 Story 是一套已接线的运行流程;工具包里的 Story Tools 是这套流程使用的六个工具。**主干同时包含这两层代码。codex/pov-story-tools 是历史 Git 开发分支名,不能用它代替业务模式或工具的名称。Story 有自己的剧情计划与结算,具体动作见本章工具表。
先看它与普通后台最关键的区别
还是用户这句话:
“我把铜钥匙递给北塔守卫,请他开门。”
普通 Agentic 在本轮开始就并行分析,不等随后写出的正文。Story 则先准备一份本轮能写的场景;这次生成完先存“等核对”的记录,到下一次请求时读取上一条实际保存的正文,再确认世界发生了什么。
本章假设产品另外选择了 Story 场景,艾琳、守卫、钥匙的素材由角色和可见剧情提供;现在也可以显式配置世界书,为 Actor 增加本轮选中的设定。没有配置不自动调用。
这个选择由接入方的配置完成,不是用户说“推进剧情”就自动切换。 Story 选择自己的准备与核对流程,普通六专家后台不会再同时运行;9 月 22 日已撤掉 Story 与世界书的旧互斥,条目接入 Story 的 Actor 正文输入,但没有自动传给 Story 的规划和结算模型。要接上哪些模型、身份和存储,见本章启用与保存边界。
第一步:回复前,准备“现在可以写什么”
Story 读取旧的 Story 状态、角色素材、已有聊天与用户的新动作。首次没有状态时,会先根据这些材料初始化。它把工作分成两部分:
| 部分 | 用人话说在管什么 | 北塔例子 |
|---|---|---|
| World,世界推进 | 人在哪里、时间与事件进行到哪、当前视角能看到什么 | 用户和艾琳仍在门外;守卫在场;“请求开门”还不能让用户直接进入塔内 |
| Narrative,叙事安排 | 这段故事想逐步揭开什么、哪些目标已有前提 | 可以围绕钥匙来历建立一点信任,但“可逐步取得许可”不是已经获准通行 |
世界准备先识别用户是在继续当前场面、主动转向已知的场外事件,还是回应已送达的邀请。递钥匙通常是继续眼前交涉。若需要换场并涉及同行者,才处理谁同行、谁留下,不能默认所有人瞬移。
叙事安排在需要时请模型生成一个可调整的目标周期,再由程序从满足前提的目标中挑这轮适合的一小步。这里既有模型,也有程序:模型补场景和目标等内容,程序维护阶段与数量、检查前提、挑选本轮目标;并非每个名字叫“工具”的步骤都再次调用 LLM。各项分工见World 与 Narrative 的实际动作。
不是每轮都能挑出一个目标。 如果上一事件还留着未完成的结算,当前编排先不派新的叙事任务;如果目标的前提都没满足,也不会硬挑一个让角色执行。这时回复仍要围绕当前可见场景和用户动作展开,不能因为没有新任务就凭空宣告进塔成功。下面演示的是本轮确实有可用方向的情况:有未结算事件时不派发[1] · 没有合格目标时的空结果[2]
**本轮给回复模型的场景说明:**用户、艾琳和守卫在北塔门口。先回应递钥匙动作。可以表现守卫谨慎核验;不要把提出请求写成已经通行。可以轻轻推动彼此了解,下一步仍由用户决定。
这份说明在正文之前加入回复模型的输入,所以这一轮要等它准备完。它是当前可用事实和可选写作方向,不是把整个后台世界和所有秘密交给角色。
第二步:回复模型写正文,先保存一条“等核对”的记录
本例正文可能写出:
守卫接过钥匙,翻看了一下,却没有开门。艾琳站在你身旁,等着他的答复。
这次与普通 Agentic 的示例“守卫没接”不同,是为了展示 Story 后果由这条实际保存的正文决定,不是预先固定守卫必须怎么做。
Harness 生成成功后,Story 暂存的是:
“这轮准备的是北塔交涉;对应的助手消息编号是这一条;对应用户原话是递钥匙;等待下次核对这条消息实际保存成了什么。”
这叫 pendingActor,即等待核对的回复记录。它主要保存世界准备结果及消息关联,不代替聊天服务保存这段助手正文。保存成功时的 waiting_for_acceptance,意思是“等读取权威保存的正文”,不是“用户必须点一次接受”,也不是“钥匙交接、开门、任务完成已经全部结算”。
本轮生成成功也不保证这条记录写成了。 程序随后尝试按旧版本保存;版本冲突或保存异常会进入 Story 执行报告,当前接线不会因此撤销已经完成的角色回复。遇到超时等不明确结果,还需要核对服务端记录,不能把界面上有台词当成 Story 已存好。
第三步:下一次请求先看保存正文,再处理新动作
用户下一句说:
“那我把钥匙拿回来。”
Story 会先查到上一条真实保存的助手消息,核对是不是待核对的那一条、对应的用户输入有没有被改、之前已经采用的正文是否仍匹配。
若确实保存了“守卫接过钥匙,但没有开门”,才据此推进世界:
**已发生:**钥匙曾被守卫接收。
**没发生:**守卫没有开门,用户仍未获通行。
**现在的新要求:**用户想拿回钥匙,需要本轮正文继续回应。
它不会拿现在的“拿回来”去证明上一轮必定接过。 上一轮的后果只依据当时对应的材料和保存正文;新的输入随后再处理。
整个事件到了该结算的时候,Narrative 再判断原来的目标是否完成、是否转向、是否需要重做某条线。守卫拿钥匙检查一下,不会自动等于主线“成功进塔”完成。
第四步:下一轮成功后,再把这次推进持久保存
上述新世界先在内存里准备。当前回复成功、状态提交也成功后,更新才能持久保留。如果当前轮失败,不能承诺刚计算出的推进已经落库。正文返回、准备记录保存和世界后果确认,仍有不同完成时刻。
| 遇到的情况 | 当前接线怎样处理 |
|---|---|
| 改了最新待核对正文,ID和其他关联条件仍匹配 | 按该消息实际保存的新正文结算;比如改成“拒绝接钥匙”,就不能沿用“已接收” |
| 改了关联用户输入或更早已采用的正文,导致关联检查不符 | 从当前可见的权威历史重新建立 Story 状态,而不是盲沿旧结果 |
| 待核对消息缺失或换了 ID | 无法按原记录直接采用,走历史变化处理;不会凭空补成功结局 |
| 事件结算所需证据缺失或变化 | 有限重试及隔离记录,不能假装结算成功 |
| 重生成或编辑后重生成 | 当前接线只走基础 Actor,不做 Story 准备与写入 |
| 当前消息与会话长度无法形成可信来源位置,触发受控的来源位置错误 | 回基础 Actor 生成,报告只读来源位置分支;不把无法可靠关联的一轮写入 Story |
| 首次初始化因受支持的不可用情况失败 | 可回基础 Actor 完成回复,不写 Story 状态;不是所有任意错误都承诺自动降级 |
事件提示牌:已合主线,给 Actor 的是写作提示
PR #250 已于 9/24 合入 main,Core Tools 0.2.3 已发布。事件提示牌让同一事件的几轮回复沿用一份氛围、视角和节奏提示。程序在事件开始时抽一张牌,随叙事快照保存;后续轮使用同一张,事件成功结算后再推进。交给 Actor 的是抽象写作提示,不能当成“世界里已经发生了某事”,也不覆盖用户动作和已有场面安排。牌与事件状态[3]
storyV1.omenDeck 未填写时用 64 个易经卦象加 78 张塔罗,共 142 张;空数组在配置语义上表示关闭,自定义非空数组整体替换。当前主线仍只给缺少牌组指纹的旧快照补建:已经保存过牌组指纹的会话,随后关闭或换牌,下一轮会报“牌组与快照不匹配”。因此关闭/换牌还不能当作已运行会话的安全回滚办法。已有场景 seed 为 731,同一设置下洗牌序列相同;是否符合希望的每局差异也需确认。配置语义[4] · 缺失的迁移处理[5]
10/9 核对确认该能力已合入并随 Core Tools 0.2.3 发包,不再是待合并候选。当前协调器及状态校验仍保留上述关闭/换牌限制;本次读固定源码确认,未冒称重跑旧测试。9/24 的 41 项定向检查与失败复现只属于当时的 8bf877f 记录。包发布不证明 Story 产品已启用或完成真实会话迁移验收。当前协调器[6] · 当前牌组校验[7] · Core Tools 0.2.3
这条分支交付什么
给用户的仍是一条角色回复。内部另外留下世界/叙事状态、待核对回复的关联记录,以及执行报告。这些让未来可以检查“当初准备怎么写”和“最终保存成什么”之间的关系。
这套机制更关注世界推进与剧情事件结算,包含显式计划周期;是否采用取决于产品需求与等待成本。不能把它包装成普通 Agentic 现在已经自动具备的正文复核,也不能把两套状态当成一份统一记忆。
技术对齐:实现边界与代码证据
World 与 Narrative 工具分别做什么
**以下六项才是具体的工具。**当前 Story 应用由程序协调器直接调用它们,按状态决定是否需要执行;它们不会仅因安装工具包就自动出现在普通 RP 主 Agent 的工具菜单里。
| 工具(类型) | 谁在什么时候调用、交入什么 | 返回什么、下一步怎么用 |
|---|---|---|
PovPrepareTurnTool(场面准备工具,包含模型调用) |
回复前,协调器交入当前世界快照、用户行动和角色/历史材料;识别继续当前事件、转场或回应已送达邀请,必要时判断同行 | 本轮准备结果与可见场面。程序按世界规则更新事件阶段、倒计时和暗线,把允许角色知道的内容交给 Actor;隐蔽状态不直接变成角色知识 |
PovAdvanceWorldTool(世界结算工具,包含模型调用) |
当前应用在后续请求中取到前一条已保存的完整正文后,交入该正文及对应的准备记录 | 更新后的世界快照和 committed/duplicate/pending 结果。协调器据此继续事件处理;pending 保留待结算材料,committed 仍需后续存储提交才算持久保存 |
NarrativePlanCycleTool(剧情目标规划工具,包含模型调用) |
叙事状态要求新周期时,由成功结算事件后的下一步动作触发;回复前若已无待结算事件,程序也会检查并补触发。输入为叙事快照和故事材料 | 一组剧情目标、依赖与方向;保留未完成目标,供后面的目标选择工具挑选 |
NarrativeDealBeatTool(本轮目标选择工具,纯程序规则) |
可以派发目标时,协调器交入叙事快照和当前场面阶段 | 根据前提、优先级、主副线停滞与情绪方向挑本轮目标,或返回没有合适目标;选中的方向和场面一起加入 Actor 输入 |
NarrativeSettleEventTool(剧情事件结算工具,包含模型调用) |
事件结束或中断后,协调器交入事件记录、实际采用的完整正文及对应用户行动证据 | 有证据支持的目标完成情况、剧情进度和下一步动作;材料不足时保留待处理结果,按恢复规则重试或隔离 |
NarrativeRebranchTool(剧情线路调整工具,包含模型调用) |
结算结果要求调整线路时,协调器交入叙事快照、所选主线/支线及故事材料 | 更新后的线路候选与继承关系,再交给后续目标派发;一次犹豫不会自动重写主线 |
六个工具返回的快照和建议先留在本次执行中,状态由应用按保存规则提交。世界的数字、容量、阶段与视角约束由程序维护,模型负责补充内容;到期事件按阶段延后、增加眼前压力或接下一场。公共工具允许配置执行前后回调,这些回调叫 hook;上表工具与 Story 运行模式各有明确职责。
依据:两项世界工具[8] · 四项叙事工具[9] · 应用协调器实际调用[10] · hook 定义[11]。
Story工具现在可以接收“用户是不会魔法的旅人”这样的 userPersona,帮助模型理解用户身份和视角。Core Tools 0.2.2会把非空人设裁到最多4000字符,放在JSON材料前的 CURRENT USER PERSONA 中;人设不是“用户刚刚施法”的事件证据,也不应该凭资料直接改持久世界。
不过当前 StoryV1 协调器在准备场面、结算事件、规划周期、改分支和推进世界这五处调用里都没有传 userPersona,因此这条业务链还未采用新参数。普通 AgenticV2 planner 已从Axon拿到persona,是另一条已接输入。业务直接复用Core Tools时可显式传入,但不能从“包已发布”推导出“Story用户已经受益”。工具渲染[12] · Story实际调用[13] · 普通V2实际输入[14]
保存、采用和回退
storyV1 未配置或 enabled:false 就不装配此分支。启用时必需 modelConfigId,可另配 initializerModelConfigId;默认单次模型超时 45 秒、生成后状态收尾超时 90 秒、状态序列化上限 60000 字节、seed=731。它要求显式 Agentic V2 Actor/recovery 配置及 modelConfigRef/presetRef,但 dispatch 在 Story 与普通后台之间使用互斥分支;这不是把两套后台一起启动。此场景仍不能同时配置前台控制器或 Sumi,可以显式配置 worldbook。当前配置条件[15]
世界书原文只加入本轮 Actor;StorySource 没有自动追加同批条目的字段,Story 的准备又先于基础 Actor 组装。因此“Actor 据城规写出守卫查验钥匙”不等于“事件准备模型事先读到了全部城规”。后续结算可能从已保存正文获得实际表现出来的内容;若要求准备/结算直接依据原书,仍须补传条目和版本。程序通过进程内来源标记识别真正的世界书注入,检查最后一个非世界书消息仍为当前用户输入,不能用同名客户端字段绕过;模型重试预算也保护 Story 场景约束和 lore。准备顺序与用户位置检查[16] · 受保护输入预算[17]
Story 沿用的 Actor 若配置备用恢复模型,也适用首段暂存、早期拒答与空响应恢复。POV 样例已有该配置,#208 让主模型空完成也能尝试一次备用;备用仍失败时依旧按 Actor 失败处理。它不改 Story 的正文采用和世界结算时机,不能把已显示片段当作本轮 Story 成功保存。
Story adapter 需要 authenticated turn 的 assistant_message_id。状态存储虽然复用 AgenticStateStore 接口,保存的内容却是 StoryEnvelope,不能等同普通 Agentic 的23栏目文本。初始化读取真实角色与可见历史。初始化不可用的受控分支、来源位置回退、重生成可回基础 Actor;其他异常按其规则失败。
准备阶段注入 [CURRENT STORY STAGE],包含 stage 和 narrative packet;提示明确隐藏状态不是角色知识、pending方向不是已发生事实。用户下次请求时先从保存接口读取待采用消息,再核对 userMessage 锚点和 prior acceptedMessage 内容哈希。最新待采用正文内容可改变;关联用户输入和此前已采用正文的锚点仍需匹配。
settle 只在 Harness 的 completed 结果后调用,还要求 usable prose;它序列化 prepared 状态及 pendingActor,用版本 CAS 保存,成功为 waiting_for_acceptance。保存版本冲突被记录为 stale_write_rejected,其他收尾异常被记录为 failed;正常已准备分支内的这类异常被转成报告,不把已经 completed 的 Harness 结果改写成生成失败。工具返回的 world/narrative 快照先在当前编排内存里使用,不由每个工具自行写到 Axon。
真正 PovAdvanceWorld 读取匹配正文后推进;若 outcome=pending,宿主抛错中止本次准备,原已保存的 prepared 留待后续重试,不能宣称世界已推进。这与“叙事待处理事件未清空,所以暂不派新目标”是不同分支。事件证据缺失/改变会经过受限重试和隔离记录;进展在本轮内存中,仍需随后有效提交持久化。
本章保留 Story 工作流的固定源码依据。9/21 新增普通 V2 的 Jev 和通用 SDK gate,没有据此认定 Story 启动或结算方式变化。
固定主线 13c481b 的核源位置
Story 配置字段与默认值[18]
Story 装配与互斥分支[19]
生成完成之后再尝试 Story 保存[20]
保存失败转报告的范围[21]
Story 组合限制[22]
读取角色、基础 Actor 回退、重生成和状态接线[23]
读取保存正文并核对上一条[24]
准备 world 和 narrative、Actor 场景说明[25]
采用已保存正文推进世界[26]
本轮先保存 pendingActor[27]
世界工具[28]
叙事工具[29]
原审阅锚点(保留追溯,不作为线上启用证明)
旧稿的全部代码链接保留于此;其中 77a1537 是历史基线,61039e5 是单独的候选分支。上面正文以本章固定主线核源为准。
代码证据 · 34 处
- 有未结算事件时不派发 ↗
- 没有合格目标时的空结果 ↗
- 牌与事件状态 ↗
- 配置语义 ↗
- 缺失的迁移处理 ↗
- 当前协调器 ↗
- 当前牌组校验 ↗
- 两项世界工具 ↗
- 四项叙事工具 ↗
- 应用协调器实际调用 ↗
- hook 定义 ↗
- 工具渲染 ↗
- Story实际调用 ↗
- 普通V2实际输入 ↗
- 当前配置条件 ↗
- 准备顺序与用户位置检查 ↗
- 受保护输入预算 ↗
- Story 配置字段与默认值 ↗
- Story 装配与互斥分支 ↗
- 生成完成之后再尝试 Story 保存 ↗
- 保存失败转报告的范围 ↗
- Story 组合限制 ↗
- 读取角色、基础 Actor 回退、重生成和状态接线 ↗
- 读取保存正文并核对上一条 ↗
- 准备 world 和 narrative、Actor 场景说明 ↗
- 采用已保存正文推进世界 ↗
- 本轮先保存 pendingActor ↗
- 世界工具 ↗
- 叙事工具 ↗
- Story 接入及重生成分支 ↗
- World 的玩家意图、准备与推进工具 ↗
- 叙事计划、机械派发、结算与重分支 ↗
- 正文完成后保存待核对状态 ↗
- 下一请求核对并采用上一条正文 ↗
9. 记忆与资料:什么时候存,下一轮取回什么,模型怎样用
**这套 RP 没有一个“把这一轮全部记住”的统一保存按钮。**聊天原文、普通后台状态、日记、记忆表、历史摘要和世界书各有用途、写入时间与读取者。它们共同支撑后续聊天,但不能用“慢通道结束了”代表全部保存完成,也不能用“读到了记录”代表每个模型都看到了它。
本章先把同一句话走到下一轮,再展开各条真实流程。最新按 2026-10-09 差异巡检回填,Harness 82e0169、Worldbook ad38dce;原有机制保留各自固定依据。Compact 新增显式后台执行、记忆保留和角色定义兜底;Sumi、Entity 关联分别更新其保存与回读条件。源码接线、配置启用、外部保存和实际部署分别判断,示例不是生产回包。
先看一轮到下一轮:同一把钥匙会留下哪几份东西
假设艾琳此前把铜钥匙借给用户,两人还约好明早去北塔。用户现在明确说:
我已经把铜钥匙还给艾琳了。明早去北塔找人的约定不变。
**发送后、写回复前,先读旧资料。**聊天业务带来这段会话的历史;程序读取所选方案需要的角色、用户资料和旧记录。若启用普通后台,此时拿到的状态可能仍写“钥匙在用户手中”;若接入日记或表格,取回的摘要/表格文字也可能还保留旧内容。新输入明确声明的“已经归还”与旧记录一起进入本轮准备;这一步没有等待未来后台把旧记录全部改好。
**本轮 Actor 先接住变化;并行后台从自己的那份材料出发。**Actor 可以回复:“艾琳收好钥匙。‘那就明早见。’”普通后台能依据用户已宣布的归还分析状态,却没有自动收到 Actor 新写的“收好”细节,也不自动获得 Actor 用过的日记、表格或当轮世界书。它按需要咨询专家,再由 Director 整理状态;没有值得保存的变化时可以不更新。后台每个实际进入生成的逻辑轮安排一次,日记的累计轮数门槛不能套给它。
**正文生成成功后,还有各自的收尾。**正文交给聊天业务展示并保存。启用了 Axon Go 表格时,程序用 Actor 的原始输出解析修改,成功后写新表;启用了日记时,程序安排后台任务,检查轮数、额度、冷却和锁,再决定是否另请模型总结。日记重新查询的是当时已经保存的聊天,并没有把这一条新回复强行追加进去;聊天尚未落库时,这次摘要可能不包含它。普通后台状态保存可以早于或晚于这些动作,它们没有一个统一事务。
**下一句来时,重新读取,而不是使用上次所有内存结果。**用户说“我们出发吧”,请求可能拿到:已保存的“明早见”原话;新版状态里的“钥匙已归还、北塔约定未完成”;表格提示中的“持有人:艾琳”;或日记摘要里的整段经历。实际只读取当前方案接通的那些来源。若状态后台未完成,就可能仍读旧状态;若表格已保存而模板没引用它,Actor 仍看不到新表。模型需要用实际进入本轮输入的资料理解“出发”指什么,保存本身不会让模型永久学会这段经历。
对应字段和完成事件见完成回执与实际模型输入。
这里刻意把几种可能产物放在同一时间线上,**不表示有一份默认配置同时启用它们,也不表示一处更新会自动同步其他记录。**例如“过去借过钥匙”作为经历可以保留,“现在谁持有”作为当前值需要更新;旧日记不一定应被删除,但模型必须有机会读到较新的变化。
保存发生在哪一刻,决定了能影响哪一轮
| 时间点 | 这时实际可能写入什么 | 哪个结果说明下一步可以使用 |
|---|---|---|
| 作者准备内容时 | 世界书原文修订;需要向量检索时另建对应版本索引 | 会话选择了该版本,本轮又选中并装入原文;聊天不自动发布新修订 |
| 本轮准备时判断;默认同步,也可显式后台执行 | Compact 根据完整旧历史生成摘要,通过检查后尝试保存覆盖检查点 | 同步结果可用于本轮;后台结果留到后续重新读取。成功保存且覆盖检查通过才可复用 |
| Actor 开始生成时同时运行 | 普通 Agentic 后台按需写新状态与随附连续性记录 | 有效、有变化且版本条件通过;只影响后来读到它的请求,不改正在写的正文 |
| 本次更新本轮成功完成生成后的记忆收尾 | Personalization/Hinos 的完成提交;Axon Go 日记/表格的任务或更新 | 各自外部提交或后台任务成功;Hinos 召回降级没有有效 claim 时不 commit,正常空召回仍提交;不能凭 turn.completed 判断 Go 后台已写完 |
| 当前助手正文已保存以后 | Visual World 本地实现更新此消息的视觉状态;图片流程还会单独处理交付 | 视觉记录达到 applied,后续图片准备实际读到;文字出现或图片已安排都不是同一件事 |
| Story 当前回复成功以后 | 保存世界/叙事快照和本条回复的待核对记录 | 这是等待核对,不是当前正文的全部后果已采用 |
| Story 下一次请求准备时 | 查上轮实际保存正文,计算其后果;本次成功后再提交新快照 | 核对材料与消息锚点成立、当前提交成功;计算完成但未提交还不等于持久更新 |
| Sumi 主模型生成结束以后 | 保存这条消息的正文、前后状态、图片说明和分支信息,再安排图片 | 快照写入先于完成通知;图片仍有自己的生成、审核、写入和通知结果 |
| 宿主调用 JSON 更新工具时 | 按预期版本替换完整对象 | update_memory 返回已提交的新版本;何时调用和下次怎么带给模型由宿主决定 |
聊天业务保存消息是另一条责任线:普通 Harness 生成结果并不是聊天库保存回执。世界书 Demo 明确先保存用户消息、生成后保存助手消息;其他接入要看自己的聊天链。当前代码可核对调用的 Axon/外部服务接口,不能据此替它们命名或确认底层数据库表、保留期限和整体事务。
从存储取出来,到模型真正看到,中间还有一次转换
**存储对象不等于完整模型输入。**程序通常先取结构化结果,再把模型需要的部分变成文字;版本号、锁、摘要覆盖范围等留下来控制执行。普通 Actor 还要通过本轮提示词模板和预算处理,普通后台则重新组装自己的输入。
| 取回的产物 | 实际交给模型的形式 | 程序另留什么;谁没有自动得到 |
|---|---|---|
| 聊天消息 | 本轮选用且预算保留的 user/assistant 原文 | 不是每次取全量历史,也不自动恢复上游未传入的窗口外内容 |
| 普通 Agentic state+ledger | Actor收到system状态块;协调器在user任务材料中收到状态段。两边都会裁剪并选择部分连续性记录,范围和长度不同 | 保存版本、来源轮次、工具与调试进度不等于故事事实 |
Axon Go merged_summary |
作为 compassMemory 变量供 Actor 模板引用 |
不是自动把每篇日记标题、正文、独白全文塞入;普通后台没有这个直接输入字段 |
Axon Go table_prompt |
作为 memoryTable 变量供 Actor 模板引用 |
tables 与 table_version 留给程序解析、冲突检查;普通后台不自动获得原表 |
| Personalization 返回的 setvar 宏 | 提取配置指定变量,交给 Actor 的输入准备 | hook 成功也可能没有非空记忆;服务内部保存机制不可由本仓推定 |
Hinos 返回的 memory 字符串 |
作为 hinosMemory 重渲染 Actor 模板 |
claim_id 用于完成提交,turn/state_through_round 是外部处理进度,不是正文内容 |
| Compact checkpoint | 结构摘要放入 <context_compaction> system;纯文本放入安全 user 位置,与保留原文一起组装 |
覆盖边界和指纹用于验证;普通后台只有 enforce 模式采用本轮压缩结果 |
世界书 blocks |
按允许位置包装条目原文送入 Actor | 决策说明及指纹用于诊断;同批原文不自动给普通后台 |
| Story 世界/叙事快照 | 程序准备成当前可见场景与可选叙事方向,再交给 Actor | 隐藏世界、随机状态、待结算事项不全部变成角色知识 |
| Sumi 消息快照 | 对应分支的 stateAfter 与角色/用户资料、历史进入下一次图文模型 | 图片交付租约和通知进度控制交付,不能当作剧情事实 |
| Visual World 快照 | renderVisualWorld 产生的文字供图片描述生成使用 | 不自动成为普通后台或所有文字回复的公共记忆 |
| JSON 工具读取结果 | 完整 JSON 及 revision 返回调用者;宿主自行决定投给谁 | 工具不自动改 Actor 提示词、世界书或 Persona |
例如,服务返回“钥匙已归还”,程序只把它放在变量里,而这轮模板根本没有引用该变量,模型就没有获得这条依据。日志的 recalled 说明取回过非空资料;rendered 说明相应变量被渲染后的消息使用;实际采用仍要核对最终发送的输入与生成结果。普通后台不能仅因与 Actor 用同一个模型供应商,就共享 Actor 的上下文。
开发核对:总时间线中的完成事件、版本号和具体输入含 2 处更新
turn.completed 不等于所有记忆都完成存储
本次更新完整聊天入口先 await memory.recall,再 prepareTurn、生成;确认生成结果存在且请求未取消后,才 await memory.ingest,最后发 turn.completed。当前应用默认召回 fail_turn、写入 best_effort;场景只可显式选择 memoryRecall 的容错策略,Hinos 降级无 claim 时不 commit,正常空召回仍提交。Axon Go 的 ingest 可以只完成后台任务调度便返回,Personalization/Hinos 则等待各自外部调用。普通 Agentic 后台是另一条在 Actor 开始时已安排的任务,不等这次 ingest,也不以此时助手正文已落库为统一条件。
这份 Harness 的 TurnResult.stateVersion 在完成阶段由 request.stateVersion+1 得到,不是所有外部资料共同的数据库版本。普通 RP 状态的 revision、表格 table_version、Compact 的 revision/lineage、SDK JSON 的 revision、Story 快照版本以及 Sumi 的协议version分属不同记录。Sumi 的返回 stateVersion 也不是逐项图片归档的成功计数。
Actor 采用变量,普通后台另外组装
Actor 先获取 ModelConfig/PromptManager,buildSetVars 准备已有用户Persona、外部setvar等资料,再结合模板变量与请求允许的覆盖值渲染。某变量存在不等于任何模板都必须使用。预算后的 sourceVariables 用于记录 rendered;最终请求还有各路径后续装配和检查,需查看实际发送的模型消息。
还有一层容易误判的中间结果:RPPromptCompiler 确实把 MemorySnapshot.items 编成 foundation_context blocks;但当前 closed-loop RoleplayActorRuntime 最终用 axon.history 构造真实模型请求,PreparedKaonRouter 使用这份已准备消息,不再把 compiled blocks 自动追加一次。因此“编译器有一块memory”仍不能代替检查模板渲染后的实际输入。本章Chat Kernel 试跑接法则明确消费 compiled anchors,不能把某一种运行时行为概括整个仓库。
普通后台构造 character、question、history、userPersona(非空时)、prompts、state 等自己的材料;Compact enforce 才另加 compactSummary 或 compactSummaryText,并改用 retainedHistory。这个对象没有 compassMemory/memoryTable 或本轮 worldbook blocks,也没有并行 Actor 新正文的字段。它们可能以后通过保存的聊天间接出现,但不能把未来历史路径画成同轮直接注入。
本次更新依据:读记忆、输入准备与生成[1]、生成后写入与完成版本[2]、当前召回失败策略[3]、Actor变量与模板[4]、rendered追踪[5]、编译的记忆块[6]、Actor真实消息[7]、网关实际请求[8]、后台独立材料[9]、背景任务时点[10]。
下面每条流程都接着回答:是谁触发、读回什么、写的是什么、存到哪里、失败或尚未完成时怎样处理。
每种资料下方都说明完整过程。**这里列的是项目能力与实际接线;不是要求一次请求把所有流程跑一遍。**组合关系在本章最后集中说明,具体型号的上线配置不用于定义本章范围。
聊天原话与剧情进度:先区分“说过什么”和“现在怎样”
**聊天原文由聊天业务保存。**Harness 接收本次传来的历史,或在相应应用流程中经服务读取历史;不同使用者再按自己的范围准备输入。用户说“钥匙已经归还”,这句话保存在消息里,后续带回这条消息的模型才能直接读到原话。模型本轮收到一句话,不等于聊天服务已经把它保存,更不等于以后每次都带回全部历史。
在此之外,仓库已有几套持续状态。它们属于不同运行方式,不能把其中一套的字段和生效时间套给其他几套。
普通 Agentic:保留下一次写作要沿用的事实与要求
输入是角色、本轮问题、保留的历史和旧状态。例如旧状态写“钥匙在用户手里,明早去北塔”,用户新输入明确说“已经归还,明早约定不变”。当前回复可以立即承接;并行后台按需分析,将“已归还”和“仍待赴约”整理成新状态。
专家先给建议,由汇总模型 Director 整理完整状态,程序检查后通过 Axon 保存。记录按用户、会话和执行方案定位,包含持续状态及相应连续性记录;下一次请求读到新版本,才会带给其回复或后台模型。无有效更新、检查不通过或版本冲突时,本次候选不会替换有效记录,当前正文也不因此撤回。
**这趟后台不自动收到正在并行生成的新正文。**用户已经说明“已归还”可以成为它的依据;Actor 新写的“艾琳把钥匙收进腰包”要进入未来可见聊天,才可能被以后处理。完整的状态验证、保存与后续读取集中在后台状态如何生效。
**取回的实际东西是“整份状态文字+控制保存的外壳”,不是单独一句新事实。**Axon 回包里的 revision/source_turn/source_message_id/state/tools_called/ledger 经适配器变成应用的 revision/sourceTurn/sourceMessageId/state/toolsCalled/ledger。例如版本13可能仍包含完整人物、知识、物品、未完成事项与写作建议,只在物品和约定部分改为“钥匙已归还、明早约定保留”。版本和来源由程序用来防止旧稿覆盖新稿;Actor 使用的是编成系统文字的状态与选定连续性记录,不是这份 RPC 原封不动的 JSON。后台也有自己的裁剪规则。
读取成功但 found=false 时,应用生成保守初始状态供本轮使用;读服务报错则不能当成“从未聊过”静默重置。状态的首次持久版本仍要等后续有效更新提交。后续请求读到的可能是这轮后台写入,也可能是其他较新轮次写入;不能仅凭某个版本号证明它依据的是哪条正文。
Story:保留世界进度、叙事目标,以及等正文确认的事项
这套流程维护两份业务快照:世界快照记录当前事件、人物所在场面、背景活动等;叙事快照记录目标、待办、情节安排与事件结算进度。未来计划和等待采用的事项,并不等于已经发生。
回复前,程序据此准备本轮能推进的内容。回复成功后,会保存世界/叙事资料和本条助手消息的待核对记录。**下一次请求先读取实际保存的上轮正文,核对身份与内容锚点,再采用其后果。**例如“守卫接过钥匙”可以确认交接,但不能据此确认已经开门。采用后的新进度仍须走本次的保存流程;只在内存里算出了结果,不代表持久化完成。
应用通过 Axon 状态接口保存这组资料。工具包中的世界与叙事工具接受、返回快照,宿主负责落库;单独调用一个工具不等于已保存。当前 Story 应用分支替代普通六专家后台,完整时序见Story 的准备与正文采用。
**Story 回读的是可校验的 JSON 快照,Actor 拿到的是其中本轮可用的场景。**程序读取 world/narrative/activeEvent/pendingEvents/acceptedMessage/pendingActor 等字段,先核对上次待确认消息,再准备 [CURRENT STORY STAGE],其中只投放 stage 和这轮分配的 narrative 内容。未来计划、隐藏世界与待确认回复记录不会原样全变成角色知道的事实。工具返回的快照仍需协调程序提交,单独借一个 Story 工具不自动得到整套回读与消息核对。
因此“下一次取回什么”有两层:程序拿世界/叙事快照及锚点,回复模型拿据此计算的场景说明。若世界推进返回 pending,当前编排会停止这次采用并保留原有持久准备记录供后续重试,不能把 pending 当完成后继续写入。
Sumi 先检查当前角色资料和选中的历史是否支持复用旧状态。自 #294 起,旧快照的正文与聊天服务保存正文不一致、来源不符或原生快照缺失,也会先核实已存消息,再从当前材料和有效历史重建;不再一概要求用户从编辑处重新生成。重建场景、动作和情绪,不改旧消息或重画已完成图片。完整恢复过程 · 固定源码[11]。
Sumi:让这段文字和它的图像沿同一条消息分支继续
Sumi 有独立的图文状态。先从角色、用户资料、开场和参考图准备人物/场景锚点;主模型生成时同时产生可见正文、图片描述和隐藏状态。程序提取新状态,没更新的字段沿用旧值;没有有效新状态时也可能沿用旧状态,并不保证每次都产生新资料。
一条助手回复对应一份快照,保存之前/之后的状态、可见正文、整理后的模型历史文本、父消息和图片信息。下一轮按所选消息分支读取相应快照,例如继续保留“艾琳穿蓝斗篷、仍在北塔门口”。记录经专用的 Sumi 存储范围落到 Axon;不是读普通 Director 的状态。角色/用户资料不兼容、重试输入改变或分支不匹配时,不能无条件复用。
Sumi 的 historyImportEnabled 控制普通旧历史能否只提取最近可信快照之后的片段;关闭后,快照缺失或来源不一致仍可能转入完整重建,并调用历史提取模型。它不是“关闭所有历史恢复”的开关,也不是无限历史召回。Sumi 不直接叠加普通 Agentic、Compact、额外日记/表格来源;可选世界书只进入主回复输入,不进入视觉初始化、历史恢复或自动写入持久状态。
**Sumi 回读的是所选消息分支的 stateAfter,不是普通后台的 Director 笔记。**快照里的状态是带隐藏状态标记的字段文本;托管模型从 Prompt Manager 按顺序加载 system 模板,并将当前状态供模板渲染。旧模型保留原内置模板路径,随后组织保留历史和本轮输入。解析新输出时按字段合并:未输出的字段沿用旧值,因此“这次没给新状态”不一定意味着这次回复失败。
存储按用户、会话和由 promptId+逻辑记录key 算出的专用范围隔离;消息快照还用父消息、输入签名及素材指纹防止混用。它和普通状态虽然都经 Axon 状态接口,仍不是一份共享记忆。
**Sumi 的图片归档还要再分开。**最新主线把生成结果先写入该图片任务记录,再单独排队保存图片历史;审核满足条件的 ready 结果才进入图库。图库保存的是图片及这条回复的展示资料,不是给 RP 模型回读的一份剧情记忆。消息快照已保存、图已写回聊天、图片 history 已归档、gallery 已保存,是四个不同完成点。下方展开保留本次主线的具体条件与异常边界。
图像连续性资料:为后续画图保留人物与场景依据
图像流程另有 Visual World 资料,记录外貌、衣物、道具、场景和天气等。图片工具实际需要它时,先读取此前助手消息附带的视觉状态,必要时补处理或初始化,再交给图片描述生成过程。
这一轮成功且确实准备过视觉资料后,程序可以安排更新:根据本轮正文分析变化,写回对应助手消息的附加状态。**仓内直接实现先等待助手消息已保存,再写入;默认按 120 秒窗口轮询,单次读取若耗时较长,总等待仍可能超过这个窗口。**外部图片服务的内部实现仍需按其协议确认。后续图片流程读到这份状态,才有依据沿用外观;图片任务“已安排、已送达”的记录则是交付进度,不等于剧情事实。
**Visual World 取回给图片流程的是 stateBefore 和一份 renderedState 文字。**准备时沿此前消息向前找已应用的 stateAfter;有尚未计入的正文则补处理,找不到才初始化。图片描述生成使用整理出的文字。更新后保存到目标助手消息附加的 narrative 资料中,包含 stateBefore/statePatch/stateAfter/stateStatus;下次准备只把已应用记录当作直接可用的新状态,pending/failed 还有单独回退和补处理逻辑。这条链不会自动将衣物道具变化同步到世界书、JSON记忆或普通后台状态。
核对保存位置、具体字段及下次读取者:普通后台 · Story · Sumi 快照 · 图片归档 · Visual World。
开发核对:普通状态、Story、Sumi 与视觉资料的存储和消费者
普通后台状态:一份持续状态与分类连续性记录
getRoleplayState / compareAndSetRoleplayState 按 userId + conversationId + scenarioId 定位记录。内容包括 state、版本 rev、来源轮次/消息、历史版本、工具记录和 ledger。Director 输出仍是固定栏目文本,校验包括标题、顺序及长度,不是对全部叙事事实作真实性证明。专家成功结果可以整理为连续性记录,但在这条提交链里,没有有效且变化的 Director 状态,就不会另行只提交一份新 ledger。
Actor 和后台使用各自的投放内容与长度限制;它们不是每次都读到全部存储字段。普通后台共享材料有长度上限,专家还会按类别读取近期有效连续性记录;来源轮次和工具执行记录只是追踪信息,不能都当作已经发生的故事。无更新、无效候选或冲突拒绝均不替换有效状态;非冲突保存错误有有限重试,含糊成功会再核对结果,不保证无限补跑。已启动的后台也没有自动绑定 Actor 后续取消。
依据:状态存储范围与版本[12]、状态校验[13]、连续性记录构造[14]、Director 与提交[15]、后台材料限制[16]、保存重试[17]、并行调度[18]。
Story:快照、待确认正文与消息锚点一起保存
持久记录 StoryEnvelope 用 kind=emochi-pov-story、schemaVersion=1 和 promptId 识别,包含 world、narrative、activeEvent、pendingEvents、eventSequence、已采用消息锚点及 pendingActor。世界中的背景事件、种子池、倒计时、随机数状态和待执行轮次,以及叙事中的周期、情节和结算进度,混合了故事资料与控制状态;不能把整个对象都叫“已确认事实”。
pendingActor 记录助手消息 ID、用户消息/内容锚点、本轮合成输入和采用所需投放信息。下次准备时,程序经消息服务查到实际正文,核验后才处理上轮采用;不是仅凭上轮模型返回成功就把所有提议当成已发生。待推进状态也不能当作已经完成的世界推进而继续使用。本次回复成功后才走快照提交;采用计算完成但本次生成或保存失败,并不保证新进度已落库。
PovPrepareTurnTool、PovAdvanceWorldTool 以及周期规划、情节分配、事件结算、重分支工具操作的是传入快照,并返回结果;工具本身没有替所有宿主保存 StoryEnvelope。当前应用由协调程序负责 Axon 读写,重生成/编辑后重生成还有单独处理边界。Story 使用 Actor,但替代普通六专家后台。#197 合入后,显式配置 worldbook 的 Story 已可在 Actor 前注入选中条目;不把条目同步送给 Story 的世界/叙事工具,也不自动写进快照。当前接线[19]
依据:持久字段与锚点[20]、准备与核对[21]、正文采用与提交[22]、保存正文读取与重生成边界[23]、世界字段[24]、叙事字段[25]、世界工具[26]、叙事工具[27]、应用分支[28]。
Sumi:同一助手消息的文本、状态与图像快照
Sumi 需要已配置的执行方案、助手消息 ID 和角色参考图。初始化用角色资料、用户 Persona、开场、参考图及提示词版本生成指纹,模型提取人物/场景锚点;缺失必要资料或提取失败不能视作初始化成功。后续主模型协议把可见文字、图片描述与隐藏状态分开,状态字段按协议解析并合并;没有有效更新时记录提示并保留旧值。
SumiSnapshot 包含版本、输入签名、父消息、历史摘要指纹、初始化指纹、五份材料的各自指纹、stateBefore/stateAfter、modelText/visibleText、图片及其锚点版本、用量和交付进度。经用户/会话及 promptId+逻辑记录 key 所构造的专用范围,以 JSON 和版本检查保存;单记录上限 64 KiB。快照保存先于本轮完成通知,图片交付有后续进度;不能凭正文完成就断言所有图片已经送达。
重试可以复用签名匹配的既有消息快照,输入改变则不能把当前消息直接当作原结果重放。读取此前分支时,正文变化、来源不符或原生快照缺失会先向聊天服务核实;使用协调后的有效历史重建,新的 historyDigest 和提取缓存身份也按该历史计算。即使 historyImportEnabled=false,必要重建仍可发生。历史读取仍限 500 条、256 KiB;来源 RPC、权限、取消或存储失败不能当作已删除消息继续。独立 auto_reply 仍有专用路径;配置继续排除普通 Agentic、Compact、前台编排、非空额外记忆来源及普通前后 hooks。协调与重建 · 新快照的历史来源[29]。
依据:快照字段与存储[30]、请求条件和重放[31]、初始化与历史恢复[32]、解析和保存时点[33]、状态协议[34]、历史与导入[35]、组合限制[36]。
Sumi 图片历史/图库:独立归档,不是下一次 RP 的状态输入
最新主线在拿到生成 outcome 后补上 completedAt,并先等待图片结果记录的 store.put。交付程序看到每张图已有结果后,将 persistGeneratedImage 加入独立的串行 archiveTail;这不占住生图并发槽,也不要求聊天通知先等待整条归档完成。正文、图像生成结果、聊天图片补回、图片历史、图库的成功时点分别记录。
归档先请求 Axon image.history.save。只有 ready、审核状态 COMPLETED、blocked=false、SFW 且 URL 满足匹配条件的结果,才继续 image.gallery.save;生成失败或审核拦截记为 FAILED 历史,不带图片 URL,也不进入图库;unknown 以及缺 completedAt 的旧结果跳过。它不会借补归档把旧结果重新计费生成。
历史 metadata.latestMessage 使用已经保存的消息快照 snapshot.visibleText,即这一条完整可见回复;配套图库详情接口从这个字段取得当时正文。selectedParagraph 另存本图关联的文字锚点,顶部图可为空。这条归档不重新向聊天服务读取最新编辑正文;快照文字与聊天后来被编辑后的文字可能不同。它们是图片历史/图库展示资料,当前代码没有把 gallery 回读为普通 Actor/Planner 的剧情记忆。
每项外部写入前先取得 CAS claim,校验回执后才记完成检查点。存在 claim 却没有 receipt 时不会盲目重放,避免重复外部写入,但因此可能有需要核对的漏存;不能把未重试等同于已归档。每图归档上限110秒,RPC50秒,整体队列清理也有限时,回执保存10秒;这些限制不是各阶段全部必定成功的承诺。外部 Axon/Node 接口是否实际发布、本轮真实归档效果尚未运行验证。
依据:图片归档条件与调用[37]、交付与独立归档队列[38]、先保存生成结果[39]。
Visual World:供图片描述使用,更新落在助手消息上
准备参数包括此前消息 ID、角色与用户资料、开场、参考图和语言;提交参数包括本条助手消息 ID、更新前状态及本轮原始角色输出。视觉状态包含 turn/world/characters/scenes/counters,会处理永久、当前和临时外观、场景变化及衰减;它由图片描述生成过程消费,不会自动作为普通后台的完整记忆。
本地实现从消息附加资料找最近的已应用状态,必要时补处理未纳入的正文或初始化。提交先等目标助手消息可读取:每次读取返回未命中后等待 200 毫秒,再检查 120 秒轮询窗口是否到期;没有用这个窗口强制中断正在等待的读取,因此它不是 120 秒硬超时。随后先记 pending,调用模型取得变化并应用,再记 applied;异常记失败。pending/failed 不能当作新视觉事实已生效。应用只有本轮成功且确实准备过 Visual World,才安排这项回复后工作;并非所有文字轮次都运行。图片接入也可能改走外部 MCP 服务,该服务内部的保存与超时不能用本地实现直接代替。
依据:状态与输入字段[40]、变化应用[41]、等消息保存[42]、恢复与提交状态[43]、本地/外部服务及完成条件[44]。
同一项日记/记忆需求,后端接法不同,取回与保存过程也不同
**执行方案先选 memoryRuntime,再列出 memorySources。**前者决定使用哪套服务协议,后者说明要取哪些资料变量;例如来源的 variable=compassMemory 表示日记摘要,memoryTable 表示表格提示。业务需要同时接通来源、模型模板与回复后处理。普通后台协调模型并不会在本轮临时决定“把 Personalization 换成 Hinos”。
省略接法时走 Personalization,省略来源时列表为空。**空来源只说明没有经这条来源列表取记忆,不能推出所有外部前后 hooks 都关闭。**Actor 输入准备还可以使用方案中配置的 hooks,或者在明确启用相应 hookPlanMode 时从模型配置里取得 Agent 引用;这是另一条配置装配机制,不是自动扫描仓库目录并装载所有记忆工具。
实际回包和模板转换可逐项对照Go 示例、Personalization/Hinos 协议及读取/写入失败。
**Axon Go:一次回读取到两种文字,回复后按两条不同流程写。**程序向 memory.recall 传用户、会话、是否取日记/表格及摘要条数上限,不传本轮 query。返回的 merged_summary 和 table_prompt 变成模板变量;原始表和版本由程序留存。回复完成后,日记可能另调摘要模型,表格则解析本轮模型原始输出。这两条不能混称“后台统一总结”。分别看日记怎样触发和总结与表格怎样从回复解析修改。
**Personalization:Harness 让外部 Agent 在聊天前后参与。**程序读取来源对应的外部 Agent 配置;Agent 处于 live 状态,才发送 beforeChat。外部返回类似“把用户曾归还钥匙这段文字赋给 compassMemory”的宏,Harness 提取对应内容供模板使用。回复成功后,再发送 chatResponse,把本轮最终正文、原始输出、推理及上下文交给相同 Agent。日记究竟何时形成、怎样解析、存在哪个底层库,属于该外部服务;不能拿 Axon Go 的20轮、10轮或表格冲突规则替它作保证。beforeChat 成功但不返回所需变量时,本轮仍可能没有这份记忆。
**Hinos:先准备角色,再让外部服务准备这一轮记忆。**最初的 recall 只记录请求与用户问题,返回空的待准备结果;程序先渲染角色 system,再把这些角色材料和真实聊天(最后一条必须是当前用户)送到 /v1/memory/prepare。服务返回一段 memory 文字和本次 claim_id 等进度信息。文字非空时,以 hinosMemory 重新渲染 Actor;为空则沿用第一次渲染。回复成功后向 /v1/memory/commit 提交同一 claim、本轮 user 和最终 assistant,只有协议回执 committed=true 才算该提交正常完成。服务内部采用什么摘要、检索或数据库算法,在两仓内不可见。
**Axon shadow:两边读取作比较,仍只采用旧接法。**它同时发起 Personalization 和 Go 回读,记录内容、字节数与耗时差异,交给当前回复的是 Personalization 结果;回复后也只写 Personalization。Go 的比较结果没有变成第二份模型记忆,Personalization 失败时也不会自动改用 Go。这与普通后台选择 Compact 的 contextGovernance=shadow 是两个独立配置。
**另有一条“带固定记忆试跑”的 Chat Kernel 接口,不能算自动保存链。**启用相应服务开关和地址后,/v1/turns 接受 cookie-diary 或 clove-diary-table,请求自己带 memory.compassMemory;后者还必须带 memory.memoryTable。Harness 把这些现成文字固定成本轮快照再交给外部 Chat Kernel,回复后本地不写日记/表格。它适合检查“给这份记忆,回复会怎么用”,不会先替调用者查询真实记忆或把新经历持续保存。
这几种接法在服务内部处理一轮聊天的 closed-loop 入口工作。上游已经把提示词准备好的 prepared-provider 入口,则由 Chat Service 承担日记/表格前后处理;Harness 使用空记忆适配器,避免重复写入。不能拿一个入口看到的请求时间,直接套给另一个入口。
真实回包怎样转成模板变量;这些 version 和 claim 分别是什么含 5 处更新
Axon Go 回读与 Harness 中间结果
下面只展示接口的已知字段,值为教学数据。tables 的内部结构由 Axon 解释,本仓类型为 unknown[],这里不虚构一套固定列结构。
{
"diary_found": true,
"summaries": [{"data": "用户曾向艾琳借铜钥匙,后来归还。", "diary_id": "diary-example"}],
"merged_summary": "用户曾向艾琳借铜钥匙,后来归还。",
"table_found": true,
"table_version": 7,
"table_prompt": "铜钥匙:持有人艾琳;归还已完成。"
}
Harness 把非空文字转换成 items 和 externalSetvars,例如:
{
"version": "axon:request-example",
"items": [{"id":"configured-diary-source","source":"compassMemory","content":"用户曾向艾琳借铜钥匙,后来归还。"}],
"externalSetvars": ["{{setvar::compassMemory::用户曾向艾琳借铜钥匙,后来归还。}}"],
"sourceTraces": [{"id":"configured-diary-source","variable":"compassMemory","recalled":true,"byteLength":48,"rendered":false}]
}
上例省略表格对应的 item/宏;byteLength 是 UTF-8 字节数,不是 token 预算。version=axon:请求ID 是这次召回快照标签,不是表格存储版本,也不是第几轮日记。是否有表格、原始 tables 和 table_version 单独留在 AxonMemoryRuntime 内部;真正用于表格并发检查的是后者。
Personalization 宏与 Hinos 协议
Personalization 的 beforeChat 返回对象可含 setvars 字符串数组,例如同一个 {{setvar::compassMemory::...}}。来源配置指出取哪个变量;同一 Agent 返回多次同名宏时,本地提取按最后匹配值。它的 version=hooks:请求ID 同样不是底层数据库保存版本。
Hinos prepare 接口需要以下协议结构;数值与内容是教学示例:
{
"schema": "hinos.external_memory.prepare.v1",
"claim_id": "claim-example",
"memory": "铜钥匙已归还艾琳;明早北塔之约仍未完成。",
"turn": 21,
"state_through_round": 20
}
后续提交不是把整个 prepare 回包送给模型或照写进 Actor 消息,而是向 commit 发 claim_id、user、assistant。响应须为 schema=hinos.external_memory.commit.v1 且 committed=true。本地还检查提交 requestId/input 与 prepare 一致。turn 与 state_through_round 通过类型校验,但不能替代服务内部状态正确性的验证。
冻结记忆试跑的实际边界
FrozenMemoryRuntime.recall 复制请求构造的快照,version 为 frozen:请求ID;ingest/consolidate 只检查取消,不执行持久化。ChatKernelRPRuntime 先确认固定变量确实出现在 compiled blocks,随后向外部 /v1/chat/completions 传 memoryVariables 及 harnessFoundationContext/harnessTurnContext,明确 includeDefaultAgents=false;它还检查 debug.setvarKeys 是否含要求的变量。这个检查证明接口按约定接收了变量,不证明模型正确采用或上游数据库保存。接口本身要求 service token;未开启入口或缺地址时不会作为普通RP默认流程执行。
依据:请求固定资料与空写入[45]、编译内容、变量与上游回执[46]、字段校验[47]、受开关保护的入口[48]。
没准备好或写入失败
本次新增当前完整聊天方案的默认值仍是 failurePolicy.memoryRecall=fail_turn:记忆服务读取失败,会让本轮正文准备失败。研发现在可以在该场景的 AGENT_ROUTER_SCENARIOS_JSON 配置里明确改成 continue_without_memory。例如日记服务暂时连不上,程序记录 memory.recall_failed 和降级状态,然后用空的本轮召回结果继续生成;角色和聊天仍按原接线准备,但模型这一轮确实少了那份记忆。未填写、空配置仍严格失败,拼错字段或填其他值会被配置校验拒绝。成功读到空内容不算故障,也不会被记为降级。
本次新增Hinos 要先等角色材料渲染完,才调用 /v1/memory/prepare,所以它的错误可能晚于最初 recall。当前代码把这类延后错误也记入本轮,但只让连接/读取超时、响应传输失败、HTTP 429 和 5xx 使用上述容错。地址不合法、401/403 及其他 4xx、成功回包却不是合法 JSON/协议、缺少角色来源、真实对话不以当前用户结束,仍然失败。整轮取消、deadline 到期、Actor 失败或 Axon 渲染失败也不被吞掉。
本次新增Hinos 降级时复用已经完成的角色渲染,不重复执行 Axon 与 hooks;本轮清掉旧 claim 和 Memory 来源标记。回复完成后,程序先验证本轮请求与输入身份,因为没有有效 claim,便不向 Hinos commit。**正常 prepare 成功但 memory 为空则不同:它仍有 claim,回复成功后仍需 commit。**下一轮服务恢复可重新取得 claim。
本次更新普通日记/Personalization 不能套用“没有 Hinos claim 就不写”的规则。Actor 成功后仍尝试原有 ingest;应用内回复后写入策略 memoryIngest=best_effort 保持原默认,它不是本次新增的 Scenario failurePolicy JSON 字段,写入失败不撤回已完成正文。Hinos 仍需地址及恰好一个 hinosMemory 来源,默认服务超时 10 秒;Personalization Agent 不 live 会跳过。普通 afterChat 返回信息不会被这份适配器用来改写已生成正文。
本次新增以上策略已随 #301 合入主线;本轮没有读正式 Emochi 场景的有效配置,不能写成全部产品已默认容错。配置选择[49] · 请求采用[50] · 普通召回与事件[51] · Hinos 分类与 claim[52]
依据:来源配置和装配[53]、Go 回包与变量转换[54]、memory.recall真实字段[55]、Personalization完整前后链[56]、Hinos prepare和commit[57]、Hinos再次渲染[58]、动态hook选择与变量准备[59]、hook载荷与live条件[60]、上游准备入口责任[61]。
日记:把一段经历整理后,留给以后取用
**日记保留的是“发生过怎样一段互动”。**例如聊天已经保存了借钥匙、到北塔、归还钥匙这一段经历,摘要模型可能整理为:
用户曾向艾琳借铜钥匙前往北塔,后来归还;两人仍约定明早继续找人。
以下具体过程对应仓库中由 Harness 编排的日记接法(代码名 axon_go)。其他外部服务接法不能直接套用同一套触发规则。
- **什么时候开始检查:**一轮回复成功进入完成处理后,程序安排日记后台任务。任务还会检查配置、用户额度、生成间隔、冷却以及是否已有任务占用;满足这些条件后,再向后端取得本次生成计划。不是每回复一句都写一篇日记。
- **交给摘要模型什么:**取得允许生成的计划后,程序重新读取后端已保存的聊天历史,按计划准备本次要总结的内容。它没有直接把刚生成的全文塞进历史;如果聊天服务尚未保存这条回复,日记这一趟未必包含它。
- **模型输出什么:**生成结果需要被解析。用于后续取回的摘要是一项产物;用户可能看到的日记标题、正文和独白是另一组产物,是否保存由生成计划决定。因此“摘要更新了”不一定意味着“新增了一张日记卡”。
- **保存在哪里:**程序通过 Axon 服务提交摘要与计划要求的日记内容,并处理相应缓存。模型生成成功后还要保存成功,才能作为以后取回的资料。
- **以后怎么用:**后续回复前,启用了日记来源的请求会向服务取回摘要,交给回复提示词模板。模板实际引用这段内容,回复模型才会看见;保存后不保证每轮都返回同一篇或全部日记。
这条回读请求携带用户、会话、所需来源和条数限制,没有把本轮“铜钥匙”这句话作为搜索问题传给服务。因此这里不能描述成“模型一提铜钥匙,系统就自动语义搜索所有相关日记”。服务内部如何选取内容,要看对应后端,不能从这两个仓库推定。
**用于回读的摘要,与可供用户打开的日记卡不是同一字段。**模型响应经外部 memory.diary.parse 返回 success/title/content/monologue/summary 等结果;只有解析成功才继续。程序调用 memory.diary.append 时,按计划决定是否带标题、正文、独白,而 summary 若存在则单独提交。合并摘要还可能写入按用户/会话/Agent引用定位的缓存。下一次 memory.recall 给 Actor 准备的是 merged_summary,例如“用户借钥匙后归还,两人约好明早去北塔”;不是默认把整篇日记、所有卡片或过去全部消息取回来。
这份摘要通过 compassMemory 进入所用模板,仍受预算影响。下一句若在日记任务完成前已读过旧摘要,就沿用那次读到的内容,不会中途换成刚生成的新日记。后端摘要如何排序、来自缓存还是其他存储以及底层数据库,两个仓库没有完整实现可供确认。
轮数怎样计、用户额度怎样影响触发、模型具体读哪些聊天,以及成功后先写哪项记录,见日记完整执行规则。
开发核对:日记触发、额度、模型输入和保存边界
下表都是固定版本的缺省值/分支规则;有效 Agent 参数、请求策略、订阅和实验配置会影响结果,不能宣布线上统一采用这些数字。
| 字段或条件 | 代码中的含义与缺省值 |
|---|---|
| 日记来源 | 配置来源变量 compassMemory;相应 Agent 引用还用于取得生成配置和摘要缓存 |
| 生成配置位置 | 从该 Agent 工作流的 generate_and_save_diary 节点取参数 |
最小轮数 minRounds |
缺省 20,可按订阅配置覆盖;不是普通 Agent V2 后台每隔 20 轮运行 |
免费路径间隔 freeRoundsPerDiary |
缺省 10;仍须结合策略和服务返回的生成计划 |
| 免费 Memory V2 首次/后续间隔 | 配置了相应策略字段才进入此路径;兜底首次 20、后续 10,首次之后默认不保存日记正文 |
| 用户是否允许生成 | 结合请求策略、Agent 参数、订阅及实验。plus/ultra/lite/max 的付费判断会影响 enabled,不能把单一请求开关当成所有订阅的总开关 |
| 轮数从哪里来 | 优先用已有准备结果;否则查询会话消息数并向下取整除以 2,查询失败按 0 |
| 免费数量 | 传给 plan 的实际额度来自 memoryFree 实验,未启用时为 1;不能把另一个解析参数的缺省 3 当成统一免费数量 |
| 生成锁 | 默认开启,TTL 120 秒;还会检查额度冷却,避免并发或短期重复失败 |
| 最终是否生成 | 请求 memory.diary.plan,返回 should_generate 才调用摘要模型;should_save_diary 单独决定是否存标题、正文、独白 |
| 取历史范围 | 最多 500 条;优先取配置的 fetchMessageLimit,否则按计划中的历史轮数乘以 2 |
| 摘要模型 | 可由实验及免费/付费配置指定;代码兜底 ID 是 cheni-dairy-qwen-4b,不代表当前线上实际模型 |
| 单次模型超时 | 缺省 60 秒;免费 vanilla 路径外层最多 3 次生成/解析尝试,其余外层 1 次,底层模型重试另算 |
合并摘要 mergeSummaryThreshold |
缺省 1;取旧摘要和新摘要最后 N 份拼接,并非再调用模型总结 |
| 摘要缓存 | 写入 30 天 TTL;不能把缓存有效期等同于全部日记原文的永久保存期限 |
| 回复前返回条数上限 | plus 2、ultra 3、max 5,其余 1,包括 lite;这是回读的摘要数量上限,不是生成间隔 |
通常以已保存 history 加“summary”任务调用摘要模型;部分免费路径把历史放在 question,模型 history 留空。专用摘要调用使用空角色 promptId。结果交给 memory.diary.parse,再按计划提交;某些限额或认证错误会触发额度冷却。免费卡片额度耗尽时,也可能发送广告卡后跳过生成,不能据“用户看到一张卡”判断生成了摘要。
这份实现显式检查了 parseDiary 的 success,但 appendDiary 回包的 success 没有再次判断,后续主要取 diary_id;cache.put 的成功字段也没有另行判定。因此 memory_diary_ingest_completed 的 generated 日志说明本地编排走完,不独立证明所有外部保存均已验证。应结合服务回执、记录与再次回读确认,尤其不能把一条日志当成摘要、卡片、缓存同时成功。
写日记、更新生成计数、写缓存和推送卡片是顺序操作,本段代码没有证明它们组成一个整体事务。后一步失败,不代表前一步自动回滚;调用日志也不能替代逐项落库验证。日记没有等待本轮助手消息保存完成的屏障,使用的是调用时存储服务实际返回的历史。
依据:日记任务与生成计划[62]、模型、解析和保存[63]、策略与订阅[64]、回读上限与后台任务[65]、Axon 日记接口[66]。
按字段维护记录:记忆表和 JSON 工具分别怎样写
**记忆表是一条已经在应用中编排的流程;JSON 记忆工具是让接入业务自己定义内容和采用规则的可复用能力。**两者都能保留字段,但输入格式、存储范围、调用者和后续读取者不同。
记忆表:从回复里解析修改,再写回记录
**记忆表保留的是“某项记录现在是什么”。**假设所用表格有物品记录,变化可以表示成:
| 物品 | 修改前 | 本次希望保存的结果 |
|---|---|---|
| 铜钥匙 | 持有人:用户;归还:未完成 | 持有人:艾琳;归还:已完成 |
列名是业务示例,不是所有场景内置的固定字段。当前 Axon Go 路径按以下步骤工作:
- **回复前拿旧表。**程序取回表格内容和版本;文字交给回复模板,版本由程序留着,供写入时判断这张表有没有被别的任务改过。
- **回复模型产生修改内容。**如果接入使用的提示词让模型按表格约定输出修改,模型原始输出里才可能有可解析的编辑。用户看到的“钥匙已归还”一句普通正文,并不等于已经产生了有效表格编辑。
- **回复后解析。**程序把旧表和模型原始输出交给 Axon 的表格解析接口。接口返回改动列表和改后的表;没有解析出改动,就结束本次更新。这里不是另请一位后台专家重新分析整段聊天。
- **按版本保存。**程序提交改后的表;原先已有表时,会带上读取时的版本,首次创建没有旧版本可带。如果发现有人先改过,会重读最新表,再应用同一份修改,重试一次;仍失败就没有本次新表已保存的保证。
- **下一次取回新表。**之后的请求仍需启用表格来源,并在回复模板里使用它,模型才能读到“持有人:艾琳”。普通后台专家不会因为表格已写入,就自动获得这张表。
表格更新在这条已接线的路径中可由后台任务执行;用户看到正文时,它可能还没写完。**决定是否更新的是有没有有效编辑,决定能否影响下次回复的是保存与再次带入是否成功。**表格编辑的具体语法与解析实现归外部 Axon 服务,这里不把口语例子伪装成一个已验证可直接提交的格式。
**表格服务回给模型的是表格提示文字,写入时用的却是结构化原表。**例如回读有 table_prompt="铜钥匙:持有人艾琳;明早约定保留"、table_version=8,Actor 通过 memoryTable 看这段提示;程序把 tables 与版本留在请求内。回复后,apply_edits 返回 tables/changes/extracted_content/clean_response;真正用来替换存储的是改后的 tables,是否值得写由 changes 是否为空判断。这里不能把上述中文示例直接当作服务认可的编辑语法。
表格通过 memory.table.replace 按用户和会话保存,已有表带 expected_version;回执返回新 version。表格版本与普通 Agentic 状态版本分别计数。解析回包的 clean_response 在该路径用于可选训练样本,不负责把已经展示的正文再改一遍;若还有文本清理,要看角色模板及输出处理。
自定义 JSON 记忆:宿主定义字段,工具读写完整对象
假设业务要维护这份记录:
{
"keyHolder": "用户",
"nextMeeting": "明早北塔"
}
接入方先绑定存储范围,再把 get_memory、update_memory 注册给需要它们的执行者。读取工具返回完整对象与版本号;更新工具接收读取时的版本和完整的新对象。工具校验 JSON 与版本;如果宿主另设业务校验,也需先通过,再保存并返回新版本。
要把持有人改为“艾琳”并保留约定,就要提交两个字段都在的新对象。只提交 keyHolder,原来的 nextMeeting 会被删除;它不是自动合并局部修改的接口。
下次由业务再调用读取工具,并明确把结果放进哪个模型的输入,才会发挥作用。工具本身不调用模型,也不会自动把全部 JSON 投给 RP 回复模型。这组能力已从工具包导出,并有隔离调试示例;它的存在不表示普通 RP 已把它注册为默认记忆工具,也不是向世界书新增条目的接口。
例如宿主已注册 JSON 记忆工具,一次完整读改可以这样理解。字段为业务自定义,版本为教学值:
{"revision":7,"memory":{"keyHolder":"用户","nextMeeting":"明早北塔"}}
更新调用要提交:
{"expectedRevision":7,"memory":{"keyHolder":"艾琳","nextMeeting":"明早北塔"}}
成功回包只有新版本:
{"revision":8}
其中工具同时给调用模型一份 JSON 文本和结构化 details;缺少记录时读取返回 memory=null, revision=0。接入若使用仓内 AxonJsonMemoryStore,按认证用户、会话、namespace 和 key 构造独立保存范围,不能由模型随便在参数里改用户身份。下次显式读取并被调用者采用,才会接着使用这些字段。
两套写入协议分别核对:Actor 输出怎样被解析成表格修改 · JSON 完整替换、版本与存储范围。
开发核对:表格解析与版本重试、JSON 完整替换及存储范围
Axon Go 记忆表:模型输出怎样变成新表
回复前拿到 table_prompt、tables 和 table_version。table_prompt 变成供模板使用的 memoryTable;结构和版本不直接作为普通后台专家输入。
回复成功后,把 rawOutput(没有时才用最终 output)与旧 tables 交给 memory.table.apply_edits;该外部接口返回新表、改动列表、提取的修改内容和清理后的正文。changes 为空就不写。否则调用 memory.table.replace:已有表时带 expectedVersion,新建时不带。第一次版本冲突后重读,再对最新表应用同一份处理前文本;最多两次尝试,不让 Actor 重写一遍。
**用户看到的改写稿,不会自动成为表格重算依据。**这里的 rawOutput 来自 Actor 的 rawText:已经做过助手后缀防泄露处理,但还不是正则和 after-chat 改写后的最终交付稿。假设一个同时接入 Axon Go 表格与正文改写的方案里,Actor 生成“守卫接过钥匙”,并附有服务能解析的“钥匙持有人改为守卫”的表格编辑;后置处理却把最终正文改成“守卫没有接钥匙”。Harness 仍把前一份 rawOutput 交给表格解析,不会因为展示句子变了,就自动撤销或重做那份编辑。本例说明接线可能出现的材料分歧,不是一次生产事故记录;表格还要按实际编辑、版本与保存结果判断是否更新。调用方需要明确正文改写是否允许改变事实,以及相应表格应采用哪份文本;不能仅看聊天里的最终一句来推断表内值。
从模型产物到用户正文、再到记忆的完整分流见第4章:实际交付链,字段和后处理顺序见精确合同。如果用户随后编辑旧聊天,哪份历史和普通持续状态会改变,另见编辑、重生成与分支的实际影响;这里的表格处理不会因此自动成为通用历史回滚。依据:最终正文与处理前文本分别传入记忆[67]、表格优先读取 rawOutput[68]、Actor 后处理与 rawText 返回[69]。
若表格蒸馏开关开启,程序在表格保存成功之后才构造并上传训练样本;解析结果里的 clean_response 用于样本,没有覆写已交付正文。当前 main 43332d8 的日志把这两步包在一起:memory.table.replace 已成功,但样本构造或上传随后抛错时,只会留下 memory_write_started → memory_write_failed,不会有 memory_write_completed。因此看到 failed 要先读取表格及版本,不能当成“表格没写入”直接重做。巡检的隔离复现确认过这条部分成功分支,没有声明线上已发生事故。保存、提炼与日志顺序[70]
JSON 工具:完整对象更新,不是局部补丁
get_memory 不接受业务参数,由宿主事先绑定存储范围;缺少记录时返回 memory=null、revision=0。update_memory 必须提交 expectedRevision 与完整 memory 对象,完整对象序列化后的 JSON 限制为 64 KiB。更新先通过参数及 JSON 检查;宿主设置了 beforeUpdate 才额外执行业务校验。随后进行版本比较,冲突则拒绝,成功返回新版本 revision=expectedRevision+1;工具标记不可自动重放,不能对失败含糊的写入任意重复执行。
宿主可用任意实现了读取和比较更新的存储。仓内 Axon 适配器把已认证用户、会话、namespace 和 key 组合成独立作用域;不是复用 Director 的栏目文本或 Visual World 记录。工具不决定 JSON 字段的业务含义,也不替接入方选择何时调用、怎样把结果给模型。工具包公开导出这项能力;调试宿主中的内存存储示例只证明隔离调试可用,不是普通聊天已经开启这项存储的证据。
依据:读写参数与可选业务校验[73]、JSON 数据限制[74]、存储接口[75]、Axon 存储范围[76]、调试示例[77]、SDK 接入示例[78]。
历史压缩:旧聊天太长,本轮怎样装得下
若想先确认“窗口能否改、谁决定历史长度”,从上下文容量与参数进入。Compact 读取旧聊天和上次保存的摘要,把早期完整对话整理得更短,再与近期原文一起交给回复模型。它不改聊天原件,也不写日记或记忆表。现在有同步和显式开启的后台两种时序。
例如旧聊天里有“借铜钥匙、承诺归还、约好明早去北塔”,用户本轮说“我已经还了钥匙”。压缩模型处理的是此前已完成的对话,本轮新输入仍单独保留。程序会检查摘要格式、覆盖的消息和最终输入长度;只有通过检查的结果才可使用。
| 何时执行 | 这一轮 Actor 用什么 | 什么时候保存,下一轮拿到什么 |
|---|---|---|
| 默认同步;或需要立即解决硬超限/紧急推进旧摘要的消息锚点 | 等压缩完成,使用新摘要+保留原文+本句 | 回复前尝试一次版本检查写入;下一轮重新读取并验证这个检查点。保存失败时,本轮仍可能用临时摘要 |
显式 compact.scheduling=async_preferred,输入仍装得下,达到提前压缩条件 |
当前已有摘要和历史;不会在输出一半时换成新摘要 | 后台根据固定的完整输入生成并提交。后续请求读到成功保存的新检查点才采用;来得太快可能仍读到旧版 |
后台模式另开 asyncOverflowPolicy=trim_history,当前已经超限,且任务与临时裁剪均通过检查 |
暂时少带一些较早完整对话,保留已有摘要和近期材料 | 后台仍使用完整来源;当前省略的原文不等于已经被记住。若没有获准的新任务或同快照任务承接,回到同步处理 |
当输入仍装得下,后台无空位、已有同链任务或材料不满足准入条件时,程序记录原因,继续使用当前输入,不会因此额外同步调用压缩模型。每条用户/会话/场景记忆链最多一个后台任务,每个应用实例最多四个,不排队。任务独立于前台的普通结束/取消;配置、检查点版本变化或后台总时限会终止它。后台稍后失败,不会把已经交付的回复重新同步执行。
检查点保存的是摘要、覆盖到哪条消息、配置与历史指纹、版本和用量。启动了任务、模型写完了摘要、版本写入成功,是三个不同结果。普通 Agent V2 的 contextGovernance=enforce 采用本次最终摘要与保留历史,shadow 保留原后台历史作比较;通用 SDK Agent 不会自动读取这一应用检查点。
Compact 只能处理上游交来的历史与可验证的旧摘要;它不自行找回全部聊天。无法建立连续覆盖、模型失败或预算用尽时,仍可能舍去旧历史或拒绝生成。短窗口边界、参数、保存与复用、后台准入及角色卡兜底在本节继续展开。
本次新增日记更新了,旧摘要是否还有效
本次新增日记和 Compact 摘要记录的是不同资料。以前,日记替换角色开场内容后,程序可能把“日记 A 变成 B”误认成“作者改了角色”,让已经保存的压缩摘要失效。#302 把这两件事分开:判断旧摘要能否复用时,使用作者原开场或明确覆盖的开场;生成这一轮回复、进行新的压缩时,仍使用最新日记。日记内容变化或暂时读不到,不再单独导致旧摘要作废;真正修改角色背景、作者开场、压缩配置或已覆盖历史,仍要重新校验。
本次新增程序若尚未核实角色资料的来源,就不采用、不作废、不覆盖旧检查点,也不启动后台压缩。来源恢复后,旧记录仍可以重新验证。即使临时生成了一份摘要,canPersist=false 时也不能说它已经保存。
本次新增后台任务还有另一层检查:任务冻结的是当时真实的全部角色输入。日记 B 到来后,不能因为持久摘要身份不变,就把使用日记 A 的未完成后台任务当成同一份输入复用。trim_history 需要的完整快照不匹配时,会回到同步恢复并使用新日记。
日记覆盖顺序与字段依据含 2 处更新
本次新增Compact 启用时,适配器只在这次 Axon buildSetVars 调用里临时传 enableSummary:false,取得日记替换前的开场,再在本地恢复原覆盖规则:用户未关 summary、没有显式 extra welcome、日记按同一空白规则处理后非空,才替换实际 roleCard.welcome。显式空 welcome 也算明确覆盖;不修改共享请求的开关。checkpointWelcome 保留摘要兼容性所需的作者来源,实际 roleCard.welcome 保留本次生成内容;旧调用者没传新字段时沿用旧指纹算法。后台 snapshot fingerprint 另含完整 input.roleCard。原有模板/Actor/Memory/来源 hooks 的覆盖顺序、Actor 最终预算与 CAS 条件都仍生效。
本次新增取得与恢复日记覆盖[81] · 分开传递开场身份和实际输入[82] · 摘要身份[83] · 来源未核实的保护[84] · 后台实际输入指纹[85]
开发核对:压缩模型、摘要结构、预算、保存与失败含 1 处更新
压缩模型实际拿到什么,产出什么
每次启用 Compact 的准备,先解析配置并读 checkpoint,即便此次历史很短也要读取。读取接口返回 record_found/active_found/revision/status/lineage/checkpoint。checkpoint 内有 source 指纹与消息 ID、coverage 首末消息/末对话组及覆盖数量、summary 和用量审计。模型不会直接拿数据库记录全文;Harness 验证后才把摘要投放给本轮模型。
当前执行策略由 Scenario 的 compact 配置决定;ModelConfig 提供模型、上下文上限、参数和 PromptManager。profile 默认 generic-json-v1,或显式选 configurable-v2。当前代码不再从 ModelConfig 的 feature_config.roleplay_compact 选择执行协议,也不按模型名自动选择旧 auto-memory-v0-v1。旧版本曾兼容宽松 auto-memory JSON;它不能继续当作当前主干的可配置 profile。
| 本次压缩采用什么输入 | 模型真正看到的内容 | 不应误解成什么 |
|---|---|---|
generic-json-v1,或 configurable-v2 + harness_json_v1 |
JSON 中的 role_card.character_name/scenario、可选 previous_compaction、待压历史 canonical_history(role/message_id/content)、upcoming_query |
不是整张角色卡、日记、表格和世界书的统一打包 |
configurable-v2 + dream_text_v0 |
user 模板中的角色背景、可选旧摘要、按 user:/assistant: 排列的旧聊天;没有旧摘要时可带 welcome;模板另含当前 query |
背景由 Actor 模板变量的 systemPrompt、personality 或 initPrompt、scenario、summary 去重组装,并移除 user-persona 标签;不等于所有资料原样注入 |
configurable-v2 + automemory_recursive_v1 |
首段由角色背景起头;已有摘要时以此前压缩记忆起头,再加本段完整对话组。每段的 query 优先用这段之后紧接的 user 内容,末段才回落到本轮 query | 是按顺序滚动摘要,不是多个摘要模型随意并行。上一段输出作为下一段输入;中间摘要不单独保存 |
文本输入需要 PromptManager 中明确的 roleplay_compact system 模板和唯一的 roleplay_compact_input user 模板。支持变量 compact.history、compact.recent_keep、compact.user_query、compact.max_summary_tokens;当前 recent_keep 传空字符串,不能据变量名推定它已收到全部保留原文。user 模板必须各包含一次 history 和 user_query;system 只允许 max_summary_tokens 变量。模板源只渲染一次,用户/模型正文里出现同名宏不会再执行。harness_json_v1 不接自定义 Compact user 模板。纯文本输出也必须有明确 system Prompt,不能同时强制 JSON response_format。
| 输出方式 | 模型输出例子 | Harness 怎样放进 Actor;怎样保存 |
|---|---|---|
structured_json(默认兼容 profile 也用此结构) |
{"canonical":"用户曾向艾琳借铜钥匙。","interaction":"承诺用完归还。","open_threads":["明早一起去北塔"]} |
三段摘要包装为 <context_compaction>,作为独立 system 消息插在历史前;持久化同样的三字段结构 |
plain_text |
用户曾向艾琳借铜钥匙并承诺归还;明早的北塔之约仍待进行。 |
未声明新摘要位置的旧 preset 仍用 <compressed_history> 注入 user 历史;声明了下述 compactMemory 的 preset 则在它指定的 system 位置渲染。保存时正文仍落在 summary.canonical,interaction 为空、open_threads 为空,并以 compactor_version 区分协议;运行时解码为 {format:"plain_text",text:…} |
结构摘要只接受 canonical、interaction 字符串和 open_threads 字符串数组;canonical 必须非空,interaction 可空,不接受额外字段。两种输出都要检查大小、token 和 Actor 重新装配后的预算。日记/表格若已进入 Actor 模板,同样占窗口,但压缩不会顺手改它们。
依据:Scenario 协议校验与配置解析[86]、模型与模板要求[87]、JSON 输入[88]、文本协议、角色背景与模板[89]、摘要放入 Actor 的位置[90]。
谁控制触发、保留范围和调用预算
触发有两个方向:输入超过预算比例;旧检查点覆盖的末条消息已逼近本次历史窗口起点,需要在它滑出前推进。仍须存在可以压缩的完整旧对话组。可用输入预算是 Actor 上下文上限 − 本轮预留输出 token − 安全余量,触发线再乘 triggerRatio 并向下取整。
| Scenario.compact 参数 | 控制什么 | 当前仓库示例,非全局默认 |
|---|---|---|
boundaryMode |
selected_turns 由 user 开组,有 assistant 回复才成完整组;explicit_groups 使用接入方连续分组标识 |
native v0/v1 都是 selected_turns |
compactorModelConfigId |
选择独立压缩模型及 PromptManager | 两个 native 示例分别引用 AutoMemory v0/v1 Native |
profile/inputProtocol/outputFormat/lengthPolicy |
压缩输入协议、输出形态与输出截断政策 | native 为 configurable-v2、纯文本、accept_bounded;v0 用 dream_text_v0,v1 用 automemory_recursive_v1 |
triggerRatio |
触发比例,大于0小于1 | native 为0.8 |
keepLastCanonicalGroups |
保留近期完整组,非调用间隔;兼容 profile 至少1组,configurable-v2允许0 | native 保留2组;旧 preset 示例保留6组 |
safetyMarginTokens/maxSummaryTokens |
安全余量和摘要输出上限;还受压缩模型剩余容量限制 | native 安全余量512;v0摘要700 token,v1摘要1600 token |
reliability |
限制候选尝试、实际模型调用和压缩总时长;configurable-v2 或 bounded_recent 必须明确提供 | native:至少256 token生成空间、最多24次候选预检、2次模型调用、120000ms |
recursive.segmentContentTokens |
递归每段正文容量,按闭合组切分;只适用于 automemory_recursive_v1 | v1 为16000;不等于模型完整输入窗口 |
executionPolicy=bounded_recent |
先规划可承受的连续近期覆盖范围,再花模型调用;必要时重建覆盖,记录舍弃数量 | 两个 native 示例开启 |
boundarySearch |
binary/measured/cumulative;未填沿用 binary,显式设置要求 bounded_recent;只改变怎样寻找候选边界 |
#207 已加入 cumulative,现有 config/deploy 未配置;完整预算及保存检查仍保留 |
scheduling |
默认同步;async_preferred 提前后台整理,必须有 reliability.maxCompactionMs 总时限 |
显式启用;不证明生产已采用 |
asyncOverflowPolicy |
后台模式硬超限默认同步;trim_history 允许在后台完整来源得到承接后临时少带旧历史 |
不能独立于后台模式使用 |
rolePromptFallback |
角色定义本身过长时,给出 modelConfigId、timeoutMs、maxOutputTokens 尝试请求内压短 |
显式配置;共用总时长、调用和候选额度 |
checkpointMutationTimeoutMs |
检查点变更独立等待窗口,1000—10000ms;明确设置后,保存超时可只读确认一次 | native 为5000ms;未设置沿用2000ms兼容路径 |
bounded_recent 会用实际输入计数、预计摘要空间、可用模型调用数与完整组边界,规划本次能压的连续近期范围;若全量候选放不下,可能舍弃未覆盖的更早组,诊断会记录。它不是扩大模型窗口,也不是保证把所有旧消息都保存成摘要。递归按段顺序执行,每段继承上一段摘要;每次尝试与模型调用都累计入同一预算。只有最终摘要通过 Actor 整体预算后,才进入一次最终 checkpoint 保存,中间段不会逐段落库。
字节限制仍分别是 canonical 24 KiB、interaction 8 KiB、open_threads 最多64项且每项1 KiB、整体 checkpoint 64 KiB。纯文本借 canonical 字段存放,也受该边界。字节、token、字符不同;普通 Agent V2 的 maxStateChars 不能替代这些检查。
依据:顺序递归与完整组[91]、近期范围预规划[92]、native v0 配置[93]、native v1 配置[94]。这些配置进入仓库期望清单不代表当前生产已部署或运行过。
何时存、超时如何确认、下一次如何用
- 本次更新**先核验旧记录。**比较 Scenario、分组、角色材料、模型/Prompt/协议/策略等语义指纹;角色开场身份与实际日记输入按上面的 #302 规则分开,日记变化本身不再作废摘要。覆盖首末消息都在当前窗口时比覆盖数量及整段历史哈希;首消息已滑出而末消息仍在时可以复用,不会重新读回窗口外原文。因此上游保持消息 ID 修改窗口外旧内容,不能保证本次马上识别。未知 checkpoint 格式不渲染、不覆盖;配置未核实或读取失败也限制复用和写入。
- **构造新的可用输入。**新摘要经过格式、大小、输出 token 以及最终 Actor 输入计数;成功才采用。递归必须走到最终结果。并非压缩模型返回文字就直接存。
- **等待一次版本写入。**允许
chat/continue/auto_reply的共享记录修改、源消息 ID 稳定且 checkpoint 允许持久化,才通过roleplay.context_compaction.compare_and_set按用户/会话/Scenario 保存。仅复用、重生成等只读分支、临时消息 ID 都不会产生这一写入。冲突不重试覆盖。 - **处理保存超时。**明确设置 checkpointMutationTimeoutMs 后,invalidate 与 save 可使用各自时间窗。已发出 save 且非冲突超时,会发起一次最多2000ms的只读确认:比较 expected revision+1、lineage 和完整提交载荷(仅排除服务生成的审计字段)。完全匹配标记
confirmed_after_timeout,不同或读不到则保留对应诊断;不自动再次写入。请求取消不会进入这项确认。 - **下一轮重新读。**只有读到仍有效的记录才复用;本轮临时采用与成功保存是两个结果。正文生成后来失败,也不回滚此前已保存的压缩检查点,因为它压缩的是此前已有历史。
**当前短窗口边界:不能无条件承诺“丢锚点会自动恢复”。**旧摘要覆盖末消息不在当前有限历史时,允许写入的请求先让旧 checkpoint 失效;如果当前窗口过短,没有达到新压缩触发条件,或没有足够的完整组可重建,就可能出现旧摘要已 inactive、没有新摘要接替。已有“大窗口可重建”和“锚点仍在短窗口可复用”测试不能覆盖这组组合条件。这是固定源码审阅发现的边界,不是已证实的线上事故。接入需要让历史窗口与压缩覆盖衔接,并检查 checkpointReason、adoption 和 persistence,不能只看回复成功。
普通 Agent V2 的 contextGovernance=enforce 先把轮初 Agent 状态计入不可压缩材料,后台再采用 retainedHistory 加 compactSummary 或 compactSummaryText;shadow 仍用原历史。保存 Agent V2 state/ledger 的接口另算,没有有效且变化的 Director 状态时不在那条路径单独存专家记录。普通状态保存的初次加两次重试和含糊结果核对,不是 Compact 的写入规则。
内容过滤 finishReason=content_filter 直接拒绝,即使输出看起来完整。configurable-v2 的 lengthPolicy 默认 reject;accept_bounded 仅允许纯文本,并仍检查非空、大小、输出 token 和最终 Actor 预算,不保证截断文本语义完整。兼容 generic-json-v1 保留旧行为:length 回包仅在 JSON 完整且所有检查通过时可用。工具调用、非法结构或输出超限都不接受。配置错误与取消会中断;其他可降级故障可能保留有效旧摘要、原材料或缩短历史,不能泛化成所有错误都继续生成。
诊断区分 candidateAttempts/prechecks/modelCalls、discardedUncoveredGroups、adoption、persistence、检查点变更耗时与确认结果;compacted 只表示本轮采用新摘要,historyWindowSlid 也可能是复用旧摘要或降级舍组。查看本轮最终材料和存储回执,才能判断“这次用了什么”和“下一次能读到什么”。
后台怎样获准,超限后又怎样尽量保住记忆
程序在 token 阈值或旧摘要的末消息即将滑出窗口时检查后台资格:配置能够验证、检查点允许保存、有消息 ID 稳定的完整旧对话组,而且宿主提供了独立的模板渲染器。任务复制历史、本句、实际 Actor 输入和模型配置;随后核对同一套配置与读取时的检查点版本,不在运行中偷偷换成另一轮材料。
| 当前情况 | 程序的处理 | 对这一轮的影响 |
|---|---|---|
| 输入仍在硬预算内,任务成功安排 | 后台执行原压缩协议和一次最终提交 | 当前直接回复,后来成功的摘要留给后续请求 |
| 输入仍在预算内,但没候选、缺身份/渲染器、实例满额或已有同链任务 | 记录 ineligible、capacity、inflight 等结果,不排队、不为此转同步 |
继续使用当前可用输入,不能声称本轮已安排新的摘要 |
已硬超限,没有开启 trim_history,或旧锚点必须紧急推进 |
取消同链旧后台任务,走同步压缩/恢复 | 先解决容量问题,再让 Actor 开始 |
已硬超限,开启 trim_history |
先试裁完整旧组并重新计数;只有新任务获准或同一完整快照任务仍有效才采用临时输入 | 准入、计数、容量或快照不匹配则回同步;不会用另一轮后台任务担保本轮被省掉的历史 |
bounded_recent 现在先给摘要留空间:用非空占位激活模板中的记忆位置,再预留 maxSummaryTokens。若不够,扩大需要总结的连续闭合历史前缀。真实摘要生成后如果仍放不下,程序先把这份成功摘要与更多连续旧组一起继续总结,重新计数通过才保存。不能只删原文就把它记成已经总结。没有额外完整组、已用接替模型或剩余额度不足时,仍可能进入有损恢复;后台不允许通过丢失未总结内容重新建立覆盖。
角色卡本身已占满窗口时,显式配置的 rolePromptFallback 才会作为最后兜底。程序先证明要修改的位置就是实际 Actor 系统提示词中的角色定义;模型可压短 initPrompt、独立的 personality/scenario,多字段按严格 JSON 分别返回原位置,明确识别的系统规则和用户人设前缀保留。结果在宏渲染完成后替换,不执行新宏。再次计数确认更短且放得下才采用;只改变这一次调用,不改作者原角色卡、聊天或持久摘要。
动态/条件模板、字段或位置无法证明、模型失败、结果缺字段、取消或总预算不足时跳过或失败,不能保证任意长卡都能救回。该路径和正常摘要共用总时限、候选数与实际模型调用数。10/12 合入的 #295 修正了其中两处过早拒绝,具体条件如下;角色精简仍需显式启用,最终 Actor 的完整输入预算没有放宽。SDK 0.6.0 未重新发包,不能据包版本判断应用修复已经部署。
Jev 的 reduce_input_or_stages 现在依据完整压缩计划判断收益:过滤后能覆盖原来放不下的完整范围,或减少所需阶段,也可采用,不只比较一段 token 是否更短。已确认的正文计数会复用;真实输入仍需验证。查看诊断时分别检查最初、摘要后和恢复后的预算,以及摘要采用、版本写入、任务状态;取消不代表此前的工作和费用为零,已发起但结果未知的写入保留 unknown。
完整输入与准入[99] · 摘要预留与继续覆盖[100] · 真实摘要超限恢复[101] · 角色位置识别[102] · 多字段输出[103]。
角色设定太长:先尝试压短,再检查整份回复输入是否装得下
这项兜底仍由研发在所用 Scenario 的 compact.rolePromptFallback 中明确配置。程序优先处理旧历史;历史压缩或滑窗后仍超限,且能证明角色正文的位置和来源,才尝试精简角色。没有历史槽、但固定角色定义过长时也可尝试。成功后只替换本次请求中的角色文字,不改原角色卡,也不新写摘要检查点。
#295 解决的是“可以尝试,却被计数预检过早拦住”。例如原文太长时只能使用经过核验的本地计数,移除角色后又可以使用模型服务原生计数;以前只因两次来源不同就拒绝,现在分别核验每次计数,合格就可继续。程序还会对精简结果重新组装的完整 Actor 输入计数,必须同时满足“比原输入更小”和“不超过回复模型的输入预算”,才采用。
精简模型收到什么、三次计数、调用额度与失败条件含 1 处更新
| 检查位置 | 可接受的计数 | 不满足时发生什么 |
|---|---|---|
| 原始完整 Actor、暂时移除角色后的完整 Actor、放回精简角色后的完整 Actor | 三次分别可用原生计数,或元数据齐全且质量为 exact/compatible 的本地 Profile;允许来源切换 |
旧 token.count、未验证 Profile 或不完整证据不能批准角色兜底 |
| 角色精简模型自己的输入预检 | 此处单独允许元数据齐全且标为 not_validated 的本地估算;原质量标签保留 |
估算失败或“输入+输出上限+256”超过该模型窗口时,不调用角色模型 |
| 最终 Actor 请求 | 回到严格计数;输入 ≤ contextLimit − maxOutputTokens − safetyMarginTokens,且严格小于原输入 |
精简模型已经返回文字也不能放行,仍进入上下文超限失败路径 |
调用方配置 modelConfigId、timeoutMs(1–60,000)与 maxOutputTokens(1–8,192);模型来自 kaon-router、ID 和模型名有效,窗口须大于输出额度+256。就绪检查只取模型元数据和核配置,不生成角色。运行时还需有一次模型调用、至少两个候选计数的额度和剩余总时限。
程序先对移除角色后的完整 Actor 计数,确认角色确实能腾出空间。生成目标为配置上限与 (Actor 输入预算 − 去角色计数 −128) / 角色正文出现次数 向下取整后的较小值。该数字只是长度目标,不替代最终完整输入计数。
精简模型收到专用指令及被当作数据的原角色正文,不继承工具、停止串、Preset 或其他业务路由状态。输出为正文或要求的多字段 JSON。空输出、工具调用、截断/内容过滤、模型身份不符、非法或超限 usage、字段不合格都会拒绝。一次恢复只生成一次角色,不增加角色重试。取消与超时覆盖元数据、计数、生成,迟到结果不采用。
日志分别留下 originalCountSource、withoutRoleCountSource、finalCountSource 和角色预检证据;跨计数方法不能把前后差值包装成精确节省量,actorInputTokenDelta 仍仅在方法元数据一致时计算。通过 token 检查证明容量合格,不代表人物设定的含义无损。
本次更新#295 已合入 47fb054,代码也包含在 10/19 Sumi 成功部署的 f9b26a9 镜像内;但 Sumi 路径不因此变成 Emochi 的 Compact 流程,正式 Emochi 是否启用该选项仍未核。本次维护读取已有分审和固定源码,没有重跑产品测试或真实角色用例。
本次新增开发中的摘要检查:发现漏记或矛盾后,尝试重做一次
本次新增这项是 #305 未合入候选,不是当前 Compact 的默认能力。它在新摘要已经通过容量检查之后,额外询问判断模型:旧的重要事实是否保留、前后是否矛盾、摘要是否增加没有依据的事实。证据是旧摘要、此次覆盖区间的完整聊天原文、角色背景和新摘要;角色背景不能当成剧情已经发生的证明,文风不同也不算错。
本次新增off 默认不运行;shadow 只记录,即使发现问题也不改结果;repair 只有明确判出问题才从“旧摘要+完整新原文”重新生成一次,不把错误候选拿来润色。第一次判断不确定、服务不可用或证据太大,仍保留原候选的既有处理,不能描述成“摘要必须审过才能存”。真正发起重做后,新摘要要重新通过 Actor 预算且第二次检查明确 pass,才能采用;再次不确定或失败就拒绝这份修复,走已有失败恢复。
触发条件、次数与当前验证结果含 3 处更新
本次新增仅覆盖已有旧摘要的 incremental 阶段、最终主模型候选、没有 rebase 且预算已通过的情况;初始化和 fallback 输出不审。非 off 要求 bounded_recent + configurable-v2 + plain_text + reliability,repair 还须已配置 fallback Compactor。默认单次检查 5 秒、证据 80,000 字节、判断概率门槛 0.85;范围分别为 1–30,000 毫秒、1,024–100,000 字节、0.5–1。完整原文放不下就拒绝重做,不截短凑预算;最多一次重做、两次判断,共用既有总时限、调用和候选额度,后台在检查完成后才尝试 CAS。
本次新增截至 10/19 14:51,PR 为 Open/Changes requested,1 项 CI 显示通过但没有部署。作者报告 6 份重做、8 次复核全部 uncertain,0 次明确 pass;本轮未复现,因此没有已改善线上质量的证据。评审仍在处理:不配合取消的依赖可能不按 timeout 结束;Luna 实际双层 JSON 字节与预检口径不同;离线 telemetry 特殊键处理有缺口。文档矛盾是评审提出的另一项,巡检未完整独立定位,不能声称已解决。
本次新增检查配置[107] · 触发与采用[108] · 一次重做[109] · 作者离线结果[110] · PR 状态
让 Actor 的模板决定摘要放在哪
例如模板作者希望先放艾琳的人设,再放“用户承诺归还钥匙”,最后放文风要求。main 的 #218 允许作者在一个不受条件控制的 system 模板里写下唯一的摘要位置:
<compact_memory>
{{getvar::compactMemory}}
</compact_memory>
程序在每次实际渲染时把当前摘要填进去,转义其中的 &、<、>,并核对最终模型材料确实含这次的摘要块。重复位置、错误 role、受条件控制的特殊模板、给这个保留变量赋值或做算术都会被拒绝;实际渲染漏掉当前块也会终止,不能继续提交 checkpoint。未声明该位置的旧 preset 保留原注入办法。这个位置改变 Actor 怎样读摘要,不会给摘要增加新事实,也不会自动修改已部署模板。位置约束与转义[111] · 每次渲染采用当前摘要[112]
第一次整理、增量整理和超时接替,可以选不同模型
单一摘要模型仍是兼容路径。接入方显式增加 compact.bootstrap 后,缺少旧摘要或需要重建时可交给 bootstrap;已有可用摘要时由原 compact.compactorModelConfigId 指定的 primary 整理新增历史。比如已保存“借钥匙、约好归还”,primary 这次只需接入“守卫检查钥匙”的新对话。若 primary 已整理好前一段、后一段触发可交接的预算或超时条件,程序保留成功段的摘要,把它和全部尚未完成的原文交给 fallback;不会把已经花过的时间或调用次数返还。
fallback 不是任意报错都重试一次。只有 primary 的规划/尝试额度不足、单次模型超时或为备用预留时间而结束 primary 才能交接;调用方取消、整次压缩超时、配置无法确认等直接终止或跳过。bootstrap 失败不会自动进入这条 primary→fallback 路径。迟到的 primary 被取消,不能回来覆盖备用结果。fallback 使用自己的模型和完整请求重新计数,不裁掉待处理原文去凑预算;最终摘要、Actor 输入预算及 CAS 保存都通过后,整次只提交一个 checkpoint。角色选择与共享时限[113] · 允许交接的原因[114] · 备用重新计数及失败分支[115]
| 配置或记录 | 程序如何使用 |
|---|---|
Scenario 顶层 compact.bootstrap/compact.fallback |
可选;primary 仍是同一 compact 对象原有模型,不是另填一个 routing 对象 |
| 启用组合 | primary 必须 bounded_recent+configurable-v2+plain_text,并显式给出 reliability v1.1;各备用角色也必须使用 configurable-v2/plain_text |
| 各角色参数 | 一旦给出bootstrap或fallback对象,必须提供非空modelConfigId、profile:"configurable-v2"、受支持的inputProtocol与outputFormat:"plain_text"。lengthPolicy可选、默认reject;递归协议可配recursive.segmentContentTokens,不改变全局共享预算 |
| fallback 时间 | primaryAttemptTimeoutMs 与 reserveMs 必须为正整数;前者不大于总时限,后者小于总时限;共享 maxModelCalls 至少 2 |
| 共享额度 | 三角色共用候选次数、模型调用、token 和总时间约束;必须留有剩余预算才能启动备用 |
| 采用与保存 | initialRole、modelCallsByRole、fallbackReason/Disposition/SkipReason 说明做过什么;fallbackModelValid 不等于已采用,还需看 fallbackAdopted、adoption 和 persistence |
当前混合路径只在增量阶段使用 Jev;冷启动和重建跳过分类。角色配置及实际模型身份进入指纹,换角色可能使旧摘要需要重建。生产目录中两个 AutoMemory native 覆盖文件目前没有 bootstrap/fallback 字段,因此不能把“生产覆盖文件已存在”写成“Hybrid 已在生产启用”。仓库测试覆盖预算、取消、失败、恢复和单次保存,真实长聊事实保留、费用与线上使用仍未验收。配置校验[116] · 指纹[117] · v0生产配置[118] · v1生产配置[119]
#207 已合入:累计计数搜索怎样减少回复前的重复准备
**它改变的是压缩任务中寻找历史范围的准备工作:**当旧聊天太多,程序要找出“从哪一组开始,剩下的连续历史才放得进压缩模型”。累计计数搜索尝试减少对大段重叠历史的反复计数。它不负责判断哪件剧情更重要,也不改变 Compact 的触发时机;先有压缩需求,并采用 bounded_recent,才会走到这项搜索。
例如原候选有几十组旧聊天,完整请求计数显示超过压缩模型窗口。程序仍按完整对话组寻找近期连续范围,再交给摘要模型;累计搜索只是改变寻找这个起点的办法。它可能跳到比原办法更靠后的起点,少带一些历史、留出更多预算空隙,所以“最终放得下”不等于“已找出保留最多历史的最优边界”。
boundarySearch |
怎样找边界 | 当前状态与结果边界 |
|---|---|---|
未填或 binary |
二分选择候选,每次完整计数判断能否放下 | 默认行为 |
measured |
用已实测的预算占用比例指导下一次探测,并保持搜索范围约束 | #198 已合入;在原有单调性假设下寻找与 binary 相同的首个可用起点 |
cumulative |
先依据完整计数压力和组的字符量跳到候选;临近边界仍超限时,仅累计待移除完整组的片段 token,随后再次完整计数 | #207 已合入;找到已验证可用的近期后缀即可返回,不保证与其他算法选择同样的历史 |
开启后,每一步拿什么、产出什么
- **输入沿用现有准备结果。**候选是已闭合的历史组,另带旧摘要、角色材料、本轮问题、压缩模型配置、摘要预留和可靠性预算。要求保留的近期原文仍由原配置处理。
- **先检查完整候选。**如果已经能放下,直接继续,不额外逐条预计算。需要裁选时,完整计数的占用比例用于大步定位;字符量只用于选下一个探测位置,不直接授权生成。
- **只在小范围超限时计边界组。**JSON 协议按真实 JSON 消息片段渲染;文本协议保留
user:/assistant:角色标记。不可拆的一组先连成一个字符串,再计数;它不是把全部历史逐消息扫描一次。Jev 已形成筛选投影时,候选片段按该投影计算;完整来源恢复仍遵守原恢复规则。 - **产出连续区间与分段计划。**每个被采用的候选仍调用完整
countInput,检查角色、旧摘要、问题、模板、摘要预留和安全余量;递归模式另查每段正文容量。片段 token 相加不是完整请求 token 的可靠上界。 - **生成与保存仍经过原闭环。**摘要模型按计划生成,输出通过格式、长度等检查,最后再组装并计数 Actor 的全部输入。具备持久化条件才 CAS 保存摘要、原始覆盖与指纹;同步任务发生在回复前,后台任务在其完成时提交;中间片段计数缓存不是长期记忆,下一轮仍读取正式检查点。
配置和约束[120] · 片段与完整输入渲染[121] · 完整检查与算法选择[122] · 累计定位算法[123] · 最终 Actor 输入及保存条件[124]
接入片段、计数降级、诊断与实验范围
把以下两字段合并进已有可工作的 Scenario.compact,保留原来的摘要模型、协议和显式 reliability。它们不是独立完整场景,也不启用 Jev:
{
"executionPolicy": "bounded_recent",
"boundarySearch": "cumulative"
}
当前 config/、deploy/ 没有开启 cumulative 的实例。接入应先确认 Axon 支持文本计数及所用模型的本地文本 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,不是看计数成功。
主线#211修改的是开发者回放脚本的CLI参数校验:提供 --legacy-axon-url 时必须同时提供 --cumulative-axon-url,否则在开始计数前报错;未提供这两个覆盖参数仍可按原方式回放。它不是聊天请求或Scenario的新开关,也不改变上面运行时计数失败时的回退策略。回放参数校验[125]
**已有实验只验证特定数据下的计数准备开销。**仓库最终版以三个既有会话各做三轮交替对照,摘要生成使用冻结响应、检查点只写内存;三组计数阶段中位耗时分别下降 17.5%/23.1%/19.1%,三个案例每轮合计下游请求 39→35、提交文本字节下降 38.7%,摘要覆盖仍为 42/58/34 条消息。实际走的是“AutoMemory 新文本 profile 不可用 → 旧片段计数回退”,不代表新文本接口在所有模型上已获同样收益,更不证明生产 p95、真实摘要遗漏率或实际生成费用改善。不能把早期不同算法版本的数字混进这一版结论。
Counter 和降级[126] · Axon 文本 RPC[127] · 诊断与回退[128] · 最终版回放及限制[129]
截至 9/23 08:31,#196/#198 历史及段落过滤、#205 本地计数与段落 V2、#207 累计边界搜索均已进入 main。默认关闭的是 Jev 过滤,默认 binary 的是独立边界搜索;不能把二者当同一个开关。段落 V2、cumulative、Hybrid 和 preset 摘要位置都需要各自显式配置,代码合入不等于已有 workload 采用。旧候选锚点继续保留。
已合入、默认关闭:摘要前筛历史,再由原压缩模型生成摘要
**Jev 在这里是历史分类器。**现有 Compact 已经决定需要压缩后,它判断哪些候选历史可以不交给摘要模型;程序再算节省是否值得、实际请求能否装下。Jev 不写摘要、不选角色工具、不更新 Director 状态。普通 Agent V2 的 Jev 工具编排是另一项接线。
例如,用户曾说“铜钥匙借给你,天黑前还”。助手的一条长回复分为两段:第一段只反复描写同一片月光;第二段写“我答应天黑前还钥匙”。本轮用户问:“你答应我的事还记得吗?”
| 时点 | 程序与模型实际做什么 | 本轮和下一轮得到什么 |
|---|---|---|
| 同步准备或后台任务中,Compact 已触发 | 保留配置要求的近期完整组,把其他已闭合历史交入筛选;Jev 得到角色背景、旧摘要、本轮问题、近期原文,以及目标与相邻组 | 分类对象来自本次收到的历史,不去聊天库找回全部旧消息 |
| Jev 返回判断 | 选用自然段策略时,每段返回 keep/drop/uncertain 和三类分数。承诺段应保留;仅装饰段可能满足省略条件 |
这是解释性例子,不是对真实模型判断的保证 |
| 程序生成投影并检查收益 | 只按宿主切好的原文范围替换为 […],用户消息保持原文;用完整真实请求比较同一来源区间过滤前后的 token |
默认至少省 512 token 且达到 10% 才采用;单个短例子很可能达不到门槛,继续用原文 |
| 原压缩模型生成摘要 | 真正采用时,收到保留正文、省略标记与宿主说明,例如产出“已承诺天黑前归还铜钥匙”;它读不到被省略段落 | 摘要与保留近期原文重新进入 Actor 输入,仍需格式、大小和最终窗口检查 |
| 摘要验证通过后保存检查点(同步在回复前,后台在任务完成时) | 沿既有 CAS 保存摘要和完整原始覆盖范围、历史指纹、用量审计 | 保存后下一轮复用摘要与未覆盖原文。聊天原文没有被修改;被省略内容不会因下一句追问而自动回补 |
**“用户消息不删”仅指自然段筛选阶段。**原有预算规划仍可能舍弃装不下的早期区间;不能把它理解为全部用户历史都会永久进入摘要。保存覆盖范围也只证明该区间经过了筛选和摘要,不证明每条事实都留在最终摘要里。自然段筛选与投影[130] · 最终采用和保存[131]
三种模式和两种筛选策略
| 开关 | 谁等待、是否改变摘要 | 当前默认 |
|---|---|---|
historyFilter.mode=off |
不发 Jev 请求,继续原有压缩 | 默认;只配置 policy 不会启用 |
shadow |
后台做分类,前台仍按原文压缩;不改变摘要输入或检查点,也不生成第二份摘要 | 每个缓存的应用依赖实例最多两个分类任务,不排队,满额跳过;仍有额外请求和费用 |
apply |
压缩任务等待分类;同步时回复准备也在等待;满足触发、规则与收益门槛才采用,否则在剩余预算内恢复原文规划 | 需要主动启用并提供 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% 误删率” |
任何批次失败、超时或单目标也装不下,会放弃本次全部筛选建议;请求取消继续向上传播。达到调用次数上限而没检查到的旧内容保留。分类输入本身也有预算,过大会缩批;不是每段都单独请求一次模型。完整组规则[132] · 自然段门槛与失败处理[133] · Shadow 容量[134]
实际接入片段、全部默认参数、计数和回滚
把下面字段合并进已配置可用的 Scenario.compact 对象,保留其摘要模型、协议、预算和 reliability;完整 native 样例见本节上方“谁控制触发、保留范围和调用预算”。示例先用 shadow 观察新自然段策略;这会发真实分类请求,需现有 Kaon 地址、鉴权与 Axon 计数服务。它不是一份可独立替代整个 Scenario 的 JSON,也不是已在生产启用的配置。
{
"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 只对没有可用旧摘要的压缩分类 |
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 额外要求计划只需一次摘要调用且完整请求与递归预算均通过 |
minSavedInputTokens / minSavedInputRatio |
512 / 0.1 | 两项同时达到才采用,分别可设 0–1000000、0–1;比较同一来源区间,不能把原规划丢弃的旧前缀算成筛选收益 |
budget.maxInputTokens |
28000,范围 1–32000 | Jev 的完整 state+questions 请求预算,另受身份声明的上下文上限约束 |
maxQuestionsPerCall |
128 | 组策略范围 8–1024,每组八题,默认最多 16 组/次;段落策略范围 1–1024,每段一题 |
maxCalls / maxTotalMs |
2 / 3000 | 范围 1–10 次、1–30000ms;apply 身份读取也消耗此时间,分类还受整个 Compact 时限约束 |
model 或 modelConfigId |
不填时直接用 openrouter/~typesafe/jev-latest,身份窗口 32000 |
两者互斥。显式 ModelConfig 必须解析到 Kaon Jev 及合法上下文;它选择分类器,不替换摘要模型 |
Jev 调用原生 Decisions:{model,state,questions}。#205 已合入 main 后,程序在本地把 model/state/questions 序列化,用加权 UTF-8 加 256 的协议余量估算长度;不再把远程 token.count + 1024 当当前分类计数路径。估算不是严格上界,低估仍可能让供应商拒绝请求并增加失败与回退等待。对话组或段落分类失败时放弃本次筛选,保留这次送筛选的完整原文;用户取消沿取消流程结束。摘要模型自身仍做完整请求计数。当前估算[135] · 实际接线[136] · 段落失败保留原文[137]
boundarySearch 是独立于 Jev 的预算搜索选项,可选 binary/measured/cumulative,显式设置仅允许 executionPolicy=bounded_recent;省略沿用 binary。它不筛语义,搜索本身不调用摘要模型,也不扩大窗口。三种算法、实际候选输入和计数回退见上文累计计数与边界搜索。可以关闭 Jev 后单独使用。Jev 配置解析[138] · 分类模型身份和计数估计[139] · 三种边界配置[140]
段落策略新增 paragraph-memory-experimental-v2,仍需明确选择且过滤默认 off。V2 调整分类提示与保留判断,实验结果有好有坏,不能把本地估算优化等同于减少误删。9/22 的有限 186 请求未出现低估,只能说明那批数据;不保证其他语言、长文本或供应商边界同样成立。V2 的策略指纹进入采用与复用判断,切换时需同时核对旧 checkpoint 是否仍可复用。段落V2及策略指纹[141]
停止采用设置 mode=off。若回滚到不认识新 policy 的旧镜像,应删除新 policy 或改回旧策略;仅设 off 不能绕过未知策略校验。配置变更不会自动启动 A/B 或恢复旧摘要里的缺失事实。
保存、故障恢复和仍需验证的语义质量
已修复的工程故障:#196 最终合入版已修复“提供方报上下文溢出后继续沿用过滤摘要、却推进完整覆盖”的旧问题。当前遇到过滤计划的本地/提供方溢出,会清除已采用的收益证据并恢复原 source。有界路径从原摘要重新规划整个已选原区间,废弃已经生成的过滤前缀,且不额外丢弃这些已选消息;普通路径恢复当前阶段及后续原文。已花费的候选次数、模型调用、时间不返还,剩余预算不足时不写 checkpoint。当前恢复实现[142] · 普通路径恢复[143]
**仍需验收的是判断质量。**如果返回合法的高分 drop,却误省略了“答应天黑前还钥匙”,运行时可能正常生成、校验、保存一个没有该承诺的摘要。格式正确、预算通过、CAS 成功都不会自动发现语义遗漏。当前没有 summaryAudit、maxRepairAttempts、生成后事实对账或自动重写恢复。
| 要核对的结果 | 现有记录及边界 |
|---|---|
| 本轮提出了多少省略建议 | CompactDiagnostics.jev 或 roleplay_compact_jev_shadow 中有模式、状态、调用/检查数、分数、耗时和用量;段落策略新增 checkedParagraphs/omittedParagraphs,它的 omittedGroups=0 不表示没筛选 |
| 本轮是否真的采用 | 要看 status=adopted 和实际节省诊断。分类建议数量不等于最终采用数,shadow 也没有真实摘要节省结果 |
| 能否事后还原省略正文 | 请求诊断只有宿主别名和分数,不带原文/源消息 ID;checkpoint 保存原始覆盖与哈希,但没有省略清单。现有记录不足以单独还原每段被省略内容,需要业务补可追溯 omission audit |
| 下一轮是否复用同一规则 | apply 的语义指纹含配置、模型身份与 renderer;完整组版本后缀 +jev-retention-v1,自然段版本后缀 +jev-paragraph-memory-experimental-v1。off/shadow 沿原身份;变策略可能失效并重压 |
| 身份临时无法确认 | 不失效或覆盖旧 checkpoint;可退回原文压缩供本轮使用,但不持久化这次结果。取消、Regenerate 只读、CAS 冲突和超时确认沿原机制 |
启用 apply 的业务验收应覆盖承诺/取消、纠正、伏笔、状态变化、短答依赖与情绪连续性;同时比较包含分类成本的总耗时、费用和事实保留,并确定可追溯审计与回滚阈值。Shadow 只证明旁路分类,不能代替实际摘要和多轮继续聊天的质量验证。观测字段[144] · 身份与保存保护[145]
**巡检证据范围:**9 月 22 日早间巡检已记录 #196 最终版定向测试和受控旧/新复现、专用 Staging 21/21;随后 #198 相关七个文件 109/109、远端 main Actions 成功。下午固定 ccaaa46e 的报告另记录 cumulative 22/22、suffix search 10/10、paragraph runtime 12/12 定向检查通过。这里引用已完成巡检,本次文档更新没有重跑或调用真实模型;它们支持工程路径,不证明新策略已在现网启用或带来质量、延迟、费用净收益。
用户身份与长期要求:资料读取和规则修改分开
**Persona 是已有用户资料的读取流程。**例如用户选择“外乡学徒”的扮演身份,程序准备出这段资料,回复模板引用后才能使用;普通 Agentic 后台还会单独收到非空的用户资料。它描述用户,不是目标角色,也不能证明守卫已经知道用户的身份。
**聊天中新说的偏好,先是一条新消息。**用户说“以后叫我阿宁”,本轮回复应直接回应;能否之后继续采用,要看当前启用的持续状态、日记或表格流程是否成功保存并再次读取。这段读取 Persona 的实现没有在回复后自动把聊天偏好写回用户资料库。
**长期角色指令有另一条 DIO 流程。**在已接这项能力的前台,用户明确要求“以后让艾琳说话简短”,可以触发向外部服务提交角色修改任务。受理回执说明任务已接受;外部服务随后尝试生成并启用新的角色指令。任务成功且后续请求读取到有效新指令,才用它准备角色回复,已经开始的正文不会被这条新指令中途替换。
这里需要保留的内容不同:Persona 回答“用户扮演谁”;持续状态可记“用户提出了什么偏好”;DIO 修改“角色以后遵循什么指令”。普通后台的 Director 整理状态,DIO 的输出则是角色指令,两者不能因同名而当成一条保存链。
从实际结果看,Persona 准备把文字放在 setvars.userCustomPersona,Actor 模板按需引用;非空时另以 userPersona 给普通后台。这个步骤负责读既有资料,不负责把聊天里新称呼同步保存回去。DIO 则读外部已启用版本的 compiledPrompt,按对应配置参与角色输入准备;后台普通 state 保存不会代替这项指令发布。
具体可见范围与生效条件:Persona 进入哪些模型 · 长期指令怎样读取并替换角色位置。
开发核对:Persona 可见范围与 DIO 的受理、读取和生效
Persona、召回变量与实际模型输入
buildSetVars 取得 userCustomPersona;persona_id 若传入需为正整数,不传也不等于一定没有用户资料。模板决定回复模型怎样使用;非空资料还会显式传入普通后台,相关岗位截取上限 4000 字符,并要求把它视作用户身份而非 NPC 身份或已经发生的剧情。
日记与表格分别以 compassMemory、memoryTable 返回。程序记录 recalled 和 rendered,分别代表取回非空内容与模板引用;还要考虑后续预算裁剪。普通后台材料重新构造,没有自动复制这两个变量;本轮实际是否使用,应查最终模型输入,不能只看召回日志。
依据:用户资料准备[146]、模板变量与渲染[147]、后台独立构造[148]、后台 Persona 限制[149]。
DIO:受理修改要求,后续读取已启用指令
DIO 是显式长期修改角色、世界或表达要求时使用的接法。当前应用要同时启用前台编排和 DIO,才在回复前尝试取有效角色指令;一次普通继续聊天不会自动被理解为长期修改。向外部 /v1/chat 提交的任务包含用户、RP 会话、DIO 会话、目标角色 prompt、修改要求和语言。accepted 只表示受理,没有本轮已完成生成并启用的保证。
后续读取返回的版本、变更信息、编译后的角色指令与内容哈希。程序验证可用后把 compiledPrompt 交给角色输入准备;读取失败通常记录并继续原有输入,取消另行传播。正在生成的这条正文不会被后台角色修改中途重新生成。新指令如何生成、审核、启用和落库属于外部 DIO 服务,两个仓库并未实现其完整内部保存链,不能仅凭受理回执宣称角色资料修改完成。
依据:适用修改要求[150]、提交任务[151]、有效指令与校验[152]、读取条件及失败[153]、写作输入采用[154]。
世界书:保存作者设定,按每轮需要重新选取
可直接核对原文版本与 Prompt 绑定、条件 state 的实际来源、本轮 blocks 与诊断保存。
**世界书的原文由作者或管理接入维护。**例如“铜钥匙代表旧王室身份,但不能替代城主手令”被导入为条目,连同触发规则、位置和优先级形成内容版本,存入世界书服务。修订创建新版本。需要向量检索时,要为确切版本显式构建索引;规则选择和词法检索不依赖它,hybrid 的向量部分不可用时可降级为词法。
**每轮用哪本书、哪一版,由该 Prompt 当前的绑定决定。**Harness 先经 Axon 调 worldbook.conversation.check 核对会话,再按 Scenario 的 tenant 和请求的 Prompt 调 worldbook.bindings.resolve,得到本轮具体 book/revision 后调用选择接口。#199 后若绑定结果为空,程序不创建 WorldbookTurn,因此不做 select 或 placement,也不因“启用了但没有书”改变普通历史预算;下一轮仍重新核身份和解析绑定。绑定写固定 revision,作者的新版本不会自动切入;绑定 revision 为空表示跟随最新书头,作者更新后既有会话下一轮就可读新版。更换或清空 Prompt 绑定也影响既有会话下一轮;本逻辑轮已解析和选择的结果仍复用。
**选择返回本轮资料,不生成新的剧情记忆。**世界书服务读取指定内容快照,按规则或混合召回选条目,返回原文块、位置与选择原因。Harness 把合适的块装入回复模型;普通后台没有自动收到同一批原文。用户在故事里归还钥匙,不会通过这次选择自动改写作者条目。
**本轮选择与诊断也是单独一类记录。**Harness 在一次逻辑请求里缓存选择结果,供本次重试复用;Demo 可以在浏览器保存选择轨迹。#200 又接入了 Worldbook RPC 的 Langfuse 输入/输出观测,包括 query、历史、state 和 lore;是否导出取决于 telemetry 配置。它们是调试记录,不是世界书跨轮使用计数,也不会自动进入下一轮剧情记忆。
在本次固定世界书源码中,选择接口没有会话轮次或选择检查点参数,也没有聊天结束后提交选择进度的接口。导入器会把 sticky/cooldown/delay 等源格式的运行要求标成不支持;识别这些字段不等于执行跨轮持续、冷却或延迟。聊天后保存正文、普通后台保存状态,是各自的服务调用,不能改称“世界书自动沉淀”。
**服务交回的是可直接装配的原文块,不是“记忆搜索完成”的空通知。**一个 blocks 元素有 id/content/position,还可以带 title、role、depth、order 等。例如 content 为“铜钥匙不能代替城主手令”,position 指定人设前后或允许的历史深度。Harness 校验位置后包装为带条目身份的文字,再放入 Actor 消息;decisions、snapshot、hash 和 token 统计用于追踪本次选择。条目原文、选择回包、已保存聊天是不同对象。
这里保存到世界书服务的是作者的内容版本与派生检索资料;本轮 blocks 仅在逻辑请求内缓存。下一次会重新解析 Prompt 绑定与具体版本,再重新选择,不从一个“上轮已选条目列表”恢复整套跨轮计时状态。即使同一条连续命中,也不能倒推服务已存过冷却/粘滞计数。
开发核对:内容修订、索引、Prompt 绑定、条件 state 与本轮轨迹
作者原文、检索索引和 Prompt 绑定是三种记录
Worldbook Service 将书籍修订及条目存到 PostgreSQL。新建/正式导入会保存;preview 仅解析、返回规范化内容及报告。提交修订要求 expected_revision:事务中检查当前版本,成功才写下一版本的完整条目集合并更新书头,旧版并非原地覆盖。聊天的 select/context 调用不执行这项修订。
向量存于同一 PG 装配下的 pgvector 与 vector_manifests,按书、revision 和 embedding 版本区分。建索引可由显式API触发,也可由明确开启的一次性启动重建触发;不是每轮聊天自动执行。单版本索引状态经历 building/ready/failed;已 ready 且未 force 时复用。每轮选择不自动建索引,向量命中也要回到所选原文快照取权威条目。 明确开启的启动重建会处理所有已存修订的派生向量,不修改作者原文;新版索引验证成功后才提交旧向量清理,失败有回滚边界。规则与词法检索不要求向量就绪;hybrid 遇向量部分的 DomainError 可标记 degraded 后以词法继续,纯 vector 搜索会报错。不能把这个特定降级规则概括成任意服务故障都能继续。
Worldbook 当前用 entity_worldbook_bindings 保存资料分组、业务对象、书籍的关联;007 将旧表和字段改名并保留数据。现有 RP 用 promptId 作为 entity_id,revision 可以为空以跟随最新 head,也可以明确固定。管理侧 replace 以事务锁替换绑定;resolve 读出这轮具体版本。Harness 的 conversation.check 是核对会话身份/范围的外部 Axon 合同,随后调用 bindings.resolve,不再沿旧会话 pin/get 机制固定一本书。内容新版本、派生向量和 Prompt 绑定分别保存;改绑定本身不为缺失版本建索引,也不改作者原文。生产 007 改名迁移与 Axon 的 Entity 参数是否已接通,需要单独回执;新旧接口与升级步骤在世界书原章展开。
依据:创建与修订写入[155]、修订版本检查[156]、创建、预览和导入接口[157]、索引装配[158]、检索原文及降级[159]、显式索引生命周期[160]、明确开启的启动重建[161]、派生索引重建与清理[162]、省略 revision[163]、逐轮核对及解析[164]、当前服务绑定存储[165]。
条件 state 由调用方提供,服务不替会话积累跨轮进度
SelectRequest 接受 state 字典,条件读取指定 path 并判断 eq/ne/in/exists;服务不推演或更新这个字典。Harness 尝试 JSON.parse(state.state),只有对象才用于条件;解析失败或不是对象就传 {}。普通 Agentic 的固定栏目文本通常不是 JSON,不能说它已把全部物品、NPC 和 ledger 自动转成可筛选的字段。当前#223只发送原始本轮输入作query,不再从公开场景文字追加检索词;hybrid短历史由服务端单独构造。
固定服务的选择请求没有 session、conversation、聊天轮次、上轮选择检查点或冷却计数字段。context() 读取 PG 只读快照,必要时计算 hybrid 排名,再选择并返回;没有聊天后提交 selection/runtime 的接口,也不返回下一轮运行状态。
导入的非零 sticky/cooldown/delay 会标为 timed_activation,含这类运行要求的条目因 unsupported_runtime 落选;原生 Entry 也不接受这些未知顶层字段。MVU 等状态更新方言会被标记并排除,不会在选择时执行。constant 是每次选择可走免关键词激活的规则,仍受资格与预算;max_recursion_rounds 是同一次选择内部继续激活候选的次数;seed 参与概率筛选。这三个都不是跨聊天轮的使用计数。
依据:请求字段与严格契约[166]、状态条件[167]、Harness JSON 解析与场景[168]、只读选择服务[169]、API 边界[170]、时间与状态方言导入标记[171]、资格过滤与本轮递归[172]。
选择响应、浏览器诊断与正文保存分别完成
选择响应包含原文 blocks/位置、decisions、版本 snapshot、内容与提示词 hash、token 统计、selection fingerprint 和 degraded 信息。Harness 在一次逻辑请求中缓存选择 Promise,同轮模型重试复用,新逻辑轮重新选择;该 Prompt 没有绑定书时不创建 WorldbookTurn,跳过选择 RPC 和后续 placement;身份核对与 binding resolve 仍每轮执行。预算后的 blocks 装进 Actor,普通后台材料构造没有同批 blocks 字段。正文以后若被保存并带回历史,后台可能间接看见写入正文的信息,但这仍不是同轮原文注入或作者设定更新。
新增服务端观测:worldbook.conversation.check、worldbook.bindings.resolve、worldbook.select 已封装成功、超时、取消和失败 span。开启 HARNESS_TELEMETRY_ENABLED=true 并配置 Langfuse 后,宿主创建的 Worldbook envelope 可导出 RPC 参数与结果;内容含本轮 query、最多 20 条历史、state、binding 和选中 lore。每项 JSON 上限 16000 字符,超过时输出带 truncated 的结构化预览。当前只对 authorization、cookie、password、secret、api_key、access_token 等精确键名脱敏,故事正文不会自动脱敏;没有独立“仅指标开、正文关”的开关。发布前须核对正文采集授权、访问范围、保留和删除策略;本次未直接验证生产有效开关或 Langfuse 权限。RPC 观测[173] · 总开关与正文过滤[174] · 脱敏及预览[175]
Demo 的 trace 在模型调用前产生,经 SSE 给页面,再尝试写浏览器 localStorage;key 包含用户、书和 revision,记录挂在助手消息 ID 下。它可以解释本轮准备了什么,但正文生成失败也可能已有 trace;换浏览器或本地保存失败,不能承诺从后端重建全部轨迹。Demo 先保存用户消息,生成完成后保存 result.output.text 为助手消息,保存成功才发 done;它没有把这次选择修订为世界书条目,也没有提交跨轮计时状态。
依据:响应字段[176]、逻辑轮缓存与 trace[177]、后台独立输入[178]、模型前 trace[179]、浏览器诊断保存[180]、Demo 正文保存时点[181]。
单独接 SDK 时,记忆从哪里来:默认不会搬来应用的整套资料
**通用 SDK Agent 没有一套默认替所有 RP 读取日记、世界书和状态的工具菜单。**宿主实现 prepare,提供这次 Pi Agent 的配置、提示词/消息及工具,并用 result 解释结束状态;每次 run 建立新的实例。主 Agent 的 system prompt、工具定义和资料都由这条接入准备,不能因为仓库已有 Memory 工具就认为普通 SDK 调用会自动装载。
例如业务想记住“明早去北塔”:先选一个受认证身份约束的存储,注册 get_memory/update_memory,告诉模型什么时候读、什么信息值得改,以及调用后的结果要怎样接受。模型调用 get_memory 得到完整对象和版本后,才能基于旧值提出完整新对象;程序校验并比较版本保存。下一轮仍要明确读取并交给模型。只注册写入工具,没有回读和输入使用,就只能做到“某处可能写了数据”,还没有形成记忆闭环。
**如果接独立 Slow,宿主要传起始状态与历史,它不会自行查聊天库。**它的初始消息由“宿主慢任务说明+state文字和版本+宿主提供的history+当前input”组成;传入快照的 ledger 也不会自动逐项编进这段 state 文字。工具列表来自传入的 capabilities,缺省是空。循环返回 final、toolResults、执行结果;没有 prepareCommit 回调,或回调判断无需保存,状态就是 retained。回调给出被业务接受的新状态,并且存储提交成功,才是 committed。SDK 不自动套用普通 RP Director 的固定栏目或审查剧情语义。
**FastSlow 只是把同一起始状态提供给两条执行,再并行安排。**它先经宿主 state.get 读快照,冻结本轮材料;默认快路是一次模型调用,慢路用自己的提示词与工具循环。背景慢路没有自动收到快路稍后生成的新正文。如果业务要求“正文已保存并被采用以后才更改事实”,可以由宿主在那个时点把实际正文交给独立 Slow;当前并行入口不替业务补这条因果关系。
因此 SDK 中的模型选工具,是在宿主已经开放的菜单里决定做什么;业务应用中 memoryRuntime/memorySources/hookPlanMode 的装配,是另一层准备规则。没有一个统一的动态机制,会因模型谈到钥匙就临时发现所有仓库工具、挂载相关数据库并将结果写入全部状态。
工具由谁挂载、哪些资料能按请求配置加载,见三个 SDK 入口的责任和应用动态装配的范围。
开发核对:默认工具、主提示词、状态读取和提交的责任
Agent、Slow 与 FastSlow 的不同入口
AgentRun 由 options、prompt、result 回调组成。Slow 的 capabilities 缺省为空,并明确启用工具参数校验;提示词取 options.prompt,状态与历史取调用者上下文。FastSlow 的 start 才负责调用配置的 state.get,并用 prepareFastSlowContext 复制冻结;直接 Slow 调用不代读也不再次复制。
独立 Slow 的 prepareCommit 返回空时,不创建新版本;有候选时用起始 revision 提交完整 state、工具名及可选 ledgerEntries。状态冲突可以是执行 completed 但 stateOutcome=stale_write_rejected。某个工具失败的回执也可以留在一趟 completed 结果里,宿主要看业务结果后再接受。取消不能撤销已经成功的外部写入;普通后台应用、SDK 的通用循环和 Story 的正文采用逻辑不能互相替代。
“动态加载”在应用里的实际范围
memorySources 提供每项 id、agentRef、variable 及可选priority;Axon Go 只接受 compassMemory/memoryTable 这两类来源变量,不会从 Agent 名称猜出任意新记忆协议。Personalization 通过 agentRef 向外部加载配置,受 live 和 hook 调用条件控制。
Actor 的 hookPlanMode=profile 采用方案中指定的前后引用;model_config 从模型 feature_config 提取引用,merge 再合并方案引用,并排除已经作为记忆来源的 Agent,避免按同一来源再走发现路径。include_prompt_sources=true 的 hook 要等角色原始资料可用后才调用。随后角色模板按实际使用的变量渲染,再经过输入预算。模型本身没有在这些步骤里读取磁盘目录或选择任意系统工具。
依据:通用 Agent 的宿主输入与结果[182]、Slow 默认工具与主提示词[183]、状态文字和历史的消息结构[184]、SDK 状态接受与提交[185]、FastSlow 读快照与安排[186]、JSON读写工具[187]、认证作用域适配[188]、记忆来源类型限制[189]、应用hook配置装配[190]。
这些资料怎样组合:接线和消费者决定是否生效
| 接入方式 | 资料由谁安排 | 必须明确的关系 |
|---|---|---|
| 复用 SDK/单个工具/既有 Workflow | 宿主提供模型、存储、输入准备和结果处理 | JSON工具可以保存对象,Story工具可以返回新快照,但宿主仍要决定何时读取、采用和保存 |
| 仓内完整文字 RP 流程 | 请求选执行方案,程序装配相应记忆服务、回复和可选后台 | 日记/表格取回后须进模板;普通后台单独准备输入,不自动继承 Actor 见过的全部资料 |
| Story 流程 | Story 协调程序维护世界与叙事快照,核对已采用正文 | 当前分支替代普通六专家后台;不能同时把两个流程当成同一份状态的写入者 |
| Sumi 流程 | 独立图文程序按消息和分支维护快照 | 当前配置校验不允许直接叠加普通 Agentic、Compact、额外记忆来源和普通前后 hooks |
| 显式配置的世界书输入 | 接入方维护业务对象关联(RP 仍以 promptId 为编号),回复前解析版本、选条目并装入 Actor;普通 RP、Compact、V2、Story、Sumi 均已有对应接线 | 只向本轮回复模型注入;不自动给后台、Story 工具或 Sumi 初始化使用,也不合并日记等存储 |
Agentic 与 Compact 组合还需明确选择上下文处理模式:enforce 才让普通后台采用本轮摘要和保留历史;shadow 只做对比,后台仍用原请求历史。这个 shadow 与记忆后端的 axon_shadow 是两个不同配置。
**每次判断“记住了”都应沿对应资料检查三件事:保存成功了吗;后续请求读到了吗;最终模型输入真的使用了吗。**新记录不会自动改写其他资料;保存成功也不能保证模型每次都正确遵循。版本检查、重复消息、停止生成、取消与失败,应按上述各条流程分别判断。
遇到“它又忘了”,应定位哪一步
先确定丢的是聊天原话、经历摘要、当前记录、作者设定,还是某条消息分支的状态,再沿那条流程检查。名称相近不代表读取同一份资料。
| 具体情况 | 当前流程中可能发生了什么 |
|---|---|
| 用户刚说完,下一句没采用 | 普通后台可能尚未完成,后一轮先读了旧状态;也可能新信息仍在历史里,但模型没有遵循。先区分未读到和读到后写错 |
| 正文已收到,普通后台状态没有更新 | Director 没有有效变化、校验不通过或版本冲突,候选不会替换有效记录。保存超时/报错还需核对实际结果,不能仅凭错误断言一定写入或一定未写入 |
| 日记没有新增 | 可能未接该来源、未达到条件、额度或锁不允许,或者计划只更新摘要而不生成日记卡;也可能生成、解析或保存失败 |
| 正文写对了,记忆表没变 | 原始输出未包含有效编辑、改动为空、后台尚未写完,或版本冲突等写入失败 |
| 记忆表已更新,角色仍按旧值回答 | 那轮可能早已读到旧表,模板没有带入新表,或模型读到后仍写错;普通后台也不会自动获得这张表 |
| JSON 更新后其他字段不见了 | 工具采用完整对象替换,提交时没有保留那些字段;它不是局部字段自动合并 |
| 压缩摘要生成了,下次仍重复压缩 | 本轮用了临时摘要但持久保存失败,或角色/历史覆盖变化导致旧记录不再适用 |
| 修改旧消息后,摘要仍含旧内容 | 核验受本次可见消息范围和稳定标识限制,窗口外被修改的原文不能凭空重读;需查摘要覆盖与此次输入 |
| 本次更新回复前记忆服务报错,本轮没有回复 | 默认终止;场景可显式选择缺少召回记忆但继续。Hinos 只容错可恢复服务错误,取消、鉴权及坏协议仍失败;空召回不同于故障 |
| 正文收到后记忆任务失败 | 回复后写入尽力执行,失败不撤回正文,也不证明新内容已经保存;后台任务没有耐久补跑保证 |
| Persona 没变,但用户已经提出新称呼 | 本轮聊天没有自动写回 Persona;要查实际承担偏好保存的状态、日记或表格是否启用并成功 |
| DIO 已受理,角色仍用旧说话方式 | 受理不等于生成并启用完成;还需后续请求成功读取有效新指令,本轮已开始的正文不被替换 |
| Story 写了接钥匙,但进度没有确认开门 | 后果须按实际保存正文核对,接钥匙本身也不能证明开门。还需本次采用后的快照成功提交,不能只查模型曾经提出什么 |
| Sumi 切分支后不能沿用原状态 | 每条消息的父节点、输入签名与状态快照需匹配;缺快照、历史改变、角色资料变化或导入未启用,都不能无条件复用 |
| Sumi 聊天里已有图,图库里却没有 | 图片归档是独立链;审核条件、archive任务或外部保存可能未完成,有claim无receipt也不会自动重放。先核图片历史、图库各自结果,不把消息补图成功当成归档完成 |
| 下一张图没有沿用衣服或道具 | 需先确认该轮真的准备并提交了视觉资料、助手消息已保存且更新达到 applied;任务 pending/failed 或只送达了图片都不足以证明视觉状态更新 |
| 世界书作者改了设定,聊天仍用旧版 | 先核对 Prompt 绑定是否固定旧 revision,或 latest 解析到了哪一版;内容新版本、向量索引和 Prompt 绑定分别处理 |
| 本轮世界书落选,或没有继续保持上轮条目 | 每个新逻辑轮重新判断资格、触发和预算;固定服务不执行跨轮 sticky/cooldown。普通栏目文本解析不成 JSON 时,条件 state 也是空对象 |
| 页面已有世界书轨迹,但回复没生成或没有遵循 | 轨迹在模型调用前即可出现,且可能只存浏览器;它证明准备过资料,不证明正文成功、保存或生成质量 |
开发核对:入口、Personalization/Go/shadow/Hinos 与失败策略
接入选择与外部实现边界
服务内部准备资料并执行聊天的 closed-loop 路径,由请求选择已配置方案;memoryRuntime 选择记忆服务接法,memorySources 选择要取用的资料。它们不是普通后台协调模型临时选择的专家工具。省略接法时使用 Personalization;省略来源时是空列表,空列表不会自动发现全部记忆,也不能据此概括其他前后 hooks 是否执行。
上游已把输入准备好的 prepared-provider 入口,日记和表格的前后处理由 Chat Service 负责,Harness 在该入口使用空记忆实现避免重复写入。内置默认、某份部署清单和生产当前配置是三个层次;本章列出仓内可配置能力,不据某个方案的开关推定整个项目或线上会话。
几种记忆服务接法,不是同时叠加的四层
| 接法 | 回复前如何取用 | 回复后如何处理 | 本仓库的可确认范围 |
|---|---|---|---|
| Personalization | 按来源加载外部 Agent 配置;处于 live 状态才请求其 beforeChat,收集返回变量,交给模板 | 调用相同 Agent 的 chatResponse,传本轮最终/原始输出、推理和上下文 | 具体摘要、表格解析、生成轮次及保存实现归外部服务。不能套用下方 Axon Go 阈值;未启用的 Agent 会跳过 |
| Axon Go | memory.recall 按用户、会话取 merged_summary、table_prompt;表格结构和版本另留程序使用 |
日记另调摘要模型;表格从 Actor 原始输出解析编辑,再经 Axon 保存 | 编排、触发和保存调用在 Harness;实际存储及表格解析在 Axon |
| Axon shadow | 并行取 Personalization 与 Go,比较结果、字节数和耗时;实际返回 Personalization 的结果 | 只写 Personalization | 用于对比迁移结果,不合并两份记忆,也没有在 Personalization 失败时自动切到 Go 的机制 |
| Hinos | 初始召回只是占位;先渲染角色资料,再将角色 system 与真实 user/assistant 历史交给外部 prepare。返回非空记忆后重新渲染模板 | 用同一 claim 提交本轮 user 和最终 assistant 正文,检查 committed 结果 | 内部如何保存、检索和压缩属于 Hinos 服务,不能补造固定轮数规则;需要专门来源与服务地址 |
Hinos 要求恰好一个 hinosMemory 来源、配置 HINOS_MEMORY_URL,默认服务超时 10 秒。prepare 返回需要有协议标识、claim、记忆、轮次及覆盖进度;真实历史末条必须是当前用户输入,不能把模板里的示范对话当成真实轮次。记忆为空时沿用第一次渲染,非空时重渲染;即便返回非空,也仍取决于模板有没有引用该变量。commit 失败走回复后写入失败策略。
Axon Go 的日记过程直接读取 Agent 参数,不走 Personalization 的 beforeChat/chatResponse,也没有复制其 live 跳过条件。三种普通 MemoryRuntime 的 consolidate 在本仓实现为空方法;接口存在不代表另有统一的定时长期整理任务。
Personalization 的请求超时取 Agent 配置与 hook 上限较小者,服务默认 hook 上限为 2000 毫秒。外部返回变量为空或缺失,并不证明取回了资料。其 afterChat 返回的附加处理结果没有在该记忆适配器中被用于改写本轮正文。
成功、取消和失败的时间点
日记/表格 ingest 在回复生成成功、且没有在这之前被取消时才执行。**这与普通 Agent V2 后台不同:后者已在 Actor 开始时安排,Actor 后来失败或取消不必然取消它。**两者不能都写成“慢通道成功后更新”。
该完整聊天接线的记忆读取策略为 fail_turn;写入策略为 best_effort,普通写入失败记录降级,取消仍传播。尽力写入不等于所有接法都立刻返回:Personalization/Hinos 会等待外部调用;已装配的 Axon Go 则把日记/表格放入 180 秒超时的后台任务。后台任务不是耐久队列,进程关闭也可能中止,不能承诺失败后必定恢复。
依据:记忆服务装配[191]、入口与来源选择[192]、完整轮次读取与写入策略[193]、Personalization[194]、外部 Agent 读取[195]、外部 hook 协议[196]、Go 与 shadow[197]、Hinos 准备与提交[198]、任务取消及超时[199]、Sumi 组合限制[200]、当前世界书可选配置[201]。
源码溯源:保留原第 8 章的补充定位
同一固定基线的其他入口
这些是同章流程的补充代码定位,不代表额外开启了一条记忆链。
内置日记方案[202]、记忆接法选择及后台装配[203]、预组装入口由聊天服务负责记忆[204]、回复完成后的写入调用[205]、日记模型材料解析保存与缓存[206]、shadow只使用与写入legacy[207]、日记触发配置[208]、世界书示例配置[209]、生成与输出检查[210]、输入预算和可靠性约束[211]、组合配置校验[212]、压缩保存权限和角色材料[213]、输入计数回退[214]、保存失败与本轮临时摘要[215]。
历史阅读入口
以下链接保留旧章的 77a1537 阅读定位,仅供追溯;原有机制沿各项固定证据,Compact 与 Prompt 绑定已按本章 fa41d220/9fd897e 的增量替换,不以旧版推定当前行为。
专家的输入与输出[216]、hooks[217]、shadow[218]、Hinos[219]、召回与写入[220]、日记配置与生成判断[221]、用户人设进入本轮上下文[222]。
更新前的固定源码记录(保留历史引用)
下列链接对应更新前的实现,保留用于核对历史记录;现行绑定、Compact、SDK 与图片行为以上文本次定向更新为准。
配置与指纹[223]
覆盖核验与失效[224]
每轮先读记录[225]
有限窗口与编辑测试[226]
Prompt 与 profile 选择[227]
两种 JSON 解析与规范化[228]
profile 专项测试[229]
过滤、JSON 与 token 校验[230]
结果诊断字段[231]
临时采用与保存分离[232]
过滤及完整 length 回包测试[233]
完整对话分组[234]
压缩模型输入[235]
触发与计数[236]
保存条件与临时结果[237]
失败降级[238]
历史覆盖核验[239]
配置校验[240]
示例参数[241]
可靠性示例[242]
后台组合模式[243]
Harness 会话绑定[244]
Demo 固定版本[245]
代码证据 · 245 处
- 读记忆、输入准备与生成 ↗
- 生成后写入与完成版本 ↗
- 当前召回失败策略 ↗
- Actor变量与模板 ↗
- rendered追踪 ↗
- 编译的记忆块 ↗
- Actor真实消息 ↗
- 网关实际请求 ↗
- 后台独立材料 ↗
- 背景任务时点 ↗
- 固定源码 ↗
- 状态存储范围与版本 ↗
- 状态校验 ↗
- 连续性记录构造 ↗
- Director 与提交 ↗
- 后台材料限制 ↗
- 保存重试 ↗
- 并行调度 ↗
- 当前接线 ↗
- 持久字段与锚点 ↗
- 准备与核对 ↗
- 正文采用与提交 ↗
- 保存正文读取与重生成边界 ↗
- 世界字段 ↗
- 叙事字段 ↗
- 世界工具 ↗
- 叙事工具 ↗
- 应用分支 ↗
- 新快照的历史来源 ↗
- 快照字段与存储 ↗
- 请求条件和重放 ↗
- 初始化与历史恢复 ↗
- 解析和保存时点 ↗
- 状态协议 ↗
- 历史与导入 ↗
- 组合限制 ↗
- 图片归档条件与调用 ↗
- 交付与独立归档队列 ↗
- 先保存生成结果 ↗
- 状态与输入字段 ↗
- 变化应用 ↗
- 等消息保存 ↗
- 恢复与提交状态 ↗
- 本地/外部服务及完成条件 ↗
- 请求固定资料与空写入 ↗
- 编译内容、变量与上游回执 ↗
- 字段校验 ↗
- 受开关保护的入口 ↗
- 配置选择 ↗
- 请求采用 ↗
- 普通召回与事件 ↗
- Hinos 分类与 claim ↗
- 来源配置和装配 ↗
- Go 回包与变量转换 ↗
- memory.recall真实字段 ↗
- Personalization完整前后链 ↗
- Hinos prepare和commit ↗
- Hinos再次渲染 ↗
- 动态hook选择与变量准备 ↗
- hook载荷与live条件 ↗
- 上游准备入口责任 ↗
- 日记任务与生成计划 ↗
- 模型、解析和保存 ↗
- 策略与订阅 ↗
- 回读上限与后台任务 ↗
- Axon 日记接口 ↗
- 最终正文与处理前文本分别传入记忆 ↗
- 表格优先读取 rawOutput ↗
- Actor 后处理与 rawText 返回 ↗
- 保存、提炼与日志顺序 ↗
- 表格召回与更新 ↗
- 表格解析和保存接口 ↗
- 读写参数与可选业务校验 ↗
- JSON 数据限制 ↗
- 存储接口 ↗
- Axon 存储范围 ↗
- 调试示例 ↗
- SDK 接入示例 ↗
- 当前后台调度 ↗
- 任务与容量限制 ↗
- 取得与恢复日记覆盖 ↗
- 分开传递开场身份和实际输入 ↗
- 摘要身份 ↗
- 来源未核实的保护 ↗
- 后台实际输入指纹 ↗
- Scenario 协议校验与配置解析 ↗
- 模型与模板要求 ↗
- JSON 输入 ↗
- 文本协议、角色背景与模板 ↗
- 摘要放入 Actor 的位置 ↗
- 顺序递归与完整组 ↗
- 近期范围预规划 ↗
- native v0 配置 ↗
- native v1 配置 ↗
- 覆盖核验及失效 ↗
- 检查点先读、触发与组装 ↗
- 最终保存与超时确认 ↗
- 输出及截断政策 ↗
- 完整输入与准入 ↗
- 摘要预留与继续覆盖 ↗
- 真实摘要超限恢复 ↗
- 角色位置识别 ↗
- 多字段输出 ↗
- 计数质量与来源 ↗
- 精简模型预检 ↗
- 完整恢复与最终预算 ↗
- 检查配置 ↗
- 触发与采用 ↗
- 一次重做 ↗
- 作者离线结果 ↗
- 位置约束与转义 ↗
- 每次渲染采用当前摘要 ↗
- 角色选择与共享时限 ↗
- 允许交接的原因 ↗
- 备用重新计数及失败分支 ↗
- 配置校验 ↗
- 指纹 ↗
- v0生产配置 ↗
- v1生产配置 ↗
- 配置和约束 ↗
- 片段与完整输入渲染 ↗
- 完整检查与算法选择 ↗
- 累计定位算法 ↗
- 最终 Actor 输入及保存条件 ↗
- 回放参数校验 ↗
- Counter 和降级 ↗
- Axon 文本 RPC ↗
- 诊断与回退 ↗
- 最终版回放及限制 ↗
- 自然段筛选与投影 ↗
- 最终采用和保存 ↗
- 完整组规则 ↗
- 自然段门槛与失败处理 ↗
- Shadow 容量 ↗
- 当前估算 ↗
- 实际接线 ↗
- 段落失败保留原文 ↗
- Jev 配置解析 ↗
- 分类模型身份和计数估计 ↗
- 三种边界配置 ↗
- 段落V2及策略指纹 ↗
- 当前恢复实现 ↗
- 普通路径恢复 ↗
- 观测字段 ↗
- 身份与保存保护 ↗
- 用户资料准备 ↗
- 模板变量与渲染 ↗
- 后台独立构造 ↗
- 后台 Persona 限制 ↗
- 适用修改要求 ↗
- 提交任务 ↗
- 有效指令与校验 ↗
- 读取条件及失败 ↗
- 写作输入采用 ↗
- 创建与修订写入 ↗
- 修订版本检查 ↗
- 创建、预览和导入接口 ↗
- 索引装配 ↗
- 检索原文及降级 ↗
- 显式索引生命周期 ↗
- 明确开启的启动重建 ↗
- 派生索引重建与清理 ↗
- 省略 revision ↗
- 逐轮核对及解析 ↗
- 当前服务绑定存储 ↗
- 请求字段与严格契约 ↗
- 状态条件 ↗
- Harness JSON 解析与场景 ↗
- 只读选择服务 ↗
- API 边界 ↗
- 时间与状态方言导入标记 ↗
- 资格过滤与本轮递归 ↗
- RPC 观测 ↗
- 总开关与正文过滤 ↗
- 脱敏及预览 ↗
- 响应字段 ↗
- 逻辑轮缓存与 trace ↗
- 后台独立输入 ↗
- 模型前 trace ↗
- 浏览器诊断保存 ↗
- Demo 正文保存时点 ↗
- 通用 Agent 的宿主输入与结果 ↗
- Slow 默认工具与主提示词 ↗
- 状态文字和历史的消息结构 ↗
- SDK 状态接受与提交 ↗
- FastSlow 读快照与安排 ↗
- JSON读写工具 ↗
- 认证作用域适配 ↗
- 记忆来源类型限制 ↗
- 应用hook配置装配 ↗
- 记忆服务装配 ↗
- 入口与来源选择 ↗
- 完整轮次读取与写入策略 ↗
- Personalization ↗
- 外部 Agent 读取 ↗
- 外部 hook 协议 ↗
- Go 与 shadow ↗
- Hinos 准备与提交 ↗
- 任务取消及超时 ↗
- Sumi 组合限制 ↗
- 当前世界书可选配置 ↗
- 内置日记方案 ↗
- 记忆接法选择及后台装配 ↗
- 预组装入口由聊天服务负责记忆 ↗
- 回复完成后的写入调用 ↗
- 日记模型材料解析保存与缓存 ↗
- shadow只使用与写入legacy ↗
- 日记触发配置 ↗
- 世界书示例配置 ↗
- 生成与输出检查 ↗
- 输入预算和可靠性约束 ↗
- 组合配置校验 ↗
- 压缩保存权限和角色材料 ↗
- 输入计数回退 ↗
- 保存失败与本轮临时摘要 ↗
- 专家的输入与输出 ↗
- hooks ↗
- shadow ↗
- Hinos ↗
- 召回与写入 ↗
- 日记配置与生成判断 ↗
- 用户人设进入本轮上下文 ↗
- 配置与指纹 ↗
- 覆盖核验与失效 ↗
- 每轮先读记录 ↗
- 有限窗口与编辑测试 ↗
- Prompt 与 profile 选择 ↗
- 两种 JSON 解析与规范化 ↗
- profile 专项测试 ↗
- 过滤、JSON 与 token 校验 ↗
- 结果诊断字段 ↗
- 临时采用与保存分离 ↗
- 过滤及完整 length 回包测试 ↗
- 完整对话分组 ↗
- 压缩模型输入 ↗
- 触发与计数 ↗
- 保存条件与临时结果 ↗
- 失败降级 ↗
- 历史覆盖核验 ↗
- 配置校验 ↗
- 示例参数 ↗
- 可靠性示例 ↗
- 后台组合模式 ↗
- Harness 会话绑定 ↗
- Demo 固定版本 ↗
10. 世界书上线前:导入、修订、索引与角色关联
本章回答“运营交什么,以及资料什么时候真的变成可用于聊天的书”。先看顺序:准备文件 → 预览转换结果(未保存)→ 保存出 book_id/revision → 按需建索引 → 给角色/作品的 Prompt ID 关联世界书 → 每轮解析版本、选择原文 → 装入 Actor 输入。这里的 Prompt ID 是外部角色/作品标识,不是岗位提示词的 PromptManager ID。聊天里发生的新事件由消息/剧情状态另存,不会回写作者条目。当前主干按 Prompt 关联逐轮取书,关联修改可以影响已经在聊的会话下一轮。
运营准备数据:交一个 JSON 文件,照这个模板填
从零准备世界书,准备一个独立的 .json 文件即可。 下载下面的模板,把示例书名、关键词和设定正文换成你的内容即可。一份文件是一本世界书;entries 里面的每个对象是一条设定,例如一种物品、一处地点或一条世界规则。
下面是可以保存成文件的完整内容,不是节选。 示例包含一条按需使用的“铜钥匙”资料和一条常驻候选“世界底线”:
{
"name": "北塔设定",
"entries": [
{
"uid": 1,
"comment": "铜钥匙的用途",
"key": ["铜钥匙", "王室钥匙"],
"content": "铜钥匙证明旧王室身份,但不能代替城主手令。进入北塔仍需出示盖有城主印章的手令,手令可到市政厅登记处申请。",
"constant": false
},
{
"uid": 2,
"comment": "世界底线",
"key": [],
"content": "这个世界的魔法不能让死者复生。",
"constant": true
}
]
}
照表修改字段的值,保留左边的英文名称和文件结构。 下面是这份运营模板的填写约定;服务支持的其他格式和技术上的可省略字段见两种 JSON 与真实入口;字段省略后的行为见默认值和实际映射。
| 文件里看到的字段 | 运营填什么 |
|---|---|
name |
整本世界书的名称,例如“北塔设定” |
uid |
这条设定的编号。同一本书内不能重复;新增依次用 3、4、5,修改原条目时保留原编号 |
comment |
便于查找的条目标题,例如“铜钥匙的用途” |
key |
用户可能提到的关键词,例如 ["铜钥匙", "王室钥匙"];只有一个词也写成 ["铜钥匙"]。关键词参与触发,不代表命中后必定入选 |
content |
希望模型参考的完整设定正文。标题和关键词不能代替正文;写“钥匙有什么用途”,不要把这轮尚未发生的“守卫已经开门”写成世界规则 |
constant |
false 表示按需使用;true 表示常驻候选,不必命中关键词。常驻也受资格和预算限制,不保证每轮都装入模型 |
加一条资料: 复制一整个条目对象,放在同一个 entries 列表里,换一个不重复的 uid,再改标题、关键词、正文和常驻开关。两条对象之间保留英文逗号;最后一条后面不加逗号。上面的两条就是排版示范。
保存前只检查这四件事:
- 每条都有实际设定正文,编号没有重复;不把整本故事塞成一条,也不填尚未确认的剧情结果。
- 关键词保留方括号;
true/false不加引号。字段名使用英文双引号,正文里需要引号时可用中文引号“”。 - 用纯文本方式、UTF-8 编码保存为例如
beita-worldbook.json。如果从页面复制,只复制最外层{到},不带代码框标记或说明文字;JSON 里不加注释,正文换行可写成\n。 - 交付的是
.json文件,不是.json.txt,也不是只改后缀的 Word、Excel、PDF 或普通 PNG 图片。
交给谁: 将文件交给负责世界书管理接入的开发或管理员,同时写明“用于哪个角色/业务,是新建书还是修改哪本已有书”。例如:“新建《北塔设定》,用于艾琳的北塔 RP。”当前聊天 Demo 没有上传入口,需要管理接入方完成导入及角色世界书关联,文件做好并不等于聊天已启用。
修改已有书时: 先向管理员取得需要修订版本的完整文件、书籍编号和版本,按管理员确认的格式在这份底稿上修改。保留需要继续使用的旧条目及其原编号,交回完整新版;不要用上面两条示例覆盖旧书,也不能只交新增几条。
这个模板走“外部文件导入”,使用 uid / key;后文给开发看的原生创建接口使用 id / keys。运营按上面这一份准备即可,不必把两套字段混起来。模板字段的实际映射[1]
用户对艾琳说:“我把铜钥匙递给北塔守卫,请他开门。” 假设这名守卫已经在对话中出现,作者希望艾琳演绎这段场景时遵循“铜钥匙证明旧王室身份,但不能代替城主手令”。作者必须先把规则变成一份能被会话读取的资料;用户聊天时不需要重新粘贴规则。
世界书保存提前设好的世界规则;聊天历史和持续状态记录这一局已经发生的事。 钥匙有什么含义可以写在书里;守卫这轮是否接过钥匙、是否开门,要由实际对话建立,不能由这条静态资料替剧情决定。下面沿用同一教学场景,走完准备、选择、入模和页面核对;例子不是线上实测。
作者写的句子,怎样变成一条可用资料?
作者把这条规则拆成“正文+什么时候可能用到它”,例如外部世界书里的一条记录可以写成下面这样。以下只解释单条记录的转换;运营交付请使用本章开头的完整模板。
{
"uid": 1,
"key": ["铜钥匙"],
"content": "铜钥匙证明旧王室身份,但不能代替城主手令。"
}
导入器把它转换成服务内部的条目:编号 uid:1 变成字符串 id:"1",关键词 key 变成 keys,正文留在 content。本例未额外配置,所以它是启用的动态条目,默认供 Actor 使用、放在人设前;既不自动常驻,也不自动成为必需条目。作者若需要必需、条件、依赖等内部规则,要在预览后的内部结构中明确补齐,再保存;不能以为外部文件里写了同名字段就都生效。实际字段转换[2]
当前能接收独立世界书 JSON、CCv2/CCv3 角色卡里的世界书,以及带对应角色卡元数据的 PNG。角色卡只取世界书部分,不顺便新建艾琳的角色卡;PNG 读取内嵌文字数据,不识别画面上的字。没有任意 TXT、PDF 或普通图片 OCR 转世界书的入口。接入程序也可以直接按内部结构创建书,绕过外部文件转换。文件解析入口[3]
从“导入成功”到“艾琳下一轮能用”,中间还有什么?
| 谁做什么 | 得到的结果 | 下一步怎样使用 |
|---|---|---|
| 作者或接入程序提交预览 | 转换后的内部书籍和导入报告:哪些条目有效、哪些依赖不支持的脚本能力 | 检查正文和字段;预览不落库,也还没有改变聊天 |
| 管理接入方确认并保存 | 获得一本书的 ID 和不可变版本,例如《北塔设定》第 1 版 | 后续读取按书籍 ID+版本定位原文;允许不经过预览、直接解析并保存文件 |
| 需要向量检索时,为指定版本建索引 | 该 revision 与 embedding 版本的检索副本,ready 才表示构建完成 | rules 不需要向量;hybrid 的向量召回使用对应版本,每轮 select 不自动重建 |
| 管理接入方给艾琳的业务对象 ID 保存关联 | 例如“艾琳使用《北塔设定》,固定第 1 版”或“跟随最新版本” | 关联保存在世界书服务数据库;创建、更新、清空都独立于聊天消息 |
| 用户发送下一条消息 | Harness 检查会话身份,再以本次 promptId 作为 entity_id,解析当前启用的书籍与具体版本 | 本轮所有选择及内部重试都使用这一份版本快照;下一轮重新解析 |
| 世界书程序返回条目,Harness 装入 Actor | 入选原文 blocks、位置和本轮诊断 | Actor 写本轮回复;后台 Planner 不自动收到这批原文 |
**交接时要留下两种不同的编号。**条目的 uid:1 只标识书内“铜钥匙”这一条;保存接口给出的 book_id 标识整本书,revision 标识这一版。给角色配置关联时用书籍 ID,不能拿条目编号或文件名代替。
**关联存的是“哪个角色使用哪些书”,不复制书正文,也不再把书版本永久钉在会话上。**例如管理员给 entity_id=character:ailin 保存下面的配置。书籍 ID 是教学编号;tenant_id 与 entity_id 放在接口 query,不放入这个 JSON。tenant_id 是业务分配的资料分组编号,例如 branches-production;同一角色的读写必须使用同一组编号。它是必填数据定位字段,不是登录身份:
{
"bindings": [
{
"book_id": "11111111-1111-4111-8111-111111111111",
"revision": null,
"position": 0,
"enabled": true
}
]
}
这表示“艾琳启用《北塔设定》,每一轮跟随它当时的最新版本”。若 revision 改为 1,就固定读第 1 版。position 是多本书解析时的排序,不是条目放到 Prompt 哪个位置;条目投放位置另由 position: before_char 等字段控制。
| 接口/调用者 | 准备什么 | 返回或保存什么 | 什么时候用 |
|---|---|---|---|
管理端 GET /v1/entity-bindings |
tenant_id+entity_id |
已保存的 bindings,包含 book_id、revision、position、enabled;无记录返回空数组 |
展示管理员当前配置,包括停用项 |
管理端 PUT /v1/entity-bindings |
同样的资料分组/业务对象,以及完整 bindings 数组 |
原子替换该角色全部关联;返回保存后的列表,写入 entity_worldbook_bindings 表 |
点击管理保存时;传 [] 清空关联,不是删书,也不删聊天 |
Harness 经 Axon 调 worldbook.conversation.check |
tenant、Prompt、会话、场景,以及可信入口传来的用户身份 | 核对返回身份四项与本次请求一致;不在会话上保存书籍或 revision | 新建/读取会话及每轮准备时,身份不符就失败 |
Harness 经 Axon 调 worldbook.bindings.resolve |
资料分组+entity_id(现有 RP 由 promptId 提供);服务对应 GET /v1/entity-bindings/resolve |
{tenant_id,entity_id,books:[{book_id,revision}]},只含启用项,revision 已是具体正整数 |
每个逻辑轮解析一次;再把这份 books 交给 worldbook.select |
10/9 的新接口把关联对象统一称为 Entity,也就是业务自己的角色、故事或作品编号。比如 character:123 与 story:123 是两份不同关联;宿主负责确定名称、跨类型唯一性和编辑权限。服务不会检查角色/故事是否存在,也没有内置类型枚举。旧 Prompt 接口本来就接受业务 ID,因此这不是首次允许故事复用世界书,而是把调用合同通用化。
新路径是 GET/PUT /v1/entity-bindings 和 GET /v1/entity-bindings/resolve。旧的三个 /v1/prompt-bindings 路由仍保留兼容。新旧请求都可传 entity_id 或 prompt_id,至少一个;两个同时传必须相同,否则 422。新路径响应 entity_id,旧路径响应 prompt_id。tenant_id 必填且无默认值;这些 ID 为 1–200 字符,不接受首尾空格。请求正文仍只有上面的完整 bindings 列表。最多 20 本、不可重复、固定/最新版本、原子替换与空数组清空规则没有改变。
新版 Harness 保留 worldbook.conversation.check 和 worldbook.bindings.resolve 两个 RPC 名,将请求及响应中的对象字段改为 entity_id;当前 RP 接线仍把 context.promptId 作为 entity_id,并没有自动把每个会话换成任意故事 ID。自行接入的业务可以定义自己的对象编号,再使用独立 HTTP 服务或 SDK 客户端。Harness 新接入文档曾称不保留旧别名,但服务固定源码明确保留,兼容性按实际路由说明。
数据库还需要 007_entity_bindings.sql:把旧关联表、prompt_id 字段和约束改名,保留原记录。生产保留 AUTO_MIGRATE=false,需协调 Service、Axon、Harness/管理端及手工迁移,不能仅升级 SDK 就认为数据库已经完成。本次补核到 Entity 版本 ad38dce 已于 10/09 10:59 成功生产部署,但没有独立读取 007 迁移、Axon 配套和真实关联请求结果;部署与迁移分别记录。生产部署。
兼容路由与 ID 校验[4] · 关联保存与解析[5] · 007 迁移[6] · 现有 RP 的 ID 来源[7]
**什么时候算保存成功:**世界书服务先验证全部关联,包括停用项的书和指定版本都属于该 tenant;再在事务里串行替换整组记录,返回成功后才算配置已保存。最多 20 本,不可重复 ID;并发保存按事务锁串行,最后成功写入的一组生效。它不是条目合并接口,修改一项也需交完整希望保留的列表。Axon 转发实现不在这两个仓库里,不能把接口合同当成已完成线上联调。
**本轮取出来的是版本清单,之后才是原文。**服务解析时用一次数据库查询同时取关联和最新书头;无启用关联返回 books:[],Harness 不创建 WorldbookTurn,不请求 select、不执行世界书装配,保留原产品的历史和预算处理。每轮身份检查和 resolve 仍会执行,因此不会把空关联永久缓存。存在明确关联但书/版本失效,整次 resolve 返回 409 binding_book_not_found,不会只拿正常的几本继续;身份不符、解析结构无效或 RPC 失败也会上抛,不能当“没有书”。当前空绑定入口[8] · 当前失效关联校验[9]
关联接口与契约[10] · 事务保存与版本解析[11] · 会话检查与逐轮解析[12] · 空关联与本轮缓存[13]
**保存原文、建索引、保存角色关联,是三个分别生效的动作。**书已保存不代表向量可用,索引 ready 不代表角色已经关联到它,更不代表某条原文已进入本轮模型;仍要经过本轮选择及位置和总预算检查。聊天用的是选中条目的正文,不是向量本身。配置由谁改。
作者改了规则,已经在聊的用户何时读到?
假设作者给第 2 版新增“城主手令只在签发当日有效”。修订要提交希望保留的整本书,不是只交新增一句让服务合并;旧第 1 版仍可读,已经生成的聊天不会改写。
| 艾琳的关联配置 | 下一轮会读什么 | 正在执行的这一轮 |
|---|---|---|
固定 revision:1 |
仍取第 1 版;管理员改为第 2 版后,后续新轮次才改读第 2 版 | 使用开始时已解析的版本与选择结果 |
revision:null,跟随最新 |
第 2 版发布成功后,下一轮 resolve 得到第 2 版 | 不在生成中途追随书头变化 |
管理员将一项 enabled:false,或保存空列表 |
下一轮不再从停用的书取条目;全部清空时可正常无世界书聊天 | 已经解析的本轮不会因此撤回已选材料 |
| 所关联的书/明确版本已经失效 | 解析报错,不能把失败静默当作空列表 | 已有聊天原文仍保留;失败不倒改过去的回复 |
第 2 版若需要向量检索,应为它准备对应索引;第 1 版 ready 不代表第 2 版 ready。重复上传同一个源文件仍可能命中最初 revision 1 的去重记录,它不是修改关联或发布修订的替代操作。改变书籍关联也不会自动重置已有剧情状态;若新规则与旧剧情冲突,要按跨来源材料冲突检查。
**旧行为的时间边界:**9 月 18 日前版 Wiki 使用 Harness 3b99f4c,当时是 worldbook.conversation.pin/get 与固定书 Demo;随后 fa41d220 改成 Prompt 逐轮关联。本次四章继续按 9 月 22 日固定 a4f5bb83 / fafdb8d 补入通用接线、空绑定直通、Selection v3 和正文观测。旧浏览器关联/pin 不会被新服务自动导入,需要管理接入方明确迁移。未变化字段保留原固定源码依据,新增行为使用最新固定源码。每轮入口[14]
展开:两种 JSON 的区别、必填项与真实 API 入口
可接收的文件容器
| 你手上的资料 | 当前导入器怎样处理 |
|---|---|
| 独立世界书 JSON | 读取顶层 entries;接受条目数组,也接受以编号为键的条目对象 |
| CCv2/CCv3 角色卡 JSON | 只取 data.character_book;不会把角色介绍、开场白顺便建成角色卡 |
| 带角色卡元数据的 PNG | 从图片内嵌的 chara/ccv3 数据取世界书;不是识别图片上的文字,普通 PNG 不行 |
| 接入方按内部结构写的 JSON | 走原生创建接口,直接校验内部字段;与“把外部文件上传给导入器”是两条入口 |
格式按文件内容判断,不靠修改后缀。独立世界书 entries 可以是数组,也可以是以编号为键的对象;对象外层的键不会自动变成可靠的内部条目 ID。
既有完整文件示例与原生接口示例
下面两份格式示例保留此前核对的字段和正文值,其中手令使用“摄政官”称谓;主阅读层的艾琳教学案例使用“城主手令”。这些都是说明格式的虚构文案,不是生产书籍。第一份是完整外部文件:
{
"name": "北塔设定",
"entries": [
{
"uid": 1,
"key": ["铜钥匙"],
"content": "铜钥匙证明旧王室身份,但不能代替摄政官的书面命令。"
}
]
}
外部格式负责兼容已有世界书文件,内部格式负责明确表达本服务的规则。 上面的 uid / key 是外部写法。下面是同一条资料走原生 POST /v1/books 时的最小实用请求体;它不是把外部文件原样换个接口发送:
{
"name": "北塔设定",
"entries": [
{
"id": "copper-key",
"content": "铜钥匙证明旧王室身份,但不能代替摄政官的书面命令。",
"keys": ["铜钥匙"]
}
]
}
原生结构: 书名 name 必填,1—300 字符;entries 可省略,默认空数组。条目 content 必须提供字符串,但允许空串,最长 200,000 字符。id 可以省略,书级校验会按顺序补 entry-0、entry-1;显式提供时必须是 1—150 字符的字符串。title、description、metadata 等可选。为了跨修订稳定识别同一条资料,接入方应主动维护 ID,不能依赖重排后仍相同的自动编号。
外部结构: 独立 JSON 顶层要有 entries;书名缺失时用文件名。角色卡要求 spec 是 chara_card_v2 或 chara_card_v3,并且 data.character_book 是对象;书名优先用世界书名,其次角色名,最后文件名。条目正文未提供时导入器补空串,关键词未提供时补空数组;这些空条目可以通过格式校验,不能把“导入成功”当作内容质量合格。
| 目的 | 服务端真实入口 | 输入/结果 |
|---|---|---|
| 只预览外部文件 | POST /v1/imports/preview |
multipart 字段 file;返回 book + import_report,不保存 |
| 保存外部文件 | POST /v1/imports/files |
multipart 字段 files,一次 1—10 个;先全部解析,再整批保存 |
| 指定租户保存外部文件(新main) | POST /v1/admin/imports/files?tenant_id=... |
同样的multipart files与批次解析/原子保存;可信管理接入方明确租户并负责写入授权 |
| 新建一本原生书 | POST /v1/books |
上面的内部书籍 JSON;新书从 revision 1 开始 |
| 批量新建原生书 | POST /v1/imports |
{ "books": [...] },一次 1—10 本 |
| 修改已有书 | POST /v1/books/{book_id}/revisions |
完整内部书籍结构,再加 expected_revision |
| 显式建索引 | POST /v1/books/{book_id}/index |
可指定 revision、force;查询状态用同路径 GET |
| 指定租户建索引(新main) | POST /v1/admin/books/{book_id}/index?tenant_id=... |
JSON {revision,force:false};构建选定租户的书版本,调用方负责权限 |
预览返回的 book 已经是内部结构,可以审核后用原生创建或修订接口保存。这种保存走的是原生入口,不会继承文件上传入口的原始文件哈希去重。 表内管理接口都存在于 Worldbook Service;Harness Demo 会拒绝 preview,并把 RPC 限制为 book.get / book.entries / index.get,因此不能把后端能力当成当前页面已有按钮。内部契约[15] · 服务路由[16] · 预览不保存及原生保存用例[17] · Demo 拒绝写操作[18]
展开:字段分别控制什么,省略后会怎样
以下是内部 Entry 的业务分组;外部文件只映射其中一部分。不是要求作者每条资料都填满。
| 作者要控制的事情 | 内部字段 | 原生入口省略时 |
|---|---|---|
| 这张资料卡是谁、写什么 | id / title / content / kind |
自动 ID;标题空;正文必填;kind 为 lore |
| 是否开放、是否常驻、是否必须装下 | enabled / constant / required |
true / false / false;必需仍须先符合资格 |
| 聊到什么时尝试选它 | keys / secondary_keys / selective / logic |
两组关键词为空;selective=false;logic=and_any |
| 如何匹配、看多远、概率多少 | case_sensitive / match_whole_words / scan_depth / probability |
不区分大小写、不要求整词、沿用请求扫描深度、100% |
| 能否靠其他条目继续召回 | exclude_recursion / prevent_recursion |
原生都为 true;外部导入省略时都为 false |
| 有限预算里优先谁、资料放哪 | priority / order / position / depth / role / outlet_name |
优先级和顺序 0;人设前;深度 0;system;无 outlet |
| 给谁看、何时才有资格 | audience / conditions |
audience=[actor];无条件。条件是 path、op(默认 eq)、value |
| 必须一起带谁、与谁互斥 | requires / conflict_key |
无依赖、无冲突组;这些是选择约束,不会替作者改正文 |
| 原文件从哪来、依赖什么运行能力 | source / runtime_requirements |
原生为空;导入器会保存来源和识别结果 |
外部常用映射是:id 优先于 uid;comment 优先于 name 作为条目标题;keys 优先于 key;secondary_keys 优先于 keysecondary;enabled 优先于反向的 disable;insertion_order 优先于 order。ST 独立条目含 key 或 uid 时,会同时读取顶层扩展字段,同名 extensions 内字段优先。它不是把外部对象所有字段无条件搬成内部配置。
尤其是 required / priority / audience / conditions / requires / conflict_key:当前外部导入器没有把这些同名字段映射到内部规则。 即使它们还在 source.raw 里,也不代表生效。需要这些业务限制时,应在预览后的内部 book.entries 上明确补齐,再经原生创建或完整修订接口保存。条目 kind 和 runtime_requirements 也由导入器按内容识别,不直接照抄外部同名值。完整字段、默认值与校验[19] · 实际映射清单[20]
位置在外部与内部也有不同写法。内部用八个字符串名称;ST 数字映射为:0 人设前、1 人设后、2 作者注释顶部、3 作者注释底部、4 at_depth、5 示例前、6 示例后、7 outlet。outlet 必须附合法名称。CC 的旧 position="after_char" 另有兼容分支。保存了位置,只表示作者意图;这一轮宿主有无对应插入点,仍在选择时检查。
展开:哪些会拒绝、哪些只保留原文、哪些不会执行
| 遇到的问题 | 当前结果 |
|---|---|
原生结构出现未知字段,例如把 key 当作内部 keys |
契约禁止额外字段,拒绝请求;不能靠拼错字段名扩展行为 |
| 外部 JSON 重复字段名、NaN/Infinity、根不是对象、条目不是对象、关键词不是字符串数组 | 导入失败,返回 invalid_import;不是保留前一项或自动修好 |
| 超长正文/标题/关键词、越界概率或深度、非法内部枚举等 | 规范化后的模型校验失败;不是把超长文本截短后保存 |
| 同版重复条目 ID、依赖指向不存在的 ID、自依赖或循环依赖 | 拒绝整本内部版本;外部导入的重复 ID 也会失败 |
| 外部文件中的 EJS、前端脚本、MVU 状态更新、NPC 生成协议、不支持的宏等 | 保留条目原文,标记 runtime_requirements;当前选择器排除这些需要额外运行时的资料 |
| sticky/cooldown/delay、分组、延迟递归、特定生成类型触发、忽略预算等源运行逻辑 | 识别为不支持的运行要求;不会因为上传成功就执行 |
| 未映射的普通扩展字段 | 条目原对象可留在 source.raw 中;不是自动转成规则,也不保证逐字段产生警告 |
“保留”有明确范围。 每个规范化条目的 source.raw 保留该原始条目对象,书籍配置放入 metadata;正文里的脚本只是字符串。源文件的全局 ST 设置也不会因留在 metadata 里就自动接管本轮选择参数。角色卡中的角色介绍、开场白等被忽略,不会保存整张角色卡作可运行角色资产。服务也没有把原 PNG 图片和完整原文件字节存成可原样下载的附件。因此这里不承诺完整往返导出、全部扩展兼容或原文件备份。
这些校验检查结构、边界和依赖,不会理解故事后替作者判断两条设定是否矛盾。一条写“铜钥匙可以开门”、另一条写“铜钥匙不能开门”,不能指望导入器替你调和;conflict_key 是后续选择时的互斥标记,也不负责改写原文。
不支持的位置/选择逻辑可能先回退为默认值,同时标记运行要求;这类条目不应被理解为“已经安全转换成等价行为”。当前导入版本为 st-inert-v2。报告包含总条数、启用数、启用且常驻数、带运行要求的条目数、要求分类和 warnings;runtime_blocked_count 也会统计被关闭但仍带运行要求的条目,不等于本轮实际漏掉的条数。
PNG 读取的是内嵌数据。 支持相应 tEXt/zTXt/iTXt 文本块,校验 CRC、Base64、JSON 和解压大小;截断图片、重复同名角色元数据块等会失败。若同时有 ccv3 与 chara,优先取 ccv3;比较到相关内容不一致时报告 dual_metadata_differs_ccv3_selected,不是两套条目混合导入。解析和运行要求识别[21] · 非法数据及原文保留测试[22]
展开:ID、重复上传、冲突和“整批成功/整批失败”
条目 ID 只需在同一本书的同一修订里唯一。 外部导入依次取条目 id、uid、从 0 开始的排列序号,转成字符串;不把外层 entries 对象的键当作可靠条目 ID。整数 1 与字符串 "1" 会变成同一个 ID,放在一版里会冲突;布尔值不能作外部 UID。书籍 ID 则由服务新建 UUID,与作者写的条目 ID 不同。
重复上传按同一租户内的原始文件字节 SHA-256 去重,不按“看起来是不是同一本书”。 相同字节再次上传会返回原 book_id、deduplicated=true,并明确指向最初导入的 revision 1;即使这本书后来已经编辑到第 3 版,也不是返回第 3 版,更不会替它创建第 4 版。只改 JSON 空格也会改变文件哈希,因此语义相同不保证去重;文件内容改了再上传,通常是另建一本书,不是更新原书。
原生创建没有这个文件哈希。创建/批量导入可另传 Idempotency-Key:同一租户、同一 key、同一请求指纹会重放上次结果;同一 key 换了内容会报 409 idempotency_conflict。文件去重与请求幂等是两层不同机制,也都不是内容合并器;没有文件哈希、也没用同一个幂等 key 的重复原生创建,可以产生新书。
批量文件导入先把所有文件解析成功,再进一个数据库事务保存全部书籍。 其中一份损坏,就不会先把前面的好文件存进去;保存事务失败也整体回滚。原生批量创建同样先校验整个请求,再用同一保存事务。预览只有单文件解析,没有保存可回滚。批量保存、去重与幂等[23] · 原子批次和重复上传用例[24]
展开:完整修订、容量限制、索引与八位置升级
修订提交的是整本快照,不是增量补丁。 例如修改铜钥匙,提交第 2 版时仍要带上希望保留的北塔门禁、世界底线等条目;漏掉的条目不会从第 1 版自动补回来。省略 entries 会得到空条目列表,省略其他可选书籍字段也会使用其默认值。expected_revision 是“我基于哪一版编辑”:服务锁住这本书核对当前版,相符才保存下一版;已被别人更新则报 409 revision_conflict,要求重新读取处理冲突。旧 revision 不改,旧版仍可读。完整修订和并发检查[25]
默认容量: 每本最多 5000 条;一次文件/原生批量请求最多 10 份/本。单文件上传默认 16 MiB,批次文件合计默认 48 MiB;HTTP 请求体还另受默认 48 MiB 限制,包含 multipart 开销。解析后的 JSON/PNG 元数据另有 24 MiB 上限。上传、批次与请求体上限来自服务设置,可配置;条目模型和导入器还有自己的数量、长度限制,不能只看上传大小。容量设置[26] · 文件与整请求限制[27]
索引是原文的检索副本。 服务按租户、书籍、revision和embedding version构建,经历building→ready/failed;ready且未要求force时复用。显式index请求同步等待构建完成;原文与向量同存PostgreSQL。rules和词法无需向量,hybrid只在已配置并建好相应版本索引时取得向量结果;特定失败可显式降级词法。索引构建[28]
新版main的向量后端仍默认关闭。 vector_backend=none时不实例化嵌入服务;启用pgvector后,默认embedding_backend为openai、模型为经Kaon Router调用的aliyun-2/qwen3.7-text-embedding-flash,使用1024维及L2归一化,需配置服务专用Key。旧FastEmbed仍可显式选。路由与profile组成embedding版本,旧MiniLM索引不能直接作为新Qwen索引用;更换这些语义需重建,不改变书原文和revision。默认设置[29] · 装配[30] · 嵌入版本[31]
索引有两个明确入口,都不是每轮自动触发。 除普通/admin index API,新版还有默认false的embedding_reset_minilm_on_start开关。显式开启后后台重建已有revision,核验新索引后才提交旧MiniLM衍生数据的删除;失败/取消不修改原文,已完成的新索引可供恢复复用。/health/ready即使HTTP200,也要看embedding_reset.state确认迁移是否完成。这是受控迁移,不是聊天进行一次就重索引。启动开关[32] · 迁移处理[33] · 就绪与迁移状态[34]
升级代码不会让旧书自动得到八种位置。 如果旧导入器曾把“示例前”回退为“人设前”,升级服务不会把旧记录猜回原位置。应重新预览原文件、检查规范化结果,再对原书发布完整新 revision;需要向量检索时为新版建索引,最后检查角色关联:固定版本时改到新版,跟随最新时确认下一轮解析出的版本。重复导入同文件仍可能命中旧 revision 1 的去重结果,不能拿它代替迁移。位置升级说明[35] · Harness 消费方升级要求[36]
代码证据 · 36 处
- 模板字段的实际映射 ↗
- 实际字段转换 ↗
- 文件解析入口 ↗
- 兼容路由与 ID 校验 ↗
- 关联保存与解析 ↗
- 007 迁移 ↗
- 现有 RP 的 ID 来源 ↗
- 当前空绑定入口 ↗
- 当前失效关联校验 ↗
- 关联接口与契约 ↗
- 事务保存与版本解析 ↗
- 会话检查与逐轮解析 ↗
- 空关联与本轮缓存 ↗
- 每轮入口 ↗
- 内部契约 ↗
- 服务路由 ↗
- 预览不保存及原生保存用例 ↗
- Demo 拒绝写操作 ↗
- 完整字段、默认值与校验 ↗
- 实际映射清单 ↗
- 解析和运行要求识别 ↗
- 非法数据及原文保留测试 ↗
- 批量保存、去重与幂等 ↗
- 原子批次和重复上传用例 ↗
- 完整修订和并发检查 ↗
- 容量设置 ↗
- 文件与整请求限制 ↗
- 索引构建 ↗
- 默认设置 ↗
- 装配 ↗
- 嵌入版本 ↗
- 启动开关 ↗
- 迁移处理 ↗
- 就绪与迁移状态 ↗
- 位置升级说明 ↗
- Harness 消费方升级要求 ↗
11. 世界书每轮怎样选择:常驻、动态与必需
现在艾琳的 Prompt 已关联《北塔设定》。Harness 在这一轮解析到它的明确版本。用户发出:“我把铜钥匙递给北塔守卫,请他开门。” 在这个已启用世界书的场景,Harness 先准备本轮资料,之后 Actor 才开始写回复。每个新的用户输入都会重新选;不等累计 X 轮,也不需要慢协调器先批准查书。
Harness 把什么交给谁?
Harness 核对会话身份、解析 Prompt 当前启用的书籍版本,再把本轮材料通过 Axon 的 worldbook.select 交给世界书服务。是否能带旧状态,由具体产品接线决定,见下表后的区别。世界书服务运行选择程序;不是让 Actor 或 Planner 先通读整本书再拍板。这里每轮变化的是“取哪些已保存条目”,没有安装新工具或执行条目里的脚本;脚本等兼容范围见不会执行的源功能。
| 本轮交出的材料 | 北塔例子 | 选择时用来做什么 |
|---|---|---|
| 本轮解析得到的书籍和具体版本 | 《北塔设定》第 1 版;若关联跟随最新,下一轮可能解析为第 2 版 | 限定本轮条目来源;同轮内部重试复用,版本不会中途漂移 |
| 用户本轮原始输入 | “那把钥匙还能开门吗?” | 原样作为 query,最多 8000 字符;不再拼接旧状态的公开场景 |
| 近期聊天历史 | 艾琳刚说“北塔守卫正在检查铜钥匙” | 给关键词提供作者指定的扫描窗口;hybrid另从最近两条非空user/assistant消息补充检索线索 |
| 能解析成字段的旧状态 | 某事件是否发生等条件 | 检查条目设置的状态条件;不是把全部状态塞进搜索词 |
| 场景策略、预算、模板能放的位置 | rules 或 hybrid、世界书预算、可用位置 | 决定怎样找、装多少、在哪里放 |
角色卡全文没有交给世界书当搜索词。请求另带角色/用户名称用于正文变量替换,Actor 通过自己的模板采用角色资料。当前 main #223 只发送原始本轮输入作 query;旧状态继续只作条件数据,不能解析为 JSON 对象就得到空条件对象,不再从 Current scene 文字拼检索词。当前请求构造[1]
旧版固定依据(新行为以上文为准):本轮选择请求[2]
不同产品送来的状态不能混称为“已有世界状态”。普通 Agent V2 读取轮初 Agentic 状态,只有 JSON.parse(state.state) 成功且得到对象时才传给服务作条件判断;普通栏目文本解析失败就传 {}。普通 RP/Compact/前台工具循环的基础适配器、Story 和 Sumi 仍未把各自剧情快照自动映射成条件字段。要判断 quest.started 或 keyHolder,接入方必须实际提供这些字段;新的短历史检索不会替业务完成这项映射。当前状态解析[3]
旧版固定依据(新行为以上文为准):解析与请求[4] · V2读取[5] · 基础适配器[6] · Story调用基础准备[7] · Sumi空状态[8]
同一本书里的四条资料,这一轮怎样取舍?
先用纯规则 rules 讲清楚。假设条目都启用、位置可用、条件满足,前三条能装下,最近扫描窗口也没谈南港:
| 作者提前写的资料 | 怎样触发 | 本例最终结果 |
|---|---|---|
| 死亡不能被魔法逆转 | 作者标为常驻 | 本轮没提死亡也能参选;本例预算足够,所以入选 |
| 北塔午夜后开门需要城主手令 | 动态条目,关键词“北塔” | 用户本轮提到北塔,入选 |
| 铜钥匙证明旧王室身份,但不能代替城主手令 | 动态条目,关键词“铜钥匙” | 用户本轮提到铜钥匙,入选 |
| 南港每周三有商船开往群岛 | 动态条目,关键词“南港” | 本例扫描窗口没命中,落选 |
当前标准世界书场景实际配置的是 hybrid。它除了规则触发,还按当前搜索问题做词法和向量相关性排名。因此用户说“我拿出那把王室旧钥匙”,即使没直接命中“铜钥匙”,也可能通过相关性进入候选;不是保证同义表达一定命中。反过来,“没匹配关键词”也不能单独解释 hybrid 中每一条落选。召回候选之后仍要过资格和预算关。场景策略[9] · 混合召回[10]
常驻、动态、必需,差别发生在哪一步?
条件只能判断这次真正传来的字段。服务不会自行把聊天或剧情笔记变成条件数据;普通 Agentic 的栏目文本无法解析为 JSON 时,选择请求的 state 就是 {}。所以笔记里写“钥匙已归还”,不等于选择器已得到 keyReturned=true;当前实现也不再把公开场景文字加入 query。当前解析[11]
旧版固定依据(新行为以上文为准):实际状态解析[12] · 条件只读判断[13]
先检查这条资料有没有资格,再决定哪些候选装得下。 禁用、受众不符、条件不满足、运行要求不支持、概率未通过或正文不可用,都不会因为标了常驻/必需而被豁免;作者要求的位置也必须在这轮模板中可用。
| 配置 | 本轮如何参选 | 预算紧张时会怎样 |
|---|---|---|
常驻 constant=true |
免关键词参选;适合简短、反复需要的底线 | 普通常驻仍可能落选,不保证每次出现在模型输入中 |
| 动态条目 | 关键词、hybrid 相关性,或允许的递归触发 | 命中只是候选,仍可能因预算、冲突或依赖无法满足而落选 |
必需 required=true |
通过资格检查后,免关键词且优先装配 | 合格的必需条目及其依赖包无法完整装下时会报错,不是悄悄删掉,也不是无上限硬塞 |
**常驻不表示命中后连续保留若干轮。**本次核对的服务没有跨轮持续、冷却或延迟的进度提交;导入器识别 sticky/cooldown/delay 后会标为不支持的运行要求,选择时排除相应条目。选择中的递归次数也只发生在本次选择内部。导入运行要求[14] · 选择资格与轮内递归[15]
常驻和必需可以同时标在同一条上,它们不是三个分开的资料库。服务先放合格的必需包,再考虑可选常驻和动态候选;依赖条目要作为整包处理,正文不会截半凑预算,同一冲突组也不能随意全选。 必需不是只在超预算时才会失败: 如果它必须携带的依赖没有资格,或必需包与已经选中的条目/包内条目使用同一冲突标记,本轮选择也会报错。可选候选遇到这些问题则落选。例如铜钥匙条目要求同时带上“北塔门禁规则”,但作者把这条规则标为禁用:普通铜钥匙候选一起落选;若铜钥匙是已通过资格检查的必需条目,则不能默默缺少门禁继续。这里按作者填写的依赖和冲突标记判断,不是程序理解正文后自动发现矛盾。依赖与冲突处理[16] · 可选落选与必需报错[17]
以当前场景的 2400 tokens 为例,服务默认给“由可选常驻候选发起的包”设置累计新增成本上限 35%,即 840 tokens。这只是上限,不是提前占住 840 个空位;required 包不计入这笔常驻账,共享依赖不重复收费。因此可能出现“世界底线是常驻,却因预算没有入选”,不能只看 constant 开关就承诺一直存在。完整角色输入还有另一道预算检查,下一节说明。资格与最终选择[18]
选择完成后,Harness 拿到了什么?
正常结果是一组 blocks:每条带入选的正文、书籍版本、条目身份和插入位置;还有选择/落选原因、使用预算、降级说明等诊断。北塔例子里,下一步交给 Harness 的是前三条的实际文字,不是仅三个标题,也不是整本书。blocks[].content 是待放入模型的正文,position/depth/role 决定怎样放;decisions 和 degraded 则交给排查使用,不作为剧情指令执行。返回字段与用途逐项对照这几份结果。
如果有绑定但没有合格或相关条目,选择器正常返回空列表;Prompt 无启用关联则更早跳过世界书对象、选择和位置装配,保留原产品链路,Demo 仍允许聊天。**空结果与读取失败是两件事。**成功查到“没有已保存状态”时 V2 可用保守初始状态;会话身份检查、关联解析、状态读取或选择 RPC 失败则向上传递,不能统一改成“忽略世界书继续聊”。失效的明确书籍关联报错,不静默忽略。空关联跳过入口[19] · 解析校验[20]
hybrid 的向量步骤遇到可识别的领域错误时,可以明确记录降级并继续词法排名;这不会把必需依赖不可用、必需冲突、必需包超限或一般 RPC 失败都变成成功。正常零条、降级后选中、准备/选择失败,是三种不同结果。 返回与失败边界[21] · 空关联与选择调用[22] · 会话身份检查与关联解析[23]
从 005e19c 起,成功选择还会在服务进程中累计条目数、返回正文 token 数、世界书预算占比和选择原因;向量降级另计原因。它统计这一次选出了什么,不反过来参与预算或排序。比如这次正常选中零条,指标应记为零条成功选择;它不同于 Prompt 为空而根本没有调用 select。当前看板的零条查询有标签错误,面板无数据不能解释成“空选择为 0%”。选择调用中的计数[24] · 监控指标与已知问题
继续看:扫描窗口、hybrid、递归、依赖和预算数字
关键词仍默认扫描“传入历史+query”的末尾 4 条文本,query 算一条,不是 4 轮。Harness 最多传 20 条 user/assistant 历史,每条最多 16000 字符;query 是最多 8000 字符的本轮原始输入。条目可覆盖 scan_depth,显式为 0 不读基础窗口;递归、常驻、必需和 hybrid 仍各有参选路径。短历史增强只改变 hybrid 排名,不扩大作者的关键词扫描窗口。
当前输入先从历史中排除,再单独发送为 query。Harness 优先按当前 message ID 排除;旧调用方没有 ID 时,只去掉末尾内容相同的 user 消息。因此不能再把主链默认扫描 4 条解释成“query 与当前输入重复,再加两条历史”。外部调用方仍应遵守本轮输入与既有历史分开的合同。历史去重[25]
旧版固定依据(新行为以上文为准):字段默认值[26] · 窗口实际组成[27] · 扫描与递归[28] · Harness 截取字段[29] · Demo 加入当前用户消息[30]
hybrid 在规则触发之外,再增加一份相关性名单。服务把当前 query 与最近两条非空 user/assistant 消息拼成检索文本:每条历史取尾部最多 2000 字符,合计最多 8000;空间不够时优先最新消息。例如用户只问“它呢”,刚才提到“铜钥匙”的对话仍能帮助词法与向量排名。system 和 state 不进入增强检索,rules 与 /v1/search 保持原行为。相关性名单最多 30 条,不是整轮候选总数;常驻、必需、关键词、依赖仍按原资格与预算规则处理。短历史构造与限额[31] · hybrid采用与指纹[32]
主次关键词逻辑决定的是关键词这条触发路径:主关键词至少命中一个,启用 selective 且有次关键词时,再按 and_any/and_all/not_any/not_all 检查次关键词。次关键词的“排除”不是所有路径的硬禁令,没走通关键词路径的条目仍可能通过 hybrid 相关性或显式依赖入选;状态条件、受众、启用开关等才在各路径共享的资格检查中生效。向量步骤遇到可识别的 DomainError 会带降级说明继续词法排名;这不是所有错误都能降级。混合召回与降级[33] · 完整快照与30条相关性名单[34] · 主次关键词逻辑[35] · hybrid 激活与依赖[36]
一条资料可以带出另一条,但现在必须先真正入选。 Selection v3 每次扩展先激活候选,再处理依赖、冲突、条目数和预算;只有已录取且 prevent_recursion=false 的正文/依赖,才能触发下一次关键词扫描。默认最多再扩展 2 次。比如“北塔风俗”因太长落选,它正文提到的“南港”不会继续带出南港资料;已经录取的直接相关项也不会被后来的递归候选挤掉。原生 Entry 的 prevent_recursion / exclude_recursion 默认 true;文件导入器对省略值填 false,以保存后的字段为准。显式 requires 仍把同一本同一版依赖组成整包,依赖不用另命中关键词,但仍须通过资格检查。返回 policy_version 已变成 native-bounded-v3,相关 fingerprint 也包含 v3。录取后递归[37] · v3返回与指纹[38]
**中文相关性排名减少了单字噪声。**例如 query“铜钥匙”按连续二字“铜钥”“钥匙”参与词法排名,其他资料仅含孤立的“铜”或“匙”不再因此获得这一路排名贡献;单汉字 query 仍支持。该修改作用于词法/hybrid 召回,不改变作者填写的 keys 子串、全词或正则规则,也不增加 LLM 调用。当前中文分词与排名[39]
世界书预算是 2400 tokens。 这是当前 Harness 标准场景值,策略为hybrid;服务接口自身默认是rules、1500 tokens、最多50条、受众actor。Harness 的选择请求没有自动覆盖所有服务默认项。条目和依赖整包算成本,包括包装与间隔,不把长条目截半。组内还比较 priority、直接关键词命中、hybrid 分数等。当前场景配置[40]
默认 constant_budget_ratio=0.35,所以 2400 的场景中,可选常驻候选发起的包累计新增成本上限是 840 tokens;这是上限,不是预留位置。必需包不计入这笔常驻账,共享依赖不重复计费,也不能解释成“所有带 constant 标记的正文加起来不能超过 840”。
#17 已在 main fca57b8 中减少重复计算:每次请求自己缓存已选正文和精确 token 成本;只有候选真正进入预算判定才转义、拼接并计数,同一递归深度的相邻扫描复用规范化后的窗口,hybrid 候选只构造一次 Entry。缓存不跨请求、tokenizer 或会话复用,最终 context 仍按精确 token 预算核对。它不改录取规则、不增加世界状态,也不能凭测试通过推算生产 CPU 或延迟下降多少。请求内缓存及预算采用[41] · 最终context及诊断[42] · 候选构造[43]
服务返回的字段分别给谁用
| 返回字段 | 真实内容 | 后续用途 |
|---|---|---|
blocks[] |
每项的 id/book_id/revision/entry_id/title/content/position/depth/role/order/reason,命名位置另有 outlet_name |
Harness 取正文与位置来装 Actor;不是让模型自行下载书籍 |
snapshot |
本轮读取的书版本及内容哈希 | 核对本次究竟从哪个资料快照选出,不是会话剧情状态 |
context |
选中条目的聚合文本 | 供通用消费者与服务计数;当前多位置接线使用 blocks,不能把它的拼接顺序当最终 messages 顺序 |
decisions / degraded / duration_ms |
入选和排除原因、可识别降级、服务选择耗时 | 供排查;不表示用户动作成功,也不是后台执行清单 |
diagnostics |
实际retrieval query、query policy、lexical/vector/fused rank、匹配来源、激活原因、依赖和预算尝试及汇总 | 解释为何参选或落选;retrieval query含当前与近期聊天,进入观测时也是正文数据 |
token_count / token_budget / tokenizer / token_scope |
返回资料的用量、预算与计数口径;当前计数器为 cl100k_base |
不能据此宣称完整 Actor 请求已放得下;总预算仍另算 |
policy_version / prompt_hash / selection_fingerprint |
本次选择策略和内容的识别信息 | 对照同次结果与诊断;不是可以提交剧情更新的凭据 |
返回里没有“下一轮冷却状态”、保存会话的提交令牌或待执行工具。拿到结果后,本轮装配由Harness继续;聊天正文、普通后台state和作者书版本仍分别保存。服务默认[44] · 真实选择回包[45] · 服务附加耗时[46] · Harness消费契约[47]
代码证据 · 47 处
- 当前请求构造 ↗
- 本轮选择请求 ↗
- 当前状态解析 ↗
- 解析与请求 ↗
- V2读取 ↗
- 基础适配器 ↗
- Story调用基础准备 ↗
- Sumi空状态 ↗
- 场景策略 ↗
- 混合召回 ↗
- 当前解析 ↗
- 实际状态解析 ↗
- 条件只读判断 ↗
- 导入运行要求 ↗
- 选择资格与轮内递归 ↗
- 依赖与冲突处理 ↗
- 可选落选与必需报错 ↗
- 资格与最终选择 ↗
- 空关联跳过入口 ↗
- 解析校验 ↗
- 返回与失败边界 ↗
- 空关联与选择调用 ↗
- 会话身份检查与关联解析 ↗
- 选择调用中的计数 ↗
- 历史去重 ↗
- 字段默认值 ↗
- 窗口实际组成 ↗
- 扫描与递归 ↗
- Harness 截取字段 ↗
- Demo 加入当前用户消息 ↗
- 短历史构造与限额 ↗
- hybrid采用与指纹 ↗
- 混合召回与降级 ↗
- 完整快照与30条相关性名单 ↗
- 主次关键词逻辑 ↗
- hybrid 激活与依赖 ↗
- 录取后递归 ↗
- v3返回与指纹 ↗
- 当前中文分词与排名 ↗
- 当前场景配置 ↗
- 请求内缓存及预算采用 ↗
- 最终context及诊断 ↗
- 候选构造 ↗
- 服务默认 ↗
- 真实选择回包 ↗
- 服务附加耗时 ↗
- Harness消费契约 ↗
12. 世界书怎样进入模型:一份实际材料示例
上一节已经选出“世界底线、北塔门禁、铜钥匙”三条资料。接下来发生的不是“提醒模型去找书”,而是 Harness 在本轮模型请求发出前,把三条正文实际放进 Actor 的输入。 世界书服务负责挑资料,Harness 负责把资料和艾琳的人设、历史、旧状态、用户输入组装在一起。
返回的正文,怎样变成 Actor 真正读到的材料?
以铜钥匙条目为例,服务返回的内容里有“铜钥匙不能代替城主手令”,并附作者指定的位置。Harness 校验这些结构化块,再转义标签字符、保留条目身份,以类似下面的形式放入模型消息。这是包装格式的教学节选,ID 和正文均为示意。
<worldbook-entry id="book-id:1:copper-key" title="铜钥匙">
铜钥匙证明旧王室身份,但不能代替城主手令。
</worldbook-entry>
因此“原文入模”的意思是以条目正文为主要材料,没有先请聊天模型总结成另一段话;char/user 变量替换及标签转义仍可能改变字符。关键词和优先级主要用于选择,不把整份条目配置 JSON 都当正文塞给 Actor。原文包装与装配[1]
假设作者把世界底线设在人设前、门禁设在人设后、钥匙设在当前用户消息前,而且本轮 Actor 模板确实引用了艾琳的人设、聊天历史和当前问题,最终材料可以这样理解;这不是全部预设块的精确数组顺序:
人设和历史不是取到就全部放进去。 Harness 从 Axon 读取本轮 Actor 的 PromptManager,准备角色资料、用户画像等模板变量,再按模板实际引用的字段生成消息。模板没引用的变量,不会因为已经取到就自动进入 Actor;历史范围也受模板及已启用的压缩配置影响。下面展示的是这些材料都被采用时的教学例子,不能当作线上模板逐字段内容的证明。模板取回与变量准备[2] · 按模板展开消息[3]
世界书:死亡不能被魔法逆转
艾琳的角色卡与原有 Prompt:身份、性格、说话方式
世界书:北塔午夜后开门需要城主手令
轮初旧状态:当前场景及已建立事实
保留的聊天历史:包括已经出现的北塔守卫
世界书:铜钥匙证明旧王室身份,但不能代替城主手令
用户新输入:我把铜钥匙递给北塔守卫,请他开门
↓
Actor 生成本轮回复
Actor 因而有机会写出“艾琳望向守卫,守卫看了看铜钥匙,仍要求出示手令”。这只是可能的表达;材料存在不等于模型必然遵守,更不意味着场上每个 NPC 都知道钥匙的秘密来历。 本轮世界书没有自动给既有守卫补角色小卡,也没有把“开门成功”写入剧情状态。
**这些材料如果说法不同,程序不会先替作者统一事实。**例如艾琳的旧角色定义写“持铜钥匙即可进塔”,本轮世界书写“仍须城主手令”,已保存状态却写“没有手令,守卫已经放行”。只要它们分别被采用,就可能一起进入这次 Actor 输入。世界书装配检查的是条目结构和位置;普通状态在提交候选时校验格式、长度,并检查提交版本。这条接线没有在生成前理解三段故事、判定谁正确,再自动改掉另外两份资料的步骤。条目结构检查与装配[4] · 状态投放[5] · 状态候选校验[6]
这里不能把条目的 priority、required 或 conflict_key 当成“世界书永远压过角色卡和历史”的开关:它们约束世界书选择,conflict_key 也只按作者填写的冲突标记处理条目。放在人设前或人设后,表达的是装配位置,同样不能单凭位置推出统一的事实优先级。实际岗位模板可能另有处理冲突的指令,应核对该次采用的模板;本页不把外部模板的未知规则说成没有规则。世界书依赖、冲突与选择范围[7]
因此,遇到“资料已入模,艾琳仍说钥匙足够”的结果,要继续核对这次输入里是否还带着相反的角色定义、历史或旧状态,以及模板要求怎样处理它们。改对世界书,只改了其中一份来源;不能据此认定其他资料已同步纠正。下方的后台输入边界还说明:本轮后台没有自动收到同批世界书原文,不能假设它会立即替 Actor 调和这些说法。
作者想放的位置与总预算,两边都必须满足
作者设置位置,Harness 告诉服务这轮模板能提供哪些位置,服务据此筛选,Harness 再实际放入。当前标准世界书场景仍只开放人设前、人设后、聊天深度三种;代码另外支持示例、作者注释和命名插槽,不代表每个场景都自动开放八种位置。
如果作者指定了模板里不存在的位置,可选条目会被排除;其他资格已通过的必需条目无处可放,会报错。服务返回结构或位置不合法时 Harness 也会失败,不会把“收到一条返回记录”冒充“已经装进输入”。八种位置与所需模板可直接展开查看,重试和总预算见精确边界。服务位置检查[8] · 必需位置缺失[9]
世界书选中且装入后,还要检查整份 Actor 请求是否放得下。 前一节的 2400 只限制世界书;艾琳人设、历史、旧状态、世界书加起来,要给输出和安全余量留空间。全部超限仍会失败,不能拿“世界书选择成功”当作“模型一定能开始生成”。完整输入预算[10]
**这条接线现在也适用于显式配置的 Story 和 Sumi。**Story 把本輪选中原文装进 Actor 正文请求,不自动交给 Story 准备/结算模型;程序以进程内可信标记识别世界书补充消息,检查“当前用户消息”时会排除这些补充,避免世界书在用户后方放置时被误认成用户输入结束。Sumi 把原文装入生成正文与配图描述的主模型,再按完整输入计数;其 VLM 初始化/恢复和持久状态不会自动收到这批 lore。日记生成也显式剥离本轮 worldbook。它们复用了世界书取用能力,没有因此变成同一套产品编排。Story当前用户检查[11] · Sumi入模位置[12] · 日记排除[13]
后台 Planner 是否同时知道“钥匙不能代替手令”?
当前普通 Agentic 世界书路径没有把本次入选原文自动转发给 Planner。 Actor 和后台是分别发起的模型请求,程序各自组织材料;即便用同一家模型,它们也不自动共享上下文。
| 同一轮的材料 | Actor | 后台 Planner/专家 |
|---|---|---|
| 艾琳的人设、用户输入、已有历史、轮初旧状态 | 按回复模板组织 | 按分析模板另组,窗口和状态裁剪可能不同 |
| 本轮新选中的铜钥匙/北塔原文 | 直接进入这次输入 | 没有自动收到同批 blocks |
| Actor 这轮新写的守卫回应 | 是它正在产生的输出 | 本轮并行后台没有收到这份新输出 |
如果“铜钥匙不能代替手令”只存在世界书中,后台就没有保证知道这条新召回规则;如果它已经出现在角色定义、旧状态或本次保留的历史里,后台仍可以从那些材料得知。给条目的 audience 多写一个 planner,也不会凭空增加转发代码。**这两份输入的差异是接线事实,不能靠“都叫 Agent”来消除。**其他角色、历史和状态分别怎样组装,见本次Actor材料与普通持续状态的回读。Actor 前准备[14] · 后台独立材料来源[15]
本轮用了资料,下一轮会自动记住吗?
同一轮模型重试复用已经解析的书版本和已选条目;新的用户输入先重新 resolve Prompt 关联,再重新选择。用户下一轮说“那我们去市政厅申请手令”,候选由当时启用的书、这次输入、场景和历史决定;管理员刚改的关联或 latest 书头会在这个时点生效。北塔仍留在扫描窗口时也可能继续命中,不是换话题就立即清空。
世界书原文本身是临时上下文,不直接永久写入聊天历史,也不会因为用过一次就成为后台记忆。若 Actor 真正在回复里说出“需要手令”,宿主保存正文后,未来再把它带回且留在后台历史窗口内,后台才可能经对话间接知道。慢通道另行产生的新状态也要提交成功、被后续轮次读取才生效。本轮缓存与临时材料边界[16]
展开:八种位置、模板准备与位置缺失处理
八种位置怎样对应宿主模板
条目写的 position 是“我想放哪里”;Harness 在选择前通过 placement_capabilities 告诉世界书服务“这一轮我能放哪里”。两边对得上,才有资格入选。 当前标准世界书场景没有额外配置 worldbook.prompt,所以仍只声明原来的前三种;八种能力不会自动全部开启。
| 作者可选位置 | 模型输入里放在哪里 | 宿主要准备什么 |
|---|---|---|
before_character 人设前 |
角色设定区域之前 | 原有角色区域 |
after_character 人设后 |
角色设定区域之后 | 原有角色区域 |
at_depth 聊天深度 |
指定的真实聊天消息边界 | 聊天消息范围 |
before_examples 示例前 |
结构化示例对话之前 | 显式配置 examples;空数组也能保留这个位置 |
after_examples 示例后 |
结构化示例对话之后 | 同上 |
author_note_top 作者注释顶部 |
拼进作者注释消息的开头 | 显式配置 authorNote |
author_note_bottom 作者注释底部 |
拼进作者注释消息的末尾 | 同上 |
outlet 命名插槽 |
替换宿主模板中的指定标记 | 配置同名 outlet,例如 scene_lore |
比如作者让铜钥匙条目进入 scene_lore。后端要先准备一个含 {{outlet::scene_lore}} 的模板,并声明这个名字;服务才能返回这条资料,Harness 才能把原文填进去。用户在聊天中打出这串字符,不会凭空创建插槽。
如果模板没有这个位置,可选条目以 placement_unavailable 排除,不占后续候选和预算;其他资格都通过的必需条目无处可放,则报 required_placement_unavailable。若服务仍返回宿主无法放置的条目,Harness 也会明确失败,不会假装已经注入。服务位置判定[17] · 必需位置缺失处理[18] · 宿主位置配置[19]
继续看:位置、角色、重试与总预算的精确边界
depth 数真实聊天消息,不数轮次,也不数所有 Prompt 块。 新装配实现排除示例、作者注释、世界书资料和 prefill;depth=0 放在最后一条真实聊天消息之后,depth=1 放在它之前。世界书路径保留消息与人设边界,不先合并相邻同角色消息,也不会把所有 system 消息都搬到开头。深度与位置算法[20]
位置和消息角色是两件事。 独立条目默认 system,也能使用允许的 user/assistant;作者注释和 outlet 条目拼进宿主消息,继承宿主消息的 role。示例前后条目若采用支持的 char/user 对话格式,可以拆成多条 user/assistant 示例;普通正文保留条目角色。系统不会从一大段本地化 initPrompt 的标题猜出示例边界。示例解析[21] · 结构化区域约定[22]
旧调用方保留原三位置。 Worldbook Service 请求不传 capabilities 时,按原三种处理;显式传空 positions 则表示没有可放位置。多位置调用方必须消费 blocks,聚合 context 的拼接顺序不是最终模型 messages 顺序。服务八位置协议[23]
同一轮重试不重新选书。 本轮选择 Promise 缓存,模型重试复用同份结果;下一次用户输入再选。选中的原文只用于本轮模型上下文,不自动写回书籍、不直接永久存进聊天历史。
**2400 只管世界书,不管整份 Prompt。**角色、人设、历史、旧状态和世界书合起来,还要扣除输出额度和安全余量。非 Compact 的世界书 Actor 路径默认安全余量 1000 tokens;每次前台函数循环和模型重试重新装配、重新计数,从最老历史开始裁剪。固定 Prompt、当前输入、lore、状态 overlay、assistant suffix、循环控制和累计正文不会被这次历史裁剪删除。某个目标仍装不下就跳过它;试裁失败不污染后面的模型目标。Compact 路径沿压缩后的完整渲染计数,Sumi 沿自己的 fitMessages 计数。所有可用目标都装不下才以超限结束,不能用“世界书选择成功”代替完整请求合格。裁剪、试裁隔离与每次重装[24] · Compact最终装配[25] · Sumi计数[26]
历史对照:13c481b时的预算入口[27]与3b99f4c时的专用场景校验[28]保留供旧链接定位;它们的世界书接线限制已被 #197 替代,当前行为以上述 a4f5bb83 为准。
13. 世界书页面里,作者、管理员和用户分别控制什么
现在可以把“作者想让艾琳遵守手令规则”拆成三份工作:作者写清资料;管理员或接入程序把资料接到会话;聊天用户发出自己的行动,再观察实际回复。 这些是工作职责,不代表服务已经内置了作者/管理员/用户三套完整权限角色。
作者、管理员、聊天用户各自改变哪一环?
| 角色 | 能控制的内容 | 对本轮结果的影响 |
|---|---|---|
| 作者,通过管理接入程序 | 正文、关键词、常驻/必需、条件、优先级、依赖、目标位置等 | 决定铜钥匙条目写什么、何时有资格参选;外部文件未映射的内部规则须明确补齐保存 |
| 管理员或接入后端 | 保存完整修订、显式建索引、给 Prompt 保存完整书籍关联 | 决定固定某版或跟随最新、启停哪本书;保存后的关联供既有会话下一轮重新解析 |
| Harness 的服务端配置 | 选择策略、预算、模板提供的位置 | 决定本轮怎么选、最多装多少、资料放在哪里 |
| 聊天用户 | 输入角色 Prompt ID,读取服务端关联后试聊、浏览资料与结果 | “递出钥匙”成为检索线索和角色输入;用户没有因此修改条目或绕过预算 |
随后由世界书程序选择,Harness 装配,Actor 生成文字。没有一位操作员每轮手动勾选所有条目,也不是用户在聊天里说“强制注入”就获得配置权限。 某个角色可以有服务端单独配置的模板;当前 Demo 的角色布局是整份覆盖场景布局,不能理解为聊天时随手追加一个插槽。开发者改动的具体配置及读取时点列在本章展开项。角色布局配置[1]
在当前 Demo 页面,用户实际怎么用?
**先设置会话用户 ID,再输入艾琳的 Prompt ID,点击“读取关联”。**后端读取真实角色名称和服务端启用的世界书版本;页面显示这些书,允许在下拉框切换“查看哪一本”。这只是浏览切换,不会把本轮检索限制为正在查看的那一本;聊天端仍按 Prompt 全部启用关联选条目。无关联时页面说明可正常聊天。用户 ID 是调试身份输入,不是完成了登录认证。
读取成功后,可以新建或打开该角色的会话、发送“我把铜钥匙递给北塔守卫,请他开门”,浏览条目并查看本轮装配快照。若关联读取失败,已有本地聊天与草稿仍可看、可编辑,但暂不能发送或新建;重新读取成功后恢复。
**页面“读取关联”与每轮实际取书各做一次自己的读取。**前者决定侧栏展示的版本清单;后者由生成请求里的 Harness 重新 resolve,才决定本轮真正使用的书。管理端改版后,侧栏需再次读取才能刷新展示;不能只看侧栏旧版本就认定本轮也用旧版本,应以回复旁本轮 trace 的 books 为准。
**继续旧会话与新建对话分开。**同一用户、tenant 和 Prompt 的本地工作区保留会话列表;重新读取同一个角色的关联不会自动清除故事。换到另一个 Prompt 后进入另一份本地工作区;世界书版本本身不再是工作区键的一部分。
| 用户操作 | 程序实际做什么 | 对接下来聊天的影响 |
|---|---|---|
| 读取另一个 Prompt,或选择已有对话 | 按用户+tenant+Prompt 切换本地工作区,再读取所选会话远端历史和状态 | 继续对应角色的会话;不重置剧情;新会话与每轮生成均核对身份 |
| 点击“新对话” | 验证角色存在,读取其关联,核对新会话身份,创建会话和开场消息(如有) | 建立新的聊天;不保存一份会话专属书版本,也不改旧会话 |
| 在“查看世界书”中换一本 | 读取那本书解析时的具体版本和全部条目供浏览 | 不改变 Prompt 关联,不改变聊天使用的全体启用书籍 |
| 在管理端保存关联或发布 latest 新版本 | 管理端改数据库;Harness 下一轮重新解析 | 已有会话下一轮生效,已生成消息与状态不重写 |
| 清理浏览器站点数据 | 清本地用户选择、会话列表、草稿、回复缓存和世界书诊断 | 不调用远端删除/状态重置,也不删除服务端 Prompt 关联 |
**搜索框只筛选展示列表。**搜索“铜钥匙”不会将这个词加入下一轮 query;用户不能在这里勾选条目强制入模、改检索策略/预算/模板位置。
**当前 Demo 是关联读取与试聊页面,不是世界书编辑后台。**它没有上传、编辑正文、发布修订、建索引或保存角色关联的按钮;管理操作由其他可信接入完成。界面文字指向 Tavern 世界书页面集中管理,但 Tavern 页面实现和生产权限不在这两个仓库内。9 月 17 日 #172 的浏览器本地绑定提案保留为历史记录;当前 main #188 采用服务端 Prompt 关联,不能继续把这条当前读取链列为“候选未接”。当前页面操作[6] · 只读RPC名单[7]
**这里仍需后端身份与书籍权限保护,不能把“有用户 ID”或“只读”当成已鉴权。**聊天相关接口要求 X-User-ID,但此处理器不校验登录签名;只读 /rpc 在这项必填检查之前执行。当前 RPC 接受调用者提供的合法书籍 UUID+revision,固定 tenant 后读取书/条目/索引,没有在此处核对这本书是否属于当前 Prompt。Origin 只在请求带该头时检查,无 Origin 的直接请求不因此被拒绝。这是已定位的代码访问边界;实际部署是否由可信网关限制须独立确认,不能写成已发生生产越权。
上线前试选与聊天后核对,分别回答什么?
上线前试选回答:“给这份输入和配置,选择器会挑谁?” Worldbook Service 的只读管理接口 POST /v1/admin/context/select 允许管理接入方指定 tenant、书籍版本、query 和条件。可以先试“递出铜钥匙”,检查钥匙和门禁是否入选、南港为何落选、预算和降级情况。它运行同一套选择逻辑,但不生成艾琳的回答、不补 NPC 卡、不写剧情状态、不建索引;hybrid 仍可能调用 query embedding。此接口已经在固定 main 基线内,当前聊天 Demo 没有因此自动增加管理测试页面。管理选择接口[10] · 管理测试说明[11]
聊天后核对回答:“本轮准备发给 Actor 的消息里,装入了哪些世界书条目?” 页面“本轮世界书”记录实际 tenant、Prompt ID 和本轮解析到的全部书籍版本,并展示装入条目的正文、入选原因、位置、消息角色和最终消息编号,还能展开未注入条目的服务端原因,查看检索耗时、降级说明及世界书服务统计的 token 用量。这里的 token 数不包含完整 Actor 请求。
快照在 Actor 最终预算检查通过后、模型请求发出前记录,因此能确认装配结果,不能证明模型请求随后成功。展示正文来自服务返回的条目块;实际模型消息还可能经过标签转义、与宿主注释拼接或拆成多条示例对话,所以快照不是完整模型输入的逐字副本,也不能证明艾琳遵守了资料。页面诊断内容[12] · 实际装配快照[13] · 记录快照的时机[14]
这份诊断通过页面事件送达,并可保存在当前浏览器的本地工作区;不是世界书服务里的永久会话记录。换浏览器、清理本地数据或本地保存失败后,不能承诺恢复此前全部快照。它也没有把本轮选择提交成下轮的冷却状态。诊断本地存储[15]
除了页面快照,服务端现在会记录什么?
Harness 主干的 Worldbook RPC 接线会在启用 Langfuse 后记录“本轮查了什么、选了什么、在哪一步失败”。它与上面的浏览器快照是两份记录:页面快照显示实际装配位置;Langfuse 记录身份检查、解析关联、选择服务的输入/返回。Worldbook 服务 main 005e19c 又增加一份只含运行数值的 Prometheus 指标,下文分别说明。三份记录都不自动回灌给下一轮模型,也不是剧情记忆。
| 调用或记录 | 实际采集什么 | 可检查的问题 |
|---|---|---|
worldbook.conversation.check |
tenant、Prompt、会话、场景、RPC名及requestId | 身份作用域是否正确 |
worldbook.bindings.resolve |
角色关联请求、返回 books/具体revision、bookCount/emptyBindings | 是否未绑定、是否解析到预期版本 |
worldbook.select 输入 |
query、最多20条已截取历史、条件state、books、预算、位置能力、变量 | 本轮给选择器的线索究竟是什么 |
worldbook.select 返回 |
blocks原文、decisions、快照、token数、耗时、降级原因 | 服务选了什么;哪些被排除 |
| 失败/超时/取消 | 错误类型、消息、可用业务错误码、Axon error data | 哪一步失败;不会把原始取消语义改成成功 |
开关 HARNESS_TELEMETRY_ENABLED 默认 false。开启时必须有 LANGFUSE_BASE_URL、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY 和 HARNESS_TELEMETRY_ENVIRONMENT;HARNESS_TELEMETRY_SAMPLE_RATE 默认1,可设0–1。目前没有独立“记录耗时但不收世界书正文”的开关:宿主开启 telemetry 即设置 captureContent=true,过滤器只放行宿主自己创建的 Worldbook 封装;普通模型/工具内容仍被这套过滤器省略。配置[16] · RPC观测范围[17]
每份输入/输出限制在16,000个JSON字符内,超出后记录结构化 preview,标明 truncated 和 originalChars,不是截坏的JSON字符串。authorization、cookie、password、secret、API key、access/refresh token等精确键名会脱敏,HTTP凭据headers本就没有交给观测;聊天、剧情state和lore正文有意保留,不属于已脱敏内容。这份预览可辅助排查,但截断后不能保证完整复现。当实际环境要启用时,接入方需明确正文采集授权、区域、访问权限、保留和删除策略;清单写了true不证明有效配置已经部署。结构化预览与脱敏范围[18]
世界书请求结束后,监控怎样知道发生了什么
例如艾琳这一轮解析到一本书,服务成功选出三条正文。原流程照常把三条原文返回给 Harness;服务同时在当前进程内累计一次绑定成功、书籍数、选择条目数和正文长度。监控采集器随后访问同端口 8876 的 GET /metrics,取得 Prometheus 文本格式数值,再由 Grafana 查询采集器保存的时间序列。程序没有把这些统计写成书籍修订、聊天消息或长期状态;下一句的条目仍由当时的输入、绑定和规则重新选择。创建并注入同一份指标对象[19] · 抓取入口[20]
每个应用进程有独立 registry,当前 Dockerfile 启动一个 Uvicorn worker。计数和直方图留在进程内,重启后重新累计;是否能查历史取决于外部采集与留存。HTTP 指标使用方法、路由模板和状态码;业务指标使用固定的策略、结果或原因分类,不把 tenant、Prompt、book、entry、原始 URL、请求正文或错误详情放进标签。抓取 /metrics 本身不计入 HTTP 请求统计;抓取时只读连接池的本地统计与启动重建的内存状态,不查询业务数据库。HTTP 记录方式[21] · 标签与指标定义[22]
| 运行到哪一步 | 进程实际记录什么 | 读数能回答什么,不能代替什么 |
|---|---|---|
| HTTP 处理开始、结束 | 正在处理数、按 method/route/status 分类的完成次数,以及从中间件进入到响应建立的耗时 | 哪类接口慢或失败;耗时不含完整响应传输 |
| 解析角色关联 | empty/bound/error 及成功返回的启用书籍版本数;只统计进入处理函数的请求 |
没有关联和读取失败分开统计;没有关联不是故障,也不是零条 select |
| search/select 准备资料 | 等待四个检索并发槽的时间、读取快照的耗时和原始条目数 | 排队和读库分别耗时多少;条目数还没经过禁用、可见范围等过滤 |
| 检索与向量排名 | 成功 search 结果数,向量阶段成功/错误耗时,hybrid 回退原因 | 向量是否参与或降级;纯 vector 报错不作为成功降级,没进入向量阶段的请求不计向量耗时 |
| 成功选择条目 | blocks 数、返回 context 的 token 数、世界书预算使用比例和逐条决策原因 | 是否选到资料、预算如何使用;token 不包含完整 Actor 输入,预算为零时不记比例,原因次数也不是请求数 |
| 建立或复用索引 | built/reused/failed、整次耗时,新建成功写入的 chunk 数 | 索引是否真正新建;复用或失败不增加新建 chunk 数,包括启动重建任务的构建调用 |
| 采集器抓取 | 连接池大小/空闲/等待数、进程资源、embedding reset 状态与已完成/计划版本数 | 当前进程状态;reset 为失败不因此自动改变原 readiness 判断 |
绑定仍由原 repository 返回具体版本,计数发生在结果返回或异常收尾;选择、索引的观测也挂在原调用链上,不改变保存、版本、召回、排序和选择结果。绑定处理[23] · 检索、选择与索引接线[24] · 完整指标字典[25]
看板“空选择比例”为什么现在可能没有数据
#18 的看板有 36 个面板、34 条查询,覆盖 API、选择、绑定、向量降级、索引、PG pool、进程和 embedding reset;数据源、namespace、pod 可选,采集器还须附加后两种标签。它本身不会创建告警。生成器[26] · 变量与查询范围[27]
巡检在固定代码上让 Metrics().selection_entries.labels("rules").observe(0) 记录一次零条成功选择,实际导出 worldbook_selection_entries_bucket{le="0.0",strategy="rules"} 1.0。看板却查询 worldbook_selection_entries_bucket{le="0"};标签值精确匹配失败,比例的分子没有序列。因此这是验收前的 P1 查询缺陷,不能把面板空白当作“没有空选择”或“空选择为 0%”。建议将查询改成实际零桶标签并补导出标签与查询相匹配的测试;本次 Wiki 更新没有修改产品代码。错误查询[28] · 现有测试仅核生成器/JSON一致性及描述[29]
截至 9/24 14:27,作者记录已将看板导入 production Grafana,并读回 36 个面板和 34 条可解析查询;巡检没有直连复核,查询语法通过也不证明取得预期数据。作者同时明确 image 和 annotations 未部署,005e19c 没有对应 GitHub deployment。真正采用还需确认固定版本镜像、Pod 抓取注解、Prometheus target 为 UP、非空和空选择序列、Grafana 数据源及访问权限。最近直接成功 rollout 仍是 9/22 的 fca57b8,但没有读取当前 Pod,不能据此断言当前一定仍运行旧版。部署证据的完整范围
/metrics 没有应用认证;现有 Service 为 ClusterIP,仓库未提供当前集群 NetworkPolicy 的读回证据。因此发布时仍需核对仅监控网络可访问,不能由“未见 Ingress”推断实际不可达。staging 与 production 清单里的抓取注解只声明抓取意图;production CD 只 set image,不会 apply 清单,首次加注解需要另行更新实际清单。看板导入、镜像 rollout、注解生效和真实时间序列是四件不同的事。发布与网络条件[30] · production 注解[31] · CD 实际动作[32]
如果艾琳没按手令规则回应,从哪一步查?
| 看到的现象 | 先核对什么 | 不能直接得出的结论 |
|---|---|---|
| 当前浏览的世界书里没有铜钥匙 | 作者是否保存了它,Prompt 关联及本轮 trace 是否解析到含它的版本;侧栏是否已重新读取 | 不能先断定检索模型没理解用户 |
| 书里有,但本轮没入选 | 资格、触发、位置、依赖/冲突与预算;管理试选和本轮决策说明可帮助区分 | 常驻或关键词命中不保证最后入模 |
| 本轮快照确认已插入,回复仍违背规则 | Actor 的最终材料与生成表现 | 不能再把问题等同于“这轮根本没注入”;入模不等于遵守 |
| 没看到本轮快照 | 先看本轮是否在核对身份、解析关联、选择资料、装配或总预算检查时已失败;再看事件是否收到、当前浏览器是否保留记录 | “没有记录”既不能证明未检索,也不同于“有记录但实际零条” |
| Grafana“空选择比例”没有数据 | 005e19c 看板查询 le="0",实际 registry 导出 le="0.0";同时核对镜像、抓取注解、target 和真实序列 |
面板空白不等于零条选择从未发生,也不证明聊天正常或异常 |
快照随本次流式事件发送一次,同轮重试不重复发。它保存在当前浏览器工作区,服务端历史主要保存聊天正文;换浏览器、清缓存或事件到达前断线,不能靠历史接口补回完整旧快照。截图和本地记录适合核对这次接线,不能替代生产效果验证。
**一次失败的发送,也可能已经留下一条用户消息。**Demo先把“我把铜钥匙递给守卫”保存到聊天服务,再开始准备和生成;只有生成完成、助手正文保存成功,才发送done。如果用户消息已保存而后面的选择、生成或助手保存失败,这段处理器没有把先前用户消息删除回滚。因此可能出现“历史里有这次提问,却没有完整助手回复”;已有世界书快照也不能补成一条成功回复。再次发送前应以重新读取的历史和本次错误为准,不能假设上一轮什么都没留下。先存用户消息[33] · 失败与助手保存时点[34]
世界书不会根据这轮回复自动发布新版。若守卫最终接过钥匙,那是本局已发生的变化,应进入对话/状态链路;不能把“钥匙永远在守卫手上”直接固定成所有会话共用的书籍规则。
继续看:设定、剧情状态与服务访问的分工含 4 处更新
接入方究竟改哪里,什么时候生效
| 要改变的事情 | 由谁改、实际配置或接口 | 读取与生效边界 |
|---|---|---|
| 让Harness采用世界书这套接法 | 开发/部署方在已有普通RP、Compact、Agent V2、Story、前台循环或Sumi场景显式加 worldbook,并启用该场景;agentic-v2-worldbook 是现成示例。请求走 roleplay-harness/v2 扩展及对应 scenario_id |
旧v1预编译协议会拒绝;只把文件放进目录不等于已启用。世界书参数在请求真正使用时校验,不由用户聊天文字决定选路 |
| 指定资料租户 | 场景 worldbook.tenantId 必填;进程 WORLDBOOK_TENANT_ID 可覆盖已有worldbook对象的tenantId |
环境变量不会为未配置worldbook的场景自动打开能力;部署须核对实际Pod值,不能只看manifest |
| 改本轮选择策略或预算 | 场景维护者改 worldbook.strategy 与 worldbook.tokenBudget;允许rules/hybrid及整数0—32000,省略时为hybrid/2400 |
由服务采用新的有效场景配置后用于后续请求;Demo从服务配置取值,聊天请求不能随意覆盖 |
| 改某个角色使用的书及版本 | 管理接入调用 Worldbook PUT /v1/entity-bindings?tenant_id=...&entity_id=... 保存完整列表;固定 revision/null 跟最新/enabled 开关 |
保存成功后,新逻辑轮通过 Axon resolve 读取;已有会话也生效,同轮内部重试仍使用旧快照 |
| 选择 Demo 体验角色及浏览书 | 用户输入 Prompt ID,点“读取关联”;后端 prompt.get+worldbook.bindings.resolve。WORLDBOOK_DEMO_CONFIG_JSON 仍提供起始角色和角色布局,可有兼容书值 |
配置不再把聊天锁到固定书;实际聊天取书以服务端 Prompt 关联为准。未配置角色列表时仍可输入 Prompt ID;没有关联可聊 |
| 修改 Demo 侧栏展示 | 用户重新读取关联,再在返回书清单中选“查看世界书” | 只改变浏览对象;管理端改版后的实际聊天仍每轮自行 resolve,不以侧栏选择充当检索范围 |
| 开放Demo页面处理器 | 部署方设 WORLDBOOK_DEBUG_ENABLED=true,并配置Axon、允许Origin及静态文件 |
页面入口与世界书场景装载是两件事;只开页面不能补齐书、角色或模型配置 |
| 开放额外五种放置位置 | 模板维护者改场景 worldbook.prompt.examples/authorNote/outlets,或Demo某角色的 prompts[].prompt |
本次请求据有效布局声明capabilities;角色级布局整份覆盖场景布局。配置、条目位置与实际模板必须对应,详见八位置表 |
| 启用语义向量检索 | 世界书部署方改 vector_backend/embedding_backend及相应凭据,管理接入方为目标revision建索引 |
服务重建有效运行配置后才接该后端;索引ready只证明检索副本可用。默认关闭与迁移开关详见索引配置 |
当前 main 已撤掉“仅专用 V2 且排斥前台循环/Story/Sumi”的世界书限制,改为显式配置后共用身份、关联解析和本轮选择。各产品原有组合限制仍在:例如 Story 需要 Actor/recovery 设置且不能再叠另一个前台协调器,Sumi 仍不与 AgenticV2、Compact、记忆 hooks 混用。世界书本身不会替这些产品打开开关。整轮 deadline 同时覆盖 identity check、resolve、select 和生成;同轮重试复用快照,下一轮重新解析。本次没有读取运行环境的有效变量、关联或模板,配置样例不当作部署证明。现行配置与组合校验[35] · 协议要求[36] · deadline与接线[37]
专用场景配置[38] · 当前Demo配置解析[39] · 实际聊天请求与布局覆盖[40] · 关联管理合同[41] · 服务向量默认和装配[42]
快照中的位置字段
命名插槽显示 outletName;若条目拆成多条示例消息,快照显示多个最终消息编号。它记录的是本轮实际放置结果,不是固定的永久数组下标。
资料、状态与访问边界
“铜钥匙代表旧王室身份”是稳定设定,适合世界书;“钥匙刚交给守卫”是本局发生的事,属于对话/状态;“接下来检查钥匙真伪”是规划建议。世界书服务不会在聊天后自动把这三件事整理成新 revision,也不管理角色 Prompt。新人物首次出场之后,要不要补 NPC 小卡、补什么、何时保存,仍需看该场景实际启用的专家和状态提交链路。
文中的“作者”“管理员”是工作职责,不是服务内置的组织权限系统。**当前 Worldbook 普通接口也由请求 query 的 tenant_id 选择作用域,不能把租户参数当认证身份。**服务不检查 Bearer,客户端虽然要求传 api_key 并发送 header,服务端不使用它验证权限;能连接服务的调用方必须由可信网络、代理或业务入口限制,并将已认证用户映射到允许的 tenant/Prompt/book。仓库 ClusterIP 与无 Ingress 不证明实际集群 ACL 已验收;清单未包含 NetworkPolicy。tenant真实来源[43] · Prompt API[44] · 客户端header[45] · 无认证测试[46]
哪些已进入主干,哪些还要部署验证
本次更新Worldbook 最新可核验的生产部署事件是 10/09 10:59 的 ad38dce1de7ccd291d702a67b92c06a966fddf85。run 37876956192 完成测试、构建推送、固定 digest、更新镜像及 rollout,包含 Entity 关联版本。它是此前补查到的历史事实,10/19 本轮仅复核部署列表,没有重读该 job;不能记成近几天新增代码或新上线。随后同 SHA 的另一次运行被取消,且没有执行部署步骤,不构成前次回滚的证据。此前 9/22 的 fca57b8、88c99e99 与 fafdb8d 部署继续作为历史记录保留。Entity 版本生产部署 · 9/22 历史部署。
旧版固定依据(新行为以上文为准):本次生产部署
本次更新本章状态核对至 2026-10-19 14:51。Worldbook main 仍为 ad38dce1de7ccd291d702a67b92c06a966fddf85;本轮提交和部署概览没有新增,未重读旧部署 job 或新增源码。Entity 接口、007 迁移文件与既有指标代码已在已核部署的源版本中,但当前 Pod、数据库 007 实际执行、Axon/调用方兼容、采集 target 和用户业务效果仍未独立回读。#15 滚动部署策略、#19 urllib3 升级本轮列表仍开放,未重核 head/评论;版本细节沿用上次已读来源。
| 需要确认的对象 | 已有事实 | 还不能由它证明什么 |
|---|---|---|
| Entity 关联与 schema007 | #20 在原有服务校验基础上改名关联表/字段,保留旧数据和 Prompt 兼容接口;任一启用关联失效仍整次 resolve 报 409 | 生产默认AUTO_MIGRATE=false,发布需协调 007 执行回执和新旧客户端;readiness 不能替代迁移、孤儿记录检查与回滚准备 |
| 向量重建 | /health/ready 即使 reset 为 pending/running/failed 也可能 HTTP 200;vector-only 对未ready索引报错,hybrid可降级 |
rollout成功不证明语义召回已切换完成;要查 reset 状态、数量和目标 revision 的查询结果 |
| 世界书最新生产部署 | ad38dce 的 run 37876956192 于 10/09 10:59 完成测试、构建、固定 digest、更新镜像与 rollout;包含 Entity 接口 |
当前 Pod、007 迁移、Axon 兼容、ACL、向量选择效果和性能仍需直接验证;这是补查旧部署证据,不是本周新增代码 |
| #18 指标与看板 | 指标实现已包含在 ad38dce 部署源版本;仓库已有 36 面板/34 查询,作者以前记录导入 Grafana |
镜像部署不等于采集注解已 apply;target UP、真实样本与查询未独立验收。已知空选择比例标签不匹配问题未取得修复证据 |
| 世界书历史部署 | 9月21日 c67852c 的Actions 35572601775 曾完成build、set image、rollout/readiness与image equality;其tree与合入的 a2dad786 相同 |
作为历史成功发布保留,不再作为最新部署;两次成功部署都不能代替schema006执行回执、ACL和当前有效配置核对 |
| 本次更新Harness 对应业务部署 | Sumi f9b26a9 于 10/19 13:26 完成实际生产部署步骤;Fusion c8fc61c 保留 9/24 历史 production 记录,本轮未复核 |
Sumi 源版本含 Entity 接线,仍需有效配置、007 迁移及 Axon 协同才能用于真实请求;不能推断所有 main 场景都已采用 |
| staging配置 | 内置示例tenant为production-default;staging manifest声明staging-default,且若干manifest打开telemetry | Worldbook workflow只patch镜像和Demo JSON,Sumi只set image;新tenant/env不会自动同步到已有Pod。尚未读回实际tenant、场景hash或观测开关,不称已发生线上串租户/采集事故 |
| 定向测试与实际接入 | 前次巡检Worldbook selection/lexical 29/29,Harness placement/telemetry 47/47、Langfuse export 19/19;此次Worldbook生产工作流在PostgreSQL+pgvector下跑未过滤pytest并成功 | 这些测试环境证据不等于生产schema、Axon、模型、ACL、业务流量和正文采集治理验收。绑定修复的持久回归测试仍未覆盖“书缺失但revision残留”的真正孤儿分支 |
实际生产部署步骤[47] · 本次数据库测试配置[48] · 当前关联校验[49] · 006迁移[50] · Worldbook staging实际patch[51] · Sumi staging实际动作[52] · 9月21日生产rollout · 本次Harness镜像构建 · 前次Harness镜像构建
本次更新**开发分支中的 PR #15:更新服务时先启动新实例,再回收旧实例。**固定候选 be19065bb5507f5856f78e51a6b662632f51b477 将生产清单从 Recreate 改为 RollingUpdate,设置 maxSurge:1、maxUnavailable:0、minReadySeconds:10。10/19 列表仍是开放 PR,本轮未重核该 head;没有合入当前 ad38dce,也不属于已核生产版本的变更;现有CD只更新image,清单合入也不会自动把新策略apply到集群。PR #15 · 主干Recreate[53] · 候选RollingUpdate[54]
这里的Ready只检查数据库连通和 book_revisions/vector_chunks 表存在;返回中的 embedding_reset 为pending或failed不会使它失败。如果启动时要后台重建Embedding,候选策略可能在新实例仅通过上述检查10秒后回收旧实例,向量/混合检索是否可用仍未经过同一门槛。需要按真实查询和发布期间流量验证,不能将“Pod Ready”写成“所有召回能力已验收”。PR作者另有手工patch生产并读回1/1 Ready、镜像未变的运维记录,本次仅作为作者记录保留,不等于独立集群确认;也不替代 ad38dce 已有部署事件或当前集群读回。当前readiness[55] · 后台reset启动[56]
PR #15 的候选清单还将 /cache 挂在每个 Pod 自己的 emptyDir 卷上,供 Hugging Face 等缓存使用。滚动更新创建的新 Pod 不会继承旧 Pod 的这份本地缓存。候选清单中的缓存目录与卷[57]
新增schema[58] · 关联升级说明[59] · 后台重建[60] · readiness判断[61] · 历史生产部署任务 · 数据库CI配置[62]
历史源码索引:9 月 18 日前版的会话 pin 与固定书 Demo
以下链接保留原有核查记录与深链。它们说明 3b99f4c/13c481b 时的旧行为,不作为当前 Prompt 关联与权限结论。
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/debug-api.ts#L104[63]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L23[64]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L30[65]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L39[66]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/adapters/agent-router/dispatch.ts#L764-L772[67]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/scenario-files.ts#L29-L64[68]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L751-L774[69]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L883-L885[70]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L902-L910[71]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L973-L984[72]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/contracts.ts#L41-L45[73]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L104-L120[74]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L104-L135[75]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L138-L172[76]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L75-L90[77]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/demo-config.ts#L8-L34[78]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/demo-storage.ts#L3-L47[79]
3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/web/src/main.tsx#L156-L157[80]
9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L138-L145[81]
9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L288-L296[82]
9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L345-L368[83]
9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L91-L126[84]
b0af622b3af6bbc9c59c7201501f768955151efd/src/worldbook/app.py#L210[85]
b0af622b3af6bbc9c59c7201501f768955151efd/src/worldbook/service.py#L150[86]
13c481bf8be04560940d4362f9ceced12ab57011/adapters/agent-router/dispatch.ts#L764-L772[87]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/runtime.ts#L349-L366[88]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/debug-api.ts#L119-L120[89]
13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/runtime.ts#L49-L76[90]
代码证据 · 90 处
- 角色布局配置 ↗
- 读取关联与浏览选书 ↗
- 后端角色检查和解析 ↗
- 本地工作区键 ↗
- 会话和展示处理 ↗
- 当前页面操作 ↗
- 只读RPC名单 ↗
- 处理顺序与身份来源 ↗
- 当前只读参数校验 ↗
- 管理选择接口 ↗
- 管理测试说明 ↗
- 页面诊断内容 ↗
- 实际装配快照 ↗
- 记录快照的时机 ↗
- 诊断本地存储 ↗
- 配置 ↗
- RPC观测范围 ↗
- 结构化预览与脱敏范围 ↗
- 创建并注入同一份指标对象 ↗
- 抓取入口 ↗
- HTTP 记录方式 ↗
- 标签与指标定义 ↗
- 绑定处理 ↗
- 检索、选择与索引接线 ↗
- 完整指标字典 ↗
- 生成器 ↗
- 变量与查询范围 ↗
- 错误查询 ↗
- 现有测试仅核生成器/JSON一致性及描述 ↗
- 发布与网络条件 ↗
- production 注解 ↗
- CD 实际动作 ↗
- 先存用户消息 ↗
- 失败与助手保存时点 ↗
- 现行配置与组合校验 ↗
- 协议要求 ↗
- deadline与接线 ↗
- 专用场景配置 ↗
- 当前Demo配置解析 ↗
- 实际聊天请求与布局覆盖 ↗
- 关联管理合同 ↗
- 服务向量默认和装配 ↗
- tenant真实来源 ↗
- Prompt API ↗
- 客户端header ↗
- 无认证测试 ↗
- 实际生产部署步骤 ↗
- 本次数据库测试配置 ↗
- 当前关联校验 ↗
- 006迁移 ↗
- Worldbook staging实际patch ↗
- Sumi staging实际动作 ↗
- 主干Recreate ↗
- 候选RollingUpdate ↗
- 当前readiness ↗
- 后台reset启动 ↗
- 候选清单中的缓存目录与卷 ↗
- 新增schema ↗
- 关联升级说明 ↗
- 后台重建 ↗
- readiness判断 ↗
- 数据库CI配置 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/debug-api.ts#L104 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L23 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L30 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/demo-config.ts#L39 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/adapters/agent-router/dispatch.ts#L764-L772 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/scenario-files.ts#L29-L64 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L751-L774 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L883-L885 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L902-L910 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/server.ts#L973-L984 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/contracts.ts#L41-L45 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L104-L120 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L104-L135 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L138-L172 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/debug-api.ts#L75-L90 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/demo-config.ts#L8-L34 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/demo-storage.ts#L3-L47 ↗
- 3b99f4c943a363ea05e5b9d53ad21a3cb16114b2/apps/emochi/worldbook/web/src/main.tsx#L156-L157 ↗
- 9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L138-L145 ↗
- 9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L288-L296 ↗
- 9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L345-L368 ↗
- 9edea5287a399039d2e9f1cf58001e20a271a8c1/src/worldbook/app.py#L91-L126 ↗
- b0af622b3af6bbc9c59c7201501f768955151efd/src/worldbook/app.py#L210 ↗
- b0af622b3af6bbc9c59c7201501f768955151efd/src/worldbook/service.py#L150 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/adapters/agent-router/dispatch.ts#L764-L772 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/planning/runtime.ts#L349-L366 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/debug-api.ts#L119-L120 ↗
- 13c481bf8be04560940d4362f9ceced12ab57011/apps/emochi/worldbook/runtime.ts#L49-L76 ↗
14. 工具能力目录:哪些能用,挂在哪里,业务怎样组合
先看实际装配名单,再看工具能解决的业务问题。仓库里有函数、工具封装、程序固定步骤和模型可选菜单;这四种东西不能用一个“可用工具数”混在一起。当前main没有一份自动挂到所有Agent上的总菜单。下表列出每个执行入口真正提供的能力,后半章逐项说明输入、结果和用途。
本章是工具能力总表;第21章是具体调用参数和SDK接法;第15章仅用“陌生人出场”演示Actor+人物分析+状态保存的组合。第15章没有增加一种工具,也不是整份目录只服务于NPC。全部已接业务场景先看总览场景表。
原有工具目录沿固定证据;2026-09-22 定向核对 Harness main a4f5bb83 的世界书多场景接线和空绑定处理,Compact 新增筛选同章更新。Imagine 失败路径、SDK gate 和未变原机制沿原固定证据。旧固定链接保留作对应实现依据;新增量写在所属能力处,候选分支仍单列,不冒充 main 或生产启用。
main 里到底挂了哪些工具:按谁调用来查
| 实际执行入口 | 确切名单 | 谁选择/谁执行 | 当前结果交给谁 |
|---|---|---|---|
| 普通RP后台协调器 | analyze_plot、judge_npc、audit_knowledge、simulate_world、manage_callbacks、direct_scene、update_director_state |
协调模型选择;程序补必要审计;注册表调用专家LLM或DirectorLLM。第二阶段菜单只剩状态整理 | 专家结果回协调器/Director;候选由程序检查保存。只有这一组才是“六专家+Director” |
| 前台工具循环 | actor、over;按接线再开放generate_image、schedule_dio |
前台控制模型逐次选择;程序执行,结果回给它再判断。visual_beat后图片可由程序自动安排 | Actor正文给用户;图片和DIO给后台任务。其回执不等于图片或新Prompt已经完成 |
| SDK 自建Agent/SDK slow | 没有默认业务工具;从宿主传入的tools或capabilities得到名单 |
宿主注册,模型从这份名单选择,Pi循环执行与回传 | 自建Agent宿主解释最终结果;slow可通过prepareCommit把结果转为待提交状态 |
| Story 现有应用 | PovPrepareTurnTool、PovAdvanceWorldTool、NarrativePlanCycleTool、NarrativeDealBeatTool、NarrativeSettleEventTool、NarrativeRebranchTool |
Story程序根据阶段和条件直接调用;这些是宿主类,不能直接假装成普通后台的六个function名称 | 场景准备、世界/叙事新快照、当前剧情包;交Actor或宿主保存 |
| 回复前后的记忆/资料流程 | 记忆后端recall/ingest;Compact;Persona;ReadMemoryTool/WriteMemoryTool;worldbook选择与注入 |
程序按启用方案在固定时点调用;没有全都进入模型工具菜单 | 文本材料/快照进入上下文,更新交对应存储;保存与回读见第9章 |
| 世界书场景 | worldbook.conversation.check、worldbook.bindings.resolve、worldbook.select;管理读取book.get、book.entries、index.get等Axon接口 |
会话和资料程序调用;本轮选择在Actor前完成;管理接口由管理业务调用 | 本轮解析的书版本、blocks、诊断;每轮重新解析 Prompt 绑定,后台协调器不能自行调用这些未注册函数 |
| Sumi 图文交付 | 图文协议解析、状态读写、分段、image.generate、消息get/edit、通知;新main加image.history.save/image.gallery.save |
Sumi程序处理模型输出,先核对所属消息,再执行图片与保存;不是普通专家调用 | 当前图文消息、后续状态、图片尝试/通知进度、图库记录;这几份产物分开保存 |
| Core Tools 隔离调试worker | 上述六专家+update_director_state+get_memory、update_memory、generate_image_asset,共10项目录 |
调试界面选定工具;worker按依赖决定是否可运行。它不是一只默认自动挑10项的线上RP Agent | 专家/Director结果仅回显;JSON记忆为隔离快照;图片可调用已配置的真实staging服务 |
**10项调试目录、7项普通后台注册项、最多4项前台动作,回答的是三个不同问题。**Core Tools包的范围还包括Story和通用工具基类,不能拿调试目录当整仓能力清单。世界书管理API与图片消息写回也已存在,但它们多数由程序调用,不是模型自由选择的function tool。
普通后台的enabledTools用于生成菜单和相关规则,注册表仍注册七项;当前实现没有把本阶段菜单作为完整的二次执行许可检查,普通应用也未开启通用注册表的严格参数校验。SDK slow则采用自己的严格注册表。产品文档可以描述正常可选名单,但不能把两者混称成同一种权限保证。
给另一个业务使用时,现成可拿走的封装是什么
| 包或仓内能力 | 已有工具/入口 | 业务实际拿到什么 | 默认挂载情况与接入责任 |
|---|---|---|---|
| Core Tools根入口 | 六专家工厂/类;ReadMemoryTool、WriteMemoryTool、Tool及hooks |
专项建议或状态读写结果;before/afterExecute、显式afterTurn扩展点 | 六专家已用于普通后台;读写包装由程序调用。模型、Prompt、上下文和store由宿主给 |
/memory |
createMemoryTools生成get_memory/update_memory |
JSON记忆对象和revision;按expectedRevision整体替换后的新revision | 可直接给Pi挂载,也在隔离调试使用;普通RP默认菜单没有这两个函数 |
/image |
createImageAssetTool生成generate_image_asset |
任务ID、图片URL与COMPLETED/ERROR审核证据;不自动变成聊天插图 | 宿主注入图片执行器;绑定用户、配额、消息、保存与展示另接。与空参generate_image不是同一协议 |
/story |
世界准备/推进2类,叙事计划/当前节拍/结算/分支4类 | 本轮场景资料、剧情包、候选新世界与叙事快照 | 已有Story应用调用,也可单独复用;宿主控制调用顺序与快照提交,不自带通用function注册 |
/pi |
toPiTool |
将一个专家的定义和执行包装成Pi工具 | 这是适配器,不是多出来的业务专家,也不会自动装全包 |
| 仓内SDK/工具适配 | AxonJsonMemoryStore、MCP包装、外部Workflow调用、工具目录与观测 |
让已有执行器、存储和流程接到宿主 | 需核对公开导出;仓内有文件并不表示npm根入口公开,例子文件不代表应用已挂载 |
下面按业务结果展开。每一项都应同时读它的调用者、材料、回包、保存与生效时间;“已可调用”只说明这段执行链存在。
按想得到的业务结果查能力
| 业务需要 | 下文入口 | 先确认什么 |
|---|---|---|
| 本轮回复、图片、下一句话选项、长期风格修改 | 当前交付 | 是否有图片、DIO、快捷回复的配置与接线 |
| 本轮遵守已有世界设定 | 世界书 | 绑定哪本书哪一版,本轮是否选中并放进模型输入 |
| 以后记得经历、物品、人设或长历史 | 记忆材料 | 用哪个存储、何时保存、由谁再次读取 |
| 人物、知情范围、承诺与场外进展连续 | 后台专项分析 | 是否普通 Agentic;分析是否最终保存成新状态 |
| 世界事件推进或连续图文玩法 | Story / 视觉与 Sumi | 需产品另选模式,不是普通后台默认附带 |
| 另一业务只借用一项能力 | 可复用封装 | 新宿主负责身份、调用时机、保存与再次使用 |
| 判断候选是否可直接上线 | 候选边界 | 是否已合并、当前链路是否使用、验证到哪一步 |
当前交付能力:回复、配图、长期修改
| 业务上要做什么 | 实际工具或能力 / 谁调用 | 输入与产出 | 怎么用,以及什么时候生效 |
|---|---|---|---|
| 写角色回复 | 普通 Actor 直接生成;开启前台循环后,由控制模型调用 actor |
已准备的角色、历史、query、状态等 → 用户可见正文;循环参数 responseMode=complete/visual_beat |
例:先让新来的总统在酒馆开口。本轮交付;各段共用整轮正文预算 |
| 给当前情节配图 | 前台 generate_image,以及 visual_beat 后的自动安排;必须有图片接线 |
前台参数为空,程序使用最新 Actor 段落 → 图片任务;后台取得消息 ID 后生成并写回 | 例:为刚写出的酒馆会面配一张图。文字可先到,图片稍后补进同一条消息 |
| 让后续角色持续改变表现 | 前台 schedule_dio → DIO 服务 |
程序取用户原始长期指令、会话与角色身份 → accepted,后台等待编译完成 | 例:“以后艾琳说话更简洁,保持这种风格。”本轮不半途换 Prompt,后续加载有效版本 |
| 结束本轮前台编排 | 前台 over |
空参数;须已有 Actor 输出,且满足未完成配图等检查 | 表示这轮前台动作结束;不代表剧情已结算、所有图片已完成或后台状态已保存 |
| 接入既有业务的回复前后处理 | before_chat、before_chat_prompt_source、after_chat hooks;宿主按配置调用 |
前置材料/变量 → 当前上下文;后置处理可返回替换后的正文 | 例:前置补入业务资料,后置按业务规则处理展示文本。外部 hook 的额外行为由对应服务实现,不能从名称推定 |
| 给玩家几个下一步回复选项 | 独立 auto_reply 请求 → generateAgenticAutoReplies / generateStoryAutoReplies |
对应消息与相关状态 → 建议回复选项 | 普通路径等待对应回复的后台建议,Story 路径重读已保存正文;返回三个选项供玩家选择,不代发、不改事实。需相应模型配置;具体输入、等待与返回。Sumi 走 Chat Service 独立路由 |
调用参数和回执见前台四动作;实际写回过程见当前消息配图,长期要求的后续读取见DIO 生效。
这里要分清两个同名的 generate_image:前台这个是“为刚写的一段安排图”的空参数动作;后端 MCP 同名接口接收消息和图片位置等参数,执行具体生图与回写。visual_beat 是 Actor 参数,不是第五个工具。DIO 修改后续有效 Prompt;普通剧情状态、世界书版本和 JSON 记忆不会因此自动同步改写。
依据:前台调用条件与执行[1]、图片任务与消息回写[2]、DIO 接收与等待[3]、图文与 DIO 的装配条件[4]。
回复前后处理与快捷回复依据:前置材料[5]、后置正文处理[6]、快捷回复生成[7]。
当前资料能力:世界书怎样参与,谁负责维护它
| 业务上要做什么 | 实际接口 / 谁调用 | 输入与产出 | 当前能力和缺口 |
|---|---|---|---|
| 本轮参考正确的世界设定 | worldbook.select;世界书场景由程序在 Actor 前调用 |
本轮解析出的书版本、query、历史、状态与预算 → 入选原文 blocks、选择理由 | 例:问北塔门禁时取出“铜钥匙不能代替城主手令”。本轮加入 Actor;后台 Planner 没自动收到同批原文 |
| 决定这张角色卡本轮参考哪些书 | Harness 每轮调用 worldbook.conversation.check、worldbook.bindings.resolve;管理侧替换 Prompt 绑定 |
tenant、Prompt、会话身份 → 本轮明确的 book/revision 集合 | 固定 revision 或跟随最新均可;更换、清空绑定在既有会话下一轮生效,同轮重试复用原选择;空书仍可聊天 |
| 查看当前书里有什么 | worldbook.book.get/book.entries/index.get;管理页面的程序调用 |
合法书 ID 与版本 → 元数据、条目与索引状态 | 查看与 Prompt 关联管理由页面/宿主调用;这些接口没有注册给 RP 模型自由挑书、编辑或发布。后端读书授权需另核对,不能由前端可见范围代替 |
| 导入、建立或修订世界资料 | 世界书服务的导入预览、创建、修订与索引 API;需作者/管理业务调用 | PNG/JSON 或原生条目 → 导入报告、不可变修订;按需显式建索引 | 后端能力已存在,当前 RP 没有“剧情里出现新人物就自动发布世界书”的调用链 |
**当前 main 已解除世界书的专用场景限制。**普通 RP、Compact、Agent V2、Story、Sumi,以及有前台 function loop 的路径,只要显式配置 worldbook 并满足对应入口条件,就可在 Actor 前选择并注入条目。内置 agentic-v2-worldbook 示例仍没有启用图片、日记或 Compact;不能把该示例的选择当成全仓的组合禁令。用户说“配图”不会替接入方开启图片执行器;工具菜单及开关仍由所选业务配置决定。统一入口与空绑定处理[8] · 当前配置组合[9]
“常驻/动态”是选条目的策略,不是 Agent 的两种工具。常驻可以免关键词匹配,仍受资格、冲突和预算约束;动态条目按规则或检索取得候选。选书不负责创作缺失人物,更不负责把聊天事实变成作者设定。若要把人物沉淀进世界书,需要另外定义条目生成、发布权限、版本和会话生效方式。第 10–13 节展开这套生命周期。
依据:本轮选择与注入[10]、当前逐轮绑定解析[11]、Demo 接口与读书范围[12]、服务导入与创建[13]、修订和索引入口[14]。
当前记忆能力:记住经历、表格事实、用户材料和长历史
| 业务上要做什么 | 当前实现 / 谁调用 | 输入、保存与后续使用 | 一个实际用法 |
|---|---|---|---|
| 记住较早的共同经历 | Axon Go 日记召回与 diary-orchestrator;宿主在回复前后安排 |
回复前召回日记交模板;回复后经轮数、额度、冷却、锁等条件判断是否摘要并存入 Axon | 后续请求按用户/会话和已选来源取到已保存摘要;此Axon Go RPC并未用“上次救援”这句query做语义检索。不是每轮都写,也不等同专家分析 |
| 维护物品或关系表 | Axon Go 表格召回与编辑处理;宿主调用 | 读表和版本;完成回复后解析约定格式的编辑,按版本保存 | 例:将钥匙持有人由莉娅改成用户。正文里提了一句不等于必然形成有效表格编辑 |
| 使用既有 Personalization 记忆 | personalization runtime 的外部前后 hooks |
外部服务提供本轮材料、处理完成后的回合 | 已有接入;召回与整理的内部算法在外部服务,不能由 Harness 代码推定 |
| 对照两种记忆后端 | axon_shadow runtime |
同时召回 Personalization 和 Go 作对照,实际使用与写入仍走 Personalization | 用于观察差异;不能说已经切到 Go 写入 |
| 使用 Hinos 记忆服务 | hinos runtime 的 prepare/提交流程 |
基础上下文渲染后向外部服务准备材料,非空时重渲染;回复后按 claim 提交 | 是另一套记忆接入方式,不能与其他后端默认为同时全开 |
| 让长对话装进模型 | Compact;准备阶段按上下文预算与历史检查点触发 | 较早历史 → 摘要,保留近期原文,保存覆盖范围和检查点 | 例:保留借钥匙约定同时压缩旧闲聊。它会影响本轮材料;不是固定 X 轮的后台专家 |
| 让模型理解用户扮演的身份 | Persona / 角色模板变量;材料准备时提供 | 已配置用户人设 → 模板或专家输入 | 用于理解“用户是谁”;并不自动把用户聊天中新说的偏好抽取成永久档案 |
上表各条完整链路:日记 · 表格 · Personalization/shadow/Hinos · Compact · Persona。
召回成功,还要看模板有没有引用材料。 仓库内置世界书场景的 memorySources=[],也没有 Compact;这是该份配置的选择。#197 已允许其他显式配置 worldbook 的普通 RP、Compact、V2、Story 和 Sumi 走各自 Actor 注入,不再局限于专用场景;仍不能把上表所有步骤当成每个请求都会执行。Agentic state、日记、表格、Compact 和通用 JSON memory 有不同存储与触发规则,目前没有一个自动同步它们的“总记忆工具”。
依据:Axon Go 与 shadow 读写[15]、Personalization hooks[16]、Hinos[17]、日记触发[18]、Compact[19]、世界书场景配置[20]。
当前剧情能力之一:后台分析与连续性状态
普通 Agentic 把当前正文交给 Actor,同时在后台分析轮初材料。六位专家是这里的一组专项 LLM 工具:每位有自己的 Prompt 和模型配置,通常用一次模型请求给出建议,失败可能重试;它们不要求六种不同底层模型,也不各自拥有独立长期记忆。
| 业务问题 | 工具 | 如何用 / 可能产出 |
|---|---|---|
| 用户改变了调查方向 | analyze_plot 剧情分析:输入与后续使用 |
问“拒绝进塔后,如何继续寻找失踪者” → 保留主目标、改用城门登记簿线索的建议 |
| 新人如何融入当前故事 | judge_npc 人物分析:输入与后续使用 |
问“新总统是谁、与谁有关、知道什么” → 身份、位置、关系和待揭示来历的建议;不直接建独立 NPC 卡 |
| 角色有没有突然全知 | audit_knowledge 知识检查:输入与后续使用 |
问“守卫从何知道钥匙位置” → 区分已知、猜测和缺少的知情依据 |
| 场外人物和时间是否该变化 | simulate_world 世界进展:输入与后续使用 |
问“两小时会谈对城门期限有何影响” → 基于既有日程的时间、位置、期限建议 |
| 承诺和伏笔有没有被忘掉 | manage_callbacks 连续性跟踪:输入与后续使用 |
问“明日文书承诺是否已兑现” → 保留待兑现事项,不强行当场触发 |
| 这一幕该怎么表现 | direct_scene 场面指导:输入与后续使用 |
问“让守卫主动回应,保留玩家决定权” → 视角、镜头和主动性建议 |
| 把值得保留的意见整理成状态 | update_director_state |
Director 读取旧状态、轮初材料和专家结果 → 完整候选状态;程序校验并按版本保存 |
调用每个专家时,模型传 reason 和可选 focus,程序补入角色卡、开场、轮初状态与记录、近期对话、query 等材料。不是让模型在参数里自己凭空补齐背景。专家结果先给后台协调器与 Director;候选有效、有变化且版本写入成功,后续 Actor 才能读取到新的状态投影。
这组能力已接入普通 Agentic,但不是每轮六个全跑。首轮、新名字有特定补审计规则,其余按需选择;工具执行仍受配置与额度影响。后台看不到 Actor 本轮刚生成的正文,世界书入选原文也不自动传给它。上表每项可直接打开自己的完整例子;触发/读回规则和Director 保存条件也有同章对应接口。
依据:专家职责、输入和结果[21]、按需选择与强制规则[22]、Director 后的保存[23]。
六种专项分析的业务例子:给什么材料、产生什么建议、以后怎样用
① 剧情顾问:用户改变选择后,故事怎样继续
analyze_plot 负责分析主线、当前情节和分支是否需要改变。它适合处理“用户拒绝原来的路线”“当前目标卡住”“用户主动提出新方向”等情况,帮助故事承接玩家选择。
例子。 原目标是进北塔找失踪者,用户说:“我不进塔了,先去城门问问昨天的出入记录。”协调器可以给它 reason:“用户改变了调查路线”;focus:“保留寻找失踪者的目标,检查当前情节是否应转向城门调查”。
可能给出的意见:“目标仍是寻找失踪者;接下来可以询问登记官,塔内线索暂时挂起。如果用户继续追问,再引出出入记录中的异常。”这是一份剧情方向建议;用户刚说想去城门,不能据此记录为他已经到达、已经问完并拿到了答案。
后续怎样用: Director 可以把“待推进:查城门记录”“暂缓:进入北塔”整理进状态。后续 Actor 读到后,更容易沿着用户选的方向写下去。
② 人物顾问:让新人物逐步站得住脚
judge_npc 负责人物身份、人数、动机、关系、知识范围、位置,以及合理的进出场路径。新人物出现、同名人物混淆、人物忽然知道不该知道的事,都是它适合检查的问题。
例子。 主角色卡描述一个异世界酒馆,世界书里没有这个人物。用户说:“美国总统出现了,站在酒馆门口,请接着演。”Actor 可以先写他观察四周、与店主搭话;后台则围绕“这个陌生来客怎样在当前世界中成立”分析。下面是一次示意调用,工具名为 judge_npc:
{
"reason": "用户安排了当前状态中没有的新人物:美国总统。",
"focus": "整理已知身份、当前所在位置、关系和知情范围;给出与角色设定相容的性格或来历方向,区分已发生事实与待揭示建议。"
}
可能给出的意见:“已知他是用户称作‘美国总统’的外来者,刚到酒馆;尚不认识店内人物。可考虑让他擅长谈判、表面镇定,但担心身份在异世界失去作用;来路暂留为待揭示线索。”这些性格与来历方向是创作建议,不是代码规定每次都要生成的字段,也不能把‘可能被召唤’直接记成已发生的事实。
后续怎样用: Director 选择应保留的人物事实、关系、待解问题与扮演方向,保存成功后供后续 Actor 使用。当前工具返回分析文字,没有独立的“创建 NPC 小卡”接口,也不会自动新增世界书条目。可以通俗地理解为后台整理人物档案的材料,但本轮回复无需等待一份完整身世。
用户已在 query 点名的人物,本轮后台就能看到;如果是 Actor 本轮临场创造了人物,要等这段正文进入之后的历史,后台才有机会分析。第 15 节另有两种情况的完整时序。
③ 知识审计员:防止角色突然全知
audit_knowledge 负责区分事实、秘密、谎言、猜测与证据,并检查每个角色通过什么途径知道什么。它看的是信息归谁知道、依据是否成立;人物顾问则还要兼顾人物身份和进出场等更广的问题。
例子。 已有历史写明:只有用户和莉娅在密室见过钥匙,守卫当时不在场。用户问:“守卫怎么知道钥匙在我手里?”协调器可以把重点设为:“核对守卫的知情来源,区分亲眼见到、听说和猜测”。
可能给出的意见:“目前没有守卫获知钥匙归属的证据。他可以怀疑或试探,但不能把确切位置当作自己已经知道的事实;用户的提问也不能替代此前缺失的知情过程。”
后续怎样用: 状态可以保留“莉娅知情、守卫未知或仅怀疑”。后续 Actor 让守卫追问,比直接报出密室细节更符合现有材料。专家给出审计意见本身并不能保证模型之后绝不犯错。
④ 世界进展顾问:镜头之外的世界怎样继续
simulate_world 负责因时间流逝或人物分离而需要考虑的日程、位置、期限和场外活动。它让故事里的世界不只随着眼前一句对话静止,但分析仍应建立在已有时间和安排上。
例子。 先前已经说明城门日落关闭,莉娅下午去码头打探。用户现在说:“我和这位总统在酒馆谈了两个小时。”协调器可以要求:“检查谈话时长对城门期限、莉娅的既定行程有什么影响”。
可能给出的意见:“若当前时间已接近日落,应保留赶赴城门的紧迫感;莉娅仍在场外执行此前安排,没有证据证明她已找到线索或已回到酒馆。”如果材料不足以算出准确时间,可以给条件判断,而不是编一个精确时刻。
后续怎样用: Director 可整理期限提醒、场外人物所在位置与待确认进度,让后续 Actor 适时提及暮色或等候中的同伴。这是普通 Agentic 的世界进展建议;Story 有另一套按快照推进事件的世界机制,Visual World 则保存画面外观连续性,三者不是同一份状态。
⑤ 伏笔与承诺管理员:把尚未处理的事记住
manage_callbacks 负责承诺、线索、物品、伤势、义务、伏笔和延迟后果。重点是跟踪“还有什么没兑现、没解释、没归还”,而非每次提到伏笔就必须马上揭晓。
例子。 已有对话中,总统答应“明天带来通行文书”,用户手中还有向莉娅借的钥匙。用户说:“先不说通行证了,今晚休息。”协调器可以让它检查:“哪些承诺需要保留,哪些事情还未完成”。
可能给出的意见:“通行文书承诺仍待兑现,不能记成用户已拿到;借来的钥匙尚未归还。当前休息场景可以暂不追问,在明日会面或再次需要钥匙时再提起。”
后续怎样用: 成功保存的待办与伏笔能帮助后续 Actor 自然回收线索。它不是日历提醒服务,不会仅因账本里有‘明天’就在现实世界自动发消息;是否在某轮提起,还要结合剧情和后续生成。
⑥ 场面导演:这一幕怎么写,谁可以主动
direct_scene 负责视角平衡、镜头方式和角色主动性,工具说明还包含 0–4 的主动性预算。这个数字表达角色主动行动程度的建议,不是回复轮数或 token 数,也不授予角色替玩家决定行动的权力。具体文字指导取决于实际专家 Prompt。
例子。 用户说:“我沉默地看着守卫,等他开口。”协调器可以让它重点看:“让守卫主动回应,但保留用户对下一步行动的决定权”。
可能给出的意见:“镜头留在守卫与用户之间;守卫可以注意到用户没有回答、提出一个问题,或指出当前选择。不要替用户写出‘我承认偷了钥匙’,也不要擅自让用户跟着走进塔。”
后续怎样用: Director 可把场面重点、视角与主动性约束整理进状态,供后续 Actor 控制叙事节奏。它给写作方向;实际正文仍由 Actor 生成。
上面六种用法对应代码中的职责描述;各专家更详细的岗位 Prompt 从 Axon PromptManager 读取,并绑定各自的模型配置。只凭这两个仓库,能确认职责、参数和执行过程,不能把示例输出当成线上 Prompt 保证执行的固定模板。职责和输出约定[24]、专家 Prompt 的加载[25]
Core Tools 0.2.2新增的可选 userPersona 已可供Story工具调用者传入,最多4000字符。当前StoryV1还未把用户人设交给它的世界/叙事工具,所以复用工具的参数能力与现有业务采用分开看;Story原章的实际输入与缺口给出五处调用和源码。
当前剧情能力之二:Story 按世界与事件推进
**Story 是代码编排的剧情工作流,已在 roleplay-harness / main。**应用中的程序协调器按阶段和条件安排下面六个工具;它们接收结构化快照,输出更新快照或写作材料,程序再决定保存。部分工具调用 LLM,执行顺序仍由程序控制。它们有明确可复用类,当前没有自动导出成普通 Agent 的 function-call 菜单。
| 业务步骤 / 精确类名 | 谁触发,准备哪些材料 | 产生什么,交给谁 | LLM / 写入 |
|---|---|---|---|
本轮开始准备:PovPrepareTurnTool |
Story 程序在写正文前,把用户行动与旧世界快照交进来 | 用户意图、事件阶段、当前可展示的背景/暗流、骰子等 prepared 材料;给 Writer 写本轮 | 自由输入可调意图模型,特定同伴分流可调 escort;选择项或已结构化意图可免意图模型。只返回 prepared,不证明事情已发生 |
世界结算:PovAdvanceWorldTool |
正文已被业务接受后,传相同 prepared 和实际正文/选项 | 世界更新、事件、诊断和新快照;交给保存程序与下轮准备 | 可调世界模型提议,机械规则校验应用;pending 保留待结算,duplicate 不重算;工具的 committed 不是数据库已保存 |
新阶段目标:NarrativePlanCycleTool |
快照表示需要新 cycle 时,传已有目标/主副线与世界设定 | 新目标及依赖,保留未完成旧目标;给后续情节分配 | 有 LLM。不是每轮强制制定一份完整大计划,也不生成已发生事件 |
本轮情节分配:NarrativeDealBeatTool |
程序按事件处于开始/发展/收尾调用 | 本轮 pending、情绪指导、主副线方向和偏向;交给 Writer | 纯程序,不调 LLM。 按条件与分数挑选,未满足前置的目标不强推 |
事件结算:NarrativeSettleEventTool |
事件结束/中断且有已接受正文、用户行动、eventId | 哪些目标有证据完成、主副线是否推进、情绪、持续新方向;返回新叙事快照 | 有 LLM 判断,程序校验。unknown 不能当无进展惩罚;重复 event 不重复结算 |
转线:NarrativeRebranchTool |
程序决定随用户持续追求改主线,或替换失去作用的副线;传范围与依据 | 新方向及连接既有进展/未清承诺的过渡理由;交后续目标安排 | 有 LLM;只改副线时不能顺便重写主线。最终持久化仍属业务 |
举例:用户持续离开“修灯”去追查失踪者,程序可以在证据满足后安排转线,把已有钥匙与承诺继续带入新方向。一次随口问“谁寄来的”不自动等于已经换主线。世界结算关注世界状态,事件结算关注叙事目标是否兑现,两份结果要按 Story 流程保存,不是六专家建议自动替代它们。精确日志名与类名见Story 六类接口;实际 action/writer 输入和 pending 失败见Story 请求节选。
当前视觉能力:画得出来,还要画面保持一致
| 能力 | 谁调用 / 材料怎么走 | 保存什么、解决什么问题 |
|---|---|---|
prepare_visual_world |
选中配图后,宿主通过图片接线准备;读取角色、会话分支与既有视觉状态 | 让图片提示词有外观和场景依据,例如衣着、道具和布局 |
| 图片提示词生成 | 程序调用模型,输入 Actor 片段及视觉资料;此请求关闭自由工具选择 | 生成本次画面的描述,交给图片服务;不是交给六位专家来画 |
MCP generate_image |
后端图片执行路径使用消息 ID、图槽位等信息请求图片服务 | 生图并补到对应消息,完成与前台文字不是同一时刻 |
commit_visual_world |
本轮成功且做过视觉准备后,宿主回合结束 hook 后台调用 | 依据本轮最终输出文本维护视觉连续性,写到已保存 assistant 消息的 narrative 数据;例如后续画面保留被雨淋湿的衣服 |
| Sumi 初始视觉状态 | 宿主让视觉模型读取角色参考图与相关设定,建立初始锚点 | 按材料 fingerprint 保存初始状态供复用;不调用普通 NPC 专家 |
| Sumi 逐轮图文与状态 | 主模型生成 Sumi 协议,宿主解析正文、状态和图片描述 | 保存每条 assistant 对应的前后快照、模型文本、可见正文和图片信息;这不是前台四工具的 function call |
| Sumi 历史恢复 | 启用 history import 时,宿主校验历史与已存快照 | 选取正确分支的起点;不能把不兼容历史随意合并到当前状态 |
| Sumi 图片交付 | 宿主等待正文保存并校验消息锚点,再生成、保存和通知 | 配置 imageGeneration 才走真实生图;参考图占位不能当作已经生成新图。图片交付记录与本轮状态分开维护 |
**普通当前消息配图有一个已核边界:**Imagine 先保存 pending 图槽再请求下游;若请求尚未成功送达就失败,当前路径没有失败回写或自动恢复任务,图槽可能一直 pending。见失败发生在哪一步、留下什么。Sumi 的 claim/恢复机制不能套到这条链。
图片里的外观状态、Story 世界快照、普通 Agentic 连续性状态是三份不同用途的数据。 “工具都在同一个仓库”不等于“人物换衣服后,三份数据自动同步”。Sumi 的初始化与逐轮输入输出、快照保存字段与图片交付失败分别有对应流程。
依据:视觉准备与整轮提交[26]、图片 MCP 菜单[27]、Sumi 逐轮运行[28]、Sumi 状态保存[29]。
视觉保存与交付依据:实际传入的本轮文本[30]、Visual World 消息存储[31]、Sumi 图片交付[32]。
可复用工具:换一个业务时怎样接
| 已有封装 | 可以拿来做什么 | 接入时要提供什么 | 当前 RP 的接入事实 |
|---|---|---|---|
get_memory / update_memory |
让自建 Agent 读写一份 JSON 记忆,例如用户偏好或 NPC 草稿 | 授权范围内的 store、版本与完整新对象;可选接入业务校验;更新是整对象替换 | Pi 工具工厂和示例已存在;13c481b 另有独立隔离调试接线,仍未自动注册进普通 RP 已实现的菜单,也不替代日记或导演状态 |
AxonJsonMemoryStore |
为新业务把独立 JSON 数据存到 Axon | 用户、会话、namespace、key,再按 get/CAS 读写 | 存储适配器已存在,当前应用未见实例化;它与普通 Agentic state 使用不同的存储范围 |
generate_image_asset |
独立生成头像、道具等图片资产 | prompt、可选参考图/数量/尺寸,以及宿主注入的图片生成接口 | 有独立封装、可选 MCP 暴露;13c481b 调试 worker 可真实调用 staging 生图。它不是前台 generate_image 的另一种参数,会话归属和展示仍需接入 |
六专家的独立调用与 toPiTool |
在已有业务里只复用人物/剧情等一种分析 | 模型、岗位 Prompt、授权上下文;自定义材料可用上下文编译接口 | 专家已在普通 Agentic 使用;把它装进另一个 Agent 的 Pi 适配、保存和调度仍须业务明确接入 |
ReadMemoryTool / WriteMemoryTool 与 Tool hooks |
复用存储读写、执行前后校验与整轮收尾 | 宿主 store 的 get/CAS、授权范围和相应生命周期调用 | 普通 Agentic 内部用存储封装;不是其模型菜单里的额外两个函数,也没有自带数据库。整轮 hook 须由宿主显式调用 |
selectPreActorSkill / createPreActorDirectorHook |
先让模型选一个预设,再按预设运行 Actor 与后处理 | skill 列表、Actor 参数、afterActorTools 与 hook 装配 | 仓库有 actor({skill}) 的预选实现,但当前 dispatch 的 preActorDirector 配置实际装配的是前台 function loop;不能据相似名称认定此 hook 已运行 |
McpCapability / CapabilityExecutor |
把指定 MCP 能力接进静态执行图 | 服务、操作、输入映射、依赖和结果投影 | aoi.observe_scene 是仓内示例;当前 closed-loop 是空执行图/空 capability 列表,不是已经运行中的场景观察或查书工具 |
| SDK Agent、Slow、FastSlow | 为另一项业务自定义模型与工具循环,或复用已有快路 Workflow | 工具/capabilities、模型、状态 store、需要时的提交回调与持久任务封装 | 这是运行框架,不是新增业务工具;不会自动获得 Emochi 的全套能力与配置 |
这里的“可以拿来”表示具备可复用基础,不代表无需开发。比如 JSON store 能放 NPC 对象,但仍缺人物的字段设计、身份与分支范围、生成/修改规则、读入模型的位置;不能把通用存储能力直接当成完整 NPC 产品。
依据:包的公开入口[33]、JSON 记忆[34]、图片资产[35]、Pi 桥接[36]、预选 hook 实现[37]、当前实际装配[38]、静态能力示例[39]。
存储与生命周期依据:读写封装[40]、Tool 生命周期[41]。
独立 JSON 适配依据:AxonJsonMemoryStore[42]。
具体契约统一查JSON、图片资产与复用接口。独立专家放在回复前并等待,就增加本轮延迟;放后台,就由后续消费保存好的结果。仅安装工具不会取得现有应用的后台调度、世界书输入与存储。
没调用、调用失败、调试成功,各能说明什么
后台可以判断这轮没有值得更新的内容,保留旧状态。某位专家失败也不必然使整次后台停止:后续仍可能依据其他材料整理;但失败分析不能当成成功事实。Director 失败、候选不合法或版本提交冲突,则不能宣称这份新状态存好了。
图片安排成功不等于图片已生成或允许展示;DIO 接收成功不等于长期指令已生效。每种能力应看最终落点,而不是只统计“工具调用了一次”。
想先判断工具能否解决问题,可以走独立调试入口:给人物检查一份角色与对话,看它能否区分事实和猜测;给 JSON 工具一份测试对象,看修改前后差异。目录现有六专家、Director、两个 JSON 记忆工具及一个图片资产工具,共十项。模型和图片会真实请求外部服务;测试记忆及 Director 状态在本次隔离环境里,测试通过不会直接改玩家会话或发布生产配置。
调试的十项精确目录、准备/执行/取消、签名快照和返回字段统一看调试接口。试跑成功不等于发布生产 Prompt;worker 没有配置发布接口。
从这份清单能做哪些产品判断
下面是基于接线事实作出的业务判断;“还需补什么”是实现该产品目标所需的工作,不是仓库已经保证的能力。
| 你想达到的业务结果 | 当前已经有的基础 | 还不能直接承诺什么 / 需要补哪一环 |
|---|---|---|
| 新角色先出场,后台逐步完善 | Actor 与人物分析并行,Director 可保存连续性状态 | 不能直接承诺独立、可编辑、可检索、可跨会话复用的 NPC 卡;需要定义实体、字段、保存与读取链路 |
| 后台分析严格遵循本轮世界书 | 世界书选择和 Actor 注入已存在 | 后台没自动收到同批原文;需明确哪些世界观材料进入 Planner/专家,及其预算和权限 |
| Planner 缺资料时自己决定查世界书 | 世界书有检索/选择服务,宿主已能按轮调用 | 当前后台菜单没有主动查书函数;若需要“分析到一半再查”,还要注册相应工具、限定书与版本、把返回材料接回分析过程 |
| 从聊天自动扩展世界书 | 有世界书创建/修订接口,有人物与剧情分析 | 没有自动发布链路;需区分临时剧情事实与作者设定,定义发布、冲突、版本及旧会话生效规则 |
| 用户只管提要求,系统自动挑全部工具 | 各场景有自己的菜单与程序调用链 | 目前先选场景、且有互斥组合;跨场景能力组合与路由仍需设计,不能靠名字齐全来保证 |
| 所有长期内容永不矛盾 | 有 Agentic state、Story、记忆、视觉状态和世界书各自的保存机制 | 未自动合成一份总状态;需明确各类事实的保存归属,以及跨模块何时读、何时同步 |
| 使用现成工具就能保证任务完成 | 有执行结果、版本提交、观测及可复用参数校验能力;普通 Agentic 未开启严格参数校验 | 还要分别确认调用成功、数据存好、正确版本被读取、正文实际采用;工具返回成功只覆盖其中一段 |
因此,评估一个新需求时,先沿着“用户希望发生什么 → 当前哪条场景能做 → 哪些步骤已接 → 输入是否够 → 结果放哪 → 什么时候被用到”检查。再决定复用哪个工具或补哪段接线。第21章保留参数与执行边界,第15章展开人物时序。
候选能力边界:AOI/Pioneer、图文格式与历史验证范围
以下是 2026-09-17 历史核查:参照 Harness 13c481b、Worldbook b0af622,候选为 Pioneer 61039e5、图文格式 44ffcf1。本次未重新确认远端或生产。PR 巡检及演变过程统一看第23章与第24章;这里保留会改变“能否直接拿来用”的独有能力和边界。
真正还在候选分支里的能力,业务上有什么用
| 已开发的工具或能力 | 谁调用,拿什么做什么 | 保存在哪里、影响哪一步 | 一个 PM 能理解的例子 |
|---|---|---|---|
图片准备:prepare_image_asset → prepare_image;另有 parse_image_prompt 校验绘图块 |
图片执行程序传入图像描述块、视觉状态、角色参考图和画风;复用 AOI 解析器,编译成生图 Prompt、参考图列表、比例和尺寸 | 本身是准备与解析,不把新人物写入世界书;结果交给当前图片任务 | “总统坐在酒馆里”先变成可画的镜头描述。只对应该人物的参考图进入任务,避免拿主角头像画成总统 |
视觉状态操作:initialize_state、apply_state_patch、render_state |
Visual World 程序先取得初始化模型或 Producer 的输出,再交 AOI 代码解析、应用变化并渲染状态 | 宿主保存 visual state / 前后状态;用于当前准备和后续视觉连续性,操作函数本身不负责持久化 | 记住谁还在场、衣着和场景发生什么变化。这里的视觉人物记录不等于具有身世、性格、发布版本的完整 NPC 卡 |
本轮图片工具:AoiImageTool |
前台的配图动作或 visual beat 后的自动安排进入它;读取刚完成的 Actor 段落、角色卡、视觉状态和资产投影,调用图片 Prompt Producer | 按图片槽位组织准备与生成;回合完成后安排视觉状态收尾。与当前回复配图相关 | 正文先让总统坐下,再为这一幕准备图;启用相应图文生成与交付时,特定 AOI 解析、初始化或状态补丁错误可记录为失败槽位,保住正文及其他图,不要求先丰满人物再开口 |
生成、审核和消息回写:AoiImageExecution + EmochiImageAssetTools |
程序用准备好的 Prompt 调已有 createImageAssetTool 和 Axon image.generate,检查图片审核结果,再回写并推送 |
图片尝试记录在 Axon JSON memory;图片结果关联所属消息和槽位。重复请求复用已记录结果,结果不确定时不盲目再次生图 | 第二张图超时后,保留失败/未知状态;重试不能让第一张图重复生成或串到另一条回复。现有通用生图工具已在 main,候选新增的是这套业务执行与交付链 |
图文正文解析与独立聊天入口:parse_narrative / Narrative API |
程序把 Actor 的图文输出拆成可见正文、段落与图片 Prompt;入口另外调用历史准备、消息保存、通知及按配置执行的正文计费接口 | 保存并核对消息后交付;独立支持 chat、continue、regenerate、edit-regenerate | 重生成一条回复时,文字、图片和后续补发围绕同一条新消息组织。它是业务入口,不是让 LLM 任意调用消息删除或钱包接口 |
| 后台状态跟随回复分支(接线能力,不是新模型工具) | 加载状态时核对可见 assistant、正文 hash、用户锚点和 snapshotRef;后台计算后等待正文已保存,再按版本提交与挂接 | Axon 状态快照 + 消息关联;主要影响后续轮读取哪份状态 | 玩家把“总统离开”重生成“总统留下”,后续不应继续拿被替换回复所属的旧状态。这只绑定保存结果,没有给已启动的 Planner 追加本轮新正文 |
图片主色提取:createNodeImageColorTool |
图片交付程序把生成且审核通过的图片 URL 交给已有 Node 接口取主色 | 用于图片交付展示;失败用默认颜色,不把已生成图片判为失败 | 图片出现时给客户端提供匹配的背景颜色。它不参与人物判断或剧情推进 |
这些是一组工具与业务接线,不是“七个新的慢系统工具”。前台可选菜单仍围绕 actor、generate_image、schedule_dio、over;AOI 的解析、状态、存储和通知主要由宿主程序调用。视觉状态能力本来在 main 就有,候选新增的是复用 AOI 实现及把它纳入这条生命周期,不能说 main 原来完全没有世界状态或生图。
依据:AOI 工具名与调用封装[43]、六种内部操作及编译[44]、本轮图片工具[45]、实际生成与尝试保存[46]、资产交付[47]、Narrative 入口[48]、状态绑定[49]、主色工具[50]。
分支差异会影响接入,不能串成一条现成链
- Pioneer
61039e5当时仍与 main 分叉,较旧071eb76新。PR #147 当时 Draft、未合并,head28989d9,目标为codex/aoi-fusion-integration,不是 main。 - 图文格式
44ffcf1当时也与 main 分叉,分支表未关联开放 PR。它用chatStream/chat、段落锚定、generate_image_list_v2原生消息字段和 Axon 私有图片状态;这是另一条接法,不能与 Pioneer 拼成已接通的单一链路。 - 格式分支记录明确:原生单图重试未进 Fusion,端到端验收未完,chat 和 edit-regenerate 没在那次最终原生运行重验。原核查只读代码与记录,没有重跑或确认生产。
候选中保留 ImageWalletTool.reserve / commit / rollback 和测试,可调用已有 Node 图片额度/扣费接口。但当前 AOI 图片执行已经移除它的实际调用,只兼容读取旧尝试里的 wallet 状态;应用源码未发现创建该类的生产接线。因此应标为 “候选中已开发、当前候选执行链未使用”,不能画成当前每次生图必经的钱包工具。正文的 wallet.charge 是另一条流程,不能混为一谈。钱包实现[51]、图片执行中的旧记录兼容[52]。
旧 PR #115 的 Pi 专家适配方案有实现,但已 Closed / unmerged。关闭说明指出旧根包方案与现行分包结构冲突,需要按新边界重做。当前 main 已有 toPiTool 与 /pi 导出,所以这是被关闭的旧接法,不能把它当成正在等待合并的新专家能力。main 现有 Pi 适配[53]。
已在 main,不应按旧 PR 状态误算为缺席
- Actor、DIO、Imagine、生图 MCP 核心已经 #108 整合;当时 #78 仍 Open 不代表整套能力尚缺。
- Worldbook #7/#8、Harness #168 已合并;八插入位置仍需宿主能力声明、书 revision 和模板配合,不自动迁移旧会话。
- Core Tools 隔离调试、Pi 观测、JSON 记忆、Story 和六专家有 main 实现。某个场景未注册,不等于分支未合并。#159 是 SDK 文档,#110 是移除生产 AutoMemory 场景配置,不是两种新工具。
- 当时世界书为 0 个开放 PR、8 条远端分支,7 条功能分支关联 PR 均 Merged;这个范围不覆盖开发者未推送的本地代码。
这些候选主要补图片交付与消息分支状态归属,没有补齐“依据完整世界观自动建立、校验、保存并发布 NPC 小卡”的闭环。
固定源码与历史巡检证据:其余原链接
保留原章节的独有证据链接,方便继续查实现;不表示本次刷新 PR 或部署状态。
- apps/emochi/story/coordinator.ts#L195-L259(13c481b)[54]
- apps/emochi/story/coordinator.ts#L390-L418(13c481b)[55]
- apps/sumi/runtime.ts#L129-L192(13c481b)[56]
- apps/emochi/planning/agentic-v2.ts#L879(13c481b)[57]
- apps/emochi/actor/roleplay-runtime.ts#L87(13c481b)[58]
- apps/emochi/worldbook/runtime.ts#L47(13c481b)[59]
- apps/emochi/server.ts#L751(13c481b)[60]
- apps/emochi/tool-debug/catalog.ts#L15(13c481b)[61]
- apps/emochi/actor/roleplay-runtime.ts#L87(77a1537)[62]
- apps/emochi/planning/agentic-v2.ts#L335(77a1537)[63]
- apps/emochi/tool-debug/catalog.ts#L15-L24(13c481b)[64]
- apps/emochi/tool-debug/catalog.ts#L82-L149(13c481b)[65]
- apps/emochi/tool-debug/host-tools.ts#L70-L139(13c481b)[66]
- apps/emochi/tool-debug/worker.ts#L811-L851(13c481b)[67]
- apps/emochi/tool-debug/server.ts#L58-L101(13c481b)[68]
- apps/emochi/tool-debug/worker.ts#L313-L345(13c481b)[69]
- apps/emochi/tool-debug/worker.ts#L647-L662(13c481b)[70]
- docs/tool-debug-worker.md#L63-L74(13c481b)[71]
- docs/tool-debug-worker.md#L86-L98(13c481b)[72]
- apps/emochi/story/coordinator.ts#L247(77a1537)[73]
- packages/tools/src/modules/story/world.ts#L114(77a1537)[74]
- packages/tools/src/modules/story/narrative.ts#L48(77a1537)[75]
- apps/emochi/server.ts#L718(77a1537)[76]
- apps/emochi/planning/runtime.ts#L569(77a1537)[77]
- 历史 PR #147
- 固定提交 61039e5
- 固定提交 44ffcf1
- docs/decisions/2026-09-16-fusion-sumi-format.md(44ffcf1)[78]
- apps/emochi/tools/narrative-tools.ts#L10(44ffcf1)[79]
- 历史 PR #78
- 历史 PR #108
- 历史 PR #7
- 历史 PR #8
- 历史 PR #168
- 历史 PR #159
- 历史 PR #110
代码证据 · 79 处
- 前台调用条件与执行 ↗
- 图片任务与消息回写 ↗
- DIO 接收与等待 ↗
- 图文与 DIO 的装配条件 ↗
- 前置材料 ↗
- 后置正文处理 ↗
- 快捷回复生成 ↗
- 统一入口与空绑定处理 ↗
- 当前配置组合 ↗
- 本轮选择与注入 ↗
- 当前逐轮绑定解析 ↗
- Demo 接口与读书范围 ↗
- 服务导入与创建 ↗
- 修订和索引入口 ↗
- Axon Go 与 shadow 读写 ↗
- Personalization hooks ↗
- Hinos ↗
- 日记触发 ↗
- Compact ↗
- 世界书场景配置 ↗
- 专家职责、输入和结果 ↗
- 按需选择与强制规则 ↗
- Director 后的保存 ↗
- 职责和输出约定 ↗
- 专家 Prompt 的加载 ↗
- 视觉准备与整轮提交 ↗
- 图片 MCP 菜单 ↗
- Sumi 逐轮运行 ↗
- Sumi 状态保存 ↗
- 实际传入的本轮文本 ↗
- Visual World 消息存储 ↗
- Sumi 图片交付 ↗
- 包的公开入口 ↗
- JSON 记忆 ↗
- 图片资产 ↗
- Pi 桥接 ↗
- 预选 hook 实现 ↗
- 当前实际装配 ↗
- 静态能力示例 ↗
- 读写封装 ↗
- Tool 生命周期 ↗
- AxonJsonMemoryStore ↗
- AOI 工具名与调用封装 ↗
- 六种内部操作及编译 ↗
- 本轮图片工具 ↗
- 实际生成与尝试保存 ↗
- 资产交付 ↗
- Narrative 入口 ↗
- 状态绑定 ↗
- 主色工具 ↗
- 钱包实现 ↗
- 图片执行中的旧记录兼容 ↗
- main 现有 Pi 适配 ↗
- apps/emochi/story/coordinator.ts#L195-L259(13c481b) ↗
- apps/emochi/story/coordinator.ts#L390-L418(13c481b) ↗
- apps/sumi/runtime.ts#L129-L192(13c481b) ↗
- apps/emochi/planning/agentic-v2.ts#L879(13c481b) ↗
- apps/emochi/actor/roleplay-runtime.ts#L87(13c481b) ↗
- apps/emochi/worldbook/runtime.ts#L47(13c481b) ↗
- apps/emochi/server.ts#L751(13c481b) ↗
- apps/emochi/tool-debug/catalog.ts#L15(13c481b) ↗
- apps/emochi/actor/roleplay-runtime.ts#L87(77a1537) ↗
- apps/emochi/planning/agentic-v2.ts#L335(77a1537) ↗
- apps/emochi/tool-debug/catalog.ts#L15-L24(13c481b) ↗
- apps/emochi/tool-debug/catalog.ts#L82-L149(13c481b) ↗
- apps/emochi/tool-debug/host-tools.ts#L70-L139(13c481b) ↗
- apps/emochi/tool-debug/worker.ts#L811-L851(13c481b) ↗
- apps/emochi/tool-debug/server.ts#L58-L101(13c481b) ↗
- apps/emochi/tool-debug/worker.ts#L313-L345(13c481b) ↗
- apps/emochi/tool-debug/worker.ts#L647-L662(13c481b) ↗
- docs/tool-debug-worker.md#L63-L74(13c481b) ↗
- docs/tool-debug-worker.md#L86-L98(13c481b) ↗
- apps/emochi/story/coordinator.ts#L247(77a1537) ↗
- packages/tools/src/modules/story/world.ts#L114(77a1537) ↗
- packages/tools/src/modules/story/narrative.ts#L48(77a1537) ↗
- apps/emochi/server.ts#L718(77a1537) ↗
- apps/emochi/planning/runtime.ts#L569(77a1537) ↗
- docs/decisions/2026-09-16-fusion-sumi-format.md(44ffcf1) ↗
- apps/emochi/tools/narrative-tools.ts#L10(44ffcf1) ↗
15. 新人物突然出现:本轮先接住,后台整理人物
**本章是第14章工具目录的一次组合使用案例,不是一类新工具或新的执行模式。**使用的是已接好的Actor、普通后台人物分析和状态保存;用户安排新人,只会触发现有流程里的判断,不会动态安装NPC工具或自动创建世界书条目。可用工具总清单看第14章,支持的业务玩法看项目总览。
用户说:“一位陌生使者站在北塔门口,请让他接着说话。”世界书里没有这位人物。产品要同时满足两件事:这一句能继续演,之后又不能每次都把他写成不同的人。 当前普通 Agentic 的接法是回复与后台并行,不要求先生成完整身世再开口。
下面用一位虚构使者走完;同样适用于用户之前举的“美国总统进入异世界”例子。身份名称变了,工具的输入、保存与时序不会因此自动增加一张人物卡。主层按固定 main 3b99f4c 核对,候选分支另列。
本轮先让人物做什么,哪些内容还不能认定
假设角色卡已经设定“旧城北塔;守卫谨慎核验来访者”,用户只明确了使者出场。Actor 是负责用户当前正文的模型,它收到角色设定、历史、旧状态、本轮输入及这个场景提供的其他材料,可以先写:
陌生来客停在门槛外,抬手示意自己没有敌意。“我来找值守的人。”守卫没有立刻让路。
这样已经承接用户安排,不必先解释他出生在哪、为什么跨越世界或与谁有多年旧识。这是一种可能的生成结果,不是固定模板。新的人物动作以写出的实际正文为准,后台不会提前保证它一定这样演。
同时,后台拿到的是本轮开始时的材料。用户已说的“使者在门口”它能看到;Actor 刚临场写出的“抬手示意、要求见值守者”它这次看不到。因此后台应区分:用户已经确认的人物位置、尚未确认的身份来历、之后可以采用的创作建议。
谁决定找人物专家,它拿到什么
普通后台协调器会根据本轮材料和可用工具菜单选择检查。程序也有首轮、新名字补人物检查的规则,前提是这项能力已启用并能在执行预算内安排。它不是每出现任意新称谓就必定识别;这次例子假设协调器选中了人物检查。首轮、启用名单与低预算条件可直接看补调用规则。
发给 judge_npc 的任务可以用人话读成:
为什么找你:用户安排了此前状态中没有的来客。
重点检查:他是谁、在哪、与现有人物有什么依据支持的关系、知道什么;来历不明就保留未知。
Harness 再补入角色设定与开场白、可选用户人设、旧状态与有限记录、近期对话、本轮输入,加上人物专家的专项工作说明,调用模型。“基于世界观”意味着世界观必须真实出现在这些材料中。 当前 Actor 收到的世界书原文不自动同步给专家;工具也不会因为人物缺资料就自行查世界书或网络补完。具体字段、角色原设定从哪取,以及近期历史条数,见实际输入合同。
专家交出的不是小卡,而是一份分清事实与建议的分析
本例可能交回:
已有依据: 用户称他为使者,目前站在北塔门口。
仍然未知: 姓名、代表谁、为何来到这里、与守卫是否认识。
连续性要求: 后续继续当作同一名来客;没有依据就不要突然说他是守卫的老朋友。
可选创作方向: 可通过下一次问答逐渐透露任务;保持谨慎举止,但不要把尚未发生的问答当成既成事实。
“可选方向”帮助以后扮演,并不是世界事实。人物专家的能力是分析身份、关系、知识、位置与进退场,不是保证每次填写固定姓名、性格、背景字段;详细岗位提示来自外部配置,仓库本身不能证明线上一定使用“完整小卡生成”模板。完整分析示例列出事实、未知和可选方向各怎样表达。
分析怎样变成下一次可以读的材料
有检查结果且允许更新状态时,协调器再决定是否整理。Director 是整理剧情状态的模型岗位,负责把旧状态和有用建议写成一整份新稿。例如保留旧塔门状态,再加入:“新使者在门外;身份与来意待证实;不要重复新增同一个人。”
程序检查格式、长度、内容是否变化,再按旧版号尝试保存。成功时,当前会话状态更新,还可留下人物分析的分类记录;未来准备回复时,程序会把有限长度的状态与记录文字放入 Actor 输入。Actor 因而有机会继续同一人物,而不是每轮重新发明。保存字段和后续读取给出人物账本的具体 key、payload 与失败边界。
这不是改世界书,也不是建立一个可独立编辑、检索、跨会话复用的 NPC 实体。后台新稿未采用或版本冲突被拒绝时,不会用它覆盖较新记录;一般保存报错或超时需核对存储结果,不能仅凭失败回包认定已经写入或完全没写入。某位专家失败时,Director 仍可能利用其他材料更新,只是失败分析不能作为成功记录。即使存好了,下一句来得比后台快,也可能先读旧版本。
当前可以描述的能力是“先承接出场,后台为后续一致性整理人物”。 如果产品要一张真正可管理的小卡,还需明确人物 ID、字段、事实与候选设定、保存范围、修改权限,以及哪一步将卡片交给模型。
如果新人是 Actor 自己临时写出来的,什么时候才轮到后台知道
换一种输入:用户只说“我走进岗亭”。Actor 这一轮自己写出一位从未出现的使者。因为后台已经使用起始材料启动,它不能可靠地分析自己尚未收到的人物。
这时通常需要:本轮正文先保存 → 下一轮把它带入历史 → 后台才有机会识别并分析 → 整理保存成功后,更后面的回复读到新状态。 下一轮 Actor 已能从历史承接使者出场,但那不等于人物审计已经完成。若后台更晚保存,采用也会更晚。
名字检测只扫描有限的近期消息与本句,使用规则提取候选名并与状态文本对照;别名、称谓和句式可能漏检,协调器也可能自行选人物检查。它不是一个能保证所有人物都有唯一档案的识别系统。哪些句式会命中或漏掉已有直接样例。
**如果同时给新人配图:**先有正文再安排图片,不等于已交付可用人物画像。普通 Imagine 在写入 pending 图片位后、下游请求交接前失败,当前可能没有失败回写或恢复任务;这不影响“人物分析不是小卡”的判断,也不能与 Sumi 恢复机制混算。具体失败过程。
候选分支补了什么,还没有补什么
第24章单独核验的候选分支把后台状态提交与已保存的助手正文、正确消息分支挂接,试图避免重生成后读到另一条回复所属的旧状态。它保留并行分析,没有把本轮新正文自动追送进已启动的后台,也没有让 Actor 等完整 NPC 卡。
“已保存正文”也不等于玩家点击接受。候选接线应单独验收,不能作为当前 main 已有完整建卡与人物事实审查的证明。
普通后台并行调度[1];人物检查职责与输入[2];首轮和新名规则[3];Director 整理与提交[4]。
原“美国总统”例子:两种时序、名字检测样例与固定证据
历史固定依据:并行调度与固定输入[5]、Actor 开始即调度[6]。
情况一:用户已经明确安排“美国总统”出场
以下是虚构剧情示例:角色卡设定为“异世界的边境酒馆,偶有异乡人出现”,世界书没有“美国总统”这条资料。用户在第 N 轮说:“美国总统出现了。他站在酒馆门口,请接着演。”
| 发生在哪一步 | 这一轮实际做什么 | 玩家感受到什么 |
|---|---|---|
| 本轮准备 | 读角色设定、历史与起始状态;快慢各自组装材料 | 还没有等待 NPC 专家建档 |
| Actor 生成 | 可以写“门口的陌生来客整理衣领,先观察四周”,承接已给出的出场安排 | 剧情继续,不必先交代童年、性格全貌和穿越机制 |
| 并行后台 | 协调器选择专家;代码也会检查近期可见文本中的新名字,命中时补上 judge_npc |
后台审计不阻塞这段回复 |
| 整理与保存 | 专家给建议;Director 生成完整候选状态;格式与版本校验通过才保存 | 本轮已开始生成的正文不会因此重写 |
| 后续轮准备 | 读取当时已经保存成功的状态 | 如果保存赶在 N+1 轮准备之前,该轮可使用新整理;否则更晚 |
这条链路不是每隔 X 轮才启动。普通 Agentic 的慢规划随该次逻辑生成启动一次;协调器决定哪些专家值得用。第一轮、以及检测到起始状态没有的新名字时,代码会补上人物审计,前提是 judge_npc 已启用。第一轮还会补上已启用的 direct_scene。执行仍受工具预算约束:在 enforce 模式下,强制工具优先排入,但极低预算仍可能截去后面的调用。强制条件与执行顺序[7]
情况二:用户没点名,是 Actor 在正文中临时创造了人物
用户只说“我推开酒馆的门”。第 N 轮 Actor 自己写出“美国总统坐在角落”。这一轮后台不知道刚写出的这句话。 它不能针对尚未出现在自己输入中的人物,可靠地开展补全。
时序因此是:N 轮 Actor 写出人物 → 业务保存这段正文 → N+1 轮把它带进历史,后台才有机会识别并审计 → 保存成功后,N+2 或更晚的 Actor 才读到这份后台整理。 N+1 的 Actor 仍能直接从聊天历史知道这个人已经出现,只是还没有这次新审计的持久状态。
“有机会”有具体含义:代码用多语言正则扫描最近 4 条 user/assistant 消息加当前 query,再看候选名称是否已出现在起始 state 文本中。它不是完整的语义人物识别器,称谓、别名和句式都可能导致漏检或误判;没命中强制规则,协调器仍可自行选择人物工具。对最新函数直接运行样例:美国总统出现了、这是美国总统能提取到“美国总统”;让美国总统承接剧情没有命中。I meet John Smith只提取 John。这里也没有查询世界书来确认“这个人是否已经建卡”的步骤。名字检测[8]
人物工具准确参数、输入范围、分析与账本格式
NPC 工具怎么调用,它到底得到什么
judge_npc 的接口声明要求 reason,可选 focus;角色卡、历史、状态由运行时补入。不过普通 Agentic 后台没有开启严格参数 schema 校验,不能把“声明必填”理解为缺参一定在执行前被拒绝。下面是虚构调用示例,不是线上抓取:
{
"reason": "用户安排了起始状态中没有的新人物:美国总统。",
"focus": "确认身份称谓、所在位置、与酒馆人物的关系和已知信息;来历未明时保留未知,不把猜测写成既成事实。"
}
它实际获得:当前主角色的名字、描述、原始定义、开场白;当前 Agentic 状态及账本投影;最近 9 条有效可见消息;最新 query;上面的 reason/focus;若存在,还包括用户 persona 与 Compact 摘要。它没有收到“全仓库工具”“世界书全库”,当前选中的世界书原文也不会因 Actor 已收到就自动传给专家。参数定义[9]、专家材料组装[10]
“基于这个卡的世界观”也有明确来源:优先取业务返回的 prompt.init_prompt;没有时才拼接角色卡的 personality、scenario、summary、system_prompt,另带 description 与 opening message。世界观若只存在于本轮世界书注入、没有进入这些材料,不能假定 NPC 专家也知道。 专家具体写作要求从 Axon 的 PromptManager 读取;这两份仓库本身不能证明线上一定使用某份“生成完整 NPC 小卡”模板。角色设定来源[11]、运行时专家提示词[12]
“补小卡”在代码里对应什么结果
judge_npc 返回的是分析文本,没有独立 NPC 卡的固定字段,也不会直接创建世界书条目或写状态。下面仍是虚构输出:
已确定:用户称其为美国总统;现在站在酒馆门口。
身份待确认:具体姓名、任期、是否为真实本人均未说明。
关系与知识:尚不认识店内人物;不能默认知道当地秘密。
可选性格方向:擅长谈判,表面镇定,但担心身份在陌生世界不再有用。
可选来历方向:把来路作为待揭示线索,后续用一次询问或事件建立。
后续扮演建议:先以陌生来客的谨慎观察接话,通过后续互动逐步建立细节。
未知:如何来到这个世界;不要直接写成“昨晚被法师召唤”。
上例的性格、来历方向是虚构的创作建议,说明分析可以怎样帮助后续扮演;它们不是必填字段,也不是这次出场已经证明的事实。是否提出、采用和怎样采用,取决于实际专家 Prompt、模型结果与 Director 的整理。
这份建议交给 Director,与原状态及其他专家结果合并。Director 产出完整候选状态,可能更新“Active relationships and NPCs”“Social graph and NPC lifecycle”“Knowledge boundaries”等段落。只有候选有效、有变化且版本写入成功,才同时保存状态与本轮成功专家的账本记录;NPC 分析记录形如 type=npc、key=judge_npc:turn:N、payload.analysis=分析文本。它是“供后续回复维持人物一致性的记录”,可以通俗叫人物小档案,但不能理解为已经有了一张可独立编辑、检索和复用的 NPC 实体卡。工具只给建议[13]、Director 的合并要求[14]、保存状态与账本[15]、账本结构[16]
如果 NPC 专家失败,可能返回 ok:false;Director 仍可能依据已有材料整理状态,失败专家不会生成成功分析账本。如果 Director 没启用、候选无效或没变化、版本冲突或保存失败,就没有这次新人物整理的完整落库保证。即使保存成功,Actor 读的是有长度上限的投影,并非无限量人物档案。产品上应承诺“先让剧情继续,后台维护后续一致性”,不能承诺“每个新人物当场自动生成完整身世,并保证下一句马上采用”。专家失败返回[17]、下一轮使用的投影限制[18]
候选分支改变了什么
第 24 章核验的候选分支保留上述并行分析和 NPC 工具契约,但把状态提交与已保存的 assistant 正文、可见消息分支绑定。它仍不会让 Actor 先等一张完整 NPC 卡,也没有让已经启动的 Planner 自动看到本轮新正文。此处“已保存”不等于用户点击接受。
16. 图片、长期指令与Sumi各自怎样运行
“给这句话配张图”“以后换一种说话方式”“连续图文角色扮演”,看起来都可能在后台处理,完成后改变的东西却不一样:图片补到当前消息,长期指令改变以后输入,Sumi 则维护自己的逐轮图文状态。
下面用三个目的分别走完。它们由业务提前选择和接线,不会因为用户同时提了三种要求,就自动组成一条全功能链路。Sumi 原有归档沿 3b99f4c 固定证据;普通 Imagine 的失败边界本轮按 fa41d220 补审。具体接口、并发恢复和旧证据可展开。
我想给这次回复配图:先有可画的文字,再把图补回来
假设当前方案已开放图文前台。用户说:“写守卫接过铜钥匙的反应,并配张图。”前台控制模型会看用户需求和可用菜单,让 Actor 实际写 RP 正文。选择 complete 片段时,可以随后调用空参数的 generate_image;选择 visual_beat 且形成可用完整片段时,若循环仍有下一步可执行,程序会先自动安排图片,再让控制模型继续决定动作;恰好用尽步数时不能保证这次自动调度发生。同一片段已经配图,就不能再重复安排。
例如 Actor 写出:“守卫举起钥匙,火光映在铜纹上。”图片步骤拿到的不是一句孤立的“画图”,而是这段文字、角色外观、参考图和可用视觉状态。程序把它们交给绘图描述模型,再把描述与相关参数交给图片服务。
前台收到“图片已安排”就可继续文字,不必等外部图片生成完成。图片任务会等所属助手消息已保存,再将图片位置、待生成信息和后续结果写回这一条消息。所以玩家可能先看到正文,后来在同一条回复里看到图。图片不需要等下一轮才展示;这一点与普通后台状态影响以后回复不同。
为了下一张图仍像同一个人,视觉准备会读取衣着、道具和场景等状态。本轮成功且做过视觉准备时,结束处理再根据最终文本维护外观连续性。这里存的是视觉资料,不会自动把剧情笔记、世界书或 NPC 档案都同步更新。
没开放图片菜单、尚无可配图的 Actor 段落、同一段已配过图等情况,程序可以拒绝这个前台动作;安排成功也不是生成成功。工具的回执应区分已调度、已生成、审核结果和写回完成。前台的“结束”只结束文字动作编排,不保证所有图片已完成。多次写正文还共享整轮输出额度,不能靠反复叫 Actor 无限增加篇幅。
**“请配两张图”的上限与交齐要求,由不同机制约束。**程序用有限的中英文句式识别明确数字;识别到两张时,会阻止继续安排第三张,并在后续 Actor 调用中调整配图模式。另一方面,“至少安排到请求数量才结束”写在控制模型的提示词里;over 的程序检查是已经有 Actor 输出、没有待安排的 visual beat 图片,没有再核对最低张数。因此模型提前结束、步数或正文预算用完时,仍可能只安排一张;两张都已安排,也不等于两张都生成并送达。这不是对所有自然语言数量表达都可靠识别的保证。数量识别[1] · 最低数量的提示要求[2] · 结束、上限与模式调整的实际检查[3]
我想以后都改风格:提交长期要求,等后续请求读取新指令
用户明确说:“以后让艾琳说话更简洁,保留这个风格。”艾琳是当前 RP 绑定的主角色;这次要修改的是她的角色指令。有 DIO 接线时,前台可以选择提交长期修改。程序把原始要求、用户身份、RP 会话和艾琳的角色身份交给外部 DIO 服务。
**是否属于长期要求,当前这一层先由前台控制模型判断。**工具描述要求它只为用户明确提出的持续修改调用 schedule_dio;这条要求不是另一道已实现的语义拦截。执行程序会检查 DIO 是否接好、这一轮是否已经安排过,再提交用户原始输入。例如“这一次说短点”按选择政策不应调用;若模型仍选了该工具,此层没有再判断“只针对这一句”并拒绝提交。外部 DIO 服务是否还会另行识别或拒绝这类要求,在两仓代码里不能确认,本轮也没有验证该服务。任务回执的会话、消息和请求身份校验,是另一项程序检查。模型选择政策[4] · 可用与重复检查[5] · 原始输入的提交[6] · 回执身份核验[7]
DIO 接收后先给一个任务回执,之后编译新的角色指令。当前 Actor 继续使用已经准备好的提示词;后续请求按用户、RP 会话和目标角色读取有效编译结果,校验内容及 hash 后,放入约定的角色指令位置。“已接收”表示任务进来了,“后续读到有效版本并成功装入模板”才是这条接线真正影响回复的时点。
找不到有效版本时沿用原配置;读取或校验失败且请求未取消时,会记录失败并沿用原配置。但拿到有效版本后,原模板若没有唯一可替换的角色指令位置,会直接报错。接入方因此既要配置 DIO 服务,也要让角色模板留有正确的位置,不能只凭任务 accepted 宣布长期修改已生效。
这里的 DIO Director 是外部长效指令服务;普通 Agentic 的 Director 是整理剧情状态的模型岗位。前者可改变以后怎样扮演,后者记录当前连续性及软建议。名字相同不等于保存到同一处,也不代表一个工具自动替两个流程做完。
普通续写、提问或只针对这一句的要求,不应被解释成永久修改。DIO 调度失败时前台会收到失败回执;接收后最终编译失败,也不能宣布长期修改生效。具体版本由外部服务管理,Harness 负责这边的身份传递、观察结果和后续读取;不会因此自动更新日记、通用 JSON 记忆或世界书。
本次新增新候选:先完整回复,再判断这句话是否要长期改变角色
本次新增**#303 仍是 Draft,未合入 main。**它把长期修改的判断移到完整成功回复之后:后台 Jev 同时读用户原话和最终可见回复,判断有没有持续偏好、稳定事实、纠正或撤销;只有选中 schedule_dio 才让 DIO 处理。用户不必说“记住”,但 Actor 自己写出的剧情不能替用户授权长期修改。DIO 可以决定不改,也可以发布仅属于当前用户/会话/角色的新正文,不修改共享 Preset。
本次新增当前回复不等新版本生成;下一轮开头按用户、会话和角色读取已经成功发布的版本,新任务尚未完成就继续用已有版本。读取有效版本本身仍有 HTTP 耗时。程序校验版本 ID、changeSetId、非空正文及 SHA256,再冻结到本轮上下文,供 Actor 重试与后台使用;唯一角色 system 位置的替换发生在 Compact、token 计数和最终装配之前,不能把“读取成功”直接当成“模型已经使用”。实际派发另外记录正文版本和上游 body hash。
开关、失败、持久化责任与当前状态含 5 处更新
本次新增默认关闭。启用时需要 postTurnDio.enabled=true、Jev ModelConfig、含唯一 dio_trigger 的策略 PromptManager、正确关联 Preset 的 Actor 模型及 DIO/Axon 地址;不能配 Sumi。该方案移除旧前台 schedule_dio,避免同轮两个触发入口。判断默认 3 秒,可配 1–30,000 毫秒;答案只能 none/schedule_dio,超预算、非法答案、策略/推理失败、超时和取消都记失败且不提交,不伪装成 none。
本次新增调度条件是结果 completed 且不是 partialResponse;auto_reply、失败和中断回复不触发。代码没有另读 Chat Service 消息落库回执,因此只能说“完整成功回复后”,不能写成“确认落库后”。后台独立上限 16 分钟,完整回复后断连不会撤销已安排任务;后台失败不撤回正文。读取新版本失败且请求未取消时沿用基础角色正文;取消继续传播,模板没有唯一合法角色位置则报错。
本次新增Harness 以请求 ID 派生稳定任务身份,但 runner 仍为进程内 Set/Promise。跨 Pod 会话串行、持久防重、编译和版本发布依赖外部 DIO 服务;本轮没有审第三仓。该候选的长正文不保证自动识别为可做角色精简的字段,超预算仍可能失败。
本次新增10/19 固定 head 的 1 项 CI 通过且有批准,但 PR 仍 Draft。页面显示 staging deployment 的 job 实际只有 build/push,没有 apply/rollout/readiness,不能写已部署。配套服务、数据库迁移和隔离环境故障仍待完成/核验。
本次新增后台判断[8] · 完成后的实际门槛[9] · 回合开头读取[10] · 替换角色正文[11] · 外部服务责任[12] · PR 状态
Fusion 分支的 #253 改的是 DIO 请求如何申请计费,不改“受理后编译、以后请求读取”的时序。启用了前台 DIO 且配置 DIO_URL 后,该分支的 DioTool.schedule() 每次提交都发送 x-dio-skip-billing: true,并在有原用户授权时透传它;不再发送 demo token,也没有加入 Harness 服务身份。这段代码随 c8fc61c 于 9/24 03:16–03:19 完成 Fusion production rollout。这里只确认部署代码会提出免计费请求;DIO 是否接受、如何鉴别调用者以及真实钱包是否没有扣款,仍无实际记录。main 3b6ba5f 没有这项 header 变化,仍保留旧 demo token 接法。Fusion 请求[13] · 主干原接法[14] · Fusion 部署
用户参考图、绘图提示编译和生图/保存追踪已随 #237 进入 main,#239 将角色与参考图的写作要求交由 Prompt Manager 的模板提供,#240 另在独立分支增加前台输入与最终正文的根追踪记录,尚未进入 main。以下已按当前主干更新;版本、部署与未合实验另外列明。
我想整段体验都用连续图文:Sumi 是另一种运行方式
业务选择 Sumi 后,第一次会用角色、人设、开场白和参考图建立初始视觉状态。例如识别“主角色穿蓝斗篷,场景是塔门,画风偏水彩”,按这些来源的指纹缓存下来供同样材料复用。
**Sumi 是代码编排的图文工作流,已在 roleplay-harness / main。**读取材料、调用模型、解析产物、保存状态、异步生图和回填的步骤,由应用程序规定;模型负责生成内容。它有自己的应用入口,没有用通用 profile 的节点配置来定义这条图文流程。
每轮程序读取与当前历史分支相符的上一份快照,把状态和聊天交给 Sumi 主模型。模型按协议同时交出可见正文、内部状态和图片描述;程序解析后,玩家只看可见部分。可直接展开一段模型原文怎样拆成三份产物。若本轮写到“守卫摘下手套”,新状态与前后快照、整理后的模型历史文本、可见正文、图片清单一起按所属消息保存,后续从正确快照衔接。
这条链没有另叫普通六专家逐条补状态,也不是调用前台四工具菜单。 它有自己的初始化、模型输出协议、状态保存和历史恢复。当前配置限制不能把它同普通 Agentic、Compact 和 Emochi 记忆 hooks 任意叠加。世界书已是另接好的可选输入:显式配置后只加入 Sumi 主模型的本轮请求,不进入视觉初始化、历史恢复或持久状态。Sumi lore 准备与预算[15]
有真实生图配置时,正文返回后,图片按描述生成并补到这条消息。没有启用真实生成时,参考图占位不能算新生成图片。当前 main 最多四张同时生成,但按正文中的顺序保存和通知:第三张先生成完,也不能抢到第一张的位置。
本次新增本轮用哪个模型、要不要配图,由谁选择
本次新增Chat Service 先为这次请求选定主模型,再把选择交给 Harness;Sumi 不重新给用户做 A/B 分组。请求 extensions.turn_context.runtime_decision.target_model_config_id 存在时使用其对应内层 ModelConfig;没有才回到场景的 modelConfigRef。实际模型配置同时决定正文模型、Prompt Manager 模板、模型参数与输入预算,provider 必须为 kaon-router。初始化和历史提取仍使用各自原来的视觉模型配置。
| 本次新增接入方交什么 | 程序具体如何使用 | 缺省或限制 |
|---|---|---|
| 本次新增请求身份、用户 ID、会话 ID、角色 Prompt ID、当前 assistant 消息 ID,以及所选历史和本次输入 | 定位角色资料与消息快照;判断这是新回合还是重试旧回合 | 当前 assistant 消息 ID 必须有;同消息 ID 不能换一套输入冒充重试 |
本次新增Chat Service 在 extensions.turn_context.runtime_decision.target_model_config_id 填入的配置 ID |
解析为 runtimeDecision.targetModelConfigId,读取对应 ModelConfig/Prompt Manager |
未传则用场景 modelConfigRef;不是在请求里直接塞任意模型名称 |
本次新增已解析的 temperature、max_tokens、context_limit 运行决定 |
覆盖所选配置中的对应项,其他 parameters 保留;按最终 context_limit - 353 算主回复输入额度 |
最大输出必须为正安全整数;最终模板仍需实际 token 计数 |
本次新增所选场景 sumiV1.imagesEnabled |
true 走图文;false 只交文字,跳过新 loading、新图及历史图片补发 |
缺省为 true;必须是布尔值,字符串 "false" 不合法 |
本次新增纯文本模式仍要准备角色参考图及可选用户参考图、执行必要的视觉初始化、按配置读取世界书、推导状态并生成正文。解析器仍隐藏图片标签,新快照记录 imagesEnabled=false,图片清单为空且不存 imageGeneration。以后重新开图,也不会给已经完成的纯文本回合补图。场景关图只约束这次新执行与恢复调度,不撤回已经交付的图片,也不取消此前已经启动的后台任务。
本次新增已有快照的回合先回放已保存正文,甚至早于重新读取模型配置;切实验模型不让同一条已完成回复重跑。新快照记录实际主模型 ID 和图片开关。仓库有 sumi-v1-full/sumi-v1-text-only 示例,但只是接入模板;真实 Chat Service 实验分桶和独立主动生图设置仍需业务配合,不能由该示例断言生产已经启用。
本次新增模型优先级与参数[16] · 回放与图文开关[17] · 场景校验[18] · 配置示例[19]
本次新增初始化慢在哪里,现在可以沿一条记录查清
本次新增#289 已合主线。开启并采样的 telemetry 会把 bot→user 参考图、personality/persona/opening 和最终 state/welcome 关联到 sumi.init 父记录,同时标记缓存命中、模型配置及 cache_read、model_config、opening_image、initial_state、state_validation、persist、complete 阶段。缓存未命中时,两次视觉模型分别作为子调用:开场图描述读角色图,状态初始化读角色图和可选用户图;缓存命中不再调用它们,已完成消息回放直接跳过初始化。
本次新增两次视觉模型、状态校验与缓存保存原先就有,这次新增的是定位初始化问题的记录。模型成功但校验或保存失败,初始化仍标失败;未开启、未采样或导出失败时不能保证看到记录。内容仍受脱敏与长度截断控制,线上 trace 本轮未独立读取。初始化记录与阶段[20]
改了角色资料,或者选择另一条回复之后,Sumi 从哪里继续
例如用户把角色莉娅的参考图从蓝斗篷换成红外套,又从另一条历史回复继续。角色卡、开场白、用户人设文字或角色参考图变化,历史前缀/父链不匹配,或旧快照缺少证明时,程序按当前材料和选中历史重建。只更换用户人设参考图是一个可局部复用的例外:其他四类材料相同,历史前缀和精确父链也匹配,才沿用已验证的 stateAfter,只替换 USER_ANCHOR 外观锚点;尚未得到回复的本轮输入不会提前写进继承状态。当前复用与重建条件[21]。
重建时保持当前用户外貌和画风,旧聊天对旧外貌的描述不应覆盖新参考资料;新开场白也不能当作既有聊天中新发生的事。这是从文字重建状态,不能精确还原旧图的每个镜头。historyImportEnabled=false 只禁止普通历史沿最近可信快照做局部导入;无快照、正文变化或来源证明失效仍可以进入完整重建。关闭它不等于停止所有历史提取模型调用。
历史提取可以保存独立缓存;本轮只有主模型完成、解析通过并成功保存消息快照,才留下新的 stateAfter、材料指纹及协调后历史的 historyDigest。旧消息、旧图和旧快照保持原样。取消或模型失败不提交本轮快照,重试可以复用身份匹配的已完成提取。#294 已把“已标记为 Sumi 但没有快照”“同消息正文与快照不符”等情形接入下述核实与重建流程,不能再把它们一律写成无法继续。
聊天保存的正文变了,系统怎样决定该相信哪份记录
例如模型原先写了三段,聊天服务只保存了前两段。下一句到来时,Sumi 不能继续把第三段中的剧情当成已发生。程序先将请求里选中的助手消息与各自快照比较;正文和证明一致时直接复用,不为每条消息重新查数据库。快照缺失或正文不一致时,才按当前用户、会话和消息编号向 Axon 查询已经保存的原消息,读取快照最多四个并发。
| 核实结果 | 本轮采用什么 | 接下来怎样处理 |
|---|---|---|
| 找到同 ID 的 assistant 消息,正文是字符串,但与请求不同 | 聊天服务返回的持久化正文 | 按协调后的历史重建;旧快照不能继续替被删掉的那段文字证明状态 |
| 找不到消息,或 ID/角色不符、正文不是字符串 | 从本轮输入排除该消息 | 不删除或修改原会话;其后的有效历史仍要重新核对证明 |
| Axon RPC 失败、无权限或用户取消 | 不把错误解释为“消息不存在” | 本轮失败或取消,不带着未经确认的旧来源继续生成 |
| 后续完整快照能证明相同历史前缀 | 可使用这份后续可信快照 | 它能覆盖更早的不一致,减少重复重建;不能用更早快照证明后来已被删除的消息 |
重建从当前初始化状态开始,只处理到最后一条有效 assistant 消息。本次尚未回答的用户输入仍留给正文模型。缓存身份与新快照的历史摘要指纹都按协调后的文本计算,重试不会把过期正文的抽取缓存误当成本次状态。
对于已经标记来源恢复、或可见正文与快照不再匹配的旧回复,模型只读协调后的可见正文,不再读取旧 modelText,也不续排这条回复的旧图片任务。仅父链、前缀或材料证明失效,则不自动禁用旧 modelText 和未完成图片恢复。已经完成的图片与旧快照不回滚、不补画。
恢复仍受下方历史条数、字节、token、八次新提取和时限约束;超限、计数不精确、抽取不完整或存储失败仍会报错。部署记录证明代码已经发布到指定环境,不证明所有不一致历史都能恢复,也不证明重建后的视觉细节与原图完全一致。
来源核实[22] · 恢复、后续证明与旧图处理[23] · 实际入口及保存[24]。
图片生成前,先把图文模型的描述交给绘图提示编译服务
本轮主模型读当前角色资料、用户人设、状态、选中历史和本次输入;Persona 已启用且图片地址为 HTTP(S) 时,用户参考图会与角色参考图一起进入初始化和快照。托管模型的 system 提示词按 Prompt Manager 返回顺序渲染,运行时已不再额外补一条“Role bindings / Image references”规则。因此谁是角色、谁是用户、图片应怎样引用,必须在实际托管模板中写好;仓库中的模板 ID 本身不能证明这些规则已配置。参考图与模板采用[27]
本次更新开发者在所选 Sumi 方案的 sumiV1.imageGeneration.promptCompilerUrl 填入地址后,程序先保存该图片尝试的占用记录,再把完整 <image> 标签和用户 ID 发送到 /v1/internal/prompt-compiler/compile,最多等 15 秒。服务成功返回时,程序要求非空自然语言提示、合法且不重复的 bot/user 参考角色、同一画幅以及所需图片存在,然后按返回角色顺序选择参考图。未配置 compiler 时直接使用原绘图描述。编译输入与校验[28] · 先保存 claim 再调用[29]
本次新增#304 已把“编译失败就让新图片槽终止”改为兜底:新尝试遇到编译 HTTP 错误、网络错误、编译器自己的 15 秒超时或输出格式错误时,保留失败原因,再用完整原始图片标签继续调用图片模型。不是只截取里面一句自然语言;标签属性与 JSON 内容保留,旧记录没有标签才使用 image.prompt,缺用户参考图时去掉 [picture2]。兜底参考图仍按原 bot→user 顺序,不采用失败编译结果的排序。
本次新增生图任务的调用方 signal 被取消,或整个后台任务到期时,不会走这次兜底生图;这不等于前台用户断开就会取消已受理的独立后台任务。程序在兜底后、通知后、生图前再次检查取消。原有付费防重仍在:匹配签名且已经保存的结果直接回放,未完成的旧 claim 在期限内等待,过期则返回 unknown/interrupted_generation,不重新收费生成。过去已经写成 prompt_compilation_failed 的旧终态也不会因为新代码自动重跑。
本次新增最终结果仍按 ready/blocked/failed/unknown 保存;只有生成成功且审核允许的图片才公开 URL。已取得 claim 的终态用独立 10 秒时限保存,以免中断后重复付费。编译错误单独记在 sumi_prompt_compile_errors_total{reason},实际生图阶段标 promptSource=compiler_fallback;因此一次编译错误不等于最终图片失败。编译失败后成功生成,仍沿用原 loading 的 requestId 通知完成;通知是否在客户端显示仍另验。原始标签[30] · 取消、兜底与保存[31] · 错误分类指标[32]
一轮能带多少聊天材料
#247 已在 main 把 Sumi 的 context_limit 定义为输入额度:主回复使用 context_limit - 350 - 3;历史提取还要遵守下述独立窗口与输出预留,不再从中扣掉最大输出。以仓库当前 context_limit=5000、max_tokens=2048 为例,主回复可放 4647 tokens 输入,旧算法为 2952;如果回复写满,供应商实际总窗口至少要能容纳约 6695 tokens。程序仍会计数并裁剪输入,但没有替调用方验证供应商真实窗口。87 项定向测试使用模拟计数/模型,只证明本地规则,不能证明上游一定接受这个边界请求。输入预算[33] · 当前模型参数[34]
历史恢复模型与主回复另算。旧聊天先拆成最多 4000 Unicode 字符的小片,再对真正渲染后的请求做精确 token 计数,扩张/二分寻找能放下的前缀。每次输入预算是 min(8192 - 1200, inputTokenBudget(context_limit)),在 8192 总窗口内为提取结果预留 1200 token;最多八次新模型提取,读到已完成缓存或并发成功方的缓存不占次数。总恢复上限 90 秒,单次缓存/提取流程 40 秒。每次完整结果通过身份和格式检查才保存;失败/取消不会留下可用状态。计数、提取与缓存[35]
文字还在输出时,客户端就能收到图片加载位置
Sumi 读到非空且已经闭合的 <image> 指令,就拿那一刻的可见正文校准对应段落;程序先用版本检查预留占位记录,再发出 chatImageGenerationStartedV2。这时前端可以显示 loading,还没有开始收费生图。整条回复完成、格式通过并成功提交消息快照后,才进入绘图提示编译和生图;最终通知复用占位的 requestId,把结果补回同一位置。
占位按消息 ID、图片序号、图片内容和原始段落签名区分。最多四个段落校准并行,每个 20 秒;慢校准不阻塞文字输出。同图的并发流共享占位,取消或失败的一方只退出自己的所有权,不能关闭仍在输出或已经成功提交的一方;所有方均失败才清理。被取消的记录再次复用时更换通知身份,防止迟到的失败通知关闭新的 loading。
本次更新通知本身是尽力发送,loading 不是生图已开始或已成功的凭证。#280 在 10/8 合入主线,已包含在下述 10/19 f9b26a9 Sumi 生产部署源码中;实际客户端是否收到、展示并正确收尾仍需验收。完整占位实现[36] · 流式通知与快照提交[37]。
本次新增Sumi 最新已核生产部署为 10/19 13:26 的 f9b26a919965f471756cdacf0f5b2e596cd5991d,目标为 agent-production/roleplay-harness-sumi-v1。生产 run 13:24 启动,实际 Deploy pinned image and wait for readiness 步骤执行 23 秒,日志有镜像 patched 与成功 rollout。日志同时有 watch forbidden;最终 rollout 和 job 均成功,不能因该行改判失败。固定镜像 digest 为 sha256:5be481f299287a7b4e8f0a0b77846fb9de40e2077e2bd71c54456b2cdd890662。它包含本轮 Sumi 模型/图文开关、初始化追踪、compiler 兜底与指标;不证明当前 Pod、实际实验开关、客户端展示或用户效果已验收,也不证明同镜像内的 Memory/Compact 代码已被 Emochi 产品启用。生产运行与实际步骤。
Sumi 生图请求由后端写入 caller_service=roleplay-harness-sumi;工具调试写入 roleplay-harness-tool-debug,不允许调用参数冒充来源。这是服务来源与路由标记,不是用户登录凭证。新增 LLM/图片 Clickstream 事件;图片开始/结果事件用会话、消息、图片序号形成固定身份,附成功、失败、审核、段落与耗时。上报失败或 7 秒超时不撤销已存图片,也不再生一次;accepted 仅表示 Axon 接受上报。图片事件里的 rawCost 为耗时估算,不是真实账单。图片事件及来源字段[38] · 实际调用[39]
一张图生成后,聊天里、图片历史和图库各保存什么
假设正文是“守卫接过铜钥匙,转身走向塔门”,其中“接过铜钥匙”这一段配了一张图。新版 main 的保存分成下列几步;它们服务于不同页面和后续请求。
| 何时发生 | 保存的实际内容 | 以后谁取出来,怎样用 |
|---|---|---|
| 主模型写完、解析通过 | 本条消息的完整可见正文、内部状态、图片描述和锚点;存入消息快照 | 下轮 Sumi 按消息分支取 stateAfter,继续图文叙事;图片任务用快照确定本轮属于哪段正文 |
| 一张图获得确定生成结果后 | 先保存 outcome:URL/失败或审核状态、完成时间等 | 当前交付和重试用它,不因通知失败再生成一张;这还不是图库保存回执 |
| 排到这张图交付时 | 重读并核对当前聊天消息,写入图片结果,再发通知 | 聊天页面在对应位置显示图片;编辑后的消息不再匹配时,停止按旧位置补图 |
| 生成结果已保存后,独立归档队列执行 | 图片历史:成功/失败、图片描述、身份、当时完整可见正文及本图关联段落 | 配套图库详情从图片历史的正文快照展示“这张图当时出自哪句话”;不会重新读后来编辑过的聊天 |
| 图片成功且审核证据全部满足后 | 以图片历史回执关联一条图库记录 | 图库可以展示这张已合格图片。失败、被拦截、审核条件不完整,都不能当成已加入图库 |
**聊天补图与图片归档可以分别成功或失败。**归档不占住四图生成槽,也不要求聊天通知先等图库保存;用户已在聊天里看到图片,仍不能据此说图库已经写好。归档保留的是生成时的正文快照,因此用户后来编辑或删除聊天,并不会把这份快照自动改成新正文。
例如,下次用户问“再画一次守卫开门”,Sumi 使用的是对应消息分支的状态和聊天输入。当前代码没有从图库自动找出这张铜钥匙图,再把图库记录当作普通 RP 的记忆交给 Actor 或后台协调器。图库的后续展示,与下一轮剧情的状态回读是两种用途。
上述新归档调用已经进入 Harness main;实际使用还需要配套 Axon/Node 接口已发布。这次核对了代码,没有替生产环境验收归档结果。图片归档实现[40] · 归档与聊天交付调度[41] · 配套接口与验收范围[42]
需要核对审核条件、原文快照、外部回执或“聊天有图但图库没有”,直接看每项归档字段与失败恢复。
新 main 的写入条件、实际字段和失败恢复
- **生成开始与完成通知。**新领取的生成请求先尝试发送
chatImageGenerationStartedV2,通知失败记录后继续生成;复用已有生成结果时不再发送开始通知。完成事件可带请求对应的尺寸:1:1 为 1024×1024,3:4 为 768×1024,16:9 为 1312×736。这是请求尺寸,不是重新测量图片像素。图片结果补completedAt,等待结果store.put完成后才返回给交付和归档流程。 - **写图片历史。**调用
image.history.save,提交用户、角色、会话、消息、task、图片描述、模型信息、状态和完成时间。ready 且有 URL 才记 SUCCESS;确定失败/拦截记 FAILED,不带图片 URL。unknown 或缺少完成时间的旧 outcome 跳过,不把它们冒充确定历史。 - 保留生成时正文。
metadata.latestMessage=snapshot.visibleText,不含内部状态和图片提示标记;selectedParagraph保存已解析的图片锚点,顶部图可以是空串。配套/image/chat/message读取 history metadata 的完整正文;旧记录没有这份 metadata 时,本次代码不会批量回填。 - **再写图库。**必须是 ready,审核状态 COMPLETED、blocked=false、标签 SFW,并且审核资产 URL 与结果 URL 匹配,才用 history receipt 的 ID 调
image.gallery.save。不能只凭“有 URL”进入图库。 - **外部保存与本地回执分开。**每项保存先以 CAS 记录 claim,外部返回后验证 receipt,再记录确认结果。已有有效 receipt 就复用;claim 已存在但没 receipt 则要求核对,不盲目重放非幂等请求。这样避免重复归档,但崩溃在 claim 与请求之间仍可能漏存,不能称为跨服务恰好一次事务。
- **独立收尾与时限。**生成结果按完成时点加入串行 archiveTail,交付和归档各自推进;归档不依赖聊天请求的取消信号。每图归档上限 110 秒,单次 RPC 50 秒,回执写入 10 秒;队列最终清理也有独立时限。已经完整通知的消息不会只为补归档而自动重启整条任务;没有持久补偿队列保证最终一定齐全。
固定差异包含 #171 图片历史/图库、#176 图片生命周期通知和 #177 图库正文快照;配套依赖为 Axon #155、Node Flow #23344。这里只以 Harness 已合并为事实,没有把配套发布当作已验证部署。新生成结果处理[43] · 完整 main 差异
Fusion 的图片失败通知另有 #241 修正:原有失败事件之后,再发送一条同 requestId/同段落、但没有图片 URL 的 chatImageGeneratedV2,让 Android 2.2.8 能清掉加载占位。程序先等开始占位通知完成,再发结束通知;这个事件名不代表图片成功,成功图片才写入可用结果。该改动已合入 Fusion 并包含在后续 c8fc61c 的部署里,未合 main;真实 Android、iOS、Web 对重复或双事件的行为仍待验收。失败通知顺序[44]
图失败了、用户改了正文,后面还会乱补吗
Sumi 开始生图前会核对正文已经保存且与本轮匹配,确认图片插入的位置;每张交付前还会重新读消息并核对当前交付资格。正文被编辑到不匹配、或另一任务取得交付权时,就不能继续拿旧位置覆盖新消息。
成功且审核允许的图才写入 URL;失败、被拦截或结果未知会保留正文并记录对应状态。已生成结果可以在恢复时复用,避免仅因通知重试又生一遍。单张通知失败也不等于后面的图不能保存。
但当前后台不是持久任务队列,没有后续请求就不保证自动唤醒恢复;消息保存和外部通知也不是一次不可分割的事务。这里描述代码设计,不等于已经完成生产页面和时延验收。AOI/Pioneer 的候选图文实现另有保存链,不能把 Sumi 的承诺直接套过去。
前台动作与执行条件[45];DIO 接收与有效指令读取[46];Sumi 逐轮状态[47];Sumi 图片交付[48]。
对应接口细节:前台四个动作及回执 · 图片写回当前消息 · 长期指令后续生效。
图片和 DIO 的原接线证据
在启用前台工具控制器的 Emochi 场景,一次回复可以分成“写一段 → 安排一张图 → 再写下一段”。控制模型读取用户本次需求,选择调用 Actor 或其他已开放工具;Actor 负责真正的角色正文,控制模型再根据刚完成的段落和剩余正文预算决定下一步。例如“写我们进入北塔的过程,并配两张图”,可以先写门外场景、安排插图,再继续室内段落。所有 Actor 段落共用本轮正文预算,不是每调用一次就得到一份新额度。前台编排与共享预算[49]
图片如何补到当前消息
图片能在后台完成,却补回本轮消息。 调度图片后,前台可以继续输出文字;图片任务根据对应段落和角色视觉资料准备生成内容,等待这条 assistant 消息已经保存,再写入图片位置、待生成状态和图片提示词,随后请求图片服务。结果归属于这条消息的图片区域,不需要等用户发下一句话。因此用户可能先看见正文与占位,稍后在同一条回复里看到图片。这里保存的是消息的图片结构与任务结果,和后台导演维护剧情状态不是同一项写入。同一条消息的图片写入[50]
失败分支:保存了占位,不等于图片任务已受理。ImagineSkill.run 先把对应 narrative.sections 写为 type=image,status=pending,url=null,同时存图片描述;保存成功后才逐张调用 image.generate。如果请求在成功交给 Image MCP 下游之前失败,当前函数收集错误,最后抛 AggregateError;这一支没有再写 failed,也没有安排恢复任务。因此消息可能保留正文和永久 pending 槽。9/21 巡检在固定 fa41d220 离线复现为一次消息编辑、最终 pending、url 为 null;现有测试通过不能证明这条最终状态已修复。这里不是已确认的生产事故,也不代表所有已被下游受理的失败都同样处理。
检查时分别看“消息槽已保存”“生成请求已受理”“下游终态已回写”。如果只看到第一项,不能把它展示成保证稍后一定完成,更不能引用 Sumi 的结果复用/lease/后续恢复作为 Imagine 的已有能力。当前占位、调用与错误汇总[51]。
DIO 怎样改变后续角色表现
长期指令走另一条路。例如用户明确要求“以后让莉娅说话简短一些,保留这种风格”,具备 DIO 工具的场景可以把原始要求交给外部 Director 服务,连同用户、RP 会话和目标角色身份一起提交。返回 accepted 只表示任务已接收;后台继续观察最终结果。后续请求读取有效的编译 Prompt,并应用到约定的角色指令位置。正在生成的这一轮不会被半途换 Prompt,也不能把普通“继续故事”或仅本轮的临时要求都当成长期修改。长期版本及编译结果由 DIO 服务管理,Harness 保存的是接入身份并读取其结果。长期指令的接收与后续读取[52]
Sumi 初始化、快照、四图并发与交付恢复的完整边界
Sumi 的逐轮图文状态
Sumi 是独立的图文 RP 路径,按代码编排工作流运行。 首次遇到一组角色、人设、开场白和参考图时,它用视觉模型提取初始人物、场景、风格等状态,并缓存结果。后续每轮读取对应历史消息的快照,把上一份状态与聊天记录送给主模型。模型输出经过解析,拆成用户可见正文、内部状态与图片描述;前台只展示可见内容,结束后保存本轮前后状态、模型文本、正文和图片列表,再安排图片交付。Sumi 的初始化与逐轮处理[53]
例如第二轮出现“莉娅脱下斗篷”,Sumi 后续使用的状态来自对应消息快照,而不是普通 Agentic 的六专家与导演链。它还检查人物材料和分支连续性,避免把另一个角色或另一条分支的状态接进来。快照经 Axon 的状态接口按用户、会话、角色及逻辑记录键隔离保存。当前配置不允许把 Sumi 与普通 Agentic、Compact、Emochi 记忆 hooks 随意叠加;显式配置的世界书已可单独注入 Sumi 主模型,但不会把 Sumi 变成普通 Agentic 后台。选择 Sumi 就是在选择这套独立运行方式。Sumi 状态的存储范围[54]
同一段模型输出,怎样拆成正文、状态与生图任务
以下仅示范已实现的标记和解析规则;人物、句子及 CHARACTERS 更新内容是教学数据,不是固定输出模板。假设旧状态已有场景、画风和守卫穿戴。主模型可能交回:
守卫摘下手套,接过铜钥匙。
<image ratio="3:4">水彩画风,蓝斗篷守卫赤手接过铜钥匙,背景为石塔门。</image>
<!--KAON_STATE-->
CHARACTERS: 蓝斗篷守卫已摘下手套,手持铜钥匙。
<!--/KAON_STATE-->
程序分别处理,而不是把整段显示给用户:
| 解析出的东西 | 本例的实际值 | 程序随后怎样使用 |
|---|---|---|
visibleText |
守卫摘下手套,接过铜钥匙。 | 作为本轮正文流出并返回;内部状态和完整图片描述不显示 |
images[0] |
index:0、ratio:"3:4"、上述水彩图片描述、selectedParagraph:"守卫摘下手套,接过铜钥匙。" |
生图任务据描述作图,锚点把结果接到这句正文的位置;此时还没有图片 URL |
stateAfter |
旧状态各字段,加上新的 CHARACTERS 值 |
按大写字段名合并:同名字段整项替换,未提供字段保留;下轮读取正确消息分支的这份状态 |
modelText |
正文和 <image ratio="3:4"/> 占位 |
保留给模型历史使用的图文结构,不含完整图片描述、隐藏状态或 draft notes;它不是未经处理的上游原始输出 |
如果模型没有交回状态块,只记录缺少更新并保留旧状态,不能声称这轮已分析出新的穿戴变化。没有闭合的已知隐藏块在流结束时会被丢弃;只有完整非空的 image 块才产生图片任务。没有可见正文或没有合法完成原因,整轮失败。解析成功后必须先成功保存消息快照,才安排后台图片并发出本轮完成;一般存储报错/超时仍需核对实际存储结果。
依据:标记、状态合并和流解析[55]、快照保存与任务安排[56]。
Sumi 图片怎样并发生成、按顺序交付
正文先返回,图片在后台补回同一条消息。 13c481b 已包含、在已核 3b99f4c 仍保留的 Sumi 实现最多让 4 张图同时生成,却仍按正文里的图片序号逐张保存和通知。假设本轮有门外、验钥匙、塔内三张图,即使第三张最先生成好,也要等前面的交付轮次;第一张结果就绪并轮到它时便可保存、通知,不必等整批全部生成完。并发上限与交付顺序[57]
开始生图前,系统先等待助手正文已保存且与本轮可见正文匹配,并确认图片锚点。每张图真正交付前,会再次读取这条消息、检查正文,同时按自己的版本续约 delivery lease。可以把 lease 理解为“这会儿由我负责给这条消息补图”的临时凭据:归属丢失便停止写消息和发通知;正文已被编辑得不再匹配,也停止按旧锚点补图。读取最新消息再合并图片,是为了保留生成期间新增的字段,避免旧结果把新正文或其他元数据覆盖回去。等待正文与取得交付归属[58] · 每图续约、重读、保存与通知[59]
成功且审核通过的图片才写 URL;失败、审核拦截或结果未知保留正文并发送相应失败事件。每图有独立 claim 和保存结果,恢复交付时会复用结果,避免仅因通知重试再次生图。一张通知被拒绝不会挡住后面图片的保存和通知,未完成部分保留给后续恢复;但后台并非持久队列,没有后续请求不会自动唤醒,通知与存档也不是跨服务原子事务。审核、恢复及通知边界[60]
这段是 Sumi 主线的图片交付,不能套到 AOI/Pioneer 候选的生图、资产重绘或钱包流程。历史平行候选曾修过“重绘失败保留旧图”,也不能据此给所有当前分支作同一承诺。按 2026-09-17 所读源码文档,并发、乱序完成仍按序交付、生成中编辑与失去 lease 等行为已有本地测试覆盖,但尚未对这项并发增量做 staging 实测;测试通过不等于线上页面和时延效果已经验收。测试范围与 staging 边界[61]
代码证据 · 61 处
- 数量识别 ↗
- 最低数量的提示要求 ↗
- 结束、上限与模式调整的实际检查 ↗
- 模型选择政策 ↗
- 可用与重复检查 ↗
- 原始输入的提交 ↗
- 回执身份核验 ↗
- 后台判断 ↗
- 完成后的实际门槛 ↗
- 回合开头读取 ↗
- 替换角色正文 ↗
- 外部服务责任 ↗
- Fusion 请求 ↗
- 主干原接法 ↗
- Sumi lore 准备与预算 ↗
- 模型优先级与参数 ↗
- 回放与图文开关 ↗
- 场景校验 ↗
- 配置示例 ↗
- 初始化记录与阶段 ↗
- 当前复用与重建条件 ↗
- 来源核实 ↗
- 恢复、后续证明与旧图处理 ↗
- 实际入口及保存 ↗
- 材料标记 ↗
- 旧版重建范围 ↗
- 参考图与模板采用 ↗
- 编译输入与校验 ↗
- 先保存 claim 再调用 ↗
- 原始标签 ↗
- 取消、兜底与保存 ↗
- 错误分类指标 ↗
- 输入预算 ↗
- 当前模型参数 ↗
- 计数、提取与缓存 ↗
- 完整占位实现 ↗
- 流式通知与快照提交 ↗
- 图片事件及来源字段 ↗
- 实际调用 ↗
- 图片归档实现 ↗
- 归档与聊天交付调度 ↗
- 配套接口与验收范围 ↗
- 新生成结果处理 ↗
- 失败通知顺序 ↗
- 前台动作与执行条件 ↗
- DIO 接收与有效指令读取 ↗
- Sumi 逐轮状态 ↗
- Sumi 图片交付 ↗
- 前台编排与共享预算 ↗
- 同一条消息的图片写入 ↗
- 当前占位、调用与错误汇总 ↗
- 长期指令的接收与后续读取 ↗
- Sumi 的初始化与逐轮处理 ↗
- Sumi 状态的存储范围 ↗
- 标记、状态合并和流解析 ↗
- 快照保存与任务安排 ↗
- 并发上限与交付顺序 ↗
- 等待正文与取得交付归属 ↗
- 每图续约、重读、保存与通知 ↗
- 审核、恢复及通知边界 ↗
- 测试范围与 staging 边界 ↗
17. 取消、重试与失败:用户最终会看到什么
**9/21 补入两条具体失败结果:**Imagine 为消息图片位写入 pending 后,下游请求还没成功交接就失败,当前路径可能只记录错误而没有失败回写或恢复任务,页面可持续待生成;不能套用 Sumi 的恢复规则。Compact 的旧摘要锚点丢失、历史又太短不能重建时,旧摘要可能先 inactive 而无替代。这两项是固定源码与离线检查的边界,不是已观察到的生产事故。图片失败过程 · 摘要失效过程。
9/22 更新的失败边界:Compact #196/#198 已合入主干,默认关闭;高置信误省略关键承诺仍可能导致后续摘要缺事实,需质量验收。此前“过滤后发生供应商超限却仍推进检查点”的工程问题已修:恢复原输入和原摘要,禁用丢弃并在剩余预算重规划,预算不足不写检查点。恢复与事实遗漏的区别。
另有 Actor 交付变化:配置恢复模型的主模型首次即时流式尝试,先暂存正文,生成正常完成或首个正文片段到达后 4 秒释放。释放前的可恢复失败可丢弃缓冲并切备用模型;已经发出可见正文后不能丢掉用户已看到的前缀重新生成;符合下述Gemini中断续写条件时,会保留前缀并续写,其余错误仍可能留下部分正文后失败。不是所有请求固定等 4 秒,也不改变普通后台每轮安排规则。Actor 缓冲机制[1]。
main 当前有两条一次性恢复。尚未发出可见正文时,已配置 recovery.transientRetryModelConfigId 的主尝试可切到允许的 DeepSeek;除空响应、供应商过滤和指定状态码外,Gemini 的 HTTP/SSE/嵌套 Google 错误也按上游来源判断。本地配置或参数失败、取消、已恢复过的调用和备用模型不会递归恢复。已发出可见正文的 Gemini 如果在可信完成标志前中断,则保留原文,改用 deepseek-beta/deepseek-v4-flash 续写一次;不能重写前缀,也不重跑后台、世界书选择或状态保存。预算不足、前缀放不进备用窗口或续写再次失败就终止。当前资格判断[2] · 中断续写、预算与一次性终止[3]
旧版固定依据(新行为以上文为准):实际条件[4] · Actor 恢复分支[5]
一次聊天有多个完成点:材料准备好、正文生成好、正文保存好、后台状态保存好、图片交付好。 其中一项失败,需要先看它发生在哪一步,才能判断用户会看到什么。
本章的主例是普通后台+世界书。其他方案的停止与结算机制另行说明,不能共用一个“全部撤销”的结论。需要直接核对时可跳到:各类失败的实际后果、世界书 Actor 的重试次数、停止与外部写入、编辑、连续发送与进程退出。
从用户遇到的情况看影响
| 具体情况 | 这条路径怎样处理 | PM 能据此承诺到哪一步 |
|---|---|---|
| 角色、所需模板或必要材料准备失败 | 失败发生在正文开始之前,可能阻断本轮生成 | 不能因为叫“后台模板”就认为一定不影响当前回复 |
| 世界书按语义检索的向量能力不可用,符合服务降级条件 | 混合选择可退到按词匹配排名;其他选择错误并不统一吞掉 | 可能仍有回复,但不能保证入选条目与原先相同 |
| 某个专家正常返回失败说明 | 后台仍可能看其他结果,请 Director 整理 | 不等于整轮后台或当前正文一定失败 |
| Director 失败、稿件无效或没有变化 | 分别报告失败/无效/无变化;没有这份新状态提交 | 文字可能正常交付,后续仍使用可读到的已有状态 |
| 两份后台工作都从版本 12 开始,其中一份先保存 | 后一份不能拿旧稿覆盖较新的版本 | 拒绝旧写入不等于自动合并或重新规划成功 |
| 图片或完成后的记忆更新失败 | 按相应应用自己的交付、重试或容错规则处理 | 不把“看到了正文”理解成所有附属结果都成功 |
Sumi 遇到旧正文与快照不一致时,先查询已保存消息并协调历史,再重建状态;消息不存在或身份不符,只从本轮输入排除,RPC/权限/取消错误仍终止,不能当作消息删除。完整恢复条件。模型连不上时,新主线日志还可带 DNS、TLS、连接、socket 或超时类别,原来的重试与 HTTP 分类保持不变。诊断字段与限制。
用户点停止,哪些工作还可能继续
在当前普通 Agentic 主线里,Actor 的生成会收到取消信号,但已经启动的后台没有绑定同一个父信号,仍可能分析并尝试保存状态。已经完成的外部写入也不会自动回滚。
通用 SDK 的显式取消可向快慢两路传信号,底层模型或工具仍要配合停止。快路自身失败,又不等于调用方明确取消;慢路还可能继续并尝试提交。因此如果产品要求“正文被采用才允许更新状态”,必须在对应接受和保存流程里实现,不能由快慢名称推定。
这不是建议用户多按几次重试。某个写入已经成功、但回执丢失时,表面失败不能证明没写过;是否重试应由该工具的去重和保存协议判断。
连续发消息、编辑或重生成时
用户下一句来得很快,Harness 可能先读到版本 12,后台随后才保存版本 13。已准备好的这次回复不会在生成中自动换资料。版本检查防止旧稿覆盖新稿,不能保证每个相邻回复都吃到最新后台状态。
“继续”“重新生成”“编辑后重生成”会改变聊天,但当前普通 Agentic 主线没有替产品包办整套消息替换与剧情回退。 入口接收动作类型,也接收业务交来的历史与本轮问题。应该保留哪些旧消息、替换哪一条助手正文,需要聊天业务正确构造请求并保存最终结果。只有动作名称正确,材料仍可能错误。
| 用户操作 | 接入业务需要交给 Harness 什么 | 普通 Agentic 主线会做什么;结果怎样使用 |
|---|---|---|
| 正常发送:“请守卫开门。” | 当前保留的聊天历史、本轮问题、身份及本轮助手消息关联信息 | 组装 Actor 与后台材料;进入生成时安排后台。最终正文由业务存为本轮回复;后台另行尝试更新持续状态 |
| 继续写下去:希望续上刚才的回复 | 要继续的历史与明确的续写输入,按所用接入协议传递。入口优先用 input_question,否则最近一条用户消息,再否则才用字面值 continue |
不会仅因选择 continue 就保证以“请续写”作为新问题。若请求未正确构造,仍可能把此前问题当当前输入;普通后台也会按交入的材料工作 |
| 重新生成这条回复:不满意守卫的回答 | 业务选择要保留的历史、问题和替代回复的关联信息;决定新回复替换哪条旧消息 | 普通 Actor 重新生成;普通后台的生成包装仍会安排规划,可能尝试提交。这里没有依据 regenerate 自动回到旧状态的分支,也没有自动删除原回答的业务操作 |
| 修改旧输入再生成:“递给守卫”改成“把钥匙收回” | 业务交回修改后的历史,并明确后续哪些消息保留或作废 | 新历史与此前读出的状态可以同时进入本轮。旧状态若已记成“钥匙在守卫手中”,不会因消息被改就先自动撤销;后续后台可能纠正,但没有本轮生成前必定纠正的保证 |
因此,产品如果提供“改一句,就把这句以后的一切重来”的体验,需要明确定义并接通要回退的记录范围。 仅重发请求不能保证聊天正文、普通持续状态、日记、表格、世界书和图片都恢复到同一个过去时点。下面列出的保护只适用于各自路径:
- **普通 Agentic:**持续状态按用户、会话与执行方案读取。这里名为
historyRevision的值来自消息数量/会话长度,不是旧消息全文的指纹。同条数改文字不能依靠这个数字保证检测并撤销旧后果。保存时的版本检查用于拒绝过期写入;通过版本检查也不证明剧情与编辑后的历史一致。 - **Compact:**有自己的历史窗口与编辑核验机制;检查点只允许
chat / continue / auto_reply路径更新。它的保护不代表普通持续状态也能回退,详见压缩摘要生命周期。 - **Story:**重生成与编辑后重生成走只读基础 Actor;正常轮核对已保存正文及关联锚点,再决定采用或重建。具体条件在下方展开。
- **Sumi:**有按消息分支读取快照的独立流程,见状态与图片交付。未合并的 Pioneer 候选也有另外的分支关联设计,不能代替普通主线已有行为。
世界书 Demo 的“点回角色”“新建对话”和“清浏览器数据”也有不同效果,见三个操作分别留下什么。其中某一项成功,不能当成所有远端记录已被清空。
依据:动作映射与原样接收历史[6] · 本轮问题的取值顺序[7] · 普通生成仍安排后台[8] · 状态身份[9] · 历史位置的计算[10] · Compact 写入动作范围[11] · Story 的只读重生成[12]。
产品排查时,应分别确认“正文有没有交付”和“哪份状态最终保留”。后台没有产生新状态,既可能是失败,也可能是正确判断本轮无需更新。 依据:生成与后台调度[13] · 后台结果分支[14] · SDK 显式取消[15] · 后台任务记录[16]。
实现细节、参数及固定代码依据含 1 处更新
一轮 RP 包含多项工作,它们可能分别成功或失败。 用户看到了文字,只能先确认正文已产生;日记、剧情状态、图片和长期指令还各有自己的完成状态。
按失败发生的位置看结果
| 发生的事情 | 当前链路如何处理 | 用户侧可能出现的结果 |
|---|---|---|
| 世界书 hybrid 的向量索引未就绪或向量不可用 | 记录降级原因,继续词法召回 | 仍可回复,但选择结果可能变化 |
| 绑定了世界书,选择 RPC 发生其他错误 | 当前 Harness 不统一吞掉错误 | 当轮回复可能无法开始 |
| 首选 Actor 返回空正文且满足 recovery 条件 | 主尝试可切一次配置的 DeepSeek;备用仍为空则失败 | 成功时只交付备用正文;不是所有场景默认重试,也不保证本轮一定有内容 |
| 本次更新闭环记忆召回失败 | 默认 fail_turn;场景可显式配置 continue_without_memory,Hinos 另有错误分类 | 默认正文准备失败;获准降级时缺少本轮召回记忆继续,取消/鉴权/坏协议不吞掉 |
| 回复前所需角色/模板准备失败 | 发生在生成启动之前 | 即使出问题的是后台所需模板,也可能挡住正文 |
| 普通后台协调过程或 Director 最终失败 | 返回相应失败报告,未产生该次有效的新状态 | Actor 可能正常回复,持续状态没有更新 |
| Director 候选没有变化或未通过校验 | 不提交新状态 | 后台工作做了,但状态仍旧 |
| 状态 CAS 版本冲突 | 拒绝这次旧候选覆盖较新状态 | 不等于重新规划或自动合并成功 |
| Story 本轮候选保存失败 | settle 报告失败;正文结果与该报告分开 | 正文成功,世界/剧情候选可能未保存 |
| 完成后的记忆 ingest 失败 | 该闭环入口采用 best_effort | 文字可能已交付,记忆更新失败 |
| 世界书完整输入或其他启用完整预算检查的请求超限 | 按对应检查拒绝该模型请求;没有这项检查的旧路径有各自裁剪规则 | 世界书选成功仍可能无法生成;不能推广成全仓每次调用都有同一预算保护,见逐路径容量处理 |
候选中的回复额度修正: 071eb76 及后续 Pioneer 的相关路径里,Actor 失败且上游没有返回用量时,零正文不占这次回复额度;部分正文按实际文本计数,计数也失败才保守占用本次上限。预算不足时保留原始失败原因。这是候选的额度处理,不表示供应商没有收费,也不替代主线的行为说明。候选额度处理[17]
“重画失败,旧图能否保留”也必须按所用分支判断。此前巡检在平行候选 e3b57e6 找到保留旧审核通过图片的修复;不能只凭这个历史修复,就给所有 Sumi、AOI 或当前 main 承诺同样结果。第 24 章单列该修复的固定版本与适用范围。
当前世界书场景的 Actor 到底重试几次
这份配置的名字是 retryPolicy=empty_once,但当前适配器实际转成 retryCount=2。本配置未设置另一条恢复模型分支,因此最多是首次尝试+两次重试,共三次尝试;不能照名字解释成“只重试一次”。空正文可能重试;临时错误还需满足可重试、尚未交付可见正文等条件。取消、次数或时间预算用尽会提前停止,并非任何失败都跑满三次。已经交付半句后,也不能承诺一定从头重写完整句。这个结论只对应本章的 Actor 配置;后台模型的重试是另一套逻辑,第 5 章已经列出。世界书配置[18] · 名字到实际重试配置[19] · 总尝试次数[20] · 空正文与临时错误分支[21]
配置了 recovery.transientRetryModelConfigId 的单次 Actor 生成应按另一规则计算:最多主尝试+一次备用;仅有 recovery 对象不代表启用备用模型。后续恢复扩展仍未把未配备用模型的世界书示例统一改成两次;已发可见正文的Gemini另按一次前缀续写处理。两条路径的次数选择[22]。
用户点“停止”时
以下描述 main 的普通 Agentic。第 24 章另外说明候选分支增加的“等待本轮正文保存、按消息分支取状态”,两者不要混用。
普通 Actor 的生成会收到取消信号,但普通 Agentic 后台调度没有绑定同一个 Actor 父信号,已经启动的后台仍可能尝试保存状态。已经发出的外部写入也不会因为停止输出被自动回滚。
通用 SDK FastSlow 的显式 cancel 会向两路传递取消信号,是否停止仍需要底层模型和工具配合。外层不再等待,不代表忽略信号的外部任务已经停止。如果一个写工具已经保存成功,随后网络响应丢失,看到的失败并不能证明“什么也没发生”。图片、记忆等写入需要按各自结果与去重机制处理,不能一律重新执行。
快路失败和显式取消也有区别。 SDK 中快模型请求失败,不会自动取消已安排的慢路;只要慢路继续完成,且接入方配置的 prepareCommit 返回候选,它仍可尝试保存。若产品要求“只有正文已被采用,状态才能更新”,接入方要把这一条件放进接受与提交流程,不能仅凭两路属于同一轮来推断。SDK 两路调度与取消[23]、独立提交回调[24]
编辑、重新生成和连续快速发送
本次 main 的新观测可分别追踪前台与后台结果,但没有改变取消、并发或提交规则;具体怎么查见第 18 章。
Story 的 regenerate/edit_regenerate 会退回原 Actor,只生成替代文字,不执行 Story 状态写入。正常新轮会核对已保存正文及锚点:最新待采用回复仍为同一消息 ID、相关锚点匹配时,可以采用其编辑后保存的正文;关联用户输入或更早已采用正文被改、锚点失配,或者待采用消息缺失、换 ID,才重建 Story。
用户连续快速发送两句时,下一轮可能在上一轮后台保存前读取旧状态。版本检查可以拒绝过期覆盖,但不会让已经准备好的 Actor 自动换上后来才保存的新笔记。
当前后台 runner 用内存中的 Promise 集合跟踪任务,关闭时可以等待、取消;它自身没有任务数据库和进程崩溃后的续跑功能。Sumi 等具体应用对部分图片任务另做了持久声明和去重,不应把某条应用的保障推广给所有工具。
依据:入口失败策略[25]、后台独立调度[26]、Story 保存报告[27]、重生成路径[28]、后台任务生命周期[29]。
代码证据 · 29 处
18. 调用成本、时间与可观察结果
Compact 已合入过滤策略的成本边界:#196/#198 默认关闭。过滤会增加分类请求,apply 可能减少摘要模型输入;shadow 不改本轮摘要。不能只凭省下的摘要 token 推断总费用或 P95 延迟下降。巡检记录了离线与工程验证,真实 Jev/摘要模型的费用净收益、长聊事实召回和交付延迟尚未验收。模式与实际产物。
Actor 首字时间还受恢复缓冲影响。配置恢复模型并满足即时流式条件时,主模型首次尝试等生成正常完成或首个非空正文片段后的 4 秒才释放缓存;未发可见正文且符合恢复条件的失败,可换一次备用模型;用户取消不触发恢复。它可能影响首字等待,但不是从用户发问起固定增加 4 秒。当前没有真实 TTFT、完成时间或放弃率数据。缓冲与释放[1]。
“用户只发一句话”不等于“只调用一次模型”。 当前回复与后台并行,可以让正文不必等待整套后台检查结束;后台调用仍然消耗模型请求和时间。没有实际运行数据,不能仅从这套结构承诺多少毫秒首字或每轮多少钱。
Compact 新增的累计计数优化只影响压缩前寻找历史边界。boundarySearch:"cumulative" 已在 main,限定 bounded_recent,默认仍为 binary且已有场景未启用。它不减少每轮后台专家的固定成本;最终输入仍完整核预算,有限离线计数耗时下降也不等于真实模型总延迟或摘要质量改善。同章算法、参数与实验。
把一轮的工作数出来
假设递钥匙这轮:回复模型一次成功;后台先选两位专家,两位专家各分析一次;后台看完建议决定请 Director 整理;没有重试或模型升级。
这时是 1 次回复+1 次分工+2 次检查+1 次复核+1 次整理=6 次模型调用。这只是该分支的算例。没有必要检查时可以更少;失败重试、压缩历史、分段写作、图片或其他启用能力可能增加工作。世界书混合选择还可能使用向量模型,不能遗漏这类请求。后台报告中的 usage.modelCalls 另有计数口径,不能拿它直接对照这个全链路算式,见实际请求与用量记录的区别。
用户等待首字的时间,主要看生成前的准备和回复模型何时开始输出;后台完成时间要另看。两者都不是把所有节点时长简单相加就一定得到的产品端到端耗时。
**新增可选路径要单独计量。**开启普通 V2 的 Jev 工具编排后,一次“分工”可能包含决策请求与另一次文本补参;专家和 Director 的模型调用照旧,不能沿用上面的次数算例当固定费用。Jev 仅在所有组成阶段都有 usage 时汇总;缺失不是零成本。当前 Jev 决策请求未接入既有 contextBudget 计数/enforce,部分业务 trace 标签也未转发;这些边界限定在可选适配器。请求和观测限制。
Compact 新配置中的 candidateAttempts/预检查次数与 modelCalls 是不同计数:预检查可以先拒绝放不下的输入而不调用模型。native 示例最多 2 次模型调用、保存等待 5000ms 是该示例值,不能推广为所有场景;检查点写入超时后可能只读确认一次,没有自动重写。预算及保存确认。SDK gate 跳过时记录的是该慢循环 0 次调用,不含宿主自己在 gate 内另做的外部工作。gate 合同。
一份回执如何读成业务结果
假设记录显示:正文生成完成,后台完成了版本冲突处理,这次状态提交被拒绝。应读成:用户可能已经拿到回复,但这份过时笔记没有保存;不能把其中一个 completed 当作“本轮全部成功”。
| 想确认什么 | 应看哪项实际结果 | 单凭什么仍不够 |
|---|---|---|
| 用户拿到当前正文了吗 | 生成结果,以及接入产品自己的发送/保存结果 | 只看模型请求结束 |
| 专家到底做了什么 | 工具是否被调用、返回成功或失败,必要时读授权保存的分析内容 | 只看菜单里有这个工具 |
| 新状态存好了吗 | 提交结果与保存后的版本;例如 committed | 只看 Director 生成了文字,或调试节点 completed |
| 下一轮真的用了新版吗 | 下一次准备时实际读取的版本和输入材料 | 只看上一轮某时刻保存成功 |
| 花了多少模型用量 | 上游实际返回的用量及调用记录;财务还需对照实际计费 | 把缺失用量写成零,或把程序额度当供应商账单 |
当前要分开看 Langfuse 调用追踪、stdout/Loki 日志,以及新增的 Prometheus 运行指标。Langfuse 由配置启用,已插桩的模型/工具正文在各环境均可导出,仍受有效配置和采样控制;stdout 生命周期日志在所有环境常开。Sumi main 的 #237 已有主模型/图片/保存子步骤追踪;#240 另在独立分支把这轮输入和最终可见回复写到 Langfuse 根记录,并让后台不继承根输入。这一分支曾部署 staging,当前 main 未包含这项根记录,不能与子步骤追踪混称。生产代码与真实看板的状态在下文逐项说明。
哪些数字真的是什么限制
想调“上下文窗口”时,先看谁能改、各层参数和实际超限处理:模型容量、历史消息数与输出额度不是同一项设置。
世界书的 2400 tokens 是这份方案给世界书内容的预算,既不是 2400 汉字,也不是整份模型请求上限。扫描最近 4 项、后台历史段 9 条消息,是材料窗口;它们不是“每 4/9 轮启动一次”。状态字符上限控制这段状态的长度;工具额度控制调用安排,Director 和重试等要按实际流程计算。
Langfuse导出需要运行配置开启;stdout生命周期日志不需要这个开关。查询不到记录可能是尚未执行、采样、上报、日志收集或检索范围的问题,不能单凭“没有trace”判断没有执行或没有保存。代码接线、workload已更新、实际读到记录仍是不同层证据。
旧版固定依据(新行为以上文为准):用量汇总[2] · 后台报告与保存结果[3] · 观测开关及实际用量[4] · 状态进入后续请求[5]
实现细节、参数及固定代码依据含 13 处更新
一条用户消息可能触发多次模型调用。快慢并行改变等待方式,不会把后台推理变成零成本。
一轮到底调用几次模型
以普通 Agentic 为例,假设 Actor 一次成功,后台调用两位专家,然后协调器决定让 Director 整理状态,而且没有重试:
| 工作 | 这个例子中的调用数 |
|---|---|
| Actor 写正文 | 1 |
| 后台协调器第一次选专家 | 1 |
| 两位专家分别分析 | 2 |
| 后台协调器再决定是否整理状态 | 1 |
| Director 生成候选状态 | 1 |
| 合计 | 6 |
这是按所述分支计算的示例,不是所有轮次固定六次。后台可以不调用专家;配置升级模型、失败重试、前台分段、Compact、日记或图片又会增加工作。世界书选择不是一次聊天 LLM 调用,但 hybrid 的 query embedding 可能产生另一次向量模型请求。
后台报告的 usage.modelCalls 不能直接拿来验证这个“六次”。 它首先只汇总这趟后台收集到的模型用量,Actor 和世界书向量请求不在这张后台汇总里;模型没返回 usage 的结果不会进入 calls,若干重试的已返回用量还可能被合并成一条最终记录。这里的 modelCalls 是这些汇总记录的条数,不是实际发给供应商的请求总数。有 costUsd 也只表示已收集记录具备金额,不能证明所有调用都已计入。要核实际次数和费用,仍需逐请求记录与供应商账单;缺记录不等于零成本。无 usage 时不收集、按记录数计数[6] · 重试用量合并[7]
不同数字分别限制什么
| 设置/数字 | 作用范围 |
|---|---|
| 普通 Agentic 每逻辑轮调度 | 后台启动频率;没有全局 X 轮参数 |
| 世界书 2400 tokens | 当前场景世界书内容预算,不含整份角色与历史 |
| 世界书 scan_depth=4 | 关键词扫描的消息项数,含 query |
| Planner 近期 transcript=9 | 内置近期历史段的消息数 |
| SDK Slow 默认 maxSteps=4、maxToolCalls=8、maxParallelTools=4 | 通用慢执行内部循环、工具数量与并发限制;不是 Emochi 所有场景的共同默认值 |
| SDK Slow 默认 timeoutMs=180000 | 该慢执行的超时;快路另有超时控制 |
| Actor/Planner 状态文本长度 | 这一部分材料的字符裁剪,与 token/cost 限制不同 |
SDK 的 token/cost 限制根据已经返回的 usage 在调用前后检查,没有为每个并行调用预扣额度。因此已发出的调用可能使累计量跨过上限,然后阻止后续执行;它不是整个产品的统一扣费闸门。
页面和日志能证明什么
世界书快照可以回答“本轮装入了哪条原文、为何入选、预算是多少”;它不能证明角色遵守了设定。正文完成事件也不能单独证明后台状态保存成功。要查状态更新,需看对应提交结果和 revision,不能只看回合结果里递增的 stateVersion。
当前 Demo 的世界书快照经 SSE 回到浏览器,服务器聊天历史不单独保存这份快照;清理浏览器后可能失去它。执行记录则有本次新增的接线,见下面的说明。
仓库已有评估器可检查指定事实是否出现在输出、禁止文本是否出现。该通用评分器使用规范化文本匹配,适合特定回归用例;完整剧情合理性还不能由这一个分数代表。报告的 passRate 分母是完成且有评分的样本,失败样本另外列出,阅读结果时要同时看完成数。
依据:后台执行阶段[8]、SDK 限制默认值[9]、用量检查[10]、Trace 内容采集[11]、评分实现[12]、评估汇总[13]。
现在可以怎样查“前台回复了,后台到底干了没有”
可以把这次更新理解成给原有工作流程加上分段计时与执行回执。比如用户突然安排“美国总统来到这个魔法世界”:Actor 继续按当前输入承接剧情,后台是否调用 NPC 专家、专家是否正常返回、Director 有没有整理状态、最后是否保存成功,分别成为可查询的执行记录。记录下这些步骤,不会让 Actor 改成等待完整 NPC 小卡才回复。 谁决定调用专家、什么时候更新状态,仍由原来的场景和规划逻辑决定。
同一条用户消息会有一个业务请求 ID;当前回复与后台工作各有自己的运行 ID。这样即使回复已经结束、后台还在执行,也能看到“前台已经完成,后台仍未结束”。后台完成后,再看它自己的结果:状态已提交、没有变化、旧版本写入被拒绝,或分析失败。它们不被压成一个模糊的“本轮成功”。
| 想确认什么 | 新记录提供什么 | 应怎样读 |
|---|---|---|
| 用户本轮是否完成生成 | 前台 harness.run;业务 rootRequestId、场景 scenarioId、本次 runId |
response_generated 代表 Harness 返回了正文结果;不等于 Chat Service 已保存或已扣费 |
| 当前回复在哪段耗时 | actor.stream 的开始、结束、模型配置、请求 ID;重试路径另带 attempt |
观察实际流的消费,没有逐 token 重复上报;不能单靠这一条推断完整产品端到端耗时 |
| 后台是否实际执行 | harness.background.<任务名>,独立 runId,同时继承业务请求 ID 和父记录关系 |
成功安排任务不等于它已执行完,更不等于状态已保存 |
| 是否叫了 NPC 等专家 | tool.<工具名>,内部模型调用可归到工具下 |
工具返回 ok:false 会被明确记作失败;不是只有抛异常才会失败 |
| Planner 最后决定了什么 | planner.run 和实际 stateOutcome |
invalid/failed 记为执行失败;unchanged/stale_write_rejected 等保留具体业务结果 |
| 状态到底写入了没有 | state.commit,预期 revision、来源轮次;成功后新 revision 与 committed |
要与 Planner 的最终结果一起看,不能把“专家有产出”当成“写入成功” |
举个具体的排查结果:前台可能显示 completed + response_generated,后台显示 completed + stale_write_rejected,而其中那次 state.commit 显示 failed。这不是互相矛盾:回复成功生成;后台完整处理了版本冲突;这次旧候选没有保存。前台与后台结果要分开读。反过来,后台 committed 也不能证明用户已经接受正文,接受与保存正文仍是接入业务自己的边界。
Langfuse 内容范围在 #273 再次调整:总开关默认仍 false;开启、配置合法且调用被采样/插桩时,各环境均可导出传入的模型与工具正文,不再只允许 staging。字段遮罩与大小限制继续保留。Worldbook diagnostics 优先放在有界预览前部,query 可能包含本轮及近期聊天;截断和凭据键脱敏不等于业务正文匿名化。只有实际传给观测层的调用会被记录,不能推定所有服务、所有请求或独立分支根 trace 自动齐全。当前内容规则[14]
Langfuse总开关默认关闭,开启需要地址、项目凭证、环境与采样率;这只控制该导出链,不控制stdout。观测开启也可能因采样、导出失败或尚未结束看不到记录。世界书页面的本轮注入快照仍是另一份记录,不会自动变成长久的服务器聊天材料库。
main 从 #236 起,在鉴权后的有效 Agent Router 请求开始时,将 turn_context.input_question 或最后一条 user 文本的前 16000 字符、字符数和 hash 写到 stdout;错误消息最多 300 字符。这个日志行为在当前 main 3b6ba5f 中仍在,关闭 Langfuse 不会关闭它。#254 新看板使用已有 Loki 日志;作者称已导入 production Grafana,但巡检没有直连读取看板或日志结果。不能由“存在看板 JSON”推出已有访问控制、留存或删除策略。输入日志[15] · Loki 看板说明[16]
本次更新Memory 日志还存在部分成功分支:表格 CAS 已成功,后面的样本构造/上传失败时,最终只记 memory_write_failed。应把表格版本读回与样本结果分开核对,不能把 failed 直接用于“未写入”的重试判断。此前巡检已做隔离复现,未调用生产。实际保存顺序[19]。Fusion 对冲仍沿用此前只汇总赢家 stream 的核对记录,不能据此取得败方取消前的全部费用。Sumi 原先“生图业务失败但步骤记 completed”的问题,已由下文 #296 对返回内容的失败分类修正;步骤完成、通知受理和客户端实际显示仍是不同结果。
本次更新当前运行监控:请求为什么失败、图片停在哪一步
本次更新#296 已于 10 月 13 日 19:32 合入 main,#297 仍开放。当前服务通过 GET /metrics 导出已接入操作的计数和耗时;Sumi 最新部署镜像包含这份接线。外部采集器成功抓取、Grafana 有实时样本仍未独立验证,不能只凭端点代码或 deployment 成功宣布看板可用了。
| 本次新增当前已有的记录 | 能回答什么 | 不能替代什么 |
|---|---|---|
| 本次更新HTTP/RPC 请求、协议错误、鉴权拒绝、业务成功/失败/超时/取消、首个可见正文等待 | 请求停在传输、鉴权还是应用执行;HTTP 200 内业务是否仍失败 | 不能用 HTTP 成功当剧情生成和状态提交全部成功 |
| 本次新增已接步骤、模型 usage、后台、Planner 与状态结果 | 生成、工具、世界书或后台哪步耗时/失败;收到了多少已返回用量 | SDK model.complete 等既有观察边界不等于每个底层重试尝试;#297 的逐 provider attempt 方案没有因此合入 |
| 本次更新Sumi 初始化、缓存、历史恢复、预算、图片 claim/生成/保存、通知与归档 | 是生成新图还是回放,停在编译、生图、审核还是交付 | accepted 不等于客户端已显示,进程计数不是唯一交付或支付账本 |
本次更新服务启动时注册独立 Registry,指标不依赖 Langfuse 开启或抽样;流式 usage 只收最后一份,回放不重复增加新模型用量。GET /metrics 没有业务 Bearer 校验,网络范围由部署负责;本轮没有因此推断公网暴露。计数保存在进程内,重启归零,多副本需由采集和查询合并。
本次新增这次合入还校正了“函数没抛异常却已经业务失败”的统计:ok:false、failed/blocked/unknown、stateOutcome=failed/invalid 都记失败,不依赖 Langfuse scope。Axon 本地超时按明确错误类型识别,不看报错文字猜测;Worldbook 的原 RPC 仍只调用一次,指标包装不多发请求、不替它重试,也不改变原取消原因。Sumi 的内部请求超时返回 timed_out,RPC 侧映射 TIMEOUT;取消/普通失败分别保留,准备阶段失败不提交新快照。
仍未合入的 #297 和本轮核验范围含 3 处更新
本次更新#297 在 10/13 固定 6cceff5 中另做实际 provider 请求尝试计数:预检未发请求不计,主模型失败再 fallback 分开记;另含 Grafana 查询调整。本轮只确认它仍开放,列表更新时间早于上次基线,没有重新审 head。它和已合 #296 改同一入口、部分同名指标,标签与分桶不同,不能把两套看板查询直接互换。#297 历史源码[20]
本次更新#296 对图片新 claim、已存结果、通知和归档分别统计;它还要求 Sumi token 计数是正安全整数,0、负数、小数或非有限值失败,不能把所有改动描述成只加日志。后续 #304 的 sumi_prompt_compile_errors_total 另属 compiler 兜底变化。巡检读了真实 HTTP fixture、关闭 Langfuse 的失败分类、Worldbook 单次请求、Sumi 超时与取消测试源码;这次没有重跑产品测试、真实 scrape 或 Grafana。
本次更新当前指标实现[21] · 业务失败分类[22] · 入口注册[23] · RPC 结果[24] · Sumi 指标[25] · Worldbook 单次调用[26] · 未合 #297
9/24 的四项看板记录:保留历史口径,最新状态见上方
| 改动 | 能看到什么;数据从哪里来 | 截至 9/24 14:27 的状态 |
|---|---|---|
| Fusion #249 的 Prometheus 指标与 21 面板 | 进程内累计正文首段/停顿、恢复、生图阶段、工具、后台、通知、Axon RPC 和模型用量等,再供采集器抓取 | 已合 fusion-harness,9/23 23:35–23:38 部署 a5e6fb,后续 c8fc61c 继续包含;真实采集、查询、告警和当前 Pod 未读回 |
| 主 Agent Router #252 的 Prometheus 指标与 17 面板 | 请求耗时、首 delta、最大间隔、结束、工具/后台/模型/恢复;新增 /metrics 供采集器读取 |
head 6d14ce0 仍开放,未合入/部署;不能把 Fusion 指标已部署当作此项也完成 |
| #254 的 Loki 看板,10 面板/17 查询 | 直接查询已有容器日志,展示请求数、失败步骤/错误码、模型和最慢 Pod 的 p95 等;不新增 Prometheus 采集器 | head a266445 仍开放;作者称已手工导入 production Grafana,只有仓库陈述,没有本次巡检直连读回 |
| Worldbook #18 的 Prometheus 指标,36 面板/34 查询 | 服务进程累计 API、绑定、选择、向量降级、索引、PG pool 与 embedding reset,再由采集器抓取 | 已合 main 005e19c;作者称导入 production Grafana,但 image/annotations 未部署,当前 target/序列未核;空选择比例的 le="0" 不匹配实际 le="0.0",面板无数据。完整过程与缺陷 |
Prometheus 的进程内计数会随进程重启清零,多副本要由采集和查询正确合并。notify 成功只代表通知传输方确认收到,不能证明客户端已经展示;后台 completed 也不能替代每张图片的实际结果。#252 的 /metrics 没有应用鉴权,但现有清单是 ClusterIP,已知 Ingress 只转 /v1/pioneer,不能据此声称指标已在公网裸露。Fusion 指标[27] · 主服务指标提案 · Loki 看板 JSON[28]
新的诊断怎样解释,哪些结果还要另查
Actor 前缀观测比较同进程中已验证的前一次成功调用与本次最终供应商请求,给出文本公共前缀的上下界,并关联首字等待、token 和 Compact 阶段。256 字节 HMAC 分块用于比较,不是 GPU 缓存命中的证据。重试、续写、同轮、并发重叠和多模态等情况可能排除或标为不可比,不能把每条都放进同一个命中率。前缀范围[31]
Compact 现在分别记录初始、摘要后和恢复预算;输入按单快照/整次限额分块捕获,manifest 带 hash 与完整性。查看省略、截断和 unknown 状态,才能判断材料有没有完整采到、写入结果是否确定。取消后的已有调用和耗时不清零。输入捕获与限额[32]
Sumi 新增 LLM 和图片 Clickstream 事件,图片上报失败不改变已存结果;accepted 不等于最终统计入库。生图来源字段由后端固定,不能当用户认证。事件、来源及生产版本。Axon 客户端缓存另有过期和数量边界,这属于接入进程的资源维护,不是新的业务记忆或产品能力。缓存实现[33]
模型连不上时,日志怎样区分网络故障
以前包装过的模型错误可能只剩“调用失败”,研发难以区分 DNS、TLS 证书、连接、socket 或超时。10/13 已合主线的 #298 会从错误及有限层原因中提取允许公开的错误码,写入 transport_error_code 和 transport_error_category,让 Actor、Compactor、Agentic 的现有失败日志多保留这类证据。
程序最多检查八个位置,防止原因链循环;只接受固定 Node/Undici 错误码,不从错误消息或 HTTP 正文猜原因,不复制原始 cause、地址、证书和凭据。未知码、没有原因或读取原因出错时,字段可以为空。原来的 error_message 行为没有被这次改动整体替换。
HTTP 状态仍决定原错误分类和是否重试:例如 403 的响应正文读取又遭遇 socket 故障,仍是不可重试的权限拒绝,只额外保留 socket 诊断。取消、TimeoutError/AbortError 的优先级不变;Actor 流中断仍是 router.incomplete_stream。本次没有新增模型重试、fallback 或跳过 TLS 校验,也没有据日志字段证明证书已更换或服务恢复。
本次更新#298 已合入 6a108dd,也包含在 10/19 Sumi 成功部署的 f9b26a9 镜像内;本轮仍未读取真实故障的生产日志或证明具体网络问题已修复。本次引用既有分审和测试源码,未模拟真实网络故障。诊断白名单与提取[34] · HTTP 及重试分类保持[35] · 现有日志追加诊断[36]。
为什么一次请求不能只看一个 Trace 的最终状态
一个 Trace 可以包含前台、后台或嵌套的多次运行。新版给每个运行自己的根记录标上 recordType=run_root,并使用 scenarioId + rootRequestId + runId 表达身份。列表应按根 observation 展示;具体模型请求 ID、工具步骤结果放在各自 observation 上,不再让后结束的子步骤覆盖整条 Trace 的请求身份。身份没传全就标成 incomplete,不会猜一个场景或把模型请求 ID 冒充业务请求 ID。
这改善的是排查、统计和 Debug 页面如何读取数据,不是新增“模型调用一次就算一轮”的产品定义。安装 SDK 的其他业务仍需要自己提供这些身份、包住调用和产品提交边界。Sumi 内部步骤与独立 Pioneer HTTP 入口,也不能据 Emochi 接线推断已经全部被自动观察。原生 Pi 现在已有显式包装入口,具体用法见下面;有入口仍不等于所有调用方都已接入。
依据:Emochi 开关及后台运行身份[37]、本轮生成结果记录[38]、Actor 流式记录[39]、工具执行记录[40]、状态保存记录[41]、Planner 结果[42]、根记录与身份字段[43]。
接入细节:开关、采样和用量记录
| 设置 | 当前 Emochi 接线的含义 |
|---|---|
HARNESS_TELEMETRY_ENABLED |
默认 false,只接受字符串 true/false;控制Langfuse,不关闭stdout生命周期日志 |
HARNESS_TELEMETRY_SAMPLE_RATE |
开启后默认 1,可配置为 0–1;父记录的采样决定会延续到子记录 |
| 开启所需配置 | LANGFUSE_BASE_URL、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、HARNESS_TELEMETRY_ENVIRONMENT |
| Langfuse正文采集 | 总开关默认 false;开启且配置合法、该调用被采样/插桩时,各环境允许传入的模型/工具内容;遮罩与大小上限仍保留 |
| stdout原始输入与错误 | #236已合main;有效请求原始输入最多16000字符,模型/工具/Memory错误消息最多300字符。始终开启,不受telemetry开关、staging门或该凭据键脱敏器控制 |
| 用量 | 当前 13c481b 的 Actor 流已记录上游实际返回的 tokens、可选缓存/推理用量与 cost;没有返回就保留 missing,不会用事后估算冒充上游用量。非流式包装也记录返回 usage;这些仍不是统一财务账单 |
| 故障 | 初始化配置错误会报错;运行中的导出失败不改业务回调原有结果。没有查到记录也可能是采样或上报问题 |
一次世界书选择会保存什么:worldbook.conversation.check、worldbook.bindings.resolve、worldbook.select 分别产生调用记录。selection 的 query、最多 20 条历史、传入的 state,以及返回的绑定/条目原文可被导出;失败则记录类型、消息及可用错误码。它不会因进入观测而自动成为 Agent 的长期记忆或下一轮 Prompt。
**保存多少、谁控制:**采样由宿主环境配置决定,启用后默认采样率为 1。每项最多 16,000 个 JSON 字符,超出时保存标记 truncated 的结构化 preview。过滤器会掩去 authorization、cookie、password、secret、api_key、access_token 等精确键名;故事文本中的姓名、情节或其他业务敏感内容不会自动匿名化。接入方需要确定 Langfuse 的区域、访问者、保留和删除规则,以及是否允许把这些正文写入。三份 staging manifest 已设总开关 true;当前运行实例是否用了这些环境变量,本轮未核实。
配置与总开关[44] · 三类 RPC 的输入、返回与错误[45] · 允许内容、脱敏与预览上限[46]。
新主线中原生 Pi 怎样接: 业务先用 telemetry.observeAgentOptions(options) 包装配置,再在 telemetry.run 的运行范围内执行 Agent。它观察实际模型与工具调用,也覆盖下轮替换的工具;不另建根 Trace,不抢读用户的 token 流,也不替业务记录“用户接受”“消息保存”“扣费成功”。Slow/FastSlow 已有内部观测,不应再重复包装它们的内部模型。Pi 明确包装契约[47] · Actor 实际用量记录[48] · Actor 流的默认 missing 与记录入口[49]
独立服务和普通 SDK 业务仍需接入自己的调用边界;本次并未把 Sumi、所有原生 Pi 调用方、独立 Pioneer 入口全部自动接成同一条观测链。元数据过滤也不等于全系统所有日志自动脱敏;模型网关与其他服务日志有各自规则。
昨天巡检发现的候选边界:保存对账和错误日志
候选 61039e5 按消息分支读取状态时,要对照 Actor 读到哪份快照、CAS 实际确认哪份、消息挂上哪份引用、下一轮又读到哪份。这四处一致,才更接近回答“新状态确实被后续回复使用”;多了日志并不会把保存正文、CAS 和消息挂接变成一个原子事务。候选状态读写与挂接[53]
还有一项未闭合的具体日志路径:该候选对用户的失败通知使用通用文案,但仍重抛原始异常;后台 runner 取 error.message,装配层再写入 stdout。如果上游错误含有原始敏感内容,这条路径仍可能把它带进日志。 当前 main 遥测总开关默认关闭、启用后允许 Worldbook 正文的规则,也不能替这条候选日志路径提供脱敏保证。这是已读代码中的风险条件,不是本次发现了生产泄露事件。原异常重抛[54] · 提取错误消息[55] · 写入 stdout[56]
代码证据 · 56 处
- 缓冲与释放 ↗
- 用量汇总 ↗
- 后台报告与保存结果 ↗
- 观测开关及实际用量 ↗
- 状态进入后续请求 ↗
- 无 usage 时不收集、按记录数计数 ↗
- 重试用量合并 ↗
- 后台执行阶段 ↗
- SDK 限制默认值 ↗
- 用量检查 ↗
- Trace 内容采集 ↗
- 评分实现 ↗
- 评估汇总 ↗
- 当前内容规则 ↗
- 输入日志 ↗
- Loki 看板说明 ↗
- 输入日志 ↗
- 常开stdout与错误消息 ↗
- 实际保存顺序 ↗
- #297 历史源码 ↗
- 当前指标实现 ↗
- 业务失败分类 ↗
- 入口注册 ↗
- RPC 结果 ↗
- Sumi 指标 ↗
- Worldbook 单次调用 ↗
- Fusion 指标 ↗
- Loki 看板 JSON ↗
- 旧环境内容门 ↗
- Worldbook 诊断优先 ↗
- 前缀范围 ↗
- 输入捕获与限额 ↗
- 缓存实现 ↗
- 诊断白名单与提取 ↗
- HTTP 及重试分类保持 ↗
- 现有日志追加诊断 ↗
- Emochi 开关及后台运行身份 ↗
- 本轮生成结果记录 ↗
- Actor 流式记录 ↗
- 工具执行记录 ↗
- 状态保存记录 ↗
- Planner 结果 ↗
- 根记录与身份字段 ↗
- 配置与总开关 ↗
- 三类 RPC 的输入、返回与错误 ↗
- 允许内容、脱敏与预览上限 ↗
- Pi 明确包装契约 ↗
- Actor 实际用量记录 ↗
- Actor 流的默认 missing 与记录入口 ↗
- 配置装配与模型原请求保留 ↗
- SDK 内容与用量处理 ↗
- 服务覆盖范围 ↗
- 候选状态读写与挂接 ↗
- 原异常重抛 ↗
- 提取错误消息 ↗
- 写入 stdout ↗
19. 已有业务怎样接入SDK和Workflow
假设用户输入:“我把封着蜡印的信递给米拉,问她是谁寄来的。”我们希望立即有角色回复,后台检查人物与信息是否自洽,并把值得保留的信息交给下一轮。
SDK 提供运行模型、执行工具、把结果交回模型、限制预算和可选的快慢并行。米拉是谁、信里有什么、允许调用谁、哪些内容算事实、什么能保存,仍由业务接线决定。 不传这些材料,SDK 不会从角色卡、世界书或其他 Agent 那里自动补齐。
业务必须交齐的四份东西
| 业务准备什么 | 这个例子具体交什么 | 如果不提供会怎样 |
|---|---|---|
| 本轮可用材料 | 米拉是港口管理员;用户刚递信;此前仅知道信封有陌生蜡印;最近对话;第 12 版已存状态 | 模型只能依据实际收到的文字判断。系统内部有数据库,不代表模型本轮看到了它 |
| 每个模型的工作要求 | 回复模型“以米拉身份回应,不代替用户拆信”;后台模型“检查新事实和后续建议,不把未揭晓的寄件人写成定论” | 通用 SDK 不会自动补一份全行业通用的 RP 岗位 prompt |
| 允许执行的工具与执行者 | 本例只挂 judge_npc 和 audit_knowledge;绑定相应模型、专家 prompt、上下文编译器 |
模型不能调用没挂载的能力;安装完整工具包不等于菜单有所有工具 |
| 结果接受和保存规则 | 用户真的递信可以保留;“寄信者可能是旧同事”只能是推测;接入方定义如何由 final/工具建议生成新状态,以及哪个 store 接受版本写入 | 模型完成回答只是产生结果;未接保存回调/写工具就不会自动形成下轮记忆 |
本轮要不要加世界书条目、要不要检索日记、要不要等正文被接受后才更新状态,也要在应用路径中接线。它们不是“写了一个 Agent 类”之后自动出现的功能。
可用三种接法,取决于谁决定下一步
| 接法 | 这一轮怎么走 | 适合哪种业务决定 | 代码里的事实 |
|---|---|---|---|
| 程序固定调用工具 | 程序先读记忆,再调用人物检查和知识检查,拿结果后调用回复模型,最后按接受规则保存 | 步骤明确,需要保证某项检查确实发生 | 可直接调用工具 .execute();示例 02、04、05 分别演示咨询、Story 程序流、记忆读写 |
| 一个模型在菜单中选下一步 | 模型先看材料,可能调用人物工具;看到结果后再决定是否调用知识工具,最后返回业务结果 | 下一步取决于刚得到的观察 | 自定义 SDK Agent 使用原生工具循环;示例 03 挂剧情工具,示例 06 挂图片工具。接入方提供提示词、tools 和结果解析 |
| 前台回复与后台工具循环并行 | 同一份旧状态快照分别交快模型和慢模型;快模型写当前回复;慢模型咨询工具、整理建议,可按接入方规则提交 | 希望尽快回复,同时在后续轮次使用后台成果 | FastSlowRuntime + SlowTurnRuntime 已实现;示例 07 显式挂两位专家,不是默认挂所有工具 |
固定 profile 工作流也在仓内有实现:节点写清调用哪个 capability、依赖哪个节点、结果放进回复材料哪里,程序按图执行。它目前使用应用内的 StaticPlanner/CapabilityExecutor;不要把内部 ScenarioProfile 定义当作已从 npm 根入口公开的 API。“固定 profile 已有、通用 profile 的 agentic 接线尚未统一”和“SDK 已有可用的 Agent 工具循环”可以同时成立。
一次真实工具循环中,流转的是这些东西
以下是按 SDK Slow 接口写出的业务示意,值不是实测结果;下方 JSON 先展示“工具名+业务参数”,完整调用还包含 ID、function 包装及编码后的参数,见实际调用包与工具回包。后台主模型第一次收到业务给定的工作要求、旧状态、历史和最新用户输入;工具菜单只包含 judge_npc、audit_knowledge。
第一步:模型发出调用,不是直接把 NPC 完整写进数据库。
{
"name": "audit_knowledge",
"arguments": {
"reason": "用户询问寄件人,但已知材料只有蜡印",
"focus": "区分米拉能认出的线索与尚不能确认的身份"
}
}
程序检查名字存在、参数合法和预算未超限,然后调用已注册的知识工具。工具执行时,程序额外给它绑定米拉资料、旧状态、近期对话、这轮 query 和专家工作要求;模型写的 reason/focus 不是这位专家的全部输入。
第二步:专家返回一份可读的判断。 例如:“已知:用户递出信。可观察:陌生蜡印。不能确认寄件人;米拉可检查纹样,但不能直接认定来自旧同事。”此处是工具建议,没有保存,也没有凭空获得数据库里的其他信件记录。
第三步:主模型真正收到工具回执(observation)。 SDK 把刚才的调用记录,以及与它 ID 对应的工具结果重新放进下一次模型请求。主模型可以继续调用已在菜单里的工具,也可以结束并输出“保留寄件人未知,后续先辨认蜡印”的整理结果。这里存在看结果再做决定的循环;没有自动多出来一个独立 Review 模型。
第四步:接入方决定存什么。 若配置 prepareCommit,它会拿到 final、所有已记录的工具结果和本轮旧 context。业务可以返回新的完整 state,也可以判断本轮没有值得写的东西而不返回候选。SDK 只在有候选时带第 12 版作为写入前提提交。
第五步:下一轮重新读取才会使用。 如果提交成功,下一次请求读到新版本,再把“寄件人仍未知”组装进模型材料。这不会倒流到正在生成的本轮回复,也不会使本轮冻结的旧 context 自行更新。若第 12 版已被别的请求更新,旧稿会被版本冲突拒绝,不能覆盖较新记录。
快模型和后台并行时,本轮回复可能已经写出“米拉接过信,转向光线检查蜡印”。后台不是在看完这句新正文以后才自动开始;要对新正文做接受/结算,接入方必须把这个事件纳入自己的流程。
已发布的另一种接法:把原生 Pi Agent 放进慢执行器
PR #244 提供 SlowTurnRuntime 的原生 Pi 接法。宿主传 agent(context, signal, controls) 来创建 Agent,保留 Pi 的工具、消息、图片和执行钩子。要将主模型及专家模型放进同一本调用用量账,必须使用 controls.wrapModel 包装对应模型;只创建一个专家对象不会自动计入共享额度。宿主接口[1]
它分开限制整次任务和单次模型等待,取消后可立即返回、有限等待,或严格等待所有 I/O 结束。若仍有未结束 I/O,结果会给出 ioSettled=false,不返回可供宿主提交的 agentState;迟到的模型成功仍计入用量,超预算后阻止后续副作用。这个执行器不替业务写剧情状态,宿主仍需验证结果、提取状态并按自己的版本检查保存。取消与结果[2]
PR #244 已于 9/24 合入 main,SDK 0.5.0 于 10/8 发布,0.6.0 继续包含。宿主仍需创建 Agent、包装需计费用量的模型、解释结果并实现状态保存;这不代表普通 Agent V2 后台自动换成 Pi。已核 Release 与发包流水线,没有独立安装或正式业务采用验收。SDK 0.5.0 Release
只想复用世界书,可以直接用 SDK 客户端
SDK 0.6.0 新增 @flowgpt/roleplay-harness/worldbook。接入方提供服务地址和自己的资料分组编号 tenantId,再按需调用创建/导入、读取/修订、建索引、业务对象关联、search/select 和管理方法;不必启用 RP Agent V2 或 Story。返回仍是服务的书籍版本、关联清单、入选原文和诊断,接入方在调用自己的模型前将 blocks 按位置放进 messages。
这个客户端默认 30 秒超时,支持取消信号、请求 ID 和创建幂等键,不自带缓存、自动重试、模型调用或剧情状态保存。宿主负责登录权限与允许访问的资料分组;传入一个编号本身不能证明有访问权。写请求遇到网络错误也可能已在服务端成功,需按同一请求身份核实,不能随意重复创建。
0.6.0 在 10/9 11:52 发布到 GitHub Packages,发布流水线成功;这是包交付证据,不是服务部署或业务接入验收。客户端完整合同[3] · Release · 发包运行 · Entity 关联与迁移
怎样判断“已经接上了”
应同时看到:本入口构造了哪个 runtime;传了哪些真实工具实例;初始 prompt/messages 里有什么;工具返回后谁读取;若需要持久化,哪个接受条件和 store 确实被调用。只有工具类、一个名字列表或可运行 demo,无法证明产品已接通整条链。
这五步在代码里对应哪些字段、何时停止和失败后返回什么,见SDK 循环及提交契约。原生 Pi Agent 与已有 Workflow 的接入方式另见接入类对应。
工程接线、默认限制与失败结果
- 自定义
Agent.prepare()返回AgentRun:options(含模型与 tools 等)、prompt、result(state,signal)。每次run()新建 Pi Agent;没有默认业务状态持久化,也没有 SDK 自动填的 RP system prompt。 SlowTurnRuntime明确接model/modelConfigId/prompt/capabilities/limits;capabilities 默认[]。用六专家时需包装为AgenticCapability并绑定专家 prompt;用于原生 Pi 时可采用工具包/pi的toPiTool()。- Slow 首次消息:system=接入方 prompt;system=状态版本/来源轮次+state 字符串;history;最新 user input。其默认快照消息不自动展开 ledger。专家的默认上下文编译可另外读取 state+ledger,两者是分别组装的模型输入。
- 每批工具执行前校验整批名称、调用 ID 和 JSON schema。一次出现未注册名字/错误参数,该批不会先执行前面的合法项再发现后面的坏项。
- 默认每次慢运行最多 4 次外层模型决策、累计 8 次工具调用、每批 4 个、180000ms;可配置。最终不带工具的回答也占一次决策;专家内部模型调用不是外层步数。专家使用 invocation.model 才纳入统一模型预算。
- 工具结果以
role:'tool'、name、tool_call_id、JSON result 交回下一次主模型,之前 assistant 的 tool_calls 也保留。直到不再请求工具,或错误/取消/预算使执行结束。 - 普通
ok:false结果可以让主模型看到并继续,故 status=completed 不等于每项工具都成功;抛出的执行错误会使这条 Slow legacy 适配路径失败。 - 没有
prepareCommit或它返回 undefined:不写 SDK 状态。存在候选:SDK 调compareAndSet,附 sourceTurn/sourceMessageId/historyRevision。版本冲突为 stale_write_rejected;一般保存报错/超时需核对外部存储,不能仅凭失败回包断定完全没写入。 - FastSlow 每次启动都会安排后台;当前 main 可向 SlowTurnRuntime 注入 gate,在慢模型、工具和提交之前决定是否跳过。没有默认“累计 X 轮”规则,host 决定门槛与计数。默认后台管理在当前进程内,不是持久任务平台。取消信号共享,不能直接套用普通 RP 应用分离后台的取消行为。
- 工具 before/after hooks 是程序校验或观察回调,不是自动 Review LLM;afterTurn 也需 host 自行调用。
代码依据:Agent 接线[4]、Slow 初始菜单与输入[5]、观察值与结束[6]、候选与版本提交[7]、默认预算/消息[8]、FastSlow 启动[9]、例 07 的两工具与保存函数[10]、固定 profile[11]、SDK 公开 exports[12]。
接入类与已有 Workflow 的完整技术对应
接入可以从一个工具开始,不必一次替换整个聊天系统。单独工具适合已有稳定链路、只想增加一项能力的业务:例如原来的回复前增加知识检查,业务传入角色、历史、状态与模型,拿到建议后决定放进当前上下文还是留作记录。要读写数据,就给工具绑定自己的存储与用户范围。通用 Agent则适合自己定义模型与工具对话过程:业务准备消息和工具,Agent 每次建立一个新的模型代理执行,完成后由业务解释返回结果;它不替业务加载角色库、保存聊天或安排后台任务。通用 Agent 的职责[13]
单独做一次慢分析
独立 Slow适合“做完一整次分析再交回”的任务。比如用户已接受一段剧情,业务把这段正文、历史和起始状态交给慢执行;它完成模型与工具循环,返回结论和工具结果。业务可以只展示分析,也可以经接受后提交状态;若配置提交回调,SDK 会用预期版本调用存储。Slow 自己不负责后台调度,也不会自动重新从聊天数据库找输入。独立慢执行[14]
**当前 main 新增可注入的慢路门槛 options.gate。**例如业务希望“无新事实的寒暄暂不分析”,可以提供函数读取本轮 context(input、history、旧 state、sourceTurn 等)与取消信号,返回 {run:false,reason:"本轮无需要更新的事实"}。这不是 SDK 已经替业务写好的判别策略;函数可以纯规则判断,也可以由宿主另接分类模型。
| gate 的结果 | 本轮慢路实际做什么 | 返回给宿主什么 |
|---|---|---|
未注入 gate,或返回 run:true |
继续原有慢模型 → 工具循环 → 可选 prepareCommit/版本提交 | 正常 final、toolResults、保存结果;有 gate 时附判断 |
返回 run:false |
跳过慢模型、所有工具和 prepareCommit,不写新状态 | status=completed、stateOutcome=retained,前后版本相同,工具列表为空,慢循环 modelCalls/totalTokens 为0;附 gate 决定,无 final |
| 抛错、非法返回、取消或超时 | 不把它当成“正常跳过”,进入相应 failed/cancelled/timed_out 路径 | 返回错误类别与已知状态结果。gate 的耗时在整次慢运行超时之内 |
返回必须是对象且 run 为布尔;可选 reason 为字符串、confidence 在0—1、latencyMs 为非负数。confidence 的业务含义由宿主定义,不是 SDK 已校准概率。门槛只在慢循环前评估一次,并非每个工具前重新判断。若宿主自己在 gate 内调用模型,该外部调用不会凭空进入慢循环的 modelCalls/token 统计,不能把返回0解读为整项业务完全免费。
**这项能力已合入 main fa41d220,已进入后续发布,旧 SDK 0.3.0 不包含;没有证据表明普通 RP Agent V2 已接入此 gate。**它与 V2 的可选 Jev 工具决策适配器是不同接线,也不改变普通 V2 每逻辑轮安排后台的现状。
依据:gate 输入与返回合同[15]、慢循环前跳过及结果[16]、判断结果校验[17]。
实际送给模型的消息按顺序是:接入方提供的慢任务说明;包含状态版本、来源轮次和 state 正文的系统消息;接入方传入的 history;最后一条用户 input。例如想检查“守卫已经接过钥匙”,就必须由业务把已保存的那段正文放进这些材料。此入口不会自动加载角色卡、选择世界书,也不会把快照里的 ledger 自动编进状态文字。直接调用 Slow 时,起始状态也由调用方提供;先读取状态的是 FastSlow 组合入口。调用方可用 prepareFastSlowContext 复制并冻结一轮材料,Slow 本身不再复制。实际消息序列[18] · 状态文字、历史和 input[19]
执行保护与普通应用不同。 独立 Slow 只注册接入方传入的能力,明确开启参数 JSON Schema 校验;每一批先检查工具名、调用 ID、调用与并发额度,再校验整批参数,全部通过才执行这一批。不能把这项 SDK 行为套给未开启严格参数校验的普通 Agentic 应用。默认步数、工具数、并发数及超时已列在第 18 章;调用方可以另配。这里检查的是参数与执行额度,不是在证明工具建议符合世界观。注册与整批预校验[20] · 批次执行前检查[21] · 工具名、ID和额度[22]
返回要分两层读。 final 是循环最后的模型结果,toolResults 是工具回包;status=completed 只表示该次执行正常结束。没有配置 prepareCommit,或回调判断无需提交而返回空,stateOutcome 是 retained;回调给出新状态并保存成功才是 committed;版本冲突可以返回 completed + stale_write_rejected,表示流程处理完了,但这份稿没写进去。SDK 也不会自动套用普通 Director 的 23 项标题或替业务审查剧情事实,业务需要在回调和存储中落实自己的接受规则。提交回调和保存结果[23]
把已有 Workflow 接成快路
FastSlow适合“当前回复与下一步规划并行”的交互。入口先读一次状态并冻结本轮快照,再安排慢任务与快生成;默认快路只有一次模型请求。如果业务原来已有“识别意图 → 查资料 → Writer”的 Workflow,可以把整条链包装成快路的 complete,需要逐段返回就再实现 stream。默认 SimpleFastRuntime.stream() 实际先等待一次 complete(),再交出整段 content;方法名含 stream 不代表默认已有 token 流。默认 stream 的实现[24]SDK 不会自动发现旧 Workflow,也不会替它拆节点。两路共享起始材料,慢路看不到本轮刚写出的回复;每调用一次组合入口就安排一次慢执行。想每三轮分析,业务可在 Slow 的 options.gate 中按自己的计数返回 run,也可在外部决定何时调用独立 Slow;没有默认累计 X 轮规则。默认快路与自定义快路[25]
复用现有应用服务
直接接业务服务是另一种选择:沿用 Harness 请求接口、场景配置和 Axon 等现有服务,得到已实现的 Emochi 或 Sumi 行为。这比接一个工具包含更多产品规则,也带来现有场景的组合限制。Emochi 实际使用自己的 Planner、协调器和适配器;安装 SDK 不会自动安装这套应用配置。比如要复用现有日记和角色渲染,接业务服务与只调用 FastSlow 是两项不同工程。应用服务的装配[26]
需要可恢复任务时怎样包装
若已有持久 Workflow,推荐把一次分析显式包成平台步骤:先保存任务 ID、输入快照和配置版本;步骤执行时重建模型与工具依赖,完整等待 Slow 返回;检查成功、失败或超时,再由独立提交步骤核对版本并保存接受结果。例如“总结第 30 轮已保存正文”重试时仍使用同一份输入,已接受的结果也有去重记录。只在步骤里启动 FastSlow 的后台 Promise 就返回,并不能让平台恢复这个脱离步骤的工作。Slow 内部每次模型调用也不是自动检查点,重新执行分析可能重新推理;持久化、排队和步骤重试仍由 Workflow 平台承担。Workflow 的显式包装示例[27]
示例验证、SDK 发布版本、可选观测与贡献规则
可跑示例能证明什么
原来的 01–08 八组业务示例已进入主线:从直接借一个专家、读写 JSON 记忆,到快慢协作和 Workflow 步骤,都有可编译执行的脚本。2026-09-16 巡检记录实际做过打包、独立消费者安装、编译和执行;脚本使用固定数据、假模型与内存存储,验证的是公共接口、执行顺序和接受/提交边界。它们不会证明真实角色库、钱包、长期记忆、模型效果或生产部署已经接通。本次文档同步没有重新运行这些检查。
当前源码还增加了第 09 组位置装配示例,所以目录现列九组;它属于后续代码增量,不能因为 README 中仍保留原八组的 SDK 0.2.2 + Core 0.2.1 验证组合,就认定旧版本也有新位置接口。仓内示例使用本地打包产物;安装 registry 包的业务仍须核对实际版本和导出接口。示例范围与假依赖[28] · 打包、消费者验证与第 09 组版本说明[29]
main 的接线和已发布版本怎样对齐
截至 10/9 的发布记录,SDK 0.4.0/0.5.0 已在 10/8 发包,0.6.0 在 10/9 11:52 发布;Core Tools 0.2.3 已发布。原 SDK 0.4.0 流水线始于 9/22,曾失败,10/8 重跑完成;按 Release 时间区分发布结果,不再沿用“没有 tag、仍未发布”的旧判断。Core Tools 的 userPersona 支持和 Omen 交付仍须与实际 Story 应用传参、产品启用分开。SDK 0.6.0 · Core Tools 0.2.3
旧版固定依据(新行为以上文为准):SDK 0.3.0 变更[30] · Core 版本[31] · 0.3.0 Release · 成功发布运行
包发布成功不代表某项业务已经升级。Emochi 当前源码的 Langfuse 遥测仍需配置开启;#236 的 stdout 生命周期日志始终开启,两条记录不能共用一个开关判断。另一项业务如果使用原生 Pi,需要自己用 telemetry.observeAgentOptions(options) 包装配置,并在 telemetry.run(...) 中执行。它记录实际模型调用和工具执行,包括后续轮次替换的工具;包装本身不创建根 Trace、不消费正文 token 流,也不会替业务记录“接受结果”和“保存成功”。这两件事仍由宿主显式记录。Slow/FastSlow 已有自己的观测,不应再次包装内部模型形成重复记录。Pi 包装的明确边界[32]
SDK 0.4.0、0.5.0 已于 10/8 发布,0.6.0 已于 10/9 发布。 世界书位置辅助、context-placement 导出和 SlowTurnRuntime.options.gate 是 0.3.0 之后的增量,现已进入后续发布;需要这项能力时,应使用确实包含它的后续构建/发布产物,不能仅按版本文本承诺已安装的 0.3.0 具备它。普通 SDK 入口仍不强制安装可选 OpenTelemetry peers;使用 /langfuse 时再满足该入口的依赖要求。当前源码导出[33] · 包版本与可选依赖[34]
共用工具的贡献审批与历史依赖更新
Core Tools 的源码、直接契约测试、包示例及共享构建/发布输入按 CODEOWNERS 保护,修改需要四位指定 owner 中一位非作者批准;其他路径通常由具有写权限的非作者评审。共享根清单、锁文件等即使是 SDK 变动,也可能落在这一边界内。这是代码贡献和合并规则,不是玩家每次调用工具都要人工审批。贡献规则[35]
SDK 0.2.2 曾将 MCP SDK 升到 1.26.0,包含跨客户端响应隔离的安全修复;9/17 固定 0.3.0 清单沿用该依赖。它说明共享依赖已加固,不证明业务曾实际触达漏洞或发生线上事故。历史补丁记录[36] · 当前 MCP 依赖[37]
代码证据 · 37 处
- 宿主接口 ↗
- 取消与结果 ↗
- 客户端完整合同 ↗
- Agent 接线 ↗
- Slow 初始菜单与输入 ↗
- 观察值与结束 ↗
- 候选与版本提交 ↗
- 默认预算/消息 ↗
- FastSlow 启动 ↗
- 例 07 的两工具与保存函数 ↗
- 固定 profile ↗
- SDK 公开 exports ↗
- 通用 Agent 的职责 ↗
- 独立慢执行 ↗
- gate 输入与返回合同 ↗
- 慢循环前跳过及结果 ↗
- 判断结果校验 ↗
- 实际消息序列 ↗
- 状态文字、历史和 input ↗
- 注册与整批预校验 ↗
- 批次执行前检查 ↗
- 工具名、ID和额度 ↗
- 提交回调和保存结果 ↗
- 默认 stream 的实现 ↗
- 默认快路与自定义快路 ↗
- 应用服务的装配 ↗
- Workflow 的显式包装示例 ↗
- 示例范围与假依赖 ↗
- 打包、消费者验证与第 09 组版本说明 ↗
- SDK 0.3.0 变更 ↗
- Core 版本 ↗
- Pi 包装的明确边界 ↗
- 当前源码导出 ↗
- 包版本与可选依赖 ↗
- 贡献规则 ↗
- 历史补丁记录 ↗
- 当前 MCP 依赖 ↗
20. 请求与交付协议:业务要交什么、接回什么
用户点“发送”时,交给 Harness 的不只是“我把铜钥匙递给北塔守卫,请他开门”。聊天业务还要告诉它:这是哪位用户的哪段会话、在和哪个角色聊天、这次运行哪套已配置的能力,以及本轮和历史分别是什么。 否则程序无法知道该取艾琳的资料、哪份旧笔记,也不能把结果归到正确消息上。
以“世界书+普通后台”这套已有接线为例,接入方交来的材料可以理解为:
**身份和归属:**用户 U、会话 C、艾琳的角色编号;本次调用编号 R,以及预留给这条助手回复的消息编号 A。
**本轮与历史:**用户现在的递钥匙原话;请求实际携带的既有聊天消息和各自编号。
**执行方式:**使用已经配置好的世界书+普通后台方案;模型和资料服务按这套方案装配。
谁证明“这是用户 U 的会话 C”?当前接入设计把这件事交给前面的聊天业务。 用户先在产品登录,聊天业务核验用户及会话归属、受理这次请求,再把身份与消息信息交给 Harness。Harness 的服务调用密钥证明调用方可以访问这个服务,不等于重新证明“请求里写的 U 就是当前登录用户”。不能因为请求包含了用户编号,就省略产品自己的用户授权;也不能把这里的服务密钥直接当用户登录凭据。
这些编号是为了找到和关联记录,不是发给用户看的剧情。上游没带来的聊天,不会仅凭“会话 C”就自动全部补齐。 这条闭环接法用请求里的消息作为历史来源,再按配置读取角色、模板、记忆等;历史保留多少以及最终哪些文字进入模型,还受模板和输入预算影响。具体字段与配置含义见请求合同,窗口如何控制见输入额度与控制权。
世界书用“角色使用的 Prompt 编号”找书。9 月 22 日主干已把接线扩到所有显式配置 worldbook 的闭环场景:普通 RP、Compact、普通 Agent V2、Story、Sumi 和前台工具循环。 不再要求只能使用专用 Worldbook 场景名,也不会对没配置的场景自动开启。旧 v1 预编译协议不支持这条通路。
每个逻辑轮先调用 worldbook.conversation.check 核对会话身份,再以场景的 tenant 和 Prompt 调用 worldbook.bindings.resolve,得到最多 20 本书各自固定的 revision。同轮重试复用本轮解析和选取,下一轮重新解析,改绑/跟随最新版/清空绑定都会影响既有会话下一轮。绑定为空时不创建 WorldbookTurn,不做 select/placement,不改变原场景历史与预算;身份核验和逐轮解析仍保留,下一句绑定了书就能重新进入选取。整轮超时覆盖这些 RPC 与后续 Actor,不是模型开始后才计时。绑定与控制权见世界书版本及关联。依据:协议与入口[1] · 整轮期限[2] · 空绑定与分流[3] · 解析结果校验[4]。
正常生成后,聊天业务接回的是“守卫没有接钥匙,要求先办手令……”这样的正文及相应结束、用量信息,负责展示并保存为助手消息 A。普通后台若另存了“用户已递出钥匙、尚未确认接收”的新笔记,那是另一条保存流程,不是正文回执的一部分。下一轮要重新带回已保存聊天,并读到已提交笔记,两个结果才会分别参与后续回复;收到一段流式文字不能代替这两次保存成功。
一次用户输入的完整业务过程见两轮运行案例。这里按接入问题定位准确合同。
| 接入方要确认的事 | 当前合同与详细位置 |
|---|---|
| 已经把角色、历史和本轮问题组装成模型消息 | 预组装入口复用这些消息,按加载的模型方案执行;该入口的日记和表格前后处理由聊天业务负责。见两种接入职责 |
| 交用户、会话、角色标识及问题,让应用组装材料 | 闭环入口读取已加载方案,准备模板、资料与预算,再按启用的流程执行。v2协议本身不意味着一定有普通后台。见请求字段和执行开关 |
| 用户消息、助手消息与请求各用哪个标识 | 会话定位、角色定位、调用追踪、消息身份分开传递;缺失必填信息、错误版本或不存在的方案不会自动换一套玩法。见身份与校验 |
| 什么才算回复交付完成 | 流式片段已出现、生成结束、聊天服务保存、后台状态保存是不同完成点;缺必要结束或用量信息还可能返回协议错误。见交付与回执 |
| 接口成功之后,还要由谁保存 | 正文交给聊天业务展示和保存;后台状态走独立提交;日记、表格等按各自收尾流程执行。见保存过程和记忆资料 |
准确字段、请求/结果示例、失败条件与源码都位于链接的同一份规范正文中;本入口不另起一轮对话案例。
入口边界:两种材料交法、最先失败的条件与固定代码位置
两种接法外层都使用 protocol_version=v1。extensions_version=roleplay-harness/v1 是预组装入口:聊天业务已经准备模型 messages,Harness 按方案调用模型;这条路径不会自行加上六专家后台。roleplay-harness/v2 是闭环入口:接入方交身份、角色、本轮输入和消息历史,Harness 再读取配置、渲染模板并按启用能力准备其他资料。普通后台是否运行,另看 agenticV2;Story 是否接管,另看 storyV1。
入口先检查项目与版本、extensions.scenario_id 对应的方案、调用和会话标识、模型配置标识、非空 messages 与 generation.n=1。闭环还要求服务端闭环依赖、方案的 modelConfigRef/presetRef、turn_context.user_id/model_alias。普通 Agentic 与 Story 的实际执行另需本轮 assistant_message_id。缺失身份、未知方案或准备失败,不会自动猜一套配置补跑;也不能把“请求到达服务”算作后台已经启动。
Agent Router 的 authorize() 核对配置的服务 Bearer;未配置密钥时,只有显式允许未认证调用才放行。闭环解析器从 turn_context.user_id 读取用户标识并检查字段要求,这不是本地登录认证或会话所有权证明。x-flow-user-authorization 是另一路可转发的用户凭据,此处只检查 Bearer 形式,不在这里解析验证用户身份。仓内接入合同的路径为“客户端 → Chat Service 鉴权与受理 → Agent Router → Harness”;Chat Service 保留认证、额度受理、消息保存、通知、费用和实验事件等职责。世界书 Demo 等独立入口另有身份来源,不能沿用这个服务密钥推定其认证方式。
这里的示例是材料职责说明,不是可直接发送的完整 JSON。完整契约继续以请求字段、身份校验和结果字段为准。
21. 工具接口:参数、返回与执行边界
本章用于接入与排错:已经决定用哪项能力后,核对谁能调用、传什么、返回什么,以及谁还须负责授权、校验、保存和后续读取。 业务需求、六专家长例与接线状态统一看能力目录;一轮怎样选工具、执行、读回并整理,统一看Harness 调度章。这里不再重复整轮教学。
本章保留既有工具接口的固定源码证据;9/21 已同步世界书每轮解析、Imagine 失败和可选 Jev 校验差异。新增 SDK gate 见独立慢路;不能因旧接口示例仍适用就推定后续 SDK 未变。AutoReply 是已有能力补充说明;以下请求与结果是教学节选,不代表线上实测。
先查哪组契约
| 已选的业务能力 | 精确接口入口 | 成功返回后仍须确认 |
|---|---|---|
| 本轮正文、配图、长期指令 | 前台动作 | 正文、实际图片与有效长期指令各自是否完成 |
| 人物、剧情等分析与状态整理 | 后台接口 | 分析不是状态;候选是否有效、有变化且按旧版本提交成功 |
| 世界书、记忆、Story、视觉资料 | 宿主固定步骤 | 返回材料给哪个模型,谁保存与再次读取 |
| 独立 JSON、图片、专家、SDK/MCP | 复用接口 | 新业务是否绑定 store、用户范围、执行时机和结果使用 |
| 单独验证工具 | 调试协议 | 隔离修改不是生产修改;真实模型/图片请求可能计费 |
一次模型工具请求有任务编号、准确工具名和编码后的参数。文字里说“最好检查一下”不会自动执行。专家参数可以是下面的节选;角色背景由宿主补入,不让模型在这些字段里凭空编齐:
{"reason":"用户安排此前未记录的使者出场","focus":"核对位置、关系和已知身份,保留未证实的来历"}
这里的 JSON 仅是 arguments 解码后的业务参数。若要核对“模型发了什么、下一步实际又收到什么”,展开下面的对应调用与回执。
一条调用与下一次模型实际收到的观察:ID、参数字符串和结果怎样对应
以 SDK Slow 使用的 AgenticToolCall 为例,主模型交回 toolCalls 数组,其中一项可为:
{
"id": "npc-example-1",
"type": "function",
"function": {
"name": "judge_npc",
"arguments": "{\"reason\":\"用户安排此前未记录的使者出场\",\"focus\":\"核对位置、关系和已知身份,保留未证实的来历\"}"
}
}
arguments 此时是 JSON 字符串。程序解码并把它交给注册表匹配的执行者;专家还从宿主取得角色、状态、历史和岗位要求。假设执行者返回下面的教学结果:
{"ok":true,"tool":"judge_npc","result":"已知使者站在北塔门外;姓名与所属势力未知,暂不补成既定关系。"}
SDK 保留上一条 assistant 的 tool_calls,再追加以下消息给下一次主模型;由同一个调用 ID 把问与答配对:
{
"role": "tool",
"name": "judge_npc",
"tool_call_id": "npc-example-1",
"content": "{\"ok\":true,\"tool\":\"judge_npc\",\"result\":\"已知使者站在北塔门外;姓名与所属势力未知,暂不补成既定关系。\"}"
}
这条观察供主模型继续选择工具或结束,不会自行写入状态。SDK Slow 的循环次数、严格整批参数检查和 prepareCommit 见接入契约;普通 RP 的后台则按第一阶段咨询、第二阶段整理的既定边界运行,不能把 SDK 的通用循环上限当作普通后台默认行为。
六专家等 Agentic capability 的回执按 {ok,tool,result?,error?,usage?} 读取;这是这组接口的格式,前台调度、Pi JSON 工具、Story 类和独立调试的外层结果分别按下面各自协议读取。ok:true 只说明这项工具交回结果,不保证分析正确、状态已保存、图片可展示或模型以后已经采用。advisory/readOnly 等说明也不替宿主实施权限隔离与事务。
菜单、注册与执行是不同边界
| 运行路径 | 谁控制 | 实际可用的工具/机制 | 用户等待的是什么 |
|---|---|---|---|
| 普通 Agentic RP | 场景开启 agenticV2,后台 Orchestrator 选专家 |
六个咨询专家 + update_director_state;菜单按 enabledTools 生成,执行层未再完整核对允许名单 |
当前 Actor 正文。后台分析在 Actor 启动时并行调度,不等分析完成再回复 |
| 前台简单编排 | 开启前台 function loop 的控制模型 | actor、over;有生图/DIO接线才额外提供 generate_image、schedule_dio |
控制模型选动作、Actor 生成片段;图片与 DIO 的完成在后台 |
| Story RP | storyV1 的宿主协调器 |
初始化 + 六个 World/Narrative 类 | 必要准备完成后才开始 Actor;采用过的正文在后续准备阶段结算 |
| 世界书 RP | 宿主在 Actor 前固定选条目 | worldbook.select RPC,不是后台 Orchestrator 的函数工具 |
选条目完成、注入后,Actor 才能回复 |
| 通用 SDK / Pi | 接入业务自己传入 tools/capabilities | 没有自动配齐的 RP 全家桶;可挑选任意已封装能力 | 完全由接入业务安排同步、后台或 Workflow |
Story 分支虽然也要求 Actor 的 Agentic 配置,但 dispatch 使用 if storyV1 … else if agenticV2,因此不会再同时启动普通六专家后台。当前 closed-loop 构建的是 CapabilityExecutor([]);旧式执行图能力不是已经默认塞进这条 RP 链路。
普通后台的 enabledTools 决定给模型的菜单,注册表仍登记全部七项,执行时未再完整核对本阶段允许名单。未注册名称会查找失败;当前普通 Agentic 未开启严格参数 schema 校验,不能把菜单标注的必填理解为程序保证拦住缺参。可选 Jev 的参数补全适配层另有严格 schema 检查,其检查不应与本段默认注册表混为一处,Jev 合同。完整执行检查见第22章工程调度;本章可分别核对前台回执、专家实际输入和后台保存。
当前交付:前台四动作的参数、返回与限制
前台编排:模型看到四个动作
| 工具 | 输入和触发 | 输出、保存与例子 |
|---|---|---|
actor |
responseMode 可为 complete 或 visual_beat,省略时为 complete;前台控制模型调用 |
生成当前用户可见正文片段,总输出额度由这一轮共享。有生图接线、visual_beat 形成可用完整片段且循环还有下一步时,由程序自动安排图片;complete 片段可再由模型选 generate_image。例:写出走进会客厅的一幕再配图 |
generate_image |
空参数,使用最近一段 Actor 正文;只有生图接线存在才列进菜单 | 立即返回已调度,后台实际生图并写回已保存的消息。例:为会客厅会面场景配图;不能在 Actor 前调用,也不能重复给同一片段配图 |
schedule_dio |
空参数,宿主取原始用户指令;工具描述要求模型仅在用户明确提出持续修改角色/世界/风格/行为时选择,执行层不再次语义复核 | 返回 accepted;后台 DIO 编译替换 Prompt,成功后供后续轮次使用。例:“之后总统说话请更克制”,本轮仍继续 Actor;收到任务不代表已改好 |
over |
空参数;至少已有一段 Actor 输出,且没有待完成的 visual beat 图片 | 结束本轮前台编排,不是角色退出、剧情结算或保存世界状态 |
visual_beat 是 Actor 参数。主线 dispatch 的 preActorDirector 配置实际装配上表这套前台 function loop。仓库另有 selectPreActorSkill / createPreActorDirectorHook,向模型提供 actor({skill}) 预选接口,但当前入口未使用该 hook,引用来自实现与测试。它应归到可复用能力,不能写成已经运行的第二条前台路径。skill 是参数值,afterActorTools 是配置字段,两者都不是新的模型工具。
依据:四个函数定义[6]、执行限制[7]、DIO 任务协议[8]、预选 skill 的 Actor schema[9]。
调度回执与宿主补齐的材料
前台 generate_image({}) 可返回 {ok:true,scheduled:true,imageIndex:0};scheduled 不是图片已生成。visual_beat 自动配图仍需形成可用完整片段且循环有下一步,恰好用尽步数不能保证自动安排。
schedule_dio({}) 的程序材料为用户原始要求、用户、RP 会话、目标角色指令 ID 与语言。回执含 accepted:true、appliesFrom:"next_turn";外部编译完成、后续读到有效版本并装入角色模板后才生效,不保证紧接着一轮已加载。本轮不半途换 Prompt;这也不是普通后台 Director 的剧情状态保存。
选择政策与程序检查不能混读。schedule_dio 的“仅用户明确要求长期修改”由控制模型根据工具描述判断;本地执行分支只核是否有 DIO 接线、是否本轮已安排过,随后把原始用户输入交给服务。比如“这一次说短点”按政策不应提交,但当前执行层没有第二次语义判断来保证拒绝。DIO 回执还会校验会话、请求、任务消息身份;这些身份检查不能证明请求语义确实是长期修改。外部 DIO 是否另有语义判断未在两仓中确认,也未由本轮外部实测验证。完整业务例子见长期要求的选择与后续生效。
**图片数量也分上限与交齐要求。**有限句式识别出的明确数字用于阻止超量安排,达到上限后会调整后续 Actor 配图模式;“达到最低请求数量再结束”则写在模型提示词中。over 硬检查 Actor 已运行且没有待安排的 visual beat,并不额外检查最低图片数量。已安排张数也不是已生成/已交付张数。因此“已结束”不能当作“用户要求的两张图均已交齐”;具体例子见本轮配图流程。
依据:DIO 选择说明[10]、DIO 执行与结束检查[11]、传递原始输入[12]、DIO 回执字段核验[13]、图片数量识别[14]、最低数量的提示词[15]、图片上限和配图模式检查[16]。
后台连续性:六专家、Director 与提交结果
专家参数、共享输入和返回
六项名称:analyze_plot、judge_npc、audit_knowledge、simulate_world、manage_callbacks、direct_scene。工具 schema 声明 reason 必填、focus 可选;普通 Agentic 没有开启严格参数校验。职责与长例统一看业务能力目录。
宿主补入主角色名字、描述、原始设定和开场;如有则带用户 Persona;轮初 state 与连续性记录;最近 9条有效消息;当前 query;如有则带较早历史的 Compact 摘要。9是消息数不是轮数,状态和记录有长度裁剪。各专家使用对应岗位 Prompt 与模型配置,同一底层模型可任多个岗位;正常成功通常一次模型请求,失败或空结果可能重试。
六位返回分析文字、可用 usage 或失败 error,不直接写正式状态,也没有各自独立长期数据库。同批共享轮初资料,并非先一位生成再让另一位读取;没有自动收到 Actor 本轮 Worldbook 原文或正在写的新正文。direct_scene 的 0–4主动性预算是写作主动程度建议,不是轮数、token 或代替玩家做决定的权限。
哪些规则会补调用,什么时候读回结果
普通 Agentic 每个逻辑生成安排后台,没有全局“攒满X轮再跑”,也不要求六位全跑。首逻辑轮会在已启用时补 judge_npc、direct_scene;最近4条可见历史与 query 的正则识别人名若不在轮初 state,会补 judge_npc。检测是启发式,可能漏检;执行仍受配置与额度限制。首轮/新人物这类强制检查在状态工具启用时要求 Director。
本批有专家调用且启用状态工具时,才进行第二次协调器调用,读成功或失败结果;第二阶段只开放 update_director_state,不是无限再开专家批次。没有专家时也可直接选 Director。完整分支以第2章为唯一整轮说明。
建议怎样变成下一轮能用的内容
| 工具/步骤 | 输入 → 输出 | 谁保存 / 什么时候生效 |
|---|---|---|
update_director_state |
轮初 state + 本轮材料 + 专家结果 + 更新 reason → 一份完整候选 state | Director 仅生成候选;Planner 校验长度/结构并通过 state runtime 的版本检查提交到 Axon。成功保存后的后续轮次读取 |
ReadMemoryTool / WriteMemoryTool |
宿主 store 的读取/CAS | 这是内部存储封装,不在上述 Orchestrator 的七项模型菜单里。数据库、会话隔离及原子写入由宿主存储提供 |
专家建议可以追加进连续性 ledger;Actor 后续读取的是有长度限制的 state/ledger 投影,不是把全部历史专家回复原封不动塞回 Prompt。若 Director 失败、校验不通过或提交发生版本冲突,不能宣称新设定已保存。
依据:六个工具定义和共享输入[17]、首轮/新人规则[18]、Director 生成及注册[19]、后续汇总和提交[20]。
candidateState 是完整待采用状态,不是一句建议。候选有效、有变化且旧版本仍可提交,才保存新状态与相应成功专家的分类记录;失败专家不能当成功分析保存。未执行 Director、生成失败、候选无效、内容未变或版本冲突,均可能没有新版本。Actor 后续读有限长度的 state/ledger 投影;当前正文不重写,下一轮来得很快也可能仍读旧版。
主线不能承诺先等本轮正文保存再提交。候选的消息分支绑定另见第24章,不能混成相同路径。
宿主固定步骤:Story、世界书、记忆与图文服务
Story:是宿主安排的世界/叙事步骤
这里的名称是执行日志名,后面对应工具类。这六步不是普通后台七工具菜单的扩容。工具返回候选快照、诊断和用量;Story 宿主负责保存整个 Story envelope、采用正文、版本冲突和恢复。
| 日志名 / 实现 | 何时输入什么 | 产出 / 例子 |
|---|---|---|
initialize / initializeStory |
无可用状态或需要重建时;角色卡、开场、最近可见历史、query | 初始化当前事件、已知场外事件、潜在线索、主副线。它是应用函数,不是工具包第七个 Story 类。例:建立“学院门口迎接求助者”,不把未来阴谋写成既成事实 |
pov_prepare_turn / PovPrepareTurnTool |
Actor 前;世界快照和玩家当前行动 | 识别 normal/cue/signal,必要时判断同伴跟随;机制控制时钟、阶段和可见舞台。例:用户只问塔内情况,不应被推断为已走进塔 |
narrative_plan_cycle / NarrativePlanCycleTool |
needPlan 时;叙事快照、世界/故事材料 |
生成有依赖的待推进事项,保留未清偿事项。例:先建立总统的可信证据,再安排盟友支持的回报 |
narrative_deal_beat / NarrativeDealBeatTool |
本轮准备;叙事快照和当前事件阶段 | 确定性选择符合前提的情节目标、情绪及主副线方向;本步骤不调用 LLM。例:当前仍是试探会谈,给“追问来意”而不是直接庆祝结盟 |
pov_advance_world / PovAdvanceWorldTool |
已采用的完整 Writer 正文 + 对应 prepared 快照 | 结算世界推进、场外结果与可见信号;模型只能补内容,不能随意改机械时钟。例:正文确实送达邀请后,才记录玩家已收到信号 |
narrative_settle_event / NarrativeSettleEventTool |
一个事件结束/被打断;完整事件正文和用户行动证据 | 判断目标达成、主副线推进、情绪变化,返回下一步动作;证据不明保留。例:只是提议结盟,不能按已经结盟发奖励 |
narrative_rebranch / NarrativeRebranchTool |
机制返回重分支动作时;main/sub scope、设定、主线所需 direction | 调整指定线并给衔接;例:玩家持续明确转向寻找回家通道,调整主线,而非一次闲聊就擅自换目标 |
当前 Emochi Story 会在后续请求准备阶段核对上一轮已保存正文再结算;不等于“本轮流式输出结束就全部变成世界事实”。改写/缺失的历史会影响采用与重建。
依据:Story 协调器调用顺序[21]、World 工具[22]、Narrative 工具[23]、初始化[24]。
图文服务:前台的“配张图”背后还有什么
| 能力 | 已有调用位置 | 输入 → 输出 / 保存与例子 |
|---|---|---|
prepare_visual_world |
Imagine 路径通过 MCP 或直接 VisualWorld runtime 调用;选中图片后才准备 | 会话/分支、角色外观、参考图等 → 读取或初始化视觉状态,交图片提示词使用。例:固定总统衣着和会客厅布局 |
| 图片提示词模型 | 宿主调用,不是让普通六专家来画图 | Actor 片段 + 视觉材料 → 图片描述;toolChoice:none,不再自由发工具调用 |
MCP generate_image |
兼容图片服务;与前台同名但参数完全不同 | 已保存的 messageId、imageIndex 等 → 外部 Image Agent 生成并回写消息、通知前端;前台那层只是调度入口 |
commit_visual_world |
完整回合成功且本轮做过视觉准备,宿主 whole-turn hook 后台调用 | 轮前视觉状态 + 本轮最终输出文本 → 持久化视觉变化;不负责生成图片。例:衣服被雨淋湿,后续图保留这一变化 |
generate_image_asset |
已封装为 /image Pi 工具,并可选暴露到图片 MCP;13c481b 独立调试 worker 也已接入;当前前台 loop 不注册此名称 |
prompt + 可选参考 URL/数量/尺寸 → task IDs、图片 URL、审核证据。不要求 RP 会话或消息,资产保存/展示由宿主决定。例:独立为新NPC绘制头像 |
**Imagine 当前失败边界(fa41d220):**先写消息图片位为 pending,再发下游请求;若请求尚未成功交接就失败,这条路径可能没有失败状态回写或恢复任务。安排成功、请求发送和图片可见是三个时点。完整失败证据。
Sumi 走自己独立的状态/正文/图片标记协议与后台生图流程,不能据此声称也调用这套 Orchestrator、judge_npc 或前台四工具循环。它的存储和恢复在 Sumi 分支独立完成。
依据:Imagine 的 MCP 调用与回合后保存[25]、MCP 暴露菜单[26]、独立图片工具[27]、Sumi[28]。
Story 请求节选与失败边界
PovPrepareTurnTool 收到世界快照、设定材料与 action:{type:"free",text:"我递出钥匙,请开门"}。没有待结算事件阻挡时,宿主把叙事快照和阶段交给 NarrativeDealBeatTool,取得给 Actor 的 packet。后续读取已采用正文后,把对应 prepared 快照和 writer:{prose:已采用正文} 交给 PovAdvanceWorldTool。结算仍 pending 时,本次准备报错终止,先前已保存的待处理记录供以后重试;不能宣称世界已推进或本轮已准备好。
世界书请求与模板消费
**9/21 当前取书流程:**先以 worldbook.conversation.check 核对会话,再按 tenant+Prompt 调 worldbook.bindings.resolve,得到本轮具体 book/revision,然后 select。同轮首次选择结果被缓存,下一轮重新解析;修改关联、latest 发布或清空关联可以影响已有会话下一轮。保存与解析示例。
worldbook.select 的材料为绑定书版本、当前输入组成的 query、近期 history、从旧状态解析出的 JSON 条件 state、token_budget,返回 blocks 原文与选择记录。当前query只用本轮原始输入,服务端hybrid另补最近两条非空历史;普通后台旧状态是分标题文本时,条件 state 通常是 {},并未发送旧状态全文。条目入选且放入模板后才进入当前 Actor;不经过 Director 保存,不自动送同批原文给后台。未命中不能认为模型已读规则。
看起来也是“能力”,但当前不是由 Agent 随机挑选的 tool
| 模块 | 谁触发 / 输入输出 | 对当前 RP 的作用与例子 |
|---|---|---|
| 世界书选择 | 宿主固定调用 worldbook.select;绑定书版本、query、历史、状态、预算 → 条目 blocks 与决策记录 |
Actor 前注入;例:用户问北塔时检索北塔规则。没有提供给 Orchestrator 一个“想查再查”的 worldbook 函数 |
| 世界书配置与检查 | Demo 读取 Prompt 关联后,可切换浏览书籍;worldbook.book.get、worldbook.book.entries、worldbook.index.get 读取实际书/修订。当前只读 RPC 不自行核验书属于该 Prompt |
例:查看“北塔规则”原文和索引状态;页面的查看操作不是 RP 模型发出的工具调用 |
| 世界书角色关联 | 管理接入保存 Prompt 与书籍关联;每轮 conversation.check+bindings.resolve,再用返回的具体版本选择 |
例:指定第 3 版保持该版;改为 latest 后下一轮跟随最新发布版。清空关联可无书聊天;Demo 只读关联,不提供保存按钮 |
| Compact | 上下文预算/检查点治理;历史 → 压缩摘要和保留窗口 | 在需压缩的准备阶段发生,影响当轮上下文;不是慢通道六专家中的一个,也不是固定累积X轮后必调用。已合入 main 的 #196/#198 Jev 过滤是该流程的可选前处理,默认 off,不是挂给 Agent 自选的新工具。模式和结果 |
| Axon Go 日记召回与写入 | 选定 axon_go 及对应来源后宿主 recall;确认生成成功后 memory.ingest 调度 diary orchestrator;turn.completed 在 ingest 返回后发出 | 召回摘要交模板变量;成功生成后的 ingest 调度后台,再经额度/锁/冷却等规则判断是否写日记。例:长期记住一起救援的经历 |
| Axon Go 表格记忆 | recall 表与版本;完成回复后解析编辑并按版本保存 | 例:物品表更新钥匙归属。Go 路径可后台 ingest;这不是模型调用 update_memory 的任意 JSON store |
| Persona / Personalization / Hinos | 相应 memory runtime 或 hook 的准备/回合后生命周期 | 给当前上下文提供用户材料或把本轮送到外部记忆处理;具体外部服务算法不是 Harness 六工具实现 |
“世界状态”也要具体区分:simulate_world 返回场外发展建议,Story World 按快照与机制推进事件,Visual World 保存外观/画面连续性;它们没有自动合并成同一份 state。
Axon Go 日记、表格召回结果成为 external setvars,只有模板实际引用相应变量才进入 Actor 提示词。Personalization、Hinos、冻结记忆试跑各走自己的返回与完成协议;Hinos取memory字符串,冻结记忆只读请求提供的内容,并不执行这套日记写入。世界书、Compact、专家 ledger、JSON memory 都有各自生命周期;不能把其中任何一个的保存说成自动同步其余所有模块。
依据:世界书调用[29]、日记/表格召回与写入[30]、Compact[31]、记忆模式接线[32]、旧版只读接口记录[33]、旧版会话绑定记录[34];当前绑定以新版接口及源码为准。
其他宿主入口:回复 hooks 与快捷回复
before_chat、before_chat_prompt_source 提供前置资料/变量,after_chat 可交回替换正文;具体额外保存取决于外部实现。独立 auto_reply 请求生成玩家下一句的选项,具体取材和返回见快捷回复;Sumi 走 Chat Service 独立路由。
快捷回复:玩家下一句的三个候选怎么来
角色回复完成后,上游可以单独请求三个“玩家接下来能说什么/尝试什么”的候选。 比如角色刚说“北塔门需要手令”,候选可以是“问去哪里办手令”“询问守卫是否认识这把钥匙”“先离开北塔”。这些只是示例;代码不会固定生成这三句,也不会替玩家点击、发送或宣告某个行动已经成功。
这次请求必须带要接续的assistant消息ID,并有AutoReply专用模型配置。Harness先读角色名字与描述,然后按当前运行方式进入以下一条路径:
| 问题 | 普通Agentic方式 | Story方式 |
|---|---|---|
| 指向哪句角色回复 | 在请求带来的可见消息中找到指定assistant ID,取它及其之前最多6条可见消息 | 请求中指定ID必须唯一且是assistant;取它之前最多6条可见消息,再按用户/会话/消息ID从Axon重读这句已保存的正式正文 |
| 除了对话还看什么 | 向Axon读取pending/planning_settlements中、source_message_id与指定assistant相同的auto_reply_guidance | 正式保存的assistant正文是当前锚点;不等待普通Agentic的guidance。更早对话和最近用户输入仍来自请求,不是全部逐条回库校验 |
| 为什么有时要等 | 等待这句回复对应的guidance,默认轮询窗口30秒,可配置;未命中时读回后间隔250ms。状态读取耗时可能超过窗口,整个请求不保证30秒内返回 | 不等这份guidance,但要成功取得正式正文;正文不存在/为空/ID或角色不符就失败,不退回请求里的副本凑建议 |
| 交给模型什么 | 角色、请求上下文中的输出语言、最近用户输入、对应guidance、锚点附近对话 | 角色、请求上下文中的语言、此前请求上下文、已保存正式正文;要求候选只是用户能说/尝试的下一步,不能预写别人反应或行动成功 |
| 得到什么 | 三个不同的用户候选;指令分别偏当前故事线索、关系/好奇、自由/中性方向 | 三个适合当下的不同策略,给暂停/澄清/其他合理方向留空间,不固定每个槽位的策略 |
| 拿到以后怎么用 | 上游把选项给玩家,由玩家决定是否采用;此请求不运行Actor,不更新世界或Agentic事实 | 同样只返回选项;不跑Story结算,不因为显示了“去找市长”就把用户位置改成市政厅 |
普通方式缺少可用消息或等待后仍没有对应guidance,会返回可重试的暂不可用;不会跳过事实来源随便编三个兜底选项。Story读取正式正文失败也不回退到可能过时的请求副本。模型最多有三次尝试,仍无法得到符合格式/语言等条件的三个候选则失败;两条路径的精确解析、重试和计量规则并不完全相同。失败时用户应由上游决定是否重试或不展示快捷选项,不应显示为用户已经采取了某个行动。
快捷回复的准确参数、解析、重试与失败条件
- 入口与保存: 当前
executeClosedLoopRequest在auto_reply时先行返回专用结果,不继续普通Actor/Agentic后台/Story结算。输出为1: ...\n2: ...\n3: ...的text,stateVersion=0,events=[];这个0不是重置真实世界版本。工具不自动发用户消息、不写RP状态;采用行为由上游处理。 - 消息锚点: 普通实现对可见user/assistant消息findIndex匹配首个指定assistant,没有Story的“请求内唯一”校验。两者都排除该锚点以后的消息,不能用未来对话生成当时建议。Story仅对目标assistant正文canonical重读,较早上下文仍是请求数据。
- guidance来源边界: 普通实现查同消息ID的pending和planning_settlements,只有非空auto_reply_guidance才使用。本次只证明消费合同,不以字段名称推断所有后端都会生成该字段。
- Story optional pendingStage: 函数类型允许传“尚未发生的提案”,prompt明确不是已完成事件/用户知识;当前dispatch调用并未传pendingStage。不要把工具接口支持写成该入口本轮一定附带了提案。
- 提示词与语言: system由专用模型配置的auto_reply模板经PromptManager渲染,必须含语言宏;user另放上述材料。调用useNativeLanguage=false;中文/日文/韩文有字符脚本检查,不等于完整语言质量验收。未读取当前线上有效模板全文。
- 两种重试不同: 普通每次以同一套system/user重试,最多三次;Story在格式不合格后追加前次输出与纠正要求再调同一配置。取消或stopModelRetries定义的错误会提前退出;recoveryAttempted也限制继续尝试,不能承诺一定打满三次。
- 选项格式不同: 普通解析兼容数组、options对象及content项,清理编号/空白,截取每项160字符、去重、最多取3;最终必须有3个。Story同样兼容数组、options对象与content项,但要求提取出的候选数组恰好3项,非空、互异、每项不超过160字符,超长直接视为不合格。不能把二者写成完全相同parser。
- 计量: dispatch设置requireUsage=true;一般usageStatus=invalid不被接受,但恢复配置
tolerateMissingStreamMetadata可使tolerateInvalidUsage=true。缺usage会调用Axon countTokens估算输入和输出;没有完成所需计量不能无条件当成功建议返回。内部函数也允许调用方不要求usage,不能把dispatch要求写成所有直接使用者的硬编码默认。 - 取消与debug审查项: 普通AutoReply把捕获的原始error.message作为lastError,最终可能交给Axon debug node;这段无本地脱敏,需核实上游错误内容、debug权限与保留策略,不等于已发现泄露。Story在canonical读取和model后检查signal,但required-usage countTokens await后到成功return没有再显式检查;依赖不遵守取消时存在迟到结果边界。只列为实现审查项,本次没有运行定向测试。
当前固定源码证据:入口与模型配置/输出/错误映射[35]、提前返回[36]、普通消息和重试[37]、普通guidance轮询及user prompt[38]、普通选项解析[39]、Story正式正文与候选生成[40]、Story严格选项格式[41]、语言模板[42]。
独立复用:JSON、图片资产、专家适配与 SDK/MCP
有现成封装,业务还需主动接入的工具
| 名称 | 怎么用 / 存什么 | 当前接入边界 |
|---|---|---|
get_memory |
空参数 → 当前授权范围 {revision,memory};缺省 revision=0,memory=null。例:读取用户偏好的称呼 |
/memory 原生 Pi 工厂提供;13c481b 独立调试已接隔离 store,仍没有在 Emochi Orchestrator/前台注册 |
update_memory |
{expectedRevision,memory} → 完整替换 JSON 后的 revision。例:保存 {preferredName:"阿林",…其余要保留的字段} |
独立调试只改本次内存;生产接入仍需宿主绑定用户/会话 store 和 beforeUpdate 业务校验。漏写字段会删除,不是局部 merge,也不是日记系统的别名 |
toPiTool |
包装六专家:业务 prepare 提供授权上下文、模型、Prompt;Pi 接收 content/details |
适配函数,不是业务工具新名字;默认 RP context 有类型边界,自定义世界数据不能无条件硬套 |
createAgentCoreToolWithContext |
宿主同步编译自己的上下文供同一专家分析 | 可让 NPC 专家分析自定义剧本/项目,不会自动检索世界书或继承 Actor 的完整 Prompt |
SDK SlowTurnRuntime / FastSlowRuntime |
业务传 capabilities,模型调用后由业务解释结果;持久化需显式 prepareCommit/store |
两种 runtime 是执行框架,不是工具。默认能力列表可为空;不会因为包里导出就把全部工具注册 |
McpCapability / CapabilityExecutor |
按静态执行图调用指定 MCP、传依赖结果、投影 prompt/artifact | 通用接线类已存在;aoi.scene-observer → aoi.observe_scene 是仓内示例,当前 closed-loop executor 空列表,不能写成线上自带场景观察工具 |
依据:JSON 两工具[43]、Pi 适配[44]、SDK 注册入口[45]、静态 MCP 示例[46]、工具包 exports[47]。
JSON 版本与完整替换示例
get_memory({}) 假设返回 {revision:12,memory:{preferredName:"小林",keyReturned:false}}。要保留钥匙字段,就提交 update_memory({expectedRevision:12,memory:{preferredName:"阿林",keyReturned:false}});成功返回 {revision:13}。漏写 keyReturned 会删除它,版本冲突先重读。正式称呼是否变化仍取决于宿主再次读出并注入。
AxonJsonMemoryStore 需要用户、会话、namespace、key,通过 get/CAS 读写;当前应用未见实例化,与普通 Agentic state 的存储范围不同。ReadMemoryTool/WriteMemoryTool 依赖宿主 store 的 get/CAS,不自带数据库;beforeUpdate 业务校验、权限隔离和事务仍由宿主落实。
JSON 与图片参数的准确范围
**JSON 记忆。**get 参数严格 {};update 参数 expectedRevision 为非负安全整数,memory 为 JSON 对象,有 64 KiB 校验。整对象替换;beforeUpdate 为业务校验入口;工具标 replay:never。读写 store 的产品/用户/session 作用域由程序绑定,不交模型任意填。
图片。 prompt 执行校验 1–32768 UTF-8 字节;reference_images 最多 9 个无用户名密码的 HTTP(S) URL;count 1–8,width/height 正整数。configRef source=multimodal 或 image-model,id 由 host 绑定;execute 交给 host.generate。结果含 1–8 个 jobs、每 job 的 task_id/image_urls/moderation,总审核状态与逐图证据状态必须为 COMPLETED/ERROR,逐图 asset_url 还须与对应 image_urls 一致;结构通过不等于展示许可。PENDING、缺少任务/图片/审核对应关系等不合格回包会抛出“结果未知”,不能当作成功返回的待完成任务。replay:never,未知结果不自动重试。
参数依据:JSON严格字段与版本[48]、图片参数和回包[49]。
图片资产、独立专家与生命周期
generate_image_asset({prompt:"蓝斗篷守卫的头像",count:1}) 可独立生图,可选参考 URL、数量、宽高,返回 task IDs、图片 URL、审核证据;不要求 RP 消息,宿主决定展示与资产归属,不能仅见 URL 就展示。它不是前台空参数 generate_image 的另一种填法。
独立专家需要业务提供模型、Prompt、授权材料和问题;toPiTool 包装为 Pi content/details,自定义数据由 createAgentCoreToolWithContext 同步编译。装在 Writer 前并等待,就增加本轮延迟;放后台则以后消费结果。仅安装不会获得应用的后台调度、世界书输入或持久化。
工具支持执行前、执行后、整轮结束处理;整轮 hook 要宿主主动调用。SDK 需另提供能力、模型、store,持久化按需显式 prepareCommit。外部写入已成功后,不能因后续日志失败盲目重复写入。
selectPreActorSkill/createPreActorDirectorHook 提供 actor({skill}),需要 skill 列表、Actor 参数、afterActorTools 和 hook 装配;当前 dispatch 的 preActorDirector 配置实际接的是前台 function loop。skill 是参数,afterActorTools 是配置,都不是额外模型工具。
独立调试:十项目录、HTTP 参数、结果与取消
独立工具调试:十项能力怎样准备、执行与看结果
这是调用方明确选一项工具的测试入口。比如先单独检查“日落前归还钥匙”的承诺是否被识别,再单独测试一个 JSON 记忆更新。它不启动普通 RP 的 Planner/Actor 链,也不会自动把测试结果变成下一轮角色事实。
| 工具目录 | 执行类型与输入 | 返回与保存范围 |
|---|---|---|
analyze_plot、judge_npc、audit_knowledge、simulate_world、manage_callbacks、direct_scene |
model;arguments 为 reason 和可选 focus,另给上下文、岗位 Prompt、模型及参数 |
真实模型的咨询结果及可用 usage;不写生产状态 |
update_director_state |
model;使用 director Prompt slot、输入状态与本次材料,复用生产同源生成和最终校验 |
合法候选才应用于本次隔离 state,返回前后状态与增加后的 revision;不调用生产 CAS |
get_memory |
sandbox;arguments={},context.memory={revision,memory} 提供隔离种子 |
读取这次输入的副本;不去查玩家真实记忆 |
update_memory |
sandbox;arguments={expectedRevision,memory},其中 memory 是完整替换对象 |
对本次内存副本做真实 CAS 校验;版本冲突失败。每次执行新建内存,跨运行延续需显式传入上次 after |
generate_image_asset |
image;arguments 为 prompt,可选 reference_images/count/width/height |
真实 staging Axon image.generate,返回任务、URL 和审核证据;可能计费、生成 CDN 资产,但不写聊天/角色、不发通知 |
例如读取 {revision:1,memory:{preferredName:"小林"}},再测试替换为 {preferredName:"阿林"}:成功的 update_memory 可返回 revision 2 的 after。这里测试的是工具的版本与替换行为,正式用户称呼不会因此改变。真正接入 RP 还要绑定生产 store、授权范围和把记忆送入上下文的读取入口。
依据:完整目录[50]、隔离 store 与 CAS[51]、工具执行及 before/after[52]、Director 最终校验[53]。
技术接入:HTTP 顺序、配置快照与返回字段
| 顺序 / 接口 | 请求与返回 | 需要读懂的边界 |
|---|---|---|
健康检查 GET /healthz |
返回 {ok,contractVersion,build} |
同样要求 bearer 并拒绝 Origin;健康响应不代表各下游模型或图片服务均已验收 |
1. GET /tools |
返回 {tools,businesses,build};每项含 id/name/inputSchema/examples/executionKind/runnable/disabledReason |
十项有入口,不代表本环境依赖齐全;不可执行项仍返回明确原因 |
2. POST /prepare |
{toolId,exampleId?,modelName?,modelConfigId?,preview?,previewDraft?} → draft、签名 snapshot、snapshotHash、configHash、来源和模型选项 |
不调用生成模型;模型工具冻结主/恢复 ModelRuntime、原 Prompt 模板、语言、构建与允许模型;记忆/图片用 host snapshot,无须伪造聊天 ModelConfig |
3. POST /execute |
{runId,snapshot,snapshotHash,draft} → status/output/steps/modelAttempts/durationMs/build、实际草稿及 hash 等 |
核验签名和构建;在规则内允许改草稿的参数、上下文、Prompt、主模型名/参数。执行用冻结模型映射,configHash 绑定冻结来源和实际草稿 |
4. POST /cancel |
{runId} → {runId,cancelled} |
只找到并取消本进程的活动运行;执行结果另报 cancelled/timed_out。跨副本由 BFF 取消等待中的 execute 连接,不承诺外部任务或费用回滚 |
POST 请求必须使用 application/json,请求体上限为 1 MiB;程序既检查声明的 Content-Length,也累计读取字节,超限拒绝。请求限制[54]
draft 统一保留 {arguments,context,prompt,modelName,parameters}。记忆和图片的 prompt/modelName 固定为空串,parameters={};图片真实 Prompt 在 arguments.prompt。模型的语言/native 选择属于准备时冻结内容,改变它需要重新 prepare。模型权重、宏服务和图片配置引用背后的下游版本并未完全冻结,不应承诺严格复现相同输出。
执行结果要分两层看:外层 status 是 completed/failed/cancelled/timed_out;内层 output 有 {ok,tool,result?,error?,usage?,details?,sandboxState?}。steps 和 modelAttempts 可用于查看真实调用和耗时,作为这次 tool_debug 运行结果返回;没有自动导出到 Langfuse。响应内容可能有明确的截断标记,实际执行草稿不会为了展示而被静默截断。
成功记忆/Director 的隔离结果会包含以下结构。下例只展开 sandboxState,是接口示意,不是一次真实执行记录;Director 的 before/after 则是它自己的状态对象:
{
"isolated": true,
"before": {"revision": 1, "memory": {"preferredName": "小林"}},
"after": {"revision": 2, "memory": {"preferredName": "阿林"}},
"committedToProduction": false
}
Director 候选最终校验失败时返回 ok:false,不会产生一次成功隔离状态更新。六位专家和图片不因目录统一就获得这份 before/after。图片的 details.jobs 带原任务和审核信息;工具执行完成不代表图片审核已通过。当前文档要求总审核和单图审核均完成、单图为 SFW 且 blocked=false 才展示对应 URL。断连或取消前可能已经产生模型费用/图片任务,不自动重提不确定的请求。
所有接口都要求 bearer,worker 拒绝带浏览器 Origin 的请求;面向用户的 BFF 负责用户授权、run 所有权、持久记录和去重。worker 的 run ID 去重是进程内的,不是跨重启持久队列。当前 saveSupported:false:worker 没有配置写入/发布接口;调用方若另外支持保存 staging 预览,也与修改生产配置、绑定场景和迁移流量分开。
依据:路由/鉴权/取消请求[55]、请求及输出类型[56]、准备的签名快照和草稿[57]、执行校验与进程内去重[58]、冻结模型读取[59]、图片审核与外部影响[60]、观测/取消/保存协议[61]。
固定源码与历史巡检证据:其余原链接
保留原章节的独有证据链接,方便继续查实现;不表示本次刷新 PR 或部署状态。
- packages/tools/src/modules/memory/advisory.ts#L63(13c481b)[62]
- apps/emochi/planning/agentic-v2.ts#L879(13c481b)[63]
- packages/tools/src/memory-tool.ts#L14(13c481b)[64]
- apps/emochi/tool-debug/catalog.ts#L15(13c481b)[65]
- packages/tools/src/modules/memory/advisory.ts#L18-L37(77a1537)[66]
- packages/tools/src/modules/memory/advisory.ts#L239-L273(77a1537)[67]
- packages/tools/src/modules/memory/advisory.ts#L169-L236(77a1537)[68]
- packages/tools/src/modules/memory/advisory.ts#L63-L79(77a1537)[69]
- apps/emochi/planning/agentic-v2.ts#L671-L739(77a1537)[70]
- apps/emochi/planning/agentic-v2.ts#L841-L875(77a1537)[71]
- apps/emochi/planning/runtime.ts#L700-L716(77a1537)[72]
- packages/tools/src/modules/memory/advisory.ts#L31-L37(77a1537)[73]
- apps/emochi/planning/prompt-manager.ts#L195-L252(77a1537)[74]
- packages/tools/src/modules/memory/advisory.ts#L315-L341(77a1537)[75]
- apps/emochi/planning/agentic-v2.ts#L878-L956(77a1537)[76]
- apps/emochi/planning/agentic-v2.ts#L979-L1008(77a1537)[77]
- packages/sdk/src/registry.ts#L38(77a1537)[78]
- apps/emochi/prompt/compiler.ts#L33(77a1537)[79]
- packages/tools/src/tool.ts#L10(77a1537)[80]
代码证据 · 80 处
- 调用与消息结构 ↗
- 写回带ID的工具观察 ↗
- Slow执行与提交 ↗
- 实际分支与注册 ↗
- 普通后台启动点 ↗
- 四个函数定义 ↗
- 执行限制 ↗
- DIO 任务协议 ↗
- 预选 skill 的 Actor schema ↗
- DIO 选择说明 ↗
- DIO 执行与结束检查 ↗
- 传递原始输入 ↗
- DIO 回执字段核验 ↗
- 图片数量识别 ↗
- 最低数量的提示词 ↗
- 图片上限和配图模式检查 ↗
- 六个工具定义和共享输入 ↗
- 首轮/新人规则 ↗
- Director 生成及注册 ↗
- 后续汇总和提交 ↗
- Story 协调器调用顺序 ↗
- World 工具 ↗
- Narrative 工具 ↗
- 初始化 ↗
- Imagine 的 MCP 调用与回合后保存 ↗
- MCP 暴露菜单 ↗
- 独立图片工具 ↗
- Sumi ↗
- 世界书调用 ↗
- 日记/表格召回与写入 ↗
- Compact ↗
- 记忆模式接线 ↗
- 旧版只读接口记录 ↗
- 旧版会话绑定记录 ↗
- 入口与模型配置/输出/错误映射 ↗
- 提前返回 ↗
- 普通消息和重试 ↗
- 普通guidance轮询及user prompt ↗
- 普通选项解析 ↗
- Story正式正文与候选生成 ↗
- Story严格选项格式 ↗
- 语言模板 ↗
- JSON 两工具 ↗
- Pi 适配 ↗
- SDK 注册入口 ↗
- 静态 MCP 示例 ↗
- 工具包 exports ↗
- JSON严格字段与版本 ↗
- 图片参数和回包 ↗
- 完整目录 ↗
- 隔离 store 与 CAS ↗
- 工具执行及 before/after ↗
- Director 最终校验 ↗
- 请求限制 ↗
- 路由/鉴权/取消请求 ↗
- 请求及输出类型 ↗
- 准备的签名快照和草稿 ↗
- 执行校验与进程内去重 ↗
- 冻结模型读取 ↗
- 图片审核与外部影响 ↗
- 观测/取消/保存协议 ↗
- packages/tools/src/modules/memory/advisory.ts#L63(13c481b) ↗
- apps/emochi/planning/agentic-v2.ts#L879(13c481b) ↗
- packages/tools/src/memory-tool.ts#L14(13c481b) ↗
- apps/emochi/tool-debug/catalog.ts#L15(13c481b) ↗
- packages/tools/src/modules/memory/advisory.ts#L18-L37(77a1537) ↗
- packages/tools/src/modules/memory/advisory.ts#L239-L273(77a1537) ↗
- packages/tools/src/modules/memory/advisory.ts#L169-L236(77a1537) ↗
- packages/tools/src/modules/memory/advisory.ts#L63-L79(77a1537) ↗
- apps/emochi/planning/agentic-v2.ts#L671-L739(77a1537) ↗
- apps/emochi/planning/agentic-v2.ts#L841-L875(77a1537) ↗
- apps/emochi/planning/runtime.ts#L700-L716(77a1537) ↗
- packages/tools/src/modules/memory/advisory.ts#L31-L37(77a1537) ↗
- apps/emochi/planning/prompt-manager.ts#L195-L252(77a1537) ↗
- packages/tools/src/modules/memory/advisory.ts#L315-L341(77a1537) ↗
- apps/emochi/planning/agentic-v2.ts#L878-L956(77a1537) ↗
- apps/emochi/planning/agentic-v2.ts#L979-L1008(77a1537) ↗
- packages/sdk/src/registry.ts#L38(77a1537) ↗
- apps/emochi/prompt/compiler.ts#L33(77a1537) ↗
- packages/tools/src/tool.ts#L10(77a1537) ↗
22. Harness 工程调度参考:工具请求怎样执行,结果怎样被采用
业务全程采用同一份两轮案例,本入口按工程问题定位到它的对应展开项。
| 需要核对什么 | 直接阅读 |
|---|---|
| 请求如何指定执行方式,哪些配置真正控制行为 | 请求字段、配置与预算 |
| 各模型的材料来源与状态来源字段 | 上下文、状态和来源记录 |
| 每次模型调用能装多少资料,谁配置,超限怎样处理 | 上下文窗口与逐路径预算规则 |
| LLM 如何给出一项可以执行的动作 | 工具调用字段;任务单与结果消息示例 |
| 参数解析、允许名单、调用额度和重试究竟保证什么 | 执行器与校验边界 |
| 工具返回后是否再次判断,哪些分支可以跳过 | 第二阶段与复核分支 |
| Director 到底写什么,哪些栏目是建议而非已发生事实 | 完整状态栏目 |
| 工具完成、候选生成与状态保存如何区分 | 结果字段与状态处理结果 |
| 普通后台是否开放 ReAct 循环,与前台、SDK、Workflow 有什么区别 | 四种调度方式 |
| 预组装、闭环和额外记忆收尾如何接入 | 宿主接入合同 |
| 可选 Jev 怎么选工具、谁补参数、是否改变普通 V2 启动规则 | Jev 的实际五步;请求/参数/失败合同 |
| Jev 的上下文预算、并列概率和业务 trace 有哪些现行限制 | Jev 启用边界 |
| 本轮从哪本世界书取内容,改绑后何时生效 | 每轮按 Prompt 解析书与版本 |
| 固定代码与原版证据在哪里 | 全部源码引用 |
| 某能力是默认已有、需装配还是候选,部署核实到哪一步 | 开发状态口径与能力表;各章开头的开发状态 |
这些入口对应执行器的不同责任;业务输入、输出、保存和下一轮使用集中在同一份案例中。
新合入的两处可选能力,分别接在哪一步
fa41d220 同时包含 Jev 决策适配器和 SDK 的慢路 gate。它们作用于不同位置,当前没有接成“Jev 先决定整轮后台要不要启动”的同一条业务链。
| 能力 | 在执行链的哪个位置 | 输入与返回 | 当前状态 |
|---|---|---|---|
| Jev 可选编排 | 普通 V2 后台已经启动,协调器需要挑工具时 | 读该阶段上下文及工具菜单;返回选择,再由文本模型补开放参数,最后形成执行器能调用的 toolCalls |
主干已有;必须显式配置 jevOrchestration.argumentModelConfigId,仓库场景未启用。六专家与 Director 仍走文本模型 |
SlowTurnRuntime.options.gate |
宿主调用通用 SDK 的慢运行时后、模型循环开始前 | 宿主注入函数读本轮上下文,返回 run:true/false;false 时跳过模型、工具与候选提交,返回 completed/retained |
主干源码已有,未见普通 V2 或其他业务宿主注入接线;旧 SDK 0.3.0 不含,0.4.0 及后续已发布 |
Compact 的 Jev 过滤也已进入 main(#196/#198),但属于另一条调用链。它在需要压缩旧聊天时筛对话组或助手段落,默认关闭;不产生工具调用、不决定普通 V2 后台是否启动,也没有新增 SDK 公共接口。过滤过程 · 合入与验证。
gate 返回 false 只是“这次按策略跳过”,不是一次成功的后台分析。 SDK 此次慢循环的模型调用数与 token 为 0,状态版本不变;gate 本身若由宿主调用外部模型,其费用不会自动计入这些慢循环计数。gate 抛错、返回非法值、取消或超时会走相应失败/取消/超时结果,不会被当作正常跳过。未注入 gate 时按原来的慢循环执行。普通 V2 自己的后台调度仍是每个实际进入生成的逻辑轮一次,不能拿 SDK 的新接口改写它的现状。
23. 变更记录:巡检与文档修订
本次更新最新回填截至 2026-10-19 14:51 的已完成巡检。当前行为已直接替换到对应章节,以下保留各次变化及当时证据;旧记录的未合/未部署不覆盖上方当前状态。本次使用已完成的增量报告、分审和固定源码更新文档,没有重跑远端巡检、产品模型、测试或生产验收,也没有部署线上 Wiki。
本次新增2026-10-19:记忆容错、摘要复用、Sumi 图文接入与监控
| 本次新增更新内容 | 现在具体怎样运行 | 状态和正文位置 |
|---|---|---|
| 本次新增Memory #301 | 业务可选择记忆服务临时故障时缺少召回记忆但继续回复;默认仍失败。Hinos 只容错可恢复服务错误,无有效 claim 不 commit | 已合 main;Emochi 有效配置未核。读取和写入 |
| 本次新增Compact #302 | 日记更新不再误作角色变更而废掉旧摘要;本次模型仍用新日记,未核来源不修改旧检查点,旧后台输入不能冒充本轮 | 已合 main。摘要复用 |
| 本次新增Sumi #300/#289 | Chat Service 选主模型,Sumi 接收模型参数和图文/纯文本开关;新增初始化父子追踪与阶段结果 | 已合 main;实验分桶和实际 trace 未独立验收。接入输入 |
| 本次新增生图编译 #304 | 新图片尝试编译失败后可带完整原标签继续生图;调用方取消、旧付费 claim、审核与 unknown 仍保留边界 | 已合 main。编译与交付 |
| 本次新增监控 #296 | HTTP/RPC 和 Sumi 分阶段指标已在 main 接线;关闭 Langfuse 仍按真实业务结果统计失败 | #296 已合;#297 另一方案仍开放。真实采集/看板样本未验。观察口径 |
| 本次新增DIO #303 | 完整成功回复后判断长期需求,后台生成会话专属角色正文,后续轮读到有效版本才使用 | Draft 未合;所谓 staging job 只有 build/push。完整过程 |
| 本次新增Compact 审计 #305 | off/shadow/repair;明确发现摘要问题才重做一次,修复结果需再次明确 pass | 未合、评审要求修改、无部署;作者 8 次复核全 uncertain、0 pass。条件与结果 |
本次新增Sumi 的 f9b26a9 已于 10/19 13:26 完成生产镜像更新与 rollout;未核当前 Pod、有效实验配置或用户体验。Worldbook main 仍 ad38dce,本轮只复核提交/部署列表,沿用 10/09 历史成功证据,没有重读 job、007 迁移或调用方。SDK Latest 仍 0.6.0;Core Tools 0.2.3 为前次已核基线。Fusion #255/#292/#293 沿用 10/13 未合历史,本轮没有重核 head 或逻辑。
本次新增依据是 10/13 手动快照至 10/19 的关键链增量审阅,不是全仓逐行复审。六项 main 的页面 checks 均显示 success;本次没有重跑这些测试,也不把 CI 当作上线效果验收。
2026-10-13:Sumi 历史恢复、角色精简修复及候选状态
本轮接入 10/12 增量报告与 10/13 昨日更新报告,状态截到 10/13 16:38。Harness 从 82e0169 经 ebab290、47fb054 到 6a108ddbddb46b03a4179f23ec6988b62aaf4e89;Worldbook 保持 ad38dce1de7ccd291d702a67b92c06a966fddf85,没有新代码。SDK 最新仍 0.6.0,Core Tools 仍 0.2.3。
| 更新 | 现在的实际变化 | 状态及正文位置 |
|---|---|---|
| Sumi #294 历史协调 | 已存正文与快照不符、来源不符或快照缺失时,先核实聊天服务正文,再重建。无效消息仅从本轮输入排除,RPC 失败仍终止;导入关闭也可触发恢复 | 已合入 ebab290,10/11 生产部署成功。记忆 · 来源、旧图和保存 |
| Compact #295 角色精简修复 | 三次 Actor 计数可切换分别合格的来源;只放宽角色精简模型的受限预检。最终完整回复输入仍须严格更短且不超预算 | 10/12 21:37 合入 47fb054,CI/镜像构建成功,未见部署。显式配置未改。完整条件 |
| #298 网络诊断 | 日志可保留白名单中的 DNS、TLS、连接、socket 或超时原因,保留原 HTTP 分类与重试语义 | 10/13 11:54 合入 6a108dd,CI/构建成功,未见部署;不证明证书或服务已恢复。字段与边界 |
| Worldbook 部署历史补证 | 查到 Entity 版本 ad38dce 于 10/09 10:59 完成生产部署,纠正此前只核到 9 月版本的旧状态 |
这次新增的是证据,不是新增代码/上线;007 迁移、调用方兼容和业务效果仍未验。部署与迁移 |
| Fusion #255/#292/#293 | 最新显式 over、有条件去重复生图指令、Rian 单张分镜工具;逐幕 instruction 字段尚未由 Jev 实际产生 |
依次叠加、都未合入;#255 只有构建,#293 未找到实际服务入口。逐项条件 |
| 监控 #296/#297 | 分别补 HTTP/Sumi 生命周期与应用操作/模型请求尝试统计、看板文件;部分指标和入口重叠 | 都未合入,不能拼成一套已交付能力;部署、采集与真实样本待验。观察口径 |
Sumi 的新部署源版本已包含 10/8 loading 占位,不再写作“未核到包含该代码的生产部署”;用户界面是否真正展示及通知收尾仍待验。Sumi #289、群聊实验和依赖候选保持自己的未合状态。#297 今日模型尝试计数和看板修正另按 10/13 记录,没有倒算成昨晚初稿已有。
报告记录的远端 CI、构建、固定镜像部署及 readiness 是各自时点的证据;本次未重跑这些检查。10/12 公开比对的 97 个 Wiki 文件仍与 9/24 发布包一致,是当时线上快照,本次未再抓取,不能据本地文档更新宣称线上已部署。分支下载归档也不等于全仓逐行审阅。
Sumi 10/11 部署 · Worldbook 10/09 部署 · #295 合并 · #298 合并。
2026-10-09:后台压缩、Sumi 图文、Entity 关联与 SDK 发布
固定主线为 Harness 82e0169ab2f59f38a11cbdc7e874deec720b0620、Worldbook ad38dce1de7ccd291d702a67b92c06a966fddf85。窗口内 Harness 27 个 PR 合入 main、Worldbook 1 个;另有两项合入群聊实验分支。提交/PR 数不是功能数。
| 本次变化 | 现在实际怎样工作 | 状态与对应正文 |
|---|---|---|
| Compact 新增后台执行与超限策略 | 明确启用后提前后台生成,当前继续用已有输入,后续读成功提交的摘要;硬超限默认同步,可选有条件临时少带历史 | 已合主线、生产启用未核。执行、保存与失败 |
| Compact 调整记忆保留与角色卡兜底 | 先为摘要留空间,真实超限时尝试继续总结额外闭合历史;过长角色定义可请求内压短,多字段仍留在原位置 | 已合主线;最后仍可能有损恢复;最新多字段修复晚于 SDK 0.6.0 标签。条件与边界 |
| Sumi 更新历史恢复 | 按真实 token 装载,提取窗口预留 1200 输出,八次只计新模型调用;仅用户参考图改变且历史匹配可局部复用 | 包含在 10/5 a119b8b 成功生产部署中;当前实例与真实效果未验。材料与预算 |
| Sumi 新增流式图片占位 | 完整图片指令出现后先通知 loading;整轮快照保存后才收费生图,取消/共享占位各自收尾 | 10/8 已合主线;晚于上述部署,未核生产。执行时序 |
| 世界书新增 Entity 调用合同 | 角色/故事等业务编号关联书籍,旧 Prompt 路由兼容;当前 RP 仍以 promptId 为对象编号,007 改名迁移保留数据 | 两仓已合入;生产迁移和 Axon 接线未核。接口与迁移 |
| SDK 新增独立世界书客户端 | 直接导入、修订、建索引、关联和选原文;业务自己处理权限、模型输入和保存 | SDK 0.6.0 已发布到 GitHub Packages。接入合同 |
| 观测扩展 | 已插桩正文取消仅 staging 限制,仍需开关、配置与采样;Sumi 新增图文事件,Compact 新增分阶段预算诊断 | 已合主线;发送成功不等于远端入库或业务效果变好。如何解读 |
| 更正 Pi/Omen 的交付状态 | Pi #244、Omen #250 均已合主线,分别有 SDK 0.5.0/Core Tools 0.2.3 发布证据 | 不再列待合候选;正式消费者采用另验。Pi · Omen |
| 分支更新 | 群聊参考流程只进 group-chat-spike;Fusion #255 新增继续/结束决策和 DIO 提示约束;Sumi #289 初始化追踪开放 | 不算 main 正式产品。各自输入、结果与状态 |
发布证据:SDK 0.4.0/0.5.0 于 10/8 发布,0.6.0 于 10/9 11:52 发布;核对 Release、tag 与成功发包运行,没有做独立安装验收。Sumi 10/5 的构建、推镜像、固定镜像部署和等待 Ready 均成功,但不能覆盖后续 main。0.6.0 Release · 发包运行 · Sumi 生产 job
本次差异扫描确认线上 97 个成功读取的文件仍与 9/24 包一致;9 张 PNG 与包外路径未穷举。本次文档回填保留既有章节和锚点,新增源码引用使用上述固定 SHA;既有段落继续保留各自历史依据,不将下载归档当成全仓已读。没有验证真实模型质量、当前数据库迁移、Pod、配置启用或终端体验。
2026-09-24 14:27:Worldbook 监控已合主干,空选择看板仍有查询缺陷
Harness main 保持 3b6ba5f3f22e11baceb1c6857560a97140f41a85;Worldbook main 从 fca57b8 前进到 005e19c664900e999fb7efca7b1dbe2da3629437,只新增 #18 的一个 merge commit(15 files,+3469/-13)。这轮定向审查新增指标、看板及相关调用、测试和部署证据,没有重审全仓。
| 本次确认的变化 | 对实际使用的影响 | 已回填位置 |
|---|---|---|
| Worldbook #18 已合 main | 服务累计 HTTP、绑定、检索、选择、索引、连接池和重建指标,由 /metrics 供采集;不改保存、版本、召回、排序或选择结果 |
项目全貌、选择结果、服务端指标 |
| 36 面板/34 查询与抓取注解已在仓库 | 作者称看板已导入 production Grafana,但 image/annotations 未部署;没有新 SHA 的 GitHub deployment,当前 Pod、target、真实序列没有直接核验 | 部署证据、四项观测对照 |
| 空选择比例有 P1 查询缺陷 | 查询 le="0" 不匹配实际导出的 le="0.0",分子没有序列;面板无数据不是空选择为 0% |
实际复现与测试缺口 |
Story #250 仍 Open,新 head 21021d6 待审 |
14:21 把 main 合进开发分支;只登记 3 commits/8 files merge 清单,旧 head 8bf877f 的关闭/换牌风险还须对新 head 复验 |
Story 原章、候选状态 |
最近直接成功的 Worldbook rollout 仍是 9/22 21:13–21:15 的 fca57b8,run 35732023874/deployment 6591512315。没有新 deployment 不能排除人工操作,旧 rollout 也不能代替当前 Pod 镜像读回。Worldbook #15 仍固定 be19065 开放,Harness #252/#254 head 未变;没有新增 release 或 tag。已有成功部署 · 本次主干 CI
巡检对固定 Worldbook archive 的本地测试记录为 132 passed、35 skipped(缺本地 TEST_DATABASE_URL),Ruff lint/format 通过,生成器与 JSON 一致。远端 CI job/steps 确认 PostgreSQL+pgvector、依赖安装、Ruff 和 pytest 成功;作者称远端 167 passed,但具体 job log GET 权限失败,数字没有独立日志核实。已有看板测试不检查实际导出标签与 PromQL 匹配,所以测试通过未覆盖上述 P1。本次文档维护使用这些已有结果,没有把它们称为重跑或生产验收。测试边界[1] · CI 环境定义[2]
原有图示继续说明资料进入回复、保存及下轮读取的业务链;本轮新增观测不改变这条业务链。新增监控关系在相应正文说明,不引入巡检中未通过几何校验的 Archify 候选图。两仓整仓完成游标仍为 null,不以这次增量回填表示整仓审查完成。
2026-09-24 08:29:Sumi 主线更新、Story 提示牌提案与 Fusion 部署
Harness main 从 43332d8 更新到 3b6ba5f3f22e11baceb1c6857560a97140f41a85;Worldbook 仍是 fca57b8af8ae74a44a033ea061043ecbf9a38373,没有新增;Fusion 单独到 c8fc61c86883fb2e9fceefab721b45f0829760f2。没有把分支部署写成主干能力,也没有把这次增量核查写成全仓审完。
| 本次结果 | 对业务实际改变什么 | 已更新位置 |
|---|---|---|
| Sumi #237/#239 已合主干;#240 仍在分支 | 主干新增用户参考图、可选绘图提示编译、主模型/图片/保存追踪,绑定规则由外部模板提供;#240 分支另加 staging 根输入/最终正文记录 | 图文运行、编译失败如何保存 |
| Sumi 状态重建已合主干 | 修改角色卡、开场白、人设或参考图,以及换历史分支后,以当前材料和选中历史重新整理状态,旧消息与旧图不改 | 状态何时重建 |
| Sumi #247 已合主干 | context_limit 按输入额度计算;当前 5000 配置可用 4647 输入,最大输出另留 2048;真实供应商窗口仍待验 |
预算与边界 |
| Fusion #241/#249/#253 已合分支并部署 | 图片失败额外发送无 URL 的终态通知;新增运行指标;DIO 请求固定携免计费 header | 图片收尾、观测、DIO |
| Story #250、Pi #244、主指标 #252、Loki #254 仍开放 | 分别是事件提示牌、原生 Pi 慢执行器、新 Prometheus 指标与已有日志看板;各自用途与采用条件不同 | 候选与部署状态 |
| Sumi #251 已关闭未合 | 图片失败模拟分支曾部署 staging,默认 off;不能把它当成 main 开关或已启用模拟 | Sumi 版本状态 |
Fusion c8fc61c 于 9/24 03:16–03:19 完成 production rollout;Sumi 最新可见 staging 部署是 9/23 21:41–21:43 的失败模拟分支 46383d3。部署完成的代码如上,当前 Pod、有效 compiler/Prompt Manager 配置、客户端终态、指标采集及 DIO 钱包均未由巡检直接验收。Worldbook 仍沿用 9/22 fca57b8 的生产部署记录,不计本次新增。Core Tools 已发布 0.2.2、SDK 已发布 0.3.0 的状态不变。Fusion 部署 · Sumi staging 部署
本次使用报告中的固定源码与测试记录;没有重跑产品模型测试。报告中 Sumi 主线 87 项、compiler/追踪 108 项,Pi 22 项、Story 41 项、主指标 43+26 项、Fusion 指标 4+14 项、DIO 3 项定向检查通过。Story 关闭/替换牌组失败和 Sumi compiler 短暂错误被持久化为终态仍保留;它们不是“CI 绿了就已修复”。
2026-09-23 08:31:流中断续写、混合压缩、世界书短历史与生命周期日志
这三轮把Harness从 ccaaa46e 更新到 43332d8616b4e24874915a69cdea7bdaa0429aba,Worldbook从 fafdb8d 更新到 fca57b8af8ae74a44a033ea061043ecbf9a38373;Fusion单独核对至 c75dabb942bcf5ab00e2cadbabd95ef961203e69。报告完成的是固定增量及明确候选,不是重新审完两仓全部历史。
| 原章更新 | 现在实际怎样工作 | 合入、启用与部署 |
|---|---|---|
| 当前回复与失败 | Gemini中断后保留已见前缀,单次DeepSeek续写;未见正文时扩大上游恢复资格;修复prefix计数和旧流兼容 | #214/#216/#220/#230/#233已main;需recovery和相应流条件,真实接缝质量及main workload未验 |
| Compact | #205本地估算与段落V2、#218 preset摘要位置、#231 bootstrap/primary/fallback共享预算和一次提交;#211错误覆盖配置拒绝继续 | 均已main;各能力显式配置,不能把production目录存在当Hybrid生产启用 |
| 场景加载 | 基础/实验目录、前缀*选择、同名实验优先、旧JSON整条覆盖,并输出有效hash | #232已main;实际workload目录与启用列表未读回 |
| Story与发布 | Core Tools可传最多4000字符userPersona;普通V2已接,StoryV1五处调用未传 | Core Tools0.2.2发布成功;SDK0.4.0仅准备,发布失败且无tag/release;SDK最新仍0.3.0 |
| 世界书选择与预算 | 原始输入与历史分开;hybrid补最近两条历史、返回检索与预算诊断;请求内缓存精确成本 | 88c99e99已部署短历史;fca57b8后续部署包含等价预算优化。真实效果、性能和Harness采用另验 |
| Fusion与#209 | 20秒正文watchdog、正文/图片解耦、图片失败隔离、5秒模型对冲;同消息追加状态修复依赖新ID合同 | 6dac2cbe已有直接部署,含前四项;#209后来只合Fusion至c75dabb,无后续部署。败方成本未闭环 |
| 观测与Memory | exact staging开放普通Langfuse内容;所有环境常开stdout原始输入/错误;表格已保存后提炼失败仍只记memory failed | #235/#236已main,后者经owner接受内容边界后合入,不能继续列未合blocker;43332d8仅build/push |
| Sumi#237 | Persona双参考图、托管模型、compiler先于付费生图、全链trace;非ready图片在stdout可能仍completed | head8d83f70仍Open、无review/部署;68项定向通过不等于聊天落库与交付验收 |
Worldbook最新生产run 35732023874/deployment 6591512315于9/22 21:13–21:15成功,包含Selection v3、短历史hybrid、解释诊断和请求内精确预算缓存;此前18:04–18:06的run 35713959292发布短历史。Fusion production于23:54–23:56完成deployment 6594895170的6dac2cbe部署,实际功能如上表。两项当前Pod digest均未独立读回。Harness main 43332d8的run 35771926336/deployment 6598612800只有镜像build/push,没有apply/rollout,因此main新功能和原始日志是否在线生效均未知。
引用的巡检测试结果为:9/22晚间Harness470项中469通过、9/23凌晨main463项中462通过,均保留Node24 stdout mock失败;Fusion恢复68/68、Actor161/162,Narrative大文件未取得全量通过。Worldbook针对选择/诊断/位置70/70,production工作流完整数据库测试成功。最新main日志/Memory52/52,Sumi候选68/68;受控Memory复现确认“replace成功、提炼失败、只有failed日志”。这些不是此次文档维护重跑的产品测试,也没有真实模型、生图、生产流量或业务验收。
当前main[3] · 最新Harness镜像构建 · Worldbook预算优化部署 · 短历史部署 · Fusion当前审读代码[4]
2026-09-22 14:40:累计计数、空响应恢复与世界书部署
本次回填 14:13 开始、14:40 标记完成的巡检。Harness 固定范围为 a4f5bb83..ccaaa46e;Worldbook main 仍为 fafdb8d,新增的是部署证据与开放候选记录。本次维护复核保存的源码与报告,未另跑远端巡检或调用真实模型。
本条随后按同一份报告补齐两处原段落说明:PR #205 估算偏低可能带来的拒绝与回退等待,以及分类失败保留原文的处理;Worldbook PR #15 中各 Pod 的本地缓存不共享。两项均已对照保存的候选版本源码,属于文档补漏,没有新增巡检或上线结论。
| 项目更新 | 已有行为与启用状态 | 对应内容 |
|---|---|---|
| Compact 累计计数 · main #207 | 新增 boundarySearch:"cumulative",只用于 bounded_recent;借片段累计计数减少边界探测,最终仍检查完整模型请求并通过原保存规则。默认 binary;已有场景未配置 cumulative |
长历史压缩:算法、配置、降级、实际计数与质量取舍 |
| Actor 空响应恢复 · main #208 | 配置了恢复模型且满足已有条件时,router.empty_response 可切一次允许的 DeepSeek 模型;备用仍为空则失败。已有 POV 场景含 recovery 配置,但未核当前线上采用 |
前台回复、Agent V2 产品、失败与恢复 |
| Worldbook 生产部署成功 | fafdb8d 于 10:59–11:02 完成数据库测试、镜像构建、部署、rollout 与镜像一致性检查;run 35681509122、deployment 6582461066 成功。纠正 08:42 时“未见对应部署”的旧记录 |
世界书部署现状与业务接入边界 |
| 候选 #205/#209/Worldbook #15 | 本地估算及段落 V2、同助手消息追加的状态关联、滚动发布策略仍分别属于开放 PR。#209 目标是 fusion-harness,不能作为 main 的保证;#15 的 readiness 不保证向量重建已完成 | 对应能力的候选说明与旧 Wiki 候选章节 |
| 文档 #210 与待查 #211/#212 | #210 只有文档改动。#211/#212 及 #205 后续 head 仅登记为待复核,不从标题推导产品功能 | 本条巡检范围与后续记录 |
**部署与测试的准确范围。**Worldbook 当次部署成功已经成立;14:xx 当前 workload 未独立读回,job log GET 失败未取得具体 digest,不能补写不存在的集群读回结果。真实 Harness 流量、迁移 006、权限与向量/混合检索业务效果仍未验收。Harness ccaaa46e 的 CI 和 staging 镜像构建成功,后者只有 build/push,不能算工作负载已经部署。
巡检记录 Compact 定向 22+10+12 项、新增 Actor 空响应恢复 3 项通过;Actor 全文件 111/112,唯一失败涉及既有 Node 24 stdout mock;类型检查遇到既有环境相关 TS2742。这里引用巡检记录,没有在文档维护中重跑这些产品测试。离线累计计数实验走了 legacy fragment fallback,其耗时降幅不能写成生产延迟或摘要质量提升。
**Wiki 结构调整。**产品与能力 Wiki 现在分成三个并列模块:01 完整产品、02 原子能力、03 业务接入。“业务如何接入”移入第三模块,原章节与段落地址保留;这项调整不改变产品代码。
Harness 固定主干[5] · Worldbook 生产部署工作流 · Harness staging 镜像构建 · PR #209 · Worldbook PR #15
2026-09-22:两仓主干增量与接入边界
本次合并 02:14 和 08:13 开始的两次已完成巡检,最新完成时间 08:42 CST。Harness 从 fa41d220 经 c2264753 更新至 a4f5bb83;Worldbook 从 9fd897e 经 a2dad786 更新至 fafdb8d。使用报告及保存的源码定向复核受影响调用链;本次文档维护没有另跑远端巡检、真实模型或生产调用。
| 项目变化 | 实际结果和启用条件 | 对应说明 |
|---|---|---|
| Worldbook 接入扩展:Harness #197/#199 | 显式配置后,普通 RP、Agent V2、Compact、Story、Sumi、前台工具循环均可使用世界书。每轮校验会话、解析绑定,同轮复用固定版本快照;返回空书单时不建立选择任务,不占条目位置预算,下一轮仍会重新解析 | 世界书上下文与接入章节;Agent V2、Story 产品及世界书原子能力 |
| 每次 Actor 调用重新放置世界书 | 本轮重试/分段 Actor 调用分别渲染、计数并只裁旧历史,固定提示、当前输入、条目和续写材料受保护。放不下的重试目标跳过,不污染下一个目标;本轮条目仍不自动进入 Planner、长期状态或聊天原文 | 模型输入、窗口、异常与世界书注入 |
| Prompt 绑定修复:服务 #13 | 移除两条绑定外键限制,通过应用层验证整个批次后替换;读取遇到失效书籍/版本返回 409,不悄悄丢一部分绑定。生产需执行 migration 006;AUTO_MIGRATE=false,镜像更新不代替表结构升级 |
导入与 Prompt 绑定、接入条件 |
| Selection v3:服务 #14 | 每一轮先通过预算/冲突录取条目,再用真正录取的正文及依赖递归;被拒条目不再额外触发其他设定。中文多字 query 用连续双字匹配,避免常见单字反复加分;单字 query 仍支持 | 条目选择、动态召回、世界书能力 |
| Compact 过滤进入 main:#196/#198 | 完整对话组过滤、助手自然段过滤和实测边界搜索已合入,默认关闭;自然段策略只筛 ≥40 字的 assistant 段落,drop 概率 ≥0.8,用户消息不删。超限回退恢复完整原输入与原摘要;语义误省略仍需质量验证 | 长历史压缩、记忆保存、配置参数;原候选链接保留并标已合入 |
| Worldbook 调用观测:#200+后续修整 | 总观测仍默认关闭;启用后 query、历史、state、binding、选中 lore 可进入 Langfuse。只放行宿主 Worldbook envelope,每项最多 16,000 JSON 字符,超出保留结构化 preview;没有单独正文开关 | 观测与成本、世界书接入与 SDK 接线 |
| Actor 早期失败恢复缓冲:#206 | 配好恢复模型且符合即时流式条件时,主模型首次尝试在生成正常完成或首个正文片段后 4 秒释放缓存;未发可见正文且符合恢复条件时可切一次备用模型,已发可见正文后不能无痕切换。并非所有请求固定多等 4 秒 | 当前回复、失败处理、延迟及 Agent V2 产品 |
| SDK/应用文档整理:#159 | 新增/整理 46 份 SDK 与 Emochi 文档,帮助定位公开接口与接线;这次文档提交本身不代表新增运行能力、发包或部署 | 工程参考与接入源码索引 |
测试、部署与尚未证明的结果
巡检已记录 Harness 与 tools 类型检查通过;最新 Worldbook 放置/观测 47 项、Langfuse 导出 19 项、Actor 拒答恢复 6 项、Compact 定向 109 项通过;世界书词法/选择 29 项和 Ruff 通过。这些是既有巡检结果,不冒充此次 Wiki 更新重跑。另一次旧 Compact 测试受 Node 24 与 stdout mock 限制,在 36 项后停止,保留该限制。真实模型的事实召回、费用、TTFT/P95、用户放弃率未验收。
Worldbook 曾有 c67852c 的成功 rollout/readiness/镜像一致性记录,其文件树与合入的 a2dad786 一致;08:42 当时尚未取得 fafdb8d 的新部署证据;14:40 巡检已确认其 10:59–11:02 生产部署成功,见本章最新记录。Harness a4f5bb83 的成功工作流只有镜像构建/推送,没有 apply、rollout 或 readiness,不能据此写成已接管生产流量。生产当前 digest、schema 和有效配置未直接核实;没有新部署证据也不抹去此前成功部署。
另须分开核实:Worldbook migration 006 是否执行;Staging 更换镜像的工作流是否同时落实新增 tenant/观测环境变量;Demo 所信任的 X-User-ID 是否由真实网关注入并受 ACL 保护。Origin/CORS 不是身份认证。上述是接入与发布证据缺口,未被本次巡检证明为线上故障。
Harness 当前固定版本[6] · Worldbook 当前固定版本[7]。此前章节和历史条目各保留自己的固定源码,不将本次增量同步称为全仓重新审完。
2026-09-21 14:11–14:22 巡检:新增 Compact 历史过滤候选
本次两仓 main 仍为 Harness fa41d220、Worldbook 9fd897e,没有新增主干能力。新增的是 Draft PR #196,固定 head 2dc1cbe8、base fa41d220,在既有 Compact 压缩前分类旧聊天;本文按该次已完成报告合并,没有另跑远端巡检或生产调用。
| 类型 | 本轮新增信息 | 更新到哪里 |
|---|---|---|
| 候选新增:摘要前筛历史 | Scenario 的 compact.jev 默认 off;shadow 只试算、apply 才可能省略高置信纯寒暄组。服务不可用、分类不确定或收益不足时保留原文或回退原规划。它不等于普通 V2 的 Jev 工具编排,也不是新 SDK 工具 |
第一章能力表 · 工具索引 · 记忆中的实际过程 · 上下文材料差异 |
| 候选边界:省略与覆盖不是同一件事 | 摘要输入可省略某组,但 checkpoint 仍标记完整原始区间已覆盖。隔离假模型强制误判后,关键承诺漏进摘要而覆盖范围继续前进;当前缺省略清单、生成后对账及自动重算/回滚,不能写成已解决长聊遗忘 | 保存与后续读取 · 候选状态与验收缺口 |
| 验证记录:工程通过,业务效果待验 | 巡检记录本地定向 54/54、远端 CI 1053 tests 通过;镜像已 build/push。没有 workload rollout、真实 Jev/摘要模型、费用净收益或长期事实召回验收证据 | 验证与部署分层 · 成本与观测 |
| 文档澄清:普通 V2 每轮做什么 | 第一章明确每个进入生成的逻辑轮启动分工模型;专家与 Director 并非每轮全跑,有有效变化才尝试保存。该调度规律没有被 #196 改动 | Agent 主干说明 · 普通后台与两种 Jev 的区别 |
完整分支目录补录 #196 的真实开发分支,保留历史目录原记录和各自时间;本次不是全量远端分支刷新。世界书没有本轮新增,原实现与待验范围不变。PR #196 · 候选设计与边界[8]。
2026-09-21:项目增量与工具索引
| 类型 | 项目更新或本次补审结果 | 对应正文 |
|---|---|---|
| 主干更新:世界书角色关联 | 服务保存 tenant+Prompt 的书籍关联;聊天每轮 check 会话、resolve 具体书版本,再 select。固定 revision、latest、清空关联分别生效;旧会话下一轮也可采用新关联。Demo 读取多书供浏览,未提供保存关联按钮 | 关联与保存 · Demo实际操作 |
| 主干更新:历史压缩 | 协议与策略归 Scenario;支持配置化 JSON/文本/顺序递归、结构或纯文本摘要、bounded_recent 规划及检查点超时只读确认。native 配置值单列,未推广成全局默认 | Compact完整过程 · 窗口衔接 |
| 主干新增:可选 Jev 编排 | 工具选择与参数补充分开;六专家与 Director 仍使用文本模型。代码已合入,仓内场景未启用;预算检查旁路、并列概率顺序和 trace 标签缺口同处标明 | Jev调用过程 · 限制 |
| 主干新增:SDK Slow gate | 宿主可在慢循环开始前决定是否跳过;跳过保留状态、不调用该循环模型/工具。普通 V2 尚未接这项策略点,已发布 SDK 0.3.0 不含增量 | gate输入与回执 |
| 补审失败边界 | Imagine 下游交接前失败可能留下 pending 图片位;Compact 丢锚点且短历史时,旧摘要可能先失效而未重建。两者为固定源码/离线核查,不是生产事故声明 | 图片失败 · 短窗口 |
| 候选补审 | Fusion 目标分支的 #185 分段指令未送入 Actor;#187 总开关即采正文;#192 图块结构和用户图片标记改造仍有姓名冲突边界。均未混入 main 能力 | 三项候选 |
| 部署与验证记录补充 | 世界书 9e4d897 有9/18生产 rollout 成功记录;该版本早于 Prompt 绑定 9fd897e。后者 CI 已使用 PostgreSQL+pgvector,仍不证明生产新表迁移、真实RPC或业务端到端完成 |
部署范围与接入条件 |
| 文档新增:按需求找工具 | 读取飞书一期/二期/三期及完整需求表;第一章按 Agent、Harness、Worldbook 加 24 行索引,覆盖全部25个不同需求点及额外现有入口。每行列类型、调用方式、产物、对应程度及原章定位 | 三类索引入口 |
| 文档阅读调整:合并项目入口 | 原“Roleplay 现状总览”与“Agent、Harness、Worldbook”合为第 01 页“Roleplay 项目全貌”。开头精简为一条运行链和四个同页入口;案例、接入条件、三类能力表与完整分支目录按需展开,工具索引及旧链接会打开并定位对应内容 | 项目全貌 |
**映射中的关键差异:**后台 Director 与“当轮排演工具”、人物分析与“独立 NPC 卡”、世界书检索与“聊天原文检索”、逐轮解析绑定与“剧情自动回写世界书”分别标注。动态 preset 的预选实现、Story 目标评分/改线条件、Imagine 既有素材投影也加入对应索引;不以术语相近认定需求已经完成。
本轮读取八份已完成巡检报告、飞书 KAS 需求List&优先级,并核对本地固定源码。没有新跑生产调用、刷新完整远端分支列表、发包或部署。112 条分支目录继续保留自己的历史日期;新增 PR 的状态和证据在上述原章记录,未伪造一个今天的全量分支快照。
2026-09-18 后续:执行方式与主干/分支位置逐项标明
第 1 章 Agent、Harness、Worldbook 三张表新增“代码位置(主干/开发分支)”列,逐项写明 roleplay-harness / main、worldbook-service / main 或具体开发分支。普通 V2 与 Pioneer 增强、Sumi 图文能力与观测部署候选分别标注,Fusion 与浏览器绑定页面保留各自候选位置。
名称列同时说明谁决定步骤:Story、Sumi 是代码编排工作流;普通 RP V2 由程序安排前后台、后台模型在受限两阶段内选工具;前台工具循环由控制模型选动作;工具包、协议适配和检索服务按各自调用机制说明。SDK 拆开列通用 Agent、独立慢路、快慢组合器与应用内固定 profile 工作流,避免将不同执行方式混为一项。Story/Sumi 对应正文和详情同步更新。
本次仍采用既有固定源码与分支证据,未刷新远端全集或生产状态;白底黑字、原资料、六专家说明和历史深链接保留。
2026-09-18 后续:标明能力类型,按主干整体与分支改动对照
第 1 章三组表统一说明“它是什么/main 已形成的能力/相关分支改动/当前阶段”。main 描述已合并代码的整体运行结果,分支描述研发的具体改动;已进入主干的能力归入 main 说明,分支栏保留开发与合并记录。线上启用继续按部署和配置证据分别标注。
Story 明确标为“剧情推进运行模式,内部调用六个世界/叙事工具”;RP Agent V2、Sumi、Pioneer、Fusion、前台工具组、SDK、世界书服务与适配代码均补上类型。世界书管理员匹配接口与浏览器绑定管理候选分为两行。第一章 Story 详情补组成和调用者,Story 正文章节逐项列出六个工具的触发、输入、输出与后续使用;区分剧情业务流程、工具和执行前后回调(hook)。
Agent 表下直接展示普通 V2 六类分析专家的名称、工具名、职责和产物例子,并写明 Orchestrator 分工、Director 整理、程序保存与后续读取的关系;Scene Director 与笔记 Director 分开定义。“状态”用实际剧情笔记内容说明。慢通道开头与普通 RP 详情同步使用这些明确定义。
能力表采用已核实的实现描述;旧 Story 分支与主干的完整差异尚未审完这一阅读范围留在源码展开项。此次重读本地固定源码,未刷新远端分支或生产配置;保留原始目录记录与旧链接。
2026-09-18 后续:白底黑字,Agent 主干与分支同表对照
Wiki 全文固定使用白底、深色正文,不再跟随系统自动切换深色。第 1 章 Agent 改为一张“业务方向/main 已有运行/分支新增或修改/目前状态”的表:Pioneer 的状态与图文增强放回 RP Agent V2 同一行,Story、Sumi、Fusion 及旧 Actor 工具记录分别对照;已合入内容与仍属候选的部分不靠读者跨段拼接。
Agent 的完整输入、执行、保存和后续使用说明移到该表紧邻的展开项,原深链接继续可用。Harness、Worldbook 分类和 112 条完整分支记录保留;本次只调整阅读结构与配色,没有刷新代码或部署结论。
2026-09-18 后续:以 Agent、Harness、Worldbook 三类阅读项目
第 1 章的混合概览拆成三组:Agent 放 RP Agent V2、Story、Sumi、图文候选及其专用改进;Harness 放通用 SDK、工具接口、Workflow 接入、观测与公共工程支持;Worldbook 放资料服务以及两个仓库中的世界书接线。每项分别写实现名称、业务作用和真实 Git 位置。
完整分支目录增加相同的三类标签及筛选。整仓主干、集成或跨层分支可有多个标签,但真实记录仍是 112 条;只凭名称的分类标作暂归类,不升级核查状态。原源码说明、历史时点、已知缺口和旧链接继续保留。本次是文档分类调整,没有新增扫描、代码能力或上线结论。
2026-09-18 后续:以真实 Git 分支建立项目目录
**第 1 章改为分支入口。**从真实分支及其业务变化认识项目,再下探运行过程;原有仓库归属、工具和应用边界保留在同章展开项。
| 类型 | 本次文档变化 | 证据范围 |
|---|---|---|
| 新增全分支历史目录 | 恢复 Harness 五页共 99 条、Worldbook 8 条完整列表;补录后来确认名称的 5 条 Harness 分支。提供名称/业务关键词搜索、PR 状态与核查材料筛选 | 是 2026-09-17 历史快照与后来记录的并集,共 112 个仓库+分支条目;不是今天实时全集。Harness 当晚已显示 109 条,晚间完整列表尚未恢复 |
| 升级具体实现说明 | 同章展开 main 中 RP Agent V2、Story、Pioneer、Fusion 和旧 Actor 工具分支:具体输入、运行、回复、保存时点、下一句使用与失败边界 | 各自用固定源码或原专项审计;Story 说明当前主干对应实现,未冒充旧分支 head 全量阅读 |
| 补全每条的业务作用与核查程度 | 76 条 Merged 分支逐条说明:4 条有历史 PR 正文、43 条核过主干对应源码、29 条仅名称;其他分支保留自己的审阅范围 | 核过主干对应源码不等于复原该支差异。文档、部署、修复和评测仍列在目录,不冒充独立聊天产品 |
| 修正分支状态的误读 | 明确 #78 虽仍 Open,主要能力已经 #108 入主线;#170 合入目标是 Fusion 分支;#177 与世界书 #9/#10 有主线变化证据,但完整旧分支名尚未恢复 | PR 标签、能力所在位置、部署和验收分别记录;没有推断分支名称相近就存在继承关系 |
| 维护阅读和交付 | 首页增加分支入口;现有章节编号、技术细节及旧深链接保留;增加可下载目录数据 | 独立 Agent V2/Tickle 说明未改动;本次不改产品代码、不部署、不调用模型 |
入口:第 1 章分支全貌 · 完整目录及筛选 · 覆盖与待核范围。当前远端读取受限,未把历史记录标作新一轮线上巡检。
2026-09-18 后续:补入正常聊天之外的产品操作与交付规则
这次沿接入、生成、交付、修改已有聊天的过程,检查文档缺失的业务判断,再核对固定代码。以下均为补充或修订现有实现的说明,不表示新功能开发、代码合并或上线。内容放回原章;首页取消单纯罗列窗口与资料问题的链接行,改用完整聊天过程连接交付与后续操作。
| 类型 | 对应位置 | 本次新增的信息 |
|---|---|---|
| 补充业务接入责任 | 第20章 | 服务调用凭据与最终用户身份、会话归属的区别;聊天业务在交请求前和收到结果后分别负责什么 |
| 补充正文的完整交付链 | 第4章、第9章 | 模型文字、正则、并行生成后处理与最终交付的顺序;完成事件整体替换预览,包括空字符串;处理前文字与展示改写稿可分别被记忆表和聊天消费。部分正文恢复注明准确适用路径 |
| 补充既有聊天的修改行为 | 第7章、第17章 | 改角色卡后 Actor/后台分别读什么;继续、重生成、编辑后生成怎样接收历史;普通后台不会因动作名称自动回滚,历史位置数字也不等于全文编辑指纹;与 Compact、Story、Sumi 区分 |
| 补充世界书参与长期使用的边界 | 第12章、第13章 | 角色、书与旧状态发生冲突时,已有结构/选择检查没有代替跨来源事实裁决;Demo 的切角色、新对话和清浏览器资料分别影响什么 |
| 修订工具保证的表述 | 第16章、第21章 | DIO 何时该调用属于模型选择政策,程序另查可用、重复及身份;图片数量的上限检查与最低交付要求分开,结束编排不代表图片交齐 |
| 更新整体阅读顺序中的衔接 | 首页及相应原章 | 从正常的一句输入延伸到改输入、换回复、改角色及重开;材料、调用、保存之外,加入交付采用与后续修改对已有记录的影响,保留原有窗口/资料入口 |
本轮采用上述固定两仓基线,未刷新远端分支、调用模型或验证生产。章节仍按现有目录连续编号,旧内容与深链接保留;独立 Agent V2/Tickle 说明未改动。
2026-09-18:章节按目录顺序连续编号
左侧目录从上到下改为 01–24;正文标题、Markdown 排列和当前章节引用同步更新,原有深链接仍指向相同内容。历史来源中明确标为“原第”的编号保留为当时编号。
2026-09-18 后续:全篇阅读链检查与开发状态分层
本轮按同一标准检查全部 24 章及折叠内容:谁决定、真实输入、执行过程、实际产物、保存时点、后续采用和失败分支。已有完整内容的地方增加准确入口;缺少或表述过度的地方在原章修订。源码基线不变,没有把文档补充算作新开发功能。
| 类型 | 对应位置 | 实际变化 |
|---|---|---|
| 新增开发状态标识 | 首页、全部 24 章 | 按能力分别标明主线接线、需业务装配、候选已读/待审和未成闭环;具体配置启用、包发布、测试部署及生产验收独立记录。每章可展开查看自身的判断依据与限制 |
| 修正混淆与缺失环节 | 请求、快慢通道、状态、Story | 在对应章节交代实际交接;可选世界书不再写成 Actor 默认必有;聊天正文与后台状态分开,状态不存在与读取失败分开;Story 的启用及提交失败后果就地说明 |
| 补充世界书的实物与控制点 | 第 10–13 章 | 条目 ID、书 ID、revision 与会话绑定的关系;选择结果哪些给模型、哪些给排查;服务与应用不同默认;实际配置由谁改、何时读取及生效;页面候选与当前只读范围分开 |
| 补充工具与结果采用边界 | 第 9、14–16、19、21 章 | 现成工具、模型菜单、宿主调用和调试入口分开定位;补实际调用/输出示例,复核记忆、图文、SDK 与新人物的保存、读取及失败条件 |
| 修正预算与观测口径 | 第 2、7、17、18、22 章 | 不将某条路径的完整输入检查推广到全仓;前移遥测默认关闭条件;区分实际模型请求数与 usage 汇总条数;案例与工程入口可直达窗口、解析、复核及保存细节 |
| 维护原有结构与证据 | 全篇、候选章节 | 保留 24 章结构、原有内容和源码深链接,不新增另一套 Wiki;#170、#172、#173 及旧候选保留自己的日期、目标分支和阅读深度 |
本轮依据既有固定源码与已完成巡检修订,未刷新远端 PR 状态、调用付费模型、修改业务代码或验证生产环境。未确认部署表示证据不足,不等于确认没有部署。
2026-09-18 后续:总览直接定位资料与上下文规则
| 类型 | 对应位置 | 本次改动 |
|---|---|---|
| 已有内容增加直达定位 | 总览、第 7、9 章 | 将“角色与已保存资料”展开成角色卡、聊天原文、普通持续状态、世界书、可选记忆与不同玩法状态;每项直接跳到具体段落。已有完整状态格式与 Compact 参数可以定位并展开 |
| 补充此前缺少的运行细节 | 第 7 章 | 逐次调用的输入示例;谁控制模型容量、历史条数、回复额度;参数覆盖优先级;无 Compact/普通后台/世界书/Compact 的不同处理;各后台、Story、Sumi 和 SDK 的独立窗口边界 |
| 同章衔接 | 第 9、18 章 | 记忆压缩与额度说明链接回统一的上下文规则,不新增第二份窗口说明;已核世界书界面没有窗口设置按钮,配置可改与界面是否开放分开记录 |
这次是固定源码说明与阅读定位的更新,没有修改业务参数、调用模型或刷新生产版本。
本次实际改了哪些内容
| 类型 | 对应正文 | 实际补入的信息 |
|---|---|---|
| 补充现有行为 | 第 9 章:记忆 | Compact 每轮如何读旧摘要;模型/Prompt/配置变化怎样影响复用;旧消息滑出窗口后无法完整核验编辑的条件;两种输出格式适配;过滤、截断、临时采用与持久保存的区别 |
| 补充现有行为 | 第 13 章:世界书页面 | Demo 的用户标识从请求头取得;固定书白名单与用户认证各负责什么;用户消息已存、后续失败时,历史可能留下提问而没有完整回复 |
| 补充接口与运行过程 | 第 14 章:能力入口、第 21 章:快捷回复 | 普通建议回复等待对应消息的后台建议,Story 重读正式正文;各自输入、三条选项、等待/重试/计量/失败条件;Tool Debug 增补健康接口与 1 MiB JSON 请求限制。AutoReply 来自 9 月 18 日跨日补审,不是昨天新开发的功能 |
| 新增候选记录 | 第 24 章:候选分支 | #170 Aoi/Yuzu 入口与计费标记区别;#172 浏览器世界书绑定提案;#173 Sumi 测试环境观测工作流。逐项标记已读代码、仅有提案、作者部署记录和验收缺口 |
| 补齐发布与部署证据 | 本章下方对账记录 | SDK 0.3.0 的准确发布来源;Tool Debug 从两项扩为十项;#167 撤回早期默认模型修改;构建推送和维护者另行记录的 staging 部署分开列出 |
| 已覆盖,核对后保留 | 世界书第 10–13 章、Sumi 第 16 章、SDK 第 19 章 | 世界书八类位置与标准场景三类、默认关闭向量及启用后的 Qwen 配置、管理接口;Sumi #171 归档及更晚 #176/#177;已发布 SDK 和显式观测。原章节已有这些信息,不再重复新增一份能力说明 |
这里的“补充现有行为”是文档信息补全;“新增候选记录”是本次开始记录这些候选,不表示它们刚刚合并或上线。本轮未重新运行巡检任务、执行产品测试、调用生成服务或部署。
9 月 17 日四次巡检:发现、时间变化和正文落点
| 报告时间(北京时间) | 当时观察到的变化 | 本次怎样处理 |
|---|---|---|
01:40 · main 2b7c98c |
SDK 0.3.0 发布成功,来源 bd6f726;Tool Debug 首版目录六顾问,但当时只有两项可执行;#167 当时仍 Draft |
SDK 发布事实保留在第 19 章。两项执行限制和 Draft 状态属于早期时间点,后续已变化,不能覆盖现在的十项能力 |
07:36 · main c568725 |
#167 最终合并为 ac34b53,中间提交 2677f54 撤销早期默认模型变更,保留原 Gemini 默认和 DeepSeek allowlist;#169 调试入口扩为十项 |
第 14、21 章保留六顾问、Director、JSON 读写、图片的完整十项清单;补接口细节。本次将发布、构建与作者部署记录对齐;不再把 #167 当作未解决 Draft |
| 13:34 · 未取得新的远端 SHA | 补读历史 bf934d0 的 Compact 实现:复用指纹、窗口覆盖、压缩选择、预算与保存;远端读取受阻 |
第 9 章按当前相同路径重新核实后补充。标题的 c568725 是此前观察游标,不能当成这次新审完的源码基线,更不能从访问受阻推断仓库没变化 |
19:40 · main 6c50dbc |
相对 c568725 为 7 提交、39 个变化文件;#168 世界书位置与 #171 Sumi 归档已合入;新增 #170/#172/#173 候选信息。属于部分审阅,未审完全部 39 文件 |
位置与归档已在第 10–14、16 章覆盖;第 24 章新增候选及各自证据范围。原报告未读部分仍是待核范围,不能写成实现不存在或已经全部验收 |
后续 Wiki 定向核对已到 Harness 3b99f4c、Worldbook 9edea52。因此第 16 章仍保留晚于 19:40 巡检的 #176 图片生命周期事件、#177 图库正文快照;世界书服务新版配置和管理接口也保留。它们来自后续核查,不冒充 19:40 报告已经审过的内容。
SDK 0.3.0 发布 · 发布源提交 · 成功发布任务 · #167 最终变更 · Tool Debug 扩展 #169 · 19:40 固定比较范围 · Wiki 后续主线差异
有部署记录的部分:谁提供证据,证明到哪一步
| 对象 | 已有证据 | 本次保留的准确结论 |
|---|---|---|
| SDK 0.3.0 | Release/Package、来源 bd6f726、发布任务成功 |
已发布;之后合入的世界书位置 helper 不因此属于这次旧发布物。业务消费者是否升级另看安装与接线 |
Tool Debug c568725 |
Actions 35137564114 证明 build/push;#169 作者另记录 staging rollout、Pod imageID、十项实跑和一张 SFW 图片 |
有维护者测试环境验收记录。巡检没有独立读回当前集群版本,不能只写“绝无部署证据”,也不能写“已核实当前生产可用” |
融合图文 #170 de0ea87 |
作者 9 月 17 日约 16:30 记录 rollout、健康检查和精确版本;未授权请求 401 | 有该候选的 staging 部署记录;带鉴权的五入口功能验收仍未完成,目标是融合分支而非 main |
| Sumi #171/#173 | #171 已合入的归档调用链;#173 当时仍是部署观测工作流候选 | 不代替外部接口发布、真实图库记录或当前观测开关证明 |
| 世界书服务 | 较早 267b9ea 人工恢复 Ready;后续 bf934d0 自动更新在 apply 前因 RBAC 停止 |
后次失败不抹掉较早就绪记录;两者也都不证明此刻服务版本。与 Tool Debug 是不同工作负载 |
Tool Debug 作者记录的镜像 digest 为 sha256:cfd106e1e3516aedb2a523eac3e4e49adb083a54ee883cc7c23dfac2bb22bbdf;#170 的固定 digest 与验收范围列在第 24 章。Tool Debug 构建任务 · 维护者部署记录所在 PR
9 月 18 日跨日补审及六份原报告的对应关系
- **01:35:Compact 旧测试阅读补齐。**阅读的是
bf934d0的测试剩余区间,补入 profile、过滤与完整 length 回包、采用/保存区别。当前测试另有后来新增内容,不能把历史测试读完写成当前 main 全部测试已审,更没有运行测试。 - **07:34:AutoReply 历史源码补审。**两份实现、两份测试的文件哈希,与 Wiki 本地
13c481b副本完全相同;这些文件不在13c481b → 3b99f4c的七文件差异中。本次还核对当前 dispatch 调用条件,才补入第 21 章。没有取得新的远端 main,不能称 9 月 18 日新增了 AutoReply。
本次读取的原报告如下;回传同一份报告的通知不另算一次巡检:
KAS-2026-09-17-0140-2b7c98c-SDK03与工具预览增量.mdKAS-2026-09-17-0736-c568725-工具预览十项与部署证据.mdKAS-2026-09-17-1334-c568725-Compact补审与远端阻塞.mdKAS-2026-09-17-1940-6c50dbc-世界书位置与Sumi归档部分审阅.mdKAS-2026-09-18-0135-6c50dbc-Compact测试补审与锁屏阻塞.mdKAS-2026-09-18-0734-6c50dbc-AutoReply历史补审与远端阻塞.md
固定源码与具体行号随对应章节提供;本章记录证据日期和文档去向,不重建另一份业务说明。
2026-09-17 本轮:重新核对两仓 main,按完整业务链更新
**本轮源码基线:Harness 3b99f4c、Worldbook Service 9edea52。**Harness 相对前版 13c481b 的完整差异为 7 个 Sumi 文件;SDK、工具、普通 RP、记忆、Story 和世界书接线沿未变化源码向下追读。世界书另核对新版配置、管理 API 与索引迁移。以下是本轮实际回填,不代表生产已经升级。
| 内容 | 本轮增加/更新的实际信息 | 所在位置 |
|---|---|---|
| 项目全貌 | 四种接入入口默认提供什么;十种业务目的、现有实现、实际产物、接入条件;未完成的跨模块组合 | 总览、第 1、3 章 |
| 默认与动态装载 | 服务启动、单次请求、准备输入、模型循环四个时点;固定配置、资料选择、显式工具注册的区别 | 第 3、14、19 章 |
| 主 Agent 提示词 | 每个入口 system、用户材料、工具菜单的真实来源;前台首步只有控制Prompt+本句,普通后台模板由外部PromptManager提供 | 第 7、19 章 |
| 跨模块记忆 | 保存时间线;回读的实际对象/文字;变量怎样进入模板与模型;各记录的成功凭据、失败与下一轮采用;新增冻结记忆试跑入口 | 第 9 章,相关说法同步到第 7、14、21 章 |
| 工具与业务组合 | 逐入口列实际名单;全部可复用封装;Story六类输入输出;调试目录与生产菜单;陌生人出场只是组合案例 | 第 14、15、19、21 章 |
| Sumi 新 main | 图片完成结果先存;图片历史/图库独立归档;生成时正文快照;开始与完成通知;失败和不确定写入的边界 | 第 9、14、16 章 |
| 世界书新 main | 默认向量后端仍关闭;启用后默认远程Qwen嵌入;显式启动迁移;指定tenant的admin导入/建索引 | 第 9、10、13 章 |
本轮核查覆盖源码和文档结构,没有发起真实模型、生图、生产写入或部署验证。外部 PromptManager 的岗位完整原文、外部服务内部算法与数据库、运行环境是否启用对应能力仍需各自证据;本文明确标在消费它们的位置。
Harness 完整差异 · Sumi 图片归档[9] · 世界书管理 API[10] · 世界书配置[11]
2026-09-17 较早修订:项目范围与内容归属调整
**范围纠正:**本 Wiki 说明 roleplay-harness 与 worldbook-service 两个仓库。某个模型型号或部署方案只是一种配置实例,不再作为整个项目记忆能力的边界。
**新增内容:**第 9 章补入 JSON 记忆工具、Story 世界/叙事快照、Sumi 逐消息状态、Visual World 图像连续性资料和长期角色指令的保存与后续使用;补入世界书版本、会话绑定、单轮选择/诊断与聊天记录的独立边界。世界书条件实际输入与跨轮计时不支持的事实同时补到第 11 章,诊断本地保存范围补到第 13 章。
**结构更新(以下为当时编号):**第 1 章改为两仓职责与可选运行方式;原第 1、2、19、24 章重复的对话流程合并为第 19 章规范案例,具体条件、参数与源引用保留。第 2、24 章分别提供请求协议和执行机制定位。第 14、21 章分为业务能力目录与准确调用合同。导航改按主题查阅,候选实现与巡检记录单列。
本次重读资料相关执行路径及世界书固定版本实现,没有新跑四次巡检、升级运行配置或验证生产结果。下面是此前各次核查的记录,保留其时间和版本语境。
2026-09-16 巡检及较早文档修订记录
**下面保留较早巡检与文档修订的时间记录。**这些记录采用当时的 Harness 13c481b、世界书 b0af622 等基线;本轮更新以顶部新基线为准。候选PR状态仍是记录当时所见,不能当作当前线上版本公告。
哪些新增能力值得产品关注
| 已有更新 | 在具体业务中意味着什么 | 接入时还要确认什么 |
|---|---|---|
| 世界书增加位置装配与管理匹配调试 | 可以先试“递钥匙”会选哪些原文,并支持更多资料放置方式 | 当前模板实际开放哪些位置;新书版本是否已绑定到会话;代码支持八类不等于八类已全开 |
| 普通后台和工具执行观测 | 可以分开追踪正文生成、人物检查、状态整理与保存 | 采集是否开启、记录是否存在;工具跑完不能当状态存好 |
| 十项 Core Tools 可独立调试 | 开发者可用一份测试材料单独检查人物、记忆、剧情或图片能力 | 测试入口不是在线角色每轮的新菜单;图片可能真实调用外部服务 |
| Sumi 图片并发和顺序交付 | 图片可同时生成,用户仍按正文顺序收到相应结果 | 该业务是否走 Sumi;不能套用到所有图片调用或候选链 |
| SDK 发布与调用观测增量 | 接入方有已发布的通用能力可选 | 实际安装版本、主线新增但未包含在包内的改动、业务有没有主动接入 |
这些信息已放回对应正文:世界书在第 10–13 章,工具在第 14、21 章,图文在第 16 章,成本观测在第 18 章,SDK 接入在第 19 章。本章用于对账;理解业务不需要先读巡检时间线。
哪些判断没有因此改变
普通后台仍从本轮准备阶段的材料分析,世界书原文仍没有自动复制给同轮后台;“有新观测”不会使后台突然读到当前正在生成的正文。发布了 SDK,也不会让日记、表格、Story、世界书和图片自动组合为一条万能流程。
候选 Pioneer 的消息分支状态、图文消息格式和历史重绘保图修复,需要按各自提交阅读。它们没有统一证明 main 已具备同样行为,也没有新增“自动把每个陌生人物创建为完整可编辑小卡”的闭环。
怎样把更新用到产品判断里
以“希望新角色先出场,稍后补全”为例:当前能依据的是回复继续、后台按材料做人物分析并可能更新会话状态。要承诺独立人物小卡,还需人物实体结构、保存和后续读取接线;不能因为日志里出现 NPC 专家就说小卡已建好。
判断一项变更可否对用户承诺,应分别确认:代码在哪个版本、目标业务是否接线、运行配置是否开启、实际结果是否验证。 构建镜像成功或测试报告通过,各只能证明各自步骤。下面保留四份报告、对应章节和固定提交,便于逐条核查。
逐项变更、原始巡检与固定分支证据
以下为此前固定版本核查的详细记录;其中“本次”“昨天”指该记录形成时,不代表本轮重新巡检或部署。
之前只同步了部分结果,确实存在“更新记录提到了,原章节仍没改”的遗漏。 本次找到 9 月 16 日四次巡检的原任务与报告,逐项回填对应章节;同时用 9 月 17 日已取得的固定源码修正过期说法。下面分开列历史发现与今天采用的结论。
昨天四次巡检,分别更新到了哪里
四个任务的原名都为《KAS 仓库每六小时深度巡检》,是同一巡检计划的四次独立运行。下表均为北京时间,使用报告开始时间,各任务完成时间另列。
| 9 月 16 日报告 | 当时主要发现 | 本次回填的对应章节 |
|---|---|---|
01:36;main bf934d0 |
候选增加状态/Actor 观测;正文保存、状态 CAS、消息挂接仍是不同步骤。平行候选 e3b57e6 修复重绘失败保留旧审核通过图。镜像构建推送不等于服务已替换 |
第 6、17、18、24 章:状态生效、分步保存与观测边界;重绘保旧图按历史分支标明;保留构建与部署区别 |
07:39;main bf934d0 |
候选修复 Actor 失败时的回复额度与原错误保留;原始上游错误仍可能经后台 runner 写入 stdout。定向 14 项测试与类型检查通过 | 第 17、18、24 章:回复额度与供应商账单分开;补具体日志路径,未把定向测试当作生产验收 |
13:42;main c4a7b9a |
Core 贡献审批及 MCP 依赖更新;SDK 0.2.2 已发包但发布后校验失败;八组 fake SDK 示例已编译执行,当时尚未合并;候选 AOI 解析/失败隔离改进 | 第 19 章:接入与贡献规则、示例证明范围、发布历程;第 14、24 章:候选图文工具链。今天版本已另更新 |
19:40;main 77a1537 |
#156 示例、#158 消费者校验修复、#161 Emochi 可选观测已合并。独立 registry 校验成功,旧发布任务仍失败。Pi 观测 #160 当时未合并 | 第 18、19 章:保留前台/后台独立记录、默认关闭、用量与提交结果区分;改掉“schema 尚未发布”等过期结论 |
已阅读四份原报告并核对原任务。本次读到报告中的测试通过,不等于重新执行了这些业务测试。昨日 main · 中午 main · 晚间 main
四份原报告名称,供与巡检任务对账
KAS-2026-09-16-0136-bf934d0-PR147可观测性与镜像构建分层.md;任务最后完成 02:01:53。KAS-2026-09-16-0739-bf934d0-平行分支预算修复与日志泄露.md;最后完成 07:50:49。KAS-2026-09-16-1342-c4a7b9a-SDK安全补丁已发但发布闭环失败.md;最后完成 13:54:52。KAS-2026-09-16-1940-77a1537-遥测接线与发布复核.md;最后完成 19:48:10。
已区分巡检执行任务与接收巡检回传的常驻任务,没有把回传入口再当成第五次巡检。
今天的新信息,已直接补回业务章节
| 新信息或修正 | 读者现在应怎样理解 | 已更新位置 |
|---|---|---|
| 世界书八位置、宿主能力协商、管理匹配调试 | 支持八类,不等于当前模板八类全开;默认场景仍是原三类。旧书须按新 revision 和会话绑定生效 | 第 10–13 章:格式导入、选条目、上下文图、页面控制;第 7 章 同步输入边界 |
| 新增 Harness 调度说明 | 从业务场景配置、两份上下文、LLM 工具调用,走到工具执行、条件复核与程序保存;区分两阶段调度和通用 ReAct 循环 | 第 22 章:独立业务模块与流程图;第 7 章 增加直接入口 |
| 快路/慢路的产物与使用 | 快路交正文;专家给建议;Director 给完整候选;有效保存后,未来准备请求才把状态投影装回模型 | 第 4–6 章:同一轮铜钥匙例子,展示步骤、结果、保存与再使用;解释下一轮太快及保存失败 |
| Core Tools 独立调试 | 十项能力可 prepare / execute / cancel;状态、记忆在隔离内存试跑,图片可能真实调用外部服务。不是在线 RP 菜单扩为十项 | 第 14、21 章:工具、入口、输入输出、例子及保存边界 |
| Sumi 图片并发与顺序交付 | 正文不等图;并发生成后仍按正文图序逐张保存通知,每次检查消息及租约 | 第 16 章:生成与交付顺序分开,区别于 AOI 候选 |
| Actor 用量、原生 Pi 观测 | Actor 记上游实际用量,没有就保留 missing;Pi 提供显式包装入口,仍由业务接入 | 第 18、19 章:修旧表、补接法,不当作统一财务账单 |
| SDK 0.3.0 已发布 | schema v1、Pi 观测已随此版发布;之后 main 的 placement 增量不能自动算进已发布包 | 第 19 章:发布版本、源码增量、业务是否升级分开 |
Pioneer 61039e5、格式候选 44ffcf1 |
已有图文与消息分支工具,仍没有自动创建并发布完整 NPC 卡;原生单图重试等未闭合 | 第 14、24 章:分支分别列出;第 5、6、17、18 章 就地提示影响 |
| Compact 补审精度修正 | 本轮可用临时摘要不等于已确认持久化;历史编辑检测受覆盖边界可见性限制 | 第 9 章:来自 9 月 17 日 13:34 额外报告及本次源码复核,不算昨天四次的新功能 |
依据:Harness 固定 main 13c481b · Worldbook 固定 main b0af622 · 位置接入 #168 · Sumi 交付 #162 · SDK 0.3.0 发布。具体代码证据随各业务章节提供。
哪些结论保持不变,哪些不能据此承诺
普通 Agentic 没有全局“累积 X 轮才开慢系统”的开关;Actor 与 Planner 使用轮初材料并行执行。世界书原文进入当前 Actor,不自动复制给同轮 Planner 或知识专家。Story、日记、Compact、Sumi 各有生命周期,新日志和新 SDK 版本没有把它们合成一条万能链路。
已发布 SDK、已合并代码、已部署服务、业务配置已启用、真实聊天已验证,仍是不同事实。旧世界书服务曾有 267b9ea 人工恢复 Ready 的巡检证据;后续 bf934d0 自动更新在 apply 前受权限阻碍,不能倒推服务从未部署。本次没有独立核实当前运行的服务 SHA。
发布历史与覆盖范围,供技术对齐
SDK 0.2.2 的历史是“包已发布,但发布后消费者校验失败”;#158 随后修正可选 OpenTelemetry peers 的校验矛盾,另一次 registry 验证成功,旧失败任务仍是历史失败。9 月 17 日巡检已核验 SDK 0.3.0 的新发布任务成功,本次沿用该证据并核对 changelog,没有重新发包或重跑 registry 测试。旧发布任务 · 后续独立校验 · 0.3.0 成功任务
13:42 提到的 MCP SDK 1.26.0 是依赖安全更新,不是本次确认业务曾触发漏洞。Core 的非作者审批要求是代码贡献治理,不是玩家调工具要人工批准。SDK 变更记录[12] · 贡献规则[13]
本轮对账四份历史报告,定向复核相关源码、配置、契约和测试断言,没有把分支全部历史或两个仓库每一行重新审计。正文保留与结论一致的固定链接,未改动处沿用先前基线。没有调用付费模型、生图、导入业务世界书、部署服务或修改生产数据。
24. 候选分支:新增能力、接入改造与验证状态
本次更新这里区分已合主干、已发布、指定版本已部署、只进实验分支和仍开放的改动。截至 2026-10-19 14:51,Harness main f9b26a9,Worldbook main ad38dce。#296/#301/#300/#302/#289/#304 六项已合主线;Sumi 10/19 有实际生产镜像更新与 rollout 证据,Worldbook 保留 10/09 历史证据。SDK Latest 仍 0.6.0,Core Tools 0.2.3 为前次已核基线。下方旧标题和旧分支保留历史定位,当前状态按各行的核验日期读。
本次更新主线与开发分支:Fusion、监控、DIO 与摘要检查
本次更新10/19 补核:下面 #296、#289 已改为主线已合;新增 #303、#305。Fusion 三层分支沿用 10/13 已读记录,本轮未重新核 head、部署或逻辑。
| 候选与位置 | 现在准备做什么 | 合入、接入与部署状态 |
|---|---|---|
Fusion #255,e8b003c,目标 fusion-harness |
Actor 写一段后再决定下一步;正常完成显式选择 over。另补 Narrative JWT 直连和已保存图片槽通过 Image Tool 重绘 |
Open,未合入目标分支,也非 main。当前 head 的 staging 任务只有镜像构建推送,实际部署步骤 skipped;不能按整项 success 写成已部署 |
Fusion #292,bedc628,目标 #255 开发分支 |
图片 Hook 已负责判断插图时,清理 RP Planner 中重复指挥生图的提示 | Draft,未合;显式要求逐段配图、无 Hook 或自定义提示时条件不同,不能说 RP 一律不再安排图片 |
Rian #293,81d17ff,目标 #292 开发分支 |
用角色识别、镜头设计和编译过程,生成一张分镜图 | Draft,未合;已有 callable tool 和测试源码,未发现服务/Planner/Pi 实际注册入口,保存、扣费和通知仍由接入方承担 |
本次更新监控 #296,已合 ac43719,当前源码 f9b26a9 |
导出 HTTP/RPC 与 Sumi 历史、预算、图片交付指标;按真实业务失败分类 | 10/13 19:32 已合 main,包含在 Sumi 10/19 部署镜像;Prometheus 抓取和看板样本未验,不含 #297 的逐 provider attempt 方案 |
本次更新监控 #297,10/13 已核 6cceff5 |
另做应用操作、实际模型请求尝试和 Grafana 看板 | 10/19 列表仍开放,更新时间早于上次基线;本轮未重新核 head。与已合 #296 有重叠,不能直接算成同套能力 |
GroupChat #261/#262,bdf04c9 |
挑发言者、生成发言、记录真正采用的发言及状态 | 只合入 group-chat-spike;不是普通 RP V2 的默认群聊能力 |
本次更新Sumi #289,已合 8c072e5 |
为初始化增加父 span、参考图、缓存/校验/保存阶段记录 | 10/19 12:52 已合 main,包含在 13:26 Sumi 生产部署镜像;实际 trace 仍取决于配置和采样 |
| 本次新增依赖与发布候选 | 新 #299 升级 MCP SDK;Worldbook #15 调整滚动发布、#19 升级 urllib3 | #299 本轮仅核列表标题/开放状态,未审 patch;Worldbook 两项仍开放但未重核 head。Harness #283–#286 只沿用前次历史,不声称本轮重新确认 |
本次新增DIO #303,111b912 |
完整回复后由 Jev 判断长期要求,DIO 生成会话专属角色正文,后续轮采用 | Draft 未合;固定 head 有 CI/批准,staging job 仅 build/push,无实际部署。输入、生效及外部依赖 |
本次新增Compact 审计 #305,8d66caa |
检查摘要遗漏/矛盾/无依据事实,repair 模式最多重做一次 | Open、Changes requested、未合、无部署;作者复核 0 pass,未证明质量收益。条件与失败 |
本次更新这三项图文候选的叠加顺序是 #255 → #292 → #293,不是三项可直接接到 main 的独立功能。监控 #296 已合,#297 仍是有重叠的另一候选;实际观察口径在原观测章节展开。
Fusion #255:先看实际写出的正文,再决定继续还是结束
程序将用户原请求、已生成 Actor 片段和工具回执交给规划器。当前 Jev 动作是 actor、可用图片工具、可用 DIO 和 over;Actor 每写完一段就回到规划器,至少有一段正文后才接受 over,结束时不再多调一次 Actor。旧 finishResponse 已拒绝。预算耗尽、步数上限或失败仍能终止,所以并非每个终态都保证调用过 over。
各段共享本轮 ModelConfig 的输出额度,缺省 2048,而非每段各有一份全额预算。最多 12 次规划决定;提供 DIO 回调时为 13 次。非法规划回执有一次纠正机会,已有正文时部分可恢复错误可保留正文;首段失败、取消另有处理。没有正文且额度允许时存在直接 Actor 兜底。
通用循环新增了逐段 instruction:首段临时加入指令,续段同时带已有正文和本幕要求,不把上一幕临时指令变成永久故事历史。**当前 Jev adapter 仍只生成 generateImageAfter,没有生成这个 instruction。**因此本分支能确认“按实际正文决定下一动作”,不能据字段存在宣称“Jev 已给每幕发送因果导演指令”。
DIO 继续用于后台改写后续角色设定;accepted 后本轮照常回复,后续再读取任务完成后的有效提示词。成功受理后程序拒绝重复提交;失败后代码仍允许再次调度,而 Jev 提示词要求调用过就不再选。因此“最多一次”不是包括所有失败的新增硬计数限制,相关提示在 10/09 基线已经存在。
动作及 Jev 实际参数[1] · 循环、预算与出口[2]。
Narrative 身份、保存图片槽重绘与实际部署证据
NARRATIVE_AUTH_MODE 默认仍为 gateway。显式改为 jwt 时须配置公钥,使用校验后的 Bearer 用户身份而非传来的 x-user-id;提供 Origin 时还校验允许来源。它没有因为复用 Pioneer 鉴权函数就新增会员周期要求。配置存在也不证明当前运行环境启用。
已保存图片槽的手工/重绘可以使用已配置 Image Tool:按 messageId + imageIndex + requestId 认领持久 attempt,保留旧图并标 pending,从原图片槽读取段落锚,再调图工具,外层不重复扣款。成功仅替换仍属于当前 attempt 的槽;失败保留原已审核图片并发错误通知。同请求完成结果可重放;提交结果 unknown 时不盲目重提。外部工具的账务和审核实现仍需单独核验。
#255 head 对应 run 37924857151 的 job 虽显示 success,但 kubectl、EKS 认证、Deploy narrative-fusion 都 skipped,只有构建推送镜像执行。Fusion 旧 c8fc61c 仍有 9/24 的生产部署历史,新候选不能据此算已运行。
JWT 接线[3] · 认领、重绘和保留旧图[4] · 只有构建的工作流步骤。
#292:图片 Hook 已负责配图时,避免两套提示同时指挥
未明确要求“每段都配图”,并且已有 createImageToolPreHook、scheduleImage、图片额度不为零时,程序把 Planner 的 generate_image、generateImageAfter 等默认图片说明移开,Actor schema 仅暴露 instruction。Actor 写出正文后,图片 Hook 仍会判断、安排图片,原额度和交付限制保持;它没有关闭插图。
明确要求逐段配图、没有 Hook 或调度能力时,仍保留 Planner 图片合同。接入方自定义 plannerPrompt 会原样保留,不自动清洗其中的旧指令;不能承诺所有提示词都已去重。实际启用条件[5]。
#293:Rian 分镜工具怎样接,哪些工作仍需业务完成
接入方创建 createRianImageTool,取得工具 generate_storyboard_image。它接收当前正文段、v3 状态或 null、bot/user 名字、本轮用户输入、画风锚点与随机种子;可附此前正文、前轮回复、当前轮已抽人物和已有镜头。宿主另供角色识别/镜头设计两套 ModelConfig、模型 runtime、图片生成 transport 与图模型 configRef。工具不自行拉会话状态,也不把旧格式自动升级为 v3。
一次调用先确定人物与场景,再设计主体、景别和视角,参考最近镜头减少重复构图;随后编译绘图提示和参考图,最后只提交一张图。返回 taskId、图片列表及 storyboard;仅审核 COMPLETED + SFW + blocked=false 时公开图片,否则 images=[]。模型提取失败可以退规则或纯场景方案,不等于任意输入都成功。
模型次数、参考图、返回与保存责任
输入最多 1 MiB,正文不能为空,状态须为 v3 或 null,seed 必须有效。角色识别 T1 最多两次、每次 15 秒;镜头设计 T2 最多两次、每次 25 秒,并可等待宿主 beforeT2 后读取 getPriorShots。相似镜头只尝试改变相邻景别,不保证每张完全不同。最多两个前/中景人物参考槽,按 bot → user → story 优先,绑定当前图片版本;缺图或满槽仍可保留文字描述。当前默认 16:9、1392×768,count=1、steps=4、true_cfg_scale/guidance_scale=1。
工具不保存会话/镜头状态,不扣费、不发 WebSocket,也不生成 loading 占位。replay:'never' 不提供跨调用的持久防重;同一次 execute 不自动重试付费生成,不代表业务重发两次永不重复扣费。取消 signal 要由底层模型和图服务共同遵守,阶段超时不是无条件硬截止。代码中有实现、测试和文档,未发现现有服务、Fusion loop 或 Pi 的实际注册调用;产品接入仍待完成。
上述候选依据 10/12–10/13 已完成的固定源码增量审阅。测试源码被读取,不代表本次亲自运行;#293 的移植辅助文件、底层编译器和全部调用方未被全仓逐行审查。
9/24 原有记录:合入去向与仍待接入的改动
| 候选与固定版本 | 研发在改什么 | 当前状态与业务边界 |
|---|---|---|
| Harness #205 | 本地加权UTF-8估算分类输入、可选助手段落V2 | 已合main,不再是待合候选;V2仍需显式配置、默认关闭。有限186请求未低估不构成严格上界,长聊语义和真实成本仍待验 |
Harness #209 · Fusion c75dabb9 |
同一助手消息追加Actor段落时保留关联后台状态 | 已合 fusion-harness、未合 main;后续 c8fc61c 包含这项修复,已有 9/24 03:16–03:19 production rollout 事件。编辑/重生成必须换message ID的外部合同仍需验证 |
Worldbook #15 · be19065b |
将生产部署清单从 Recreate 改为 RollingUpdate,保留旧实例直到新实例 Ready | Open、checks 成功;maxSurge:1、maxUnavailable:0、minReadySeconds:10。当前 Ready 只证明数据库和表可用,向量 reset pending/failed 不一定阻止 Ready;新实例就绪不等于语义检索已经准备好 |
Harness #210 · d7c054fb |
澄清 POV、世界书服务和 SDK 的职责及接线 | 12 个文档文件,无代码、API、配置或部署变化;不计作产品新增功能 |
**#209 的具体例子:**同一条助手消息先写“守卫走近”,再追加“接过钥匙”,原快照的正文 hash 会变化;Fusion已合入实现取消快照对整段助手正文 hash 的绑定,保留消息 ID、场景、状态引用、用户锚点和版本检查。读取时仍核对数据库里的正文与当前可见正文一致。可是,如果另一个客户端在同一 ID 下把正文直接替换为“守卫拒绝接钥匙”,旧后台状态仍可能通过这些检查。因此需要跨客户端验证编辑/重生成产生新 ID,或提供能区分追加与替换的版本规则;不是只看这个 PR 的定向测试通过。
候选读取检查[9] · 保存及消息 ID 前提[10] · 滚动策略候选[11] · 当前 readiness[12]
PR #205 已合入 main;其先前审读的 9cd88b1f 及当前主干中,程序用本地估算决定分类请求能否装进预算。如果估算低于实际长度,请求仍可能被供应商按输入超限拒绝,增加一次失败请求及回退处理的等待。分类请求失败时,程序会放弃本次筛选结果,保留这次送筛选的完整原文交给后续压缩;用户取消则沿取消流程结束。估算的边界[13] · 对话组分类失败处理[14] · 段落分类失败处理[15]
前次只登记的#211已合main,已核其开发者Compact回放CLI要求legacy URL覆盖参数必须伴随cumulative URL;它不改聊天接口开关;#212合入Fusion,不是main,main的中断续写由#214/#216/#220及后续#230/#233形成。#205新组合也已完成后续核查并合入,不能继续列为post-pin待审。#236在owner接受常开原始输入日志的边界后已合main; #237/#239 已合 main,#240 的根追踪改动仍在独立分支,Sumi 对应现状见下文。历史#201/#202没有在这三轮完成新的代码复核,继续保留原范围。
Fusion:先交正文、隔离图片失败,并为慢模型安排一次对冲
这组实现位于 fusion-harness,不是通用main。Narrative的增量流在执行前启动20秒正文idle计时,只有 actor_text 重置;Planner一直工作也不能延后期限。超时或长时间没有正文时程序取消请求并发错误;只有receipt仍为 generating/reserved 才自动回滚,其他提交结果不明时保留对账边界。正文完成立即清计时器并关闭文字流,再处理图片提示。图片准备或工具失败时已完成正文保留,待处理图片标为失败并尽力通知,不再把文本一起拖回失败。计时与正文结束[16] · 图片失败隔离[17] · 有限回滚[18]
Fusion的 agentic-v2-luna 配置 hedgeDelayMs=5000。首次主尝试还没给出合格结果时,程序可在5秒后并发DeepSeek;可恢复的主请求错误也可触发备用,不可恢复错误不盲目等待。Actor的赢家必须通过后缀保护和预览过滤形成可见正文,即时流可在首段可见正文时获胜,缓冲路径等待流完成。赢家确定后取消另一请求,整轮取消同时传给双方;双方失败则终止。此处的5秒是该配置值,不是所有模型的默认。
当前tracing与回传usage只消费赢家stream,败方在取消前已消耗的provider tokens和cost没有闭合。因此“回传只用了一次模型额度”不证明只付过一次费用;20秒watchdog是否会误杀较慢Planner,也需要真实TTFT分布。对冲状态机[19] · Actor可见结果获胜[20] · 实际5秒配置[21]
Fusion 当前最新直接部署记录是 9/24 03:16–03:19 CST 的 c8fc61c,run 35908208557/deployment 6622371614 完成 build、set image 和 rollout。它沿用此前的正文 watchdog、文字/图片分开收尾、模型对冲和 #209 同消息状态修复,并包含 #241 失败通知、#249 指标与 #253 DIO 免计费请求标记。当前 Pod digest、真实流量、模型双请求账单与 DIO 钱包结果未独立核验。最新 Fusion 部署
Sumi #237:让用户参考图、提示编译、生图与保存能连起来追查
#237 已在 9/23 合入 main,#239 随后删除运行时补充的角色/图片绑定规则,改由实际 Prompt Manager 模板提供;#240 的前台根 input/output 追踪仍在独立分支,曾部署 staging;当前 main 没有这项根记录接线。继续进入 main 的还有角色材料变化、分叉历史的状态重建,以及 #247 输入预算调整。具体输入、编译失败的持久化、何时保存快照和后续如何使用,已回填原图文运行章,不再作为“尚未合并的图文能力”。
本次更新**10/19 当前生产证据:**Sumi f9b26a9 已于 13:26 完成 production 镜像更新及成功 rollout,包含 #289 初始化追踪、#300 模型/图文开关和 #304 编译失败兜底,以及既有历史恢复、token 预算和 loading。当前 Pod、有效配置、客户端效果仍未独立验收。当前图文与生产版本。
9/24 以前的 staging 部署和失败模拟记录
Sumi staging 先后部署过 main 83013e6、72e13d7,之后还部署 #240、#247 的分支。9/24 巡检当时最新可见直接事件为 9/23 21:41–21:43 的 #251 46383d3,run 35868869411;该 PR 随后于 22:25 关闭且未合入。它新增进程级 SUMI_IMAGE_FAILURE_MODE,默认 off,可模拟审核拦截、模型错误或生成失败;写下的终态会被同签名重入复用,后来关开关也不重画旧槽。这个故障演练开关没有进入 main。失败模拟历史部署 · 已关闭未合 PR
当前已核 Sumi 生产版本与新的历史/占位行为见图文章节。下面保留早期 workflow 边界。
这些 workflow 完成镜像 set image/rollout,没有同时证明新增 YAML 配置已经 apply。尤其 promptCompilerUrl 是否进入 Pod、外部 Prompt Manager 是否有正确角色与参考图规则、失败模拟是否开启,都没有有效配置读回。最新部署事件也不等于当前 Pod 一定还运行该版本。main 定向 87 项、早前 compiler/追踪 108 项等检查通过;真实连续对话、compiler 故障恢复、生图和多客户端展示仍需业务验收。
早期 #237 候选的固定证据(保存追溯)
PR #237 · compiler合同[22] · 编译先于生图[23] · 快照保存步骤[24] · 非ready的处理[25] · stdout按回调返回判定[26] · 需区分的候选文档状态[27]
10/9 历史快照:合入、发布与当时尚待验证的状态
| 改动 | 具体作用 | 状态与限制 |
|---|---|---|
| Story #250/当前 main | 事件内沿用抽象氛围、视角和节奏提示牌 | 已合 main,Core Tools 0.2.3 已发布;旧会话关闭/换牌仍有当前源码限制,产品采用与生产验收未核。当前行为 |
| SDK #244/Pi 慢执行器 | 宿主创建原生 Pi Agent,共享模型用量账,配置取消后的等待;由宿主保存状态 | 已合 main,SDK 0.5.0、0.6.0 已发布;不等于普通 V2 自动更换内核。接法 |
| Fusion #241/#249/#253 | 图片失败时清客户端加载;增加进程指标;提交 DIO 时请求免计费 | 已合 Fusion 并包含于 c8fc61c production rollout,均非 main 新能力;展示、采集与钱包结果分别验收 |
Agent Router #252/6d14ce0 |
新增进程内 Prometheus 指标、/metrics 和 17 面板 |
Open,未合/未部署;采集器和实际看板未验 |
Loki #254/a266445 |
用已有容器日志做 10 面板/17 查询的看板 | Open;作者称已导入 production Grafana,未直接读取验证;它不使用 Prometheus。四个观测改动的区别 |
Worldbook #18/005e19c |
已合 main 的运行指标、36 面板/34 查询与两份抓取注解,不改业务选择结果 | 作者称看板已导入,但 image/annotations 未部署,无对应 deployment 或独立生产读取;零桶标签错误是已复现的 P1。指标与看板实际接线 |
Worldbook #15/be19065 |
候选 RollingUpdate 与 10 秒 Ready | 仍 Open、head 未变;未进入 005e19c,readiness 不等待 embedding reset 的既有边界保持。发布条件 |
Compact #196/#198:已转入主干,实验默认关闭
#196 原分支 codex/compact-jev-history-filter 于 63d27c40 合入 main;#198 在 e55ad141 加入助手自然段过滤与实测边界搜索。旧的“9/21 Draft”仅是当时状态,不再代表当前版本。现在可按配置筛完整对话组或助手段落,再生成摘要、保存检查点供后续复用;没有挂成主 Agent 的工具菜单。完整输入、参数、保存和下一轮采用。
**已修正的工程问题:**bounded_recent 路径遇供应商输入超限时,恢复该次已选区间的完整原输入与原摘要,清除过滤采用诊断,关闭丢弃,在剩余预算里重新规划;普通路径恢复当前阶段及后续原文。预算耗尽不写新检查点。**仍需验收的效果问题:**模型高置信误省略承诺或伏笔时,检查点覆盖完整区间仍不证明所有事实进入摘要;没有自动语义对账和事实恢复合同。原始聊天未删除。
**默认与验证:**过滤默认关闭;bounded_recent 边界搜索默认采用 binary,measured/cumulative 需要显式配置,巡检未找到现有 Scenario/deploy 启用这些增强策略。9/22 报告记录最新 Compact 定向 109 项通过;此前 provider-overflow 修复的定向检查已过。另一次旧 Compact 测试受 Node 24/stdout mock 限制,在 36 项后停止,不能把所有本地测试说成全绿。真实 Jev/摘要效果、总费用、P95 和部署有效配置仍未验证。该能力现在是“主干已实现、按配置启用”,不再是“待合入候选”。
合入 #196 · 合入 #198 · 当前实现[28] · 历史巡检记录。
9 月 17 日候选记录及当前对应关系
| 候选 | 想让业务做到什么 | 已核实的代码或记录 | 尚不能当作什么 |
|---|---|---|---|
| #170:融合图文入口增加 Yuzu | 同一组 Narrative 聊天入口接收 Aoi 或 Yuzu,生成与消息按请求的模型标记 | 固定 head de0ea87 的入口差异已读;Aoi 原回执指纹保持,Yuzu 增加模型隔离。目标是融合分支 codex/fusion-sumi-message-format,并非直接合入 main |
不能称 main 已支持此入口;不能称五种业务请求均已验收,也不能将其当成 Yuzu 独立价格档已接通 |
| #172:浏览器管理世界书测试绑定 | 拟让每个用户在浏览器管理“某份 Prompt 对应哪本书、哪版内容”,同时保留已有会话的版本固定关系 | 当时 head 0c9df14,12 个变化文件;巡检只核 PR 描述和文件清单,没有逐读实现 |
**该条是旧提案,不代表当前能力缺席。**后续 #188/服务 #12 已实现服务端 Prompt 关联和 Demo 读取;当前 Demo 仍无保存关联按钮,权限另验。现行实现 |
| #173:Sumi staging 部署时带上观测开关 | 更换镜像时,同时配置该测试环境的调用观测,方便后续检查运行链路 | 固定 head c3bae9b 的工作流已读:先检查环境变量/Secret 引用是否存在,再将镜像与 telemetry enabled/staging 一起 patch |
变量存在不等于凭据可用;工作流提案不等于已执行部署,更不等于正式环境已记录每次调用 |
例如业务选择 Yuzu:#170 会让 Actor 的上下文、保存的消息和 client_model_name 使用本次请求的模型;但是钱包请求的 model_tier 仍为 Aoi。因此这里已读到的是“扩展模型选择及回执隔离”,价格与计费档位还要按实际合同判断,不能把模型名称变化当作新价格已经生效。入口及回执[29] · 钱包与 Actor 参数[30]
**#170 有测试环境部署记录,但业务验收仍有缺口。**作者在 9 月 17 日约 16:30 记录了精确 head 的 rollout、1 个 Ready 实例、健康接口 200 及 /meta 版本;巡检未直连环境重验。记录中的五入口未授权请求返回 401,只验证拒绝未授权访问;带鉴权的聊天、续写、重生成、编辑后重生成和单图功能端到端验收尚未完成。部署与验收记录所在 PR
三个候选的固定版本、阅读范围与环境证据
9 月 17 日 19:40 巡检所见三项均为 Open。#170 固定 head de0ea8788fdeac419c8a7b5b70a95968a5370e9f,未固定 PR base SHA;两文件中已读 narrative-api.ts 有效差异,测试差异后半未逐读。作者记录的 staging 镜像为 sha256:df3200561823800f977fcc3ad7e80ebf970a65b08d8f18eba139a101a2a208c4。CI 绿色和健康检查各有证明范围,不能替代真实五入口验收。
#172 固定 head 0c9df14e966a09db6c9410cd7b25e9219aa00b12,#173 固定 head c3bae9b518645a181c46e9daac48aa7f083cfb8e;两项目标为 main,当时均提示 base 已过期。#172 仅元数据/文件清单,#173 为单工作流差异阅读。#173 作者另称已有一次 Shiki smoke trace,巡检没有独立查询,不能据此确认当前环境观测状态。
世界书绑定候选 #172 · 观测变量预检[31] · 镜像与开关更新[32]
9/21 回填:Fusion 目标分支中的三项候选
以下三项在 9/19 23:40 巡检中逐文件读过 patch;不是今天重新扫描全部远端分支,也不是 main 已采用。
| 候选与固定提交 | 研发要增加什么 | 实际实现与尚未闭合处 |
|---|---|---|
#185 · c3800221 |
Planner 为多段图文 Actor 调用写每段指令,让后续段落按预期推进 | schema 要求 instruction,但执行时只把它放进 trace,未放进 Actor 的请求/历史/变量。不能宣称按该段指令生成已接通。定义与调用[33] |
#187 · 4ecaba2b |
记录完整模型和工具内容,方便排查图文运行 | 只开总观测就 captureContent=true,没有独立内容开关;用户、历史、正文/reasoning 和工具结果可被记录。此候选采集完整模型/工具内容;9/22早间main当时只放行Worldbook envelope;现行main还在exact staging开放普通内容,并新增常开stdout日志,详见观测章。配置[34] |
#192 · 2b5b9c9 |
收紧 AOI 图片块结构,并为用户角色补图片参考标记 | 枚举/JSON shape 和 owner=user 的 picture2 补标已有差异;姓名仍按相等或互为前缀匹配,同名/短名冲突未验。CI 成功不代替这些业务边界验证 |
三项的目标均是 fusion-harness;本次未取得其生产部署和业务采用证据。主干已合入的 Jev/SDK gate #195 在慢通道和SDK说明,不继续归入“未合并候选”。
这些改动解决哪种用户问题
第一种:用户重生成了回复,旧剧情状态会不会串进新分支? 例如旧回复说守卫接住钥匙,新回复改成没有接。Pioneer 候选增加根据可见消息和内容关联去找状态,并在提交前等待相应非空助手正文保存,再把状态引用关联回消息。它要改善的是“这份状态属于哪条回复”。
但这不等于后台重读了新正文后再分析。该候选仍用本轮起始材料;正文保存、状态提交、引用关联也是分开的步骤,仍可能部分失败。不能据此承诺完整事务或语义完全一致。
第二种:想把一轮的文字和图片交付到聊天产品。 Pioneer 扩展图文宿主和图片资产任务;另一条 44ffcf1 格式候选将文字、段落关联图片等接到原生消息格式。它们是不同接线,不能从一个分支有某工具推导另一个分支也已接好。格式候选的原生单图重试与完整端到端验收仍有未闭合项。
第三种:一张图重画失败,能否保留旧的好图? 历史巡检在平行候选 e3b57e6 找到相应修复。这个事实只属于该次固定分支核验,不能推广成今天所有 Sumi、AOI、Pioneer 失败路径的共同保证。
有些听起来相近的能力,其实还没完成
这些候选没有因此新增“模型遇见新人→创建完整人物实体卡→发布成世界书→下一轮自动使用”的统一链路。人物专家仍主要给分析建议,普通 Director 仍整理状态;若要可独立编辑的小卡,还需要明确的数据结构与读写连接。
候选中对用户显示通用错误文案,也不能证明所有内部日志都做了同样处理。已核实的一条原始异常转写日志路径仍需单独解决;这是特定代码路径的条件性风险,不是本次观察到线上泄露事件。
什么时候可以把候选写进正式产品能力
需要确认目标代码合入或明确选择部署该候选、业务请求走到它、所需配置和依赖已开,再验证实际交付及失败路径。镜像构建推送成功只说明构建阶段完成;它不能单独证明新服务接管线上流量。
因此本章主阅读给业务影响,下面展开给精确分支、输入输出、失败条件和历史构建证据。对用户承诺时,应使用已确认的运行版本,而不是把所有候选优点合在一起。
逐项变更、原始巡检与固定分支证据
以下为此前固定版本核查的详细记录;其中“本次”“昨天”指该记录形成时,不代表本轮重新巡检或部署。
本次核查两条尚未合入 main 13c481b 的候选:Pioneer 61039e5,以及图文消息格式 44ffcf1。 它们扩展图文交付、消息分支与状态归属,没有新增“自动创建并发布完整 NPC 小卡”的闭环。第 14 章列工具能力,本章说明候选实际改变的结果与尚未闭合的部分。
当前候选能解决什么,结果怎么使用
| 候选能力 | 用户场景与结果 | 仍需区分的边界 |
|---|---|---|
| Pioneer:后台状态跟随消息分支 | 重生成或改写后,按可见消息及内容锚点找状态;提交前等指定非空助手正文已保存,CAS 后将快照引用挂回消息 | 等正文存在不等于后台重读正文再分析;正文、CAS、挂接分步进行,仍可能部分失败。第 5、6 章已就地说明 |
| Pioneer:图文宿主链 | 解析 Actor 图文段、准备视觉状态/提示词、执行图片资产任务,再按消息保存与通知时序交付 | 属于候选应用接线;图片钱包虽有类实现,当前图片执行链已不调用,不能画成每轮必经 |
| 格式候选:原生消息交付 | 文字用 chatStream/chat,图片按段落锚定,落入原生图片字段;私有图片状态存 Axon memory | 不是 Pioneer 的同一条必经路径;记录明确原生单图重试未进入 Fusion,端到端验收未完成,那次最终运行也未重验 chat 与 edit-regenerate |
依据:Pioneer 状态读取、等待与挂接[35] · Pioneer 图文入口[36] · 格式实现与验收记录[37]
昨天巡检还发现了什么
同一张图重画失败,还要看旧图是否保留。 01:36 报告在平行候选 e3b57e6 确认了修复:旧图已审核通过时,新重绘失败仍保留旧 URL、审核结果、主色与任务 ID。这只按该固定候选记录,未据此宣称今天 main 或 61039e5 的每条失败路径都有同等保证。历史重绘修复
对用户隐藏详细错误,不等于内部日志也隐藏。 07:39 等报告提出的原错误日志问题,本次在 61039e5 定向复核仍有路径:Narrative 重抛原 cause,后台 runner 取 error.message,dispatch 写 stdout。如果上游错误含敏感内容,仍可能进入日志;这不是本次已确认的生产泄露事件。第 18 章列完整依据。合并候选前应修正并验证这条路径,不能只看默认不抓正文的遥测配置。原异常[38] · 后台错误记录[39] · 日志输出[40]
展开 9 月 16 日候选 071eb76 的逐步解释与构建证据(历史版本)
核查对象是 codex/pioneer-actor-progress 的 071eb7664a2201824aa5373af2342930aca30910,不是主线 77a1537,也不是已确认运行中的服务版本。GitHub 提交页记录 2026-09-16 19:55(GMT+8),9 文件、+154/-97;父提交 719f4e650c9484b3207ce14bb5c170b26a5a195b 为当天 14:58,3 文件、+89/-4。主线到该分支的 GitHub 三点比较显示 43 commits / 100 files,包含分叉后的历史,不能把这 43 笔都称为“刚刚上线的新改动”。本次只读提交差异和最终版本关键源码,未执行部署或业务调用。071 提交、719 提交
对用户“先接剧情、后台补人物”的解释,有一处必须增补
并行分工没有变,持久状态与已保存正文的绑定变了。 候选版仍在 Actor generate() 开始时调用 coordinator.schedule(),慢路仍使用本轮起始材料。因此:用户 query 已点名新人物,本轮后台可审计;Actor 本轮才发明的名字,要等正文进入后续历史,后台才能针对它审计。候选没有增加“先同步生成完整 NPC 卡才让 Actor 回复”的步骤。并行调度[41]、Actor 启动点[42]
但在候选的普通 Agentic 装配中,dispatch.ts 会恢复 assistant lineage,并把 context 传给 AxonAgenticStateRuntime。它启用以下链路,不能继续沿用主线“后台完全独立于正文是否已保存”的表述:
- 读哪份状态:从当前可见历史倒查 assistant 消息,在存储消息中找到
narrative.agenticState;核对消息 ID、scenario、assistant 正文 hash、对应 user 消息及其 hash,再按snapshotRef取这条分支的状态。没有可验证锚点时,使用空快照基线;只有现存 state 的来源消息确实还在当前可见分支中,才允许兼容升级。 - 什么时候允许发布新状态:后台可以先计算,但 CAS 前会等本轮 assistant 消息已经保存、角色为 assistant、正文非空。最多等 120 秒,每 200 ms 查一次。不需要等用户点“接受”,这里的门槛是业务存储里已有正文。
- 保存以后怎样关联:CAS 带
baseSnapshotRef,成功后把snapshotRef、assistant 正文 hash、userAnchor 保存回该 assistant 的 narrative。后续读取按这些锚点识别所属分支;改写/换分支导致 hash 或锚点不匹配时,不能直接拿旧分支状态。
这改进的是“这份后台状态属于哪条已保存回复”,没有把本轮 Actor 新正文追加给已经启动的 Planner,也没有宣称整套跨服务事务原子化。保存正文、CAS、挂接快照仍是不同步骤;代码对丢失 CAS 响应有读回确认,并可重试挂接,但仍可能失败。入口实际传入 lineage[43]、分支选择[44]、等待正文与挂接[45]、CAS 及恢复[46]
NPC 本体没有新增完整人物卡 schema
最终版本仍使用原六个专家及 update_director_state。judge_npc 的模型调用参数还是 reason(必填)、focus(可选),输出仍是 {ok, tool, result: 文本, usage?},失败则带 error;职责描述仍明确 advisory / never writes state。最近 4 条消息加 query 的名字检测、首轮/新名字补审计、Director 合并候选的结构仍在。没有在这个候选中发现“创建 NPC 实体卡”“新增世界书条目”的人物工具。不能把画像示例写成已强制执行的固定性格/身世字段。最终人物工具契约[47]、最终触发逻辑[48]
候选另有一个状态质量变化:Director 候选校验失败后,重试请求会带回具体 validationFeedback,要求完整修正、保留全部必需段落、缩短各段,不要只返回缺失段或编造事实补空。这改善格式修正反馈,不能保证人物事实一定正确。重试校验反馈[49]
前台模型菜单仍是四个,新增业务能力主要在宿主工具链
| 位置 | 当前明确有什么 | 业务例子与边界 |
|---|---|---|
| 前台 function loop 的模型菜单 | actor、generate_image、schedule_dio、over |
调 Actor 写一段;按这段安排图;用户明确要求长期修改时安排 DIO;结束本轮。没有新增 create_npc_card |
actor 参数 |
responseMode: complete / visual_beat,使用整轮剩余 token 预算 |
“先写一幕,再配图”,不是给每一段重新发一份完整预算 |
| 独立 Narrative HTTP 入口 | /v1/chat、/v1/chat/continue、/v1/chat/regenerate、/v1/chat/edit-regenerate |
独立处理聊天、续写、重生成、改用户消息后重生成;要求目标 scenario 有 Agentic V2、AOI 输出、modelConfig/preset |
| Narrative 宿主调用 | conversation.meta.get、conversation.history.get、conversation.message.get、conversation.messages.save;history.prepare/对应操作;wallet.charge;notify.push;AOI parse_narrative |
校验当前分支与消息 → 准备历史 → 预留计费 → 生成 → 解析图文段 → 保存并读回确认 → 提交计费 → 推送完成消息 → 放行图片交付。它们是业务代码调用,不是全部暴露给 LLM 的菜单 |
| 图片资产/执行链 | AoiImageTool、EmochiImageAssetTools、AOI 状态/提示词工具;本次明确新增兼容操作 parse_image_prompt |
从最新 Actor 段落准备图、跟踪图槽位和已生成结果;图片结果在完整消息推送后才交付 |
前台菜单及独立入口见Actor runtime[50]、Narrative 入口[51]、实际装配[52]。这些最终候选路径已逐项读取;不能从分支源码单独证明线上 scenario 已启用。
9 月 16 日两笔提交,玩家能感知到的具体变化
14:58 的 719f4e6:生成中能提前看到经过过滤的 Actor 正文预览。 前提是有 onProgress、没有 after-hook Agent,且正则规则为空或能被安全流式过滤;特殊识别现有 Luna 的四条过滤规则。visual_beat 等原本缓冲的段落也可以给 Narrative 客户端预览;最终 Axon 过滤结果仍是正式内容,完成时替换预览。不是所有输出配置都无条件逐 token 展示。预览条件和实现
19:55 的 071eb76:图片坏一张,尽量保留正文和其他图片;Actor 瞬时失败不再过度扣掉回复额度。
- Image Prompt Producer 请求明确
maxTokens: 2000、thinking: disabled。图片块交给 AOIparse_image_prompt统一兼容解析/编译,移除前端额外的严格字段校验;可兼容缺省相机字段、可修补 JSON 等,嵌套 image 分隔符仍拒绝。 - 对特定 AOI 准备失败(
parse_image_prompt、apply_state_patch、initialize_state),在 AOI 输出、实际生图及流式图片交付已开启且未取消时,保存一个带image_preparation_failed的失败槽位和可人工重试的场景提示词。该槽位不会继续实际生图,其他正文/图槽位得以保留。不是所有异常都吞掉。 - Actor 失败且上游没有 usage:若没有收到任何正文,不扣这次回复额度;收到部分正文则数这段实际 token;计数服务也失败时才保守占用本次上限。预算耗尽时保留原上游错误,避免被“重试没预算”错误覆盖。这里是回复额度管理,不是声称供应商未计费。
- Narrative 失败会保留 Harness 原错误和 error_code;不再统一替换为没有原因的 “Narrative turn failed”。
图片准备失败隔离[53]、图片提示词兼容解析[54]、AOI 新操作[55]、Actor 失败额度处理[56]、本次完整提交
本章描述候选分支已实现的路径;线上是否启用仍需运行证据。主线的取消/提交说明保留在第 17 章。
构建成功能证明到哪一步
本次实际打开了候选 071eb766 对应的 Build Staging Image #235 任务:Build and push 在 19:57 成功,步骤包括源码检出、ECR 登录、镜像构建与推送。没有在这个 job 中看到集群 apply 或 rollout。GitHub 环境页的 “Deployed” 标签因此不能单独证明新服务已替换线上流量;这也不排除存在另一路人工或自动部署。
依据:核查的构建推送任务。
核查范围:已读 071/719 两笔提交差异、071 最终 planning/runtime、planning/agentic-v2、advisory、dispatch、Actor runtime、pre-actor-director、Narrative API,以及图片相关改动。未对分叉以来 100 个文件全面审计,未读线上 PromptManager 实际内容,未执行测试、部署或核对集群运行镜像。自建研究标签页已关闭。
代码证据 · 56 处
- 动作及 Jev 实际参数 ↗
- 循环、预算与出口 ↗
- JWT 接线 ↗
- 认领、重绘和保留旧图 ↗
- 实际启用条件 ↗
- 工具输入与单图输出 ↗
- 识别、镜头、兜底和编译 ↗
- 群聊参考执行 ↗
- 候选读取检查 ↗
- 保存及消息 ID 前提 ↗
- 滚动策略候选 ↗
- 当前 readiness ↗
- 估算的边界 ↗
- 对话组分类失败处理 ↗
- 段落分类失败处理 ↗
- 计时与正文结束 ↗
- 图片失败隔离 ↗
- 有限回滚 ↗
- 对冲状态机 ↗
- Actor可见结果获胜 ↗
- 实际5秒配置 ↗
- compiler合同 ↗
- 编译先于生图 ↗
- 快照保存步骤 ↗
- 非ready的处理 ↗
- stdout按回调返回判定 ↗
- 需区分的候选文档状态 ↗
- 当前实现 ↗
- 入口及回执 ↗
- 钱包与 Actor 参数 ↗
- 观测变量预检 ↗
- 镜像与开关更新 ↗
- 定义与调用 ↗
- 配置 ↗
- Pioneer 状态读取、等待与挂接 ↗
- Pioneer 图文入口 ↗
- 格式实现与验收记录 ↗
- 原异常 ↗
- 后台错误记录 ↗
- 日志输出 ↗
- 并行调度 ↗
- Actor 启动点 ↗
- 入口实际传入 lineage ↗
- 分支选择 ↗
- 等待正文与挂接 ↗
- CAS 及恢复 ↗
- 最终人物工具契约 ↗
- 最终触发逻辑 ↗
- 重试校验反馈 ↗
- Actor runtime ↗
- Narrative 入口 ↗
- 实际装配 ↗
- 图片准备失败隔离 ↗
- 图片提示词兼容解析 ↗
- AOI 新操作 ↗
- Actor 失败额度处理 ↗