更新检查比较已保存的版本基线与远端来源中的 Skill 版本，不修改直接安装 Skill 或库成员的内容。检查优先使用远端版本摘要；旧版 Well-known 索引需要下载本次检查成员的内容以计算摘要。用户发起更新后，应用先准备并校验所选内容，再展示确认界面；确认后的执行只使用本次已准备的内容。
Skill 能否更新以及来源失效后的处理方式，见Skill 生命周期。lock 文件字段、内容哈希和参考版本规则见skills CLI 参考与兼容。
更新检查记录以下三类信息：
| 信息 | 含义 |
|---|---|
| 检查能力 | Skill 来源和保存的来源记录是否足以获取远端版本信息并完成比较 |
| 上次成功检查的结果 | 已确认的“有更新”“没有更新”或“来源中已不存在” |
| 本次检查状态 | 本次检查是否成功、失败、正在等待重试或因远端服务限流而暂停 |
本次检查失败时，应用保留同一比较基线下的上次成功结果，单独记录本次未能完成检查的原因。来源记录或版本基线变化后，旧结果失效。只有完成一次版本比较后，才能得出“没有更新”；尚未检查或检查失败都不能表示当前已经是最新版本。
用户主动检查未完成时，界面按网络、认证或其他原因反馈；自动检查失败不弹出干扰提示。临时网络错误和超时不作为常驻标题标签或详情诊断块，需要处理的来源或认证问题则保留简短说明。具体提示和重试入口见产品行为与交互。
全局、项目和 Skill 库使用相同的版本比较规则。
Skills 页检查所选 Scope 的实际直接安装，支持仅存在于 Agent 专用目录中的 Skill。应用根据 Agent 读取目录、实际安装位置和完整库成员归属确认检查资格；归属无法确认时返回异常。远端比较模块使用规范化后的来源记录，不再解析 Agent 目录或读取已安装内容清单。
检查开始时固定所选名称列表。没有来源记录的本地 Skill，以及本地或导入来源不纳入远端检查，也不计入检查异常。来源记录存在但字段不完整或无法解释时，应用显示来源信息异常。
远端请求完成后，应用重新核对实际位置、归属和所选来源记录。相关状态已经变化的 Skill 不接收旧比较。后端用比较指纹标识结果所依据的来源和版本基线，前端据此拒绝失效结果，必要时重新加载位置快照。
Skill 库的检查只处理当前库成员，使用该成员自己的来源记录和版本基线。本地和导入成员不计为检查失败；缺少比较基线的成员无法检查更新，现有内容保留。库成员与同名直接安装 Skill 的比较结果分别归属各自位置。检查结果不作为写入凭据。
两个已有版本标记不相等即视为有更新，包括旧工具采用其他算法生成标记的情况，因此允许一次内容不变的更新。真正缺少标记时不产生比较结论；来源仍可定位时，用户可以按来源重新获取内容。
库检查重试开始时清除旧操作错误，保留仍有效的成功比较。本次失败记录新错误；请求正常返回后清除操作错误，并根据逐来源、逐成员结果显示本次异常。切换库之后，旧请求不能覆盖当前状态。
| 检查方式 | 触发方式 | 行为 |
|---|---|---|
自动检查（Automatic） |
Skill 列表成功加载后由应用发起 | 复用仍在有效期内且覆盖所选成员的远端信息；遵循来源失败等待和服务限流 |
手动检查（Force） |
用户明确要求重新检查 | 重新获取远端信息，可以跳过单个来源的失败等待，但仍遵循服务限流；已有同源请求进行时合并获取 |
列表加载、切换位置和窗口重新获得焦点时，应用核对当前选择位置的比较基线及有效期。仍有效的结果不重复请求；结果过期或基线改变时，自动检查对应成员。搜索和 Agent 筛选只影响展示与手动选择范围。
同一位置、选择、基线和模式的进行中请求共用一次调用。不同选择的手动请求立即提交，可以与自动检查交叠；后端按等价来源合并进行中的获取。前端逐成员按远端信息的取得时间合并比较结果，按请求编号更新本次检查状态，各请求分别结束。检查失败后，应用等待后续触发，不会因本次请求结束而立即重新检查。
Skill Deck 根据来源类型和操作所在的 Environment 选择获取方式：
| 来源与操作位置 | 获取方式 | 用于比较的信息 |
|---|---|---|
| GitHub，应用所在的 Windows、macOS 或 Linux | 优先使用 GitHub Trees API，指定失败情形下改用本机 Git | Skill 目录的 Git 目录树对象 ID（tree object ID） |
| GitHub，WSL Environment | 使用所选发行版中的 Git | Skill 目录的 Git 目录树对象 ID |
| GitLab 或普通 Git | 使用应用所在系统或所选 WSL 发行版中的 Git | 与参考 CLI 兼容的内容哈希 |
| Well-known | 读取索引；旧版索引需要下载所选成员内容 | 索引摘要或根据内容计算的兼容摘要 |
| 本地或导入来源 | 不发起远端请求 | 没有远端版本可供比较 |
GitHub Trees API 因认证、仓库不存在或未授权、目录清单不完整、来源暂时不可用而未取得版本信息时，应用改用本机 Git。切换后，本次结果以 Git 返回的认证、仓库、分支或标签、网络、超时及执行状态为准。
API 已确认限流或请求发生普通网络错误时，应用按相应规则等待或记录失败，不再启动 Git 获取。代理配置不可用时，应用返回配置错误。具体凭据来源见GitHub 凭据。
已保存的 Git Skill 路径直接在当前来源快照中定位，不受默认发现深度限制。定位遵循以下规则：
- 从来源根目录到 Skill 目录的各级路径必须是普通目录；检查和更新不通过目录符号链接或 Windows 目录联接（junction）定位 Skill，即使链接指向来源内部也会拒绝。
- 用户可以调整来源目录结构，或将内容作为本地 Skill 导入。
- 此限制不改变已安装的 Agent 链接、库链接或 Skill 内容内部资源链接的处理规则。
Git 引用（ref）包括分支、标签和固定提交。短名称优先解析为分支，明确指定的分支和标签按原类型解析；附注标签使用其指向的提交，探测与检出遵循同一规则。固定提交的检查、预览和重新获取始终使用已保存的完整提交 ID；上游分支继续前进不会改变它的比较目标。历史基线不同或缺失时沿用已有比较及重新获取规则，检查仍不读取本地内容判断是否被编辑。
GitHub 检查命名分支时使用明确的分支引用；未分类的完整十六进制名称由 Git 解析，以区分同名分支和提交。固定提交通过 API 获取时，先核对提交对象，再读取该提交关联的目录树；对象不一致则改用 Git 核实。获取失败不表示 Skill 已从来源删除。引用类型参与缓存与比较身份，同字符串的分支、固定提交和未分类记录保持隔离。
直接安装与库成员的 Git Skill 在原路径缺失时，会在同一仓库和引用的完整来源快照中查找同名位置。名称按 SKILL.md 中的值严格匹配，多个同名路径全部保留。原路径仍然有效时继续使用原路径；原路径的名称改变、文档损坏或目录链接不受支持时，保留对应错误，不改用其他位置。
只有完整候选目录中的唯一同名位置可以形成路径迁移。多个候选返回歧义，完整目录中没有候选才表示来源中已不存在；读取失败、候选文档解析失败、扫描超限或取消均不能形成迁移或删除结论。迁移扫描遵循来源排除目录和项目 lock 的安装副本过滤，读取深层及嵌套 Skill，不使用普通安装发现的同名去重结果。
GitHub API 确认旧路径缺失后，改用 Git 快照核实迁移候选。本次结果使用实际获取的同一个提交；引用在 API 请求和 Git 获取之间前进时，不混用两个提交的证据。原路径有效的检查继续使用原有快速路径。
路径变化本身属于有更新，即使内容摘要相同。检查只提供结论，用户进入更新后才重新核实并准备新路径的完整内容。候选目录与远端证据按快照缓存；旧缓存中缺少迁移证明的缺失路径会重新核实，已有正向版本信息和限流等待继续保留。
新快照确认存在同名歧义时，界面采用这一新结论，不沿用旧的有更新或已删除状态；迟到的旧快照不能覆盖新结论。网络等未完成检查仍沿用已有结果保留规则。
来源目录超过内容保留额度时，应用停止获取后的接纳并提示使用较小来源；所选内容无法接纳时提示减少选择，已有准备内容继续受保护。额度与清理规则见执行与恢复。
v2 索引直接提供 Skill 摘要。旧版索引只下载本次检查的直接安装 Skill 或库成员内容，计算兼容摘要，不下载索引中的其他 Skill。
Well-known 记录同时包含索引地址和安装时摘要时可以检查更新；只有索引地址时不能得出版本比较结果，但仍可按来源重新获取内容。只有历史制品地址或来源主机时，需要先移除当前 Skill，再通过普通安装流程重新添加。
完整索引明确不再包含本次检查的 Skill 时，应用显示来源中已不存在，并保留本地内容。成员格式错误、清单不完整或资源下载失败都不表示来源已删除该 Skill；一个成员失败时，其他有效成员仍可检查。
保存的地址遵循来源范围规则：带页面路径的地址只读取对应范围，精确索引地址保留原有协议、端口、路径大小写及查询参数。页面或站点根地址中的查询参数不转交给生成的索引地址。应用所在系统和 WSL 中的已保存 Well-known 来源都按这套规则处理，更新时保留来源类型。
远端信息只用于判断版本是否变化，缓存失效后仍按上述来源和 Environment 规则重新获取。安装和复制使用经过校验的完整 Skill 内容。
更新检查沿用“设置 > 代理设置”中的连接方式。HTTP 请求、Native Git 与 WSL Git 分别使用各自当前的配置，执行时的代理选择和配置生效边界见系统架构。
Skill Deck 自身的应用更新与 Skill 来源更新分别处理。应用更新的插件边界见系统架构，交互见产品行为与交互，发布资产约束见贡献指南。
远端版本信息、失败记录和限流信息使用不同的保存范围：
| 记录内容 | 区分依据 | 使用规则 |
|---|---|---|
| 远端版本信息 | 来源类型、远端主机、仓库或 Well-known 索引，以及分支、标签等 ref |
获取成功后一小时内可以复用；GitHub 目录树对象 ID 和 Well-known 摘要可以跨 Environment 共用，GitLab 与普通 Git 的 CLI 内容哈希只在对应 Environment 内复用 |
| 本地比较结果 | 直接安装位置或所属库、Skill 名称与后端比较指纹 | 基线改变即失效；成员的有效期不因同源其他成员的检查而延长 |
| 单个来源的失败记录 | Environment 和具体远端来源 | 限制该 Environment 中对应来源的自动重试；同一来源用于全局、项目或库时，共用这份记录 |
| 远端服务的限流等待时间 | Environment、来源类型和远端主机 | 同时限制该范围内的自动检查和手动检查 |
缓存按照远端来源区分，不按照 Skill 名称区分。名称相同但来源不同的 Skill 不会共用远端版本信息。
界面中的检查状态由位置快照维护。安装、更新或移除成功后，应用清除受影响成员的旧比较，拒绝这些成员在变更前启动的迟到响应；其他成员保留各自结果。来源身份由后端提供，界面不通过显示地址推断来源等价性。
检查失败后的处理分为三类：
- 认证失败、仓库不存在、分支或标签不存在，以及无法区分的“不存在或未授权”，会暂停该来源的自动检查。用户处理凭据或来源后，可以手动重试。
- 网络错误、远端返回的信息不完整或暂时无法访问远端来源时，Skill Deck 会逐步延长下一次自动检查前的等待时间，依次为 30 秒、1 分钟、2 分钟、5 分钟、10 分钟和 30 分钟。检查成功后，失败次数和等待时间会被清除。
- 应用将
429视为限流。403响应只有在携带Retry-After、X-RateLimit-Remaining: 0，或正文说明触发二级限流或滥用检测时，才按限流处理。限流会暂停当前 Environment 对该主机的更新检查；结束时间优先采用Retry-After，其次采用X-RateLimit-Reset，两者都缺失时等待五分钟。同一客户端在等待期内直接复用该限流结果，不再重复访问 GitHub。
页面已经得知来源目录链接不受支持或来源本身超限时，不自动重复请求同一安装基线。用户调整后可以手动检查；安装基线变化后重新按正常规则判断。
失败记录和限流记录按实际操作分别清理：
| 触发条件 | 清理范围 |
|---|---|
| 检查成功 | 清除当前 Environment 中对应来源的失败次数和等待时间 |
| 本次安装的全部执行项成功 | 清除当前 Environment 中本次安装来源的失败记录和等待时间；其他来源和服务限流继续保留 |
| GitHub Token 成功保存或清除 | 清除应用所在系统中 GitHub 的认证失败记录和限流等待；成功的远端信息、WSL 状态及非认证失败继续保留 |
安装部分完成时保留来源失败记录。更换来源不会顺带清理旧来源的失败记录，后续检查按新的来源和基线重新判断。
安装或凭据变更成功后，如果检查记录的清理结果无法保存，原操作仍然有效，界面单独显示清理警告。清理状态的保存规则见状态文件。
用户可以在 Git 设置中验证 GitHub Token，并将验证通过的 Token 保存到系统安全存储。GitHub API 依次使用已保存凭据、GITHUB_TOKEN、GH_TOKEN；没有可用凭据时匿名访问。清除已保存凭据后，应用重新读取环境变量。新 Token 验证失败时保留已有凭据。
携带 Token 的目录树请求收到 401 时，应用会匿名重试一次，使公开仓库仍有机会完成检查；其他失败继续按 GitHub API 与 Git 的获取规则处理。
GitHub API 在应用所在系统中改用 Git 获取时，使用本机 Git 已有的凭据助手（credential helper）、SSH 配置和其他 Git 支持的认证方式。Skill Deck 不从 GitHub CLI 提取 Token，也不为这条获取流程新增凭据存储。WSL Environment 继续直接使用对应发行版中的 Git 及其凭据配置。
系统安全存储不可用时，Skill Deck 不会将 Token 写入明文文件。Token 不会进入全局或项目 lock 文件、更新检查状态文件、前端持久化设置或用户可见诊断。界面只能读取凭据来源、账号、验证结果和额度等不含 Token 的信息。
更新检查使用带版本号的状态文件，其中包括：
- GitHub、GitLab、Well-known 等来源类型，以及远端主机、仓库、索引和
ref； - 最近获取的远端提交、Skill 相对路径和版本标识；
- 最近一次检查的失败类型、连续失败次数和下次重试时间；
- 远端服务限流的结束时间。
状态文件不保存 Token、带凭据的来源 URL、原始错误文本或仓库文件内容。写入采用原子替换。文件可以读取、但内容损坏或结构版本不受支持时，应用隔离原文件并重新创建状态文件；文件无法读取或超过读取上限时，返回读取错误并保留原文件。
清理状态时，应用先保存新文件，再更新内存记录。新文件发布前失败时，两者保留原值；已经确认发布成功时，内存同步到新状态。发布结果不明确时，应用重新读取文件，只有确认内容与待保存状态一致才继续采用新状态。