IronClaw 会话绑定与入站编排:ironclaw_conversations 适配器安全边界的架构设计与实现

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

IronClaw 会话绑定与入站编排:ironclaw_conversations 适配器安全边界的架构设计与实现

ironclaw_conversations 是 IronClaw(一个聚焦隐私、安全与可扩展性的 Agent OS)中"渠道适配器与回合(Turn)提交之间"的适配器安全边界:它负责把外部参与者/会话标识解析为规范的租户/线程/绑定引用、强制入站消息的幂等语义,并拥有进入回合协调器的唯一端口。本文以该 crate 的规范工作规则文档(CLAUDE.md)为主体骨架,结合其源码、依赖清单、契约测试与架构测试,深入拆解绑定身份、路由语义、提交幂等性、端口反转与持久化语法等核心设计,帮助你理解在 IronClaw 中接入一个新渠道(Slack/Telegram/Web/CLI)时,入站消息从"外部事件"到"规范回合提交"的完整信任边界是如何被约束的。

一、定位:它不是 transcript,而是"绑定"的所有者

在展开规则之前,必须先明确这个 crate 在 IronClaw 家族中的位置。根据 README.md 的定位描述:

它是产品/渠道适配器与回合提交之间的适配器安全边界:解析外部参与者/会话标识为规范的租户/线程/绑定引用,强制入站幂等性,并拥有入站编排触达回合协调器所需的单方法端口。它不是 transcript——ironclaw_threads 拥有规范线程和消息内容;本 crate 拥有的是"从外部会话到某个规范线程的绑定(binding)"。

这段话是理解整个 crate 的钥匙。源码层面,lib.rs 的模块级文档给出了同样清晰的边界:

  • 它不持有回合协调器(TurnCoordinator)。入站编排通过 ConversationTurnSubmitter 端口(声明于 src/turn_submission.rs)触达真正的协调器,由 ironclaw_composition 实现,因此本 crate 只讲 ironclaw_host_api::turn 的词汇加上自己的类型。
  • 它不解析具体的 Slack/Telegram/Web/CLI 载荷。产品/渠道适配器必须先完成协议载荷的规范化,再调用这些服务。
  • 它不持久化原始的用户/助手消息内容。回合面向的记录里只有内容/消息引用(content/message refs),可持久化的 transcript 内容属于 ironclaw_threads 的 SessionThreadService(transcript 存储边界),永远不会进入本 crate 的存储。
  • 曾经两边共享过五个类型名(包括两边各有一个同签名 accept_inbound_message 的 SessionThreadService),因此这里所有类型都拼写为 …Conversation…(InboundConversationService、AcceptedConversationMessage、ConversationMessageRecord 等),并由架构测试 reborn_conversations_threads_attachments.rs 强制任何新共享类型名直接失败。

依赖关系上,Cargo.toml 显示的正式依赖只有 ironclaw_extension_contracts、ironclaw_filesystem、ironclaw_host_api、ironclaw_triggers(消费——从不铸造——可信提交绑定);ironclaw_turns 仅是 dev-dependency,注释明确写着"生产代码不再命名回合内核"。消费方(3 个):ironclaw_assistant、ironclaw_composition、ironclaw_extension_host。

二、所有权边界:什么属于这个 crate,什么必须离开

CLAUDE.md 的 Ownership boundary 是全部规则的出发点,可归纳为四条:

  1. 只拥有适配器安全的会话绑定与入站回合服务契约:source/reply 绑定引用、参与者检查、消息接受引用、幂等语义,以及外部引用的持久化语法(stored_refs)。
  2. 不解析具体渠道载荷(由产品/渠道适配器在调用前规范化)。
  3. 不持久化面向回合记录的原始用户/助手消息内容,只使用内容/消息引用。
  4. 外部引用对(ExternalActorRef / ExternalConversationRef)只在 ironclaw_extension_contracts::external 声明一次——在这里再声明任何一方都会使 reborn_conversations_threads_attachments.rs 失败,任何与 ironclaw_threads 共享的新类型名也同样失败。

