feat(contributor-insight): 更新至 v1.1.0，新增 EXAMPLES.md 和实际执行样例

- 新增命令可用性声明（标注 repo +contributors/user +heatmap 等不可用命令及替代方案） - 重写工作流步骤：贡献者列表从 pr +list 提取，活跃度从 PR 时间戳推算 - 新增年轻项目（<30天）分级放宽规则 - 扩充异常场景处理表（新增 3 种场景） - 新增 EXAMPLES.md：手动执行 + Agent 调用两种完整样例 - 新增 examples/jiangtx-gitlink-cli.md：原始命令输出数据附录 - 同步 ci-health EXAMPLES.md Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-03 10:29:52 +08:00 · 2026-06-03 10:29:52 +08:00 · 7c293f9b5a
parent dd805951a5
commit 7c293f9b5a
5 changed files with 746 additions and 64 deletions
--- a/skills/gitlink-ci-health/EXAMPLES.md
+++ b/skills/gitlink-ci-health/EXAMPLES.md
@ -0,0 +1,178 @@
+# gitlink-ci-health 使用样例
+
+## 样例 1：CI 未激活的仓库
+
+**日期**：2026-06-03
+**仓库**：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
+**CLI 版本**：gitlink-cli 0.1.18
+
+### 执行流程
+
+```bash
+# Step 1: 检查 CI 状态（方法 1 — repo +info）
+gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
+# → "open_devops": false  ← CI 未激活
+
+# Step 1 补充（方法 2 — ci +builds）
+gitlink-cli ci +builds --owner jiangtx --repo gitlink-cli --format json
+# → {"status":-1,"message":"接口数据异常"}  ← 确认 CI 未激活
+
+# 此时终止后续步骤，生成"CI 未激活"报告
+```
+
+### 关键发现
+
+| 项目 | 值 |
+|------|-----|
+| `open_devops` | `false` |
+| `ci +builds` 返回 | `{"status": -1, "message": "接口数据异常"}` |
+| 可用 CI 命令 | `+builds`、`+logs`、`+restart`、`+stop` |
+| 不存在的命令 | `ci +authorize`、`ci +activate`、`ci +deactivate` |
+
+### 诊断结论
+
+CI 完全未启用，需通过 GitLink Web 界面开启（仓库设置 → DevOps）。用户拥有 Manager 权限，可以操作。
+
+### 生成的报告
+
+```markdown
+# 🔧 CI 健康巡检报告：jiangtx/gitlink-cli
+
+> 巡检时间：2026-06-03
+> 仓库：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
+> CI 状态：❌ 未激活
+
+## 一、健康度总览
+
+| 指标 | 数值 | 评分 |
+|------|------|------|
+| CI 激活状态 | ❌ 未激活（open_devops: false） | 0/4 |
+| 整体成功率 | N/A | —/5 |
+| 近期稳定性 | N/A | —/5 |
+| 构建频率 | N/A | —/3 |
+| 修复速度 | N/A | —/3 |
+| **总分** | | **0/20** |
+
+## 二、诊断详情
+
+API 调用 ci +builds 返回：
+{"status": -1, "message": "接口数据异常"}
+
+仓库元数据显示 open_devops: false，确认该仓库尚未启用 GitLink 平台的 CI/CD（DevOps）服务。
+
+## 三、改进建议
+
+- 🔴 立即激活 CI：前往 GitLink Web 界面 → 仓库设置 → DevOps 开启 CI/CD 服务
+- 🟡 配置 CI Pipeline：建议添加 .gitlink-ci.yml 配置编译和测试流水线
+
+## 四、仓库基本信息
+
+| 项目 | 值 |
+|------|-----|
+| 默认分支 | master |
+| 仓库大小 | 13.4 MB |
+| 贡献者 | 2 |
+| PR 数量 | 9 |
+| 权限 | Manager |
+```
+
+---
+
+## 异常场景速查
+
+| 场景 | 检测方式 | `ci +builds` 返回值 | 处理 |
+|------|----------|---------------------|------|
+| CI 未激活 | `repo +info` 的 `open_devops: false` | `{"status":-1,"message":"接口数据异常"}` | 建议 Web 界面激活，终止巡检 |
+| CI 已激活但无构建 | `repo +info` 的 `open_devops: true` + builds 为空 | `[]` 或空列表 | 标注"暂无构建记录" |
+| 构建样本不足（<5） | builds 列表长度 < 5 | 正常 JSON 数组 | 标注"数据有限，不具代表性" |
+
+---
+
+## 版本兼容性说明
+
+本 skill 基于 `gitlink-cli 0.1.18` 编写。不同版本的 CI 子命令可能有差异：
+
+| CLI 版本 | 可用 CI 命令 |
+|----------|-------------|
+| 0.1.18 | `+builds`、`+logs`、`+restart`、`+stop` |
+| 未来版本 | 可能新增 `+activate`、`+deactivate` 等 |
+
+当 CLI 版本更新后，重新验证可用命令：
+```bash
+gitlink-cli ci --help
+```
+
+---
+
+## 样例 2：通过 Agent 调用 Skill（自动巡检）
+
+**日期**：2026-06-03
+**仓库**：jiangtx/gitlink-cli
+**调用方式**：`Agent(subagent_type="general-purpose", prompt="调用 gitlink-ci-health skill，检查 jiangtx/gitlink-cli 的 CI 状态。严格按照 skill 的工作流步骤执行。")`
+
+### Agent 自主执行的命令序列
+
+```
+工具调用 1: gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
+           → open_devops: false  ← 发现 CI 未激活
+
+工具调用 2: gitlink-cli ci +builds --owner jiangtx --repo gitlink-cli --format json
+           → {"status": -1, "message": "接口数据异常"}  ← 二次确认
+```
+
+### Agent 决策过程
+
+Agent 读取到 `open_devops: false` 后，**正确遵循了 skill 的异常场景处理规则**：
+
+> "CI 未激活 → 报告 CI 状态为'未激活'，建议通过 Web 界面开启，**不再继续后续步骤**"
+
+Agent 没有继续尝试 `ci +logs` 或统计分析，直接生成了完整报告。共消耗 **5 次工具调用**，**32,113 tokens**，耗时 **35.8 秒**。
+
+### Agent 生成的报告
+
+```markdown
+# CI 健康巡检报告：gitlink-cli
+
+> 巡检时间：2026-06-03
+> 仓库：jiangtx/gitlink-cli
+> CI 状态：未激活
+
+## 一、健康度总览
+
+| 指标 | 数值 | 评分 |
+|------|------|------|
+| CI 激活状态 | 未激活 | 0/4 |
+| 整体成功率 | N/A | -/5 |
+| 近期稳定性 | N/A | -/5 |
+| 构建频率 | N/A | -/3 |
+| 修复速度 | N/A | -/3 |
+| **总分** | | **0/20** |
+
+## 二、构建趋势
+
+无构建记录。仓库 CI 未启用。
+
+## 三、故障分析
+
+CI 未激活，无构建数据可供分析。
+
+## 四、改进建议
+
+- **立即激活 CI**：前往 GitLink Web 界面 → 仓库设置 → DevOps，开启 CI/CD 服务。
+  （CLI 暂不支持 ci +activate 命令，需要通过 Web 界面操作。）
+
+---
+
+总结：仓库 jiangtx/gitlink-cli（项目 ID: 1547588，默认分支: master，权限: Manager）
+当前 open_devops 字段为 false，CI/CD 服务未开启。其他仓库信息：2 位贡献者、
+9 个 PR、0 个 Issue，Fork 自 Gitlink/gitlink-cli。
+```
+
+### 验证结论
+
+✅ skill v1.1.0 修复验证通过：
+- Agent 正确使用了 `repo +info` 的 `open_devops` 字段判断 CI 状态
+- Agent 在 CI 未激活时正确终止，没有执行后续无效步骤
+- Agent 没有尝试调用不存在的 `ci +authorize` 或 `ci +activate`
+- Agent 正确建议通过 Web 界面激活
+- 报告结构完整，包含了仓库基本信息
--- a/skills/gitlink-ci-health/SKILL.md
+++ b/skills/gitlink-ci-health/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: gitlink-ci-health
-version: 1.0.0
+version: 1.1.0
 description: "CI 健康巡检：检查仓库 CI/CD 授权状态、构建历史和成功率，生成 CI 健康度报告。当用户需要检查 CI 状态、分析构建成功率、排查 CI 故障时触发。"
 metadata:
  requires:
@ -11,7 +11,7 @@ metadata:
 # gitlink-ci-health（CI 健康巡检）

 **CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
-**CRITICAL — 本 Skill 为只读操作（`ci +activate`/`+deactivate` 除外），非只读操作需确认用户意图。**
+**CRITICAL — 本 Skill 为只读操作。CI 激活/关闭需通过 GitLink Web 界面操作，CLI 不提供对应命令。**
 **CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

 > **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
@ -34,11 +34,24 @@ metadata:

 ### Step 1：检查 CI 授权状态

+**方法 1（推荐）**：通过 `repo +info` 查看 `open_devops` 字段：
+
 ```bash
-gitlink-cli ci +authorize --owner <owner> --repo <repo> --format json
+gitlink-cli repo +info --owner <owner> --repo <repo> --format json
 ```

-判断 CI 是否已激活。若未激活，报告中说明"CI 未启用"，建议执行 `ci +activate`。
+- `"open_devops": true` → CI 已激活
+- `"open_devops": false` → CI 未激活
+
+**方法 2**：直接调用 `ci +builds`，CI 未激活时返回：
+
+```json
+{"status": -1, "message": "接口数据异常"}
+```
+
+> ⚠️ `ci +authorize` 命令在当前 CLI 版本（v0.1.18）中**不存在**。可用 CI 命令仅：`+builds`、`+logs`、`+restart`、`+stop`。
+
+若 CI 未激活，报告中说明"CI 未启用"，建议通过 GitLink Web 界面（仓库设置 → DevOps）开启，随后不再继续后续步骤。

 ### Step 2：获取构建历史

@ -146,7 +159,7 @@ gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build_id> --format j

 <!-- 根据分析结果，从以下列表中选择匹配的建议输出 -->

- **立即激活 CI**（当 CI 未激活时）：执行 `gitlink-cli ci +activate --owner <owner> --repo <repo>`
+- **立即激活 CI**（当 CI 未激活时）：前往 GitLink Web 界面 → 仓库设置 → DevOps 开启 CI/CD 服务（CLI 暂不支持 `ci +activate`）
 - **提升成功率**（当 success_rate < 80% 时）：优先修复高频失败原因
 - **增加构建频率**（当构建频率评分 < 2 时）：建议每次 push 触发 CI
 - **缩短修复时间**（当修复速度评分 < 2 时）：建立 CI 失败告警
@ -158,7 +171,7 @@ gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build_id> --format j

 | 场景 | 处理方式 |
 |------|----------|
-| CI 未激活 | 报告 CI 状态为"未激活"，给出激活命令建议，不再继续后续步骤 |
+| CI 未激活 | 报告 CI 状态为"未激活"，建议通过 Web 界面开启，不再继续后续步骤 |
 | 无构建记录 | 标注"仓库暂无 CI 构建记录" |
 | `ci +logs` 返回空 | 标注"日志不可用" |
 | 构建总数 < 5 | 样本量不足，标注"数据有限，统计不具代表性" |
@ -168,8 +181,9 @@ gitlink-cli ci +logs --owner <owner> --repo <repo> --build <build_id> --format j
 ## 注意事项

 - ✅ **所有命令使用 `--format json`**，确保可解析
- ✅ **`ci +activate` 和 `+deactivate` 为写操作**，执行前需确认用户意图
+- ✅ **CI 激活/关闭需通过 GitLink Web 界面**，CLI 不提供 `+activate`/`+deactivate` 命令
 - ✅ **Owner/repo 优先从 `git remote` 自动解析**
 - ⚠️ **`ci +logs` 输出可能很大**，仅提取关键错误行
 - ⚠️ **构建历史无分页参数**，实际返回条数取决于 API
 - ⚠️ **CI 数据仅反映 GitLink 平台活动**，不包括第三方 CI 服务
