← 返回文档列表

技能管理功能说明

功能说明浏览 107 更新 2026-08-26 17:35

> 正在渲染文档内容…

# 技能管理功能说明

## 功能概述

技能（Skill）是 go-stock 提供的**渐进式提示词注入机制**，让 AI 在 DeepAgents 模式下能够按需加载专业知识、工作流脚本或参考资料，而无需在每次对话中都占用宝贵的上下文 token。

技能以**文件系统目录**形式存储，每个技能是一个独立的目录，包含描述文件（`SKILL.md`）和可选的脚本、参考文档等资源。用户可以通过应用内的「技能管理」界面导入、编辑、管理这些技能。

## 技能的工作原理

### 渐进式展示（Progressive Disclosure）

go-stock 基于 eino ADK 的 skill 中间件实现技能系统。其核心机制是：

1. **启动时扫描**：DeepAgents 模式启动时，扫描 `skills/` 目录下所有包含 `SKILL.md` 的一级子目录，构建技能索引
2. **按需发现**：用户提问时，AI 根据问题内容判断是否需要某个技能，先读取技能的 `SKILL.md` 元数据
3. **激活注入**：当 AI 决定使用某技能时，技能的完整提示词被注入到对话上下文
4. **资源加载**：技能可引用 `scripts/`、`references/` 等子目录中的脚本或文档，按需读取

这种机制相比「始终注入所有提示词」的优势：

| 方式 | token 占用 | 适用场景 |
|------|-----------|---------|
| 始终注入 | 高（每次对话都消耗） | 简单固定的提示词 |
| 渐进式展示 | 低（仅激活时消耗） | 复杂、可组合的领域知识 |

### 仅 DeepAgents 模式生效

技能系统**仅在 DeepAgents 模式下启用**，原因：

- DeepAgents 模式内置 `write_todos`（任务规划）和 `task`（子 Agent 委派）能力，能够主动判断何时需要加载技能
- React / PlanExecute 模式架构不同，不支持 skill 中间件
- 若希望在简单任务中也使用技能，请切换到 DeepAgents 模式

## 技能目录结构

每个技能是 `skills/` 下的一个一级子目录，目录名即技能名。最小可用技能只包含一个 `SKILL.md` 文件：

```
skills/
└── my-skill/
    └── SKILL.md
```

完整技能可包含脚本、参考文档等资源：

```
skills/
└── my-skill/
    ├── SKILL.md              # 必需：技能描述与提示词
    ├── scripts/              # 可选：脚本资源
    │   ├── analyze.py        # Python 脚本（Agent 可调用 execute 工具运行）
    │   └── fetch.sh          # Shell 脚本
    ├── references/           # 可选：参考文档
    │   ├── api-spec.yaml     # API 规范
    │   └── examples.json     # 示例数据
    └── config.toml           # 可选：配置文件
```

### 文件大小限制

- 单文件：≤ 10 MB
- 单技能总大小：≤ 100 MB

## SKILL.md 格式

`SKILL.md` 是技能的核心文件，包含技能的元数据和工作指引。文件由两部分组成：

1. **YAML FrontMatter**（`---` 之间的部分）：技能元数据，中间件启动时解析
2. **Markdown 正文**（`---` 之后）：技能的完整提示词，AI 调用技能时才加载

建议格式如下：

```markdown
---
name: 技能名称
description: 技能的简短描述，AI 通过它判断是否激活本技能
context: fork              # 可选：执行模式（fork / fork_with_context / 不设=inline）
agent: sub-agent-name      # 可选：fork 模式下使用的子 Agent 名（需配置 AgentHub）
model: deepseek-chat       # 可选：覆盖默认模型（inline 下切换后续对话模型，fork 下传给子 Agent）
---

# 技能名称

## 技能说明

在此处编写 AI 应当遵循的工作流程、分析框架、输出格式要求等。
这部分内容只在 AI 调用 skill 工具时才会被加载到上下文（渐进式展示）。

## 工作流程

1. 步骤一
2. 步骤二
3. 步骤三

## 资源引用

- `scripts/analyze.py`：数据预处理脚本
- `references/api-spec.yaml`：API 接口规范
```

**FrontMatter 字段说明**：

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 技能显示名称，也是 `skill` 工具调用的参数值 |
| `description` | string | 是 | 技能描述，**AI 据此自主判断是否调用本技能**（不是关键词匹配） |
| `context` | string | 否 | 执行模式：`fork`（新子 Agent 无历史）/ `fork_with_context`（新子 Agent 带历史）/ 不设=inline（默认，结果返回主对话） |
| `agent` | string | 否 | fork 模式下使用的子 Agent 名（需配置 AgentHub，go-stock 当前未配置，留空即可） |
| `model` | string | 否 | 覆盖默认模型名。inline 下后续 ChatModel 请求切换到该模型；fork 下传给子 Agent |

