FastGPT 工具开发技能
为开发 FastGPT 系统工具提供简化的工作流程，包括类型安全、正确的配置管理和自动化测试。
何时使用此技能
在进行 FastGPT 工具开发任务时使用此技能：
-
创建新的独立工具或工具集
-
实现带有适当身份验证的 API 集成
-
开发具有 Zod 验证和 TypeScript 类型的工具
-
在工具集子工具之间设置共享配置
-
为工具功能编写全面的测试
核心能力
-
类型安全开发: Zod schema 验证 + TypeScript 类型推导
-
配置管理: 工具集内共享密钥配置，支持版本控制
-
系统化测试: 自动化测试生成和验证
-
代码质量: 内置代码审查和优化步骤
-
最佳实践: 遵循 FastGPT 设计模式和规范
开发工作流
开发 FastGPT 工具时遵循此 4 阶段工作流程。每个阶段都有明确的目标、操作和质量标准。
阶段 1: 需求与设计
目标: 创建全面的需求文档
操作步骤:
-
查看 references/design_spec.md 中的现有设计模式
-
定义工具/工具集的范围和功能
-
使用 Zod schemas 指定输入/输出配置
-
记录 API 要求和测试凭证
-
使用 references/requirement_template.md 作为起点
质量标准:
-
✅ 所有功能清晰定义
-
✅ 输入/输出类型已指定
-
✅ 边界情况和错误场景已记录
交付物: 完整的设计文档（参见 references/requirement_template.md ）
阶段 2: 实现
目标: 按照 FastGPT 模式开发工具
操作步骤:
-
创建目录结构（tool/ 或 toolset/children/ ）
-
实现 config.ts ，包含正确的版本列表
-
开发 src/index.ts ，包含 Zod 验证的业务逻辑
-
如需要，添加共享模块（client.ts 、utils.ts ）
代码规范:
-
采用 camelCase 命名规范
-
类型导入: import { type Foo } from 'bar'
-
最小化错误处理（让框架处理常见情况）
-
函数简洁、职责单一
质量标准:
-
✅ TypeScript 编译无错误
-
✅ 遵循现有项目模式
-
✅ 配置结构正确
阶段 3: 测试与验证
目标: 通过全面测试确保可靠性
操作步骤:
-
安装依赖: bun install
-
在 test/index.test.ts 中编写测试用例
-
运行测试套件: bun test
-
修复失败的测试和边界情况
-
验证 TypeScript: bun run tsc --noEmit
测试覆盖:
-
输入验证（Zod schema 边界情况）
-
业务逻辑正确性
-
错误处理场景
-
资源清理（如适用）
质量标准:
-
✅ 所有测试通过
-
✅ 无 TypeScript 错误
-
✅ 构建成功: bun run build
阶段 4: 审查与优化
目标: 完成前优化代码质量
操作步骤:
-
代码审查，寻找简化机会
-
删除未使用的代码和依赖
-
优化性能瓶颈
-
最终集成测试
-
更新文档
质量标准:
-
✅ 代码清晰且可维护
-
✅ 无不必要的复杂性
-
✅ 最终测试运行成功
快速参考
常用命令
安装依赖
bun install
运行测试
bun test
类型检查
bun run tsc --noEmit
构建
bun run build
测试特定文件
bun test test/index.test.ts
文件模板
访问详细的模板和规范：
-
需求模板: references/requirement_template.md
-
完整设计规范: references/design_spec.md
-
工具配置示例: design_spec.md 第 4.1 节
-
工具集配置示例: design_spec.md 第 5.1 节
-
Zod 验证模式: design_spec.md 第 7.2 节
-
测试结构: design_spec.md 第 9.1 节
关键设计原则
-
关注点分离: 配置 ≠ 逻辑 ≠ 工具
-
类型安全: Zod 验证 → TypeScript 类型推导
-
共享配置: 工具集密钥由子工具继承
-
单一职责: 一个工具 = 一个功能
-
快速失败: 让框架处理常见错误
绑定资源
Scripts 目录
-
init_skill.py : 初始化具有正确结构的新 skill
-
package_skill.py : 验证并打包 skill 为可分发的 zip 文件
-
quick_validate.py : 快速验证 skill 结构
References 目录
-
design_spec.md : 完整的 FastGPT 工具设计规范（10 个章节）
-
requirement_template.md : 创建工具需求文档的模板
使用模式
-
查看详细技术规范 → 阅读 references/design_spec.md
-
创建新工具需求 → 使用 references/requirement_template.md
-
管理 skill → 使用 scripts/*.py 工具
相关文档
-
工具类型: @tool/type/tool 中的 ToolTypeEnum
-
配置类型: @tool/type 中的 ToolConfigType 、ToolSetConfigType
-
FastGPT 类型: WorkflowIOValueTypeEnum 、FlowNodeInputTypeEnum