Skills
skills/mercury-api.wepieoa.com/requirement-assistant

requirement-assistant

SKILL.md

需求开发助手 Skill

执行保障

引用: execution-guard

本 Skill 遵循 execution-guard 的执行保障机制，详见该 Skill 文档。

规则与范围

  • 适用场景（统一入口，自动分流）：
    • 简单改配置：仅需修改配置，自动分流到 simple-weconfig-change
    • Bug / 缺陷修复：线上问题、测试反馈的缺陷、紧急修复等
    • 功能需求：描述清晰的功能点
    • 支持单仓库或多仓库协同开发
  • 不适用场景：
    • 需要跨团队协作、长周期迭代的大型项目（建议人工拆解）
  • 默认环境：测试环境优先；生产环境需要明确确认

流程图

flowchart TD
    A[用户输入需求] --> B{需求分类}

    B -->|简单改配置| C[分流到 simple-weconfig-change]
    B -->|一句话需求| D[澄清问题]
    D --> A
    B -->|Bug/功能需求| E[阶段一：分析与确认]

    E --> E1[需求分析 + 确定仓库]
    E1 --> E3[AI 自动生成分支名]
    E3 --> F
    F[输出确认清单] --> G{用户确认 🛑}
    G -->|确认| H[阶段二：自动执行]
    G -->|修改| E

    H --> I[创建/切换分支]
    I --> J[编码实现]
    J --> K[commit + push]
    K --> L[创建 MR]
    L --> L1[自动 Code Review]
    L1 -->|有问题| J
    L1 -->|无问题| M{阶段三：GitLab 审阅 🛑}

    M -->|通过| N[阶段四：自动发布]
    M -->|修改| J

    N --> O[合并到 dev]
    O --> P1[发布服务 + 更新配置]
    P1 --> P2{需要流转工单?}
    P2 -->|是| P3[流转到 server开发 之后]
    P2 -->|否| P4[输出发布计划]
    P3 --> P4
    P4 --> R[完成]

    style B fill:#f9f,stroke:#333
    style C fill:#bbf,stroke:#333
    style G fill:#fbb,stroke:#333
    style M fill:#fbb,stroke:#333
    style P2 fill:#ffc,stroke:#333
    style P3 fill:#bfb,stroke:#333

流程特点：

  • 2 个用户交互点：方案确认、GitLab 代码审阅
  • 飞书工单联动：发布完成后自动流转关联工单到"server开发"之后
  • 确认后 agent 自动执行，无中断
  • 代码审阅在 GitLab MR 页面 进行，不是本地

关键规则

Epic 根目录定位

执行 gitepic 命令前，必须先定位 epic 根目录：

  • 从当前目录往上查找，直到找到包含 epic.repos 文件的目录
  • 该目录即为 epic 根目录，所有 gitepic 命令在此目录下执行
# 查找 epic 根目录
while [ ! -f "epic.repos" ] && [ "$(pwd)" != "/" ]; do cd ..; done

分支确定规则

默认自动新建分支（不询问用户）：

  • AI 自动生成分支名
  • Bug 修复格式：fix-<简述>-<日期>
  • 功能需求格式：feat-<简述>-<日期>
  • 简述：从需求中提取 2-4 个英文单词
  • 日期：YYYYMMDD 格式
  • 示例：fix-null-pointer-crash-20260128、feat-add-login-info-20260128

使用已有分支（仅当用户主动指定时）：

  1. 用户在需求描述中明确提供了分支名
  2. 验证远端分支是否存在（对涉及的每个仓库）： 
    cd repos/<repo>/bare
git fetch origin
git ls-remote --heads origin <branch-name>
  3. 存在 → 继续流程
  4. 不存在 → 提示用户分支名有误，请重新输入

多仓库串行处理

涉及多个仓库时，逐个仓库串行处理：

  • 按依赖顺序修改代码（被依赖的仓库先改）
  • 每个仓库：编码 → git add → git commit，然后切换到下一个仓库
  • 全部完成后统一推送

冲突处理策略

执行 gitepic merge-feat-to-dev 或 gitepic sync-master-to-feat 时可能产生冲突：

  • 禁止自动解决冲突：不要使用 -X theirs、-X ours 或任何自动冲突解决策略
  • 发现冲突后，列出冲突文件，然后立即执行 git merge --abort 回滚
  • 提示用户手动处理冲突，回复示例： 
    合并 <branch-name> 到 dev 时发生冲突，已自动回滚（git merge --abort）。

