@coda-console/plugin-check 0.8.24 → 0.8.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +16 -3
  2. package/bin/check.mjs +18 -2
  3. package/check/coda/adapters/plugin-events.mjs +2 -0
  4. package/check/coda/adapters/plugin-modules.mjs +13 -4
  5. package/check/coda/adapters/plugin-test-host.d.mts +71 -3
  6. package/check/coda/adapters/plugin-test-host.mjs +6 -1
  7. package/check/coda/api-surface.txt +349 -0
  8. package/check/coda/application/host-protocols.mjs +3 -1
  9. package/check/coda/components/plugins/plugin-extensions.mjs +1 -1
  10. package/check/coda/components/protocols/record-rules.mjs +2 -2
  11. package/check/coda/contract.json +16 -9
  12. package/check/coda/domain/accord.mjs +144 -0
  13. package/check/coda/domain/jcs.mjs +58 -0
  14. package/check/coda/domain/usage.mjs +56 -0
  15. package/check/coda/kernel/accord-protocol.mjs +168 -0
  16. package/check/coda/kernel/usage-protocol.mjs +97 -0
  17. package/check/index.mjs +6 -2
  18. package/check/init.mjs +33 -0
  19. package/check/level.mjs +70 -0
  20. package/check/manifest.mjs +5 -2
  21. package/check/module.mjs +133 -0
  22. package/check/report.mjs +2 -2
  23. package/package.json +7 -2
  24. package/templates/agent/agent/entry.mjs +128 -0
  25. package/templates/agent/icons/README.md +14 -0
  26. package/templates/agent/icons/echo.pdf +0 -0
  27. package/templates/agent/icons/echo.svg +8 -0
  28. package/templates/agent/package.json +20 -0
  29. package/templates/module/main.mjs +37 -0
  30. package/templates/module/package-lock.json +306 -0
  31. package/templates/module/package.json +80 -0
  32. package/templates/module/test/main.test.mjs +65 -0
  33. package/templates/resource/package.json +22 -0
  34. package/templates/resource/scripts/mark.mjs +6 -0
  35. package/templates/resource/scripts/resources.mjs +35 -0
package/README.md CHANGED
@@ -27,6 +27,7 @@ plugins/testbed/ 测试机:长插在 Mac 上的 iPhone、iPad 只经 u
27
27
  plugins/composer/ 输入框模式与开发流程:监督开发(一个需求一条需求分支,主 Agent 把一块块改动合进需求分支,用户批准一次)与需求交付;Ultra 名单引用 composer.templates
28
28
  templates/agent/ 最小的 Agent 插件:手写 ACP 的回声 Agent,演示会话指令、插话、Agent 活动与自主轮次
29
29
  templates/resource/ 最小的资源插件:一个资源、两个读数、一个按钮
30
+ templates/module/ 带模块的插件:自己的协议(一个查询、一个做事的操作、一个事件),模块登记操作、写记录、发布并订阅事件,附测试
30
31
  bin/、check/ 契约检查(仓库根的 package.json 就是它,@coda-console/plugin-check);check/coda/ 是 Coda 同步来的规则副本,不要手改
31
32
  test/ 检查包的测试;test/plugins/ 是各插件的测试(插件目录里只放运行要用的文件)
32
33
  .coda/workflows/ 本仓库自己的流程:sync-coda 等新版本发到 npm,再给 Coda 开升级依赖的 PR
