@wacry/codeks-bridge 0.0.0-stage → 0.0.1

package/dist/writer.js

@@ -0,0 +1,430 @@
+// Writes an OpenAI Responses SSE stream for codeks.
+//
+// Rules that codeks depends on (see docs/responses-stream.md):
+// - every item gets output_item.added before any delta, and output_item.done
+//   with the complete item; codeks records history from the done event;
+// - response.completed carries the response id and a complete usage object;
+// - errors go into response.failed, never into a bare "error" event.
+import { formatSse } from "./sse.js";
+import { newId } from "./ids.js";
+import { BridgeError } from "./errors.js";
+export function usageJson(usage) {
+    const input = Math.max(0, Math.round(usage.input_tokens));
+    const output = Math.max(0, Math.round(usage.output_tokens));
+    const out = {
+        input_tokens: input,
+        input_tokens_details: {
+            cached_tokens: Math.max(0, Math.round(usage.cached_tokens ?? 0)),
+            ...(usage.cache_write_tokens ? { cache_write_tokens: Math.round(usage.cache_write_tokens) } : {}),
+        },
+        output_tokens: output,
+        total_tokens: input + output,
+    };
+    if (usage.reasoning_tokens !== undefined) {
+        out.output_tokens_details = { reasoning_tokens: Math.max(0, Math.round(usage.reasoning_tokens)) };
+    }
+    return out;
+}
+export class ResponseWriter {
+    id;
+    sink;
+    model;
+    showSummary;
+    seq = 0;
+    nextOutputIndex = 0;
+    output = [];
+    message;
+    reasoning;
+    // A finished message waits here until we know whether a tool call follows.
+    pendingMessage;
+    calls = 0;
+    // Once a tool appears, preserve its entire ordered suffix until success.
+    suffix;
+    suffixOutputStart = 0;
+    native = false;
+    nativeEnd;
+    started = false;
+    finished = false;
+    constructor(sink, opts) {
+        this.sink = sink;
+        this.model = opts.model;
+        this.showSummary = opts.showSummary ?? true;
+        this.id = opts.responseId ?? newId("resp");
+    }
+    get responseId() { return this.id; }
+    get nativeResponse() { return this.nativeEnd?.response; }
+    get outputItems() {
+        return this.output;
+    }
+    get isFinished() {
+        return this.finished;
+    }
+    get hasOutput() {
+        return this.nextOutputIndex > 0 || this.calls > 0 || this.message !== undefined;
+    }
+    write(event, native = false) {
+        this.sink.write(formatSse(native ? event : { sequence_number: this.seq++, ...event }));
+    }
+    send(event, native = false) {
+        if (this.suffix)
+            this.suffix.push({ event, native });
+        else
+            this.write(event, native);
+    }
+    emit(type, fields) {
+        this.send({ type, ...fields });
+    }
+    holdSuffix() {
+        if (this.suffix)
+            return;
+        this.suffix = [];
+        this.suffixOutputStart = this.output.length;
+    }
+    releaseSuffix() {
+        const suffix = this.suffix;
+        this.suffix = undefined;
+        for (const { event, native } of suffix ?? [])
+            this.write(event, native);
+    }
+    discardSuffix() {
+        if (this.suffix)
+            this.output.length = this.suffixOutputStart;
+        this.suffix = undefined;
+        this.message = undefined;
+        this.reasoning = undefined;
+        this.pendingMessage = undefined;
+        this.calls = 0;
+    }
+    responseObject(status, extra = {}) {
+        return {
+            id: this.responseId,
+            object: "response",
+            created_at: Math.floor(Date.now() / 1000),
+            model: this.model,
+            status,
+            output: status === "in_progress" ? [] : this.output,
+            ...extra,
+        };
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        if (!this.native)
+            this.emit("response.created", { response: this.responseObject("in_progress") });
+    }
+    /** An event that codeks ignores but that resets its stream idle timer. */
+    keepalive() {
+        if (!this.started || this.finished)
+            return;
+        // Heartbeats bypass an ordered suffix while the upstream is still working.
+        this.write({ type: "keepalive" }, this.native);
+    }
+    /** Native Responses events retain their own ids, envelopes and metadata. */
+    useNativeResponses() { this.native = true; }
+    nativeEvent(event) {
+        if (this.finished)
+            return;
+        if (typeof event.response?.id === "string")
+            this.id = event.response.id;
+        if (event.type === "response.completed") {
+            this.nativeEnd = event;
+            return;
+        }
+        if (["response.output_item.added", "response.output_item.done"].includes(event.type)) {
+            if (["function_call", "custom_tool_call"].includes(event.item?.type))
+                this.holdSuffix();
+            if (event.type === "response.output_item.done")
+                this.output.push(event.item);
+            this.nextOutputIndex = Math.max(this.nextOutputIndex, Number(event.output_index ?? 0) + 1);
+        }
+        this.send(event, true);
+    }
+    nativeFailed(response, event = {}) {
+        this.nativeFailure("response.failed", response, event);
+    }
+    nativeIncomplete(response, event = {}) {
+        this.nativeFailure("response.incomplete", response, event);
+    }
+    nativeFailure(type, response, event) {
+        if (this.finished)
+            return;
+        this.discardSuffix();
+        this.finished = true;
+        if (typeof response.id === "string")
+            this.id = response.id;
+        this.nativeEnd = { ...event, type, response };
+        this.write(this.nativeEnd, true);
+    }
+    // Reasoning -----------------------------------------------------------
+    openReasoning() {
+        if (this.reasoning)
+            return this.reasoning;
+        this.closeMessage();
+        this.flushPendingMessage("commentary");
+        const r = { id: newId("rs"), outputIndex: this.nextOutputIndex++, summary: new Map() };
+        this.reasoning = r;
+        this.emit("response.output_item.added", {
+            output_index: r.outputIndex,
+            item: { type: "reasoning", id: r.id, summary: [], encrypted_content: null },
+        });
+        return r;
+    }
+    startReasoningSummary(summaryIndex = 0) {
+        const r = this.openReasoning();
+        if (!this.showSummary || r.summary.has(summaryIndex))
+            return;
+        r.summary.set(summaryIndex, { text: "", done: false });
+        this.emit("response.reasoning_summary_part.added", {
+            item_id: r.id,
+            output_index: r.outputIndex,
+            summary_index: summaryIndex,
+            part: { type: "summary_text", text: "" },
+        });
+    }
+    reasoningDelta(text, summaryIndex = 0) {
+        const r = this.openReasoning();
+        if (!text || !this.showSummary)
+            return;
+        this.startReasoningSummary(summaryIndex);
+        const part = r.summary.get(summaryIndex);
+        if (part.done)
+            throw new BridgeError("The upstream changed a completed reasoning summary", "stream_error", 502);
+        part.text += text;
+        this.emit("response.reasoning_summary_text.delta", {
+            item_id: r.id,
+            output_index: r.outputIndex,
+            summary_index: summaryIndex,
+            delta: text,
+        });
+    }
+    endReasoningSummary(summaryIndex = 0, text) {
+        const r = this.openReasoning();
+        if (!this.showSummary)
+            return;
+        this.startReasoningSummary(summaryIndex);
+        const part = r.summary.get(summaryIndex);
+        if (text !== undefined) {
+            if (!text.startsWith(part.text)) {
+                throw new BridgeError("The upstream changed already streamed reasoning summary", "stream_error", 502);
+            }
+            this.reasoningDelta(text.slice(part.text.length), summaryIndex);
+        }
+        if (part.done)
+            return;
+        part.done = true;
+        this.emit("response.reasoning_summary_text.done", {
+            item_id: r.id,
+            output_index: r.outputIndex,
+            summary_index: summaryIndex,
+            text: part.text,
+        });
+        this.emit("response.reasoning_summary_part.done", {
+            item_id: r.id,
+            output_index: r.outputIndex,
+            summary_index: summaryIndex,
+            part: { type: "summary_text", text: part.text },
+        });
+    }
+    /** Closes the open reasoning item (opening one if needed) with its carrier. */
+    endReasoning(encryptedContent, summary) {
+        const r = this.openReasoning();
+        for (const [index, part] of (summary ?? []).entries())
+            this.endReasoningSummary(index, part.text);
+        for (const index of r.summary.keys())
+            this.endReasoningSummary(index);
+        const item = {
+            type: "reasoning",
+            id: r.id,
+            summary: [...r.summary.entries()].sort(([a], [b]) => a - b)
+                .map(([, part]) => ({ type: "summary_text", text: part.text })),
+            encrypted_content: encryptedContent ?? null,
+        };
+        this.reasoning = undefined;
+        this.emit("response.output_item.done", { output_index: r.outputIndex, item });
+        this.output.push(item);
+    }
+    get reasoningOpen() {
+        return this.reasoning !== undefined;
+    }
+    // Messages ------------------------------------------------------------
+    textDelta(text, phase) {
+        if (this.message && phase !== undefined)
+            this.message.phase = phase;
+        if (!text)
+            return;
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        if (!this.message) {
+            this.flushPendingMessage("commentary");
+            const m = { id: newId("msg"), outputIndex: this.nextOutputIndex++, text: "", phase };
+            this.message = m;
+            this.emit("response.output_item.added", {
+                output_index: m.outputIndex,
+                item: { type: "message", id: m.id, role: "assistant", status: "in_progress", content: [], ...(phase !== undefined ? { phase } : {}) },
+            });
+            this.emit("response.content_part.added", {
+                item_id: m.id,
+                output_index: m.outputIndex,
+                content_index: 0,
+                part: { type: "output_text", text: "", annotations: [] },
+            });
+        }
+        this.message.text += text;
+        this.emit("response.output_text.delta", {
+            item_id: this.message.id,
+            output_index: this.message.outputIndex,
+            content_index: 0,
+            delta: text,
+        });
+    }
+    /** Ends the current text block. Its done event waits until the phase is known. */
+    closeMessage(phase) {
+        if (!this.message)
+            return;
+        if (phase !== undefined)
+            this.message.phase = phase;
+        this.flushPendingMessage("commentary");
+        this.pendingMessage = this.message;
+        this.message = undefined;
+    }
+    flushPendingMessage(phase) {
+        const m = this.pendingMessage;
+        if (!m)
+            return;
+        this.pendingMessage = undefined;
+        const item = {
+            type: "message",
+            id: m.id,
+            role: "assistant",
+            status: "completed",
+            content: [{ type: "output_text", text: m.text, annotations: [] }],
+            phase: m.phase ?? phase,
+        };
+        this.emit("response.output_text.done", {
+            item_id: m.id,
+            output_index: m.outputIndex,
+            content_index: 0,
+            text: m.text,
+        });
+        this.emit("response.output_item.done", { output_index: m.outputIndex, item });
+        this.output.push(item);
+    }
+    // Tool calls (held until the upstream response finishes) ---------------
+    addFunctionCall(call) {
+        this.closeMessage();
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        const item = {
+            type: "function_call",
+            id: newId("fc"),
+            call_id: call.call_id,
+            name: call.name,
+            arguments: call.arguments,
+            encrypted_function_args: [],
+            status: "completed",
+        };
+        if (call.namespace)
+            item.namespace = call.namespace;
+        this.addTool(item);
+    }
+    addCustomToolCall(call) {
+        this.closeMessage();
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        this.addTool({
+            type: "custom_tool_call",
+            id: newId("ctc"),
+            call_id: call.call_id,
+            name: call.name,
+            input: call.input,
+            ...(call.namespace ? { namespace: call.namespace } : {}),
+            status: "completed",
+        });
+    }
+    addTool(item) {
+        this.flushPendingMessage("commentary");
+        this.holdSuffix();
+        this.calls++;
+        const outputIndex = this.nextOutputIndex++;
+        const added = { ...item, status: "in_progress" };
+        if (item.type === "function_call")
+            added.arguments = "";
+        else
+            added.input = "";
+        this.emit("response.output_item.added", { output_index: outputIndex, item: added });
+        this.emit("response.output_item.done", { output_index: outputIndex, item });
+        this.output.push(item);
+    }
+    get toolCallCount() {
+        return this.output.slice(0, this.suffix ? this.suffixOutputStart : undefined)
+            .filter((item) => ["function_call", "custom_tool_call"].includes(item.type)).length;
+    }
+    /** Emits a complete item as-is (added and done together). */
+    addItem(item) {
+        this.closeMessage();
+        this.flushPendingMessage("commentary");
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        const outputIndex = this.nextOutputIndex++;
+        this.emit("response.output_item.added", { output_index: outputIndex, item });
+        this.emit("response.output_item.done", { output_index: outputIndex, item });
+        this.output.push(item);
+    }
+    flushAll(endTurn) {
+        this.closeMessage();
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        this.flushPendingMessage(endTurn === false || this.calls > 0 ? "commentary" : "final_answer");
+    }
+    // Endings ---------------------------------------------------------------
+    complete(usage, endTurn) {
+        if (this.finished)
+            return;
+        this.start();
+        if (this.nativeEnd) {
+            this.releaseSuffix();
+            this.finished = true;
+            this.write(this.nativeEnd, true);
+            return;
+        }
+        if (this.native)
+            throw new BridgeError("The upstream stream ended before response.completed", "stream_error", 502);
+        this.flushAll(endTurn);
+        this.releaseSuffix();
+        this.finished = true;
+        const extra = {};
+        if (usage)
+            extra.usage = usageJson(usage);
+        if (endTurn !== undefined)
+            extra.end_turn = endTurn;
+        this.emit("response.completed", { response: this.responseObject("completed", extra) });
+    }
+    /** Fails the response. Tool calls that were not emitted yet are dropped. */
+    fail(error) {
+        if (this.finished)
+            return;
+        this.start();
+        this.discardSuffix();
+        this.finished = true;
+        this.emit("response.failed", {
+            response: this.responseObject("failed", { error }),
+        });
+    }
+    incomplete(reason, usage) {
+        if (this.finished)
+            return;
+        this.start();
+        if (this.suffix)
+            this.discardSuffix();
+        this.closeMessage();
+        if (this.reasoning)
+            this.endReasoning(undefined);
+        this.flushPendingMessage("final_answer");
+        this.finished = true;
+        const extra = { incomplete_details: { reason } };
+        if (usage)
+            extra.usage = usageJson(usage);
+        this.emit("response.incomplete", { response: this.responseObject("incomplete", extra) });
+    }
+}

