⚙️ 运行环境契约（最高优先级，先于本文其余内容执行）

本技能可能运行在 QuantBot（QwenPaw 容器） 或宿主机/本地 Claude Code。执行前先探测环境（which docker、API 连通性），并遵守以下映射规则：

1. 后端 API 地址：QwenPaw / 容器网络内一律用 http://quantmind:8000（quantmind 是 docker 网络别名）；仅宿主机调试用 http://127.0.0.1:8000。正文中出现的 127.0.0.1:8000、localhost:800x，在 QwenPaw 环境下自动替换为 http://quantmind:8000。
2. 取数脚本执行：凡 import 了 pandas / duckdb / psycopg2 / numpy / sqlalchemy 等重依赖或 backend 包的脚本，必须在 quantmind 容器内执行（QwenPaw 本地 venv 无这些依赖）：

   docker cp <脚本路径> quantmind:/tmp/<脚本名> && docker exec -w /app quantmind python3 /tmp/<脚本名> <参数>
   

   脚本源三选一：宿主机 repo skills/<name>/scripts/、QwenPaw 工作区 /app/working/workspaces/default/skills/<name>/scripts/、挂载目录 /quantmind/skills/<name>/scripts/。纯标准库脚本（无重依赖）可在 QwenPaw 本地直接跑。
3. 报告落盘：股票报告页可见的 MD/PDF 报告，直接写 /data/reports/trading_agents/{市场或类别}/{股票名}/（/data 是 QwenPaw 与 quantmind 容器共享的可读写挂载，QwenPaw 直接 mkdir/cp 即可，不要 docker cp）；过程数据 facts 写 /data/reports/<类别>/。
4. MD → PDF 转换（按优先级降级）： ① QwenPaw 本地直接跑 python3 /app/backend/scripts/md_to_pdf_report.py <输入.md> <输出.pdf>（扩展镜像已内置 reportlab + 中文字体，研报级排版，首选）； ② QwenPaw 环境缺依赖时，docker exec -w /app quantmind python3 backend/scripts/md_to_pdf_report.py <输入.md> <输出.pdf>（扩展镜像已含 docker CLI）； ③ 以上都不可用时，改用 QwenPaw 内置 pdf 技能把 MD 转成 PDF； ④ 全部失败则只交付 MD，并明确告知用户 PDF 未能生成及原因。
5. 本文中的 ~/.claude、cp -r ... ~/.claude/skills 等说明仅适用于本地 Claude Code 维护者，QuantBot 不要执行。

stock-research — 个股深度研究（多 Agent 框架版）

把 TradingAgents-CN 的多角色投研框架落地到 QuantMind：数据 100% 走本地（QuantDB parquet + PG 新闻富集 + Huntly），新闻双通道（自家 FinBERT 情绪量化 + WebSearch 实时补充），输出研报级 MD + PDF，落盘深度分析目录（报告管理页 → A股市场 → {股票名}）。

与「深度分析某只股票」（后端 TradingAgents 深度分析）不冲突，互为补充：

• 后端深度分析 = TradingAgents 图管线（AI 分析师辩论 → 投资决策报告），在 QuantBot/页面触发，报告落 A股市场/{股票名}/；
• 本 skill = Claude Code 直接编排的多 Agent 版，数据同源（QuantDB + PG），并额外整合了模型推理分数（engine_signal_scores）与新闻类型分布；
• 结论冲突时以数据为准：skill 的每个数字都可在数据包溯源，后端深度分析的报告也可作为第六维参考（用户要求时读 A股市场/{股票名}/ 下已有投研报告交叉验证）。

架构

Phase 1（并行 5 分析师，各读同一份数据包的不同切片）：
  技术面 → 趋势/均线/指标/量价
  新闻面 → 自家 FinBERT 情绪（主）+ WebSearch 实时新闻（辅）
  资金情绪 → L2 主力资金流 + 换手/量能
  基本面 → 估值 + 财务三表核心科目
  市场面 → 大盘背景 + 所属行业强弱 + 板块资金流
Phase 2（并行）：多头研究员 vs 空头研究员（基于 facts 辩论，禁编数据）
Phase 3：研究经理汇总 → 结论（评级/目标区间/风险/跟踪信号）
输出 → md → PDF → 落盘

⚠️ 数据铁律（最高优先级，所有 Agent 必须遵守）

