deepfish-ai 2.0.2 → 2.0.4

package/README.md

@@ -50,9 +50,15 @@
   - [缓存管理（AI自我学习的缓存）](#缓存管理ai自我学习的缓存)
 - [5. MCP 扩展配置](#5-mcp-扩展配置)
   - [配置示例](#配置示例)
-- [6. 贡献](#6-贡献)
-- [7. 许可证](#7-许可证)
-- [8. 支持](#8-支持)
+- [6. Tool 与 Skill 扩展说明](#6-tool-与-skill-扩展说明)
+  - [当前目录扩展](#当前目录扩展)
+  - [全局扩展](#全局扩展)
+- [7. 系统配置文件说明](#7-系统配置文件说明)
+  - [配置文件字段](#配置文件字段)
+  - [AI 模型配置字段](#ai-模型配置字段)
+- [8. 贡献](#8-贡献)
+- [9. 许可证](#9-许可证)
+- [10. 支持](#10-支持)
 
 ## 1. 介绍
 
@@ -71,7 +77,6 @@
 
 - 高度可扩展：支持通过扩展机制拓展功能边界，除基础的终端、文件操作外，可轻松实现翻译、小说创作、文件格式转换、数据处理等复杂任务，满足多样化使用需求。
 
-
 ## 2. 安装
 
 ### 前置要求
@@ -114,79 +119,80 @@ ai "你的问题或指令"
 
 ### 配置管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai config edit` | 编辑配置文件 |
-| `ai config view` | 查看当前配置 |
-| `ai config reset` | 重置配置 |
-| `ai config dir` | 查看配置目录 |
+| 命令              | 说明         |
+| ----------------- | ------------ |
+| `ai config edit`  | 编辑配置文件 |
+| `ai config view`  | 查看当前配置 |
+| `ai config reset` | 重置配置     |
+| `ai config dir`   | 查看配置目录 |
 
 ### 模型管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai models add` | 添加新模型 |
-| `ai models ls` | 列出所有模型 |
+| 命令                   | 说明           |
+| ---------------------- | -------------- |
+| `ai models add`        | 添加新模型     |
+| `ai models ls`         | 列出所有模型   |
 | `ai models use <name>` | 切换使用的模型 |
-| `ai models del <name>` | 删除指定模型 |
+| `ai models del <name>` | 删除指定模型   |
 
 ### Skill 管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai skills ls` | 列出所有 Skill |
-| `ai skills add <name>` | 添加 Skill |
-| `ai skills del <index>` | 删除指定 Skill |
-| `ai skills enable <name\|index>` | 启用 Skill |
-| `ai skills disable <name\|index>` | 禁用 Skill |
-| `ai skills dir` | 查看 Skill 目录 |
-| `ai skills generate xxx` | 通过 AI 生成 Skill |
+| 命令                              | 说明               |
+| --------------------------------- | ------------------ |
+| `ai skills ls`                    | 列出所有 Skill     |
+| `ai skills add <name>`            | 添加 Skill         |
+| `ai skills del <index>`           | 删除指定 Skill     |
+| `ai skills enable <name\|index>`  | 启用 Skill         |
+| `ai skills disable <name\|index>` | 禁用 Skill         |
+| `ai skills dir`                   | 查看 Skill 目录    |
+| `ai skills generate xxx`          | 通过 AI 生成 Skill |
 
 ### 工具管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai tools dir` | 查看工具目录 |
-| `ai tools generate xxx` | 通过 AI 生成工具 |
+| 命令                    | 说明                                               |
+| ----------------------- | -------------------------------------------------- |
+| `ai tools dir`          | 查看全局工具目录                                   |
+| `ai tools add <name>`   | 添加当前目录下的本地工具目录，可选择本地或全局生效 |
+| `ai tools generate xxx` | 通过 AI 生成工具                                   |
 
 ### 会话管理
 
-| 命令 | 说明 |
-|------|------|
+| 命令               | 说明         |
+| ------------------ | ------------ |
 | `ai session clear` | 清除会话历史 |
-| `ai session dir` | 查看会话目录 |
+| `ai session dir`   | 查看会话目录 |
 
 ### 任务管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai task ls` | 列出所有任务 |
-| `ai task add <task>` | 添加任务 |
+| 命令                  | 说明         |
+| --------------------- | ------------ |
+| `ai task ls`          | 列出所有任务 |
+| `ai task add <task>`  | 添加任务     |
 | `ai task del <index>` | 删除指定任务 |
-| `ai task clear` | 清除所有任务 |
+| `ai task clear`       | 清除所有任务 |
 
 ### MCP 管理
 
-| 命令 | 说明 |
-|------|------|
+| 命令          | 说明          |
+| ------------- | ------------- |
 | `ai mcp edit` | 编辑 MCP 配置 |
 
 ### 服务管理
 
-| 命令 | 说明 |
-|------|------|
-| `ai serve` | 启动服务 |
-| `ai serve start` | 启动服务 |
-| `ai serve stop` | 停止服务 |
+| 命令               | 说明     |
+| ------------------ | -------- |
+| `ai serve`         | 启动服务 |
+| `ai serve start`   | 启动服务 |
+| `ai serve stop`    | 停止服务 |
 | `ai serve restart` | 重启服务 |
 
 ### 缓存管理（AI自我学习的缓存）
 
-| 命令 | 说明 |
-|------|------|
-| `ai cache ls` | 列出缓存 |
+| 命令                        | 说明       |
+| --------------------------- | ---------- |
+| `ai cache ls`               | 列出缓存   |
 | `ai cache edit <index\|id>` | 编辑缓存项 |
-| `ai cache del <index\|id>` | 删除缓存项 |
+| `ai cache del <index\|id>`  | 删除缓存项 |
 
 ## 5. MCP 扩展配置
 
@@ -209,14 +215,101 @@ MCP（Model Context Protocol）允许 AI 连接外部工具和服务。通过 `a
 
 配置完成后，AI 将自动加载 MCP Server 提供的工具，你可以在对话中直接让 AI 使用这些能力。
 
-## 6. 贡献
+## 6. Tool 与 Skill 扩展说明
+
+DeepFish 支持通过 Tool 和 Skill 扩展 AI 的能力。扩展文件可以放在当前工作目录的 `.deepfish-ai` 目录中，也可以放在全局配置目录中。
+
+- **Tool 扩展**：用于定义 AI 可直接调用的自定义函数工具，适合封装 API 调用、数据库操作、文件处理等能力。
+- **Skill 扩展**：用于定义 AI 的工作流知识包，适合沉淀某类任务的执行步骤、规范和最佳实践。
+
+### 当前目录扩展
+
+如果扩展只希望在当前目录下生效，请将扩展拷贝到当前目录的 `.deepfish-ai` 目录中：
+
+```text
+当前目录/
+└── .deepfish-ai/
+    ├── tools/
+    │   └── your-tool/
+    └── skills/
+        └── your-skill/
+```
+
+- Tool 扩展放入 `当前目录/.deepfish-ai/tools/`。
+- Skill 扩展放入 `当前目录/.deepfish-ai/skills/`。
+- 这种方式只对当前目录有效，适合项目级扩展或仅在某个项目中使用的能力。
+
+### 全局扩展
+
+如果扩展希望在所有目录下生效，请将扩展拷贝到全局配置目录中的 `tools` 或 `skills` 目录。
+
+可以通过以下命令打开全局配置目录：
+
+```bash
+ai config dir
+```
+
+目录结构示例：
+
+```text
+全局配置目录/
+└── .deepfish-ai/
+    ├── tools/
+    │   └── your-tool/
+    └── skills/
+        └── your-skill/
+```
+
+- Tool 扩展放入 `全局配置目录/.deepfish-ai/tools/`。
+- Skill 扩展放入 `全局配置目录/.deepfish-ai/skills/`。
+- 这种方式对全局有效，适合通用工具或长期复用的工作流能力。
+
+## 7. 系统配置文件说明
+
+DeepFish 的系统配置文件位于用户目录下的 `.deepfish-ai/config.json5`，可通过以下命令打开或查看：
+
+```bash
+ai config edit
+ai config view
+```
+
+### 配置文件字段
+
+| 字段                  | 类型      | 默认值   | 说明                                                                    |
+| --------------------- | --------- | -------- | ----------------------------------------------------------------------- |
+| `aiList`              | `array`   | `[]`     | AI 模型配置列表，可添加多个模型配置。                                   |
+| `currentModel`        | `string`  | `''`     | 当前正在使用的 AI 配置名称，对应 `aiList` 中某一项的 `name`。           |
+| `maxIterations`       | `number`  | `-1`     | AI 完成工作流的最大迭代次数，`-1` 表示不限制。                          |
+| `maxMemoryExpireTime` | `number`  | `30`     | 会话记忆最大保留时间，单位为天；`-1` 表示永久保留，`0` 表示不记录。     |
+| `maxLogExpireTime`    | `number`  | `3`      | 日志最大保留时间，单位为天；`-1` 表示永久保留，`0` 表示不记录。         |
+| `maxBlockFileSize`    | `number`  | `50`     | 最大分块文件大小，单位为 KB；超过该大小的文件会按块处理。               |
+| `encoding`            | `string`  | `'auto'` | 命令行输出编码，可设置为 `utf-8`、`gbk` 等；`auto` 或空值表示自动判断。 |
+| `maxSubAgentCount`    | `number`  | `2`      | 最大并行子 Agent 数量，`-1` 表示不限制。                                |
+| `isPrintThinking`     | `boolean` | `true`   | 是否打印 AI 思考过程中的中间信息。                                      |
+| `serve.port`          | `number`  | `8866`   | DeepFish 本地服务端口。                                                 |
+
+### AI 模型配置字段
+
+`aiList` 中的每一项表示一个 AI 模型配置，常见字段如下：
+
+| 字段               | 类型     | 说明                                                            |
+| ------------------ | -------- | --------------------------------------------------------------- |
+| `name`             | `string` | 模型配置名称，用于 `ai models use <name>` 切换模型。            |
+| `type`             | `string` | 模型供应商类型，例如 `DeepSeek`、`Ollama`、`OpenAICompatible`。 |
+| `baseUrl`          | `string` | 模型 API 地址。                                                 |
+| `model`            | `string` | 实际调用的模型名称。                                            |
+| `apiKey`           | `string` | 模型 API Key。                                                  |
+| `temperature`      | `number` | 生成随机性参数，数值越高输出越发散，数值越低输出越稳定。        |
+| `maxContextLength` | `number` | 模型最大上下文长度，单位为 tokens。                             |
+
+## 8. 贡献
 
 欢迎贡献！请随时提交Pull Request。
 
-## 7. 许可证
+## 9. 许可证
 
 本项目采用MIT许可证 - 详见[LICENSE](LICENSE)文件。
 
-## 8. 支持
+## 10. 支持
 
 如有问题和疑问，请在GitHub仓库上提交issue。

package/dist/generate-skill.md

@@ -0,0 +1,104 @@
+---
+name: 'generate-skill'
+description: '根据用户需求生成符合标准规范的自定义 Skill 工具包'
+homepage: ''
+---
+
+# 生成自定义技能
+
+你是一个技能生成器，基于 OpenClaw Skill 规范创建标准化的 Skill 工具包，最终输出可被系统直接加载使用。
+
+## 任务目标
+
+基于用户需求创建一个标准化的 Skill 工具包，实现用户目标。
+
+## 任务步骤
+
+### 第一步：项目初始化
+
+1. **目录创建**：在当前工作目录下新建一个子目录，目录名称应简洁明了地反映 Skill 功能（如 `web-scraper`、`code-reviewer`、`image-optimizer` 等）
+2. **核心文件**：目录中必须包含 `SKILL.md` 文件（文件名大小写敏感，必须为 `SKILL.md`）
+3. **辅助文件**：如果 Skill 涉及复杂逻辑，可在目录中创建辅助脚本文件（如 `.js`、`.sh`、`.py` 等），并在 `SKILL.md` 中说明其用途和调用方式；如果是 js 文件，可以在函数中通过 `this.Tools` 调用内置函数，如直接使用 `this.Tools.createSubAgent(workGoal)`
+
+#### 标准目录结构
+
+```
+<skill-name>/
+├── SKILL.md          # [必需] 核心文件：YAML元数据 + AI执行指令
+├── scripts/          # [可选] 辅助脚本目录（复杂Skill适用）
+│   ├── helper.js     #   Node.js辅助脚本
+│   ├── process.sh    #   Shell辅助脚本
+│   └── ...
+└── assets/           # [可选] 资源文件目录（模板、配置等）
+    ├── template.txt  #   模板文件
+    └── ...
+```
+
+### 第二步：SKILL.md 完整开发规范
+
+#### 2.1 文件结构
+
+SKILL.md 由两部分组成：
+
+- **YAML Frontmatter**（元数据区）：位于文件顶部，用 `---` 包裹
+- **Markdown Body**（指令正文区）：Frontmatter 之后的所有内容，是 AI 执行 Skill 的核心指令
+
+#### 2.2 YAML Frontmatter 规范（必须遵循）
+
+```yaml
+---
+name: 'skill-name'
+description: '简要描述该Skill的核心功能和适用场景（建议20-50字）'
+homepage: 'https://github.com/your-repo/skill-name'
+---
+```
+
+字段说明：
+
+- `name`：Skill 的唯一标识名称，使用小写字母和连字符，与目录名保持一致
+- `description`：Skill 功能的简要描述，用于在 Skill 列表中展示，帮助 AI 判断何时匹配使用该 Skill
+- `homepage`：Skill 的主页或仓库地址，可留空
+
+#### 2.3 Markdown Body 指令正文规范
+
+指令正文是 Skill 的核心，AI 在加载 Skill 后会仔细阅读此部分内容来学习如何使用该 Skill。正文需包含以下模块：
+
+**模块一：概述**
+
+- 清晰说明该 Skill 的核心功能、适用场景、能解决的问题
+- 列出 Skill 的能力边界（能做什么、不能做什么）
+
+**模块二：环境依赖**（如有）
+
+- 列出 Skill 运行所需的外部依赖（如 Node.js 包、Python 库、系统工具等）
+- 说明依赖的安装方式和版本要求
+- 如果无外部依赖，可省略此模块
+
+**模块三：使用指令**
+
+- 这是 AI 执行 Skill 时的核心参考，必须详细、精确、可操作
+- 以步骤化的方式描述 Skill 的使用流程
+- 每个步骤需说明：输入是什么、执行什么操作、输出是什么
+- 如果涉及命令行操作，提供完整的命令示例
+- 如果涉及代码调用，提供完整的代码示例
+- 如果有多种使用场景，分场景给出说明
+
+**模块四：输入输出规范**
+
+- 定义 Skill 接受的输入格式和参数说明
+- 定义 Skill 输出的结果格式和内容说明
+- 提供输入输出的示例
+
+**模块五：注意事项与限制**
+
+- 说明使用过程中需要注意的关键点
+- 列出已知限制和边界条件
+- 提供常见问题的处理建议
+
+### 第三步：执行生成
+
+1. 理解用户要生成的技能用途
+2. 在当前工作目录下创建 `<skill-name>/` 目录
+3. 编写 `SKILL.md`，遵循上述 YAML Frontmatter + Markdown Body 规范
+4. 如有需要，创建 `scripts/` 和 `assets/` 辅助目录及文件
+5. 确认所有文件内容完整、格式正确

package/dist/generate-tool.md

@@ -0,0 +1,88 @@
+---
+name: 'generate-tool'
+description: '根据用户需求生成符合 Deepfish 规范的 Node.js 自定义工具模块'
+homepage: ''
+---
+
+# 生成自定义工具
+
+你是一个工具生成器，负责根据用户需求生成一个 Node.js 工具模块（`.js` 文件）。
+
+## 输出规范
+
+在当前工作目录下创建 `deepfish-tool-{工具功能}/` 目录，在其中生成 `index.js`。
+
+### 返回值类型
+
+函数必须返回以下两种类型之一：
+
+```js
+// 成功
+{ success: true, data: any }
+
+// 失败
+{ success: false, error: '错误描述' }
+```
+
+### index.js 模板
+
+```js
+const functions = {
+  /**
+   * @param {string} param1 - 参数1说明
+   * @param {number} param2 - 参数2说明
+   * @returns {{ success: boolean, data?: any, error?: string }}
+   */
+  myFunction(param1, param2) {
+    try {
+      // 实现逻辑
+      const result = `处理结果: ${param1}, ${param2}`;
+      return { success: true, data: result };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  },
+};
+
+const descriptions = [
+  {
+    type: 'function',
+    function: {
+      name: 'my_function',
+      description: '工具的功能描述，说明何时使用、做什么、返回什么',
+      parameters: {
+        type: 'object',
+        properties: {
+          param1: {
+            type: 'string',
+            description: '参数1的描述',
+          },
+          param2: {
+            type: 'number',
+            description: '参数2的描述',
+          },
+        },
+        required: ['param1'],
+      },
+    },
+  },
+];
+
+module.exports = { functions, descriptions };
+```
+
+## 规范
+
+1. **返回值**：必须是 `{ success: true, data: any }` 或 `{ success: false, error: string }`
+2. **命名**：函数名用 camelCase，工具名用 snake_case
+3. **描述**：每个工具和参数都要有清晰的中文描述
+4. **错误处理**：函数内部必须 try-catch，出错返回 `{ success: false, error: '...' }`
+5. **一个文件一个工具**：每个 index.js 只导出一个工具函数
+6. **参数类型**：支持 string、number、boolean、object、array
+
+## 执行步骤
+
+1. 理解用户要生成的工具功能
+2. 在当前工作目录下创建 `deepfish-tool-{功能名}/` 目录
+3. 编写 `index.js`，导出 `functions` 和 `descriptions`
+4. 确保代码语法正确、可以直接 `require` 使用