@coda-console/protocol 2.3.0 → 2.5.0

package/docs/executor-protocol.md

@@ -5,7 +5,7 @@
 2.2.0 按[第 7 步方案](https://github.com/coda-console/coda/issues/2078#issuecomment-6559423071)补齐流程接入：
 **无资源或一个资源的一单位**，可独占所申请资源；多单位、多资源原子申请仍未开放。
 
-协议对象版本 `protocolVersion: 1`、本目录的 v1、npm 包版本 2.3.0 和插件清单的 v2 分开演进。
+协议对象版本 `protocolVersion: 1`、本目录的 v1、npm 包版本 2.5.0 和插件清单的 v2 分开演进。
 本次只增加契约；不改变 `contributes.executors`，也不宣称 host、scheduler、空间引用解析或账本接口已经实现。
 
 ## 定义与登记

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器、流程方言与 Agent 接入协议",
   "type": "module",
   "license": "MIT",

package/schemas/plugin/plugin.json

@@ -7,6 +7,14 @@
   "properties": {
     "id": {"$ref": "common.json#/$defs/id", "description": "插件 ID：小写字母、数字和「-」，以字母开头，至多 40 个字符；不写就用 name"},
     "name": {"type": "string"},
+    "description": {"description": "一句话简介：插件列表里只显示一行，20 字以内为宜；更多的说明写在插件目录的 README.md，插件页里显示", "type": "string"},
+    "icon": {
+      "description": "插件的图标：插件目录里的 PDF（light 必填，dark 与 template 可选，同 Agent 的图标），或 SF Symbols 的符号画在系统色的底上（symbol 与 color）；客户端裁成圆角方块。不写时，只带一个 Agent 的插件用那个 Agent 的图标，其余用分类的默认图标",
+      "type": "object",
+      "if": {"required": ["symbol"]},
+      "then": {"$ref": "#/$defs/symbolIcon"},
+      "else": {"$ref": "#/$defs/fileIcon"}
+    },
     "categories": {"description": "分类：文本的数组，第一个是插件页里归的类", "type": "array", "items": {"type": "string"}},
     "coda": {
       "description": "Coda 宿主的安装要求；不写 channels 就不限制后端通道",
@@ -49,6 +57,23 @@
       "propertyNames": {"description": "contributes 的键：字母和数字，以小写字母开头", "pattern": "^[a-z][A-Za-z0-9]{0,39}$"}
     }
   },
+  "$defs": {
+    "fileIcon": {
+      "type": "object",
+      "properties": {"light": {"$ref": "agents.json#/$defs/icon"}, "dark": {"$ref": "agents.json#/$defs/icon"}, "template": {"description": "单色图标：按文字颜色画", "type": "boolean"}},
+      "required": ["light"],
+      "additionalProperties": false
+    },
+    "symbolIcon": {
+      "type": "object",
+      "properties": {
+        "symbol": {"description": "SF Symbols 的符号名，如 key.fill", "type": "string", "maxLength": 100, "pattern": "^[a-z0-9]+(\\.[a-z0-9]+)*$"},
+        "color": {"description": "底色：系统色 red、orange、yellow、green、mint、teal、cyan、blue、indigo、purple、pink、brown、gray 之一", "enum": ["red", "orange", "yellow", "green", "mint", "teal", "cyan", "blue", "indigo", "purple", "pink", "brown", "gray"]}
+      },
+      "required": ["symbol", "color"],
+      "additionalProperties": false
+    }
+  },
   "if": {"properties": {"activationEvents": {"minItems": 1}}, "required": ["activationEvents"]},
   "then": {"required": ["main"], "description": "写了 activationEvents 的插件须有 main"}
 }

package/schemas/plugin/views.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://coda.pub/schemas/plugin/v2/views.json",
   "title": "contributes.views：客户端为插件打开的页面",
-  "description": "插件目录里的 HTML，客户端在沙箱里开：在哪常驻（side 会话旁、page 一页），图标，接管打开的引用种类（handles，像 VS Code 的自定义编辑器），读数（readout）与只给哪种工作位置的会话（checkout）。",
+  "description": "插件目录里的 HTML，客户端在沙箱里开：在哪常驻（side 会话旁、page 一页），图标，接管打开的引用种类（handles，像 VS Code 的自定义编辑器），读数（readout），只给哪种工作位置的会话（checkout）与占位（frame：document 由客户端整页滚动、横向锁死，canvas 铺满视图、自己滚动）。",
   "type": "array",
   "maxItems": 10,
   "items": {
@@ -21,7 +21,8 @@
         "items": {"$ref": "common.json#/$defs/id"}
       },
       "readout": {"description": "读数：workflow-runs、machines、changes", "enum": ["workflow-runs", "machines", "changes"]},
-      "checkout": {"description": "只给哪种工作位置的会话：worktree", "enum": ["worktree"]}
+      "checkout": {"description": "只给哪种工作位置的会话：worktree", "enum": ["worktree"]},
+      "frame": {"description": "它怎么占位：document 由客户端整页滚动、横向锁死；canvas 铺满视图、自己滚动；不写暂与 canvas 相同", "enum": ["document", "canvas"]}
     },
     "required": ["id", "title", "entry"],
     "additionalProperties": false