Strategic Insight

✅ 能力边界

能做：

• 基于 benchmark-analysis 的对标结果，生成 3–5 条核心战略洞察（增长机会 / 风险预警 / 效率提升），按优先级排序
• 结合零售业务高频词与组织架构变化，产出面向高管视角的战略洞察 PDF 报告
• 按用户指定的基准行 / 报告主角定制洞察结论

不能做（超出范围）：

• 不下载财报、不提取数据、不做原始对标计算（依赖上游 ①②③④）
• 无对标数据时不产出洞察，不脱离数据主观臆断
• 不做治理韧性/言行比对等穿透分析（属于 strategy-governance-analysis）

战略洞察生成器

共享 PDF Runtime（已随包内置）

本 Skill 生成 PDF 所需的共享 PDF Runtime 已随包内置在 _vendor/pdf_report_builder_runtime/ 下，独立安装态（发布包）无需执行任何初始化命令，可直接生成 PDF 报告。

仅仓库开发态需要从共享源码重新注入：执行 python3 scripts/release.py --sync-paths（release.py 仅存在于仓库开发态，发布包中不含此脚本，无需也无法运行）。

📁 目录约定（所有 Skill 共享）

重要：本 Skill 系列不再把配置/数据/输出放在仓库里，统一落到用户主目录：

~/RetailAnalysis/              # 默认 Home；可通过 RETAIL_ANALYSIS_HOME 覆盖
├── config/                    # 全局共享配置（降级兜底）
├── data/
│   ├── extracted_text/        # 财报解析产物（章节检索输入）
│   ├── standard/              # Skill 1 主输出：<bank>.json（本 Skill 输入）
│   ├── text/                  # Skill 2 主输出：<bank>.json（本 Skill 输入）
│   ├── partial/<bank_short>/  # 本 Skill 按客户隔离的中间产物
│   └── insight_result.json    # 向后兼容的机器可读入口
├── output/<bank_short>/
│   ├── insight_result.json
│   ├── strategic_insight_report.html
│   └── 同业战略洞察报告.pdf
├── report_assets/             # PDF 生成所需视觉资产（LOGO/palette/封面图等）
└── logs/

本 Skill 本地配置（优先于全局 config/）：

skills/skill4-strategic-insight/
├── config/                    # Skill 4 本地配置副本（pack/publish 前由 shared/config-sources 生成）
│   ├── banks.yaml             # 银行列表
│   ├── warning_rules.yaml     # 预警阈值
│   └── output_format.md       # 输出格式
└── assets/

详细目录约定见 Skill 1 SKILL.md 开头。

📖 生成 PDF 前必读：RUNTIME.md（2026-04-29 新增·强制）

Agent 在首次触发 PDF 生成前必须 read_file 运行时规约： skills/skill4-strategic-insight/_vendor/pdf_report_builder_runtime/RUNTIME.md

该文件覆盖：模板完整性守卫、rich_text 过滤器、按行视觉资产、自动下载与多级质量核验、 P0 VIS 验收、5 项 PDF 校验。调用 build_report(...) 时须传 runtime_acknowledged=True。

🎯 基准行（base_bank）解析规则（2026-04-29 新增·强制）

与 skill3 / skill5 共享本规则。详见 skills/skill3-benchmark-analysis/SKILL.md → "基准行（base_bank）解析规则"小节。本节只列 skill4 的专属差异。

解析优先级：显式参数 > RETAIL_ANALYSIS_BASE_BANK 环境变量 > 从用户 query 抽取。无默认值——若三者均未命中，Agent 必须主动询问用户指定基准银行。 解析由 shared/pdf-report-builder-runtime/scripts/bank_context.py::resolve() 统一实现。

按行产物：本 Skill 的所有产物写入 ~/RetailAnalysis/output/<bank_short>/：

• insight_result.json
• strategic_insight_report.html
• 同业战略洞察报告.pdf

按行视觉资产：与 skill3 共用 report_assets/by_bank/<bank>/，由 build_by_bank_vis.py 维护。PDF 生成前必须执行 bank_context.BankContext.assets_ready() 自检，未就绪时先运行 build_by_bank_vis.py --bank <short>。

build_report 调用：一律传入 base_bank=ctx.short_name，让共享 PDF Runtime 自动按行选取 LOGO / palette。具体示例见 skill3 SKILL.md 的 build_report 章节。

定位

