diff --git a/skills/gitlink-ci-health/SKILL.md b/skills/gitlink-ci-health/SKILL.md new file mode 100644 index 0000000..7142cf9 --- /dev/null +++ b/skills/gitlink-ci-health/SKILL.md @@ -0,0 +1,175 @@ +--- +name: gitlink-ci-health +version: 1.0.0 +description: "CI 健康巡检：检查仓库 CI/CD 授权状态、构建历史和成功率，生成 CI 健康度报告。当用户需要检查 CI 状态、分析构建成功率、排查 CI 故障时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli ci --help" +--- + +# gitlink-ci-health（CI 健康巡检） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 本 Skill 为只读操作（`ci +activate`/`+deactivate` 除外），非只读操作需确认用户意图。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 + +--- + +## 功能概述 + +面向维护者的 CI/CD 健康度巡检工具： + +1. **授权检查** — 确认仓库 CI 是否已激活 +2. **构建历史** — 获取近期构建列表 +3. **成功率统计** — 计算构建成功率和平均耗时 +4. **故障分析** — 识别频繁失败的构建及其原因 +5. **健康报告** — 生成 CI 健康度评分和改进建议 + +--- + +## 工作流：CI 健康巡检 + +### Step 1：检查 CI 授权状态 + +```bash +gitlink-cli ci +authorize --owner --repo --format json +``` + +判断 CI 是否已激活。若未激活，报告中说明"CI 未启用"，建议执行 `ci +activate`。 + +### Step 2：获取构建历史 + +```bash +gitlink-cli ci +builds --owner --repo --format json +``` + +提取每次构建的： +- `status` — 构建状态（success/failed/running/pending） +- `created_at` / `finished_at` — 时间信息 +- `duration` — 耗时（如有） +- `branch` — 触发分支 + +如构建数量 >30，取最近 30 次分析。 + +### Step 3：构建日志（失败构建） + +对状态为 failed 的构建获取日志： + +```bash +gitlink-cli ci +logs --owner --repo --build --format json +``` + +> ⚠️ **控制调用量**：仅对最近 5 次失败构建获取日志，避免过多 API 调用。日志可能过大，提取关键错误行（最后 20 行）。 + +### Step 4：统计分析 + +#### 4.1 成功率计算 + +| 指标 | 计算方式 | +|------|----------| +| 整体成功率 | 成功构建数 / 总构建数 × 100% | +| 近 10 次成功率 | 最近 10 次中成功占比 | +| 平均修复时间 | 从失败到下次成功的平均间隔 | + +#### 4.2 健康度评分（满分 20） + +| 维度 | 权重 | 评分标准 | +|------|------|----------| +| CI 激活 | 4 | 已激活=4，未激活=0 | +| 构建成功率 | 5 | ≥90%=5，≥80%=4，≥70%=3，≥50%=2，<50%=1 | +| 近期稳定性 | 5 | 近10次全部成功=5，8-9次=4，6-7次=3，4-5次=2，<4次=1 | +| 构建频率 | 3 | 每天有构建=3，2-3天=2，每周=1，更少=0 | +| 修复速度 | 3 | 失败后1次内修复=3，2-3次=2，>3次=1 | + +### Step 5：生成 CI 健康报告 + +--- + +## 输出模板 + +```markdown +# 🔧 CI 健康巡检报告：{{仓库名}} + +> 巡检时间：{{当前时间}} +> 仓库：{{full_name}} +> CI 状态：{{ci_status_display}} + +--- + +## 一、健康度总览 + +| 指标 | 数值 | 评分 | +|------|------|------| +| CI 激活状态 | {{activated_status}} | {{activate_score}}/4 | +| 整体成功率 | {{success_rate}}%（{{success_count}}/{{total_count}}） | {{success_score}}/5 | +| 近期稳定性 | 近 10 次 {{recent_success}} 次成功 | {{stability_score}}/5 | +| 构建频率 | {{build_frequency_desc}} | {{frequency_score}}/3 | +| 修复速度 | {{repair_speed_desc}} | {{repair_score}}/3 | +| **总分** | | **{{total_score}}/20** | + +## 二、构建趋势 + +``` +最近 20 次构建： +✅✅❌✅✅✅❌✅✅✅✅✅❌✅✅✅✅✅✅ +（✅=成功 ❌=失败） +``` + +| 时间段 | 总构建 | 成功 | 失败 | 成功率 | +|--------|--------|------|------|--------| +| 最近 7 天 | {{w1_total}} | {{w1_success}} | {{w1_fail}} | {{w1_rate}}% | +| 7-14 天 | {{w2_total}} | {{w2_success}} | {{w2_fail}} | {{w2_rate}}% | +| 14-30 天 | {{w3_total}} | {{w3_success}} | {{w3_fail}} | {{w3_rate}}% | + +## 三、故障分析 + +> 如无失败构建，输出：**🎉 分析期内无失败构建，CI 运行健康。** + +| 构建 ID | 分支 | 失败时间 | 错误摘要 | +|---------|------|----------|----------| +| {{id}} | {{branch}} | {{time}} | {{error_summary}} | + +### 故障模式分类 + +| 故障类型 | 次数 | 占比 | +|----------|------|------| +| 编译错误 | {{compile_count}} | {{compile_pct}}% | +| 测试失败 | {{test_fail_count}} | {{test_fail_pct}}% | +| 超时 | {{timeout_count}} | {{timeout_pct}}% | +| 环境问题 | {{env_count}} | {{env_pct}}% | +| 其他 | {{other_count}} | {{other_pct}}% | + +## 四、改进建议 + + + +- **立即激活 CI**（当 CI 未激活时）：执行 `gitlink-cli ci +activate --owner --repo ` +- **提升成功率**（当 success_rate < 80% 时）：优先修复高频失败原因 +- **增加构建频率**（当构建频率评分 < 2 时）：建议每次 push 触发 CI +- **缩短修复时间**（当修复速度评分 < 2 时）：建立 CI 失败告警 +``` + +--- + +## 异常场景处理 + +| 场景 | 处理方式 | +|------|----------| +| CI 未激活 | 报告 CI 状态为"未激活"，给出激活命令建议，不再继续后续步骤 | +| 无构建记录 | 标注"仓库暂无 CI 构建记录" | +| `ci +logs` 返回空 | 标注"日志不可用" | +| 构建总数 < 5 | 样本量不足，标注"数据有限，统计不具代表性" | + +--- + +## 注意事项 + +- ✅ **所有命令使用 `--format json`**，确保可解析 +- ✅ **`ci +activate` 和 `+deactivate` 为写操作**，执行前需确认用户意图 +- ✅ **Owner/repo 优先从 `git remote` 自动解析** +- ⚠️ **`ci +logs` 输出可能很大**，仅提取关键错误行 +- ⚠️ **构建历史无分页参数**，实际返回条数取决于 API +- ⚠️ **CI 数据仅反映 GitLink 平台活动**，不包括第三方 CI 服务 diff --git a/skills/gitlink-contributor-insight/SKILL.md b/skills/gitlink-contributor-insight/SKILL.md new file mode 100644 index 0000000..10bb52c --- /dev/null +++ b/skills/gitlink-contributor-insight/SKILL.md @@ -0,0 +1,207 @@ +--- +name: gitlink-contributor-insight +version: 1.0.0 +description: "贡献者活跃度分析：分析仓库贡献者的活跃度、贡献趋势和工作节奏，生成贡献者洞察报告。当用户需要分析贡献者活跃度、查看团队贡献趋势、评估成员参与度时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli user --help" +--- + +# gitlink-contributor-insight（贡献者活跃度分析） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 本 Skill 为只读操作，不会修改任何仓库。无需用户额外确认即可执行。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 + +--- + +## 功能概述 + +面向开源社区管理者和维护者的贡献者分析工具： + +1. **项目概览** — 获取仓库贡献者规模 +2. **贡献热力图分析** — 通过 `user +heatmap` 查看贡献节奏 +3. **统计数据提取** — 通过 `user +stats` 获取个人统计 +4. **趋势分析** — 通过 `user +trends` 查看项目趋势 +5. **洞察报告** — 生成贡献者活跃度排名和团队健康度评估 + +--- + +## 工作流：贡献者分析全流程 + +### Step 1：获取项目贡献者列表 + +```bash +gitlink-cli repo +contributors --owner --repo --format json +``` + +> 如果仓库贡献者数量较多（>15），按 `repo +contributors` 返回中 `commits_count` 降序排列，取前 10 位分析。如 `commits_count` 缺失，按返回的自然顺序取前 10 位，报告中注明"基于返回顺序 Top 10"。 + +提取每个贡献者的 `login`（用户名）。 + +### Step 2：获取仓库基本信息 + +```bash +gitlink-cli repo +info --owner --repo --format json +``` + +提取 `contributor_users_count`、`full_name`、`description`。 + +### Step 3：逐位贡献者深度分析 + +对每位贡献者执行以下命令： + +```bash +# 热力图（最近一年的贡献日历） +gitlink-cli user +heatmap --login --format json + +# 统计信息（PR/Issue/Commit 数量） +gitlink-cli user +stats --login --format json + +# 项目趋势 +gitlink-cli user +trends --login --format json +``` + +从返回数据中提取： + +| 维度 | 来源命令 | 分析要点 | +|------|----------|----------| +| 贡献频率 | `+heatmap` | 最近 1/3/6/12 个月有贡献的天数，判断是"持续贡献者"还是"间歇参与者" | +| 贡献产出 | `+stats` | PR 数、Issue 数、Commit 数，区分"代码贡献者"和"问题反馈者" | +| 活跃趋势 | `+trends` | 贡献量是上升/稳定/下降，识别"上升期贡献者"和"逐渐淡出者" | + +> ⚠️ **控制 API 调用**：贡献者 >15 人时，仅分析 Step 1 中按 `commits_count` 排序后的前 10 位。每人最多 3 次 API 调用（heatmap + stats + trends，共 ≤30 次）。 + +### Step 4：贡献者分级与分类 + +#### 4.1 活跃度分级 + +| 级别 | 判定标准 | +|------|----------| +| 🔥 **核心贡献者** | 最近 30 天有贡献 + 总贡献 PR > 10 | +| 🌟 **活跃贡献者** | 最近 60 天有贡献 + 总贡献 > 5 | +| 🌱 **新兴贡献者** | 最近 90 天首次出现 + 贡献频率上升 | +| 💤 **休眠贡献者** | 最近 90 天无贡献 + 历史有贡献 | + +#### 4.2 贡献类型分类 + +| 类型 | 判定 | +|------|------| +| **代码贡献者** | PR/Commit 数量占比最高 | +| **问题反馈者** | Issue 数量占比最高 | +| **全能贡献者** | PR 和 Issue 数量均衡 | + +### Step 5：生成贡献者洞察报告 + +--- + +## 输出模板 + +```markdown +# 👥 贡献者洞察报告：{{仓库名}} + +> 分析时间：{{当前时间}} +> 仓库：{{full_name}} +> 总贡献者：{{contributor_users_count}} 人，本次分析：{{analyzed_count}} 人 + +--- + +## 一、团队概览 + +| 指标 | 数值 | +|------|------| +| 总贡献者 | {{contributor_users_count}} | +| 核心贡献者 | {{core_count}} | +| 活跃贡献者 | {{active_count}} | +| 新兴贡献者 | {{new_count}} | +| 休眠贡献者 | {{dormant_count}} | +| 近 30 天活跃率 | {{active_30d_rate}}% | + +--- + +## 二、贡献者活跃度排行榜 + +| 排名 | 贡献者 | 级别 | 类型 | 近30天贡献 | 总PR | 总Issue | 趋势 | +|------|--------|------|------|-----------|------|---------|------| +| 1 | {{login}} | 🔥 | 代码 | {{d30}} 天 | {{pr_count}} | {{issue_count}} | ↑ | +| ... | ... | ... | ... | ... | ... | ... | ... | + +--- + +## 三、重点贡献者分析 + +> 仅展示核心/活跃贡献者。 + +### 🔥 {{login}}（核心贡献者） + +| 维度 | 数据 | 说明 | +|------|------|------| +| 最近 30 天贡献 | {{d30}} 天 | {{评价}} | +| 总 PR 数 | {{pr_count}} | | +| 总 Issue 数 | {{issue_count}} | | +| 贡献趋势 | {{trend_direction}} | {{trend_comment}} | + +--- + +## 四、团队健康度评估 + +### 健康度指标 + +| 指标 | 状态 | 说明 | +|------|------|------| +| 核心贡献者占比 | {{core_ratio}}% | {{core_comment}} | +| 新老比例 | {{new_old_ratio}} | {{new_old_comment}} | +| 贡献频率稳定性 | {{stability}} | {{stability_comment}} | +| 知识分散度 | {{bus_factor}} | {{bus_factor_comment}} | + +### 风险提示 + + + +- ⚠️ **核心贡献者不足**（当 core_count < 3 时）：仅 {{core_count}} 位核心贡献者，存在单点依赖风险（Bus Factor = {{core_count}}）。 +- ⚠️ **贡献者流失**（当 dormant_rate > 50% 时）：超过一半的贡献者已不活跃，需要关注社区留存。 +- ⚠️ **缺少新鲜血液**（当 new_count == 0 时）：近期无新兴贡献者，建议通过 Good First Issue 等方式吸引新人。 +- ✅ **团队健康**（当以上情况均不满足时）：贡献者结构合理，团队运转良好。 + +> 指标计算： +> - `core_ratio` = core_count / analyzed_count × 100 +> - `dormant_rate` = dormant_count / analyzed_count × 100 +> - `active_30d_rate` = (近30天至少一次贡献的人数) / analyzed_count × 100 +> - `new_old_ratio`：新兴贡献者数 : 核心+活跃贡献者数 的比值 +> - `bus_factor` = core_count（简化定义：核心贡献者数量最低值） +> - `stability`：判断标准为"贡献标准差"（各月贡献量波动小=高稳定性，波动大=低稳定性） + +--- + +## 五、社区建设建议 + +1. **激励核心贡献者**：{{核心贡献者维护建议}} +2. **激活休眠贡献者**：{{休眠贡献者召回建议}} +3. **吸引新贡献者**：{{新贡献者吸引建议}} +4. **平衡贡献类型**：{{贡献类型平衡建议}} +``` + +--- + +## 异常场景处理 + +| 场景 | 处理方式 | +|------|----------| +| `repo +contributors` 返回空 | 标注"仓库暂无贡献者数据"，仅从 `repo +info` 获取 `contributor_users_count` | +| `user +heatmap` 返回空 | 标注"无热力图数据"，评分仅基于 stats 和 trends | +| `user +stats` / `+trends` 返回错误 | 跳过该维度，标注"数据不可用" | +| 贡献者 > 15 人 | 仅分析贡献量最高的前 10 位，报告中注明"基于 Top 10 分析" | + +--- + +## 注意事项 + +- ✅ **所有命令使用 `--format json`**，确保可解析 +- ✅ **本 Skill 为纯只读分析**，不会修改任何仓库 +- ✅ **Owner/repo 优先从 `git remote` 自动解析**，无 git 上下文时询问用户 +- ⚠️ **每人 3 次 API 调用**（heatmap + stats + trends），10 人即 30 次，注意控制分析人数 +- ⚠️ **热力图数据可能稀疏**：部分贡献者数据不完整，标注"数据有限" +- ⚠️ **数据仅反映 GitLink 平台活动**：不包括 GitHub 或其他平台的数据 diff --git a/skills/gitlink-issue-triage/SKILL.md b/skills/gitlink-issue-triage/SKILL.md index 05bb621..bdcaf70 100644 --- a/skills/gitlink-issue-triage/SKILL.md +++ b/skills/gitlink-issue-triage/SKILL.md @@ -1,6 +1,6 @@ --- name: gitlink-issue-triage -version: 1.0.0 +version: 1.1.0 description: "Issue 智能分拣：自动分析仓库 Issue 列表，按类型、紧急度、复杂度分类，生成分拣报告和维护建议。当用户需要整理 Issue、分类 Issue、Issue 分拣、Issue 优先级排序时触发。" metadata: requires: @@ -11,7 +11,7 @@ metadata: # gitlink-issue-triage（Issue 智能分拣） **CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** -**CRITICAL — 本 Skill 为只读操作，不会修改任何 Issue。无需用户额外确认即可执行。** +**CRITICAL — `issue +series-update` 为写操作，会批量修改 Issue 状态。执行前需确认用户意图。** **CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。** > **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 @@ -25,7 +25,9 @@ metadata: 1. **类型分类** — 判断每个 Issue 是 Bug、功能请求、文档问题还是使用咨询 2. **紧急度评估** — 根据关键词和优先级字段标注紧急程度 3. **复杂度预估** — 根据描述详尽程度评估修复难度 -4. **行动建议** — 给出具体处理建议（立即修复/需讨论/可关闭/适合作入门任务） +4. **活动日志分析** — 通过 `issue +journals` 查看 Issue 活动历史 +5. **行动建议** — 给出具体处理建议（立即修复/需讨论/可关闭/适合作入门任务） +6. **批量操作** — 支持通过 `issue +series-update` 批量更新 Issue 状态 --- @@ -71,6 +73,22 @@ gitlink-cli issue +view --owner --repo --number --repo --number --format json +``` + +从 `journals` 数组中提取： +- 最近一次状态变更时间和操作者 +- 最近一次评论时间和作者 +- 是否有 @提及等待回复 +- 是否有分配变更记录 + +> ⚠️ **控制调用量**：仅对 urgent/high 级别的 Issue 获取活动日志。日志数据可能较大，只提取关键时间节点。 + ### Step 4：分类规则 #### 4.1 类型分类（type） @@ -120,6 +138,20 @@ gitlink-cli issue +view --owner --repo --number --repo --ids --status closed --format json +``` + +> ⚠️ **写操作**：执行前需向用户展示将要操作的 Issue 列表，获得确认后再执行。 + +典型使用场景： +- 批量关闭 `close-candidate` 列表中的 Issue +- 批量将 `good-first-issue` 标记为 open（确保状态正确） + --- ## 输出模板 @@ -151,40 +183,31 @@ gitlink-cli issue +view --owner --repo --number 如本段为空，输出：*当前无紧急 Issue，状态健康。* -| # | 标题 | 类型 | 紧急度 | 复杂度 | 建议 | 备注 | -|---|------|------|--------|--------|------|------| -| {{number}} | {{subject}} | bug | urgent | medium | fix-now | | -| ... | ... | ... | ... | ... | ... | ... | +| # | 标题 | 类型 | 紧急度 | 复杂度 | 上次活动 | 建议 | 备注 | +|---|------|------|--------|--------|----------|------|------| +| {{number}} | {{subject}} | bug | urgent | medium | {{last_journal_time}} | fix-now | | +| ... | ... | ... | ... | ... | ... | ... | ... | ## 🟡 建议近期处理 -> 如本段为空，输出：*当前无高优先级 Issue。* - -| # | 标题 | 类型 | 紧急度 | 复杂度 | 建议 | 备注 | -|---|------|------|--------|--------|------|------| -| ... | ... | bug/feature | high/normal | easy/medium | investigate/implement | | +| # | 标题 | 类型 | 紧急度 | 复杂度 | 上次活动 | 建议 | 备注 | +|---|------|------|--------|--------|----------|------|------| +| ... | ... | bug/feature | high/normal | easy/medium | ... | investigate/implement | | ## 🟢 可延迟 / 需讨论 -> 如本段为空，输出：*所有 Issue 均已明确，无需额外讨论。* - -| # | 标题 | 类型 | 紧急度 | 复杂度 | 建议 | 备注 | -|---|------|------|--------|--------|------|------| -| ... | ... | question/feature | normal/low | medium/hard | discuss | | +| # | 标题 | 类型 | 紧急度 | 复杂度 | 上次活动 | 建议 | 备注 | +|---|------|------|--------|--------|----------|------|------| +| ... | ... | question/feature | normal/low | medium/hard | ... | discuss | | ## ⭐ 适合入门（Good First Issue） -> 如本段为空，输出：*暂无完全符合条件的入门 Issue。建议在后续工作中拆分出简单子任务。* - | # | 标题 | 类型 | 复杂度 | 推荐理由 | |---|------|------|--------|----------| | {{number}} | {{subject}} | bug/docs | easy | 范围明确，单文件修改 | -| ... | ... | ... | ... | ... | ## ⚠️ 候选关闭（90+ 天无活动） -> 如本段为空，输出：*无长期不活跃的 Issue。* - | # | 标题 | 最后更新 | 建议 | |---|------|----------|------| | {{number}} | {{subject}} | {{updated_at}} | 评论询问是否仍需要，如无回应可关闭 | @@ -194,11 +217,18 @@ gitlink-cli issue +view --owner --repo --number 如无适用操作，输出：*当前无需批量操作。* + +以下 Issue 建议批量关闭（已确认超 90 天无活动）： +`gitlink-cli issue +series-update --owner --repo --ids {{close_ids}} --status closed` ``` --- @@ -212,15 +242,18 @@ gitlink-cli issue +view --owner --repo --number **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 + +--- + +## 功能概述 + +帮助用户高效管理 GitLink 通知： + +1. **通知列表** — 获取所有未读通知 +2. **自动分类** — 按类型（Issue/PR/评论/系统）分组 +3. **优先级判断** — 识别需要立即处理的通知 +4. **批量操作** — 支持标记已读（需确认） +5. **摘要报告** — 生成结构化通知摘要 + +--- + +## 工作流：通知摘要 + +### Step 1：获取通知列表 + +```bash +gitlink-cli notification +list --format json +``` + +获取参数： +- 默认获取未读通知 +- 如需全部通知（含已读）：`--all` +- 如需仅参与的通知：`--participating` +- 分页：`--page 2 --limit 20` + +提取每条通知的： +- `id` — 通知 ID（用于 `+read` 单条标记已读） +- `content` — 通知内容（HTML 格式，从中提取摘要文本） +- `source` — 通知来源类型（如 IssueAtme、PullRequestAssigned、ProjectForked 等） +- `notification_url` — 通知链接，从中解析关联仓库（提取 URL path 中的 `/owner/repo/` 段） +- `created_at` — 通知时间 +- `status` — 状态（1=未读，2=已读） + +### Step 2：分类与优先级 + +#### 2.1 按类型分类（优先使用 `source` 字段） + +| 类型 | `source` 字段匹配 | 处理建议 | +|------|------------------|----------| +| 🔴 **@提及** | 含 `Atme`（如 IssueAtme, PullRequestAtme） | 立即查看回复 | +| 🟡 **Issue 更新** | 含 `Issue`（如 IssueAssigned, IssueClosed） | 当天处理 | +| 🟢 **PR 更新** | 含 `PullRequest`（如 PullRequestAssigned, PullRequestMerged） | 跟进代码 | +| 🔵 **系统通知** | 含 `Project`/`Organization`（如 ProjectForked, ProjectJoined） | 知悉即可 | +| ⚪ **其他** | 不匹配以上 | 按需查看 | + +> `source` 字段返回的是结构化枚举值（如 `IssueAtme`），优先以此分类。`content` 字段为 HTML 文本，仅作补充参考。 + +#### 2.2 优先级排序 + +| 优先级 | 判定 | +|--------|------| +| **P0 - 立即** | @提及 + 来自自己参与的 Issue/PR | +| **P1 - 今天** | 自己创建的 Issue/PR 有新回复，或分配的 Issue 有更新 | +| **P2 - 本周** | 关注的仓库有新动态 | +| **P3 - 可忽略** | 系统通知、已解决的 Issue | + +### Step 3：生成通知摘要 + +按模板输出。 + +### Step 4：批量标记已读（可选，需确认） + +```bash +# 标记全部已读 +gitlink-cli notification +read-all --format json + +# 标记单条已读 +gitlink-cli notification +read --id --format json +``` + +> ⚠️ **执行前必须确认用户意图** — `+read` 和 `+read-all` 为写操作。 + +--- + +## 输出模板 + +```markdown +# 🔔 通知摘要 + +> 生成时间：{{当前时间}} +> 未读通知：{{unread_count}} 条 / 总计：{{total_count}} 条 + +--- + +## 一、概要 + +| 类型 | 未读 | 总计 | +|------|------|------| +| @提及 | {{mention_unread}} | {{mention_total}} | +| Issue 更新 | {{issue_unread}} | {{issue_total}} | +| PR 更新 | {{pr_unread}} | {{pr_total}} | +| 系统通知 | {{system_unread}} | {{system_total}} | +| 其他 | {{other_unread}} | {{other_total}} | + +--- + +## 二、需要立即处理（P0） + +> 如无，输出：*🎉 无紧急通知。* + +| # | 类型 | 仓库 | 内容摘要 | 时间 | +|---|------|------|----------|------| +| 1 | 🔴@提及 | {{repo}} | {{summary}} | {{time}} | + +--- + +## 三、今天处理（P1） + +> 如无，输出：*无待处理通知。* + +| # | 类型 | 仓库 | 内容摘要 | 时间 | +|---|------|------|----------|------| + +--- + +## 四、本周关注（P2） + +> 如无，输出：*无需要本周关注的通知。* + +--- + +## 五、可忽略（P3） + +> 如本段被折叠，输出：*{{p3_count}} 条低优先级通知，已折叠。* + +--- + +## 六、通知趋势 + +| 时间段 | 通知数 | +|--------|--------| +| 今日 | {{today_count}} | +| 昨日 | {{yesterday_count}} | +| 本周 | {{week_count}} | +| 上周 | {{last_week_count}} | + +--- + +## 操作建议 + +- 建议标记已读：{{suggest_read_count}} 条 P3 通知 +- 需要回复/处理：{{need_action_count}} 条 P0/P1 通知 + +如需标记全部已读，我可以执行： +`gitlink-cli notification +read-all` +``` + +--- + +## 异常场景处理 + +| 场景 | 处理方式 | +|------|----------| +| 无未读通知 | 输出"🎉 所有通知已处理完毕" | +| 通知数量 > 50 | 分批获取（page 1/2/3），优先分析最近 50 条 | +| `notification +list` 返回空 | 检查认证状态（参考 gitlink-shared） | + +--- + +## 注意事项 + +- ✅ **所有命令使用 `--format json`**，确保可解析 +- ✅ **`+read` 和 `+read-all` 为写操作**，执行前必须确认用户意图 +- ✅ **本 Skill 默认只读分析**，仅在用户明确要求时标记已读 +- ⚠️ **通知类型依赖标题关键词推断**，实际类型可能有偏差 +- ⚠️ **通知可能分页**，数量 >20 时需追加 `--page 2` 等 diff --git a/skills/gitlink-research-tracker/SKILL.md b/skills/gitlink-research-tracker/SKILL.md index ae4e222..385197d 100644 --- a/skills/gitlink-research-tracker/SKILL.md +++ b/skills/gitlink-research-tracker/SKILL.md @@ -1,6 +1,6 @@ --- name: gitlink-research-tracker -version: 1.0.0 +version: 1.1.0 description: "技术评估与调研报告：对技术项目进行多维度评估（社区活跃度、成熟度评分、技术趋势），生成含选型建议的结构化调研报告。当用户需要做技术评估、生成调研报告、科研选题分析、竞品对比研究时触发。" metadata: requires: @@ -22,7 +22,7 @@ metadata: 面向科研场景的技术调研工具，帮助研究者快速了解 GitLink 平台上的技术格局： -1. **多关键词搜索** — 将研究主题拆解为多个关键词，全面覆盖相关项目 +1. **多关键词搜索** — 仓库搜索 + 代码搜索 + Issue 搜索，三维覆盖 2. **项目深度评估** — 从活跃度、社区规模、代码产出等维度评估项目健康度 3. **横向对比** — 对比同类项目的核心指标，识别领先者和潜力项目 4. **趋势洞察** — 基于更新时间、贡献者增长、版本发布频率等推断技术趋势 @@ -45,9 +45,9 @@ metadata: > **原则**：关键词应覆盖中英文、缩写全称、技术术语和行业叫法。每个关键词独立搜索。 -### Step 2：多关键词搜索 +### Step 2：多维度搜索（v1.1 扩展：三维搜索） -对每个关键词执行搜索： +#### 2a. 仓库搜索 ```bash gitlink-cli search +repos -k <关键词> --format json @@ -57,13 +57,43 @@ gitlink-cli search +repos -k <关键词> --format json | SKILL 中用到的概念 | 实际字段来源 | 说明 | |-------------------|-------------|------| -| owner/repo 标识 | `author.login` + `/` + `identifier` | 搜索结果**没有** `full_name`，需手动拼接。`identifier` 是仓库的唯一标识符 | +| owner/repo 标识 | `author.login` + `/` + `identifier` | 搜索结果**没有** `full_name`，需手动拼接 | | 项目描述 | `description` | 直接可用 | -| 关注度 | `praises_count` | 搜索结果中叫 `praises_count`，**不是** `stars`。`watchers_count` 仅在 `repo +info` 中返回 | +| 关注度 | `praises_count` | 搜索结果中叫 `praises_count`，**不是** `stars` | | Fork 数 | `forked_count` | 搜索结果中叫 `forked_count`，**不是** `forks_count` | | 编程语言 | `language.name` | `language` 是嵌套对象 `{id, name}`，需取 `.name`。可能为 `null` | -| 更新时间 | `last_update_time`（Unix 时间戳）或 `full_last_update_time`（ISO 8601 字符串） | 搜索结果中**没有** `updated_at` | -| 是否镜像 | `mirror` | 仅在 `repo +info` 返回。GitLink 上大量仓库是 GitHub 镜像，需特别标注 | +| 更新时间 | `last_update_time` 或 `full_last_update_time` | 搜索结果中**没有** `updated_at` | +| 是否镜像 | `mirror` | 仅在 `repo +info` 返回 | + +#### 2b. 代码搜索（v1.1 新增） + +对技术关键词搜索代码引用，了解技术在实际项目中的使用情况： + +```bash +gitlink-cli search +code -k <关键词> --format json +``` + +从结果中提取： +- 匹配到的文件路径和仓库 +- 代码片段预览 +- 判断：哪些项目**实际使用了**该技术（而非仅描述中提到） + +> 代码搜索结果用于辅助判断"代码活跃度"——有大量代码匹配的项目说明该技术在实际开发中活跃使用。 + +#### 2c. Issue 搜索（v1.1 新增） + +搜索与主题相关的 Issue 讨论，了解技术痛点和需求： + +```bash +gitlink-cli search +issues -k <关键词> --format json +``` + +从结果中提取： +- 高频讨论主题 +- 常见技术痛点和需求 +- 社区对某个技术的关注焦点 + +> ⚠️ **控制搜索量**：代码搜索和 Issue 搜索仅针对 2-3 个核心关键词执行，不是全部关键词。避免 API 调用过多。 **去重规则**：用 `author.login/identifier` 作为唯一标识。同一仓库出现在多个关键词结果中时，只保留一次，标注匹配了哪些关键词。 @@ -87,6 +117,7 @@ gitlink-cli repo +info --owner --repo --format json | **代码规模** | `size` | 粗略判断项目复杂度 | | **开放性** | `forked_count` | fork 数反映二次开发热度 | | **PR 活跃度** | `pull_requests_count` | 反映代码贡献频率 | +| **代码活跃度**（v1.1） | `search +code` 命中量 | 反映技术在实际代码中的使用程度 | 可选补充（如有需要）： @@ -98,33 +129,29 @@ gitlink-cli issue +list --owner --repo --state open --format json gitlink-cli release +list --owner --repo --format json ``` -> ⚠️ **控制分析数量**：深度评估仅对最有价值的 5~8 个项目执行（优先匹配多关键词、watchers 多、updated_at 最近的项目），避免过多 API 调用。 +> ⚠️ **控制分析数量**：深度评估仅对最有价值的 5~8 个项目执行，避免过多 API 调用。 ### Step 4：横向对比与趋势分析 #### 4.1 项目分类与镜像识别 -在评分之前，先通过 `repo +info` 的 `mirror` 字段区分项目类型： - | 类型 | 判定 | 处理 | |------|------|------| -| **镜像仓库** | `mirror: true` | 标注 `[镜像]`。GitLink 上的 `contributor_users_count`/`watchers_count` 等指标均为 0，不代表真实社区活跃度。评分仅作参考 | +| **镜像仓库** | `mirror: true` | 标注 `[镜像]`。评分仅作参考 | | **原创仓库** | `mirror: false` 且 `forked_from_project_id: null` | 正常评分 | -| **Fork 仓库** | `forked_from_project_id` 非 null | 标注 `[Fork]`，评分反映的是 Fork 后的独立开发情况 | +| **Fork 仓库** | `forked_from_project_id` 非 null | 标注 `[Fork]` | -#### 4.2 项目成熟度评分 - -对每个深度评估的项目，按以下标准打分（满分 25）： +#### 4.2 项目成熟度评分（满分 25） | 维度 | 权重 | 评分标准 | |------|------|----------| | 社区规模 | 5 | contributor_users_count: >20=5, >10=4, >5=3, >2=2, ≤2=1 | -| 关注度 | 5 | repo +info 的 watchers_count: >30=5, >15=4, >8=3, >3=2, ≤3=1 | -| 研发节奏 | 5 | version_releases_count: >10=5, >5=4, >1=3, 0=2。**镜像仓库此项固定给 1**（镜像通常不通过 GitLink 发版）。注意 GitLink 平台 Release 功能使用率低，即使原创仓库 release=0 也建议给 2 而非 1 | -| 开发活跃 | 5 | 最近 30 天有更新=5, 60 天=4, 90 天=3, 180 天=2, >180 天=1。（基于 `repo +info` 的更新时间或搜索结果中的 `last_update_time`） | +| 关注度 | 5 | watchers_count: >30=5, >15=4, >8=3, >3=2, ≤3=1 | +| 研发节奏 | 5 | version_releases_count: >10=5, >5=4, >1=3, 0=2。镜像仓库固定给 1 | +| 开发活跃 | 5 | 最近 30 天有更新=5, 60 天=4, 90 天=3, 180 天=2, >180 天=1 | | 开放性 | 5 | forked_count: >30=5, >15=4, >8=3, >3=2, ≤3=1 | -> **镜像修正**：镜像仓库的社区规模、关注度、开放性三项在 GitLink 上均为 0，应标注"数据为 GitLink 平台内数据，不代表项目在原始平台（GitHub）的真实影响力"，不参与排名比较。 +> **镜像修正**：镜像仓库评分仅作参考，不参与排名比较。 #### 4.3 技术趋势推断 @@ -132,6 +159,7 @@ gitlink-cli release +list --owner --repo --format json - **成熟信号**：大量 watcher + 稳定 Release 节奏 + 大社区 → 技术趋于成熟 - **衰退信号**：超过 180 天无更新 + 少量 contributor + 无新 Release → 可能已不活跃 - **新兴信号**：小社区 + 快速迭代 + 最新更新时间近 → 可能是新兴项目 +- **代码证据**（v1.1）：`search +code` 命中量增长 → 技术采纳度上升 ### Step 5：生成技术调研报告 @@ -144,7 +172,8 @@ gitlink-cli release +list --owner --repo --format json > 调研时间：{{当前时间}} > 搜索关键词：{{keyword_list}} -> 搜索命中：{{total_hits}} 个仓库，去重后 {{unique_count}} 个，深度分析 {{deep_analysis_count}} 个 +> 搜索维度：仓库搜索 {{repo_hits}} + 代码搜索 {{code_hits}} + Issue 搜索 {{issue_hits}} +> 去重后 {{unique_count}} 个项目，深度分析 {{deep_analysis_count}} 个 --- @@ -157,15 +186,15 @@ gitlink-cli release +list --owner --repo --format json | 平均社区规模 | {{avg_contributors}} 人 | | 近 30 天活跃项目 | {{active_30d_count}}（{{active_30d_pct}}%） | | 高成熟度项目（≥20分） | {{high_maturity_count}} | +| 代码引用量 | {{code_search_hits}} 次命中（反映技术采纳度） | --- ## 二、项目成熟度排行榜 -| 排名 | 项目 | 类型 | 评分 | 语言 | Watch | 贡献者 | Release | Fork | 关键词匹配 | -|------|------|------|------|------|-------|--------|---------|------|------------| -| 1 | {{full_name}} {{#if mirror}}[镜像]{{/if}} | {{原创/镜像/Fork}} | {{score}}/25 | {{language}} | {{watchers}} | {{contributors}} | {{releases}} | {{forks}} | {{matched_keywords}} | -| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | +| 排名 | 项目 | 类型 | 评分 | 语言 | Watch | 贡献者 | 代码引用 | Fork | 关键词匹配 | +|------|------|------|------|------|-------|--------|----------|------|------------| +| 1 | {{full_name}} | {{原创/镜像/Fork}} | {{score}}/25 | {{language}} | {{watchers}} | {{contributors}} | {{code_refs}} | {{forks}} | {{matched_keywords}} | --- @@ -188,18 +217,13 @@ gitlink-cli release +list --owner --repo --format json --- -### 🥈 {{项目名}}（{{score}}/25） - -（同上格式） - ---- - ## 四、技术趋势洞察 -1. **热点方向**：{{当前最热的技术方向，基于项目分布推断}} -2. **新兴项目**：{{列出 1~3 个"新兴信号"明显的项目}} -3. **成熟生态**：{{列出 1~2 个"成熟信号"明显的项目，适合作为技术选型参考}} -4. **风险提示**：{{列出 1~2 个"衰退信号"项目或值得关注的生态空白}} +1. **热点方向**：{{当前最热的技术方向}} +2. **新兴项目**：{{1~3 个"新兴信号"明显的项目}} +3. **成熟生态**：{{1~2 个"成熟信号"明显的项目}} +4. **社区讨论焦点**（v1.1）：基于 `search +issues` 的技术痛点分析 +5. **风险提示**：{{1~2 个"衰退信号"项目或生态空白}} --- @@ -223,6 +247,7 @@ gitlink-cli release +list --owner --repo --format json ## 六、数据来源 所有数据通过 `gitlink-cli` 从 GitLink 平台实时获取，每个项目均已通过 `repo +info` 验证。 +搜索维度：`search +repos`（仓库）、`search +code`（代码）、`search +issues`（Issue） ``` --- @@ -231,13 +256,14 @@ gitlink-cli release +list --owner --repo --format json | 场景 | 处理方式 | |------|----------| -| 关键词无搜索结果 | 尝试近义词或更宽泛的关键词重试，仍无结果则标注"该方向暂无相关项目" | -| 搜索返回大量结果（>50） | `search +repos` 无分页参数，实际返回约 20 条/关键词。合并后按 `praises_count` 降序取前 20 | -| 某项目 `repo +info` 返回 404 | 该项目可能为私有或已删除，从列表中移除 | -| `repo +info` 网络超时/TLS 错误 | 等待 5 秒后重试一次。仍失败则标注"网络请求失败"，跳过该项目继续分析其余 | -| 大量搜索结果来自镜像仓库 | 优先分析 `mirror: false` 的原创项目。镜像项目保留但标注，评分仅作参考 | -| 所有项目评分均 <15 | 说明该领域尚未形成成熟生态，调整报告语气为"早期探索阶段" | -| 用户未提供具体关键词 | 引导用户明确研究主题，提供几个示例关键词供选择 | +| 关键词无搜索结果 | 尝试近义词重试，仍无结果则标注"该方向暂无相关项目" | +| 搜索返回大量结果（>50） | 合并后按 `praises_count` 降序取前 20 | +| 某项目 `repo +info` 返回 404 | 从列表中移除 | +| `repo +info` 网络超时/TLS 错误 | 等待 5 秒后重试一次，仍失败则跳过 | +| 大量搜索结果来自镜像仓库 | 优先分析 `mirror: false` 的原创项目 | +| 所有项目评分均 <15 | 调整报告语气为"早期探索阶段" | +| `search +code` 返回空 | 标注"代码搜索无命中"，不阻塞分析 | +| `search +issues` 返回空 | 标注"Issue 搜索无命中"，不阻塞分析 | | `language` 字段为 `null` | 标注为"未知" | --- @@ -246,11 +272,11 @@ gitlink-cli release +list --owner --repo --format json - ✅ **所有命令使用 `--format json`**，确保可解析 - ✅ **本 Skill 为纯只读分析**，不会修改任何仓库 -- ✅ **搜索关键词建议中英文各覆盖**，提高命中率 +- ✅ **搜索关键词建议中英文各覆盖** - ✅ **深度评估控制在 5~8 个项目**，避免调用过多 API -- ⚠️ **`search +repos` 和 `repo +info` 字段名不同**：搜索结果用 `praises_count`/`forked_count`/`author.login+identifier`，`repo +info` 才有 `watchers_count`/`full_name`/`mirror`。详见 Step 2 字段映射表 -- ⚠️ **`repo +info` 并发请求可能触发 TLS 超时**，失败时等 5 秒重试一次，不要放弃 -- ⚠️ **GitLink 平台镜像仓库比例高**，镜像仓库的社区数据为 0，不代表项目真实影响力。在报告中标注 `[镜像]` 并单独说明 -- ⚠️ **GitLink Release 功能使用率低**，大部分项目 `version_releases_count`=0。评分时 Release 维度降低权重预期，0 个 Release 给 2 分（而非 1 分） -- ⚠️ **搜索结果无分页参数**，每次返回约 20 条。关键词超过 5 个时需手动截断合并结果 -- ⚠️ **本 Skill 场景适配 GitLink 平台**，GitLink 以国内开发者和企业项目为主，搜索结果可能偏向中文技术生态，且镜像项目较多 +- ⚠️ **v1.1 新增 `search +code` 和 `+issues`**：仅对 2-3 个核心关键词执行，控制 API 调用总量 +- ⚠️ **`search +repos` 和 `repo +info` 字段名不同**：搜索结果用 `praises_count`/`forked_count`，`repo +info` 有 `watchers_count`/`full_name`/`mirror` +- ⚠️ **`repo +info` 并发请求可能触发 TLS 超时**，失败时等 5 秒重试一次 +- ⚠️ **GitLink 平台镜像仓库比例高**，镜像仓库的社区数据为 0 +- ⚠️ **GitLink Release 功能使用率低**，0 个 Release 给 2 分（非镜像） +- ⚠️ **本 Skill 场景适配 GitLink 平台**，结果可能偏向中文技术生态