IronClaw 入站对话编排与绑定边界:ironclaw_conversations 的适配器安全层、幂等语义与端口反转设计

原创2026-09-22 11:15:571,655 阅读
文章标签:人工智能AI Agent交互助手本地部署Agent 沙箱MCP ClientsAI 技能AI 插件后端认证鉴权CLI前端

IronClaw 入站对话编排与绑定边界:ironclaw_conversations 的适配器安全层、幂等语义与端口反转设计

导读

ironclaw_conversations 是 IronClaw 中位于产品/渠道适配器与回合提交(turn submission)之间的适配器安全边界:它把 Slack、Telegram、Web、CLI 等渠道的外部参与者/会话标识解析为规范的 tenant/thread/binding 引用,强制入站消息幂等,并通过一个单方法端口把入站编排送入回合协调器。读完本文,你将掌握该 crate 的职责边界、绑定与路由身份规则、双层幂等模型、TurnSubmissionError 类型化错误锥、WS5 端口反转的动机,以及如何运行它的测试与契约套件。

一、Crate 定位:它是“绑定层”,不是“会话记录层”

ironclaw_conversations 位于 domains 家族、substrates 分层(见 Cargo.toml 中的 layer = "substrates")。它的核心定位可以用一句话概括:

它拥有从“外部会话”到“规范线程”的绑定(binding),而不是会话本身的内容。

ironclaw_threads 拥有规范线程与消息内容(SessionThreadService / transcript 存储边界);本 crate 只拥有 binding 与入站幂等。这一区分在 lib.rs 的模块文档中被反复强调,且是 2026-08-05 规则整合时特意修正过的一处历史错误:旧文档曾把 InboundConversationService 误标为 transcript 存储边界,实际上它是本 crate 的绑定/接收服务,而 transcript 服务是 ironclaw_threads 的 SessionThreadService(WS5 重命名已纠正此表述,见 AGENTS.md)。

何时使用 / 何时不使用

根据 README.md:

  • 使用场景:把外部会话/参与者绑定(pairing)到规范线程、恰好一次地接收入站消息、重放重复投递、对 trusted-trigger 提交失败进行分类。
  • 不要使用:需要消息内容或线程历史时请用 ironclaw_threads;需要解析渠道原始载荷时请用对应渠道的扩展包;需要持有 TurnCoordinator 时——本 crate 不持有它,请实现或复用 ironclaw_composition::automation::conversation_turn_submitter。

二、公共表面(Public surface)

本 crate 的公共 API 集中在 lib.rs 的重导出中,主要分为四组:

类别 类型 说明
服务 trait ConversationBindingService、ConversationActorPairingService、InboundConversationService 绑定解析、参与者配对、消息接收三个契约(traits.rs)
编排服务 InboundTurnService、trusted_trigger_fire_submitter 入站编排 + 本 crate 侧的 trusted-trigger 提交器(inbound.rs)
存储 ConversationStateStore + RebornFilesystemConversationServices(持久,基于 ScopedFilesystem)、InMemoryConversationServices(真实服务,测试用,非桩) 绑定、消息幂等、提交状态三类记录
提交端口 ConversationTurnSubmitter 及 ConversationTurnSubmission、ConversationInboundClassification、TurnSubmissionError 错误锥 声明于 turn_submission.rs,由组合层实现

值得注意的刻意不导出:ExternalActorRef / ExternalConversationRef 这对类型唯一的家在 ironclaw_extension_contracts::external,本 crate 绝不成为渠道词汇的第二个导入路径(规则 reborn_extension_contract_location_scan 强制)。

依赖与被依赖

  • 正常依赖(被测量):ironclaw_extension_contracts、ironclaw_filesystem、ironclaw_host_api、ironclaw_triggers(消费——从不铸造——trusted-submission 绑定)。ironclaw_turns 是仅 dev 依赖(见 Cargo.toml 的注释),以便测试 fake 能站在真实 SubmitTurnRequest 形状上代替组合层适配器。
  • 被 3 个 crate 消费:ironclaw_assistant、ironclaw_composition、ironclaw_extension_host。

三、所有权边界:拥有什么、绝不拥有什么

AGENTS.md 的“Ownership boundary”一节明确了四条硬规则:

  1. 只拥有适配器安全的契约:source/reply binding refs、参与者检查、消息接收 refs、幂等语义、外部 ref 的持久语法(stored_refs)。
  2. 不解析具体渠道载荷:Slack/Telegram/Web/CLI 的协议载荷由 product/channel 适配器先规范化,再调用这些服务。
  3. 不在面向 turn 的记录中持久化原始消息内容:使用 content/message refs;持久 transcript 内容属于 ironclaw_threads,永远不进本 crate 的存储。
  4. 外部 ref 对只声明于 ironclaw_extension_contracts::external:在此处重复声明会直接导致 reborn_conversations_threads_attachments.rs 失败;任何与 ironclaw_threads 共享的新类型名也一样(reborn_conversations_threads_attachments.rs 就是这道边界闸门)。

