内容
<p align="center"><strong>锁步</strong></p>
<h3 align="center">阻止团队的AI编码代理进行冲突更改 — 无需共享源代码。</h3>
<p align="center">
<a href="https://github.com/lockstep-team-agent/lockstep/actions/workflows/ci.yml"><img src="https://github.com/lockstep-team-agent/lockstep/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/lockstep-cli"><img src="https://img.shields.io/npm/v/lockstep-cli" alt="npm version"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
<img src="https://img.shields.io/badge/TypeScript-strict-blue" alt="TypeScript strict">
<img src="https://img.shields.io/badge/Fastify-5-black" alt="Fastify 5">
<img src="https://img.shields.io/badge/PostgreSQL-16-336791" alt="PostgreSQL 16">
</p>
<!--
HERO ASSET — record a 20–30s clip of the magic loop and embed it here:
Agent A renames a contract surface → Lockstep captures the decision →
Agent B's next session is warned automatically → an uncoordinated PR fails the gate.
Save as docs/assets/demo.gif (+ docs/assets/demo.mp4 fallback), then uncomment:
<p align="center"><img src="docs/assets/demo.gif" alt="Lockstep in action" width="820"></p>
LIVE DEMO — once the hosted playground URL is live, add it to the nav line below:
<a href="https://YOUR-DEMO-URL"><b>▶ Try the live demo</b></a> ·
-->
<p align="center">
<a href="#quick-start"><b>快速开始</b></a> ·
<a href="#how-it-works"><b>工作原理</b></a> ·
<a href="./DEPLOY.md"><b>部署</b></a>
</p>
---
当两个开发者将AI编码代理（如Claude Code、Codex、Gemini CLI）指向同一个系统时，代理之间不知道对方刚刚做了什么：
- **代理A** 重命名一个API端点 → **代理B** 继续调用旧端点。
- **代理A** 选择一种身份验证模式 → **代理B** 发明一种冲突的模式。
- 没有人知道谁拥有哪个，发生了什么变化，或者仍然需要审查什么。
**锁步是代理的 neutral 记录系统。** 每个决定、合同更改和依赖关系都被捕获并实时路由到需要的代理，而无需将源代码从开发人员的机器上移出（只有决定和元数据同步到云端）。
```bash
npm i -g lockstep-cli
```
### 对比
| | 没有 | Slack / 文档 | CODEOWNERS | **锁步** |
| --------------------------------------- | :-----: | :----------: | :---------: | :--------------------: |
| 代理了解其他代理的更改 | ❌ | 手动 | ❌ | ✅ 自动 |
| 合同更改路由到消费者 | ❌ | ❌ | ❌ | ✅ 依赖关系图 |
| 在PR时间阻止不协调的更改 | ❌ | ❌ | 仅审查 | ✅ 调和门 |
| 跨代理供应商工作 | — | — | — | ✅ Claude/Codex/Gemini |
| 源代码离开您的机器 | — | 有时 | ❌ | ❌ 从不 |
## 工作原理
```
开发人员A（机器） 锁步云 开发人员B（机器）
──────────────────── ─────────────── ────────────────────
┌─────────────────┐ ┌─────────────────┐
│ Claude Code │ │ Codex / Gemini │
│ + MCP Server │──── 捕获 ────┐ │ + MCP Server │
└─────────────────┘ │ └─────────────────┘
│ ▼ ▲
│ ┌─────────────┐ │
钩子在每个文件编辑上触发 ──→ │ 决定 │ ──→ 依赖关系图 │
（PostToolUse） │ 合同 │ 查看谁 │
│ │ 所有权 │ 消耗更改的 │
▼ │ 依赖关系图 │ │ │
将差异分类为合同 追加日志 分发到 ───────┘
表面或所有权 无源代码 每个消费者的收件箱
```
### 通知生命周期
**1. 捕获** — Claude Code钩子在每个文件编辑（`PostToolUse`）和会话结束时触发。CLI将工作树与HEAD进行比较，分类每个更改的文件 — 它是API路由、`.proto`、OpenAPI规范还是导出的函数？ 标记为公共接口的文件为**合同表面**。更改发布到账本中，风险等级为（`owned`如果您单独更改，`shared`如果它是合同表面）。
**2. 路由** — 当更改到达账本时，**依赖关系图** 启动。每个注册了更改表面的依赖关系的仓库都会收到通知，分发到其收件箱。发送者被排除在外。 如果仓库B声明`POST /auth/session`为依赖关系，而仓库A刚刚更改了该表面，则仓库B的收件箱会自动收到更改 — 无需任何配置。
**3. 重放** — 当代理启动新会话（`SessionStart`钩子）时，锁步读取收件箱并重放自上次会话以来到达的所有内容：未读更改、绑定决策和开放问题。 这被注入为`additionalContext`，以便代理立即了解队友的操作。
**4. 决策** — 代理可以提出特定于表面的决策（例如“将`POST /auth/login`重名为`POST /auth/session`）。所有者范围的决策立即绑定。 共享/合同决策在另一个团队成员确认后保持`open` — 然后它们对整个项目生效。
**5. 门控** — 在PR时，二级协调门控（GitHub Action）检查每个更改的合同表面是否与账本一致。 如果表面被更改但没有绑定决策，PR检查失败。 这可以防止一级未捕获的内容。
### 谁会收到通知？
| 发生什么 | 谁会收到通知 | 如何通知 |
| ---------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
| 合同表面更改（API路由，proto，导出的类型） | 每个注册了该表面的依赖关系的仓库 | 收件箱分发，在下一个会话重放 |
| 在共享范围内提出决策 | 所有项目成员在决策列表中看到它 | `decisions` MCP工具/仪表盘 |
| 提问（可选范围到表面） | 所有项目成员 | 收件箱/仪表盘 |
| 任务委派给特定队友 | 被委派的队友 | 收件箱/仪表盘 |
| PR触及具有无绑定决策的合同表面 | PR作者 | GitHub Action检查失败，附有违规列表 |
### 云端流动的内容（和不流动的内容）
| 通过锁步流动 | 从未离开机器 |
| --------------------------------------------------------- | ------------------------ |
| 决策文本（“将端点X重命名为Y”） | 源代码 |
| 表面标识符（`POST /auth/session`） | 文件内容 |
| 更改摘要（“更改了3个文件：routes/auth.ts, ...”） | Git差异 |
| 依赖关系边（仓库B使用表面X） | 凭证或密钥 |
| 所有权规则（从CODEOWNERS解析） | 环境变量 |
## 功能
| 功能 | 描述 |
| --------------------- | ---------------------------------------------------------------------------- |
| **跨供应商** | 与Claude Code、Codex、Gemini CLI合作 — 任何支持MCP的代理 |
| **决策账本** | 追加日志，具有提案/确认工作流的CAS版本决策 |
| **依赖关系图** | 自动路由 — 更改表面通知每个消费者 |
| **所有权图** | CODEOWNERS支持的所有权，自动连接 |
| **两级捕获** | 一级：实时更改捕获。二级：PR级协调门控 |
| **问题和任务** | 跨代理委派 — 提问，分配任务，获取答案 |
| **MCP原生** | 12工具MCP服务器在开发人员的机器上运行 |
| **仪表盘** | Next.js UI用于决策，合同，依赖关系，活动和任务 |
| **自托管** | `docker compose up`在您自己的基础设施上，或使用托管云 |
| **默认安全** | RLS隔离，加密令牌，追加日志审计跟踪，代码中没有密钥 |
## 快速开始
在5分钟内建立一个可用的本地设置 — 无需GitHub应用程序密钥。
### 1. 启动堆栈
```bash
git clone https://github.com/lockstep-team-agent/lockstep.git
cd lockstep
cp .env.example .env # 默认启用dev-login
docker compose up --build # 启动Postgres + API + 仪表盘
```
等待日志中出现`lockstep-core listening on :8080`。 验证：
```bash
curl http://localhost:8080/readyz
# => { "ok": true, "db": "up", "deployment": "self-host" }
```
这为您提供：
- **API** 在 http://localhost:8080
- **仪表盘** 在 http://localhost:3000
- **Postgres** 在 localhost:5432
### 2. 安装CLI并登录
```bash
npm i -g lockstep-cli
# 将CLI指向您的本地服务器（永久保存 — 仅需一次）
lockstep login --api http://localhost:8080 --dev --dev-id 1 --dev-login alice
```
> **重要**: `--api`标志告诉CLI后端在哪里。 如果没有它，CLI默认为`http://localhost:8080`。 对于已部署的服务器，请使用`lockstep login --api https://your-server.example.com`。
### 3. 连接您的仓库
```bash
cd your-project # 任何具有源代码仓库的git仓库
lockstep init # 在仓库中安装MCP服务器+钩子
lockstep connect --project "my-team" # 创建项目并链接此仓库
```
### 4. 打开仪表盘
在浏览器中打开 http://localhost:3000。 要登录，您需要会话令牌。 使用以下方法获取：
```bash
# macOS（密钥链中存储令牌）
security find-generic-password -s lockstep -a session-token -w
# Linux / 备用（令牌存储在文件中）
cat ~/.lockstep/credentials.json
```
将 `lsk_...` 令牌粘贴到仪表盘登录字段中。
### 5. 添加队友
您的队友运行（在他们的机器上）：
```bash
npm i -g lockstep-cli
lockstep login --api http://localhost:8080 --dev --dev-id 2 --dev-login bob
cd their-project
lockstep init
lockstep connect --project "my-team" # 加入现有项目
```
两个开发者现在都在同一个项目中。 他们将在仪表盘的成员页面上看到对方。
### 6. 使用AI代理开始编码
在仓库中打开Claude Code（或任何MCP兼容的代理）。 在会话开始时，代理接收锁步自上次会话以来发生的所有内容的重放 — 更改，绑定决策，开放问题和分配的任务。
当您工作时，合同更改会自动捕获并路由到队友的收件箱。
> **生产设置**: 对于真正的GitHub身份验证（无需 `--dev` 标志），注册GitHub应用程序并在 `.env` 中填写密钥。 设置 `NODE_ENV=production` 和 `LOCKSTEP_DEV_LOGIN=0`。 有关Railway/云部署，请参阅 [DEPLOY.md](./DEPLOY.md)。
## 项目结构
```
packages/core/ # Fastify API + PostgreSQL（Drizzle ORM），RLS隔离，追加日志
packages/cli/ # lockstep-cli — 登录，初始化，连接，捕获，MCP服务器
packages/web/ # Next.js仪表盘 — 决策，合同，依赖关系，活动，任务
actions/pr-check # GitHub Action — PR的二级协调门控
```
## CLI命令
| 命令 | 功能 |
| ------------------------------------- | ---------------------------------------------------------- |
| `lockstep login [--api <url>]` | 通过GitHub设备流（或 `--dev` 用于本地）进行身份验证 |
| `lockstep init` | 在当前仓库中安装MCP服务器+钩子 |
| `lockstep connect [--project <name>]` | 将此仓库链接到共享项目 |
| `lockstep invite <github-handle>` | 邀请队友加入您的项目 |
| `lockstep capture` | 手动触发更改捕获（也自动运行） |
| `lockstep status` / `lockstep doctor` | 检查身份验证+配置健康 |
## 开发
```bash
npm run build # 构建所有工作区
npm run typecheck # 类型检查所有工作区
npm run test # 运行所有测试
npm run lint # 校验所有工作区
npm run format # 使用Prettier格式化
npm run dev:core # 在监视模式下启动核心API
```
有关分支约定，PR流程和代码样式，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 部署
锁步有两种运行模式（12因子配置）：
- **自托管**: 在您的基础设施上运行 `docker compose up` — 您注册自己的GitHub应用程序
- **托管云**: 具有RLS隔离的多租户SaaS
有关分步Railway部署说明，请参阅 [DEPLOY.md](./DEPLOY.md)。
## 架构
- **26表架构**，带有行级安全（RLS）进行租户隔离
- **追加日志** — 决策是不可变的，带有内容可寻址存储的版本控制
- **供应商中立适配器模式** — 新的AI代理集成是一个适配器文件
- **Zod验证**，在每个边界上，以及整个TypeScript严格模式
- **零源代码存储** — 只有决策，合同和元数据流经系统
## 安全
有关我们的责任披露政策，请参阅 [SECURITY.md](./SECURITY.md)。
## 许可证
[MIT](./LICENSE) © Naman Jain
连接信息
猜你喜欢
暂无推荐服务器