IronClaw 对话绑定层解析:外部会话到规范线程的幂等入站编排端口

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

IronClaw 对话绑定层解析:外部会话到规范线程的幂等入站编排端口

导读

本文围绕 IronClaw(Agent OS,定位隐私、安全与可扩展性)的 ironclaw_conversations crate 展开,讲解产品/渠道适配器与回合(turn)提交之间的"适配器安全边界":如何把外部参与者/会话标识解析为规范的租户/线程/绑定引用,如何保证入站消息恰好被处理一次,以及如何通过单方法端口把入站编排安全地交给回合协调器。读完本文,你将掌握该 crate 的公开 API、InboundTurnService 入站编排全流程、绑定解析与幂等重放规则、可信触发器提交链路,以及它通过 WS5 端口反转实现的依赖约束与持久化兼容语法。


一、定位:它是"绑定",不是"会话记录"

ironclaw_conversations 是整个 IronClaw 架构中适配器安全边界的承担者。它的职责可以用一句话概括:它不持有回合协调器,也不存消息正文。

  • 从产品适配器(Slack / Telegram / Web / CLI 等)看,它是入站编排唯一要面对的服务层——适配器把协议载荷规范化为 InboundTurnRequest 后调用本 crate;
  • 从回合内核(ironclaw_turns)看,本 crate 通过一个单方法端口 ConversationTurnSubmitter 触达回合协调器,绝不直接持有 TurnCoordinator 句柄;
  • 从存储边界看,会话记录(transcript)归 ironclaw_threads 所有,本 crate 只持有"外部会话 → 规范线程"的**绑定(binding)**以及入站幂等状态。

该 crate 的元信息记录在 README.md:domains 家族、substrates 层,包名为 ironclaw_conversations。在 Cargo.toml 中可以看到其依赖刻意保持最小:ironclaw_extension_contracts(外部引用类型)、ironclaw_filesystem(作用域文件系统)、ironclaw_host_api(turn 词汇)、ironclaw_triggers(消费可信提交绑定,从不铸造它)。ironclaw_turns 只是 dev-dependency——这条注释直接点明了 WS5 端口反转的历史:生产代码不再命名回合内核,测试桩才能用真实的 SubmitTurnRequest 形状顶替组合层适配器。

什么时候该用它、什么时候不该用

场景 结论
把外部会话/参与者绑定(pair)到规范线程 ✅ 使用本 crate
恰好接受一次入站消息、重放重复投递 ✅ 使用本 crate
对可信触发器提交失败做分类 ✅ 使用本 crate
需要消息内容或线程历史 ❌ 交给 ironclaw_threads
解析渠道载荷(Slack 事件、Telegram update) ❌ 交给对应渠道的扩展包
想持有 TurnCoordinator ❌ 从本 crate 拿不到——去 ironclaw_composition::automation::conversation_turn_submitter 实现或复用 ConversationTurnSubmitter 适配器

二、公开 API 面:三个服务 + 两个存储 + 一个提交端口

2.1 服务 trait 三元组

在 lib.rs 中导出,定义于 traits.rs:

  • ConversationBindingService —— 绑定解析、配对、接受。核心方法:

    • resolve_or_create_binding(request):解析既有绑定,或在不信任适配器提供的请求范围提示的前提下创建"首次接触"绑定;
    • resolve_or_create_binding_with_trusted_scope(request, trusted_agent_id, trusted_project_id, trusted_owner_user_id):应用宿主自有的默认范围(必须来自宿主配置而非适配器输入),并在首次绑定时持久化,防止后续配置变更静默改变既有外部会话的路由;
    • lookup_binding(request):只查询不创建,绝不扩大绑定状态;
    • reset_conversation_binding(request):原子地把既有外部会话旋转到新线程,且必须保留旧线程与消息历史、吊销旧投递引用、重放重复的 reset 事件 ID(默认实现返回 BindingConflict,即"默认拒绝、fail closed");
    • link_conversation_to_thread(request) / validate_reply_target(request) / resolve_stored_reply_target(request):显式链接、回复目标校验与密封回复目标重解析(默认实现同样 fail closed)。
  • ConversationActorPairingService —— 参与者配对。pair_external_actor / pair_external_actor_with_epoch / unpair_external_actor / unpair_external_actor_if_owned_by。注意语义:只持久化"已获宿主授权"的映射,不是自助扫码审批流;epoch 是提供方中立的绑定代次,本 crate 只保存与比较,其含义由产品适配器拥有。

  • InboundConversationService —— 消息接受与幂等。accept_inbound_message、replay_accepted_inbound_message、inbound_message_turn_submission、inbound_message_turn_submission_key、rotate_inbound_message_turn_submission_key、mark_inbound_message_turn_submitted。这六个方法构成消息生命周期状态机:接受 → 查重 → 取提交键 → 旋转键 → 标记已提交。

