企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• 金融科技
• 桌面应用
• MCP Clients

导读

本文围绕 go-stock 的「技能管理」功能，系统讲解技能（Skill）系统的核心原理与完整实操：从渐进式提示词注入（Progressive Disclosure）的工作机制、SKILL.md的 FrontMatter 规范、skills/目录结构，到技能包的导入、在线编辑、与 DeepAgents 模式的集成，以及背后基于 eino ADK skill 中间件的源码级实现。读完本文，你将掌握如何为 go-stock 编写、导入、管理可被 AI 按需激活的专业技能，并理解其在 token 占用与上下文管理上的设计取舍。

一、功能概述：技能是什么

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

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

从项目描述看，go-stock 定位为 AI 赋能股票分析/选股工具（支持 A 股、港股、美股，数据全部保留在本地），技能系统正是为这类需要「K 线形态识别、技术指标解读、基本面分析、资讯研究」等复杂领域知识注入的场景而设计的：把专业分析框架沉淀成技能包，让 AI 在需要时自行加载。

二、技能的工作原理

2.1 渐进式展示（Progressive Disclosure）

go-stock 基于 eino ADK 的 skill 中间件实现技能系统（对应源码 backend/agent/agent.go 中buildSkillMiddleware的调用）。其核心机制是：

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

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

2.2 源码级的容错设计

从源码结构看，go-stock 并没有直接使用 eino 内置的filesystemBackend，而是实现了一个tolerantSkillBackend容错后端（backend/agent/skill_backend.go）。其背景注释（backend/agent/skill_backend.go）说明了原因：

eino 内置的filesystemBackend.list()在加载 SKILL.md 时，任意一个技能的 frontmatter 解析失败都会让 List/Get 返回错误。该错误会经由 skill 工具的Info()传播到NewToolNode，导致整个 DeepAgents Agent 构建工具列表失败，表现为：[NodeRunError] failed to convert tool list from call option: ... failed to unmarshal frontmatter: yaml: unmarshal errors: line 2: cannot unmarshal !!seq into string

也就是说，一个手写/导入错误的 SKILL.md 会拖垮整个 Agent 运行。go-stock 的容错实现复用 eino 的 frontmatter 提取与解析逻辑，但在单个技能解析失败时仅记录警告日志并跳过该技能，保证其余技能正常加载、Agent 不受影响（backend/agent/skill_backend.go）。

这一行为有测试用例直接验证：TestTolerantSkillBackendSkipsBadFrontmatter（backend/agent/skill_backend_test.go）构造了三个技能——正常技能、name被写成 YAML 序列的坏技能、缺少 frontmatter 分隔符的技能，断言List仍能成功返回 1 个可用技能（good-skill），且Get("bad-skill")返回未找到错误。这意味着：即使你的某个技能包格式有问题，也不会影响其他技能和 Agent 的正常运行，调试时请留意日志中的 "skill 中间件: 跳过格式错误的技能文件" 警告。

2.3 仅 DeepAgents 模式生效

技能系统仅在 DeepAgents 模式下启用，原因（参见 backend/agent/agent.go 的 createDeepAgent 设计说明）：

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

在 backend/agent/agent.go 中，createDeepAgent会先构造文件系统 Backend（tools.NewLocalFilesystemBackend）与流式 Shell（tools.NewLocalStreamingShell），再通过buildSkillMiddleware挂载 skill 中间件，并输出日志"DeepAgents 启用 skill 中间件（渐进式展示）"。

三、技能目录结构

每个技能是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。

在源码层面，技能目录的扫描通过GlobInfo以*/SKILL.md模式完成（backend/agent/skill_backend.go），即以skills/为 baseDir，只匹配一级子目录下的SKILL.md，与文档描述的「一级子目录」约束完全一致；若skills/目录不存在或 glob 失败，则视为无技能，不阻塞 Agent。

四、SKILL.md 格式规范

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

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

建议格式如下：

