AlphaDesk

2026-11-05 实际运行，详见 docs/eval-report.md 和 reports/eval_report.html。

Agent 评测（智谱 glm-5.3，32 个任务，两轮）

第一轮跑完后按 badcase 修了工具、提示词和模型参数，再跑第二轮。

第二轮也调整了评分规则（支持"亿/万"换算，接受含答案数字的引用）。按新规则重算第一轮为成功率 90.6%、引用 83.3%，所以同一规则下修改带来的提升是成功率 +6.3 个百分点、引用 +8.4 个百分点、延迟 -39%、成本 -42%。剩余 1 个失败是模型服务的内容审核误拦截。两轮用的是同一套评测题，存在过拟合可能，所以另写了 24 道没用过的新题做验证（运行前已单独提交，跑完后未改任何代码）：

验证集两个失败：一个是没检索到季度报告里的数据，Agent 错误地说"尚未披露"；一个是把原文的 66.6 亿美元写成约 66 亿，被严格评分判错。详见 评测报告 3.8 节。

其他测试

检索评测题由同一人阅读财报后编写，分数可能高于真实用户提问。

安装（Windows）

需要 Python 3.10 及以上和 Git。在 PowerShell 中执行：

git clone https://github.com/TTNAN/AlphaDesk.git
cd AlphaDesk
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python scripts\mcp_smoke_test.py      # 列出 7 个工具并逐个调用，确认安装成功

macOS / Linux 把 .venv\Scripts\activate 换成 source .venv/bin/activate，路径分隔符换成 /。

数据快照（约 3.3 MB）已随仓库提交：行情截至 2026-11-04 收盘，财报为截至 2026-11-05 的最新一期 10-K 和 10-Q。默认离线运行，不需要联网和 API key 就能使用全部工具。

接入 MCP 客户端

以下示例假设仓库在 C:\AlphaDesk，请换成你的实际路径。MCP 模式下由客户端自己的模型调用工具，不需要在 AlphaDesk 里配置 API key。

Claude Desktop：编辑 %APPDATA%\Claude\claude_desktop_config.json（macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json），保存后重启 Claude Desktop：

{
  "mcpServers": {
    "alphadesk": {
      "command": "C:\\AlphaDesk\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finagent.mcp_server"],
      "env": { "PYTHONPATH": "C:\\AlphaDesk" }
    }
  }
}

Claude Code：在终端执行

claude mcp add alphadesk -e PYTHONPATH=C:\AlphaDesk -- C:\AlphaDesk\.venv\Scripts\python.exe -m finagent.mcp_server

Cursor：在 %USERPROFILE%\.cursor\mcp.json（全局）或项目根目录 .cursor\mcp.json 写入与 Claude Desktop 相同的 JSON。

Cherry Studio 等其他客户端：在 MCP 设置中新增 stdio 类型服务，命令填 C:\AlphaDesk\.venv\Scripts\python.exe，参数填 -m finagent.mcp_server，环境变量填 PYTHONPATH=C:\AlphaDesk。

确认模拟订单：客户端里的模型只能生成待确认订单。在 AlphaDesk 目录下执行：

python -m finagent.orders list
python -m finagent.orders confirm SIM-XXXXXXXX

命令行对话和评测（需要模型 API key）

AlphaDesk 自带的 Agent 支持任何 OpenAI 兼容接口。以智谱为例：

$env:BASE_URL="https://open.bigmodel.cn/api/paas/v4"
$env:API_KEY="你的 key"
$env:MODEL="glm-5.3"
$env:FINAGENT_REASONING_EFFORT="low"      # 可选：降低思考强度，延迟约减少 40%

python -m finagent.cli ask "英伟达最大客户占营收多少？请引用财报"
python -m finagent.cli chat                 # 多轮对话
python eval\agent_eval.py                   # 跑 32 个评测任务
python scripts\build_report.py              # 生成 reports\eval_report.html

其他模型：DeepSeek https://api.deepseek.com，通义千问 https://dashscope.aliyuncs.com/compatible-mode/v1，Kimi https://api.moonshot.cn/v1。API key 只从环境变量读取，仓库中不保存任何 key。

成本估算：DeepSeek 官方价格已内置（见 finagent/agent/cost.py）。其他模型设置 FINAGENT_PRICE_INPUT_PER_M 和 FINAGENT_PRICE_OUTPUT_PER_M（美元/百万 tokens），未设置时只记录 token 数。

flowchart LR
    C[Claude Desktop / Claude Code / Cursor / Cherry Studio] -->|MCP stdio| M[mcp_server.py]
    U[用户 / 投顾] -->|命令行| A[Agent 主循环]
    A -->|function calling| L[(OpenAI 兼容模型<br/>智谱 GLM / DeepSeek / Qwen / Kimi)]
    M --> R[统一工具层]
    A --> R
    A --> MEM[记忆<br/>短期窗口 + 用户画像]
    R --> Q[行情 / 新闻]
    R --> S[财报检索<br/>BM25 + 片段引用]
    R --> F[XBRL 财务数据]
    R --> P[组合风险]
    R --> O[模拟订单]
    O --> G{人工确认}
    Q & S & F --> CACHE[(本地数据快照)]
    CACHE -.可选在线刷新.- SRC[Yahoo Finance / SEC EDGAR / 东方财富]
    A --> T[(JSONL 轨迹)]
    T --> REP[评测报告]

finagent/
  mcp_server.py        MCP stdio 服务入口
  tools/               行情、财报检索、风险、模拟订单、工具注册
  rag/                 财报切分（按 Part / Item）与 BM25 检索
  agent/               Agent 循环、模型接口、记忆、轨迹、成本
  orders.py            人工确认命令行
  cli.py               命令行入口
eval/                  检索评测题、Agent 评测任务、评测脚本、结果
scripts/               数据抓取、建索引、MCP 冒烟测试、生成报告
tests/                 42 项单元测试
docs/                  PRD、评测报告
data/cache/            离线数据快照