skillhub-publish

概述

SkillHub Publish

将任一 skill 准备好发布到 SkillHub。五步流水线：出发前确认 → 七维审计 → 确认修复 → 脱敏生成 → 打包交付；可选 Phase 5 经官方 CLI 自动上传（默认人工，逐字确认后才发布）。当前仅支持 WorkBuddy 发布。

文档入口：README.md（用户文档）| DESIGN.md（架构决策）| CHANGELOG.md（版本历史）

文件结构详见 README.md。

使用方式

发布 {skill名称} [版本号]

示例：发布 skill-creator-king v3.8.0

输入

• 目标 skill 名称（必填）：skill 目录名（平台根目录下的 skills/{name}/）
• 目标版本号（可选）：不提供时从 SKILL.md frontmatter 读取

目标路径：~/.workbuddy/skills/{name}/。用户显式提供本地 skill 目录时使用该目录；发布目标仍为 WorkBuddy。

依赖：Python 3.9+、Git（解析各级 .gitignore）。缺少依赖则停止并报告，不降级为未过滤复制。

Phase 0: 出发前确认（Pre-flight Checklist）

目标：在动手之前确认所有前提条件，避免走一半发现走不通。

步骤 0.1: 识别目标

1. 在 ~/.workbuddy/skills/{name}/ 定位目标；如用户明确给出目录则使用该目录。
2. 确认目标是目录，且包含可读的 SKILL.md。
3. 读取 frontmatter，获取当前版本号；用户未指定时使用当前版本号。
4. 目标平台固定为 WorkBuddy，无需询问平台。
5. 以当前实际加载的本工具 SKILL.md 所在目录定位 scripts/ 和 references/；不得从目标 skill 的路径推导工具路径。资源缺失则停止并报告。

步骤 0.2: 出示机票

以固定格式向用户展示出发前状态：

🎫 出发前机票
━━━━━━━━━━━━━━━━━━━━━━
Skill:     {name}
当前版本:   {current_version}
目标版本:   {target_version}
目标平台:   WorkBuddy
目录文件数: {file_count}
SKILL.md:  ✅/❌（存在/缺失）
DESIGN.md: ✅/❌
README.md: ✅/❌
CHANGELOG: ✅/❌
状态:      ✅ 可以出发 / ❌ 阻塞（原因）

阻塞条件：

• SKILL.md 不存在 → 阻塞
• 目标 skill 目录不存在 → 阻塞
• README.md 不存在 → 警告但允许继续

步骤 0.3: 凭据前置扫描（机械、先于一切读取）

在 AI 打开目标 skill 的任何文件之前，运行本 skill 自带的本地扫描器：

python3 "{本skill目录}/scripts/secret_scan.py" "{target_skill_dir}"

路径解析规则：使用步骤 0.1 确定的本工具实际目录，与被发布 skill 的位置无关。

为什么这一步必须在最前：内容一旦进入模型上下文就已离开本机——「读出来再判断是不是凭据」本身就是泄漏动作。因此凭据检测只能由本地脚本做、在任何读取之前做；AI 全程只见掩码引用（文件、行号、形态族、长度），永远不见原值，也不得为「验证真伪」去打开命中文件。

退出码语义：

• 0 干净 → 继续后续 Phase
• 1 发现候选 → 阻断审计：把掩码发现列表原样交给用户，请用户本地核实并处置（移入外部凭据源或换成文档化占位符），处置后重跑本步；在用户确认处置完成前，不得进入 Phase 1，不得打开 files with hits 列出的任何文件
• 2 扫描器自身出错 → 报告错误并停止，不允许以「人工通读」顶替

注意：Phase 3.5 的脱敏替换只保护发布包，不保护上下文——凭据防线是本步。

Phase 1: 七维审计（只读）

目标：在不修改目标 skill 任何文件的前提下，进行七维度全面审计。输出分 P0/P1/P2 三级。

维度 0: 后台兼容性扫描 — 正则卡死预检 🆕

触发条件：目标 skill 包含 README.md 或 DESIGN.md。

执行：运行本 skill 自带的 regex-hang-check.py（位于本 skill 目录的 scripts/ 下，按当前平台实际安装路径定位）：

