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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.en.md +5 -3
  2. package/README.md +14 -8
  3. package/dist/index.d.ts +4 -1
  4. package/package.json +10 -1
  5. package/skills/fastgpt-sdk-factory/SKILL.md +9 -5
  6. package/skills/fastgpt-system-tool-development/SKILL.md +6 -4
package/README.en.md CHANGED
@@ -28,7 +28,8 @@ import z from 'zod';
28
28
  const handler = createToolHandler({
29
29
  inputSchema: z.object({
30
30
  text: z.string().meta({
31
- title: 'Text'
31
+ title: 'Text',
32
+ isToolParams: true
32
33
  } satisfies InputSchemaMetaType)
33
34
  }),
34
35
  outputSchema: z.object({
@@ -118,7 +119,7 @@ Defines a tool set with multiple child tools. All child tools share the top-leve
118
119
 
119
120
  A single tool can declare `secretSchema` in its handler. A tool set can declare a shared `secretSchema` at the top level of `defineToolSet()`.
120
121
 
121
- 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.
122
+ Schema field metadata is written into the built JSON Schema through Zod `.meta()`. Use `InputSchemaMetaType` for input fields and optionally set `isToolParams: true` for input parameters recommended to be managed by AI. Use `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.
122
123
 
123
124
  ## Host Invocation
124
125
 
@@ -128,7 +129,8 @@ Use `ctx.invoke` to call FastGPT host capabilities. The SDK currently exposes fi
128
129
  const handler = createToolHandler({
129
130
  inputSchema: z.object({
130
131
  content: z.string().meta({
131
- title: 'Content'
132
+ title: 'Content',
133
+ isToolParams: true
132
134
  } satisfies InputSchemaMetaType)
133
135
  }),
134
136
  outputSchema: z.object({
package/README.md CHANGED
@@ -34,7 +34,8 @@ import z from 'zod';
34
34
  const handler = createToolHandler({
35
35
  inputSchema: z.object({
36
36
  text: z.string().meta({
37
- title: 'Text'
37
+ title: 'Text',
38
+ isToolParams: true
38
39
  } satisfies InputSchemaMetaType)
39
40
  }),
40
41
  outputSchema: z.object({
@@ -83,7 +84,8 @@ Defines a tool handler and infers `input`, `output`, and `secrets` types from Zo
83
84
  const handler = createToolHandler({
84
85
  inputSchema: z.object({
85
86
  query: z.string().meta({
86
- title: 'Query'
87
+ title: 'Query',
88
+ isToolParams: true
87
89
  } satisfies InputSchemaMetaType)
88
90
  }),
89
91
  outputSchema: z.object({
@@ -144,7 +146,8 @@ Defines a tool set with multiple child tools. All child tools share the top-leve
144
146
  const searchHandler = createToolHandler({
145
147
  inputSchema: z.object({
146
148
  query: z.string().meta({
147
- title: 'Query'
149
+ title: 'Query',
150
+ isToolParams: true
148
151
  } satisfies InputSchemaMetaType)
149
152
  }),
150
153
  outputSchema: z.object({
@@ -158,7 +161,8 @@ const searchHandler = createToolHandler({
158
161
  const summaryHandler = createToolHandler({
159
162
  inputSchema: z.object({
160
163
  content: z.string().meta({
161
- title: 'Content'
164
+ title: 'Content',
165
+ isToolParams: true
162
166
  } satisfies InputSchemaMetaType)
163
167
  }),
164
168
  outputSchema: z.object({
@@ -240,9 +244,9 @@ export default defineToolSet({
240
244
 
241
245
  A single tool can declare `secretSchema` in its handler. A tool set can declare a shared `secretSchema` at the top level of `defineToolSet()`.
242
246
 
243
- Schema 字段元数据通过 Zod `.meta()` 写入构建后的 JSON Schema。输入字段使用 `InputSchemaMetaType`，输出字段使用 `OutputSchemaMetaType`，密钥字段使用 `SecretSchemaMetaType`。`secretSchema` 的每个字段都要包含 `isSecret`，需要加密存储时设为 `true`。
247
+ Schema 字段元数据通过 Zod `.meta()` 写入构建后的 JSON Schema。输入字段使用 `InputSchemaMetaType`，推荐由 AI 托管补充的输入参数可设置 `isToolParams: true`。输出字段使用 `OutputSchemaMetaType`，密钥字段使用 `SecretSchemaMetaType`。`secretSchema` 的每个字段都要包含 `isSecret`，需要加密存储时设为 `true`。
244
248
 
245
- 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.
249
+ Schema field metadata is written into the built JSON Schema through Zod `.meta()`. Use `InputSchemaMetaType` for input fields and optionally set `isToolParams: true` for input parameters recommended to be managed by AI. Use `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.
246
250
 
247
251
  ```ts
248
252
  const secretSchema = z.object({
@@ -259,7 +263,8 @@ const secretSchema = z.object({
259
263
  const handler = createToolHandler({
260
264
  inputSchema: z.object({
261
265
  prompt: z.string().meta({
262
- title: 'Prompt'
266
+ title: 'Prompt',
267
+ isToolParams: true
263
268
  } satisfies InputSchemaMetaType)
264
269
  }),
265
270
  outputSchema: z.object({
@@ -286,7 +291,8 @@ Use `ctx.invoke` to call FastGPT host capabilities. The SDK currently exposes fi
286
291
  const handler = createToolHandler({
287
292
  inputSchema: z.object({
288
293
  content: z.string().meta({
289
- title: 'Content'
294
+ title: 'Content',
295
+ isToolParams: true
290
296
  } satisfies InputSchemaMetaType)
291
297
  }),
292
298
  outputSchema: z.object({
package/dist/index.d.ts CHANGED
@@ -222,7 +222,10 @@ type ToolHandlerDefinition<TInput extends ToolInputSchema = ToolInputSchema, TOu
222
222
  declare function createToolHandler<TInput extends ToolInputSchema, TOutput extends ToolOutputSchema, TSecret extends ToolSecretSchema = undefined>(def: ToolHandlerDefinition<TInput, TOutput, TSecret>): ToolHandlerDefinition<TInput, TOutput, TSecret>;
223
223
  //#endregion
224
224
  //#region src/index.d.ts
225
- type InputSchemaMetaType = z.GlobalMeta;
225
+ type InputSchemaMetaType = z.GlobalMeta & {
226
+ /** 面向模型的参数说明 */toolDescription?: string; /** 标注该字段是否推荐由 AI 托管补充 */
227
+ isToolParams?: boolean;
228
+ };
226
229
  type OutputSchemaMetaType = z.GlobalMeta;
227
230
  type SecretSchemaMetaType = z.GlobalMeta & {
228
231
  /** 标注该字段是否需要加密存储 */isSecret: boolean;
package/package.json CHANGED
@@ -1,6 +1,14 @@
1
1
  {
2
2
  "name": "@fastgpt-plugin/sdk-factory",
3
- "version": "0.0.1",
3
+ "version": "0.1.0-alpha.1",
4
+ "description": "TypeScript factory SDK for authoring FastGPT Plugin tools and tool suites.",
5
+ "keywords": [
6
+ "fastgpt",
7
+ "fastgpt-plugin",
8
+ "sdk",
9
+ "tool",
10
+ "typescript"
11
+ ],
4
12
  "devDependencies": {
5
13
  "tsdown": "^0.21.10"
6
14
  },
@@ -24,6 +32,7 @@
24
32
  "publishConfig": {
25
33
  "access": "public"
26
34
  },
35
+ "license": "MIT",
27
36
  "scripts": {
28
37
  "build": "tsdown"
29
38
  }
package/skills/fastgpt-sdk-factory/SKILL.md CHANGED
@@ -23,7 +23,8 @@ import z from 'zod';
23
23
  const handler = createToolHandler({
24
24
  inputSchema: z.object({
25
25
  text: z.string().meta({
26
- title: 'Text'
26
+ title: 'Text',
27
+ isToolParams: true
27
28
  } satisfies InputSchemaMetaType)
28
29
  }),
29
30
  outputSchema: z.object({
@@ -64,7 +65,7 @@ export default defineTool({
64
65
  - Use `z.object(...)` for `inputSchema` and `outputSchema` so TypeScript can infer `input` and return types.
65
66
  - Import `InputSchemaMetaType`, `OutputSchemaMetaType`, and `SecretSchemaMetaType` from `@fastgpt-plugin/sdk-factory` when schema metadata is used.
66
67
  - Add `.meta({ ... } satisfies InputSchemaMetaType)` to input fields and `.meta({ ... } satisfies OutputSchemaMetaType)` to output fields that need UI/manifest metadata.
67
- - 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.
68
+ - Set `isToolParams: true` in an input field's `.meta()` when that field is recommended to be managed by AI; use `toolDescription` for the model-facing parameter description.
68
69
  - Add `.meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)` to every `secretSchema` field; set `isSecret: true` for values that must be encrypted at rest.
69
70
  - Return an object that matches `outputSchema`; throw errors for failed operations.
70
71
  - Add `secretSchema` when plugin configuration needs secrets such as API keys.
@@ -84,7 +85,8 @@ const handler = createToolHandler({
84
85
  inputSchema: z.object({
85
86
  query: z.string().meta({
86
87
  title: 'Query',
87
- toolDescription: 'Search query'
88
+ toolDescription: 'Search query',
89
+ isToolParams: true
88
90
  } satisfies InputSchemaMetaType)
89
91
  }),
90
92
  outputSchema: z.object({
@@ -162,7 +164,8 @@ const secretSchema = z.object({
162
164
  const searchHandler = createToolHandler({
163
165
  inputSchema: z.object({
164
166
  query: z.string().meta({
165
- title: 'Query'
167
+ title: 'Query',
168
+ isToolParams: true
166
169
  } satisfies InputSchemaMetaType)
167
170
  }),
168
171
  outputSchema: z.object({
@@ -214,7 +217,8 @@ Use `ctx.invoke` for host capabilities. The SDK exposes `userInfo()` and `upload
214
217
  const uploadHandler = createToolHandler({
215
218
  inputSchema: z.object({
216
219
  content: z.string().meta({
217
- title: 'Content'
220
+ title: 'Content',
221
+ isToolParams: true
218
222
  } satisfies InputSchemaMetaType)
219
223
  }),
220
224
  outputSchema: z.object({
package/skills/fastgpt-system-tool-development/SKILL.md CHANGED
@@ -62,7 +62,7 @@ npx @fastgpt-plugin/cli pack --entry <plugin-directory> --dist <plugin-directory
62
62
  - 每个 handler 用 `createToolHandler()` 定义。
63
63
  - `inputSchema` 和 `outputSchema` 使用 `z.object(...)`。
64
64
  - `inputSchema` 字段使用 `.meta({ ... } satisfies InputSchemaMetaType)`。
65
- - `inputSchema` 字段需要被工具调用自动填参时，必须在 `.meta()` 中设置 `toolDescription`；未设置时该字段只能由用户手动指定。
65
+ - `inputSchema` 字段推荐由 AI 托管补充时，在 `.meta()` 中设置 `isToolParams: true`；`toolDescription` 可用于补充面向模型的参数说明。
66
66
  - `outputSchema` 字段使用 `.meta({ ... } satisfies OutputSchemaMetaType)`。
67
67
  - `secretSchema` 字段使用 `.meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)`；需要加密存储的字段标记为 `isSecret: true`。
68
68
  - handler 返回值必须匹配 `outputSchema`。
@@ -137,7 +137,8 @@ const handler = createToolHandler({
137
137
  inputSchema: z.object({
138
138
  text: z.string().min(1).meta({
139
139
  title: 'Text',
140
- toolDescription: 'Text to normalize'
140
+ toolDescription: 'Text to normalize',
141
+ isToolParams: true
141
142
  } satisfies InputSchemaMetaType)
142
143
  }),
143
144
  outputSchema: z.object({
@@ -197,7 +198,8 @@ const searchHandler = createToolHandler({
197
198
  inputSchema: z.object({
198
199
  query: z.string().min(1).meta({
199
200
  title: 'Query',
200
- toolDescription: 'Search query'
201
+ toolDescription: 'Search query',
202
+ isToolParams: true
201
203
  } satisfies InputSchemaMetaType)
202
204
  }),
203
205
  outputSchema: z.object({
@@ -257,7 +259,7 @@ export default defineToolSet({
257
259
  - `manifest` 字段完整，国际化字段包含 `en` 和 `zh-CN`。
258
260
  - `permission` 只包含插件实际使用的权限，且权限值来自当前支持的枚举。
259
261
  - 使用 `ctx.invoke` 时已在 `manifest.permission` 声明对应权限，例如上传文件声明 `file-upload:allow`。
260
- - Zod schema 覆盖全部用户可见输入和输出；需要工具调用自动填参的输入字段包含 `toolDescription`。
262
+ - Zod schema 覆盖全部用户可见输入和输出；推荐由 AI 托管补充的输入字段设置 `isToolParams: true`。
261
263
  - handler 成功路径返回值与 `outputSchema` 一致。
262
264
  - 外部调用失败、空响应、超时、鉴权失败都有明确错误。
263
265
  - 密钥配置只通过 `secretSchema` 和 `ctx.secrets` 处理。