妙想自选股管理 Skill（mx-zixuan）实战解析：基于东方财富 API 的自然语言自选股增删查

妙想自选股管理 Skill（mx-zixuan）实战解析：基于东方财富 API 的自然语言自选股增删查

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents

导读

本篇文章围绕 hello-agents 仓库中「智能股票分析助手」项目（Co-creation-projects/lcyting-StockSage-agent）的自选股管理 Skill（mx-zixuan）展开，讲解如何通过自然语言查询、添加、删除东方财富通行证账户下的自选股，并给出可直接运行的 Python 脚本调用方式、底层接口协议与异常处理方案。读完本文，你将掌握一个完整 Skill 的骨架结构、凭据管理方式，以及它如何被后端服务层与 API 路由层二次封装、最终供 Web 前端与 Agent 调用。

一、Skill 定位：把"自选股管理"变成一句自然语言

mx-zixuan 是东方财富妙想团队发布的官方 Skill，其元信息定义在 SKILL.md 的 YAML frontmatter 中：

该 Skill 的核心能力只有三个，全部围绕"东方财富通行证账户下的自选股数据"：

• ✅ 查询我的自选股列表
• ✅ 添加指定股票到我的自选股列表
• ✅ 从我的自选股列表中删除指定股票

所有操作均以自然语言指令为输入，接口统一返回 JSON 格式内容。这与仓库中其他妙想 Skill（智能选股 mx-xuangu、模拟组合管理 mx-moni、金融数据 mx-data 等）共享同一套命名规范与凭据体系，是 StockSage 项目中"自选股"业务能力的底层数据源。

二、配置与前置要求

2.1 获取并配置 API Key

运行该 Skill 只需一个密钥MX_APIKEY，步骤如下：

1. 在东方财富妙想 Skills 页面获取 apikey（SKILL.md 的homepage字段即指向该申请入口）。
2. 将 apikey 配置到环境变量MX_APIKEY：

   export MX_APIKEY=your_apikey_here

3. 确保服务器网络可以访问https://mkapi2.dfcfs.com。

从源码实现看，mx_zixuan.py 的get_apikey()提供了两级取值逻辑：

1. 优先读环境变量：os.environ.get("MX_APIKEY", "")；
2. 环境变量缺失时回退读.env文件：查找mx-zixuan目录上一级的.env文件，逐行解析MX_APIKEY=value格式的键值对（自动忽略空行与#注释行）。

两级都取不到时，会在 stderr 打印❌ 未找到MX_APIKEY，请设置环境变量的提示并抛出RuntimeError("MX_APIKEY 未配置")。这一设计与仓库中其他mx_*Skill 保持一致，方便在本地开发时用.env文件统一管理密钥。

2.2 安全注意事项（官方声明）

• 外部请求：本 Skill 会将您的查询文本发送至东方财富官方 API 域名mkapi2.dfcfs.com以获取金融数据；
• 凭据保护：API Key 仅通过环境变量MX_APIKEY在服务端或受信任的运行环境中使用，不会在前端明文暴露。

2.3 输出目录与文件约定

• 默认输出目录：/root/.openclaw/workspace/mx_data/output/（自动创建，对应源码中output_dir.mkdir(parents=True, exist_ok=True)的初始化逻辑）；
• 输出文件名前缀：mx_zixuan_；
• 输出文件：
  • mx_zixuan_{query}.csv—— 自选股列表 CSV 格式（方便 Excel 打开查看）；
  • mx_zixuan_{query}_raw.json—— API 原始 JSON 数据（供二次开发）。

输出目录可通过命令行参数--output-dir覆盖，源码在 main() 中优先取参数值，缺省时才使用上述默认路径。

三、直接调用：Python 脚本三种操作速览

先设置环境变量：

export MX_APIKEY=your_apikey_here

3.1 查询自选股列表

