TNT-Likely/PanWatch · 上手攻略

  • 仓库：TNT-Likely/PanWatch
  • 链接：https://github.com/TNT-Likely/PanWatch
  • 分类：agent / llm-infra（engineering · app）
  • 作者：spark
  • 更新：2026-10-24

一、它是什么

PanWatch（中文名"盯盘侠"）是一个开源自托管的 AI 盯盘与持仓分析平台，核心引擎不是自己造的，而是套壳自研的 TradingAgents 多智能体投研框架。官方一句话定位是："AI stock monitoring for A-shares, HK & US markets, powered by TradingAgents"——覆盖 A 股 / 港股 / 美股三个市场的行情监控、持仓管理、实时提醒和自动报告。

它区别于普通"行情软件"或"AI 选股脚本"的地方在于把 LLM 决策流水线做成了可运营的产品：

  • 九智能体研究链：从你持仓里的某只票出发，四个分析师角色（技术面 / 情绪面 / 新闻面 / 基本面）并行跑数据，再进入多空辩论（bull/bear debate）、风险复核（risk review），最后由组合经理（PM）出一份决策备忘录。README 明确说全流程 3–5 分钟跑完，完整推理链路在 App 和通知渠道里都能看。
  • 多市场同一套工作流：股票、场内 ETF、自选股、持仓、价格提醒、行情与 K 线，主流程在内地、香港、美国三个市场完全共用；按代码或名称搜索（510300、159915、02800、SPY 都支持）。行情来自东方财富、新浪、雪球、财联社等中文源 + yfinance（美股）多供应商容错。
  • 定时 Agent 不是一个而是一族：盘前展望（pre-market）、盘中监控（intraday）、每日复盘报告（daily report）三类调度任务，另有独立的 packages/pan-investment-research 研究包提供图模板、专家角色、辩论策略和每次运行的预算控制。
  • 纸面交易（paper trading）：按信号模拟开平仓，带 T+1/T+2 交收、可用资金、保证金约束（买用已交收资金）等等待细节，有一个完整的权益曲线与绩效面板。
  • 工程底座扎实：FastAPI + SQLAlchemy + APScheduler + OpenAI SDK / React 18 + TypeScript + Tailwind + shadcn/ui，内置 OTel 可观测栈（GenAI 语义约定 span）、PWA 可安装到手机主屏、MIT 协议。

当前版本：最新 release 0.20.0（2026-10-23 发布，tag commit ec3e87e），Docker 镜像 sunxiao0721/panwatch:0.20.0 / :latest。TradingAgents 上游 pin 在 v0.7.0。仓库最近提交 2026-10-23，Stars 2202。

二、它解决什么问题

  1. "我不想盯盘但又想盯盘"——把盘前/盘中/盘后三段固定流程写成定时 Agent，睡觉时让它自己跑，早上在 Telegram / 企业微信 / 钉钉 / 飞书 / Bark / Webhook 里收到报告。
  2. 多账户持仓没有统一视图——券商账户分散在多个 App，PanWatch 把多账户持仓、P&L、交易风格拉到一个面板，并直接作为 AI 分析的输入上下文。
  3. "AI 给我一个理由"——不是要一个买卖信号就完事，而是要能审计的多空辩论记录和最终 PM 决策备忘录，附完整 reasoning trail。这是它比大多数"AI 荐股"玩具更务实的地方。
  4. "提醒太多/太少"的配置地狱——价格提醒支持价格、涨跌幅、换手率、量比等条件 AND/OR 组合，可设冷却期（cooldown）、每日触发上限、过期时间、限定交易时段或全天。
  5. 想验证策略但不敢上真钱——纸面交易 + 机会池（AI 打分排序的候选，带入场位、目标位、风险上下文）+ 决策复盘与预测追踪闭环。

⚠️ 明确划线：README 反复强调"研究输出不产生订单，也不建立已验证的买入力"（"This research output does not place orders or establish verified buying power"）。它是研究与提醒工具，不是自动交易系统。Paper trading 默认关闭，启用后也只把合格的买/卖建议写成纸面信号。

三、快速安装

3.1 Docker（推荐，README 主推路径）

docker run -d \
  --name panwatch \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -p 8000:8000 \
  -v panwatch_data:/app/data \
  sunxiao0721/panwatch:latest