冲突文件：
- path/to/file1.go
- path/to/file2.go

请手动处理冲突后重新合并：
1. git checkout dev && git pull
2. git merge <branch-name>
3. 解决冲突文件
4. git add <resolved-files> && git commit && git push

部分仓库失败处理

多仓库操作时，如果部分仓库失败：

  • 立即停止后续操作
  • 向用户报告：哪个仓库失败、失败原因、已成功的仓库列表
  • 不自动重试，等待用户指示

核心工作流程

阶段一：分析与确认 🛑

目标：一次性确认所有关键信息，确认后 agent 自动执行

📋 进入阶段一时，必须先创建 Task（注意保存返回的 taskId）：

task1 = TaskCreate({ subject: "[1.1] 需求分类与分流", description: "判断需求类型：简单改配置/Bug修复/功能需求", activeForm: "分类需求中" })
task2 = TaskCreate({ subject: "[1.2] 需求分析", description: "分析需求细节，定位代码位置，确定涉及仓库", activeForm: "分析需求中" })
task3 = TaskCreate({ subject: "[1.3] 分支确定", description: "自动生成分支名（用户主动指定已有分支时验证存在性）", activeForm: "确定分支中" })
task4 = TaskCreate({ subject: "[1.4] 技术方案", description: "生成技术方案，列出改动文件和实现思路", activeForm: "编写方案中" })
task5 = TaskCreate({ subject: "[1.5] 输出确认清单", description: "输出确认清单并等待用户确认", activeForm: "等待确认" })

执行时更新状态（使用保存的 taskId）：

  • 开始执行：TaskUpdate({ taskId: task1.id, status: "in_progress" })
  • 执行完成：TaskUpdate({ taskId: task1.id, status: "completed" })

1.1 需求分类与分流

根据用户输入自动判断需求类型：

简单改配置特征： → 分流到 simple-weconfig-change

  • 提到"配置"、"开关"、"参数"、"文案"、"白名单"、"黑名单"
  • 提到 namespace/key 或类似格式（如 variable/lucky_number）
  • 明确说"不需要改代码"、"只改配置"

一句话需求特征： → 先澄清再继续

  • 描述简短（< 20 字）且缺少具体细节
  • 无法直接判断改动范围
  • 示例："优化一下性能"、"改个东西"

Bug / 缺陷修复特征： → 继续本流程

  • 提到"bug"、"缺陷"、"修复"、"问题"、"报错"、"异常"、"崩溃"
  • 提到"线上问题"、"紧急修复"、"hotfix"
  • 提到"创建修复分支"、"修复分支"
  • 测试反馈的缺陷单、飞书工单链接

功能需求： → 继续本流程

1.2 需求分析

  • Bug 修复：提取错误信息、日志、环境信息，定位代码位置，分析影响范围
  • 功能需求：提取功能点、业务规则，识别涉及模块，判断是否需要配置变更
  • 确定涉及仓库：明确需要修改哪些仓库（为 1.3 分支验证做准备）

1.3 分支确定

默认自动新建分支，不询问用户：

  • AI 根据需求类型自动生成分支名（fix-<简述>-<日期> 或 feat-<简述>-<日期>）
  • 直接进入 1.4 技术方案

用户主动指定已有分支时：

  • 验证远端分支是否存在（对 1.2 确定的每个仓库）
  • 全部存在 → 进入 1.4 技术方案
  • 部分/全部不存在 → 提示用户分支名有误，自动改为新建分支

1.4 技术方案

  • 生成技术方案，说明实现思路
  • 识别需要修改的文件，列出代码改动范围
  • 识别是否需要配置变更、数据库变更
  • Bug 修复需生成回归测试清单和回滚方案

输出需求文档：

# [需求名称]

## 一、需求概述
- 需求类型：Bug 修复 / 功能需求
- 涉及仓库：<repo1>, <repo2>
- 目标区服：<region>
- 分支：<branch-name>

## 二、技术方案
- 改动文件：...
- 实现思路：...
- 配置变更：有/无
- 数据库变更：有/无

1.5 输出确认清单

⚠️ 必须停止并向用户确认以下内容：

## 确认清单

**需求类型**：Bug 修复 / 功能需求
**涉及仓库**：<repo1>, <repo2>, ...
**目标区服**：<region>
**分支**：<branch-name>（新建 / 已有）

**技术方案**：
- 改动文件：...
- 实现思路：...
- 配置变更：有/无
- 数据库变更：有/无

