Shree-git/claw-vcs

# Claw VCS [](https://github.com/Shree-git/claw-vcs/actions/workflows/ci.yml) [](LICENSE) [](SECURITY.md) **意图原生、代理原生的版本控制。** Claw VCS 是一个为 AI 代理与人类协同编写代码的时代而构建的版本控制系统。它不仅追踪*发生了什么*变更，更追踪*为什么*发生变更，并存储关于谁完成了工作以及他们运行了哪些检查的签名声明。 ``` claw init claw intent create --title "Add dark mode" --goal "Support light/dark theme toggling" claw change create --intent # ... 编写代码 ... claw snapshot --change -m "Initial dark mode implementation" claw ship --intent --revision-ref heads/main --evidence test=pass --evidence lint=pass ``` ## 为什么开发 Claw VCS Git 在人类编写的源码历史记录方面依然表现出色。Claw VCS 探索了一种互补的模型，用于代理编写的代码，其中意图、证据和策略都是一流的仓库对象。 AI 代理正在编写大量的代码。在这个新世界中，Git 的模型存在一些不可忽视的缺陷： **Git 不存储结构化的检查证据。** Alice 在她的提交信息中说“我运行了测试”。Git 记录了这条信息，而不是关于命令、运行器、修订版本和结果的经过签名的、可查询的声明。CI 在外部运行，其结果通常存在于 GitHub Actions 中，而不是在仓库里。 **Git 无法区分人类 Alice 和机器人 Alice。** 如果 AI 代理以 alice@example.com 的身份进行提交，Git 是无法分辨的。目前没有结构化的方式可以说明“这是由 Claude 3.5 Sonnet 编写的，使用了工具链 X，在环境 Y 中运行。” Git 的作者字段只是一个自由格式的字符串。 **Git 记录“为什么”的方式是自由格式的字符串。** 如果不使用 `grep` 搜索提交信息，就没有办法查询“显示与暗黑模式功能相关的所有变更”。意图与实现之间的联系是非正式的。 **Git 的策略是外部的。** 分支保护、必需的代码审查、必需的 CI 检查——这些都存在于 GitHub/GitLab 的设置中，而不是在仓库中。复刻（Fork）该仓库后，这些规则就不复存在了。 Claw 通过一流的基元（primitives）解决了上述每一个问题。 ## 核心概念 ### Intent（意图） → Change（变更） → Revision（修订） Git 追踪*发生了什么变更*。Claw 追踪*为什么变更*。 ``` Intent ("add dark mode") ← the goal, with constraints and acceptance tests └── Change ← an implementation attempt └── Revision ← a snapshot of code (like a commit) ``` Intent 是仓库中的版本化对象——而不是 Jira 中的外部 Issue。它们拥有结构化的字段：`goal`（目标）、`constraints`（约束）、`acceptance_tests`（验收测试）、`status`（状态）。Change 通过 ID 链接到 Intent。你可以通过编程方式询问：“哪些修订处理了意图 X，它们是否全部通过了验收测试？” ### Capsule（胶囊）：签名的代理来源声明 当代理进行更改时，它会生成一个 **Capsule**，这是一个包含以下内容的签名信封： ``` Capsule { revision_id: clw_..., public_fields: { agent_id: "claude-3.5-sonnet", agent_version: "20240620", toolchain_digest: "sha256:a1b2c3...", env_fingerprint: "linux-x86_64-rust-1.79", evidence: [ { name: "test", status: "pass", duration_ms: 4200 }, { name: "lint", status: "pass", duration_ms: 800 }, { name: "security-scan", status: "pass", duration_ms: 1500 }, ] }, signatures: [{ signer_id: "agent-key-01", signature: }], encrypted_private: , } ``` 证据（测试结果、代码规范检查结果、安全扫描结果）以签名的 Capsule 形式存储在仓库中。Claw 可以验证签名的 Capsule 是否声明了针对特定修订版、由特定密钥生成的特定证据。该证据是否可信取决于密钥管理、运行器完整性和策略配置。 ### 作为版本化对象的策略（Policies） ``` Policy { required_checks: ["test", "lint", "security-scan"], sensitive_paths: ["secrets/", "admin/"], quarantine_lane: true, min_trust_score: "0.8", visibility: Public, } ``` 策略存储在仓库中并随其一起传输。集成操作可以被设限：“此修订版的 Capsule 必须包含所有必需检查均已通过的证据。” 复刻（Fork）仓库时，这些策略会一并带过来。 当前的执行亮点： - `required_reviewers` 与经过验证的 Capsule 签名者身份（代理 ID 或密钥 ID）进行匹配。 - 触及 `sensitive_paths` 时，要求对 Capsule 的私有字段进行加密。 - 当触及敏感路径时，`quarantine_lane` 会阻止自动化集成。 - `min_trust_score` 支持 `0.0-1.0` 或百分比格式（例如 `0.85`、`85%`），并根据 Capsule 证据的通过率进行评估。 ## 架构 Claw 使用 Rust 编写，并被组织为一个由专注于特定功能的 crate 组成的工作空间： ``` crates/ ├── claw-core Core types and COF codec (package `claw-vcs-core`) ├── claw-store Object store, refs, HEAD, reflog (package `claw-vcs-store`) ├── claw-patch Codec-based diff/apply/merge engine (package `claw-vcs-patch`) ├── claw-merge Three-way merge with conflicts (package `claw-vcs-merge`) ├── claw-crypto Signing, verification, capsules (package `claw-vcs-crypto`) ├── claw-policy Policy and visibility checks (package `claw-vcs-policy`) ├── claw-sync gRPC sync with daemon fetch filters (package `claw-vcs-sync`) ├── claw-git Git import/export (package `claw-vcs-git`) └── claw The `claw-vcs` Cargo package, publishing the `claw` binary proto/ Protocol Buffer definitions for all gRPC services ``` ### 对象模型 Claw 拥有 12 种一流的对象类型，每种都有唯一的类型标签： | 类型 | 标签 | 用途 | |------|-----|---------| | **Blob** | `0x01` | 带有可选媒体类型的文件内容 | | **Tree** | `0x02` | 目录结构（名称、模式、每个条目的对象 ID） | | **Patch** | `0x03` | 两种状态之间特定于编解码器的差异操作 | | **Revision** | `0x04` | 历史记录中的一个点（父级、补丁、作者、时间戳） | | **Snapshot** | `0x05` | 完整工作树的原子的捕获 | | **Intent** | `0x06` | 带有约束和验收测试的目标 | | **Change** | `0x07` | 链接到意图的实现尝试 | | **Conflict** | `0x08` | 合并冲突状态（基础/左侧/右侧） | | **Capsule** | `0x09` | 带有证据的签名代理来源信封 | | **Policy** | `0x0A` | 版本化的执行规则 | | **Workstream** | `0x0B` | 相关变更的有序堆栈 | | **RefLog** | `0x0C` | 仅追加的引用变更历史 | 每个对象都使用 Protocol Buffers 进行序列化，并封装在 **COF**（Claw 对象格式）中： ``` ┌──────────┬─────────┬──────────┬───────┬─────────────┬──────────────────────┬─────────┬────────┐ │ Magic │ Version │ TypeTag │ Flags │ Compression │ Uncompressed Length │ Payload │ CRC32 │ │ "CLW1" │ 0x01 │ u8 │ u8 │ None | Zstd │ uvarint │ ... │ 4B LE │ └──────────┴─────────┴──────────┴───────┴─────────────┴──────────────────────┴─────────┴────────┘ ``` 对象使用带有域分隔的 **BLAKE3**（`"claw\0" || type_tag || version || payload`）进行内容寻址，因此具有相同内容的不同对象类型永远不会发生冲突。ID 显示为 `clw_` + 小写 Base32（例如，`clw_ab3fg7kl...`）。 ### 感知编解码器的修补（Codec-aware patching） 补丁系统是可插拔的。每个编解码器实现五个操作： ``` trait Codec { fn diff(&self, old: &[u8], new: &[u8]) -> Vec; fn apply(&self, base: &[u8], ops: &[PatchOp]) -> Vec; fn invert(&self, ops: &[PatchOp]) -> Vec; fn commute(&self, left: &[PatchOp], right: &[PatchOp]) -> (Vec, Vec); fn merge3(&self, base: &[u8], left: &[u8], right: &[u8]) -> Vec; } ``` 内置编解码器： | 编解码器 | ID | 文件类型 | 策略 | |-------|----|------------|----------| | **Text/Line** | `text/line` | `.txt`, `.md`, `.rs`, `.py`, ... | 基于行的差异（类似于 `diff`） | | **JSON/Tree** | `json/tree` | `.json` | 结构化树差异（基于键，而非行） | | **Binary** | `binary` | 所有其他文件 | 全 Blob 替换 | `commute` 操作支持 Darcs 风格的补丁重新排序——如果两个补丁触及文件中互不相关的部分，则它们可以按任何顺序应用而不会发生冲突。 该架构支持为 YAML、TOML、SQL 迁移、Protobuf 架构添加编解码器——任何结构化理解胜过逐行差异比较的场景。 ### 同步协议 Claw 使用 **基于 HTTP/2 流的 gRPC** 进行网络操作，并为计划中的托管远程仓库提供了一个可选的 HTTP 传输适配器： ``` service SyncService { rpc Hello(HelloRequest) returns (HelloResponse); rpc AdvertiseRefs(AdvertiseRefsRequest) returns (AdvertiseRefsResponse); rpc FetchObjects(FetchObjectsRequest) returns (stream ObjectChunk); rpc PushObjects(stream ObjectChunk) returns (PushObjectsResponse); rpc UpdateRefs(UpdateRefsRequest) returns (UpdateRefsResponse); } ``` 在守护进程协议层，`FetchObjects` 接受用于选择性获取对象的过滤器： - **Intent ID** — 仅获取与特定目标相关的工作 - **路径前缀** — 仅获取 `src/frontend/` - **时间范围** — 仅获取近期的工作 - **编解码器类型** — 仅获取 JSON 文件 - **Capsule 可见性** — 遵循公开/私有/加密元数据要求的策略模式 - **字节预算 / 深度限制** — 资源受限的获取 当前 CLI 的限制：`claw sync clone` 仍然执行完整克隆，并且没有暴露这些过滤器。 ### 守护进程 `claw daemon`（或 `claw serve`）运行一个长期存在的 gRPC 服务器，公开了用于 intent、change、capsule、workstream、event 和 sync 的服务。代理以编程方式连接——创建 intent、提交 change、实时流式传输 event。Git 没有等效的功能。 对于生产环境配置文件的运行，非本地守护进程绑定默认需要身份验证和 TLS。守护进程身份验证可以使用 `--auth-token`（显式 Bearer Token）或 `--auth-profile`（复用 `claw auth` 配置文件中的 Token）进行配置。 ### 密码学 | 原语 | 算法 | 用途 | |-----------|-----------|---------| | 哈希 | BLAKE3 | 内容寻址（比 SHA-1 更快、更安全） | | 签名 | Ed25519 | Capsule 签名，代理身份 | | 加密 | XChaCha20-Poly1305 | 可选的 Capsule 私有数据 | | 完整性 | CRC32 | COF 格式损坏检测（独立于哈希） | | 压缩 | Zstd | 对象存储和传输（比 zlib 速度更快、压缩比更好） | ## CLI 参考 ``` claw init Initialize a new repository claw intent Create and manage intents claw change Create and manage changes claw policy Create and manage integration policies claw snapshot -m "msg" Record the working tree atomically claw ship --intent Finalize a revision and produce a capsule (use --revision-ref for branches) claw integrate --right Merge changes (three-way, codec-aware) claw branch List, create, or delete branches claw checkout Switch branches or restore working tree claw log Show revision history claw diff Show changes between trees claw status Show working tree status claw show Inspect any object claw resolve Manage merge conflicts claw agent Register and manage agent identities claw remote Manage remote repositories claw auth Manage auth profiles and tokens for explicit remote URLs; hosted remotes are planned claw sync Pull from a remote (shorthand) claw sync Push, pull, or clone claw daemon Run the gRPC sync server claw patch Create and apply patches directly claw git-export Export to Git format (supports --all-heads, --git-notes) claw git-import Import from Git format (supports --all-branches, --read-notes) claw git-roundtrip Verify claw -> git -> claw integrity for a ref ``` **没有暂存区** —— 这是刻意为之的。`claw snapshot` 以原子方式捕获所有内容。对于代理工作流来说，这是一个深思熟虑的简化，因为部分暂存只会增加复杂性而没有价值。 ## Claw VCS 在 Git 之外增加了什么 | 能力 | Git | Claw | |---|---|---| | 追踪变更的*原因*（结构化） | 自由格式的提交信息 | 带有目标、约束和验收测试的 Intent 对象 | | 记录签名的检查声明 | 外部 CI；不在仓库中 | Capsule 中的证据，经过签名并存储在仓库内 | | 区分人类与 AI 代理 | 自由格式的作者字符串 | 使用 Ed25519 密钥的注册代理身份 | | 在仓库内执行策略 | GitHub/GitLab 设置（外部） | 与代码一起版本化的 Policy 对象 | | 感知编解码器的合并 | 仅支持基于行的差异 | 可插拔的编解码器（如 JSON 树差异等） | | 守护进程按意图/时间/编解码器过滤获取内容 | 仅限无树/无 Blob | 守护进程对象获取可以按意图、路径、时间、编解码器、可见性和字节预算进行过滤；CLI clone 目前获取所有 refs/objects | | 代理原生的守护进程 | 无 | 用于编程式代理访问的 gRPC 服务器 | | 补丁交换律 | 不适用 | Darcs 风格的独立补丁重新排序 | | Capsule 加密 | 不适用 | XChaCha20-Poly1305 加密的私有元数据 | ### 老实说，Git 在以下方面依然够用 - **人类创作** —— Git 的 author/committer 模型对人类开发者非常适用。 - **提交信息作为“原因”** —— 对于大多数仅由人类参与的项目来说已经完全足够。 - **GPG/SSH 签名** —— 证明已配置的密钥签署了提交。Claw 的 Capsule 签名将相同的理念扩展到了代理密钥和证据声明。 **核心论点：** 如果你的项目 100% 是人类编写的，那么 Git 的来源模型可能就足够了。如果代理正在自主提交更改，那么 Git 没有内置的仓库对象来强制执行“只有在可信密钥签署了该确切修订版的可接受测试证据时才进行集成”。Claw 将这些证据和策略变成了仓库的一部分。 ## Claw VCS 不是什么 - 不是适用于所有项目的 Git 替代品。 - 不是 CI 系统。 - 不是代码审查平台。 - 不能证明代码是正确的。 - 不能证明测试是充分的。 - 不能证明 AI 代理的行为是安全的。 - 本身不能提供完整的供应链安全。 ## 安装 带有标签的版本发布会在 GitHub Releases 中为 macOS、Linux 和 Windows 发布预构建的二进制文件。下面的验证步骤需要使用基于此加固树构建的发布版本；现有的发布于 2026-05-01 的 `v0.1.0` 版本早于 `claw doctor`，在进行启动验证时应被视为历史版本。 对于当前的工作树，源码安装路径已通过 `cargo install --path crates/claw --locked` 进行了冒烟测试。关于发布渠道，请查看[安装验证](docs/operations/install-verification-log.md)，并且只有在其当前的公共构件通过了匹配的纯净环境冒烟测试后，才能将某个发布渠道标记为已准备好启动。 ### 当前的源码安装 在发布并验证了启动加固版本之前，请使用此路径： ``` git clone https://github.com/shree-git/claw-vcs.git cd claw-vcs cargo install --path crates/claw --locked claw --version claw doctor ``` ### 发布渠道 以下针对发布渠道的命令适用于下一个经过验证的启动加固版本。在将该标签记录到安装验证日志中之前，请使用上面的当前源码安装方法。在发布说明和[安装验证日志](docs/operations/install-verification-log.md)记录了当前标签的验证通过之前，不要将 `/latest`、Homebrew、MSI 或安装程序输出视为已准备好启动。在下面的示例中，请将 `` 替换为该已验证的标签。 ### macOS **Homebrew** ``` brew install shree-git/tap/claw ``` 或者，如果你愿意： _BLOCK_11/> 验证： ``` claw --version claw doctor mkdir -p /tmp/claw-demo && cd /tmp/claw-demo claw init claw status ``` **手动下载** 从 [GitHub Releases](https://github.com/shree-git/claw-vcs/releases) 获取针对 `` 且已验证的 macOS 归档文件，使用[发布验证](docs/security/verifying-releases.md)进行验证，解压缩后，将 `claw` 放置在你的 `PATH` 路径中（例如 `~/.local/bin`）。 **安装脚本** 建议在运行安装程序之前先下载并检查它： ``` curl --proto '=https' --tlsv1.2 -LsSfO https://github.com/shree-git/claw-vcs/releases/download//claw-installer.sh sh ./claw-installer.sh ``` 当你验证了该发布版本后，可使用通过管道传递至 shell 的便捷形式： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shree-git/claw-vcs/releases/download//claw-installer.sh | sh ``` 安装到自定义位置： ``` CLAW_HOME="$HOME/.claw" sh ./claw-installer.sh ``` 验证： ``` claw --version claw doctor mkdir -p /tmp/claw-demo && cd /tmp/claw-demo claw init claw status ``` ### Linux **手动下载** 从 [GitHub Releases](https://github.com/shree-git/claw-vcs/releases) 获取针对 `` 且已验证的 Linux 归档文件，使用[发布验证](docs/security/verifying-releases.md)进行验证，解压缩后，将 `claw` 放置在你的 `PATH` 路径中（例如 `~/.local/bin`）。 **安装脚本** 建议在运行安装程序之前先下载并检查它： ``` curl --proto '=https' --tlsv1.2 -LsSfO https://github.com/shree-git/claw-vcs/releases/download//claw-installer.sh sh ./claw-installer.sh ``` 当你验证了该发布版本后，可使用通过管道传递至 shell 的便捷形式： ``` curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shree-git/claw-vcs/releases/download//claw-installer.sh | sh ``` 安装到自定义位置： ``` CLAW_HOME="$HOME/.claw" sh ./claw-installer.sh ``` 验证： ``` claw --version claw doctor mkdir -p /tmp/claw-demo && cd /tmp/claw-demo claw init claw status ``` 注意： - 在 NixOS（或其他不寻常的环境）上，建议使用手动安装（下载发布归档文件并将 `claw` 放在你的 `PATH` 路径中）或从源代码构建。 ### Windows **WinGet（计划中）** WinGet 支持已在计划中，但在上游 Microsoft 仓库接受清单之前，没有 WinGet 安装命令是准备好启动的。在发布说明和安装验证日志将 Windows 渠道标记为当前标签已验证之前，请使用当前的源码安装或手动验证的 GitHub 发布构件。 **MSI** 从 GitHub Releases 下载针对 `` 且已验证的 `.msi` 文件并运行它。安装程序会将 `claw` 添加到 `PATH`。 **PowerShell 安装程序（无 MSI）** 建议在运行安装程序之前先下载并检查它： ``` iwr -useb https://github.com/shree-git/claw-vcs/releases/download//claw-installer.ps1 -OutFile claw-installer.ps1 powershell -ExecutionPolicy Bypass -File .\claw-installer.ps1 ``` 当你验证了该发布版本后，可使用管道传递至 `iex` 的便捷形式： ``` iwr -useb https://github.com/shree-git/claw-vcs/releases/download//claw-installer.ps1 | iex ``` 验证： ``` claw --version claw doctor mkdir $env:TEMP\claw-demo -Force cd $env:TEMP\claw-demo claw init claw status ``` ### 从源代码构建（任何操作系统） 需要 [Rust](https://rustup.rs/)（稳定版）。Claw 默认使用内置的 `protoc`，因此通常你**不需要**安装 Protocol Buffers 工具。如果你想强制使用特定的 `protoc`，请在构建前设置 `PROTOC=/path/to/protoc`。 ``` git clone https://github.com/shree-git/claw-vcs.git cd claw-vcs cargo build --release -p claw-vcs CLAW_BIN="$(pwd)/target/release/claw" "$CLAW_BIN" --version "$CLAW_BIN" doctor mkdir /tmp/claw-demo cd /tmp/claw-demo "$CLAW_BIN" init "$CLAW_BIN" status ``` 运行测试： ``` cargo test --workspace ``` ### Rust 用户 如果你已经安装了 Rust，可以直接使用 cargo 进行安装： ``` cargo install --git https://github.com/shree-git/claw-vcs.git --package claw-vcs --locked claw --version claw doctor mkdir /tmp/claw-demo cd /tmp/claw-demo claw init claw status ``` 若要进行特定发布版本的源码安装，请添加标签： ``` cargo install --git https://github.com/shree-git/claw-vcs.git --tag vX.Y.Z --package claw-vcs --locked ``` ## 验证发布版本 在信任下载的构件之前，当发布资产提供校验和、签名和证明时，请对其进行验证。请参阅[发布验证](docs/security/verifying-releases.md)。 ## 卸载 有关 Homebrew、MSI、手动安装、配置、身份验证配置文件和本地仓库状态的卸载说明，请参阅[卸载说明](docs/operations/uninstall.md)。 ## 文档 - 完整操作文档：[docs/README.md](docs/README.md) - 快速入门：[docs/getting-started/quickstart.md](docs/getting-started/quickstart.md) - 概念：[docs/concepts/index.md](docs/concepts/index.md) - 工作流：[docs/workflows/index.md](docs/workflows/index.md) - 代理集成：[docs/agents/index.md](docs/agents/index.md) - 从 Git 迁移：[docs/migration/index.md](docs/migration/index.md) - 角色指南：[docs/persona/index.md](docs/persona/index.md) - CLI 参考：[docs/cli/README.md](docs/cli/README.md) - 支持：[SUPPORT.md](SUPPORT.md) - 路线图：[ROADMAP.md](ROADMAP.md) - 贡献：[CONTRIBUTING.md](CONTRIBUTING.md) - 生产就绪清单：[docs/reference/production-readiness-checklist.md](docs/reference/production-readiness-checklist.md) - 基础演示：[scripts/demo.sh](scripts/demo.sh) 和 [examples/basic-demo/README.md](examples/basic-demo/README.md) - 备份与恢复演示：[examples/backup-restore/README.md](examples/backup-restore/README.md) - 演示媒体：[examples/demo-media/README.md](examples/demo-media/README.md) - 生产环境安装：[docs/operations/production-install.md](docs/operations/production-install.md) - 升级与回滚：[docs/operations/upgrade-and-rollback.md](docs/operations/upgrade-and-rollback.md) - 灾难恢复：[docs/operations/disaster-recovery.md](docs/operations/disaster-recovery.md) - 故障排除：[docs/operations/troubleshooting.md](docs/operations/troubleshooting.md) - 运行手册索引：[docs/runbooks/README.md](docs/runbooks/README.md) ## 项目状态 Claw VCS 目前处于 **v0.1.1 实验阶段**。该仓库包含了发布、操作、回滚和生产预检工具，但在被视为正式上线之前，公共发布渠道必须在每次发布时进行验证。在评估 Claw VCS 时，请将 Git 或其他成熟的系统保留作为事实来源。 ## 许可证 MIT

标签：AI编程, CI/CD证据, Git替代, MIT许可, Python工具, SOC Prime, VCS, Zenmap, 人机协作, 代码变更追踪, 代码审查, 代码溯源, 代码管理, 可视化界面, 大模型代码, 开发工具, 意图驱动, 数据完整性, 数据管道, 源代码管理, 版本控制系统, 签名验证, 软件工程, 通知系统