- 人工智能
- AI Agent
- AI 技能
- 后端
- 前端
【免费下载链接】skillhub
Self-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.
本篇指南以 skillhub-cli 技能 的配套参考文档 cli-operations.md 为核心，面向已经通过第一方@astron-team/skillhubCLI 连接 SkillHub 注册表、需要执行写操作（安装、升级、同步、发布、移除）的 Agent 与开发者。读完本文，你将掌握 SkillHub CLI 的「先只读检查、后显式写入」安全纪律、四种坐标写法、命名空间工作区的状态/差异/拉取/推送全流程，以及故障排查与结果上报的规范；文中每一条规则都对照了 CLI 源码 中的实际实现，可直接在真实注册表上安全复现。
使用前提：先解析注册表，再确认第一方 CLI
cli-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） |
|---|---|---|
| 安装（Install） | search、list | install |
| 升级（Upgrade） | list、upgrade --check | upgrade |
| 命名空间同步（Namespace sync） | sync status、sync diff、sync pull --check | 选定的sync pull或sync push |
| 发布（Publish） | 检查包、publish --dry-run | publish |
| 移除（Remove） | list | 精确的remove |
需要额外批准的操作
如果用户当前请求没有明确指名该动作与目标，以下操作必须先获得批准：--force、--prune、remove --all、远程移除（remove --remote）、--hard、logout、doctor。反之，一个指名了精确动作与目标的请求本身即视为对该动作的批准。
当本地变更阻塞操作时，不要自行替用户选择提交（commit）、备份、删除或丢弃策略——比如升级遇到本地改动时不能擅自决定"丢弃改动"或"提交改动"。
坐标与目标：如何精确定位一次安装
四种坐标写法
| 写法 | 解析出的命名空间 | 解析出的 slug |
|---|---|---|
slug | global | slug |
namespace/slug | namespace | slug |
@namespace/slug | namespace | slug |
namespace--slug | namespace | slug |
裸 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/slug@version、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 无效、来源冲突、本地变更（指纹差异）、缺文件基线、远端版本更旧、版本不可比较、同版本但远端内容变化等情况，一律记为blocked（upgrade-service.ts）。版本比较基于 semver（skill-version-order.ts），文件指纹基于 SHA-256 逐文件哈希聚合（skill-fingerprint.ts）。单次升级最多接受 50 个坐标（MAX_UPGRADE_SELECTION，upgrade-service.ts）；部分目标被拒绝是因为一条 inventory 记录对所有 target 共享同一个版本（upgrade-service.ts）。执行阶段某个升级提交后若后续失败，执行即停止，已提交的不回滚，剩余记为not-attempted（upgrade-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 必须显式选择每一个 Skill：
skillhub sync pull --namespace team-a \ --skill code-review \ --dir <skills-dir> \ --registry <registry>交互式终端下 pull 会弹出多选列表，空选择不变更任何内容。--force不能用于覆盖本地变更、--prune不能用于清理孤儿 Skill，除非已经为确切受影响的路径获得批准；--force只作用于显式选中的 Skill，且永远无法绕过blocked类的发布安全检查（远端版本更旧、版本顺序不可判定、同版本内容变化）——这些场景需要核实发布后改用显式skillhub install（sync-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-only，private会被拒绝（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。非交互环境下远程删除必须
--hard（remove.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 login，PowerShell 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.md
- CLI 完整用户指南：cli/README.md
- 命令实现：cli/src/commands（install/list/search/upgrade/sync/publish/remove/doctor/login/logout/whoami/update 等）
- 服务层实现：cli/src/services（upgrade-service、sync-service、doctor-service、skill-fingerprint、skill-version-order、registry-service 等）
- 集成测试：cli/test/integration（install-command、upgrade-command、sync-command、publish-command、remove-command、search-command、doctor-command 等）
- 人工智能
- AI Agent
- AI 技能
- 后端
- 前端
【免费下载链接】skillhub
Self-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.
相关推荐
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
