编写内存插件

记忆插件是一种存储后端：它持久化代理记住的内容并回答回忆查询。它是数据模型负担最重的插件类型。工具有一个函数，channel 有一种消息形状，而记忆后端则有多代理归属、命名空间、会话、类别和重要性权重，并且运行时的记忆语义（作用域回忆、GDPR 导出、替代）依赖于你的实现正确处理行模型。

本指南假设你已了解 工具插件 的基础知识，以及来自 channel guide 的 warm-store 生命周期。它已针对 wit/v0/memory.wit 和 crates/zeroclaw-plugins/src/wasm_memory.rs 中的主机适配器进行校验。

接线状态。 WasmMemory 基于 memory-plugin 世界实现了运行时完整的 Memory trait，受能力门控，并通过单元测试和真实组件的端到端测试覆盖。运行时尚未将其作为可配置后端进行构造；宿主缺少与 channel_plugin_details() 对应的内存侧接口。与通道相同，应面向约定进行构建：真正需要冻结的是 WIT 世界和适配器语义。内存世界目前还没有配置导出，因此不要请求 config_read；只有在将类型化配置 ABI 和解析器接入 WasmMemory 之后，才能再添加该导出。

数据模型

一种记录类型会在两个方向上跨越边界，memory-entry (memory.wit)。在设计存储之前先将其字段内部化，因为这些可选方法都只是对它们的视图：

(key, agent-id) 组合是最常见的错误。基础 get 契约明确说明：当多行共享同一个 key 时，返回的是任意一个匹配的行，而按 agent 范围的查找走的是 get-for-agent。同样，forget 会删除某个 key 的所有行，而不管归属如何；而 forget-for-agent 只会删除恰好对应 (key, agent-id) 的那一行，并保留其他同级行。

必需的导出

有十二个函数没有默认值，且必须实现（memory.wit，required-methods 部分）：

recall-for-agents 接受一个 agent-filter 变体：all（不筛选 agent）或 some(list<string>)（限制为列出的 agent ID）。运行时将其 Rust &[&str] 切片映射为“空切片表示 all”，因此应将 some([]) 视为匹配不到任何内容，而不是匹配所有内容。

能力标志：11 个可选方法

与通道相同：宿主只读取一次 get-memory-capabilities，对于每个未设置的标志，它会使用 Rust trait 默认值，而不是调用你。默认值在 memory.wit 中紧挨着这些标志以内联注释的形式记录，宿主侧的回退逻辑可在 wasm_memory.rs 中看到（每个受保护的方法都会检查该标志，并在缺失时走回退路径）：

请把最后一行读两遍：如果你不实现 store-with-metadata，运行时请求的命名空间和重要性会被回退机制悄悄丢弃。存储命名空间数据的后端应当成套实现 store-with-metadata、recall-namespaced 和 purge-namespace，否则命名空间隔离会悄然退化为后过滤和有损写入。

purge 家族是你的数据删除入口。purge-agent 接受的是 agent-alias（不是 ID）；export-entries 用于 GDPR 第 20 条的数据可携性，且必须返回按创建时间升序排列、排除 embeddings 的 entries。如果你的后端提供真实用户数据，请实现 purge 和 export 标志；只有对于一次性后端，“not supported” 才是可接受的回答。

Sketch：存储形状

组件模式采用的是 channel 模式（warm 实例、thread_local 状态），因此只有数据层不同。一个最小且诚实的后端实现是内存中的 map，并使用正确的键：

#![allow(unused)]
fn main() {
use std::collections::HashMap;

struct Row {
    id: String,
    content: String,
    category: Category,
    timestamp: String,
    session_id: Option<String>,
    namespace: String,
    importance: Option<f64>,
    superseded_by: Option<String>,
    agent_alias: Option<String>,
}

/// (key, agent_id) -> Row。agent_id None 表示未归因的行。
type Table = HashMap<(String, Option<String>), Row>;
}

然后每个必需的方法都是一次直接的遍历：

• store-entry 以命名空间 "default" 插入 (key, None)。
• store-with-agent 使用调用者的命名空间和重要性在 (key, agent-id) 处插入。
• recall 按 content 进行子串/排序筛选，应用会话筛选器，对 timestamp 应用包含式 RFC 3339 边界，排序，并截断到 limit。将空/* 查询按最近优先处理。
• recall-for-agents 在键的第二个组件上添加 agent-filter 遍历。

真实的后端可以在不改变契约结构的情况下，将 map 替换为嵌入式存储。内存适配器有意不链接 wasi:http，即使其作用域携带 http_client；远程后端需要经过独立组件测试的内存网络边界。

主机在你周围所做的事情

了解 wasm_memory.rs 中的适配器行为，有助于解释几个合约边缘情况：

• 温存储，每次调用重新加油。 与 channels 相同：插件生命周期内一个实例，每次调用补充新燃料，调用在互斥锁后串行化。你的后端永远不会看到并发调用。
• 能力在加载时缓存。 主机仅在 from_wasm 期间读取一次你的标志，此后不再读取。没有动态能力发现；重启守护进程才会重新读取它们。
• 一次 trap 就会终止后端。 每个调用点都会用具名上下文包裹 trap（例如 memory.recall-namespaced trapped）。trap 或燃料耗尽会让 Wasmtime 拒绝再次进入该 store；而错过截止时间会在你的代码执行到一半时将其中断。因此在上述任一情况下，宿主都会丢弃你的实例，之后所有到达该实例的调用都会失败，并返回 plugin instance is unavailable。宿主无法提升（lift）的结果也会如此，例如单次调用从 guest 内存中复制的数据超过 Wasmtime 默认的 128 MiB。宿主不会重建该实例：你的条目只存在于该实例中，新实例会表现得仿佛从未存储过任何内容。对于可预期的失败，请返回 err(string)，而不是 panic；你返回的错误会保留该实例。
• 后置过滤回退在主机端执行。 当你的 recall-namespaced 标志未设置时，命名空间过滤会在你的 recall 返回后在主机端运行。你的 limit 处理会与此交互：主机把调用方的 limit 传给 recall，因此后置过滤可能会使结果不足。这也是要原生实现 namespaced 变体的另一个原因。

清单、构建、安装

manifest 是插件目录中名为 manifest.toml 的文件。其字段是 crates/zeroclaw-plugins/src/lib.rs 中 PluginManifest 的 serde 表面，这是唯一的事实来源：

只声明代码实际使用的权限。未声明的权限是组件无法触达的宿主表面；不必要声明的权限则是你主动增加的攻击面，也是审查你的插件的人需要承担的审核负担。

[egress] 是一项声明，而非授权。清单文件本身不赋予任何网络访问权限：主机强制执行的白名单是运维人员在该实例自身的 zpi1_… 记录上设置的 plugins.entries[].egress_hosts，因此即使未签名的组件自行写入了 [egress] 表，也无法访问任何地址。声明的作用在于安装流程：zeroclaw plugin install 会将其写入它新建的记录中，并打印已授予的内容；对于已存在的记录，它从不会扩大其权限。参见 Declaring and granting egress。

操作方提供的值在 plugins.entries 中仍保持为字符串，并会在持久化时加密，以一个由宿主拥有的包、能力和绑定标识派生的版本化 zpi1_… 字符串作为键（安装过程会打印并初始化默认工具绑定的完整实例密钥）：字符串按原样存储，布尔值和数字使用 JSON 标量文本，数组和对象使用 JSON 文本。在任何来宾代码运行之前，宿主会将这些字符串物化为包模式规定的类型，并针对工具和频道适配器验证完整对象。非机密工具属性构成 __config；频道通过 config.get 获取非机密对象。标记为 x-secret = true 的属性会从两个公共接口中省略，仅可在授权的服务帧中通过 secrets.get("property") 获取。频道在一次调用中的公共和机密读取共享同一个规范修订版本，调用结束时宿主会丢弃该物化视图。符合要求的频道插件 必须 在每个使用点都解析这两类值，并且不得在来宾的热状态中保留配置或凭据值；将明文返回给来宾意味着宿主无法针对恶意代码强制实施不保留策略。如果请求了 config_read 但未实际获授予，宿主会验证一个空对象；因此，包含必需属性的模式会拒绝启动，而不会在缺少必需配置的情况下启动。如果空对象有效，工具会省略空的 __config，而频道的配置/机密导入会返回 access-denied；在授权帧之外的调用、解析失败以及宿主调用预算耗尽会返回 unavailable。

对于内存后端：capabilities 包含 memory。暂时不要请求 config_read：准入需要一个模式，但当前内存世界没有可供主机交付生成对象的导出机制。也不要依赖 http_client：仅授予权限无法扩展内存适配器，而该适配器目前不提供任何网络接口。

先安装一次 WASI Preview 2 目标，然后构建组件：

rustup target add wasm32-wasip2
cargo build --release --target wasm32-wasip2

该组件位于 target/wasm32-wasip2/release/<crate_name>.wasm（crate 名称中的连字符会变成下划线）。在组装插件目录时，请将其重命名为你的清单中 wasm_path 声明的名称。

[!IMPORTANT] 编译后的 .wasm 和 .cwasm 文件是二进制构件，通常每个都有数 MB。不要在没有 Git LFS 的情况下将它们提交到 git 源树中：每次重建都作为普通 blob 提交，会永久膨胀仓库历史，并且 git diff/审查工具会因此卡住。把它们当作其他构建输出一样处理：将 target/ 和 *.wasm/*.cwasm 添加到 .gitignore，并改为通过发布构件或插件注册表归档分发。如果某个构件确实必须留在树中，请在首次提交之前使用 LFS 跟踪该模式（git lfs track "*.wasm"）。

如果目标主机是仅运行时构建（未编译 JIT 后端），它在加载时无法编译 .wasm；而是反序列化预编译的 .cwasm。请使用与主机版本匹配的 wasmtime CLI 进行预编译，并将 .cwasm 作为 wasm_path 构件分发。版本不匹配的构件会被 wasmtime 的反序列化检查拒绝，而不会被静默错误加载。

这些命令需要一个编译了插件宿主的二进制文件。 64 位桌面和服务器目标的发布归档包（x86_64 和 aarch64 的 Linux，包括 glibc 和 musl 版本，Apple silicon 与 Intel 的 macOS，以及 Windows x86_64）都包含该宿主，并且每次发布前都会从这些归档中各执行一个插件，然后才会正式发布。两个 32 位 ARM 归档和实验性的 Android 归档不包含该宿主，使用 Cargo 默认配置的源码构建也不包含（cargo install zeroclaw、install.sh --source 或不带特性的 cargo build）：在这些情况下，zeroclaw plugin ... 会被识别为未知子命令，已安装的插件也永远不会被发现。对于这些情况，请使用插件执行后端从源码构建，例如 cargo build --release --features plugins-wasm-cranelift。协议页面列出了每个构件的插件支持情况。

每个插件都位于 plugins 目录的各自子目录中（默认 ~/.zeroclaw/plugins/，通过 plugins.plugins_dir 解析），其中包含清单以及与清单的 wasm_path 匹配的组件：

~/.zeroclaw/plugins/
└── my-plugin/
    ├── manifest.toml
    └── my-plugin.wasm

从本地目录安装（这会在复制任何内容之前验证清单形状并运行签名策略）：

zeroclaw plugin install ./my-plugin/

启用插件系统并确认发现：

zeroclaw config set plugins.enabled true
zeroclaw plugin list
zeroclaw plugin info my-plugin

zeroclaw plugin list 和 zeroclaw plugin info 可确认软件包已安装且可被发现，但发现并不等于激活。plugins.enabled = true 会开启插件主机；只有同时将 plugins.auto_discover = true 设为 true 时，自动发现的工具和技能功能才会在运行时加载，而该标志默认为 false（故障关闭）：

zeroclaw config set plugins.auto_discover true

因此，仅设置 plugins.enabled = true 时，会启用你在 [channels.plugin.<alias>] 下声明的通道，而不会启用任何插件工具或技能：工具或技能包可能会出现在 zeroclaw plugin list 中，但在运行时不会产生任何作用。显式通道绑定由操作员命名，而不是自动发现，因此不需要 auto_discover；该标志仅控制自动发现的工具和技能。

zeroclaw plugin list 中缺失的插件在发现时已被跳过：请检查启动日志中的跳过警告（清单格式错误、缺少 wasm_path 文件，或签名策略拒绝）。

下一个

• Skill bundles：通过相同的安装机制进行仅限 markdown 的技能分发。
• 分发插件。