然后打开 http://localhost:8000，首次访问时自己设置登录用户名和密码（AUTH_USERNAME / AUTH_PASSWORD 留空则由你在 UI 里创建）。

Docker Compose 版本：

services:
  panwatch:
    image: sunxiao0721/panwatch:latest
    container_name: panwatch
    environment:
      TZ: "Asia/Shanghai"
    ports:
      - "8000:8000"
    volumes:
      - panwatch_data:/app/data
    restart: unless-stopped

volumes:
  panwatch_data:

docker compose up -d

3.2 本地开发

需求：Python 3.11+ / Node.js 24.14.0 / pnpm 9.15.9（这三个版本号是 README 明写的，Node 24.14.0 这个 pin 相当新，务必对齐）。

# 一键开发（自动建 venv 装依赖）
make dev-api    # 后端 :8000
make dev-web    # 前端 :5183

# 或手动
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python server.py                 # 后端 :8000

cd frontend && pnpm install && pnpm dev   # 前端 :5183

前端 dev server 在 http://localhost:5183，把 /api 代理到 127.0.0.1:8000。

3.3 首次配置流程（新手必读）

README 描述了一个强制的新手引导（main tour），首次登录自动打开且不可跳过步骤（可暂停/恢复），内容涵盖关注股票、行情、AI 配置和第一次分析。引导进度存在服务端，浏览器换了也不丢；可从 Guide center 重开。

关键顺序：Settings → AI Services 里配置服务商、设默认模型、测连通性，然后再显式触发第一次分析——这个动作会消耗你的模型额度。

必配环境变量（README 表格 verbatim）：

变量 含义 默认
AUTH_USERNAME 预置登录用户名 首次访问时设置
AUTH_PASSWORD 预置登录密码 首次访问时设置
JWT_SECRET JWT 签名密钥 自动生成
DATA_DIR 数据存储目录 ./data
TZ 部署时区（影响调度与免打扰时段） Asia/Shanghai
PLAYWRIGHT_SKIP_BROWSER_INSTALL 跳过 Chromium 下载 未设置
LOG_LEVEL 日志级别，DEBUG 出调度心跳与采集步骤 INFO
HTTP_PROXY / HTTPS_PROXY / http_proxy 出站代理 未设置
OTEL_EXPORTER_OTLP_ENDPOINT OTel 导出端点 未设置（禁用）

代理优先级：外部环境变量 > UI（Settings → Global HTTP Proxy）> .env。NO_PROXY 默认含 localhost,127.0.0.1。

四、核心用法

4.1 配置 AI 服务（OpenAI 兼容 / 本地 Ollama）

README 主旨是"self-host with your preferred OpenAI-compatible provider or local models through Ollama"。具体配置入口在 Settings → AI Services。⚠️ 具体字段名、模型下拉选项我未逐一核实（README 只给了入口路径和"设默认模型 + 测连通性"两步），第一次配置请以 UI 实际渲染为准。

4.2 触发单标的深度分析

在持仓页某只票旁边的"脑图标"点一下即触发 TradingAgents 深度分析，四个分析师角色并行 → 多空辩论 → 风险复核 → PM 决策，推理链路可在 App 内和已配置的通知渠道查看。也可以从定时 Agent 或已启用的盘中事件规则触发。

关键参数（来自 docs/tradingagents-flow.en.md）：

  • 四个分析师类型并行跑，然后 join 进入研究辩论；
  • 研究辩论轮数与风险讨论轮数可配置；
  • 论文式输出：最终评级取 final_rating，研究主管结论取 investment_plan；
  • 评级映射：TradingAgents 的评级被映射为 PanWatch 的 buy / add / hold / reduce / sell 五档；无法解析的评级会被标记为人工复核（不会瞎猜）；
  • 纸面交易集成默认关闭，开启后仅合格的买卖建议写成纸面信号；
  • 决策日志独立存储，决策在其日期后第一个收盘入场；持仓期结束且有行情数据后，相对基准表现与反思笔记会反馈进同一标的的后续分析。

4.3 定时 Agent

