FateBridge

一个人问 AI「我适合怎样的工作」，背后可能涉及出生资料、历法、不同传统的规则，还有这个人眼下面临的真实选择。回答可以写得流畅，但流畅本身不能告诉我们：盘是怎么算的，依据来自哪里，哪些地方仍有疑问。

FateBridge 想解决的是其中可以被计算和核对的部分。它是面向开发者与 AI Agent 的开源工具包，将八字、紫微斗数、西方占星、占卜与风水接入 AI 应用，为自我认识、事业与关系探索、阶段变化及空间布局等咨询提供传统文化视角的计算依据。

通过 MCP、REST API 和 CLI，应用可以调用同一套领域计算，读取结构化结果，核对时间口径、精度与规则范围。Onda 咨询技能指导 Agent 从用户的问题出发选择方法与时间层，分开表达计算事实、传统解释和现实建议。

计算服务在本地运行，无需 LLM API Key。自然语言对话由你选择的 Agent 客户端与模型提供；项目提供后端和咨询技能，前端由接入应用实现。

目录

• 为什么使用 FateBridge
• 支持的能力
• 技术栈与运行前提
• 快速开始
• 架构与项目结构
• MCP 部署与 Onda 技能
• REST API
• 配置、结果与精度
• 开发与测试
• 部署与升级
• 常见问题
• 文档导航
• 参与贡献
• 使用范围与许可

为什么使用 FateBridge

• 先理解问题，再选择依据：用户可以直接问「我有哪些做事特点」「我们有哪些磨合点」，并说明已知资料。Onda 指导 Agent 选择相关依据、组织解读和追问，无需用户先掌握工具名或接口字段。
• 让依据可以被追问：领域引擎提供计算数据，各工具按实际能力给出时间口径、精度、规则来源与覆盖说明；Onda 指导解读保留分歧和未知。读者可以追问依据，开发者也有路径核对结果。
• 把计算接入现有应用：用 MCP 连接 AI 助手，用 REST 集成产品，或用 CLI 执行计算。三端共享请求校验、工具目录与错误格式，但各端的公开范围仍需分别核对。
• 掌握运行环境：安装依赖并准备所需星历后，本地计算不依赖在线占算服务。CLI 可单次执行，MCP 可由客户端启动，REST 可独立部署；对话客户端与模型由你选择。

支持的能力

当前源码提供 91 个业务 REST 路由、92 个 FastMCP 工具，覆盖 13 family / 92 工具。中央目录含 93 条记录，CLI 可执行其中 92 条。各端的名称与公开范围见三端能力边界，逐项实现与限制见算法覆盖矩阵。

新增人类图：太阳88°双时刻、门线细分、通道、类型与权威，保留原典数值分歧和四项独立验收状态。

印度占星已提供 Lahiri 九曜、星宿四分段、D1／D9／D10、独立宫主／尊贵／相位规则与 Vimshottari 主运／次运，详见计算范围、可复制示例与验证。

技术栈与运行前提

实际依赖范围见 pyproject.toml，源码开发的解析版本由 uv.lock 固定。

首次使用需要联网安装依赖；下载外部星历时也需要网络。源码安装另需 Git。无需配置数据库、Redis、前端构建或 LLM API Key；大结果交付会按需写入本机私有临时文件，见结果与精度。

快速开始

0. 准备 uv

尚未安装 uv 时，可按 uv 官方安装说明选择安装方式。macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

重新打开终端并运行 uv --version 确认安装。包要求 Python 3.10+，当前 CI 覆盖 3.10–3.13。下面的工具安装显式选择 Python 3.12，源码通过 .python-version 选择 3.12；缺少该解释器时 uv 可自动下载。

1. 安装

只使用已发布的 CLI、REST 或 MCP，从 PyPI 安装独立工具环境：

uv tool install --python 3.12 fatebridge
fatebridge doctor

安装提供 fatebridge、fatebridge-api、fatebridge-mcp 三个命令。若终端找不到命令，运行 uv tool update-shell 后重新打开终端。

需要当前分支功能、Onda 技能或参与开发时，使用源码安装：

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

源码命令使用 uv run --locked --extra dev 前缀；下文无前缀的 fatebridge 命令面向独立工具安装。无需同时安装两种版本。本文描述当前开发分支，已发布包以对应标签的文档为准，未发布变化见 CHANGELOG。wheel 不包含 Onda 技能目录，仅连接 MCP 不会自动安装这些技能。

