dhicoc/wuyun-liuqi-skills

wuyun-liuqi-skills TCM Yunqi Skills Router · 五运六气技能路由包

天人合一，五运六气

AI 自动路由 + 确定性推算引擎 + RAG 知识库 + 自进化经验库 支持 Claude Code / Cursor / Codex CLI / Cline / OpenClaw 等 AI 客户端

这是什么 · 适合谁用 · 快速上手 · 核心能力 · 项目结构 · 贡献

🌐 English

---

这是什么

如果你是 AI Agent，直接跳转到 README_AI.md，严格按照内容要求执行。

当用户对 AI Agent（Claude、Cursor、Codex 等）说「今年运气怎么样」「我出生那年的体质倾向」「历代医家怎么治头痛」时，这个技能包让 Agent 调用确定性推算引擎算出干支运气格局，从 3727 条真实医案中检索相关病机与治法，再用通俗语言讲给用户听——而不是凭记忆胡编。

用户提问（自然语言）
  -> routing.yaml 路由匹配
  -> calculate_yunqi_api.py 推算引擎（大寒定年，非幻觉）
  -> rag_search 检索 39 个 RAG asset（3727 条医案 + 33 条疾病易感性）
  -> infer_pathogenesis 病机推理链
  -> 通俗语言解释 + 免责声明
  -> self_evolve 自动沉淀经验

当前状态

路由核心由一个 routing.yaml 驱动，跨工具薄壳自动发现，推算引擎与知识库分离。

(返回顶部)

为什么需要这个项目：

• 大模型容易对干支、司天在泉、客主加临产生幻觉–本包用确定性推算引擎，大寒定年，结果可复现
• 运气知识分散在经典中，普通人难以系统掌握–本包把 51 篇公版文献蒸馏成可 Grep 的结构化指南
• 缺少专为 Agent 设计的运气学技能包–本包提供路由契约、ReAct 工作流、自进化经验库，开箱即用

⚠️ 运气学为中医传统理论，本包用于学习研究与辅助推理，不构成医学诊断或治疗建议。临床决策须由执业医师处理。

适合谁用

• 中医学生 / 研究者 —— 需要准确推算某年某步运气格局，检索历代医家临证经验
• AI 应用开发者 —— 想给 Agent 加一个可靠的运气学能力，而非自己从头实现
• 运气学爱好者 —— 想通过自然对话理解天人合一、气化、中和这些思想，而不是背表格

快速上手

最短安装（推荐）

把下面这段话直接发给 Claude（或其他支持技能的 AI）：

仓库地址：https://github.com/dhicoc/wuyun-liuqi-skills.git

请按 workflows/one-line-install.md 帮我安装五运六气技能包：
克隆仓库、运行 python scripts/install.py --link-global、验证通过。

AI 会完成：克隆 → 注册全局技能 → 验证。之后在任意项目里说「五运六气」即可激活。

手动安装

# 1. 克隆
git clone https://github.com/dhicoc/wuyun-liuqi-skills.git
cd wuyun-liuqi-skills

# 2. 装 Python 依赖（仅需 lunar-python，用于精确节气）
pip install -r requirements.txt

# 3. 可选：Node.js 接口依赖
npm install

# 4. 注册全局技能（Claude / Cursor 自动发现）
python scripts/install.py --link-global

环境要求：Python 3.8+ / Node.js 14+。

三十秒验证

# 算今天的运气
python scripts/calculate_yunqi_api.py today --summary

# 深度解读某个概念
python scripts/calculate_yunqi_api.py today --level deep --explain-concept "天人合一"

# 检索医案
python scripts/rag_search.py 头痛 --asset asset26,asset27

激活方式

配置好后，直接对 Agent 说话即可：

• 「今年运气对养生有什么启发？」
• 「我出生那年的运气格局和体质有什么关系？」
• 「用简单语言解释司天在泉」
• 「历代医家怎么治头痛？给我对比孙一奎和叶天士」

核心能力

🔮 确定性推算引擎

干支推算 · 大运太过不及 · 司天在泉 · 客主加临六步 · 平气判定 · 天符岁会。Python 主链路 + JS 可选接口，双引擎一致性校验，大寒定年，结果可信。

python scripts/calculate_yunqi_api.py today --json    # Agent / JSON 接口
python scripts/calculate_yunqi_api.py 2026-06-27 --summary

📚 3727 条真实医案 · 21 部公版典籍

从维基文库公版原文逐字蒸馏，零占位、零编造，每条医案附 source_quote 原文存证。覆盖名医类案、续名医类案、古今医案按、丁甘仁、伤寒九十论、临证指南、回春录、张聿青、吴鞠通、寓意草、洄溪、花韵楼、杏轩（184 条）、孙文垣（390 条）等 21 部。

🔍 多维检索

🧠 Agent 自进化 Fallback

工具答不上来时，Agent 不拒绝、不硬编，而是：联网搜索 -> 总结回答（标注来源 + 免责声明）-> 沉淀经验到 case-journal/field-journal/ -> 下次优先查经验库。越用越聪明。

