From e57667ae60069890ccb040fbafd4944ea7d94483 Mon Sep 17 00:00:00 2001 From: FenjuFu Date: Tue, 16 Jun 2026 10:15:36 +0800 Subject: [PATCH] docs(faq): add CLI publish & deployment Q&A (zh & en) Add more community-sourced questions (both Chinese and English): - Troubleshooting CLI `skillhub publish` returning 400 (name conflict, SKILL.md location/frontmatter, namespace membership, etc.) - Required skill package structure (SKILL.md in root) - "malformed input" on publish caused by non-UTF-8 / Chinese-path zips - Per-package file-count limit and how to raise it - Minimum server version for CLI features (v0.2.7+) - PostgreSQL-only (no MySQL); plugins not distributable yet - How to check server/CLI versions and customize via secondary dev Signed-off-by: FenjuFu --- docs/skillhub/en/faq.md | 60 +++++++++++++++++++++++++++++++++++++++++ docs/skillhub/faq.md | 60 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md index e65541f6..9cf6d556 100644 --- a/docs/skillhub/en/faq.md +++ b/docs/skillhub/en/faq.md @@ -186,6 +186,66 @@ A: SkillHub has built-in security scanning. The scanner integration, task orches A: `scanner/Dockerfile` runs `pip install cisco-ai-skill-scanner` directly without pinning a version, so the latest version on PyPI is pulled when the image is built. To pin a version, do so yourself when customizing the build. +## Q: How do I troubleshoot a `registry returned 400` error from `skillhub publish` (CLI)? + +A: A 400 usually means backend validation failed. Common causes: + +- `SKILL.md` is not in the package root directory; +- `SKILL.md` frontmatter is missing `name` / `description` or is malformed; +- name or version conflict (e.g. `error.skill.publish.nameConflict`, meaning a skill with the same name is already published in that namespace) — change `name` in `SKILL.md`, use another namespace, or have an admin handle the existing skill; +- the namespace does not exist, or you are not a member of it; +- the package contains suspected tokens/secrets that the CLI cannot confirm skipping; +- file type / size / path is not allowed. + +You can inspect the server logs to locate the cause: + +```bash +docker logs --tail=300 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest' +``` + +## Q: What directory structure does a skill package require? + +A: The package root directory must contain a `SKILL.md` file, whose frontmatter must include fields such as `name` and `description`. + +## Q: Publishing fails with "package validation failed / malformed input" — what do I do? + +A: This error occurs while unzipping and reading file names, usually because the archive is not UTF-8 encoded (e.g. created with the built-in Windows compression tool) or contains Chinese/non-ASCII paths. Repackage using UTF-8 encoding and avoid Chinese / special-character paths. + +## Q: How many files can a skill package contain? What if I hit the file-count limit? + +A: The default limit is **100 files** (this is separate from the 100MB size limit). To raise it, change the `skillhub.publish.max-file-count` setting, or override it via an environment variable at deploy time: + +```bash +SKILLHUB_PUBLISH_MAX_FILE_COUNT=500 +``` + +Restart the containers for the change to take effect. Note that `compose.release.yml` must also reference this variable; older versions (e.g. v0.2.6) may hard-code the value, so upgrading to the latest version is recommended. + +## Q: Is there a server version requirement for using the CLI (publish / download, etc.)? + +A: A SkillHub server image of **v0.2.7 or later** is required for CLI features. + +## Q: Does SkillHub support MySQL? + +A: Currently only PostgreSQL is supported; MySQL is not supported. + +## Q: Can SkillHub be used to distribute Plugins? + +A: Not supported for now. + +## Q: How do I check the SkillHub version? How do I customize it (e.g. change the logo)? + +A: + +- Check the server image version: + +```bash +docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}' +``` + +- Check the CLI version: `skillhub version`. +- For customization (e.g. changing the logo), it is recommended to fork the latest code, modify it, and build your own Docker image. + ## Q: What should I do if I encounter issues? A: You can get help through the following channels: diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md index 4d9715fc..2aac0a54 100644 --- a/docs/skillhub/faq.md +++ b/docs/skillhub/faq.md @@ -186,6 +186,66 @@ A: SkillHub 内置安全扫描能力。其中扫描接入、任务编排、审 A: `scanner/Dockerfile` 中直接执行 `pip install cisco-ai-skill-scanner`，未锁定版本，因此构建镜像时会拉取 PyPI 上的最新版本。如需固定版本，可在二次开发时自行锁定。 +## Q: 使用 CLI `skillhub publish` 报错 `registry returned 400` 怎么排查？ + +A: 400 通常是后端校验未通过。常见原因： + +- `SKILL.md` 不在技能包根目录； +- `SKILL.md` 的 frontmatter 缺少 `name` / `description` 或格式错误； +- 名称或版本冲突（如 `error.skill.publish.nameConflict`，表示该 namespace 下已存在同名的已发布技能）——可改 `SKILL.md` 里的 `name`、换一个 namespace，或让管理员处理已有同名技能； +- namespace 不存在，或你不是该 namespace 的成员； +- 包内含疑似 token/secret，CLI 无法确认跳过； +- 文件类型 / 大小 / 路径不合规。 + +可用以下命令查看服务端日志定位： + +```bash +docker logs --tail=300 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest' +``` + +## Q: 技能包的目录结构有什么要求？ + +A: 技能包根目录必须包含一个 `SKILL.md` 文件，且其 frontmatter 需包含 `name`、`description` 等字段。 + +## Q: 发布时报“技能包校验失败 / malformed input”怎么办？ + +A: 该错误发生在 zip 解包读取文件名阶段，通常是压缩包不是 UTF-8 编码（例如用 Windows 自带压缩工具生成）或包内含中文路径导致。请使用 UTF-8 编码重新打包，并避免中文 / 特殊字符路径。 + +## Q: 技能包能包含多少个文件？提示文件数超限怎么办？ + +A: 默认上限为 **100 个文件**（这与 100MB 的大小限制是两回事）。如需放宽，修改配置项 `skillhub.publish.max-file-count`，或在部署时用环境变量覆盖： + +```bash +SKILLHUB_PUBLISH_MAX_FILE_COUNT=500 +``` + +修改后需重启容器生效。注意 `compose.release.yml` 中也需引用该变量；较旧版本（如 v0.2.6）可能将该值写死，建议升级到最新版本。 + +## Q: 使用 CLI（发布 / 下载等）对服务端版本有要求吗？ + +A: 需要 SkillHub 服务端镜像 **v0.2.7 及以上** 才支持 CLI 功能。 + +## Q: SkillHub 支持 MySQL 数据库吗？ + +A: 目前仅支持 PostgreSQL，暂不支持 MySQL。 + +## Q: SkillHub 可以用来分发 Plugin 吗？ + +A: 暂不支持。 + +## Q: 如何查看 SkillHub 的版本？想做定制（如修改 logo）怎么办？ + +A: + +- 查看服务端镜像版本： + +```bash +docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}' +``` + +- 查看 CLI 版本：`skillhub version`。 +- 如需定制（如修改 logo 等），建议基于最新代码进行二次开发并自行构建 docker 镜像。 + ## Q: 遇到问题怎么办？ A: 可以通过以下方式获取帮助：