人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载ironclaw_observability是 IronClaw一个以隐私、安全与可扩展性为目标的 Agent OS中负责延迟追踪的 substrate 层组件它只提供一组覆盖ironclaw_latencytracing target 的宏与辅助函数在追踪目标关闭时零开销。本文以该 crate 的 CLAUDE.md 为骨架结合其 src/lib.rs、Cargo.toml 与七个消费方源码完整讲解公共 API、零成本关闭原理、依赖数量即契约的边界设计以及如何用两条测试守住这些不变量——读完你既能直接上手埋点也能理解这套小到用依赖列表当执行机制的架构治理思路。一、职责边界这是宏 宏需要的辅助仅此而已1.1 Charter可以用测试来检验的定位CLAUDE.md 开头用一句话定义了该 crate 的宪章charterEverything here is either a macro or a helper the macros need. 这里的一切要么是宏要么是宏需要的辅助函数。这句话被刻意写成一条可以随时套用的测试任何想加入这个 crate 的代码都必须先回答它是宏还是宏的辅助如果都不是就不属于这里。对应的目标架构条目是 PROPOSAL §6.2.5families/substrates.md。1.2 公共表面Public Surfacecrate 对外暴露的完整清单为宏live_latency_trace!、live_latency_trace_ok!、live_latency_trace_error!函数elapsed_ms、live_latency_enabled、live_latency_started_at再导出pub use tracing一个刻意的宏卫生权衡见下文Never contains明确不允许放入state状态policy策略sinks接收端/导出端最容易写错的一条一个仅仅产生某个 trace 恰好会记录的值的函数——这个测量动作属于被测量的东西的生产者不属于本 crate。文档原文强调That measurement belongs to whoever produces the thing being measured.从源码结构看src/lib.rs 是全 crate 唯一的源文件约 100 行含内联测试代码量极小这本身就是宪章的执行结果没有地方可以藏下state、policy、sinks。1.3 一个依赖整个 crate 的边界Cargo.toml 中依赖区只有一项[dependencies] # One dependency, deliberately. The macros expand to tracing; anything that # would add a second dependency here is a measurement that belongs to its # producer, not to this crate. See AGENTS.md. tracing 0.1注意publish false这是一个仅供工作区内共享的私有 crate其注释直接声明了唯一个依赖是刻意为之的立场。二、公共 API 全解三个宏与三个辅助函数2.1 核心宏live_latency_trace!最底层的宏是live_latency_trace!它只是把调用转发到tracing的trace!并固定 target 为ironclaw_latency#[macro_export] macro_rules! live_latency_trace { ($($fields:tt)*) { $crate::tracing::trace!(target: ironclaw_latency, $($fields)*) }; }关键点展开时通过$crate::tracing::trace!调用而不是裸写tracing::trace!。配合pub use tracing;lib.rs 第 13 行消费方在使用这些宏时不需要自己引入tracing依赖或use tracing这就是文档所说的宏卫生权衡macro-hygiene tradeoff宏在展开时借助$crate前缀解析到本 crate 再导出的tracing从而把对tracing的依赖完全收敛到这一个 crate 内。2.2 成功/失败语义live_latency_trace_ok! 与 live_latency_trace_error!两个带语义的宏把component、operation、elapsed_ms、outcomeok/error作为统一字段注入其中live_latency_trace_error!还额外注入error_kind#[macro_export] macro_rules! live_latency_trace_ok { ($component:expr, $operation:expr, $started_at:expr, $($fields:tt)*) { if let Some(started_at) $started_at { let elapsed_ms $crate::elapsed_ms(started_at); $crate::live_latency_trace!( component $component, operation $operation, elapsed_ms, outcome ok, $($fields)* ); } }; }两个宏都接受$started_at: OptionInstant当传入None即目标未启用时整个宏体是 no-op一行 trace 都不发。elapsed_ms是在宏内部计算的消费方无需自行计时。error变体结构相同只是多一个error_kind $error_kind字段并把outcome置为error见 lib.rs。2.3 三个辅助函数#[inline] pub fn elapsed_ms(started_at: Instant) - u64 { started_at.elapsed().as_millis().try_into().unwrap_or(u64::MAX) } #[inline] pub fn live_latency_enabled() - bool { tracing::enabled!(target: ironclaw_latency, tracing::Level::TRACE) } #[inline] pub fn live_latency_started_at() - OptionInstant { live_latency_enabled().then(Instant::now) }elapsed_ms把Instant差值换算为毫秒u128 → u64可能溢出的极端情形下饱和到u64::MAX而不是回绕原因见第五节测试。live_latency_enabled对ironclaw_latencytarget 的 TRACE 级别做tracing::enabled!静态/动态检查。live_latency_started_attarget 启用时返回Some(Instant::now())否则返回None——这是零成本关闭的入口。2.4 一个最小可用示例把上述 API 组合起来一次带语义的计时埋点长这样结合 host_runtime 的实际用法归纳use ironclaw_observability::{live_latency_enabled, live_latency_started_at, live_latency_trace_ok}; let started_at live_latency_started_at(); // 目标关闭时是 None后续零成本 // ... 执行被计时的操作 ... live_latency_trace_ok!(my_component, my_operation, started_at, key value, /* 其余自定义字段 */);成功/失败分支则分别在操作结束时调用live_latency_trace_ok!/live_latency_trace_error!失败时附上error_kind。三、零成本关闭原理以及调用方必须承担的那一半3.1 覆盖的是 trace不是 fieldslive_latency_started_at()在 target 关闭时返回None而每个宏遇到None都是 no-op——这保证了trace 的发射零成本。但文档明确划出一条边界That covers thetrace, not thefields: a caller that computes an expensive field before checking is paying for it with tracing off.也就是说如果一个调用方在检查之前就计算了一个昂贵的字段比如序列化整个 JSON 入参、统计字节数那么即使 trace 不发射这个计算成本也已经付出了。要守卫的是计算本身而不只是发射动作。3.2 守卫计算的正确姿势ironclaw_host_runtime 的形状CLAUDE.md 明确推荐参考ironclaw_host_runtime::latency::RuntimeLatencyFields::from_json_input的模式先live_latency_enabled()再测量。对应源码见 crates/kernel/ironclaw_host_runtime/src/latency.rsimpl RuntimeLatencyFields { pub(crate) fn from_json_input( capability_id: CapabilityId, scope: ResourceScope, runtime: impl IntoString, input: serde_json::Value, ) - OptionSelf { if !ironclaw_observability::live_latency_enabled() { return None; } Self::from_scope(capability_id, scope, runtime, json_value_bytes(input)) } // ... }json_value_bytes是昂贵的序列化计数因此必须先检查live_latency_enabled()再调用它字段构建完成后整体包装成OptionRuntimeLatencyFields传入trace_runtime_ok/trace_runtime_error这两个函数在fields为None时直接返回。这样目标关闭 → 不构建字段 → 不发 trace整条链路都是惰性的。3.3 生产中的完整调用链在 crates/kernel/ironclaw_host_runtime/src/production.rs 中可以看到真实用法入口处let total_started_at live_latency_started_at();、let dispatch_started_at live_latency_started_at();各取一次起点操作结束时分别走live_latency_trace_ok!/live_latency_trace_error!分支process_executor.rs 里同样是先取started_at末尾按结果选择 ok/error 宏。这是贯穿全部消费方的标准姿势早点取起点惰性晚点发 trace一次性。四、依赖数量即契约serde_json 驱逐始末4.1 一个伪装成观测助手的函数这个 crate 曾经有第二个依赖serde_json用途只有一个函数json_value_bytes——计算一个 JSON 值的序列化大小。它读起来像个观测助手但不是在ironclaw_extension_support的五个调用点中有三个是喂给ResourceUsage::set_output_bytes的——那是资源记账resource accounting而不是 trace 字段。4.2 共享它买不来任何不变量进一步分析发现共享这个函数并没有带来不变量output_bytes在生产中本就有三种不同的测量方式——上述字节计数器曾在此 crate 中output.stdout.len()在ironclaw_scriptsValue::to_string().len()在ironclaw_loop_host。原因正如文档所述每个生产者测量的是自己生产的东西each producer measures whatitproduced让所有人共享一个计数函数并不能让它们的结果一致反而给本应轻量的宏 crate 背上一个所有消费方都会继承的serde_json依赖。最终对应 WS6、PROPOSAL §12.12 D-K该函数被移到了它的两个消费者那里serde_json也随之离开。4.3 迁移后的落点与源码佐证被驱逐函数的两个消费者之一就是ironclaw_host_runtime如今它以私有函数形式存在于 crates/kernel/ironclaw_host_runtime/src/latency.rs且文档注释完整记录了这段历史Sharing the function bought no invariant and cost the latency macro crate aserde_jsondependency every one of its consumers inherited。它用JsonByteCounter实现std::io::Writesaturating_add防溢出在不物化字节的前提下统计序列化大小并约定序列化失败返回 0trace/记账字段绝不因自身失败而拖垮调用方。4.4 裁决的边界条件两份副本是上限这条裁决不是无条件的条件被明确写下来以便被检查而不是被重吵It holds attwocopies. If a third consumer needs that byte counter, the duplication argument flips and D-K should be revisited.即当前两份本地副本ironclaw_host_runtime与ironclaw_extension_support是保持现状的前提如果出现第三个需要字节计数器的消费者复制duplication论证就反转了——届时应当重新讨论 PROPOSAL §12.12 D-K既不能简单地再加第三份拷贝也不能把函数搬回ironclaw_observability。决策记录中还列出了被考虑并否决的替代归宿ironclaw_common重构正在主动收窄的 crate和ironclaw_host_api已被批评携带行为的 contracts 叶子。4.5 一句话总结这条 tripwire如果此处的一个改动需要引入第二个依赖那就说明这个新增的东西不是本 crate 的职责。依赖列表因此成为执行机制enforcement mechanism而这份文档只是解释。五、七个消费方依赖传播就是约束力5.1 消费方清单按 2026-08-05 实测共有七个 crate 依赖ironclaw_observabilityironclaw_filesystemscoped.rs 中直接use ironclaw_observability::live_latency_started_at;ironclaw_host_runtimelatency.rs、production.rs、egress/pipeline.rs、services/process_executor.rsironclaw_loop_hostlib.rs、model_gateway.rsironclaw_turn_runnerloop_driver_host.rs、turn_run_executor.rsironclaw_turnscoordinator.rs、host_managed_ports/prompt.rsironclaw_compositionruntime/latency.rs、capability_authorization.rsironclaw_extension_supportlatency.rs、coding/mod.rs5.2 为什么每个消费方都会继承依赖本身就是约束CLAUDE.md 的Consumers一节点出要害Every one of them gets whatever this crate depends on, which is the whole reason the dependency list is the enforcement mechanism and this file is only the explanation.——七个 crate 全部继承本 crate 的依赖所以任何试图往这里塞需要第二个依赖的功能的改动都会立刻被依赖图放大为七个 crate 的依赖膨胀这正是把依赖列表当作执行机制的原因。文档CLAUDE.md / AGENTS.md只是解释Cargo.toml才是机械化的宪章the manifest is the charter made mechanical。此外ironclaw_agent_loop的 executor/latency.rs 也使用了同样的target: ironclaw_latency TRACE 级别模式说明ironclaw_latency是工作区内统一的延迟追踪 target 命名约定。六、测试两条用例守住全部不变量运行方式README.mdcargo test -p ironclaw_observability # 2 tests: elapsed_ms clamps; disabled without a subscriber两条测试恰好各押住一个核心性质见 lib.rs 测试模块elapsed_ms_saturates_instead_of_wrapping验证elapsed_ms在极端时间差下饱和clamp而不是回绕wrap。注释点破了原因回绕的时长会被读成一次飞快的操作a wrapped duration reads as afastoperation这在延迟追踪里是灾难性的误报——慢操作显示成 0ms。测试构造了一个 1.5 秒前的Instant断言结果 1500同时断言刚创建的Instant计为 0。started_at_is_none_when_the_latency_target_is_off测试二进制中未安装任何 subscriber因此ironclaw_latency的 TRACE target 是关闭的——断言live_latency_enabled()为false且live_latency_started_at()为None直接验证无 subscriber 即零成本关闭这一整个 crate 存在的前提。配套地消费者侧也有对应测试守护例如 host_runtime/latency.rs 用json_value_bytes_matches_serialized_value_length验证字节计数器与serde_json::to_vec长度一致用json_byte_counter_saturates_on_write验证计数器u64饱和——两处都延续了宁可饱和、不可回绕的记账哲学。七、什么时候用它什么时候明确不用它结合 README.md 的 Use this when / Dont use this when 与 AGENTS.md 的边界说明给出决策清单应当使用任何想要live_latency_trace!风格计时的 crate——在ironclaw_latencytarget 关闭期间零成本且不需要额外引入tracing依赖宏展开走$crate再导出的 facade。明确不要用你是在产生一个 trace 恰好会记录的值字节数、大小等→ 该测量属于被测量的东西的生产者PROPOSAL §12.12 D-K就近放在自己的 crate 里你需要 sinks、exporters、state → 本 crate 中不存在这类东西去其他适合的层寻找你的改动会让本 crate 出现第二个依赖→ 先停下来读 §12.12 D-K 的历史裁决大概率这个改动不属于这里。结语ironclaw_observability用约 100 行代码示范了一种可复制的架构治理把一个依赖写成机械化的契约manifest 注释把边界故事写成可检查的文档AGENTS.md / CLAUDE.md把不变量写成两条针对性测试。它既解决了七个消费方统一延迟埋点、免去各自引入tracing的实际问题又用serde_json 驱逐案证明了——观测类 crate 最容易犯的错就是把测量误当成观测而正确的答案始终是测量属于生产者宏 crate 只负责把它记录成 trace。继续深挖可参考本 crate 的 CLAUDE.md本文依据含完整裁决叙述、AGENTS.md决策记录的规范性版本、lib.rs全部实现以及消费方代表 host_runtime/latency.rs字段守卫与字节计数器的迁移落点。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 标准消息框架解析list_members 会话成员列取的契约设计与实现IronClaw 标准消息框架解析 list_members 会话成员列取的契约设计与实现 本文以 list_members.core.md https://人工智能AI 应用交互助手AI AgentIronClaw 扩展契约层ironclaw_extension_contracts 的词汇、边界与密封设计解析IronClaw 扩展契约层ironclaw_extension_contracts 的词汇、边界与密封设计解析 本文基于 IronClaw一个以隐私、安全人工智能AI 应用交互助手AI Agent.NET Runtime cDAC 数据契约解析PlatformMetadata 契约的设计与实现.NET Runtime cDAC 数据契约解析PlatformMetadata 契约的设计与实现 导读 本文深入剖析 .NET Runtime 仓库中 cD语言运行时标准库JIT编译编译器上一篇PasteBar免费开源的跨平台剪贴板管理器彻底释放你的复制粘贴效率下一篇推荐开源项目Milligram - 极简主义的CSS框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考