# dbtool-cli-v1 Git 仓库与 Agent 提交规范

日期：2026-03-26  
作者：CTO

## 1. 结论

- `dbtool-cli-v1` 应立即作为独立 Git 仓库初始化，不再依赖任何“Paperclip 根仓库”语义。
- 默认远程使用 HTTPS：
  - `https://gitea.shay7sev.site/paperclip/dbtool-cli-v1.git`
- agent 不允许直接 push 到默认分支 `main`。
- 一个实现类 issue 允许多次 commit，但每次都必须对应清晰检查点。
- 前端、后端各自对自己负责的 issue 分支与提交负责；跨前后端/集成类 issue 由该 issue 的 owner 负责最终整合与合并。
- `main` 应开启 protected branch；常规变更走 branch + review gate，只有一次性仓库 bootstrap 允许例外。

## 2. 独立仓库边界

从本次初始化开始，项目根目录就是唯一仓库边界：

- 仓库根：`/workspace/repo/dbtool-cli-v1`
- Git 元数据：`/workspace/repo/dbtool-cli-v1/.git`
- 远程名：`origin`
- 默认分支：`main`

这意味着：

- 共享计划、backlog、runbook、代码和测试都跟随本仓库历史演进。
- 后续任何 agent 都应在本仓库内提交，不再把该项目视为上层 monorepo 的子目录。
- 若未来存在前后端共存结构，也应继续共用此仓库边界，按目录分工，而不是拆成“一个产品多个隐藏仓库”。

## 3. 远程接入方案结论

### 推荐：HTTPS + Gitea bot token

推荐把 HTTPS 作为默认 push 方案，原因如下：

- 容器内不依赖宿主机 SSH agent 或私钥转发。
- 更容易通过 Paperclip secret / 环境变量注入。
- 更适合做统一脚本化封装，复用到前端、后端和全栈项目。
- 轮换 token 和停用单个 bot 凭据更直接。

建议采用：

- 一个专用 Gitea bot / service account
- 仅授予目标仓库写权限
- token 不写入仓库，不落盘到共享文档
- agent 运行时通过环境变量注入：
  - `GITEA_USERNAME`
  - `GITEA_TOKEN`

### 备选：SSH bot key / deploy key

SSH 可以作为组织偏好的备选，但不是当前默认推荐：

- 优点：不需要 HTTP token；可与已有 SSH 管理习惯一致。
- 缺点：容器内要管理私钥文件、`known_hosts`、权限位与 key 分发。
- 对多项目复用来说，落地复杂度高于 HTTPS。

只有在以下条件成立时再选 SSH：

- 组织已有稳定的 bot key 生命周期管理；
- 已有容器内密钥挂载与 host fingerprint 管理机制；
- 明确要求禁用 HTTPS token。

## 4. Agent 认证与 push 机制

### 最小可落地方案

1. 运行时向 agent 注入：
   - `GITEA_USERNAME`
   - `GITEA_TOKEN`
2. 使用 `GIT_ASKPASS` 辅助脚本回答 Git 的用户名/密码提示。
3. 本地仓库远程固定为：
   - `origin -> https://gitea.shay7sev.site/paperclip/dbtool-cli-v1.git`
4. push 时只推送当前工作分支，不推送 `main`。

仓库内已提供最小脚本：

- `scripts/git/gitea-askpass.sh`

示例：

```bash
export GITEA_USERNAME=paperclip-bot
export GITEA_TOKEN=***REDACTED***
export GIT_ASKPASS="$PWD/scripts/git/gitea-askpass.sh"
git push -u origin HEAD
```

### 安全边界

- token 只通过运行时环境注入。
- 禁止把 token 写入 `.git/config`、shell history 或文档。
- bot 凭据只用于 Git 读写，不复用个人账号。
- 若 agent 只需 commit、不需 push，则不注入 `GITEA_TOKEN`。

## 5. Commit / Branch / Push 规则

### Commit 粒度

实现类 issue 允许多次 commit，但必须满足：

- 每次 commit 对应一个清晰检查点；
- 检查点至少满足“代码可读”或“文档可评审”；
- 不允许把多个无关 issue 混在一个 commit；
- 未达到检查点时可继续在工作区迭代，不强制碎片化提交。

推荐检查点：

- 一个子命令可运行
- 一个 defect 已复现并修复
- 一组测试新增并通过
- 一个 runbook / governance 文档完成首版

### Branch 规则

默认分支命名：

- agent：`agent/<agent-name>/<issue-id>-<slug>`
- human：`user/<name>/<issue-id>-<slug>`

示例：

- `agent/backend/CMP-14-sqlite-connect-validation`
- `agent/cto/CMP-18-git-bootstrap`
- `user/alice/CMP-12-release-smoke`

### Push 规则

- agent 不直接 push `main`
- agent 只 push 自己负责 issue 的工作分支
- 合并到 `main` 前必须经过 review gate
- 仅仓库第一次 bootstrap 可由指定 owner 执行一次受控初始化推送

## 6. Protected Branch / Review Gate

`main` 应立即启用以下保护：

- 禁止直接 push
- 禁止 force push
- 至少 1 个 review
- CI / smoke 必须通过后才允许合并

当前阶段的最小 gate：

- Rust 项目：`cargo test`
- CLI 可启动检查：`cargo run -p dbtool-cli -- --help`
- 发布链路 issue 涉及时，再叠加 release smoke

## 7. 前端 / 后端 / 集成 issue 提交责任

- 后端 issue：由后端 owner 负责提交、push、自测说明和最终合并准备
- 前端 issue：由前端 owner 负责提交、push、预览说明和最终合并准备
- 测试 / QA issue：由 QA owner 提交测试资产、矩阵、runbook 和证据脚本
- 集成类 issue：由该 issue 明确 owner 负责最终整合提交

管理规则：

- 不存在“别人顺手帮你提交”的默认机制
- 如需跨角色修改，必须在 issue 上明确 owner 与验收边界
- 多人参与同一产品仓库时，各自 push 自己的分支，由集成 owner 收口

## 8. dbtool-cli-v1 当前落地动作

本次已完成：

- 在项目根目录初始化独立 Git 仓库
- 确认目标远程仓库页面可达：
  - `https://gitea.shay7sev.site/paperclip/dbtool-cli-v1`
- 配置 `origin`
- 完成首次本地 commit，证明 agent 在受控条件下具备 commit 能力

本次未做：

- 未直接 push 到远程默认分支
- 未在仓库中存放任何长期凭据
- 未跳过未来应有的 branch protection / review gate

## 9. 后续复用方式

该机制可直接复用到前后端共存项目：

1. 每个产品/项目一个独立仓库
2. 统一使用 `origin` + HTTPS bot token
3. 统一使用 `agent/...` / `user/...` 分支命名
4. 统一要求“一个 issue 多次 commit 允许，但每次必须是清晰检查点”
5. 统一由 issue owner 对最终提交与合并负责

如果未来要平台化，可以把以下内容抽成公司级模板：

- `GIT_WORKFLOW.md`
- `scripts/git/gitea-askpass.sh`
- protected branch 默认策略
- Paperclip agent 运行时凭据注入规范