FolioMind

FolioMind 是一个面向 Windows 和 macOS 的开源金融研究 Agent。产品以自选股为入口，把行情、投资组合、个股盯盘、金融 Skills 与可审计对话放在同一工作台中。它是独立的社区项目，不代表任何数据服务商；QVeris 只是内置的可选数据能力适配器。

当前能力

• 自选股分组、分组筛选与按名称/最新价/涨跌幅排序；侧栏支持按名称、代码、分类、市场和分组即时搜索，筛选只作用于本地视图并显示命中数量；自定义顺序下可用行级上移/下移操作整理同组标的，顺序会通过 canonical Host 持久化并在 Web/桌面端保持一致；内置标的目录只提供搜索元数据，缺失行情始终保持为空，绝不回退静态价格；侧栏会显示真实报价的新鲜度、来源和交易所时区；长名称会安全省略并保留完整悬浮提示；未知市场使用明确的 UTC 参考而不会猜测本地时区；支持 FolioMind CSV/TradingView 风格 TXT 的批量导入导出。
• 投资组合持仓、成本、市值、未实现盈亏与行情覆盖率。
• 组合盘后复盘快照：保存真实行情覆盖、组合盈亏、风险信号和未来 7 天已返回事件，可展开回顾并随本地备份迁移。
• 组合风险洞察在已有真实历史序列上展示加权样本波动、平均相关性、有效配对数和历史覆盖率；序列不足时保持空值，结果明确标注未年化，不生成综合风险评分。
• 组合占比、行情覆盖和成本暴露使用无方向百分比显示，涨跌与盈亏仍保留正负号，避免将覆盖率误读为收益。
• 持仓可选配置止盈/止损价；真实行情到价后按边沿去重生成站内/系统提醒，不执行自动交易。
• 过期行情仍保留来源与时间用于查看，但不会触发新的组合止盈/止损或行情类盯盘提醒；刷新拿到新鲜数据后才会重新评估。
• 持仓可建立交易计划档案（买入逻辑、计划周期、目标/止损价），支持执行/重新跟踪、操作留痕和真实价格距离提示。
• 组合明细支持按名称、代码、市场或买入逻辑搜索，并按交易计划状态筛选；筛选仅改变视图，不修改持仓。
• 组合支持导入 FolioMind 导出报告或最小字段 CSV；导入会先完整校验并展示预览，确认后才提交，重复代码更新原持仓，运行时行情字段不会进入本地状态。
• 个股盯盘规则、事件时间线和开关状态。
• 盯盘规则支持单个标的或整个自选组；自选组会跟随当前自选动态检查，并按标的独立触发去重。
• 盯盘规则中心支持按条件/标的搜索、运行状态筛选和最近活动/条件名称/运行状态排序；已有规则可原地编辑，修改会保留审计时间线并重新建立触发边沿。
• 盯盘规则支持边沿触发或单次触发，并可设置有效期；单次触发或到期后自动停用，避免重复提醒和不必要的数据请求。
• 股票详情页支持一键收藏/取消收藏，更多菜单可刷新行情、查看证据、打开盯盘或复制证券代码。
• Agent 输入框提供最新行情、公司事件和风险核验快捷指令，选择后可编辑再发送。
• 生产渲染异常时显示安全恢复界面，可重试或重新加载，不暴露错误正文或清理用户数据。
• 公司事件日历：按自选标的展示未来 90 天真实分红、拆股、股东会和财报日期，支持列表/月视图、月份导航、范围筛选、关键词搜索和来源追溯；无数据时保持明确空态。
• 公司事件提醒：真实事件进入未来 7 天窗口时提供一次提前提醒，事件当天再提醒一次；按事件和阶段幂等去重，并支持站内/系统通知。
• 盯盘告警按触发边沿去重：条件持续成立时不重复刷屏，恢复后再次触发才生成新消息。
• 盯盘消息支持可选的系统通知；用户主动授权后，桌面端和 localhost 调试页可选择接收全部提醒或仅关键提醒，普通消息始终保留在站内；消息中心支持清理已读和导出当前筛选 CSV，未读提醒不会被清理。
• 盯盘规则中心支持一键全部暂停/全部启用；批量保存失败会精确回滚，不覆盖期间发生的其它规则编辑。
• 盯盘条件支持涨跌幅与价格水平（大于等于/小于等于）告警，缺失真实价格时保持待核实。
• 桌面端与本地 Web Host 均支持按间隔执行真实盯盘检查；普通浏览器预览不会伪造检查结果。
• 市场行情总览与跨市场自选列表，缺失数据保持为空；支持核心估值、交易盘面、完整字段和自定义命名行情视图。
• 市场页顶部行情概览卡支持鼠标、Enter 和空格快捷进入标的详情；缺失涨跌幅保持中性，不误显示方向。
• 行情图表在渲染前会统一时间戳、排序并去重，过滤无效点；缺失 OHLC 时保持真实空值并安全降级为面积图，避免异常数据导致白屏。
• 行情图表设置支持独立显示 MA5/MA20 趋势线；指标只基于已返回的真实序列计算，窗口不足时保持不绘制。
• 行情图表支持十字光标悬浮明细：按标的交易所时区显示完整日期时间、K 线 OHLC/面积图价格和可用 MA5/MA20；未知市场明确使用 UTC，不会残留旧点位。
• 行情响应会拒绝 null/空字符串和零或负数价格；缺失涨跌幅保持空值，不会被隐式转换为 0 参与方向、宽度或组合统计。
• 设置页支持实时、均衡、手动三种行情自动刷新策略；策略只保存在当前 WebView，手动模式停止后台行情轮询但保留显式刷新，帮助在实时性与 QVeris 调用成本之间取舍。
• 市场页提供自选市场宽度概览：仅用真实报价统计上涨、下跌、平盘、最大涨幅和最大跌幅；缺失行情不会参与计算。
• 异动雷达支持按需发起真实证据解读：聚合新闻、公司事件和资金流 CAP，诱因必须关联来源；证据不足时保持空态，不猜测原因。
• 研究筛选工作台：按名称、代码、市场、涨跌方向及行情覆盖筛选自选标的，估值字段缺失时保持为空。
• 研究筛选支持涨跌幅、PE、PB、成交量等真实数值条件，可与文本/方向筛选组合并保存最多 10 个本地命名预设；缺失字段不会被猜测或补值。
• 跨市场标识使用显式 token 边界识别；未知市场不会被静默当作 A 股，数据参数和自动复盘交易日历会安全拒绝无法确认的交易所。
• 行情卡提供统一“来源与证据”抽屉，展示渠道、Provider、能力、新鲜度、截至时间和字段覆盖；缺失字段保持为空，并可独立重试当前标的。
• 组合风险洞察：基于真实现价提示集中度、行情覆盖和未计价成本；没有足够历史序列时不会虚构波动率或相关性。
• Skill 市场及安装状态管理；安装/取消安装会持久化到当前 Host，刷新、重启和备份迁移后保持。
• FolioMind Agent 对话支持逐步显示 Pi 流式回答，可在应用内停止正在运行的分析，并以安全的 Markdown 展示标题、列表、表格、代码和来源链接，同时保留工具调用记录、数据截至时间与免责声明。
• Tauri 2 Rust Host 管理 pi --mode rpc JSONL 子进程。
• 固定并校验 Pi 0.84.2，桌面构建自动下载对应 Windows/macOS Runtime 并随安装包分发。
• Run-scoped 数据执行桥，只向 Pi 暴露固定金融 CAP，以及明确授权的 Search、Inspect、Call 发现能力。
• 内置金融研究 Skill；行情页面默认直连 QVeris CAP 的 qveris_finance 能力（MKT.L1.RT、REF.COMPANY_PROFILE、FUNDAMENTALS.DERIVED_RATIOS、MKT.BARS.EOD），本地保存稳定的 tool schema，只有明确的能力缺失才回退 Search → Inspect → Call；认证、限流、超时和服务端错误不会追加发现调用。QVeris 适配器可替换为兼容的自托管服务。
• 设置页可将数据服务 API Key 保存到系统凭据库、同步动态模型目录并选择 Pi 默认模型。
• 设置页可在保存 API Key 后直接测试已保存的数据连接；探针只调用真实 quote CAP，不要求模型，并显示来源、数据时间和耗时。
• 设置页可检查 GitHub 最新公开版本并直达发布页；安装包仍提供 SHA-256 校验，自动更新待平台签名密钥接入后启用。
• 设置页支持导出/导入本地 JSON 备份，迁移自选、盯盘、消息与持仓；API Key、模型配置、缓存和运行日志不会进入备份。
• 内置兼容 OpenAI API 的模型网关配置；Pi 只访问带短期令牌的本机回环代理，不接触长期 API Key。
• 内置 Pi Bash 工具；Windows 安装包捆绑经过 SHA-256 校验的 PortableGit/Bash，所有桌面子进程均以无控制台窗口方式启动。
• WebView 对话在桌面环境通过 Tauri command 调用真实 Pi RPC；普通浏览器预览使用明确的演示回退。
• 本地 Web 调试可连接独立的 127.0.0.1 Local Host；浏览器通过受保护的短期会话调用同一套 Pi、数据适配器、凭据和用户状态能力。
• 开发者面板支持动态加载当前 provider 的完整 CAP 目录，查看参数/费用/成功率、复制 Skill Tool schema，并对任意目录项执行真实调用测试；目录查询不扣费，调用按上游规则计费。

