gitlink-cli/skills/gitlink-health/examples/full-workflow.md

项目健康度报告 — 完整生成示例

前置条件： 先阅读 ../../gitlink-shared/SKILL.md 了解认证、全局参数和安全规则。 适用场景： AI Agent 端到端生成项目健康度报告，以 zzx-coder/gitlink-cli 为例。

完整流程

第一步：收集 Issue 数据

# 获取未关闭 Issue
gitlink-cli issue +list --state open --format json

# 获取已关闭 Issue
gitlink-cli issue +list --state closed --format json

# AI 从返回中提取：
# - open count: 28
# - closed count: 1 (我们之前创建的 #29，已关闭)
# - priority 分布: 大部分为 normal (priority_id=2)
# - 平均关闭时间: #29 创建后约 1 分钟关闭（测试 issue）

第二步：收集 PR 数据

# 获取未合并 PR
gitlink-cli pr +list --state open --format json

# 获取已合并 PR
gitlink-cli pr +list --state merged --format json

# AI 从返回中提取：
# - merged count: 10
# - open count: 0
# - 合并率: 10/11 = 91%
# - 最新合并 PR: #11 (2026-06-04)
# - PR 平均合并时间需逐条计算

第三步：收集贡献者统计

# Raw API 获取贡献者数据
gitlink-cli api GET /:owner/:repo/contributors --format json

# AI 从返回中提取：
# - author_count: 4+
# - 各贡献者 commit 数和增删行数
# - 集中度计算

第四步：AI 计算指标

AI 根据 指标计算规则 处理数据：

Issue 响应时间:
  平均 0.1 天（仅 1 个已关闭 Issue，样本量不足）
  积压 28 个 → 触发扣分

PR 合并效率:
  平均合并时间 ≈ 3.5 天（估算，需 merge_at 字段）
  积压 0 个 ✓
  合并率 91%

贡献者活跃度:
  mengcheng (camelliamc) — 🔥 高频
  zzx-coder — 🔥 高频
  wbtiger — 🟢 正常
  wangyue789 — 🟡 低频

综合评分:
  起始 100
  核心指标: 0 扣分（响应时间样本不足/PR合并正常/贡献者活跃）
  辅助指标: -10 Issue 积压 (28 open), -5 无近期发布 (已解决)
  最终: 85/100（良好 🔵）

第五步：填充 HTML 模板

AI 读取 skills/gitlink-health/template.html，将计算后的指标替换所有 {{PLACEHOLDER}} 占位符，生成完整的 HTML 文件。

第六步：输出报告

1. 写入 skills/gitlink-health/report.html（唯一的输出文件）
2. 自动打开浏览器展示报告
3. 如需持久化，可选发布为 Issue（内容从内存生成，不写本地文件）

AI Agent 执行要点

1. 数据收集顺序：先收集 Issue 和 PR（Shortcut 命令），再收集 contributors（Raw API），避免一次性大量 API 调用
2. 分页处理：Issue 和 PR 数量超过单页限制时，用 --page 逐页获取
3. 时间计算：ISO 8601 格式解析优先，Unix 时间戳更可靠但 PR 的 pr_created_unix 仅部分返回
4. 指标计算容错：样本不足时标注而非报错，新项目可能仅有少量数据
5. 评分可按需调整：新项目无 Release 时，"无近期发布"项自动跳过
6. 避免 GIGO：数据异常时（如极长的响应时间），标注并排除 outlier
7. HTML 生成：读取 template.html → 替换所有 {{PLACEHOLDER}} → 写入 report.html → 自动 start/open 打开浏览器
8. 禁止创建临时文件：所有 API 数据在内存中处理，禁止创建 tmp_data/、脚本文件、中间 JSON 等任何多余文件。整个流程只输出一个 report.html。

References

• SKILL.md — 工作流和模板总览
• collect-data — 数据收集详细说明
• health-metrics — 指标计算和评分规则
• generate-report — 报告生成和输出