@coda-console/protocol 1.6.1 → 1.7.0

package/README.md

@@ -7,6 +7,12 @@ Coda 与插件之间的约定，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`（文字换算成数字是个有限的数）。流程的结构对不对（元素与事件、连接、补偿、走不到的步骤、事件启动），现在仍由 Coda 读流程时检查。
 - **Agent 接入协议**（`docs/agent-protocol.md`）：Coda 怎样用 ACP 接 Agent，以及 Coda 加的扩展（会话指令、插话、`_coda/wait`、执行失败、工具调用的审核）。
 
+流程方言的 **卡片字段**由 `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 +31,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` 不算数，指针只指它校验的那份值里的位置。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "1.6.1",
+  "version": "1.7.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/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;
+      };
+    },
+  });
+}

package/workflow/values.json

@@ -171,10 +171,77 @@
     "UserTask.children": {
       "type": "object",
       "properties": {
-        "choice": {"type": "array", "maxItems": 6, "x-unique-by": [{"key": "id", "nested": "choices"}],
-          "contains": {"type": "object", "properties": {"primary": {"const": true}}, "required": ["primary"]}, "minContains": 0, "maxContains": 1,
-          "description": "最多 6 个 coda:choice，最多一个主按钮；所有答复的 id（包括按住出现的）不重复"}
-      }
+        "choice": {
+          "type": "array",
+          "maxItems": 6,
+          "x-unique-by": [{"key": "id", "nested": "choices"}],
+          "contains": {"type": "object", "properties": {"primary": {"const": true}}, "required": ["primary"]},
+          "minContains": 0,
+          "maxContains": 1,
+          "description": "最多 6 个 coda:choice，最多一个主按钮；所有答复的 id（包括按住出现的）不重复"
+        },
+        "field": {"type": "array", "x-unique-by": ["id"], "description": "coda:fields 须为字段的 JSON 数组", "allOf": [{"maxItems": 12, "description": "最多 12 个字段"}]}
+      },
+      "allOf": [
+        {
+          "if": {"not": {"properties": {"fields": {"minItems": 1}}, "required": ["fields"]}},
+          "then": {
+            "properties": {
+              "choice": {
+                "items": {
+                  "allOf": [
+                    {
+                      "properties": {
+                        "fields": {
+                          "type": "string",
+                          "x-ref": {
+                            "pointer": "/field",
+                            "key": "id",
+                            "split": "[\\s,]+",
+                            "match": {"type": "object", "required": ["type"], "properties": {"type": {"enum": ["text", "secret"]}}}
+                          },
+                          "description": "fields 里的 {value} 不是这个任务的输入字段"
+                        }
+                      }
+                    },
+                    {
+                      "properties": {
+                        "choices": {
+                          "items": {
+                            "properties": {
+                              "fields": {
+                                "type": "string",
+                                "x-ref": {
+                                  "pointer": "/field",
+                                  "key": "id",
+                                  "split": "[\\s,]+",
+                                  "match": {"type": "object", "required": ["type"], "properties": {"type": {"enum": ["text", "secret"]}}}
+                                },
+                                "description": "fields 里的 {value} 不是这个任务的输入字段"
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "Field": {"$ref": "https://coda.pub/schema/bpmn/1.0/fields.json"},
+    "Fields": {
+      "type": "object",
+      "properties": {
+        "value": {"type": "string", "pattern": "^\\s*=", "x-feel": true, "description": "coda:fields 须用 value 写一个「=」开头的表达式（字段的列表）"},
+        "host": {"type": "string", "x-feel": true, "description": "host 是展开后 secret 字段未另写 host 时的备用值"},
+        "dir": {"type": "string", "x-feel": true, "description": "dir 是展开后非 keep=\"use\" 的 secret 字段未另写 dir 时的备用值"}
+      },
+      "required": ["value"],
+      "description": "coda:fields 须用 value 写一个「=」开头的表达式（字段的列表）"
     }
   }
 }

package/workflow.mjs

@@ -5,12 +5,14 @@
 // the types a run's inputs take. Coda reads a workflow with them, and coda-plugins' contract check does where a plugin is
 // written. readWorkflow refuses what the dialect does not have and a value of it its schema does not take; how the
 // process itself is put together is still Coda's to check as it reads the workflow.
-// What JSON Schema cannot say of a value it says with three keywords of its own, besides the manifests' (validate.mjs):
+// What JSON Schema cannot say of a value it says with these keywords, besides the manifests' (validate.mjs):
 // - `x-feel`: true, or { names } — the value is FEEL: an expression when it starts with `=`, else text whose every
 //   `{{ … }}` holds one, each reading by name what the workflow has (its nodes and messages, the run's variables, a loop's
 //   element), or only `names`;
 // - `x-duration`: true — the value is an ISO 8601 duration, not negative;
 // - `x-number`: true — the text, read as a number, is a finite one (`1e999` reads as none).
+// workflow/keywords.mjs adds x-deferred (check FEEL now, the result later), x-length (UTF-16 text length, optionally
+// limited by a sibling), x-json (a JSON value or its text, with a byte budget), and absolute-path / https-url formats.
 import { parseDuration } from '@0dep/piso';
 import { BpmnModdle } from 'bpmn-moddle';
 import { parseExpression } from 'feelin';
@@ -19,10 +21,13 @@ import moddle from './workflow/moddle.json' with { type: 'json' };
 import values from './workflow/values.json' with { type: 'json' };
 import actions from './workflow/actions.json' with { type: 'json' };
 import dialect from './workflow/dialect.json' with { type: 'json' };
+import fields from './workflow/fields.json' with { type: 'json' };
+import { valueKeywords } from './workflow/keywords.mjs';
 
 export const CODA_MODDLE = moddle;
 export const CODA_NAMESPACE = moddle.uri;
 export const CODA_VALUES = values;
+export const CODA_FIELDS = fields;
 // Each action by name, with the parameters it takes (`coda:param`).
 export const CODA_ACTIONS = Object.fromEntries(Object.entries(actions.actions).map(([name, action]) => [name, action.params]));
 export const WORKFLOW_KINDS = Object.keys(dialect.kinds);
@@ -72,6 +77,7 @@ export function isDuration(text) {
 }
 
 const ajv = newAjv();
+valueKeywords(ajv, { feelProblem, isExpression });
 ajv.addKeyword({
   keyword: 'x-feel', type: 'string', schemaType: ['boolean', 'object'], errors: true,
   metaSchema: { anyOf: [{ type: 'boolean' }, { type: 'object', properties: { names: { type: 'array', items: { type: 'string' } } }, required: ['names'], additionalProperties: false }] },
@@ -86,11 +92,12 @@ ajv.addKeyword({
 });
 ajv.addKeyword({ keyword: 'x-duration', type: 'string', schemaType: 'boolean', compile: spec => value => !spec || isDuration(value) });
 ajv.addKeyword({ keyword: 'x-number', type: 'string', schemaType: 'boolean', compile: spec => value => !spec || Number.isFinite(Number(value)) });
+ajv.addSchema(fields);
 ajv.addSchema(values);
 const checks = new Map();
 // The validator of a definition of values.json, by its name; none for a type it says nothing of.
 const check = name => {
-  if (!checks.has(name)) checks.set(name, values.$defs[name] ? ajv.getSchema(`${values.$id}#/$defs/${name}`) : null);
+  if (!checks.has(name)) checks.set(name, Object.hasOwn(values.$defs, name) ? ajv.getSchema(`${values.$id}#/$defs/${name}`) : null);
   return checks.get(name);
 };
 
