元守 yotta-publish-guard

元守（yotta-publish-guard）

发布前守门：把元阁「发布规范 + 已踩过的坑」固化成确定性 CLI——check 聚合校验、 pack 打包检查、versions 版本四件对齐、names 名称三通道查重、publish 发布命令封装， 任何智能体照流程走不踩坑。零依赖（Python 3.8+ 标准库），Windows + Linux + macOS 通用。

python3 scripts/yotta_publish_guard.py check ./yotta-my-tool

何时使用

• 新技能发布前，把校验 / 版本对齐 / 查重 / 打包检查 / 发布命令一次性跑完；
• 只推 GitHub（不推 npm / ClawHub），或只想给自用技能做本体检查；
• 改完既有技能准备升版本、重新三源发布前的复核。

Do NOT trigger：

• 不替用户做发布决策与最终人工审查——报告与命令只是辅助，是否发布由用户决定；
• 网络不可用时只降级为「需手动查重」提示，不伪造查重结果；
• 不做技能内容开发——造脚手架用元造（yotta-skill-creator），正文 / 脚本需人工开发。

快速使用

# 1) 发布就绪检查（full 档：完整发布件；可聚合元安 / 元审 / 元信 verdict）
python3 scripts/yotta_publish_guard.py check ./yotta-my-tool
python3 scripts/yotta_publish_guard.py check ./yotta-my-tool --with-audit --with-vetter --with-verify
python3 scripts/yotta_publish_guard.py check ./yotta-private --self-use

# 2) 打包检查 / 版本四件对齐 / 名称三通道查重
python3 scripts/yotta_publish_guard.py pack ./yotta-my-tool
python3 scripts/yotta_publish_guard.py versions ./yotta-my-tool
python3 scripts/yotta_publish_guard.py names ./yotta-my-tool

# 3) 发布命令封装（默认 dry-run 打印计划；--exec 直接执行；--force 显式跳过闸门）
python3 scripts/yotta_publish_guard.py publish ./yotta-my-tool
python3 scripts/yotta_publish_guard.py publish ./yotta-my-tool --github-only
python3 scripts/yotta_publish_guard.py publish ./yotta-my-tool --channels github,npm --exec

三档校验模式

子命令速览

• check：内置校验（三档模式）+ 可选聚合元安 / 元审 / 元信 verdict（未安装自动降级提示），输出发布就绪报告。
• pack：npm pack --dry-run 检查——包内无 pyc / pycache、关键文件（SKILL / LICENSE / README 中英）在包内；npm 不可用本地回退列举。
• versions：package.json / SKILL.md / CHANGELOG 顶部 / CLI VERSION 常量四件对齐。
• names：npm view / gh repo view / clawhub search 三通道查重；网络失败降级为手动查重提示。
• publish：生成发布命令计划（git init/add/commit → gh repo create --description + topic yottaskills → npm publish → clawhub publish），默认 dry-run，--exec 按序执行，--force 显式跳过推送闸门。

发布渠道（可选）

publish --channels github,npm,clawhub（缺省全渠道）或 --github-only——npm / ClawHub 都不是必选，只推 GitHub 时闸门用 github 档。详见 references/publish-flow.md。

推送闸门

publish 前先跑内置校验：有 ERROR 默认阻断（退出码 2）；--force 仅显式授权后可用。

退出码

行为锚点

1. 推送闸门默认阻断：未通过校验不得发布，--force 仅显式授权后可用。
2. 网络命令优雅降级：npm / gh / clawhub 不可用时输出「需手动查重」提示，不伪造结果。
3. 只读：不修改被测技能目录（除 npm pack 临时产物）；git init / commit 仅在 --exec 时执行。
4. 平台适配：Windows 下 .cmd/.bat 子进程经 cmd.exe 执行；npm 命令使用可写 --cache 目录。

与工坊 / 工具链分工

• 元守（本技能）= 守：发布前全量校验 + 发布命令封装；
• 元造 yotta-skill-creator = 造：生成合规脚手架（元守的 check 对元造脚手架直接 READY）；
• 仓库 tools/validate-skill.py 的规则 = 元守内置校验的自包含副本来源（发布包内带实现副本， 不依赖仓库 tools/）。
• 推荐链路：元造 create → 人工开发 → 元守 check → pack → versions → names → publish。

渐进披露

• references/check-items.md —— 校验项明细（三档模式 / 口吻黑名单 / 四方式安装 / 版本四件 / pack / names）
• references/publish-flow.md —— 三源发布流程与已踩坑清单（git 代理 / ClawHub --name / categories / gh --description / npm cache / 传播延迟）
• references/tutorial.md —— 中文教程（check → pack → versions → names → publish 全流程）