工具说明：AKShare 与 macro-data

项目介绍

它是什么。 AKShare 是一个免费、免 Key 的 Python 库，把东方财富、金十数据、新浪财经、国家统计局等网站上的宏观、行情、基金数据整理成表格，一行代码取回。它解决的问题是：财经数据散在各个网站，格式不一，手工下载费时。本课不要求你自己写 AKShare 代码，而是经课程仓库里的 macro-data 技能使用：技能里写好了选哪个源、取数模板、已知的坑，以及用国家统计局数据核验的办法。

GitHub 数据为 2026-10 核查。

核心能力：

• 取中国宏观月度、季度数据：CPI、PPI、PMI、GDP、M2、社融、LPR 等，一个函数返回一张表；
• 取 A 股、指数、基金净值、期货等行情；
• 免费、免 Key、免注册；
• 配合 macro-data：先选源，再取数，再用国家统计局数据核对最新一期，每条数据记下来源与接口。

在同类工具里的位置： AKShare 是二手汇总，数据抓自第三方网站；关键数字要回国家统计局、人民银行的原发布核对。akshare-one-mcp 是 MCP 形态的对照，只覆盖 A 股行情和财报，不含宏观数据。

国内网络： 可用。从清华 PyPI 镜像装 akshare 半分钟内完成；macro_china_cpi、macro_china_ppi、macro_china_pmi 能取到最新一期（2026-10 取数时为 2026 年 9 月）。走金十数据的 _yearly、_monthly 接口不可用：金十的数据中心接口连不上，这些接口停在 2025 年 9 月且值为空。

如果你之前已经把 macro-data 拷进项目、装过 Python 与 AKShare，这份说明用于复用和排错。

官方链接

核查日期：2026-10。

能做什么、不能做什么

能做

• 取中国宏观月度、季度数据：CPI、PPI、PMI、GDP、M2、社融、LPR 等，一个函数返回一张表。
• 取 A 股、指数、基金净值、期货等行情（stock_zh_a_daily、stock_zh_index_daily 等）。
• 配合 macro-data：先选源，再取数，再用国家统计局新接口核对最新一期，每条数据记下来源与接口。

不能做或要小心

• AKShare 是二手镜像，数据抓自第三方网站。论文、汇报里引用的关键数字，要回到国家统计局、中国人民银行的原发布核对。
• 同一个指标有多个接口，来源不同，更新进度可能差一年（见下文“常用宏观接口”）。
• 接口没有服务承诺：网站改版、接口改名时有发生；批量抓取过快可能被目标网站限流。金十数据的数据中心接口国内连不上，走金十的 _yearly／_monthly 接口不要用。
• akshare-one-mcp 没有宏观工具，查 CPI、PMI 用不上它。

适合本课的任务：取近三年中国宏观指标做基本面汇报；查最新一期 CPI、PMI 并给出原发布链接；取某只股票或基金的历史行情做描述统计。

支持的 Python 版本

结论：装 Python 3.11 及以上的 64 位版本，推荐 3.13。 3.14 也在官方声明范围内，本课统一用 3.13。最常见的失败是装了 32 位 Python（mini-racer 装不上，报 Microsoft Visual C++ 14.0 is required），不是小版本问题。

安装与配置

前置依赖

• 64 位 Python 3.11 及以上（推荐 3.13）。Windows 安装包从国内镜像下载，文件名是 python-3.13.x-amd64.exe：npmmirror https://registry.npmmirror.com/-/binary/python/ 或华为云 https://repo.huaweicloud.com/python/，两处都有 python-3.13.16-amd64.exe；官网 https://www.python.org/downloads/windows/ 国内也能打开，可作备选。已有 Anaconda／Miniconda 的可用 conda 具名环境（先按下文配国内源）。不建 venv。
• macro-data 技能文件夹。之前已拷进项目的直接复用；要重新拷，用你之前下载解压过的 sysu-awesome-cc 文件夹。课程仓库在 GitHub，国内访问时好时坏，打不开时不要让智能体想办法绕过，改用手上已有的副本。
• pip 国内镜像（见下一小节），装包全程不走 PyPI 官方源。
• 能直连国内网站：东方财富、国家统计局都是国内站，开着全局代理反而容易失败。

0. 先配好 pip 国内镜像

