Harness · 一轮聊天实例回到项目导读 ↗

先看业务:接住当前剧情 · 补齐当前资料 · 保持后续连续

一句话进去,回复和笔记怎么出来?

用户:“我把铜钥匙递给北塔守卫,请他开门。”

这轮给用户的回复 · 示例“手令呢?光有钥匙还不行。”
后台可能保存的笔记 · 节选用户已递出钥匙;本次分析还没收到守卫回应。
一次只看一步

第 1 步 / 共 7 步

用户只发一句话,系统要替这次对话办哪几件事?

本章单独演示“守卫接过钥匙,仍要求手令”这一种可能回复。其他章节也展示了“守卫没有接钥匙”的分支;各章例子分别演示系统行为,不构成一段连续聊天记录。

先从用户的期待说起。 用户递钥匙之后,需要看到守卫怎么回应;回复要符合北塔规则;继续聊下去时,系统还得记得钥匙交接进展、谁知道什么。当前接线把这三件事分开处理(这套普通后台实现的代码名是 Agentic V2):

  • 回复前补资料: 查到“铜钥匙不能替代手令”,让当前回复有规则可依。
  • 现在接剧情: 回复模型 Actor 写出守卫的反应,交给用户。
  • 同时维护后续状态: 后台分工模型 Orchestrator 按需安排检查,Director 再把值得保留的内容整理成新状态,供以后回复读取。

Harness 是把这些工作接起来的程序。 它负责送材料、发起模型调用、执行工具和保存结果。模型负责生成文字与提出判断;程序决定这些判断怎样被执行、能否被保存。

这里称“快通道”的是当前回复工作,“慢通道”的是后台连续性工作;称呼表示职责,不保证后台一定更晚完成。世界书要在当前回复前准备,普通后台分析则与回复并行。

这几个英文名分别是谁?放在一起对照

“模型”指能读文字、生成文字或工具请求的 LLM(大语言模型);下面的英文是岗位名,不是五家不同模型公司的名字,也不代表一定用了五种不同底层模型。

名字 到底是什么 在递钥匙这轮交出什么
Harness:负责把整轮跑起来的程序 按已选功能送材料、调用模型、执行工具、检查和保存结果 把查到的世界书交给回复模型;把后台新状态交给存储服务
Actor:写当前回复的模型岗位 把角色、历史和本轮资料写成用户能读的剧情 “手令呢?光有钥匙还不行。”
Orchestrator:后台分工的模型岗位 判断该找谁检查;必要时看检查结果,再决定是否整理状态 “检查守卫的身份连续性和知识边界。”这样的工具请求
专家工具:针对一个问题做检查的功能 Harness 执行这些工具时,会调用有专项工作说明的模型;六个名称对应六种职责 “能确认用户已递出钥匙,不能确认守卫已放行。”这样的建议
Director:整理剧情状态的模型岗位 把旧状态、本轮材料、可用建议整理成供后续回复读取的一整份新状态 已发生的行动、人物关系、未知事项,以及可以怎样继续演的软建议;由程序另行检查和保存

工具就是程序已经登记好、允许模型请求执行的功能。模型发出请求,Harness 才真正执行。Director 也是通过一个工具入口被调用的;它具体怎么定义、写些什么,直接看本页第 5 步。

收到的具体内容

用户输入:

我把铜钥匙递给北塔守卫,请他开门。

接入这个能力的业务后端,还要告诉 Harness:这是哪段会话、使用哪个角色、按哪套功能设置运行,并提供本轮对话所需信息。程序才能读对这个会话的旧记录、找到对应资料。只发一句“开门”并不足以确定这些事。

产品后端为这次聊天选择了代码里已有的“世界书专用场景”。这里的“场景配置”是一套预先保存的功能开关和模型选择,不是故事里的北塔场景。 这份配置包含:

  • 一个回复模型:负责接住当前剧情,写给用户看。
  • 一个后台分工模型:判断这轮需要检查什么。
  • 六种可选检查:剧情、人物、知识、场外变化、伏笔、场景节奏。
  • 一个 Director:需要时把旧状态和检查建议整理成新状态,既有连续性记录,也可有后续剧情的软建议。
  • 世界书:回复前按规则选择条目,补充当前需要的设定。