@@ -98,6 +105,12 @@ const SIZE_LIMIT = 1_000_000;
 // bpmn-moddle rewrites a descriptor as it takes it in (its names get their prefix), and whoever imports CODA_MODDLE may hand
 // it to one: what is read here is a copy taken as this loads, and each parse is given a copy of its own.
 const DESCRIPTOR = structuredClone(moddle);
+// moddle's Boolean/Integer coercion accepts `no` as false and `1.5` as 1. Keep field attributes as text until their
+// complete spelling is known; valid ones are restored to the descriptor's types before returning the parsed workflow.
+const FIELD_SCALARS = DESCRIPTOR.types.find(type => type.name === 'Field').properties.filter(p => ['Boolean', 'Integer'].includes(p.type));
+const PARSER_DESCRIPTOR = structuredClone(DESCRIPTOR);
+for (const property of PARSER_DESCRIPTOR.types.find(type => type.name === 'Field').properties)
+  if (FIELD_SCALARS.some(p => p.name === property.name)) property.type = 'String';
 const children = element => Object.values(element).flatMap(v => (Array.isArray(v) ? v : [v])).filter(v => v?.$type && v.$parent === element);
 // Everything in the definition under `element`, depth first, by a stack of its own, pushed one at a time: a definition may
 // nest deeper than the call stack goes, and hold more in one place than a call takes arguments.
