chenlin
0d986f60bd
web-platform-ci / Standalone decision service (no cloud credentials) (push) Has been cancelled
web-platform-ci / TypeScript, lint, unit, build (push) Has been cancelled
web-platform-ci / Playwright E2E (push) Has been cancelled
lekiwi-compatibility / cpu-compatibility (push) Has been cancelled
集成服务器托管模型、自然语言移动与有界抓放、内置 LeKiwi URL 导入和双摄像头；同步部署契约与指定域名 iframe 白名单，保留原有物理安全、会话及调用预算防护。 更新 npm 包及锁文件版本、CHANGELOG 与发布文档。提交前 typecheck、120 项定向前端测试和 44 项后端测试通过（3 项可选跳过）；真实 v2 云模型抓放仍待单独验收，不包含运行密钥或构建产物。
41 lines
6.2 KiB
Markdown
41 lines
6.2 KiB
Markdown
# 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)。
|