# agent-lane

**Repository Path**: miracleeeee/agent-lane

## Basic Information

- **Project Name**: agent-lane
- **Description**: 为编码代理管理基于 Git worktree 隔离的本地任务工作流。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Lane

Agent Lane 是一个 Cargo 子命令，用于管理基于 Git worktree 隔离的本地编码代理工作流。

一条 lane 对应一个明确目标、一个 Git 分支、一个独占 worktree 和一套可跨会话恢复的
工作记录。一个项目可以同时拥有多条 lane，各自的未提交代码互不影响。

当前版本支持 Linux 和 macOS，需要 Git 和 Rust 1.88 或更高版本。
默认 Codex 会话管理通过 Codex CLI 的公开 App Server 协议完成；不读取其私有会话数据库。

## 安装

从 crates.io 安装：

```bash
cargo install cargo-lane --locked
```

从源码安装：

```bash
git clone https://gitee.com/miracleeeee/agent-lane.git
cd agent-lane
cargo install --path . --locked
```

日常以 Cargo 子命令形式调用：

```bash
cargo lane --version
```

## 快速开始

```bash
# 在要管理的 Git 仓库中创建 lane
cargo lane new auth-api -o "重构用户认证 API"

# 启动或恢复默认 Codex 会话
cargo lane start auth-api

# 打开 new 创建的源码与工作流多根编辑器工作区
cargo lane code auth-api

# 查看目标、分支、worktree 和里程碑状态
cargo lane status auth-api

# 恢复当前工作集；调查前检索已有记录
cargo lane briefing auth-api
cargo lane recall --lane auth-api "认证超时"

# 完成后关闭 lane；会话由 close 自动归档
cargo lane close auth-api

# 需要继续时重新激活；close 归档的会话会自动恢复
cargo lane reopen auth-api
```

默认数据位于 `~/.agent-lane`，可通过 `AGENT_LANE_HOME` 修改。lane 的工作流记录位于
`agents/`，源码位于独占的 `workspace/` worktree，不会写入被管理项目的工作流私有数据。
新 lane 默认在根目录创建一个与源码仓库完全独立的本地 Git 审阅仓库，并生成一次初始
基线提交；之后的工作流提交完全由用户管理。无需该仓库时在创建命令中加入
`-n/--no-workflow-git`。

面向人的 lane 列表使用宽窄终端一致的紧凑条目，空间不足时只移动状态并换行长字段；
其他规则数据按终端宽度使用表格或卡片。终端中用低亮度样式显示辅助结构、字段标签
（包括表格表头）和中性标记，只为明确状态使用颜色；重定向到文件或管道时保持纯文本；
自动化脚本应继续使用命令提供的 `--json` 或原始路径输出。

## 核心行为

- `new` 从明确的 Git commit 创建新分支，不复制原工作树中的未提交改动。
- `new` 默认为 `AGENTS.md`、普通工作流记录、脚本和非秘密配置创建本地 Git 审阅基线；
  `workspace/`、机器状态、秘密、日志、产物和临时文件不会进入该仓库。
- `briefing` 汇总目标、短期上下文、未关闭计划和实时 Git 状态；`recall` 只检索公开白名单
  记录，默认不输出命中正文，也不扫描秘密、会话、日志、产物或临时目录；公开文件通过
  禁止跟随链接的文件描述符路径打开，不能被并发路径替换重定向到秘密目录或 lane 外部。
- `start` 精确恢复 Agent Lane 记录的默认会话，并为确认归属当前 lane 的 Codex 会话附加
  只读恢复提示：先报告现场并等待用户，不直接继续任务或修改文件；`-n <NAME>` 创建用途
  明确的新会话，`-B/--no-bootstrap` 可关闭提示。
- `new` 创建 `<lane-name>.code-workspace`，`code` 直接打开这份可由用户维护的源码与工作流
  双根编辑器配置。
- `close` 拒绝移除脏 worktree，也默认拒绝会随 worktree 删除的 ignored 文件；确需丢弃时
  使用 `--discard-ignored`，非交互环境还必须同时使用 `--yes`。
- `reopen` 恢复已关闭 lane、由 `close` 归档的会话及关闭前的默认会话选择。
- `purge` 永久删除归档、关联 Codex 会话和对应 Git 分支。
- 生命周期操作中断后使用 `cargo lane recover` 验证现场并继续。
- 同一 lane 的 runner 运行期间，生命周期恢复和会话变更会明确拒绝；存在待恢复事务时
  `start` 也会要求先执行 `recover`，不影响其他 lane。
- IP、用户名和私钥路径等连接配置可保存在 `agents/config/`；秘密集中保存在
  `agents/private/`，不写入普通文档和日志。

## 配置

可选的全局配置文件是 `~/.agent-lane/config.toml`：

```toml
schema_version = 1

[runner]
command = "codex"
args = []

[editor]
command = "code"
args = []

[git]
branch_prefix = "lane/"
```

`new` 会把 runner 的命令和固定参数完整写入 lane 清单；之后修改全局默认值不会改变已建
lane 的 runner。编辑器需要支持打开 `.code-workspace` 文件，默认的 VS Code 和 Cursor
均可直接使用。Git remote URL 不进入清单，避免把 URL 中的凭据写入机器数据。

## 文档

- [工作流模式](docs/workflow.md)：理解一条 lane 如何组织并推进目标。
- [使用手册](docs/usage.md)：完整目录、命令参数和操作流程。
- [设计文档](docs/design.md)：存储契约、事务、Git 安全和实现边界。

## 开发

```bash
cargo fmt --all --check
cargo +1.88.0 check --all-targets --locked
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo package --locked
cargo tree --locked --duplicates
```

## License

本项目使用 [Apache License 2.0](LICENSE)。