Skip to content
cccskills
FreePublished on GitHub

commit

代码提交与 MR 创建技能 - 自动生成语义化 commit message、创建符合规范的 GitLab Merge Request、验证飞书工作项关联。当用户提到 Git 提交、commit、push、推送代码、创建 MR、创建 PR、合并请求、或需要提交代码、推送代码、创建 MR/PR 时,必须使用此技能。

支持交互式(对话)和非交互式(参数)两种模式。

The English summary is being prepared. Showing the original description.

Works withGitLab
See how to install

Files included (21)

  • SKILL.md13.5 KB
  • config/code-committer.yaml2.5 KB
  • examples/interactive-usage.md1.5 KB
  • examples/non-interactive-usage.md2.4 KB
  • references/audit-checklist.md960 B
  • references/commit-conventions.md887 B
  • references/mr-creation-troubleshooting.md12.8 KB
  • references/mr-templates/bugfix.md331 B
  • references/mr-templates/ci-cd.md365 B
  • references/mr-templates/docs.md290 B
  • references/mr-templates/feature.md292 B
  • references/mr-templates/hotfix.md408 B
  • references/mr-templates/refactoring.md379 B
  • scripts/audit-checker.sh8.9 KB
  • scripts/check-dependencies.sh4.7 KB
  • scripts/code-committer.sh19.7 KB
  • scripts/commit-generator.sh5.0 KB
  • scripts/error-codes.sh6.5 KB
  • scripts/feishu-validator.sh7.1 KB
  • scripts/gitlab-api.sh14.6 KB
  • scripts/remote-handler.sh8.3 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Commit Skill

企业级 Git 提交和 MR 创建技能,支持自动生成语义化 commit message、创建符合规范的 MR、验证飞书工作项关联。

核心职责

  1. 代码提交:自动生成语义化 commit message,基于代码变更分析
  2. 推送代码:推送到远端仓库,支持自动创建远端分支
  3. MR 创建:创建符合 Conventional Commits 规范的 GitLab MR
  4. 工作项验证:验证飞书项目工作项关联,确保可追溯性
  5. 内审检查:提交前检查敏感信息、测试覆盖、文档更新

🚨 铁律:MR 创建前必须同步目标分支(强制执行)

⚠️ 创建 MR 之前,必须先同步目标分支的代码!!!没有 conflict 才能创建 MR!

标准工作流程(强制执行):

# Step 1: 同步目标分支(必须!)
git fetch origin <target-branch>

# Step 2: Rebase 到最新目标分支(必须!)
git rebase origin/<target-branch>

# Step 3: 检查是否有冲突
git status

# Step 4: 只有在没有冲突的情况下,才能:
#    - 推送代码
#    - 创建 MR

检查清单(强制执行):

  • 目标分支已同步(git fetch origin <target-branch>)
  • 已 rebase 到最新目标分支(git rebase origin/<target-branch>)
  • 无冲突(git status 显示 clean)
  • 变更列表正确(git diff --name-only origin/<target-branch>...HEAD)
  • 提交历史正确(git log --oneline origin/<target-branch>..HEAD)

只有以上全部满足,才能创建 MR!

Why: 避免重复提交、错误的 diff、不必要的冲突

典型后果:

  • MR 包含已合并到目标分支的变更
  • 需要强制 rebase 修复,增加工作量
  • 影响代码审查效率和 CI/CD 流程

⚠️ 环境配置管理

设计原则:

  • ✅ SKILL.md: 存储可移植的代码提交流程和最佳实践
  • ✅ .env.skill: 存储项目特定凭证信息(GitLab PAT、飞书 auth_key 等)
  • ❌ 禁止: 将具体凭证值硬编码在 SKILL.md 中

凭证信息配置:

项目根目录的 .env.skill 文件会保留此技能需要的凭证信息:

# GitLab Personal Access Token
GITLAB_PAT=glpat-xxxxxxxxxxxxx

# 飞书认证密钥
FEISHU_AUTH_KEY=cli_xxxxxxxxxxxxxx

# GitLab 实例地址(可选,默认从环境变量读取)
GITLAB_URL=https://git.example.com