此外,turn 提交输入必须保持规范形状:TurnScope、TurnActor、AcceptedMessageRef、SourceBindingRef、ReplyTargetBindingRef 一律从 ironclaw_host_api::turn 导入,绝不经过 turn 内核的再导出。

四、绑定与路由身份:fail-closed 与稳定三元组

4.1 解析必须 fail-closed

绑定解析在以下任一情况下都必须默认拒绝(fail closed,AGENTS.md):

  • 未配对的参与者(unpaired actors);
  • 未知/不可访问的线程;
  • 非法 refs;
  • 参与者策略拒绝;
  • tenant / 适配器安装不匹配;
  • 若被扁平化为字符串可能发生碰撞的“分隔符相似”外部 ID(delimiter-like external IDs)。

4.2 绑定身份排除消息级 ID:绑定在稳定三元组上

会话绑定身份排除逐消息的外部 ID,而是绑定在稳定的 (space_id, conversation_id, topic_id) 路由身份上,这样包含消息 ID 的适配器不会 fork 出重复的规范线程。关键命名语义:

  • topic_id 是渠道的子会话(Slack thread、Telegram topic),永远不是 ironclaw_host_api::ids::ThreadId——这正是 WS5 移除的命名陷阱;
  • 本 crate 中的 thread_id 指规范线程,但有一个刻意的例外:持久记录语法仍把路由的 topic 拼写为 thread_id,以便回滚版本能读到它(见 stored_refs,它写入已发布的拼写、读取两种拼写)。

4.3 source ref 与 reply target ref 必须区分

  • source binding ref 与 reply target binding ref 是两类不同的东西;
  • 出站路径在发送前必须针对当前外部 actor/thread 校验 reply target,保留 adapter kind、adapter installation 与完整外部路由字段;
  • 回复路由是 owner-scoped 的:除非适配器显式标记为 shared/group,否则只对精确的外部 actor 配对键可见;shared 标记只能把既有路由从 direct 拓宽为 shared,不能反向。

4.4 消息级快照 vs 绑定级回复引用

  • 已接受的入站消息必须快照消息级 reply target 与路由访问策略;稳定会话绑定会忽略并剥离消息级 ID,但已接受消息的出站路由必须保留它们;
  • 新入站写入使用规范的绑定级 reply ref,而非旧的消息级回复快照;
  • 已接受的入站消息写入必须拒绝不属于同一 tenant/thread 绑定的混搭 source/reply refs,以及稳定身份与绑定不一致的外部路由快照。

4.5 Serde 与未来存储的约束

  • 外部 ref 类型的 Serde 反序列化必须委托给与构造函数相同的校验规则(stored_refs.rs 中反序列化后重新走 ExternalConversationRef::new 正是这个模式的落地);
  • 未来持久的绑定仓库应避免对外部路由字段建“原始宽复合唯一索引”,改用类型化行 + 由长度前缀组件派生的抗碰撞 digest/间接键;
  • 自动首接触绑定不得信任适配器自报的 agent/project scope 提示:只有经 resolve_or_create_binding_with_trusted_scope 传入的主机自有 trusted scope 才允许在自动绑定时持久化(traits.rs 的 doc 注释明确说明 trusted scope 必须来自主机配置而非适配器输入);
  • 仅查找(lookup-only)的绑定解析不得创建线程、绑定、路由访问拓宽、外部事件路由预留或已接受消息状态;
  • 显式链接只对同一目标线程幂等:绝不静默地把已绑定的外部会话重定向到另一线程。

五、幂等与回合提交:双层幂等 + 类型化错误锥

5.1 两个独立的幂等域

AGENTS.md 明确:接收幂等与提交幂等是两回事。

  • 适配器重试必须复用已接受的 message ref、规范 actor、原始接收时间戳与原始 run-profile 请求,直到消息被标记为 submitted——即使接受之后配对状态发生了变化;
  • 提交完成后的重复投递重放已存储的提交结果;
  • 解析期间要预留安装级的外部事件 ID,并在创建第二个线程前拒绝路由漂移;
  • 瞬态提交失败时,每次重试都要轮换 submit 幂等键,防止 turn-store 重放卡住消息;
  • 线程繁忙对用户消息的准入是终结性 RejectedBusy(永久)——适配器不要retry-until-submitted;RejectedBusy 之后的重复投递只重放终结结果而不重新提交,并且所有永久拒绝都保留原始 submit 幂等键。

