IronClaw 对话绑定层解析:外部会话到规范线程的幂等入站编排端口
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 三元组
-
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):
- 信任分类:根据
BindingResolutionPolicy(Untrusted/Trusted{kind})推导ConversationInboundClassification——TrustedTrigger仅当可信提交缝以TrustedInboundKind::Trigger构造请求时可达。分类永远从类型化的信任策略推导,绝不复用适配器种类字符串(untrusted_trigger_adapter_records_product_inbound_not_scheduled_trigger规则钉死这一点:一个名叫"trigger"的非可信适配器也必须归类为Untrusted)。 - 路由到表面类型:
route_kind == Direct→TurnSurfaceType::Direct,Shared→Channel。 - 重放检查:用
AcceptedConversationMessageLookup查replay_accepted_inbound_message,命中即进入submit_or_replay——同一外部事件重复投递直接重放已存储的提交结果,不重复创建绑定与消息。 - 绑定解析:非可信路径调用
resolve_or_create_binding,可信路径调用resolve_or_create_binding_with_trusted_scope(并强制把请求中的requested_agent_id/requested_project_id置为None——信任范围只来自宿主)。 - 消息接受:用解析出的
tenant_id、thread_id、actor、两个绑定引用组装AcceptConversationMessageRequest调accept_inbound_message,得到幂等状态。 - 提交或重放(
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 的规范工作规则文件)把幂等拆成两个独立事实:
- 消息接受幂等:适配器重试必须复用已接受的
message_ref、规范参与者、原始接收时间戳与原始运行配置文件请求,直到消息被标记为已提交——即使接受后实时配对状态发生了变化; - 提交幂等:提交后到达的重复投递重放已存储的提交结果(
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:
- 接收已密封的
TrustedTriggerSubmitRequest(铸造权在触发器 worker,不在本公开工厂); - 解包为
TrustedInboundTurnRequest(TrustedInboundKind::Trigger+ 可信 agent/project/owner + 执行策略); - 走
handle_inbound_turn_with_trusted_scope的完整编排; - 产出
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_runnerruntime.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 钉死的四条架构边界(均有架构测试):
- 无
ironclaw_turns普通依赖、无协调器句柄:WS5 端口反转关掉了层矩阵例外,由reborn_crate_dependency_boundaries_hold与层矩阵钉死; - 无
ironclaw_safety依赖:可信触发器提示扫描在ironclaw_triggers铸造侧执行,缺位由本 crate 的BoundaryRule(reborn_dependency_boundaries.rs)钉死; - 无
ironclaw_threads依赖:会话内容永不落在此处,同一BoundaryRule钉死; - 不与
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 明确列出了四个邻居文件:
- ironclaw_threads/AGENTS.md —— 会话记录的拥有者;
- ironclaw_extension_contracts/CLAUDE.md —— 声明本 crate 绑定所依赖的外部参与者/会话引用对;
- conversation_turn_submitter.rs —— 提交端口的生产实现(
TurnError→ 端口错误的总映射 + 原样保留协调器渲染原因); - ironclaw_turns/AGENTS.md —— 仅作背景,无普通依赖。
家族层边界见 domains/AGENTS.md,设计记录(端口反转历史)见 families/domains.md 与 PROPOSAL §6.4.2。
小结
ironclaw_conversations 是 IronClaw 中"外部世界与回合内核"之间小而精的边界:它以三个服务 trait 完成绑定解析、参与者配对与消息接受,以 ConversationTurnSubmitter 单方法端口保持对回合内核的依赖倒置,以类型化错误锥与三态重试类实现可靠的重试/重放语义,以 stored_refs 双拼写语法保证持久化记录的前后兼容,并用一整套架构测试把依赖边界、命名边界与信任边界永久钉死。对任何想要扩展新渠道或新增入站路径的开发者而言,理解这条边界就是理解 IronClaw 入站消息的第一课。