---
name: stock-deep-analysis
description: >
  个股深度分析 — 输入 A 股股票代码或简称，自动从通联 MCP、华泰证券、妙想、iFinD、东方财富等多数据源搜集信息，
  输出三份报告：① 深色赛博科技风 HTML 可视化看板（16 板块完整分析）；② 结构化纯文字摘要（.txt，可粘贴到聊天/邮件）；③ PDF 归档文件（基于 HTML 渲染转换）。
  覆盖行业赛道、财务质量、估值、技术面、资金面、机构观点、风险因素等维度。
  Trigger：用户说"分析XX""深度分析XX""怎么看XX""XX股票分析""诊断XX""帮我看一下XX"等。
triggers:
  - 分析 <股票>
  - 深度分析 <股票>
  - 怎么看 <股票>
  - <股票> 股票分析
  - 诊断 <股票>
  - 帮我看一下 <股票>
  - 从中长期角度分析 <股票>
  - 短线看 <股票>
  - 基本面分析 <股票>
  - 估值分析 <股票>
  - 技术面分析 <股票>
  - 资金面分析 <股票>
  - <股票> 财务分析
  - <股票> 行业分析
agent_created: true
evolved: "2026-07-03"
changelog: "v2.9.0 (2026-07-03): 因果链框架集成 — Step 2 新增批次5(隔夜海外事件监控+跨市场映射); Step 2.7 增强为三层交叉验证(数据精度+多源一致性+正反论据); Step 3.6 纯文字摘要扩展为10-14段(新增股价异动归因/叙事分析/市场结构/策略分层); JSON 新增 trigger_event/narrative_analysis/market_structure/qualitative_judgment 四字段; 第1板块(核心结论)嵌入股价异动归因; 第11板块(催化因素)新增因果链条\nv2.8.1 (2026-06-29): 版式修复 — Step 3 新增硬性约束(禁止 Agent 内联手写 HTML, 必须通过 generate_report.py 脚本生成)；Step 3.5 质量检查新增"脚本生成"和"CSS 完整性"两项(从 12→14 项)；修复 Agent 跳过脚本导致六维评分/因子仪表盘/风险矩阵/催化剂等组件缺失的版式退化问题\nv2.8.0 (2026-06-29): 新增 PDF 输出 — Step 3.6 后新增 Step 3.7(HTML→PDF 转换, 使用 html-to-pdf skill 的 Playwright + Chromium 引擎渲染, A4 纵向 10mm 边距)；Step 3.5 质量自检新增 PDF 验证项；Step 4/5 更新为三文件交付(HTML+TXT+PDF)；描述更新为三份报告\nv2.7.0 (2026-06-25): 安全优化 — 移除 Step 5(上传到网站, 含 SSH 密钥/服务器 IP/.pem 路径/域名等敏感信息); Step 6→5(总结输出改为引用本地文件); Step 7→6(质量自评编号更新); 去除 能力边界 中网站归档描述\nv2.6.1 (2026-06-25): 量化因子行业排名修复 — Step 2.5.3 新增前置检查B(用 hithink-astock-selector 获取同行业股票代码列表→写入 .peer_codes.txt)；提取脚本重写(同时解析股票代码+因子值→全市场排名+行业子集排名→输出 industry_rank_pct)；修复 industry_rank_pct 始终为 N/A 的 bug\nv2.6.0 (2026-06-25): 双产出物架构 — 新增 Step 3.6: 纯文字摘要生成(scripts/generate_text_summary.py, 读取相同JSON数据生成结构化.txt); Step 4/5/6 更新为双文件交付(HTML+.txt); 文字摘要7-11段结构化输出(核心结论→操作参考→免责声明)\nv2.5.2 (2026-06-24): 量化因子数据获取可靠性修复 — 批次4新增数据落地策略(缓存到固定路径.quant_factor_cache.txt); Step 2.5 量化因子提取脚本重写(从JSON文件读取→按股票代码提取→rank_pct转换为生成脚本约定的"优于X%"语义); 修复排名计算bug(因子值排序逻辑与百分比转换); 修复generate_report.py量化因子面板显示bug(后X%→优于X%标的, bar宽度修正)\nv2.5.1 (2026-06-13): 量化因子面板数据缺失修复 — Step 2 新增批次4(华泰量化因子必调); Step 2.5.3 新增前置检查+三级降级方案(华泰失败→hithink技术指标替代→行情自算动量→N/A占位); Step 2.6 强制核查量化因子数据完整性\nv2.5.0 (2026-06-13): 免责声明补充合规关键词(过往业绩不代表未来表现/审慎评估/独立判断); 风险矩阵新增流动性风险与信用风险专项分析字段; 新增「运作保证」章节(幂等性/能力边界/安全防护策略); 显式标注 html.escape XSS防护策略\nv2.4.0 (2026-06-13): 新增 YAML triggers 字段(机器可解析触发词列表); 新增「不适用场景」拒识章节; 新增 MCP 调用监控与日志文档; 新增行业分析模板填充 templates/; 新增研究框架参考文档 references/; 新增 requirements.txt 依赖声明; 确认 XSS 防护已完备(html.escape 全覆盖)\nv2.3.0 (2026-06-12): 新增 evolved字段; 新增 数据源全量失效三层降级策略; 改善 与行业最佳实践对齐\nv2.2.2 (2026-06-12): 新增 HTML 生成后 JS语法验证步骤（node --check，参照 portfolio-analysis 致命级约束）\nv2.2.1 (2026-06-12): +Step 7 执行质量自评与自动进化触发\nv2.2.0 (2026-06-12): +MCP超时/重试策略(Step 2.0) +降级行为协议 +HTML生成后质量自检(Step 3.5)\nv2.1: +数据交叉验证(Step 2.7) +行业专属分析模板(Step 2.8) +数据源优先级强制执行门 +data_verification JSON字段"
version: "2.9.0"
---

# 个股深度分析 (Stock Deep Analysis)

面向 A 股股票的全自动深度分析 Skill。输入股票代码或简称，自动搜集多维度数据，输出专业、精美的 HTML 分析报告。

## 你需要提供的信息

| 必选 / 可选 | 信息项 | 说明 | 示例 |
|:---:|------|------|------|
| ✅ 必选 | **股票代码或简称** | A 股沪深京股票 | `300750` / `宁德时代` / `600519` |
| 可选 | 分析视角 | 短期 / 中期 / 长期 | "中长期角度分析" |
| 可选 | 关注维度 | 基本面 / 技术面 / 估值 / 资金面等 | "重点看估值和资金" |
| 可选 | 对比标的 | 同行对比需求 | "和比亚迪对比" |

> **能力边界**：仅支持 A 股（沪深京），暂不支持港股/美股；分析结论基于公开数据和量化模型，不构成投资建议。

## 触发词

- `分析 宁德时代` / `深度分析 300750` / `怎么看 中际旭创`
- `帮我看一下 XX` / `XX 股票分析` / `诊断 XX`
- `从中长期角度分析 XX` / `短线看 XX`
- `基本面分析 XX` / `估值分析 XX` / `技术面分析 XX` / `资金面分析 XX`
- `XX 财务分析` / `XX 行业分析`

## 不适用场景（拒识）

以下场景**不应触发**本 Skill，应推荐替代方案：

