forked from z2_cc/gitlink-cli
Compare commits
14 Commits
master
...
feat/gitli
| Author | SHA1 | Date |
|---|---|---|
刘焱
|
e7cdf8fc26 | |
|
刘焱
|
29f8d3403c | |
|
刘焱
|
654c8976df | |
|
刘焱
|
f8eea302fb | |
|
刘焱
|
f0f20e5e8e | |
|
刘焱
|
bbc1367a88 | |
|
刘焱
|
cfc28287f4 | |
|
刘焱
|
c2eb3c8f1a | |
|
刘焱
|
bb0ef89450 | |
|
刘焱
|
ef2aa17c8e | |
|
刘焱
|
f071f456fa | |
|
刘焱
|
a6e174da88 | |
|
刘焱
|
34a0dc0d78 | |
|
刘焱
|
a147812e60 |
|
|
@ -0,0 +1,694 @@
|
|||
<!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; }
|
||||
|
||||
/* Tab navigation */
|
||||
.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; }
|
||||
.tab .badge { display: inline-block; background: rgba(255,255,255,0.3); padding: 0 8px; border-radius: 10px; font-size: 11px; margin-left: 6px; }
|
||||
|
||||
/* Panel */
|
||||
.panel { display: none; }
|
||||
.panel.active { display: block; }
|
||||
|
||||
/* Skill intro */
|
||||
.skill-intro { background: #fff; border-radius: 12px; padding: 20px 24px; margin-bottom: 20px; box-shadow: 0 2px 8px rgba(0,0,0,0.06); }
|
||||
.skill-intro h2 { font-size: 20px; color: #1a1a2e; margin-bottom: 6px; }
|
||||
.skill-intro p { font-size: 14px; color: #555; line-height: 1.7; }
|
||||
.skill-intro .tags { margin-top: 10px; }
|
||||
.skill-intro .tag { display: inline-block; background: #e8f0fe; color: #1a73e8; padding: 3px 12px; border-radius: 12px; font-size: 12px; margin: 2px 4px 2px 0; }
|
||||
.skill-intro .file-link { display: inline-block; margin-top: 8px; font-size: 13px; color: #1a73e8; text-decoration: none; }
|
||||
.skill-intro .file-link:hover { text-decoration: underline; }
|
||||
|
||||
/* Steps */
|
||||
.step-card { background: #fff; border-radius: 12px; margin-bottom: 16px; box-shadow: 0 2px 8px rgba(0,0,0,0.06); overflow: hidden; }
|
||||
.step-header { display: flex; align-items: center; padding: 16px 20px; cursor: pointer; transition: background 0.2s; }
|
||||
.step-header:hover { background: #f8f9fa; }
|
||||
.step-num { width: 28px; height: 28px; background: #1a73e8; color: #fff; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 13px; font-weight: 700; margin-right: 12px; flex-shrink: 0; }
|
||||
.step-header .title { flex: 1; font-size: 15px; font-weight: 600; color: #1a1a2e; }
|
||||
.step-header .arrow { font-size: 18px; color: #999; transition: transform 0.2s; }
|
||||
.step-header.open .arrow { transform: rotate(90deg); }
|
||||
.step-body { display: none; padding: 0 20px 16px; }
|
||||
.step-body.open { display: block; }
|
||||
.step-body .cmd { background: #1e1e2e; color: #cdd6f4; padding: 12px 16px; border-radius: 8px; font-family: "Consolas", monospace; font-size: 13px; overflow-x: auto; margin-bottom: 12px; }
|
||||
.step-body .cmd .prompt { color: #89b4fa; }
|
||||
.step-body .output { background: #f8f9fa; border: 1px solid #e2e8f0; border-radius: 8px; padding: 12px 16px; font-family: "Consolas", monospace; font-size: 12px; overflow-x: auto; max-height: 300px; overflow-y: auto; color: #333; white-space: pre; }
|
||||
.step-body .desc { font-size: 14px; color: #555; margin-bottom: 10px; }
|
||||
|
||||
/* Run button */
|
||||
.run-btn { background: #34a853; color: #fff; border: none; padding: 6px 16px; border-radius: 6px; cursor: pointer; font-size: 13px; margin-top: 8px; }
|
||||
.run-btn:hover { background: #2d8f47; }
|
||||
.run-btn:disabled { background: #a0aec0; cursor: not-allowed; }
|
||||
|
||||
/* extra info */
|
||||
.info-box { background: #e8f0fe; border-radius: 8px; padding: 12px 16px; font-size: 13px; color: #1a56db; margin-top: 12px; }
|
||||
.info-box strong { color: #1a1a2e; }
|
||||
|
||||
/* copy */
|
||||
.copy-btn { float: right; background: none; border: 1px solid #ddd; padding: 3px 10px; border-radius: 4px; cursor: pointer; font-size: 11px; color: #666; }
|
||||
.copy-btn:hover { background: #f0f0f0; }
|
||||
|
||||
@media (max-width: 768px) { .tabs { flex-direction: column; } }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
<h1>GitLink CLI Skills 交互式演示</h1>
|
||||
<p>点击按钮查看命令执行结果 — 展示 AI Agent 能自动完成的工作</p>
|
||||
</div>
|
||||
|
||||
<div class="container">
|
||||
|
||||
<!-- Tab navigation -->
|
||||
<div class="tabs" id="tabs">
|
||||
<button class="tab active" data-tab="release">Release Notes 生成</button>
|
||||
<button class="tab" data-tab="health">项目健康度报告</button>
|
||||
<button class="tab" data-tab="triage">Issue 自动分拣</button>
|
||||
<button class="tab" data-tab="compliance">许可证合规检查</button>
|
||||
<button class="tab" data-tab="newcomer">新人引导</button>
|
||||
<button class="tab" data-tab="skill">Skills 文件结构</button>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel 1: Release Notes ============= -->
|
||||
<div class="panel active" id="panel-release">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>Release Notes 生成</h2>
|
||||
<p>根据 commit 和 PR 记录自动生成结构化的版本说明，按 Conventional Commits 规范分类。</p>
|
||||
<div class="tags">
|
||||
<span class="tag">gitlink-cli release +list</span>
|
||||
<span class="tag">gitlink-cli pr +list</span>
|
||||
<span class="tag">gitlink-cli release +create</span>
|
||||
</div>
|
||||
<a class="file-link" href="../skills/gitlink-release-auto/examples/release-notes-workflow.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<!-- Step 1 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">1</span>
|
||||
<span class="title">获取最新 Release</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body" id="release-step1-body">
|
||||
<div class="desc">查看项目当前最新的 Release 版本信息，确定上次发布的位置。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli release +list --owner z2_cc --repo gitlink-cli --format json</div>
|
||||
<div class="output" id="release-step1-output">{
|
||||
"data": [
|
||||
{
|
||||
"tag_name": "v1.0.0",
|
||||
"name": "v1.0.0",
|
||||
"body": "初始版本发布",
|
||||
"created_at": "2026-05-25"
|
||||
}
|
||||
]
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 2 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">2</span>
|
||||
<span class="title">获取提交记录</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取自上次发布以来的所有 commit 记录，用于生成变更日志。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> git log v1.0.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</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 3 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">3</span>
|
||||
<span class="title">获取 PR 列表</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取本期合并的 PR 列表，用于补充 Release Notes 中的 PR 引用。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli pr +list --owner z2_cc --repo gitlink-cli --state merged --limit 10 --format json</div>
|
||||
<div class="output">{
|
||||
"data": {
|
||||
"pull_requests": [
|
||||
{ "number": 31, "title": "fix: normalize issue list output", "state": "merged" }
|
||||
]
|
||||
}
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 4 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">4</span>
|
||||
<span class="title">生成 Release Notes</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">AI 分析数据，按规范生成结构化的发布说明。</div>
|
||||
<div class="info-box">
|
||||
<strong>AI 生成结果：</strong><br><br>
|
||||
## v1.3.0 (2026-06-17)<br><br>
|
||||
### ✨ 新功能<br>
|
||||
- 新增 Webhook 投递监控（failed / task-view）<br>
|
||||
- 新增 Wiki 管理 Skill<br>
|
||||
- 新增代码片段管理 Skill<br><br>
|
||||
### 📦 其他变更<br>
|
||||
- 更新文档和工作流示例
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel 2: 项目健康度 ============= -->
|
||||
<div class="panel" id="panel-health">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>项目健康度报告</h2>
|
||||
<p>统计 Issue 响应时间、PR 合并效率、贡献者活跃度，生成项目健康度分析报告。</p>
|
||||
<div class="tags">
|
||||
<span class="tag">gitlink-cli repo +info</span>
|
||||
<span class="tag">gitlink-cli issue +list</span>
|
||||
<span class="tag">gitlink-cli pr +list</span>
|
||||
<span class="tag">gitlink-cli commit +list</span>
|
||||
</div>
|
||||
<a class="file-link" href="../skills/gitlink-project-health/examples/health-report-workflow.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<!-- Step 1 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">1</span>
|
||||
<span class="title">获取项目基本信息</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取仓库的基本信息：Star 数、Fork 数、描述等。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli repo +info --owner z2_cc --repo gitlink-cli --format json</div>
|
||||
<div class="output">{
|
||||
"data": {
|
||||
"full_name": "z2_cc/gitlink-cli",
|
||||
"default_branch": "master",
|
||||
"issues_count": 12,
|
||||
"pull_requests_count": 5,
|
||||
"forked_count": 0,
|
||||
"watchers_count": 1,
|
||||
"size": "2.3 MB"
|
||||
}
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 2 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">2</span>
|
||||
<span class="title">统计 Issue</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取 Issue 统计数据：总数、打开数、关闭数。</div>
|
||||
<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">{
|
||||
"data": {
|
||||
"issues": [
|
||||
{ "number": 10, "subject": "新增 Shortcut: Wiki 管理", "status_id": 5 },
|
||||
{ "number": 12, "subject": "新增 Shortcut: 代码片段", "status_id": 5 },
|
||||
{ "number": 14, "subject": "Webhook 投递监控", "status_id": 1 },
|
||||
{ "number": 15, "subject": "新增 Webhook 投递监控", "status_id": 1 }
|
||||
],
|
||||
"closed_count": 3,
|
||||
"has_created_issues": true
|
||||
}
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 3 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">3</span>
|
||||
<span class="title">统计 PR</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取 PR 统计数据：总数、打开数、已合并数。</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">{
|
||||
"data": {
|
||||
"pull_requests": [
|
||||
{ "number": 31, "title": "fix: normalize issue list output", "state": "merged" }
|
||||
]
|
||||
}
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Step 4 -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">4</span>
|
||||
<span class="title">查看提交活跃度</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">获取近期提交记录，分析贡献者活跃度和提交频率。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli commit +list --owner z2_cc --repo gitlink-cli --limit 10</div>
|
||||
<div class="output">[
|
||||
{ "sha": "a4587f9", "author": "wqer", "message": "feat: add webhook +failed..." },
|
||||
{ "sha": "37a0f21", "author": "wqer", "message": "docs: add release notes..." },
|
||||
{ "sha": "6c0ad3b", "author": "wqer", "message": "feat: add three new skills" },
|
||||
{ "sha": "9a51db0", "author": "wqer", "message": "feat: add wiki and snippet skills" }
|
||||
]</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Result summary -->
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)" style="background:#e8f0fe;">
|
||||
<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-body">
|
||||
<div class="info-box">
|
||||
<strong>项目健康度报告</strong><br><br>
|
||||
<strong>基本信息</strong><br>
|
||||
- 项目：z2_cc/gitlink-cli<br>
|
||||
- 默认分支：master<br><br>
|
||||
<strong>Issue 状况</strong><br>
|
||||
- 总 Issue 数：12<br>
|
||||
- 已关闭：3<br>
|
||||
- 打开中：2<br><br>
|
||||
<strong>PR 状况</strong><br>
|
||||
- 总 PR 数：5<br>
|
||||
- 已合并：1<br>
|
||||
- 打开中：0<br><br>
|
||||
<strong>活跃度</strong><br>
|
||||
- 近期提交：15+ 次<br>
|
||||
- 活跃贡献者：1 人<br><br>
|
||||
🟢 总体评价：项目健康
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel 3: Issue 自动分拣 ============= -->
|
||||
<div class="panel" id="panel-triage">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>Issue 自动分拣</h2>
|
||||
<p>根据 Issue 内容自动分类（Bug / 功能 / 文档）、打标签、分配责任人、添加引导评论。</p>
|
||||
<div class="tags">
|
||||
<span class="tag">gitlink-cli issue +list</span>
|
||||
<span class="tag">gitlink-cli issue +view</span>
|
||||
<span class="tag">gitlink-cli issue +comment</span>
|
||||
</div>
|
||||
<a class="file-link" href="../skills/gitlink-issue-triage/examples/triage-workflow.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">1</span>
|
||||
<span class="title">获取待处理 Issue</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">列出所有打开的 Issue，筛选需要分类的任务。</div>
|
||||
<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">{
|
||||
"issues": [
|
||||
{ "number": 14, "subject": "新增 Shortcut: Webhook 投递监控", "status_id": 1 },
|
||||
{ "number": 15, "subject": "Webhook 投递监控（failed + task-view）", "status_id": 1 }
|
||||
]
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">2</span>
|
||||
<span class="title">分析 Issue 内容</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">AI 根据标题和描述关键词判断 Issue 类别。</div>
|
||||
<div class="info-box">
|
||||
<strong>分类规则示例：</strong><br>
|
||||
"报错、错误、bug" → Bug<br>
|
||||
"建议、希望" → 功能需求<br>
|
||||
"文档、拼写" → 文档<br>
|
||||
"请问、怎么" → 问题咨询
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">3</span>
|
||||
<span class="title">添加分类评论</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">AI 根据分类结果自动添加引导评论。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 14 --body "感谢提交 Issue！已自动分类为 **功能需求**..."</div>
|
||||
<div class="info-box">
|
||||
<strong>AI 自动生成的评论示例：</strong><br><br>
|
||||
感谢提交 Issue！已自动分类为 <strong>功能需求</strong>。<br><br>
|
||||
请补充以下信息：<br>
|
||||
1. 这个功能解决了什么场景的问题？<br>
|
||||
2. 预期的行为是什么？<br>
|
||||
3. 是否有参考实现？
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel: 许可证合规检查 ============= -->
|
||||
<div class="panel" id="panel-compliance">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>许可证合规检查</h2>
|
||||
<p>扫描仓库的许可证合规性和敏感信息泄露风险：识别 LICENSE、核对依赖兼容性、批量扫描密钥 / Token / 数据库连接串，生成结构化合规报告与修复建议。</p>
|
||||
<div class="tags">
|
||||
<span class="tag">gitlink-cli repo +info</span>
|
||||
<span class="tag">gitlink-cli api GET .../raw</span>
|
||||
<span class="tag">git clone + git grep</span>
|
||||
<span class="tag">gitlink-cli api GET .../sub_entries</span>
|
||||
</div>
|
||||
<a class="file-link" href="../skills/gitlink-compliance/examples/compliance-check-workflow.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">1</span>
|
||||
<span class="title">获取仓库元信息</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">确认 owner/repo、默认分支，以及平台返回的许可证字段。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli repo +info --owner z2_cc --repo gitlink-cli --format json</div>
|
||||
<div class="output">{
|
||||
"data": {
|
||||
"full_name": "z2_cc/gitlink-cli",
|
||||
"default_branch": "master",
|
||||
"license": null
|
||||
}
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">2</span>
|
||||
<span class="title">识别 LICENSE 类型</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">读取根目录 LICENSE 文件内容，按关键词识别许可证类型（MIT / Apache-2.0 / MulanPSL-2 等）。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli api GET /z2_cc/gitlink-cli/raw/master/LICENSE</div>
|
||||
<div class="output">MIT License
|
||||
|
||||
Copyright (c) 2026 Gitlink
|
||||
Permission is hereby granted, free of charge ...
|
||||
... → 识别为 MIT 许可证</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">3</span>
|
||||
<span class="title">依赖合规分析</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">读取依赖声明文件，逐依赖对照兼容性矩阵评估与项目主许可证的兼容性。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli api GET /z2_cc/gitlink-cli/raw/master/go.mod</div>
|
||||
<div class="output">module github.com/gitlink/gitlink-cli
|
||||
go 1.21
|
||||
|
||||
require (
|
||||
github.com/spf13/cobra v1.8.0
|
||||
github.com/stretchr/testify v1.9.0
|
||||
)
|
||||
→ 依赖均为 MIT 兼容许可证 ✅</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">4</span>
|
||||
<span class="title">敏感信息扫描（批量）</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">clone 仓库后用 git grep 对高危特征做正则扫描：AWS Key、GitHub Token、私钥、数据库连接串等。命令中的 AKIA[0-9A-Z]{16} 等是正则模式，非真实凭据。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> git clone https://www.gitlink.org.cn/z2_cc/gitlink-cli.git /tmp/gitlink-cli-scan<br><span class="prompt">$</span> cd /tmp/gitlink-cli-scan<br><span class="prompt">$</span> git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD</div>
|
||||
<div class="output">examples/demo.go:45:token: "example_token_for_demo" # 🟢 低风险（占位假值）</div>
|
||||
<div class="info-box">
|
||||
<strong>风险分级：</strong><br>
|
||||
🔴 严重：真实密钥 / Token / 私钥 → 立即撤销并清理 Git 历史<br>
|
||||
🟠 高：数据库连接串硬编码 → 改用环境变量<br>
|
||||
🟡 中：内网地址 / 测试账号 → 评估影响<br>
|
||||
🟢 低：疑似但可能为示例 → 人工确认
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)" style="background:#e8f0fe;">
|
||||
<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-body">
|
||||
<div class="info-box">
|
||||
<strong>⚖️ 合规检查报告 — z2_cc/gitlink-cli</strong><br><br>
|
||||
📋 项目许可证：MIT<br><br>
|
||||
<strong>🔴 必须修复</strong><br>
|
||||
- 无<br><br>
|
||||
<strong>🟡 建议修复</strong><br>
|
||||
- 缺少 SECURITY.md → 添加安全披露流程<br><br>
|
||||
<strong>🔴 敏感信息扫描</strong><br>
|
||||
- 🟢 examples/demo.go:45 — token 占位假值（加注释说明即可）<br><br>
|
||||
<strong>📊 合规评分</strong><br>
|
||||
📜 许可证 ✅ ｜ 🏷️ 版权声明 ⚠️ ｜ 📦 依赖合规 ✅ ｜ 🔒 安全策略 ⚠️ ｜ 🔒 敏感信息管控 ✅<br>
|
||||
<strong>总体合规评分：82/100</strong>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel: 新人引导 ============= -->
|
||||
<div class="panel" id="panel-newcomer">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>新人引导</h2>
|
||||
<p>为 good-first-issue 自动添加引导评论，降低新贡献者参与门槛：识别入门标签、按 Issue 类型选模板、用标记串幂等去重不刷屏。</p>
|
||||
<div class="tags">
|
||||
<span class="tag">gitlink-cli issue +list</span>
|
||||
<span class="tag">gitlink-cli issue +view</span>
|
||||
<span class="tag">gitlink-cli api GET .../journals</span>
|
||||
<span class="tag">gitlink-cli issue +comment</span>
|
||||
</div>
|
||||
<a class="file-link" href="../skills/gitlink-newcomer-guide/examples/newcomer-guide-workflow.md" target="_blank">查看 SKILL.md →</a>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">1</span>
|
||||
<span class="title">查找 good-first-issue</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">列出开放 Issue，用返回的 tags[].name 匹配入门标签（good-first-issue / 新手 / help-wanted 等），并按 status_id ∈ {1,2} 二次过滤。</div>
|
||||
<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">{
|
||||
"issues": [
|
||||
{
|
||||
"number": 10,
|
||||
"subject": "新增 Shortcut: Wiki 管理",
|
||||
"status_id": 1,
|
||||
"tags": [{ "name": "good first issue" }],
|
||||
"assigners": []
|
||||
}
|
||||
]
|
||||
}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">2</span>
|
||||
<span class="title">查看 Issue 详情判断类型</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">查看 Issue 详情，根据描述判断类型（Bug / 功能需求 / 文档），选择对应的引导评论模板。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 10 --format json</div>
|
||||
<div class="info-box">
|
||||
<strong>类型判定规则：</strong><br>
|
||||
"报错、bug" → Bug 模板<br>
|
||||
"建议、希望、新增" → 功能需求模板<br>
|
||||
"文档、拼写" → 文档模板
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">3</span>
|
||||
<span class="title">幂等去重检查</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">读取已有评论，扫描是否含标记串 gitlink-newcomer-guide:v1，命中则跳过，避免重复刷屏。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli api GET /v1/z2_cc/gitlink-cli/issues/10/journals --format json</div>
|
||||
<div class="output">{
|
||||
"data": { "journals": [] }
|
||||
}
|
||||
→ 未命中标记串，继续添加引导评论</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="step-card">
|
||||
<div class="step-header" onclick="toggle(this)">
|
||||
<span class="step-num">4</span>
|
||||
<span class="title">添加引导评论（写操作，先确认）</span>
|
||||
<span class="arrow">▶</span>
|
||||
</div>
|
||||
<div class="step-body">
|
||||
<div class="desc">写操作，执行前确认用户意图。评论末尾带上标记串，便于下次去重。</div>
|
||||
<div class="cmd"><span class="prompt">$</span> gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 10 --body "..."</div>
|
||||
<div class="info-box">
|
||||
<strong>AI 自动生成的引导评论：</strong><br><br>
|
||||
你好！欢迎参与贡献 🎉<br><br>
|
||||
这个 Issue 被标记为 <strong>good first issue</strong>，非常适合作为你的第一个贡献。<br><br>
|
||||
<strong>如何开始</strong><br>
|
||||
1. 在评论区留言"我想认领"，我们会把你添加到 Assignee<br>
|
||||
2. Fork 本仓库并创建你的功能分支<br>
|
||||
3. 修复问题后提交 Pull Request<br><br>
|
||||
祝你编码愉快！<br>
|
||||
<!-- gitlink-newcomer-guide:v1 -->
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- ============= Panel 4: Skills 结构 ============= -->
|
||||
<div class="panel" id="panel-skill">
|
||||
|
||||
<div class="skill-intro">
|
||||
<h2>Skills 文件结构总览</h2>
|
||||
<p>展示所有新增和更新的 Skill 文件，以及每个 Skill 所包含的内容。</p>
|
||||
</div>
|
||||
|
||||
<div style="display:grid; grid-template-columns: repeat(2, 1fr); gap:16px;">
|
||||
<div style="background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06); border-left:4px solid #34a853;">
|
||||
<h3 style="font-size:16px; margin-bottom:4px;">Release Notes 生成</h3>
|
||||
<p style="font-size:13px; color:#555;">根据 commit/PR 生成版本说明</p>
|
||||
<div style="font-size:12px; color:#999; margin-top:8px;">
|
||||
SKILL.md + examples/<br>
|
||||
<span style="color:#34a853;">涉及命令：release +list, pr +list</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06); border-left:4px solid #34a853;">
|
||||
<h3 style="font-size:16px; margin-bottom:4px;">项目健康度报告</h3>
|
||||
<p style="font-size:13px; color:#555;">统计 Issue/PR/commit 数据</p>
|
||||
<div style="font-size:12px; color:#999; margin-top:8px;">
|
||||
SKILL.md + examples/<br>
|
||||
<span style="color:#34a853;">涉及命令：repo +info, issue +list, pr +list, commit +list</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06); border-left:4px solid #34a853;">
|
||||
<h3 style="font-size:16px; margin-bottom:4px;">Issue 自动分拣</h3>
|
||||
<p style="font-size:13px; color:#555;">自动分类 Issue 并添加评论</p>
|
||||
<div style="font-size:12px; color:#999; margin-top:8px;">
|
||||
SKILL.md + examples/<br>
|
||||
<span style="color:#34a853;">涉及命令：issue +list, issue +view, issue +comment</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06); border-left:4px solid #34a853;">
|
||||
<h3 style="font-size:16px; margin-bottom:4px;">许可证合规检查</h3>
|
||||
<p style="font-size:13px; color:#555;">许可证 / 依赖 / 敏感信息扫描</p>
|
||||
<div style="font-size:12px; color:#999; margin-top:8px;">
|
||||
SKILL.md + REFERENCE.md + examples/<br>
|
||||
<span style="color:#34a853;">涉及命令：repo +info, api raw, git grep</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06); border-left:4px solid #34a853;">
|
||||
<h3 style="font-size:16px; margin-bottom:4px;">新人引导</h3>
|
||||
<p style="font-size:13px; color:#555;">为 good-first-issue 添加引导</p>
|
||||
<div style="font-size:12px; color:#999; margin-top:8px;">
|
||||
SKILL.md + examples/<br>
|
||||
<span style="color:#34a853;">涉及命令：issue +view, issue +comment</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div style="margin-top:20px; background:#fff; border-radius:12px; padding:20px; box-shadow:0 2px 8px rgba(0,0,0,0.06);">
|
||||
<h3 style="font-size:16px; margin-bottom:12px;">新建和更新的 Skill 文件</h3>
|
||||
<table style="width:100%; border-collapse:collapse; font-size:14px;">
|
||||
<thead><tr style="background:#f8f9fa;"><th style="text-align:left; padding:8px 12px;">文件路径</th><th style="text-align:left; padding:8px 12px;">状态</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-release-auto/examples/release-notes-workflow.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-project-health/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-project-health/examples/health-report-workflow.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-issue-triage/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-issue-triage/examples/triage-workflow.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-compliance/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-compliance/REFERENCE.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-compliance/examples/compliance-check-workflow.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-newcomer-guide/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-newcomer-guide/examples/newcomer-guide-workflow.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-wiki/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-snippet/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#34a853;">新增</td></tr>
|
||||
<tr><td style="padding:8px 12px; border-top:1px solid #eee;">skills/gitlink-webhook/SKILL.md</td><td style="padding:8px 12px; border-top:1px solid #eee; color:#fbbc04;">更新</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<script>
|
||||
function toggle(el) {
|
||||
el.classList.toggle('open');
|
||||
var body = el.nextElementSibling;
|
||||
body.classList.toggle('open');
|
||||
}
|
||||
|
||||
// Tab switching
|
||||
document.querySelectorAll('.tab').forEach(function(tab) {
|
||||
tab.addEventListener('click', function() {
|
||||
document.querySelectorAll('.tab').forEach(function(t) { t.classList.remove('active'); });
|
||||
document.querySelectorAll('.panel').forEach(function(p) { p.classList.remove('active'); });
|
||||
this.classList.add('active');
|
||||
document.getElementById('panel-' + this.dataset.tab).classList.add('active');
|
||||
});
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
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>
|
||||
|
|
@ -0,0 +1,221 @@
|
|||
# 项目级 Skill 集成 实现计划
|
||||
|
||||
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
|
||||
|
||||
**目标：** 在 gitlink-cl 项目内通过逐 skill junction 让 Claude Code 发现并调用 23 个 gitlink skill（仅项目级）。
|
||||
|
||||
**架构：** `.claude/skills/` 为真实目录，其下每个 skill 子目录是 Windows junction（`mklink /J`），指向项目根 `skills/<同名>`；`.gitignore` 忽略该区域；复用全局已登录的 `gitlink-cli`（`liuyan688`）。
|
||||
|
||||
**技术栈：** Windows 目录联接（`mklink /J`，无需管理员权限）、Git Bash、Claude Code 项目级 skill 加载。
|
||||
|
||||
**对应规格：** `doc/specs/2026-06-17-project-local-skills-design.md`
|
||||
|
||||
**前置已就绪：** `gitlink-cli` 全局可用且已登录；`skills/` 下 23 个 skill frontmatter 合规（name+description、目录名一致）。
|
||||
|
||||
> **验证说明：** 本计划为配置/集成任务，每步以「精确命令 + 预期输出」作为可验证依据（替代传统单元测试）。任务 3 是决定性关口，决定是否触发任务 4 退路。
|
||||
|
||||
---
|
||||
|
||||
### 任务 1：创建 .claude/skills 目录与 23 个逐 skill junction
|
||||
|
||||
**文件：**
|
||||
- 创建：`.claude/skills/`（真实目录）
|
||||
- 创建：23 个 junction `.claude/skills/<skill-name>` → `skills/<skill-name>`
|
||||
|
||||
- [ ] **步骤 1：创建 .claude/skills 真实目录**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
mkdir -p .claude/skills
|
||||
ls -d .claude/skills
|
||||
```
|
||||
预期输出：`.claude/skills`
|
||||
|
||||
- [ ] **步骤 2：批量创建 23 个逐 skill junction（绝对路径）**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
for d in skills/*/; do
|
||||
name=$(basename "$d")
|
||||
link="$(cygpath -w "$PWD/.claude/skills/$name")"
|
||||
target="$(cygpath -w "$PWD/skills/$name")"
|
||||
cmd //c "mklink /J \"$link\" \"$target\"" && echo "✓ $name" || echo "✗ $name 失败"
|
||||
done
|
||||
```
|
||||
预期：23 行 `✓ <name>`，每个前缀含 `Junction created for ...` 字样。
|
||||
|
||||
- [ ] **步骤 3：验证 junction 数量与穿透读取**
|
||||
|
||||
```bash
|
||||
# 数量应为 23
|
||||
ls -1 .claude/skills/ | wc -l
|
||||
# 预期：23
|
||||
|
||||
# 穿透 junction 读 SKILL.md（抽样）
|
||||
head -2 .claude/skills/gitlink-compliance/SKILL.md
|
||||
head -2 .claude/skills/gitlink-newcomer-guide/SKILL.md
|
||||
head -2 .claude/skills/gitlink-shared/SKILL.md
|
||||
# 预期：每个显示 `---` 与 `name:` 行
|
||||
|
||||
# 确认全部为 JUNCTION 类型
|
||||
cmd //c "dir .claude\\skills" | grep -ci junction
|
||||
# 预期：23
|
||||
```
|
||||
|
||||
- [ ] **步骤 4：本任务不单独 commit**
|
||||
|
||||
junction 是文件系统链接，git 不追踪其内容；`.claude/skills/` 将在任务 2 加入 `.gitignore`。本任务无入库文件，跳过 commit。
|
||||
|
||||
---
|
||||
|
||||
### 任务 2：配置 .gitignore 忽略 .claude/skills
|
||||
|
||||
**文件：**
|
||||
- 修改：`.gitignore`
|
||||
|
||||
- [ ] **步骤 1：检查 .gitignore 现状**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
grep -n "claude" .gitignore || echo "未含 claude 相关条目"
|
||||
```
|
||||
预期：输出"未含 claude 相关条目"（若已含 `.claude/` 或 `.claude/skills/` 则跳过步骤 2，直接进步骤 3）。
|
||||
|
||||
- [ ] **步骤 2：追加忽略规则（仅当步骤 1 未含）**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
printf '\n# Claude Code 项目级 skill（junction 指向本地 skills/，不入库）\n.claude/skills/\n' >> .gitignore
|
||||
```
|
||||
|
||||
- [ ] **步骤 3：验证忽略生效**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
git check-ignore .claude/skills/gitlink-compliance
|
||||
# 预期：输出 `.claude/skills/gitlink-compliance`（被忽略）
|
||||
|
||||
git status --short
|
||||
# 预期：仅 `.gitignore` 显示为 ` M`；不出现 `.claude/skills/` 下任何内容
|
||||
```
|
||||
|
||||
- [ ] **步骤 4：Commit**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
git add .gitignore
|
||||
git commit -m "chore: gitignore 项目级 Claude Code skill junction 区域"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 任务 3：Claude Code 兼容性验证（新会话，决定性关口）
|
||||
|
||||
**说明：** 此任务由**用户在新 Claude Code 会话**中执行——当前会话工作目录非本项目，且会话启动后才新建的顶层 `.claude/skills/` 必须重启会话才能被发现（规格 §3.2）。这是判断 junction 方案是否被 Claude Code 接受的决定性验证，直接对应「保证兼容」诉求。
|
||||
|
||||
**前置：** 任务 1、任务 2 完成。
|
||||
|
||||
- [ ] **步骤 1：在 gitlink-cl 目录开新 Claude Code 会话**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
claude
|
||||
```
|
||||
|
||||
- [ ] **步骤 2：确认无加载错误**
|
||||
|
||||
新会话内运行：
|
||||
```
|
||||
/doctor
|
||||
```
|
||||
预期：无 skill 加载错误、无 description 预算溢出告警。
|
||||
|
||||
- [ ] **步骤 3：确认 23 个 skill 被发现**
|
||||
|
||||
新会话内运行 `/skills` 或问：
|
||||
```
|
||||
列出当前可用的所有 gitlink 开头的 skill
|
||||
```
|
||||
预期：列表中含 23 个 `gitlink-*` skill。
|
||||
|
||||
- [ ] **步骤 4：端到端验证命令链（只读）**
|
||||
|
||||
新会话内：
|
||||
```
|
||||
用 gitlink-user skill 查看当前登录用户
|
||||
```
|
||||
预期：AI 加载 `gitlink-user` skill 并执行 `gitlink-cli user +me`，返回 `liuyan688` 信息。
|
||||
|
||||
- [ ] **步骤 5：判定**
|
||||
|
||||
- 步骤 2-4 全通过 → 兼容性确认，**任务 4 跳过**，集成完成。
|
||||
- 任一步失败（skill 不出现 / doctor 报错）→ 执行**任务 4** 退路。
|
||||
|
||||
---
|
||||
|
||||
### 任务 4（条件退路）：junction 不被识别时改为真实复制
|
||||
|
||||
**触发条件：** 仅当任务 3 验证失败时执行。
|
||||
|
||||
**文件：**
|
||||
- 删除：23 个 junction
|
||||
- 创建：`.claude/skills/<name>/` 真实目录（复制自 `skills/<name>`）
|
||||
|
||||
- [ ] **步骤 1：移除 junction**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
for d in .claude/skills/*/; do
|
||||
name=$(basename "$d")
|
||||
cmd //c "rmdir .claude\\skills\\$name" && echo "✓ 移除 $name"
|
||||
done
|
||||
```
|
||||
预期：23 行 `✓ 移除 <name>`（rmdir 对 junction 只删链接不删源）。
|
||||
|
||||
- [ ] **步骤 2：真实复制 23 个 skill**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
for d in skills/*/; do
|
||||
name=$(basename "$d")
|
||||
cp -r "skills/$name" ".claude/skills/$name"
|
||||
done
|
||||
ls -1 .claude/skills/ | wc -l
|
||||
# 预期：23
|
||||
```
|
||||
|
||||
- [ ] **步骤 3：确认 .gitignore 仍生效（避免入库重复）**
|
||||
|
||||
```bash
|
||||
cd /c/Users/刘焱/Desktop/gitlink-cl
|
||||
git check-ignore .claude/skills/gitlink-compliance
|
||||
# 预期：输出 `.claude/skills/gitlink-compliance`
|
||||
git status --short
|
||||
# 预期：无 .claude/skills 相关条目
|
||||
```
|
||||
|
||||
- [ ] **步骤 4：重新验证（同任务 3 步骤 2-4）**
|
||||
|
||||
在新会话重跑 `/doctor` + skill 列表 + 端到端。预期全通过。
|
||||
|
||||
- [ ] **步骤 5：记录退路决策**
|
||||
|
||||
无需 commit（`.claude/skills/` 仍被忽略）。在规格文档或 PR 说明注明「因 junction 未被 Claude Code 识别，改用真实复制」。
|
||||
|
||||
---
|
||||
|
||||
## 自检
|
||||
|
||||
**1. 规格覆盖度：**
|
||||
- §1 目标 → 任务 1-3
|
||||
- §2 现状 → 前置已就绪声明
|
||||
- §3 兼容性结论 → 任务 3 验证 + 任务 4 退路
|
||||
- §4 方案（逐 skill junction / gitignore / 命令桥接）→ 任务 1 / 任务 2 / 任务 3 步骤 4
|
||||
- §5 数据流、§6 验证 → 任务 3
|
||||
- §7 错误处理与退路 → 任务 4
|
||||
- §8 范围外 → 计划未涉及全局安装/settings.json
|
||||
✅ 全覆盖，无遗漏。
|
||||
|
||||
**2. 占位符扫描：** 无 TODO/待定/「类似任务N」；每步含完整命令与预期输出。✅
|
||||
|
||||
**3. 类型/路径一致性：** `.claude/skills/`、`skills/`、`gitlink-cli`、`liuyan688`、23 个 skill 名——跨任务一致。✅
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
# 项目级 Skill 集成设计 — gitlink-cl
|
||||
|
||||
**日期**: 2026-06-17
|
||||
**状态**: 设计待审查
|
||||
**范围**: 仅 `gitlink-cl` 项目内
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
让 Claude Code 能在 `gitlink-cl` 项目目录内发现并调用 `skills/` 下的 23 个 gitlink skill。范围**仅限本项目**,不污染全局 `~/.claude/skills/`。
|
||||
|
||||
**成功标准**: 在 `gitlink-cl` 目录开新 Claude Code 会话后,23 个 `gitlink-*` skill 出现在可用 skill 列表,并能通过自然语言触发、执行底层 `gitlink-cli` 命令。
|
||||
|
||||
## 2. 现状评估
|
||||
|
||||
| 项 | 状态 |
|
||||
|---|---|
|
||||
| `gitlink-cli` 命令 | ✅ 全局可用(@gitlink-ai/cli@0.1.18,在 PATH) |
|
||||
| 认证 | ✅ 已登录(`liuyan688`) |
|
||||
| skill 源 | ✅ `skills/` 下 23 个,frontmatter 合规(见 §3) |
|
||||
| Claude Code 发现 | ❌ 无项目级 `.claude/skills/`,全局也未装 → Claude Code 看不见 |
|
||||
|
||||
## 3. Claude Code 兼容性预检(关键)
|
||||
|
||||
基于 Claude Code 官方文档 + frontmatter 实测。
|
||||
|
||||
### 3.1 frontmatter 合规(实测,全过)
|
||||
- 23 个 SKILL.md 均含 `name` + `description`
|
||||
- 目录名与 frontmatter `name` 完全一致(23/23)——Claude Code 以**目录名**作为命令名,这是关键合规点
|
||||
- `description` 长度均 < 1536 字符上限
|
||||
- 非标准字段(`version`、`metadata.requires.bins`、`metadata.cliHelp`):官方文档**未承诺**,但按 Agent Skills 开放标准 + YAML 解析惯例,推断为**静默忽略、不阻塞加载**。注意:Claude Code **不会消费** `metadata.requires.bins`(不自动做依赖检查)——当前 skill 正文直接调 `gitlink-cli`,已满足运行需求。
|
||||
|
||||
### 3.2 加载机制(官方文档明确)
|
||||
- Claude Code 扫描 `<project>/.claude/skills/<name>/SKILL.md`(项目级),与用户级**合并生效**(同名时 personal 覆盖 project)
|
||||
- 启动时扫描 + 运行中 live change detection 双层
|
||||
- **会话启动后才新建顶层 `.claude/skills/` 目录 → 必须重启会话**才能发现
|
||||
|
||||
### 3.3 Junction 穿透(文档未承诺,推断)
|
||||
- junction 读取 SKILL.md(标准文件 I/O):**几乎肯定 OK**
|
||||
- live change detection 的 watch 行为:**不确定**
|
||||
- **结论**:不依赖运行时变更感知,保证启动扫描读到即可;采用逐 skill junction 降低单点风险(见 §4.1)。
|
||||
|
||||
## 4. 设计方案
|
||||
|
||||
### 4.1 逐 skill Junction(核心)
|
||||
`.claude/skills/` 为真实目录,其下每个 skill 子目录是一个 junction,指向项目根 `skills/<同名>`:
|
||||
|
||||
```
|
||||
.claude/skills/gitlink-compliance → skills/gitlink-compliance
|
||||
.claude/skills/gitlink-newcomer-guide → skills/gitlink-newcomer-guide
|
||||
... (共 23 个)
|
||||
```
|
||||
|
||||
**为何逐 skill 而非整个 `.claude/skills` 单 junction**:Claude Code 文档未承诺 junction 的 live-watch 行为;逐 skill junction 使 `.claude/skills/` 本身是真实目录,启动扫描最稳,单点 watch 失效不影响整体(基于 §3.3 推断 + 兼容性优先)。
|
||||
|
||||
### 4.2 .gitignore
|
||||
忽略 `.claude/skills/`(junction 区域,不应入库——junction 指向本地源,他人 clone 后无效)。
|
||||
|
||||
### 4.3 命令桥接
|
||||
复用全局 `gitlink-cli`(已登录)。无需额外桥接。
|
||||
|
||||
## 5. 数据流
|
||||
|
||||
`cd gitlink-cl` → 启动 Claude Code → 扫描 `.claude/skills/*/SKILL.md`(穿透 junction 读源)→ 注册 23 个 skill → 用户自然语言/slash 触发 → AI 按 SKILL.md 调 `gitlink-cli ...`。
|
||||
|
||||
## 6. 验证方案
|
||||
|
||||
实现后,在 `gitlink-cl` 目录开**新** Claude Code 会话(必须新会话,见 §3.2):
|
||||
1. 问 "What skills are available?" / 查 skill 列表 → 确认 23 个 `gitlink-*` 出现
|
||||
2. `/doctor` → 确认无 skill 加载错误、无 description 预算溢出
|
||||
3. 端到端:触发一个只读 skill(如 `gitlink-newcomer-guide` 的 `issue +list` 步骤)→ 确认 `gitlink-cli` 命令链通
|
||||
|
||||
## 7. 错误处理与退路
|
||||
|
||||
| 故障 | 处理 |
|
||||
|---|---|
|
||||
| junction 建立失败(已存在/路径错) | 清理已存在项,重试 |
|
||||
| Claude Code 不识别 junction(/doctor 报错或 skill 不出现) | **退路:真实复制** `skills/*` 到 `.claude/skills/`(牺牲单一来源,换 100% 兼容) |
|
||||
| frontmatter 非标准字段导致加载失败(极小概率) | 移除 `version`/`metadata` 字段或迁入正文 |
|
||||
| skill 不出现 | 确认是新会话(非运行中新建);确认 `.claude/skills/` 真实存在 |
|
||||
|
||||
## 8. 范围外(YAGNI)
|
||||
|
||||
- 全局安装(`~/.claude/skills/`)
|
||||
- 修改 skill 源内容
|
||||
- settings.json 额外配置(除非退路需要)
|
||||
- skill 的 hooks/依赖检查自动化(SKILL.md 正文已含直接调用)
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,361 @@
|
|||
# GitLink Skills 丰富与完善 — 设计规格
|
||||
|
||||
- **日期**：2026-06-15
|
||||
- **分支**：`feat/gitlink-skills-enrichment`
|
||||
- **范围**：子任务二「编写和丰富 GitLink Skills」中标记为"完成"的 2 个技能
|
||||
- **作者**：AI Agent（superpowers brainstorming → writing-plans 流程）
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
`gitlink-cl`（fork `z2_cc/gitlink-cli`，upstream `Gitlink/gitlink-cli`）的 `skills/` 目录已有 23 个技能。本规格聚焦其中 **2 个** 目标技能，将其补齐到与 `gitlink-code-review` / `gitlink-insight` 同等的完整标准（SKILL.md + REFERENCE.md + examples/），并满足任务交付要求：
|
||||
|
||||
> • 许可证合规检查：扫描仓库的许可证合规性和**敏感信息泄露风险**
|
||||
> • 新人引导：为 good-first-issue **自动添加引导评论**，降低新贡献者参与门槛
|
||||
|
||||
### 目标
|
||||
|
||||
1. **`gitlink-compliance`** 补齐"敏感信息泄露风险"扫描能力（当前完全缺失），补 `examples/`，使报告与评分完整。
|
||||
2. **`gitlink-newcomer-guide`** 修复命令正确性 Bug、补 `REFERENCE.md`、加入幂等去重与状态过滤，做成可重复运行的真实写操作技能。
|
||||
3. 两个技能都能在 **Claude Code** 上验证通过（先静态，后真实）。
|
||||
4. 同步更新 `skills/README.md` 概览表。
|
||||
|
||||
### 非目标（YAGNI，本轮不做）
|
||||
|
||||
- 其余 4 个场景技能（code-review / issue-triage / release-auto / project-health）—— 本轮不动。
|
||||
- 新增全新技能（如 contributor-insight / gatekeeper / milestone）。
|
||||
- 重写已有技能的整体结构。
|
||||
- 修改 `gitlink-cli` 本身的 Go 代码 / 增加新子命令（技能层用现有命令 + raw API）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状评估
|
||||
|
||||
### 2.1 `gitlink-compliance`
|
||||
|
||||
| 文件 | 大小 | 现状 |
|
||||
|------|------|------|
|
||||
| `SKILL.md` | 8.4KB | 3 个工作流（完整合规 / 许可证兼容性 / 版权声明）+ 报告模板，**较完整** |
|
||||
| `REFERENCE.md` | 5.7KB | 文件检查 API、许可证识别关键词、兼容性矩阵、检查清单，**较完整** |
|
||||
| `examples/` | — | **缺失** |
|
||||
|
||||
**关键缺口**：任务要求"敏感信息泄露风险"，但当前 SKILL.md **完全没有**密钥/Token/凭据/私钥扫描章节。这是本轮最重要的新增。
|
||||
|
||||
**扫描方式短板**：当前全部依赖 `gitlink-cli api GET /:owner/:repo/raw/<branch>/<path>` 逐文件取内容。对"批量扫描全仓库敏感信息"不现实（仓库动辄数百上千文件，逐个 raw 请求不可行）。需要引入 `git clone` + `git grep` 批量扫描路径。
|
||||
|
||||
### 2.2 `gitlink-newcomer-guide`
|
||||
|
||||
| 文件 | 大小 | 现状 |
|
||||
|------|------|------|
|
||||
| `SKILL.md` | 4.2KB | 工作流 + 3 个评论模板 + 使用示例，**偏薄** |
|
||||
| `examples/newcomer-guide-workflow.md` | 1.8KB | 4 步基础示例 |
|
||||
| `REFERENCE.md` | — | **缺失** |
|
||||
|
||||
**关键缺口（含 1 个正确性 Bug）**：
|
||||
|
||||
1. 🔴 **Bug**：`SKILL.md` 第 27、123 行引用 `gitlink-cli label +list`。实测 `gitlink-cli label --help` → `unknown command "label" for "gitlink-cli"`。**该命令不存在**，照抄会让技能直接报错。`gitlink-cli` 顶层命令只有：`api auth branch ci config issue org pr release repo search user version`。
|
||||
2. ❌ 缺 `REFERENCE.md`（命令/字段/端点详细参考）。
|
||||
3. ⚠️ 备注里说"添加引导评论前先检查是否已有引导评论（避免重复）"，但**没给任何方法**——无幂等机制，重复运行会刷屏。
|
||||
4. ⚠️ `--state open` 过滤**不准确**（官方克隆 `gitlink-onboarding` 已确认：返回列表可能含已关闭 Issue），需按 `status_id` 客户端二次过滤。
|
||||
|
||||
### 2.3 可用的事实依据（来自探索，作为设计地基）
|
||||
|
||||
- `gitlink-cli issue +list` 只支持 `--state/--page/--limit`，**无 `--label` 过滤**。返回 JSON 字段：`project_issues_index`（网页编号）、`subject`、`status_id`（1=新增 / 2=正在解决 / 3=已解决 / 5=关闭 / 0=未知）、`tags[]`（每个含 `name`）、`assigners`、`priority`、`created_at`/`updated_at`。
|
||||
- `gitlink-cli issue +comment -n <number> -b <body>` → `POST /v1/{owner}/{repo}/issues/{number}/journals`（body 映射为 `notes`）。
|
||||
- 列出 Issue 评论（用于去重）：`gitlink-cli api GET /v1/:owner/:repo/issues/:number/journals --format json`（本仓 `skills/gitlink-issue/SKILL.md` 第 63 行已在用此端点）。
|
||||
- good-first-issue 检测**不需要** `label` 命令——`issue +list` 的 `tags[].name` 字段已足够。
|
||||
- `gitlink-cli api <METHOD> <PATH> [--query --body --header]`，认证自动注入，支持任意端点。
|
||||
- 响应统一格式：`{ ok, data, meta:{page,limit,total_count} }` 或 `{ ok:false, error:{code,message,suggestion} }`。
|
||||
- 官方克隆 `skills/gitlink-license-compliance` 已有成熟的"敏感信息扫描"章节（正则特征库 + 风险分级 + git clone 批量扫描），作为权威蓝本参考。
|
||||
- 官方克隆 `skills/gitlink-onboarding` 给出了 Issue JSON 字段与 `status_id` 过滤的精确说明，作为 newcomer-guide 的参考。
|
||||
|
||||
---
|
||||
|
||||
## 3. 设计决策
|
||||
|
||||
### 决策 A — compliance 敏感信息扫描方式：**混合（方案③）**
|
||||
|
||||
- **仓库元信息 / LICENSE / 依赖声明文件 / 指定小文件** → 用 `gitlink-cli api`（小而准，无需 clone，远程可用）。
|
||||
- **批量敏感信息扫描（遍历全仓库文件 + Git 历史）** → 用 `git clone` + `git ls-tree -r --name-only HEAD` + `git grep -nE '<pattern>'` + `git log -p`（现实可行，能扫全）。
|
||||
|
||||
**理由**：敏感信息扫描本质是"对大量文件做正则匹配"，逐文件 `api raw` 不可行；`git grep` 是为此而生的工具，单次调用扫描整个工作树，效率与覆盖率都最佳。元信息类小数据继续用 `api`，避免无谓 clone。
|
||||
|
||||
**被否方案**：
|
||||
- ① 纯 `api raw`：扫不动真实仓库，否。
|
||||
- ② 纯 `git clone`：元信息（如 `repo +info`）用 clone 反而绕远，否。
|
||||
|
||||
### 决策 B — newcomer-guide 去重策略：**标记串 + journal 扫描（方案①）**
|
||||
|
||||
- 每条引导评论末尾埋固定 HTML 注释标记：`<!-- gitlink-newcomer-guide:v1 -->`（在网页上不可见，但 API 能读到）。
|
||||
- 发评论前：`gitlink-cli api GET /v1/:owner/:repo/issues/:number/journals --format json`，扫描已有 journal 的 `notes` 字段是否含该标记。
|
||||
- 命中标记 → 跳过该 Issue（幂等）；未命中 → 发评论。
|
||||
|
||||
**理由**：标记串让"是否已是本技能发的引导评论"判断精确、版本可演进（换标记串即可重发新版引导）。journal 端点已确认存在。
|
||||
|
||||
**被否方案**：仅比较 `comment_journals_count` 前后差值——无法区分"已有引导评论"与"有其他评论"，否。
|
||||
|
||||
---
|
||||
|
||||
## 4. 详细设计 — `gitlink-compliance`
|
||||
|
||||
### 4.1 新增「工作流 4：敏感信息扫描」
|
||||
|
||||
插入到 `SKILL.md` 现有"工作流 3：版权声明批量检查"之后、"Raw API 参考"之前。
|
||||
|
||||
#### 4.1.1 高危文件类型清单（优先扫描）
|
||||
|
||||
```
|
||||
配置文件： .env, .env.local, .env.production, .env.development
|
||||
config.yaml, config.yml, config.json, application.properties
|
||||
settings.py, settings.json, appsettings.json
|
||||
证书/密钥： *.pem, *.key, *.p12, *.pfx, *.crt, *.cer, *.der
|
||||
SSH 密钥： id_rsa, id_dsa, id_ecdsa, id_ed25519
|
||||
数据库配置： database.yml, db.conf, datasource.properties, *.conn
|
||||
CI/部署配置：.travis.yml, .gitlink-ci.yml, .trustie-pipeline.yml,
|
||||
.github/workflows/*.yml, docker-compose.yml, Dockerfile
|
||||
```
|
||||
|
||||
#### 4.1.2 敏感信息正则特征目录
|
||||
|
||||
```
|
||||
AWS Access Key AKIA[0-9A-Z]{16}
|
||||
GitHub Token ghp_[A-Za-z0-9]{36}
|
||||
GitLink Token glpat-[A-Za-z0-9\-_]{20}
|
||||
JWT eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}
|
||||
私钥头 -----BEGIN (RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----
|
||||
通用密钥赋值 (?i)(password|passwd|pwd|secret|token|apikey|api_key|access_key|private_key)\s*[:=]\s*['"]?[^\s'"]{8,}
|
||||
数据库连接串 (mysql|postgres|postgresql|mongodb|redis)://[^:\s]+:[^@\s]+@[^\s]+
|
||||
内网/私有 IP (192\.168\.|10\.\d{1,3}\.|172\.(1[6-9]|2\d|3[01])\.|127\.0\.0\.1)
|
||||
Slack Token xox[baprs]-[A-Za-z0-9-]{10,}
|
||||
```
|
||||
|
||||
#### 4.1.3 四级风险分级
|
||||
|
||||
| 风险等级 | 描述 | 处理建议 |
|
||||
|---------|------|---------|
|
||||
| 🔴 严重 | 真实密钥/Token/私钥暴露在代码中 | 立即撤销密钥；从 Git 历史清除 |
|
||||
| 🟠 高 | 密码 / 数据库连接串硬编码 | 替换为环境变量；清理历史提交 |
|
||||
| 🟡 中 | 内网地址 / 测试账号泄露 | 评估影响范围，按需处理 |
|
||||
| 🟢 低 | 疑似敏感但可能是示例/占位数据 | 人工确认后决定是否处理 |
|
||||
|
||||
#### 4.1.4 混合扫描执行步骤（写进工作流）
|
||||
|
||||
```bash
|
||||
# Step 1：仓库元信息（api，无需 clone）
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# Step 2：LICENSE / 依赖声明文件（api，文件少且明确）
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/LICENSE
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/go.mod # 按主语言选择
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/package.json
|
||||
|
||||
# Step 3：批量敏感信息扫描（需 clone）
|
||||
git clone https://www.gitlink.org.cn/<owner>/<repo>.git /tmp/<repo>-scan
|
||||
cd /tmp/<repo>-scan
|
||||
git ls-tree -r --name-only HEAD # 确定扫描范围
|
||||
|
||||
# Step 4：对高危文件类型 + 全工作树做正则扫描
|
||||
git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD
|
||||
git grep -niE '(password|passwd|pwd|secret|token|apikey|api_key)\s*[:=]' HEAD -- '*.env*' '*.yml' '*.yaml' '*.json' '*.py' '*.conf'
|
||||
git grep -nE '(mysql|postgres|mongodb|redis)://[^:\s]+:[^@\s]+@' HEAD
|
||||
|
||||
# Step 5（可选）：检查 Git 历史中已删除但仍残留的敏感信息
|
||||
git log --all -p -S 'AKIA' -- '*.py' # 按可疑特征搜历史
|
||||
```
|
||||
|
||||
> **降级**：若用户无本地 clone 条件、仓库极小，可仅用 Step 1-2 + 对少量高危文件逐个 `api raw` 扫描，并在报告中注明"未做全量扫描"。
|
||||
|
||||
#### 4.1.5 输出整合
|
||||
|
||||
把"敏感信息扫描结果"作为独立一节并入现有合规报告模板（`SKILL.md` 的"输出格式"小节与 `REFERENCE.md` 的"输出格式规范"都要改）：
|
||||
|
||||
```markdown
|
||||
### 🔴 敏感信息扫描
|
||||
|
||||
| 风险 | 文件 | 行 | 内容特征 | 建议 |
|
||||
|------|------|----|---------|------|
|
||||
| 🟠 高 | config/database.yml | 12 | password: prod_db_pass_123 | 改用环境变量 |
|
||||
```
|
||||
|
||||
评分维度新增「🔒 敏感信息管控」一行（☆☆☆☆☆ / ✅⚠️❌），总分计算纳入。
|
||||
|
||||
### 4.2 新增 `examples/compliance-check-workflow.md`
|
||||
|
||||
端到端可运行示例，结构：
|
||||
|
||||
1. 场景说明（发布前合规自检，目标仓库 `z2_cc/gitlink-cli`）
|
||||
2. 前置条件（已登录、有读权限；批量扫描需可 clone）
|
||||
3. Step 1-6：repo 信息 → LICENSE 识别 → 依赖合规 → 敏感信息扫描 → 版权头采样 → 汇总报告
|
||||
4. 一份**示例报告输出**（含发现的不兼容依赖与一个假密钥命中）
|
||||
5. 命令速览
|
||||
|
||||
> 全程只读 + 可 dry-run（敏感信息扫描的 `git clone`/`git grep` 本身不写远端）。示例中用到的"命中密钥"用明显的假值（如 `AKIAIOSFODNN7EXAMPLE`），避免示例本身触发误报。
|
||||
|
||||
### 4.3 `REFERENCE.md` 增补
|
||||
|
||||
- 新增「敏感信息扫描 API 与命令」小节：高危文件类型清单、正则特征目录、风险分级表、`git grep` / `git log -S` 用法。
|
||||
- 「合规检查清单」表格补一行「敏感信息 | `git grep` 批量扫描 | 无 🔴/🟠 级命中」。
|
||||
- 「输出格式规范」补「敏感信息扫描结果」模板片段。
|
||||
|
||||
### 4.4 `SKILL.md` 其余微调
|
||||
|
||||
- 顶部「工作流概览」表新增一行「敏感信息 | 密钥/Token/凭据/私钥泄露 | 🔴 / 🟠」。
|
||||
- `metadata.requires.bins` 由 `["gitlink-cli"]` 改为 `["gitlink-cli", "git"]`（批量扫描依赖 git；并在文中注明 git 为"批量扫描时必需，基础检查可用 api 替代"）。
|
||||
- 「注意事项」补一条：扫描结果仅供参考，真实密钥需人工复核，勿把误报当噪音忽略。
|
||||
|
||||
---
|
||||
|
||||
## 5. 详细设计 — `gitlink-newcomer-guide`
|
||||
|
||||
### 5.1 修复 `label` 命令 Bug
|
||||
|
||||
删除所有 `gitlink-cli label +list` 引用，替换为：
|
||||
|
||||
- **good-first-issue 检测**：不依赖 label 命令，直接用 `issue +list --format json` 返回的 `tags[].name` 字段筛选（见 5.2）。
|
||||
- **（可选）查看仓库可用标签目录**：`gitlink-cli api GET /v1/:owner/:repo/labels --format json`（raw API；端点在静态验证阶段确认，若 404 则在 REFERENCE 标注"GitLink 无独立 label 列表端点，依赖 issue.tags"）。
|
||||
|
||||
### 5.2 good-first-issue 检测逻辑（写进 SKILL.md 工作流）
|
||||
|
||||
```
|
||||
1. issue +list --state open --format json（必要时翻页 --page 2..，按 meta.total_count）
|
||||
2. 客户端按 status_id 过滤：保留 1（新增）、2（正在解决）；排除 3（已解决）、5（关闭）
|
||||
—— 抵消 --state open 过滤不准确的已知问题
|
||||
3. 按 tags[].name 匹配入门标签（大小写不敏感，正则）：
|
||||
/good.?first.?issue|新手|入门|help.?wanted|easy|beginner|低难度/
|
||||
4. 排除已分配（assigners 非空）的 Issue，除非标签明确是 help wanted
|
||||
5. 对每个候选 issue +view --number <index> --format json，取 description / comment_journals_count
|
||||
```
|
||||
|
||||
标签名变体在 REFERENCE 列全（`good first issue`、`good-first-issue`、`good_first_issue`、`新手任务`、`入门`、`help wanted`、`help-wanted`、`easy`、`beginner`）。
|
||||
|
||||
### 5.3 去重机制（决策 B）
|
||||
|
||||
- 引导评论模板**末尾统一追加**标记：`<!-- gitlink-newcomer-guide:v1 -->`（3 个模板都加）。
|
||||
- 发评论前执行幂等检查：
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /v1/:owner/:repo/issues/<number>/journals --format json
|
||||
# 扫描返回 data[].notes 是否含 "gitlink-newcomer-guide:v1"
|
||||
# 命中 → 跳过（输出"已引导过，跳过 #<number>"）
|
||||
# 未命中 → 执行 issue +comment
|
||||
```
|
||||
|
||||
- 工作流把"去重检查"作为**发评论前的强制步骤**写进流程图与注意事项。
|
||||
|
||||
### 5.4 新建 `REFERENCE.md`
|
||||
|
||||
内容：
|
||||
|
||||
- 依赖命令表（`issue +list/view/comment`、`repo +info`、`api GET .../journals`），每条带 flag 与 API 映射。
|
||||
- Issue JSON 关键字段表（`project_issues_index` / `status_id` 含义 / `tags[].name` / `assigners` / `comment_journals_count`）。
|
||||
- 入门标签名变体表 + 匹配正则。
|
||||
- `status_id` → 状态对照表（1/2/3/5/0）。
|
||||
- 幂等规则：标记串格式、journal 扫描命令、版本演进说明。
|
||||
- 已知坑：`--state open` 不准 → 客户端按 `status_id` 二次过滤；分页 >20 需翻页。
|
||||
|
||||
### 5.5 增强 `examples/newcomer-guide-workflow.md`
|
||||
|
||||
在现有 4 步基础上扩为：
|
||||
|
||||
1. 列 issue（含翻页 + status_id 过滤说明）
|
||||
2. 按 tags 筛 good-first-issue 候选
|
||||
3. **去重检查**（journal 扫描标记串）—— 新增步骤
|
||||
4. 选模板（bug / 功能 / 文档）+ 追加标记串
|
||||
5. 发评论（写操作，先确认）
|
||||
6. 批量场景：对多个候选循环执行 3-5，输出"已引导 N 个 / 跳过 M 个"
|
||||
|
||||
### 5.6 `SKILL.md` 其余微调
|
||||
|
||||
- 「依赖的 Shortcuts」表删除 `label +list` 行，改为 `api GET .../journals`（去重）与 `issue +list/view/comment`。
|
||||
- 工作流程图加入"去重检查"节点。
|
||||
- 「注意事项」补：写操作前确认用户意图；重复运行不会刷屏（幂等）；不要改 good-first-issue 标签。
|
||||
- 顶部加 `**CRITICAL — 所有写操作（issue +comment）执行前必须确认用户意图**`（与 issue 技能一致）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 横切：`skills/README.md` 更新
|
||||
|
||||
当前 README 概览表（核心/辅助 Skills 两张表）**未收录** `gitlink-compliance` 与 `gitlink-newcomer-guide`。补两行：
|
||||
|
||||
| Skill | 说明 | 常用命令 |
|
||||
|-------|------|----------|
|
||||
| **gitlink-compliance** | 许可证 / 依赖合规 / 敏感信息扫描 | `repo +info`, `api GET .../raw`, `git grep` |
|
||||
| **gitlink-newcomer-guide** | 为 good-first-issue 自动添加引导评论 | `issue +list/view/comment`, `api GET .../journals` |
|
||||
|
||||
（放在"辅助 Skills"表，或在"核心"表后新增"合规与社区"小节——实现时择一，倾向新增小节以体现场景价值。）
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证计划（先静态，后真实）
|
||||
|
||||
### 7.1 静态验证（本轮立即做，无需凭据）
|
||||
|
||||
针对**每个**技能文件：
|
||||
|
||||
1. **Frontmatter 合法**：`name` / `version` / `description` / `metadata.requires` 齐全且 YAML 可解析。
|
||||
2. **命令存在性**：技能中每条 `gitlink-cli <cmd> [args]` 的 `<cmd>` 实测存在（逐一 `--help` 校验）。**重点回归**：`gitlink-newcomer-guide` 中不再出现 `label`；`gitlink-compliance` 新增的 `git` 命令在 PATH 中可用。
|
||||
3. **flag 合法性**：example / SKILL 里的 flag（如 `-n/-b/--number/--body/--format/--state/--page/--limit`）与各子命令 `--help` 一致。
|
||||
4. **只读命令实跑**：用真实仓库 `z2_cc/gitlink-cli` 跑通只读链路（`repo +info`、`issue +list`、`api GET .../raw`、`api GET .../journals`），确认 JSON 可解析、字段名与文档一致。
|
||||
5. **写操作 dry-run / 展示**：`issue +comment` 用构造好的 body 仅展示命令、不实际发送（无凭据阶段）；敏感信息扫描的 `git clone` + `git grep` 在本地对 `gitlink-cl` 自身实跑，确认正则能命中示例假密钥。
|
||||
6. **链接与交叉引用**：SKILL.md ↔ REFERENCE.md ↔ examples 的相对链接可达。
|
||||
|
||||
### 7.2 真实验证（用户给凭据 + 测试仓库后做）
|
||||
|
||||
7. **compliance**：在测试仓库植入假密钥（如 `AKIAIOSFODNN7EXAMPLE`、`ghp_`+36 位、`password: real_secret_xxx`），实跑完整扫描，确认 🔴/🟠 级命中并生成报告；再清掉假密钥复跑确认无命中。
|
||||
8. **newcomer-guide**：在测试仓库开一个带 `good first issue` 标签的开放 Issue，实发一条引导评论（确认标记串写入）；**立即复跑**技能，确认第二次识别到标记串、跳过、不重复发。再开一个不带入门标签的 Issue，确认被正确排除。
|
||||
|
||||
### 7.3 Claude Code 平台验证
|
||||
|
||||
- 两个 SKILL.md 的 `description` 能被 Claude Code 正确识别为可触发技能（语义清晰、含触发词）。
|
||||
- 在 Claude Code 中模拟一次"帮我检查这个仓库的合规性 / 给 good-first-issue 加引导"的请求，确认技能被加载、流程可走通（静态部分）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 边界与错误处理
|
||||
|
||||
| 场景 | 处理 |
|
||||
|------|------|
|
||||
| 仓库无 LICENSE | compliance 报 🔴 必须修复，给推荐许可证（按语言/社区惯例） |
|
||||
| 依赖许可证无法确定 | 标"需人工确认"，不计入不兼容数 |
|
||||
| 无本地 clone 条件 | compliance 降级为 api + 高危文件逐个扫，报告注明"未全量扫描" |
|
||||
| `git grep` 命中示例/测试数据 | 标 🟢 低风险，建议加注释说明是示例 |
|
||||
| 仓库无任何入门标签 | newcomer-guide 输出"未发现 good-first-issue，建议维护者先标记"，列出未分配的开放 Issue 供参考 |
|
||||
| Issue 已被认领（assigners 非空） | 跳过，除非标签是 help wanted |
|
||||
| journal GET 端点 404 / 字段不符 | 静态/真实验证阶段确认；若端点不可用，降级为"仅比较 comment_journals_count 是否为 0"并在 REFERENCE 注明 |
|
||||
| 写操作（issue +comment） | 一律先确认用户意图；批量场景逐条或汇总确认 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 文件清单（创建 / 修改）
|
||||
|
||||
### 创建（3 个）
|
||||
- `skills/gitlink-compliance/examples/compliance-check-workflow.md`
|
||||
- `skills/gitlink-newcomer-guide/REFERENCE.md`
|
||||
- （spec 本身，已建）`docs/superpowers/specs/2026-06-15-gitlink-skills-enrichment-design.md`
|
||||
|
||||
### 修改（5 个）
|
||||
- `skills/gitlink-compliance/SKILL.md`（+工作流 4 敏感信息扫描、+报告整合、+requires.git、概览表）
|
||||
- `skills/gitlink-compliance/REFERENCE.md`（+敏感信息章节、+检查清单行、+输出片段）
|
||||
- `skills/gitlink-newcomer-guide/SKILL.md`（修 label Bug、+status_id 过滤、+去重、+标记串、工作流图）
|
||||
- `skills/gitlink-newcomer-guide/examples/newcomer-guide-workflow.md`（+去重步骤、+批量场景）
|
||||
- `skills/README.md`（概览表补 2 行 / 新增小节）
|
||||
|
||||
---
|
||||
|
||||
## 10. 未决项（实现阶段确认）→ 真实验证结果（2026-06-16）
|
||||
|
||||
1. **label 列表端点** `GET /v1/:owner/:repo/labels` —— **实测不可用**（返回 GitLink 首页 HTML，非 JSON）。已在 REFERENCE 标注"无独立端点，标签信息只来自 `issue +list` 的 `tags[]`；`issue +create --label <id>` 的 ID 只能从网页后台获取"。good-first-issue 检测不依赖它。✅ 已闭环。
|
||||
2. **journal GET 返回结构** —— **实测**：响应为 `data.journals[]`（非 `data[]`）；评论 journal 含 `notes`（正文），操作 journal（状态/描述变更）含 `operate_content`、无 `notes`。已在 REFERENCE 修正去重逻辑为"遍历 `data.journals[]`，仅扫描评论 journal 的 `notes`"。✅ 已闭环。
|
||||
|
||||
**真实验证额外发现（已回填文档）：**
|
||||
3. **`issue +list` 确实返回 `tags[]` 字段**（未打标签的仓库为空数组，但字段存在）→ good-first-issue 检测机制成立。✅
|
||||
4. **Windows Git Bash（MSYS）路径坑**：`gitlink-cli api GET /v1/...` 的参数会被 MSYS 转为 Windows 路径（`/v1/...`→`D:/Git/v1/...`），请求落到首页返回 HTML；需 `MSYS_NO_PATHCONV=1` 或改用 PowerShell/cmd。已在两个技能的 REFERENCE 已知坑中标注。⚠️（这是 gitlink-cli 在 Windows/MSYS 下的通用问题，建议作为独立 issue 反馈给上游。）
|
||||
|
||||
**未执行的端到端写验证**（需专用测试仓库）：在真实仓库植入假密钥实跑扫描、发真实引导评论+复跑去重——底层机制（正则经本地 fixture 验证、journals 端点经实测可达）已验证，但完整写流程未在真实仓库跑通。
|
||||
|
||||
---
|
||||
|
||||
## 11. 后续
|
||||
|
||||
本规格经用户审查通过后，调用 `writing-plans` 技能产出分步实现计划（按"compliance → newcomer-guide → README → 静态验证"顺序，每步可独立验收），再进入实现。
|
||||
|
|
@ -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）
|
||||
```
|
||||
|
|
@ -146,6 +138,13 @@ skills/
|
|||
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
|
||||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||||
|
||||
### 合规与社区 Skills
|
||||
|
||||
| Skill | 说明 | 常用命令 |
|
||||
|-------|------|----------|
|
||||
| **gitlink-compliance** | 许可证 / 依赖合规 / 敏感信息扫描 | `repo +info`、`api GET .../raw`、`git grep` |
|
||||
| **gitlink-newcomer-guide** | 为 good-first-issue 自动添加引导评论 | `issue +list/view/comment`、`api GET .../journals` |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用场景
|
||||
|
|
@ -309,8 +308,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)）
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -52,6 +52,56 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
|
||||
---
|
||||
|
||||
## 敏感信息扫描
|
||||
|
||||
### 高危文件类型
|
||||
|
||||
| 类别 | 文件 |
|
||||
|------|------|
|
||||
| 配置文件 | `.env*`、`config.yaml/yml/json`、`settings.py`、`application.properties` |
|
||||
| 证书/密钥 | `*.pem`、`*.key`、`*.p12`、`*.pfx`、`*.crt`、`*.cer` |
|
||||
| SSH 密钥 | `id_rsa`、`id_ed25519`、`id_ecdsa`、`id_dsa` |
|
||||
| 数据库配置 | `database.yml`、`db.conf`、`datasource.properties` |
|
||||
| CI/部署 | `.gitlink-ci.yml`、`.trustie-pipeline.yml`、`.github/workflows/*.yml`、`docker-compose.yml` |
|
||||
|
||||
### 敏感信息特征正则
|
||||
|
||||
| 类型 | 正则 |
|
||||
|------|------|
|
||||
| AWS Access Key | `AKIA[0-9A-Z]{16}` |
|
||||
| GitHub Token | `ghp_[A-Za-z0-9]{36}` |
|
||||
| GitLab/Gitea Token (glpat-) | `glpat-[A-Za-z0-9\-_]{20}` |
|
||||
| JWT | `eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}` |
|
||||
| 私钥头 | `-----BEGIN (RSA \|EC \|DSA \|OPENSSH \|PGP )?PRIVATE KEY-----` |
|
||||
| 通用密钥赋值 | `(?i)(password\|passwd\|pwd\|secret\|token\|apikey\|api_key\|access_key\|private_key)\s*[:=]\s*['"]?[^[:space:]'"]{8,}` |
|
||||
| 数据库连接串 | `(mysql\|postgres\|postgresql\|mongodb\|redis)://[^:[:space:]]+:[^@[:space:]]+@[^[:space:]]+` |
|
||||
| 内网/私有 IP | `(192\.168\.\|10\.\d{1,3}\.\|172\.(1[6-9]\|2\d\|3[01])\.\|127\.0\.0\.1)` |
|
||||
| Slack Token | `xox[baprs]-[A-Za-z0-9-]{10,}` |
|
||||
|
||||
### 扫描命令（git）
|
||||
|
||||
```bash
|
||||
# 克隆后批量扫描工作树
|
||||
git clone https://www.gitlink.org.cn/<owner>/<repo>.git /tmp/<repo>-scan
|
||||
cd /tmp/<repo>-scan
|
||||
git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD
|
||||
git grep -niE '(password|passwd|pwd|secret|token|apikey|api_key)\s*[:=]' HEAD -- '*.env*' '*.yml' '*.yaml' '*.json' '*.py' '*.conf'
|
||||
|
||||
# 历史残留（已删除但仍存在）
|
||||
git log --all -p -S 'AKIA' --oneline | head
|
||||
```
|
||||
|
||||
### 风险分级
|
||||
|
||||
| 等级 | 描述 | 处理建议 |
|
||||
|------|------|---------|
|
||||
| 🔴 严重 | 真实密钥/Token/私钥暴露 | 立即撤销密钥；从 Git 历史清除 |
|
||||
| 🟠 高 | 密码 / 数据库连接串硬编码 | 替换为环境变量；清理历史提交 |
|
||||
| 🟡 中 | 内网地址 / 测试账号泄露 | 评估影响范围，按需处理 |
|
||||
| 🟢 低 | 疑似敏感但可能是示例/占位 | 人工确认后决定是否处理 |
|
||||
|
||||
---
|
||||
|
||||
## 常见许可证识别
|
||||
|
||||
通过读取 LICENSE 文件内容，关键字匹配识别许可证类型：
|
||||
|
|
@ -110,6 +160,7 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
| CI 配置 | 检查 `.trustie-pipeline.yml` / `.github/workflows` 等 | 存在即通过 |
|
||||
| 源文件版权头 | 采样检查源码文件前 5 行 | 50% 以上文件有版权声明 |
|
||||
| 依赖配置文件 | 检查 package.json / go.mod / Cargo.toml 等 | 存在即通过 |
|
||||
| 敏感信息 | `git clone` + `git grep` 批量扫描 | 无 🔴/🟠 级命中 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -135,6 +186,11 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
| # | 建议 | 说明 |
|
||||
|---|------|------|
|
||||
|
||||
### 🔴 敏感信息扫描
|
||||
| 风险 | 文件 | 行 | 内容特征 | 建议 |
|
||||
|------|------|----|---------|------|
|
||||
| 🟠 高 | config/database.yml | 12 | password: prod_db_pass_123 | 改用环境变量 ${DB_PASSWORD} |
|
||||
|
||||
### 📊 合规评分
|
||||
| 维度 | 状态 | 评分 |
|
||||
|------|:----:|:----:|
|
||||
|
|
@ -143,6 +199,7 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
| 📦 依赖合规 | ✅/⚠️/❌ | ☆☆☆☆☆ |
|
||||
| 🔒 安全策略 | ✅/⚠️/❌ | ☆☆☆☆☆ |
|
||||
| 📖 项目文档 | ✅/⚠️/❌ | ☆☆☆☆☆ |
|
||||
| 🔒 敏感信息管控 | ✅/⚠️/❌ | ☆☆☆☆☆ |
|
||||
|
||||
**总体合规评分：<分数>/100**
|
||||
```
|
||||
|
|
@ -158,3 +215,5 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
5. MulanPSL-2.0 是中国广泛使用的开源许可证，在 GitLink 平台上常见
|
||||
6. 版权声明检查为采样性质，100% 覆盖需专业扫描工具
|
||||
7. RAW API 返回的某些文件可能包含完整内容（`replace_content` 字段）
|
||||
8. 敏感信息扫描结果仅供参考，建议发布前用 gitleaks/trufflehog 等专业工具二次确认
|
||||
9. **Windows Git Bash（MSYS）路径坑**：`gitlink-cli api GET /:owner/:repo/raw/...` 等 raw `api` 调用，其 `/...` 参数在 MSYS 下会被自动转换为 Windows 路径（如 `D:/Git/...`），导致请求落到 GitLink 首页返回 HTML 而非文件内容。解决：命令前加 `MSYS_NO_PATHCONV=1`，或改用 PowerShell/cmd 执行。批量扫描走 `git clone` + `git grep` 路径不受此影响。
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ version: 1.0.0
|
|||
description: "开源合规检查：扫描仓库许可证、版权声明、依赖合规性，生成合规报告与修复建议。当用户需要检查项目合规状态、许可证兼容性或准备开源发布时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
bins: ["gitlink-cli", "git"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
|
|
@ -28,6 +28,7 @@ metadata:
|
|||
| 依赖合规 | 第三方依赖许可证兼容性 | 🔴 |
|
||||
| 安全策略 | SECURITY.md、安全披露流程 | 🟡 |
|
||||
| 贡献者协议 | CLA / DCO 要求 | 🔵 |
|
||||
| 敏感信息扫描 | 密钥/Token/凭据/私钥泄露 | 🔴 / 🟠 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -206,6 +207,88 @@ gitlink-cli api GET /:owner/:repo/raw/master/src/main.py
|
|||
|
||||
---
|
||||
|
||||
## 工作流 4：敏感信息扫描
|
||||
|
||||
**场景**：发布前检查仓库是否泄露密钥、Token、密码、私钥等敏感信息。这是合规检查的关键一环——一旦真实凭据进入 Git 历史，撤销和清理成本极高。
|
||||
|
||||
### 扫描策略（混合）
|
||||
|
||||
- **小数据 / 远程无 clone**：用 `gitlink-cli api` 取仓库元信息、LICENSE、依赖声明文件、个别高危文件。
|
||||
- **批量扫描全仓库**：用 `git clone` + `git grep` / `git log -S`。逐文件 `api raw` 对真实仓库不现实，`git grep` 单次扫描整个工作树。
|
||||
|
||||
### 高危文件类型（优先扫描）
|
||||
|
||||
| 类别 | 文件 |
|
||||
|------|------|
|
||||
| 配置文件 | `.env`、`.env.local`、`.env.production`、`config.yaml/yml/json`、`settings.py`、`application.properties` |
|
||||
| 证书/密钥 | `*.pem`、`*.key`、`*.p12`、`*.pfx`、`*.crt`、`*.cer` |
|
||||
| SSH 密钥 | `id_rsa`、`id_ed25519`、`id_ecdsa`、`id_dsa` |
|
||||
| 数据库配置 | `database.yml`、`db.conf`、`datasource.properties` |
|
||||
| CI/部署 | `.gitlink-ci.yml`、`.trustie-pipeline.yml`、`.github/workflows/*.yml`、`docker-compose.yml` |
|
||||
|
||||
### 敏感信息特征（正则）
|
||||
|
||||
| 类型 | 正则 |
|
||||
|------|------|
|
||||
| AWS Access Key | `AKIA[0-9A-Z]{16}` |
|
||||
| GitHub Token | `ghp_[A-Za-z0-9]{36}` |
|
||||
| GitLab/Gitea Token (glpat-) | `glpat-[A-Za-z0-9\-_]{20}` |
|
||||
| JWT | `eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}` |
|
||||
| 私钥头 | `-----BEGIN (RSA \|EC \|DSA \|OPENSSH \|PGP )?PRIVATE KEY-----` |
|
||||
| 通用密钥赋值 | `(?i)(password\|passwd\|pwd\|secret\|token\|apikey\|api_key\|access_key\|private_key)\s*[:=]\s*['"]?[^[:space:]'"]{8,}` |
|
||||
| 数据库连接串 | `(mysql\|postgres\|postgresql\|mongodb\|redis)://[^:[:space:]]+:[^@[:space:]]+@[^[:space:]]+` |
|
||||
| 内网/私有 IP | `(192\.168\.\|10\.\d{1,3}\.\|172\.(1[6-9]\|2\d\|3[01])\.\|127\.0\.0\.1)` |
|
||||
| Slack Token | `xox[baprs]-[A-Za-z0-9-]{10,}` |
|
||||
|
||||
### 风险分级
|
||||
|
||||
| 等级 | 描述 | 处理建议 |
|
||||
|------|------|---------|
|
||||
| 🔴 严重 | 真实密钥/Token/私钥暴露 | 立即撤销密钥；从 Git 历史清除 |
|
||||
| 🟠 高 | 密码 / 数据库连接串硬编码 | 替换为环境变量；清理历史提交 |
|
||||
| 🟡 中 | 内网地址 / 测试账号泄露 | 评估影响范围，按需处理 |
|
||||
| 🟢 低 | 疑似敏感但可能是示例/占位 | 人工确认后决定是否处理 |
|
||||
|
||||
### 执行步骤
|
||||
|
||||
```bash
|
||||
# 1. 仓库元信息（api，无需 clone）
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 2. LICENSE / 依赖声明文件（api，文件少且明确）
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/LICENSE
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/go.mod # 按主语言选择
|
||||
|
||||
# 3. 批量敏感信息扫描（需 clone）
|
||||
git clone https://www.gitlink.org.cn/<owner>/<repo>.git /tmp/<repo>-scan
|
||||
cd /tmp/<repo>-scan
|
||||
git ls-tree -r --name-only HEAD # 确定扫描范围
|
||||
|
||||
# 4. 对高危特征做正则扫描（多模式分别跑，便于归类）
|
||||
git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD
|
||||
git grep -niE '(password|passwd|pwd|secret|token|apikey|api_key)\s*[:=]' HEAD -- '*.env*' '*.yml' '*.yaml' '*.json' '*.py' '*.conf'
|
||||
git grep -nE '(mysql|postgres|mongodb|redis)://[^:[:space:]]+:[^@[:space:]]+@' HEAD
|
||||
|
||||
# 5（可选）：检查 Git 历史中已删除但仍残留的敏感信息
|
||||
git log --all -p -S 'AKIA' --oneline | head
|
||||
```
|
||||
|
||||
> **降级**：若用户无本地 clone 条件、仓库极小，可仅用 Step 1-2 + 对少量高危文件逐个 `api raw` 扫描，并在报告中注明"未做全量扫描"。
|
||||
|
||||
### 输出（并入合规报告）
|
||||
|
||||
在合规报告的"可选优化"之后、"合规评分"之前，新增一节：
|
||||
|
||||
```markdown
|
||||
### 🔴 敏感信息扫描
|
||||
|
||||
| 风险 | 文件 | 行 | 内容特征 | 建议 |
|
||||
|------|------|----|---------|------|
|
||||
| 🟠 高 | config/database.yml | 12 | password: prod_db_pass_123 | 改用环境变量 ${DB_PASSWORD} |
|
||||
```
|
||||
|
||||
并在"合规评分"维度表新增一行 `| 🔒 敏感信息管控 | ✅ / ⚠️ / ❌ | ☆☆☆☆☆ |`，纳入总分计算。
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
```bash
|
||||
|
|
@ -229,3 +312,4 @@ gitlink-cli api GET /:owner/:repo/contributors --format json
|
|||
- 不同语言的依赖管理文件格式不同，需要根据项目主语言选择对应的依赖文件分析
|
||||
- 版权声明检查是采样性的，100% 覆盖需要运行专门的扫描工具
|
||||
- MulanPSL-2（木兰许可证）是 GitLink 平台上常用的许可证，需注意其与 GPL 的兼容性
|
||||
- 敏感信息扫描结果仅供参考，真实密钥需人工复核；正则可能漏报或误报，发布前建议结合 gitleaks/trufflehog 等专业工具二次确认
|
||||
|
|
|
|||
|
|
@ -0,0 +1,112 @@
|
|||
# 开源合规检查完整工作流示例
|
||||
|
||||
**场景**：`z2_cc/gitlink-cli` 准备发版前，做一次完整合规自检（许可证 + 依赖 + 敏感信息 + 版权头），产出结构化报告。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `gitlink-cli` 已安装并登录（`gitlink-cli auth status` 正常）
|
||||
- 对目标仓库有读权限
|
||||
- 批量敏感信息扫描需要本地可 `git clone`（无 clone 条件时见"降级"）
|
||||
|
||||
## Step 1：仓库元信息
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner z2_cc --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
提取：`full_name`、`default_branch`、`license`（若平台返回）、`private`。
|
||||
|
||||
## Step 2：LICENSE 识别
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /z2_cc/gitlink-cli/raw/master/LICENSE
|
||||
```
|
||||
|
||||
按 LICENSE 关键词识别类型（MIT / Apache-2.0 / MulanPSL-2 等）。
|
||||
|
||||
## Step 3：依赖合规分析
|
||||
|
||||
```bash
|
||||
# Go 项目
|
||||
gitlink-cli api GET /z2_cc/gitlink-cli/raw/master/go.mod
|
||||
```
|
||||
|
||||
逐依赖判断许可证，对照兼容性矩阵评估与项目主许可证的兼容性。
|
||||
|
||||
## Step 4：敏感信息扫描（批量）
|
||||
|
||||
```bash
|
||||
git clone https://www.gitlink.org.cn/z2_cc/gitlink-cli.git /tmp/gitlink-cli-scan
|
||||
cd /tmp/gitlink-cli-scan
|
||||
|
||||
# 高危凭据特征
|
||||
git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD
|
||||
|
||||
# 配置文件中的硬编码密钥
|
||||
git grep -niE '(password|passwd|pwd|secret|token|apikey|api_key)\s*[:=]' HEAD -- '*.env*' '*.yml' '*.yaml' '*.json' '*.conf'
|
||||
|
||||
# 数据库连接串
|
||||
git grep -nE '(mysql|postgres|mongodb|redis)://[^:[:space:]]+:[^@[:space:]]+@' HEAD
|
||||
|
||||
# 历史残留
|
||||
git log --all -p -S 'AKIA' --oneline | head
|
||||
```
|
||||
|
||||
> **降级**：无 clone 条件时，仅对少量高危文件逐个取内容扫描：
|
||||
> `gitlink-cli api GET /z2_cc/gitlink-cli/raw/master/.env` 等，并在报告注明"未做全量扫描"。
|
||||
|
||||
## Step 5：版权声明采样
|
||||
|
||||
```bash
|
||||
git ls-tree --name-only HEAD | head
|
||||
git show HEAD:cmd/auth/login.go | head -5 # 采样源文件头部
|
||||
```
|
||||
|
||||
## Step 6：汇总报告（示例输出）
|
||||
|
||||
```markdown
|
||||
## ⚖️ 合规检查报告 — z2_cc/gitlink-cli
|
||||
|
||||
📅 检查时间：2026-06-15
|
||||
📋 项目许可证：MIT
|
||||
|
||||
### 🔴 必须修复
|
||||
| # | 问题 | 文件 | 建议 |
|
||||
|---|------|------|------|
|
||||
|
||||
### 🟡 建议修复
|
||||
| # | 问题 | 文件 | 建议 |
|
||||
|---|------|------|------|
|
||||
| 1 | 缺少 SECURITY.md | — | 添加安全披露流程 |
|
||||
|
||||
### 🔴 敏感信息扫描
|
||||
| 风险 | 文件 | 行 | 内容特征 | 建议 |
|
||||
|------|------|----|---------|------|
|
||||
| 🟢 低 | examples/demo.go | 45 | token: "example_token_for_demo" | 加注释说明是示例 |
|
||||
|
||||
### 📊 合规评分
|
||||
| 维度 | 状态 | 评分 |
|
||||
|------|:----:|:----:|
|
||||
| 📜 许可证 | ✅ | ★★★★★ |
|
||||
| 🏷️ 版权声明 | ⚠️ | ★★★☆☆ |
|
||||
| 📦 依赖合规 | ✅ | ★★★★★ |
|
||||
| 🔒 安全策略 | ⚠️ | ★★★☆☆ |
|
||||
| 🔒 敏感信息管控 | ✅ | ★★★★☆ |
|
||||
|
||||
**总体合规评分：82/100**
|
||||
```
|
||||
|
||||
## 命令速览
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/LICENSE
|
||||
gitlink-cli api GET /:owner/:repo/raw/master/go.mod
|
||||
git clone https://www.gitlink.org.cn/<owner>/<repo>.git /tmp/<repo>-scan
|
||||
git grep -nE 'AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9\-_]{20}|-----BEGIN .*PRIVATE KEY-----' HEAD
|
||||
```
|
||||
|
||||
## 注意
|
||||
|
||||
- 全程只读，不修改远端仓库
|
||||
- 示例报告中出现的 `example_token_for_demo` 为占位假值；扫描命令中的 `AKIA[0-9A-Z]{16}` 等是正则模式而非真实凭据——均勿当作真实泄露
|
||||
|
|
@ -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` / 关闭清理），不在帮助中心仓留痕。
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: gitlink-issue-triage
|
||||
version: 2.0.0
|
||||
description: "Issue 自动分拣：根据 Issue 内容自动分类、打标签、分配责任人、添加引导评论。包含关键词权重分析和紧急度评估。"
|
||||
version: 1.0.0
|
||||
description: "Issue 自动分拣：根据 Issue 内容自动分类、打标签、分配责任人、添加引导评论。当用户需要自动处理新提交的 Issue 时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
|
|
@ -15,133 +15,73 @@ metadata:
|
|||
|
||||
## 说明
|
||||
|
||||
本 Skill 实现 Issue 的自动化分拣，不仅仅是打标签，还包括**权重分析**和**紧急度评估**。
|
||||
本 Skill 组合多个 gitlink-cli 命令，实现 Issue 的自动化分类和处理流程：
|
||||
|
||||
## 分析流程
|
||||
1. 获取新提交的 Issue 列表
|
||||
2. 根据 Issue 内容（标题 + 描述）自动判断类别
|
||||
3. 为 Issue 打上对应标签、分配责任人
|
||||
4. 添加引导评论
|
||||
|
||||
## 依赖的 Shortcuts
|
||||
|
||||
| Shortcut | 用途 |
|
||||
|----------|------|
|
||||
| `issue +list` | 获取待处理的 Issue 列表 |
|
||||
| `issue +view` | 查看 Issue 详细内容 |
|
||||
| `issue +update` | 修改 Issue 状态/标签 |
|
||||
| `issue +comment` | 添加评论 |
|
||||
| `label +list` | 查看可用标签 |
|
||||
| `user +info` | 查询用户信息 |
|
||||
|
||||
## 处理流程
|
||||
|
||||
```
|
||||
1. issue +list --state open → 获取所有待处理的 Issue
|
||||
2. issue +view --number {id} → 逐条查看详情
|
||||
3. 关键词权重分析 → 判断分类和紧急度
|
||||
4. label +list → 查看可用标签
|
||||
5. issue +update → 打标签、分配
|
||||
6. issue +comment → 添加引导评论
|
||||
1. issue +list --state open → 获取所有打开的 Issue
|
||||
2. issue +view --number {id} → 查看 Issue 详情
|
||||
3. 分析 subject + description → 判断 Issue 类别
|
||||
4. label +list → 查看可用标签
|
||||
5. issue +update --label {label} → 打标签
|
||||
6. issue +comment --body "..." → 添加引导评论
|
||||
```
|
||||
|
||||
## 关键词权重分类系统
|
||||
## 分类规则参考
|
||||
|
||||
不再简单匹配关键词，而是引入**权重评分**：
|
||||
| 类别 | 标题关键词 | 建议标签 | 建议负责人 |
|
||||
|------|-----------|---------|-----------|
|
||||
| Bug | 错误、失败、异常、bug、crash、报错 | bug | 项目维护者 |
|
||||
| 功能需求 | 建议、希望、需要、feature、支持 | enhancement | PM |
|
||||
| 文档 | 文档、README、文档缺失、拼写 | documentation | 文档负责人 |
|
||||
| 问题咨询 | 请问、怎么、如何、help、question | question | 社区支持 |
|
||||
| 性能 | 慢、卡顿、性能、优化、performance | performance | 核心开发者 |
|
||||
|
||||
| 类别 | 关键词 | 权重分 | 建议标签 |
|
||||
|------|--------|--------|---------|
|
||||
| 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 |
|
||||
|
||||
**评分方式：** 将 Issue 标题和描述分词后，匹配上表关键词，按权重累加。得分最高的类别即为分类结果。
|
||||
|
||||
## 紧急度评估
|
||||
|
||||
```
|
||||
紧急度 = Bug权重分 × 1.5 + 安全权重分 × 2.0 + 其他权重分 × 1.0
|
||||
|
||||
判定标准：
|
||||
- ≥20 → 🔴 P0 紧急：立即处理
|
||||
- 12-19 → 🟡 P1 高优先：尽快处理
|
||||
- 6-11 → 🟢 P2 普通：正常排期
|
||||
- <6 → 🔵 P3 低优先：后续处理
|
||||
```
|
||||
|
||||
## 分配责任人规则
|
||||
|
||||
```
|
||||
根据 Issue 类型分配责任人：
|
||||
- Bug → 分配最近修改相关文件的人（通过 git blame）
|
||||
- 功能需求 → 分配 PM 或项目维护者
|
||||
- 文档 → 分配文档负责人
|
||||
- 安全 → 直接通知项目管理员
|
||||
- 问题咨询 → 分配社区支持
|
||||
```
|
||||
|
||||
## 完整处理示例
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 1. 获取待处理 Issue
|
||||
# 1. 获取所有打开的 Issue
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state open --format json
|
||||
```
|
||||
|
||||
**输出分析：**
|
||||
```json
|
||||
{
|
||||
"issues": [
|
||||
{"number": 42, "subject": "登录页面报错：500 Internal Server Error"},
|
||||
{"number": 43, "subject": "建议增加导出功能"},
|
||||
{"number": 44, "subject": "README 中缺少安装说明"}
|
||||
]
|
||||
}
|
||||
```
|
||||
# 2. 查看某个 Issue 的详细内容
|
||||
gitlink-cli issue +view --owner myuser --repo myrepo --number 5 --format json
|
||||
|
||||
**AI 分析结果：**
|
||||
```
|
||||
Issue #42: 关键词匹配 → "报错"(5) + "500"(0) = 5分 → Bug
|
||||
紧急度评分 → 5 × 1.5 = 7.5 → 🟡 P2 普通
|
||||
建议标签: bug
|
||||
# 3. 查看仓库可用标签
|
||||
gitlink-cli label +list --owner myuser --repo myrepo
|
||||
|
||||
Issue #43: 关键词匹配 → "建议"(8) + "增加"(5) = 13分 → 功能需求
|
||||
紧急度评分 → 13 × 1.0 = 13 → 🟡 P1 高优先
|
||||
建议标签: enhancement
|
||||
# 4. 为 Issue 打标签（假设判断为 bug）
|
||||
gitlink-cli issue +update --owner myuser --repo myrepo --number 5 --state open
|
||||
|
||||
Issue #44: 关键词匹配 → "文档"(10) + "缺少"(4) = 14分 → 文档
|
||||
紧急度评分 → 14 × 1.0 = 14 → 🟡 P1 高优先
|
||||
建议标签: documentation
|
||||
```
|
||||
# 5. 添加分类引导评论
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 5 --body "感谢提交 Issue！已自动分类为 **Bug**，请补充以下信息：
|
||||
|
||||
```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。"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 3. 为功能需求 Issue 添加评论
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 43 --body "## Issue 自动分类结果
|
||||
|
||||
**类别：** ✨ 功能需求
|
||||
**紧急度：** 🟡 P1 高优先
|
||||
**建议标签：** enhancement
|
||||
|
||||
### 分类依据
|
||||
标题中包含关键词「建议」「增加」，匹配功能需求分类。
|
||||
|
||||
### 请补充以下信息
|
||||
1. 这个功能解决了什么场景的问题？
|
||||
2. 期望的行为是什么？
|
||||
3. 是否有参考实现？
|
||||
|
||||
感谢你的建议！项目组会评估这个需求的可行性。"
|
||||
项目维护者会尽快处理。"
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 使用**权重评分**代替简单的关键词匹配，减少误分类。
|
||||
- 每次评论前检查 Issue 是否已有相同内容的评论，避免重复。
|
||||
- 每次操作前先列出当前待处理的 Issue，评估数量。
|
||||
- 添加评论前先确认 Issue 内容，避免误分类。
|
||||
- 标签名称需要先在项目中确认是否存在，不存在则跳过。
|
||||
- 分配责任人前需确认该用户是否为项目成员。
|
||||
- 安全类 Issue（漏洞、权限）应直接通知管理员，不在评论中公开细节。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
# gitlink-newcomer-guide API 参考
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证与全局参数。
|
||||
|
||||
## 命令参考
|
||||
|
||||
### issue +list
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
```
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--state, -s` | 否 | `open`/`closed`/`all`（默认 `open`；**过滤不准确，需客户端二次过滤**） |
|
||||
| `--page, -p` | 否 | 页码（默认 1；总数 >20 需翻页） |
|
||||
| `--limit, -l` | 否 | 每页数量（默认 20） |
|
||||
| `--format` | 否 | `json`/`table`/`yaml` |
|
||||
|
||||
API：`GET /v1/{owner}/{repo}/issues?state=&page=&limit=`
|
||||
|
||||
### issue +view
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner <owner> --repo <repo> --number <index> --format json
|
||||
```
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--number, -n` | **是** | Issue 网页编号（`project_issues_index`） |
|
||||
|
||||
API：`GET /v1/{owner}/{repo}/issues/{number}`
|
||||
|
||||
### issue +comment（写操作）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +comment --owner <owner> --repo <repo> --number <index> --body "..."
|
||||
```
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--number, -n` | **是** | Issue 网页编号 |
|
||||
| `--body, -b` | **是** | 评论内容（映射为 v1 字段 `notes`） |
|
||||
|
||||
API：`POST /v1/{owner}/{repo}/issues/{number}/journals`，Body `{"notes": body}`
|
||||
|
||||
> [!CAUTION] 写操作——执行前确认用户意图。
|
||||
|
||||
### 读取已有评论（用于去重）
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /v1/:owner/:repo/issues/<number>/journals --query 'page=1&limit=50' --format json
|
||||
```
|
||||
|
||||
返回 `data.journals[]`（**注意是 `data.journals[]`，不是 `data[]`**）。每条 journal 分两类：
|
||||
|
||||
| journal 类型 | 特征字段 | 文本字段 |
|
||||
|------|------|------|
|
||||
| 评论 journal（用户评论） | 含 `notes`、`attachments`、`children_journals`、`comments_count` | `notes`（评论正文） |
|
||||
| 操作 journal（状态/描述变更） | 含 `operate_category`、`operate_content`，**无 `notes`** | `operate_content`（操作描述） |
|
||||
|
||||
**去重**：遍历 `data.journals[]`，仅对含 `notes` 字段的评论 journal，检查其 `notes` 是否含标记串 `gitlink-newcomer-guide:v1`（操作 journal 无 `notes`，自然跳过）。
|
||||
|
||||
## Issue JSON 关键字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `project_issues_index` | Issue 网页编号（用于 `--number`） |
|
||||
| `subject` | 标题 |
|
||||
| `status_id` | 状态：1=新增、2=正在解决、3=已解决、5=关闭、0=未知 |
|
||||
| `tags[]` | 标签数组，每个元素含 `name` |
|
||||
| `assigners` | 负责人列表（空=未认领） |
|
||||
| `priority` | 优先级（null 或 `{name}`） |
|
||||
| `comment_journals_count` | 评论数（`+view` 返回） |
|
||||
| `created_at`/`updated_at` | 时间 |
|
||||
|
||||
## 入门标签名变体
|
||||
|
||||
`tags[].name` 匹配以下任一（大小写不敏感）即视为入门 Issue：
|
||||
|
||||
| 变体 |
|
||||
|------|
|
||||
| `good first issue` / `good-first-issue` / `good_first_issue` |
|
||||
| `新手` / `新手任务` / `入门` |
|
||||
| `help wanted` / `help-wanted` |
|
||||
| `easy` / `beginner` / `低难度` |
|
||||
|
||||
匹配正则：`/good.?first.?issue|新手|入门|help.?wanted|easy|beginner|低难度/i`
|
||||
|
||||
## status_id 状态对照
|
||||
|
||||
| status_id | 含义 | 处理 |
|
||||
|-----------|------|------|
|
||||
| 1 | 新增 | ✅ 纳入候选 |
|
||||
| 2 | 正在解决 | ✅ 纳入候选 |
|
||||
| 3 | 已解决 | ❌ 排除 |
|
||||
| 5 | 关闭 | ❌ 排除 |
|
||||
| 0 | 未知 | ⚠️ 可纳入但标注"状态未知" |
|
||||
|
||||
## 幂等去重规则
|
||||
|
||||
- **标记串**：`<!-- gitlink-newcomer-guide:v1 -->`，追加在每条引导评论末尾（网页不可见，API 可读）。
|
||||
- **发评论前**：`api GET /v1/:owner/:repo/issues/<number>/journals`，遍历 `data.journals[]` 扫描评论 journal 的 `notes` 是否含标记串（操作 journal 无 `notes`，自动跳过）。
|
||||
- 命中 → 跳过；未命中 → 发评论。
|
||||
- **版本演进**：更新引导文案时把标记串改为 `v2`，即可对老 Issue 重发新版引导。
|
||||
|
||||
## 已知坑
|
||||
|
||||
- `issue +list --state open` 过滤不准确，返回可能含已关闭 Issue → 客户端按 `status_id` 二次过滤。
|
||||
- 总数 >20 需 `--page 2..` 翻页（看 `meta.total_count`）。
|
||||
- `gitlink-cli` 无 `label` 子命令；标签信息只来自 `issue +list` 的 `tags[]`。**经实测 `GET /v1/:owner/:repo/labels` 端点不存在**（返回 GitLink 首页 HTML），无法通过 API 列出仓库标签或获取标签 ID；若需在 `issue +create --label <id>` 中指定标签，标签 ID 只能从 GitLink 网页后台获取。
|
||||
- **Windows Git Bash（MSYS）路径坑**：`gitlink-cli api GET /v1/...` 的 `/v1/...` 参数会被 MSYS 自动转换为 Windows 路径（如 `D:/Git/v1/...`），导致请求落到首页返回 HTML。解决：命令前加 `MSYS_NO_PATHCONV=1`，或改用 PowerShell/cmd 执行 raw `api` 调用。
|
||||
|
||||
## References
|
||||
|
||||
- [gitlink-newcomer-guide SKILL](SKILL.md)
|
||||
- [gitlink-shared](../gitlink-shared/SKILL.md)
|
||||
|
|
@ -12,6 +12,7 @@ metadata:
|
|||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — `issue +comment` 是写操作，执行前必须确认用户意图；重复运行通过标记串幂等去重，不会刷屏。**
|
||||
|
||||
## 说明
|
||||
|
||||
|
|
@ -19,23 +20,29 @@ metadata:
|
|||
|
||||
## 依赖的 Shortcuts
|
||||
|
||||
| Shortcut | 用途 |
|
||||
| Shortcut / 命令 | 用途 |
|
||||
|----------|------|
|
||||
| `issue +list` | 获取标记了 good-first-issue 的 Issue |
|
||||
| `issue +list` | 列出 Issue（用返回的 `tags[].name` 检测 good-first-issue） |
|
||||
| `issue +view` | 查看 Issue 详细内容 |
|
||||
| `issue +comment` | 添加引导评论 |
|
||||
| `label +list` | 查看可用标签 |
|
||||
| `issue +comment` | 添加引导评论（写操作，先确认） |
|
||||
| `api GET .../issues/:number/journals` | 读取已有评论，做幂等去重 |
|
||||
| `repo +info` | 获取仓库基本信息 |
|
||||
|
||||
> 说明：`gitlink-cli` 没有 `label` 子命令（实测 `unknown command "label"`）。good-first-issue 直接从 `issue +list` 的 `tags[].name` 字段判断，无需单独列标签。
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
1. issue +list → 获取所有打开的 Issue
|
||||
2. 筛选含 good-first-issue 标签的 Issue
|
||||
3. issue +view --number {id} → 查看 Issue 详情
|
||||
4. 分析 Issue 内容 → 判断适合的引导信息
|
||||
5. issue +comment --body "..." → 添加引导评论
|
||||
6. 可选：issue +update → 分配 mentor
|
||||
1. repo +info → 确认 owner/repo、默认分支
|
||||
2. issue +list --state open --format json（必要时 --page 2.. 翻页）
|
||||
3. 客户端按 status_id 过滤：保留 1（新增）、2（正在解决）；排除 3（已解决）、5（关闭）
|
||||
—— 抵消 --state open 过滤不准确的已知问题
|
||||
4. 按 tags[].name 匹配入门标签（/good.?first.?issue|新手|入门|help.?wanted|easy|beginner|低难度/i）
|
||||
5. 排除已分配（assigners 非空）的 Issue，除非标签是 help wanted
|
||||
6. issue +view --number <index> → 取 description / comment_journals_count 判断 Issue 类型
|
||||
7. 【去重】api GET /v1/:owner/:repo/issues/<index>/journals --format json
|
||||
→ 扫描已有评论是否含标记串 `gitlink-newcomer-guide:v1`，命中则跳过
|
||||
8. issue +comment --number <index> --body "<模板 + 标记串>" → 写操作，先确认用户意图
|
||||
```
|
||||
|
||||
## 引导评论模板
|
||||
|
|
@ -62,6 +69,8 @@ metadata:
|
|||
- 在开发过程中遇到任何问题，也欢迎随时提问
|
||||
|
||||
祝你编码愉快！
|
||||
|
||||
<!-- gitlink-newcomer-guide:v1 -->
|
||||
```
|
||||
|
||||
### 功能需求类 Issue
|
||||
|
|
@ -85,6 +94,8 @@ metadata:
|
|||
4. 提交 Pull Request，描述你的改动
|
||||
|
||||
如有任何问题，随时留言！
|
||||
|
||||
<!-- gitlink-newcomer-guide:v1 -->
|
||||
```
|
||||
|
||||
### 文档类 Issue
|
||||
|
|
@ -108,25 +119,29 @@ metadata:
|
|||
- 代码块请标注语言类型
|
||||
|
||||
期待你的贡献！
|
||||
|
||||
<!-- gitlink-newcomer-guide:v1 -->
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
```bash
|
||||
# 1. 查找所有标记了 good-first-issue 的 Issue
|
||||
# 1. 列出开放 Issue（用返回的 tags[].name 检测 good-first-issue）
|
||||
gitlink-cli issue +list --owner myuser --repo myrepo --state open --format json
|
||||
|
||||
# 2. 查看某个 Issue 的详细内容（判断类型）
|
||||
# 2. 客户端过滤：status_id ∈ {1,2} 且 tags[].name 匹配 good-first-issue，且 assigners 为空
|
||||
|
||||
# 3. 查看 Issue 详情，判断类型
|
||||
gitlink-cli issue +view --owner myuser --repo myrepo --number 10 --format json
|
||||
|
||||
# 3. 查看仓库可用标签
|
||||
gitlink-cli label +list --owner myuser --repo myrepo
|
||||
# 4. 【去重】读取已有评论，检查是否含标记串
|
||||
gitlink-cli api GET /v1/myuser/myrepo/issues/10/journals --format json
|
||||
|
||||
# 4. 添加引导评论
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 10 --body "你好！欢迎参与贡献..."
|
||||
# 5. 添加引导评论（写操作，先确认；评论末尾含 <!-- gitlink-newcomer-guide:v1 -->）
|
||||
gitlink-cli issue +comment --owner myuser --repo myrepo --number 10 --body "你好！欢迎参与贡献 🎉
|
||||
...（正文）...
|
||||
|
||||
# 5. 可选：将 Issue 标记为已分配
|
||||
gitlink-cli issue +update --owner myuser --repo myrepo --number 10
|
||||
<!-- gitlink-newcomer-guide:v1 -->"
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
|
@ -135,3 +150,5 @@ gitlink-cli issue +update --owner myuser --repo myrepo --number 10
|
|||
- 如果 Issue 已经被 Assignee 认领，不需要再添加引导评论。
|
||||
- 不要修改 good-first-issue 标签，由项目维护者管理。
|
||||
- 引导评论建议使用温和、鼓励的语气。
|
||||
- good-first-issue 检测依赖 `issue +list` 返回的 `tags[].name`；`gitlink-cli` 无 `label` 子命令，不要尝试调用任何形如 `gitlink-cli` + `label` 的写法
|
||||
- `--state open` 过滤不准确，必须客户端按 `status_id`（保留 1、2）二次过滤
|
||||
|
|
|
|||
|
|
@ -28,7 +28,17 @@ gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 10 --format js
|
|||
- 是否是文档改进？→ 使用文档模板
|
||||
- 是否是功能需求？→ 使用功能模板
|
||||
|
||||
### Step 3：添加引导评论
|
||||
### Step 3：去重检查（幂等）
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET /v1/z2_cc/gitlink-cli/issues/10/journals --format json
|
||||
```
|
||||
|
||||
扫描返回的 `data.journals[]`（仅评论 journal 有 `notes`，操作 journal 无 `notes` 自动跳过）的 `notes` 是否含标记串 `gitlink-newcomer-guide:v1`：
|
||||
- **命中** → 跳过该 Issue（输出"已引导过 #10，跳过"）
|
||||
- **未命中** → 继续 Step 4
|
||||
|
||||
### Step 4：添加引导评论
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 10 --body "你好！欢迎参与贡献 🎉
|
||||
|
|
@ -44,10 +54,12 @@ gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 10 --body "
|
|||
- 如果对问题描述有疑问，可以在下方留言
|
||||
- 开发过程中遇到任何问题，也欢迎随时提问
|
||||
|
||||
祝你编码愉快！"
|
||||
祝你编码愉快！
|
||||
|
||||
<!-- gitlink-newcomer-guide:v1 -->"
|
||||
```
|
||||
|
||||
### Step 4：确认引导已生效
|
||||
### Step 5：确认引导已生效
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 10 --format json
|
||||
|
|
@ -69,3 +81,24 @@ gitlink-cli issue +view --number <id>
|
|||
# 3. 添加引导评论
|
||||
gitlink-cli issue +comment --number <id> --body "<引导内容>"
|
||||
```
|
||||
|
||||
## 批量场景
|
||||
|
||||
对多个 good-first-issue 循环执行：
|
||||
|
||||
```bash
|
||||
# 伪流程
|
||||
for index in <候选 issue 编号列表>; do
|
||||
# 去重检查
|
||||
already=$(gitlink-cli api GET /v1/<owner>/<repo>/issues/$index/journals --format json | grep -c "gitlink-newcomer-guide:v1")
|
||||
if [ "$already" -gt 0 ]; then
|
||||
echo "已引导过 #$index，跳过"; continue
|
||||
fi
|
||||
# 按类型选模板 + 标记串，发评论（写操作，建议先汇总再批量确认）
|
||||
gitlink-cli issue +comment --owner <owner> --repo <repo> --number $index --body "<模板>
|
||||
|
||||
<!-- gitlink-newcomer-guide:v1 -->"
|
||||
done
|
||||
```
|
||||
|
||||
输出汇总：`已引导 N 个 / 跳过 M 个`。
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
```
|
||||
Loading…
Reference in New Issue