FateCat

FateCat 是面向 Agent 与应用开发者的测算基础设施，提供统一的能力协议、可复现计算核心、证据化解释层和多端交付接口。

统一能力协议 × 可复现计算核心 × 证据化解释层 × CLI / Web / Telegram / FastAPI / Agent 多端交付接口

立即免费使用 FateCat Web 工作台

项目总览 · Skill 仓库 · 模式选择 · 架构 · 快速开始 · Web HTML · HF 免费部署 · 报告结构 · 常用命令 · 目录结构 · 仓库卫生 · 文档地图 · 免责声明

Warning

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

Tip

FateCat 是 TradeCat Labs 的测算基础设施项目。推荐工作流：先由成熟算法或生产 capability 完成确定性计算，再把结构化结果交给 AI / Agent 深度分析，尽量减少模型乱编。

• DEX Screener: https://dexscreener.com/bsc/0x8a99b8d53eff6bc331af529af74ad267f3167777
• X: https://x.com/tradecatlabs
• GitHub: https://github.com/tradecatlabs
• Hugging Face: https://huggingface.co/tradecatlabs
• FateCat Repo: https://github.com/tradecatlabs/fatecat
• CA: 0x8a99b8d53eff6bc331af529af74ad267f3167777

AI / Agent 机器发现入口

资源	用途
项目说明与常见问题	项目定位、实时能力、证据边界、Agent 接入步骤与可引用 FAQ
综合八字能力说明	综合八字输入、引擎、证据、范围、边界与独立 FAQ
紫微斗数能力说明	紫微斗数输入、引擎、证据、范围、边界与独立 FAQ
llms.txt	产品身份、能力状态、输入契约、证据来源、高意图问答和引用边界
robots.txt	公开抓取策略与 sitemap 发现
sitemap.xml	Web、OpenAPI 与机器资源索引
OpenAPI	当前 HTTP 请求和响应契约
Capability Registry	production 与 planned 能力的实时真相源
GEO Query Set	固定 AI 问答采样题集、预期事实、官方来源与禁止声明；不包含平台结果

GEO 方法、当前基线、指标口径和复测命令见 GEO 发现与引用治理。项目不承诺任何 AI 平台必然收录、引用或推荐；公开事实必须能回指代码、契约、测试或运行端点。

项目总览

FateCat 是面向 Agent 与应用开发者的测算基础设施，提供统一的能力协议、可复现计算核心、证据化解释层和多端交付接口。它不是让 AI 直接“脑补排盘”，而是把“确定性计算”和“解释交付”拆开：

1. 成熟排盘系统、外部算法或生产 capability 负责可复现结构化计算。
2. FateCat 负责统一能力协议、统一字段、统一证据链、统一输出和统一交付入口。
3. AI / Agent 只基于稳定 JSON 或标准 Markdown 做解释、总结与后续任务。

维度	说明
项目角色	面向 Agent 与应用开发者的测算基础设施
当前形态	企业级系统仓库；源码、运行资产、契约、治理和导出入口均从 canonical roots 解析
推荐链路	成熟算法 / capability provider -> FateCat capability executor -> AI / Web / Telegram / API / Agent
核心真相源	目标为 contracts/fate/ 定义字段与 capability 契约，tools/reference-repos/ 或供应链 manifest 保留成熟算法快照
明确边界	不让 AI 直接口算排盘，不在 vendor 快照内魔改外部源码；复用先于自写

企业级仓库

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

• 单-skill 仓库入口：SKILL.md 定义 agent 如何接手、安装、检查、执行。
• 企业治理层：governance/ 记录标准、门禁、迁移账本、baseline evidence、任务和风险。
• 领域服务层：domains/fate-analysis/services/fate-core/ 与 domains/experience-delivery/services/fatecat-delivery/ 登记生产候选服务契约。
• 统一执行包装层：根 scripts/ 把源码仓库常用动作封成稳定入口。
• 可导出 bundle 源：可把当前 skill 连同运行时骨架导出为独立交付包。

生产候选源码当前归位：

• domains/fate-analysis/services/fate-core/src/：测算计算、能力执行与解释证据核心。
• domains/experience-delivery/services/fatecat-delivery/src/：Web HTML、Telegram、FastAPI、报告生成与交付适配。

企业根运行资产当前归位：

• infra/environments/local/：本地配置模板与 branding。
• infra/databases/ 与 infra/runtime/local-state/：数据库 schema 与本地运行态目录。
• contracts/fate/：capability、profile、evidence、policy 和典籍规则契约。
• domains/fate-analysis/data-products/：可提交数据产品与 golden fixtures。
• tools/reference-repos/：第三方成熟算法快照，默认只读。

旧组织退役证据见 governance/migration/fatecat-enterprise-directory-mapping.md 与 governance/tasks/project-history/。

模式选择

场景	推荐入口	输出形态	是否要求 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	企业根自举入口	非交互 CLI / 健康检查	纯分析否，Bot 是	适合批处理与自动部署
用户自己免费云端部署	HF Duplicate / GitHub Actions	Hugging Face /web	否	不用本机保活；详见 docs/deployment/huggingface-space.md

