# Website API 契约

网站模式与原本机 Bearer 模式分别启动，不自动降级。前缀 `/api/decision/v1`。

当前生产启用服务器内置固定配置，不接收前端密钥。`/configuration`、`/models`、`/test`、`/codex/*` 在此模式统一返回 403；表中这些接口只保留给非共享兼容模式。会话返回 `configurationManaged:true`、`keyStorage:"server-managed"`，不会返回密钥。

### 新源码 v2 语言任务（需前后端一同部署）

URL 前缀仍为 `/api/decision/v1`（传输 API），数据版本为 `lekiwi-language-v2`；旧 v1 校验保留，不接受跨版本混用。

`POST /command` 可输入 `{instruction,stamp,sceneContext}`。sceneContext 包含 `version`、固定 `sceneId:lekiwi-language-scene-v2`、`source:mujoco-ground-truth`、`units:SI`、`frame:world-z-up`、实测 `object:[x,y,z]`、`base:[x,y,z]` 与 `yaw`。台面/命名区来自服务端固定预设，不接受模型生成新场景。

返回 value 固定字段 `{version,action,value,summary,objectId,targetId,position,supportId}`。抓放 objectId=block，targetId 为 A/B（position=[]）或 coordinates（position=XY/XYZ），supportId 为 source/table；其他动作三个 ID 为 none、position=[]。坐标统一米、Z 为物体中心；单位/明确数值与原始指令独立交叉校验，未知目标/无支撑/越界/高度不符拒绝。抓取→搬运→释放是一项合法任务，不等于允许任意多指令串联。

`/plan`、`/decide` 按 observation.version 分派 schema。v2 增加 stow/approach 两个前置阶段；Jev 同一请求返回 choice、grasp、diagnosis、recovery 和 noul/score/reason。noul 为 allow/deny/uncertain；score 是 poor/partial/good/excellent/unavailable 离散等级，不能代替物理验收。v2 仅支持服务端 API 模型，不通过新版面板发起订阅登录；旧 v1 程序化订阅接口不删除。

指令和后续技能闭环共享 runId/sceneRevision，LLM 初始调用共 2 次，Jev 包括 1 次意图审核及技能边界审核；预算不重置。浏览器不自动重载场景、不静默转 mock。最终脱敏只读事件为 `robot-task-result`，含 snapshot、commandReceipt 和本任务 receipts，不含密钥。

### 旧指令兼容

`POST /command` 不带 sceneContext 时输入 `{instruction,stamp}`，返回标准 stamped 回执：`value:{action,value,summary}`，`usage:{llm,jev?}`。动作枚举为 `move`（有符号米，正前负后，绝对值 0.01–1）、`turn`（有符号度，正左负右，1–180）、`pick_place`、`stop`、`clarify`（后三者 value=0）。单次不接受复合动作，不猜缺失方向；具体单位/数值/输出字段由代码再验证，模型只给受限意图，不能写执行器或宣布成功。

DeepSeek 理解后，运动/抓放意图再经 Jev 选择 allow/stop；同一取消标识覆盖两个调用。浏览器等待期间暂停物理，响应到达后重新核对会话、场景、位姿/控制目标、取消代次，过期响应不执行。运动使用现有单一物理时钟、闭环速度与角度控制、碰撞/姿态/时间上限和实际误差验收。旧 v1 `/plan` 仍仅供原固定抓放技能链；新版按上述版本分派。

| 路径                                            | 方法   | 语义                                                                  |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------- |
| `/session`                                      | POST   | 同源 JSON 空对象建立/恢复会话，返回 CSRF、版本、设置状态；不调用模型  |
| `/session`                                      | DELETE | CSRF 保护，取消任务、销毁凭据和订阅进程                               |
| `/status`                                       | GET    | 当前会话状态、配置版本，不延长空闲寿命                                |
| `/models`                                       | GET    | DeepSeek 固定型号及服务端缓存的 OpenRouter 结构化模型目录             |
| `/configuration`                                | PUT    | 原子更新 `{llm:{provider,model,apiKey?},jev:{apiKey?}}`，拒绝其他字段 |
| `/plan`,`/decide`,`/test`,`/cancel`             | POST   | 沿用既有契约，作用域仅当前会话                                        |
| `/codex/status`,`/codex/models`,`/codex/limits` | GET    | 会话独立订阅状态，无账号时不启动 CLI                                  |
| `/codex/login`,`/codex/cancel`,`/codex/logout`  | POST   | 官方设备码登录、取消、退出；拒绝任意 RPC                              |

生产 Cookie 为 `__Host-cadworld-session; Secure; HttpOnly; SameSite=Strict; Path=/`，无 Domain。修改/推理携带 `X-CSRF-Token` 和 `X-Config-Version`，精确 Origin/Host 校验。开发 HTTP 只接受显式 `--website-dev` 与回环来源，用不同 Cookie 名，不改变生产要求。代理只信任配置的来源 IP，覆盖外来转发头。

以下配置语义适用于非共享兼容模式：省略 apiKey 表示同提供方保留内存密钥，换提供方必须重填；清除通过销毁整个会话完成。配置草稿不改变后台，保存不推理。并发标签页以配置版本拒绝旧配置。错误只返回稳定错误码，不回显上游文本。

会话空闲 30 分钟、最长 8 小时，状态轮询不续期。默认最多 128 会话，单会话 1 推理；非共享模式默认全局 8 推理、2 Codex 账号，生产共享模式覆盖为全局 2 推理且不开放 Codex；会话/IP/全局限流分别生效。浏览器模型 ZIP 不上传。服务不自动发现仓库 `.env`；共享模式通过显式 `--website-key-file` 读取受保护服务器文件。另有跨会话、跨进程的 60 次/小时、600 次/24h 上游调用预留限额（持久 SQLite，`/command` 每次预留 2，其他推理 1；失败不退款），生产并行上限为 2。用户后续要求固定 DeepSeek＋Jev，故不再把 Jev Key 用于其他 OpenRouter 主规划模型。当前结果与限制见 [内置模型/语言控制记录](website-hosted-control-2026-09-24.md)；此前 BYOK 阶段的实测保留于 [历史受控验收](website-acceptance-2026-09-24.md)。