@fastgpt-plugin/sdk-factory 0.0.1-alpha.1 → 0.0.1-alpha.10

package/README.en.md

@@ -0,0 +1,174 @@
+# FastGPT Plugin SDK Factory
+
+Language: [简体中文](./README.md) | [English](./README.en.md)
+
+TypeScript SDK for building FastGPT Tool Plugins. It wraps plugin metadata, input/output validation, secret configuration, runtime communication, and streaming responses behind a small API surface so tool authors can focus on business logic.
+
+## Installation
+
+```bash
+pnpm add @fastgpt-plugin/sdk-factory zod
+```
+
+When developing inside this monorepo, use the workspace dependency directly.
+
+## Quick Start
+
+The plugin entry file must default-export the instance returned by `defineTool()` or `defineToolSet()`.
+
+```ts
+import {
+  createToolHandler,
+  defineTool,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    text: z.string().meta({
+      title: 'Text'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    result: z.string().meta({
+      title: 'Result'
+    } satisfies OutputSchemaMetaType)
+  }),
+  handler: async (input) => {
+    return {
+      result: input.text.toUpperCase()
+    };
+  }
+});
+
+export default defineTool({
+  manifest: {
+    pluginId: 'uppercase',
+    version: '1.0.0',
+    name: {
+      en: 'Uppercase',
+      'zh-CN': '转大写'
+    },
+    description: {
+      en: 'Convert text to uppercase',
+      'zh-CN': '将文本转换为大写'
+    },
+    versionDescription: {
+      en: 'Initial version',
+      'zh-CN': '初始版本'
+    },
+    tags: ['tools']
+  },
+  handler
+});
+```
+
+## API
+
+### `createToolHandler(definition)`
+
+Defines a tool handler and infers `input`, `output`, and `secrets` types from Zod schemas.
+
+The handler context includes:
+
+| Field | Description |
+| --- | --- |
+| `systemVar` | System variables injected by FastGPT. |
+| `secrets` | Secret values validated by `secretSchema`. |
+| `invoke` | Client for invoking host capabilities, such as file upload. |
+| `streamResponse` | Sends streaming tool answers. |
+
+### `defineTool(options)`
+
+Defines a single-tool plugin. `manifest` describes the plugin metadata, and `handler` contains the execution logic.
+
+```ts
+export default defineTool({
+  manifest,
+  handler
+});
+```
+
+### `defineToolSet(options)`
+
+Defines a tool set with multiple child tools. All child tools share the top-level `manifest`; each child tool has its own `id`, name, description, and handler.
+
+## Manifest
+
+`manifest` uses bilingual i18n fields. Common fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `pluginId` | Yes | Unique plugin ID. |
+| `version` | Yes | Plugin version. |
+| `name` | Yes | Plugin name in `{ en, 'zh-CN' }` format. |
+| `description` | Yes | Plugin description in `{ en, 'zh-CN' }` format. |
+| `versionDescription` | No | Version description. |
+| `author` | No | Author. |
+| `repoUrl` | No | Repository URL. |
+| `tutorialUrl` | No | Tutorial URL. |
+| `tags` | No | Plugin tags. |
+| `permission` | No | Plugin permission declarations. |
+| `icon` | No | Plugin icon; the build pipeline can fill it automatically. |
+| `toolDescription` | No | Tool description for the model; the build pipeline can fill it automatically. |
+
+## Secret Configuration
+
+A single tool can declare `secretSchema` in its handler. A tool set can declare a shared `secretSchema` at the top level of `defineToolSet()`.
+
+Schema field metadata is written into the built JSON Schema through Zod `.meta()`. Use `InputSchemaMetaType` for input fields, `OutputSchemaMetaType` for output fields, and `SecretSchemaMetaType` for secret fields. Every `secretSchema` field must include `isSecret`; set it to `true` for values that need encrypted storage.
+
+## Host Invocation
+
+Use `ctx.invoke` to call FastGPT host capabilities. The SDK currently exposes file upload.
+
+```ts
+const handler = createToolHandler({
+  inputSchema: z.object({
+    content: z.string().meta({
+      title: 'Content'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    accessURL: z.string().meta({
+      title: 'Access URL'
+    } satisfies OutputSchemaMetaType),
+    fileName: z.string().meta({
+      title: 'File Name'
+    } satisfies OutputSchemaMetaType),
+    size: z.number().meta({
+      title: 'Size'
+    } satisfies OutputSchemaMetaType)
+  }),
+  handler: async (input, { invoke }) => {
+    const [result, err] = await invoke.uploadFile({
+      fileName: 'result.txt',
+      contentType: 'text/plain',
+      file: Buffer.from(input.content, 'utf-8')
+    });
+
+    if (err) {
+      throw err;
+    }
+    if (!result) {
+      throw new Error('Failed to upload file');
+    }
+
+    return {
+      accessURL: result.accessURL,
+      fileName: result.fileName,
+      size: result.size
+    };
+  }
+});
+```
+
+## Build
+
+```bash
+pnpm --filter @fastgpt-plugin/sdk-factory build
+```
+
+After build, the package entry is `dist/index.js` and type declarations are emitted to `dist/index.d.ts`.

package/README.md

@@ -1,5 +1,7 @@
 # FastGPT Plugin SDK Factory
 
+语言：[简体中文](./README.md) | [English](./README.en.md)
+
 用于构建 FastGPT Tool Plugin 的 TypeScript SDK。它把插件声明、输入输出校验、密钥配置、运行时通信和流式响应封装成少量 API，让工具开发者专注于业务逻辑。
 
 TypeScript SDK for building FastGPT Tool Plugins. It wraps plugin metadata, input/output validation, secret configuration, runtime communication, and streaming responses behind a small API surface so tool authors can focus on business logic.