架构

React desktop UI
    │ Tauri commands / runtime events
    ▼
Rust Host
    ├─ window + lifecycle
    ├─ Pi JSONL RPC manager
    ├─ credential boundary
    └─ run-scoped data executor capability
              │
              ▼
    Pi runtime + reviewed Skills
              │ fixed CAP first
              ▼
       Configured data tools
              │ explicit capability miss only
              └─ Search → Inspect → Call fallback

此项目不使用 qveris-qlab 架构。技术基线参考 ZiCode Studio Desktop 的 Tauri/Host/Pi 分层，但前端统一使用 React，且只保留金融客户端需要的边界。

配置真实数据与模型

在桌面端打开“设置”：

1. 保存数据服务 API Key。该密钥优先进入操作系统凭据库；Linux 本地调试若未运行 Secret Service，则使用权限为 0600 的用户配置文件回退，避免设置页保存失败。用户状态、集成设置和固化工具缓存也会在 POSIX 系统按 0600 保存，避免依赖机器默认 umask。
2. 可使用内置的 QVeris 兼容配置（工具地址 https://qveris.ai/api/v1、模型地址 https://aigateway.qveris.ai/v1），也可以按部署环境替换为兼容服务。
3. 点击“同步模型”，从网关的 /models 原子读取并保存当前可用模型，再选择 Pi 默认模型并应用。更换网关地址后必须重新同步，已下线的默认模型会安全回退到目录中的首个可用模型。
4. 在自选股页面点击“获取实时数据”可直接刷新当前标的；需要解释时再点击“交给 Agent”。行情卡会根据 provider 时间标记“数据时间未知”或“可能已延迟”，不会把缺少时间戳的数据冒充实时数据；没有可识别真实价格的数据不会进入行情、组合或盯盘结果。