2.2 两个存储实现

  • ConversationStateStore + RebornFilesystemConversationServices:持久化实现,运行在 ScopedFilesystem 之上,见 conversation_state_store.rs。它以 /conversations 挂载别名下的单 JSON 文件 state.json 落地,租户隔离由调用方提供的 MountView 结构性保证(两个用不同 MountView 构造的服务即使共享同一 RootFilesystem 也互相看不见),并用 revision 计数器 + 文件系统 RecordVersion 双重 CAS(最多重试 5 次,常量 FILESYSTEM_CAS_RETRIES)。
  • InMemoryConversationServices:测试里真实使用的内存实现,不是桩。

2.3 单方法提交端口

turn_submission.rs 声明了本 crate 对宿主需要的唯一能力:

#[async_trait]
pub trait ConversationTurnSubmitter: Send + Sync {
    async fn submit_conversation_turn(
        &self,
        submission: ConversationTurnSubmission,
    ) -> Result<SubmitTurnResponse, TurnSubmissionError>;
}

端口声明的三件套:ConversationTurnSubmission(一次入站回合提交的完整描述)、ConversationInboundClassification(信任分类)、TurnSubmissionError(带 retry() / category() / adapter_status_code() 的类型化错误锥)。声明在本 crate,实现在组合层(ironclaw_composition,WS5 端口反转,2026-08-04)——这是"声明在下层、实现在上层"的依赖倒置。

2.4 刻意不导出的东西

ExternalActorRef / ExternalConversationRef 不在本 crate 重导出,它们的唯一归属是 ironclaw_extension_contracts::external。消费者必须从那里导入,避免本 crate 成为渠道词汇的第二条导入路径(由规则 reborn_extension_contract_location_scan 强制)。


三、核心类型:请求、决议、幂等状态

types.rs 定义了编排所用的数据类型,按功能分组:

入站请求与解析

  • InboundTurnRequest:入站编排的入口载荷,包含 tenant_id、adapter_kind、adapter_installation_id、external_actor_ref、external_conversation_ref、external_event_id、route_kind(Direct / Shared)、content_ref(内容引用,非正文)、requested_agent_id / requested_project_id、received_at、requested_run_profile。
  • ResolveConversationRequest → ConversationBindingResolution:解析请求产出 tenant_id、actor(TurnActor)、可选 binding_epoch、turn_scope(TurnScope)、source_binding_ref、reply_target_binding_ref、access(ThreadAccessDecision)。

绑定生命周期

  • ResetConversationRequest / ResetConversationOutcome:比较-旋转(expected thread 作为栅栏,防止并发/过期 reset 静默重定向无关绑定)。
  • LinkConversationRequest / LinkedConversationBinding:显式链接到目标线程。
  • ConditionalUnpairOutcome(Unpaired / AlreadyAbsent / OwnerChanged)+ ExpectedExternalActorOwner(user_id + 可选 binding_epoch):条件解绑,owner 不匹配时不动绑定。

回复目标

  • ValidateReplyTargetRequest → ReplyTargetBinding;ResolveStoredReplyTargetRequest → StoredReplyTargetBinding;StoredReplyTargetAccess(OrdinaryReply / ExactOriginActor)。权威型提示(审批、认证)要求发起路由的外部参与者仍然配对到运行参与者,共享路由拓宽永远不够。

消息接受与幂等

  • AcceptConversationMessageRequest → AcceptedConversationMessage(含 message_ref、idempotency: MessageIdempotencyStatus,Inserted / Duplicate)。
  • AcceptedConversationMessageLookup(租户 + 适配器种类/安装 + 外部参与者/会话 + 外部事件 ID)→ AcceptedConversationMessageReplay(决议 + 已接受消息)。
  • ConversationMessageRecord:接受记录(accepted + actor + 外部事件 ID + 内容引用 + 接收时间)。

响应

  • InboundTurnResponse:resolution + accepted_message + turn_submission(可选)+ replayed_turn_submission(布尔),是适配器拿到最终结果的统一形状。

