WeKnora Agent 持久化运行环境：基于 CubeSandbox 的生产级 Wasm 沙箱实践

1. 项目概述：为什么需要一个“能一直在线”的 Agent 运行环境？

WeKnora 是一个面向知识协作与语义化工作流的开源平台，它的核心价值不在于单次问答，而在于持续、可信、可追溯的知识沉淀与协同演进。当你在 WeKnora 里配置好一个能自动归档会议纪要、实时同步 GitHub Issue、或定时抓取行业 RSS 并结构化入库的 Agent 时，你真正期待的不是它“跑一次就完事”，而是它像办公室里的行政助理一样——每天早上 9 点准时开工，遇到异常自动重试，系统重启后无缝续上，日志清晰可查，权限收束得当，哪怕连续运行三个月，你打开管理界面看到的仍是“运行中”三个字，而不是一堆红色报错。这就是“持久化运行环境”的真实含义：它不是让 Agent 能“启动”，而是让它能“活着”，并且活得健康、可控、可审计。

我最早在本地用cargo run启动 WeKnora 的 Rust Agent 时，以为万事大吉。结果第二天发现服务挂了——不是代码 bug，是终端窗口被误关、系统休眠唤醒后进程丢失、或是 Docker 容器因 OOM 被 kill。更麻烦的是，Agent 的临时状态（比如正在处理的第 37 条 Slack 消息、缓存中的 OAuth token）全丢了，重跑就得从头开始，甚至可能重复触发下游 API 导致数据错乱。这根本不是生产级可用的状态。后来我们团队在给一家律所部署 WeKnora 时，客户明确提了一条需求：“这个合同摘要 Agent 必须 7×24 小时在线，周末也不能掉线，否则律师周一早上打开系统发现上周五的邮件没处理，整个工作流就断了。”那一刻我才意识到：Agent 开发的终点，从来不在“写完逻辑”，而在“托付给环境”。

关键词WeKnora和CubeSandbox在这里不是并列关系，而是层级关系：WeKnora 是业务层框架，定义了 Agent 的能力契约（如knora://agent/contract/summarize）、知识图谱交互协议和 OIDC 认证集成；而 CubeSandbox 是它的底层沙箱引擎，负责将 WeKnora 的 Agent 描述（YAML 或 JSON Schema）编译为隔离、可度量、可中断的执行单元。它不是 Docker 容器的简单封装，而是基于 WebAssembly 的轻量级运行时，每个 Agent 实例都拥有独立的内存空间、文件系统视图和网络策略。这种设计天然规避了传统容器间共享 PID 命名空间带来的信号干扰问题，也避免了 Python 虚拟环境全局污染导致的依赖冲突。换句话说，CubeSandbox 不是“让 Agent 跑起来”的工具，而是“让 Agent 安心活下去”的基础设施。

所以，“WeKnora 基于 CubeSandbox 的 Agent 持久化运行环境建设”，本质上是一场从“开发态”到“运维态”的范式迁移。它要求我们跳出main.rs的舒适区，去思考：进程如何优雅启停？失败后怎样自动恢复？资源使用怎么限制不拖垮宿主？日志怎么分类归档便于审计？权限如何最小化授予又不失灵活性？这些都不是 WeKnora 文档里会写的，却是你在真实世界里让一个 Agent 从 Demo 变成生产力工具的必经之路。接下来的内容，就是我们踩过坑、调过参、压过测后，整理出的一套可直接落地的建设方案。

2. 整体架构设计：为什么选择 CubeSandbox 而非 Docker/K8s 直接托管？

2.1 核心矛盾：WeKnora Agent 的“轻量性”与“可靠性”需求

WeKnora 的 Agent 设计哲学是“小而专”：一个 Agent 通常只做一件事，比如rss-to-knora，它可能只有 200 行 Rust 代码，依赖仅reqwest+serde_json，内存常驻占用不到 8MB。如果把它塞进一个标准 Docker 镜像里，光基础 Alpine Linux + Rust 运行时就占掉 50MB+，启动时间 3~5 秒，还要配一套复杂的 healthcheck 和 livenessProbe。更关键的是，Docker 的 PID 1 进程模型对 WeKnora 这类需要精细信号控制（如 SIGUSR1 触发状态快照、SIGUSR2 强制刷新凭证）的场景并不友好——你得自己写 init 进程来转发信号，稍有不慎就变成僵尸进程。

