发布工作流模板

发布入口为 /api/workflows/publish，仅接受已授权学堂且账号具有发布权限的中央 API Key。账号发布权限与技能发布共用，见认证方式。本接口不接受网页登录 Cookie、会员安装口令或旧平台发布口令。

1. 准备 ZIP 与目录信息

ZIP 根目录必须有 workflow.json，guide 指向包内非空 HTML 文件：

{"slug":"meeting-workflow","version":"1.0.0","guide":"guide/index.html"}

ZIP 最大 32MB，解压后最大 128MB、最多 2000 个文件；不允许加密、符号链接或路径穿越。使用 UTF-8 HTML，图片、CSS、JS 随包携带；不要求 SKILL.md。指南和展示资源应允许公开预览，包内不放密钥和真实业务数据。

另存 catalog.json，slug、version 必须与 ZIP 清单一致，无需 publisher 字段：

{
  "slug": "meeting-workflow",
  "version": "1.0.0",
  "name": "会议纪要工作流",
  "summary": "把会议记录整理为纪要和待办",
  "category": "办公效率",
  "tags": ["会议"],
  "steps": ["准备记录", "整理纪要", "核对待办"],
  "changelog": "首次发布"
}

必填 slug,version,name；可选 summary,description,category,tags,steps,changelog,article。article 是从包内 HTML 和材料整理的 Markdown 正文，最多 30000 字符。名称最多 120 字符，简介 500、描述 12000、分类 60、更新说明 4000；tags 和 steps 各最多 12 项，每项分别最多 40、100 字符。分类默认“通用”。

2. 查询发布权限与已有版本

curl --fail-with-body 'https://link2.cn/api/workflows/publish' \
  -H "Authorization: Bearer ${LINGTU_API_KEY}"

curl --fail-with-body 'https://link2.cn/api/workflows/publish?slug=meeting-workflow' \
  -H "Authorization: Bearer ${LINGTU_API_KEY}"

不带 slug 返回 {publishAllowed:true,maxZipBytes:33554432}；带 slug 仅返回本人固定归属的模板及全部历史版本，包含未上架项，查询他人模板返回 403。首次发布前查询返回 404 时，仍需核对标识。账号没有发布权限返回 403。

3. 上传并回读验证

curl --fail-with-body 'https://link2.cn/api/workflows/publish' \
  -H "Authorization: Bearer ${LINGTU_API_KEY}" \
  --form-string "catalog=$(cat catalog.json)" \
  -F 'file=@meeting-workflow.zip;type=application/zip'

POST 只接受 multipart/form-data，字段为 catalog JSON 字符串和必填的 file ZIP。成功返回 {slug,version,sha256,repeated}。再次查询发布接口，核对目标 release 的版本和摘要，以及 status,currentVersion；已上架模板可在 /workflows/{slug} 查看。

首次发布直接上架且默认免费，固定归属首次发布账号；仅归属发布者可以更新。新版本成为当前版本，保留历史版本，已有模板保持原收费设置、价格、归属与上下架状态。新版本必须高于历史最高版本，即使后台曾切换到旧版也不能发布较低版本；构建后缀不用于版本递增。同版本需 ZIP 摘要和 changelog 一致，且显式提供的 article 与已存正文一致，才返回 repeated:true，不更新目录、不切换当前版本、不重新上架。修改同版本内容返回 409，需要新版本；仅编辑目录、推荐、排序或上下架使用管理员后台。

超时或 5xx 后先查询目标版本是否存在并校验摘要，再决定重试；409 后重新读取，不自动升级版本或覆盖。不要把重试成功等同于模板当前已上架。

安装 lingtu-workflow 0.2.6 即包含工作流发布与改价能力，无需另外安装发布技能。内置 scripts/publish_workflow.py 提供 inspect --zip、permissions、query --slug、publish --zip --catalog、pricing --slug、set-pricing --slug --revision --pricing-mode --price-fen 命令，使用进程环境变量 LINGTU_API_KEY。发布和改价后均会回读验证，改价规则见“工作流定价与购买”。

指南中的教程视频

<iframe data-workflow-video="实际内容slug" title="教程视频"></iframe>

站点将此标记替换为播放按钮，在指南沙箱外的主站播放器中打开 /workflows/video/{slug}，按原课程权限播放。只填写内容 slug，不嵌入视频地址、播放凭证或第三方 iframe。普通 HTTP(S) 外链由主站展示可由用户点击的新窗口链接。

管理员维护

上述接口只接受管理员网页登录，PUT/DELETE 还校验 Origin，中央 API Key 不可调用。PUT 必须提供 revision,pricingMode,priceFen,name,summary,description,category,tags,steps,featured,sortOrder,status,currentVersion；可选 article 仅修改 currentVersion 对应正文，省略时保留所有版本的整理稿。status 为 draft/published/archived，currentVersion 必须已存在。并发变化返回 409，刷新后再保存。

删除清理失败返回 503 并保留 deleting 状态；刷新取得最新 revision 后重试。成功保留 deleted 墓碑，slug 不可复用。不要将 SkillHub 的 version,updatedAt 删除参数用于工作流。