agentleFS
qilaidevqilaidev/metaphysics-engine/.claude/skills/bazi-cli/SKILL.md

bazi-cli

Skill1 starsChanged 3 days agoMITView on GitHub

metaphysics-engine 算法能力层的操作入口。当需要调用八字、紫微斗数、六爻纳甲、大六壬、奇门遁甲、八宅风水、择吉黄历、姓名五格、合盘、塔罗、周易起卦、星座这些命理算法能力,或者准备环境、起停引擎、跑测试、排查引擎起不来与 /health 503 时使用。也用于确认各术数选的是哪一派口径(藏干权重、闰月归属、中气换将、拆补定局、转盘排星)。所有操作都通过仓库根的 ./bazi CLI 完成,不要自己拼 curl,也不要绕过 CLI 手动起进程。

  • Reads credentials
  • In this repositoryOne other file it gives its agents.

The file

Files
SKILL.md

metaphysics-engine 操作手册

这个项目是算法能力层,不是网页应用。它的形态是:引擎作为常驻进程跑着,对外暴露 HTTP 接口;./bazi 是引擎的薄客户端,把能力包成命令给 Agent 调用。

命令分三类,bazi help --json 里一眼能分出来(前两类由每条命令声明的 kind 区分):

类别命令是什么
能力calc / cast这个项目对外输出的算法能力
运维setup doctor env stack test维护这个仓库本身
接入schema / mcp把上面那些能力交给上层 Agent

能做什么以 bazi help --json 为准,这里不重复命令清单——重复的清单一定会腐化。 这份文档只讲 --help 讲不了的:算法侧的语义边界、顺序、坑。

带 --json 跑。stdout 保证只有一个 JSON 文档,进度和子进程噪音全在 stderr。

语言约定:能力层一律中文

CLI 的文本输出、引擎返回的断语(如流日的 advice)一律中文。 --json 里的枚举键保持英文(Wood / Controls / zisun)—— 那是机器契约, 改了会破坏调用方;需要中文时取同一对象上的 cn 字段,各术数都备了。

于是同一份数据有两副面孔:calc bazi 打出「五行: 木 1 火 2」,--json 里仍是 {"Wood": 1, "Fire": 2}。拿 --json 做断言,拿文本给人看。

例外只有两处,都是刻意的:

  • README.en.md 面向英文读者,通篇英文。
  • 西方星座的描述性内容(keywords / strengths 这类形容词)保留英文原文 —— 那是内容不是界面。星座名、守护星、宫性、象征这些界面元素已译出。

退出码就是你的下一步

不要去读人类可读的错误文本猜意图,看退出码:

码含义你该做什么
0成功继续
1命令跑通了但结果失败(测试挂了、引擎内部错)去看结果本身,不是修环境
2用法错读 --help,别瞎试参数
3环境未就绪照 next 字段修,修完原样重试
4引擎拒绝了这个请求改请求内容,不是改环境
5瞬时失败原样重试
7命中安全边界停下来问人,不要自己绕过

失败的 JSON 里 next 一定是一条可以直接复制执行的命令。优先照它做。

调用能力命令时,HTTP 语义已经替你翻译成退出码了,不需要自己判断状态码:

引擎那边发生了什么你拿到意味着
连不上3引擎没起,bazi stack up
5033引擎在跑但没就绪,看 bazi stack status
400 / 4224参数没过服务端校验,改参数
4295限流或 AI 并发闸,等几秒原样重试,别动参数
5001请求没问题,引擎内部炸了,看 stack logs
4041code: endpoint_missing,不是你参数写错了

不存在的日期不会穿透成 500:2 月 30 日这类被 CLI 挡下(退 2),1582-10-05~14 儒略历缺口 由引擎拒绝(退 4)。看到这两个码就是日期本身的问题,不是引擎炸了。

最后一条特别容易误判:404 说明 CLI 和引擎版本对不上(或该能力已下线), 再怎么改参数都不会好。看到 endpoint_missing 就去重启/升级引擎,不要在参数上打转。


算法语义:这一节的坑,错了不会报错

下面每一条都不会让命令失败。命令照样退 0,照样返回一张结构完整的盘——只是那张盘 不是你以为的那张。这是这份文档存在的主要理由。

不给出生地时,分钟不改时辰;但交节当日分钟决定年柱月柱

不给出生地时排盘取的就是钟表时刻,时柱按整个时辰定,分钟不参与定时柱。实测:

1990-05-20 14:00 -> 庚午 辛巳 乙酉 癸未
1990-05-20 14:30 -> 庚午 辛巳 乙酉 癸未
1990-05-20 14:59 -> 庚午 辛巳 乙酉 癸未

但年柱月柱按交节时刻换,精确到分,交节当天分钟直接决定落在哪一边:

2024-02-04 16:27 -> 癸卯 乙丑 ...   ← 立春 16:27:07 尚未到(输入分钟的起点比交节秒早)
2024-02-04 16:28 -> 甲辰 丙寅 ...

所以交节日务必把分钟给全,不要凑整。没有地点就没有真太阳时校正;一旦给了 --location, 分钟还会通过真太阳时反过来影响时柱,见下节。奇门定局、六壬换将、八宅定年判交节也是同一条线 (jieqi.service),交节那一分钟与八字同边。

时间体系以中国为主

默认输入是中国民用墙钟(北京时间)。不给 --timezone 时,年月日时数字直接按 东八区语义进节气表 —— 与国内主流排盘软件一致。

场景行为
不给地点、不给时区按输入数字当中国墙钟排四柱
中国地点(北京/乌鲁木齐/…)只给 --location默认 Asia/Shanghai,真太阳时按经度相对 120°E 回拨
海外地点只给 --location不擅自校正(no-timezone);必须显式 --timezone
显式海外时区(如 America/New_York)年月柱换算到东八区再比节气;日时柱仍按当地时辰

海外出生:一张盘吃两个时刻

年月柱与日时柱的判据不是一回事,海外出生必须分开看:

  • 年柱月柱看节气。节气是绝对时刻,而引擎的节气表是东八区语义,所以先把出生时刻 换算成北京墙钟再比 —— 否则交节当天会错年、错月。换算结果在 chartTime.termReference。
  • 日柱时柱看当地时辰。时辰本就是当地太阳的位置,纽约中午必须是午时。用的就是 chartTime.used(含真太阳时校正)。

所以纽约 2024-02-04 10:00 EST 的盘是:年柱按北京 23:00(已过立春)取甲辰, 日时柱按当地 2/4 巳时。used 与 termReference 差整整一个时区是正常的, 两个字段都回显就是为了让这件事可核对。国内出生两者相同。

真太阳时会改写时柱

中国地点给了 --location(时区可省略)或显式给了时区之后,响应里会出现:

"trueSolarTime": { "applied": true, "correctionMinutes": -14.37, ... }

