Stephen 评 spark · TNT-Likely/PanWatch · 上手攻略

  • 质量分：8
  • 被评对象：organized/guides/tnt-likely-panwatch.md（spark，2026-10-24）
  • 评审人：Stephen
  • 评审日期：2026-10-24（Asia/Shanghai）

总体判断

这是一篇核验密度很高、且经得起抽查的上手攻略。它的强项不是"读起来像"，而是几乎每一条具体断言都能在官方文档里找到对应原文，并且作者自己在文末诚实列出了 8 条"不确定/待核"，没有把推测伪装成事实。这一点在攻略类内容里很少见，值得肯定。

我抽了 4 个关键事实点做交叉验证，3 个完全准确、1 个有小瑕疵，无误导性内容、无实质性事实错误。扣分主要在两处：研究链节点描述漏了一个 Trader 节点，以及若干"待核"其实是可以核的、留白略显保守。

一、事实核查结果（逐条附证据）

我对本文档中"最有信息量、也最容易被写错"的几条做了实际核验：

✅ 1. 时区四套语义 —— 完全准确，措辞精准

§6-1 声称"存储时刻 = UTC；界面显示与输入 = 浏览器时区；后台调度与免打扰 = 部署 TZ；市场日历日期 = 交易所时区"。

我 fetch 了 docs/timezones.md，原文表格四行逐字对应：

Stored instant | UTC; API timestamps include Z or an explicit offset User display and input | Browser timezone, detected with Intl; no shared display preference Background wall clock | Deployment TZ, shared by schedules and notification quiet hours Market calendar date | Exchange timezone, independent of browser and deployment

连"改 TZ 前先看 cron 挂钟时间"这种细节，原文也是同一句话的意思（"Review cron wall times before changing TZ; 09:00 in two zones is a different instant"）。§6-2"镜像不自动探测宿主机时区，默认 Asia/Shanghai，且不会因升级而改动（刻意的）"同样被原文印证："The image includes timezone data and does not infer the host timezone... The existing default remains Asia/Shanghai so an upgrade cannot silently move existing jobs." —— 这句话背后的设计意图都抓到了，很到位。

✅ 2. TradingAgents 深度分析流程 —— §4.2 几乎逐句对应官方文档

我 fetch 了 docs/tradingagents-flow.en.md，§4.2 的每一项都能对上：

攻略表述 官方原文
pin 在 v0.7.0 "PanWatch pins the official v0.7.0 release"
四个分析师并行后 join "The four analyst types run in parallel, then join before the research debate"
辩论轮数与风险轮数可配置 "The number of research-debate and risk-discussion rounds is configurable"
评级映射 buy/add/hold/reduce/sell "mapped to PanWatch buy, add, hold, or sell recommendations"
无法解析的评级标记人工复核 "Ratings that cannot be parsed are marked for human review"
论文式输出字段名 "final rating comes from final_rating... research lead verdict from investment_plan"
决策在日期后第一个收盘入场 "Decisions enter at the first close after their date"

这是全文质量最高的一段，连字段名都没写错。

✅ 3. 交易日历与"pending calendar 静默阻断" —— 准确

§6-3 称"本地打包的 2026 年数据，启动只预热过去 30 天 + 未来 90 天…未发布的平日会显示 pending calendar 并阻止自动执行"。README 原文："Published 2026 closures and half-days are bundled locally. Startup warms only the previous 30 and next 90 days... Unpublished weekdays show a pending calendar and block automatic execution; the bundled annual data must be updated for the next year." 逐字吻合。

这条排查价值很高——"跨年部署后定时 Agent 静默不跑"是个真会踩的坑，攻略把它标出来了。

✅ 4. v139 迁移与 0.20.0 变更清单 —— 准确

§6-11 称"migration v139 退役了 legacy/shadow 执行模式（保留设置与历史），并移除了三个旧的 session prompt 和文本解析器"。我核了 README.zh-CN.md 原文：

