微信扫一扫Financial Excel Query Skill
从 workspace/excels/*.xlsx 里读结构化财务数据
应用场景
Agent 回答业绩类问题时，[fact] 数字必须来自可核验的结构化数据源。本 skill 就是这一层数据源：
- 公司整体：营业总收入 / 毛利 / 营业利润 / 净利润 / YoY / 各项费用（→
query_income.py） - 分部业务：各业务线（如淘天、Cloud）的分部收入、EBITA、EBITA 利润率、多层子分部（→
query_segments.py）
Agent 拿到这两个脚本的 JSON 输出后，把数字塞进 [fact] 表格，再叠加 retrieve_filing_kb（[filing-stated cause]）+ web 搜索（[external]）综合分析。
数据源约定
workspace/excels/ 由上游其它 skill（futu-financial-report / segment-financial-report）生成，文件命名两套：
| 类型 | 文件名规则 | 例子 |
|---|---|---|
| 公司整体 | {MARKET}_{TICKER}_income_{yyyymmdd}_{hhmmss}.xlsx | US_BABA_income_20260628_141917.xlsx |
| 分部业务 | {TICKER}_segments_{yyyymmdd}_{hhmmss}.xlsx | BABA_segments_20260630_210744.xlsx |
MARKET∈US / HK / SH / SZ- 同 ticker 同类型的多个版本：脚本按文件名末尾时间戳降序取最新一份，其它忽略
- 打开 Excel 时自动跳过临时锁文件（
~$前缀）
Excel 内部结构（两类文件对齐）：
| 布局 | 说明 |
|---|---|
| 第 1 列 | income = 指标名（营业总收入）；segments = 分部名（可能带 ├─ 缩进标层级） |
| 第 2 列 | income = 单位（百万人民币）；segments = 指标（收入 / EBITA / EBITA 利润率(%)） |
| 第 3 列起 | 每列一个 period，如 2026Q1 / 2025FY / 2024Q4；2025FY 视为完整财年 |
| 第 1 行 | period 列头 |
| 第 2 行（仅 income） | 财报日期 |
| 第 3 行起 | 数据行 |
目录结构
workspace/skills/financial-metrics-query/
├── SKILL.md
├── config/
│ └── excel-format.json # 文件名正则 + 列布局 + period 正则
└── scripts/
├── _common.py # 共用：文件挑选、period 过滤、单元格规范化
├── query_income.py # 整体损益表查询
├── query_segments.py # 分部业务查询
└── requirements.txt # openpyxl
前置准备
pip install -r workspace/skills/financial-metrics-query/scripts/requirements.txt
用法：query_income.py
# 最简：取 BABA 最新一份 income excel，返回全部指标全部 period
python workspace/skills/financial-metrics-query/scripts/query_income.py --ticker BABA --pretty
# 只要营业总收入 + 营业利润，最近两年全部季度
python workspace/skills/financial-metrics-query/scripts/query_income.py \
--ticker BABA \
--metrics "营业总收入,营业利润" \
--fiscal-years 2024-2025 \
--pretty
# 只要 FY 与 Q4
python workspace/skills/financial-metrics-query/scripts/query_income.py \
--ticker 00700 --fiscal-periods FY,Q4 --pretty
# 精确 period 列表
python workspace/skills/financial-metrics-query/scripts/query_income.py \
--ticker BABA --periods "2024Q3,2025FY,2026Q1" --pretty
query_income.py 参数
| 参数 | 说明 | 默认 |
|---|---|---|
| --ticker | 股票代码（自动 upper） | 必填 |
| --metrics | 指标名子串（逗号分隔），任一命中即返回 | 全部 |
| --fiscal-years | 财年过滤，2024 单年或 2022-2025 闭区间 | 不限 |
| --fiscal-periods | 财期类型，如 FY,Q3,Q4 | 不限 |
| --periods | 精确 period 列表，如 2024Q3,2025FY | 不限 |
| --config | 配置文件路径 | config/excel-format.json |
| --excels-dir | 覆盖 excels 目录 | workspace/excels/ |
| --pretty | 缩进输出 | 关闭 |
用法：query_segments.py
# BABA 全部分部全部指标（可能很大，建议加过滤）
python workspace/skills/financial-metrics-query/scripts/query_segments.py --ticker BABA --pretty
# 只看云智能分部的收入与 EBITA
python workspace/skills/financial-metrics-query/scripts/query_segments.py \
--ticker BABA --segment "Cloud" --pretty
# 只要一级分部（level=1）的收入
python workspace/skills/financial-metrics-query/scripts/query_segments.py \
--ticker BABA --metric 收入 --max-level 1 --pretty
# 结合财年过滤
python workspace/skills/financial-metrics-query/scripts/query_segments.py \
--ticker BABA --metric EBITA --fiscal-years 2024-2025 --pretty
query_segments.py 参数
| 参数 | 说明 | 默认 |
|---|---|---|
| --ticker | 股票代码 | 必填 |
| --segment | 分部名子串过滤（大小写不敏感） | 全部 |
| --metric | 指标名子串过滤 | 全部 |
| --fiscal-years / --fiscal-periods / --periods | 同 income | 不限 |
| --max-level | 只返回层级 ≤ N 的分部（Level 1 = 顶层） | 不限 |
输出格式
query_income.py 输出
{
"success": true,
"ticker": "BABA",
"source": "US_BABA_income_20260629_220718.xlsx",
"sheet": "利润表",
"periods": ["2026Q1", "2025FY", "2025Q4", "2025Q3", ...],
"report_dates": {"2026Q1": "2026-03-30", "2025FY": "2025-03-30"},
"metrics": [
{
"metric": "营业总收入",
"unit": "百万人民币",
"values": {"2026Q1": 247652, "2025FY": 996347, "2025Q4": 236454, ...}
},
{
"metric": "营业利润",
"unit": "百万人民币",
"values": {"2026Q1": 76235, "2025FY": 250986, ...}
}
],
"count": 2
}
query_segments.py 输出
{
"success": true,
"ticker": "BABA",
"source": "BABA_segments_20260702_174907.xlsx",
"sheet": "分部财务数据",
"periods": ["2026Q1", "2025Q4", "2025Q3", "2025Q2", "2025Q1", ...],
"rows": [
{
"segment": "Taobao and Tmall Group",
"level": 1,
"parent_segment": null,
"metric": "收入",
"values": {"2026Q1": 122220, "2025Q4": 159347, ...}
},
{
"segment": "China commerce retail",
"level": 2,
"parent_segment": "Taobao and Tmall Group",
"metric": "收入",
"values": {"2026Q1": 116280, ...}
},
{
"segment": "Customer management",
"level": 3,
"parent_segment": "China commerce retail",
"metric": "收入",
"values": {"2026Q1": 73024, ...}
}
],
"count": 3
}
失败时：{"success":false,"company":"BABA","error":"..."}，退出码 2。
Excel 布局如何配置
config/excel-format.json 里的所有硬编码集中管理，涉及新格式时只改 JSON：
| 节点 | 用途 |
|---|---|
| excelsDir | Excel 存放目录（相对 workspace） |
| income.filenamePattern | 整体损益表文件名正则（含 named group market/ticker/date/time） |
| income.metricColumn / unitColumn / firstPeriodColumn | 各类列在 sheet 中的位置 |
| income.reportDateRow / reportDateLabel | 财报日期所在行 |
| segments.filenamePattern | 分部文件名正则 |
| segments.hierarchyPrefixes | 分部名的层级前缀（├─ / └─ 等） |
| periodFilter.periodTypeRegex | period 列名匹配（默认 20YYFY / 20YYQx / 20YYHx） |
Agent Prompt 集成建议
[fact] 数据源里应加入本 skill：
可用工具与分工：
- financial-metrics-query skill (query_income.py) → 结构化"事实"来源：公司整体损益（营收/毛利/营业利润/费用/YoY）
- financial-metrics-query skill (query_segments.py)→ 结构化"事实"来源：分部业务数据（分部收入/EBITA/多层级）
- retrieve_filing_kb → [filing-stated cause] 原文片段
- ...
优先级：本 skill 是"结构化事实"的唯一入口，覆盖全部市场且延迟毫秒级。workspace/excels/ 由 futu-financial-report / segment-financial-report 两个 skill 负责生成。