Imported from tradecatlabs/fatecat (SKILL.md). Install upstream with npx skills add tradecatlabs/fatecat. Copyright stays with the author.

fatecat Skill

把 FateCat 从“仓库已存在”推进到“依赖就绪、健康通过、能真实执行测算 capability 并交付结果”。FateCat 是面向 Agent 与应用开发者的测算基础设施，提供统一的能力协议、可复现计算核心、证据化解释层和多端交付接口。本 skill 只编排当前仓库能力，不重写命理算法，不用文档替代真实命令证据。

When to Use This Skill

Trigger when any of these applies:

• 用户要生成八字 / 紫微等命理排盘结果，且结果需要落到 JSON 或 Markdown 文件。
• 用户要打开 Web HTML 页面录入出生日期、时间、地区、姓名并复制 Markdown。
• 用户要启动或验收 FastAPI、Telegram Bot、CLI 或 Agent 交付入口。
• 用户要首次安装仓库、修复虚拟环境、检查 pure / delivery 健康状态。
• 用户要发布、导出、审计、检查仓库卫生、检查隐私样例或验证 skill bundle。
• 用户要求“能不能生产复用”“上线前检查”“完整验收”“live Bot smoke”。

Not For / Boundaries

• 不在 tools/reference-repos/ 内魔改第三方算法源码；vendor 默认只读，除非任务明确是供应链治理。
• 不得新增第二套业务源码或旧路径 fallback；源码根是 domains/*/services/*，运行资产根是 infra/、contracts/、tools/ 和 domains/fate-analysis/data-products/。
• 不把缺少真实 token、真实 API URL、生产 CORS、远程服务器权限的 dry-run 说成生产 live 验证。
• 不在缺少 birthDateTime、gender、longitude、latitude 时直接执行纯分析。
• 不把未来功能塞回默认综合八字报告；紫微、黄历、梅花、六爻、奇门、大六壬、风水、姓名合婚等必须走独立体系契约。
• 不向用户前端展示除北京以外的真实地区样例；第一方示例统一使用北京 / 测试用户口径。

Quick Reference

1. 确认仓库位置

test -f SKILL.md && test -d domains && test -d governance && test -d references

2. 首次安装运行时

bash scripts/bootstrap.sh --with-dev

3. 标准纯分析预检

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

4. 预检并生成样例输出

bash scripts/preflight.sh --mode pure --bootstrap --smoke --output-file output/preflight-sample.json --pretty

5. 用输入文件生成 JSON

mkdir -p output
bash scripts/pure-analysis.sh --input-file input.json --output-file output/result.json --pretty

6. 用 JSON 字符串生成 JSON

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/result.json \
  --pretty

7. 启动 Web / API 前验收

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

Web 地址：

http://127.0.0.1:8001/web

8. 启动 Telegram Bot 前验收

bash scripts/preflight.sh --mode delivery --bootstrap --pretty
bash scripts/delivery-smoke.sh --target bot --startup-timeout 8
bash scripts/serve-bot.sh

9. 发布前完整验收

bash scripts/acceptance.sh --with-dev
bash scripts/acceptance.sh --with-dev --with-mingli-bench

完整验收包含 wheel clean-room、核心性能预算、全量测试、静态检查、交付 smoke 和导出包 smoke。内部 lite 运行包不等于公共分发包；公共发布还必须通过 vendor 许可证门禁。

10. 清理本地运行态

bash scripts/clean-runtime.sh

彻底重建虚拟环境时才加：

bash scripts/clean-runtime.sh --venv

11. 导出 lite skill 包并检查卫生

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

12. 生产就绪门禁

bash scripts/production-readiness.sh --api-url https://your-domain.example --require-live-bot

没有真实生产 URL、CORS allowlist、API token 和 Telegram token 时，只能记录为“外部连通验证待执行”。

13. 校验当前 skill

/home/lenovo/.codex/skills/auto-skill/scripts/validate-skill.sh /home/lenovo/.projects/fatecat --strict

Execution Logic

1. 先定位目标：纯分析输出文件走 pure；Web / API / Bot 走 delivery；发布交付走 acceptance；公网生产走 production-readiness。
2. 再补运行时：优先 bash scripts/preflight.sh --mode <pure|delivery> --bootstrap --pretty，不要手工拼散命令。
3. 再验输入：排盘必须有出生时间、性别、经纬度；前端示例必须使用北京 / 测试用户。
4. 再执行目标命令：生成文件、启动服务、导出 bundle 或跑门禁。
5. 最后复核证据：退出码、输出文件、健康检查、smoke 日志、导出包卫生、Git 状态。

Examples

Example 1: 首次接手仓库

• Input: 用户说“先检查这个 skill 能不能跑”。
• Steps:
  1. bash scripts/preflight.sh --mode pure --bootstrap --pretty
  2. bash scripts/health.sh --mode pure --json --pretty
  3. 必要时执行 bash scripts/acceptance.sh --with-dev
• Expected output / acceptance:
  • 虚拟环境创建成功。
  • CLI 可执行。
  • pure 健康检查通过。

Example 2: 生成排盘 JSON

• Input: 用户给出出生时间、性别、经纬度、姓名，要求保存结果。
• Steps:
  1. 检查字段包含 birthDateTime、gender、longitude、latitude。
  2. bash scripts/preflight.sh --mode pure --bootstrap --pretty
  3. bash scripts/pure-analysis.sh --input-file input.json --output-file output/result.json --pretty
• Expected output / acceptance:
  • 命令退出码为 0。
  • output/result.json 存在且可解析。
  • 输出不是空文件、报错栈或模型臆造文本。

Example 3: 启动 Web HTML 页面

• Input: 用户要浏览器输入出生日期、出生时间、出生地区、姓名，并复制 Markdown。
• Steps:
  1. bash scripts/preflight.sh --mode delivery --bootstrap --pretty
  2. bash scripts/delivery-smoke.sh --target api
  3. bash scripts/serve-api.sh
• Expected output / acceptance:
  • API smoke 通过。
  • /web 可访问。
  • 页面输出 Markdown，可复制。

Example 4: 发布前完整门禁

• Input: 用户说“提交前检查到能交付”。
• Steps:
  1. bash scripts/clean-runtime.sh
  2. bash scripts/acceptance.sh --with-dev
  3. git status --short --branch
• Expected output / acceptance:
  • acceptance 全部通过。
  • 未跟踪非忽略文件为 0。
  • 没有运行态、缓存、真实 .env 或数据库文件混入版本控制。

References

• references/index.md: 文档导航。
• references/execution-playbook.md: 标准执行顺序、模式判断和失败处理。
• references/commands.md: 命令入口与使用场景。
• references/io-contract.md: 输入输出契约。
• references/architecture.md: 企业根结构、skill 入口、包装脚本与 canonical runtime 边界。
• references/ops-pack.md: 运维包、delivery smoke 与生产边界。
• references/live-bot-verification.md: 真实 Telegram token 验证。
• domains/fate-analysis/data-products/calendar/solar_terms/golden/: 1900-2030 节气 golden 回归 fixture。
• contracts/fate/evidence_schema.json: 综合八字机器可读依据契约。
• contracts/fate/weight_policy.json: 综合八字核心、动态、辅助、民俗权重边界。
• contracts/fate/classics_rule_index.json: 典籍规则索引种子。
• references/stage-gates.md: 从可运行到可生产的阶段门禁。
• references/troubleshooting.md: 常见失败与修复路径。
• references/migration-plan.md: 当前目录迁移与根卫生口径。

Maintenance

• Sources:
  • scripts/bootstrap.sh
  • scripts/preflight.sh
  • scripts/health.sh
  • scripts/pure-analysis.sh
  • scripts/delivery-smoke.sh
  • scripts/export-runtime.sh
  • scripts/acceptance.sh
  • domains/fate-analysis/services/fate-core/src/fate_core/cli.py
  • domains/experience-delivery/services/fatecat-delivery/src/web_ui.py
  • domains/experience-delivery/services/fatecat-delivery/src/main.py
• Quality gate:
  • /home/lenovo/.codex/skills/auto-skill/scripts/validate-skill.sh /home/lenovo/.projects/fatecat --strict
  • bash scripts/preflight.sh --mode pure --bootstrap --pretty
  • bash scripts/acceptance.sh --with-dev
• Last updated: 2026-05-07
• Known limits:
  • delivery-smoke 的 Bot 检查默认是 dry-run，不等于 Telegram live。
  • 生产 live 验证必须依赖真实外部 URL、token、CORS 与网络权限。
  • vendor 体积偏大是完整复用外部源码快照的取舍，不能无门禁删除。