人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本篇技术指南以 IronClaw 仓库内 test-tools 夹具包market-data的能力文档prompt doc为主线完整解读market-data.snp500这个 SP 500SPX行情快照工具的能力契约它何时被调用、返回什么结构、背后的 WASM 实现如何产出假数据以及它在宿主侧触发networkuse_secret义务链与密钥注入的完整机制。读完本文你将掌握 IronClaw 沙箱工具能力文档 → 输入/输出 Schema → WASM 实现 → 宿主义务管线的完整链路并能在本地构建、安装与触发该夹具工具。能力文档是什么模型侧的工具使用说明书关联文档 snp500.md 位于test-tools/market-data/prompts/market-data/目录是market-data扩展包中market-data.snp500能力的prompt doc能力文档。在 IronClaw 的扩展清单模型中每个能力都可以通过prompt_doc_ref声明一段面向 LLM 的能力描述由宿主在模型选择工具时注入上下文。这段文档正是模型判断何时该调用这个工具的依据。从 manifest 中的声明可以看到该引用关系[[capability_provider.tools.capabilities]] id market-data.snp500 description Get the current SP 500 (SPX) index snapshot — level, daily change, and percent change. Takes no arguments. ... prompt_doc_ref prompts/market-data/snp500.md也就是说manifest.toml 中的description与prompt_doc_ref共同构成了工具对模型的可观测面前者是简短摘要后者是展开后的完整行为说明。行为契约无参数、单一职责、明确的触发语义能力文档原文定义了三条核心契约返回内容当前 SP 500SPX市场快照——指数点位index level、日涨跌daily change、涨跌百分比percent change入参无参数Takes no arguments调用方不需要也不允许传入任何参数触发语义当用户询问 SP 500、SPX 或整体股票市场水平overall stock market level时使用。同时文档明确声明数据为 fixture/fake无实时行情源——这是一个测试夹具工具返回值是罐头数据而非真实市场行情。这一声明与 test-tools/README.md 中All data is canned — no fixture ever performs live egress的总体设计一致整个test-tools目录下的三个工具ascii-renderer、hacker-news、market-data都不做真实外呼network声明只是用来驱动宿主侧的义务规划器。输入/输出契约空入参与十字段快照能力文档的无参数语义在输入 Schema 中得到形式化约束。snp500.input.v1.json 是一个空对象 Schema{ $schema: https://json-schema.org/draft/2020-12/schema, title: market-data.snp500 input, type: object, properties: {}, additionalProperties: false }additionalProperties: false意味着任何多余字段都会被拒绝模型侧无法向该工具传递任何参数。输出 Schema 则定义了完整的快照结构。snp500.output.v1.json 包含 10 个字段其中 5 个为必填字段类型必填语义symbolstring✅指数代码如SPXpricenumber✅当前指数点位changenumber✅较昨收的绝对涨跌change_percentnumber✅涨跌百分比as_ofstring✅数据时间戳ISO 8601namestring—指数名称如SP 500previous_closenumber—上一交易日收盘点位day_highnumber—当日最高day_lownumber—当日最低data_sourcestring—数据源标签这套 Schema 同时被宿主用于两个目的参数校验调用前按 input schema 校验模型生成的入参与输出校验/泄露扫描返回值在沙箱出口被扫描防止秘密形数据外泄。源码实现WASM 组件如何产出固定快照能力文档描述的返回快照行为由market-data的 WASM 工具实现承担。工具源码位于 wasm-src/src/lib.rs基于wit-bindgen生成绑定实现了sandboxed-toolworld 的tool接口接口契约定义见 crates/lanes/ironclaw_wasm/wit/tool.wit。execute入口的行为与能力文档完全对应不读取任何入参_req被直接忽略构造一个固定的Snp500Snapshot快照并序列化为 JSON 返回。核心数据点let snapshot Snp500Snapshot { symbol: SPX.to_string(), name: SP 500.to_string(), price: 5_487.03, change: 12.45, change_percent: 0.23, previous_close: 5_474.58, day_high: 5_492.10, day_low: 5_468.77, as_of: 2026-06-30T20:00:00Z.to_string(), data_source: market_data_api (fake fixture data).to_string(), };数据结构定义在 wasm-src/src/types.rsSnp500Snapshot是一个Serialize派生结构体字段与输出 Schema 一一对应。可以看到快照的as_of是一个固定的历史时间戳、data_source明确标注fake fixture data与能力文档数据是 fixture/fake的声明互相印证。序列化成功返回Response::Success(output)失败则返回Response::Failure携带ErrorKind::Executor与code serialization_failed。此外工具还实现了schema()返回与 input schema 等价的空对象 JSON和description()与能力文档一致的模型侧描述。值得注意的工程细节序列化失败在 WASM 工具里几乎不可能触发固定结构体、无动态字段但实现仍然以结构化GuestFailure上报而非 panic符合 tool.wit 中guest 上报失败必须使用封闭词表closed vocabulary的error-kind且message会在沙箱出口被清洗与限长的约束——这是 IronClaw 对沙箱工具失败路径的硬性安全要求。宿主义务链network use_secret 双义务与密钥注入能力文档本身没有提安全模型但 manifest 揭示了它作为测试夹具的真正价值market-data是 test-tools 三个夹具中义务最重的一个。对照 test-tools/README.md 的工具矩阵工具Effects凭据覆盖的用例ascii-rendererdispatch_capability无纯计算无义务hacker-news network无仅出口 allowlist无密钥market-data network, use_secret租户共享market_data_api_key出口 allowlist 宿主中介密钥注入manifest 中关键声明[[capability_provider.tools.capabilities]] id market-data.snp500 effects [dispatch_capability, network, use_secret] default_permission allow origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } visibility model [[capability_provider.tools.capabilities.runtime_credentials]] handle market_data_api_key source { type secret_handle } audience { scheme https, host_pattern api.marketdata.example } target { type header, name x-api-key } required true这段声明的安全含义值得拆解use_secretruntime_credentials运行时凭据的handle market_data_api_key会触发宿主侧的InjectSecretOnce义务同时audience.host_pattern api.marketdata.example填充出口 allowlist触发ApplyNetworkPolicy义务——正如 manifest 注释所写该能力同时获得两个义务密钥永远不进入 WASM凭据target声明为 HTTP 请求头的x-api-key由宿主在 egress 边界注入。这与 tool.wit 安全模型完全一致Secrets are NEVER exposed to WASM; credentials are injected at host boundaryWASM 侧只能通过secret-exists检查秘密是否存在永远读不到值夹具不真实外呼由于返回罐头数据注入的x-api-key永远不会被真正发送密钥的存在只是为了驱动宿主义务管线pre-flight、gating、injection而不是认证任何真实服务。义务的执行逻辑在宿主侧有专门测试印证。在 crates/kernel/ironclaw_host_runtime/src/obligations/tests.rs 中market_data_api_key被构造为SecretHandle并验证了关键语义InjectSecretOnce可由管理员设置的租户共享密钥满足——测试注释明确写道 tenant-shared key satisfies InjectSecretOnce for a caller with no personal secret即个人无密钥的用户也能通过租户共享凭据获得调用资格。这正是 manifest 注释中admin installs it, provides the sharedmarket_data_api_key, and every user can use it的完整实现闭环。义务处理器本身的调度逻辑位于 obligations/handler.rs其中InjectSecretOnce与ApplyNetworkPolicy均被纳入义务管线枚举。本地安装与运行导入、密钥播种与构建作为可上传的扩展包market-data的完整使用路径如下。1. 密钥播种先于激活租户共享密钥通过环境变量或管理员 API 注入环境变量形式为IRONCLAW_REBORN_DEV_SECRET__market_data_api_keyvalue见 test-tools/README.md。未播种密钥时工具的use_secret义务会使调度被AuthRequired门控拦截。2. 打包导入将test-tools/market-data/目录打成 zip 即为可上传的 bundle通过 WebUI v2 的 Import Tool 流程POST /api/webchat/v2/extensions/import仅管理员导入。导入校验要求trust third_partycapability_providerhost_api 形状上传的 bundle 以ManifestSource::InstalledLocal校验拒绝 first_party/系统信任声明与旧式顶层[[capabilities]]manifest 声明的每个资产WASM 模块、schemas、prompt docs都必须存在于 zip 中且拒绝重复 zip 条目与非 WASM 运行时。3. 构建模块WASM 组件需要wasm32-wasip2目标该目标产出的是WASI component宿主以wasmtime::component::Component::new加载若误用wasm32-wasip1的核心模块会在调度时以 the tool manifest is invalid 失败rustup target add wasm32-wasip2 # 一次性安装 bash scripts/build-test-tools.sh market-data # 构建单个工具构建脚本会把组件产物复制到 manifest 声明的[runtime].module路径wasm/market_data_tool.wasm并产出test-tools/market-data.zip。zip 与wasm-src/target/均为 git 忽略的构建产物仓库只跟踪源码、manifest、schemas 与 prompts。4. 触发调用管理员导入并激活后任意用户向 agent 询问SP 500、SPX或整体股市水平时模型依据能力文档选择market-data.snp500宿主完成门控与密钥注入后调度 WASM返回固定快照 JSON。自动化测试保障manifest 形状被 CI 锁定test-tools的 manifest 并非一次性手写文件而是被测试锁定的契约Rust 测试套件通过include_str!内联这些 manifest 并断言其保持可导入形状见 test-tools/README.md 提到的available_extensions::tests::test_tool_fixture_manifests_stay_importable一旦 manifest 偏离合法的导入形状CI 失败而非 demo 失败。E2E 套件则构建并上传这些 bundle 走完整导入流程。这意味着 manifest.toml 中trust、effects、runtime_credentials等字段的任何改动都会受到回归保护。小结一份能力文档背后完整的安全与测试链路market-data.snp500的能力文档虽只有短短几行但它串联起了 IronClaw 沙箱工具机制的完整链路prompt doc 定义模型侧触发语义 → input/output Schema 定义参数与结果契约 → WASM 组件实现固定快照返回 → manifest 声明networkuse_secret义务与运行时凭据 → 宿主在 egress 边界注入x-api-key头 → 义务管线测试验证租户共享密钥可满足InjectSecretOnce→ CI 锁定 manifest 可导入性。对于希望理解 IronClaw能力声明 沙箱执行 宿主义务三段式架构的开发者这个夹具是一个最小但完整的可读样例。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐EmDash CMS 插件 Hooks 完全指南从沙箱声明到共享宿主管线的执行语义EmDash CMS 插件 Hooks 完全指南从沙箱声明到共享宿主管线的执行语义 导读 本文以 EmDash 插件开发技能库中的 Hooks 参考文档 htCMS后端前端插件系统IronClaw 宿主运行时ironclaw_host_runtime架构导航能力中介执行、义务三权分立与首方工具边界IronClaw 宿主运行时ironclaw_host_runtime架构导航能力中介执行、义务三权分立与首方工具边界 导读 ironclaw_host_人工智能AI 应用交互助手AI AgentOwncast 插件宿主集成深度解析WebAssembly 沙箱、HostEnv 接线与事件分发Owncast 插件宿主集成深度解析WebAssembly 沙箱、HostEnv 接线与事件分发 Owncast 是自托管直播平台服务端用 Go 编写自带音视频直播后端上一篇PUBG罗技鼠标宏自动压枪工具完全指南三步实现精准射击下一篇如何通过消息信号中断优化PCIe设备性能5个关键步骤提升系统中断处理效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw 沙箱工具能力文档解析：market-data.snp500 的声明语义、触发条件与宿主义务链
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本篇技术指南以 IronClaw 仓库内 test-tools 夹具包market-data的能力文档prompt doc为主线完整解读market-data.snp500这个 SP 500SPX行情快照工具的能力契约它何时被调用、返回什么结构、背后的 WASM 实现如何产出假数据以及它在宿主侧触发networkuse_secret义务链与密钥注入的完整机制。读完本文你将掌握 IronClaw 沙箱工具能力文档 → 输入/输出 Schema → WASM 实现 → 宿主义务管线的完整链路并能在本地构建、安装与触发该夹具工具。能力文档是什么模型侧的工具使用说明书关联文档 snp500.md 位于test-tools/market-data/prompts/market-data/目录是market-data扩展包中market-data.snp500能力的prompt doc能力文档。在 IronClaw 的扩展清单模型中每个能力都可以通过prompt_doc_ref声明一段面向 LLM 的能力描述由宿主在模型选择工具时注入上下文。这段文档正是模型判断何时该调用这个工具的依据。从 manifest 中的声明可以看到该引用关系[[capability_provider.tools.capabilities]] id market-data.snp500 description Get the current SP 500 (SPX) index snapshot — level, daily change, and percent change. Takes no arguments. ... prompt_doc_ref prompts/market-data/snp500.md也就是说manifest.toml 中的description与prompt_doc_ref共同构成了工具对模型的可观测面前者是简短摘要后者是展开后的完整行为说明。行为契约无参数、单一职责、明确的触发语义能力文档原文定义了三条核心契约返回内容当前 SP 500SPX市场快照——指数点位index level、日涨跌daily change、涨跌百分比percent change入参无参数Takes no arguments调用方不需要也不允许传入任何参数触发语义当用户询问 SP 500、SPX 或整体股票市场水平overall stock market level时使用。同时文档明确声明数据为 fixture/fake无实时行情源——这是一个测试夹具工具返回值是罐头数据而非真实市场行情。这一声明与 test-tools/README.md 中All data is canned — no fixture ever performs live egress的总体设计一致整个test-tools目录下的三个工具ascii-renderer、hacker-news、market-data都不做真实外呼network声明只是用来驱动宿主侧的义务规划器。输入/输出契约空入参与十字段快照能力文档的无参数语义在输入 Schema 中得到形式化约束。snp500.input.v1.json 是一个空对象 Schema{ $schema: https://json-schema.org/draft/2020-12/schema, title: market-data.snp500 input, type: object, properties: {}, additionalProperties: false }additionalProperties: false意味着任何多余字段都会被拒绝模型侧无法向该工具传递任何参数。输出 Schema 则定义了完整的快照结构。snp500.output.v1.json 包含 10 个字段其中 5 个为必填字段类型必填语义symbolstring✅指数代码如SPXpricenumber✅当前指数点位changenumber✅较昨收的绝对涨跌change_percentnumber✅涨跌百分比as_ofstring✅数据时间戳ISO 8601namestring—指数名称如SP 500previous_closenumber—上一交易日收盘点位day_highnumber—当日最高day_lownumber—当日最低data_sourcestring—数据源标签这套 Schema 同时被宿主用于两个目的参数校验调用前按 input schema 校验模型生成的入参与输出校验/泄露扫描返回值在沙箱出口被扫描防止秘密形数据外泄。源码实现WASM 组件如何产出固定快照能力文档描述的返回快照行为由market-data的 WASM 工具实现承担。工具源码位于 wasm-src/src/lib.rs基于wit-bindgen生成绑定实现了sandboxed-toolworld 的tool接口接口契约定义见 crates/lanes/ironclaw_wasm/wit/tool.wit。execute入口的行为与能力文档完全对应不读取任何入参_req被直接忽略构造一个固定的Snp500Snapshot快照并序列化为 JSON 返回。核心数据点let snapshot Snp500Snapshot { symbol: SPX.to_string(), name: SP 500.to_string(), price: 5_487.03, change: 12.45, change_percent: 0.23, previous_close: 5_474.58, day_high: 5_492.10, day_low: 5_468.77, as_of: 2026-06-30T20:00:00Z.to_string(), data_source: market_data_api (fake fixture data).to_string(), };数据结构定义在 wasm-src/src/types.rsSnp500Snapshot是一个Serialize派生结构体字段与输出 Schema 一一对应。可以看到快照的as_of是一个固定的历史时间戳、data_source明确标注fake fixture data与能力文档数据是 fixture/fake的声明互相印证。序列化成功返回Response::Success(output)失败则返回Response::Failure携带ErrorKind::Executor与code serialization_failed。此外工具还实现了schema()返回与 input schema 等价的空对象 JSON和description()与能力文档一致的模型侧描述。值得注意的工程细节序列化失败在 WASM 工具里几乎不可能触发固定结构体、无动态字段但实现仍然以结构化GuestFailure上报而非 panic符合 tool.wit 中guest 上报失败必须使用封闭词表closed vocabulary的error-kind且message会在沙箱出口被清洗与限长的约束——这是 IronClaw 对沙箱工具失败路径的硬性安全要求。宿主义务链network use_secret 双义务与密钥注入能力文档本身没有提安全模型但 manifest 揭示了它作为测试夹具的真正价值market-data是 test-tools 三个夹具中义务最重的一个。对照 test-tools/README.md 的工具矩阵工具Effects凭据覆盖的用例ascii-rendererdispatch_capability无纯计算无义务hacker-news network无仅出口 allowlist无密钥market-data network, use_secret租户共享market_data_api_key出口 allowlist 宿主中介密钥注入manifest 中关键声明[[capability_provider.tools.capabilities]] id market-data.snp500 effects [dispatch_capability, network, use_secret] default_permission allow origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } visibility model [[capability_provider.tools.capabilities.runtime_credentials]] handle market_data_api_key source { type secret_handle } audience { scheme https, host_pattern api.marketdata.example } target { type header, name x-api-key } required true这段声明的安全含义值得拆解use_secretruntime_credentials运行时凭据的handle market_data_api_key会触发宿主侧的InjectSecretOnce义务同时audience.host_pattern api.marketdata.example填充出口 allowlist触发ApplyNetworkPolicy义务——正如 manifest 注释所写该能力同时获得两个义务密钥永远不进入 WASM凭据target声明为 HTTP 请求头的x-api-key由宿主在 egress 边界注入。这与 tool.wit 安全模型完全一致Secrets are NEVER exposed to WASM; credentials are injected at host boundaryWASM 侧只能通过secret-exists检查秘密是否存在永远读不到值夹具不真实外呼由于返回罐头数据注入的x-api-key永远不会被真正发送密钥的存在只是为了驱动宿主义务管线pre-flight、gating、injection而不是认证任何真实服务。义务的执行逻辑在宿主侧有专门测试印证。在 crates/kernel/ironclaw_host_runtime/src/obligations/tests.rs 中market_data_api_key被构造为SecretHandle并验证了关键语义InjectSecretOnce可由管理员设置的租户共享密钥满足——测试注释明确写道 tenant-shared key satisfies InjectSecretOnce for a caller with no personal secret即个人无密钥的用户也能通过租户共享凭据获得调用资格。这正是 manifest 注释中admin installs it, provides the sharedmarket_data_api_key, and every user can use it的完整实现闭环。义务处理器本身的调度逻辑位于 obligations/handler.rs其中InjectSecretOnce与ApplyNetworkPolicy均被纳入义务管线枚举。本地安装与运行导入、密钥播种与构建作为可上传的扩展包market-data的完整使用路径如下。1. 密钥播种先于激活租户共享密钥通过环境变量或管理员 API 注入环境变量形式为IRONCLAW_REBORN_DEV_SECRET__market_data_api_keyvalue见 test-tools/README.md。未播种密钥时工具的use_secret义务会使调度被AuthRequired门控拦截。2. 打包导入将test-tools/market-data/目录打成 zip 即为可上传的 bundle通过 WebUI v2 的 Import Tool 流程POST /api/webchat/v2/extensions/import仅管理员导入。导入校验要求trust third_partycapability_providerhost_api 形状上传的 bundle 以ManifestSource::InstalledLocal校验拒绝 first_party/系统信任声明与旧式顶层[[capabilities]]manifest 声明的每个资产WASM 模块、schemas、prompt docs都必须存在于 zip 中且拒绝重复 zip 条目与非 WASM 运行时。3. 构建模块WASM 组件需要wasm32-wasip2目标该目标产出的是WASI component宿主以wasmtime::component::Component::new加载若误用wasm32-wasip1的核心模块会在调度时以 the tool manifest is invalid 失败rustup target add wasm32-wasip2 # 一次性安装 bash scripts/build-test-tools.sh market-data # 构建单个工具构建脚本会把组件产物复制到 manifest 声明的[runtime].module路径wasm/market_data_tool.wasm并产出test-tools/market-data.zip。zip 与wasm-src/target/均为 git 忽略的构建产物仓库只跟踪源码、manifest、schemas 与 prompts。4. 触发调用管理员导入并激活后任意用户向 agent 询问SP 500、SPX或整体股市水平时模型依据能力文档选择market-data.snp500宿主完成门控与密钥注入后调度 WASM返回固定快照 JSON。自动化测试保障manifest 形状被 CI 锁定test-tools的 manifest 并非一次性手写文件而是被测试锁定的契约Rust 测试套件通过include_str!内联这些 manifest 并断言其保持可导入形状见 test-tools/README.md 提到的available_extensions::tests::test_tool_fixture_manifests_stay_importable一旦 manifest 偏离合法的导入形状CI 失败而非 demo 失败。E2E 套件则构建并上传这些 bundle 走完整导入流程。这意味着 manifest.toml 中trust、effects、runtime_credentials等字段的任何改动都会受到回归保护。小结一份能力文档背后完整的安全与测试链路market-data.snp500的能力文档虽只有短短几行但它串联起了 IronClaw 沙箱工具机制的完整链路prompt doc 定义模型侧触发语义 → input/output Schema 定义参数与结果契约 → WASM 组件实现固定快照返回 → manifest 声明networkuse_secret义务与运行时凭据 → 宿主在 egress 边界注入x-api-key头 → 义务管线测试验证租户共享密钥可满足InjectSecretOnce→ CI 锁定 manifest 可导入性。对于希望理解 IronClaw能力声明 沙箱执行 宿主义务三段式架构的开发者这个夹具是一个最小但完整的可读样例。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐EmDash CMS 插件 Hooks 完全指南从沙箱声明到共享宿主管线的执行语义EmDash CMS 插件 Hooks 完全指南从沙箱声明到共享宿主管线的执行语义 导读 本文以 EmDash 插件开发技能库中的 Hooks 参考文档 htCMS后端前端插件系统IronClaw 宿主运行时ironclaw_host_runtime架构导航能力中介执行、义务三权分立与首方工具边界IronClaw 宿主运行时ironclaw_host_runtime架构导航能力中介执行、义务三权分立与首方工具边界 导读 ironclaw_host_人工智能AI 应用交互助手AI AgentOwncast 插件宿主集成深度解析WebAssembly 沙箱、HostEnv 接线与事件分发Owncast 插件宿主集成深度解析WebAssembly 沙箱、HostEnv 接线与事件分发 Owncast 是自托管直播平台服务端用 Go 编写自带音视频直播后端上一篇PUBG罗技鼠标宏自动压枪工具完全指南三步实现精准射击下一篇如何通过消息信号中断优化PCIe设备性能5个关键步骤提升系统中断处理效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考