@fastgpt-plugin/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/package.json

@@ -1,28 +1,29 @@
 {
   "name": "@fastgpt-plugin/cli",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "type": "module",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "@fastgpt-plugin/cli": "index.js"
+    "@fastgpt-plugin/cli": "index.js",
+    "fastgpt-plugin": "index.js"
   },
   "files": [
     "dist",
     "index.js",
-    "templates"
+    "templates",
+    "skills"
   ],
   "scripts": {
     "build": "tsdown",
     "build:verbose": "tsdown",
     "test": "vitest run",
-    "dev": "bun run src/index.ts",
-    "prepublishOnly": "npm run build"
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
-    "@fastgpt-plugin/helpers": "0.0.1-alpha.7",
     "@oxc-parser/binding-wasm32-wasi": "^0.112.0",
     "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.3",
@@ -30,7 +31,9 @@
     "es-toolkit": "^1.44.0",
     "oxc-parser": "^0.112.0",
     "tsdown": "^0.20.1",
-    "yazl": "^3.3.1"
+    "yazl": "^3.3.1",
+    "yaml": "^2.6.1",
+    "zod": "^4"
   },
   "devDependencies": {
     "@types/yazl": "^3.3.0",

package/skills/cli-usage/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: cli-usage
+description: 使用 FastGPT plugin CLI 时启用，适用于创建插件项目、构建 dist 产物、校验构建输出、打包 .pkg 文件，以及指导用户选择 create/build/check/pack 命令和参数。该技能使用通用说明风格，可被 Claude、Codex 等代理直接阅读。
+---
+
+# FastGPT CLI 使用技能
+
+在需要“使用 `apps/cli` 这个命令行工具”时使用这个技能，不用于修改 CLI 源码。
+
+## 适用场景
+
+- 想创建一个新的 FastGPT 插件项目
+- 想把插件源码构建成 `dist` 产物
+- 想检查 `dist` 下的构建结果是否符合约定
+- 想把构建产物打成 `.pkg`
+- 不确定该用 `create`、`build`、`check` 还是 `pack`
+
+## CLI 范围
+
+CLI 入口在 `apps/cli/src/cmd.ts`，当前主要命令有：
+
+- `create`
+- `build`
+- `check`
+- `pack`
+
+包名与可执行名见 `apps/cli/package.json`：
+
+- `@fastgpt-plugin/cli`
+- `fastgpt-plugin`
+
+## 常用命令
+
+推荐两种调用方式：
+
+```bash
+npx @fastgpt-plugin/cli <command>
+```
+
+```bash
+pnpm fastgpt-plugin <command>
+```
+
+### 1. 创建插件项目
+
+创建单工具：
+
+```bash
+npx @fastgpt-plugin/cli create my-tool --type tool
+```
+
+创建工具集：
+
+```bash
+npx @fastgpt-plugin/cli create my-suite --type tool-suite
+```
+
+常用参数：
+
+- `--cwd <path>`: 指定项目创建目录
+- `--description <desc>`: 指定插件描述
+
+说明：
+
+- `tool` 会生成单工具模板
+- `tool-suite` 会生成工具集模板
+- 模板目录在 `apps/cli/templates/tool`
+
+### 2. 构建插件
+
+```bash
+npx @fastgpt-plugin/cli build --entry ./path/to/plugin --output ./dist
+```
+
+常用参数：
+
+- `--entry <path>`: 插件源码根目录
+- `--output <path>`: 构建输出目录，默认 `./dist`
+- `--minify`: 是否压缩
+- `--format esm|cjs`: 输出格式
+
+适用时机：
+
+- 想先拿到 `dist/index.js`、`dist/manifest.json` 等产物
+- `pack` 前先单独确认构建结果
+
+### 3. 检查构建输出
+
+```bash
+npx @fastgpt-plugin/cli check --entry ./path/to/plugin --output ./dist
+```
+
+它会检查构建产物是否包含并满足约定：
+
+- `manifest.json`
+- `index.js`
+- logo 引用
+
+适用时机：
+
+- 打包前做一次快速校验
+- CI 中校验插件产物格式
+
+### 4. 打包为 .pkg
+
+```bash
+npx @fastgpt-plugin/cli pack --entry ./path/to/plugin --dist ./dist --output ./out
+```
+
+常用参数：
+
+- `--entry <path>`: 插件源码根目录
+- `--dist <path>`: 构建产物目录，默认 `./dist`
+- `--output <path>`: `.pkg` 输出目录
+- `--name <name>`: 包名，默认取入口目录名
+
+说明：
+
+- `pack` 会先执行构建，再把构建产物打成 `.pkg`
+- `.pkg` 里按约定包含 `index.js`、`manifest.json`、logo、可选 `README.md` 和 `assets/**`
+
+## 选择建议
+
+- 只想生成项目骨架：用 `create`
+- 已有源码，想得到构建产物：用 `build`
+- 已有 `dist`，想校验格式：用 `check`
+- 想直接得到最终 `.pkg`：用 `pack`
+
+## 排查建议
+
+- 模板生成不符合预期：检查 `apps/cli/templates/tool`
+- 命令参数不生效：检查 `apps/cli/src/commands/*.ts` 的 Commander 定义
+- 测试命令找不到用例：优先在 `apps/cli` 目录下运行 `pnpm test`
+
+## 验证
+
+在 `apps/cli` 目录下：
+
+```bash
+pnpm fastgpt-plugin --help
+```
+
+如果已经安装依赖并希望用 pnpm 执行：
+
+```bash
+pnpm fastgpt-plugin create my-tool --type tool
+```

package/templates/tool/index.tool.ts

@@ -0,0 +1,35 @@
+import { createToolHandler, defineTool } from '@fastgpt-plugin/sdk-factory';
+import z from 'zod';
+
+const handler = createToolHandler({
+  inputSchema: z.object({
+    delay: z.number()
+  }),
+  outputSchema: z.object({}),
+  handler: async (input, _ctx) => {
+    await new Promise((resolve) => setTimeout(resolve, input.delay));
+    return {};
+  }
+});
+
+const tool = defineTool({
+  manifest: {
+    description: {
+      en: 'Delay for a specified amount of time',
+      'zh-CN': '延迟指定的时间'
+    },
+    name: {
+      en: 'Delay',
+      'zh-CN': '延迟工具'
+    },
+    pluginId: 'delay',
+    version: '1.0.0',
+    versionDescription: {
+      en: 'Initial version',
+      'zh-CN': '初始版本'
+    }
+  },
+  handler
+});
+
+export default tool;

package/templates/tool/index.toolset.ts

@@ -0,0 +1,109 @@
+import { defineToolSet } from 'sdk/factory/dist';
+import { createToolHandler } from 'sdk/factory/src';
+import z from 'zod';
+
+const secretSchema = z.object({
+  host: z.string(),
+  port: z.number(),
+  username: z.string(),
+  password: z.string(),
+  database: z.string()
+});
+
+const mysqlHandler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string()
+  }),
+  outputSchema: z.object({
+    results: z.array(z.record(z.string(), z.unknown()))
+  }),
+  secretSchema,
+  handler: async (input, ctx) => {
+    return {
+      results: [
+        {
+          query: input.query,
+          host: ctx.secrets?.host,
+          port: ctx.secrets?.port,
+          username: ctx.secrets?.username,
+          password: ctx.secrets?.password,
+          database: ctx.secrets?.database,
+          db: 'MySQL'
+        }
+      ]
+    };
+  }
+});
+
+const pgsqlHandler = createToolHandler({
+  inputSchema: z.object({
+    query: z.string()
+  }),
+  outputSchema: z.object({
+    results: z.array(z.record(z.string(), z.unknown()))
+  }),
+  secretSchema,
+  handler: async (input, ctx) => {
+    return {
+      results: [
+        {
+          query: input.query,
+          host: ctx.secrets?.host,
+          port: ctx.secrets?.port,
+          username: ctx.secrets?.username,
+          password: ctx.secrets?.password,
+          database: ctx.secrets?.database,
+          db: 'PostgreSQL'
+        }
+      ]
+    };
+  }
+});
+
+export default defineToolSet({
+  manifest: {
+    pluginId: 'dbops',
+    name: {
+      en: 'DB Operations',
+      'zh-CN': '数据库操作'
+    },
+    description: {
+      en: 'A suite of tools for database operations, including MySQL, PostgreSQL, SQL Server, Oracle, and ClickHouse.',
+      'zh-CN':
+        '一套用于数据库操作的工具，包括 MySQL、PostgreSQL、SQL Server、Oracle 和 ClickHouse。'
+    },
+    version: '1.0.0',
+    versionDescription: {
+      en: 'Initial version with basic database operation tools.',
+      'zh-CN': '初始版本，包含基本的数据库操作工具。'
+    },
+    author: 'test author'
+  },
+  children: [
+    {
+      description: {
+        en: 'MySQL database operation tool',
+        'zh-CN': 'MySQL 数据库操作工具'
+      },
+      name: {
+        en: 'MySQL Tool',
+        'zh-CN': 'MySQL 工具'
+      },
+      id: 'mysql',
+      handler: mysqlHandler
+    },
+    {
+      description: {
+        en: 'PostgreSQL database operation tool',
+        'zh-CN': 'PostgreSQL 数据库操作工具'
+      },
+      name: {
+        en: 'PostgreSQL Tool',
+        'zh-CN': 'PostgreSQL 工具'
+      },
+      id: 'pgsql',
+      handler: pgsqlHandler
+    }
+  ],
+  secretSchema
+});

