--- title: "W07 工具说明：AKShare 与 macro-data" --- # AKShare 与 macro-data ## 项目介绍 **它是什么。** AKShare 是一个免费、免 Key 的 Python 库，把东方财富、金十数据、新浪财经、国家统计局等网站上的宏观、行情、基金数据整理成表格，一行代码取回。它解决的问题是：财经数据散在各个网站，格式不一，手工下载费时。本课不要求你自己写 AKShare 代码，而是经课程仓库里的 `macro-data` 技能使用：技能里写好了选哪个源、取数模板、已知的坑，以及用国家统计局数据核验的办法。 | 项 | AKShare | macro-data | akshare-one-mcp（对照） | | --- | --- | --- | --- | | 是什么 | Python 数据接口库 | 取数技能（Skill） | MCP 服务器 | | 开发与维护 | AKFamily（GitHub 组织 akfamily） | 课程组，课程仓库 ai-lingnan/sysu-awesome-cc | 个人开发者 zwldarren | | 开源与许可证 | 开源，MIT | 公开仓库，未声明许可证 | 开源，MIT | | 首次发布 | GitHub 仓库建于 2019-10-01 | 课程仓库建于 2026-05-10 | PyPI 0.1.0，2025-05-02 | | 最新版本 | 1.19.1，2026-09-30 | 提交 fe05128，2026-09-27 | 0.4.1，2026-10-18 | | GitHub 星数与最近提交 | 约 2.3 万星；最近提交 2026-10-13 | 33 星；最近提交 2026-09-27 | 235 星；最近提交 2026-10-18 | | 接入方式 | Python 库 | Skill（放进 `.claude/skills/` 或 `.workbuddy/skills/`，智能体按说明调用你电脑上的 Python 跑 AKShare） | MCP（stdio 启动） | 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。 | 项目 | 链接 | 说明 | | --- | --- | --- | | AKShare 文档站 | | 接口目录按“宏观”“股票”“基金”等分类，每个接口写了目标地址和返回字段 | | AKShare 安装指导 | | Python 版本要求、国内镜像安装命令、安装报错处理 | | AKShare GitHub | | MIT 许可，约 2.3 万星 | | AKShare 更新日志 | | 版本更新频繁，接口会改名、换源 | | AKShare PyPI | | 最新 1.19.1，2026-09-30 发布 | | macro-data 技能（课程仓库） | | `SKILL.md`、`scripts/check_env.py`、`scripts/nbs_fetch.py`、`references/common-series.md` | | 国家统计局数据查询 | | macro-data 核验用的一手源；旧 `easyquery.htm` 接口 2026-03 起已废止。统计局官网 国内能正常打开 | | akshare-one-mcp | | 社区项目，MIT 许可，约 230 星；PyPI 最新 0.4.1（2026-10-18） | | 价格页 | 无 | AKShare 与 akshare-one-mcp 均免费、免 Key | ## 能做什么、不能做什么 **能做** - 取中国宏观月度、季度数据：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 版本 | 依据 | 内容 | | --- | --- | | 官方安装指导 | 只支持 64 位操作系统；Python 3.11（64 位）及以上，推荐 3.13.x（64 位） | | PyPI 元数据（1.19.1） | `requires_python >=3.11`；分类器列出 3.11、3.12、3.13、3.14 | | Windows 关键依赖 | `mini-racer` 0.14.1 提供 `py3-none-win_amd64` 安装包，不限 Python 小版本，但没有 32 位包；`curl_cffi` 0.16.3 提供 `cp310-abi3-win_amd64` 包，3.10 以上通用 | 结论：**装 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 或华为云 ，两处都有 `python-3.13.16-amd64.exe`；官网 国内也能打开，可作备选。已有 Anaconda／Miniconda 的可用 conda 具名环境（先按下文配国内源）。不建 venv。 - `macro-data` 技能文件夹。之前已拷进项目的直接复用；要重新拷，用你之前下载解压过的 `sysu-awesome-cc` 文件夹。课程仓库在 GitHub，国内访问时好时坏，打不开时不要让智能体想办法绕过，改用手上已有的副本。 - pip 国内镜像（见下一小节），装包全程不走 PyPI 官方源。 - 能直连国内网站：东方财富、国家统计局都是国内站，开着全局代理反而容易失败。 ### 0. 先配好 pip 国内镜像 pip 是 Python 自带的装包工具。配一次镜像，之后 `pip install` 默认走国内镜像，不用每次写 `-i`。Windows PowerShell： ```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' ``` 清华镜像不通时换阿里云镜像： ```powershell py -m pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ ``` 配置写在 `C:\Users\<你的用户名>\AppData\Roaming\pip\pip.ini`，内容等价于： ```txt [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 下载，先换清华源（按清华镜像站帮助页写法）： ```powershell 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` 后粘贴： ```txt 请帮我把 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/`，并加一句： ```txt 如果装包被沙箱拦下（例如解压时 mkdir 失败、Permission denied），不要换路径、改权限或用其他办法绕过沙箱，停下来告诉我，改用 scripts/nbs_fetch.py 和材料包里的备用 CSV。 ``` **它会请求的权限** | 请求 | 怎么处理 | | --- | --- | | 运行 `py --version`、`check_env.py`（不带参数） | 只读，可以允许 | | `pip config set global.index-url` 清华或阿里云镜像 | 改的是你用户目录下的 pip 配置，可以允许 | | `py -m pip install akshare -i 清华或阿里云镜像` | 看清装进的是哪个 Python（与检查结果的“Python 路径”一致）再允许 | | 换成 `https://pypi.org/simple` 或其他境外源 | 拒绝，让它换另一个国内镜像 | | `check_env.py --smoke`、运行取数脚本 | 会联网访问统计局、东方财富，可以允许 | | 以管理员身份运行、`Set-ExecutionPolicy`、改系统 PATH、关杀毒软件 | 看清再点；能不改就不改，执行策略问题可改用 `python.exe` 完整路径 | | 建 venv、装 Miniconda、加 `--trusted-host` 或关证书校验去取数 | 拒绝，告诉它“用系统 Python，不装 conda，不关证书校验” | | WorkBuddy 里尝试绕过沙箱或换代理 | 点停止 | WorkBuddy 默认权限下装包不会逐条请你批准，所以上面那句“被拦就停”要写进提示词。 ### 2. 要你亲手做的部分 - 从 npmmirror（）或华为云（）下载 `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）** 先检查版本和位数： ```powershell py --version # 应显示 3.11 以上 py -c "import struct; print(struct.calcsize('P')*8, '位')" # 应显示 64 位 ``` 从清华镜像装： ```powershell py -m pip install akshare pandas -i https://pypi.tuna.tsinghua.edu.cn/simple ``` 清华镜像失败时换阿里云镜像： ```powershell 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 的： ```powershell 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** ```bash 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` 安装脚本（境外）： ```powershell 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`： ```powershell 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 里路径用 `/` 或 `\\`）： ```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`。冒烟输出类似下面这样，版本号和数值随取数时间变化： ```txt [统计局] 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）。数据源按各函数源码里的目标网址判断。 | 接口 | 内容 | 数据源 | 最新一期 | 判断 | | --- | --- | --- | --- | --- | | `macro_china_cpi` | CPI 当月指数、同比、环比（全国／城市／农村） | 东方财富数据中心 | 2026 年 9 月（同比 0.9%） | 及时，**查最新 CPI 用它** | | `macro_china_cpi_yearly` | CPI 同比（“年率”） | 金十数据（数据中心接口国内连不上） | 2025-09-10 那一行，值为空；最后有值的是 2025 年 8 月 | 滞后约一年，不用 | | `macro_china_cpi_monthly` | CPI 环比（“月率”） | 金十数据（同上） | 同上 | 滞后约一年，不用 | | `macro_china_pmi` | 官方制造业、非制造业 PMI | 东方财富数据中心 | 2026 年 9 月（制造业 50.1） | 及时 | | `macro_china_pmi_yearly` | 官方制造业 PMI | 金十数据 | 2025 年 8 月（49.4） | 滞后约一年 | | `macro_china_ppi` | PPI 当月指数、同比 | 东方财富数据中心 | 2026 年 9 月（当月 105.0，即同比 5.0%） | 及时 | | `macro_china_ppi_yearly` | PPI 同比 | 金十数据 | 2025-09-10 那一行，值为空 | 滞后约一年 | 核验：用 `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 通用）： ```txt 用 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`、运行脚本、写文件。 **产出文件** ```txt 项目文件夹/ ├── 宏观数据/ │ ├── CPI同比.csv │ ├── PPI同比.csv │ └── 制造业PMI.csv └── 取数记录.md ``` **取数记录至少包含** | 指标 | 来源机构 | 接口 | 获取时间 | 覆盖期间 | 最新一期 | 是否滞后 | 核验 | | --- | --- | --- | --- | --- | --- | --- | --- | | CPI 同比 | 东方财富数据中心（转载国家统计局） | `ak.macro_china_cpi` | 2026-10-19 17:00 | 2023-10 至 2026-09 | 2026-09 | 否 | 国家统计局新接口 2026-09 为 100.9，一致 | **验收** - 三个指标的最新一期都是 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`： ```powershell 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` 的“环境与问题”里写清卡在哪一步、报错原文。 ## 常见问题与排错 | 现象 | 原因 | 处理 | | --- | --- | --- | | 输入 `python` 弹出 Microsoft Store，或提示 `Python was not found` | Windows 的占位程序 | 改用 `py`；或关掉“应用执行别名”里的两项 | | `Microsoft Visual C++ 14.0 is required`，`mini-racer` 装不上 | 装了 32 位 Python | 用 `check_env.py` 看“Python 位数”；卸掉，重装 “Windows installer (64-bit)” | | `No matching distribution found for akshare` 或提示 `Requires-Python >=3.11` | Python 版本低于 3.11 | 装 3.13 后重跑检查 | | 刚装过却 `No module named 'akshare'` | 装进了另一个 Python | 装包和运行用同一个解释器完整路径，以 `check_env.py` 打印的路径为准 | | pip `ReadTimeoutError`、`ProxyError` | 网络或代理 | 清华与阿里云镜像互换（不要换成境外的 PyPI 官方源）；关掉全局代理；校园网先登录 | | 取数 `ProxyError`、`RemoteDisconnected`、超时 | 全局代理把国内网站绕到境外 | 关全局代理；PowerShell 清代理变量 `Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY -ErrorAction SilentlyContinue` | | `SSL: CERTIFICATE_VERIFY_FAILED` | Windows 上多为杀毒软件或公司网络拦截 HTTPS；macOS 是没装证书 | 换网络或暂停杀毒软件的 HTTPS 扫描；macOS 运行 `Install Certificates.command`。取数不要关证书校验 | | `[WinError 5] 拒绝访问` | 往系统目录装包 | 加 `--user`；不要用管理员 PowerShell | | `UnicodeEncodeError: 'gbk' codec`、中文乱码 | Windows 控制台默认 GBK | 先运行 `$env:PYTHONUTF8=1` | | 取到的最新 CPI 是 2025 年的，或最后一行值为空 | 用了金十源的 `_yearly`／`_monthly` 接口（停在 2025-09-10、值为空） | 改用 `macro_china_cpi`，或用 `nbs_fetch.py` 从统计局取 | | 装 akshare 很慢 | pip 走了 PyPI 官方源 | 按上文配清华或阿里云镜像，国内镜像半分钟内能装完 | | 函数报 `AttributeError: module 'akshare' has no attribute ...` | 接口在新版本改名或下线 | 先 `py -m pip install akshare --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple`；再用 `[x for x in dir(ak) if x.startswith('macro_china')]` 找新名字，对照更新日志 | | 两个来源的数对不上 | 口径不同：同比还是累计、初值还是修订值、官方 PMI 还是财新 PMI | 以国家统计局、中国人民银行原发布为准，记录里写明用的哪个 | | WorkBuddy 装包时 `mkdir` 失败、`Permission denied` | 沙箱限制写入 | 不绕过，走上一节的退路 | | 文件夹或脚本名叫 `akshare` 后导入出错 | 官方文档提示：程序文件名、文件夹名不能是 `akshare` | 改名 | ## 费用、额度、隐私与安全 - **费用**：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](https://ai.lingnan.top/materials/2026-autumn/w07/tool-09-python-excel)。 ## 参考链接 - AKShare 安装指导： - AKShare 文档站与更新日志：、 - PyPI：`akshare` （1.19.1，`requires_python >=3.11`）；`mini-racer` ；`curl_cffi` ；`akshare-one-mcp` - akshare-one-mcp 仓库（社区项目，非 AKShare 官方）： - macro-data 技能： - uv 环境变量 `UV_DEFAULT_INDEX`、`UV_PYTHON_DOWNLOADS`： - 清华 PyPI 镜像帮助：；清华 Anaconda 镜像帮助： - 国家统计局：、