2. 完成第一次计算

CLI 无需启动服务。以下使用虚构资料，macOS / Linux 可直接执行；PowerShell 多行命令见部署指南：

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 --no-include-snapshot-text

退出码为 0 时，响应包含以下业务数据及 run_metadata 回执：

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

3. 选择接入方式

4. 查找工具与请求格式

用运行环境中的实际 Schema 确认参数，避免从不同接口或旧示例复制字段：

fatebridge discover --family bazi
fatebridge describe bazi_birth --detail input
fatebridge scenarios --scenario onda-shiye

源码用户为每条命令加 uv run --locked --extra dev。describe 返回输入定义与示例；省略 --detail input 时还返回输出合同。REST 可通过 GET /api/tools 查询目录，MCP 提供发现资源，详见能力发现。

架构与项目结构

三种接口通过中央目录绑定到领域服务，复用执行、输出校验和运行回执，再由各传输层处理协议与结果交付：

flowchart LR
    REST[REST / FastAPI] --> Execution[共享执行与输出校验]
    MCP[MCP / FastMCP] --> Execution
    CLI[CLI / argparse] --> Execution
    Execution --> Services[领域服务与专题分析]
    Services --> Core[历法与领域计算]
    Core --> Data[规则 JSON / 本地星历]
    Catalog[ToolSpec 中央目录] -.-> REST
    Catalog -.-> MCP
    Catalog -.-> CLI

FateBridge/
├── src/fatebridge/
│   ├── api.py / mcp_server.py / cli.py  # 三端入口
│   ├── application/                   # 发现、绑定、执行、投影与结果交付
│   ├── transports/                    # REST / MCP 协议注册
│   ├── services/catalog/              # 分领域工具声明
│   ├── services/                      # 领域编排与运行回执
│   ├── analysis/                      # 专题与复合分析
│   ├── core/                          # 算法、请求与输出模型
│   ├── data/                          # 随包规则与知识 JSON
│   └── utils/                         # 地点、时区、太阳时与文件等公共能力
├── skills/                            # Onda 咨询流程与共享资料
├── .agents/skills/                     # 项目技能发现入口
├── tests/                             # 领域、三端合同与回归测试
├── scripts/                           # 文档、生成合同与审计工具
├── docs/                              # 使用、部署、方法与开发指南
├── .env.example                       # 可选运行配置模板
├── pyproject.toml / uv.lock            # 包定义与开发锁文件
└── .github/workflows/                  # CI 与 PyPI 发布流程

以 bazi_birth 为例：参数经请求模型校验后，由 ToolSpec 绑定领域服务；共享执行层校验业务输出并附加 run_metadata，最后投影字段、处理快照和响应预算。三端复用计算，但路由、参数形状和公开范围仍以各端 Schema 为准。分层职责、重放与扩展流程见架构说明。

MCP 部署

本地 MCP：由客户端启动 stdio 进程

这是桌面 Agent 的直接接入方式。无需启动 REST、开放端口或提前运行 fatebridge-mcp。客户端根据配置启动子进程，通过标准输入输出通信；手工运行后等待输入属于正常行为。

先在选定的安装环境验证 MCP：

# PyPI 工具安装
fatebridge doctor --mcp

# 源码安装：在仓库根目录运行
uv run --locked --extra dev fatebridge doctor --mcp

二选一即可。ok=true 表示依赖、独立进程初始化、工具发现、资源读取和一条虚构计算通过。记录输出中的 executable 绝对路径，作为下面配置的 command；它指向已安装 FateBridge 的 Python，不依赖桌面客户端的 PATH 或工作目录。

Codex

将以下配置合并到 ~/.codex/config.toml，替换解释器路径；已有 fatebridge 条目时编辑原条目：

[mcp_servers.fatebridge]
command = "/absolute/path/to/python"
args = ["-m", "fatebridge.mcp_server"]
startup_timeout_sec = 30
tool_timeout_sec = 60

[mcp_servers.fatebridge.env]
FATEBRIDGE_MCP_FAMILIES = ""
FATEBRIDGE_MCP_SCENARIOS = ""
PYTHONUTF8 = "1"

也可执行 doctor 返回的 codex.add_command 自动注册；该命令使用当前安装的绝对路径。桌面版与终端可能有不同 Codex CLI，优先使用 doctor 确认的路径。注册只需选择一种方式；细节见 Codex 指南与 Codex 官方配置说明。