请确认以上信息，确认后将自动执行：创建/切换分支 → 编码 → 提交 commit

用户响应处理：

用户响应 处理方式
"确认" / "可以" / "开始" 进入阶段二
提出修改意见 根据修改内容处理（见下表）

修改意见处理：

修改内容 处理方式
修改分支名 直接采纳新分支名，如是已有分支需重新验证
修改涉及仓库 回到 1.2 重新分析
修改目标区服 直接采纳新区服
修改技术方案 根据用户意见调整方案
全部重来 回到 1.1 重新开始

修改完成后，重新输出确认清单。

用户确认后，进入阶段二。

📋 阶段一完成后，输出精简 Checkpoint：

✅ 方案已确认 | 仓库: <repos> | 分支: <branch> | 区服: <region>
→ 开始执行：创建分支 → 编码 → 提交

阶段二：自动执行（无中断）

用户确认后，以下步骤自动执行，无需中断：

📋 进入阶段二时，必须先创建 Task（保存返回的 taskId，根据仓库数量动态生成）：

单仓库示例：

t1 = TaskCreate({ subject: "[2.1] 定位 epic 根目录", description: "查找包含 epic.repos 的目录", activeForm: "定位目录中" })
t2 = TaskCreate({ subject: "[2.2] 创建/切换功能分支", description: "执行 gitepic feat 创建或切换分支", activeForm: "切换分支中" })
t3 = TaskCreate({ subject: "[2.3] 拉取最新代码", description: "如已有分支，执行 git pull 拉取最新", activeForm: "拉取代码中" })
t4 = TaskCreate({ subject: "[2.4] 生成 VS Code 工作区", description: "执行 gitepic vscode 生成工作区", activeForm: "生成工作区中" })
t5 = TaskCreate({ subject: "[2.5] 编码实现", description: "根据技术方案修改代码", activeForm: "编码中" })
t6 = TaskCreate({ subject: "[2.6] git add", description: "添加修改的文件到暂存区", activeForm: "暂存文件中" })
t7 = TaskCreate({ subject: "[2.7] git commit", description: "提交代码变更", activeForm: "提交中" })
t8 = TaskCreate({ subject: "[2.8] 推送并创建 MR", description: "执行 gitepic push-master 推送并创建 MR", activeForm: "推送中" })
t9 = TaskCreate({ subject: "[2.9] 自动 Code Review", description: "对 feature 分支与 master 的 diff 进行代码审查", activeForm: "Code Review 中" })
t10 = TaskCreate({ subject: "[2.10] 输出审阅信息", description: "输出 MR 链接和 CR 报告", activeForm: "输出信息中" })

多仓库示例（2 个仓库，编码任务可设置依赖关系）：

t1 = TaskCreate({ subject: "[2.1] 定位 epic 根目录", ... })
t2 = TaskCreate({ subject: "[2.2] 创建/切换功能分支", ... })
t3 = TaskCreate({ subject: "[2.3] 拉取最新代码", ... })
t4 = TaskCreate({ subject: "[2.4] 生成 VS Code 工作区", ... })
t5_api = TaskCreate({ subject: "[2.5] 编码 [api_server]", description: "修改 api_server 仓库代码", activeForm: "编码 api_server" })
t5_common = TaskCreate({ subject: "[2.5] 编码 [common]", description: "修改 common 仓库代码", activeForm: "编码 common" })
t6_api = TaskCreate({ subject: "[2.6] 提交 [api_server]", description: "git add + commit api_server", activeForm: "提交 api_server" })
t6_common = TaskCreate({ subject: "[2.6] 提交 [common]", description: "git add + commit common", activeForm: "提交 common" })
t7 = TaskCreate({ subject: "[2.7] 推送并创建 MR", ... })
t8 = TaskCreate({ subject: "[2.8] 自动 Code Review", ... })
t9 = TaskCreate({ subject: "[2.9] 输出审阅信息", ... })

# 设置依赖关系（提交依赖编码完成）
TaskUpdate({ taskId: t6_api.id, addBlockedBy: [t5_api.id] })
TaskUpdate({ taskId: t6_common.id, addBlockedBy: [t5_common.id] })

2.1 创建/切换分支与工作区

1. 定位 epic 根目录

while [ ! -f "epic.repos" ] && [ "$(pwd)" != "/" ]; do cd ..; done

2. 创建或切换功能分支

gitepic feat <branch> --repos=<repo1,repo2,...>