而 CubeSandbox 的设计恰恰切中这个痛点。它不是一个通用容器，而是一个为 WeKnora Agent 量身定制的 Wasm 运行时。我们实测过：一个编译后的rss-to-knora.wasm文件大小仅 1.2MB，冷启动耗时 120ms（含 Wasm 解析、内存初始化、WASI 环境注入），热启动（即已有实例存在时新任务派发）更是低至 8ms。更重要的是，CubeSandbox 内置了对 WeKnora 协议栈的原生支持：它能直接读取agent.yaml中定义的knora://URI，并自动完成 OIDC Token 获取、知识图谱 endpoint 发现、以及knora://schema/Document等语义类型校验。这些能力如果用 K8s Operator 自己实现，至少要写 300 行 Go 代码，还要维护一套 CRD schema。

2.2 架构分层：四层解耦保障可维护性

我们最终采用的架构不是“一个 CubeSandbox 实例跑所有 Agent”，而是分四层解耦：

• 调度层（Orchestrator）：独立服务，监听 WeKnora 的agent_registry事件流（通过 Kafka 或 NATS）。当检测到新 Agent 注册或状态变更（如status: enabled），它生成一条标准化的RunSpec消息，包含wasm_url、env_vars、resource_limits、restart_policy四个核心字段。这个层完全不碰 Wasm 执行，只做决策。

• 沙箱管理层（Sandbox Manager）：这是 CubeSandbox 的核心守护进程。它接收RunSpec，校验 Wasm 模块签名（WeKnora 要求所有 Agent 必须由私钥签名，防止恶意代码注入），然后调用wasmerruntime 创建隔离实例。关键设计是：每个 Agent 实例对应一个独立的sandbox_id，该 ID 作为其所有资源（内存、文件句柄、网络连接池）的命名空间前缀。这样即使某个 Agent 泄露内存，也不会影响其他实例。

• 持久化层（Persistence Layer）：这是“持久化”的物理载体。我们没有用传统数据库存 Agent 状态，而是采用分层存储：

  • 瞬时状态（Transient）：存于内存映射文件/dev/shm/sb_<id>_state，用于高频读写的运行时变量（如 last_fetched_timestamp）；
  • 可靠状态（Reliable）：存于 SQLite 数据库./persistence/<agent_id>.db，记录 checkpoint、失败重试次数、OAuth refresh_token 等需跨重启保留的数据；
  • 审计日志（Audit）：写入journalctl兼容格式的二进制日志./logs/<agent_id>.journal，每条记录含 timestamp、level、span_id、structured_payload，支持journalctl -t weknora-agent-<id>直接查询。

• 接入层（Gateway Layer）：提供统一 HTTP 接口供 WeKnora UI 调用，如POST /v1/agents/{id}/trigger手动触发，GET /v1/agents/{id}/metrics获取 Prometheus 指标。这一层做了关键的权限网关：所有请求必须携带X-Knora-Auth-Token，该 token 由 WeKnora OIDC 服务签发，Gateway 会验证其 scope 是否包含agent:manage:<id>。

这套分层的好处是：升级 CubeSandbox runtime 时，只需重启 Sandbox Manager，调度层和持久化层完全不受影响；更换日志后端（比如从 journalctl 切到 Loki），只需改 Gateway 层的写入逻辑；甚至可以把 Persistence Layer 换成 S3 兼容对象存储，只要实现相同的 SQLite WAL 日志同步协议即可。我们曾用这套架构，在不中断任何 Agent 的情况下，将底层 Wasm runtime 从 Wasmer 2.x 平滑升级到 3.x。

2.3 为什么不用 Dify/CrewAI 等主流框架？

网络热词里频繁出现的dify、crewai、langchain，它们解决的是“Agent 编排”问题——如何把多个 LLM 调用、工具函数、记忆模块串成一个 workflow。但 WeKnora 的定位不同：它是一个“知识操作系统”，Agent 是它的“系统服务进程”，而非“用户工作流”。举个例子：Dify 里你创建一个“周报生成 Agent”，它每次运行都是独立的、无状态的；而 WeKnora 里的weekly-reporterAgent，必须记住“上周生成的是哪几份文档”，才能避免重复生成，这就要求它有可靠的、带事务的状态存储。

