内容
# 上下文控制平面（`ctx`）
上下文控制平面（ContextVC）是一种原生的 Git 上下文控制平面，适用于 AI 编程代理。
它将项目规则、决策、故障记忆、操作指南、偏好和代码映射存储在 `.context/` 目录中，然后将其渲染为 Claude Code、Cursor、Codex、GitHub Copilot、Gemini 和 Cline 等原生文件。
简而言之：**代理内存成为仓库级基础设施，可以版本控制、审查、合并、在 CI 中检查，并在进行高风险操作之前强制执行。**
## 为什么存在
AI 编程工具已经有很多地方可以放置内存：提示、规则文件、聊天摘要、向量存储、本地偏好和会话日志。
这些系统有助于代理记住，但通常不能回答仓库需要的工程问题：
- 该记忆是否经过审查？
- 是否遵循分支和拉取请求？
- 生成的代理文件是否仍然同步？
- 规则是否已过时，因为源文件已更改？
- 是否可以在代理再次运行之前阻止已知不良命令？
- CI 是否可以证明上下文是健康的？
- 两个分支是否可以合并上下文而不会默默丢失语义？
上下文控制平面（ContextVC）是为了解决这些问题而构建的。
## 安装
从 GitHub 安装已标记的版本：
```bash
cargo install --locked --git https://github.com/HaochengLu/contextvc.git --tag v0.1.0
ctx --help
```
或者从源代码克隆和安装：
```bash
git clone https://github.com/HaochengLu/contextvc.git
cd contextvc
cargo install --locked --path .
ctx --help
```
您需要 Rust 稳定工具链。如果未安装 Rust，请从 [rustup.rs](https://rustup.rs/) 安装。
## 快速入门
在任何仓库中：
```bash
ctx init --install-hooks
ctx status
ctx check
```
这会创建 `.context/` 目录，渲染代理文件，安装本地钩子适配器，并写入 MCP 配置。
生成的 文件可以包括：
```text
.context/
AGENTS.md
CLAUDE.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
GEMINI.md
.cline/memory-bank/contextvc.md
.mcp.json
```
上下文控制平面（ContextVC）是本地优先的：
- 无需 API 密钥
- 无需托管服务
- 无需源代码上传
- 本地 stdio MCP 服务器
- 长期上下文存储在仓库中，可以使用 Git 审查
## 传统内存管理没有的功能
传统内存管理通常将内存视为摘要、向量记录、用户偏好或私有代理历史。上下文控制平面（ContextVC）将内存视为仓库控制平面。
| 传统内存管理通常缺乏 | 上下文控制平面（ContextVC）提供 |
| --- | --- |
| 内存不跟随仓库 | 持久对象存储在 `.context/objects/` 中，并随分支、拉取请求、克隆和分叉而移动 |
| 内存可以被调用但不能被强制执行 | `ctx precheck`、MCP 和钩子在进行高风险操作之前返回 `warn`、`ask` 或 `block` |
| 内存写入跳过审查 | 运行时学习创建提案；`ctx review accept` 在正式化之前是必需的 |
| 内存不知道代码何时更改 | 文件/源绑定存储哈希；`ctx check` 检测过时的绑定 |
| 每个代理都有单独的规则文件 | `.context/` 是真实来源；`ctx render` 为许多代理编译原生文件 |
| 检索无法证明生成的 文件是当前版本 | `render.lock`、模式验证和管理块漂移检查在 CI 中运行 |
| 分支冲突不明确 | `ctx merge` 和 `ctx harvest` 保留语义冲突；冲突的约束失败并关闭 |
| 回滚是手动的 | `ctx blame`、`ctx diff` 和 `ctx revert` 使用 Git 语义跟踪上下文对象 |
| 客户端可以伪造事件身份 | MCP `context_log` 重建服务器拥有的字段并遮蔽秘密 |
| 很难衡量内存是否防止重复 | RepeatBench 验证已知故障被捕获，而安全操作仍然通过 |
## 核心功能
| 功能 | 命令/文件 | 功能描述 |
| --- | --- | --- |
| 初始化上下文 | `ctx init` | 创建 `.context/`、投影文件和锁文件 |
| 采用现有规则 | `ctx adopt` | 将 `AGENTS.md`、`CLAUDE.md` 和 Cursor 规则导入对象 |
| 填充代码映射 | `ctx backfill` | 从 Git 历史记录构建代码映射对象 |
| 渲染投影 | `ctx render` | 生成原生代理文件，同时保留人类编写的区域 |
| CI 守卫 | `ctx check` | 检测投影漂移、过时绑定、模式错误、冲突和不良事件 |
| 项目简介 | `ctx brief` | 为代理任务打印简洁的上下文 |
| MCP 运行时 | `ctx serve-mcp` | 为简报、搜索、预检查、日志、提案和状态提供本地工具 |
| 安装钩子 | `ctx install` | 安装 Claude / Cursor / Codex 钩子、MCP 配置和 Git 钩子 |
| 操作前门控 | `ctx precheck` | 在进行高风险操作之前检查命令或路径与约束和故障内存 |
| 门控休眠 | `ctx snooze` | 在本地抑制特定的门控命中 |
| 故障写入 | `ctx log-event` / `ctx hook stop` | 将运行时故障提炼成提案 |
| 人工审查 | `ctx review` | 在提案进入真实来源之前接受或拒绝提案 |
| 过时检查 | `ctx verify` | 验证对象绑定与当前文件/源哈希 |
| 语义合并 | `ctx merge` / `ctx harvest` | 保留语义冲突并阻止冲突的约束 |
| Git 历史记录 | `ctx log` / `ctx blame` / `ctx diff` / `ctx revert` | 使用 Git 语义跟踪和回滚上下文对象 |
| 诊断 | `ctx doctor` | 检查配置、锁文件、钩子、模式和可能的秘密 |
| 模式 | `ctx schema` | 打印或写入 OCL 对象 JSON 模式 |
| 基准测试 | `ctx repeatbench` | 运行重复故障门控场景 |
## 架构
同一张图也可在 [docs/architecture.mmd](docs/architecture.mmd) 中找到。
## 三个实际工作流程
### 工作流程 1：引导现有仓库
当仓库已经有代理规则分散在各个文件中时使用。
```bash
cd your-repo
ctx init --skip-adopt
ctx adopt
ctx render --force
ctx check
ctx install all
```
发生的情况：
- 现有代理指令被导入 `.context/objects/` 中
- 原生投影文件从单一真实来源重新生成
- 钩子和 MCP 配置在本地安装
- CI 可以运行 `ctx check` 以检测漂移
### 工作流程 2：阻止重复的不良命令
创建一次约束，让所有支持的代理都可以使用它。
```bash
mkdir -p .context/objects/constraints
cat > .context/objects/constraints/use-pnpm.md <<'EOF'
---
id: c-usepnpm
type: constraint
title: 使用 pnpm
scope: ["**"]
status: active
trust: human
confidence: 1.0
evidence: []
bindings:
- kind: command
pattern: "npm install"
enforcement: block
created: init
---
使用 `pnpm install`；不要在此仓库中运行 `npm install`。
EOF
ctx render --force
ctx check
ctx precheck --command "npm install"
```
预期行为：
- `ctx render` 将约束投影到代理原生文件中
- `ctx precheck` 返回 `npm install` 的阻止门控命中
- 不匹配约束的安全命令不会被阻止
### 工作流程 3：将故障转化为审查的内存
使用审查队列，而不是让运行时学习默默地改变真实来源。
```bash
ctx log-event \
--event-type failure \
--payload '{"target":"src/parser.rs","action":"cargo test parser","outcome":"failed","evidence":"parser fixture failed"}'
ctx hook stop
ctx review list
ctx review accept <proposal-id>
ctx render --force
ctx check
```
发生的情况：
- 故障事件被本地追加
- 从重复或有意义的证据中生成提案
- 人工接受或拒绝提案
- 接受的内存成为正式的 `.context/objects/` 文件
- 投影和锁文件被重新生成
## RepeatBench 结果
RepeatBench 检查已知重复故障是否被门控捕获，而假阳性操作仍然安全。
最新提交的摘要：[benchmarks/repeatbench/results/latest-summary.json](benchmarks/repeatbench/results/latest-summary.json)
```json
{
"scenarios": 1,
"gate_hits": 1,
"misses": 0,
"repeat_failure_rate": 0.0
}
```
原始每场景输出存储在 [benchmarks/repeatbench/results/latest.json](benchmarks/repeatbench/results/latest.json) 中。
自己运行：
```bash
ctx repeatbench --json
ctx repeatbench --json --output benchmarks/repeatbench/results/latest.json
```
## CI
将 ContextVC 用作仓库健康检查：
```bash
ctx check
```
包含的 GitHub Actions 工作流程运行：
```bash
cargo fmt --all -- --check
cargo test --all --locked
cargo build --release --locked
target/release/ctx repeatbench --json
git diff --check
```
`ctx check` 在以下情况下失败：
- 缺失 `.context/VERSION` 或 `render.lock`
- 对象更改未渲染
- 编辑了托管块
- 过时文件/源绑定
- 无效对象模式字段
- 损坏的事件 JSONL
- 冲突的约束
## 对象模型
ContextVC 将持久知识存储为带有 OCL 前面的 Markdown 文件。
对象类型：
- `constraint`：硬或软规则，通常由路径或命令强制执行
- `decision`：架构或实现决策
- `failure`：重复故障或已知陷阱
- `howto`：任务配方
- `codemap`：重要源区域或高 churn 文件
- `preference`：样式、测试、格式化或工作流偏好
托管投影文件使用 `ctx:begin` / `ctx:end` 块。`ctx render` 保留这些块之外的手动编写的文本。
## 本地安全边界
- ContextVC 读取和写入当前仓库和本地配置文件。
- 事件和对象在保存前会删除常见的秘密模式。
- MCP `context_log` 不信任客户端提供的 actor/id 字段。
- 绑定路径拒绝绝对路径、父目录遍历、仓库外符号链接和超大文件。
- 审查接受使用预检和渲染回滚。
- 冲突的约束失败并关闭。
## 开发
```bash
cargo fmt --all
cargo test --all
cargo build --release
target/release/ctx repeatbench --json --output target/repeatbench-results.jsonl
git diff --check
```
## 发布
第一个公开标签是 `v0.1.0`。
```bash
git fetch --tags
git checkout v0.1.0
cargo install --locked --path .
```
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器