四、入站编排全流程:InboundTurnService

inbound.rs 中的 InboundTurnService<B, S, C> 用三个泛型参数组合出完整编排器:B: ConversationBindingService、S: InboundConversationService、C: ConversationTurnSubmitter。公开入口是 handle_inbound_turn(request)(非可信路径),内部统一走 handle_inbound_turn_inner,加上可信路径 handle_inbound_turn_with_trusted_scope。

核心流程(handle_inbound_turn_inner):

  1. 信任分类:根据 BindingResolutionPolicy(Untrusted / Trusted{kind})推导 ConversationInboundClassification——TrustedTrigger 仅当可信提交缝以 TrustedInboundKind::Trigger 构造请求时可达。分类永远从类型化的信任策略推导,绝不复用适配器种类字符串(untrusted_trigger_adapter_records_product_inbound_not_scheduled_trigger 规则钉死这一点:一个名叫 "trigger" 的非可信适配器也必须归类为 Untrusted)。
  2. 路由到表面类型:route_kind == Direct → TurnSurfaceType::Direct,Shared → Channel。
  3. 重放检查:用 AcceptedConversationMessageLookup 查 replay_accepted_inbound_message,命中即进入 submit_or_replay——同一外部事件重复投递直接重放已存储的提交结果,不重复创建绑定与消息。
  4. 绑定解析:非可信路径调用 resolve_or_create_binding,可信路径调用 resolve_or_create_binding_with_trusted_scope(并强制把请求中的 requested_agent_id / requested_project_id 置为 None——信任范围只来自宿主)。
  5. 消息接受:用解析出的 tenant_id、thread_id、actor、两个绑定引用组装 AcceptConversationMessageRequest 调 accept_inbound_message,得到幂等状态。
  6. 提交或重放(submit_or_replay,见下)。

submit_or_replay 是幂等语义的落点:

  • 若消息为 Duplicate 且已有存储的提交响应 → 直接返回 replayed_turn_submission: true,不触碰协调器;
  • 否则取该消息的提交幂等键(inbound_message_turn_submission_key),构造 ConversationTurnSubmission 调用端口;
  • 若提交失败且 should_rotate_submit_key(error) 为真(即 RetryableAfterKeyRotation),先 rotate_inbound_message_turn_submission_key 再返回 InboundTurnError::TurnSubmissionFailed;
  • 成功后 mark_inbound_message_turn_submitted 持久化提交响应,返回 replayed_turn_submission: false。

4.1 一次入站消息的状态机

外部事件到达 → 查重(lookup) ──命中──▶ 重放已存提交响应(不重新提交)
                 │
                 ▼ 未命中
            绑定解析(可信/非可信两种策略)
                 │
                 ▼
            接受消息(Inserted / Duplicate)
                 │
                 ▼
            取提交幂等键 → 调 ConversationTurnSubmitter
                 │
                 ├─ 成功 → 标记已提交 → 返回响应
                 └─ 失败 → 需要旋转键则旋转 → 返回 TurnSubmissionFailed

五、幂等与提交键旋转:两条独立的幂等轴

AGENTS.md(本 crate 的规范工作规则文件)把幂等拆成两个独立事实:

  1. 消息接受幂等:适配器重试必须复用已接受的 message_ref、规范参与者、原始接收时间戳与原始运行配置文件请求,直到消息被标记为已提交——即使接受后实时配对状态发生了变化;
  2. 提交幂等:提交后到达的重复投递重放已存储的提交结果(inbound_message_turn_submission 返回存储的 SubmitTurnResponse)。

对瞬时提交失败,TurnSubmissionRetry 三态决定键的处理:

变体 语义 键处理
RetryableAfterKeyRotation 瞬时失败,先旋转提交幂等键再重试 旋转(防止 turn-store 重放卡死消息)
RetryableWithSameKey 瞬时失败,复用同一提交键 不旋转(turn store 靠同键去重)
Permanent 永久拒绝 绝不旋转(重复重试必须重放同一终态结果)

对用户消息的 ThreadBusy 准入拒绝是终态 RejectedBusy:适配器不得重试直到提交成功;RejectedBusy 之后的重复投递重放该终态结果而不重新提交,永久拒绝保持原始提交幂等键。


六、类型化错误锥:TurnSubmissionError

