agent-better-checkpoint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Better Checkpoint — Semantic Git Commits for AI Sessions

Agent Better Checkpoint — AI会话的语义化Git提交

You are an AI coding assistant with checkpoint awareness. Every meaningful edit you make should be committed as a transparent Git checkpoint, so the user has a clear, operable history of all changes.

Core Principle: Replace opaque checkpoints with transparent Git commits. Every meaningful edit gets a semantic commit message that explains what changed and why.

你是一名具备checkpoint感知能力的AI编码助手。你所做的每一次有意义的编辑都应作为透明的Git checkpoint提交，这样用户就能拥有清晰、可操作的所有更改历史。

核心原则：用透明的Git提交替代不透明的检查点。每一次有意义的编辑都要有一条语义化的提交信息，说明更改了什么以及为什么更改。

🔧 Installation Check

🔧 安装检查

Before your first commit, verify the checkpoint scripts are installed:

macOS/Linux: Check if

~/.agent-better-checkpoint/scripts/checkpoint.sh

exists. Windows: Check if

$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1

exists.

If the scripts are not installed, run:

bash

npx @vibe-x/agent-better-checkpoint@0.1.0

This will install the checkpoint scripts and stop hook for your platform.

在首次提交前，请验证checkpoint脚本是否已安装：

macOS/Linux： 检查是否存在

~/.agent-better-checkpoint/scripts/checkpoint.sh

。 Windows： 检查是否存在

$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1

。

如果脚本未安装，请运行：

bash

npx @vibe-x/agent-better-checkpoint@0.1.0

这将为你的平台安装checkpoint脚本和停止钩子。

🔄 When to Commit

🔄 提交时机

MUST Commit After:

必须提交的场景：

Completing a logical unit of work (implementing a function, fixing a bug, adding a feature)
Making a significant refactor or restructuring
Adding or modifying configuration files
Creating or updating documentation
Before switching to a different task or file group
Before ending the conversation (the stop hook will remind you if you forget)

完成一个逻辑工作单元（实现一个函数、修复一个bug、添加一个功能）
进行重大重构或架构调整
添加或修改配置文件
创建或更新文档
切换到不同任务或文件组之前
结束对话之前（如果你忘记了，停止钩子会提醒你）

Do NOT Commit After:

无需提交的场景：

Trivial whitespace-only changes
Incomplete changes with syntax errors
Changes you're about to immediately undo

仅涉及空白字符的无关紧要更改
存在语法错误的未完成更改
即将立即撤销的更改

📝 Commit Message Format

📝 提交信息格式

Use Conventional Commits with

checkpoint

type:

checkpoint(<scope>): <short description>

<detailed description of changes, intent, and context>

使用带有

checkpoint

类型的Conventional Commits规范：

checkpoint(<scope>): <简短描述>

<更改的详细说明、意图和背景>

Rules:

规则：

Subject line:
```
checkpoint(<scope>): <description>
```
- ```
<scope>
```
  : affected area (e.g.,
```
auth
```
  ,
```
api
```
  ,
```
config
```
  ,
```
ui
```
  ,
```
docs
```
  )
- ```
<description>
```
  : imperative mood, lowercase, ≤72 chars
Body (after blank line): Explain what changed and why. Include context about intent.
Do NOT include trailers or metadata — the checkpoint script appends those automatically.

主题行：
```
checkpoint(<scope>): <描述>
```
- ```
<scope>
```
  ：受影响的区域（例如：
```
auth
```
  、
```
api
```
  、
```
config
```
  、
```
ui
```
  、
```
docs
```
  ）
- ```
<描述>
```
  ：使用祈使语气、小写、不超过72个字符
正文（空行之后）：解释更改的内容和原因，包括意图的背景信息
请勿添加trailer或元数据——checkpoint脚本会自动追加这些内容

Good Examples:

优秀示例：

checkpoint(api): add user registration endpoint

Implement POST /api/users with email/password validation.
Includes bcrypt hashing and duplicate email check.

checkpoint(config): enable TypeScript strict mode

Enable strict null checks and no-implicit-any rules.
Aligns with the team's TypeScript migration plan.

checkpoint(ui): fix responsive layout on mobile

Sidebar was overlapping main content on screens < 768px.
Switch to flex-column layout with collapsible sidebar.

checkpoint(api): add user registration endpoint

Implement POST /api/users with email/password validation.
Includes bcrypt hashing and duplicate email check.

checkpoint(config): enable TypeScript strict mode

Enable strict null checks and no-implicit-any rules.
Aligns with the team's TypeScript migration plan.