applied: true 意味着这张盘用的就是校正后的时刻。实际排盘所用的时刻在 chartTime.used,原始钟表时间保留在 chartTime.trueSolarTime.clockTime, 两者可以直接对照。中国地点自动补时区时会有 timezoneDefaulted: "Asia/Shanghai"。

校正量不小:北京(116.4°E)相对东八区标准经线约 −14 分钟,叠加均时差可到 ±30 分钟; 新疆一带钟表仍是北京时间,回拨能超过两小时。一个 15:05 出生在北京的人,真太阳时是 14:51, 跨过申时/未时边界,时柱与钟表时间那张盘不同 —— 这正是应有的行为。

要按钟表时间排盘(比如复现历史结果),传 trueSolarTime: false 显式关掉。

时区偏移取的是出生当时的实际偏移,不是今天的。1986–1991 年夏季中国实行夏令时, IANA 对那段时间的 Asia/Shanghai 给 UTC+9:引擎先把夏令时墙钟减一小时归一到北京标准时 (chartTime.dstNormalized 回显归一记录,trueSolarTime.dstCorrection 为 −60), 再按 120°E 做真太阳时并比节气。于是 1990 年 5 月同一个北京出生时刻的总校正量 (correctionMinutes)比非夏令时年份多整整一小时,这是对的,不要按今天的 UTC+8 去核对; 不给地点只给 Asia/Shanghai 的盘同样会被归一(时柱与年月柱按标准时排)。

地名表只有 88 个城市,认不出就跳过校正(不报错)

--location 走的是硬编码表(solarTime.service.js 的 KNOWN_LOCATIONS), 88 条,每条带中文名与常见别名(含繁体与行政区后缀)。归一化保留 CJK / 假名 / 谚文, 所以中文、日文、韩文地名都能命中——这一点在 2026-07-29 之前是反的:归一化把非 ASCII 字符全替换成空格,「北京」归一化成空串,中文地名 100% 认不出,真太阳时被静默跳过。

表里没有的地名仍然不报错,只是不做校正——比如 --location Timbuktu, trueSolarTime 是 null,其余一切正常。

chartTime.locationResolution.status 报的是校正的最终下场,不是「地名查得到吗」, 五个取值里只有第一个意味着这张盘用了校正后的时刻:

status含义谁该动手
applied已校正,chartTime.used 是校正后的时刻—
unresolved填了出生地但认不出,本次按钟表时间排盘调用方:换写法或传坐标
no-timezone地名认得,但没时区偏移,标准经线算不出调用方:补 timezone
absent没填 birthLocation—
disabled显式传了 trueSolarTime: false—

unresolved 与 no-timezone 同时在服务端记一条 warn(前者可能意味着城市表该补, 后者是调用方一直漏参数)。hint 字段直接给出下一步,不用去猜。

判断校正是否生效的判据仍是 trueSolarTime(null 就是没生效),这个新字段是拿来 排查「为什么没生效」的,不改变既有契约。

绕开这张表的方法是直接传坐标,这条路径永远可靠:

./bazi calc bazi --birth 1990-05-20T14:30 --gender male \
  --location "30.27,120.15" --timezone Asia/Shanghai --json

匹配带子串兜底,所以 "West London" 能命中 london。兜底有长度门槛(中文键 >= 2 字、 拉丁键 >= 4 字才下场扫描),否则 la(Los Angeles) 会在 Atlantis 里命中、京 会在 「东京」「京都」里命中——撞上不报错,只是拿错误的经度排出一张看起来正常的盘。 扫描顺序按键长降序,最具体的匹配优先,不再依赖表的书写顺序。长地址拿不准就用坐标。

节气交接当天,小时直接决定年柱和月柱

年柱按立春换,不按元旦;月柱按节气换,不按农历月。而且精确到时刻。 2024 年立春在 2/4 16:27,实测:

2024-02-04 10:00 -> 癸卯 乙丑 ...   ← 还是上一年、上一月
2024-02-04 17:00 -> 甲辰 丙寅 ...   ← 年、月柱同时翻篇

同一天,差 7 小时,年月柱全变。 所以节气交接日附近,--birth 的小时位 绝不能凑整或猜。同理:

2024-01-15 -> 癸卯年     2024-03-15 -> 甲辰年

一月出生的人年柱属于上一个干支年,这不是 bug。

晚子时:23 点这一小时,日柱和时柱分属不同的日

lunar-javascript 采用「晚子时不换日」:

5/20 22:00 -> 日柱 乙酉  时柱 丁亥
5/20 23:00 -> 日柱 乙酉  时柱 戊子   ← 日柱还是 20 日,时柱已经是子时
5/21 00:00 -> 日柱 丙戌  时柱 戊子   ← 日柱翻篇

注意 5/20 23:00 那行:日柱是乙酉(乙日),但时柱是戊子——戊子是丙日的子时。 也就是说这一小时里,日柱按当日算,时柱按次日的日干推。这是晚子时流派的标准处理, 不是错误。

但要知道:另一个流派(子正换日)会给出完全不同的日柱,而这里没有开关可切。 用户如果按早子时流派预期结果,你们对不上,原因在这里。

闰月:本项目按「归本月」算

lunar-javascript 用负数月份表示闰月(闰二月 = -2):

2023-03-05 -> getMonth() =  2   (二月)
2023-03-25 -> getMonth() = -2   (闰二月)
2023-04-25 -> getMonth() =  3   (三月)

选定流派:闰月归本月——闰二月与二月落同一个月支。所以 2023 年闰二月初四的盘, 和二月初四的盘,命宫身宫完全一致。用户如果按「闰月后半月归下月」那一派预期结果, 对不上的原因在这里。

响应里 lunar.month 给的是正数(闰二月是 2 不是 -2),闰月与否看 lunar.isLeap。 两个字段要合起来读才能还原出「闰二月」。

八字完全不受影响——它走节气,不走农历月。

这里以前有两个静默 bug(负数月份直接进索引导致月支错位、isLeap 恒为 false), 已修复,backend/test/ziwei_leap_month.test.js 守着。要换流派就改 ziwei.service.js 里 Math.abs(rawLunarMonth) 那行,并同步改那个测试的断言。

缓存键必须覆盖全部排盘输入

buildBaziCacheKey 以 年-月-日-时-性别 为基础,另把会影响排盘的因子以后缀形式 追加:出生地、分钟、时区、以及 trueSolarTime: false 开关。真太阳时接进排盘之后 这些因子就是排盘输入的一部分,不进键会让同一生辰不同出生地互相命中对方的盘。

无地点无时区的请求键形如 1990-5-12-10-male,与历史格式一致;带地点的会变成 1990-5-12-10-male|loc:beijing|tzn:Asia/Shanghai。

以后再往排盘输入里加任何因子(流派开关、节气口径等),必须同步加进这个键。

x-bazi-cache 响应头会告诉你这次是 hit 还是 miss,排查结果不符预期时先看它。

可复现性:不要按 calc / cast 分组去猜,逐条命令有声明

