FactIQ

FactIQ——面向 AI Agent 的实时财经与经济数据库

将你的 Agent 变成财经与经济分析师。此插件适用于 Claude（网页、桌面应用和 Cowork）、ChatGPT（网页和桌面应用）、Claude Code 和 Codex，可让 Agent 直接访问 FactIQ 的官方统计数据仓库——SEC 文件、美国、中国、印度、韩国、IMF、World Bank 等——以及实时市场数据、财报电话会议记录、高管媒体露面、央行演讲、会议纪要和声明，以及卫星数据（火情探测、空气质量活动信号、降雨、夜间灯光、航运和港口活动、水库水位）。 Agent 可发现数据序列、运行只读 SQL、计算衍生指标，并返回带来源的答案、图表 JSON 或报告 JSON。

无需代码库或托管数据库，只需一个免费的 FactIQ 账户。

想要贡献？最有价值的补充是领域手册，用于教会 Agent 处理一整类问题——请参阅 贡献。

安装

FactIQ 支持四种客户端接入方式。网站上的指南是应用设置和套餐要求的权威说明；这些内容的变动速度可能快于此代码仓库：

Claude（网页、桌面应用和 Cowork）

FactIQ 已列入 Claude 官方目录。登录 Claude 后，打开 claude.ai/directory/factiq，点击 Connect，完成 FactIQ 登录，然后开始新聊天。你也可以在 Customize → Plugins 中搜索 FactIQ 来找到它。为获得最佳体验，请使用 Cowork。此插件需要付费 Claude 套餐。

若要改为从此代码仓库安装，请打开 Customize → Plugins，将 defog-ai/factiq-plugin 添加为个人市场，安装 FactIQ，然后完成浏览器登录。集中审批插件的组织可以将此代码仓库镜像为私有市场。当前步骤和组织政策说明请参阅 Claude 指南。

ChatGPT（网页和桌面应用）

FactIQ 已列入 ChatGPT 官方插件目录。登录 ChatGPT 后，打开 FactIQ 列表页面，点击 Install plugin，完成 FactIQ 登录，然后开始新聊天。输入 @FactIQ 即可显式选择它。此功能适用于网页和桌面应用上的 ChatGPT Plus、Pro、Business、Enterprise 和 Edu 套餐。对于 Business、Enterprise 和 Edu，工作区管理员可能需要先允许使用 FactIQ。安装也涵盖 ChatGPT 应用内的 Codex；Codex CLI 则使用下方单独的设置方式。

若要改为从此代码仓库安装，请在 ChatGPT 桌面应用中打开 Plugins，将 defog-ai/factiq-plugin 添加为市场，然后从 Personal 选项卡安装 FactIQ。此方式仅适用于桌面应用，且需要 Pro、Business、Enterprise 或 Edu 套餐。当前套餐对照表和故障排除步骤请参阅 ChatGPT 指南。

Claude Code

/plugin marketplace add defog-ai/factiq-plugin
/plugin install factiq@factiq
/reload-plugins

安装后运行 /reload-plugins，让 Claude Code 在当前会话中加载新的技能和 MCP 服务（否则只有下次启动 Claude Code 时才会显示）。

这会添加 FactIQ 技能（Claude 会在经济／金融数据问题中自动调用）和打包的 FactIQ MCP 服务。Claude Code 会为从插件安装的技能添加命名空间，因此手动调用方式为：

最后，对 MCP 服务进行身份验证：

1. 运行 /mcp。
2. 从服务列表中选择 factiq。
3. 选择 Authenticate（或 Connect）以打开浏览器登录页面。
4. 完成 FactIQ 登录（使用邮箱、Google 或通行密钥），然后返回 Claude Code — FactIQ 工具现在已获授权。

Codex

codex plugin marketplace add defog-ai/factiq-plugin
codex plugin add factiq@factiq

然后对 MCP 服务进行授权：

codex mcp login factiq

完成浏览器登录（使用相同的 FactIQ 登录方式：邮箱、Google 或通行密钥）。安装后新建一个 Codex 对话线程；对于经济／金融数据问题，技能会自动调用。

codex plugin marketplace upgrade factiq
codex plugin add factiq@factiq

[mcp_servers.factiq]
url = "https://api.factiq.com/mcp"

claude mcp add --transport http factiq https://api.factiq.com/mcp

无需浏览器：脚本、CI 和无头 Agent