Claude Desktop / Cursor

将下面的 fatebridge 条目合并到客户端的 mcpServers，保留已有服务并替换解释器路径：

{
  "mcpServers": {
    "fatebridge": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "fatebridge.mcp_server"],
      "env": {
        "FATEBRIDGE_MCP_FAMILIES": "",
        "FATEBRIDGE_MCP_SCENARIOS": "",
        "PYTHONUTF8": "1"
      }
    }
  }
}

Claude Desktop 的配置文件为 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json。Cursor 使用项目级 .cursor/mcp.json 或用户级 ~/.cursor/mcp.json；Cursor 的 stdio 条目还应加入 "type": "stdio"。

Windows 的解释器示例为 C:\path\to\FateBridge\.venv\Scripts\python.exe，JSON 中反斜杠写成 \\。完整 PowerShell 与配置示例见 Windows 部署。

确认客户端可用

保存配置后重新加载 MCP 连接；必要时重启客户端并打开新聊天，检查 FateBridge 工具是否可见，再用虚构资料试调：

请使用 FateBridge，计算男、公历 1990 年 5 月 15 日上午 10:30、北京出生的八字，只解释日主的传统含义。

看到实际工具调用并成功返回，才完成客户端接入。配置存在或 doctor 通过均不能替代这一步。

默认公开全部工具。需要减小工具范围时设置 FATEBRIDGE_MCP_SCENARIOS=onda-shiye（事业），或 FATEBRIDGE_MCP_FAMILIES=fengshui（风水）；两个筛选取交集，空值表示不限制。修改后重启 MCP。场景列表可用 fatebridge scenarios 查询。

topic 开关由本次源码更改提供，发布前请使用源码环境。不支持延迟加载的客户端可同时设置场景与 FATEBRIDGE_MCP_TOOL_SCOPE=topic，仅公开主题直接工具和知识支撑；默认 complete 还包含条件依赖。topic 模式会在场景 availability 中标出未公开分支，需要这些技法时切回 complete。可用 uv run --locked --extra dev fatebridge doctor --mcp --scenario onda-shiye --tool-scope topic 验证。支持工具搜索的宿主可保留 complete 并按需加载；OpenAI 的少量初始工具建议不是服务器总数上限。

HTTP MCP

支持 URL 的客户端可通过 FastMCP 运行同一个 app。以下是源码安装方式，在仓库根目录启动并保持进程运行：

uv run --locked --extra dev fastmcp run src/fatebridge/mcp_server.py:app \
  --transport http --host 127.0.0.1 --port 8011 --path /mcp

MCP URL 为 http://127.0.0.1:8011/mcp。fatebridge-mcp 入口本身仍使用 stdio；HTTP 参数属于 FastMCP runner。REST 的 8010 端口与 MCP 的 8011 端口是两个独立服务。

远程机器可保持监听回环地址，通过 SSH 隧道接入。完整 URL 配置、协议验证和常驻进程示例见 MCP 部署指南。REST 的 FATEBRIDGE_API_KEYS 不保护 MCP；公网服务需要另行配置 TLS、MCP 鉴权与访问限制，当前示例不提供多租户隔离。

使用 Onda 咨询技能

MCP 提供计算工具，Onda 提供按问题组织咨询的技能。使用源码仓库作为 Codex 项目时，仓库的 AGENTS.md 与 .agents/skills/ 提供项目指导和技能入口；在新聊天确认发现状态。其他客户端需要按其技能机制加载 skills/ 中的内容，不会因 MCP 连接自动获得这些文件。详见 Onda 技能索引。可按插件构建指南生成本地可安装包，携带共享引用、当前后端源码及锁定依赖清单，并用来源散列核对；首次启动需下载目标平台依赖，宿主安装另行验收。

ModelScope 入口：FateBridge MCP Server · Onda Skills 合集。平台接入按对应页面说明操作，本地安装与配置按本文流程进行。

REST API

安装后启动本机服务。macOS / Linux：

API_HOST=127.0.0.1 fatebridge-api
# 源码安装：API_HOST=127.0.0.1 uv run --locked --extra dev fatebridge-api

Windows PowerShell：

$env:API_HOST = "127.0.0.1"
fatebridge-api

另开终端检查服务并执行与 CLI 相同的虚构计算：

