astrid

# 阿斯特里德 <p align="center"> <img src="assets/astrid-github-preview.png" alt="阿斯特里德" width="640"> </p> **一款适用于组合软件的便携、能力安全的操作系统。** [](https://github.com/astrid-runtime/astrid/actions/workflows/ci.yml) [](https://github.com/astrid-runtime/astrid/actions/workflows/codeql.yml) [](#license) [](https://www.rust-lang.org) [](https://www.rust-lang.org) [](https://github.com/astrid-runtime/book) --- 阿斯特里德将组件视为操作系统对待进程的方式。每个能力都是一个密封的WebAssembly **capsule**：它可以与其它capsule组合，授予明确的权限，并且在不扩展其范围的情况下替换。阿斯特里德独立于任何特定产品、模型提供商、代理循环、用户界面或分发。 其底层的内核很小且故意设计得很简单。它路由事件、强制执行能力、运行沙箱并记录审计跟踪；它不持有任何模型、工具模式或业务逻辑。 Jailbreak、毒化工具或普通错误仍然无法读取文件、访问网络或在其授予之外生成进程。权限是内核强制执行的能力，而不是模型被信任遵循的指令。 ## 快速开始 ```bash brew tap astrid-runtime/tap && brew install astrid astrid start astrid status astrid capsule list ``` 从 [The Book](https://github.com/astrid-runtime/book) 开始，了解架构；或者从 [Contributor Handbook](https://github.com/astrid-runtime/handbook) 开始，参与贡献。 ## 为什么存在阿斯特里德 代理框架将信任放在提示中。阿斯特里德将信任放在运行时。一个代理是运行在您机器上的不受信任的代码，具有访问您的文件、网络和凭证的权限。告诉它行为良好不是一个安全边界。操作系统级别的边界才是。 - **加密能力模型。** 每个文件路径、网络主机和工具都是一个签名的 ed25519 授予，范围限定为资源模式，主体绑定，过期检查和全局可撤销。无授予，无访问。 - **没有环境权限的WASM沙箱。** Capsule在Wasmtime中运行，没有系统调用，没有文件描述符，没有主机内存。每个外部效果都是一个能力检查的主机调用，覆盖WIT类型的ABI。 - **内核很简单。** 它实例化一个事件总线，加载capsule，并路由IPC字节，在能力ACL下。它没有LLM句柄，没有会话状态，没有工具注册表。所有智能都生活在capsule中，因此capsule错误不会破坏共享内核状态。 - **每个主体的所有内容。** 每个身份都获得隔离的capsule访问，KV数据，秘密，家目录，配额和审计链。一个主体永远无法读取另一个主体的命名空间，如果调用者无法解析，则关闭。 - **签名的，哈希链接的审计链。** 每个条目都密封了前一个条目的哈希，并签名。破坏链条，篡改就会被发现。 - **实时capsule生命周期。** 在运行的守护进程上安装、升级和删除capsule。无需重启。 ## 工作原理 前端（CLI、HTTP网关、Discord等）是 **uplinks**：连接到守护进程的协议客户端，通过Unix域套接字进行通信，使用IPC事件进行通信。没有`Frontend`特质。uplink发布事件并像其他总线参与者一样接收响应。 ```mermaid flowchart TB CLI[CLI] -->|IPC events over Unix socket| Kernel HTTP[HTTP gateway] -->|IPC events| Kernel Discord[Discord] -->|IPC events| Kernel Uplinks[Other uplinks] -->|IPC events| Kernel subgraph Runtime[Astrid] Kernel[Kernel: astrid-daemon<br/>dumb event router<br/>event bus - capability ACL - audit chain - Wasmtime sandbox] Capsules[WASM Component capsules: wasm32-unknown-unknown<br/>providers - orchestrators - tools - fs - http - sessions - registry - identity] end Kernel -->|capability-checked host calls<br/>astrid:* WIT ABI| Capsules ``` capsule之间仅通过总线进行通信。每个capsule都声明了它需要和提供的内容，位于`Capsule.toml`清单中，带有类型化的`[imports]`/`[exports]`表格；内核通过拓扑排序解析依赖图，并按顺序启动capsule。工具是一种IPC约定，而不是内核概念：工具capsule拦截`tool.v1.execute.<name>`，内核从未看到工具模式。 主机ABI是WebAssembly组件模型，带有版本的`astrid:*`WIT包：`fs`、`io`、`kv`、`ipc`、`net`、`http`、`sys`、`process`、`approval`、`identity`、`elicit`和`uplink`。客人仅导入其清单允许的内容，每个调用都在边界处进行能力检查。 ## 安全模型 阿斯特里德的安全性是分解的。没有单个阀门可以控制所有操作。capsule没有环境权限，授权由独立的、按区域划分的机制强制执行，每个机制都是封闭的，并且在实际发生影响的地方执行。 ```mermaid flowchart TB Action[A capsule action] --> Sandbox[WASM sandbox<br/>no syscalls, file descriptors, or host memory<br/>external resources are capability-checked host calls] Action --> Manifest[Manifest gate<br/>declared file, network, and process allow-list<br/>empty is deny-all; path traversal and SSRF defenses] Action --> IPC[IPC ACL<br/>declared publish and subscribe topics only<br/>per-principal routing] Action --> Capability[Capability token<br/>ed25519, principal-bound, scoped, expiring, revocable<br/>per-device tokens can be subset-scoped] Action --> Approval[Approval gate<br/>once - session - always - deny<br/>allow always mints a token; local egress elicits consent] Action --> OS[OS sandbox<br/>bwrap on Linux - seatbelt on macOS for native subprocesses] Action --> Audit[Audit chain<br/>signed, hash-linked JSONL decisions and calls<br/>split per principal and independently verifiable] ``` 这些机制是真实且独立测试的。没有统一的拦截器来协调它们。 [五层阀门](https://github.com/astrid-runtime/book) 章节介绍了The Astrid Book中的每个层级。 ## 安装 **Homebrew（macOS和Linux）：** ```bash brew tap astrid-runtime/tap brew install astrid ``` **从crates.io（需要Rust 1.95+）：** ```bash cargo install astrid ``` **从源码：** ```bash git clone https://github.com/astrid-runtime/astrid cd astrid && cargo build --release # binary at ./target/release/astrid ``` 阿斯特里德安装了四个二进制文件，它们一起工作。您只需要调用`astrid`；它启动和管理其余部分。 | 二进制文件 | 角色 | |---|---| | `astrid` | CLI uplink。连接到守护进程的Unix套接字。TUI，headless模式，capsule和agent管理。 | | `astrid-daemon` | 内核进程。加载capsule，路由IPC，强制执行能力，运行沙箱。 | | `astrid-build` | Capsule编译器和打包器。编译为`wasm32-unknown-unknown`。 | | `astrid-emit` | Stdio-to-bus桥，用于外部钩子生产者。 | ## 初始设置 `astrid init`获取一个*distro*（一个精选的capsule包），呈现提供者多选，并提示每个提供者所需的凭据，包括其API密钥。秘密存储在每个主体的秘密存储中，从不通过命令行传递。`init`写入一个`Distro.lock`，锁定每个capsule的BLAKE3哈希，以便相同的`init`重现相同的fleet。 ```bash astrid init # interactive: pick provider(s), enter keys astrid init --yes # non-interactive, accept defaults astrid init --offline ./bundle.shuttle # install a signed bundle, no network astrid init --distro @yourorg/your-distro ``` 在入职过程中，模型字段从提供者的`/v1/models`端点发现其活模型列表。在`init`之后，请确认代理循环已就绪，然后与其对话： ```bash astrid doctor # daemon up? capsules ready? an LLM available? astrid chat # interactive session; the daemon auto-starts on first use astrid models # list the current provider's models (a registry-capsule verb) ``` ### 无头和脚本 ```bash astrid -p "summarize the git log" # single prompt, prints and exits git diff HEAD~1 | astrid -p "write a commit message" # stdin is appended to the prompt astrid -p "fix all failing tests" --yes # auto-approve tool requests astrid -p "continue" --session "$SID" # resume by id or name ``` ### 守护进程生命周期 ```bash astrid start # persistent daemon (survives terminal close) astrid status # PID, uptime, connected clients, loaded capsules astrid ps # loaded capsules and their lifecycle state astrid stop # graceful shutdown astrid update # download, verify, and stage the latest release (self-update alias) ``` ## 按主体隔离 每个主体（代理身份）都是一个完全隔离的租户：它自己的capsule访问，KV命名空间，秘密，家目录，配额和审计链。新主体默认情况下不会继承任何内容。 ```bash astrid agent create ci-bot # clean-slate, least-privilege agent astrid agent create staging --clone production # full profile + state replica astrid agent modify ci-bot \ --add-capsule astrid-capsule-fs # grant access to a capsule's tools astrid caps show ci-bot # inspect capability grants astrid quota set -a ci-bot --memory 128MB # per-principal resource limits astrid pair-device issue --scope use-only # scope a device token to a subset ``` capsule访问在调度时由内核强制执行。主体只能调用显式授予给它的capsule，两个主体安装相同的capsule字节共享一个内容寻址的磁盘工件，同时获得单独的内存运行时实例。 ## 编写capsule capsule是一个由清单描述的WASM进程。脚手架生成一个首次编译的项目，针对`wasm32-unknown-unknown`，以及一个`AUTHORING.md`指南。 ```bash astrid capsule new my-capsule # scaffold Capsule.toml, Cargo.toml, src/lib.rs, .cargo/config.toml cd my-capsule astrid capsule build # compile and package astrid capsule install . # hot-loaded into the running daemon, no restart ``` capsule作者依赖于 [`astrid-sdk`](https://github.com/astrid-runtime/sdk-rust)，它镜像了`std`模块布局（`fs`、`net`、`process`、`env`、`time`、`log`）并添加了Astrid模块（`ipc`、`kv`、`http`、`hooks`、`uplink`、`identity`、`approval`）。`#[capsule]` proc宏生成WASM ABI样板：导出、序列化以及工具、命令、钩子和生命周期入口点的调度。 ```rust use astrid_sdk::prelude::*; #[derive(Default)] struct Weather; #[capsule] impl Weather { #[astrid::tool] fn forecast(&self, args: ForecastArgs) -> Result<Forecast, SysError> { let key = env::var("WEATHER_API_KEY")?; let body = http::get(&format!("https://api.example.com/wx?q={}", args.city))?; Ok(serde_json::from_slice(&body)?) } } ``` 构建capsule是Astrid中的一流工作流。 Forge（`astrid capsule new`加上作者工具和脚手架技能）是登机通道；方向是一个编写、构建和安装自己的capsule的主体，在能力沙箱内。 ### 实时capsule生命周期 ```bash astrid capsule install @org/capsule-name # install and hot-load astrid capsule update my-capsule # hot-swap the running instance astrid capsule remove my-capsule # live-unload, no restart astrid capsule list --verbose # installed capsules with capability metadata astrid capsule tree # imports/exports dependency graph ``` ## 0.9中的新增功能 五个工作成果加上安全强化通道。有关完整列表，请参见 [CHANGELOG.md](CHANGELOG.md)。 - **实时capsule生命周期。** 热点加载安装，热点交换升级，实时卸载删除，所有操作无需守护进程重启。 - **每个主体的隔离，强化端到端。** 主体视图感知capsule加载，内容寻址工件重用，内核端工具表面访问强制执行，每个设备的能力范围贯穿HTTP网关。 - **LLM提供者和模型绑定。** 多提供者入职，实时模型发现，以及网关路由和`astrid models` / `astrid doctor`用于每个主体的模型管理和循环就绪检查。 - **通过HTTP网关的对话线程。** 列出、获取、更新、删除和全文搜索线程，以及每个主体的实时对话提要，并在总线上强制执行跨主体隔离。 - **`astrid:http@1.1.0`和操作员可配置的限制。** 每个请求的超时、重定向策略、正文上限、`https-only`和子资源完整性；七个以前硬编码的上限成为操作员旋钮。 - **安全。** 本地出口同意（传输源标记，运行时诱导，每个capsule和每个主体的授予），一个SSRF隔离器，关闭IP字面和重定向绕过，以及一个强化的供应链路径（Sigstore attestation，CodeQL，固定的Action SHAs，权限最小的令牌）。 ## 文档 - **[The Astrid Book](https://github.com/astrid-runtime/book)** 是规范参考：内核、capsule模型、主机ABI、总线和安全模型，基于源码并带有文件和行锚。从 [Getting Started](https://github.com/astrid-runtime/book) 开始，几分钟内从零开始建立一个工作代理。 - **操作员指南** 位于 [`docs/`](docs/)：统一的配置模式、 [LLM模型选择](docs/models.md)、 [distro签名](docs/distro-signing.md)、 [网关部署运行手册](docs/gateway-deployment.md)和 [生成网关客户端](docs/gateway-client.md)。 ## 开发 ```bash cargo build --workspace cargo test --workspace -- --quiet cargo clippy --workspace --all-features -- -D warnings cargo fmt --all -- --check ``` 所有crate都强制执行 `#![deny(unsafe_code)]`，除了`astrid-sys`和`astrid-sdk`，其中WASM FFI需要它。Clippy以吹毛求疵的级别运行，整数溢出算术是lint错误。macOS和Linux（x86_64和aarch64）的发布二进制文件在标签推送时构建，并使用keyless Sigstore attestations签名。 ## 贡献 欢迎贡献。Astrid使用分层贡献者系统，保护安全关键代码，同时为新贡献者敞开大门。每个拉取请求必须链接到GitHub问题。有关问题优先的工作流和层描述，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 更改任何合同表面（主机ABI、IPC协议、能力模型、清单模式或SDK公共API）都需要RFC流程，在实施之前在 [RFCs repository](https://github.com/astrid-runtime/rfcs) 中进行。 ## 许可证 在 [MIT](LICENSE-MIT) 和 [Apache 2.0](LICENSE-APACHE) 下双重许可，由您选择。 Copyright (c) 2025-2026 Joshua J. Bouw and Unicity Labs.