基于 Skill 1（标准数据）和 Skill 2（文字数据）的提取结果，自动生成 3-5 条核心战略洞察，重点关注：

1. 零售业务相关的高频词和战略表述变化
2. 组织架构中关于零售业务的设置变化
3. 历史战略执行效果评估

洞察按优先级排序：增长机会点 > 风险预警点 > 效率提升点

前置条件与数据依赖

本 Skill 依赖前序 Skill 的产出数据。执行前必须确认以下数据已就绪，否则需先运行对应 Skill：

执行顺序：财报下载 → Skill 1 标准提取 → Skill 2 文字提取 → Skill 3 对标分析 → Skill 4 战略洞察

基准行：用户必须指定基准银行（分析主体）。本 Skill 不设默认基准行。 若用户未指定，Agent 应主动询问："请指定基准银行（如：以A银行为基准生成战略洞察报告）。"

典型用户请求

• "基于2025年的数据，生成给零售高管看的战略洞察PDF报告。"
• "今年年报中零售业务有哪些值得关注的变化？"
• "各行零售战略方向有什么新动向？"
• "组织架构有没有变化？"

输入/输出 Schema（权威契约）

依赖声明

Schema 注册表文件由 release.py 在打包前从仓库根 shared/config-schemas/ 自动注入到本 Skill 的 config/schemas/ 下，打包后运行时按下表中的 skill 相对路径读取。

开发期 schema 的唯一 source of truth 在仓库根 shared/config-schemas/；请不要直接修改本 skill 的 config/schemas/ 副本，由 python scripts/release.py --sync-paths 统一同步。

Python 代码 Schema 约束（scripts/build_strategic_insight.py）

以下函数必须严格使用 text-v1.0 字段（已适配，禁止回退）：

读取时强制校验：入口 main() 加载 text_payloads 后立即核对 _schema_version == "text-v1.0"，不匹配直接抛 ValueError，不做兼容读取。

LLM subagent 消费约束

Skill 4 的分析型 subagent（战略洞察 5 条生成）在读取 standard / text / benchmark JSON 前，必须先在 prompt 中声明：

• 字段取值路径（如 by_period[<期间>].metrics[*].values[*].period_end_value）
• bucket 过滤约束（category_bucket 精确匹配，禁止子串）
• 未披露语义（values=[] 表示未披露，禁止推算）

前置条件

• Skill 1 已执行，~/RetailAnalysis/data/standard/<bank>.json 存在（每家银行一个 JSON，内部按期组织）
• Skill 2 已执行，~/RetailAnalysis/data/text/<bank>.json 存在
• Skill 3 已执行，~/RetailAnalysis/data/benchmark_database.json 存在（用于战略执行评估和同业对照）
• 如需做高频词和组织架构检索，还需要 ~/RetailAnalysis/data/extracted_text/ 中有对应银行的解析产物（Markdown / JSON）

输入

