alphadesk-terminal

AlphaDesk — 高密度、快速的市场研究终端与 MCP 集成平台

高密度、快速的市场研究终端与集成平台。 用户连接自己的市场数据和新闻提供商；AlphaDesk 是一个工作区，可连接、核验并展示这些提供商，以及 SEC EDGAR 和美国财政部的公开记录所提供的信息。用户在自己的 AI Agent（Claude、ChatGPT、Codex、Cursor、opencode）中提出问题，Agent 通过 53 个只读 Agent 工具（MCP）读取相同记录。

AlphaDesk 读取：报价和图表、新闻、SEC 文件、财务报表、所有权和内幕交易活动、财报和公司日历、期权、加密货币。它不会交易、路由订单、持有头寸、评估投资点子或撰写摘要。

两种使用方式——托管云服务或自己的服务器。代码基于 GNU AGPL-3.0 开源；无法遵守其条款的用户可申请商业许可证。请参阅许可证。

_{所有截图中的数据都经过模糊处理：这些数据来自用户自己的供应商密钥，而供应商限制公开展示其数据。界面布局是真实的。}

图表 — 自带 SVG 引擎、交易时段区间、绘图工具	财报周 — 日期依据公司自己的公告和 SEC 文件
新闻 — 将你的新闻源集中在三天的时间窗口中，可按词语或含义搜索	期权 — 按到期日查看期权链，展示价格两侧的看涨期权和看跌期权

快速开始 — 自行运行，供个人使用

你需要 Python 3.11+（或 Docker；如果下方命令使用 python，而你的 shell 只识别 python3，请改用 python3，或使用虚拟环境自带的 python），并且需要自己的市场数据和新闻密钥，才能获取 SEC EDGAR 和财政部数据以外的内容。无需账户，无需登录，也无需设置数据库。

pip install alphadesk

python -m alphadesk.main init --email [email protected]

python -m alphadesk.main dashboard

打开 http://127.0.0.1:8000，然后在 账户 页面连接供应商，并在 Agent 访问页面连接 Agent。init 只需运行一次：它会创建设置文件 ~/.alphadesk/.env（仅所有者可访问），其中包含用于加密所存储供应商密钥的保险库密钥、SEC 要求提供的联系地址，以及单人模式设置。请保留此文件的副本——没有保险库密钥，就无法解密已存储的供应商密钥。服务器仅在本机监听。

要运行与云端完全相同的配置——使用 Postgres 和你自己的登录，而不是 SQLite 且无需登录——请使用 --like-cloud 进行设置。它会提示你输入密码（在终端中输入；密码绝不会显示），创建包含密码哈希的设置文件，并在服务器运行时创建 Postgres 数据库：

brew install postgresql@16 && brew services start postgresql@16

python -m alphadesk.main init --email [email protected] --like-cloud

然后像上面那样运行 python -m alphadesk.main dashboard，并使用该邮箱和 密码登录。使用 --login 指定其他登录邮箱，使用 --database-url 指定其他 Postgres，使用 --password-hash（通过 python -m alphadesk.main hash-password 生成）跳过提示。若要完全无需输入的配置，例如通过脚本配置：

python -m alphadesk.main init --email [email protected] --like-cloud --password-hash "$HASH" --database-url postgresql://localhost:5432/alphadesk

Postgres 方案须知：

• 版本。 此方案基于 Postgres 16 构建和运行。驱动程序是安装时附带的纯 Python 驱动，无需编译。
• 数据库。 如果服务器正在运行且用户有权创建数据库，init --like-cloud 会创建数据库。 如果无法创建，它仍会写入设置并说明后续操作，通常是运行 createdb alphadesk（或先启动 Postgres）。 首次启动时会创建表，之后再次启动也不会有问题。
• 词语搜索索引。 首次启动时还会尝试创建 pg_trgm 扩展和用于加速词语搜索的索引。如果数据库用户无权创建扩展（某些托管服务会如此）， 日志会提示一次，搜索仍然可用，只是没有索引。请让服务允许使用 pg_trgm，或以管理员身份运行 CREATE EXTENSION pg_trgm，然后重启。
• 从 SQLite 迁移。 两种存储彼此独立：将现有配置切换到 Postgres 后，台账会从空白开始。旧存储中密封的供应商密钥不会迁移过来，因此请保留设置文件，并在账户页面重新添加密钥， 或使用 python -m alphadesk.main keys import-file 导入。
• 备份。 台账是一个数据库：使用 pg_dump 进行备份。也请保留设置文件中的保险库密钥， 因为没有它就无法解封已存储的供应商密钥。

也可以改用 Docker：

[email protected] docker compose up -d

首次启动会在数据卷中完成相同的配置，并将数据保存在其中。它还会在应用旁启动 Postgres， 使用与线上服务器相同的数据库，因此你在本地测试的内容也会在云端运行；此处的词语搜索使用 Postgres 索引，而 SQLite 无法提供这种索引。

Docker 方案须知：

• 首次构建体积大且耗时长。 镜像包含 Python、仅支持 CPU 的机器学习库构建版本，以及用于语义搜索的 1.2 GB 嵌入模型，均已预先打包，因此启动容器时无需下载任何内容。请预留数 GB 空间，并做好首次构建耗时较长的准备。 ALPHADESK_SEMANTIC_SEARCH=off 会阻止应用运行时加载模型，但不会缩小镜像。
• 所有内容都保存在两个卷中。 alphadesk-data 保存设置文件（含保险库密钥），alphadesk-pg 保存数据库。 docker compose down 会保留这两个卷；docker compose down -v 会将其删除，连同你的历史记录和已存储的密钥一起删除。
• 备份设置文件。 docker compose cp alphadesk:/data/.env ./alphadesk.env 可将文件复制出来。没有保险库密钥就无法解封已存储的供应商密钥。
• 更新。 运行 git pull，然后运行 docker compose up -d --build。设置和数据会保留。 使用 docker compose logs -f alphadesk 查看日志。
• 容器内不提供登录。 它会像上面那样以单人模式在 127.0.0.1:8000 运行。若要使用自己的登录方式，请在主机上使用 --like-cloud 配置，或按下文所述在前面设置访问令牌。
• Agent。 按照常规在 Agent 访问 页面创建令牌；工具会在 http://127.0.0.1:8000/api/agent/tools/mcp 响应。若要从另一台机器访问，请将 ALPHADESK_BASE_URL 设置为该机器使用的地址，并为任何其他名称设置 ALPHADESK_ALLOWED_HOSTS，同时在前面配置访问令牌。 可从其他机器访问？ 此模式下已关闭登录，因此任何能访问该端口的人都能使用它并读取你已连接的供应商。 请将其限制在 127.0.0.1，或设置访问令牌——浏览器随后会提示输入一次，Agent 则继续使用你在 Agent 访问 页面创建的令牌：

python -c "import secrets; print(secrets.token_urlsafe(24))"