# 飞书项目 ID(可选,用于工作项验证)
FEISHU_PROJECT_ID=xxxxxxxxxxxxx

部署前验证:

  1. 读取项目根目录 .env.skill 文件获取凭证信息
  2. 验证 GitLab PAT 是否有效
  3. 验证飞书 auth_key 是否可用
  4. 确认凭证有足够的权限(git write、feishu project read)

注意: .env.skill 已在 .gitignore 中,不应提交到 Git 仓库


核心功能

1. Commit 自动生成

基于代码变更自动生成语义化 commit message:

  • 分析文件列表 + code diff + 工作上下文
  • 输出 ≤1/2 屏幕的精简描述
  • 不强制 Conventional Commits 格式(避免 semantic_release 版本爆炸)
  • 支持动态上下文注入(加载项目最近 commits 匹配风格)

2. Push 远端

支持推送到远端仓库:

  • 默认使用 origin/<branch> 命名
  • 远端分支不存在时自动创建
  • 自动检测默认目标分支(master/main)

3. MR 创建

创建符合规范的 GitLab MR:

  • MR Title:遵循 Conventional Commits 格式 type(scope): summary<30字符
  • MR Description:包含飞书工作项元数据(YAML front matter 格式)
  • 支持交互式(可选对话)和非交互式(一次性参数)两种模式

4. 飞书工作项验证

验证飞书项目工作项关联:

  • 检查 YAML front matter 格式
  • 使用 lark-cli 验证工作项 ID 是否存在
  • ⚠️ 强制要求:必须要求用户提供关联的"飞书工作项 uid"
  • 非交互模式:验证失败直接报错退出
  • 交互模式:提示补正,阻止创建

重要说明:

  • 飞书工作项 uid 是飞书项目管理系统中的唯一标识符
  • 创建 MR 时必须关联有效的飞书工作项 uid(数字格式,如 6934756567)
  • 不得使用占位符、默认值或跳过此验证步骤
  • 如果用户无法提供有效的 uid,应阻止创建 MR 并说明原因

5. 内审规则检查

执行代码提交前的内审检查:

  • 敏感信息检查(密钥、密码、IP 地址等)
  • 测试覆盖检查(测试文件是否存在或变更)
  • 文档更新检查

Commit 规则

📌 详细提交约定:参见 references/commit-conventions.md

自由格式:不强制 Conventional Commits,commit message 可以自由编写。

自动生成:基于代码变更自动生成语义化 message,参考项目最近的 commits 风格。


MR 规范

📌 MR 模板:

MR Title 格式

type(scope): summary
  • type: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  • scope: 影响范围(可选)
  • summary: 简短描述(<30 字符)

MR Description 格式

---
feishu.task: 6723548458
---

## 功能说明
(功能描述)

## 变更内容
- 变更点 1
- 变更点 2

## 测试
- [ ] 单元测试通过
- [ ] SIT 测试通过

重要规则:

  1. YAML front matter 必须在描述开头
  2. 字段名固定为 feishu.task
  3. 冒号后必须有空格
  4. 工作项 ID 是数字格式(如 6723548458)

工作模式

📌 详细使用示例:

交互式模式

交互式模式提供对话式流程,每个步骤都有默认值,用户可以确认或修改:

  1. 确认目标分支(自动检测 master/main)
  2. 检查 PAT 配置
  3. 输入飞书工作项 uid(⚠️ 强制要求)
  4. 验证飞书工作项 uid 有效性
  5. 生成/确认 MR Title
  6. 确认创建 MR

⚠️ 重要:飞书工作项 uid 是必填项

  • 不得使用占位符、默认值或跳过此步骤
  • 如果用户无法提供有效的 uid,应阻止创建 MR 并说明原因
  • 必须使用 lark-cli 或手动方式验证 uid 存在性

非交互式模式

非交互式模式通过命令行参数一次性提供所有信息,适合自动化脚本:

# 自动生成 commit
git add <files>
commit.sh --auto-generate --non-interactive

# 推送代码
push.sh --branch feature/login --remote origin --create-if-not-exists --non-interactive