@@ -421,7 +422,7 @@ Coda 根上的同一条 overrides 由 `sync-coda` 一起改(npm 只认根的
421
422
  「设置 › 插件 › 从仓库添加…」:
422
423
 
423
424
  1. **仓库**填 `coda-console/coda-plugins`(或 `https://github.com/coda-console/coda-plugins`);**版本**留空是默认分支,也可以填分支、标签或完整的提交号。
424
- 2. **读取**:Coda 拉取那个提交,把仓库根与两层以内 `package.json` 带 `contributes` 的目录各列成一个插件——这个仓库里是 `plugins/` 下的七个与两个模板。Coda 内置的那几个只能从 npm 上自己的包单独更新;在 Coda 里先卸载它,才能从这里装同名的。
425
+ 2. **读取**:Coda 拉取那个提交,把仓库根与两层以内 `package.json` 带 `contributes` 的目录各列成一个插件——这个仓库里是 `plugins/` 下的七个与三个模板。Coda 内置的那几个只能从 npm 上自己的包单独更新;在 Coda 里先卸载它,才能从这里装同名的。
425
426
  3. 选一个,确认里逐条列出它会运行的命令(Agent 的 `command`、资源的命令与动作),确认就是批准:这些命令以你的账户在空间里每台机器上运行,Coda 不做隔离,只装你信任的来源。
426
427
 
427
428
  **Coda 只认提交**:安装时钉在读取到的那个提交上,每台机器各自取同一个提交。「检查更新」用记下的仓库与版本再读一次,提交变了才有更新;
@@ -431,7 +432,16 @@ Coda 根上的同一条 overrides 由 `sync-coda` 一起改(npm 只认根的
431
432
 
432
433
  ## 写一个插件
433
434
 
434
- 从模板开始:把 `templates/agent` 或 `templates/resource` 复制成自己的目录,改掉 `name`(插件 ID)与 Agent 的 `id`。
435
+ 从模板开始:
436
+
437
+ ```sh
438
+ npx @coda-console/plugin-check init my-plugin # 默认 module:带模块与测试
439
+ npx @coda-console/plugin-check init my-plugin --template agent # 或 resource
440
+ ```
441
+
442
+ 目录要不存在或为空;目录名就是插件 ID(小写字母开头,小写字母、数字和 `-`,至多 40 个字符),`name` 与模块模板里协议名的前缀都换成它。
443
+ 生成后 `npx @coda-console/plugin-check my-plugin` 检查;模块模板的测试在装好依赖后用 `npm test` 跑(`devDependencies` 只有检查包,钉确切版本,模板带 `package-lock.json`)。
444
+ Agent 模板里 Agent 的 `id` 不随目录名变,按需自己改。
435
445
 
436
446
  **清单**(`package.json`)
437
447
 
@@ -535,9 +545,12 @@ node bin/check.mjs <插件目录> [--agent <id>] [--manifest] [--live] [--prompt
535
545
  npx github:coda-console/coda-plugins#<提交> <插件目录>
536
546
  ```
537
547
 
548
+ 插件自己的测试用检查包的出口:`@coda-console/plugin-check/test-host`(`createTestHost`,Coda 自己的 `coda`、`ctx` 构造)与 `@coda-console/plugin-check/types`(类型),不必直接依赖协议包。
549
+
538
550
  | 级 | 要不要登录 | 查什么 |
539
551
  | --- | --- | --- |
540
- | 清单(总是) | 不要 | `package.json` 的通用键对协议 schema 校验(`manifestProblem`),再照 Coda 读成插件(`readPlugin`:登记的贡献点各按自己的 schema 查、读,ID、设置名在 ID 之下);其余写给别的插件扩展点的键,要有 Coda 自带的或旁边依赖的插件声明这个类型。资源类型与旧的面板按资源插件给扩展点 `resources`、`panels` 带的 schema 查。`.coda/workflows/` 里的每个流程(含能力)按协议的流程方言读(`workflowProblem`):不是 BPMN、认不出的 `coda:` 属性或元素、没有的动作或动作不接受的参数都算失败。另有只提醒的:分类、版本、图标页面太小、旧的 Agent ID `claude` |
552
+ | 清单(总是) | 不要 | `package.json` 的通用键对协议 schema 校验(`manifestProblem`),再照 Coda 读成插件(`readPlugin`:登记的贡献点各按自己的 schema 查、读,ID、设置名在 ID 之下);其余写给别的插件扩展点的键,要有 Coda 自带的或旁边依赖的插件声明这个类型。资源类型与旧的面板按资源插件给扩展点 `resources`、`panels` 带的 schema 查。`.coda/workflows/` 里的每个流程(含能力)按协议的流程方言读(`workflowProblem`):不是 BPMN、认不出的 `coda:` 属性或元素、没有的动作或动作不接受的参数都算失败。另有只提醒的:分类、版本、图标页面太小、旧的 Agent ID `claude`。还算 `engines.coda` 该写几(读 `check/coda/api-surface.txt`):清单的键、`contributes.<键>`、`uses` 的协议与权限组、自己协议定义里的键,以及插件目录里 `.mjs`/`.js`(不含 `node_modules`)的 `coda.<成员>`、`ctx.<成员>` 与页面里的 `window.coda.<成员>`;要的 Level 取最大的,清单写的 `engines.coda` 比清单、`uses`、定义的项小算失败,比文本扫出的项小只提醒,没写只提醒并给出该写的值。用到的试行面(`trial` 的权限组、模块接口)列在「说明」里,一行一项 |
553
+ | 模块(有 `main`;`--manifest` 不跑) | 不要 | 清单之后、握手之前:用 `createTestHost({ plugin, settings })` 起 Coda 自己的 `coda`(状态目录是临时的),`import(main)` 后调 `activate(host.coda)`,10 秒没完成或抛错算失败(带堆栈第一行);`host.registered()` 与清单两个方向对:清单的 `protocolImplementations` 写了、定义里有、又不由 `commands` 实现的操作,模块没 `coda.handle` 算失败,模块登记了定义里没有的操作也算失败(Coda 自己的协议里 `codaOnly` 的操作只由 Coda 回答,不要求登记);`coda.on` 订了不在自己事件组里的名字,测试宿主当场抛 `forbidden`:按被拒的事件名在已知的协议定义(Coda 自己的、自己的、依赖的)里查它归谁,查到了(它的组不在 `uses` 里)算失败,另有无关的依赖缺定义也一样;查不到,而 `uses` 里有协议的定义不在本地(依赖没放在旁边),归属可能取决于缺的定义,报「未完成核对」,不判插件错;`coda.get`/`coda.list` 遇到测试宿主没有的记录类型,先按已知定义判断:协议有定义却没有记录(只含事件)、或 `uses` 没给读记录的权限(`usesRefusal`,如只申请了事件组)算失败;有记录又已获授权的,测试宿主登记不了别的插件的记录类型(登记进自己的协议会让模块也能发它的事件),报「未完成核对」,之后的调用没有核对;协议在 `uses` 里而定义不在本地的同样报「未完成核对」。`activate` 成功之后才调模块导出的 `deactivate`(抛错、或与 `activate` 一样 10 秒没完成都算失败);`activate` 失败、超时或「未完成核对」时不调,只靠 `host.close()` 收掉模块起的进程(`deactivate` 之后同样收)。`activate` 最终抛出的错,检查包用包了一层的 `coda` 认出它是哪个成员出的:成员是测试宿主没有后端的几个之一(`coda.watch`、`coda.services.register`、`coda.tell`、`coda.api`、`coda.environment`、`coda.protocols.resolve`、`coda.protocols.upload`、`coda.pluginSetup.retry`),错误又正是测试宿主为这个成员答的那一条(错误码与固定说法都对上)时不算失败:「说明」里写明模块一级只验到这里,登记不与清单比对,模块一级报「未完成核对」(清单写的协议没有定义时同样);别的都算激活失败:同一成员的别的错(回调、筛选条件不合法等),别的成员的错,包括回 `unsupported` 的(比如 `coda.query` 调非只读操作) |
541
554
  | 握手(默认) | 不要 | `sh -c` 启动 `command`(环境是 Coda 的 `pluginEnv` 给的:`CODA_NODE`、`CODA_PLUGIN_PATH`、临时的 `CODA_PLUGIN_STATE`、设置默认值的 `CODA_PLUGIN_SETTINGS`;依赖的插件在旁边(同一个父目录里同名的目录)时 `CODA_PLUGIN_DEPENDENCIES` 给它的目录,Coda 自带的不在这里、不给),发与 Coda 相同的 `initialize`,要求 `protocolVersion` 为 1;能力声明的 `_meta.coda` 与顶层插话声明交协议 schema 校验;检查会话指令能力(`sessionCapabilities.systemPrompt`,没声明也通过,由 Coda 在第一轮送入);声明了的 `session/new` 带会话指令,给出会话与当前模型,配置选项的 `_meta.coda.default` 交协议校验;错误里声明的执行失败也查协议 schema,回 -32000 记为未登录、跳过后面的检查(不算失败);像 Coda 一样对进程组发 SIGTERM,5 秒内要退出(超过 0.8 秒提醒);另起一个进程,关掉标准输入后 5 秒内不退出只提醒;声明了配置探测(`_meta.coda.probe`)的,再另起进程发带探测标记的 `session/new`(要给非空的 `sessionId`;标记不是 `true` 的要回 -32602):逐个模型用 `category: model` 的配置项切换(只有 `models` 的用 `session/set_model`),每次要返回该模型完整的配置、思考档位在它自己的选项里并能设回(标了 `_meta.coda.default` 的设回那一项),不存在的模型与配置项要报错,`session/prompt` 要回 -32602,声明了 `session/close` 的另开一个虚拟会话关掉,要回 `{}`、之后它的请求回 -32002,探测期间不干活;断线后新进程的 `session/load`、`session/resume` 要回 -32002,`session/list`(带探测的 `cwd`,沿 `nextCursor` 翻完;每页、每个会话条目合 ACP schema,`sessionId` 非空,`nextCursor` 只能是字符串或 null;重复的游标或超过 100 页算失败)不列出这个虚拟会话,没声明的跳过。资源类型(或旧的面板)由 Coda 资源插件的 `Panels` 读一次(30 秒),输出合格式 |
542
555
  | 一轮(`--live`) | 要 | 声明了会话指令的经 `systemPrompt` 送入,没声明的在第一轮前加契约的 `instructionsBlock`;第一轮问会话指令里的检查词(一个随机词),回复里要有它;再发一轮提示词(默认「只回复 ok」)收到 `stopReason`;每条 `session/update` 先过 ACP SDK 的 schema,工具审核、用量与默认选项标记再过协议 schema;`_coda/wait` 用协议的 `agentMessageProblem` 校验形状,另查会话归属、登记与终态(子 Agent 不带 `childSessionId`、定时不带 `at` 只提醒);扩展形状问题按现有规则报告协议返回的「位置:说明」;远端绑定码请求先查协议参数再查本会话归属;执行失败的形状交协议校验,重试预算照 Coda 策略;审批与提问一律回拒绝,在一轮之外发来的算失败;再发一轮并 `session/cancel`,30 秒内要结束,读到取消后还在做事或拖过 5 秒才答复却不回 `cancelled` 算失败(见下);有自主轮次的也取消一次;声明插话的,答复用协议的 `agentResultProblem` 校验,一轮结束后插话要回 `promptRequired` 且不自己另开一轮,一轮进行中插话要回 `injected` 或 `promptRequired`(`injected` 的那一轮照常回 `stopReason`);声明 `loadSession` 的,新开进程 `session/load`(声明了的同样带会话指令)要成功,随后在新进程里再跑一轮也要收到 `stopReason` |
543
556
 
package/bin/check.mjs CHANGED
@@ -1,16 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  // coda-plugin-check <插件目录> [--agent <id>] [--manifest] [--live] [--prompt "…"]
3
+ // coda-plugin-check init <目录> [--template module|agent|resource]
3
4
  import { resolve } from 'node:path';
4
5
  import { parseArgs } from 'node:util';
5
6
  import pkg from '../package.json' with { type: 'json' };
6
7
  import { ACP_PROTOCOL_VERSION } from '../check/agent.mjs';
7
8
  import contract from '../check/coda/contract.json' with { type: 'json' };
8
9
  import { checkPlugin } from '../check/index.mjs';
10
+ import { init } from '../check/init.mjs';
9
11
  import { format } from '../check/report.mjs';
10
12
 
11
13
  const USAGE = `用法:coda-plugin-check <插件目录> [--agent <id>] [--manifest] [--live] [--prompt "…"]
14
+ coda-plugin-check init <目录> [--template module|agent|resource]
12
15
 
13
- 清单(总是查) package.json 能不能被 Coda 读懂,从仓库安装的限制(带 npm 依赖要有 package-lock.json)
16
+ 清单(总是查) package.json 能不能被 Coda 读懂,从仓库安装的限制(带 npm 依赖要有 package-lock.json);engines.coda 够不够用到的各项(算出该写几);列出用到的试行面
17
+ 模块(有 main) 用 Coda 自己的 coda(测试宿主)加载 main、调 activate(10 秒内要完成);模块登记的操作与清单的 protocolImplementations 两个方向对一遍;coda.on 只能订自己事件组里的事件
14
18
  握手(默认查) 照 Coda 的样子启动每个 Agent,发 initialize、session/new(声明了的带 systemPrompt,没声明的在第一轮送入指令);SIGTERM 后 5 秒内要退出(关标准输入后不退出只提醒);读每个面板一次
15
19
  一轮(--live) 每个 Agent 先问会话指令里的检查词,再发一轮提示词(默认「只回复 ok」)、再发一轮并取消(读到取消后要回 cancelled)、核对 _coda/wait;
16
20
  声明插话的,一轮结束后与一轮进行中各插话一次;声明 loadSession 的再开进程 session/load,并在新进程里再跑一轮
@@ -18,7 +22,19 @@ const USAGE = `用法:coda-plugin-check <插件目录> [--agent <id>] [--manif
18
22
  --agent <id> 只查这一个 Agent(面板不读)
19
23
  --manifest 只查清单,什么也不运行
20
24
  --live 查一轮:会真的发提示词,可能要登录、花额度
21
- --prompt "…" 一轮用的提示词`;
25
+ --prompt "…" 一轮用的提示词
26
+
27
+ init 把模板(默认 module)复制到一个新目录(须不存在或为空),插件名与协议名前缀换成目录名`;
28
+
29
+ if (process.argv[2] === 'init') {
30
+ try {
31
+ const { values: { template = 'module' }, positionals } = parseArgs({ args: process.argv.slice(3), allowPositionals: true, options: { template: { type: 'string' } } });
32
+ if (positionals.length !== 1) throw new Error(`init 要一个目录\n\n${USAGE}`);
33
+ const id = init(positionals[0], template);
34
+ console.log(`已从模板 ${template} 生成插件 ${id}:${positionals[0]}\n检查:coda-plugin-check ${positionals[0]}`);
35
+ process.exit(0);
36
+ } catch (e) { console.error(e.message); process.exit(2); }
37
+ }
22
38
 
23
39
  let options;
24
40
  try {
@@ -32,6 +32,8 @@ export function pluginEvents(plugin, asks, fire) {
32
32
  deliver(event) {
33
33
  for (const entry of [...handlers.get(event?.name) ?? []]) if (!entry.disposed) fire([entry.fn], event);
34
34
  },
35
+ // The names of the events it has handlers of now.
36
+ names() { return [...handlers].filter(([, entries]) => entries.size).map(([name]) => name); },
35
37
  // The module stopped: its handlers go.
36
38
  clear() { handlers.clear(); },
37
39
  };
@@ -1,7 +1,7 @@
1
1
  // The plugin host's modules (docs/plugins.md「插件宿主」): each plugin's that has a `main`, loaded the first time anything
2
2
  // of it is needed, or when the backend says to, and given a `coda` of its own. What the runner (adapters/plugin-host-runner.mjs)
3
3
  // runs over Node's IPC channel with the backend, and the test host (adapters/plugin-test-host.mjs) over a channel of its own:
4
- // `send(message)` to the backend, `receive(message)` from it. `adopt(plugin, token)`: a plugin's `coda` made with no module
4
+ // `send(message)` to the backend, `receive(message)` from it. `adopt(plugin, token, parts?)`: a plugin's `coda` made with no module
5
5
  // loaded, for whoever holds it to activate a module with; `stop()`: each module loaded ends what it started (`deactivate`).
6
6
  //
7
7
  // From the backend: `start { api: { url }, parts }`, `activate { plugin, token }` (before anything else of the plugin's),
@@ -508,10 +508,19 @@ export function pluginModules({ send }) {
508
508
  await services.close(false);
509
509
  if (typeof module?.deactivate === 'function') await module.deactivate();
510
510
  })));
511
- function adopt(plugin, token) {
512
- const made = codaFor(plugin, [], token);
511
+ const adopted = new Map();
512
+ function adopt(plugin, token, provided = []) {
513
+ const made = codaFor(plugin, provided, token);
514
+ adopted.set(plugin.id, made);
513
515
  loading.set(plugin.id, Promise.resolve(made));
514
516
  return made.coda;
515
517
  }
516
- return { receive, stop, adopt };
518
+ // What an adopted plugin's module has registered: its operations (`handle`), its own queries (`self.handle`: kept under
519
+ // `self`) and the events it handles (`on`).
520
+ function registered(plugin) {
521
+ const { operations, events } = adopted.get(plugin.id), kept = [...operations.keys()].map(id => JSON.parse(id));
522
+ return { operations: kept.filter(([kind]) => kind !== 'self').map(([kind, operation]) => ({ kind, operation })),
523
+ self: kept.filter(([kind]) => kind === 'self').map(([, name]) => name), events: events.names() };
524
+ }
525
+ return { receive, stop, adopt, registered };
517
526
  }
@@ -1,6 +1,7 @@
1
1
  // Types of what a plugin's module queries and answers by (docs/plugins.md「调用」, coda#2749 3.1 and 第 7 节), and of the test
2
2
  // host (plugin-test-host.mjs), and of the records (coda#2749 3.7). All on the trial surface: they may change from one
3
3
  // version of Coda to the next. Only these members of `coda` are typed here; the others are not yet.
4
+ import type { IncomingMessage, ServerResponse } from 'node:http';
4
5
  import type { Readable, Writable } from 'node:stream';
5
6
 
6
7
  export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
@@ -45,8 +46,12 @@ export interface CallOptions {
45
46
  onProgress?(value: Json): void;
46
47
  }
47
48
 
48
- /** Who is before the page that made a doing call: Coda's own client on this machine, or a device, with its name if known. */
49
- export type Caller = { local: true } | { device: string; name?: string };
49
+ /**
50
+ * Who is before the page that made a doing call: Coda's own client on this machine, or a device, with its name if known.
51
+ * A call forwarded to the backend that holds the record has no `local` but the `machine` it was made from (that one's ID),
52
+ * a device kept as it is: so `{ machine }` or `{ machine, device, name? }`.
53
+ */
54
+ export type Caller = { local: true } | { device: string; name?: string } | { machine: string; device?: string; name?: string };
50
55
 
51
56
  /** What a handler of a call is given beside its input. A handler of a query, and `resume`, have no `progress` nor `ask`. */
52
57
  export interface Context {
@@ -271,6 +276,67 @@ export interface Coda {
271
276
  * subject. What it throws is logged; the event is not given again.
272
277
  */
273
278
  on(name: string, fn: (event: Event) => void): Disposable;
279
+ /** Trial. The plugin itself: its ID, its directory, and its state directory on this backend (`null` when the backend has no state root). */
280
+ plugin: Readonly<{ id: string; path: string; state: string | null }>;
281
+ /**
282
+ * Trial. Local streaming services: `register` serves `id` on this machine (an HTTP handler, given the caller as Coda
283
+ * names it), done once Coda has it; the handle's `dispose()` withdraws it and closes its connections.
284
+ */
285
+ services: Readonly<{
286
+ register(id: string, handler: (request: IncomingMessage, response: ServerResponse, caller: Readonly<{ [key: string]: Json }>) => void | Promise<void>): Promise<{ dispose(): Promise<void> }>;
287
+ }>;
288
+ /** Trial. The plugin's own pages: `register` the provider of a view the manifest declares (`contributes.views`); its `open` is called each time one is opened. */
289
+ views: Readonly<{ register(id: string, provider: { open(view: ViewInstance): void | Promise<void> }): { dispose(): void } }>;
290
+ /** Trial. Protocol contributions and the records' services: a contributor to another protocol's records, a record's service as this machine reaches it, and an upload of this machine's. */
291
+ protocols: Readonly<{
292
+ register(kind: string, key: string, handler: (object: ProtocolObject, key: string) => Contribution | null | Promise<Contribution | null>): Disposable;
293
+ resolve(record: Ref, service: string): Promise<{ resource: Ref; url: string; headers: Record<string, string> }>;
294
+ upload(id: string): Promise<{ id: string; name: string; size: number; path: string; mime?: string; duration?: number; [key: string]: Json | undefined }>;
295
+ }>;
296
+ /** Trial. Tells a session's agent something, told with its next turn and waking nothing; `told` is `false` for a session archived. */
297
+ tell(session: string, text: string): Promise<{ told: boolean }>;
298
+ /** Trial. This machine's Coda API as its clients reach it (the path after `/v1/`): GET without a body, POST with one; the answer is JSON. */
299
+ api(path: string, body?: Json): Promise<Json>;
300
+ /** Trial. What Coda gives every process of the plugin's, for one the module starts itself; `plugin` is another installed plugin's, for a command of its the module runs. */
301
+ environment(project?: string | null, options?: { plugin?: string }): Promise<Record<string, string>>;
302
+ /** Trial. Runs an installed plugin's environment setup again, asked as this plugin; the test host's fails (`unsupported`). */
303
+ pluginSetup: Readonly<{ retry(plugin: string): Promise<Json> }>;
304
+ }
305
+
306
+ /** The record or draft a protocol hands a contributor, without who created it: its `spec` and `status` are objects the protocol's schemas describe. */
307
+ export interface ProtocolObject {
308
+ kind: string;
309
+ id: string;
310
+ spec: { [key: string]: Json };
311
+ status: { [key: string]: Json };
312
+ }
313
+
314
+ /** What a contributor adds: only the fields the protocol declares as contributions, each of the value the protocol says (an object, not a list or a scalar); `null` adds nothing. */
315
+ export type Contribution = { [field: string]: Json };
316
+
317
+ /** A page of the plugin's, opened, as its view provider's `open` is given it. */
318
+ export interface ViewInstance {
319
+ /** This opening's ID. */
320
+ id: string;
321
+ /** The view's ID. */
322
+ view: string;
323
+ /** What the page was opened beside: the session's ID, and the `args` of the button or card that opened it; `null` for none. */
324
+ context: { session: string | null; args: Json | null };
325
+ /** Who opened it: this machine's client (`{ local: true }`) or a device. */
326
+ caller: { local?: boolean; device?: string; name?: string };
327
+ /** Sends the page a message; `false` once the page is gone. */
328
+ postMessage(message: Json): boolean;
329
+ /** A collection handed to the page: `set` and `delete` give whether the page was told anything. */
330
+ collection(name: string): {
331
+ set(id: string, object: { [key: string]: Json }): boolean;
332
+ delete(id: string): boolean;
333
+ get(id: string): { [key: string]: Json } | undefined;
334
+ keys(): string[];
335
+ };
336
+ /** Each returns a handle that stops it. */
337
+ onMessage(fn: (message: Json) => void): Disposable;
338
+ onContext(fn: (context: ViewInstance['context']) => void): Disposable;
339
+ onClose(fn: () => void): Disposable;
274
340
  }
275
341
 
276
342
  /** A protocol a plugin implements, some of its operations by commands: operation name to the file that implements it. */
@@ -312,7 +378,7 @@ export interface TestCallOptions extends QueryOptions {
312
378
 
313
379
  export interface TestHost {
314
380
  /** The plugin's `coda`, for its module's `activate`. */
315
- coda: Coda & Record<string, unknown>;
381
+ coda: Coda;
316
382
  /**
317
383
  * Calls the plugin's module as a caller would: a query, or a doing call, which ends as its handler ends it. An operation
318
384
  * one of its commands implements is run as Coda runs it: its input on standard input, its exit code first, its output
@@ -340,6 +406,8 @@ export interface TestHost {
340
406
  * protocol the plugin defines or implements, not one of Coda's own, as its payload schema has it.
341
407
  */
342
408
  emitted: Omit<Event, 'publisher'>[];
409
+ /** What the module has registered so far: its operations (`coda.handle`), its own queries' names (`coda.self.handle`) and the events it handles (`coda.on`). */
410
+ registered(): { operations: { kind: string; operation: string }[]; self: string[]; events: string[] };
343
411
  close(): Promise<unknown>;
344
412
  }
345
413
 
@@ -89,7 +89,9 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
89
89
  const ending = new AbortController();
90
90
  // What the module sends the backend, taken after the turn it is sent in, as over a process's channel.
91
91
  const modules = pluginModules({ send: message => queueMicrotask(() => taken(message)) });
92
- const coda = modules.adopt(described, randomUUID());
92
+ // `coda.pluginSetup`, a part the backend provides, is there as the module has it, but fails: the test host has no backend to ask.
93
+ const setup = () => ({ retry: async () => { throw refused('unsupported', '测试宿主不提供 coda.pluginSetup'); } });
94
+ const coda = modules.adopt(described, randomUUID(), [['pluginSetup', setup]]);
93
95
  // The records, by kind, each an entry (`{ owner, location, id, plugin, local, spec, status, labels?, version }`) by its holder and
94
96
  // ID, and the keys of those of each kind the plugin holds, by their IDs (record-rules.mjs `recordId`); and the module's
95
97
  // watches of them, by the watch's key, each with what it was last told.
@@ -420,6 +422,9 @@ export function createTestHost({ plugin = {}, call = null, clock = new Clock(),
420
422
  emit: event => modules.receive({ method: 'event', params: { plugin: described.id, event: structuredClone(event) } }),
421
423
  // The events the module published (`coda.emit`), in order: `{ name, kind, subject, project, data }` each.
422
424
  emitted,
425
+ // What the module has registered so far: `{ operations: [{ kind, operation }], self: [name], events: [name] }`, by
426
+ // `coda.handle`, `coda.self.handle` and `coda.on`.
427
+ registered: () => modules.registered(described),
423
428
  // The plugin's settings written again, as `Plugins.setSettings` leaves them: what the module's `settings.get` gives from now
424
429
  // on, and what its `settings.onChange` listeners are told, which have been by the time this is done.
425
430
  setSettings: async next => {
@@ -0,0 +1,349 @@
1
+ # Coda 对插件开放的面与 API Level:集合,任何变化都算动了骨架。由 node scripts/skeleton.mjs update 生成,规则见脚本开头。
2
+ 1 bridge window.coda.args
3
+ 1 bridge window.coda.back
4
+ 1 bridge window.coda.call
5
+ 1 bridge window.coda.choose
6
+ 1 bridge window.coda.close
7
+ 1 bridge window.coda.copy
8
+ 1 bridge window.coda.deliver
9
+ 1 bridge window.coda.describe
10
+ 1 bridge window.coda.float
11
+ 1 bridge window.coda.get
12
+ 1 bridge window.coda.getState
13
+ 1 bridge window.coda.header
14
+ 1 bridge window.coda.inline
15
+ 1 bridge window.coda.items
16
+ 1 bridge window.coda.keyboard
17
+ 1 bridge window.coda.layout
18
+ 1 bridge window.coda.lib
19
+ 1 bridge window.coda.list
20
+ 1 bridge window.coda.machine
21
+ 1 bridge window.coda.machines
22
+ 1 bridge window.coda.on
23
+ 1 bridge window.coda.open
24
+ 1 bridge window.coda.place
25
+ 1 bridge window.coda.platform
26
+ 1 bridge window.coda.plugin
27
+ 1 bridge window.coda.postMessage
28
+ 1 bridge window.coda.query
29
+ 1 bridge window.coda.relay
30
+ 1 bridge window.coda.screens
31
+ 1 bridge window.coda.scroll
32
+ 1 bridge window.coda.scrollTo
33
+ 1 bridge window.coda.self
34
+ 1 bridge window.coda.session
35
+ 1 bridge window.coda.setState
36
+ 1 bridge window.coda.toolbar
37
+ 1 bridge window.coda.view
38
+ 1 bridge window.coda.warm
39
+ 1 bridge window.coda.watch
40
+ 1 coda/agent@1
41
+ 1 coda/agent@1 read
42
+ 1 coda/agent@1 read records
43
+ 1 coda/agent@1 spawn
44
+ 1 coda/agent@1 spawn operation spawn
45
+ 1 coda/card@1
46
+ 1 coda/composer@1
47
+ 1 coda/composer@1 read
48
+ 1 coda/composer@1 read records
49
+ 1 coda/environment@1
50
+ 1 coda/environment@1 read
51
+ 1 coda/environment@1 read operation list
52
+ 1 coda/environment@1 read operation read
53
+ 1 coda/environment@1 read records
54
+ 1 coda/group@1
55
+ 1 coda/group@1 read
56
+ 1 coda/group@1 read records
57
+ 1 coda/plugin@1
58
+ 1 coda/plugin@1 read
59
+ 1 coda/plugin@1 read records
60
+ 1 coda/project@1
61
+ 1 coda/project@1 read
62
+ 1 coda/project@1 read operation branches
63
+ 1 coda/project@1 read records
64
+ 1 coda/run@1
65
+ 1 coda/run@1 cancel
66
+ 1 coda/run@1 cancel operation cancel
67
+ 1 coda/run@1 read
68
+ 1 coda/run@1 read records
69
+ 1 coda/session@1
70
+ 1 coda/session@1 post
71
+ 1 coda/session@1 post operation post
72
+ 1 coda/session@1 read
73
+ 1 coda/session@1 read operation read
74
+ 1 coda/session@1 read records
75
+ 1 coda/submission@1
76
+ 1 coda/thread@1
77
+ 1 coda/thread@1 append-draft
78
+ 1 coda/thread@1 append-draft operation append-draft
79
+ 1 coda/thread@1 changes
80
+ 1 coda/thread@1 changes operation changes
81
+ 1 coda/thread@1 changes stream diff
82
+ 1 coda/thread@1 read
83
+ 1 coda/thread@1 read records
84
+ 1 coda/thread@1 workflows
85
+ 1 coda/thread@1 workflows operation workflows
86
+ 1 coda/thread@1 workspace
87
+ 1 coda/thread@1 workspace operation workspace
88
+ 1 coda/workflow-run@1
89
+ 1 coda/workflow-run@1 control
90
+ 1 coda/workflow-run@1 control operation cancel
91
+ 1 coda/workflow-run@1 control operation message
92
+ 1 coda/workflow-run@1 control operation renew
93
+ 1 coda/workflow-run@1 control operation resume
94
+ 1 coda/workflow-run@1 read
95
+ 1 coda/workflow-run@1 read operation graph
96
+ 1 coda/workflow-run@1 read operation history
97
+ 1 coda/workflow-run@1 read operation private
98
+ 1 coda/workflow-run@1 read operation recent
99
+ 1 coda/workflow-run@1 read operation requirement
100
+ 1 coda/workflow-run@1 read records
101
+ 1 coda/workflow-run@1 read stream log
102
+ 1 coda/workflow-run@1 task
103
+ 1 coda/workflow-run@1 task operation task
104
+ 1 coda/workflow@1
105
+ 1 coda/workflow@1 configure
106
+ 1 coda/workflow@1 configure operation save-settings
107
+ 1 coda/workflow@1 read
108
+ 1 coda/workflow@1 read operation settings
109
+ 1 coda/workflow@1 read records
110
+ 1 coda/workflow@1 run
111
+ 1 coda/workflow@1 run operation run
112
+ 1 manifest activationEvents
113
+ 1 manifest categories
114
+ 1 manifest coda
115
+ 1 manifest coda.channels
116
+ 1 manifest contributes
117
+ 1 manifest contributes.agents
118
+ 1 manifest contributes.capabilities
119
+ 1 manifest contributes.commands
120
+ 1 manifest contributes.composerModes
121
+ 1 manifest contributes.configuration
122
+ 1 manifest contributes.environment
123
+ 1 manifest contributes.extensionPoints
124
+ 1 manifest contributes.extensions
125
+ 1 manifest contributes.gitCredentials
126
+ 1 manifest contributes.instructions
127
+ 1 manifest contributes.mcpServers
128
+ 1 manifest contributes.modelProviders
129
+ 1 manifest contributes.path
130
+ 1 manifest contributes.processes
131
+ 1 manifest contributes.protocolImplementations
132
+ 1 manifest contributes.protocols
133
+ 1 manifest contributes.repositories
134
+ 1 manifest contributes.services
135
+ 1 manifest contributes.setup
136
+ 1 manifest contributes.skills
137
+ 1 manifest contributes.views
138
+ 1 manifest description
139
+ 1 manifest displayName
140
+ 1 manifest engines
141
+ 1 manifest engines.coda
142
+ 1 manifest extensionDependencies
143
+ 1 manifest icon
144
+ 1 manifest id
145
+ 1 manifest main
146
+ 1 manifest name
147
+ 1 manifest uses
148
+ 1 manifest version
149
+ 1 stable manifest categories
150
+ 1 stable manifest contributes.agents[].command
151
+ 1 stable manifest contributes.agents[].configFiles[]
152
+ 1 stable manifest contributes.agents[].displayName
153
+ 1 stable manifest contributes.agents[].icon.dark
154
+ 1 stable manifest contributes.agents[].icon.light
155
+ 1 stable manifest contributes.agents[].icon.template
156
+ 1 stable manifest contributes.agents[].id
157
+ 1 stable manifest contributes.agents[].modes.auto
158
+ 1 stable manifest contributes.agents[].modes.full
159
+ 1 stable manifest contributes.agents[].modes.note
160
+ 1 stable manifest contributes.agents[].modes.title
161
+ 1 stable manifest contributes.agents[].modes.unset
162
+ 1 stable manifest contributes.agents[].setupHint
163
+ 1 stable manifest contributes.agents[].skillsDir
164
+ 1 stable manifest contributes.commands[].command
165
+ 1 stable manifest contributes.commands[].name
166
+ 1 stable manifest contributes.configuration.properties.*
167
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*
168
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.default
169
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.description
170
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.enum
171
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.format
172
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.format values coda-model-provider
173
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.format values coda-model-url
174
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.minimum
175
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.modelApi
176
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.modelKey
177
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.order
178
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.title
179
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.type
180
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.properties.*.writeOnly
181
+ 1 stable manifest contributes.configuration.properties.*.additionalProperties.type
182
+ 1 stable manifest contributes.configuration.properties.*.default
183
+ 1 stable manifest contributes.configuration.properties.*.description
184
+ 1 stable manifest contributes.configuration.properties.*.order
185
+ 1 stable manifest contributes.configuration.properties.*.title
186
+ 1 stable manifest contributes.configuration.properties.*.type
187
+ 1 stable manifest contributes.configuration.title
188
+ 1 stable manifest contributes.environment.*
189
+ 1 stable manifest contributes.setup.command
190
+ 1 stable manifest contributes.skills[]
191
+ 1 stable manifest contributes.views[].entry
192
+ 1 stable manifest contributes.views[].icon
193
+ 1 stable manifest contributes.views[].id
194
+ 1 stable manifest contributes.views[].in[]
195
+ 1 stable manifest contributes.views[].in[] values side
196
+ 1 stable manifest contributes.views[].title
197
+ 1 stable manifest description
198
+ 1 stable manifest displayName
199
+ 1 stable manifest engines.coda
200
+ 1 stable manifest icon.color
201
+ 1 stable manifest icon.symbol
202
+ 1 stable manifest id
203
+ 1 stable manifest main
204
+ 1 stable manifest name
205
+ 1 stable manifest uses.*[]
206
+ 1 stable manifest version
207
+ 1 stable view root.classes
208
+ 1 stable view root.classes values coda-dark
209
+ 1 stable view root.classes values coda-ios
210
+ 1 stable view root.classes values coda-light
211
+ 1 stable view root.classes values coda-mac
212
+ 1 stable view root.cssVariables
213
+ 1 stable view root.cssVariables values --coda-accent
214
+ 1 stable view root.cssVariables values --coda-background
215
+ 1 stable view root.cssVariables values --coda-card
216
+ 1 stable view root.cssVariables values --coda-fill
217
+ 1 stable view root.cssVariables values --coda-font
218
+ 1 stable view root.cssVariables values --coda-font-size
219
+ 1 stable view root.cssVariables values --coda-foreground
220
+ 1 stable view root.cssVariables values --coda-hover
221
+ 1 stable view root.cssVariables values --coda-mono
222
+ 1 stable view root.cssVariables values --coda-orange
223
+ 1 stable view root.cssVariables values --coda-outline
224
+ 1 stable view root.cssVariables values --coda-radius
225
+ 1 stable view root.cssVariables values --coda-radius-card
226
+ 1 stable view root.cssVariables values --coda-secondary
227
+ 1 stable view root.cssVariables values --coda-secondary-background
228
+ 1 stable view root.cssVariables values --coda-selection
229
+ 1 stable view root.cssVariables values --coda-separator
230
+ 1 stable view root.cssVariables values --coda-tertiary
231
+ 1 stable view window
232
+ 1 stable view window events message
233
+ 1 stable view window.coda.args
234
+ 1 stable view window.coda.back
235
+ 1 stable view window.coda.close
236
+ 1 stable view window.coda.copy
237
+ 1 stable view window.coda.getState
238
+ 1 stable view window.coda.on
239
+ 1 stable view window.coda.on events back
240
+ 1 stable view window.coda.on events context
241
+ 1 stable view window.coda.on events theme
242
+ 1 stable view window.coda.on events toolbar
243
+ 1 stable view window.coda.on events visibility
244
+ 1 stable view window.coda.open
245
+ 1 stable view window.coda.open targets args
246
+ 1 stable view window.coda.open targets view
247
+ 1 stable view window.coda.platform
248
+ 1 stable view window.coda.postMessage
249
+ 1 stable view window.coda.setState
250
+ 1 stable view window.coda.toolbar
251
+ 1 stable view window.coda.toolbar fields icon
252
+ 1 stable view window.coda.toolbar fields id
253
+ 1 stable view window.coda.toolbar fields kind
254
+ 1 stable view window.coda.toolbar fields label
255
+ 1 stable view window.coda.toolbar fields on
256
+ 1 stable view window.coda.toolbar kinds button
257
+ 1 stable view window.coda.toolbar kinds toggle
258
+ 2 bridge window.coda.refresh
259
+ 2 manifest contributes.records
260
+ 2 manifest contributes.self
261
+ 3 definition description
262
+ 3 definition events
263
+ 3 definition events.description
264
+ 3 definition events.ends
265
+ 3 definition events.payload
266
+ 3 definition events.starts
267
+ 3 definition name
268
+ 3 definition operations
269
+ 3 definition operations.description
270
+ 3 definition operations.idempotent
271
+ 3 definition operations.input
272
+ 3 definition operations.result
273
+ 3 definition operations.run
274
+ 3 definition operations.safe
275
+ 3 definition operations.timeout
276
+ 3 definition permissions
277
+ 3 definition permissions.events
278
+ 3 definition permissions.operations
279
+ 3 definition permissions.read
280
+ 3 definition permissions.streams
281
+ 3 definition permissions.title
282
+ 3 definition permissions.trial
283
+ 3 definition plural
284
+ 3 definition spec
285
+ 3 definition status
286
+ 3 definition streams
287
+ 3 definition streams.description
288
+ 3 definition streams.input
289
+ 3 definition title
290
+ 3 module coda.api
291
+ 3 module coda.call
292
+ 3 module coda.delete
293
+ 3 module coda.emit
294
+ 3 module coda.environment
295
+ 3 module coda.error
296
+ 3 module coda.get
297
+ 3 module coda.handle
298
+ 3 module coda.list
299
+ 3 module coda.on
300
+ 3 module coda.plugin
301
+ 3 module coda.plugin.id
302
+ 3 module coda.plugin.path
303
+ 3 module coda.plugin.state
304
+ 3 module coda.pluginSetup
305
+ 3 module coda.pluginSetup.retry
306
+ 3 module coda.protocols
307
+ 3 module coda.protocols.register
308
+ 3 module coda.protocols.resolve
309
+ 3 module coda.protocols.upload
310
+ 3 module coda.put
311
+ 3 module coda.query
312
+ 3 module coda.replace
313
+ 3 module coda.self
314
+ 3 module coda.self.handle
315
+ 3 module coda.services
316
+ 3 module coda.services.register
317
+ 3 module coda.settings
318
+ 3 module coda.settings.get
319
+ 3 module coda.settings.onChange
320
+ 3 module coda.spawn
321
+ 3 module coda.tell
322
+ 3 module coda.views
323
+ 3 module coda.views.register
324
+ 3 module coda.watch
325
+ 3 module ctx.ask
326
+ 3 module ctx.call
327
+ 3 module ctx.caller
328
+ 3 module ctx.deadline
329
+ 3 module ctx.id
330
+ 3 module ctx.progress
331
+ 3 module ctx.query
332
+ 3 module ctx.record
333
+ 3 module ctx.signal
334
+ 3 module ctx.spawn
335
+ 4 coda/usage@1
336
+ 4 coda/usage@1 read
337
+ 4 coda/usage@1 read operation buckets
338
+ 4 coda/usage@1 read records
339
+ 5 coda/accord@1
340
+ 5 coda/accord@1 manage
341
+ 5 coda/accord@1 manage operation accept
342
+ 5 coda/accord@1 manage operation handshake
343
+ 5 coda/accord@1 manage operation remove
344
+ 5 coda/accord@1 publish
345
+ 5 coda/accord@1 publish operation publish
346
+ 5 coda/accord@1 read
347
+ 5 coda/accord@1 read operation records
348
+ 5 coda/accord@1 read records
349
+ level 5
@@ -7,6 +7,8 @@
7
7
  // (CORE_PROTOCOLS).
8
8
  import { PLUGIN_PROTOCOL } from '../kernel/plugin-protocol.mjs';
9
9
  import { PROJECT_PROTOCOL } from '../kernel/project-protocol.mjs';
10
+ import { USAGE_PROTOCOL } from '../kernel/usage-protocol.mjs';
11
+ import { ACCORD_PROTOCOL } from '../kernel/accord-protocol.mjs';
10
12
  import { THREAD_PROTOCOL } from '../kernel/thread-protocol.mjs';
11
13
  import { composerType, submissionType } from '../components/composers/schemas.mjs';
12
14
  import { groupType } from '../components/concurrency-groups/schemas.mjs';
@@ -14,4 +16,4 @@ import { WORKFLOW_PROTOCOL, WORKFLOW_RUN_PROTOCOL, withWorkflows } from '../comp
14
16
 
15
17
  // A session's, with the workflows' query and the group that has it (workflow-protocol-definitions.mjs `withWorkflows`).
16
18
  export const THREAD_DEFINITION = withWorkflows(THREAD_PROTOCOL);
17
- export const HOST_PROTOCOLS = [THREAD_DEFINITION, PROJECT_PROTOCOL, PLUGIN_PROTOCOL, WORKFLOW_PROTOCOL, WORKFLOW_RUN_PROTOCOL, composerType, submissionType, groupType];
19
+ export const HOST_PROTOCOLS = [THREAD_DEFINITION, PROJECT_PROTOCOL, PLUGIN_PROTOCOL, USAGE_PROTOCOL, ACCORD_PROTOCOL, WORKFLOW_PROTOCOL, WORKFLOW_RUN_PROTOCOL, composerType, submissionType, groupType];
@@ -98,7 +98,7 @@ export function implementsMissing(plugin, plugins, defined) {
98
98
  }
99
99
  // This Coda's API Level (docs/plugins.md「兼容」): what it offers plugins, counted. A manifest's `engines.coda` names the least
100
100
  // a plugin needs; one naming none needs 0, which any Coda has.
101
- export const API_LEVEL = 2;
101
+ export const API_LEVEL = 5;
102
102
  // The API Level a package's registry metadata asks for in its `engines`: a positive integer, or its digits as text (what
103
103
  // npm's registry may make of one); undefined when it asks for none, null when it is anything else. A manifest read from
104
104
  // its directory has the schema's shape (plugin-rules.mjs readPlugin).