AgentSkillsCN

tool-dev

专门用于开发 FastGPT 系统工具和工具集的技能，包含 Zod 类型安全验证、共享配置管理和完整测试工作流。适用于创建新的 FastGPT 工具、开发包含子工具的工具集、或实现带有正确配置和测试的 API 集成。

中文原作
SKILL.md
--- frontmatter
name: tool-dev
description: 专门用于开发 FastGPT 系统工具和工具集的技能，包含 Zod 类型安全验证、共享配置管理和完整测试工作流。适用于创建新的 FastGPT 工具、开发包含子工具的工具集、或实现带有正确配置和测试的 API 集成。
license: MIT
category: development
author: FastGPT Team
version: 2.0.0

FastGPT 工具开发技能

为开发 FastGPT 系统工具提供简化的工作流程，包括类型安全、正确的配置管理和自动化测试。

何时使用此技能

在进行 FastGPT 工具开发任务时使用此技能：

  • •创建新的独立工具或工具集
  • •实现带有适当身份验证的 API 集成
  • •开发具有 Zod 验证和 TypeScript 类型的工具
  • •在工具集子工具之间设置共享配置
  • •为工具功能编写全面的测试

核心能力

  • •类型安全开发: Zod schema 验证 + TypeScript 类型推导
  • •配置管理: 工具集内共享密钥配置，支持版本控制
  • •系统化测试: 自动化测试生成和验证
  • •代码质量: 内置代码审查和优化步骤
  • •最佳实践: 遵循 FastGPT 设计模式和规范

开发工作流

开发 FastGPT 工具时遵循此 4 阶段工作流程。每个阶段都有明确的目标、操作和质量标准。

阶段 1: 需求与设计

目标: 创建全面的需求文档

操作步骤:

  1. •查看 references/design_spec.md 中的现有设计模式
  2. •定义工具/工具集的范围和功能
  3. •使用 Zod schemas 指定输入/输出配置
  4. •记录 API 要求和测试凭证
  5. •使用 references/requirement_template.md 作为起点

质量标准:

  • •✅ 所有功能清晰定义
  • •✅ 输入/输出类型已指定
  • •✅ 边界情况和错误场景已记录

交付物: 完整的设计文档（参见 references/requirement_template.md）

阶段 2: 实现

目标: 按照 FastGPT 模式开发工具

操作步骤:

  1. •创建目录结构（tool/ 或 toolset/children/）
  2. •实现 config.ts，包含正确的版本列表
  3. •开发 src/index.ts，包含 Zod 验证的业务逻辑
  4. •如需要，添加共享模块（client.ts、utils.ts）

代码规范:

  • •采用 camelCase 命名规范
  • •类型导入: import { type Foo } from 'bar'
  • •最小化错误处理（让框架处理常见情况）
  • •函数简洁、职责单一

质量标准:

  • •✅ TypeScript 编译无错误
  • •✅ 遵循现有项目模式
  • •✅ 配置结构正确

阶段 3: 测试与验证

目标: 通过全面测试确保可靠性

操作步骤:

  1. •安装依赖: bun install
  2. •在 test/index.test.ts 中编写测试用例
  3. •运行测试套件: bun test
  4. •修复失败的测试和边界情况
  5. •验证 TypeScript: bun run tsc --noEmit

测试覆盖:

  • •输入验证（Zod schema 边界情况）
  • •业务逻辑正确性
  • •错误处理场景
  • •资源清理（如适用）

质量标准:

  • •✅ 所有测试通过
  • •✅ 无 TypeScript 错误
  • •✅ 构建成功: bun run build

阶段 4: 审查与优化

目标: 完成前优化代码质量

操作步骤:

  1. •代码审查，寻找简化机会
  2. •删除未使用的代码和依赖
  3. •优化性能瓶颈
  4. •最终集成测试
  5. •更新文档

质量标准:

  • •✅ 代码清晰且可维护
  • •✅ 无不必要的复杂性
  • •✅ 最终测试运行成功

快速参考

常用命令

bash
# 安装依赖
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 节

关键设计原则

  1. •关注点分离: 配置 ≠ 逻辑 ≠ 工具
  2. •类型安全: Zod 验证 → TypeScript 类型推导
  3. •共享配置: 工具集密钥由子工具继承
  4. •单一职责: 一个工具 = 一个功能
  5. •快速失败: 让框架处理常见错误

绑定资源

Scripts 目录

  • •init_skill.py: 初始化具有正确结构的新 skill
  • •package_skill.py: 验证并打包 skill 为可分发的 zip 文件
  • •quick_validate.py: 快速验证 skill 结构

References 目录

  • •design_spec.md: 完整的 FastGPT 工具设计规范（10 个章节）
  • •requirement_template.md: 创建工具需求文档的模板

使用模式

  1. •查看详细技术规范 → 阅读 references/design_spec.md
  2. •创建新工具需求 → 使用 references/requirement_template.md
  3. •管理 skill → 使用 scripts/*.py 工具

相关文档

  • •工具类型: @tool/type/tool 中的 ToolTypeEnum
  • •配置类型: @tool/type 中的 ToolConfigType、ToolSetConfigType
  • •FastGPT 类型: WorkflowIOValueTypeEnum、FlowNodeInputTypeEnum