entireio/cli
GitHub: entireio/cli
Entire 是一款将 AI 编程助手会话与 Git 提交关联的工具，帮助开发者追溯代码变更的完整上下文和 AI 推理过程。
Stars: 3542 | Forks: 255
# 完整 CLI
Entire 接入你的 Git 工作流，在你工作时捕获 AI agent 会话。会话与提交一同索引，创建关于代码如何在你的仓库中编写的可搜索记录。
使用 Entire，你可以：
- **理解代码变更原因** — 查看完整的 prompt/response 转录以及涉及的文件
- **即时恢复** — 当 agent 偏离轨道时回退到已知良好的 checkpoint 并无缝恢复
- **保持 Git 历史整洁** — 在单独的分支上保留 agent 上下文
- **更快上手** — 展示从 prompt → 变更 → 提交的路径
- **保持可追溯性** — 在需要时支持审计和合规要求
## 目录
- [快速入门](#quick-start)
- [典型工作流](#typical-workflow)
- [核心概念](#key-concepts)
- [工作原理](#how-it-works)
- [策略](#strategy)
- [命令参考](#commands-reference)
- [配置](#configuration)
- [安全与隐私](#security--privacy)
- [故障排除](#troubleshooting)
- [开发](#development)
- [获取帮助](#getting-help)
- [许可证](#license)
## 环境要求
- Git
- macOS 或 Linux（Windows 通过 WSL）
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenCode](https://opencode.ai/docs/cli/), [Cursor](https://www.cursor.com/), 或 [GitHub Copilot CLI](https://docs.github.com/en/copilot) 已安装并完成认证
## 快速入门
```
# 通过 Homebrew 安装
brew tap entireio/tap
brew install entireio/tap/entire
# 或通过 Go 安装
go install github.com/entireio/cli/cmd/entire@latest
# 在您的项目中启用
cd your-project && entire enable
# 检查状态
entire status
```
## 典型工作流
### 1. 在你的仓库中启用 Entire
```
entire enable
```
这会安装 agent 和 git hooks 以配合你的 AI agent（Claude Code、Gemini CLI、OpenCode、Cursor 或 Copilot CLI）工作。你会被提示选择要启用的 agent。要以非交互方式启用特定 agent，请使用 `entire enable --agent `（例如 `entire enable --agent cursor`）。
这些 hooks 在你工作时捕获会话数据。当你或 agent 进行 git commit 时会创建 checkpoint。你的代码提交保持整洁，Entire 永远不会在你的活动分支上创建提交。所有会话元数据都存储在单独的 `entire/checkpoints/v1` 分支上。
### 2. 使用你的 AI Agent
只需正常使用 Claude Code、Gemini CLI、OpenCode、Cursor 或 Copilot CLI。Entire 在后台运行，跟踪你的会话：
```
entire status # Check current session status anytime
```
### 3. 回退到之前的 Checkpoint
如果你想撤销一些更改并返回到较早的 checkpoint：
```
entire rewind
```
这会显示当前会话中所有可用的 checkpoint。选择一个即可将代码恢复到该确切状态。
### 4. 恢复之前的会话
要恢复某个分支的最新 checkpoint 会话元数据：
```
entire resume
```
Entire 会检出该分支，恢复最新的 checkpoint 会话元数据（一个或多个会话），并打印继续所需的命令。
### 5. 禁用 Entire（可选）
```
entire disable
```
移除 git hooks。你的代码和提交历史保持不变。
## 核心概念
### Sessions（会话）
一个 **session** 代表与你的 AI agent 从开始到结束的完整交互。每个会话捕获所有 prompt、response、修改的文件和时间戳。
**Session ID 格式：** `YYYY-MM-DD-`（例如 `2026-01-08-abc123de-f456-7890-abcd-ef1234567890`）
会话与你的代码提交分开存储在 `entire/checkpoints/v1` 分支上。
### Checkpoints（检查点）
一个 **checkpoint** 是会话中你可以回退到的快照——你工作中的"保存点"。
当你或 agent 进行 git commit 时会创建 checkpoint。**Checkpoint ID** 是 12 个字符的十六进制字符串（例如 `a3b2c4d5e6f7`）。
### 工作原理
```
Your Branch entire/checkpoints/v1
│ │
▼ │
[Base Commit] │
│ │
│ ┌─── Agent works ───┐ │
│ │ Step 1 │ │
│ │ Step 2 │ │
│ │ Step 3 │ │
│ └───────────────────┘ │
│ │
▼ ▼
[Your Commit] ─────────────────► [Session Metadata]
│ (transcript, prompts,
│ files touched)
▼
```
Checkpoint 在你工作时保存。当你提交时，会话元数据会永久存储在 `entire/checkpoints/v1` 分支上并与你的提交关联。
### 策略
Entire 使用手动提交策略来保持你的 git 历史整洁：
- **不在你的分支上创建提交** — Entire 永远不会在活动分支上创建提交
- **适用于任何分支** — 可在 main、master 和 feature 分支上正常工作
- **非破坏性回退** — 从任何 checkpoint 恢复文件而不改变提交历史
- **元数据单独存储** — 所有会话数据存储在 `entire/checkpoints/v1` 分支上
### Git Worktrees
Entire 与 [git worktrees](https://git-scm.com/docs/git-worktree) 无缝协作。每个 worktree 都有独立的会话跟踪，因此你可以在不同的 worktree 中运行多个 AI 会话而不会冲突。
### 并发会话
多个 AI 会话可以在同一个提交上运行。如果你在另一个会话有未提交的工作时启动第二个会话，Entire 会警告你并分别跟踪它们。两个会话的 checkpoint 都会被保留，并且可以独立回退。
## 命令参考
| 命令 | 描述 |
| ---------------- | ------------------------------------------------------------------- |
| `entire clean` | 清理孤立的 Entire 数据 |
| `entire disable` | 从仓库中移除 Entire hooks |
| `entire doctor` | 修复或清理卡住的会话 |
| `entire enable` | 在你的仓库中启用 Entire |
| `entire explain` | 解释会话或提交 |
| `entire reset` | 删除当前 HEAD 提交的 shadow branch 和会话状态 |
| `entire resume` | 切换到分支，恢复最新的 checkpoint 会话元数据，并显示继续的命令 |
| `entire rewind` | 回退到之前的 checkpoint |
| `entire status` | 显示当前会话信息 |
| `entire version` | 显示 Entire CLI 版本 |
### `entire enable` 标志
| 标志 | 描述 |
| ---------------------- | ------------------------------------------------------------- |
| `--agent ` | 要安装 hooks 的 AI agent：`claude-code`, `gemini`, `opencode`, `cursor`, 或 `copilot-cli` |
| `--force`, `-f` | 强制重新安装 hooks（先移除现有的 Entire hooks） |
| `--local` | 将设置写入 `settings.local.json` 而非 `settings.json` |
| `--project` | 将设置写入 `settings.json`（即使已存在） |
| `--skip-push-sessions` | 禁用 git push 时自动推送会话日志 |
| `--checkpoint-remote ` | 将 checkpoint 分支推送到单独的仓库（例如 `github:org/checkpoints-repo`） |
| `--telemetry=false` | 禁用匿名使用分析 |
**示例：**
```
# 强制重新安装 hooks
entire enable --force
# 本地保存设置（不提交至 git）
entire enable --local
```
## 配置
Entire 在 `.entire/` 目录中使用两个配置文件：
### settings.json（项目设置）
团队共享，通常会提交到 git：
```
{
"enabled": true
}
```
### settings.local.json（本地设置）
个人覆盖，默认被 gitignore：
```
{
"enabled": false,
"log_level": "debug"
}
```
### 配置选项
| 选项 | 值 | 描述 |
| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------ |
| `enabled` | `true`, `false` | 启用/禁用 Entire |
| `log_level` | `debug`, `info`, `warn`, `error` | 日志详细程度 |
| `strategy_options.push_sessions` | `true`, `false` | 在 git push 时自动推送 `entire/checkpoints/v1` 分支 |
| `strategy_options.checkpoint_remote` | `{"provider": "github", "repo": "org/repo"}` | 将 checkpoint 分支推送到单独的仓库（见下文） |
| `strategy_options.summarize.enabled` | `true`, `false` | 在提交时自动生成 AI 摘要 |
| `telemetry` | `true`, `false` | 向 Posthog 发送匿名使用统计 |
### Agent Hook 配置
每个 agent 将其 hook 配置存储在自己的目录中。当你运行 `entire enable` 时，hooks 会安装到每个选定 agent 的相应位置：
| Agent | Hook 位置 | 格式 |
|-------------| ----------------------------- | ----------------- |
| Claude Code | `.claude/settings.json` | JSON hooks 配置 |
| Gemini CLI | `.gemini/settings.json` | JSON hooks 配置 |
| OpenCode | `.opencode/plugins/entire.ts` | TypeScript 插件 |
| Cursor | `.cursor/hooks.json` | JSON hooks 配置 |
| Copilot CLI | `.github/hooks/entire.json` | JSON hooks 配置 |
你可以同时启用多个 agent —— 每个 agent 的 hooks 是独立的。Entire 通过检查已安装的 hooks 来检测哪些 agent 处于活动状态，而不是通过 `settings.json` 中的设置。
### Checkpoint Remote
默认情况下，Entire 将 `entire/checkpoints/v1` 推送到与你的代码相同的 remote。如果你想将 checkpoint 数据推送到单独的仓库（例如公共项目的私有仓库），请使用结构化的 provider 和 repo 配置 `checkpoint_remote`：
```
{
"strategy_options": {
"checkpoint_remote": {
"provider": "github",
"repo": "myorg/checkpoints-private"
}
}
}
```
或通过 CLI：
```
entire enable --checkpoint-remote github:myorg/checkpoints-private
```
Entire 使用与你的 push remote 相同的协议（SSH 或 HTTPS）自动推导 git URL。它会：
- 如果 remote 上存在但本地不存在，则在本地获取 checkpoint 分支（一次性）
- 将 `entire/checkpoints/v1` 推送到 checkpoint 仓库，而不是你的默认 push remote
- 如果检测到 fork 则跳过推送（push remote 所有者与 checkpoint 仓库所有者不同）
- 如果 remote 无法访问，则发出警告并继续，不阻塞你的主推送
### 自动摘要
启用后，Entire 会在提交时自动为 checkpoint 生成 AI 摘要。摘要捕获会话中的意图、结果、学习点、摩擦点和待办事项。
```
{
"strategy_options": {
"summarize": {
"enabled": true
}
}
}
```
**要求：**
- 必须安装并认证 Claude CLI（PATH 中可用 `claude` 命令）
- 摘要生成是非阻塞的：失败会被记录但不会阻止提交
**注意：** 目前使用 Claude CLI 进行摘要生成。未来版本可能支持其他 AI 后端。
### 设置优先级
本地设置会逐字段覆盖项目设置。当你运行 `entire status` 时，它会显示项目和本地（有效）设置。
### Gemini CLI
Gemini CLI 支持目前处于预览阶段。Entire 可以将 [Gemini CLI](https://github.com/google-gemini/gemini-cli) 作为 Claude Code 的替代方案，或与其并存 —— 你可以同时启用多个 agent 的 hooks。
启用方式：
```
entire enable --agent gemini
```
所有命令（`rewind`、`status`、`doctor` 等）的工作方式相同，无论配置了哪个 agent。
如果你在使用 Gemini CLI 集成时遇到任何问题，请[提交 issue](https://github.com/entireio/cli/issues)。
### OpenCode
OpenCode 支持目前处于预览阶段。Entire 可以将 [OpenCode](https://opencode.ai/docs/cli/) 作为 Claude Code 的替代方案，或与其并存 —— 你可以同时启用多个 agent 的 hooks。
启用方式：
```
entire enable --agent opencode
```
或者在运行 `entire enable` 时从交互式 agent 选择器中选择 OpenCode。
所有命令（`rewind`、`status`、`doctor` 等）的工作方式相同，无论配置了哪个 agent。
如果你在使用 OpenCode 集成时遇到任何问题，请[提交 issue](https://github.com/entireio/cli/issues)。
### Cursor
Cursor 支持目前处于预览阶段。Entire 可以将 [Cursor](https://www.cursor.com/) 作为 Claude Code 的替代方案，或与其并存 —— 你可以同时启用多个 agent 的 hooks。
Entire 支持 Cursor IDE 和 Cursor Agent CLI 工具。
启用方式：
```
entire enable --agent cursor
```
或者在运行 `entire enable` 时从交互式 agent 选择器中选择 Cursor IDE。
目前暂不支持 Rewind，但其他命令（`doctor`、`status` 等）与其他 agent 相同。
如果你在使用 Cursor 集成时遇到任何问题，请[提交 issue](https://github.com/entireio/cli/issues)。
### Copilot CLI
GitHub Copilot CLI 支持目前处于预览阶段。Entire 可以将 [GitHub Copilot CLI](https://docs.github.com/en/copilot) 作为 Claude Code 的替代方案，或与其并存 —— 你可以同时启用多个 agent 的 hooks。
启用方式：
```
entire enable --agent copilot-cli
```
或者在运行 `entire enable` 时从交互式 agent 选择器中选择 Copilot CLI。
所有命令（`rewind`、`resume`、`status`、`doctor` 等）的工作方式相同，无论配置了哪个 agent。
如果你在使用 Copilot CLI 集成时遇到任何问题，请[提交 issue](https://github.com/entireio/cli/issues)。
## 安全与隐私
**你的会话转录存储在你的 git 仓库中**，位于 `entire/checkpoints/v1` 分支上。如果你的仓库是公开的，此数据对任何人可见。
Entire 在写入 `entire/checkpoints1` 时会自动修订检测到的秘密（API key、token、凭据），但修订是尽力而为的。会话期间使用的临时 shadow branch 可能包含未修订的数据，不应被推送。详情请参阅 [docs/security-and-privacy.md](docs/security-and-privacy.md)。
## 故障排除
### 常见问题
| 问题 | 解决方案 |
| ------------------------ | ------------------------------------------------------- |
| "Not a git repository" | 先导航到 Git 仓库 |
| "Entire is disabled" | 运行 `entire enable` |
| "No rewind points found" | 使用你配置的 agent 并提交你的更改 |
| "shadow branch conflict" | 运行 `entire reset --force` |
### SSH 认证错误
如果在运行 `entire resume` 时看到类似这样的错误：
```
Failed to fetch metadata: failed to fetch entire/checkpoints/v1 from origin: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain
```
这是 [go-git SSH 处理的已知问题](https://github.com/go-git/go-git/issues/411)。通过将 GitHub 的 host key 添加到你的 known_hosts 文件来修复：
```
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
ssh-keyscan -t ecdsa github.com >> ~/.ssh/known_hosts
```
### 调试模式
```
# 通过环境变量
ENTIRE_LOG_LEVEL=debug entire status
# 或通过 settings.local.json
{
"log_level": "debug"
}
```
### 重置状态
```
# 重置当前提交的 shadow branch
entire reset --force
# 禁用并重新启用
entire disable && entire enable --force
```
### 无障碍
对于屏幕阅读器用户，启用无障碍模式：
```
export ACCESSIBLE=1
entire enable
```
这会使用更简单的文本提示代替交互式 TUI 元素。
## 开发
本项目使用 [mise](https://mise.jdx.dev/) 进行任务自动化和依赖管理。
### 前置条件
- [mise](https://mise.jdx.dev/) - 使用 `curl https://mise.run | sh` 安装
### 入门
```
# 克隆仓库
git clone
cd cli
# 安装依赖（包括 Go）
mise install
# 信任 mise 配置（首次设置必需）
mise trust
# 构建 CLI
mise run build
```
### 常用任务
```
# 运行测试
mise run test
# 运行集成测试
mise run test:integration
# 运行所有测试（单元 + 集成，CI 模式）
mise run test:ci
# 对代码进行 Lint
mise run lint
# 格式化代码
mise run fmt
```
## 获取帮助
```
entire --help # General help
entire --help # Command-specific help
```
- **GitHub Issues:** 在 https://github.com/entireio/cli/issues 报告 bug 或请求功能
- **贡献:** 参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](LICENSE)。
标签：AI代理, AI编程, Claude, Copilot, Cursor, CVE检测, DLL 劫持, EVTX分析, Gemini, Git工作流, Golang, Homebrew, 人工智能安全, 代码上下文, 代码历史, 代码索引, 会话记录, 可追溯性, 合规性, 回滚恢复, 团队协作, 大语言模型, 安全可观测性, 安全编程, 开发者平台, 推理追踪, 提示词工程, 日志审计, 版本控制, 策略决策点, 网络调试, 自动化