这一点在 lib.rs 的导出处体现得淋漓尽致:ExternalActorRef / ExternalConversationRef 被刻意不重新导出,消费方必须从 ironclaw_extension_contracts::external 导入,从而保证本 crate 永远不会成为渠道词汇的第二导入路径(由规则 reborn_extension_contract_location_scan 强制)。

回合提交的输入保持规范形态:TurnScope、TurnActor、AcceptedMessageRef、SourceBindingRef、ReplyTargetBindingRef 一律从 ironclaw_host_api::turn 导入(lib.rs 中 pub use ids::{...} 与 pub use traits::{...} 清晰列出了这套公共面),绝不允许通过回合内核的重导出进入本 crate。

三、绑定与路由身份:(space_id, conversation_id, topic_id) 与命名陷阱

3.1 绑定解析必须 fail closed

工作规则要求:绑定解析对以下情形必须失败关闭(fail closed):

  • 未配对的参与者(unpaired actors);
  • 未知/不可访问的线程;
  • 无效引用;
  • 参与者策略拒绝;
  • 租户/适配器安装不匹配;
  • 类似分隔符的外部 ID——如果被扁平化成字符串可能发生碰撞。

这对应 traits.rs 中 ConversationBindingService 的 resolve_or_create_binding / lookup_binding / reset_conversation_binding / link_conversation_to_thread 等方法签名——它们全部返回 Result<_, InboundTurnError>,其中 InboundTurnError::BindingRequired、AccessDenied、BindingConflict 等错误变体就是这些失败条件的类型化投影。

3.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:写入已发布的拼写,读取两种拼写)。

源码层面,ids.rs 中的 ExternalConversationIdentity 就是这个"路由投影":它只保留 space_id + conversation_id + topic_id,刻意去掉每事件的 reply_target_message_id。其测试 route_identity_drops_the_reply_target_but_keeps_the_topic 直接验证:带 reply target 的引用与不带 reply target 的引用产生相同的路由身份,而 topic 不同则身份不同。

3.3 两种绑定引用与路由校验

  • Source binding ref 与 reply target binding ref 是两种不同的东西。出口(egress)路径在发送前必须针对当前外部参与者/线程校验 reply target,并完整保留适配器种类(adapter kind)、适配器安装(adapter installation)以及全部外部路由字段。
  • 回复路由是所有者作用域的:严格限定在精确的外部参与者配对键,除非适配器显式把路由标记为 shared/group。共享标记只能把已有路由从 direct 拓宽为 shared,不能反向缩窄,也不能凭空拓宽。
  • 被接受的入站消息必须快照消息作用域的 reply target 与路由访问策略:稳定的会话绑定会忽略并剥离每消息 ID,但"已接受消息的出口路由"必须保留它们;新的入站写入则使用规范的绑定级 reply ref,而不是旧的消息作用域回复快照。
  • 混合引用拒绝:已接受的入站消息写入必须拒绝"不属于同一租户/线程绑定的混合 source/reply 绑定引用",也必须拒绝"稳定身份与绑定不一致的外部路由快照"。

这些语义在类型上落地为 types.rs 的 ValidateReplyTargetRequest / ReplyTargetBinding / ResolveStoredReplyTargetRequest / StoredReplyTargetBinding / StoredReplyTargetAccess。其中 StoredReplyTargetAccess 有两个值:OrdinaryReply(普通回复可用共享路由,只要运行参与者仍是绑定线程的参与者)与 ExactOriginActor(审批/认证等权威承载型提示必须要求最初拥有路由的外部参与者仍与运行参与者配对,共享拓宽永远不够)。

