a65adcc2e5
Sources: extracted from two upstream archives (skill-repo, skills-main),
merged with the following policy:
- 15 broken symlinks (pointing to /Users/jameslee/.cc-switch/skills or
../../.agents/skills on a foreign machine) discarded
- 3 real name collisions with identical content (ai-pair, ifind-http-api,
zhipu-websearch) kept as one copy
- Functional overlaps deduped keeping the strongest variant:
- docx family: kept docx (official, full toolchain) + docx-cn
(GB/T 9704 Chinese official-document constants),
dropped docx_writer (no scripts, name collided with docx)
- humanizer family: kept humanizer-zh (6 zh reference docs),
dropped humanizer (en, redundant for CN workflow)
- Skills that only ran in a foreign environment removed:
ablemind-ops, app-publish, hlb-design-system, openclaw-adj-skill,
claude-driver
- alphapai excluded from this public repo because its SKILL.md hard-coded
live credentials
Result: 25 skills, 572 files, ~7.5 MB.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
196 lines
7.8 KiB
Markdown
196 lines
7.8 KiB
Markdown
# ppt-station skill
|
||
|
||
Claude Code skill，在对话中通过 `/ppt-station` 触发。自动路由到合适的工作流生成、解析或编辑 PowerPoint。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
skill/
|
||
├── SKILL.md # skill 元数据 + 路由表 + 速查表
|
||
├── README.md # 本文件
|
||
├── scripts/ # CLI 工具（全部 stdout=JSON, stderr=日志）
|
||
│ ├── generate_ppt.py # Flow A: 模板替换生成
|
||
│ ├── run_job.py # Flow B: Job JSON 声明式编排
|
||
│ ├── parse_ppt.py # Flow C-1: PPT → JSON
|
||
│ ├── rebuild_ppt.py # Flow C-2: JSON → PPT
|
||
│ ├── parse_template.py # 工具: 解析模板占位符
|
||
│ ├── describe_chart.py # 工具: 描述已有图表结构
|
||
│ ├── list_presets.py # 工具: 查询配色/日期轴/图表预设
|
||
│ ├── add_placeholders.py # 工具: 给现有 PPT 注入占位符
|
||
│ ├── gen_moutai_report.py # 示例: 茅台年度分析报告
|
||
│ └── gen_moutai_risk.py # 示例: 茅台风险分析报告
|
||
├── reference/ # 详细参考文档
|
||
│ ├── chart-config.md # 图表配置完整字段
|
||
│ ├── job-schema.md # Job JSON Schema
|
||
│ ├── placeholder-syntax.md # 占位符语法
|
||
│ ├── connectors-transforms.md# 数据连接器 + 变换操作
|
||
│ ├── workflow-template.md # Flow A 详解
|
||
│ ├── workflow-engine.md # Flow B 详解
|
||
│ ├── workflow-parse-rebuild.md# Flow C 详解
|
||
│ └── workflow-tushare.md # Flow D 详解
|
||
└── tests/ # Bash 集成测试
|
||
├── test_parse_template.sh
|
||
├── test_generate_ppt.sh
|
||
├── test_run_job.sh
|
||
├── test_parse_rebuild.sh
|
||
└── test_describe_chart.sh
|
||
```
|
||
|
||
## 四条工作流
|
||
|
||
### Flow A — 模板替换
|
||
|
||
最常用。模板 PPT 中放好 `{变量名}` 和 `{@图:图表名}` 占位符，配合 config.json + CSV 数据生成最终 PPT。图表样式最丰富（双轴、8 种配色、日期轴预设）。
|
||
|
||
```bash
|
||
# 1. 查看模板有哪些占位符
|
||
python scripts/parse_template.py aim/aim03.pptx
|
||
|
||
# 2. 准备 config.json + CSV，然后生成
|
||
python scripts/generate_ppt.py aim/aim03.pptx config.json output.pptx
|
||
|
||
# 3. 验证生成的图表
|
||
python scripts/describe_chart.py output.pptx
|
||
```
|
||
|
||
### Flow B — Job JSON 声明式编排
|
||
|
||
适合多数据源编排。一个 job.json 声明数据源（CSV/Excel/Tushare）、变换管道、幻灯片配置，一键生成。
|
||
|
||
```bash
|
||
# 验证 schema
|
||
python scripts/run_job.py job.json --dry-run
|
||
|
||
# 正式生成
|
||
python scripts/run_job.py job.json
|
||
```
|
||
|
||
> 注意：Job 引擎的图表渲染分支对复杂双轴图支持有限，复杂图表请用 Flow A。
|
||
|
||
### Flow C — 解析→编辑→重建
|
||
|
||
对已有 PPT 做微调（批量文本替换、结构检查）。不适合改图表数据。
|
||
|
||
```bash
|
||
python scripts/parse_ppt.py input.pptx parsed.json # PPT → JSON
|
||
# 编辑 parsed.json ...
|
||
python scripts/rebuild_ppt.py parsed.json output.pptx # JSON → PPT
|
||
```
|
||
|
||
### Flow D — Tushare 实时数据
|
||
|
||
在 Flow A 或 B 中接入 Tushare 实时 A 股数据。需要 `TUSHARE_TOKEN` 环境变量或 `.env` 文件。
|
||
|
||
```bash
|
||
# 完整示例：茅台年度报告（自动拉数据+生成图表+输出 PPT）
|
||
python scripts/gen_moutai_report.py
|
||
|
||
# 风险分析报告
|
||
python scripts/gen_moutai_risk.py
|
||
```
|
||
|
||
## 工具脚本速查
|
||
|
||
| 脚本 | 用途 | 用法 |
|
||
|------|------|------|
|
||
| `parse_template.py` | 解析模板占位符清单 | `<template.pptx> [--flat]` |
|
||
| `describe_chart.py` | 描述已有图表结构 | `<input.pptx> [--slide N]` |
|
||
| `list_presets.py` | 查询所有可用预设 | `[--color-schemes\|--date-axis\|--chart-presets\|--all]` |
|
||
| `add_placeholders.py` | 给已有 PPT 注入占位符 | `<in.pptx> <out.pptx> <map.json>` |
|
||
|
||
所有脚本遵循统一约定：**JSON 输出到 stdout，日志输出到 stderr**。
|
||
|
||
## 内置预设
|
||
|
||
### 配色方案（8 种）
|
||
|
||
| 名称 | 色值 | 场景 |
|
||
|------|------|------|
|
||
| `aim00` | `C0C0C0` `C00000` `305496` `808080` | 养老金报告：浅灰柱+深红线 |
|
||
| `default` | 深红/深蓝/深橙/深灰 + 浅色 | 通用 |
|
||
| `dark_only` | `C00000` `0070C0` `ED7D31` `595959` | 深色系 |
|
||
| `light_only` | `FF9999` `9DC3E6` `F4B183` `BFBFBF` | 浅色系 |
|
||
| `red/blue/orange/gray_series` | 各两色渐变 | 单系列强调 |
|
||
|
||
### 日期轴预设（6 种）
|
||
|
||
| 预设 | 间隔 | 格式 | 数据量 |
|
||
|------|------|------|--------|
|
||
| `DAILY_TICKS` | 1 天 | `mm-dd` | 1-30 天 |
|
||
| `WEEKLY_TICKS` | 7 天 | `yyyy-mm-dd` | 1-6 个月 |
|
||
| `BIWEEKLY_TICKS` | 14 天 | `yyyy-mm-dd` | 季度 |
|
||
| `MONTHLY_TICKS` | 1 月 | `yyyy-mm` | 年度 |
|
||
| `QUARTERLY_TICKS` | 3 月 | `yyyy-mm` | 多年 |
|
||
| `YEARLY_TICKS` | 1 年 | `yyyy` | 长期 |
|
||
|
||
### 养老金图表预设（4 种）
|
||
|
||
| 预设 | 系列 | 所需列 |
|
||
|------|------|--------|
|
||
| 当年收益率走势 | bar(右)+line(左) | `分类`, `沪深300指数(收盘价)`, `组合收益率（左轴）` |
|
||
| 成立以来收益率 | area(右)+line(左) | `分类`, `组合规模(万元)`, `累计收益率` |
|
||
| 权益仓位走势 | area(右)+line(左) | `分类`, `沪深300指数(收盘价)`, `权益仓位（人社部口径）` |
|
||
| 久期走势 | bar(右)+line(左) | `分类`, `中债新综合总财富指数(收盘价)`, `久期` |
|
||
|
||
## 智能配置（新增）
|
||
|
||
skill 底层的 `ppt_station` 新增了两个模块，可大幅减少手工配置：
|
||
|
||
### StyleExtractor — 从参考 PPT 提取风格
|
||
|
||
```python
|
||
from ppt_station.extractors import StyleExtractor
|
||
profile = StyleExtractor("reference.pptx").extract()
|
||
style_config = profile.to_style_config() # → StyleConfig
|
||
layout_config = profile.to_chart_layout_config() # → ChartLayoutConfig
|
||
```
|
||
|
||
### ChartAdvisor — DataFrame 自动推荐图表配置
|
||
|
||
```python
|
||
from ppt_station.advisors import ChartAdvisor
|
||
rec = ChartAdvisor.suggest(df, title="三一重工 vs 沪深300")
|
||
# rec.to_kwargs() → {"categories_col", "series_config", "layout_config", "style_config"}
|
||
```
|
||
|
||
自动识别中文金融列名（收益率→line/primary/0%，指数→bar/secondary/#,##0 等），3 行代替 30+ 行手工配置。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cd ppt-st
|
||
|
||
# 跑所有集成测试
|
||
for t in skill/tests/test_*.sh; do bash "$t"; done
|
||
|
||
# 单独跑
|
||
bash skill/tests/test_parse_template.sh
|
||
bash skill/tests/test_generate_ppt.sh
|
||
bash skill/tests/test_run_job.sh
|
||
bash skill/tests/test_parse_rebuild.sh
|
||
bash skill/tests/test_describe_chart.sh
|
||
|
||
# ChartAdvisor + StyleExtractor 单元测试
|
||
python output/sany_moat/test_advisor.py
|
||
```
|
||
|
||
## 关键约束
|
||
|
||
1. **路径**：脚本内部用 `Path(__file__).resolve()` 定位项目根，不要用绝对路径。CSV 路径相对于 config.json 所在目录。
|
||
2. **merge 变换未实现**：Job JSON 中不要用 `merge`，用 `from: [src1, src2]` concat 替代。
|
||
3. **占位符匹配**：`{@图:ChartName}` 与 config.json 中的 key 必须完全一致（区分大小写）。
|
||
4. **Tushare 索引数据**：用 `pro_bar(asset="I")` 而非 `index_daily`（后者可能失败）。
|
||
|
||
## 参考文档
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [chart-config.md](reference/chart-config.md) | 图表系列、样式、布局、日期轴完整字段 |
|
||
| [job-schema.md](reference/job-schema.md) | Job JSON 声明式配置完整结构 |
|
||
| [placeholder-syntax.md](reference/placeholder-syntax.md) | 文本/图表/表格占位符格式 |
|
||
| [connectors-transforms.md](reference/connectors-transforms.md) | 3 种数据源 + 7 种变换操作 |
|
||
| [workflow-template.md](reference/workflow-template.md) | Flow A 模板替换详解 |
|
||
| [workflow-engine.md](reference/workflow-engine.md) | Flow B Job 引擎详解 |
|
||
| [workflow-parse-rebuild.md](reference/workflow-parse-rebuild.md) | Flow C 解析重建详解 |
|
||
| [workflow-tushare.md](reference/workflow-tushare.md) | Flow D Tushare 集成详解 |
|