python3 "{本skill目录}/scripts/regex-hang-check.py" "{target_skill_dir}"

路径解析规则：使用步骤 0.1 确定的本工具实际目录，与被发布 skill 的位置无关。

检查范围：在独立子进程中执行内置的历史 validate.py 文件树正则，超时后终止并回收子进程。它用于发现历史正则的回溯风险，不能证明线上当前审核器一定卡死或一定通过。

判断标准：

• 任意正则超时（>2 秒）或报告 ⛔ → P0，"README/DESIGN 触发内置历史正则超时"
• 报告 ⚠️（>0.5 秒）→ P1，"有回溯风险，建议精简"
• 报告 ✅ → 本项通过；退出码 2 表示无文档可检查，记录跳过；其他执行错误阻塞，不能当作通过

修复方案：精简 README/DESIGN 中的文件树，将同类文件合并：├── ... (12个文件) 替代逐行列出。

维度 1: 文件结构完整性

检查标准 skill 文件是否存在：SKILL.md, DESIGN.md, README.md, CHANGELOG.md

• 缺失关键文件 → P0
• 缺失非关键文件 → P1

维度 2: Frontmatter 字段检查

检查 SKILL.md frontmatter 字段：

检查占位符："待补充"、"TODO"、"FIXME"、"TBD" 等 → P1

维度 3: 内容质量检查

• frontmatter 必须能被 YAML 安全解析，description 必须为非空字符串 → P0
• description 按解析后的值去除首尾空白检查；应为单个文本段。源码可使用普通字符串、引号或 > / >- 折叠块，不按源码行数判错；值中仍有换行则列 P1，按确认清单整理
• description 长度 80-200 字 → P1
• description 人机双读体检 → P1：发布平台会直接展示该字段，但它同时是 AI 触发契约。要求三段式——首句为面向人的价值主张（回答「这工具帮我做什么」），中段核心能力，触发词集中在 Use when 尾段。动词堆砌开头、实现约束先于用户价值、缺 Use when 尾段 → 提示按三段式重写。落盘形式要求：Use when 尾段独立成段——folded 块中以两个空行与人读段分隔（单空行被 YAML 折叠为单个换行，无法按空行分切；两空行折叠为空白分隔，解析结果中机读段独占一行且人读/机读可按空行分切）
• README.md 是否包含"适合谁"/"快速开始"章节 → P2
• CHANGELOG.md 是否有最新版本的条目 → P1

维度 4: 版本一致性检查

交叉校验以下文件中的版本号：

• SKILL.md frontmatter version（顶层或 metadata 嵌套）
• DESIGN.md 版本号
• README.md 版本号
• CHANGELOG.md 最新条目版本号

不一致 → P0

维度 5: 安全扫描

扫描所有文件（scripts/ 下的 .py/.sh 文件深度检查）：

• 危险清理命令（如递归删除）未经保护 → P0
• 硬编码 API key / token / secret → P0
• 通过 subprocess 模块或 system 级调用执行外部命令 → P1
• 网络请求到非标准域名 → P1
• eval / exec 动态执行调用 → P1

维度 6: 外部依赖检查

• 脚本引用了不在标准库中的 Python 包 → P1
• SKILL.md 引用了不存在的 skill → P1
• 引用了未声明的第三方工具（如 CLI 工具） → P2
• frontmatter 中 bundled_files 引用的底座文件不存在 → P1
• bundled_files 中底座文件比内嵌内容新（内容未同步）→ P2

输出格式

🔍 七维审计报告 — {skill_name} v{version}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
P0（必须修复）: {count} 项
P1（强烈建议）: {count} 项
P2（可选优化）: {count} 项

各维度详情...

Phase 2: 讨论与确认

目标：用户审核审计结果，逐项决定修复策略。

⚠️ 执行约束：Phase 2 的 4 个步骤（2.1→2.2→2.3→2.4）必须逐个向用户确认，不可合并为一次交互。每步等用户回应后再进入下一步。

步骤 2.1: 展示审计结果

以结构化表格展示所有 P0/P1/P2 项，每项包含：

• 严重性标签
• 所属维度
• 问题描述
• 建议修复方案
• 预估影响