turn_submission.rs 定义了编排层只分叉的三件事:是否值得重试、是否必须先旋转键、面向适配器的分类。TurnSubmissionError 是类型化值而非扁平字符串——调用方必须分支 retry() / category(),禁止解析 Display;构造时保留实现方渲染的原始原因(detail),供服务端原样诊断(单元测试 rendered_cause_is_preserved_verbatim 验证这一点)。

TurnSubmissionErrorCategory 八个分类与 adapter_status_code() 的映射被单元测试 adapter_status_code_is_derived_from_category_for_every_category 逐项钉死:

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

外层 InboundTurnError(error.rs)则覆盖编排期失败:InvalidExternalRef、BindingRequired、AccessDenied、BindingConflict、ThreadNotFound、StatePoisoned、InvalidCanonicalRef、TurnSubmissionFailed(保留类型化端口错误,绝不平铺成字符串)、DurableState。


七、可信触发器提交链路

InboundTurnService 之外,本 crate 还导出了 trusted_trigger_fire_submitter(inbound.rs 中的工厂函数),实现 ironclaw_triggers::TrustedTriggerFireSubmitter:

  1. 接收已密封的 TrustedTriggerSubmitRequest(铸造权在触发器 worker,不在本公开工厂);
  2. 解包为 TrustedInboundTurnRequest(TrustedInboundKind::Trigger + 可信 agent/project/owner + 执行策略);
  3. 走 handle_inbound_turn_with_trusted_scope 的完整编排;
  4. 产出 TrustedTriggerFireSubmitOutcome::Accepted { run_id, submitted_at, turn_scope } 或 Replayed { original_run_id, replayed_at, thread_id }。

