@shiqianjiang/ceru-plugin-core 0.2.0
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 +19 -0
- package/dist/index.d.ts +90 -0
- package/dist/index.js +165 -0
- package/package.json +30 -0
package/README.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# @shiqianjiang/ceru-plugin-core
|
|
2
|
+
|
|
3
|
+
Ceru Music v2 的 Host 无关 Core。它读取单文件 artifact,校验 manifest,接收插件注册的 Provider、Action 和歌单 Importer,并在结果返回应用前执行统一的数据契约校验。
|
|
4
|
+
|
|
5
|
+
Core 不实现 Electron、播放器、歌单数据库或账号登录。宿主通过 `CoreHostAdapter` 提供 sandbox、HTTP、权限和 UI 服务;CeruMusic 的 Electron Host 与开发 Host 使用同一边界。
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
const core = await PluginCore.load(bytes, {
|
|
9
|
+
host: {
|
|
10
|
+
activate: (artifact, context) => sandbox.run(artifact, context),
|
|
11
|
+
request: (request) => hostHttp.request(request),
|
|
12
|
+
},
|
|
13
|
+
})
|
|
14
|
+
|
|
15
|
+
await core.invokeProvider('tx', 'tracks.search', [request], operation)
|
|
16
|
+
await core.importPlaylist('import.tx', value, undefined, 100, operation)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
插件仍然只需要导出 `manifest`、`activate` 和可选的 `surfaces`。Core 不要求使用 CLI。
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { type ContentEntity, type JsonObject, type JsonValue, type OperationContext, type PluginContext, type PluginManifest, type ProviderImplementation } from '@shiqianjiang/ceru-plugin-sdk';
|
|
2
|
+
import { type Artifact, type ArtifactHeader } from '@shiqianjiang/ceru-plugin-issuer';
|
|
3
|
+
export interface CoreHostAdapter {
|
|
4
|
+
/** Execute the bundled logic entry in the Host sandbox. */
|
|
5
|
+
activate(artifact: Artifact, context: PluginContext): Promise<void | (() => unknown)>;
|
|
6
|
+
/** Host-owned network broker. Playback URLs are returned directly. */
|
|
7
|
+
request?(request: {
|
|
8
|
+
url: string;
|
|
9
|
+
method?: string;
|
|
10
|
+
headers?: Record<string, string>;
|
|
11
|
+
body?: string;
|
|
12
|
+
timeoutMs?: number;
|
|
13
|
+
operation: OperationContext;
|
|
14
|
+
}): Promise<{
|
|
15
|
+
status: number;
|
|
16
|
+
headers: Record<string, string>;
|
|
17
|
+
body: JsonValue;
|
|
18
|
+
}>;
|
|
19
|
+
onNotice?(notice: {
|
|
20
|
+
type: string;
|
|
21
|
+
data: JsonValue;
|
|
22
|
+
}): void;
|
|
23
|
+
}
|
|
24
|
+
export interface CoreOptions {
|
|
25
|
+
host: CoreHostAdapter;
|
|
26
|
+
/** Optional trusted artifact verification is performed by the issuer before Core loads it. */
|
|
27
|
+
maxProviders?: number;
|
|
28
|
+
maxActions?: number;
|
|
29
|
+
maxImporters?: number;
|
|
30
|
+
}
|
|
31
|
+
export interface ProviderRegistration {
|
|
32
|
+
id: string;
|
|
33
|
+
implementation: ProviderImplementation;
|
|
34
|
+
}
|
|
35
|
+
export interface ActionRegistration {
|
|
36
|
+
id: string;
|
|
37
|
+
handler: (input: JsonValue, operation: OperationContext) => Promise<JsonValue | void> | JsonValue | void;
|
|
38
|
+
}
|
|
39
|
+
export interface ImporterRegistration {
|
|
40
|
+
id: string;
|
|
41
|
+
implementation: {
|
|
42
|
+
getTracks(request: {
|
|
43
|
+
value: string;
|
|
44
|
+
cursor?: string;
|
|
45
|
+
limit: number;
|
|
46
|
+
}, operation: OperationContext): Promise<{
|
|
47
|
+
items: ContentEntity[];
|
|
48
|
+
nextCursor?: string;
|
|
49
|
+
totalEstimate?: number;
|
|
50
|
+
name?: string;
|
|
51
|
+
}>;
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
export interface CoreSnapshot {
|
|
55
|
+
manifest: PluginManifest;
|
|
56
|
+
config: JsonObject;
|
|
57
|
+
providers: string[];
|
|
58
|
+
actions: string[];
|
|
59
|
+
importers: string[];
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Host-neutral v2 Core. The Core owns protocol dispatch and validation; a Host
|
|
63
|
+
* owns sandbox execution and application services.
|
|
64
|
+
*/
|
|
65
|
+
export declare class PluginCore {
|
|
66
|
+
readonly artifact: Artifact;
|
|
67
|
+
readonly manifest: PluginManifest;
|
|
68
|
+
readonly config: Readonly<JsonObject>;
|
|
69
|
+
private readonly options;
|
|
70
|
+
private readonly providers;
|
|
71
|
+
private readonly actions;
|
|
72
|
+
private readonly importers;
|
|
73
|
+
private disposers;
|
|
74
|
+
private constructor();
|
|
75
|
+
static load(input: Uint8Array | ArrayBuffer | string, options: CoreOptions): Promise<PluginCore>;
|
|
76
|
+
context(): PluginContext;
|
|
77
|
+
private registerProvider;
|
|
78
|
+
private registerAction;
|
|
79
|
+
private registerImporter;
|
|
80
|
+
private request;
|
|
81
|
+
invokeProvider(providerId: string, method: string, args?: any[], operation?: OperationContext): Promise<any>;
|
|
82
|
+
invokeAction(id: string, input?: JsonValue, operation?: OperationContext): Promise<JsonValue | void>;
|
|
83
|
+
importPlaylist(id: string, value: string, cursor?: string, limit?: number, operation?: OperationContext): Promise<any>;
|
|
84
|
+
dispose(): Promise<void>;
|
|
85
|
+
snapshot(): CoreSnapshot;
|
|
86
|
+
}
|
|
87
|
+
export declare function readPluginArtifact(input: Uint8Array | ArrayBuffer | string): {
|
|
88
|
+
header: ArtifactHeader;
|
|
89
|
+
artifact: Artifact;
|
|
90
|
+
};
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import { assertContentPage, assertLyricsDocument, assertResolveResult, } from '@shiqianjiang/ceru-plugin-sdk';
|
|
2
|
+
import { readArtifact, resolveArtifactConfig, } from '@shiqianjiang/ceru-plugin-issuer';
|
|
3
|
+
function methodAt(value, path) {
|
|
4
|
+
const parts = path.split('.');
|
|
5
|
+
const owner = parts.slice(0, -1).reduce((current, key) => current?.[key], value);
|
|
6
|
+
const method = owner?.[parts.at(-1)];
|
|
7
|
+
return typeof method === 'function' ? method.bind(owner) : undefined;
|
|
8
|
+
}
|
|
9
|
+
function declaration(manifest, group, id) {
|
|
10
|
+
const values = manifest.contributes?.[group] ?? [];
|
|
11
|
+
return values.find((item) => (group === 'commands' ? item.action === id : item.id === id));
|
|
12
|
+
}
|
|
13
|
+
function operationOrDefault(operation) {
|
|
14
|
+
if (operation)
|
|
15
|
+
return operation;
|
|
16
|
+
const controller = new AbortController();
|
|
17
|
+
return {
|
|
18
|
+
id: `core-${Date.now()}`,
|
|
19
|
+
deadlineAt: Date.now() + 30_000,
|
|
20
|
+
signal: controller.signal,
|
|
21
|
+
userIntent: { kind: 'user-intent', id: `core-${Date.now()}` },
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Host-neutral v2 Core. The Core owns protocol dispatch and validation; a Host
|
|
26
|
+
* owns sandbox execution and application services.
|
|
27
|
+
*/
|
|
28
|
+
export class PluginCore {
|
|
29
|
+
artifact;
|
|
30
|
+
manifest;
|
|
31
|
+
config;
|
|
32
|
+
options;
|
|
33
|
+
providers = new Map();
|
|
34
|
+
actions = new Map();
|
|
35
|
+
importers = new Map();
|
|
36
|
+
disposers = [];
|
|
37
|
+
constructor(artifact, options) {
|
|
38
|
+
this.artifact = artifact;
|
|
39
|
+
this.manifest = artifact.header.manifest;
|
|
40
|
+
this.config = resolveArtifactConfig(artifact.header);
|
|
41
|
+
this.options = {
|
|
42
|
+
host: options.host,
|
|
43
|
+
maxProviders: options.maxProviders ?? 128,
|
|
44
|
+
maxActions: options.maxActions ?? 256,
|
|
45
|
+
maxImporters: options.maxImporters ?? 128,
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
static async load(input, options) {
|
|
49
|
+
const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input instanceof ArrayBuffer ? new Uint8Array(input) : input;
|
|
50
|
+
const artifact = readArtifact(bytes);
|
|
51
|
+
const core = new PluginCore(artifact, options);
|
|
52
|
+
const dispose = await options.host.activate(artifact, core.context());
|
|
53
|
+
if (typeof dispose === 'function')
|
|
54
|
+
core.disposers.push(dispose);
|
|
55
|
+
return core;
|
|
56
|
+
}
|
|
57
|
+
context() {
|
|
58
|
+
const core = this;
|
|
59
|
+
const context = {
|
|
60
|
+
plugin: { id: this.manifest.id, version: this.manifest.version, manifest: this.manifest },
|
|
61
|
+
host: { apiVersion: '2.0.0', libraries: { lodash: 'host', icons: 'host', assets: 'host' }, mode: 'production' },
|
|
62
|
+
modules: { require: (name) => { throw new Error(`Host module ${name} must be supplied by the Host`); } },
|
|
63
|
+
utils: { lodash: {} },
|
|
64
|
+
icons: { list: () => [], url: async () => { throw new Error('Icon service is not connected'); } },
|
|
65
|
+
assets: { list: () => [], url: async () => { throw new Error('Asset service is not connected'); } },
|
|
66
|
+
config: { get: async () => this.config },
|
|
67
|
+
providers: { register: (id, implementation) => this.registerProvider(id, implementation) },
|
|
68
|
+
actions: { register: (id, handler) => this.registerAction(id, handler) },
|
|
69
|
+
playlistImporters: { register: (id, implementation) => this.registerImporter(id, implementation) },
|
|
70
|
+
effects: { add: (dispose) => { this.disposers.push(dispose); } },
|
|
71
|
+
http: {
|
|
72
|
+
request: (request) => this.request(request),
|
|
73
|
+
create: (defaults = {}) => ({
|
|
74
|
+
request: (url, input = {}) => this.request({ ...input, ...defaults, url: new URL(url, defaults.baseURL).href }),
|
|
75
|
+
}),
|
|
76
|
+
},
|
|
77
|
+
permissions: { getGranted: async () => [], query: async () => ({ status: 'prompt' }), request: async () => ({ status: 'prompt' }), requestGroup: async () => ({ status: 'prompt', grants: [] }) },
|
|
78
|
+
playback: { failure: (error) => ({ ok: false, error }) },
|
|
79
|
+
ui: { toast: async (message) => this.options.host.onNotice?.({ type: 'toast', data: message }), notify: async (message) => this.options.host.onNotice?.({ type: 'notify', data: message }) },
|
|
80
|
+
log: { debug: () => undefined, info: () => undefined, warn: () => undefined, error: () => undefined },
|
|
81
|
+
};
|
|
82
|
+
return context;
|
|
83
|
+
}
|
|
84
|
+
registerProvider(id, implementation) {
|
|
85
|
+
if (!declaration(this.manifest, 'providers', id))
|
|
86
|
+
throw new Error(`Provider ${id} is not declared in manifest`);
|
|
87
|
+
if (!this.providers.has(id) && this.providers.size >= this.options.maxProviders)
|
|
88
|
+
throw new Error('Provider limit exceeded');
|
|
89
|
+
this.providers.set(id, implementation);
|
|
90
|
+
return () => this.providers.delete(id);
|
|
91
|
+
}
|
|
92
|
+
registerAction(id, handler) {
|
|
93
|
+
if (!declaration(this.manifest, 'commands', id))
|
|
94
|
+
throw new Error(`Action ${id} is not declared in manifest`);
|
|
95
|
+
if (!this.actions.has(id) && this.actions.size >= this.options.maxActions)
|
|
96
|
+
throw new Error('Action limit exceeded');
|
|
97
|
+
this.actions.set(id, handler);
|
|
98
|
+
return () => this.actions.delete(id);
|
|
99
|
+
}
|
|
100
|
+
registerImporter(id, implementation) {
|
|
101
|
+
if (!declaration(this.manifest, 'playlistImporters', id))
|
|
102
|
+
throw new Error(`Playlist importer ${id} is not declared in manifest`);
|
|
103
|
+
if (!this.importers.has(id) && this.importers.size >= this.options.maxImporters)
|
|
104
|
+
throw new Error('Importer limit exceeded');
|
|
105
|
+
this.importers.set(id, implementation);
|
|
106
|
+
return () => this.importers.delete(id);
|
|
107
|
+
}
|
|
108
|
+
async request(input) {
|
|
109
|
+
if (!this.options.host.request)
|
|
110
|
+
throw new Error('Host HTTP service is not connected');
|
|
111
|
+
return this.options.host.request({ ...input, operation: operationOrDefault(input.operation) });
|
|
112
|
+
}
|
|
113
|
+
async invokeProvider(providerId, method, args = [], operation) {
|
|
114
|
+
const provider = this.providers.get(providerId);
|
|
115
|
+
if (!provider)
|
|
116
|
+
throw new Error(`Provider ${providerId} is not registered`);
|
|
117
|
+
const fn = methodAt(provider, method);
|
|
118
|
+
if (!fn)
|
|
119
|
+
throw new Error(`Provider ${providerId} does not implement ${method}`);
|
|
120
|
+
const result = await fn(...args, operationOrDefault(operation));
|
|
121
|
+
if (method === 'tracks.resolve' || method === 'resolve')
|
|
122
|
+
assertResolveResult(result);
|
|
123
|
+
else if (method === 'tracks.lyrics' || method === 'lyrics')
|
|
124
|
+
assertLyricsDocument(result);
|
|
125
|
+
else if (method.includes('search') || method.endsWith('.list') || method.endsWith('.get') || method === 'categories' || method === 'list')
|
|
126
|
+
assertContentPage(result);
|
|
127
|
+
return result;
|
|
128
|
+
}
|
|
129
|
+
async invokeAction(id, input = {}, operation) {
|
|
130
|
+
const handler = this.actions.get(id);
|
|
131
|
+
if (!handler)
|
|
132
|
+
throw new Error(`Action ${id} is not registered`);
|
|
133
|
+
const result = await handler(input, operationOrDefault(operation));
|
|
134
|
+
return result === undefined ? undefined : JSON.parse(JSON.stringify(result));
|
|
135
|
+
}
|
|
136
|
+
async importPlaylist(id, value, cursor, limit = 100, operation) {
|
|
137
|
+
const importer = this.importers.get(id);
|
|
138
|
+
if (!importer)
|
|
139
|
+
throw new Error(`Playlist importer ${id} is not registered`);
|
|
140
|
+
const result = await importer.getTracks({ value, cursor, limit }, operationOrDefault(operation));
|
|
141
|
+
assertContentPage(result);
|
|
142
|
+
return result;
|
|
143
|
+
}
|
|
144
|
+
async dispose() {
|
|
145
|
+
for (const dispose of this.disposers.splice(0))
|
|
146
|
+
await dispose();
|
|
147
|
+
this.providers.clear();
|
|
148
|
+
this.actions.clear();
|
|
149
|
+
this.importers.clear();
|
|
150
|
+
}
|
|
151
|
+
snapshot() {
|
|
152
|
+
return {
|
|
153
|
+
manifest: this.manifest,
|
|
154
|
+
config: this.config,
|
|
155
|
+
providers: [...this.providers.keys()],
|
|
156
|
+
actions: [...this.actions.keys()],
|
|
157
|
+
importers: [...this.importers.keys()],
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
export function readPluginArtifact(input) {
|
|
162
|
+
const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input instanceof ArrayBuffer ? new Uint8Array(input) : input;
|
|
163
|
+
const artifact = readArtifact(bytes);
|
|
164
|
+
return { header: artifact.header, artifact };
|
|
165
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@shiqianjiang/ceru-plugin-core",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Ceru Music v2 plugin Core runtime and Host adapter boundary",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js",
|
|
12
|
+
"default": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": ["dist", "README.md", "LICENSE"],
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"author": "澜音团队",
|
|
18
|
+
"engines": { "node": ">=22.12.0" },
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@shiqianjiang/ceru-plugin-issuer": "0.2.3",
|
|
21
|
+
"@shiqianjiang/ceru-plugin-sdk": "0.2.3"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
|
|
24
|
+
"repository": {
|
|
25
|
+
"type": "git",
|
|
26
|
+
"url": "git+https://github.com/CeruMusic/CeruMusic-Plugin-Cli.git",
|
|
27
|
+
"directory": "packages/core"
|
|
28
|
+
},
|
|
29
|
+
"keywords": ["ceru-music", "plugin", "core", "electron"]
|
|
30
|
+
}
|