这份场景配置没有启用图片、前台多工具循环、另一套章节剧情流程、日记记忆源或对话压缩。

做什么

谁决定同时走两条路? 业务后端在请求中指定处理方式,Harness 按预先配置安排。本例配置选择了“当前回复+普通后台”;不是让模型先读“递钥匙”再判断应该二选一。

系统按这个选择,准备“当前回复”和“后台检查”两份工作。六种检查都可选,不等于每轮六种都跑。 这次例子只用人物、知识两种。

没有启用日记或对话压缩,也不等于系统失忆:已经保存的对话历史和上一版后台笔记仍会读取。

交出的具体内容、给谁用

这轮要准备两条工作:

给回复模型:请接着写守卫如何回应用户递钥匙、请求开门。
给后台分工模型:请检查这轮是否产生了以后需要记住的变化。

这两句话是对工作职责的通俗表述。下面展示它们实际收到的材料。

查字段:请求怎样选方案,哪些是实际配置开关?
名称 用人话说 当前页面所依据的例子 谁提供 / 谁用
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 和模型重试等另有调用

第 2 步 / 共 7 步

回复前必须准备什么?为什么两边看到的资料不同?

模型这次能参考什么,取决于程序这次实际交给它什么。 这一步把四种来源接到一起:作者写的角色、知识库中的世界规则、已经保存的聊天,以及这个会话此前整理的状态。它们分别回答“谁在说话、世界怎么运作、刚才发生什么、哪些连续性要记住”。

收到的具体内容

先解释这几份材料的名字: query 是用户这次刚发的一句话;“角色卡”是作者事先写的角色身份与行为设定;“历史”是已经发生并保留的聊天原文;“世界书”是预先维护的背景资料。

**后台状态(State)**是这个会话目前的剧情工作记录。这页为了好读也叫它“笔记”:它不仅记过去,还可写“接下来可以怎么演”的建议。版本 12只是这份记录的保存版本号,不表示已经聊了 12 轮。

角色作者写的角色卡:

艾琳是旧城向导,谨慎、话不多,正在陪用户前往北塔。她不替用户决定行动,也不凭空知道没有见过的秘密。

之前已经保存的笔记,版本 12:

用户与艾琳在北塔门外,铁门仍关着,尚未进塔。门口是此前已经多次交谈的那一名守卫。用户持有铜钥匙;没有可见证据说明守卫知道钥匙的来源。

最近已经发生的两句对话:

用户:我们又回到北塔门口了,铜钥匙还在我这里。
回复:守卫认出了你,在岗亭旁站直身子。“又来了?这次有什么事?”艾琳停在你身侧。

如果提供了用户人物设定(Persona),例如“用户扮演外乡学徒”,它描述的是用户扮演谁;不能误抄成艾琳或守卫的身份。本例未另设 Persona。角色的“开场白”是开始这段聊天时的第一段角色文字;Director 的实际输入还会单独带上它,这里省略长篇原文。

本轮新输入:

我把铜钥匙递给北塔守卫,请他开门。

知识库维护者预先写好、本例这一轮被选中的三条世界书原文:

条目 原文
常驻:旧城与北塔 “北塔是旧城封闭区域的入口。塔门是铁栅门,门外设有守卫岗亭。”
按本轮内容选中:北塔通行规则 “岗亭通行告示:持有铜钥匙仍须出示加盖城主印章的手令;手令在市政厅登记处申请。这项守门规则已告知当班守卫。”
按本轮内容选中:塔内秘密 “北塔封存着危险的回声装置。真正用途只有城主和塔内书记知道;门口守卫不知道装置的存在。”

做什么