pip 是 Python 自带的装包工具。配一次镜像，之后 pip install 默认走国内镜像，不用每次写 -i。Windows PowerShell：

py -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
py -m pip config set global.timeout 60
py -m pip config list          # 应显示 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'

清华镜像不通时换阿里云镜像：

py -m pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

配置写在 C:\Users\<你的用户名>\AppData\Roaming\pip\pip.ini，内容等价于：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 60

macOS 把 py 换成 python3，配置文件位置以 python3 -m pip config list -v 显示的为准。两个镜像都是 https 地址，不需要加 --trusted-host。清华、阿里云镜像都已同步 akshare 1.19.1 和 akshare-one-mcp 0.4.1，清华镜像有 Windows 用的 mini_racer-0.14.1-py3-none-win_amd64.whl。

有 conda 的，conda create 默认从境外的 anaconda.org 下载，先换清华源（按清华镜像站帮助页写法）：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --set show_channel_urls yes

没有 conda 的不必为此装 conda。

1. 首选：交给智能体装

macro-data 的 SKILL.md 第〇节已经写了“先检查、说明、得到同意再装”的流程，配套 scripts/check_env.py（只用标准库，默认只读）。让智能体照技能做即可。

Claude Code（Windows，项目作用域），在项目文件夹里启动 claude 后粘贴：

请帮我把 macro-data 技能的取数环境准备好，不要装别的东西。
1. 技能在本项目 .claude/skills/macro-data/。没有的话告诉我，由我指给你本机已有的副本，不要自己去 GitHub 下载。
2. 先读 SKILL.md 第〇节，按它做：找到 64 位 Python（Windows 先试 py --version），运行 scripts/check_env.py 只做检查，把结果原样给我看。
3. 先运行 py -m pip config list，看 pip 有没有配国内镜像；没配的，说明后用 py -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple 配上。
4. 缺 akshare 就只装它：py -m pip install akshare -i https://pypi.tuna.tsinghua.edu.cn/simple ；失败换阿里云镜像 https://mirrors.aliyun.com/pypi/simple/ 。不要换成 PyPI 官方源，不要建 venv，不要用管理员权限，不要加 --break-system-packages，不要关证书校验。
5. 缺 Python 或是 32 位 Python，停下来告诉我，由我从国内镜像下载 64 位安装包自己装。
6. 装完运行 check_env.py --smoke，最后一行是 SMOKE: PASS 才算好；再告诉我装的 Python 完整路径和 akshare 版本。
每条要联网下载或改动文件的命令，先说明再执行。

不直接用 check_env.py --install：它先试清华镜像，失败后会自动换境外的 PyPI 官方源，国内网络下包文件下载慢、不稳定。按上面的提示词让它只用清华或阿里云镜像。

WorkBuddy：把技能放在项目的 .workbuddy/skills/macro-data/，新任务里粘贴同一段提示词，把第 1 条的路径改成 .workbuddy/skills/macro-data/，并加一句：

如果装包被沙箱拦下（例如解压时 mkdir 失败、Permission denied），不要换路径、改权限或用其他办法绕过沙箱，停下来告诉我，改用 scripts/nbs_fetch.py 和材料包里的备用 CSV。

它会请求的权限

WorkBuddy 默认权限下装包不会逐条请你批准，所以上面那句“被拦就停”要写进提示词。

2. 要你亲手做的部分

• 从 npmmirror（https://registry.npmmirror.com/-/binary/python/）或华为云（https://repo.huaweicloud.com/python/）下载 python-3.13.x-amd64.exe（带 amd64 的才是 64 位），双击安装包，勾选第一页底部的 “Add python.exe to PATH”，再点 “Install Now”。
• 装完关掉所有 PowerShell、VS Code、Claude Code、WorkBuddy 窗口再重开，新 PATH 才生效。
• 输入 python 弹出 Microsoft Store：那是占位程序。改用 py；或在「设置 → 应用 → 高级应用设置 → 应用执行别名」关掉两项 “应用安装程序 python.exe / python3.exe”。
• 本工具不需要 API Key，没有 Key 要保管。

3. 参考：手动安装命令

Windows 11 x64（PowerShell）

先检查版本和位数：

py --version                                   # 应显示 3.11 以上
py -c "import struct; print(struct.calcsize('P')*8, '位')"   # 应显示 64 位

从清华镜像装：

py -m pip install akshare pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

清华镜像失败时换阿里云镜像：

