SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场skill-staleness-check

skill-staleness-check

编程与开发

查看项目

更新于 10-16 05:36

技能介绍

用途

Skill Staleness Check 是一个编码智能体技能，用于判断上游 TanStack 源码变更后，intent 技能（skill）是否已经过时，并在需要时更新技能内容、提交 PR。它端到端自主运行，PR 中包含的是已经更新好的技能内容，而不是修改建议。如果没有任何内容需要更新，则静默退出，不产生 PR、通知或 issue。

输入

输入是来自上游包仓库合并到 main 的 webhook 负载，包含：

  • package：包名，例如 @tanstack/query
  • sha：commit SHA
  • changed_files：变更文件列表

示例：

{
  "package": "@tanstack/query",
  "sha": "abc123",
  "changed_files": ["docs/framework/react/guides/queries.md", "src/query.ts"]
}

主要能力与工作流程

第 1 步 — 将变更文件匹配到技能

读取 packages/intent/skills/ 下所有 SKILL.md 文件，从每个技能的 frontmatter 中提取 sources。将 webhook 的 changed_files 与所有技能的 sources 条目匹配。source 引用格式为 Owner/repo:relative-path，支持 glob 模式。若某技能的任一 sources 条目匹配到变更文件，该技能即为候选。若没有技能匹配，则静默退出。

关于 intent stale：没有单独的同步脚本，intent stale [dir] [--json] 是真实存在的过时信号（见 docs/cli/intent-stale.md）。它是只读的，只报告漂移，不写入任何内容。例如：

intent stale packages/query --json

它会报告：库版本漂移（技能 frontmatter 中的 library_version 与当前已发布版本对比，分类为 major/minor/patch）；以及该包 skills/sync-state.json 中缺失的 source SHA（这是一个保守信号，标记的是存储 SHA 记录中的缺口，而非实际远程内容差异）。intent stale 不会像专门的同步工具那样区分“需要重新生成”与“仅版本号变更”，该分类是本技能自己的职责，在第 2 步中依据实际源码 diff 完成，而不是仅凭 intent stale 的输出。

第 2 步 — 评估每个候选技能

对每个匹配的技能：读取当前 SKILL.md 内容；从触发 commit 的源仓库获取文件 diff；对变更进行分类：

  • 无影响：diff 是拼写修正、注释变更、仅测试或内部重构，无 API/行为变更 → 跳过，无需更新。
  • 仅版本号变更：diff 只改版本号、依赖范围或元数据，无文档化行为变更 → 在 frontmatter 中提升 library_version。
  • 内容更新：diff 改变了技能所记录的 API 形态、行为、默认值、类型或模式 → 重写受影响章节。
  • 破坏性变更：diff 删除、重命名或根本性改变技能所记录的 API → 重写，并将旧模式添加为 Common Mistake。

采用两遍分类：

  • 第一遍 — 快速扫描：读取 diff 摘要（变更文件、插入、删除），识别可能受影响的技能章节。
  • 第二遍 — 详细评估：对每个可能受影响的章节，读取完整 diff hunk 并与技能内容对比，判断变更是否真正影响技能所记录的内容。

这可以防止过度更新。一个 200 行的源码 diff 可能只影响某个技能的一行，或完全不影响。

第 3 步 — 更新过时技能

对需要内容更新的技能：加载 generate-skill 元技能，向其提供现有 SKILL.md 内容、源码 diff、当前源码文档（获取更新后的文件），使用重新生成模式（外科手术式更新，而非完全重写），并对更新后的技能执行所有校验。

对仅版本号变更：没有可写入的脚本。直接在每个受影响技能的 frontmatter 中编辑 library_version，然后更新该库 skills/sync-state.json 中记录的 SHA（见第 5 步），以反映新的同步状态。

第 4 步 — 检查跨技能引用

在第 3 步更新技能后，检查跨技能过时：对每个被更新的技能读取其名称；扫描所有其他技能中引用该更新技能的 requires 条目或 sources；对每个引用更新技能者，评估该更新是否使其过时或不一致；若过时则用与第 3 步相同的流程更新，否则跳过。该级联仅限一层，引用二阶依赖的技能不会被自动重新检查。

第 5 步 — 标记技能为已同步

同样没有可写入的脚本。更新技能后，直接编辑该库的 skills/sync-state.json：更新 library_version 以及受影响技能的 skills[skillName].sources_sha 映射，填入触发本次运行的 commit 中新的源文件 SHA。

第 6 步 — 提交 PR

对每个（或每组）被更新的技能：创建分支 skill-update/<skill-name>-<short-sha>；提交更新后的 SKILL.md 文件；以结构化正文提交 PR。

PR 格式：

  • 标题：skill: update <skill-name> (<package>@<short-sha>)
  • 正文包含：Triggered by（匹配的源文件列表）、What changed in the source（diff 摘要，最多 2–3 句）、What changed in the skill（技能编辑摘要，哪些章节被更新及原因）、Cross-skill impact（检查的下游技能列表，是否为其开了 PR）、Review checklist（技能内容准确；代码示例完整可复制粘贴；无其他技能需要相应更新；少于 500 行）。

PR 分组规则：同一库的多个技能若受同一 commit 影响，合并到一个 PR；若需要跨技能更新（第 4 步），为下游技能单独开 PR 以保持审查范围清晰；绝不在同一 PR 中混合不同库的技能。

无操作行为

当以下任一条件成立时静默退出（无 PR、无通知、无 issue）：没有变更文件匹配任何技能的 sources；所有匹配的 diff 在第 2 步均被分类为“无影响”；intent stale 报告所有技能均为最新。

运行说明

GitHub API 使用：本技能（而非单独脚本）直接使用 gh CLI 访问 GitHub API——在第 2 步获取源码 diff，在第 6 步开 PR。它需要：已安装并认证的 gh CLI；对上游 TanStack 包仓库（query、router、db、form、table）的读权限；对 intent 仓库的写权限以创建分支和 PR。

速率限制：检查多个库或大量源文件时，第 2 步的 diff 获取会对每个技能的每个源文件发起一次 API 调用。大批量时可能触及 GitHub API 速率限制（认证用户 5000 请求/小时）。目前没有批处理或响应缓存；若成为问题，可在 diff 获取步骤周围添加缓存。

手动触发：维护者可在 webhook 触发流程之外手动运行只读过时信号：

# 检查特定库
intent stale packages/db

# JSON 输出
intent stale packages/db --json

这仅报告漂移（版本漂移、缺失的 source SHA），不会更新 sync-state.json 或开 PR；那些仍是本技能工作流的第 5 步和第 6 步，需按上述方式手动完成。

约束

  • 无变化时静默：无需更新则干净退出，不产生噪音。
  • 外科手术式更新优于完全重写：只改受 diff 影响的章节。
  • 级联仅一层：跨技能检查只深入一层，不递归。
  • PR 限定单一库：绝不在单个 PR 中混合不同库。
  • 版本号提升与内容更新分离：仅版本号提升不需要重新生成。
  • commit 信息包含共同作者：包含编码智能体的 co-author 标签。

适用场景

适用于维护 TanStack intent 技能库的自动化流程：当上游包仓库合并到 main 后，自动检测并修复因源码变更而过时的技能文档，减少人工同步成本。

限制

  • 依赖 gh CLI 认证及对相关仓库的读写权限。
  • 无批处理或缓存，大批量时可能触及 GitHub API 速率限制。
  • 跨技能级联仅一层，不递归。
  • 版本号提升与同步状态标记均无写入脚本，需手动编辑文件。
  • 关于收费、价格、平台支持等具体信息，资料中暂未提供。