Harness 先取得本会话绑定的世界书版本,再把用户这句话、旧状态里的公开场景、近期对话等线索交给世界书服务。可查哪本书,由已有绑定限定;具体选哪条,由服务结合条目规则、相关性、可放置的位置和预算计算。

本例关键词是“北塔、铜钥匙”,当前地点在塔门外,所以假设这次选中了上面三条。Harness 拿到的是条目正文,把它们放进回复模型的消息里。这里说“注入”就是把原文加入这次发给模型的输入,不是把知识永久训练进模型。

“这次选中三条”是例子条件,不是每轮固定三条,也不是让回复模型自己临时编出三条设定。

第三条同时说明了秘密和谁知道秘密。回复模型能看到它,不代表守卫知道它;守卫只能谈自己有依据知道的事情。

交出的具体内容、给谁用

接收方 这次收到 这次没有收到
回复模型 角色卡、版本 12 笔记的输入文本、最近对话、用户本轮输入、三条世界书原文、回复工作说明 尚未生成的后台新笔记
后台分工模型 角色卡、版本 12 笔记及已有记录的输入文本、最近对话、用户本轮输入、分工说明和可选检查菜单 本轮三条世界书原文;回复模型稍后生成的新正文

两边不同,原因在于代码分别组装两份模型输入:后台没有复制那份已经放好世界书的回复请求。本例回复模型知道“还要手令”,后台目前却没有收到这条规则。后台若在别处见过相同规则,是另一回事;这个例子没有假设它见过。

查材料名称:Prompt、Context、State、版本和来源记录分别是什么?
名称 用人话说 钥匙例子 谁提供 / 谁用
prompt / 工作说明 告诉模型这次扮演什么岗位、应该怎样工作的文字 “你负责知识检查;不要把猜测写成事实” 配置/提示词管理提供,程序装进模型请求;模型读
context / 上下文 这次真正发给某个模型的整包材料;不是它能访问的一切数据 卡片+旧笔记+历史+本句输入;Actor 还收到选中的世界书 Harness 组装;每个模型收到的包可能不同
query / 本轮输入 用户当前说的这句话;在世界书检索中,查询文本还会加公开场景描述 “我把铜钥匙递给北塔守卫,请他开门” 用户提供;程序送去回复与后台,并组装世界书检索 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 数组不是同一个字段:前者是完整笔记内部的一个标题;后者是额外保存的结构化分类记录。

第 3 步 / 共 7 步

哪个结果现在交给用户?哪些工作同时在后台做?

这一步要解决“这句话之后,人物怎么回应”。 当前回复不用等普通后台把新状态整理完;它先使用已经准备好的旧状态和本轮世界书。这样后台维护连续性的工作,不会成为这条路径统一等待的前置步骤。

收到的具体内容

回复模型看到:

用户已经向老相识守卫递出铜钥匙,请他开门。
世界书说:守卫知道必须有手令;他不知道塔内回声装置的秘密。
用户仍在门外,艾琳在身侧;不要替用户决定下一步。

做什么

回复模型根据这些材料,接着写人物回应。开始这份正文生成时,系统也安排后台工作;后台不必等整段正文完成后才开始。

用户已经表达“递出钥匙”,不能被降格成“只是打算递”。 但守卫是否接收、是否放行,是需要在回应中继续发生的事,不能仅从用户的请求推定已经发生。

交出的具体内容、给谁用

本例回复模型可能交给用户:

守卫接住你递来的铜钥匙,看了一眼,却没有转身开门。
“手令呢?光有钥匙还不行。”
艾琳停在你身侧,等着你回应。

这里新增了两件事:守卫接住钥匙;守卫要求手令。 它们来自这次新正文。此刻并行工作的后台使用的是之前准备好的材料,不会自动读到这两句新事实。

第 4 步 / 共 7 步

后台怎么决定查什么?执行工具实际发生了什么?

