check-updates

检查更新

这是一个只读的更新检查器。它会识别提供此技能的安装，比较其版本与仓库的 main 分支，并显示当前 Agent 宿主支持的更新路径。它绝不会自动更新。

检查频率

请将以下两个控制项分开处理：

• 调用守卫： 其他 Fabric 技能会在每个会话开始时调用此技能一次，然后再继续。
• 网络守卫： 自动调用时，对于每个检测到的安装身份，每 7 天最多进行一次远程查询。

如果用户当前的请求直接要求查询版本、变更日志或检查更新，则将其视为显式调用，绕过 7 天网络守卫。 如果此技能仅由其他技能的会话开始通知调用，则将其视为自动调用。

自动调用后，始终继续处理调用方的原始任务，包括跳过检查或检查失败的情况。

流程

步骤 1：解析安装上下文

确定一个候选安装根目录：

1. 如果用户明确提供了安装路径，则使用该确切路径。
2. 否则，从活动的 <skills-root>/check-updates/SKILL.md 文件开始。
3. 当 <skills-root> 名为 skills 时，将其父目录视为可能的包含根目录。只有当该包含根目录具有受支持的插件清单，或者同时具有 package.json、直接 .git 文件或目录，以及下文定义的肯定 skills-for-fabric Git 身份时，才使用该包含根目录。
4. 否则，将 <skills-root> 用作候选根目录。这包括 ~/.copilot/skills 和 ~/.agents/skills 下的个人副本，以及 .github/skills、.agents/skills 和 .claude/skills 下的项目副本。
5. 如果运行时未公开活动技能路径，则将上下文报告为未知。不要猜测。

绝不要根据 shell 的当前工作目录推断安装位置。绝不要向上遍历到候选根目录之外。项目中无关的父级 .git 目录不能作为此技能来自该仓库的证据。

独立于安装渠道解析运行时宿主：

copilot-cli | claude-code | cursor | windsurf | codex | other | unknown

使用当前会话或运行时公开的宿主身份。不要根据插件清单、安装路径或工作目录进行推断。确定性测试可以提供明确的运行时宿主覆盖值；正常使用时不可以。如果无法确定宿主，则使用 unknown。

运行时检测已安装插件时，按以下跨工具优先顺序使用第一个存在的清单：

1. .plugin/plugin.json
2. plugin.json
3. .github/plugin/plugin.json
4. .claude-plugin/plugin.json

在此仓库中，.github/plugin/plugin.json 是规范源清单。.plugin/plugin.json 和 plugin.json 是其他已安装布局或测试夹具的兼容性回退选项。最后一个位置支持仅提供 Claude 兼容清单的软件包。不要将此运行时探测顺序视为此仓库的编写指南。

然后按以下顺序对候选根目录进行分类：

渠道	候选根目录中必需的文件	读取内容
插件	一个受支持的插件清单	顶层的 name、version、repository
Git 克隆	package.json、直接 .git 文件或目录，以及肯定的 skills-for-fabric Git 身份	顶层的 version、repository.url
复制的技能	不属于插件或 Git 布局，且具有根级 SKILL.md 或包含 SKILL.md 的直接子技能目录	仅临时读取技能目录名称
未知	不符合任何确切布局	不提供身份信息或更新命令

如果两种布局同时存在，则优先检测插件。这样，开发夹具即使使用本地 Git 远程地址，也能保留插件语义。

肯定的 Git 身份要求同时通过以下两项检查：

• package.json 中 name 的最后一个非作用域片段是 skills-for-fabric。可接受的示例包括 skills-for-fabric、 @microsoft/skills-for-fabric 和贡献者分叉的作用域名称。
• 去除末尾的斜杠和 .git 后，仓库路径的最后一个片段是 skills-for-fabric，比较时不区分大小写。

如果任一检查失败，不要将该根目录归入 Git 通道，也不要对其运行 Git。 继续解析候选根目录，并独立分类最终得到的候选项；因此，嵌套的 skills 根目录可能是一个松散副本。仅仅包含 skills/ 目录的通用 Node 仓库，并不代表 它是 skills-for-fabric 安装。

在明确确认来源之前，复制的通道处于终止状态：

• 对于自动调用，不要提问。可以简短提示一次，说明已跳过未经验证的松散副本， 用户可以明确要求检查它，然后继续调用方的原始任务。
• 对于未确认来源的明确调用，列出暂定的复制技能名称，说明来源和版本未经验证， 在复制通道部分提出确认问题，然后停止。

这两种路径都不会继续执行网络防护检查或远程版本步骤。

构建一个上下文对象：

