@coda-console/protocol 1.4.0 → 1.6.0

package/README.md

@@ -4,7 +4,7 @@ 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 的描述格式），`actions.json` 是 `coda:action` 的各个动作和它们接受的参数，`dialect.json` 是流程种类、Coda 自己发的事件、步骤失败的错误码和表达式能读的运行变量。`workflow.mjs` 用它们读一份流程，方言里没有的都拒绝；每个值能写什么、流程的结构对不对，现在仍由 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`、执行失败、工具调用的审核）。
 
 ## 用法
@@ -37,6 +37,12 @@ const { root } = await readWorkflow(source, 'deploy');
 
 `TYPES` 是 Coda 自己的类型（`contributes` 的键），`SCHEMAS` 是全部 schema（按文件名）。
 
+## 插件的后端通道
+
+插件清单可以声明 `"coda": { "channels": ["preview"] }`，限定只在预览版后端安装和更新。允许的通道是 `stable`（正式版）和 `preview`（预览版）；数组非空、不重复。不写 `channels` 的插件不限制通道。
+
+宿主按每台目标后端自己的安装记录判断，不按 Mac / iPhone 客户端版本判断；没有通道记录的后端不满足显式限制。商店和直接从 npm、Git 安装执行同一限制。这是 Coda 的安装约束，不改变 npm 包的公开性，也不能约束不认识该字段的旧宿主。
+
 ## 项目中的多选选项
 
 设置的 `items.anyOf` 选项可附带 `workflowKind`（`check`、`premerge`、`deploy`、`preview`、`release`）。全局设置显示全部选项；项目设置只显示该项目有的流程类别，未写此字段的选项始终显示。宿主负责按项目提供可选项，流程执行时仍需按运行的提交判断可用操作。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coda-console/protocol",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Coda 的协议：插件清单的类型（JSON Schema）、通用校验器、流程方言与 Agent 接入协议",
   "type": "module",
   "license": "MIT",
@@ -30,8 +30,10 @@
     "node": ">=24"
   },
   "dependencies": {
+    "@0dep/piso": "5.2.0",
     "ajv": "8.20.0",
-    "bpmn-moddle": "10.3.1"
+    "bpmn-moddle": "10.3.1",
+    "feelin": "8.2.0"
   },
   "scripts": {
     "test": "node --test 'test/**/*.test.mjs'"

package/schemas/plugin/plugin.json

@@ -8,6 +8,14 @@
     "id": {"$ref": "common.json#/$defs/id", "description": "插件 ID：小写字母、数字和「-」，以字母开头，至多 40 个字符；不写就用 name"},
     "name": {"type": "string"},
     "categories": {"description": "分类：文本的数组，第一个是插件页里归的类", "type": "array", "items": {"type": "string"}},
+    "coda": {
+      "description": "Coda 宿主的安装要求；不写 channels 就不限制后端通道",
+      "type": "object",
+      "properties": {
+        "channels": {"description": "允许安装和更新的后端通道：stable（正式版）、preview（预览版）；以目标后端的安装记录为准，没有通道记录不满足限制", "type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["stable", "preview"]}}
+      },
+      "additionalProperties": false
+    },
     "main": {"description": "插件宿主运行的模块：插件目录里的 .js 或 .mjs 文件", "type": "string", "pattern": "\\.m?js$", "x-file": {"type": "file"}},
     "activationEvents": {"description": "宿主什么时候加载 main：onStartupFinished（后端一启动），不重复", "type": "array", "items": {"enum": ["onStartupFinished"]}, "uniqueItems": true},
     "extensionDependencies": {"description": "需要先装的插件的 ID，不重复", "type": "array", "items": {"$ref": "common.json#/$defs/id"}, "uniqueItems": true},

package/validate.mjs

@@ -6,8 +6,9 @@
 // when it reads one, and coda-plugins' contract check does where a plugin is written.
 // What JSON Schema cannot say of one value alone it says with five keywords, each meaning one thing wherever it is written,
 // as Kubernetes extends its OpenAPI with `x-kubernetes-*`:
-// - `x-unique-by`: [name or { part }] — in an array, each named property of its objects is unique among the items having it,
-//   and so is `part`'s first group of each of its texts (a directory's last name);
+// - `x-unique-by`: [name, { part } or { key, nested }] — in an array, each named property of its objects is unique among the
+//   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
 //   of the array, at `pointer` in the manifest: absolute (`/contributes/configuration/properties`), or relative to the value
@@ -53,7 +54,8 @@ const SCHEMA_VALUE = { type: ['object', 'boolean'] };
 const META = {
   'x-max-contains': { type: 'object', properties: { match: SCHEMA_VALUE, max: { type: 'integer', minimum: 0 } }, required: ['match', 'max'], additionalProperties: false },
   'x-unique-by': { type: 'array', minItems: 1, items: { anyOf: [{ type: 'string' },
-    { type: 'object', properties: { part: { type: 'string' } }, required: ['part'], additionalProperties: false }] } },
+    { 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 },
     required: ['pointer'], additionalProperties: false },
   'x-placeholders': { type: 'object', properties: { names: { type: 'array', items: { type: 'string' } }, config: SCHEMA_VALUE }, additionalProperties: false },
@@ -90,11 +92,23 @@ function keywords(ajv) {
   ajv.addKeyword({
     keyword: 'x-unique-by', type: 'array', schemaType: 'array', metaSchema: META['x-unique-by'], errors: true,
     compile(keys, parentSchema) {
-      const by = keys.map(key => typeof key === 'object' ? { part: new RegExp(key.part, 'u') } : { key });
+      const by = keys.map(key => typeof key !== 'object' ? { key } : key.part !== undefined ? { part: new RegExp(key.part, 'u') } : key);
+      // The items, and with `nested` those in each one's array of that name, at every depth: by a stack of its own.
+      const every = (items, nested) => {
+        if (!nested) return items;
+        const found = [], stack = [...items].reverse();
+        while (stack.length) {
+          const item = stack.pop();
+          found.push(item);
+          const inner = item && typeof item === 'object' ? item[nested] : undefined;
+          if (Array.isArray(inner)) for (let i = inner.length - 1; i >= 0; i--) stack.push(inner[i]);
+        }
+        return found;
+      };
       return function unique(items) {
-        for (const { key, part } of by) {
+        for (const { key, part, nested } of by) {
           const seen = new Set();
-          for (const item of items) {
+          for (const item of every(items, nested)) {
             const value = part ? (typeof item === 'string' ? part.exec(item)?.[1] : undefined)
               : item && typeof item === 'object' && Object.hasOwn(item, key) ? item[key] : undefined;
             if (value === undefined) continue;
@@ -162,8 +176,14 @@ function keywords(ajv) {
   });
 }
 
-const ajv = new Ajv2020({ allErrors: false, verbose: true, passContext: true, strict: true, strictTypes: false, strictRequired: false, allowUnionTypes: true });
-keywords(ajv);
+// An Ajv as these schemas are checked with, the keywords above in it: also for the schemas of the protocol's other parts
+// (workflow.mjs), which add their own keywords to it.
+export function newAjv() {
+  const made = new Ajv2020({ allErrors: false, verbose: true, passContext: true, strict: true, strictTypes: false, strictRequired: false, allowUnionTypes: true });
+  keywords(made);
+  return made;
+}
+const ajv = newAjv();
 for (const schema of Object.values(SCHEMAS)) ajv.addSchema(schema);
 // The validators of the schemas here, by file.
 const compiled = new Map();
@@ -197,7 +217,7 @@ const nodes = function* (node) {
   yield node;
   for (const child of Object.values(node)) yield* nodes(child);
 };
-function described(error, { roots = true, schemas = [] } = {}) {
+export function described(error, { roots = true, schemas = [] } = {}) {
   if (!error.parentSchema) return undefined;
   if (error.parentSchema.description) return roots || !error.parentSchema.$id ? error.parentSchema.description : undefined;
   const steps = error.schemaPath.replace(/^#\//, '').split('/').map(unescape).slice(0, -1);

package/workflow/dialect.json

@@ -1,5 +1,5 @@
 {
-  "description": "Coda 的 BPMN 方言里共用的名字：流程种类、Coda 自己发的事件、步骤失败时抛出的错误码、表达式按名字读的运行变量",
+  "description": "Coda 的 BPMN 方言里共用的名字：流程种类、Coda 自己发的事件、步骤失败时抛出的错误码、表达式按名字读的运行变量，以及运行的输入能是哪些类型、从会话的哪里取值（inputs.sources：来源 → 它能给的类型）",
   "kinds": {
     "deploy": "部署后端与服务；只跑合并进默认分支的提交",
     "preview": "发布预览版客户端；只跑合并进默认分支的提交",
@@ -16,5 +16,9 @@
   },
   "userMessage": "^user\\.[a-z][a-z0-9-]{0,39}$",
   "stepFailed": "STEP_FAILED",
-  "variables": ["inputs", "run", "github", "vars"]
+  "variables": ["inputs", "run", "github", "vars"],
+  "inputs": {
+    "types": ["string", "boolean", "number", "branch"],
+    "sources": {"session.branch": ["branch", "string"]}
+  }
 }

package/workflow/values.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coda.pub/schema/bpmn/1.0/values.json",
+  "title": "流程里每个 coda: 值能写什么",
+  "description": "$defs 按 moddle.json 的类型名，各是那个类型的属性（和它套着的 coda: 元素）组成的对象的 schema；「<BPMN 类型>.children」是一个元素的 extensionElements 里各种 coda: 元素按名字成组的 schema。x-feel：值是 FEEL（「=」开头是一个表达式，否则文字里每个 {{ … }} 是一个），按这份流程里的名字读得通；x-duration：ISO 8601 时长，不为负；x-number：文字换算成数字是个有限的数",
+  "$defs": {
+    "ProcessProperties": {
+      "type": "object",
+      "properties": {
+        "concurrency": {"type": "string", "minLength": 1, "maxLength": 200, "description": "coda:concurrency 须为 1–200 个字符"},
+        "key": {"type": "string", "pattern": "\\S", "maxLength": 4000, "x-feel": {"names": ["inputs", "github", "vars"]}, "description": "coda:key 须为 1–4000 个字符"},
+        "title": {"type": "string", "pattern": "\\S", "maxLength": 200, "x-feel": true, "description": "coda:title 须为 1–200 个字符"},
+        "kind": {"enum": ["deploy", "preview", "release", "check", "premerge"], "description": "coda:kind 只能是 deploy、preview、release、check、premerge"},
+        "agents": {"type": "string", "pattern": "^[\\s,]*[a-z][a-z0-9-]{0,39}(?:[\\s,]+[a-z][a-z0-9-]{0,39})*[\\s,]*$",
+          "description": "coda:agents 写 Agent 的 ID，用逗号或空格分隔（小写字母、数字和「-」，以字母开头，至多 40 个字符），不能为空"}
+      }
+    },
+    "ScriptTaskProperties": {
+      "type": "object",
+      "properties": {
+        "audience": {"const": "user", "description": "coda:audience 只能是 user"},
+        "group": {"type": "string", "pattern": "^\\S{1,100}$", "description": "coda:group 须为 1–100 个非空白字符的组名"},
+        "timeout": {"type": "number", "exclusiveMinimum": 0, "maximum": 1440, "description": "coda:timeout 须为 0–1440 之间的分钟数"},
+        "cancelTimeout": {"type": "number", "exclusiveMinimum": 0, "maximum": 1440, "description": "coda:cancelTimeout 须为 0–1440 之间的分钟数"},
+        "checkout": {"enum": ["true", "false"], "description": "coda:checkout 只能是 true 或 false"},
+        "retry": {"type": "string", "pattern": "^[1-5]$", "description": "coda:retry 是失败后最多再试几次，须为 1 到 5 的整数"}
+      }
+    },
+    "RunsOnProperties": {
+      "type": "object",
+      "properties": {
+        "runsOn": {"type": "string", "pattern": "^\\s*[a-z0-9][a-z0-9._-]{0,39}\\s*(?:,\\s*[a-z0-9][a-z0-9._-]{0,39}\\s*){0,9}$",
+          "description": "coda:runsOn 写逗号分隔的标签（小写字母、数字与 . _ -，至多 10 个），如 linux,x64"}
+      }
+    },
+    "LoopProperties": {
+      "type": "object",
+      "properties": {
+        "inputCollection": {"type": "string", "pattern": "^\\s*=", "x-feel": true, "description": "coda:inputCollection 须为「=」开头的 FEEL 表达式，如 =inputs.targets"},
+        "inputElement": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "not": {"enum": ["inputs", "run", "github", "vars", "loopCounter"]},
+          "description": "coda:inputElement 须为字母开头的字母、数字、「_」，且不是 inputs、run、github、vars、loopCounter 或节点、消息的 id"}
+      },
+      "allOf": [
+        {"if": {"required": ["inputCollection"]}, "then": {"required": ["inputElement"], "description": "写 coda:inputElement，给每份拿到的元素起个名字"}},
+        {"if": {"required": ["inputElement"]}, "then": {"required": ["inputCollection"], "description": "coda:inputElement 只配合 coda:inputCollection"}}
+      ]
+    },
+    "FlowNodeProperties": {
+      "type": "object",
+      "properties": {
+        "status": {"type": "string", "pattern": "\\S", "maxLength": 200, "x-feel": true, "description": "coda:status 须为 1–200 个字符"},
+        "expect": {"type": "string", "anyOf": [{"pattern": "^\\s*=", "maxLength": 200}, {"maxLength": 200, "x-duration": true}], "x-feel": true,
+          "description": "coda:expect 须为 ISO 8601 时长，如 PT1H，或读出时长的表达式"}
+      }
+    },
+    "StartEventProperties": {
+      "type": "object",
+      "properties": {
+        "reportTo": {"type": "string",
+          "anyOf": [{"pattern": "^\\s*=\\s*vars(?:\\.[A-Za-z0-9_-]+)+\\s*$"},
+            {"pattern": "^\\s*(?:coda://threads/|coda\\+space://[^/#]+/threads/)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(?:#(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|command:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))?\\s*$"}],
+          "description": "coda:reportTo 写会话引用（coda://threads/<会话 UUID>），或只读插件设置的表达式，如 =vars.maintenance.reportTo"},
+        "reportOn": {"enum": ["failure", "always"], "description": "coda:reportOn 只能是 failure、always"},
+        "scope": {"enum": ["project", "machine"], "description": "coda:scope 只能是 project、machine"}
+      },
+      "if": {"required": ["reportOn"]},
+      "then": {"required": ["reportTo"], "description": "写了 coda:reportOn 就要写 coda:reportTo（结果交给谁）"}
+    },
+    "EndEventProperties": {
+      "type": "object",
+      "properties": {
+        "notify": {"type": "string", "anyOf": [{"enum": ["true", "false"]}, {"pattern": "^\\s*="}], "x-feel": true, "description": "coda:notify 须为 true、false 或一个表达式"}
+      }
+    },
+    "UserTaskProperties": {
+      "type": "object",
+      "properties": {
+        "assignee": {"enum": ["agent", "user"], "description": "coda:assignee 只能是 agent（先交给发起会话的 Agent，它停下后转给用户）或 user（直接交给用户）"}
+      }
+    },
+    "Input": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "name 不合法：须为字母开头的字母、数字、「_」"},
+        "type": {"enum": ["string", "boolean", "number", "branch"], "description": "type 只能是 string、boolean、number、branch"},
+        "label": {"type": "string", "pattern": "\\S", "maxLength": 40, "description": "label 须为 1–40 个字"},
+        "defaultFrom": {"enum": ["session.branch"], "description": "defaultFrom 只能是 session.branch"}
+      },
+      "required": ["name"],
+      "allOf": [
+        {"if": {"required": ["defaultFrom"]}, "then": {"properties": {"type": {"enum": ["branch", "string"], "description": "defaultFrom=\"session.branch\" 只用于 type 为 branch、string 的参数"}}}},
+        {"if": {"required": ["type"], "properties": {"type": {"const": "number"}}},
+          "then": {"properties": {"default": {"pattern": "^\\s*[-+]?(?:\\d+\\.?\\d*|\\.\\d+)(?:[eE][-+]?\\d+)?\\s*$", "x-number": true, "description": "default 须为数字"}}}}
+      ]
+    },
+    "Env": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "名字不合法：须为字母开头的字母、数字、「_」"},
+        "value": {"type": "string", "maxLength": 20000, "x-feel": true, "not": {"pattern": "\\$\\{\\{"},
+          "description": "value 不超过 20000 字；这里的表达式以「=」开头，如 =inputs.name，不写 ${{ … }}"}
+      },
+      "required": ["name", "value"]
+    },
+    "Output": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "名字不合法：须为字母开头的字母、数字、「_」"},
+        "value": {"type": "string", "maxLength": 4000, "x-feel": true, "description": "value 不超过 4000 字"}
+      },
+      "required": ["name"]
+    },
+    "Param": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "名字不合法：须为字母开头的字母、数字、「_」"},
+        "value": {"type": "string", "maxLength": 4000, "x-feel": true, "description": "value 不超过 4000 字"}
+      },
+      "required": ["name", "value"]
+    },
+    "Inspect": {
+      "type": "object",
+      "properties": {
+        "label": {"type": "string", "pattern": "\\S", "maxLength": 100, "description": "label 须为 1–100 个字"},
+        "type": {"enum": ["string", "number", "boolean", "timestamp"], "description": "type 只能是 string、number、boolean、timestamp"},
+        "phase": {"enum": ["input", "output"], "description": "phase 须为 input 或 output"},
+        "value": {"type": "string", "pattern": "^\\s*=", "x-feel": true, "description": "value 须为「=」开头的表达式，如 =approval-facts.given"}
+      },
+      "required": ["label", "type", "phase", "value"]
+    },
+    "Choice": {
+      "type": "object",
+      "properties": {
+        "id": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$", "not": {"const": "handback"}, "description": "id 须为字母开头的字母、数字、「_」「-」，不能是 handback"},
+        "name": {"type": "string", "pattern": "\\S", "maxLength": 40, "description": "name 须为 1–40 个字"},
+        "detail": {"type": "string", "maxLength": 200, "x-feel": true, "description": "detail 不超过 200 字"},
+        "choices": {"type": "array", "maxItems": 6, "description": "最多 6 个按住出现的选项"},
+        "options": {"type": "array", "maxItems": 12, "x-unique-by": ["id"], "description": "最多 12 个勾选项"}
+      },
+      "required": ["id", "name"],
+      "allOf": [{"description": "勾选项（coda:option）只能属于没有嵌套 choice 的外层 choice", "not": {"required": ["choices", "options"]}}]
+    },
+    "NestedChoice": {
+      "allOf": [{"$ref": "#/$defs/Choice"}],
+      "properties": {
+        "primary": {"const": false, "description": "只有最外层的选项能是主按钮"},
+        "choices": {"maxItems": 0, "description": "按住出现的选项里不能再嵌套"},
+        "options": {"maxItems": 0, "description": "勾选项（coda:option）只能属于没有嵌套 choice 的外层 choice"}
+      }
+    },
+    "Option": {
+      "type": "object",
+      "properties": {
+        "id": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$", "description": "须有不重复的 id（字母开头的字母、数字、「_」「-」）"},
+        "name": {"type": "string", "pattern": "\\S", "maxLength": 40, "x-feel": true, "description": "name 须为 1–40 个字"},
+        "detail": {"type": "string", "maxLength": 200, "x-feel": true, "description": "detail 不超过 200 字"},
+        "shown": {"type": "string", "pattern": "^\\s*=", "x-feel": true, "description": "coda:shown 须为表达式（以 = 开头）"},
+        "default": {"type": "string", "anyOf": [{"enum": ["true", "false"]}, {"pattern": "^\\s*="}], "x-feel": true, "description": "default 须为 true、false 或表达式"}
+      },
+      "required": ["id", "name"]
+    },
+    "Process.children": {
+      "type": "object",
+      "properties": {
+        "input": {"type": "array", "x-unique-by": ["name"], "description": "coda:input 的 name 不能重复"}
+      }
+    },
+    "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（包括按住出现的）不重复"}
+      }
+    }
+  }
+}

package/workflow.mjs

@@ -1,16 +1,28 @@
 // Coda's dialect of BPMN 2.0 (workflow/): what a workflow of a project or a plugin may write in Coda's namespace, as a
-// bpmn-moddle descriptor (moddle.json); the steps it may ask of Coda itself, each with the parameters it takes
-// (actions.json); and the names workflows share (dialect.json): their kinds, the events Coda sends, the error code of a
-// failed step, the run's variables an expression reads by name. 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; what each value may
-// be is still Coda's to check as it reads the workflow.
+// bpmn-moddle descriptor (moddle.json); what each of those values may be, as JSON Schemas (values.json); the steps it may
+// ask of Coda itself, each with the parameters it takes (actions.json); and the names workflows share (dialect.json):
+// their kinds, the events Coda sends, the error code of a failed step, the run's variables an expression reads by name,
+// 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):
+// - `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).
+import { parseDuration } from '@0dep/piso';
 import { BpmnModdle } from 'bpmn-moddle';