所有 FactIQ 工具都支持使用个人 API 密钥，而非通过浏览器登录。请在 factiq.com/settings/security 创建密钥。factiq.com/docs/api 中的指南介绍了如何使用该密钥调用 REST 端点和 MCP 服务，以及如何在无需浏览器的情况下将服务注册到 Claude Code 或 Codex。请勿将密钥提交到源代码管理中。在设置页面重新生成密钥后，旧密钥会立即失效。

插件会发送和运行什么

• 一个远程 MCP 服务。 插件会添加 https://api.factiq.com/mcp（参见 .mcp.json），你需要使用 OAuth 登录。每次工具调用都会将参数（搜索词、SQL 语句、序列 ID、股票代码、地区）发送到该服务，并返回 FactIQ 数据。FactIQ 会记录连接器工具的输入和输出，用于确保可靠性并提供支持，详情请参见隐私政策。
• 一个会发送消息的工具。 当 FactIQ 结果看起来有误时，send_feedback 会将由 Agent 撰写的简短报告发送给 FactIQ 团队。它不会更改任何数据。其他所有工具都只读取数据。
• 无网络访问的本地脚本。 技能可以运行 scripts/ 中的 Python 脚本（hs_codes.py、trade_sql.py、series_math.py）。这些脚本只读取其参数、你传入的文件以及 scripts/data/ 中打包的文件，并打印结果。它们不会发起网络请求。
• 仅生成本地输出。 图表和报告会作为文件写入你自己的工作区。插件不会将它们发布到任何地方。
• 插件没有钩子，安装时不会运行任何内容。

试用

安装并完成身份验证后，提出一个问题：

/factiq:factiq How has India's trade deficit with China evolved since 2020?

Agent 会找到相关系列、运行 SQL，并根据你的提问给出附有来源的答案、图表 JSON 或完整报告。你不需要使用斜杠命令：在任何受支持的客户端中提出经济或金融数据问题，都会自动调用此技能。

对于“Micron 管理层在最近一次财报电话会议上说了什么？”这类财报问题，该技能会先检查实时文字稿覆盖情况，锁定确切的财季，然后检索同一场会议中范围明确的管理层主张和问答环节压力数据。它会将口头发言与正式指引及 SEC 备案的实际数据分开；该工具不会返回原始文字稿。

对于“Jensen Huang 在财报电话会议之外如何谈论出口管制？”这类媒体问题，该技能会检查公司层面的结构化覆盖情况，按相关性排序执行确定性的词法检索，并仅在需要时间线时明确按最新内容排序。结果是适合公开展示的转述，附带带时间戳的 YouTube 链接，而非引述；当原话或语气很重要时，工作流会核验链接中的来源。专用操作手册还会确保媒体与财报内容的比较在公司、人物、主题和日期方面保持一致。 同一工具也覆盖中央银行和货币当局发布的文件（包括 Federal Reserve、European Central Bank、Bank of England、Bank of Japan、Reserve Bank of India 等）：对于“Bank of Japan 对通胀前景说了什么？”这类问题，它会按 institution 或 country 筛选，并报告每份文件所载的会议或演讲日期。

工作原理

你的编码 Agent 就是分析师：它会查找数据、进行计算，并撰写本地输出。数据访问通过 .mcp.json 中捆绑的 FactIQ MCP server，使用一个 OAuth 连接。

┌─────────────────────────────┐
│  Claude / ChatGPT /         │
│  Claude Code / Codex        │
│  + factiq skill (SKILL.md)  │      the agent orchestrates everything
└──────────────┬──────────────┘
               │  MCP over HTTP (one OAuth connection)
┌──────────────▼──────────────┐
│  FactIQ MCP server          │
│                             │
│  discover   search_datasets, describe_dataset, search_series,
│             get_data_catalog
│  fetch      run_sql (read-only), get_series, get_market_data,
│             search_company_filings, search_earnings_transcripts,
│             search_media_appearances, search_news
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│  FactIQ data warehouse      │      official and derived data sources
└─────────────────────────────┘

一项技能之所以能用相同的 SQL 习惯用法查询 BLS 失业数据、中国海关流量、RBI 货币数据和世界银行指标，是因为：后端中的每个数据源都已规范化为相同的三个核心表，且每种架构中的表都完全一致：

