@shareai-lab/kode-sdk 2.7.1 → 2.7.2

package/dist/tools/tool.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+exports.tools = tools;
+const zod_1 = require("zod");
+const registry_1 = require("./registry");
+/**
+ * 实现
+ */
+function tool(nameOrDef, executeFn) {
+    // 解析参数
+    const def = typeof nameOrDef === 'string'
+        ? {
+            name: nameOrDef,
+            description: `Execute ${nameOrDef}`,
+            parameters: zod_1.z.any(),
+            execute: executeFn,
+        }
+        : nameOrDef;
+    // 生成 JSON Schema (使用 Zod v4 原生方法)
+    let input_schema;
+    if (def.parameters) {
+        // Zod v4: 使用 zodToJsonSchema 的替代方案
+        // 由于 zod-to-json-schema 已被弃用，我们需要手动转换 Zod schema 为 JSON Schema
+        input_schema = zodToJsonSchemaManual(def.parameters);
+    }
+    else {
+        input_schema = { type: 'object', properties: {} };
+    }
+    // 创建工具实例
+    const toolInstance = {
+        name: def.name,
+        description: def.description || `Execute ${def.name}`,
+        input_schema,
+        hooks: def.hooks,
+        async exec(args, ctx) {
+            try {
+                // 参数验证
+                if (def.parameters) {
+                    const parseResult = def.parameters.safeParse(args);
+                    if (!parseResult.success) {
+                        return {
+                            ok: false,
+                            error: `Invalid parameters: ${parseResult.error.message}`,
+                            _validationError: true,
+                        };
+                    }
+                    args = parseResult.data;
+                }
+                // 增强上下文
+                const enhancedCtx = {
+                    ...ctx,
+                    emit(eventType, data) {
+                        ctx.agent?.events?.emitMonitor({
+                            type: 'tool_custom_event',
+                            toolName: def.name,
+                            eventType,
+                            data,
+                            timestamp: Date.now(),
+                        });
+                    },
+                };
+                // 执行工具
+                const result = await def.execute(args, enhancedCtx);
+                // 如果工具返回 {ok: false}，保持原样
+                if (result && typeof result === 'object' && 'ok' in result && result.ok === false) {
+                    return result;
+                }
+                // 正常结果
+                return result;
+            }
+            catch (error) {
+                // 捕获工具执行中的所有错误，统一返回格式
+                return {
+                    ok: false,
+                    error: error?.message || String(error),
+                    _thrownError: true,
+                };
+            }
+        },
+        toDescriptor() {
+            return {
+                source: 'registered',
+                name: def.name,
+                registryId: def.name,
+                metadata: {
+                    version: def.metadata?.version,
+                    tags: def.metadata?.tags,
+                    cacheable: def.metadata?.cacheable,
+                    cacheTTL: def.metadata?.cacheTTL,
+                    timeout: def.metadata?.timeout,
+                    concurrent: def.metadata?.concurrent,
+                    access: def.metadata?.readonly ? 'read' : 'write',
+                    mutates: !def.metadata?.readonly,
+                },
+            };
+        },
+    };
+    // 自动注册到全局 registry
+    registry_1.globalToolRegistry.register(def.name, () => toolInstance);
+    return toolInstance;
+}
+/**
+ * 批量定义工具
+ */
+function tools(definitions) {
+    return definitions.map((def) => tool(def));
+}
+/**
+ * 手动转换 Zod Schema 为 JSON Schema (替代已弃用的 zod-to-json-schema)
+ *
+ * 设计原则：
+ * - 简洁：只处理工具定义中常用的 Zod 类型
+ * - 健壮：对于不支持的类型，返回默认的 object schema
+ * - 可扩展：可以根据需要添加更多类型的支持
+ */
+function zodToJsonSchemaManual(zodType) {
+    // 处理 ZodEffects 类型（经过 .transform()、.refine() 等转换的 schema）
+    const typeName = zodType._def?.typeName;
+    if (typeName === 'ZodEffects' || (typeof typeName === 'string' && typeName.includes('ZodEffects'))) {
+        const innerSchema = zodType._def.schema;
+        if (innerSchema) {
+            return zodToJsonSchemaManual(innerSchema);
+        }
+        return { type: 'object', properties: {}, required: [] };
+    }
+    // 如果是 ZodObject
+    if (zodType instanceof zod_1.z.ZodObject) {
+        // Zod v4: shape 是属性而非方法
+        const shape = zodType.shape || zodType._def.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            const fieldSchema = convertZodType(value);
+            properties[key] = fieldSchema;
+            // 检查是否可选
+            const isOptional = isZodTypeOptional(value);
+            if (!isOptional) {
+                required.push(key);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required,
+        };
+    }
+    // 默认返回空对象
+    return {
+        type: 'object',
+        properties: {},
+        required: [],
+    };
+}
+/**
+ * 转换 Zod 类型为 JSON Schema 类型
+ */
+function convertZodType(zodType) {
+    // 处理可选类型
+    if (zodType instanceof zod_1.z.ZodOptional) {
+        const innerType = zodType._def.innerType;
+        return convertZodType(innerType);
+    }
+    // 处理默认值类型
+    if (zodType instanceof zod_1.z.ZodDefault) {
+        const innerType = zodType._def.innerType;
+        return convertZodType(innerType);
+    }
+    // 基本类型映射
+    if (zodType instanceof zod_1.z.ZodString) {
+        return { type: 'string' };
+    }
+    if (zodType instanceof zod_1.z.ZodNumber) {
+        return { type: 'number' };
+    }
+    if (zodType instanceof zod_1.z.ZodBoolean) {
+        return { type: 'boolean' };
+    }
+    if (zodType instanceof zod_1.z.ZodArray) {
+        const elementType = zodType._def.type;
+        return {
+            type: 'array',
+            items: convertZodType(elementType),
+        };
+    }
+    if (zodType instanceof zod_1.z.ZodObject) {
+        return zodToJsonSchemaManual(zodType);
+    }
+    if (zodType instanceof zod_1.z.ZodEnum) {
+        return {
+            type: 'string',
+            enum: zodType._def.values,
+        };
+    }
+    if (zodType instanceof zod_1.z.ZodLiteral) {
+        return {
+            type: typeof zodType._def.value,
+            const: zodType._def.value,
+        };
+    }
+    // 未知类型，默认为 object（避免意外返回 string）
+    return { type: 'object', properties: {}, required: [] };
+}
+/**
+ * 检查 Zod 类型是否可选
+ */
+function isZodTypeOptional(zodType) {
+    return (zodType instanceof zod_1.z.ZodOptional ||
+        zodType instanceof zod_1.z.ZodDefault ||
+        zodType.isNullable?.() === true);
+}

