SkillHub 发布与改名工作流 v1.0.0

把本地 skill 发布到 https://skillhub.cn，支持三种动作：全新发布、本地改名、更新已存在 entry（不新建 slug）。

0. 环境（Git-bash / Windows 必看，否则命令找不到）

本机 bash 是 PortableGit 的，核心命令常不在 PATH，且原生 python3 不认 /c/... 路径。每条命令前先：

export PATH="$HOME/.local/bin:/usr/bin:/bin:/mingw64/bin:$PATH"
export TMPDIR="$HOME/.skillhub/tmp"      # 用 POSIX 路径，避免 tar/curl 把 C:\ 当远程主机
mkdir -p "$TMPDIR"

• skillhub 包装脚本在 ~/.local/bin/skillhub，内部已用 cygpath -w 把 CLI 的 python 路径转 Windows 路径，所以传 <skill目录> 给 publish 时用 Windows 风格路径 + 正斜杠 最稳，例如：
  C:/Users/Administrator/.workbuddy/skills/@user_88370eb4/my-skill
• 若 skillhub 报 command not found，先确认 ~/.local/bin 在 PATH（见上面 export）。

安装 skillhub CLI（仅首次；可复用，已踩坑）

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

直接跑常失败，绕过法：自己 curl ... -o ./latest.tar.gz（下到 CWD，别用 /tmp），tar -xzf，进解压目录 _kit/cli/ 跑 bash ./install.sh --cli-only（检测到本地 kit 跳过联网）。装完 skillhub 应可用。

1. 登录（拿到 skh_ Key 后）

skillhub login --key skh_xxxxxxxxxxxxxxxx

• 校验 GET /api/v1/auth/me 通过才写入 ~/.skillhub/credentials.json::user（明文存储，注意本机安全）。
• 之后 publish 自动读取凭据；也可 skillhub publish ... --token skh_xxx 覆盖。

2. 改名（本地 skill）

slug 硬约束正则：^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$
- 下划线 _ 会被拒绝 → 转连字符 -（如 zhiping_total_return_valuation → zhiping-total-return-valuation）。
- 改 SKILL.md 顶部的 name: 与 slug:，同时改脚本里类似 "skill": "..." 的自引用，必要时改目录名保持一致。
- name 可含中文/大写，slug 只能小写字母数字连字符。

3. 发布前清理（必做，否则服务端拒）

服务端拒绝 scripts/tang_valuation.py.bak_v20 这类「不允许的文件类型」。客户端自动排除 .pyc / .DS_Store / Thumbs.db，但 不排 *.bak / *.bak_vNN。发布前删掉：

rm -rf <dir>/scripts/__pycache__
find <dir> -type f \( -name '*.bak*' -o -name '*.tmp' -o -name '*.pyc' -o -name '.DS_Store' \) -delete

4. dry-run 预检（无 token 也能跑）

skillhub publish "<win路径>" --dry-run

只校验 metadata + 打包，不发包。通过会打印 ✓ Dry-run passed: <slug>@<version>。

5. 发布 / 更新（核心）

5a. 全新 slug（最常见）

skillhub publish "<win路径>" --version 1.0.0 --changelog "首次发布"

该 slug 成为该 entry 的默认/最新版本。

5b. 更新已存在的 slug（不新建 entry）—— 关键路径

目标：把新内容推到已经发布过的那个 slug 上，而不是生成一个新 slug。

做法：
1. 把待发布目录 SKILL.md 的 slug: 改成已发布的那个 slug（如 zhping-stock-buy-sell-evaluation）。
2. 用比现有更高的版本号（如现有 1.0.0 → 发 2.1.0）。
3. 建议用临时副本改 slug，别直接改本地已改名的 skill——否则本地 slug 会被污染。

SRC="C:/.../zhiping-tangchao-stock-buy-sell-skill"
TMP="C:/.../_publish_tmp"
rm -rf "$TMP"; cp -r "$SRC" "$TMP"
# 编辑 $TMP/SKILL.md：slug 改为已发布 slug，version 改为更高号
skillhub publish "$TMP" --version 2.1.0 --changelog "in-place update"
rm -rf "$TMP"

> ⚠️ 平台行为（重要）：发布会给该 entry 新增一个版本，但不一定把它提升为默认/最新版本——尤其该 entry 此前已有默认版本时。CLI 没有 promote / delete 命令。后果：用户直接 install <slug>（不带版本）可能仍拉到旧默认内容，只有 &version=2.1.0 能拿到新版。见第 7 节处理。

6. 验证（确认真的发上去了）

(a) 落库证明（最快）：同版本再发一次 --json → 返回 409 VERSION_EXISTS 即证明已落库。

skillhub publish "<win路径>" --version 1.0.0 --changelog "verify" --json
# 期望：{"success": false, "status": 409, "error": "slug 冲突: 版本 1.0.0 已存在..."}

(b) 版本化下载确认新版本可拉取：

TOKEN=$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.skillhub/credentials.json')))['user']['token'])")
curl -sL -o /tmp/s.zip -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" \
  "https://api.skillhub.cn/api/v1/download?slug=<slug>&version=2.1.0"
# 200 = 该版本存在；用 python zipfile 解 s.zip 读 SKILL.md 核对 version/name

(c) 端到端 install：

skillhub install <slug> --dir /tmp/verify --force --json
# success:true 即链路通

> 静态 zip（COS skills/<slug>.zip）与搜索索引是异步构建，发布后约 1 分钟内 download 接口从 404 转 200，属正常，可轮询 ?slug=<slug> 直到 200。

7. 平台限制与收尾（必读）

1. CLI 无 delete：任何残留 / 重复 / 旧 slug 条目，只能去 skillhub.cn 网页后台删除。
2. 默认版本不自动提升：若 install 或默认下载仍给旧内容，去网页后台把该 entry 的 current version 设为新版本；若过程中意外生成了重复 entry（如 Plan A 先发了新 slug），一并删掉，只留一个。
3. API Key 明文存于 ~/.skillhub/credentials.json。
4. 发布接口带安全审核（内容过滤 + 漏洞扫描 + AI 评估），非 2xx 会返回详细错误，按提示修。

命令速查

详细命令与 python 校验片段见 references/commands.md。