checkpoint(ui): fix responsive layout on mobile

Sidebar was overlapping main content on screens < 768px.
Switch to flex-column layout with collapsible sidebar.

🛠️ How to Commit

🛠️ 提交方法

Call the checkpoint script after composing your message. Determine the OS and use the appropriate command:

macOS/Linux:

bash

~/.agent-better-checkpoint/scripts/checkpoint.sh "<commit-message>" "<user-prompt>"

Windows (PowerShell):

powershell

powershell -File "$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1" "<commit-message>" "<user-prompt>"

编写完提交信息后，调用checkpoint脚本。根据操作系统选择相应的命令：

macOS/Linux：

bash

~/.agent-better-checkpoint/scripts/checkpoint.sh "<commit-message>" "<user-prompt>"

Windows (PowerShell)：

powershell

powershell -File "$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1" "<commit-message>" "<user-prompt>"

Parameters:

参数说明：

Parameter	Required	Description
message (1st arg)	Yes	Full commit message (subject + blank line + body)
user-prompt (2nd arg)	No	The user's original prompt/request
`--type` / `-Type`	No	`auto` (default) or `fallback`

参数	是否必填	描述
message（第一个参数）	是	完整的提交信息（主题 + 空行 + 正文）
user-prompt（第二个参数）	否	用户的原始提示/请求
`--type` / `-Type`	否	`auto` （默认）或 `fallback`

Example (macOS/Linux):

示例（macOS/Linux）：

bash

~/.agent-better-checkpoint/scripts/checkpoint.sh \
  "checkpoint(auth): add JWT token refresh logic

Implement automatic token refresh when access token expires.
Uses refresh token rotation for security." \
  "帮我实现 token 刷新机制"

bash

~/.agent-better-checkpoint/scripts/checkpoint.sh \
  "checkpoint(auth): add JWT token refresh logic

Implement automatic token refresh when access token expires.
Uses refresh token rotation for security." \
  "帮我实现 token 刷新机制"

Example (Windows):

示例（Windows）：

powershell

powershell -File "$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1" `
  "checkpoint(auth): add JWT token refresh logic`n`nImplement automatic token refresh when access token expires.`nUses refresh token rotation for security." `
  "帮我实现 token 刷新机制"

powershell

powershell -File "$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1" `
  "checkpoint(auth): add JWT token refresh logic`n`nImplement automatic token refresh when access token expires.`nUses refresh token rotation for security." `
  "帮我实现 token 刷新机制"

What the script does:

脚本功能：

Truncates user prompt to ≤60 characters (head...tail)
Appends Git Trailers:
```
Agent
```
,
```
Checkpoint-Type
```
,
```
User-Prompt
```
Runs
```
git add -A && git commit
```
Exits gracefully if there are no changes

将用户提示截断至≤60个字符（开头...结尾）
追加Git Trailers：
```
Agent
```
、
```
Checkpoint-Type
```
、
```
User-Prompt
```
执行
```
git add -A && git commit
```
如果没有更改则优雅退出

⚡ Workflow

⚡ 工作流程

1. User gives you a task
2. You make edits (code, config, docs, etc.)
3. When a logical unit is complete → compose checkpoint message → call script
4. Continue with next task → repeat step 2-3
5. Conversation ends → stop hook verifies nothing is left uncommitted

This should feel natural — commit as you go, like any good developer.

1. 用户给你分配任务
2. 你进行编辑（代码、配置、文档等）
3. 当一个逻辑单元完成后 → 编写checkpoint提交信息 → 调用脚本
4. 继续下一个任务 → 重复步骤2-3
5. 对话结束 → 停止钩子验证是否有未提交的更改

这应该成为自然的习惯——像优秀的开发者一样，边做边提交。

🚨 Important Rules

🚨 重要规则

One commit per logical change — don't batch unrelated changes into one commit
Always commit before ending — the stop hook catches missed commits, but proactive is better
Be descriptive — future humans (and AI) will read these messages
Don't force empty commits — the script handles "no changes" gracefully
Scope matters — choose a meaningful scope that helps categorize the change

Version: 0.1.0

每个逻辑更改对应一次提交——不要将无关更改批量提交到一个commit中
结束对话前务必提交——停止钩子会捕获遗漏的提交，但主动提交更好
提交信息要描述清晰——未来的人类（和AI）会阅读这些信息
不要强制提交空commit——脚本会妥善处理“无更改”的情况
scope很重要——选择有意义的scope来帮助分类更改

版本：0.1.0