人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载ironclaw_host_api是 IronClaw一个聚焦隐私、安全与可扩展性的 Agent OS中全工作区共享的权威词汇层它描述跨越所有特权边界的事物——身份、作用域、路径、挂载、能力、动作、决策、审批、密封的Authorized见证与CapabilityDispatcher端口、净化后的解析与失败词汇、进出站描述符、运行时与信任词汇以及完整的规范 turn 词汇——但不执行其中任何一项。这篇指南以该 crate 的规范工作规则文档AGENTS.md为主体结合其 README.md 与源码实现讲解它的边界纪律、六条工作规则、两个关键陷阱、密封证据机制以及本地验证方法帮助你在该仓库中正确命名权威类型、规避常见误用。一、先定位这个 crate 是什么以及为什么它必须零依赖1.1 契约层家族中的地基ironclaw_host_api位于crates/contracts/家族全部 6 个契约 crate 之一是整套系统的词汇层全家族只描述跨越权威、宿主或产品边界的概念不执行、不持久化、不做决策。家族规则crates/contracts/AGENTS.md给出了类型入驻此层的四部分录取测试它命名了一个跨越权威、宿主或产品边界的概念它对厂商、运行时、存储和部署保持中立两个或更多消费者需要它且无需导入所有者它不携带执行、持久化、策略引擎或工作流。对于依赖倒置端口两个消费者是声明方调用者与实现方所有者——一个调用方 crate 加一个实现方 crate 的端口通过这种分离正是端口的意义而调用方与实现方同属一个 crate 的端口不通过。从依赖矩阵看该家族处于contracts substrates runtimes kernel loops products app层级的最底层向下没有任何依赖——往下是死路本家族即地板。这正是ironclaw_host_api被称为整个系统零依赖权威词汇的原因。1.2 为什么零内部依赖是安全属性而非风格偏好README 明示约 53 个工作区 manifest 依赖此 crate可在仓库根目录复现grep -rl ^ironclaw_host_api --includeCargo.toml crates tests Cargo.toml | wc -l几乎覆盖每个家族。因此ironclaw_host_api的零内部依赖姿态就是整个系统的安全属性任何添加在此处的依赖都会变成整个系统的依赖。对应的强制执行门是ironclaw_architecture_tests中的reborn_crate_dependency_boundaries_hold见 crates/app/ironclaw_architecture_tests。与其配套的还有一系列不变式无框架/驱动依赖——不允许 axum/hyper/tower/reqwest/tonic、libsql/rusqlite/sqlx、wasmtime 等reborn_contracts_crates_hold_no_framework_dependencies尺寸上限——每个契约 crate 有生产行数上限由显式评审才能提高reborn_contracts_crates_carry_a_checked_size_ceiling无通配符再导出——仅模块限定导入规则写在 src/lib.rs。从 Cargo.toml 看其实际依赖全部是通用基础设施serde、serde_json、uuid、chrono、thiserror、tracing、sha2、zeroize、rust_decimal、async-trait以及唯一可选特性test-supportdep:jsonschema——这是仅开发期的接缝用于编译共享的TestDispatcher双倍实现与消息契约一致性辅助任何发布产物都不会启用。二、从哪里开始面向贡献者的上手路径工作规则文档AGENTS.md给出清晰的起点先读 README了解 crate 是什么再读 Cargo.toml看清真实的依赖与特性形状注意test-support特性只在cargo test或明确开启时生效。契约文档优先于直觉——在改变任何行为之前必须查阅三份冻结契约文档docs/internal/reborn/contracts/host-api.mddocs/internal/reborn/contracts/kernel-boundary.mddocs/internal/reborn/contracts/capability-access.md契约与代码冲突时停止不要静默地顺手修正行为而应把任务当作一次契约变更请求来处理——这正是契约高于实现的纪律体现。此外README.md 还给出使用边界需要扩展表面时去ironclaw_extension_contracts产品膜或线上 DTO 去ironclaw_product_contracts循环端口去ironclaw_loop_contracts任何需要执行、持久化或记录日志的东西去上层的所有者 crate。三、六条工作规则词汇层的行为边界3.1 只拥有共享权威词汇行为保持在类型自身形状上本 crate 只保留类型自身形状上的校验/序列化辅助不包含运行时执行、持久化、HTTP 客户端、策略引擎或产品工作流也不得依赖任何其他ironclaw_*crate。这条规则由reborn_crate_dependency_boundaries_hold断言强制执行——如前所述这是整套系统的安全属性。在 src/lib.rs 的文档注释中可看到明确声明本 crate 有意只包含承载权威的类型、校验与序列化契约运行时行为属于 system-service cratefilesystem、resources、extensions、WASM、MCP、auth、network、kernel。3.2 能力表面策略是中立的可见性词汇capability_surface模块拥有CapabilitySurfacePolicy及其能力 ID 作用域代数见 src/capability_surface.rs。关键纪律策略只收窄模型可见的能力绝不授予调度权威解析与强制执行仍然留在ironclaw_loop_host与ironclaw_host_runtime策略默认失败关闭CapabilityIdScope默认是Only(空集)即不显示任何能力 IDallow_all()才开放全部运行时与效果种类Wasm/Mcp/Script/Sandbox/FirstParty/System以及 ReadFilesystem、WriteFilesystem、Network、UseSecret、ExecuteCode、SpawnProcess、DispatchCapability、ModifyExtension、ModifyApproval、ModifyBudget、ExternalWrite、Financial 等效果。源码提供了allow_only、narrow_to_capability_ids、deny_capability_ids、without_approval_gated等组合算子并在intersect/without中实现了Only与AllExcept两种作用域的归并代数——例如两个Only求交集、Only与AllExcept合并后收窄为Only、两个AllExcept合并后取并集。测试断言了默认策略失败关闭、allow_only 再 deny 归并为一个作用域、无审批门控后不再渲染可询问能力等行为。3.3turn是完整规范语言不是部分语言如果某个 crate 需要命名一个 turn——作用域、ID、引用、状态、门种类、事件游标、起源适配器——它就应该依赖本 crate绝不要依赖ironclaw_turns。当 turn 类型必须在 turn 内核之外被命名时答案是把它移到这里而不是从ironclaw_turns再导出。这在 src/turn.rs 模块头部有完整说明ironclaw_turns拥有协调、准入、调度、持久化与状态转换而本模块拥有这些服务、产品表面与通道适配器之间交换的完整稳定语言——类型化 ID 与引用、turn 作用域/参与者/所有者、运行状态及其门对应、事件游标、运行起源适配器身份、净化后的失败/取消形状。turn模块的实打实内容包括见 src/turn.rs类型化 ID 家族TurnId、TurnRunId、CapabilityActivityId、TurnCheckpointId、TurnLeaseToken、TurnRunnerId、EventCursor单调位置用于投影与投递交接的断点续读均为基于Uuid的 newtype有界引用宏bounded_ref!与loop_ref!前者校验非空、≤256 字节、无控制字符后者额外要求前缀exit:、msg:、result:、gate:TurnScope/TurnActor/TurnOwnerturn 的作用域、参与者与所有者词汇个人Personal{user}与共享代理SharedAgent{agent,project}以及product_owner、to_resource_scope等推导辅助TurnStatus状态机Queued、Running、五种Blocked*Approval/Auth/Resource/DependentRun/ExternalTool、CancelRequested、Cancelled、Completed、Failed、RecoveryRequired并提供is_terminal、is_blocked、keeps_active_lock谓词BlockedExternalTool是非终态、保持活动锁的特殊状态模型调用了调用方声明的外部工具运行被暂停并交还控制权给 API 客户端GateKind权威对应表每类阻塞状态唯一对应一种门种类from_status/blocked_status是添加一种门 编译器强制在此处编辑的单点对应关系BlockedReason是其携带数据的形态Auth门还携带凭证要求净化失败词汇SanitizedFailure类别必须是蛇形小写 ASCII细节字段可被public_projection()剥离、SanitizedCancelReason、ModelInvalidOutputDetailReason九种固定安全摘要 512 字节上限 纯 ASCII 校验产品上下文ProductTurnContextTurnOriginKindWebUi/Inbound/ScheduledTriggerTurnSurfaceTypeDirect/ChannelRunOriginAdapter1..512 字节有界适配器名channel_context通道侧第三方文本仅作咨询execution_policy无人值守执行的主机密封限制与SubmitTurnResponse::Accepted携带 turn_id、run_id、状态、解析出的运行画像、事件游标、已接受消息引用。turn.rs内置测试还验证了TurnGateRef仅做有界校验而LoopGateRef做前缀校验的对比、RunOriginAdapter在 512 字节边界上的接受/拒绝、旧 JSON 的无损加载与序列化省略规则等。3.4 无通配符再导出模块限定导入lib.rs只暴露模块绝不暴露扁平的 prelude消费者必须写成ironclaw_host_api::module::Type例如scope::ExecutionContext、ids::ExtensionId。crate 根唯一的条目是Timestamp别名pub type Timestamp chrono::DateTimechrono::Utc。理由很务实按模块粒度的 glob 再导出会隐藏消费者到底依赖哪个模块——而这正是将来把某个词汇族从本 crate 切分出去时需要看清的东西。源码注释明确警告不要在这里重新加入按模块的 glob 再导出。3.5 HTTP 入口契约只含路由/策略词汇监听器绑定、路由器挂载、认证执行、作用域提取、请求体/速率限制、CORS/Origin 校验、审计发射与效果分发全部属于宿主组合与传输层例如ironclaw_host_ingress、webui transport不属于本 crate。本 crate 的ingress/http模块只承载描述性词汇路由/策略/监听器描述符与RuntimeHttpEgress端口。3.6 可序列化 API 类型的三条红线与一个例外可序列化 API 类型不得包含裸HostPath、机密secrets、后端特定错误细节——无论是在错误、事件、快照、日志还是文档中。唯一狭窄例外是有界的ModelDiagnostic生产者必须先擦除凭证值并围栏注入形状的文本才能携带模型恢复所需的原因。这体现了模型可见内容必须净化的一致设计哲学与SanitizedFailure::public_projection()剥离细节的行为一脉相承。3.7 其他规则host-port 目录、强类型优先、编辑范围Host-port 目录新的 host-port 常量必须添加到host_port::default_host_port_catalog里、常量名的旁边——而不是在某个内核调用方里。目录只是校验辅助不是权威来源。强类型优先形状已知时优先使用强枚举/newtype 而非字符串。编辑范围除非契约明确要求修改相邻 crate否则把改动保持在本 crate 内部。四、两个关键陷阱类型混淆与薄授权令牌4.1TurnGateRef、ids::GateRef与LoopGateRef是三种不同的类型这是文档列出的第一个也是最重要的陷阱类型职责校验turn::TurnGateRef面向循环的路由引用bounded_ref!仅非空、≤256 字节、无控制字符loop_ref!(..., gate:)生成的LoopGateRef带前缀校验的循环门引用必须以gate:开头后缀仅限 ASCII 字母/数字/_/-/.ids::GateRef不透明的 uuidGateRecord键无前缀概念关键纪律生产环境铸造gate:approval-{id}/gate:auth-{id}is_auth_gate_ref之类的谓词按此前缀匹配——但前缀只是约定类型本身并不强制。因此不要修复传无前缀值的调用方或测试夹具不要未经迁移所有已持久化引用就收紧构造函数二者互不为别名任何 crate 都不得把其中一个再别名为另一个的名字。src/turn.rs 的测试turn_gate_ref_is_bounded_only_unlike_the_prefix_validated_loop_gate_ref直接验证了这一对比gate-alpha、custom-auth-gate、approval:missing、gate:auth-1都是合法的TurnGateRef而LoopGateRef::new(gate-alpha)必须失败空串、257 字节、含控制字符的TurnGateRef也必须失败。4.2HostPortGrant是有意保持薄的作用域视图授权令牌HostPortGrant是包裹HostPortId的薄作用域视图授权令牌。文档明确禁止给它添加衰减attenuation/作用域/过期字段——如果将来需要这类行为应引入一个独立的、带衰减的授权类型而不是扩大这个线上形状。五、密封证据不要扩大验证边界5.1 两个唯一实现者与一个禁令不要实现HostProtocolAuthenticator或ChannelIngressVerifier也不要添加第三个授权类型。每个 trait恰好允许一个生产实现者ironclaw_webuibearer/session信任阶段 T1和ironclaw_extension_hostchannel/webhookT2。这由reborn_sealed_evidence_mint_ratchet固定因为第二个实现者可以为未经认证的请求伪造已验证声明。5.2 见证令牌模式编译器半与测试半授权类型与authorized::AuthorizationGrant使用同样的见证令牌模式字段对本 crate 私有提供的 trait 方法体是唯一来源覆盖实现无法构造一个实例。保持它们非Clone/ 非Default/ 非Deserialize。这构成结构屏障私有字段 授权门控构造而 companion 的ironclaw_architecture_tests测试把impl CapabilityAuthorizer限制在 kernel crate——即类型密封 测试密封双保险。这一点在 src/authorized.rs 有完整实现Authorized::seal消费AuthorizationGrant零尺寸见证其唯一构造函数是CapabilityAuthorizer::authorization_grantAuthorized是一次性、绑定运行通道、有截止期限的密封证明——字段私有、不可Clone、dispatch()消费它、is_expired超过截止期限即失败关闭、未分发的见证走abort()显式释放资源预留绝不使用Drop因为析构器不做异步 I/O泄漏的见证由租约过期回收。seal还会校验描述符能力 ID 与调用能力 ID 一致不匹配则返回AuthorizedSealError::CapabilityMismatch。5.3 测试接缝与特性门的历史教训需要已验证证据的测试使用ProtocolAuthEvidence::test_verifiedtest-support接缝必须持有授权的测试双倍放到tests/目录下如 tests/authorized_seal.rs——绝不放在内联#[cfg(test)]模块里因为棘轮ratchet按生产代码扫描内联模块。这取代了旧的host-auth-mintcargo 特性。不要在此处重新引入特性门cargo 会在一次构建中统一特性一个消费者的 opt-in 会在整个工作区重新打开该特性。六、验证本地检查与边界门文档给出的验证路径分三层对应cargo命令# 快速本地检查本 crate 测试套件 cargo test -p ironclaw_host_api # 依赖或 API 变更后边界 / 密封 / 上限门 cargo test -p ironclaw_architecture_tests第三层是调用方层测试优先当辅助函数为调度、持久化、网络、机密、审批、资源、事件或进程副作用设门时优先写调用方层测试而不是在本 crate 内写行为测试。README.md 的 Tests 一节给出了同样的两条命令并补充说明test-support特性是 dev-only 接缝共享TestDispatcher双倍与消息一致性辅助从不被发布产物启用。从实现证据看本 crate 的测试面相当完整tests/下有authorized_seal.rs、host_api_contract.rs、model_result_preview_contract.rs、protocol_auth_evidence_seal.rs四个集成测试文件turn.rs、capability_surface.rs等模块内置大量单元测试覆盖线上形状的序列化往返、失败关闭默认值、旧 JSON 兼容加载等契约细节。此外Cargo.toml的 dev-dependencies 无条件编译 32 个规范 JSON Schema 文件schemas/messaging/*.json以确认它们是合法的 draft-07 JSON Schema保证纯cargo test -p ironclaw_host_api不带--features test-support也能运行该套件。七、总结这套规则的深层逻辑把 AGENTS.md 的规则串联起来可以看到一条清晰的安全主线零依赖→ 全工作区共享词汇而不引入传递依赖风险只命名、不执行→ 权威类型与机制实现彻底分离任何执行、持久化、网络行为都留在上层所有者 crate密封证据→ 唯一的授权铸造路径被编译器半 测试半双保险锁定伪造一个已验证声明在结构上不可能净化输出→ 一切可能到达模型或外界的序列化类型都经过擦除与围栏单一权威对应→ 门种类、状态、前缀约定、host-port 目录都收敛到单点定义避免分散的 match 表漂移。对于在 IronClaw 仓库中工作的开发者这份文档的实际价值在于当需要命名一个权威、身份或 turn 概念时先问自己它是否符合四部分录取测试当它属于本 crate 时严格遵守零依赖、无 prelude、密封铸造与净化序列化四条红线当契约与代码冲突时把它当作契约变更请求而非顺手修复。这样ironclaw_host_api才能持续扮演整个 Agent OS 的安全词汇地基角色。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐应对DevDocs资源瓶颈多维度存储优化与性能调优方案应对DevDocs资源瓶颈多维度存储优化与性能调优方案 随着开发者在DevDocs中安装的文档集不断增加本地存储资源瓶颈逐渐显现。当用户同时加载多个大型文档人工智能AI 应用交互助手AI Agent如何快速上手dzakwan-MoE-4x7b-Beta从安装到首次推理的完整指南如何快速上手dzakwan MoE 4x7b Beta从安装到首次推理的完整指南 想要快速上手强大的dzakwan MoE 4x7b Beta混合专家模型吗人工智能AI 应用交互助手AI Agent深入解析gte-base-zh-openmindBERT微调技术与文本嵌入模型完整指南深入解析gte base zh openmindBERT微调技术与文本嵌入模型完整指南 gte base zh openmind是一个基于BERT架构的中文文人工智能AI 应用交互助手AI Agent上一篇Ramalama 项目使用教程下一篇为什么选择WebGui终极轻量级Web端IMGUI解决方案的优势分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考