运行时 API

codewhale app-server 是 canonical 的本地运行时 API 与控制平面。本地 SDK、移动/远控客户端和编辑器集成直接与它对话，而不是抓终端输出。引擎只作为本地进程运行：所有 API 默认绑定 localhost——没有托管中继，不托管 provider 令牌，不泄露秘密。codewhale serve --http / --mobile 保留为 app-server --http / --mobile 的兼容别名，启动的是同一个服务器；新集成应面向 app-server。

codewhale app-server --http

完整 /v1/* HTTP/SSE 运行时 API（canonical 入口），默认 127.0.0.1:7878。

codewhale app-server --mobile

运行时 API 加 /mobile 手机控制页。

codewhale app-server --stdio

换行分隔的 JSON-RPC 2.0 控制传输，无监听端口，适合本地 SDK 和探针。

codewhale web [--port 7878]

仅回环的浏览器客户端，内嵌于二进制并打开默认浏览器。

codewhale doctor --json

机器可读的健康与能力报告。

codewhale serve --acp

面向 Zed 等编辑器的 ACP（Agent Client Protocol）stdio 适配器。

codewhale exec [args]

一次性无头 worker（stream-json、Fleet 子进程、CI 原语）——不属于本 API，但共享同一运行时与事件词汇。

零成本探测

stdio 控制传输可以不花模型 token 地探测。capabilities 返回声明的方法族（thread/*、app/*、prompt/*）和完整方法列表；方法集由 crates/app-server/src/lib.rs 中的漂移测试固定，SDK 和本地集成可以放心依赖它不会悄悄变化。

printf '%s
' \
  '{"jsonrpc":"2.0","id":1,"method":"healthz"}' \
  '{"jsonrpc":"2.0","id":2,"method":"capabilities"}' \
  '{"jsonrpc":"2.0","id":3,"method":"shutdown"}' \
  | codewhale app-server --stdio

进行中的回合可以用 thread/interrupt（或 HTTP 的 POST /v1/threads/{id}/turns/{turn_id}/interrupt）请求中断；没有正在流式输出的回合时返回 interrupted: false——这不是错误，只是没有可停的东西。

安全边界

运行时 API 令牌按 --auth-token、CODEWHALE_RUNTIME_TOKEN、DEEPSEEK_RUNTIME_TOKEN 的顺序读取；--insecure-no-auth 只允许与回环绑定一起使用。浏览器侧的跨源请求会被 CORS 允许列表拒绝。选择非回环绑定（尤其是 app-server --mobile）之前，请阅读 docs/RUNTIME_API.md 的完整部署与认证约定。

来源文档：docs/RUNTIME_API.md · 更新时请同步修改 docs-map.ts。

查找准确的使用说明。