人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw将谁发起的通信ingress identity、以什么权限执行execution authority与最终投递到哪里communication destination作为三个相互独立的概念。本契约communication-delivery-resolution定义了 Reborn 架构中用户可见通信事件的投递目标解析规则由ironclaw_outbound::OutboundPolicyService完成候选目标选择、目标再校验与投递尝试记录最终把已通过校验的目标交给产品外发路径。读完本文你将掌握候选解析的输入信封resolution envelope、OutboundPushKind投递种类语义、通知目标存储模型、确定性解析规则以及候选不等于授权的校验边界并能直接对照 delivery_resolution.rs 与 resolution_engine.rs 的源码验证每一处实现细节。1. 契约目的把投递到哪里从谁发起的中彻底解耦通信投递解析communication delivery resolution要回答的问题非常具体当 Reborn 已经决定应当尝试投递某个用户可见的通信事件之后应当优先尝试哪个外发目标outbound target。候选选择candidate selection是ironclaw_outbound::OutboundPolicyService契约的一部分。选择步骤只返回一个候选candidate only同一个外发服务边界随后会校验该目标、记录一次投递尝试并把经过校验的目标交给产品外发路径。传输transport流量完全位于选择步骤之外。本契约刻意保持三个概念的分离ingress identity入口身份一条消息、触发器或事件是如何进入系统的execution authority执行权限当前正在运行的是哪个 tenant/user/thread 作用域communication destination通信目的地最终回复、进度更新、审批提示、认证提示或投递状态通知应当尝试投递到哪里。一个容易被忽视但关键的边界是触发器事件本身的执行不依赖投递解析。触发器轮询、可信入口、turn 提交与运行持久化可以在没有外发目标的情况下照常进行只有当系统打算把外部触发器结果或另一条运行通知投递到某个产品界面product surface时才需要投递解析。2. 所有权边界谁拥有什么契约以一张所有权表划清了组件职责防止政策语言与产品行为被注入到解析器内部组件拥有不拥有ironclaw_outbound::OutboundPolicyService候选选择、目标再校验、投递尝试记录、发送前门控pre-send gating触发器执行、认证/审批状态、传输发送ironclaw_outbound::OutboundResolutionEngineOutboundPolicyService内部候选选择的可选辅助引擎公共调用方边界、目标校验权威、投递尝试记录ironclaw_conversations入口身份、来源路由绑定、回复目标绑定语义外发政策选择、产品专属回复行为ironclaw_event_projections/ironclaw_event_streams持久化事件事实、投影重建、通知/扇出界面最终外发目标选择、传输发送、发送权威ChannelAdapter实现与传输胶水外发政策批准候选后的渲染、宿主提供的传输执行通信政策选择、持久化投递状态契约强调解析器必须保持宿主所有host-owned且确定性deterministic。Channel adapter 可以描述自身能力capabilities但无权定义解析器的政策语言也无权把产品专属行为注入契约。这一点在源码中体现为 resolution_engine.rs 的OutboundResolutionEngine被声明为pub(crate)仅作为OutboundPolicyService的内部辅助存在。3. 契约不变量Contract Invariants契约定义了 8 条不可违背的不变量是理解整个解析模型安全语义的基石外发候选选择只返回一个CommunicationDeliveryCandidate候选不等于授权candidate is not authority任何发送之前候选仍必须通过OutboundPolicyService的校验解析器绝不能把入口身份、执行权限、通信目的地合并成单个字段或字符串触发器事件执行不依赖投递解析只有触发器结果的外部投递才使用本契约解析器不得编码产品专属行为例如Web UI 可以显示审批卡片Telegram 不能做门控提示能力由外发政策边界在稍后阶段评估§6 的解析规则固定且确定fixed and deterministic若选中目标不可用、被撤销、未授权或以其他方式失效系统失败关闭fail closed绝不静默回退到另一个渠道隐式回退不是解析规则的一部分未来的回退必须建模为显式的有序政策规则并配套测试。第 3 条不变量在 delivery_resolution.rs 中直接体现解析请求携带scope: TurnScope、actor: TurnActor、modality: CommunicationModality、intent: CommunicationDeliveryIntent四个独立字段目标只存在于intent分支的ReplyTargetBindingRef内没有任何一个字符串同时表达身份与目的地的通道。4. 解析输入单一类型化信封Resolution Envelope4.1 请求结构外发服务使用一个类型化解析信封这样调用方无法把无关的认证、审批或传输字段塞进请求同时实现仍保持单一公共外发 API 表面。请求结构如下源码见 delivery_resolution.rspub struct CommunicationDeliveryResolutionRequest { scope: TurnScope, actor: TurnActor, modality: CommunicationModality, intent: CommunicationDeliveryIntent, }其中scope是(tenant_id, agent_id, project_id, thread_id)的 turn 作用域actor是当前用户modality是通信模态intent是本次解析的意图分支。4.2 投递种类一个贯穿全链路的规范枚举OutboundPushKind是从解析到持久化投递尝试全链路唯一规范的投递种类枚举见 types.rspub enum OutboundPushKind { FinalReply, Progress, DeliveryStatus, GateRequired, AuthPrompt, ModelDelivery, }该枚举在序列化时使用snake_case且保留了私有 serde 别名Progress仍接受历史拼写progress_updateGateRequired仍接受approval_prompt——这保证旧持久化记录写的是progress/gate_required与新代码兼容而新写入者始终使用既有的持久化值。曾经存在过的仅用于解析的镜像枚举已被删除。4.3 意图分支显式请求 vs. 运行通知CommunicationDeliveryIntent只有两个分支pub enum CommunicationDeliveryIntent { RequestedOutbound(RequestedOutboundContext), RunNotification(RunNotificationContext), } pub struct RequestedOutboundContext { requested_target: ReplyTargetBindingRef, requested_kind: RequestedOutboundKind, } pub enum RequestedOutboundKind { ProductMessage, DeliveryStatus, }RequestedOutbound是显式命令意图explicit command intent调用方明确点名一个目标RunNotification是生命周期政策lifecycle policy覆盖最终回复、进度更新、审批提示、认证提示与投递状态通知。关键语义RequestedOutboundContext.requested_target是类型化的回复目标绑定候选ReplyTargetBindingRef不是裸渠道名、adapter 字符串、产品专属 conversation id 或传输地址RequestedOutboundKind刻意比运行通知的投递种类更窄排除审批/认证提示载荷请求式外发目标仍然只是候选任何发送前都必须在当前 scope、actor、派生的投递种类与模态下通过OutboundPolicyService校验CommunicationDeliveryResolutionRequest的投递种类由intent派生delivery_kind()调用方不得再提供一个可能与请求分支矛盾的顶层种类字段。源码中RequestedOutboundContext::delivery_kind()将ProductMessage → FinalReply、DeliveryStatus → DeliveryStatusdelivery_resolution.rs。4.4 运行通知上下文事件种类与起源pub struct RunNotificationContext { event_kind: RunNotificationEventKind, origin: RunNotificationOrigin, } pub enum RunNotificationEventKind { FinalReplyReady, ProgressUpdate, ApprovalNeeded, AuthRequired, RunBlocked, DeliveryStatus, /// 显式模型发起的投递builtin.outbound_deliver。 /// 自带 OutboundPushKind::ModelDelivery使投递尝试 /// 在持久化审计轨迹与按运行核算中保持可区分。 ModelDelivery, } pub enum RunNotificationOrigin { LiveSourceRoute { source_route: SourceRouteContext }, RunScopedTarget { target: ReplyTargetBindingRef }, SystemEventTarget { reason: SystemEventReasonCode, target: ReplyTargetBindingRef }, SystemEvent { reason: SystemEventReasonCode }, }事件种类到投递种类的映射在源码中是一一对应且被测试全覆盖的delivery_resolution.rs事件种类派生的OutboundPushKindFinalReplyReadyFinalReplyProgressUpdateProgressApprovalNeeded或RunBlockedGateRequiredAuthRequiredAuthPromptDeliveryStatusDeliveryStatusModelDeliveryModelDeliveryRunNotificationOrigin四个变体的语义LiveSourceRoute携带已验证的回复目标SourceRouteContext.reply_target_binding_ref用于从真实入站产品消息衍生、且该事件支持回复到消息来源处的活跃会话活跃会话的最终回复、进度更新、门控提示或认证提示RunScopedTarget本次运行唯一存活的按目标起源per-target origin。它逐字解析verbatim完全不触发偏好查询§5、§6。每个后台运行通知与每个显式模型投递都经过这一分支SystemEventTarget宿主起源事件 一个 owner 作用域内的密封目标例如提交前就永久失败的触发器触发。它没有 run但可投递其目标仍由OutboundPolicyService再校验稳定的事件投影引用配合turn_run_id None让重试幂等无需捏造运行状态SystemEvent纯元数据解析为无投递候选原因码仅作为投递元数据记录。契约特别澄清了历史上曾存在的偏好槽位preference slots模型没有专门的触发器通信上下文、没有按目的区分的偏好目标字段、也没有它们之间的优先级链。构造RunNotificationContext的调用方后台运行通知器或builtin.outbound_deliver工具处理器已经决定了本次通知使用的唯一目标解析器的工作只是把它原样读回作为候选。ModelDelivery的特殊约束它永远不能携带LiveSourceRoute——该起源的含义是回复到入站消息来源处即运行自身会话而显式投递指向运行自身会话会在解析运行前就被拒绝工具的 same-origin 检查。ModelDelivery总是携带模型选定的RunScopedTarget。SystemEventReasonCode是稳定、脱敏的枚举/码Generic、Trigger、Tool、Operator见 delivery_resolution.rs。人可读的后端细节、原始工具输入、提示材料、OAuth 状态、审批载荷与传输错误不会进入解析请求若产品界面需要显示文本则在目标选定并校验之后接收独立的脱敏显示载荷。4.5 解析结果pub enum CommunicationDeliveryResolution { Candidate { candidate: CommunicationDeliveryCandidate }, NoDelivery { reason: SystemEventReasonCode }, } pub struct CommunicationDeliveryCandidate { pub target: ReplyTargetBindingRef, pub kind: OutboundPushKind, }大多数意图产生具体投递候选宿主/系统事件在 P0 阶段仅元数据除非调用方显式请求外发投递因此解析为NoDelivery而非非法输入。5. 通知目标用户通信默认值存储模型注本节原名偏好字段Preference Fields。原先描述的四个按目的区分的偏好槽——final_reply_target、progress_target、approval_prompt_target、auth_prompt_target——已全部退役。现在没有任何代码再写入按目的目标投递是模型调用的工具绝不再是存储的隐式路由。用户通信默认值由ironclaw_outbound::CommunicationPreferenceRepository拥有由专门的类型化 tenant/user 数据库表CommunicationPreferenceRecord支撑。它们不存储在通用 JSON 设置存储中也不是 profile/tone 偏好。5.1 记录结构记录以 scope 为键DeliveryDefaultScope即(tenant_id, user_id)也支持SharedAgent变体携带源码见 communication_preferences.rsnotification_targets: VecOutboundDeliveryTargetId显式的、用户配置的0..8 个目录目标集合上限常量NOTIFICATION_TARGETS_CAP 8接收后台/例行运行无活跃来源路由时的门控提示、认证提示与失败通知。空集合 无外部通知路由——运行的回复仍落在自己的线程中且没有专门的应用内伪目标可配置。需要说明的是web-app目录目标浏览器推送到用户已注册设备是真实的、provider 支撑的外部目标可像任何渠道目标一样选入该集合并未重新引入已退役的应用内伪目标legacy_notification_target: OptionReplyTargetBindingRef仅作为读取迁移输入read-migration序列化时保留历史线名final_reply_target以便迁移前的行仍能反序列化没有任何代码再写它。CommunicationPreferenceRecord::effective_notification_target_ids仅在notification_targets为空时才把该旧槽折叠进通知集合见 communication_preferences.rsdefault_modality: OptionCommunicationModality。契约明确progress_target、approval_prompt_target、auth_prompt_target字段已不存在它们之间也没有优先级链OutboundResolutionEngine§6根本不读取任何存储偏好。一次运行的最终回复、进度更新、审批提示、认证提示与投递状态通知分别从活跃来源路由或调用方已选定的显式RunScopedTarget解析——绝不来自存储的按目的槽位。存储的通知目标同样只是候选。外发服务在记录投递尝试前必须再校验 tenant 所有权、目标能力、投递种类与模态。5.2 版本化写入与上限强制CommunicationPreferenceRepository使用**乐观锁CAS**语义CommunicationPreferenceVersion是不透明比较令牌读取返回、写入必须携带expected_version: None仅在行不存在时创建上限NOTIFICATION_TARGETS_CAP 8在仓库写入缝write seam强制而非Deserialize——过大的历史行必须能完整加载以便修正见 communication_preferences.rs 及测试communication_preference_record_deserializes_scoped_and_legacy_payloads。5.3 产品读写面产品面的读写均为 descriptor 支撑的 ProductSurface 能力get_notification_channels视图投影调用方生效的通知目标集合按上述规则折叠旧槽两个唯一的写入面builtin.notification_channels_set模型可调用、需审批、全量替换 CAS 写与 WebUI 通知渠道面板的产品命令——两者都进入同一个经过校验的set_notification_channels服务路径owner 作用域内 id 校验、去重、上限get_outbound_preferences/set_outbound_preferencesfacade 已随偏好槽一起删除outbound_delivery_targets仍是 descriptor 支撑的、按调用方作用域裁剪的目标清单视图。写入保持副作用性必须走能力路径。6. 解析规则直接读取而非搜索候选是对调用方提供的意图的直接读取direct read绝不是对存储回退项的搜索。OutboundResolutionEngine::resolve是对CommunicationDeliveryIntent的单一 match源码见 resolution_engine.rsRequestedOutbound逐字返回调用方显式目标候选目标即requested_target种类由requested_kind派生ProductMessage → FinalReply、DeliveryStatus → DeliveryStatus。不咨询任何其他规则RunNotification直接从origin读出目标LiveSourceRoute→ 来源路由的回复目标。只要运行源自真实入站产品消息、且该事件支持回复到来源处活跃会话的最终回复、进度更新、门控提示或认证提示即使用RunScopedTarget→ 对每种事件种类都逐字使用密封目标。后台运行的门控/认证/失败通知以及每次显式ModelDelivery都走此路——调用方在请求解析器之前已经解析出确切目标通知渠道集合中的一项或模型选定的目录目标SystemEvent→ 无候选原因码仅作为投递元数据记录不尝试外部发送。没有隐式回退链没有按目的偏好查询上述每条规则都是直接的字段读取而非搜索。如果构造请求的调用方对某事件拿不出目标它应构造SystemEvent而不是让解析器发明一个。解析器读出目标后不会继续搜索。如果返回的候选随后在校验中失败不可用、被撤销、未授权结果是失败而不是自动跳到其他渠道——由调用方决定是否以及如何用不同目标重试。这一设计与不变量 7、8 完全一致。resolve的实际实现非常直白resolution_engine.rscandidate_from_requested_outbound直接克隆requested_targetresolve_run_notification_context对四种origin变体做 match其中SystemEvent返回NoDelivery其余三种返回CommunicationDeliveryCandidate { target, kind }。7. 校验边界候选如何变成可发送目标校验与投递尝试记录仍位于ironclaw_outbound。完整流程OutboundPolicyService candidate-selection step - returns CommunicationDeliveryCandidate OutboundPolicyService - validates target and capability scope - records delivery attempt - returns validated target or rejection Channel adapter / host transport - renders through adapter and sends through host-owned transport only after validation在服务层OutboundPolicyService::prepare_communication_delivery_attempt先调用OutboundResolutionEngine::resolve得到CommunicationDeliveryResolution再通过lower_communication_delivery_resolution把候选降级为PrepareOutboundDeliveryRequest见 service.rs。降级时每个候选都被强制打上requires_reply_target_revalidation: true——解析只选候选任何被降级的候选都必须先通过回复目标校验才能被渲染或发送。若解析结果是NoDelivery则返回Ok(None)不产生任何投递尝试。真正的校验在prepare_delivery_attempt中执行validate_delivery_scope_candidate强制候选的tenant_id、agent_id、project_id、thread_id与请求 scope 完全一致validation.rsReplyTargetBindingValidator::validate_reply_target验证候选的回复目标绑定对当前 scope 仍被授权返回的ReplyTargetBindingClaim是不受信任的服务只有在确认 claim 的目标与原始候选一致无目标替换后才铸造密封的ValidatedReplyTargetBinding见 service.rs校验通过 → 记录OutboundDeliveryAttempt状态Prepared任何供应商出口之前持久化并返回AuthorizedAccessDenied→ 记录FailedAuthorizationRevoked并返回Rejected瞬态校验器错误 → 记录FailedTransientValidatorError并返回Rejectedservice.rs。校验器对候选是否仍属于当前 tenant/user/scope、目标是否支持所请求的模态与通知种类拥有最终裁决权。这也意味着prepare_delivery_attempt天然支持幂等重放——已存在的Prepared行表示记录与发送声明之间崩溃供应商出口尚未发生可安全重试而Sending及之后的状态以存储行为权威。8. 触发器投递边界触发不阻塞、结果走通信触发器循环不被外发投递解析阻塞。触发器可以触发、执行并持久化自己的 run即使尚无外部投递路径可用。当触发器结果必须外部投递时解析器把它当作通信事件处理而不是触发器权威trigger authority。触发器身份留在触发器域外发目的地选择留在ironclaw_outbound。SystemEventTargetreason: Trigger正是提交前永久失败的触发器触发这类无 run 生命周期事实的受控出口——它携带密封目标、仍走再校验并以turn_run_id None保证重试幂等。9. 非目标Non-Goals本契约不定义以下内容它们分别属于各自的契约与服务传输专属渲染transport-specific rendering产品 UI 行为订阅扇出政策subscription fan-out policy认证流程创建或回调处理参见 auth-product.md审批解析或租约语义参见 approvals.md触发器调度、轮询或执行编排参见 triggers.md。10. 关联契约与延伸阅读本契约依赖以下兄弟契约阅读时建议按依赖顺序展开events-projections.md持久化事件事实与投影重建是通知/扇出界面的数据底座conversation-binding.md入口身份、来源路由绑定与回复目标绑定语义approvals.md审批解析与租约语义本契约明确不拥有auth-product.md认证流程创建与回调处理run-state.md运行状态、turn run 持久化与生命周期。实现与测试证据集中在以下路径delivery_resolution.rs信封、意图、起源与候选的全部类型定义及 JSON 往返/映射测试resolution_engine.rsOutboundResolutionEngine::resolve的实现与逐分支解析测试communication_preferences.rsCommunicationPreferenceRecord、NOTIFICATION_TARGETS_CAP 8、版本化 CAS 写入与旧行迁移测试service.rsprepare_communication_delivery_attempt的解析→降级→校验→记录完整调用链validation.rs作用域匹配与偏好记录校验outbound_deliver.rsbuiltin.outbound_deliver工具实现ModelDelivery的模型发起入口含空内容拒绝与 same-origin 拒绝约束。结语IronClaw 的通信投递解析契约用单一类型化信封 确定性直接读取 候选/授权分离三件套解决了多渠道产品下最容易出错的投递选路问题解析器永远不猜、不搜、不回退只忠实地把调用方意图读成候选权威校验、投递尝试记录与持久化全部收敛在ironclaw_outbound一个边界内入口身份、执行权限与通信目的地自始至终是三个独立的类型。对实现者而言这意味着投递逻辑可测试、可审计、可幂等重放对架构演进而言未来的回退必须建模为显式有序政策规则并配测试这条不变量为多目标容灾留出了清晰且受控的扩展路径。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐三步完成电子课本下载tchMaterial-parser 批量下载 PDF 完整指南三步完成电子课本下载tchMaterial parser 批量下载 PDF 完整指南 tchMaterial parser 是一款面向国家中小学智慧教育平台的网页爬虫教育IronClaw 权威词汇契约深入解读 ironclaw_host_api 的架构边界与工作规则IronClaw 权威词汇契约深入解读 ironclaw_host_api 的架构边界与工作规则 导读 ironclaw_host_api 是 IronCla人工智能AI 应用交互助手AI AgentIronClaw 技能系统深度解析SKILL.md 解析、确定性选择、学习与管理全链路IronClaw 技能系统深度解析SKILL.md 解析、确定性选择、学习与管理全链路 IronClaw 是一个以隐私、安全和可扩展性为核心的 Agent O人工智能AI 应用交互助手AI Agent上一篇大麦抢票自动化指南Python 双端抢票脚本从配置到跑通下一篇DataChain高级分析功能解锁非结构化数据隐藏价值创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