curl --fail http://127.0.0.1:8010/health
curl --fail http://127.0.0.1:8010/ready
curl --fail 'http://127.0.0.1:8010/api/cn/bazi/birth?fields=bazi_birth.day_master&strict_fields=true&include_snapshot_text=false' \
  -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"
  }'

/health 返回 {"status":"healthy"}；命盘结果位于 bazi_birth.day_master，另附 run_metadata。/ready 表示必需检查就绪，不等于所有算法或星历均已验证。Swagger UI可查看 Schema 与试调请求。

监听默认值为 0.0.0.0:8010，上例显式限制为本机。共享部署前设置 FATEBRIDGE_API_KEYS=client:replace-with-a-secret，业务请求发送 X-API-Key: replace-with-a-secret，并在网关处理 TLS、访问和请求速率。密钥不提供用户账户或结果所有权隔离；/health、/ready、/metrics 与接口文档等运维路径免鉴权，详见安全策略。

配置、结果与精度

环境变量

基础 CLI 计算无需 .env。源码 API / MCP 可按需复制模板（macOS / Linux；已有文件时保留）：

cp -n .env.example .env

源码 API / MCP 会读取仓库根目录 .env，进程环境变量优先；文件只解析简单 KEY=value、包裹引号和整行注释，不执行 shell 展开。CLI 不自动读取 .env。独立工具安装请在启动器或客户端 env 中显式注入配置，修改后重启相应服务。加载规则与鉴权示例见快速入门。

星历数据

需要外部 Swiss Ephemeris 数据时，源码用户在仓库根目录运行：

uv run --locked --extra dev python -m fatebridge.fetch_ephe

默认下载三个 .se1 文件到仓库 ephe/。其他年代或天体可能需要额外文件；数据许可独立于项目代码。独立工具用户使用自定义目录下载流程，并在服务启动环境设置 SE_EPHE_PATH。数据准备后重启服务，核对实际返回的星历模型。

需要显式使用完整原始 DE441 时，可通过 python -m fatebridge.fetch_jpl 安装并校验文件，再按星历数据与精度设置严格 JPL 后端；下载本身不会切换计算模型。

输入、结果与精度

• 输入：出生接口使用公历；按各工具 Schema 提供小时、时区和地点，不能把未知出生时刻补成零点。中式出生计算默认开启真太阳时，西占核心盘默认使用民用时刻；保留实际解析和精度提示。
• 地点：离线库按来源版本覆盖大陆 397 个县级市、333 个地级行政单位，扩展至县区、台湾行政区及五大洲 6,333 座海外城市。支持同名地点按省市、国家/州消歧；坐标为城市/行政代表点，具体出生地址应传实际经纬度。来源、坐标系转换和已知缺项见离线地点库。
• 结果：先检查 MCP isError、REST 状态码或 CLI 退出码，再读取业务字段。fields 支持点路径投影，strict_fields=true 拒绝无效路径；REST 投影选项放在 query，而非 JSON body。
• 完整导出：完整 JSON 首次调用设置 fields=null。MCP 默认预算为 8192 字符，超限后按 result_delivery 读取同一 run；未被首次选中的字段不能事后恢复。详见同次完整导出。
• 精度与复现：保留原输入与 run_metadata。外部 .se1 星历不随 wheel 分发；检查 chart_profile.ephemeris_model 与 run_metadata.engine_is_approximate，不能仅凭依赖可导入就认定加载了高精度数据。重现还需匹配实现、数据与环境，见星历说明。

大结果交付按需写入当前系统用户的私有临时目录，无需数据库。当前实现的有效期为 1 小时，目录总容量上限为 64 MiB，容量不足时可提前淘汰旧结果；这是临时交付机制，需要留存的结果应及时导出。它不提供加密或按应用用户隔离，文件格式、分页与校验步骤见完整结果交付。

开发与测试

先完成源码安装，以下命令均在仓库根目录执行。无需激活虚拟环境：

tests/ 包含领域回归、输入／输出合同、三端对齐、结果交付、文档与技能检查；tests/golden/ 保存数值基线。先运行与改动相关的文件，也可用 uv run --locked --extra dev python -m pytest -q tests/test_api_alignment.py -k relative_chart 选择关系盘用例。

纯文档改动可从以下检查开始；生成区只通过脚本更新：

