git-commit-helper
项目摘要
git-commit-helper 是 Docker 优先的本地开发者工具。它在浏览器中管理显式挂载的 Git 仓库，展示分支、工作区、暂存区、差异、远端配置和提交拓扑，并生成可编辑的 Conventional Commit 信息。提交和推送仍是明确操作，不由模型自动执行。
作者职责
- 设计仓库添加、状态读取、差异审阅、提交和推送流程。
- 实现 React 前端、Express API、SQLite 设置存储和 Git 调用层。
- 约束挂载目录、凭据、暂存范围和子进程执行边界。
- 建立后端测试、端到端测试、容器冒烟和 CNB 镜像构建。
系统架构
React/Vite 构建为静态资源，由 Express 单进程同时提供页面和 /api。SQLite 保存应用设置，代码仓库通过宿主机目录显式挂载。运行镜像不包含用户代码、SSH Key 或 AI Key，服务端通过 Git 库读取状态并执行受控命令。
关键设计决策
- 默认提交只处理已暂存内容，不隐式执行
git add -A，使提交范围与用户审查结果一致。 - AI 仅生成可编辑消息，不直接提交或推送；最终副作用必须经过单独操作。
- 前后端合并为单容器交付，降低本地工具启动和端口管理成本。
- 仓库刷新时同步刷新差异和拓扑，避免界面继续展示过期状态。
安全边界
所有仓库操作限制在配置的挂载根目录内，应用数据使用独立持久卷。AI Key 通过环境或本地设置提供，不写入镜像。案例不公开实际仓库清单、远端 URL、Git 用户信息、文件差异或认证材料。
工程难点
目录浏览、仓库状态和文件状态均可能触发大量同步文件系统调用。实现需要限制扫描范围、减少重复状态读取，并在仓库不存在、工作区变化或远端鉴权失败时返回可定位错误。
验证证据
- 后端单元与集成测试覆盖仓库发现、状态、配置和提交逻辑。
- 端到端用例验证从页面操作到 API 响应的主要流程。
- 容器冒烟检查镜像启动、挂载目录和 HTTP 健康状态。
已知限制
- 当前镜像发布基线面向 macOS arm64，本地目录和凭据挂载方式需要按运行环境调整。
- 推送行为依赖用户自行配置的 SSH 或 HTTPS 凭据。
- 工具不替代 Git 的冲突处理、签名提交和复杂历史重写能力。
后续演进
后续可增加更细粒度的命令审计、只读模式提示和多架构镜像，同时保持所有写操作显式触发。