| 场景 | 原因 | 推荐替代 Skill |
|------|------|---------------|
| **港股/美股分析请求** | 数据源仅覆盖 A 股（沪深京），不支持港股/美股 | `overseas-market-data` 或 `westock-data` |
| **仅需单一指标查询** | 本 Skill 为全维度深度分析（7 步工作流），单指标查询开销过大 | `query-indicator` / `hithink-market-query` / `hithink-finance-query` |
| **实时盯盘/盘中快速决策** | 分析总耗时 60-120s，不适合秒级实时场景 | `htsc-daily-review-skill` 或 `ths-advanced-analysis` |
| **基金/ETF 分析** | 本 Skill 仅覆盖个股基本面与技术面分析 | `portfolio-analysis` 或 `hithink-etf-selector` |
| **纯技术面选股/量化筛选** | 本 Skill 聚焦单股深度分析，不涉及多股排序筛选 | `量化因子选股` / `寻风骑龙` / `融盛轨道选股` |
| **宏观策略/大类资产配置** | 本 Skill 聚焦微观个股层面 | `htsc-daily-review-skill` / `overseas-market-tracker` |
| **已退市/ST/*ST 股票** | 退市股与 ST 股数据完整性无法保证，分析结论参考价值有限 | 明确告知用户该标的限制，建议关注基本面正常的标的 |
| **新股/次新股（上市不足 3 个月）** | 财务数据不足 4 期，估值分位无意义 | 建议至少等待 1 个完整财报季后分析 |

## 核心原则

1. **先事实，后判断** — 所有结论必须建立在数据基础之上
2. **先行业，后公司** — 先分析行业景气度、政策、供需格局，再分析公司定位
3. **先逻辑，后估值** — 估值必须结合行业空间、成长性、利润弹性
4. **短期与中长期区分** — 短期(1周~1月)、中期(1~6月)、长期(6月+)分别分析
5. **明确风险提示** — 行业、政策、竞争、估值、股价、财务风险均需覆盖
6. **先因果，后归因**（v2.9.0）— 当个股出现显著涨跌（单日≥3%），必须先识别直接触发事件（导火索），区分"导火索"与"背景因素"，画出"事件→叙事变化→股价影响"的因果链，再进入基本面分析

## 华泰研究框架核心理念（来自 `a-share-stock-deep-analysis` 框架）

| 理念 | 说明 |
|------|------|
| **商业模式是起点** | 先理解公司靠什么挣钱，再看财务数据。数字只是商业模式的结果 |
| **自由现金流是终极标尺** | 利润可以被操纵，但自由现金流很难。FCFF回归企业本质 |
| **护城河决定持续性** | 高ROE只是结果，护城河才是原因。没有护城河的高ROE终将均值回归 |
| **财务报表交叉验证** | 三张表互相印证，四个匹配原则(实际vs报表、同行对比、当期vs历史、项目间匹配) |
| **预测而非描述** | 分析的目的不是描述过去，而是预测未来。关注趋势主因、加强/削弱因素和反转条件 |

---

## 数据优先级策略

> **总优先级链**：通联MCP > 华泰MCP > 华泰证券技能包 > iwencai > 妙想 > 财联社、东方财富网等权威平台
>
> **必须按以下顺序获取数据，上一级数据不足时自动降级：**

### 第一优先：通联数据 MCP（Datayes）

覆盖最全的 A 股结构化数据，优先使用以下通联 MCP 工具：

| 模块 | 通联 MCP Server | 核心接口 |
|------|----------------|---------|
| 股票基本信息 | `stock-info` | `getEqu` — 股票基本信息；`getEquIndustry` — 行业分类 |
| 财务数据 | `stock-finoper` | `getFdmtMainDataLt` — 财务指标；`getFdmtIndiDupontNew` — 杜邦分析；`getFdmtISLT2018` — 合并利润表；`getFdmtBSLT2018` — 合并资产负债表；`getFdmtCFLT2018` — 合并现金流量表；`getEquOperData` — 经营数据 |
| 行情数据 | `stock-mkt` | `getMktEqud` — 日行情；`getMktEqudEval` — 估值信息 |
| 股东/股本 | `stock-eqhld` | `getEquShTen` — 十大股东；`getEquFloatShTen` — 十大流通股东；`getEquShareholderNum` — 股东户数；`getEquSharesFloat` — 限售解禁；`getEquPledge` — 股权质押 |
| 事件数据 | `stock-event` | `getEquShareBuyback` — 回购；`getEquSharesExcit` — 股权激励；`getFdmtEeAllLatest` — 业绩快报；`getFdmtEfV2` — 业绩预告 |
| 资金流向 | `stock-mkt` | `getMktEquMfNew` — 个股资金流向 |

**使用方式**：先调用 `stock_xxx_get_info` 获取接口参数，再调用 `stock_xxx_get_data` 获取数据。

### 第二优先：华泰智研 MCP（htsc_research）— 方法+数据双引擎

> **核心理念**：华泰 MCP 的价值不仅在数据，更在其内置的专业研究框架。数据优先用通联，分析方法用华泰。

#### 2A. 研究框架加载（Step 2.5 时必须执行）

**第一步：列出可用框架** → `list_research_frameworks` 浏览候选

**第二步：加载核心框架**（以下两个框架每次分析必调）：
1. `get_research_framework("a-share-stock-deep-analysis")` — 个股深度分析框架
   - 包含：商业模式分析/财务体检/护城河评估/估值定价/催化剂与风险/综合评级(六维评分)
   - 提供 `available_references` 列表，按需深入加载
2. `get_research_framework("a-share-rotation-allocation")` — 风格/行业轮动框架（辅助行业定位）

**第三步：按需加载 reference 文档**：
- 商业模式深入 → `get_framework_reference("a-share-stock-deep-analysis", "ref-01-business-model")`
- 财务造假排查 → `get_framework_reference("a-share-stock-deep-analysis", "ref-03-fraud-detection")`
- 护城河评估 → `get_framework_reference("a-share-stock-deep-analysis", "ref-04-moat-analysis")`
- 估值方法选型 → `get_framework_reference("a-share-stock-deep-analysis", "ref-05-valuation-methods")`
- 催化剂/预期差 → `get_framework_reference("a-share-stock-deep-analysis", "ref-06-catalyst-expectation")`
- 风险识别体系 → `get_framework_reference("a-share-stock-deep-analysis", "ref-07-risk-detection")`
- ⭐ 个股评级体系 → `get_framework_reference("a-share-stock-deep-analysis", "ref-09-stock-grading")`

#### 2B. 数据接口（补充通联不足）

- `get_industry_sentiment`：行业景气度（优先查二级行业）
- `get_market_emotion`：A股/港股市场情绪指数（默认A）
- `get_a_stock_capital_flow`：A股资金面（散户/ETF/融资/公募/产业资本/一级市场 6 指标）
- `get_quant_factor`：金工因子 — 4因子全量拉取后，在本地计算个股排名/分位/同行对比
- `get_principal_views`：**必须指定 domain** — 资产配置领域→板块13 投资观点；基本面领域→板块3 行业分析

### 第三优先：华泰证券技能包（Hithink）

| 需求 | Hithink Skill |
|------|--------------|
| 行情数据 | `hithink-market-query` |
| 财务数据 | `hithink-finance-query` |
| 行业数据 | `hithink-industry-query` |
| 研报评级 | `hithink-insresearch-query` |
| 经营数据 | `hithink-business-query` |
| 事件数据 | `hithink-event-query` |
| 股东股本 | `hithink-management-query` |

### 第四优先：iwencai

- 使用 `hithink-astock-selector` skill 进行条件选股/对比
- 使用 `hithink-finance-query` 补充财务数据

### 第五优先：妙想

- 使用 `neodata-financial-search` skill 进行自然语言金融搜索
- 使用 `china-ifind` skill 查询财务指标、行情数据

### 第六优先：财联社、东方财富网等权威平台

- **东方财富**：研报、公告、财务数据
- **财联社**：最新资讯、公告解读
- 使用 `news-search` skill 获取最新新闻
- 使用 `WebFetch` 抓取网页数据

### 数据源全量失效三层降级

| 层级 | 触发条件 | 处理方案 |
|------|---------|---------|
| L1 轻度 | 通联MCP不可用 | 降级到华泰MCP → hithink技能包，标注[降级] |
| L2 中度 | 通联+华泰不可用 | neodata + WebSearch，标注"估算值" |
| L3 重度 | 全部不可用 | 标注⚠️，生成简化版HTML仅含标题+日期+免责 |

### 降级行为协议

> **当一级数据源不可用时，按以下固定链自动降级。禁止自行跳跃或混合使用。**

| 当前层 | 触发条件 | 降级动作 | 标注 |
|--------|---------|---------|------|
| 通联 MCP | Timeout / 5xx / 无权限 | ↓ 华泰 MCP | `[DEGRADED: 通联→华泰]` |
| 华泰 MCP | Timeout / 无数据 / 无权限 | ↓ hithink skills | `[DEGRADED: 华泰→hithink]` |
| hithink skills | 调用失败 / 无数据 | ↓ 妙想 (mx-data / mx-search) | `[DEGRADED: hithink→妙想]` |
| 妙想 | 调用失败 / 无数据 | ↓ 东方财富 (WebFetch / news-search) | `[DEGRADED: 妙想→东财]` |
| 东方财富 | 网页不可达 | → 标注 `[DATA_UNAVAILABLE]` | 跳过该字段 |

**降级粒度**：降级以「单个数据字段」为单位，非整个分析。例如：通联 PE 可用但 ROE 超时 → ROE 降级华泰，PE 继续用通联。

---

## 工作流程

### Step 1：识别股票

- 用户输入代码/简称/全称 → 搜索确认股票身份
- 使用 `stock_info_get_info` + `stock_info_get_data(api_name="getEqu", api_parameters={"ticker":"XXXXXX"})` 确认股票基本信息
- 备选：`westock-data search` 或 `hithink-basicinfo-query` 搜索

### Step 2.0：MCP 调用超时与重试策略

> **CRITICAL：所有 MCP 调用必须在以下约束内完成。超时自动触发降级。**

| MCP 服务器 | 单次超时 | 最大重试 | 降级目标 |
|-----------|---------|---------|---------|
| 通联 MCP (所有 server) | 15s | 1 | 华泰 MCP → hithink |
| 华泰 MCP (htsc_research) | 10s | 1 | hithink → iwencai |
| hithink-* skills | 8s | 0 | 妙想 → 东方财富 |

**重试规则**：
- 仅在第一调用返回 `5xx` / `Network Error` / `Timeout` / `无权限` 时重试
- 重试前等待 2 秒
- 两次均失败 → 立即触发降级链，标注 `[DATA_SOURCE_DEGRADED]`
- 禁止无限等待：整个 Step 2（含所有批次）总耗时 ≤ 120s

#### MCP 调用监控与告警

每次 MCP 调用后自动记录以下日志字段，用于事后审计与问题排查：

| 字段 | 说明 | 示例 |
|------|------|------|
| `mcp_server` | 调用的 MCP 服务器名 | `stock-finoper` |
| `api_name` | 接口方法名 | `getFdmtMainDataLt` |
| `latency_ms` | 响应耗时（毫秒） | `320` |
| `status_code` | 返回状态 | `200` / `504` / `timeout` |
| `retry_count` | 重试次数 | `0` / `1` |
| `degraded` | 是否触发降级 | `false` / `华泰→hithink` |
| `data_available` | 是否返回有效数据 | `true` / `false` |

**异常告警规则**：

| 告警级别 | 触发条件 | 动作 |
|---------|---------|------|
| ⚠️ 警告 | 单个 MCP 调用首次超时或返回 5xx | 记录日志，执行 1 次重试，不阻塞流程 |
| 🔶 中等 | 同一 MCP 服务器连续 2 次超时/失败 | 标记 `[DEGRADED]`，自动降级到下一优先级数据源 |
| 🔴 严重 | 三级数据源全部不可用（通联+华泰+hithink） | 标记 `[DATA_UNAVAILABLE]`，跳过该字段并在报告中标注 `N/A` |
| 🚫 致命 | 所有通联 MCP 服务器均不可用（连接/认证失败） | 立即中止 Step 2，切换至 L3 重度降级模式（仅生成简化版 HTML） |
| ⏱️ 总超时 | Step 2 总耗时 ≥ 120s | 强制终止剩余 MCP 调用，进入 Step 2.6 数据完整性核查 |

**日志示例**（Agent 内部记录，不写入用户可见报告）：
```
[MCP:stock-finoper::getFdmtMainDataLt] latency=320ms status=200 retry=0 degraded=false data=true
[MCP:stock-finoper::getFdmtIndiDupontNew] latency=15230ms status=timeout retry=1 degraded=true data=false
[MCP:htsc::get_industry_sentiment] latency=180ms status=200 retry=0 degraded=false data=true  [DATA_SOURCE_DEGRADED: 通联→华泰]
```

### Step 2：并行搜集数据

> ⚠️ **数据源优先级强制执行**：在发起任何数据调用前，必须先确认调用的是当前优先级最高的可用数据源。规则如下：
> 1. 通联 MCP 可用 → 必须先用通联，失败后才能降级到华泰 MCP
> 2. 华泰 MCP 可用 → 通联缺失的字段用华泰补充，不可跳过通联直接用华泰
> 3. 仅在通联+华泰均不可用时，才使用 iwencai / 妙想 / 财联社
> 4. **违规后果**：若发现跳过通联直接调用低级数据源，必须标注 `[DATA_SOURCE_VIOLATION]` 并重新获取

**必须并行调用以下数据源（互不依赖，可同时发起）：**

**批次 1（基础信息+行情，可并行）：**
1. 股票基本信息、行业分类 — `stock-info` MCP (`getEqu`)
2. 最新行情、估值 — `stock-mkt` MCP (`getMktEqud`)
   - ⚠️ **日期范围必须 ≥30 个交易日**（向后回溯），以确保能计算 MA5/MA10/MA20/MA60
   - 同时获取 `PE`/`PB`/`PS`/`marketValue`/`turnoverRate`/`chgPct` 等估值指标
3. 公司简况 — `stock-info` MCP + `hithink-basicinfo-query`

**批次 2（财务，可并行）：**
4. 财务指标（最近4期）— `stock-finoper` MCP (`getFdmtMainDataLt`)
   - 获取：营收/净利润/毛利率/ROE/资产负债率/经营现金流/自由现金流
5. 杜邦分析 — `stock-finoper` MCP (`getFdmtIndiDupontNew`)
   - 获取：ROE拆解(净利率×周转率×杠杆)/ROA/营收/研发费用
6. 利润表数据 — `stock-finoper` MCP (`getFdmtISLT2018`)
   - 获取：营收/归母净利润/基本EPS/营业利润等利润表完整字段
7. 经营数据（主营构成）— `stock-finoper` MCP + `hithink-business-query`

**批次 3（股东+资金+事件，可并行）：**
8. ⭐ **十大股东** — `stock-eqhld` MCP (`getEquShTen`)
   - → 报告字段：`capital.north_flow`（香港中央结算=北向）、`capital.institution_holding`（基金/外资/QFII）、`capital.major_holder_signals`（控股股东/实控人）
9. ⭐ **股东户数趋势** — `stock-eqhld` MCP (`getEquShareholderNum`, 查询近2年)
   - → 报告字段：`capital.shareholders_change`（趋势+方向+幅度）、`risk.risk_matrix`（筹码分散化风险）
10. 股权质押 — `stock-eqhld` MCP (`getEquPledge`, 查询最新)
    - → 报告字段：`capital.major_holder_signals.质押比例`
11. 业绩预告/快报 — `stock-finoper` MCP (`getFdmtEfV2` / `getFdmtEeAllLatest`)
12. 回购/增减持 — `stock-event` MCP (`getEquShareBuyback`)
    - → 报告字段：`capital.major_holder_signals.减持/增持/回购`
13. 资金流向 — `stock-mkt` MCP (`getMktEquMfNew`，近10-20日)
14. ⭐ **融资融券明细** — `stock-mkt` MCP (`getFstDetail`, 查询近20交易日)
    - → 报告字段：`capital.margin_balance`（融资余额趋势+变化幅度）
15. 机构研报 — `hithink-insresearch-query`
16. 最新新闻/公告 — `news-search` skill

**批次 5（隔夜海外事件 — v2.9.0 新增，与批次 1-4 并行）：**
17. **隔夜海外事件监控**（用于股价异动归因）：
    - WebSearch 中英文双语："隔夜美股 [行业关键词] [海外对标公司] 公告 异动" + "overnight US stock [peer company] announcement"
    - 若个股所属行业被跨市场映射表覆盖（参考 hot-topics-tracker 的跨市场映射表），搜索对应的海外龙头公告
    - 输出：{海外事件, 发布时间, 对 A 股对应板块的影响方向, 对目标个股的传导逻辑}

**批次 4（华泰量化因子 — 单独批次，与批次3并行）：**
17. ⭐ **华泰量化因子（4因子全量）** — `htsc_research` MCP (`get_quant_factor`)
    - → 报告字段：`quant_factors.*`
    - ⚠️ **此调用为必选项**，是唯一获取量化因子排名数据的途径
    - ⚠️ **CRITICAL — 数据落地策略**：`get_quant_factor` 返回全市场 5100+ 只股票因子数据（约 645KB），远超上下文窗口。MCP 会自动将结果保存到临时文件。调用后**必须立即执行以下操作**：
      1. 从 MCP 返回的 `output saved to` 路径中获取文件地址
      2. 将该文件复制到工作区固定路径：`<workspace>/.quant_factor_cache.txt`
      3. 如果工具结果未显示保存路径（直接截断），使用 `Grep` 搜索 `get_quant_factor` 在 `<workspace>/../*/tool-results/` 下的最新文件
      4. **禁止跳过此落地步骤**——后续 Step 2.5 必须从此缓存文件读取
    - 拉取全市场最新一期 4 因子原始数据，用于 Step 2.5 中本地计算个股排名/分位
    - 若华泰 MCP 不可用 → 降级：使用 `hithink-market-query` 获取技术指标替代（如 RSI/MACD 等作为简易替代）

#### 📋 数据→报告字段速查表

> **此表用于 Step 3 组装 JSON 时对照使用，确保每个报告字段都有对应的 MCP 调用支撑。**

| 报告字段 | MCP 服务器 | API 接口 | 说明 |
|---------|-----------|---------|------|
| `stock.*` 基本信息 | `stock-info` | `getEqu` | 名称/代码/行业/市值/流通股本 |
| `technical.ma5/ma20/ma60` | `stock-mkt` | `getMktEqud`(≥30日) | 本地计算均值 |
| `technical.trend/support/resistance` | `stock-mkt` | `getMktEqud`(近5日) | 基于走势判断 |
| `valuation.pe_ttm/pb/ps_ttm` | `stock-mkt` | `getMktEqud` | 行情自带PE/PB |
| `valuation.pe_percentile_5y` | `stock-mkt` | `getMktEqudEval` | 估值分位 |
| `finance.*` 财务指标 | `stock-finoper` | `getFdmtMainDataLt` | 营收/利润/ROE/毛利率/现金流等 |
| `finance.dupont` | `stock-finoper` | `getFdmtIndiDupontNew` | ROE杜邦拆解 |
| `finance.revenue/net_profit` | `stock-finoper` | `getFdmtISLT2018` | 利润表(含EPS) |
| `capital.north_flow` (北向) | `stock-eqhld` | `getEquShTen` | 找"香港中央结算"持股比例 |
| `capital.institution_holding` (机构) | `stock-eqhld` | `getEquShTen` | 基金/外资/QFII持股汇总 |
| `capital.major_holder_signals` | `stock-eqhld` + `stock-event` | `getEquShTen` + `getEquPledge` + `getEquShareBuyback` | 控股/实控人+质押+回购增减持 |
| `capital.shareholders_change` | `stock-eqhld` | `getEquShareholderNum` | 近2年股东户数趋势 |
| `capital.margin_balance` (融资) | `stock-mkt` | `getFstDetail`(≥15日) | 融资余额趋势+变化方向 |
| `peers.*` 同行对比 | `hithink-astock-selector` / `hithink-finance-query` | — | 同行业筛选+财务对比 |
| `industry_analysis` (行业分析) | `htsc_research` + `hithink-industry-query` | `get_industry_sentiment` | 行业景气度+趋势判断 |
| `advantages` | 综合分析 | — | 公司核心竞争优势（文本） |
| `growth_analysis` | 综合分析 | — | 成长逻辑：确定性与想象空间（文本，**必填**） |
| `framework_insights.*` | `htsc_research` | `get_research_framework` / `get_market_emotion` / `get_a_stock_capital_flow` | 框架洞见+情绪+资金面 |
| `quant_factors.*` | `htsc_research` | `get_quant_factor` (批次4) | 4因子排名/分位(本地计算，含全市场+行业排名)；需要 `hithink-astock-selector` 提供同行业代码列表 |
| `opinion.principal_asset_view` | `htsc_research` | `get_principal_views(domain="资产配置")` | 华泰首席观点 |
| `catalysts` | `stock-event` + `news-search` | `getFdmtEfV2` + `news-search` | 业绩预告+新闻驱动事件 |

### Step 2.5：加载华泰研究框架 + 生成分析洞察

> **CRITICAL：此步骤在数据搜集完成后、报告生成前执行。** 框架提供分析"方法论"，数据提供分析"素材"。

**必须执行的操作：**

1. **加载个股深度分析框架**：
   ```
   get_research_framework("a-share-stock-deep-analysis")
   ```
   从返回的 `available_references` 中，根据个股特征选择加载：
   - ⭐ **必选** `ref-09-stock-grading` — 六维评级体系（100% 个例都需要）
   - **必选** `ref-05-valuation-methods` — 估值方法选型
   - **必选** `ref-07-risk-detection` — 风险识别与预警
   - 财务疑点多 → `ref-03-fraud-detection`
   - 护城河模糊 → `ref-04-moat-analysis`
   - 有重大催化剂 → `ref-06-catalyst-expectation`

2. **加载轮动框架（辅助行业定位）**：
   ```
   get_research_framework("a-share-rotation-allocation")
   ```
   用于判断当前风格环境是否利于该个股所属行业。

3. **量化因子排名计算**（基于批次 4 获取的 `get_quant_factor` 数据）：
   - ⚠️ **CRITICAL：此步骤不可跳过。**
   - **前置检查 A — 缓存文件**：确认批次 4 中 `get_quant_factor` 返回了有效数据且已落地到 `<workspace>/.quant_factor_cache.txt`：
     - ✅ 缓存文件存在 → 跳至前置检查 B
     - ❌ 缓存文件不存在 → 搜索 tool-results 目录下最新 `get_quant_factor-*.txt`，复制到缓存路径后执行
     - ❌ 完全无数据（超时/无权限/降级失败）→ 使用降级方案
   - **前置检查 B — 同行业股票代码列表（新增）**：
     - ⚠️ **必须执行**：在提取脚本运行前，使用 `hithink-astock-selector` 查询"申万二级行业为 `{industry_l2}` 的所有 A 股"，将返回的股票代码列表写入 `<workspace>/.peer_codes.txt`（每行一个代码）
     - hithink 不可用 → 降级：使用 `westock-tool` filter 模式按行业筛选
     - 全部失败 → 文件写空，脚本内 `industry_rank_pct` 自动填 `null`
   - **标准提取脚本**（一次性完成提取+排名+转换，同时计算全市场 + 行业排名）：
     
   ```python
   import json, os
   
   target_code = "<股票代码>"  # 替换
   cache = "<workspace>/.quant_factor_cache.txt"  # 替换为实际路径
   peer_file = "<workspace>/.peer_codes.txt"  # 同行业代码列表
   
   if not os.path.exists(cache):
       import glob
       candidates = glob.glob("<workspace>/../*/tool-results/*get_quant_factor*.txt")
       if candidates: cache = max(candidates, key=os.path.getmtime)
       else: raise FileNotFoundError("quant factor cache not found")
   
   # 加载同行业股票代码集合
   peer_set = set()
   if os.path.exists(peer_file):
       with open(peer_file, 'r', encoding='utf-8') as f:
           for line in f:
               code = line.strip()
               if code and not code.startswith('#'):
                   peer_set.add(code)
   
   with open(cache, 'r', encoding='utf-8') as f:
       raw = json.load(f)
   
   data_str = raw.get('data', '')
   sections = data_str.split('## ')
   results = {}
   
   for section in sections:
       if not section.strip(): continue
       lines = section.strip().split('\n')
       factor_name = lines[0].strip()
       all_entries = []  # (code, value) 元组
       target_val = None
       # 跳过表头行
       for line in lines:
           if '|' not in line or '---' in line or '股票名称' in line:
               continue
           parts = [p.strip() for p in line.split('|')]
           if len(parts) < 4: continue
           code_in_line = parts[1] if len(parts) >= 2 else ''
           val_str = parts[3] if len(parts) >= 4 else ''
           try:
               val = float(val_str)
               all_entries.append((code_in_line, val))
               if code_in_line == target_code:
                   target_val = val
           except (ValueError, TypeError):
               pass
       
       if target_val is not None and all_entries:
           # 全市场排名
           all_vals = [v for _, v in all_entries]
           all_vals.sort()
           global_rank = sum(1 for v in all_vals if v > target_val) + 1
           global_pct = round(100 - global_rank / len(all_vals) * 100, 1)
           
           # 行业排名（同行业子集内排序）
           peer_vals = [v for c, v in all_entries if c in peer_set]
           if peer_vals:
               peer_vals.sort()
               peer_rank = sum(1 for v in peer_vals if v > target_val) + 1
               industry_pct = round(100 - peer_rank / len(peer_vals) * 100, 1)
           else:
               industry_pct = None
           
           results[factor_name] = {
               'value': target_val,
               'rank_pct': global_pct,        # 全市场：优于 X% 标的
               'total': len(all_vals),
               'industry_rank_pct': industry_pct,  # 行业：优于 X% 同行业标的
               'industry_total': len(peer_vals) if peer_vals else 0
           }
       elif target_val is not None:
           results[factor_name] = {
               'value': target_val,
               'rank_pct': None, 'total': 0,
               'industry_rank_pct': None, 'industry_total': 0
           }
       else:
           results[factor_name] = {
               'value': None,
               'rank_pct': None, 'total': 0,
               'industry_rank_pct': None, 'industry_total': 0
           }
   
   print(json.dumps(results, ensure_ascii=False, indent=2))
   ```
   
   - **rank_pct 语义说明**：`get_quant_factor` 返回的原始排名是"第X名/共N只"（值越小越好），需转换为"优于 (100 - X/N*100)% 标的"以适应 `generate_report.py` 的显示约定
   - **industry_rank_pct 语义说明**：同上，但仅在同行业子集内计算，"优于 X% 同行业标的"
   - 记录 4 因子中 `rank_pct ≥ 80`（高亮/优秀）或 `rank_pct ≤ 20`（警示/弱势）的因子

4. **首席观点定向引用**：
   ```
   get_principal_views(domain="资产配置")  → 写入板块13
   get_principal_views(domain="基本面")    → 写入板块3
   ```

5. **根据框架方法论，在 JSON 数据中补充以下字段**：
   - `grading` — 六维评分（见下方数据结构）
   - `moat` — 护城河分析
   - `industry_analysis` — 行业与赛道分析（dict 格式，含 sector_position/space/trend/drivers/competition/barriers/cycle）
   - `advantages` — 公司核心竞争优势分析（文本）
   - `growth_analysis` — 成长逻辑分析（确定性与想象空间双维度，文本，**不能为空**）
   - `risk.risk_matrix` — 三层风险分类
   - `quant_factors` — 量化因子排名/分位
   - `framework_insights` — 框架分析洞见

### Step 2.6：数据完整性核查（JSON 写入前强制执行）

> **CRITICAL：此步骤在组装 JSON 之前执行，确保所有必填字段有数据源支撑。**

逐项检查以下清单，缺失项立即补调数据源：

| 检查项 | 对应 MCP 调用 | 关键字段 |
|--------|-------------|---------|
| ☐ 股票身份 | `stock-info/getEqu` + `getEquIndustry` | name/code/industry |
| ☐ 行情+估值 | `stock-mkt/getMktEqud`(≥30日) | PE/PB/PS/close/MA5/MA20/MA60 |
| ☐ 财务指标 | `stock-finoper/getFdmtMainDataLt` | revenue/net_profit/gross_margin/ROE/debt_ratio/FCFF |
| ☐ 杜邦分析 | `stock-finoper/getFdmtIndiDupontNew` | ROE拆解(净利率/周转率/杠杆) |
| ☐ 利润表 | `stock-finoper/getFdmtISLT2018` | 营收/归母净利润/EPS |
| ☐ 主营构成 | `stock-finoper/getFdmtMoStdItem` 或经营数据 | 各产品线收入+毛利率 |
| ☐ 十大股东 | `stock-eqhld/getEquShTen` | 北向/机构/实控人持股 |
| ☐ 股东户数 | `stock-eqhld/getEquShareholderNum`(≥2年) | 筹码集中度趋势 |
| ☐ 质押 | `stock-eqhld/getEquPledge` | 质押比例 |
| ☐ 资金流向 | `stock-mkt/getMktEquMfNew`(≥10日) | 主力/散户净流向 |
| ☐ **融资余额** | `stock-mkt/getFstDetail`(≥15日) | 融资余额趋势+变化幅度 |
| ☐ 业绩预告/快报 | `stock-finoper/getFdmtEfV2` + `getFdmtEeAllLatest` | 预期业绩 |
| ☐ 回购/增减持 | `stock-event/getEquShareBuyback` | 回购/增减持信号 |
| ☐ **量化因子** | `htsc/get_quant_factor`(4因子全量，**批次4必调**) | 排名/分位计算；不可用→执行降级方案 |
| ☐ 行业景气度 | `htsc/get_industry_sentiment` | 行业景气度评分 |
| ☐ 市场情绪 | `htsc/get_market_emotion` | 市场情绪指数 |

> **缺失处理规则**：若某项数据源返回空或无权限，在 JSON 对应字段标注 `"N/A"` 或 `null`，不得留空字符串。generate_report.py 已适配 `null` 值渲染。

### Step 2.7：数据交叉验证（三层，v2.9.0 扩展）

> **CRITICAL：Step 2.6 通过后，必须进行三层交叉验证。**

#### 第一层：数据精度验证（保留原有）

| 关键指标 | 主数据源 | 交叉验证源 | 允许偏差 | 处理规则 |
|---------|---------|-----------|---------|---------|
| 营收 | `getFdmtISLT2018` (通联) | `getFdmtMainDataLt` (通联) + `hithink-finance-query` | ≤ 5% | 偏差>5%→标注为估计值 |
| 归母净利润 | `getFdmtISLT2018` | `getFdmtMainDataLt` + `hithink-finance-query` | ≤ 5% | 偏差>5%→二次确认 |
| ROE | `getFdmtMainDataLt` | `getFdmtIndiDupontNew`(杜邦反算) | ≤ 2pp | 偏差>2pp→标注差异原因 |
| PE / PB | `getMktEqud` (通联) | `getMktEqudEval` (通联) + `hithink-market-query` | ≤ 10% | 偏差>10%→使用通联数据并标注 |
| 毛利率 | `getFdmtMainDataLt` | `getFdmtISLT2018`(收入-成本)/收入 | ≤ 3pp | 按通联主数据源为准 |
| 行业分类 | `getEquIndustry` (通联) | `hithink-basicinfo-query` + `get_industry_sentiment` | — | 不一致→以通联申万分类为准 |

#### 第二层：多源一致性验证（保留原有）

> 验证流程和 JSON 字段同 v2.8.1，无变化。

#### 第三层：正反论据交叉验证（v2.9.0 新增）

> 对个股的核心投资逻辑进行正反双向检验，防止确认偏误。

| 检验项 | 正向证据 | 反向证据 | 权重判断 |
|--------|---------|---------|---------|
| 行业景气度 | 通联/华泰行业景气数据 | 是否有反向数据（如海外龙头指引下调、价格回落） | 综合权重 |
| 公司竞争力 | 护城河评分+财务数据 | 竞争格局恶化信号（份额下降、毛利率承压） | 综合权重 |
| 估值合理性 | PE分位+PEG+DCF | 是否有估值陷阱（盈利不可持续、周期性高PE） | 综合权重 |
| 近期催化 | 已确认催化剂 | 催化剂是否已充分定价？是否有利好出尽风险？ | 综合权重 |

**输出格式**（写入 JSON 新字段 `narrative_analysis`）：
> "我们认为，[个股]的核心逻辑[得到强化/部分修正/面临挑战]。支持信号：[1-2条]，反向信号：[1-2条或'当前未发现明确反向证据']。综合判断：[维持/上调/下调]。"

> **JSON 新增字段**：`trigger_event`, `narrative_analysis`, `market_structure`, `qualitative_judgment`

### Step 2.8：行业专属分析模板选择

> **CRITICAL：不同行业的分析逻辑截然不同。必须根据股票所属行业选择对应的分析模板，避免用白酒逻辑分析半导体。**

| 行业类型 | 行业关键词 | 分析重点 | 估值方法偏好 | 关键风险 |
|---------|-----------|---------|-------------|---------|
| **消费品牌** | 白酒/食品/饮料/乳品/调味/家电 | 品牌护城河、渠道力、提价能力 | PE + DCF | 消费降级、渠道变革 |
| **硬科技** | 半导体/芯片/集成电路/晶圆/光刻 | 技术代差、国产替代进度、研发投入 | PS + EV/EBITDA | 技术封锁、产能过剩 |
| **新能源** | 电池/锂电/光伏/储能/风电 | 产能周期、价格战格局、海外拓展 | PE + 产能估值 | 产能过剩、原材料波动 |
| **金融** | 银行/保险/证券/券商/信托 | 净息差、不良率、拨备覆盖率 | PB + ROE-PB | 利率政策、房地产敞口 |
| **医药** | 医药/制药/生物/医疗/疫苗/CRO | 管线价值、集采影响、出海进展 | DCF + Pipeline | 集采、临床失败 |
| **周期资源** | 铜/金/铝/钢铁/化工/煤炭/石油 | 商品价格周期、成本曲线、储量 | EV/EBITDA + NAV | 价格下行、矿山风险 |
| **智能制造** | 机械/机器人/工业母机/自动化 | 国产替代、订单周期、下游景气 | PE + PEG | 制造业周期、竞争加剧 |
| **TMT** | 计算机/软件/AI/云计算/通信/5G | 客户粘性、ARR增速、研发效率 | PS + EV/Revenue | 技术迭代、客户流失 |

**使用方式**：
- 在 Step 2.5 加载完华泰框架后，根据行业关键词匹配上表
- 将匹配到的分析重点、估值方法偏好、关键风险融入分析
- 在 JSON 的 `industry_analysis` 中标注使用的模板类型

**使用 Python 脚本生成**，脚本位于 `~/.workbuddy/skills/stock-deep-analysis/scripts/generate_report.py`

> 🚫 **致命约束（CRITICAL — 违反将导致版式错误）**：
> - **HTML 必须且仅能通过 `generate_report.py` 脚本生成。绝对禁止 Agent 自行内联写 HTML（如直接在对话中用代码块或 Write 工具输出 HTML）。**
> - 原因：脚本内嵌了完整的深色赛博科技风 CSS（360 行）、六维评分总览卡、量化因子仪表盘、三层风险矩阵等组件。Agent 手写的 HTML 缺失这些组件，导致版式退化。
> - 违反检查方法：生成后搜索 `grading-card` / `grade-badge` / `factor-grid` / `dcf-extra` / `catalyst-list` / `back-top` 关键词，任一项缺失即为违规生成。

> ⚠️ **路径注意事项**：
> - JSON 数据文件**必须使用绝对路径**（Windows 下如 `C:\Users\...\data.json`），`/tmp/` 在 Git Bash 和 PowerShell 间路径映射不一致
> - 确认 `--data-file` 指向的 JSON 文件已成功写入且编码为 UTF-8（无 BOM）
> - PowerShell 下建议使用 `&` 调用运算符执行 Python 脚本

```bash
cd ~/.workbuddy/skills/stock-deep-analysis
python scripts/generate_report.py \
  --name "宁德时代" \
  --code "300750" \
  --industry "电力设备-电池" \
  --data-file /path/to/stock_analysis_data.json