@@ -21,15 +23,24 @@ When developing inside this monorepo, use the workspace dependency directly.
 The plugin entry file must default-export the instance returned by `defineTool()` or `defineToolSet()`.
 
 ```ts
-import { createToolHandler, defineTool } from '@fastgpt-plugin/sdk-factory';
+import {
+  createToolHandler,
+  defineTool,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
 import z from 'zod';
 
 const handler = createToolHandler({
   inputSchema: z.object({
-    text: z.string()
+    text: z.string().meta({
+      title: 'Text'
+    } satisfies InputSchemaMetaType)
   }),
   outputSchema: z.object({
-    result: z.string()
+    result: z.string().meta({
+      title: 'Result'
+    } satisfies OutputSchemaMetaType)
   }),
   handler: async (input) => {
     return {
@@ -71,13 +82,20 @@ Defines a tool handler and infers `input`, `output`, and `secrets` types from Zo
 ```ts
 const handler = createToolHandler({
   inputSchema: z.object({
-    query: z.string()
+    query: z.string().meta({
+      title: 'Query'
+    } satisfies InputSchemaMetaType)
   }),
   outputSchema: z.object({
-    answer: z.string()
+    answer: z.string().meta({
+      title: 'Answer'
+    } satisfies OutputSchemaMetaType)
   }),
   secretSchema: z.object({
-    apiKey: z.string()
+    apiKey: z.string().meta({
+      title: 'API Key',
+      isSecret: true
+    } satisfies SecretSchemaMetaType)
   }),
   handler: async (input, ctx) => {
     ctx.streamResponse({
@@ -124,14 +142,30 @@ Defines a tool set with multiple child tools. All child tools share the top-leve
 
 ```ts
 const searchHandler = createToolHandler({
-  inputSchema: z.object({ query: z.string() }),
-  outputSchema: z.object({ items: z.array(z.string()) }),
+  inputSchema: z.object({
+    query: z.string().meta({
+      title: 'Query'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    items: z.array(z.string()).meta({
+      title: 'Items'
+    } satisfies OutputSchemaMetaType)
+  }),
   handler: async (input) => ({ items: [input.query] })
 });
 
 const summaryHandler = createToolHandler({
-  inputSchema: z.object({ content: z.string() }),
-  outputSchema: z.object({ summary: z.string() }),
+  inputSchema: z.object({
+    content: z.string().meta({
+      title: 'Content'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    summary: z.string().meta({
+      title: 'Summary'
+    } satisfies OutputSchemaMetaType)
+  }),
   handler: async (input) => ({ summary: input.content.slice(0, 100) })
 });
 
@@ -206,14 +240,33 @@ export default defineToolSet({
 
 A single tool can declare `secretSchema` in its handler. A tool set can declare a shared `secretSchema` at the top level of `defineToolSet()`.
 
+Schema 字段元数据通过 Zod `.meta()` 写入构建后的 JSON Schema。输入字段使用 `InputSchemaMetaType`，输出字段使用 `OutputSchemaMetaType`，密钥字段使用 `SecretSchemaMetaType`。`secretSchema` 的每个字段都要包含 `isSecret`，需要加密存储时设为 `true`。
+
+Schema field metadata is written into the built JSON Schema through Zod `.meta()`. Use `InputSchemaMetaType` for input fields, `OutputSchemaMetaType` for output fields, and `SecretSchemaMetaType` for secret fields. Every `secretSchema` field must include `isSecret`; set it to `true` for values that need encrypted storage.
+
 ```ts
 const secretSchema = z.object({
-  apiKey: z.string()
+  apiKey: z.string().meta({
+    title: 'API Key',
+    isSecret: true
+  } satisfies SecretSchemaMetaType),
+  baseURL: z.url().meta({
+    title: 'Base URL',
+    isSecret: false
+  } satisfies SecretSchemaMetaType)
 });
 
 const handler = createToolHandler({
-  inputSchema: z.object({ prompt: z.string() }),
-  outputSchema: z.object({ text: z.string() }),
+  inputSchema: z.object({
+    prompt: z.string().meta({
+      title: 'Prompt'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    text: z.string().meta({
+      title: 'Text'
+    } satisfies OutputSchemaMetaType)
+  }),
   secretSchema,
   handler: async (input, ctx) => {
     return {
@@ -232,12 +285,20 @@ Use `ctx.invoke` to call FastGPT host capabilities. The SDK currently exposes fi
 ```ts
 const handler = createToolHandler({
   inputSchema: z.object({
-    content: z.string()
+    content: z.string().meta({
+      title: 'Content'
+    } satisfies InputSchemaMetaType)
   }),
   outputSchema: z.object({
-    accessURL: z.string(),
-    fileName: z.string(),
-    size: z.number()
+    accessURL: z.string().meta({
+      title: 'Access URL'
+    } satisfies OutputSchemaMetaType),
+    fileName: z.string().meta({
+      title: 'File Name'
+    } satisfies OutputSchemaMetaType),
+    size: z.number().meta({
+      title: 'Size'
+    } satisfies OutputSchemaMetaType)
   }),
   handler: async (input, { invoke }) => {
     const [result, err] = await invoke.uploadFile({
@@ -246,7 +307,10 @@ const handler = createToolHandler({
       file: Buffer.from(input.content, 'utf-8')
     });
 
-    if (err || !result) {
+    if (err) {
+      throw err;
+    }
+    if (!result) {
       throw new Error('Failed to upload file');
     }
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import z from "zod";
-import * as node_stream0 from "node:stream";
+import * as _$node_stream0 from "node:stream";
 
 //#region src/manifest.type.d.ts
 declare const UserToolManifestSchema: z.ZodObject<{
@@ -59,15 +59,18 @@ type I18nStringType = z.infer<typeof I18nStringSchema>;
 //#endregion
 //#region ../../packages/domain/src/value-objects/result.vo.d.ts
 /** usecase, interface-adapter 都要使用这个类型， 手动处理错误，并且能从内到外把错误透出来*/
-type ResultFailure<E = unknown> = {
+type ResultFailure<E extends Error = Error> = {
   reason: I18nStringType;
   error: E;
+  code?: string;
+  message?: string;
+  data?: unknown;
 };
-type Result<T = unknown, E = unknown> = [T, null] | [null, ResultFailure<E>];
+type Result<T = unknown, E extends Error = Error> = [T, null] | [null, ResultFailure<E>];
 //#endregion
 //#region ../../packages/domain/src/ports/invoke.port.d.ts
 declare const InvokeUploadFileInputSchema: z.ZodObject<{
-  file: z.ZodUnion<readonly [z.ZodCustom<node_stream0.Readable, node_stream0.Readable>, z.ZodPipe<z.ZodUnion<readonly [z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodTransform<Buffer<any>, Uint8Array<ArrayBuffer> | Buffer<ArrayBufferLike>>>]>;
+  file: z.ZodUnion<readonly [z.ZodCustom<_$node_stream0.Readable, _$node_stream0.Readable>, z.ZodPipe<z.ZodUnion<readonly [z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodTransform<Buffer<any>, Uint8Array<ArrayBuffer> | Buffer<ArrayBufferLike>>>]>;
   fileName: z.ZodOptional<z.ZodString>;
   contentType: z.ZodOptional<z.ZodIntersection<z.ZodEnum<{
     "application/javascript": "application/javascript";
@@ -102,9 +105,9 @@ declare const InvokeUploadFileInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const InvokeUploadFileOutputSchema: z.ZodObject<{
   accessURL: z.ZodString;
-  etag: z.ZodString;
-  fileName: z.ZodString;
-  contentType: z.ZodIntersection<z.ZodEnum<{
+  etag: z.ZodOptional<z.ZodString>;
+  fileName: z.ZodOptional<z.ZodString>;
+  contentType: z.ZodOptional<z.ZodIntersection<z.ZodEnum<{
     "application/javascript": "application/javascript";
     "application/json": "application/json";
     "application/yaml": "application/yaml";
@@ -133,40 +136,50 @@ declare const InvokeUploadFileOutputSchema: z.ZodObject<{
     "application/octet-stream": "application/octet-stream";
     "multipart/form-data": "multipart/form-data";
     "text/event-stream": "text/event-stream";
-  }>, z.ZodString>;
-  size: z.ZodNumber;
-  createTime: z.ZodDate;
+  }>, z.ZodString>>;
+  size: z.ZodOptional<z.ZodNumber>;
+  createTime: z.ZodOptional<z.ZodDate>;
 }, z.core.$strip>;
 type InvokeUploadFileInputType = z.infer<typeof InvokeUploadFileInputSchema>;
 type InvokeUploadFileOutputType = z.infer<typeof InvokeUploadFileOutputSchema>;
+declare const InvokeUserInfoOutputSchema: z.ZodObject<{
+  username: z.ZodString;
+  contact: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  memberName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  orgs: z.ZodArray<z.ZodObject<{
+    pathId: z.ZodString;
+    name: z.ZodString;
+  }, z.core.$strip>>;
+  groups: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type InvokeUserInfoOutputType = z.infer<typeof InvokeUserInfoOutputSchema>;
+type InvokeWecomCorpTokenOutputType = {
+  access_token: string;
+  expires_in: number;
+};
 /**
  * 反向调用 FastGPT 的能力
  */
 interface InvokePort {
   /** 上传文件 */
   uploadFile(input: InvokeUploadFileInputType): Promise<Result<InvokeUploadFileOutputType>>;
+  userInfo(): Promise<Result<InvokeUserInfoOutputType>>;
+  getWecomCorpToken(): Promise<Result<InvokeWecomCorpTokenOutputType>>;
 }
 //#endregion
 //#region ../../packages/domain/src/value-objects/system-var.vo.d.ts
 declare const SystemVarSchema: z.ZodObject<{
-  user: z.ZodObject<{
-    id: z.ZodString;
-    username: z.ZodString;
-    contact: z.ZodString;
-    membername: z.ZodString;
-    teamName: z.ZodString;
-    teamId: z.ZodString;
-    name: z.ZodString;
-  }, z.core.$strip>;
   app: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
   }, z.core.$strip>;
-  tool: z.ZodObject<{
-    id: z.ZodString;
-    version: z.ZodString;
-    prefix: z.ZodOptional<z.ZodString>;
-  }, z.core.$loose>;
+  chat: z.ZodObject<{
+    chatId: z.ZodString;
+    uid: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  invokeToken: z.ZodString;
   time: z.ZodString;
 }, z.core.$strip>;
 type SystemVarType = z.infer<typeof SystemVarSchema>;
@@ -209,6 +222,11 @@ type ToolHandlerDefinition<TInput extends ToolInputSchema = ToolInputSchema, TOu
 declare function createToolHandler<TInput extends ToolInputSchema, TOutput extends ToolOutputSchema, TSecret extends ToolSecretSchema = undefined>(def: ToolHandlerDefinition<TInput, TOutput, TSecret>): ToolHandlerDefinition<TInput, TOutput, TSecret>;
 //#endregion
 //#region src/index.d.ts
+type InputSchemaMetaType = z.GlobalMeta;
+type OutputSchemaMetaType = z.GlobalMeta;
+type SecretSchemaMetaType = z.GlobalMeta & {
+  /** 标注该字段是否需要加密存储 */isSecret: boolean;
+};
 interface DefinedToolFactory {
   setSecretSchema<TSecret extends Record<string, unknown>>(schema: z.ZodType<TSecret>): void;
   registerTool(definition: ToolHandlerDefinition, id?: string, childManifest?: ToolChildManifestDefinition): void;
@@ -237,4 +255,4 @@ declare const defineToolSet: ({
   })[];
 }) => DefinedToolFactory;
 //#endregion
-export { DefinedToolFactory, createToolHandler, defineTool, defineToolSet };
+export { DefinedToolFactory, InputSchemaMetaType, OutputSchemaMetaType, SecretSchemaMetaType, type ToolHandlerContext, createToolHandler, defineTool, defineToolSet };

package/dist/index.js

@@ -1 +1 @@
-import e from"zod";import{Readable as t}from"node:stream";import{randomUUID as n}from"node:crypto";import r,{Readable as i}from"stream";var a=class e{stream;closed=!1;constructor(e){this.stream=new t({objectMode:!0,read(){}}),e?.(this)}static create(t){return new e(t)}write(e){this.ensureWritable(),this.stream.push(e)}send(e){this.write(e)}close(){this.closed||(this.closed=!0,this.stream.push(null))}end(){this.close()}fail(e){this.closed=!0,this.stream.destroy(e)}toReadable(){return this.stream}onData(e){return this.stream.on(`data`,e),this}onEnd(e){return this.stream.on(`end`,e),this}onError(e){return this.stream.on(`error`,e),this}async consume(e){for await(let t of this.values())await e(t)}async*values(){for await(let e of this.stream)yield e}ensureWritable(){if(this.closed||this.stream.destroyed)throw Error(`StreamData is already closed`)}};const o=e=>(e=e.replace(/(?<=https?:\/\/)[^\s]+/g,`xxx`),e=e.replace(/ns-[\w-]+/g,`xxx`),e),s=(e,t=``)=>o(typeof e==`string`?e:e?.response?.data?.message||e?.response?.message||e?.message||e?.response?.data?.msg||e?.response?.msg||e?.msg||t),c=`application/javascript,application/json,application/yaml,application/zip,image/jpeg,image/png,image/gif,image/webp,image/svg+xml,application/pdf,text/plain,text/csv,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.openxmlformats-officedocument.presentationml.presentation,application/msword,application/vnd.ms-excel,application/vnd.ms-powerpoint,text/markdown,audio/mpeg,video/mp4,audio/wav,text/html,application/xml,application/gzip,application/octet-stream,multipart/form-data,text/event-stream`.split(`,`),l=e.enum(c).and(e.string().regex(/^[^/]+\/[^/]+$/)),u=e.object({fileKey:e.string(),fileName:e.string(),contentType:l,size:e.number(),etag:e.string(),createTime:e.date()}),d=e.object({fileKey:e.string().optional(),path:e.string().optional(),fileName:e.string().optional(),contentType:l.optional(),overwrite:e.boolean().optional(),file:e.union([e.instanceof(i,{error:`Stream cannot be empty`}),e.union([e.instanceof(Buffer,{error:`Buffer is required`}),e.instanceof(Uint8Array,{error:`Uint8Array is required`})]).transform(e=>e instanceof Uint8Array&&!(e instanceof Buffer)?Buffer.from(e):e)])});e.object({...d.omit({fileKey:!0,overwrite:!0,path:!0}).shape});const f=e.object({...u.omit({fileKey:!0}).shape,accessURL:e.string()}),p=e.enum([`uploadFile`]).enum,m=e=>[e,null];function h(e,t){return g(e)?[null,e]:[null,{reason:e,error:t}]}function g(e){return!!(e&&typeof e==`object`&&`reason`in e&&`error`in e)}const _=`__plugin_ipc_stream__`,v=`__pluginIpcDuplexReply__`;var y=class{pending=new Map;readyHandlers=new Set;errorHandlers=new Set;streamHandlers=new Map;incomingStreams=new Map;bufferedIncomingStreams=new Map;pendingStreamWaiters=new Map;requestHandler=null;eventHandler=null;endpoint;options;unsubscribeMessage;closed=!1;constructor(e,t={}){C(e)?(this.endpoint=e,this.options=t):(this.endpoint=process,this.options=e??{}),this.unsubscribeMessage=x(this.endpoint,e=>{this.dispatch(e).catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))})})}onReady(e){return this.readyHandlers.add(e),()=>{this.readyHandlers.delete(e)}}onError(e){return this.errorHandlers.add(e),()=>{this.errorHandlers.delete(e)}}setRequestHandler(e){this.requestHandler=e}setEventHandler(e){this.eventHandler=e}async requestDuplex(e,t,r){this.ensureOpen();let i=r?.requestId??n(),a=r?.timeoutMs??this.options.defaultTimeoutMs??3e4,o=Date.now(),s=r?.input===void 0?void 0:this.pipeStream(j(i),r.input,{traceId:r.traceId,streamId:r.inputStreamId,meta:r.inputMeta});s&&s.catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))});let c=await this.request(e,t,{timeoutMs:a,traceId:r?.traceId,requestId:i});if(!E(c))return{requestId:i,result:c,...s===void 0?{}:{inputDone:s}};let l;if(c.hasOutputStream){let e=Date.now()-o,t=Math.max(1,a-e);l=await this.waitForStream(M(i),{timeoutMs:t})}return{requestId:i,result:c.result,...l===void 0?{}:{output:l},...s===void 0?{}:{inputDone:s}}}replyDuplex(e,t,n){return{[v]:!0,...t===void 0?{}:{result:t},...n?.output===void 0?{}:{output:n.output},...n===void 0?{}:{options:{...n.traceId===void 0?{}:{traceId:n.traceId},...n.outputStreamId===void 0?{}:{outputStreamId:n.outputStreamId},...n.outputMeta===void 0?{}:{outputMeta:n.outputMeta}}}}}async waitForRequestInputStream(e,t){return this.waitForStream(j(e.id),t)}onStream(e,t){this.streamHandlers.has(e)||this.streamHandlers.set(e,new Set);let n=this.streamHandlers.get(e),r=t;return n.add(r),()=>{n.delete(r),n.size===0&&this.streamHandlers.delete(e)}}async waitForStream(e,t){this.ensureOpen();let n=this.bufferedIncomingStreams.get(e);if(n&&n.length>0){let t=n.shift();return n.length===0&&this.bufferedIncomingStreams.delete(e),t}return new Promise((n,r)=>{let i={resolve:n,reject:r};t?.timeoutMs!==void 0&&(i.timer=setTimeout(()=>{let t=this.pendingStreamWaiters.get(e);if(!t)return;let n=t.indexOf(i);n>=0&&t.splice(n,1),t.length===0&&this.pendingStreamWaiters.delete(e),r(Error(`Wait stream timeout: ${e}`))},t.timeoutMs)),this.pendingStreamWaiters.has(e)||this.pendingStreamWaiters.set(e,[]),this.pendingStreamWaiters.get(e).push(i)})}async createWritableStream(e,t){this.ensureOpen();let r=t?.streamId??n(),i=!1;return await this.sendStreamFrame({type:`start`,streamId:r,streamName:e,...t?.meta===void 0?{}:{meta:t.meta}},t?.traceId),{streamId:r,write:async e=>{if(i)throw Error(`Stream is already closed: ${r}`);await this.sendStreamFrame({type:`chunk`,streamId:r,chunk:e},t?.traceId)},end:async()=>{i||(i=!0,await this.sendStreamFrame({type:`end`,streamId:r},t?.traceId))},fail:async e=>{i||(i=!0,await this.sendStreamFrame({type:`error`,streamId:r,error:O(e)},t?.traceId))}}}async pipeStream(e,t,n){let r=await this.createWritableStream(e,n);try{for await(let e of A(t))await r.write(e);await r.end()}catch(e){throw await r.fail(e instanceof Error?e:Error(String(e))),e}}async request(e,t,r){this.ensureOpen();let i=r?.requestId??n(),a=r?.timeoutMs??this.options.defaultTimeoutMs??3e4;return new Promise((n,o)=>{let s=setTimeout(()=>{this.pending.delete(i),o(Object.assign(Error(`Request timeout: ${e}`),{code:`REQUEST_TIMEOUT`,requestId:i,method:e}))},a);this.pending.set(i,{resolve:n,reject:o,timer:s}),this.send({id:i,messageType:`request`,method:e,params:t,...r?.traceId===void 0?{}:{traceId:r.traceId},timestamp:Date.now()}).catch(e=>{clearTimeout(s),this.pending.delete(i),o(e)})})}async emit(e,t,r){this.ensureOpen(),await this.send({id:n(),messageType:`event`,method:e,params:t,...r===void 0?{}:{traceId:r},timestamp:Date.now()})}async sendReady(){this.ensureOpen(),await this.send({id:n(),messageType:`ready`,timestamp:Date.now()})}async reply(e,t){this.ensureOpen(),await this.send({id:e.id,messageType:`response`,...t===void 0?{}:{result:t},...e.traceId===void 0?{}:{traceId:e.traceId},timestamp:Date.now()})}async replyError(e,t){this.ensureOpen();let n=O(t);await this.send({id:e.id,messageType:`error`,error:n,...e.traceId===void 0?{}:{traceId:e.traceId},timestamp:Date.now()})}async close(e=Error(`IPC channel closed`)){this.closed||(this.closed=!0,this.unsubscribeMessage(),this.rejectAllPending(e),this.rejectAllPendingStreamWaiters(e),this.failAllIncomingStreams(e))}async dispatch(e){if(!this.closed){if(e.messageType===`response`||e.messageType===`error`){this.handleResponse(e);return}if(e.messageType===`ready`){this.readyHandlers.forEach(t=>t(e));return}if(e.messageType===`event`){if(T(e)){await this.handleStreamFrameMessage(e);return}await this.eventHandler?.(e);return}e.messageType===`request`&&await this.handleRequest(e)}}handleResponse(e){let t=this.pending.get(e.id);if(t){if(clearTimeout(t.timer),this.pending.delete(e.id),e.error){t.reject(k(e.error));return}t.resolve(e.result)}}async handleRequest(e){if(!e.method){await this.replyError(e,{code:`INVALID_REQUEST`,message:`Request method is required`});return}if(!this.requestHandler){await this.replyError(e,{code:`METHOD_NOT_FOUND`,message:`Method not found: ${e.method}`});return}try{let t=await this.requestHandler(e);if(D(t)){await this.handleDuplexReply(e,t);return}await this.reply(e,t)}catch(t){await this.replyError(e,t instanceof Error?t:Error(String(t)))}}rejectAllPending(e){this.pending.forEach((t,n)=>{clearTimeout(t.timer),t.reject(e),this.pending.delete(n)})}rejectAllPendingStreamWaiters(e){this.pendingStreamWaiters.forEach((t,n)=>{t.forEach(t=>{t.timer&&clearTimeout(t.timer),t.reject(e)}),this.pendingStreamWaiters.delete(n)})}failAllIncomingStreams(e){this.incomingStreams.forEach((t,n)=>{t.stream.fail(e),this.incomingStreams.delete(n)}),this.bufferedIncomingStreams.clear()}async sendStreamFrame(e,t){await this.emit(_,e,t)}async handleDuplexReply(e,t){let n=t.options?.traceId??e.traceId;t.output!==void 0&&this.pipeStream(M(e.id),t.output,{traceId:n,streamId:t.options?.outputStreamId,meta:t.options?.outputMeta}).catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))}),await this.reply(e,{[v]:!0,hasOutputStream:t.output!==void 0,...t.result===void 0?{}:{result:t.result}})}async handleStreamFrameMessage(e){let t=e.params;switch(t.type){case`start`:{let n={streamId:t.streamId,streamName:t.streamName,stream:a.create(),...e.traceId===void 0?{}:{traceId:e.traceId},...t.meta===void 0?{}:{meta:t.meta}};this.incomingStreams.set(t.streamId,n),this.dispatchIncomingStream(n);return}case`chunk`:{let e=this.incomingStreams.get(t.streamId);if(!e){this.emitError(Error(`Stream not found: ${t.streamId}`));return}e.stream.write(t.chunk);return}case`end`:{let e=this.incomingStreams.get(t.streamId);if(!e)return;e.stream.close(),this.incomingStreams.delete(t.streamId);return}case`error`:{let e=this.incomingStreams.get(t.streamId);if(!e)return;e.stream.fail(k(t.error)),this.incomingStreams.delete(t.streamId);return}}}dispatchIncomingStream(e){let t=!1,n=this.pendingStreamWaiters.get(e.streamName);if(n&&n.length>0){let r=n.shift();r.timer&&clearTimeout(r.timer),n.length===0&&this.pendingStreamWaiters.delete(e.streamName),r.resolve(e),t=!0}let r=this.streamHandlers.get(e.streamName);if(r&&r.size>0){r.forEach(t=>{Promise.resolve(t(e)).catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))})});return}t||(this.bufferedIncomingStreams.has(e.streamName)||this.bufferedIncomingStreams.set(e.streamName,[]),this.bufferedIncomingStreams.get(e.streamName).push(e))}emitError(e){this.errorHandlers.forEach(t=>t(e))}async send(e){await S(this.endpoint,e)}ensureOpen(){if(this.closed)throw Error(`IPC channel closed`)}};function b(e){return new y(process,e)}function x(e,t){let n=e,r=e=>{w(e)&&t(e)};return n.on(`message`,r),()=>n.off(`message`,r)}function S(e,t){let n=e;if(typeof n.send!=`function`)throw Error(`IPC channel not available`);return new Promise((e,r)=>{n.send(t,t=>{if(t){r(t);return}e()})})}function C(e){return!!(e&&typeof e==`object`&&`on`in e&&typeof e.on==`function`&&`off`in e&&typeof e.off==`function`)}function w(e){return!!(e&&typeof e==`object`&&`messageType`in e)}function T(e){return e.messageType===`event`&&e.method===_}function E(e){return!!(e&&typeof e==`object`&&v in e&&`hasOutputStream`in e)}function D(e){return!!(e&&typeof e==`object`&&v in e)}function O(e){return typeof e==`string`?{code:`HANDLER_ERROR`,message:e}:(e instanceof Error,{code:e.code??`HANDLER_ERROR`,message:e.message,...e.stack===void 0?{}:{stack:e.stack}})}function k(e){return Object.assign(Error(e.message),{code:e.code,stack:e.stack})}function A(e){return e instanceof a?e.values():e}function j(e){return`__plugin_ipc_request_input_stream__:${e}`}function M(e){return`__plugin_ipc_request_output_stream__:${e}`}var N=class{constructor(e,t={}){this.channel=e,this.options=t}async uploadFile(e){try{let t=await this.channel.requestDuplex(`__host_invoke__`,{method:p.uploadFile,args:{contentType:e.contentType,fileName:e.fileName}},{requestId:n(),traceId:this.options.invocationId,input:Buffer.isBuffer(e.file)?r.Readable.from(e.file):e.file});return m(f.parse(t.result))}catch(e){return h({en:`Failed to upload file`,"zh-CN":`上传文件失败`},e)}}};const P=e.enum([`en`,`zh-CN`,`zh-Hant`]).enum;e.object({[P.en]:e.string(),[P[`zh-CN`]]:e.string().optional(),[P[`zh-Hant`]]:e.string().optional()});const F=e.object({[P.en]:e.string(),[P[`zh-CN`]]:e.string(),[P[`zh-Hant`]]:e.string()});e.object({pluginId:e.string(),version:e.string(),etag:e.string()});const I=e.literal(`system`).or(e.string());e.array(e.record(e.string(),F));const L=e.enum([`localPool`,`serverless`]).enum;e.object({pluginId:e.string(),version:e.string().optional(),source:I.optional()});var R=class{channel;getChannel(){if(!this.channel)throw Error(`Channel is not initialized yet.`);return this.channel}mode;checkRuntimeMode(){process.env.RUNTIME_MODE==L.localPool&&(this.mode=L.localPool),process.env.RUNTIME_MODE===`dev`&&(this.mode=`dev`)}async init(){this.checkRuntimeMode(),this.mode===`localPool`&&(this.channel=b(),setImmediate(()=>this.getChannel().sendReady())),this.mode===`dev`&&(this.channel=z().pluginChannel,setImmediate(()=>this.getChannel().sendReady()))}constructor(){this.init()}};function z(){let e=globalThis.__FASTGPT_PLUGIN_LOCAL_DEBUG_RUNTIME__;if(!e)throw Error(`Local debug runtime is not initialized. Set it before importing the plugin.`);return e}function B(e){return e}var V=class t extends R{toolHandlers=new Map;childManifests=new Map;secretSchema=e.record(e.string(),e.unknown());constructor(e){super(),this.userToolManifest=e,this.mode&&this.getChannel().setRequestHandler(async e=>{if(e.method===`run`)try{let{input:t,systemVar:n,childId:r,secrets:i}=e.params,o=this.toolHandlers.get(r??`tool`);if(!o)throw Error(`No tool registered`);let s=a.create(),c=a.create();s.onData(e=>{c.send({type:`stream`,data:e})});let l=await o.handler(t,{systemVar:n,secrets:i,invoke:new N(this.getChannel(),{invocationId:e.traceId}),streamResponse:e=>{s.send(e)}});return c.send({type:`response`,data:l}),c.end(),this.getChannel().replyDuplex(e,void 0,{output:c})}catch(t){let n=a.create();return n.write({data:s(t),type:`error`}),n.end(),this.getChannel().replyDuplex(e,void 0,{output:n})}})}setSecretSchema(e){this.secretSchema=e}registerTool(e,t=`tool`,n){this.toolHandlers.set(t,e),n&&this.childManifests.set(t,n)}static getInstance(e){return new t(e)}getSecretSchema(){return this.secretSchema}getToolHandler(e=`tool`){return this.toolHandlers.get(e)}getUserToolManifest(){return this.userToolManifest}getChildManifests(){return[...this.childManifests.values()]}};const H=({manifest:t,handler:n})=>{let r=V.getInstance(t);return r.setSecretSchema(n.secretSchema??e.object()),r.registerTool(n),r},U=({manifest:t,children:n,secretSchema:r})=>{let i=V.getInstance(t);return n.forEach(e=>{i.registerTool(e.handler,e.id,{id:e.id,description:e.description,name:e.name,...e.icon===void 0?{}:{icon:e.icon},...e.toolDescription===void 0?{}:{toolDescription:e.toolDescription}})}),i.setSecretSchema(r??e.object()),i};export{B as createToolHandler,H as defineTool,U as defineToolSet};
+import e from"zod";import{Readable as t}from"node:stream";import n,{Readable as r}from"stream";import{randomUUID as i}from"node:crypto";var a=class e{stream;closed=!1;constructor(e){this.stream=new t({objectMode:!0,read(){}}),e?.(this)}static create(t){return new e(t)}write(e){this.ensureWritable(),this.stream.push(e)}send(e){this.write(e)}close(){this.closed||(this.closed=!0,this.stream.push(null))}end(){this.close()}fail(e){this.closed=!0,this.stream.destroy(e)}toReadable(){return this.stream}onData(e){return this.stream.on(`data`,e),this}onEnd(e){return this.stream.on(`end`,e),this}onError(e){return this.stream.on(`error`,e),this}async consume(e){for await(let t of this.values())await e(t)}async*values(){for await(let e of this.stream)yield e}ensureWritable(){if(this.closed||this.stream.destroyed)throw Error(`StreamData is already closed`)}};const o={ready:`client.ready`,stdio:`client.stdio`,fail:`client.fail`,request:`client.request`},s=e.enum([o.ready,o.stdio,o.fail,o.request]);e.object({pid:e.number().optional(),version:e.string().optional(),runtimeMode:e.string().optional(),capabilities:e.array(e.string()).optional(),startedAt:e.number().optional(),meta:e.unknown().optional()}),e.object({stream:e.enum([`stdout`,`stderr`]),chunk:e.string(),timestamp:e.number().optional()}),e.object({reason:e.enum([`startup`,`runtime`,`crash`,`shutdown`,`unknown`]),error:e.object({code:e.string(),message:e.string(),data:e.unknown().optional()}).optional(),exitCode:e.number().nullable().optional(),signal:e.string().nullable().optional(),timestamp:e.number().optional()});const c={streamFrame:`channel.stream`},l=e.enum([c.streamFrame]),u={request:`host.request`,ping:`host.ping`,shutdown:`host.shutdown`},ee=e.enum([u.request,u.ping,u.shutdown]);e.object({timestamp:e.number()}),e.object({timestamp:e.number(),receivedAt:e.number().optional()}),e.object({reason:e.string().optional(),timeoutMs:e.number().nonnegative().optional()}),e.object({accepted:e.boolean(),message:e.string().optional()}),e.union([s,l,ee]);const d=e.enum([`en`,`zh-CN`,`zh-Hant`]).enum,te=e.object({[d.en]:e.string(),[d[`zh-CN`]]:e.string().optional(),[d[`zh-Hant`]]:e.string().optional()}),ne=e.object({[d.en]:e.string(),[d[`zh-CN`]]:e.string(),[d[`zh-Hant`]]:e.string()}),f=e.literal(`1.0`),p=e.union([e.string(),e.number()]),m=e.object({code:e.string(),message:e.string(),reason:te.optional(),data:e.unknown().optional(),cause:e.lazy(()=>m).optional()}),h={parseError:`PARSE_ERROR`,invalidMessage:`INVALID_MESSAGE`,methodNotFound:`METHOD_NOT_FOUND`,invalidParams:`INVALID_PARAMS`,internalError:`INTERNAL_ERROR`,requestTimeout:`REQUEST_TIMEOUT`,channelClosed:`CHANNEL_CLOSED`,streamError:`STREAM_ERROR`},g=e.object({protocol:f,id:p,method:e.string(),params:e.unknown().optional(),traceId:e.string().optional(),timestamp:e.number().optional()}),re=g.omit({id:!0}),ie=e.object({protocol:f,id:p,result:e.unknown().optional(),traceId:e.string().optional(),timestamp:e.number().optional()}),ae=e.object({protocol:f,id:p,error:m,traceId:e.string().optional(),timestamp:e.number().optional()});e.union([g,re,ie,ae]),e.enum([`ipc`,`tcp`,`http`]),e.enum([`host`,`client`]),e.object({streamId:e.string(),streamName:e.string(),meta:e.unknown().optional()}),e.discriminatedUnion(`type`,[e.object({type:e.literal(`start`),streamId:e.string(),streamName:e.string(),meta:e.unknown().optional()}),e.object({type:e.literal(`chunk`),streamId:e.string(),chunk:e.unknown()}),e.object({type:e.literal(`end`),streamId:e.string()}),e.object({type:e.literal(`error`),streamId:e.string(),error:m})]);const oe=e=>(e=e.replace(/(?<=https?:\/\/)[^\s]+/g,`xxx`),e=e.replace(/ns-[\w-]+/g,`xxx`),e),_=(e,t=``)=>oe(v(e)||t),v=(e,t=0)=>t>5?void 0:typeof e==`string`?e:!e||typeof e!=`object`?void 0:ce(e,t)||se(e,t)||le(y(e?.response?.data,t),y(e?.response?.body,t),y(e?.body,t),x(e?.response?.data?.error?.reason),x(e?.response?.error?.reason),x(e?.error?.reason),x(e?.response?.data?.reason),x(e?.response?.reason),e?.response?.data?.message||e?.response?.data?.error?.message||e?.response?.error?.message||e?.error?.message||e?.response?.message||e?.message||e?.response?.data?.msg||e?.response?.msg||e?.msg,x(e?.response?.data?.error),x(e?.response?.error),x(e?.error),x(e?.reason),v(e?.error,t+1),v(e?.cause,t+1),x(e)),se=(e,t)=>{if(!(!(`reason`in e)||!(`cause`in e)))return S(x(e.reason),b(e.cause,t+1))},ce=(e,t)=>{if(`error`in e)return S(x(e.reason),v(e.error,t+1))},y=(e,t)=>{if(e){if(typeof e!=`string`)return v(e,t+1);try{let n=JSON.parse(e);return v(n?.error,t+1)||v(n,t+1)}catch{return e||void 0}}},b=(e,t)=>!e||typeof e!=`object`?v(e,t):S(x(e.reason),`cause`in e?b(e.cause,t+1):void 0)??v(e,t),x=e=>{if(!e||typeof e!=`object`)return;let t=e,n=t[`zh-CN`]??t.en??t[`zh-Hant`];return typeof n==`string`?n:void 0},le=(...e)=>e.find(e=>typeof e==`string`&&e.length>0),S=(...e)=>{let t=e.filter((t,n)=>!!t&&e.indexOf(t)===n).filter((e,t,n)=>!n.some((n,r)=>r>t&&n.startsWith(`${e}:`)));return t.length>0?t.join(`: `):void 0},ue=`application/javascript,application/json,application/yaml,application/zip,image/jpeg,image/png,image/gif,image/webp,image/svg+xml,application/pdf,text/plain,text/csv,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.openxmlformats-officedocument.presentationml.presentation,application/msword,application/vnd.ms-excel,application/vnd.ms-powerpoint,text/markdown,audio/mpeg,video/mp4,audio/wav,text/html,application/xml,application/gzip,application/octet-stream,multipart/form-data,text/event-stream`.split(`,`),C=e.enum(ue).and(e.string().regex(/^[^/]+\/[^/]+$/)),de=e.object({fileKey:e.string(),fileName:e.string(),contentType:C,size:e.number(),etag:e.string(),createTime:e.date()}),fe=e.object({fileKey:e.string().optional(),path:e.string().optional(),fileName:e.string().optional(),contentType:C.optional(),overwrite:e.boolean().optional(),file:e.union([e.instanceof(r,{error:`Stream cannot be empty`}),e.union([e.instanceof(Buffer,{error:`Buffer is required`}),e.instanceof(Uint8Array,{error:`Uint8Array is required`})]).transform(e=>e instanceof Uint8Array&&!(e instanceof Buffer)?Buffer.from(e):e)])});e.object({...fe.omit({fileKey:!0,overwrite:!0,path:!0}).shape});const pe=e.object({...de.omit({fileKey:!0}).partial().shape,accessURL:e.string()});e.object({username:e.string(),contact:e.string().nullish(),memberName:e.string().nullish(),orgs:e.array(e.object({pathId:e.string(),name:e.string()})),groups:e.array(e.object({name:e.string()}))});const w=e.enum([`uploadFile`,`userInfo`,`wecomCorpToken`]).enum,me={en:`Internal Server Error`,"zh-CN":`服务器内部错误`},T=new Map;var E=class extends Error{code;reason;httpStatus;telemetryKind;visibility;severity;data;constructor(e,t={}){super(t.message??e.message,{cause:M(t.cause)}),this.name=`RegisteredError`,this.code=e.code,this.reason=t.reason??e.reason,this.httpStatus=e.httpStatus??500,this.telemetryKind=e.telemetryKind,this.visibility=e.visibility??`public`,this.severity=e.severity??`expected`,this.data=t.data}};function he(e){for(let t of e){if(T.get(t.code))throw Error(`Error definition already registered: ${t.code}`);T.set(t.code,t)}}function ge(e){return T.get(e)}function D(e,t={}){let n=M(t.cause),r=n===void 0?Error(e.en):Error(e.en,{cause:n});return Object.assign(r,{reason:e})}function O(e,t=`Unknown error`){if(e instanceof Error)return e;if(typeof e==`string`)return Error(e);if(I(e))return D(e);if(R(e)){let n=I(e.reason)?e.reason:void 0,r=O(e.error,n?.en??t);return n&&be(n,k(r))?r:n?D(n,{cause:r}):Error(t,{cause:r})}return Error(F(e,t),{cause:e})}function k(e,t){if(e instanceof E)return e.visibility===`internal`?me:e.reason;if(I(e))return e;let n=L(e)?e:void 0;return n&&I(n.reason)?n.reason:n&&I(n.error)?n.error:t||(e instanceof Error?{en:e.message,"zh-CN":e.message}:typeof e==`string`?{en:e,"zh-CN":e}:me)}function A(e,t){return N(e,{includeStack:t?.includeStack??!1,depth:0,seen:new WeakSet})}function j(e){let t=e.cause?j(e.cause):void 0,n=e.code?ge(e.code):void 0;if(n){let r=new E(n,{message:e.message,reason:e.reason,cause:t,data:L(e.data)?e.data:void 0});return e.stack&&(r.stack=e.stack),r}let r=Error(e.message,{cause:t});return r.name=e.name||`Error`,e.stack&&(r.stack=e.stack),Object.assign(r,{...e.code===void 0?{}:{code:e.code},...e.reason===void 0?{}:{reason:e.reason},...e.data===void 0?{}:{data:e.data}})}function M(e){return e===void 0||e instanceof Error?e:typeof e==`string`?Error(e):I(e)?D(e):R(e)?O(e):e}function N(e,t){if(t.depth>5)return{name:`Error`,message:`Error cause depth exceeded`};if(e instanceof E)return{name:e.name,code:e.code,message:e.message,reason:e.reason,httpStatus:e.httpStatus,telemetryKind:e.telemetryKind,visibility:e.visibility,data:e.data,...t.includeStack&&e.stack!==void 0?{stack:e.stack}:{},...e.cause===void 0?{}:{cause:N(e.cause,P(t,e))}};if(e instanceof Error){let n=ve(e,`reason`);return{name:e.name,code:_e(e,`code`),message:e.message,...n===void 0?{}:{reason:n},data:ye(e,`data`),...t.includeStack&&e.stack!==void 0?{stack:e.stack}:{},...e.cause===void 0?{}:{cause:N(e.cause,P(t,e))}}}return typeof e==`string`?{name:`Error`,message:e}:{name:`Error`,message:F(e,`Unknown error`)}}function P(e,t){return e.seen.has(t)?{...e,depth:6}:(e.seen.add(t),{...e,depth:e.depth+1})}function F(e,t){if(e==null)return t;if(L(e)){let t=e.message??e.msg;if(typeof t==`string`&&t.length>0)return t}return String(e)}function _e(e,t){let n=e[t];return typeof n==`string`?n:void 0}function ve(e,t){let n=e[t];return I(n)?n:void 0}function ye(e,t){return e[t]}function I(e){return L(e)&&typeof e.en==`string`&&(e[`zh-CN`]===void 0||typeof e[`zh-CN`]==`string`)&&(e[`zh-Hant`]===void 0||typeof e[`zh-Hant`]==`string`)}function be(e,t){return e.en===t.en&&e[`zh-CN`]===t[`zh-CN`]&&e[`zh-Hant`]===t[`zh-Hant`]}function L(e){return!!(e&&typeof e==`object`)}function R(e){return L(e)&&`error`in e&&(`reason`in e||L(e.error))}const z=e=>[e,null];function B(e,t){return xe(e)?[null,V(e.reason,e.error,e)]:e instanceof Error?[null,V(k(e),e)]:[null,V(e,t===void 0?D(e):Se(e,t))]}function xe(e){return!!(e&&typeof e==`object`&&`reason`in e&&`error`in e)}function Se(e,t){return D(e,{cause:O(t,e.en)})}function V(e,t,n){let r=A(t),i=n?.code??r.code,a=n?.message??r.message,o=n&&`data`in n?n.data:r.data;return{reason:e,error:t,...i===void 0?{}:{code:i},...a===void 0?{}:{message:a},...o===void 0?{}:{data:o}}}var Ce=class{constructor(e,t={}){this.channel=e,this.options=t}async getWecomCorpToken(){try{let[e,t]=(await this.channel.request(o.request,{method:w.wecomCorpToken,args:{}},{traceId:this.options.invocationId})).result;return t?B({en:`Failed to get wecom corp token`,"zh-CN":`获取企业微信企业令牌失败`},t):z(e)}catch(e){return B({en:`Failed to get wecom corp token`,"zh-CN":`获取企业微信企业令牌失败`},e)}}async userInfo(){try{let[e,t]=(await this.channel.request(o.request,{method:w.userInfo,args:{}},{traceId:this.options.invocationId})).result;return t?B({en:`Failed to get user info`,"zh-CN":`获取用户信息失败`},t):z(e)}catch(e){return B({en:`Failed to get user info`,"zh-CN":`获取用户信息失败`},e)}}async uploadFile(e){try{let[t,n]=(await this.channel.request(o.request,{method:w.uploadFile,args:{contentType:e.contentType,fileName:e.fileName}},{traceId:this.options.invocationId,input:this.toUploadInputStream(e.file)})).result;return n?B({en:`Failed to upload file`,"zh-CN":`上传文件失败`},n):z(pe.parse(t))}catch(e){return B({en:`Failed to upload file`,"zh-CN":`上传文件失败`},e)}}toUploadInputStream(e){return e instanceof n.Readable?e:n.Readable.from(Buffer.from(e))}};e.object({pluginId:e.string(),version:e.string(),etag:e.string()});const we=e.literal(`system`).or(e.string()),Te=e.object({id:e.string(),name:ne});e.array(Te);const H=e.enum([`localPool`,`serverless`]).enum;e.object({pluginId:e.string(),version:e.string().optional(),source:we.optional()});const U={unknown:`common.unknown`,operationFailed:`common.operation_failed`,badRequest:`http.bad_request`,unauthorized:`http.unauthorized`,notFound:`http.not_found`,validationFailed:`http.validation_failed`,internalServerError:`http.internal_server_error`,pluginRuntimeManagerDestroyed:`plugin.runtime.manager_destroyed`,pluginRuntimeAlreadyRegistered:`plugin.runtime.already_registered`,pluginRuntimeReplacementPluginNotFound:`plugin.runtime.replacement_plugin_not_found`,pluginRuntimeConfigLoadFailed:`plugin.runtime.config_load_failed`,pluginRuntimeConfigUpdateFailed:`plugin.runtime.config_update_failed`,pluginRuntimeConfigResetFailed:`plugin.runtime.config_reset_failed`,pluginRuntimeConfigInvalid:`plugin.runtime.config_invalid`,pluginRuntimePodQuotaExceeded:`plugin.runtime.pod_quota_exceeded`,pluginRuntimePluginInfoLoadFailed:`plugin.runtime.plugin_info_load_failed`,pluginRuntimeInitializeFailed:`plugin.runtime.initialize_failed`,pluginRuntimePluginNotFound:`plugin.runtime.plugin_not_found`,pluginRuntimeEventNotSupported:`plugin.runtime.event_not_supported`,pluginRuntimeShutdownFailed:`plugin.runtime.shutdown_failed`,pluginInvokeFailed:`plugin.invoke.failed`,pluginInvokeTimeout:`plugin.invoke.timeout`,pluginInvokeQueueTimeout:`plugin.invoke.queue_timeout`};he([{code:U.unknown,message:`Unknown error`,reason:{en:`Unknown error`,"zh-CN":`未知错误`},visibility:`internal`,severity:`unexpected`},{code:U.operationFailed,message:`Operation failed`,reason:{en:`Operation failed`,"zh-CN":`操作失败`}},{code:U.badRequest,message:`Bad Request`,reason:{en:`Bad Request`,"zh-CN":`请求参数错误`},httpStatus:400},{code:U.unauthorized,message:`Unauthorized`,reason:{en:`Unauthorized`,"zh-CN":`未授权`},httpStatus:401},{code:U.notFound,message:`Not Found`,reason:{en:`Not Found`,"zh-CN":`资源未找到`},httpStatus:404},{code:U.validationFailed,message:`Validation failed`,reason:{en:`Validation failed`,"zh-CN":`数据校验失败`},httpStatus:400},{code:U.internalServerError,message:`Internal Server Error`,reason:{en:`Internal Server Error`,"zh-CN":`服务器内部错误`},httpStatus:500,visibility:`internal`,severity:`unexpected`},{code:U.pluginRuntimeManagerDestroyed,message:`Plugin manager already destroyed`,reason:{en:`Plugin manager already destroyed`,"zh-CN":`插件管理器已销毁`}},{code:U.pluginRuntimeAlreadyRegistered,message:`Plugin already registered`,reason:{en:`Plugin already registered`,"zh-CN":`插件已注册`},httpStatus:409,telemetryKind:`plugin_already_registered`},{code:U.pluginRuntimeReplacementPluginNotFound,message:`Replacement plugin not found`,reason:{en:`Replacement plugin not found`,"zh-CN":`替换插件未找到`},httpStatus:404},{code:U.pluginRuntimeConfigLoadFailed,message:`Failed to get plugin runtime config`,reason:{en:`Failed to get plugin runtime config`,"zh-CN":`获取插件运行时配置失败`},telemetryKind:`runtime_config_load_failed`},{code:U.pluginRuntimeConfigUpdateFailed,message:`Failed to update plugin runtime config`,reason:{en:`Failed to update plugin runtime config`,"zh-CN":`更新插件运行时配置失败`},telemetryKind:`runtime_config_update_failed`},{code:U.pluginRuntimeConfigResetFailed,message:`Failed to reset plugin runtime config`,reason:{en:`Failed to reset plugin runtime config`,"zh-CN":`重置插件运行时配置失败`},telemetryKind:`runtime_config_reset_failed`},{code:U.pluginRuntimeConfigInvalid,message:`Invalid plugin runtime config`,reason:{en:`Invalid plugin runtime config`,"zh-CN":`插件运行时配置无效`},httpStatus:400,telemetryKind:`runtime_config_invalid`},{code:U.pluginRuntimePodQuotaExceeded,message:`Pod quota exceeded`,reason:{en:`Pod quota exceeded`,"zh-CN":`Pod 配额超出`},httpStatus:429,telemetryKind:`pod_quota_exceeded`},{code:U.pluginRuntimePluginInfoLoadFailed,message:`Register plugin error, can not get plugin info`,reason:{en:`Register plugin error, can not get plugin info`,"zh-CN":`注册插件失败，无法获取插件信息`}},{code:U.pluginRuntimeInitializeFailed,message:`Failed to initialize plugin runtime`,reason:{en:`Failed to initialize plugin runtime`,"zh-CN":`初始化插件运行时失败`},telemetryKind:`plugin_runtime_initialize_failed`},{code:U.pluginRuntimePluginNotFound,message:`Plugin not found`,reason:{en:`Plugin not found`,"zh-CN":`插件未找到`},httpStatus:404},{code:U.pluginRuntimeEventNotSupported,message:`Event not supported`,reason:{en:`Event not supported`,"zh-CN":`不支持的事件`},httpStatus:400},{code:U.pluginRuntimeShutdownFailed,message:`Error during shutdown`,reason:{en:`Error during shutdown`,"zh-CN":`关闭过程中发生错误`},telemetryKind:`runtime_shutdown_failed`},{code:U.pluginInvokeFailed,message:`Invoke failed`,reason:{en:`Invoke failed`,"zh-CN":`调用失败`},telemetryKind:`invoke_failed`},{code:U.pluginInvokeTimeout,message:`Plugin invocation timed out`,reason:{en:`Plugin invocation timed out`,"zh-CN":`插件调用超时`},httpStatus:504,telemetryKind:`invoke_timeout`},{code:U.pluginInvokeQueueTimeout,message:`Plugin invocation waited too long for an available local-pool pod`,reason:{en:`Plugin invocation waited too long for an available local-pool pod`,"zh-CN":`插件调用等待空闲本地运行实例超时`},httpStatus:503,telemetryKind:`queue_timeout`}]);const W=`__fastgptChannelReply__`,G=`__fastgptChannelError__`;var Ee=class{transport=`ipc`;pending=new Map;errorHandlers=new Set;closeHandlers=new Set;incomingStreams=new Map;bufferedIncomingStreams=new Map;pendingStreamWaiters=new Map;requestHandler=null;notificationHandler=null;closed=!1;unsubscribeMessage;constructor(e,t,n={}){this.side=e,this.endpoint=t,this.options=n,this.unsubscribeMessage=Oe(t,e=>{this.dispatch(e).catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))})})}async request(e,t,n){this.ensureOpen();let r=n?.id??i(),a=n?.timeoutMs??this.options.defaultTimeoutMs??3e4,o=n?.input===void 0?void 0:this.pipeStream(Re(r),n.input,{traceId:n.traceId,streamId:n.inputStream?.streamId,streamName:n.inputStream?.streamName,meta:n.inputStream?.meta}),s=Date.now();o&&o.catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))});let c=await new Promise((i,o)=>{let s=setTimeout(()=>{this.pending.delete(r),o(Object.assign(Error(`Request timeout: ${String(e)}`),{code:h.requestTimeout,requestId:r,method:e}))},a);this.pending.set(r,{method:String(e),resolve:i,reject:o,timer:s}),this.send({protocol:`1.0`,id:r,method:String(e),params:t,...n?.traceId===void 0?{}:{traceId:n.traceId},timestamp:Date.now()}).catch(e=>{clearTimeout(s),this.pending.delete(r),o(e)})}),l=c,u;if(Pe(c)&&(l=c.result,c.hasOutputStream)){let e=Date.now()-s,t=Math.max(1,a-e);u=await this.waitForStream(Q(r),{timeoutMs:t})}return{requestId:r,result:l,...u===void 0?{}:{output:u},...o===void 0?{}:{inputDone:o}}}async notify(e,t,n){this.ensureOpen(),await this.send({protocol:`1.0`,method:String(e),params:t,...n?.traceId===void 0?{}:{traceId:n.traceId},timestamp:Date.now()})}setRequestHandler(e){this.requestHandler=e}setNotificationHandler(e){this.notificationHandler=e}async waitForStream(e,t){this.ensureOpen();let n=this.bufferedIncomingStreams.get(e);if(n&&n.length>0){let t=n.shift();return n.length===0&&this.bufferedIncomingStreams.delete(e),t}return new Promise((n,r)=>{let i={resolve:n,reject:r};t?.timeoutMs!==void 0&&(i.timer=setTimeout(()=>{let t=this.pendingStreamWaiters.get(e);if(!t)return;let n=t.indexOf(i);n>=0&&t.splice(n,1),t.length===0&&this.pendingStreamWaiters.delete(e),r(Error(`Wait stream timeout: ${e}`))},t.timeoutMs)),this.pendingStreamWaiters.has(e)||this.pendingStreamWaiters.set(e,[]),this.pendingStreamWaiters.get(e).push(i)})}async createWritableStream(e,t){this.ensureOpen();let n=t?.streamId??i(),r=!1,a=t?.streamName??e;return await this.sendStreamFrame({type:`start`,streamId:n,streamName:a,...t?.meta===void 0?{}:{meta:t.meta}},t?.traceId),{streamId:n,streamName:a,...t?.meta===void 0?{}:{meta:t.meta},write:async e=>{if(r)throw Error(`Stream is already closed: ${n}`);await this.sendStreamFrame({type:`chunk`,streamId:n,chunk:e},t?.traceId)},end:async()=>{r||(r=!0,await this.sendStreamFrame({type:`end`,streamId:n},t?.traceId))},fail:async e=>{r||(r=!0,await this.sendStreamFrame({type:`error`,streamId:n,error:K(e)},t?.traceId))}}}async pipeStream(e,t,n){let r=await this.createWritableStream(e,n);try{for await(let e of Le(t))await r.write(e);await r.end()}catch(e){throw await r.fail(e instanceof Error?e:Error(String(e))),e}}onError(e){return this.errorHandlers.add(e),()=>{this.errorHandlers.delete(e)}}onClose(e){return this.closeHandlers.add(e),()=>{this.closeHandlers.delete(e)}}async close(e=Error(`Channel closed`)){this.closed||(this.closed=!0,this.unsubscribeMessage(),this.rejectAllPending(e),this.rejectAllPendingStreamWaiters(e),this.failAllIncomingStreams(e),this.closeHandlers.forEach(t=>t(e)))}createReply(e,t){return{[W]:!0,...e===void 0?{}:{result:e},...t?.output===void 0?{}:{output:t.output},...t?.outputStream===void 0?{}:{outputStream:t.outputStream}}}async dispatch(e){if(!this.closed){if(Me(e)){this.handleResponse(e);return}if(je(e)){await this.handleRequest(e);return}await this.handleNotification(e)}}handleResponse(e){let t=this.pending.get(e.id);if(t){if(clearTimeout(t.timer),this.pending.delete(e.id),`error`in e){t.reject(q(e.error));return}t.resolve(X(e.result))}}async handleRequest(e){if(!this.requestHandler){await this.replyError(e,{code:h.methodNotFound,message:`Method not found: ${e.method}`});return}try{let t=await this.requestHandler({id:e.id,method:e.method,params:e.params,...e.traceId===void 0?{}:{traceId:e.traceId},raw:e,waitForInputStream:t=>this.waitForStream(Re(e.id),t)});if(Ne(t)){await this.handleReplyDescriptor(e,t);return}await this.reply(e,t)}catch(t){await this.replyError(e,t instanceof Error?t:Error(String(t)))}}async handleNotification(e){if(e.method===c.streamFrame){await this.handleStreamFrame(e.params,e.traceId);return}await this.notificationHandler?.({method:e.method,params:e.params,...e.traceId===void 0?{}:{traceId:e.traceId},raw:e})}async handleReplyDescriptor(e,t){t.output!==void 0&&this.pipeStream(Q(e.id),t.output,{traceId:t.outputStream?.traceId??e.traceId,streamId:t.outputStream?.streamId,streamName:t.outputStream?.streamName,meta:t.outputStream?.meta}).catch(e=>{this.emitError(e instanceof Error?e:Error(String(e)))}),await this.reply(e,{[W]:!0,hasOutputStream:t.output!==void 0,...t.result===void 0?{}:{result:t.result}})}async reply(e,t){await this.send({protocol:`1.0`,id:e.id,...t===void 0?{}:{result:Y(t)},...e.traceId===void 0?{}:{traceId:e.traceId},timestamp:Date.now()})}async replyError(e,t){await this.send({protocol:`1.0`,id:e.id,error:K(t),...e.traceId===void 0?{}:{traceId:e.traceId},timestamp:Date.now()})}async sendStreamFrame(e,t){await this.notify(c.streamFrame,e,{traceId:t})}async handleStreamFrame(e,t){switch(e.type){case`start`:{let n={streamId:e.streamId,streamName:e.streamName,stream:a.create(),...t===void 0?{}:{traceId:t},...e.meta===void 0?{}:{meta:e.meta}};this.incomingStreams.set(e.streamId,n),this.dispatchIncomingStream(n);return}case`chunk`:{let t=this.incomingStreams.get(e.streamId);if(!t){this.emitError(Error(`Stream not found: ${e.streamId}`));return}t.stream.write(e.chunk);return}case`end`:{let t=this.incomingStreams.get(e.streamId);if(!t)return;t.stream.end(),this.incomingStreams.delete(e.streamId);return}case`error`:{let t=this.incomingStreams.get(e.streamId);if(!t)return;t.stream.fail(q(e.error)),this.incomingStreams.delete(e.streamId);return}}}dispatchIncomingStream(e){let t=!1,n=this.pendingStreamWaiters.get(e.streamName);if(n&&n.length>0){let r=n.shift();r.timer&&clearTimeout(r.timer),n.length===0&&this.pendingStreamWaiters.delete(e.streamName),r.resolve(e),t=!0}t||(this.bufferedIncomingStreams.has(e.streamName)||this.bufferedIncomingStreams.set(e.streamName,[]),this.bufferedIncomingStreams.get(e.streamName).push(e))}rejectAllPending(e){this.pending.forEach((t,n)=>{clearTimeout(t.timer),t.reject(e),this.pending.delete(n)})}rejectAllPendingStreamWaiters(e){this.pendingStreamWaiters.forEach((t,n)=>{t.forEach(t=>{t.timer&&clearTimeout(t.timer),t.reject(e)}),this.pendingStreamWaiters.delete(n)})}failAllIncomingStreams(e){this.incomingStreams.forEach((t,n)=>{t.stream.fail(e),this.incomingStreams.delete(n)}),this.bufferedIncomingStreams.clear()}emitError(e){this.errorHandlers.forEach(t=>t(e))}async send(e){await ke(this.endpoint,e)}ensureOpen(){if(this.closed)throw Error(`Channel closed`)}};function De(e){return new Ee(`client`,process,e)}function Oe(e,t){let n=e,r=e=>{Ae(e)&&t(e)};return n.on(`message`,r),()=>n.off(`message`,r)}function ke(e,t){let n=e;if(typeof n.send!=`function`)throw Error(`IPC channel not available`);return new Promise((e,r)=>{n.send(t,t=>{if(t){r(t);return}e()})})}function Ae(e){return!!(e&&typeof e==`object`&&`protocol`in e)}function je(e){return`id`in e&&`method`in e}function Me(e){return`id`in e&&!(`method`in e)&&(`result`in e||`error`in e)}function Ne(e){return!!(e&&typeof e==`object`&&W in e&&e[W]===!0)}function Pe(e){return!!(e&&typeof e==`object`&&W in e&&`hasOutputStream`in e)}function K(e){return typeof e==`string`?{code:h.internalError,message:e}:e instanceof Error?J(A(e)):e}function q(e){return j(Fe(e))}function J(e){return{code:e.code??h.internalError,message:e.message,...e.reason===void 0?{}:{reason:e.reason},...e.data===void 0?{}:{data:e.data},...e.cause===void 0?{}:{cause:J(e.cause)}}}function Fe(e){return{name:`Error`,code:e.code,message:e.message,reason:e.reason,data:e.data,...e.cause===void 0?{}:{cause:Fe(e.cause)}}}function Y(e,t=new WeakSet){return e instanceof Error?{[G]:!0,error:A(e)}:!e||typeof e!=`object`||t.has(e)?e:(t.add(e),Array.isArray(e)?e.map(e=>Y(e,t)):Z(e)?Object.fromEntries(Object.entries(e).map(([e,n])=>[e,Y(n,t)])):e)}function X(e,t=new WeakMap){if(Ie(e))return j(e.error);if(!e||typeof e!=`object`)return e;let n=t.get(e);if(n)return n;if(Array.isArray(e)){let n=[];return t.set(e,n),n.push(...e.map(e=>X(e,t))),n}if(!Z(e))return e;let r={};t.set(e,r);for(let[n,i]of Object.entries(e))r[n]=X(i,t);return r}function Ie(e){return Z(e)&&e[G]===!0&&Z(e.error)&&typeof e.error.name==`string`&&typeof e.error.message==`string`}function Z(e){if(!e||typeof e!=`object`)return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function Le(e){return e instanceof a?e.values():e}function Re(e){return`request.input:${String(e)}`}function Q(e){return`request.output:${String(e)}`}var ze=class{channel;getChannel(){if(!this.channel)throw Error(`Channel is not initialized yet.`);return this.channel}mode;checkRuntimeMode(){process.env.RUNTIME_MODE==H.localPool&&(this.mode=H.localPool),process.env.RUNTIME_MODE===`dev`&&(this.mode=`dev`)}async init(){this.checkRuntimeMode(),this.mode===`localPool`&&(this.channel=De(),setImmediate(()=>{this.getChannel().notify(o.ready,{pid:process.pid,runtimeMode:H.localPool,startedAt:Date.now()})})),this.mode===`dev`&&(this.channel=Be().pluginChannel,setImmediate(()=>{this.getChannel().notify(o.ready,{pid:process.pid,runtimeMode:`dev`,startedAt:Date.now()})}))}constructor(){this.init()}};function Be(){let e=globalThis.__FASTGPT_PLUGIN_LOCAL_DEBUG_RUNTIME__;if(!e)throw Error(`Local debug runtime is not initialized. Set it before importing the plugin.`);return e}function Ve(e){return e}var $=class t extends ze{toolHandlers=new Map;childManifests=new Map;secretSchema=e.record(e.string(),e.unknown());constructor(e){super(),this.userToolManifest=e,this.mode&&this.getChannel().setRequestHandler(async e=>{if(e.method===u.request&&e.params.eventName===`run`)try{let{input:t,systemVar:n,childId:r,secrets:i}=e.params.payload,o=this.toolHandlers.get(r??`tool`);if(!o)throw Error(`No tool registered`);let s=a.create();return(async()=>{try{let r=await o.handler(t,{systemVar:n,secrets:i,invoke:new Ce(this.getChannel(),{invocationId:e.traceId}),streamResponse:e=>{s.send({type:`stream`,data:e})}});s.send({type:`response`,data:r})}catch(e){s.send({data:_(e,`Unknown error during tool execution`),type:`error`})}finally{s.end()}})(),this.getChannel().createReply(void 0,{output:s})}catch(e){let t=a.create();return t.write({data:_(e,`Unknown error during tool execution`),type:`error`}),t.end(),this.getChannel().createReply(void 0,{output:t})}})}setSecretSchema(e){this.secretSchema=e}registerTool(e,t=`tool`,n){this.toolHandlers.set(t,e),n&&this.childManifests.set(t,n)}static getInstance(e){return new t(e)}getSecretSchema(){return this.secretSchema}getToolHandler(e=`tool`){return this.toolHandlers.get(e)}getUserToolManifest(){return this.userToolManifest}getChildManifests(){return[...this.childManifests.values()]}};const He=({manifest:t,handler:n})=>{let r=$.getInstance(t);return r.setSecretSchema(n.secretSchema??e.object()),r.registerTool(n),r},Ue=({manifest:t,children:n,secretSchema:r})=>{let i=$.getInstance(t);return n.forEach(e=>{i.registerTool(e.handler,e.id,{id:e.id,description:e.description,name:e.name,...e.icon===void 0?{}:{icon:e.icon},...e.toolDescription===void 0?{}:{toolDescription:e.toolDescription}})}),i.setSecretSchema(r??e.object()),i};export{Ve as createToolHandler,He as defineTool,Ue as defineToolSet};

package/package.json

@@ -1,20 +1,14 @@
 {
   "name": "@fastgpt-plugin/sdk-factory",
-  "version": "0.0.1-alpha.1",
-  "dependencies": {
-    "@fastgpt-plugin/domain": "workspace:*",
-    "@fastgpt-plugin/infrastructure": "workspace:*"
-  },
-  "scripts": {
-    "build": "tsdown"
-  },
+  "version": "0.0.1-alpha.10",
   "devDependencies": {
-    "tsdown": "catalog:"
+    "tsdown": "^0.21.10"
   },
   "type": "module",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -29,5 +23,8 @@
   "private": false,
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}

package/skills/fastgpt-plugin-development/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: fastgpt-plugin-development
+description: Use as the entry skill when a user wants to develop a FastGPT plugin. Identify the plugin category, then route to the matching specialized skill such as fastgpt-system-tool-development.
+---
+
+# FastGPT 插件开发入口
+
+在用户要开发 FastGPT 插件时先使用这个 skill。它只负责判断插件类型和选择后续规范，具体实现规则放在对应专项 skill 中。
+
+## 类型判断
+
+先确认用户要开发的插件类型：
+
+- 系统工具：通过 `@fastgpt-plugin/sdk-factory` 暴露 `defineTool()` 或 `defineToolSet()`，由 FastGPT 作为工具调用。
+- 其他插件类型：按后续新增的专项 skill 处理。
+
+当前已支持：
+
+- `fastgpt-system-tool-development`: 系统工具插件开发规范，文件位于 `../fastgpt-system-tool-development/SKILL.md`。
+
+## 路由规则
+
+- 用户提到系统工具、tool、tool-suite、工具调用、`defineTool()`、`defineToolSet()`、`createToolHandler()` 时，继续读取 `../fastgpt-system-tool-development/SKILL.md`。
+- 用户只说“开发插件”且没有说明类型时，先根据需求判断是否属于系统工具；能判断时直接进入对应专项 skill。
+- 无法判断插件类型时，先询问用户插件要暴露成哪类能力，再进入对应专项 skill。
+
+## 通用原则
+
+- 入口 skill 不承载具体插件代码模板。
+- 专项 skill 负责说明插件怎么写、目录包含哪些内容、通过什么工具写和验证。
+- 新增插件类型时，在这里补一条类型说明和对应 skill 名称。

package/skills/fastgpt-sdk-factory/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: fastgpt-sdk-factory
+description: Use when creating, reviewing, or modifying FastGPT Tool Plugins with the @fastgpt-plugin/sdk-factory TypeScript SDK, including defineTool, defineToolSet, createToolHandler, Zod input/output schemas, secretSchema, ctx.invoke host calls, and streaming tool responses.
+---
+
+# FastGPT SDK Factory
+
+Use this skill when working on a FastGPT Tool Plugin that imports `@fastgpt-plugin/sdk-factory` or the local `sdk/factory` package.
+
+## Core Pattern
+
+Plugin entry files default-export the instance returned by `defineTool()` or `defineToolSet()`.
+
+```ts
+import {
+  createToolHandler,
+  defineTool,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    text: z.string().meta({
+      title: 'Text'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    result: z.string().meta({
+      title: 'Result'
+    } satisfies OutputSchemaMetaType)
+  }),
+  handler: async (input) => ({
+    result: input.text.toUpperCase()
+  })
+});
+
+export default defineTool({
+  manifest: {
+    pluginId: 'uppercase',
+    version: '1.0.0',
+    name: {
+      en: 'Uppercase',
+      'zh-CN': '转大写'
+    },
+    description: {
+      en: 'Convert text to uppercase',
+      'zh-CN': '将文本转换为大写'
+    },
+    versionDescription: {
+      en: 'Initial version',
+      'zh-CN': '初始版本'
+    },
+    tags: ['tools']
+  },
+  handler
+});
+```
+
+## Handler Rules
+
+- Define handlers with `createToolHandler({ inputSchema, outputSchema, secretSchema?, handler })`.
+- Use `z.object(...)` for `inputSchema` and `outputSchema` so TypeScript can infer `input` and return types.
+- Import `InputSchemaMetaType`, `OutputSchemaMetaType`, and `SecretSchemaMetaType` from `@fastgpt-plugin/sdk-factory` when schema metadata is used.
+- Add `.meta({ ... } satisfies InputSchemaMetaType)` to input fields and `.meta({ ... } satisfies OutputSchemaMetaType)` to output fields that need UI/manifest metadata.
+- Set `toolDescription` in an input field's `.meta()` when that field should be available as an automatically filled tool-call parameter; without `toolDescription`, users must specify the field manually.
+- Add `.meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)` to every `secretSchema` field; set `isSecret: true` for values that must be encrypted at rest.
+- Return an object that matches `outputSchema`; throw errors for failed operations.
+- Add `secretSchema` when plugin configuration needs secrets such as API keys.
+- Read secrets from `ctx.secrets`; the value is typed from `secretSchema`.
+- Use `ctx.streamResponse({ type: 'answer', content })` to emit incremental visible output before the final response.
+- Use `ctx.systemVar` only for FastGPT-provided runtime variables.
+
+```ts
+const secretSchema = z.object({
+  apiKey: z.string().meta({
+    title: 'API Key',
+    isSecret: true
+  } satisfies SecretSchemaMetaType)
+});
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string().meta({
+      title: 'Query',
+      toolDescription: 'Search query'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    answer: z.string().meta({
+      title: 'Answer'
+    } satisfies OutputSchemaMetaType)
+  }),
+  secretSchema,
+  handler: async (input, ctx) => {
+    ctx.streamResponse({
+      type: 'answer',
+      content: `Searching: ${input.query}`
+    });
+
+    return {
+      answer: `Result for ${input.query}`
+    };
+  }
+});
+```
+
+## Manifest Rules
+
+`manifest` must include these fields unless the surrounding package already supplies them:
+
+- `pluginId`: stable unique plugin id.
+- `version`: plugin version, usually semver.
+- `name`: i18n object shaped as `{ en, 'zh-CN' }`.
+- `description`: i18n object shaped as `{ en, 'zh-CN' }`.
+
+Common optional fields:
+
+- `versionDescription`
+- `author`
+- `repoUrl`
+- `tutorialUrl`
+- `tags`
+- `permission`
+- `icon`
+- `toolDescription`
+
+Use `permission` to declare host capabilities required by the plugin. It is an array of permission strings. Declare only the minimum permissions that the plugin actually uses. When using `ctx.invoke` to call host capabilities, declare the matching permission.
+
+Supported permissions:
+
+- `userInfo:read`: read user information, for example through `ctx.invoke.userInfo()`.
+- `teamInfo:read`: read team information.
+- `model:read`: read model information.
+- `dataset:read`: read dataset information.
+- `file-upload:allow`: upload files, for example through `ctx.invoke.uploadFile()`.
+
+Keep `pluginId`, child tool `id`, input field names, and output field names stable for compatibility.
+
+## Tool Sets
+
+Use `defineToolSet()` for one plugin with multiple child tools. Put shared metadata in the top-level `manifest`; put each child tool's `id`, `name`, `description`, optional `icon`, optional `toolDescription`, and `handler` in `children`.
+
+```ts
+import {
+  createToolHandler,
+  defineToolSet,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType,
+  type SecretSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const secretSchema = z.object({
+  apiKey: z.string().meta({
+    title: 'API Key',
+    isSecret: true
+  } satisfies SecretSchemaMetaType)
+});
+
+const searchHandler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string().meta({
+      title: 'Query'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    items: z.array(z.string()).meta({
+      title: 'Items'
+    } satisfies OutputSchemaMetaType)
+  }),
+  secretSchema,
+  handler: async (input) => ({ items: [input.query] })
+});
+
+export default defineToolSet({
+  secretSchema,
+  manifest: {
+    pluginId: 'text-tools',
+    version: '1.0.0',
+    name: {
+      en: 'Text Tools',
+      'zh-CN': '文本工具集'
+    },
+    description: {
+      en: 'Search and summarize text',
+      'zh-CN': '搜索和总结文本'
+    }
+  },
+  children: [
+    {
+      id: 'search',
+      name: {
+        en: 'Search',
+        'zh-CN': '搜索'
+      },
+      description: {
+        en: 'Search text',
+        'zh-CN': '搜索文本'
+      },
+      toolDescription: 'Search text by query',
+      handler: searchHandler
+    }
+  ]
+});
+```
+
+## Host Invocation
+
+Use `ctx.invoke` for host capabilities. The SDK exposes `userInfo()` and `uploadFile()`. Declare the corresponding `manifest.permission` item before using a host capability; for example, `ctx.invoke.uploadFile()` requires `file-upload:allow`. These methods return a `Result` tuple shaped as `[result, err]`; check `err` before using `result`. When `err` is present, throw or return that original `err` so host-side error details are preserved.
+
+```ts
+const uploadHandler = createToolHandler({
+  inputSchema: z.object({
+    content: z.string().meta({
+      title: 'Content'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    accessURL: z.string().meta({
+      title: 'Access URL'
+    } satisfies OutputSchemaMetaType),
+    fileName: z.string().meta({
+      title: 'File Name'
+    } satisfies OutputSchemaMetaType),
+    size: z.number().meta({
+      title: 'Size'
+    } satisfies OutputSchemaMetaType)
+  }),
+  handler: async (input, { invoke }) => {
+    const [result, err] = await invoke.uploadFile({
+      fileName: 'result.txt',
+      contentType: 'text/plain',
+      file: Buffer.from(input.content, 'utf-8')
+    });
+
+    if (err) {
+      throw err;
+    }
+    if (!result) {
+      throw new Error('Failed to upload file');
+    }
+
+    return {
+      accessURL: result.accessURL,
+      fileName: result.fileName,
+      size: result.size
+    };
+  }
+});
+```
+
+## Local Development
+
+- In external plugins, import from `@fastgpt-plugin/sdk-factory`.
+- Inside this monorepo package tests or fixtures, imports may point at `sdk/factory/src` or `../../src/index` when matching existing local patterns.
+- Build the SDK with `pnpm --filter @fastgpt-plugin/sdk-factory build`.
+- When changing SDK behavior, check `sdk/factory/src/index.ts`, `sdk/factory/src/tool-factory.ts`, `sdk/factory/src/invoke.client.ts`, and fixtures under `sdk/factory/test/fixtures/`.

package/skills/fastgpt-system-tool-development/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: fastgpt-system-tool-development
+description: Use when writing a FastGPT system tool plugin with @fastgpt-plugin/sdk-factory and @fastgpt-plugin/cli, including tool structure, SDK writing rules, required files, avatar/logo naming, and build/check/pack tooling.
+---
+
+# FastGPT 系统工具开发规范
+
+在编写 FastGPT 系统工具插件时使用这个 skill。目标是指导代理用 `@fastgpt-plugin/sdk-factory` 写出符合 FastGPT 约定的系统工具，并用 `@fastgpt-plugin/cli` 创建、构建、检查和打包。
+
+## 使用工具
+
+同时参考这些能力：
+
+- `fastgpt-sdk-factory`: 处理 `defineTool()`、`defineToolSet()`、`createToolHandler()`、Zod schema、`secretSchema`、`ctx.invoke`、`ctx.streamResponse()` 等 SDK 写法。
+- `cli-usage`: 使用 `@fastgpt-plugin/cli` 的 `create`、`build`、`check`、`pack` 命令。
+
+常用命令：
+
+```bash
+npx @fastgpt-plugin/cli create <plugin-name> --type tool --cwd <target-directory>
+```
+
+```bash
+npx @fastgpt-plugin/cli create <plugin-name> --type tool-suite --cwd <target-directory>
+```
+
+```bash
+npx @fastgpt-plugin/cli build --entry <plugin-directory> --output <plugin-directory>/dist
+```
+
+```bash
+npx @fastgpt-plugin/cli check --entry <plugin-directory> --output <plugin-directory>/dist
+```
+
+```bash
+npx @fastgpt-plugin/cli pack --entry <plugin-directory> --dist <plugin-directory>/dist --output <plugin-directory>/out
+```
+
+## 系统工具包含内容
+
+一个系统工具目录通常包含：
+
+- `index.ts`: 系统工具入口，默认导出 `defineTool()` 或 `defineToolSet()` 的返回值。
+- `package.json`: 声明依赖和 `build`、`build:dev`、`pack`、`test` 脚本。
+- `logo.<ext>`: 主工具头像，必须放在工具根目录。
+- `README.md`: 工具用途、输入、输出、密钥配置和使用说明。
+- `assets/`: 可选资源目录，例如图标或示例资源。
+- `dist/`: CLI 构建输出目录，包含 `index.js`、`manifest.json` 和必要资源。
+- `out/`: CLI 打包输出目录，通常包含 `.pkg` 文件。
+
+依赖建议：
+
+- 运行依赖：`@fastgpt-plugin/sdk-factory`、`zod`。
+- 开发依赖：`@fastgpt-plugin/cli`、`typescript`、`vitest`。
+
+## 系统工具写法
+
+入口文件必须默认导出 SDK factory 实例：
+
+- 单工具使用 `defineTool()`。
+- 多个相关工具组成一个插件时使用 `defineToolSet()`。
+- 每个 handler 用 `createToolHandler()` 定义。
+- `inputSchema` 和 `outputSchema` 使用 `z.object(...)`。
+- `inputSchema` 字段使用 `.meta({ ... } satisfies InputSchemaMetaType)`。
+- `inputSchema` 字段需要被工具调用自动填参时，必须在 `.meta()` 中设置 `toolDescription`；未设置时该字段只能由用户手动指定。
+- `outputSchema` 字段使用 `.meta({ ... } satisfies OutputSchemaMetaType)`。
+- `secretSchema` 字段使用 `.meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)`；需要加密存储的字段标记为 `isSecret: true`。
+- handler 返回值必须匹配 `outputSchema`。
+
+manifest 至少包含：
+
+- `pluginId`: 稳定唯一工具 ID。
+- `version`: 工具版本。
+- `name`: `{ en, 'zh-CN' }` 格式。
+- `description`: `{ en, 'zh-CN' }` 格式。
+
+常用可选字段：
+
+- `versionDescription`
+- `author`
+- `repoUrl`
+- `tutorialUrl`
+- `tags`
+- `permission`
+- `icon`
+- `toolDescription`
+
+`permission` 用于声明插件运行时需要的宿主能力，类型为权限字符串数组。只声明当前插件实际使用的最小权限；没有使用对应能力时不要添加。使用 `ctx.invoke` 反向调用宿主能力时，必须声明对应权限。
+
+当前可用权限：
+
+- `userInfo:read`: 读取用户信息，例如调用 `ctx.invoke.userInfo()`。
+- `teamInfo:read`: 读取团队信息。
+- `model:read`: 读取模型信息。
+- `dataset:read`: 读取知识库信息。
+- `file-upload:allow`: 上传文件，例如调用 `ctx.invoke.uploadFile()`。
+
+兼容性要求：
+
+- `pluginId`、工具 `id`、输入字段名、输出字段名对外使用后保持稳定。
+- 用户配置的密钥、API Key、Base URL 等使用 `secretSchema` 描述，通过 `ctx.secrets` 读取。
+- 错误信息应能帮助定位问题，同时避免暴露密钥、令牌和完整上游敏感响应。
+- 需要向用户展示执行进度时使用 `ctx.streamResponse()`。
+- 需要生成文件时使用 `ctx.invoke.uploadFile()`，并在 `manifest.permission` 中声明 `file-upload:allow`；收到 `[result, err]` 的 `err` 时保留原始 `err`，避免覆盖反向调用的宿主错误信息。
+
+## 头像规范
+
+CLI 构建时会自动扫描系统工具根目录中的头像文件，并写入 `manifest.icon` 或子工具 `icon` 字段。工具代码里通常不用手写 `icon`。
+
+命名方式：
+
+- 主工具头像：`logo.<ext>`，例如 `logo.svg`、`logo.png`。
+- 工具集子工具头像：`<childId>.logo.<ext>`，例如子工具 `id` 为 `search` 时使用 `search.logo.svg`。
+- 子工具没有独立头像时，CLI 会复用主工具头像。
+
+格式限制：
+
+- 支持扩展名：`.svg`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`。
+- 头像文件必须放在系统工具根目录，不能放在 `assets/` 后再通过 manifest 引用。
+- `childId` 必须和 `defineToolSet({ children })` 中的子工具 `id` 完全一致。
+- 避免使用空格、中文或特殊符号作为头像文件名的一部分。
+- `logo.*` 和 `<childId>.logo.*` 只保留一个匹配文件，避免不同扩展名同时存在导致扫描结果不明确。
+- `build` 后检查 `dist/manifest.json` 中的 `icon` 字段是否指向已复制到 `dist/` 的头像文件。
+
+## 单工具模板
+
+```ts
+import {
+  createToolHandler,
+  defineTool,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    text: z.string().min(1).meta({
+      title: 'Text',
+      toolDescription: 'Text to normalize'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    result: z.string().meta({
+      title: 'Result'
+    } satisfies OutputSchemaMetaType)
+  }),
+  handler: async (input) => {
+    return {
+      result: input.text.trim()
+    };
+  }
+});
+
+export default defineTool({
+  manifest: {
+    pluginId: 'text-normalizer',
+    version: '1.0.0',
+    name: {
+      en: 'Text Normalizer',
+      'zh-CN': '文本规范化'
+    },
+    description: {
+      en: 'Normalize input text',
+      'zh-CN': '规范化输入文本'
+    },
+    versionDescription: {
+      en: 'Initial version',
+      'zh-CN': '初始版本'
+    },
+    permission: []
+  },
+  handler
+});
+```
+
+## 工具集模板
+
+```ts
+import {
+  createToolHandler,
+  defineToolSet,
+  type InputSchemaMetaType,
+  type OutputSchemaMetaType,
+  type SecretSchemaMetaType
+} from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const secretSchema = z.object({
+  apiKey: z.string().min(1).meta({
+    title: 'API Key',
+    isSecret: true
+  } satisfies SecretSchemaMetaType)
+});
+
+const searchHandler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string().min(1).meta({
+      title: 'Query',
+      toolDescription: 'Search query'
+    } satisfies InputSchemaMetaType)
+  }),
+  outputSchema: z.object({
+    items: z.array(z.string()).meta({
+      title: 'Items'
+    } satisfies OutputSchemaMetaType)
+  }),
+  secretSchema,
+  handler: async (input, ctx) => {
+    ctx.streamResponse({
+      type: 'answer',
+      content: `Searching: ${input.query}`
+    });
+
+    return {
+      items: []
+    };
+  }
+});
+
+export default defineToolSet({
+  secretSchema,
+  manifest: {
+    pluginId: 'example-search-tools',
+    version: '1.0.0',
+    name: {
+      en: 'Example Search Tools',
+      'zh-CN': '示例搜索工具集'
+    },
+    description: {
+      en: 'Search public example data',
+      'zh-CN': '搜索公开示例数据'
+    },
+    permission: []
+  },
+  children: [
+    {
+      id: 'search',
+      name: {
+        en: 'Search',
+        'zh-CN': '搜索'
+      },
+      description: {
+        en: 'Search by query',
+        'zh-CN': '按查询搜索'
+      },
+      toolDescription: 'Search public example data by query',
+      handler: searchHandler
+    }
+  ]
+});
+```
+
+## 验证重点
+
+- `index.ts` 默认导出正确。
+- `manifest` 字段完整，国际化字段包含 `en` 和 `zh-CN`。
+- `permission` 只包含插件实际使用的权限，且权限值来自当前支持的枚举。
+- 使用 `ctx.invoke` 时已在 `manifest.permission` 声明对应权限，例如上传文件声明 `file-upload:allow`。
+- Zod schema 覆盖全部用户可见输入和输出；需要工具调用自动填参的输入字段包含 `toolDescription`。
+- handler 成功路径返回值与 `outputSchema` 一致。
+- 外部调用失败、空响应、超时、鉴权失败都有明确错误。
+- 密钥配置只通过 `secretSchema` 和 `ctx.secrets` 处理。
+- 系统工具根目录存在 `logo.<ext>`。
+- 工具集子工具头像按 `<childId>.logo.<ext>` 命名，或确认复用主头像。
+- `build` 后存在 `dist/index.js` 和 `dist/manifest.json`。
+- `check` 通过后再执行 `pack`。