ALTWEB Context Loader

ALTWEB — 已签名的上下文胶囊

为 AI Agent 提供已签名的上下文胶囊——将 Markdown 编译为独立、可验证、可选加密的制品，并配备一个拒绝未签名或不受信任上下文的 MCP 加载器。注入前先验证。

AI Agent 基于纯文本上下文运行：指令、角色设定、技能、记忆文件。这些内容都没有来源证明——任何能写入这些文件的对象都能污染它们。ALTWEB 为上下文提供完整的保管链，并让加载器拒绝任何缺少保管链的内容：

• 胶囊 — 将 Markdown 编译为单个 .altweb.html 文件（或 URL）：内容经过压缩（deflate），可选加密（AES-256-GCM），也可选签名（ECDSA P-256）。独立运行——可在任何浏览器中打开、离线验证，无需服务器：你交给别人的是文件，而不是数据库。
• 已验证的上下文加载 — 只有签名有效且签名者的公钥位于你的信任文件中时，altweb-context MCP 服务才会将胶囊加载到你的 Agent 中。未签名、遭篡改或不受信任的胶囊会在加载时被拒绝，并明确说明原因。默认拒绝：空的信任文件会拒绝所有内容，无论是否已签名。

you write MD ──► altweb compile --sign ──► capsule (.altweb.html / URL)
                                              │
agent asks for context ──► altweb-context ──► verify signature + trust
                                              │
                              trusted ──► markdown injected
                          everything else ──► REFUSED (reason)

软件包

软件包	说明
altweb	命令行工具：altweb compile / decode / verify / keygen（packages/cli）
altweb-context	MCP 服务：load_capsule、verify_capsule、list_trusted_keys（packages/mcp）
@altweb/core	无头引擎：内容模型、编解码器、加密、Markdown、清理（打包在两个软件包中；计划发布到 npm）
@altweb/editor	类 Notion 编辑器（基于 Novel 构建），支持一键导出胶囊
site/	文档站点（Astro + Starlight）

快速入门

这两个工具都已发布到 npm——无需克隆。在源代码检出目录之外运行以下命令（在此仓库内运行时，npm 会解析到本地工作区软件包）：

# create your signing identity (deterministic from a passphrase; only the
# public key + fingerprint are stored, in ~/.altweb/identity.json)
npx altweb keygen --save

# write, compile, sign
echo "# My agent's operating notes" > notes.md
npx altweb compile notes.md -o notes.altweb.html --sign

# verify anywhere, offline
npx altweb verify notes.altweb.html

将加载器接入 MCP 客户端（Claude Code 示例）：

claude mcp add altweb-context -- npx -y altweb-context

（从源代码运行：执行 npm install && npm run build，然后使用 packages/*/dist/ 下的打包文件。）

从源代码运行

需要 Node.js 20 或更高版本。在仓库根目录中运行：

npm install
npm run build

# Create and save an identity with the locally built CLI
npm run keygen

# Start the editor in development mode
npm run dev

编辑器会显示本地 URL（通常为 http://localhost:5173）。可以通过 node packages/cli/dist/altweb.mjs <command> 调用命令行工具。请勿在检出目录中使用 npx altweb：npm 可能会选择本地工作区软件包，而该软件包的可执行文件要等到构建后才会存在。

文档站点有意作为独立的 npm 项目，而非工作区。要在本地运行：

npm install --prefix site
npm run dev --prefix site

将签名者的完整公钥添加到 ~/.altweb/trusted-keys.json，即可信任该签名者（UNTRUSTED_KEY 拒绝消息会提供可直接使用的条目；短指纹只是便于人识别的标签，并非信任锚点）：

{ "keys": [ { "name": "Me", "publicKey": "<base64url SPKI>", "fingerprint": "ab:12:..." } ] }

签名能证明什么——不能证明什么

有效签名可以证明胶囊由谁创作，以及字节内容未被篡改。它不能证明内容安全或属实。信任文件代表你的策略；请保持条目精简。

请选择高强度密码短语。 身份通过 Argon2id 和固定的协议盐从你的密码短语确定性地派生（因此无需存储任何信息即可移植）。内存困难特性会大幅提高大规模字典攻击的成本，但密码短语的熵仍然是身份的根基。请使用至少 16 个字符的 Diceware 风格短语；工具会强制要求达到最低强度。

安全性

解码时会使用 DOMPurify 清理内容；制品带有 CSP；编解码器使用 zod 验证结构。完整说明请参阅 site/ 文档 → 安全模型，其中包括加密胶囊的注意事项（签名覆盖解密后的负载，因此必须在解密后才能完成验证）。

路线图

近期计划，按大致优先级排列：

• @altweb/core 发布到 npm —— 将引擎作为可安装的库，供程序化使用（CLI 和加载器已将其打包在内）。
• 硬件支持的身份验证（FIDO2 / passkeys） —— 作为口令身份之外的可选身份类型：私钥存储在安全密钥或安全隔区中，永远无法导出；签名需要用户实际操作。口令身份仍是默认选项——“口令就是密钥对”——硬件密钥则为有此需求的用户增添持有之物这一要素。

致谢

本项目基于出色的开源项目构建：Novel（Apache-2.0）和 Tiptap（MIT）用于编辑器；引擎中使用了 DOMPurify、marked、pako、zod、@noble/curves。详见 NOTICE。

许可证

ALTWEB 采用双重许可：

• 开源：AGPL-3.0-or-later。 可免费使用、研究、修改和分享——但须履行一项核心义务：如果你修改 ALTWEB 并分发修改后的版本，或将其作为网络服务运行（例如为他人托管 altweb-context），就必须依据 AGPL 发布修改后的源代码。
• 商业许可：另行协商。 若要在闭源产品中使用 ALTWEB，或将其作为托管服务提供而不公开你的修改，则需要单独的商业许可证。详见 COMMERCIAL.md。

版权所有 © 2026 Daniel C. ȘOIMU。打包的第三方组件仍适用各自的（宽松型）许可证——详见 NOTICE。