CubeSandbox 的优势在于它把“状态持久化”变成了运行时的内置契约。在 Dify 中，你要自己写代码把last_run_date存到 Redis；而在 CubeSandbox 里，你只需在agent.yaml中声明：

state: schema: last_run_date: "date" processed_docs: ["string"] persistence: "reliable" # 可选 transient/reliable/audit

CubeSandbox 会在每次 Agent 执行结束时，自动将这个结构序列化存入 SQLite，并在下次启动时反序列化注入WASI环境。你完全不用碰数据库连接字符串或 ORM。这种“约定优于配置”的设计，大幅降低了 WeKnora Agent 的开发门槛——一个 Rust 新手，只要会写println!()，就能写出一个带状态的生产级 Agent。

3. 核心细节解析：从 YAML 配置到沙箱生命周期的完整闭环

3.1 Agent 描述文件（agent.yaml）的深层语义

WeKnora 的agent.yaml看似简单，但每个字段都承载着运行时契约。我们以一个真实的github-issue-syncAgent 为例，逐字段拆解其背后的技术含义：

# agent.yaml name: github-issue-sync version: "1.2.0" description: "Sync GitHub issues to Knora knowledge graph with semantic tagging" # —— 这不是注释，而是 WeKnora CLI 生成文档的来源，也是 UI 展示的依据 runtime: type: wasm engine: wasmer version: "3.0.0" # —— 显式声明 Wasm 引擎及版本，CubeSandbox 会据此选择预编译的 runtime binary， # 避免因引擎 ABI 不兼容导致的神秘 crash。实测过：wasmer 2.x 编译的 wasm 在 3.x runtime 下 # 会因 `wasi_snapshot_preview1` 接口变更而 panic，这个字段就是救命稻草。 entrypoint: "src/main.rs" # —— 注意！这不是文件路径，而是 Cargo.toml 中的 crate 名。CubeSandbox 会根据此名 # 在 Wasm 模块的 custom section 中查找 `producers` 字段，确认其是否由 rustc 1.75+ 编译， # 因为旧版 rustc 生成的 wasm 缺少必要的 stack trace 支持。 environment: GITHUB_TOKEN: "secret://vault/github-token" KNORA_ENDPOINT: "https://knora.example.com/v2" # —— `secret://vault/xxx` 是 CubeSandbox 的密钥注入协议。它不会把 token 写进 env var， # 而是在 sandbox 启动时，通过 `WASI` 的 `keyvalue` interface 提供一个只读 key-value store， # Agent 代码需调用 `wasi:keyvalue/get` syscall 获取，杜绝了 `ps aux | grep GITHUB_TOKEN` 的泄露风险。 resources: memory: "128Mi" cpu: "200m" # 即 0.2 vCPU disk: "512Mi" # —— 这些不是 Docker 的 --memory/--cpus，而是 CubeSandbox 的 Wasm 内存页限制。 # `128Mi` 表示最多分配 32768 个 4KB 内存页。一旦 Agent 尝试申请第 32769 页， # runtime 会抛出 `wasm trap: out of bounds memory access`，比 OOM killer 更早、更精准地拦截。 lifecycle: restart_policy: "always" max_restart_count: 5 restart_delay: "30s" # —— `always` 表示无论 exit code 是什么（0 正常退出 or 101 panic），都重启。 # 但 `max_restart_count` 是防爆破的关键：如果 Agent 连续 5 次在 30 秒内崩溃， # Sandbox Manager 会将其 status 置为 `crashloop_backoff`，停止自动重启， # 并发送 alert 到 configured webhook。这是我们线上环境发现的一个重大隐患： # 某个 Agent 因 GitHub API rate limit 返回 403，却没处理这个 error，导致无限重启。 state: schema: last_synced_issue_number: "integer" processed_repos: ["string"] persistence: "reliable" # —— 如前所述，这是状态持久化的声明。`reliable` 意味着 CubeSandbox 会确保： # 1) 每次 Agent 退出前，state 必须成功写入 SQLite； # 2) 如果写入失败（如磁盘满），Agent 进程会被强制 kill，避免脏状态； # 3) 启动时若 SQLite 文件损坏，会回退到上一个 valid WAL checkpoint。 triggers: - type: "webhook" endpoint: "/webhook/github" method: "POST" - type: "cron" schedule: "0 0 * * *" # 每天凌晨 0 点 # —— 触发器不是简单的路由表。`webhook` 类型会由 Gateway Layer 自动注册反向代理， # 并在请求头注入 `X-Sandbox-ID: sb_abc123`，方便 Agent 代码区分调用来源； # `cron` 类型则由 Scheduler Service 统一管理，它使用 `cron_rs` 库，支持秒级精度， # 且每个 cron job 都绑定到特定 sandbox_id，避免全局 cron 表锁竞争。