@@ -130,7 +143,40 @@ function said(error, at, attribute) {
     return `${at} 需要 ${attribute ? 'coda:' : ''}${error.params.missingProperty}${own ? `：${own}` : ''}`;
   }
   if (error.keyword === 'x-unique-by') return `${at}：${error.message}`;
-  return `${at}：${described(error, { schemas: [values] }) ?? error.message}`;
+  return `${at}：${description(error)}`;
+}
+const description = (error, object = {}) => (described(error, { schemas: [values, fields] }) ?? error.message)
+  .replace(/\{(\w+)\}/g, (whole, key) => Object.hasOwn(error.params, key) ? String(error.params[key])
+    : object && Object.hasOwn(object, key) ? String(object[key]) : whole);
+// Required values and allowed attributes come from the same schema as validation; none of the field types is named here.
+function fieldSaid(error, at, field) {
+  if (error.keyword === 'additionalProperties') {
+    const allowed = Object.keys(error.parentSchema.properties), type = error.parentSchema.properties.type.const;
+    const extra = Object.keys(error.data).filter(key => !Object.hasOwn(error.parentSchema.properties, key));
+    return `${at}：${type} 字段没有 ${extra.join('、')}，可写 ${allowed.join('、')}`;
+  }
+  return `${at}：${error.keyword === 'x-feel' ? error.message : description(error, field)}`;
+}
+// A resolved field, at task opening or when accepting an answer. No expression is evaluated and no default is inserted.
+export function fieldProblem(field, where = '字段') {
+  const validate = ajv.getSchema(fields.$id);
+  return validate(field) ? null : fieldSaid(validate.errors[0], where, field);
+}
+// The expanded fields of one task (after reading coda:fields JSON and applying host/dir), checked together as in a
+// definition. Choice references still need the task's choices; Coda checks those after expansion.
+let fieldsBound;
+export function fieldsProblem(list, where = '任务') {
+  const schema = values.$defs['UserTask.children'].properties.field;
+  // Check the bound before visiting items, and individual values before uniqueness can inspect their ids.
+  const { 'x-unique-by': unique, ...shape } = schema;
+  const bound = fieldsBound ??= ajv.compile(shape);
+  if (!bound(list)) return `${where}：${description(bound.errors[0])}`;
+  for (const [index, field] of list.entries()) {
+    const problem = fieldProblem(field, `${where} 的字段 ${typeof field?.id === 'string' ? field.id : index + 1}`);
+    if (problem) return problem;
+  }
+  const validate = ajv.getSchema(`${values.$id}#/$defs/UserTask.children/properties/field`);
+  return validate(list) ? null : `${where}：字段 id 重复：${validate.errors[0].message.slice('id 不能重复：'.length)}`;
 }
 // What of the coda: values in the definition its schemas do not take, or null: each element in order, its coda:
 // attributes by each type of Coda's extending what it is, the coda: elements it holds by kind, and each coda: element.