后台不是另写一段更长的聊天回复。 它要判断这句话有没有需要专门检查、值得以后继续保留的内容。本例重点在钥匙交接与证据边界,因此展示人物、知识两项检查;剧情、伏笔等其他检查并非必做。

如果当前材料没有值得专门检查或更新的内容,模型也可以不选工具、保留原状态。七步是这次例子的阅读路径,并非每轮必须跑满的流水线。

模型会收到每项可用工具的职责和参数说明,再根据本轮材料提出调用。代码没有规定“每次出现钥匙就必叫知识专家”的统一规则,所以这里的两项选择是教学例子,不是确定的关键词开关。

收到的具体内容

后台分工模型能看到的关键变化是:

旧笔记:用户持有钥匙,尚未进塔,守卫是以前已经认识的人。
本轮输入:用户已经递出钥匙,并请守卫开门。
尚无材料:守卫这次如何回应;北塔完整通行规则。

它这次发出两张任务单:

给谁 为什么找他 具体检查什么
检查人物的模型 “老相识守卫正在参与钥匙交接,需要检查人物与动作是否接得上。” “保持是同一名守卫;记录用户已递出,不替守卫提前接收或开门,不擅自补性格和身世。”
检查知识的模型 “用户拿出钥匙并请求通行,需要区分已有证据与未确认结论。” “守卫是否知道钥匙来源?有没有证据证明已获准通行?目前是否读到了通行规则?”

做什么

任务单要有机器能识别的格式。 分工模型除了可能生成普通文字,还可交出工具名和参数;例如“工具名=检查知识,任务重点=有无放行证据”。Harness 读取这些字段,才知道执行哪段已登记的功能。模型只说一句“最好检查一下”不会自动产生同样效果。

系统收到任务单后,找到两项已经登记的检查功能,把角色卡、版本 12 笔记、已有对话、这次新输入,加上各自工作说明和任务重点,交给两个检查模型。它们可以并行工作。

本例不是首轮,也没有新名字,主要展示模型选择工具。实际代码在首轮或识别到新名字时,还可能由程序补检查任务,不能把所有选择都归功于模型。

交出的具体内容、给谁用

人物检查交回的建议:

继续沿用此前那一名北塔守卫,不新增人物。用户本轮已向他递出钥匙并请求开门。当前检查材料还没有守卫接收或放行的回应。现有资料不足以新增守卫的性格、身世或隐藏动机。

知识检查交回的建议:

用户已递出钥匙是当前可见动作;守卫知道钥匙来源、已经允许通行,则没有足够证据。当前检查材料没有提供完整通行规则,不能断言“有钥匙就能进”,也不能凭空补出“还要手令”。

两份建议交回后台分工模型,之后也可交给整理笔记的模型。它们不是玩家正文,也没有直接创建人物卡或改写正式笔记。

查任务单字段:工具名、参数、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 标必填,不等于执行器已经保证模型每次都正确提供。

第 5 步 / 共 7 步

几份检查结果怎样变成下次能用的状态?Director 在这里做什么?

专家各看一个问题,后续回复却需要一份能连贯使用的状态。 例如人物专家强调“还是同一名守卫”,知识专家强调“尚无放行证据”;程序不能仅凭把两段文字拼起来,就认为已经得到一份完整、没有遗漏和冲突的新状态。因此这里再调用 Director,综合材料、保留仍有效的旧内容,写一整份待保存的新稿。模型可能整理错,后面的程序格式检查也不能保证剧情语义全对。

Director 在本项目里是“整理剧情状态的模型岗位”。 代码把一份专门的工作说明和材料交给配置选定的 LLM(大语言模型),让它写出新状态。这个岗位的作用是把零散材料变成后续回复能使用的一份统一记录:哪些已经发生、人物想做什么、谁知道什么、哪些事仍待确认,以及剧情可以朝哪里发展。

