SkillHub 自动化发布专家（skillhub-publish-expert）

定位：帮助用户将已开发完成的 Skill 自动化发布到 SkillHub（https://skillhub.cn），发布后可被 Agent / 专家 / 专家团直接安装调用；覆盖登录态管理、合规脱敏检查、发布预检、发布执行与检查报告全流程。

一、能力概览

典型场景：「把我刚写好的 xxx skill 发布到 SkillHub」「检查这个 skill 能不能直接发布」「帮我更新 SkillHub 上的 xxx 到 v1.2」。

二、首次使用引导（先查登录态，再谈发布）

任何发布操作前，必须先确认登录态：

2.1 检测登录态

# 方式一：CLI 身份查询（推荐）
python ~/.skillhub/skills_store_cli.py auth whoami
# 输出 userId / handle / role 三行 = 已登录

# 方式二：检查本地凭证文件
ls ~/.skillhub/credentials.json

2.2 已登录 → 直接进入第三节发布 SOP

2.3 未登录 → 分两种情况引导

情况 A：用户已有 SkillHub 账户
1. 请用户提供 API key（skh_ 开头 Token）。获取路径：浏览器登录 https://skillhub.cn → 右上角头像 → 个人中心 → 左侧「API keys」（直链 https://skillhub.cn/dashboard/keys ）→「创建 API key」→ 弹窗只显示一次，请立即复制（丢失只能删掉重建）。
2. ⚠️ 提醒用户：密钥发到对话里后建议用后作废重建；对话记录不做密钥留存。
3. 执行登录（密钥只传给 CLI，不写入任何文件、不写进检查报告、回复中只展示 skh_**** 形式）：
bash python ~/.skillhub/skills_store_cli.py login --key <用户提供的skh_token> --host https://api.skillhub.cn
4. 复验：auth whoami 看到 userId / handle / role 即成功。

情况 B：用户没有账户（自动化注册的边界，如实说明）
- SkillHub 注册必须手机验证码登录 + 人脸核身实名认证，无法通过对话/API 纯自动完成——这是平台实名合规要求，本技能不绕过。
- 引导用户完成（约 3 分钟）：
1. 浏览器打开 https://skillhub.cn → 右上角「登录 / 注册」→ 手机号验证码登录（首次登录自动注册）
2. 头像 → 个人中心 → 「实名认证」→ 按提示完成人脸核身，看到「已认证」
3. 未实名将无法创建 API Token、无法发布（发布时报 403）
4. 按「情况 A」创建 API key 并提供给本技能
- 注册完成后回到情况 A 登录，之后进入发布 SOP。

2.4 CLI 未安装的处理（Windows）

• macOS/Linux（官方）：curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only
• Windows Git Bash 实测坑：官方 install.sh 的 mktemp+tar 报「Cannot connect to C」→ Python 手动安装：
  bash python -c "import urllib.request, tarfile, os, tempfile; d=os.path.expanduser('~/.skillhub'); os.makedirs(d, exist_ok=True); p=tempfile.mktemp(suffix='.tar.gz'); urllib.request.urlretrieve('https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/latest.tar.gz', p); tarfile.open(p).extractall(d)" python ~/.skillhub/skills_store_cli.py --version

三、发布检查 SOP（标准流程，按序执行）

第 0 步 登录态检查        → 未登录走第二节引导
第 1 步 发布单元确认      → 必须是「Skill 文件夹」（根目录含 SKILL.md），专家包整体不可直接发布
第 2 步 上传检查          → frontmatter / 目录结构 / 体积（preflight_check.py 自动）
第 3 步 合规与脱敏检查    → 敏感信息扫描（脚本自动）+ 人工复核清单
第 4 步 dry-run 本地预检  → skillhub publish <dir> --dry-run
第 5 步 输出检查报告      → 全项汇总给用户确认
第 6 步 用户确认后发布    → skillhub publish <dir> --changelog "..."
第 7 步 发布结果回执      → skillId / slug / 状态 / 详情页

第 1 步：发布单元确认（易错点 ⚠️）

SkillHub 只接受「Skill 文件夹」（根目录直接是 SKILL.md）或单个 .zip，不接受专家包整体（agents/.md + skills/ 结构）。
- 输入是专家包 → 先与用户确认发布其中哪一个 skill 目录，单独抽出为发布目录（本机先例：dist/skillhub-publish/<skill-name>/）。
- 输入是单 skill 目录 / .zip → 进入下一步。

第 2+3 步：自动检查（一条命令出结果）

python "<本技能目录>/scripts/preflight_check.py" <skill目录或zip> [--json]

脚本只读扫描、不联网、不改动任何文件；报告模板见第五节。

