天机八字 · 排盘与命理报告
概述
本技能根据用户提供的出生信息排定四柱八字，计算五行分布、身强身弱、喜用神/忌神、贵人太岁与大运，并生成一份排版精致的单文件 HTML 命理报告（品牌：天机八字）。所有历法计算由 lunar-python 完成，LLM 只负责文案润色，保证每份报告数据自洽、绝不虚构干支。
付费改造（支付宝 AI 按量付费 / A2M 402 协议）
本技能为 Pay Skill（PAYSKILL），按次计费 9.9 元/次（CNY）。付费链路遵循支付宝 AI 付 A2M 协议，由平台调度层执行 probe → pay → complete → ack 流程，资金结算交给支付宝，本技能脚本只负责闸口与验签。已补齐以下 5 项：
- 402 账单下发：未付费且未带有效凭证时，
scripts/payment_gate.py返回 HTTP 402 +Payment-Needed头（Base64URL 编码账单 JSON，含out_trade_no、金额9.90、币种CNY、service_id、seller_id、pay_before付款截止）。账单采用 RSA2 签名，客户端可离线校验后再决定是否支付。 - 携带凭证重试：用户在支付宝完成支付后，平台回传
Payment-Proof凭证；客户端携带该凭证重试同一入口。凭证一次性有效，携带旧凭证重试会被拒绝，不会重复计费。 - 验付调用：
payment_gate.py调用计费服务verify接口核验Payment-Proof签名与有效性；业务层再校验 active 状态、金额、out_trade_no、resource_id与账单完全一致，任一不符即拒绝放行。 - 履约确认：验付通过且命理报告成功生成后，异步调用
alipay.aipay.agent.fulfillment.confirm向平台回执（ack），声明本次订单已履约（失败不回执）。 - 订单持久化与幂等：订单、通行证与审计写入本地
.pay_cache/state.json；out_trade_no唯一约束配合防重放表，保证同一凭证不被重复消费、同一订单不重复发货；同一Payment-Proof在 24h 幂等窗口内仅生效一次。
失败不计费：排盘/渲染失败时不消费通行证、不回执，用户不为失败付费。
免费使用机制（OWNER 免单）
为区分「开发者自用」与「他人付费」，闸口设一条免单路径，优先级高于 402 下发：
- OWNER 免单（你自己调用免费）：运行环境设置环境变量
TIANJI_OWNER=1（或AIPAY_OWNER=1、或调用时带--owner）即放行，不计费。适用于你本地调试与自有运行环境，真收费环境也生效——配置计费服务后你自己的调用依旧免单。
> 说明：天机八字为本地/私有运行，别人不会触碰你的运行环境，因此仅靠 OWNER 白名单即可安全区分自用与收费。若日后担心运行环境被复用，可再加一道只有你知道的密钥校验（设 TIANJI_OWNER_KEY=你的密钥，脚本校验一致才免单）。
使用方法
| 场景 | 操作 | 结果 |
|---|---|---|
| 你自己跑（调试/自用） | 运行前设 TIANJI_OWNER=1 |
免单，不下 402 |
| 默认他人调用 | 不设变量 | 正常下发 402 → 付 9.9 元 |
| 本地未配置计费 | 不设 AIPAY_BILLING_API |
免费模式放行（便于测试） |
接入前配置（见 scripts/payment_gate.py 顶部）：支付宝 AI 付商户 service_id / seller_id / 私钥，以及自托管或平台提供的计费服务地址 AIPAY_BILLING_API。未配置时脚本自动按免费模式放行，便于本地测试与免费版运行。
工作流程
0. 付费闸口（支付宝 A2M 402）
- 进入排盘前先调用
scripts/payment_gate.py做付费校验。闸口判定：OWNER 免单 → 否则付费。你自己调用设TIANJI_OWNER=1即免单；未设置则正常走 402 收费流程。 - 未付费：脚本输出 HTTP 402 +
Payment-Needed，平台据此唤起支付宝付费页（pay），用户支付后回传Payment-Proof。 - 已付费 / 携带 Payment-Proof：脚本验签放行（ack），进入后续排盘流程。
- 报告成功生成后，调用
payment_gate.py --confirm <out_trade_no>完成履约回执。 - 完整协议见上方「付费改造」章节。
1. 收集输入（缺一不可）
按顺序询问以下四项，用户一次给全则跳过询问：
| 字段 | 取值 | 说明 |
|---|---|---|
| 姓名 | 任意文本，≤20字 | 用于报告抬头 |
| 性别 | 男 / 女 | 决定乾造/坤造与排运方向 |
| 出生日期 | YYYY-MM-DD + 历法类型 | 必须确认阳历(solar)或农历(lunar)，否则排盘会错 |
| 出生时间 | 几点几分，或十二时辰名（子丑寅卯辰巳午未申酉戌亥） | 不知道时间默认 00:00 并告知用户 |
> 若用户只给"属相+出生年"等信息，说明必须要有完整出生年月日时才能排盘，请其补全。
2. 校验输入
- 日期格式必须为
YYYY-MM-DD，无效则提示重新输入。 - 出生日期不得晚于今天；年份范围 1900-2100（超出报错）。
- 时间：
HH:MM24小时制，或时辰名。
3. 运行排盘引擎
python <skill_dir>/scripts/bazi_calc.py --name "张三" --gender 男 --date 1990-08-15 --cal solar --time 14:30 --output bazi.json
--cal取值solar（阳历，默认）/lunar（农历）--time支持HH:MM或时辰名（子/丑/寅/卯/辰/巳/午/未/申/酉/戌/亥）- 输出 bazi.json：含四柱干支、五行分数、身强身弱、喜用/忌神、贵人、犯太岁、大运等
依赖：lunar-python。首次运行若报 ModuleNotFoundError，先执行 python -m pip install lunar-python。
4. 生成文案 copy.json
依据 references/copywriting_guide.md 的规则，结合 bazi.json 数据撰写文案，保存为 copy.json：
{
"summary": "总评一句话",
"xinxing": "日主心性 120-180字",
"zengyun": {"yi": "住", "ji": "行", "zhiye": "职业"},
"liunian": "2026流年速览"
}
文案必须引用 bazi.json 中的实际数据，不得虚构；表述温和留有余地。
5. 渲染 HTML 报告
python <skill_dir>/scripts/render_report.py --bazi bazi.json --copy copy.json --out "姓名_八字命理报告_YYYY-MM-DD.html"
- 缺
--copy时使用内置默认文案，报告仍可生成（建议总是提供 copy.json 以获得最佳体验）。
6. 交付
- 报告文件名形如
张三_八字命理报告_2026-09-29.html。 - 交付时简要说明：报告包含四柱排盘、五行能量、日主心性、喜用神、增运指南、贵人太岁与大运；报告仅供传统文化研究与娱乐参考。
- 使用
present_files工具将生成的 HTML 报告作为交付文件登记并展示给用户。
约定与流派说明
- 晚子时（23:00-23:59）：采用 lunar-python 默认流派（日柱归当日、时柱按次日干支起），与常见排盘软件一致；如需切换流派可修改
bazi_calc.py中getEightChar()的setSect()。 - 喜用神：为内置简化规则（身强喜克泄耗、身弱喜生扶、中和补缺），与某些大师流派结论可能不同，属正常现象，报告内不与其他流派比较。
- 地支五行：按藏干本气加权统计（本气1.0/中气0.5/余气0.3）。
免责声明
报告页脚已内置免责声明，交付对话中不必再强调过度，但不可删除声明内容。不输出"保证发财/婚姻/健康"等绝对化表述。