盯盘消息页的“系统通知”开关默认关闭。开启时仅在当前桌面/localhost 环境请求系统通知权限，并可选择“全部提醒”或“仅关键提醒”；分级只影响系统通知，站内消息仍完整保存。拒绝权限不会影响站内消息保存和盯盘任务执行。

桌面版关闭主窗口后会隐藏到系统托盘并保持本地 Host 与自动复盘协调器运行。托盘菜单提供“显示 FolioMind”“立即检查盘后复盘”和“退出 FolioMind”；需要完全停止后台进程时请使用托盘退出。Web 本地调试页关闭后不会继续运行。

研究筛选目前以“我的自选”为明确数据范围；添加更多标的或安装额外数据 Skill 后，仍需等真实行情返回才会进入筛选结果。组合风险洞察只展示可解释的已计价暴露，不输出没有数据依据的综合风险分数。

自选侧栏“更多”支持批量导入和导出。导入文件只包含代码、名称、市场、分类和分组，解析会先完整校验，重复或非法行不会污染已有自选；实时行情、凭证和运行日志不会进入文件。

设置页的“本地数据备份”适合换机或在 Web 调试与桌面端之间迁移用户数据。导入会覆盖当前自选、盯盘、消息和持仓，并清空旧行情缓存，随后重新获取真实数据；正在分析或盯盘检查时会暂时禁止导入，避免覆盖进行中的任务。Host 每次保存前会保留上一份通过校验的状态快照，主文件损坏时自动恢复；若主文件和快照同时损坏，会提示导入备份，不会静默覆盖成默认数据。规则、消息已读、自选删除等状态操作也会等待 canonical Host 保存成功，失败时回滚并提供重试提示；事件提醒只有保存成功后才发送系统通知。

