本项目由 周嘉翔 / zhoujiaxiang 使用 gpt-6.1-sol 进行开发。
轻量级、来源优先的金融研究工作台。模型自主多轮调用 SEC、公开网页、检索、财务数据和计算工具；公司与年份无需预选，strict 才限制范围。可交付带来源的 XLSX 和 Markdown，普通回答不是产物。
当前为单用户原型：FastAPI + Pydantic AI + SQLite WAL/FTS5 + 每会话文件目录，React 使用 assistant-ui 和 AI Elements。Python/shell 尚不可执行，财年语义、数字校验和重试恢复仍有已知缺陷。不能据此承诺无幻觉或超越 ChatGPT。
Python≥3.12、uv；构建前端使用 Node 22+、npm。在本项目根目录：
uv sync --extra dev --extra agent
cp .env.example .env
npm --prefix frontend ci
npm --prefix frontend run build
uv run uvicorn finagent.api:app --host 127.0.0.1 --port 8000已有 .env 时不要覆盖。至少设置真实 SEC 联系身份、模型端点、密钥和模型：
SEC_IDENTITY=Financial Research Agent your-email@example.com
LLM_BASE_URL=https://provider.example/v1
LLM_API_KEY=your-server-side-key
LLM_MODEL=your-model
LLM_API_MODE=responses兼容 responses / chat_completions，不要求 OpenRouter。密钥仅留服务端，不进仓库或浏览器。
未配置模型时有抽取/确定性表格降级，不提供自主深度研究。生产不需要 Node 服务，但需构建前端。
页面 http://127.0.0.1:8000/ ，接口 /api/docs，存活 /api/health；health 不证明模型与 SEC 就绪。
如需内网访问可改为 0.0.0.0；项目无内置鉴权，不应直接暴露公网。单进程运行，勿直接开多 worker。
核对日期：2026-10-15。仅维护当前实现，每个模块独立中英文；不保留过渡方案、修复过程或评测报告 Markdown。 以下为统一入口，代码/机器 schema 与文档冲突时以代码为准，并同步修订双语版本。
| 模块 | 中文 | English |
|---|---|---|
| 完整处理流程（通俗详解） | 阅读 | Processing flow |
| 整体架构 | 阅读 | Architecture |
| Agent 与工具、Prompt | 阅读 | Agent, tools and prompts |
| SEC、网页与检索 | 阅读 | SEC, web and retrieval |
| 财务数据与计算 | 阅读 | Financial data and computation |
| Provenance 与校验 | 阅读 | Provenance and validation |
| 会话、存储与产物 | 阅读 | Sessions, storage and artifacts |
| 前端与语言交互 | 阅读 | Frontend and language interaction |
| API 契约 | 阅读 | API contracts |
| 配置、部署与运维 | 阅读 | Configuration, deployment and operations |
| 测试、能力与已知限制 | 阅读 | Testing, capabilities and known limits |
| 交互架构图 | 中文 HTML | English HTML |
| 第三方组件 | 说明 | Notice |
架构图由 archify 重新生成，JSON 是图源；主题、缩放、搜索和导出均内置。维护方式及校验回执： 中文 · English。
src/finagent/
api.py HTTP、SSE 与默认/兼容入口
agent.py 模型循环、工具注册、输出门槛
research_tools.py 按需研究工具
data/ retrieval/ SEC、事实选择、HTML 与 FTS5
compute/ verify/ 公式、原值回查、回答校验
storage.py SQLite 数据与来源缓存
workspace.py 会话、历史、产物元数据
filesystem.py tools.py 受限文件与显式交付
export/ XLSX
prompts.toml 可修改 Prompt 配置
frontend/ React 界面及第三方说明
docs/zh-CN/ docs/en/ 当前模块文档
docs/diagrams/ 当前架构图与图源
tests/ eval/ 测试、自建示例与评测 runner
运行数据位于 .data/（可配置）；共享 SEC 缓存在 SQLite，会话文件在默认 .data/workspaces/<thread_id>/。
同级 sec-filing-room 是已废弃的旧项目，不是运行实现，也不属于这套文档。
- 模型按需选择公司、财报和计算工具，避免回答前预取全部指标；Pydantic AI 提供结构化输出与有界重试。
- SEC/XBRL 和财报原文为主要来源，SQLite 保存引用和精确定位；派生值保留公式及输入引用，发布前重放核验。
- 回答整份校验通过后发布；问候走单独的对话字段，Prompt 要求综合分析本轮保存 Markdown 报告和核验 XLSX；程序硬门槛目前主要覆盖显式报告/Excel 请求。
- Decimal 保留完整计算精度，
compute_financial.display.text默认展示两位小数；USD 自动按百万/十亿缩放，后续计算仍用原始引用。 - 单 FastAPI 进程、SQLite 和会话文件降低部署成本；不开放任意 Python/shell。财年辨识、语义核验和生产多用户能力仍有限。
按快速开始启动服务并保持运行，在第二个终端、项目根目录执行：
uv run python eval/runners/prepare_financebench.py \
--output eval/dataset/financebench-pilot-10.json
uv run python eval/runners/financebench_pilot.py \
--sample eval/dataset/financebench-pilot-10.json \
--output eval/results/submission-run --timeout 180 --concurrency 2准备命令从固定版本的 FinanceBench 公共数据下载，核对 SHA-256，再以 seed=42 选取 10 条原题；数据只在本地生成，不随仓库再分发，也不覆盖已有题集。HTTP runner 只向 Agent 发送问题和目标文件名，金标及证据保留在评测端；输出包含配置、事件、回答和来源，不自动给出语义准确率。每次使用新输出目录，对照 gold.jsonl 人工核对完成状态、期间、数值和来源支持。这些命令会调用真实模型和 SEC，并写入本地缓存。格式与计分边界见 runner 文档。
uv run pytest -q
uv run ruff check src tests eval/runners/financebench_pilot.py
npm --prefix frontend run build最近一次记录的回归检查为 99 项测试通过。真实模型固定 FinanceBench 10 题，verification-opt-v1 完整核心正确 9/10（90%），原版和旧 v4 为 6/10。
本轮一个迭代版本达到 80% 目标后停止；当前平均 36.448 秒、旧 v4 44.85 秒、原版 70.39 秒。
模型与预算、题目和金标不变；剩余错题为 Ulta 目标期间歧义。此为单次开发集回归，暖缓存和随机性影响结果，不代表未见题准确率。
原始 JSON、事件、来源与复核仅在本地 eval/results/ 保留，不随公开仓库发布；FinanceBench 固定题集亦待再分发许可审查，不包含在本仓库。
上述准备命令可在本地生成固定题集；公开 runner 也支持另行准备符合其格式、获准使用的题集。上述分数是本地开发集结果，不是随仓库附带的独立可审计成绩。
无完整基线/ChatGPT 对照，未测全量基准和完整研报交付。
具体方法与限制见测试能力模块，测试通过不证明投资结论正确。
该评测成绩早于后续的发布流程、报告/XLSX 强制交付和数字展示改动。2026-10-14 提交更新未重跑模型评测或回归测试，90% 不能当作最新提交的已测准确率。本次更新使用 Python 编译、Ruff 和前端生产构建检查。
仓库包含有效源代码、测试、依赖锁文件、配置示例和当前中英文模块文档及架构图。
不包含密钥、真实 .env、数据库、会话与下载产物、日志、依赖目录、构建输出、独立产品调研和本地验收文件。
项目许可尚未确定；公开可见不等于已授予开源许可。第三方组件要求见对应说明。
改工具/Prompt→Agent 文档；改来源/索引→检索文档；改指标/期间→财务文档； 改引用/核验→Provenance；改会话/目录→产物；改交互→前端；改路由→API； 改配置/部署→运维；改功能边界/测试→能力文档。架构变化同步两份图源并重新校验。 每次同时更新中英文、核对日期和 README，不再追加旧流程快照或过程性方案。