@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
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 结构化日志:优先复用 dsh 的 ctx.logger,没有就退回 console。
|
|
3
|
+
*
|
|
4
|
+
* 插件不自己拼前缀,一律通过 log.child({ plugin }) 拿作用域。
|
|
5
|
+
* ctx 是 Cordis Proxy,未 inject 的服务直接读会抛错,这里用 getService 探测。
|
|
6
|
+
*/
|
|
7
|
+
import { getService } from '../ctx-service.mjs'
|
|
8
|
+
|
|
9
|
+
const LEVELS = ['debug', 'info', 'warn', 'error']
|
|
10
|
+
|
|
11
|
+
/* 安全格式化:日志调用绝不能反过来崩掉调用方。
|
|
12
|
+
* - Error 特判取 stack/message(JSON.stringify(Error) 是 '{}',根因会彻底丢失);
|
|
13
|
+
* - 循环引用用 replacer 标 '[Circular]',不再抛 Converting circular structure;
|
|
14
|
+
* - 其余 stringify 失败(BigInt 等)退回 String。 */
|
|
15
|
+
function format(arg) {
|
|
16
|
+
if (typeof arg === 'string') return arg
|
|
17
|
+
if (arg instanceof Error) return arg.stack || `${arg.name}: ${arg.message}`
|
|
18
|
+
const seen = new WeakSet()
|
|
19
|
+
try {
|
|
20
|
+
return JSON.stringify(arg, (_key, value) => {
|
|
21
|
+
if (typeof value === 'object' && value !== null) {
|
|
22
|
+
if (seen.has(value)) return '[Circular]'
|
|
23
|
+
seen.add(value)
|
|
24
|
+
}
|
|
25
|
+
return value
|
|
26
|
+
})
|
|
27
|
+
} catch {
|
|
28
|
+
return String(arg)
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function createScoped(underlying, scope) {
|
|
33
|
+
const prefix = scope ? `[${scope}]` : ''
|
|
34
|
+
const scoped = {}
|
|
35
|
+
for (const level of LEVELS) {
|
|
36
|
+
scoped[level] = (...args) => {
|
|
37
|
+
const message = args.map(format).join(' ')
|
|
38
|
+
const line = `${prefix} ${message}`.trim()
|
|
39
|
+
const fn = underlying?.[level]
|
|
40
|
+
if (typeof fn === 'function') fn.call(underlying, line)
|
|
41
|
+
else if (level !== 'debug') console[level](line)
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
scoped.child = (next) => createScoped(underlying, scope ? `${scope}:${next}` : next)
|
|
45
|
+
return scoped
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function createLogger(host, config = {}) {
|
|
49
|
+
const underlying = typeof host?.log === 'function' ? host.log() : getService(host, 'logger')
|
|
50
|
+
return createScoped(underlying, config.scope || 'foundation')
|
|
51
|
+
}
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTTP 共享宿主:内核持有的唯一监听面。
|
|
3
|
+
*
|
|
4
|
+
* 惰性:第一次有插件挂路由时才创建共享宿主并 listen,
|
|
5
|
+
* 只注册 skill 的插件不会因为装了 foundation 就占一个端口。
|
|
6
|
+
*
|
|
7
|
+
* 优先同源:宿主提供 `web()`(dsh 即 `ctx.webServer`)时,共享宿主挂到该端口的
|
|
8
|
+
* `http.basePath` 前缀下,**不再新起端口**;只有拿不到 web() 的宿主才独立监听。
|
|
9
|
+
*/
|
|
10
|
+
import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
|
|
11
|
+
|
|
12
|
+
export const DEFAULT_WEB_BASE_PATH = '/plugins/foundation-shared'
|
|
13
|
+
|
|
14
|
+
/** 等宿主网页端口出现的上限:插件比 webserver fiber 早 settle 时不至于永久独占端口。
|
|
15
|
+
* 这个等待会阻塞插件的 start(),所以刻意保持短;更晚出现的端口由 watchForLateWeb() 补挂。 */
|
|
16
|
+
export const WEB_WAIT_MS = Number(process.env.DSH_FOUNDATION_WEB_WAIT_MS) || 4000
|
|
17
|
+
const WEB_POLL_MS = 100
|
|
18
|
+
/** 独立监听之后再等宿主网页端口的时长:桌面宿主是「先加载全部插件、最后起网页端口」,
|
|
19
|
+
* 它姗姗来迟时要把同一套路由补挂上去,否则站点永远只在自己那个端口上可达。 */
|
|
20
|
+
export const WEB_LATE_WAIT_MS = Number(process.env.DSH_FOUNDATION_WEB_LATE_WAIT_MS) || 60000
|
|
21
|
+
const WEB_LATE_POLL_MS = 250
|
|
22
|
+
|
|
23
|
+
export function createNet(host, config = {}) {
|
|
24
|
+
const http = config.http || {}
|
|
25
|
+
let sharedHost = null
|
|
26
|
+
let listening = null
|
|
27
|
+
let closed = false
|
|
28
|
+
let disposal = null
|
|
29
|
+
let embedded = false
|
|
30
|
+
/** listen 的返回值:{ url, port, mode },说明这次到底挂在哪里。 */
|
|
31
|
+
let info = null
|
|
32
|
+
/** 迟到补挂的轮询是否已启动,以及补挂成功后的 disposer(close 时撤掉)。 */
|
|
33
|
+
let lateWatching = false
|
|
34
|
+
let lateDispose = null
|
|
35
|
+
/** 迟到补挂成功时宿主网页端口的端口号(describe().port 以它为准)。 */
|
|
36
|
+
let webPort = 0
|
|
37
|
+
|
|
38
|
+
/** 宿主的网页端口;没有就不返回,调用方一律退化成独立监听。 */
|
|
39
|
+
function webServer() {
|
|
40
|
+
const web = typeof host.web === 'function' ? host.web() : null
|
|
41
|
+
return web && typeof web.register === 'function' ? web : null
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function basePath() {
|
|
45
|
+
const value = http.basePath ?? DEFAULT_WEB_BASE_PATH
|
|
46
|
+
return typeof value === 'string' ? value : DEFAULT_WEB_BASE_PATH
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** 只有真宿主才值得等:内存宿主(测试)本来就没有网页端口,等只是拖慢启动。 */
|
|
50
|
+
function shouldWaitForWeb() {
|
|
51
|
+
return typeof host.web === 'function' && host.kind !== 'memory'
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** 诊断用:这次到底把站点挂在了哪里(桌面宿主的 stdout 能在启动日志里看到)。 */
|
|
55
|
+
function logDecision() {
|
|
56
|
+
try {
|
|
57
|
+
console.log(`[foundation] net ${info?.mode || 'unknown'} port=${Number(info?.port) || 0}`
|
|
58
|
+
+ ` url=${info?.url || ''} embedded=${embedded} host.web=${typeof host.web === 'function'}`)
|
|
59
|
+
} catch { /* 日志失败不影响监听 */ }
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* 网页端口迟到时的补救:独立端口已经在跑,但宿主的网页端口随后出现,
|
|
64
|
+
* 就把同一套子 app 再挂到它的 `basePath` 前缀上(同源,浏览器半用相对路径即可)。
|
|
65
|
+
* 只注册一次;注册失败(重复/宿主拒收)只记一笔,不打扰已经可用的独立端口。
|
|
66
|
+
*/
|
|
67
|
+
function watchForLateWeb() {
|
|
68
|
+
if (!shouldWaitForWeb() || closed || lateWatching) return
|
|
69
|
+
lateWatching = true
|
|
70
|
+
const deadline = Date.now() + WEB_LATE_WAIT_MS
|
|
71
|
+
void (async () => {
|
|
72
|
+
while (!closed && Date.now() < deadline) {
|
|
73
|
+
const web = webServer()
|
|
74
|
+
if (web) {
|
|
75
|
+
try {
|
|
76
|
+
const prefix = basePath()
|
|
77
|
+
const app = sharedHost?.app
|
|
78
|
+
if (typeof web.register === 'function' && typeof app?.dispatch === 'function') {
|
|
79
|
+
lateDispose = web.register({
|
|
80
|
+
kind: 'prefix',
|
|
81
|
+
path: prefix,
|
|
82
|
+
handler: (req, res) => app.dispatch(req, res, prefix),
|
|
83
|
+
})
|
|
84
|
+
embedded = true
|
|
85
|
+
webPort = Number(web.port) || 0
|
|
86
|
+
info = { ...(info || {}), mode: 'embedded-late', url: `http://127.0.0.1:${webPort || Number(info?.port) || 0}${prefix}` }
|
|
87
|
+
logDecision()
|
|
88
|
+
}
|
|
89
|
+
} catch (error) {
|
|
90
|
+
console.warn?.(`[foundation] net 补挂 ${basePath()} 失败:${error?.message || error}`)
|
|
91
|
+
}
|
|
92
|
+
return
|
|
93
|
+
}
|
|
94
|
+
await new Promise((resolve) => setTimeout(resolve, WEB_LATE_POLL_MS))
|
|
95
|
+
}
|
|
96
|
+
})().catch(() => {})
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function ensure() {
|
|
100
|
+
if (closed) {
|
|
101
|
+
throw new AbiError(ERROR_CODES.E_ADAPTER_THREW,
|
|
102
|
+
'共享 HTTP 宿主已关闭,不能重新挂载或监听', { capability: 'os.net' })
|
|
103
|
+
}
|
|
104
|
+
if (!sharedHost) {
|
|
105
|
+
const serviceHost = host.http()
|
|
106
|
+
if (!serviceHost?.createSharedHost) {
|
|
107
|
+
throw new AbiError(ERROR_CODES.E_CAP_MISSING,
|
|
108
|
+
'ctx.serviceHost 不可用:无法挂载 HTTP 路由', { capability: 'os.net' })
|
|
109
|
+
}
|
|
110
|
+
sharedHost = serviceHost.createSharedHost({ id: http.hostId || 'foundation-shared' })
|
|
111
|
+
// 宿主网页端口可能比本插件晚 settle(cordis 只在服务 fiber 处于 active 时
|
|
112
|
+
// 才把它暴露给 ctx.get),此时立刻退回独立监听会让站点永久脱离同源前缀。
|
|
113
|
+
// 先短暂等待它出现,再决定嵌入还是独立端口;listen 之前挂上的路由不受影响。
|
|
114
|
+
listening = (async () => {
|
|
115
|
+
let web = webServer()
|
|
116
|
+
if (!web && shouldWaitForWeb()) {
|
|
117
|
+
const deadline = Date.now() + WEB_WAIT_MS
|
|
118
|
+
while (!web && Date.now() < deadline && !closed) {
|
|
119
|
+
await new Promise((resolve) => setTimeout(resolve, WEB_POLL_MS))
|
|
120
|
+
web = webServer()
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
embedded = !!web
|
|
124
|
+
info = await sharedHost.listen(
|
|
125
|
+
web ? { webServer: web, basePath: basePath() } : { port: http.port ?? 0 },
|
|
126
|
+
)
|
|
127
|
+
if (!embedded) watchForLateWeb()
|
|
128
|
+
logDecision()
|
|
129
|
+
return info
|
|
130
|
+
})()
|
|
131
|
+
// compile 阶段就可能开始监听;立即观察拒绝,但 ready 仍返回原始失败。
|
|
132
|
+
void listening.catch(() => {})
|
|
133
|
+
}
|
|
134
|
+
return sharedHost
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function close() {
|
|
138
|
+
if (disposal) return disposal
|
|
139
|
+
closed = true
|
|
140
|
+
disposal = (async () => {
|
|
141
|
+
if (!sharedHost) return
|
|
142
|
+
// listen 失败由 ready/start 报告;清理仍需执行,且 close 失败不能被吞掉。
|
|
143
|
+
await listening.catch(() => {})
|
|
144
|
+
// 迟到补挂的路由要一起撤掉,否则共享宿主关了、宿主网页端口上还留着分发器。
|
|
145
|
+
try {
|
|
146
|
+
lateDispose?.()
|
|
147
|
+
} catch { /* 撤不掉也不能挡住关闭 */ }
|
|
148
|
+
lateDispose = null
|
|
149
|
+
try {
|
|
150
|
+
await sharedHost.close()
|
|
151
|
+
} finally {
|
|
152
|
+
sharedHost = null
|
|
153
|
+
}
|
|
154
|
+
})()
|
|
155
|
+
return disposal
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return {
|
|
159
|
+
ensure,
|
|
160
|
+
mount(prefix, child) {
|
|
161
|
+
return ensure().mount(prefix, child)
|
|
162
|
+
},
|
|
163
|
+
children: () => (sharedHost ? sharedHost.children() : []),
|
|
164
|
+
/** 是否挂到了宿主网页端口(true = 没有新起端口)。 */
|
|
165
|
+
embedded: () => embedded,
|
|
166
|
+
/**
|
|
167
|
+
* 本次监听的实情,供插件拼自己的对外地址:
|
|
168
|
+
* embedded → origin = `http://host:port/plugins/...`(可与 location.origin 拼相对路径)
|
|
169
|
+
* 独立端口 → origin = `http://127.0.0.1:<port>`(插件的路由挂在它的 MOUNT 上)
|
|
170
|
+
*/
|
|
171
|
+
describe() {
|
|
172
|
+
return {
|
|
173
|
+
embedded,
|
|
174
|
+
basePath: basePath(),
|
|
175
|
+
origin: info?.url || '',
|
|
176
|
+
// 迟到补挂时站点实际归宿主网页端口,独立端口只是兜底,不应再报给插件。
|
|
177
|
+
port: embedded && webPort ? webPort : Number(info?.port) || 0,
|
|
178
|
+
mode: info?.mode || '',
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
ready() {
|
|
182
|
+
ensure()
|
|
183
|
+
return listening
|
|
184
|
+
},
|
|
185
|
+
close,
|
|
186
|
+
dispose: close,
|
|
187
|
+
}
|
|
188
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@capyclaw/foundation",
|
|
3
|
+
"version": "0.1.9",
|
|
4
|
+
"description": "dsh 插件基石层:接口 ABI、插件加载器与内核服务 ctx.os。应用插件只声明接口,不写装配代码。",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./lib/host.mjs",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./lib/host.mjs",
|
|
9
|
+
"./abi": "./abi/index.mjs",
|
|
10
|
+
"./kit": "./kit/index.mjs",
|
|
11
|
+
"./runtime": "./runtime/index.mjs",
|
|
12
|
+
"./package.json": "./package.json"
|
|
13
|
+
},
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=18",
|
|
16
|
+
"dsh": "^0.2.0-rc.2"
|
|
17
|
+
},
|
|
18
|
+
"publishConfig": {
|
|
19
|
+
"access": "public"
|
|
20
|
+
},
|
|
21
|
+
"dsh": {
|
|
22
|
+
"bundle": {
|
|
23
|
+
"patch": "./cordis.patch.yml"
|
|
24
|
+
},
|
|
25
|
+
"category": "service",
|
|
26
|
+
"platform": "both",
|
|
27
|
+
"apiVersion": "1.0.0"
|
|
28
|
+
},
|
|
29
|
+
"meta": {
|
|
30
|
+
"title": "插件基石层",
|
|
31
|
+
"description": "接口 ABI、插件加载器与 ctx.os 内核服务;应用插件只声明接口"
|
|
32
|
+
},
|
|
33
|
+
"files": [
|
|
34
|
+
"abi/",
|
|
35
|
+
"lib/",
|
|
36
|
+
"kit/",
|
|
37
|
+
"runtime/",
|
|
38
|
+
"cordis.patch.yml",
|
|
39
|
+
"README.md"
|
|
40
|
+
],
|
|
41
|
+
"scripts": {
|
|
42
|
+
"test": "node --test test/*.test.mjs"
|
|
43
|
+
},
|
|
44
|
+
"license": "MIT",
|
|
45
|
+
"dependencies": {
|
|
46
|
+
"@capyclaw/plugin-kit": "^0.2.0"
|
|
47
|
+
},
|
|
48
|
+
"repository": {
|
|
49
|
+
"type": "git",
|
|
50
|
+
"url": "git+https://github.com/Maple496/capyclaw.git",
|
|
51
|
+
"directory": "C/packages/capyclaw-foundation"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 宿主运行时入口:给 dsh 之外的宿主装配插件用。
|
|
3
|
+
*
|
|
4
|
+
* 适用:独立技能服务、构建工具、e2e 夹具。
|
|
5
|
+
* 不适用:应用插件。应用插件只允许 import `./abi` 与 `./kit`,
|
|
6
|
+
* 由准入闸(scripts/checks/check-foundation-only.mjs)强制。
|
|
7
|
+
*
|
|
8
|
+
* 宿主的职责与 dsh 相同:提供 ctx 里真实存在的服务,内核据此探测能力表。
|
|
9
|
+
*/
|
|
10
|
+
export {
|
|
11
|
+
createKernel,
|
|
12
|
+
detectCapabilities,
|
|
13
|
+
BASE_CAPABILITIES,
|
|
14
|
+
KERNEL_VERSION,
|
|
15
|
+
ABI_VERSION,
|
|
16
|
+
} from '../lib/kernel.mjs'
|
|
17
|
+
export { assertHostContract } from '../lib/host/contract.mjs'
|
|
18
|
+
export { createMemoryHost } from '../lib/host/memory.mjs'
|
|
19
|
+
export { createDshHost } from '../lib/host/dsh.mjs'
|
|
20
|
+
export * from '../abi/index.mjs'
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# 新插件稳定接入清单
|
|
2
|
+
|
|
3
|
+
> 新插件优先使用公共插件:`@capyclaw/service-host`、`@capyclaw/tool-host`、`@capyclaw/asset-service`、`@capyclaw/editor-host`。
|
|
4
|
+
> 本文件只描述底层 kit 的接入方式,供公共插件实现或旧插件维护使用。
|
|
5
|
+
|
|
6
|
+
## 1. 包结构
|
|
7
|
+
|
|
8
|
+
```text
|
|
9
|
+
my-plugin/
|
|
10
|
+
├─ package.json # dsh.bundle.patch + dsh.suite(可选)
|
|
11
|
+
├─ cordis.patch.yml # 只放插件行;不内联大段业务配置
|
|
12
|
+
├─ lib/host.mjs # 只负责生命周期,不写业务
|
|
13
|
+
├─ server/
|
|
14
|
+
│ ├─ relay.mjs # 路由/生命周期:/healthz /metrics /mcp
|
|
15
|
+
│ ├─ store.mjs # 业务状态(可扩展 JournalStore)
|
|
16
|
+
│ ├─ tools.mjs # 工具 schema + 分派
|
|
17
|
+
│ ├─ impl.mjs # 业务实现
|
|
18
|
+
│ └─ infra/ # 构建期从 @capyclaw/plugin-kit 拷贝的稳定快照
|
|
19
|
+
└─ editor/ # 浏览器端(可选)
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## 2. 必须实现的基础协议
|
|
23
|
+
|
|
24
|
+
| 项 | 要求 |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `GET /healthz` | `{ ok:true, name, version, contractVersion, uptimeSec, ...业务状态 }` |
|
|
27
|
+
| `GET /metrics` | Prometheus 文本;至少 `*_up`、`*_uptime_seconds` |
|
|
28
|
+
| `/mcp` | 使用 `createMcpHandler`,所有工具调用先 `validateToolArguments` |
|
|
29
|
+
| 绑定地址 | 只绑定 `127.0.0.1`,不要 `0.0.0.0` |
|
|
30
|
+
| 单实例 | 由 service-host 内置实例锁承担(锁文件/复用探测/残留接管一体);不要自建第二套 |
|
|
31
|
+
| 状态落盘 | 每次变更原子写;journal + checkpoint 可选但推荐 |
|
|
32
|
+
| 编辑器 | 显示即连接;心跳用 Worker;lease TTL 与心跳间隔匹配 |
|
|
33
|
+
| 关闭 | `server.close` + `closeAllConnections`,释放锁和 discovery 文件 |
|
|
34
|
+
|
|
35
|
+
## 3. kit 快照
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
node C/packages/capyclaw-plugin-kit/bin/sync.mjs --out <plugin>/server/infra --force
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
生成 `INFRA_MANIFEST.json`;插件导入示例:
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
import { listen, send, sendText, readBody } from './infra/service/http.mjs'
|
|
45
|
+
import { createMcpHandler } from './infra/service/mcp-http.mjs'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 4. 工具接入
|
|
49
|
+
|
|
50
|
+
1. 工具 schema 放在独立 `schema` 模块或 `tools.mjs`;
|
|
51
|
+
2. 实现按领域分组(`impl-*.mjs`),由 `index.mjs` 汇合;
|
|
52
|
+
3. 每个工具都有稳定的 name / inputSchema / 返回形状;
|
|
53
|
+
4. 参数超限必须返回 `isError`,不能进入实现;
|
|
54
|
+
5. 契约版本和工具清单通过一个只读 `*_capabilities` 工具暴露;
|
|
55
|
+
6. 大参数工具必须在 schema 里限制 `maxItems` / `maxLength`。
|
|
56
|
+
|
|
57
|
+
## 5. 技能接入
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { createSkillProvider } from '@capyclaw/plugin-kit/skills/provider'
|
|
61
|
+
|
|
62
|
+
const provider = createSkillProvider({
|
|
63
|
+
assetRoot,
|
|
64
|
+
skillDirs: ['my-router', 'my-edit'],
|
|
65
|
+
providerName: 'dsh-my-plugin',
|
|
66
|
+
contractRoot,
|
|
67
|
+
contractFile: 'my-contract.json',
|
|
68
|
+
})
|
|
69
|
+
ctx.skills.registerProvider(() => provider)
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
技能正文只写 instructions;运行时能力通过工具名/契约引用,不复制工具实现。
|
|
73
|
+
|
|
74
|
+
## 6. 领域接入
|
|
75
|
+
|
|
76
|
+
- 用 `dsh-suite.json` 描述组件与能力;
|
|
77
|
+
- 用 `dsh-domain.json` 选择领域所需组件;
|
|
78
|
+
- 新插件先 `dsh-suite validate`,再 `dsh-domain stage`,最后 `dsh-domain launch`;
|
|
79
|
+
- 不要自定义 profile 结构,统一用 `@capyclaw/suite-kit` 生成。
|
|
80
|
+
|
|
81
|
+
## 7. 稳定性验收
|
|
82
|
+
|
|
83
|
+
- `@capyclaw/plugin-kit` 单测通过;
|
|
84
|
+
- 插件自身契约测试通过;
|
|
85
|
+
- MCP E2E:capabilities / tools / 错误路径 / 恢复;
|
|
86
|
+
- 压测:并发读、并发写、非法参数、超大参数、截图/长任务;
|
|
87
|
+
- 进程重启后 `state.json` / journal / checkpoint 可恢复;
|
|
88
|
+
- 两个 profile 同时启动可复用 bridge 或使用独立端口。
|
|
89
|
+
|
|
90
|
+
## 8. Runtime / Content Store 接入
|
|
91
|
+
|
|
92
|
+
- 插件启动时 `runtimeContextFromConfig(config)` 读取 `runtime.json`,拿
|
|
93
|
+
`ports.content`、`paths.contentState`、`store.root`、`store.token`;
|
|
94
|
+
- 用 `createRuntimeStoreClient(context)` 得到 scoped `WorkspaceClient`;
|
|
95
|
+
- 插件状态用 `WorkspaceBackend` 映射到对象仓库(state/journal/checkpoint);
|
|
96
|
+
- 不要硬编码任何固定端口(历史上有插件写死过,后来端口变了就全线连不上)、`~/.dsh-ppt-bridge` 或全局锁文件;
|
|
97
|
+
- `BlobStore` 只存对象;work 归属、版本 CAS、catalog 和生命周期由
|
|
98
|
+
`WorkspaceManager` 中间层负责;
|
|
99
|
+
- 多 runtime 同时运行时,每个 runtime 的 `harness` / `content` 端口和
|
|
100
|
+
namespace token 都不同,不能复用其他 runtime 的端口或 store token。
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# @capyclaw/plugin-kit(插件底层协议库)
|
|
2
|
+
|
|
3
|
+
> 运行时公共服务已经拆到 `@capyclaw/service-host`、`@capyclaw/tool-host`、`@capyclaw/asset-service`、`@capyclaw/editor-host`。
|
|
4
|
+
> 新插件优先使用这些公共插件(`ctx.*`),或用 `@capyclaw/*` 包直接 import;`server/shared/` 只是零拷贝转发,不要当作快照副本。
|
|
5
|
+
> 本包只保留纯函数/传输/存储算法,供公共插件和旧插件使用。
|
|
6
|
+
|
|
7
|
+
后续插件不要各自重复实现这些机制。按本包的接口接入,PPT 只是第一个消费者,新的 `plugin-development` 脚手架是第二个消费者。
|
|
8
|
+
|
|
9
|
+
## 提供什么
|
|
10
|
+
|
|
11
|
+
| 模块 | 能力 |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `service/http` | 安全响应头、JSON/text 响应、body 上限、query 解析、loopback 监听(可挂 handler) |
|
|
14
|
+
| `service/mcp-http` | 通用 MCP Streamable HTTP 处理器(initialize/ping/tools/list/tools/call) |
|
|
15
|
+
| `tools/validate` | inputSchema 子集校验(required/type/enum/maxLength/maxItems/additionalProperties) |
|
|
16
|
+
| `skills/provider` | 扫描 `skills/*/SKILL.md`,按需加载,自动 frontmatter 校验 |
|
|
17
|
+
| `editor/transport` | 浏览器 → 本机服务的 fetch/JSON 封装 |
|
|
18
|
+
| `editor/lease` | “显示即连接”的编辑器租约与自动挂接 |
|
|
19
|
+
| `editor/heartbeat-worker.js` | 不受标签页节流的心跳 Worker |
|
|
20
|
+
| `store/journal-store` | 原子 JSON 状态、append-only journal、命名 checkpoint |
|
|
21
|
+
| `store/blob-store` | 纯内容仓库:按 sha256 存不可变对象,不关心文件关系 |
|
|
22
|
+
| `workspace/manager` | 中间层:work manifest、文件归属、版本 CAS、catalog、生命周期 |
|
|
23
|
+
| `runtime/context` | 读取当前 runtime 的端口、目录、namespace,并创建 scoped WorkspaceClient |
|
|
24
|
+
|
|
25
|
+
## 职责边界
|
|
26
|
+
|
|
27
|
+
- 编排中间层在 `@capyclaw/suite-kit`:打包插件、分配端口、创建 runtime、校验
|
|
28
|
+
`requires`、声明 work 的文件范围、维护 catalog 和生命周期。
|
|
29
|
+
- `BlobStore` 只接收字节,按内容 hash 存储;它不知道文件名、作品、runtime。
|
|
30
|
+
- `WorkspaceManager` 是中间层的 workspace 实现:解释“哪些对象属于同一个 work、
|
|
31
|
+
谁能改、版本是多少”,并把可展示的目录写到 `catalog/works.json`。
|
|
32
|
+
- 插件通过 `WorkspaceClient` 访问自己的 namespace;新文件自动进入当前 work
|
|
33
|
+
的 manifest,不会串到别的 runtime。
|
|
34
|
+
- `WorkspaceBackend` 把 state/journal/checkpoint 映射到对象仓库;可选 `journalPath` 把 append-only journal 写到 runtime 自己的 logs,避免 O(n²) 对象重写。PPT 已接入。
|
|
35
|
+
|
|
36
|
+
## 使用方式
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
import { listen, send, sendText, readBody } from '@capyclaw/plugin-kit/service/http'
|
|
40
|
+
import { createMcpHandler } from '@capyclaw/plugin-kit/service/mcp-http'
|
|
41
|
+
import { createSkillProvider } from '@capyclaw/plugin-kit/skills/provider'
|
|
42
|
+
import { createEditorLease } from '@capyclaw/plugin-kit/editor/lease'
|
|
43
|
+
import { JournalStore } from '@capyclaw/plugin-kit/store/journal-store'
|
|
44
|
+
import { BlobStore, WorkspaceManager, WorkspaceClient, WorkspaceBackend } from '@capyclaw/plugin-kit'
|
|
45
|
+
import { runtimeContextFromConfig, createRuntimeStoreClient } from '@capyclaw/plugin-kit/runtime/context'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
本地插件包可以在构建期把 kit 源码快照进自己的包(`server/infra/`),这样插件仍然可以独立分发:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
node C/packages/capyclaw-plugin-kit/bin/sync.mjs --out <plugin>/server/infra --force
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
快照会写 `INFRA_MANIFEST.json`(版本、hash、文件清单),升级 kit 后重新同步并提交。
|
|
55
|
+
|
|
56
|
+
## 兼容性契约
|
|
57
|
+
|
|
58
|
+
- kit minor 版本只新增导出,不改变已有函数签名;
|
|
59
|
+
- breaking change 必须 major;
|
|
60
|
+
- 插件包应锁定 kit 的精确版本/快照,不要跨 major 混用;
|
|
61
|
+
- 任何插件暴露的 `/healthz` 至少返回 `{ ok, version, contractVersion }`;
|
|
62
|
+
- 任何插件暴露的 `/metrics` 使用稳定的指标名;
|
|
63
|
+
- 任何 MCP 工具调用前必须经过 `validateToolArguments`。
|
|
64
|
+
|
|
65
|
+
## 测试
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
cd C/packages/capyclaw-plugin-kit
|
|
69
|
+
npm test
|
|
70
|
+
```
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* 把 @capyclaw/plugin-kit 源码快照到插件包的 server/infra/。
|
|
4
|
+
*
|
|
5
|
+
* 用法:
|
|
6
|
+
* node packages/@capyclaw/plugin-kit/bin/sync.mjs --out <plugin>/server/infra
|
|
7
|
+
* node packages/@capyclaw/plugin-kit/bin/sync.mjs --out <plugin>/server/infra --force
|
|
8
|
+
*/
|
|
9
|
+
import fs from 'node:fs'
|
|
10
|
+
import path from 'node:path'
|
|
11
|
+
import { fileURLToPath } from 'node:url'
|
|
12
|
+
import { createHash } from 'node:crypto'
|
|
13
|
+
|
|
14
|
+
const HERE = path.dirname(fileURLToPath(import.meta.url))
|
|
15
|
+
const KIT_ROOT = path.resolve(HERE, '..')
|
|
16
|
+
const KIT_SRC = path.join(KIT_ROOT, 'src')
|
|
17
|
+
|
|
18
|
+
function parseArgs(argv) {
|
|
19
|
+
const options = { out: '', force: false }
|
|
20
|
+
for (let i = 0; i < argv.length; i++) {
|
|
21
|
+
const arg = argv[i]
|
|
22
|
+
if (arg === '--out' || arg === '-o') options.out = argv[++i]
|
|
23
|
+
else if (arg.startsWith('--out=')) options.out = arg.slice('--out='.length)
|
|
24
|
+
else if (arg === '--force' || arg === '-f') options.force = true
|
|
25
|
+
else if (arg === '--help' || arg === '-h') options.help = true
|
|
26
|
+
else throw new Error(`未知参数: ${arg}`)
|
|
27
|
+
}
|
|
28
|
+
return options
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function listFiles(dir, base = dir) {
|
|
32
|
+
const out = []
|
|
33
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
34
|
+
const full = path.join(dir, entry.name)
|
|
35
|
+
if (entry.isDirectory()) out.push(...listFiles(full, base))
|
|
36
|
+
else if (entry.isFile()) out.push(path.relative(base, full).replace(/\\/g, '/'))
|
|
37
|
+
}
|
|
38
|
+
return out.sort()
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function hashFiles(root, files) {
|
|
42
|
+
const hash = createHash('sha256')
|
|
43
|
+
for (const file of files) {
|
|
44
|
+
hash.update(file)
|
|
45
|
+
hash.update(fs.readFileSync(path.join(root, file)))
|
|
46
|
+
}
|
|
47
|
+
return hash.digest('hex')
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function syncKit({ outDir, force = false } = {}) {
|
|
51
|
+
if (!outDir) throw new Error('syncKit: outDir 必填')
|
|
52
|
+
const target = path.resolve(outDir)
|
|
53
|
+
if (fs.existsSync(target)) {
|
|
54
|
+
const entries = fs.readdirSync(target)
|
|
55
|
+
if (!force && entries.length > 0 && !entries.includes('INFRA_MANIFEST.json')) {
|
|
56
|
+
throw new Error(`目标目录非空且不是 kit 快照: ${target}(使用 --force 覆盖)`)
|
|
57
|
+
}
|
|
58
|
+
fs.rmSync(target, { recursive: true, force: true })
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const pkg = JSON.parse(fs.readFileSync(path.join(KIT_ROOT, 'package.json'), 'utf8'))
|
|
62
|
+
const files = listFiles(KIT_SRC)
|
|
63
|
+
fs.mkdirSync(target, { recursive: true })
|
|
64
|
+
for (const file of files) {
|
|
65
|
+
const dest = path.join(target, file)
|
|
66
|
+
fs.mkdirSync(path.dirname(dest), { recursive: true })
|
|
67
|
+
fs.copyFileSync(path.join(KIT_SRC, file), dest)
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const manifest = {
|
|
71
|
+
name: pkg.name,
|
|
72
|
+
version: pkg.version,
|
|
73
|
+
source: 'packages/@capyclaw/plugin-kit/src',
|
|
74
|
+
syncedAt: new Date().toISOString(),
|
|
75
|
+
hash: hashFiles(KIT_SRC, files),
|
|
76
|
+
files,
|
|
77
|
+
}
|
|
78
|
+
fs.writeFileSync(path.join(target, 'INFRA_MANIFEST.json'), JSON.stringify(manifest, null, 2) + '\n')
|
|
79
|
+
return { target, manifest }
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function main() {
|
|
83
|
+
let options
|
|
84
|
+
try {
|
|
85
|
+
options = parseArgs(process.argv.slice(2))
|
|
86
|
+
} catch (error) {
|
|
87
|
+
console.error(`✗ ${error.message}`)
|
|
88
|
+
process.exit(1)
|
|
89
|
+
}
|
|
90
|
+
if (options.help || !options.out) {
|
|
91
|
+
console.log('用法: node packages/@capyclaw/plugin-kit/bin/sync.mjs --out <plugin>/server/infra [--force]')
|
|
92
|
+
process.exit(options.help ? 0 : 1)
|
|
93
|
+
}
|
|
94
|
+
try {
|
|
95
|
+
const result = syncKit({ outDir: options.out, force: options.force })
|
|
96
|
+
console.log(`✓ kit ${result.manifest.version} 已同步到 ${result.target}(${result.manifest.files.length} 个文件)`)
|
|
97
|
+
} catch (error) {
|
|
98
|
+
console.error(`✗ ${error.message}`)
|
|
99
|
+
process.exit(1)
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main()
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@capyclaw/plugin-kit",
|
|
3
|
+
"version": "0.2.6",
|
|
4
|
+
"description": "DSH 插件基础设施标准件:HTTP/MCP、单实例锁、参数校验、技能 provider、journal 存储、编辑器传输与租约。",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.mjs",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.mjs",
|
|
9
|
+
"./service/http": "./src/service/http.mjs",
|
|
10
|
+
"./service/mcp-http": "./src/service/mcp-http.mjs",
|
|
11
|
+
"./service/server": "./src/service/server.mjs",
|
|
12
|
+
"./service/api": "./src/service/api.mjs",
|
|
13
|
+
"./tools/validate": "./src/tools/validate.mjs",
|
|
14
|
+
"./tools/result": "./src/tools/result.mjs",
|
|
15
|
+
"./skills/provider": "./src/skills/provider.mjs",
|
|
16
|
+
"./editor/transport": "./src/editor/transport.js",
|
|
17
|
+
"./editor/lease": "./src/editor/lease.mjs",
|
|
18
|
+
"./editor/shadow": "./src/editor/shadow.mjs",
|
|
19
|
+
"./store/journal-store": "./src/store/journal-store.mjs",
|
|
20
|
+
"./store/blob-store": "./src/store/blob-store.mjs",
|
|
21
|
+
"./store/content-store": "./src/store/content-store.mjs",
|
|
22
|
+
"./workspace/manager": "./src/workspace/manager.mjs",
|
|
23
|
+
"./runtime/context": "./src/runtime/context.mjs",
|
|
24
|
+
"./packaging/pack": "./src/pack.mjs",
|
|
25
|
+
"./packaging/zip": "./src/zip.mjs",
|
|
26
|
+
"./packaging/self-contained": "./src/self-contained.mjs",
|
|
27
|
+
"./cli": "./src/cli.mjs",
|
|
28
|
+
"./package.json": "./package.json",
|
|
29
|
+
"./config": "./src/config.mjs",
|
|
30
|
+
"./tuning": "./src/tuning.mjs",
|
|
31
|
+
"./util/fs-lock": "./src/util/fs-lock.mjs",
|
|
32
|
+
"./util/http": "./src/util/http.mjs",
|
|
33
|
+
"./editor/heartbeat-worker": "./src/editor/heartbeat-worker.js"
|
|
34
|
+
},
|
|
35
|
+
"bin": {
|
|
36
|
+
"@capyclaw/plugin-kit-sync": "./bin/sync.mjs"
|
|
37
|
+
},
|
|
38
|
+
"files": [
|
|
39
|
+
"bin/",
|
|
40
|
+
"src/",
|
|
41
|
+
"README.md",
|
|
42
|
+
"INTEGRATION.md"
|
|
43
|
+
],
|
|
44
|
+
"scripts": {
|
|
45
|
+
"test": "node --test \"test/*.test.mjs\""
|
|
46
|
+
},
|
|
47
|
+
"engines": {
|
|
48
|
+
"node": ">=18"
|
|
49
|
+
},
|
|
50
|
+
"license": "MIT",
|
|
51
|
+
"publishConfig": {
|
|
52
|
+
"access": "public"
|
|
53
|
+
},
|
|
54
|
+
"repository": {
|
|
55
|
+
"type": "git",
|
|
56
|
+
"url": "git+https://github.com/Maple496/capyclaw.git",
|
|
57
|
+
"directory": "C/packages/capyclaw-plugin-kit"
|
|
58
|
+
},
|
|
59
|
+
"keywords": [
|
|
60
|
+
"dsh",
|
|
61
|
+
"dsh-plugin",
|
|
62
|
+
"cordis",
|
|
63
|
+
"plugin-sdk"
|
|
64
|
+
],
|
|
65
|
+
"bugs": {
|
|
66
|
+
"url": "https://github.com/Maple496/capyclaw/issues"
|
|
67
|
+
},
|
|
68
|
+
"homepage": "https://github.com/Maple496/capyclaw/tree/main/C/packages/capyclaw-plugin-kit#readme"
|
|
69
|
+
}
|