1. 禁止伪造数据：所有价格/PE/财务/资金流数字必须来自数据包 JSON，严禁编造
2. 数据包是唯一数据源：先跑 research_data.py 拿到 {symbol}_{date}.json，各分析师只读该文件对应切片；WebSearch 只允许补充新闻面的时效性（不得用于取行情/财务）
3. 过期标注：数据包 generated_at 距今 >5 个交易日时，报告开头标注 ⚠️ 数据截止 {generated_at}；财报报告期为上季度时注明
4. 单位口径：amount 万元、市值元（估值 JSON 已原样给出，报告统一 亿元=÷1e8）、L2 资金流脚本已转亿元、技术指标 pct_change 为 %
5. 数据缺失不跳过：某段数据为空时在报告「数据可用性」注明，不得用推断值充数
6. Symbol 格式：内部统一后缀格式（600036.SH）；输入任意格式（600036/SH600036/招商银行）由脚本归一化

执行流程（每次 7 步）

第 1 步：跑数据脚本（容器内）

docker cp <repo>/skills/stock-research/scripts/research_data.py quantmind:/tmp/
docker exec quantmind python3 /tmp/research_data.py --symbol 600036.SH
# 输出: /data/reports/stock_research/600036_SH_YYYYMMDD.json（容器内）
docker cp quantmind:/data/reports/stock_research/600036_SH_YYYYMMDD.json /tmp/

数据包含：quote（120 日 K 线/60日高低/20-60日涨幅）、indicators（量纲无关指标：rsi/kdj/macd/乖离率/量能/波动率/return 系列；均线由 K 线计算）、valuation（pe_ttm/pb/ps/市值）、l2_flow（近 10 日主力净流入）、financials（三表最新报告期）、sector（CSRC 一级行业）、market_context（5 指数 + 行业涨幅榜 + 板块资金流 1/5/10 日 + 所属行业）、news（近 60 天 FinBERT 情绪事件 + 来源/标签统计 + 类型分布）、model_score（最新推理 run 的融合/轻量/TFT 分数 + 信号方向 + 预期价 + 全市场分位）。

第 2 步：创建报告目录

mkdir -p /tmp/stock-research/{symbol}/reports

第 3 步：Phase 1 并行启动 5 个分析师（Agent tool，各自独立）

每个 Agent 的 prompt = prompts/{role}.md 内容 + 数据包路径 + 输出路径。并行（同一消息多个 Agent 调用）。输出各自 reports/{role}.md。

• technical.md — 技术面
• news.md — 新闻面（双通道：自家情绪统计为主 + WebSearch 实时为辅）
• sentiment.md — 资金情绪（L2 主力资金流）
• fundamentals.md — 基本面（估值 + 财务）
• market.md — 市场面（大盘 + 行业 + 板块资金）

第 4 步：Phase 2 多空辩论（并行）

bull.md / bear.md：基于 5 份分析师报告 + 数据包，各自构建最强多/空逻辑链。必须引用具体数据，不得空泛。

第 5 步：Phase 3 研究经理汇总（串行）

research_manager.md：读全部 7 份报告，输出最终研究报告（结论/目标区间/风险/跟踪信号）。

第 6 步：md → PDF → 落盘深度分析目录

# PDF（研报风管线，QwenPaw 本地直接执行：扩展镜像已内置 reportlab + 中文字体）
python3 /app/backend/scripts/md_to_pdf_report.py /tmp/stock-research/{symbol}/reports/final.md /tmp/ma_report.pdf

# 落盘（A股市场/{股票名}/，与深度分析报告同列表）
# /data 为 QwenPaw 与 quantmind 共享挂载，直接写入即可被「报告档案」页实时列出
mkdir -p '/data/reports/trading_agents/A股市场/{股票名}'
cp /tmp/stock-research/{symbol}/reports/final.md '/data/reports/trading_agents/A股市场/{股票名}/{股票名}{代码}_2026-08-29_深度研究分析报告.md'
cp /tmp/ma_report.pdf '/data/reports/trading_agents/A股市场/{股票名}/{股票名}{代码}_2026-08-29_深度研究分析报告.pdf'

文件名约定：{股票名}{代码}_{日期}_深度研究分析报告.pdf（与现有深度学习分析报告同格式，便于排序）。

第 7 步：聊天回复速览

3-5 行：结论评级、关键数据（现价/PE/资金/情绪）、主要风险、报告路径。

支持的分析师独立运行

用户指定单个分析师时只跑该角色（如"技术面分析 600519"）：步骤 1 + 3（单 Agent）+ 直接输出该角色报告。

已知边界

• 财务为最新报告期（季度），非实时；估值/技术指标为最新交易日
• 新闻情绪依赖 FinBERT 富集（PG），Huntly 断流时新闻段降级为空并在报告中标注
• 仅支持 A 股（QuantDB 主库）；港股/美股个股研究走其他 skill
• 报告落盘目录为容器 root，宿主机不可写，统一容器内操作