dbtool-cli-v1/GIT_WORKFLOW.md

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

示例：

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 运行时凭据注入规范