AVCS

AVCS — Agentic Version Control System

一款原生面向 AI 的版本控制系统，供人类和 AI Agent 并行协作。

Agent 不应该把上下文耗费在版本控制上。 这就是全部设计目标，而且这个目标不是靠声称，而是靠测量来验证的——以下是 Agent 完成相同工作所需的成本：

Agent 需要付出的成本	git / 完整功能面	AVCS
在他人的 PR 先合并后提交更改（30 KB 模块）	18,922 个 token	279 个 token — 减少 99%
完成恢复所需的往返次数	7	4
工具 schema，每次会话都要付出的成本	≈8.8k 个 token（39 个工具）	≈3.5k 个 token（13 个，--profile core）
同一行发生冲突时交给模型的内容	整个文件，带有冲突标记	一个指明两个竞争操作的对象

git 的恢复成本随文件大小增长——冲突是文件中的字节，因此 Agent 必须读取整个模块并写回整个模块，才能更改一行。AVCS 的恢复成本则随更改大小增长：冲突是一个指明两个竞争操作的对象，因此即使文件变大，成本也保持不变。此外，无需重写分支，也无需强制推送，这就是往返次数不同的原因——而这只是一个周期，每个比你更早合并的 PR 都会重复一次。在测量过的文件大小范围内，节省幅度为 37–99%。

这并不是事后附加的压缩技巧。它源于存储操作图而非快照：无需执行变基，因此也无需重新读取。关于方法、注意事项以及用于得出变基数据的测试工具，请参阅： avcs-demo → Agent 使用 token 的成本。 schema 数据指 MCP 本身公开的功能面——35 KB 的 JSON 对比 14 KB，按通常每个 token ≈4 字节计算。

Git 记录代码何时发生更改。 AVCS 记录代码由谁更改、出于什么意图、依据什么证据，以及通过哪些冲突决策到达当前状态。

AVCS 是一款全新的、刻意与 Git 不兼容的版本控制系统，面向人类和多个 AI Agent 并行编辑同一代码库的世界。它摒弃了提交 / 分支 / 合并 / 冲突标记模型，转而将意图、会话、操作、证据和决策作为一等对象存储。代码树并非事实来源，而是通过确定性地归约操作图计算得出的投影：

state = reduce(base, operationDAG, decisions, policy, materializer)

相同的对象 + 相同的策略 + 相同的物化器，会在任何副本上产生相同的树。合并不是文本选择，而是一种纯粹、确定性的归约。

**状态：**研究原型。实现是真实的，并经过测试覆盖，但每个阶段都只构建到可运行的 MVP 深度（与语言无关的文本三方合并、ed25519 签名）。结构感知合并、语义破坏检测、多签名信任以及强化的分布式同步都已列入路线图。 快速开始：安装 · 前五分钟 · 针对服务开展工作 · 通过 MCP 连接 Agent · Agent 快速入门指南

先看运行效果：izagood/avcs-demo — 一个可运行的演示，展示了此设计要解决的问题：两个 Agent 同时编辑同一个文件时会发生什么？ 运行一次 ./demo.sh，即可看到一个过时头部的落地操作被吸收而非拒绝、一次无需变基的同文件自动合并，以及一次同一行冲突如何变成签名决策，而不是冲突标记。

为什么不在 git 之上构建一层？

每种“AI + git”工具最终都会把 Agent 的上下文存放在历史记录旁边——提交说明尾注、PR 评论、旁路 JSON。AVCS 的存在是因为这些对象必须成为承重结构——由合并机制本身使用——而附加在 git 上无法做到这一点：

• 证据必须作为合并门槛。 git 会欣然合并没有通过测试的行为变更。在 AVCS 中，缩减器会将此类变更评为 L3 — 已阻止，直到可信证据提交为止；操作的作者为自己的操作背书并不算数。
• 决策必须在合并后继续存在。 git merge 通过生成字节来解决冲突；选择及其理由随之消失。AVCS 的 decision 是一个签名对象——以后可以重新调用，且先前的决策会影响未来的自动解析。
• 并发编辑不能退化成冲突标记。 两个 Agent 编辑同一个文件时，会经过确定性的策略缩减（见下方 L0–L4），而不是在树中留下 <<<<<<<，再由人来收拾残局。
• 意图必须随工作一起传递。 尾注只是惰性文本。intent（目标 + 约束 + 允许的范围）才是会话开启所依据的内容、租约和争用检查所限定的范围，也是 avcs.context.build 交给下一个 Agent 的内容。