Agents 页面配置。三个核心 Agent：Pre-market outlook（隔夜行情 + 新闻 + 技术结构 → 开盘计划）、Intraday monitor（盘中异动与技术信号）、Daily report（当日复盘 + 次日计划）。调度可自定义 cron 表达式（如 0 9 * 1-5）。

自动运行会先按交易所节假日过滤；盘中流程还要求当前处于开市时段。

4.4 研究编排（Research orchestration）

Agents 页的 Research orchestration 里可以选：验证过的图模板（validated graph templates）、专家角色（specialists）、辩论策略（debate policy）、每次运行预算（per-run budgets）。盘中用确定性变化门控（deterministic change gate） + 短专家/决策图；quiet snapshot 不用任何模型并保留上一次的建议。盘前加开盘情景，盘后加归因与"带证据链的复盘"。

预算与限流规则：模型候选与只读证据工具共享显式的尝试次数、token、并发和时间限制。未解决的反对意见或耗尽的预算会把研究标记为 incomplete，只保留已验证的策略草稿——不会在没有策略完成时伪造看涨建议。已完成图谱产物、归一化建议、预测追踪和投递声明原子提交；未完成的研究不发布正式建议或预测结果。未知通知确认会被记录但不盲目重放。⚠️ 明确未启用：跨进程图谱恢复和自动 outbox 恢复。

4.5 价格提醒

条件可组合：价格、百分比变化、换手率、量比等，支持 AND/OR 逻辑。可限定"仅交易时段"或"全天（仅交易日）"，设冷却期、每日触发上限、重复行为、过期日期与 HH:mm（留空则永不过期）。每条规则可选通知渠道，不选则用系统默认。

4.6 技术面指标

  • 趋势：均线排列、MACD 金叉死叉、布林带突破
  • 动量：RSI 超买超卖、KDJ 饱和与背离
  • 量价：量比异动、缩量回调、放量突破
  • 形态：锤子线、吞没、十字星等 K 线形态
  • 支撑压力：自动计算多档支撑/压力位

4.7 可观测性（可选 OTel 导出）

三步开启：

# 1. 装可选依赖
pip install -r requirements-otel.txt

# 2. 配置采集端点
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=panwatch   # 可选，默认 panwatch

# 3. 正常启动，启动日志会确认 OTel 导出已启用
python server.py

本地 Jaeger 验证：

docker run -d --name jaeger -p 16686:16686 -p 4318:4318 \
  jaegertracing/all-in-one:latest
# 触发一次 agent，打开 http://localhost:16686，选择 service=panwatch

Span 映射三类：一次 agent run → root span（与 agent_runs 表的 trace_id 关联）；一次 LLM 调用 → 遵循 OTel GenAI 语义约定的 gen_ai 子 span（含 gen_ai.system、gen_ai.request.model、输入/输出 token 用量、gen_ai.operation.name）；一个 TradingAgents 节点 → 复用节点级进度回调的子 span。依赖未装或端点为空时导出是彻底的 no-op。 Langfuse / Tempo 只需指向它们的 OTLP endpoint。

五、典型适用场景

  1. 跨市场个人投资者的统一工作台：同时管 A 股 + 港股 + 美股账户，一个面板看持仓和 P&L，AI 分析天然吃多市场上下文。
  2. "盘前 15 分钟"决策仪式：配 pre-market agent，每天固定时间出开盘计划 + 关键新闻，技术面形态和消息面在同一份报告里对齐。
  3. 研究员的对照组：纸面交易 + 决策日志 + 相对基准表现，可以把"AI 建议复盘"变成可量化的实验。
  4. 小团队/工作室的行情播报：通知渠道支持 Telegram / 企业微信 / 钉钉 / 飞书 / Bark / Webhook，把报告直接推到团队 IM，比自己写定时脚本省事。
  5. 纯技术面交易者的自动化提醒：不用跑 LLM，只用技术指标 + 价格提醒 + 量化条件。
  6. 自托管 LLM 用户的实验场：支持 Ollama 本地模型，出站代理可控，数据不出内网（行情源仍需外网）。

