# Docs Generator

> 报告生成子技能。定义五运六气分析报告的标准格式与模板，支持简明版、临床版、研究版三种报告类型。触发词：运气报告、运气分析报告、报告生成、五运六气报告、docs-generator。

- Skill: `dhicoc/docs-generator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dhicoc/docs-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dhicoc/docs-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dhicoc (https://skillmd.com/u/dhicoc)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/dhicoc/docs-generator

---


# 报告生成（运气分析报告标准格式）

## 适用范围

- 根据上游推算结果生成结构化的五运六气分析报告
- 支持三种报告类型：简明版（student）、临床版（practitioner）、研究版（researcher）
- 确保报告包含必要的免责声明与推算脚本标注
- 为不同使用场景（教学、临床、研究）提供适配的报告格式

## 脚本依赖

本子技能无独立脚本依赖，但需要调用上游子技能的推算结果：

| 依赖来源 | 数据内容 | 格式要求 |
|---------|---------|---------|
| `ganzhi-basics` | 干支、甲子序号、大运、六气格局、节气运气交司 | 结构化键值对 |
| `yunqi-classics` | 文献引用、理论依据、验证结论 | 结构化引用列表 |
| `calculate_yunqi_api.py` | 推算脚本名称与版本 | 字符串 |

## 推荐工作流

1. **ACT: 收集推算结果**，从 `ganzhi-basics` 获取干支推算数据（公历年份、天干、地支、完整干支、甲子序号、大运五行及太过不及、司天在泉、六气格局、节气运气交司关系），从 `yunqi-classics` 获取文献引用与理论验证结论。
2. **ACT: 确定报告类型**，根据用户身份与使用场景选择报告类型：
   - **简明版（student）**：面向学生与初学者，侧重干支与运气格局的简明呈现
   - **临床版（practitioner）**：面向临床中医师，侧重病机分析与治法方药
   - **研究版（researcher）**：面向研究人员，侧重文献引用与理论讨论
3. **ACT: 按模板生成报告**，根据所选报告类型对应的模板生成报告内容。各模板格式见下方"报告模板"章节。报告中所有推算数据须标注来源脚本。
4. **ACT: 附加免责声明**，在报告末尾附加标准免责声明。免责声明为报告的必须组成部分，不得省略。免责声明内容见下方"免责声明"章节。
5. **ACT: 校验报告完整性**，检查报告是否包含所有必要章节、是否标注推算脚本、是否附加免责声明。校验通过后输出最终报告。

## 脚本调用示例

| 使用场景 | 命令 |
|----------|------|
| 快速摘要 | `python scripts/calculate_yunqi_api.py 2026-06-29 --summary` |
| 完整报告（学生版） | `python scripts/calculate_yunqi_api.py 2026-06-29 --report-type student` |
| 完整报告（临床版） | `python scripts/calculate_yunqi_api.py 2026-06-29 --report-type practitioner` |
| 完整报告（研究版） | `python scripts/calculate_yunqi_api.py 2026-06-29 --report-type researcher` |
| 仅输出 JSON 数据 | `python scripts/calculate_yunqi_api.py 2026-06-29 --json` |
| 年度综合报告 | `python scripts/yunqi_report.py 2026 --audience student\|practitioner\|researcher` |
| 验证安装 | `python tests/verify_expansion.py` + `tests/full_regression_test.py`（105/0 + 55/0） |

## 报告模板

### 简明版（student）

面向学生与初学者，侧重运气格局的简明呈现。**学生版报告默认附带术语解释**，帮助初学者理解专业概念。

```
# 五运六气分析报告（简明版）

## 基本信息
- 公历年份：[年份]
- 干支：[天干][地支]（第[序号]甲子）
- 推算脚本：scripts/calculate_yunqi_api.py

## 大运（中运）
- 天干：[天干] → 化[五行]运
- 运气特征：[太过/不及]
- 气候趋势：[简述]

## 六气格局
- 司天：[司天之气]（主上半年）
- 在泉：[在泉之气]（主下半年）
- 主气六步：[初之气~终之气简列]

