cnb-rs skill update

cnb-rs skill update [<SKILL>...] [options]

把已装的 cnb skill 升到上游最新版本：从 lockfile 拿 source / skill_root，重新解析 ref（默认拉最新 release tag / 默认分支 HEAD），递归下载，做 file sha 比对，命中则跳过为「up-to-date」，否则 clean 重装并刷新 updatedAt。

gh skill / vercel-skills 装的 entry（sourceType: "github" / "vercel"）完全不动。

参数

• [SKILL]...：要 update 的 skill name（多个空格分隔，对应 lockfile 中的 entry key）；不传则必须加 --all

选项

• --all：更新所有非 pinned 的 cnb skill
• --scope <SCOPE>：安装 scope（project / user），决定写回 agent 目录的 base_dir；默认 project
• --dir <PATH>：自定义目标根目录（覆盖 --scope）
• --agent <LIST>：目标 agent（comma 分隔，如 claude-code,windsurf）；不指定则 auto-detect
• --all-agents：装到所有已 detect 的 agent（与 --agent 互斥）
• --copy：用 copy 而非 symlink（Windows 上 symlink 失败时自动 fallback 也走 copy）
• --force：连 --pin <REF> 锁定的 skill / 远端 sha 未变 的 skill 也强制重装

继承的全局选项：

• --domain <DOMAIN>：仅在 --dir 解析需要 host 时使用（默认：cnb.cool）

行为：10 步流程

1. 校验 args：要么 --all，要么显式 <SKILL>...，二者皆无 → 拒绝并提示
2. 加载 lockfile → 提取 sourceType: "cnb" 条目（其它 sourceType 原样保留）
3. 选 target set：--all → 全集；<SKILL>... → 按名 filter，缺失 → 列可选
4. 过滤 pinned：pinned_ref 非空且无 --force 时跳过，并 stderr 打 ⏭ 提示
5. 解析 scope/agents：与 install 同语义；agent 0 个 → fail-fast
6. 对每个 target 重解析 ref：调 ref_resolver（与 install 同优先级：显式 > release tag > 默认分支）
7. discover + download：调 fetcher::discover_blobs_recursive + download_blobs 拉整个 skill 目录
8. up-to-date 检测：!force && new_ref == old_entry.ref && new_sha_set == old_sha_set → 跳过并打 ✓ up-to-date
9. frontmatter 注入 SKILL.md 的 cnb-ref 等键 → install_files（自带 clean_dir_robust 清旧）→ lockfile upsert 刷新 updated_at + files + ref + skill_file_sha，保留 installed_at
10. lockfile save

与 install 的关键差异

维度	install	update
source 来源	用户命令行 <REPO>	lockfile entry source 字段
skill_root 来源	仓库 skills/ discover	lockfile entry skill_root 字段
已装时行为	拒绝（除非 --force）	重新拉 + sha diff（决定是否写盘）
installed_at	写入当前时间	保留原值
updated_at	写入当前时间	sha 变 / --force 时刷新；否则不动
pinned_ref	由 --pin 决定	保留原值
pinned skip 行为	n/a	默认跳过（⏭ 提示），--force 强制

输出示例

普通 update（远端有变化）

$ cnb-rs skill update cnb-rs-api
📋 targets: 1 skill(s) to update
🤖 agents:  1 (claude-code)
📂 base:    /home/alice/myproj

── cnb-rs-api ──
  [ref]      old=main new=main
  [download] 5 files / 23456 bytes
  [install]  → 1 agent dirs
  ✓ updated

🎉 updated 1 skill(s) / 5 files; up-to-date 0; pinned skipped 0

up-to-date 跳过

$ cnb-rs skill update --all
📋 targets: 2 skill(s) to update
🤖 agents:  1 (claude-code)
📂 base:    /home/alice/myproj

── cnb-rs ──
  [ref]      old=main new=main
  [download] 4 files / 27600 bytes
  ✓ up-to-date (no changes)

── cnb-rs-api ──
  [ref]      old=main new=main
  [download] 5 files / 23456 bytes
  [install]  → 1 agent dirs
  ✓ updated

🎉 updated 1 skill(s) / 5 files; up-to-date 1; pinned skipped 0

pinned 跳过 + --force 强制

$ cnb-rs skill update --all
⏭  cnb-rs (=v0.1.0): pinned，跳过 — 用 --force 强制升级

🎉 updated 0 skill(s) / 0 files; up-to-date 0; pinned skipped 1

$ cnb-rs skill update --all --force
📋 targets: 1 skill(s) to update
...
── cnb-rs ──
  [ref]      old=v0.1.0 new=main
  [download] 4 files / 27600 bytes
  [install]  → 1 agent dirs
  ✓ updated

🎉 updated 1 skill(s) / 4 files; up-to-date 0; pinned skipped 0

错误示例

既没传 skill 名也没加 --all

$ cnb-rs skill update
错误: 必须显式指定要 update 的 skill 名，或加 --all 升级所有非 pinned skill

提示：
  cnb-rs skill update --all
  cnb-rs skill update <SKILL>...

skill 不在 cnb lockfile 中

$ cnb-rs skill update skill-nonexistent
错误: skill 'skill-nonexistent' 不在 cnb lockfile 中（sourceType="cnb"）

可选: cnb-rs, cnb-rs-api, cnb-rs-issue, cnb-rs-pr

注意：列出的 entry 仅是 sourceType: "cnb" 的；gh skill / vercel-skills 装的 entry 不会出现。

未检测到 AI agent

$ cnb-rs skill update --all
错误: 未检测到任何已安装的 AI agent

提示：用 --agent <name> 显式指定（如 claude-code / windsurf / cursor），
或先装一个 agent（创建对应目录如 ~/.claude）

退出码

• 0：所有 target 处理完成（含 up-to-date / pinned skipped）
• 1：任何一步失败（lockfile 读 / API / 下载 / 写盘 / lockfile 写）

与 gh skill update 的差异

特性	cnb-rs skill update	gh skill update
处理范围	仅 sourceType: "cnb" 的 entry	仅 sourceType: "github"
up-to-date 检测	✅ (ref, sha_set) 双匹配 → 跳过	✅ 同 (gh trees sha)
--force 行为	强制重写 + 升级 pinned	强制重写
--all 行为	升所有非 pinned	同
installed_at 保留	✅	✅
pass-through	✅ gh / vercel entry 在 lockfile 中完全不动	✅ 同
Windows symlink	✅ 通过 install_files 自动 fallback copy	⚠ 不一致

示例

# 升所有已装的 cnb skill（跳过 pinned）
$ cnb-rs skill update --all

# 仅升一个
$ cnb-rs skill update cnb-rs-api

# 升多个
$ cnb-rs skill update cnb-rs cnb-rs-issue

# 升所有 + 同时升 pinned
$ cnb-rs skill update --all --force

# 装到 user scope（默认 project）
$ cnb-rs skill update --all --scope user

# 显式指定 agent
$ cnb-rs skill update --all --agent claude-code,windsurf

# Windows 上想避免 symlink
$ cnb-rs skill update --all --copy

另请参阅

• cnb-rs skill
• cnb-rs skill install — 首次安装 + 写 lockfile
• cnb-rs skill list — 看已装 skill 的 installed_at / updated_at
• agentskills.io — skill 规范