人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 是一个以隐私、安全与可扩展性为核心诉求的 Agent OS。在它的架构中crates/events/ironclaw_event_log是全部运行时事实与安全审计证据的记录入口——它定义了系统里每一种可记录的事实长什么样脱敏后的RuntimeEvent与SecurityAuditEvent以及生产者通过什么 trait 记录它们尽力而为的EventSink/AuditSink与显式报错的DurableEventLog/DurableAuditLog。读完本文你将掌握该 crate 的公共 API 全貌、脱敏不变量在序列化层的强制实现、基于游标的回放语义以及它在事件族四阶段单向流水线中的边界位置与验证命令。crate 定位为什么证据词汇表必须与存储驱动分离ironclaw_event_log位于crates/events/家族包名ironclaw_event_log分层元数据为substrates见 Cargo.toml。它的核心设计是这是一个没有存储驱动的记录层。README.md 解释了这样拆分的理由它是系统中每一个生产者都需要引用的唯一中立契约只有它独立于任何数据库驱动ironclaw_event_store才能作为隔离的 crate 存在。如果证据词汇表与持久化后端选择耦合在一起那么每个生产者都会被迫编译一套它根本不会触碰的数据库与 TLS 栈。从依赖关系上看这个判断非常扎实crate 的内部依赖只有ironclaw_host_api见 Cargo.toml其余依赖全部是通用基础设施serde、serde_json、async-trait、chrono、uuid、thiserror、tracing。它被 14 个工作区 crate 消费涵盖内核capabilities、approvals、host_runtime、processes、循环turn_runner、hooks、领域auth、outbound、车道wasm、产品assistant、组合层以及事件族自身的 store/projections。可以在仓库根目录用如下命令复现grep -rl ^ironclaw_event_log --includeCargo.toml crates Cargo.toml在事件族四阶段流水线中的位置crates/events/AGENTS.md定义了事件族是一条单向流水线四层递进生产者发出一条脱敏事件或审计信封ironclaw_event_log的 trait 接收它ironclaw_event_store在单调游标下将其持久追加ironclaw_event_projections将日志折叠成带作用域的只读模型ironclaw_event_streams对订阅做鉴权并放行。没有任何东西能反向流动projection 不能改动它折叠出的日志stream 不能发明未经回放抵达的状态依赖箭头从 evidence → store → projection → stream 反向就是错误的。ironclaw_event_log是这条流水线的第一环它负责脱敏后的证据词汇表 记录 trait。以下内容在事件族中永不出现SSE/WebSocket 等具体传输、产品视图组装、第二个写权限、存储驱动、领域记录语法如 thread 记录、trigger 记录、以及任何形态的原始机密——这些由家族边界规则与架构测试强制执行。公共 API 面六个私有模块的扁平重导出crate 的公共表面由 src/lib.rs 从六个私有模块扁平重导出模块导出内容定位cursor.rsEventCursor、EventLogEntry、EventReplay、EventStreamKey、ReadScope游标/回放信封error.rsEventError统一错误类型in_memory.rsInMemoryEventSink、InMemoryAuditSink、InMemoryDurableEventLog、InMemoryDurableAuditLog测试与参考回路的内存后端runtime_event.rsRuntimeEvent、RuntimeEventId、RuntimeEventKind及全部 sanitize 函数脱敏运行事件词汇表security_audit.rsSecurityAuditEvent、SecurityAuditSink、SecurityBoundary、SecurityDecision及三种实现安全边界审计原语sink.rsEventSink、NonBlockingEventSink、AuditSink、DurableEventLog、DurableAuditLog、DurableEventSink、DurableAuditSink记录 trait 与桥接适配器使用边界速查何时使用本 crate你要记录一个事实派发结果、进程迁移、安全审计决策或定义可记录的事实长什么样何时不用本 crate需要构造持久化后端→ironclaw_event_store经组合层注入、需要读模型→ironclaw_event_projections、需要订阅→ironclaw_event_streams。各 crate 的分工见 README.md。RuntimeEvent脱敏运行事件词汇表事件种类枚举RuntimeEventKindruntime_event.rs以snake_case序列化覆盖运行时的完整生命周期派发路径dispatch_requested、runtime_selected、dispatch_succeeded、dispatch_failed能力活动capability_activity_requested、capability_activity_succeeded、capability_activity_failed模型调用model_started、model_completed、model_failed循环assistant_reply_finalized、loop_completed、loop_cancelled、loop_failed进程生命周期process_started、process_completed、process_failed、process_killed钩子遥测hook_dispatched、hook_decision_emitted、hook_failed恢复failure_recovered。值得注意的设计取舍审批相关的事件种类被刻意排除。审批解析属于控制平面关切以AuditEnvelopeAuditStage::ApprovalResolved的形式记录而不是作为运行时事件出现见 runtime_event.rs 的注释说明。事件结构可选字段按语义填充RuntimeEventruntime_event.rs的字段保持pub以便内存内检查但脱敏不变量在每次跨越 I/O 边界时强制执行。核心字段event_id: RuntimeEventId——由Uuid::new_v4()生成或由调用方用from_bytes从领域分离的字节构造稳定身份timestamp: Timestampchrono::Utc语义kind: RuntimeEventKindscope: ResourceScope——租户/用户/Agent/项目/任务/线程/调用上下文的完整作用域parent_invocation_id——嵌套活动时的父调用 IDcapability_id、provider: OptionExtensionId、runtime: OptionRuntimeKind、process_idoutput_bytes、duration_ms——其中duration_ms仅在新产生的模型终止事件上存在且被MAX_RUNTIME_EVENT_DURATION_MS24 小时见 runtime_event.rs封顶防止可观测性元数据变成无界墙钟计数器error_kind、error_summary——脱敏约束的核心字段一组钩子字段hook_idblake3 十六进制 64 字符、hook_point如before_capability、hook_trust_class如builtin/installed、hook_decisionallow/deny/pause_approval/pause_auth/pass/patch、hook_failure_category如timeout/panic、hook_failure_dispositionfail_closed/fail_isolated一组恢复字段recovery_stage、recovery_class、recovery_dispositionretried/model_visible。类型化构造函数事件不应手工拼装而是通过类型化构造函数创建例如// 派发请求 RuntimeEvent::dispatch_requested(scope, capability_id); // 选择运行时 RuntimeEvent::runtime_selected(scope, capability_id, provider, RuntimeKind::Wasm); // 派发成功记录输出字节数 RuntimeEvent::dispatch_succeeded(scope, capability_id, provider, runtime, output_bytes); // 派发失败error_kind 在构造时即被脱敏 RuntimeEvent::dispatch_failed(scope, capability_id, provider, runtime, wasm.host_http_denied) .with_error_summary(optional host-authored display summary); // 进程生命周期 RuntimeEvent::process_started(scope, capability_id, provider, runtime, process_id); RuntimeEvent::process_killed(scope, capability_id, provider, runtime, process_id); // 钩子遥测 RuntimeEvent::hook_dispatched(scope, capability_id, hook_id, before_capability, installed, owning_extension); RuntimeEvent::hook_decision_emitted(scope, capability_id, hook_id, deny, owning_extension); RuntimeEvent::hook_failed(scope, capability_id, hook_id, timeout, fail_closed, owning_extension); // 恢复 RuntimeEvent::failure_recovered(event_id, scope, capability_id, dispatch, timeout, retried);构造函数的每个入参都经过对应的 sanitizer详见下文脱敏不变量一节例如dispatch_failed内部即调用sanitize_error_kindruntime_event.rs。SecurityAuditEvent无自由文本负载的安全边界审计SecurityAuditEventsecurity_audit.rs是一个刻意无自由文本负载的记录它没有details、message、value或reason: String字段防止粗心的调用方把边界刚刚拒绝的机密/头部/路径塞进去。它只记录boundary: SecurityBoundary——哪个边界触发枚举定义LeakDetector泄漏检测/输出脱敏守卫、NoExposureGuard出口守卫、CredentialChannel凭证通道、AuthContinuation产品认证续接、HookDeny钩子谓词拒绝、McpDirectLeaseMCP 直连租约每个都有稳定的as_str()短 token如leak_detectordecision: SecurityDecision——决策类别Blocked、Allowed、ScopeMismatch、ReplayRejectedcode: static str——短小、稳定、snake_case 的原因码是 SRE 的 grep 目标如leak_redact_failed、no_exposure_block_header、hook_deny_predicate、auth_continuation_replay、mcp_direct_lease_deny绝不允许来自用户输入或含机密可选的capability_id与scope均为已脱敏安全的类型、timestamp。构造函数唯一入口是SecurityAuditEvent::new(boundary, decision, code)配合with_capability_id/with_scopebuilder从类型系统上杜绝自由文本注入。这个原语的由来security_audit.rs 的模块文档在多个 PR 评审中安全边界总是通过tracing::warn!/tracing::error!输出决策而仓库CLAUDE.md明确禁止对非面向用户的诊断使用warn!/info!会破坏 REPL/TUI 渲染同时LLM 数据永不删除、必须可过滤、始终保留的规则要求安全决策被留存且可按边界/决策/作用域过滤而不是只活在一条warn!日志里。配套的 sink 有三种实现security_audit.rs 起NoopSecurityAuditSink——丢弃全部事件适合测试TracingSecurityAuditSink——在tracing::debug!级别输出完整维度集boundary、decision、code、capability_id、scope选debug!而非info!/warn!正是为了不污染交互显示它负责可观测性持久化留存由组合层在旁侧装配持久 sink 提供InMemorySecurityAuditSink——内存收集供测试/参考回路使用。注意SecurityAuditSink::record是同步方法安全边界常常在同步路径谓词门、头部过滤、输出脱敏触发不应强求.await管道。双契约尽力而为的 Sink 与显式报错的 Durable Logcrate 的核心是两对 trait它们代表两种根本不同的可靠性承诺sink.rs尽力而为EventSink / AuditSinkEventSinksink.rs是异步事件 sink尽力而为的可观测性#[async_trait] pub trait EventSink: Send Sync { async fn emit(self, event: RuntimeEvent) - Result(), EventError; async fn flush(self) - Result(), EventError { Ok(()) } }文档对尽力而为调用方dispatcher、process manager、host runtime给出三条硬性纪律只在等待 sink 不会拖慢运行时工作的位置emit(...).await将返回的任何错误记录到独立的诊断通道继续执行原始的成功/失败结果——sink 失败绝不能改变运行时或控制平面的结果。flush默认是 no-op因为同步 sink 在emit返回时已持久化写后write-behindsink 覆写它以排空缓冲区优雅停机、测试。AuditSinksink.rs对控制平面审计信封AuditEnvelope给出同样的尽力而为契约sink 失败不得改变审批解析的结果。NonBlockingEventSinksink.rs是运行时关键生产者要求的更强契约try_emit必须不等待队列容量或持久 I/O 即可返回。它的存在防止普通EventSink被意外接入关键路径而静默丢弃所有事件——InMemoryEventSink即实现了该 trait。显式报错DurableEventLog / DurableAuditLogDurableEventLogsink.rs是显式报错的追加日志 traitappend(event) - ResultEventLogEntryRuntimeEvent, EventError——追加失败必须传播append_batch(events) - VecResult...——按输入顺序逐事件返回结果使部分失败精确呈现而不丢弃成功追加的前缀默认实现逐个追加以保持正确性支持合并的后端可覆写为单次往返read_after_cursor(stream, filter, after, limit) - ResultEventReplayRuntimeEvent, EventError——双层权威门槛调用方必须先验证请求的EventStreamKey与消费者授权流匹配传入的ReadScope由实现方强制执行而非调用方使项目/线程级消费者无法读到同一流中其他项目/线程的记录head_cursor(stream, after)——无默认实现的必需操作PR #3931 的 Hole 1 修复必须在调用瞬间从单一权威尾部观测点原子地读取流头绝不允许通过逐页排空直到空读来推导头——并发追加的记录会折叠进观测头并被误判为回放。事件触发订阅靠它在订阅启动时一次性快照头从而严格区分回放cursor startup_head与实时记录。DurableAuditLogsink.rs以AuditEnvelope为记录类型提供同样的语义。桥接适配器DurableEventSink / DurableAuditSinkDurableEventSinksink.rs包装Arcdyn DurableEventLog并实现EventSink——emit即log.append(event)。DurableAuditSink同理包装DurableAuditLog实现AuditSink。它们是组合层把持久日志传递给期望 live sink trait的生产者的全部桥接故事ironclaw_event_log自身不需要更多。基于游标的回放信封EventCursor单调、每流、透明EventCursorcursor.rs是#[serde(transparent)]的u64包装。要点EventCursor::origin()是0先于一切记录read_after_cursor(.., None, ..)等价于read_after_cursor(.., Some(origin()), ..)游标不是全局权威必须在服务任何回放前对照请求者的EventStreamKey校验早于最早保留记录的游标产生EventError::ReplayGap传输层因此可以请求快照/rebase而不是静默丢失历史。EventStreamKey按 (tenant, user, agent) 分区的流键EventStreamKeycursor.rs由tenant_id user_id Optionagent_id组成可从ResourceScope直接构造EventStreamKey::from_scope。游标在流内单调更深层作用域过滤project、mission、thread、process、invocation作为匹配流上的读侧过滤而非独立游标。ReadScope只收紧、不放宽的读过滤ReadScopecursor.rs携带project_id、mission_id、thread_id、process_id四个可选项。过滤语义是收紧绝不默认放行过滤器中的Some(want)只匹配对应作用域字段为Some(want)的记录记录中该字段为None不匹配任何Some(...)请求。ReadScope::any()关闭过滤仅限已持有全流权威的测试或管理/聚合路径。matches_event针对RuntimeEvent注意process_id是对照事件记录而非 scope 内部字段matches_audit针对AuditEnvelope。EventLogEntry 与 EventReplayEventLogEntryT{ cursor: EventCursor, record: T }——一条回放记录及其持久游标cursor.rsEventReplayT{ entries: VecEventLogEntryT, next_cursor: EventCursor }——有界回放响应next_cursor可直接用于下一次read_after_cursor当entries为空时next_cursor回显请求的游标消费者可干净续跑cursor.rs。为什么只允许游标回放CLAUDE.md 与 AGENTS.md 共同强调回放只能基于游标。可压缩后端必须存储显式游标不能依赖行索引——字节级的parse_jsonl/replay_jsonl辅助函数已随jsonl模块删除PROPOSAL §6.3.1 的dead exports deleted条款已执行不要重新引入字节偏移或行索引回放。这样后端可以压缩而不会破坏消费者的续跑位置。脱敏不变量构造即脱敏 序列化层双保险这是 crate 的安全边界。CLAUDE.md 的规则是脱敏感知的构造函数把不安全的错误细节折叠为Unclassified而非泄漏不得添加绕过sanitize_error_kind/sanitize_error_summary的构造函数或字段。错误种类脱敏sanitize_error_kindsanitize_error_kindruntime_event.rs只接受lower_snake_case标识符可带./:分隔符如missing_runtime_backend、wasm.host_http_denied、dispatch:timeout。拒绝任何像路径、自由文本、JWT、base64 token 或 API key 的东西空串总长超过 64 字节或任一分段超过 24 字节击破长随机 token主体含[a-z0-9_]之外字符或分隔符非[._:]首字符不是小写 ASCII 字母击破数字前缀 token、前导下划线、前导分隔符。失败值统一折叠为稳定 tokenUnclassified常量UNCLASSIFIED_ERROR_KINDruntime_event.rs。错误摘要脱敏sanitize_error_summarysanitize_error_summaryruntime_event.rs是更复杂的主机编写摘要守卫空白 →None工作区文件相关摘要 → 固定标记cant access your workspace file当摘要提及工作区文件/路径/文件系统上下文且含文件名形 token 或失败关键词或包含内部工作区文件名如AGENTS.md、.system、identity.md等含控制字符、非 ASCII、{}[]/\等字符或含access token、api key、bearer、password、secret、stack trace、traceback等禁止短语或出现机密形 tokensk-、sk-ant-、ghp_、github_pat_、glpat-、gcp-、ya29.、aiza、16 位的akia/asia前缀等→ 固定标记the tool failure details were redactedREDACTED_ERROR_SUMMARY安全摘要截断到 512 字节MAX_ERROR_SUMMARY_BYTES并在字符边界优雅截断加...。一个特例INPUT_ENCODE_HUMAN_SUMMARY来自ironclaw_host_api::dispatch作为白名单原样通过——它是主机端输入编码失败的固定人类摘要。序列化层双保险Serialize/Deserialize 重跑 sanitizerRuntimeEvent的自定义Serialize/Deserializeruntime_event.rs在每条线上重跑脱敏守卫内部 wire 结构RuntimeEventWire的into_event在入站 JSONL/wire 载荷上重跑全部 sanitizerduration_ms同时被MAX_RUNTIME_EVENT_DURATION_MS封顶自定义Serialize在发出 wire 载荷前重跑同样的守卫——即使进程内调用方直接构造结构体字段RuntimeEvent { error_kind: Some(raw), .. }也无法通过任何serde_json::to_*/ durable-logappend路径走私原始错误文本、路径或 token 形机密。此外还提供三条可信载荷入口deserialize_trusted_runtime_event、runtime_event_from_trusted_json_slice、runtime_event_from_trusted_json_strruntime_event.rs它们同样经过TrustedRuntimeEventWire的 sanitize 处理。单元测试 runtime_event.rs 起验证了这些保证工作区文件路径摘要被折叠为cant access your workspace file、bearer token leaked被折叠为脱敏标记、AKIAIOSFODNN7EXAMPLE等机密形 token 被折叠而合法的builtin.json returned invalid input原样保留。内存参考实现与错误类型InMemoryEventSink/InMemoryAuditSinkin_memory.rs——ArcMutexVec...收集供测试与现场演示InMemoryEventSink实现NonBlockingEventSinkInMemoryDurableEventLog/InMemoryDurableAuditLog——每流StreamState { next_cursor, earliest_retained, entries }的内存持久后端游标从 1 开始checked_add递增溢出返回DurableLog错误实现head_cursor的原子头读取EventErrorerror.rs——Serialize、Sink、DurableLog、ReplayGap { requested, earliest }、InvalidReplayRequest五种变体ReplayGap的错误消息明确指示消费者请求带作用域的快照/rebase。消费者级契约测试durable_log_contract.rscrates/events/ironclaw_event_log/tests/durable_log_contract.rs 是消费者级测试直接驱动公开 trait 表面而非内部辅助函数。它覆盖追加与顺序回放InMemoryDurableEventLog追加三条事件后游标依次为 1、2、3read_after_cursor从 origin 回放得到完整三跳DispatchRequested→RuntimeSelected→DispatchSucceedednext_cursor为 3next_cursor 续跑紧跟next_cursor的第二次回放返回空条目、next_cursor回显请求值干净续跑语义流键分区、ReadScope过滤、脱敏保证、尽力而为 sink 投递等其余用例。测试使用tokiodev-dependency见 Cargo.toml并构造完整的ResourceScope/AuditEnvelope验证公开契约的可操作性。依赖边界唯一的家族叶子CLAUDE.md 明确定义依赖边界内部依赖只有ironclaw_host_api——这是事件族的叶子强制 deny-list 是ironclaw_event_log的BoundaryRule位于 reborn_dependency_boundaries.rs禁止 authorization、approvals、capabilities、extension_registry、host_runtime、secrets、network、mcp、processes、resources、sandbox、wasm 等特权层分层矩阵将 crate 封顶在 substratesironclaw_filesystem与ironclaw_memory刻意未列入禁止名单crate 目前不需要它们但也未论证需要把它们加入名单——若本文档与测试冲突测试胜出文档视为过期。从crates/events/AGENTS.md还能看到整个家族的强制结构每 crate 声明layer substratesprojections 禁止链接 store/filesystemprojections 永不写由链接能力强制streams 禁止链接 event_log/event_store/filesystem存储驱动只能出现在ironclaw_event_store的私有后端模块体内。验证与测试命令# 快速本地检查本 crate 的全部测试 cargo test -p ironclaw_event_log # 依赖/API 变更后的边界检查 cargo test -p ironclaw_architecture_tests若生产持久化行为发生变化需在 store 与 fabric 侧维护 PostgreSQL 与 libSQL 对等测试当某个辅助函数把关派发、持久化、网络、机密、审批、资源、事件或进程副作用时优先编写调用方级测试而非内部单元测试。小结ironclaw_event_log用最小的公共面解决了三个环环相扣的问题脱敏构造即脱敏 序列化层双保险Unclassified兜底、分层契约尽力而为的EventSink/AuditSink与显式报错的DurableEventLog/DurableAuditLog通过DurableEventSink/DurableAuditSink桥接、可压缩回放单调每流游标 ReplayGap显式报错绝不依赖行索引。它把记录什么与存在哪里彻底解耦词汇表在 substrates存储驱动在ironclaw_event_store读模型在ironclaw_event_projections订阅在ironclaw_event_streams——一条从证据到订阅的单向流水线由此成型。生产后端选择、组合注入与投影/订阅层分别见 ironclaw_event_store、ironclaw_event_projections 与 ironclaw_event_streams以及 事件族边界文档。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 事件与审计基座 ironclaw_event_log脱敏词汇表、Sink 契约与游标式回放设计解析IronClaw 事件与审计基座 ironclaw_event_log脱敏词汇表、Sink 契约与游标式回放设计解析 导读 ironclaw_event_lo人工智能AI 应用交互助手AI AgentIronClaw 内存服务契约深度解析provider-neutral 的 MemoryService 接缝与路径/安全词汇表IronClaw 内存服务契约深度解析provider neutral 的 MemoryService 接缝与路径/安全词汇表 本文围绕 IronClaw 中人工智能AI 应用交互助手AI AgentIronClaw 扩展契约层ironclaw_extension_contracts 的词汇、边界与密封设计解析IronClaw 扩展契约层ironclaw_extension_contracts 的词汇、边界与密封设计解析 本文基于 IronClaw一个以隐私、安全人工智能AI 应用交互助手AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考