提示：agent.yaml中的version字段必须与 Wasm 文件的build-id严格匹配。CubeSandbox 启动时会计算 Wasm 的 blake3 hash，并与agent.yaml中version的语义版本做校验。如果不匹配，会拒绝启动并返回ERR_VERSION_MISMATCH。这个设计强制开发者养成“每次变更必更新版本号”的习惯，杜绝了“配置和代码不一致”的经典运维灾难。

3.2 沙箱生命周期：从创建到销毁的七步状态机

CubeSandbox 的沙箱不是简单的“start/stop”，而是一个七状态机，每个状态都有明确的进入/退出条件和副作用。理解这个状态机，是调试 Agent 异常的核心：

1. pending：收到RunSpec，但尚未校验 Wasm 签名。此时 Agent 在 UI 中显示为“等待中”。如果签名验证失败（如公钥不匹配），状态直接转为failed，日志记录ERR_INVALID_SIGNATURE。

2. validating：Wasm 模块已加载，正在执行__wasm_start函数（由wasm-bindgen自动生成）。这一步会检查所有导入的 WASI 函数是否可用，并验证state.schema的 JSON Schema 是否合法。如果 Agent 代码里引用了未声明的wasi:random接口，这里就会 fail。

3. initializing：__wasm_start成功返回，CubeSandbox 开始注入环境：挂载secret://vault、设置WASI文件系统视图、初始化state从 SQLite 加载。这是最易出错的阶段——如果 SQLite 文件损坏，状态会卡在这里，直到手动干预。

4. running：Agent 的main函数开始执行。此时lifecycle.restart_policy生效。注意：running状态下，Agent 可以主动调用wasi:cli/exit退出，也可以被外部 signal 终止。

5. stopping：收到SIGTERM或restart_policy触发重启。CubeSandbox 会先向 Agent 发送SIGUSR1，通知其保存当前 state（调用wasi:keyvalue/set），然后等待最多grace_period: 10s（默认值，可在agent.yaml中覆盖）。如果超时，强制SIGKILL。

6. stopped：进程已退出，但 state 和日志仍保留在磁盘。这是restart_policy: never的终态。

7. crashloop_backoff：连续max_restart_count次在restart_delay内失败。此时 Sandbox Manager 会暂停对该 Agent 的所有调度，并在GET /v1/agents/{id}/status中返回backoff_until: "2024-05-20T14:22:30Z"。这是运维同学最该关注的状态——它意味着你的 Agent 代码里有未捕获的 panic，或者依赖的服务（如 GitHub API）彻底不可达。

我们曾遇到一个典型 case：github-issue-syncAgent 在initializing状态卡住数小时。排查发现，其KNORA_ENDPOINT配置错误，指向了一个不存在的域名。CubeSandbox 在初始化state时，尝试连接 Knora 的/healthendpoint 做预检，DNS 解析失败导致阻塞。解决方案是：在agent.yaml中增加health_check_timeout: "5s"，并让 CubeSandbox 在预检失败时快速 fail，而不是无限等待。

3.3 持久化层的工程实现：SQLite WAL 与内存映射的协同

“持久化”这个词容易让人联想到 PostgreSQL 或 MongoDB，但在 CubeSandbox 的轻量级场景下，SQLite 是更优解。关键在于如何让它既可靠又高效。我们的方案是 WAL（Write-Ahead Logging）模式 + 内存映射文件的组合：

• WAL 模式启用：在创建 SQLite DB 时，执行PRAGMA journal_mode = WAL;。这使得写操作先写入*-wal文件，再异步刷盘，读操作可并发进行，避免了传统DELETEjournal 的锁竞争。实测表明，在 1000 次/秒的 state 更新频率下，WAL 模式比DELETE模式吞吐量高 3.2 倍。