# 创建 MR
mr.sh create \
  --source-branch feat/login \
  --target-branch master \
  --mr-title "feat(auth): implement login" \
  --feishu-task 6723548458 \
  --non-interactive

# ⚠️ 注意:--feishu-task 参数是必填项
# 如果用户未提供,必须明确提示并提供有效的飞书工作项 uid

错误处理

退出码系统

使用 3 位数字退出码(000-999):

  • 0xx: 成功/信息
  • 2xx: 依赖/配置错误
  • 3xx: Git 操作错误
  • 4xx: GitLab API 错误
  • 5xx: 飞书集成错误
  • 6xx: 内审检查错误
  • 9xx: 未知错误

交互式 vs 非交互式错误处理

场景交互式非交互式
PAT 未配置提示配置指导,等待输入输出错误,退出码 203
工作项验证失败提示补正,阻止创建输出错误,退出码 500
GitLab API 错误显示错误,询问重试输出错误,退出码 402
内审检查失败警告,询问是否继续输出警告,继续创建

配置

📌 配置文件示例:参见 config/code-committer.yaml

PAT 配置优先级

  1. 环境变量 GITLAB_PAT
  2. 配置文件 ~/.config/commit/config.yaml
  3. 项目配置 .claude/commit.yaml
  4. 运行时交互输入(仅交互式模式)

配置文件示例

gitlab:
  pat: ""  # 留空表示使用环境变量
  auto_detect_url: true

feishu:
  require_validation: true
  auth_identity: "user"

audit:
  check_sensitive_data: true
  check_test_coverage: false
  check_documentation: true

commit:
  max_length_lines: 12
  include_file_summary: true
  load_recent_commits: true
  check_claude_md: true

依赖要求

📌 可用脚本:

  • scripts/commit-generator.sh:自动生成 commit message
  • scripts/feishu-validator.sh:验证飞书工作项
  • scripts/audit-checker.sh:执行审计检查
  • scripts/error-codes.sh:错误码定义
  • scripts/gitlab-api.sh:GitLab API 操作
  • scripts/remote-handler.sh:远端仓库操作
  • 其他辅助脚本位于 scripts/ 目录

系统依赖:


使用示例

场景 1: 自动生成 commit 并推送

# 暂存变更
git add src/login.py tests/test_login.py

# 自动生成 commit message
commit.sh --auto-generate

# 推送到远端
push.sh --create-if-not-exists

场景 2: 创建关联飞书工作项的 MR

# 非交互式
mr.sh create \
  --source-branch feat/login \
  --target-branch master \
  --mr-title "feat(auth): implement JWT authentication" \
  --feishu-task 6723548458 \
  --non-interactive

# 交互式
mr.sh create
# (按提示输入)

场景 3: 一键提交+推送+创建 MR

push-and-mr.sh \
  --feishu-task 6723548458 \
  --non-interactive

内审检查

📌 详细审计检查清单:参见 references/audit-checklist.md

敏感信息检查

检测以下模式并提供警告:

  • password.*=
  • api[_-]?key.*=
  • secret.*=
  • IP 地址格式

测试覆盖检查

检查变更中是否包含测试文件:

  • 检查文件名是否包含 test 或 spec
  • 不实际运行测试,仅检查文件是否存在或变更

文档更新检查

检查相关文档是否需要更新:

  • README.md
  • API 文档
  • 变更日志

最佳实践

📌 详细故障排除指南: 参见 references/mr-creation-troubleshooting.md

MR 创建成功的关键技巧

核心技巧:

  1. ⚠️ 同步目标分支(铁律):git fetch origin <target-branch> && git rebase origin/<target-branch>
  2. PAT 验证: 先验证 PAT 权限,避免 401 错误
  3. HTTP 状态码捕获: 使用 curl -w 捕获状态码,判断创建结果
  4. MR 信息查询: 通过 API 查询 MR 的 iid 和 web_url
  5. 飞书任务 ID 验证: 检查 YAML front matter 格式(feishu.task: <uid>)
  6. 完整工作流程: 同步目标分支 → PAT 验证 → 创建 MR → 查询信息 → 验证结果