3.4 首接触绑定、只读查找与显式链接

  • 自动首接触绑定不得信任适配器提供的 agent/project 作用域提示:只有通过 resolve_or_create_binding_with_trusted_scope 传入的、宿主拥有的可信作用域才能被持久化到自动绑定上(traits.rs 的方法签名同时接收 trusted_agent_id / trusted_project_id / trusted_owner_user_id)。
  • 只读查找(lookup-only)解析不得创建线程、绑定、路由拓宽、外部事件路由预留或已接受消息状态——lookup_binding 在语义上就是无副作用的。
  • 显式链接只对同一目标线程幂等:永远不得把已绑定的外部会话静默重定向到另一个线程。link_conversation_to_thread 与 reset_conversation_binding(compare-and-rotate,expected_thread_id 充当并发栅栏,types.rs 的 ResetConversationRequest)就是这一规则的实现载体。

3.5 反序列化必须复用构造器校验

规则:外部引用类型的 Serde 反序列化必须委托给与构造器相同的校验规则。ids.rs 用 bounded_string_id! 宏生成了四个有界字符串 ID(AdapterKind、AdapterInstallationId、ExternalEventId、InboundMessageContentRef),其共享校验 validate_external_id 明确三条规则:

  • 非空;
  • 最多 512 字节;
  • 不得包含 NUL 或控制字符。

每个类型的 Deserialize 都先反序列化为 String 再走 Self::new 校验,保证手工编辑或损坏的持久化记录无法把未校验的标识符偷渡回内存。

3.6 未来持久化绑定仓库的设计约束

工作规则对未来的持久化绑定仓库给出前瞻性约束:避免对外部路由字段使用原始宽复合唯一索引,改用"类型化行 + 由长度前缀组件派生的抗碰撞摘要/间接键"。这是对"把外部 ID 扁平化为字符串"类碰撞隐患的架构级预防。

四、幂等性与回合提交:两条独立的幂等轴

这是本 crate 最核心的运行时行为。工作规则首先划清两条互相独立的幂等性:

  1. 已接受消息(accepted-message)幂等性:适配器重试必须复用已接受的消息引用、规范参与者、原始接收时间戳与原始 run-profile 请求,直到消息被标记为已提交——即使实时配对状态在接受到提交之间发生了变化。
  2. 回合提交(turn-submission)幂等性:提交完成后的重复投递,直接重放已存储的提交结果。

4.1 事件 ID 预留与路由漂移拒绝

规则要求在解析期间预留安装级(installation-wide)的外部事件 ID,并在创建第二个线程之前拒绝路由漂移(route drift)。对于瞬时回合提交失败,每次重试都轮换提交幂等键(submit idempotency key),这样 turn-store 的重放不会使消息搁浅(strand)。

4.2 RejectedBusy 是终态

线程繁忙(thread-busy)对用户消息的准入是终态 RejectedBusy(permanent):适配器不要"重试直到提交";RejectedBusy 之后的重复投递重放终态结果而不再重新提交,所有永久拒绝都保留原始的提交幂等键。

4.3 类型化的 TurnSubmissionError:retry() / category() / adapter_status_code()

工作规则要求保留 ConversationTurnSubmitter 端口返回的类型化 TurnSubmissionError,而不是把回合失败扁平化为字符串。调用方必须分支在它的 retry() 类上,并用 category() / adapter_status_code() 做投影,绝不能从渲染后的消息文本重新推导这两者。

src/turn_submission.rs 给出了完整定义:

  • TurnSubmissionRetry(重试/幂等键三分法):
    • RetryableAfterKeyRotation:瞬时失败,下次尝试前必须轮换提交幂等键;
    • RetryableWithSameKey:瞬时失败,复用同一提交幂等键让 turn-store 去重;
    • Permanent:永久失败,绝不轮换键——永久拒绝的重复重试必须持续重放同一终态结果。
  • TurnSubmissionErrorCategory(八类):ThreadBusy、AdmissionRejected、ScopeNotFound、Unauthorized、InvalidRequest、Unavailable、Conflict、CapacityExceeded。
  • adapter_status_code() 由 category 唯一派生(不能漂移):ThreadBusy/Conflict→409,AdmissionRejected/CapacityExceeded→429,ScopeNotFound→404,Unauthorized→403,InvalidRequest→400,Unavailable→503。该映射有单元测试 adapter_status_code_is_derived_from_category_for_every_category 逐一钉死。
  • detail 是来源失败自身的渲染文本,原样保留(测试 rendered_cause_is_preserved_verbatim 验证)。

