name: git-workflow description: Use when the user wants to generate, rewrite, validate, or prepare Git commit messages, pull request titles, or pull request descriptions.
Git Workflow
目标
为当前仓库变更生成可追溯的 Git 提交信息和 Pull Request 内容。输出必须准确反映实际变更，不编造测试结果、需求背景、CI 状态或风险结论。
适用场景
- 生成或校验 commit message。
- 生成或校验 PR title。
- 生成或校验 PR description。
- 根据当前分支、暂存区、diff 或用户说明整理提交/PR 文案。
- 判断变更是否应该拆分成多个 commit 或 PR。
上下文优先级
- 用户明确提供的信息：模块名、需求背景、issue、type、测试结果、目标分支。
- 已暂存变更：
git diff --staged。 - 当前分支相对目标分支的提交和 diff。
- 未暂存变更：
git diff。 - 文件状态：
git status --short。
如果信息不足以判断意图，先问一个具体问题，不要猜。 生成 commit message 时，默认只基于已暂存变更；没有已暂存变更时再说明将基于未暂存变更生成。生成 PR 内容时，默认基于当前分支相对目标分支的已提交变更；未提交变更只能作为额外提醒，不能默认写进 PR 已完成内容。
推荐命令
按需读取最小上下文：
git branch --show-current
git status --short
git diff --staged
git log --oneline main..HEAD
git diff --stat main...HEAD
git diff main...HEAD
缺少目标分支时默认使用 main；仓库没有 main 时尝试 master；仍无法判断时询问用户。
Commit Message
默认使用 Conventional Commits 风格：
<type>(<module>): <subject>
模块不明确或变更多模块无法拆分时省略模块：
<type>: <subject>
需要正文时：
<type>(<module>): <subject>
<body>
<footer>
Type
| type | 使用场景 |
|---|---|
feat | 新增用户可见功能、接口、能力 |
fix | 修复 bug、错误行为、异常处理 |
docs | 文档变更，不影响运行时代码 |
test | 新增或调整测试 |
refactor | 不改变外部行为的代码结构调整 |
chore | 依赖、工具、脚本、配置等维护工作 |
build | 构建系统、打包、镜像相关变更 |
ci | CI/CD 流程或配置变更 |
style | 纯格式化、空白、代码风格调整 |
perf | 性能优化 |
revert | 回滚提交 |
Module
- module 必须是业务模块或产品模块，例如
studio、hub。 - 优先使用用户明确给出的模块名。
- 未指定模块名时，根据变更路径、包名、文档语境、功能归属推断。
- 不要把技术层、目录名、资源名直接当 module，例如
routes、types、openapi、readme、deps，除非它们本身是用户认可的模块。 - 一次提交涉及多个无关模块时，建议拆分；无法拆分时省略 module。
- module 使用小写短横线或单个小写词，避免中文、空格和过长名称。
Subject
- 使用英文小写祈使句或简洁动词短语。
- 不以句号结尾。
- 控制在 72 个字符以内。
- 只描述本次提交实际包含的主要变更。
- 避免
update code、misc changes、fix stuff等模糊表达。
Commit 输出
只要求 commit message 时，默认输出 1 到 3 个候选，推荐项放第一：
1. feat(studio): add agent creation endpoint
2. feat(hub): add workspace sync support
3. feat: add agent creation and workspace sync support
如果用户要求校验，输出是否合规、原因和修正版。
Pull Request
PR title 默认复用 commit message 规则，并必须让跨团队评审者快速理解变更范围：
<type>(<module>): <subject>
- 标题要描述最终结果，不要只写实现动作。
- module 必须是业务模块或产品模块，例如
studio、hub。 - 如果 PR 包含多个相关 commit，标题描述整体结果。
- 如果包含多个无关主题，先建议拆分 PR。
PR Description
默认使用 GitHub 风格模板：
# Pull Request: <type>(<module>): <subject>
## Purpose
<!-- Why is this change needed? What problem does it solve? Link related issues. -->
## Implementation Details
<!-- What changed technically? Explain notable design choices and tradeoffs. -->
## Testing Evidence
<!-- List real automated and manual testing performed. Do not invent results. -->
### Automated Tests
- [ ] Unit tests
- [ ] Integration tests
- [ ] E2E tests
- [ ] Other:
### Manual Testing
<!-- Describe manual verification steps, or write "Not run (reason: ...)". -->
## Impact Assessment
<!-- Note potential impacts on APIs, routes, OpenAPI docs, README API docs, configs, deployment, data, performance, or other modules. -->
## Review Checklist
- [ ] Code follows project style guidelines
- [ ] Functions and parameters include TSDoc/JSDoc where applicable
- [ ] Tests are added or updated where behavior changed
- [ ] Automated tests pass locally or the reason is documented
- [ ] Route changes update `docs/openapi` and `README.md` API sections
- [ ] Type changes are reflected in `src/types`
- [ ] No unrelated files, formatting churn, or speculative abstractions are included
- [ ] `docs/design` was not modified
## Related Issues
<!-- Link tickets, issues, requirements, or discussions. Use "Closes #..." only when appropriate. -->
用户要求中文时使用：
# Pull Request: <type>(<module>): <subject>
## 目的
<!-- 为什么需要这个变更？解决什么问题？关联哪些 issue 或需求？ -->
## 实现细节
<!-- 技术上改了什么？说明关键设计选择和取舍。 -->
## 测试证据
<!-- 列出真实执行过的自动化和手工测试，不要编造结果。 -->
### 自动化测试
- [ ] 单元测试
- [ ] 集成测试
- [ ] E2E 测试
- [ ] 其他：
### 手工测试
<!-- 说明手工验证步骤，或写“未运行（原因：...）”。 -->
## 影响评估
<!-- 说明对 API、routes、OpenAPI 文档、README API 文档、配置、部署、数据、性能或其他模块的影响。 -->
## Review Checklist
- [ ] 代码符合项目风格
- [ ] 函数和参数在适用处包含 TSDoc/JSDoc
- [ ] 行为变更已新增或更新测试
- [ ] 自动化测试已本地通过，或已说明未运行原因
- [ ] routes 变更已同步更新 `docs/openapi` 和 `README.md` API 部分
- [ ] 类型变更已同步更新 `src/types`
- [ ] 未包含无关文件、格式噪音或推测性抽象
- [ ] 未修改 `docs/design`
## 关联问题
<!-- 关联 issue、需求或讨论。只有真正关闭问题时才使用 “Closes #...”。 -->
PR 内容规则
- Purpose/目的说明变更原因，不重复实现细节。
- Implementation Details/实现细节说明技术方案和关键取舍，避免泛泛描述。
- Testing Evidence/测试证据必须来自真实执行结果或用户提供的信息。
- 未运行测试时写
Not run (reason: ...)或未运行（原因：...）。 - Impact Assessment/影响评估必须写具体可评审的影响；低风险也要说明依据。
- Review Checklist 保留未勾选状态，由提交者或评审者按实际情况处理。
- Related Issues/关联问题只在确实相关时填写；不要凭空关联 issue。
- 修改 HTTP routes 时，检查是否需要提及 OpenAPI 和 README API 文档更新。
- 修改后端接口类型时，检查是否需要提及
src/types变更。 - 不要声称 CI 通过，除非已经看到对应结果。
平台适配
- GitHub：使用上面的默认模板，支持 task list、
Closes #...和 draft PR。 - GitLab：将标题保留不变；把
Purpose改为Why is this MR needed?，把Implementation Details改为Implementation Notes，把Related Issues改为Relevant issue links。 - Azure DevOps：将
Related Issues写成Fixes: AB#<work-item-number>；保留Types of changes或Checklist，方便和 work item 关联。 - 如果用户指定平台，优先输出该平台格式；未指定时默认 GitHub。
PR 输出
默认输出：
Title:
feat(studio): add agent creation endpoint
Body:
# Pull Request: feat(studio): add agent creation endpoint
## Purpose
Add an endpoint for creating agents from DIP Studio so clients can start the agent lifecycle through the backend API.
## Implementation Details
- Add the agent creation route and request/response types.
- Update OpenAPI and README API documentation for the new route.
## Testing Evidence
### Automated Tests
- [x] Unit tests: npm test
- [ ] Integration tests
- [ ] E2E tests
- [ ] Other:
### Manual Testing
Not run (reason: covered by route tests).
## Impact Assessment
Low: endpoint behavior is covered by route tests and API documentation is updated.
## Review Checklist
- [ ] Code follows project style guidelines
- [ ] Functions and parameters include TSDoc/JSDoc where applicable
- [ ] Tests are added or updated where behavior changed
- [ ] Automated tests pass locally or the reason is documented
- [ ] Route changes update `docs/openapi` and `README.md` API sections
- [ ] Type changes are reflected in `src/types`
- [ ] No unrelated files, formatting churn, or speculative abstractions are included
- [ ] `docs/design` was not modified
## Related Issues
Closes #123
用户只要求标题时，只输出标题候选；只要求描述时，不输出标题。
判断规则
- 代码和测试一起变更：按代码行为选择 type，不使用
test。 - 文档随接口变更一起更新：按接口变更选择 type，不使用
docs。 - 只更新 OpenAPI、README 或文档：使用
docs(<module>)。 - 只修复测试失败且不改变业务行为：使用
test(<module>)或chore(<module>)。 - 修改依赖版本：使用
chore(<module>)，subject 说明依赖变更。 - 调整 Dockerfile、Helm Chart、构建脚本：使用
build(<module>)。 - 调整 GitHub Actions 或 CI 脚本：使用
ci(<module>)。 - 发现多个无关主题：先建议拆分，再分别生成 commit 或 PR 文案。