FateCat

[!WARNING] 本项目及 AI 分析结果仅供传统文化研究、算法测试与娱乐参考。命理学非精密科学，命运掌握在自己手中。使用者因轻信或误读本程序结果而产生的任何心理、财务及生活决策后果，本开源项目及开发者概不负责。

[!TIP] 交易猫 TradeCat 赞助与支持本项目。推荐工作流：先用交易猫完成专业排盘，再把结构化命盘交给 AI 深度分析，尽量减少模型乱编。

• TradeCat Repo: https://github.com/tukuaiai/tradecat
• FateCat Repo: https://github.com/tukuaiai/fatecat
• CA: 0x8a99b8d53eff6bc331af529af74ad267f3167777

项目总览

FateCat 不是让 AI 直接“脑补排盘”，而是把“排盘”和“解释”拆开：

1. 成熟排盘系统或外部算法负责结构化计算。
2. FateCat 负责统一字段、统一输出、统一交付入口。
3. AI / Agent 只基于稳定 JSON 或标准 Markdown 做解释、总结与后续任务。

维度	说明
项目角色	专业排盘结果到 AI 分析结果之间的结构化中间层
当前形态	标准单-skill 仓库；根目录是 skill 外壳，scripts/project/ 是真实源码
推荐链路	TradeCat / 专业排盘 -> FateCat pure-analysis -> AI / Web / Telegram / API / Agent
核心真相源	scripts/project/assets/fate/ 定义字段 profile，scripts/project/assets/vendor/ 保留成熟算法快照
明确边界	不让 AI 直接口算排盘，不在 scripts/project/assets/vendor/ 魔改外部源码

Skill 仓库

当前根仓库承担 4 个职责：

• 单-skill 仓库入口：SKILL.md 定义 agent 如何接手、安装、检查、执行。
• 生命周期治理层：scripts/project/assets/docs/lifecycle/、references/、根脚本负责需求到运维的标准化闭环。
• 统一执行包装层：根 scripts/ 把源码仓库常用动作封成稳定入口。
• 可导出 bundle 源：可把当前 skill 连同运行时骨架导出为独立交付包。

真实业务源码与运行时真相源在：

• scripts/project/modules/fate_core/：纯命理分析内核。
• scripts/project/modules/telegram/：Web HTML、Telegram、FastAPI、报告生成与 legacy 适配。
• scripts/project/assets/：配置、schema、字段 profile、外部成熟算法与数据资产。
• scripts/project/runtime/：数据库与运行态产物。

模式选择

场景	推荐入口	输出形态	是否要求 FATE_BOT_TOKEN	说明
本地调试、脚本串联、先排盘再喂 AI	bash scripts/pure-analysis.sh	stdout JSON / 文件 JSON	否	最稳定、最适合结构化输出
人类在浏览器中录入并复制报告	bash scripts/serve-api.sh -> /web	HTML 表单 + Markdown	否	直接输入出生信息，输出可复制 Markdown
要接服务、工作流、上层系统	bash scripts/serve-api.sh	HTTP JSON	否	适合 Webhook、自动化平台、自建前端
想直接聊天式使用	bash scripts/serve-bot.sh	Telegram 消息 / 报告文件	是	人工交互最直接
OpenClaw / Harness / 自动化 Agent	project 内自举入口	非交互 CLI / 健康检查	纯分析否，Bot 是	适合批处理与自动部署

架构

flowchart LR
    A[TradeCat / 专业排盘] --> B[外部成熟算法 scripts/project/assets/vendor]
    B --> C[fate_core 纯分析内核 scripts/project/modules/fate_core]
    F[字段 profile scripts/project/assets/fate] --> C
    G[配置 / 数据 / schema scripts/project/assets] --> C
    C --> D[稳定 JSON + branding + disclaimer]
    D --> E1[CLI]
    D --> E2[Web HTML /web]
    D --> E3[FastAPI JSON]
    D --> E4[Telegram Bot]
    D --> E5[Agent / Skill]
    H[runtime 数据库 / 日志] --> E3
    H --> E4

推荐工作流：