py -m pip install akshare pandas -i https://mirrors.aliyun.com/pypi/simple/

已按上文配好全局镜像的，可省掉 -i 一段。升级用 py -m pip install akshare --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple（官方文档的升级命令写的是 PyPI 官方源，国内改用镜像）。

pandas 会随 akshare 自动装上，写出来是为了让你知道取回的是 pandas 表格。不要直接敲 pip，用 py -m pip，保证装进的就是 py 指向的那个 Python。没有写权限时加 --user。

有 conda 的：

conda create -n macro-data python=3.13 -y
& "$(conda info --base)\envs\macro-data\python.exe" -m pip install akshare -i https://pypi.tuna.tsinghua.edu.cn/simple

macOS

python3 --version
python3 -m pip install akshare -i https://pypi.tuna.tsinghua.edu.cn/simple

macOS 安装包同样从上面两个国内镜像下载（文件名 python-3.13.x-macos11.pkg）。用 python.org 安装包装的 Python，装完要双击「应用程序 → Python 3.x → Install Certificates.command」，否则取数报 SSL 证书错误。不要用系统自带的 /usr/bin/python3（3.9，版本太旧）和 Homebrew 的 Python（pip 拒绝安装）。

MCP 版对照：akshare-one-mcp（不推荐装，仅供对照）

官方 README 的写法是用 uvx akshare-one-mcp 启动。uvx 是 uv 这个 Python 工具自带的“临时下载并运行”命令，默认从境外的 PyPI 官方源拉包；电脑上没有 Python 3.12 以上时，uv 还会从 GitHub 下载 Python。按国内网络改成下面这样：

