forked from z2_cc/gitlink-cli
Compare commits
1 Commits
| Author | SHA1 | Date |
|---|---|---|
s2_cc
|
42c5d11a62 |
469
doc/demo.html
469
doc/demo.html
|
|
@ -1,469 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>GitLink CLI Skills 交互式演示</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, "Microsoft YaHei", sans-serif; background: #f0f2f5; color: #333; }
|
||||
.header { background: linear-gradient(135deg, #1a1a2e, #16213e); color: #fff; padding: 40px 20px; text-align: center; }
|
||||
.header h1 { font-size: 28px; margin-bottom: 8px; }
|
||||
.header p { color: #a0aec0; font-size: 15px; }
|
||||
.container { max-width: 1100px; margin: 0 auto; padding: 24px 20px; }
|
||||
.tabs { display: flex; gap: 8px; margin-bottom: 24px; flex-wrap: wrap; }
|
||||
.tab { padding: 10px 20px; border-radius: 8px; border: none; cursor: pointer; font-size: 14px; background: #e2e8f0; color: #4a5568; transition: all 0.2s; }
|
||||
.tab:hover { background: #cbd5e0; }
|
||||
.tab.active { background: #1a73e8; color: #fff; }
|
||||
.panel { display: none; }
|
||||
.panel.active { display: block; }
|
||||
.card { background: #fff; border-radius: 12px; padding: 20px 24px; margin-bottom: 16px; box-shadow: 0 2px 8px rgba(0,0,0,0.06); }
|
||||
.card h3 { font-size: 18px; color: #1a1a2e; margin-bottom: 8px; }
|
||||
.card p { font-size: 14px; color: #555; line-height: 1.7; }
|
||||
.card .tag { display: inline-block; background: #e8f0fe; color: #1a73e8; padding: 3px 12px; border-radius: 12px; font-size: 12px; margin: 2px 4px 2px 0; }
|
||||
.step { margin-bottom: 12px; border: 1px solid #e2e8f0; border-radius: 8px; overflow: hidden; }
|
||||
.step-hd { display: flex; align-items: center; padding: 12px 16px; cursor: pointer; background: #fafbfc; }
|
||||
.step-hd:hover { background: #f0f2f5; }
|
||||
.step-num { width: 26px; height: 26px; background: #1a73e8; color: #fff; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700; margin-right: 10px; flex-shrink: 0; }
|
||||
.step-hd .title { flex: 1; font-size: 14px; font-weight: 600; }
|
||||
.step-hd .arrow { font-size: 14px; color: #999; transition: transform 0.2s; }
|
||||
.step-hd.open .arrow { transform: rotate(90deg); }
|
||||
.step-bd { display: none; padding: 16px; }
|
||||
.step-bd.open { display: block; }
|
||||
.cmd { background: #1e1e2e; color: #cdd6f4; padding: 10px 14px; border-radius: 6px; font-family: Consolas,monospace; font-size: 12px; overflow-x: auto; margin-bottom: 10px; }
|
||||
.cmd .prompt { color: #89b4fa; }
|
||||
.output { background: #f8f9fa; border: 1px solid #e2e8f0; border-radius: 6px; padding: 12px 14px; font-family: Consolas,monospace; font-size: 12px; overflow-x: auto; white-space: pre-wrap; color: #333; max-height: 250px; overflow-y: auto; margin-bottom: 10px; }
|
||||
.analysis { background: #fefce8; border: 1px solid #fde68a; border-radius: 6px; padding: 14px; font-size: 13px; color: #92400e; margin-top: 8px; line-height: 1.8; }
|
||||
.analysis strong { color: #78350f; }
|
||||
.report { background: #fff; border: 2px solid #1a73e8; border-radius: 8px; padding: 20px; font-size: 13px; line-height: 2; margin-top: 8px; }
|
||||
.report h4 { font-size: 18px; margin-bottom: 10px; color: #1a1a2e; }
|
||||
.report table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 13px; }
|
||||
.report th { background: #e8f0fe; color: #1a56db; padding: 6px 10px; text-align: left; border: 1px solid #d0d7de; }
|
||||
.report td { padding: 6px 10px; border: 1px solid #d0d7de; }
|
||||
.badge { display: inline-block; padding: 1px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
|
||||
.badge-g { background: #dcfce7; color: #166534; }
|
||||
.badge-y { background: #fef9c3; color: #854d0e; }
|
||||
.badge-r { background: #fce4ec; color: #c62828; }
|
||||
.file-link { color: #1a73e8; text-decoration: none; font-size: 13px; }
|
||||
.file-link:hover { text-decoration: underline; }
|
||||
.bar { display: inline-block; height: 14px; border-radius: 3px; margin-right: 4px; vertical-align: middle; }
|
||||
@media (max-width: 768px) { .tabs { flex-direction: column; } }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="header">
|
||||
<h1>GitLink CLI Skills 交互式演示</h1>
|
||||
<p>点击查看 AI 对数据的深度分析与处理结果</p>
|
||||
</div>
|
||||
<div class="container">
|
||||
|
||||
<div class="tabs">
|
||||
<button class="tab active" data-tab="health">项目健康度报告</button>
|
||||
<button class="tab" data-tab="release">Release Notes 生成</button>
|
||||
<button class="tab" data-tab="triage">Issue 自动分拣</button>
|
||||
</div>
|
||||
|
||||
<!-- ======================== 项目健康度 ======================== -->
|
||||
<div class="panel active" id="panel-health">
|
||||
<div class="card">
|
||||
<h3>项目健康度报告</h3>
|
||||
<p>采集 Issue、PR、commit 数据，从 7 个维度量化分析，生成综合评分和改进建议。</p>
|
||||
<div><span class="tag">repo +info</span><span class="tag">issue +list</span><span class="tag">pr +list</span><span class="tag">commit +list</span><span class="tag">milestone +list</span></div>
|
||||
<a class="file-link" href="../skills/gitlink-project-health/SKILL.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">1</span><span class="title">采集原始数据</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state all --format json</div>
|
||||
<div class="output">{
|
||||
"issues": [
|
||||
{"number":1,"subject":"提升跨平台兼容性","status_id":1,"created_at":"2026-05-28"},
|
||||
{"number":2,"subject":"keyword-test-xyz-abc","status_id":5,"created_at":"2026-05-28","closed_at":"2026-06-01"},
|
||||
{"number":10,"subject":"新增 Wiki 管理","status_id":5,"created_at":"2026-06-01","closed_at":"2026-06-04"},
|
||||
{"number":12,"subject":"新增代码片段管理","status_id":5,"created_at":"2026-06-03","closed_at":"2026-06-04"},
|
||||
{"number":14,"subject":"Webhook 投递监控","status_id":1,"created_at":"2026-06-04"},
|
||||
{"number":15,"subject":"新增 failed + task-view","status_id":1,"created_at":"2026-06-04"}
|
||||
],
|
||||
"total_count":16, "closed_count":14
|
||||
}</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state all --format json</div>
|
||||
<div class="output">{
|
||||
"pull_requests": [
|
||||
{"number":31,"title":"fix: normalize issue list output","state":"merged","created_at":"2026-06-01","merged_at":"2026-06-03"}
|
||||
],
|
||||
"total_count":5, "merged_count":4
|
||||
}</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 50</div>
|
||||
<div class="output">[
|
||||
{"author":"wqer","message":"enhance: enrich skill outputs with data analysis","date":"2026-06-17"},
|
||||
{"author":"wqer","message":"docs: update demo page with AI analysis","date":"2026-06-17"},
|
||||
{"author":"wqer","message":"docs: add interactive demo page for skills","date":"2026-06-17"},
|
||||
{"author":"wqer","message":"docs: add release notes workflow example","date":"2026-06-17"},
|
||||
{"author":"wqer","message":"feat: add three new skills","date":"2026-06-17"}
|
||||
]</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">2</span><span class="title">Issue 维度深度分析</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>📊 Issue 基础统计</strong><br>
|
||||
总 Issue 数：<strong>16</strong> 个<br>
|
||||
打开中：<strong>2</strong> 个（12.5%）<br>
|
||||
已关闭：<strong>14</strong> 个（87.5%）<br><br>
|
||||
|
||||
<strong>⏱ 响应时间分析</strong><br>
|
||||
计算每条 closed Issue 从 created 到 closed 的天数：<br>
|
||||
#2 keyword-test: 4 天<br>
|
||||
#10 Wiki 管理: 3 天<br>
|
||||
#12 代码片段: 1 天<br>
|
||||
平均响应时间：<strong>2.7 天</strong> → <span class="badge badge-g">响应及时 🟢</span><br><br>
|
||||
|
||||
<strong>📈 积压趋势分析</strong><br>
|
||||
近 30 天新增：4 个<br>
|
||||
近 30 天关闭：3 个<br>
|
||||
净变化：<strong>+1</strong> → <span class="badge badge-y">基本稳定 🟡</span><br><br>
|
||||
|
||||
<strong>🏷 标签分布</strong><br>
|
||||
未打标签：16 个（100%）→ 建议增加标签管理<br><br>
|
||||
|
||||
<strong>📋 小结</strong><br>
|
||||
关闭率 87.5%，响应及时，积压稳定 → <span class="badge badge-g">Issue 管理良好 🟢</span><br>
|
||||
<strong>评分：8/10</strong>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">3</span><span class="title">PR 维度深度分析</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>📊 PR 基础统计</strong><br>
|
||||
总 PR 数：<strong>5</strong> 个<br>
|
||||
已合并：<strong>4</strong> 个（80%）<br>
|
||||
打开中：<strong>1</strong> 个（20%）<br><br>
|
||||
|
||||
<strong>⏱ 合并效率分析</strong><br>
|
||||
#31 fix: normalize output — 2 天<br>
|
||||
平均合并时间：<strong>2 天</strong> → <span class="badge badge-g">合并迅速 🟢</span><br><br>
|
||||
|
||||
<strong>📋 小结</strong><br>
|
||||
合并率高，速度快 → <span class="badge badge-g">PR 流程健康 🟢</span><br>
|
||||
<strong>评分：8/10</strong>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">4</span><span class="title">贡献者活跃度分析</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>👥 贡献者统计</strong><br>
|
||||
近 50 次提交：<strong>15</strong> 次<br>
|
||||
去重作者：<strong>1</strong> 人（wqer） → <span class="badge badge-r">单人维护 🔴</span><br>
|
||||
新贡献者：0 人 → <span class="badge badge-r">缺少新鲜血液 🔴</span><br><br>
|
||||
|
||||
<strong>📅 提交频率</strong><br>
|
||||
最近一周：每天都有提交 → <span class="badge badge-g">非常活跃 🟢</span><br><br>
|
||||
|
||||
<strong>🔄 提交类型分布</strong><br>
|
||||
feat（新功能）：6 次（40%）<br>
|
||||
docs（文档）：5 次（33%）<br>
|
||||
fix（修复）：2 次（13%）<br>
|
||||
chore（工程）：2 次（13%）<br><br>
|
||||
|
||||
<strong>📋 小结</strong><br>
|
||||
提交活跃但仅 1 人维护 → <span class="badge badge-y">需吸引贡献者 🟡</span><br>
|
||||
<strong>评分：6/10</strong>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">5</span><span class="title">里程碑进度</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>🗓 里程碑概览</strong><br>
|
||||
v1.3.0 — 到期日：2026-06-30，完成度：60% → <span class="badge badge-g">进行中 🟢</span><br>
|
||||
v2.0.0 — 到期日：2026-08-15，完成度：20% → <span class="badge badge-y">初期阶段 🟡</span><br><br>
|
||||
<strong>逾期风险：</strong>无 🔴 无逾期
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)" style="background:#f0f9ff;">
|
||||
<span class="step-num" style="background:#34a853;">R</span>
|
||||
<span class="title" style="color:#1a73e8;">📋 AI 生成的完整健康度报告</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-bd">
|
||||
<div class="report">
|
||||
<h4>项目健康度报告 — z2_cc/gitlink-cli</h4>
|
||||
<strong>报告日期：</strong>2026-06-17<br>
|
||||
<strong>综合评分：7.3/10 🟢 良好</strong><br><br>
|
||||
|
||||
<strong>一、Issue 状况（8/10 🟢）</strong><br>
|
||||
关闭率 87.5%，平均 2.7 天响应，积压基本稳定。<br><br>
|
||||
|
||||
<strong>二、PR 状况（8/10 🟢）</strong><br>
|
||||
合并率 80%，合并迅速。<br><br>
|
||||
|
||||
<strong>三、贡献者活跃度（6/10 🟡）</strong><br>
|
||||
单人维护，提交活跃，缺少新贡献者。<br><br>
|
||||
|
||||
<strong>四、里程碑进度（7/10 🟢）</strong><br>
|
||||
v1.3.0 完成 60%，按计划推进。<br><br>
|
||||
|
||||
<strong>五、改进建议</strong><br>
|
||||
<strong>🔴 高优先级</strong><br>
|
||||
1. 标记 good-first-issue 吸引新贡献者<br>
|
||||
2. 为 Issue 增加标签分类<br><br>
|
||||
<strong>🟡 中优先级</strong><br>
|
||||
3. 添加 CONTRIBUTING.md 引导新人<br>
|
||||
4. 定期清理积压 Issue<br><br>
|
||||
<strong>🟢 低优先级</strong><br>
|
||||
5. 考虑添加 CI/CD 自动化流水线
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ======================== Release Notes ======================== -->
|
||||
<div class="panel" id="panel-release">
|
||||
<div class="card">
|
||||
<h3>Release Notes 生成</h3>
|
||||
<p>分析 commit 历史，按 Conventional Commits 规范分类统计，推荐语义化版本，生成结构化发布说明。</p>
|
||||
<div><span class="tag">release +list</span><span class="tag">git log</span><span class="tag">pr +list</span></div>
|
||||
<a class="file-link" href="../skills/gitlink-release-auto/SKILL.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">1</span><span class="title">获取基线版本</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli release +list --owner z2_cc --repo gitlink-cli --format json</div>
|
||||
<div class="output">[ { "tag_name":"v1.2.0", "name":"v1.2.0", "body":"初始版本发布", "created_at":"2026-06-01" } ]</div>
|
||||
<div class="analysis"><strong>基线版本：</strong>v1.2.0（2026-06-01）<br>作为对比基准，计算自 v1.2.0 以来的所有变更。</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">2</span><span class="title">获取提交历史并分析</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="cmd"><span class="prompt">$</span> git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short</div>
|
||||
<div class="output">a4587f9|feat: add webhook +failed and +task-view commands|wqer|2026-06-04
|
||||
37a0f21|docs: add release notes workflow example|wqer|2026-06-17
|
||||
6c0ad3b|feat: add three new skills|wqer|2026-06-17
|
||||
d1cc68b|docs: add workflow examples|wqer|2026-06-17
|
||||
9a51db0|feat: add wiki and snippet skills|wqer|2026-06-17
|
||||
5866600|enhance: enrich skill outputs|wqer|2026-06-17
|
||||
21a3447|docs: update demo page|wqer|2026-06-17</div>
|
||||
|
||||
<div class="cmd"><span class="prompt">$</span> git log v1.2.0..HEAD --stat --oneline | tail -5</div>
|
||||
<div class="output">15 files changed, 980 insertions(+), 810 deletions(-)</div>
|
||||
|
||||
<div class="analysis">
|
||||
<strong>📊 AI 分类统计过程：</strong><br><br>
|
||||
<strong>Step 1 — 按 Conventional Commits 分类</strong><br>
|
||||
feat: add webhook +failed → ✨ 新功能<br>
|
||||
docs: add release notes → 📝 文档<br>
|
||||
feat: add three new skills → ✨ 新功能<br>
|
||||
docs: add workflow examples → 📝 文档<br>
|
||||
feat: add wiki and snippet → ✨ 新功能<br>
|
||||
enhance: enrich skill → ⚡ 优化<br>
|
||||
docs: update demo page → 📝 文档<br><br>
|
||||
|
||||
<strong>Step 2 — 数量统计</strong><br>
|
||||
✨ 新功能：3 次（43%）<br>
|
||||
📝 文档：3 次（43%）<br>
|
||||
⚡ 优化：1 次（14%）<br>
|
||||
<strong>总提交：7 次 | 贡献者：1 人</strong><br><br>
|
||||
|
||||
<strong>Step 3 — 变更规模</strong><br>
|
||||
涉及文件：15 个<br>
|
||||
新增行数：+980<br>
|
||||
删除行数：-810
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">3</span><span class="title">版本号推荐</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>语义化版本推荐规则：</strong><br>
|
||||
<table>
|
||||
<tr><th>条件</th><th>版本变更</th></tr>
|
||||
<tr><td>包含 BREAKING CHANGE</td><td>主版本 +1（1.x.x → 2.0.0）</td></tr>
|
||||
<tr><td>包含 feat，无 breaking</td><td><strong>次版本 +1（1.2.x → 1.3.0） ✓</strong></td></tr>
|
||||
<tr><td>仅 fix/docs/chore</td><td>修订号 +1（1.2.0 → 1.2.1）</td></tr>
|
||||
</table>
|
||||
<br>
|
||||
<strong>当前版本：</strong>v1.2.0<br>
|
||||
<strong>包含 feat：</strong>是<br>
|
||||
<strong>包含 BREAKING CHANGE：</strong>否<br><br>
|
||||
<strong>推荐版本：v1.3.0 🏷</strong>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)" style="background:#f0f9ff;">
|
||||
<span class="step-num" style="background:#34a853;">R</span>
|
||||
<span class="title" style="color:#1a73e8;">📋 AI 生成的完整 Release Notes</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-bd">
|
||||
<div class="report">
|
||||
<h4>v1.3.0 (2026-06-17)</h4>
|
||||
|
||||
<strong>📊 版本概览</strong><br>
|
||||
<table>
|
||||
<tr><td>提交次数</td><td>7 次</td></tr>
|
||||
<tr><td>贡献者</td><td>1 人</td></tr>
|
||||
<tr><td>涉及文件</td><td>15 个</td></tr>
|
||||
<tr><td>新增/删除</td><td>+980 / -810 行</td></tr>
|
||||
</table>
|
||||
|
||||
<strong>✨ 新功能（3）</strong><br>
|
||||
- feat: 新增 Webhook 投递监控（failed + task-view）<br>
|
||||
- feat: 新增三个 AI Agent Skill（issue-triage / project-health / newcomer-guide）<br>
|
||||
- feat: 新增 Wiki 和代码片段管理 Skill<br><br>
|
||||
|
||||
<strong>📝 文档（3）</strong><br>
|
||||
- docs: 添加 Release Notes 工作流示例<br>
|
||||
- docs: 添加其他工作流示例<br>
|
||||
- docs: 更新交互式演示页面<br><br>
|
||||
|
||||
<strong>⚡ 优化（1）</strong><br>
|
||||
- perf: 增强 Skill 输出的数据分析能力<br><br>
|
||||
|
||||
<strong>📈 统计汇总</strong><br>
|
||||
<table>
|
||||
<tr><th>类别</th><th>数量</th><th>占比</th><th>可视化</th></tr>
|
||||
<tr><td>✨ 新功能</td><td>3</td><td>43%</td><td><span class="bar" style="width:86px; background:#34a853;"></span></td></tr>
|
||||
<tr><td>📝 文档</td><td>3</td><td>43%</td><td><span class="bar" style="width:86px; background:#1a73e8;"></span></td></tr>
|
||||
<tr><td>⚡ 优化</td><td>1</td><td>14%</td><td><span class="bar" style="width:28px; background:#fbbc04;"></span></td></tr>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ======================== Issue 自动分拣 ======================== -->
|
||||
<div class="panel" id="panel-triage">
|
||||
<div class="card">
|
||||
<h3>Issue 自动分拣</h3>
|
||||
<p>通过关键词权重评分系统，对 Issue 自动分类、评估紧急度，并生成结构化引导评论。</p>
|
||||
<div><span class="tag">issue +list</span><span class="tag">issue +view</span><span class="tag">issue +comment</span></div>
|
||||
<a class="file-link" href="../skills/gitlink-issue-triage/SKILL.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">1</span><span class="title">采集待处理 Issue</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state open --format json</div>
|
||||
<div class="output">[
|
||||
{"number":42, "subject":"登录页面报错：500 Internal Server Error",
|
||||
"body":"每次点击登录按钮后，页面白屏并返回 500 错误。已尝试清除缓存无效。"},
|
||||
{"number":43, "subject":"建议增加 CSV 导出功能",
|
||||
"body":"项目中需要将数据导出为 CSV 格式，希望增加此功能。"},
|
||||
{"number":44, "subject":"README 中缺少安装说明",
|
||||
"body":"第一次使用这个项目，发现 README 没有写如何安装和配置。"}
|
||||
]</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">2</span><span class="title">AI 关键词权重评分</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>🔍 Issue #42 — 登录页面报错：500 Internal Server Error</strong><br>
|
||||
┌────────────────────────────────────────────<br>
|
||||
│ 匹配关键词及权重：<br>
|
||||
│ 报错(5) + 错误(8) + 页面(0) + 白屏(3) = <strong>16 分</strong><br>
|
||||
│ 分类：🐛 Bug（≥15 分触发）<br>
|
||||
│ 紧急度：16 × 1.5 = <strong>24 → 🔴 P0 紧急</strong><br>
|
||||
└────────────────────────────────────────────<br><br>
|
||||
|
||||
<strong>🔍 Issue #43 — 建议增加 CSV 导出功能</strong><br>
|
||||
┌────────────────────────────────────────────<br>
|
||||
│ 匹配关键词及权重：<br>
|
||||
│ 建议(8) + 增加(5) + 功能(3) + 导出(3) = <strong>19 分</strong><br>
|
||||
│ 分类：✨ 功能需求（≥12 分触发）<br>
|
||||
│ 紧急度：19 × 1.0 = <strong>19 → 🟡 P1 高优先</strong><br>
|
||||
└────────────────────────────────────────────<br><br>
|
||||
|
||||
<strong>🔍 Issue #44 — README 缺少安装说明</strong><br>
|
||||
┌────────────────────────────────────────────<br>
|
||||
│ 匹配关键词及权重：<br>
|
||||
│ 文档(10) + 缺少(4) + 安装(3) + README(8) = <strong>25 分</strong><br>
|
||||
│ 分类：📝 文档（≥10 分触发）<br>
|
||||
│ 紧急度：25 × 1.0 = <strong>25 → 🟡 P1 高优先</strong><br>
|
||||
└────────────────────────────────────────────
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step">
|
||||
<div class="step-hd" onclick="toggle(this)"><span class="step-num">3</span><span class="title">AI 生成引导评论</span><span class="arrow">▶</span></div>
|
||||
<div class="step-bd">
|
||||
<div class="analysis">
|
||||
<strong>🤖 AI 为 Issue #42（Bug / P0 紧急）生成的评论：</strong>
|
||||
</div>
|
||||
<div class="report">
|
||||
<strong>Issue 自动分类结果</strong><br><br>
|
||||
<strong>类别：</strong>🐛 Bug<br>
|
||||
<strong>紧急度：</strong>🔴 P0 紧急 — 建议立即处理<br>
|
||||
<strong>建议标签：</strong>bug<br><br>
|
||||
<strong>分类依据：</strong><br>
|
||||
标题和描述中包含关键词「报错」「错误」「白屏」，匹配 Bug 分类（权重 16 分）。<br><br>
|
||||
<strong>请补充以下信息以便排查：</strong><br>
|
||||
1. 运行环境：操作系统 / 浏览器版本<br>
|
||||
2. 复现步骤：详细描述如何触发此 bug<br>
|
||||
3. 错误日志：浏览器控制台是否有报错信息<br>
|
||||
4. 是否必现：每次操作都能复现吗？<br><br>
|
||||
<strong>自动分配：</strong>已通知项目维护者。
|
||||
</div>
|
||||
|
||||
<div class="analysis" style="margin-top:12px;">
|
||||
<strong>🤖 AI 为 Issue #43（功能需求 / P1 高优先）生成的评论：</strong>
|
||||
</div>
|
||||
<div class="report">
|
||||
<strong>Issue 自动分类结果</strong><br><br>
|
||||
<strong>类别：</strong>✨ 功能需求<br>
|
||||
<strong>紧急度：</strong>🟡 P1 高优先<br>
|
||||
<strong>建议标签：</strong>enhancement<br><br>
|
||||
<strong>分类依据：</strong><br>
|
||||
标题中包含关键词「建议」「增加」，匹配功能需求分类（权重 19 分）。<br><br>
|
||||
<strong>请补充以下信息：</strong><br>
|
||||
1. 这个功能解决了什么场景的问题？<br>
|
||||
2. 期望的导出格式是什么？<br>
|
||||
3. 是否有参考实现？<br><br>
|
||||
感谢你的建议！项目组会评估这个需求的可行性。
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<script>
|
||||
function toggle(el) {
|
||||
el.classList.toggle('open');
|
||||
el.nextElementSibling.classList.toggle('open');
|
||||
}
|
||||
document.querySelectorAll('.tab').forEach(function(t) {
|
||||
t.addEventListener('click', function() {
|
||||
document.querySelectorAll('.tab').forEach(function(x){x.classList.remove('active')});
|
||||
document.querySelectorAll('.panel').forEach(function(x){x.classList.remove('active')});
|
||||
this.classList.add('active');
|
||||
document.getElementById('panel-' + this.dataset.tab).classList.add('active');
|
||||
});
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -108,14 +108,6 @@ skills/
|
|||
│ └── ci-workflow.md # CI 工作流
|
||||
├── gitlink-pm/ # 项目管理
|
||||
│ └── SKILL.md # PM 操作指南
|
||||
├── gitlink-duplicate-detector/ # 重复 Issue 检测
|
||||
│ ├── SKILL.md # 重复检测与关联收敛指南
|
||||
│ └── examples/
|
||||
│ └── duplicate-detection-workflow.md # 端到端工作流与验证记录
|
||||
├── gitlink-pr-deep-review/ # PR 深度审查
|
||||
│ ├── SKILL.md # 编排 code-review + 设计/一致性推理
|
||||
│ └── examples/
|
||||
│ └── pr-deep-review-workflow.md # 端到端工作流与验证记录
|
||||
└── gitlink-workflow/ # AI 自动化工作流
|
||||
└── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes）
|
||||
```
|
||||
|
|
@ -309,8 +301,6 @@ AI 代理可以：
|
|||
- ✅ 自动分类 Issue
|
||||
- ✅ 自动生成 Release Notes
|
||||
- ✅ 自动执行代码审查
|
||||
- ✅ 自动检测并收敛重复 Issue（[gitlink-duplicate-detector](gitlink-duplicate-detector/SKILL.md)）
|
||||
- ✅ PR 深度审查：实现质量 + 设计/需求一致性 + 跨模块影响（[gitlink-pr-deep-review](gitlink-pr-deep-review/SKILL.md)）
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -50,23 +50,34 @@ gitlink-cli pr +files --id <pull_request_id> --format json
|
|||
| `files[].isDeleted` | boolean | 是否删除文件 |
|
||||
| `files[].isRenamed` | boolean | 是否重命名 |
|
||||
|
||||
### 获取 PR Diff
|
||||
### 获取 PR Diff（`pr +version-diff`，替代已移除的 `pr +diff`）
|
||||
|
||||
`pr +diff` 已移除（与 `file` 冗余）。先取补丁集版本，再看版本差异：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +diff --id <pull_request_id> --format json
|
||||
# 1) 取 patchset version_id
|
||||
gitlink-cli pr +versions --id <pull_request_id> --format json
|
||||
# 2) 看该版本的逐行 diff
|
||||
gitlink-cli pr +version-diff --id <pull_request_id> --version-id <vid> [--file <path>] --format json
|
||||
```
|
||||
|
||||
**返回字段说明：**
|
||||
**`pr +versions` 返回字段：**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `files_count` | int | 文件总数 |
|
||||
| `total_addition` | int | 总新增行数 |
|
||||
| `total_deletion` | int | 总删除行数 |
|
||||
| `files[].sections[].lines[].leftIdx` | int | 原文件行号 |
|
||||
| `files[].sections[].lines[].rightIdx` | int | 新文件行号 |
|
||||
| `files[].sections[].lines[].type` | int | 1=未变, 2=新增, 3=删除, 4=统计信息 |
|
||||
| `files[].sections[].lines[].content` | string | 行内容 |
|
||||
| `data.versions[].id` | int | **patchset 版本 ID（version-diff 用这个）** |
|
||||
|
||||
**`pr +version-diff` 返回字段：**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `data.file_nums` | int | 文件总数 |
|
||||
| `data.files[].name` | string | 文件名 |
|
||||
| `data.files[].addition` / `deletion` | int | 该文件增/删行数 |
|
||||
| `data.files[].sections[].lines[].content` | string | 行内容（含 `@@ ...` hunk 头） |
|
||||
| `data.files[].sections[].lines[].type` | int | **2=新增, 3=删除, 4=hunk 头（`@@`）；据此筛出变更行** |
|
||||
|
||||
> ⚠️ `--file <path>` 过滤不稳定，建议整份取后客户端按 `files[].name` 筛。需读文件全文用 `file +get --ref <head分支> --path <文件>`。
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -100,6 +111,53 @@ gitlink-cli pr +list --state <open|merged|closed> --format json
|
|||
|
||||
---
|
||||
|
||||
## 评审与评论命令（代码审查写入）
|
||||
|
||||
### `pr +review` — 提交评审（首选）
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +review --id <pr_id> --status <common|approved|rejected> --content "<报告>" [--commit <sha>] [--dry-run] --format json
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `-i, --id` | PR 编号 |
|
||||
| `-s, --status` | **评审状态：`common`（普通评论）/ `approved`（批准）/ `rejected`（拒绝，即 Request changes）**，默认 `common` |
|
||||
| `-c, --content` | 评审内容（Markdown，放整体审查报告） |
|
||||
| `-m, --commit` | 可选，挂到具体 commit SHA |
|
||||
| `--dry-run` | **预览不提交（审查必用）** |
|
||||
|
||||
> 状态映射：报告含 Critical → `rejected`；仅 Warning/Suggestion → `common`；无问题 → `approved`。**不要用 GitHub 风格的 `event:"COMMENT"`**，GitLink 用 `--status`。
|
||||
|
||||
### `pr +create-comment` — 行内评审评论
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +create-comment --id <pr_id> --path <文件路径> --line <行号> --body "<意见>" --format json
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `-i, --id` | PR 编号 |
|
||||
| `-p, --path` | 文件路径 |
|
||||
| `-l, --line` | **文件中的行号**（非 diff 补丁位置；注意 import/头注释偏移） |
|
||||
| `-b, --body` | 评论内容 |
|
||||
|
||||
> 行号不确定时**不要发**——并入 `pr +review --content` 总报告，或改用 `pr +comment`。
|
||||
|
||||
### `pr +comment` — 普通评论（不绑行）
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +comment --id <pr_id> --body "<评论>" --format json
|
||||
```
|
||||
|
||||
> 以 journal 形式挂在 PR 下，不绑定文件行。是行内评论失败时的安全 fallback。
|
||||
|
||||
### `pr +reviews` — 列出已有评审（复审时用）
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +reviews --id <pr_id> [--status <common|approved|rejected>] --format json
|
||||
```
|
||||
|
||||
## Issue 相关 API
|
||||
|
||||
### 获取 Issue 列表
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-code-review
|
||||
version: 1.0.0
|
||||
description: "智能代码审查：获取 PR 变更、分析代码质量、自动生成 Review 评论与摘要报告。当用户需要审查 Pull Request、检查代码质量或生成审查报告时触发。"
|
||||
version: 1.2.0
|
||||
description: "当用户需要对 GitLink 上的 Pull Request 做代码审查时触发：获取 PR 变更/Diff、按严重程度输出结构化 Review 意见、并（经确认后）把评审评论提交到 PR。适用于收到 PR Review 请求、需要批量审查 PR、为 PR 自动生成审查报告等场景。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -11,311 +11,201 @@ metadata:
|
|||
# gitlink-code-review（智能代码审查）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图；提交 Review 会通知 PR 相关人，必须先出报告→用户确认→dry-run→再提交。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
## 核心原则
|
||||
|
||||
1. **用 Shortcut，不用 Raw API**：提交评审用 `pr +review`，行内评论用 `pr +create-comment`，普通评论用 `pr +comment`。不要用 GitHub 风格的 Raw API（`event:"COMMENT"` / `position` 等字段 GitLink 不支持）。
|
||||
2. **建议优先，确认后提交**：先把结构化审查报告交给用户确认，**禁止未经确认直接提交 Review/评论**。尤其禁止用 `--yes` 绕过确认，除非用户明确说「直接提交/不用确认」。
|
||||
3. **严重程度分级驱动结论**：有 Critical → 评审状态用 `rejected`（Request changes）；仅 Suggestion/Positive → `common`；无问题 → `approved`。
|
||||
4. **安全红线零容忍**：硬编码密钥、SQL/命令注入、XSS、路径遍历、不安全反序列化必须标 Critical。
|
||||
|
||||
## 工作流概览
|
||||
|
||||
本 Skill 提供一套完整的 AI 驱动代码审查工作流，覆盖从获取 PR 变更到生成审查报告的全过程。不需要额外的 CLI Shortcuts——现有 `gitlink-cli` 命令 + AI Agent 的分析能力即可完成。
|
||||
|
||||
| 阶段 | 操作 | AI Agent 角色 |
|
||||
|------|------|--------------|
|
||||
| ① 获取上下文 | 拉取 PR 详情、变更文件、Diff | 执行 CLI 命令采集数据 |
|
||||
| ② 分析代码 | 检查每个文件的变更 | 逐文件审查，标记问题 |
|
||||
| ③ 结构化反馈 | 按严重程度分级输出审查意见 | 生成分级 Review 评论 |
|
||||
| ④ 提交评论 | 发表 Review 到 PR | 通过 API 提交 |
|
||||
| ⑤ 生成报告 | 输出审查摘要 | 生成 Markdown 摘要 |
|
||||
| 阶段 | 操作 | 命令 |
|
||||
|------|------|------|
|
||||
| ① 获取上下文 | PR 详情 / 变更文件 / Diff | `pr +view` / `pr +files` / `pr +diff` |
|
||||
| ② 逐文件分析 | 按语言检查项审查 | （AI 分析） |
|
||||
| ③ 出审查报告 | 按严重程度分级，**等用户确认** | （无写入） |
|
||||
| ④ dry-run 预览 | 用户确认后，预览评审 | `pr +review --dry-run` |
|
||||
| ⑤ 提交评审 | 用户再次确认后提交 | `pr +review`（去 `--dry-run`） |
|
||||
| ⑥ 行内评论（可选） | 针对具体行追加 | `pr +create-comment --path --line` |
|
||||
|
||||
---
|
||||
|
||||
## 详细工作流
|
||||
|
||||
### 工作流 1：PR 代码审查
|
||||
|
||||
**场景**：收到 PR Review 请求后，进行完整代码审查。
|
||||
|
||||
#### Step 1：获取 PR 上下文
|
||||
### Step 1：获取 PR 上下文
|
||||
|
||||
```bash
|
||||
# 获取 PR 详情
|
||||
# PR 详情
|
||||
gitlink-cli pr +view --id <pr_id> --format json
|
||||
|
||||
# 获取变更文件列表
|
||||
# 变更文件列表（含增删行数、是否新建）
|
||||
gitlink-cli pr +files --id <pr_id> --format json
|
||||
|
||||
# 获取 Diff 内容（含变更行号和代码上下文）
|
||||
gitlink-cli pr +diff --id <pr_id> --format json
|
||||
# Diff 内容（先取补丁集版本，再看版本差异；pr +diff 已移除）
|
||||
gitlink-cli pr +versions --id <pr_id> --format json # 拿 version_id
|
||||
gitlink-cli pr +version-diff --id <pr_id> --version-id <vid> --format json # 逐行 diff
|
||||
```
|
||||
|
||||
#### Step 2：逐文件分析
|
||||
> `--id` 是 PR 编号（web URL 中的编号）。Diff 在 `files[].sections[].lines[]`，`type`：2=新增、3=删除、4=hunk 头（`@@ ...`）；按文件分组逐文件分析，大型 PR 分段处理。
|
||||
>
|
||||
> ⚠️ **实测（2026-06-21）**：`pr +diff` 已被移除（与 `file` 冗余），由 `pr +version-diff` 替代。`--file <path>` 过滤不稳定，建议整份取 diff 后客户端按文件名筛。需要读某文件全文时用 `file +get --ref <head分支> --path <文件>`。
|
||||
|
||||
对每个变更文件，根据文件类型执行针对性检查：
|
||||
### Step 2：逐文件分析
|
||||
|
||||
**Python 文件检查项：**
|
||||
- 语法与导入：未使用的 import、循环导入、wildcard import
|
||||
- 代码规范：PEP 8 风格偏离、过长行（>88 chars）、命名规范
|
||||
- 安全：硬编码密钥、SQL 注入风险、`eval()`/`exec()` 使用
|
||||
- 性能：不必要的循环、缺少缓存、N+1 查询
|
||||
- 错误处理：裸 `except`、吞异常、缺少 finally
|
||||
对每个变更文件，按语言执行针对性检查：
|
||||
|
||||
**JavaScript/TypeScript 文件检查项：**
|
||||
- 安全：`innerHTML` 直接赋值、`eval()` 使用
|
||||
- 类型安全：`any` 滥用、缺失类型定义
|
||||
- 性能：不必要的 re-render、大对象深拷贝
|
||||
- 异步：未处理的 Promise、缺少 error boundary
|
||||
- 依赖：已废弃 API 使用
|
||||
**Python**：未用/循环 import；PEP8 偏离与过长行；硬编码密钥、SQL 注入、`eval()`/`exec()`；裸 `except`、吞异常；N+1 查询。
|
||||
**JS/TS**：`innerHTML` 直赋、`eval()`；`any` 滥用；未处理 Promise；废弃 API。
|
||||
**Go**：未检查的 error return、panic 滥用；goroutine 泄漏、缺 sync；未关闭 file/conn；导出标识符缺注释。
|
||||
**通用**：硬编码配置/密钥/URL；边界条件缺失；圈复杂度过高；魔法数字；DRY 违反；注释过时；测试覆盖不足。
|
||||
|
||||
**Go 文件检查项：**
|
||||
- 错误处理：未检查的 error return、panic 滥用
|
||||
- 并发：goroutine 泄漏、缺少 sync 保护
|
||||
- 资源管理：未关闭的 file/conn、defer 使用
|
||||
- 命名：导出标识符缺少注释、变量 shadowing
|
||||
### Step 3：出审查报告（建议，不写入）
|
||||
|
||||
**通用检查项：**
|
||||
- 硬编码的配置值、密钥、URL
|
||||
- 缺少或错误的边界条件检查
|
||||
- 过于复杂的函数（圈复杂度高）
|
||||
- 魔法数字（未命名的常量）
|
||||
- 重复代码（DRY 违反）
|
||||
- 缺少或过时的注释
|
||||
- 测试覆盖不足
|
||||
|
||||
#### Step 3：生成结构化审查结果
|
||||
|
||||
按以下 Severity 分级输出：
|
||||
按严重程度分级输出，**此阶段不执行任何写入**：
|
||||
|
||||
```markdown
|
||||
## PR #<id> 代码审查报告
|
||||
|
||||
### 🔴 Critical（必须修改）
|
||||
- <问题描述> — <文件>:<行号>
|
||||
- <问题> — <文件>:<行号>
|
||||
> <修改建议>
|
||||
|
||||
### 🟡 Warning（建议修改）
|
||||
- <问题描述> — <文件>:<行号>
|
||||
> <修改建议>
|
||||
### 🟡 Warning（建议修改） / 🔵 Suggestion（可选优化） / ✅ Positive（值得肯定）
|
||||
- ...
|
||||
|
||||
### 🔵 Suggestion（可选优化）
|
||||
- <问题描述> — <文件>:<行号>
|
||||
> <修改建议>
|
||||
|
||||
### ✅ Positive（值得肯定）
|
||||
- <做得好的地方>
|
||||
### 总体结论
|
||||
<评审状态建议：rejected / common / approved；是否阻塞合并>
|
||||
```
|
||||
|
||||
#### Step 4：提交 Review 评论
|
||||
**等待用户确认**：用户没说「确认/提交」前停在 Step 3。**禁止用 `--yes` 自行推进。**
|
||||
|
||||
### Step 4：dry-run 预览（用户确认报告后）
|
||||
|
||||
根据报告的严重程度选择评审状态，dry-run 预览（不实际提交）：
|
||||
|
||||
| 报告含 Critical | 评审状态 | 含义 |
|
||||
|-----------------|----------|------|
|
||||
| 是 | `rejected` | Request changes，阻塞合并 |
|
||||
| 否，仅 Warning/Suggestion | `common` | 普通评审评论 |
|
||||
| 无问题 | `approved` | 批准合并 |
|
||||
|
||||
```bash
|
||||
# 方式 1：提交整体 Review
|
||||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
|
||||
"body": "## 审查结果\n\n### 🔴 Critical\n...\n\n### 🟡 Warning\n...\n\n总体评价：...",
|
||||
"event": "COMMENT"
|
||||
}'
|
||||
|
||||
# 方式 2：在特定行添加内联评论（逐条提交）
|
||||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
|
||||
"body": "这里存在安全风险：用户输入未经转义直接拼接到 SQL 查询中，存在注入风险。建议使用参数化查询。",
|
||||
"event": "COMMENT",
|
||||
"commit_id": "<commit_sha>",
|
||||
"path": "src/query.py",
|
||||
"position": 42
|
||||
}'
|
||||
gitlink-cli pr +review --id <pr_id> \
|
||||
--status <common|approved|rejected> \
|
||||
--content "<把审查报告 Markdown 作为 content>" \
|
||||
--dry-run --format json
|
||||
```
|
||||
|
||||
> **注意：** `event` 参数支持 `COMMENT`（普通评论）和 `APPROVE`（批准）。对于需要修改的问题，使用 `COMMENT`。
|
||||
> `--content` 放整体审查报告（Markdown）。`--commit <sha>` 可选，把评审挂到具体 commit。核对 dry-run 输出无误。
|
||||
|
||||
#### Step 5：生成审查摘要
|
||||
### Step 5：提交评审（用户确认 dry-run 后）
|
||||
|
||||
审查完成后，输出 Markdown 摘要供用户查阅：
|
||||
去掉 `--dry-run` 正式提交：
|
||||
|
||||
```markdown
|
||||
## 📋 审查摘要 — PR #<id> <title>
|
||||
```bash
|
||||
gitlink-cli pr +review --id <pr_id> \
|
||||
--status <common|approved|rejected> \
|
||||
--content "<审查报告>" \
|
||||
--format json
|
||||
```
|
||||
|
||||
| 指标 | 数据 |
|
||||
|------|------|
|
||||
| 审查文件数 | <n> |
|
||||
| 变更行数 | +<add> / -<del> |
|
||||
| Critical 问题 | <n> |
|
||||
| Warning | <n> |
|
||||
| Suggestion | <n> |
|
||||
### Step 6：行内评论（可选，针对具体行）
|
||||
|
||||
### 主要发现
|
||||
1. **[Critical]** <最严重的问题>
|
||||
2. **[Warning]** <次要问题>
|
||||
3. **[Suggestion]** <优化建议>
|
||||
需要把某条意见精准挂在某一行时，用 `pr +create-comment`：
|
||||
|
||||
### 总体评价
|
||||
<整体评估：代码质量、审查通过建议>
|
||||
```bash
|
||||
gitlink-cli pr +create-comment --id <pr_id> \
|
||||
--path <文件路径> --line <行号> \
|
||||
--body "<针对该行的意见>" --format json
|
||||
```
|
||||
|
||||
---
|
||||
*由 gitlink-code-review Skill 自动生成*
|
||||
> ⚠️ `--line` 是**文件中的行号**。Diff 输出给的可能是补丁内位置，需换算为文件真实行号（注意文件头部 import/license 偏移）。**若行号不确定，不要盲目发**——把该意见并入 Step 5 的 `--content` 总报告，或改用 `pr +comment`（普通评论，不挂行）。
|
||||
>
|
||||
> ⚠️ **实测（2026-06-21）**：`pr +create-comment --line` 会返回 `ok:true`，但返回的 `line_code` 为 `null`，**评论未真正锚定到该行**（仅挂在文件级）。因此优先用 `pr +review --content` 提交总报告；行内评论不可靠时改用 `pr +comment`。
|
||||
|
||||
```bash
|
||||
# 普通评论（挂在 PR 下，不绑定行；行号不确定时的安全 fallback）
|
||||
gitlink-cli pr +comment --id <pr_id> --body "<评论>" --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作流 2：仓库代码健康度扫描
|
||||
## 评审状态与严重程度的映射
|
||||
|
||||
**场景**：对仓库整体代码质量进行评估，不依赖 PR。
|
||||
| 报告内容 | `--status` | 合并建议 |
|
||||
|---------|-----------|---------|
|
||||
| 含任何 Critical | `rejected` | 阻塞，修复后复审 |
|
||||
| 仅 Warning/Suggestion | `common` | 可合并，建议跟进 |
|
||||
| 全部 Positive / 无问题 | `approved` | 可合并 |
|
||||
|
||||
```bash
|
||||
# 1. 获取仓库信息
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
## 安全红线（必须标 Critical）
|
||||
|
||||
# 2. 获取仓库文件列表（遍历关键目录）
|
||||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=src&ref=master'
|
||||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=tests&ref=master'
|
||||
|
||||
# 3. 获取关键文件内容
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/README.md
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/.gitignore
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/.eslintrc.js # 或类似配置
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/package.json # 或 go.mod, Cargo.toml
|
||||
|
||||
# 4. 获取语言统计和贡献者
|
||||
gitlink-cli api GET /:owner/:repo/languages
|
||||
gitlink-cli api GET /:owner/:repo/contributors
|
||||
```
|
||||
|
||||
**健康度检查清单：**
|
||||
|
||||
| 检查项 | 标准 | 评分依据 |
|
||||
|--------|------|----------|
|
||||
| 文档完整性 | 有 README、CONTRIBUTING、CHANGELOG | 文件是否存在、内容质量 |
|
||||
| 许可证 | 有 LICENSE 文件 | 是否存在、是否合规 |
|
||||
| CI 配置 | 有 CI 配置（.github/workflows, Jenkinsfile 等） | 文件是否存在 |
|
||||
| 代码规范 | 有 linter 配置 | eslint/prettier/ruff/pylint 等 |
|
||||
| 测试覆盖 | 有 test 目录或测试文件 | 测试文件比例 |
|
||||
| 依赖管理 | 依赖文件完整且无已知漏洞 | package-lock/go.sum/poetry.lock |
|
||||
| Issue 健康度 | Issue 有分类标签、响应及时 | 通过 Issue 列表分析 |
|
||||
|
||||
**输出格式：**
|
||||
|
||||
```markdown
|
||||
## 🏥 仓库健康度报告 — <owner>/<repo>
|
||||
|
||||
### 总体评分：<⭐x/5>
|
||||
|
||||
| 维度 | 状态 | 评分 | 建议 |
|
||||
|------|:----:|:----:|------|
|
||||
| 📖 文档 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 📜 许可证 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 🔧 CI/CD | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 🎨 代码规范 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 🧪 测试覆盖 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 📦 依赖安全 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
| 🐛 Issue 管理 | ✅/⚠️/❌ | ☆☆☆☆☆ | <建议> |
|
||||
|
||||
### 关键发现
|
||||
1. <最需要改进的问题>
|
||||
2. <次要问题>
|
||||
3. <做得好的方面>
|
||||
|
||||
### 改进路线图
|
||||
- **紧急（本周）：** ...
|
||||
- **短期（本月）：** ...
|
||||
- **长期（本季度）：** ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作流 3：批量 Issue Triage + 自动分配
|
||||
|
||||
**场景**：对新 Issue 进行自动分类、标签分配和责任人推荐。
|
||||
|
||||
```bash
|
||||
# 1. 获取未标记的 Issue
|
||||
gitlink-cli issue +list --state open --format json
|
||||
|
||||
# 2. 逐个分析 Issue 内容
|
||||
gitlink-cli issue +view --id <issue_id> --format json
|
||||
|
||||
# 3. 根据内容智能分类
|
||||
# 分析标题和描述后，通过 Raw API 打标签
|
||||
gitlink-cli api POST /:owner/:repo/issues/:id --body '{
|
||||
"issue_tag_ids": [<tag_id>],
|
||||
"done_ratio": 0,
|
||||
"subject": "<原始标题>",
|
||||
"description": "<原始描述>"
|
||||
}'
|
||||
```
|
||||
|
||||
**分类规则参考：**
|
||||
|
||||
| Issue 关键词 | 推荐标签 | 优先级 |
|
||||
|-------------|----------|:------:|
|
||||
| bug, 错误, 失败, crash, 崩溃 | bug | 🔴 High |
|
||||
| feature, 新增, 建议, 希望 | enhancement | 🔵 Low |
|
||||
| 安全, 漏洞, 权限, 泄露 | security | 🔴 High |
|
||||
| 性能, 慢, 卡顿, 优化 | performance | 🟡 Medium |
|
||||
| 文档, README, 注释 | documentation | 🔵 Low |
|
||||
| question, 如何, 怎么, 请问 | question | 🟡 Medium |
|
||||
| 测试, test, 覆盖率 | testing | 🔵 Low |
|
||||
|
||||
---
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
代码审查相关的 GitLink API 端点：
|
||||
|
||||
```bash
|
||||
# 获取 PR 详情
|
||||
gitlink-cli api GET /:owner/:repo/pulls/:id --format json
|
||||
|
||||
# 获取 PR 变更文件列表
|
||||
gitlink-cli api GET /:owner/:repo/pulls/:id/files --format json
|
||||
|
||||
# 获取 PR Diff
|
||||
gitlink-cli api GET /:owner/:repo/pulls/:id/diff --format json
|
||||
|
||||
# 提交 PR Review
|
||||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"...","event":"COMMENT"}'
|
||||
|
||||
# 获取仓库文件列表
|
||||
gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=<path>&ref=<branch>'
|
||||
|
||||
# 获取仓库语言统计
|
||||
gitlink-cli api GET /:owner/:repo/languages --format json
|
||||
|
||||
# 获取贡献者列表
|
||||
gitlink-cli api GET /:owner/:repo/contributors --format json
|
||||
|
||||
# 获取仓库动态
|
||||
gitlink-cli api GET /:owner/:repo/activity --format json
|
||||
```
|
||||
- 硬编码的密钥 / Token / 密码 / 数据库连接串
|
||||
- SQL / NoSQL 注入（用户输入直接拼接进查询）
|
||||
- 命令注入（shell 命令拼接用户输入）
|
||||
- 路径遍历（用户输入直接用于文件路径）
|
||||
- XSS（未转义的用户输入直接渲染，如 `innerHTML`）
|
||||
- 不安全的反序列化
|
||||
|
||||
## 代码审查最佳实践
|
||||
|
||||
### 审查原则
|
||||
1. **先大局后细节**：先理解 PR 目的与整体变更范围，再逐文件审查。
|
||||
2. **关注行为而非风格**：风格问题交给 linter/formatter。
|
||||
3. **提供可操作的建议**：不只指出问题，给出具体修改方案。
|
||||
4. **肯定好的代码**：清晰命名、完善测试、良好设计给予正面反馈。
|
||||
5. **控制评论量**：最严重的 3–5 个问题比 20 个小问题更有价值。
|
||||
|
||||
1. **先大局后细节**：先理解 PR 的目的和整体变更范围，再逐文件审查
|
||||
2. **关注行为，而非风格**：自动化工具（linter/formatter）能处理的风格问题优先交给工具
|
||||
3. **提供可操作的建议**：不只是指出问题，要给出具体的修改方案
|
||||
4. **肯定好的代码**：发现好的设计、清晰的命名、完善的测试时给予正面反馈
|
||||
5. **控制评论量**：避免信息过载——最严重的 3-5 个问题比 20 个小问题更有价值
|
||||
## 命令速查
|
||||
|
||||
### 安全红线
|
||||
```bash
|
||||
# 获取上下文
|
||||
gitlink-cli pr +view --id <pr_id> --format json
|
||||
gitlink-cli pr +files --id <pr_id> --format json
|
||||
gitlink-cli pr +versions --id <pr_id> --format json # 拿 version_id
|
||||
gitlink-cli pr +version-diff --id <pr_id> --version-id <vid> --format json # 逐行 diff（替代已移除的 pr +diff）
|
||||
|
||||
以下问题必须标记为 **Critical**，不得忽略：
|
||||
# 提交评审（首选）
|
||||
gitlink-cli pr +review --id <pr_id> --status <common|approved|rejected> --content "<报告>" [--commit <sha>] [--dry-run]
|
||||
|
||||
- 硬编码的密钥 / Token / 密码
|
||||
- SQL / NoSQL 注入漏洞
|
||||
- 命令注入（shell 命令拼接）
|
||||
- 路径遍历（用户输入直接用于文件路径）
|
||||
- 不安全的反序列化
|
||||
- XSS（未转义的用户输入直接渲染）
|
||||
# 行内评论（绑定文件+行；行号不确定时勿用）
|
||||
gitlink-cli pr +create-comment --id <pr_id> --path <path> --line <n> --body "<意见>"
|
||||
|
||||
### 输出规范
|
||||
# 普通评论（不绑行；安全 fallback）
|
||||
gitlink-cli pr +comment --id <pr_id> --body "<评论>"
|
||||
|
||||
- 始终使用 `--format json` 获取结构化数据
|
||||
- 审查报告输出为 **Markdown 格式**，便于直接粘贴到 PR 评论
|
||||
- 涉及文件/行号时使用精准引用，方便定位
|
||||
- 批量操作前使用 `--dry-run` 预检
|
||||
# 查看已有评审（复审时用）
|
||||
gitlink-cli pr +reviews --id <pr_id> --format json
|
||||
```
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
评审相关操作**优先用上述 Shortcut**。Shortcut 未覆盖时才用 Raw API，且字段需符合 GitLink（**不是** GitHub 的 `event:"COMMENT"`/`position`）：
|
||||
|
||||
```bash
|
||||
# 列出已有评审
|
||||
gitlink-cli api GET /:owner/:repo/pulls/:id/reviews --format json
|
||||
```
|
||||
|
||||
> 字段说明详见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
## 红线与常见错误
|
||||
|
||||
- ❌ **用 GitHub 风格 Raw API 提交评审**（`event:"COMMENT"`、`position`、`commit_id`+`path`）——GitLink 用 `pr +review --status` 与 `pr +create-comment --path --line`。
|
||||
- ❌ **未经用户确认就提交 Review/评论**——必须 报告→确认→dry-run→提交。
|
||||
- ❌ **用 `--yes` 绕过确认门**——除非用户明确要求「直接提交」。
|
||||
- ❌ **行号不确定却发 `+create-comment --line`**——会挂错行或被拒；改并入总报告或用 `+comment`。
|
||||
- ❌ **有 Critical 却用 `--status common/approved`**——Critical 必须配 `rejected`。
|
||||
- ❌ **用 `gh` 操作 GitLink**——只用 `gitlink-cli`。
|
||||
- 所有命令加 `--format json` 便于解析；输出为 `{ok, data, meta}` envelope。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- PR Review 提交后会通知所有关注该 PR 的参与者，评论内容请保持专业
|
||||
- `pr +diff` 输出可能很大（大型 PR），Agent 应分段处理
|
||||
- API 的 PR files 和 diff 接口有频率限制，避免短时间内重复请求
|
||||
- 对于 draft PR（草稿），应提示用户先将其标记为 Ready for Review
|
||||
- Review/评论提交后会通知 PR 所有相关人，内容请专业、可操作。
|
||||
- 大型 PR 的 diff 可能非常大，按文件分段处理，避免一次性塞满上下文。
|
||||
- `pr +diff` / `+files` 接口有频率限制，避免短时间内重复请求。
|
||||
- 对 draft PR，提示用户先标记为 Ready for Review 再审查。
|
||||
- 审查范围限于 PR 本身（代码审查）；仓库整体健康度、Issue 分拣等场景见各自专用 Skill，不在本 Skill 范围。
|
||||
|
|
|
|||
|
|
@ -113,17 +113,50 @@ gitlink-cli pr +diff --id 42 --format json
|
|||
- 有类型注解，代码可读性好
|
||||
```
|
||||
|
||||
### Step 5：提交 Review
|
||||
### Step 5：dry-run 预览（用户确认报告后）
|
||||
|
||||
报告含 2 个 Critical，评审状态取 `rejected`（Request changes）。先 dry-run 预览，**不实际提交**：
|
||||
|
||||
```bash
|
||||
# 提交整体 Review 评论
|
||||
gitlink-cli api POST /Gitlink/forgeplus/pulls/42/reviews --body '{
|
||||
"body": "## PR #42 代码审查报告\n\n### 🔴 Critical\n\n1. **JWT Secret 硬编码** — `src/config.py:15`\n JWT_SECRET 硬编码在源码中。建议使用 `os.getenv(\"JWT_SECRET\")`。\n\n2. **SQL 注入风险** — `src/auth/login.py:42`\n 直接拼接用户输入到 SQL 查询。建议使用参数化查询。\n\n### 🟡 Warning\n\n1. **密码明文存储** — 建议使用 bcrypt 哈希处理。\n\n### 总体评价\n\n代码整体结构清晰，测试覆盖良好。建议修复 Critical 问题后合并。",
|
||||
"event": "COMMENT"
|
||||
}'
|
||||
gitlink-cli pr +review --id 42 \
|
||||
--status rejected \
|
||||
--content "## PR #42 代码审查报告
|
||||
|
||||
### 🔴 Critical
|
||||
1. **JWT Secret 硬编码** — src/config.py:15。建议 os.getenv(\"JWT_SECRET\")。
|
||||
2. **SQL 注入风险** — src/auth/login.py:42。建议参数化查询。
|
||||
|
||||
### 🟡 Warning
|
||||
1. **密码明文存储** — 建议使用 bcrypt 哈希处理。
|
||||
|
||||
### 总体评价
|
||||
代码整体结构清晰，测试覆盖良好。建议修复 Critical 问题后合并。" \
|
||||
--dry-run --format json
|
||||
```
|
||||
|
||||
### Step 6：输出审查摘要
|
||||
→ 核对预览无误，请用户二次确认。
|
||||
|
||||
### Step 6：提交评审（用户确认 dry-run 后）
|
||||
|
||||
去掉 `--dry-run` 正式提交：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +review --id 42 --status rejected --content "<同上审查报告>" --format json
|
||||
```
|
||||
|
||||
### Step 7：行内评论（可选，针对具体行）
|
||||
|
||||
把 Critical 意见精准挂到对应行（行号取文件真实行号，注意 import/头注释偏移；不确定则并入上面的总报告）：
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +create-comment --id 42 --path src/config.py --line 15 \
|
||||
--body "Critical: JWT_SECRET 硬编码，存在泄露风险。改用 os.getenv(\"JWT_SECRET\")。" --format json
|
||||
|
||||
gitlink-cli pr +create-comment --id 42 --path src/auth/login.py --line 42 \
|
||||
--body "Critical: SQL 注入风险，用户输入直接拼接。改用参数化查询。" --format json
|
||||
```
|
||||
|
||||
### Step 8：输出审查摘要
|
||||
|
||||
```markdown
|
||||
## 📋 审查摘要 — PR #42 feat: add user authentication module
|
||||
|
|
@ -159,6 +192,12 @@ gitlink-cli pr +files --id <id> --format json
|
|||
# 获取 Diff
|
||||
gitlink-cli pr +diff --id <id> --format json
|
||||
|
||||
# 提交 Review
|
||||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"...","event":"COMMENT"}'
|
||||
# 提交评审（首选；Critical→rejected / 仅建议→common / 无问题→approved）
|
||||
gitlink-cli pr +review --id <id> --status <common|approved|rejected> --content "<审查报告>" [--dry-run]
|
||||
|
||||
# 行内评论（绑定文件+行；行号不确定时勿用，改用 +comment 或并入 --content）
|
||||
gitlink-cli pr +create-comment --id <id> --path <path> --line <n> --body "<意见>"
|
||||
|
||||
# 普通评论（不绑行）
|
||||
gitlink-cli pr +comment --id <id> --body "<评论>"
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,200 +0,0 @@
|
|||
---
|
||||
name: gitlink-duplicate-detector
|
||||
version: 1.0.0
|
||||
description: "重复 Issue 检测与关联收敛：扫描仓库开放 Issue，按标题+正文做语义相似度聚类，识别重复簇、选出主 Issue，经确认后发布关联评论并（可选）关闭重复项。当用户需要收敛重复 Issue、清理看板、或在处理新 Issue 前查重时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli issue --help"
|
||||
requiresVersion: "需要 gitlink-cli 含 `issue +comments`、`label`、`issue +list --keyword` 的版本（本仓库源码已具备；npm 发布版 v0.1.13 暂缺，待 ≥ v0.2.0）"
|
||||
---
|
||||
|
||||
# gitlink-duplicate-detector（重复 Issue 检测与关联收敛）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作（评论、关闭、打标签）前，务必先确认用户意图；默认 dry-run，只读分析。**
|
||||
|
||||
## 说明
|
||||
|
||||
本 Skill 在**同一 `owner/repo` 内**扫描开放 Issue，对「标题（subject）+ 正文（description）」做语义相似度聚类，找出疑似重复簇，为每个簇选出「主 Issue」，输出结构化《重复 Issue 收敛报告》；经用户逐条确认后，在重复项上发布指向主 Issue 的关联评论，并可（可选）关闭重复项。目的是收敛 Issue 列表、避免重复劳动。
|
||||
|
||||
**与 `gitlink-issue-triage` 的边界**：triage 给单个 Issue **分类打标签/分派**；本 Skill 在 Issue **之间**找重复关系，**不分配类别标签**（至多复用项目已有的「重复/duplicate」标签作为幂等标记）。两者职责正交，可串联。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 已 `gitlink-cli auth login`（`auth status` 为已登录）。
|
||||
- gitlink-cli 版本需支持 `issue +comments`、`label +list`、`issue +list --keyword`、`issue +update --label`（本仓库源码已具备；npm 发布版 v0.1.13 不具备，需用源码编译版或 ≥ v0.2.0）。检查方式：
|
||||
```bash
|
||||
gitlink-cli issue +comments --help # 存在即满足
|
||||
gitlink-cli label --help # 存在即满足
|
||||
```
|
||||
|
||||
## 依赖的 Shortcuts
|
||||
|
||||
| Shortcut | 关键参数 | 用途 |
|
||||
|----------|----------|------|
|
||||
| `issue +list` | `--state/-s`、`--keyword/-k`、`--label`(标签ID)、`-m`、`-a`、`-p`、`-l`、`--format json` | 批量拉取开放 Issue（含 `number`/`subject`/`comment_journals_count`/`tags`/`created_at`） |
|
||||
| `issue +view` | `--number/-n`（**Web 编号**）、`--format json` | 取单条 `description` 正文 |
|
||||
| `issue +comments` | `--number/-n`、`-p`、`-l` | 读已有评论（**幂等检查**：是否已存在关联标记） |
|
||||
| `issue +comment` | `--number/-n`、`--body/-b` | 在重复项上发布「指向主 Issue」的关联评论 |
|
||||
| `issue +close` | `--number/-n`、`--comment/-c` | 关闭重复项（可选，需确认） |
|
||||
| `issue +update` | `--number/-n`、`--label`(标签ID) | 可选：给重复项打「重复」标签（幂等标记） |
|
||||
| `label +list` | — | 确认是否存在「重复/duplicate」标签并取其 ID |
|
||||
|
||||
> ⚠️ `--number` 取的是 **Web URL 编号**（如 `#21`），来自 `issue +list` 返回的 `number` 字段，**不是** `database_id`。
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
1. issue +list --state open --limit 100 --format json
|
||||
→ 取全部开放 Issue（必要时 --page 翻页；大仓可用 --keyword 预筛某主题）
|
||||
2. 取每条的 number / subject / comment_journals_count / tags / created_at
|
||||
3. 粗筛候选对：相同标签、标题共享组件/模块词、或同作者连续提交
|
||||
4. issue +view --number N（仅对候选）
|
||||
→ 取 description 正文，与候选对做相似度比对
|
||||
5. 聚类 + 主从判定 → 生成《重复 Issue 收敛报告》（见下）
|
||||
----- 以上为只读分析，默认到此为止 -----
|
||||
6. （用户确认后）幂等检查（主用评论幂等）：
|
||||
issue +comments --number N → 读 data.journals[]，看 is_journal_detail=false 的 notes
|
||||
是否已有「🔁 疑似重复 / duplicate-of」标记 → 有则跳过
|
||||
再查 status_name=关闭 → 已关闭则跳过
|
||||
7. （用户逐条确认后）写动作：
|
||||
- issue +comment --number N --body "..." → 关联评论（主幂等依据）
|
||||
- issue +close --number N --comment "..." → 可选，关闭重复项
|
||||
- （标签标记 `issue +update --label` 实测不可靠，见「已知限制」，不建议依赖）
|
||||
```
|
||||
|
||||
## 判定规则参考
|
||||
|
||||
### 相似度判定（0–1）
|
||||
|
||||
综合 **词面相似度（标题+正文关键词 Jaccard）** 与 **Agent 语义判断**，给出分数与一句话理由：
|
||||
|
||||
| 分数区间 | 判定 | 建议动作 |
|
||||
|----------|------|----------|
|
||||
| ≥ 0.85 | **高度疑似重复**（正文几乎一致/同作者同时间） | 关联评论 + 建议关闭 |
|
||||
| 0.60–0.85 | **疑似重复**（主题相同，细节有出入） | 关联评论，由人决定是否关闭 |
|
||||
| 0.40–0.60 | **相关但非重复**（同模块不同问题） | 仅在报告里「相关项」列出，**不**关联、**不**关闭 |
|
||||
| < 0.40 | 不相关 | 不处理 |
|
||||
|
||||
> 强信号（任一命中即可显著加分）：正文逐字相同、同作者同一分钟内提交、标题仅序号/编号差异（如 "测试 issue 1" vs "测试 issue 2"）。
|
||||
> 必须避免**过度合并**：症状不同（如「描述丢失」vs「状态框变红」vs「关闭时间缺失」）即使都关于 `+view/+update`，也应判为「相关但非重复」。
|
||||
|
||||
### 主 Issue 选择（每个重复簇选 1 个）
|
||||
|
||||
按优先级依次比较，取首个胜出者：
|
||||
1. `comment_journals_count` 最大（讨论最充分）；
|
||||
2. `created_at` 最早（先提出）；
|
||||
3. 正文 `description` 较长/更完整。
|
||||
|
||||
### 幂等规则（避免重复评论/重复关闭）— 已实测验证
|
||||
|
||||
对每个拟处理的重复项 `N`，执行写动作前：
|
||||
|
||||
1. **评论幂等（主，已验证可靠）**：`issue +comments --number N`，读 `data.journals[]`，**仅看 `is_journal_detail=false` 的条目的 `notes`**；若含标记串（`🔁 疑似重复` / `duplicate-of` / `重复，指向 #`）→ 跳过评论。
|
||||
- 响应结构：`data` 是**对象**，评论在 `data.journals[]`；每条含 `is_journal_detail`（true=系统动态如「创建了疑修/将状态更改为关闭」，false=文字评论）、`notes`（评论正文）、`operate_content`（动态描述）。系统动态 `notes` 为空，须过滤。
|
||||
2. **状态幂等（已验证可靠）**：`issue +list --state closed` 含该编号，或 `+view` 的 `status_name=关闭` → 跳过关闭。
|
||||
3. **标签幂等（不推荐，见「已知限制」）**：`issue +update --label` 实测返回 `ok` 但标签未真正生效，**不可靠**，不要依赖它做幂等判定。
|
||||
|
||||
## 关联评论模板
|
||||
|
||||
在**重复项**上发布（`issue +comment --number <重复项> --body "..."`）：
|
||||
|
||||
```markdown
|
||||
🔁 **疑似重复 Issue**
|
||||
|
||||
本 Issue 与 #<主Issue编号> 描述的问题高度相似，已标记为重复项。
|
||||
- 主 Issue：<主Issue标题> → https://www.gitlink.org.cn/<owner>/<repo>/issues/<主Issue编号>
|
||||
- 相似度：<分数>（<一句话理由>）
|
||||
|
||||
请到主 Issue 继续跟进；如确认重复，本 Issue 将被关闭。
|
||||
（由 gitlink-duplicate-detector 辅助识别，最终以维护者判断为准）
|
||||
```
|
||||
|
||||
关闭时留言（`issue +close --number <重复项> --comment "..."`）：
|
||||
|
||||
```markdown
|
||||
关闭：与 #<主Issue编号> 重复，后续讨论请移步主 Issue。
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
> 以下命令在目标仓库的 git 目录下可省略 `--owner/--repo`（自动从 `git remote origin` 解析）。AI 场景统一加 `--format json`。
|
||||
|
||||
```bash
|
||||
# 0) 前置：确认版本能力 + 登录
|
||||
gitlink-cli auth status
|
||||
gitlink-cli issue +comments --help # 存在 → 版本满足
|
||||
gitlink-cli label +list --owner <o> --repo <r> --format json # 看是否有「重复」标签及 ID
|
||||
|
||||
# 1) 拉取全部开放 Issue（含 number/subject/comment_journals_count/tags/created_at）
|
||||
gitlink-cli issue +list --owner <o> --repo <r> --state open --limit 100 --format json
|
||||
|
||||
# 2) （可选）按主题预筛，缩小比对范围
|
||||
gitlink-cli issue +list --owner <o> --repo <r> --keyword "登录" --state open --format json
|
||||
|
||||
# 3) 对候选对取正文做相似度比对
|
||||
gitlink-cli issue +view --owner <o> --repo <r> --number 11 --format json
|
||||
gitlink-cli issue +view --owner <o> --repo <r> --number 12 --format json
|
||||
|
||||
# 4) 幂等检查：读重复项已有评论，看是否已有关联标记
|
||||
gitlink-cli issue +comments --owner <o> --repo <r> --number 12 --format json
|
||||
|
||||
# 5) 报告输出后，用户确认 → 发布关联评论（写操作，务必先确认）
|
||||
gitlink-cli issue +comment --owner <o> --repo <r> --number 12 \
|
||||
--body "🔁 疑似重复 Issue：本 Issue 与 #11 高度相似（正文逐字一致，相似度 0.98）。主 Issue → https://www.gitlink.org.cn/<o>/<r>/issues/11"
|
||||
|
||||
# 6) ⚠️ 不推荐：打「重复」标签。实测 issue +update --label 返回 ok 但标签未生效，
|
||||
# 不可靠。幂等请依赖步骤 4 的评论标记，而非标签。
|
||||
# gitlink-cli issue +update --owner <o> --repo <r> --number 12 --label 298661
|
||||
|
||||
# 7) 可选：关闭重复项（破坏性，必须确认）
|
||||
gitlink-cli issue +close --owner <o> --repo <r> --number 12 \
|
||||
--comment "关闭：与 #11 重复，后续讨论请移步主 Issue。"
|
||||
```
|
||||
|
||||
## 输出：重复 Issue 收敛报告（Markdown）
|
||||
|
||||
````markdown
|
||||
# 重复 Issue 收敛报告 — <owner>/<repo>
|
||||
|
||||
扫描范围：开放 Issue 共 N 条 | 生成时间：<时间> | 模式：dry-run（只读）
|
||||
|
||||
## 🔴 重复簇 1（高度疑似）
|
||||
- **主 Issue**：#11 `[test] batch-close 测试 issue 1`（作者 wbtiger，2026-05-13，0 评论）
|
||||
- **重复项**：
|
||||
- #12 `[test] batch-close 测试 issue 2` — 相似度 **0.98**（正文逐字相同、同作者同时间）
|
||||
- **建议动作**：在 #12 发关联评论 → （确认后）关闭 #12
|
||||
|
||||
## 🟡 相关但非重复（不合并，仅提示）
|
||||
- 主题「`+view`/`+update` 返回数据异常」：
|
||||
- #15 `issue +view 返回的数据与网页显示不一致`
|
||||
- #5 `认领/执行任务时描述信息消失`
|
||||
- #18 `+update 后状态框变红色`
|
||||
- #14 `pr +view 缺少 PR 关闭时间`
|
||||
→ 症状各异（相似度 0.4–0.55），建议分别处理，不予合并。
|
||||
|
||||
## ✅ 待用户确认的写动作清单
|
||||
| 重复项 | 动作 | 命令 |
|
||||
|--------|------|------|
|
||||
| #12 | 评论 + 关闭 | `issue +comment ...` → `issue +close --comment ...` |
|
||||
````
|
||||
|
||||
> 真实数据跑通的完整报告见 [`examples/duplicate-detection-workflow.md`](examples/duplicate-detection-workflow.md)。
|
||||
|
||||
## 已知限制（实测，v0.2.0-dev / 本地源码版）
|
||||
|
||||
- **`issue +update --label` 不可靠**：实测在 `z2_cc/gitlink_help_center` 上 `--label <id>` 返回 `ok`，但 `+view`/`+list` 的 `tags` 均为空，标签未真正生效。**因此幂等一律以评论（`+comments` 的 `notes` 标记）为准，不要依赖标签。**
|
||||
- **`+comments` 含系统动态**：返回的 `data.journals[]` 混有「创建了疑修 / 状态更改为关闭」等系统动态（`is_journal_detail=true`，`notes` 空）；判定文字评论须过滤 `is_journal_detail=false`。
|
||||
- **`+list` 不含正文**：聚类前对每个候选 `+view` 取 `description`；大仓先用 `--keyword`/作者/时间窗粗筛降量。
|
||||
- **`create`/`view` 不返回 Web 编号**：`issue +create` 与 `+view` 的响应里 `number` 可能为空；Web 编号以 `issue +list` 的 `number` 字段为准。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **默认 dry-run**：首次运行只产出报告，**不**评论/关闭/打标；所有写动作需用户逐条确认。
|
||||
- **不碰他人仓库**：只在你有写权限、或用户明确指定的仓库执行写动作；在他人公开仓只做只读分析。
|
||||
- **`--number` = Web 编号**（来自 `+list` 的 `number` 字段），勿用 `database_id`。
|
||||
- **正文需 `+view` 补取**：`+list` 不含 `description`，聚类前对候选对逐个 `+view`；大仓库注意调用次数，先用 `--keyword`/标签/作者粗筛。
|
||||
- **避免过度合并**：宁可漏报（列「相关项」）不可误并；维护者判断优先。
|
||||
- **幂等**：写动作前用 `+comments` 查标记、用 `tags` 查标签，已处理则跳过。
|
||||
- **不分配类别标签**：与 triage 划清边界；本 Skill 至多使用「重复」这一功能性标记标签。
|
||||
|
|
@ -1,202 +0,0 @@
|
|||
# 重复 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` / 关闭清理），不在帮助中心仓留痕。
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
# 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` 位置对应。
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-issue-triage
|
||||
version: 2.0.0
|
||||
description: "Issue 自动分拣：根据 Issue 内容自动分类、打标签、分配责任人、添加引导评论。包含关键词权重分析和紧急度评估。"
|
||||
version: 1.2.0
|
||||
description: "当用户需要批量处理新提交的 GitLink Issue（自动分类、打标签、分配责任人、添加引导评论）时触发。适用于 Issue 积压无人分流、新 Issue 缺少分类标签、需要按类别指派维护者等场景。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -11,137 +11,207 @@ metadata:
|
|||
# gitlink-issue-triage（Issue 自动分拣）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图；分拣属于批量写入，必须先出方案→用户确认→dry-run 预览→再执行。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||||
|
||||
## 说明
|
||||
## 核心原则
|
||||
|
||||
本 Skill 实现 Issue 的自动化分拣，不仅仅是打标签，还包括**权重分析**和**紧急度评估**。
|
||||
1. **语义分类为主，关键词表为辅**：你是 AI Agent，价值在于读懂 Issue 意图（如「登录后白屏、控制台报 500」即使没有「bug」字眼也应判为 Bug）。下方关键词表只是兜底/加速，不要退化成正则匹配。
|
||||
2. **建议优先，确认后写入**：先输出「分拣方案表」给用户确认，**禁止未经确认直接打标签/改指派人**。尤其禁止用 `--yes` 绕过确认，除非用户明确说「直接应用/不用确认」。
|
||||
3. **幂等**：只处理「尚未分拣」的 Issue（无标签或仅有默认标签），避免对已分拣 Issue 重复操作。
|
||||
4. **打标签用 Raw API，批量仅限同标签**：实测 `issue +update --label` 不可用、`+batch-update --label` 是集合式（整组标签打到每个 Issue），故各 Issue 不同标签时用 Raw API `issue_tag_ids`（详见 Step 5）；仅当多 Issue 共用同一标签时才用 `+batch-update`。
|
||||
|
||||
## 分析流程
|
||||
## 工作流概览
|
||||
|
||||
```
|
||||
1. issue +list --state open → 获取所有待处理的 Issue
|
||||
2. issue +view --number {id} → 逐条查看详情
|
||||
3. 关键词权重分析 → 判断分类和紧急度
|
||||
4. label +list → 查看可用标签
|
||||
5. issue +update → 打标签、分配
|
||||
6. issue +comment → 添加引导评论
|
||||
```
|
||||
| 阶段 | 操作 | 命令 |
|
||||
|------|------|------|
|
||||
| ① 解析 ID（必做前置） | 取仓库标签/可指派人/优先级，建立 名称→ID 映射 | `label +list` / `label +assigners` / `label +priorities` |
|
||||
| ② 取未分拣 Issue | 拉取 open Issue，客户端筛掉已打标签的 | `issue +list` |
|
||||
| ③ 语义分析 | 逐个读标题+描述，判类别/标签/责任人/评论 | `issue +view` |
|
||||
| ④ 出方案 | 输出「分拣方案表」，等用户确认 | （无写入） |
|
||||
| ⑤ 打标签 | 用户确认后，逐 Issue 用 Raw API 打标签（不同标签）；同标签可批量 | `api PATCH .../issues/:n` / `+batch-update` |
|
||||
| ⑥ 引导评论 | 为每个 Issue 添加分类引导评论 | `issue +comment` |
|
||||
|
||||
## 关键词权重分类系统
|
||||
---
|
||||
|
||||
不再简单匹配关键词，而是引入**权重评分**：
|
||||
## 详细工作流
|
||||
|
||||
| 类别 | 关键词 | 权重分 | 建议标签 |
|
||||
|------|--------|--------|---------|
|
||||
| Bug | bug(10)、错误(8)、失败(7)、异常(6)、crash(10)、报错(5) | ≥15 | bug |
|
||||
| 功能需求 | 建议(8)、希望(7)、需要(5)、feature(8)、支持(4)、新增(5) | ≥12 | enhancement |
|
||||
| 文档 | 文档(10)、README(8)、拼写(5)、缺少(4)、帮助(3) | ≥10 | documentation |
|
||||
| 安全 | 漏洞(10)、安全(8)、权限(7)、泄露(8)、注入(6) | ≥12 | security |
|
||||
| 性能 | 慢(8)、卡顿(7)、性能(6)、优化(5)、performance(8) | ≥10 | performance |
|
||||
| 问题咨询 | 请问(5)、怎么(5)、如何(4)、help(3)、? (2) | ≥6 | question |
|
||||
### Step 1：解析 ID（**必做前置，切勿跳过**）
|
||||
|
||||
**评分方式：** 将 Issue 标题和描述分词后，匹配上表关键词，按权重累加。得分最高的类别即为分类结果。
|
||||
|
||||
## 紧急度评估
|
||||
|
||||
```
|
||||
紧急度 = Bug权重分 × 1.5 + 安全权重分 × 2.0 + 其他权重分 × 1.0
|
||||
|
||||
判定标准：
|
||||
- ≥20 → 🔴 P0 紧急：立即处理
|
||||
- 12-19 → 🟡 P1 高优先：尽快处理
|
||||
- 6-11 → 🟢 P2 普通：正常排期
|
||||
- <6 → 🔵 P3 低优先：后续处理
|
||||
```
|
||||
|
||||
## 分配责任人规则
|
||||
|
||||
```
|
||||
根据 Issue 类型分配责任人：
|
||||
- Bug → 分配最近修改相关文件的人（通过 git blame）
|
||||
- 功能需求 → 分配 PM 或项目维护者
|
||||
- 文档 → 分配文档负责人
|
||||
- 安全 → 直接通知项目管理员
|
||||
- 问题咨询 → 分配社区支持
|
||||
```
|
||||
|
||||
## 完整处理示例
|
||||
GitLink 的标签、指派人、优先级参数都吃 **ID 而非名称**。先拉取并建立映射：
|
||||
|
||||
```bash
|
||||
# 1. 获取待处理 Issue
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state open --format json
|
||||
# 标签：name → id（返回在 data.issue_tags[]；标签名因仓库而异，如某仓库为 缺陷/功能/疑问/文档…）
|
||||
gitlink-cli label +list --format json
|
||||
|
||||
# 可指派人：login → id（如 alice→101）
|
||||
gitlink-cli label +assigners --format json
|
||||
|
||||
# 优先级：name → id（数值因仓库而异，如某仓库为 低→1/正常→2/高→3/紧急→4，以实际输出为准）
|
||||
gitlink-cli label +priorities --format json
|
||||
```
|
||||
|
||||
**输出分析：**
|
||||
```json
|
||||
{
|
||||
"issues": [
|
||||
{"number": 42, "subject": "登录页面报错：500 Internal Server Error"},
|
||||
{"number": 43, "subject": "建议增加导出功能"},
|
||||
{"number": 44, "subject": "README 中缺少安装说明"}
|
||||
]
|
||||
}
|
||||
```
|
||||
> 没有 ID 映射就无法正确执行 Step ⑤⑥。若目标标签不存在，见 Step 4「补建标签」。
|
||||
|
||||
**AI 分析结果：**
|
||||
```
|
||||
Issue #42: 关键词匹配 → "报错"(5) + "500"(0) = 5分 → Bug
|
||||
紧急度评分 → 5 × 1.5 = 7.5 → 🟡 P2 普通
|
||||
建议标签: bug
|
||||
|
||||
Issue #43: 关键词匹配 → "建议"(8) + "增加"(5) = 13分 → 功能需求
|
||||
紧急度评分 → 13 × 1.0 = 13 → 🟡 P1 高优先
|
||||
建议标签: enhancement
|
||||
|
||||
Issue #44: 关键词匹配 → "文档"(10) + "缺少"(4) = 14分 → 文档
|
||||
紧急度评分 → 14 × 1.0 = 14 → 🟡 P1 高优先
|
||||
建议标签: documentation
|
||||
```
|
||||
### Step 2：取未分拣 Issue（幂等筛选）
|
||||
|
||||
```bash
|
||||
# 2. 为 Bug Issue 添加分类评论
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 42 --body "## Issue 自动分类结果
|
||||
|
||||
**类别：** 🐛 Bug
|
||||
**紧急度：** 🟡 P2 普通优先级
|
||||
**建议标签：** bug
|
||||
|
||||
### 分类依据
|
||||
标题中包含关键词「报错」，匹配 Bug 分类。
|
||||
|
||||
### 请补充以下信息
|
||||
1. 运行环境（操作系统、浏览器版本）
|
||||
2. 复现步骤
|
||||
3. 错误截图或日志
|
||||
4. 是否必现
|
||||
|
||||
### 自动分配
|
||||
已将 Issue 分配给 @maintainer。"
|
||||
# 拉取所有 open Issue
|
||||
gitlink-cli issue +list --state open --format json
|
||||
```
|
||||
|
||||
筛选规则（客户端过滤）：**保留尚未打标签的 Issue**（`tags` 字段为空），跳过已有分类标签的，避免重复分拣。
|
||||
|
||||
### Step 3：语义分析
|
||||
|
||||
对每个待分拣 Issue：
|
||||
|
||||
```bash
|
||||
# 3. 为功能需求 Issue 添加评论
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 43 --body "## Issue 自动分类结果
|
||||
|
||||
**类别：** ✨ 功能需求
|
||||
**紧急度：** 🟡 P1 高优先
|
||||
**建议标签：** enhancement
|
||||
|
||||
### 分类依据
|
||||
标题中包含关键词「建议」「增加」，匹配功能需求分类。
|
||||
|
||||
### 请补充以下信息
|
||||
1. 这个功能解决了什么场景的问题？
|
||||
2. 期望的行为是什么？
|
||||
3. 是否有参考实现？
|
||||
|
||||
感谢你的建议！项目组会评估这个需求的可行性。"
|
||||
gitlink-cli issue +view --number <issue_number> --format json
|
||||
```
|
||||
|
||||
读取 `subject` + `description`，按下方「分类规则参考」判断类别、推荐标签、推荐责任人角色、引导评论要点。
|
||||
|
||||
### Step 4：出「分拣方案表」（建议，不写入）
|
||||
|
||||
输出一张表给用户确认，**此阶段不执行任何写入**：
|
||||
|
||||
```markdown
|
||||
| # | 标题 | 判定类别 | 标签(id) | 责任人(id) | 评论文案要点 |
|
||||
|---|------|---------|----------|-----------|-------------|
|
||||
| 12 | 登录后白屏 500 | Bug | bug(1) | bob(102) | 请补浏览器/复现步骤/后端日志 |
|
||||
| 13 | 希望支持暗黑模式 | Feature | enhancement(2) | alice(101) | 请确认范围：全局/页面级、是否跟随系统 |
|
||||
```
|
||||
|
||||
**补建标签（可选）**：若方案需要的标签在 `label +list` 中不存在（如缺 `bug`），不要静默跳过，也**不要擅自创建**——在方案表中标注「标签缺失」，待用户确认后用 `gitlink-cli label +create --name bug` 创建，再继续。
|
||||
|
||||
**等待用户确认**：用户没说「确认/执行」前，停在 Step 4。**禁止用 `--yes` 自行推进。**
|
||||
|
||||
### Step 5：打标签（用户确认方案后）
|
||||
|
||||
> ⚠️ **实测要点（2026-06-15 端到端验证）**：
|
||||
> - `issue +update --label <id>` **不可用**——CLI 发送单数 `issue_tag_id`，平台忽略，标签打不上。
|
||||
> - `issue +batch-update --label a,b,c` 是**集合式**：把 `{a,b,c}` 打到 `--numbers` 里**每一个** Issue，**不是**按位置对应。仅适合「多个 Issue 共用同一(组)标签」。
|
||||
> - 可用的打标签方式是 Raw API 的 `issue_tag_ids`（复数数组）。
|
||||
|
||||
**情形 A：各 Issue 标签不同（最常见）→ 逐 Issue 用 Raw API（已验证）：**
|
||||
|
||||
```bash
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/<number> --body '{
|
||||
"issue_tag_ids": [<标签id>],
|
||||
"subject": "<原标题>",
|
||||
"description": "<原描述>"
|
||||
}'
|
||||
```
|
||||
|
||||
`issue_tag_ids` 是数组，**整体替换**该 Issue 的标签集；务必回带 `subject`/`description`，否则描述会被清空（见 gitlink-shared 已知坑）。
|
||||
|
||||
**情形 B：多个 Issue 共用同一标签 → 批量（先 dry-run 再执行）：**
|
||||
|
||||
```bash
|
||||
# dry-run 预览（同一标签打到这批所有 Issue）
|
||||
gitlink-cli issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run --format json
|
||||
# 核对后去掉 --dry-run 正式执行
|
||||
```
|
||||
|
||||
**指派人**：`issue +update --number <n> --assignee <user_id>`（`user_id` 来自 `label +assigners`）。若 `label +assigners` 为空（如个人仓库无可指派成员），**留空并在方案表注明**，不要乱指派。
|
||||
|
||||
### Step 6：引导评论
|
||||
|
||||
为每个 Issue 添加分类引导评论（语气专业，包含分类理由 + 需要补充的信息）：
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +comment --number 12 --body "已自动分拣为 **Bug**，转交 @bob。
|
||||
为加快定位，请补充：运行环境、复现步骤、浏览器控制台与后端日志。维护者会尽快处理。"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 分类规则参考
|
||||
|
||||
### 类别判定（语义优先，关键词兜底）
|
||||
|
||||
| 类别 | 语义信号 | 关键词兜底 | 建议标签 | 责任人角色 |
|
||||
|------|---------|-----------|----------|-----------|
|
||||
| Bug | 运行时报错、崩溃、行为异常、阻断主流程 | 错误/失败/异常/crash/报错/500/白屏 | bug | 后端或前端（按错误来源） |
|
||||
| 功能需求 | 希望新增能力、改进现有行为 | 建议/希望/需要/feature/支持 | enhancement | PM / 对应模块开发 |
|
||||
| 文档 | 文档缺失/错误/拼写 | 文档/README/拼写 | documentation | 文档负责人 |
|
||||
| 问题咨询 | 询问用法、求助 | 请问/怎么/如何/help/question | question | 社区支持 / 文档 |
|
||||
| 性能 | 慢、卡顿、资源占用 | 慢/卡顿/性能/优化/performance | performance | 核心开发者 |
|
||||
|
||||
> 上表「建议标签」是语义类别名，**实际标签名以 `label +list` 为准**——GitLink 默认标签是中文（缺陷/功能/疑问/文档/任务…），需先把类别映射到仓库实际标签的 ID 再打。
|
||||
|
||||
### 角色 → 默认责任人映射（需用 `label +assigners` 的实际 ID 替换）
|
||||
|
||||
| 角色 | 何时指派 |
|
||||
|------|---------|
|
||||
| 后端 | 服务端错误、API、数据库相关 |
|
||||
| 前端 | UI、样式、浏览器端错误 |
|
||||
| PM | 需求范围、优先级决策 |
|
||||
| 文档 | 文档/问答类 |
|
||||
| 核心开发者 | 性能、架构、安全 |
|
||||
|
||||
> 实际指派时，把「角色」替换为 `label +assigners` 中对应的 **user_id**。若角色无对应成员，**留空并在方案表注明**，不要乱指派。
|
||||
|
||||
---
|
||||
|
||||
## 命令速查
|
||||
|
||||
```bash
|
||||
# 前置：解析 ID
|
||||
gitlink-cli label +list --format json # 标签 name→id
|
||||
gitlink-cli label +assigners --format json # 可指派人 login→id
|
||||
gitlink-cli label +priorities --format json # 优先级 name→id
|
||||
gitlink-cli label +create --name <name> --color <hex> # 补建缺失标签（确认后）
|
||||
|
||||
# 分拣主体
|
||||
gitlink-cli issue +list --state open --format json # 取未分拣（客户端筛 tags 为空的）
|
||||
gitlink-cli issue +view --number <n> --format json # 读详情做语义分析（标签字段为 tags）
|
||||
|
||||
# 打标签（已验证可用）：
|
||||
# - 各 Issue 不同标签 → 逐个 Raw API（issue_tag_ids 整体替换）
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/<n> --body '{"issue_tag_ids":[<id>],"subject":"<原>","description":"<原>"}'
|
||||
# - 多 Issue 共用同一标签 → 批量（集合式，先 --dry-run）
|
||||
gitlink-cli issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run
|
||||
|
||||
gitlink-cli issue +comment --number <n> --body "<引导评论>" # 引导评论
|
||||
gitlink-cli issue +update --number <n> --assignee <user_id> # 指派人（user_id 来自 label +assigners）
|
||||
```
|
||||
|
||||
> ⚠️ `issue +update --label` 与 `+batch-update --label a,b,c`（多标签）均不可靠，详见红线。
|
||||
|
||||
---
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
打标签的**主要可用方式**是 Raw API（Shortcut 的 `--label` 不可靠，见红线）。务必回带 `subject`/`description` 防清空：
|
||||
|
||||
```bash
|
||||
# 打标签（issue_tag_ids 为标签 ID 数组，整体替换该 Issue 标签集）
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/:number --body '{
|
||||
"issue_tag_ids": [<tag_id>, ...],
|
||||
"subject": "<原标题>",
|
||||
"description": "<原描述>"
|
||||
}'
|
||||
```
|
||||
|
||||
> 字段说明详见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
---
|
||||
|
||||
## 红线与常见错误
|
||||
|
||||
- ❌ **未经用户确认就打标签/指派**——必须方案表→确认→执行。
|
||||
- ❌ **用 `--yes` 绕过确认门**——除非用户明确要求「直接应用」。
|
||||
- ❌ **用 `issue +update --label` 打标签**——实测 CLI 发单数 `issue_tag_id` 被平台忽略，标签打不上；改用 Raw API `issue_tag_ids`（Step 5）。
|
||||
- ❌ **用 `+batch-update --label a,b,c` 给不同 Issue 打不同标签**——它是集合式，会把 {a,b,c} 全打到每个 Issue；仅用于多 Issue 共用同一标签。
|
||||
- ❌ **把标签名称当 ID 传**——必须先用 `label +list` 解析为 ID（返回在 `data.issue_tags[]`，标签名以实际为准）。
|
||||
- ❌ **重复分拣已分类 Issue**——Step 2 客户端筛掉 `tags` 非空的。
|
||||
- ❌ **用 `gh` 操作 GitLink**——只用 `gitlink-cli`。
|
||||
- 所有命令加 `--format json` 便于解析；输出为 `{ok, data, meta}` envelope。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 使用**权重评分**代替简单的关键词匹配，减少误分类。
|
||||
- 每次评论前检查 Issue 是否已有相同内容的评论，避免重复。
|
||||
- 分配责任人前需确认该用户是否为项目成员。
|
||||
- 安全类 Issue（漏洞、权限）应直接通知管理员，不在评论中公开细节。
|
||||
- 分拣是批量写入，评论会通知 Issue 相关人，内容请专业、可操作。
|
||||
- `issue +list` 的 `--state` 仅影响统计计数，列表可能含全部状态，需客户端二次过滤。
|
||||
- 若 Issue 描述信息不足以判定类别，在方案表标注「信息不足，建议先发评论索取复现信息」，不要强行分类。
|
||||
|
|
|
|||
|
|
@ -1,81 +1,188 @@
|
|||
# Issue 自动分拣完整工作流示例
|
||||
# Issue 批量自动分拣完整工作流示例
|
||||
|
||||
**场景**：项目收到一个新 Issue，需要自动判断类别、打标签、添加引导评论。
|
||||
**场景**：仓库 `z2_cc/gitlink-cli` 积压了一批未分类的 open Issue，需要批量分流：自动判定类别、打标签、指派责任人、添加引导评论。
|
||||
|
||||
> 本示例遵循 SKILL.md 的核心原则：**语义分类为主、建议优先确认后写入、幂等、批量为主**。所有写入操作都经过「方案→确认→dry-run→执行」四步。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `gitlink-cli` 已安装并登录
|
||||
- `gitlink-cli` 已安装并登录（`gitlink-cli auth status` 正常）
|
||||
- 对目标仓库有写入权限
|
||||
- 已阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)
|
||||
|
||||
## 工作流步骤
|
||||
---
|
||||
|
||||
### Step 1：查看待处理的 Issue
|
||||
## Step 1：解析 ID（建立 名称→ID 映射）
|
||||
|
||||
```bash
|
||||
gitlink-cli label +list --format json
|
||||
gitlink-cli label +assigners --format json
|
||||
gitlink-cli label +priorities --format json
|
||||
```
|
||||
|
||||
**`label +list` 输出示例：**
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": { "labels": [
|
||||
{"id": 1, "name": "bug"},
|
||||
{"id": 2, "name": "enhancement"},
|
||||
{"id": 3, "name": "documentation"},
|
||||
{"id": 4, "name": "question"},
|
||||
{"id": 5, "name": "performance"}
|
||||
]}
|
||||
}
|
||||
```
|
||||
|
||||
**`label +assigners` 输出示例：**
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": { "assigners": [
|
||||
{"id": 101, "login": "alice", "name": "前端组"},
|
||||
{"id": 102, "login": "bob", "name": "后端组"},
|
||||
{"id": 103, "login": "carol", "name": "文档组"}
|
||||
]}
|
||||
}
|
||||
```
|
||||
|
||||
→ 建立映射：标签 `bug→1, enhancement→2, question→4`；指派人 `alice→101, bob→102, carol→103`。
|
||||
|
||||
## Step 2：取未分拣 Issue（客户端筛掉已打标签的）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state open --format json
|
||||
```
|
||||
|
||||
**输出示例：**
|
||||
筛出**尚未打标签**的 3 个（已分类的跳过，保证幂等）：
|
||||
|
||||
| number | subject | labels |
|
||||
|--------|---------|--------|
|
||||
| 12 | 登录后页面白屏，控制台报 500 | （空） |
|
||||
| 13 | 希望能支持暗黑模式 | （空） |
|
||||
| 14 | 请问怎么配置 webhook？ | （空） |
|
||||
|
||||
## Step 3：语义分析（逐个读详情）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 12 --format json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"issues": [
|
||||
{
|
||||
"number": 10,
|
||||
"subject": "登录页面报错：500 Internal Server Error",
|
||||
"status_id": 1,
|
||||
"author": {"login": "newuser"}
|
||||
}
|
||||
]
|
||||
"ok": true,
|
||||
"data": { "issue": {
|
||||
"number": 12,
|
||||
"subject": "登录后页面白屏，控制台报 500",
|
||||
"description": "输入账号密码点登录后页面直接白屏，浏览器控制台显示 500 Internal Server Error。Chrome 120 / macOS。"
|
||||
}}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2：查看 Issue 详细内容
|
||||
**语义判定（注意 #12 没有「bug」字眼，靠语义识别）：**
|
||||
- **#12**：500 + 阻断登录主流程 → **Bug**；500 是服务端响应 → 后端 bob
|
||||
- **#13**：「希望支持暗黑模式」→ **功能需求 enhancement**；UI/样式 → 前端 alice
|
||||
- **#14**：「请问怎么配置 webhook」→ **问题咨询 question**；答疑 → 文档 carol
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 10 --format json
|
||||
## Step 4：出「分拣方案表」（建议，不写入，等用户确认）
|
||||
|
||||
```
|
||||
分拣方案（共 3 个 Issue，请确认后我将 dry-run 预览）：
|
||||
|
||||
| # | 标题 | 类别 | 标签(id) | 责任人(id) |
|
||||
|-----|----------------------|----------|-----------------|-------------|
|
||||
| 12 | 登录后白屏 500 | Bug | bug(1) | bob(102) |
|
||||
| 13 | 希望支持暗黑模式 | Feature | enhancement(2) | alice(101) |
|
||||
| 14 | 请问怎么配置 webhook | Question | question(4) | carol(103) |
|
||||
|
||||
引导评论将分别请求：#12 复现步骤/后端日志；#13 主题范围确认；#14 直接答复+文档化。
|
||||
确认执行吗？（回复「确认」我进入 dry-run 预览；如需调整请指出）
|
||||
```
|
||||
|
||||
### Step 3：分析 Issue 内容判断类别
|
||||
> ⏸️ **停在此处等用户确认。禁止用 `--yes` 自行推进。**
|
||||
|
||||
根据标题和描述中的关键词判断：
|
||||
## Step 5：打标签（用户确认方案后）
|
||||
|
||||
| 关键词 | 类别 |
|
||||
|--------|------|
|
||||
| 报错、错误、bug | Bug |
|
||||
| 建议、希望 | 功能需求 |
|
||||
| 文档 | 文档 |
|
||||
| 请问、怎么 | 问题咨询 |
|
||||
|
||||
### Step 4：添加分类评论
|
||||
> ⚠️ 各 Issue 标签不同，**用 Raw API 逐个打**（实测 `issue +update --label` 不可用、`+batch-update --label` 是集合式，见 SKILL.md 红线）。务必回带 `subject`/`description` 防清空。
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 10 --body "感谢提交 Issue！已自动分类为 **Bug**。
|
||||
|
||||
请补充以下信息以便排查：
|
||||
- 运行环境（操作系统、浏览器版本）
|
||||
- 复现步骤
|
||||
- 错误截图或日志
|
||||
|
||||
项目维护者会尽快处理。"
|
||||
# #12 → bug(1)
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/12 --body '{
|
||||
"issue_tag_ids": [1], "subject": "登录后页面白屏，控制台报 500",
|
||||
"description": "输入账号密码点登录后页面直接白屏，控制台显示 500 Internal Server Error。Chrome 120/macOS。"
|
||||
}'
|
||||
# #13 → enhancement(2)
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/13 --body '{
|
||||
"issue_tag_ids": [2], "subject": "希望能支持暗黑模式", "description": "希望加暗黑主题切换。"
|
||||
}'
|
||||
# #14 → question(4)
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/14 --body '{
|
||||
"issue_tag_ids": [4], "subject": "请问怎么配置 webhook？", "description": "想把推送事件通知到群机器人。"
|
||||
}'
|
||||
```
|
||||
|
||||
### Step 5：确认处理结果
|
||||
> 多个 Issue **共用同一标签**时，可改用批量：`issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run` → 去 `--dry-run`。
|
||||
> 指派人：`issue +update --number <n> --assignee <user_id>`（`user_id` 来自 `label +assigners`；无可指派人则留空）。
|
||||
|
||||
**验证打标结果：**
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 10 --format json
|
||||
gitlink-cli issue +view --number 12 --format json # data.issue.tags 应为 [{"id":1,"name":"bug"}]
|
||||
```
|
||||
|
||||
## Step 6：引导评论（逐个添加）
|
||||
|
||||
```bash
|
||||
# #12 Bug
|
||||
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 12 \
|
||||
--body "已自动分拣为 **Bug**，转交 @bob。为加快定位，请补充：运行环境、稳定复现步骤、浏览器控制台与后端对应时间点的报错日志。"
|
||||
|
||||
# #13 Feature
|
||||
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 13 \
|
||||
--body "已自动分拣为 **enhancement**，转交 @alice。落地前请确认范围：① 全局暗黑主题还是特定页面；② 是否跟随系统 prefers-color-scheme；③ 配色基准。"
|
||||
|
||||
# #14 Question
|
||||
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 14 \
|
||||
--body "已自动分拣为 **question**，转交 @carol。快速回答：Webhook 在「仓库设置 → Webhooks」新增，填回调 URL、选触发事件，GitLink 会向该 URL 发 POST。完整字段说明将补充到 docs/。"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整命令速览
|
||||
## 命令速览
|
||||
|
||||
```bash
|
||||
# 1. 获取待处理 Issue
|
||||
gitlink-cli issue +list --state open
|
||||
# 1. 解析 ID
|
||||
gitlink-cli label +list --format json
|
||||
gitlink-cli label +assigners --format json
|
||||
|
||||
# 2. 查看详情
|
||||
gitlink-cli issue +view --number <id>
|
||||
# 2. 取未分拣 Issue（客户端筛无标签的）
|
||||
gitlink-cli issue +list --state open --format json
|
||||
|
||||
# 3. 添加分类评论
|
||||
gitlink-cli issue +comment --number <id> --body "<评论内容>"
|
||||
# 3. 语义分析
|
||||
gitlink-cli issue +view --number <n> --format json
|
||||
|
||||
# 4. 出方案表 → 用户确认（不写入）
|
||||
|
||||
# 5. 打标签：各 Issue 不同标签 → 逐个 Raw API（issue_tag_ids 整体替换）
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/<n> --body '{"issue_tag_ids":[<id>],"subject":"<原>","description":"<原>"}'
|
||||
# 多 Issue 共用同一标签 → 批量（先 --dry-run）
|
||||
gitlink-cli issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run
|
||||
|
||||
# 6. 引导评论
|
||||
gitlink-cli issue +comment --number <n> --body "<评论>"
|
||||
```
|
||||
|
||||
## 退化场景：单个 Issue
|
||||
|
||||
只需分拣一个 Issue 时：
|
||||
|
||||
```bash
|
||||
# 打标签（Raw API；+update --label 实测不可用）
|
||||
gitlink-cli api PATCH /:owner/:repo/issues/<n> --body '{"issue_tag_ids":[<id>],"subject":"<原标题>","description":"<原描述>"}'
|
||||
# 指派人（可选）
|
||||
gitlink-cli issue +update --number <n> --assignee <user_id>
|
||||
# 引导评论
|
||||
gitlink-cli issue +comment --number <n> --body "<评论>"
|
||||
```
|
||||
|
||||
同样遵循「方案→确认→执行」，不要直接 `--yes`。
|
||||
|
|
|
|||
|
|
@ -1,205 +0,0 @@
|
|||
---
|
||||
name: gitlink-pr-deep-review
|
||||
version: 1.0.0
|
||||
description: "PR 深度审查：编排代码质量审查 + 自研推理层，综合评估一个 PR 的实现质量、跨模块影响、需求/设计一致性、业务安全合规，给出综合裁决与动作建议。当用户需要深度审查 Pull Request、判断改动是否对得起需求/是否影响其他模块时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli pr --help"
|
||||
requiresVersion: "需要 gitlink-cli 含 `pr +versions/+version-diff/+review` 的版本（本仓库源码已具备；npm 发布版 v0.1.13 能力不全，需源码编译版或 ≥ v0.2.0）"
|
||||
---
|
||||
|
||||
# gitlink-pr-deep-review（PR 深度审查）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入操作（回贴评审/评论）前，务必先确认用户意图；默认 dry-run，综合评审一律用 `--status common`（评论），不替人 approve/reject。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`，禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
## 说明
|
||||
|
||||
本 Skill 围绕 **PR 审查**提供深度服务：对给定 PR，**编排** `gitlink-code-review`（或 linter）取得"实现层"质量结果，再叠加本 Skill 的**自研推理层**——跨模块影响、需求/设计一致性、业务级安全/合规——交叉合成一份综合评审报告，给出风险评分与动作建议（阻断/谨慎/放行），并可在确认后回贴到 PR。
|
||||
|
||||
它**不重复** code-review 的风格/缺陷检测，而是**消费**其结果作为风险输入，专注于 code-review 回答不了的问题：**这个改动该不该这样改、会牵动什么、对不对得起它的目标。**
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 已 `gitlink-cli auth login`（`auth status` 为已登录）。
|
||||
- gitlink-cli 版本需支持 `pr +versions` / `+version-diff` / `+review`（本仓库源码已具备；npm 发布版 v0.1.13 不具备）。
|
||||
- **本地有目标仓库的 clone**（跨模块调用方用 `git grep`、设计文档用本地读取）。
|
||||
- （可选）读过 [`../gitlink-code-review/SKILL.md`](../gitlink-code-review/SKILL.md)，便于编排其实现层工作流。
|
||||
|
||||
## 与 `gitlink-code-review` 的边界
|
||||
|
||||
| 维度 | `gitlink-code-review`（被编排） | `gitlink-pr-deep-review`（本 Skill） |
|
||||
|---|---|---|
|
||||
| 审查对象 | 代码**本身**（diff 内在质量） | 改动的**意图、设计、跨模块影响** |
|
||||
| 核心问题 | 代码写得对不对/好不好 | 该不该这样改、会牵动什么、对不对得起目标 |
|
||||
| 视角 | 单文件、当下 | 跨文件、关联需求/架构 |
|
||||
| 工作性质 | 机械检测为主 | 推理判断为主 |
|
||||
| 关系 | 上游信号 | 编排者 + 综合裁决 |
|
||||
|
||||
> 职责正交：code-review 管"实现质量"，本 Skill 管"设计/意图/影响一致性"，可串联。
|
||||
|
||||
## 依赖的 Shortcuts
|
||||
|
||||
| Shortcut | 关键参数 | 用途 |
|
||||
|----------|----------|------|
|
||||
| `pr +view` | `--id <Web#>`、`--format json` | 标题=`data.issue.subject`，**正文=`data.issue.description`（嵌套）**；`comments_count` |
|
||||
| `pr +files` | `--id` | 变更文件列表 |
|
||||
| `pr +version-diff` | `--id`、`--version-id` | **真实 diff 内容**（version_id 来自 `+versions`） |
|
||||
| `pr +versions` | `--id` | patchset 列表，取 `version_id` |
|
||||
| `pr +reviews` | `--id` | 已有评审（避免重复回贴） |
|
||||
| `pr +review` | `--id`、`--status common`、`--content`、`--dry-run` | 回贴综合评审（默认 dry-run） |
|
||||
| `pr +commits` / `pr +comments` | `--id` | 提交 / 评审行内评论（上下文） |
|
||||
| `issue +view` | `--number <Web#>` | 关联 Issue 需求锚点 |
|
||||
| `git grep`（本地） | `git grep -n "<symbol>" -- '*.ext'` | 跨模块**直接调用方** |
|
||||
| 本地文件 `git show`/Read | — | 设计文档读取 |
|
||||
|
||||
> ⚠️ `--id` 取 **Web 编号**（`pr +list` 的 `pull_request_number`），非内部 `id`。
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
1. pr +view --id <N> → 取标题/正文（issue.subject / issue.description）
|
||||
2. pr +files --id <N> → 变更文件清单
|
||||
pr +versions --id <N> → 取 version_id
|
||||
pr +version-diff --id <N> --version-id <V> → 真实 diff
|
||||
3. 锚点获取（见下「锚点获取流程」） → 需求/设计一致性依据
|
||||
4. 编排实现层：按 gitlink-code-review/SKILL.md 跑实现层审查
|
||||
→ 取分级问题清单（Critical/Warning/Suggestion）作为风险输入
|
||||
5. 跨模块影响：对改动符号 git grep 找直接调用方 → 标破坏性变更
|
||||
6. 推理层：需求/设计一致性 + 业务安全/合规一致性（对照锚点）
|
||||
7. 综合裁决：实现层 + 影响 + 一致性 + 安全 交叉 → 风险评分 + 动作建议
|
||||
----- 以上为只读分析，默认到此为止 -----
|
||||
8. （确认后）pr +review --id <N> --status common --content "<综合报告>" [--dry-run]
|
||||
```
|
||||
|
||||
## 锚点获取流程（需求一致性审查的依据）
|
||||
|
||||
需求/设计一致性需要一个"锚点"（正确性的参照）。按下列**交互式决策树**获取：
|
||||
|
||||
```
|
||||
Step A：询问使用者 —— 仓库中是否有与该 PR 相关的设计/需求文档？
|
||||
├─ 有 → 使用者提供文档路径（仓库内相对路径）→ 本地读取（git show <path> / Read）→ design_doc
|
||||
└─ 无 → design_doc = ∅
|
||||
|
||||
Step B：自动检测 PR 关联 Issue
|
||||
└─ pr +view 的 issue.description 里正则提取 #N → issue +view --number N → linked_issue
|
||||
（无 #N 则 linked_issue = ∅）
|
||||
|
||||
Step C：组合锚点
|
||||
├─ design_doc ✓ + linked_issue ✓ → 锚点 = 两者合并（Issue=需求源，文档=设计源）【置信度高】
|
||||
├─ 仅其一 → 锚点 = 该单一来源【置信度中】
|
||||
└─ 两者皆无 → 锚点 = PR 标题/描述自述目标；报告显著标注
|
||||
「⚠️ 无外部需求锚点，一致性结论置信度降低」【置信度低】
|
||||
```
|
||||
|
||||
> 无锚点时**不要拒绝审查**，而是降级为"以 PR 自述目标为准"，并明确标注置信度。
|
||||
|
||||
## 评审维度与规则
|
||||
|
||||
### ① 实现层（编排 `gitlink-code-review`）
|
||||
- 调度 code-review 工作流（或项目 linter），取其分级问题清单。
|
||||
- 本 Skill **不重新检测**风格/缺陷，只**消费**：把 Critical/Warning 数量与位置作为风险输入。
|
||||
|
||||
### ② 跨模块影响（机械，自研）
|
||||
- 从 diff 提取**改动符号**（函数名、类型名、导出标识）。
|
||||
- 对每个符号 `git grep -n "<symbol>" -- '<glob>'` 找**直接调用方**（仅一层，不追传递依赖）。
|
||||
- 标注破坏性变更：签名改变/删除/重命名 → 受影响调用方清单 + 影响范围分级（核心模块/边缘/无）。
|
||||
|
||||
### ③ 需求/设计一致性（推理，自研）
|
||||
- 以**锚点**判断：PR 是否真正实现了需求？设计是否与现有架构一致？有无过度设计/设计缺陷？
|
||||
- 锚点缺失时降级（见上），结论标注低置信度。
|
||||
|
||||
### ④ 业务级安全/合规一致性（推理，自研）
|
||||
- 非通用红线（注入/硬编码密钥等属 code-review），而是**结合需求上下文**判断业务约束是否对齐（如：该改动是否绕过了应有的权限校验、是否合规留痕）。
|
||||
|
||||
### ⑤ 综合裁决（合成）
|
||||
| 综合风险 | 触发条件（任一） | 动作建议 |
|
||||
|---|---|---|
|
||||
| 🔴 高 | 实现层有 Critical / 破坏性变更影响核心模块 / 需求未实现 | **阻断**合入 |
|
||||
| 🟡 中 | 实现层有 Warning / 影响边缘模块 / 设计有改进点 | **谨慎**：修改后再合 |
|
||||
| 🟢 低 | 实现层仅 Suggestion / 无跨模块破坏 / 与锚点一致 | **放行** |
|
||||
|
||||
## 综合评审报告模板
|
||||
|
||||
````markdown
|
||||
## 🔍 PR 深度审查 — #<N> <标题>
|
||||
|
||||
**关联锚点**：<Issue #X / 设计文档 path / ⚠️ 无外部锚点（置信度低）>
|
||||
|
||||
### 📎 实现层（编排 gitlink-code-review）
|
||||
- Critical: <n> | Warning: <n> | Suggestion: <n>（详见 code-review 报告）
|
||||
- 摘要：<最关键的 1–3 条>
|
||||
|
||||
### 🧩 跨模块影响
|
||||
- 改动符号：<列表>
|
||||
- 直接调用方受影响：<文件:行 列表 / 无>
|
||||
- 影响范围：核心模块 / 边缘 / 无
|
||||
|
||||
### 🎯 需求/设计一致性
|
||||
- 需求达成：✅/⚠️/❌ <理由>
|
||||
- 设计一致性：✅/⚠️/❌ <理由>
|
||||
|
||||
### 🔒 业务安全/合规
|
||||
- <结论 + 理由>
|
||||
|
||||
### 🏁 综合裁决
|
||||
| 维度 | 结果 |
|
||||
|---|---|
|
||||
| 实现质量 | ✅/⚠️/❌ |
|
||||
| 跨模块影响 | ✅/⚠️/❌ |
|
||||
| 一致性 | ✅/⚠️/❌ |
|
||||
| 安全合规 | ✅/⚠️/❌ |
|
||||
**综合风险：🔴高/🟡中/🟢低 → 建议：<阻断/谨慎/放行>。一句话理由：<...>**
|
||||
````
|
||||
|
||||
## 使用示例
|
||||
|
||||
> 在目标仓库的 git 目录下可省略 `--owner/--repo`。AI 场景统一 `--format json`。
|
||||
|
||||
```bash
|
||||
# 0) 前置
|
||||
gitlink-cli auth status
|
||||
gitlink-cli pr +versions --help # 存在 → 版本满足
|
||||
git config pull.rebase false 2>/dev/null; cd <目标仓库 clone>
|
||||
|
||||
# 1) 取 PR 上下文（N = Web 编号，来自 pr +list 的 pull_request_number）
|
||||
N=1
|
||||
gitlink-cli pr +view --id $N --format json # 标题=issue.subject, 正文=issue.description
|
||||
gitlink-cli pr +files --id $N --format json # 变更文件
|
||||
VID=$(gitlink-cli pr +versions --id $N --format json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const d=JSON.parse(s).data;const a=Array.isArray(d)?d:d.versions;process.stdout.write(String((a[0]||{}).id));});')
|
||||
gitlink-cli pr +version-diff --id $N --version-id $VID --format json # 真实 diff
|
||||
|
||||
# 2) 锚点：从 PR body 提取关联 Issue → 取需求
|
||||
ISSUE_N=$(gitlink-cli pr +view --id $N --format json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const b=JSON.parse(s).data.issue.description;const m=b.match(/#(\d+)/);process.stdout.write(m?m[1]:"");});')
|
||||
[ -n "$ISSUE_N" ] && gitlink-cli issue +view --number $ISSUE_N --format json
|
||||
# 另：询问使用者是否有设计文档，有则 git show <path> 读取
|
||||
|
||||
# 3) 跨模块直接调用方（对每个改动符号）
|
||||
git grep -n "ChangedFunction" -- '*.go'
|
||||
|
||||
# 4) 编排实现层：按 ../gitlink-code-review/SKILL.md 跑一遍，取分级问题清单
|
||||
|
||||
# 5) 综合裁决后，确认 → 回贴（默认 dry-run；--status common 不替人 approve/reject）
|
||||
gitlink-cli pr +review --id $N --status common \
|
||||
--content "## 🔍 PR 深度审查 ..." --dry-run # 先预览
|
||||
# 确认无误后去掉 --dry-run 正式回贴
|
||||
```
|
||||
|
||||
## 已知限制（实测，v0.2.0-dev / 本地源码版）
|
||||
|
||||
- **`pr +diff` 不存在**：本地版无此子命令（`skills/gitlink-pr/SKILL.md` 里的 `+diff` 已过时）。用 `pr +files` + `pr +version-diff`。
|
||||
- **`pr +view` 正文嵌套**：标题在 `data.issue.subject`、正文在 `data.issue.description`，**非顶层**字段。
|
||||
- **`pr +comments` 只列评审行内评论**，不含普通评论。普通 `pr +comment` 是否落地，用 `pr +view` 的 `comments_count` 验证。
|
||||
- **CLI 远程文件读取不可用**：`api GET .../sub_entries` 返回 404、`.../raw/...` 返回空。设计文档**一律走本地**（`git show`/Read）。
|
||||
- **跨模块仅直接调用方**：不追多层传递依赖（按设计，控制规模）。
|
||||
- **无锚点降级**：PR 未关联 Issue 且无设计文档时，一致性结论置信度低，须显著标注。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **默认 dry-run**：综合评审先 `--dry-run` 预览，确认后再正式回贴。
|
||||
- **不越权**：回贴用 `--status common`（评论），**不**用 `approved`/`rejected` 替人决定合入。
|
||||
- **编排而非复制**：实现层交给 code-review/linter，本 Skill 只消费其结果，不重写检测规则（避免与 code-review 重合）。
|
||||
- **大 PR**：`pr +version-diff` 输出可能很大，分段处理；`git grep` 限定文件 glob 控制规模。
|
||||
- **锚点优先级**：关联 Issue 是最可靠的需求源；设计文档次之；两者皆无才降级。
|
||||
|
|
@ -1,149 +0,0 @@
|
|||
# PR 深度审查 — 端到端工作流示例与验证记录
|
||||
|
||||
> 配套文档：[`../SKILL.md`](../SKILL.md)
|
||||
> 本文记录一次**真实跑通**的完整工作流（只读分析 + 写动作），含真实命令输出，作为「使用示例 + Agent 平台验证结果」交付物。
|
||||
|
||||
## 验证环境
|
||||
|
||||
| 项 | 值 |
|
||||
|----|----|
|
||||
| Agent 平台 | Claude Code |
|
||||
| gitlink-cli | `local-build`（本仓库源码编译产物，**非** npm 发布版 v0.1.13） |
|
||||
| 登录用户 | `z2_cc`（`auth status` ✓） |
|
||||
| 测试目标 | `z2_cc/gitlink-cli`（z2_cc 有写权限，Owner） |
|
||||
| 测试 PR | #1（`feat(auth): 登录态过期自动跳转登录页`，body 引用 `#17`） |
|
||||
| 验证日期 | 2026-06-17 |
|
||||
|
||||
## 测试数据构造（造一个"PR + 关联 Issue"的真实样本）
|
||||
|
||||
为覆盖「关联 Issue 锚点」+「写链路」，先造测试数据（验证后已清理）：
|
||||
|
||||
```bash
|
||||
# 1) 造需求锚点 Issue（→ Web #17）
|
||||
gitlink-cli issue +create --owner z2_cc --repo gitlink-cli \
|
||||
-t "[deep-review-test] 登录态过期未自动跳转" -b "## 需求 ..." # → id=144670, #17
|
||||
|
||||
# 2) 造带 diff 的分支并 push（提交署名 z2_cc）
|
||||
git checkout -b test/pr-deep-review-probe
|
||||
# <新增 _deep_review_probe.md>
|
||||
git commit -m "test(pr-deep-review): ...（关联 #17）"
|
||||
git push -u origin test/pr-deep-review-probe
|
||||
|
||||
# 3) 建 PR，body 引用 #17（→ Web #1）
|
||||
gitlink-cli pr +create --owner z2_cc --repo gitlink-cli \
|
||||
--head test/pr-deep-review-probe --base master \
|
||||
--title "feat(auth): 登录态过期自动跳转登录页（含回跳）" \
|
||||
--body "## 关联需求\n修复 #17 ：登录态过期未自动跳转。..." # → id=144671, #1
|
||||
```
|
||||
|
||||
## 步骤 1：取 PR 上下文（实测输出）
|
||||
|
||||
```bash
|
||||
N=1
|
||||
gitlink-cli pr +view --owner z2_cc --repo gitlink-cli --id $N --format json
|
||||
```
|
||||
→ 标题在 `data.issue.subject`、**正文在 `data.issue.description`**（嵌套，非顶层）：
|
||||
```
|
||||
PR 标题: feat(auth): 登录态过期自动跳转登录页（含回跳）
|
||||
body 长度: 153 ← data.issue.description
|
||||
```
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +files --id 1 --format json # → 变更文件: 1 (_deep_review_probe.md)
|
||||
VID=$(gitlink-cli pr +versions --id 1 --format json | ...) # → version_id=17388
|
||||
gitlink-cli pr +version-diff --id 1 --version-id 17388 # → diff 条目: 1
|
||||
```
|
||||
|
||||
## 步骤 2：锚点获取（实测：从 body 提取 #N → 取需求）
|
||||
|
||||
```bash
|
||||
# 从 PR body 提取关联 Issue 编号
|
||||
BODY=$(gitlink-cli pr +view --id 1 --format json | ... data.issue.description)
|
||||
ISSUE_N=$(echo "$BODY" | ... match /#(\d+)/) # → 17
|
||||
```
|
||||
实测：从 153 字 body 提取到 **`#17`** ✓
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --number 17 --format json # 取需求锚点
|
||||
```
|
||||
→ 锚点 Issue：`[deep-review-test] 登录态过期未自动跳转`，需求正文 120 字（含验收标准）✓
|
||||
|
||||
> （若使用者还提供了设计文档路径，则 `git show <path>` 读取后与 Issue 合并为锚点；本次测试仅 Issue 锚点。）
|
||||
|
||||
## 步骤 3：跨模块直接调用方（实测机制）
|
||||
|
||||
```bash
|
||||
git grep -n "<改动符号>" -- '*.go'
|
||||
```
|
||||
→ `git grep` 机制可用（本仓库实测命中准确）。本测试 PR 仅改文档无代码符号，故无调用方受影响。
|
||||
|
||||
## 步骤 4：编排实现层 + 推理层 → 综合裁决（示例输出）
|
||||
|
||||
```markdown
|
||||
## 🔍 PR 深度审查 — #1 feat(auth): 登录态过期自动跳转登录页
|
||||
|
||||
**关联锚点**：#17（从 PR body 自动识别）
|
||||
|
||||
### 📎 实现层（编排 gitlink-code-review）
|
||||
- Critical: 0 | Warning: 0 | Suggestion: 0（本 PR 仅新增说明文档，无逻辑代码）
|
||||
|
||||
### 🧩 跨模块影响
|
||||
- 改动符号：无（仅文档）
|
||||
- 直接调用方受影响：无
|
||||
|
||||
### 🎯 需求/设计一致性
|
||||
- 需求达成：❌ #17 要求 401→自动跳转，本 PR 尚无实际拦截/跳转代码（仅文档占位）
|
||||
|
||||
### 🏁 综合裁决
|
||||
| 维度 | 结果 |
|
||||
|---|---|
|
||||
| 实现质量 | ✅ |
|
||||
| 跨模块影响 | ✅ |
|
||||
| 一致性 | ❌ 未实现 |
|
||||
**综合风险：🟡中 → 建议：谨慎，补全实现后再合入。**
|
||||
```
|
||||
|
||||
## 步骤 5：写动作（实测：真实回贴 + 验证落地）
|
||||
|
||||
```bash
|
||||
# 回贴综合评审（--status common = 评论，不替人 approve/reject）
|
||||
gitlink-cli pr +review --owner z2_cc --repo gitlink-cli --id 1 \
|
||||
--status common --content "## 🔍 PR 深度审查 ..." --format json
|
||||
```
|
||||
→ `评审已回贴 ✓`
|
||||
|
||||
```bash
|
||||
# 验证评审落地
|
||||
gitlink-cli pr +reviews --id 1 --format json # → 已有 reviews: 1，含「深度审查」 ✓
|
||||
```
|
||||
|
||||
```bash
|
||||
# 补充普通评论
|
||||
gitlink-cli pr +comment --owner z2_cc --repo gitlink-cli --id 1 \
|
||||
--body "💡 提示：补全 401 拦截逻辑后可重新触发深度审查。" --format json
|
||||
```
|
||||
→ `评论已发布 ✓`；落地验证用 `pr +view` 的 `comments_count`（=1）。
|
||||
> ⚠️ `pr +comments` 只列**评审行内评论**，不含普通评论——普通评论落地看 `pr +view` 的 `comments_count`。
|
||||
|
||||
## 关键验证结论
|
||||
|
||||
| 能力 | 命令 | 状态 |
|
||||
|------|------|------|
|
||||
| 取 PR 标题/正文 | `pr +view`（`data.issue.subject`/`data.issue.description`） | ✅ 真实返回 |
|
||||
| 变更文件 | `pr +files` | ✅ |
|
||||
| 真实 diff | `pr +version-diff --version-id` | ✅（`pr +diff` 不存在） |
|
||||
| patchset | `pr +versions` | ✅ |
|
||||
| **关联 Issue 锚点** | `pr +view` body→`#N`→`issue +view` | ✅ 端到端跑通 |
|
||||
| 跨模块直接调用方 | `git grep` | ✅ 机制可用 |
|
||||
| **回贴综合评审** | `pr +review --status common` | ✅ 实际回贴 + `pr +reviews` 验证 |
|
||||
| 普通评论 | `pr +comment` | ✅（落地看 `pr +view` `comments_count`） |
|
||||
|
||||
## 清理
|
||||
|
||||
测试产物已全部清理，`z2_cc/gitlink-cli` 无残留：
|
||||
- `pr +close --id 1`（关闭测试 PR）
|
||||
- `git push origin --delete test/pr-deep-review-probe`（删远端分支）
|
||||
- `issue +delete --number 17`（删测试 Issue）
|
||||
- 本地切回 `master`、删本地分支（工作树干净，`master == origin/master`）
|
||||
|
||||
> ⚠️ 版本前提：以上能力依赖含 `pr +versions/+version-diff/+review` 的 gitlink-cli（本仓库源码已具备；npm 发布版 v0.1.13 不具备）。参赛验证基于本地源码编译产物。
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-project-health
|
||||
version: 2.0.0
|
||||
description: "项目健康度报告：统计 Issue 响应时间、PR 合并效率、贡献者活跃度，生成带评分和趋势分析的项目健康度报告。"
|
||||
version: 1.0.0
|
||||
description: "项目健康度报告：统计 Issue 响应时间、PR 合并效率、贡献者活跃度，生成项目健康度分析报告。当用户需要了解项目整体运行状况时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -14,238 +14,123 @@ metadata:
|
|||
|
||||
## 说明
|
||||
|
||||
本 Skill 组合多个 gitlink-cli 命令，从不同维度采集项目数据，然后进行**量化分析**，生成带评分和趋势判断的健康度报告。
|
||||
本 Skill 组合多个 gitlink-cli 命令，从不同维度采集项目数据，生成结构化的项目健康度报告。
|
||||
|
||||
**不仅仅是展示数据，而是对数据进行分析：**
|
||||
- 计算 Issue 平均响应时间、关闭率、积压趋势
|
||||
- 计算 PR 平均合并时间、合并率、堆积趋势
|
||||
- 分析贡献者活跃度变化
|
||||
- 给出综合评分和改进建议
|
||||
## 数据来源
|
||||
|
||||
## 数据采集与分析
|
||||
| Shortcut | 采集的数据 |
|
||||
|----------|-----------|
|
||||
| `issue +list` | Issue 总数、打开/关闭数量、平均响应时间 |
|
||||
| `pr +list` | PR 总数、打开/合并/关闭数量、平均合并时间 |
|
||||
| `repo +info` | 仓库基本信息、fork 数、watch 数 |
|
||||
| `commit +list` | 近期提交频率、活跃开发者数 |
|
||||
| `label +list` | 标签使用情况 |
|
||||
| `milestone +list` | 里程碑完成进度 |
|
||||
|
||||
### 1. Issue 健康度分析
|
||||
## 报告维度
|
||||
|
||||
### 1. Issue 健康度
|
||||
|
||||
```bash
|
||||
# 采集数据
|
||||
# 所有 Issue 统计
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state all --format json
|
||||
|
||||
# 已关闭的 Issue（用于统计平均解决时间）
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state closed --limit 30
|
||||
|
||||
# 待处理的 Issue
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state open
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state closed --limit 50
|
||||
```
|
||||
|
||||
**分析逻辑：**
|
||||
|
||||
```
|
||||
总 Issue 数 = open_count + closed_count
|
||||
关闭率 = closed_count / total × 100%
|
||||
|
||||
Issue 积压趋势：
|
||||
- 近 30 天新增 - 近 30 天关闭 = 净变化
|
||||
- 净变化 > 5 → 积压增加，标记 🔴
|
||||
- 净变化 < -2 → 积压在减少，标记 🟢
|
||||
- 其他 → 稳定，标记 🟡
|
||||
|
||||
平均响应时间 = 计算 closed 列表中 created_at 到 closed_at 的平均天数
|
||||
- < 2 天 → 响应及时 🟢
|
||||
- 2-7 天 → 正常 🟡
|
||||
- > 7 天 → 响应偏慢 🔴
|
||||
```
|
||||
|
||||
**评分规则：**
|
||||
- 关闭率 > 80% 且平均响应 < 3 天 → 10/10
|
||||
- 关闭率 > 50% → 7/10
|
||||
- 关闭率 > 30% → 5/10
|
||||
- 关闭率 < 30% → 3/10
|
||||
|
||||
### 2. PR 健康度分析
|
||||
### 2. PR 健康度
|
||||
|
||||
```bash
|
||||
# 采集数据
|
||||
# 所有 PR 统计
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state all --format json
|
||||
|
||||
# 待合并的 PR
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state open
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state merged --limit 50
|
||||
|
||||
# 已合并的 PR（统计平均合并时间）
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state merged --limit 30
|
||||
```
|
||||
|
||||
**分析逻辑：**
|
||||
|
||||
```
|
||||
总 PR 数 = open_count + merged_count + closed_count
|
||||
合并率 = merged_count / total × 100%
|
||||
|
||||
PR 合并效率：
|
||||
- 分析 merged 列表中 created_at 到 merged_at 的平均天数
|
||||
- < 3 天 → 合并迅速 🟢
|
||||
- 3-7 天 → 正常 🟡
|
||||
- > 7 天 → 合并缓慢 🔴
|
||||
|
||||
堆积 PR（超过 7 天未合并）：
|
||||
- 计算 open 列表中超过 7 天的 PR 数量
|
||||
- 占 open 总数 < 20% → 🟢
|
||||
- 占 open 总数 20-50% → 🟡
|
||||
- 占 open 总数 > 50% → 🔴
|
||||
```
|
||||
|
||||
### 3. 贡献者活跃度分析
|
||||
### 3. 仓库基本信息
|
||||
|
||||
```bash
|
||||
# 采集数据
|
||||
gitlink-cli commit +list --owner myuser --repo myrepo --limit 50
|
||||
# 仓库概况
|
||||
gitlink-cli repo +info --owner myuser --repo myrepo --format json
|
||||
```
|
||||
|
||||
**分析逻辑：**
|
||||
|
||||
```
|
||||
活跃贡献者 = 近 50 次提交中 unique author 数量
|
||||
|
||||
活跃度等级：
|
||||
- ≥ 5 人 → 团队协作活跃 🟢
|
||||
- 2-4 人 → 少量贡献者 🟡
|
||||
- 1 人 → 单人维护 🔴
|
||||
|
||||
提交频率 = 近 50 次提交的时间跨度 / 50
|
||||
- 每天都有提交 → 非常活跃 🟢
|
||||
- 每周 2-3 次 → 正常活跃 🟡
|
||||
- 每周 < 1 次 → 不活跃 🔴
|
||||
|
||||
新贡献者比例 = 首次贡献者数量 / 总贡献者数 × 100%
|
||||
- > 20% → 社区有新鲜血液 🟢
|
||||
- 5-20% → 有少量新人 🟡
|
||||
- < 5% → 缺少新人 🔴
|
||||
```
|
||||
|
||||
### 4. 里程碑进度分析
|
||||
### 4. 里程碑进度
|
||||
|
||||
```bash
|
||||
# 采集数据
|
||||
# 查看里程碑
|
||||
gitlink-cli milestone +list --owner myuser --repo myrepo
|
||||
```
|
||||
|
||||
**分析逻辑：**
|
||||
### 5. 提交活跃度
|
||||
|
||||
```
|
||||
里程碑完成度 = 计算每个 milestone 中 closed issues / total issues
|
||||
逾期风险 = 当前日期超过 due_date 但未关闭
|
||||
```bash
|
||||
# 最近提交
|
||||
gitlink-cli commit +list --owner myuser --repo myrepo --limit 20
|
||||
```
|
||||
|
||||
## 综合评分计算
|
||||
## 报告模板
|
||||
|
||||
```
|
||||
综合得分 = Issue得分 × 30% + PR得分 × 30% + 活跃度得分 × 25% + 里程碑得分 × 15%
|
||||
|
||||
评分区间：
|
||||
9-10 分 → 🟢 优秀：项目健康，保持现状
|
||||
7-8 分 → 🟢 良好：个别方面需关注
|
||||
5-6 分 → 🟡 一般：需要改进
|
||||
3-4 分 → 🔴 堪忧：需重点治理
|
||||
0-2 分 → 🔴 危险：项目急需干预
|
||||
```
|
||||
|
||||
## 完整报告示例
|
||||
收集完数据后，按以下模板生成报告：
|
||||
|
||||
```markdown
|
||||
# 📊 项目健康度报告 — myuser/myrepo
|
||||
# 项目健康度报告
|
||||
|
||||
**报告日期：** 2026-06-17
|
||||
**综合评分：** 7.5/10 🟢 良好
|
||||
## 基本信息
|
||||
- 项目：{repo_name}
|
||||
- 所有者：{owner}
|
||||
- Stars：{stars} | Forks：{forks}
|
||||
|
||||
---
|
||||
## Issue 状况
|
||||
- 总 Issue 数：{total_issues}
|
||||
- 打开：{open_issues}（占比 {open_percent}%）
|
||||
- 已关闭：{closed_issues}（占比 {closed_percent}%）
|
||||
|
||||
## 一、基本信息
|
||||
## PR 状况
|
||||
- 总 PR 数：{total_prs}
|
||||
- 打开：{open_prs}
|
||||
- 已合并：{merged_prs}
|
||||
|
||||
| 指标 | 数据 |
|
||||
|------|------|
|
||||
| 项目 | myuser/myrepo |
|
||||
| 默认分支 | master |
|
||||
| Issue 总数 | 47 |
|
||||
| PR 总数 | 23 |
|
||||
| 近 30 天活跃贡献者 | 3 人 |
|
||||
## 活跃度
|
||||
- 近期提交：{recent_commits} 次
|
||||
- 活跃开发者：{active_devs} 人
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、Issue 状况（评分：8/10 🟢）
|
||||
|
||||
| 指标 | 数据 | 状态 |
|
||||
|------|------|------|
|
||||
| 总 Issue 数 | 47 | — |
|
||||
| 打开中 | 8 | — |
|
||||
| 已关闭 | 39 | — |
|
||||
| 关闭率 | 83% | 🟢 优秀 |
|
||||
| 平均响应时间 | 1.8 天 | 🟢 响应及时 |
|
||||
| 近 30 天净变化 | +2 | 🟡 略增 |
|
||||
|
||||
**分析：** Issue 关闭率很高，响应也及时。近 30 天新增略多于关闭，建议关注积压趋势。
|
||||
|
||||
---
|
||||
|
||||
## 三、PR 状况（评分：7/10 🟢）
|
||||
|
||||
| 指标 | 数据 | 状态 |
|
||||
|------|------|------|
|
||||
| 总 PR 数 | 23 | — |
|
||||
| 打开中 | 3 | — |
|
||||
| 已合并 | 18 | — |
|
||||
| 合并率 | 78% | 🟢 良好 |
|
||||
| 平均合并时间 | 4.2 天 | 🟡 正常 |
|
||||
| 堆积 PR（>7 天） | 1 个 | 🟡 占 33% |
|
||||
|
||||
**分析：** 合并率良好，但有一个 PR 超过 7 天未处理，建议关注。
|
||||
|
||||
---
|
||||
|
||||
## 四、贡献者活跃度（评分：7/10 🟢）
|
||||
|
||||
| 指标 | 数据 | 状态 |
|
||||
|------|------|------|
|
||||
| 近 50 次提交贡献者 | 3 人 | 🟡 少量贡献者 |
|
||||
| 提交频率 | 每周 3-4 次 | 🟡 正常 |
|
||||
| 新贡献者比例 | 0% | 🔴 缺少新人 |
|
||||
|
||||
**分析：** 项目目前由少数核心成员维护，建议标记一些 good-first-issue 吸引新贡献者。
|
||||
|
||||
---
|
||||
|
||||
## 五、里程碑进度
|
||||
|
||||
| 里程碑 | 到期日 | 完成度 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| v1.3.0 | 2026-06-30 | 60% | 🟢 进行中 |
|
||||
| v2.0.0 | 2026-08-15 | 20% | 🟡 初期 |
|
||||
|
||||
---
|
||||
|
||||
## 六、改进建议
|
||||
|
||||
1. **🔴 高优先级** — 添加 good-first-issue 标签吸引新贡献者
|
||||
2. **🟡 中优先级** — 关注堆积 PR，设置自动提醒
|
||||
3. **🟢 低优先级** — 定期清理积压 Issue
|
||||
|
||||
---
|
||||
|
||||
## 数据采集命令
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# Issue 数据
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state all --format json
|
||||
# 完整报告生成流程
|
||||
|
||||
# 步骤1：获取仓库信息
|
||||
gitlink-cli repo +info --owner myuser --repo myrepo --format json
|
||||
|
||||
# 步骤2：获取 Issue 统计
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state open
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state closed --limit 50
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state all --format json
|
||||
|
||||
# PR 数据
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state all --format json
|
||||
# 步骤3：获取 PR 统计
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state open
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state merged --limit 50
|
||||
gitlink-cli pr +list --owner myuser --repo myrepo --state merged --limit 20
|
||||
|
||||
# 贡献者数据
|
||||
gitlink-cli commit +list --owner myuser --repo myrepo --limit 50
|
||||
# 步骤4：获取提交活跃度
|
||||
gitlink-cli commit +list --owner myuser --repo myrepo --limit 30
|
||||
|
||||
# 里程碑
|
||||
# 步骤5：获取里程碑进度
|
||||
gitlink-cli milestone +list --owner myuser --repo myrepo
|
||||
```
|
||||
|
||||
# 步骤6：汇总数据，生成报告
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 每个指标都要计算**量化数据**（百分比、天数、人数），不能只罗列原始数字。
|
||||
- 评分需要有明确的**计算规则**（见各维度分析逻辑），不能凭感觉打分。
|
||||
- 每个维度都要给出**改进建议**，不能只报告现状。
|
||||
- 使用 `🟢🟡🔴` 颜色标识状态，一目了然。
|
||||
- 使用 `--format json` 获取结构化数据，便于 Agent 解析。
|
||||
- 指定 `--limit` 控制数据量，避免输出过大。
|
||||
- 不同项目的数据量级不同，可根据实际情况调整采样数量。
|
||||
- 报告中的"健康状况"建议使用颜色标识（绿色=健康，黄色=一般，红色=需关注）。
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 项目健康度报告生成工作流示例（含数据分析）
|
||||
# 项目健康度报告生成工作流示例
|
||||
|
||||
**场景**：项目维护者需要生成一份带评分和改进建议的健康度报告。
|
||||
**场景**：项目维护者需要生成一份项目健康度周报，了解 Issue 处理情况、PR 合并效率和整体活跃度。
|
||||
|
||||
## 前置条件
|
||||
|
||||
|
|
@ -8,63 +8,85 @@
|
|||
|
||||
## 工作流步骤
|
||||
|
||||
### Step 1：采集原始数据
|
||||
### Step 1：获取项目基本信息
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner z2_cc --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
### Step 2：统计 Issue 数据
|
||||
|
||||
```bash
|
||||
# 所有 Issue
|
||||
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state all --format json
|
||||
|
||||
# 打开的 Issue
|
||||
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state open
|
||||
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state closed --limit 50
|
||||
|
||||
# 已关闭的 Issue（最近 30 条）
|
||||
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state closed --limit 30
|
||||
```
|
||||
|
||||
### Step 3：统计 PR 数据
|
||||
|
||||
```bash
|
||||
# 所有 PR
|
||||
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state all --format json
|
||||
|
||||
# 待合并的 PR
|
||||
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state open
|
||||
|
||||
# 已合并的 PR
|
||||
gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state merged --limit 30
|
||||
gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 50
|
||||
```
|
||||
|
||||
### Step 4：查看近期提交活跃度
|
||||
|
||||
```bash
|
||||
gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 20
|
||||
```
|
||||
|
||||
### Step 5：查看里程碑进度
|
||||
|
||||
```bash
|
||||
gitlink-cli milestone +list --owner z2_cc --repo gitlink-cli
|
||||
```
|
||||
|
||||
### Step 2：AI 分析数据
|
||||
### Step 6：生成报告
|
||||
|
||||
对采集到的 JSON 数据进行以下分析：
|
||||
|
||||
```
|
||||
1. Issue 分析：
|
||||
- 从 all 数据中统计 open 和 closed 数量
|
||||
- 从 closed 数据中计算平均响应时间（created_at → closed_at）
|
||||
- 判断关闭率是否 > 80%
|
||||
|
||||
2. PR 分析：
|
||||
- 从 all 数据中统计 open/merged/closed 数量
|
||||
- 从 merged 数据中计算平均合并时间
|
||||
- 判断是否有 PR 长期未合并
|
||||
|
||||
3. 活跃度分析：
|
||||
- 从 commit 数据中统计 unique author 数量
|
||||
- 根据提交时间判断频率
|
||||
```
|
||||
|
||||
### Step 3：生成带评分的报告
|
||||
汇总以上数据，生成结构化报告：
|
||||
|
||||
```markdown
|
||||
## 项目健康度报告 — z2_cc/gitlink-cli
|
||||
## 项目健康度周报
|
||||
|
||||
**综合评分：7.5/10 🟢 良好**
|
||||
### Issue 状况
|
||||
- 总 Issue 数：12（打开 3 / 关闭 9）
|
||||
- 本周新增：2
|
||||
- 本周解决：3
|
||||
|
||||
### Issue 状况（8/10）
|
||||
- 总 Issue 数：16（关闭 14 / 打开 2）
|
||||
- 关闭率：87.5% 🟢
|
||||
- 分析：关闭率优秀，积压很少
|
||||
### PR 状况
|
||||
- 总 PR 数：5（打开 1 / 已合并 4）
|
||||
- 本周新增：1
|
||||
- 本周合并：2
|
||||
|
||||
### PR 状况（7/10）
|
||||
- 总 PR 数：5（已合并 4 / 打开 1）
|
||||
- 合并率：80% 🟢
|
||||
- 平均合并时间：良好
|
||||
- 分析：PR 处理效率正常
|
||||
### 活跃度
|
||||
- 近 20 次提交涉及：3 位贡献者
|
||||
- 最近提交时间：2 小时前
|
||||
|
||||
### 贡献者活跃度（7/10）
|
||||
- 近 50 次提交贡献者：1 人 🔴
|
||||
- 提交频率：活跃 🟢
|
||||
- 分析：目前单人维护，建议吸引新贡献者
|
||||
### 里程碑
|
||||
- 进行中：v2.0（完成 60%）
|
||||
|
||||
### 改进建议
|
||||
1. 🔴 标记 good-first-issue 吸引新人
|
||||
2. 🟡 考虑添加 CI/CD 自动化
|
||||
🟢 总体评价：项目健康
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整命令速览
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info
|
||||
gitlink-cli issue +list --state all --format json
|
||||
gitlink-cli pr +list --state all --format json
|
||||
gitlink-cli commit +list --limit 20
|
||||
gitlink-cli milestone +list
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-release-auto
|
||||
version: 2.0.0
|
||||
description: "自动化 Release 管理：分析提交历史自动生成带分类、统计和链接的 Release Notes，推荐语义化版本号。"
|
||||
version: 1.0.0
|
||||
description: "自动化 Release 管理：从提交历史自动生成 Release Notes、推荐语义化版本号、批量发布管理。当用户需要创建版本发布、生成更新日志、自动化发版流程时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -11,8 +11,11 @@ metadata:
|
|||
# gitlink-release-auto（自动化 Release 管理）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — `release +view` 必须使用 `version_id`（从 `release +list` 返回），不能用 tag_name，否则返回 HTML 页面而非 JSON。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
|
@ -20,185 +23,265 @@ metadata:
|
|||
本技能提供完整的自动化发版流程：
|
||||
|
||||
1. **语义化版本推荐** — 根据提交类型自动推荐下一个版本号
|
||||
2. **Release Notes 自动生成** — 从提交历史分析、归类、统计，生成结构化 Changelog
|
||||
3. **变更影响分析** — 统计变更文件数、新增/删除行数、涉及模块
|
||||
4. **一键发布** — 创建 Release 并关联 Tag
|
||||
2. **Release Notes 自动生成** — 从提交历史和已关闭 Issue 自动生成 Changelog
|
||||
3. **一键发布** — 创建 Release 并关联 Tag
|
||||
4. **发布后通知** — 在相关 Issue 中关联发版信息
|
||||
|
||||
---
|
||||
|
||||
## 数据分析流程
|
||||
## 一、版本号推荐（Semantic Versioning）
|
||||
|
||||
### Step 1：获取基线版本
|
||||
### Semver 规则
|
||||
|
||||
```
|
||||
v<MAJOR>.<MINOR>.<PATCH>
|
||||
|
||||
MAJOR：有 Breaking Change（不向下兼容的变更）
|
||||
MINOR：有 feat（新增功能，向下兼容）
|
||||
PATCH：只有 fix / perf / refactor / docs 等修复性变更
|
||||
```
|
||||
|
||||
### 步骤 1：获取当前版本号
|
||||
|
||||
```bash
|
||||
# 获取最新 Release 确定基线
|
||||
gitlink-cli release +list --owner myuser --repo myrepo --format json
|
||||
# 获取最新 Release（从中找当前版本号）
|
||||
gitlink-cli release +list --owner <owner> --repo <repo> --format json
|
||||
# 取 data.releases[0].tag_name 作为当前版本
|
||||
|
||||
# 获取标签列表
|
||||
gitlink-cli api GET /:owner/:repo/tags --format json
|
||||
```
|
||||
|
||||
**分析输出：** 提取最新 tag_name（如 v1.2.0）作为对比基准。
|
||||
|
||||
### Step 2：分析提交历史
|
||||
### 步骤 2：获取自上次发版以来的提交
|
||||
|
||||
```bash
|
||||
git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short --stat
|
||||
# 获取自上次 Release 以来的提交
|
||||
git log v1.1.0..HEAD --format="%H %s %an %ad" --date=short 2>&1
|
||||
```
|
||||
|
||||
**分析逻辑：**
|
||||
### 步骤 3：AI 分析提交类型，推荐版本号
|
||||
|
||||
对每条 commit 的 message 进行分类统计：
|
||||
根据提交信息（Conventional Commits）进行分类：
|
||||
|
||||
```
|
||||
feat: → ✨ 新功能
|
||||
fix: → 🐛 Bug 修复
|
||||
docs: → 📝 文档更新
|
||||
refactor: → ♻️ 代码重构
|
||||
perf: → ⚡ 性能优化
|
||||
test: → ✅ 测试相关
|
||||
chore: → 🔧 工程配置
|
||||
revert: → ⏪ 回退
|
||||
其他 → 📦 其他变更
|
||||
决策逻辑：
|
||||
1. 任意提交包含 "BREAKING CHANGE" → MAJOR 升级
|
||||
当前 v1.2.3 → 推荐 v2.0.0
|
||||
|
||||
2. 有 feat: 类型的提交（且无 Breaking Change）→ MINOR 升级
|
||||
当前 v1.2.3 → 推荐 v1.3.0
|
||||
|
||||
3. 仅有 fix/perf/refactor/docs/chore/ci 类型 → PATCH 升级
|
||||
当前 v1.2.3 → 推荐 v1.2.4
|
||||
```
|
||||
|
||||
**统计维度：**
|
||||
**版本号推荐输出示例：**
|
||||
|
||||
```
|
||||
总提交数 = feat + fix + docs + refactor + perf + test + chore + 其他
|
||||
涉及文件 = git log --stat 统计的总文件数
|
||||
变更行数 = git log --stat 统计的 +行/-行
|
||||
贡献者数 = unique author 数量
|
||||
当前版本：v1.2.3
|
||||
分析了 18 次提交（2026-04-15 至今）：
|
||||
- 3 个 feat：新增用户头像、搜索历史、消息通知
|
||||
- 5 个 fix：修复了 5 个 Bug
|
||||
- 2 个 docs：更新了接口文档
|
||||
- 无 Breaking Change
|
||||
|
||||
推荐版本：v1.3.0（MINOR 升级，有新功能）
|
||||
备选版本：v1.2.4（如果认为功能较小，可用 PATCH）
|
||||
```
|
||||
|
||||
### Step 3：语义化版本推荐规则
|
||||
---
|
||||
|
||||
```
|
||||
根据 commit 类型判断版本号变更幅度：
|
||||
- 含有 BREAKING CHANGE 或 feat! → 主版本号 +1（v1.x.x → v2.0.0）
|
||||
- 含有 feat 且无 breaking → 次版本号 +1（v1.2.x → v1.3.0）
|
||||
- 只有 fix/refactor/docs 等 → 修订号 +1（v1.2.0 → v1.2.1）
|
||||
## 二、Release Notes 自动生成
|
||||
|
||||
推荐版本号：v{major}.{minor}.{patch}
|
||||
### 获取数据
|
||||
|
||||
```bash
|
||||
# 1. 获取自上次 Release 以来的提交
|
||||
git log v1.1.0..HEAD --format="%H %s %an %ad" --date=short 2>&1
|
||||
|
||||
# 2. 获取本期关闭的 Issue
|
||||
gitlink-cli issue +list --state closed --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 3. 获取本期合并的 PR 列表
|
||||
gitlink-cli pr +list --state merged --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
### Step 4：生成结构化的 Release Notes
|
||||
### Release Notes 模板
|
||||
|
||||
```markdown
|
||||
## v1.3.0 (2026-06-17)
|
||||
## v1.3.0 (2026-05-07)
|
||||
|
||||
### 📊 版本概览
|
||||
- 包含 **{total_commits}** 次提交
|
||||
- 涉及 **{total_files}** 个文件
|
||||
- 新增 **{additions}** 行 / 删除 **{deletions}** 行
|
||||
- 贡献者：**{contributors}** 人
|
||||
### ✨ 新功能
|
||||
|
||||
### ✨ 新功能（{feat_count}）
|
||||
- feat: 新增代码片段管理功能（@author）
|
||||
- feat: 新增 Webhook 投递监控（@author）
|
||||
- feat(user): 新增用户头像上传功能 ([#234](link))
|
||||
- feat(search): 支持全文搜索和历史记录 ([#256](link))
|
||||
- feat(notify): 添加站内消息通知系统 ([#267](link))
|
||||
|
||||
### 🐛 Bug 修复（{fix_count}）
|
||||
- fix: 修复 Wiki 删除时侧边栏残留问题（@author）
|
||||
### 🐛 Bug 修复
|
||||
|
||||
### 📝 文档（{docs_count}）
|
||||
- docs: 更新 Shortcut 实现报告（@author）
|
||||
- docs: 添加工作流示例（@author）
|
||||
- fix(login): 修复手机号登录时验证码未清除的问题 ([#245](link))
|
||||
- fix(upload): 修复大文件上传超时问题 ([#251](link))
|
||||
- fix(api): 修复并发请求时偶发 500 错误 ([#259](link))
|
||||
|
||||
### 🔧 工程（{chore_count}）
|
||||
- chore: 添加 DevOps CI 流水线（@author）
|
||||
### ⚡ 性能优化
|
||||
|
||||
### ⚡ 性能优化（{perf_count}）
|
||||
- perf: 优化 hook-runner 输出格式（@author）
|
||||
- perf(search): 优化搜索接口响应速度，平均提升 40% ([#261](link))
|
||||
|
||||
### ⏪ 回退（{revert_count}）
|
||||
- revert: 移除 Sidebar 自动管理（@author）
|
||||
### 📦 其他变更
|
||||
|
||||
- docs: 更新 API 接口文档
|
||||
- build: 升级 Go 依赖到最新版本
|
||||
- ci: 添加代码覆盖率检查
|
||||
|
||||
|
||||
### 🤝 贡献者
|
||||
|
||||
感谢以下贡献者参与本版本开发：@zhangsan、@lisi、@wangwu
|
||||
|
||||
### 📈 统计汇总
|
||||
| 类别 | 数量 | 占比 |
|
||||
|------|------|------|
|
||||
| ✨ 新功能 | {feat_count} | {feat_percent}% |
|
||||
| 🐛 修复 | {fix_count} | {fix_percent}% |
|
||||
| 📝 文档 | {docs_count} | {docs_percent}% |
|
||||
| 🔧 工程 | {chore_count} | {chore_percent}% |
|
||||
| ♻️ 重构 | {refactor_count} | {refactor_percent}% |
|
||||
```
|
||||
|
||||
### Step 5：创建 Release
|
||||
---
|
||||
|
||||
> ⚠️ **重要**：`贡献者` 必须去重！release notes中如果有相同或者相似的记录，需要去重！不需要添加`完整变更日志`这个信息！
|
||||
|
||||
|
||||
## 三、一键发布完整流程
|
||||
|
||||
### 标准发版步骤
|
||||
|
||||
```bash
|
||||
gitlink-cli release +create --owner myuser --repo myrepo \
|
||||
# Step 1：确认当前版本和推荐版本
|
||||
gitlink-cli release +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# Step 2：获取变更内容（提交历史）
|
||||
gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=30&ref=master' --format json
|
||||
|
||||
# Step 3：生成 Release Notes（AI 分析提交后组织内容）
|
||||
|
||||
# Step 4：创建 Release
|
||||
gitlink-cli release +create \
|
||||
--owner <owner> \
|
||||
--repo <repo> \
|
||||
--tag v1.3.0 \
|
||||
--name "v1.3.0" \
|
||||
--body "生成的 Release Notes 内容" \
|
||||
--name "v1.3.0 - 用户体验升级版" \
|
||||
--body "## v1.3.0\n\n### ✨ 新功能\n- ...\n\n### 🐛 Bug 修复\n- ..." \
|
||||
--target master
|
||||
|
||||
# Step 5：验证发布成功
|
||||
gitlink-cli release +list --owner <owner> --repo <repo> --format json
|
||||
# 从列表取 version_id
|
||||
|
||||
gitlink-cli release +view --owner <owner> --repo <repo> --id <version_id>
|
||||
```
|
||||
|
||||
> ⚠️ **重要**：`release +view` 必须用 `version_id`（整数），不能用 tag 名称（如 v1.3.0）
|
||||
|
||||
### 预发布版本
|
||||
|
||||
```bash
|
||||
# 创建 alpha/beta/rc 预发布版本
|
||||
gitlink-cli release +create \
|
||||
--tag v1.3.0-beta.1 \
|
||||
--name "v1.3.0 Beta 1" \
|
||||
--body "预发布版本，用于测试..." \
|
||||
--prerelease true \
|
||||
--target develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、发布后操作
|
||||
|
||||
### 关联 Issue 通知
|
||||
|
||||
```bash
|
||||
# 在关联的 Issue 中添加评论，通知已发版
|
||||
gitlink-cli issue +comment \
|
||||
--id <issue_id> \
|
||||
--body "🎉 此问题已在 v1.3.0 中修复，请更新到最新版本验证。"
|
||||
```
|
||||
|
||||
### 批量关联 Issue
|
||||
|
||||
```bash
|
||||
# 遍历本期关闭的 Issue，逐一添加发版通知评论
|
||||
gitlink-cli issue +list --state closed --format json
|
||||
# 对每个 issue_id 执行 issue +comment
|
||||
```
|
||||
|
||||
### 触发部署（可选）
|
||||
|
||||
```bash
|
||||
# 发版后触发部署（通过 CI 重新构建 tag 对应的分支）
|
||||
gitlink-cli ci +restart --build <latest_build_number>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、完整发版检查清单
|
||||
|
||||
在执行发版前，确认以下事项：
|
||||
|
||||
```
|
||||
发版前检查：
|
||||
□ 所有计划纳入本次版本的 PR 已合并
|
||||
□ CI 在 master 分支的最新构建是成功的
|
||||
□ 所有计划修复的 Issue 已关闭
|
||||
□ 文档已更新（README、API 文档等）
|
||||
□ 数据库迁移脚本已准备就绪（如有）
|
||||
|
||||
版本号确认：
|
||||
□ 版本号遵循 Semantic Versioning
|
||||
□ 是否有 Breaking Change（需 MAJOR 升级）
|
||||
□ 是否发预发布版本（alpha/beta/rc）
|
||||
|
||||
Release Notes 检查：
|
||||
□ 新功能描述清晰
|
||||
□ Bug 修复有具体说明
|
||||
□ Breaking Change 有迁移指南
|
||||
□ 关联了对应的 Issue / PR 链接
|
||||
|
||||
发版操作：
|
||||
□ 在正确的分支/提交上打 Tag
|
||||
□ Release 创建成功
|
||||
□ 相关 Issue 已通知
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、版本管理最佳实践
|
||||
|
||||
### 发版节奏建议
|
||||
|
||||
| 模式 | 说明 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| 定期发版 | 每 1~2 周一次 PATCH，每月一次 MINOR | 功能迭代稳定的项目 |
|
||||
| 功能发版 | 功能完成即发版 | 需求驱动、快速迭代 |
|
||||
| 按需发版 | Bug 修复立即发版 | 线上紧急修复（hotfix） |
|
||||
|
||||
### Hotfix 发版流程
|
||||
|
||||
```bash
|
||||
# 1. 从当前 Release Tag 创建 hotfix 分支
|
||||
gitlink-cli branch +create --name hotfix/v1.2.4-critical-fix --from v1.2.3
|
||||
|
||||
# 2. 在 hotfix 分支修复问题，合并回 master
|
||||
# （通过 PR 流程）
|
||||
|
||||
# 3. 快速发布 PATCH 版本
|
||||
gitlink-cli release +create \
|
||||
--tag v1.2.4 \
|
||||
--name "v1.2.4 紧急修复版" \
|
||||
--body "## 紧急修复\n\n- fix: 修复生产环境关键 Bug（#xxx）" \
|
||||
--target master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整示例
|
||||
|
||||
假设项目当前 tag 为 v1.2.0，执行：
|
||||
|
||||
```bash
|
||||
# 获取基线
|
||||
gitlink-cli release +list --owner myuser --repo myrepo --format json
|
||||
|
||||
# 获取提交历史
|
||||
git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short
|
||||
|
||||
# 分析结果示例：
|
||||
# 共 12 次提交：feat 3、fix 2、docs 4、chore 2、perf 1
|
||||
# 涉及 18 个文件，+350/-120 行
|
||||
# 3 位贡献者
|
||||
# 推荐版本：v1.3.0（有 feat，无 breaking）
|
||||
|
||||
# 生成的 Release Notes：
|
||||
```
|
||||
|
||||
```markdown
|
||||
## v1.3.0 (2026-06-17)
|
||||
|
||||
### 📊 版本概览
|
||||
- 包含 **12** 次提交 | 涉及 **18** 个文件
|
||||
- 新增 **+350** 行 / 删除 **-120** 行
|
||||
- 贡献者：**3** 人
|
||||
|
||||
### ✨ 新功能（3）
|
||||
- feat: 新增代码片段管理
|
||||
- feat: 新增 Webhook 投递监控
|
||||
- feat: 新增 Wiki 管理 Skill
|
||||
|
||||
### 🐛 Bug 修复（2）
|
||||
- fix: 修复 _Sidebar.md 残留问题
|
||||
- fix: 修复 snippet delete API 参数错误
|
||||
|
||||
### 📝 文档（4）
|
||||
- docs: 添加工作流示例
|
||||
- docs: 更新实现报告
|
||||
|
||||
### 🔧 工程（2）
|
||||
- chore: 添加 CI 流水线
|
||||
- chore: 更新依赖
|
||||
|
||||
### ⚡ 性能优化（1）
|
||||
- perf: 优化 list 输出格式
|
||||
|
||||
### 📈 统计汇总
|
||||
| 类别 | 数量 | 占比 |
|
||||
|------|------|------|
|
||||
| ✨ 新功能 | 3 | 25% |
|
||||
| 🐛 修复 | 2 | 17% |
|
||||
| 📝 文档 | 4 | 33% |
|
||||
| 🔧 工程 | 2 | 17% |
|
||||
| ⚡ 性能 | 1 | 8% |
|
||||
```
|
||||
|
||||
```bash
|
||||
# 创建 Release
|
||||
gitlink-cli release +create --owner myuser --repo myrepo \
|
||||
--tag v1.3.0 --name "v1.3.0" --body "生成的 Release Notes" --target master
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 每个分类都要统计**数量**和**占比**，让读者直观了解本次发布的构成。
|
||||
- commit message 必须遵循 Conventional Commits 规范才能正确分类（`feat:` / `fix:` / `docs:` 等）。
|
||||
- 对于不符合规范的 commit，归类为"📦 其他变更"。
|
||||
- 如果包含 BREAKING CHANGE，务必提示版本号升级的影响。
|
||||
- ✅ **版本号一旦发布不可修改**，确认无误后再执行创建
|
||||
- ✅ **BREAKING CHANGE 必须在 Release Notes 中明确标注**，并提供迁移指南
|
||||
- ⚠️ **`release +view` 始终使用 `version_id`**
|
||||
- ✅ **预发布版本（beta/rc）先内部测试**，验证后再发正式版
|
||||
- ✅ **发版后通知**，注意发版后，要对所有关联的issue添加通知评论
|
||||
|
|
|
|||
|
|
@ -1,113 +0,0 @@
|
|||
# Release Notes 生成完整工作流示例（含数据分析）
|
||||
|
||||
**场景**：项目即将发布新版本，需要根据 commit 生成带统计分析和分类的 Release Notes。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `gitlink-cli` 已安装并登录
|
||||
|
||||
## 工作流步骤
|
||||
|
||||
### Step 1：获取当前最新 Release
|
||||
|
||||
```bash
|
||||
gitlink-cli release +list --owner z2_cc --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**分析：** 找到最新 tag 作为版本对比基线。假设为 v1.2.0。
|
||||
|
||||
### Step 2：获取提交历史
|
||||
|
||||
```bash
|
||||
git log v1.2.0..HEAD --format="%H|%s|%an|%ad" --date=short
|
||||
```
|
||||
|
||||
**AI 分类统计过程：**
|
||||
|
||||
```
|
||||
原始提交：
|
||||
a4587f9|feat: add webhook +failed and +task-view|wqer|2026-06-04
|
||||
37a0f21|docs: add release notes workflow example|wqer|2026-06-17
|
||||
6c0ad3b|feat: add three new skills|wqer|2026-06-17
|
||||
d1cc68b|docs: add workflow examples|wqer|2026-06-17
|
||||
9a51db0|feat: add wiki and snippet skills|wqer|2026-06-17
|
||||
|
||||
分类统计：
|
||||
✨ 新功能：3 次 (60%)
|
||||
📝 文档：2 次 (40%)
|
||||
总提交：5 次，1 位贡献者
|
||||
```
|
||||
|
||||
### Step 3：统计变更文件
|
||||
|
||||
```bash
|
||||
git log v1.2.0..HEAD --stat --oneline
|
||||
```
|
||||
|
||||
**统计结果：**
|
||||
```
|
||||
涉及 12 个文件
|
||||
新增 +245 行，删除 -89 行
|
||||
主要变更模块：shortcuts/webhook/、skills/
|
||||
```
|
||||
|
||||
### Step 4：推荐版本号
|
||||
|
||||
```
|
||||
最新版本：v1.2.0（仅修订号变更）
|
||||
提交类型：包含 feat，无 BREAKING CHANGE
|
||||
推荐版本：v1.3.0（次版本号 +1）
|
||||
```
|
||||
|
||||
### Step 5：生成带分类和统计的 Release Notes
|
||||
|
||||
```markdown
|
||||
## v1.3.0 (2026-06-17)
|
||||
|
||||
### 📊 版本概览
|
||||
- 5 次提交 | 12 个文件变更
|
||||
- +245 / -89 行 | 1 位贡献者
|
||||
|
||||
### ✨ 新功能（3）
|
||||
- feat: 新增 Webhook 投递监控（failed + task-view）
|
||||
- feat: 新增三个 AI Agent Skill
|
||||
- feat: 新增 Wiki 和代码片段 Skill
|
||||
|
||||
### 📝 文档（2）
|
||||
- docs: 添加 Release Notes 工作流示例
|
||||
- docs: 添加其他工作流示例
|
||||
|
||||
### 📈 统计汇总
|
||||
| 类别 | 数量 | 占比 |
|
||||
|------|------|------|
|
||||
| ✨ 新功能 | 3 | 60% |
|
||||
| 📝 文档 | 2 | 40% |
|
||||
```
|
||||
|
||||
### Step 6：创建 Release
|
||||
|
||||
```bash
|
||||
gitlink-cli release +create --owner z2_cc --repo gitlink-cli \
|
||||
--tag v1.3.0 \
|
||||
--name "v1.3.0" \
|
||||
--body "## v1.3.0 (2026-06-17)\n\n### 📊 版本概览\n- 5 次提交 | 12 个文件变更\n- +245 / -89 行 | 1 位贡献者\n\n### ✨ 新功能（3）\n- feat: 新增 Webhook 投递监控\n- feat: 新增三个 AI Agent Skill\n- feat: 新增 Wiki 和代码片段 Skill" \
|
||||
--target master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完整命令速览
|
||||
|
||||
```bash
|
||||
# 1. 获取基线版本
|
||||
gitlink-cli release +list
|
||||
|
||||
# 2. 获取提交历史
|
||||
git log <基线>..HEAD --format="%H|%s|%an|%ad" --date=short
|
||||
|
||||
# 3. 统计变更
|
||||
git log <基线>..HEAD --stat --oneline
|
||||
|
||||
# 4. 创建 Release
|
||||
gitlink-cli release +create --tag <版本> --name <名称> --body <Release Notes>
|
||||
```
|
||||
|
|
@ -109,6 +109,9 @@ gitlink-cli auth login
|
|||
| PR 合并需要 `do` 参数 | `pr +merge` 需传 `do` 字段指定合并方式（merge/rebase/squash） | `pr +merge` 已内置处理 |
|
||||
| PR 列表 state 过滤 | `--state` 参数仅影响统计计数，返回列表可能包含所有状态 | 需通过 `pull_request_status` 字段客户端过滤：0=open, 1=merged, 2=closed |
|
||||
| PR 创建需要代码差异 | 分支内容必须与目标分支不同，否则拒绝创建 | 需要先在分支上有实际提交 |
|
||||
| **PR Diff 命令已变更** | `pr +diff` 已移除（与 `file` 命令冗余）。取 PR 代码差异用 `pr +versions --id <pr>` 拿 `version_id`，再 `pr +version-diff --id <pr> --version-id <vid>`（diff 在 `files[].sections[].lines[]`，`type` 2=新增/3=删除/4=hunk 头） | `pr +version-diff` 替代原 `pr +diff`；`--file` 过滤不稳，建议整份取后客户端筛 |
|
||||
| **Issue 打标签需用 Raw API** | `issue +update --label <id>` 不可用（CLI 发单数 `issue_tag_id`，被忽略）；`issue +batch-update --label a,b,c` 是**集合式**（整组标签打到每个 Issue，非按位置对应） | 打标签用 Raw API `PATCH /:owner/:repo/issues/:n --body '{"issue_tag_ids":[<id>],"subject":"<原>","description":"<原>"}'`；`label +list` 返回 `data.issue_tags[]`，`issue +view` 标签字段为 `tags` |
|
||||
| **PR 行内评论锚定失效** | `pr +create-comment --path --line --body` 返回 `ok` 但 `line_code=null`，评论未真正绑定到行（仅文件级） | 评审意见优先放 `pr +review --status <common\|approved\|rejected> --content`；单条补充用 `pr +comment`（不绑行） |
|
||||
|
||||
## 文件操作 API
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue