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

仓库：unicity-astrid/sdk-js
链接：https://github.com/unicity-astrid/sdk-js（重定向至 astrid-runtime/sdk-js）
分类：ai · wasm · developer-tools · operating-system
作者：Tom
更新：2026-07-15

这是什么

sdk-js 是 Astrid OS 的官方 JavaScript / TypeScript SDK，用于构建可在 Astrid 操作系统中运行的 Capsule（胶囊）。Capsule 是 Astrid 的核心应用格式——一种基于 WebAssembly（wasip2 Component Model）的可移植二进制包，既可以用 Rust 编写，也可以用 TypeScript 编写，运行在同一个内核之上。

该 SDK 由 Unicity Labs 开发维护，提供 @unicity-astrid/sdk（运行时 API）和 @unicity-astrid/build（构建编排）两个 npm 包。TypeScript 版本的 API 设计风格借鉴了 Node.js 社区熟悉的 node:fs/promises、WHATWG 和 EventEmitter，而非简单移植 Rust 风格。

注意：仓库原路径为 unicity-astrid/sdk-js，现重定向至 astrid-runtime/sdk-js，两者内容一致。

解决什么问题

Astrid 是一个新兴的操作系统级开源项目，核心理念是用 WASM 组件模型构建一个语言无关的应用生态——类似 WebAssembly 在浏览器中的跨语言能力，但扩展到桌面/服务器操作系统层面。

sdk-js 的出现让 熟悉 JavaScript/TypeScript 的开发者不需要学习 Rust 就能为 Astrid 编写原生应用（Capsule），同时产出的 .capsule 包和 Rust 版本完全二进制兼容，共享同一套 host ABI 和 IPC 协议。

典型使用场景： - 不想学 Rust 但想参与 Astrid 生态的前端/全栈开发者 - 需要多语言混合开发（Rust + TypeScript）Capsule 的系统架构师 - 对 WASM Component Model 感兴趣，想快速上手实验的开发者

快速安装

前置要求

Node.js ≥ 20（需支持 ESM 和 WASM 相关 API）
npm 或 pnpm
Rust 工具链（cargo、astrid-build，构建链的最后一环依赖 Rust 侧工具）

# 1. 创建项目目录
mkdir my-capsule && cd my-capsule
npm init -y

# 2. 安装 SDK 和构建工具
npm install @unicity-astrid/sdk
npm install --save-dev @unicity-astrid/build typescript

# 3. 创建 Capsule.toml（包配置）
cat > Capsule.toml << 'EOF'
[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 = ["*"]
EOF

# 4. 创建 TypeScript 源码
mkdir -p src

核心用法

编写一个最简单的 Capsule

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

@capsule
export class MyCapsule {
  private 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");
  }
}

核心 Decorators

Decorator	作用
`@capsule`	标记入口类，将 TypeScript 类编译为 WASM Component
`@tool(name, opts)`	暴露一个工具方法，供 IPC 调用；`mutable: true` 表示可修改状态
`@install`	生命周期钩子：Capsule 被安装时执行
`@upgrade`	升级钩子
`@command`	暴露命令行接口
`@interceptor`	拦截器，监控/修改 IPC 消息

可用模块（与 Rust SDK 对齐）

模块	功能
`fs`	文件系统访问
`net`	网络操作
`process`	进程管理
`env`	环境变量
`time`	时间操作
`log`	日志输出
`kv`	键值存储
`http`	HTTP 客户端/服务端
`ipc`	进程间通信
`hooks`	生命周期钩子
`uplink`	与宿主机通信
`identity`	身份认证
`approval`	权限审批
`capabilities`	能力声明与检查

构建流程

# 方法一：使用 Astrid CLI（需安装 astrid toolchain）
astrid build

# 方法二：直接调用 build CLI
node node_modules/@unicity-astrid/build/src/index.mjs examples/test-capsule

构建管线详解（TypeScript → .capsule 完整链路）：

src/*.ts
    ↓ tsc（类型检查 + 输出 dist/*.js）
    ↓ esbuild（将 @unicity-astrid/sdk 和所有依赖打包为单一 ESM）
    ↓ ComponentizeJS（将 ESM 转为 wasip2 WebAssembly Component）
target/<name>.wasm
    ↓ pack_capsule_archive（Rust 侧工具将 wasm + Capsule.toml + wit/ 打包）
dist/<name>.capsule   ← 最终产物

安装和运行

# 将 .capsule 包安装到本地 Astrid 内核
astrid capsule install ./dist/my-capsule.capsule

# 触发工具调用（示例）
astrid tool execute my-capsule.greet '{"name": "world"}'

包体积说明

⚠️ JS Capsule 约 11 MB 原始大小，压缩后（.capsule 归档）约 3.5 MB。这主要是 StarlingMonkey（WASM 运行时嵌入）的体积。

对比：Rust Capsule 同等功能仅约 200 KB。

如果包体积是核心约束（如频繁分发的轻量工具），建议使用 Rust SDK；如果追求开发效率和生态接入（ npm 生态），TypeScript 版本是更务实的选择。

典型使用场景

场景 1：快速原型开发

用 TypeScript 写一个 LLM 工具封装 Capsule，不需要懂 Rust 即可完成从代码到可分发二进制包的完整流程。

场景 2：多语言 Capsule 协作

Rust 团队写核心 Kernel-boundary 工具（性能关键路径），TypeScript 团队写业务逻辑胶水层，两边用同一套 .capsule 接口协议互通。

场景 3：探索 WASM Component Model

Astrid 的 wasip2 Component Model 和 WIT（WebAssembly Interface Types）是 W3C WASM 小组推进的标准。Astrid SDK-js 是目前最完整、最可运行的 wasip2 示例之一，学习价值高。

坑与注意

Alpha 状态：该 SDK 处于早期开发阶段（README 明确标注 "Alpha"），API 可能在后续版本中有破坏性变更，不建议直接用于生产环境。
依赖 Rust 工具链：最终构建产物（.capsule）依赖 Rust 侧的 astrid-build 工具，npm 包本身只负责 ts → wasm 这前半段，完整工具链需要本地装 Rust。
Node.js ≥ 20 硬性要求：较早版本缺少必要的 ESM 和 WASM 相关 API 支持。
Capsule 分发体积：JS 版本 3.5 MB（压缩后）比 Rust 版本重约 17 倍，在网络分发频繁场景下需评估成本。
文档尚不完整：Phase 开发笔记（notes/phase-*.md）有详细设计决策记录，但面向最终用户的 API 文档较稀缺，很多细节需要读源码或对照 Rust SDK 理解。
WASM 调试困难：WASM 组件的调试体验不如原生代码，stack trace 常常不完整。

与同类对比

项目	语言	WASM 支持	成熟度	生态
Astrid SDK-JS	TypeScript	wasip2 Component Model	Alpha	新兴，npm 生态
Bun.sh	JavaScript/TypeScript	内置 WASM 集成	稳定	成熟
wasmtime (Rust)	任意（WASM）	wasip2	稳定	成熟
WASI SDK	C/C++/Rust	WASI	稳定	系统编程

Astrid 的差异化在于操作系统的原生抽象（文件、网络、进程、IPC）而不是单纯的运行时。相比 Docker 容器，Capsule 具备更细粒度的能力声明和更强的可移植性。

一句话推荐结论

如果你是 TypeScript/Node.js 开发者，想为 Astrid OS 写原生应用或实验 WASM Component Model，sdk-js 提供了目前最低门槛的入口，接受其 Alpha 状态和包体积约束即可快速上手。

来源：GitHub README (astrid-runtime/sdk-js)、README 代码示例、Capsule 构建管线文档