```

> ⚠️ **生成后必须验证**：执行 `ls -l` 检查输出文件的修改时间是否已更新，或搜索 `factor-value` 关键字确认量化因子等关键数据已渲染。避免因脚本静默失败使用旧版缓存 HTML。

**数据准备**：先将搜集到的所有数据（含 Step 2.5 的分析洞察）整理为 JSON 文件（`/tmp/stock_analysis_data.json`），结构见下方「数据结构」章节。

**HTML 特性（参照 yanbao-center 版式）：**
- 🌌 深色赛博科技风主题（`#06080d` 底色）
- 💎 玻璃态（Glassmorphism）卡片：`rgba(15,22,45,0.85)` + `backdrop-filter: blur(20px)`
- ✨ 星空粒子 + 网格线背景
- 🎨 霓虹配色：青 `#00d4ff`、紫 `#7b2fff`、绿 `#00ff88`、金 `#ffd700`
- 📊 数字渐变发光标题
- 🆕 **六维评分总览卡**（评级徽章 S/A/B/C/D + 综合得分 + 一票否决标记）
- 🆕 **量化因子仪表盘**（4因子全市场排名/分位/行业对比 + 高亮/警示）
- 🆕 **三层风险矩阵面板**（致命/重大/可管理 + 预警指标状态灯）
- 📋 结构化分节：核心结论 → 基本面 → 财务 → 估值 → 技术 → 量化因子 → 资金 → 风险 → 观点
- 📈 数据表格、红涨绿跌配色
- 🔗 跳转锚点导航栏
- 📱 响应式布局，移动端适配
- ⬆️ 回到顶部按钮
- 🛡️ 底部免责声明（含华泰智研数据来源声明 + 风险揭示）

