@ai-setting/roy-agent-core 1.5.5 → 1.5.7

package/dist/env/skill/tool/index.d.ts

@@ -0,0 +1,193 @@
+import { z, ZodType, ZodError } from "zod";
+/**
+* 沙箱配置
+*/
+interface SandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱类型 */
+	type: "native" | "docker";
+	/** 动作过滤 */
+	actionFilter?: {
+		/** 包含的动作 */
+		include?: string[];
+		/** 排除的动作 */
+		exclude?: string[];
+	};
+	/** 文件系统限制 */
+	filesystem?: {
+		/** 允许读取 */
+		allowRead?: string[];
+		/** 禁止读取 */
+		denyRead?: string[];
+		/** 允许写入 */
+		allowWrite?: string[];
+		/** 禁止写入 */
+		denyWrite?: string[];
+	};
+	/** 网络限制 */
+	network?: {
+		/** 允许的域名 */
+		allowedDomains?: string[];
+		/** 禁止的域名 */
+		deniedDomains?: string[];
+	};
+	/** Docker 配置 */
+	docker?: {
+		/** 镜像 */
+		image?: string;
+		/** 网络模式 */
+		networkMode?: "bridge" | "host" | "none";
+		/** 卷挂载 */
+		volumes?: Record<string, string>;
+	};
+}
+/**
+* 工具执行上下文
+*/
+interface ToolContext {
+	/** 工作目录 */
+	workdir?: string;
+	/** 用户 ID */
+	user_id?: string;
+	/** 会话 ID */
+	session_id?: string;
+	/** 消息 ID */
+	message_id?: string;
+	/** 中断信号 */
+	abort?: AbortSignal;
+	/** 额外元数据 */
+	metadata?: Record<string, unknown>;
+	/** 沙箱配置 */
+	sandbox?: SandboxConfig;
+	/** 沙箱 Provider */
+	sandboxProvider?: unknown | null;
+}
+/**
+* 工具结果元数据
+*/
+interface ToolResultMetadata {
+	/** 执行时间（毫秒） */
+	execution_time_ms: number;
+	/** 输出大小（字节） */
+	output_size?: number;
+	/** 标准输出 */
+	stdout?: string;
+	/** 标准错误 */
+	stderr?: string;
+	/** 退出码 */
+	exit_code?: number;
+	/** Token 使用量 */
+	usage?: {
+		inputTokens: number;
+		outputTokens: number;
+		totalTokens?: number;
+	};
+	/** 额外元数据 */
+	[key: string]: unknown;
+}
+/**
+* 工具执行结果
+*/
+interface ToolResult {
+	/** 是否成功 */
+	success: boolean;
+	/** 输出内容 */
+	output: string | Record<string, unknown>;
+	/** 错误信息 */
+	error?: string;
+	/** 结果元数据 */
+	metadata?: ToolResultMetadata;
+}
+/**
+* 工具元数据
+*/
+interface ToolMetadata {
+	/** 分类 */
+	category?: string;
+	/** 标签 */
+	tags?: string[];
+	/** 版本 */
+	version?: string;
+	/** 作者 */
+	author?: string;
+	/** 是否实验性 */
+	experimental?: boolean;
+	/** MCP 工具信息（MCP adapter 使用） */
+	mcpTool?: {
+		originalName: string;
+		originalDescription: string;
+		inputSchema?: unknown;
+	};
+}
+/**
+* 工具沙箱配置
+*/
+interface ToolSandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱配置 */
+	config?: Partial<SandboxConfig>;
+}
+/**
+* 工具权限配置
+*/
+interface ToolPermissionConfig {
+	/** 是否需要用户确认 */
+	requireConfirmation?: boolean;
+	/** 权限级别 */
+	level?: "safe" | "dangerous" | "critical";
+}
+/**
+* 工具信息
+*/
+interface ToolInfo<Parameters extends ZodType = ZodType> {
+	/** 工具名称 */
+	name: string;
+	/** 工具描述 */
+	description: string;
+	/** 参数 Schema */
+	parameters: Parameters;
+	/** 初始化函数（可选） */
+	init?: (ctx?: ToolContext) => Promise<void>;
+	/** 执行函数 */
+	execute: (args: z.infer<Parameters>, ctx: ToolContext) => Promise<ToolResult>;
+	/** 参数验证错误格式化（可选） */
+	formatValidationError?: (error: ZodError) => string;
+	/** 沙箱配置 */
+	sandbox?: ToolSandboxConfig;
+	/** 权限配置 */
+	permission?: ToolPermissionConfig;
+	/** 工具元数据 */
+	metadata?: ToolMetadata;
+}
+/**
+* 工具类型别名
+*/
+type Tool = ToolInfo;
+/**
+* Skill 来源类型
+*/
+type SkillSource = "built-in" | "user" | "project";
+/**
+* Skill 列表项（用于 list 和 description）
+*/
+interface SkillListItem {
+	name: string;
+	description: string;
+	source: SkillSource;
+}
+/**
+* 构建 SkillTool 的 description
+*/
+declare function buildSkillDescription(items: SkillListItem[]): string;
+/**
+* 创建 SkillTool
+*
+* @param getSkillList - 获取 skill 列表的回调
+* @param getSkill - 获取单个 skill 的回调
+*/
+declare function createSkillTool(getSkillList: () => SkillListItem[], getSkill: (name: string) => {
+	content: string;
+} | undefined): Tool;
+export { createSkillTool, buildSkillDescription };