TradeCat / 专业排盘
        ↓
FateCat pure-analysis 输出稳定 JSON
        ↓
AI 基于结构化字段做命理解读
        ↓
Web / Telegram / API / Agent 继续交付

快速开始

1. 首次准备运行时

bash scripts/bootstrap.sh --with-dev

只需要最小运行时：

bash scripts/bootstrap.sh

2. 先做标准预检

bash scripts/preflight.sh --mode pure --bootstrap --pretty

交付层检查：

bash scripts/preflight.sh --mode delivery --bootstrap --pretty

3. 执行一次命理排盘并输出文件

mkdir -p output
bash scripts/pure-analysis.sh \
  --input-json '{"birthDateTime":"1990-01-01 08:00:00","gender":"男","longitude":116.4074,"latitude":39.9042,"birthPlace":"北京市","name":"测试样本"}' \
  --output-file output/bazi-result.json \
  --pretty

4. 做完整验收

bash scripts/acceptance.sh --with-dev

完整验收覆盖 shell 语法、strict skill 校验、纯分析 smoke、vendor health、全量 pytest、ruff、format、fate_core mypy、API/Bot dry-run、导出包卫生检查与导出包 smoke。 其中 pytest 已包含 1900-2030 节气 golden、月令/立春边界、起运样本、综合八字报告结构、隐私脱敏和 evidence 权重策略回归。

Web HTML

Web 版遵循零美化语义界面：原生 HTML 表单、服务端直出、psql ASCII 字段表、Markdown 原文 <pre><code> 展示、复制按钮只做渐进增强。

启动 API：

bash scripts/preflight.sh --mode delivery --bootstrap --pretty
bash scripts/delivery-smoke.sh --target api
bash scripts/serve-api.sh

访问：

http://127.0.0.1:8001/web

字段契约：

字段	必填	说明
出生日期	是	YYYY-MM-DD
出生时间	是	HH:MM 或 HH:MM:SS
出生地区	是	中文地点或 lng,lat，如 北京 / 116.4074,39.9042
性别	是	male / female；现有排盘逻辑必需，不能默认猜测
输出体系	否	当前可用：bazi / ziwei；默认 bazi，每次只输出一个已实现体系
姓名	否	为空时报告标题使用“命主”

前端展示规则：非北京类出生地区只用于经纬度解析和真太阳时计算，Web/Bot/Markdown 展示层会统一显示为“已填写（非北京地区已隐藏）”。

标准 Markdown 报告结构

默认 Markdown 输出综合八字体系，包含八字主线和袁天罡称骨民俗辅助。紫微斗数作为独立体系保留，既可通过 Web HTML 的“输出体系”控件、Telegram 确认页按钮或 API options.reportSystem 单独选择，也已作为 ziwei production capability 进入统一协议；它仍不和综合八字一起输出。黄历/择日已作为 almanac 生产 capability 独立提供 CLI/API 调用，梅花易数已作为 meihua production capability 提供轻量问事盘面，但二者都不进入默认 Markdown 报告；六爻、奇门、大六壬、风水九星、姓名合婚等仍是未来 capability，不允许混入综合八字默认报告。

综合八字 JSON 结果包含默认隐藏的 analysisEvidence 与 accuracyGuards，用于审计日主、五行喜忌、格局、干支关系、真太阳时、节气月令、起运边界、神煞和袁天罡称骨的依据、来源、规则 ID 与权重。这些字段不渲染到默认 Markdown 正文，避免用户报告变成技术附录。

可选体系：

值	输出体系	状态	是否与八字混排
bazi	综合八字	当前可用	否；默认输出八字主线与袁天罡称骨
ziwei	紫微斗数	当前可用 / 独立 capability 可用	否；独立输出紫微斗数、紫微基础、紫微运限四化
almanac	黄历/择日	独立 capability 可用	否；通过 fatecat capability almanac 或 /api/v1/capabilities/almanac 调用，不属于 Markdown 报告体系
meihua	梅花易数	独立 capability 可用	否；通过 fatecat capability meihua 或 /api/v1/capabilities/meihua 调用，只输出盘面与证据
liuyao	六爻占卜	未来功能	否；事件型起卦
qimen	奇门遁甲	未来功能	否；独立排盘
liuren	大六壬	未来功能	否；独立排盘
fengshui	风水九星	未来功能	否；方位/山向/门向输入
name_marriage	姓名合婚	未来功能	否；姓名学与合婚输入
yijing	易经系统	未来功能	否；卦辞与起卦体系