• 内存映射优化：SQLite 默认使用mmap加速读取，但对小文件效果有限。我们为每个 Agent 的 DB 设置了PRAGMA mmap_size = 268435456;（256MB），并确保state表的rowid是主键（SQLite 的默认行为）。这样，当 Agent 查询last_synced_issue_number时，SQLite 可以直接从内存映射区域读取，无需系统调用。

• WAL 日志同步策略：这是可靠性的核心。我们禁用了PRAGMA synchronous = NORMAL（默认），改为PRAGMA synchronous = FULL，并设置了PRAGMA wal_autocheckpoint = 1000;。这意味着：每 1000 条 WAL 记录，SQLite 就强制执行一次fsync，将 WAL 写入磁盘。虽然牺牲了点性能，但保证了即使系统突然断电，WAL 中的最后 1000 条记录也不会丢失。

• 状态快照（Snapshot）机制：为了应对 WAL 文件过大（>1GB）导致的恢复慢问题，CubeSandbox 实现了一个后台快照线程。它定期（默认 1 小时）执行PRAGMA wal_checkpoint(TRUNCATE)，将 WAL 中的修改合并到主 DB 文件，并清空 WAL。这个操作是原子的，且全程不阻塞读写。我们监控发现，开启快照后，Agent 重启平均时间从 8.2s 降至 1.3s。

注意：SQLite 的WAL模式要求数据库文件和-wal文件必须在同一文件系统上。如果你把./persistence目录挂载到 NFS 或 CephFS，WAL 可能失效。我们线上环境强制要求persistence目录必须是本地 ext4 或 XFS 文件系统，并在启动时用stat -f -c "%T" ./persistence校验。

4. 实操过程：从零搭建一个高可用 WeKnora Agent 运行环境

4.1 环境准备：硬件、OS 与依赖的硬性要求

别跳过这一步。很多 WeKnora Agent 的“不稳定”，根源在于底层环境不符合 CubeSandbox 的硬性要求。我们线上集群的基准配置如下：

• CPU：必须支持 AVX2 指令集。Wasmer 3.x 的 JIT 编译器重度依赖 AVX2 加速 Wasm 指令翻译。在不支持 AVX2 的老 CPU（如 Intel Xeon E5-26xx v3）上，Wasm 启动时间会从 120ms 暴增至 2.3s，且 CPU 占用率飙升。用grep -q avx2 /proc/cpuinfo && echo "OK" || echo "FAIL"快速检测。

• 内存：最小 4GB RAM。CubeSandbox 的 Sandbox Manager 进程自身常驻内存约 1.2GB（含 WASI runtime cache），每个活跃 Agent 实例额外消耗 128MB（见resources.memory）。如果你只打算跑 3 个 Agent，4GB 是底线；10 个以上，建议 16GB 起步。

• OS 内核：Linux 5.4+。关键需求是memcg（Memory Cgroup）和io.weight（IO Weight）的支持。CubeSandbox 使用 cgroups v2 限制每个 sandbox 的内存和 IO，老内核无法正确 enforcememory.max。检查命令：uname -r和cat /sys/fs/cgroup/cgroup.controllers | grep -E "(memory|io)"。

• 文件系统：ext4 或 XFS，且必须启用dax（Direct Access）特性。dax允许内存映射文件绕过 page cache，直接读写 SSD。这对 SQLite WAL 的fsync性能提升巨大。启用方法（以 ext4 为例）：mkfs.ext4 -O dax /dev/sdb1，挂载时加dax参数：mount -o dax /dev/sdb1 /opt/weknora/persistence。

• 依赖安装：不要用包管理器装wasmer，必须用官方二进制。原因：包管理器的wasmer版本往往滞后，且缺少wasmer compile的 AOT 支持。正确做法：

  curl -L https://github.com/wasmerio/wasmer/releases/download/3.0.0/wasmer-linux-amd64.tar.gz | tar xz -C /usr/local/bin # 验证 wasmer --version # 必须输出 3.0.0

• 安全加固：禁用ptrace。CubeSandbox 的 sandbox 隔离依赖seccomp-bpf过滤系统调用，而ptrace是绕过隔离的常见入口。执行echo 0 > /proc/sys/kernel/yama/ptrace_scope（需 root）。这一步能阻止恶意 Wasm 模块通过ptrace读取宿主进程内存。

4.2 CubeSandbox 部署：三步完成生产级安装

