docs / troubleshooting

故障排查

按固定顺序自查，先排除作用域、工作目录和环境问题；再看懂常见报错的含义与处置；然后守住缓存与快照的纪律；最后，需要向上游报告时，准备一份脱敏的、可提交的问题报告。

自查五步

遇到报错或状态异常时，按同样的五步走。顺序是刻意的：作用域和工作目录解释大多数"莫名其妙"的结果，环境和版本解释剩下的很大一部分。

  1. 确认作用域与工作目录。项目命令默认读写当前目录的 SKILL.mod 与 SKILL.lock，并装进当前目录的 .agents/skills/；要影响用户全局环境的命令，必须显式加 --global。
  2. 运行 git --version 与 skillmod --version，确认 Git 可用，并记下 skillmod 版本。
  3. 运行 skillmod list 看全部声明；对具体条目运行 skillmod why <selector>，看它的来源、解析版本、commit、dirhash、安装目录，以及每个配置目标的状态。
  4. 运行 skillmod verify 并记录退出码。list、why、verify 对每个安装目录的分类方式一致，它们不可能对同一个目标给出互相矛盾的结论。
  5. 对计划中的写操作，在命令支持时用 --dry-run 重跑一遍，先审阅报告，再决定是否真正执行。
$ git --version
$ skillmod --version
$ skillmod list
$ skillmod why review
$ skillmod verify
# 计划中的写操作：先看 dry-run 报告
$ skillmod sync --relink --dry-run
退出码：verify 返回 0 表示检查过的条目全部一致，1 表示操作或输入错误，2 表示检测到漂移，3 表示命令安全保留了冲突目标的未完成状态。完整退出码表和 --json 报告结构见自动化与 CI。

常见报错与处置

下面每一条都是一种常见失败。先读懂含义，再决定动作；涉及本地修改的，一律以用户的决定为准。

现象 / 报错含义与处置
SKILL.mod not found当前作用域没有清单。初始化目标作用域（init），或切换到正确的项目根目录。
漂移，或冲突的目标被保留查看本地修改，不要未经用户决定就覆盖。sync 返回 3 时逐目标看结果：部分工作已完成，冲突的目标被保留。
网络不可用已经物化的不可变快照可能离线可用，直接从本地子目录校验并安装；latest 解析需要远端引用，离线时拿不到。
分支名被拒绝版本必须不可变：选一个 tag、一个完整 commit SHA，或省略版本，让 skillmod 解析最新的不可变版本。
地址因不安全被拒地址必须不带凭证：去掉 URL 里的密码或 token、query string 和 fragment；把 source 里的 @version 后缀移进 version 字段。凭证放进 Git credential helper、SSH agent 或环境变量。
manifest 校验错误声明和锁在读取时都会校验。报告原文，不要凭猜测改写文件。没有 schemaversion 的 SKILL.lock 早于 schema 版本化，按 schema 1 处理；显式写了不支持的版本，仍需人工介入。
快照完整性错误不要压制它。保留诊断信息；如果来源和本地状态看起来都正常，转入问题报告流程。

缓存与快照的纪律

两个作用域共享同一个内容存储：缓存在 $SKILLMOD_HOME/pkg/mod/，默认 ~/.agents/skillmod/pkg/mod/。快照可读且不可变，项目、全局技能和 CI 复用同一份，同一个仓库不会重复下载。

  • prune 删除过时的安装条目，但不删链接目标，也不删快照。
  • 没有自动缓存逐出。手删快照之前，先确认没有安装中的链接还在用它——链接指向的快照与机器上其他项目共享。
  • 不要把手删缓存当作移除一个依赖的捷径。移除依赖用 remove，清理过时安装用 prune。
  • --dry-run 不动清单和安装，但远端来源校验可能仍会填充共享缓存。
$ skillmod remove review --dry-run
$ skillmod prune --dry-run
编辑安装的技能前先脱离链接：auto 模式装的是指向共享只读快照的目录链接，顺着链接编辑，等于修改机器上所有项目共享的内容。需要编辑时，用 sync --relink --install-mode=copy 换成独立副本。

准备问题报告

只有当诊断指向 skillmod 自身的缺陷、且用户同意上报时，才进入提 issue 的流程。创建 GitHub issue 是对外的公开变更：先给出目标仓库和最终草稿，提交前必须获得明确授权。

复现只用对当前状态安全的命令：--dry-run、list、why、verify。不要在收集诊断信息之前破坏失败状态。

报告里带上这些信息：

  • skillmod --version、git --version，装有 GitHub CLI 时再加 gh --version
  • 操作系统与架构
  • 安装方式与可执行文件路径
  • 项目作用域还是全局作用域
  • 确切的 skillmod 命令与退出码
  • 预期行为与实际行为
  • 最小复现步骤
  • 行为是稳定复现还是间歇出现

附上 SKILL.mod、SKILL.lock 和命令输出中最小的相关片段，不要默认贴整个文件。

分享之前一律脱敏：删掉 access token、凭证、私有仓库 URL、用户名、home 目录路径、内部主机名，以及与问题无关的 skill 声明。默认绝不上传整个私有清单或 Git 配置。

诊断输出默认可能是中文。设置 SKILLMOD_LANG=en 可以让维护者更容易检索，但不要为了翻译输出而重跑会改状态的命令。

没有 gh 时，按官方安装说明处理，不要未经同意就安装或认证；不想用 GitHub CLI 的用户，准备同一份草稿，到仓库的 issues 页面手动提交。新建之前先查重：

# 用症状关键词检索已关闭和未关闭的 issue
$ gh issue list --repo huija/skillmod --state all --search "<keywords>" --limit 20
报告结构：Summary（一两句说明缺陷与影响）· Environment（skillmod 与 Git 版本、系统与架构、安装方式、作用域）· Steps to reproduce · Expected behavior · Actual behavior · Command output（脱敏后的输出与退出码）· Additional context（最小的脱敏清单片段）。标题用 <command>: <observable problem> 的形式陈述事实，不写未证实的根因。