关键安全点:

  • 提示扫描不在这里:注入扫描在 ironclaw_triggers 铸造密封请求时执行(PROPOSAL §6.4.2 把扫描移到缝后面),因此任何提交器实现都不会漏掉守卫;本 crate 因此没有 ironclaw_safety 依赖(由 BoundaryRule 钉死);
  • 运行配置:可信触发器 fire 强制携带 RunProfileId::scheduled_trigger() 运行配置文件,让宿主 deny-map(ironclaw_turn_runner runtime.rs)从 fire 的模型可见面剥离触发器 mutator 能力——一次 fire 绝不能创建/删除/暂停/恢复触发器(Issue #5505);
  • owner 语义:可信 owner 以 ExplicitUser 出现在解析出的 TurnScope 上,但既有 Direct 路由绑定不回溯升级 owner(保持兼容,重建触发器以修复投递)。

测试 submit_trusted_trigger_fire_surfaces_creator_as_explicit_turn_scope_owner 完整演示了从 TriggerFire → 密封请求 → 提交 → 断言 scheduled_trigger 配置文件与执行策略(如 allowed_capability_ids: ["mail.list_messages"])到达持久化回合请求的全链路。


八、持久化与存储兼容:stored_refs 的双拼写语法

stored_refs.rs 是本 crate 最值得单独讲解的模块:记录语法比塑造它的类型活得更久。

  • 已发布构建把外部会话引用持久化为 {space_id, conversation_id, thread_id, message_id};
  • 规范类型把后两字段拼作 topic_id / reply_target_message_id(topic_id 是渠道的子会话——Slack 线程、Telegram topic——永远不是规范 ThreadId,这正是 WS5 消除的命名陷阱);
  • 适配器策略:写旧语法、读两种语法。写入侧用 Written { space_id, conversation_id, thread_id, message_id },读取侧用 #[serde(alias = "topic_id")] / #[serde(alias = "reply_target_message_id")] 兼容规范拼写。

为什么写侧如此重要:每个重命名字段都是 Option,serde 会把缺失的 Option 静默填为 None——任何方向的拼写错位都是静默的:读者看到一个没有 topic 的路由,每个线程回复都坍缩到会话根,且 ExternalConversationIdentity 作为 BindingKey 键,两个丢失 topic 的线程绑定会变成同一个键、后写者静默胜出。所以模块:

  • 升级(旧记录被本构建读取):由 alias 处理;
  • 回滚(本构建写入的记录被已发布二进制读取):靠写 thread_id/message_id 处理——发布版读者只认这两个字段名且无 alias,其他拼写读回 None;
  • 拒绝双拼写并存:同时携带两种拼写的记录作为重复字段被拒绝——歧义记录 fail closed,不让字段顺序挑赢家(测试 a_record_carrying_both_spellings_is_rejected);
  • 加载时重新校验:反序列化必须经 ExternalConversationRef::new 重新验证,手改/损坏的持久化记录无法把未验证的标识符带进内存(测试 stored_conversation_ref_revalidates_on_load)。

而 ExternalActorRef 的变更纯粹是增量的(发布版写 {kind,id},本构建写 {kind,id,display_name}):新增字段在两个方向都安全(serde 默认忽略未知字段、缺失 Option 读为 None),其规范序列化已通过构造函数重新校验,因此不需要 actor 适配器——测试 actor_serde_needs_no_adapter 证明了这一点,且配对查找按 (kind, id) 键控,display name 不会重新键控。

存储层面(conversation_state_store.rs):/conversations/state.json 单 JSON 文档,InMemoryState 的 HashMap 以 Vec<(K, V)> 上盘并在加载时重建;租户隔离不编码在路径中,而由 MountView 结构性保证。


九、架构约束:依赖边界与命名边界

README 的 "Invariants" 部分总结了本 crate 钉死的四条架构边界(均有架构测试):

  1. 无 ironclaw_turns 普通依赖、无协调器句柄:WS5 端口反转关掉了层矩阵例外,由 reborn_crate_dependency_boundaries_hold 与层矩阵钉死;
  2. 无 ironclaw_safety 依赖:可信触发器提示扫描在 ironclaw_triggers 铸造侧执行,缺位由本 crate 的 BoundaryRule(reborn_dependency_boundaries.rs)钉死;
  3. 无 ironclaw_threads 依赖:会话内容永不落在此处,同一 BoundaryRule 钉死;
  4. 不与 ironclaw_threads 共享任何声明类型名:外部引用对只由 ironclaw_extension_contracts 声明,二者都由 reborn_conversations_threads_attachments.rs 钉死。

命名上刻意全用 …Conversation… 前缀(InboundConversationService、AcceptedConversationMessage、ConversationMessageRecord…)——历史上有五个类型名两边共享,包括两侧同名同签名的 SessionThreadService,这就是 WS5 移除的命名陷阱的根源。

依赖关系小结:普通依赖为 ironclaw_extension_contracts、ironclaw_filesystem、ironclaw_host_api、ironclaw_triggers(消费——从不铸造——可信提交绑定);被 ironclaw_assistant、ironclaw_composition、ironclaw_extension_host 三个 crate 消费。


十、测试与验证

cargo test -p ironclaw_conversations
cargo test -p ironclaw_conversations --test conversation_state_store_contract
cargo test -p ironclaw_conversations --test inbound_contract
  • 快速本地检查:cargo test -p ironclaw_conversations;
  • 契约套件:conversation_state_store_contract(存储契约)与 inbound_contract(入站契约);
  • 依赖/API 变更后的边界检查:cargo test -p ironclaw_architecture_tests(架构测试 crate 位于 ironclaw_architecture_tests);
  • 依赖变更检查:cargo test -p ironclaw_architecture_tests 覆盖上文所有 reborn_* 规则。

值得一读的单元测试证据包括:trusted_inbound_with_real_services_creates_binding_records_message_and_replays_submission(可信入站真实服务下创建绑定、记录消息、重放提交,且断言首个提交的 product_context.origin == TurnOriginKind::ScheduledTrigger)、trusted_inbound_uses_trusted_binding_resolution_and_replays_duplicate_submission(可信绑定决议 + 重复提交重放)、classify_trusted_trigger_inbound_error_maps_retryable_backend_cases_to_opaque_backend(错误分类总映射)。


十一、修改行为前必读的邻居

AGENTS.md 明确列出了四个邻居文件:

家族层边界见 domains/AGENTS.md,设计记录(端口反转历史)见 families/domains.md 与 PROPOSAL §6.4.2。

小结

ironclaw_conversations 是 IronClaw 中"外部世界与回合内核"之间小而精的边界:它以三个服务 trait 完成绑定解析、参与者配对与消息接受,以 ConversationTurnSubmitter 单方法端口保持对回合内核的依赖倒置,以类型化错误锥与三态重试类实现可靠的重试/重放语义,以 stored_refs 双拼写语法保证持久化记录的前后兼容,并用一整套架构测试把依赖边界、命名边界与信任边界永久钉死。对任何想要扩展新渠道或新增入站路径的开发者而言,理解这条边界就是理解 IronClaw 入站消息的第一课。

登录后查看全文
ironclaw