3. 如果是已有分支，拉取最新代码

# 对每个仓库执行
cd repos/<repo>/wt/<branch>
git pull origin <branch>

4. 生成 VS Code 工作区

gitepic vscode <branch> --repos=<repo1,repo2,...>

5. 切换到 worktree 目录

<epic-root>/repos/<repo>/wt/<branch>

⚠️ 禁止在 master worktree 或 dev worktree 或 bare 仓库目录下执行代码修改操作！

2.2 编码实现

  • 基于技术方案修改代码
  • 确保在正确的 worktree 目录下操作
  • 自动进行代码自检（规范、潜在问题）
  • 多仓库时：按依赖顺序逐个仓库修改，每个仓库改完后 git add + commit，再切换到下一个

2.3 Commit 与 Push

对每个仓库逐个执行：

  1. 切换到对应 worktree 目录

    cd <epic-root>/repos/<repo>/wt/<branch>

  2. 执行 git add

    • 只添加自己修改的文件，不要 add 全部文件
    • 使用 git status 查看修改的文件
    • 使用 git add <file-path> 逐个添加修改的文件
    • ⚠️ 禁止：使用 git add . 或 git add -A 添加全部文件

  3. Commit

    • 格式：<type>: <description>
    • type：仅支持（1）feat（2）fix
    • description：用中文说明修改内容
    • 示例：
      • Bug / 缺陷修复：fix: 修复登录空指针异常
      • 功能需求：feat: 新增登录历史记录功能

2.4 推送分支并创建 MR

回到 epic 根目录执行：

gitepic push-master <branch> --repos=<repo1,repo2,...>

获取 MR 链接：

  • gitepic push-master 执行时 glab 会输出 MR 信息
  • 如果未能从输出中获取链接，使用以下命令查询： 
    glab mr list --source-branch <branch> --target-branch master --state opened

2.5 自动 Code Review

使用 code-review skill 对本次变更进行代码审查。

对每个仓库执行 CR：

  • 在对应仓库的 worktree 目录下，对 <branch> 与 master 之间的 diff 进行审查
  • 关注：逻辑错误、安全漏洞、遗漏的边界检查、代码规范问题

CR 结果处理：

  • 发现问题 → 自动修复，重新 git add + commit + push，然后再次 CR（最多重试 2 次）
  • 无问题 → 进入 2.6 输出审阅信息

2.6 输出审阅信息

📋 阶段二完成后，输出精简审阅信息（仅此格式，禁止冗长）：

✅ 代码已提交，请审阅 MR：
- repo1: <MR链接>
- repo2: <MR链接>

变更: <N>个文件 | 自动 CR: 通过 | 审阅通过后回复"通过"

阶段三：GitLab 代码审阅 🛑

⚠️ 必须停止等待用户在 GitLab 上审阅代码

  • 用户在 GitLab MR 页面 审阅代码
  • 如果需要修改，回到阶段二的编码步骤，修改后重新 push
  • 用户审阅通过后，进入阶段四

阶段四：自动发布（无中断）

用户审阅通过后，以下步骤自动执行，无需中断：

📋 进入阶段四时，必须先创建 Task（保存返回的 taskId，根据仓库和服务数量动态生成）：

示例（2 个仓库，2 个服务）：

t1 = TaskCreate({ subject: "[4.1] 合并到 dev", description: "执行 gitepic merge-feat-to-dev 合并分支", activeForm: "合并分支中" })
t2_s1 = TaskCreate({ subject: "[4.2] 发布 [service1]", description: "触发 Jenkins 部署 service1", activeForm: "发布 service1" })
t2_s2 = TaskCreate({ subject: "[4.2] 发布 [service2]", description: "触发 Jenkins 部署 service2", activeForm: "发布 service2" })
t3 = TaskCreate({ subject: "[4.3] 更新配置", description: "如需要，更新测试环境配置", activeForm: "更新配置中" })
t4 = TaskCreate({ subject: "[4.4] 流转飞书工单", description: "如有关联工单，流转到 server开发 之后", activeForm: "流转工单中" })
t5 = TaskCreate({ subject: "[4.5] 输出发布计划", description: "在对话中输出发布计划", activeForm: "生成发布计划" })
t6 = TaskCreate({ subject: "[4.6] 输出最终报告", description: "输出完成报告", activeForm: "生成报告中" })