架构

flowchart LR
    A[成熟算法 / capability provider] --> B[外部成熟算法 tools/reference-repos]
    B --> C[fate-core 测算能力执行服务 domains/fate-analysis]
    F[capability / profile / evidence contracts/fate] --> C
    G[配置 / 数据 / schema infra + data-products] --> 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

Loading

推荐工作流：

成熟算法 / capability provider
        ↓
FateCat capability executor 输出稳定 JSON / Markdown
        ↓
AI 基于结构化字段和 evidence 做解释
        ↓
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. 本地 CI/CD profile

bash scripts/local-ci.sh --profile quick
bash scripts/local-ci.sh --profile full
bash scripts/local-ci.sh --profile container
bash scripts/local-ci.sh --profile public-service

local-ci.sh 只调用本仓脚本，不调用 GitHub Actions；quick 会检查 wheel clean-room、核心性能预算和关键回归，full 复用本地 scripts/acceptance.sh --with-dev，container 执行真实 Docker 容器 smoke，public-service 执行公网服务静态准入门禁。GitHub quick.yml 在 pull request 与 main push 自动执行同一个 quick profile。

公开 Web 工作台发布前使用：

bash scripts/public-release-gate.sh --api-url https://tradecatlabs-fatecat.hf.space

该门禁仍只调用本地脚本：quick CI、公开发布策略检查、公共导出许可检查、delivery smoke、生产静态准入和可选线上 /health / /ready / /metrics。GitHub Acceptance 和容器工作流只保留手动触发，避免 push 自动跑重型验收。

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

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

5. 做完整验收

bash scripts/local-ci.sh --profile full

完整验收覆盖 shell 语法、strict skill 校验、纯分析 smoke、vendor health、wheel clean-room、核心性能预算、全量 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> 展示、复制按钮只做渐进增强。公开入口默认使用异步报告任务：浏览器提交后先拿到 jobId，后端有界队列生成报告，页面轮询完成后回到 /web?jobId=... 展示 Markdown。

面向 AI、Agent 和抓取器的公开端点、Web 字段契约、地点解析、任务协议与风险边界集中在 llms.txt，线上入口为 GET /llms.txt；Web 顶部表格只保留人类需要的项目和使用摘要。

项目归属块提供 免费 AI 分析入口（Gemini Gem） 外链。该入口用于用户复制 Markdown 报告后自行打开 Gemini Gem 分析；FateCat 不会自动把排盘输入或报告发送给 Gemini。

启动 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
地区模式	是	domestic / overseas / coordinates
出生地区	是	地点名称或 WGS84 lng,lat；文本重名时必须从候选中选择稳定地点 ID
稳定地点 ID	条件必填	搜索候选后使用 cn:<code> 或 geonames:<id>；直接坐标模式由服务端生成
出生时间口径	是	local_civil / beijing_time / utc；不得默认猜测
DST 重复时刻	条件必填	夏令时回拨产生重复当地时间时选择 earlier / later
性别	是	male / female；现有排盘逻辑必需，不能默认猜测
输出体系	否	当前可用：bazi / ziwei；默认 bazi，每次只输出一个已实现体系
姓名	否	为空时报告标题使用“命主”

地点规则：国内与海外候选统一返回稳定 ID、WGS84 坐标、IANA 时区和坐标精度。重名、模糊地点、DST 缺口或重复时刻均显式报错；经纬度、时区和规范化时间用于后端计算，不写入免费 Space 记录库。

报告任务 API：

POST /api/v1/report/jobs
GET /api/v1/report/jobs/{job_id}
POST /api/v1/report/jobs/web

免费公开版使用进程内有界队列，默认 1 个 worker、最多 20 个等待任务、结果 TTL 30 分钟。它解决浏览器同步等待和平台超时问题；如果自部署需要多副本高并发、跨重启保留任务或独立 worker 扩容，应把任务后端升级为 Redis/RQ、Celery 或同等级外部队列。

Hugging Face 免费 Space

FateCat 提供 Hugging Face Docker Space 分发模板，目标是让用户直接通过 Web 工作台使用 /web。免费公共演示默认关闭记录存储，不需要 Telegram Bot token，也不写入本地数据库。

用户自助部署有两条无需本机服务器的路径：

• HF 网页复制：打开 https://huggingface.co/spaces/tradecatlabs/fatecat，右上角三个点选择 Duplicate this Space，按页面提示选择 owner、Space name、visibility 和 CPU Basic。
• GitHub 网页部署：fork https://github.com/tradecatlabs/fatecat，在 fork 仓库添加 HF_TOKEN secret，然后到 Actions -> Deploy Hugging Face Space -> Run workflow，填写 <你的HF用户名>/fatecat。该部署 workflow 是手动触发，不会因为 push 自动发布。

完整说明见 docs/deployment/huggingface-space.md。

本地 hf CLI 部署：

hf auth login
bash scripts/hf-space-deploy.sh --space tradecatlabs/fatecat

只生成并检查分发包，不上传：