uv run --locked --extra dev python scripts/check_docs.py
uv run --locked --extra dev python scripts/build_scenario_manifest.py --check
uv run --locked --extra dev python scripts/build_codex_call_contracts.py --check
uv run --locked --extra dev python -m pytest -q \
  tests/test_documentation_integrity.py tests/test_doc_tool_counts.py \
  tests/test_scenario_routing_coverage.py tests/test_skills_interface_contract.py \
  tests/test_skills_engine_contract.py tests/test_codex_call_contracts.py \
  tests/test_ci_workflow.py
git diff --check

CI 在锁定环境、Python 3.10–3.13 最新依赖、最低直接依赖和 Windows 环境运行自包含检查，代码变更保留相同检查范围，并按节点分片并行；普通 README／文档变更只运行轻量路径与汇总检查。测试数据仅留本地，云端不恢复外部夹具、星历或黄金快照。完整领域回归与数值验收需在本地另行执行，云端通过不代表它们已通过。规则见测试策略与 CI 范围。

PR 以 CI result 汇总状态确认检查完成；代码变更还会核对六种环境的分片节点覆盖。连续推送会取消同一 PR 的旧运行，main／master 的每次推送独立运行。

部署与升级

选择运行环境

本地 stdio MCP 由客户端管理进程；REST 与 HTTP MCP 需要独立常驻服务。当前仓库没有提供 Dockerfile 或 Compose 文件。容器部署建议按 uv 官方 Docker 指南构建自己的镜像：复制源码、包定义与锁文件，用 uv sync --locked --no-dev 安装运行环境，并以非 root 用户运行选定入口。容器内 HTTP 服务需监听 0.0.0.0；宿主机端口映射与网关决定外部访问范围。星历应在构建时单独准备或作为数据卷挂载，临时结果目录须可写。

直接部署 Linux 主机时，先在固定目录建立源码环境，再用 systemd 等进程管理器运行 .venv/bin/fatebridge-api 或 FastMCP HTTP runner；MCP 的 unit 模板见常驻部署。运行用户需要访问实际 Python、源码、星历与私有临时目录。环境变量在服务配置中显式注入；REST 密钥、网络访问与运维端点范围见安全策略。

验证与运维

• REST：检查 /health、/ready，执行一次本文的虚构请求；/metrics 提供当前进程的 Prometheus 指标。
• HTTP MCP：使用 MCP 客户端完成初始化、发现与工具调用；普通浏览器 GET /mcp 不能替代协议验收，见HTTP 验证示例。
• 故障定位：记录 doctor 的版本、解释器与包路径，结合服务管理器日志；回执和日志对外分享前脱敏。

升级与回退

升级前保存版本／提交、服务配置和仍需保留的导出文件。独立工具使用 uv tool upgrade fatebridge；源码用户先保留本地改动，再用 git pull --ff-only 与 uv sync --locked --extra dev 更新。随后重新运行 doctor 与协议验证，重启服务或客户端连接，并核对实际加载的版本。

回退时选定已确认的发布版本或 Git tag / commit，在独立环境安装并切换服务路径；具体固定版本、停用与卸载命令见升级与回退指南。CI 成功后是否发布 PyPI 取决于该提交的包版本是否尚未发布；普通源码更新不一定产生新的 PyPI 版本，详见打包发布流程。

常见问题

更多恢复步骤见故障排除，MCP 的升级、停用与部署验证见部署指南。

文档导航

全部文档见文档中心，版本变化见 CHANGELOG。

参与贡献

欢迎算法修正、接口改进、测试、文档和技能贡献。先按开发与测试建立环境并选择检查范围；代码改动按影响补齐领域测试与三端合同验证。依赖变更使用 uv add / uv remove，同时提交 pyproject.toml 与 uv.lock。

开发与 PR 流程见贡献指南。通过 Issues报告问题时，附版本、系统、最小虚构输入与实际错误；安全问题按 SECURITY.md私下报告。

使用范围与许可

传统解释与分数用于文化参考，分数不代表现实成功概率。计算测试验证历法、数值和所选规则的一致性，不证明预测有效性。咨询不提供生死寿命、灾祸断言、临床诊断治疗与医疗择时，详见咨询硬边界。

本地运行仍需考虑 Agent 客户端、模型服务、聊天记录与导出文件对资料的处理；真实出生资料不应提交到公开 Issue 或仓库。

项目代码采用 Apache-2.0，第三方组件与来源见 NOTICE。依赖与星历数据遵循各自许可，分发或商用集成时需分别核对。

返回顶部 ↑