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: 初始化具有正确结构的新 skillpackage_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