GitLab Issue 协作创建

引导开发人员明确 Issue 内容，自动推断标签，通过 API 创建。

GitLab 配置

Token 检查（步骤 0）

每次开始工作前，使用 pwsh 7 会话（默认 UTF-8）检查 $env:GITLAB_TOKEN 是否已设置：

if ($env:GITLAB_TOKEN) { 'Token exists' } else { 'Token not set' }

⚠️ 必须使用 pwsh 7。如果通过外层 shell 调用，使用 pwsh -NoProfile -Command 并用单引号包住脚本，避免 $env: 被外层 shell 展开。

• 已设置（输出 Token exists）→ 直接进入步骤 1
• 未设置 → 引导用户创建并配置：

1. 告诉用户：当前未配置 GitLab Token，需要创建一个才能操作 Issue
2. 引导用户打开 http://gitlab.roboticplus.com:2022/-/profile/personal_access_tokens，创建一个 Personal Access Token，勾选 api 权限
3. 让用户在终端执行以下命令设置环境变量（永久生效）：

   # 在 pwsh 7 profile 中持久化
   Add-Content -Path $PROFILE -Value "`n`$env:GITLAB_TOKEN = '<用户粘贴的token>'"
   $env:GITLAB_TOKEN = '<用户粘贴的token>'

4. 或者让用户在 Claude Code 中直接输入 ! $env:GITLAB_TOKEN = '<token>' 来临时设置
5. 设置完成后继续步骤 1

注意：不要自己生成或猜测 Token 值，必须由用户提供。

工作流程

步骤 1：理解意图

从用户的描述中提取：

• 类型：根据语义自动判断
• 初步内容：问题/需求的核心描述

类型判断规则：

步骤 2：引导补充内容

根据类型，引导用户补充关键信息（用自然对话方式，不要一次性抛出所有问题）。

类型::缺陷

引导获取（按顺序，已有信息跳过）：

1. 问题现象：具体表现是什么？
2. 复现步骤：怎么触发这个问题？
3. 期望行为：应该是什么样子？
4. 影响范围：哪些场景受影响？现场/研发？
5. 环境信息：分支、工件版本（可选）

生成正文格式：

## 问题现象

{描述}

## 复现步骤

1. {步骤1}
2. {步骤2}

## 期望行为

{描述}

## 实际行为

{描述}

## 影响范围

{描述}

类型::功能

引导获取：

1. 需求背景：为什么要做？谁提出？
2. 功能描述：具体要实现什么？怎么使用？
3. 验收标准：做到什么程度算完成？

生成正文格式：

## 需求背景

{描述}

## 功能描述

{描述}

## 验收标准

- [ ] {标准1}
- [ ] {标准2}

类型::优化 / 类型::重构

引导获取：

1. 现状：当前有什么问题？
2. 目标：改进后达到什么效果？
3. 影响范围：涉及哪些模块？需要注意什么？

步骤 3：推断模块

从用户描述中匹配关键词，自动推断模块标签：

如果无法推断，用 AskUserQuestion 让用户从列表选择。

步骤 4：确认并创建

向用户展示完整的 Issue 摘要：

📋 Issue 预览
━━━━━━━━━━━━━━━━━━
标题：{标题}
类型：{类型}
优先级：{优先级}
模块：{模块}
━━━━━━━━━━━━━━━━━━
{正文预览}

用户确认后，通过 API 创建：

$Headers = @{ "PRIVATE-TOKEN" = $Token; "Content-Type" = "application/json" }
$Body = @{
    title = "{标题}"
    description = "{正文}"
    labels = "类型::xxx,优先级::xxx,模块::xxx,阶段::待办"
} | ConvertTo-Json -Compress
Invoke-RestMethod -Uri "$ApiBase/issues" -Method Post -Headers $Headers -ContentType "application/json" -Body $Body

创建成功后返回 Issue 链接：http://gitlab.roboticplus.com:2022/robimweld/weldone/-/issues/{iid}

步骤 5：上传附件（可选）

用户可能要求上传截图、视频等附件到 Issue。

上传流程：先调 POST $ApiBase/uploads 上传文件拿 markdown 引用，再调 POST $ApiBase/issues/{iid}/notes 发布为评论。

关键约束：

• 中文文件名必须先 cp 为 ASCII 名再上传，否则 GitLab API 返回 Bad Request
• 上传接口返回 JSON，取 markdown 字段放入评论 body 即可在 Issue 中展示

规则

1. 标签必打齐：每个 Issue 必须有 类型 + 优先级 + 模块 + 阶段，四类标签缺一不可
2. 创建前必须获取已有标签：每次创建 Issue 前，必须先调用 GET /projects/:id/labels?per_page=100 获取项目已有标签列表，只从中选择。绝不允许使用列表中不存在的标签——GitLab API 会自动创建新标签，这是错误行为。如果已有标签中没有合适的，必须先向用户确认
3. 优先级默认：如果用户未指定，缺陷默认 优先级::P1 高，功能/优化/重构默认 优先级::P2 中，但必须告知用户
4. 对话优先：用自然对话引导，不要一次性列出所有问题让用户填表
5. 信息充分才创建：核心信息（现象/需求+模块）不完整时主动追问，不要创建空泛的 Issue
6. 中文标题：标题用中文，简洁概括核心内容，不超过 50 字
7. 不重复创建：创建前搜索是否已有类似 Issue，避免重复
8. 不写代码级分析：Issue 正文只记录问题现象、复现步骤、期望/实际行为等用户可感知的信息。不要在正文中写入原因分析、代码定位、修复方案等内容——这些属于开发过程，不应由 Issue 创建时自动生成