它的职责由三部分定义:

  1. 岗位工作说明(Prompt): 指定“写完整状态、保留有效旧事实、根据已有对话和有效建议更新”。例如:只知道用户递钥匙,不能直接写成用户已经进塔。
  2. 模型选择(ModelConfig): 服务端选择这次用哪个模型配置执行 Director 工作。Director 是任务角色;配置名本身不能证明底层一定用了哪家、哪款模型。
  3. 工具入口(update_director_state): 后台请求“整理状态”时,Harness 通过这个入口调用 Director。名字虽然有 update,工具首先交出待保存的新稿;保存成功还要看第 6 步的程序处理。

谁叫它开始? 普通后台可以由 Orchestrator 选择这个工具;首轮或新名字等规则也可能补调用。本例是看完两份专家建议后再叫 Director,不是每轮固定把所有专家跑完才允许它工作。

收到的具体内容

后台分工模型第二次收到:

原来的角色卡、旧笔记、历史和用户输入。
我刚安排了人物检查和知识检查。
人物检查说:用户已递出,守卫的回应在这份材料中未知。
知识检查说:没有证据证明已获准通行,也没收到完整通行规则。

这次可选动作只剩“整理笔记”;不能再自由打开下一批人物、剧情等检查。

做什么

本例分工模型决定整理,发出理由:

把“用户持有钥匙”推进为“用户已递出钥匙并请求开门”,保留守卫回应尚未进入本次材料的边界,不新增未知身份、知识或通行规则。

Director 随后收到:旧状态、角色资料及开场白、可选用户人物设定、已有对话、本轮输入、这段整理理由、两份检查建议。它据此写一份可以替换旧版的完整笔记:保留仍有效的旧内容,再写入本次变化,不只返回一句“检查完成”。

这就是工具做完后的一次复核:看两份建议,决定是否整理笔记;不是复核当前刚写的玩家正文。

这次第二轮判断之所以发生,是因为已经执行了检查,而且配置允许整理笔记。没有专家调用时也可能直接整理;不需要更新时可以保留旧版,并非每轮都跑满这些步骤。这里按“选动作、执行、看结果、决定更新”推进,不需要先写大计划,但也不会无限重复选择工具。

交出的具体内容、给谁用

Director 交给 Harness 的是一份完整的新状态文本,技术字段叫 candidateState。“candidate”只是“等待程序检查和保存的新稿”,不是另一个 Agent,也不是已经采用的结果。

这份文本里有三类内容,使用时要分清:

内容类型 本例可写的具体内容 后续回复怎么用
已有事实与证据边界 “用户已递出钥匙;本次后台还没收到守卫回应。” 接住已经发生的行动,避免误写成用户已经进塔
人物目标与行为约束 “艾琳仍谨慎,不替用户做决定;守卫不知道没有依据的秘密。” 保持人物一致,不让他突然无所不知
后续剧情的软建议 “围绕当前通行请求自然推进;用户转向别的事时跟随用户。” 给回复模型参考,不自动安排必演剧情,也不保证模型逐字照做

Director 不只是聊天摘要器:它同时维护连续性和后续演绎建议。 建议必须与“已发生事实”分开。下面仍只展示本次事实变化的节选:

人物连续性: 门口仍是此前已与用户交谈的同一名守卫,不新增人物。
本轮用户动作: 用户已向守卫递出铜钥匙,并请求开门。
尚待后续材料: 本次分析还没有守卫接收钥匙、同意放行或开门的回应,不能记为用户已经进入北塔。
知识边界: 尚无证据说明守卫知道钥匙来源。北塔是否还要求其他通行凭证,在本次后台材料中未确定。

新笔记里没有写“守卫已经要求手令”。 当前回复可能已经这样写了,但这次后台没有收到那段新正文。这份笔记表达的是“这份材料里不知道”,不是“这个世界没有通行规定”。

这份“完整状态”到底写哪些内容?逐项看用途和例子

这些是一段长文本里的栏目标题,不是 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。

岗位提示词加载 · 状态进入后续 Actor

第 6 步 / 共 7 步

模型写完就生效了吗?谁负责保存,失败怎么办?