步骤 2.2: 逐项确认

用户决定：

• 修：接受建议修复方案
• 跳过：该问题不修复（P2 可跳过，P0 不可）
• 自定义：用户指定不同修复方案

P0 项不可跳过——这是硬约束。

步骤 2.3: 版本号确认

询问用户目标版本号：

• 保持当前版本（小修）
• 升 patch（bugfix）
• 升 minor（新功能/改进）
• 升 major（breaking change）

步骤 2.4: 生成修复清单 + 发布渠道确认

汇总所有"修"项的修复计划，用户确认后进入 Phase 3。

发布渠道二选一（必问，不可由 AI 代答或从其他指令推断）：随修复清单一并询问——

• 网页手动上传：流程终点为 Phase 4 交付报告，用户自行上网页发布
• CLI 自动上传：Phase 4 后接 Phase 5（登录态前置检查此时做），5.3 逐字终确认仍不可省

用户仅在本次会话明确选定后才按该渠道走到底；未回答渠道问题不得进入 Phase 3。「打包发布」「发更新」等指令只授权打包与发布意图本身，不隐含渠道选择。

Phase 3: 自动修复 + 生成物料

目标：按确认清单自动修复 + 生成标准发布物料。所有操作在桌面发布副本上进行。

步骤 3.1: 创建发布副本

前置 — 共用底座同步：读取目标 skill 的 SKILL.md frontmatter 中 bundled_files 字段。若存在，对每个文件：读取底座文件内容，计算 hash 或关键词特征，与 SKILL.md 中的内嵌内容对比。若底座比内嵌内容新 → 提示用户「⚠️ {文件名} 已更新，内嵌内容可能过期。是否需要手动同步后再发布？」。用户选择「先同步」→ 停止发布流程，等用户更新。用户选择「跳过」→ 标注「⚠️ {文件名} 可能过期」，继续发布。无 bundled_files 则跳过此步。

1. 目标为 ~/Desktop/{skill_name}-v{version}/。目标若已存在（包括链接），不得复用、合并或删除；改用带时间戳的新目录，并在交付报告中使用实际路径。
2. 调用本工具的打包脚本，路径作为独立参数传递：

   python3 "{本skill目录}/scripts/package-skill.py" "{target_skill_dir}" "{desktop_dest}"

脚本使用隔离 Git 索引解析源目录及子目录的 .gitignore，支持否定规则；不读取用户全局 Git 忽略设置，也不修改源目录。忽略规则同样作用于源仓库已跟踪文件。固定排除 .git、.gitignore、.gitkeep、.skillignore、__pycache__、.pyc/.pyo 和 .DS_Store，不复制空目录。拒绝未排除的符号链接及不支持的文件类型；失败则阻塞交付。

1. .skillignore 已停用。若目标仅有该文件，先报告并将其规则迁移到发布用的源副本 .gitignore，不得覆盖已有规则，经检查后再打包；不修改原始目录，也不能静默忽略其规则。新项目参考 templates/gitignore-template.md。
2. 文件类型白名单预检（2026-09-26 三次 400 学费）：dry-run 不查文件类型，平台只在真发时逐个报 400（LICENSE / requirements.lock / .gitignore 实测），且每次炸在终确认之后。打包后立即运行：

   python3 "{本skill目录}/scripts/adapt_file_types.py" "{desktop_dest}"

脚本处置发布副本内的黑名单命中：无扩展名文件加 .txt、.lock 改 -lock.txt、.gitignore/.skillignore 本体及伪装（.gitignore.tmp）删除，同步包内文本引用（.md/.yaml/.yml/.txt/.sh）。内容字节不变，源仓保留原名。变更清单进交付报告；发现新的黑名单类型（真发 400 实证）时把规则补进脚本并记录学费。

1. 从发布副本的 frontmatter 移除内部字段 bundled_files。保留 WorkBuddy 的其余字段，不执行跨平台字段剥离。

步骤 3.2: 按清单修复

根据 Phase 2 确认的修复清单，逐项执行：

