← 返回文档列表

go-stock 技能系统使用指南

使用指南浏览 112 更新 2026-08-27 17:03

> 正在渲染文档内容…

# go-stock 技能系统使用指南

本文档介绍 go-stock 的**技能（Skill）系统**：什么是技能、如何创建、导入、编辑、让 AI 使用，以及如何通过技能广场分享与获取他人技能。

---

## 一、技能是什么

技能 = **一组可复用的 AI 专业指令**，以文件夹形式存放，核心是 `SKILL.md` 文件（YAML 元数据 + Markdown 指令正文），可附带脚本、配置等任意文件。

**两个典型用法：**

| 用法 | 机制 | 适合场景 |
| --- | --- | --- |
| **斜杠指令**（`/` 手动选择） | 选中技能后，SKILL.md 正文**覆盖系统提示词**，本 轮对话按该技能的指令行事 | 明确想让 AI 扮演某个角色 / 执行固定流程 |
| **AI 自动选用**（DeepAgents 模式） | 技能列表注入 Agent，AI 依据 frontmatter 的 name/description **自主判断**是否加载某个技能的正文 | 开放式提问，让 AI 自己挑合适的方法论 |

> 💡 斜杠指令在所有 Agent 模式下可用；AI 自动选用目前仅 DeepAgents 模式（默认模式）支持。

---

## 二、技能的存储结构

```
<go-stock 可执行文件所在目录>/
└── skills/                        # 技能根目录（与工作目录无关）
    ├── 打板策略/                   # 一个技能 = 一个子目录
    │   ├── SKILL.md               # 必需：技能定义
    │   ├── scripts/run.sh         # 可选：附带脚本
    │   └── examples/demo.md       # 可选：示例/参考资料
    └── 复盘模板/
        └── SKILL.md
```

要点：

- 目录位置跟随**可执行文件**（`os.Executable()` 所在目录），从任何工作目录启动都不会变，避免「换目录启动数据丢失」；
- 每个一级子目录就是一个技能，**必须包含 `SKILL.md`**，否则不被识别；
- 目录名即技能的 `dirName`（用于斜杠指令与本地管理），显示名取自 SKILL.md 的 `name` 字段。

### SKILL.md 格式

```markdown
---
name: 龙头战法
description: A股超短线龙头股识别与跟踪策略，覆盖情绪周期定位、连板高度预判、断板处理纪律
---

## 你的任务
你是一名专注A股超短线的游资风格交易顾问……

## 情绪周期定位
……

## 纪律铁律
……
```

- `---` 包裹的头部是 **YAML frontmatter**，只有两个字段：`name`（名称）与 `description`（描述，**务必写清楚适用场景**——AI 自动选用全靠它判断）；
- 正文即喂给模型的完整指令，建议用 Markdown 结构化（角色设定 → 方法论 → 纪律约束 → 输出格式）；
- ⚠️ frontmatter 的字段值必须是**字符串**，不要写成数组或数字，否则该技能解析失败会被静默跳过（详见第七节 FAQ）。

---

## 三、入口位置

技能管理内嵌于**深入研究**页（路由 `/research`）：

- **技能管理区块**：本地技能列表 / 导入技能包 / 内置编辑器 / 打开技能广场；
- **MCP 服务区块**：与技能系统相邻（见 [MCP_GUIDE.md](MCP_GUIDE.md)）。

---

## 四、获取技能的三种方式

### 方式 A — 技能广场下载（推荐）

1. 技能管理 →「技能广场」按钮；
2. 浏览/搜索/按分类与排序（最新/最热/最多下载）筛选；
3. 点开技能详情 → 查看 SKILL.md 内容预览；
4. 点「导入」→ 自动下载 zip（base64）并解压到本地 `skills/` 目录，立即生效。

> - VIP 专属技能（带 VIP 标识）需开通 VIP 后才能下载；
> - 下载即本地化：之后离线可用，广场删除分享不影响已导入的本地副本。

### 方式 B — 导入本地 zip 技能包

从其他渠道（网站、好友）拿到 `.zip` 技能包后：

1. 技能管理 →「导入技能包」；
2. 选择 zip 文件 → 自动校验并解压。

zip 包要求与安全校验：

- 必须包含 `SKILL.md`（在根目录或子目录均可，子目录名会作为技能名）；
- 自动拦截路径穿越（含 `..` 的条目直接拒绝）；
- 解压写入量受限（防 zip 炸弹，声明大小与实际写入双重校验）。

### 方式 C — 手工创建

1. 在 `skills/` 下新建文件夹（名字即 dirName，建议用英文或无特殊符号，如 `dragon-strategy`）；
2. 新建 `SKILL.md`，按第二节格式填写；
3. 回到技能管理页点「刷新」即可看到。

---

## 五、在对话中使用技能

### 1. 斜杠指令（所有模式）

在 AI 助手输入框输入 `/`：

```
/
```

会弹出技能选择浮层，支持：

| 按键 | 作用 |
| --- | --- |
| 继续输入文字 | 按名称/描述**过滤**技能（如 `/龙头`） |
| `↑` / `↓` | 上下选择 |
| `Enter` | 选中（输入框中的 `/xxx` 文本自动清除） |
| `Esc` | 关闭浮层 |