六、坑与注意

  1. ⚠️ 时区是四套，别混（官方 docs/timezones.md 定义）：存储时刻 = UTC；界面显示与输入 = 浏览器时区；后台调度与免打扰 = 部署 TZ；市场日历日期 = 交易所时区。改 TZ 前务必先看现有 cron 和免打扰的挂钟时间——同一个 09:00 在两个时区是两个不同瞬间。界面时间戳和提醒过期输入走浏览器时区，不跟部署时区。北京时间周六上午可能对应纽约周五收盘后，状态条要"市场状态条"对照三个交易所未来 14 天。
  2. ⚠️ 镜像不自动探测宿主机时区，默认 Asia/Shanghai，且不会因升级而改动（这是刻意的，避免升级静默挪动已有任务）。容器化部署在海外务必显式设 TZ=America/New_York 之类。
  3. ⚠️ 交易日历是本地打包的 2026 年数据，启动只预热过去 30 天 + 未来 90 天，不下载完整历史。未发布的平日会显示"pending calendar"并阻止自动执行——跨年部署前必须更新打包的年度日历数据，否则定时 Agent 会静默不跑。同理，纸面交收依赖日历，未来日历未知时未交收资金会一直 pending。
  4. ⚠️ 首次启动会下载 Playwright 的 Chromium headless shell（落到挂载卷，默认 /app/data/playwright），需要网络且可能耗时几分钟。不需要截图/浏览器功能就设 PLAYWRIGHT_SKIP_BROWSER_INSTALL=1。
  5. ⚠️ 每次深度分析都烧模型额度，README 明确说"runtime and cost depend on the selected models and configuration"。新手引导里"测连通性"那一步本身不耗额度，但"显式生成第一次分析"耗。批量研究有 token/并发/时间三重预算上限，预算耗尽 = 研究 incomplete = 不出正式建议，不是 bug。
  6. ⚠️ ETF 支持不完整：ETF 深度分析用基金语境，但不替代公司财报；基金持仓、净值、费率、跟踪误差尚未以结构化数据提供；纸面交易的 ETF 特殊 T+0 例外与费率表未建模。买 ETF 的人别指望基金层面数据。
  7. ⚠️ 纸面交易的交收模型是简化的：A 股 T+1（按上海买入日算，不等 24 小时）；港股 T+2、美股 T+1 走现金账户，只用已交收且未被占用的资金。A 股卖出款可立即用于新开仓，港美股不行。未建模日内清算批次、提现截止、融资、汇率、券商特定设施；历史交易不会被追溯锁定。港股半日市是非交收日；美国 Columbus Day / Veterans Day 即使有交易也推迟交收。README 直接引用了 HKEX / SEC T+1 / DTC 2026 假期三个公告作为规则依据。
  8. ⚠️ 零散券商 API 接入？不存在的。 券商账户是手工维护的持仓数据，PanWatch 不连你的券商下单接口。数据准确性完全取决于你录入得准不准。
  9. ⚠️ 通知不盲目重放："Unknown notification acknowledgements are recorded without blind replay"——通知投递状态未知时只记录不重发，可能出现"发了但没收到且不会补发"的情况。
  10. ⚠️ 跨进程图谱恢复与自动 outbox 恢复未启用（README 明确列为不支持），进程在研究中途挂掉，那次研究不会自动续跑。
  11. ⚠️ 升级前留意破坏性变更：README 提到 migration v139 退役了 legacy/shadow 执行模式（保留设置与历史），并移除了三个旧的 session prompt 和文本解析器。TradeAgents 深度分析保持独立不受影响。0.20.0 的变更列表集中在前端解耦与性能、runtime 存储/供应商状态隔离、回测记账修正、TradingAgents 升级加"visual reading"、yfinance fast_info 映射键读取修复。
  12. ⚠️ AUTH_USERNAME/AUTH_PASSWORD 不设就在首访创建，容器重建 + 数据卷丢失 = 账号失联。务必备份 panwatch_data 卷。JWT_SECRET 默认自动生成，数据卷丢失后所有 JWT 失效。
  13. ⚠️ "AI 评分"不是投资建议。星级 2202、成熟度标记为 research 的开源项目，它的输出质量完全取决于你配的模型 + 喂给它的行情数据质量。README 自己就写了 "This research output does not place orders or establish verified buying power"。不要把它当交易系统。
  14. ⚠️ 成本不可忽视：研究用多智能体 + 多轮辩论，单次深度分析就是多次 LLM 调用。开源免费的是软件，不是推理。选便宜模型或用 Ollama 本地跑是控本关键。

