技能发布器

把本机技能推到魔搭社区 Skills 中心，支持增量：只发新增和改动过的。

自然语言怎么用

直接说就行，不用记命令：

「把这个技能同步到魔搭」
「把我刚做的 skill 发到魔搭社区」
「更新一下魔搭上的 XX 技能」
「skills 目录里改过的都同步上去」

指代不明时必须先确认，不许猜。 用户说「这个技能」但没指明是哪个时：

先看对话上下文——如果是刚才一起写出来的技能，那就是它，可以直接发
上下文也没有，就跑 python scripts/publish.py --recent 列出最近改过的自建技能，把列表给用户挑，不要自己选一个发出去
发布是不可逆的公开操作。发错仓库比多问一句的代价大得多

发布前检查：目标目录必须有 SKILL.md，没有就不是可发布的技能，直接说明而不是硬发。

默认范围：用户说「同步/上传/发上去」但没指定时，跑 --changed（只发有变动的），不要跑 --all——避免一次误发一堆没动过的技能。

先确认配置

凭证读环境变量 MODELSCOPE_API_KEY / MODELSCOPE_OWNER，没有就读 ~/.workbuddy/skill-publisher-config.json：

{
  "token": "ms-xxxx",
  "owner": "你的魔搭用户名"
}

Token 在 https://www.modelscope.cn/my/myaccesstoken 获取（只显示一次）。用户名看个人主页地址栏 modelscope.cn/profile/<用户名> 的最后一段。

配置文件必须在技能目录之外。放在技能里会被打包上传，token 就泄露了。

日常用法

cd ~/.workbuddy/skills/skill-publisher
python scripts/publish.py --list      # 看每个技能是 未发布 / 有改动 / 已同步
python scripts/publish.py --changed   # 只发有变动的（最常用）
python scripts/publish.py skill-name  # 发指定技能
python scripts/publish.py --all       # 全部自建技能重发

先看再发是稳妥习惯；--dry-run 可演练，不产生任何请求。

市场技能默认跳过。 带 _skillhub_meta.json 的技能是从市场安装的，本来就在魔搭上，重传只会制造重复仓库，所以 --all 和 --changed 都不碰它们。确实要发得显式加 --include-market。

增量是怎么判断的

每个技能按内容算一个指纹（sha256，前 16 位），算之前把换行符统一规范化，所以编辑器在 CRLF/LF 之间来回切换不会被误判成"有改动"。指纹与上次发布时一致就跳过。

--force 可无视指纹全部重发。想重置某个技能的状态，删掉 state 文件里对应的那一项即可。

显示名与分类怎么来

按优先级从 SKILL.md 的 frontmatter 取：

display_name → 页面展示名；不写则取 description 第一个句号前的片段
category → 分类；不写默认 developer-tools
tags → 逗号分隔
description → 同时作为技能简介提交

所以想要页面好看，就在 frontmatter 里补 display_name 和 tags，本脚本会一并带上去。

脚本自动挡掉的坑

这三个都是实测踩过的，脚本已内置校验，失败时会直接报错而不是发出去：

zip 根目录必须恰好 1 个 SKILL.md — 不能把技能文件夹整个套一层再压。
SKILL.md 必须是 LF 换行 — CRLF 会让服务端 YAML 解析器认不出 ---\r，报 frontmatter must contain 'name' field（文件里明明有 name，报错极具误导性）。脚本只在打包时于 zip 内转 LF，不改动你的源文件。
JSON 请求体不能带 BOM — 带 \ufeff 会报 InputParameterError: invalid request body。

另外自动排除 node_modules、__pycache__、.git、*.log、*.zip、config.json，遇到限流会自动退避重试。

已发布状态记在哪

~/.workbuddy/skill-publisher-state.json，记录每个技能的内容指纹、file_id、发布时间和链接。删掉某项即可让它下次被当成"未发布"重发。

常见错误对照

| 回执 | 原因 | 处理 | |---|---|---| | invalid request body | 请求体带 BOM 或字段非法 | 用本脚本，不要手写 curl | | frontmatter must contain 'name' | SKILL.md 是 CRLF | 脚本会自动转，仍报错则检查文件是否只读 | | Too Many Requests | 请求太密 | 脚本已留间隔；等 1 分钟再跑 | | 401 / Unauthorized | token 错或权限不足 | 重新生成 token，权限要能写 | | ResourceNotFound 且是更新时报 | owner 写错 | 核对个人主页地址栏 | | 上传成功但创建失败 | 通常是 zip 结构问题 | 看脚本报的具体原因 |

更新已有技能

同一技能名再次运行会走更新（PATCH .../settings），不会重复建仓库。 owner 和 skill_name 创建后不可改，要改名只能新建一个再删旧的。