docs(demo): 演示页新增许可证合规检查与新人引导交互流程

- panel-compliance: 仓库元信息 / LICENSE 识别 / 依赖合规 / 敏感信息扫描(git grep) / 合规报告 - panel-newcomer: 查找 good-first-issue / 类型判定 / 幂等去重 / 添加引导评论 - Skills 结构总览补 compliance 卡片与文件清单
docs(plans): 项目级 Skill 集成实现计划
2026-06-24 10:34:11 +08:00 · 2026-06-17 08:59:59 +08:00 · 2026-06-17 08:57:53 +08:00 · 2026-06-16 08:02:49 +08:00 · 2026-06-15 21:07:08 +08:00 · 2026-06-15 20:58:17 +08:00
12 changed files with 2857 additions and 22 deletions
--- a/demo.html
+++ b/demo.html
@ -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>点击按钮查看命令执行结果 &mdash; 展示 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>
+          &lt;!-- gitlink-newcomer-guide:v1 --&gt;
+        </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>
--- a/doc/plans/2026-06-17-project-local-skills.md
+++ b/doc/plans/2026-06-17-project-local-skills.md
@ -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 名——跨任务一致。✅
--- a/doc/specs/2026-06-17-project-local-skills-design.md
+++ b/doc/specs/2026-06-17-project-local-skills-design.md
@ -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 正文已含直接调用)
--- a/docs/superpowers/plans/2026-06-15-gitlink-skills-enrichment.md
+++ b/docs/superpowers/plans/2026-06-15-gitlink-skills-enrichment.md
--- a/docs/superpowers/specs/2026-06-15-gitlink-skills-enrichment-design.md
+++ b/docs/superpowers/specs/2026-06-15-gitlink-skills-enrichment-design.md
@ -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 → 静态验证"顺序，每步可独立验收），再进入实现。
--- a/skills/README.md
+++ b/skills/README.md
@ -138,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` |
+
 ---

 ## 🎯 使用场景
--- a/skills/gitlink-compliance/REFERENCE.md
+++ b/skills/gitlink-compliance/REFERENCE.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` 路径不受此影响。
--- a/skills/gitlink-compliance/SKILL.md
+++ b/skills/gitlink-compliance/SKILL.md
@ -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 等专业工具二次确认
--- a/skills/gitlink-compliance/examples/compliance-check-workflow.md
+++ b/skills/gitlink-compliance/examples/compliance-check-workflow.md
@ -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}` 等是正则模式而非真实凭据——均勿当作真实泄露
--- a/skills/gitlink-newcomer-guide/REFERENCE.md
+++ b/skills/gitlink-newcomer-guide/REFERENCE.md
@ -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)
--- a/skills/gitlink-newcomer-guide/SKILL.md
+++ b/skills/gitlink-newcomer-guide/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）二次过滤
--- a/skills/gitlink-newcomer-guide/examples/newcomer-guide-workflow.md
+++ b/skills/gitlink-newcomer-guide/examples/newcomer-guide-workflow.md
@ -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 个`。
Author	SHA1	Message	Date
刘焱	e7cdf8fc26	docs(demo): 演示页新增许可证合规检查与新人引导交互流程 - panel-compliance: 仓库元信息 / LICENSE 识别 / 依赖合规 / 敏感信息扫描(git grep) / 合规报告 - panel-newcomer: 查找 good-first-issue / 类型判定 / 幂等去重 / 添加引导评论 - Skills 结构总览补 compliance 卡片与文件清单	2026-06-24 10:34:11 +08:00
刘焱	29f8d3403c	docs(plans): 项目级 Skill 集成实现计划	2026-06-17 08:59:59 +08:00
刘焱	654c8976df	docs(specs): 项目级 Skill 集成设计（Claude Code 兼容）	2026-06-17 08:57:53 +08:00
刘焱	f8eea302fb	docs(skills): 真实验证回填基于真机 API 实测（z2_cc/gitlink-cli + 上游 Gitlink/gitlink-cli）修正： - journals 响应结构：data.journals[]（非 data[]）；评论 journal 含 notes，操作 journal 含 operate_content 无 notes；去重仅扫评论 journal 的 notes - GET /v1/:owner/:repo/labels 端点实测不存在（返回首页 HTML），REFERENCE 已标注 - 补充 Windows Git Bash(MSYS) 路径坑：api 的 /v1 参数被转为 D:/Git/... 需 MSYS_NO_PATHCONV=1 - spec §10 未决项全部闭环，并记录未执行的端到端写验证	2026-06-16 08:02:49 +08:00
刘焱	f0f20e5e8e	docs(skills-readme): 概览表补 compliance 与 newcomer-guide	2026-06-15 21:07:08 +08:00
刘焱	bbc1367a88	docs(newcomer-skill): 示例加入去重检查与批量场景	2026-06-15 20:58:17 +08:00
刘焱	cfc28287f4	docs(newcomer-skill): 新增 REFERENCE（命令/字段/标签变体/幂等规则）	2026-06-15 20:57:40 +08:00
刘焱	c2eb3c8f1a	fix(newcomer-skill): 修复 label 命令 Bug，加入状态过滤与幂等去重	2026-06-15 20:57:11 +08:00
刘焱	bb0ef89450	fix(compliance-skill): 修复 DB 连接串正则与跨文件一致性（C1/I1/I2/I3/I4/M2）	2026-06-15 20:45:45 +08:00
刘焱	ef2aa17c8e	docs(compliance-skill): 新增端到端合规检查示例	2026-06-15 20:25:44 +08:00
刘焱	f071f456fa	docs(compliance-skill): REFERENCE 增补敏感信息扫描章节	2026-06-15 20:25:20 +08:00
刘焱	a6e174da88	feat(compliance-skill): 新增敏感信息扫描工作流与报告整合	2026-06-15 20:24:26 +08:00
刘焱	34a0dc0d78	docs(plans): GitLink Skills 丰富与完善实现计划 11 个任务（10 静态 + 1 真实验证），compliance→newcomer→README→全局验证顺序。每步含完整内容与可执行验证命令，已自检（规格覆盖/占位符/类型一致）。	2026-06-15 20:17:48 +08:00
刘焱	a147812e60	docs(specs): GitLink Skills 丰富与完善设计规格聚焦子任务二标记完成的 2 个技能： - gitlink-compliance：补敏感信息扫描工作流 + examples - gitlink-newcomer-guide：修 label 命令 Bug + REFERENCE + 幂等去重决策 A=混合扫描（api+git），决策 B=标记串+journal 去重。验证=先静态后真实。	2026-06-15 20:04:45 +08:00