• 更新 frontmatter 字段
• 修复占位符
• 统一版本号
• 修复安全问题
• 补充缺失文件
• description 修复：仅修复解析失败、空值或已确认的内容问题。不得仅因单行超过 120 字符而转换格式。需要折叠块时使用 >-，写回后重新解析并核对文本含义。按三段式体检：首句价值主张（人读）→ 核心能力（人读）→ Use when 触发尾段（机读）——发布平台会直接展示该字段，机器文体上架即「文笔差」。三段式落盘形式：人读段在前，Use when 尾段独立成段（folded 块内空一行分隔，解析结果中机读段独占一行）。
• 修复结束后再次确认内部字段 bundled_files 已移除，未误删 WorkBuddy 元数据。

步骤 3.3: 生成 README.md

参考 templates/readme-template.md 格式。如果 README.md 不存在或需要更新，生成包含以下章节的完整 README：

1. 一句话概述
2. 快速开始
3. 核心功能
4. 触发方式
5. 适合谁
6. 边界与注意事项
7. 文件结构

步骤 3.4: 生成 SkillHub 描述

参考 templates/description-template.md 格式。生成 80-200 字的 SkillHub 上架描述。落地方式按发布路径分流：

• 人工上传（默认）：网页上传发布副本文件并发布即可，无描述粘贴步骤——SkillHub 网页后台无描述编辑入口（2026-09-24 实证），详情页长描述由平台从包内容（README/SKILL）自动生成；描述文本随交付报告给出，供用户留档与发布后核对生成结果，不满意须改包内容（如 README 措辞）重新发布
• CLI 自动上传（Phase 5）：从描述中提炼一句话简介（含版本亮点），在步骤 5.1 以 --summary 注入发布副本 frontmatter——CLI 无描述参数，summary 是唯一随包带上去的简介；详情页长描述同样由平台从包内容生成，发布后在详情页核对，修正路径同上（改包重发，非网页编辑）

步骤 3.5: 生成版本更新说明

从 CHANGELOG.md 提取最新版本的条目，格式化为发布说明。

Phase 3.5: 内容脱敏

目标：对发布副本中的 .md 和 .yaml 文件执行内容脱敏，移除可能触发内容审核的敏感词。

步骤 3.5.1: 加载脱敏规则

按优先级加载：

1. 私有规则：~/.workbuddy/principles/sanitize_rules.yaml（用户自定义，优先）
2. 内置规则：references/sanitize_rules.yaml（通用基线，回退）

合并规则，私有规则同名覆盖内置规则。

步骤 3.5.2: 执行脱敏

对发布副本中所有 .md 和 .yaml 文件：

1. 读取文件内容
2. 按规则列表顺序应用正则替换
3. 写回文件

步骤 3.5.3: 脱敏报告

输出脱敏执行报告：

🛡️ 内容脱敏报告
━━━━━━━━━━━━━━━━━━
扫描文件: {count}
命中规则: {count}
替换次数: {count}

各规则命中详情...

注意：脱敏仅操作发布副本，不影响原始 skill 文件。脱敏替换只保护发布包，不保护上下文——凭据防线是步骤 0.3 的前置扫描。

Phase 4: 验证与交付

目标：最终验证发布包完整性，交付给用户。

步骤 4.1: 最终验证

对发布副本复查全部 P0 和本次已修复项；重新解析 frontmatter，确认目标版本、description 和 WorkBuddy 字段正确，内部 bundled_files 已移除。检查必需资源引用未因打包排除而丢失；失败则不得输出“发布包就绪”。未修复 P1/P2 如实记录。

步骤 4.2: 生成交付报告

📦 发布包就绪
━━━━━━━━━━━━━━━━━━━━━━━━━━━
位置:       {实际发布目录}
目标平台:   WorkBuddy
文件数:     {count}
审计状态:   ✅ P0 全部通过 / ⚠️ 有P1未修复
脱敏状态:   ✅ 已执行 / ⏭️ 未命中规则
元数据:     ✅ 已保留 WorkBuddy 字段并移除内部字段

📋 变更清单
- [修复] ...
- [生成] README.md
- [生成] SkillHub 描述