package/docs/backends-anthropic.md

@@ -0,0 +1,61 @@
+# Claude Messages
+
+模型选择 `catalog: "claude-opus-5-5"` 或 `"claude-sonnet-5-5"`，条目指定 `claude-messages` adapter，请求转换为 `POST <base_url>/messages`。官方端点的 `base_url` 为 `https://api.anthropic.com/v1`；默认使用 `x-api-key` 和 `anthropic-version: 2023-06-01`，可通过连接配置覆盖。
+
+## 历史与 thinking
+
+开头的 `instructions`、system 和 developer 消息组成顶层 `system`。会话中途的 system/developer 消息留在原位置，转换成 user 文本中的 `<system-reminder>`。新指令不会搬到会话顶部，因此已有前缀稳定；这保留时间顺序，但不具有原生 system 角色的优先级。
+
+相邻同角色消息合并；reasoning、文本和工具调用成为 assistant 内容块，工具输出成为下一条 user 消息中的 `tool_result`。原历史不变。
+
+默认 effort 为 `medium`，普通映射提供 `low`、`medium`、`high`、`xhigh`、`max` 并保留同名值，使用 adaptive thinking 并写入 `output_config.effort`。codeks 的 `ultra` 注入多代理提示词，并将 Opus 5.5 的原生 effort 设为 `xhigh`、Sonnet 5.5 设为 `max`。
+
+Opus 5.5 始终启用 thinking；Sonnet 5.5 的最低模式是 `between_tools`，关闭回复前的思考，但仍在工具之间返回带签名的进度说明。两者都拒绝 `thinking.type: "disabled"`，因此目录不把 `none` 作为可选档位，也不把关闭思考的请求静默改成 `low`。Sonnet 的 `between_tools` 只接受 `high` 或以下 effort，且 `thinking` 对象中不能附带 `display`、`budget_tokens` 等字段。[官方 thinking 规则](https://platform.claude.com/docs/en/build-with-claude/thinking)、[Sonnet 5.5 变更说明](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5)
+
+`reasoning.summary` 缺省或为 `none` 时选择 `display: "omitted"`；`auto`、`concise`、`detailed` 选择 `summarized`，不保证上游区分摘要长度。目录默认值与 GPT-6.1 Sol 一样为 `none`；要显示摘要，在 codeks 配置中设置 `model_reasoning_summary = "auto"`。显示开关不关闭 thinking 或载荷回放。
+
+`reasoning.effort_map` 可以替换映射，`options.thinking` 和 `options.output_config` 可以覆盖完整原生对象。例如以下 Sonnet 模型条目固定使用 `between_tools` 与 `low` effort；options 优先于客户端请求中推导的模式、effort 和 display，无需新增转换接口：
+
+```json
+{
+  "catalog": "claude-sonnet-5-5",
+  "upstream": "anthropic",
+  "model": "claude-sonnet-5-5",
+  "options": {
+    "thinking": { "type": "between_tools" },
+    "output_config": { "effort": "low" }
+  }
+}
+```
+
+未映射的显式 effort 仍交给上游判断；客户端显式请求 `none` 时，adapter 仍发送 `thinking.type: "disabled"`，由上游返回错误。目录精调不构成运行时能力预检。
+
+Opus / Sonnet 5.5 目录的默认及最大上下文窗口为 `1000000`，Messages API 要求提供 `max_tokens`，因此目录设置默认输出预算 `128000`，对应官方标准最大输出。输出预算依次取请求 `max_output_tokens`、模型配置、目录默认值，再接受上游和模型 options 的覆盖；这是允许的上限，不要求每次生成同样长度。[模型规格](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)、[配置优先级](config.md)
+
+完整 `thinking`/`redacted_thinking` block，包括签名或隐藏数据，存入 `anthropic.thinking.v1` carrier。请求按 `replay.reasoning_from` 恢复允许来源，签名完整保留；其他来源只在当前请求过滤。允许配对不意味着上游一定接受其签名。[Reasoning 策略](reasoning.md)
+
+## 输出格式、工具与图片
+
+Responses `text.format: {type: "json_schema", schema: ...}` 转为 `output_config.format: {type: "json_schema", schema: ...}`；name/strict 不转发。schema 内容直接交给上游，随后 options 仍可覆盖原生格式。普通 `text` 不添加约束；无法表达为 Messages 的未知格式报错。
+
+namespace 和 custom tool 使用共享映射。自由文本工具转换成 `{input: string}`，Lark/regex 放入描述，返回时恢复原始字符串；不添加工具专属提示词。指定工具必须能在当前工具表中解析，`tool_choice: "required"` 转为原生 `any`，不会改成 `auto`。显式 `temperature`、`top_p` 也继续发送；这些参数与具体模型、thinking 的组合是否受支持由上游判断。静默删除参数或关闭 thinking 会改变用户请求，bridge 不做这类修正。
+
+有工具且未选择 `none` 时，显式 `parallel_tool_calls: false` 转为 `tool_choice.disable_parallel_tool_use: true`，显式 `true` 则转为 `false`；未指定 choice 时采用 `auto`，原生 options 仍可覆盖。这保留 Codex Lite 的外层工具调用限制，不限制一次 `exec` 内 JavaScript 的并发执行。[Claude 并行工具调用](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use)
+
+用户与工具结果都可带图片。HTTP(S) URL 和 JPEG、PNG、GIF、WebP 的 base64 data URL 转为原生 image block，bridge 不下载图片。图片能力、尺寸和 schema 限制交给上游，不能转换的内容类型明确报错。空工具结果仍发送 `tool_result` 及原调用 ID，只省略空的 `content` 数组，不添加占位文字。
+
+工具参数分片先拼接、解析，在对应 `content_block_stop` 按原顺序交给 writer 缓存，完整 `message_stop` 后才交付客户端。工具之后的 thinking 和文字一起缓冲，保留签名所依赖的块顺序。`tool_use`、`pause_turn` 返回 `end_turn: false`；输出截断或 refusal 返回失败，不交付部分工具调用。`model_context_window_exceeded` 转为 `context_length_exceeded`，同样不交付工具调用；后续是否压缩或重试由 codeks 决定。
+
+## 缓存与压缩
+
+最多四个显式缓存断点：最后一个工具、最后一段顶层 system、最近两条 user 消息的末块。普通请求 TTL 为 `1h`。压缩保留公共前缀的 `1h`，只将最后的摘要请求末块设为 `5m`，使长 TTL 位于短 TTL 之前。thinking 块不直接设置缓存断点。
+
+压缩只生成文字摘要，保留工具定义及普通请求的工具选择，移除 `output_config.format`，其他参数保留。摘要封装为客户端 V2 compaction item，可供其他模型恢复。保留工具选择的缓存依据及意外工具调用的处理见 [压缩](compaction.md#工具选择与缓存)。
+
+## Usage 与错误
+
+input 为 `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`，output 使用最终累计值，不累加流事件；可得的 thinking 用量记录到 reasoning 分项。缺失或无效的计数返回错误，不伪造零值。
+
+HTTP 与流内错误经共享层分类，同时保留上游原始错误体；未完整结束的流返回错误。bridge 不改参数重试，容量与限流退避由 codeks 决定。[错误结构](responses-stream.md)
+
+实现与测试：[`src/backends/anthropic.ts`](https://github.com/WAcry/codeks-bridge/blob/main/src/backends/anthropic.ts)、[`test/anthropic.test.ts`](https://github.com/WAcry/codeks-bridge/blob/main/test/anthropic.test.ts)。协议参考：[thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)、[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)、[缓存](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。

package/docs/backends-deepseek-chat.md

@@ -0,0 +1,75 @@
+# DeepSeek Chat
+
+模型设置 `catalog: "deepseek-flash"`，条目指定 `deepseek-chat` adapter，请求发送到 `<base_url>/chat/completions`。这个 adapter 明确使用 DeepSeek 方言：`reasoning_content`、thinking 参数和对应 usage。实际模型可以是 `deepseek-flash` 或第三方部署名称，bridge 不按名字猜测规则。
+
+```json
+{
+  "upstreams": {
+    "deepseek": {
+      "base_url": "https://api.deepseek.com",
+      "api_key_env": "DEEPSEEK_API_KEY"
+    }
+  },
+  "models": {
+    "flash": {
+      "upstream": "deepseek",
+      "catalog": "deepseek-flash",
+      "model": "deepseek-flash"
+    }
+  }
+}
+```
+
+目录的默认及最大上下文窗口为 `1000000`。输出预算使用上游默认值；请求中的 `max_output_tokens` 或模型配置可指定预算，请求值优先，并转为 `max_tokens`；原生 options 仍可覆盖。上游的输出预算包含 thinking 与可见输出；达到上限返回失败，不执行不完整工具调用。`base_url` 可包含 `/v1` 等前缀。[官方参数范围](https://api-docs.deepseek.com/api/create-chat-completion/)
+
+## Reasoning 与参数
+
+思考从 `delta.reasoning_content` 读取，作为 `reasoning.text.v1` 的字符串 data 保存。下次请求把允许来源的文本恢复到 assistant 的 `reasoning_content`。`reasoning.summary` 为 `auto`、`concise` 或 `detailed` 时，将原生 reasoning 文本作为可见摘要输出；缺省或 `none` 时不展示，但仍保存和回放载荷，不关闭 thinking。目录沿用 GPT-6.1 Sol 的摘要默认值 `none`；可在 codeks 中设置 `model_reasoning_summary = "auto"`。是否同模型、是否同上游都由来源策略决定，不能只凭文本格式推断应该共享。[复用配置](reasoning.md)
+
+没有可恢复 reasoning 的 assistant 历史使用 `reasoning_content: ""`，不编造思考。它使带有其他目标历史的工具循环仍具备 DeepSeek 要求的字段。
+
+默认 effort 为 `high`，默认映射如下：
+
+| 客户端 effort | 原生参数 |
+| --- | --- |
+| `none` | `thinking.type: "disabled"` |
+| `minimal`、`low` | `thinking.type: "enabled"`，`reasoning_effort: "low"` |
+| `medium`、`high`、`xhigh` | `thinking.type: "enabled"`，`reasoning_effort: "high"` |
+| `max`、`ultra` | `thinking.type: "enabled"`，`reasoning_effort: "max"` |
+
+codeks 的 `ultra` 由客户端注入多代理提示词，并使用原生 `max` effort。映射可由 `reasoning.effort_map` 整体替换，目录中可选档位来自同一配置。未映射的显式 effort 原样发送。上游和模型 `options` 随后覆盖推导参数，允许直接设置端点专有选项；桥接器最终固定 model、messages、工具定义、流模式和 usage 开关。
+
+强制工具选择、JSON Schema 与 thinking 能否组合由上游判断。bridge 转换可表达的请求后直接发送，上游不支持时保留错误，不自动关闭 thinking 或改成普通文本输出。
+
+## 消息、工具与图片
+
+Responses instructions 成为开头的 system 消息；历史 developer 在原位置转为 system。user、assistant、工具调用和结果保留顺序。同一次 assistant 输出的 reasoning、文字和并行工具调用合并为一条 Chat assistant 消息。
+
+工具结果使用 `role: "tool"` 和原 `tool_call_id`。namespace、自由文本工具及语法使用[共享工具转换](tools.md)。Responses JSON Schema 转为 Chat `response_format.json_schema`，JSON object 转为 `response_format: {type: "json_object"}`；schema 由上游验证。
+
+用户图片转为 `image_url`，支持 HTTP(S) 和 image data URL，`detail: "original"` 转为 `high`。工具结果文本保持 tool 消息，图片放在同组所有 tool 结果之后的 user 消息，标注来源 call ID；这样不打断并行调用与结果的配对。这会增加一个 user 边界，是转换的代价。
+
+assistant/system/developer 图片、文件 ID、音频和视频没有本轮转换路径，明确报错。图片的实际识别能力和尺寸限制交给模型端点。
+
+## 流、用量与压缩
+
+出站开启 `stream: true`、`stream_options.include_usage: true`。文字和启用展示的 reasoning 随到随发，工具参数按索引拼接，只有流结束且所有调用完整时才交给 codeks。未结束的连接、缺失 usage、未知工具或不完整参数不能构成成功响应。
+
+`stop` 完成，`tool_calls` 要求继续执行工具。`length` 和内容过滤返回错误；DeepSeek 的 `insufficient_system_resource`、`aborted` 归为容量错误。HTTP 与流内错误保留原始上游详情，bridge 不叠加重试。[错误结构](responses-stream.md)
+
+| DeepSeek 用量 | Responses 用量 |
+| --- | --- |
+| `prompt_tokens` | `input_tokens` |
+| `completion_tokens` | `output_tokens` |
+| `prompt_cache_hit_tokens`，或 `prompt_tokens_details.cached_tokens` | `input_tokens_details.cached_tokens` |
+| `completion_tokens_details.reasoning_tokens` | `output_tokens_details.reasoning_tokens` |
+
+reasoning 不重复加到总量中。压缩只生成文字摘要，仍由客户端远程 V2 通道接收；保留工具定义及普通请求的工具选择。参数保持与意外工具调用的处理见 [压缩](compaction.md#工具选择与缓存)。
+
+## 扩展方言
+
+[`src/backends/chat.ts`](https://github.com/WAcry/codeks-bridge/blob/main/src/backends/chat.ts) 负责 Chat 消息、工具和流转换，定义小型 `ChatDialect` 接口；[`src/backends/deepseek.ts`](https://github.com/WAcry/codeks-bridge/blob/main/src/backends/deepseek.ts) 提供 DeepSeek 的 reasoning 字段、thinking 参数、usage 和特殊结束原因。`deepseek-flash` 目录条目选择 `deepseek-chat` adapter，由后者调用前者。
+
+当前 Chat 转换层按单个文本字段读写 reasoning，包括为没有 reasoning 的 assistant 历史写入空字符串。这是现有 DeepSeek 路径需要的行为；接入其他模型时须按其协议决定能否复用。参数差异优先使用 profile 和 options；如果 reasoning 改为内容块或其他结构，再调整转换边界。当前没有其他 Chat 方言实现。
+
+验证见 [`test/chat.test.ts`](https://github.com/WAcry/codeks-bridge/blob/main/test/chat.test.ts)。协议参考：[Chat API](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion)、[思考模式](https://api-docs.deepseek.com/zh-cn/guides/thinking_mode)、[图片](https://api-docs.deepseek.com/zh-cn/guides/vision)。

package/docs/backends-responses.md

@@ -0,0 +1,33 @@
+# GPT Responses
+
+模型选择 GPT 目录 key，例如 `catalog: "gpt-6.1-sol"`，条目指定 `gpt-responses` adapter，bridge 向连接的 `/responses` 发请求。`base_url` 包含版本前缀，例如 `https://api.openai.com/v1`。实际模型名可以是任意部署别名，转换不依赖名称前缀。
+
+## 请求与参数
+
+普通 Responses 参数、namespace 和 custom grammar 工具保留原始格式，包括未知扩展字段；请求及响应 header 按 [HTTP 边界](responses-stream.md#header-与转发边界) 默认透传。模型名替换为配置的实际名称，reasoning effort 使用 profile 默认值和配置映射。`max_output_tokens` 优先使用请求值，再使用模型默认值。
+
+客户端默认发送 Responses Lite：工具声明保留在 `input[].additional_tools` 的原位置，不提升到顶层 `tools`。保留 `reasoning.context: "all_turns"` 和 `parallel_tool_calls: false`，并向所有 GPT 上游发送 Lite header。入口从客户端 header 或 `additional_tools` 识别 Lite；只有 header、没有工具的请求也能保持标记。后端不通过模型名称或云厂商猜测协议。
+
+随后浅层合并上游和模型 `options`，后者覆盖前者，也可覆盖推导出的普通参数。最后由 bridge 固定 `model`、`input`、`tools`、`store: false`、`stream: true`，`include` 至少包含 `reasoning.encrypted_content`。上游状态由完整历史承载，不依赖服务器保存的会话。
+
+历史 reasoning 按允许来源选择，将 `responses.reasoning.v1` 的 data 还原为原生密文；原生压缩按独立策略选择。每条输入项移除顶层 `id`，工具配对的 `call_id` 保留，避免引用已过滤的 reasoning。图片、普通消息、工具结果和明文 agent message 保留原格式。[状态规则](reasoning.md)
+
+## 流与工具交付
+
+桥接器消费 SSE，也接受完整 JSON response。原生事件和 response envelope 保留 ID、时间、usage 和未知元数据，只修改桥接所需字段。完整 JSON 或仅在终止事件提供的输出会补齐 item added/done，供客户端持久化。保留上游消息的 `phase`，包括 `partial_answer`；只有缺失时才按后续输出、工具和 `end_turn` 推断。摘要保留同一 item 内的分段索引及完整 summary 数组，不把多段压成一段。
+
+第一个工具之前的文字和摘要流式交付；从第一个工具起，所有事件作为有序后缀缓存，完整成功后释放。function call 保留 namespace，custom tool 保留原始输入。失败、截断和连接中断丢弃整个后缀，不让客户端执行未完成的工具调用，也不改变工具与后续消息的相对顺序。
+
+`end_turn` 有显式值时遵从上游，否则有工具调用时返回 false。成功响应的 input/output usage 必须是有效计数，cache read/write、reasoning 分项有则记录；reasoning 不重复叠加到 input。无效 usage 作为错误返回，避免影响 codeks 压缩判断。`response.incomplete` 原样保留原因与可用 usage，由客户端处理继续生成、内容过滤或截断，不统一改成可重试错误。
+
+上游成功响应头到达前，不建立下游 SSE。HTTP 失败保留原始 status、body 和诊断 header；流内错误保留完整 error 对象，不维护 GPT code 白名单。被允许的密文遭拒也直接返回，不自动过滤后重试。[错误结构](responses-stream.md)
+
+## 原生压缩
+
+默认 `compaction.mode: "native"` 向 `/responses` 发送保留 `compaction_trigger` 的请求，保存原生检查点及复述配方。目标需要文字表示时，原来源读取后续请求中实际保留的历史与原生检查点，使用 handoff prompt 复述，并缓存成功结果。若端点只适合文字压缩，显式设置 `mode: "summary"`，使用标准 prompt 汇总原历史。
+
+原生请求移除普通回答的 `max_output_tokens`，包括配置和 options 中的值，由上游管理压缩输出预算。摘要仍使用普通预算，保留工具定义和工具选择，移除结构化输出格式；工具调用的失败语义见 [压缩](compaction.md#工具选择与缓存)。
+
+是否生成原生压缩与是否恢复原生检查点独立。配置 `native_replay` 和 `native_compaction_from` 后，格式可读且来源允许的原生状态优先发送；上游拒绝即报错。[压缩配置](compaction.md)
+
+实现与测试：[`src/backends/responses.ts`](https://github.com/WAcry/codeks-bridge/blob/main/src/backends/responses.ts)、[`test/responses.test.ts`](https://github.com/WAcry/codeks-bridge/blob/main/test/responses.test.ts)。