# Skill Publish Yashu

> 把私有技能按白名单复制到公开技能目录。激活条件：用户消息须包含以下关键词之一:`发布技能`、`把技能公开`、`复制技能到公开目录`、`发布私有技能`。

- Skill: `steelan9199/skill-publish-yashu` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add steelan9199/skill-publish-yashu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/skill-publish-yashu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: steelan9199 (https://skillmd.com/u/steelan9199)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/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` 运行命令。配置字段详细说明见 [发布流程与配置参考]($SKILL_DIR/references/publish-api.md)。

## 三层过滤机制

| 层级               | 作用                               | 配置位置                             |
| ------------------ | ---------------------------------- | ------------------------------------ |
| 第一层：全局白名单 | 顶层条目必须在白名单中才复制       | `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/references/publish-api.md)。

## 全业务脚本索引清单

| 脚本                            | 功能                                                                     |
| ------------------------------- | ------------------------------------------------------------------------ |
| `$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` 登记该条目，重新发布                       |