package-author

# 插件包标准化（package-author） 把用户给的工具/技能/脚本，整理成 pinvou 应用商店可导入的**标准插件包**。规范以 `docs/plugin-package-spec.md` 为准，本文件内置完整规则，可直接照做、不依赖文档可达。 ## 何时用 / 何时不用 - ✅ 用：用户要打包/标准化一个工具，给了文件/目录/脚本/SKILL.md/manifest.json/zip，或口头描述要一个插件包。 - ❌ 不用：用户只是"写个脚本"/"写个技能内容"而没说要打包；或是在装/卸载/开关某个已存在的工具。 ## 先弄清三件事（问清再动手，别猜） 1. **输入在哪**：用户给的是目录路径、粘贴的代码、还是 zip？文件类型是什么？ 2. **包类型**：纯技能？纯 MCP？还是 MCP+技能组合？（见 §类型判定） 3. **输出形态**：要一个**目录**（可直接 zip），还是直接产出 **zip**？ 若用户没给 id/名称，按内容起一个语义化小写 id（如 `weather-insight`），并告诉用户可改。 --- ## 类型判定（决定布局） | 用户给的东西 | 类型 | 标准布局 | |---|---|---| | 只有 SKILL.md 或技能目录 | 纯技能 Skill | `skills/<name>/SKILL.md` | | 一个 MCP server（脚本 + 描述） | 纯 MCP Mcp | `mcp/manifest.json` + `mcp/server.py` | | MCP + 配套使用引导技能 | 组合 Bundle | `mcp/` + `skills/<name>/` 同时存在 | --- ## 标准包结构（必须落成这样） ``` <id>/ ├── plugin.json ← 权威声明（见下） ├── mcp/ ← 纯 MCP / 组合包才有 │ ├── manifest.json │ └── server.py ├── skills/<name>/ ← 纯技能 / 组合包才有 │ └── SKILL.md └── icon.svg | icon.png ← 图标（缺失则生成，见 §图标） ``` --- ## plugin.json（schema v1） ```jsonc { "manifest_version": 1, // 必填，=1 "id": "weather-insight", // 必填，[a-z0-9-_]{1,64} 全小写 "name": "天气洞察", // 必填，展示名 "version": "1.0.0", // 可选（当前为预留字段，不驱动升级；更新包内容需更换包 id，或先删除 ~/.pinvou3/bundles/<id>/ 再导入） "description": "聚合天气查询与解读", // 可选 "icon": "icon.svg", // 可选，相对根，icon.svg/icon.png "components": { // 多组件用 "mcp_servers": [ { "id": "weather", "dir": "mcp" } ], "skills": [ { "id": "weather-interpret", "dir": "skills/weather-interpret" } ] } } ``` 硬规则： - `id` 全小写 `[a-z0-9-_]`，禁 `.`/`..`/路径分隔符；`name` 可任意可读文本。 - `components.mcp_servers[].dir` **写 `"mcp"`**（扁平单 server）；skills 的 `dir` 写 `"skills/<name>"`，且 `<name>` 必须等于该 SKILL.md frontmatter 的 `name`。 - 纯单组件可省略 `plugin.json`（导入走结构回退），但**标准化输出一律补上**（自描述）。 - 未知字段别乱加；当前只认 `components{mcp_servers,skills}`。 --- ## MCP 组件：mcp/manifest.json 本地 stdio server（最常见）： ```jsonc { "id": "weather", // [a-z0-9-_]{1,64}，与 plugin.json 声明一致 "name": "天气查询", "description": "查指定城市天气", "version": "1.0.0", "icon": "", // 空串即可（图标走包级 icon.*） "category": "life", // 分组 slug：dev/office/life/data/search… "mcp_tools": [], // 本地可为空：工具由 server 运行期 tools/list 声明 "command": "python", // 解释器：python / node … "args": ["server.py"] // 入口脚本名（推荐就叫 server.py） } ``` 硬规则： - 入口脚本**命名为 `server.py`**、`args: ["server.py"]`（安装时被重写为包内绝对路径）。 - 依赖 pip 包 → `"pip_dependencies": ["requests"]`（上传/导入安装路径不会自动执行 pip 安装，须提醒用户自行安装）。 - 密钥/Token **不写明文**：走 `config_fields`（`secret:true`）或 `secret_env`/`secret_headers`。 - 远程 HTTP/OAuth server：仍须保留 `"command": ""` 与 `"args": []`（manifest 必填字段），另以 `servers:[{name,url,scopes?,oauth?}]` 声明远程端点。 --- ## 技能组件：SKILL.md ```markdown --- name: weather-interpret # [a-zA-Z0-9_-]{1,64}（可大小写） description: 解读天气数据，用户要分析/解释天气结果时使用。 # 必填：做什么 + 何时用 --- # 正文：给模型看的指令 ``` - 若用户给的技能缺 frontmatter 或缺 `description`，**补上**（description 是触发依据）。 - 子资料放 `references/`，正文只列目录。 --- ## 图标 - 用户没给图标 → **生成一个 `icon.svg`**（简约扁平、单色几何图形，24×24 viewBox、 `stroke="currentColor"`、无外链/无脚本），并在 `plugin.json` 写 `"icon": "icon.svg"`。 - 只认 `.svg` / `.png`。用户给了图就校验扩展名，不合规则转 SVG 或换名。 - 禁止外链图片、禁止脚本、禁止超长/畸形 SVG。 --- ## 校验清单（交活前逐条过） 1. `plugin.json` 存在且 `manifest_version:1`、`id` 全小写合法。 2. 目录结构符合 §标准包结构；声明了 `components` 的 `dir` 都在包内、skill 目录有 `SKILL.md`。 3. MCP：`mcp/manifest.json` 的 `id/name/description/version/icon/category/mcp_tools/command/args` 八项齐（可空值但字段在），`command` 是解释器、`args` 指向 `server.py`。 4. 技能：`SKILL.md` frontmatter 有 `name` + `description`。 5. 图标：有 `icon.svg` 或 `icon.png`。 6. 无明文密钥/Token；无路径穿越名（`.`/`..`/分隔符）。 ## 产出 - 默认把标准化结果**写成一个目录**（相对工作目录，如 `<id>/…`），并列出文件清单。 - 用户要 zip → 用可用的打包方式压成 `<id>.zip`（根就是 `plugin.json`，别多套一层目录）。 - 收尾：一句话说明类型（纯技能/纯 MCP/组合）+ 落盘路径 + 如何在商店上传。