• ~/RetailAnalysis/data/standard/<bank>.json — 标准化表格数据（Skill 1 主输出，按银行聚合多期）
• ~/RetailAnalysis/data/text/<bank>.json — 文字描述数据（Skill 2 主输出，按银行聚合多期）
• ~/RetailAnalysis/data/extracted_text/* — 各银行财报的章节文本（用于高频词统计、组织架构检索）

执行流程

默认执行模式：Step 1-3 是三个相互独立的分析维度，必须使用 Team 并行模式并发执行（见下方"Team 并行模式"章节）。Step 4-6 为串行汇总步骤，由主 Agent 执行。

Step 1: 高频词与战略表述分析

对每家银行的零售业务章节文本：

1. 提取高频词：统计关键词频次，重点关注业务方向词（如"财富管理""数字化""养老金融"）、产品创新词、风控相关词
2. 与上期对比：识别新增、消失、频次显著变化的高频词
3. 跨行对比：识别行业共同趋势和基准行特有表述

Step 2: 组织架构变化检测

搜索组织架构相关章节，检查：

• 零售相关部门的设立/撤销/合并
• 财富管理/私人银行/信用卡的组织隶属关系调整
• 新设部门（数字金融/客群经营/生态平台等）

Step 3: 历史战略执行效果评估

• 回顾各行上期零售战略目标
• 对照本期实际表现
• 识别"说了没做到"或"做了没说"的领域

Step 4: 生成 3-5 条核心洞察

每条洞察包含：

• 标题：一句话核心判断
• 优先级类型：增长机会 / 风险预警 / 效率提升
• 数据依据：具体数值、排名或高频词变化
• 业务含义：对零售经营的解读
• 行动建议：后续关注方向或经营动作
• 风险提示：口径差异、数据局限性
• 来源标注：已披露事实 / 模型判断

优先级排序：增长机会点 > 风险预警点 > 效率提升点

Step 5: 质量检查

每条洞察必须通过：

1. ✅ 有数据依据
2. ✅ 明确标注事实/判断
3. ✅ 说明口径差异风险
4. ✅ 建议有具体方向
5. ✅ 避免脱离数据推测
6. ✅ 语言适合高管阅读

Step 6: 生成输出

保存为 ~/RetailAnalysis/data/insight_result.json，包含：

• executive_summary：3-5句总体判断
• insights：洞察列表
• high_frequency_analysis：高频词分析结果
• org_structure_changes：组织架构变化

输出

Team 并行模式（默认执行方式）

触发条件：本 Skill 默认使用 Team 并行模式（Step 1-3 是三个相互独立的分析维度，天然适合并行）。

核心思想：将三个互不依赖的分析维度拆分为三个 team member 并发执行，main 负责 Step 4-6 的汇总推理和输出。

流程

Step 0: 加载 ~/RetailAnalysis/data/standard/<bank>.json + ~/RetailAnalysis/data/text/<bank>.json
  │
  ├─ Step 1: team_create("skill4-insight")
  ├─ Step 2: 同一批次并行 spawn 3 个 task
  │    ├─ s4-freqword    → Step 1：高频词与战略表述分析
  │    │     输出 ~/RetailAnalysis/data/partial/insight_freqword.json
  │    │     (每家银行零售章节的高频词 Top20、与上期对比、跨行对比)
  │    ├─ s4-orgchange   → Step 2：组织架构变化检测
  │    │     输出 ~/RetailAnalysis/data/partial/insight_orgchange.json
  │    │     (零售部门增/撤/并、隶属关系调整、新设部门清单)
  │    └─ s4-stratreview → Step 3：历史战略执行效果评估
  │          输出 ~/RetailAnalysis/data/partial/insight_stratreview.json
  │          (上期战略目标 vs 本期实际表现，"说了没做到"/"做了没说")
  │    每个 member 完成后 send_message 汇报关键发现
  │
  ├─ Step 3: main 等待 3 个 member 全部完成
  ├─ Step 4: main 执行 Step 4：整合 3 个 partial 文件 + 数据指标，生成 3-5 条核心洞察
  │    按 增长机会 > 风险预警 > 效率提升 的优先级排序
  ├─ Step 5: main 执行 Step 5：质量检查（6项红线）
  ├─ Step 6: main 生成 ~/RetailAnalysis/data/insight_result.json
  ├─ Step 7: main shutdown 所有 member + team_delete
  └─ Step 8: 向用户汇报

Member 职责边界

为何洞察合成必须由 main 执行：洞察生成需要同时参考"数据事实""高频词""组织变化""战略执行"四类信息，且要进行优先级排序和质量红线检查，属于"全局推理"任务，不适合拆分到 member。

质量红线

• 不得脱离数据编造结论
• 不得把推测写成事实
• 高频词分析必须基于实际文本统计
• 组织架构变化必须有年报文本依据
• 建议必须有具体方向，避免空泛表述
• 增长机会 > 风险预警 > 效率提升 的优先级排序必须遵守

🧹 运行时临时脚本命名与清理约束

详细规范见 skills/skill1-standard-data-extraction/SKILL.md → "运行时临时脚本命名与清理约束（全 Skill 统一）"小节。

1. Agent 为本 Skill 临时撰写的洞察分析脚本（如 analyze_org_changes.py、extract_org_changes_v*.py、generate_insight_pdf.py）必须统一命名为 _runtime_generate_<用途>_<时间戳>.py
2. 落盘至 ~/RetailAnalysis/work/ 或 ~/RetailAnalysis/data/partial/，严禁提交到 scripts/
3. 本 Skill 已沉淀的正式脚本仅包括：build_strategic_insight.py、paths.py
4. 任何一次性 PDF 生成、临时抽样分析、实验性规则验证脚本仍属于临时脚本，必须遵守 _runtime_generate_* 命名规范
5. 任务完成（insight_result.json 生成且用户验收）后，立即删除该临时脚本
6. 兜底：_runtime_generate_* 已写入 .gitignore；scripts/cleanup_runtime_scripts.py 可批量清理

依赖

• Python 3.10+
• pyyaml
• jinja2（PDF 交付物模板渲染）
• playwright（HTML → PDF）
• Pillow（PDF 校验）

PDF 交付物（"同业战略洞察报告"）

基于本 Skill 的主输出 ~/RetailAnalysis/data/insight_result.json，生成符合基准行 VIS 风格的 PDF 报告。

PDF 生成由共享 PDF Runtime（shared/pdf-report-builder-runtime）统一提供。本 Skill 只负责准备数据上下文 ctx 和业务模板。

前置条件

• ~/RetailAnalysis/data/insight_result.json 已生成
• VIS 资产已固化（见共享 PDF Runtime 的 P0 强制前置流程）

报告结构（固定 8 节）

1. 封面页：LOGO + 标题"同业战略洞察报告"+ 副标题 + 生成日期
2. 目录页
3. Executive Summary：5 句话摘要
4. 第一部分 行业全景（高频词 / 组织架构 / 战略执行）
5. 第二部分 五大核心洞察（按优先级排序）
6. 第三部分 基准行 vs 同业战略雷达
7. 第四部分 给管理层的 5 条建议
8. 附录：数据局限 / 数据与产物索引 / 免责声明

样式规范

• 基础样式：由共享 PDF Runtime 的 style_guide.css 统一提供
• 业务覆盖：当前 Skill 的 assets/style_overrides.css（如需微调）
• 配色：由 ~/RetailAnalysis/report_assets/vis/palette.json 驱动
• 优先级标签：增长机会=绿色 / 风险预警=红色 / 效率提升=蓝色

生成方式

调用当前 Skill 内 vendored 的共享 PDF Runtime build_report：

import pathlib
import sys

skill_dir = pathlib.Path("<当前业务 Skill 根目录>")
vendor_scripts = skill_dir / "_vendor" / "pdf_report_builder_runtime" / "scripts"
sys.path.insert(0, str(vendor_scripts))

from html_to_pdf import build_report

build_report(
    ctx=insight_result,  # insight_result.json 内容，meta.base_bank_short 必填
    template_path=str(skill_dir / "assets" / "report_template.html"),
    output_html="~/RetailAnalysis/output/<bank_short>/strategic_insight_report.html",
    output_pdf="~/RetailAnalysis/output/<bank_short>/同业战略洞察报告.pdf",
    style_overrides_path=str(skill_dir / "assets" / "style_overrides.css"),  # 如文件不存在可省略
    base_bank="<bank_short>",
    runtime_acknowledged=True,
    margin_top="25mm",
    margin_bottom="16mm",
    header_text="同业战略洞察报告",
)

scripts/release.py 会在 pack/publish 前自动把共享 PDF Runtime 的公共 assets/config/scripts 注入到当前 Skill 的 _vendor/pdf_report_builder_runtime/ 下，因此运行时不需要跨目录读取共享源码。

产物结构

~/RetailAnalysis/
├── data/
│   └── insight_result.json               # 向后兼容的机器可读入口
├── report_assets/                        # VIS 资产（与共享 PDF Runtime / skill3 / skill5 共享）
└── output/<bank_short>/
    ├── insight_result.json               # 当前客户结构化交付物
    ├── strategic_insight_report.html     # 中间 HTML
    └── 同业战略洞察报告.pdf              # 最终 PDF

skills/skill4-strategic-insight/
├── SKILL.md
├── config/
├── scripts/
│   └── paths.py                          # 共享路径模块
├── assets/
│   ├── report_template.html              # 业务模板（继承共享 PDF Runtime 的 base_template）
│   └── style_overrides.css               # 业务覆盖样式（可选）
├── _vendor/
│   └── pdf_report_builder_runtime/       # pack/publish 前由 release.py 自动注入
│       ├── assets/
│       ├── config/
│       └── scripts/

报告用字规范

• 标题固定为 "同业战略洞察报告"
• 免责声明统一为 "本报告由 AI 基于上市银行公开披露信息生成，仅供研究参考，不构成任何投资建议，亦不构成对任何个股的推荐"
• 所有引用数据必须带来源标注
• 每条洞察区分"已披露事实"与"模型判断"

执行模式

• 默认串行：主流程完成后由 main 串行调用当前 Skill 内 vendored 的共享 PDF Runtime，不新建 team
• 默认产物：除兼容数据入口外，默认将 JSON、HTML、PDF 写入 ~/RetailAnalysis/output/<bank_short>/