import { createDashileeEngineClient } from '@dashilee/engine-client';
const engine = createDashileeEngineClient({
baseUrl: 'https://api.example.com',
getAccessToken: () => session.accessToken,
});
const capabilities = await engine.capabilities();
const result = await engine.baziPersonal({
subject: { birthData, timeBasis: 'true_solar' },
options: {
responseView: 'full',
reportMode: 'template',
contentLocale: 'zh-Hans',
formatLocale: 'zh-Hans-CN',
interpretationProfileId: 'ziping-zh-Hans@1',
},
});API 卷首 · Headless Service
一套引擎，
四种命盘能力。
前端只需识别一个稳定的执行信封。历法、地点校时、排盘、规则、合参和报告由服务端统一编排，Web、App 与游戏可以自由选择表现形式。
- 入口
- 1 个执行 API
- 状态
- Ephemeral
- 核心
- 确定性计算
- LLM
- 可选、可回退
POST
/v1/engine/
executions JSON · STATELESS
executions JSON · STATELESS
壹四柱个人bazi.personal
贰四柱合盘bazi.compatibility
叁紫微个人ziwei.personal
肆紫微合参ziwei.compatibility
01 · Quickstart
先发现能力，再执行计算
不要从页面文案猜测 feature、语言或版本。启动时读取 capabilities，并把完整执行交给同一个入口。
AuthorizationBearer <token>
本地验收服务默认不强制令牌；生产部署必须在 API Gateway 开启身份、配额与限流。无状态执行不要求 Idempotency-Key。
02 · Integration flow
一条可审计的前端链路
- 01读取能力
GET /v1/engine/capabilities
- 02取得地点
搜索并保存版本化 placeId
- 03必要时校时
展示民用时与真太阳时边界
- 04统一执行
POST /v1/engine/executions
03 · Features
四个平行功能，不设前置门槛
每个 feature 都有独立输入约束与默认解释档案，但共用同一个请求和响应骨架。
bazi.personal
四柱个人命盘
正在读取结构化能力清单。
{}04 · Endpoints
核心端点
四项能力只需两个引擎端点；地点、历法与校时端点作为输入准备层按需调用。
GET
/v1/engine/capabilities获取能力、版本与限制
公共能力发现。适合应用启动、配置刷新和兼容性检查。
POST
/v1/engine/executions执行任意一个命盘功能
纯计算、无状态。通过 feature 选择模块，通过 responseView 选择返回粒度。
输入准备端点 5 个相关接口
GET /v1/places/search通用地点检索
GET /v1/places/china-divisions中国省／市／县
GET /v1/places/market-cities全球重点地区城市
POST /v1/calendar/convert公历／农历换算
POST /v1/time/calibrations历史时区与真太阳时
05 · Response
一个稳定的执行信封
facts、report 与 full 只改变 result 的粒度，不改变顶层服务、执行、警告和版本字段。
{
"service": { ... },
"execution": {
"feature": "bazi.personal",
"inputHash": "sha256...",
"status": "succeeded"
},
"result": {
"subjects": [ ... ],
"charts": [ ... ],
"analysis": null,
"claims": [ ... ],
"report": { ... }
},
"warnings": [],
"versions": { ... }
}| responseView | charts / analysis / claims | report | 适用场景 |
|---|---|---|---|
facts | 包含 | 不包含 | 二次开发、游戏映射、规则审计 |
report | 省略 | 包含 | 轻量报告页、阅读器 |
full | 包含 | 包含 | 研发、验收、完整客户端 |
06 · Problems
错误用 code 分支，文案只负责解释
失败响应使用 application/problem+json。记录 requestId 便于追踪，不要解析中文或英文 detail 做程序判断。
{
"type": "/problems/consent_required",
"title": "Both people must authorize...",
"status": 422,
"code": "CONSENT_REQUIRED",
"detail": "...",
"requestId": "req-...",
"invalidParams": [ ... ]
}07 · SDK
表现层可以不同，契约保持一致
JavaScript SDK 覆盖浏览器、Node 和 React Native；Unity 示例只连接游戏自有网关。
@dashilee/engine-client
零运行时依赖，内置四个便捷方法、请求追踪与 Problem 错误映射。
查看 SDK 文档 ↗Unity gateway client
示范 UnityWebRequest 传输边界。生产密钥只存在游戏后端或 API Gateway。
查看 Unity 示例 ↗08 · Agent-ready
给 AI 一条更短的理解路径
AI 先读轻量能力目录，选定 feature 后再读取 OpenAPI Schema；需要完整提示上下文时使用 llms-full.txt。
推荐 Agent 指令
先读取/docs/api/service-engine.json选择 feature；再使用/docs/api/openapi.json校验请求。不得改写排盘事实，不得跳过合盘授权，不得自行生成 placeId。
09 · Playground
请求调试台
默认连接当前站点的 API 代理。本地启动 npm run dev 后可直接发送；令牌只保存在当前页面内存。