+import { parseExpression } from 'feelin';
+import { described, newAjv } from './validate.mjs';
 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' };
 
 export const CODA_MODDLE = moddle;
 export const CODA_NAMESPACE = moddle.uri;
+export const CODA_VALUES = values;
 // 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);
@@ -23,8 +35,69 @@ export const SESSION_OPENED = 'session.opened', SESSION_FACTS = 'session.facts',
 export const USER_MESSAGE = new RegExp(dialect.userMessage);
 export const STEP_FAILED = dialect.stepFailed;
 export const RUN_VARIABLES = dialect.variables;
+// The types a run's inputs take (`coda:input type`), and where one started from a session takes its value from when given
+// none (`defaultFrom`), with the types each gives.
+export const INPUT_TYPES = dialect.inputs.types;
+export const INPUT_SOURCES = Object.freeze(Object.fromEntries(Object.entries(dialect.inputs.sources).map(([name, types]) => [name, { types }])));
+
+// A value that starts with `=` is a FEEL expression; anything else is text, where each `{{ … }}` holds one.
+export const isExpression = value => typeof value === 'string' && value.trimStart().startsWith('=');
+const TEMPLATE = /\{\{([\s\S]*?)\}\}/g;
+// What the expressions of the engine before FEEL looked like: refused with the way to write it now.
+const OLD = /\$\{\s*environment\./;
+// FEEL reads every name it is given at each parse, and a workflow has a name for each of its nodes: an expression is given
+// only those it mentions.
+const mentioned = (expression, names) => Object.fromEntries(Object.entries(names).filter(([name]) => expression.includes(name)));
+// Why a value does not read as FEEL, or null: `names`, what it may read by name (an object with them as keys), so that a
+// task id like `in-queue` reads as one name.
+export function feelProblem(value, names = {}) {
+  if (typeof value !== 'string') return null;
+  if (OLD.test(value)) return '表达式改用 FEEL，以「=」开头，如 =review.verdict；文字里用 {{ … }}，如 还在验证：{{verifying.what}}（docs/workflows.md「表达式」）';
+  const expressions = isExpression(value) ? [value.trimStart().slice(1)] : [...value.matchAll(TEMPLATE)].map(m => m[1]);
+  for (const expression of expressions) {
+    if (!expression.trim()) return '表达式是空的';
+    // A property's name says nothing of the grammar, and what a value holds is known only once read (`vars.probe.every`
+    // names a setting, not FEEL's `every`): each is read as a plain one.
+    const plain = expression.replace(/\.(?=[A-Za-z_])[\w-]+/g, '.p');
+    let error = null;
+    parseExpression(plain, mentioned(plain, names)).iterate({ enter(node) { if (node.type.isError && error === null) error = node.from; } });
+    if (error !== null) return `「${expression.trim()}」不是有效的 FEEL 表达式（第 ${error + 1} 个字符附近）`;
+  }
+  return null;
+}
+// An ISO 8601 duration (`P30D`, `PT6H`), not negative, as bpmn-engine reads its timers.
+export function isDuration(text) {
+  if (typeof text !== 'string' || !text || text.length > 200) return false;
+  try { return parseDuration(text).result.sign !== -1; } catch { return false; }
+}
+
+const ajv = newAjv();
+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 }] },
+  compile(spec, parentSchema) {
+    const own = typeof spec === 'object' ? Object.fromEntries(spec.names.map(name => [name, null])) : null;
+    return function feel(value) {
+      const problem = spec ? feelProblem(value, own ?? this?.names ?? {}) : null;
+      if (problem) feel.errors = [{ keyword: 'x-feel', message: problem, params: {}, parentSchema }];
+      return !problem;
+    };
+  },
+});
+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(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);
+  return checks.get(name);
+};
 
 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);
 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.