runtimeHost: copilot-cli | claude-code | cursor | windsurf | codex | other | unknown
channel: plugin | git | copy | unknown
root: exact candidate root
installKind: marketplace | direct | none
installScope: user | project | local | managed | none
manifestName: plugin manifest name | none
installedName: marketplace entry name | none
marketplace: marketplace name | none
sourceId: direct-install source ID | none
identity: plugin:<marketplace>/<installed-name> | plugin:direct/<source-id> | git:<repository-url-as-stored>|<root>
localVersion: manifest version
repository: URL exactly as stored in the selected manifest
updateTarget: <installed-name>@<marketplace> | <manifest-name> | <root> | none
copiedSkills: direct skill directory names | none

对于插件，请将清单名称与已安装的 marketplace 条目名称分别保存。两者可能不同。 如果原生运行时元数据或原生插件列表能够标识候选根目录，请据此解析已安装的条目。

对于 GitHub Copilot CLI marketplace 安装，文档指定的路径是 ~/.copilot/installed-plugins/<marketplace>/<installed-name>，因此这两个路径 片段具有权威性。

对于直接安装的 Copilot CLI 插件，路径为 ~/.copilot/installed-plugins/_direct/<source-id>。将 installKind 设为 direct，仅使用源 ID 作为缓存标识，并将清单名称用作不带作用域的更新目标。 _direct 不是 marketplace 名称。

对于 Claude Code marketplace 安装，请根据 Claude 的原生插件元数据解析已安装的 条目和作用域。claude plugin list --json 可以标识条目；声明该条目的设置文件 可以标识其作用域：

• ~/.claude/settings.json -> user
• .claude/settings.json -> project
• .claude/settings.local.json -> local
• 托管设置 -> managed

如果同一条目存在于多个作用域，请列出这些选项，并询问要更新哪一个。不要猜测 作用域。仅从技能目录、--plugin-dir 或 --plugin-url 加载的插件没有 marketplace 安装记录；不要为其编造更新命令。

如果原生元数据和已安装路径均不可用，仅当映射明确无歧义时，才将清单名称与 marketplace fabric-collection 配合使用。fabric-skills 清单存在歧义，因为 旧版 skills-for-fabric marketplace 条目使用相同的载荷。在这种情况下，说明 无法解析已安装的条目，请用户检查原生插件列表，不要猜测标识或更新命令。

对于 Git package.json，接受包含 url 属性的仓库对象，或仓库 URL 字符串。 保持仓库值与存储时完全一致，并在构建缓存标识时附加精确解析出的根目录。 这样可以防止一个克隆抑制对同一仓库另一克隆的检查。为远程工具解析 GitHub 所有者和仓库时，只去除末尾的 .git 和斜杠。不要更改所有者的拼写、大小写、 下划线或标点符号。

验证必需字段是否存在，以及 localVersion 是否为语义版本文本。如果验证失败， 报告格式错误的字段，并将上下文分类为未知，而不是使用不完整的元数据。

步骤 2：应用网络防护

仅在进行确定性测试时，使用调用方提供的精确缓存路径。 否则，使用此持久缓存文件：

~/.config/fabric-collection/last-update-check.json

在 Windows 上，此文件为：

$env:USERPROFILE\.config\fabric-collection\last-update-check.json

该文件是一个以安装身份为键的扁平 JSON 对象：

{
  "plugin:fabric-collection/fabric-consumption": "2026-07-15",
  "plugin:direct/github-com-example-skills": "2026-07-15",
  "git:https://github.com/example/skills-for-fabric.git|C:\\repos\\skills-for-fabric": "2026-07-14"
}

使用 YYYY-MM-DD 格式的 UTC 日期。

• 对于自动调用，如果此身份在过去 7 天内有有效日期，则跳过远程查询。
• 对于显式调用，即使存在最新的缓存条目，也要执行远程查询。
• 不同已安装插件条目或 Git 克隆根目录的缓存条目不会互相抑制。
• 写入文件时，保留所有无关条目。
• 如果文件包含格式错误的 JSON，则发出警告且不要覆盖该文件。
• 对于已复制或未知的上下文，不要读取或写入缓存条目。

远程尝试完成后，为检测到的身份记录今天的 UTC 日期，无论尝试是发现了更新、未发现更新还是失败，除非缓存文件格式错误。这样可以防止自动网络请求失败后在每个会话中重复尝试。如果网络防护跳过了此次尝试，则不要重写标记。

步骤 3：读取远程版本

从同一仓库的同一 main ref 读取 package.json 和 CHANGELOG.md。按以下顺序尝试这些方法，并在首次成功后停止：

