@coda-console/protocol 1.6.1 → 1.8.0

package/README.md

@@ -4,9 +4,21 @@ Coda 与插件之间的约定，Coda 和插件都引用它，独立演进：
 
 - **插件清单的类型**（`schemas/plugin/`）：插件目录 `package.json` 里 `contributes` 的每个键是一种类型，各有一份 JSON Schema（draft 2020-12，`$id` 为 `https://coda.pub/schemas/plugin/v1/<文件>`）。`plugin.json` 是整份清单，`setting.json` 是一项设置的声明。插件写的合乎它用到的类型就对；写给别的插件扩展点的键由那个插件声明，扩展点可以带自己的 schema（`extensionPoints.<名>.schema`，声明它的插件目录里的一个文件），写给它的东西合乎那份 schema 才对。
 - **通用校验器**（`validate.mjs`）：用 Ajv 对清单做 schema 校验。JSON Schema 说不了的只用五个通用关键字（`x-unique-by`、`x-max-contains`、`x-ref`、`x-placeholders`、`x-file`，照 Kubernetes 的 `x-kubernetes-*`），每个在哪里写都是同一个意思，写法见文件开头。校验器不随功能变长：类型加字段就是改 schema。
-- **流程方言**（`workflow/`）：项目和插件的流程（`.coda/workflows/*.bpmn`，BPMN 2.0）在 Coda 的命名空间 `https://coda.pub/schema/bpmn/1.0` 里能写什么。`moddle.json` 是 `coda:` 属性与元素（bpmn-moddle 的描述格式），`values.json` 是每个值能写什么（每个 `coda:` 类型的属性组成的对象的 JSON Schema，一个元素里同种 `coda:` 元素成组的 schema），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码、表达式能读的运行变量和运行的输入能是哪些类型。`workflow.mjs` 用它们读一份流程：方言里没有的、值不合 schema 的都拒绝，说法是「位置：schema 对那里的说明」。值的 schema 用清单的那几个关键字，另加三个：`x-feel`（是 FEEL：「=」开头是表达式，否则文字里的 `{{ … }}` 是，按这份流程里的名字读得通）、`x-duration`（ISO 8601 时长，不为负）、`x-number`（文字换算成数字是个有限的数）。流程的结构对不对（元素与事件、连接、补偿、走不到的步骤、事件启动），现在仍由 Coda 读流程时检查。
+- **流程方言**（`workflow/`）：项目和插件的流程（`.coda/workflows/*.bpmn`，BPMN 2.0）在 Coda 的命名空间 `https://coda.pub/schema/bpmn/1.0` 里能写什么。`moddle.json` 是 `coda:` 属性与元素（bpmn-moddle 的描述格式），`values.json` 是每个值能写什么（每个 `coda:` 类型的属性组成的对象的 JSON Schema，一个元素里同种 `coda:` 元素成组的 schema），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码、表达式能读的运行变量和运行的输入能是哪些类型。`workflow.mjs` 用它们读一份流程：方言里没有的、值不合 schema 的都拒绝，说法是「位置：schema 对那里的说明」。值的 schema 用清单的那几个关键字，另加三个：`x-feel`（是 FEEL：「=」开头是表达式，否则文字里的 `{{ … }}` 是，按这份流程里的名字读得通）、`x-duration`（ISO 8601 时长，不为负）、`x-number`（文字换算成数字是个有限的数）。`structure.json` 声明流程结构规则，`structure.mjs` 负责跨节点检查。
 - **Agent 接入协议**（`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
 
+流程方言的 **结构规则**从 1.8.0 起也由 `readWorkflow` / `workflowProblem` 检查。`workflow/structure.json` 声明支持的顶层元素与不支持的流程元素、各位置的事件定义、`coda:` 属性的位置限制、任务与多实例的局部写法、脚本数量、定时间隔和生命周期等待类型。`rules` 使用 JSON Schema 检查节点的无环投影（原始标量属性与父级、事件种类等固定事实），复用 `newAjv()` 和已有关键字；`moddle.json` 的 `extends` 仍声明属性可附着的基础类型。`CODA_STRUCTURE` 导出同一份表。新增局部规则改数据，不增加校验器分支。
+
+`structure.mjs` 的固定检查处理数据表无法单独表达的关系：事件子流程与顺序流、连接事件按作用域配对、事件网关的出口、补偿关联、经过子流程与边界事件的可达性、事件启动以及生命周期的「聋状态」。Coda 的事件名通过 `dialect.json` 的 `eventRoles` 读取；等待动作与节点类型也来自数据表。ISO 8601 重复间隔用 `@0dep/piso` 解析，脚本变量边界用固定的词法扫描检查，条件和 documentation 用同一份 FEEL 检查。图和嵌套树使用显式栈与 Map/Set，不递归、不把大数组展开成函数参数。报错尽量保留 Coda 的原位置与原话。
+
+读取定义时原有的 Coda 结构规则已全部纳入协议。Coda 接入 1.8.0 后，`parseBpmn` 只需调用 `readWorkflow`，再把 `root` 编译成引擎、任务、调度和图所需的结构；运行时才能知道的表达式结果、动态字段引用、调度设置实际值及能力是否存在，仍由宿主在运行时检查。
+
+流程方言的 **卡片字段**由 `workflow/fields.json` 定义：七种字段各能写哪些属性、必填项、文字长度与单行限制、路径与网址、视图参数、输入框与密钥选项；`values.json` 的 `Field` 引用它，`Fields` 声明读出 JSON 字段列表的表达式，`UserTask.children` 限定最多 12 个静态字段、id 不重复，以及全部字段已知时答复的 `fields` 只能引用输入字段（含按住出现的答复）。
+
+定义和运行时共用这一份 schema。`x-deferred` 包住一个 schema：读定义时，文字先检查 FEEL，表达式或含 `{{ … }}` 的模板留到打开任务后查；运行时只按包住的 schema 严格检查，不再把结果当表达式。只有内容属性使用它，`type`、`id`、布尔值、枚举和 `maxLength` 不放宽。另有 `x-length`（沿用 Coda 的 UTF-16 长度，可用 `{ "property": "maxLength" }` 读取同一对象的上限）、`x-json`（解析 JSON 文字或检查 JSON 值，按序列化后的 UTF-8 字节数限制大小）；`absolute-path`、`https-url` 两个 format 按本机路径与 URL 解析器检查。已有的 `x-ref` 增加 `key`（按数组元素的属性引用）和 `split`（逐个检查分隔后的名字）。这些操作都不改写输入。
+
+`fieldProblem(field, where)` 检查一个已求值的字段；`fieldsProblem(fields, where)` 检查展开并应用 `host`/`dir` 后的数组，复用同一份字段 schema、数量和唯一性规则。两者合法时返回 `null`，否则返回「位置：说明」；`where` 是调用方给出的完整位置。schema 的 `default` 仅作标注：默认值填充、去空白、域名转小写、`args` 解析后的保留、表达式求值、动态字段展开和用户答复的处理仍由 Coda 完成。`coda:fields` 的 `host`/`dir` 是可能被覆盖或忽略的备用值，定义时只检查 FEEL，合并后才检查实际字段。动态字段展开后，答复的输入引用仍须由 Coda 检查。
+
 ## 用法
 
 ```sh
@@ -25,12 +37,16 @@ pointProblem(panelsSchema, manifest.contributes.panels, 'contributes.panels', 'p
 ```
 
 ```js
-import { workflowProblem, readWorkflow, CODA_MODDLE, CODA_ACTIONS } from '@coda-console/protocol/workflow';
+import { workflowProblem, readWorkflow, fieldProblem, fieldsProblem, CODA_FIELDS } from '@coda-console/protocol/workflow';
 
 // 一份流程（名字不带 .bpmn，用在说明里）：方言里都有就返回 null，否则是一句说明。
 const problem = await workflowProblem(readFileSync('.coda/workflows/deploy.bpmn', 'utf8'), 'deploy');
 // 要接着读它的：{ root } 是解析好的 definitions，或 { problem }。
 const { root } = await readWorkflow(source, 'deploy');
+// 任务打开、接受答复时检查已求值的字段，不填默认值，不执行表达式。
+fieldProblem({ type: 'text', id: 'name', label: '名称' }, 'ask 的字段 name');
+fieldsProblem(JSON.parse(fieldsJSON), 'ask');
+// CODA_FIELDS 是同一份 fields.json，也可从 @coda-console/protocol/workflow/fields.json 导入。
 ```
 
 扩展点的 schema 和这里的并列：可以 `$ref` 协议的 schema（`common.json#/$defs/line40`），可以用五个关键字；它自己写的 `$id` 不算数，指针只指它校验的那份值里的位置。
@@ -49,7 +65,7 @@ const { root } = await readWorkflow(source, 'deploy');
 
 ## 谁在用
 
-- **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。读流程时先用 `readWorkflow` 按方言解析，再查每个值。
+- **Coda**：读插件时用它校验清单，再整理成自己的结构；只另看插件身份（ID、设置名在 ID 之下），以及装到一台机器上才知道的（来源、已装插件的冲突）。读流程时用 `readWorkflow` 同时校验方言、值与结构，再编译成引擎需要的数据。
 - **coda-plugins 的契约检查包**（`@coda-console/plugin-check`）：在写插件的地方用同一个校验器判清单。
 
 ## 版本

package/package.json

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

package/validate.mjs

@@ -10,7 +10,8 @@
 //   items having it, and so is `part`'s first group of each of its texts (a directory's last name), and `key` among the
 //   items and those in their `nested` arrays, at every depth (a task's answers and those offered on holding one);
 // - `x-max-contains`: { match, max } — of an object's values, at most `max` satisfy `match` (`maxContains` of an object);
-// - `x-ref`: { pointer, part?, match? } — the value (or `part`'s first group of it) names a key of the object, or an element
+// - `x-ref`: { pointer, part?, key?, split?, match? } — the value (or `part`'s first group of it), or each nonempty token
+//   separated by `split`, names a key of the object, or an element (with `key`, that property of an element)
 //   of the array, at `pointer` in the manifest: absolute (`/contributes/configuration/properties`), or relative to the value
 //   (`2/properties`: two levels up, then down); what it names satisfies `match` when that is given;
 // - `x-placeholders`: { names?, config? } — every `${…}` in the text is one of `names`, or `config:<setting>` naming one of
@@ -56,7 +57,7 @@ const META = {
   'x-unique-by': { type: 'array', minItems: 1, items: { anyOf: [{ type: 'string' },
     { type: 'object', properties: { part: { type: 'string' } }, required: ['part'], additionalProperties: false },
     { type: 'object', properties: { key: { type: 'string' }, nested: { type: 'string' } }, required: ['key', 'nested'], additionalProperties: false }] } },
-  'x-ref': { type: 'object', properties: { pointer: { type: 'string', pattern: '^(?:\\d+(?:/.*)?|/.*)$' }, part: { type: 'string' }, match: SCHEMA_VALUE },
+  'x-ref': { type: 'object', properties: { pointer: { type: 'string', pattern: '^(?:\\d+(?:/.*)?|/.*)$' }, part: { type: 'string' }, key: { type: 'string' }, split: { type: 'string' }, match: SCHEMA_VALUE },
     required: ['pointer'], additionalProperties: false },
   'x-placeholders': { type: 'object', properties: { names: { type: 'array', items: { type: 'string' } }, config: SCHEMA_VALUE }, additionalProperties: false },
   'x-file': { type: 'object', properties: { type: { enum: ['file', 'directory'] }, under: { type: 'string' }, suffix: { type: 'string' }, contains: { type: 'string' },
@@ -124,16 +125,24 @@ function keywords(ajv) {
   // A reference: whether `name` is a key (or element) of what `pointer` names, and that satisfies `match`.
   function resolves(self, ref, matches, name, cxt) {
     const { at, path } = locate(ref.pointer, cxt);
-    const key = Array.isArray(at) ? at.indexOf(name) : at !== null && typeof at === 'object' && Object.hasOwn(at, name) ? name : -1;
+    const key = Array.isArray(at) ? ref.key === undefined ? at.indexOf(name)
+      : at.findIndex(item => item !== null && typeof item === 'object' && Object.hasOwn(item, ref.key) && item[ref.key] === name)
+      : at !== null && typeof at === 'object' && Object.hasOwn(at, name) ? name : -1;
     return key !== -1 && (!matches || matches(self, at[key], `${path}/${escape(key)}`, cxt));
   }
   ajv.addKeyword({
-    keyword: 'x-ref', type: 'string', schemaType: 'object', metaSchema: META['x-ref'],
-    compile(ref) {
+    keyword: 'x-ref', type: 'string', schemaType: 'object', metaSchema: META['x-ref'], errors: true,
+    compile(ref, parentSchema) {
       const matches = ref.match !== undefined ? inner(ajv, ref.match) : null, part = ref.part !== undefined ? new RegExp(ref.part, 'u') : null;
-      return function (value, cxt) {
-        const name = part ? part.exec(value)?.[1] : value;
-        return name !== undefined && resolves(this, ref, matches, name, cxt);
+      const split = ref.split === undefined ? null : new RegExp(ref.split, 'u');
+      return function reference(value, cxt) {
+        for (const token of split ? value.split(split).filter(Boolean) : [value]) {
+          const name = part ? part.exec(token)?.[1] : token;
+          if (name !== undefined && resolves(this, ref, matches, name, cxt)) continue;
+          reference.errors = [{ keyword: 'x-ref', params: { value: token }, parentSchema, message: '引用不存在或类型不符' }];
+          return false;
+        }
+        return true;
       };
     },
   });

package/workflow/dialect.json

@@ -14,6 +14,7 @@
     "workflow.dispatch": "手动发起（workflow_run、客户端的按钮）：由事件启动的流程也订阅它，才能手动发起",
     "workflow.cancel": "要它停下：在等它的运行被告知，走到自己的结束，以取消结束"
   },
+  "eventRoles": {"lifecycleStart": "session.opened", "lifecycleFacts": "session.facts", "dispatch": "workflow.dispatch", "cancel": "workflow.cancel"},
   "userMessage": "^user\\.[a-z][a-z0-9-]{0,39}$",
   "stepFailed": "STEP_FAILED",
   "variables": ["inputs", "run", "github", "vars"],

package/workflow/fields.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schema/bpmn/1.0/fields.json",
+  "title": "人工任务卡片的字段",
+  "description": "字段须为对象",
+  "type": "object",
+  "allOf": [
+    {"required": ["type"], "description": "字段的 type 只能是 markdown、code、image、text、secret、link、view"},
+    {"properties": {"type": {"enum": ["markdown", "code", "image", "text", "secret", "link", "view"], "description": "字段的 type 只能是 markdown、code、image、text、secret、link、view"}}},
+    {"if": {"properties": {"type": {"const": "markdown"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/markdown"}},
+    {"if": {"properties": {"type": {"const": "code"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/code"}},
+    {"if": {"properties": {"type": {"const": "image"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/image"}},
+    {"if": {"properties": {"type": {"const": "text"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/text"}},
+    {"if": {"properties": {"type": {"const": "secret"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/secret"}},
+    {"if": {"properties": {"type": {"const": "link"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/link"}},
+    {"if": {"properties": {"type": {"const": "view"}}, "required": ["type"]}, "then": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/view"}}
+  ],
+  "$defs": {
+    "markdown": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "markdown"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "text": {"x-deferred": {"type": "string", "pattern": "\\S", "x-length": 4000, "description": "text 须为1–4000 个字"}}
+          },
+          "additionalProperties": false
+        },
+        {"required": ["text"], "description": "须写 text"}
+      ]
+    },
+    "code": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "code"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "text": {"x-deferred": {"type": "string", "pattern": "\\S", "x-length": 16384, "description": "text 须为1–16384 个字"}}
+          },
+          "additionalProperties": false
+        },
+        {"required": ["text"], "description": "须写 text"}
+      ]
+    },
+    "image": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "image"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "src": {
+              "x-deferred": {
+                "allOf": [
+                  {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 4096, "description": "src 须为一行、1–4096 个字"},
+                  {"format": "absolute-path", "description": "src 须为本机文件的绝对路径"}
+                ]
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        {"required": ["src"], "description": "须写 src"}
+      ]
+    },
+    "text": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "text"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "required": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/required"},
+            "default": {},
+            "maxLength": {"type": "integer", "minimum": 1, "maximum": 4000, "description": "maxLength 须为 1–4000 的整数"},
+            "multiline": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/multiline"},
+            "autofill": {"enum": ["username", "otp"], "description": "autofill 只能是 username、otp"}
+          },
+          "additionalProperties": false
+        },
+        {"required": ["id"], "description": "须有 id（字母或数字开头的字母、数字、「_」「-」，最长 40 个字符）"},
+        {"required": ["label"], "description": "须写 label"},
+        {
+          "if": {"properties": {"multiline": {"const": true}}, "required": ["multiline"]},
+          "then": {
+            "if": {"required": ["maxLength"]},
+            "then": {"properties": {"default": {"x-deferred": {"type": "string", "pattern": "\\S", "x-length": {"property": "maxLength"}, "description": "default 须为1–{maxLength} 个字"}}}},
+            "else": {"properties": {"default": {"x-deferred": {"type": "string", "pattern": "\\S", "x-length": 4000, "description": "default 须为1–4000 个字"}}}}
+          },
+          "else": {
+            "if": {"required": ["maxLength"]},
+            "then": {
+              "properties": {
+                "default": {"x-deferred": {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": {"property": "maxLength"}, "description": "default 须为一行、1–{maxLength} 个字"}}
+              }
+            },
+            "else": {"properties": {"default": {"x-deferred": {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 200, "description": "default 须为一行、1–200 个字"}}}}
+          }
+        },
+        {
+          "if": {"required": ["multiline"], "properties": {"multiline": {"const": true}}},
+          "then": {"properties": {"maxLength": {"default": 4000}}},
+          "else": {"properties": {"maxLength": {"default": 200}}}
+        }
+      ]
+    },
+    "secret": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "secret"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "required": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/required"},
+            "maxLength": {"type": "integer", "minimum": 1, "maximum": 65536, "description": "maxLength 须为 1–65536 的整数", "default": 65536},
+            "multiline": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/multiline"},
+            "masked": {"type": "boolean", "description": "masked 须为 true 或 false"},
+            "autofill": {"enum": ["username", "password", "otp"], "description": "autofill 只能是 username、password、otp"},
+            "keep": {
+              "enum": ["session", "memory", "use"],
+              "description": "keep 只能是 session（写进会话的密钥目录，流程拿到路径）、memory（只在后端内存里，本会话的桌面动作可反复用，流程拿到句柄）或 use（只在后端内存里，流程拿到句柄，用一次）",
+              "default": "session"
+            },
+            "host": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/host"},
+            "dir": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/dir"}
+          },
+          "additionalProperties": false
+        },
+        {"required": ["id"], "description": "须有 id（字母或数字开头的字母、数字、「_」「-」，最长 40 个字符）"},
+        {"required": ["label"], "description": "须写 label"},
+        {
+          "if": {"required": ["keep"], "properties": {"keep": {"const": "use"}}},
+          "then": {"not": {"required": ["dir"]}, "description": "dir 只用于 keep=\"session\" 或 keep=\"memory\" 的密文"}
+        },
+        {
+          "if": {"required": ["autofill"], "properties": {"autofill": {"enum": ["username", "otp"]}}},
+          "then": {"properties": {"masked": {"default": false}}},
+          "else": {"properties": {"masked": {"default": true}}}
+        }
+      ]
+    },
+    "link": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "link"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "href": {
+              "x-deferred": {
+                "allOf": [
+                  {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 2000, "description": "href 须为一行、1–2000 个字"},
+                  {"format": "https-url", "description": "href 须为 https 网址"}
+                ]
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        {"required": ["label"], "description": "须写 label"},
+        {"required": ["href"], "description": "须写 href"}
+      ]
+    },
+    "view": {
+      "allOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "view"},
+            "id": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/id"},
+            "label": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json#/$defs/label"},
+            "plugin": {
+              "x-deferred": {
+                "allOf": [
+                  {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 64, "description": "plugin 须为一行、1–64 个字"},
+                  {"pattern": "^\\s*[a-z0-9][a-z0-9-]{0,63}\\s*$", "description": "plugin 须为插件 ID（小写字母、数字和「-」）"}
+                ]
+              }
+            },
+            "view": {
+              "x-deferred": {
+                "allOf": [
+                  {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 40, "description": "view 须为一行、1–40 个字"},
+                  {"pattern": "^\\s*[a-z][a-z0-9-]{0,39}\\s*$", "description": "view 须为插件声明的视图 ID（小写字母开头的小写字母、数字和「-」）"}
+                ]
+              }
+            },
+            "args": {"x-deferred": {"x-json": {"schema": {"type": "object", "description": "args 须为不超过 4096 字节的 JSON 对象"}, "maxBytes": 4096}, "description": "args 须为 JSON 对象"}},
+            "presentation": {"enum": ["window", "inline", "side"], "description": "presentation 只能是 window、inline 或 side"}
+          },
+          "additionalProperties": false
+        },
+        {"required": ["label"], "description": "须写 label"},
+        {"required": ["plugin"], "description": "须写 plugin"},
+        {"required": ["view"], "description": "须写 view"}
+      ]
+    },
+    "id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$", "description": "须有 id（字母或数字开头的字母、数字、「_」「-」，最长 40 个字符）"},
+    "label": {"x-deferred": {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 40, "description": "label 须为一行、1–40 个字"}},
+    "required": {"type": "boolean", "description": "required 须为 true 或 false", "default": true},
+    "multiline": {"type": "boolean", "description": "multiline 须为 true 或 false"},
+    "host": {
+      "x-deferred": {
+        "allOf": [
+          {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 253, "description": "host 须为一行、1–253 个字"},
+          {
+            "pattern": "^\\s*(?=[a-zA-Z0-9.-]{4,253}\\s*$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\s*$",
+            "description": "host 须为网站域名，如 signin.aws.amazon.com"
+          }
+        ]
+      }
+    },
+    "dir": {
+      "x-deferred": {
+        "allOf": [
+          {"type": "string", "pattern": "^\\s*\\S(?:[^\\r\\n]*\\S)?\\s*$", "x-length": 80, "description": "dir 须为一行、1–80 个字"},
+          {"pattern": "^\\s*[A-Za-z0-9][A-Za-z0-9._-]{0,79}\\s*$", "description": "dir 只能是字母、数字、点、下划线和连字符，以字母或数字开头，最长 80 个字符"}
+        ]
+      }
+    }
+  }
+}

package/workflow/keywords.mjs

@@ -0,0 +1,104 @@
+// Value operations JSON Schema cannot express: defer checking an expression until it is read, measure UTF-16 text
+// (with a limit optionally named by a sibling), and validate JSON supplied as text or as a value, bounded in UTF-8 bytes.
+// None knows what a card field is. Schemas select the operations and their limits; validation never changes the input.
+import { isAbsolute } from 'node:path';
+
+// The byte length of a JSON value, without recursion or serializing the whole object. Stop as soon as the budget is
+// exceeded. Only JSON values count: cycles, non-finite numbers and non-JSON objects cannot turn into a different value.
+function jsonFits(value, max) {
+  let bytes = 0;
+  const active = new Set(), stack = [{ value }];
+  while (stack.length && bytes <= max) {
+    const frame = stack.at(-1);
+    if (frame.keys) {
+      if (frame.index === frame.keys.length) { active.delete(frame.value); stack.pop(); continue; }
+      const key = frame.keys[frame.index++];
+      bytes += (frame.index > 1 ? 1 : 0) + Buffer.byteLength(JSON.stringify(key)) + 1;
+      stack.push({ value: frame.value[key] });
+      continue;
+    }
+    if (frame.array) {
+      if (frame.index === frame.value.length) { active.delete(frame.value); stack.pop(); continue; }
+      if (frame.index++) bytes++;
+      stack.push({ value: frame.value[frame.index - 1] });
+      continue;
+    }
+    const item = frame.value;
+    if (item !== null && typeof item === 'object') {
+      if (active.has(item)) return false;
+      active.add(item);
+      bytes += 2;
+      frame.index = 0;
+      if (Array.isArray(item)) {
+        if (item.length > max) return false;
+        frame.array = true;
+      } else {
+        if (![Object.prototype, null].includes(Object.getPrototypeOf(item))) return false;
+        frame.keys = Object.keys(item);
+        if (frame.keys.length > max) return false;
+      }
+    } else {
+      if (typeof item === 'number' && !Number.isFinite(item)) return false;
+      if (item !== null && !['string', 'number', 'boolean'].includes(typeof item)) return false;
+      // JSON escaping cannot shorten a string, so avoid serializing one already over budget.
+      if (typeof item === 'string' && item.length > max - bytes) return false;
+      bytes += Buffer.byteLength(JSON.stringify(item));
+      stack.pop();
+    }
+  }
+  return bytes <= max;
+}
+
+export function valueKeywords(ajv, { feelProblem, isExpression }) {
+  ajv.addFormat('absolute-path', value => isAbsolute(value.trim()));
+  ajv.addFormat('https-url', value => { try { return new URL(value.trim()).protocol === 'https:'; } catch { return false; } });
+  ajv.addKeyword({
+    keyword: 'x-length', type: 'string', schemaType: ['number', 'object'], errors: true,
+    metaSchema: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'object', properties: { property: { type: 'string' } }, required: ['property'], additionalProperties: false }] },
+    compile(spec, parentSchema) {
+      return function length(value, cxt) {
+        const limit = typeof spec === 'number' ? spec : cxt.parentData && Object.hasOwn(cxt.parentData, spec.property) ? cxt.parentData[spec.property] : undefined;
+        if (Number.isInteger(limit) && limit >= 0 && value.length <= limit) return true;
+        length.errors = [{ keyword: 'x-length', params: { limit }, parentSchema, message: '文字过长' }];
+        return false;
+      };
+    },
+  });
+  ajv.addKeyword({
+    keyword: 'x-deferred', schemaType: ['object', 'boolean'], errors: true,
+    compile(schema) {
+      const validate = ajv.compile(schema);
+      return function deferred(value, cxt) {
+        // In a definition every textual value is also read as FEEL. At runtime even an expression-looking result is
+        // literal content; only a definition may postpone the wrapped schema's checks.
+        if (this?.definition && typeof value === 'string') {
+          const problem = feelProblem(value, this.names);
+          if (problem) { deferred.errors = [{ keyword: 'x-feel', params: {}, message: problem }]; return false; }
+          if (isExpression(value) || value.includes('{{')) return true;
+        }
+        const valid = validate.call(this, value, cxt);
+        deferred.errors = validate.errors;
+        return valid;
+      };
+    },
+  });
+  ajv.addKeyword({
+    keyword: 'x-json', schemaType: 'object', errors: true,
+    metaSchema: { type: 'object', properties: { schema: { type: ['object', 'boolean'] }, maxBytes: { type: 'integer', minimum: 0 } }, required: ['schema', 'maxBytes'], additionalProperties: false },
+    compile(spec, parentSchema) {
+      const validate = ajv.compile(spec.schema);
+      return function json(value, cxt) {
+        let parsed = value;
+        if (typeof value === 'string') try { parsed = JSON.parse(value); }
+        catch { json.errors = [{ keyword: 'x-json', params: {}, parentSchema, message: '不是 JSON' }]; return false; }
+        if (!jsonFits(parsed, spec.maxBytes)) {
+          json.errors = [{ keyword: 'x-json', params: {}, parentSchema: spec.schema, message: `须为不超过 ${spec.maxBytes} 字节的 JSON` }];
+          return false;
+        }
+        const valid = validate.call(this, parsed, cxt);
+        json.errors = validate.errors;
+        return valid;
+      };
+    },
+  });
+}