package/dist/tools/toolkit.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolKit = void 0;
+exports.toolMethod = toolMethod;
+const zod_1 = require("zod");
+const tool_1 = require("./tool");
+/**
+ * 工具方法装饰器
+ *
+ * @example
+ * ```ts
+ * class WeatherKit extends ToolKit {
+ *   @toolMethod({ description: 'Get current weather' })
+ *   async getWeather(args: { city: string }, ctx: ToolContext) {
+ *     return { temperature: 25, city: args.city };
+ *   }
+ * }
+ * ```
+ */
+function toolMethod(metadata = {}) {
+    return function (target, propertyKey, descriptor) {
+        // 存储元数据到类的原型
+        if (!target.constructor._toolMethods) {
+            target.constructor._toolMethods = new Map();
+        }
+        target.constructor._toolMethods.set(propertyKey, {
+            ...metadata,
+            method: descriptor.value,
+        });
+    };
+}
+/**
+ * ToolKit 基类
+ *
+ * 提供组织化的工具定义方式
+ *
+ * @example
+ * ```ts
+ * class DatabaseKit extends ToolKit {
+ *   constructor(private db: Database) {
+ *     super('db');
+ *   }
+ *
+ *   @toolMethod({
+ *     description: 'Query database',
+ *     parameters: z.object({ query: z.string() })
+ *   })
+ *   async query(args: { query: string }, ctx: ToolContext) {
+ *     return await this.db.query(args.query);
+ *   }
+ *
+ *   @toolMethod({ description: 'Insert record' })
+ *   async insert(args: { table: string; data: any }, ctx: ToolContext) {
+ *     return await this.db.insert(args.table, args.data);
+ *   }
+ * }
+ *
+ * // 使用
+ * const dbKit = new DatabaseKit(myDatabase);
+ * const tools = dbKit.getTools();
+ * // 返回: [db__query, db__insert]
+ * ```
+ */
+class ToolKit {
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    /**
+     * 获取所有工具实例
+     */
+    getTools() {
+        const constructor = this.constructor;
+        const toolMethods = constructor._toolMethods;
+        if (!toolMethods) {
+            return [];
+        }
+        const tools = [];
+        for (const [methodName, metadata] of toolMethods) {
+            const toolName = this.namespace ? `${this.namespace}__${methodName}` : methodName;
+            const def = {
+                name: toolName,
+                description: metadata.description || `Execute ${methodName}`,
+                parameters: metadata.parameters || zod_1.z.any(),
+                execute: metadata.method.bind(this),
+                metadata: metadata.metadata,
+            };
+            tools.push((0, tool_1.tool)(def));
+        }
+        return tools;
+    }
+    /**
+     * 获取工具名称列表
+     */
+    getToolNames() {
+        return this.getTools().map((t) => t.name);
+    }
+}
+exports.ToolKit = ToolKit;