calc 与 cast 的分家只是历史分组,可复现性是逐条命令声明的, 在 help --json 的 reproducibility 和 schema --json 的 catalog 里都能读到:

值含义能不能拿来做断言/回归基准
deterministic给定输入必然同样输出能
conditional看怎么调用,requires 列出给全就确定的参数给全了才能
not-reproducible同样输入不保证同样输出不能

按分组猜会在两个方向上出错,这两条都是实打实的:

  • cast iching --numbers 7,8,9 是确定性的(conditional,requires numbers), 它是「要一个可复现的卦」唯一的出路。只有 --method time 才不可复现。
  • calc daily 是恒不可复现的(not-reproducible):它压根没有日期参数, 日柱永远取引擎当日,隔天调用必然不同。要可复现的当日信息用 calc almanac --date。

conditional 的其余几条是起课类(liuren / qimen / liuyao / almanac): 不给 --date(六壬奇门还要 --hour)就取引擎当日当时。文本输出末尾会带一句 「未指定 --date,用的是引擎当日 X,此结果不可复现」,但 --json 里没有这句 —— 要可复现就照 requires 把参数给全。calc zodiac 也是 conditional, 但条件不是补参数:带 --horoscope 时响应含引擎当下算出的日期区间,跨天就变。

六爻是装卦不是起卦:--lines 由你给(六位 0/1,自初爻起),引擎只负责装。 所以只要 --lines 和 --date 都给了,它就是完全确定性的(--hour 不参与装卦)。

这些声明不是文档口径,是会被验证的:bazi test engine 拿真实引擎把每条 声明可复现的命令连调两次比对输出,对不上就是硬失败。

交节精确到分,所以「只给日期」在交节当天是存疑的

节气交接有具体时刻(2024 立春在 2/4 16:27),不是一整天。凡是按节气分界的算法 ——八字年月柱、六壬月将、奇门定局、八宅定年——交节当天差几小时就换一边。

八宅的响应因此带一个 lifeTrigram.precision,告诉你这个结论有多可信:

值含义交节当天可信吗
minute给全了年月日时可信
day给了年月日、没给时刻存疑 —— 只能按零点算
year只给了年份完全没过立春这道关

看到 day 或 year 且日期恰在 lichunAt 当天,别把结果当确定值, 先去把出生时刻问清楚。八字那边同理,见上面「节气交接当天」一节。

择吉分三层,混着读会答错问题

calc almanac 的输出是三层,各自回答不同的问题:

层字段回答的是
论日yi / ji / zhiXing / xiu / tianShen / chongSha这一天宜什么忌什么、冲谁
论时hours这一天几点可以动手
论方directions / dayPositions哪个方向不能动

「今天适合搬家吗」看第一层;「今天几点搬」只能看第二层,拿第一层去答是答不了的; 「哪个方向不能动土」在第三层,taiSui / suiPo / sanSha / wuHuang / erHei。

hours 是十三条不是十二条。 子时跨两个公历日,故一日之内有早子(00:00–00:59) 与晚子(23:00–23:59)两段,且两段的时干不同——晚子的时干由次日日干起五鼠遁。 按十二条去取下标会把晚子整段丢掉,而丢掉不会报错。

directions 的年界是立春,与年柱同界:正月初一到立春之间,方位煞仍属上一年。 入中紫白星是按 7 − ((年 − 1984) mod 9) 算出来的,不是查表——手抄的流年紫白表 极易整体错位一年(对标过的一个公开项目就是这么错的),而错了同样不报错。

八宅不给 --sitting 只有一半

八宅论的是命卦配宅卦。--birth 给的是人那一半(命卦), --sitting 给的是房子那一半(宅卦,由坐山定)。只给出生信息时, house 是 null、houseResolution 是 absent——此时「这房子对我合不合」答不了。

坐山四种写法都收:卦名(坎)、二十四山(子 / 壬 / 乾)、方位(正北)、 子山午向。认不出不报错,houseResolution 标 unresolved,命卦那一半照常给出 ——与出生地认不出时 locationResolution 的处理方式一致。

match.matched 只是粗判(东西四是否同组)。细判看 match.sittingStarForLife: 宅之坐山方在本人命卦游年里值的是生气还是绝命,那才是这栋房子对这个人的实际吉凶方位。

合盘要各自给出生地,否则与 calc bazi 不是同一张盘

calc synastry 的地点时区是分两边给的:--a-location / --a-timezone / --b-location / --b-timezone。不给就按钟表时间排盘。

这一条要紧是因为:同一个人,calc bazi --location 乌鲁木齐 排出来的时柱, 与合盘里不给地点排出来的时柱可能不是同一柱(西部真太阳时能回拨两小时以上)。 合婚最吃重的日支也在这个差的射程内。两处口径要一致,就两处都给地点。

各术数的流派口径:选的是哪一派,换派改哪里

命理算法几乎每一步都有分歧,选错不会报错,只会给出另一门派的盘。

