docs/skill-ui.md

# Skill 展示协议（skill-ui.json）

`skill-ui.json` 是可选的用户端展示清单，放在 Skill 根目录（与 `SKILL.md` 同级）。它只描述展示、输入和输出，不改变 `SKILL.md` 的 Agent 指令。

没有此文件时，系统会按以下顺序自动发现展示信息：README/USAGE/QUICKSTART、本地 `assets/`、`examples/`、`demo/`、`skill-workflow.json`、`SKILL.md`。打开详情不会运行 Skill、调用模型或扣除积分。

```json
{
  "version": "1.1.0",
  "author": "Example Studio",
  "source": {
    "label": "GitHub 开源",
    "url": "https://github.com/example/studio-skill",
    "author": "Example Studio",
    "version": "1.1.0",
    "openSource": true
  },
  "display": {
    "title": "商品海报设计",
    "description": "根据商品参考图生成电商海报。",
    "category": "视觉创作",
    "tags": ["海报", "电商"],
    "cover": "assets/cover.webp"
  },
  "capabilities": ["image", "html", "script"],
  "assets": [
    { "path": "examples/result-1.webp", "title": "竖版案例", "role": "gallery" },
    { "path": "demo/index.html", "title": "互动演示", "role": "demo" }
  ],
  "examples": [
    {
      "id": "poster",
      "title": "生成一张商品海报",
      "description": "保留商品外观并重新设计背景。",
      "prompt": "$studio-skill 把上传商品图制作成 3:4 高级电商海报。",
      "attachmentHint": "请上传一张清晰商品图"
    }
  ],
  "inputs": [
    { "id": "request", "label": "设计要求", "type": "text", "required": true },
    { "id": "image", "label": "商品参考图", "type": "image", "required": true }
  ],
  "outputs": [
    { "id": "poster", "label": "海报图片", "type": "image" },
    { "id": "gallery", "label": "互动展示页", "type": "html" }
  ]
}
```

支持的案例素材包括 PNG、JPEG、WebP、GIF、SVG、PDF、HTML、MP4、WebM、MP3 和 WAV。单文件上限 8MB；路径必须位于 Skill 目录内。HTML/SVG 默认在禁止脚本的沙箱中预览，HTML 交互只能由用户手动启用。

来源和作者的自动发现顺序为：`skill-ui.json` → `SKILL.md` frontmatter → `package.json` → `.install.json`。通过 GitHub 安装时，即使 Skill 没有声明作者，也会把仓库 owner 作为作者回退值并显示开源地址。

`skill-workflow.json` 中的 `summary`、`tasks` 和 `postprocess` 会被渲染成用户可读步骤。配置错误只会产生后台展示诊断，Skill 仍可按 `SKILL.md` 基础方式调用。

## 后台展示覆盖

管理员可以在 Skills 管理页编辑标题、简介、分类、标签、封面、案例和示例提示词。修改内容保存在 Skill 目录的 `.presentation-overrides.json`，优先级高于自动发现结果，但不会改写第三方 Skill 自带的 `SKILL.md`、README 或 `skill-ui.json`。管理员上传的封面和案例保存在 `.presentation-assets/`，仍遵循 8MB 单文件限制和图片类型白名单。

“AI 生成示例”会读取 Skill 协议及 README/USAGE/QUICKSTART 等本地文档，生成多条可继续编辑的示例；只有管理员主动点击时才调用模型，打开详情和切换案例不会触发模型或扣除积分。生成结果在管理员保存后成为稳定展示数据。

输入要求以 `skill-ui.json` 或后台覆盖中的 `inputs[].required` 为最高优先级。未显式配置时，只有文档明确要求“必须/需要上传图片”才把参考图片推断为必需；仅支持图片、可使用参考图或能够编辑图片时，参考图片默认是可选项。

## 用户收藏

收藏按登录用户隔离保存。用户可在 Skill 选择器的“我的收藏”中快速筛选，隐藏、删除或不存在的 Skill 不会继续出现在收藏列表中。收藏只影响用户端导航，不修改 Skill 文件，也不影响其调用权限。

## 更新与跨部署迁移

安装记录写在 Skill 目录的 `.install.json`，其中 `source` 是安装时使用的地址（GitHub 页面地址或 `upload:文件名.zip`）。Skills 管理页的「更新」按钮据此重新拉取并覆盖安装；由本地上传安装、或来源不是 http(s) 地址的 Skill 无法自动更新，需要重新上传新版 ZIP。

覆盖安装只替换包内文件。管理员在本地做出的决定会跨更新保留：脚本权限（`.permissions.json`）、展示覆盖（`.presentation-overrides.json`）、上传的展示素材（`.presentation-assets/`）和显示状态（`.visibility.json`）。覆盖前旧目录会整份备份到 `data/skills/.backups/<skill-id>/`，每个 Skill 保留最近 3 份，需要回滚时把对应快照拷回即可。

「导出全部」或单个 Skill 的导出按钮会生成一个 ZIP，内含每个 Skill 的完整目录（含上述管理文件）和描述本次导出的 `manifest.json`。缓存文件（`.user-guide-cache.json`）与 `__pycache__` 不会被打包。该 ZIP 可在另一套部署通过「导入 ZIP」直接安装，展示设置、脚本权限和展示素材一并还原——这是部署之间迁移 Skill 的推荐方式，不需要逐个重新配置。导入走管理员专用通道，归档上限高于普通仓库安装。