技能一键发布（Edge/CDP 自动上传）
〇 定位与核心洞察
- 问题：
skillhub-publish的自动模式依赖已登录 Chrome 的 CDP（9223）。当用户机器没装 Chrome、或 Chrome 起不来时，自动发布失效，只能退回手动兜底。 - 洞察（已验证 2026-08-23）：发布脚本
publish_community.py只连接127.0.0.1:9223的标准 CDP WebSocket，浏览器无关——Microsoft Edge（Chromium 内核）完全可替代 Chrome。脚本不硬编码浏览器路径，只认端口。 - 本技能价值：把"用 Edge 自动发布"的可复用流程固化，覆盖启动、依赖、验证、排错，使任何无 Chrome 环境也能一键自动发布，无需依赖
skillhub-publish原目录（自带发布三件套）。
一 触发场景
- 用户要求把某个 skill 发布 / 升级到 SkillHub。
- 环境特征：Chrome 缺失、或
localhost:9223探测无响应；用户确认本机装有 Microsoft Edge。 - 不触发：用户只想本地改 skill、不想发布；或用户明确走手动上传（此时给清单即可，不要强制自动）。
二 前置依赖（一次性）
- managed Python venv（已隔离，不污染用户环境）：
<VENV>（例：C:/Users/<你的用户名>/.workbuddy/binaries/python/envs/default） - websocket-client（实测 managed python 3.13.12 默认未带，必须装）：
"<VENV>/Scripts/pip.exe" install websocket-client - Microsoft Edge 已安装（默认
C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe；64 位在C:\Program Files\Microsoft\Edge\Application\msedge.exe）。
三 标准流程（5 步）
> 所有命令在 Git Bash / CMD 执行；路径含空格必须加英文双引号。
Step 0 依赖校验（每次发布前跑一次，缺则装）
VENV="<VENV>"
"$VENV/Scripts/python.exe" -c "import websocket; print('ok', websocket.__version__)" || "$VENV/Scripts/pip.exe" install websocket-client
Step 1 彻底关闭所有 Edge 进程〔关键〕
- 否则旧 Edge 会"吃掉"新启动参数，只开新标签页、调试端口起不来。
- 任务管理器结束所有 msedge.exe（msedgewebview2.exe 是别的程序内嵌的，不用管）。
Step 2 用调试端口启动 Edge
"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9223 --remote-allow-origins=* https://skillhub.cn/dashboard
- 若复用默认 profile 报"profile 被锁"，加独立 profile（需重新登录 skillhub）：
"...msedge.exe" --remote-debugging-port=9223 --user-data-dir="<USERPROFILE>/.workbuddy/scratch/edge-skillhub-personal-profile" --remote-allow-origins=* https://skillhub.cn/dashboard
Step 3 验证端口真的起来了
curl -s http://localhost:9223/json/version
- 看到含
webSocketDebuggerUrl的 JSON = 成功；无响应 = 回到 Step 1（旧 Edge 没关干净）。
Step 4 在 Edge 中登录 skillhub.cn
- 若用了独立 profile，需重新登录（扫码 / 账号均可）；默认 profile 复用既有登录态。
Step 5 运行发布（本技能自带 scripts/publish_community.py，需 cd 进 scripts 目录以解析兄弟模块）
cd "<SKILL_DIR>/scripts"
VENV="<VENV>"
"$VENV/Scripts/python.exe" publish_community.py \
--folder "<SKILL_DIR>" \
--slug <slug> --version <新版本号> \
--display-name "<展示名>" --summary "<一句话简介>" --changelog "<变更说明>" \
--cdp-port 9223
- 脚本会：连 Edge → 导航 dashboard → 查 slug（own 则走升级迭代）→ 过门禁 → 打包上传 → 轮询审核状态。
四 发布前验证（不真正上传）
"$VENV/Scripts/python.exe" publish_community.py --check-slug <slug> --cdp-port 9223
- 返回
available=True表示该 slug 可发布（新技能，或你自己的技能升级）。
四·二 合规门禁的自定义禁用词（外置，不写进技能包）
scripts/preflight_check.py 的默认规则只含通用内部标识词，不含任何具体企业名——
这样技能包本身可以公开传播，不会把你的品牌词带给所有人。
要严查自家品牌词，有三个位置可叠加（后写的不覆盖前者，只追加）：
| 方式 | 位置 | 说明 |
|---|---|---|
| 环境变量 | SKILLHUB_PREFLIGHT_CONFIG 指向 JSON 文件 |
临时生效 |
| 用户级配置 | ~/.workbuddy/skills/.preflight_blocklist.json |
推荐，永久生效且不随任何技能包上传 |
| 命令行 | --config <路径> |
单次调用 |
JSON 格式：
{
"company_tokens": ["你的品牌名", "你的域名"],
"client_tokens": []
}
- 确认生效：运行
preflight_check.py <目录>时，stderr 首行会打印规则来源: 默认通用词, user:...，看到user:即说明用户级配置已加载。 - 品牌词写在包外，包内
preflight_check.py与SKILL.md始终不含任何真实企业名。
五 疑难排查
| 现象 | 原因 | 解决 |
|---|---|---|
localhost:9223 无响应 |
旧 Edge 没关，新参数被吃掉 | 回到 Step 1 彻底关 Edge 再启动 |
No module named websocket |
venv 缺 websocket-client | Step 0 安装 |
| HTTP 409 | 版本号 ≤ 线上版本 | 把 --version 调高于线上版本 |
| 门禁拦截（命中自有公司名/客户词等） | 合规预检命中 | 干净发布改词；或强发加 --no-preflight（自有品牌词确属己方时合理） |
profile 被锁 |
默认 profile 被占用 | 加 --user-data-dir 独立 profile（需重登录） |
六 边界与反虚构
- 绝不虚构：发布结果以脚本返回的 HTTP 状态码 / JSON 为准；不确定状态用
[待补充]标注，不臆测"已上线"。 - 门禁强发需用户明确授权：仅当用户确认某词为其自有公司时才加
--no-preflight；未授权不得擅自绕过。 - 本技能不负责撰写 / 修改待发布 skill 的内容，只负责把已就绪的 skill 自动发布出去。
六·常见错误与应对
| 错误类型 | 真实错误做法 | 为什么错 | 正确做法 |
|---|---|---|---|
| 不验端口直接发 | 略过 Step 1，直接跑发布 | Edge 未启动会报连接失败，浪费时间排查 | 先 curl http://127.0.0.1:9223/json/version 确认返回 |
| 版本号不校验 | 直接用本地 version 发布 | 低于线上会 409 Conflict，白跑一次 | 先查线上版本：skillhub skill list --namespace xxx 或用 --check-slug |
| 忽略门禁拦截 | 把含敏感词的内容直接发布 | 会被平台拦截，发布失败还可能封号 | 先用 --dry-run 预检；有敏感词需用户授权 --no-preflight |
| 不等异步完成 | 发完命令立刻查结果 | 平台有写入延迟，立即查可能返回旧状态 | 等待 2-3 秒后再查，或用脚本内的轮询逻辑 |
| 路径写死 | 写 C:/Users/xxx/... |
换机器路径失效，技能无法迁移 | 用相对路径或环境变量 ${SKILLHUB_DIR} |
| 忽略依赖版本 | 假设 websocket-client 已装 | 报错 No module named 'websocket' 才去装 |
文档里写清依赖，用 requirements.txt 或脚本内检查 |
七 交付质量门（发布前自检）
- [ ] Edge 调试端口 9223 已验证通（
/json/version有响应） - [ ] venv 已装 websocket-client
- [ ] skill 目录含合法 SKILL.md（带 frontmatter：name/slug/version/summary）
- [ ]
--version高于或等于线上版本（避免 409） - [ ] slug 经
--check-slug确认可发布 - [ ] 门禁词已处理（干净，或用户授权强发）
- [ ] 展示名 / 简介 / 变更说明已填
- [ ] 发布命令从 scripts 目录执行（兄弟模块可 import）
- [ ] 发布返回 HTTP 2xx 且
ok:true - [ ] 安全扫描 benign、reviewStatus 已知（pending / approved）
八 引用
- 本技能自带
scripts/：publish_community.py（主脚本）、cdp_driver.py（CDP 连接）、preflight_check.py（合规预检）。三者需同目录。 - 远程调试协议：Chrome DevTools Protocol（CDP，浏览器无关）。