常见错误

🚨 MR 包含重复的文件变更(铁律违反):

  • 原因: 创建 MR 前未同步目标分支,导致包含已合并的变更
  • 解决: git fetch origin <target-branch> && git rebase origin/<target-branch> --force-with-lease
  • 预防: 遵循铁律,创建 MR 前必须先同步并 rebase 目标分支

HTTP 401 Unauthorized:

  • 原因: PAT 无效或权限不足
  • 解决: 验证 PAT 是否有 api 权限

glab 命令无返回结果:

  • 原因: PAT 未配置或版本过旧
  • 解决: 使用 glab --web 或切换到 curl API

飞书任务 ID 验证失败:

  • 原因: YAML 格式错误或 ID 不存在
  • 解决: 检查 feishu.task: <uid> 格式,冒号后有空格

🤝 Agent Team 协作

Commit 工作需要与其他角色密切协作。本 SKILL 专注于代码提交和 MR 创建技术实践,相关职责请参考:

  • 开发工作流 → dev SKILL

    • 代码开发、测试规范
    • Commit message 格式要求
    • 参考:docs/scrum/story/ 中的 Story 文档
  • 测试验证 → qa SKILL

    • 测试覆盖要求
    • 提交前测试验证
    • SIT/UAT 测试标准
  • 项目管理 → pm SKILL

    • 飞书工作项管理
    • Story/Epic 状态跟踪
    • 参考:飞书项目管理系统
  • DevOps 流程 → devops SKILL

    • CI/CD Pipeline 集成
    • MR/Merge Request 审批流程
    • 部署环境配置

参考


版本: v2.1 维护者: DevTools Team

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

arch

Free

架构师工作技能 - 架构设计、文档管理、语义化版本控制、设计审查。当用户提到架构、设计文档、版本管理、技术选型、系统设计、数据模型、API设计、文档审查、设计规范、架构决策、或需要创建/更新设计文档时,必须使用此技能。确保所有设计文档遵循语义化版本规范和命名约定。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

dev

Free

开发工作流程指导 - 编码、测试、代码质量、MR/PR 创建和 CI/CD。用于开发任务、编码、功能实现、Bug 修复、单元测试、代码覆盖率、代码审查、CI/CD 流水线和 Git 操作。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

devops

Free

DevOps 工作技能 - CI/CD 流程、容器化构建、Kubernetes 部署、基础设施即代码、监控告警。当用户提到部署、容器化、K8s、Helm、ArgoCD、CI/CD、监控、日志、或需要执行部署、排查线上问题时,必须使用此技能。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

pm

Free

PM 编排技能 — 具备意图识别与动态路由能力的项目管理中枢。除了 pm 的全部 Story/Epic/Sprint 管理能力外,pm 能分析用户 prompt 的多领域意图,动态匹配所需的专业 skill(arch/dev/ued/qa/devops 等),生成编排计划并在用户确认后依次唤起各 skill 协同工作。当用户的请求涉及多个专业领域、需要跨 skill 协调、或者用户希望用一个 prompt 驱动完整的「设计→实现→验证」流程时,使用此技能。纯 Story 管理/迭代规划等单领域任务,pm 会直接处理而不路由。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

qa

Free

QA 工作技能 — 测试分层架构、UT/API/SIT/E2E/UAT 测试、交叉验证策略、测试数据管理、测试报告管理。当用户提到测试、QA、质量保证、回归测试、单元测试、集成测试、验收测试、测试覆盖率、pytest、go test、E2E、Playwright、monkey test、fuzz test、RPC 测试、测试用例设计、TDD、测试框架、测试策略审查、问题排查、测试环境、测试数据、SIT 交叉验证、或需要设计/执行/增强测试策略时,必须使用此技能。确保所有测试活动遵循分层架构和业务正确性验证原则。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

安全重构代码技能。当用户明确提到"重构"、"代码异味"或需要在TDD循环的Refactor阶段改进代码内部结构时使用。

The English summary is being prepared. Showing the original description.

linview/agent-team-archetype22Updated Aug 9, 2026

See all skills by linview

Report a problem with this skill