第 3 步补充：人工复核清单（脚本扫不全的语义级项）

• [ ] 内部系统 URL/域名、真实员工姓名+工号组合、客户数据样例、内部群名/群 ID
• [ ] 标识符类漏网项（本机实测踩坑：钉钉应用 Client ID dinglks**** 审计时漏网）→ clientId/appKey 类即便非密钥也建议脱敏
• [ ] license 是否合适（个人 Skill 建议 MIT）
• [ ] slug 是否带个人/组织前缀（降低 409 撞名概率）
• [ ] description 是否清晰说明触发场景

第 4 步：dry-run 预检

python ~/.skillhub/skills_store_cli.py publish <skill目录> --dry-run
# ✓ Dry-run passed: <slug>@<version> = 通过

第 5 步：输出检查报告（模板见第五节），等用户明确确认后才发布

第 6 步：正式发布

python ~/.skillhub/skills_store_cli.py publish <skill目录> --changelog "首次发布"
# 版本更新：slug 不变 + version 递增 + changelog 写清变更点

发布属写操作：必须先出示检查报告并取得用户明确同意，禁止擅自发布。

第 7 步：发布回执

成功输出 ✓ Published: skillId=xxxxx status=pending_review → 给用户：
- slug 与详情页 https://skillhub.cn/skills/<slug>（审核中不可见，属正常）
- 状态 = pending_review，审核通过后自动可见
- 可复核：python ~/.skillhub/skills_store_cli.py verify <slug> --json

四、敏感信息脱敏规则

4.1 脚本自动扫描的 11 类模式

4.2 脱敏替换标准

• 密钥/Token → skh_**** / sk-****（保留前 4 字符 + ****）
• 内网 IP → 10.x.x.x 或 <内网地址>
• 手机号 → 138****xxxx；身份证 → 前 6 后 2 保留
• 标识符类（clientId/appKey）→ 前 6 字符 + ****

4.3 红线

• 修复方式是修改源文件后重新检查，不允许「报告里写脱敏了但源文件没改」
• 密钥一经泄露进已发布版本，必须立即作废该密钥并发布脱敏后的新版本

五、检查报告模板（第 5 步输出）

# SkillHub 发布检查报告

- **检查对象**：<路径>（N 个文件，M KB）
- **检查时间**：<时间>
- **检查工具**：preflight_check.py v1.0 + 人工复核

## 一、上传检查
| 检查项 | 结果 | 说明 |
|--------|------|------|
| SKILL.md 存在且在根目录 | ✅/❌ | ... |
| frontmatter 必填字段 | ✅/❌ | 缺失字段列出 |
| slug 规范（唯一性前缀建议） | ✅/⚠️ | ... |
| version 格式（x.y.z） | ✅/❌ | ... |
| 目录体积 | ✅/⚠️ | 超限列出 |

## 二、合规与脱敏检查
| 检查项 | 结果 | 位置 |
|--------|------|------|
| 密钥/Token 扫描 | ✅ 0 处 / ❌ N 处 | 文件:行号 |
| 内网地址扫描 | ✅/❌ | ... |
| 个人 PII（手机号/身份证） | ✅/❌ | ... |
| 标识符复核（clientId/appKey/webhook） | ✅/⚠️ | ... |
| 人工复核项（语义级敏感） | 待用户确认 | ... |

## 三、dry-run 预检
- 命令与输出结果

## 四、结论
- ✅ 可发布 / ❌ 需修复（列出修复清单）
- 建议的发布命令（含 changelog 文案）

## 五、发布信息（发布后补填）
- skillId / slug / version / 状态 / 详情页

六、常见问题（FAQ，官方口径 + 实测）

七、命令速查

CLI="python $HOME/.skillhub/skills_store_cli.py"

# 登录态
$CLI auth whoami                  # 查身份
$CLI login --key <skh_...> --host https://api.skillhub.cn
$CLI auth logout                  # 登出（换号/密钥泄露时）

# 发布
$CLI publish <dir|zip> --dry-run
$CLI publish <dir|zip> --changelog "首次发布"
$CLI publish <dir|zip> --version 1.2.0 --changelog "..."   # 覆盖版本号

# 发布后验证 / 查重
$CLI verify <slug> --json
$CLI search <关键词>

# 自动检查（本技能）
python <本技能目录>/scripts/preflight_check.py <dir|zip>

八、参考文件

• references/publish-sop.md：官方教程（publish-via-cli）全文要点 + 本机实测踩坑展开（CLI 安装细节、注册流程、状态机、发布档案）
• scripts/preflight_check.py：自动预检脚本（只读、不联网、支持目录与 zip、--json 输出）