1. Git CLI： 仅当候选根目录本身直接包含 .git 文件或目录时使用。不要使用 git rev-parse 检查可用性，因为它可能会发现无关的父级仓库。

   git -C "<root>" fetch origin main --quiet
   git -C "<root>" show origin/main:package.json
   git -C "<root>" show origin/main:CHANGELOG.md
   

2. 经过身份验证的 GitHub 工具： 使用 GitHub MCP 文件工具，或使用 gh api，并严格根据 manifest URL 解析出所有者和仓库。在 ref main 上读取 package.json 和 CHANGELOG.md。

3. 公共原始内容： 对于公共仓库，从 https://raw.githubusercontent.com/<owner>/<repo>/main/ 读取这两个文件。

不要使用最新的 GitHub Release 标签作为远程版本。插件市场更新依据仓库内容，而 Release 标签可能落后于插件用户可用的版本。

如果无法获取版本，则显示检测到的渠道、身份和本地版本，并附上简洁的警告。不要捏造远程版本。如果仅 changelog 获取失败，仍要报告版本比较结果，并注明 changelog 不可用。

步骤 4：比较并报告

比较语义化版本：

• remoteVersion > localVersion：有可用更新。
• remoteVersion <= localVersion：已是最新版本。

有更新时，显示本地版本与远程版本之间相关的 CHANGELOG.md 条目，然后仅提供同时针对检测到的渠道和 runtimeHost 验证过的指导。

插件渠道

绝不要为某个主机输出另一个主机的插件命令。

运行时主机	已验证的指导
GitHub Copilot CLI	对于市场安装，显示 /plugin update <installed-name>@<marketplace>。对于直接安装，显示 /plugin update <manifest-name>。
Claude Code	对于已解析作用域的市场安装，显示 claude plugin update <installed-name>@<marketplace> --scope <scope>，然后告知用户运行 /reload-plugins 或重启 Claude Code。
Cursor	指引用户前往 Customize > Plugins。对于团队市场，管理员可以使用 Refresh 或 Enable Auto Refresh。不要输出插件 CLI 命令。
Windsurf、Codex、其他或未知	报告可用版本和仓库，但不要提供可执行的插件命令，因为此布局没有经过验证的命令。

GitHub Copilot CLI 市场安装：

/plugin update <installed-name>@<marketplace>

已安装的市场条目具有权威性。例如，已安装的 fabric-consumption@fabric-collection 条目会生成：

/plugin update fabric-consumption@fabric-collection

如果已安装条目是旧版 skills-for-fabric 别名，则先更新该别名， 以便已安装条目能够获取当前负载，即使其复制的 manifest 名为 fabric-skills 也是如此：

/plugin update skills-for-fabric@fabric-collection

之后，可选择迁移到规范入口：

/plugin uninstall skills-for-fabric@fabric-collection
/plugin install fabric-skills@fabric-collection

GitHub Copilot CLI 直接安装：

/plugin update <manifest-name>

直接安装的原生 CLI 更新目标是不带修饰的清单名称。 请勿在后面添加 @_direct，也不要将不透明的源 ID 用作更新目标。

Claude Code marketplace 安装：

claude plugin update <installed-name>@<marketplace> --scope <scope>

入口名称和范围必须来自 Claude 的已安装插件元数据。 请勿在 Claude Code 中沿用 Copilot 的 _direct 行为。

Git 渠道

git -C "<detected-root>" pull --ff-only

未知渠道

说明缺少哪些预期文件，不提供更新命令。绝不要默认使用 fabric-skills。

复制的技能渠道

松散副本没有可信的仓库、已安装版本或原生更新目标。通过 copilot skill add 从本地文件或 URL 生成的技能，如果没有随附来源元数据，也属于此类。

对于自动调用，不要因询问来源而打断调用方。跳过复制技能更新流程，可以选择说明 显式更新检查能够识别受支持的替代项，然后继续处理调用方的任务。 不要列出可执行命令。

对于显式调用，列出在候选根目录中找到的暂定技能名称，说明仅凭文件无法验证 其来源，并询问：

Were these skills copied from https://github.com/microsoft/skills-for-fabric?
If yes, I can inspect the official public repository and show the supported
plugin bundle that will refresh them. I will not install or remove anything
without your confirmation.

在用户明确确认来源之前，不要联系网络、比较版本、写入缓存状态，也不要提供 可执行的安装／更新命令。

明确确认后：

1. 从 microsoft/skills-for-fabric 的 main ref 读取 .github/plugin/marketplace.json，优先使用经过身份验证的 GitHub 工具，其次使用 公共原始内容。

2. 将暂定技能目录名称与每个 marketplace 插件来源中的技能路径进行匹配。仅将 完全匹配的路径视为证据。

3. 优先选择涵盖所有已匹配非实用工具技能的专用插件。如果符合条件的插件不止一个， 列出有效选项并请用户选择。绝不要仅因为 check-updates 出现在其中就选择 fabric-skills。

