195 lines
6.3 KiB
Markdown
195 lines
6.3 KiB
Markdown
# 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 运行时凭据注入规范
|