4.4 端口反转:声明在下层,实现在上层

ironclaw_conversations 拥有入站编排(已接受消息幂等、绑定解析、重放、提交键轮换),但运行它不能依赖回合内核。编排只在一个调用点(submit_or_replay 内的 submit_turn)触达协调器,因此这个调用点被声明为单方法端口 ConversationTurnSubmitter(turn_submission.rs 的 #[async_trait] pub trait ConversationTurnSubmitter),由 ironclaw_composition 在真正的 TurnCoordinator 句柄之上实现。这是典型的依赖反转:声明在下层,实现在上层(WS5 端口反转,2026-08-04)。

实现位于 crates/app/ironclaw_composition/src/automation/conversation_turn_submitter.rs:CoordinatorTurnSubmitter 把 ConversationTurnSubmission 组装成 SubmitTurnRequest(入站提交从不请求模型/运行 ID/父运行,subagent_depth 固定为 0,产品上下文由分类而非适配器身份解析),并把 TurnError 以无通配符分支的全映射投影到端口词汇上——其中 Conflict 同时横跨可重试(TurnError::Conflict)与永久(LeaseMismatch / InvalidTransition / RunNotRetryable)两类,这正证明了 retry() 类不能从 category 推导、必须由端口独立携带。

4.5 入站编排的完整流水线

src/inbound.rs 的 InboundTurnService::handle_inbound_turn 展示了端到端流程:

  1. 用 AcceptedConversationMessageLookup(租户 + 适配器种类 + 安装 + 外部参与者/会话引用 + 外部事件 ID)尝试 replay_accepted_inbound_message——命中则直接进入 submit_or_replay 重放;
  2. 未命中则按策略解析绑定:非可信路径走 resolve_or_create_binding(保留适配器请求的 scope 提示),可信路径走 resolve_or_create_binding_with_trusted_scope(忽略适配器提示、采用宿主可信作用域);
  3. accept_inbound_message 持久化接受记录;
  4. submit_or_replay 检查重复消息是否已有提交结果;否则取幂等键、经 ConversationTurnSubmitter 提交;若失败且 should_rotate_submit_key(即 RetryableAfterKeyRotation),先 rotate_inbound_message_turn_submission_key 再返回错误;成功则 mark_inbound_message_turn_submitted。

契约测试 tests/inbound_contract.rs 验证了完整路径:paired_actor_without_binding_creates_thread_binding_message_and_submits_turn(配对参与者 + 无绑定 → 创建线程绑定 + 接受 + 提交)、untrusted_inbound_uses_untrusted_binding_resolution_and_preserves_requested_scope_hints(非可信路径保留 scope 提示)、unpaired_external_actor_returns_binding_required_before_message_or_turn_submission(未配对 → 在产生任何消息或提交前返回 BindingRequired)等。

五、可信触发器提交接缝:安全扫描后移到铸造端

工作规则有一条重要的安全历史:不要在本 crate 扫描可信触发器提示,也不要重新引入 ironclaw_safety 依赖。原因记录在文档中:直到 2026-08-04,conversations 拥有的 TrustedTriggerFireSubmitter 会自己重跑注入扫描;因为它只存在于接缝的某一个实现里,替换或新增 submitter 会静默丢掉这道防线。PROPOSAL §6.4.2 把扫描移到接缝之后:ironclaw_triggers 在铸造密封的 TrustedTriggerSubmitRequest 时运行扫描,因此到达本 crate 的请求已经通过检查。缺失依赖由本 crate 的 BoundaryRule(reborn_dependency_boundaries.rs)钉死。

源码侧,inbound.rs 的 trusted_trigger_fire_submitter 工厂只负责接线,可信权威存在于 ironclaw_triggers 拥有的密封请求构造器中。入站编排用类型化的 ConversationInboundClassification(三态:TrustedTrigger / TrustedOther / Untrusted)表达信任决策,绝不从 adapter-kind 字符串重新推导 trigger 性——这就是 untrusted_trigger_adapter_records_product_inbound_not_scheduled_trigger 钉死的:一个 adapter 字面名叫 "trigger" 的非可信入站,仍必须归类为 Untrusted,且 ScheduledTrigger 产品 origin 只能从 TrustedTrigger 到达。

另一个值得注意的细节(源码注释中的 Issue #5505):可信触发器触发必须请求专用的 scheduled_trigger run profile,以便宿主 deny-map(ironclaw_turn_runner runtime.rs)从触发回合对模型可见的表面上剥离 trigger 变更能力——一个触发不能创建/移除/暂停/恢复触发器。相关测试 submit_trusted_trigger_fire_surfaces_creator_as_explicit_turn_scope_owner 断言了 run profile 与执行策略(如 allowed_capability_ids)确实到达了协调器。

六、持久化适配器:ScopedFilesystem 上的状态存储与 stored_refs 语法

6.1 持久化范围与物理布局

本 crate 的持久化严格限制在:会话绑定、已接受消息幂等、回合提交状态存储记录,载体是 ScopedFilesystem;transcript 内容与线程存储留在各自所属的存储边界。未来任何持久化扩展都必须先声明作用域存储边界、让原始消息内容远离回合面向的行,并补充带迁移覆盖的后端对齐测试。

src/conversation_state_store.rs 展示了物理实现:ConversationStateStore 在 /conversations 挂载别名下持久化 InMemoryState 单例,磁盘布局是单个 JSON blob:

/conversations/state.json
  • 路径是别名相对的,每次操作都由 ScopedFilesystem 针对调用方提供的 MountView 解析别名,并在后端分发前强制按授权(ACL)执行;
  • 租户隔离是结构性的:组合层把别名接到租户/用户作用域的 VirtualPath 上,两个基于不同 MountView、但共享同一 RootFilesystem 的服务互相看不见对方的状态,store 本身不在路径里编码 tenant_id/user_id;
  • 状态修订双轨跟踪:持久化记录上的 revision 延续 ConversationStateRepository 契约(save_state(expected_revision, state)),底层文件系统返回的 RecordVersion 则用作写 CAS 的 CasExpectation;不支持版本化 put 的后端回退到 CasExpectation::Any,依赖调用方(InMemoryConversationServices::mutation_lock)的进程内串行化;
  • CAS 最多重试 5 次(FILESYSTEM_CAS_RETRIES),与 secrets / processes / run-state 存储一致。

6.2 stored_refs:持久化语法比塑造它的类型活得更久

src/stored_refs.rs 的模块文档提出了一个深刻的原则:记录语法(record grammar)比塑造它的类型活得更久。已发布版本写入的是 {space_id, conversation_id, thread_id, message_id};规范类型把后两个字段命名为 topic_id / reply_target_message_id。这个适配器在线上保持已发布语法,读入时接受两种拼写:

  • 写侧:Written 结构把 topic_id 写为 thread_id、把 reply_target_message_id 写为 message_id(为了可回滚);
  • 读侧:Read 结构用 #[serde(alias = "topic_id")] 与 #[serde(alias = "reply_target_message_id")] 同时接受新旧拼写,并重新走 ExternalConversationRef::new 校验,杜绝损坏记录偷渡。

为什么写侧如此重要?因为每个被重命名的字段都是 Option——Serde 遇到缺失的 Option 会填 None 而不报错,所以任一方向的拼写不匹配都是静默的:读者会看到一个没有 topic 的路由,于是所有线程化回复都塌缩到会话根。这种塌缩比路由错误更糟,它是有损的:ExternalConversationIdentity 是 BindingKey 的键,StoredConversationState::into_state 用 Vec<(K,V)>::into_iter().collect() 重建绑定映射,两个都丢了 topic 的线程化绑定会变成同一个键,后写入者静默胜出。

同时,双写两种拼写是被拒绝的:#[serde(alias)] 让"同时接受两种拼写的读者"拒绝携带重复字段的文档——歧义记录必须失败关闭,而不是让字段顺序挑选赢家。测试 a_record_carrying_both_spellings_is_rejected 直接验证这一点;legacy_conversation_record_keeps_its_topic_and_reply_target 与 canonically_spelled_conversation_record_still_loads 分别验证升级与中间版本读取路径。

另外,ExternalActorRef 的变更({kind,id} → {kind,id,display_name})是纯增量的,因此不需要 actor 适配器:新增字段在双向都安全(Serde 默认忽略未知字段,缺失 Option 读为 None),且其规范序列化已通过 ExternalActorRef::new 重新校验——测试 actor_serde_needs_no_adapter 用断言而不是口头声明钉死了这个等价性。

最后注意:48 小时的 DELIVERED_GATE_ROUTE_TTL 只用于愈合指纹格式变更(记录在同一 CHECKLIST 行上),与这里的字段重命名无关——绑定身份是持久化的,不会老化淘汰。

七、验证与测试:三组命令

工作规则给出的验证路径(全部可在当前仓库直接运行):

# 快速本地检查
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
  • inbound_contract 是对入站编排行为的契约级验证(见 4.5 的用例);conversation_state_store_contract 覆盖持久化存储的契约,包括后端对齐与迁移覆盖的约定。
  • 架构测试层(crates/app/ironclaw_architecture_tests/tests)承载了多个不变量钉死:reborn_conversations_threads_attachments.rs(类型名共享禁令、外部引用对单一归属)、reborn_dependency_boundaries.rs(无 ironclaw_turns 正式依赖、无 ironclaw_safety 依赖、无 ironclaw_threads 依赖)、以及 conversation_trusted_trigger_submitter_stays_conversation_or_composition_owned / untrusted_ingress_paths_cannot_submit_host_trusted_inbound(可信触发器提交者归属与不可信入站路径禁令)。
  • 值得强调的是测试中的假件(fakes)设计:因为 ironclaw_turns 只是 dev-dependency,测试假件站在 composition 适配器的位置上、铸造与真实适配器完全相同的 SubmitTurnRequest(含 product_context::resolve_inbound),这让 untrusted_trigger_adapter_records_product_inbound_not_scheduled_trigger 等运行来源守卫能对"实际到达协调器的精确值"断言,而不是对它的转述断言。

八、修改行为前必读的邻居

工作规则列出了四个"邻居",改动本 crate 行为前应当先读:

结语

ironclaw_conversations 的全部设计可以浓缩为一句话:渠道世界(外部参与者、会话、事件 ID、路由)与内核世界(规范线程、回合、幂等键)之间的每一次转换,都必须经过一条类型化、可验证、默认拒绝的边界。绑定身份排除每消息 ID 以保持线程稳定;两条幂等轴分离以兼容适配器重试与重复投递;端口反转让下层不再依赖回合内核;可信触发器扫描后移到铸造端以消除"实现级守卫";stored_refs 的写旧读双拼写则让字段重命名对持久化存储完全透明。对任何想在 IronClaw 上新增渠道适配器、或深入理解 Agent OS 入站消息信任链的开发者而言,先吃透本文涉及的这些规则、源码与契约测试,就能在不破坏家族边界的前提下安全地扩展它。

登录后查看全文
ironclaw