# gitlink-issue-triage API 参考

> 分拣相关的 gitlink-cli 命令返回字段说明。先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解 envelope `{ok, data, meta}` 与全局参数。

## 前置：ID 解析命令

分拣写入参数（`--label`/`--assignee`/`--priority`）都吃 **ID**，必须先解析。

### `label +list` — 标签（name → id）

```bash
gitlink-cli label +list --format json
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.issue_tags[].id` | int | **标签 ID（写入时传这个）** |
| `data.issue_tags[].name` | string | 标签名称（GitLink 默认为中文：缺陷/功能/疑问/文档/任务…） |
| `data.issue_tags[].color` | string | 颜色（hex） |
| `data.issue_tags[].description` | string | 标签说明 |

### `label +assigners` — 可指派人（login → id）

```bash
gitlink-cli label +assigners --format json
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.assigners[].id` | int | **用户 ID（`--assignee` 传这个）** |
| `data.assigners[].login` | string | 登录名 |
| `data.assigners[].name` | string | 显示名/角色（如「后端组」） |

### `label +priorities` — 优先级（name → id）

```bash
gitlink-cli label +priorities --format json
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.priorities[].id` | int | 优先级 ID（`--priority` 传这个） |
| `data.priorities[].name` | string | 名称（如 高/正常/低） |

### `label +create` — 补建缺失标签（确认后）

```bash
gitlink-cli label +create --name <name> --color <hex_without_#> --format json
```

| 参数 | 说明 |
|------|------|
| `-n, --name` | 标签名称（必填） |
| `-c, --color` | 颜色 hex（不带 #，如 `ff0000`），可选 |

---

## 分拣主体命令

### `issue +list` — 列出 Issue

```bash
gitlink-cli issue +list --state open --format json
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.issues[].number` | int | **Issue 编号（web URL 中的编号，写入用这个）** |
| `data.issues[].id` | int | Issue 内部 ID |
| `data.issues[].name` / `subject` | string | 标题 |
| `data.issues[].tags` | array | 已打标签（**为空 = 未分拣，需处理**） |
| `data.issues[].assigners` | array | 已指派人 |
| `data.issues[].priority` | object | 优先级 `{id, name}` |
| `data.issues[].author` | object | 作者 `{login, name}` |

> ⚠️ `--state` 仅影响统计计数，返回列表可能含所有状态。**幂等筛选**：保留 `tags` 为空的 Issue，跳过已打标签的。

### `issue +view` — 查看详情（语义分析用）

```bash
gitlink-cli issue +view --number <n> --format json
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.issue.number` | int | Issue 编号 |
| `data.issue.subject` | string | 标题 |
| `data.issue.description` | string | **描述（语义分析的主要输入）** |
| `data.issue.status_id` | int | 状态 ID |
| `data.issue.tags` | array | 已打标签（`[{id,name,color}]`，**为空 = 未分拣**） |
| `data.issue.priority` | object | 优先级 |

> 写入参数用 `--number`（web 编号），不是内部 `id`。

### `issue +batch-update` — 批量更新（同标签批量场景）

```bash
gitlink-cli issue +batch-update \
  --numbers <a,b,c> \
  --label <单个id> \
  [--assignee <id>] [--priority <id>] \
  [--dry-run] --format json
```

| 参数 | 说明 |
|------|------|
| `-n, --numbers` | 逗号分隔的 Issue 编号 |
| `-l, --label` | 标签 **ID**；⚠️ **集合式**——把传入的标签集合打到 `--numbers` 里**每一个** Issue，**非按位置对应** |
| `-a, --assignee` | 指派人 **ID** |
| `-m, --milestone` / `-p, --priority` | 里程碑 / 优先级 ID |
| `-s, --state` | open / closed / 数字 status_id |
| `--dry-run` | **预览不写入** |
| `--from` | 从 CSV 读编号（大批量场景） |

> ⚠️ **实测**：`--label a,b,c` 会把 {a,b,c} 全部打到这批每个 Issue（集合式）。因此**仅用于多个 Issue 共用同一(组)标签**；各 Issue 标签不同时改用下方 Raw API。`--dry-run` 输出含 `updates.issue_tag_ids`（扁平数组，印证集合式）。

### `issue +update` — 单个 Issue 更新

```bash
gitlink-cli issue +update --number <n> --assignee <id> --format json
```

| 参数 | 说明 |
|------|------|
| `-n, --number` | Issue 编号 |
| `-l, --label` | ⚠️ **实测不可用**：CLI 发单数 `issue_tag_id` 被平台忽略，标签打不上。打标签改用 Raw API `issue_tag_ids` |
| `-a, --assignee` | 指派人 **ID** |
| `-t, --title` / `-b, --body` | 新标题/描述（更新会自动保留原 subject/description，不会清空） |
| `-s, --state` / `-m, --milestone` / `-p, --priority` | 状态/里程碑/优先级 |

### `issue +comment` — 添加引导评论

```bash
gitlink-cli issue +comment --number <n> --body "<评论内容>" --format json
```

| 参数 | 说明 |
|------|------|
| `-n, --number` | Issue 编号 |
| `-b, --body` | 评论内容（支持 Markdown） |

---

## Raw API 兜底

Shortcut 未覆盖时用 Raw API。**Issue 更新需先 GET 拿到当前 `subject`/`description` 再带上提交**，否则可能清空描述（见 gitlink-shared 已知坑）。

```bash
# 打标签（issue_tag_ids 为标签 ID 数组）
gitlink-cli api PATCH /:owner/:repo/issues/:number --body '{
  "issue_tag_ids": [<tag_id>, ...],
  "subject": "<原标题>",
  "description": "<原描述>"
}'
```

| 字段 | 说明 |
|------|------|
| `issue_tag_ids` | 标签 **ID 数组**（不是名称） |
| `subject` / `description` | 必须回带原值，防止清空 |

## 数据获取最佳实践

1. **始终 `--format json`** 便于解析。
2. 写入参数一律传 **ID**：标签/指派人/优先级都先解析为 ID。
3. **幂等**：`issue +list` 后客户端筛 `labels` 为空的，避免重复分拣。
4. 批量前先 `--dry-run` 预览，核对 `--numbers` 与 `--label`/`--assignee` 位置对应。