写出一份稿子与把它变成当前会话记录,是两件事。 Director 完成的是前一件;Harness 负责检查和提交。这个界限能让格式无效或已经过时的新稿不直接覆盖现有记录。

收到的具体内容

系统收到两样东西:

一份完整的新笔记,包含上一节展示的几句变化。
这份笔记是基于旧版本 12 整理出来的。

做什么

revision 是记录当前保存版本的字段;state 是已保存的状态正文;candidateState 是 Director 刚生成、尚待采用的新正文。例如:读到 revision = 12 和旧正文,再拿新正文去申请保存。

系统用程序检查完整笔记的长度、必要标题和顺序、禁止的内部标签,以及内容有没有变化。这里没有再请一个模型审查人物设定是否合理。

**检查旧版本再保存(CAS)**的意思是:“只有现在的旧稿仍是我读到的那一版,才接受我的新稿。”这里要求仍是版本 12;若已被另一份更新抢先修改,就不能直接覆盖。本例假设检查通过、内容有变化、版本仍匹配,保存成功。

主线这一步不先等待当前回复已经保存。所以后台可能先交出笔记,也可能比正文更晚完成;不能把它想成“读完用户已经看到的正文,再写总结”。

交出的具体内容、给谁用

本例的保存结果可以读成:

基于版本:12。
新内容:记录用户已递出钥匙及尚待确认的回应。
保存结果:成功,当前笔记成为版本 13。

如果这轮没有顺利走到“保存成功”,结果分别是:

这轮发生什么 留给后续使用的是什么
没必要整理,或者新稿与旧稿相同 继续使用现有状态;后台没有更新也可以是正常结果
某个专家正常返回失败说明 失败信息也可交回后续阶段;Director 仍可能根据其余材料整理并提交,不等于整轮更新一定失败
Director 失败,或它交回的状态格式无效 没有这份有效的新状态提交;已有状态不会因此自动变成新稿
保存时发现版本已经变了 这份过时稿不能覆盖较新的记录
有效、确有变化,而且保存成功 后续准备时可以读取新版本

这里说的是普通后台的状态结果。它不能单凭“工具完成了”就证明当前回复交付成功,也不会替已经交给用户的正文重新写一遍。

除了完整状态,程序还可能把本次成功专家分析作为带来源的附属记录(ledger)随有效状态提交。后续只会按规则选取其中的内容,不等于把所有工具日志都贴回模型。

版本 13 保存在这个会话的后台状态记录里,由接入方提供的存储服务负责保存。它不是改角色卡、不是改世界书,也不是自动写一张独立人物卡。

后续准备对话时,Harness 会重新读取这个记录。它不直接显示给用户,也不回头改写这一轮正文。若格式不合格或版本冲突,这份新稿就不会以本例方式成为版本 13。如果用户下一句话来得很快、后台还没存好,新一轮也可能仍读到版本 12。

查结果字段: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。两者用途不同,不能统称为“工具已更新状态”。

第 7 步 / 共 7 步

下一轮究竟怎样使用它?哪些作用已经有,哪些还没有?

保存的状态不会自己发号施令。 下一次准备回复时,Harness 重新读取状态,把已保存的状态文字和允许进入的专家记录整理成一段有长度上限的文字,再放进发给回复模型的输入。Actor 读到这段话,连同角色卡、聊天历史和这轮世界书生成回复。这就是后台结果影响后续行为的实际连接处。

收到的具体内容

假设上一轮正文正常保存,版本 13 也保存成功。用户下一句是:

我问守卫:手令该找谁开?

下一轮回复模型会有三种不同来源的材料:

来源 这次拿到的具体内容
已保存的笔记,版本 13 用户上一轮已经递出钥匙并请求开门;当时后台尚未收到守卫回应
已保存的上一轮正文历史 “守卫接住你递来的铜钥匙……‘手令呢?光有钥匙还不行。’”
本例假设再次选中的世界书条目 “手令在市政厅登记处申请……这项守门规则已告知当班守卫。”