package/templates/tool/package.json

@@ -13,7 +13,7 @@
   "dependencies": {},
   "devDependencies": {
     "@fastgpt-plugin/cli": "catalog:",
-    "@fastgpt-plugin/helpers": "catalog:",
+    "@fastgpt-plugin/sdk-factory": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:",
     "zod": "catalog:"

package/templates/tool/config.ts

@@ -1,28 +0,0 @@
-import { defineTool, WorkflowIOValueTypeEnum, ToolTagEnum } from '@fastgpt-plugin/helpers';
-
-export default defineTool({
-  tags: [ToolTagEnum.tools],
-  name: {
-    'zh-CN': '{{name}}',
-    en: '{{name}}'
-  },
-  description: {
-    'zh-CN': '{{description}}',
-    en: '{{description}}'
-  },
-  versionList: [
-    {
-      value: '0.0.1',
-      description: 'Initial version',
-      inputs: [],
-      outputs: [
-        {
-          key: 'time',
-          valueType: WorkflowIOValueTypeEnum.string,
-          label: '时间',
-          description: '当前时间'
-        }
-      ]
-    }
-  ]
-});

package/templates/tool/index.ts

@@ -1,11 +0,0 @@
-import { exportTool } from '@fastgpt-plugin/helpers/tools/helper';
-import config from './config';
-import { InputSchema, OutputSchema } from './src/schemas';
-import { handler } from './src/tool';
-
-export default exportTool({
-  handler,
-  InputSchema,
-  OutputSchema,
-  config
-});

package/templates/tool/src/schemas.ts

@@ -1,9 +0,0 @@
-import { z } from 'zod';
-
-export const InputSchema = z.object({});
-export type Input = z.infer<typeof InputSchema>;
-
-export const OutputSchema = z.object({
-  time: z.string().nonempty()
-});
-export type Output = z.infer<typeof OutputSchema>;

package/templates/tool/src/tool.test.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { InputSchema, OutputSchema } from './schemas';
-import { tool } from './tool';
-import { mockedEventEmitter, mockedSystemVar } from '@fastgpt-plugin/helpers/tools/mocks';
-
-describe('get-time', () => {
-  it('should run with valid IO schemas', async () => {
-    const input = InputSchema.parse({});
-    const result = await tool(input, {
-      systemVar: mockedSystemVar,
-      emitter: mockedEventEmitter
-    });
-
-    const output = OutputSchema.parse(result);
-    expect(output).toBeDefined();
-  });
-});

package/templates/tool/src/tool.ts

@@ -1,8 +0,0 @@
-import type { ToolContextType } from '@fastgpt-plugin/helpers/tools/schemas/req';
-import type { Input, Output } from './schemas';
-
-export async function handler(_: Input, ctx: ToolContextType): Promise<Output> {
-  const { systemVar } = ctx;
-
-  return { time: systemVar.time };
-}

package/templates/tool-suite/README.md

@@ -1,11 +0,0 @@
-# {{name}}
-
-{{description}}
-
-## 开发
-
-```bash
-pnpm install
-pnpm run build
-pnpm run test
-```

package/templates/tool-suite/children/tool/config.ts

@@ -1,28 +0,0 @@
-import { defineTool, ToolTagEnum, WorkflowIOValueTypeEnum } from '@fastgpt-plugin/helpers';
-
-export default defineTool({
-  tags: [ToolTagEnum.tools],
-  name: {
-    'zh-CN': '{{name}}',
-    en: '{{name}}'
-  },
-  description: {
-    'zh-CN': '{{description}}',
-    en: '{{description}}'
-  },
-  versionList: [
-    {
-      value: '0.0.1',
-      description: 'Default version',
-      inputs: [],
-      outputs: [
-        {
-          key: 'time',
-          valueType: WorkflowIOValueTypeEnum.string,
-          label: '时间',
-          description: '当前时间'
-        }
-      ]
-    }
-  ]
-});

package/templates/tool-suite/children/tool/index.ts

@@ -1,11 +0,0 @@
-import { exportTool } from '@fastgpt-plugin/helpers/tools/helper';
-import config from './config';
-import { InputSchema, OutputSchema } from './src/schemas';
-import { handler } from './src/tool';
-
-export default exportTool({
-  handler,
-  InputSchema,
-  OutputSchema,
-  config
-});

package/templates/tool-suite/children/tool/logo.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
-  <rect width="64" height="64" rx="8" fill="#e0e7ff" />
-  <text x="32" y="40" text-anchor="middle" font-size="24" fill="#4338ca">?</text>
-</svg>

package/templates/tool-suite/children/tool/src/schemas.ts

@@ -1,9 +0,0 @@
-import { z } from 'zod';
-
-export const InputSchema = z.object({});
-export type Input = z.infer<typeof InputSchema>;
-
-export const OutputSchema = z.object({
-  time: z.string().nonempty()
-});
-export type Output = z.infer<typeof OutputSchema>;

package/templates/tool-suite/children/tool/src/tool.test.ts

@@ -1,37 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { tool } from './tool';
-import { InputType, OutputType } from './schemas';
-
-describe('{{name}} child tool', () => {
-  it('should run with valid IO schemas', async () => {
-    const input = InputType.parse({});
-    const result = await tool(input, {
-      systemVar: {
-        user: {
-          id: 'test',
-          username: 'test',
-          contact: 'test',
-          membername: 'test',
-          teamName: 'test',
-          teamId: 'test',
-          name: 'test'
-        },
-        app: {
-          id: 'test',
-          name: 'test'
-        },
-        tool: {
-          id: 'test',
-          version: '0.0.1'
-        },
-        time: new Date().toISOString()
-      },
-      streamResponse: () => {
-        // noop
-      }
-    });
-
-    const output = OutputType.parse(result);
-    expect(output).toBeDefined();
-  });
-});

package/templates/tool-suite/children/tool/src/tool.ts

@@ -1,8 +0,0 @@
-import type { ToolContextType } from '@fastgpt-plugin/helpers/tools/schemas/req';
-import type { Input, Output } from './schemas';
-
-export async function handler(_: Input, ctx: ToolContextType): Promise<Output> {
-  const { systemVar } = ctx;
-
-  return { time: systemVar.time };
-}

package/templates/tool-suite/config.ts

@@ -1,14 +0,0 @@
-import { defineToolSet, ToolTagEnum } from '@fastgpt-plugin/helpers';
-
-export default defineToolSet({
-  name: {
-    'zh-CN': '{{name}}',
-    en: '{{name}}'
-  },
-  tags: [ToolTagEnum.tools],
-  description: {
-    'zh-CN': '{{description}}',
-    en: '{{description}}'
-  },
-  secretInputConfig: []
-});

package/templates/tool-suite/index.ts

@@ -1,6 +0,0 @@
-import { exportToolSet } from '@fastgpt-plugin/helpers/tools/helper';
-import config from './config';
-
-export default exportToolSet({
-  config
-});

package/templates/tool-suite/logo.svg

@@ -1,4 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
-  <rect width="64" height="64" rx="8" fill="#e0e7ff" />
-  <text x="32" y="40" text-anchor="middle" font-size="24" fill="#4338ca">?</text>
-</svg>

package/templates/tool-suite/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "{{name}}",
-  "version": "0.0.1",
-  "description": "{{description}}",
-  "type": "module",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "npx @fastgpt-plugin/cli build --minify",
-    "build:dev": "npx @fastgpt-plugin/cli build",
-    "pack": "npx @fastgpt-plugin/cli pack",
-    "test": "vitest run"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@fastgpt-plugin/cli": "catalog:",
-    "@fastgpt-plugin/helpers": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
-    "zod": "catalog:"
-  }
-}

package/templates/tool-suite/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "target": "es2022",
-    "moduleResolution": "bundler",
-    "types": [],
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "strict": true,
-    "jsx": "react-jsx",
-    "verbatimModuleSyntax": true,
-    "isolatedModules": true,
-    "noUncheckedSideEffectImports": true,
-    "moduleDetection": "force",
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test.tsx", "**/*.spec.tsx"]
-}

package/templates/tool-suite/vitest.config.ts

@@ -1,7 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    environment: 'node'
-  }
-});