## 节气运气交司
- 当前节气：[节气名]
- 所处主气：[步位]（[六气名]）
- 所处主运：[步位]（[五行运]）

## 简述
[一段简明的运气格局总结，100-200字]

## 术语解释（学生版默认附带）
- **岁运**：五运六气中一年的主管运气，由年干决定，每10年一个周期。
- **司天**：主管上半年的气，由年支决定。
- **在泉**：主管下半年的气，与司天相对。
- **主气**：每年固定不变的六气，代表正常季节气候。
- **客气**：每年变动的六气，客气加临主气形成客主加临。
- **客主加临**：客气与主气叠加，顺则气候平和，逆则气候异常。
- **[当前司天/在泉/主气/客气术语]**：分别解释当前出现的六气术语。

> 如需更完整的术语解释，可运行：
> `python scripts/calculate_yunqi_api.py [日期] --explain`

---
免责声明：本报告基于五运六气理论推算生成，仅供参考与学习之用，
不构成任何医疗建议。运气学说为古代气候医学理论，其预测准确性
存在争议。如有健康问题，请咨询专业医师。
```

### 临床版（practitioner）

面向临床中医师，侧重病机分析与治法方药。

```
# 五运六气分析报告（临床版）

## 基本信息
- 公历年份：[年份]
- 干支：[天干][地支]（第[序号]甲子）
- 推算脚本：scripts/calculate_yunqi_api.py

## 完整推算
### 大运（中运）
- 天干：[天干] → 化[五行]运
- 运气特征：[太过/不及]
- 大运说明：[依据《气交变大论》/《五常政大论》的理论依据]

### 司天在泉
- 司天：[司天之气]
- 在泉：[在泉之气]
- 司天在泉说明：[依据《天元纪大论》的理论依据]

### 主客气加临
- 主气六步：[初之气~终之气列表]
- 客气六步：[初之气~终之气列表]
- 加临分析：[主客胜复关系，依据《六元正纪大论》]

### 运气同化判断
- 是否天符/岁会/太一天符：[判断结果]
- 特殊意义：[如有，说明]

## 病机分析
### 大运病机
- [五行]运[太过/不及]的病机特点：[依据《气交变大论》]
- 易患脏腑：[脏腑]
- 症候倾向：[症状描述]

### 六气病机
- 司天[之气]所致病候：[依据《至真要大论》]
- 在泉[之气]所致病候：[依据《至真要大论》]
- 病机十九条相关：[相关条文]

### 综合病机
- 全年疾病倾向：[综合分析]
- 高发季节与疾病：[按六步分析]

## 治法方药
### 治则
- 基本治则：[依据《至真要大论》]
- 用药禁忌：[用寒远寒/用热远热等]

### 推荐方向
- 调理脏腑：[目标脏腑]
- 用药气味：[五味配属]
- 方剂方向：[推荐方剂类型，非具体方剂]

### 各步治法
- 初之气（[节气范围]）：[治法建议]
- 二之气（[节气范围]）：[治法建议]
- 三之气（[节气范围]）：[治法建议]
- 四之气（[节气范围]）：[治法建议]
- 五之气（[节气范围]）：[治法建议]
- 终之气（[节气范围]）：[治法建议]

---
免责声明：本报告基于五运六气理论推算生成，仅供中医临床参考之用，
不构成具体医疗诊断或处方建议。运气学说为古代气候医学理论，其临床
应用须结合患者实际情况，由具备执业资格的中医师综合判断。方剂方向
仅为理论推演，具体处方须由执业医师根据患者个体情况确定。如有健康
问题，请及时就医。
```

### 研究版（researcher）

面向研究人员，侧重文献引用与理论讨论。

```
# 五运六气分析报告（研究版）

## 基本信息
- 公历年份：[年份]
- 干支：[天干][地支]（第[序号]甲子）
- 推算脚本：scripts/calculate_yunqi_api.py

## 完整推算
### 大运（中运）
- 天干：[天干] → 化[五行]运
- 运气特征：[太过/不及]
- 理论依据：《天元纪大论》第66篇