选中后顶部出现技能标签，提示「已选择技能『xxx』，将忽略系统提示词」——**系统提示词下拉会被禁用**（技能指令优先），发送后整轮对话按技能行事。点标签上的 × 可清除恢复默认。

> 选中状态持久保存在本地，下次打开助手仍生效，记得按需清除。

### 2. AI 自动选用（DeepAgents 模式）

无需任何操作。DeepAgents 启动时会扫描 `skills/` 下所有合法技能，把 frontmatter 摘要交给模型；模型判断问题与某技能相关时自动读取其正文执行。

例：本地有「龙头战法」技能（description 提到情绪周期、连板），直接问：

> 「今天大盘冰点，怎么判断明天有没有修复的接力机会？」

模型识别到与技能描述相关 → 自动加载技能指令作答。

**description 的写法决定命中率**：写「做什么 + 适用于什么问题」，不要只写「很厉害的策略」。

---

## 六、管理本地技能

技能管理页表格列出所有本地技能（名称 / 目录名 / 描述），每行可：

| 操作 | 说明 |
| --- | --- |
| **编辑文件** | 打开内置编辑器：左侧文件树（含子目录），右侧编辑器；支持**新建文件/目录**（如 `scripts/run.sh`）、保存、删除文件（`SKILL.md` 不可删，防技能失效） |
| **删除技能** | 整目录删除，二次确认 |
| **刷新** | 重新扫描 `skills/`（手工在文件系统里改文件后需要刷新） |

> 编辑器常用于微调下载来的技能（比如把指令里的默认参数改成自己的），改完即时生效，无需重启。

---

## 七、分享技能到广场

1. 技能广场 →「分享我的技能」（需先登录广场账号）；
2. 从本地技能下拉中选择要分享的技能 → 自动打包为 base64 预填表单；
3. 填写标题、分类、简介，可勾选 **VIP 专属**（仅 VIP 用户可下载）；
4. 提交后广场出现你的分享，**我的分享**中可管理（更新/删除）。

> 分享的是打包快照：之后本地修改不会自动同步，需重新分享更新。

---

## 八、常见问题

### 1. 技能管理页看不到我手工创建的技能

- 确认目录在**可执行文件所在目录**的 `skills/` 下（不是工作目录）；
- 确认含 `SKILL.md` 且文件名大小写正确；
- 点「刷新」重新扫描。

### 2. `/` 弹不出技能菜单

本地没有任何合法技能时浮层为空。先按第四节导入或创建至少一个技能。

### 3. AI（DeepAgents）没有自动用我的技能

- 检查 `description` 是否描述清楚适用场景（AI 靠它判断相关性）；
- frontmatter 格式错误会被**静默跳过**——日志（`logs/wails.log`）中搜「跳过格式错误的技能」确认；
- 常见错误：`name`/`description` 值写成了 YAML 数组或数字；`---` 前有空行；缺结束 `---`。

### 4. 一个格式错误的 SKILL.md 会不会拖垮 AI？

不会。技能加载采用**容错后端**（tolerantSkillBackend）：单个技能解析失败仅记警告并跳过，其余技能与 Agent 正常运行。历史上曾出现一个错误技能导致整个 Agent 启动失败的问题，现已修复。

### 5. 导入 zip 报「压缩包包含非法路径」

zip 内条目名含 `..`（路径穿越攻击特征），已按安全策略拒绝。来源不可信的包不要强行导入。

### 6. VIP 技能下载提示「请先开通 VIP」

广场侧权限控制（服务端校验，非客户端判断）。开通 VIP 后重新下载即可。

### 7. 选了技能后系统提示词不生效

这是**设计行为**：斜杠指令选中的技能正文会覆盖系统提示词。清除技能标签即可恢复。

---

## 九、技术细节（开发者参考）

| 内容 | 位置 |
| --- | --- |
| 技能目录定位（`skills/`，跟随可执行文件） | `../app.go` → `skillsDir()` |
| zip 导入（zip slip 防护 / SKILL.md 校验 / 解压限流） | `../app.go` → `ImportSkillPackage()` / `ImportSkillFromBase64()` |
| 本地技能列表 / 删除 | `../app.go` → `ListFilesystemSkills()` / `DeleteFilesystemSkill()` |
| frontmatter 解析 / 技能提示词组装 | `../app.go` → `parseSkillFrontmatter()` / `buildSkillPromptByDirName()` |
| 目录名清洗（去 `..` / `/` 等非法字符） | `../app.go` → `sanitizeSkillDirName()` |
| 容错技能后端（DeepAgents 自动选用） | `../backend/agent/skill_backend.go` → `tolerantSkillBackend` |
| 技能管理前端 | `../frontend/src/components/skill-manager.vue` |
| 技能广场前端 | `../frontend/src/components/skillPlaza.vue` |
| 斜杠指令交互 | `../frontend/src/components/FloatingAgentAssistant.vue` → `checkSlashCommand()` 等 |

## 许可证

详见项目根目录的 LICENSE 文件。