### Step 3.5：HTML 生成后质量自检（强制执行）

> **CRITICAL：预览和上传前，逐项检查以下清单。任一项不通过 → 退回修复。**

| 检查项 | 检查方法 | 不通过处理 |
|--------|---------|-----------|
| ☐ 脚本生成 | 搜索 `grading-card` 存在（非 Agent 手写） | **必须重跑 `generate_report.py`，禁止手写 HTML** |
| ☐ CSS 完整性 | 搜索 `grade-badge` / `factor-grid` / `dcf-extra` / `catalyst-list` / `back-top` 均存在 | 回退至脚本生成 |
| ☐ 16 板块完整性 | 搜索 `<div class="section"` 出现 ≥ 14 次 | 缺失板块用 `N/A` 占位 |
| ☐ 六维评分卡存在 | 搜索 `grading` / `overall_grade` 关键字 | 补充评分 JSON 重生成 |
| ☐ 风险矩阵三层 | 搜索 `fatal` / `major` / `manageable` | 补充风险分级数据 |
| ☐ 量化因子面板 | 搜索 `quant_factors` / `rank_pct` | 因子缺失填 `null` |
| ☐ 免责声明完整 | 搜索 `华泰智研数据服务` + `不构成投资建议` | 追加声明模板 |
| ☐ 数据日期标注 | 搜索 `数据截止` / `data_date` | 补充日期字符串 |
| ☐ 无占位符残留 | 搜索 `TODO` / `FIXME` / `待补充` | 删除或替换为实际内容 |
| ☐ HTML 可自包含打开 | 浏览器直接打开 HTML 不报错 | 修复 CSS/JS 引用 |
| ☐ JS语法正确 | node --check验证通过 | 修复语法 |
| ☐ 数据源标注完整 | 每个数据点标注来源层级 | 补充来源 |
| ☐ 文件实际更新 | 检查 HTML 修改时间 ≥ 脚本执行时间；搜索 `factor-value` 不为全 N/A | 重新执行生成脚本 |
| ☐ PDF 生成成功 | 检查 PDF 文件存在且 size > 100KB；搜索 PDF 中 `六维评分` 关键词确认内容完整 | 重试转换或标注 `[PDF_FAILED]` |