# 明确命令 python ./mx_zixuan.py query # 自然语言查询 python ./mx_zixuan.py "查询我的自选股列表" python ./mx_zixuan.py "我的自选" python ./mx_zixuan.py "看一下自选"

3.2 添加股票到自选股

# 明确命令 python ./mx_zixuan.py add "贵州茅台" python ./mx_zixuan.py add "300059" # 自然语言 python ./mx_zixuan.py "把贵州茅台添加到我的自选股列表" python ./mx_zixuan.py "加入自选 比亚迪"

3.3 删除自选股

# 明确命令 python ./mx_zixuan.py delete "贵州茅台" # 自然语言 python ./mx_zixuan.py "把贵州茅台从我的自选股列表删除" python ./mx_zixuan.py "删除自选 万科A"

3.4 底层命令解析逻辑

直接裸跑脚本且不带参数时，会打印完整使用帮助并退出（exit code 1）。从 main() 的命令分派逻辑可以看清三种模式的判定规则：

这意味着即使不记忆任何命令语法，直接把一句话丢给脚本，它也能通过关键词路由到正确的接口。

四、异常情形与处理方式（完整对照表）

SKILL.md 给出了覆盖网络、鉴权、限流、业务数据四类异常的排查指引：

此外，脚本自身的错误处理逻辑还包括：

• 未配置 apikey：提示设置环境变量MX_APIKEY（并在.env文件读取失败时打印读取异常）；
• 接口调用失败：requests层的response.raise_for_status()会抛出 HTTP 错误，业务层的status/code非 0 时打印❌ 查询失败/操作失败及服务端返回的message；
• 数据为空：format_query_result()在dataList为空时提示用户到东方财富 App 查询。

五、输出示例

5.1 查询自选股成功

📊 我的自选股列表 ================================================================================ 股票代码 | 股票名称 | 最新价(元) | 涨跌幅(%) | 涨跌额(元) | 换手率(%) | 量比 -------------------------------------------------------------------------------- 600519 | 贵州茅台 | 1850.00 | +2.78% | +50.00 | 0.35% | 1.2 300750 | 宁德时代 | 380.00 | -1.25% | -4.80 | 0.89% | 0.9 ================================================================================ 共 2 只自选股

查询完成后会自动保存：

• CSV 格式方便 Excel 打开查看；
• 原始 JSON保存供二次开发。

从源码 format_query_result() 可以看出终端表格只抽取 7 个展示字段（SECURITY_CODE、SECURITY_SHORT_NAME、NEWEST_PRICE、CHG、PCHG、010000_TURNOVER_RATE、010000_LIANGBI），并对涨跌幅做了正负号与颜色语义处理（涨幅为正时自动加+前缀）；而 CSV 则依据接口返回的columns元数据把全部列的中文标题作为表头写出（使用utf-8-sig编码，确保 Excel 打开不乱码）。

5.2 添加/删除成功

✅ 操作成功：贵州茅台已添加到自选股列表

六、底层接口协议

两个接口都使用POST + JSON请求，鉴权统一通过 Header 传递apikey：

6.1 查询接口

• URL：https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/get
• 方法：POST
• Header：apikey: {MX_APIKEY}
• Body：空 JSON{}

对应源码 query_self_select()：携带Content-Type: application/json与apikey两个 Header，请求超时时间设为 30 秒，返回响应体 JSON。

6.2 管理接口（添加/删除）

• URL：https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/manage
• 方法：POST
• Header：apikey: {MX_APIKEY}
• Body：{"query": "自然语言指令"}

对应源码 manage_self_select()：与查询接口的区别在于请求体携带query字段，内容即"把 X 添加到我的自选股列表"或"把 X 从我的自选股列表删除"这类自然语言指令，由妙想服务端解析执行。

6.3 响应状态判定约定

两处格式化函数均遵循同一判定规则：status与code同时为 0 才算成功，否则取message字段打印错误原因。查询接口的成功响应嵌套结构为data.allResults.result.columns（列定义）与data.allResults.result.dataList（行数据），后续的 StockSage 后端服务层解析也正是沿用了这套路径。

