---
name: gitlink-issue
version: 3.0.0
description: "Issue 全生命周期管理：创建/查看/更新/关闭/重开 Issue、添加评论、标签操作（添加/移除/查看）、批量操作（创建/关闭/标签/状态/优先级/负责人）。当用户需要操作 GitLink Issue 时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli issue --help"
---

# gitlink-issue（Issue 操作）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。

## Shortcuts

### 查询

| Shortcut | 说明 | 需要认证 |
|----------|------|----------|
| `issue +list` | Issue 列表（支持 `--state open/closed`、`--limit`、`--page`） | 否（公开项目） |
| `issue +view` | Issue 详情（含 description、状态、优先级等） | 否（公开项目） |
| `issue +label-list` | 查看 Issue 上的标签 | 否（公开项目） |

### 单个操作

| Shortcut | 说明 | 需要认证 |
|----------|------|----------|
| `issue +create` | 创建 Issue（`--title` + `--body`） | 是 |
| `issue +update` | 更新 Issue 标题/描述 | 是 |
| `issue +close` | 关闭 Issue | 是 |
| `issue +reopen` | 重新打开已关闭的 Issue | 是 |
| `issue +comment` | 添加评论 | 是 |
| `issue +label-add` | 添加标签（⚠️ API 可能 404，建议用 `+batch-label`） | 是 |
| `issue +label-remove` | 移除标签 | 是 |

### 批量操作

| Shortcut | 说明 | 支持 dry-run |
|----------|------|-------------|
| `issue +batch-create` | 批量创建 Issue（`--titles` 逗号分隔 或 `--from CSV`） | ✅ |
| `issue +batch-close` | 批量关闭 Issue | ✅ |
| `issue +batch-label` | 批量修改标签：bug, feature, support, doc, test, duplicate, question | ✅ |
| `issue +batch-status` | 批量修改状态：new, in-progress, resolved, closed, rejected | ✅ |
| `issue +batch-priority` | 批量修改优先级：low, normal, high, urgent | ✅ |
| `issue +batch-assign` | 批量修改负责人（`--assignee` 登录名或用户 ID） | ✅ |

> 批量操作均支持 `--numbers 1,2,3` 或 `--from file.csv` 指定目标 Issue。

## 使用示例

```bash
# === 查询 ===
# 列出 Issue
gitlink-cli issue +list --owner Gitlink --repo forgeplus --state open
# 分页拉取
gitlink-cli issue +list --owner Gitlink --repo forgeplus --state open --limit 20 --page 2
# 查看详情（使用网页 URL 中的 Issue 编号）
gitlink-cli issue +view --owner Gitlink --repo forgeplus --number 4

# === 单个操作 ===
# 创建 Issue
gitlink-cli issue +create --owner myuser --repo myrepo --title "Bug: 登录失败" --body "复现步骤：..."
# 更新 Issue
gitlink-cli issue +update --number 4 --title "新标题" --body "更新描述"
# 关闭 / 重开
gitlink-cli issue +close --number 4
gitlink-cli issue +reopen --number 4
# 添加评论
gitlink-cli issue +comment --number 4 --body "已修复，请验证"

# === 批量操作 ===
# 批量创建
gitlink-cli issue +batch-create --titles "修复登录Bug,新增导出功能,优化首页加载"
# 批量关闭（先 dry-run 预览）
gitlink-cli issue +batch-close --numbers 1,2,3 --dry-run
gitlink-cli issue +batch-close --numbers 1,2,3
# 批量打标签
gitlink-cli issue +batch-label --label duplicate --numbers 3,4
# 批量改状态
gitlink-cli issue +batch-status --state resolved --numbers 1,2,3
# 批量改优先级
gitlink-cli issue +batch-priority --priority high --numbers 5,6
# 批量分配
gitlink-cli issue +batch-assign --assignee zzx-coder --numbers 7,8
```

## Raw API 补充

```bash
# 获取 Issue 评论列表（使用 v1 API，按 issue number 查询）
gitlink-cli api GET /v1/:owner/:repo/issues/:number/journals

# 批量更新 Issue（仍使用旧版 API，需传数据库 ID）
gitlink-cli api POST /:owner/:repo/issues/series_update --body '{"ids":[1,2,3],"status_id":"closed"}'
```

## GitLink Issue 字段映射

| gitlink-cli 参数 | GitLink API 字段 | 说明 |
|------------------|-----------------|------|
| `--number` / `-n` | `project_issues_index` | Issue 编号（网页 URL 中的序号） |
| `--title` | `subject` | Issue 标题 |
| `--body` | `description` | Issue 描述 |
| `--assignee` | `assigned_to_id` | 指派人 ID |
| `--milestone` | `fixed_version_id` | 里程碑 ID |
| `--state` | `status_id` | 状态（open=1，closed=5，也可直接传数字 ID） |

## API 注意事项

- **Issue 编号（`--number`）是网页 URL 中看到的序号**（如 `issues/4` 中的 `4`），不是数据库内部 ID
- **批量操作使用 `--numbers`，同样传网页 URL 中的 Issue 编号**，不是数据库内部 ID
- Issue 操作使用 v1 API（`/api/v1/`），支持按 Issue 编号查询和操作
- **创建 Issue 时 CLI 会自动设置 `status_id: 1`（新增）和 `priority_id: 2`（正常）**
- **更新/关闭 Issue 时必须保留当前 `subject` 和 `description`**，即使只修改状态（CLI 会先读取当前 Issue 并自动带回）
- v1 API 写操作必须使用 `access_token`（非 `token`）认证，CLI 已自动处理
- **`issue +label-add` / `+label-remove` / `+label-list` 的 labels API（`POST /v1/.../issues/{N}/labels`）可能返回 404**。打标签请优先使用 `issue +batch-label`，它走 `updateIssueField` 而非 labels API

## Issue 状态映射（status_id）

| status_id | 名称 | `+batch-status --state` 对应值 |
|-----------|------|-------------------------------|
| 1 | 新增 | `new` |
| 2 | 正在解决 | `in-progress` |
| 3 | 已解决 | `resolved` |
| 5 | 关闭 | `closed` |
| 6 | 已拒绝 | `rejected` |

## Issue 标签映射（tracker_id）

| 标签 | `+batch-label --label` 对应值 |
|------|------------------------------|
| Bug | `bug` |
| 功能 | `feature` |
| 支持 | `support` |
| 文档 | `doc` |
| 测试 | `test` |
| 重复 | `duplicate` |
| 问题 | `question` |