bash scripts/hf-space-deploy.sh --dry-run --bundle-dir /tmp/fatecat-hf-space

部署脚本默认校验当前 hf 认证必须属于 tradecatlabs 用户或显示 tradecatlabs org 权限，避免误发到个人账号。Space 模板位于 infra/huggingface-space/，运行端口为 7860，默认环境变量包含：

FATE_RECORDS_ENABLED=0
FATE_SERVICE_PORT=7860
FATE_MAX_INFLIGHT_CALCULATIONS=1
FATE_REPORT_JOB_QUEUE_SIZE=20
FATE_REPORT_JOB_WORKERS=1
FATE_REPORT_JOB_TTL_SECONDS=1800
FATE_TELEGRAM_WEBHOOK_ENABLED=0

可选 Telegram 消费端与 FastAPI 运行在同一进程，通过 POST /api/v1/integrations/telegram/webhook 接收 Update，并继续复用 Bot 现有 calculation_service -> fate-core -> report_generator 链路。不要把 Space 改为 start.py both。 启用时在 Space Secrets 配置 FATE_BOT_TOKEN、FATE_TELEGRAM_WEBHOOK_SECRET，再把 Variable FATE_TELEGRAM_WEBHOOK_ENABLED 设为 1；Webhook URL 默认从 SPACE_HOST 推导。

标准 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 输出块顺序固定如下：

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

**TradeCat Labs 实验室**（纯文本品牌与赞助块，无 `#` 标题）

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

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

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

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

体系归属：

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

常用命令

bash scripts/bootstrap.sh --with-dev
bash scripts/local-ci.sh --profile quick
bash scripts/local-ci.sh --profile full
bash scripts/local-ci.sh --profile container
bash scripts/local-ci.sh --profile public-service
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/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/hf-space-deploy.sh --dry-run --bundle-dir /tmp/fatecat-hf-space
bash scripts/hf-space-deploy.sh --space tradecatlabs/fatecat
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
├── apps/
├── ai/
├── domains/
│   ├── fate-analysis/
│   │   └── services/fate-core/
│   └── experience-delivery/
│       └── services/fatecat-delivery/
├── platform/
├── infra/
├── contracts/
├── catalog/
├── governance/
├── shared/
├── tools/
├── docs/
├── tests/
├── references/
│   ├── commands.md
│   ├── execution-playbook.md
│   └── troubleshooting.md
├── scripts/
│   ├── acceptance.sh
│   ├── check-export-hygiene.sh
│   ├── clean-runtime.sh
│   ├── delivery-smoke.sh
│   ├── export-runtime.sh
│   ├── local-ci.sh
│   └── preflight.sh

企业根 canonical 边界：

• 企业根：服务契约、catalog、governance、目标 docs/contracts/infra/tools 归位。
• domains/*/services/*：生产候选服务源码、服务契约和测试入口。
• 根 scripts/：预检、验收、导出、结构门禁和卫生门禁。
• vendor 快照：默认只读；后续只做供应链登记与路径归位，不魔改源码。

仓库卫生

默认卫生规则：

• 不提交 infra/environments/local/.env。
• 不提交 .venv、.pytest_cache、.ruff_cache、.mypy_cache。
• 不提交或分发本地编辑器历史 .history/。
• 不分发 node_modules/。
• 不分发 __pycache__、*.pyc、*.pyo。
• 不把 domains/*/services/*/output/、运行态 .db / .sqlite 或本地 .env 放进导出包。
• 导出后必须运行 scripts/check-export-hygiene.sh。
• 内部 lite 运行包与公共分发包使用不同门禁：公共发布必须追加 --public，任何 distributionAllowed != true 的 vendor 都会阻断。
• 当前 bazi-1 与 sxwnl 缺少可确认的上游分发许可证，因此不得把包含它们的内部运行包称为可公开分发包。
• tools/reference-repos/ 保存完整外部快照，体积偏大属于当前复用完整源码能力的明确取舍；如需瘦身，必须先改成 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 时，记录接口返回“记录接口未启用”，避免公网误暴露。
• FATE_MAX_REQUEST_BYTES：应用层请求体上限；同时建议在 Nginx / Traefik / Cloudflare 等边缘层配置 body limit。
• FATE_RATE_LIMIT_PER_MINUTE：应用内单 IP 每分钟限流；仅适合单副本兜底。
• FATE_DEPLOYMENT_REPLICAS + FATE_RATE_LIMIT_BACKEND：多副本公网服务必须把 FATE_RATE_LIMIT_BACKEND 设为 gateway、redis、waf 或 external，不能继续用单进程 memory。
• FATE_TRUST_PROXY_HEADERS / FATE_ENABLE_HSTS：生产反向代理后建议开启；确保直连端口只允许可信代理访问。
• 公网生产前运行 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：运维与加固。
• docs/reference-materials/README.md：项目级产品说明与业务背景归位副本。
• docs/reference-materials/reference/功能状态.md：标准报告与未来功能边界。
• docs/reference-materials/reference/综合八字陈述服务加固.md：综合八字报告、节气 golden、evidence 与验收门禁。

免责声明

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