我们摒弃了官方文档推荐的docker-compose up方式，因为 Docker 的 overlay2 存储驱动在高并发 Wasm 加载时会出现 inode 泄露。以下是裸机部署的三步法：

第一步：下载并解压 CubeSandbox 发行版

# 创建安装目录 sudo mkdir -p /opt/cubesandbox/{bin,config,logs,persistence} sudo chown -R $USER:$USER /opt/cubesandbox # 下载最新稳定版（截至 2024-05，v1.4.2） curl -L https://github.com/weknora/cubesandbox/releases/download/v1.4.2/cubesandbox-v1.4.2-linux-amd64.tar.gz \ | tar xz -C /tmp/ cp /tmp/cubesandbox/cubesandbox /opt/cubesandbox/bin/ chmod +x /opt/cubesandbox/bin/cubesandbox

第二步：编写核心配置文件config.yaml

# /opt/cubesandbox/config.yaml server: host: "0.0.0.0" port: 8080 tls: enabled: true cert_file: "/opt/cubesandbox/tls/cert.pem" key_file: "/opt/cubesandbox/tls/key.pem" sandbox: # 每个 sandbox 的最大内存，单位 MB memory_limit_mb: 128 # Wasm 模块的最大执行时间，单位秒 timeout_seconds: 300 # 启用 AOT 编译缓存，大幅提升冷启动速度 aot_cache_dir: "/opt/cubesandbox/aot-cache" persistence: # SQLite DB 的根目录 db_root: "/opt/cubesandbox/persistence" # WAL 日志的自动 checkpoint 间隔（条数） wal_autocheckpoint: 1000 # 快照线程的执行间隔（秒） snapshot_interval_seconds: 3600 logging: # 日志级别：debug/info/warn/error level: "info" # 日志输出格式：json/text format: "json" # 日志轮转：按大小 100MB，保留 7 天 rotation: max_size_mb: 100 max_age_days: 7 # OIDC 配置，对接 WeKnora 的认证服务 oidc: issuer: "https://knora.example.com/auth/realms/weknora" client_id: "cubesandbox-gateway" client_secret: "your-client-secret-here"

第三步：创建 systemd 服务并启动

# 创建 service 文件 sudo tee /etc/systemd/system/cubesandbox.service << 'EOF' [Unit] Description=CubeSandbox Agent Runtime After=network.target [Service] Type=simple User=weknora Group=weknora WorkingDirectory=/opt/cubesandbox ExecStart=/opt/cubesandbox/bin/cubesandbox --config /opt/cubesandbox/config.yaml Restart=always RestartSec=10 # 关键：限制内存，防止 runaway process 拖垮宿主 MemoryMax=2G # 关键：限制 CPU，避免抢占 WeKnora 主服务 CPUQuota=50% # 安全加固 NoNewPrivileges=true RestrictNamespaces=true ProtectSystem=strict ProtectHome=true PrivateTmp=true [Install] WantedBy=multi-user.target EOF # 启用并启动 sudo systemctl daemon-reload sudo systemctl enable cubesandbox sudo systemctl start cubesandbox # 查看状态 sudo systemctl status cubesandbox -l # 应该看到 "active (running)" 且无 ERROR 日志

实操心得：MemoryMax=2G和CPUQuota=50%是我们线上环境的黄金参数。MemoryMax必须大于 Sandbox Manager 自身内存（1.2G）+ 所有 Agent 的resources.memory总和，否则 systemd 会 OOM kill 整个服务。CPUQuota=50%意味着 CubeSandbox 最多使用半个 CPU 核心，这足够应付 20 个并发 Agent，又不会影响 WeKnora 主服务的响应延迟。我们曾把CPUQuota设为100%，结果在流量高峰时，WeKnora 的 GraphQL 查询 P95 延迟从 120ms 涨到 850ms，根源就是 CPU 争抢。

4.3 WeKnora Agent 开发与部署：一个完整的端到端示例

现在，让我们亲手打造一个rss-to-knoraAgent，并部署到刚建好的 CubeSandbox 环境中。这个 Agent 的功能是：每小时抓取指定 RSS 源，解析<item>，提取标题、链接、发布日期，然后调用 WeKnora API 创建一个knora://schema/Article实例。

Step 1：初始化 Rust 项目

cargo new rss-to-knora --lib cd rss-to-knora