在 inbound.rs 的 submit_or_replay 中可以看到这套逻辑的落点:先查 replay_accepted_inbound_message,命中则直接重放已存储的提交;否则取 inbound_message_turn_submission_key,调用 turn_submitter.submit_conversation_turn,失败时按 should_rotate_submit_key 决定是否轮换键,成功则 mark_inbound_message_turn_submitted。

5.2 保留类型化 TurnSubmissionError,而不是拍平成字符串

ConversationTurnSubmitter 端口返回类型化错误 TurnSubmissionError(turn_submission.rs),它携带两个独立事实:

重试类(retry())——编排层只分支这三个类:

类 语义
RetryableAfterKeyRotation 瞬态,且下次尝试前必须轮换 submit 幂等键,防止 turn-store 重放卡住消息
RetryableWithSameKey 瞬态,复用同一 submit 键让 turn-store 去重
Permanent 永久,绝不轮换键:重复重试必须持续重放同一终结结果

类别(category())+ HTTP 形状状态码(adapter_status_code())——adapter_status_code 由 category 单独派生,两者不会漂移:

Category HTTP 状态码
ThreadBusy / Conflict 409
AdmissionRejected / CapacityExceeded 429
ScopeNotFound 404
Unauthorized 403
InvalidRequest 400
Unavailable 503

TurnSubmissionError 还携带实现方自己渲染的 detail(来源错误的渲染文本,服务端诊断时逐字保留)。turn_submission.rs 的单元测试 adapter_status_code_is_derived_from_category_for_every_category 与 rendered_cause_is_preserved_verbatim 分别固定了完整映射表与 detail 逐字保留的约束。

5.3 WS5 端口反转:本 crate 不再触碰 turn 内核

这是本 crate 最关键的架构决定(AGENTS.md):

  • 不得在本 crate 中持有 TurnCoordinator 或任何 turn 内核句柄;
  • 入站编排通过声明于 src/turn_submission.rs 的单方法端口 ConversationTurnSubmitter 到达回合提交,由组合层(composition)实现;
  • 添加 ironclaw_turns 正常依赖会重新打开本 crate 已关闭的 layer-matrix 例外——它只允许作为 dev 依赖,让测试 fake 站在真实 SubmitTurnRequest 形状上代替适配器。

这一端口反转在 lib.rs 的文档中被概括为“declared below, implemented above”(下层声明、上层实现)。

5.4 Trusted-trigger 提示扫描已移到缝后面

本 crate 不扫描 trusted-trigger 提示,也不得重新引入 ironclaw_safety 依赖(AGENTS.md)。历史教训:2026-08-04 之前,conversations 自有的 TrustedTriggerFireSubmitter 自己重跑注入扫描;因为该扫描住在 seam 的某一个实现里,替换或新增 submitter 会悄悄丢掉这个防护。PROPOSAL §6.4.2 把扫描移到缝后面:ironclaw_triggers 在铸造密封的 TrustedTriggerSubmitRequest 时执行扫描,因此能到达本 crate 的请求必然已通过。缺失的依赖由本 crate 在 reborn_dependency_boundaries.rs 中的 BoundaryRule 钉死(reborn_dependency_boundaries.rs)。

六、组合层的端口实现:全量错误映射(源码佐证)

端口的生产实现位于 conversation_turn_submitter.rs:

  • 构造函数 conversation_turn_submitter(coordinator) 包装组合层已构造的 TurnCoordinator 句柄;
  • coordinator_submit_request 把 ConversationTurnSubmission 映射为内核 SubmitTurnRequest:入站提交从不请求模型、run id 或 parent/spawn-tree 谱系,全部保持空值;product context 由会话编排已决定的分类解析而来(product_context::resolve_inbound),绝不从适配器身份重新推导;仅 trusted-trigger 会携带 execution_policy;
  • turn_submission_error 对 TurnError 做无通配符分支的全量映射(新变体将编译失败),例如:
    • ThreadBusy → ThreadBusy / RetryableAfterKeyRotation;
    • Unavailable → Unavailable / RetryableAfterKeyRotation;
    • AdmissionRejected 按原因细分:TenantLimit/Unavailable/SystemWakeStreak 可重试(后者表示线程耗尽了自主唤醒预算、等待人工介入,不是永久拒绝),ProfileRejected/Policy/Unauthorized 永久;
    • CapacityExceeded、Conflict → RetryableWithSameKey(注意 Conflict 跨两个类:TurnError::Conflict 可重试,而 LeaseMismatch/InvalidTransition/RunNotRetryable 是永久 Conflict);
    • ScopeNotFound、Unauthorized、InvalidRequest、InvalidRunOriginAdapter → Permanent。