--- 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 字段说明：

💡 关键提示：

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

从源码看，frontmatter 的解析逻辑（backend/agent/skill_backend.go）要求文件必须以---分隔符开头，并在后续内容中找到\n---作为结束分隔符，否则解析失败；frontmatter与正文内容分别提取后，正文经strings.TrimSpace处理作为Skill.Content（backend/agent/skill_backend.go）。此外还包含一个stripSkillLineNumbers兼容处理（backend/agent/skill_backend.go）：某些文件系统后端会在每行前加「行号\t」前缀，此处会剥离首个制表符之前的内容。

五、界面介绍：技能管理

技能管理界面位于「研究中心」→「技能管理」（对应前端组件 frontend/src/components/skill-manager.vue），包含三个主要区域。

5.1 工具栏

从 frontend/src/components/skill-manager.vue 可以看到，工具栏还包含「技能广场」按钮（可在线获取技能包）以及技能卡片上的启用/停用开关（handleToggleSkill），卡片会展示技能名称（缺失时回退到目录名）与「已停用」标签。

5.2 技能列表表格

5.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主题。

六、使用流程

6.1 导入技能包

从其他网站或社区下载的技能包通常为.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；
• 若同名技能已存在，先删除再覆盖导入。

⚠️ 提示：技能包导入后存放于skills/目录，该目录位于应用工作目录（go-stock 根目录）下。这一点与源码中buildSkillMiddleware的skillsDir := filepath.Join(rootDir, "skills")（backend/agent/agent.go）一致——DeepAgents 的文件系统沙箱根即应用可执行文件所在目录。

6.2 在线编辑技能文件

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

编辑器快捷操作：

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

6.3 新建文件

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

路径规则：

• 使用/作为路径分隔符；
• 支持创建子目录（如scripts/utils/helper.py）；
• 不允许包含..。

6.4 删除文件

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

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

6.5 删除技能

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

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

七、与 Agent 的集成

7.1 自动加载技能

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

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

在源码层面，「启动时扫描 → 判断是否注册中间件」发生在 backend/agent/agent.go 的buildSkillMiddleware：先用容错后端List所有可用技能，若len(matters) == 0（目录不存在或无可用技能）则返回 nil、不注册中间件；否则通过skill.NewMiddleware(ctx, &skill.Config{Backend: fileBackend})创建中间件并挂载到 DeepAgents 的 handlers 中。激活后，skill工具会以name（FrontMatter 字段）作为参数值按名获取技能——对应tolerantSkillBackend.Get的实现（backend/agent/skill_backend.go）。

7.2 Agent 可用的技能资源

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

Agent 可以通过这些工具读取或运行技能内的脚本与参考文档。这些能力来自 go-stock 自实现的沙箱化文件系统 Backend backend/agent/tools/filesystem_backend.go：它以rootDir为沙箱根，所有路径操作均通过resolve校验防止路径穿越（支持 POSIX 与 Windows 两种路径风格，并解析软链接后校验是否越界，backend/agent/tools/filesystem_backend.go）；GrepRaw使用 Go 标准库 regexp（RE2 语法，与 ripgrep 高度兼容）实现文件内容搜索（backend/agent/tools/filesystem_backend.go）；GlobInfo使用bmatcuk/doublestar/v4支持**递归匹配（backend/agent/tools/filesystem_backend.go）。

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

SKILL.md：

--- name: 技术分析助手 description: 提供 K 线形态识别、技术指标解读、买卖点判断的专业分析框架 --- # 技术分析助手 ## 分析流程 1. 调用 GetEastMoneyKLine 获取最近 60 日 K 线数据 2. 调用 GetEastMoneyKLineWithMA 计算 5/10/20/60 日均线 3. 识别 K 线形态（锤头线、十字星、吞没形态等） 4. 计算 MACD、RSI、KDJ 指标 5. 综合判断买卖信号 ## 输出格式 | 指标 | 数值 | 信号 | |------|------|------| | ... | ... | ... |

