astrid-runtime/sdk-js · 上手攻略

• 仓库：astrid-runtime/sdk-js
• 链接：https://github.com/astrid-runtime/sdk-js
• 分类：ai · wasm · runtime · component-model
• 作者：Tom
• 更新：2026-07-15

这是什么

sdk-js 是 Astrid（一个分布式 AI capsule 运行时）的官方 JavaScript / TypeScript SDK，用于将 TypeScript 代码编译为 WASM 组件（.capsule 格式）并被 Astrid 内核加载执行。

Astrid 是一个新兴的开放协议项目，核心设计思想是「kernel-is-dumb」：内核只负责加载、安全隔离和生命周期管理，业务逻辑全部封装在独立的 capsule（.capsule 归档文件）中。Astrid 的核心理念是让 AI 工具以标准化 capsule 形式分发、安装和运行，不同语言写的 capsule（目前有 Rust 和 JS）互相兼容。

sdk-js 的目标：用开发者更熟悉的 TypeScript 生态来写 Astrid capsule，而不是必须用 Rust。

解决什么问题

• 跨语言 capsule 生态：Astrid 的 Rust SDK（sdk-rust）先出，sdk-js 补齐了 TS/JS 开发者这一环，同一个 capsule 可以用两种语言写
• 标准化的 AI 工具封装：capsule 是 Astrid 分发 AI 工具的标准格式，sdk-js 让 TS 开发者参与这一生态
• WASM 安全沙箱：capsule 运行在 WASM 沙箱里，有明确的主机 ABI（文件系统、网络、KV 存储等），安全边界清晰
• 统一发布格式：.capsule 归档（gzip 压缩的 tar，含 Capsule.toml 配置和 .wasm 文件）跨平台、跨语言

快速安装

环境要求

• Node.js ≥ 20
• TypeScript
• Rust 工具链（cargo，用于调用 Astrid 核心构建工具 astrid-build）

⚠️ sdk-js 构建流程需要调用 Rust 侧的 astrid-build，因此本地完整构建需要 Rust 工具链。纯 JS 开发者可以用预构建好的 capsule 文件。

安装

mkdir my-capsule && cd my-capsule
npm init -y
npm install @unicity-astrid/sdk
npm install --save-dev @unicity-astrid/build typescript

项目配置

Capsule.toml:

[package]
name = "my-capsule"
version = "0.1.0"

[[component]]
id = "my-capsule"
file = "my-capsule.wasm"
type = "executable"

[capabilities]
ipc_publish = ["tool.v1.execute.*"]
kv = ["*"]

编写 Capsule 代码

src/index.ts:

import { capsule, tool, install, log, kv } from "@unicity-astrid/sdk";

@capsule
export class MyCapsule {
  greetings = 0;

  @tool("greet", { mutable: true })
  greet({ name }: { name: string }): { message: string; count: number } {
    this.greetings++;
    log.info(`greeting ${name} (#${this.greetings})`);
    return { message: `Hello, ${name}!`, count: this.greetings };
  }

  @install
  onInstall(): void {
    log.info("my-capsule installed");
  }
}

说明：@capsule 装饰器声明一个 capsule 类；@tool 暴露一个工具方法；@install 定义安装钩子；mutable: true 表示该工具可以修改 capsule 内部状态。

构建

astrid build   # 或: astrid capsule install .

构建流水线：

src/*.ts
  ↓ tsc（类型检查 + emit JS）
  ↓ esbuild（打包 + SDK 抹平）
  ↓ ComponentizeJS（StarlingMonkey 运行时 → wasip2 Component）
target/<name>.wasm
  ↓ pack_capsule_archive（Rust 侧 astrid-build）
dist/<name>.capsule（Capsule.toml + .wasm + wit/，gzip 压缩 tar）

核心 API 概览

装饰器

主机 ABI 模块（可通过 import 访问）

构建输出

JS capsule 打包后约 11MB raw / 3.5MB gzipped（包含 StarlingMonkey 运行时）。Rust capsule 约 200KB。如果在意体积，建议用 Rust；JS 的优势是开发体验而非交付体积。

典型适用场景

1. Astrid 生态贡献者：想为 Astrid 写 capsule 但不熟悉 Rust
2. AI 工具封装：想把一个 AI 能力封装成分发包，用 TS 写比 Rust 更直观
3. 跨语言 capsule 开发：团队 TS 开发者为主，部分 capsule 用 Rust 写性能关键路径
4. WASM Component Model 探索：想了解 wasip2 和 ComponentizeJS 的实际工程用法

坑与注意

• 当前状态为 Alpha：端到端链路（TypeScript → WASM → .capsule → 安装 → 生命周期钩子）已跑通，但工具调用等高级功能处于「准备就绪，等待人工 smoke test」阶段，不建议直接用于生产
• 需要 Rust 工具链：完整构建依赖 astrid-build（Rust 编写），纯 Node.js 开发者需要额外安装 Rust（rustup）
• 包名 @unicity-astrid/sdk：注意不是 astrid-runtime/sdk，发布在 npm 上的是 @unicity-astrid 组织下的包
• ComponentizeJS 限制：WASM Component Model 有特殊约束（如 WIT 接口定义、external 标记），不熟悉 WASM 的 TS 开发者需要理解 wasip2 接口语义
• 文档分散：SDK 文档主要是代码注释和 notes/phase-*.md 开发笔记，官方文档（book、handbook）在各自的 astrid-runtime 仓库
• StarlingMonkey 运行时开销：JS capsule 的体积（~11MB）比 Rust（~200KB）大 50 倍，在资源受限环境要谨慎
• 需要参考 Astrid 核心项目：sdk-js 是 Astrid 的 JS 语言绑定，要理解整个系统需要同时阅读 astrid-runtime/astrid 和 astrid-runtime/sdk-rust

与同类对比

Astrid sdk-js 是一个专有生态的 SDK，它的价值在于 Astrid 协议本身，而非独立的 JS/WASM 工具链。如果你对 Astrid 开放协议感兴趣，或者想参与分布式 capsule 运行时生态，sdk-js 提供了和 Rust SDK 完全等价的能力；如果你只是想在 Node.js 里调用 AI 模型，有更成熟完整的方案（如 Vercel AI SDK、LangChain.js）。

一句话推荐结论

sdk-js 是 Astrid capsule 生态的 TypeScript 语言入口，适合想以 TS/JS 而非 Rust 参与 Astrid 开放协议建设的开发者——但目前仍在 Alpha 阶段，建议先读 handbook 和 book 理解 Astrid 全貌再动手。

注意：本文基于 astrid-runtime/sdk-js GitHub README 整理。该项目处于 Alpha 阶段，API 和工具链可能快速迭代，不建议直接用于生产环境。Astrid 生态有多个关联仓库（astrid、sdk-rust、book、handbook），建议配套阅读以获得完整上下文。