radotsvetkov/soma

# soma：具备可验证、防篡改审计追踪的本地优先 AI agent 治理工具 soma 是一个小巧、零依赖的 runtime，负责治理 AI agent 并证明它们的所作所为。它在强制的 policy 下封装任何 agent 命令行，将每一个操作记录在哈希链式审计日志中，并导出任何人都可以验证的便携证据，无需信任你、你的供应商或你的云服务商。 如果你在工作中运行 AI agent，并且需要有人对其进行签字确认（安全团队、合规部门、客户、审计员或 EU AI Act），soma 能为你提供确凿的凭证。  ``` binary 883 KB (release build, stripped) dependencies 0 (Rust std only, the whole supply chain is src/) tests 219 (cargo test) memory ~2 MB peak RSS on a typical run ``` 许可证：Apache-2.0。状态：v0.2.0。平台：macOS 和 Linux。 ## soma 解决的问题 AI agent 正在成为企业内部的黑盒。它们会选择工具、调用 API、编辑文件并运行命令，但大多数时候，你随后无法展示 agent 实际上做了什么或为什么这么做。一旦 agent 接触到任何重要事务，这就成了一个问题。 大型供应商在 2025 年和 2026 年推出的 agent 控制平面部分解决了这个问题。它们提供了身份验证、注册中心和审计日志。但是，这些审计日志全都存在于各自供应商的云和信任边界内。你无法向监管机构或客户提供一份他们能在自己机器上验证的记录，你无法在离线状态下运行治理层，而且信任根始终是那家供应商。 soma 采取了截然相反的立场： 1. 治理和证据是本地优先的。一个全新的项目网络出口流量为零。 2. 证据是便携的。只需一个 SHA-256 工具和一个 JSON 阅读器即可验证审计追踪。 3. 信任根是数学，而不是供应商。你自己重新计算哈希链，并且你可以将其锚定到独立的 timestamp 权威机构，这样即使是操作员也无法重写历史记录。 ## 十分钟内你能做什么 ``` # 先安装 soma（见下文的 Install）。然后整个循环就是这些命令。 # 创建一个仅限本地的项目（在您选择加入之前没有外部网络）。 soma init --name myproject # 管控任何 AI agent CLI。启动时会进行 policy 检查并完整记录 journaled。 soma wrap --label fix-tests -- claude -p "fix the failing tests" # 证明没有任何人编辑过 history。 soma log verify # 导出任何人都可以检查的 evidence，无需 soma。 soma export # 在独立的权威机构为 journal 的头部加盖 Timestamp。 soma anchor now ``` 这就是整个闭环：治理 agent、记录其行为、锚定证明、导出可供陌生人验证的证据。无需账号，无需租户，无需按席位授权。 ## 使用 `soma wrap` 治理任何 AI agent CLI `soma wrap` 将 soma 转变为一个治理层，适用于你已经在运行的 agent，包括 Claude Code、GitHub Copilot CLI 以及任何其他带有命令行的工具。你不需要集成 SDK，也不需要更改 agent。 ``` soma wrap --label nightly-refactor -- claude -p "refactor the storage layer" ``` 该命令执行前后会发生以下操作： - 在进程启动之前，会根据你的 policy 检查启动行为。如果 autonomy 级别为 `observe`，或者命令匹配到拒绝规则，soma 会拒绝执行并记录该决定。什么都不会运行。 - stdout 和 stderr 会实时流式传输，因此 agent 保持交互状态，同时 soma 使用 SHA-256 对两个流进行哈希处理，并保留经过脱敏处理的摘录。 - soma 会向日志中写入 `wrap.start` 和 `wrap.end` 凭证：标签、命令、exit code、持续时间、输出哈希值和大小，以及是否超时。 - agent 的 exit code 会被保留，因此这可以直接嵌入到脚本或 CI job 中。 客观说明其局限性。`soma wrap` 会对启动行为进行 policy 检查并记录到日志中。它不是围绕子进程的 syscall 或网络沙箱，并且它的命令网关是一个已知不良命令格式的拒绝列表，而不是语义层面的防护。如果需要硬隔离，请在 container 或受限用户下运行 soma。管道也会扁平化全屏终端 UI，因此请针对无头和打印模式（例如 `claude -p`）使用。 ## 在 cockpit 中查看每一个操作 我们提供了一个配套的桌面应用程序 [soma cockpit](https://github.com/radotsvetkov/cockpit)，它会读取磁盘上的 soma 项目并将日志渲染为可读的时间线。它在本地运行，不进行任何网络调用，并通过 shell 调用同一个二进制文件，因此绿色的“chain verified”徽章就是 `soma log verify` 的字面输出结果。  这是一次真实的运行记录。你可以阅读封装的 agent 会话、锚定在 freetsa.org 的链头、导出的证据包，以及在被孵化出来之前就被 policy 拒绝的 `sudo` 命令（以红色标记）。 ## 你可以验证的防篡改审计日志 soma 采取的每一个操作都会成为只追加的 JSONL 日志中的一个事件。每个事件都带有前一个事件的 SHA-256 值以及自身的哈希值，因此该文件形成了一个哈希链。 ``` soma log verify # recompute the whole chain and point at the first edited line ``` 编辑或删除单行内容，`soma log verify` 就会准确地告诉你问题出在哪里。在任何事件写入磁盘之前，都会根据 key 模式执行脱敏操作，因此环境变量中的机密信息永远不会落入日志中。 ## 任何人都可以检查的便携证据 ``` soma export # writes a bundle plus a .tar.gz soma export verify # recompute every file hash and the full chain ``` 证据包包含日志、状态快照、带有每个文件 SHA-256 值的 manifest，以及一个 `VERIFY.md` 文件，该文件说明了如何使用标准工具检查所有内容。从未听说过 soma 的审查人员也能手动确认该证据包。如果链条未通过验证，导出操作将拒绝运行，因此绝不会存在表面上看起来正常、实则链条已损坏的虚假证据。 ## 锚定日志，这样连你自己也无法篡改时间 哈希链证明了没有人篡改过过去的记录。但它本身并不能阻止操作员删除日志并重新生成一份新的。`soma anchor` 通过在独立的 RFC 3161 权威机构对日志链头进行 timestamp 操作，从而弥补了这一漏洞。 ``` soma anchor now # POST the head hash to a public timestamp authority soma anchor verify # recompute the chain and check the timestamp ``` soma 手动构建 RFC 3161 请求（没有加密依赖，请求编码器只有几十行代码），并使用系统自带的 `curl` 发送该请求。第三方一旦获取了权威机构的根证书，就可以使用标准的 `openssl ts -verify` 来验证保存的响应。这证明了日志链头在某个你无法控制的时间点就已经存在，这意味着你无法对每个锚定点之前的历史记录进行倒填时间戳。 准确说明这能证明什么和不能证明什么：锚定证明了直到每个锚定点之前的时间是不可倒填的，但不能证明完整性。在最后一个锚定点之后追加的事件，以及 soma 自身写入的日志，都不在此保证范围内，直到生成下一个锚定点。 ## 基于日志生成的 EU AI Act 第 12 条记录 如果你在欧盟境内运营或向欧盟提供 AI 系统，EU AI Act 第 12 条是对高风险系统的记录保存要求。soma 可以直接从日志中生成可供审计员使用的第 12 条记录附件。 ``` soma export eu-ai-act # writes a Markdown annex plus a machine-readable .json ``` 该附件记录了日志记录能力、映射到第 12 条的事件分类、使用周期记录、完整性和防篡改说明、符合第 19 条和第 26 条六个月最低期限的留存策略，以及可重现的验证说明。如果链条损坏，它将拒绝运行。 它对自身的适用范围非常客观。它记录了日志记录能力和相关记录。它不是符合性评估，不是法律建议，也不执行第 6 条的分类操作。大多数开发和编程 agent 根本不属于附录 III 中的高风险类别，文档中也对此进行了说明。它还同时打印了当前生效的适用日期和根据暂定协议的 Digital Omnibus 确定的较晚日期，从而使法律快照更加清晰。 ## in-toto 证明以及用于 CI 的 GitHub Action ``` soma export attestation # in-toto Statement v1 over the journal head ``` 该证明的 subject digest 是日志链头的哈希值，因此它绑定的是确切的证据链，而不是某个文件的校验和。soma 在设计上不对其进行签名，从而保持了 runtime 的零依赖性。你可以在 CI 中使用 cosign 或 `gh attestation` 对其进行签名。包含的 GitHub 复合操作会在 soma policy 下运行 agent，然后将证据包和证明作为构建产物导出，供审查人员验证。参见 [docs/CI.md](docs/CI.md)。 ## 符合 Agent Control Specification soma 将其 policy 网关映射到微软的 Agent Control Specification (ACS)，这是 2026 年发布的开放 runtime 治理规范。该映射涵盖了 soma 实现的干预点，并客观说明了存在的差距。soma 的 autonomy 级别与 ACS 语义高度契合：`observe` 表现为仅评估模式，`assist` 转为由人工审批，而 `auto` 则强制执行。参见 [docs/CONFORMANCE.md](docs/CONFORMANCE.md)。 ## 为什么要做到零依赖 soma 特意使用大约 1,400 行 Rust 代码手动实现了 JSON、SHA-256、HTTP、RFC 3161 编码和 cron 解析： 1. 供应链就是 `src/`。审计一个与安全相关的 agent runtime，不应该还需要审计数百个传递依赖包。 2. 它可以在模型刚好能装下的地方运行。没有异步 runtime，也没有 TLS 堆栈，这意味着内存占用小且可预测，从而将 RAM 留给了你的本地模型。 3. 构建快速且稳定。冷构建只需要几秒钟，没有 lockfile 漂移，构建时也不需要网络。 ## Autonomy 是一种 policy，而不是随性而为 ``` observe plan and explain only, execution is refused and recorded assist execute, but a human applies any self-improvement proposals (default) auto execute and apply mechanical proposals automatically ``` 除了 autonomy 级别之外，你还享有命令允许和拒绝模式、网络主机允许列表（默认仅限 localhost）、可写路径边界以及机密信息脱敏。每一个命令、执行、网络调用和路径决策都会连同触发的确切规则一起被记录在案。soma 采取失败即关闭策略：格式错误的 policy 文件会被拒绝，而不是在不知不觉中被放宽限制。 ## 安装 soma 是一个独立的单一二进制文件。请选择你最信任的安装方式。 ### 验证并运行预构建的二进制文件（推荐） 每次发布版本都会在 SHA-256 校验和旁边附上适用于 macOS 和 Linux 的压缩归档文件，以便你在运行它之前准确确认下载的内容。对于一个以提供可验证证据为全部使命的工具来说，检查二进制文件本身就是核心目的，而不是事后补救。 ``` base=https://github.com/radotsvetkov/soma/releases/latest/download # 选择适用于您平台的 archive： # soma-aarch64-apple-darwin.tar.xz Apple Silicon macOS # soma-x86_64-apple-darwin.tar.xz Intel macOS # soma-aarch64-unknown-linux-gnu.tar.xz ARM64 Linux # soma-x86_64-unknown-linux-gnu.tar.xz x86_64 Linux file=soma-aarch64-apple-darwin.tar.xz curl -LO $base/$file curl -LO $base/$file.sha256 # 在信任它之前，请根据已发布的 checksum 验证下载。 # （macOS 使用 shasum；在 Linux 上替换为 sha256sum。） grep . $file.sha256 | shasum -a 256 -c - # Linux: grep . $file.sha256 | sha256sum -c - # 解压（archive 包含 soma、LICENSE 和 README，位于同一个文件夹下）并 # 将 soma 放入您的 PATH 中。 tar -xf $file sudo install -m 0755 ${file%.tar.xz}/soma /usr/local/bin/soma soma --version ``` ### Homebrew ``` brew install radotsvetkov/soma/soma ``` ### 一行命令安装程序 每次发布版本都会提供一个安装脚本，用于下载正确的归档文件、检查其哈希值，并将 `soma` 添加到你的 PATH 中。 ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/radotsvetkov/soma/releases/latest/download/soma-installer.sh | sh ``` ### 使用 cargo ``` cargo install --git https://github.com/radotsvetkov/soma ``` ### 从源码构建 ``` git clone https://github.com/radotsvetkov/soma cd soma cargo build --release ./target/release/soma --help ``` soma 只需要最新的 Rust 工具链，不需要其他任何东西。冷构建只需几秒钟，因为没有需要获取的依赖项。 ## 项目布局 ``` src/ the runtime, hand-rolled and test-vectored json.rs sha256.rs util.rs http.rs foundations events.rs export.rs hash-chained journal and evidence policy.rs project.rs autonomy policy, projects, presets skills.rs neuro.rs knowledge.rs skills, explained selection, lessons models.rs cache.rs providers, routing, response cache goals.rs cron.rs improve.rs workflows, schedules, proposals wrap.rs anchor.rs aiact.rs attest.rs govern agents, anchor, AI Act, attest mcp.rs cli.rs MCP client, command dispatch ci/ a GitHub Action for governed agent runs in CI docs/ the JSON API, the ACS conformance mapping, CI usage SPEC.md the original requirements ``` ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。

标签：AI代理, Homebrew安装, LNA, Rust, 可视化界面, 审计日志, 本地优先, 网络流量审计, 通知系统, 防篡改, 零依赖