未配置凭证和模型时，界面可能显示带有“预览模式”标识的静态布局样例；一旦配置完成，行情、指标、图表、组合和盯盘信号只使用数据服务已返回的真实数据，缺失字段显示为空并提示查询，不会用样例补齐。设置页可分别测试已保存的数据连接和模型连接；模型探针只发起一次最小请求，不调用金融工具，但可能产生模型费用。

本地 Web 调试

Web 端本机调试不需要安装或启动桌面端。推荐用一个命令同时启动 Vite 和独立 Dev Host：

npm run web:dev

浏览器打开终端打印的 Web 地址（默认 http://127.0.0.1:5173；端口被占用时会自动递增并打印新的地址）后，设置页会显示“本地开发 Host”。Dev Host 与桌面端共享同一套 Host HTTP 协议，并优先直连固定 CAP，仅在明确能力缺失时代理 Search → Inspect → Call 和对话，因此修改前端或 Host 逻辑后刷新页面即可验证，不需要重新安装桌面包。API Key 保存在用户配置目录下权限为 0600 的文件中，浏览器只持有当前标签页的短期会话令牌。

本地 Web Host 会把 qveris_finance CAP 的 tool schema（tool_id、参数、返回字段、能力 ID、provider）保存到用户配置目录的 tool-selection-cache.json。设置页可选择 QVeris CAP 或兼容相同 tool schema 的 CAP 网关，并填写受校验的 Provider ID；Web Host 与桌面端持久化同一套渠道配置，不同渠道使用隔离缓存。行情、基本面和历史序列优先直连 CAP；只有明确的工具缓存缺失、能力不存在或 HTTP 404 才回退到一次 Search → Inspect → Call。认证、限流、超时、网络和服务端错误直接进入可恢复错误态，不追加发现调用。direct CAP 真实结果缓存最多保留 256 项，按最近使用顺序淘汰，命中会续期；过期条目立即移除，空结果和失败不会缓存。QVeris 数据调用和模型网关遇到 408/425/429/5xx 或可恢复网络错误时使用有界指数退避，并尊重上游 Retry-After；已取消的请求不会重试，取消请求会立即打断等待。固化工具只有收到明确的工具失效/不存在响应才会清除，瞬时限流、服务端错误和网络抖动会保留缓存。运行时同一时间只接受一轮对话请求，重复提交返回可识别的忙碌状态，不会互相覆盖取消控制器。价格异动盯盘也复用 CAP 行情工具，避免每次检查重新调用模型编排；本地 Web 自选行情默认以 4 路、桌面端默认以 2 路受限并发请求，开发面板仍可在 1–4 路之间调整。行情轮询会感知浏览器可见性。localhost 页面和桌面端右下角的“开发者面板”均可查看运行时、API Key 前缀、模型/CAP 调用日志、耗时和能力目录；密钥与原始提示词不会记录。