做什么

回复模型把这些材料放到一起:不重复演一次递钥匙;承接守卫已经接收、已经要求手令的对话;根据这轮实际收到的世界书,回答办理地点。

这一轮模型实际同时面对:“用户已经递出”“历史已经写出守卫接住”“现在问手令去哪办”。旧笔记的“当时还不知道回应”,不能被当成比后来对话更新的事实。

状态中的“别替用户做决定”“可围绕通行请求推进”是发给模型的文字指导。 模型参考这些文字写回复;程序没有逐字强迫它采用,也没有验证每一条剧情约束都被遵守。

“守卫已经接收”来自刚保存的正文历史;“到市政厅办理”来自世界书。 不是版本 13 自动知道了所有新信息。

交出的具体内容、给谁用

回复模型这次可能给用户:

“市政厅登记处。”守卫看着你,“拿到盖着城主印章的手令,再来找我。”

如果这一轮后台也运行,它现在可以从已保存的上一轮正文里读到“守卫接住钥匙、要求手令”,据此更新旧笔记中的待确认内容。但本例后台仍没有自动获得这轮选给回复模型的世界书原文,不能仅凭旧笔记声称已经知道办理地点。

看完这条链路,可以明确当前实现的边界: 世界书给当前回复补设定;后台状态给后续回复保留连续性和软建议;保存的聊天原文提供人物实际说了什么。普通后台还没有自动读本轮新回复和同批世界书、再对本轮正文完成全面审查的闭环;也没有仅靠一次人物专家调用,就自动创建可独立编辑的 NPC(故事配角)小卡。这些如果是产品目标,还需要额外接线,不能由工具名推定已经完成。

技术对应、示例范围与固定代码依据

固定源码:13c481bf8be04560940d4362f9ceced12ab57011。角色、对话、世界书原文、具体模型选择和回复均为教学编写,不是运行日志。笔记展示的是业务节选;真正提交仍需完整状态格式。

真实场景文件为 config/scenarios/agentic-v2-worldbook.json:配置普通 Actor、普通 Agentic V2、worldbook hybrid/2400 token budget;memorySources: [];未配置 Compact、Story、图片或前台工具循环。六专家与 Director 的 ModelConfig 均已配置,默认 enabledTools 包含六专家及 Director;本例只是其中一次选择两个专家,不是把可用菜单缩成两个。场景文件存在不等于当前生产环境已启用。

本文叫法 对应实现
回复模型 Actor
后台分工模型 Orchestrator
检查人物的模型 judge_npc
检查知识的模型 audit_knowledge
整理笔记的模型 Director,经 update_director_state 调用
旧笔记 / 候选笔记 Agentic RP State;投影中也可能包含已有 ledger
检查旧版本再保存 compare-and-set / CAS

模型给出的是 function tool calls。例如人物任务单可表现为:

{
  "id": "call_npc",
  "type": "function",
  "function": {
    "name": "judge_npc",
    "arguments": "{\"reason\":\"老相识守卫正在参与钥匙交接,需要检查人物与动作是否接得上。\",\"focus\":\"保持同一人物,承认用户已递出,不提前替守卫接收或开门。\"}"
  }
}

专家返回 ok/tool/result 等字段。第二阶段协调器获得 assistant 工具调用记录及对应的 role:tool 结果,只能从提供的菜单中选择 Director;程序强制规则也可能补 Director。当前普通应用没有开启严格参数 schema 校验,不能把教学任务单的规整格式理解为执行器保证所有模型参数都有效。

依据:

Harness 是负责送材料、启动模型、执行工具和保存结果的程序。

故事、材料和模型输出是教学示例,非线上实测。处理方式依据 main 13c481b 的“普通 Agentic+世界书”;例子从聊天中途开始。角色名在第 1 步解释,Director 在第 5 步展开;参数含义放在对应步骤,源码收在最后的展开项内。

原技术关系图 ↗ · 对应正文第 24 章 ↗