能力选定口径另一派会怎样
八字·藏干本气 0.6 / 中气 0.3 / 余气 0.1有 100:70:30 等归一化法,旺衰占比会变
八字·月令月支力量 ×2不加倍则身强身弱的判定线整体挪动
八字·用神扶抑法与调候法并列给出,两者都在 analysis 里病药、通关法仍未实现;中和局扶抑给空数组,此时看 tiaohou
八字·调候《穷通宝鉴》通行速查表(constants/geju.js),首位主用、其余辅用各刊本互有出入,与所宗版本不符时改那一张表即可,取用规则不动
八字·取格从月令,《子平真诠》一派:本气透干则以透干论,不透取中余气之透者,皆不透以本气论另有以强弱定格、以格局用神反推等派;facts 一节是无分歧的结构事实,可照它自行重推
八字·禄刃建禄羊刃按禄刃表定(戊禄巳刃午、己禄午,土寄火乡);阴干无刃,月令本气劫财为月劫;四季月戊己不作建禄,比劫透干或皆不透归月劫、财官透干以透干论按「月令本气同五行」推会让戊日巳月报印格、戊日辰月报建禄,与禄神表自相矛盾
八字·透干「透」只算年干、月干、时干把日干也算进去会让日主成为自己的格
八字·晚子不换日柱(sect=2 钉死)子正换日派 23 点日柱已是次日
八字·时区以中国为主:默认北京时间墙钟;中国地点缺时区默认 Asia/Shanghai;海外须显式 timezone把海外墙钟当北京钟会在交节日错年/月
八字·海外年月柱换东八区比节气,日时柱按当地时辰日时柱也跟着换会把纽约中午排成北京次日子丑时
紫微·年界农历年(正月初一换年干支)立春派在立春~春节窗口年干支不同,整盘皆偏
紫微·闰月归本月(闰二月=二月)「闰月后半归下月」派的命宫身宫会不同
紫微·庙旺不实现(属断语层)需要就自行按所宗流派叠加
紫微·解神只取年解(戌宫起子年逆行)另有月系解神,落宫不同;要就自行叠加
紫微·顺逆长生十二神、博士十二神按年干阴阳分男女顺逆;岁前、将前一律顺行四组混用同一套顺逆会让后两组整体错位
紫微·宫序十二宫自命宫逆布:兄弟在命宫前一位、父母在后一位顺布则除命宫迁移外十宫两两互换,星位仍对、宫名全错,且与大限顺逆冲突
紫微·四化戊科右弼、庚取「阳武阴同」、壬梁紫左武庚科天府 / 壬科天府是另一派;壬化忌恒为武曲,取破军是错不是派
六壬·月将中气换将用节换将会差将近半个月,整盘皆错
六壬·四课第一课以日干为下判克,寄宫只用于取上神(乙日干上神未:乙木克未土为下贼上)按寄宫地支五行判克,乙丁戊辛癸五干(一半日子)的一课克应整层错,三传随之错
六壬·伏吟有克依贼克(乙癸日一课有克)、无克刚日自任柔日自信;自刑时颠倒日辰改取另一上神把伏吟当作「永无克」会让乙癸日伏吟全误报自任/自信
六壬·涉害顺行归家、路逢多克为用;深浅相等看候选所临地盘位是孟是仲(见机/察微),皆不能决报复等课另有「直取孟仲季」派,不归家直接数孟上贼克;按候选支自身判孟仲,察微复等永远走不到
六壬·昴星阳仰阴俯(《六壬大全》:无遥无克昴星穷,阳仰阴俯酉位中)两向取反会得到完全不同的初传
六壬·贵人「庚」归甲戊庚一组(昼丑夜未),与紫微魁钺同派「庚辛逢虎马」派把庚归午寅,昼夜贵人两支全变
六壬·子时23 点起日柱入次日(子初换日)与八字晚子不换日不同,起课按占时日
奇门·定局拆补法:往前取最近的甲己符头,按符头地支定上中下元,不置闰一个节气内三元出现「残中—下—上—补中」是拆补法的正常形态,不是错;置闰法另配闰局
奇门·天盘转盘法飞盘法的星门落宫完全不同
奇门·值使值使门自值符宫按九宫数序阳顺阴逆飞到时辰旬序,中五寄坤二(甲子时坎一,乙丑时坤二…)在八宫环上转会让一旬十个时辰里八个时辰的值使宫错
奇门·子时23 点与次日 0 点同盘(子初换日)按公历日劈开会得到两套完全不同的盘
奇门·八神第五第六位取白虎、玄武(现代通行简化派)古法阳遁用勾陈、朱雀,阴遁才用白虎、玄武;顺逆布的算法两派相同
奇门·入墓五行墓库:木墓坤二、火土墓乾六、金墓艮八、水墓巽四「阴干各自逆行取墓」派的落宫不同(如乙墓戌)
奇门·门迫门克宫为迫(开门属金落震三巽四木);反向的宫克门为门制(isGateZhi)曾把方向取反、还拿「开门落离九宫」当例证 —— 那是宫克门,是门制不是门迫
奇门·格局格局命名不实现(属断语层);格局所依据的关系量一律给出青龙返首、飞鸟跌穴之类各家取名与条件出入极大
八宅·定年立春为界用元旦为界,正月初生人的命卦会差一位
八宅·宅卦由坐山定,坐山归到八卦(各 45°)兼向(骑两山交界)不在八宅讨论范围,那是玄空的事
择吉·年柱立春为界,按日:立春当日整日归新年,年柱与方位煞同一判法春节换年会在立春前显示新年干支;年柱按日、紫白按时刻会在立春当天给出两套年
择吉·方位太岁、三煞、流年紫白一律以立春为界,与年柱同界用春节换年会在立春~春节窗口给出上一年的方位煞
择吉·紫白入中星按 7 − ((年 − 1984) mod 9) 算,不查表手抄的流年紫白表极易整体错位一年,且错了不报错
择吉·宜忌照录通书条目,不加工那是数据不是断语;「对你这件事意味着什么」仍不给
姓名·笔画由调用方提供引擎不内置字典;康熙笔画与简体差异很大
姓名·外格天格 + 地格 − 人格旧式 total−human+1 在单姓单名/复姓双名会偏
易经·经文卦辞、爻辞、大象照录维基文库《周易》(zh-hans 简体),断句一律从底本换底本(通行本/帛书/竹简)只改 scripts/fetch-zhouyi.mjs 的页名与解析规则
六壬·八专日干寄宫 = 日支(STEM_LODGING 推导)手写日表易把乙卯等误收进八专
六壬·六亲三传六亲以日干为我六爻以本宫五行为我,两者判据不同,不要互相代入
六爻·卦变进神退神只在同五行且序数递进时成立,八组写死用「同五行的下一位」去算,水与土那两组会两个方向都算成进神
六爻·伏吟内外卦伏吟返吟只在该卦有动爻时判不设这道闸,任何未动的内卦或外卦都会被报成伏吟
性别入参仅 male/female(兼容 男/女),规范化大小写或中文未规范化会静默按女命排大运

上表是人读的口径全览;代码侧的唯一真源是 backend/constants/rulings.js, 排盘响应统一带 school 字段回显所用口径。关键 key 如下(改名必须同步锁测试):

能力选定口径(rulings key)另一派会怎样
共用·子时晚子时不换日 late-zi-no-day-change子正换日(无开关)
共用·节气交节精确到分 solar-term-to-minute只比到日会在交节当天错边
共用·真太阳时有地点+时区默认启用 true-solar-time-when-location一律钟表时间
八字·藏干normalized-0.6-0.3-0.1(逐支归一)100:70:30 不归一等,旺衰占比会变
八字·月令month-branch-x2(仅月支×2)不加倍则身强身弱判定线整体挪动
八字·旺衰ally-ratio-55-45只看得令通根、不设阈值
八字·用神fuyi-only 扶抑法(与调候并列给出)病药/通关未实现,中和局扶抑给空数组
八字·调候qiongtong-quick-table 穷通宝鉴速查表各刊本互有出入,换版本改 geju.js 的表
八字·取格ziping-yueling 子平真诠月令取格以强弱定格等派,可照 facts 自行重推
紫微·闰月leap-to-base-month「闰月后半归下月」命宫身宫不同
紫微·庙旺not-implemented(断语层)需要就自行按所宗流派叠加
紫微·解神year-jieshen-only 只取年解月系解神落宫不同
紫微·宫序counter-clockwise-from-ming 自命宫逆布顺布与大限口径直接冲突
紫微·四化quanji-line-geng-yang-wu-yin-tong 戊右弼壬左辅中州派庚科天府、戊科太阳
六壬·四课first-course-day-stem 一课以日干为下按寄宫五行判克(错,非流派)
奇门·值使zhishi-luoshu-order 九宫数序飞、中五寄坤二八宫环转(错,非流派)
择吉·历注lichun-day-inclusive 立春当日整日归新年按交节时刻切(择吉没有时刻输入)
六爻·之爻ben-gong-as-self 六亲仍以本卦宫为我按之卦宫重排
六壬·月将mid-qi-change 中气换将用节换将会差将近半个月
六壬·涉害clockwise-home-tally-by-type 顺行归家「直取孟仲季」派不归家
六壬·取传nine-gates-order 八专在遥克前次第错则课体错
六壬·昴星yang-looks-up-yin-looks-down 阳仰阴俯两向取反初传全变
六壬·贵人geng-with-jia-wu 庚归甲戊庚组「庚辛逢虎马」派庚归午寅
奇门·定局chaibu 拆补法(符头地支定元,不置闰)置闰法(符头配所领节气+闰局)、茅山法
奇门·天盘zhuanpan 转盘法飞盘法
奇门·八神modern-baihu-xuanwu 白虎玄武古法阳遁用勾陈朱雀
奇门·入墓wuxing-tomb-treasury 五行墓库阴干各自逆行取墓(如乙墓戌)
奇门·格局not-implemented(断语层,关系量照给)青龙返首等各家出入大
八宅·定年lichun-year 立春为界(module=bazhai)用元旦为界
择吉·历注lunar-javascript-almanac(module=almanac)不自造第二份历注表
姓名·笔画caller-provides-strokes(module=name)引擎不内置字典