scripts/calc_indicators.py：

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

该示例中调用的GetEastMoneyKLine、GetEastMoneyKLineWithMA等工具是 go-stock 内置的东方财富 K 线数据接口（参见 backend/data/eastmoney_kline_api.go 相关实现），Agent 在 DeepAgents 模式下可以像调用普通工具一样获取真实行情数据，再结合技能提示词里的分析框架完成计算与判断。

八、常见问题（FAQ）

Q1：技能管理菜单在哪？

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

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

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

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

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

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

• 检查SKILL.md的description是否清晰描述了技能的适用场景（例如「提供 K 线形态识别、技术指标解读」比「技术分析」更有效）；
• 在提问时显式包含技能相关关键词；
• 查看应用日志确认技能中间件是否加载成功（搜索 "skill 中间件" 关键字）。注意：若存在格式错误的技能包，日志会出现skill 中间件: 跳过格式错误的技能文件警告（来源 backend/agent/skill_backend.go），此时应优先修复该技能包的 frontmatter（如name字段被误写为 YAML 列表导致cannot unmarshal !!seq into string）。

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

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

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

DeepAgents 模式下子进程控制台窗口会自动隐藏，输出通过流式方式返回给 Agent（对应源码 backend/agent/tools/streaming_shell.go 的流式 Shell 实现）。

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

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

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

技能目录默认位于应用工作目录下的skills/子目录。可通过应用文件管理器直接访问该目录进行批量管理。从源码看，DeepAgents 的文件系统沙箱根deepAgentRootDir()为可执行文件所在目录（桌面应用启动时即 go-stock 根目录），skills目录即rootDir/skills（backend/agent/agent.go）。

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

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

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

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

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

如果同名技能目录已存在，系统会先删除原目录再覆盖导入。如需保留原内容，请先在编辑器中备份。

九、补充：数据库中另有一套技能模型（延伸阅读）

需要说明的是，go-stock 的技能体系包含两条线：本文主体讲述的文件系统技能（skills/<技能名>/SKILL.md，由 eino skill 中间件驱动），以及仓库中另有一套基于数据库的技能模型models.Skill（backend/models/models.go，表名skills），字段包括名称、分类、系统提示词（SystemPrompt）、示例对话（Examples）、触发关键词（TriggerKeywords）、绑定的 MCP 服务器 ID（MCPServerIDs）、启用状态与排序值；其 CRUD 由 backend/data/skill_api.go 提供，并封装为ListSkills、CreateSkill、UpdateSkill、EnableSkill等 Agent 工具（backend/agent/tools/mcp_skill_tools.go）。从 backend/agent/agent.go 的注释「构建 skill 中间件：组合文件系统技能（SKILL.md）与数据库技能（models.Skill）」可以推断，两者在 DeepAgents 中会被共同纳入技能中间件体系。若你在界面上看到技能有「分类」「触发关键词」「绑定 MCP 服务」等字段，即对应这套数据库模型；而本文的SKILL.md文件技能则强调「没有trigger_keywords字段、完全靠 AI 自主判断」，使用时请注意区分。

结语

技能系统是 go-stock 在 AI 股票分析场景下的关键基础设施：它以SKILL.md为最小单元，通过渐进式展示把复杂的领域专业知识、工作流脚本和参考文档以极低的常驻 token 成本注入 DeepAgents 的上下文，配合容错后端与沙箱化文件系统，既保证了单个坏技能不会拖垮整个 Agent，又让 AI 具备读取脚本、执行命令的完整工程能力。掌握技能包的编写、导入与调试方法，你就能把「K 线形态识别」「财务分析框架」「资讯研究流程」等经验沉淀为可复用、可分享的技能，让 go-stock 的 AI 助手真正贴合自己的分析习惯。

• 人工智能
• 大模型
• AI 应用
• AI Agent
• RAG
• 金融科技
• 桌面应用
• MCP Clients