# 重复 Issue 检测 — 端到端工作流示例与验证记录

> 配套文档：[`../SKILL.md`](../SKILL.md)
> 本文记录一次**真实跑通**的完整工作流（只读分析 + 写动作计划），含真实命令输出，作为「使用示例 + Agent 平台验证结果」交付物。

## 验证环境

| 项 | 值 |
|----|----|
| Agent 平台 | Claude Code |
| gitlink-cli | `local-build`（本仓库源码编译产物，**非** npm 发布版 v0.1.13） |
| 登录用户 | `z2_cc`（`auth status` ✓） |
| 测试目标 | `Gitlink/gitlink-cli`（19 条开放 Issue） |
| 验证日期 | 2026-06-17 |

> 选 `Gitlink/gitlink-cli` 是因其开放 Issue 较多、含真实重复/测试 Issue；**写动作未在该他人仓库执行**，仅做只读分析 + 命令语法已 `--help` 验证。

## 步骤 1：拉取全部开放 Issue

```bash
gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --limit 50 --format json
```

解析 `data.issues[]`，取 `number`(Web编号) / `subject` / `comment_journals_count` / `tags` / `created_at`：

```
all_count: 19
#21  [3评论] 2026-06-14  dataset 快捷命令需要的后端 API 支持
#20  [1评论] 2026-06-12  bug: api 命令单次调用不替换 :owner/:repo 占位符（0.2.0）
#6   [3评论] 2026-04-25  只要创建Iusse就让Agent开始干活
#1   [1评论] 2026-04-01  CLI测试Issue - 已更新标题
#18  [0评论] 2026-05-22  giklink-cli issue +update后issue状态框变红色
#17  [0评论] 2026-05-21  API是否支持自动读取仓库内文件（README等）？
#16  [5评论] 2026-05-19  [Bug] Windows 平台完全不可用：Release 缺少 Windows 二进制…
#14  [1评论] 2026-05-16  pr +view 的返回中缺少PR关闭时间
#4   [4评论] 2026-04-18  PR使用gd login无法自动完成
#5   [1评论] 2026-04-24  通过这个skill认领任务，描述信息消失
#7   [1评论] 2026-04-25  目前看Gitlink-skill返回的PR ID和实际的不符
#15  [1评论] 2026-05-19  issue +view 返回的数据与网页显示不一致
#11  [0评论] 2026-05-13  [test] batch-close 测试 issue 1
#12  [0评论] 2026-05-13  [test] batch-close 测试 issue 2
#9   [2评论] 2026-05-12  feat(api): 希望 Issue API 支持按项目内序号查询
#8   [1评论] 2026-05-12  Test: PR#7 标题已修改
#10  [1评论] 2026-05-12  [test] PR#11 v1 API 测试 - 已更新
#2   [4评论] 2026-04-03  gitlink-cli 使用讨论与反馈收集
#3   [1评论] 2026-04-04  Skill测试Issue-0404 (已更新)
```

## 步骤 2：粗筛候选对

标题信号已显出两个簇：
- **簇 A**：`#11` / `#12` —— `[test] batch-close 测试 issue 1/2`，同作者同时间，强重复嫌疑。
- **簇 B**（主题「`+view`/`+update` 返回数据异常」）：`#5` / `#14` / `#15` / `#18` —— 需看正文区分「重复」还是「相关」。

## 步骤 3：取正文做相似度比对

```bash
gitlink-cli issue +view --owner Gitlink --repo gitlink-cli --number 11 --format json
gitlink-cli issue +view --owner Gitlink --repo gitlink-cli --number 12 --format json
```

| 编号 | 作者 | 创建时间 | 正文（节选） |
|------|------|----------|--------------|
| #11 | wbtiger | 2026-05-13 19:06 | `PR #12 测试用，验证后关闭` |
| #12 | wbtiger | 2026-05-13 19:06 | `PR #12 测试用，验证后关闭` |

→ **正文逐字相同、同作者、同一分钟提交**，相似度 **0.98**，判为**高度疑似重复**。

