zerkerlabs/treeship

## 问题所在 AI agent 正在执行实际工作——部署代码、处理交易、做出决策。但当有人问*“agent 实际上做了什么？”*时，答案通常是一份聊天记录。聊天记录是可以编辑的、可以截图的、可以否认的。它们只是故事，而不是证据。 **Treeship 生成证据。**每个 agent 动作都会获得一份经签名、带时间戳、便携的回执，任何人都可以独立验证它——无需信任 Treeship，无需创建账号，也无需网络访问。 ## 30秒演示 ``` # 安装 + 初始化（一次性） curl -fsSL treeship.dev/setup | sh # 包装任何命令 — 获取已签名的 receipt treeship wrap -- npm test # → artifact art_abc123: npm test, exit 0, 4.2s, signed key_xyz # 离线验证 receipt treeship verify last # → ✓ signature valid ✓ chain valid ✓ 1 artifact # 分享公开的 verify URL treeship hub push last # → https://treeship.dev/verify/art_abc123 ``` 这就是整个核心循环。其他所有内容都基于此构建。 ## Treeship 的独特之处 | | Treeship | 审计日志 | 平台原生 (GitHub, Vercel) | Sigstore / in-toto | |---|---|---|---|---| | **跨基础设施便携** | ✅ 独立的 JSON | ❌ 绑定到日志系统 | ❌ 绑定到平台 | ✅ 但实现复杂 | | **离线工作** | ✅ 纯 WASM 验证器 | ❌ 需要日志服务器 | ❌ 需要 API | ⚠️ Rekor 需在线 | | **无需账号 / API key** | ✅ DPoP 认证（无 bearer key） | ❌ 通常需要访问权限 | ❌ 需要平台认证 | ✅ 无密钥签名 | | **默认隐私保护** | ✅ SHA-256 哈希，而非原始内容 | ❌ 通常存储完整数据 | ❌ 存储完整数据 | ⚠️ 可配置 | | **Agent 原生** | ✅ 专为 agent 工作流构建 | ❌ 通用日志记录 | ❌ 以平台为中心 | ⚠️ 需要集成 | | **多运行时** | ✅ Rust / TS / Python / Go / WASM | ❌ 通常是单一运行时 | ❌ 特定于平台 | ✅ 多语言支持 | ## 安装 ### CLI（你始终需要的二进制文件） ``` # One-liner：安装 CLI，运行 treeship init，并对其检测到的任何 AI agents 进行插桩 # （Claude Code, Cursor, Hermes, OpenClaw） curl -fsSL treeship.dev/setup | sh # 或通过 npm（可检查、已签名的 package，无 shell pipe） npm install -g treeship ``` `/setup` 和 `/install` 都是 POSIX shell 脚本。请参阅[支持的平台矩阵](https://docs.treeship.dev/guides/install#supported-platforms)——支持 macOS arm64/x64 和 Linux x86_64（截至 v0.10.1，任何发行版、glibc 或 musl 均通过单个静态链接的二进制文件支持）。Linux ARM64 尚未发布。Windows 原生不支持；请使用 WSL。 ### Claude Code 插件（推荐 Claude Code 用户使用） ``` claude plugin marketplace add zerkerlabs/treeship claude plugin install treeship@treeship ``` 此后，带有 `.treeship/` 目录的项目中的每个 Claude Code 会话都会自动记录到便携、经签名的回执中。插件的 SessionStart / PostToolUse / SessionEnd 钩子会自动触发——无需记住 `treeship session start`，也无需手动包装。 完整设计请参阅 [`integrations/claude-code-plugin/`](./integrations/claude-code-plugin/)。 ## 60秒内获取第一份回执 ``` treeship init # one-time, per machine treeship session start # opens a recording session treeship wrap -- npm test # captures the command + its exit code + file writes treeship session close # seals the receipt treeship session report # uploads + prints a shareable URL ``` 或者，如果安装了 Claude Code 插件：只需在执行过 `treeship init` 的项目中打开 Claude Code。会话将自动启动并密封。 ## 你将获得什么 - **签名回执** —— 基于 RFC 8785 规范 JSON 的 Ed25519 签名（DSSE 信封，兼容 in-toto） - **自动链接** —— 每个回执都链接到前一个回执的哈希 - **Merkle 包含证明** —— 与回执打包在一起以供离线验证 - **仅哈希 payload** —— 默认情况下，回执存储的是参数和输出的 SHA-256 哈希，而非原始内容 - **审批绑定** —— `treeship attest action --approval-nonce` 将人工审批与其授权的操作关联起来 - **本地优先** —— 一切皆可离线工作；hub 是发布平台，而非托管者 - **离线验证** —— `treeship package verify` 是纯 WASM，无需网络 - **多运行时 SDK** —— TypeScript、Python、Go (hub)、Rust 核心；验证器可在 Node、Deno、浏览器、Vercel Edge、Cloudflare Workers、AWS Lambda 上运行 ## 信任模型 Treeship 不会全局决定信任。每个验证者都根据本地策略决定信任。 - 信任源于密钥 + 你的策略，而非 Treeship 服务器 - 回执是独立的包——在任何地方验证，无需回调 Treeship API - 注重隐私的默认设置：payload 经过哈希处理，不存储原始数据 - Hub 连接是可选的，并按回执进行 opt-in 有关 `@treeship/mcp` 实际捕获内容的详尽说明（每种 artifact 类型中的每个字段），请参阅 [`TREESHIP.md`](./TREESHIP.md)。这是一份通用的信任和新手引导文档，任何 AI agent 都可以在使用前阅读它以评估 Treeship。 ## 工作原理 ``` Agent / human action │ ▼ Treeship core │ ├─ Canonicalize payload (RFC 8785) ├─ Hash inputs/outputs (SHA-256) ├─ Link to previous receipt ├─ Sign with Ed25519 └─ Append to Merkle log │ ▼ Local receipt store (.treeship/) │ ├─ Bundle builder ├─ Checkpoint (signed Merkle root) ├─ Verifier (pure WASM) └─ Optional: hub publish ``` 验证运行五项检查：签名（DSSE 信封）、链完整性（每个回执都链接到其父回执）、Merkle 包含、checkpoint 签名以及策略。全部离线进行。 ## 软件包 ### Rust crate (crates.io) | Crate | 路径 | 描述 | |---|---|---| | `treeship-core` | `packages/core/` | 回执引擎、签名、Merkle 树、验证 | CLI 通过 `treeship` npm 包装器分发（该包装器会自动获取适合该平台的二进制文件），而不是作为单独的 cargo install。 ### npm 包 | 包 | 路径 | 描述 | |---|---|---| | `treeship` | `npm/treeship/` | 自动安装正确平台二进制文件的 CLI 包装器 | | `@treeship/sdk` | `packages/sdk-ts/` | TypeScript SDK（封装了 WASM 验证器） | | `@treeship/mcp` | `bridges/mcp/` | MCP bridge —— 只需修改一行 import，每次工具调用都会获得经签名的回执 | | `@treeship/a2a` | `bridges/a2a/` | A2A bridge —— 验证附加在 agent 间消息上的回执 | | `@treeship/verify` | `packages/verify-js/` | 零依赖验证包（WASM + fetch） | | `@treeship/core-wasm` | `packages/core-wasm/` | 编译为 WebAssembly 的 Rust 核心（gzip 后 167 KB） | ### PyPI | 包 | 路径 | 描述 | |---|---|---| | `treeship-sdk` | `packages/sdk-python/` | Python SDK | ### Hub 服务器 (Go) 参考 hub 服务器位于 `packages/hub/`，运行在 。支持自托管，但目前并不常见。 ### Claude Code 插件 | 路径 | 描述 | |---|---| | `integrations/claude-code-plugin/` | 可通过 Marketplace 安装的插件：SessionStart/PostToolUse/SessionEnd 钩子 + MCP server + 技能 | | `.claude-plugin/marketplace.json` | 仓库根目录下的 Marketplace 清单 | 使用 `claude plugin marketplace add zerkerlabs/treeship && claude plugin install treeship@treeship` 安装。 ### 其他 agent 集成 | 路径 | 描述 | |---|---| | `integrations/claude-code/` | 手动 Claude Code 接线（CLAUDE.md 模板 + MCP config）——适用于不想要该插件的用户 | | `integrations/cursor/` | Cursor MCP 接线 | | `integrations/hermes/` | Hermes 技能 | | `integrations/openclaw/` | OpenClaw 技能 | ## SDK 示例 ### TypeScript ``` import { Ship } from "@treeship/sdk"; const ship = await Ship.init("./.treeship", "agent://researcher"); const { receipt } = ship.attestAction({ actor: { type: "agent", id: "agent://researcher" }, actionType: "tool.call", actionName: "search.web", inputs: JSON.stringify({ query: "AI safety" }), outputs: JSON.stringify({ results: ["paper1"] }), }); ship.attestHandoff({ fromActor: { type: "agent", id: "agent://researcher" }, toActor: { type: "agent", id: "agent://executor" }, taskCommitment: "complete-purchase", }); ship.createCheckpoint(); const bundle = ship.createBundle("Research workflow"); await ship.save(); ``` ### Python ``` from treeship_sdk import Treeship ts = Treeship() # Attest 一个操作 result = ts.attest_action( actor="agent://deployer", action="deploy.production", meta={"commit": "abc123", "env": "prod"}, ) # 验证 artifact verified = ts.verify(result.artifact_id) print(f"Outcome: {verified.outcome}, chain: {verified.chain} artifacts") ``` ### CLI（审批门控部署） ``` # Human 创建一个 approval。CLI 会打印一个 approval nonce；捕获它。 approval=$(treeship attest approval \ --approver human://alice \ --description "deploy v2.1" \ --expires 2026-04-30T11:00:00Z \ --format json | jq -r .approval_nonce) # Agent attests deploy 意图，并通过 nonce 绑定 human approval。 treeship attest action \ --actor agent://deployer \ --action deploy.production \ --approval-nonce "$approval" # 验证完整的 chain。验证过程将检查 approval-nonce 绑定。 treeship verify last ``` ## 标准 Treeship 构建在现有标准之上，而不是发明密码学： - **RFC 8785**（JSON 规范化方案）用于确定性签名 - **Ed25519** (RFC 8032) 用于签名 - **DSSE** 用于签名信封（兼容 Sigstore / in-toto） - **SHA-256** 用于内容寻址和 Merkle 树 ## 文档 - 文档站点：**** - 信任模型 + 捕获清单：[`TREESHIP.md`](./TREESHIP.md) - 更新日志：[`CHANGELOG.md`](./CHANGELOG.md) - 插件设计：[`integrations/claude-code-plugin/README.md`](./integrations/claude-code-plugin/README.md) ## 路线图 切合实际，带版本标签（有关每次发布实际包含的内容，请参阅 [`CHANGELOG.md`](./CHANGELOG.md)）。 **已发布 (v0.9.x)** - Rust 核心、CLI、hub 服务器、WASM 验证器、TypeScript / Python SDK - MCP bridge (`@treeship/mcp`) 和 A2A bridge (`@treeship/a2a`) - 带有包含证明和 checkpoint 的 Merkle 树 - DSSE 信封、Ed25519 签名、默认仅哈希 payload - ZK 证明（Circom Groth16，RISC Zero 链证明） - Hub 身份验证（DPoP、设备流），多 hub 支持 - OpenTelemetry 导出（通过 feature flag 控制） - 进程安全的跨进程事件日志（flock + 竞争条件下 fail-open） - **Claude Code 插件** —— SessionStart / PostToolUse / SessionEnd 钩子，技能，Zerker Labs marketplace 安装（v0.9.3+；请参阅 [`CHANGELOG.md`](./CHANGELOG.md)）；Anthropic 自己的插件目录是单独的发布工作 - **Cursor** —— 通过 `treeship add` → `~/.cursor/mcp.json` 实现 MCP，文档和模板位于 [`integrations/cursor/`](./integrations/cursor/) - 位于 的 **通用 SKILL.md**，用于 AI agent 自我新手引导 **v0.10.1（进行中）—— 平台、SDK 和供应链强化** - 静态 `x86_64-unknown-linux-musl` 二进制文件，使得 Debian 12、Ubuntu 22.04、Alpine、RHEL/Rocky 9 和 Amazon Linux 2023 能够顺利安装（当前的 GNU 构建需要 GLIBC 2.39+） - npm postinstall 验证二进制校验和（SHA-256），检测到篡改时强制关闭 - Python SDK 正确性优化（源自 metadata 的 `__version__`、argv-list 的 `wrap()`、`verify()` returncode 处理、可配置的 `cli_path`/`timeout`） - 针对角色 / artifact / nonce / 审批人字段的 SDK 输入验证（拒绝选项注入模式） - Keystore 权限强化：`init` 以 0700/0600 权限写入，`doctor --fix` 负责修复，签名操作拒绝全局可读的私钥 - `@treeship/mcp` 中的 MCP server（`treeship_session_status`、`treeship_session_event`、`treeship_attest_action`、`treeship_verify`、`treeship_session_report`）—— 可直接在 Claude Code、Codex、Cursor、Cline 中使用 - CLI 正确性修复：`init --force` 不再覆盖全局配置；遵循项目级的 `extends:`；`attest action --format json` 返回结构化的成功/失败结果 **计划中，v0.10.1 之后** - Linux ARM64 (`aarch64`) 二进制文件 - `treeship attach ` —— 用于非 MCP agent 的进程检测 - 选择性披露（可编辑的回执） - Anthropic 插件 marketplace 列表（扩大 Claude Code 插件的影响范围；Zerker marketplace 已可正常工作） - `@treeship/mcp` 中的透明 MCP 转发器模式（目前该 bridge 提供服务器模式 + 库模式） **不在路线图中** - 原生 二进制文件。请使用 WSL。如果你有强烈的用例，请在 提交 issue。 **研究中，暂无承诺** - ZK TLS (TLSNotary) —— 等待 TLSNotary alpha 版本稳定 - Hub Merkle Rekor 锚定 - OTS / Bitcoin / Solana 的锚定适配器 ## 贡献 请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。欢迎所有贡献——代码、文档、bug 报告、功能请求、安全审查。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。 版权所有 2025–2026 Zerker Labs, Inc.

标签：AI Agent, 可验证凭证, 命令行工具, 审计日志, 密码学签名, 通知系统