chore(release): 发布 0.9.0 版本并更新路线图

docs/configuration-guide.md

@@ -0,0 +1,693 @@
+# QuiCommit 配置指南
+
+[English](configuration-guide.en.md) | 简体中文
+
+本指南面向希望完整掌握 QuiCommit 配置的读者，覆盖：
+
+- **快速设置**：三分钟跑通「建仓库 → 配 LLM → 第一次提交」
+- **分类详细设置**：逐项说明配置文件里每个字段的含义、取值与默认值
+- **命令参考**：`config` / `profile` 子命令全表
+- **环境变量与全局选项**
+- **常见场景配方**与**故障排除**
+
+> 想先看功能全貌，请阅读 [README](../README.md)（中文版 [readme_zh.md](../readme_zh.md)）。
+> 配置术语（Repo init、Config init、Initial branch 等）的定义见 [CONTEXT.md](../CONTEXT.md)。
+
+---
+
+## 目录
+
+1. [快速设置](#1-快速设置)
+2. [配置文件位置与优先级](#2-配置文件位置与优先级)
+3. [分类详细设置](#3-分类详细设置)
+   - [3.1 应用元信息（version / default_profile）](#31-应用元信息version--default_profile)
+   - [3.2 LLM 与 AI 生成（`[llm]`）](#32-llm-与-ai-生成llm)
+   - [3.3 Git 身份配置（`[profiles.*]`）](#33-git-身份配置profiles)
+   - [3.4 仓库到身份映射（`[repo_profiles]`）](#34-仓库到身份映射repo_profiles)
+   - [3.5 提交配置（`[commit]`）](#35-提交配置commit)
+   - [3.6 标签配置（`[tag]`）](#36-标签配置tag)
+   - [3.7 变更日志配置（`[changelog]`）](#37-变更日志配置changelog)
+   - [3.8 语言配置（`[language]`）](#38-语言配置language)
+   - [3.9 输出配置（`[output]`）](#39-输出配置output)
+4. [配置命令参考（`quicommit config`）](#4-配置命令参考quicommit-config)
+5. [身份配置命令参考（`quicommit profile`）](#5-身份配置命令参考quicommit-profile)
+6. [令牌与凭据](#6-令牌与凭据)
+7. [环境变量](#7-环境变量)
+8. [全局选项](#8-全局选项)
+9. [完整配置示例](#9-完整配置示例)
+10. [常见场景配方](#10-常见场景配方)
+11. [故障排除](#11-故障排除)
+
+---
+
+## 1. 快速设置
+
+### 前置条件
+
+| 依赖 | 说明 |
+| --- | --- |
+| Git | 任意版本均可（仓库初始化走 libgit2，不依赖 `git init -b`） |
+| Rust / 已安装的 `quicommit` | 见 [README 安装章节](../README.md#installation) |
+| 系统密钥环（推荐） | Windows 凭据管理器 / macOS Keychain / Linux Secret Service。用于安全存放 API Key 与 PAT。用 `quicommit config check-keyring` 检查 |
+
+### 路线 A：交互式向导（推荐首次使用）
+
+```bash
+quicommit init
+```
+
+向导依次询问：输出语言 → 第一个 Git Profile（名称 / 用户名 / 邮箱 / 描述 / 是否工作身份）→ 可选 SSH → 可选 GPG → LLM provider → 模型 → API Key（隐藏输入，存入密钥环）。这与 CONTEXT.md 所说的 **Config init** 对应——只创建 QuiCommit 自己的配置文件，不碰 Git 仓库。
+
+跳过所有提问、使用本机 Git 身份生成一份最小配置：
+
+```bash
+quicommit init --yes
+```
+
+### 路线 B：仓库起步 + 手动配 LLM
+
+```bash
+# ① 把当前目录变成 Git 仓库（建库、写 README、生成 .gitignore、定初始分支）
+quicommit ginit
+
+# ② 选择 LLM provider（无参数时进入交互选择）
+quicommit config set-llm deepseek
+
+# ③ 设置 API Key（省略值可隐藏输入；已带值时注意 shell 历史泄露）
+quicommit config set-api-key
+
+# ④ 验证连通性
+quicommit config test-llm
+
+# ⑤ 第一次提交
+quicommit commit
+```
+
+### 验证当前配置
+
+```bash
+quicommit config show          # 汇总展示所有生效配置
+quicommit config path          # 打印配置文件路径
+quicommit config get llm.provider
+quicommit config check-keyring # 检查密钥环与相关环境变量
+```
+
+---
+
+## 2. 配置文件位置与优先级
+
+配置文件是单个 TOML 文件，默认位置由操作系统的配置目录决定：
+
+| 平台 | 默认路径 |
+| --- | --- |
+| Linux | `~/.config/quicommit/config.toml` |
+| macOS | `~/Library/Application Support/quicommit/config.toml` |
+| Windows | `%APPDATA%\quicommit\config.toml` |
+
+### 指定自定义路径
+
+优先级（从高到低）：
+
+1. 命令行全局选项 `-c` / `--config <PATH>`
+2. 环境变量 `QUICOMMIT_CONFIG`
+3. 上述平台默认路径
+
+```bash
+quicommit -c ./my-config.toml config show
+# 或
+QUICOMMIT_CONFIG=./my-config.toml quicommit config show
+```
+
+> 该路径会被所有子命令共享（`commit`、`tag`、`changelog`、`profile`、`ginit` 等）。
+> 用自定义路径时，密钥环条目仍按 provider / profile 维度存取，与配置文件路径无关。
+
+### 配置来源优先级汇总
+
+| 配置项 | 优先级（高 → 低） |
+| --- | --- |
+| 配置文件路径 | `-c/--config` > `QUICOMMIT_CONFIG` > 平台默认 |
+| API Key | 环境变量（`QUICOMMIT_API_KEY`，进程内始终优先） > 密钥环（默认存储方式） > 配置文件内 `llm.api_key`（仅当 `api_key_storage = "config"`） |
+| Emoji 装饰 | `--no-color`（关闭） > `--no-emoji` / `--emoji` > 配置 `output.emoji` > 默认开启 |
+| 日志级别 | `RUST_LOG` > `-v` 次数 |
+| Initial branch（`ginit`） | `-b/--branch` > 全局 `init.defaultBranch` > `main` |
+
+---
+
+## 3. 分类详细设置
+
+下面按配置文件的顶层表（table）逐项说明。每个字段都给出 **键名 / 类型 / 默认值**。
+
+### 3.1 应用元信息（version / default_profile）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `version` | string | `"1"` | 配置结构版本，用于未来迁移，一般不手动改动 |
+| `default_profile` | string（可省略） | 无 | 默认 Git 身份名。`profile apply` 不带参数、`profile show` 不带参数时使用它 |
+
+### 3.2 LLM 与 AI 生成（`[llm]`）
+
+QuiCommit 通过 [rig-core](https://github.com/0xPlaygrounds/rig) 统一对接六家 provider：`ollama`、`openai`、`anthropic`、`kimi`、`deepseek`、`openrouter`。
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `provider` | string | `"ollama"` | provider 名称，见下表 |
+| `model` | string | `"llama2"` | 模型名。切换 provider 时若当前模型为空或仍是 `llama2`，会自动替换为该 provider 的默认模型 |
+| `base_url` | string（可省略） | 无（用 provider 默认） | 自定义 API 地址，用于代理、私有部署或国内镜像 |
+| `max_tokens` | 整数 | `500` | 单次生成的最大输出 token 数 |
+| `temperature` | 浮点 | `0.6` | 采样温度。部分 provider 会覆盖它（见「温度与思考模式」） |
+| `timeout` | 整数（秒） | `30` | HTTP 请求超时 |
+| `api_key_storage` | string | `"keyring"` | API Key 存储方式：`keyring` / `config` / `environment` |
+| `api_key` | string（可省略） | 无 | 仅当 `api_key_storage = "config"` 时生效，明文存于配置文件 |
+| `thinking_enabled` | 布尔 | `false` | 默认是否启用思考/推理模式（`commit`/`tag`/`changelog` 的 `--think` 可临时覆盖） |
+| `thinking_budget_tokens` | 整数（可省略） | 无（运行期按 `1024` 处理） | 仅 Anthropic 使用：思考预算 token |
+
+#### Provider 默认值速查
+
+| provider | 默认 `base_url` | 默认 `model` | 是否需要 API Key |
+| --- | --- | --- | --- |
+| `ollama` | `http://localhost:11434` | `llama2` | 否 |
+| `openai` | `https://api.openai.com/v1` | `gpt-4` | 是 |
+| `anthropic` | `https://api.anthropic.com/v1` | `claude-3-sonnet-20240229` | 是 |
+| `kimi` | `https://api.moonshot.cn/v1` | `kimi-k2.6` | 是 |
+| `deepseek` | `https://api.deepseek.com` | `deepseek-v4-flash` | 是 |
+| `openrouter` | `https://openrouter.ai/api/v1` | `openai/gpt-3.5-turbo` | 是 |
+
+> `quicommit config list-models` 会按当前 provider 打印一批示例模型名（Ollama 会尝试直接调用本机 `ollama list`）。
+
+#### API Key 的三种存储方式
+
+- `keyring`（默认，推荐）：存入系统密钥环，`config.toml` 中不出现明文。密钥环不可用时 `set-api-key` 会报错并提示改用环境变量或 `config`。
+- `config`：明文写入 `config.toml` 的 `llm.api_key`。方便但不安全，`set-api-key` 会给出明文告警。
+- `environment`：不存储，要求你自行设置环境变量。
+
+设置与删除：
+
+```bash
+# 方式一：交互式选择 provider / 模型 / base_url / API Key
+quicommit config set-llm deepseek
+
+# 方式二：非交互，直接给出参数（--api-key 会进入 shell 历史，建议仅用于 CI）
+quicommit config set-llm openai --model gpt-4o --base-url https://api.openai.com/v1
+
+# 单独设置/删除 API Key（省略值则隐藏输入）
+quicommit config set-api-key
+quicommit config delete-api-key
+```
+
+#### 温度与思考模式
+
+`--think`（或配置 `thinking_enabled = true`）只在 `deepseek`、`kimi`、`anthropic`、`openai` 上生效；其余 provider 会自动降级为普通生成。各 provider 的参数处理如下：
+
+| provider | 普通模式 | 思考模式 |
+| --- | --- | --- |
+| `ollama` | 使用 `temperature` / `max_tokens` | 不支持，降级 |
+| `deepseek` | 使用 `temperature`；显式传 `thinking: disabled` | 省略 temperature，走流式 |
+| `kimi` | 强制 `temperature = 0.6`（忽略配置） | 强制 `temperature = 1.0`，走流式 |
+| `anthropic` | 使用 `temperature` | 省略 temperature；`max_tokens` 提升到至少 `thinking_budget_tokens + 100`，预算缺省 `1024`；走流式 |
+| `openai` | 使用 `temperature`；`o*` 系列模型显式关闭推理 | 省略 temperature，走流式 |
+| `openrouter` | 使用 `temperature` / `max_tokens` | 不支持，降级 |
+
+> 命令层开关：`commit --think`、`tag --think`、`changelog --think`。
+
+### 3.3 Git 身份配置（`[profiles.*]`）
+
+每个 profile 是一组可独立启用的 Git 身份 + 认证设置。用 `quicommit profile add`（交互式）创建，或直接编辑配置文件。
+
+顶层字段：
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | 无 | profile 名，须与 TOML 表名一致。只允许字母、数字、`-`、`_`，最长 50 字符 |
+| `user_name` | string | 无 | 写入 `user.name` |
+| `user_email` | string | 无 | 写入 `user.email`，须符合邮箱格式 |
+| `description` | string（可省略） | 无 | 备注 |
+| `is_work` | 布尔 | `false` | 是否工作身份（仅作展示/筛选标记） |
+| `organization` | string（可省略） | 无 | 组织名（`is_work = true` 时有意义） |
+| `signing_key` | string（可省略） | 无 | 直接指定签名 key；未设置时回退到 `gpg.key_id` |
+
+#### `[profiles.<name>.settings]` — 行为偏好
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `auto_sign_commits` | 布尔 | `false` | 应用该 profile 时是否写入 `commit.gpgsign = true` |
+| `auto_sign_tags` | 布尔 | `false` | 应用该 profile 时是否写入 `tag.gpgsign = true` |
+| `default_commit_format` | string（可省略） | 无 | 该 profile 偏好的提交格式：`conventional` / `commitlint` |
+| `repo_patterns` | 字符串数组 | `[]` | 用于把仓库路径匹配到该 profile 的路径片段 |
+| `llm_provider` | string（可省略） | 无 | 该 profile 偏好的 LLM provider（元数据，供未来使用） |
+| `commit_template` | string（可省略） | 无 | 自定义提交信息模板 |
+
+#### `[profiles.<name>.ssh]` — SSH 配置（可选）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `private_key_path` | 路径（可省略） | 无 | SSH 私钥路径（校验存在性） |
+| `public_key_path` | 路径（可省略） | 无 | 公钥路径；未设置时按私钥推导 `<key>.pub` |
+| `passphrase` | string（可省略） | 无 | 私钥口令（加密存储） |
+| `agent_forwarding` | 布尔 | `false` | 是否加 `-A` |
+| `ssh_command` | string（可省略） | 无 | 完全自定义的 SSH 命令；设置后覆盖其他字段 |
+| `known_hosts_file` | 路径（可省略） | 无 | 追加 `-o UserKnownHostsFile=<path>` |
+
+应用时写入 Git 本地配置 `core.sshCommand`。命令拼接规则：`ssh` +（`-A`）+（`-i <私钥>`）+（`-o UserKnownHostsFile=<文件>`）；若 `ssh_command` 有值则直接使用它。
+
+#### `[profiles.<name>.gpg]` — GPG 配置（可选）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `key_id` | string | 无 | GPG Key ID，须为 16–40 位十六进制大写字符 |
+| `program` | string | Windows：`gpg.exe`；其他：`gpg` | 写入 `gpg.program` |
+| `home_dir` | 路径（可省略） | 无 | GPG home 目录 |
+| `passphrase` | string（可省略） | 无 | 口令（加密存储） |
+| `use_agent` | 布尔 | `true` | 是否使用 gpg-agent |
+
+应用时写入 Git 本地配置 `gpg.program`、`user.signingkey`，并按 `settings.auto_sign_commits` / `auto_sign_tags` 写入 `commit.gpgsign` / `tag.gpgsign`。
+
+#### 应用（写出到 Git）与展示
+
+`profile apply` / `profile set-repo` / `profile switch` 会把 profile 写入 Git 配置：
+
+- 仓库级：`user.name`、`user.email`，以及上面提到的 SSH / GPG 相关键
+- 全局（`profile apply --global`）：写入全局 Git 配置
+
+> 应用 profile 时会先清理「新 profile 不再设置」的受管键（`core.sshCommand`、`user.signingkey`、`commit.gpgsign`、`tag.gpgsign`、`gpg.program`），避免残留旧身份。
+
+### 3.4 仓库到身份映射（`[repo_profiles]`）
+
+把「仓库绝对路径 → profile 名」记录下来，供 `profile show` 等命令识别当前仓库应使用哪个身份。由 `profile set-repo` 或 `ginit --profile` 自动写入，一般无需手改。
+
+```toml
+[repo_profiles]
+"/home/me/work/project" = "work"
+"/home/me/personal/project" = "personal"
+```
+
+### 3.5 提交配置（`[commit]`）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `format` | string | `"conventional"` | 提交格式：`conventional` 或 `commitlint` |
+| `auto_generate` | 布尔 | `true` | 是否默认用 AI 生成提交信息（`commit --manual` 可临时关闭） |
+
+格式差异（见 [validators.rs](../src/utils/validators.rs)）：
+
+- `conventional`：`<type>[scope][!]: <description>`，type 取自 11 种（feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert）。
+- `commitlint`：在 conventional 基础上扩展 type（额外支持 wip、init、update、remove、security），并额外校验主题不以大写字母开头、不以句点结尾。
+
+```bash
+quicommit config set commit.format conventional
+quicommit config set-commit-format commitlint
+quicommit config set commit.auto_generate false
+```
+
+### 3.6 标签配置（`[tag]`）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `version_prefix` | string | `"v"` | tag 版本前缀，如 `v1.2.3` |
+| `auto_generate` | 布尔 | `true` | 是否默认用 AI 生成 tag message |
+
+```bash
+quicommit config set tag.version_prefix v
+quicommit config set-version-prefix v
+```
+
+### 3.7 变更日志配置（`[changelog]`）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `path` | string | `"CHANGELOG.md"` | 变更日志文件路径 |
+| `auto_generate` | 布尔 | `true` | 是否默认用 AI 生成变更日志（`--no-generate` 可临时关闭，改用模版） |
+
+```bash
+quicommit config set changelog.path CHANGELOG.md
+quicommit config set-changelog-path CHANGELOG.md
+```
+
+### 3.8 语言配置（`[language]`）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `output_language` | string | `"en"` | 界面/生成文案语言 |
+| `keep_types_english` | 布尔 | `true` | 提交类型（feat、fix…）是否保持英文 |
+| `keep_changelog_types_english` | 布尔 | `true` | 变更日志分类（Added、Fixed…）是否保持英文 |
+
+支持的语言代码：`en`、`zh`（含 `zh-cn` / `zh-tw`）、`ja`、`ko`、`es`、`fr`、`de`（也接受 `english`、`chinese` 等全称）。无效代码会静默回退为英文。
+
+```bash
+quicommit config set-language zh          # 省略参数则交互式选择
+quicommit config set language.output_language zh
+quicommit config set-keep-types-english true
+quicommit config set-keep-changelog-types-english true
+```
+
+### 3.9 输出配置（`[output]`）
+
+| 键 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `emoji` | 布尔 | `true` | 是否显示 ✓ / ✗ / ⚠ / → 等装饰符号 |
+
+```bash
+quicommit config set output.emoji false
+```
+
+命令行覆盖：`--no-color` 会同时关闭颜色与装饰；`--emoji` / `--no-emoji` 单独控制装饰。
+
+---
+
+## 4. 配置命令参考（`quicommit config`）
+
+别名：`quicommit cfg`。不带子命令时等价于 `config show`。
+
+| 子命令 | 说明 |
+| --- | --- |
+| `config show` | 汇总展示当前配置（通用 / LLM / 提交 / 标签 / 语言 / 变更日志 / 安全） |
+| `config path` | 打印配置文件路径 |
+| `config edit` | 用 `$EDITOR`（或 `$VISUAL`）打开配置文件 |
+| `config get <key>` | 读取单个配置项 |
+| `config set <key> <value>` | 写入单个配置项（见下方键表） |
+| `config set-llm [provider]` | 交互式配置 LLM；可带 `--model` / `--base-url` / `--api-key` |
+| `config set-api-key [key]` | 设置当前 provider 的 API Key（省略则隐藏输入） |
+| `config delete-api-key` | 从当前存储方式中删除 API Key |
+| `config set-commit-format <fmt>` | 设置 `conventional` / `commitlint` |
+| `config set-version-prefix <prefix>` | 设置 tag 版本前缀 |
+| `config set-changelog-path <path>` | 设置变更日志路径 |
+| `config set-language [code]` | 设置输出语言（省略则交互式选择） |
+| `config set-keep-types-english <bool>` | 提交类型是否保持英文 |
+| `config set-keep-changelog-types-english <bool>` | 变更日志分类是否保持英文 |
+| `config list-models` | 按当前 provider 列出示例/已安装模型 |
+| `config test-llm` | 发送一次测试请求，验证 provider 连通性 |
+| `config check-keyring` | 检查密钥环可用性与相关环境变量 |
+| `config export -o <file> [--password]` | 导出配置（可选加密） |
+| `config import -i <file> [--password]` | 导入配置 |
+| `config reset [--force]` | 重置为默认配置 |
+
+### `config set` / `config get` 支持的键
+
+| 键 | 取值 |
+| --- | --- |
+| `llm.provider` | `ollama` / `openai` / `anthropic` / `kimi` / `deepseek` / `openrouter` |
+| `llm.model` | 任意模型名 |
+| `llm.base_url` | URL |
+| `llm.max_tokens` | 整数 |
+| `llm.temperature` | 浮点 |
+| `llm.timeout` | 整数（秒） |
+| `llm.thinking_enabled` | `true` / `false` |
+| `llm.thinking_budget_tokens` | 整数 |
+| `llm.api_key_storage` | `keyring` / `config` / `environment` |
+| `commit.format` | `conventional` / `commitlint` |
+| `commit.auto_generate` | `true` / `false` |
+| `tag.version_prefix` | 字符串 |
+| `tag.auto_generate` | `true` / `false` |
+| `changelog.path` | 路径字符串 |
+| `changelog.auto_generate` | `true` / `false` |
+| `language.output_language` | 语言代码 |
+| `language.keep_types_english` | `true` / `false` |
+| `language.keep_changelog_types_english` | `true` / `false` |
+| `output.emoji` | `true` / `false` |
+
+> `config set` 只接受上表键名，其他键会报「未知配置键」。
+> **API Key 不在其中**——请用 `config set-api-key` / `config delete-api-key`。
+> 布尔键只接受字面 `true` / `false`。
+
+---
+
+## 5. 身份配置命令参考（`quicommit profile`）
+
+别名：`quicommit p`。不带子命令时等价于 `profile list`。
+
+| 子命令 | 说明 |
+| --- | --- |
+| `profile add` | 交互式新建 profile（名称 / 用户名 / 邮箱 / 描述 / 工作标记 / SSH / GPG / 令牌） |
+| `profile list` | 列出所有 profile（默认项标 `●`） |
+| `profile show [name]` | 展示当前仓库 Git 配置、匹配到的 profile 及详情 |
+| `profile edit <name>` | 交互式编辑，含 SSH / GPG / 签名偏好 / 令牌子菜单 |
+| `profile copy <from> <to>` | 复制 profile（不复制使用统计） |
+| `profile remove <name>` | 删除 profile（同时清理其密钥环 PAT） |
+| `profile set-default <name>` | 设置默认 profile |
+| `profile set-repo <name>` | 为当前仓库记录映射并立即应用 |
+| `profile switch` | 交互式切换默认 profile，可选是否应用到当前仓库 |
+| `profile apply [name] [--global]` | 把 profile（默认取 default）应用到当前仓库或全局 Git 配置 |
+| `profile check [name]` | 对比 profile 与当前仓库 Git 配置的差异 |
+| `profile stats [name]` | 查看使用统计 |
+| `profile token add <profile> <service>` | 添加服务令牌（存入密钥环） |
+| `profile token remove <profile> <service>` | 移除服务令牌 |
+| `profile token list <profile>` | 列出令牌及其存储状态 |
+
+---
+
+## 6. 令牌与凭据
+
+### PAT（Personal Access Token）
+
+PAT 用于把私有仓库推送到 GitHub / GitLab 等平台，按 **profile + 服务名** 维度存入系统密钥环（`config.toml` 中只记录元信息如类型、描述、是否已存储）。
+
+```bash
+quicommit profile token add personal github
+quicommit profile token list personal
+quicommit profile token remove personal github
+```
+
+服务名可自由填写（`github`、`gitlab`、`bitbucket` 等）。
+
+### Git Credential Helper
+
+QuiCommit 可作为 Git 凭据助手，注册后 Git 推送时会自动向它索取 PAT：
+
+```bash
+git config --global credential.helper quicommit
+# 或限定主机
+
+git config --global credential.https://github.com.helper quicommit
+```
+
+`credential get|store|erase` 由 Git 自动调用，命令隐藏在 `--help` 之外。删除已存凭据：
+
+```bash
+echo "protocol=https
+host=github.com" | git credential reject
+```
+
+### 导入导出与备份
+
+```bash
+# 明文导出（不含密钥环中的 PAT）
+quicommit config export -o config-backup.toml
+
+# 加密导出（把 profile 的 PAT 一并加密打包）
+quicommit config export -o config-backup.enc --password
+
+# 导入
+quicommit config import -i config-backup.toml
+quicommit config import -i config-backup.enc --password
+```
+
+> 加密导出使用 AES-GCM + Argon2；导出文件以 `ENCRYPTED:` 前缀标识。若目标配置含有 PAT 却未启用加密，导入/导出会给出明文告警。
+
+---
+
+## 7. 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `QUICOMMIT_CONFIG` | 配置文件路径（等价于 `-c/--config`） |
+| `QUICOMMIT_API_KEY` | 任意 provider 的 API Key，**进程内始终优先**于密钥环与配置文件 |
+| `QUICOMMIT_<PROVIDER>_API_KEY` | provider 专属 API Key（如 `QUICOMMIT_OPENAI_API_KEY`）。交互式 `init` 会检测它，`config check-keyring` 会展示它 |
+| `EDITOR` / `VISUAL` | `config edit` 使用的编辑器（`EDITOR` 优先） |
+| `NO_COLOR` | 设置任意值即关闭彩色与 Emoji 装饰 |
+| `RUST_LOG` | 覆盖 `-v` 的日志过滤，如 `RUST_LOG=debug` |
+
+> 注意：真正参与生成请求的 Key 解析路径是 `QUICOMMIT_API_KEY` → 密钥环 →（`api_key_storage = "config"` 时）配置文件。
+> provider 专属的 `QUICOMMIT_<PROVIDER>_API_KEY` 目前仅用于 `init` 的检测与 `config check-keyring` 的展示；若要让它生效参与生成，请改设 `QUICOMMIT_API_KEY`。
+
+---
+
+## 8. 全局选项
+
+所有子命令共享以下全局选项：
+
+| 选项 | 说明 |
+| --- | --- |
+| `-v, --verbose`（可叠加） | `-v` info、`-vv` debug、`-vvv` trace |
+| `-c, --config <PATH>` | 配置文件路径 |
+| `--no-color` | 关闭颜色**与** Emoji 装饰（最高优先级） |
+| `--emoji` / `--no-emoji` | 强制开启/关闭 Emoji 装饰，覆盖 `output.emoji` |
+
+---
+
+## 9. 完整配置示例
+
+```toml
+version = "1"
+default_profile = "personal"
+
+# ── LLM ─────────────────────────────────────────────────────────────
+[llm]
+provider = "deepseek"
+model = "deepseek-v4-flash"
+# base_url = "https://api.deepseek.com"   # 省略则用 provider 默认
+max_tokens = 500
+temperature = 0.6
+timeout = 30
+api_key_storage = "keyring"
+thinking_enabled = false
+# thinking_budget_tokens = 1024           # 仅 Anthropic 使用
+
+# ── 提交 / 标签 / 变更日志 ──────────────────────────────────────────
+[commit]
+format = "conventional"
+auto_generate = true
+
+[tag]
+version_prefix = "v"
+auto_generate = true
+
+[changelog]
+path = "CHANGELOG.md"
+auto_generate = true
+
+# ── 语言与输出 ──────────────────────────────────────────────────────
+[language]
+output_language = "zh"
+keep_types_english = true
+keep_changelog_types_english = true
+
+[output]
+emoji = true
+
+# ── 个人身份 ────────────────────────────────────────────────────────
+[profiles.personal]
+name = "personal"
+user_name = "Your Name"
+user_email = "you@example.com"
+description = "个人项目"
+is_work = false
+
+[profiles.personal.settings]
+auto_sign_commits = false
+auto_sign_tags = false
+repo_patterns = []
+
+# ── 工作身份（含 SSH + GPG） ───────────────────────────────────────
+[profiles.work]
+name = "work"
+user_name = "Your Name"
+user_email = "you@company.com"
+description = "工作项目"
+is_work = true
+organization = "Your Company"
+
+[profiles.work.settings]
+auto_sign_commits = true
+auto_sign_tags = true
+default_commit_format = "conventional"
+repo_patterns = ["/work/"]
+
+[profiles.work.ssh]
+private_key_path = "/home/user/.ssh/id_ed25519_work"
+agent_forwarding = true
+
+[profiles.work.gpg]
+key_id = "0123456789ABCDEF"
+program = "gpg"
+use_agent = true
+
+# ── 仓库 → 身份映射 ────────────────────────────────────────────────
+[repo_profiles]
+"/home/user/work/project" = "work"
+"/home/user/personal/project" = "personal"
+```
+
+---
+
+## 10. 常见场景配方
+
+### 用本地 Ollama（无需 API Key）
+
+```bash
+quicommit config set-llm ollama --base-url http://localhost:11434 --model llama2
+quicommit config test-llm
+```
+
+### 用 DeepSeek
+
+```bash
+quicommit config set-llm deepseek --model deepseek-v4-flash
+quicommit config set-api-key          # 隐藏输入
+# 或一次性：quicommit config set-llm deepseek --api-key <KEY>
+```
+
+### 工作 / 个人双身份
+
+```bash
+quicommit profile add                 # 建 personal
+quicommit profile add                 # 再建 work（可配 SSH/GPG）
+quicommit profile set-default personal
+
+cd ~/work/project
+quicommit profile set-repo work       # 记录映射并立即应用到本仓库
+quicommit profile check work          # 校验是否与仓库 Git 配置一致
+```
+
+### 在 CI 中使用（无密钥环）
+
+```bash
+export QUICOMMIT_API_KEY=<KEY>        # 环境变量始终优先
+export QUICOMMIT_CONFIG=./ci-config.toml
+quicommit commit --yes
+```
+
+### 启用思考模式
+
+```bash
+# 仅本次提交
+quicommit commit --think
+
+# 全局默认开启（对 deepseek/kimi/anthropic/openai 生效）
+quicommit config set llm.thinking_enabled true
+```
+
+### Linux 无桌面环境（无 Secret Service）
+
+```bash
+# 方案一：改用环境变量
+export QUICOMMIT_API_KEY=<KEY>
+
+# 方案二：改存配置文件（明文，注意权限）
+quicommit config set llm.api_key_storage config
+quicommit config set-api-key
+```
+
+---
+
+## 11. 故障排除
+
+### 配置损坏或旧版本不兼容
+
+```bash
+quicommit config reset --force        # 重置为默认
+quicommit init                        # 重新配置
+```
+
+### API Key 相关报错
+
+```bash
+quicommit config check-keyring        # 确认密钥环是否可用、环境变量是否被识别
+quicommit config show                 # 确认 provider 与 Key 掩码状态
+quicommit config test-llm             # 端到端连通性
+```
+
+- 「keyring is not available」：系统无 Secret Service（常见于无桌面的 Linux）。改用环境变量或 `api_key_storage = config`。
+- 「API key not configured」：`set-api-key` 未生效或环境变量未设置。
+- provider 报「not available」：多为 `base_url` 或凭据问题。DeepSeek 的默认地址是 `https://api.deepseek.com`（**不带** `/v1`）；若历史配置里显式写过 `/v1` 导致校验失败，请重新执行 `quicommit config set-llm deepseek`。
+
+### 改了配置但行为没变
+
+- 确认改的是生效的配置文件：`quicommit config path`（注意 `-c` / `QUICOMMIT_CONFIG` 可能改变了路径）。
+- 检查全局选项是否覆盖了配置：`--emoji`、`--no-emoji`、`--think`。
+- 检查环境变量优先级：`QUICOMMIT_API_KEY`、`RUST_LOG`。
+
+### 打开配置文件
+
+```bash
+quicommit config edit                 # 使用 $EDITOR / $VISUAL
+quicommit config show                 # 只读查看
+```