# Investment Intelligence Agent

**行业研究与投资逻辑验证智能体**

把分散的研报观点、新闻事实和市场行情，组织成有证据支撑、能够回看原文、可以持续核验的研究判断。

研究一个行业，既要知道市场在讨论什么，也要理解观点背后的驱动因素，并跟踪这些判断是否得到后续事实支持。本项目围绕这一研究过程，将 **研究问答、投资逻辑验证和可复用投研能力** 接入 DeepSeek Harness，通过 Python MCP 工具完成检索、分析与校验。

*An investment research agent for evidence retrieval, thesis verification and reusable research workflows, built on DeepSeek Harness and MCP.*

[阅读示例简报](examples/research.md) · [查看结构化输出](examples/research.json) · [快速运行](#快速运行) · [架构说明](docs/ARCHITECTURE.md) · [验证记录](docs/VALIDATION.md)

## 项目成果

| 研究环节 | 要回答的问题 | 当前公开版提供的能力 |
| --- | --- | --- |
| **研究问答** | 市场上有哪些相关信息？依据来自哪里？ | 按主题、来源和截止日检索研报与新闻，返回可定位的证据片段，为带引用的回答提供依据 |
| **投资逻辑验证** | 观点由哪些变量驱动？什么证据会改变判断？ | 读取结构化观点，逐维度比对后续事件，区分支持、削弱与证据不足，并保留机构分歧 |
| **能力复用** | 如何把同一套研究方法用于其他主题或 Agent？ | 将领域能力封装为 9 个 MCP 工具，统一研究输入、证据凭据与输出校验，生成 HTML / Markdown / JSON 简报 |

下面是使用虚构公司「云澜算力」生成的研究简报。公开样例包含 **10 篇合成文档、4 条观点、6 条事件标注**，截止 2026-07-31 可见 9 篇文档。无需 API Key 即可复现。

![合成案例研究简报](docs/assets/research-preview.jpg)

## 研究问答：找到信息，也能找到依据

研报记录机构判断，新闻与公告提供后续事实，行情反映市场价格变化。系统保留每条材料的来源、发布时间和原文定位，让研究结论可以逐条核对。

例如，研究者提出“云澜算力的需求扩张是否已经兑现”，系统会围绕资本开支、服务器交付等维度检索证据。返回结果包含文档与 Chunk ID，研究者可以继续读取上下文，检查引用是否支持回答。

公开版默认使用 **BM25 检索**，配合查询扩展、来源平衡与时间过滤。研究内核保留了向量检索、RRF 融合和重排模块，混合检索尚未接入公开默认流程。

最终简报的引用还要通过程序校验：证据是否由工具返回、是否属于当前语料与截止日、引文是否出现在原文中。模型结束后，命令行入口会独立执行这一步。

## 投资逻辑：把观点拆成可以跟踪的研究问题

一条“资本开支扩张将带动服务器订单增长”的观点，包含驱动因素、预期结果和需要观察的指标。系统按这些维度组织研究，分别回答资本开支是否增加、交付是否兑现、盈利是否改善。

### 结构化观点

每条观点保留主题、方向、来源机构、报告日期与原文证据，并附带具体的验证维度。当前公开流程读取预先准备的观点库。

| 字段 | 合成案例中的内容 |
| --- | --- |
| 研究主题 | AI 算力 |
| 核心观点 | 云澜算力的 AI 算力资本开支增长将带动服务器订单增长 |
| 观点方向 | 偏多 |
| 驱动因素 | 资本开支扩张 |
| 观察指标 | 资本开支、服务器交付 |
| 来源定位 | 示例研究甲，报告日期 2026-05-05，保留原文 Chunk ID |

### 后续事实验证

系统将后续新闻与公告整理为事件，再判断事件与观点维度的关系。同一研究主题可以同时存在得到支持的判断和受到削弱的判断。

| 研究问题 | 后续证据（合成数据） | 研究结果 |
| --- | --- | --- |
| 资本开支是否增长？ | 实际资本开支同比增长 20% | 支持需求扩张中的投入维度 |
| 服务器交付是否兑现？ | 已完成服务器交付 1,200 台 | 提供需求兑现的方向性事实 |
| 订单增长是否带来盈利改善？ | 毛利率为 18%，同比下降 3 个百分点 | 削弱盈利改善判断，保留竞争压力 |
| 经营现金流是否改善？ | 当前语料缺少足够披露 | 标记为证据缺口，继续观察 |

这组证据形成的研究判断是：**需求端已有兑现证据，盈利端仍有压力，现金流改善尚缺少可验证事实。** 对应原文见 [示例简报](examples/research.md)。

### 观点、事实与市场反应分别记录

系统把基本面事实、预期变化和市场价格反应放在不同的证据类别中。预测上调与股价上涨可以作为研究背景，但不能直接计入基本面验证。行情工具依据本地价格数据计算指标，供研究者与业务判断对照。

跨研报聚合时，程序分别统计观点、报告和机构，保留同一报告内的不同方向，避免把观点条数误当成独立机构数量。缺少证据的维度也会留在最终输出中。

## 可复用投研能力

研究方法通过明确的输入输出和工具接口实现复用。更换符合数据契约的研究语料后，可以沿用检索、事件验证和引用校验流程。

| 输入 | 输出 |
| --- | --- |
| 研究主题与问题 | 主题观点及分歧 |
| 研报、新闻、公告与准备好的观点库 | 可定位到原文的代表性证据 |
| 统一研究截止日 | 各维度的验证状态与证据缺口 |
| 本地行情与对照基准 | 市场反应指标及结构化研究简报 |

**模型负责语义理解与研究表达，程序负责计算、时间约束和校验。** DeepSeek Harness 提供模型与工具循环、上下文和会话，本项目提供投研领域工具及最终报告检查。默认演示使用手工标注和预设模型响应，便于复现业务过程。

```mermaid
flowchart LR
    Q[研究问题] --> H[DeepSeek Harness]
    H <-->|9 个 MCP 工具| M[Python 研究服务]
    M --> R[研报与新闻检索]
    M --> V[观点聚合与事件验证]
    M --> K[行情计算]
    R --> E[原文证据与截止日凭据]
    V --> E
    H --> J[结构化研究答案]
    J --> G[应用独立引用校验]
    E --> G
    G --> P[HTML / Markdown / JSON 简报]
```

<details>
<summary>查看 9 个 MCP 工具及职责</summary>

| 工具 | 职责 |
| --- | --- |
| `corpus_info` | 数据范围、截止日和运行模式 |
| `search_research_reports` | 有时间边界的研报检索 |
| `search_news` | 新闻与公告检索 |
| `list_theses` | 读取已准备的结构化观点 |
| `read_evidence` | 按 Chunk ID 回看原文 |
| `verify_thesis` | 事件去重、维度验证、证据缺口 |
| `build_research_object` | 分别统计观点、研报和机构，保留 mixed 方向 |
| `calculate_market_response` | 确定性计算本地行情指标 |
| `validate_research_output` | 校验输出结构、引用身份和原文片段 |

</details>

框架与依赖：[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)、[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)。详细分工见 [架构说明](docs/ARCHITECTURE.md)，语料接入要求见 [数据契约](docs/DATA.md)。

## 快速运行

安装 [uv](https://docs.astral.sh/uv/getting-started/installation/) 后，在仓库根目录执行。建议 Python 3.12，uv 可自动准备解释器。

```sh
uv sync --frozen --python 3.12
uv run --frozen investment-agent doctor
uv run --frozen investment-agent demo
```

用浏览器打开 `outputs/demo/research.html`。同目录还有 `research.md` 和 `research.json`，包含工具调用轨迹和引用校验结果。

`demo` 通过真实 MCP 客户端启动 Python 服务并执行 11 次工具调用，**不需要 API Key**。调用顺序固定，用于演示业务流程，不测试模型自主规划。

### 使用官方 DS Harness

先运行不消耗模型 API 的集成演示：

```sh
uv run --frozen --extra harness investment-agent harness --mock-model
```

这里运行的是官方 Harness 与真实 MCP 工具。本地脚本模型提供预设 tool calls，用于验证框架接线与最终输出校验。Python SDK 固定为 `0.1.2rc1`，Web 发行版固定为 `0.1.2-rc.1`，均为预发布版本，升级需要重新验证兼容性。

使用真实模型时，将 `.env.example` 复制为 `.env`，填写自己的 `DEEPSEEK_API_KEY`：

```dotenv
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
INVESTMENT_MODEL_MODE=fixture
```

```sh
uv run --frozen --extra harness --extra live investment-agent harness "验证云澜算力的需求、盈利与现金流判断，引用原文并说明缺口。"
```

默认仍以 fixture 提供可复现的业务判定，外层工具选择和答案由真实模型完成。设置 `INVESTMENT_MODEL_MODE=live` 后，事件抽取和维度判定也调用模型，会产生额外 API 请求。真实外部模型的端到端验证尚未完成，详见 [验证记录](docs/VALIDATION.md)。

会话保存在 `outputs/harness/harness-home`，可使用同一 `--output` 与 `--session-id` 继续。会话和证据数据库仅保存在本地。

### 可选 Web 界面

安装 **Node.js 24+**，在仓库根目录执行：

```sh
npm ci --ignore-scripts
uv run --frozen investment-agent web
```

浏览器打开终端给出的本地地址，在官方 Harness 界面添加当前仓库为工作区，开始研究对话。默认地址为 `127.0.0.1:3080`，可用 `--port 3081` 换端口，`--no-open` 禁止自动打开浏览器。

Web 使用官方界面和本项目的研究配置，关闭通用 shell、编辑文件和子 Agent 工具。它展示工具结果与模型聊天。需要经过应用独立校验的 HTML 简报时，请使用命令行 `harness` 入口。

## 验证与工程交付

公开源码包含 61 项测试，覆盖时间边界、证据来源、引文一致性、观点统计及失败处理。官方 Harness 集成测试使用本地脚本模型与真实 MCP 服务，检查协议与运行流程。Windows 和 Ubuntu 的 [GitHub Actions](https://github.com/wst1234566/investment-intelligence-agent/actions) 已通过测试、演示、发布检查与构建。

```text
src/investment_agent/    MCP 服务、Harness 适配、示例与报告生成
src/financial_rag/       检索、事件、验证与行情业务内核
tests/                  业务测试、真实 MCP 和 Harness 集成测试
examples/               可直接阅读的合成案例产物
docs/                   架构、数据契约、验证记录与来源说明
scripts/                样例生成、发布检查、纯源码打包
.github/workflows/      Windows / Ubuntu CI
```

```sh
uv run --frozen ruff check src/investment_agent scripts tests
uv run --frozen --extra harness --extra live pytest -q
uv run --frozen python scripts/check_release.py
uv build
uv run --frozen python scripts/build_release.py
```

源码打包采用明确的文件范围，排除环境、密钥、会话和私人数据。更新公开示例时，先运行 `demo`，再运行 `uv run --frozen python scripts/export_public_example.py`，导出器会移除执行时间、耗时和会话身份字段。提交前可使用 `scripts/check_release.py --git-index` 检查实际暂存内容。详见 [发布步骤](docs/GITHUB.md) 和 [隐私复查](docs/PRIVACY_REVIEW.md)。

## 研究路线与公开范围

项目的研究路线还包括机构观点共识与投资传导分析：比较近期共识与历史窗口的差异，观察机构观点的边际变化，并沿需求、投入、经营兑现等环节组织研究问题。

| 方向 | 当前公开状态 |
| --- | --- |
| 研报与新闻检索、观点验证、证据引用 | 已提供可运行的合成案例 |
| 混合检索 | 保留相关内核模块，默认入口使用 BM25 |
| 多时间窗口 ICRS 机构观点共识因子 | 尚未提供完整可复现入口与配套回测 |
| 自动生成投资传导图 | 尚未接入当前公开工作流 |

公开版使用合成语料，不包含历史私人知识库、机构原始材料或相关评测数据。样例行情用于演示计算公式，不代表策略回测。引用校验可以确认来源与引文一致，但不能证明推理或投资判断必然成立。工具调用次数目前由提示词约束，尚未实现强制预算或业务级 exactly-once 执行。

MIT License。数据与依赖归属见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。本项目为独立展示项目。