opencode-tianji

六爻占卜 opencode 插件(天机)。提供 13 个工具:起卦、排盘、断卦、查卦、梅花体用断卦、八字四柱、小六壬、农历黄历、大衍、易林、京氏、火珠林、查注。数据深度绑定包内 books/(书层)+ data/(统一 schema 数据),安装即用,无需额外配置。

独家卖点(2026-08 开源生态对比)

卖点	说明
8 部古籍全文 + 条目级行号溯源	六十四卦/爻辞/彖象/易林 4096 诗/占验卦例等每条数据可溯源到原文行号。开源生态无等价物(kanripo 无 schema、HF 语料无溯源)
381 则占验卦例库	增删卜易(卷一二三四)+ 卜筮正宗(十八问答)全量提取,含卦象/断语/应期原理/白话/来源,六爻领域最大结构化卦例库
六爻规则断卦引擎	用神/旬空/月破/六冲六合三合/旺相休囚/飞伏神,确定性算法,非 LLM 自由发挥
六爻解卦公开评测基准	benchmark/ 自带金标准(346 例)+ runner,排盘可判、断语可溯,填补生态空白(见下文)
白话铁律	每个卦学术语紧跟白话翻译,结尾必有纯白话【总结】段,输出即懂

架构:低耦合 · 模块化 · 可扩展

opencode-tianji/
├── plugins/          # 插件层:聚合器,合并全部术别工具,无业务逻辑
│   └── zhanbu.ts     #   聚合器(合并 modules/ 全部工具,13 个)
├── modules/          # 术别模块:每术一模块,自声明导出
│   ├── liuyao.ts     #   六爻(qigua/paipan/duangua/cha)
│   ├── meihua.ts     #   梅花易数
│   ├── dayan.ts      #   大衍筮法(蓍草四营十八变)
│   ├── yilin.ts      #   焦氏易林(4096 变诗占)
│   ├── jingshi.ts    #   京氏易传(八宫/飞伏)
│   ├── huozhulin.ts  #   火珠林(钱卜杂占)
│   ├── jingdian.ts   #   经传查注(朱熹注/十翼/彖象)
│   ├── bazi.ts       #   八字四柱
│   ├── liuren.ts     #   小六壬
│   └── almanac.ts    #   黄历
├── lib/              # hex.ts(共享计算核心)db.ts(数据加载)ganzhi.ts(干支)engine.ts(引擎入口)
├── books/            # 书层:8 部典籍元数据(篇章/行号/提取状态)+ index.json
├── data/             # 数据层:统一 schema(每条目带 来源 溯源)
│   └── schema/       #   JSON Schema 定义(书/数据文件/条目溯源)
├── templates/        # 技能与命令模板
├── mcp/              # stdio MCP 服务器(复用全部 13 工具)
├── benchmark/        # 六爻解卦评测基准(金标准 + runner)
└── types/            # TypeScript 类型声明

加新占卜术 = 新建 modules/X.ts(导出 元信息/工具/数据)+ 聚合器数组加一行,互不影响。数据层每条记录可溯源到典籍原文行号(来源 字段)。八部典籍对应算法全部独立成模块,单向依赖 lib → 不跨术耦合。

安装

已发布到 npm:opencode-tianji。在项目 opencode.json 中加一行:

{
  "plugin": ["opencode-tianji"]
}

重启 opencode 即可。安装后 13 个工具自动可用:qigua、paipan、duangua、cha、meihua、bazi、liuren、almanac、dayan、yilin、jingshi、huozhulin、chazhu。

MCP 客户端(Claude Desktop / Cursor / Codex 等)安装:

claude mcp add tianji -- bun run node_modules/opencode-tianji/mcp/index.ts

历法精度(0.4.0 起)

• 节气:采用通用天文库 astronomy-engine(MIT)的太阳黄经天文算法,节气/立春精确到秒级(实测与权威天文年历误差 ±30 秒内),不再用近似固定节界。
• 晚子时:默认 23 点换日(晚子时归次日,对齐生态主流);工具可传 晚子时:"换日"|"不换日" 切换。
• 真太阳时:默认按北京时间(东八区);工具可传 经度(如乌鲁木齐 87)按地方真太阳时定生辰/起卦时辰,内置 Meeus 均时差算法。
• 每个工具输出末尾附 [口径] 行披露历法口径。

可审计(0.4.0 起)

• qigua 铜钱起卦支持 seed 参数:同 seed 结果可复现,输出含 [seed=0x…];不传则自动生成并展示,便于事后核对。
• qigua/paipan 支持 format="json":输出结构化审计 JSON(含卦象/动爻/旬空/月破/爻信息/依据/口径),可直接机器核对(0.5.0)。

stdio MCP(0.5.0 起)

复用全部 13 个工具的 stdio MCP 通道,可接入 Claude Desktop / Cursor / Codex 等任意 MCP 客户端:

bun run node_modules/opencode-tianji/mcp/index.ts

客户端 mcpServers 配置:

{ "tianji": { "command": "bun", "args": ["run", "node_modules/opencode-tianji/mcp/index.ts"] } }

MCP 目录收录

已收录于 Glama MCP 目录(自动安全/质量检查通过后展示)。仓库含 Dockerfile(Glama 沙箱构建用,本地验证:镜像构建 + initialize/tools-list 握手通过,13 工具齐全)与 glama.json(展示元数据)。

引擎独立入口(0.5.0 起)

纯计算引擎(hex + ganzhi,仅依赖 astronomy-engine)可从子路径直接调用,不依赖 opencode 运行时:

import { buildPan, buildPanByGanzhi } from "opencode-tianji/engine";

完整 TypeScript 类型声明随包发布(types/),engine 与主入口均有 types 条件映射。

Tools(工具说明)

工具	说明	关键参数
qigua 起卦	梅花易数时间起卦 / 三枚铜钱六掷(seed 可复现) / 报数起卦 / 字占起卦 / 手动指定卦名,输出本卦、变卦、卦辞、世应、起卦干支	method、datetime、卦名、动爻、数、字、seed、晚子时、经度
paipan 排盘	六爻排盘:六神/六亲/纳甲/五行、世应动空破、卦身、旬空、月破、六冲六合三合、旺相休囚、飞伏神	卦名、动爻、datetime、占事、晚子时、经度
duangua 断卦	按占事取用神,结合旺衰动空破与世应关系给出规则性吉凶倾向,并附相似卦例佐证(381 例卦例库)	卦名、占事、动爻、datetime、晚子时、经度
cha 查卦	卦辞、爻辞(动爻高亮)、乾坤用九用六、彖传/大象、变卦卦辞、焦氏易林变诗、朱熹卦爻注、序卦/杂卦/文言、上下卦八卦象意	卦名、动爻
meihua 梅花断卦	梅花易数体用生克:分体卦用卦、求变卦互卦,按五行生克断吉凶、看体卦卦气旺衰,并按十八类占(天时/人事/家宅/婚姻/求财/疾病…)出白话断语	卦名、动爻、占事、datetime
bazi 八字	八字四柱排盘:年/月/日/时干支(精确节气),十神、地支藏干、纳音、五行统计、大运流年	datetime、性别、晚子时、经度
liuren 小六壬	小六壬占课:月/日/时起课(大安/留连/速喜/赤口/小吉/空亡),输出落宫、吉凶与断辞	datetime、month、day
almanac 黄历	农历/干支/节气/宜忌/吉神方位/冲煞/旬空(基于 lunar-javascript 农历历法标准)	datetime
dayan 大衍	大衍筮法(蓍草四营十八变):49 策分二挂一揲四归奇,三变成爻、十八变成卦,seed 可复现	seed、占事
yilin 易林占	焦氏易林占:本卦+之卦取 4096 首变诗断吉凶,之卦可指定/动爻推/随机(seed 复现)	本卦、之卦、动爻、随机、seed
jingshi 京氏占	京氏易传占:八宫/宫五行/世应/纳甲六亲/飞伏神,据占事取用神看显伏	卦名、占事
huozhulin 火珠林	火珠林钱卜断占:按占事门类(求财/婚姻/疾病/出行/失物/射覆…)匹配《火珠林》口占断辞	占事、卦名
chazhu 查注	经传查注:查某卦朱熹《周易本义》卦爻注/十翼(序卦/杂卦/文言)/彖传大象,附白话导读	卦名、范围、动爻

使用技能(推荐)

复制技能到项目并重启 opencode:

for s in zhanbu meihua bazi liuren; do
  mkdir -p .opencode/skills/$s
  cp -r node_modules/opencode-tianji/templates/skills/$s/* .opencode/skills/$s/
done

zhanbu 技能定义"先问清楚再算"的完整六爻占卜流程:先收集【占卜事项、求测人性别、地理位置、是否本人、起卦时间】,再起卦、排盘、断卦,并要求每个卦学术语后附白话翻译。meihua/bazi/liuren 为各术轻量技能(最小信息先问后算)。

使用命令

mkdir -p .opencode/command
cp node_modules/opencode-tianji/templates/command/*.md .opencode/command/

可用命令:/zhanbu(六爻完整流程)、/paipan(快速排盘)、/meihua、/bazi、/liuren、/almanac、/cha(查卦)。如输入 /zhanbu 占卜事项 触发完整流程,/bazi 1990-05-06 08:00 男 直接排盘。

示例用法

• 让模型"起一卦问求财" → 模型会先问必问信息,再依次调 qigua → paipan → duangua + cha。
• 手动指定:qigua method=manual,卦名=乾,动爻=[1,3]。
• 起卦时间:qigua method=time,datetime=2024-02-10 12:00。
• 古法占:dayan(大衍筮法)、yilin 本卦=乾 之卦=坤(易林变诗)、jingshi 卦名=乾(京氏飞伏)。
• 断卦佐证:duangua 会附「相似卦例」段(381 例卦例库);chazhu 卦名=乾 查朱熹注/十翼。

六爻解卦评测基准(生态空白)

benchmark/ 提供一个排盘可判、断语可溯的六爻解卦评测基准——这是开源生态当前空白(现有基准如 MingLi-Bench 只覆盖八字/紫微选择题):

bun run benchmark/gold.ts   # 从 data/guaili.json 生成金标准(346 例)
bun run benchmark/run.ts    # 引擎排盘 + 用神命中统计 → benchmark/report.md

• 排盘可判:每条例以「卦名 + 月支 + 日干支」重建六爻盘,校验旬空/月破/六亲/世应(引擎零失败)。
• 断语可溯:按占事类别推断用神,校验用神六亲在卦或伏神可引拔,输出各类别命中率。
• 与 MingLi-Bench 的差异:后者测"排盘结果选择",本基准测规则断卦引擎在真实古籍卦例上的表现。

数据来源与版权

数据整理自公版古籍(周易·经传、京氏易传、火珠林、增删卜易、梅花易数、卜筮正宗、焦氏易林、周易本义),全部收录于 books/(书层:篇章/行号/提取状态)与 data/(统一 schema 数据,每条目带 来源 溯源到原文行号)。含:六十四卦排盘、彖传/大象、64 卦飞伏、十二长生、星煞、进神退神、梅花起卦法与三要十应、焦氏易林 4096 诗、占验卦例、命理与小六壬通行资料。古籍内容属公有领域,整理与结构化工作供学习研究使用,不构成任何现实决策依据。

开发

bun install
bun run test    # 全量:zhanbu/meihua/bazi/liuren 工具 + lib(数据/schema/干支)

E2E 真实 opencode 实例测试

用途:验证插件被真实 opencode 实例加载、13 个工具真实注册、真实 LLM 对话中模型能调用工具、/zhanbu 命令可用——补充单元测试未覆盖的"真实加载"环节。

前置:

• opencode ≥ 1.18 在 PATH 中(或设置 TIANJI_E2E_OPENCODE_BIN 指定路径);
• deepseek 配置自动读取全局 ~/.config/opencode/opencode.json,或用 TIANJI_E2E_PROVIDER_JSON 提供。

命令:

bun run test:e2e               # 完整:含真实 LLM 对话(消耗少量 deepseek API 费用)
bun run test:e2e:skip-llm      # 跳过真实对话,仅确定性验证(加载/工具注册/命令)

环境变量:

变量	说明
TIANJI_E2E_OPENCODE_BIN	opencode 可执行文件路径(默认自动探测 PATH)
TIANJI_E2E_PROVIDER_JSON	覆盖 provider 配置 JSON(CI/他机使用,不落盘 apiKey)
TIANJI_E2E_SKIP_LLM	设 1 跳过真实 LLM 对话
TIANJI_E2E_MODEL	指定对话模型(默认 deepseek 配置中的模型)
TIANJI_E2E_NO_COMMAND	设 1 强制命令验证失败(测试失败分支)

注意:真实对话消耗少量 deepseek API 费用;测试全程 XDG 隔离(临时 HOME/配置目录),不干扰日常配置;失败时可加 --keep 保留临时目录排查。

发布

bun run test   # 全量测试通过后再发布
npm publish    # 发布到 npm(需 NPM_TOKEN 或 npm login)