### Step 3.6：生成纯文字摘要 ⭐

> **CRITICAL：HTML 质量检查通过后，立即生成纯文字摘要。三份产出物共享同一份 JSON 数据文件。**

**脚本**：`~/.workbuddy/skills/stock-deep-analysis/scripts/generate_text_summary.py`

```bash
cd ~/.workbuddy/skills/stock-deep-analysis
python scripts/generate_text_summary.py \
  --name "宁德时代" \
  --code "300750" \
  --data-file /path/to/stock_analysis_data.json
```

**产出物**：`stock_analysis_{code}_{date}.txt`，与 HTML 同级目录。

**文字摘要结构**（10-14 段，v2.9.0 扩展，视量化因子有无动态调整）：1. 核心结论（六维评级+定性判断+亮点/风险）；2. **股价异动归因**（v2.9.0 NEW — 若近期涨跌幅≥3%：导火索事件→叙事变化→股价影响因果链）；3. **叙事与交叉验证**（v2.9.0 NEW — 新旧叙事对比+正反论据+综合判断）；4. 行业与竞争（产业链位置+空间+护城河+成长逻辑）；5. **市场结构与策略分层**（v2.9.0 NEW — 业绩窗口/板块拥挤度/宏观背景+仓位分层策略建议）；6. 财务质量（营收/利润/毛利率/ROE/现金流+杜邦拆解+造假排查）；7. 估值水平（PE/PB/PS/分位+PEG+DCF+同行对比表）；8. 技术走势（趋势/支撑压力/均线/量能）；9. 量化因子（如有，4因子排名分位）；10. 资金与筹码（主力/北向/融资/股东户数/机构）；11. 催化因素（含因果链，v2.9.0）；12. 风险因素（三层矩阵+预警指标）；13. 投资观点（短/中/长+框架洞察）；14. 操作参考（买入/加仓/止损/目标/一票否决）；15. 免责声明。