package/dist/tools/type-inference.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patterns = exports.SchemaBuilder = void 0;
+exports.inferFromExample = inferFromExample;
+exports.schema = schema;
+exports.mergeSchemas = mergeSchemas;
+exports.extendSchema = extendSchema;
+const zod_1 = require("zod");
+/**
+ * TypeScript 类型到 Zod schema 的自动推断
+ *
+ * 注意：由于 TypeScript 类型在运行时被擦除，我们无法直接从类型生成 schema。
+ * 这个模块提供了一些辅助函数来简化 schema 定义。
+ */
+/**
+ * 从示例对象推断 Zod schema
+ *
+ * @example
+ * ```ts
+ * const schema = inferFromExample({
+ *   name: 'string',
+ *   age: 0,
+ *   active: true,
+ *   tags: ['string']
+ * });
+ * // 等价于:
+ * z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ *   active: z.boolean(),
+ *   tags: z.array(z.string())
+ * })
+ * ```
+ */
+function inferFromExample(example) {
+    const shape = {};
+    for (const [key, value] of Object.entries(example)) {
+        shape[key] = inferValueType(value);
+    }
+    return zod_1.z.object(shape);
+}
+/**
+ * 推断单个值的类型
+ */
+function inferValueType(value) {
+    if (value === null || value === undefined) {
+        return zod_1.z.any();
+    }
+    const type = typeof value;
+    switch (type) {
+        case 'string':
+            return zod_1.z.string();
+        case 'number':
+            return zod_1.z.number();
+        case 'boolean':
+            return zod_1.z.boolean();
+        case 'object':
+            if (Array.isArray(value)) {
+                if (value.length === 0) {
+                    return zod_1.z.array(zod_1.z.any());
+                }
+                return zod_1.z.array(inferValueType(value[0]));
+            }
+            return inferFromExample(value);
+        default:
+            return zod_1.z.any();
+    }
+}
+/**
+ * Schema 构建器 - 提供流畅的 API
+ *
+ * @example
+ * ```ts
+ * const schema = schema()
+ *   .string('name', 'User name')
+ *   .number('age', 'User age').optional()
+ *   .boolean('active').default(true)
+ *   .array('tags', z.string())
+ *   .build();
+ * ```
+ */
+class SchemaBuilder {
+    constructor() {
+        this.fields = {};
+    }
+    string(name, description) {
+        this.fields[name] = description ? zod_1.z.string().describe(description) : zod_1.z.string();
+        return this;
+    }
+    number(name, description) {
+        this.fields[name] = description ? zod_1.z.number().describe(description) : zod_1.z.number();
+        return this;
+    }
+    boolean(name, description) {
+        this.fields[name] = description ? zod_1.z.boolean().describe(description) : zod_1.z.boolean();
+        return this;
+    }
+    array(name, itemSchema, description) {
+        const schema = zod_1.z.array(itemSchema);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    object(name, shape, description) {
+        const schema = zod_1.z.object(shape);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    enum(name, values, description) {
+        const schema = zod_1.z.enum(values);
+        this.fields[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    optional(name) {
+        if (this.fields[name]) {
+            this.fields[name] = this.fields[name].optional();
+        }
+        return this;
+    }
+    default(name, defaultValue) {
+        if (this.fields[name]) {
+            this.fields[name] = this.fields[name].default(defaultValue);
+        }
+        return this;
+    }
+    custom(name, schema) {
+        this.fields[name] = schema;
+        return this;
+    }
+    build() {
+        return zod_1.z.object(this.fields);
+    }
+}
+exports.SchemaBuilder = SchemaBuilder;
+/**
+ * 创建 schema 构建器
+ */
+function schema() {
+    return new SchemaBuilder();
+}
+/**
+ * 快速定义常用的 schema 模式
+ */
+exports.patterns = {
+    /**
+     * 文件路径
+     */
+    filePath: (description = 'File path') => zod_1.z.string().describe(description),
+    /**
+     * 目录路径
+     */
+    dirPath: (description = 'Directory path') => zod_1.z.string().describe(description),
+    /**
+     * URL
+     */
+    url: (description = 'URL') => zod_1.z.string().url().describe(description),
+    /**
+     * Email
+     */
+    email: (description = 'Email address') => zod_1.z.string().email().describe(description),
+    /**
+     * 正整数
+     */
+    positiveInt: (description = 'Positive integer') => zod_1.z.number().int().positive().describe(description),
+    /**
+     * 非负整数
+     */
+    nonNegativeInt: (description = 'Non-negative integer') => zod_1.z.number().int().nonnegative().describe(description),
+    /**
+     * 字符串数组
+     */
+    stringArray: (description = 'Array of strings') => zod_1.z.array(zod_1.z.string()).describe(description),
+    /**
+     * 可选字符串
+     */
+    optionalString: (description) => zod_1.z.string().optional().describe(description || 'Optional string'),
+    /**
+     * 可选数字
+     */
+    optionalNumber: (description) => zod_1.z.number().optional().describe(description || 'Optional number'),
+    /**
+     * JSON 对象
+     */
+    json: (description = 'JSON object') => zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe(description),
+};
+/**
+ * 辅助函数：合并多个 schema
+ */
+function mergeSchemas(...schemas) {
+    if (schemas.length === 0) {
+        return zod_1.z.object({});
+    }
+    if (schemas.length === 1) {
+        return schemas[0];
+    }
+    // 使用 z.intersection 合并
+    return schemas.reduce((acc, schema) => acc.and(schema));
+}
+/**
+ * 辅助函数：扩展 schema
+ */
+function extendSchema(base, extension) {
+    if (base instanceof zod_1.z.ZodObject) {
+        return base.extend(extension);
+    }
+    // 如果不是 object schema，创建新的 object schema
+    return zod_1.z.object(extension);
+}

package/dist/utils/agent-id.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAgentId = generateAgentId;
+const CROCKFORD32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function encodeTime(time, length) {
+    let remaining = time;
+    const chars = Array(length);
+    for (let i = length - 1; i >= 0; i--) {
+        const mod = remaining % 32;
+        chars[i] = CROCKFORD32.charAt(mod);
+        remaining = Math.floor(remaining / 32);
+    }
+    return chars.join('');
+}
+function encodeRandom(length) {
+    const chars = Array(length);
+    for (let i = 0; i < length; i++) {
+        const rand = Math.floor(Math.random() * 32);
+        chars[i] = CROCKFORD32.charAt(rand);
+    }
+    return chars.join('');
+}
+function generateAgentId() {
+    const time = Date.now();
+    const timePart = encodeTime(time, 10);
+    const randomPart = encodeRandom(16);
+    return `agt-${timePart}${randomPart}`;
+}

package/dist/utils/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * 日志工具模块
+ *
+ * 仅在 NODE_ENV=local 时输出日志，生产环境静默
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * 检查是否启用日志（仅在本地开发环境）
+ */
+function isLoggingEnabled() {
+    return process.env.NODE_ENV === 'local';
+}
+/**
+ * 日志输出（仅在 NODE_ENV=local 时输出）
+ */
+exports.logger = {
+    log: (...args) => {
+        if (isLoggingEnabled()) {
+            console.log(...args);
+        }
+    },
+    info: (...args) => {
+        if (isLoggingEnabled()) {
+            console.info(...args);
+        }
+    },
+    warn: (...args) => {
+        if (isLoggingEnabled()) {
+            console.warn(...args);
+        }
+    },
+    error: (...args) => {
+        if (isLoggingEnabled()) {
+            console.error(...args);
+        }
+    },
+    debug: (...args) => {
+        if (isLoggingEnabled()) {
+            console.debug(...args);
+        }
+    },
+};

package/dist/utils/session-id.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionId = void 0;
+class SessionId {
+    static parse(id) {
+        const parts = id.split('/');
+        const components = {
+            agentTemplate: '',
+            rootId: '',
+            forkIds: [],
+        };
+        for (const part of parts) {
+            if (part.startsWith('org-')) {
+                components.orgId = part.slice(4);
+            }
+            else if (part.startsWith('team-')) {
+                components.teamId = part.slice(5);
+            }
+            else if (part.startsWith('user-')) {
+                components.userId = part.slice(5);
+            }
+            else if (part.startsWith('agent-')) {
+                components.agentTemplate = part.slice(6);
+            }
+            else if (part.startsWith('session-')) {
+                components.rootId = part.slice(8);
+            }
+            else if (part.startsWith('fork-')) {
+                components.forkIds.push(part.slice(5));
+            }
+        }
+        return components;
+    }
+    static generate(opts) {
+        const parts = [];
+        if (opts.orgId)
+            parts.push(`org-${opts.orgId}`);
+        if (opts.teamId)
+            parts.push(`team-${opts.teamId}`);
+        if (opts.userId)
+            parts.push(`user-${opts.userId}`);
+        parts.push(`agent-${opts.agentTemplate}`);
+        if (opts.parentSessionId) {
+            const parent = SessionId.parse(opts.parentSessionId);
+            parts.push(`session-${parent.rootId}`);
+            parts.push(...parent.forkIds.map((id) => `fork-${id}`));
+            parts.push(`fork-${this.randomId()}`);
+        }
+        else {
+            parts.push(`session-${this.randomId()}`);
+        }
+        return parts.join('/');
+    }
+    static snapshot(sessionId, sfpIndex) {
+        return `${sessionId}@sfp-${sfpIndex}`;
+    }
+    static label(sessionId, label) {
+        return `${sessionId}@label-${label}`;
+    }
+    static randomId() {
+        return Math.random().toString(36).slice(2, 8);
+    }
+}
+exports.SessionId = SessionId;