1. 项目概述如果你和我一样是个对A股市场有点想法但又不想整天泡在K线图和各种财经软件里手动折腾的投资者那你肯定会对今天要聊的这个项目感兴趣。A-Stockit这个名字听起来就有点意思对吧它不是一个传统的股票分析软件也不是一个量化交易平台。简单来说它是一个“AI原生的技能包”专门为像Claude Code、OpenClaw、Codex这类AI Agent框架设计的。它的核心目标是把我们平时做A股研究时那些零散、重复、繁琐的步骤——比如导入自选股、拉取行情数据、做技术分析、生成复盘报告——打包成一个个可以被AI直接理解和执行的“技能”。你不再需要记住复杂的命令行参数或者在不同的工具间来回切换只需要用最自然的语言跟你的AI助手对话比如“给我看看贵州茅台的简报”或者“筛选一下我自选股里今天表现最好的三只”剩下的就交给A-Stockit去处理。我第一次接触这个项目时感觉它解决了一个非常实际的痛点。我们很多人在用AI辅助投资时往往停留在“问一句答一句”的层面。比如你问AI“600519今天涨了多少”它能告诉你。但如果你想让它基于你的一篮子自选股自动生成一份包含涨跌幅、技术指标、新闻舆情和初步决策建议的日报传统的方式就非常吃力了。你需要自己写脚本或者把多个工具的输出结果手动拼凑起来。A-Stockit的价值就在于它把这一整套从数据准备到决策支持的完整工作流都封装成了标准化的“技能”让AI Agent能够像一个真正的投资研究助手一样连贯地、有逻辑地为你工作。它特别适合那些希望用AI提升研究效率但又不想深入编程细节的普通投资者和活跃交易者。1.1 核心需求解析为什么我们需要AI原生的投资工作流在深入技术细节之前我们得先想明白一个问题为什么是“AI原生”为什么不是直接用一个Python库这里面的区别恰恰是A-Stockit设计的精髓。传统的量化工具或数据分析库比如Pandas、TA-Lib或者AKShare它们提供的是“功能”。你需要自己写代码去调用这些功能组织数据流处理异常最后生成报告。这个过程对开发者很友好但对大多数投资者来说门槛太高。而A-Stockit提供的是“工作流”和“意图理解”。它定义的不是一个个孤立的函数而是一系列有上下文关联的“技能”。当你对AI说“分析我的自选股”时AI通过A-Stockit能理解到这背后可能隐含着一连串动作首先它需要去_artifacts/sessions/下找到你上次保存的自选股列表然后为列表中的每只股票调用market-data技能获取最新行情接着可能再调用technical-scan技能进行指标分析最后将结果汇总用market-brief技能生成一份人类可读的报告。整个过程中你不需要关心数据从哪里来、怎么处理、存到哪里你只需要表达你的意图。这种“意图驱动”的模式极大地降低了使用门槛。你不需要知道股票代码查询API的URL不需要理解MACD指标的计算公式甚至不需要知道数据文件保存在哪个路径。你只需要用你思考投资时最自然的语言去提问。这对于构建一个可持续、可复现的研究习惯至关重要。很多人的投资分析是随机的、碎片化的今天用Excel记一笔明天在笔记软件里写一段后天又忘了之前是怎么分析的。A-Stockit通过统一的产物管理所有输出都存到_artifacts/目录强制性地为你的每一次分析、每一个决策留下了“痕迹”。你可以随时回溯历史查看过去某一天对某只股票的分析报告或者评估某个筛选策略在历史上的表现如何。这种可追溯性是个人投资者从感性决策走向理性、系统化决策的关键一步。1.2 目标用户画像谁最适合使用A-Stockit根据我的使用经验以下几类朋友会从这个项目中获益最大第一类是信息整合需求强烈的普通投资者。你可能每天会看很多财经新闻、券商研报、股吧讨论但信息过于庞杂难以形成有效决策。A-Stockit的news-intel和market-recap技能可以帮助你快速抓取和整合关键信息market-brief技能能给你一个结构化的当日概览让你在五分钟内对持仓和关注标的有个整体把握。第二类是有一定方法论体系的活跃交易者或独立研究者。你可能有自己的选股逻辑、技术分析体系但每次手动执行这些分析步骤非常耗时。A-Stockit的market-screen和decision-support技能可以将你的筛选条件比如“市盈率低于30且近期放量上涨”固化下来一键运行。strategy-design和backtest-evaluator技能则能帮你快速验证一个交易想法的历史表现虽然不能保证未来盈利但至少能帮你排除掉一些明显无效的策略。第三类是希望为AI Agent增加垂直领域能力的开发者。如果你正在基于Claude Code或类似框架开发一个金融领域的AI助手A-Stockit提供了一个近乎“开箱即用”的能力模块。你不需要从零开始构建数据获取、分析、回测这一整套东西直接集成这个技能包你的Agent就立刻具备了专业的A股研究能力。它的bundle-first设计意味着所有技能的定义、实现和路由都是打包好的集成成本很低。第四类是量化研究的入门者。你对编程和数据分析有一定了解想尝试构建自己的量化策略但又觉得搭建完整的数据管道和回测框架太复杂。A-Stockit的_src目录下共享的Python实现如backtest/引擎是一个很好的学习参考和起点。你可以基于它已有的框架快速试验自己的想法而不用操心数据清洗、复权、滑点这些底层细节。2. 核心架构与设计哲学要真正用好A-Stockit不能只停留在“怎么用”的层面还得理解一点它“为什么这么设计”。这能帮助你在遇到问题时更快地排查甚至根据自己的需求进行定制。它的架构清晰地反映了其“AI原生”和“工作流驱动”的设计思想。2.1 Bundle-First与Definition-First技能即插件A-Stockit最核心的设计理念是“Bundle-First”捆绑包优先和“Definition-First”定义优先。这是什么意思呢我们拆开来看。在传统的软件开发中我们可能会先写一个庞大的Python库里面包含几百个函数然后写一个厚厚的使用手册告诉用户怎么调用。但在AI Agent的世界里Agent理解世界的方式是“技能”Skill。一个技能就是一个独立的、可被调用的能力单元它有自己的名字、描述、输入输出规范。A-Stockit选择先定义“技能”是什么Definition-First然后再去实现它。所以你在项目根目录的skills/astockit/下会看到24个以技能名命名的文件夹比如market-brief/、watchlist-import/。每个文件夹里至少有一个SKILL.md文件这个文件就是用自然语言辅以一些结构化标记向AI描述这个技能是干什么的、怎么用、输入输出是什么。这相当于给AI Agent写了一份“产品说明书”。而“Bundle-First”是指这些技能不是散乱分布的它们被组织成一个完整的“捆绑包”bundle。这个捆绑包有一个统一的入口index.md一个统一的元数据注册中心_registry/和一个共享的实现代码库_src/。当你把这个捆绑包安装到你的AI Agent框架比如Claude Code时框架会一次性加载所有技能的定义AI立刻就知道了“哦我现在拥有了24个关于A股研究的新能力”。这种设计的好处是可发现性和可组合性极强。AI可以自己根据你的问题决定调用哪个或哪几个技能甚至能串联它们形成一个工作流。比如你问“帮我分析一下茅台和宁德时代”AI可能会自动先调用watchlist-import如果还没导入再调用stock-data获取数据最后调用analysis进行比较。2.2 三层架构定义、实现与产物A-Stockit的代码结构清晰地分为了三层这对应了技能从定义到执行再到产出结果的完整生命周期。第一层公开技能定义层Public Skill Surface这就是我们刚才说的skills/astockit/skill-name/目录。这一层是面向AI和用户的接口。SKILL.md文件是核心它用Markdown写成但里面包含了特殊的指令块通常是!-- skill ... --这样的注释用来定义技能的参数、示例和边界。这一层是“声明式”的它告诉世界“我能做什么”但不关心“我具体怎么做”。目前24个公开技能中有18个已经有了对应的run.py即“code-backed”还有6个暂时只有工作流定义“workflow-only”等待社区或开发者来实现。注意理解“workflow-only”技能很重要。这并不意味着这个技能不能用。相反AI仍然可以理解这个技能的定义并尝试通过自身的推理能力或调用其他已有技能来“模拟”完成这个工作流。这为技能的渐进式完善提供了可能。社区可以先贡献一个清晰的工作流定义然后再慢慢补全代码实现。第二层共享实现层Shared Implementation Surface这就是_src/目录。这里存放了所有技能背后共用的Python代码。比如无论是market-brief还是technical-scan它们都需要获取股票行情数据。这个功能就不会在每个技能的run.py里重复写一遍而是会调用_src/market/data_provider.py里的某个函数。这种设计避免了代码重复也使得维护和更新变得更容易。如果你想修复一个数据获取的bug或者增加一个新的数据源只需要修改_src/下的对应文件所有依赖它的技能都会自动受益。第三层持久化产物层Durable Artifact Surface这就是_artifacts/目录。这是A-Stockit非常实用且关键的一个设计。所有技能运行的结果——你导入的自选股列表、生成的行情简报、回测报告、决策面板截图——都会按照类别自动保存到这里。目录结构组织得很有条理sessions/: 保存会话状态比如当前的自选股。reports/: 保存生成的各类报告Markdown、HTML或PDF格式。backtests/: 保存回测的配置和结果。history/: 保存历史操作记录。paper/: 模拟交易Paper Trading的记录。这样做的好处是所有分析过程都可追溯、可复盘。你不仅可以查看最新的结果还可以对比历史上任意一次分析。对于投资研究来说这种“历史记忆”能力是无价的。你可以看到三个月前对某只股票的判断依据是什么和今天的市场表现对比如何从而不断修正自己的分析框架。2.3 运行时接口与技能路由AI Agent框架如何知道该调用A-Stockit里的哪个技能呢这依赖于_registry/目录下的元数据文件特别是skills.json。这个文件相当于整个技能包的“总目录”列出了所有可用的技能及其元信息如名称、描述、输入参数模式等。当AI接收到用户的指令时它会去匹配这个目录找到最合适的技能来调用。而具体的调用执行则依赖于runtime.json中定义的运行时接口。A-Stockit设计了一套轻量级的“运行时”负责在技能被调用时设置好正确的Python环境加载必要的依赖并将用户的自然语言指令解析成技能run.py可以理解的命令行参数或函数参数。这使得技能的开发者可以专注于业务逻辑比如如何计算RSI指标而不需要关心如何与不同的AI框架进行适配。3. 从零开始安装、配置与初体验理论说了不少现在我们动手把它真正用起来。我会以最流行的Claude Code为例带你走一遍完整的安装和初次使用流程。其他框架如OpenClaw、Codex的原理类似只是安装路径稍有不同。3.1 环境准备与项目克隆首先你需要一个已经安装并能正常运行的AI Agent框架。以Claude Code为例确保你的开发环境比如VS Code with Claude Code扩展已经就绪。然后我们获取A-Stockit的代码。# 克隆项目仓库到本地建议放在一个你容易找到的目录比如你的工作区或文档目录下。 git clone https://github.com/NatsuFox/A-Stockit.git cd A-Stockit克隆完成后你会看到项目的完整目录结构。接下来就是把它“安装”到你的AI框架里。这里的“安装”本质上是一种符号链接目的是让AI框架能发现这个技能包。3.2 技能包安装与框架集成对于Claude Code安装分为“项目级”和“用户级”两种。我推荐使用用户级安装这样在任何项目里你的AI助手都能使用A-Stockit技能。# 为用户级的Claude Code创建技能目录如果不存在的话 mkdir -p ~/.claude/skills # 创建指向A-Stockit技能包的符号链接 ln -s $(pwd)/skills/astockit ~/.claude/skills/astockit这个命令做了什么呢ln -s创建了一个“快捷方式”符号链接把本地的A-Stockit/skills/astockit目录链接到了Claude Code默认查找技能的目录~/.claude/skills/下。这样Claude Code在启动时就能扫描到这个名为astockit的技能包并加载其中定义的所有技能。实操心得路径与权限问题在执行ln -s时确保$(pwd)能正确展开为你克隆的A-Stockit项目绝对路径。在Windows的Git Bash或WSL中这个命令同样有效。如果遇到“Permission denied”错误可能是目标目录~/.claude/的权限问题可以尝试用sudoLinux/macOS或以管理员身份运行终端。更稳妥的做法是先确认~/.claude/目录是否存在如果不存在手动创建并赋予当前用户读写权限。3.3 验证安装与技能发现安装完成后如何验证是否成功呢最直接的方式就是问你的AI助手。打开你的VS Code唤出Claude Code的聊天界面通常是侧边栏或底部面板然后输入“列出 astockit 技能” 或者 “List astockit skills”如果安装成功你应该会看到AI回复一个列表里面包含了watchlist-import,market-brief,technical-scan等技能的名称和简要描述。这说明AI已经成功加载了A-Stockit技能包并知道了它现在能做什么。如果AI回复说“找不到相关技能”或没有反应请按以下步骤排查检查符号链接在终端运行ls -la ~/.claude/skills/确认astockit是否存在并且是一个指向正确位置的符号链接箭头指向你的项目路径。重启AI框架有时需要完全重启VS Code或重新加载Claude Code扩展才能使新技能生效。检查框架配置确认你的Claude Code配置中技能加载路径是否包含~/.claude/skills/。3.4 第一个工作流导入自选股与获取简报验证通过后我们就可以开始真正的使用了。让我们从一个最经典的工作流开始导入几只股票然后获取其中一只的详细简报。步骤一导入自选股在AI聊天框输入“导入自选股600519,300750,000858”这条指令会触发watchlist-import技能。AI会做以下几件事解析识别出“600519”贵州茅台、“300750”宁德时代、“000858”五粮液是三只A股股票代码。验证调用内部逻辑可能通过AKShare验证这些代码是否有效、是否存在。保存将验证通过的自选股列表以JSON格式保存到_artifacts/sessions/watchlist.json文件中。反馈AI会回复你导入结果例如“已成功导入3只股票至自选股列表”。此时你可以去项目目录下的_artifacts/sessions/里查看会发现多了一个watchlist.json文件里面记录了你刚才导入的股票代码和相关信息如名称、市场。这个文件就是你后续所有分析的“数据源”。其他技能如market-screen、analysis都会默认读取这个列表。步骤二获取单只股票市场简报接着输入“给我 600519 的市场简报”这会触发market-brief技能。AI会获取数据从配置的数据源如AKShare获取600519的最新行情开盘价、收盘价、最高价、最低价、成交量等、分时数据、以及可能的基本面快照。分析计算基于获取的数据计算一系列常用技术指标如MA、MACD、RSI、布林带等。生成报告将原始数据和分析结果组织成一份结构清晰、易于阅读的Markdown格式报告。保存与展示报告会被保存到_artifacts/reports/目录下并以一个带时间戳的文件名存储例如market_brief_600519_20231027.md。同时AI会在聊天界面将报告的核心内容摘要呈现给你。你得到的报告可能会包含以下章节概览股票名称、代码、当前价格、涨跌幅、市值等。行情数据当日关键价格和成交量。技术指标各种指标的值及其所处的信号区间如超买/超卖。简要分析AI根据数据生成的一段文字解读。建议关注基于当前技术面提示可关注的关键价位或信号。步骤三筛选自选股有了自选股列表我们经常想从中找出“最值得关注”的。试试这个命令“筛选我的自选股找出最值得关注的 3 只”这会触发market-screen技能。AI会读取列表从watchlist.json加载你所有的自选股。批量获取数据并行或依次获取列表中所有股票的实时行情数据。应用筛选逻辑A-Stockit内置了一套默认的筛选逻辑可能是综合考量涨跌幅、成交量变化、技术指标强度等。它会根据这套逻辑对所有股票进行打分或排序。输出结果返回排名前3的股票列表并附上简要的筛选理由比如“宁德时代(300750)放量上涨突破短期均线MACD金叉”。至此你已经完成了一个完整的“数据准备 - 单一分析 - 批量筛选”的微型工作流。整个过程完全通过自然语言完成你不需要写一行代码也不需要操作任何图形界面。这就是AI原生工作流的魅力。4. 核心技能深度解析与实战技巧A-Stockit提供了24个技能我们不可能一一细说但我会挑几个最核心、最能体现其设计思想的技能深入讲讲它们的工作原理、使用场景以及我踩过的一些坑。4.1watchlist-import不仅仅是导入这个技能看似简单就是导入一串股票代码但它的设计考虑了很多实际场景。核心功能批量导入支持逗号、空格分隔的代码列表。智能验证不仅检查代码格式沪市6开头深市0或3开头还会尝试从数据源获取股票名称以此验证代码有效性。无效的代码会被过滤掉并给出提示。持久化存储保存为JSON文件结构清晰包含代码、名称、导入时间等信息。会话管理理论上支持多个会话session但目前默认使用一个全局自选股列表。未来可以扩展为不同分析场景使用不同的股票池。实战技巧与避坑指南代码格式A股代码通常不需要后缀。直接输入“600519”即可不需要“600519.SH”。技能内部会进行处理。如果你有带后缀的代码它大概率也能识别但为了保险建议使用纯数字代码。导入覆盖与追加根据我的测试当前版本的watchlist-import默认是覆盖操作。即新的导入会完全替换掉之前watchlist.json里的内容。如果你是想追加股票需要一次性列出所有你想保留的代码。例如原有列表有A、B、C你想加入D应该输入“导入自选股A,B,C,D”。处理无效代码如果你输入了无效代码如“123456”技能会跳过它并在回复中告知你哪些代码无效。这比整个操作失败要好但你需要仔细阅读AI的回复确认最终导入的列表是否符合预期。文件位置导入后务必习惯去_artifacts/sessions/目录下看一眼watchlist.json。这是你的“权威数据源”。如果AI的回复和文件内容对不上以文件为准。你也可以手动编辑这个JSON文件比如删除某只股票后续技能会读取你手动修改后的版本。4.2market-brief你的自动化日报生成器这是我个人使用频率最高的技能。它本质上是一个数据聚合与报告生成器。内部工作流程拆解参数解析技能首先解析你输入的股票代码。数据获取调用_src/market/下的数据获取模块。这里有一个关键点数据源配置。A-Stockit默认使用AKShare但它在设计上支持多数据源。在_src/core/config.py或相关配置文件中可以指定数据源优先级如source: auto表示自动选择或指定为akshare、tushare等。指标计算获取到行情数据通常是DataFrame格式后会传入_src/research/technical.py等模块进行计算。计算哪些指标是预定义的但你可以通过修改源码来增加或调整。报告模板渲染计算好的数据会被填充到一个Markdown报告模板中。这个模板定义了报告的结构和样式。生成的报告不仅包含数字还包含一些简单的文本解读例如“股价位于20日均线之上短期趋势偏多”。文件保存报告以股票代码_日期.md的格式保存。这种命名方式便于按股票和日期进行历史检索。自定义与扩展修改指标如果你觉得默认的MACD、RSI不够用想加入ATR平均真实波幅或OBV能量潮你需要修改_src/research/technical.py文件添加相应的计算函数并在报告生成逻辑中调用它。调整报告模板报告的外观和章节顺序是由模板控制的。你可以找到报告生成的源码可能在_src/research/report_generator.py修改其中组装Markdown字符串的部分。增加数据维度如果你想在简报中加入财务数据摘要如市盈率、市净率需要扩展数据获取模块从基本面数据源抓取信息并整合到报告中。重要提示修改源码属于高级操作。建议在修改前先通读相关代码理解数据流。修改后最好在本地直接运行对应的run.py脚本进行测试确保无误后再通过AI调用。例如测试market-brief可以运行python3 skills/astockit/market-brief/run.py 600519 --source auto。4.3market-screen多维度的股票筛选器筛选是量化研究的核心。market-screen技能提供了基础的筛选能力但其真正的威力在于它的可扩展性。默认筛选逻辑浅析 根据代码和文档推断其默认筛选可能是一个简单的多因子打分模型。例如动量因子近期涨幅如5日涨跌幅给予正分。成交量因子近期成交量相对于均值的放量程度给予正分。技术指标因子RSI是否处于强势区间如30-70之间MACD是否金叉等。波动性因子股价是否突破布林带上轨或下轨表示极端行情。每个因子赋予一定权重最后对所有股票进行加权求和排序。这只是一个猜测实际的筛选逻辑需要查看_src/research/screener.py源码。如何构建你自己的筛选器这才是更有价值的部分。A-Stockit的架构允许你创建自定义的筛选逻辑。创建新技能在skills/astockit/下复制一个现有技能目录如market-screen重命名为my-custom-screen。修改SKILL.md更新技能描述明确说明你的筛选规则例如“筛选出自选股中市盈率低于行业平均且ROE大于15%的股票”。实现run.py这是核心。你需要编写Python代码从watchlist.json读取股票列表。循环获取每只股票的基本面数据这可能需要扩展_src/market/fundamental.py。应用你的自定义逻辑进行计算和过滤。将结果格式化为AI可回复的文本并可选地保存到_artifacts/reports/。注册技能在_registry/skills.json中添加你的新技能条目。测试通过AI调用你的新技能“使用my-custom-screen筛选股票”。通过这种方式你可以将任何你信任的选股模型如格雷厄姆的净流动资产折价模型、彼得林奇的PEG指标等固化成AI技能实现一键筛选。4.4backtest-evaluator策略想法的试金石回测是量化交易中避免“拍脑袋”决策的关键。A-Stockit内置的回测框架虽然不如专业的Backtrader、Zipline复杂但对于快速验证一个策略想法的逻辑正确性和历史大致表现已经足够。回测工作流策略设计首先你需要有一个明确的策略逻辑。A-Stockit的strategy-design技能可以帮你用自然语言描述一个策略但它目前可能更多是生成策略框架代码或提示。更实际的做法是你直接想好策略规则例如“当5日均线上穿20日均线金叉时买入当5日均线下穿20日均线死叉时卖出每次全仓操作。”数据准备回测需要历史数据。A-Stockit会通过AKShare等数据源获取指定股票和日期范围的历史日线数据。信号生成根据你的策略规则在历史数据的每一个时间点上计算是否产生买入或卖出信号。这部分逻辑在_src/strategies/下的预设策略文件中或者你需要自己实现。模拟交易_src/backtest/engine.py中的回测引擎会遍历时间序列在产生买入信号时以当时的价格“买入”在卖出信号时“卖出”并考虑是否允许做空、交易费用佣金、印花税等参数。它还会记录每一次交易和最终的资产曲线。绩效评估回测结束后backtest-evaluator技能会计算一系列评估指标例如总收益率策略的最终收益。年化收益率/波动率衡量收益和风险。夏普比率衡量风险调整后的收益。最大回撤历史上最大的亏损幅度这是衡量策略风险承受能力的关键指标。胜率盈利交易次数占总交易次数的比例。报告生成将所有结果包括资产曲线图如果配置了绘图库、交易明细列表、绩效指标表格整合成一份详细的回测报告保存到_artifacts/backtests/目录。使用回测的注意事项历史不代表未来这是回测最核心的警示。过去有效的策略未来可能失效。回测主要用来验证逻辑和排除明显无效的策略。避免过度拟合不要在历史数据上反复调整参数直到曲线完美。这样得到的策略在未来大概率会失败。A-Stockit目前的回测框架比较简单但你在设计策略时也应有此意识。关注交易成本默认的回测可能使用了简单的成本模型。在A股印花税和佣金对高频策略影响很大。你需要确认回测引擎中设置的费率是否符合实际。理解假设回测通常假设可以以收盘价成交这在实际中很难做到。对于波动大的股票滑点实际成交价与预期价的偏差影响显著。A-Stockit当前版本可能未考虑滑点这需要你心中有数。尽管有这些限制对于投资者来说能快速、低成本地对一个想法进行历史模拟已经是一个巨大的进步。它至少能告诉你这个想法在历史上是赚是亏波动有多大最大可能亏多少。5. 高级用法与定制化开发当你熟悉了基本技能后可能会不满足于默认的功能。A-Stockit作为一个开源项目最大的优势就是可以被深度定制。这里分享几个进阶的使用和开发思路。5.1 集成外部数据源A-Stockit默认使用AKShare这是一个非常优秀的开源A股数据库。但你可能有自己的数据源比如Wind、Tushare Pro的API或者自己爬取的特色数据如社交媒体情绪、产业链数据。集成步骤创建数据提供者模块在_src/market/目录下新建一个文件例如my_data_provider.py。这个模块需要实现一个或多个标准的函数接口比如get_stock_quote(code, start_date, end_date)用于获取行情get_stock_basic(code)用于获取股票基本信息。修改配置在项目的配置文件可能是_src/core/config.py或通过环境变量中增加一个数据源选项比如my_custom_source。修改数据获取逻辑找到_src/market/data_provider.py或类似的文件这里有一个类似工厂模式或路由器的函数根据配置选择使用哪个数据源。你需要在这里添加对你新建的my_data_provider的调用支持。技能适配确保所有依赖市场数据的技能如market-brief,stock-data在调用数据获取函数时能正确传递source参数或者使用全局配置的默认数据源。实操心得在集成新数据源时最关键的是数据格式的统一。AKShare返回的数据通常是Pandas DataFrame且有固定的列名如open,high,low,close,volume。你的新数据提供者返回的数据结构必须与之兼容否则下游的指标计算和报告生成都会出错。建议先写一个小脚本模拟技能调用的数据流确保从新数据源获取的数据能被现有分析模块正确处理。5.2 构建自动化工作流A-Stockit的单个技能已经很有用但真正的威力在于将它们组合成自动化的工作流。虽然项目提供了6个“workflow-only”的技能定义作为指导但你完全可以利用AI Agent的上下文管理能力自己构建更复杂的工作流。示例盘后自动复盘流水线你可以给AI助手一个复杂的指令让它依次执行“请执行以下任务 1. 更新我的自选股列表从文件xxx.csv读取。 2. 为自选股中所有股票生成今日市场简报。 3. 基于简报筛选出出现‘放量上涨’且‘RSI低于70’的股票。 4. 为筛选出的股票生成一份详细的对比分析报告。 5. 将这份报告通过飞书机器人发送到我的群组。”AI在接收到这个指令后会将其分解为多个子任务并依次调用对应的A-Stockit技能watchlist-import(可能需要你先将CSV处理成代码列表)循环调用market-briefmarket-screen(需要你预先定义好这个筛选逻辑对应的技能或AI在上下文中进行临时计算)analysis(对比分析)feishu-notify(飞书通知)关键在于你需要确保每个技能的输出格式能被下一个技能或AI的上下文理解所接受。A-Stockit将大部分输出保存为结构化的文件JSON、Markdown这为技能间的数据传递提供了便利。AI可以读取上一个技能生成的报告文件从中提取关键信息作为下一个技能的输入或判断依据。5.3 贡献代码如何添加一个新技能如果你发现了一个缺失的功能或者想优化现有技能向开源项目贡献代码是最好的方式。以下是添加一个全新技能的标准化流程这也是对A-Stockit架构理解的一次实践。步骤一规划与设计假设我们要添加一个dividend-analysis股息分析技能用于分析股票的历史分红和股息率。明确功能输入股票代码输出其近几年的分红历史、股息率、分红率并与行业平均进行对比。确定输入输出输入股票代码必选、分析年份数可选默认5年。输出一份Markdown报告包含表格和简要分析同时将原始数据保存为JSON文件。步骤二创建技能目录和定义文件cd skills/astockit mkdir dividend-analysis cd dividend-analysis创建SKILL.md文件# 股息分析 (dividend-analysis) 分析指定A股股票的历史分红数据计算股息率等指标。 ## 技能描述 获取股票的历史分红数据计算年均股息率、分红融资比等并生成分析报告。 ## 输入 - symbols (必需): 一个或多个A股股票代码用逗号分隔。例如600519 或 600519,000858。 - years (可选): 回溯分析的年份数默认5年。 ## 输出 - 在聊天界面返回核心分析结论。 - 在 _artifacts/reports/ 目录下生成详细的Markdown分析报告。 - 在 _artifacts/exports/ 目录下保存原始分红数据的JSON文件。 ## 示例 用户可以说 - “分析一下贵州茅台的股息情况” - “对比一下600519和000858过去5年的分红” - “dividend-analysis for 600519 with years8” ## 实现状态 [ ] 工作流定义 [x] 代码实现 (见 run.py) ## 作者 [你的名字]步骤三实现技能执行器 (run.py)#!/usr/bin/env python3 股息分析技能执行器。 import sys import json from pathlib import Path from datetime import datetime # 假设我们从共享模块导入一个数据获取函数 sys.path.append(str(Path(__file__).parent.parent.parent / _src)) from market.data_provider import get_dividend_data # 这个函数需要你实现或已存在 def main(): # 1. 解析命令行参数这里简化实际应从AI框架传入的参数解析 # 例如python run.py 600519 --years 5 if len(sys.argv) 2: print(错误请提供股票代码。) sys.exit(1) symbol sys.argv[1] years 5 if --years in sys.argv: idx sys.argv.index(--years) if idx 1 len(sys.argv): years int(sys.argv[idx 1]) # 2. 获取数据 print(f正在获取 {symbol} 近{years}年的分红数据...) dividend_df get_dividend_data(symbol, yearsyears) if dividend_df.empty: print(f未找到 {symbol} 的分红数据。) # 仍然生成一个空的报告文件保持流程一致性 report_content f# {symbol} 股息分析报告\n\n未找到相关分红数据。 else: # 3. 计算指标示例 total_dividend dividend_df[dividend_cash].sum() avg_dividend_yield total_dividend / years / (dividend_df[price_at_exdiv].mean() if price_at_exdiv in dividend_df.columns else 1) # 4. 生成报告内容 report_content f# {symbol} 股息分析报告近{years}年 ## 数据概览 - **累计现金分红**: {total_dividend:.2f} 元/股 - **年均股息率估算**: {avg_dividend_yield:.2%} ## 详细分红记录 {dividend_df.to_markdown()} ## 简要分析 此处可根据指标添加自动生成的文字分析 # 5. 保存原始数据 export_dir Path(_artifacts/exports/dividend/) export_dir.mkdir(parentsTrue, exist_okTrue) export_file export_dir / fdividend_{symbol}_{datetime.now().strftime(%Y%m%d)}.json dividend_df.to_json(export_file, orientrecords, force_asciiFalse) # 6. 保存报告 report_dir Path(_artifacts/reports/) report_dir.mkdir(parentsTrue, exist_okTrue) report_file report_dir / fdividend_analysis_{symbol}_{datetime.now().strftime(%Y%m%d_%H%M%S)}.md report_file.write_text(report_content, encodingutf-8) # 7. 输出给AI最终会呈现给用户 print(f股息分析完成报告已保存至{report_file}) # 这里可以输出一个摘要AI会将其整合到回复中 summary f已完成对 {symbol} 的股息分析。近{years}年累计分红 {total_dividend if total_dividend in locals() else N/A} 元/股。详细报告已生成。 print(summary) if __name__ __main__: main()步骤四在注册表中注册技能编辑_registry/skills.json文件在数组中添加一个新条目{ name: dividend-analysis, description: 分析股票的历史分红数据和股息率。, path: dividend-analysis, type: code-backed, tags: [analysis, fundamental, dividend], input_patterns: [ 分析{symbols}的股息, 查看{symbols}的分红历史, dividend-analysis for {symbols} ] }步骤五测试与提交在本地直接运行你的技能进行测试python3 skills/astockit/dividend-analysis/run.py 600519。通过AI框架调用测试“分析600519的股息”。确保技能能正确执行输出符合预期并且文件保存到了正确的位置。运行项目现有的测试如果有确保没有破坏原有功能。按照项目的贡献指南提交Pull Request。通过这个过程你不仅为项目贡献了新功能也彻底理解了A-Stockit从技能定义、代码实现到注册集成的完整生命周期。6. 常见问题、故障排查与优化建议在实际使用和开发过程中你肯定会遇到各种各样的问题。这里我总结了一些常见的情况和解决思路希望能帮你少走弯路。6.1 数据获取失败或缓慢这是最常见的问题因为A-Stockit依赖外部数据源主要是AKShare。症状AI执行技能时卡住很久最后报错“获取数据失败”或超时。可能原因与解决方案网络问题AKShare的数据来自网络API或爬虫。检查你的网络连接特别是能否访问相关的财经数据网站。可以尝试在浏览器中手动访问一个数据源网站如东方财富看是否正常。数据源API变更开源数据源的API接口有时会发生变化。如果之前正常突然失败可能是AKShare库更新后接口变了或者目标网站改版了。解决升级AKShare到最新版本pip install -U akshare。如果问题依旧查看A-Stockit的GitHub Issues页面看是否有其他人遇到相同问题。可能需要等待AKShare修复或者临时修改_src/market/下的数据获取代码使用备用数据源。请求频率过高被限制如果你短时间内频繁请求大量数据可能会触发数据源网站的反爬机制。解决在数据获取代码中增加延时time.sleep。A-Stockit可能已经内置了简单的延时逻辑但对于批量操作如筛选整个自选股你可能需要手动调整_src/market/data_provider.py中的请求间隔。股票代码无效或停牌输入了错误的代码或者股票当天停牌数据源可能返回空值或错误。解决使用watchlist-import技能时仔细核对AI的反馈确认所有代码都有效。对于停牌股票技能应能优雅处理返回“暂无数据”而非崩溃。6.2 AI无法识别或错误调用技能症状输入指令后AI回复“我不明白”或调用了错误的技能。排查步骤检查技能安装首先确认技能包已正确安装并链接。在AI聊天框输入“列出所有技能”或“List all skills”查看astockit开头的技能是否在列表中。检查技能定义如果技能在列表中但无法触发可能是SKILL.md中的input_patterns输入模式定义不够全面未能覆盖你的说话方式。你可以尝试使用技能定义中给出的精确示例句式。例如对于market-brief尝试使用“给我600519的市场简报”这个标准句式。查看AI框架日志有些AI框架如Claude Code会有更详细的调试日志记录技能匹配的过程。查看日志可以帮助你理解AI是如何解析你的指令并选择技能的。指令清晰度尽量使用简洁、明确的指令。避免过于复杂或模糊的句子。例如“帮我看看茅台怎么样”就不如“给我600519的市场简报”明确。6.3 生成的报告内容不准确或指标计算有误症状报告中的涨跌幅、技术指标值与你在其他软件上看到的不一致。可能原因数据源差异不同的数据源如AKShare vs 券商软件在数据清洗、复权处理上可能存在差异。A股的前复权、后复权算法各家可能不同。验证对比同一只股票、同一天的基础数据开盘、收盘、最高、最低、成交量是否一致。如果不一致问题出在数据源头。解决考虑在配置中切换数据源如果支持或者接受这种差异在分析时以单一数据源为准进行纵向比较看趋势而非横向绝对值的比较。指标计算参数差异技术指标如MA、MACD、RSI都有计算周期参数如RSI常用14日。A-Stockit使用的默认参数可能与你习惯的软件不同。解决查看_src/research/technical.py文件找到对应指标的计算函数确认其参数。你可以修改这些参数来匹配你的习惯。Bug代码计算逻辑可能存在错误。解决对于简单的指标可以手动用一小段历史数据验证计算是否正确。如果发现bug欢迎在项目GitHub仓库提交Issue或者直接修复并提交PR。6.4 性能优化建议当自选股数量很多比如超过50只时批量运行market-screen或为每只股票生成market-brief可能会很慢。优化思路异步并发请求目前的数据获取可能是串行的。可以改造_src/market/data_provider.py中的批量获取函数使用asyncio或concurrent.futures进行并发请求大幅缩短IO等待时间。缓存机制引入一个简单的缓存层。对于同一只股票在短时间内如5分钟的重复数据请求直接返回缓存结果而不是重新访问网络。可以将缓存保存在内存如字典或本地文件如_artifacts/cache/中。增量更新对于market-brief报告如果只是获取最新一天的行情可以只请求最新数据而不是每次都获取很长的历史序列来计算指标当然某些指标需要历史数据。按需计算在market-screen中如果筛选逻辑不需要所有技术指标可以只获取和计算必要的字段避免不必要的计算开销。6.5 安全与隐私提醒数据本地存储A-Stockit的所有产物都保存在本地_artifacts/目录这是一个优点。但请注意备份这个目录以防误删。同时如果你的研究涉及敏感的自选股列表或分析结论请妥善保管整个项目目录。依赖库安全定期更新项目依赖requirements.txt中的库以获取安全补丁。可以使用pip list --outdated检查并谨慎升级。网络请求A-Stockit会代表你向外部数据源发起网络请求。请确保你信任这些数据源如AKShare及其背后的网站。在不可信的网络环境中使用需谨慎。A-Stockit作为一个早期项目其强大之处不在于它现在提供了多少坚如磐石的功能而在于它开创性地将AI Agent与专业的投资研究工作流结合了起来并且提供了一个高度可扩展的架构。它就像给你提供了一套精良的“乐高积木”技能和“搭建手册”工作流定义让你可以和你的AI助手一起自由地构建属于你自己的智能投资研究平台。从简单的数据查询到复杂的策略回测从被动的信息接收者到主动的研究流程设计者这或许才是“AI赋能”在个人投资领域最实在的体现。