📤 下一步（网页手动渠道；CLI 渠道见下方分流注）
1. 打开 SkillHub 网页版
2. 上传实际发布目录中的全部文件并发布
3. 发布后核对详情页（长描述由平台从包内容生成，网页无描述编辑入口）

💡 或回复「自动发布」，经官方 CLI 上传（需已完成 skillhub login；正式发布前仍会向你逐字确认）

渠道分流（2026-09-26）：步骤 2.4 已选「CLI 自动上传」时，「下一步」替换为——1. 个人中心 → 我的 Skill 查看审核进度；2. 审核通过后核对详情页长描述与 summary 卡片简介，并省略自动上传提示行（渠道已定，不再二次提示）。

步骤 4.3: 交付

• 报告发布包位置
• 提供 SkillHub 描述文本（供留档与发布后核对；网页无粘贴入口）
• 如有未修复的 P1/P2，明确提示
• 交付报告「下一步」中以静态一行提示自动上传选项（见 4.2 模板）——不主动追问、不重复提示、不诱导
• 若用户已显式要求「自动发布/自动上传」（含看到提示后回复触发）→ 进入 Phase 5；否则到此结束

Phase 5: 自动上传（可选，默认跳过）

目标：仅在用户显式要求「自动发布/自动上传」时，通过 SkillHub 官方 CLI 上传发布副本。默认终点仍是 Phase 4 的发布包交付。

进入条件（满足其一）：①步骤 2.4 用户明确选定「CLI 自动上传」渠道；②用户明确说出「自动发布」「直接发上去」等意图（包括看到交付报告的静态提示行后回复触发）。否则本 Phase 整体跳过。安全闸门不在入口可见性，在步骤 5.3 的逐字终确认。

凭据铁律：API Key 永不进入上下文。login 由用户在终端自行执行，或由脚本读取环境变量 $SKILLHUB_KEY；AI 不读取、不打印、不转述 key 值，命令输出含 key 时按掩码处理。

步骤 5.0: 前置检查

1. CLI 存在性：command -v skillhub 或 ~/.local/bin/skillhub --version。缺失 → 出示安装命令并停止，不代装：

   curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only

用户装完回报 command not found 时：引导新开终端窗口，或用全路径 ~/.local/bin/skillhub 验证（安装路径在 ~/.local/bin，需 PATH 生效）。

1. 登录态：skillhub auth whoami 成功（输出 userId/handle/role）。失败 → 向用户出示下方首次发布决策树并停止，不得以「先发了试试」降级：

   🔑 首次发布引导（API Token 获取）
   ━━━━━━━━━━━━━━━━━━━━━━
   1. 浏览器打开直链：https://skillhub.cn/dashboard/keys
      ├─ 被弹回首页 → 未登录：右上角「登录」，手机号+验证码
      │   （首次登录自动注册），登录后重开直链
      ├─ 页面在、但没有「创建 API key」按钮 → 实名认证未完成：
      │   右上角头像 → 个人中心 → 实名认证（人脸核身，可手机扫码），
      │   状态「已认证」后重开直链
      └─ 页面正常 → 左下角「创建 API key」
   2. 弹窗显示 skh_ 开头的完整 token——只显示这一次，立即复制
      （丢失不慌：列表里删掉重建一把即可）
   3. 二选一完成登录：
      ├─ 你在终端执行：
      │   skillhub login --key skh_你的token --host https://api.skillhub.cn
      │   看到 ✓ Logged in as @你的handle 即完成
      └─ 或提供环境变量 SKILLHUB_KEY 后让我重试
   注意：SkillHub CLI 无浏览器 OAuth 登录，login 只接受 --key。

步骤 5.1: 发布元数据注入（仅发布副本）

官方 CLI 要求 frontmatter 含 slug / displayName，并建议含 summary（列表卡片简介），WorkBuddy 源文件通常没有。运行 scripts/inject_publish_meta.py（按本工具实际目录定位）：

python3 "{本skill目录}/scripts/inject_publish_meta.py" "{发布副本目录}" [--slug xxx] [--display-name "名称"] [--summary "一句话简介"]