> 💡 关键提示：
> - **没有 `trigger_keywords` 字段**。技能激活完全由 AI 根据 `description` 自主判断，不是关键词匹配
> - `description` 应当清晰描述技能的适用场景，例如「提供 K 线形态识别、技术指标解读、买卖点判断」比「技术分析」更有效
> - FrontMatter 之外的正文内容**启动时不加载**，仅在 AI 调用 `skill` 工具时才注入上下文

## 界面介绍

技能管理界面位于「研究中心」→「技能管理」，包含三个主要区域：

### 1. 工具栏

| 按钮 | 说明 |
|------|------|
| 📥 导入技能包 | 从 `.zip` 文件导入技能到 `skills/` 目录 |
| 🔄 刷新 | 重新扫描 `skills/` 目录，更新技能列表 |

### 2. 技能列表表格

| 列 | 说明 |
|----|------|
| 技能名称 | 取自 `SKILL.md` 的 `name` 字段或目录名 |
| 目录 | 技能在 `skills/` 下的目录名（带文件夹图标） |
| 描述 | 技能的简短描述 |
| 操作 | 「编辑」（打开文件编辑器）、「删除」（移除整个技能目录） |

### 3. 文件编辑器（弹窗）

点击技能的「编辑」按钮后弹出，采用左右分栏布局：

**左侧文件树**：
- 「新建文件」按钮：输入路径如 `scripts/run.py` 或 `config.yaml` 即可创建
- 文件列表：默认展开所有目录，点击文件名切换编辑

**右侧编辑器**：
- 顶部：当前文件路径标签 + 「保存」按钮 + 「删除文件」按钮（`SKILL.md` 不可删除）
- 编辑器：
  - `.md` 文件 → **MdEditor**（支持实时预览、工具栏）
  - `.py` / `.pyw` → **CodeMirror 6**（Python 语法高亮）
  - `.yaml` / `.yml` → **CodeMirror 6**（YAML 语法高亮）
  - `.json` → **CodeMirror 6**（JSON 语法高亮）
  - 其他扩展名 → **CodeMirror 6**（无语法高亮，但保留行号、Tab 缩进、括号匹配等基础能力）

编辑器主题自动跟随应用主题（亮色/暗色），暗色下使用 `oneDark` 主题。

## 使用流程

### 导入技能包

从其他网站或社区下载的技能包通常为 `.zip` 格式，导入步骤：

1. 点击工具栏「导入技能包」按钮
2. 在弹出的文件选择对话框中选中 `.zip` 文件
3. 系统自动校验并解压到 `skills/` 目录

**ZIP 包格式要求**：

- 必须包含 `SKILL.md` 文件，否则提示「不是有效的技能包」
- 支持两种结构：
  - **扁平结构**：`SKILL.md` 在 zip 根目录，技能名取自 zip 文件名
    ```
    my-skill.zip
    ├── SKILL.md
    └── scripts/analyze.py
    ```
  - **嵌套结构**：`SKILL.md` 在子目录中，技能名取自第一级目录名
    ```
    my-skill.zip
    └── my-skill/
        ├── SKILL.md
        └── scripts/analyze.py
    ```
- 安全限制：禁止包含 `..` 路径（防 zip slip 攻击）
- 单文件 ≤ 10 MB，总计 ≤ 100 MB
- 若同名技能已存在，**先删除再覆盖导入**

### 在线编辑技能文件

1. 在技能列表中点击目标技能的「编辑」按钮
2. 弹窗左侧文件树中点击要编辑的文件
3. 右侧编辑器加载文件内容
4. 修改后点击顶部「保存」按钮，写入文件系统

**编辑器快捷操作**：

- `Tab` 键缩进（Python 文件默认 4 空格）
- 支持 `Ctrl+F` 查找替换（CodeMirror 内置）
- 行号、括号匹配、自动缩进（CodeMirror basicSetup）

### 新建文件

1. 在文件编辑器左侧点击「新建文件」按钮
2. 输入文件路径，如 `scripts/run.py` 或 `config.yaml`
3. 按回车或点击「确定」
4. 文件创建后自动选中新文件

**路径规则**：
- 使用 `/` 作为路径分隔符
- 支持创建子目录（如 `scripts/utils/helper.py`）
- 不允许包含 `..`

### 删除文件

1. 在文件树中选中要删除的文件
2. 点击顶部「删除文件」按钮
3. 在确认弹窗中点击「确定」

> ⚠️ `SKILL.md` 是技能的必需文件，**不可删除**。删除按钮对 `SKILL.md` 不显示。

### 删除技能

1. 在技能列表中点击目标技能的「删除」按钮
2. 在确认弹窗中点击「确定」
3. 整个技能目录（含所有文件）从文件系统移除

