@zhin.js/core 1.1.35 → 1.1.37
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 +79 -193
- package/lib/built/ai-outbound/index.d.ts +0 -1
- package/lib/built/ai-outbound/index.js +0 -1
- package/lib/built/ai-outbound/types.d.ts +0 -9
- package/lib/built/ai-trigger.d.ts +0 -5
- package/lib/built/ai-trigger.js +1 -27
- package/lib/built/common-adapter-tools.d.ts +0 -2
- package/lib/built/common-adapter-tools.js +0 -4
- package/lib/built/html-segment-fallback.d.ts +2 -5
- package/lib/built/html-segment-fallback.js +0 -15
- package/lib/built/interactive-segments/index.d.ts +0 -2
- package/lib/built/interactive-segments/index.js +0 -2
- package/lib/built/interactive-segments/keyboard-segment.d.ts +0 -1
- package/lib/built/interactive-segments/keyboard-segment.js +0 -1
- package/lib/built/interactive-segments/onebot-keyboard.d.ts +0 -1
- package/lib/built/interactive-segments/onebot-keyboard.js +0 -2
- package/lib/built/interactive-segments/resolve.d.ts +0 -1
- package/lib/built/interactive-segments/resolve.js +0 -1
- package/lib/built/interactive-segments/types.d.ts +0 -5
- package/lib/built/login-assist.d.ts +1 -8
- package/lib/built/message-enrich.d.ts +2 -8
- package/lib/built/message-enrich.js +3 -11
- package/lib/built/segment-contract/validate.d.ts +2 -2
- package/lib/built/segment-contract/validate.js +1 -3
- package/lib/built/tool-access.d.ts +5 -0
- package/lib/built/tool-access.js +17 -0
- package/lib/built/user-interaction.js +0 -4
- package/lib/feature/handler.d.ts +1 -5
- package/lib/index.d.ts +4 -45
- package/lib/index.js +3 -39
- package/lib/message.d.ts +1 -2
- package/lib/models/system-log.d.ts +0 -2
- package/lib/models/system-log.js +1 -8
- package/lib/models/user.d.ts +0 -2
- package/lib/models/user.js +1 -7
- package/lib/notice.d.ts +1 -2
- package/lib/plugin-runtime/im/conversation-runtime.d.ts +19 -0
- package/lib/plugin-runtime/im/conversation-runtime.js +312 -0
- package/lib/plugin-runtime/im/endpoint-runtime.d.ts +79 -0
- package/lib/plugin-runtime/im/endpoint-runtime.js +162 -0
- package/lib/plugin-runtime/im/im-runtime.d.ts +13 -106
- package/lib/plugin-runtime/im/im-runtime.js +58 -1061
- package/lib/plugin-runtime/im/inbound-runtime.d.ts +31 -0
- package/lib/plugin-runtime/im/inbound-runtime.js +252 -0
- package/lib/plugin-runtime/im/index.d.ts +4 -2
- package/lib/plugin-runtime/im/index.js +2 -2
- package/lib/plugin-runtime/im/ingress-route.d.ts +10 -0
- package/lib/plugin-runtime/im/ingress-route.js +10 -0
- package/lib/plugin-runtime/im/interaction-runtime.d.ts +23 -0
- package/lib/plugin-runtime/im/interaction-runtime.js +181 -0
- package/lib/plugin-runtime/im/interactive-router.d.ts +17 -0
- package/lib/plugin-runtime/im/interactive-router.js +98 -0
- package/lib/plugin-runtime/im/message-bus.d.ts +3 -3
- package/lib/plugin-runtime/im/message-bus.js +3 -3
- package/lib/plugin-runtime/im/message-events.d.ts +26 -0
- package/lib/plugin-runtime/im/message-events.js +61 -0
- package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +19 -0
- package/lib/plugin-runtime/im/outbound-delivery-runtime.js +165 -0
- package/lib/plugin-runtime/im/outbound-segments.d.ts +2 -3
- package/lib/plugin-runtime/im/outbound-segments.js +3 -4
- package/lib/plugin-runtime/im/runtime-middleware.d.ts +3 -0
- package/lib/plugin-runtime/im/runtime-middleware.js +13 -0
- package/lib/request.d.ts +1 -2
- package/lib/side-event/base.d.ts +1 -2
- package/lib/side-event/normalize.d.ts +1 -5
- package/lib/side-event/normalize.js +1 -11
- package/lib/system-event.d.ts +1 -2
- package/lib/types.d.ts +9 -116
- package/lib/utils.d.ts +51 -24
- package/lib/utils.js +11 -23
- package/package.json +18 -28
- package/lib/adapter.d.ts +0 -145
- package/lib/adapter.js +0 -377
- package/lib/built/adapter-process.d.ts +0 -58
- package/lib/built/adapter-process.js +0 -128
- package/lib/built/agent-preset.d.ts +0 -64
- package/lib/built/agent-preset.js +0 -79
- package/lib/built/ai-outbound/adapter-access.d.ts +0 -3
- package/lib/built/ai-outbound/adapter-access.js +0 -9
- package/lib/built/authorization.d.ts +0 -10
- package/lib/built/authorization.js +0 -76
- package/lib/built/command.d.ts +0 -72
- package/lib/built/command.js +0 -105
- package/lib/built/component.d.ts +0 -67
- package/lib/built/component.js +0 -97
- package/lib/built/config.d.ts +0 -98
- package/lib/built/config.js +0 -372
- package/lib/built/connect-endpoint-instance.d.ts +0 -17
- package/lib/built/connect-endpoint-instance.js +0 -42
- package/lib/built/database.d.ts +0 -68
- package/lib/built/database.js +0 -106
- package/lib/built/dispatcher.d.ts +0 -141
- package/lib/built/dispatcher.js +0 -383
- package/lib/built/endpoint-commands.d.ts +0 -3
- package/lib/built/endpoint-commands.js +0 -99
- package/lib/built/endpoint-lifecycle-service.d.ts +0 -28
- package/lib/built/endpoint-lifecycle-service.js +0 -242
- package/lib/built/endpoint-lifecycle.d.ts +0 -27
- package/lib/built/endpoint-lifecycle.js +0 -36
- package/lib/built/endpoint-manager.d.ts +0 -34
- package/lib/built/endpoint-manager.js +0 -1
- package/lib/built/html-renderer-loader.d.ts +0 -13
- package/lib/built/html-renderer-loader.js +0 -33
- package/lib/built/inbound-pipeline.d.ts +0 -37
- package/lib/built/inbound-pipeline.js +0 -63
- package/lib/built/inbound-runner.d.ts +0 -22
- package/lib/built/inbound-runner.js +0 -34
- package/lib/built/interactive-segment-contract.d.ts +0 -6
- package/lib/built/interactive-segment-contract.js +0 -9
- package/lib/built/interactive-segments/fallback-store.d.ts +0 -29
- package/lib/built/interactive-segments/fallback-store.js +0 -63
- package/lib/built/interactive-segments/handlers.d.ts +0 -16
- package/lib/built/interactive-segments/handlers.js +0 -74
- package/lib/built/introspection-format.d.ts +0 -10
- package/lib/built/introspection-format.js +0 -28
- package/lib/built/management-command-guard.d.ts +0 -15
- package/lib/built/management-command-guard.js +0 -25
- package/lib/built/message-filter.d.ts +0 -176
- package/lib/built/message-filter.js +0 -239
- package/lib/built/optional-peer-import.d.ts +0 -3
- package/lib/built/optional-peer-import.js +0 -33
- package/lib/built/outbound-media-contract.d.ts +0 -22
- package/lib/built/outbound-media-contract.js +0 -10
- package/lib/built/permission.d.ts +0 -51
- package/lib/built/permission.js +0 -99
- package/lib/built/permit-check.d.ts +0 -7
- package/lib/built/permit-check.js +0 -35
- package/lib/built/permit-parse.d.ts +0 -16
- package/lib/built/permit-parse.js +0 -32
- package/lib/built/platform-permit.d.ts +0 -20
- package/lib/built/platform-permit.js +0 -91
- package/lib/built/rich-segments/adapter-policies.d.ts +0 -9
- package/lib/built/rich-segments/adapter-policies.js +0 -27
- package/lib/built/rich-segments/base.d.ts +0 -11
- package/lib/built/rich-segments/base.js +0 -24
- package/lib/built/rich-segments/builtins.d.ts +0 -4
- package/lib/built/rich-segments/builtins.js +0 -40
- package/lib/built/rich-segments/capabilities.d.ts +0 -6
- package/lib/built/rich-segments/capabilities.js +0 -38
- package/lib/built/rich-segments/html-segment.d.ts +0 -15
- package/lib/built/rich-segments/html-segment.js +0 -62
- package/lib/built/rich-segments/index.d.ts +0 -13
- package/lib/built/rich-segments/index.js +0 -13
- package/lib/built/rich-segments/markdown-segment.d.ts +0 -14
- package/lib/built/rich-segments/markdown-segment.js +0 -58
- package/lib/built/rich-segments/qrcode-segment.d.ts +0 -18
- package/lib/built/rich-segments/qrcode-segment.js +0 -73
- package/lib/built/rich-segments/registry.d.ts +0 -16
- package/lib/built/rich-segments/registry.js +0 -52
- package/lib/built/rich-segments/resolve.d.ts +0 -5
- package/lib/built/rich-segments/resolve.js +0 -87
- package/lib/built/rich-segments/tts-segment.d.ts +0 -13
- package/lib/built/rich-segments/tts-segment.js +0 -51
- package/lib/built/rich-segments/types.d.ts +0 -79
- package/lib/built/rich-segments/types.js +0 -17
- package/lib/built/runtime-io.d.ts +0 -9
- package/lib/built/runtime-io.js +0 -67
- package/lib/built/schedule.d.ts +0 -54
- package/lib/built/schedule.js +0 -112
- package/lib/built/schema-endpoint-manager.d.ts +0 -17
- package/lib/built/schema-endpoint-manager.js +0 -73
- package/lib/built/schema-feature.d.ts +0 -77
- package/lib/built/schema-feature.js +0 -130
- package/lib/built/skill.d.ts +0 -120
- package/lib/built/skill.js +0 -151
- package/lib/built/speech-loader.d.ts +0 -14
- package/lib/built/speech-loader.js +0 -32
- package/lib/built/tool.d.ts +0 -151
- package/lib/built/tool.js +0 -388
- package/lib/command.d.ts +0 -50
- package/lib/command.js +0 -106
- package/lib/endpoint-capabilities.d.ts +0 -46
- package/lib/endpoint-capabilities.js +0 -55
- package/lib/endpoint.d.ts +0 -19
- package/lib/endpoint.js +0 -3
- package/lib/host-plugin-registry.d.ts +0 -8
- package/lib/host-plugin-registry.js +0 -12
- package/lib/plugin-context.d.ts +0 -27
- package/lib/plugin-context.js +0 -64
- package/lib/plugin-runtime/im/interactive.d.ts +0 -26
- package/lib/plugin-runtime/im/interactive.js +0 -46
- package/lib/plugin-runtime/im/service-tokens.d.ts +0 -18
- package/lib/plugin-runtime/im/service-tokens.js +0 -13
- package/lib/plugin.d.ts +0 -268
- package/lib/plugin.js +0 -583
- package/lib/schema-interaction.d.ts +0 -117
- package/lib/schema-interaction.js +0 -247
- package/lib/tool-zod.d.ts +0 -43
- package/lib/tool-zod.js +0 -184
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
import { createWarnOnce, resetWarnOnceForTests } from '@zhin.js/logger';
|
|
2
|
-
import { importOptionalPeerPackage } from './optional-peer-import.js';
|
|
3
|
-
/** 动态 import 时使用的包名(与 @zhin.js/speech package.json 一致) */
|
|
4
|
-
export const SPEECH_PACKAGE = '@zhin.js/speech';
|
|
5
|
-
let cached;
|
|
6
|
-
const speechPeerWarnOnce = createWarnOnce('speech');
|
|
7
|
-
/** zhin 启动时已创建 pipeline 时注入 */
|
|
8
|
-
export function seedSpeechPipeline(pipeline) {
|
|
9
|
-
cached = pipeline;
|
|
10
|
-
}
|
|
11
|
-
/** 动态加载 @zhin.js/speech;未安装时 warn 一次并返回 undefined */
|
|
12
|
-
export async function loadSpeechPipeline(opts) {
|
|
13
|
-
if (cached !== undefined) {
|
|
14
|
-
return cached ?? undefined;
|
|
15
|
-
}
|
|
16
|
-
try {
|
|
17
|
-
const mod = await importOptionalPeerPackage(SPEECH_PACKAGE);
|
|
18
|
-
const speechConfig = opts?.getConfig?.()?.speech;
|
|
19
|
-
cached = mod.createSpeechPipeline(speechConfig);
|
|
20
|
-
return cached;
|
|
21
|
-
}
|
|
22
|
-
catch {
|
|
23
|
-
speechPeerWarnOnce(opts?.warn, `未安装 ${SPEECH_PACKAGE},STT/TTS 已降级。安装: pnpm add ${SPEECH_PACKAGE}`);
|
|
24
|
-
cached = null;
|
|
25
|
-
return undefined;
|
|
26
|
-
}
|
|
27
|
-
}
|
|
28
|
-
/** 测试用:重置加载缓存 */
|
|
29
|
-
export function resetSpeechLoaderForTests() {
|
|
30
|
-
cached = undefined;
|
|
31
|
-
resetWarnOnceForTests('speech');
|
|
32
|
-
}
|
package/lib/built/tool.d.ts
DELETED
|
@@ -1,151 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* ToolFeature — 统一的工具管理服务
|
|
3
|
-
* 工具仅面向 AI(通过 MCP 注册),不再与 Command 互转
|
|
4
|
-
*/
|
|
5
|
-
import { Feature, FeatureJSON } from "@zhin.js/kernel";
|
|
6
|
-
import type { Tool, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolScope } from "../types.js";
|
|
7
|
-
import type { Message } from "../message.js";
|
|
8
|
-
import { type PermissionHost } from '@zhin.js/permission';
|
|
9
|
-
/**
|
|
10
|
-
* 检查工具是否可被当前 Message 通讯上下文访问。
|
|
11
|
-
* `host` 为 PermissionHost 实例;无 host 且有 permissions → deny。
|
|
12
|
-
*/
|
|
13
|
-
export declare function canAccessTool(tool: Tool, message?: Message<any>, host?: PermissionHost | null): Promise<boolean>;
|
|
14
|
-
/**
|
|
15
|
-
* 从参数定义中提取参数信息
|
|
16
|
-
*/
|
|
17
|
-
export declare function extractParamInfo(parameters: ToolJsonSchema): Tool.ParamInfo[];
|
|
18
|
-
/**
|
|
19
|
-
* 定义工具的辅助函数(提供类型推断)
|
|
20
|
-
*/
|
|
21
|
-
export declare function defineTool<TArgs extends Record<string, any> = Record<string, any>>(tool: Tool<TArgs>): Tool;
|
|
22
|
-
/**
|
|
23
|
-
* 参数定义(带顺序)
|
|
24
|
-
*/
|
|
25
|
-
interface ParamDef {
|
|
26
|
-
name: string;
|
|
27
|
-
schema: PropertySchema;
|
|
28
|
-
required: boolean;
|
|
29
|
-
}
|
|
30
|
-
/**
|
|
31
|
-
* ZhinTool 类
|
|
32
|
-
* 提供链式调用风格来定义工具
|
|
33
|
-
*/
|
|
34
|
-
export declare class ZhinTool {
|
|
35
|
-
#private;
|
|
36
|
-
constructor(name: string);
|
|
37
|
-
get name(): string;
|
|
38
|
-
get description(): string;
|
|
39
|
-
get params(): ParamDef[];
|
|
40
|
-
desc(description: string): this;
|
|
41
|
-
param(name: string, schema: PropertySchema, required?: boolean): this;
|
|
42
|
-
platform(...platforms: string[]): this;
|
|
43
|
-
scope(...scopes: ToolScope[]): this;
|
|
44
|
-
permit(...permissions: string[]): this;
|
|
45
|
-
tag(...tags: string[]): this;
|
|
46
|
-
keyword(...keywords: string[]): this;
|
|
47
|
-
hidden(value?: boolean): this;
|
|
48
|
-
/**
|
|
49
|
-
* 标记此工具允许被预执行(opt-in)。
|
|
50
|
-
* 仅适用于无副作用的只读工具(如获取系统状态、读取配置等)。
|
|
51
|
-
* 默认为 false,即不预执行。
|
|
52
|
-
*/
|
|
53
|
-
preExec(value?: boolean): this;
|
|
54
|
-
/** 设置工具分类(如 file / shell / web),用于展示与 TOOLS.md 协同 */
|
|
55
|
-
kind(value: string): this;
|
|
56
|
-
execute(callback: (args: Record<string, any>, message?: Message<any>) => MaybePromise<any>): this;
|
|
57
|
-
toTool(): Tool;
|
|
58
|
-
toJSON(): {
|
|
59
|
-
name: string;
|
|
60
|
-
description: string;
|
|
61
|
-
parameters: ToolParametersSchema;
|
|
62
|
-
platforms?: string[];
|
|
63
|
-
scopes?: ToolScope[];
|
|
64
|
-
permissions?: string[];
|
|
65
|
-
tags?: string[];
|
|
66
|
-
};
|
|
67
|
-
get help(): string;
|
|
68
|
-
toString(): string;
|
|
69
|
-
}
|
|
70
|
-
export declare function isZhinTool(obj: any): obj is ZhinTool;
|
|
71
|
-
/**
|
|
72
|
-
* 工具输入类型(支持 Tool 对象或 ZhinTool 实例)
|
|
73
|
-
*/
|
|
74
|
-
export type ToolInput = Tool | ZhinTool;
|
|
75
|
-
/**
|
|
76
|
-
* Message 工具扩展方法类型
|
|
77
|
-
*/
|
|
78
|
-
export interface MessageToolExtensions {
|
|
79
|
-
/** 添加工具 */
|
|
80
|
-
addTool(tool: ToolInput): () => void;
|
|
81
|
-
}
|
|
82
|
-
declare module "../plugin.js" {
|
|
83
|
-
namespace Plugin {
|
|
84
|
-
interface Extensions extends MessageToolExtensions {
|
|
85
|
-
}
|
|
86
|
-
interface Contexts {
|
|
87
|
-
tool: ToolFeature;
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
export declare class ToolFeature extends Feature<Tool> {
|
|
92
|
-
#private;
|
|
93
|
-
readonly name: "tool";
|
|
94
|
-
readonly icon = "Wrench";
|
|
95
|
-
readonly desc = "\u5DE5\u5177";
|
|
96
|
-
/** 按名称索引 */
|
|
97
|
-
readonly byName: Map<string, Tool<Record<string, any>>>;
|
|
98
|
-
/**
|
|
99
|
-
* 添加工具(仅注册到 ToolFeature,不再生成 Command)
|
|
100
|
-
* @param toolInput 工具或 ZhinTool 实例
|
|
101
|
-
* @param pluginName 注册插件名
|
|
102
|
-
*/
|
|
103
|
-
addTool(toolInput: ToolInput, pluginName: string): () => void;
|
|
104
|
-
/**
|
|
105
|
-
* 移除工具
|
|
106
|
-
*/
|
|
107
|
-
removeTool(name: string): boolean;
|
|
108
|
-
/**
|
|
109
|
-
* 获取工具
|
|
110
|
-
*/
|
|
111
|
-
get(name: string): Tool | undefined;
|
|
112
|
-
/**
|
|
113
|
-
* 获取所有工具
|
|
114
|
-
*/
|
|
115
|
-
getAll(): Tool[];
|
|
116
|
-
/**
|
|
117
|
-
* 根据标签过滤工具
|
|
118
|
-
*/
|
|
119
|
-
getByTags(tags: string[]): Tool[];
|
|
120
|
-
/**
|
|
121
|
-
* 执行工具
|
|
122
|
-
*/
|
|
123
|
-
execute(name: string, args: Record<string, any>, message?: Message<any>): Promise<any>;
|
|
124
|
-
/**
|
|
125
|
-
* 根据 Message 通讯上下文过滤工具
|
|
126
|
-
*/
|
|
127
|
-
filterByContext(tools: Tool[], message?: Message<any>, host?: PermissionHost | null): Promise<Tool[]>;
|
|
128
|
-
/**
|
|
129
|
-
* 按插件名获取工具
|
|
130
|
-
*/
|
|
131
|
-
getToolsByPlugin(pluginName: string): Tool[];
|
|
132
|
-
/**
|
|
133
|
-
* 生命周期: 销毁时清理所有工具
|
|
134
|
-
*/
|
|
135
|
-
dispose(): void;
|
|
136
|
-
/**
|
|
137
|
-
* 兼容旧接口:tools Map
|
|
138
|
-
*/
|
|
139
|
-
get tools(): Map<string, Tool>;
|
|
140
|
-
/**
|
|
141
|
-
* 序列化为 JSON
|
|
142
|
-
*/
|
|
143
|
-
toJSON(pluginName?: string): FeatureJSON;
|
|
144
|
-
/**
|
|
145
|
-
* 提供给 Plugin.prototype 的扩展方法
|
|
146
|
-
*/
|
|
147
|
-
get extensions(): {
|
|
148
|
-
addTool(tool: ToolInput): () => void;
|
|
149
|
-
};
|
|
150
|
-
}
|
|
151
|
-
export {};
|
package/lib/built/tool.js
DELETED
|
@@ -1,388 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* ToolFeature — 统一的工具管理服务
|
|
3
|
-
* 工具仅面向 AI(通过 MCP 注册),不再与 Command 互转
|
|
4
|
-
*/
|
|
5
|
-
import { Feature } from "@zhin.js/kernel";
|
|
6
|
-
import { toPermissionSubject } from '@zhin.js/permission';
|
|
7
|
-
/**
|
|
8
|
-
* 检查工具是否可被当前 Message 通讯上下文访问。
|
|
9
|
-
* `host` 为 PermissionHost 实例;无 host 且有 permissions → deny。
|
|
10
|
-
*/
|
|
11
|
-
export async function canAccessTool(tool, message, host) {
|
|
12
|
-
if (!message)
|
|
13
|
-
return !tool.platforms?.length && !tool.scopes?.length && !tool.permissions?.length;
|
|
14
|
-
const adapter = String(message.$adapter);
|
|
15
|
-
const scope = (message.$channel?.type || 'private');
|
|
16
|
-
if (tool.platforms?.length && !tool.platforms.includes(adapter)) {
|
|
17
|
-
return false;
|
|
18
|
-
}
|
|
19
|
-
if (tool.scopes?.length && !tool.scopes.includes(scope)) {
|
|
20
|
-
return false;
|
|
21
|
-
}
|
|
22
|
-
if (!tool.permissions?.length)
|
|
23
|
-
return true;
|
|
24
|
-
if (!host)
|
|
25
|
-
return false;
|
|
26
|
-
const subject = toPermissionSubject(message);
|
|
27
|
-
return host.checkAll(tool.permissions, subject);
|
|
28
|
-
}
|
|
29
|
-
// ============================================================================
|
|
30
|
-
// Tool 工具函数
|
|
31
|
-
// ============================================================================
|
|
32
|
-
/**
|
|
33
|
-
* 从参数定义中提取参数信息
|
|
34
|
-
*/
|
|
35
|
-
export function extractParamInfo(parameters) {
|
|
36
|
-
if (!parameters.properties)
|
|
37
|
-
return [];
|
|
38
|
-
const required = parameters.required || [];
|
|
39
|
-
return Object.entries(parameters.properties).map(([name, schema]) => ({
|
|
40
|
-
name,
|
|
41
|
-
type: schema.type,
|
|
42
|
-
required: required.includes(name),
|
|
43
|
-
description: schema.description,
|
|
44
|
-
default: schema.default,
|
|
45
|
-
enum: schema.enum,
|
|
46
|
-
}));
|
|
47
|
-
}
|
|
48
|
-
/**
|
|
49
|
-
* 定义工具的辅助函数(提供类型推断)
|
|
50
|
-
*/
|
|
51
|
-
export function defineTool(tool) {
|
|
52
|
-
return tool;
|
|
53
|
-
}
|
|
54
|
-
/**
|
|
55
|
-
* ZhinTool 类
|
|
56
|
-
* 提供链式调用风格来定义工具
|
|
57
|
-
*/
|
|
58
|
-
export class ZhinTool {
|
|
59
|
-
#name;
|
|
60
|
-
#description = '';
|
|
61
|
-
/** 有序的参数列表 */
|
|
62
|
-
#params = [];
|
|
63
|
-
#execute;
|
|
64
|
-
#platforms = [];
|
|
65
|
-
#scopes = [];
|
|
66
|
-
#permissions = [];
|
|
67
|
-
#tags = [];
|
|
68
|
-
#keywords = [];
|
|
69
|
-
#hidden = false;
|
|
70
|
-
#source;
|
|
71
|
-
#preExecutable = false;
|
|
72
|
-
#kind;
|
|
73
|
-
constructor(name) {
|
|
74
|
-
this.#name = name;
|
|
75
|
-
}
|
|
76
|
-
get name() {
|
|
77
|
-
return this.#name;
|
|
78
|
-
}
|
|
79
|
-
get description() {
|
|
80
|
-
return this.#description;
|
|
81
|
-
}
|
|
82
|
-
get params() {
|
|
83
|
-
return [...this.#params];
|
|
84
|
-
}
|
|
85
|
-
desc(description) {
|
|
86
|
-
this.#description = description;
|
|
87
|
-
return this;
|
|
88
|
-
}
|
|
89
|
-
param(name, schema, required = false) {
|
|
90
|
-
const existingIndex = this.#params.findIndex(p => p.name === name);
|
|
91
|
-
if (existingIndex >= 0) {
|
|
92
|
-
this.#params[existingIndex] = { name, schema, required };
|
|
93
|
-
}
|
|
94
|
-
else {
|
|
95
|
-
this.#params.push({ name, schema, required });
|
|
96
|
-
}
|
|
97
|
-
return this;
|
|
98
|
-
}
|
|
99
|
-
platform(...platforms) {
|
|
100
|
-
this.#platforms.push(...platforms);
|
|
101
|
-
return this;
|
|
102
|
-
}
|
|
103
|
-
scope(...scopes) {
|
|
104
|
-
this.#scopes.push(...scopes);
|
|
105
|
-
return this;
|
|
106
|
-
}
|
|
107
|
-
permit(...permissions) {
|
|
108
|
-
this.#permissions.push(...permissions);
|
|
109
|
-
return this;
|
|
110
|
-
}
|
|
111
|
-
tag(...tags) {
|
|
112
|
-
this.#tags.push(...tags);
|
|
113
|
-
return this;
|
|
114
|
-
}
|
|
115
|
-
keyword(...keywords) {
|
|
116
|
-
this.#keywords.push(...keywords);
|
|
117
|
-
return this;
|
|
118
|
-
}
|
|
119
|
-
hidden(value = true) {
|
|
120
|
-
this.#hidden = value;
|
|
121
|
-
return this;
|
|
122
|
-
}
|
|
123
|
-
/**
|
|
124
|
-
* 标记此工具允许被预执行(opt-in)。
|
|
125
|
-
* 仅适用于无副作用的只读工具(如获取系统状态、读取配置等)。
|
|
126
|
-
* 默认为 false,即不预执行。
|
|
127
|
-
*/
|
|
128
|
-
preExec(value = true) {
|
|
129
|
-
this.#preExecutable = value;
|
|
130
|
-
return this;
|
|
131
|
-
}
|
|
132
|
-
/** 设置工具分类(如 file / shell / web),用于展示与 TOOLS.md 协同 */
|
|
133
|
-
kind(value) {
|
|
134
|
-
this.#kind = value;
|
|
135
|
-
return this;
|
|
136
|
-
}
|
|
137
|
-
execute(callback) {
|
|
138
|
-
this.#execute = callback;
|
|
139
|
-
return this;
|
|
140
|
-
}
|
|
141
|
-
#buildParameters() {
|
|
142
|
-
const properties = {};
|
|
143
|
-
const required = [];
|
|
144
|
-
const sortedParams = [...this.#params].sort((a, b) => {
|
|
145
|
-
if (a.required && !b.required)
|
|
146
|
-
return -1;
|
|
147
|
-
if (!a.required && b.required)
|
|
148
|
-
return 1;
|
|
149
|
-
return 0;
|
|
150
|
-
});
|
|
151
|
-
for (const param of sortedParams) {
|
|
152
|
-
properties[param.name] = param.schema;
|
|
153
|
-
if (param.required) {
|
|
154
|
-
required.push(param.name);
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
return {
|
|
158
|
-
type: 'object',
|
|
159
|
-
properties,
|
|
160
|
-
required: required.length > 0 ? required : undefined,
|
|
161
|
-
};
|
|
162
|
-
}
|
|
163
|
-
toTool() {
|
|
164
|
-
if (!this.#execute) {
|
|
165
|
-
throw new Error(`Tool "${this.#name}" has no execute() defined`);
|
|
166
|
-
}
|
|
167
|
-
const tool = {
|
|
168
|
-
name: this.#name,
|
|
169
|
-
description: this.#description,
|
|
170
|
-
parameters: this.#buildParameters(),
|
|
171
|
-
execute: this.#execute,
|
|
172
|
-
};
|
|
173
|
-
if (this.#platforms.length > 0)
|
|
174
|
-
tool.platforms = this.#platforms;
|
|
175
|
-
if (this.#scopes.length > 0)
|
|
176
|
-
tool.scopes = this.#scopes;
|
|
177
|
-
if (this.#permissions.length > 0)
|
|
178
|
-
tool.permissions = this.#permissions;
|
|
179
|
-
if (this.#tags.length > 0)
|
|
180
|
-
tool.tags = this.#tags;
|
|
181
|
-
if (this.#hidden)
|
|
182
|
-
tool.hidden = this.#hidden;
|
|
183
|
-
if (this.#source)
|
|
184
|
-
tool.source = this.#source;
|
|
185
|
-
if (this.#keywords.length > 0)
|
|
186
|
-
tool.keywords = this.#keywords;
|
|
187
|
-
if (this.#preExecutable)
|
|
188
|
-
tool.preExecutable = true;
|
|
189
|
-
if (this.#kind)
|
|
190
|
-
tool.kind = this.#kind;
|
|
191
|
-
return tool;
|
|
192
|
-
}
|
|
193
|
-
toJSON() {
|
|
194
|
-
const json = {
|
|
195
|
-
name: this.#name,
|
|
196
|
-
description: this.#description,
|
|
197
|
-
parameters: this.#buildParameters(),
|
|
198
|
-
};
|
|
199
|
-
if (this.#platforms.length > 0)
|
|
200
|
-
json.platforms = this.#platforms;
|
|
201
|
-
if (this.#scopes.length > 0)
|
|
202
|
-
json.scopes = this.#scopes;
|
|
203
|
-
if (this.#permissions.length > 0)
|
|
204
|
-
json.permissions = [...this.#permissions];
|
|
205
|
-
if (this.#tags.length > 0)
|
|
206
|
-
json.tags = this.#tags;
|
|
207
|
-
return json;
|
|
208
|
-
}
|
|
209
|
-
get help() {
|
|
210
|
-
const lines = [this.#name];
|
|
211
|
-
if (this.#description)
|
|
212
|
-
lines.push(` ${this.#description}`);
|
|
213
|
-
if (this.#params.length > 0) {
|
|
214
|
-
lines.push(' 参数:');
|
|
215
|
-
for (const param of this.#params) {
|
|
216
|
-
const required = param.required ? '(必填)' : '(可选)';
|
|
217
|
-
const desc = param.schema.description || '';
|
|
218
|
-
lines.push(` ${param.name}: ${param.schema.type} ${required} ${desc}`);
|
|
219
|
-
}
|
|
220
|
-
}
|
|
221
|
-
if (this.#permissions.length > 0) {
|
|
222
|
-
lines.push(` 权限: ${this.#permissions.join(', ')}`);
|
|
223
|
-
}
|
|
224
|
-
if (this.#platforms.length > 0) {
|
|
225
|
-
lines.push(` 平台: ${this.#platforms.join(', ')}`);
|
|
226
|
-
}
|
|
227
|
-
if (this.#scopes.length > 0) {
|
|
228
|
-
lines.push(` 场景: ${this.#scopes.join(', ')}`);
|
|
229
|
-
}
|
|
230
|
-
return lines.join('\n');
|
|
231
|
-
}
|
|
232
|
-
toString() {
|
|
233
|
-
return `[ZhinTool: ${this.#name}] ${this.#description}`;
|
|
234
|
-
}
|
|
235
|
-
}
|
|
236
|
-
export function isZhinTool(obj) {
|
|
237
|
-
return obj instanceof ZhinTool;
|
|
238
|
-
}
|
|
239
|
-
// ============================================================================
|
|
240
|
-
// ToolFeature 实现
|
|
241
|
-
// ============================================================================
|
|
242
|
-
export class ToolFeature extends Feature {
|
|
243
|
-
name = 'tool';
|
|
244
|
-
icon = 'Wrench';
|
|
245
|
-
desc = '工具';
|
|
246
|
-
/** 按名称索引 */
|
|
247
|
-
byName = new Map();
|
|
248
|
-
/** 工具到插件名的映射 */
|
|
249
|
-
#toolPluginMap = new Map();
|
|
250
|
-
/**
|
|
251
|
-
* 添加工具(仅注册到 ToolFeature,不再生成 Command)
|
|
252
|
-
* @param toolInput 工具或 ZhinTool 实例
|
|
253
|
-
* @param pluginName 注册插件名
|
|
254
|
-
*/
|
|
255
|
-
addTool(toolInput, pluginName) {
|
|
256
|
-
const zhinTool = isZhinTool(toolInput) ? toolInput : null;
|
|
257
|
-
const tool = zhinTool ? zhinTool.toTool() : toolInput;
|
|
258
|
-
// Re-register (e.g. adapter hot-reload) must not leave duplicate entries in items[]
|
|
259
|
-
if (this.byName.has(tool.name)) {
|
|
260
|
-
this.removeTool(tool.name);
|
|
261
|
-
}
|
|
262
|
-
const toolWithSource = {
|
|
263
|
-
...tool,
|
|
264
|
-
source: tool.source || `plugin:${pluginName}`,
|
|
265
|
-
tags: [...(tool.tags || []), 'plugin', pluginName],
|
|
266
|
-
};
|
|
267
|
-
this.byName.set(tool.name, toolWithSource);
|
|
268
|
-
this.#toolPluginMap.set(tool.name, pluginName);
|
|
269
|
-
// Use Feature.add for item tracking
|
|
270
|
-
const baseDispose = super.add(toolWithSource, pluginName);
|
|
271
|
-
return () => {
|
|
272
|
-
this.removeTool(tool.name);
|
|
273
|
-
baseDispose();
|
|
274
|
-
};
|
|
275
|
-
}
|
|
276
|
-
/**
|
|
277
|
-
* 移除工具
|
|
278
|
-
*/
|
|
279
|
-
removeTool(name) {
|
|
280
|
-
const tool = this.byName.get(name);
|
|
281
|
-
if (!tool)
|
|
282
|
-
return false;
|
|
283
|
-
this.byName.delete(name);
|
|
284
|
-
this.#toolPluginMap.delete(name);
|
|
285
|
-
// 移除 item
|
|
286
|
-
super.remove(tool);
|
|
287
|
-
return true;
|
|
288
|
-
}
|
|
289
|
-
/**
|
|
290
|
-
* 获取工具
|
|
291
|
-
*/
|
|
292
|
-
get(name) {
|
|
293
|
-
return this.byName.get(name);
|
|
294
|
-
}
|
|
295
|
-
/**
|
|
296
|
-
* 获取所有工具
|
|
297
|
-
*/
|
|
298
|
-
getAll() {
|
|
299
|
-
return [...this.items];
|
|
300
|
-
}
|
|
301
|
-
/**
|
|
302
|
-
* 根据标签过滤工具
|
|
303
|
-
*/
|
|
304
|
-
getByTags(tags) {
|
|
305
|
-
return this.items.filter(tool => tags.some(tag => tool.tags?.includes(tag)));
|
|
306
|
-
}
|
|
307
|
-
/**
|
|
308
|
-
* 执行工具
|
|
309
|
-
*/
|
|
310
|
-
async execute(name, args, message) {
|
|
311
|
-
const tool = this.byName.get(name);
|
|
312
|
-
if (!tool) {
|
|
313
|
-
throw new Error(`Tool "${name}" not found`);
|
|
314
|
-
}
|
|
315
|
-
return tool.execute(args, message);
|
|
316
|
-
}
|
|
317
|
-
/**
|
|
318
|
-
* 根据 Message 通讯上下文过滤工具
|
|
319
|
-
*/
|
|
320
|
-
async filterByContext(tools, message, host) {
|
|
321
|
-
const results = await Promise.all(tools.map(async (tool) => ({
|
|
322
|
-
tool,
|
|
323
|
-
allowed: await canAccessTool(tool, message, host),
|
|
324
|
-
})));
|
|
325
|
-
return results.filter((r) => r.allowed).map((r) => r.tool);
|
|
326
|
-
}
|
|
327
|
-
/**
|
|
328
|
-
* 按插件名获取工具
|
|
329
|
-
*/
|
|
330
|
-
getToolsByPlugin(pluginName) {
|
|
331
|
-
const result = [];
|
|
332
|
-
for (const [toolName, pName] of this.#toolPluginMap) {
|
|
333
|
-
if (pName === pluginName) {
|
|
334
|
-
const tool = this.byName.get(toolName);
|
|
335
|
-
if (tool)
|
|
336
|
-
result.push(tool);
|
|
337
|
-
}
|
|
338
|
-
}
|
|
339
|
-
return result;
|
|
340
|
-
}
|
|
341
|
-
/**
|
|
342
|
-
* 生命周期: 销毁时清理所有工具
|
|
343
|
-
*/
|
|
344
|
-
dispose() {
|
|
345
|
-
this.byName.clear();
|
|
346
|
-
this.#toolPluginMap.clear();
|
|
347
|
-
}
|
|
348
|
-
/**
|
|
349
|
-
* 兼容旧接口:tools Map
|
|
350
|
-
*/
|
|
351
|
-
get tools() {
|
|
352
|
-
return this.byName;
|
|
353
|
-
}
|
|
354
|
-
/**
|
|
355
|
-
* 序列化为 JSON
|
|
356
|
-
*/
|
|
357
|
-
toJSON(pluginName) {
|
|
358
|
-
const list = pluginName ? this.getByPlugin(pluginName) : this.items;
|
|
359
|
-
return {
|
|
360
|
-
name: this.name,
|
|
361
|
-
icon: this.icon,
|
|
362
|
-
desc: this.desc,
|
|
363
|
-
count: list.length,
|
|
364
|
-
items: list.map(t => ({
|
|
365
|
-
name: t.name,
|
|
366
|
-
desc: t.description,
|
|
367
|
-
platforms: t.platforms,
|
|
368
|
-
tags: t.tags,
|
|
369
|
-
})),
|
|
370
|
-
};
|
|
371
|
-
}
|
|
372
|
-
/**
|
|
373
|
-
* 提供给 Plugin.prototype 的扩展方法
|
|
374
|
-
*/
|
|
375
|
-
get extensions() {
|
|
376
|
-
const feature = this;
|
|
377
|
-
return {
|
|
378
|
-
addTool(tool) {
|
|
379
|
-
const plugin = this;
|
|
380
|
-
const toolObj = isZhinTool(tool) ? tool.toTool() : tool;
|
|
381
|
-
const dispose = feature.addTool(tool, plugin.name);
|
|
382
|
-
plugin.recordFeatureContribution(feature.name, toolObj.name);
|
|
383
|
-
plugin.onDispose(dispose);
|
|
384
|
-
return dispose;
|
|
385
|
-
},
|
|
386
|
-
};
|
|
387
|
-
}
|
|
388
|
-
}
|
package/lib/command.d.ts
DELETED
|
@@ -1,50 +0,0 @@
|
|
|
1
|
-
import { MatchResult, SegmentMatcher } from 'segment-matcher';
|
|
2
|
-
import { AdapterMessage, SendContent, RegisteredAdapter, MaybePromise } from './types.js';
|
|
3
|
-
import type { Message } from './message.js';
|
|
4
|
-
import { type PermissionHost } from '@zhin.js/permission';
|
|
5
|
-
type ConstructFirstParam<T extends new (...args: any[]) => any> = T extends new (...args: [infer U, ...any[]]) => any ? U : never;
|
|
6
|
-
type ConstructSecondParam<T extends new (...args: any[]) => any> = T extends new (...args: [any, infer V, ...any[]]) => any ? V : never;
|
|
7
|
-
/**
|
|
8
|
-
* MessageCommand类:经典命令系统(segment-matcher)。
|
|
9
|
-
*
|
|
10
|
-
* @deprecated 新插件请用 `defineCommand`(`zhin.js/command`)+ `commands/` 约定目录。
|
|
11
|
-
* 本类仍供 Agent init / game-kit hub / legacy `CommandFeature` 使用;计划随经典
|
|
12
|
-
* Plugin 路径一并退役。见 `docs/contributing/public-api-surface.md`。
|
|
13
|
-
*/
|
|
14
|
-
export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdapter> extends SegmentMatcher {
|
|
15
|
-
#private;
|
|
16
|
-
get helpInfo(): MessageCommand.HelpInfo;
|
|
17
|
-
constructor(C: ConstructFirstParam<typeof SegmentMatcher>, P?: ConstructSecondParam<typeof SegmentMatcher>);
|
|
18
|
-
get help(): string;
|
|
19
|
-
desc(...desc: string[]): MessageCommand<T>;
|
|
20
|
-
usage(...usage: string[]): MessageCommand<T>;
|
|
21
|
-
examples(...examples: string[]): MessageCommand<T>;
|
|
22
|
-
/**
|
|
23
|
-
* 注册命令回调
|
|
24
|
-
* @param callback 命令处理函数
|
|
25
|
-
*/
|
|
26
|
-
action(callback: MessageCommand.Callback<T>): MessageCommand<T>;
|
|
27
|
-
permit(...permissions: string[]): MessageCommand<T>;
|
|
28
|
-
/** 命令要求的 permit 列表(空表示所有人可用) */
|
|
29
|
-
get requiredPermits(): readonly string[];
|
|
30
|
-
/** 与 handle 一致的 permit 校验,供帮助菜单等场景过滤不可见命令 */
|
|
31
|
-
checkPermits(message: Message<AdapterMessage<T>>, host: PermissionHost | null): Promise<boolean>;
|
|
32
|
-
/**
|
|
33
|
-
* 处理消息,自动匹配命令并执行回调
|
|
34
|
-
* @param message 消息对象
|
|
35
|
-
* @param host PermissionHost(null 时有 permit 的命令 fail-closed)
|
|
36
|
-
* @returns 命令返回内容或undefined
|
|
37
|
-
*/
|
|
38
|
-
handle(message: Message<AdapterMessage<T>>, host: PermissionHost | null): Promise<SendContent | undefined>;
|
|
39
|
-
}
|
|
40
|
-
export declare namespace MessageCommand {
|
|
41
|
-
type Callback<T extends RegisteredAdapter> = (message: Message<AdapterMessage<T>>, result: MatchResult) => SendContent | undefined | Promise<SendContent | undefined>;
|
|
42
|
-
type Checker<T extends RegisteredAdapter> = (message: Message<AdapterMessage<T>>) => MaybePromise<boolean>;
|
|
43
|
-
type HelpInfo = {
|
|
44
|
-
pattern: string;
|
|
45
|
-
desc: string[];
|
|
46
|
-
usage: string[];
|
|
47
|
-
examples: string[];
|
|
48
|
-
};
|
|
49
|
-
}
|
|
50
|
-
export {};
|