stock-report

name	stock-report
description	使用本仓库的 ds CLI + Python 生成稳定结构的 A 股数据报告。只要用户想“给一个股票名称/代码生成报告”“批量前先验证单个标的报告流程”“按当前仓库固定模板重跑报告”，就应该使用这个 skill，即使用户没有明确提到 skill 名称。默认依赖本地 `ds` 已安装并登录、`python3` 可用。

Stock Report

这个 skill 的目标很窄：给定一个 A 股标的名称或代码，用本仓库固定的 DS 数据采集链路拉数，并生成统一版式的 HTML 报告。
它不是泛化的股票分析 skill，也不是 MCP skill。这里的真源是：

• ./cli-data-fetch-guide.md
• ./scripts/fetch_and_generate_stock_report.py
• ./scripts/generate_ds_report.py

何时使用

出现以下任一情况时，直接使用本 skill：

• 用户说“生成某只股票的报告”
• 用户给出股票名称或股票代码，希望直接出本仓库这套 HTML 报告
• 用户要复跑现有报告、验证生成链路是否稳定
• 用户要在批量化之前先单标的验证 DS 拉数 + 报告生成

如果用户要的是：

• 改报告样式/章节/图表逻辑：先用本 skill 找到真源脚本，再修改脚本
• 改 DS CLI 本身：回到代码仓库，不要把 skill 当主场
• 用 MCP 或其他数据源：不要用这个 skill

输入约定

支持两种输入：

• 股票代码：如 000728.SZ
• 股票名称：如 国元证券

如果用户给的是中文名称，脚本会先执行：

ds iid Stk search "<名称>" --output json

并先按 A 股主证券做精确匹配。
如果无法唯一确认标的，应该明确报错并要求用户提供 000728.SZ 这类准确 IID，不要猜测代码或直接取第一条。

环境前提

执行前默认检查：

ds status

只有在以下条件满足时才继续：

• ds 命令存在
• 用户已登录，token 可用
• python3 可执行

如果 ds status 失败，先告诉用户是环境/登录问题，不要继续生成半成品。

标准执行步骤

1. 识别标的

用 ds iid Stk search <标的名称> 确认标的的IID代码

运行：

python3 <skill_path>/scripts/fetch_and_generate_stock_report.py "<标的IID代码>"

这个脚本会自动做以下事情：

• 创建仓库根目录下的 data/<股票代码>/raw/
• 按 skill 内 cli-data-fetch-guide.md 的固定专题清单抓取原始 JSON
• 对“允许为空”的专题写空文件，而不是报错退出
• 调用 skill 内 scripts/generate_ds_report.py 生成结构化 JSON 和 HTML 报告
• 写出仓库根目录下的 data/<股票代码>/run_summary.json

2. 固定查询范围

不要临场删改这套查询清单。当前固定覆盖：

• 基本信息 1000933
• 实控人 1000998
• 高管薪酬 1001034
• 股本结构 1000987
• 解禁 1001006
• 十大股东 1000991
• 十大流通股东 1000996
• 股东户数 1000183
• 大股东持股比例 1000989
• 分红 1000978
• 年度资产负债表 1000964
• 年度利润表 1000965
• 年度现金流量表 1000966
• 季度利润表 1000970
• 季度现金流量表 1000971
• 主营业务构成 1000961
• 一致评级 1001348/1001352/1001351/1001353

其中以下专题允许无数据：

• 实控人 1000998
• 解禁 1001006
• 分红 1000978
• 一致评级四个专题

无数据时应保留空结果，并让最终报告明确显示“该标的暂无此类数据”，不要表述成抓取异常。

3. 生成结果

成功后，目标目录应至少包含：

data/<股票代码>/
├── raw/
├── basic_info.json
├── financial_data.json
├── shareholders.json
├── data_sources.md
├── run_summary.json
└── report/
    └── report.html

其中 report.html 是用户主要关心的产物。

报告契约

当前报告是固定 5 章结构：

1. 公司简介
2. 股本和股东
3. 财务数据
4. 主营业务行业数据
5. 一致评级

关键约束：

• 样式对齐 data/601377/report/report.html 和 stock-analysis-report/template/report_template.html
• 页面中不显示数据来源区块
• 利润表、现金流量表支持年度/季度页内 Tab
• 资产负债表只展示年度口径
• 解禁/一致评级无数据时显示明确空状态
• 分红有数据则展示图表，无数据则显示空状态
• “主营业务行业数据”里的业务观察与论证逻辑，不通过代码模板生成；应在报告文件生成完成后，由执行该 skill 的 agent 基于当次标的数据单独输出。

输出给用户时怎么说

默认简洁交付：

• 报告路径
• 关键生成文件路径
• 是否存在“该标的暂无此类数据”的专题（如实控人/解禁/分红/一致评级）
• 是否真的完成了脚本执行验证

如果你没有实际运行生成，不要暗示已经生成成功。

故障处理

1. ds status 失败

优先判断为环境或登录问题，提示用户先确认：

• ds 是否安装
• 是否已登录
• token 是否有效

2. iid search 没结果

直接报“未识别到标的”，让用户提供更准确名称或代码。

3. 单个专题返回“缺少数据集”

如果该专题属于允许为空的范围：

• 写空文件
• 继续后续流程
• 最终报告显示空状态

如果不属于允许为空范围：

• 中止流程
• 明确告诉用户是哪条专题失败

4. 生成脚本失败

先检查：

• raw 文件是否存在空文件以外的损坏内容
• 标的目录是否创建成功
• Python 是否可执行

不要手工改 HTML 兜底，优先修脚本真源。

真源文件

需要修改或排查时，优先看：

• ./scripts/fetch_and_generate_stock_report.py：一键采集入口
• ./scripts/generate_ds_report.py：HTML/JSON 生成逻辑
• ./cli-data-fetch-guide.md：DS 查询专题清单

示例

示例 1：直接生成报告

输入：

给我生成国元证券的报告

执行：

python3 <skill_path>/scripts/fetch_and_generate_stock_report.py "国元证券"

示例 2：按代码重跑

输入：

重跑 000728.SZ 的报告

执行：

python3 <skill_path>/scripts/fetch_and_generate_stock_report.py "000728.SZ"

边界

• 不要把这个 skill 扩展成批量任务编排器；批量化另做
• 不要自动切换到 MCP
• 不要擅自改章节结构或报告样式
• 不要跳过 DS 原始数据落盘直接生成报告