# 小六壬AI占卜技能

`占卜` `Claude Code` `小六壬` `五行生克` `AI解读`

# 小六壬占卜 — Claude Code Skill

传统九宫小六壬占卜系统，作为 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 技能（Skill）运行，结合 AI 智慧解读卦象。

支持数字、日期时间、汉字笔画、当前时间四种起卦方式，输出三传（初传→中传→末传）占卜结果，并由 LLM 结合五行生克进行个性化解读。

---

## 安装

### 一键安装（推荐）

使用 [skills.sh](https://skills.sh) 一键安装到当前项目：

```bash
# 使用 bunx
bunx skills add https://github.com/aicoder2048/mini-six-ren-skill

# 或使用 npx
npx skills add https://github.com/aicoder2048/mini-six-ren-skill
```

### 手动安装

将 `.claude/skills/mini-six-ren/` 目录复制到你的任意项目的 `.claude/skills/` 下：

```bash
# 在目标项目根目录执行
mkdir -p .claude/skills
cp -r <path-to>/XiaoLiuRenSkill/.claude/skills/mini-six-ren .claude/skills/
```

安装完成后，在该项目中使用 Claude Code 时，输入占卜相关的自然语言（如"占一卦""算算运势"等），Claude 会自动识别并调用此技能。

**运行环境要求**：
- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) — 脚本使用 PEP 723 内联元数据，uv 会自动处理依赖安装（`lunardate>=0.2.0`）

### Opencode CLI 移植建议

> 以下为迁移思路，未经测试。