### 司天在泉
- 司天：[司天之气]
- 在泉：[在泉之气]
- 理论依据：《天元纪大论》第66篇

### 主客气加临
- 主气六步：[列表]
- 客气六步：[列表]
- 理论依据：《六微旨大论》第68篇、《六元正纪大论》第71篇

### 运气同化
- 判断：[结果]
- 理论依据：《六元正纪大论》第71篇

## 文献引用
### 经典文献
1. [篇名]（第[篇号]篇）："[引用经文片段]" —— [与推算结果的关联说明]
2. [篇名]（第[篇号]篇）："[引用经文片段]" —— [与推算结果的关联说明]
...

### 历代注家
1. [医家]《[著作]》：[观点摘要] —— [与推算结果的关联]
2. [医家]《[著作]》：[观点摘要] —— [与推算结果的关联]
...

### 现代研究
- 相关研究方向：[方向概述]
- 研究概况：[简述，标注为研究方向概述而非具体结论]
- 注意：现代研究内容为方向性概述，如需引用具体数据须检索原始论文

## 理论讨论
### 推算结果的理论一致性
- 与经典论述的一致性：[一致/部分一致/存在差异] —— [说明]
- 与历代注家观点的一致性：[一致/部分一致/存在差异] —— [说明]

### 学术争议
- [如有争议，列出不同观点及出处]

### 方法论说明
- 推算方法：天干化运、地支化气
- 立春分界：[说明]
- 太过不及判断：阳干太过、阴干不及

## 参考文献
- [1] 《黄帝内经·素问》[篇名]大论（第[篇号]篇）
- [2] [医家]《[著作]》
- [3] 现代研究方向：[方向名称]（概述性引用，非具体论文）
...

