Install skill

.claude/skills/toolDev/SKILL.md

@@ -0,0 +1,181 @@
+---
+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`

.claude/agents/toolCodeAgent.md → .claude/skills/toolDev/references/design_spec.md

@@ -1,59 +1,3 @@
----
-name: toolCodeAgent
-description: 当用户需要开发一个工具/工具集时调用
-model: sonnet
----
-
-# 工作流程
-
-开发新工具时，参考该流程完成任务。
-
-1. 参考 DESIGN.md  已有信息，完成需求文档编写。
-2. 审核需求文档，检查是否有遗漏。
-3. 依据需求文档完成代码开发。
-4. 依据需求文档，编写测试案例。
-5. 安装对应依赖后，进行测试并纠错问题。
-6. 进行代码 Review，简化无用代码。
-7. 最后再进行一次测试，保证代码可用。
-
-## 需求文档模板
-
-```
-# xxx 设计文档
-
-## 参考信息
-
-这里可能会给一些参考文档，测试密钥等。
-
-## 功能描述
-
-实现 xxxx。
-
-* 需要一个 tool/toolset
-* 包含 n 个工具，具体如下：
-
-1. xxx
-2. xxx
-
-## 目录结构
-
-## 输入输出配置
-
-## 代码示例
-
-## 测试方案
-
-## 可能存在的问题和重点检查内容
-```
-
-## 测试流程
-
-1. 检查 TS 是否有错误
-2. 检查是否可以正常运行和build
-3. 检查测试案例是否通过
-
----
-
 # FastGPT 系统工具设计规范
 
 本文档定义了 FastGPT Plugin 系统中工具(Tool)和工具集(ToolSet)的统一设计规范,基于 Redis 工具集的最佳实践总结。
@@ -191,7 +135,7 @@ export default defineTool({
           required: true,
           valueType: WorkflowIOValueTypeEnum.string,
           renderTypeList: [FlowNodeInputTypeEnum.input, FlowNodeInputTypeEnum.reference],
-          toolDescription: 'Input description for AI', // 可选，当该变量需要由 LLM 模型动态生成时才存在
+          toolDescription: 'Input description for AI', // 可选,当该变量需要由 LLM 模型动态生成时才存在
           defaultValue: 'default value',           // 可选
           placeholder: 'Enter value...',           // 可选
           maxLength: 1000                          // 可选,字符串最大长度
@@ -361,7 +305,7 @@ export const OutputType = z.object({
   success: z.boolean()
 });
 
-// 工具回调函数（简单版，由上层自动处理错误）
+// 工具回调函数(简单版,由上层自动处理错误)
 export async function tool({
   connectionString,
   apiKey,
@@ -376,7 +320,7 @@ export async function tool({
   };
 }
 
-// 工具回调函数（需处理错误/关闭链接）
+// 工具回调函数(需处理错误/关闭链接)
 export async function tool({
   connectionString,
   apiKey,
@@ -415,7 +359,7 @@ export async function tool({
 
 ### 6.1 客户端模块 (client.ts)
 
-用于封装工具集中的子工具共享连接逻辑，比如数据库实例，请求实例封装。
+用于封装工具集中的子工具共享连接逻辑,比如数据库实例,请求实例封装。
 
 ```typescript
 import SomeClient from 'some-library';
@@ -517,9 +461,9 @@ export async function withTimeout<T>(
 
 ### 6.3 错误处理 (error.ts)
 
-对于一个工具集来说，如果统一用的是同一家的 API，通常会有错误映射码，可以在该文件中声明，并统一做错误映射处理。如果是常见的错误，则无需该文件和报错捕获，直接抛错即可。
+对于一个工具集来说,如果统一用的是同一家的 API,通常会有错误映射码,可以在该文件中声明,并统一做错误映射处理。如果是常见的错误,则无需该文件和报错捕获,直接抛错即可。
 
-如果不需要做错误映射， src/index.ts 逻辑处理中，无需 try catch，直接由上层自动捕获错误即可。
+如果不需要做错误映射, src/index.ts 逻辑处理中,无需 try catch,直接由上层自动捕获错误即可。
 
 ```ts
 const errorMap = {
@@ -724,15 +668,15 @@ secretInputConfig: [
 
 ### 8.2 输入验证
 
-如果用户未制定特殊校验，则无需增加额外自定义校验，使用下面常见的几种校验即可：
+如果用户未制定特殊校验,则无需增加额外自定义校验,使用下面常见的几种校验即可:
 
 ```typescript
 import { z } from 'zod';
 
 export const InputType = z.object({
   // 字符串验证
   name: z.string()
-    .nonempty('Name cannot be empty') // 如果是长度限制：minLength(1, 'Name cannot be empty')
+    .nonempty('Name cannot be empty') // 如果是长度限制:minLength(1, 'Name cannot be empty')
     .maxLength(100, 'Name too long'),
 
   // 数字验证
@@ -898,7 +842,6 @@ describe('ToolName Tests', () => {
 ## 10. 代码规范
 
 * 采用小驼峰命名规范。
-* 类型引入需要强制什么 type，例如 import {type xx} from xxx;
+* 类型引入需要强制什么 type,例如 import {type xx} from xxx;
 * 代码精简。
-* 简单内容无需额外报错捕获，外层已做处理。
-
+* 简单内容无需额外报错捕获,外层已做处理。