# 设置依赖关系
TaskUpdate({ taskId: t2_s1.id, addBlockedBy: [t1.id] })      # 发布依赖合并
TaskUpdate({ taskId: t2_s2.id, addBlockedBy: [t2_s1.id] })   # 服务间按依赖顺序
TaskUpdate({ taskId: t4.id, addBlockedBy: [t2_s2.id, t3.id] })  # 工单流转依赖发布和配置完成
TaskUpdate({ taskId: t5.id, addBlockedBy: [t4.id] })            # 发布计划依赖工单流转完成
TaskUpdate({ taskId: t6.id, addBlockedBy: [t5.id] })            # 最终报告等待全部完成

执行顺序说明：

4.1 合并到 dev → 4.2 发布服务 → 4.3 更新配置 → 4.4 流转飞书工单 → 4.5 输出发布计划 → 4.6 输出最终报告

4.1 合并到 dev

gitepic merge-feat-to-dev <branch> --repos=<repo1,repo2,...>
  • 如果发生冲突，禁止自动解决，必须 git merge --abort 回滚并提示用户手动处理（参见「冲突处理策略」）
  • ⚠️ 注意：开发分支从 master 创建，但最终合并到 dev 分支进行测试

推送失败重试机制：

由于其他人可能在你 pull 之后又提交了新代码，导致 push dev 失败。遇到此情况，执行以下重试逻辑（最多重试 3 次）：

# 重试逻辑（伪代码）
for attempt in 1 2 3; do
    # 执行合并推送
    gitepic merge-feat-to-dev <branch> --repos=<repo1,repo2,...>

    if [ 成功 ]; then
        break
    fi

    # 失败则等待 5 秒后重试
    echo "推送失败，等待 5 秒后重试 (第 $attempt 次)..."
    sleep 5

    # 重新拉取 dev 最新代码
    for repo in <repos>; do
        cd repos/$repo/wt/dev
        git pull origin dev
    done
done

如果 3 次重试后仍失败，停止并报告错误给用户。

4.2 测试环境发布

确定发布顺序（多仓库场景）：

  • 分析仓库间的依赖关系（如 common 被 api_server 依赖）
  • 被依赖的仓库先发布，依赖方后发布

执行发布：

  • 确定服务名：查看代码修改的文件路径，通过 main 函数定位到最终的服务名
  • 使用阶段一确认的区服参数
  • 使用 jenkins-deployer skill 触发测试环境部署： 
    python3 ~/.codex/skills/jenkins-deployer/scripts/jenkins_deploy.py --service <service_name> --region <region>
  • 按顺序逐个发布，确认上一个发布成功后再发布下一个

4.3 更新配置

如果涉及配置变更，使用 simple-weconfig-change 或 weconfig-skill 更新测试环境配置。

4.4 流转飞书工单（可选）

  • 用户输入中包含飞书项目链接（project.feishu.cn）→ 尝试流转
  • 无飞书项目链接 → 直接跳过

执行流转：

python ~/.codex/skills/feishu-project-tool/scripts/schedule_cli.py flow "<工单URL>" --to "server开发"

说明：

  • 流转失败不阻断整体流程，仅输出警告

4.5 输出发布计划

根据本次需求的实际执行情况，在对话中直接输出发布计划。 使用 publish-plan-writer skill 的格式，按需填写，不需要的内容直接省略：

## 发布计划

### MR
- repo1: <MR链接>
- repo2: <MR链接>

### 服务发布
1. 发布 <service1> 到 <region>
2. 发布 <service2> 到 <region>

### 配置变更
- namespace/key: old_value → new_value

### 验证步骤
1. 验证 xxx 功能正常
2. 检查日志无报错

4.6 输出最终报告

📋 阶段四完成后，输出精简完成报告（仅此格式，禁止冗长）：

✅ 完成
- MR: <url1>, <url2>
- 测试环境: 已发布 (<region>)

→ 请验证测试环境后进行正式发布

异常处理

当步骤执行失败时：

  1. 保持当前 Task 状态为 in_progress（不标记为 completed）
  2. 输出精简异常报告：
⚠️ 失败: [阶段X.Y] <步骤>
原因: <一句话错误信息>
→ 需要: <用户决策/自动重试>
  1. 可创建阻塞任务记录问题：
TaskCreate({ subject: "解决: <问题简述>", description: "<详细问题描述>", activeForm: "等待处理" })
TaskUpdate({ taskId: "<当前任务id>", addBlockedBy: ["<问题任务id>"] })
Installs
1
Source
mercury-api.wep…ssistant
First Seen
Apr 16, 2026