git 存储快照，并将合并交给文本选择；AVCS 存储操作图，并根据意图、证据和决策进行计算来完成合并。这就是它刻意与 git 不兼容的原因——这些对象是引擎，而非元数据。（仍提供 git 互操作作为桥接：docs/14、docs/20。）

核心原则

#	原则	与 Git 的区别
1	操作构成历史，而非提交	一次提交只是许多操作之上的检查点
2	身份由实体 ID 决定，而非文件路径	重命名 + 编辑可以自动合并
3	合并是确定性的缩减，而非文本选择	没有冲突标记
4	冲突是一级 decision 对象，而非损坏的文件	理由会留在历史记录中
5	AI 输出是附带证据的拟议操作，而非可信代码	没有测试的行为变更无法被 accepted
6	代码绝不默认采用最后写入者胜出	优先级由策略决定

工作原理

每个有意义的事物都是一个内容寻址、仅追加的对象。代码是操作 DAG 上的投影，绝不会以提交的形式存储。

对象	作用
intent	说明进行更改的原因（目标 + 约束 + 允许的范围）
session	Agent／人类围绕某个 intent 开展的一段工作
operation	一个语义更改单元 — 真正的历史记录
evidence	附加到操作上的机器可检查证明（测试／类型检查／lint／扫描）
decision	对冲突或设计选择所作的记录性决断
checkpoint	已验证的（操作 + 策略 + 物化器）状态向量 — 取代提交
view	对操作图的声明式查询 — 取代分支
release	带签名且包含溯源信息的检查点 — 取代标签
policy	reducer 所依据的确定性合并规则

……以及用于多机器和安全阶段的原始内容 blob 和治理对象（lease、membership、protection、promotion、redaction、override、approval、line、integration）。

冲突解决级别

AVCS 对代码绝不会退回到后写入优先。相互竞争的操作会经过分级，并依据记录的理由进行解决：

• L0 / L1 — 涉及不同实体，或同一文件中不相交的行区域 → 自动合并
• L2 — 并发编辑重叠了同一行区域 → 策略自动决策（优先考虑人类意见，并按信任度加权）；自动决策本身会记录在 autoDecisions 中
• L3 — 行为变更缺少可信证据 → 阻止
• L4 — 破坏公共 API → 需要人类决策，并路由给该范围的所有者

证据的信任度至关重要：操作的作者不能为自己的操作背书。证据门控和通过测试加分只会将由非作者且可信的参与者（CI 机器人／人类）生成的证据计入。

当前已实现的功能

reducer 和策略引擎是基础；更高阶段则在此基础上构建分布式协作、安全性和可观测性。

基础功能（第 1–6 阶段）

• 存储核心 — 仅追加、内容寻址的对象存储（.avcs/objects）
• 确定性 reducer + 策略引擎 — 采用上述 L0–L4 冲突分级，并配有优先级阶梯、有限的可靠性调整和可审计的自动决策
• 语言无关的文本合并（第 2 阶段）— 确定性的 N 路、按行进行的 3 路合并（src/merge/merge3.ts），因此无论使用何种语言，同一文件中不相交区域的编辑都能自动合并；重叠编辑则成为由策略解决的冲突区域。核心中不进行语言解析
• 加密信任（第 3 阶段）— 使用 ed25519 对证据／决策签名；伪造的签名无法通过信任门控。提供真正的验证运行器、WorkLease、RepairContext
• 决策记忆（第 4 阶段）— 可供回溯的过往人类决策（recallDecisions），以及影响未来自动解决的提炼版“学习策略”
• 策略深度（第 5 阶段）— 代码所有者路由和有限的可靠性学习
• 发布与溯源（第 6 阶段）— 已验证的检查点 + CycloneDX SBOM + 已签名的制品