簇 B 正文各异（#5「描述丢失」、#14「关闭时间缺失」、#15「返回旧数据」、#18「状态框变红」），相似度 0.40–0.55 → **相关但非重复**，不合并。

## 步骤 4：幂等检查（写动作前）

```bash
gitlink-cli issue +comments --owner Gitlink --repo gitlink-cli --number 12 --format json
```

实测输出（节选）—— 注意 `+comments` 返回的是**活动日志**，需区分：

```json
[
  { "is_journal_detail": true,  "operate_content": "创建了<b>疑修</b>", "notes": "", "user": {"login":"wbtiger"} },
  { "is_journal_detail": true,  "operate_content": "…",                 "notes": "" },
  { "is_journal_detail": true,  "operate_content": "…",                 "notes": "" }
]
```

**判定规则**：仅当某条 `notes` **非空且含标记串**（`duplicate-of` / `重复，指向 #`）才视为已处理。此处 3 条均为系统日志（`notes` 空）→ **未处理，可执行写动作**。

> 真实文字评论才会带 `notes`（如 #21 的「新建声明: 我来解决」）。`comment_journals_count` 与 `+comments` 条数口径不同（后者含系统日志），幂等一律以 `notes` 内容为准。

另查 `issue +list` 的 `tags`：#12 为空 → 未打「重复」标签 → 双重确认未处理。

## 步骤 5：输出报告（dry-run，默认产物）

````markdown
# 重复 Issue 收敛报告 — Gitlink/gitlink-cli

扫描：开放 Issue 19 条 | 模式：dry-run（只读） | 2026-06-17

## 🔴 重复簇 1（高度疑似）
- 主 Issue：#11 `[test] batch-close 测试 issue 1`（wbtiger，2026-05-13，正文"PR #12 测试用，验证后关闭"）
- 重复项：
  - #12 `[test] batch-close 测试 issue 2` — 相似度 0.98（正文逐字一致、同作者同时间）
- 幂等：#12 无 duplicate 标记评论、无「重复」标签 → 待处理
- 建议动作：评论关联 #11 → 打「重复」标签 → 关闭 #12

## 🟡 相关但非重复（仅提示，不合并）
主题「+view/+update 返回数据异常」：#5 / #14 / #15 / #18，症状各异（相似度 0.40–0.55），分别处理。

## ✅ 待确认写动作
| 重复项 | 动作 | 命令 |
|--------|------|------|
| #12 | 评论+打标+关闭 | 见步骤 6 |
````

## 步骤 6：写动作计划（需用户逐条确认，未在他人仓库执行）

```bash
# 6.1 取「重复」标签 ID（已确认存在：id=298661，描述"表示已存在类似的疑修"）
gitlink-cli label +list --owner Gitlink --repo gitlink-cli --format json

# 6.2 关联评论
gitlink-cli issue +comment --owner Gitlink --repo gitlink-cli --number 12 \
  --body "🔁 疑似重复 Issue：本 Issue 与 #11 高度相似（正文逐字一致，相似度 0.98）。主 Issue → https://www.gitlink.org.cn/Gitlink/gitlink-cli/issues/11"

# 6.3 打「重复」标签做幂等标记
gitlink-cli issue +update --owner Gitlink --repo gitlink-cli --number 12 --label 298661

# 6.4 关闭重复项
gitlink-cli issue +close --owner Gitlink --repo gitlink-cli --number 12 \
  --comment "关闭：与 #11 重复，后续讨论请移步主 Issue。"
```

> 以上命令语法均经 `--help` 验证可用；因 `Gitlink/gitlink-cli` 非登录用户所有，**未实际执行写动作**。如需完整写链路验证，请在 `z2_cc` 自有仓库上重跑（可先 `issue +create` 造两条重复 Issue）。

## 关键验证结论

