@coda-console/plugin-check 0.8.26 → 0.8.28
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.
- package/README.md +49 -42
- package/bin/check.mjs +3 -3
- package/check/coda/adapters/plugin-modules.mjs +2 -7
- package/check/coda/adapters/plugin-test-host.d.mts +0 -2
- package/check/coda/api-surface.txt +8 -2
- package/check/coda/builtin.json +44 -1400
- package/check/coda/components/plugins/plugin-extensions.mjs +7 -6
- package/check/coda/components/plugins/plugin-rules.mjs +6 -44
- package/check/coda/components/plugins/plugin-source-rules.mjs +19 -15
- package/check/coda/contract.json +10 -13
- package/check/index.mjs +5 -4
- package/check/leftovers.mjs +1 -1
- package/check/manifest.mjs +7 -9
- package/check/module.mjs +5 -5
- package/check/report.mjs +1 -1
- package/check/resources.mjs +99 -0
- package/package.json +5 -4
- package/templates/resource/package.json +13 -10
- package/templates/resource/scripts/act.mjs +20 -0
- package/templates/resource/scripts/{resources.mjs → resource.mjs} +10 -5
- package/check/coda/resources/plugins/resources/panels/panels.mjs +0 -313
- package/check/coda/resources/plugins/resources/panels/rules.mjs +0 -232
- package/check/coda/resources/plugins/resources/panels/sign-in.mjs +0 -122
- package/check/panel.mjs +0 -78
- package/templates/resource/scripts/mark.mjs +0 -6
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Coda 插件
|
|
2
2
|
|
|
3
|
-
Coda 的公开插件仓库,和给插件作者用的契约检查。
|
|
3
|
+
Coda 的公开插件仓库,和给插件作者用的契约检查。Agent 插件(Codex、Claude、Kimi、Grok、OpenCode 与 Codex 多账号)和 PR 生命流程也在这里维护,用户在 Coda 的商店里安装。
|
|
4
4
|
|
|
5
5
|
Coda 是一个多 Agent 客户端(Mac、iPhone 与运行在你机器上的后端)。Agent 与资源页上的资源都以插件接入:
|
|
6
|
-
插件是一个目录,清单就是它的 `package.json`(`contributes.agents`、`contributes.
|
|
6
|
+
插件是一个目录,清单就是它的 `package.json`(`contributes.agents`、`contributes.records` 等,照 VS Code 扩展的写法);
|
|
7
7
|
Agent 讲 [ACP](https://agentclientprotocol.com),外加 Coda 的 Agent 活动报告 `_coda/wait`,见 [接入协议](https://github.com/coda-console/coda-protocol/blob/main/docs/agent-protocol.md)。
|
|
8
8
|
插件清单的类型、它们的 schema 与接入协议都在协议包 `@coda-console/protocol`([coda-console/coda-protocol](https://github.com/coda-console/coda-protocol))里;本仓库文中与代码注释说的 `docs/agent-protocol.md` 指那里的那份。
|
|
9
9
|
|
|
@@ -21,16 +21,17 @@ plugins/git/ Git 源与快照:本机仓库 provider、运行关联
|
|
|
21
21
|
plugins/host/ 宿主资源:Xcode 构建、Apple 模拟器与项目要求排队的命令共用这台机器的一组名额(组 host、持锁执行 run-held、host-sim),资源「构建名额」
|
|
22
22
|
plugins/magpie/ Magpie:把本机的 Magpie 网关作为模型服务提供给 Pi 等插件,安装时装好 Magpie 并让网关常驻
|
|
23
23
|
plugins/network-log/ 网络记录:默认关闭,按需开启建连等待与定时探测采集;关闭后仍可查看历史
|
|
24
|
+
plugins/friends/ 好友:Accord 身份与公开名片、接受好友邀请并互认、好友列表与仅存本机的备注
|
|
24
25
|
plugins/review/ PR 生命流程:会话开的 PR 先跑项目的检查、再交叉评审,你批准后合并、部署与发布,别人的 PR 只评审;也是写 PR 流程的样例
|
|
25
26
|
plugins/desktop-pet/ 桌面宠物:Coda 娘待在 Mac 桌面上,Agent 在跑时打字,有事等你时举卡片叫你(Coda 的浮窗)
|
|
27
|
+
plugins/token-board/ Token 消耗榜:看本机的 Token 用量,可选向好友分享匿名每日汇总并看熟人消耗榜(coda/usage@1 只读,coda/accord@1 读与发布)
|
|
26
28
|
plugins/testbed/ 测试机:长插在 Mac 上的 iPhone、iPad 只经 use-testbed 使用,排到后装 App、交给会话操作、用完切黑屏;依赖宿主资源
|
|
27
29
|
plugins/composer/ 输入框模式与开发流程:监督开发(一个需求一条需求分支,主 Agent 把一块块改动合进需求分支,用户批准一次)与需求交付;Ultra 名单引用 composer.templates
|
|
28
30
|
templates/agent/ 最小的 Agent 插件:手写 ACP 的回声 Agent,演示会话指令、插话、Agent 活动与自主轮次
|
|
29
|
-
templates/resource/
|
|
31
|
+
templates/resource/ 最小的资源插件:一条记录命令、一条 `act` 命令,一个资源、两个读数、一个按钮
|
|
30
32
|
templates/module/ 带模块的插件:自己的协议(一个查询、一个做事的操作、一个事件),模块登记操作、写记录、发布并订阅事件,附测试
|
|
31
33
|
bin/、check/ 契约检查(仓库根的 package.json 就是它,@coda-console/plugin-check);check/coda/ 是 Coda 同步来的规则副本,不要手改
|
|
32
34
|
test/ 检查包的测试;test/plugins/ 是各插件的测试(插件目录里只放运行要用的文件)
|
|
33
|
-
.coda/workflows/ 本仓库自己的流程:sync-coda 等新版本发到 npm,再给 Coda 开升级依赖的 PR
|
|
34
35
|
```
|
|
35
36
|
|
|
36
37
|
## 商店
|
|
@@ -43,24 +44,19 @@ Coda 插件页的「商店」列出 Coda 自带的插件,以及 npm 上 `@coda
|
|
|
43
44
|
- **下架**:给它的最新版标 `npm deprecate`,商店就不再列它。
|
|
44
45
|
- 别处的插件(别的仓库、别的 npm 包)不在商店里,用户在 Coda 里填仓库地址或包名添加。
|
|
45
46
|
|
|
46
|
-
##
|
|
47
|
+
## 常用的 Agent 与流程插件
|
|
47
48
|
|
|
48
|
-
`codex`、`claude`、`kimi`、`grok`、`opencode`、`codex-accounts`、`review`
|
|
49
|
-
合进 main 后它们发布为 npm 包 `@coda-console/<id>`([npm 发布](#npm-发布)
|
|
50
|
-
随后端的 `npm ci` 装好,新机器首次启动就带着它们。
|
|
49
|
+
`codex`、`claude`、`kimi`、`grok`、`opencode`、`codex-accounts`、`review` 的源码在这里维护。
|
|
50
|
+
合进 main 后它们发布为 npm 包 `@coda-console/<id>`([npm 发布](#npm-发布));Coda 不随安装包带它们,用户在商店里安装,装的就是 npm 上的包。
|
|
51
51
|
|
|
52
|
-
- **改它们先在这里提 PR
|
|
53
|
-
升依赖由本仓库的部署流程 `sync-coda`(`.coda/workflows/sync-coda.bpmn`、`scripts/sync-coda.mjs`)做:合并时勾选「部署」,它在合并提交上先等
|
|
54
|
-
`publish.yml` 跑完、npm 读得到这个提交的版本(发布失败就带着那次运行的地址失败),再把 Coda 用到的包升到这些版本(只升不降)、照抄插件的 `overrides`,
|
|
55
|
-
推到 Coda 的分支 `sync/coda-plugins` 并开 PR(开着的就只更新),PR 由开这边 PR 的会话负责、走 Coda 的 PR 流程;Coda 已是这些版本就什么都不做。
|
|
56
|
-
也可以单独发起,同步默认分支的最新提交。
|
|
52
|
+
- **改它们先在这里提 PR、合并**,发布流程发出新版本就完了:不用给 Coda 开改依赖的 PR,各台 Coda 自己更新(默认自动更新插件,也可在「设置 › 插件」点「检查更新」)。
|
|
57
53
|
- **改了哪个插件就升哪个插件的 `version`**(`plugins/<id>/` 下任何文件,含 `package-lock.json`;只改 `test/` 不用):Coda 的插件页与遥测按版本认插件。
|
|
58
54
|
CI 在 PR 上运行 `node scripts/check-versions.mjs origin/<目标分支>` 核对;Dependabot 升 CLI、SDK 的 PR 也要补一个升版本的提交。
|
|
59
|
-
- Coda
|
|
55
|
+
- Coda 自带插件的 ID 和 `coda`,外部插件不能用。
|
|
60
56
|
- 测的是插件自己代码的用例在 `test/plugins/<id>/`;把 Coda 与入口合在一起测的(启动 Coda 后端、写进 Coda 的存储)留在 Coda,对它装的 npm 包跑。
|
|
61
57
|
`review` 是一个流程,要 Coda 的流程引擎才跑得起来,它的用例都在 Coda。
|
|
62
58
|
|
|
63
|
-
| 插件 | npm
|
|
59
|
+
| 插件 | npm 依赖 | 运行机上另要 |
|
|
64
60
|
| --- | --- | --- |
|
|
65
61
|
| `codex` | `@agentclientprotocol/codex-acp` 1.12.0、`@openai/codex` 0.169.0;`overrides` 让 codex-acp 用同一个 `@openai/codex` | — |
|
|
66
62
|
| `claude` | `@agentclientprotocol/sdk` 1.4.0、`@anthropic-ai/claude-agent-sdk` 0.3.312(平台二进制是 SDK 自己的可选依赖) | — |
|
|
@@ -337,12 +333,11 @@ Codex 用普通 ACP 选择型配置项 `service-tier`(「速度」)报告速
|
|
|
337
333
|
|
|
338
334
|
### Codex 账号与额度
|
|
339
335
|
|
|
340
|
-
`codex` 与 `codex-accounts`
|
|
341
|
-
|
|
336
|
+
`codex` 与 `codex-accounts` 是两个独立插件,都在商店里安装;多账号插件需用户主动安装。
|
|
337
|
+
未安装多账号插件时保留 Codex 原生登录与额度看板,安装后由多账号插件接管,卸载后恢复。
|
|
342
338
|
|
|
343
339
|
`codex-accounts` 2.0.0 自己管理账号,不需要预装账号管理器或 Python。安装时 Coda 安装它的 npm 依赖和
|
|
344
|
-
`codex` 插件;本版接管额度、登录入口和续期通知的配套入口是 `codex` 1.1.0
|
|
345
|
-
Coda 升级依赖时也一起升这两个包。
|
|
340
|
+
`codex` 插件;本版接管额度、登录入口和续期通知的配套入口是 `codex` 1.1.0。已有安装的更新由各台 Coda 本机做(默认自动更新),两个插件各自更新。
|
|
346
341
|
|
|
347
342
|
- 首次使用会把运行机 `$CODEX_HOME/auth.json`(默认 `~/.codex/auth.json`)里的 ChatGPT 登录导入插件,作为第一个
|
|
348
343
|
普通受控账号并默认选用。原文件保留;之后的凭据、续期与选择都由插件维护,原登录文件后续变化不会替换受控账号。
|
|
@@ -411,8 +406,7 @@ Kimi 在一轮失败后暂停 goal,goal 的定时随之以 `failed` 结束,
|
|
|
411
406
|
Codex 会话、资源与登录用的 Codex CLI 就是 `codex` 插件依赖的 `@openai/codex`;Claude 的是 `claude` 插件依赖的
|
|
412
407
|
`@anthropic-ai/claude-agent-sdk`。插件按包名从自己的依赖里找它们,Coda 不另给路径。升级就是改这两个版本:
|
|
413
408
|
Dependabot(`.github/dependabot.yml`)每周为它们各开一个 PR,连同 `package-lock.json` 一起改;合并后在 Coda「设置 › 插件」
|
|
414
|
-
|
|
415
|
-
Coda 根上的同一条 overrides 由 `sync-coda` 一起改(npm 只认根的,Coda 的测试会核对);合并前用真实会话跑一轮。
|
|
409
|
+
对该插件点「检查更新」(默认自动更新的各台 Coda 自己会取到)。升 `@openai/codex` 时 codex-acp 经 `overrides` 跟着用新版本;合并前用真实会话跑一轮。
|
|
416
410
|
升 `@openai/codex` 还要登记新 Codex 带来的东西,见 [Codex 没适配的东西](#codex-没适配的东西)。
|
|
417
411
|
升 `@anthropic-ai/claude-agent-sdk` 要先把新 SDK 的消息类型与内容块登记进 `plugins/claude/agent/registry.mjs`,`npm test` 里的升级检查会列出没登记的,
|
|
418
412
|
见 [plugins/claude/README.md](plugins/claude/README.md)「认不出的东西」。
|
|
@@ -422,11 +416,11 @@ Coda 根上的同一条 overrides 由 `sync-coda` 一起改(npm 只认根的
|
|
|
422
416
|
「设置 › 插件 › 从仓库添加…」:
|
|
423
417
|
|
|
424
418
|
1. **仓库**填 `coda-console/coda-plugins`(或 `https://github.com/coda-console/coda-plugins`);**版本**留空是默认分支,也可以填分支、标签或完整的提交号。
|
|
425
|
-
2. **读取**:Coda 拉取那个提交,把仓库根与两层以内 `package.json` 带 `contributes` 的目录各列成一个插件——这个仓库里是 `plugins/`
|
|
426
|
-
3. 选一个,确认里逐条列出它会运行的命令(Agent 的 `command
|
|
419
|
+
2. **读取**:Coda 拉取那个提交,把仓库根与两层以内 `package.json` 带 `contributes` 的目录各列成一个插件——这个仓库里是 `plugins/` 下的各个插件与三个模板。已装的外部插件(如商店里装的 `@coda-console/<id>`)可以用这里的同名插件替换;Coda 真正自带的插件(Coda 资源目录里的那些)的 ID 外部不能占用,装不了同名的。
|
|
420
|
+
3. 选一个,确认里逐条列出它会运行的命令(Agent 的 `command`、资源的记录命令与 `act` 等命令),确认就是批准:这些命令以你的账户在空间里每台机器上运行,Coda 不做隔离,只装你信任的来源。
|
|
427
421
|
|
|
428
422
|
**Coda 只认提交**:安装时钉在读取到的那个提交上,每台机器各自取同一个提交。「检查更新」用记下的仓库与版本再读一次,提交变了才有更新;
|
|
429
|
-
上一个提交留着,可以回退。清单里的 `version` 只作显示,不参与比较——改了行为就把它加一,方便人看。这个仓库不打标签、不发 npm
|
|
423
|
+
上一个提交留着,可以回退。清单里的 `version` 只作显示,不参与比较——改了行为就把它加一,方便人看。这个仓库不打标签、不发 release;发 npm 的方式见下面的「npm 发布」。
|
|
430
424
|
|
|
431
425
|
自己的插件可以放在自己的仓库里(单插件仓库让仓库根就是插件目录),在自己的 Mac 上试的时候,仓库填本机仓库的绝对路径即可:Coda 读的是**提交**,没提交的改动它看不到。
|
|
432
426
|
|
|
@@ -446,9 +440,9 @@ Agent 模板里 Agent 的 `id` 不随目录名变,按需自己改。
|
|
|
446
440
|
**清单**(`package.json`)
|
|
447
441
|
|
|
448
442
|
- `name` 是包名;另写 `id` 时以它为 Coda 插件 ID,否则以 `name` 为 ID。ID 只能用小写字母、数字和 `-`,以字母开头,至多 40 个字符。
|
|
449
|
-
本仓库的包名是 `@coda-console/<id>`,设置名与 Agent ID 仍使用原来的插件 ID
|
|
443
|
+
本仓库的包名是 `@coda-console/<id>`,设置名与 Agent ID 仍使用原来的插件 ID。可以与已装的外部插件同名(用别的来源替换它);不能与 Coda 自带的插件(Coda 资源目录里的那些)同名:这是安装时的规矩,Coda 拒绝装与自带插件同 ID 的外部插件。契约检查不因同 ID 判失败,`manifest.name` 只提示一句「Coda 也自带这个 ID」。
|
|
450
444
|
- `displayName`、`description`、`version` 显示在安装确认与插件页。
|
|
451
|
-
- `contributes` 只能有 Coda 认识的贡献:`agents`、`
|
|
445
|
+
- `contributes` 只能有 Coda 认识的贡献:`agents`、`records`、`protocolImplementations`、`configuration`、`capabilities`、`instructions`、`extensionPoints`、`extensions`、`commands`、`services`、`setup`;读不懂的键一律报错,不会被悄悄忽略。
|
|
452
446
|
- `setup` 是插件的设置动作:`{ "command": "…" }`,一行、不超过 4000 字(与资源命令同样的规则),没有别的键。
|
|
453
447
|
|
|
454
448
|
**从仓库安装的限制**:带 npm 依赖(`dependencies`、`optionalDependencies`)就要把 `package-lock.json` 一起提交,Coda 在插件的版本目录里
|
|
@@ -466,7 +460,7 @@ Agent 模板里 Agent 的 `id` 不随目录名变,按需自己改。
|
|
|
466
460
|
| `modes` | 可省:`title`、`unset`、`note` 是模式选择的标题与说明;`auto`、`full` 是这个 Agent 的「自动审批」「全部放行」各是哪个 ACP 模式 |
|
|
467
461
|
| `skillsDir`、`configFiles`、`setupHint` | 可省:Agent 在工作副本里找 skills 的目录;它读模型列表的配置文件(变了 Coda 重读);用不了时给用户的一句话 |
|
|
468
462
|
|
|
469
|
-
Agent
|
|
463
|
+
Agent 进程的环境是会话的环境再加插件进程的那组变量(资源的记录命令与 act 命令、放在会话 `PATH` 上的命令也一样;继承来的同名变量先去掉,一个插件的进程拿不到别的插件的):
|
|
470
464
|
`CODA_NODE`(Coda 后端自己的 Node,插件自带的入口用它运行,不在 Agent 的 `PATH` 上)、`CODA_PLUGIN_PATH`(插件目录,从仓库装的是它钉住的版本目录)、
|
|
471
465
|
`CODA_PLUGIN_STATE`(插件在这台机器上的状态目录,跨会话、跨版本保留)、`CODA_PLUGIN_SETTINGS`(插件设置的 JSON)、
|
|
472
466
|
`CODA_PLUGIN_EXTENSIONS`(别的插件接在它扩展点上的东西,没有就不设)、`CODA_PLUGIN_DEPENDENCIES`(它依赖的插件的目录,没有就不设)、
|
|
@@ -487,28 +481,33 @@ Agent 进程的环境是会话的环境再加插件进程的那组变量(资
|
|
|
487
481
|
- Coda 关会话是对 Agent 的进程组发 SIGTERM,0.8 秒后 SIGKILL:收到 SIGTERM 要尽快退出。
|
|
488
482
|
- 一轮之外的审批与提问 Coda 一律拒绝,除非正有活动在 `handling`(那是一轮自主轮次)。
|
|
489
483
|
|
|
490
|
-
**资源**(`
|
|
491
|
-
`
|
|
484
|
+
**资源**(`coda/resource@1`,例子见 `templates/resource`):插件写资源记录,资源页只读记录、调操作。清单里两处:
|
|
485
|
+
`contributes.records` 里 `{ "kind": "coda/resource@1", "command": "scripts/resource.mjs" }`(可选 `every`,不短于 `PT1M`,按周期重跑),
|
|
486
|
+
`contributes.protocolImplementations` 里 `{ "kind": "coda/resource@1", "commands": { "act": "scripts/act.mjs" } }`(`act`、`sign-in`、`install` 有哪个写哪个)。
|
|
487
|
+
`contributes.resources`、`contributes.panels` 已退役:清单里还写着的插件,Coda 判「需要更新」,检查报 `manifest.retired`。
|
|
488
|
+
|
|
489
|
+
- **记录命令**:Coda 以插件身份在插件目录里运行它(`{}` 在标准输入,`CODA_RECORD_KIND`,30 秒),标准输出是这个插件在这台机器上这一类的整组记录
|
|
490
|
+
`[{ key, spec }]`,每条不超过 64 KiB,key 不重复;`spec.type` 等于 `key`,`spec.title`(类型名,如「CPU」「Claude」:资源页上只写它,不写插件)与 `spec.resources`,至多 50 个资源。
|
|
491
|
+
命令失败(非零退出,原因写在标准错误的最后一行)时 Coda 保留上一份记录,资源页写「更新失败:原因」。
|
|
492
|
+
- **资源**:
|
|
492
493
|
|
|
493
494
|
| 字段 | 内容 |
|
|
494
495
|
| --- | --- |
|
|
495
496
|
| `name` | 可省:资源的名字(账号、磁盘、设备),一行不超过 80 字;类型只有一个资源时不写 |
|
|
496
497
|
| `identity` | 可省:它是哪个外部身份(如 `codex:<哈希>`):几台机器、几个插件说同一个身份时资源页只显示一行 |
|
|
497
|
-
| `values` |
|
|
498
|
+
| `values` | 必写,至多 8 个读数,每个可选 `label`(只有一个读数时不写)、`value`、`fraction`(0–1,**还剩多少**,不知道就不写)、`time`(ISO 8601,如额度何时恢复),`value` 与 `fraction` 至少有一个 |
|
|
498
499
|
| `error` | 可省:哪里不对,一行不超过 80 字 |
|
|
499
|
-
| `
|
|
500
|
+
| `buttons` | 必写,至多 8 个按钮,每个 `label` 和 `action`(调 `act` 操作)、`view`(插件的视图)或 `url`(`https://` 网页)之一,可选 `args`(序列化后不超过 4096 字节)、`disabled`、`confirm` |
|
|
500
501
|
|
|
501
502
|
`name` 与 `values` 至少有一个。没有副标题、说明行或整段文字:资源页上只有类型名、名字、读数与按钮,要说明的写进插件自己的文档或视图。
|
|
502
|
-
|
|
503
|
-
命令的环境是后端的环境(不带会话 ID)加上插件进程的那组变量(同上),`PATH` 最前面是 Coda 后端的 `node`;`CODA_GROUPS_STATE`
|
|
504
|
-
(`{now, groups}`);动作另有 `CODA_PANEL_ARGS`(按钮的 `args`)。
|
|
505
|
-
动作至多跑 10 分钟,成功后 Coda 立即重读这个类型。之前的写法 `contributes.panels`(`{ "items": [...] }`,卡片与说明行)Coda 仍读,当作资源显示、说明文字丢掉;新插件写 `resources`。
|
|
503
|
+
- **`act` 命令**:点按钮(并确认)后 Coda 运行它,`{ action, args }` 在标准输入里,至多 10 分钟;成功就在标准输出写 `{}`,失败退出 1、原因写在标准错误的最后一行;不认识的动作要让调用失败。
|
|
504
|
+
- 命令的环境是后端的环境(不带会话 ID)加上插件进程的那组变量(同上),`PATH` 最前面是 Coda 后端的 `node`;`CODA_GROUPS_STATE` 是这一刻这个后端各并发组的占用与排队(`{now, groups}`)。
|
|
506
505
|
|
|
507
506
|
## npm 发布
|
|
508
507
|
|
|
509
508
|
仓库根的 `@coda-console/plugin-check` 与 `plugins/*` 各自发布为公开 npm 包;包名带 scope,插件 ID 单独写在清单的 `id`。
|
|
510
509
|
`repository.directory` 指向插件所在目录。Coda 必须先支持清单的 `id`,才能从改名后的仓库或 npm 读取这些插件。
|
|
511
|
-
插件在仓库里的锁文件仍供 Git 来源安装与本仓库测试使用;npm 包不带 `package-lock.json`,从 npm
|
|
510
|
+
插件在仓库里的锁文件仍供 Git 来源安装与本仓库测试使用;npm 包不带 `package-lock.json`,从 npm 安装时按依赖声明解析。
|
|
512
511
|
|
|
513
512
|
`.github/workflows/publish.yml` 在合入 main 或手动发起时检查测试、清单与 npm 包内容,然后逐包发布 npm 上尚不存在的版本。
|
|
514
513
|
只有发布步骤有 `id-token: write`,由 GitHub 托管运行机通过 npm Trusted Publishing 鉴权并生成 provenance,不配置 npm 写令牌。
|
|
@@ -531,7 +530,7 @@ npm 包设置里的 Publishing access 保持 npm 的默认设置,不另行收
|
|
|
531
530
|
|
|
532
531
|
## 契约检查
|
|
533
532
|
|
|
534
|
-
扮演 Coda 去读一个插件目录:清单对 Coda 的类型 schema 校验,流程按 Coda 的流程方言读,Agent 照 Coda 的样子启动、说 Coda
|
|
533
|
+
扮演 Coda 去读一个插件目录:清单对 Coda 的类型 schema 校验,流程按 Coda 的流程方言读,Agent 照 Coda 的样子启动、说 Coda 说的话,写资源记录的插件,它的记录命令照宿主的样子跑一次,输出照协议校验。
|
|
535
534
|
插件写的合乎它用到的类型就对:清单的通用键只在协议包 `@coda-console/protocol`([coda-console/coda-protocol](https://github.com/coda-console/coda-protocol))的 schema 里,
|
|
536
535
|
`agents`、`skills`、`mcpServers` 等业务键由 Coda 里读它的一方登记成贡献点(schema 与读法,`check/coda/application/contributions.mjs` 先于读清单加载),都由 Coda 自己用的同一个校验器判,
|
|
537
536
|
检查包不另写规则。`check/coda/` 是 Coda 文件的原样副本(见[契约副本](#契约副本)),检查包手写的只有怎样扮演 Coda、怎样判。
|
|
@@ -545,13 +544,21 @@ node bin/check.mjs <插件目录> [--agent <id>] [--manifest] [--live] [--prompt
|
|
|
545
544
|
npx github:coda-console/coda-plugins#<提交> <插件目录>
|
|
546
545
|
```
|
|
547
546
|
|
|
548
|
-
插件自己的测试用检查包的出口:`@coda-console/plugin-check/test-host`(`createTestHost`,Coda 自己的 `coda`、`ctx`
|
|
547
|
+
插件自己的测试用检查包的出口:`@coda-console/plugin-check/test-host`(`createTestHost`,Coda 自己的 `coda`、`ctx` 构造)、`@coda-console/plugin-check/resources`(`resourceRecords`、`resourceRecordsProblem`,见下)与 `@coda-console/plugin-check/types`(类型),不必直接依赖协议包。
|
|
548
|
+
|
|
549
|
+
写 `coda/resource@1` 记录的插件(`contributes.records` 里有这一种)握手一级还会照宿主的样子跑一次它的记录命令(插件目录里、`{}` 在标准输入、`CODA_RECORD_KIND`、30 秒),
|
|
550
|
+
输出照协议的 schema 与宿主的上限校验:是 `[{ key, spec }]`、key 不重复、`spec.type` 等于 `key`、每条不超过 64 KiB、按钮的 `args` 序列化后不超过 4096 字节;规则 `resource.read`、`resource.output`。
|
|
551
|
+
记录里的动作(`act`、`sign-in`、`install`)不运行。插件自己的测试从 `@coda-console/plugin-check/resources` 导入(不要按文件路径导 `check/resources.mjs`):
|
|
552
|
+
`await resourceRecords(插件目录, { env })` 跑清单里 `coda/resource@1` 的记录命令,返回它打印的记录,不合则抛出原因(`env` 是测试给的进程环境,不给就用本进程的,`CODA_PLUGIN_PATH` 为插件目录);
|
|
553
|
+
`resourceRecordsProblem(输出)` 判手头已有的输出,返回 `null` 或哪里不对。
|
|
554
|
+
记录命令读不到数据时的规则:Coda 在命令失败(非零退出)时保留上一份记录、资源页显示「更新失败:原因」,所以只有「重新登录才能恢复」的错才打印带 `error` 和 `signIn` 的记录(凭据缺失、过期、无效,认证文件读不了或内容坏了;有登录却没有 CLI 也算,登录入口会装它);没登录、没账号不是错,照常打印有效记录、带 `signIn`;其余读失败(网络、超时、5xx、响应读不懂、本地登记损坏、查询失败)一律以非零退出,原因写在标准错误的最后一行,不要打印一条只有错误的记录去顶掉上一份好读数。
|
|
555
|
+
实现了 `coda/resource@1` 又带模块(`main`)的插件,模块一级不要求登记 `act`、`sign-in`、`install` 里清单没写命令的操作:这三个操作插件有哪个写哪个。
|
|
549
556
|
|
|
550
557
|
| 级 | 要不要登录 | 查什么 |
|
|
551
558
|
| --- | --- | --- |
|
|
552
|
-
| 清单(总是) | 不要 | `package.json` 的通用键对协议 schema 校验(`manifestProblem`),再照 Coda 读成插件(`readPlugin`:登记的贡献点各按自己的 schema 查、读,ID、设置名在 ID 之下);其余写给别的插件扩展点的键,要有 Coda
|
|
559
|
+
| 清单(总是) | 不要 | `package.json` 的通用键对协议 schema 校验(`manifestProblem`),再照 Coda 读成插件(`readPlugin`:登记的贡献点各按自己的 schema 查、读,ID、设置名在 ID 之下);其余写给别的插件扩展点的键,要有 Coda 自带的或旁边依赖的插件声明这个类型。清单还写着退役的 `contributes.resources`、`contributes.panels` 的,照 Coda 的判断(`ownIncompatibility`)算失败(`manifest.retired`)。`.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
560
|
| 模块(有 `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` 调非只读操作) |
|
|
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
|
|
561
|
+
| 握手(默认) | 不要 | `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/resource@1` 记录的,记录命令跑一次(30 秒),输出照协议的 schema 与宿主的上限校验 |
|
|
555
562
|
| 一轮(`--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` |
|
|
556
563
|
|
|
557
564
|
**取消后的 `stopReason` 怎么判**:检查发 `session/cancel` 时紧跟一个只会得到 -32601 的探测请求(`_codaCheck/barrier`)。Agent 按顺序读,
|
|
@@ -560,7 +567,7 @@ npx github:coda-console/coda-plugins#<提交> <插件目录>
|
|
|
560
567
|
答复先于读到取消写出(取消送到前这一轮已经结束),或读到取消时已经做完、随即答复的(如 Codex 做完后等标题时被取消),只记一条说明。
|
|
561
568
|
|
|
562
569
|
`--manifest` 只查清单(什么也不运行);`--agent <id>` 只查一个 Agent。退出码:0 通过,1 有失败,2 用法不对。
|
|
563
|
-
|
|
570
|
+
资源的 `act`、`sign-in`、`install` 命令与插件的设置动作(`contributes.setup`)不运行(可能改动东西、装软件);Coda 自己的 MCP 服务器不给(`mcpServers` 为空)。
|
|
564
571
|
检查给的会话指令不是 Coda 的全文,是一段替身加一句检查词。
|
|
565
572
|
|
|
566
573
|
在自己插件仓库的 CI 里:
|
|
@@ -573,7 +580,7 @@ npx github:coda-console/coda-plugins#<提交> <插件目录>
|
|
|
573
580
|
|
|
574
581
|
## 契约副本
|
|
575
582
|
|
|
576
|
-
Coda
|
|
583
|
+
Coda 主仓库不公开。它的插件规则(读清单、插件进程的环境、ACP 与 `_coda/wait` 的约定等,按 Coda `backend/src/` 下的路径放在 `check/coda/`)、
|
|
577
584
|
它自带的插件(`check/coda/builtin.json`)都是 Coda 的原样副本,由 Coda 的部署流程 `sync-plugin-check`
|
|
578
585
|
(脚本 `scripts/plugin-contract.mjs`)同步:它在分支 `sync/coda` 上给这里开 PR。**不要手改**;规则要改先改 Coda。
|
|
579
586
|
`check/coda/contract.json` 记着同步自哪个提交、每个文件的 sha256 和副本用到的包的版本,CI 用它核对:
|
package/bin/check.mjs
CHANGED
|
@@ -15,11 +15,11 @@ const USAGE = `用法:coda-plugin-check <插件目录> [--agent <id>] [--manif
|
|
|
15
15
|
|
|
16
16
|
清单(总是查) package.json 能不能被 Coda 读懂,从仓库安装的限制(带 npm 依赖要有 package-lock.json);engines.coda 够不够用到的各项(算出该写几);列出用到的试行面
|
|
17
17
|
模块(有 main) 用 Coda 自己的 coda(测试宿主)加载 main、调 activate(10 秒内要完成);模块登记的操作与清单的 protocolImplementations 两个方向对一遍;coda.on 只能订自己事件组里的事件
|
|
18
|
-
握手(默认查) 照 Coda 的样子启动每个 Agent,发 initialize、session/new(声明了的带 systemPrompt,没声明的在第一轮送入指令);SIGTERM 后 5
|
|
18
|
+
握手(默认查) 照 Coda 的样子启动每个 Agent,发 initialize、session/new(声明了的带 systemPrompt,没声明的在第一轮送入指令);SIGTERM 后 5 秒内要退出(关标准输入后不退出只提醒);跑一次资源记录命令,核对输出合 coda/resource@1
|
|
19
19
|
一轮(--live) 每个 Agent 先问会话指令里的检查词,再发一轮提示词(默认「只回复 ok」)、再发一轮并取消(读到取消后要回 cancelled)、核对 _coda/wait;
|
|
20
20
|
声明插话的,一轮结束后与一轮进行中各插话一次;声明 loadSession 的再开进程 session/load,并在新进程里再跑一轮
|
|
21
21
|
|
|
22
|
-
--agent <id> 只查这一个 Agent
|
|
22
|
+
--agent <id> 只查这一个 Agent(资源记录不读)
|
|
23
23
|
--manifest 只查清单,什么也不运行
|
|
24
24
|
--live 查一轮:会真的发提示词,可能要登录、花额度
|
|
25
25
|
--prompt "…" 一轮用的提示词
|
|
@@ -45,7 +45,7 @@ const { values, positionals } = options;
|
|
|
45
45
|
if (values.help) { console.log(USAGE); process.exit(0); }
|
|
46
46
|
if (positionals.length !== 1 || (values.manifest && values.live)) { console.error(USAGE); process.exit(2); }
|
|
47
47
|
|
|
48
|
-
// Detached agents and
|
|
48
|
+
// Detached agents and record commands, and temporary directories, go with the checker (check/leftovers.mjs).
|
|
49
49
|
for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => process.exit(130));
|
|
50
50
|
const dir = resolve(positionals[0]);
|
|
51
51
|
const { report, plugin } = await checkPlugin(dir, { agent: values.agent ?? null, manifestOnly: !!values.manifest, live: !!values.live, prompt: values.prompt });
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
// (a notice: an event it subscribes to, adapters/plugin-events.mjs), and `output`, `exited`
|
|
13
13
|
// of a process it started (adapters/process-relay.mjs). To it: `post { instance, message }`, `change { instance,
|
|
14
14
|
// collection, type, id, object }`, `unwatch { watch }`, `cancel { id }` of a `query` or a `question`, `progress { run,
|
|
15
|
-
// value }` of a `run`, `drained`, `kill` of a process, and the requests `
|
|
15
|
+
// value }` of a `run`, `drained`, `kill` of a process, and the requests `settings`
|
|
16
16
|
// (the plugin's own, as they are now), `watch { collection, selector }`, `tell { session, text }`, `part { part, method,
|
|
17
17
|
// args }`, `provider { method, args }`, `serviceRegister { id, port, secret }`, `serviceUnregister { id }`, `query { record,
|
|
18
18
|
// operation, input, timeout, deadline }`, `emit { name, data, subject, project }`, `call { record, operation, input, id, timeout, deadline, under, progress }`, `spawn { under, process, command, args, cwd, env, name }`, each with the
|
|
@@ -198,14 +198,13 @@ export function pluginModules({ send }) {
|
|
|
198
198
|
return entry.value;
|
|
199
199
|
};
|
|
200
200
|
|
|
201
|
-
// What a plugin's module is given: this plugin's own
|
|
201
|
+
// What a plugin's module is given: this plugin's own; and the parts
|
|
202
202
|
// others provide, each asking the backend under its name. `token`: this plugin's for this host process, brought with
|
|
203
203
|
// every request it asks (`asks`).
|
|
204
204
|
function codaFor(plugin, provided, token) {
|
|
205
205
|
const views = new Map(), protocols = new Map(), operations = new Map();
|
|
206
206
|
const asks = (method, params, signal = null, progress = null) => ask(method, { ...params, token }, signal, progress);
|
|
207
207
|
const services = pluginServices(asks);
|
|
208
|
-
const environment = (project = null, options = {}) => asks('environment', { of: options?.plugin ?? null, project });
|
|
209
208
|
// The listeners of `settings.onChange`: this plugin's own settings only, told as they are written.
|
|
210
209
|
const settingsChanges = new Set();
|
|
211
210
|
// The events it publishes and those it subscribes to (adapters/plugin-events.mjs).
|
|
@@ -277,10 +276,6 @@ export function pluginModules({ send }) {
|
|
|
277
276
|
if (!response.ok) throw new Error(value?.error?.message ?? `Coda 回答 ${response.status}`);
|
|
278
277
|
return value;
|
|
279
278
|
},
|
|
280
|
-
// What Coda gives every process of the plugin's (docs/plugins.md「插件进程的环境」), for one the module starts itself
|
|
281
|
-
// (Node's child_process, as a VS Code extension starts its language server); `{ plugin }`, another installed plugin's,
|
|
282
|
-
// for a command of its the module runs.
|
|
283
|
-
environment,
|
|
284
279
|
// This plugin's own settings (docs/plugins.md「设置」): as they are now, asked of the backend each time, and told to
|
|
285
280
|
// `onChange` as they are written, while the module runs. Secrets are not among them.
|
|
286
281
|
settings: Object.freeze({
|
|
@@ -297,8 +297,6 @@ export interface Coda {
|
|
|
297
297
|
tell(session: string, text: string): Promise<{ told: boolean }>;
|
|
298
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
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
300
|
/** Trial. Runs an installed plugin's environment setup again, asked as this plugin; the test host's fails (`unsupported`). */
|
|
303
301
|
pluginSetup: Readonly<{ retry(plugin: string): Promise<Json> }>;
|
|
304
302
|
}
|
|
@@ -291,7 +291,6 @@
|
|
|
291
291
|
3 module coda.call
|
|
292
292
|
3 module coda.delete
|
|
293
293
|
3 module coda.emit
|
|
294
|
-
3 module coda.environment
|
|
295
294
|
3 module coda.error
|
|
296
295
|
3 module coda.get
|
|
297
296
|
3 module coda.handle
|
|
@@ -346,4 +345,11 @@
|
|
|
346
345
|
5 coda/accord@1 read
|
|
347
346
|
5 coda/accord@1 read operation records
|
|
348
347
|
5 coda/accord@1 read records
|
|
349
|
-
|
|
348
|
+
6 coda/resource@1
|
|
349
|
+
6 coda/resource@1 act
|
|
350
|
+
6 coda/resource@1 act operation act
|
|
351
|
+
6 coda/resource@1 act operation install
|
|
352
|
+
6 coda/resource@1 act operation sign-in
|
|
353
|
+
6 coda/resource@1 read
|
|
354
|
+
6 coda/resource@1 read records
|
|
355
|
+
level 6
|