1. 用 pip 从国内镜像装 uv，不用官方的 astral.sh 安装脚本（境外）：

   py -m pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 用一个 3.12 以上的本机 Python（推荐就是装 akshare 的那个 3.13），并让 uv 走国内镜像。Claude Code，项目作用域，配置写进项目的 .mcp.json：

   claude mcp add --transport stdio --scope project `
     --env UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple `
     --env UV_PYTHON_DOWNLOADS=never `
     akshare-one-mcp -- uvx --python 3.13 akshare-one-mcp
   

   UV_DEFAULT_INDEX 让 uv 从清华镜像拉包；UV_PYTHON_DOWNLOADS=never 禁止它从 GitHub 下载 Python，找不到本机 3.13 时直接报错，而不是卡在下载上。

3. WorkBuddy：在 MCP 设置里添加 stdio 服务器，或写进 .workbuddy/mcp.json。command 写 uvx（找不到时写 uvx.exe 的完整路径，JSON 里路径用 / 或 \\）：

   {
     "mcpServers": {
       "akshare-one-mcp": {
         "command": "uvx",
         "args": ["--python", "3.13", "akshare-one-mcp"],
         "env": {
           "UV_DEFAULT_INDEX": "https://pypi.tuna.tsinghua.edu.cn/simple",
           "UV_PYTHON_DOWNLOADS": "never"
         }
       }
     }
   }
   

两个环境变量的名称与用法见 uv 官方文档。akshare-one-mcp 取数用的东方财富、新浪、雪球都是国内站。官方 README 另给了 Smithery 一键安装（走 npx 和境外服务）和 HTTP 模式（默认监听 0.0.0.0:8081），本课都不用：前者依赖境外服务，后者会把服务暴露到局域网。

4. 怎样确认装好了

• py -c "import akshare; print(akshare.__version__)" 输出版本号（如 1.19.1）。
• py .claude/skills/macro-data/scripts/check_env.py 最后一行 STATUS: READY；带 --smoke 最后一行 SMOKE: PASS。冒烟输出类似下面这样，版本号和数值随取数时间变化：

[统计局] OK  M2 同比 2026年8月 = 7.5%（区间 202605MM-202610MM，共 4 期有值）
[AKShare] OK  akshare 1.18.97，macro_china_pmi 共 225 行，第一行：2026年09月份 | 50.1 | 0.60240964
SMOKE: PASS

• Claude Code 里 /skills 列表有 macro-data；取数时屏幕上出现 Skill(macro-data)。WorkBuddy 里展开过程，看它读了 .workbuddy/skills/macro-data/SKILL.md 或运行了其中的脚本。
• 装了 akshare-one-mcp 的：重开 Claude Code，/mcp 里显示 akshare-one-mcp 已连接，工具列表有 get_hist_data、get_income_statement 等。

常用宏观接口：数据源与更新滞后

下表是 2026 年 10 月中旬取数时的结果（akshare 1.19.1）。数据源按各函数源码里的目标网址判断。

核验：用 nbs_fetch.py 从国家统计局新接口取 CPI（上年同月 = 100），2026 年 9 月为 100.9、8 月为 100.8，与 macro_china_cpi 一致。

要点：

• 同一个指标，名字带 _yearly／_monthly 的走金十数据，停在 2025 年 9 月左右；不带后缀的走东方财富，到 2026 年 9 月。函数名看不出来源，取到数先看最新一期是哪个月。
• 如果你手上的 macro-data 的 SKILL.md 写着“查最新 CPI 改用统计局接口或 macro_china_cpi_yearly”：macro_china_cpi_yearly 同样走金十、同样滞后，替代接口应为 macro_china_cpi。在提示词里写明“CPI 用 macro_china_cpi”。
• “年率”“月率”是金十的叫法，指同比、环比，不是年度数据、月度数据。
• 东方财富接口返回的“月份”是 2026年09月份 这样的文本，按时间倒序排列，第一行最新；金十接口按时间正序，最后一行最新，且最后一行常是值为空的“待公布”。
• 国家统计局发布节奏：月度 CPI、PPI 在次月中旬前后，官方 PMI 在当月最后一天。若 10 月 19 日取到的最新 CPI 不是 9 月，就是取错了接口。
• 东方财富的个股接口 stock_zh_a_hist 偶尔连接失败，macro-data 建议改用新浪源 stock_zh_a_daily(symbol="sh600519")。

使用教程：查最新 CPI、PPI、PMI 并核验

任务：取近三年中国 CPI 同比、PPI 同比、官方制造业 PMI，标出最新一期，用国家统计局核对，留取数记录。

提示词（Claude Code 与 WorkBuddy 通用）：

用 macro-data 技能，取 2023 年 10 月以来的中国 CPI 同比、PPI 同比、官方制造业 PMI。
1. 先告诉我每个指标准备用哪个 AKShare 接口、数据源是哪家网站，为什么选它。
2. CPI 用 ak.macro_china_cpi，PPI 用 ak.macro_china_ppi，PMI 用 ak.macro_china_pmi；不要用名字带 _yearly、_monthly 的接口（来源金十数据，滞后约一年）。取到后先报告每个指标的最新一期是哪个月；最新一期早于 2026 年 8 月的，说明是接口滞后，换接口重取。
3. 用国家统计局新接口（scripts/nbs_fetch.py）核对 CPI 最新两期，写明是否一致。
4. 每个指标存一份 CSV 到 宏观数据/，逐行带：指标、期间、数值、单位、来源机构、接口名、获取时间。
5. 写 取数记录.md，每个指标一行：来源机构、接口名、获取时间（年-月-日 时:分）、覆盖期间、最新一期月份、是否滞后、核验结果。
取不到的写“未取到”和报错原文，不要补造数字。

预期看到的工具调用

• Claude Code：Skill(macro-data) → Bash 运行 check_env.py（会话第一次）→ Bash 运行一段调 ak.macro_china_cpi()、ak.macro_china_ppi()、ak.macro_china_pmi() 的 Python → Bash 运行 nbs_fetch.py data ... → Write 写 CSV 与 取数记录.md。Windows 上若没有 Git Bash，它会先把代码存成 .py 文件再运行，属正常。
• WorkBuddy：过程里能看到读取 .workbuddy/skills/macro-data/SKILL.md、运行脚本、写文件。

产出文件

项目文件夹/
├── 宏观数据/
│   ├── CPI同比.csv
│   ├── PPI同比.csv
│   └── 制造业PMI.csv
└── 取数记录.md

取数记录至少包含

验收

• 三个指标的最新一期都是 2026 年 9 月（在 2026-10-19 前后取数时）；不是的，记录里写明原因。
• 接口名里没有 _yearly、_monthly 这类滞后接口，或用了但写明了滞后。
• CSV 每行都有来源与接口列；取数记录.md 的获取时间具体到分钟。
• CPI 有一条国家统计局核验结果。
• 汇报里引用数字时写成“2026 年 9 月 CPI 同比上涨 0.9%（国家统计局）”，并能顺着取数记录找回原发布。

沙箱拦截或取不到数时的退路

WorkBuddy 自带的 Python 环境装 akshare 可能失败（解压时 mkdir 失败，被沙箱拦下）；校园网、代理也可能让 AKShare 连不上。按这个顺序退，不绕过沙箱：

1. 停下智能体正在尝试的绕过办法（换安装目录、改权限、换代理、关证书校验）。

2. 改用 scripts/nbs_fetch.py：只用 Python 标准库，不用装包，任何 Python 3 都能跑，直接从国家统计局新接口取数。CPI 同比、GDP 当季值、M2 同比的 cid 与 indicatorId 已写在 references/common-series.md：

   py .workbuddy/skills/macro-data/scripts/nbs_fetch.py data 5c7452825c7c4dcba391db5ca7f335c5 53180dfb9c14411ba4b762307c85920c 202601MM-202610MM
   py .workbuddy/skills/macro-data/scripts/nbs_fetch.py search 工业生产者出厂价格
   

   搜索只接受中文关键词；返回里“（未发布）”的月份不要当成数值。

3. 统计局也取不到的指标，用材料包里的备用 CSV：材料包/02_宏观汇报/宏观数据_备用/宏观月度数据_2024-2026.csv，从国家统计局、中国人民银行官网整理，每行带原发布网址和发布日期，覆盖到 2026 年 8 月（GDP 到 2026Q2）。取数记录里“接口”一栏写“课程备用数据”，并写明比最新发布少了哪几期。

4. 在 取数记录.md 的“环境与问题”里写清卡在哪一步、报错原文。

常见问题与排错

费用、额度、隐私与安全

• 费用：AKShare、macro-data、akshare-one-mcp 均免费，不需要注册或 API Key，没有 Key 泄露问题。
• 额度与限流：没有官方额度，但数据抓自东方财富、金十、新浪等网站，没有服务承诺。macro-data 要求批量抓取统计局不超过每秒 2 次并带重试；不要让智能体循环抓几千只股票。
• 数据使用：AKShare 转载的是第三方网站数据，引用时注明原始来源，不把它当权威发布。
• 隐私：取数只发出公开数据请求，不涉及登录态。macro-data 的 FRED 部分提到 FRED_API_KEY，本课用不到；有人配置了也不要打印到对话或截图里。
• 安装安全：只从清华或阿里云 PyPI 镜像装；不加 --break-system-packages、--trusted-host 去取数；拒绝管理员权限安装。akshare-one-mcp 用 stdio 模式，不开 HTTP 模式，不用 Smithery 的 npx 安装器。

与同类工具对比

AKShare 加 macro-data 免 Key、中国宏观覆盖全、能用统计局核验，适合本课主讲；akshare-one-mcp 以 MCP 工具形式提供 A 股行情、财报、新闻，不含宏观；OpenBB MCP 偏国际行情与宏观，部分源要 Key，依赖重；国家统计局新接口最权威，但要知道指标 ID，适合作核验而非首选。取回的数据要整理成 Excel 的，见 Python 读写 Excel。

参考链接

• AKShare 安装指导：https://akshare.akfamily.xyz/installation.html
• AKShare 文档站与更新日志：https://akshare.akfamily.xyz/、https://akshare.akfamily.xyz/changelog.html
• PyPI：akshare https://pypi.org/project/akshare/（1.19.1，requires_python >=3.11）；mini-racer https://pypi.org/project/mini-racer/；curl_cffi https://pypi.org/project/curl-cffi/；akshare-one-mcp https://pypi.org/project/akshare-one-mcp/
• akshare-one-mcp 仓库（社区项目，非 AKShare 官方）：https://github.com/zwldarren/akshare-one-mcp
• macro-data 技能：https://github.com/ai-lingnan/sysu-awesome-cc/tree/main/skills/macro-data
• uv 环境变量 UV_DEFAULT_INDEX、UV_PYTHON_DOWNLOADS：https://docs.astral.sh/uv/reference/environment/
• 清华 PyPI 镜像帮助：https://mirrors.tuna.tsinghua.edu.cn/help/pypi/；清华 Anaconda 镜像帮助：https://mirrors.tuna.tsinghua.edu.cn/help/anaconda/
• 国家统计局：https://www.stats.gov.cn/、https://data.stats.gov.cn/