@@ -34,14 +107,73 @@ const all = element => {
   while (stack.length) { const next = stack.pop(); found.push(next); push(children(next)); }
   return found;
 };
+const TYPES = new Map(DESCRIPTOR.types.map(type => [type.name, type]));
+const codaType = element => element.$type.startsWith('coda:') ? TYPES.get(element.$type.slice(5)) : undefined;
+const lower = name => `${name[0].toLowerCase()}${name.slice(1)}`;
+// The attributes `type` declares that `element` has, as moddle read them.
+const attributes = (element, type) => Object.fromEntries(type.properties.filter(p => p.isAttr && element[p.name] !== undefined).map(p => [p.name, element[p.name]]));
+// A coda: element as one object: its attributes, and the coda: elements it holds (`isMany`), each as its attributes.
+function codaObject(element) {
+  const type = codaType(element), object = attributes(element, type);
+  for (const p of type.properties.filter(p => p.isMany && element[p.name]?.length)) object[p.name] = element[p.name].map(child => attributes(child, codaType(child)));
+  return object;
+}
+// The element of the process a coda: element is written in: the nearest around it of BPMN's with an id.
+const owner = element => { let at = element.$parent; while (at && (codaType(at) || !at.id)) at = at.$parent; return at; };
+// What is wrong, said once, as Coda says it: where (`at`), then what the schema says of the value there. `attribute`: the
+// object is a BPMN element's coda: attributes, whose names are said with their prefix.
+function said(error, at, attribute) {
+  const key = error.instancePath.split('/')[1], name = key === undefined ? '' : `${attribute ? 'coda:' : ''}${key}`;
+  if (error.keyword === 'x-feel') return `${at}${key && key !== 'value' ? ` 的 ${name}` : ''}：${error.message}`;
+  if (error.keyword === 'required') {
+    const own = error.parentSchema?.description;
+    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}`;
+}
+// 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.
+function valuesProblem(root) {
+  const elements = all(root);
+  // What an expression may read by name: the run's own variables, each node's result and each message's latest, and in a
+  // loop its element and `loopCounter`.
+  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;
+  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);
+      if (problem) return problem;
+      continue;
+    }
+    if (element.$type?.startsWith('bpmn:') !== true || !element.$instanceOf) continue;
+    const at = element.id ?? owner(element)?.id;
+    for (const extending of DESCRIPTOR.types.filter(t => t.extends?.some(on => element.$instanceOf(on)))) {
+      const problem = failed(check(extending.name), attributes(element, extending), at, true);
+      if (problem) return problem;
+    }
+    const held = (element.extensionElements?.values ?? []).filter(codaType);
+    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);
+    if (problem) return problem;
+  }
+  return null;
+}
 
 // A workflow's definition (`file`, its name without `.bpmn`, for what is said) read with Coda's dialect: `{ root }`, the
 // parsed definitions, or `{ problem }`, what of it the dialect does not have — not BPMN, a coda: attribute or element it
-// does not know, an action it does not have or a parameter that action does not take.
+// does not know, an action it does not have or a parameter that action does not take — or a value of it its schema does
+// not take.
 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: CODA_MODDLE }).fromXML(source); }
+  try { parsed = await new BpmnModdle({ coda: structuredClone(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('；')}` };
@@ -51,7 +183,8 @@ export async function readWorkflow(source, file = 'workflow') {
     const given = (task.extensionElements?.values ?? []).filter(v => v.$type === 'coda:Param');
     if (given.some(p => !params.includes(p.name))) return { problem: `${task.id}：coda:action ${task.action} 只接受参数 ${params.join('、')}` };
   }
-  return { root };
+  const problem = valuesProblem(root);
+  return problem ? { problem } : { root };
 }
 // What of a workflow's definition the dialect does not have, or null.
 export async function workflowProblem(source, file) {