finai-research

# 论文-研报工作流 · FinAI Research Workflow > **描述你的研究主题 → 获取一份可提交的 LaTeX 草稿。** > > 经济与金融研究的人工智能辅助工作流 — 从创意到 LaTeX 手稿草稿。集成了 **43 个 MCP 服务器目录（41 个实际实现 + 2 个仅模拟机构数据 + 3 个可选法律风险）**，现代因果推断（DID/IV/RDD/PSM/GMM，见依赖项注释），30 种期刊模板的 LaTeX 格式化（英文/中文/日文/德文），以及人工智能辅助的审阅循环。 > > ⚠️ **重要提示**：该工具生成的草稿需要人工审阅后方可提交。所有因果识别策略、统计结果和引用必须由研究人员验证。 > > ⚠️ **法律风险服务器（CNKI / 万方 / 中国文献）**：这 3 个 MCP 服务器抓取禁止自动访问的网站。**它们默认对所有用户禁用**，包括 `full` 配置文件。要使用它们，您必须：（1）仔细阅读 [LEGAL_CONSENT.md](LEGAL_CONSENT.md)，（2）在环境中设置 `CLI_ACCEPT_RISK=cnki,wanfang,chinese-literature`。如果没有此变量，这些服务器永远不会被加载。用户对使用这些服务器产生的法律责任负责。 > 🔴 **科研诚信 — 模拟数据默认关闭（2026-06-28）**：以下 5 个 MCP 服务器返回**模拟/硬编码/公开数据快照**，**默认禁用**，防止用户基于伪造数据发表错误结论： > > - `user_nber_wp` — 返回 3 个编造的 paper_id（w32456/w32098/w31567）+ 硬编码引用计数 > - `user_bea_data` — 无论 `year` 参数如何，都返回硬编码 GDP（$27.36T） > - `user_csmar` — 文件头自承认"提供模拟数据用于演示" > - `user_wuhan_stats` / `user_macro_datas` — 公开数据快照（统计局发布，非实时 API） > > **临时启用**（如演示场景）：`export MCP_MOCK_MODE=allow`。**禁止**用于任何拟发表的研究输出。详见 [docs/MOCK_DATA_POLICY.md](docs/MOCK_DATA_POLICY.md)。  [](https://github.com/csmar432/finai-research) [](https://opensource.org/licenses/MIT) [](https://github.com/csmar432/finai-research#installation) [](https://github.com/csmar432/finai-research/releases) [](https://github.com/csmar432/finai-research/stargazers) [](https://codespaces.new/csmar432/finai-research) [](https://arxiv.org/) [](https://github.com/csmar432/finai-research/actions) [](https://github.com/csmar432/finai-research/actions) [](https://codecov.io/gh/csmar432/finai-research) [](https://github.com/PyCQA/bandit) [](https://github.com/pre-commit/pre-commit) [](https://github.com/astral-sh/ruff) [](https://github.com/csmar432/finai-research/stargazers) [](docs/audit/audit-2026-07-04.md) [](https://codecov.io/gh/csmar432/finai-research) [](https://github.com/csmar432/finai-research/discussions) [](https://doi.org/10.5281/zenodo.21262689) --- <!-- [🇨🇳 **中文文档**](README.md) · [🇬🇧 **English Documentation**](README_EN.md) --> **Languages**: 🇨🇳 [简体中文](README.md) (默认) · 🇬🇧 [English](README_EN.md) --- ## 快速导航 | 我正在寻找... | 前往 | |---|---| | **🧭 交互式配置向导** | `python scripts/setup_wizard.py --guided` · 首次安装推荐 | | **🩺 系统自检** | `python scripts/health_check.py --json` · 验证环境就绪 | | **完整中文指南** | [使用指南.md](使用指南.md) · 完整的 13 章中文手册 | | **~20 种计量方法实现** | [使用指南.md - 实证分析方法](使用指南.md#8-实证分析方法) | | **43 个 MCP 服务器目录** | [使用指南.md - MCP 数据源](使用指南.md#6-mcp-数据源)；**41 个真实实现（含 stdlib HTTP/数据库）+ 2 个仅模拟（CSMAR/Wind 需要机构账号）+ 3 个可选法律风险（CNKI/万方/中文文献）** | | **17 种 AI 技能** | [knowledge/skills/](knowledge/skills/) | | **基准测试结果** | [BENCHMARK.md](BENCHMARK.md) · 5 种计量方法精度验证 | | **API 参考** | [scripts/](scripts/) 目录下的每个模块都含 docstring 和类型注解 | | **故障排除** | [使用指南.md - 常见问题](使用指南.md#13-常见问题) | ## 60 秒演示 ```bash $ python scripts/agent_pipeline.py --topic "碳排放权交易对企业绿色创新的影响" ```  **从一个研究问题到一个结构化的研究计划 — 时间和 API 成本根据主题复杂性、数据可用性和使用的 LLM 模型而有所不同。** 所有八个阶段（创意生成 → 文献综述 → 新颖性检查 → 实证设计 → 数据获取 → 分析 → 写作 → 对抗性审查）都包括人工干预检查点。 ## 为什么选择 FinAI 研究工作流？ - **为经济学家而建，非通用 AI 演示** — 每个默认值都针对 *Journal of Finance* / *经济研究* 标准进行校准（DID 具有异质处理效应、集群稳健标准误差在公司层面、19 个稳健性检查、平行趋势图）。 - **43 个 MCP 服务器目录** — 涵盖 A 股财务数据、美国股票、全球宏观（FRED/World Bank/IMF/OECD/BEA）和 2 亿+ 学术论文。**41 个目录具有完整的 Python 实现；2 个仅模拟（user-csmar, user-wind 需要机构账号）；3 个可选法律风险（CNKI/万方/中文文献）**。免费替代方案通过 `user-financial` （akshare）和 `user-yfinance` 提供。 - **~20 种计量方法实现，不仅限于 OLS** — 标准 DID、事件研究、Bacon 分解、阶梯 DID（Callaway-Sant'Anna/Sun-Abraham/Borusyak/Goodman-Bacon，需要 `pip install diff-in-diff2`）、合成控制、工具变量（需要 `linearmodels`）、面板 GMM、RDD、事件研究、中介等。有关完整列表，请参见 CLAUDE.md 和依赖项注释。 - **30 种期刊模板，英文/中文/日文/德文** — JF、JFE、RFS、JAE、Econometrica、经济研究、金融研究、管理世界、会计研究、中国工业经济。 - **18 种专业 AI 技能**（Claude Code / Cursor / GitHub Copilot）— 创意发现、文献综述、新颖性检查、实验设计、数据获取、论文草稿、图表生成、LaTeX 编译、审查循环。 - **人工干预，绝不自主构建** — 每个阶段都需要明确的检查点批准；数据源在使用前会进行验证；没有用户同意不会使用合成数据。 ## 为什么不使用 ChatGPT？ FinAI 是专门为经济和金融研究而构建的。以下是通用 LLM 无法实现的功能： | 功能 | ChatGPT / Claude（通用） | FinAI（专业） | |---|---|---| | **A 股财务数据** | 手动下载，易出错 | ✅ 43 个 MCP 服务器自动获取 | | **具有 19 个稳健性检查的 DID** | 通用响应 | ✅ 集群稳健标准误差、Bacon 分解、事件研究 | | **JF / 经济研究 LaTeX 模板** | 手动格式化 | ✅ 30 种期刊模板，一键生成 | | **因果识别策略** | 通用建议 | ✅ 计量经济学专家知识嵌入 | | **具有出处验证的文献综述** | 复制粘贴引用 | ✅ 来源跟踪、引用验证 | | **多阶段流程，具有检查点** | 一次性答案 | ✅ 8 个阶段流程，具有人工批准 | > [!TIP] > 现在开始，零设置：**[在 GitHub Codespaces 中打开](https://codespaces.new/csmar432/finai-research)**（免费，120 小时/月）。无需安装。 > **对于中国用户：** 最全面的指南是 **[使用指南.md](使用指南.md)** — 一份完整的 13 章手册，涵盖安装、工作流程、数据源、计量方法、论文写作和常见问题。 --- ## 目标用户 | 受众 | 用例 | |----------|----------| | **博士生 / 研究人员** | 设计实证研究、运行计量分析、为 JF/JFE/RFS/经济研究/金融研究生成 LaTeX 手稿 | | **金融教授** | 自动进行文献综述、跟踪政策实验、与已发表论文进行基准测试 | | **研究生** | 使用自动化验证和稳健性检查学习计量方法（DID/IV/RDD） | | **量化分析师** | 访问 A 股数据、运行因子分析、生成机构级研究报告 | | **AI/ML 研究人员** | 探索 LLM 在金融研究自动化中的应用、来源跟踪、HITL 设计 | > **不确定？** 如果您曾经花费数天下载数据、运行回归、格式化 LaTeX 表格或搜索相关工作 — 此工具为您而设计。 --- ## MCP 服务器配置文件：选择适合您的配置文件 `register_mcp_servers.py` 支持 4 种用户类型配置文件 — 选择与您的硬件和使用场景相匹配的配置文件： | 配置文件 | 服务器 | 启动时间 | 内存 | 最适合 | |---------|---------|---------|--------|----------| | `minimal` | 5 | ~1s | ~30 MB | 演示/教学（Demo / Teaching）— 低端笔记本 | | `academic` | 18 | ~4s | ~100 MB | 学生/个人研究者 — 无机构账号 | | `quant` | 30 | ~8s | ~180 MB | 机构/量化（Quant / Institution）— 拥有 Tushare/Wind/CSMAR | | `full` | 43 | ~12s | ~220 MB | 重度用户（Power User）— 所有数据源，RAM ≥ 16 GB | ```bash # 1) 首次运行（推荐先看） python scripts/register_mcp_servers.py --profile academic --prune --dry-run # 2) 实际应用 python scripts/register_mcp_servers.py --profile academic --prune # 3) 列出当前注册 python scripts/register_mcp_servers.py --list ``` 查看 [config/mcp_profiles.json](config/mcp_profiles.json) 以获取完整的服务器列表，并查看 [使用指南.md](使用指南.md#2-安装配置) 章节，了解安装的逐步指南。 > **默认行为**：如果没有 `--profile`，所有 43 个 MCP 服务器都会注册（匹配 `full` 配置文件）。使用 `--prune` 删除超出配置文件的服务器。 --- ## 跨平台安装 该项目支持 **macOS**、**Linux** 和 **Windows**，具有特定的平台入口点： | 操作系统 | 入口脚本 | 先决条件 | |----|-------------|---------------| | **macOS**（12+） | `./run.sh` | Python 3.10+ （推荐使用 Homebrew） | | **Linux**（Ubuntu 20.04+，Debian 11+，Fedora 35+） | `./run.sh` | `sudo apt install python3.10 python3-venv`（或发行版等效） | | **Windows**（10/11） | `run.bat` | Python 3.10+ ([python.org](https://www.python.org/downloads/)）— **勾选"添加到 PATH"** 安装程序 | ### 选择您的路径 该项目支持两个入口点 — 选择与您的工作流程匹配的入口点： #### 路径 A：AI 代理（推荐） AI 代理处理整个流程端到端。无需记住命令。 ```bash # 1) 安装一次 ./run.sh # macOS / Linux run.bat # Windows # 2) 健康检查 python scripts/health_check.py # 3) 启动 AI 代理（Claude Code / Cursor / Codex）并描述您的研究： # "帮我研究关税政策对A股出口型企业创新的影响，设计一篇发表在经济研究的实证论文" ``` AI 代理自动调用所有 8 个流程阶段、MCP 数据源和 LaTeX 生成器。每个阶段都需要您的检查点批准后继续。 #### 路径 B：CLI（脚本级控制） 直接运行脚本直接运行以细粒度控制： ```bash # 完整的研发流程 python scripts/agent_pipeline.py --topic "碳排放权交易对企业绿色创新的影响" # 研究执行层（DID/IV/RDD + 写作） python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响" # 演示：机构级金融报告 python scripts/demo_research_report.py --stock 000001.SZ # MCP 工具发现 python scripts/core/mcp_tool_market.py --search "gdp" --report # 期刊模板生成 python scripts/journal_template.py --list python scripts/journal_template.py --generate JFE output/paper.tex ``` ### 平台特定说明 - **macOS**：Keychain 是原生的；keyring 自动使用 `KeychainBackend`。 - **Linux**：Keyring 使用 SecretService（gnome-keychain）。对于中文字体，请安装 `fonts-noto-cjk`： ```bash sudo apt install fonts-noto-cjk fonts-wqy-zenhei ``` - **Windows**：Keyring 使用 Credential Manager。中文字体（`SimHei`，`Microsoft YaHei`）已预安装。 ### 跨平台功能 - ✅ 所有 `scripts/*.py` 入口点 - ✅ 43 个 MCP 服务器（纯 Python stdlib） - ✅ Checkpoint（`fcntl.flock` 降级为 Windows 上的无操作） - ✅ 2,234 个单元测试（pytest --collect-only；CI 集成：Ubuntu + macOS；无 Windows） ### 已知的跨平台限制 - ⚠️ `event_monitor.py` 使用 Unix-only 的 `signal.pause()`；在 Windows 上降级为轮询循环。 - ⚠️ `keychain_setup.py` 是 macOS 特有的；对于 Windows/Linux，请使用跨平台的 keyring via `scripts/keychain_manager.py`。 - ⚠️ `core/sandbox.py` 使用 `os.fork`（Unix-only）；在 Windows 上降级为 `subprocess`。 --- ## 展示给我 用纯中文描述您的研究主题 — 代理将处理其余部分： ``` 帮我分析碳排放权交易对企业绿色创新的影响，设计一篇实证论文，发表在经济研究 ``` **代理自动生成的内容： | 阶段 | 输出 | |-------|--------| | 研究设计 | DID/IV/RDD 识别策略 + 数据来源计划 | | 实证分析 | ~30 种计量方法，自动化稳健性测试（18 种） | | 论文草稿 | 期刊格式的 LaTeX 手稿（JF/JFE/RFS/经济研究/金融研究/管理世界） | | 审查循环 | 人工智能辅助对抗性审查，需要研究人员验证 | > **数字说明：** 上表描述了核心流程输出阶段。MCP 服务器计数包括 43 个注册服务器；一些需要机构/付费账号（Tushare Pro，Wind，CSMAR，CEIC），而其他服务器无需 API 密钥（yfinance，akshare，World Bank，IMF，OECD，FRED，ArXiv，NBER，OpenAlex）。请参阅 CLAUDE.md 中的依赖项注释。 **架构概览：  * 多代理流程：用户输入 → AI 代理 → 5 阶段研究流程（大纲 → 文献 → 绘制 → 写作 → 完善，可选 HITL 门控）→ 43 个 MCP 服务器 → ~30 种计量方法 → 20 种图表类型 → LaTeX 论文 * > **注意：** 演示资产位于 `.github/demo/` 和 `docs/assets/`。该项目正在积极维护。 --- ## 主要功能 | 功能 | 描述 | |---------|-------------| | **多代理流程** | 协调 5 个流程代理（大纲 → 文献 → 绘制 → 写作 → 完善），具有可选的 HITL 门控 | | **43 个 MCP 数据服务器** | 43 个注册的 MCP 服务器目录；**41 个完全用 Python 实现（stdlib HTTP + 数据库）**；2 个仅模拟（user-csmar, user-wind 需要机构账号）；3 个可选法律风险（user-cnki, user-wanfang, user-chinese-literature）。其中 41 个真实服务器中，约 28 个无需 API 密钥（yfinance, akshare, World Bank, IMF, OECD, FRED, ArXiv, NBER, OpenAlex, SEC EDGAR, eastmoney 等）；11 个需要 API 密钥（Tushare Pro, CEIC, EODHD 等）。运行 `python scripts/count_assets.py` 获取最新的分类。 | | **~30 种计量方法** | DID（5 种变体）、RDD、合成控制、面板 GMM、空间回归、IV/2SLS、因果 ML、GARCH、生存分析、面板协整 — JF/JFE/RFS 标准。现代阶梯 DID（Callaway-Sant'Anna, Borusyak, Sun-Abraham）需要 `pip install diff-in-diff2` | | **来源跟踪** | 从原始 API 到最终图表/表格的完整数据来源 | | **HITL 门控** | 关键流程阶段的人工干预批准 | | **分析师代理** | 用于基本、估值、风险、收益、竞争和宏观研究的金融分析代理 | | **自我进化** | 基于任务结果的持续改进 | | **45 种期刊模板** | JF, JFE, RFS, JAE, Econometrica + 经济研究/金融研究/管理世界/会计研究/中国工业经济等。 | --- ## 快速开始 ### 5 分钟设置 ```bash # 1. 克隆仓库 git clone https://github.com/csmar432/finai-research.git cd finai-research-workflow # 2. 安装依赖 python3 -m venv .venv && source .venv/bin/activate pip install -e . # 可选：安装计量经济学附加包（包括 diff-in-diff2，用于 CS/BJS/Gardner DID） pip install -e ".[econometrics]" # 3. 配置 API 密钥（至少需要一个） cp .env.example .env # 编辑 .env 并添加：DEEPSEEK_API_KEY=sk-your-key # 支持的其他 API 密钥：ANTHROPIC_API_KEY, OPENAI_API_KEY # 4. 运行您的第一个研究流程 python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响" # 或使用 AI 代理（推荐）进行完整的交互式工作流 ``` ### 通过 Cursor（推荐） 用自然语言简单描述您的研究目标： ``` 帮我分析碳排放权交易对企业绿色创新的影响，设计一篇实证论文，发表在经济研究 ``` AI 代理将自动调用所有必要的模块。 --- ## 架构 系统采用**分层代理架构**，以 AI 代理（Claude Code / Cursor / Codex）作为编排器：  **关键数字**（由 `scripts/count_assets.py` 自动生成）： | 指标 | 数量 | |--------|------:| | MCP 服务器目录 | 43（28 个免费，12 个需要 API 密钥，0 个存根，3 个选择性） | | 经济计量方法模块 | 47 | | 期刊模板 | 30 | | AI 技能 | 17 | | 研究方向 | 12 | | 测试文件 / 测试函数 | 98 / 296 | | 具有测试的研究框架模块 | 21/47 | > 运行 `python scripts/count_assets.py` 以重新生成这些数字。它们被检查到 README 中作为最新计数的快照；CI 是真相的来源。 --- ## MCP 工具概述 > 总共 43 个服务器：28 个无需 API 密钥，12 个需要 API 密钥，3 个选择性法律风险。完整目录请参见 [MCP 工具市场](docs/tutorials/04-mcp-marketplace.md)。 > | 徽章 | 含义 | > |-------|---------| > | 💰 付费 | 需要机构/付费账户（Tushare Pro / Wind / CSMAR / CEIC） | > | ⚠️ 有限 | 免费层可用但限速或需要注册 | > | ✅ 免费 | 无需账户 — 开箱即用 | | MCP 服务器 | 功能 | 费用 | 免费层 | |-----------|----------|------|---------| | **user-tushare** | A 股数据（行情、财务、融资融券） | 💰 付费 | akshare 替代品 | | **user-yfinance** | 美国股票、ETF、期权、财务数据 | ✅ 免费 | 完整 | | **user-sec-edgar** | SEC 10-K/10-Q/8-K 文件 | ✅ 免费 | 完整 | | **user-financial** | 中国宏观经济（GDP/CPI/M2） | ✅ 免费 | 完整 | | **user-eodhd** | 美国收益率曲线、经济日历 | ⚠️ 有限 | 需要注册 | | **user-fed-data** | 美联储、FOMC、褐皮书 | ✅ 免费 | 完整 | | **user-wb-data** | 世界银行数据 API | ✅ 免费 | 完整 | | **user-imf-data** | 国际货币基金组织世界经济展望 | ✅ 免费 | 完整 | | **user-oecd-data** | OECD 经济数据 | ✅ 免费 | 完整 | | **user-bea-data** | 美国经济分析局（美国 GDP） | ✅ 免费 | 完整 | | **user-eastmoney-reports** | 研究报告、新闻、分析师排名 | ✅ 免费 | 完整 | | **user-enhanced-finance** | 外汇、航运指数、大宗商品 | ✅ 免费 | 完整 | | **user-openalex** | 250M+ 学术论文 + 引用图 | ✅ 免费 | 完整 | | **user-arxiv** | 学术论文搜索和下载 | ✅ 免费 | 完整 | | **user-context7** | 论文全文检索（ArXiv/DOI） | ✅ 免费 | 完整 | | **user-semantic-scholar** | AI 增强的论文搜索 | ⚠️ 有限 | 可选 API 密钥 | | **user-nber-wp** | NBER 工作论文 | ✅ 免费 | 完整 | | **user-brave-search** | 网络搜索（中文/英文） | ⚠️ 有限 | 需要注册 | | **user-chinese-literature** | CSSCI、CNKI 式搜索 | ⚠️ 有限 | 见 SECURITY.md 中的法律声明 | > **无机构账户的 A 股用户**：`user-yfinance`（美国/ADR）和 `user-financial`（akshare 免费层）涵盖基本的权益/宏观需求。付费 A 股数据（CSMAR/Wind/Tushare Pro）需要机构账户。 参见 [MCP 工具市场教程](docs/tutorials/04-mcp-marketplace.md) 以获取完整目录。 --- ## 可用技能（17 个） 每个技能都在 `.claude/skills/`（Claude Code）和 `.github/skills/`（GitHub Copilot）中记录。在 Cursor 中，直接使用 `Skill:` 命令。 | 技能 | 描述 | 关键模块 | |-------|-------------|------------| | `fin-full-pipeline` | 端到端：主题 → 论文 PDF | `scripts/agent_pipeline.py` | | `fin-idea-discovery` | 想法生成 + 数据验证 | `scripts/research_framework/pipeline.py` | | `fin-lit-review` | 系统性文献综述 | `scripts/citation_graph.py`，MCP 多源 | | `fin-generate-idea` | 8-12 个排名想法与实证验证 | MCP 数据验证 | | `fin-novelty-check` | 对 JF/JFE/RFS 的新颖性验证 | NBER，中国期刊搜索 | | `fin-experiment-design` | 完整的实证设计 | `modern_did.py`，`regression_engine.py` | | `fin-paper-writing` | 写作编排 | `report_generator.py` | | `fin-paper-draft` | 正文生成（LaTeX） | `journal_template.py` | | `fin-paper-plan` | 大纲生成 | 30 个期刊模板 | | `fin-paper-figure` | 图表生成（≥300 DPI） | `fin_charts.py`，`chart_factory.py` | | `fin-paper-convert` | LaTeX 编译 | `xelatex`/`pdflatex` + 期刊模板 | | `fin-review-loop` | 多轮对抗性评审 | 5 维评分 | | `fin-submit-check` | 提交前检查清单 | 格式，DPI，引用审计 | | `fin-data-acquisition` | 数据获取 + 回归脚本 | 43 个 MCP 服务器 | | `fin-brief-generator` | 自动生成 `FIN_BRIEF.md` | 5 个增强工具 | | `fin-ref-paper` | BibTeX 参考文献管理 | CrossRef DOI API | | `fin-viz-launch` | 自然语言 → 学术图表 | `chart_pipeline.py`，20+ 类型 | --- ## 教程 | 教程 | 描述 | 时间 | |----------|-------------|------| | [01 - 快速开始](docs/tutorials/01-quickstart.md) | 设置并运行您的第一个流程 | 5 分钟 | | [02 - 财务报告](docs/tutorials/02-financial-report.md) | 生成机构研究报告 | 10 分钟 | | [03 - 研究方向](docs/tutorials/03-research-directions.md) | 使用 DID/RDD/IV 设计实证研究 | 15 分钟 | | [04 - MCP 市场](docs/tutorials/04-mcp-marketplace.md) | 发现和添加 MCP 工具 | 15 分钟 | | [05 - 事件驱动研究](docs/tutorials/05-event-driven-research.md) | 通过事件监控自动研究 | 20 分钟 | --- ## 文档 | 文档 | 描述 | |----------|-------------| | [SETUP_GUIDE.md](SETUP_GUIDE.md) | 环境设置、API 密钥、Docker | | [USAGE_GUIDE.md](USAGE_GUIDE.md) | 完整使用指南（中文） | | [QUICKSTART.md](QUICKSTART.md) | 5 分钟快速开始 | | [CLAUDE.md](CLAUDE.md) | 代理配置和功能 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献指南 | | [docs/tutorials/](docs/tutorials/) | 分步教程 | | [docs/api_reference.md](docs/api_reference.md) | API 文档 | | [docs/MANUAL_TASKS_RUNBOOK.md](docs/MANUAL_TASKS_RUNBOOK.md) | GitHub 侧手动步骤的操作手册 | | [docs/MOCK_DATA_POLICY.md](docs/MOCK_DATA_POLICY.md) | 模拟数据政策（5 个服务器默认禁用） | | [docs/DOCKER_INSTALL.md](docs/DOCKER_INSTALL.md) | Docker 安装指南 | | [docs/CITATION_GUIDE.md](docs/CITATION_GUIDE.md) | 引用指南，用于派生作品 | | [docs/GITHUB_DISCUSSIONS_SETUP.md](docs/GITHUB_DISCUSSIONS_SETUP.md) | GitHub Discussions 启用 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统架构概述 | | [docs/audit/audit-2026-07-04.md](docs/audit/audit-2026-07-04.md) | 最新 CI 覆盖率治理审计 | --- ## 常用命令 ```bash # 论文流程 python scripts/research_framework/pipeline.py --topic "碳排放权交易对企业绿色创新的影响" # 财务报告 python scripts/demo_research_report.py --stock 000001.SZ # MCP 工具市场 python scripts/core/mcp_tool_market.py --search "gdp" --report # 事件监控 python scripts/event_monitor.py --interval 300 --test # 文献综述 python scripts/research_framework/pipeline.py --mode lit-review --topic "carbon trading innovation" # 或直接使用 AI 代理 # "帮我做碳交易创新领域的文献综述" # 期刊模板 python scripts/journal_template.py --list python scripts/journal_template.py --generate JFE output/paper.tex # 仪表盘 streamlit run scripts/dashboard.py --server.port 8050 ``` --- ## 数据覆盖 | 市场 | 来源 | 数据类型 | |--------|--------|------------| | **A 股** | `user-tushare`（免费） | 日行情、财务数据、融资融券、北向资金 | | **美国股票** | yfinance + Finviz（免费） | 行情、财务数据、ESG、期权、SEC 文件 | | **宏观（全球）** | 世界银行 + 国际货币基金组织 + OECD（免费） | GDP、CPI、人口、贸易、债务 | | **宏观（中国）** | `user-financial` + 国家统计局（免费） | CPI、PPI、PMI、M2、FDI、零售销售 | | **宏观（美国）** | FRED + 美联储经济分析局 + 美联储（免费） | NIPA、FOMC、褐皮书、收益率曲线 | | **固定收益** | EODHD（密钥）/ `user-financial`（免费） | 国债收益率、债券价格、信用利差 | | **外汇和大宗商品** | `user-enhanced-finance` + `user-financial`（免费） | 外汇汇率、航运指数、贵金属 | | **研究报告** | 东方财富（免费） | 分析师报告、新闻、行业分析 | | **学术** | arXiv + NBER（免费） | 工作论文、引用 | --- ## 扩展系统 ### 添加新的 MCP 服务器 1. 创建目录：`mcp_servers/user_your_server/` 2. 添加 `SERVER_METADATA.json` 3. 在 `tools/*.json` 中添加工具定义 4. 在 Cursor MCP 设置中注册 5. 重新构建注册表：`python scripts/core/mcp_tool_market.py --dir mcp_servers` 参见 [MCP 市场教程](docs/tutorials/04-mcp-marketplace.md) 以获取完整指南。 ### 添加新的研究方向 1. 创建文件：`scripts/research_directions/carbon_economics.py`（从现有方向复制，如 `green_finance.py` 作为模板） 2. 定义 `ResearchDirection` 类： - 研究问题 - 数据需求 - 假设推导 - 实证策略 3. 添加到 `scripts/research_directions/__init__.py` --- ## 贡献 欢迎贡献！请： 1. 分叉仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 提交更改（`git commit -m 'Add amazing feature'`） 4. 推送到分支（`git push origin feature/amazing-feature`） 5. 打开拉取请求 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整指南。 --- ## 许可证 该项目在 MIT 许可证下许可。详情请参见 [LICENSE](LICENSE)。 --- ## 致谢 - 5 轮交互式澄清模式参考 [Night Owl Research Agent](https://github.com/GRIND-Lab-Core/night_owl_research_agent) 设计（2026-06-27 命名已重命名） - 灵感来自 [PaperOrchestra](https://github.com/google-research/paper-orchestra) 多代理架构 - 数据由 akshare、yfinance、世界银行 API 和 Tushare Pro 提供支持 --- ## 星历史 [](https://star-history.com/#csmar432/finai-research&Timeline) --- ## 构建工具 | 层 | 技术 | |-------|------------| | **AI 编排** | Claude Code / Cursor / Codex，Claude API，OpenAI API，Anthropic API | | **数据（43 个服务器）** | `user-tushare`，`user-yfinance`，`user-financial`，`user-sec-edgar`，`user-eastmoney-*`，世界银行 API，IMF API | | **计量经济学** | statsmodels，linearmodels，scipy | | **可视化** | matplotlib，seaborn，plotly | | **流程** | Python 3.10+ | | **测试** | pytest，ruff | | **文档** | MkDocs Material | | **容器化** | Docker，Docker Compose | --- ## 架构图 ### 流程 DAG（8 个阶段 + 4 个人工检查点） ```mermaid flowchart TD Start([用户输入研究主题]) --> P1[1. 大纲<br/>研究框架 + 模板] P1 -->|HITL 门| P2[2. 文献综述<br/>OpenAlex + ArXiv + Context7 + NBER] P2 -->|HITL 门| P3[3. 绘图<br/>并行图表生成] P3 --> P4[4. 论文写作<br/>完整稿件草稿] P4 -->|HITL 门| P5[5. 精炼<br/>多轮对抗性评审] P5 --> Done([LaTeX 手稿草稿]) IdeaStage[想法生成<br/>第 1 阶段，共 3 阶段] -.->|可选| P1 DataStage[数据获取<br/>第 2 阶段，共 3 阶段] -.->|feeds into| P3 NoveltyStage[新颖性检查<br/>第 3 阶段，共 3 阶段] -.->|feeds into| P1 style P1 fill:#e94560,color:#fff style P2 fill:#0f3460,color:#fff style P3 fill:#533483,color:#fff style P4 fill:#16213e,color:#fff style P5 fill:#0f3460,color:#fff style IdeaStage fill:#444,color:#fff,stroke-dasharray:3 style DataStage fill:#444,color:#fff,stroke-dasharray:3 style NoveltyStage fill:#444,color:#fff,stroke-dasharray|3 classDef hitl_gate stroke:#f0ad4e,stroke-width:3px class P1,P2,P4,P5 hitl_gate ``` ### MCP 数据源选择（43 个目录：41 个真实 + 2 个模拟 + 3 个选择性法律） ```mermaid flowchart LR Req[数据请求<br/>例如 A 股 ROA] --> Router{智能路由} Router -->|Tier 1<br/>CSMAR/Wind<br/>最高质量] Router -->|不可用| Tier2[Tier 2<br/>Tushare<br/>+ 专利数据] Router -->|无密钥| Tier3[Tier 3<br/>akshare<br/>免费，慢速] Router -->|无数据| Tier4[Tier 4<br/>yfinance/合成<br/>最后手段] Tier1 --> Cache[(本地缓存<br/>SQLite)] Tier2 --> Cache Tier3 --> Cache Tier4 --> Cache Cache --> Result[验证数据 +<br/>出处哈希] style Tier1 fill:#28c840,color:#fff style Tier2 fill:#febc2e,color:#000 style Tier3 fill:#0f3460,color:#fff style Tier4 fill:#e94560,color:#fff style Cache fill:#1a1a2e,color:#fff ``` ### 现代 DID 估计器选择 ```mermaid flowchart TD DID[DID 带有阶梯处理] --> Check{从未治疗过<br/>可用？} Check -->|是| Q1{异质<br/>影响怀疑？} Check -->|否| Q2{连续<br/>治疗？} Q1 -->|是| CS[Callaway-Sant'Anna<br/>2021 - 默认] Q1 -->|否| SA[Sun-Abraham<br/>2021] Q1 -->|想要插补| BJJ[Borusyak-Jaravel-Spiess<br/>2024] Q2 -->|是| ContDID[连续 DID<br/>Callaway-DiTraglia 2024] Q2 -->|否| Decompose[Bacon 分解<br/>诊断 TWFE 偏差] CS --> Synth[合成 DID<br/>Arkhangelsky 2021] SA --> Synth BJJ --> Synth style CS fill:#e94560,color:#fff style SA fill:#0f3460,color:#fff style BJJ fill:#533483,color:#fff style Synth fill:#16213e,color:#fff style Decompose fill:#16213e,color:#fff style ContDID fill:#0f3460,color:#fff ``` --- ## 与现有工具比较 | 功能 | **FinAI 研究工作流** | [dowhy](https://github.com/py-why/dowhy) | [StatsPAI](https://github.com/brycewang-stanford/StatsPAI) | |---------|--------------------------|------------------------------------------|--------------------------------------| | **领域** | 经济和金融研究 | 工业因果推断 | 因果推断工具包 | | **数据来源** | 43 个 MCP 服务器（A 股/US/FRED/OECD；28 个免费 + 12 个 API 密钥 + 3 个选择性） | 无（仅导入） | 无（仅导入） | | **计量经济学方法** | ~30（重点 DID/IV/RDD/GMM） | 0（通用框架） | 550+（通用） | | **期刊模板** | 45（JF/JFE/RFS + 中文顶刊） | 0 | 0 | | **中文市场** | ✅ Tushare/CSMAR/Wind | ❌ | ❌ | | **人工介入** | ✅ 流程阶段 HITL 门控 | ❌ | ❌ | | **对抗性评审** | ✅ 多轮 AI 评审 | ❌ | ❌ | | **最佳适用** | 经济学家：JF/JFE/RFS/经济研究 | 生产性因果 ML | 因果推理开发人员 | --- ## 维护者 本项目由 **[@csmar432](https://github.com/csmar432)** 维护。 - 🐛 **错误报告和功能请求**：[GitHub 问题](https://github.com/csmar432/finai-research/issues) - 💬 **问题和想法**：[GitHub 讨论](https://github.com/csmar432/finai-research/discussions) - 🔒 **安全披露**：[GitHub 安全顾问](https://github.com/csmar432/finai-research/security/advisories/new) - 💖 **赞助/支持**：[GitHub 赞助](https://github.com/sponsors/csmar432) · [爱发电](https://afdian.net/a/finresearch) > 欢迎所有规模的贡献 - 请参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取工作流程。 ## 引用此作品 如果该项目有助于您的研究，请给它一个 ⭐ - 它告诉其他经济学家该项目值得他们花费时间。 如果您在已发表的研究中使用 FinAI 研究工作流，请按以下格式引用： ```bibtex @software{finai2026, title = {FinAI 研究工作流：用于经济和金融研究的端到端 AI 代理流程}, author = {csmar432}, year = {2026}, month = jun, url = {https://github.com/csmar432/finai-research}, note = {GitHub 仓库。为永久 DOI，请发布到 Zenodo 并更新此字段。} } ``` ## 相关项目 - [**dowhy**](https://github.com/py-why/dowhy) — 因果推断库（8.1K ⭐） - [**StatsPAI**](https://github.com/brycewang-stanford/StatsPAI) — 代理原生因果推断工具包（50 ⭐） - [**moderndid**](https://github.com/jordandeklerk/moderndid) — GPU 加速的现代 DID - [**diff-diff**](https://github.com/igerber/diff-diff) — Python 中的 sklearn 式 DID - [**PaperOrchestra**](https://github.com/google-research/paper-orchestra) — Google 的多代理论文写作（58 ⭐） - [**E2ER-project**](https://github.com/bhanneke/E2ER-project) — 端到端实证研究流程 - [**econ-paper-studio**](https://github.com/gaaiyun/econ-paper-studio) — 经验经济学的代理原生 CLI ## 许可证 MIT 许可证 - 请参见 [LICENSE](LICENSE) 以获取完整文本。