fatebridge 0.1.1

面向应用与 AI Agent 的传统术数与占星计算引擎

简体中文 · English

快速开始 · 接入 Agent · 接入应用 · 文档中心 · 参与贡献

FateBridge 将八字、紫微、中国占术、西方占星与风水规则组织成可在本地运行的 Python 计算工具。通过 MCP 为 Agent 提供计算依据，通过 REST 接入应用，也可以用 CLI 在终端直接调用。

核心特性

• 中西多体系，统一调用：覆盖八字、紫微、中国占术、西方占星与风水，将不同体系的计算组织成结构化工具，供应用与 AI Agent 使用。
• 围绕问题组织咨询：Onda 按事业、财务、关系、学习等主题选择相关方法与时间层，把计算结果联系到具体问题，追问沿用已有相关依据。
• 开源、本地运行，灵活接入：通过 MCP 接入 Agent，通过 REST 接入应用，也可直接使用 CLI；支持按需取数与同次结果的完整交付。

支持的能力

当前提供 86 个业务 REST 路由、87 个 FastMCP 工具，覆盖 13 family / 87 工具。中央目录含 88 条记录，CLI 可执行其中 87 条；各端的名称与请求形态有差异，见三端能力边界。逐工具的实现、精度与限制见算法覆盖矩阵。

快速开始

需要 Python 3.10+ 与 uv，当前 CI 覆盖 Python 3.10–3.13。

安装

从 PyPI 安装最新版独立命令工具：

本页描述当前开发分支，尚未发布的变更见 CHANGELOG；体验最新技能与接口范围时，请使用源码安装。

uv tool install fatebridge

安装后可使用 fatebridge、fatebridge-api 和 fatebridge-mcp 三个命令。需要运行当前仓库或修改源码时，使用源码安装；Onda 技能随 Git 仓库分发，当前 wheel 不包含技能目录。

完成第一次计算

CLI 不需要启动服务。以下使用虚构资料，只返回日主的三个字段：

fatebridge bazi_birth \
  --birth-year 1990 --birth-month 5 --birth-day 15 \
  --birth-hour 10 --birth-minute 30 --gender 男 \
  --birth-place 北京 --birth-timezone Asia/Shanghai \
  --fields bazi_birth.day_master.stem \
    bazi_birth.day_master.element bazi_birth.day_master.polarity \
  --strict-fields

响应中的业务数据如下，另附 run_metadata 计算回执：

{
  "bazi_birth": {
    "day_master": {
      "stem": "庚",
      "element": "金",
      "polarity": "阳"
    }
  }
}

继续探索工具与输入契约：

fatebridge discover --family bazi
fatebridge describe bazi_birth --detail input

安装与 Windows 说明、环境变量和星历配置见快速入门。

接入 Agent

MCP 使用 stdio，由 Codex、Claude 或 Cursor 等 host 启动本地子进程。先诊断安装与连接，例如从事业场景开始：

fatebridge doctor --mcp --scenario onda-shiye

诊断会验证依赖、独立 MCP 进程、工具发现、资源读取和一条虚构计算。Codex 用户可执行输出中的 codex.add_command 注册连接；它使用当前安装环境的绝对路径。其他 host 可按其配置格式填写返回的 codex.config 中的 command、args 与 env。

注册后在新聊天中确认工具可见，即可用日常语言提问，例如：

请用 FateBridge 看看我的事业。我正在考虑换工作，也想了解自己适合承担哪类职责。以下是虚构体验资料：男，公历 1990 年 5 月 15 日上午 10:30，北京出生，按当地钟表时间记录。请分析 2026 年，用普通人能懂的话讲清依据。

--scenario onda-shiye 将连接限制在事业场景的工具范围；需要其他主题时调整场景或清空筛选并重启连接。Onda 技能按生活主题、问题任务与时间范围组织咨询，专题综合可使用多视角，追问保留已有相关结果。

完整注册步骤、配置格式与对话示例见 Codex 使用指南；其他 host 的配置见 Agent 接入指南。

接入应用

启动本机 REST 服务。以下为 macOS / Linux 命令，Windows 配置见快速入门：

API_HOST=127.0.0.1 fatebridge-api

在另一个终端发起请求：

curl http://localhost:8010/health

curl -X POST http://localhost:8010/api/cn/bazi/birth \
  -H 'Content-Type: application/json' \
  -d '{
    "birth_year": 1990, "birth_month": 5, "birth_day": 15,
    "birth_hour": 10, "birth_minute": 30, "gender": "男",
    "birth_place": "北京", "birth_timezone": "Asia/Shanghai",
    "use_true_solar_time": true
  }'

/health 返回 {"status":"healthy"}，命盘请求的业务数据位于 bazi_birth，另附计算回执。浏览器打开 Swagger UI 查看请求 Schema 并试调接口。

监听地址默认 0.0.0.0，上述命令将其限制为本机。启用 FATEBRIDGE_API_KEYS 后，业务请求还需发送 X-API-Key（默认头名）；配置与部署边界见快速入门和安全策略。Python 与 JavaScript 调用示例见接入指南。

结果与复现

保留原输入与 run_metadata，并核对时区、太阳时策略、分析时间和引擎版本。回执描述的是计算口径，复现还需要相同的实现、数据与运行环境。

• 只取需要的内容：使用 fields 投影结果，设置 strict_fields=true 拒绝无效字段路径。
• 完整导出从首次调用开始：需要完整 JSON 或全部时间线时，首次调用设置 fields=null，保留默认响应预算。MCP 默认预算为 8192 字符，超限后通过 result_delivery 读取同一 run；摘要投影不能恢复未选字段。详见完整结果交付与同次导出。
• 按实际返回判断精度：核心星盘支持本地星历与近似路径，核对 chart_profile.ephemeris_model 和 run_metadata.engine_is_approximate。西占推运、事件与生命周期工具缺少所需后端依赖时明确报错。星历数据单独获取，见星历数据与精度。

文档导航

全部文档及维护职责见文档中心，版本变化见 CHANGELOG。

参与贡献

欢迎改进算法、接口、测试、文档和场景技能。源码开发使用锁定的 uv 环境，无需手动激活虚拟环境：

git clone https://github.com/thomas-yanxin/FateBridge.git
cd FateBridge
uv sync --locked --extra dev
uv run --locked --extra dev fatebridge list

纯文档改动可先运行：

uv run --locked --extra dev python scripts/check_docs.py
uv run --locked --extra dev python -m pytest -q \
  tests/test_doc_tool_counts.py tests/test_scenario_routing_coverage.py

代码改动还需运行领域测试及 CI 对应检查，详见开发指南。提交与 PR 流程见贡献指南。报告问题或提出功能建议请到 Issues；安全问题按 SECURITY.md 私下报告。

使用范围与许可

FateBridge 的计算验证关注历法、数值与所选规则的一致性。传统解释与分数用于文化参考，分数不代表现实成功概率，软件测试通过也不证明预测有效性。咨询不提供生死寿命、灾祸断言、临床诊断治疗与医疗择时，传统健康内容不作为医学结论；详见咨询硬边界。

项目提供后端、CLI 与技能资料，前端和部署由接入方负责。代码采用 Apache-2.0，第三方组件与来源见 NOTICE，依赖和星历数据遵循各自许可。

返回顶部 ↑