1. 项目概述与核心价值最近在GitHub上看到一个挺有意思的项目叫“cursor-hk-stock-analysis”。光看名字你可能会觉得这又是一个普通的股票分析工具但仔细研究后我发现它的核心思路非常巧妙它试图解决一个很多量化交易者和数据分析师都头疼的问题如何高效地将自然语言指令转化为可执行的、针对港股市场的分析代码。简单来说就是你想分析“腾讯控股最近一个月的股价波动与成交量的关系”你只需要用大白话说出来这个工具就能帮你生成相应的Python代码并直接运行出图表和结果。这个项目的价值在于它极大地降低了港股数据分析的门槛。港股市场有其特殊性比如交易规则、数据源如港股通、本地券商接口、计价货币港币以及特有的股票代码后缀.HK等。对于非专业程序员或者想快速验证想法的分析师来说手动编写爬虫、处理数据、绘制图表这一整套流程耗时耗力。而这个项目通过集成强大的代码生成模型从项目名“cursor”推测很可能与Cursor编辑器或其背后的AI模型有关将自然语言需求与港股特定的数据获取、清洗、分析逻辑桥接起来实现“所想即所得”的分析体验。它适合几类人一是对港股感兴趣的个体投资者想自己做些基础分析却不懂编程二是金融专业的学生或研究员需要快速进行数据回测和可视化三是经验丰富的量化开发者可以将其作为快速原型工具验证策略思路然后再进行深度开发。接下来我就结合自己的经验深入拆解这个项目的实现思路、关键技术点以及如何在实际中应用和避坑。2. 项目整体设计与思路拆解2.1 核心架构猜想AI智能体与领域知识库的结合从项目名称“cursor-hk-stock-analysis”可以推断其核心很可能是一个构建在Cursor编辑器环境或类似AI编程助手之上的、专门针对港股分析的智能体Agent。它的设计思路绝非简单的脚本拼接而是一个系统工程。我推测其架构至少包含以下三层自然语言理解与任务规划层这是大脑。当用户输入“对比美团和京东健康的市盈率走势”时AI模型如GPT-4、Claude或专门微调的模型需要理解这句话背后的金融语义。它要识别出实体“美团”、“京东健康”、指标“市盈率”、操作“对比”、“走势”和时间范围隐含近期。然后它将这个模糊的需求分解成一系列可执行的任务例如获取美团-W03690.HK和京东健康06618.HK的历史日线数据计算每日的市盈率这可能需要同步获取财报中的每股收益EPS或使用TTM数据将两个序列在同一图表中绘制并进行对比分析。港股领域知识注入层这是项目的灵魂也是区别于通用代码生成器的关键。港股有很多特殊规则必须被编码到系统中代码转换用户可能说“腾讯”系统需要知道对应的港股代码是“00700.HK”。这需要一个本地映射表或调用外部API如新浪财经、富途的代码查询接口。数据源适配免费数据源如yfinance(需要代码为0700.HK)、akshare付费数据源如Wind、Tushare Pro。系统需要知道对于港股应该调用哪个库的哪个函数参数如何传递。金融逻辑封装计算市盈率、市净率、收益率、波动率等指标不是简单加减乘除。系统需要预置或能生成正确的金融公式代码片段。例如港股财报频率、除权除息处理方式都与A股不同。可视化规范生成符合金融分析习惯的图表如K线图叠加成交量、双Y轴对比图、相关性热力图等。代码生成与安全执行层这是双手。根据规划好的任务和调用的领域知识生成具体的Python代码。这里必须考虑安全性防止生成恶意代码和环境隔离。项目很可能会在一个受控的Docker容器或沙箱环境中执行生成的代码并捕获输出图表、数据表格、文本结论返回给用户。注意这种设计模式本质上是在创建一个“领域特定语言DSL”的编译器只不过这个编译器的前端是自然语言后端是Python。它的难点不在于生成代码本身而在于确保生成的代码在港股这个特定上下文中是准确、安全、可执行的。2.2 技术栈选型背后的逻辑虽然项目没有明说但我们可以合理推测其技术选型核心AI模型Cursor编辑器深度集成了AI功能其背后很可能是经过代码专门优化的GPT模型。选择它而不是直接调用OpenAI API可能是因为Cursor提供了更稳定的代码生成上下文、更好的项目感知能力以及与开发环境的无缝集成。另一种可能是项目使用了LangChain或Semantic Kernel这类框架来构建AI智能体链Cursor只是前端界面。数据获取库yfinance和akshare会是首选。yfinance对港股支持较好代码需加.HK后缀但数据可能略有延迟。akshare作为国内库对港股数据源整合更丰富包括实时行情、资金流向等。对于更专业或实时的需求可能会集成tushare的Pro版或baostock的接口。数据分析与可视化pandas和numpy是数据处理的事实标准。可视化方面matplotlib和seaborn足以应对大多数分析图表。对于交互式图表可能会用到plotly。环境与部署为了安全执行用户生成的代码项目很可能采用Docker进行容器化。每个分析任务在一个全新的、资源受限的容器中运行执行完毕后立即销毁防止代码互相污染或耗尽宿主机资源。Web界面则可能用FastAPI或Streamlit快速搭建。选择这些技术栈核心考量是成熟度、社区支持和对中文/金融场景的友好度。akshare和tushare由国内团队维护文档和社区支持更贴合国内开发者习惯数据也更符合港股分析的实际需求。3. 核心模块解析与实操要点3.1 自然语言到分析指令的解析这是最核心也是最难的部分。我们来看一个实例。用户输入“帮我画一下阿里巴巴最近半年的日K线图并且把20日和60日移动平均线加上。”系统需要完成以下解析实体识别“阿里巴巴” - 映射到港股股票代码09988.HK这里假设是港股上市的阿里巴巴。时间解析“最近半年” - 计算出具体的开始日期和结束日期例如end_date datetime.today(),start_date end_date - timedelta(days180)。这里要注意交易日和自然日的区别更专业的处理是获取交易日历。指标解析“日K线图” - 需要获取开盘价、最高价、最低价、收盘价OHLC和成交量数据。“20日和60日移动平均线” - 明确是基于收盘价计算的简单移动平均线SMA。操作指令“画一下...并且把...加上” - 这是一个复合操作先获取数据再计算指标最后绘制包含K线和两条均线的复合图表。在实现上这通常通过提示词工程Prompt Engineering来完成。系统会有一个精心设计的提示词模板将用户查询、港股知识代码映射、可用指标、函数库说明和输出格式要求组合在一起发送给大模型。一个简化的提示词示例可能如下你是一个专业的港股数据分析助手。请将用户的自然语言请求转化为可执行的Python代码片段。 已知信息 - 港股代码映射{阿里巴巴: 09988.HK, 腾讯控股: 00700.HK, 美团: 03690.HK} - 可用库yfinance (别名为yf), pandas as pd, matplotlib.pyplot as plt - 时间处理用户说的“最近N天/月/年”需转换为具体的datetime对象。 用户请求“帮我画一下阿里巴巴最近半年的日K线图并且把20日和60日移动平均线加上。” 请输出 **只包含Python代码** 的代码块代码必须能独立运行并生成图表。不要任何解释。然后期望模型返回类似下面的代码import yfinance as yf import pandas as pd import matplotlib.pyplot as plt from datetime import datetime, timedelta # 1. 解析时间 end_date datetime.now() start_date end_date - timedelta(days180) # 2. 获取数据 ticker yf.Ticker(09988.HK) df ticker.history(startstart_date, endend_date) # 3. 计算指标 df[MA20] df[Close].rolling(window20).mean() df[MA60] df[Close].rolling(window60).mean() # 4. 绘图 fig, (ax1, ax2) plt.subplots(2, 1, figsize(14, 10), gridspec_kw{height_ratios: [3, 1]}) # K线图 (使用蜡烛图简化表示) ax1.plot(df.index, df[Close], labelClose Price, colorblack, linewidth0.5) ax1.fill_between(df.index, df[Low], df[High], alpha0.3, colorgray, labelHigh-Low Range) ax1.plot(df.index, df[MA20], labelMA20, colorblue, linewidth1.5) ax1.plot(df.index, df[MA60], labelMA60, colorred, linewidth1.5) ax1.set_title(Alibaba (09988.HK) - Daily Chart with MAs) ax1.legend() ax1.grid(True) # 成交量 ax2.bar(df.index, df[Volume], color[green if close open else red for close, open in zip(df[Close], df[Open])]) ax2.set_title(Volume) ax2.grid(True) plt.tight_layout() plt.show()实操心得提示词的质量直接决定代码生成的准确性。你需要反复调试提示词加入足够的“约束”和“示例”比如强制要求它使用特定的数据获取函数、处理港股代码后缀、处理可能的空数据等。同时要对模型的输出做后处理校验比如检查生成的代码中是否包含了不安全的系统调用如os.system,subprocess是否尝试访问本地敏感文件等。3.2 港股数据获取的陷阱与应对数据是分析的基石。港股数据获取有几个大坑这个项目必须妥善处理代码格式不统一用户输入“腾讯”数据接口可能需要0700.HKyfinance、00700.HK某些API或HKEX:00700。项目内部必须维护一个权威的映射字典并进行标准化处理。复权问题股价数据有前复权、后复权和不复权之分。对于长期趋势分析必须使用复权数据。yfinance默认提供的是调整后收盘价Adj Close已考虑了分红和拆股通常可以当作后复权价格使用。但在计算涨跌幅、特别是与成交量结合分析时需要明确自己用的是哪种价格。停牌与缺失值港股市场节假日与A股不同还有天气导致的休市如台风。获取到的数据时间序列可能存在缺口。在计算移动平均、技术指标时pandas的.rolling()默认会忽略NaN但你需要确保缺失是因为停牌而非数据错误并在图表中予以适当标注比如在K线图上留下空白。实时与延时数据免费接口通常有15分钟延时。如果项目标榜“实时”就需要接入付费行情源。这一点必须在项目说明中清晰告知用户否则会产生误导。一个健壮的数据获取函数应该如下import yfinance as yf import akshare as ak import pandas as pd from datetime import datetime import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) HK_STOCK_MAP { 腾讯: 00700.HK, 腾讯控股: 00700.HK, 阿里巴巴: 09988.HK, 美团: 03690.HK, 美团-W: 03690.HK, 京东健康: 06618.HK, # ... 更多映射 } def get_hk_stock_data(stock_name, start_date, end_date, sourceyfinance): 获取港股历史数据 Args: stock_name: 股票名称或代码 start_date: 开始日期 (datetime或字符串) end_date: 结束日期 (datetime或字符串) source: 数据源yfinance 或 akshare Returns: pandas.DataFrame # 1. 代码转换 hk_code HK_STOCK_MAP.get(stock_name, stock_name) # 先尝试从名称映射 if not hk_code.endswith(.HK): hk_code hk_code .HK # 确保后缀 # 清理代码适配yfinance (如 00700.HK - 0700.HK) clean_code_for_yf hk_code.replace(0, , 1) if hk_code.startswith(0) and hk_code.endswith(.HK) else hk_code try: if source.lower() yfinance: ticker yf.Ticker(clean_code_for_yf) df ticker.history(startstart_date, endend_date) if df.empty: raise ValueError(fyfinance returned empty data for {clean_code_for_yf}) # yfinance的Volume列名就是Volume elif source.lower() akshare: # akshare接口可能不同这里是一个示例 code_without_suffix hk_code.replace(.HK, ) df ak.stock_hk_hist(symbolcode_without_suffix, perioddaily, start_datestart_date.strftime(%Y%m%d), end_dateend_date.strftime(%Y%m%d), adjust) if df.empty: raise ValueError(fakshare returned empty data for {code_without_suffix}) # 可能需要重命名列以统一格式例如将“日期”改为“Date”“收盘”改为“Close” df.rename(columns{日期: Date, 开盘: Open, 收盘: Close, 最高: High, 最低: Low, 成交量: Volume}, inplaceTrue) df[Date] pd.to_datetime(df[Date]) df.set_index(Date, inplaceTrue) else: raise ValueError(fUnsupported data source: {source}) logger.info(fSuccessfully fetched data for {hk_code} from {start_date} to {end_date} via {source}. Shape: {df.shape}) return df except Exception as e: logger.error(fFailed to fetch data for {stock_name} ({hk_code}): {e}) # 可以在这里加入降级策略比如yfinance失败后尝试akshare if source yfinance: logger.info(Trying fallback to akshare...) return get_hk_stock_data(stock_name, start_date, end_date, sourceakshare) else: raise注意事项在实际项目中数据获取函数需要有更完善的错误处理、重试机制和缓存特别是对于免费接口有调用频率限制。缓存可以存在本地SQLite数据库或Redis中键可以是f{hk_code}:{start_date}:{end_date}有效时间设为1天对于日线数据。3.3 金融指标计算与可视化生成当数据就绪后下一步就是根据用户指令计算指标并绘图。这部分需要预置一个“金融指标函数库”。常见指标计算示例def calculate_technical_indicators(df): 计算常见技术指标 # 确保数据按日期排序 df df.sort_index() # 移动平均线 df[MA5] df[Close].rolling(window5).mean() df[MA20] df[Close].rolling(window20).mean() df[MA60] df[Close].rolling(window60).mean() # 布林带 df[MA20] df[Close].rolling(window20).mean() df[STD20] df[Close].rolling(window20).std() df[Upper_Band] df[MA20] (df[STD20] * 2) df[Lower_Band] df[MA20] - (df[STD20] * 2) # 相对强弱指数 (RSI) delta df[Close].diff() gain (delta.where(delta 0, 0)).rolling(window14).mean() loss (-delta.where(delta 0, 0)).rolling(window14).mean() rs gain / loss df[RSI] 100 - (100 / (1 rs)) # 指数平滑移动平均线 (MACD) exp1 df[Close].ewm(span12, adjustFalse).mean() exp2 df[Close].ewm(span26, adjustFalse).mean() df[MACD] exp1 - exp2 df[Signal_Line] df[MACD].ewm(span9, adjustFalse).mean() df[MACD_Histogram] df[MACD] - df[Signal_Line] return df def calculate_fundamental_indicators(ticker_symbol, df): 计算基本面指标需要额外数据此处为示例 # 这里需要从其他接口获取财报数据如市盈率、市净率 # 假设我们有一个函数 get_fundamental_data(ticker_symbol) 返回一个字典 # fundamental_data get_fundamental_data(ticker_symbol) # df[PE] fundamental_data.get(pe_ratio, None) # 可能需要按日期对齐 # 这是一个更复杂的集成问题通常需要异步或离线处理 return df可视化模板化为了满足“生成代码”的需求我们可以预先定义一些图表模板函数AI生成的代码可以调用或组合这些模板。def plot_candlestick_with_ma(df, title): 绘制K线图与移动平均线模板 import matplotlib.pyplot as plt from matplotlib.pylab import date2num import matplotlib.dates as mdates from mpl_finance import candlestick_ohlc # 或使用 mplfinance 库 # 准备数据 df_plot df.reset_index() df_plot[Date_num] date2num(df_plot[Date].dt.to_pydatetime()) ohlc df_plot[[Date_num, Open, High, Low, Close]].values fig, ax plt.subplots(figsize(14, 7)) # 绘制K线 candlestick_ohlc(ax, ohlc, width0.6, colorupg, colordownr) # 绘制均线 if MA20 in df.columns: ax.plot(df_plot[Date_num], df[MA20].values, labelMA20, colorblue, linewidth1.5) if MA60 in df.columns: ax.plot(df_plot[Date_num], df[MA60].values, labelMA60, colororange, linewidth1.5) ax.xaxis.set_major_formatter(mdates.DateFormatter(%Y-%m-%d)) ax.xaxis.set_major_locator(mdates.AutoDateLocator()) fig.autofmt_xdate() ax.set_title(title) ax.legend() ax.grid(True) return fig, ax # 更现代的做法是使用 mplfinance import mplfinance as mpf def plot_with_mplfinance(df, title, ma_periods(5, 20, 60), volumeTrue): 使用mplfinance库绘制更专业简洁 add_plot [] for period in ma_periods: if fMA{period} in df.columns: # mplfinance可以直接用df的列作为addplot ap mpf.make_addplot(df[fMA{period}], colorblue if period20 else orange, width0.7) add_plot.append(ap) style mpf.make_mpf_style(base_mpf_stylecharles, rc{font.size: 10}) fig, axes mpf.plot(df, typecandle, stylestyle, titletitle, ylabelPrice, volumevolume, addplotadd_plot if add_plot else None, returnfigTrue) return fig, axes实操心得在让AI生成可视化代码时要引导它使用清晰、规范的绘图逻辑。避免生成过于花哨或难以阅读的图表。对于金融数据一致性很重要比如上涨用绿色、下跌用红色是行业惯例。另外一定要让生成的代码包含plt.tight_layout()和适当的图形尺寸设置否则图表元素可能会重叠。4. 系统实现与核心环节4.1 构建一个简单的本地原型要理解这个项目如何工作最好的方式是自己动手实现一个简化版。我们不涉及复杂的AI模型部署而是用规则引擎代码模板来模拟核心流程。步骤1定义指令解析规则规则引擎替代AI我们创建一个字典将关键词映射到具体的操作和参数。import re from datetime import datetime, timedelta class SimpleHKQueryParser: def __init__(self): self.stock_pattern re.compile(r(腾讯|阿里巴巴|美团|京东健康|小米|中国移动)) self.time_pattern re.compile(r最近(\d)(天|个月|月|年)) self.action_pattern re.compile(r(画|绘制|显示|查看)(.*?)(图|图表|走势)) self.indicator_pattern re.compile(r(移动平均线|均线|MA|RSI|MACD|布林带)) def parse(self, query): 解析自然语言查询返回结构化的指令字典 instruction { stock: None, start_date: None, end_date: datetime.now(), actions: [], indicators: [] } # 1. 解析股票 stock_match self.stock_pattern.search(query) if stock_match: instruction[stock] stock_match.group(0) # 2. 解析时间 time_match self.time_pattern.search(query) if time_match: num, unit int(time_match.group(1)), time_match.group(2) if unit in [天, 日]: delta timedelta(daysnum) elif unit in [个月, 月]: delta timedelta(daysnum*30) # 简化处理 elif unit 年: delta timedelta(daysnum*365) instruction[start_date] datetime.now() - delta # 3. 解析动作和指标 if K线 in query or k线 in query: instruction[actions].append(plot_candle) if 移动平均 in query or 均线 in query or MA in query: # 简单提取数字如“20日移动平均线” ma_periods re.findall(r(\d)[日]?移动平均线, query) if ma_periods: instruction[indicators].extend([fMA{period} for period in ma_periods]) else: # 默认添加MA20和MA60 instruction[indicators].extend([MA20, MA60]) return instruction # 测试 parser SimpleHKQueryParser() query 画一下阿里巴巴最近半年的日K线图并且把20日和60日移动平均线加上 instruction parser.parse(query) print(instruction) # 输出: {stock: 阿里巴巴, start_date: datetime对象(半年前), end_date: datetime.now(), actions: [plot_candle], indicators: [MA20, MA60]}步骤2根据指令生成代码我们有一个代码生成器根据解析出的指令字典填充预置的代码模板。class CodeGenerator: def __init__(self): self.template import yfinance as yf import pandas as pd import matplotlib.pyplot as plt from datetime import datetime # 参数 STOCK_CODE \{stock_code}\ START_DATE \{start_date}\ END_DATE \{end_date}\ # 获取数据 ticker yf.Ticker(STOCK_CODE) df ticker.history(startSTART_DATE, endEND_DATE) if df.empty: print(\未获取到数据请检查股票代码或日期范围。\) exit() # 计算指标 {indicator_code} # 绘图 {plot_code} plt.tight_layout() plt.show() def generate(self, instruction): stock_code self._map_stock_name(instruction[stock]) start_str instruction[start_date].strftime(%Y-%m-%d) end_str instruction[end_date].strftime(%Y-%m-%d) # 生成指标计算代码 indicator_lines [] for ind in instruction[indicators]: if ind.startswith(MA): period ind[2:] indicator_lines.append(fdf[{ind}] df[Close].rolling(window{period}).mean()) indicator_code \n.join(indicator_lines) # 生成绘图代码 plot_code self._generate_plot_code(instruction[actions], instruction[indicators]) final_code self.template.format( stock_codestock_code, start_datestart_str, end_dateend_str, indicator_codeindicator_code, plot_codeplot_code ) return final_code def _map_stock_name(self, name): mapping {阿里巴巴: 09988.HK, 腾讯: 00700.HK, 美团: 03690.HK} return mapping.get(name, name) def _generate_plot_code(self, actions, indicators): if plot_candle in actions: code fig, ax plt.subplots(figsize(14, 7)) # 绘制收盘价曲线代表K线简化版 ax.plot(df.index, df[Close], labelClose Price, colorblack, linewidth1) ax.fill_between(df.index, df[Low], df[High], alpha0.3, colorgray, labelHigh-Low Range) for ind in indicators: if ind.startswith(MA): code fax.plot(df.index, df[{ind}], label{ind}, linewidth1.5)\n code ax.set_title(f{STOCK_CODE} Price Chart)\nax.legend()\nax.grid(True) return code return print(No plot action specified.) # 生成代码 generator CodeGenerator() code generator.generate(instruction) print(code)运行上述code字符串就是一段可执行的Python脚本。这个原型虽然简陋但清晰地展示了“解析-规划-生成”的流程。4.2 集成AI模型以OpenAI API为例在真实项目中我们会用大语言模型替代上面的规则引擎。以下是使用OpenAI GPT API的简化示例import openai import os from typing import Dict, Any class AICodeGenerator: def __init__(self, api_key: str, model: str gpt-4): openai.api_key api_key self.model model # 系统提示词定义角色、约束和知识 self.system_prompt 你是一个专业的港股数据分析代码生成专家。你的任务是将用户的自然语言查询转化为准确、可立即执行的Python代码。 必须遵守以下规则 1. 只输出Python代码不要任何解释、Markdown代码块标记或额外文本。 2. 使用以下库yfinance as yf, pandas as pd, matplotlib.pyplot as plt, numpy as np。 3. 港股代码必须带.HK后缀例如腾讯控股是00700.HK但yfinance需要0700.HK所以内部要做转换。 4. 时间处理用户说的“最近N天/月/年”需转换为具体的datetime对象。默认结束日期为今天。 5. 生成的代码必须包含完整的数据获取、处理、绘图和显示逻辑。 6. 确保代码安全不包含任何文件操作、网络请求除yfinance外或系统调用。 7. 图表要求美观清晰添加标题、图例和网格。 以下是港股常用股票名称与代码映射供你参考用户可能用名称提问 - 腾讯控股/腾讯 - 代码00700.HK (yfinance: 0700.HK) - 阿里巴巴/阿里 - 09988.HK (yfinance: 9988.HK) - 美团/美团-W - 03690.HK (yfinance: 3690.HK) - 京东健康 - 06618.HK (yfinance: 6618.HK) - 小米集团 - 01810.HK (yfinance: 1810.HK) 现在请根据用户请求生成代码 def generate(self, user_query: str) - str: try: response openai.ChatCompletion.create( modelself.model, messages[ {role: system, content: self.system_prompt}, {role: user, content: user_query} ], temperature0.2, # 低温度确保代码确定性高 max_tokens1500 ) generated_code response.choices[0].message.content.strip() # 清理可能出现的markdown代码块标记 if generated_code.startswith(python): generated_code generated_code[9:] if generated_code.startswith(): generated_code generated_code[3:] if generated_code.endswith(): generated_code generated_code[:-3] return generated_code.strip() except Exception as e: return f# 代码生成失败: {e} # 使用示例 # ai_gen AICodeGenerator(api_keyos.getenv(OPENAI_API_KEY)) # code ai_gen.generate(对比腾讯和美团过去一年的股价走势并计算它们的相关性。) # print(code)注意事项直接执行AI生成的代码存在安全风险。绝对不要在未经验证的情况下在拥有敏感数据或权限的环境中执行。必须在严格的沙箱如Docker容器禁用网络和文件写入中运行或者先进行静态代码分析过滤掉危险函数如eval,exec,os.system,subprocess,open等。4.3 安全执行沙箱的实现对于生产环境安全执行是重中之重。这里给出一个使用docker-py在隔离容器中运行代码的极简示例import docker import tempfile import os import stat class CodeSandbox: def __init__(self): self.client docker.from_env() self.image_name python:3.9-slim # 轻量级Python镜像 def run_code(self, code: str, timeout30): 在Docker容器中安全执行代码 # 1. 创建一个临时目录和文件 with tempfile.TemporaryDirectory() as tmpdir: code_file_path os.path.join(tmpdir, analysis.py) with open(code_file_path, w, encodingutf-8) as f: f.write(code) # 确保文件可读 os.chmod(code_file_path, stat.S_IRUSR) # 2. 准备容器挂载和命令 volumes {tmpdir: {bind: /tmp/code, mode: ro}} # 只读挂载 command ftimeout {timeout} python /tmp/code/analysis.py 21 # 超时设置合并错误输出 # 3. 运行容器禁用网络限制资源 try: container self.client.containers.run( imageself.image_name, commandcommand, volumesvolumes, network_disabledTrue, # 禁用网络 mem_limit100m, # 内存限制 cpu_period100000, cpu_quota50000, # CPU限制50% removeTrue, # 运行后自动删除容器 detachFalse, stdoutTrue, stderrTrue ) output container.decode(utf-8) if isinstance(container, bytes) else container return {success: True, output: output} except docker.errors.ContainerError as e: return {success: False, output: fContainer error: {e.stderr.decode(utf-8) if hasattr(e, stderr) else str(e)}} except Exception as e: return {success: False, output: fExecution failed: {str(e)}} # 使用示例 # sandbox CodeSandbox() # result sandbox.run_code(generated_python_code) # if result[success]: # print(执行成功输出, result[output]) # else: # print(执行失败, result[output])这个沙箱做了几重防护禁用网络防止数据外泄内存和CPU限制防止资源耗尽超时设置防止死循环容器运行后立即销毁。对于图形输出你需要额外处理比如让代码将图表保存为/tmp/code/plot.png然后从临时目录读取图像文件返回给用户。5. 常见问题与排查技巧实录在实际构建和使用这类工具时你会遇到各种各样的问题。下面是我总结的一些典型问题及其解决方案。5.1 数据获取失败或为空这是最常见的问题。问题表现df为空或只包含列名没有数据。排查步骤检查股票代码格式这是首要怀疑对象。yfinance对于港股需要将00700.HK转换为0700.HK去掉开头的0。而akshare可能需要00700不带后缀。务必打印出最终用于查询的代码字符串进行确认。检查日期格式确保传递给API的日期是字符串且格式为YYYY-MM-DD。datetime对象需要先转换。检查市场状态你请求的日期可能是非交易日港股休市。尝试扩大日期范围。切换数据源yfinance偶尔不稳定特别是对于某些小盘股。实现一个降级策略当主数据源失败时自动尝试备用数据源如akshare。查看API返回信息yfinance的ticker.info属性可能包含错误信息。打印出来看看。示例代码增强健壮性def safe_fetch_data(ticker_symbol, start, end): sources [(yfinance, self._fetch_via_yfinance), (akshare, self._fetch_via_akshare)] for source_name, fetch_func in sources: try: df fetch_func(ticker_symbol, start, end) if df is not None and not df.empty: print(f数据成功从 {source_name} 获取) return df except Exception as e: print(f从 {source_name} 获取数据失败: {e}) continue raise Exception(f所有数据源均失败无法获取 {ticker_symbol} 的数据)5.2 AI生成的代码存在语法或逻辑错误大模型并非完美生成的代码可能无法运行。问题表现SyntaxError,NameError,ImportError或逻辑错误导致结果异常。排查与解决静态语法检查在沙箱执行前先用Python的ast模块解析代码检查基本语法。import ast def validate_syntax(code): try: ast.parse(code) return True except SyntaxError as e: print(f语法错误: {e}) return False依赖包缺失AI生成的代码可能会引入未在提示词中指定的冷门库。在执行前可以分析import语句如果不在白名单如[yfinance, pandas, numpy, matplotlib, seaborn, plotly]内则拒绝执行或尝试替换为安全等效库。逻辑错误后处理对于结果异常如所有值都是NaN可以在沙箱返回结果后进行分析。如果检测到数据全为空或指标计算无效可以触发一次重试并给AI模型更具体的错误反馈让它修正代码。使用更具体的提示词在系统提示词中严格限定代码结构和函数使用方式提供几个完美的示例代码Few-shot Learning能显著提高生成代码的质量和一致性。5.3 图表显示问题或无输出在服务器或无GUI环境下运行图表可能无法直接显示。问题表现代码执行成功但没有图表弹出或保存。解决方案强制使用非交互式后端在代码开头添加import matplotlib; matplotlib.use(Agg)。这告诉matplotlib不使用图形界面而是生成图像文件。明确保存图表修改提示词要求AI生成的代码必须将图表保存到特定路径而不是使用plt.show()。例如plt.savefig(/tmp/output_chart.png, dpi150, bbox_inchestight) print(CHART_SAVED:/tmp/output_chart.png) # 输出一个特殊标记让主程序知道图已保存处理plt.show()阻塞如果代码中仍有plt.show()在沙箱环境中它会阻塞直到超时。可以在执行前对代码进行简单的字符串替换将plt.show()替换为保存命令。5.4 性能与并发问题当多个用户同时发起复杂分析请求时系统可能变慢或崩溃。问题数据获取、AI生成、代码执行都耗时特别是AI调用和沙箱启动。优化策略数据缓存对相同股票、相同时间范围的数据请求进行缓存如使用Redis设置合理的过期时间。异步处理使用asyncio或Celery将耗时的任务尤其是AI调用和代码执行放入后台队列通过WebSocket或轮询通知用户结果。连接池与资源复用数据库连接、Docker客户端等资源要使用连接池。对于沙箱可以考虑预热几个容器而不是每次从头创建。限制请求复杂度对于免费用户限制其分析的时间范围、股票数量或指标复杂度防止恶意或过载请求。5.5 港股特殊情况的处理除权除息股价会因分红派息发生跳空下跌。yfinance的Adj Close已对此进行调整。但在计算涨跌幅时要明确自己使用的是调整后价格还是实际价格。提示对于长期趋势分析务必使用Adj Close。仙股与极低价股股价低于1港元的“仙股”其最小报价单位不同且波动率可能极高。在计算百分比变化和绘制图表时Y轴刻度可能需要使用对数坐标plt.yscale(log)才能清晰显示。涡轮、牛熊证这些衍生品的代码规则与正股不同且数据源可能有限。如果项目需要支持必须单独处理其代码映射和数据获取逻辑。构建“cursor-hk-stock-analysis”这类项目最大的挑战不在于单个技术点而在于将AI的不确定性与金融数据的严谨性、系统执行的安全性三者结合起来。它要求开发者不仅懂编程和AI还要对港股市场有基本的了解。从简单的规则引擎原型开始逐步引入AI并层层加固安全护栏是稳妥的推进方式。这个项目的终极形态或许是一个能理解复杂金融逻辑、自动进行多因子分析、甚至给出投资建议的智能助手但每一步都需要扎实的数据基础和严谨的工程实践作为支撑。