Step 2：添加必要依赖（Cargo.toml）

[dependencies] reqwest = { version = "0.11", features = ["json"] } tokio = { version = "1.0", features = ["full"] } serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" wasi-experimental-http = "0.2" # 注意：不引入 `anyhow` 或 `thiserror`，因为 CubeSandbox 的 Wasm runtime 对 panic 处理有特殊要求

Step 3：编写核心逻辑（src/lib.rs）

// src/lib.rs use serde::{Deserialize, Serialize}; use std::collections::HashMap; // WeKnora 的 state schema，必须与 agent.yaml 中的定义完全一致 #[derive(Serialize, Deserialize, Debug, Clone)] pub struct State { pub last_fetched_timestamp: u64, // Unix timestamp pub processed_guids: Vec<String>, } // RSS item 结构 #[derive(Deserialize, Debug)] pub struct RssItem { pub title: String, pub link: String, pub pub_date: String, // RFC 2822 格式 } // WeKnora API 的 Article 创建 payload #[derive(Serialize)] pub struct KnoraArticle { #[serde(rename = "@type")] pub type_: String, pub title: String, pub url: String, pub published_at: String, } // Agent 的主入口函数，CubeSandbox 会调用此函数 #[no_mangle] pub extern "C" fn main() -> i32 { // 1. 从 WASI 环境获取 secrets let github_token = wasi_experimental_http::get_env("GITHUB_TOKEN").unwrap_or_default(); // 2. 从 WASI 环境加载 state let mut state: State = match wasi_experimental_http::get_state() { Ok(s) => s, Err(_) => State { last_fetched_timestamp: 0, processed_guids: vec![], }, }; // 3. 抓取 RSS（简化版，实际应加 timeout 和 retry） let rss_content = reqwest::blocking::get("https://example.com/feed.xml") .expect("RSS fetch failed") .text() .expect("RSS parse failed"); // 4. 解析 RSS（此处用伪代码，实际用 xml-rs 库） let items: Vec<RssItem> = parse_rss_items(&rss_content); // 5. 过滤出新文章（基于 pub_date > last_fetched_timestamp） let new_items: Vec<RssItem> = items .into_iter() .filter(|item| { // 将 RFC 2822 转为 Unix timestamp let ts = parse_rfc2822_to_unix(&item.pub_date); ts > state.last_fetched_timestamp }) .collect(); // 6. 逐个创建 Knora Article for item in new_items { let knora_payload = KnoraArticle { type_: "knora://schema/Article".to_string(), title: item.title, url: item.link, published_at: item.pub_date, }; // 调用 WeKnora API（实际 URL 从 KNORA_ENDPOINT 环境变量读取） let resp = reqwest::blocking::Client::new() .post("https://knora.example.com/v2/resources") .header("Authorization", format!("Bearer {}", github_token)) .json(&knora_payload) .send() .expect("Knora API call failed"); if resp.status().is_success() { state.processed_guids.push(item.link); // 记录已处理 } } // 7. 更新 state 的 last_fetched_timestamp 为当前时间 state.last_fetched_timestamp = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .unwrap() .as_secs(); // 8. 将更新后的 state 保存回 WASI wasi_experimental_http::set_state(&state).expect("State save failed"); 0 // 成功退出 }

Step 4：构建 Wasm 并签名

# 安装 wasm-target rustup target add wasm32-wasi # 构建 release 版本 cargo build --release --target wasm32-wasi # 生成 Wasm 文件（注意：不是 target/wasm32-wasi/release/*.wasm，而是 target/wasm32-wasi/release/deps/*.wasm） cp target/wasm32-wasi/release/rss_to_knora.wasm ./rss-to-knora.wasm # 用 WeKnora 的私钥签名（假设私钥在 ~/.weknora/agent.key） weknora-cli sign --key ~/.weknora/agent.key --input rss-to-knora.wasm --output rss-to-knora.wasm.signed

Step 5：部署到 CubeSandbox

# 将 signed wasm 和 agent.yaml 放到同一目录 cp rss-to-knora.wasm.signed /opt/cubesandbox/agents/ cp agent.yaml /opt/cubesandbox/agents/ # 通过 CubeSandbox API 注册 Agent curl -X POST http://localhost:8080/v1/agents \ -H "Content-Type: multipart/form-data" \ -F "yaml=@/