将结果写入 ~/.alphadesk/.env，格式为 ALPHADESK_ACCESS_TOKEN=...（使用 Docker 时，将其作为环境变量传入），然后重启。通过互联网访问时，请在前端配置 HTTPS。

其他运行方式、为他人提供服务的方法以及所有设置，请参阅两种运行方式和配置参考。

---

目录

1. AlphaDesk 是什么——又不是什么
2. 两种运行方式
3. 设计原则
4. 功能
5. 数据源
6. 搜索
7. Agent 访问（MCP）
8. 账户、安全与隐私
9. 架构
10. 仓库结构
11. 开发
12. 配置参考
13. 生产环境部署与运维
14. 测试与质量
15. 已知限制
16. 历史
17. [许可证](#licence）

---

AlphaDesk 是什么——又不是什么

AlphaDesk 是	AlphaDesk 不是什么
行情信息终端：获取、核验并呈现市场信息	交易系统——不具备订单路由、持仓状态或券商集成功能
集成平台：每家供应商的数据都使用读者自己的密钥	聚合器——服务端不保存供应商密钥，也绝不会将一位读者的数据与其他读者共享
记录呈现工具：完整展示申报文件、报表、新闻和价格，并标明来源	摘要工具——这里没有模型会撰写、改述或评分任何内容
可插拔：新闻源、市场数据、文字记录和仪表盘磁贴都可替换为不同的供应商	黑箱——所有列表都按时间、字母顺序或所展示的数据排序

目前免费提供（已设计付款功能，但尚未启用；请参阅账户）。

---

两种运行方式

	选项 A——托管云服务	选项 B——自托管
价格	早期访问期间免费。 计划价格：每月 $19 或每年 $190，启用前会公布	免费
许可证	商业服务条款——你无需承担 AGPL 义务	GNU AGPL-3.0
你需要运行	无：使用运营方设置的登录凭据登录	一个容器或一个 Python 进程，以及一个数据库
按含义搜索	已包含（嵌入模型运行在我们的服务器上）	在你的 CPU 上运行（约 1.2 GB 模型；建议配置为 2 vCPU / 4 GiB），也可关闭
供应商密钥	你自己的密钥，在账户页面连接	你自己的密钥，放在 .env 或账户页面中
更新	持续更新	执行 git pull 并重启

选项 A——托管云服务

1. 打开托管终端，使用运营方设置的电子邮箱和密码登录。每台服务器只有一个用户，且不提供注册功能。
2. 在账户页面连接你已经在使用的市场数据和新闻供应商（Alpaca、FMP、Finnhub、Polygon 等）。SEC EDGAR 和美国财政部无需密钥。
3. 可选：在Agent 访问页面（侧边栏中，位于账户旁边）连接你自己的 Agent——获取供 Claude Code、Codex、Cursor 或 opencode 使用的令牌，或在 Claude.ai 或 ChatGPT 中将服务器 URL 添加为连接器。

选项 B — 自托管（AGPL-3.0）

你需要 SEC User-Agent，并填写真实联系信息（SEC 会阻止不带 User-Agent 的请求）、Python 3.11+ 或 Docker；此外，除 EDGAR 和 Treasury 数据外，还需要你自己的供应商密钥。

1. 配置。 复制模板并填写两个必填值：

cp alphadesk/deploy/env.example .env

.env 中的设置	必填	填写内容
ALPHADESK_VAULT_KEY	是	32 个随机字节，以 base64 编码 — 用于加密存储的供应商密钥；请留存副本，丢失后这些密钥将无法读取
SEC_USER_AGENT	是	AlphaDesk ([email protected]) — 名称和真实邮箱地址
ALPHADESK_AUTH	单人使用时	off：单个本地账户，无需登录
ALPHADESK_ACCESS_TOKEN	可从本机以外访问时	关闭登录后使用一个共享密钥（16 个以上字符），浏览器会要求输入一次；参见 Quick start
ALPHADESK_DATABASE_URL	否	一个 postgresql:// URL（推荐：Docker 设置和 init --like-cloud 会使用它，并启用需要 pg_trgm 扩展的词语搜索索引）；未设置时使用 ALPHADESK_DATA 中的 SQLite 数据库（~/.alphadesk）
ALPACA_API_KEY、ALPACA_SECRET_KEY、FMP_API_KEY、FINNHUB_API_KEY、POLYGON_API_KEY、ALPHAVANTAGE_API_KEY	否	你自己的密钥。启动时发现这些密钥后，会加密保存到你的账户中 — 登录关闭时保存到本地账户，否则保存到登录账户 — 因此设置文件是密钥记录的来源：它会添加或更新密钥，但不会删除密钥；下次启动时，设置文件中的密钥优先于账户页面上修改的密钥。你仍可改为在账户页面连接密钥
ALPHADESK_SEMANTIC_SEARCH	否	设为 off 可跳过约 1.2 GB 的嵌入模型；搜索将仅匹配词语。若未安装 search extra，该功能本来就处于关闭状态
ALPHADESK_LOGIN_EMAIL + ALPHADESK_LOGIN_PASSWORD_HASH	否	登录开启时：你自己的登录信息，也是服务接受的唯一用户。开启登录后，此项为必填；未设置时服务不会启动。启动时会创建账户；若已存在同邮箱地址的账户，则会设置密码并保留其数据。设置此项后，密码表单是唯一的登录入口。使用 python -m alphadesk.main hash-password 生成哈希；也可使用 ALPHADESK_LOGIN_PASSWORD（12 个以上字符），但任何能读取设置的人都能看到它。标识符为邮箱地址

使用以下命令生成保险库密钥：

python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

2a. 从 PyPI 安装 — 最快捷的方式；内置界面随软件包一同提供：

pip install alphadesk

python -m alphadesk.main dashboard

终端地址为 http://127.0.0.1:8000。此安装方式体积小、速度快，新闻搜索按词语匹配。如需同时按含义搜索，请安装 extra（pip install "alphadesk[search]"，需要约 1 GB 的 PyTorch）；首次启动时会将 1.2 GB 的模型下载到 Hugging Face 缓存中。

2b. 或从克隆的仓库运行，如果你打算修改任何内容，请选择这种方式：

pip install -r requirements.txt
python -m alphadesk.main keys import-env
python -m alphadesk.main dashboard

2c. 或使用 Docker 运行。 镜像已内置嵌入模型，因此容器启动时无需下载任何内容：

docker build -t alphadesk .

docker run -d --name alphadesk -p 8000:8000 --env-file .env -e ALPHADESK_DATA=/data -v alphadesk-data:/data alphadesk

如果 ALPHADESK_AUTH 保持开启，请在 .env 中设置登录信息（邮箱和使用 python -m alphadesk.main hash-password 生成的密码哈希）；开启登录但未设置登录信息时，服务不会启动。

3. 保持私有或发布你的更改。 根据 AGPL，如果你允许其他人通过网络使用修改后的副本，就必须向他们提供你所用版本的源代码。你自己使用未经修改的版本，或在自己的机器上保留更改、不与他人分享，则没有这项义务。

---

设计原则

这些就是产品本身。许多看似缺失的功能都是经过构建、衡量后特意移除的——DECISIONS.md 说明了移除什么以及原因。请提供证据并提交 issue。

1. 绝不改述。 每个面板和 Agent 工具都返回供应商或 EDGAR 实际说过的内容——分页呈现的文件、一系列声明、报道本身的文本。如果无法连同来源一起展示某个数字，就不展示。
2. 数据不足以支撑的指标会隐藏。 按系列衡量柱状图覆盖率和缺口大小；低于最低要求时，RSI 和 MACD 会隐藏，而不是绘制在稀疏的交易记录上，因为那样的图表看起来会和流动性充足的股票图表一样。
3. 绝不替你排名。 筛选器窗口按字母顺序排列；日历和 Agent 工具只按各行显示的数字排序。搜索结果按时间从新到旧排列——模型可以判断内容是否相关，但绝不决定谁排在前面。
4. 闲置的终端不会产生任何费用。 后台循环只获取公开数据和每位读者各自的新闻；其他数据都按需获取，使用发起请求的读者自己的密钥。
5. 不可信文本始终不可信。 标题、文章、文件和文字稿都是数据。这里的任何内容都不会据此采取行动，返回这些内容的 Agent 工具也会明确说明这一点。
6. 这不是聚合器。 合并多个新闻源由读者使用自己的凭据，为自己的窗口自行完成。
7. Agent 界面只读，且针对每位读者独立运行。 每次 Agent 调用都严格以携带相应令牌或授权的读者身份运行。
8. 供应商数据属于读者。 服务器上不存放供应商密钥；没有无需密钥即可访问商业供应商或非官方端点的途径；每位读者的供应商缓存彼此隔离；供应商数据仅在功能读取期间保留。

---

功能

页面

页面	展示内容
Landing (/)	产品概览，包含模糊处理的截图；登录
Markets	可组合的看板：图表、股票概览、基于该股票构建的基金、股票/ETF/加密货币/货币/期权涨跌榜、国债收益率、热力图、新闻。股票、ETF、加密货币和期权涨跌榜可回溯至过去的交易时段：股票和 ETF 显示当天整个市场的数据，并与前一个交易时段对比；加密货币按每天收盘数据与前一天对比（UTC 日期，Alpaca 的交易场所）；期权则显示每次收盘后记录的列表——没有供应商会保留过去某一天交易最活跃的合约，因此期权历史从服务首次记录数据的当晚开始。每个已结束交易时段的收盘数据都会记录在你自己的存储中（Alpaca 或 Polygon，取决于你的密钥能访问哪个），启动时会补齐最近 15 个交易时段的数据，此后每次市场收盘后都会添加新的数据；读取过去日期时会优先从存储中读取。每个已结束交易日的完整列表也会保留（按每组筛选条件检查大幅波动、波动率和流动性，并填入名称；步进器提供的五天数据会在后台生成），因此打开已记录的日期时不会向任何供应商请求数据
Chart	完整工作区：蜡烛图、折线图、面积图、阶梯图和其他样式；从 1 分钟到多年跨度的时间间隔；指标和模板；绘图工具（桌面端，每次访问）；多图表布局；隔夜、盘前、盘后和周末时段阴影；拥挤视图会按每个像素列绘制一根蜡烛，因此缩放始终流畅；按下某个范围时会显示加载状态；百分比刻度以一根 K 线为基准（图表打开时的第一根，或从右键菜单中选择的任意一根）
Analysis	全面了解一个名称：图表、申报文件、价格表现、关键统计数据、财报历史和一致预期、分析师、评级变动、已申报财务数据、拆股、股息、机构和内部人士持股、新闻。基金还会显示持仓和分类明细
Profile	了解一家公司的身份：EDGAR 注册人信息、最新的 10-K/20-F 中业务和物业章节原文、地点、高管
News	每位读者合并后的信息流，涵盖最近三天，按时间从新到旧排列；按词语、来源或看板筛选；按词语和含义搜索；页面内置阅读器会显示信息流所含的全文，并在长篇文章顶部保留返回标题列表的入口
Filings	公司刚向 SEC 提交的文件，按时间从新到旧排列，并以阅读器形式呈现：左侧为列表（时间、股票代码、公司、表格类型，按日期分组），右侧为选中的完整申报文件，包含公司按自己的措辞声明的每个项目、SEC 编号、股票代码以及指向 EDGAR 的链接。可按项目缩小范围；使用方向键（或 j 和 k）浏览。不会根据重要性进行排序或着色
Earnings	本周发布财报的公司，按公司自行发布的日期标注，并与其 SEC 业绩申报文件关联；根据历史记录预测时段；包含预估值、实际值、意外幅度、市值、波动率和流动性。下方是即将发布财报：根据供应商的日历，显示未来 1 周、2 周、1 个月或 2 个月内发布财报的公司，按日期分组；超过一周的日期会标注为预估值（与 Agent 的财报日历覆盖范围相同）
Calendars	经济数据发布、股息、经交叉验证的拆股和 IPO
Options	带隐含波动率的期权链，认购期权为绿色、认沽期权为红色；实时查看期权流
Sectors	按权重和交易金额排列的行业基金，并显示市场广度
Baskets	36 个按驱动其走势的新闻主题分组的精选组合（利率、石油、关税、芯片出口规则、比特币等），以及读者自己的组合
Portfolio / custom views	读者保存的看板
Account	已连接供应商和信息流的覆盖情况矩阵（包含纯文本导出密钥下载）以及会话
Agent access	专属页面：通过地址连接 AI 助手（Claude.ai、ChatGPT），为程序创建令牌——每个令牌都可选择绑定允许使用它的地址；并提供可直接粘贴的配置，用于通过数据 API 使用 Claude Code、Codex、Cursor、opencode 或你自己的程序
Terms, Privacy, Disclaimer	待法律审核的公开草案

跨越终端

• 符号栏适用于每个页面；选择一行即可添加并选中符号，而不会移动页面。
• 可组合的看板：显示、隐藏、重新排序、调整图块大小和位置；布局保存在 URL 中，因此链接可以还原完全一致的看板。
• 实时数据：当读者的套餐支持时使用流式传输（Alpaca 股票、加密货币和新闻套接字），其他情况下则轮询；428 提示会列出可填充读者密钥无法支持的面板的供应商和套餐。
• 手机：每个页面都针对 375 像素屏幕和桌面进行了布局。
• 浅色和深色主题、基于 4 像素网格并包含六种文字样式的手工设计系统，以及每个叠加层中完整的键盘焦点处理。

---

数据源

市场数据——读者自己的密钥

供应商	提供内容（取决于套餐）
Alpaca	合并行情（SIP）和 IEX K 线、图表中的隔夜（Blue Ocean）时段、报价和股票异动、报价、异动、加密货币、含 IV 的期权链、期权流、公司行动
Financial Modeling Prep	日历（财报、经济、股息、拆股、IPO）、关键统计数据、档案、分析师、市值、货币、新闻稿、基金数据
Polygon (Massive)	K 线、报价、异动、货币、期权
Finnhub	公司指标、档案、财报日历和交易时段
Alpha Vantage	公司概览、K 线

对于每个面板，系统都会按照固定且有文档说明的顺序查询读者已连接的供应商；第一个提供所需数据的供应商会返回结果。图表和期权链固定使用一个供应商，不会拼接不同数据源的行情。

新闻——读者自己的订阅源

Alpaca（Benzinga）、Polygon、Finnhub、Benzinga、Alpha Vantage、 Marketaux 和 FMP。多个订阅源会合并到每位读者的同一个时间窗口中， 并按 URL 去重。Alpaca 的新闻通过实时流传输；其余订阅源每五分钟轮询一次。

无需密钥的来源——可阅读，未获授权

有三个来源无需密钥，因为没有可购买的内容：读者可在 Account 页面通过按钮逐一启用。

来源	提供内容
Nasdaq	财报、股息、拆股和上市日历——以及今日的交易暂停，这是目录中任何供应商都不提供的数据
Yahoo	来自公开图表端点的图表、报价和每日历史数据
Social	一个公开账号的帖子，从该账号的公开副本中读取。仅提供文字帖子，且所有已查看的帖子都会保存在存档中，因此搜索范围可以超出该副本最新的 100 条内容

两条规则确保这些来源诚实可靠。始终优先查询需要密钥的供应商——所有获授权的供应商都排在所有抓取来源之前，因此只有在其他来源都无法提供结果时，抓取来源才会响应。并且来源信息会随结果一同传递：目录会将来源标记为非官方，每个负载都会携带该标记，图块副标题会显示“已抓取”，而 data_sources Agent 工具会将任何供应商名称解析为获授权或只读来源。此标记旨在保护读者的推理；它并不代表网站已表示同意。

绝不会从社交帖子中读取股票代码：帖子中的股票代码只是作者的说法，附加它会将未经验证的断言引入该股票代码的上下文中。

公开数据——无需密钥

• SEC EDGAR：申报文件及其文本、XBRL 财务报表、Form 4 内部人士交易、8-K Item 2.02 和 6-K 业绩公告（公告日数据直接从申报文件中读取）、股票代码和公司列表。
• US Treasury：每日平价收益率曲线。

所有来源、数据收集方式及其条款均列于**docs/data-sources.md**。供应商条款与代码许可证相互独立；请参阅已知限制。

搜索

新闻搜索在读者搜索的所有位置都以两种方式同时生效——新闻筛选框、“搜索全部”和 Agent 的 news_search 工具：

• 按词语搜索——服务端和浏览器共用一套规则：按顺序匹配完整单词，将复数匹配到单数，大小写形式的股票代码必须完全匹配，并且查询中提到某家公司时，也会找到带有该公司标签的报道（搜索“robinhood”会找到带有 HOOD 标签的报道）。

• 按含义搜索——如果报道标题与查询的含义相近，就会将其加入结果并标记为相关，因此搜索“AI 数据中心支出”会找到“Equinix 计划每年投入 50 亿至 70 亿美元建设数据中心”，即使两者没有共同短语。此功能使用 Qwen3-Embedding-0.6B（Apache 2.0），在服务内部可自托管：文本不会离开 AlphaDesk，也不需要模型密钥。标题会在到达时嵌入一次；阈值（余弦相似度 0.50）经过校准，只会加入主题相关的报道。结果仍按时间倒序排列。

  嵌入任务不会与网站争抢资源：模型只使用一个 CPU 线程运行，后台工作进程以最低操作系统优先级运行，并且只会在没有请求处理时进行嵌入。搜索耗时约三分之一秒。

币种的新闻面板会读取所有加密货币及其影响因素——任意币种的报道、加密货币股票、提及加密货币的报道，以及美联储和利率相关标题——每条都会标明收录原因。每 5 分钟进行一次的新闻轮询也会按名称向信息流请求带有主要币种标签的报道，因为加密货币在所有最新报道中占比很小。信息流会将币种写作 BTCUSD；对于账户交易的币种和固定列表中的大型币种，页面和 Agent 的新闻工具都会将这些标签显示为 BTC-USD，与行情板的写法一致。

---

加密货币

加密货币数据仅来自 Alpaca：交易在 Alpaca 上进行，因此只有它提供的币种和市场数据才是依据。这里没有全球市值排序或成交量排名。

• 搜索范围取决于账户。 连接的 Alpaca 账户可以交易的每个加密货币交易对都可以搜索和查看图表，包括对稳定币或比特币的交易对（BAT-USDC、ETH-BTC）；账户不支持的币种不会显示。SEC 股票代码文件中缺少的资产（QQQ、TLT、VOO 等许多资产）会从账户自己的资产列表中补充，每小时在后台加载一次，因此服务启动后的首次搜索暂时不会包含这些资产。
• 加密货币涨跌榜仅列出美元交易对（稳定币和比特币交易对是以另一种方式计价的同一批币种）。活跃度按 Alpaca 交易场所的美元成交额排名（价格乘以币数）；稳定币（USDT、USDC、USDG）会显示在“全部”下，但不会显示在“活跃”“涨幅榜”或“跌幅榜”下。如果某币种的最近一笔交易已过时，其价格会采用实时买卖报价中间价；如果 24 小时前的 6 小时内没有起始价格，则 24 小时涨跌幅会显示为短横线。成交量和流动性数据来自 Alpaca 自己的交易场所，该场所流动性较薄；对应列会注明这一点。
• 验证方式。 登录后，/api/crypto/tradable 会列出账户可以交易的币种和交易对；/api/crypto/check 会测试每个交易对是否支持搜索、价格柱以及是否出现在涨跌榜中。
• 币种图表的实时边缘采用实际成交数据（买卖报价中间价每秒会变动多次，会导致图表抖动），并且只额外获取一天的价格柱，而不是像股票那样获取三天以涵盖周末。

---

Agent 访问（MCP）

AlphaDesk 通过 Model Context Protocol 在 /api/agent/tools/mcp 提供与界面相同的记录，共 53 个只读工具。每次调用都以读者身份使用其密钥，并限制为每个令牌每分钟 120 个请求。

连接

• Claude.ai、ChatGPT — 添加自定义连接器并填写服务地址，然后按提示登录（使用带 PKCE 的 OAuth 2.1；每个已注册应用同时只能有一个有效授权）。
• Claude Code、Codex、Cursor、opencode — 在侧边栏中 Account 旁的 Agent access 页面创建令牌（令牌仅显示一次、以哈希形式存储，可立即撤销）；该页面会提供每个客户端的具体配置，以及一个用于通过下方数据 API 编写自有程序的选项卡。

工具

用途	工具
今日	market_today、index_board、movers（股票、ETF、指数、加密货币、货币、期权、债券）、sector_performance、sector_breadth
读者关注的名称	my_board、quotes、baskets、find_symbol
单家公司	quote（含订单簿）、key_stats、company_profile（含股数及其依据）、fund_profile、analyst_view、financial_statements、filed_report、earnings_history、symbol_events、ownership、insider_activity、peers、compare_metrics、related_funds
股价变动原因及后续走势	what_moved（大幅波动日，以及每次波动前出现的新闻和文件）、move_state（涨势是延续、消退还是反转）、priced_in（过往对报告的反应、报告前的走势、分析师目标价）、candidates（可能在下一个交易时段推动股价变动的附日期原因——周五晚间和周末的结果对应周一）、movers_in_context（附有相关新闻、文件和走势的涨跌幅榜）、news_scan（按名称分组的新闻时段）、related_assets（公司自身文件中与其相关的资产，例如其持有的代币）、entry_facts（建仓前查看点差、流动性、可交易性、价位和风险——只读，绝不会下单）
价格	price_history、price_chart
新闻	symbol_news、news_search、news_story、news_scan
文件和电话会议	list_filings、filing_text、transcripts、transcript_text
日历	earnings_calendar（即将发布的业绩，以及使用 days_back 查询已发布的业绩）、economic_calendar、corporate_calendar
期权	option_expirations、option_chain、options_flow；option_chain(on=…) 会读取指定历史日期收盘时的期权链（该看板涵盖的股票数据自 2026-10-07 起在每次收盘后保存；如果未指定到期日，则列出该日保存的到期日）
刚刚发生的事件	catalysts（将文件、停牌、政府行动和社交帖子汇集在同一时间线上）、filing_feed、trading_halts、government_actions、social_posts
历史交易时段	使用 movers(session=…) 查询股票、ETF、加密货币和期权，并通过 market_sessions(category=…) 查询已有数据的日期；优先读取记录的收盘数据。若公司事件导致大幅波动，会添加标记：来自 Alpaca 公司行动信息流的分拆事件会计入持有者的变动（母公司股票加上获配的新股）；若没有列出的事件，但走势呈现事件特征（成交量达到平均值的十倍，且次日收盘价变动不超过 15％），则会标记为 possible_corporate_event
数据溯源	data_sources——标明数据来自授权供应商还是抓取的页面

全天候价格。 常规交易时段以外，报价和涨跌幅榜条目会采用最新的可用成交价：盘后交易期间采用截至纽约时间晚上 8 点的价格，之后采用隔夜交易场所的价格，直到凌晨 4 点（标记为 overnight，来源为 "overnight venue"），随后采用盘前价格。涨跌幅以已收盘交易时段的收盘价为基准，成交时间记录在 as_of（报价）或 extended_at（涨跌幅榜）中。成交量仍为已收盘交易时段的数据。隔夜期间，买价和卖价仍是常规交易所晚间的订单簿数据，因此此时读取的点差不可靠。

并非市场报价的报价。 如果某个代码在过去十天内没有日线数据——例如已退市代码或长期停牌的股票——其报价会带有 stale: true：价格为最近一次成交价，as_of 为该成交日期，且不显示涨跌幅。公司可能已使用新代码交易；可通过 find_symbol 查找。 哪些地址。 工具只会响应服务器配置为可响应的名称：ALPHADESK_BASE_URL 中的公共地址，以及 ALPHADESK_ALLOWED_HOSTS 中的名称（逗号分隔的列表）。不在该列表中的主机将被拒绝。在 Cloud Run 上，同一服务通过两个地址提供服务，请将第二个地址放入 ALPHADESK_ALLOWED_HOSTS。

提供数据，而非结论。 工具返回数值和纯事实标记——例如变动幅度、一次涨跌中回吐了多少，以及一则报道是关于该名称本身还是仅仅提到了它——绝不会给出分数、评级或建议。每条回复都会说明哪些内容无法读取（unavailable、reliable），拒绝请求时也会说明原因：没有密钥、套餐不包含相关数据，或已连接的供应商根本没有该公司的数据（小公司通常没有分析师覆盖）。读者的价格套餐会在 data_freshness 中说明：免费套餐的数据量仅来自一家交易所，会低估整个市场。

适用于加密货币 Agent 的精简工具列表。 完整列表包含 53 个工具，每次连接都会带上约 66,000 个字符的描述。发送请求头 X-Agent-Toolset: crypto，则只会列出适用于加密货币的 17 个工具（约 28,000 个字符）；未列出的工具仍可按名称调用并获得响应。代币写作 BTC-USD；也接受 BTC/USD 和 BTCUSD，但单独的 BTC 表示上市基金。带有价格或可交易标记的回复（quote、quotes、movers、price_history、price_chart、entry_facts）都包含 data_venue，即这些数据来自哪个经纪商（目前为 alpaca；若无法确定则为 unknown），这样使用某家经纪商进行交易的 Agent 就能知道自己读取的是哪个市场的数据。每个 token 每分钟最多可以调用 120 次；设置 ALPHADESK_AGENT_RATE_PER_MIN 可更改此限制。

监测 Agent 的使用情况。 每次工具调用都会记录：工具、参数、耗时，以及调用结果（已回答、无结果、不完整或失败，以及原因）。调用方可以添加请求头 X-Agent-Task（同一个问题的所有调用共用一个 ID）和 X-Agent-Intent（用一行描述问题），还可以通过向同一地址发送一条小型 JSON 消息来说明结果是否有帮助：将 /mcp 替换为 /feedback，并使用相同的 token：{"tool": "what_moved", "useful": "yes" | "partly" | "no", "note": "…", "missing": "…"}。这是 Agent 接口上唯一的写入操作，写入的内容只会进入使用日志，不会影响其他内容。运行 python -m alphadesk.main agent-usage --days 30 查看报告；登录后也可以访问 /api/agent/usage?days=30：查看哪些工具从未被调用、哪些工具返回空结果或调用失败、哪些工具响应缓慢（以及最慢的 20 次单独调用，包括每次的时间、工具、参数和耗时）、哪些调用链反复出现（表明某个工具应该存在），以及 Agent 表示缺少哪些内容。日志绝不会保存 token、密钥、Agent 的推理过程或最终答案。

亲自试用工具。 scripts/agent_probe.py 会像 Agent 一样登录（使用保存在 ~/.alphadesk-agent-token 中的 token），并打印主要工具针对某个代码的返回结果：python scripts/agent_probe.py NVDA。通过 ALPHADESK_PROBE_URL 可将其指向其他服务器。它只会读取数据。

这些工具专为看不到屏幕的 Agent 编写：find_symbol 根据 SEC 列表将名称解析为股票代码，而不是让 Agent 自行猜测；price_chart 返回经过精简的序列，并为每个数据点提供 RSI 和 MACD；filing_text 和 transcript_text 分页返回完整文档；news_search 会将每则报道标记为关键词匹配或含义匹配。返回出版方或申报方文本的工具会注明这些内容是不可信输入。每个工具都带有 readOnlyHint，因此客户端可以直接调用，无需为每次读取单独征求许可。 与普通 HTTP API 相同的工具。 对于不是 Agent 的程序——交易机器人、导入器等——这些工具也以 /api/v1 下的 GET 端点形式提供，使用相同的令牌、相同的每位读取者密钥和相同的限制，此外还提供所有价格历史数据柱（Agent 工具会对其进行精简），按时间分页，并可选提供允许使用令牌的地址列表。它是只读的，采用轮询而非流式传输：请参阅 docs/rest-api.md。

---

账户、安全与隐私

• 登录：每个服务仅有一位用户。唯一的入口是运营者在设置中配置的电子邮件和密码（使用密码哈希的 ALPHADESK_LOGIN_EMAIL）；没有注册功能，也不支持第三方登录（Google、GitHub 和 Microsoft 登录已于 2026-10-03 移除）。任何其他账户都会被拒绝。
• 会话：使用 HMAC 签名的 Cookie，有效期 14 天，可在所有设备上退出登录。
• 供应商密钥：使用存放在数据库之外的主密钥，通过 AES-256-GCM 为每位读取者单独加密；绝不记录日志，输入后也绝不再次显示。密钥离开的唯一途径，是读取者在账户页面自行下载导出密钥：这是一个纯文本文件（不设密码短语，由所有者于 2026-10-02 自行选择，因此持有该文件的人就持有这些密钥），仅在其自己的浏览器会话中可用——绝不会提供给 Agent 令牌或 OAuth 授权；须在过去 10 分钟内登录，每小时最多下载 5 次，并只记录次数，不记录内容。发送到该路由的密码短语仍会用于加密文件（scrypt 和 AES-256-GCM，至少 12 个字符）。
• Agent 凭据：令牌和 OAuth 代码以 SHA-256 哈希形式存储；OAuth 客户端经过加密；同意页面经过签名，仅限同站访问且无法嵌入框架。
• 保留期限——以下为默认值，均可通过 ALPHADESK_KEEP_DATA 延长：快讯 7 天，完整文章正文 72 小时，语义向量与对应快讯同期限，公司公告在报告发布后保留 30 天，预测日志 120 天，发布习惯 3 天，新闻稿检查结果 24 小时，以及供应商更新较慢的答案缓存副本（历史数据、基本面、档案、评级、日历）14 天。这些副本可让服务重启后快速恢复、减少供应商速率限制的占用，并在供应商宕机时提供答案；实时答案（报价、涨跌幅榜、逐笔行情、日内图表尾部数据）绝不保留。 已记录的交易时段收盘数据——每个已结束交易时段的全市场日线数据柱，每个压缩后的时段约 200 KB——无论保留设置如何，都会永久保留（只有设置 ALPHADESK_PURGE_ON_KEY_REMOVAL 或删除账户才会移除）：已结束的交易时段不会再变化，而这些记录是过去时段涨跌幅榜正常工作的保障。 移除密钥后，已获取的数据仍会保留，除非设置了 ALPHADESK_PURGE_ON_KEY_REMOVAL。
• 删除：读取者可以删除自己的账户，确认时需输入其电子邮件；所有与该账户关联的行都会在一个事务中移除。测试套件会根据架构核对表清单。
• 不使用分析、广告或跟踪。

完整的账户、会话、密钥库和 Agent 凭据设计见 docs/hosted-mode.md。

---

架构

                       ┌──────────────────────────────────────────────┐
  Browser (React SPA) ─┤  FastAPI · one process · one port            │
  Reader's agent (MCP) ┤                                              │
  Your own bot (HTTP) ─┤                                              │
                       │  /api/*  ── panels, composed per request     │
                       │  /api/agent/tools/mcp ── 53 read-only tools  │
                       │  /api/v1 ── the same tools, GET only, HTTP   │
                       │  OAuth 2.1 at the root (/authorize, /token…) │
                       │                                              │
                       │  Per-reader DataRouter ──► reader's vendors  │──► Alpaca · FMP · Polygon
                       │    (ordered per panel; 428 when none carry)  │    Finnhub · Alpha Vantage
                       │  Background:                                 │
                       │    news poll (5 min) + held news sockets     │──► each reader's feeds
                       │    EDGAR results sweep (15 min, weekdays)    │──► SEC EDGAR
                       │    daily earnings forecast capture           │──► Treasury
                       │    embedding worker (search by meaning)      │
                       └──────────────┬───────────────────────────────┘
                                      │
                         Postgres (Cloud SQL) in production
                         SQLite (WAL) in development

后端 — Python 3.11+。使用 FastAPI，处理器以同步方式运行于包含 40 个工作线程的线程池中，并为每个上游服务明确设置套接字截止时间。提供方采用结构化 Protocol（NewsProvider、PriceProvider、TranscriptProvider），根据每位读者密封的密钥构建，并可通过入口点发现。请求中的读者身份通过上下文变量传递；后台线程会有意不继承该身份。存储层在本地使用 SQLite，在生产环境中通过纯 Python pg8000 驱动连接 Postgres。嵌入模型通过 sentence-transformers 和 PyTorch 的 CPU 版本在进程内使用 CPU 运行。

前端 — 使用 TypeScript、React 19 和 Vite，构建为由 Python 进程提供的静态文件。Tailwind CSS v4 提供设计令牌（根字号 14 像素、间距网格 4 像素、六种字体角色，支持浅色和深色主题）。TanStack Query 为每个端点共享一个查询。没有组件库，也没有图表库：基础组件均为手工编写，图表则是 AlphaDesk 自有的 SVG 渲染器，蜡烛图分批绘制为四条路径，因此节点数量不会随柱数变化。

---

仓库布局

alphadesk/
  main.py            entry point: web server + background loops, and the CLI
  app/               FastAPI app, auth, admin, agent access (tokens, OAuth, MCP mount), the plain-HTTP data API (rest_data.py)
  providers/         the plugin seams, vendor implementations, catalogue, per-reader router
  ingest/            EDGAR, news polling, calendars, movers, recorded session closes, prices and indicator math
  desk/              screener window, filings, transcripts, market-today
  ledger/            store (SQLite / Postgres), database adapter, key vault and the sealed key export
  mcp_server.py      the agent tools
  semantic.py        search by meaning (self-hosted embedding model)
  cryptonews.py      a coin's news selection, and the feed's coin tags written as the board writes them
  cryptocheck.py     the check that every crypto pair is searchable, has bars and reaches the movers
  newsquery.py       the word-search rule
  config.py          settings, retention, curated baskets
  ui/                React 19 + Vite frontend (built into app/static)
  deploy/            deployment guide and the configuration template
docs/                data sources, providers, widgets, hosted mode
scripts/deploy.sh    build on Cloud Build and roll the Cloud Run service
tests/               pytest suite

---

开发

前置条件

• Python 3.11+、安装了 pnpm 的 Node
• 包含真实联系信息的 SEC User-Agent 字符串（SEC 要求提供）
• 除 EDGAR 和 Treasury 外，使用任何服务都需要你自己的供应商密钥
• 嵌入模型约需 1.5 GB 磁盘空间，仅在使用 search extra 时需要；首次使用时下载（或设置 ALPHADESK_SEMANTIC_SEARCH=off）

设置并运行

pip install -r requirements.txt
cp alphadesk/deploy/env.example .env        # then edit: vault key, SEC user agent
python -m alphadesk.main dashboard          # API + built SPA on http://127.0.0.1:8000

生成保险库密钥（32 个随机字节，base64）：

python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

如需在本地开发时不登录，请设置 ALPHADESK_AUTH=off（一个本地账户），将你自己的供应商密钥放入 .env，并将其密封到该账户中：

python -m alphadesk.main keys import-env

前端热重载（将 /api 代理到正在运行的服务）：

cd alphadesk/ui && pnpm install && pnpm dev

命令行

命令	用途
python -m alphadesk.main dashboard	Web 服务和后台循环
python -m alphadesk.main keys import-env	开发用途：将 .env 中的供应商密钥密封到本地账户
python -m alphadesk.main keys decrypt FILE	打印从账户页面导出的文件中的密钥（会提示输入其密码短语）
python -m alphadesk.main keys import-file FILE	将导出文件中的密钥密封到本地账户，并使用此实例自己的保险库密钥
python -m alphadesk.main earnings	标记今天的 EDGAR 业绩公告，并列出最近三天的公告
python -m alphadesk.main backfill --hours 72	回填 EDGAR 业绩公告
python -m alphadesk.main calendar-accuracy --days 30	根据 EDGAR 公告日期评估日历供应商
python -m alphadesk.main mcp [--http]	独立运行的 Agent 工具（仅 EDGAR — 无读者身份）
python -m alphadesk.main init --email [email protected] [--like-cloud]	首次设置：保险库密钥、SEC 联系方式和设置文件。--like-cloud 会配置 Postgres 并创建登录账户（提示设置密码），而非使用免登录模式
python -m alphadesk.main hash-password	为 ALPHADESK_LOGIN_PASSWORD_HASH 生成密码哈希（会提示输入密码）

扩展

• 提供方：实现一个 Protocol，并通过本地模块 （ALPHADESK_PLUGINS）或 alphadesk.providers 入口点注册 — docs/providers.md。
• 仪表板磁贴：在 ui/src/widgets/ 中注册一个组件，或通过外部 JSON 后端提供磁贴（ALPHADESK_WIDGET_BACKENDS）— docs/widgets.md。
• 了解这是否适合你，以及它与其他方案的比较： docs/comparison.md。了解为何数据使用你自己的密钥： docs/your-own-keys.md。
• 约定和检查：CONTRIBUTING.md；决策规则以及尝试过又撤销的内容：DECISIONS.md；报告漏洞：SECURITY.md。

---

配置参考

环境变量（也会从 .env 读取）。只有前两项是必需的。

变量	用途
ALPHADESK_VAULT_KEY	必需。 32 字节的 base64 值：用于加密每位用户的密钥。丢失后将无法读取这些密钥
SEC_USER_AGENT	必需。 按 SEC 要求，提供包含联系信息的描述性 User-Agent
ALPHADESK_DATABASE_URL	Postgres 连接字符串；未设置时使用 ALPHADESK_DATA 中的 SQLite
ALPHADESK_DATA	SQLite 数据目录（默认值：~/.alphadesk）
ALPHADESK_AUTH	对于不需要登录的单一本地账户，设为 off
ALPHADESK_ACCESS_TOKEN	关闭登录时，用于保护浏览器的共享密钥（至少 16 个字符）；账户访问受限时会忽略此项
ALPHADESK_LOCAL_USER_EMAIL	关闭登录时，使用此现有账户，而不是新建本地账户——适用于从多账户服务转为个人自用的服务器；不会迁移任何内容
ALPHADESK_OAUTH_REDIRECT_HOSTS	可选：只有这些地址（及其子域名）可以接收 Claude.ai 或 ChatGPT 连接器授权，多个地址以逗号分隔；其他地址会在授权页面被拒绝。未设置时，任何地址都可以；页面会优先显示该地址，并在地址无法识别时发出警告
ALPHADESK_ALLOWED_HOSTS	服务器会响应的其他主机名。关闭登录且未设置访问令牌时，服务器只会响应 localhost、127.0.0.1 和 [::1]（因此网页无法通过重新绑定自身名称来访问它）；请以逗号分隔的形式列出访问服务器时使用的其他名称。ALPHADESK_BASE_URL 中的主机名也会被允许
ALPHADESK_AGENT_RATE_PER_MIN	每个 Agent 令牌每分钟可发出的调用次数（默认值：120）
ALPHADESK_AGENT_HEAVY_CONCURRENCY	可同时运行的重型 Agent 工具（what_moved、related_assets、news_search、movers_in_context、candidates、earnings_calendar、entry_facts、options_flow、priced_in、analyst_view）数量；超出的调用会排队等待，不会被拒绝（默认值：2）
ALPHADESK_KEEP_DATA	设为 forever 或天数：将记录（新闻及其文本、公告、预测日志、抓取的页面）保留指定时长，而不是采用 3 至 120 天的默认期限；如果存储中的数据更少，还会进一步补充数据（保存密钥时会补齐 30 天数据，“Load older”会回溯 30 天，查询某个代码时会回溯一年）。此项只会延长默认期限。你仍须遵守供应商自身关于数据存储的条款；此设置不会更改这些条款
NEWS_BACKFILL_DAYS	保存密钥时补齐的天数（默认值：保留期限；设置 ALPHADESK_KEEP_DATA 时为 30 天，且不超过 365 天）
ALPHADESK_SKIP_KEY_CHECK	设为 1，保存新闻密钥时不先向供应商验证（离线）
ALPHADESK_PURGE_OTHER_ACCOUNTS	维护操作：设为 count 可记录除当前登录账户外的账户数量；设为 delete 会在下次启动时彻底删除这些账户（之后请取消设置）
ALPHADESK_PURGE_ON_KEY_REMOVAL	设为 1，移除密钥时删除供应商存储的数据（适用于服务其他用户且供应商条款要求如此的实例）；默认关闭
ALPHADESK_BASE_URL	公共 URL；OAuth 重定向和 Agent 主机允许列表依赖此项
ALPHADESK_SECRET	会话签名密钥
ALPHADESK_COOKIE_SECURE	使用安全 Cookie（在 HTTPS 后方运行时启用）
ALPHADESK_SEMANTIC_SEARCH	设为 off 可禁用语义搜索
ALPHADESK_EMBED_MODEL / ALPHADESK_SEMANTIC_THRESHOLD	嵌入模型（默认值：Qwen/Qwen3-Embedding-0.6B）和相似度阈值（0.50）
ALPHADESK_PLUGINS / ALPHADESK_WIDGET_BACKENDS	提供方插件；外部图块后端
NEWS_REFRESH_MINUTES / NEWS_LOOKBACK_HOURS / NEWS_KEEP_DAYS	新闻轮询间隔（5 分钟）、回溯窗口（72 小时）、保留期限（7 天）
CHART_MIN_COVERAGE / CHART_MAX_MEDIAN_GAP_MIN	指标覆盖率门槛
DASHBOARD_HOST / DASHBOARD_PORT	Web 服务器绑定设置（Cloud Run 会注入 PORT）
MCP_HOST / MCP_PORT	独立 Agent 服务绑定设置（默认端口：8010）

带注释的完整模板位于 alphadesk/deploy/env.example；每项设置的默认值均定义在 alphadesk/config.py 中。

生产部署与运维

参考服务运行在 Google Cloud Run（alphadesk，us-east4）， 并使用 Cloud SQL for Postgres。

设置	值	原因
规格	2 vCPU，4 GiB	嵌入模型与 Web 服务器共用实例
实例数	恰好 1 个（min = max = 1）	后台循环和实时套接字需要一个写入方
CPU	始终分配，启动加速	后台循环会在请求之间运行
镜像	Python 3.12 slim、PyTorch CPU 版本，模型预先打包在镜像中（约 1.2 GB）	启动时无需下载；模型几秒内即可加载

部署——持续集成会在每个拉取请求上运行测试、lint 和构建；部署仍由维护者执行。合并到 main 后：

scripts/deploy.sh

脚本会检查当前检出是否为干净的 main，且与远程分支一致，否则拒绝执行；它会在 Cloud Build 上构建镜像，仅使用新镜像更新服务（环境、数据库挂载和扩缩容设置均不变），并检查线上页面是否提供了新版本。前端构建产物已提交到 alphadesk/app/static，因此镜像无需执行 Node 构建步骤。

运维

• 日志：在 Cloud Logging 中查看 alphadesk 服务的日志；数据摄取循环、清理任务和嵌入工作进程都会在此记录进度。

• 如果请求停滞。 根据请求日志进行测量，并忽略每个版本的前五分钟：每次部署都会冷启动。目前观察到的停滞发生在使用 15 至 25 分钟后，此时内存使用率从约 35% 升至 4 GiB 容量的 80% 以上。以下三项措施避免了停滞：实时流每组只通过一条消息订阅；后台面板刷新每次运行 15 个面板，并设有暂停（只有前五分钟会以全速运行）；每次插入时都会从缓存中移除过期的价格答案。如果内存使用率再次超过约 75%，请通过 gcloud run services update alphadesk --region us-east4 --memory 8Gi 提高内存（此操作只会更改内存）。

• 按当前构建方式，服务必须始终运行；此规格下服务的费用约为每月 $110–120（另加 Cloud SQL 费用）。降低成本应选择更小的嵌入模型，而不是将实例数缩减到零。

• 优雅关停有时间限制：一个修订版本会在几秒内停止。

• 语义搜索紧急开关。 如果服务变慢或拒绝请求，可在不重新构建的情况下将其关闭——搜索会退回到仅使用关键词：

  gcloud run services update alphadesk --region us-east4 --update-env-vars ALPHADESK_SEMANTIC_SEARCH=off
  

  始终使用 --update-env-vars（添加或更改单个变量），切勿使用 --set-env-vars（替换所有变量）。工作进程的启动日志会报告机器声明的核心数，以及模型使用的线程数 （预期为 1）。

• 后台工作发布时默认关闭，之后再启用并监控。 2-vCPU 容器报告的核心数多于实际数量，因此在多核笔记本电脑上的表现不能预测生产环境：曾经根据报告的核心数设置线程数，导致实时实例的 Web 服务器资源耗尽。

---

测试与质量

检查项	命令	范围
后端测试	python -m pytest -q	约 720 项测试：提供方、日历、EDGAR 解析、新闻规则、搜索、Agent 工具、身份验证、账户、保留策略
前端测试	cd alphadesk/ui && pnpm test	src/lib/__tests__ 下的纯逻辑测试（图表刻度、会话、新闻匹配、布局）
类型检查与构建	cd alphadesk/ui && pnpm build	tsc -b（项目引用——此处 tsc --noEmit 不会检查任何内容），然后运行 Vite
Lint	python -m ruff check alphadesk	Python

---

已知限制

• 供应商条款。 市场数据通过你自己的密钥获取，并受你与各供应商签订的协议约束；这些条款决定了你可以如何使用数据。各套餐有所不同——有些仅供个人使用，有些会限制向他人展示数据或存储数据——因此，在托管或共享环境中使用 AlphaDesk 前，请先查看你的套餐。各供应商的条款链接见 docs/data-sources.md。
• 未经测试的路径。 部分付费套餐功能（Alpha Vantage、Finnhub 高级版、Polygon 付费版）是根据文档开发的，尚未使用有效密钥进行测试。
• 按含义搜索仅处理新闻标题（处理摘要每天每位读者要耗费数小时 CPU 时间）；新部署会先为已存储的历史数据生成嵌入，然后旧新闻才能按含义匹配。
• 法律页面仍是草案，尚待法律顾问审阅。

---

历史

AlphaDesk 通过做减法，成为一款数据消费终端。筛选器排名、由运营人员持有的数据和非官方来源、应用内 Agent 以及应用内大模型都已逐一移除，每项调整都有经过衡量或明确说明的原因——详见 DECISIONS.md。唯一保留的模型是用于搜索的可自托管嵌入模型。

---

许可证

AlphaDesk 采用双重许可。版权所有 © 2026 Vignesh Murugan。

开源 — GNU AGPL-3.0（LICENSE）。你可以使用、研究、修改和再分发 AlphaDesk。AGPL 是一种强著作权传染许可，与 GPL 相比多了一项条款：如果你运行修改过的副本，并让他人通过网络使用，你必须向这些用户提供你所用版本的完整源代码，且遵循相同的许可证。无论是否修改，分发副本时也必须附带源代码。仅供自己使用则没有任何此类义务。

商业许可证。 对于希望将 AlphaDesk 嵌入专有产品、运行修改后的托管服务但不公开修改内容，或需要企业例外条款的组织，可申请商业许可证——请联系 [email protected]。托管云服务依据其自身服务条款提供；订阅者不承担 AGPL 义务。

贡献按贡献者许可协议接受，以便项目继续提供这两种许可证；贡献者保留其作品的版权。

依赖项均采用宽松许可证（MIT、ISC、BSD、Apache 2.0），且不得添加任何著作权传染型依赖项，否则将无法提供商业许可证。每次构建都会根据软件包中实际包含的内容生成 Web 界面的第三方声明文件，路径为 /third-party-notices.txt（字体采用 SIL Open Font License）。嵌入模型 Qwen3-Embedding-0.6B 采用 Apache 2.0 许可证。

数据不是代码。 代码许可证不授予任何市场数据权利。通过你的密钥获取的数据受各供应商的条款约束；请参阅 docs/data-sources.md。