@@ -141,12 +187,13 @@ function valuesProblem(root) {
   const loops = elements.filter(e => e.$type === 'bpmn:MultiInstanceLoopCharacteristics');
   const names = Object.fromEntries([...RUN_VARIABLES, ...elements.filter(e => e.$type === 'bpmn:Message' || e.$instanceOf?.('bpmn:FlowElement')).map(e => e.id),
     ...loops.map(loop => loop.inputElement).filter(Boolean), ...(loops.length ? ['loopCounter'] : [])].filter(Boolean).map(name => [name, null]));
-  const failed = (validate, object, at, attribute) => validate && !validate.call({ names }, object) ? said(validate.errors[0], at, attribute) : null;
+  const failed = (validate, object, at, attribute, field = false) => validate && !validate.call({ names, definition: true }, object)
+    ? field ? fieldSaid(validate.errors[0], at, object) : said(validate.errors[0], at, attribute) : null;
   for (const element of elements) {
     const type = codaType(element);
     if (type) {
       const name = element.id ?? element.name, kind = type.name === 'Choice' && element.$parent?.$type === 'coda:Choice' ? 'NestedChoice' : type.name;
-      const problem = failed(check(kind), codaObject(element), `${owner(element)?.id} 的 coda:${lower(type.name)}${name ? ` ${name}` : ''}`, false);
+      const problem = failed(check(kind), codaObject(element), `${owner(element)?.id} 的 coda:${lower(type.name)}${name ? ` ${name}` : ''}`, false, ['Field', 'Fields'].includes(kind));
       if (problem) return problem;
       continue;
     }
@@ -160,7 +207,16 @@ function valuesProblem(root) {
     if (!held.length) continue;
     const grouped = {};
     for (const child of held) (grouped[lower(codaType(child).name)] ??= []).push(codaObject(child));
-    const problem = failed(check(`${element.$type.slice(5)}.children`), grouped, at, false);
+    const validate = check(`${element.$type.slice(5)}.children`);
+    let problem = failed(validate, grouped, at, false);
+    if (problem && validate.errors[0].keyword === 'x-ref') {
+      const error = validate.errors[0], path = error.instancePath.split('/').slice(1);
+      let parent = grouped;
+      for (const key of path.slice(0, -1)) parent = parent[key];
+      problem = `${at} 的 coda:choice ${parent.id}：${description(error)}`;
+    }
+    if (problem && validate.errors[0].keyword === 'x-unique-by' && validate.errors[0].instancePath === '/field')
+      problem = `${at}：字段 id 重复：${validate.errors[0].message.slice('id 不能重复：'.length)}`;
     if (problem) return problem;
   }
   return null;
@@ -173,10 +229,15 @@ function valuesProblem(root) {
 export async function readWorkflow(source, file = 'workflow') {
   if (typeof source !== 'string' || source.length > SIZE_LIMIT) return { problem: `${file}.bpmn 过大` };
   let parsed;
-  try { parsed = await new BpmnModdle({ coda: structuredClone(DESCRIPTOR) }).fromXML(source); }
+  try { parsed = await new BpmnModdle({ coda: structuredClone(PARSER_DESCRIPTOR) }).fromXML(source); }
   catch (e) { return { problem: `${file}.bpmn 不是有效的 BPMN 2.0：${e.message}` }; }
   const { rootElement: root, warnings } = parsed;
   if (warnings.length) return { problem: `${file}.bpmn 有无法识别的内容：${warnings.slice(0, 3).map(w => w.message).join('；')}` };
+  for (const field of all(root).filter(e => e.$type === 'coda:Field')) for (const { name, type } of FIELD_SCALARS) {
+    const value = field[name];
+    if (type === 'Boolean' && ['true', 'false'].includes(value)) field[name] = value === 'true';
+    if (type === 'Integer' && typeof value === 'string' && /^[+-]?\d+$/.test(value)) field[name] = Number(value);
+  }
   for (const task of all(root).filter(e => e.$type === 'bpmn:ServiceTask' && e.action !== undefined)) {
     if (!Object.hasOwn(CODA_ACTIONS, task.action)) return { problem: `${task.id}：coda:action 只能是 ${Object.keys(CODA_ACTIONS).join('、')}` };
     const params = CODA_ACTIONS[task.action];