---
免责声明：本报告基于五运六气理论推算生成，仅供学术研究参考之用。
运气学说为古代气候医学理论，其科学性仍存在学术争议。报告中引用的
现代研究内容为研究方向概述，不代表具体研究结论。如需引用具体研究
数据，须通过学术数据库检索原始论文。本报告不构成任何医疗建议。
```

## 免责声明

### 标准免责声明要求

所有报告必须包含免责声明，且须满足以下要求：

| 要求 | 说明 |
|------|------|
| 位置 | 报告末尾，以分隔线（---）与正文分隔 |
| 内容 | 包含"仅供参考"声明 + "不构成医疗建议"声明 + "运气学说存在争议"声明 |
| 适配 | 根据报告类型调整措辞（简明版简述、临床版强调执业医师、研究版强调学术争议） |
| 不可省略 | 免责声明为报告必须组成部分，任何情况下不得省略 |

### 推算脚本标注要求

| 要求 | 说明 |
|------|------|
| 标注位置 | 报告"基本信息"章节中 |
| 标注内容 | 推算脚本名称（如 calculate_yunqi_api.py） |
| 标注格式 | "推算脚本：[脚本名]" |
| 不可省略 | 所有报告类型均须标注推算脚本来源 |

## 视觉规范（宣纸水墨）

任何面向读者的视觉产物（HTML 报告 / PDF / 卡片 / 时间轴 / Anki，含 agent 现场手写的 HTML/UI）必须复用 `scripts/lib/ink_theme.py` 的宣纸水墨设计 token，**禁止 agent 现场自由发挥视觉风格**（如深色霓虹配色）。

要点：

- 统一引用 ink_theme 导出的 CSS 变量：`--paper`（纸色）、`--ink`（墨色阶）、`--vermilion`（朱砂）、`--wx-*`（五行正色）、`--gold`（落款金）；字体用 `ink_theme.SERIF`（宋体）。
- 脚本侧已复用：本报告经 `generate_html_report.py` 生成时即套用 ink_theme；`export_thought.py` / `visualize_timeline.py` 同理。**agent 不得擅自换肤或另起一套配色。**
- 校验：可用 `scripts/check_visual_consistency.py` 对 `reports/**` 与 `scripts/**` 做一致性关卡——视觉产物未引用 ink_theme token 即报错。

> 设计原则见项目根 `.impeccable.md`：墨分五色、五行正色、留白即气、宋体为骨、屏印双态、装饰有意图。

## 常见误区

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 报告缺少免责声明 | 生成时遗漏或认为不必要 | 免责声明为必须组成部分，Step4不可跳过。校验时检查免责声明是否存在 |
| 报告未标注推算脚本 | 忽略脚本来源标注要求 | 在"基本信息"章节中必须包含"推算脚本：[脚本名]"字段 |
| 报告类型选择不当 | 未根据用户身份选择合适的报告类型 | Step2根据用户身份选择：学生→简明版，临床医师→临床版，研究者→研究版 |
| 临床版给出具体方剂 | 将"方剂方向"误写为具体方剂处方 | 临床版仅提供"方剂方向"（如"健脾化湿"），不给出具体方剂名称与药物组成 |
| 研究版引用现代研究不当 | 将研究方向概述当作具体论文结论引用 | 研究版现代研究部分须标注为"研究方向概述"，引用具体数据须检索原始论文 |
| 报告格式不统一 | 未按模板生成，自由发挥 | 严格按对应模板生成报告，各章节顺序与标题不得擅自更改 |
| 推算数据与上游不一致 | 报告中的推算数据与上游子技能输出不一致 | Step1须完整收集上游数据，报告中所有推算数据须与上游输出一致 |

## 输出要求

- 报告必须按对应模板格式生成，章节顺序与标题不得擅自更改
- 报告必须包含免责声明，位置在报告末尾，以分隔线分隔
- 报告必须标注推算脚本名称，位置在"基本信息"章节
- 简明版报告字数控制在500字以内（不含免责声明）
- 临床版报告须包含病机分析与治法方向，但不得给出具体方剂处方
- 研究版报告须包含文献引用与理论讨论，现代研究部分须标注为概述性引用
- 所有术语须使用标准中医运气学说术语
- 报告默认输出为 Markdown 格式；若输出 HTML / 可视化报告（含 agent 手写的任何视觉产物），必须复用 `scripts/lib/ink_theme.py` 宣纸水墨设计体系（统一引用 `--paper` / `--ink` / `--vermilion` / `--wx-*` 等 CSS 变量），禁止现场手写配色

## 路由上下文

- **上游入口**：接收 `ganzhi-basics` 的干支推算结果（干支、甲子序号、大运、六气格局、节气运气交司）和 `yunqi-classics` 的文献引用与理论验证结论
- **下游出口**：输出完整的五运六气分析报告（Markdown 为主；HTML/可视化报告须复用 `ink_theme` 宣纸水墨体系），交付给用户
- **同级关联**：与 `ganzhi-basics` 和 `yunqi-classics` 同级。`ganzhi-basics` 提供推算数据，`yunqi-classics` 提供文献支撑，本子技能负责整合为最终报告

---

## ACTION REQUIRED

- [ ] 确认上游 `ganzhi-basics` 的输出数据已完整收集
- [ ] 确认上游 `yunqi-classics` 的文献引用已完整收集（如适用）
- [ ] 确认 `calculate_yunqi_api.py` 脚本名称已知
- [ ] 确认报告类型已根据用户身份确定
- [ ] 确认免责声明内容已准备
- [ ] 确认报告模板已加载

---

## 任务完成自检

- [ ] 报告按对应模板格式生成，章节完整
- [ ] 报告包含"基本信息"章节，且标注了推算脚本名称
- [ ] 报告末尾包含免责声明，以分隔线分隔
- [ ] 免责声明内容适配报告类型（简明/临床/研究）
- [ ] 报告中所有推算数据与上游子技能输出一致
- [ ] 临床版报告未给出具体方剂处方（仅方剂方向）
- [ ] 研究版报告现代研究部分标注为概述性引用
- [ ] 报告输出为 Markdown 格式（HTML/可视化产物须复用 ink_theme 宣纸水墨体系）
- [ ] 所有术语使用标准中医运气学说术语
- [ ] 若含 HTML/可视化产物，已复用 ink_theme（`--paper`/`--ink`/`--vermilion`/`--wx-*`），未现场换肤