SkillHub CLI 操作全指南：安装、升级、命名空间同步、发布与修复的安全实操手册

人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载本篇指南以 skillhub-cli 技能 的配套参考文档 cli-operations.md 为核心面向已经通过第一方astron-team/skillhubCLI 连接 SkillHub 注册表、需要执行写操作安装、升级、同步、发布、移除的 Agent 与开发者。读完本文你将掌握 SkillHub CLI 的「先只读检查、后显式写入」安全纪律、四种坐标写法、命名空间工作区的状态/差异/拉取/推送全流程以及故障排查与结果上报的规范文中每一条规则都对照了 CLI 源码 中的实际实现可直接在真实注册表上安全复现。使用前提先解析注册表再确认第一方 CLIcli-operations.md是skillhub-cli技能的实操参考使用前提是先完成 SKILL.md 中的两步准备解析registry对已安装的 Skill其同级目录.skillhub/metadata.json中的registry字段是后续搜索与升级的权威来源否则按--registry参数 →SKILLHUB_REGISTRY环境变量 →~/.skillhub/config.json的registry字段 → 默认值https://skill.xfyun.cn的优先级解析。该优先级与 registry-service.ts 的实现完全一致默认值定义在 constants.ts 中。确认命令身份skillhub必须存在且可证明是第一方实现安装包为astron-team/skillhub、版本输出为SkillHub CLI version。缺失时全局安装npm install --global astron-team/skillhub之后skillhub version验证。在本文开始任何操作之前请对当前 CLI 执行两个 live help 面文档未列出的参数一律以实际 CLI 为准skillhub help command skillhub command --help本指南中的registry只是一个待替换的值不是 shell 语法或环境变量。整个操作过程必须始终使用同一个全局安装的、身份已验证的skillhub命令不要切换到某个按次运行的包执行器。写安全Write Safety所有写操作的前置纪律SkillHub CLI 操作文档反复强调一条核心纪律在命令写入本地或注册表状态之前必须先建立精确的注册表、坐标及可选版本、Agent 与作用域或目录、现有安装归属、本地变更状态。用户提供的每个坐标、版本、查询、路径都必须视为不可信输入——作为单个引号包裹的参数传递绝不作为 shell 代码求值。先只读检查再写每一次写操作前都要先跑对应的只读检查得到用户明确批准后再执行任务先检查Inspect first再写入Write安装Installsearch、listinstall升级Upgradelist、upgrade --checkupgrade命名空间同步Namespace syncsync status、sync diff、sync pull --check选定的sync pull或sync push发布Publish检查包、publish --dry-runpublish移除Removelist精确的remove需要额外批准的操作如果用户当前请求没有明确指名该动作与目标以下操作必须先获得批准--force、--prune、remove --all、远程移除remove --remote、--hard、logout、doctor。反之一个指名了精确动作与目标的请求本身即视为对该动作的批准。当本地变更阻塞操作时不要自行替用户选择提交commit、备份、删除或丢弃策略——比如升级遇到本地改动时不能擅自决定丢弃改动或提交改动。坐标与目标如何精确定位一次安装四种坐标写法写法解析出的命名空间解析出的 slugslugglobalslugnamespace/slugnamespaceslugnamespace/slugnamespaceslugnamespace--slugnamespaceslug裸 slug 默认解析到global命名空间除非用--namespace指定了另一个命名空间坐标内的命名空间与命令行--namespace冲突时会被拒绝而不是静默覆盖。这套解析逻辑在 skill-name-parser.ts 中实现前缀要求存在/分隔符--双短横线是另一种分隔二者都不会出现在 slug 中slug 内含/直接判为非法坐标。已知坐标时优先使用完整坐标避免裸 slug 因多命名空间歧义而匹配到错误安装。Agent 目标与目录使用 live help 报告的 Agent profile如codex、claude-code多个目标重复传--agent。对不支持的 Agent使用用户选择的绝对--dir。--dir不能与--scope或--agent组合该互斥约束同样体现在 install.ts 与 sync.ts 的参数校验中。安装后的验证安装完成后用同一注册表与同一 Agent 过滤条件运行skillhub list确认已安装版本正确且目录下同时存在SKILL.md与.skillhub/metadata.json。list --json输出中会包含每个目标的namespace/slugversion、agent、installDir、installedAt与status目录缺失时标记为missing见 list.ts。升级已安装的技能升级只针对显式点名、且由 SkillHub 管理的安装没有隐式的 upgrade-all 模式。标准流程skillhub list --registry registry --json skillhub upgrade team/code-review --registry registry --check --json skillhub upgrade team/code-review --registry registry要点先展示 check 计划再写入。--check只生成计划不写文件。没有批准的--force时本地变更会阻止替换。以下情况绝不绕过即使有--force降级远端版本更旧、来源冲突非同一 SkillHub 来源、非托管目录、指纹不匹配、以及无法保持单一共享版本的部分目标选择。源码层面这些规则落在 upgrade-service.ts 中planSkillUpgrades会对每个目标做inspectTargets检查发现 legacy 相对路径、目标缺失、metadata 无效、来源冲突、本地变更指纹差异、缺文件基线、远端版本更旧、版本不可比较、同版本但远端内容变化等情况一律记为blockedupgrade-service.ts。版本比较基于 semverskill-version-order.ts文件指纹基于 SHA-256 逐文件哈希聚合skill-fingerprint.ts。单次升级最多接受 50 个坐标MAX_UPGRADE_SELECTIONupgrade-service.ts部分目标被拒绝是因为一条 inventory 记录对所有 target 共享同一个版本upgrade-service.ts。执行阶段某个升级提交后若后续失败执行即停止已提交的不回滚剩余记为not-attemptedupgrade-service.ts。同步命名空间工作区sync系列只用于已认证的非global命名空间global没有成员关系概念sync.ts 会直接拒绝。拉取前先做只读检查skillhub sync status --namespace team-a --dir skills-dir --registry registry --json skillhub sync diff --namespace team-a --dir skills-dir --registry registry skillhub sync pull --namespace team-a --dir skills-dir --registry registry --checksync status报告每个 Skill 的状态up-to-date、update-available、local-changed、blocked、orphaned、not-installed类型定义见 sync-service.ts。sync diff只列出有差异的条目及其变更文件路径。sync pull --check检查整个命名空间且不写任何本地文件。在非交互终端外写入式 pull 必须显式选择每一个 Skillskillhub sync pull --namespace team-a \ --skill code-review \ --dir skills-dir \ --registry registry交互式终端下 pull 会弹出多选列表空选择不变更任何内容。--force不能用于覆盖本地变更、--prune不能用于清理孤儿 Skill除非已经为确切受影响的路径获得批准--force只作用于显式选中的 Skill且永远无法绕过blocked类的发布安全检查远端版本更旧、版本顺序不可判定、同版本内容变化——这些场景需要核实发布后改用显式skillhub installsync-service.ts。孤儿远端已不存在默认保留只有同时给出--prune与对应的--skill才会移除且带本地变更的孤儿仍需--force。上传前先验证而不创建版本skillhub sync push --all \ --namespace team-a \ --dir skills-dir \ --registry registry \ --dry-run只有验证通过并确认后才追加--submit-review。一次提交可能返回SCANNING、UPLOADED、PENDING_REVIEW或PUBLISHED只有PUBLISHED能证明立即可安装--submit-review要求可见性为public或namespace-onlyprivate会被拒绝sync.ts。push对已存在的namespace/slug/version含仍处于 uploaded/pending review 的版本报告冲突但不会覆盖同一--all批次中的其他 Skill 继续处理。发布技能发布前先检查包并要求根级SKILL.md存在然后对选定注册表做校验skillhub publish ./my-skill \ --namespace team-a \ --visibility public \ --registry registry \ --dry-run--dry-run会把包字节实际发送给选定注册表做校验因此如果用户尚未要求校验或发布一个本地/私有包必须先获得批准。校验失败时修复校验错误而不是强行发布发布实现publish.ts会输出Validation passed/failed、解析出的Slug、Version以及逐条Errors/Warnings。去掉--dry-run重复提交前确认解析出的 namespace、slug、version、visibility 与包含文件。提交成功后会报告生命周期状态如SCANNING、PENDING_REVIEW成功的提交并不等于已发布最终发布/评审状态要在 Web 页面确认publish.ts 同时输出 detail 页面 URL。实现细节传入目录会被自动打包为 zip 并排除.skillhub元数据目录该目录只在安装时生成不属于发布内容publish.ts传入文件必须是 zip 归档visibility的public/namespace-only/private会被转换为服务端枚举PUBLIC/NAMESPACE_ONLY/PRIVATE。移除或修复先list再用完整坐标 最窄的目标过滤skillhub list --agent codex --registry registry skillhub remove team/code-review --agent codex --registry registry裸 slug 的移除可能匹配多个命名空间中同 slug 的安装因此优先使用带命名空间的完整坐标。远程移除是破坏性操作确认确切的 registry、namespace、slug。非交互环境下远程删除必须--hardremove.ts。--hard只是抑制交互式确认提示它从不授予权限。--all不能与--agent组合--remote不能与--agent或--all组合remove.ts。手工损坏或库存记录过期时用skillhub doctor重建库存。其流程是扫描cwd/.agent/skills/slug/.skillhub/metadata.json→ 按registry namespace slug分组 → 备份旧inventory.json如存在写到inventory.json.bak→ 原子写入新inventory.json扫描不到的目标会从旧库存中保留同一 skill 在多个 target 间版本冲突时跳过并报告doctor-service.ts。注意doctor不会替你解决已安装版本冲突只负责重建库存记录。故障排查症状检查方向未知命令或选项Unknown command or option检查 CLI 身份与两个 live help 面只有获批后才更新。认证失败Authentication failure确认 registry运行whoami让用户私下刷新凭据。安装目录错误Wrong installation directory检查list --json只有在选定明确的 scope、Agent 或目录后才重装。安装或升级被阻塞Install or upgrade blocked保留文件检查来源归属、元数据、版本方向与本地变更。发布校验失败Publish validation failed修复报告指出的包、元数据、权限或扫描器问题。库存过期Inventory stale运行doctor审查其结果并保留其备份。注册表错误Registry error保留服务端公开消息与requestId不要猜测服务端原因。排查命令的退出码也有迹可循CLI 定义了generic、auth、network、filesystem、usage、validation六类退出码constants.ts脚本可以根据退出码区分参数错误usage、校验失败validation与认证问题auth。认证与完成检查配合 SKILL.md 使用本文档假设身份已建立但需牢记 SKILL.md 的认证纪律永远不要让用户把 token 贴进聊天、提示词、Skill、命令历史或仓库。需要认证时让用户在自己的终端输入POSIX 下用read -rsp读入环境变量后skillhub loginPowerShell 7 用Read-Host -MaskInput随后用skillhub whoami --registry registry验证身份401/403通过登录或权限解决不要把认证失败当作访问其他注册表的许可。每次操作完成后向用户报告安装的坐标与版本注册表来源Agent profile 与安装目录SKILL.md与.skillhub/metadata.json是否存在当前 Agent 会话是否已加载该 Skill可观测时是否查询过其他注册表任何跳过的连接、认证、完整性或本地变更问题。对publish与sync push还要报告实际的生命周期状态SCANNING/UPLOADED/PENDING_REVIEW/PUBLISHED。当安装、目标发现、Agent 加载或完整性验证失败时不要宣称成功。延伸阅读主技能定义builtin-skills/skills/skillhub-cli/SKILL.md本文档来源builtin-skills/skills/skillhub-cli/references/cli-operations.mdCLI 完整用户指南cli/README.md命令实现cli/src/commandsinstall/list/search/upgrade/sync/publish/remove/doctor/login/logout/whoami/update 等服务层实现cli/src/servicesupgrade-service、sync-service、doctor-service、skill-fingerprint、skill-version-order、registry-service 等集成测试cli/test/integrationinstall-command、upgrade-command、sync-command、publish-command、remove-command、search-command、doctor-command 等赞分享人工智能AI AgentAI 技能后端前端【免费下载链接】skillhubSelf-hosted, open-source agent skill registry for enterprises. Publish version skill packages, govern with RBAC and audit logs, deploy on-premise with Docker or Kubernetes.项目地址https://gitcode.com/gh_mirrors/sk/skillhub点击查看免费下载相关推荐CodeIgniter 2.2.0 升级至 2.2.1 完整指南安全修复、时间区更新与升级操作步骤CodeIgniter 2.2.0 升级至 2.2.1 完整指南安全修复、时间区更新与升级操作步骤 本篇技术指南以官方升级文档 upgrade_221.rst后端Web框架SkillHub CLI 实战指南用官方 skillhub-cli 内置技能连接 Agent 注册表、安装与升级技能SkillHub CLI 实战指南用官方 skillhub cli 内置技能连接 Agent 注册表、安装与升级技能 导读本文以 SkillHub 官方内置人工智能AI AgentAI 技能后端前端Cloudflare Workers KV 完整配置指南命名空间创建、绑定声明、类型安全与 CLI/REST 操作Cloudflare Workers KV 完整配置指南命名空间创建、绑定声明、类型安全与 CLI/REST 操作 Cloudflare Workers KV上一篇Palmier Pro 的 MCP 集成实战让 Claude Code、Codex、Cursor 直接操控 macOS AI 视频编辑器下一篇GHelper免费开源上手指南华硕笔记本控制工具的完整配置流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考