协作、规模与安全性（第 7–12 阶段）

• **阶段 7 — 多机协作：**成员身份／角色（签名密钥联邦）、pull（对象 Gossip；两个副本收敛到相同的 treeHash）、保护机制 + finalize CAS（拒绝非快进，因此过时的推送无法覆盖较新的历史）
• **阶段 8 — 血缘：**长期分歧的分支（例如 v1.x ∥ v2.x，路径相同、内容不同、冲突为零）、portOp（回移 = cherry-pick）
• **阶段 9 — 扩展规模：**实体索引、materializeAt（时间回溯）、支持去重的分块大型 blob 存储
• 阶段 10 — 可观测性：blame（谁／为何）、logP、确定性 bisect、diff
• **阶段 11 — 外部贡献：**隔离区层 + promote + 不受信任的 CI 门禁
• 阶段 12 — 安全：redact（通过清除字节来移除泄露的密钥，同时保留 oid）、紧急 override、仅向前回滚
• 本地撤销（文档 23）— avcs undo [--last | <op-oid>…] [--purge] [--no-git]：从视图中移除本地操作；使用 --purge 时，清除这些操作唯一引用的字节。操作一经推送便会拒绝执行，因为这种情况应由管理员授权的 redact 处理。在由 git 桥接的仓库中，--purge 也会清除 git 副本——但只会在能够证明重写安全且仅影响本地时执行（远程上没有相关内容、提交位于顶端、提交中没有其他工作区内容、工作区干净）；其他情况下仍会执行 AVCS 侧的操作，并明确指出遗留内容以及最适用的一条命令，必要时甚至会提示“轮换凭据，它已经发布”
• 工作区确实是派生结果 — checkout 会记录它投影的内容（.avcs/projection.json，路径 → blob oid），并在下次投影时删除目标视图中不再包含的文件。它从未写入的文件——构建输出、忽略的文件、你刚创建的任何内容——都不会受到影响；你后来编辑过的投影文件也会保留，并在通知中列出，而不会被悄悄覆盖。因此，切换视图得到的是该视图，而不是此前投影过的所有视图的并集