[Opencode](https://github.com/opencode-ai/opencode) 的 Agent 体系与 Claude Code Skill 有所不同。核心算法脚本 `scripts/xiaoliu.py` 是独立可执行的，可直接复用。迁移时需要：

1. 将 `SKILL.md` 中的工作流描述改写为 Opencode 的 Agent 配置格式
2. 将 `assets/template.md` 报告模板和 `references/symbols_reference.md` 参考文档放入 Opencode 对应的上下文目录
3. 在 Agent 配置中声明调用 `uv run scripts/xiaoliu.py` 的命令

---

## 小六壬算法详解

### 九宫符号

小六壬使用 9 个符号，每个符号对应五行、方位、神灵：

| 序号 | 符号 | 五行 | 方位 | 关键词 | 神灵 |
|:---:|:---:|:---:|:---:|---|:---:|
| 1 | 大安 | 木 | 正东 | 长期、缓慢、稳定 | 三清 |
| 2 | 留连 | 木 | 东南 | 停止、反复、复杂 | 文昌 |
| 3 | 速喜 | 火 | 正南 | 惊喜、快速、突然 | 雷祖 |
| 4 | 赤口 | 金 | 正西 | 争斗、凶恶、伤害 | 将帅 |
| 5 | 小吉 | 水 | 正北 | 起步、不多、尚可 | 真武 |
| 6 | 空亡 | 土 | 中间 | 失去、虚伪、空想 | 玉皇 |
| 7 | 病符 | 土 | 西南 | 病态、异常、治疗 | 后土 |
| 8 | 桃花 | 土 | 东北 | 欲望、牵绊、异性 | 城隍 |
| 9 | 天德 | 金 | 西北 | 贵人、长辈、上司 | 紫薇 |

#### 吉凶简判

- **大吉**：大安、速喜、天德
- **小吉**：小吉、留连（视情况）
- **凶**：赤口（最凶）、空亡（金钱最忌）、病符
- **中性**：桃花（恋爱吉，其余不吉）

### 左手掌诀

九宫符号排列在左手指节上，按顺序循环：

```
食指:   [留连②]
         ↓
中指:   [大安①] → [速喜③]
         ↑
无名指: [天德⑨] ← [赤口④]
         ↑
        [小吉⑤]
        [空亡⑥]
        [病符⑦]
        [桃花⑧]
```

顺序：大安→留连→速喜→赤口→小吉→空亡→病符→桃花→天德（循环）

### 三传算法

输入三个数字 `(num1, num2, num3)`，计算三传符号：

1. **初传（前期）**：从第 1 位（大安）出发，走 `num1` 步
2. **中传（中期）**：从初传的落点出发，走 `num2` 步
3. **末传（后期）**：从中传的落点出发，走 `num3` 步

每一步都在 9 个符号之间循环。算法核心：

```
初传位置 = (0 + num1 - 1) % 9
中传位置 = (num1 - 1 + num2 - 1) % 9       # 即 (num1 + num2 - 2) % 9
末传位置 = (num1 + num2 - 2 + num3 - 1) % 9 # 即 (num1 + num2 + num3 - 3) % 9
```

> 特殊处理：步数为 9 的倍数时映射到第 9 位（天德），而非回到第 1 位。

### 五行生克关系

**相生**（促进）：

```
木 → 火 → 土 → 金 → 水 → 木（循环）
```

**相克**（制约）：

```
木 → 土 → 水 → 火 → 金 → 木（循环）
```

系统判断 6 种关系：

| 关系 | 说明 | 对事态影响 |
|:---:|---|---|
| 生 | 前者促进后者 | 顺利推进，有助发展 |
| 克 | 前者制约后者 | 存在阻碍，需克服困难 |
| 被生 | 后者反哺前者 | 有外力支持 |
| 被克 | 后者反制前者 | 受到压制 |
| 同 | 同属一行 | 相互扶持，力量加强 |
| 无 | 无直接关系 | 各自独立发展 |

### 解读优先级

1. 先看**末传**（最终结果最重要）
2. 再看三传之间的**五行生克关系**
3. 最后结合各符号本身的含义和求问事项

---

## 输入模式

### 数字模式 `--numbers`

直接提供 3 个数字（逗号分隔），用作三传计算的步数。

```bash
uv run scripts/xiaoliu.py --numbers 3,5,7 --question "事业运势" --format json
```

### 日期时间模式 `--datetime`

提供公历日期时间，系统自动转换：

1. 公历 → **农历**（使用 `lunardate` 库）
2. 取农历**月份**作为第一个数字
3. 取农历**日期**作为第二个数字
4. 将小时转换为**时辰序号**作为第三个数字

```bash
uv run scripts/xiaoliu.py --datetime "2025-07-15 10:30" --question "面试能成功吗" --format json
```

**时辰对照表**：

| 时辰 | 时间段 | 序号 |
|:---:|:---:|:---:|
| 子时 | 23:00-01:00 | 1 |
| 丑时 | 01:00-03:00 | 2 |
| 寅时 | 03:00-05:00 | 3 |
| 卯时 | 05:00-07:00 | 4 |
| 辰时 | 07:00-09:00 | 5 |
| 巳时 | 09:00-11:00 | 6 |
| 午时 | 11:00-13:00 | 7 |
| 未时 | 13:00-15:00 | 8 |
| 申时 | 15:00-17:00 | 9 |
| 酉时 | 17:00-19:00 | 10 |
| 戌时 | 19:00-21:00 | 11 |
| 亥时 | 21:00-23:00 | 12 |

### 汉字模式 `--chars`

提供 3 个汉字，系统查询笔画数作为输入数字：

```bash
uv run scripts/xiaoliu.py --chars "天地人" --question "感情运势" --format json
```

- 内置约 150+ 常用汉字笔画表
- 不在表中的字使用 Unicode 编码取模近似

### 当前时间模式 `--now`

使用系统当前时间，自动按日期时间模式转换：

```bash
uv run scripts/xiaoliu.py --now --question "今天适合出行吗" --format json
```

---

## 使用演示

安装完成后，在 Claude Code 中直接用自然语言即可唤起占卜技能。以下为典型使用场景：

### Demo 1：当前时间占卜

**用户输入**：

> 占一卦今日运势

Claude Code 自动识别占卜意图，调用 `--now` 模式获取当前时间，转换为农历月日和时辰后计算三传，生成完整的占卜报告和 AI 解读。

### Demo 2：指定日期占卜

**用户输入**：

> 2025年7月15日上午10点半面试，帮我占一卦

Claude Code 从自然语言中提取日期时间 `2025-07-15 10:30`，调用 `--datetime` 模式：
- 公历 2025-07-15 → 农历六月二十一
- 10:30 → 巳时（序号 6）
- 输入数字：`[6, 21, 6]`
- 三传结果：空亡(土) → 桃花(土) → 赤口(金)
- 五行关系：同 → 生

AI 解读会结合面试场景，分析初期可能的不确定感（空亡）、人际交流的重要性（桃花）、以及需注意口舌争端的提醒（赤口）。

### Demo 3：汉字起卦

**用户输入**：

> 用"天地人"三个字帮我算算感情运势

Claude Code 提取汉字并调用 `--chars` 模式：
- 天 = 4 画，地 = 6 画，人 = 2 画
- 输入数字：`[4, 6, 2]`
- 三传结果：赤口(金) → 天德(金) → 大安(木)
- 五行关系：同 → 克

AI 解读会结合感情主题，提醒注意口舌之争（赤口）、可寻求长辈指点（天德）、最终趋于安稳（大安）。

### Demo 4：数字起卦

**用户输入**：

> 我心里想了三个数 3、5、7，占一卦事业运

Claude Code 提取数字并调用 `--numbers 3,5,7`：
- 三传结果根据数字 `[3, 5, 7]` 计算
- AI 解读会围绕事业主题展开分析

### Demo 5：生活场景

**用户输入**：

> 我爸爸下周三要做白内障手术，帮我占一卦

Claude Code 会根据下周三的具体日期调用 `--datetime` 模式，生成完整的占卜报告。AI 解读会结合健康/手术主题，分析三传卦象的含义，给出实际的宽慰和建议。

> 报告输出使用内置的 Markdown 模板，包含三传结果表格、符号详解、五行关系、以及 AI 智慧解读。

---

## 使用第三方 LLM 解读（可选）

默认情况下，占卜解读由 Claude Code 内置模型完成，无需额外配置。如果你希望使用第三方模型（如 DeepSeek、GPT、Kimi 等），按以下两步配置：

### 第 1 步：在 `config.yaml` 中激活模型

编辑 `.claude/skills/mini-six-ren/config.yaml`，取消注释你想使用的模型行：

```yaml
# 取消注释下方某一行以启用第三方模型解读。
# 不配置或全部注释 = 使用 Claude Code 内置模型解读（默认）。

# --- DeepSeek ---
model: deepseek:deepseek-chat

# --- OpenAI ---
# model: openai:gpt-5-mini
# model: openai:gpt-5.2

# --- Moonshot Kimi ---
# model: kimi:kimi-k2.5

# --- Anthropic ---
# model: anthropic:claude-sonnet-4.5

# --- Google Gemini ---
# model: google:gemini-3-flash

# ... 更多选项见 config.yaml 文件
```

> 同一时间只能激活一个模型，确保只有一行 `model:` 未被注释。

### 第 2 步：在 `.env` 中提供 API Key

参照 `.env.sample`，在 `.claude/skills/mini-six-ren/.env` 中填入对应的 API Key：

```bash
# 示例：使用 DeepSeek
DEEPSEEK_API_KEY=sk-your-deepseek-api-key

# 示例：使用 OpenAI
# OPENAI_API_KEY=sk-your-openai-api-key
```

完整的 Provider 与 API Key 对照表：

| Provider | `config.yaml` 前缀 | `.env` 变量 |
|---|---|---|
| DeepSeek | `deepseek:` | `DEEPSEEK_API_KEY` |
| OpenAI | `openai:` | `OPENAI_API_KEY` |
| Anthropic | `anthropic:` | `ANTHROPIC_API_KEY` |
| Google Gemini | `google:` | `GEMINI_API_KEY` |
| Moonshot Kimi | `kimi:` | `MOONSHOT_API_KEY` |
| Alibaba Qwen | `qwen:` | `DASHSCOPE_API_KEY` |
| Zhipu GLM | `glm:` | `ZHIPU_API_KEY` |

> 切换回内置模型：将 `config.yaml` 中的 `model:` 行全部注释掉即可。

---

## 项目结构

```
.claude/skills/mini-six-ren/       # Claude Code 技能目录
├── SKILL.md                        # 技能定义（工作流、触发关键词、分析指南）
├── config.yaml                     # 第三方 LLM 模型配置（可选）
├── .env.sample                     # API Key 配置示例
├── .env                            # API Key（不提交到 Git）
├── scripts/
│   ├── xiaoliu.py                  # 核心算法（PEP 723 单文件脚本）
│   └── interpret.py                # 第三方 LLM 解读脚本
├── examples/
│   ├── example_number_input.md     # 数字输入示例
│   ├── example_datetime_input.md   # 日期时间输入示例
│   └── example_chars_input.md      # 汉字输入示例
├── assets/
│   └── template.md                 # 占卜报告 Markdown 模板
└── references/
    └── symbols_reference.md        # 九宫符号详解参考表
```

---

## 技术细节

### 脚本运行

`xiaoliu.py` 使用 [PEP 723](https://peps.python.org/pep-0723/) 内联脚本元数据，通过 `uv run` 直接执行，无需预先安装项目或创建虚拟环境：

```bash
uv run scripts/xiaoliu.py --now --format text
```

唯一外部依赖为 `lunardate>=0.2.0`（公历↔农历转换），uv 会在首次运行时自动安装。

### 输出格式

- `--format json`：结构化 JSON，供 LLM 分析和模板填充
- `--format text`：人类可读的文本表格

### LLM 分析结构

技能调用 `--format json` 获取结构化数据后，LLM 按以下结构生成解读：

1. **卦象总览** — 三传符号和五行总结
2. **时间发展脉络** — 初传（当前状态）→ 中传（发展变化）→ 末传（最终结果）
3. **五行生克解读** — 元素关系如何影响事态走向
4. **具体建议** — 与求问事项相关的可操作建议
5. **关键提示** — 方位、时机、神灵等辅助信息

---

## 许可证

MIT

## 免责声明

本项目为文化传承和娱乐用途，占卜结果仅供参考。请勿将占卜结果作为重大决策的唯一依据。