QuiCommit/RAODMAP.md

# QuiCommit Roadmap

> 本路线图按「已完成 / 进行中 / 计划中 / 长远规划」四档跟踪功能演进，并为"计划中"条目标注优先级（P0 = 核心必做，P1 = 重要增强，P2 = 探索性方向）。
> 更新约定：条目完成后请及时勾选并移入"已完成"，避免已完成事项长期滞留在"计划中"栏目；新增条目请附带动机说明与优先级。

## 已完成 ✅

- [x] 基础 Git 操作（commit、tag、changelog）
- [x] AI 驱动提交信息生成（Conventional Commits / commitlint 格式）
- [x] 多 LLM 提供商支持：Ollama、OpenAI、Anthropic、Kimi、DeepSeek、OpenRouter
- [x] 多 Git Profile 管理（SSH 密钥 + GPG 签名）
- [x] 语义化版本自动升级与 AI 发布说明
- [x] Keep a Changelog 格式自动生成
- [x] 系统密钥环安全存储 API Key
- [x] 敏感数据加密存储（AES-GCM + Argon2）
- [x] 交互式 CLI 预览与确认
- [x] 7 种语言国际化支持
- [x] 配置导出/导入（支持加密保护）
- [x] Profile Token 管理（PAT 等）
- [x] Git 凭证管理器（Credential Helper 协议、Windows/macOS/Linux 跨平台密钥环对接、PAT scope/有效期与过期提醒）
- [x] DeepSeek 最新模型支持（`deepseek-chat` / `deepseek-reasoner` / `deepseek-v4`）
- [x] 流式生成的 SSE（Server-Sent Events）基础接入

---

## 进行中 🚧

- **`quicommit ginit`**（下方计划中条目 #1）：规格与取舍已定稿于 `.scratch/ginit/spec.md`，并记录 ADR 0005（`init` 与 `ginit` 并存）与 ADR 0006（ginit 的产出边界）；代码已落到 `main`，随下一个版本发布后移入「已完成」。

---

## 计划中 📋

### 1. `quicommit ginit`：一键初始化本地 Git 仓库 `P0`（🚧 规格已定稿）

**动机**：目前 QuiCommit 只覆盖"已有仓库"之后的提交、打标签、生成变更日志等场景，缺少"仓库起步"环节——用户需要先手动 `git init`、准备 `README.md` 与 `.gitignore`、创建分支、添加远程，才能开始使用 `quicommit commit`。`ginit` 目标是用一条命令完成这套初始化流程。

规格详见 `.scratch/ginit/spec.md`；边界取舍见 ADR 0006，命令命名见 ADR 0005。

- [ ] **仓库初始化**：把当前目录初始化为 Git 仓库，实现走 `git2::Repository::init_opts`（不 shell out `git init`，因此不必把 README 承诺的 `Git 2.0+` 下限抬高到 2.28）
  - 当前目录已是仓库时跳过建库，但**继续补齐**下面各项——`ginit` 是可重复执行的补齐工具
  - 当前目录位于某个外层仓库之内时直接拒绝并报出该外层仓库路径，避免造出嵌套仓库、也避免把远程加到不相干的仓库上
  - 裸仓库跳过建库与文件生成（无工作目录），但仍允许添加远程
  - 不新增 `--force`：`git init` 对已存在仓库本就幂等，`--force` 唯一可能的语义是删 `.git` 重建，那是销毁用户历史
- [ ] **自动生成 `README.md`**
  - 已存在则逐字节不动
  - 不存在则只写一行 `# <目录名>`（LF、UTF-8 无 BOM、单个结尾换行、不加"由工具生成"署名，也不放占位段落）
  - 目录名取不到有意义取值（盘根、UNC、`.`）时跳过并说明
- [ ] **自动生成 `.gitignore`**
  - 已存在则完全跳过，**绝不追加**（判断"条目是否已覆盖"要匹配 `/target`、`**/target/` 等多种写法，判错就是往用户手工维护的文件里写噪音）
  - 不存在则写入"通用基线 + 命中的 Ecosystem 段"
  - 基线（无条件）：`build/`、`dist/`、`*.log`、`tmp/`、`.env`、`.env.*`
  - Ecosystem 段按根目录标志文件命中，多生态取并集，跨段条目去重（保留首次出现）、去重后为空的段整段省略：Rust / Node / Python / Go / Maven / Gradle / Ruby / PHP / Flutter / C/C++
  - **不包含** OS 专属（`.DS_Store`、`Thumbs.db`）与 IDE 专属（`.vscode/`、`*.swp`）条目；也**不照抄**本仓库根目录的 `.gitignore`——它含 `# OS`、`# IDE` 两段，并把 `Cargo.lock`、`config.toml`、`CONTEXT.md`、`adr/`、`.claude/` 这类 QuiCommit 开发私货忽略了，只可参考其分节风格
  - Rust 段不忽略 `Cargo.lock`：新生成的仓库默认应可复现构建
- [ ] **Initial branch**
  - 优先级：`-b` / `--branch <name>` > 全局 `init.defaultBranch` > `main`
  - 只在尚不存在任何分支时确立；已有提交的仓库传 `-b` 时忽略并说明原因（重命名分支归 `git branch -m`）
