@capyclaw/skills-service 0.1.3 → 0.2.2
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 +7 -7
- package/node_modules/@capyclaw/foundation/README.md +51 -0
- package/node_modules/@capyclaw/foundation/abi/bridge.mjs +86 -0
- package/node_modules/@capyclaw/foundation/abi/errors.mjs +63 -0
- package/node_modules/@capyclaw/foundation/abi/index.mjs +35 -0
- package/node_modules/@capyclaw/foundation/abi/kinds.mjs +271 -0
- package/node_modules/@capyclaw/foundation/abi/loader.mjs +345 -0
- package/node_modules/@capyclaw/foundation/abi/schema.mjs +98 -0
- package/node_modules/@capyclaw/foundation/abi/spec.mjs +255 -0
- package/node_modules/@capyclaw/foundation/abi/validate.mjs +24 -0
- package/node_modules/@capyclaw/foundation/abi/version.mjs +82 -0
- package/node_modules/@capyclaw/foundation/cordis.patch.yml +5 -0
- package/node_modules/@capyclaw/foundation/kit/index.mjs +6 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/client-panel.mjs +98 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/host-event.mjs +35 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/http-router.mjs +69 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/lifecycle-hook.mjs +55 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/own-server.mjs +113 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/raw.mjs +68 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/runtime-driver.mjs +113 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/service-provider.mjs +77 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/skill-provider.mjs +56 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/tool-provider.mjs +50 -0
- package/node_modules/@capyclaw/foundation/lib/adapters/ui-panel.mjs +64 -0
- package/node_modules/@capyclaw/foundation/lib/ctx-service.mjs +42 -0
- package/node_modules/@capyclaw/foundation/lib/host/caps.mjs +34 -0
- package/node_modules/@capyclaw/foundation/lib/host/contract.mjs +85 -0
- package/node_modules/@capyclaw/foundation/lib/host/dsh.mjs +50 -0
- package/node_modules/@capyclaw/foundation/lib/host/memory.mjs +160 -0
- package/node_modules/@capyclaw/foundation/lib/host.mjs +23 -0
- package/node_modules/@capyclaw/foundation/lib/kernel.mjs +185 -0
- package/node_modules/@capyclaw/foundation/lib/skill/scan.mjs +87 -0
- package/node_modules/@capyclaw/foundation/lib/subsystems/events.mjs +60 -0
- package/node_modules/@capyclaw/foundation/lib/subsystems/log.mjs +51 -0
- package/node_modules/@capyclaw/foundation/lib/subsystems/net.mjs +188 -0
- package/node_modules/@capyclaw/foundation/package.json +53 -0
- package/node_modules/@capyclaw/foundation/runtime/index.mjs +20 -0
- package/node_modules/@capyclaw/plugin-kit/INTEGRATION.md +100 -0
- package/node_modules/@capyclaw/plugin-kit/README.md +70 -0
- package/node_modules/@capyclaw/plugin-kit/bin/sync.mjs +103 -0
- package/node_modules/@capyclaw/plugin-kit/package.json +69 -0
- package/node_modules/@capyclaw/plugin-kit/src/cli.mjs +56 -0
- package/node_modules/@capyclaw/plugin-kit/src/config.mjs +142 -0
- package/node_modules/@capyclaw/plugin-kit/src/editor/heartbeat-worker.js +129 -0
- package/node_modules/@capyclaw/plugin-kit/src/editor/lease.mjs +139 -0
- package/node_modules/@capyclaw/plugin-kit/src/editor/shadow.mjs +219 -0
- package/node_modules/@capyclaw/plugin-kit/src/editor/transport.js +13 -0
- package/node_modules/@capyclaw/plugin-kit/src/index.mjs +13 -0
- package/node_modules/@capyclaw/plugin-kit/src/pack.mjs +230 -0
- package/node_modules/@capyclaw/plugin-kit/src/runtime/context.mjs +128 -0
- package/node_modules/@capyclaw/plugin-kit/src/self-contained.mjs +307 -0
- package/node_modules/@capyclaw/plugin-kit/src/service/api.mjs +45 -0
- package/node_modules/@capyclaw/plugin-kit/src/service/http.mjs +113 -0
- package/node_modules/@capyclaw/plugin-kit/src/service/mcp-http.mjs +143 -0
- package/node_modules/@capyclaw/plugin-kit/src/service/server.mjs +131 -0
- package/node_modules/@capyclaw/plugin-kit/src/skills/provider.mjs +82 -0
- package/node_modules/@capyclaw/plugin-kit/src/store/blob-store.mjs +109 -0
- package/node_modules/@capyclaw/plugin-kit/src/store/content-store.mjs +17 -0
- package/node_modules/@capyclaw/plugin-kit/src/store/journal-store.mjs +89 -0
- package/node_modules/@capyclaw/plugin-kit/src/tools/result.mjs +41 -0
- package/node_modules/@capyclaw/plugin-kit/src/tools/validate.mjs +150 -0
- package/node_modules/@capyclaw/plugin-kit/src/tuning.mjs +82 -0
- package/node_modules/@capyclaw/plugin-kit/src/util/fs-lock.mjs +132 -0
- package/node_modules/@capyclaw/plugin-kit/src/util/http.mjs +130 -0
- package/node_modules/@capyclaw/plugin-kit/src/workspace/manager.mjs +656 -0
- package/node_modules/@capyclaw/plugin-kit/src/zip.mjs +181 -0
- package/package.json +18 -2
- package/server.mjs +237 -201
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# capyclaw-skills-service
|
|
2
2
|
|
|
3
3
|
DSH 独立技能服务(服务解耦标准形态)。把原「`ctx.skills` 进程内注册表」的
|
|
4
4
|
技能内容(SKILL.md)搬出 dsh 进程,作为独立端口服务:
|
|
@@ -11,21 +11,21 @@ GET /skills/:name 单技能正文(原 provider.get 形状)
|
|
|
11
11
|
|
|
12
12
|
## 技能数据源
|
|
13
13
|
|
|
14
|
-
自动扫描两类布局(都找 `
|
|
14
|
+
自动扫描两类布局(都找 `capyclaw-ppt-skill-*` 目录里的 `lib/index.mjs`):
|
|
15
15
|
|
|
16
|
-
- dev 树:`../plugin/
|
|
17
|
-
- 套件安装态:本目录同级(`node_modules/
|
|
16
|
+
- dev 树:`../plugin/capyclaw-ppt-skill-*`
|
|
17
|
+
- 套件安装态:本目录同级(`node_modules/capyclaw-ppt-skill-*`)
|
|
18
18
|
|
|
19
19
|
可用 `--providers <dir>[[;|,]dir…]` 显式指定。
|
|
20
20
|
|
|
21
21
|
## 由谁拉起
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
23
|
+
`@capyclaw/service-broker` 按清单以独立进程拉起(套件捆绑布局的清单见
|
|
24
|
+
@capyclaw/ppt-suite 包根 `services.json`,端口 `"auto"` 由 broker 现分配)。dsh 侧经 broker 的
|
|
25
25
|
skills 瘦客户端(`ctx.skills` 兼容形状)访问本服务。
|
|
26
26
|
|
|
27
27
|
## 独立运行
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
node server.mjs [--port
|
|
30
|
+
node server.mjs [--port 0] [--providers dir1,dir2] # 0 = OS 随机分配
|
|
31
31
|
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# @capyclaw/foundation
|
|
2
|
+
|
|
3
|
+
dsh 插件基石层:接口 ABI、插件加载器与内核服务 `ctx.os`。
|
|
4
|
+
|
|
5
|
+
应用插件不再写 `inject` / `apply` / provider 装配,只声明「我实现了哪个接口」:
|
|
6
|
+
|
|
7
|
+
```js
|
|
8
|
+
import { createPlugin, skillProvider } from '@capyclaw/foundation/abi'
|
|
9
|
+
|
|
10
|
+
export const { name, inject, apply } = createPlugin({
|
|
11
|
+
name: 'canvas',
|
|
12
|
+
requires: ['canvas.runtime@^1'],
|
|
13
|
+
implements: [skillProvider({ skill: './skills/canvas' })],
|
|
14
|
+
}, import.meta.url)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 四个入口
|
|
18
|
+
|
|
19
|
+
| 入口 | 内容 | 谁用 |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `.` | Cordis 插件,产出 `ctx.os` | dsh profile |
|
|
22
|
+
| `./abi` | 描述符构建器、加载器、错误码、版本工具 | 应用插件 |
|
|
23
|
+
| `./kit` | plugin-kit 兼容导出,包含 Node/dsh 耦合,非纯函数库 | 兼容调用方 |
|
|
24
|
+
| `./runtime` | `createKernel` 等宿主 API | dsh 之外的宿主(独立技能服务、测试夹具) |
|
|
25
|
+
|
|
26
|
+
## 状态
|
|
27
|
+
|
|
28
|
+
- 包清单当前为 `0.1.6`;0.1.6 修的是「关掉插件再启用撞 E_DUP_PLUGIN」(disposer 未登记 + 失败
|
|
29
|
+
记录占名),详见下面的「生命周期」。
|
|
30
|
+
- 分层:应用插件 → ABI → 内核 → Host 适配器 → 本地 Node.js agent 运行时。
|
|
31
|
+
dsh 服务访问位于 Host 适配层;memory 只是参考实现,不证明第二个真实 agent 兼容。
|
|
32
|
+
HTTP/资源/进程仍有本地 Node 协议约束,详见 `docs/HOST-ADAPTER.md`。
|
|
33
|
+
- ABI v1,六个标准接口 + `host-event@1` + `client-panel@1` + `service-provider@1` +
|
|
34
|
+
`own-server@1` + 可执行 `raw@1`;基建插件使用 `defineDriver` 驱动入口。
|
|
35
|
+
- 能力表按 `ctx` 实际服务探测(见 `lib/kernel.mjs` 的 `detectCapabilities`),不做空头承诺。
|
|
36
|
+
- 当前仓库:27 个插件走标准接口,`raw@1` 当前为空,6 个基建插件走
|
|
37
|
+
`defineDriver` 驱动层;`meta/foundation.allowlist.json` 的模糊豁免为 0。
|
|
38
|
+
详见 `docs/POLICY.md` 与 `docs/spec/plugin-abi.md`。
|
|
39
|
+
|
|
40
|
+
设计规范见 `docs/spec/plugin-abi.md`,强制规则见 `docs/POLICY.md`。
|
|
41
|
+
|
|
42
|
+
## 生命周期(0.1.6 起)
|
|
43
|
+
|
|
44
|
+
`createPlugin().apply` 会把 `os.mount()` 的 disposer 通过 `ctx.effect(() => () => dispose())`
|
|
45
|
+
登记到本次激活的 ctx 上——**不能只靠 apply 的返回值**:Cordis 只认 `ctx.effect` 回调返回的
|
|
46
|
+
disposer,返回值不可靠。漏登记时,关掉插件后内核里的记录不会摘除,再次启用就会撞
|
|
47
|
+
`E_DUP_PLUGIN: 插件 xxx 已挂载`。
|
|
48
|
+
|
|
49
|
+
加载器侧另有两条兜底:`mount()` 遇到 `disposed` / `failed` 的旧记录会先摘掉并尽力回收;
|
|
50
|
+
`start` 失败清理完成后立即让出插件名。两者共同保证「关掉 → 再启用」可重复无数次。
|
|
51
|
+
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 桥(editor bridge)与文档模型的标准声明。
|
|
3
|
+
*
|
|
4
|
+
* 这一层只放「协议常量 + 声明校验」,不放运行时:
|
|
5
|
+
* - 常量:协议版本、模型版本、能力名(suite 清单与 healthz 都用它)
|
|
6
|
+
* - declareBridge():把工作台的声明冻结成标准形状
|
|
7
|
+
* - assertBridgeRuntime():启动/巡检时把「声明」与「运行时实际上报」对齐
|
|
8
|
+
*
|
|
9
|
+
* 运行时(relay / 队列 / 租约)仍在 @capyclaw/document-workbench + service-host,
|
|
10
|
+
* 不进 ABI 层:foundation 是所有插件的地基,不该背 HTTP/store 依赖。
|
|
11
|
+
*
|
|
12
|
+
* 能力名(与 suite 清单的 requires/provides.capabilities 对应):
|
|
13
|
+
* editor.bridge —— 插件提供一个编辑器权威桥(/healthz + /status + /watch + /ack)
|
|
14
|
+
* doc.model —— 插件提供文档模型(稳定 ID / 清单 / 定位 / 编辑计划 / 校验)
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** 桥协议版本:端点集合与状态机语义的主版本。不兼容变更才升 major。 */
|
|
18
|
+
export const BRIDGE_PROTOCOL_VERSION = '1.0.0'
|
|
19
|
+
|
|
20
|
+
/** 文档模型版本:清单字段、定位器语义、编辑 op 的主版本。 */
|
|
21
|
+
export const DOC_MODEL_VERSION = '1.0.0'
|
|
22
|
+
|
|
23
|
+
export const BRIDGE_CAPABILITY = 'editor.bridge'
|
|
24
|
+
export const DOC_MODEL_CAPABILITY = 'doc.model'
|
|
25
|
+
|
|
26
|
+
/** healthz 里桥声明的字段名(避免与既有的 bridge: '<name>' 字符串冲突)。 */
|
|
27
|
+
export const BRIDGE_INFO_FIELD = 'bridgeInfo'
|
|
28
|
+
|
|
29
|
+
const ID_RE = /^[a-z0-9][a-z0-9-]*$/
|
|
30
|
+
const VERSION_RE = /^\d+\.\d+\.\d+$/
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* 校验并冻结一份桥声明。
|
|
34
|
+
* @param {{ id: string, protocol?: string, model?: string|null, editor?: 'required'|'optional' }} input
|
|
35
|
+
*/
|
|
36
|
+
export function declareBridge(input = {}) {
|
|
37
|
+
const { id, protocol = BRIDGE_PROTOCOL_VERSION, model = null, editor = 'required' } = input
|
|
38
|
+
const errors = []
|
|
39
|
+
if (typeof id !== 'string' || !ID_RE.test(id)) errors.push(`id 必须是 kebab-case:${id}`)
|
|
40
|
+
if (!VERSION_RE.test(protocol)) errors.push(`protocol 版本非法:${protocol}`)
|
|
41
|
+
if (model !== null && !VERSION_RE.test(model)) errors.push(`model 版本非法:${model}`)
|
|
42
|
+
if (editor !== 'required' && editor !== 'optional') errors.push(`editor 只能是 required/optional:${editor}`)
|
|
43
|
+
if (errors.length) throw new Error(`桥声明非法:${errors.join(';')}`)
|
|
44
|
+
return Object.freeze({ id, protocol, model, editor })
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** 桥声明 → suite 清单里的 provides.capabilities。 */
|
|
48
|
+
export function bridgeCapabilities(declaration) {
|
|
49
|
+
const decl = declaration && declaration.protocol ? declaration : declareBridge(declaration)
|
|
50
|
+
return Object.freeze({
|
|
51
|
+
[BRIDGE_CAPABILITY]: decl.protocol,
|
|
52
|
+
...(decl.model ? { [DOC_MODEL_CAPABILITY]: decl.model } : {}),
|
|
53
|
+
})
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** 桥声明 → suite 清单里工具面对运行时的 requires.capabilities(skill 包用)。 */
|
|
57
|
+
export function bridgeConsumerRequirements(ns, { needsModel = false } = {}) {
|
|
58
|
+
const out = { [`${ns}.runtime`]: `^${BRIDGE_PROTOCOL_VERSION}` }
|
|
59
|
+
if (needsModel) out[DOC_MODEL_CAPABILITY] = `^${DOC_MODEL_VERSION}`
|
|
60
|
+
return Object.freeze(out)
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* 声明与运行时对账:启动或巡检时调用。
|
|
65
|
+
*
|
|
66
|
+
* @param {object} declaration declareBridge 的结果(来自插件代码/清单)
|
|
67
|
+
* @param {object} runtime healthz 里的 bridgeInfo(实际运行值)
|
|
68
|
+
* @returns {{ ok: boolean, issues: string[] }}
|
|
69
|
+
*/
|
|
70
|
+
export function assertBridgeRuntime(declaration, runtime) {
|
|
71
|
+
const issues = []
|
|
72
|
+
const decl = declaration && declaration.id ? declaration : declareBridge(declaration || {})
|
|
73
|
+
if (!runtime || typeof runtime !== 'object') {
|
|
74
|
+
return { ok: false, issues: [`运行时没有上报 ${BRIDGE_INFO_FIELD}`] }
|
|
75
|
+
}
|
|
76
|
+
if (runtime.id !== decl.id) issues.push(`id 不一致:声明 ${decl.id} / 运行 ${runtime.id}`)
|
|
77
|
+
if (runtime.protocol !== decl.protocol) {
|
|
78
|
+
issues.push(`协议版本不一致:声明 ${decl.protocol} / 运行 ${runtime.protocol}`)
|
|
79
|
+
}
|
|
80
|
+
const declaredModel = decl.model || null
|
|
81
|
+
const runtimeModel = runtime.model || null
|
|
82
|
+
if (declaredModel !== runtimeModel) {
|
|
83
|
+
issues.push(`模型版本不一致:声明 ${declaredModel || '无'} / 运行 ${runtimeModel || '无'}`)
|
|
84
|
+
}
|
|
85
|
+
return { ok: issues.length === 0, issues }
|
|
86
|
+
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ABI 错误模型:稳定的错误码 + 结构化 detail。
|
|
3
|
+
*
|
|
4
|
+
* 约定:
|
|
5
|
+
* - 应用插件按 code 分支,不解析 message 文案;
|
|
6
|
+
* - message 面向人,detail 面向程序;
|
|
7
|
+
* - 所有加载期失败都必须是 AbiError,不允许裸 Error 穿透。
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/** 稳定错误码。新增只能追加,不得改语义。 */
|
|
11
|
+
export const ERROR_CODES = Object.freeze({
|
|
12
|
+
/** 插件入口形状不对:缺 name / 没有 implements / 导出了 apply 等。 */
|
|
13
|
+
E_PLUGIN_SHAPE: 'E_PLUGIN_SHAPE',
|
|
14
|
+
/** 插件声明的 ABI 主版本与内核不兼容。 */
|
|
15
|
+
E_ABI_MISMATCH: 'E_ABI_MISMATCH',
|
|
16
|
+
/** 描述符的 kind 不在内核认识的接口表里。 */
|
|
17
|
+
E_KIND_UNKNOWN: 'E_KIND_UNKNOWN',
|
|
18
|
+
/** 描述符字段不满足接口 schema。 */
|
|
19
|
+
E_SCHEMA: 'E_SCHEMA',
|
|
20
|
+
/** 内核没有提供该能力(通常是 os.* 子系统缺失)。 */
|
|
21
|
+
E_CAP_MISSING: 'E_CAP_MISSING',
|
|
22
|
+
/** 唯一性接口被第二个插件实现(例如同 id 的 runtime-driver)。 */
|
|
23
|
+
E_DUP_INTERFACE: 'E_DUP_INTERFACE',
|
|
24
|
+
/** 同名插件被重复挂载。 */
|
|
25
|
+
E_DUP_PLUGIN: 'E_DUP_PLUGIN',
|
|
26
|
+
/** 内核没有为这个 kind 注册适配器(接口定义存在但实现未就绪)。 */
|
|
27
|
+
E_KIND_UNAVAILABLE: 'E_KIND_UNAVAILABLE',
|
|
28
|
+
/** 适配器在编译期抛错。 */
|
|
29
|
+
E_ADAPTER_THREW: 'E_ADAPTER_THREW',
|
|
30
|
+
/** 插件入口没有拿到 baseUrl,相对路径无法解析。 */
|
|
31
|
+
E_BASE_URL_MISSING: 'E_BASE_URL_MISSING',
|
|
32
|
+
/** 运行时没有 ctx.os:foundation 未安装或未启用。 */
|
|
33
|
+
E_KERNEL_MISSING: 'E_KERNEL_MISSING',
|
|
34
|
+
E_KERNEL_CLOSED: 'E_KERNEL_CLOSED',
|
|
35
|
+
E_NOT_READY: 'E_NOT_READY',
|
|
36
|
+
E_CAP_RESERVED: 'E_CAP_RESERVED',
|
|
37
|
+
E_CAP_CONFLICT: 'E_CAP_CONFLICT',
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
export class AbiError extends Error {
|
|
41
|
+
/**
|
|
42
|
+
* @param {string} code ERROR_CODES 中的一项
|
|
43
|
+
* @param {string} message 面向人的说明
|
|
44
|
+
* @param {Record<string, unknown>} [detail] 面向程序的结构化信息
|
|
45
|
+
*/
|
|
46
|
+
constructor(code, message, detail = {}) {
|
|
47
|
+
super(`[${code}] ${message}`)
|
|
48
|
+
this.name = 'AbiError'
|
|
49
|
+
this.code = code
|
|
50
|
+
this.detail = detail
|
|
51
|
+
if (detail.cause instanceof Error) this.cause = detail.cause
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export function isAbiError(error) {
|
|
56
|
+
return error instanceof AbiError
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** 把任意异常归一成 AbiError(已归一的原样返回)。 */
|
|
60
|
+
export function toAbiError(error, code = ERROR_CODES.E_ADAPTER_THREW, detail = {}) {
|
|
61
|
+
if (error instanceof AbiError) return error
|
|
62
|
+
return new AbiError(code, error?.message || String(error), { ...detail, cause: error })
|
|
63
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** 接口 ABI 的唯一入口:应用插件只需要 import 这个模块。 */
|
|
2
|
+
export { ABI_MAJOR, INTERFACE_KINDS, INTERFACE_KIND_NAMES, getInterfaceKind } from './kinds.mjs'
|
|
3
|
+
export {
|
|
4
|
+
defineInterface,
|
|
5
|
+
definePlugin,
|
|
6
|
+
createPlugin,
|
|
7
|
+
skillProvider,
|
|
8
|
+
toolProvider,
|
|
9
|
+
runtimeDriver,
|
|
10
|
+
httpRouter,
|
|
11
|
+
uiPanel,
|
|
12
|
+
lifecycleHook,
|
|
13
|
+
hostEvent,
|
|
14
|
+
clientPanel,
|
|
15
|
+
ownServer,
|
|
16
|
+
serviceProvider,
|
|
17
|
+
defineDriver,
|
|
18
|
+
rawPlugin,
|
|
19
|
+
} from './spec.mjs'
|
|
20
|
+
export { createLoader } from './loader.mjs'
|
|
21
|
+
export {
|
|
22
|
+
BRIDGE_CAPABILITY,
|
|
23
|
+
BRIDGE_INFO_FIELD,
|
|
24
|
+
BRIDGE_PROTOCOL_VERSION,
|
|
25
|
+
DOC_MODEL_CAPABILITY,
|
|
26
|
+
DOC_MODEL_VERSION,
|
|
27
|
+
assertBridgeRuntime,
|
|
28
|
+
bridgeCapabilities,
|
|
29
|
+
bridgeConsumerRequirements,
|
|
30
|
+
declareBridge,
|
|
31
|
+
} from './bridge.mjs'
|
|
32
|
+
export { validateInterface } from './validate.mjs'
|
|
33
|
+
export { AbiError, ERROR_CODES, isAbiError, toAbiError } from './errors.mjs'
|
|
34
|
+
export { validateSchema } from './schema.mjs'
|
|
35
|
+
export { parseVersion, compareVersions, satisfies } from './version.mjs'
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 接口种类表:定义「插件可以是什么」。
|
|
3
|
+
*
|
|
4
|
+
* 一条记录 = 一种插件形状。应用插件不写装配代码,只产出这里的描述符;
|
|
5
|
+
* 生命周期、注册、健康检查、日志包裹由内核的适配器统一完成。
|
|
6
|
+
*
|
|
7
|
+
* 版本规则:
|
|
8
|
+
* - 主版本写在 kind 后缀里(`skill-provider@1`),主版本不同就是不同接口;
|
|
9
|
+
* - 次版本只做增量字段,内核按主版本注册适配器;
|
|
10
|
+
* - 破坏性变更 = 新 kind(@2)+ 旧 kind 至少并存一个大版本。
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const nonEmpty = { type: 'string', minLength: 1 }
|
|
14
|
+
const kebab = { type: 'string', pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
|
|
15
|
+
|
|
16
|
+
export const ABI_MAJOR = 1
|
|
17
|
+
|
|
18
|
+
export const INTERFACE_KINDS = Object.freeze({
|
|
19
|
+
'skill-provider@1': Object.freeze({
|
|
20
|
+
kind: 'skill-provider@1',
|
|
21
|
+
major: 1,
|
|
22
|
+
title: '技能提供者',
|
|
23
|
+
summary: '把一个 SKILL.md 目录注册进 dsh skills 服务,可选附带契约快照与契约注记。',
|
|
24
|
+
unique: false,
|
|
25
|
+
schema: Object.freeze({
|
|
26
|
+
type: 'object',
|
|
27
|
+
required: ['skill'],
|
|
28
|
+
additionalProperties: false,
|
|
29
|
+
properties: {
|
|
30
|
+
name: kebab,
|
|
31
|
+
skill: nonEmpty,
|
|
32
|
+
contract: nonEmpty,
|
|
33
|
+
rank: { type: 'number', min: 0, max: 1000 },
|
|
34
|
+
note: { type: 'function' },
|
|
35
|
+
},
|
|
36
|
+
}),
|
|
37
|
+
}),
|
|
38
|
+
|
|
39
|
+
'tool-provider@1': Object.freeze({
|
|
40
|
+
kind: 'tool-provider@1',
|
|
41
|
+
major: 1,
|
|
42
|
+
title: '工具提供者',
|
|
43
|
+
summary: '声明一组工具并注册到工具面(注册表 / MCP 壳 / 能力报告)。',
|
|
44
|
+
unique: false,
|
|
45
|
+
schema: Object.freeze({
|
|
46
|
+
type: 'object',
|
|
47
|
+
required: ['namespace', 'provide'],
|
|
48
|
+
additionalProperties: false,
|
|
49
|
+
properties: {
|
|
50
|
+
namespace: kebab,
|
|
51
|
+
prefixNamespace: { type: 'boolean' },
|
|
52
|
+
provide: { type: 'function' },
|
|
53
|
+
instructions: nonEmpty,
|
|
54
|
+
capabilities: { type: 'object' },
|
|
55
|
+
},
|
|
56
|
+
}),
|
|
57
|
+
}),
|
|
58
|
+
|
|
59
|
+
'runtime-driver@1': Object.freeze({
|
|
60
|
+
kind: 'runtime-driver@1',
|
|
61
|
+
major: 1,
|
|
62
|
+
title: '运行时驱动',
|
|
63
|
+
summary: '一个长驻进程的启动、就绪、健康与回收;端口由内核分配,应用不自己 spawn。',
|
|
64
|
+
unique: true,
|
|
65
|
+
uniqueBy: 'id',
|
|
66
|
+
schema: Object.freeze({
|
|
67
|
+
type: 'object',
|
|
68
|
+
required: ['id', 'entry'],
|
|
69
|
+
additionalProperties: false,
|
|
70
|
+
properties: {
|
|
71
|
+
id: kebab,
|
|
72
|
+
entry: nonEmpty,
|
|
73
|
+
when: { type: 'function' },
|
|
74
|
+
args: { type: 'array', items: { type: 'string' } },
|
|
75
|
+
port: { type: ['number', 'string', 'function'] },
|
|
76
|
+
portArg: nonEmpty,
|
|
77
|
+
dir: nonEmpty,
|
|
78
|
+
env: { type: 'function' },
|
|
79
|
+
health: {
|
|
80
|
+
type: 'object',
|
|
81
|
+
required: ['path'],
|
|
82
|
+
additionalProperties: false,
|
|
83
|
+
properties: {
|
|
84
|
+
path: nonEmpty,
|
|
85
|
+
expect: { type: 'object' },
|
|
86
|
+
timeoutMs: { type: 'number', min: 1 },
|
|
87
|
+
},
|
|
88
|
+
},
|
|
89
|
+
restart: {
|
|
90
|
+
type: 'object',
|
|
91
|
+
additionalProperties: false,
|
|
92
|
+
properties: {
|
|
93
|
+
max: { type: 'integer', min: 0 },
|
|
94
|
+
backoffMs: { type: 'number', min: 0 },
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
}),
|
|
99
|
+
}),
|
|
100
|
+
|
|
101
|
+
'http-router@1': Object.freeze({
|
|
102
|
+
kind: 'http-router@1',
|
|
103
|
+
major: 1,
|
|
104
|
+
title: '路由挂载者',
|
|
105
|
+
summary: '把一组 HTTP 路由挂到内核的共享宿主上,前缀冲突由内核检测。',
|
|
106
|
+
unique: false,
|
|
107
|
+
schema: Object.freeze({
|
|
108
|
+
type: 'object',
|
|
109
|
+
required: ['mount', 'routes'],
|
|
110
|
+
additionalProperties: false,
|
|
111
|
+
properties: {
|
|
112
|
+
mount: { type: 'string', pattern: '^/' },
|
|
113
|
+
routes: { type: 'function' },
|
|
114
|
+
host: { type: 'string', enum: ['shared', 'own'] },
|
|
115
|
+
},
|
|
116
|
+
}),
|
|
117
|
+
}),
|
|
118
|
+
|
|
119
|
+
'ui-panel@1': Object.freeze({
|
|
120
|
+
kind: 'ui-panel@1',
|
|
121
|
+
major: 1,
|
|
122
|
+
title: '界面面板',
|
|
123
|
+
summary: '把静态资源目录挂到挂载点,缓存头与 404 兜底由内核处理。',
|
|
124
|
+
unique: false,
|
|
125
|
+
schema: Object.freeze({
|
|
126
|
+
type: 'object',
|
|
127
|
+
required: ['mount', 'root'],
|
|
128
|
+
additionalProperties: false,
|
|
129
|
+
properties: {
|
|
130
|
+
mount: { type: 'string', pattern: '^/' },
|
|
131
|
+
root: nonEmpty,
|
|
132
|
+
index: nonEmpty,
|
|
133
|
+
cache: { type: 'string', enum: ['no-store', 'revalidate', 'immutable'] },
|
|
134
|
+
},
|
|
135
|
+
}),
|
|
136
|
+
}),
|
|
137
|
+
|
|
138
|
+
'lifecycle-hook@1': Object.freeze({
|
|
139
|
+
kind: 'lifecycle-hook@1',
|
|
140
|
+
major: 1,
|
|
141
|
+
title: '生命周期钩子',
|
|
142
|
+
summary: '在安装 / 启动 / 停止 / 升级四个时点插入行为,时序与幂等由内核保证。',
|
|
143
|
+
unique: false,
|
|
144
|
+
schema: Object.freeze({
|
|
145
|
+
type: 'object',
|
|
146
|
+
additionalProperties: false,
|
|
147
|
+
properties: {
|
|
148
|
+
onInstall: { type: 'function' },
|
|
149
|
+
onStart: { type: 'function' },
|
|
150
|
+
onStop: { type: 'function' },
|
|
151
|
+
onUpgrade: { type: 'function' },
|
|
152
|
+
},
|
|
153
|
+
}),
|
|
154
|
+
/** schema 表达不了「至少一个钩子」,用额外校验补。 */
|
|
155
|
+
extra(impl, errors) {
|
|
156
|
+
const hooks = ['onInstall', 'onStart', 'onStop', 'onUpgrade'].filter((key) => typeof impl[key] === 'function')
|
|
157
|
+
if (!hooks.length) errors.push('$ 至少需要实现一个钩子(onInstall/onStart/onStop/onUpgrade)')
|
|
158
|
+
},
|
|
159
|
+
}),
|
|
160
|
+
|
|
161
|
+
'host-event@1': Object.freeze({
|
|
162
|
+
kind: 'host-event@1',
|
|
163
|
+
major: 1,
|
|
164
|
+
title: '宿主事件订阅',
|
|
165
|
+
summary: '订阅宿主生命周期/界面注入事件;适配器负责在插件自己的 ctx 上注册与注销。',
|
|
166
|
+
unique: false,
|
|
167
|
+
schema: Object.freeze({
|
|
168
|
+
type: 'object',
|
|
169
|
+
required: ['event', 'handler'],
|
|
170
|
+
additionalProperties: false,
|
|
171
|
+
properties: {
|
|
172
|
+
event: nonEmpty,
|
|
173
|
+
handler: { type: 'function' },
|
|
174
|
+
},
|
|
175
|
+
}),
|
|
176
|
+
}),
|
|
177
|
+
|
|
178
|
+
'client-panel@1': Object.freeze({
|
|
179
|
+
kind: 'client-panel@1',
|
|
180
|
+
major: 1,
|
|
181
|
+
title: '客户端面板',
|
|
182
|
+
summary: '声明页面开机全局变量与可选静态目录;适配器负责 webserver/index-inject 注入与静态挂载。',
|
|
183
|
+
unique: false,
|
|
184
|
+
schema: Object.freeze({
|
|
185
|
+
type: 'object',
|
|
186
|
+
additionalProperties: false,
|
|
187
|
+
properties: {
|
|
188
|
+
mount: { type: 'string', pattern: '^/' },
|
|
189
|
+
root: nonEmpty,
|
|
190
|
+
index: nonEmpty,
|
|
191
|
+
prepare: { type: 'function' },
|
|
192
|
+
bootGlobals: { type: 'function' },
|
|
193
|
+
},
|
|
194
|
+
}),
|
|
195
|
+
extra(impl, errors) {
|
|
196
|
+
if (!impl.root && !impl.prepare && !impl.bootGlobals) {
|
|
197
|
+
errors.push('$ 至少需要 root / prepare / bootGlobals 之一')
|
|
198
|
+
}
|
|
199
|
+
if (impl.root && !impl.mount) errors.push('$ 提供 root 时必须同时提供 mount')
|
|
200
|
+
},
|
|
201
|
+
}),
|
|
202
|
+
|
|
203
|
+
'own-server@1': Object.freeze({
|
|
204
|
+
kind: 'own-server@1',
|
|
205
|
+
major: 1,
|
|
206
|
+
title: '自有 HTTP 面',
|
|
207
|
+
summary: '宿主有网页端口时挂到该端口的前缀下(不新起端口),否则由 service-host 托管独立 loopback origin。',
|
|
208
|
+
unique: true,
|
|
209
|
+
uniqueBy: 'id',
|
|
210
|
+
schema: Object.freeze({
|
|
211
|
+
type: 'object',
|
|
212
|
+
required: ['id', 'handler'],
|
|
213
|
+
additionalProperties: false,
|
|
214
|
+
properties: {
|
|
215
|
+
id: kebab,
|
|
216
|
+
mount: { type: 'string', pattern: '^/' },
|
|
217
|
+
port: { type: ['number', 'string', 'function'] },
|
|
218
|
+
host: nonEmpty,
|
|
219
|
+
handler: { type: 'function' },
|
|
220
|
+
start: { type: 'function' },
|
|
221
|
+
stop: { type: 'function' },
|
|
222
|
+
},
|
|
223
|
+
}),
|
|
224
|
+
}),
|
|
225
|
+
|
|
226
|
+
'service-provider@1': Object.freeze({
|
|
227
|
+
kind: 'service-provider@1',
|
|
228
|
+
major: 1,
|
|
229
|
+
title: '宿主服务提供者',
|
|
230
|
+
summary: '向宿主 ctx 提供一个具名服务;服务工厂必须同步,异步启动放在 start 钩子里。',
|
|
231
|
+
unique: true,
|
|
232
|
+
uniqueBy: 'service',
|
|
233
|
+
schema: Object.freeze({
|
|
234
|
+
type: 'object',
|
|
235
|
+
required: ['service', 'provide'],
|
|
236
|
+
additionalProperties: false,
|
|
237
|
+
properties: {
|
|
238
|
+
service: nonEmpty,
|
|
239
|
+
provide: { type: 'function' },
|
|
240
|
+
when: { type: 'function' },
|
|
241
|
+
start: { type: 'function' },
|
|
242
|
+
stop: { type: 'function' },
|
|
243
|
+
},
|
|
244
|
+
}),
|
|
245
|
+
}),
|
|
246
|
+
|
|
247
|
+
'raw@1': Object.freeze({
|
|
248
|
+
kind: 'raw@1',
|
|
249
|
+
major: 1,
|
|
250
|
+
title: '原生插件(逃生舱)',
|
|
251
|
+
summary: '极少数需要自定义装配的插件;必须在 meta/foundation.allowlist.json 登记,且不得与其他接口混用。',
|
|
252
|
+
unique: false,
|
|
253
|
+
exclusive: true,
|
|
254
|
+
schema: Object.freeze({
|
|
255
|
+
type: 'object',
|
|
256
|
+
required: ['apply'],
|
|
257
|
+
additionalProperties: false,
|
|
258
|
+
properties: {
|
|
259
|
+
apply: { type: 'function' },
|
|
260
|
+
},
|
|
261
|
+
}),
|
|
262
|
+
}),
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
/** 内核当前认识的 kind 列表(供错误信息与文档生成)。 */
|
|
266
|
+
export const INTERFACE_KIND_NAMES = Object.freeze(Object.keys(INTERFACE_KINDS))
|
|
267
|
+
|
|
268
|
+
/** 取接口定义;未知 kind 返回 undefined,由调用方转成 E_KIND_UNKNOWN。 */
|
|
269
|
+
export function getInterfaceKind(kind) {
|
|
270
|
+
return INTERFACE_KINDS[kind]
|
|
271
|
+
}
|