企业官网建设流程全解析

• 人工智能
• AI 应用
• 交互助手
• AI Agent

导读

ascii-renderer.draw是 IronClaw 中以 WASM 组件形式发布的一个最小化工具扩展：它渲染一小段内置的 ASCII 艺术（cat / dog / robot），仅声明dispatch_capability效果，不需要网络访问、不需要任何凭据，是典型的"纯计算（pure compute）"能力。本文以该工具的提示文档（draw.md）为主线，结合扩展清单、WASM 实现、JSON Schema 与构建脚本，完整讲解这类无网络、无密钥工具的声明方式、调用契约、沙箱实现与在测试体系中的定位。

工具契约：参数、行为与默认值

工具的提示文档定义了一条非常简洁的调用契约：

• 渲染一小段**预置（canned）**的 ASCII 艺术并返回；
• 可选参数subject选择图形：cat、dog或robot，默认值为robot；
• 传入未知 subject 时自动回退到robot，而不是报错；
• 工具适合在用户索要 ASCII 艺术或快速小图画时调用；
• 不需要网络访问、不需要凭据，是纯计算。

从 WASM 实现（lib.rs）可以看到这套行为的具体落地。输入解析采用宽松策略：req.params为空或空白时直接使用默认输入；JSON 解析失败同样回退到默认值（serde_json::from_str(params).unwrap_or_default()）。随后art_for()对 subject 做trim().to_lowercase()归一化后匹配三种图形，任何未命中分支都会落到 robot 图形上：

fn art_for(subject: &str) -> Option<&'static str> { match subject.trim().to_lowercase().as_str() { "cat" => Some(r#" /\_/\ ( o.o ) > ^ <"#), "dog" => Some(r#" / \__ ( @\___ / O / (_____/"#), "robot" | "" => Some(r#" [ o_o ] /|_____|\ | | =d b="#), _ => None, } }

返回结构由 types.rs 定义：DrawInput { subject: Option<String> }作为输入，AsciiArt { subject: String, art: String }作为输出。

输入输出 Schema：类型即契约

工具的输入输出各有独立的 JSON Schema（2020-12 draft），并在 manifest 中通过input_schema_ref/output_schema_ref引用：

• 输入 draw.input.v1.json：object，仅一个可选字符串属性subject，additionalProperties: false；
• 输出 draw.output.v1.json：object，必填字段subject与art，同样禁止多余属性。

值得注意的细节是：输入 Schema 中subject是开放字符串而非 enum。实现中对schema()的注释明确解释了原因——工具刻意接受任意字符串并对未知值回退到 robot，因此对外声明的契约不能承诺一个实际并未强制执行的封闭集合（lib.rs）。这是"声明必须与行为一致"的一个典型示例：schema 只约束参数形态，不承诺取值枚举，未知值由运行时宽容处理。

Manifest 声明：无网络、无密钥能力如何表达

工具的能力声明位于扩展清单 manifest.toml，采用reborn.extension_manifest.v2格式，其关键声明如下：

effects只声明dispatch_capability是"零义务"的关键：由于没有network效果，义务规划器（obligation planner）不会为它附加ApplyNetworkPolicy，也不会产生任何密钥义务；manifest 中的注释还提到，v2 解析器会因为缺少network效果而拒绝在此处声明network_targets（manifest.toml）。也就是说，义务边界由效果声明机械推导，声明与语义是强绑定关系。

沙箱实现：WASM 组件如何接入运行时

工具本体是编译为wasm32-wasip2的WASI 组件，通过wit-bindgen绑定 tool.wit 中定义的sandboxed-toolworld：工具导入宿主提供的host接口、导出tool接口。核心入口execute(req: Request) -> Response完成一次调用：

1. 通过宿主log接口输出info级别日志（日志按执行收集、限速每执行 1000 条、每条 4KB）；
2. 宽松解析params为DrawInput；
3. 匹配图形并构造AsciiArt；
4. 序列化为 JSON，成功返回Response::Success(output)，序列化失败则返回Response::Failure，携带ErrorKind::Executor与稳定错误码serialization_failed。

整个执行不触碰任何宿主能力——不调用http-request、不读取 workspace、不检查 secret。这正是 tool.wit 安全模型的体现：WASM 工具默认无任何访问权，所有能力均为 opt-in，而本工具显式选择了零能力集合。

构建侧，Cargo.toml 采用cdylibcrate 类型并针对体积优化（opt-level = "s"、lto = true、strip = true）。构建命令在 test-tools/README.md 中给出：

rustup target add wasm32-wasip2 # 一次性添加目标 bash scripts/build-test-tools.sh # 构建全部工具 bash scripts/build-test-tools.sh market-data # 构建单个工具

脚本会校验组件头、把产物复制到 manifest 声明的[runtime].module路径并生成可上传的 zip；wasm32-wasip1核心模块可导入但分发时会因"tool manifest is invalid"失败，因为运行时通过wasmtime::component::Component::new加载的是 WASI 组件形态。

在测试矩阵中的定位：三种义务类别的"零义务"基准

ascii-renderer属于 test-tools 体系中的测试夹具（#5459 fixture），与另外两个工具构成完整的三档义务矩阵：

这套夹具的价值在于：管理员安装后，任何用户都可以零义务地请求该工具，用来端到端验证"无网络、无密钥扩展从导入、激活到被模型调用的完整链路"。E2E 套件会构建并上传这些 bundle，Rust 套件则在ironclaw_composition::extension_lifecycle中内存构建 zip 夹具，并通过available_extensions::tests::test_tool_fixture_manifests_stay_importable以include_str!钉住这些 manifest——一旦 manifest 漂移出可导入形态，CI 就会失败，而不是等演示时才暴露。所有夹具的数据都是预置的，绝不执行真实出站请求，网络声明只是为了驱动义务规划器。

导入路径本身也有约束（test-tools/README.md）：zip 内必须包含 manifest 声明的全部资产（模块、schemas、prompt 文档），拒绝重复 zip 条目名，拒绝非 WASM 运行时。

总结

ascii-renderer.draw是一个麻雀虽小、五脏俱全的工具扩展样本：提示文档定义用户可感知的调用语义（subject 三选一、未知回退、纯计算零依赖），manifest 用效果声明把"零义务"落到义务规划器可验证的层面，WASM 实现展示了一个最小化组件如何通过wit-bindgen接入sandboxed-toolworld，而测试矩阵则赋予它"纯计算基准夹具"的工程价值。对于想要在 IronClaw 中编写同类无网络、无密钥 WASM 工具的开发者，这个 fixture 的 manifest、schema、prompt 三件套与构建脚本就是最直接的参考模板。

• 人工智能
• AI 应用
• 交互助手
• AI Agent