📖 五层注释链（公版蒸馏指南）

全部零依赖，Agent 直接 Grep + Read。

🎭 注家人格 Perspective

刘完素（寒凉派）与张介宾（温补派）做成可运行的 perspective skill，Agent 激活后能切换到注家视角回答问题，而非「替注家说话」。两方原文均可 Grep，形成运气学史上最尖锐的立场对照。

🏥 医学安全边界

• 所有临床输出强制附加免责声明
• 运气理论分析 ≠ 医疗建议，后者必须建议就医
• 方药标注「参考方药，须辨证加减」
• 不给出具体药物剂量

完整功能清单

共 54 个脚本 · 6 个子技能模块 · 10 个教学模块 · 2 个注家人格 · 39 个 RAG asset · 51 篇公版文献 · 12 本蒸馏指南

推算引擎（9 个）

知识检索（5 个）

检索增强与引用（本轮新增）

报告与导出（6 个）

学习与教学（3 个）

自进化与运维（7 个）

安装与校验（6 个）

子技能模块（6 个，routing.yaml 路由目标）

知识库资产

教学模块（10 个概念）

teaching-modules/ 下每个概念一个五段式模块（原文 / 注家 / 解读 / 金句 / 误区 / 深度分层）：

天人合一 · 气化 · 中和 · 大运岁运 · 五运推移 · 太过不及 · 平气 · 司天在泉 · 客主加临 · 天符岁会

注家人格（2 个）

高级对齐

CI 持续集成

• GitHub Actions 矩阵：Python 3.10/3.11/3.12 + Node 18/20/22
• 39 项 CI 校验步骤：validate · index · conformance · routing · regression · e2e · scenario · random-chain · answer-layer · retrieval-quality · cross-check · expansion · advanced-alignment 等
• 每次推送前本地跑通全部 CI 同款测试，全绿才推送

项目结构

.
├── SKILL.md                    # ★ 总控路由入口（AI 必读）
├── routing.yaml / routing.md   # ★ 路由真相源 / 人类索引
├── AGENTS.md / CLAUDE.md       # 跨工具薄壳（Codex / Claude）
├── scripts/                    # 54 个 Python 脚本 + JS 接口
│   ├── calculate_yunqi_api.py  #   ★ 主链路（大寒定年 + rag_keys）
│   ├── rag_search.py           #   ★ RAG 检索
│   ├── case_relations.py       #   医案对比 / 相似发现
│   ├── personal_yunqi_profile.py #   个人体质
│   ├── self_evolve.py          #   自进化引擎
│   └── …                       #   报告/导出/校验等
├── wuyun_liuqi/                # 可导入 Python 包
├── rag-knowledge-base/         # ★ 39 个 asset + 蒸馏指南 + 文献原文
│   ├── asset1-39 *.json        #   病机/方/注家/体质/医案（含 21 部医案库）
│   ├── *_guide.md              #   10 本公版蒸馏指南
│   └── literature/             #   51 篇公版文献原文（177.4 万字）
├── modules/                    # 子技能（routing.yaml 路由目标）
│   ├── ganzhi-basics/          #   干支基础
│   ├── yunqi-calc/             #   运气推算（核心）
│   ├── yunqi-pathogenesis/     #   病机分析
│   ├── yunqi-clinical/         #   临床应用
│   ├── yunqi-classics/         #   经典文献
│   └── docs-generator/         #   报告生成
├── perspectives/               # 注家人格（刘完素 / 张介宾）
├── rules/                      # medical-safety / calculation / agent-behavior
├── workflows/                  # bootstrap / routing-contract / task-closure
├── prompts/                    # system_prompt + expression_style
├── case-journal/               # 医案沉淀
├── tests/                      # 全量回归（39 项 CI 校验步骤）
└── .github/workflows/          # CI（Python 3.10/3.11/3.12 + Node 18/20/22）

验证

python scripts/health_check.py
python scripts/validate_knowledge_base.py
python tests/full_regression_test.py   # 等效 CI 校验（55 项回归 + 105 项扩展验证）
python tests/skill_full_feature_smoke.py --rounds 3   # 全功能全场景多轮冒烟（触发所有入口脚本 + 模块/教学/人格结构）

每次推送前本地跑通全部 CI 同款测试，全绿才推送。

贡献

欢迎 Fork → 特性分支 → PR。贡献前请阅读 CONTRIBUTING.md。

git checkout -b feature/your-feature
git commit -m "Add your feature"
git push origin feature/your-feature
# 提交 Pull Request

许可证

MIT License，详见 LICENSE。

相关项目

• huangdi-neijing-skill ⭐31 – 把《黄帝内经》素问+灵枢蒸馏成 22 个思维方法论 skill，与本项目的运气推算能力互补；其方法论已 vendored 快照集成进报告「内经方法论」章节（详见 teaching-modules/相关思维工具.md）。

致谢

• 架构参考 reverse-skill
• 理论依据：《黄帝内经素问》七篇大论
• AI 社区：linux.do