4. 仅提供 runtimeHost 支持的替代路径：

   GitHub Copilot CLI：

   /plugin marketplace add microsoft/skills-for-fabric
   /plugin install <matched-plugin>@fabric-collection
   

   Claude Code：个人复制技能根目录使用 user，项目复制技能根目录使用 project：

   /plugin marketplace add microsoft/skills-for-fabric
   claude plugin install <matched-plugin>@fabric-collection --scope <scope>
   

   告知用户在安装后运行 /reload-plugins 或重启 Claude Code。如果无法确定 Claude 的范围，应先询问，而不是猜测。

   对于 Cursor、Windsurf、Codex、其他或未知主机，请链接到官方仓库的安装说明， 不提供可执行的替代命令。当前公开仓库没有为这些主机提供经过验证的原生插件 marketplace。

这样会安装完整的最新资源包，而不是覆盖松散文件并留下混合版本的依赖项。在原生插件 安装并验证之前，请保留松散副本。删除它之前，请另行征求用户同意。如果没有完全匹配的 官方映射，或公共仓库不可用，请如实说明，不要捏造资源包或复制单个文件。

示例

专用插件资源包

Host: copilot-cli
Detected: plugin:fabric-collection/fabric-consumption
Current: 0.3.7
Latest: 0.3.8
Update: /plugin update fabric-consumption@fabric-collection

Claude Code 插件资源包

Host: claude-code
Detected: plugin:fabric-collection/fabric-consumption
Current: 0.3.7
Latest: 0.3.8
Update: claude plugin update fabric-consumption@fabric-collection --scope user
Reload: /reload-plugins

Git 克隆

Detected: git:https://github.com/example/skills-for-fabric.git|C:\repos\skills-for-fabric
Current: 0.3.7
Latest: 0.3.8
Update: git -C "C:\repos\skills-for-fabric" pull --ff-only

未知布局

Could not determine the skills-for-fabric installation at <candidate-root>.
Expected a supported plugin manifest, or a positively identified
skills-for-fabric package.json plus a direct .git entry.
No update command was guessed.

已确认的官方松散副本

Host: copilot-cli
Detected loose skills: check-updates, powerbi-report-planning
Confirmed source: https://github.com/microsoft/skills-for-fabric
Supported refresh:
  /plugin marketplace add microsoft/skills-for-fabric
  /plugin install powerbi-authoring@fabric-collection
The loose files were not changed or removed.

必须

• 从当前激活的技能根目录或用户明确指定的路径解析身份。
• 独立解析运行时宿主，不要根据安装布局推断。
• 将每会话仅调用一次与 7 天网络检查间隔分开处理。
• 在插件身份和更新命令中使用已安装的市场条目，而不只是清单名称。
• 区分直接安装与市场安装。
• 使用 Git 通道前，必须确认软件包和仓库的身份。
• 按仓库和精确克隆根目录隔离 Git 缓存条目。
• 保留无关缓存条目，并使用 UTC 日期。
• 在官方公共仓库中查找散落副本前，必须确认其来源。
• 将已复制的技能名称与精确的公共市场技能路径匹配。
• 只输出已针对运行时宿主验证过的更新或替换命令。
• 自动检查失败后，以非阻塞方式继续。

优先

• 优先使用根目录本地 Git 远程地址，然后再使用经过身份验证的 GitHub 工具。
• 从同一个仓库引用获取版本和更新日志。
• 通过完整的原生插件包替换已确认的官方散落副本，而不是覆盖单个文件。
• 提供简洁、可直接复制粘贴的输出。

避免

• 根据当前工作目录推断安装上下文。
• 让 git 自动发现父级仓库。
• 将无关软件包加上 .git 误认为 skills-for-fabric 克隆仓库。
• 根据清单或安装路径推断运行时宿主。
• 向其他宿主显示 Copilot 或 Claude 插件命令。
• 将 fabric-skills 设为精简版软件包的默认值。
• 使用 GitHub Release 标签作为插件市场版本。
• 每个会话都重复失败的自动网络检查。
• 将同名散落文件夹视为其来自官方仓库的证据。
• 未安装完整的软件包依赖就替换单个已复制文件。
• 未经用户明确同意就更新。

错误处理

操作失败时，报告失败的操作并继续：

Could not check plugin:fabric-collection/fabric-consumption for updates: remote package.json was unavailable.
Current installed version: 0.3.7
The automatic check is non-blocking; continuing with the requested task.

如果用户只说“更新我的技能”，请确认他们是想检查更新，还是执行检测到的原生更新命令。不要根据含糊的意图执行更新。