GitLab 工作流
通过 mx_gitlab 工具管理 GitLab 项目。严格遵守团队规范。
前置条件
- 安装插件:
openclaw plugins install openclaw-morphixai
- 获取 API Key: 访问 morphix.app/api-keys 生成
mk_xxxxxx 密钥
- 配置环境变量:
export MORPHIXAI_API_KEY="mk_your_key_here"
- 链接账号: 访问 morphix.app/connections 链接 GitLab 账号，或通过
mx_link 工具链接（app: gitlab）
参数命名规范（重要）
mx_gitlab 工具所有 action 的参数命名：
| 参数 | 说明 |
|---|
project | 项目 ID（数字字符串）或路径（group/repo），不是 project_id |
mr_iid | MR 在项目内的序号，不是 merge_request_iid |
pipeline_id | Pipeline 的全局 ID |
description 字段换行格式
⚠️ description 字段必须使用真实换行符，不要使用 \n 字面量字符串。
错误示例（在 GitLab 上会显示为 \n）：
description: "改动\n- 修复 bug\n- 新增功能"
正确示例（使用 YAML 多行字符串）：
description: |
## 改动
- 修复 bug
- 新增功能
## 测试
- 单元测试通过
代码审查策略（优先级顺序）
获取 MR 代码变更时，按以下顺序尝试：
✅ 优先：本地 git（推荐）
本地仓库 + git 命令是最可靠的代码审查方式：
- 无需额外认证（使用本地已有凭证）
- 无响应体大小限制（任意规模的 diff）
- 速度快，工具丰富（log、diff、show、blame）
第一步：查找本地仓库路径
# nodes.run — 在本机执行
find ~/www -maxdepth 4 -type d -name '<仓库名>'
# 例：find ~/www -maxdepth 4 -type d -name 'tanka-2b-web'
第二步：fetch 最新数据
# nodes.run — 工作目录切换到仓库路径
cd ~/www/<项目路径> && git fetch origin
第三步：获取 MR 的 commits（需要知道源分支和目标分支）
# 查看 MR 分支间的 commit 列表
git log origin/<target-branch>..origin/<source-branch> --oneline
# 示例（MR: feat/zoom-v2/main → uat-tanka-oh）
git log origin/uat-tanka-oh..origin/feat/zoom-v2/main --oneline
第四步：获取文件变更统计
git diff --stat origin/<target-branch>...origin/<source-branch>
# 示例
git diff --stat origin/uat-tanka-oh...origin/feat/zoom-v2/main
第五步：获取具体文件的 diff
# 全量 diff（大 MR 慎用，建议指定文件）
git diff origin/<target-branch>...origin/<source-branch>
# 指定文件 diff（推荐）
git diff origin/<target-branch>...origin/<source-branch> -- src/path/to/file.ts
# 只看特定目录
git diff origin/<target-branch>...origin/<source-branch> -- src/components/
⚠️ 备用：mx_link proxy（本地无仓库时使用）
当本地不存在仓库时，通过 MorphixAI 代理调用 GitLab API。
注意：大型 MR 的 diff 可能因响应体过大返回 400，此时只能使用本地 git。
mx_link:
action: proxy
account_id: <gitlab-account-id>
method: GET
url: https://gitlab.com/api/v4/projects/<project-id>/merge_requests/<mr-iid>/changes
可用的 MR 相关 API：
GET /api/v4/projects/{id}/merge_requests/{iid} — MR 详情GET /api/v4/projects/{id}/merge_requests/{iid}/changes — 文件变更（可能因大小失败）GET /api/v4/projects/{id}/merge_requests/{iid}/discussions — Discussion 线程GET /api/v4/projects/{id}/merge_requests/{iid}/notes — 评论列表POST /api/v4/projects/{id}/merge_requests/{iid}/notes — 发表评论GET /api/v4/projects/{id}/merge_requests/{iid}/approvals — 审批状态
分支命名
feature/JIRA-{ID}-{简短描述} — 新功能fix/JIRA-{ID}-{简短描述} — bug 修复release/v{X.Y.Z} — 发布分支hotfix/v{X.Y.Z}-{描述} — 生产热修复
Commit Message 格式
{Scope}: {action} {description}
- Scope：模块名（SDK、CLI、Gateway、Bot 等）
- Actions：add / update / fix / remove / refactor
- 示例：
SDK: add message retry logic
- 相关改动一个 commit，绝不混杂无关重构
核心操作（mx_gitlab）
查看当前用户
mx_gitlab:
action: get_user
列出项目
mx_gitlab:
action: list_projects
per_page: 10
查看项目详情
mx_gitlab:
action: get_project
project: "12345"
MR 操作
列出 MR：
mx_gitlab:
action: list_merge_requests
project: "12345"
state: "opened"
创建 MR：
mx_gitlab:
action: create_merge_request
project: "12345"
source_branch: "feature/JIRA-123-user-login"
target_branch: "main"
title: "[JIRA-123] 实现用户登录功能"
description: "## 改动\n- 实现 JWT 登录\n\n## 测试\n- 单元测试通过\n\n## 关联\n- JIRA-123"
审批 MR：
mx_gitlab:
action: approve_merge_request
project: "12345"
mr_iid: 42
查看单条 MR 详情（含合并就绪状态）：
mx_gitlab:
action: get_merge_request
project: "12345"
mr_iid: 42
返回关键字段：
detailed_merge_status: mergeable（可合并）/ preparing（准备中，需等待）/ checking（检查中）/ ci_must_pass（CI 未通过）/ not_approved（未获批准）/ discussions_not_resolved（有未解决讨论）has_conflicts: 是否有冲突blocking_discussions_resolved: 阻塞性讨论是否已解决pipeline: 最新 Pipeline 状态
合并前必须先检查状态（重要）：
⚠️ 直接调用 merge_merge_request 而不检查状态会导致 500 错误（MR 未就绪时 GitLab 拒绝合并）
# 正确流程：
1. mx_gitlab: get_merge_request → 确认 detailed_merge_status === "mergeable"
2. 如果是 "preparing" 或 "checking" → 等待后重试 get_merge_request
3. 如果是 "ci_must_pass" → CI 未通过，不能合并
4. 如果是 "not_approved" → 需要审批，先 approve_merge_request
5. 确认 mergeable 后 → mx_gitlab: merge_merge_request
合并 MR：
mx_gitlab:
action: merge_merge_request
project: "12345"
mr_iid: 42
✅ merge_merge_request 会自动检查 detailed_merge_status，若 MR 未就绪会直接返回错误和原因，无需手动 pre-check。
更新 MR（设置 Reviewer / Assignee / 标签等）：
# 先搜索 GitLab 用户 ID
mx_gitlab:
action: search_users
search: "username_or_name"
# 再设置 reviewer（使用搜索结果中的 id 字段）
mx_gitlab:
action: update_merge_request
project: "12345"
mr_iid: 42
reviewer_ids: [12345]
CI/CD 操作
查看 Pipeline：
mx_gitlab:
action: list_pipelines
project: "12345"
per_page: 5
重试失败的 Pipeline：
mx_gitlab:
action: retry_pipeline
project: "12345"
pipeline_id: 67890
Issue 操作
列出 Issue：
mx_gitlab:
action: list_issues
project: "12345"
state: "opened"
创建 Issue：
mx_gitlab:
action: create_issue
project: "12345"
title: "Bug: 登录页面白屏"
description: "## 问题\n在 Safari 下登录页面白屏\n\n## 复现\n1. 打开 Safari\n2. 访问 /login"
labels: ["bug", "frontend"]
分支操作
列出分支：
mx_gitlab:
action: list_branches
project: "12345"
search: "feature/"
MR 创建规范
标题：[JIRA-{ID}] {描述}
描述必须包含：
- 改了什么，为什么改
- 如何测试
- 关联的 Jira Issue 链接
至少指定 1 个 Reviewer。单个 MR 最多 500 行变更。
Code Review 检查清单
Review MR 时，按顺序检查所有项目：
- 分支命名符合规范
- Commit message 清晰且有 scope
- 代码符合团队风格指南
- 有对应的测试用例
- CI pipeline 全绿
- 无未解决的 Discussion
- 无硬编码的 secret 或 token
- 破坏性变更有文档说明
所有项通过才能 approve。评论具体问题时引用行号。
常见工作流
审查指定 MR（完整流程）
1. mx_gitlab: list_merge_requests, project: "<id>", state: "opened"
→ 获取 MR 信息（source_branch, target_branch, mr_iid）
2. nodes.run: find ~/www -maxdepth 4 -type d -name '<repo>'
→ 查找本地仓库路径
3. nodes.run: cd <repo-path> && git fetch origin
→ 更新远端分支数据
4. nodes.run: git log origin/<target>..origin/<source> --oneline
→ 查看 commit 列表
5. nodes.run: git diff --stat origin/<target>...origin/<source>
→ 查看文件变更统计
6. nodes.run: git diff origin/<target>...origin/<source> -- <关键文件>
→ 深入审查关键文件的 diff
7. mx_gitlab: list_pipelines, project: "<id>" → 确认 CI 状态
8. mx_gitlab: approve_merge_request, project: "<id>", mr_iid: <iid>（审查通过后）
查看我的待处理 MR
1. mx_gitlab: get_user → 获取用户名
2. mx_gitlab: list_merge_requests, project: "<id>", state: "opened"
→ 列出 open 状态的 MR
3. mx_gitlab: list_pipelines, project: "<id>" → 检查 CI 状态
创建并合并 Feature MR
1. mx_gitlab: create_merge_request
project: "<id>", source_branch: "feature/xxx", target_branch: "main"
title: "[JIRA-xxx] desc"
2. mx_gitlab: get_merge_request, project: "<id>", mr_iid: <iid>
→ 等待 detailed_merge_status 变为 "mergeable"
(刚创建后状态为 "preparing"，需要等待 GitLab 完成检查)
3. mx_gitlab: list_pipelines, project: "<id>" → 确认 CI 通过
4. mx_gitlab: merge_merge_request, project: "<id>", mr_iid: <iid> → 合并
CI 失败处理
1. mx_gitlab: list_pipelines, project: "<id>", status: "failed"
2. mx_gitlab: retry_pipeline, project: "<id>", pipeline_id: <id>
设置 MR Reviewer（完整流程）
1. mx_gitlab: search_users, search: "reviewer_name"
→ 从结果中找到目标用户的 id（数字）
2. mx_gitlab: update_merge_request
project: "<id>", mr_iid: <iid>, reviewer_ids: [<user_id>]
Pipeline 监控（等待 Pipeline 完成）
⚠️ 心跳（HEARTBEAT）默认间隔 30m，Anthropic setup-token 下为 1h，不适合实时监控。
推荐做法：将监控任务写入 HEARTBEAT.md，心跳触发时自动检查：
## 待监控
- Pipeline #10164 (project: tanka-electron)：等待完成，完成后通知用户
或用户要求"立即检查"时，直接调用：
mx_gitlab: list_pipelines, project: "<id>", per_page: 5
对比 pipeline id 和状态，判断是否完成。
注意事项
project 参数：数字 ID（如 "12345"）或路径（如 "my-group/my-project"），通过 list_projects 或 get_project 获取mr_iid 是 MR 在项目内的序号（非全局 ID），从 list_merge_requests 或 create_merge_request 返回结果中获取account_id 参数通常省略，工具自动检测已链接的 GitLab 账号mx_link proxy 获取 MR diff 可能因响应体过大返回 400，优先使用本地 git