- [ ] **添加远程仓库**
  - `--add <url>`（远程名默认 `origin`）与 `--add <name>=<url>` 两种形态，`--add` 可重复传入以一次配好多个远程
  - 远程名已存在时该条添加失败，且**不改动**现有远程的 URL（覆盖远程地址难以逆转，改地址应由用户显式用 `git remote set-url`）
  - URL 只校验非空、无空白、含 `/` 或 `:`，形态合法性交给 libgit2——严格 URL 校验会误杀 `git@host:user/repo.git` 这类 scp-like 地址
  - 不调托管平台 API 创建远端仓库、不验证远程可达性、不设置 upstream 跟踪分支：`ginit` 全程离线
- [ ] **可选的身份配置**：`--profile <name>` 时才把该 GitProfile 应用到新仓库（`GitProfile::apply_to_repo`）并记录目录→profile 映射；不带该参数时不碰身份、也不创建或改动 `config.toml`
- [ ] **不创建首个提交**：结束后打印逐步汇总与下一步提示（`quicommit commit`），并在仓库与全局都取不到 `user.name` / `user.email` 时明确提示如何补
- [ ] **交互与输出**：一个预览块 + 一次确认；`--yes` 只跳过确认、不改变产出（ADR 0004），`--dry-run` 磁盘上什么都不发生；输出遵循 ADR 0003 的通道约定；终端文案全部进 7 语言 i18n，生成文件的内容不翻译
- [ ] **失败处理**：建库或嵌套仓库冲突立即报错终止；后续单步失败（文件写入、某条远程、profile）记录后继续执行，末尾汇总并以非零码退出，不回滚已写入的文件

### 2. Agent Skills 技能包完善 `P0`（新增）

**动机**：`.claude/skills`、`skills/` 目录下现有内容零散，需要系统化沉淀为可复用的 QuiCommit Agent 技能，让编码助手（Claude、Qoder 等）能够开箱用地安装、调用 QuiCommit。

- [ ] **安装类技能：`install-quicommit`**
  - 指导用户 / Agent 在 Windows / macOS / Linux 上安装 QuiCommit：Cargo 安装、预编译二进制、源码构建等途径
  - 覆盖首次运行前的环境依赖检查（Git、系统密钥环服务等）
- [ ] **使用指导类技能：`use-quicommit`**
  - 面向 Agent 的命令速查与调用范式：`commit` / `tag` / `changelog` / `config` / `profile` / `credential`，以及新增的 `ginit`
  - 说明各命令的输入前提（如需要先 `quicommit init` 配置 LLM Provider）、典型输出与常见失败排查
- [ ] **技能内容规范**
  - 统一采用 SKILL.md 结构（触发场景 / 使用方式 / 注意事项），与 `.claude/skills` 现有约定保持一致
  - 技能内示例命令、参数需要与 `src/commands/` 的实际实现保持同步，避免文档漂移
- [ ] **发布与复用**
  - 评估随 crate 发布（打包进 `skills/`）还是通过独立仓库 / 技能市场分发

### 3. 新增模型支持 `P1`

扩展 LLM 提供商和模型覆盖范围，满足更多场景和偏好。

- [ ] **新增国内模型提供商**
  - 通义千问 (Qwen) — 阿里云 DashScope API
  - 文心一言 (ERNIE) — 百度千帆 API
  - 智谱 GLM — ChatGLM API
  - 百川 (Baichuan) — Baichuan API
- [ ] **新增国际模型提供商**
  - Google Gemini API
  - Mistral AI API
  - Cohere API
  - Groq (LPU 推理加速)
- [ ] **本地模型扩展**
  - 支持 llama.cpp 服务端（兼容 OpenAI API 格式）
  - 支持 vLLM 部署的模型
  - 本地模型推荐列表与一键配置向导
- [ ] **模型能力适配**
  - 不同模型的 token 限制自适应
  - 模型特定的 prompt 模板优化
  - 支持 function calling / tool use（用于复杂生成场景）

### 4. 生成体验优化 `P1`

提升 AI 生成提交信息、标签说明和变更日志时的用户体验。

- [ ] **流式输出与实时反馈**
  - [ ] 终端打字机效果实时显示生成内容
  - [ ] 流式生成过程中支持 `Ctrl+C` 中断
- [ ] **生成质量提升**
  - 基于 commitlint 规则的后校验与自动修正
  - 支持 Few-shot 示例引导（用户可自定义示例库）
  - 生成结果的置信度评分与多候选方案
- [ ] **Diff 上下文增强**
  - 智能 diff 摘要（大改动时自动压缩关键信息）
  - 支持 `.gitattributes` 排除 / 包含规则
  - 按文件类型分组生成更精准的提交描述
- [ ] **交互式编辑增强**
  - 生成后支持内联编辑（类似 `git rebase -i` 体验）
  - 支持重新生成指定部分（如 scope、description）
  - 历史提交信息学习与风格适配
- [ ] **批量操作支持**
  - 批量生成多个 commit（分组暂存区变更）
  - `--dry-run` 预览模式（只生成本地查看，不写 Git）
- [ ] **性能优化**
  - API 请求并发优化（多个模型同时生成候选）
  - 本地缓存常用 prompt 模板
  - 减少不必要的 diff 计算

---

## 长远规划 🌟

- [ ] **VS Code 扩展** — 在 IDE 内直接使用 QuiCommit
- [ ] **GitHub Action / GitLab CI 集成** — 自动化 PR 标题和描述生成
- [ ] **团队协作** — 共享 commit 风格配置、prompt 模板库
- [ ] **Web Dashboard** — 可视化管理多仓库的 Git 活动与 AI 生成统计
- [ ] **插件系统** — 允许社区贡献自定义 LLM 提供商和生成策略