# 给 AI 助手

> llms.txt、整份文档与单页的 Markdown 形态，一键复制入口，以及供 AI 编程助手使用的提示词与接入要点。

来源：https://www.scirouter.cn/docs/llms · 更新于 2026-10-24

文档提供供 AI 编程助手（Claude、ChatGPT、Cursor、Copilot 等）读取的 Markdown 形态。将文档交给助手后，助手可据此编写接入 SciRouter 的代码。

## 三种形态

| 地址 | 内容 | 适用场景 |
|---|---|---|
| [`/llms.txt`](https://www.scirouter.cn/llms.txt) | 目录：每一页的标题、一句话说明与 Markdown 地址 | 可联网的助手按需读取 |
| [`/llms-full.txt`](https://www.scirouter.cn/llms-full.txt) | 全部接口文档合并为一个 Markdown 文件，开头附「接入要点」 | 一次性提供给助手，最常用 |
| `/docs/<页面>.md` | 单页 Markdown，例如 [`/docs/quickstart.md`](https://www.scirouter.cn/docs/quickstart.md) | 只需要某一页时 |

`llms.txt` 的格式遵循 [llmstxt.org](https://llmstxt.org) 的约定。所有链接均为绝对地址，代码示例中的 base URL 已替换为本站的实际地址。

`llms-full.txt` 只收录编写接入代码所需的页面。「网页端指南」（站内 Chat、课题）面向在网页上操作的用户，不收入该文件；这些页面仍有单页 `.md`，列在 `llms.txt` 的 Optional 部分。

## 一键复制

| 位置 | 按钮 | 复制的内容 |
|---|---|---|
| 每一页标题下方 | 「复制 Markdown」 | 该页的 Markdown 原文，含标题、来源地址与更新日期 |
| 文档首页 | 「复制全部接口文档」 | 与 `/llms-full.txt` 相同 |

复制后粘贴到助手的对话框，再写明要实现的功能。

## 提示词示例

```text
以下是 SciRouter（兼容 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 三种格式的科研模型 API）的完整接口文档。
先读「接入要点」，然后实现：<要实现的功能，例如「给 FastAPI 服务加一个调用 <模型 id> 的接口，流式返回给前端」>。

要求：
- API Key 从环境变量 SCIROUTER_API_KEY 读取，不写进代码；
- 错误按 error.code 分支，按文档区分可重试与不可重试的错误；
- 流式请求处理两种失败：未收到 [DONE] 就结束、收到错误分片；
- 模型 id 使用我给出的，不自行编造；
- 不调用文档中没有的接口。

<粘贴复制的文档>
```

最后一条要求用于防止助手按调用 OpenAI 的习惯，使用 Assistants 等平台不提供的接口。

## 接入要点

`llms-full.txt` 的开头即为以下内容。不提供整份文档时，仅提供本节内容也可让助手写出可用的初版代码。

- base URL：`https://api.scirouter.cn/v1`。兼容 OpenAI 格式，另支持 Anthropic Messages 与 OpenAI Responses 格式。共十个接口：`GET /models`、`GET /models/{model_id}`、`POST /chat/completions`、`POST /embeddings`；OpenAI Images 格式的 `POST /images/generations`、`POST /images/edits`（multipart）、`POST /images/variations`，只能调用生图模型（`/models` 中 `scirouter.kind` 为 `image` 的模型）；OpenAI Responses 格式的 `POST /responses`，无状态：`store` 只接受 false，不支持 `previous_response_id` / `background`；Anthropic 格式的 `POST /messages`、`POST /messages/count_tokens`（Anthropic SDK 自行拼接 `/v1`，其 base URL 只写到域名）。旧的 `/completions`、Assistants、语音、按 id 操作已保存响应等接口不存在，返回 404。`model` 必须是具体的模型 id（或平台为其配置的别名），不提供 `auto` 这类虚拟模型。
- 认证：`Authorization: Bearer <API Key>` 或 `x-api-key: <API Key>`，同时携带时须为同一个 Key；不接受其他写法（Cookie、查询参数、`api-key` 请求头）。Key 格式为 `sk-sr-` 加 40 位字母数字，三种格式均只接受该 Key；OpenAI、Anthropic 等厂商的 Key 返回 401（平台自行鉴权、计费，以平台的凭据调用厂商）。Key 从环境变量（如 `SCIROUTER_API_KEY`）读取，不写入代码，不放入浏览器、App 等前端。
- 模型 id：格式为 `厂商/模型名`，从 `GET /models` 获取，原样填入 `model`。列表已按该 Key 的权限过滤（Key 与项目的白名单、套餐、受限模型的授权），列出的模型均有调用权限；唯一例外是维护中的模型（503 `model_unavailable`）。
- 错误：OpenAI 格式为 `{"error": {"message", "type", "code", "scirouter_code", "param", "request_id", "details"}}`。按小写的 `error.code` 分支，不按 `message` 判断。三个上游语义错误（400 `context_window_exceeded` / `unsupported_param` / `content_filtered`）的 `error.code` 为原厂兼容值（`context_length_exceeded` / `unsupported_parameter` / `content_filter`），平台码在 `error.scirouter_code`。403 的 `details.scope`（`key` / `project` / `plan`）指明拦截请求的白名单层级。`/messages` 两个接口使用 Anthropic 格式 `{"type": "error", "error": {"type", "message", "code", "details"}, "request_id"}`，状态码与 `error.code` 同上。
- 应重试（指数退避，遵守 `Retry-After`，设重试上限）：429 `rate_limited`、429 `upstream_saturated`、502 `upstream_error`、503 `model_unavailable`（仅限带 `Retry-After` 时；不带时属于 `details.reason` 为 `tools_unsupported` 一类，重试无效）、504 `upstream_timeout`、409 `idempotency_conflict`（同一个键的请求仍在处理中；同一个键对应不同请求体也返回该码，有限次重试后仍为 409 时停止）。套餐日上限触发的 `rate_limited`，`Retry-After` 指向次日零点。
- 不应重试：其余 4xx。包括 400 `context_window_exceeded`（缩短输入或调小 `max_tokens`）、400 `unsupported_param`（`error.param` 指出无法传递的参数；请求中有只能原样转发的内容而没有可用线路时，`details.reason` 为 `unsupported_content`）、402 `insufficient_quota`（预扣不足）、429 `key_quota_exceeded`（Key 的月度上限，创建后不能修改，次月恢复或更换 Key）、429 `project_budget_exceeded`（项目月预算，`Retry-After` 指向次月 1 日，可在控制台调高）。
- 流式：跳过以 `:` 开头的注释行（心跳 `: ping`）；`choices` 可能为空数组；出错时发送一个 `{"error": …}` 分片后断开。**未收到 `data: [DONE]` 的流一律按失败处理**，即使 HTTP 状态为 200。`/messages` 的流按 Anthropic 的事件格式发送（带 `event:` 行），以 `message_stop` 结束，没有 `[DONE]`；出错时为 `event: error`，未收到 `message_stop` 同样按失败处理。非流式请求最长等待约 270 秒（超时返回 504 `upstream_timeout`，不计费），回答耗时可能超过该时长时使用流式。
- 思考过程：`/chat/completions` 中，推理模型的思考过程同时出现在 `reasoning_content` 与 `reasoning` 两个字段（内容相同），非流式在 `message` 中，流式在 `delta` 中；`/messages` 中为 Anthropic 格式的 `thinking` 块。
- 参数：每个参数到线路上只有四种处理结果，即原样传递、翻译、平台模拟、明确告知。提示类参数（采样、思考强度、缓存提示）无法传递时被去掉，并在响应头 `X-SciRouter-Param-Actions` 留痕（如 `dropped=seed,top_k; translated=reasoning`），不报错；契约类参数（结构化输出、工具、`n`、`logprobs`）依次尝试翻译、模拟、换线路，均不可行时返回 400 `unsupported_param`。请求头 `X-SciRouter-Unsupported-Params: strict` 使提示类参数也返回 400，`lenient` 使契约类参数也被去掉。`GET /models` 的 `scirouter.supported_params` / `emulated_params` 为模型的能力自述。
- 截断与预扣：`finish_reason` 为 `length` 表示回答被 `max_tokens` 截断。`/chat/completions` 的 `max_tokens` 超过模型或套餐上限时返回 400（`details.limit` 给出上限），不自动截短；`/messages` 超过上限时按上限发出，响应头 `X-SciRouter-Max-Tokens-Clamped` 写明请求值与实际值。预扣按输入估算加输出上限冻结配额（账户充值余额大于 0 时输出只按输出上限与平台设定值中的较小者估算），结束后按实际用量结算，实际超出的部分照扣。
- 幂等：非流式的 `/chat/completions`、`/messages`、`/responses` 与 `/embeddings` 请求可带 `Idempotency-Key` 请求头（不超过 128 字节，作用域为该 Key，保留 24 小时，重试时请求体须逐字节相同）。服务端已处理完成、仅响应在传输中丢失时，同键重试直接重放结果，不再扣费；请求由调用方先断开时，服务端取消且不保存结果，重试会重新计费。图片接口也接受该请求头，`b64_json` 与流式的结果不保存，同键再请求返回 409 `idempotency_conflict`。
- 报障：记录响应头 `X-Request-Id`（错误体中也有 `request_id`）。