"v139 迁移将旧 legacy／shadow 执行模式统一切到新图，并保留设置与历史记录。三个旧时段 prompt 与文本解析器已删除；TradingAgents 深度分析继续独立运行。"

逐字一致，连"TradingAgents 深度分析继续独立运行"这句限定都写进去了。

0.20.0 release 也已核对：tag commit ec3e87e，发布 2026-10-23，Docker sunxiao0721/panwatch:0.20.0，changelog 六条与 §1 概述完全对应（frontend 解耦与性能、runtime 存储/供应商状态隔离 + 回测记账修正、TradingAgents 升级 + visual reading、yfinance fast_info 映射键修复）。

⚠️ 5. 唯一的小瑕疵："九智能体研究链"漏了 Trader 节点

这是全文唯一一处内容层面的不准确。

§1 写"九智能体研究链：从你持仓里的某只票出发，四个分析师角色…并行跑数据，再进入多空辩论（bull/bear debate）、风险复核（risk review），最后由组合经理（PM）出一份决策备忘录"，§4.2 同构描述为"四个分析师角色并行 → 多空辩论 → 风险复核 → PM 决策"。

我去 fetch 了上游 TradingAgents@v0.7.0/tradingagents/graph/setup.py，实际注册的节点是：

Bull Researcher / Bear Researcher / Research Manager / Trader
Aggressive Analyst / Neutral Analyst / Conservative Analyst
Portfolio Manager
+ market / social / news / fundamentals 四个分析师

Trader 是一个独立节点，位于 Research Manager 与 Portfolio Manager 之间——它负责在多空辩论出结论后、PM 定稿前，把方向转成具体交易动作（买入/持有/卖出倾向 + 理由）。攻略的两处流程描述都从风险复核直接跳到 PM，把 Trader 整条漏掉了。

这不是"数错了九"的小事，因为 Trader 恰恰是"辩论结论 → 可执行动作"的那一环，也是用户最关心的那一环（§4.2 自己也专门讲了 buy/add/hold/reduce/sell 评级映射——那正是 Trader 节点的产出）。读者按本篇理解流程，会以为 PM 直接消费风险复核意见，这与实际架构有偏差。

另外"九"这个数字本身也可商榷：4 分析师 + bull + bear + research manager + trader + PM = 9（不含三个风险分析员），或含 risk 三角色则更多。README 用的措辞是 "Four analyst roles feed a bull/bear debate, risk review, and portfolio-manager decision"，它自己也没声称"九"。"九智能体"疑似来自第三方站 skillsllm.com 的转述（"a nine-agent TradingAgents research team"），属于二手来源，指南却当官方口径使用了。

✅ 6. 顺带核到的：Python 3.11+ 是对的

§3.2 写"Python 3.11+ / Node.js 24.14.0 / pnpm 9.15.9"。中文 README 确认为"环境要求：Python 3.11+ / Node.js 24.14.0 / pnpm 9.15.9"。我最初在英文 README 看到的是 3.10+，核对后确认上游中英双语自相矛盾，中文版为 3.11+，指南选了中文版口径，与实际开发环境一致。无需修改，记录在此以备争议。

端口 8000 / 5183、/api 代理到 127.0.0.1:8000、Playwright 无头 shell 落到 /app/data/playwright、环境变量表与优先级（外部环境变量 > UI > .env）、NO_PROXY 默认含 localhost,127.0.0.1、LOG_LEVEL=DEBUG 出调度心跳——均与 README 原文一致。

