# ai-workflow

**Repository Path**: tony_always/ai-workflow

## Basic Information

- **Project Name**: ai-workflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-workflow

`ai-workflow` 是给 Codex 使用的个人工作流助手，用于处理 GitLab MR review、钉钉通知、review 通过后自动合并，以及按需触发 Jenkins 发布。

## 常用口令

在 Codex 中输入：

```text
cr "<MR_URL>"
```

含义：让 Codex 对 MR 做 code review。  
如果 Codex review 通过，会立即合并 MR；如果 review 不通过，会发送钉钉 review 结果给研发，并且不会合并。

底层 CLI 等价入口：

```powershell
python -m ai_workflow cr "<MR_URL>"
```

MR 已经由 `cr` 合并后，在 Codex 中输入：

```text
deploy
```

## CR 结果回放/对比

钉钉机器人执行 `CR <MR_URL>` 后，会将每次审查结果追加写入本地文件：

```text
data/review_history/reviews.jsonl
```

这个文件只保存审查元信息、结论、原因、Graph 摘要和 digest，不保存完整 diff、完整 Graph 原始上下文或敏感配置。

可用命令：

```powershell
python -m ai_workflow review-latest "<MR_URL>"
python -m ai_workflow review-history "<MR_URL>"
python -m ai_workflow review-compare "<MR_URL>"
```

- `review-latest`：查看某个 MR 最近一次 CR 记录。
- `review-history`：查看某个 MR 的所有本地 CR 记录。
- `review-compare`：对比某个 MR 最近两次 CR 记录，重点展示最终结论、语义原因、merge 状态等变化。

重复 CR 规则：

- 如果同一个 MR 的 source/head sha 没有变化，并且上次 CR 结果是 `NEEDS_ATTENTION` 或 `BLOCKED`，机器人会直接沿用上次结果，不再重复调用 Code Review Graph / Codex，也不会 merge。
- 如果 MR 已经是 `merged` 状态，第一次仍会调用 Code Review Graph / Codex 做代码审查并写入历史，但会跳过自动 merge，不会把 GitLab merge 失败当成 Review 原因。
- 如果同一个已 `merged` MR 的 source/head sha 没有变化，并且本地已经有 `merged` 状态下的 CR 历史，机器人会沿用上次结果，不再重复调用 Code Review Graph / Codex。
- 如果确实需要强制重新审查，可在钉钉群使用：

```text
@机器人 CR --force <GitLab MR 链接>
```

## 钉钉机器人自动启动

推荐使用 Windows 计划任务启动本地钉钉机器人：

```powershell
powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File "D:\ai-workflow\scripts\install-dingtalk-bot-task.ps1"
```

安装后会注册任务：

```text
ai-workflow-dingtalk-bot
```

任务行为：

- 当前 Windows 用户登录时自动启动。
- 运行 `D:\ai-workflow\scripts\start-dingtalk-bot.ps1`。
- 使用隐藏窗口启动，不需要桌面上长期挂着 cmd/PowerShell 控制台。
- bot 异常退出后由任务计划程序按 1 分钟间隔重试。
- 旧的 Startup 文件夹启动项应停用，避免重复启动多个 bot 进程。

常用检查命令：

```powershell
Get-ScheduledTask -TaskName "ai-workflow-dingtalk-bot"
Get-ScheduledTaskInfo -TaskName "ai-workflow-dingtalk-bot"
Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like "*ai_workflow trace-bot*" }
```

日志文件：

```text
D:\ai-workflow\logs\dingtalk-stream-bot.log
```

## 钉钉机器人并发处理

`trace-bot` 内置任务队列，避免多人同时 @ 机器人时出现重复处理或任务互相覆盖。

- Stream 回调会先 ACK，再进入本地任务队列处理，避免钉钉重复重投导致同一条消息被执行多次。
- 使用 DingTalk `messageId` 做短期去重；同一个回调重复到达时只处理一次。
- CR、merge、deploy 会按 MR 链接做互斥；同一个 MR 的任务正在处理时，新的同 MR 任务会收到“任务已在处理中”提示。
- 不同 MR 或不同 Trace ID 可以由多个 worker 并发处理。
- worker 内异常会回复“任务执行失败”，并写入 `logs\dingtalk-stream-bot.log`，不会让任务静默消失。

含义：触发当前已合并 MR 对应项目的 Jenkins 发布，并发送钉钉通知；`deploy` 不再执行 merge。

底层 CLI 等价入口：

```powershell
python -m ai_workflow deploy "<MR_URL>" --author gitlab_author
```

## 通知规则

- Review PASS：立即合并 MR，不发送 review 结果到钉钉。
- Review NEEDS_ATTENTION / BLOCKED：发送 review 结果到钉钉，并 @ 对应研发，不合并。
- Jenkins 构建开始：通知对应研发。
- Jenkins 构建成功：`frontend/dms-system` 通知所有配置的测试人员；其他后端项目通知对应研发。
- Jenkins 构建失败、超时或中止：通知对应研发。

## CLI 命令

```powershell
python -m ai_workflow cr "<MR_URL>"
python -m ai_workflow notify-review --mr-url "<MR_URL>" --status NEEDS_ATTENTION --message-file review.md --author gitlab_author
python -m ai_workflow merge "<MR_URL>"
python -m ai_workflow deploy "<MR_URL>" --author gitlab_author
python -m ai_workflow trace-bot
```

兼容命令：