> **纯文字摘要用途**：可直接复制粘贴到微信/邮件/文档中使用，无需浏览器打开。适合快速分享核心结论。

### Step 3.7：生成 PDF 归档文件 ⭐

> **CRITICAL：纯文字摘要生成完毕后，立即将 HTML 报告转换为 PDF。使用 `html-to-pdf` skill 的 Playwright + Chromium 引擎，确保所有 JS 图表和 CSS 样式被完整捕获。**

**转换命令**：

```bash
node "C:\Users\98322\.workbuddy\skills\html-to-pdf\scripts\html_to_pdf.mjs" \
  "<workspace>\stock_analysis_{code}_{date}.html" \
  "<workspace>\stock_analysis_{code}_{date}.pdf" \
  --page-size A4 \
  --margin 10
```

**参数说明**：
- `--page-size A4`：标准 A4 纵向，适合长篇分析报告
- `--margin 10`：10mm 四周边距，保证图表和文字不被裁切
- 无需 `--landscape`：报告以纵向排版为主
- 无需 `--no-header-footer`：保留页眉页脚便于阅读（页码/文件名）

**PDF 特性**：
- 完整捕获 Chart.js 图表（雷达图、走势图等）
- CSS Grid/Flexbox 布局完整保留
- 霓虹配色与赛博科技风格高保真渲染
- 输出文件与 HTML 同级目录，命名一致（仅后缀不同）

**故障处理**：
- Chromium 未安装 → 执行 `npx playwright install chromium`，重试一次
- 转换超时 (30s) → 检查 HTML 是否有外部资源引用，重试一次
- 两次均失败 → PDF 跳过，Step 5 输出中标注 `[PDF_GENERATION_FAILED]`，不影响 HTML 和 TXT 交付

### Step 4：预览报告

**CRITICAL：生成 HTML、TXT 和 PDF 后，必须使用 `present_files` 工具同时预览三份文件，HTML 放在首位以触发浏览器预览。** 同时用简洁文字概括分析核心结论（200 字以内）。

### Step 5：总结输出

用简洁文字告知用户：
- **可视化报告**：本地 HTML 文件路径 + 已通过 `present_files` 预览
- **纯文字摘要**：本地 TXT 文件路径，可直接复制文字内容到微信/邮件中使用
- **PDF 归档**：本地 PDF 文件路径，可直接打印或邮件发送
- 核心结论概要（200 字以内）

### Step 6：执行质量自评与自动进化触发

> **CRITICAL：每次分析完成后强制执行。这是自进化系统的"感知层"——让 Skill 自己知道做得好不好。**

执行结束后，Agent 自行评估本次执行质量，记录到 HealthMonitor：

```bash
python "C:\Users\98322\WorkBuddy\2026-06-12-09-14-55\evoskill-bridge\record_execution.py" \
  --skill stock-deep-analysis \
  --mcp-total <MCP 总调用数> \
  --mcp-degraded <降级次数> \
  --mcp-timeout <超时次数> \
  --checklist-pass <Step 3.5 通过项数，0-14> \
  --total-time-s <总耗时秒数>
```

**评分计算**（脚本自动完成）：
| 指标 | 权重 | 满分条件 | 扣分规则 |
|------|------|---------|---------|
| MCP 成功率 | 40% | 0 次降级 | 每 1 次降级 -8 分 |
| MCP 超时率 | 20% | 0 次超时 | 每 1 次超时 -10 分 |
| 质量检查通过率 | 30% | 14/14 全通过 | 每缺 1 项 -3 分 |
| 执行效率 | 10% | ≤ 120s | 每超 20s -3 分 |

**自动进化触发阈值**：

| 评分 | 状态 | 行为 |
|------|------|------|
| ≥ 85 | ✅ Healthy | 仅记录，不触发进化 |
| 60–84 | ⚠️ Degraded | 标记状态，下次对话开始时提示"建议进化" |
| < 60 | 🔴 Critical | 标记状态，下次对话**自动触发进化循环** |

**Agent 执行清单**：
1. 统计本次分析中各数据源的调用结果（查对话中的 `[DEGRADED]` / `[DATA_UNAVAILABLE]` 标记数）
2. 确认 Step 3.5 质量检查结果（所有 14 项是否通过）
3. 计算总耗时
4. 运行 `record_execution.py` 写入 HealthMonitor
5. 如果评分 < 85，在回复末尾附上提示：`⚠️ 本次执行质量评分 XX，建议下次对话时运行 "进化 stock-deep-analysis"`

---

## 输出结构

生成的 HTML 报告严格按以下 16 个板块组织：

1. **核心结论** — ⭐ 六维评分总览 + 一句话定性 + 关键速览卡 + **股价异动归因卡片**（v2.9.0，若个股近5日涨跌幅≥3%则展示）
2. **公司基本情况** — 主营业务、收入结构、产业链位置、商业模式速写
3. **行业与赛道分析** — 景气度(华泰二级行业)、空间、增速、政策、竞争格局、轮动环境
4. **公司竞争优势** — 护城河评估(转换成本/网络效应/成本优势/无形资产/规模优势)
5. **财务质量分析** — 杜邦拆解ROE、自由现金流、三表交叉验证、财务造假排查(M-Score/红旗指标)
6. **成长逻辑分析** — 确定性增长 vs 想象空间
7. **估值分析** — 行业适配估值方法 + PE/PB/PS/PEG + 历史分位 + DCF参考 + 同行对比 + 安全边际
8. **技术走势分析** — 趋势/均线/支撑压力/指标
9. **资金与筹码分析** — 主力/北向/融资融券/机构持仓/股东户数 + 大股东行为信号
10. **量化因子面板** — 🆕 4因子仪表盘（全市场排名/分位/行业对比）
11. **近期催化因素** — 已发生 + 潜在催化剂 + 预期差分析 + **因果链（v2.9.0：事件→叙事变化→股价影响）**
12. **风险因素** — 🆕 三层风险矩阵(致命/重大/可管理) + 财务预警指标 + 大股东监控
13. **投资观点** — 短期/中期/长期分别论述 + 华泰首席策略观点(资产配置domain)
14. **操作参考** — 买入区间/加仓条件/止损位/止盈思路 + 一票否决触发条件
15. **跟踪指标** — 后续需关注的关键指标清单
16. **总结** — 核心观点重申 + ⭐ 六维评分雷达图 + 免责声明

