forked from Gitlink/gitlink-cli
144 lines
6.1 KiB
Markdown
144 lines
6.1 KiB
Markdown
---
|
||
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` |
|