@fastgpt-plugin/sdk-factory 0.0.1-alpha.4 → 0.0.1-alpha.5

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@fastgpt-plugin/sdk-factory",
-  "version": "0.0.1-alpha.4",
+  "version": "0.0.1-alpha.5",
   "devDependencies": {
     "tsdown": "^0.21.10"
   },
   "type": "module",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "exports": {
     ".": {

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,200 @@
+---
+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 } from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    text: z.string()
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  }),
+  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.
+- 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()
+});
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string()
+  }),
+  outputSchema: z.object({
+    answer: z.string()
+  }),
+  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`
+
+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 } from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const secretSchema = z.object({
+  apiKey: z.string()
+});
+
+const searchHandler = createToolHandler({
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.object({ items: z.array(z.string()) }),
+  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()`. These methods return a `Result` tuple shaped as `[result, err]`; check `err` before using `result`.
+
+```ts
+const uploadHandler = createToolHandler({
+  inputSchema: z.object({
+    content: z.string()
+  }),
+  outputSchema: z.object({
+    accessURL: z.string(),
+    fileName: z.string(),
+    size: z.number()
+  }),
+  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 || !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,225 @@
+---
+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(...)`。
+- handler 返回值必须匹配 `outputSchema`。
+
+manifest 至少包含：
+
+- `pluginId`: 稳定唯一工具 ID。
+- `version`: 工具版本。
+- `name`: `{ en, 'zh-CN' }` 格式。
+- `description`: `{ en, 'zh-CN' }` 格式。
+
+常用可选字段：
+
+- `versionDescription`
+- `author`
+- `repoUrl`
+- `tutorialUrl`
+- `tags`
+- `permission`
+- `icon`
+- `toolDescription`
+
+兼容性要求：
+
+- `pluginId`、工具 `id`、输入字段名、输出字段名对外使用后保持稳定。
+- 用户配置的密钥、API Key、Base URL 等使用 `secretSchema` 描述，通过 `ctx.secrets` 读取。
+- 错误信息应能帮助定位问题，同时避免暴露密钥、令牌和完整上游敏感响应。
+- 需要向用户展示执行进度时使用 `ctx.streamResponse()`。
+- 需要生成文件时使用 `ctx.invoke.uploadFile()`。
+
+## 头像规范
+
+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 } from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    text: z.string().min(1)
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  }),
+  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': '初始版本'
+    }
+  },
+  handler
+});
+```
+
+## 工具集模板
+
+```ts
+import { createToolHandler, defineToolSet } from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const secretSchema = z.object({
+  apiKey: z.string().min(1)
+});
+
+const searchHandler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string().min(1)
+  }),
+  outputSchema: z.object({
+    items: z.array(z.string())
+  }),
+  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': '搜索公开示例数据'
+    }
+  },
+  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`。
+- Zod schema 覆盖全部用户可见输入和输出。
+- handler 成功路径返回值与 `outputSchema` 一致。
+- 外部调用失败、空响应、超时、鉴权失败都有明确错误。
+- 密钥配置只通过 `secretSchema` 和 `ctx.secrets` 处理。
+- 系统工具根目录存在 `logo.<ext>`。
+- 工具集子工具头像按 `<childId>.logo.<ext>` 命名，或确认复用主头像。
+- `build` 后存在 `dist/index.js` 和 `dist/manifest.json`。
+- `check` 通过后再执行 `pack`。