---

## 数据结构

传递给 Python 脚本的 JSON 数据结构示例：

```json
{
  "stock": {
    "name": "宁德时代",
    "code": "300750",
    "market": "sz",
    "industry_l1": "电力设备",
    "industry_l2": "电池",
    "market_cap": 890000000000,
    "float_cap": 450000000000,
    "turnover_rate": 2.5
  },
  "summary": {
    "conclusion": "中长期看好，短期估值偏高需等待回调",
    "rating_short": "中性偏谨慎",
    "rating_mid": "看好",
    "rating_long": "强烈看好",
    "highlights": ["全球动力电池龙头", "储能业务高增长", "技术壁垒深厚"],
    "main_risk": "行业产能过剩导致价格战"
  },
  "grading": {
    "overall_score": 7.2,
    "overall_grade": "A",
    "grade_desc": "推荐",
    "dimensions": {
      "business_model": {"score": 7.5, "weight": 15, "comment": "龙头地位稳固，产业链议价权强"},
      "financial_quality": {"score": 7.8, "weight": 20, "comment": "ROE持续>15%，现金流充裕"},
      "moat": {"score": 8.0, "weight": 20, "comment": "成本优势+规模壁垒+技术迭代领先"},
      "valuation": {"score": 6.0, "weight": 20, "comment": "PE-TTM 25x，历史分位35%，估值中性"},
      "catalyst": {"score": 7.5, "weight": 15, "comment": "储能海外订单+固态电池进展"},
      "risk": {"score": 6.5, "weight": 10, "comment": "产能过剩风险+锂价波动"}
    },
    "veto_flags": [],
    "adjustments": [
      {"type": "减分", "value": -0.5, "reason": "大股东质押比例偏高"},
      {"type": "加分", "value": 0.3, "reason": "公司持续回购"}
    ]
  },
  "industry_analysis": {
    "sector_position": "赛道在产业链中的位置及议价权...",
    "space": "行业空间与增速（TAM/渗透率/CAGR）...",
    "trend": "行业趋势与景气度方向...",
    "drivers": "增长驱动因素（政策/技术/需求）...",
    "competition": "竞争格局与市场份额分布...",
    "barriers": "进入壁垒（资金/技术/牌照/客户）...",
    "cycle": "行业周期位置（导入/成长/成熟/衰退）..."
  },
  "advantages": "公司核心竞争优势分析...",
  "growth_analysis": "成长逻辑双维度拆解：（1）确定性增长——现有业务营收/利润/市占率的量化增速预期及可持续性；（2）想象空间——新业务/新市场的潜在TAM、实现路径与时间节点；（3）成长质量——增长是否以牺牲利润率为代价、是否需要大量资本开支、现金流是否同步增长。综合判断：强/中/弱。",
  "moat": {
    "categories": ["成本优势", "规模优势"],
    "depth": "deep",
    "sustainability": "高",
    "description": "全球最大动力电池厂商，规模效应显著; 上游锂矿自供率提升降低外购依赖"
  },
  "finance": {
    "revenue": [{"period": "2025Q1", "value": 890.5}, {"period": "2024Q1", "value": 810.2}],
    "net_profit": [{"period": "2025Q1", "value": 105.2}, {"period": "2024Q1", "value": 98.5}],
    "gross_margin": [{"period": "2025Q1", "value": 22.5}],
    "roe": [{"period": "2025Q1", "value": 15.8}],
    "debt_ratio": [{"period": "2025Q1", "value": 58.2}],
    "fcff": [{"period": "2025Q1", "value": 65.3}],
    "dupont": {"net_margin": 11.8, "asset_turnover": 0.72, "leverage": 1.87},
    "fraud_flags": {"m_score": -2.3, "flags": []},
    "rating": "优秀"
  },
  "valuation": {
    "pe_ttm": 25.3,
    "pb": 5.2,
    "ps_ttm": 2.8,
    "pe_percentile_5y": 35,
    "peg": 0.85,
    "preferred_method": "PE+DCF",
    "dcf_reference": {"wacc": 0.08, "growth_rate": 0.04, "fair_value": 215},
    "safety_margin": "当前价距DCF合理价约5%，安全边际不足20%",
    "fair_value_range": "180-220元"
  },
  "quant_factors": {
    "factors": [
      {"name": "全频段量价融合因子", "value": 0.82, "rank_pct": 92, "industry_rank_pct": 85},
      {"name": "综合价值因子", "value": 0.45, "rank_pct": 55, "industry_rank_pct": 48},
      {"name": "LLM-FADT因子", "value": null, "rank_pct": null, "industry_rank_pct": null, "note": "未覆盖"},
      {"name": "综合成长因子", "value": 0.65, "rank_pct": 72, "industry_rank_pct": 68}
    ],
    "highlights": ["全频段量价融合因子全市场前8%", "LLM-FADT因子行业前20%"],
    "warnings": []
  },
  "technical": {
    "trend": "震荡上行",
    "support": 195,
    "resistance": 230,
    "ma5": 208,
    "ma20": 202,
    "volume_trend": "缩量调整"
  },
  "capital": {
    "main_flow": "近5日净流入3.2亿",
    "north_flow": "沪股通持股占比8.5%",
    "margin_balance": "32亿",
    "shareholders_change": "股东户数连续3季下降",
    "institution_holding": "基金重仓持股占比12%",
    "major_holder_signals": {"减持": false, "增持": false, "回购": true, "质押比例": "5%"}
  },
  "catalysts": [
    {"type": "已发生", "event": "Q2业绩预告超预期", "impact": "正面", "duration": "中期"},
    {"type": "潜在", "event": "新车型定点", "impact": "正面", "duration": "中期"},
    {"type": "潜在", "event": "储能海外订单", "impact": "强烈正面", "duration": "长期"}
  ],
  "risk": {
    "risk_matrix": {
      "fatal": [],
      "major": [
        {"name": "产能过剩", "desc": "行业扩产激进，价格战风险上升", "probability": "中", "impact": "高"},
        {"name": "锂价波动", "desc": "碳酸锂价格反弹压缩毛利率", "probability": "中", "impact": "中"}
      ],
      "manageable": [
        {"name": "竞争加剧", "desc": "比亚迪/中创新航追赶", "probability": "高", "impact": "中"},
        {"name": "估值偏高", "desc": "PE 25x处于中位，回调风险", "probability": "中", "impact": "中"}
      ]
    },
    "warning_thresholds": {
      "经营现金流": "正常",
      "商誉/净资产": "5%(安全)",
      "存货周转": "稳定",
      "应收账款增速": "低于营收增速(正常)",
      "流动性风险": "关注 — 短期债务/货币资金 1.2x，处于安全区间",
      "信用风险": "低 — 应收账款账龄 < 90天占比 85%"
    }
  },
  "liquidity_analysis": {
    "current_ratio": 1.8,
    "quick_ratio": 1.2,
    "cash_ratio": 0.6,
    "short_debt_coverage": "短期债务覆盖充足",
    "free_cash_flow_trend": "连续 4 季度为正"
  },
  "credit_analysis": {
    "receivables_quality": "应收账款账龄结构健康",
    "customer_concentration": "前5大客户占比 35%，无单一客户超过 15%",
    "provision_coverage": "坏账准备覆盖率充足"
  },
  },
  "peers": [
    {"name": "比亚迪", "code": "002594", "pe": 22, "roe": 15, "revenue_growth": 25},
    {"name": "亿纬锂能", "code": "300014", "pe": 28, "roe": 12, "revenue_growth": 30},
    {"name": "国轩高科", "code": "002074", "pe": 35, "roe": 5, "revenue_growth": 18}
  ],
  "opinion": {
    "short": "短期受大盘和板块影响，195-210区间震荡",
    "mid": "中期看储能放量+海外拓展，目标240-260",
    "long": "全球电动化不可逆，龙头地位稳固",
    "principal_asset_view": "华泰首席资产配置观点摘要"
  },
  "operation": {
    "buy_zone": "185-200元",
    "add_condition": "放量突破210且北向连续3日净流入",
    "stop_loss": "跌破180元或行业景气度恶化",
    "target": "短期220/中期260/长期300+",
    "veto_triggers": ["财务造假确认", "退市风险提示", "实控人刑事调查"]
  },
  "tracking": ["季度收入增速", "毛利率变化", "储能出货量", "海外客户进展", "锂价走势"],
  "framework_insights": {
    "industry_position": "处于行业景气度上行中期，轮动风格偏向大盘成长",
    "market_emotion": "A股情绪指数处于中性偏积极区间",
    "capital_flow_context": "近期散户资金流出，ETF和公募逆势流入",
    "rotation_context": "当前风格环境偏向大盘成长，利于电池龙头"
  },
  "trigger_event": {
    "event": "海外锂矿拍卖价创新高",
    "time": "2026-07-03 09:30",
    "source": "财联社电报",
    "direction": "正向催化",
    "causal_chain": "锂价上涨→成本支撑+库存增值→电池厂商定价权增强→利好龙头",
    "is_direct_trigger": true,
    "background_conditions": ["行业产能扩张周期", "储能需求持续增长"]
  },
  "narrative_analysis": {
    "old_narrative": "电池产能过剩，价格战压缩利润",
    "new_narrative": "上游锂价企稳回升+储能需求放量，龙头盈利拐点或已过",
    "narrative_type": "叙事强化",
    "supporting_evidence": ["海外储能订单超预期", "锂矿拍卖价连续2月上涨", "Q2业绩预告超预期"],
    "counter_evidence": "行业总产能仍过剩，二线厂商仍在降价抢份额",
    "comprehensive_judgment": "叙事边际改善但尚未转变，需Q3确认"
  },
  "market_structure": {
    "earnings_season_stage": "中报预告窗口",
    "sector_crowding": "电池板块成交额占比处于历史65%分位，偏拥挤",
    "macro_backdrop": "美联储观望期+人民币汇率稳定",
    "capital_dynamics": "增量资金有限，存量博弈为主",
    "implication": "短期无系统性风险，但板块拥挤度高意味着对负面消息更敏感"
  },
  "qualitative_judgment": "景气拐点待确认 — 需Q3业绩+锂价趋势双重验证",
  "source": "通联数据 MCP + 华泰智研 MCP",
  "data_verification": {
    "revenue": {"primary_value": 890.5, "cross_value": 888.2, "deviation_pct": 0.3, "status": "通过"},
    "roe": {"primary_value": 15.8, "cross_value": 15.6, "deviation_pct": 0.2, "status": "通过"},
    "pe_ttm": {"primary_value": 25.3, "cross_value": 25.1, "deviation_pct": 0.8, "status": "通过"}
  }
}
```