上表只挑了容易踩坑的。全部口径 key 如下(按 module 分组,字段名即 rulings.js 里的属性名;scripts/check-docs.mjs 会核对每个 key 都出现在本文里,漏了 CI 会红):

模块字段key口径
共用ziChuDayRolloverzi-chu-day-change子初换日(时家)
共用lateZiDayRolloverlate-zi-no-day-change晚子时不换日
共用solarTermPrecisionsolar-term-to-minute节气交节精确到分
共用trueSolarTimeDefaulttrue-solar-time-when-location给齐出生地与时区时默认用真太阳时排盘
八字hiddenStemWeightsnormalized-0.6-0.3-0.1藏干权重本气0.6/中气0.3/余气0.1,逐支归一到1
八字monthBranchMultipliermonth-branch-x2月令当权:仅月支藏干 ×2
八字strengthThresholdsally-ratio-55-45同党占比 >55% 身强、<45% 身弱、其间中和
八字usefulGodfuyi-onlyusefulGod 字段取扶抑法
八字tiaohouqiongtong-quick-table调候用神取《穷通宝鉴》通行速查表,与扶抑并列给出
八字monthlyStructureziping-yueling取格从月令,《子平真诠》一派
八字specialPatternrootless-follow-and-commanded-dominant从格看「四支全无同党通根且同党占比 <20%」,专旺格看「月令本气即日主且同党占比 ≥80%」
八字mingGongMonthjieqi-month命宫身宫的月支取节气月(月柱月支),不按中气分月
八字shenshaYangrenyangren-yang-stems-only羊刃只对阳干判定(神煞与格局同此一条)
紫微斗数leapMonthleap-to-base-month闰月归本月
紫微斗数fiveElementBureauming-nayin-bureau命宫干支纳音定五行局
紫微斗数palaceOrdercounter-clockwise-from-ming十二宫自命宫起逆布:兄弟在命宫前一位、父母在命宫后一位
紫微斗数majorPeriodyang-male-forward大限阳男阴女顺行、阴男阳女逆行
紫微斗数sihuayear-stem-sihua本命四化取年干
紫微斗数sihuaVariantsquanji-line-geng-yang-wu-yin-tong取《全集》一系:戊科右弼、壬科左辅、庚取「阳武阴同」
紫微斗数palaceSihuapalace-stem-sihua-fly宫干四化:每宫以本宫天干起四化,落到星所在之宫
紫微斗数brightnessnot-implemented庙旺利陷不实现
紫微斗数jieshenyear-jieshen-only解神只取年解(戌宫起子年逆行)
紫微斗数godsDirectionchangsheng-boshi-by-yin-yang长生十二神、博士十二神按年干阴阳分男女顺逆;岁前、将前一律顺行
六爻纳甲roleassemble-not-cast装卦不是起卦
六爻纳甲palaceDerivationseven-rule-derivation八宫由七条推衍规则算出,不查 64 行表
六爻纳甲changedLineSixRelativeben-gong-as-self变爻六亲仍以本卦之宫为我
六爻纳甲najiajingfang-najia京房纳甲
六爻纳甲advanceRetreateight-fixed-pairs进退神按八组固定支对判,不由「同五行下一位」推导
六爻纳甲trigramShiftrequires-moving-line内外卦伏吟返吟只在该卦有爻在动时判
六爻纳甲seasonalStatemonth-branch-wang-xiang爻的旺相休囚死只按月建(月令)判,不按日辰
大六壬monthGeneralmid-qi-change月将取月建六合,以中气换将
大六壬shehaiclockwise-home-tally-by-type涉害顺行归家;下贼上数受克、上克下数所克
大六壬maoxingyang-looks-up-yin-looks-down昴星阳仰阴俯:阳日取地盘酉上之天盘神,阴日取天盘酉所压之地盘支
大六壬noblegeng-with-jia-wu天乙贵人「庚」归甲戊庚一组(昼丑夜未),辛独取午寅
大六壬transmissionOrdernine-gates-order取传次第:贼克→比用→涉害→八专→遥克→别责/昴星
大六壬fuyinfuyin-ziren-zixin伏吟有克依贼克,无克阳日自任(干上神)、阴日自信(支上神)
大六壬firstCoursefirst-course-day-stem第一课以日干为下神,寄宫只用于取上神;判克以日干五行论
大六壬transmissionRelativeday-stem-as-self三传与四课上神的六亲以日干为我
奇门遁甲bureauchaibu拆补法定局:自占日向前取最近的甲己符头,按符头地支定上中下元,不置闰
奇门遁甲platezhuanpan转盘法排天盘九星八门八神
奇门遁甲centerPalacecenter-lodge-kun中五宫寄坤二;八门八神不入中宫
奇门遁甲zhishiFlightzhishi-luoshu-order值使门自值符宫按九宫数序阳顺阴逆飞到时辰旬序,落中五寄坤二
奇门遁甲eightGodsmodern-baihu-xuanwu八神第五第六位取白虎、玄武(现代通行简化派)
奇门遁甲stemTombwuxing-tomb-treasury十干入墓按五行墓库:木墓坤二、火土墓乾六、金墓艮八、水墓巽四
奇门遁甲gatePogate-controls-palace门迫=门克宫;反向的宫克门为门制(isGateZhi)
奇门遁甲seasonalStatemonth-branch-wang-xiang八门九星的旺相休囚死按月令(节气月支)五行判
奇门遁甲patternsnot-implemented格局命名不实现
八宅lifeTrigramYearlichun-year八宅定年以立春为界
八宅younianflip-sequence游年由变爻序列推出,不查 8×8 表
八宅houseTrigramsitting-mountain-trigram宅卦由坐山归卦,二十四山(各15°)归到八卦(各45°)
择吉dayGranularitylichun-day-inclusive历注按日:立春当日整日归新年,年柱与方位煞同一判法
择吉almanacSourcelunar-javascript-almanac历注(论日/论时两层)委托 lunar-javascript,本引擎只组结构
择吉directionsYearlichun-year-directions方位煞(太岁、岁破、三煞、紫白)以立春为界,与年柱同界
择吉nineStarcomputed-center-star流年紫白入中星按公式算,不查表
姓名五格nameStrokescaller-provides-strokes笔画由调用方提供
姓名五格nameGridswuge-standard单姓天格+1、单名地格+1、人格取姓末+名首,外格=天+地−人
周易起卦methodmeihua梅花易数
周易起卦timeCastyear-zhi-lunar-month-day-hour-zhi时间起卦用年支序数+农历月日+时支序数
周易起卦numberCastfirst-upper-second-lower-sum-mod6三数起卦:一数除八取上卦、二数除八取下卦、三数之和除六取动爻
周易起卦leapMonthleap-to-base-month闰月归本月(与紫微同)
周易起卦scripturewikisource-zh-hans卦辞、爻辞、大象传照录维基文库《周易》,取其 zh-hans 简体转换
合盘focusspouse-palace-ganzhi以日支(夫妻宫)干支关系为主,非五行粗比
合盘scoreweighted-relationsscore 由客观关系加权折算,不是断语
塔罗randomnessnot-reproducible默认抽牌随机、不可复现(给了 seed 才确定,见下条)
塔罗seedfnv1a-mulberry32seed 用 FNV-1a 哈希成 32 位整数后喂 mulberry32
塔罗reversalRatereversal-0.5默认逆位概率 0.5(正逆等权)
塔罗spreadsnamed-spreads-with-aliases牌阵:SingleCard / ThreeCard / CelticCross,别名归一后回显真实名
塔罗cardMetadataderived-from-card-name大小阿卡纳、花色、序位、花色元素由 id 与牌名推出,不逐张手写
西洋星座contentstatic-sign-content星座基础信息为静态内容表,非精密推运
西洋星座horoscopeengine-local-date-window运势区间按引擎本地「今天」切日/周/月,跨天可变
上升星座modelsimplified-gmst-obliquity简化 GMST + 黄赤交角模型,非 Swiss Ephemeris 级星历
上升星座inputlat-lon-tz-required必须给出生时刻、经纬度、时区偏移
流日dateSourceengine-today-only日柱恒取引擎当日,无日期参数
流日personalizationoptional-birth-ganzhi-score给全出生信息则结合本命干支关系计分,否则只回日柱

