docs(skills): add safe batch issue maintenance workflow #13
|
|
@ -0,0 +1,56 @@
|
|||
# Safe Batch Issue Maintenance Example（安全批量 Issue 维护示例）
|
||||
|
||||
本示例展示人类用户或 AI Agent 如何通过 dry-run 确认流程，安全地批量关闭 GitLink Issues。
|
||||
|
||||
> 依赖说明：本示例依赖 PR [#12](https://gitlink.org.cn/Gitlink/gitlink-cli/pulls/12) 中新增的 `gitlink-cli issue +batch-close` 命令，或后续已经包含该命令的版本。
|
||||
|
||||
## 场景
|
||||
|
||||
维护者希望在确认批量计划后，关闭 stale、duplicate 或 already resolved 的 Issues。
|
||||
|
||||
## 文件
|
||||
|
||||
- `issues.csv`：示例 Issue 编号输入文件。
|
||||
|
||||
## Step 1：先使用 dry-run 预览
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner Gitlink \
|
||||
--repo forgeplus \
|
||||
--from issues.csv \
|
||||
--dry-run \
|
||||
--format json
|
||||
```
|
||||
|
||||
预期行为：
|
||||
|
||||
- 不修改任何 Issue 状态。
|
||||
- 输出结构化汇总结果。
|
||||
- Agent 必须向用户展示结果并请求确认。
|
||||
|
||||
## Step 2：用户确认后再执行
|
||||
|
||||
只有在用户明确确认 dry-run 结果后，才能执行真实关闭：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner Gitlink \
|
||||
--repo forgeplus \
|
||||
--from issues.csv \
|
||||
--format json
|
||||
```
|
||||
|
||||
## Agent 检查清单
|
||||
|
||||
- [ ] 确认 `owner/repo`。
|
||||
- [ ] 确认 Issue 编号或 CSV 来源。
|
||||
- [ ] 先执行 `--dry-run`。
|
||||
- [ ] 展示计划关闭的 Issue 编号和汇总。
|
||||
- [ ] 等待用户明确确认。
|
||||
- [ ] 用户确认后，才执行不带 `--dry-run` 的真实命令。
|
||||
- [ ] 报告最终成功/失败数量。
|
||||
|
||||
## 注意事项
|
||||
|
||||
`issues.csv` 中的编号是占位示例。对真实仓库执行前，请替换为真实 Issue 编号。
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
number,reason
|
||||
101,stale
|
||||
102,duplicate
|
||||
103,resolved
|
||||
|
|
|
@ -109,7 +109,8 @@ skills/
|
|||
├── gitlink-pm/ # 项目管理
|
||||
│ └── SKILL.md # PM 操作指南
|
||||
└── gitlink-workflow/ # AI 自动化工作流
|
||||
└── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes）
|
||||
├── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes）
|
||||
└── references/ # 工作流详细参考（含安全批量 Issue 维护）
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -136,7 +137,7 @@ skills/
|
|||
| **gitlink-org** | 组织管理 | `org +list`, `org +info`, `org +members` |
|
||||
| **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` |
|
||||
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
|
||||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||||
| **gitlink-workflow** | AI 工作流 | Issue 分类、安全批量 Issue 维护、PR Review、Release Notes |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -173,6 +174,19 @@ gitlink-cli issue +close -i 123
|
|||
|
||||
详见: [gitlink-issue/examples/issue-workflow.md](gitlink-issue/examples/issue-workflow.md)
|
||||
|
||||
|
||||
### 场景 2b：安全批量 Issue 维护
|
||||
|
||||
```bash
|
||||
# Agent 必须先 dry-run，展示计划，不修改数据
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 101,102,103 --dry-run --format json
|
||||
|
||||
# 用户明确确认后，才执行真实关闭
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 101,102,103 --format json
|
||||
```
|
||||
|
||||
详见: [gitlink-workflow/references/safe-batch-issue-maintenance.md](gitlink-workflow/references/safe-batch-issue-maintenance.md)
|
||||
|
||||
### 场景 3：管理分支和发布
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-workflow
|
||||
version: 1.0.0
|
||||
description: "AI 自动化工作流：Issue 分类、PR Review、Release Notes 生成、仓库初始化、Sprint 报告等。当用户需要 AI 自动化 GitLink 操作时触发。"
|
||||
description: "AI 自动化工作流：Issue 分类、安全批量 Issue 维护、PR Review、Release Notes 生成、仓库初始化、Sprint 报告等。当用户需要 AI 自动化 GitLink 操作时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -101,9 +101,29 @@ gitlink-cli pr +list --state merged --format json
|
|||
gitlink-cli api GET /:owner/:repo/activity --format json
|
||||
```
|
||||
|
||||
## 工作流 6：Safe Batch Issue Maintenance（安全批量 Issue 维护）
|
||||
|
||||
**场景**：安全批量关闭 stale、duplicate 或 resolved Issues。
|
||||
|
||||
**核心规则**：Agent 必须先执行 `--dry-run`，展示计划并等待用户明确确认后，才可以执行真实关闭。
|
||||
|
||||
```bash
|
||||
# 1. 预览批量关闭，不修改数据
|
||||
gitlink-cli issue +batch-close --owner <owner> --repo <repo> --numbers 101,102,103 --dry-run --format json
|
||||
|
||||
# 2. 用户确认后，执行真实关闭
|
||||
gitlink-cli issue +batch-close --owner <owner> --repo <repo> --numbers 101,102,103 --format json
|
||||
|
||||
# CSV 输入方式
|
||||
gitlink-cli issue +batch-close --owner <owner> --repo <repo> --from issues.csv --dry-run --format json
|
||||
```
|
||||
|
||||
详细流程见：[Safe Batch Issue Maintenance Workflow](references/safe-batch-issue-maintenance.md)。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 所有工作流命令使用 `--format json` 以便解析输出
|
||||
- 写入操作前确认用户意图
|
||||
- 批量 Issue 写操作必须先执行 `--dry-run` 并等待用户确认
|
||||
- 批量操作建议先用小范围测试
|
||||
- 保存工作流执行结果以便回溯
|
||||
|
|
|
|||
|
|
@ -0,0 +1,212 @@
|
|||
# Safe Batch Issue Maintenance Workflow（安全批量 Issue 维护工作流）
|
||||
|
||||
> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数、安全规则和写操作确认要求。
|
||||
|
||||
本工作流用于指导 AI Agent 安全地批量关闭 stale、duplicate 或 resolved 状态的 GitLink Issues，底层命令为 `gitlink-cli issue +batch-close`。
|
||||
|
||||
> 依赖说明：本工作流依赖 PR [#12](https://gitlink.org.cn/Gitlink/gitlink-cli/pulls/12) 中新增的 `gitlink-cli issue +batch-close` 命令，或后续已经包含该命令的版本。
|
||||
|
||||
## 适用场景
|
||||
|
||||
当用户提出以下需求时，Agent 可以使用本工作流：
|
||||
|
||||
- 批量关闭 stale / inactive Issues
|
||||
- 批量关闭 duplicate Issues
|
||||
- 批量关闭已经修复或已完成的 Issues
|
||||
- 根据 CSV、表格、脚本输出批量处理 Issues
|
||||
- 在 Release / Sprint 收尾时批量关闭 Issues
|
||||
|
||||
## 安全合约
|
||||
|
||||
批量 Issue 维护属于写操作。Agent 必须遵守以下安全合约：
|
||||
|
||||
1. 明确目标仓库，并向用户说明 `--owner` 和 `--repo`。
|
||||
2. 明确 Issue 编号来源：`--numbers` 或 `--from <csv>`。
|
||||
3. 必须先执行 `gitlink-cli issue +batch-close ... --dry-run --format json`。
|
||||
4. 必须向用户展示 dry-run 汇总，包括 `total`、`succeeded`、`failed` 和计划处理的 Issue 编号。
|
||||
5. 必须等待用户明确确认后，才能去掉 `--dry-run`。
|
||||
6. 只有在用户确认后，才能执行真实批量关闭命令。
|
||||
7. 执行后必须报告最终汇总和失败项。
|
||||
|
||||
> [!CAUTION]
|
||||
> Agent 不得在未执行 dry-run、未获得用户明确确认的情况下直接执行真实批量关闭。
|
||||
|
||||
## 工作流步骤
|
||||
|
||||
### Step 1：确认目标仓库
|
||||
|
||||
如果当前目录是 GitLink 仓库，owner/repo 可以自动解析。否则应显式指定：
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
Agent 需要向用户说明即将操作的仓库，例如：
|
||||
|
||||
```text
|
||||
目标仓库：<owner>/<repo>
|
||||
```
|
||||
|
||||
### Step 2：准备 Issue 输入
|
||||
|
||||
可以直接使用 Issue 编号列表：
|
||||
|
||||
```bash
|
||||
ISSUE_NUMBERS="101,102,103"
|
||||
```
|
||||
|
||||
也可以准备 CSV 文件：
|
||||
|
||||
```csv
|
||||
number,reason
|
||||
101,stale
|
||||
102,duplicate
|
||||
103,resolved
|
||||
```
|
||||
|
||||
CSV 支持 `number`、`issue_number`、`project_issues_index` 作为 Issue 编号列名。如果没有表头，则默认读取第一列。
|
||||
|
||||
### Step 3：先执行 dry-run
|
||||
|
||||
Issue 编号列表方式：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--numbers "$ISSUE_NUMBERS" \
|
||||
--dry-run \
|
||||
--format json
|
||||
```
|
||||
|
||||
CSV 方式：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--from issues.csv \
|
||||
--dry-run \
|
||||
--format json
|
||||
```
|
||||
|
||||
### Step 4：展示 dry-run 结果
|
||||
|
||||
Agent 需要在真实执行前向用户展示计划，例如：
|
||||
|
||||
```text
|
||||
仓库：<owner>/<repo>
|
||||
Dry-run：true
|
||||
计划处理数量：3
|
||||
计划关闭的 Issue：101, 102, 103
|
||||
预检失败数量：0
|
||||
|
||||
请确认是否继续执行真实批量关闭。
|
||||
```
|
||||
|
||||
### Step 5：用户确认后执行
|
||||
|
||||
只有在用户明确确认后，才能执行真实命令。
|
||||
|
||||
Issue 编号列表方式：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--numbers "$ISSUE_NUMBERS" \
|
||||
--format json
|
||||
```
|
||||
|
||||
CSV 方式：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +batch-close \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--from issues.csv \
|
||||
--format json
|
||||
```
|
||||
|
||||
### Step 6：输出最终报告
|
||||
|
||||
最终报告应包含：
|
||||
|
||||
- 目标仓库
|
||||
- Issue 总数
|
||||
- 成功数量
|
||||
- 失败数量
|
||||
- 每个失败 Issue 编号及错误原因
|
||||
- 是否需要后续处理
|
||||
|
||||
## 输出结构示例
|
||||
|
||||
Dry-run 输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"repository": "owner/repo",
|
||||
"dry_run": true,
|
||||
"total": 3,
|
||||
"succeeded": 3,
|
||||
"failed": 0,
|
||||
"results": [
|
||||
{"id": "101", "action": "close", "status": "planned"},
|
||||
{"id": "102", "action": "close", "status": "planned"},
|
||||
{"id": "103", "action": "close", "status": "planned"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
真实执行输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"repository": "owner/repo",
|
||||
"dry_run": false,
|
||||
"total": 3,
|
||||
"succeeded": 3,
|
||||
"failed": 0,
|
||||
"results": [
|
||||
{"id": "101", "action": "close", "status": "closed"},
|
||||
{"id": "102", "action": "close", "status": "closed"},
|
||||
{"id": "103", "action": "close", "status": "closed"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent 应答模板
|
||||
|
||||
当用户说“帮我关闭这些 Issue”或“批量关闭 stale Issues”时，Agent 应先说明计划：
|
||||
|
||||
```text
|
||||
我会先对仓库 <owner>/<repo> 的 Issue 编号 <numbers> 执行 dry-run 预览，不会修改任何数据。你确认 dry-run 结果后，我再执行真实批量关闭。
|
||||
```
|
||||
|
||||
dry-run 完成后，Agent 应询问用户：
|
||||
|
||||
```text
|
||||
Dry-run 已完成。计划关闭 3 个 Issue：101、102、103。未发现失败项。请确认是否现在执行真实关闭。
|
||||
```
|
||||
|
||||
## 失败处理
|
||||
|
||||
如果 `failed > 0`：
|
||||
|
||||
1. 不要声称全部成功。
|
||||
2. 列出失败的 Issue 编号 和错误信息。
|
||||
3. 建议用户检查权限、Issue 是否存在、owner/repo 是否正确。
|
||||
4. 如果只有部分失败，需要分别报告成功项和失败项。
|
||||
|
||||
## 参考
|
||||
|
||||
- [`gitlink-workflow`](../SKILL.md)
|
||||
- [`gitlink-issue`](../../gitlink-issue/SKILL.md)
|
||||
- [`issue +batch-close` PR #12](https://gitlink.org.cn/Gitlink/gitlink-cli/pulls/12)
|
||||
- [`gitlink-shared`](../../gitlink-shared/SKILL.md)
|
||||
Loading…
Reference in New Issue