| 能力 | 命令 | 状态 |
|------|------|------|
| 批量拉取（含 Web 编号/标签/评论数/时间） | `issue +list --state --limit --format json` | ✅ 真实返回 |
| 关键词预筛 | `issue +list --keyword Windows` → 命中 1 条 | ✅ |
| 取正文 | `issue +view --number 11/12` → `description` | ✅ |
| 读评论（幂等） | `issue +comments --number 12` → 含 `notes`/`is_journal_detail` | ✅ |
| 标签管理 | `label +list` → 「重复」标签 id=298661 | ✅ |
| 评论/关闭 | `issue +comment` / `+close --number` | ✅ **实际执行成功**（见附录） |
| 打标签 | `issue +update --label` | ⚠️ 返回 ok 但未生效（见附录） |

> ⚠️ 版本前提：以上能力依赖含 `+comments`/`label`/`--keyword` 的 gitlink-cli（本仓库源码已具备；npm 发布版 v0.1.13 不具备）。参赛验证基于本地源码编译产物。

---

## 附：写链路实测验证（z2_cc/gitlink_help_center）

为验证写动作，在 z2_cc 拥有 Owner 权限的复刻仓 `z2_cc/gitlink_help_center` 实跑全链路（该仓已自带「重复」标签 id=315565、「测试」标签 id=315564）。

### A. 造两条高度相似的测试 Issue

```bash
gitlink-cli issue +create --owner z2_cc --repo gitlink_help_center -t "【dup-test】登录按钮点击无反应" -b "## 复现步骤 ..."  # → id=144589, Web #22
gitlink-cli issue +create --owner z2_cc --repo gitlink_help_center -t "【dup-test】登录按钮点了没反应" -b "## 复现步骤 ..."  # → id=144590, Web #23
```
（正文几乎逐字一致、标题同义 → 相似度 ~0.95，构造为重复对）

### B. 幂等检查（只读）

```bash
gitlink-cli issue +comments --owner z2_cc --repo gitlink_help_center --number 23 --format json
```
→ `data.journals[]` 仅 1 条系统动态（`is_journal_detail=true`，`notes` 空），无 duplicate 标记 → **可执行写动作**。

### C. 写动作执行结果

| 动作 | 命令 | 结果 |
|------|------|------|
| 关联评论 | `issue +comment --number 23 --body "🔁 疑似重复…指向 #22"` | ✅ 发布成功（journal id=476901） |
| 打「重复」标签 | `issue +update --number 23 --label 315565` | ⚠️ 返回 ok，但 `+list`/`+view` 的 `tags=[]`，**未生效** |
| 关闭重复项 | `issue +close --number 23 --comment "关闭：与 #22 重复…"` | ✅ 关闭成功 |

### D. 验证写动作落地

```bash
gitlink-cli issue +comments --owner z2_cc --repo gitlink_help_center --number 23 --format json
```
实测 `data.journals[]`（5 条）：
```
[0] is_journal_detail=true  operate_content="创建了<b>疑修</b>"            notes=""
[1] is_journal_detail=false operate_content=""                            notes="🔁 疑似重复 Issue：本 Issue 与 #22 高度相似…"
[2] is_journal_detail=true  operate_content="将状态由<b>新增</b>更改为<b>关闭</b>" notes=""
[3] is_journal_detail=true  operate_content="将结束日期设置为<b>2026-06-17</b>"  notes=""
[4] is_journal_detail=false operate_content=""                            notes="关闭：与 #22 重复，后续讨论请移步主 Issue #22。"
```

```bash
gitlink-cli issue +list --owner z2_cc --repo gitlink_help_center --state closed --format json
```
→ `#23 status=关闭`，`#22 status=新增`（主 Issue 保持开放）。✅

### E. 结论

- **评论 + 关闭链路完全可用**，且 `+comments` 能可靠回读评论（`is_journal_detail=false` 的 `notes`）→ **评论幂等成立**。
- **`+update --label` 不可靠**（返回 ok 但标签未生效）→ 幂等**不依赖标签**，仅用评论标记。
- 验证后已清理测试 Issue（`issue +delete` / 关闭清理），不在帮助中心仓留痕。