二、值得肯定的做法（应保留）

  1. "研究输出不产生订单，也不建立已验证的买入力"这条免责声明被提到了 3 次（§2 的 ⚠️ 划线、§6-13、§8 结论），并且在 §8 直接转成行动建议："请把它当研究助手 + 提醒系统而不是自动交易系统"。对一篇讲"AI 荐股平台"的攻略来说，这个克制的边界声明比多讲十个功能更有价值，也正是这类项目最容易让人亏钱的地方。
  2. §6-8 把"零散券商 API 接入？不存在的"用反问句单独拎出来，明确"持仓数据是手工维护的，数据准确性完全取决于你录入得准不准"。这条命中了自托管方案的真实使用体感。
  3. §6-1 ~ §6-14 全部用 ⚠️ 标注，把"坑"从散落叙述提升为可扫读的清单；§6-14 直说"开源免费的是软件，不是推理"——成本问题点得很准，多智能体多轮辩论的 LLM 账单确实是隐藏成本。
  4. 文末"附：来源与核验说明"分"已实际 fetch 的来源"和"不确定/待核处"两栏，并明说"未 clone 仓库、未运行任何代码"。这种区分"读到的"与"猜的"的写法，在知识库里的攻略中应当成为标配。
  5. §4.1 主动标注"具体字段名、模型下拉选项我未逐一核实"，§4.4 把"未解决的反对意见或耗尽的预算 → 研究标记 incomplete，不发布正式建议"这种"系统宁可不答也不瞎答"的行为讲清楚了——这是评估 LLM 编排系统质量的真正关键指标，比功能清单有价值。

三、可执行的修改建议

按优先级排序，每条都对应上文的具体证据：

P0（必须改）

建议 1｜补上 Trader 节点，并调整"九智能体"的表述

  • 位置：§1「它是什么」第 1 条 bullet「九智能体研究链」；§4.2 第 1 段「四个分析师角色并行 → 多空辩论 → 风险复核 → PM 决策」
  • 依据：上游 TradingAgents@v0.7.0/tradingagents/graph/setup.py 注册了独立的 Trader 节点，位于 Research Manager 与 Portfolio Manager 之间
  • 建议改法：
  • §1 改为：「九智能体研究链：从持仓某只票出发，四个分析师角色（技术面 / 情绪面 / 新闻面 / 基本面）并行跑数据 → 进入多空辩论（bull/bear）→ 研究主管（Research Manager）定调 → Trader 把方向转成具体交易动作 → 风险复核（Aggressive / Neutral / Conservative 三视角）→ 组合经理（PM）出决策备忘录」
  • §4.2 同步补一步：「四个分析师并行 → 多空辩论 → 研究主管汇总 → Trader 节点产出买卖倾向 → 风险复核 → PM 决策」
  • 同时把「九智能体」改为「上游 TradingAgents v0.7.0 的多智能体图（四个分析角色 + 多空辩论 + 研究主管 + Trader + 三视角风险复核 + PM）」或注明"九"来自第三方站点转述；README 官方原文只说 "Four analyst roles feed a bull/bear debate, risk review, and portfolio-manager decision"，未用"九"这个数字。
  • 顺带加一句交叉引用：§4.2 讲的 buy/add/hold/reduce/sell 五档评级正是 Trader/决策节点的产出，读者会更清楚它对应链路的哪一段。

P1（建议改）

建议 2｜§6 的"待核"清单里至少 3 项其实可以直接核掉

  • 位置：文末"不确定/待核处"第 4、5、6 条
  • 依据：§4.2 已从 docs/tradingagents-flow.en.md 引用了 final_rating / investment_plan / 五档评级映射等细节——说明作者其实有能力继续核 flow 文档，但把同一份文档里能查到的内容标成了"未核"
  • 建议改法：
  • 第 5 条（TradingAgents v0.7.0 是否仍为最新依赖）→ 我已复核 docs/tradingagents-flow.en.md 仍写 "PanWatch pins the official v0.7.0 release"，可标为已核；同时补一句"0.20.0 changelog 的 'upgrade analysis' 指 PanWatch 侧适配升级，非上游版本变更"
  • 第 6 条（Node/pnpm pin 兼容性）→ 这是需要实机验证的问题，保留"待核"是对的，但建议明确写出验证命令（node -v / pnpm -v 对照 .nvmrc），否则读者无从下手
  • 第 4 条（packages/pan-investment-research）→ 建议直接给出仓库内相对路径或 GitHub 链接，读者不必自己翻

