docs(zh): rewrite the server API reference - #3483
Conversation
…e entries
Rewrite docs/zh/reference/server-api.md as a field-level reference: minimal prose, structured tables for every endpoint's body/query/data and non-zero codes, plus one compact example per endpoint. Covers all 104 v1 endpoints (the 101 previously documented plus the new workspaces add-dir route and the two experimental file-history routes), 15 v2 endpoints, and all 80 WS frame types, with a new WebSocket lifecycle section (handshake, one turn, interaction branches, reconnect recovery) and a shared-type dictionary at the bottom. The English page is intentionally left unchanged for now.
Corrected against the current server:
- GET /sessions/{id} last_seq is now the real event watermark (the old page claimed it was always 0)
- the heartbeat behavior is documented (the old page claimed the server sends no heartbeats and never disconnects idle connections)
- terminal WS frames are documented as a dead protocol (declared in AsyncAPI, never produced or consumed by the server)
- profile agent_config now lists tower_mode / tower_base
- message no longer lists the phantom prompt_id / parent_message_id fields (declared in schema, never produced)
- the 40911 undo error data shape is marked engine-dependent instead of a fixed object
- subscribe payload gains the watch_fs field, and watch_fs_add/remove payload gains runtime_id alongside recursive
- event delivery scopes are documented precisely: event.question.*/event.approval.* are session events, event.fs.changed goes only to watchers
Moved:
- the "用 API 驱动一个会话" walkthrough moves to docs/zh/guides/web.md as a new section (guide-style narrative belongs in a guide; the reference page keeps a link); docs/zh/reference/kimi-command.md now points at the new anchor
Omitted:
- per-endpoint narrative paragraphs whose facts now live in the same entry's body/data/error tables (compressed, no fact lost)
- the rollback-buffer note on the terminal object (it described output replay over the terminal WS channel, which is a dead protocol and is now documented as such)
- the fixed 40911 undo data shape {reason, requestedCount, undoableCount} (unverifiable; the server passes through engine details whose shape is not fixed)
Remove the "用 API 驱动一个会话" walkthrough instead of relocating it to guides/web.md (per review direction). The reference page and kimi-command.md no longer link to it.
Define ResponseType<T> once in the conventions section and rewrite all 122 endpoint entries from "**data**（code = 0）" to "**返回**：ResponseType<T>". The WS event-envelope concept (frame outer fields) is a separate concept and stays.
Remove the 40001 details note and the non-zero-code-with-data specials table from the ResponseType section; each affected endpoint entry already carries (or now carries) its own data shape inline, and 40001 mentions in non-zero-code lines now state the { path, message }[] details shape.
…business domains Merge the flat per-registry sections into business domains (服务与账号 / 工作区与会话 / 对话 / 任务与终端 / 扩展 / 文件与其他); former sections become bold dividers inside each domain. v2 sessions and v2 MCP fold into their business domains, with the /api/v1 vs /api/v2 path prefix called out as the version marker. Endpoint headings and anchors are unchanged.
… definition blocks
New per-endpoint shape: domain H2 with intro and one merged endpoint table; endpoint H3 with description, 请求体 table (when present), 响应体 type + table, non-zero codes, and a pretty-printed 响应示例. The REST 端点 wrapper heading is dropped in favor of an unheaded lead-in.
… providers action response envelope
…rseded old-format content
|
commit: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27b8518068
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ::: warning 注意 | ||
| 本页描述的 REST 与 WebSocket API 为实验性特性：不保证接口稳定性，端点、字段与事件类型可能随任何版本更改。集成时请以你所用版本服务的 `/openapi.json` 与 `/asyncapi.json` 文档为准。 | ||
| ::: | ||
| 此页面记录 kap-server 的 API 接口类型，分为 REST API 与 WebSocket 事件流两种。 |
There was a problem hiding this comment.
This rewrite changes the Chinese page's structure, endpoint inventory, and type reference while leaving docs/en/reference/server-api.md on the older partial walkthrough, so users receive materially different API contracts depending on locale. Update the English mirror alongside this page rather than deferring it to a follow-up.
AGENTS.md reference: docs/AGENTS.md:L16-L21
Useful? React with 👍 / 👎.
| ::: warning 注意 | ||
| 本页描述的 REST 与 WebSocket API 为实验性特性：不保证接口稳定性，端点、字段与事件类型可能随任何版本更改。集成时请以你所用版本服务的 `/openapi.json` 与 `/asyncapi.json` 文档为准。 | ||
| ::: | ||
| 此页面记录 kap-server 的 API 接口类型，分为 REST API 与 WebSocket 事件流两种。 |
There was a problem hiding this comment.
For readers building integrations against this reference, the rewrite removes the only warning that these REST and WebSocket contracts are experimental and may change in any release, along with the direction to prefer the running server's /openapi.json and /asyncapi.json schemas. Nothing in this change graduates the API to a stable contract, so presenting the new exhaustive type catalog without that caveat can cause consumers to rely on unsupported compatibility guarantees; retain the warning and live-schema guidance.
AGENTS.md reference: docs/AGENTS.md:L23-L28
Useful? React with 👍 / 👎.
1 participant
Related Issue
Internal docs work — no linked issue.
Problem
The zh server API reference (
docs/zh/reference/server-api.md) was a narrative walkthrough: endpoint coverage was partial, request/response shapes were described loosely in prose, WebSocket frames were only sketched, and there was no authoritative type index — readers had to cross-read source code to learn the actual wire shapes.What changed
Rewrites
docs/zh/reference/server-api.mdas a complete typed reference, fact-checked against the current server implementation:ResponseType<T>response table with per-field optionality/nullability, non-zero business codes, and a pretty-printed response example.ServerSystemMessage/ClientControlMessage),event.*protocol events, agent events (AgentEvent), and transcript frames (TranscriptResetEvent/TranscriptOpsEvent) — with durability/volatility and delivery semantics. Dead protocol surface is documented as such instead of being presented as live.T-*entries split into REST types and WS types (event payloads + transcript family), each as a TypeScript definition block using the system's canonical type names, with "optional" (?) vs "nullable" (| null) spelled out per field.docs/zh/reference/kimi-command.md.Intentionally left for follow-ups:
完整错误码section is a TODO placeholder; the full error-code table lands separately.docs/en/reference/server-api.md) is untouched and will be synced separately.Checklist
cd docs && npm run buildpasses.gen-changesetsskill, or this PR needs no changeset. — No changeset: docs-only change that never enters the shipped artifact.gen-docsskill, or this PR needs no doc update. — This PR is the doc update.