+- ⚠️ **`repo +info` 的 `open_devops` 字段**是判断 CI 是否激活的最可靠方式
--- a/skills/gitlink-contributor-insight/EXAMPLES.md
+++ b/skills/gitlink-contributor-insight/EXAMPLES.md
@ -0,0 +1,239 @@
+# gitlink-contributor-insight 使用样例
+
+## 样例 1：直接调用 Skill（手动执行）
+
+**日期**：2026-06-03
+**仓库**：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
+**CLI 版本**：gitlink-cli 0.1.18
+
+### 执行流程
+
+```bash
+# Step 1: 获取仓库信息
+gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
+# → contributor_users_count: 2, pull_requests_count: 9, issues_count: 0
+# → fork_info: { fork_project_user_login: "Gitlink" }
+
+# Step 2: 获取 PR 列表（替代不存在的 repo +contributors）
+gitlink-cli pr +list --owner jiangtx --repo gitlink-cli --format json
+# → 9 个 PR，全部已合并
+# → 唯一 author_login: lindiwen23 (5 PRs), jiangtx (4 PRs)
+
+# Step 3: 获取用户信息
+gitlink-cli user +info --login jiangtx --format json
+# → 注册于 2026-04-28，3 个项目，身份"专业人士"
+
+gitlink-cli user +info --login lindiwen23 --format json
+# → 注册于 2025-05-26，6 个项目，1 个组织，身份"专业人士"
+
+# Step 4: 获取 Issue 列表（补充数据）
+gitlink-cli issue +list --owner jiangtx --repo gitlink-cli --format json
+# → 0 个 Issue
+```
+
+### 不可用命令确认
+
+| 命令 | 结果 |
+|------|------|
+| `gitlink-cli repo +contributors` | 命令不存在，返回 repo 帮助文本 |
+| `gitlink-cli user +heatmap` | 命令不存在（user 子命令仅 `+info` / `+me`） |
+| `gitlink-cli user +stats` | 命令不存在 |
+| `gitlink-cli user +trends` | 命令不存在 |
+| `gitlink-cli api GET "/api/v1/repos/.../contributors"` | 返回 HTML 页面，非 JSON |
+| `gitlink-cli api GET "/api/v1/users/.../heatmap"` | 返回 HTML 页面，非 JSON |
+
+### 关键发现
+
+**贡献者数据（从 PR 列表提取）：**
+
+| 贡献者 | PR 数 | 活跃日期 | 活跃天数 | 趋势 |
+|--------|-------|----------|----------|------|
+| lindiwen23 | 5 | 06-01, 06-03 | 2 天 | ↑ |
+| jiangtx | 4 | 06-02, 06-03 | 2 天 | ↑ |
+
+**PR 时间分布：**
+- 06-01: 1 PR（lindiwen23 #1）
+- 06-02: 2 PRs（jiangtx #2, #3）
+- 06-03: 6 PRs（jiangtx #4, #5 + lindiwen23 #6, #7, #8, #9）
+
+**分级处理：** 项目仅 3 天历史，适用"年轻项目放宽标准"规则，2 人均标记为 🔥 核心贡献者。
+
+### 生成的报告
+
+```markdown
+# 👥 贡献者洞察报告：gitlink-cli
+
+> 分析时间：2026-06-03 10:00 (UTC+8)
+> 仓库：jiangtx/gitlink-cli（Fork from Gitlink/gitlink-cli）
+> 总贡献者：2 人，本次分析：2 人（全量分析）
+
+## 一、团队概览
+
+| 指标 | 数值 |
+|------|------|
+| 总贡献者 | 2 |
+| 🔥 核心贡献者 | 2 |
+| 🌟 活跃贡献者 | 2 |
+| 🌱 新兴贡献者 | 0 |
+| 💤 休眠贡献者 | 0 |
+| 近 30 天活跃率 | 100% |
+| 仓库总 PR 数 | 9（全部已合并） |
+| 仓库总 Issue 数 | 0 |
+| 项目启动时间 | 2026-06-01（3 天前） |
+
+## 二、贡献者活跃度排行榜
+
+| 排名 | 贡献者 | 级别 | 类型 | 活跃天数 | 总PR | 总Issue | 趋势 |
+|------|--------|------|------|---------|------|---------|------|
+| 1 | lindiwen23 | 🔥 | 代码 | 2 天 | 5 | 0 | ↑ |
+| 2 | jiangtx | 🔥 | 代码 | 2 天 | 4 | 0 | ↑ |
+
+## 三、重点贡献者分析
+
+### 🔥 lindiwen23（核心贡献者）
+- 5 个 PR（3 feat + 1 fix + 1 refactor），集中上午时段
+- 6/3 当天 43 分钟内连续提交 4 个 PR，集中爆发型节奏
+- 平台老用户（2025-05-26 注册），6 个项目经验
+
+### 🔥 jiangtx（核心贡献者 / Owner）
+- 4 个 PR（3 feat + 1 fix），下午至深夜时段
+- 从基础设施修复 → 模块补全，有序推进型节奏
+- 平台新用户（2026-04-28 注册），项目 Owner
+
+## 四、团队健康度评估
+
+| 指标 | 状态 | 说明 |
+|------|------|------|
+| 核心贡献者占比 | 100% | 2/2 活跃 |
+| 近 30 天活跃率 | 100% | 全部近期有贡献 |
+| 知识分散度 | ⚠️ Bus Factor = 2 | 人数偏少 |
+| 贡献稳定性 | ⚠️ 仅 3 天数据 | 无法评估长期 |
+
+### 风险提示
+- ⚠️ 核心贡献者不足（2 人），Bus Factor = 2
+- ℹ️ 项目处于早期阶段（3 天），风险置信度有限
+- ⚠️ 缺少新鲜血液，0 个外部 Issue
+
+## 五、社区建设建议
+
+1. 保持当前协作节奏（独立分支 + PR 合并）
+2. 建立 Issue 文化，添加 Good First Issue 标签
+3. 在 GitLink 平台推广，完善使用文档
+4. 完善代码注释，降低 Bus Factor 风险
+5. 定期同步上游（Gitlink/gitlink-cli）
+
+## 📋 数据来源与局限性
+
+| 数据维度 | 来源 | 可靠性 |
+|----------|------|--------|
+| 贡献者数量 | repo +info | ✅ 可靠 |
+| PR 贡献数据 | pr +list 全量 | ✅ 可靠 |
+| 用户信息 | user +info | ✅ 可靠 |
+| 贡献热力图 | 不可用（命令未实现） | ❌ 缺失 |
+| 统计信息 | 不可用（命令未实现） | ❌ 缺失 |
+| 趋势数据 | PR 时间序列推算 | ⚠️ 推算 |
+```
+
+---
+
+## 样例 2：通过 Agent 调用 Skill（自动执行）
+
+**日期**：2026-06-03
+**仓库**：jiangtx/gitlink-cli
+**调用方式**：`Agent(subagent_type="general-purpose", prompt="调用 gitlink-contributor-insight skill，分析一下 jiangtx/gitlink-cli 的贡献者活跃度。")`
+
+### Agent 自主执行的命令序列
+
+```
+工具调用 1: gitlink-cli repo +info --owner jiangtx --repo gitlink-cli --format json
+           → contributor_users_count: 2, pull_requests_count: 9
+
+工具调用 2: gitlink-cli pr +list --owner jiangtx --repo gitlink-cli --format json
+           → 9 PRs, 提取 author_login: lindiwen23(5), jiangtx(4)
+
+工具调用 3: gitlink-cli issue +list --owner jiangtx --repo gitlink-cli --format json
+           → 0 issues
+
+工具调用 4: gitlink-cli user +info --login jiangtx --format json
+           → 注册 2026-04-28, 3 个项目
+
+工具调用 5: gitlink-cli user +info --login lindiwen23 --format json
+           → 注册 2025-05-26, 6 个项目, 1 个组织
+```
+
+### Agent 决策过程
+
+Agent 读取 skill 后，**正确遵循了更新后的工作流**：
+
+1. **未尝试 `repo +contributors`**：skill 的"命令可用性声明"表标注该命令不可用
+2. **未尝试 `user +heatmap/+stats/+trends`**：skill 标注不可用，直接从 PR 列表推算
+3. **未尝试 Raw API**：skill 不推荐此路径，全程使用 Shortcut 命令
+4. **正确应用"年轻项目"规则**：识别项目仅 3 天，放宽分级标准，2 人均标记为 🔥 核心
+5. **自主增强分析**：Agent 额外分析了工作时段偏好、PR 类型统计、新老比例
+
+共消耗 **5 次 CLI 调用**，**41,312 tokens**，耗时 **77.5 秒**。
+
+### Agent 相对于手动执行的改进
+
+| 维度 | 手动执行 | Agent 执行 |
+|------|----------|-----------|
+| 工作节奏分析 | 仅按日期统计 | 识别出时段偏好（上午 vs 深夜） |
+| PR 类型统计 | 未分类 | feat(6) + fix(3) + refactor(1) |
+| 新老比例 | 未计算 | 1:1（jiangtx 1 月 vs lindiwen23 1 年+） |
+| 贡献者建议 | 通用建议 | 建议为 lindiwen23 授予更高级别权限 |
+| 协作模式 | 分支策略分析 | 新增独立分支 + PR 合并模式分析 |
+
+### Agent 生成的报告摘要
+
+Agent 生成了完整的五段式报告（团队概览 → 排行榜 → 个人分析 → 健康度评估 → 建议），结构与我手动执行一致，但细节更丰富：
+
+- **lindiwen23 分析**：增加了"3 feat + 1 fix + 1 refactor"分类、"上午 9:00-11:30 时段偏好"、"集中爆发型节奏"
+- **jiangtx 分析**：增加了"先修复基础设施，再逐步补全功能模块"的有序推进评价
+- **健康度评估**：增加了新老比例 1:1 分析，指出两人经验互补
+- **建议**：更具体，如"为 lindiwen23 授予更高级别权限"、"编写 CONTRIBUTING.md"
+
+### 验证结论
+
+✅ skill v1.1.0 验证通过：
+- Agent 正确遵循了"命令可用性声明"，未尝试不可用命令
+- Agent 正确从 `pr +list` 提取贡献者数据（替代不存在的 `repo +contributors`）
+- Agent 正确从 PR 时间戳推算活跃天数（替代不存在的 `user +heatmap`）
+- Agent 正确从 PR 聚合获得产出量（替代不存在的 `user +stats`）
+- Agent 正确从 PR 时间分布判断趋势（替代不存在的 `user +trends`）
+- Agent 正确应用"年轻项目放宽标准"规则
+- Agent 正确标注数据来源局限性
+- Agent 未使用 `gh` 或其他平台工具
+- 报告结构完整，覆盖所有必需章节
+
+---
+
+## 异常场景速查
+
+| 场景 | 检测方式 | 数据表现 | 处理 |
+|------|----------|----------|------|
+| `repo +contributors` 不可用 | 命令返回帮助文本 | 无 `+contributors` 子命令 | 从 `pr +list` 提取 `author_login` |
+| `user +heatmap` 不可用 | 命令不存在 | user 仅 `+info`/`+me` | 从 PR 时间戳推算活跃天数 |
+| `user +stats` 不可用 | 命令不存在 | 同上 | 从 `pr +list` 聚合 PR/Issue 数 |
+| `user +trends` 不可用 | 命令不存在 | 同上 | 从 PR 按日聚合判断趋势 |
+| Raw API 返回 HTML | `api GET` 返回 HTML | 非 JSON 响应 | 仅使用 Shortcut 命令 |
+| 项目 < 30 天 | PR 时间跨度 < 30 天 | 全部 PR 在近期 | 放宽分级标准，标注"早期阶段" |
+| 贡献者 ≤ 2 人 | `contributor_users_count` ≤ 2 | Bus Factor 极低 | 报告标注风险 + 提供吸引新人建议 |
+| PR 数为 0 | `pr +list` 空数组 | `issues: []` | 标注"仓库暂无 PR 数据" |
+| Issue 数为 0 | `issue +list` 空数组 | `issues_count: 0` | 贡献类型统一标注"代码贡献者" |
+
+---
+
+## 版本兼容性说明
+
+本 skill 基于 `gitlink-cli 0.1.18` 编写。不同版本的可用命令可能有差异：
+
+| CLI 版本 | 贡献者分析可用命令 | 缺失命令 |
+|----------|-------------------|----------|
+| 0.1.18 | `repo +info`, `pr +list`, `issue +list`, `user +info` | `repo +contributors`, `user +heatmap`, `user +stats`, `user +trends` |
+| 未来版本 | 可能新增 `user +heatmap` 等 | — |
+
+当 CLI 版本更新后，重新验证可用命令：
+```bash
+gitlink-cli repo --help
+gitlink-cli user --help
+```
--- a/skills/gitlink-contributor-insight/SKILL.md
+++ b/skills/gitlink-contributor-insight/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: gitlink-contributor-insight
-version: 1.0.0
+version: 1.1.0
 description: "贡献者活跃度分析：分析仓库贡献者的活跃度、贡献趋势和工作节奏，生成贡献者洞察报告。当用户需要分析贡献者活跃度、查看团队贡献趋势、评估成员参与度时触发。"
 metadata:
  requires:
@ -18,62 +18,91 @@ metadata:

 ---

+## ⚠️ 命令可用性声明
+
+gitlink-cli 的命令集在持续演进中。以下命令**当前版本可能不可用**，执行前先验证：
+
+| 命令 | 状态 | 替代方案 |
+|------|------|----------|
+| `repo +contributors` | ❌ 不可用 | 从 `pr +list` 提取 `author_login` + `repo +info` 获取 `contributor_users_count` |
+| `user +heatmap` | ❌ 不可用 | 从 PR 时间戳手动推算活跃天数 |
+| `user +stats` | ❌ 不可用 | 从 `pr +list` 统计 PR 数；Issue 数通过 `issue +list` 获取 |
+| `user +trends` | ❌ 不可用 | 从 PR 时间分布手动判断趋势（上升/平稳/下降） |
+| `repo +info` | ✅ 可用 | — |
+| `pr +list` | ✅ 可用 | — |
+| `user +info` | ✅ 可用 | — |
+| `issue +list` | ✅ 可用 | — |
+
+> **核心原则**：优先使用可用的 Shortcut 命令。当所需命令不可用时，从 `pr +list` 和 `user +info` 中提取等效数据，并在报告中标注"数据来源：PR 列表（命令 X 不可用）"。
+
+---
+
 ## 功能概述

 面向开源社区管理者和维护者的贡献者分析工具：

-1. **项目概览** — 获取仓库贡献者规模
-2. **贡献热力图分析** — 通过 `user +heatmap` 查看贡献节奏
-3. **统计数据提取** — 通过 `user +stats` 获取个人统计
-4. **趋势分析** — 通过 `user +trends` 查看项目趋势
+1. **项目概览** — 获取仓库贡献者规模和基本信息
+2. **贡献数据分析** — 通过 `pr +list` 提取每位贡献者的 PR 数量和时间分布
+3. **用户画像** — 通过 `user +info` 了解贡献者背景
+4. **趋势判断** — 从 PR 时间序列推断贡献趋势
 5. **洞察报告** — 生成贡献者活跃度排名和团队健康度评估

 ---

 ## 工作流：贡献者分析全流程

-### Step 1：获取项目贡献者列表
-
-```bash
-gitlink-cli repo +contributors --owner <owner> --repo <repo> --format json
-```
-
-> 如果仓库贡献者数量较多（>15），按 `repo +contributors` 返回中 `commits_count` 降序排列，取前 10 位分析。如 `commits_count` 缺失，按返回的自然顺序取前 10 位，报告中注明"基于返回顺序 Top 10"。
-
-提取每个贡献者的 `login`（用户名）。
-
-### Step 2：获取仓库基本信息
+### Step 1：获取仓库基本信息

 ```bash
 gitlink-cli repo +info --owner <owner> --repo <repo> --format json
 ```

-提取 `contributor_users_count`、`full_name`、`description`。
+提取：`contributor_users_count`、`full_name`、`description`、`default_branch`、`fork_info`（如为 Fork 项目）。
+
+### Step 2：获取贡献者列表（通过 PR 数据）
+
+由于 `repo +contributors` 不可用，改用两步获取贡献者：
+
+```bash
+# 2a. 获取所有 PR（含已合并和已关闭）
+gitlink-cli pr +list --owner <owner> --repo <repo> --format json
+
+# 2b. 如果 Issue 数据也需要
+gitlink-cli issue +list --owner <owner> --repo <repo> --format json
+```
+
+从 `pr +list` 返回数据中：
+- 提取所有唯一的 `author_login` 作为实际代码贡献者
+- 统计每位作者的 PR 数（`pull_request_status`: 0=open, 1=merged, 2=closed）
+- 记录每个 PR 的 `pr_full_time` 用于时间分析
+- 记录每个 PR 的 `journals_count`（评论/审核活动数）
+
+从 `issue +list` 返回数据中：
+- 提取所有唯一的 `author_login` 作为 Issue 参与者
+- 统计每位作者的 Issue 数
+
+> 如果 PR 数量较多（>50），按 `author_login` 聚合后取 PR 数前 10 的贡献者分析，报告中注明"基于 Top 10 分析"。

 ### Step 3：逐位贡献者深度分析

-对每位贡献者执行以下命令：
+对每位贡献者执行：

 ```bash
-# 热力图（最近一年的贡献日历）
-gitlink-cli user +heatmap --login <username> --format json
-
-# 统计信息（PR/Issue/Commit 数量）
-gitlink-cli user +stats --login <username> --format json
-
-# 项目趋势
-gitlink-cli user +trends --login <username> --format json
+# 用户基本信息
+gitlink-cli user +info --login <username> --format json
 ```

-从返回数据中提取：
+从 `user +info` 提取：`login`、`name`、`created_time`（注册时间）、`user_projects_count`、`user_org_count`、`user_identity`。

-| 维度 | 来源命令 | 分析要点 |
+**如果 `user +heatmap/+stats/+trends` 可用**（未来版本），补充执行。当前版本用以下替代方案：
+
+| 维度 | 替代数据源 | 分析要点 |
 |------|----------|----------|
-| 贡献频率 | `+heatmap` | 最近 1/3/6/12 个月有贡献的天数，判断是"持续贡献者"还是"间歇参与者" |
-| 贡献产出 | `+stats` | PR 数、Issue 数、Commit 数，区分"代码贡献者"和"问题反馈者" |
-| 活跃趋势 | `+trends` | 贡献量是上升/稳定/下降，识别"上升期贡献者"和"逐渐淡出者" |
+| 贡献频率 | PR 时间戳列表 | 统计活跃天数、相邻 PR 间隔、判断"持续贡献者"还是"间歇参与者" |
+| 贡献产出 | `pr +list` 聚合 | PR 数、Issue 数，区分"代码贡献者"和"问题反馈者" |
+| 活跃趋势 | PR 按日/周聚合 | 贡献量上升/稳定/下降，识别"上升期贡献者"和"逐渐淡出者" |

-> ⚠️ **控制 API 调用**：贡献者 >15 人时，仅分析 Step 1 中按 `commits_count` 排序后的前 10 位。每人最多 3 次 API 调用（heatmap + stats + trends，共 ≤30 次）。
+> ⚠️ **控制 API 调用**：贡献者 >15 人时，仅分析 PR 数最高的前 10 位。每人 1 次 `user +info` 调用（共 ≤10 次），PR 数据已在 Step 2 全量获取。

 ### Step 4：贡献者分级与分类

@ -81,21 +110,25 @@ gitlink-cli user +trends --login <username> --format json

 | 级别 | 判定标准 |
 |------|----------|
-| 🔥 **核心贡献者** | 最近 30 天有贡献 + 总贡献 PR > 10 |
-| 🌟 **活跃贡献者** | 最近 60 天有贡献 + 总贡献 > 5 |
+| 🔥 **核心贡献者** | 最近 30 天有贡献 + 总贡献 PR ≥ 5（或总贡献 PR > 10） |
+| 🌟 **活跃贡献者** | 最近 60 天有贡献 + 总贡献 ≥ 3 |
 | 🌱 **新兴贡献者** | 最近 90 天首次出现 + 贡献频率上升 |
 | 💤 **休眠贡献者** | 最近 90 天无贡献 + 历史有贡献 |

+> **年轻项目特殊处理**：项目历史 < 30 天时，放宽标准——所有活跃贡献者均可标记为核心贡献者，报告中注明"项目处于早期阶段，分级标准已放宽"。
+
 #### 4.2 贡献类型分类

 | 类型 | 判定 |
 |------|------|
-| **代码贡献者** | PR/Commit 数量占比最高 |
-| **问题反馈者** | Issue 数量占比最高 |
-| **全能贡献者** | PR 和 Issue 数量均衡 |
+| **代码贡献者** | PR 数量 > Issue 数量 |
+| **问题反馈者** | Issue 数量 > PR 数量 |
+| **全能贡献者** | PR 和 Issue 数量均衡（差异 ≤ 1） |

 ### Step 5：生成贡献者洞察报告

+按下方输出模板生成报告，并根据数据可用性灵活调整章节。
+
 ---

 ## 输出模板
@ -124,9 +157,9 @@ gitlink-cli user +trends --login <username> --format json

 ## 二、贡献者活跃度排行榜

-| 排名 | 贡献者 | 级别 | 类型 | 近30天贡献 | 总PR | 总Issue | 趋势 |
-|------|--------|------|------|-----------|------|---------|------|
-| 1 | {{login}} | 🔥 | 代码 | {{d30}} 天 | {{pr_count}} | {{issue_count}} | ↑ |
+| 排名 | 贡献者 | 级别 | 类型 | 活跃天数 | 总PR | 总Issue | 趋势 |
+|------|--------|------|------|---------|------|---------|------|
+| 1 | {{login}} | 🔥 | 代码 | {{d}} 天 | {{pr_count}} | {{issue_count}} | ↑ |
 | ... | ... | ... | ... | ... | ... | ... | ... |

 ---
@ -139,11 +172,17 @@ gitlink-cli user +trends --login <username> --format json

 | 维度 | 数据 | 说明 |
 |------|------|------|
-| 最近 30 天贡献 | {{d30}} 天 | {{评价}} |
+| 活跃天数 | {{d}} 天 | {{评价}} |
 | 总 PR 数 | {{pr_count}} | |
 | 总 Issue 数 | {{issue_count}} | |
 | 贡献趋势 | {{trend_direction}} | {{trend_comment}} |

+**PR 贡献明细**：（可选，数据充足时展示）
+
+| PR# | 标题 | 日期 | 类型 |
+|-----|------|------|------|
+| ... | ... | ... | feat/fix/refactor |
+
 ---

 ## 四、团队健康度评估
@ -159,21 +198,12 @@ gitlink-cli user +trends --login <username> --format json

 ### 风险提示

-<!-- 根据分析结果，从以下列表中选择匹配的风险项输出 -->
-
 - ⚠️ **核心贡献者不足**（当 core_count < 3 时）：仅 {{core_count}} 位核心贡献者，存在单点依赖风险（Bus Factor = {{core_count}}）。
 - ⚠️ **贡献者流失**（当 dormant_rate > 50% 时）：超过一半的贡献者已不活跃，需要关注社区留存。
 - ⚠️ **缺少新鲜血液**（当 new_count == 0 时）：近期无新兴贡献者，建议通过 Good First Issue 等方式吸引新人。
+- ℹ️ **项目处于早期阶段**（当项目历史 < 30 天时）：贡献者分级标准已放宽，以上风险置信度有限。
 - ✅ **团队健康**（当以上情况均不满足时）：贡献者结构合理，团队运转良好。

-> 指标计算：
-> - `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`：判断标准为"贡献标准差"（各月贡献量波动小=高稳定性，波动大=低稳定性）
-
 ---

 ## 五、社区建设建议
@ -182,6 +212,22 @@ gitlink-cli user +trends --login <username> --format json
 2. **激活休眠贡献者**：{{休眠贡献者召回建议}}
 3. **吸引新贡献者**：{{新贡献者吸引建议}}
 4. **平衡贡献类型**：{{贡献类型平衡建议}}
+
+---
+
+## 📋 数据来源与局限性
+
+| 数据维度 | 来源 | 可靠性 |
+|----------|------|--------|
+| 贡献者数量 | `repo +info` | ✅ 可靠 |
+| PR 贡献数据 | `pr +list` 全量 | ✅ 可靠 |
+| Issue 数据 | `issue +list` | ✅ 可靠 |
+| 用户信息 | `user +info` | ✅ 可靠 |
+| 贡献热力图 | 不可用（命令未实现） | ❌ 缺失 |
+| 统计信息 | 不可用（命令未实现） | ❌ 缺失 |
+| 趋势数据 | 不可用（命令未实现） | ❌ 缺失 |
+
+> **局限性**：本报告仅反映 GitLink 平台活动，不包括其他平台（GitHub、GitLab 等）的数据。
 ```

 ---
@ -190,10 +236,13 @@ gitlink-cli user +trends --login <username> --format json

 | 场景 | 处理方式 |
 |------|----------|
-| `repo +contributors` 返回空 | 标注"仓库暂无贡献者数据"，仅从 `repo +info` 获取 `contributor_users_count` |
-| `user +heatmap` 返回空 | 标注"无热力图数据"，评分仅基于 stats 和 trends |
-| `user +stats` / `+trends` 返回错误 | 跳过该维度，标注"数据不可用" |
-| 贡献者 > 15 人 | 仅分析贡献量最高的前 10 位，报告中注明"基于 Top 10 分析" |
+| `repo +contributors` 不可用（当前版本常态） | 从 `pr +list` 的 `author_login` 提取贡献者列表 |
+| `user +heatmap` / `+stats` / `+trends` 不可用 | 从 PR 时间戳推算活跃天数，PR 聚合得产出量，时间分布得趋势 |
+| `pr +list` 返回空 | 标注"仓库暂无 PR 数据"，仅展示 `repo +info` 基本信息 |
+| `user +info` 返回空 | 标注"用户信息不可用"，仅展示 PR 统计 |
+| 贡献者 > 15 人 | 仅分析 PR 数最高的前 10 位，报告中注明"基于 Top 10 分析" |
+| 项目历史 < 30 天 | 放宽分级标准，报告中注明"项目处于早期阶段" |
+| `issue +list` 返回空 | Issue 数列为 0，贡献类型统一标注"代码贡献者" |

 ---

@ -202,6 +251,7 @@ gitlink-cli user +trends --login <username> --format json
 - ✅ **所有命令使用 `--format json`**，确保可解析
 - ✅ **本 Skill 为纯只读分析**，不会修改任何仓库
 - ✅ **Owner/repo 优先从 `git remote` 自动解析**，无 git 上下文时询问用户
- ⚠️ **每人 3 次 API 调用**（heatmap + stats + trends），10 人即 30 次，注意控制分析人数
- ⚠️ **热力图数据可能稀疏**：部分贡献者数据不完整，标注"数据有限"
+- ⚠️ **核心数据来源为 `pr +list`**：当前版本 gitlink-cli 中 `user +heatmap/+stats/+trends` 不可用，分析主要依赖 PR 列表数据
+- ⚠️ **`repo +contributors` 不可用**：贡献者列表从 PR 作者提取，可能与实际 `contributor_users_count` 有差异（后者包含未提 PR 的参与者）
 - ⚠️ **数据仅反映 GitLink 平台活动**：不包括 GitHub 或其他平台的数据
+- ℹ️ **参照样例**：[`EXAMPLES.md`](EXAMPLES.md) 包含手动执行和 Agent 调用两种场景的完整样例，[`examples/jiangtx-gitlink-cli.md`](examples/jiangtx-gitlink-cli.md) 包含原始命令输出数据
--- a/skills/gitlink-contributor-insight/examples/jiangtx-gitlink-cli.md
+++ b/skills/gitlink-contributor-insight/examples/jiangtx-gitlink-cli.md
@ -0,0 +1,201 @@
+# 执行样例：jiangtx/gitlink-cli 贡献者活跃度分析
+
+> 执行日期：2026-06-03
+> 执行版本：gitlink-cli (当前版本)
+> 说明：本文件记录了一次完整的贡献者分析执行过程，包含实际命令输出和最终报告。可作为后续分析的参考模板。
+
+---
+
+## 实际执行的命令与输出
+
+### 1. `gitlink-cli repo +info`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "author": { "id": 148911, "login": "jiangtx", "name": "jiangtx" },
+    "clone_url": "https://gitlink.org.cn/jiangtx/gitlink-cli.git",
+    "contributor_users_count": 2,
+    "default_branch": "master",
+    "fork_info": {
+      "fork_form_name": "gitlink-cli",
+      "fork_project_identifier": "gitlink-cli",
+      "fork_project_user_login": "Gitlink",
+      "fork_project_user_name": "GitLink"
+    },
+    "forked_from_project_id": 1513956,
+    "full_name": "jiangtx/gitlink-cli",
+    "identifier": "gitlink-cli",
+    "issues_count": 0,
+    "permission": "Manager",
+    "private": false,
+    "project_id": 1547588,
+    "pull_requests_count": 9,
+    "size": "13.4 MB",
+    "watchers_count": 0
+  }
+}
+```
+
+### 2. `gitlink-cli pr +list` (关键数据源)
+
+9 个 PR，全部已合并。按作者汇总：
+
+| author_login | PR 数 | PR 编号 | 时间范围 |
+|-------------|--------|---------|----------|
+| lindiwen23 | 5 | #1, #6, #7, #8, #9 | 2026-06-01～06-03 |
+| jiangtx | 4 | #2, #3, #4, #5 | 2026-06-02～06-03 |
+
+PR 详细列表：
+
+```json
+// lindiwen23 的 PR
+{ "pull_request_number": 1, "author_login": "lindiwen23",
+  "name": "feat: 新增 3 个 Skill（onboarding / issue-triage / research-tracker）",
+  "pr_full_time": "2026-06-01T11:33:00.000+08:00", "pull_request_status": 1,
+  "journals_count": 3 }
+
+{ "pull_request_number": 6, "author_login": "lindiwen23",
+  "name": "fix: detectHTMLResponse 跳过 XML 声明，添加 HTML 响应检测",
+  "pr_full_time": "2026-06-03T08:55:10.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 7, "author_login": "lindiwen23",
+  "name": "feat: org +teams/+create-team/+remove-user, search +code/+issues",
+  "pr_full_time": "2026-06-03T09:13:15.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 8, "author_login": "lindiwen23",
+  "name": "feat: 新建 notification 模块并注册",
+  "pr_full_time": "2026-06-03T09:17:32.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 9, "author_login": "lindiwen23",
+  "name": "fix: Skills 文件 api 命令替换为 Shortcut 命令 (~107 处)",
+  "pr_full_time": "2026-06-03T09:38:05.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+// jiangtx 的 PR
+{ "pull_request_number": 2, "author_login": "jiangtx",
+  "name": "基础设施修复",
+  "pr_full_time": "2026-06-02T16:54:43.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 3, "author_login": "jiangtx",
+  "name": "repo 域补全",
+  "pr_full_time": "2026-06-02T23:27:46.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 4, "author_login": "jiangtx",
+  "name": "pr 域补全",
+  "pr_full_time": "2026-06-03T00:09:46.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+
+{ "pull_request_number": 5, "author_login": "jiangtx",
+  "name": "label 模块新建",
+  "pr_full_time": "2026-06-03T00:25:32.000+08:00", "pull_request_status": 1,
+  "journals_count": 2 }
+```
+
+### 3. `gitlink-cli user +info --login jiangtx`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "login": "jiangtx", "name": "jiangtx",
+    "user_id": 148911,
+    "created_time": "2026-04-28 11:46",
+    "user_projects_count": 3,
+    "user_org_count": 0,
+    "user_identity": "专业人士"
+  }
+}
+```
+
+### 4. `gitlink-cli user +info --login lindiwen23`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "login": "lindiwen23", "name": "lindiwen23",
+    "user_id": 141609,
+    "created_time": "2025-05-26 22:40",
+    "user_projects_count": 6,
+    "user_org_count": 1,
+    "user_identity": "专业人士"
+  }
+}
+```
+
+### 5. 不可用的命令
+
+| 命令 | 结果 |
+|------|------|
+| `gitlink-cli repo +contributors` | 命令不存在，返回 repo 帮助文本 |
+| `gitlink-cli user +heatmap` | 命令不存在（user 仅 `+info` / `+me`） |
+| `gitlink-cli user +stats` | 命令不存在 |
+| `gitlink-cli user +trends` | 命令不存在 |
+| `gitlink-cli api GET "/api/v1/repos/.../contributors"` | 返回 HTML 页面，非 JSON |
+| `gitlink-cli api GET "/api/v1/users/.../heatmap"` | 返回 HTML 页面，非 JSON |
+
+---
+
+## 数据处理过程
+
+### 贡献者发现
+
+由于 `repo +contributors` 不可用：
+1. 从 `repo +info` 获取 `contributor_users_count = 2`
+2. 从 `pr +list` 提取唯一 `author_login`：`["lindiwen23", "jiangtx"]`（2 人，一致）
+
+### 活跃天数计算
+
+从 PR 的 `pr_full_time` 字段提取日期：
+
+| 贡献者 | 活跃日期 | 活跃天数 |
+|--------|----------|----------|
+| lindiwen23 | 2026-06-01, 2026-06-03 | 2 天 |
+| jiangtx | 2026-06-02, 2026-06-03 | 2 天 |
+
+### 趋势判断
+
+按日聚合 PR 数：
+- 06-01: 1 PR
+- 06-02: 2 PRs
+- 06-03: 6 PRs
+
+趋势：↑ 上升（日产出加速：1→2→6）
+
+### 贡献类型分类
+
+| 贡献者 | PR 数 | Issue 数 | 类型 |
+|--------|-------|----------|------|
+| lindiwen23 | 5 | 0 | 代码贡献者 |
+| jiangtx | 4 | 0 | 代码贡献者 |
+
+> Issue 来源：`repo +info` 中 `issues_count = 0`，无 Issue 需要获取。
+
+### 分级调整
+
+由于项目仅 3 天历史（< 30 天），适用年轻项目特殊处理：
+- jiangtx（PR=4，2 活跃天）→ 🔥 核心贡献者
+- lindiwen23（PR=5，2 活跃天）→ 🔥 核心贡献者
+
+---
+
+## 完整输出报告
+
+（见当天执行输出，此处省略以保持文件精简。核心结构：团队概览 → 排行榜 → 个人分析 → 健康度评估 → 建议。）
+
+---
+
+## 经验总结
+
+1. **PR 数据可作为贡献者分析的主要数据源**：`pr +list` 提供了作者、时间、状态、标题等丰富信息
+2. **`pr_full_time` 字段足够做时间分布分析**：可计算活跃天数、贡献频率、趋势
+3. **`user +info` 补充贡献者画像**：注册时间、项目数、组织数可用于背景分析
+4. **极端年轻项目的分级需放宽**：标准分级（PR > 10）对 3 天项目不适用
+5. **Raw API 不可靠**：GitLink 的 API 结构与标准 Gitea 不同，建议仅使用 Shortcut 命令