API 生成 Markdown 的入口：

POST /api/v1/report/markdown

请求体沿用 BaziRequest，在 options.reportSystem 中传入当前已实现的 bazi 或 ziwei。体系清单入口：

GET /api/v1/report/systems

结构化 capability 入口：

GET /api/v1/capabilities
POST /api/v1/capabilities/almanac
POST /api/v1/capabilities/ziwei

默认 bazi 输出块顺序固定如下：

免责声明（纯文本，无 # 标题）

## 赞助支持

# 命理排盘报告：{姓名}

## 第一卷：先天命格（静态分析）
  ## 基本资料（含真太阳时、节气）
    ### 基本资料
  ## 八字排盘详情
    ### 五行分数
    ### 天干分数
    ### 温湿度与拱神
    ### 干支合克与入库
      #### 干支相合（依据）
      #### 天干相克（依据）
      #### 地支入库（依据）
    ### 地支关系
  ## 神煞断语
    ### 简表神煞（字段展开）
  ## 日主概览
  ## 五行喜忌（调候与平衡）
    ### 五行比例
    ### 五行分数
    ### 天干分数
  ## 五行停匀与寒湿燥热（调候依据）
  ## 干支取象（原文）
  ## 命造格局（格局用神）
  ## 节气司令
  ## 干支关系

## 第二卷：后天运路（动态趋势）
  ## 运势分析
    ### 大运分析
    ### 流年
    ### 流月运势
    ### 小运

## 第三卷：民俗与建议（生活应用）
  ## 袁天罡称骨

体系归属：

输出块	体系归属	说明
基本资料（含真太阳时、节气）	八字排盘前置	出生时空、真太阳时、节气是八字排盘与月令判断的基础；若展示星座、星宿，只作历法/民俗辅助
八字排盘详情	八字主线	四柱、五行、天干地支、合克、入库、地支关系
神煞断语	八字辅助体系	属传统命理常见辅助，不等同于格局用神主线
日主概览	八字主线	日主、阴阳五行、强弱与坐支
五行喜忌（调候与平衡）	八字主线	五行比例、分数、调候与平衡
五行停匀与寒湿燥热（调候依据）	八字主线	月令气候、寒暖燥湿、调候依据
干支取象（原文）	八字经典辅助	干支象义，服务八字解释
命造格局（格局用神）	八字主线	格局、用神、调候取用
节气司令	八字主线	月令、人元司令与节气分野
干支关系	八字主线	干支合冲刑害破等结构关系
运势分析：大运、流年、流月、小运	八字动态主线	八字后天运路与应期分析
建除十二神	已退役为未来功能	属黄历/择日辅助，不再作为当前命理报告体系输出
紫微斗数 / 紫微基础	其他独立体系	紫微斗数独立于八字，需选择 ziwei 单独输出
紫微运限四化	其他体系	紫微大限、流年、流月、流日、流时
袁天罡称骨	综合八字民俗辅助	称骨法随默认 bazi 报告输出，不再单独作为体系选择

常用命令

bash scripts/bootstrap.sh --with-dev
bash scripts/preflight.sh --mode pure --bootstrap --pretty
bash scripts/preflight.sh --mode pure --bootstrap --smoke --output-file output/preflight-sample.json --pretty
bash scripts/preflight.sh --mode delivery --bootstrap --pretty
bash scripts/pure-analysis.sh --input-file input.json --output-file output/result.json --pretty
bash scripts/acceptance.sh --with-dev
bash scripts/delivery-smoke.sh --target api
bash scripts/serve-api.sh
bash scripts/delivery-smoke.sh --target bot --startup-timeout 8
bash scripts/production-readiness.sh --api-url https://your-domain.example --require-live-bot
bash scripts/clean-runtime.sh --dry-run
bash scripts/export-runtime.sh --output-parent /tmp/fatecat-export --mode lite
bash scripts/check-export-hygiene.sh /tmp/fatecat-export/fatecat

