[Bug] Skill 的无版本 npx 调用会被项目内旧版 CLI 静默遮蔽

[Disdjj]

问题

当前 3.4.0 的 skills/llmdoc/SKILL.md 规定所有命令默认通过：

npx -y @tokenroll/llmdoc <cmd>

同时它声明 CLI 是外部工具，不应进入项目 package.json。但在从早期 V3 迁移而来的真实仓库中，项目可能仍残留旧版 @tokenroll/llmdoc devDependency。此时上述无版本调用会静默优先命中项目本地旧版 CLI，而不是与当前 skill 匹配的版本，也没有任何 version-skew 提示。

这不是纯理论场景：本仓库早期 V3 迁移提交曾按当时流程把 @tokenroll/llmdoc 加入 devDependencies，后来 skill contract 改成外部工具，但旧依赖仍然存在。

实测环境

Node.js v26.7.0
npm 11.19.0
pnpm 11.21.0
已安装 llmdoc plugin/skill: 3.4.0
npm latest @tokenroll/llmdoc: 3.4.0
项目本地 devDependency: @tokenroll/llmdoc ^3.1.1
lockfile / node_modules 实际版本: 3.1.1

最小复现

在含旧版本项目依赖的目录运行：

npm install --save-dev @tokenroll/llmdoc@3.1.1

npx -y @tokenroll/llmdoc --version
# 3.1.1

npx -y @tokenroll/llmdoc@latest --version
# 3.4.0

npx -y @tokenroll/llmdoc@3.4.0 --version
# 3.4.0

也就是说，skill 推荐的默认命令与当前 skill/runtime contract 并不一定同版。

已观察到的实际影响

1. [Enhancement] status 区分源码落后与 meta-only follow-up，避免成功收尾后仍显示 1 commit behind #46 已在 3.4.0 修复 metadata-only baseline 文案，但无版本调用继续输出旧的、容易误判的结果：

# 实际被解析到的 3.1.1
baseline: <sha> (1 commits behind HEAD)
documents: ... / 0 impacted / 0 needs-review / 0 dirty

# 显式 3.4.0
baseline: <sha> (1 commits behind HEAD, metadata-only; knowledge clean)
documents: ... / 0 impacted / 0 needs-review / 0 dirty

2. 当前 3.4.0 skill 已要求已有 .mdx 使用 adopt，但 3.1.1 没有该命令。更隐蔽的是：

npx -y @tokenroll/llmdoc adopt --help

在旧版上返回全局帮助且退出码为 0，而显式 3.4.0 才返回真正的 llmdoc adopt 帮助。Agent 因而可能使用一个 skill 已声明、runtime 却不支持的命令，甚至误判为成功。

期望行为

安装的 skill 与它调用的 CLI 应具有明确且可复现的版本兼容性；项目本地旧版二进制不应无提示地覆盖当前 skill 所需 runtime。

建议

首选：在插件发布产物中把 skill 的 CLI 调用精确固定到同一 release，例如 3.4.0 skill 生成：

npx -y @tokenroll/llmdoc@3.4.0 <cmd>

并增加 release parity test，保证 plugin manifest、skill contract 与 CLI package 版本一致。

还可以补充：

• 启动时检测 skill/runtime version mismatch 并给出明确告警；
• upgrade 或诊断路径识别早期 V3 遗留的项目内 @tokenroll/llmdoc 依赖，并提示移除；
• 若不固定精确版本，至少使用能绕过本地旧 binary 的调用形式。

不建议只永久改成 @latest：这会把问题从“旧 CLI 遮蔽新 skill”变成“未来 CLI 配旧 skill”，同样不具备可复现性。

相关

• [Enhancement] status 区分源码落后与 meta-only follow-up，避免成功收尾后仍显示 1 commit behind #46：baseline metadata-only 文案，已在 3.4.0 修复，但本问题会静默绕过该修复
• PR docs: keep llmdoc outside project dependencies #39：明确 llmdoc 不应成为项目依赖
• PR feat(prompts): unify the CLI contract across every prompt surface #40：统一 skill 的 CLI invocation contract，但当前无版本形式仍会被遗留本地依赖遮蔽
• PR fix(cli): commit preflight, adopt command, status relevant-behind — release 3.4.0 #47 / v3.4.0：新增 adopt 与 status 修复