贯穿全部能力的一条线:结构归引擎,断语归调用方(structure-only)。 盘怎么排(三传、安星、排局、游年)有唯一正确答案,引擎必须算准; 盘怎么解各家分歧大,引擎只把原料给全。换派:改 rulings.js + 对应 service 读值处 + 锁测试。

这条线不是「凡带吉凶字样的一律不给」,而是按那句话是谁说的来分:

给因为例子
客观关系那是可核对的事实,名字只是事实的代号奇门「门迫」=门克宫;六爻「进神」=变支同五行且序数递进;紫微三方四正
通书条目那是照录的数据,不是引擎的判断择吉的宜/忌、吉神/凶煞、黄道黑道、时辰吉凶 —— 都出自通书,引擎一字不加工
结构事实无流派分歧,任何一派都从它出发八字 monthlyStructure.facts(月令藏干、透在哪柱、什么十神)
不给因为例子
吉凶评价那是引擎在替调用方下判断「门迫了会怎样」「这张盘好不好」
分歧命名各家取名与成立条件出入极大,钉死一派等于替调用方选了门派奇门格局(青龙返首、飞鸟跌穴)、紫微庙旺利陷、姓名数理吉凶

所以「三奇得使」不给(那是格局命名),但它所依据的三奇落宫、门宫生克、旬空全给; 「今天宜不宜动土」不给,但通书原文的宜忌、当日三煞五黄所在之方全给。

六爻:装卦不是起卦,且变爻六亲不按之卦论

calc liuyao 要你给 --lines(六位 0/1,自初爻起)—— 六爻由你摇、引擎只负责装。 这跟 cast iching 不是一回事,后者是起卦。

两个容易搞错的地方:

  • 变爻的六亲仍以本卦之宫为我,不按之卦的宫重排。这是纳甲筮法定例, 按之卦重排会让整个动爻分析失去参照。
  • 八宫归属是由「本宫→一世→…→游魂→归魂」七条推衍规则算出来的,不是查表。 要改流派就改那七条规则,别去找六十四行的表——没有那张表。

不给 --date 时六神与旬空按引擎当日起,同一副卦换一天结论就不同。

六壬:取传次第不可调换

九宗门是逐层排除的,次第本身就是规则的一部分:

贼克 → 比用 → 涉害 → [八专] → 遥克 → 别责 / 昴星

八专 的位置最反直觉:它的成立条件里明写「不取遥克」,所以必须排在遥克之前。 放到后面,八专日会被蒿矢/弹射先截走 —— 三传照样出得来,课体却是错的, 而课体是后面所有断语的依据。(这个坑本项目踩过,见 CHANGELOG。)

别责 判的是「四课缺一、只剩三课」,指的是上下神成对重复; 两课上神相同而下神不同时仍是四课,不该判别责。

伏吟、返吟不是特殊情况,而是由月将与占时的关系直接决定的:将时相同即伏吟、 相冲即返吟,这两门先于其余七门判定。

奇门:两套飞泊次序不能混用

  • 地盘三奇六仪按一到九顺(逆)飞九宫,中五宫要占一位。
  • 九星、八门、八神在洛书八宫环上转(坎一→艮八→震三→巽四→离九→坤二→兑七→乾六), 中五宫不参与,寄坤二。

拿九宫环去转八门,会排出「中五宫有门」这种不存在的盘。天禽星同理:它居中无方位, 实务上寄坤二随天芮,其所临之宫在 lodgedStar 里单列。

还有一个看着像 bug 的正常现象:时干恰好就是旬首所遁之仪时,值符加临自己,天盘不转, 于是每宫的天盘干与地盘干相同。这是对的,不是没转成。

外部交叉验证:对过哪些独立实现,它们哪里不可信

除公开例课外,紫微、六壬、奇门、上升星座还拿第三方独立实现做过大样本逐盘比对 (2026-09-09,固定用例钉在 backend/test/algorithm_cross_validation.test.js, 样本分布与生成记录在 backend/test/fixtures/cross_validation.json 的 provenance)。 结论与分歧点都在这里,再遇到「某某库排出来不一样」先查这张表,不要直接改算法:

能力参考实现样本结果
紫微iztro 2.6.1(fixLeap=false)400 张随机盘命身宫、五行局、宫名宫干、主星辅星煞星、四化、大限零差异
六壬kinliuren 0.1.2.9(result(0))300 课天盘、四课、天将盘全部一致;三传 234 课一致,66 课分歧全部按古法手核为本仓库正确(见下)
奇门kinqimen 0.0.6.6 拆补法200 张随机盘换算流派表示后 198 张一致;2 张分歧为时干落中五宫,kinqimen 自相矛盾,本仓库按「寄坤二、值符加临自己则伏吟」
上升星座astronomy-engine 2.1.1910 点地方恒星时最大差 0.0044 h(16 秒),上升点黄经最大差 0.006°,即简化 GMST 模型的固有精度
塔罗—(自检)15600 seed78 张 id / 牌名唯一、大小阿卡纳与花色序位齐全;连续 seed 首张牌卡方 < 118.6(p=0.001),逆位率 0.5 ± 0.02

对方不可信的地方(都是那两个 Python 库自己的实现问题,不是流派):

  • kinliuren 的返吟课把「六无依日」之外的有克日也报无依(庚寅、丙戌…);比用取了不受克的支; 涉害数深浅的方向反了;伏吟自刑的中末传把三刑方向数反(未刑丑写成未刑戌);八专日先走了遥克; 别责日误判成返吟。这些恰好都落在本仓库 rulings 里逐条声明过的口径上,nine-gates-order、 clockwise-home-tally-by-type、fuyin-ziren-zixin 的每一条都有一课钉着。
  • kinqimen 八神用古法(阳遁勾陈朱雀、阴遁白虎玄武),本仓库 modern-baihu-xuanwu 两遁皆白虎玄武, 位置一一对应;值符值使落中宫它标「中」不寄坤,本仓库一律标坤二(center-lodge-kun)。 只有这两处是表示差异,其余全部逐宫一致。
  • iztro 默认 fixLeap=true(闰月前半归上月、后半归下月)和 dayDivide='forward'; 与本仓库对比时必须传 fixLeap=false,晚子时(23 点)两边口径不同,样本避开了那一小时。

要重跑这套比对:三个库都不在仓库依赖里(其中 kinqimen 依赖的 sxtwl 在 macOS 上编不过, 得用一个只给日干支与时支的替身),装在临时目录里跑即可;重新生成夹具之前必须再跑一遍全量比对, 一致了才允许覆盖 cross_validation.json。


操作

起手式

./bazi doctor --json        # 退 3 就照每一项的 fix 修,或者 ./bazi doctor --fix
./bazi stack up --json      # 起引擎,幂等,已经在跑的会跳过
./bazi stack status --json  # 任何时候先看这个再动手

Agent 在调用能力命令前,可以用 ./bazi stack status --require-ready --json 做前置断言: 未就绪直接退 3。不过能力命令自己也会在连不上时退 3 并给出 next,所以通常不必先探。

把能力装进上层 Agent:bazi schema

bazi schema 把命令树导出成 agent tool schema —— 上层 Runtime 的 Tool Registry 装载它, 就不必读 help --json 再自己翻译一遍。纯本地生成,不需要引擎在跑。

./bazi schema --json                       # 算法能力,Anthropic 格式
./bazi schema --format openai > tools.json # 文本模式的 stdout 就是裸数组,可直接重定向
./bazi schema --scope all --format mcp --json

四件要知道的事:

  • 默认只导出能力命令。 运维命令要 --scope ops 显式取 —— 它们会改这个仓库, 其中还有破坏性的,不该默认变成模型随手可调的工具。分界读的是每条命令声明的 kind, 不是命令名前缀。
  • --json 才有 catalog。 tools 是可以直接贴给 API 的干净定义(不夹带自定义字段, 否则 Anthropic / OpenAI 会当非法字段拒掉);把一次工具调用还原成 argv 所需的映射 ——哪个 property 拼成 --flag、哪个是位置参数、布尔怎么处理——全在 catalog 和 invocation 里。调用时总是追加 --json。
  • 每条工具都带 effect(副作用)与 reproducibility(可复现性)。 effect 三档:read-only / local-write / destructive,MCP 格式下同时体现为 readOnlyHint / destructiveHint,是做权限判断的依据;非只读的还会在 description 里写明它会写 —— 因为 anthropic / openai 两种格式没有放 annotation 的地方。
  • 可复现性进了工具描述。 装载 schema 的 Runtime 不一定读得到这份文档, 而"拿一个每天都在变的结果当回归基准"是最常见的误用。

这条命令不需要维护:新增命令后它自动带上,前提是那条命令按下面「要改 CLI 本身的时候」 那节的硬约束把 effect / kind / required / choices / variadic 声明齐全。

直接挂成 MCP server:bazi mcp

要的不是一份定义而是一个能直接挂给 Agent 的 server 时,用 ./bazi mcp —— stdio 传输,工具定义与 bazi schema 同源(共用 core/toolSchema.mjs, 契约测试逐条比对,连 inputSchema 与 annotations 都不许有差异)。

{ "command": "./bazi", "args": ["mcp"] }
  • 默认只暴露 calc / cast,14 个工具,全部只读。 运维命令要 --scope ops|all 显式放进来。
  • 每次工具调用都真的去跑一次 CLI,不是在进程内直调。参数校验、必填检查、 破坏性操作的安全闸、退出码语义因此全部原样继承 —— 进程内直调等于把安全闸绕过去, 而工具长期挂在 Agent 上时正是最需要它的时候。
  • 退出码翻译成 isError,CLI 信封里的 hint / next / exitMeaning 原样交给模型。
  • stdout 归协议独占,日志走 stderr;这条命令没有 --json 可言(它没有结果信封)。
  • 引擎要先起着,和其他能力命令一样:./bazi stack up。
  • SDK(@modelcontextprotocol/sdk)是动态加载的:没装只影响这一条命令,退 3 并提示 npm install,bazi doctor 里也单列一项 deps:mcp-sdk。

--dry-run:动手之前先问它

会改东西的命令都支持 --dry-run,打印"会做什么"然后返回 0,不执行。

能力命令也支持,用途不同:它把参数被解析成了什么原样回显(尤其 --birth 拆成了 哪年哪月哪日哪时哪分),一个请求都不会发出去。参数拿不准时先 dry-run 一次比较省事。

它是全局标志,bazi help --json 的 tree.globalFlags 里能查到(--json / --quiet / --dry-run / --yes / --help 都在那里,不在每条命令自己的 flags 里)。

关于 exit 7:不要自动绕过

破坏性命令在没有 --yes 时会返回 7。不要自己补一个 --yes 重跑——那等于这道闸 从来没存在过。正确流程是先 --dry-run 看清楚会动什么,把结论告诉用户, 拿到明确的"是"之后再加 --yes。

--dry-run 只能越过"确认"这一道闸。NODE_ENV=production 是硬拒绝,加什么参数都绕不过 ——那是代码里的边界,不是约定。