• 缺省值取 frontmatter 的 name。已发布过的 skill 必须与线上 slug 一致才能发更新——不确定时先去线上详情页核对，再用 --slug 显式指定；displayName 建议用线上中文显示名。
• summary 由 Agent 按 Phase 3.4 产物提炼提供（一句话、含版本亮点）；缺失时脚本只警告不阻断——但走自动线时应提供，否则线上详情页沿用旧描述，叙事不更新。
• 只补缺失字段，已有字段不动（幂等）；只动发布副本。
• 退出码非 0 → 报告并停止。

步骤 5.2: dry-run 守门

skillhub publish "{发布副本目录}" --dry-run

失败 → 原样转述错误并停止；不擅自改动字段后重试。

步骤 5.3: 发布前终确认（不可省略）

展示：slug、version、changelog 摘要、目标 host（api.skillhub.cn）。用户逐字回复「发布」才继续；其他任何回应（含沉默、犹豫、反问）都保持不发布。此确认不可与 Phase 2 的确认合并。

步骤 5.4: 正式发布

skillhub publish "{发布副本目录}" --changelog "{CHANGELOG 最新版本条目摘要}"

步骤 5.5: 输出与错误处置

成功输出：

🚀 已提交发布
━━━━━━━━━━━━━━━━━━
slug:    {slug}
版本:    {version}
状态:    pending_review（审核中）
下一步:  个人中心 → 我的 Skill 查看审核进度；CLI 不自动上传图标，无 iconUrl 时使用默认占位图

错误处置表：

400 文件类型处置（2026-09-26 定）：平台一次只报一个坏文件，修复后重发是确定性动作，不占重试额度。处置 = 在发布副本内按 adapt_file_types.py 的同一规则改名（黑名单本体则删除）+ 同步包内引用，然后重新 publish；变更如实记入结果报告。同时把新类型补进脚本黑名单（只增不减需有真发 400 实证）。

终确认后自动适配的边界（A′ 枚举白名单，2026-09-26 觉者定）：终确认的授权覆盖达成已确认目标所必需的枚举内机械适配；枚举只有一项——文件改名到平台白名单后缀（含引用同步）。硬性不变量，违任一条必须回来问：

• 内容零改动（改名 ≠ 改写）
• 对外文案（summary / changelog / description）一字不动
• 版本号不动

枚举外的一切（含措辞调整、字段增删、依赖变更）→ 回报用户，得其确认再动。原则一句话：传输层适配可自动，内容层决策必回问。

其他错误：保留原始输出，报告并停止；任何错误未改动原样重试不超过一次（本地修复后的重发见「400 文件类型处置」，不属此类）。

Output

每次发布流程结束，输出以下交付物：

📦 发布包就绪
━━━━━━━━━━━━━━━━━━━━━━━━━━━
位置:       {实际发布目录}
目标平台:   WorkBuddy
文件数:     {count}

📋 变更清单
- [修复] ...
- [生成] README.md
- [生成] SkillHub 描述

📤 下一步
1. 打开 SkillHub 网页版
2. 上传文件并发布
3. 发布后核对详情页（长描述由平台从包内容生成，网页无描述编辑入口）

💡 或回复「自动发布」，经官方 CLI 上传（正式发布前仍会向你逐字确认）

渠道分流（2026-09-26）：步骤 2.4 选定 CLI 自动上传时，Output 的「下一步」替换为——1. 个人中心 → 我的 Skill 查看审核进度；2. 审核通过后核对详情页长描述（平台从包内容生成）与 summary 卡片简介，并省略自动上传提示行（已在渠道内）。网页手动渠道维持上方模板原样。

行为契约

不越界

• 不修改原始 skill 目录中的文件（所有操作在桌面副本）
• 默认不自动发布：Phase 5 仅在用户显式要求时进入，正式发布前须逐字确认
• 不删除原始文件

不编造

• 生成的 README 基于 SKILL.md + DESIGN.md 的实际内容
• 无法从源文件推导的内容 → 标记 <!-- TODO: 请补充 -->
• 审计报告仅报告事实

安全第一

• P0 安全项不可跳过
• 脱敏规则优先使用用户私有规则
• 发布副本在桌面，不接触受保护路径
• API Key 永不进入上下文：login 由用户终端执行或脚本读环境变量，AI 不见值