```powershell
python -m ai_workflow inspect "<MR_URL>"
python -m ai_workflow merge-and-deploy "<MR_URL>" --author gitlab_author
python -m ai_workflow deploy-only "<MR_URL>"
python -m ai_workflow run "<MR_URL>"
```

注意：`deploy` 现在表示“只发布并通知”，不会合并 MR。`merge-and-deploy` 仅保留为旧版“合并并发布”的兼容入口。

## 配置

敏感信息通过环境变量或本地 `.env` 文件提供，`.env` 不提交到仓库。

```text
GITLAB_BASE_URL=https://gitlab.example.com
GITLAB_TOKEN=xxx
JENKINS_BASE_URL=https://jenkins.example.com
JENKINS_USER=xxx
JENKINS_TOKEN=xxx
DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxx
DINGTALK_WEBHOOK_SECRET=SECxxx
DINGTALK_APP_KEY=xxx
DINGTALK_APP_SECRET=xxx
ELK_BASE_URL=https://elk.example.com
ELK_USERNAME=xxx
ELK_PASSWORD=xxx
ELK_INDEX_PATTERN=logs-*
ELK_ENABLED_ENVIRONMENTS=test,pre
ELK_TEST_INDEX_PATTERN=log-kafka-f-dms2-backend-api-test*
ELK_DEV_INDEX_PATTERN=log-kafka-f-dms2-backend-api-dev-*
ELK_PRE_INDEX_PATTERN=log-kafka-f-dms2-backend-api-pre*
```

项目到 Jenkins Job 的映射放在 `config/projects.yml`。

Trace 诊断还可以在项目配置中定义 `service_names` 和 `environment_branches`。源码上下文会从 GitLab 远程分支读取，不依赖本地文件。默认分支映射为 `test -> test`、`pre -> pre`、`prod -> main`。

GitLab author 到钉钉研发用户的映射放在 `config/review_users.yml`。

测试人员通知映射放在 `config/notify_users.yml`，目前仅用于 `frontend/dms-system` 构建成功通知。

## Trace Bot

`trace-bot` 会运行本地钉钉 Stream 机器人监听器。当群里有人 @ 内部应用机器人并发送 trace id 时，机器人会查询 ES，根据 service 匹配项目，从对应环境的 GitLab 远程分支读取源码上下文，并回复 markdown 诊断结果。

### Trace ID 智能诊断

在钉钉群里 @ 机器人，并发送 trace id：

```text
@机器人 prod 095b52f6738d4f87969539e76386f200.414.17806308837087247
```

消息可以带环境，例如 `prod <trace_id>`、`pre <trace_id>`、`test <trace_id>`、`dev <trace_id>`。如果没有指定环境，机器人会按配置顺序搜索。

Trace bot 不包含负责人或研发 @ 字段，默认由群成员共同处理配置项目的问题。

### MR Review

在钉钉群里 @ 机器人，并发送 CR 指令和一个或多个 GitLab MR 链接：

```text
@机器人 CR <GitLab MR 链接>
@机器人 CR <GitLab MR 链接1> <GitLab MR 链接2>
```

机器人会逐个 review MR：

- 每个 MR 会独立处理。
- 处理完成后会通知对应研发。
- 多个 MR 混合提交时，一个 MR 的结果不会影响其他 MR。

### MR Merge

在钉钉群里 @ 机器人，并发送 merge 指令和 GitLab MR 链接：

```text
@机器人 merge <GitLab MR 链接>
```

机器人会直接调用 GitLab merge API，仅执行 merge，不进行 CR，不触发 Jenkins 发布。
该指令仅高伟东可用；其他用户触发时，机器人会回复“MR Merge 权限不足”。

### MR 发布

在钉钉群里 @ 机器人，并发送发布指令和 GitLab MR 链接：

```text
@机器人 发布 <GitLab MR 链接>
@机器人 deploy <GitLab MR 链接>
```

机器人会校验 MR 链接所属项目是否存在于 `config/projects.yml`。校验通过后，机器人会触发该项目配置的 Jenkins 构建，并在构建开始、构建成功或构建失败时发送钉钉通知。

发布权限按项目范围控制：高伟东可发布全部项目；谢信聪、樊炜贤可发布后端项目；梁伟岸、吴冠禧仅可发布前端项目；黄榕杰可发布 `backend/tiktok-access`、`caiwu/support`、`backend/instagram-access`、`backend/dms-marketing`、`backend/dms-module-kol`。不在授权范围内的用户触发发布时，机器人会回复“MR 发布权限不足”，不会触发 Jenkins。

如果指令缺少 MR 链接或 MR 链接格式不正确，机器人会直接回复“MR 发布指令不符合要求”，不会触发 Jenkins。

### 不匹配指令

当群聊用户 @ 机器人，但消息既不是 Trace ID 诊断，也不是合法 MR Review / MR 发布指令时，机器人会回复“KOL数字员工 可支持功能”，提示当前支持的能力和示例。

## 异常处理

如果 `deploy` 执行超时，不要直接重跑。先检查：

1. MR 是否已经由 `cr` 合并。
2. Jenkins 是否已经触发新构建。
3. 最近构建是否仍在 building。
4. 如果构建成功但通知缺失，`frontend/dms-system` 补发测试通知，其他后端项目补发研发通知。
5. 如果构建失败，通知研发。
6. 只有确认 Jenkins 未触发时，才考虑重新触发。

## Skill

Codex Skill 已安装在：

```text
C:\Users\Administrator\.codex\skills\gitlab-mr-release-workflow
```

后续新会话可以继续使用：

```text
cr "<MR_URL>"
deploy
```