七、与同类对比

维度 PanWatch 裸 TradingAgents 商业 AI 盯盘终端 纯量化回测框架
定位 完整自托管产品（UI+调度+通知+纸面交易） 研究框架/库 SaaS 终端 本地研究脚本
多市场 A股/港股/美股统一工作流 面向美股为主 视厂商 需自接数据
LLM 编排 九智能体 + 辩论 + 风险 + PM 多智能体辩论 黑盒 无
可解释性 完整 reasoning trail + 决策日志 + 基准对照 图谱可读 通常仅结论 因子可查
部署成本 零许可费 + 推理费 零 订阅费 零 + 数据费
数据接入 中文源 + yfinance 多源容错 需自备 自带 需自备
短板 ETF 数据缺、简化的交收模型、无券商下单 无 UI/调度/通知 闭源不可私有化 无 LLM、无盯盘
适合 要"能运营的盯盘流水线"的自托管党 想改 agent 逻辑的研究者 不想折腾的普通用户 纯规则策略研究者

关键差异：PanWatch 相对 TradingAgents 上游的增量是"产品化"——调度、通知、纸面交易、时区与日历治理、PWA、OTel；相对商业终端的增量是"可私有化 + 可改 + 中文市场覆盖"。代价是它继承了 LLM 投研的一切幻觉风险，且交收/ETF 模型是简化的。

八、一句话推荐结论

如果你想要一个"自托管、A/港/美三市场通吃、把多智能体投研做成可定时运行的日常盯盘流水线"的产品，PanWatch 是目前开源里最完整的一个，值得部署；但请把它当"研究助手 + 提醒系统"而不是"自动交易系统"，务必先配好便宜模型或 Ollama 控成本、显式设 TZ、每年更新交易日历数据、备份 panwatch_data 卷，再配一条纸面交易线跑上几周验证它的建议质量。

附：来源与核验说明

已实际 fetch 的来源： - GitHub README（TNT-Likely/PanWatch main 分支，2026-10-24 拉取） - docs/tradingagents-flow.en.md（TradingAgents 深度分析流程，pin v0.7.0） - docs/timezones.md（四类时间策略） - src/ARCHITECTURE.en.md（模块边界与禁止设计） - CONTRIBUTING.md（目录结构、验证命令、扩展 Agent 的步骤） - GitHub API /releases/latest → 0.20.0，published_at 2026-10-23T22:38:41Z，tag commit ec3e87e - GitHub API /tags → 0.20.0 / 0.19.0 / 0.18.1 / 0.18.0 / 0.17.5 … - 仓库卡 organized/repo_cards/4600-tnt-likely-panwatch.md（Stars 2202、最近提交 2026-10-23、MIT、Python）

不确定 / 待核处： 1. Settings → AI Services 的具体配置字段名、模型供应商枚举、Ollama 的 base URL 填法——README 只给了入口与两步流程，未展开，标注待核。 2. Paper trading 的默认手续费率、佣金/印花税参数——README 提到 "existing market rules and cost model" 但未给具体数字，标注待核。 3. Opportunities（AI 打分机会池）的打分算法——README 只描述输出形态（入场位、目标位、风险上下文），未公开算法，标注待核。 4. packages/pan-investment-research 包的独立安装方式与可用图模板清单——README 只给了链接，未展开，标注待核。 5. TradingAgents v0.7.0 是否为 PanWatch 最新依赖版本——flow 文档称 "pins the official v0.7.0 release"，但 0.20.0 release note 提到 "upgrade analysis"，是否仍为 v0.7.0 未二次确认，标注待核。 6. 前端 Node/pnpm 版本 pin（24.14.0 / 9.15.9）与本机 pnpm 9 是否兼容——未实测，标注待核。 7. Docker 镜像 sunxiao0721/panwatch 的实际维护主体与 TNT-Likely 组织的关系——README 中赞助联系邮箱为 sunxiaoyes@outlook.com、镜像前缀为 sunxiao0721，与组织名不一致，未核实，标注待核。 8. 本攻略只读公开内容，未 clone 仓库、未运行任何代码，所有命令均来自 README/官方文档原文，未实测。