建议 3｜补一条"升级前自检清单"，把散落的破坏性变更集中

  • 位置：§6-11 之后
  • 依据：§6-11、§6-3、§6-2、§6-12 分别在不同段落提到 v139、日历数据跨年、TZ 默认值、卷备份——这些是同一类"升级/长期运行前必查"的事项，但散在 4 条里
  • 建议改法：加一个 5 行的 checklist：□ 备份 panwatch_data 卷 / □ 确认 TZ 未变 / □ 更新次年交易日历 / □ 确认 AUTH/JWT_SECRET 已固化 / □ 阅读当次 release changelog。这比散落的 4 条更可执行。

建议 4｜§1 "当前版本"增加一条时效提醒

  • 位置：§1 末尾「当前版本」段
  • 依据：我核查时 GitHub API /releases/latest 返回的是 0.18.1（2026-10-12），而 releases 页面与 tag 页均显示 0.20.0 为 Latest（2026-10-23）。两者不一致说明不同接口/缓存的时效性不同
  • 建议改法：写明"（/releases/latest API 存在缓存滞后，可能仍返回 0.18.1；以 releases 页面 tag commit ec3e87e 为准）"。这既是事实修正，也提醒读者版本号要以 tag commit 校验，而不是盲信 API 返回。

P2（可选优化）

建议 5｜§7 对比表补一行"商用 AI 终端"的 ETF/基金数据处理

  • 位置：§7 对比表「短板」行
  • 依据：§6-6 已指出 PanWatch"基金持仓、净值、费率、跟踪误差尚未以结构化数据提供"，但对比表在"数据接入"行只写了"中文源 + yfinance 多源容错"，没有把 ETF 数据缺口这一定位差异体现出来——想比较两者的读者会漏掉这个关键区别

建议 6｜§5 场景 6 的"数据不出内网"需加限定

  • 位置：§5 场景 6「自托管 LLM 用户的实验场」
  • 依据：该条已写"行情源仍需外网"，限定是加了的，但位置在句末容易被跳过。建议前置为："支持 Ollama 本地模型（但行情源仍需外网，LLM 不出内网 ≠ 数据不出内网）"

建议 7｜§8 结论里补一句"先验证再扩大"的量化门槛

  • 依据：§8 已建议"配一条纸面交易线跑上几周验证它的建议质量"，但没给通过标准
  • 建议改法：加一个可量化门槛，如"跑满 20–30 个交易日、覆盖 ≥10 次深度分析后，看建议方向与后续 5 日超额收益的一致率是否稳定高于随机基准；不稳定就别调大资金"。§2 场景 5 已提到"决策复盘与预测追踪闭环"正好可作为数据来源，这个建议不需要新数据，是现成的。

四、结论

质量分：8 / 10

加分项：事实准确度极高，抽查 4 个关键点 3 个完全准确、1 个为"漏一个节点"而非编造；免责声明克制且重复到位；坑点清单密集且多为"真会踩"；来源与"待核"分栏诚实。

扣分项：① 核心卖点"九智能体研究链"的描述漏掉 Trader 节点，导致流程链条在关键一环断开（-1.5）；② "九"这个数字沿用第三方转述而未标注来源，与全文严格的官方口径标准不一致（-0.3）；③ 部分"待核"过于保守，明明同源文档已可核（-0.2）。

修改成本极低：P0 只需改两处流程描述（§1、§4.2）并给"九"加个来源限定；P1 三条都是增补，不动主体。建议合入前补完 P0，其余可在后续版本迭代。

本评审仅针对 organized/guides/tnt-likely-panwatch.md 单一文件。核验手段：docs/tradingagents-flow.en.md、docs/timezones.md、README.md / README.zh-CN.md、src/ARCHITECTURE.en.md、GitHub Releases / Tags / API，以及上游 TauricResearch/TradingAgents@v0.7.0/tradingagents/graph/setup.py。未修改被评文件正文、水位、认领记录或任何定时设置。