| name | skill-publish-yashu |
| description | 把私有技能按白名单复制到公开技能目录。激活条件：用户消息须包含以下关键词之一:`发布技能`、`把技能公开`、`复制技能到公开目录`、`发布私有技能`。 |
| metadata | {"author":"牙叔教程","updated":"2026-07-20 12:00:00","version":"1.0.0"} |
发布技能到公开目录
功能概述
本 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 登记该条目，重新发布 |