文件末尾的 turn_error_class_table 测试把这张表逐行钉死,证明“retry 类不能从 category 推导”——这正是端口把两个轴分开携带的原因。

七、持久化适配器:stored_refs 的持久语法

本 crate 的持久化严格限定在三类记录上,且全部基于 ScopedFilesystem(AGENTS.md):

  1. 会话绑定;
  2. 已接受消息幂等;
  3. turn 提交状态存储记录。

transcript 内容与线程存储永远留在各自的拥有边界之后。

stored_refs.rs 是其中最精巧的部分:记录语法比塑造它的类型活得更久。WS5 重命名把规范类型的外部会话路由字段改为 topic_id / reply_target_message_id,但已发布构建写的是 thread_id / message_id。因此:

  • 写入侧用发布语法:Written { space_id, conversation_id, thread_id, message_id }(把规范字段投影到旧拼写);
  • 读取侧用 #[serde(alias)] 同时接受两种拼写(thread_id 别名 topic_id、message_id 别名 reply_target_message_id);
  • 升级(旧记录被本版本读)与回滚(本版本写的记录被发布版读)都安全:发布版读器只认识 thread_id/message_id 且无别名,任何其他拼写都会读成 None;
  • 拒绝双写:同时携带两种拼写的记录是歧义的,会 fail closed 而不是让字段顺序决定胜者(测试 a_record_carrying_both_spellings_is_rejected 固定此行为);
  • 反序列化后重新走 ExternalConversationRef::new 校验,防止手工编辑或损坏的记录把未校验的标识符带进内存。

为什么写入侧与读取侧同等重要?每个重命名字段都是 Option,Serde 对缺失字段静默填 None——若拼写不匹配,线程化回复会静默塌缩到会话根,而 ExternalConversationIdentity 是 BindingKey 的键,两条同时丢失 topic 的线程化绑定会变成同一个键,后写者静默胜出,造成比误路由更糟的有损故障(stored_refs.rs 的模块文档对此有完整推演)。相比之下,ExternalActorRef 的变更纯属增量({kind,id} → {kind,id,display_name}),双向安全,因此不需要 actor 适配器,actor_serde_needs_no_adapter 测试固定了这一结论。

八、测试与验证命令

AGENTS.md 与 README.md 给出三层验证:

# 快速本地检查
cargo test -p ironclaw_conversations

# 契约套件
cargo test -p ironclaw_conversations --test conversation_state_store_contract
cargo test -p ironclaw_conversations --test inbound_contract

# 依赖/API 变更后的边界检查
cargo test -p ironclaw_architecture_tests

测试文件位于 conversation_state_store_contract.rs 与 inbound_contract.rs。此外,inbound.rs 内部的测试覆盖了 trusted inbound 的绑定创建、消息记录、重复提交重放、trusted scope 传播、绑定失败不落库、owner 显式 turn scope、direct 绑定不回溯升级 owner,以及 scheduled_trigger run profile 的强制(Issue #5505:trusted-trigger fire 必须请求专用 profile,使 ironclaw_turn_runner 的 host deny-map 剥掉触发器的 mutator 能力)。关键的 run-origin 守卫测试包括:

  • untrusted_trigger_adapter_records_product_inbound_not_scheduled_trigger——证明一个 adapter 字面名为 "trigger" 的非可信入站仍分类为 Untrusted,绝不铸造 trigger origin(分类来自类型化绑定策略,绝不从 adapter-kind 字符串重新推导,见 turn_submission.rs);
  • conversation_trusted_trigger_submitter_stays_conversation_or_composition_owned——trusted-trigger submitter 所有权保持在 conversations/composition。

九、修改行为前必读的相邻模块

AGENTS.md 列出了修改本 crate 行为前应当阅读的邻居:

结语

ironclaw_conversations 用一组小而硬的约束换来了渠道适配器的安全接入:绑定身份稳定在渠道三元组上、双层幂等把接收与提交彻底解耦、TurnSubmissionError 以类型而非字符串携带重试语义、WS5 端口反转让本 crate 不再依赖 turn 内核,而 stored_refs 的持久语法保证了重命名对存储完全透明。理解这套边界模型,是正确扩展 IronClaw 渠道生态、新增适配器或调整入站编排的第一步——仓库内的 AGENTS.md、README.md 与上文提到的各源码文件构成了完整的可追踪证据链。

登录后查看全文
ironclaw