tool-dev

FastGPT Tool Development Skill

Provides a streamlined workflow for developing FastGPT system tools, including type safety, proper configuration management, and automated testing.

When to Use This Skill

Use this skill when performing FastGPT tool development tasks:

• Creating a new standalone tool or toolset
• Implementing API integrations with proper authentication
• Developing tools with Zod validation and TypeScript types
• Setting up shared configuration between toolset subtools
• Writing comprehensive tests for tool functionality

Core Capabilities

• Type-Safe Development: Zod schema validation + TypeScript type inference
• Configuration Management: Shared secret configuration within a toolset, with version control support
• Systematic Testing: Automated test generation and validation
• Code Quality: Built-in code review and optimization steps
• Best Practices: Follows FastGPT design patterns and conventions

---

Development Workflow

Follow this 4-phase workflow when developing FastGPT tools. Each phase has clear objectives, actions, and quality standards.

Phase 1: Requirements and Design

Objective: Create a comprehensive requirements document

Steps:

1. Review references/design_spec.md for existing design patterns
2. Define the scope and functionality of the tool/toolset
3. Specify input/output configuration using Zod schemas
4. Document API requirements and test credentials
5. Use references/requirement_template.md as a starting point

Quality Standards:

• ✅ All functionality clearly defined
• ✅ Input/output types specified
• ✅ Edge cases and error scenarios documented

Deliverable: Complete design document (see references/requirement_template.md）

---

Phase 2: Implementation

Objective: Develop the tool following FastGPT patterns

Steps:

1. Create the directory structure (tool/ or toolset/children/）
2. Implement config.ts, including the correct version list
3. Develop src/index.ts, including business logic with Zod validation
4. If needed, add shared modules (client.ts、utils.ts）

Code Conventions:

• Adopt camelCase naming conventions
• Type imports: import { type Foo } from 'bar'
• Minimize error handling (let the framework handle common cases)
• Keep functions concise with a single responsibility

Quality Standards:

• ✅ TypeScript compiles without errors
• ✅ Follows existing project patterns
• ✅ Configuration structure is correct

---

Phase 3: Testing and Validation

Objective: Ensure reliability through comprehensive testing

Steps:

1. Install dependencies: bun install
2. In test/index.test.ts write test cases
3. Run the test suite: bun test
4. Fix failing tests and edge cases
5. Validate TypeScript: bun run tsc --noEmit

Test Coverage:

• Input Validation (Zod schema boundary cases)
• Business Logic Correctness
• Error Handling Scenarios
• Resource Cleanup (if applicable)

Quality Standards:

• ✅ All tests pass
• ✅ No TypeScript errors
• ✅ Build succeeds: bun run build

---

Phase 4: Review and Optimization

Goal: Optimize code quality before completion

Steps:

1. Code review, looking for simplification opportunities
2. Remove unused code and dependencies
3. Optimize performance bottlenecks
4. Final integration testing
5. Update documentation

Quality Standards:

• ✅ Code is clear and maintainable
• ✅ No unnecessary complexity
• ✅ Final test run succeeds

---

Quick Reference

Common Commands

# 安装依赖
bun install

# 运行测试
bun test

# 类型检查
bun run tsc --noEmit

# 构建
bun run build

# 测试特定文件
bun test test/index.test.ts

File Templates

Access detailed templates and specifications:

• Requirements Template: references/requirement_template.md
• Complete Design Specification: references/design_spec.md
• Tool Configuration Example: design_spec.md Section 4.1
• Tool Set Configuration Example: design_spec.md Section 5.1
• Zod Validation Schema: design_spec.md Section 7.2
• Test Structure: design_spec.md Section 9.1

Key Design Principles

1. Separation of Concerns: Configuration ≠ Logic ≠ Tools
2. Type Safety: Zod validation → TypeScript type inference
3. Shared Configuration: Tool set keys are inherited by child tools
4. Single Responsibility: One tool = one function
5. Fail Fast: Let the framework handle common errors

---

Bound Resources

Scripts Directory

• init_skill.py: Initialize a new skill with the correct structure
• package_skill.py: Validate and package the skill into a distributable zip file
• quick_validate.py: Quickly validate the skill structure

References Directory

• design_spec.md: Complete FastGPT tool design specification (10 sections)
• requirement_template.md: Template for creating tool requirements documents

Usage Patterns

1. View detailed technical specifications → Read references/design_spec.md
2. Create new tool requirements → Use references/requirement_template.md
3. Manage skill → Use scripts/*.py tool

---

Related Documentation

• Tool types: @tool/type/tool in ToolTypeEnum
• Configuration types: @tool/type in ToolConfigType、ToolSetConfigType
• FastGPT types: WorkflowIOValueTypeEnum、FlowNodeInputTypeEnum