哪些命令会动东西不要靠命令名猜,看 help --json 里的 effect: read-only 随便跑,local-write 会改本机状态(进程 / 配置 / 依赖), destructive 会丢掉已有内容、需要人拍板(destructive: true 标记是它的派生,仍然保留)。

按最坏情况标注:doctor 不带 --fix 时其实只读,但它整条是 local-write; env init 只有 --force 才覆盖,整条按 destructive 标 —— 实际拦不拦由运行时判断, 所以你会看到 bazi env init --dry-run(不带 --force)照样退 0。

测试:skipped 不等于 passed

bazi test 的目标未就绪时会记 skipped 并照样返回 0。这意味着一次"什么都没跑" 也会报成功:

summary: {"passed": 1, "failed": 0, "skipped": 2}   # exit 0,但 lint/backend 根本没跑

永远读 summary.skipped,别只看退出码。 要让"什么都没跑"变成硬失败(CI、或者你需要 一次可信的全量),加 --fail-on-skip:有跳过就退 3。

./bazi test --fail-on-skip --json

cli 目标排在最前面是它自己的契约测试(退出码语义、--json 单文档、能力命令的 HTTP→退出码映射、安全闸不可绕、导出的 schema 与 CLI 真实行为一致),两秒跑完: 它挂了说明你正在用的这个工具本身坏了,后面目标的结论都不再可信。

engine 是四个目标里唯一需要引擎在跑的:它拿真实引擎验证每条声明可复现的 能力命令连调两次结果一致。引擎没起时它记 skipped(不是 failed —— 那是环境问题 不是代码问题),所以要一次可信的全量就配 --fail-on-skip。

foreign:CLI 不碰不是自己起的进程

stack status 里引擎带 managedBy,取值:bazi(CLI 起的,能停)/ foreign(端口被别的进程占了,CLI 不碰)/ null(没在跑)。

看到 foreign 时 CLI 会拒绝接管,也拒绝 kill。这是故意的:按端口去杀进程会误伤用户 自己开的终端、另一个 worktree、或者同事的服务。

正确处理:告诉用户 4000 端口上有不是 bazi 起的进程,让他们决定。 不要自己去 kill $(lsof -ti:4000)。

推论:不要绕过 CLI 手动起服务(node server.js)。那样起的进程 CLI 管不到, 后面 stack down 停不掉,stack status 只会显示 foreign。

把 CLI 指向别的引擎

BAZI_API_URL 环境变量可以让能力命令打到任意实例(容器、staging、同事的机器), 不改任何代码:

BAZI_API_URL=https://engine.example.com ./bazi calc bazi --birth ... --json

没配就用 .env 的 BACKEND_BASE_URL,再没有就是本地 PORT(默认 4000)。 注意 stack 那组命令管的始终是本地进程,跟这个变量无关。

排查

./bazi stack logs --tail 60         # 引擎日志(pino JSON)

启动失败时 CLI 会把日志压成一条诊断再返回,不会把几十 KB 原始日志塞进 hint。 认得出的失败特征(端口占用、必填环境变量缺失)会直接翻译成下一步命令。

运行态都在 .tmp/cli/ 下(pidfile、日志),已被 .gitignore 覆盖,可以整个删掉重来。

要改 CLI 本身的时候

源码在 tools/cli/,契约测试在 tools/cli/test/,./bazi test cli 两秒跑完,不需要引擎。 tools/cli/test/engine/ 下那一份是例外:它要打真实引擎,走 ./bazi test engine。

下面这些不是风格建议,是测试会当场拦下来的硬约束:

  • 失败一律抛 CliError,带 exit / hint / next。next 必须是一条真能跑的 bazi 命令——测试会拿 help --json 的命令树去验证它解析得出来。
  • --json 模式下 stdout 只能有一个 JSON 文档。 想给人打东西用 out.render (json 模式自动跳过),想说进度用 out.step / out.warn(走 stderr,同时进 payload.notes)。子进程一律用 out.childStdio。
  • 必填要声明成 required: true,不要写在 run 里。 校验由 parseArgs 统一做, 写在 run 里的 if (flags.x === undefined) throw 有一个看不见的后果:bazi schema 导出的 tool schema 读的是声明,于是它会告诉上层"这个参数可选",上层照做,必然失败。 同理,取值集合用 choices,并且和 run 里校验用的那个常量是同一个(GENDERS 那样)。 位置参数能给多个时标 variadic: true,否则导出的 schema 一次只让传一个。
  • 命令自己的 flag 不能和全局 flag 重名,否则会被 flagSpecFor 的查找顺序静默吃掉。
  • examples 里的命令和选项必须真实存在,测试会逐条解析;而且第一条示例会被 拿去反推一次工具调用、按 catalog 的映射拼回 argv 再跑一遍 dry-run。
  • 每条可执行命令必须声明 effect(read-only / local-write / destructive, 见 core/registry.mjs 的 EFFECTS)。缺了直接被测试拦下。破坏性的除了标 effect: 'destructive' 还要过 assertDestructiveAllowed —— destructive 布尔 是 effect 的派生,不要再单独写,两个字段各写各的迟早自相矛盾。
  • json 和文本两种模式的退出码必须一致。

新增一条命令:在 src/commands/ 下写好,挂进 src/main.mjs 的 rootCommand.commands。 help --json 会自动带上它,这份文档和 README 都不需要改——这是刻意的,抄命令清单一定会腐化。

契约三件套(kind / effect / reproducibility)沿命令树继承:整棵子树同质就在 组节点上声明一次(calc 就是这么做的),个别不同的子命令再自己覆盖。 kind 缺省是 ops —— 新增顶级能力命令组时记得声明 kind: 'capability', 否则它不会出现在 bazi schema 的默认导出里(这个缺省方向是刻意的: 宁可一条能力命令暂时不被导出,也不要一条会改仓库的命令悄悄进了模型的工具清单)。

新增能力命令时额外注意三点:

  • 走 core/apiClient.mjs 的 callApi,不要自己 fetch。那里集中着 HTTP→退出码的映射, 绕过它就等于这条命令没有契约。
  • reproducibility 要照实声明,别照着"它在 calc 底下所以是确定的"填。 标了 deterministic / conditional 的会被 bazi test engine 拿真实引擎连调两次比对, 声称可复现却每次都变会当场失败。响应里只要有一个随调用时刻变化的字段就不算确定。
  • 请求必须带 connection: close。bin/bazi.mjs 靠自然退出(不调 process.exit, 否则可能截断没 flush 的 stdout),而 Node 的 fetch 默认把连接留在 keep-alive 池里, 那是个活跃 handle,会让每条命令算完之后凭空多挂几秒才退出。

写 CLI 的测试时还有一个坑:test/helpers.mjs 的 bazi() 用 spawnSync, 它会把测试进程的 event loop 整个堵死。如果你的测试要在同进程里起一个 stub HTTP 服务, 子进程的请求永远等不到应答,所有用例都会以"超时"收场,把真正要测的东西全盖掉。 参照 test/api_client.test.mjs 里的异步 runBazi。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.