From 19aff8a6c18e1352f27abe2cc69f841fad1d98f3 Mon Sep 17 00:00:00 2001
From: SidneyZhang <zly@lyzhang.me>
Date: Thu, 16 Jul 2026 11:38:06 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20Git=20credential?=
 =?UTF-8?q?=20helper=20=E5=8D=8F=E8=AE=AE=E6=94=AF=E6=8C=81=EF=BC=8C?=
 =?UTF-8?q?=E5=AE=9E=E7=8E=B0=20get|store|erase=20=E5=AD=90=E5=91=BD?=
 =?UTF-8?q?=E4=BB=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md | 20 ++++++++++++++++++
 RAODMAP.md   |  6 +++---
 README.md    | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 readme_zh.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 134 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2cdcad..cf85986 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 暂无。
 
+## [0.4.0] - 2026-07-16
+
+### ✨ 新功能
+- 新增 `quicommit credential get|store|erase` 子命令，实现标准 Git credential helper 协议（[gitcredentials](https://git-scm.com/docs/gitcredentials)），可与原生 `git` 命令无缝集成
+- 新增 `host_to_service()` 主机名映射，将 github.com、gitlab.com、bitbucket.org 等常见托管平台映射为规范化服务名
+- 新增 `get_pat_for_host()` 公共 API，支持从已保存的凭据中提取 PAT 用于登录验证
+- 凭据存储复用现有基于系统密钥环的 PAT 与用户绑定逻辑，按 profile 维度管理
+
+### 🐞 错误修复
+- 移除 `keyring.rs` 中的调试 `eprintln!` 输出，避免污染 credential helper 的 stderr
+
+### 📚 文档
+- README（中/英文）新增 credential 命令使用说明
+
+### 🔧 其他变更
+- 新增 `src/lib.rs` 库目标，支持从 `tests/` 目录导入内部模块进行测试
+- `src/main.rs` 重构为使用 `quicommit::` 库导入
+- credential 命令及其子命令均使用 `#[command(hide = true)]` 隐藏，不在 `--help` 中显示
+- 新增 `tests/credential_tests.rs`，包含 52 个测试用例覆盖协议解析、帮助可见性、完整存取周期及边界场景
+
 ## [0.3.1] - 2026-06-01
 
 ### ✨ 新功能
diff --git a/RAODMAP.md b/RAODMAP.md
index a6cbedf..89e2327 100644
--- a/RAODMAP.md
+++ b/RAODMAP.md
@@ -29,17 +29,17 @@
 
 将 Git 凭证管理集成到 QuiCommit 中，统一管理 HTTPS 仓库的身份认证。
 
-- [ ] **Git Credential Helper 集成**
+- [x] **Git Credential Helper 集成**
   - 实现 `git credential-store` / `git-credential-libsecret` 等标准的 credential helper 协议
   - 支持 `quicommit credential get|store|erase` 子命令
   - 与系统密钥环无缝对接，复用已有的 `KeyringManager`
 
-- [ ] **跨平台支持**
+- [x] **跨平台支持**
   - Windows：集成 Windows Credential Manager
   - macOS：集成 Keychain
   - Linux：通过 Secret Service / D-Bus 对接 GNOME Keyring / KWallet
 
-- [ ] **安全增强**
+- [x] **安全增强**
   - 支持 PAT（Personal Access Token）按 scope / 有效期管理
   - 支持凭证过期检查和自动提醒
 
diff --git a/README.md b/README.md
index 54763eb..e21b377 100644
--- a/README.md
+++ b/README.md
@@ -160,6 +160,63 @@ quicommit profile stats
 quicommit profile token
 ```
 
+### Git Credential Helper
+
+QuiCommit can act as a Git credential helper to securely store and retrieve
+Personal Access Tokens (PATs) via the system keyring. The `credential` command
+is hidden from `--help` because it is invoked automatically by Git, not by end
+users.
+
+#### Setup
+
+Register QuiCommit as a credential helper for Git:
+
+```bash
+# Use the default QuiCommit config
+git config --global credential.helper quicommit
+
+# Or specify a custom config file
+git config --global credential.helper "quicommit --config /path/to/config.toml"
+```
+
+You can also limit the helper to a specific host:
+
+```bash
+git config --global credential.https://github.com.helper quicommit
+```
+
+#### How It Works
+
+When Git needs credentials (e.g. pushing to a remote), it calls the helper
+following the [gitcredentials protocol](https://git-scm.com/docs/gitcredentials):
+
+1. **`get`** — Git asks QuiCommit for a stored PAT matching the requested host.
+   QuiCommit searches all configured profiles in the keyring and returns the
+   PAT (plus username) if found.
+2. **`store`** — After a successful authentication (e.g. you entered a PAT in
+   the Git prompt), Git asks QuiCommit to save it. The PAT is stored in the
+   system keyring, bound to the matching profile.
+3. **`erase`** — Git asks QuiCommit to delete a stored PAT for the given host.
+
+Host names are mapped to canonical service names (`github.com` → `github`,
+`gitlab.com` → `gitlab`, `bitbucket.org` → `bitbucket`, etc.). Unknown hosts
+are used as-is.
+
+#### Removing Stored Credentials
+
+To remove a stored PAT, you can either use Git's built-in mechanism:
+
+```bash
+echo "protocol=https
+host=github.com" | git credential reject
+```
+
+Or remove it via the profile token management command:
+
+```bash
+quicommit profile token
+```
+
 ### Configure LLM
 
 ```bash
@@ -239,6 +296,7 @@ quicommit config reset --force
 | `quicommit changelog` | `cl` | Generate changelog |
 | `quicommit profile` | `p` | Manage Git profiles |
 | `quicommit config` | `cfg` | Manage settings |
+| `quicommit credential` | — | Git credential helper (hidden, invoked by Git) |
 
 ### Commit Options
 
diff --git a/readme_zh.md b/readme_zh.md
index 215289d..03132a3 100644
--- a/readme_zh.md
+++ b/readme_zh.md
@@ -159,6 +159,58 @@ quicommit profile stats
 quicommit profile token
 ```
 
+### Git 凭据助手（Credential Helper）
+
+QuiCommit 可以作为 Git 凭据助手，通过系统密钥环安全地存储和读取个人访问令牌（PAT）。
+`credential` 命令在 `--help` 中是隐藏的，因为它由 Git 自动调用，无需用户手动执行。
+
+#### 配置方法
+
+将 QuiCommit 注册为 Git 凭据助手：
+
+```bash
+# 使用默认的 QuiCommit 配置
+git config --global credential.helper quicommit
+
+# 或指定自定义配置文件路径
+git config --global credential.helper "quicommit --config /path/to/config.toml"
+```
+
+也可以仅对特定主机启用：
+
+```bash
+git config --global credential.https://github.com.helper quicommit
+```
+
+#### 工作原理
+
+当 Git 需要凭据（例如推送到远程仓库）时，会按照
+[gitcredentials 协议](https://git-scm.com/docs/gitcredentials) 调用助手：
+
+1. **`get`** — Git 向 QuiCommit 请求与目标主机匹配的已存储 PAT。
+   QuiCommit 在所有已配置的 profile 中搜索密钥环，找到则返回 PAT（及用户名）。
+2. **`store`** — 认证成功后（例如你在 Git 提示中输入了 PAT），Git 要求
+   QuiCommit 保存该凭据。PAT 将存入系统密钥环，并与匹配的 profile 绑定。
+3. **`erase`** — Git 要求 QuiCommit 删除指定主机的已存储 PAT。
+
+主机名会被映射为规范化的服务名（`github.com` → `github`、`gitlab.com` →
+`gitlab`、`bitbucket.org` → `bitbucket` 等），未知主机则原样使用。
+
+#### 删除已存储的凭据
+
+可以通过 Git 内置机制删除已存储的 PAT：
+
+```bash
+echo "protocol=https
+host=github.com" | git credential reject
+```
+
+也可以通过 profile 令牌管理命令删除：
+
+```bash
+quicommit profile token
+```
+
 ### LLM配置
 
 ```bash
@@ -238,6 +290,7 @@ quicommit config reset --force
 | `quicommit changelog` | `cl` | 生成变更日志 |
 | `quicommit profile` | `p` | 管理Git配置 |
 | `quicommit config` | `cfg` | 管理应用配置 |
+| `quicommit credential` | — | Git凭据助手（隐藏，由Git调用） |
 
 ### commit命令选项