API 接口文档 - 道德经-全维读书会

一、统一链接（Base URL / 版本）

引擎服务地址（内部）：http://127.0.0.1:8200（systemd 服务 zsky-engine）
对外接入：统一经站点域名/网关转发，鉴权通过后调用以下端点
版本：引擎顶层 version=v2.0-dual-drive；平台推理 version=3.0.0-platform；dynamic 扩展模型 module_version=3.0.0-dynamic

方法	端点	说明
GET	`/health`	引擎健康检查
GET	`/models`	可用模型列表
GET	`/params`	引擎参数
GET	`/platform/status`	平台化运行状态
GET	`/platform/selftest`	引擎自检（6 项 PASS）
POST	`/infer`	推理主入口（见第三节）

二、鉴权方式（Token + 角色能力）

完整鉴权体系：携带有效 Token 时以 via='token'（Token 内 role/user_id 优先）；无或伪 Token 时以请求内 role/user_id 判定（via='platform'，缺省 guest）。

调用流程

1

签发 Token：token.issue(user_id, role, ttl=3600s, quotas)，用于绑定调用方身份与角色权限。

2

发起推理：请求体携带 token（有则优先）；否则传 role / user_id（走平台缺省判定）。

3

引擎校验：无效 Token→401；角色越权→403；配额用尽→429；通过→正常推理并返回 auth{v user_id, role, via}。

角色权限矩阵（ROLE_CAPABILITIES）

角色	可用模型
`guest` / `user`	`tibetan`、`tcm`、`comprehensive`、`dual`、`cross_verify`
`vip`	以上全部 + `dynamic`（动态建模）、`report`
`admin`	`*`（全部模型）

三、调用契约（POST /infer）

请求参数

字段	类型	必填	说明
`model`	string	是	模型：`tibetan`/`tcm`/`comprehensive`/`dual`/`cross_verify`/`dynamic`
`answers`	object	是	答题答案（体系标准键，或五行/三因键，如 `{Wood:2,Fire:0,...}`）
`engine_mode`	string	否	`platform`（平台化模式）
`token`	string	否	鉴权 Token（有则优先，via='token'）
`role`	string	否	`guest`/`user`/`vip`/`admin`（无 token 时判定）
`user_id`	string	否	调用方标识（无 token 时随 role 判定）
`risk_answers`	object	否	风险题答案
`risk_true_value`	int	否	风险真值

响应结构（platform 推理，data 区）

字段	说明
`code / msg / version`	业务码 / 信息 / 版本（`0` 成功；`3.0.0-platform`）
`request_id`	单次请求唯一标识
`data.model / module_version`	模型名 / 模块版本（如 `3.0.0-dynamic`）
`data.health_index`	动态稳态健康指数（0–1，越低越失衡）
`data.health_level`	失衡等级：平衡良好 / 轻度失调 / 明显失衡 / 严重失衡
`data.factors`	健康因子 `E = 1 + δ`（1.0=平衡，>1 偏亢，<1 偏弱）
`data.imbalances[]`	失衡点（\|δ\|>0.3）：name / direction / delta / factor / type / severity
`data.diagnosis[] / advice[]`	诊断描述 / 调理建议
`data.risk_level`	风险等级
`engine`	引擎信息：name / framework_version / mode / extra_models
`auth`	鉴权结果：user_id / role / via（token 或 platform）

四、调用示例（dynamic 动态建模）

请求

curl -s http://127.0.0.1:8200/infer \
  -H 'Content-Type: application/json' \
  -d '{"model":"dynamic","answers":{"Wood":2,"Fire":0,"Earth":1,"Metal":2,"Water":1,"L":2,"T":0,"B":1},"engine_mode":"platform","role":"vip"}'

响应（实测）

{"code":0,"version":"3.0.0-platform",
 "data":{"model":"dynamic","module_version":"3.0.0-dynamic",
   "health_index":0.4988,"health_level":"严重失衡",
   "factors":{"Wood":1.1668,"Fire":1.7903,"Earth":1.8049,"Metal":1.1551,"Water":1.183,"L":0.9765,"T":1.6597,"B":1.507},
   "imbalances":[
     {"name":"火·心","direction":"偏亢","delta":0.7903,"factor":"Fire","type":"过盛","severity":"重度"},
     {"name":"土·脾","direction":"偏亢","delta":0.8049,"factor":"Earth","type":"过盛","severity":"重度"},
     {"name":"赤巴T","direction":"偏亢","delta":0.6597,"factor":"T","type":"过盛","severity":"重度"},
     {"name":"培根B","direction":"偏亢","delta":0.507,"factor":"B","type":"过盛","severity":"中度"}],
   "diagnosis":[],"advice":[],"risk_level":"low"},
 "engine":{"name":"全维理论引擎","framework_version":"3.0.0-platform","mode":"platform","extra_models":{"dynamic":"3.0.0-dynamic"}},
 "auth":{"user_id":"","role":"vip","via":"platform"}}

说明：差异答案 {Wood:2,Fire:0,Earth:1,...} → H=0.4988 严重失衡 + 4 个失衡点；全同值（全=2）→ H=0.867 平衡良好、无失衡。

五、错误码

状态/业务码	含义
`401`	Token 无效/缺失，鉴权失败
`403`	权限不足（请求模型超出角色能力）
`429`	配额用尽
`1001`	/temporal 端点未启用
`4001`（HTTP 400）	请求体非法/参数缺失
`5001`	推理无结果
`4040`（HTTP 404）	未知端点

更精简的快速接入说明见 API 文档（简洁版）。

全维理论引擎 · API 接口文档