steelan9199/skill-publish-yashu

发布技能到公开目录

功能概述

本 Skill 用于把私有技能目录中的技能，按白名单规则复制一份到公开技能目录，确保只发布应当公开的文件，私密文件（license-key、备份、测试用例、临时文件等）绝不外泄。采用"白名单为主 + 每技能可覆写 + 硬黑名单兜底"三层防护机制。

适用场景：把开发完成的私有技能发布到公开技能库；私有技能更新后同步到公开技能库。每次只发布一个技能，不支持批量或全部发布。

环境说明

• 操作系统：Windows/Linux/macOS
• Node.js：>= 18.20.8
• Shell：PowerShell 5 / bash / zsh
• 本 Skill 运行命令时采用条件执行（前一条成功才执行下一条），跨平台规则如下：
  • bash/zsh：cmd1 && cmd2
  • PowerShell 5：cmd1; if ($?) { cmd2 }（PowerShell 5 不支持 &&）
  • 禁止单 &
• $SKILL_DIR 仅为文档占位符，不是环境变量，执行命令时必须替换为本 Skill 的实际绝对路径

路径与配置

| 配置项 | 位置 | 说明 | | ------------------------ | ----------------------------------------------------- | ------------------------ | | 源目录（私有技能目录） | $SKILL_DIR/scripts/config.json 的 sourceDir | 待发布的私有技能所在目录 | | 目标目录（公开技能目录） | $SKILL_DIR/scripts/config.json 的 targetDir | 发布目标目录 | | 全局白名单 | $SKILL_DIR/scripts/config.json 的 globalWhitelist | 允许复制的顶层条目清单 | | 硬黑名单 | $SKILL_DIR/scripts/config.json 的 hardBlacklist | 任意层级命中即排除的条目 |

AI 执行脚本前必须将 $SKILL_DIR 替换为实际绝对路径，再 cd 到 $SKILL_DIR/scripts 运行命令。配置字段详细说明见 发布流程与配置参考。

三层过滤机制

| 层级 | 作用 | 配置位置 | | ------------------ | ---------------------------------- | ------------------------------------ | | 第一层：全局白名单 | 顶层条目必须在白名单中才复制 | config.json 的 globalWhitelist | | 第二层：每技能覆写 | 单个技能可声明额外要包含的顶层条目 | 技能目录下的 .publish-include 文件 | | 第三层：硬黑名单 | 任意层级命中即排除，防御性兜底 | config.json 的 hardBlacklist |

判定顺序：硬黑名单 > 白名单/覆写。即先排除黑名单，再判断白名单。node_modules 在任意层级都排除（它可能出现在 scripts/ 等白名单文件夹内部，体积巨大）。

为什么用白名单：发布是安全边界，要排除的私密文件名字发散且不可预知（测试用例、备份、缓存、笔记），而要保留的结构标准化（SKILL.md、scripts、references）。白名单"默认安全"，漏项表现为"少发"（很快发现且可挽回），黑名单漏项表现为"泄露"（难发现且不可挽回）。

执行步骤

| 步骤 | 执行动作 | 具体命令/操作 | | ---- | ------------ | -------------------------------------------------------------------------------------------------------- | | 1 | 确认配置 | 读取 $SKILL_DIR/scripts/config.json，确认 sourceDir、targetDir 指向正确 | | 2 | 确定发布范围 | 用户指定单个技能名 -> 发布该技能（每次只能发布一个技能，不支持 all/批量） | | 3 | 执行发布 | 运行 cd $SKILL_DIR/scripts; if ($?) { node publish.js <技能名> } | | 4 | 查看报告 | 脚本输出该技能的"已复制/已跳过"清单，检查跳过项是否有误伤的合法文件 | | 5 | 补救误伤 | 若有合法文件被跳过（原因"不在白名单"），在该技能目录下创建 .publish-include 文件登记额外条目，重新发布 |

参数说明

node publish.js <技能名>     # 发布单个技能（每次只能发布一个）
node publish.js              # 不带参数时打印用法并列出可用技能

输出格式

脚本对每个技能输出结构化报告：

== 技能: coze-low-code-caller-yashu ==
源目录: <sourceDir>/coze-low-code-caller-yashu
目标目录: <targetDir>/coze-low-code-caller-yashu

已复制 (12):
  + SKILL.md
  + scripts/check_status.js
  + references/bot-api.md

已跳过 (5):
  - scripts-backup            [原因: 硬黑名单]
  - license-key.txt           [原因: 硬黑名单]
  - 测试用例.md               [原因: 不在白名单]
  - temp                      [原因: 不在白名单]
  - scripts/node_modules      [原因: 硬黑名单(任意层级)]

结果: 成功

.publish-include 文件格式与完整示例见 发布流程与配置参考。

全业务脚本索引清单

| 脚本 | 功能 | | ------------------------------- | ------------------------------------------------------------------------ | | $SKILL_DIR/scripts/publish.js | 按白名单+硬黑名单规则把技能从源目录复制到目标目录，输出已复制/已跳过清单 |

跨功能公共规则

• 执行脚本前必须 cd 到 $SKILL_DIR/scripts 目录
• 脚本通过 console.error 输出日志
• 目标技能目录若已存在，脚本终止发布并提示"技能文件夹已存在"，需用户手动删除后才能重新发布
• .publish-include 文件本身不会被复制到目标目录（在硬黑名单中）
• config.json（含用户私有路径）不在全局白名单中，不会被发布；只发布 config.default.json 模板

错误处理

| 错误场景 | 错误表现 | 处理方式 | | ------------------ | -------------------------- | -------------------------------------------------------------------------------- | | config.json 不存在 | 脚本报错找不到配置 | 从 config.default.json 复制一份为 config.json，填写 sourceDir、targetDir | | 源技能不存在 | 脚本报错找不到技能目录 | 检查技能名拼写，不带参数运行脚本可列出可用技能 | | 目标技能目录已存在 | 脚本提示"技能文件夹已存在" | 确认是否需要覆盖；如需重新发布，请先手动删除目标目录下该技能的文件夹 | | 目标目录不可写 | 脚本报错权限不足 | 检查目标目录权限，关闭占用该目录的程序 | | 源目录等于目标目录 | 脚本拒绝执行 | 提示源目录不能与目标目录相同 | | 合法文件被误跳过 | 报告中显示"不在白名单" | 在该技能目录下创建 .publish-include 登记该条目，重新发布 |