我们的数据摄取管道会处理繁重的格式转换工作，将每个数据源特有的格式（BLS 平面文件、BEA API、海关记录、RBI 发布文件）转换为这种结构，这样 Agent 只需学习一次模型，就能在各处使用。所有约 20 种架构中的发现、透视和筛选都遵循相同的模式；示例见 references/data/sql-guide.md。

数据仓库内容

references/data/schemas.md 提供静态概览；get_data_catalog 工具会返回实时权威版本。

仓库结构

行为逻辑所在位置——贡献者会修改的文件：

• skills/factiq/SKILL.md — 技能定义和工作流的唯一事实来源。受支持的插件客户端会从 skills/ 目录自动发现
• references/data/ — 数据层：SQL 习惯用法（sql-guide.md）和数据集架构概览（schemas.md）
• references/output/ — 本地输出格式：ChartSpec（chart-spec.md）和报告 JSON（report-spec.md）
• references/report-patterns/ — 领域指南（货币政策、双边贸易、双边经济政策、财政政策收入、企业成立、财报情报、媒体露面情报）。 report-patterns/README.md 是 SKILL.md 引用的唯一入口：它介绍所有报告遵循的辩证方法（论点 → 反论点 → 综合），并将各个领域导向相应指南，因此新增指南无需修改 SKILL.md

插件配置——通常无需修改：

• .mcp.json — 声明内置的 FactIQ MCP 服务（Streamable HTTP、OAuth）。Claude Code 和 Codex 插件加载器都会读取该文件
• .claude-plugin/ — Claude 和 Claude Code 插件及市场清单
• .codex-plugin/ — ChatGPT 和 Codex 插件清单
• .codex-plugin/plugin.json 使用注册的 FactIQ 应用 ID 作为插件名称，以关联 ChatGPT 应用
• .agents/plugins/marketplace.json — Codex 市场条目，用于 codex plugin marketplace add defog-ai/factiq-plugin

贡献

欢迎贡献——这个插件旨在与社区共同发展。 请提交 issue 或 pull request。

定制技能（领域指南）——价值最高的贡献

你可以添加的最有价值内容是领域指南：一份参考文件，教 Agent 如何出色地回答一整类问题。指南是预先写下来的领域辩证思路——问题引出的主要解读、有能力的怀疑者会提出的矛盾观点，以及用于获取两者数据的 SQL（参见 references/report-patterns/README.md 中的方法）。现有指南位于 references/report-patterns/，可供参考：

• monetary-policy.md — 央行政策立场、管理利率、公开市场操作（OMO）、资产负债表背景
• bilateral-trade.md — 两国间的贸易趋势、产品驱动因素、镜像统计注意事项
• fiscal-policy-revenue.md — 政府收入、税收构成、分配细节

一份好的指南包含：

1. 触发条件——涵盖哪些问题形式（“A 国与 B 国之间的最新贸易趋势”“解释美联储的立场”），并将其作为一行添加到 references/report-patterns/README.md 中的路由表，以便 Agent 在获取数据之前读取指南。SKILL.md 指向该路由表，因此无需修改。
2. 必需的覆盖范围——该领域的典型对照项：完整答案必须获取的交叉核查数据（镜像统计、实际值与名义值、构成、交易对手方的账目），避免 Agent 停留在第一张显而易见的图表上。
3. 可直接使用的 SQL 模板——针对三表架构、用于关键计算的经过测试的查询（最新月份同比、年初至今比较、前 N 位驱动因素）。
4. 注意事项和防护措施——单位标准化、基年变更、全国与地方层级混淆的陷阱，以及必须明确披露的数据缺口。

我们期待看到的选题：劳动力市场状况、通胀分解、能源市场、住房、主权债务、行业收益分析、国家宏观风险概览。

其他欢迎的贡献

• SQL 习惯用法和陷阱——根据实际使用经验补充到 references/data/sql-guide.md。
• 文档和修复——任何能让 Agent 首次尝试就成功的改进。

通过端到端运行指南中的问题，并检查保存的图表或报告输出来测试指南。在 PR 中提供准确的前后对比示例。

安全

本仓库中不得存放机密信息，插件也不持有任何机密信息——交互式访问通过 MCP 服务的 OAuth 流程进行，因此编码 Agent 持有令牌，而仓库中不会写入任何内容。无头模式依赖你在 FactIQ 设置页面创建并保存在自己环境中的个人 API 密钥；该密钥绝不会存储在本仓库中。所有 SQL 查询都以只读方式针对 FactIQ 数据仓库运行。

许可证

MIT