skill-publish-yashu

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 登记该条目，重新发布