---

## 运作保证（Operational Guarantees）

### 幂等性
本 Skill 在相同输入条件下具有确定性的输出结构：

| 保证项 | 说明 |
|--------|------|
| **相同输入 → 相同报告结构** | 对同一股票代码在同一天的分析，16 板块结构和 JSON schema 保持一致 |
| **数据时效性区分** | 报告顶部标注 `数据截止 YYYY-MM-DD`，明确区分"结构幂等"与"数据时效" |
| **去重部署** | Step 5 上传脚本内置去重逻辑：同股票代码 → 替换最新报告，不产生重复条目 |
| **可重复运行** | 任意次数重复执行不会造成数据污染、重复文件或状态不一致 |

### 能力边界（What-Not 保证）
本 Skill **明确不提供**以下能力：

| 不提供 | 原因 | 替代方案 |
|--------|------|---------|
| 实时逐笔/分钟级数据 | MCP 接口无法提供高频数据 | `ths-advanced-analysis` (分钟K线) |
| 港股/美股分析 | 通联 MCP 覆盖范围仅 A 股沪深京 | `overseas-market-data` / `westock-data` |
| 投资建议或买卖指令 | 合规要求（分析 ≠ 建议） | 自行判断或咨询持牌投资顾问 |
| 实时推送/订阅 | 本 Skill 为按需触发型，非事件驱动型 | 结合 `catalyst-calendar` 日历事件 |
| 回测/量化策略生成 | 聚焦单股深度基本面分析，非策略研究 | `策略生成与优化` / `量化因子选股` |
| 多股组合优化 | 单次分析仅覆盖一只标的 | `portfolio-analysis` / `portfolio-analyzer` |

### 安全防护策略
`generate_report.py` 已实施以下输入防护措施：

| 防护层 | 策略 | 实现位置 |
|--------|------|---------|
| **HTML 实体转义** | 所有用户可控字段（股票名称、分析描述、风险文本等）在渲染前通过 `html.escape()` 转义，防止 XSS 注入 | `generate_report.py` — 40+ 处 `escape()` 调用 |
| **JSON 输入验证** | `load_data()` 使用标准 `json.load()` 反序列化，拒绝非 JSON 格式输入 | `generate_report.py:14-16` |
| **参数边界校验** | `argparse` 参数接收后不做额外评估/执行（`--name` / `--code` 仅作为字符串传入 HTML 模板） | `generate_report.py:1045-1065` |
| **路径安全** | 输出路径由 `os.path.join(skill_dir, ...)` 构建，不基于用户输入拼接原始路径 | `generate_report.py:1078` |
| **零外部依赖** | 当前仅依赖 Python 标准库（json/argparse/os/datetime/html），无第三方包风险 | `requirements.txt` |

---

## 免责声明

> **数据来源**：通联数据 MCP + 华泰智研 MCP + 东方财富
>
> **华泰智研声明**：以上内容由 AI 基于华泰证券研究报告及其附属成果总结生成，可能省略完整报告中的重要信息、市场风险、业绩不及预期等风险，请务必阅读完整原始报告。有关数据、观点、评级等具有时效性，请自行核实最新信息。
>
> **通用声明**：以上内容仅作为研究分析和投资参考，不构成任何保证收益或直接买卖建议。市场有风险，投资需谨慎，具体操作应结合个人风险承受能力、仓位情况和实时市场变化。过往业绩不代表未来表现，投资决策应基于独立判断，审慎评估各类风险因素。

---

## 注意事项

1. **并行 MCP 调用**：批次内的数据互不依赖，必须并行请求以缩短响应时间
2. **Step 2.5 框架加载**：数据搜集完成后必须加载华泰研究框架，用于指导后续分析
3. **量化因子排名**：`get_quant_factor` 必须在 Step 2 批次 4 中调用（与批次3并行），不可推迟到 Step 2.5 才调用。返回全市场逐股数据（约 645KB），MCP 结果自动保存为文件。**必须**将缓存文件复制到 `<workspace>/.quant_factor_cache.txt`，后续用 Python 脚本从缓存文件提取目标股票数据并计算排名。`rank_pct` 需转换为"优于X%标的"语义（`100 - 原始分位`）。LLM-FADT因子可能不覆盖科创板等标的 → `value`/`rank_pct` 填 `null`。华泰 MCP 不可用 → 执行三级降级方案
4. **数据容错**：某个数据源失败时自动降级到备选，不阻塞整体分析。缺失字段标注 `null` 而非空字符串
5. **Step 2.6 强制核查**：组装 JSON 前必须逐项核对「数据完整性核查清单」，任何缺失项立即补调
6. **融资数据**：必须调用 `getFstDetail`（个股融资融券明细）而非仅依赖 `getMktEquMfNew`（资金流向）
7. **HTML 自包含**：生成的 HTML 文件必须完全自包含（内嵌 CSS/JS），可直接用浏览器打开
8. **路径规范**：回复中必须展示 Windows 完整绝对路径，格式 `C:\Users\98322\.workbuddy\skills\stock-deep-analysis\stock_analysis_XXXXXX_YYYY-MM-DD.html`
9. **覆盖范围**：仅支持 A 股（沪深京），暂不支持港股/美股
10. **时效性**：报告顶部标注数据日期和数据源，提醒用户数据截止时间
11. **华泰合规**：报告中涉及华泰数据/观点的部分，必须在末尾附录"华泰智研数据服务"声明和风险揭示
12. **脚本鲁棒性**：generate_report.py 已适配 `null` 值渲染（量化因子显示 N/A 卡片），JSON 中允许 `value`/`rank_pct` 为 `null`；`grading.adjustments` 字段兼容 dict（`{type, value, reason}`）和 string 两种格式
13. **HTML 生成后必须验证**：执行 `ls -l` 检查 HTML 修改时间是否更新，搜索 `factor-value` 确认量化因子已渲染为数值而非全 N/A。PowerShell 下 generate_report.py 可能静默失败（只输出 banner 不输出结果），此时应改用 Bash 或确认 JSON 路径使用 Windows 绝对路径。
14. **自进化联动**：每次分析完成后执行 Step 6 质量自评，结果写入 HealthMonitor。连续 degraded 或评分 < 60 时将自动触发 `skill-evolver` 进化循环
15. **三产出物交付**：每次分析完成后必须同时产出 HTML（可视化看板）、TXT（纯文字摘要）和 PDF（归档文件）三份文件。TXT 通过 `generate_text_summary.py` 生成，PDF 通过 html-to-pdf skill 的 `html_to_pdf.mjs` 脚本转换，三份文件共享同一份 JSON 数据输入，存于同级目录
16. **行业排名依赖**：量化因子 `industry_rank_pct` 依赖于 `hithink-astock-selector` 提供的同行业代码列表（`.peer_codes.txt`）。若 hithink 不可用或未返回数据，行业排名自动显示为 `N/A`，不影响全市场排名
17. **PDF 转换依赖**：PDF 生成依赖 `html-to-pdf` skill 的 Playwright + Chromium 引擎。转换前确认 `C:\Users\98322\.workbuddy\skills\html-to-pdf\scripts\html_to_pdf.mjs` 存在。若 Chromium 未安装 → `npx playwright install chromium`；若转换失败 → 标注 `[PDF_GENERATION_FAILED]`，不影响 HTML 和 TXT 交付
