From 3cbf622c144b5b9faa47ebcb4db9e04c6f915465 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Thu, 3 Sep 2026 11:24:56 +0800 Subject: [PATCH] docs(compat): clarify canonical slug validation Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/openclaw-integration-en.md | 6 +++--- docs/openclaw-integration.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/openclaw-integration-en.md b/docs/openclaw-integration-en.md index 0719e075..3c022717 100644 --- a/docs/openclaw-integration-en.md +++ b/docs/openclaw-integration-en.md @@ -16,7 +16,7 @@ Current compatibility boundaries: - ClawHub CLI `0.23.3` uses `/api/v1/whoami`, which matches the SkillHub compatibility API. - ClawHub publishing depends on upload-ticket endpoints that SkillHub does not implement, so `clawhub publish` and `clawhub sync` are not supported. - ClawHub CLI `0.23.3` does not reliably prioritize the private Registry saved during `login`; site discovery or the default can select another target. Set `CLAWHUB_REGISTRY` in each shell session or pass `--registry` explicitly. -- Canonical slugs use `--` between namespace and skill. If either component itself contains `--`, the coordinate is ambiguous; use the first-party SkillHub CLI with its explicit `--namespace` option. +- Canonical slugs use `--` between namespace and skill. SkillHub rejects new namespace or skill slugs containing consecutive `--`, keeping new coordinates unambiguous. Rename invalid legacy or externally imported coordinates before using the ClawHub CLI. ## Quick Start @@ -127,7 +127,7 @@ npx @astron-team/skillhub@latest publish ./my-skill --namespace my-space Notes: - Publishing requires an API Token with the `skill:publish` scope and permission in the target namespace. - `clawhub login` and the SkillHub CLI do not share credentials; set `SKILLHUB_TOKEN` separately for the first-party CLI. -- The first-party CLI uses a separate namespace option and is not affected by canonical-slug delimiter ambiguity. +- The first-party CLI uses a separate namespace option, but it still follows the server's slug validation rules. ## API Endpoints @@ -189,7 +189,7 @@ SkillHub internally uses `@{namespace}/{skill}` format, but the compatibility la OpenClaw CLI uses canonical slug format, and SkillHub handles the conversion automatically. -The canonical format has no escaping rule. A namespace or skill slug containing `--` can map to the same string as another coordinate; use the first-party SkillHub CLI for such coordinates. +The canonical format has no escaping rule, so SkillHub rejects new namespace or skill slugs containing consecutive `--`. If legacy or externally imported data bypassed that validation, rename the coordinate first; the first-party CLI does not bypass server-side slug validation. ## Configuration Examples diff --git a/docs/openclaw-integration.md b/docs/openclaw-integration.md index 74989980..6aaff77d 100644 --- a/docs/openclaw-integration.md +++ b/docs/openclaw-integration.md @@ -16,7 +16,7 @@ SkillHub 提供 ClawHub 兼容 API，覆盖常用的只读发现和安装流程 - 已验证的 ClawHub CLI `0.23.3` 使用 `/api/v1/whoami`，与 SkillHub 兼容层一致。 - ClawHub CLI 的发布协议依赖 SkillHub 未实现的上传票据接口，因此 `clawhub publish` 和 `clawhub sync` 不属于支持范围。 - ClawHub CLI `0.23.3` 不会可靠地优先使用登录时保存的私有 Registry；站点发现或默认地址可能覆盖预期目标。每个终端会话都应设置 `CLAWHUB_REGISTRY`，或在命令中显式传入 `--registry`。 -- canonical slug 使用 `--` 分隔 namespace 与 skill。坐标任一部分自身包含 `--` 时无法无歧义解析，请改用第一方 SkillHub CLI 的显式 `--namespace` 参数。 +- canonical slug 使用 `--` 分隔 namespace 与 skill。SkillHub 会拒绝新建包含连续 `--` 的 namespace 或 skill slug，以保证新坐标可无歧义解析；历史或外部导入的异常坐标应先重命名，再使用 ClawHub CLI。 ## 快速开始 @@ -189,7 +189,7 @@ SkillHub 内部使用 `@{namespace}/{skill}` 格式，但兼容层会自动转 OpenClaw CLI 使用 canonical slug 格式，SkillHub 会自动处理转换。 -canonical 格式没有转义规则。namespace 或 skill slug 自身包含 `--` 时可能映射到相同字符串，必须改用第一方 SkillHub CLI。 +canonical 格式没有转义规则，因此 SkillHub 会拒绝新建包含连续 `--` 的 namespace 或 skill slug。若历史或外部导入数据绕过了该校验，应先重命名坐标；第一方 SkillHub CLI 虽使用独立 `--namespace` 参数，也不能绕过服务端 slug 校验。 ## 配置示例