mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 09:37:28 +00:00
81 lines
5.7 KiB
Text
81 lines
5.7 KiB
Text
---
|
|
description:
|
|
globs:
|
|
alwaysApply: false
|
|
---
|
|
|
|
**新增桌面端工具流程:**
|
|
|
|
1. **定义工具接口 (Manifest):**
|
|
- **文件:** `src/tools/[tool_category]/index.ts` (例如: `src/tools/local-files/index.ts`)
|
|
- **操作:**
|
|
- 在 `ApiName` 对象（例如 `LocalFilesApiName`）中添加一个新的、唯一的 API 名称。
|
|
- 在 `Manifest` 对象（例如 `LocalFilesManifest`）的 `api` 数组中，新增一个对象来定义新工具的接口。
|
|
- **关键字段:**
|
|
- `name`: 使用上一步定义的 API 名称。
|
|
- `description`: 清晰描述工具的功能，供 Agent 理解和向用户展示。
|
|
- `parameters`: 使用 JSON Schema 定义工具所需的输入参数。
|
|
- `type`: 通常是 'object'。
|
|
- `properties`: 定义每个参数的名称、`description`、`type` (string, number, boolean, array, etc.)，使用英文。
|
|
- `required`: 一个字符串数组，列出必须提供的参数名称。
|
|
|
|
2. **定义相关类型:**
|
|
- **文件 1:** `packages/electron-client-ipc/src/types.ts` (或类似的共享 IPC 类型文件)
|
|
- **操作:** 定义传递给 IPC 事件的参数类型接口 (例如: `RenameLocalFileParams`, `MoveLocalFileParams`)。确保与 Manifest 中定义的 `parameters` 一致。
|
|
- **文件 2:** `src/tools/[tool_category]/type.ts` (例如: `src/tools/local-files/type.ts`)
|
|
- **操作:** 定义此工具执行后，存储在前端 Zustand Store 中的状态类型接口 (例如: `LocalRenameFileState`, `LocalMoveFileState`)。这通常包含操作结果（成功/失败）、错误信息以及相关数据（如旧路径、新路径等）。
|
|
|
|
3. **实现前端状态管理 (Store Action):**
|
|
- **文件:** `src/store/chat/slices/builtinTool/actions/[tool_category].ts` (例如: `src/store/chat/slices/builtinTool/actions/localFile.ts`)
|
|
- **操作:**
|
|
- 导入在步骤 2 中定义的 IPC 参数类型和状态类型。
|
|
- 在 Action 接口 (例如: `LocalFileAction`) 中添加新 Action 的方法签名，使用对应的 IPC 参数类型。
|
|
- 在 `createSlice` (例如: `localFileSlice`) 中实现该 Action 方法：
|
|
- 接收 `id` (消息 ID) 和 `params` (符合 IPC 参数类型)。
|
|
- 设置加载状态 (`toggleLocalFileLoading(id, true)`)。
|
|
- 调用对应的 `Service` 层方法 (见步骤 4)，传递 `params`。
|
|
- 使用 `try...catch` 处理 `Service` 调用可能发生的错误。
|
|
- **成功时:**
|
|
- 调用 `updatePluginState(id, {...})` 更新插件状态，使用步骤 2 中定义的状态类型。
|
|
- 调用 `internal_updateMessageContent(id, JSON.stringify({...}))` 更新消息内容，通常包含成功确认信息。
|
|
- **失败时:**
|
|
- 记录错误 (`console.error`)。
|
|
- 调用 `updatePluginState(id, {...})` 更新插件状态，包含错误信息。
|
|
- 调用 `internal_updateMessagePluginError(id, {...})` 设置消息的错误状态。
|
|
- 调用 `internal_updateMessageContent(id, JSON.stringify({...}))` 更新消息内容，包含错误信息。
|
|
- 在 `finally` 块中取消加载状态 (`toggleLocalFileLoading(id, false)`)。
|
|
- 返回操作是否成功 (`boolean`)。
|
|
|
|
4. **实现 Service 层 (调用 IPC):**
|
|
- **文件:** `src/services/electron/[tool_category]Service.ts` (例如: `src/services/electron/localFileService.ts`)
|
|
- **操作:**
|
|
- 导入在步骤 2 中定义的 IPC 参数类型。
|
|
- 添加一个新的 `async` 方法，方法名通常与 Action 名称对应 (例如: `renameLocalFile`)。
|
|
- 方法接收 `params` (符合 IPC 参数类型)。
|
|
- 通过 `ensureElectronIpc()` 获取 IPC 代理 (`const ipc = ensureElectronIpc();`)，调用与 Manifest 中 `name` 字段匹配的链式方法，并将 `params` 传递过去。
|
|
- 定义方法的返回类型，通常是 `Promise<{ success: boolean; error?: string }>`，与后端 Controller 返回的结构一致。
|
|
|
|
5. **实现后端逻辑 (Controller / IPC Handler):**
|
|
- **文件:** `apps/desktop/src/main/controllers/[ToolName]Ctr.ts` (例如: `apps/desktop/src/main/controllers/LocalFileCtr.ts`)
|
|
- **操作:**
|
|
- 导入 Node.js 相关模块 (`fs`, `path` 等) 和 IPC 相关依赖 (`ControllerModule`, `IpcMethod`、参数类型等)。
|
|
- 添加一个新的 `async` 方法，方法名通常以 `handle` 开头 (例如: `handleRenameFile`)。
|
|
- 使用 `@IpcMethod()` 装饰器将此方法注册为对应 IPC 事件的处理器，确保方法名与 Manifest 中的 `name` 以及 Service 层的链式调用一致。
|
|
- 方法的参数应解构自 Service 层传递过来的对象，类型与步骤 2 中定义的 IPC 参数类型匹配。
|
|
- 实现核心业务逻辑：
|
|
- 进行必要的输入验证。
|
|
- 执行文件系统操作或其他后端任务 (例如: `fs.promises.rename`)。
|
|
- 使用 `try...catch` 捕获执行过程中的错误。
|
|
- 处理特定错误码 (`error.code`) 以提供更友好的错误消息。
|
|
- 返回一个包含 `success` (boolean) 和可选 `error` (string) 字段的对象。
|
|
|
|
6. **更新 Agent 文档 (System Role):**
|
|
- **文件:** `src/tools/[tool_category]/systemRole.ts` (例如: `src/tools/local-files/systemRole.ts`)
|
|
- **操作:**
|
|
- 在 `<core_capabilities>` 部分添加新工具的简要描述。
|
|
- 如果需要，更新 `<workflow>`。
|
|
- 在 `<tool_usage_guidelines>` 部分为新工具添加详细的使用说明，解释其参数、用途和预期行为。
|
|
- 如有必要，更新 `<security_considerations>`。
|
|
- 如有必要（例如工具返回了新的数据结构或路径），更新 `<response_format>` 中的示例。
|
|
|
|
通过遵循这些步骤，可以系统地将新的桌面端工具集成到 LobeChat 的插件系统中。
|