分支变为视图，提交变为检查点，标签变为发行版本。Agent 通过一流的 MCP 服务（39 个工具，或使用 --profile core 时的 13 个工具）驱动 AVCS；人类则使用 CLI。从阶段 14 起，服务运行集成队列（avcs submit、POST /integrate）：过时的提交请求绝不会收到“head 已移动——请先 pull”的回复——服务会代替提交者重新归并前沿并集，结果始终是一个判定（advanced | conflict 修复包 | needs_evidence——只需一次验证运行，无需重做 | queued）。从阶段 15 起，副本会实时收敛（GET /events 长轮询、avcs sync --watch、争用提前预警）；阶段 16 则完善了 MCP 接口：avcs.sync.land 可通过一次调用落地工作，avcs.context.build 可组装有界工作上下文并进行确定性截断，可订阅的资源会在 head 移动时通知客户端——详见 文档 17 和 文档 18。这些行为由包含 827 项测试的契约测试套件（test/*.test.ts，全部通过）固定下来，tsc 检查也已通过。

安装

需要 Node ≥ 22.6 — AVCS 通过类型剥离直接运行 TypeScript，因此无需构建，也没有运行时依赖。

AVCS 已发布到 npm，包名为 @izagood/avcs。全局安装即可在 PATH 中使用 avcs 命令：

npm install -g @izagood/avcs

也可以不安装，直接从 registry 运行：

npx @izagood/avcs version

最初的五分钟（无需服务，也无需 git）

AVCS 采用本地优先设计：磁盘上的仓库就是完整的 VCS，包含历史记录、blame、撤销和发行版本——无需服务，也完全无需 git。在现有项目目录中：

avcs init .                        # create the repo (inside a git repo is fine — .avcs is git-ignored)
avcs import . -m "initial import"  # bring the existing tree in as operations

# …edit files as usual, then record the change:
avcs commit -m "add mul()"         # authors operations for your working-tree changes

avcs status                        # operation / conflict summary
avcs log                           # operation history
avcs blame file:src/math.js        # who owns this file and why (entity key = file:<path>)
avcs conflicts                     # decisions a human still owes
avcs decide <conflict-id> --choose <op-oid> --reason "…"   # …and pay one: a signed decision


avcs undo --last                   # take the last operation back out of the view…
avcs checkout                      # …and re-project the working tree from it

请注意两点：commit 不是 git 提交——它创建的是语义操作，这才是真正的历史记录；工作区是一个投影，你需要通过 checkout 重新物化它，而它并非事实来源。avcs help 会列出所有命令。

签名身份

avcs 身份属于你和这台机器，而非某个检出目录——其作用范围与 ~/.ssh 或 ~/.gnupg 相同。只需配置一次，这台机器上的每个仓库都能用它签名：

avcs key provision human:you    # writes ~/.avcs/private/human:you.json (0600, dir 0700)
avcs key ls                     # who this machine can sign as, and which keystore each came from
avcs key import <key-file>      # put an existing identity on a NEW machine

密钥库位于 $AVCS_CONFIG_HOME、$XDG_CONFIG_HOME/avcs，或 ~/.avcs。仓库可以在 <store>/private/ 中保留自己的密钥，以不同身份签名（例如 CI 检出目录、第二个身份）；该覆盖密钥会优先读取。参见 12 — 本地生产。

你的 id 就是你的身份——信任、密钥和治理都以它为准。若要标注作者并提供联系方式，请像使用 git 一样设置显示名称和邮箱；它们会随你编写的每项操作一同传递（因此 blame 和历史记录可以显示你的信息并联系到你），但绝不会成为任何操作的门槛：

avcs config user.name  "Ada Lovelace"
avcs config user.email "[email protected]"
avcs config actor      "human:ada"      # the id commits author as (else your sole key / AVCS_ACTOR)
avcs config                              # show what is set

这些信息保存在 .avcs/config.json 中；AVCS_AUTHOR_NAME / AVCS_AUTHOR_EMAIL / AVCS_ACTOR 可按次调用覆盖。

使用服务器

即使完全没有服务器，仓库依然可用。有了服务器之后——无论是 avcs serve、avcs-server，还是任何符合规范的实现——整个交互只需几条命令：

avcs clone https://your.server/acme/web .      # fetch the graph AND project a working tree
avcs clone https://your.server/acme/web . --at <checkpoint>   # …at one exact checkpoint
avcs sync                                      # pull + push against the remote it recorded
avcs sync --watch                              # live convergence: long-poll + contention early warning
avcs land -m "add mul()"                       # push + checkpoint + integrate, in one step

需要推送时，首选 land。如果 head 已过时，服务器会将其纳入集成队列，而不是以“head 已移动——请先拉取”为由拒绝，因此结果要么是 landed，要么是交由人工决定的冲突数据包——无需重做。avcs remote add <name> <url> 可注册其他服务器；avcs sync <name> 可选择其中一个。

从 CI 读取，而无需发放签名密钥。 默认凭据是对规范请求的 AVCS-Sig 签名，其中涵盖方法和请求体——捕获到的读取凭据无法重放为写入请求。这是恰当的默认方案，但不适合临时读取者。因此，读取操作也接受 bearer token：

AVCS_HUB_TOKEN=… avcs clone https://your.server/acme/web .

该令牌在设计上仅具只读权限：写入路径根本不接受令牌参数，因此即使变量泄露，也只能克隆，绝不能推送、完成或改写策略。只要持有签名密钥，就始终优先使用签名密钥，因此已签名的读取者绝不会被悄然降级为令牌认证。令牌的格式、有效期和范围由服务器决定——参见 docs/26。

连接 Agent（MCP）

Agent 通过 AVCS 的 MCP 服务驱动 AVCS。安装 avcs 后，使用 Claude Code CLI 注册：

avcs mcp install            # runs `claude mcp add avcs -- avcs mcp` for you (scope: user)
claude mcp list             # confirm "avcs" is Connected

avcs mcp 本身就是 Agent 启动的 stdio 服务（目标仓库为 $AVCS_REPO，否则为当前工作目录）。如需手动注册——或使用其他 MCP 客户端——将其指向 avcs mcp：

claude mcp add avcs -- avcs mcp

MCP SDK 作为可选依赖提供，因此常规安装已包含它；无需额外操作。

默认情况下，每个工具的响应都很精简——只有在调用时选择 verbose 标志才会启用美化输出，因为 Agent 不会读取的空白内容，仍然会占用它付出的开销。

Agent 执行的循环——五步，落地只需一次调用：

avcs.guide                                  # the loop, the rules, error recovery
avcs.context.build   { intentOid }          # provenance, prior decisions, live risks
avcs.operation.propose { path, content }    # never write final files directly
avcs.validate.run + avcs.evidence.attach    # a behaviour change needs passing evidence
avcs.sync.land       { by }                 # push + checkpoint + integrate → landed | conflict

sync.land 是关键：过时的 head 会由系统替你纳入，因此结果要么是 landed，要么是交由人工处理的冲突数据包——绝不会出现“先拉取再重做”。添加 --profile core，即可仅公布这 13 个工具，而非全部 39 个——每次会话中交给 Agent 的架构定义会从 35 KB 缩减至 14 KB：

claude mcp add avcs -- avcs mcp --profile core

日后如需升级，请重新运行 npm install -g @izagood/avcs@latest；如需移除，请运行 npm uninstall -g @izagood/avcs（仓库数据会保留）。

从源代码安装

想跟踪最新的 main，或直接开发 AVCS？附带的 install.sh 会克隆仓库，并配置一个指向该检出目录的 avcs 启动器，因此更新只需运行 git pull，无需重新安装。

curl -fsSL https://raw.githubusercontent.com/izagood/avcs/main/install.sh | bash

这条命令会将仓库克隆到 ~/.local/share/avcs（可通过 --dir/AVCS_HOME 覆盖），并在 ~/.local/bin 中安装 avcs 启动器。再次运行即可就地更新检出目录。如果你已经克隆了仓库，也可以在仓库目录内运行安装程序：

git clone https://github.com/izagood/avcs.git && cd avcs
./install.sh

启动器会安装到 ~/.local/bin（可通过 --bin-dir <dir> 或 AVCS_BIN_DIR 覆盖）。如果 ~/.local/bin 尚未加入 PATH，安装程序会打印需要添加的配置行。

其他从源代码安装的方式：

./install.sh --bin-dir /usr/local/bin   # system-wide (may need sudo)
./install.sh --name avcs-dev            # install under a different command name
./install.sh --dir ~/src/avcs --ref v1  # one-liner mode: clone dir + ref to install
./uninstall.sh                          # remove the launcher (data is left intact)

如果运行时 node 不在 PATH 中，请通过 AVCS_NODE=/path/to/node 指定其路径。

作为库使用（@izagood/avcs）

托管服务（例如 avcshub）可以将 AVCS 核心作为带版本号的包依赖。开发和测试会通过类型剥离直接运行原始 .ts 文件，但 npm publish 会发布由 tsc 编译的 dist/（通过 tsconfig.build.json 生成 JS 和类型声明），因此使用者无需配置自己的构建工具即可导入。

npm install @izagood/avcs

import { startHub, type HubHandle } from "@izagood/avcs/hub";   // the hub server
import { ObjectStore, CorruptObjectError } from "@izagood/avcs/store";
import { verifyMessage, generateKeypair } from "@izagood/avcs/identity";
import { Repo } from "@izagood/avcs";                            // root: primary public API

const hub = await startHub({ repoDir: "./data", port: 8080, gated: true });

入口点：.（根导出文件）· ./hub · ./hub/client · ./store · ./identity · ./types。

发布：在 PR 中更新 package.json 的 version，并将其合并到 main — .github/workflows/release.yml 会检测新版本，运行 npm publish（附带来源证明），为提交打上 vX.Y.Z 标签，并创建 GitHub Release。发布步骤受注册表检查保护，因此不更改版本的 package.json 编辑不会触发操作。每个 PR 也会在 CI 中运行发布预演（npm run build + npm pack --dry-run），以便在合并前发现打包回归问题。需要一个具有 @izagood 作用域发布权限的 NPM_TOKEN 仓库密钥。

构建自己的服务

AVCS 是一种协议，而不是一项服务。符合规范的服务需要三个端点：

GET  /have            the oids you hold        → ["operation_ab12…", …]
GET  /objects/:oid    one object as JSON       → { … }  (404 if absent)
POST /objects         take one object          → { "oid": "operation_ab12…" }

其他一切都是可选的。客户端会从 GET /version 读取能力标志；如果某个标志缺失，或者端点返回 404/405/501，客户端就会自行回退。只提供前两个端点的只读镜像是合法的服务；不提供集成队列、批处理或长轮询的服务也一样。

这是有意为之：avcs 是一个面向其无法控制的部署的公共客户端。

以下两份文档定义了规范：

• 26 — 服务协议 — 每个端点的请求和响应格式、状态码、能力协商、SSH 风格的请求签名，以及一张列出服务作者常犯错误的表格。
• 24 — 规范互操作 — oid 的计算方式。如果你不是用 JavaScript 编写，请先阅读此文：对象的身份是其规范化 JSON 的 sha256，而规范化过程中的三个环节很容易出错。若实现不一致，不会收到错误，而是会出现两个各自无误、却永远无法达成一致的实现。

开始之前，先使用 spec/canonical-vectors.json 验证你的规范化器（10 个接受用例、4 个拒绝用例，每个用例都包含预期的规范化字节和 oid）。

然后让一致性测试套件检查你的服务：

AVCS_CONFORMANCE_URL=https://your.hub/acme/web npm run conformance

它会根据你的能力标志报告适用的级别：core（三个端点，以及一个能够复现源 treeHash 的克隆），之后是 sync、governance、queue。你没有声明支持的级别会被跳过，而非判定失败：部分实现也是合法的服务。

core 检查的是对象复制和克隆能力，而不是服务端投影。treeHash 比较发生在两个客户端之间——一个负责推送，另一个负责克隆——因此它证明服务忠实地返回了收到的内容，而不是证明服务本身能够从这些对象推导出树。能够正确存储和提供对象、但从不物化任何内容的服务也能通过 core，这是预期行为：投影属于客户端职责；能够做到这一点的服务只是超出了该级别的要求。

以下三个实现可供参考：

• examples/server.py — 一个完整、符合 core 级别规范的服务，全部位于单个仅依赖 Python 标准库的文件中。不需要 JS，也不需要 avcs 库：它仅依赖文档 24和黄金向量；这正是重点所在——运行 python3 examples/server.py --selftest，查看向量如何验证其规范化器，然后让一致性测试套件检查它。

• avcs-server — 基于此库构建的独立、可自托管、多仓库服务。已通过 core 级别的一致性验证；你可以运行它、阅读其代码，或将其分叉，作为自己部署的起点。

• 本仓库中的 startHub — 参考实现：仅支持单仓库，不支持多租户，但提供完整协议。可将其视为规范的可执行形式来阅读，也可以运行 avcs serve 启动它。

从代码检出运行

正在开发 AVCS 本身？所有命令都可以直接在代码检出目录中通过 node 运行：

# Walk all four merge scenarios end to end
node --experimental-strip-types src/demo.ts

# Run the behavior-contract test suite
node --experimental-strip-types --test test/*.test.ts      # or: npm test

# Human-facing CLI (or just `avcs <command>` once installed)
node --experimental-strip-types src/cli.ts init .
node --experimental-strip-types src/cli.ts status
node --experimental-strip-types src/cli.ts conflicts
node --experimental-strip-types src/cli.ts log

# Agent-facing MCP server (`avcs mcp` once installed; ships the SDK as an optionalDependency)
npm install
AVCS_REPO=$(pwd) npm run mcp      # = node --experimental-strip-types src/mcp/server.ts

类型检查（tsc --noEmit）需要 npm install；运行时本身没有依赖。

代码索引

路径	作用
src/objects/types.ts	对象模型定义（唯一事实来源）
src/store/objectStore.ts	仅追加、内容寻址的存储
src/core/canonical.ts	规范化序列化与内容寻址（oid）
src/core/identity.ts	ed25519 签名／验证与 Keyring（第 3 阶段）
src/reducer/reducer.ts	操作图 → 代码树规约 + 冲突分级
src/reducer/policy.ts	策略引擎（优先级阶梯、可靠性微调）
src/reducer/incremental.ts	增量重新规约（复用干净分组）
src/merge/merge3.ts	语言无关的 N 路、行级三方文本合并（第 2 阶段）
src/policy/owners.ts, reliability.ts	代码所有者路由 · 可靠性学习（第 5 阶段）
src/validation/runner.ts, repair.ts	验证运行器 · RepairContext（第 3 阶段）
src/concurrency/lease.ts	WorkLease（第 3 阶段）
src/release/sbom.ts	SBOM 生成（第 6 阶段）
src/hub/hubServer.ts, hubClient.ts	多机器同步服务（第 7 阶段；API 名称保留旧有的“hub”术语）
src/api/repo.ts	高层门面（供 CLI、demo、MCP 共用）
src/api/keystore.ts	机器级私有密钥库（~/.avcs/private）
src/mcp/server.ts	面向 Agent 的 MCP 接口（39 个工具；--profile core 公布 13 个）
src/cli.ts	面向用户的检查／发布 CLI
src/demo.ts	端到端场景

设计文档

• 00 — 概览与原则
• 01 — 架构
• 02 — 对象模型
• 03 — Reducer 与冲突级别
• 04 — 策略引擎
• 05 — 视图 · 检查点 · 发布
• 06 — MCP / Skill 接口
• 07 — 路线图
• 08 — 治理与共识（avcshub）
• 09 — Git/GitHub 用例覆盖与设计演进
• 10 — 生产环境设计计划
• 11 — 增量规约
• 12 — 本地生产环境
• 13 — Hub 生产环境
• 14 — Git 桥接（实际兼容性）
• 15 — 语言无关核心
• 16 — 工作区范围
• 17 — 同步收敛：集成队列与实时同步（设计）
• 18 — 将 MCP 作为一等连接方式
• 19 — 实体身份：重命名 × 编辑的交换律
• 20 — 工作区优先的 Git 桥接
• 21 — shared-paths：工作区间共享的构建环境
• 22 — 区域策略仲裁（设计）
• 23 — 本地撤销：共享前的退出通道
• 24 — 规范化互操作：语言无关规范化子集
• 25 — Agent 快速入门：通过 Claude Code（MCP）驱动 AVCS
• 26 — 服务端协议：符合规范的服务必须提供的内容

贡献

这是一个早期研究原型，设计仍在不断演进。欢迎提交问题和参与讨论——如果你计划提出变更，上面的设计文档是了解当前模型设计依据的最佳起点。提交拉取请求前，请运行 npm test 和 npm run typecheck。

提交问题

使用 AVCS 时遇到希望改进的地方？请提交问题，而不要发送自由格式的反馈——结构化报告更容易处理。我们在 .github/ISSUE_TEMPLATE 下提供了两个模板：

• 🔧 变更请求 — 提议更改现有行为、CLI/MCP 接口、默认设置或文档。
• 🐞 Bug 报告 — 某项功能行为异常、发生崩溃或产生非确定性结果。

🌐 欢迎使用任何语言。 请使用自己最熟悉的语言提交问题，例如英语、한국어、 日本語等。维护者会酌情翻译；不要让语言成为反馈问题的障碍。

每次向 main 推送代码或提交拉取请求时，都会运行 CI (.github/workflows/ci.yml)：在 Node 22.x 和 24.x 上依次运行 npm ci → npm run typecheck → npm test。只有 CI 全部通过后，才会合并 PR。

许可证

本项目根据 Apache License 2.0 授权。版权所有 © 2026 jaebin lee。署名信息请参阅 NOTICE。