> ⚠️ 删除操作不可恢复，请谨慎操作。

## 与 Agent 的集成

### 自动加载技能

在 DeepAgents 模式下提问时，技能中间件的工作流程：

```
用户提问
   ↓
Agent 读取 skills/ 下所有技能的元数据
   ↓
判断问题是否匹配某技能的 description
   ↓
匹配 → 加载该技能的 SKILL.md 完整内容到上下文
   ↓
Agent 按 SKILL.md 中的工作流执行任务
   ↓
需要时通过 execute 工具运行 scripts/ 下的脚本
需要时通过 read_file 工具读取 references/ 下的文档
```

### Agent 可用的技能资源

DeepAgents 模式下，Agent 拥有文件系统和 Shell 工具：

| 工具 | 用途 |
|------|------|
| `ls` | 列出目录内容 |
| `read_file` | 读取文件 |
| `write_file` | 写入文件 |
| `edit_file` | 编辑文件 |
| `glob` | 文件名模式匹配 |
| `grep` | 文件内容搜索 |
| `execute` | 执行 Shell 命令（如运行 Python 脚本） |

Agent 可以通过这些工具读取或运行技能内的脚本与参考文档。

### 技能示例：技术分析助手

`SKILL.md`：

```markdown
---
name: 技术分析助手
description: 提供 K 线形态识别、技术指标解读、买卖点判断的专业分析框架
---

# 技术分析助手

## 分析流程

1. 调用 GetEastMoneyKLine 获取最近 60 日 K 线数据
2. 调用 GetEastMoneyKLineWithMA 计算 5/10/20/60 日均线
3. 识别 K 线形态（锤头线、十字星、吞没形态等）
4. 计算 MACD、RSI、KDJ 指标
5. 综合判断买卖信号

## 输出格式

| 指标 | 数值 | 信号 |
|------|------|------|
| ... | ... | ... |
```

`scripts/calc_indicators.py`：

```python
# 技术指标计算脚本，可被 Agent 通过 execute 工具调用
def calc_macd(closes, fast=12, slow=26, signal=9):
    # MACD 计算
    pass
```

## 常见问题

### Q1：技能管理菜单在哪？

技能管理位于「研究中心」→「技能管理」。

### Q2：导入的技能包为什么显示不出来？

- 确认 `.zip` 文件中包含 `SKILL.md`
- 检查 `SKILL.md` 是否在 zip 根目录或第一级子目录中
- 点击「刷新」按钮重新扫描技能目录
- 查看 `skills/` 目录是否被正确创建（通常位于应用工作目录下）

### Q3：技能在 React / PlanExecute 模式下为什么不生效？

技能系统**仅在 DeepAgents 模式下启用**。在 AI 智能体页面底部的 Agent 模式选择器中切换到 `🔬 DeepAgents` 模式即可。

### Q4：如何调试技能没有被 AI 激活的问题？

- 检查 `SKILL.md` 的 `description` 是否清晰描述了技能的适用场景（例如「提供 K 线形态识别、技术指标解读」比「技术分析」更有效）
- 在提问时显式包含技能相关关键词
- 查看应用日志确认技能中间件是否加载成功（搜索 "skill 中间件" 关键字）

### Q5：技能中的 Python 脚本如何被 Agent 调用？

Agent 通过 `execute` 工具运行命令，例如：

```
execute(command="python skills/my-skill/scripts/analyze.py --code sh600519")
```

DeepAgents 模式下子进程控制台窗口会自动隐藏，输出通过流式方式返回给 Agent。

### Q6：技能支持哪些文件类型？

技能目录可包含任意文件类型。编辑器对以下类型提供语法高亮：

| 扩展名 | 编辑器 | 高亮 |
|--------|--------|------|
| `.md` | MdEditor | Markdown + 实时预览 |
| `.py` / `.pyw` | CodeMirror 6 | Python |
| `.yaml` / `.yml` | CodeMirror 6 | YAML |
| `.json` | CodeMirror 6 | JSON |
| 其他 | CodeMirror 6 | 无高亮，保留基础编辑能力 |

### Q7：技能目录在文件系统中的位置？

技能目录默认位于应用工作目录下的 `skills/` 子目录。可通过应用文件管理器直接访问该目录进行批量管理。

### Q8：能否同时启用多个技能？

可以。DeepAgents 模式下，AI 根据问题内容判断需要哪些技能，可同时加载多个技能的提示词到上下文。但建议避免技能之间描述重叠过大，以免 AI 难以判断该激活哪个。

### Q9：如何分享自己创建的技能？

1. 将 `skills/<技能名>/` 目录打包为 `.zip` 文件
2. 确保包含 `SKILL.md`
3. 分享给其他用户，他们通过「导入技能包」按钮即可导入

### Q10：技能目录已存在时导入会怎样？