目录结构

fatecat/
├── AGENTS.md
├── README.md
├── SKILL.md
├── references/
│   ├── commands.md
│   ├── execution-playbook.md
│   └── troubleshooting.md
├── scripts/
│   ├── acceptance.sh
│   ├── check-export-hygiene.sh
│   ├── clean-runtime.sh
│   ├── delivery-smoke.sh
│   ├── export-runtime.sh
│   └── preflight.sh
└── scripts/project/
    ├── AGENTS.md
    ├── README.md
    ├── assets/
    │   └── docs/
    │       └── lifecycle/
    ├── modules/
    │   ├── fate_core/
    │   └── telegram/
    ├── runtime/
    └── tests/

根目录与 scripts/project/ 的边界：

• 根目录：skill 入口、预检、验收、导出、生命周期包装。
• scripts/project/：真实业务源码、运行时骨架、项目级文档真相源。
• scripts/project/assets/vendor/：外部成熟仓库快照，默认只读。
• scripts/project/runtime/：运行态数据，不回灌静态资产目录。

仓库卫生

默认卫生规则：

• 不提交 scripts/project/assets/config/.env。
• 不提交 .venv、.pytest_cache、.ruff_cache、.mypy_cache。
• 不提交或分发本地编辑器历史 .history/。
• 不分发 node_modules/。
• 不分发 __pycache__、*.pyc、*.pyo。
• 不把 scripts/project/modules/telegram/output/、运行态 .db / .sqlite 或本地 .env 放进导出包。
• 导出后必须运行 scripts/check-export-hygiene.sh。
• 旧部署包 scripts/project/assets/deploy/pack.sh 也会清理 .env、私钥、证书、SQLite、日志和常见凭证 JSON，避免把本地运行态打进 tarball。
• scripts/project/assets/vendor/ 保存完整外部快照，体积偏大属于当前复用完整源码能力的明确取舍；如需瘦身，必须先改成 manifest / Git LFS / 按需下载方案，不能直接删除运行依赖。

API 安全开关：

• FATE_CORS_ALLOW_ORIGINS：逗号分隔 CORS allowlist；默认空列表，不再默认 *。
• FATE_API_TOKEN / FATE_API_ADMIN_TOKEN：记录接口 admin token；admin 可访问全部记录。
• FATE_API_USER_TOKENS：用户级 token，格式为 user_id:token,user_id2:token2；用户 token 只能写入、读取、列出、删除自己的记录。
• 未配置任何 API token 时，记录接口返回“记录接口未启用”，避免公网误暴露。
• 公网生产前运行 bash scripts/production-readiness.sh --api-url <url> --require-live-bot，缺少真实外部环境时不得宣称 live 验收通过。

清理本地运行态：

bash scripts/clean-runtime.sh

导出并检查：

rm -rf /tmp/fatecat-export
bash scripts/export-runtime.sh --output-parent /tmp/fatecat-export --mode lite
bash scripts/check-export-hygiene.sh /tmp/fatecat-export/fatecat

文档地图

• SKILL.md：agent 如何接手、预检、执行、验收。
• references/index.md：参考文档导航。
• references/execution-playbook.md：标准执行链路。
• references/commands.md：命令速查。
• references/ops-pack.md：运维与加固。
• scripts/project/README.md：项目级产品说明与业务背景。
• scripts/project/assets/docs/reference/功能状态.md：标准报告与未来功能边界。
• scripts/project/assets/docs/reference/综合八字陈述服务加固.md：综合八字报告、节气 golden、evidence 与验收门禁。

免责声明

本项目及 AI 分析结果仅供传统文化研究、算法测试与娱乐参考。命理学非精密科学，命运掌握在自己手中。使用者因轻信或误读本程序结果而产生的任何心理、财务及生活决策后果，本开源项目及开发者概不负责。