上手使用指南¶

面向第一次打开这个项目的人。读完你会知道：它是干什么的、怎么跑、每个界面看什么、怎么换成真实模型。

1. 它解决什么问题¶

你有一个研究问题，比如"分析贵州茅台最近一期经营情况与行业景气度"。传统做法是打开十几个网页、翻公告、记数据、拼结论——两三个小时，而且过两周你自己都记不清结论是从哪来的。

EquityLens 把这件事拆成 14 个可观测的步骤，交给 9 个分工不同的 AI 角色，产出一份每句话都能回溯到原文的报告，并且：

某个角色挂了，报告照发，但会明确写出"哪个维度数据不足"；
中途崩溃可以从断点续跑，已完成的步骤不会重复花钱；
花费在调用模型之前就被预算卡住。

2. 三种使用方式¶

方式 A：网页（推荐先玩这个）¶

# 终端 1：起服务
cd C:\Users\Mark\Desktop\my_new_project
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
python -m uvicorn equitylens.api.app:create_app --factory --port 8000

浏览器打开 http://127.0.0.1:8000

方式 B：命令行（适合批量跑、调试）¶

python -m equitylens.cli run "分析贵州茅台最近一期经营情况与行业景气度" --offline
python -m equitylens.cli run "分析贵州茅台" --offline --out report.md     # 导出 Markdown
python -m equitylens.cli run "分析贵州茅台" --offline --json              # 结构化结果，便于脚本处理
python -m equitylens.cli doctor                                        # 看当前配置与图结构

方式 C：HTTP API（适合接到别的系统）¶

# 发起一次研究
curl -X POST http://127.0.0.1:8000/api/runs \
  -H "Content-Type: application/json" \
  -d "{\"question\":\"分析贵州茅台\",\"as_of\":\"2026-09-30\"}"

# 查状态
curl http://127.0.0.1:8000/api/runs/<run_id>/status

# 拿报告
curl http://127.0.0.1:8000/api/runs/<run_id>/report.md

完整接口文档在 http://127.0.0.1:8000/docs （FastAPI 自动生成）。

3. 第一次运行：跟着点一遍¶

步骤 1：首页输入问题¶

打开首页，输入框已经预填了示例问题。点 开始研究。

输入框下方有三个示例 chip，点一下会自动填好问题和基准日。

步骤 2：看运行详情（这是最能体现"程序在干什么"的页面）¶

页面会实时刷新，重点看四块：

区域	看什么
执行时间线	14 个节点逐个从"待执行"变成"成功"，右侧显示每个节点耗时
实时事件	SSE 推过来的原始事件流，如 `node.started`、`debate.scored`
多空辩论	左右两栏是多方/空方论点，下面是每轮得分
预算	成本 / token / 调用次数三个进度条

离线模式下整条链路约 2~3 秒跑完，所以时间线会"唰"一下全绿。想看过程，可以把 --offline 去掉接真实模型。

步骤 3：看报告¶

点右上角 查看报告。左边是正文，右边是"证据链"。

这里是最值得学的部分：正文里每条结论后面有个蓝色编号 [3]，点它，右侧对应证据会高亮，你能看到这条结论挂在哪条公告/新闻/财报上、来源等级、发布时间、原文片段。

报告顶部有两个关键数字：

引用覆盖率：有证据支撑的结论占比（本项目离线实测 100%）
引用命中率：引用片段真的能在原文里找到的比例（离线实测 100%）

步骤 4：看"待核实问题"¶

报告末尾有一节"待核实问题"，来自各个分析师主动上报的数据缺口。这是刻意设计的——宁可承认不知道，也不要编。

4. 离线模式 vs 真实模型¶

	离线（默认）	真实模型
数据	`src/equitylens/fixtures/` 里的示例数据	真实数据源（下一阶段接入）
模型	确定性规则模型，零费用零外网	DeepSeek / 通义 / 智谱
用途	CI、断网演示、快速验证流程	真实研究

离线模式不是"假跑"：它走完整的校验、引用审计、合规检查，只是内容由规则从同一份结构化上下文生成。所以它能保证测试稳定，也能让你在没有 API Key 时先把整条链路摸熟。

切换成真实模型（三步）¶

# 1. 复制配置
copy .env.example .env

# 2. 编辑 .env
#    APP_MODE=dev
#    LLM_API_KEY=sk-你的key
#    LLM_MODEL=deepseek-chat

# 3. 重启服务

国内模型都兼容 OpenAI 协议，换供应商只改 LLM_BASE_URL + LLM_MODEL。当前数据仍来自本地示例集；接入真实数据源后才能进行真实研究。成本参考：一次完整研究约 13 次模型调用、2.6 万 token，DeepSeek 大概几分钱。

5. 几个常用操作¶

我想……	怎么做
换一个研究标的	直接改问题里的公司名/代码（当前 fixture 里只有贵州茅台，换别的会走同一套数据）
锁定信息时点（防未来信息）	改基准日 `as_of`，系统只使用该日期之前发布的证据
中途停止	运行详情页点"取消运行"，1 秒内进入终态
把报告发给别人	报告页"下载 MD"，或用"打印 / PDF"生成 PDF
排查某个节点为什么慢/失败	`GET /api/runs/{id}/trace` 看每个节点的耗时、重试次数、错误类型

6. 开发者：改哪里¶

想做的事	改哪个文件
改流程（加节点、调顺序）	`src/equitylens/graph/research_graph.py`（唯一装配点）
改某个角色的提示词	`src/equitylens/llm/prompts/zh/*.md`（改完 `prompt_version` 自动变，便于 A/B）
加一个分析师	仿 `agents/analysts/fundamental.py`，在 `build_graph()` 的 FanOut 里加一项
接入真实数据源	实现 `tools/providers/base.py` 的协议，在 `runtime.build_provider()` 切换
改状态字段	`engine/state.py` 声明通道 + reducer，再在 `build_schema()` 注册
调预算/并发	`.env` 里的 `BUDGET_*` / `LLM_MAX_CONCURRENCY`

跑测试：

pytest -q            # 69 passed
ruff check src tests # 0 error

7. 常见疑问¶

Q：为什么报告里写着"示例数据集"？ 因为当前数据是合成的。fixtures/ 里每条数据的 source 都标注了"示例数据集"，URL 用 example.invalid，避免被误认为真实披露。接真实数据源是下一阶段。

Q：能问它"该不该买"吗？ 不能。合规节点会拦截买卖建议、目标价、收益承诺类表述，这是硬约束——系统定位是"研究整理"，不是"投资建议"。

Q：为什么只支持茅台？ fixture 里只放了一家公司的示例数据。引擎本身不限行业，接真实数据源后可以换任意标的。

Q：跑一次要多少钱？ 离线 0 元；真实模型约 2.6 万 token，按 DeepSeek 价格几分钱。单次运行默认硬上限 1.2 元。