如需验证真实 Tauri 窗口，再使用 npm run desktop:dev；这不是 Web 调试的前置条件。

当多个自选标的首次同时刷新且工具缓存尚未命中时，Host 会合并同类请求，只执行一次 Search → Inspect → Call 预热，其余请求等待缓存固化后直接复用，减少首屏重复发现工具。

为避免长期凭据通过明文链路泄露，远程数据服务地址必须使用 HTTPS；只有 localhost、127.0.0.0/8 和 ::1 回环地址允许使用 HTTP。基础地址不能包含 query 或 fragment。

Local Host 与桌面端使用同一地址安全边界：地址不能包含用户名或密码，配置读取和发起请求前都会重新校验；被手动篡改的地址会被拒绝，不会向其发送 API Key。

本地开发

npm install
npm run dev

安装 Rust toolchain 与平台依赖后运行桌面端：

npm run desktop:dev
npm run desktop:build

验证：

npm test
npm run audit:security
npm run fetch:pi
npm run fetch:bash
npm run smoke:pi
npm run build
npm run test:sites
VERSION=$(node -p 'require("./package.json").version'); gh release view "v$VERSION" --repo ax2/foliomind --json isDraft,assets | npm run verify:release-assets -- "$VERSION"
cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo clippy --locked --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --locked --manifest-path src-tauri/Cargo.toml

构建或 Playwright 回归后可清理可重新生成的产物；该命令只处理 dist、.qa、.cache 和 Tauri target 目录，不会删除 Pi、portable-git、用户配置或源代码：

npm run clean

需要先确认清理范围时运行 npm run clean -- --dry-run。

Playwright 回归脚本默认检查 http://127.0.0.1:4173；本地 Web Host 自动递增端口时可通过 FOLIOMIND_QA_URL=http://127.0.0.1:<端口> python scripts/qa-playwright.py 指定实际页面地址。

发布安装包

GitHub Actions 的 release workflow 会在 main 的版本提交后自动运行，也支持手工触发；版本从 package.json、Cargo 和 Tauri 配置一致性校验中读取（当前为 0.1.229）。若同一版本已经正式发布，后续同版本提交会在准备阶段安全跳过，不重复构建或覆盖资产。发布会先完成格式、严格 Clippy、测试以及隔离 Web/Local Host Playwright 回归，再构建 Windows NSIS/MSI 和 macOS Apple Silicon DMG；确认三类安装包齐全并通过 SHA-256 校验后，才创建或复用 v<version> draft release、上传安装包与 SHA256SUMS.txt 并正式发布。Windows 安装包使用稳定的 WiX UpgradeCode、禁止降级并采用 current-user 安装模式；可识别的同一产品新版本会直接覆盖升级，不要求用户先手动卸载或重复确认，只有无法识别为同一产品时才保留系统安全确认。配置、API Key 和用户数据位于安装目录之外，会保留在升级后。

gh workflow run release.yml --repo ax2/foliomind -f version=0.1.229 -f prerelease=false

发布前可运行 npm run review:architecture，检查版本、真实数据边界、状态脱敏、安装升级路径、Release 资产和 PRD 阶段设计。Release 的 npm 安全审计在服务异常或连续重试失败时会阻断发布，不会以警告放行。

视觉源文件位于 design/foliomind-concept.png，最终视觉验收记录见 design-qa.md。

License

FolioMind 使用 MIT License 开源。