妙想自选股管理 Skillmx-zixuan实战指南基于东方财富通行证账户的自然语言自选股增删查【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents妙想自选股管理 Skillmx-zixuan是东方财富妙想团队基于东方财富通行证账户数据与行情底层数据构建的 Agent 技能它允许智能体通过一句自然语言即可查询、添加、删除指定账户下的自选股并以 JSON 接口返回结构化结果。本文以仓库中 自选股管理/mx-zixuan/SKILL.md 为核心结合 mx_zixuan.py 源码及其在 StockSage-agent 后端服务层、API 路由层、缓存层的完整集成方式带你掌握该 Skill 的配置、调用、输出解析与排障方法并理解其底层 API 契约与工程化接入路径。一、功能概览一个 Skill 覆盖自选股三种核心操作mx-zixuan的核心定位是把「自选股管理」这项原本需要在东方财富 App 中手工完成的账户操作封装成可通过自然语言驱动的能力。按 SKILL.md 的功能列表它支持三种操作✅ 查询我的自选股列表✅ 添加指定股票到我的自选股列表✅ 从我的自选股列表中删除指定股票从实现看这三种操作背后对应妙想侧的两个 HTTP 接口查询走self-select/get添加与删除共用self-select/manage详见下文「接口说明」。Skill 层负责把自然语言指令、明确的query/add/delete命令统一翻译成对应的 API 调用并把返回结果格式化为人类可读的表格、CSV 文件与原始 JSON。值得注意的是在 StockSage-agent 中该 Skill 属于「业务 API 直连层」根据项目 README.md 的说明选股、自选股、模拟交易由后端 Service直连skills/目录不经独立 Agent。也就是说mx-zixuan既可以作为独立 Python 脚本被直接调用也可以被后端服务层 import 后作为内部模块复用——这正是本文要演示的两条使用路径。二、前置要求与安全注意事项按照 SKILL.md 的说明使用前需要满足三个前置要求获取东方财富妙想 Skills 页面的 API Key将 API Key 配置到环境变量MX_APIKEY确保运行环境网络可以访问妙想 API 域名mkapi2.dfcfs.com。原文档同时给出了两条安全注意事项这里完整保留并补充说明⚠️安全注意事项外部请求本 Skill 会将您的查询文本发送至东方财富官方 API 域名mkapi2.dfcfs.com以获取金融数据。因此查询文本中请勿携带与金融数据无关的敏感信息。凭据保护API Key 仅通过环境变量MX_APIKEY在服务端或受信任的运行环境中使用不会在前端明文暴露。从源码层面看mx_zixuan.py 中读取凭据的逻辑get_apikey()严格限定在环境变量与本地.env文件两个来源密钥不会出现在请求 URL 中而是统一放在 HTTP Header 的apikey字段里发送从代码层面落实了「凭据不进前端」的约束。三、快速开始直接 Python 脚本调用3.1 配置环境变量# 先设置环境变量 export MX_APIKEYyour_apikey_here3.2 查询自选股列表# 明确命令 python ./mx_zixuan.py query # 自然语言查询 python ./mx_zixuan.py 查询我的自选股列表 python ./mx_zixuan.py 我的自选 python ./mx_zixuan.py 看一下自选3.3 添加股票到自选股# 明确命令 python ./mx_zixuan.py add 贵州茅台 python ./mx_zixuan.py add 300059 # 自然语言 python ./mx_zixuan.py 把贵州茅台添加到我的自选股列表 python ./mx_zixuan.py 加入自选 比亚迪3.4 删除自选股# 明确命令 python ./mx_zixuan.py delete 贵州茅台 # 自然语言 python ./mx_zixuan.py 把贵州茅台从我的自选股列表删除 python ./mx_zixuan.py 删除自选 万科A3.5 CLI 参数解析细节从 mx_zixuan.py 的实现看脚本基于标准库argparse定义了三个位置参数与一个可选参数参数含义示例command可选明确命令或自然语言指令query/add/delete/看一下自选stock可选股票名称或 6 位代码贵州茅台/300059--output-dir可选指定输出目录python ./mx_zixuan.py query --output-dir ./tmp命令解析遵循以下优先级逻辑对应源码main()中的分支query/list/查询/列表→ 走查询接口add/添加/增加 股票参数 → 自动构造指令把{stock}添加到我的自选股列表并调用管理接口delete/del/remove/删除/移除 股票参数 → 自动构造指令把{stock}从我的自选股列表删除并调用管理接口其余内容一律视为自然语言若文本命中查询/列表/我的自选/有哪些等关键词则走查询接口否则整段文本作为query原样提交给管理接口。注意自然语言模式下若同时传入command与stock两个参数脚本会把二者拼接后提交query args.stock例如python ./mx_zixuan.py 加入自选 比亚迪实际提交的查询文本为加入自选 比亚迪。若不带任何参数运行脚本会打印使用说明并退出。四、核心实现解析从自然语言到妙想 API4.1 接口说明原文档给出了完整的接口契约这里结合源码原样保留查询接口URL:https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/get方法: POSTHeader:apikey: {MX_APIKEY}管理接口添加/删除URL:https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/manage方法: POSTHeader:apikey: {MX_APIKEY}Body:{query: 自然语言指令}两个 URL 在源码中以模块级常量QUERY_URL与MANAGE_URL定义且请求均设置了timeout30秒的超时保护与Content-Type: application/json请求头QUERY_URL https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/get MANAGE_URL https://mkapi2.dfcfs.com/finskillshub/api/claw/self-select/manage查询接口使用空 JSON 体{}管理接口携带{query: 自然语言指令}。也就是说「添加」和「删除」在协议层面其实是同一个接口区分动作的是query文本中的语义「添加到」「从…删除」这解释了为什么自然语言可以直接驱动增删操作。4.2 响应结构解析与展示字段查询接口返回 JSON 的结构遵循妙想平台统一的data.allResults.result三层封装源码format_query_result()中可见result.status/result.code接口状态码0表示成功非 0 视为失败并输出messageresult.data.allResults.result.columns返回列的元信息数组result.data.allResults.result.dataList自选股数据行数组。脚本从中提取 7 个展示字段并格式化为终端表格响应字段 Key中文列名说明SECURITY_CODE股票代码6 位证券代码SECURITY_SHORT_NAME股票名称证券简称NEWEST_PRICE最新价(元)最新成交价CHG涨跌幅(%)相对昨收的涨跌幅源码对正值自动加前缀并以%显示PCHG涨跌额(元)涨跌绝对值010000_TURNOVER_RATE换手率(%)当日换手率010000_LIANGBI量比当日量比这一字段集合与后端 watchlist_service.py 中get_watchlist()解析出的字段一一对应code/name/price/change_pct/change_amount/turnover_rate/volume_ratio说明前端仪表盘展示的自选股卡片数据正是来源于此。五、输出与文件持久化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 格式utf-8-sig编码Excel 可直接打开中文列名不乱码方便查看原始 JSON 保存供二次开发。5.2 添加/删除成功输出示例✅ 操作成功贵州茅台已添加到自选股列表5.3 文件命名与输出目录约定按照 SKILL.md 的配置说明默认输出目录/root/.openclaw/workspace/mx_data/output/自动创建输出文件名前缀mx_zixuan_输出文件mx_zixuan_{query}.csv- 自选股列表 CSV 格式mx_zixuan_{query}_raw.json- API 原始 JSON 数据源码中的实现细节如下输出目录默认值为Path(/root/.openclaw/workspace/mx_data/output)可通过--output-dir覆盖并在启动时mkdir(parentsTrue, exist_okTrue)自动递归创建文件名经过safe_filename()处理将空格、/、\、:、*、?、引号、、、|等非法字符统一替换为下划线且截断到最长 80 字符保证跨平台文件系统安全查询动作实际生成的文件名为mx_zixuan_我的自选股列表.csv与mx_zixuan_我的自选股列表_raw.json固定安全名不随查询文本变化CSV 的列头取自响应columns中的中文标题原始 JSON 则以ensure_asciiFalse, indent2写入便于人工阅读与二次解析。六、异常情形与处理方式原文档提供了完整的异常排查表这里原样保留并补充源码侧的判断依据异常情形可能原因处理方式connect: Connection refused网络无法访问 mkapi2.dfcfs.com检查服务器网络配置确保能访问公网401 Unauthorized / API密钥不存在API Key 错误或已失效前往妙想 Skills 页面重新获取 API Key 并更新环境变量code113 / 今日调用次数已达上限当日调用次数超限前往妙想 Skills 页面获取更多调用次数自选股列表为空账户下没有自选股在东方财富 App 添加自选股后重试或使用 add 命令添加找不到该股票股票名称/代码不正确确认股票名称或代码正确使用 6 位数字代码成功率更高操作失败股票已经在自选股中添加或不在自选股中删除先查询确认当前自选股列表再操作JSON 解析错误网络中断或返回内容不完整检查网络后重试补充两个源码层面的错误处理事实未配置 API Keyget_apikey()首先读环境变量MX_APIKEY若为空则回退读取 Skill 所在目录上级的.env文件逐行解析MX_APIKEYxxx两处都拿不到时会向 stderr 输出❌ 未找到MX_APIKEY请设置环境变量并抛出RuntimeError终止运行。业务失败判定查询与管理结果的status与code均为0才视为成功format_query_result/format_manage_result中的判断否则输出❌ 查询失败: {message}或❌ 操作失败: {message}失败信息直接取自妙想接口返回的message字段方便定位具体原因。七、接入后端服务从 Skill 到 REST API 的工程化路径mx-zixuan在 StockSage-agent 中不是孤立脚本而是被后端服务层直接复用。理解这条调用链可以帮你把该 Skill 复用到自己的项目中。7.1 服务层封装与缓存后端 watchlist_service.py 在启动时把skills/自选股管理/mx-zixuan目录插入sys.path随后import mx_zixuan直接复用其query_self_select()与manage_self_select()两个函数。服务层做了三件关键的事参数来源统一API Key 不再读环境变量而是从应用配置settings.MX_APIKEY注入对应 config.py 中的MX_APIKEY配置项可通过.env设置并做了占位值检查your-mx-apikey-here视为未配置结果结构化把 Skill 返回的原始字段映射为{code, name, price, change_pct, change_amount, turnover_rate, volume_ratio}结构供前端直接渲染进程内计时缓存查询结果写入 mx_timed_cache.py 实现的MXTimedCache线程安全、LRU 淘汰、默认最多 400 条默认 TTL 为 600 秒TTL 内相同查询直接返回快照避免重复消耗妙想接口的当日调用额度添加/删除成功后则主动delete使缓存失效防止前端展示陈旧列表。7.2 API 路由层backend/app/api/watchlist.py 以 FastAPI 路由暴露了三个 REST 端点挂载前缀/api/v1方法路径说明GET/api/v1/watchlist/查询自选股列表返回stocks与totalPOST/api/v1/watchlist/添加自选股Body 为{stock: 贵州茅台}DELETE/api/v1/watchlist/{stock}删除自选股三个端点分别转发到服务层的get_watchlist()/add_to_watchlist()/delete_from_watchlist()最终落到mx_zixuan的查询与管理接口。也就是说一条完整链路是前端操作 → FastAPI 路由 → watchlist_service → mx_zixuan Skill → 妙想 API。7.3 相关配置项速查在 config.py 中与妙想能力直接相关的配置项如下配置项默认值说明MX_APIKEY空东方财富妙想 API Key必填MX_API_URLhttps://mkapi2.dfcfs.com/finskillshub妙想 API 基础域名MX_CACHE_TTL_SECONDS600妙想查询缓存 TTL秒≤0 表示不读缓存但仍写入供额度用尽降级若要在自己的项目里接入mx-zixuan最小配置只需设置MX_APIKEY并保证网络可达即可需要控制接口调用频率时可参照MX_CACHE_TTL_SECONDS的做法引入一层 TTL 缓存。八、使用建议与最佳实践基于原文档提示与源码实现总结以下几点实战建议优先使用 6 位数字代码股票名称可能存在简称歧义使用300059这样的 6 位代码在添加/删除时命中率更高增删前先查询添加已存在的股票或删除不存在的股票都会返回「操作失败」先执行query确认当前自选股列表再操作可避免无效调用也能省下宝贵的每日调用额度注意当日调用上限code113表示当日调用次数已达上限建议在后端接入缓存层如本文 7.1 的 TTL 缓存减少重复查询善用--output-dir与文件产物CSV 适合交给 Excel/表格工具_raw.json适合二次开发解析原始字段避免重复调用接口网络安全域要求运行环境必须能够访问公网mkapi2.dfcfs.com否则会得到connect: Connection refused请先排查网络配置。结语mx-zixuan是一个「小而完整」的 Agent Skill 范例它以东方财富妙想 API 为数据底座用统一的环境变量约定、命令式与自然语言双模入口、标准化的终端/CSV/JSON 三类输出把自选股增删查封装成了可被智能体与后端服务直接复用的能力。理解它的接口契约、输出约定与工程化接入方式你既可以把它当作独立工具直接使用也可以像 StockSage-agent 那样在服务层引入 TTL 缓存、通过 REST 路由对外暴露从而快速为自有 Agent 应用补齐「账户级金融数据操作」这一环。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考