七、在 StockSage 项目中的工程化封装

mx-zixuan 不只是命令行脚本，在「智能股票分析助手」中，它被后端服务层与 API 层二次封装，成为 Web 端"自选股"功能的真实数据源（见项目 README 中"业务 API 与 Agent 分工"一节：选股、自选股、模拟交易由后端 Service 直连skills/）。

7.1 服务层：watchlist_service.py

watchlist_service.py 将脚本的模块级函数直接 import 复用：

• 启动时把skills/自选股管理/mx-zixuan目录注入sys.path，然后import mx_zixuan as _mx；
• get_watchlist()：调用_mx.query_self_select(settings.MX_APIKEY)，将返回的dataList中 7 个字段映射为{code, name, price, change_pct, change_amount, turnover_rate, volume_ratio}结构；
• add_to_watchlist() / delete_from_watchlist()：分别拼接"把 X 添加到我的自选股列表""把 X 从我的自选股列表删除"指令后调用_mx.manage_self_select()；
• 结果缓存：查询结果写入妙想侧进程内 TTL 缓存（默认 600 秒，与 mx_data / mx_search 共用），添加/删除成功后会调用_invalidate_watchlist_cache()主动失效缓存，保证下一次查询立即拿到最新数据；
• API Key 兜底校验：MX_APIKEY未配置或仍为占位值your-mx-apikey-here时直接返回"MX_APIKEY 未配置"错误，不发起网络请求。

7.2 API 层：watchlist.py

watchlist.py 以 FastAPI 暴露三个 RESTful 接口：

服务层返回的success/error会被转换为统一的success_response/error_response包装，前端 Vue3 页面（仪表盘自选直接价格展示、股票分析页与智能选股结果行"加自选"、移除二次确认）均经由这组接口落地。这也印证了 README 中"自选股增删查直接走 Service → skills 直连"的架构设计——Skill 本身不依赖任何 Agent 框架，可被 CLI、Web 服务、Agent 工具等多种形态复用。

八、Skill 目录规范小结

一个完整的妙想 Skill 目录通常由三个文件组成（本仓库skills/下所有妙想技能均遵循此约定）：

自选股管理/mx-zixuan/ ├── SKILL.md # 元信息（frontmatter）+ 能力说明 + 使用方式 + 异常处理 + 接口文档 ├── _meta.json # 平台元数据（ownerId / slug / version / publishedAt） └── mx_zixuan.py # 可直接执行的命令行工具实现

从源码结构看，mx_zixuan.py中safe_filename()对查询词做文件名安全化（空格、斜杠、冒号等替换为下划线并截断 80 字符）、输出文件前缀mx_zixuan_、目录自动创建等约定均与其他mx_*脚本保持一致，便于在统一的/root/.openclaw/workspace/mx_data/output/目录下聚合管理所有妙想技能的产物。如果你需要在本仓库中继续扩展自选股相关能力，参照该目录结构复制改造即可。

九、总结

mx-zixuan 以"一行命令 + 一句自然语言"的方式屏蔽了东方财富自选股接口的复杂度：查询、添加、删除三类操作共用两个 POST 接口，凭据统一收敛到MX_APIKEY，结果自动落盘为 CSV 与原始 JSON，异常场景在官方文档中均给出明确处置建议。在 hello-agents 的 StockSage 项目中，它又被服务层与 API 层二次封装为可缓存、可失效的 Web 接口，验证了一条清晰的 Skill 落地路径：Skill 定义数据能力 → Service 层做解析与缓存 → API 层做协议适配 → 前端/Agent 消费。后续如需了解同仓库其他妙想技能（智能选股、模拟组合、金融数据、资讯搜索），可对比阅读对应 SKILL.md 与实现脚本，会发现它们共享同一套设计与工程化范式。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents