opencode-tianji

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

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

Related MCP server: 命盘 Mingpan

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

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(工具说明)

使用技能(推荐)

复制技能到项目并重启 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      # 跳过真实对话,仅确定性验证(加载/工具注册/命令)

环境变量:

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

发布

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