Skip to content

Commit 927a09d

Browse files
ShousenZHANGShousenZHANG
committed
docs: restructure README to big-tech standard, Chinese-default bilingual
- README.md is now the Chinese default (rendered by GitHub first); English moved to README.en.md. Each is single-language (no mixing) with a header language switcher. - Centered header block, badge row (CI/tests/coverage/license/release), TOC, Features section, refreshed metrics (977 tests, 82% coverage, 13 engines). - build_skill.py + test_build.py: README.zh.md -> README.en.md in the package whitelist. Deleted README.zh.md.
1 parent e74d595 commit 927a09d

5 files changed

Lines changed: 204 additions & 142 deletions

File tree

‎README.en.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
<div align="center">
2+
3+
# Chinese Fortune · 中国传统命理
4+
5+
**A Claude Skill packing 20+ Chinese metaphysics methods (五术: 山·医·命·相·卜) into one portable skill.**
6+
7+
[![CI](https://github.com/ShousenZHANG/chinese-fortune/actions/workflows/ci.yml/badge.svg)](https://github.com/ShousenZHANG/chinese-fortune/actions/workflows/ci.yml)
8+
[![tests](https://img.shields.io/badge/tests-977%20passing-brightgreen)](tests)
9+
[![coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)](#quality-gates)
10+
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
11+
[![release](https://img.shields.io/github/v/release/ShousenZHANG/chinese-fortune)](https://github.com/ShousenZHANG/chinese-fortune/releases)
12+
13+
[简体中文](README.md) ｜ **English**
14+
15+
</div>
16+
17+
---
18+
19+
BaZi, Zi Wei Dou Shu, I-Ching, Liu Yao, Qi Men Dun Jia, Feng Shui, almanac, naming, Tarot, and more. Heavy calendrical math runs in deterministic Python scripts; Claude narrates from the reference docs. **Cultural and educational reference only — not medical, legal, or financial advice.**
20+
21+
## Table of Contents
22+
23+
- [Features](#features)
24+
- [Quick Start](#quick-start)
25+
- [Methods](#methods)
26+
- [How It Works](#how-it-works)
27+
- [Safety](#safety)
28+
- [Quality Gates](#quality-gates)
29+
- [Contributing](#contributing)
30+
- [License & Sources](#license--sources)
31+
32+
## Features
33+
34+
- **20+ methods, one skill** — divination, destiny, physiognomy, and practical arts in a single self-contained skill. No backend, no network.
35+
- **Deterministic computation** — 13 Python engines on `lunar_python` (a port of the [寿星天文历](https://github.com/6tail/lunar-python) algorithm, solar-term error < 1s) do the 排盘/起卦, instead of asking an LLM to do error-prone arithmetic.
36+
- **Calendrically rigorous** — true solar time, solar-term month boundaries, the 立春 year boundary, late-子时, and leap months are all correct, and cross-checked against the **independent `sxtwl` engine** over a 1920–2080 date grid.
37+
- **Progressive disclosure** — Claude loads the small router first, then only the reference/script for the method in play. Minimal context cost.
38+
- **Safety rails** — hard red lines (no death-date prediction, no medical/legal/financial calls, no curses) plus a crisis hand-off, built into the skill.
39+
- **Engineered** — 977 tests / 82% coverage / `ruff` + `mypy` + a 5-gate CI.
40+
41+
## Quick Start
42+
43+
Download `chinese-fortune-v*.zip` from [Releases](https://github.com/ShousenZHANG/chinese-fortune/releases) and import:
44+
45+
| Platform | How |
46+
|---|---|
47+
| **Claude Code** | Unzip into `~/.claude/skills/` → restart. The `chinese-fortune/` folder is the skill. |
48+
| **Claude.ai** | Settings → Capabilities → Skills → **Upload skill** → select the zip. |
49+
| **OpenAI / other** | Unzip anywhere; point your agent at `agents/openai.yaml` and call the `scripts/` as tools. |
50+
51+
```bash
52+
pip install "lunar_python>=1.4.4,<2.0" # all platforms: accurate 农历 / 八字 / 黄历
53+
```
54+
55+
Then just talk to Claude — the skill auto-triggers on Chinese or English fortune requests:
56+
57+
```text
58+
Born 1990-05-10, 2:30 PM, male, Beijing. Give me a full BaZi reading.
59+
Cast an I-Ching hexagram with coins on whether I should switch jobs.
60+
I want to move house in June 2026, I'm a Dragon — which days are auspicious?
61+
```
62+
63+
Scripts also run standalone (structured JSON on stdout):
64+
65+
```bash
66+
python scripts/bazi_calc.py --year 1990 --month 5 --day 10 --hour 14 --gender male
67+
python scripts/yijing_cast.py coins --question "should I take the offer?"
68+
python scripts/huangli_query.py --date 2026-06-15
69+
```
70+
71+
Run `python scripts/<name>.py --help` for options. Build the package from source: `python scripts/build_skill.py`.
72+
73+
## Methods
74+
75+
| Group | Methods | Has script |
76+
|---|---|---|
77+
| **命 Destiny** | BaZi, Zi Wei Dou Shu, 称骨, 河洛理数, 七政四余 | BaZi, Zi Wei |
78+
| **卜 Divination** | I-Ching, Liu Yao, Mei Hua, Qi Men, Da Liu Ren, Xiao Liu Ren, Tai Yi, oracle slips, Bei Jiao | I-Ching, Liu Yao, Mei Hua, Qi Men, Da/Xiao Liu Ren |
79+
| **相 Physiognomy** | Feng Shui (Eight Mansions / Xuan Kong), face, palm, glyphomancy | — (reference-guided) |
80+
| **术 Practical** | almanac date selection, naming, compatibility, dream, zodiac, astrology, Tarot | almanac, naming, compatibility/zodiac, Tarot |
81+
82+
Each method maps to a reference doc in `references/` and (where computation helps) a script in `scripts/`. The full routing table lives in [SKILL.md](SKILL.md).
83+
84+
## How It Works
85+
86+
```
87+
SKILL.md router — frontmatter trigger + method table
88+
references/ (23) the canon: theory + per-method interpretation guides
89+
scripts/ (13) deterministic engines (lunar_python + SystemRandom)
90+
assets/ (12) JSON lookup tables (干支, 64卦, 神煞, Tarot, strokes …)
91+
evals/ release harness + 12 machine-asserted scenarios
92+
tests/ pytest golden values + edge cases + independent-engine diff
93+
```
94+
95+
Calendrical correctness (true solar time, solar-term months, 立春 year boundary, late-子时, leap months) is delegated to `lunar_python`; the skill adds the 格局/用神/interpretation layer on top.
96+
97+
## Safety
98+
99+
Hard red lines (see [references/20-disclaimer.md](references/20-disclaimer.md)): no death-date prediction, no medical/legal/financial decisions, no curse/harm requests, no blaming third parties, no paid "remedies". Every reading is framed as a reflective pattern with a brief disclaimer, and acute-distress signals trigger a crisis-resource hand-off.
100+
101+
## Quality Gates
102+
103+
```bash
104+
python -X utf8 evals/run_checks.py # release harness (6 checks)
105+
python -m pytest tests/ # unit + integration + independent diff
106+
```
107+
108+
CI (Python 3.11 / 3.12) enforces five gates:
109+
110+
| Gate | What |
111+
|---|---|
112+
| `ruff` | linting, zero tolerance |
113+
| `mypy` | static type checking |
114+
| `pytest` | **977 tests** — golden values, 立春/late-子时/leap-month edges, 五鼠遁 invariant, differential vs the independent `sxtwl` engine |
115+
| coverage | subprocess-tracked **82%**, fails under 80% |
116+
| harness | SKILL.md validation + 12 machine-asserted scenarios + script JSON integrity |
117+
118+
## Contributing
119+
120+
PRs welcome — deeper Zi Wei / Xuan Kong logic, more `evals` scenarios, Traditional-Chinese translations. Run `evals/run_checks.py` and `pytest` before submitting. See [CONTRIBUTING.md](CONTRIBUTING.md).
121+
122+
## License & Sources
123+
124+
[MIT](LICENSE). Built on classical texts (《周易》《滴天髓》《三命通会》《渊海子平》《紫微斗数全书》《卜筮正宗》《梅花易数》 …) and [`6tail/lunar-python`](https://github.com/6tail/lunar-python). Cultural/educational reference only — readings are probabilistic patterns, not deterministic predictions.

‎README.md‎

Lines changed: 77 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,124 @@
1-
# Chinese Fortune · 中国传统命理 Claude Skill
1+
<div align="center">
2+
3+
# 中国传统命理 · Chinese Fortune
4+
5+
**一个 Claude Skill，把中国五术（山·医·命·相·卜）的 20+ 种命理方法装进一个可移植技能。**
26

37
[![CI](https://github.com/ShousenZHANG/chinese-fortune/actions/workflows/ci.yml/badge.svg)](https://github.com/ShousenZHANG/chinese-fortune/actions/workflows/ci.yml)
4-
&nbsp;![tests](https://img.shields.io/badge/tests-94%20passing-brightgreen)
5-
&nbsp;![license](https://img.shields.io/badge/license-MIT-blue)
8+
[![tests](https://img.shields.io/badge/tests-977%20passing-brightgreen)](tests)
9+
[![coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)](#质量保障)
10+
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
11+
[![release](https://img.shields.io/github/v/release/ShousenZHANG/chinese-fortune)](https://github.com/ShousenZHANG/chinese-fortune/releases)
612

7-
> 20+ traditional Chinese metaphysics methods in one Claude skill · MIT · [中文](README.zh.md)
13+
**简体中文** ｜ [English](README.en.md)
814

9-
A Claude Code / Agent SDK skill covering the Chinese metaphysical canon (五术：山医命相卜) — BaZi, Zi Wei Dou Shu, I-Ching, Liu Yao, Qi Men, Feng Shui, almanac, naming, Tarot, and more. Heavy calendrical math runs in deterministic Python scripts; Claude narrates the result from the reference docs.
15+
</div>
1016

11-
For **cultural exploration and self-reflection** — not medical, legal, or financial advice.
17+
---
1218

13-
## Install
19+
八字、紫微斗数、周易、六爻、奇门遁甲、风水、黄历、姓名学、塔罗……繁重的历法计算交给确定性 Python 脚本，Claude 依据参考文档解读。**仅供文化研习与自我反思，不构成医疗、法律、金融建议。**
1420

15-
Grab `chinese-fortune-v*.zip` from [Releases](../../releases) (or build it — see below), then pick your platform:
21+
## 目录
1622

17-
| Platform | How |
18-
|---|---|
19-
| **Claude Code** | Unzip into `~/.claude/skills/` → restart. The `chinese-fortune/` folder is the skill. |
20-
| **Claude.ai** | Settings → Capabilities → Skills → **Upload skill** → select the zip. |
21-
| **OpenAI / other** | Unzip anywhere; point your agent at `agents/openai.yaml` and call the `scripts/` as tools. |
23+
- [特性](#特性)
24+
- [快速开始](#快速开始)
25+
- [覆盖方法](#覆盖方法)
26+
- [工作原理](#工作原理)
27+
- [安全边界](#安全边界)
28+
- [质量保障](#质量保障)
29+
- [贡献](#贡献)
30+
- [许可与来源](#许可与来源)
2231

23-
```bash
24-
pip install "lunar_python>=1.4.4,<2.0" # all platforms: accurate 农历/八字/黄历
25-
```
32+
## 特性
33+
34+
- **20+ 种方法，一个技能** — 命卜相术全覆盖，单一自包含 skill，无需后端、无需联网。
35+
- **确定性计算** — 13 个 Python 引擎在 `lunar_python`（[寿星天文历](https://github.com/6tail/lunar-python) 算法移植，节气误差 < 1 秒）上排盘起卦，而非让大模型手算（易错）。
36+
- **历法严谨** — 真太阳时、节气定月、立春年界、夜子时、闰月等业余易错处全部正确，并经**独立引擎 sxtwl 跨库对照** 1920–2080 全网格验证。
37+
- **渐进式披露** — Claude 先加载小路由，再按需调用对应方法的文档与脚本，上下文最小化。
38+
- **安全护栏** — 硬红线（不预测死亡、不做医疗法律金融决断、不接诅咒）+ 危机转介，内建于技能。
39+
- **工程化** — 977 测试 / 82% 覆盖 / `ruff` + `mypy` + CI 五道质量门。
2640

27-
Build the package yourself from source:
41+
## 快速开始
42+
43+
从 [Releases](https://github.com/ShousenZHANG/chinese-fortune/releases) 下载 `chinese-fortune-v*.zip`，按平台导入：
44+
45+
| 平台 | 导入方式 |
46+
|---|---|
47+
| **Claude Code** | 解压到 `~/.claude/skills/` → 重启。压缩包内 `chinese-fortune/` 文件夹即技能。 |
48+
| **Claude.ai** | 设置 → Capabilities → Skills → **上传技能** → 选该 zip。 |
49+
| **OpenAI / 其他** | 解压到任意位置；agent 指向 `agents/openai.yaml`，把 `scripts/` 当工具调用。 |
2850

2951
```bash
30-
python scripts/build_skill.py # -> dist/chinese-fortune-v<version>.zip
52+
pip install "lunar_python>=1.4.4,<2.0" # 所有平台：精确农历 / 八字 / 黄历
3153
```
3254

33-
Then just talk to Claude — the skill auto-triggers on Chinese or English fortune requests:
55+
导入后直接对 Claude 说话即可，技能按中英文请求自动触发：
3456

3557
```text
3658
我 1990 年 5 月 10 日下午 2 点半出生，男，北京。详细批一下八字。
3759
帮我用铜钱起一卦，问要不要跳槽。
3860
2026 年 6 月想搬家，我属龙，哪几天合适？
3961
```
4062

41-
Scripts also run standalone (structured JSON on stdout):
63+
脚本也可独立运行（输出结构化 JSON）：
4264

4365
```bash
4466
python scripts/bazi_calc.py --year 1990 --month 5 --day 10 --hour 14 --gender male
45-
python scripts/yijing_cast.py coins --question "should I take the offer?"
67+
python scripts/yijing_cast.py coins --question "要不要接这个 offer？"
4668
python scripts/huangli_query.py --date 2026-06-15
4769
```
4870

49-
Run `python scripts/<name>.py --help` for options.
71+
`python scripts/<名>.py --help` 查看完整参数。从源码自行打包：`python scripts/build_skill.py`。
5072

51-
## Methods
73+
## 覆盖方法
5274

53-
| Group | Methods | Has script |
75+
| 分类 | 方法 | 配套脚本 |
5476
|---|---|---|
55-
| 命 Destiny | 八字 BaZi, 紫微斗数, 称骨, 河洛理数, 七政四余 | 八字, 紫微 |
56-
| 卜 Divination | 周易 I-Ching, 六爻, 梅花易数, 奇门遁甲, 大六壬, 小六壬, 太乙, 灵签, 杯筊 | I-Ching, 六爻, 梅花, 奇门, 大六壬, 小六壬 |
57-
| 相 Physiognomy | 风水 (八宅/玄空), 面相, 手相, 测字 | — (reference-guided) |
58-
| 术 Practical | 黄历择日, 姓名学, 合婚, 解梦, 生肖, 星座, 塔罗 | 黄历, 姓名, 合婚/生肖, 塔罗 |
77+
| **命** | 八字、紫微斗数、称骨、河洛理数、七政四余 | 八字、紫微 |
78+
| **卜** | 周易、六爻、梅花易数、奇门遁甲、大六壬、小六壬、太乙、灵签、杯筊 | 周易、六爻、梅花、奇门、大六壬、小六壬 |
79+
| **相** | 风水（八宅 / 玄空）、面相、手相、测字 | —（文档解读） |
80+
| **术** | 黄历择日、姓名学、合婚、解梦、生肖、星座、塔罗 | 黄历、姓名、合婚 / 生肖、塔罗 |
5981

60-
Each method maps to a reference doc in `references/` and (where computation helps) a script in `scripts/`. The full routing table lives in [SKILL.md](SKILL.md).
82+
每种方法对应 `references/` 中的参考文档，需要计算的另配 `scripts/` 脚本。完整路由表见 [SKILL.md](SKILL.md)。
6183

62-
## How it works
84+
## 工作原理
6385

6486
```
65-
SKILL.md router — frontmatter trigger + method table
66-
references/ (23) the canon: theory + per-method interpretation guides
67-
scripts/ (13) deterministic computation (lunar_python + SystemRandom)
68-
assets/ (12) JSON lookup tables (干支, 64卦, 神煞, 塔罗, 笔画 …)
69-
evals/ release harness + 12 scenario assertions
70-
tests/ pytest golden-value + edge-case suite
87+
SKILL.md 路由：frontmatter 触发词 + 方法表
88+
references/ (23) 命理正文：理论 + 各方法解读指南
89+
scripts/ (13) 确定性计算引擎（lunar_python + SystemRandom）
90+
assets/ (12) JSON 查表（干支、64卦、神煞、塔罗、笔画 …）
91+
evals/ 发布校验 + 12 场景机器断言
92+
tests/ pytest 黄金值 + 边界 + 独立引擎差分
7193
```
7294

73-
Progressive disclosure: Claude loads the small router first, then only the reference/script for the method in play. Calendrical correctness (真太阳时, 节气定月, 立春年界, 夜子时, 闰月) is delegated to `lunar_python`; the skill adds the 格局/用神/interpretation layer on top.
95+
历法正确性（真太阳时、节气定月、立春年界、夜子时、闰月）交给 `lunar_python`，技能在其上叠加格局 / 用神 / 解读层。
7496

75-
## Safety
97+
## 安全边界
7698

77-
Hard red lines (see [references/20-disclaimer.md](references/20-disclaimer.md)): no death-date prediction, no medical/legal/financial decisions, no curse/harm requests, no blaming third parties, no paid "remedies". Every reading is framed as a reflective pattern with a brief disclaimer, and acute-distress signals trigger a crisis-resource handoff.
99+
硬红线（见 [references/20-disclaimer.md](references/20-disclaimer.md)）：不预测死亡日期、不做医疗 / 法律 / 金融决断、不接诅咒加害、不归咎他人、不推销付费“化解”。每次解读都以“启发性倾向”呈现并附简短免责；遇急性危机信号转介求助资源。
78100

79-
## Validation
101+
## 质量保障
80102

81103
```bash
82-
python -X utf8 evals/run_checks.py # 6-check release harness
83-
python -m pytest tests/ # unit + integration suite
104+
python -X utf8 evals/run_checks.py # 发布校验（6 项）
105+
python -m pytest tests/ # 单元 + 集成 + 独立引擎差分
84106
```
85107

86-
`run_checks.py` verifies: SKILL.md frontmatter, every script emits valid JSON, reference coverage, the 12 eval scenarios' machine assertions, the pytest suite, and release cleanliness. It prints a PASS/FAIL summary and exits non-zero on any failure.
108+
CI（Python 3.11 / 3.12）强制执行五道门：
109+
110+
| 门 | 内容 |
111+
|---|---|
112+
| `ruff` | 代码规范，0 容忍 |
113+
| `mypy` | 静态类型检查 |
114+
| `pytest` | **977 测试** — 黄金值、立春 / 夜子时 / 闰月边界、五鼠遁不变量、对 sxtwl 独立引擎差分 |
115+
| coverage | 子进程追踪 **82%**，低于 80% 即失败 |
116+
| harness | SKILL.md 校验 + 12 场景机器断言 + 脚本 JSON 合法性 |
87117

88-
## Contributing
118+
## 贡献
89119

90-
PRs welcome — deeper 紫微/玄空飞星 logic, more `evals` scenarios, 繁體/English reference translations. Run `evals/run_checks.py` and `pytest` before submitting. See [CONTRIBUTING.md](CONTRIBUTING.md).
120+
欢迎 PR——更深的紫微 / 玄空飞星逻辑、更多 `evals` 场景、繁體翻译。提交前请跑 `evals/run_checks.py` 与 `pytest`，详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
91121

92-
## License & sources
122+
## 许可与来源
93123

94-
[MIT](LICENSE). Built on classical texts (《周易》《滴天髓》《三命通会》《渊海子平》《紫微斗数全书》《卜筮正宗》《梅花易数》 …) and [`6tail/lunar-python`](https://github.com/6tail/lunar-python). Cultural/educational reference only — readings are probabilistic patterns, not deterministic predictions.
124+
[MIT](LICENSE)。基于经典文献（《周易》《滴天髓》《三命通会》《渊海子平》《紫微斗数全书》《卜筮正宗》《梅花易数》…）与 [`6tail/lunar-python`](https://github.com/6tail/lunar-python)。仅供文化 / 教育参考——结果是概率性倾向，非确定性预言。

0 commit comments

Comments
 (0)