ozon-seller-mcp 2.2.0 → 2.3.1

package/README.md

@@ -37,7 +37,8 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
-| `OZON_CLIENT_ID` / `OZON_API_KEY` | — | 店铺凭证，必填 |
+| `OZON_CLIENT_ID` / `OZON_API_KEY` | — | 单店凭证；只有一家店时用 |
+| `OZON_SHOPS` | — | 多店铺：JSON 数组，见下方「多店铺」；填了它就不再读单店的 4 个凭证变量 |
 | `OZON_READ_ONLY` | `true` | `false` 才允许写操作；其他值启动报错，拼写错误不会开放写入 |
 | `OZON_TOOLSET` | `core` | `core` 常用工具；`minimal` 只要组合工具和通用工具；`all` 全部接口；可追加接口路径或工具名，逗号分隔，如 `core,/v1/returns/list` |
 | `OZON_COMPACT` | `true` | 结果省略 null、空字符串、空数组、空对象 |
@@ -50,6 +51,32 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 修改后需要重启 MCP。
 
+## 多店铺
+
+一个 MCP 连多家店：`OZON_SHOPS` 填一个 JSON 数组，每家店一项。
+
+```json
+"env": {
+  "OZON_SHOPS": "[{\"name\":\"shop-a\",\"client_id\":\"…\",\"api_key\":\"…\",\"perf_client_id\":\"…@advertising.performance.ozon.ru\",\"perf_client_secret\":\"…\",\"market\":true,\"default\":true},{\"name\":\"shop-b\",\"client_id\":\"…\",\"api_key\":\"…\",\"perf_client_id\":\"…\",\"perf_client_secret\":\"…\"}]",
+  "OZON_READ_ONLY": "true"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 店铺名，1～32 个字母、数字、汉字、`_`、`-`，不能重复；调用时用它选店 |
+| `client_id` / `api_key` | 二选一 | 该店的 Seller API 凭证，两项要么都填要么都不填 |
+| `perf_client_id` / `perf_client_secret` | 二选一 | 该店的广告凭证，两项要么都填要么都不填；每家店至少填一组凭证（只做广告的店可以不填 Seller API） |
+| `access_token` | 否 | 该店的 Ozon Delivery OAuth 令牌 |
+| `default` | 否 | `true` = 调用不指定店铺时用它；不标就用第一项 |
+| `market` | 否 | `true` = 市场数据店，最多一家；没有店标它时，市场数据接口就用调用时选的那家店 |
+
+- 访问 Ozon 的工具（含组合工具、广告工具）都多一个可选参数 `shop`（店铺名），不填用默认店。结果里的 `shop` 字段写明实际用哪家店的凭证查的。只在本地运行的工具（`ozon_status`、目录、说明、校验、报告）没有这个参数。
+- **市场数据固定走 `market` 店**：类目大盘 `/v1/analytics/category/comparison`、全站热搜词 `/v1/search-queries/top`、`/v1/search-queries/text` 要 Premium Pro 订阅，结果和查询的店铺无关，所以不论 `shop` 填哪家，都用市场数据店的凭证查。本店相关的数据（销量、商品搜索词、价格指数、广告）一律用各自店的凭证。
+- 限流和 5 分钟读缓存按店铺（Client-Id）分开计；广告令牌每家店各一个。
+- 配置有错（JSON 不合法、缺凭证、重名、未知字段、两家店填了同一个 `client_id` / `perf_client_id`、两家都标 `market`）启动时直接报错，报错只说第几项哪个字段，不回显密钥。所有店的密钥都会从结果和报错里隐藏。
+- `ozon_status` 列出每家店的名称、Client-Id、是否默认 / 市场店、是否配了 Seller API / 广告凭证，不含密钥。
+
 ## 通过节点访问 Ozon
 
 国内网络直连 Ozon 经常不通。把节点链接填进 `OZON_PROXY` 即可，不用另装代理软件：
@@ -95,6 +122,8 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 \* 2026-10-26 在一家约 480 个商品的店铺实测，从国内网络访问。
 
+营收 `revenue`（来自 `/v1/analytics/data`）单位是卢布，结果里带 `revenue_currency: "RUB"`；商品价格 `price`/`old_price`/`min_price` 是店铺结算币种（可能是 CNY），见 `price_currency`（旧字段 `currency` 保留，值相同）。两者不要直接相加或相除。
+
 ### 通用工具
 
 | 工具 | 用途 |
@@ -131,7 +160,7 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 | `ozon_ads_api_catalog` | 搜索全部 48 个广告接口 + 官方说明中给出的 12 个 `/json` 报表版本，或查看单个接口的参数与响应定义 |
 | `ozon_ads_api_call` | 按路径调用任一广告接口：路径参数和查询参数放 `params`，请求体放 `body` |
 
-- `ozon_ads_stats` 的活动汇总来自 `/api/client/statistics/campaign/product/json`（同步，不消耗限额）；商品明细来自异步活动报表 `/api/client/statistics/json`（每次最多 10 个活动，同一账号同时只生成 1 个，最多等 90 秒），包含本期内已移出活动的商品。`include_products=false` 只看活动汇总
+- `ozon_ads_stats` 的活动汇总来自 `/api/client/statistics/campaign/product/json`（同步，不消耗限额）；商品明细来自异步活动报表 `/api/client/statistics/json`（每次最多 10 个活动，同一账号同时只生成 1 个，最多等 90 秒），包含本期内已移出活动的商品。同一进程内同一广告账号的报表逐个生成：本服务记住每个广告账号最近提交的报表（UUID、提交时间），下一次提交前（`ozon_ads_stats` 和 `ozon_ads_api_call` 的报表提交，含外部流量报表）先在本次调用内查它的状态，等到 OK/ERROR（外部流量报表还有 TIMEOUT/CANCEL）或它已提交满 120 秒；查询失败不算完成，每次查询也受上一份报表剩余的等待上限约束。本次调用的时间预算内没等到就不提交并返回提示。报表提交不自动重试；已发出但结果未知（连接中断、超时、5xx）时，按“可能正在生成”处理，下一次提交等它满 120 秒。没有任何后台任务；相同查询同时进行时共用一份报表。`ozon_ads_stats` 整次调用（活动列表、汇总、取令牌、等待、重试、报表）共用一个 90 秒期限，超时即取消，不再发出后续请求。`include_products=false` 只看活动汇总
 - `/api/client/statistics/products/sku` 实测只接受今天或昨天（Ozon 返回 `date range must contain only today or yesterday`），所以不用于多天统计
 - `OZON_READ_ONLY=true` 时，改出价、启停活动、增删商品、开关“按订单付款”等 16 个写接口在发送前拦截（包括 `GET /api/client/campaign/all_sku_promo/activate` 这类用 GET 做写操作的接口）
 - 官方限制：每天总计 100 000 次；统计报表同一账号同时只能生成 1 个、一次最多 10 个活动、最长 62 天
@@ -158,13 +187,14 @@ Windows 上如果客户端找不到 `npx`，把 `command` 改为 `"cmd"`，`args
 
 其他接口文档未写具体数字，Ozon 仍可能返回 429。
 
-本地保护：同一进程内超出上述窗口时直接返回“约 N 秒后可再调用”，不发请求；限流接口的相同只读请求 5 分钟内返回缓存（`from_cache: true`）。本地计数只统计当前进程（含被 Ozon 拒绝的调用），以 Ozon 服务端为准。只读请求遇到 429/502/503/504 且 `Retry-After` ≤ 5 秒时重试一次；写请求从不自动重试。
+本地保护：同一进程内超出上述窗口时直接返回“约 N 秒后可再调用”，不发请求；限流接口的相同只读请求 5 分钟内返回缓存（`from_cache: true`）。本地计数只统计当前进程（含被 Ozon 拒绝的调用），以 Ozon 服务端为准。只读请求遇到 429/502/503/504 且 `Retry-After`（秒数或 HTTP 日期）≤ 5 秒时重试一次；每次实际发送（含重试、等过冷却之后）在发出前一刻计入上述窗口，并受每个账号的重试额度限制（并发失败时不会把请求量翻倍），等待时间加少量随机抖动。写请求从不自动重试。Ozon 返回 429 后，同一账号（同一 Client-Id 或广告 Client ID）的后续请求都先等过 `Retry-After`（最多按 60 秒计）：剩余不超过 5 秒就等待后发送，更长则直接返回“约 N 秒后可再调用”；有独立限额的接口（上表）只冷却该接口本身。
 
 **实测注意**：`/v1/analytics/data` 带 `sort` 参数的请求在 2026-10-26 连续被 Ozon 以“每秒限流”拒绝，同样的请求不带 `sort` 正常。`ozon_top_products` 因此不传 `sort`，一次取 1000 个 SKU 后本地排序。
 
 ## 参数校验
 
-- 必填、类型、嵌套、枚举、上下限、数组约束、日期与 int32/int64/uint64 格式、未知字段，发送前全部校验
+- 必填、类型、嵌套、枚举、上下限、数组约束、日期、date-time（RFC 3339，须带时区，如 `2026-10-01T00:00:00Z`；闰秒只接受 UTC 23:59:60）与 int32/int64/uint64 格式、未知字段，发送前全部校验。少数字段（如 `/v1/finance/balance` 的 `date_from`）规范类型是 date-time、说明和官方示例却是 `YYYY-MM-DD`，这些字段两种写法都接受
+- 整数参数超出 ±9007199254740991 时直接拒绝：JSON 解析时这类数字已被舍入（9007199254740993 会变成 …992），照发可能作用到别的对象
 - 482 个 schema 与原 Python 版逐个比对一致（3114 个校验用例结论相同），以下 8 处除外
 - 官方规范有 8 个 schema 把某字段列为必填、却没有定义该字段（如 `/v2/products/stocks` 的 `quant_size`，`/v1/cargoes/label/transport/status` 的 `operation_idd`），原实现因此无法调用这些接口。现在这些字段改为“已声明、不校验类型”的可选字段，说明里注明官方列为必填，最终以 Ozon 返回为准
 - 官方 `type=null` 的字段禁止传入，不猜测类型；`int`/`bool` 等书写错误按无歧义方式规范化

package/bin/ozon-seller-mcp.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // MCP stdio entry. stdout carries JSON-RPC only; diagnostics go to stderr.
+import { redactText } from '../src/privacy.js';
 import { VERSION } from '../src/version.js';
 
 const args = process.argv.slice(2);
@@ -11,7 +12,11 @@ if (args.includes('--version') || args.includes('-v')) {
 用法：npx -y ozon-seller-mcp
 
 环境变量：
-  OZON_CLIENT_ID, OZON_API_KEY   店铺凭证（必填）
+  OZON_CLIENT_ID, OZON_API_KEY   单店凭证（只有一家店时用）
+  OZON_SHOPS                     多店铺：JSON 数组，每项 {"name","client_id","api_key",
+                                 "perf_client_id"?,"perf_client_secret"?,"access_token"?,"market"?,"default"?}；
+                                 填了它就不再读上面的单店变量。"market": true 的店负责
+                                 类目大盘、全站热搜词（需 Premium Pro）；工具多一个 shop 参数
   OZON_READ_ONLY                 true（默认，只读）/ false（允许写入）
   OZON_TOOLSET                   core（默认）/ all / minimal / 追加接口路径，逗号分隔
   OZON_COMPACT                   true（默认，省略空值字段）/ false
@@ -25,14 +30,15 @@ if (args.includes('--version') || args.includes('-v')) {
 `);
 } else {
   // A stray error must not kill the server mid-conversation; log it to stderr and keep serving.
-  const report = (kind) => (error) => process.stderr.write(`[ozon-seller-mcp] ${kind}: ${error?.stack ?? error}\n`);
+  // Logged text goes through the same redaction as tool results (configured keys, ad tokens).
+  const report = (kind) => (error) => process.stderr.write(`[ozon-seller-mcp] ${kind}: ${redactText(error)}\n`);
   process.on('unhandledRejection', report('unhandledRejection'));
   process.on('uncaughtException', report('uncaughtException'));
   try {
     const { main } = await import('../src/server.js');
     await main();
   } catch (error) {
-    process.stderr.write(`[ozon-seller-mcp] 启动失败：${error?.message ?? error}\n`);
+    process.stderr.write(`[ozon-seller-mcp] 启动失败：${redactText(error?.message ?? error)}\n`);
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozon-seller-mcp",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Ozon Seller API + Performance (ads) API MCP server: 482 seller endpoints, 48 advertising endpoints, one-call composite queries, read-only by default, strict schema validation.",
   "keywords": [
     "mcp",

package/src/ads/http.js

@@ -1,116 +1,205 @@
 // Performance API transport: client-credentials token, path/query parameters, JSON or CSV responses.
 // Shares the proxy setting and socket pool with the Seller API transport.
 import { OzonError, ValidationError } from '../errors.js';
-import { currentFetch, describeNetworkError, getDispatcher, parseJson, readCapped, sleep } from '../http.js';
-import { redact } from '../privacy.js';
+import {
+  RETRY_STATUSES, WRITE_UNKNOWN, currentFetch, describeNetworkError, discardBody, getDispatcher, parseJson, readErrorText, readResponse,
+  sleep,
+} from '../http.js';
+import { forgetTokens, holdToken, redact, rememberToken } from '../privacy.js';
+import {
+  DEFAULT_RETRY_MS, MAX_RETRY_WAIT_MS, admitRetry, admitSend, awaitCooldown, checkAdmission, noteRateLimited, parseRetryAfter,
+  withJitter,
+} from '../ratelimit.js';
 import { enforceMode } from '../schema.js';
+import { currentShop, hasAds, shops } from '../shops.js';
 import { VERSION } from '../version.js';
 import { parseCsv } from './csv.js';
 import { SAFE_PATH_VALUE, pathParamNames, validateAdsRequest } from './schema.js';
-import { ADS_BASE_URL, findAdsOperation } from './spec.js';
+import { ADS_BASE_URL, findAdsOperation, isReportSubmit } from './spec.js';
 
 const HOST = new URL(ADS_BASE_URL).host;
 const TOKEN_PATH = '/api/client/token';
+const TOKEN_OP = Object.freeze({ path: TOKEN_PATH });
 const USER_AGENT = `Ozon-Seller-MCP/${VERSION}`;
 const TOKEN_MARGIN_MS = 60_000;
 const DEFAULT_TOKEN_TTL_MS = 30 * 60_000;
 const MAX_BODY = 2_000_000;
-const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+// A token request serves every caller of the account, so no single caller's budget cancels it;
+// it has its own limit instead.
+const TOKEN_TIMEOUT_MS = 30_000;
 const SAFE_SEGMENT = new RegExp(SAFE_PATH_VALUE);
 
 export const CREDENTIAL_HELP = '在卖家后台 设置 → API 密钥 → Performance API 创建服务账号并添加密钥，'
   + '把 Client ID（以 @advertising.performance.ozon.ru 结尾）和 Client Secret 分别填到 MCP env 的 OZON_PERF_CLIENT_ID、OZON_PERF_CLIENT_SECRET，然后重启 MCP。'
   + '它和 OZON_CLIENT_ID / OZON_API_KEY（Seller API）不是同一组凭证。';
 
-let cachedToken = null;
-let pendingToken = null;
+// One token per Performance client: shops alternating in one process must not evict each other's token.
+const cachedTokens = new Map();
+const pendingTokens = new Map();
 
 export function resetAdsToken() {
-  cachedToken = null;
-  pendingToken = null;
+  cachedTokens.clear();
+  pendingTokens.clear();
+  forgetTokens();
 }
 
-export const adsConfigured = () => Boolean((process.env.OZON_PERF_CLIENT_ID ?? '').trim() && (process.env.OZON_PERF_CLIENT_SECRET ?? '').trim());
+// True when any shop has Performance API credentials (the ads tools are listed then).
+export const adsConfigured = () => shops().some(hasAds);
 
 function adsCredentials() {
-  const clientId = (process.env.OZON_PERF_CLIENT_ID ?? '').trim();
-  const secret = (process.env.OZON_PERF_CLIENT_SECRET ?? '').trim();
-  if (!clientId || !secret) throw new OzonError(`广告数据需要 Performance API 凭证，OZON_PERF_CLIENT_ID / OZON_PERF_CLIENT_SECRET 未配置。${CREDENTIAL_HELP}`);
-  if (/[\r\n]/.test(clientId + secret)) throw new OzonError('Performance API 凭证包含无效换行，请检查 MCP 环境变量。');
-  return { clientId, secret };
+  const shop = currentShop();
+  if (!hasAds(shop)) {
+    throw new OzonError(shop.legacy
+      ? `广告数据需要 Performance API 凭证，OZON_PERF_CLIENT_ID / OZON_PERF_CLIENT_SECRET 未配置。${CREDENTIAL_HELP}`
+      : `店铺「${shop.name}」没有配置广告凭证（perf_client_id / perf_client_secret）。`);
+  }
+  if (/[\r\n]/.test(shop.perfClientId + shop.perfSecret)) throw new OzonError('Performance API 凭证包含无效换行，请检查 MCP 环境变量。');
+  return { clientId: shop.perfClientId, secret: shop.perfSecret, shop };
 }
 
-// Bearer tokens are credentials too: hide the one a request used as well as the current one.
-function hideTokens(text, ...tokens) {
-  return [...tokens, cachedToken?.value].filter(Boolean).reduce((out, token) => out.replaceAll(token, '[已隐藏令牌]'), String(text));
+// Rate-limit scope of a Performance account: its 429 cooldown and retry budget are its own,
+// separate from the Seller account of the same shop.
+const accountScope = (clientId) => `perf:${clientId}`;
+
+// The Performance client of the shop this call runs as. Not a secret (ozon_status shows it).
+export const adsAccount = () => adsCredentials().clientId;
+
+// A time limit for one call: `signal` aborts after `ms`. The timer never keeps the process alive
+// on its own (unref) and done() clears it once the work has settled.
+export function timeLimit(ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  timer.unref?.();
+  return { signal: controller.signal, deadline: Date.now() + ms, done: () => clearTimeout(timer) };
 }
 
-function scrubTokens(data, token) {
-  const text = JSON.stringify(data);
-  const hidden = hideTokens(text, token);
-  return hidden === text ? data : JSON.parse(hidden);
+const NOT_SENT = '已超过本次调用的时间预算，请求未发送。';
+const notSent = () => new OzonError(NOT_SENT);
+
+// Marks a failure of a request's own exchange, after it went out, without a definite answer from
+// Ozon: a network error or cancellation during the fetch, an unreadable success body, or a 5xx. Such
+// a request may have been carried out (e.g. a report may be being built). Failures before it was
+// sent (budget, cooldown, the token phase) and definite refusals (3xx, 4xx) carry no mark.
+const outcomeUnknown = (error) => Object.assign(error, { outcomeUnknown: true });
+// send() tags failures of the fetch itself; only execute() turns that into outcomeUnknown, for the
+// request it was asked to make. A token request's network error never marks a report submission.
+const fetchFailed = (error) => Object.assign(error, { fetchFailed: true });
+
+// Settles like `promise`, or rejects once `signal` aborts, whichever comes first: a request, a body
+// or a wait that hangs cannot outlive its caller's time budget, whatever the fetch implementation
+// does. A rejection of `promise` after the race was lost is handled here, never left unhandled.
+export function untilAborted(promise, signal, message = NOT_SENT) {
+  const raced = Promise.resolve(promise);
+  if (!signal) return raced;
+  raced.catch(() => {});
+  if (signal.aborted) return Promise.reject(new OzonError(message));
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new OzonError(message));
+    signal.addEventListener('abort', abort, { once: true });
+    raced.then((value) => {
+      signal.removeEventListener('abort', abort);
+      if (signal.aborted) abort();
+      else resolve(value);
+    }, (error) => {
+      signal.removeEventListener('abort', abort);
+      reject(error);
+    });
+  });
 }
 
-async function send(url, init, agent, { write = false } = {}) {
+// Every send waits out the account's shared 429 cooldown, then, right before it goes out, is
+// dropped if the caller's budget is used up, or checked and counted by the limiter. Bearer tokens
+// in a failure message are hidden by redact(), which knows every token issued in this process.
+async function send(url, init, agent, { write = false, scope, op, signal } = {}) {
+  try {
+    await awaitCooldown(op, scope, signal);
+  } catch (error) {
+    throw signal?.aborted ? notSent() : error;
+  }
+  if (signal?.aborted) throw notSent();
+  admitSend(op, Date.now(), scope);
   const sentAt = performance.now();
   try {
-    return await currentFetch()(url, { ...init, redirect: 'manual', dispatcher: agent });
+    return await untilAborted(currentFetch()(url, { ...init, redirect: 'manual', dispatcher: agent, signal }), signal);
   } catch (error) {
-    throw new OzonError(describeNetworkError(error, performance.now() - sentAt, HOST)
-      + (write ? ' 写入结果未知，请先查询业务状态，不要自动重试。' : ''));
+    if (signal?.aborted) throw fetchFailed(new OzonError(`等待 Ozon 响应超时，已取消请求。${write ? WRITE_UNKNOWN : ''}`));
+    throw fetchFailed(new OzonError(describeNetworkError(error, performance.now() - sentAt, HOST) + (write ? WRITE_UNKNOWN : '')));
   }
 }
 
-async function rejectRedirect(response, path) {
+function rejectRedirect(response, path) {
   if (response.status >= 300 && response.status < 400) {
-    await response.body?.cancel().catch(() => {});
+    discardBody(response);
     throw new OzonError(`HTTP ${response.status} ${path}：Ozon 返回重定向，为保护凭证未跟随。`);
   }
 }
 
-const errorText = async (response, token) => hideTokens(redact((await response.text().catch(() => '')).slice(0, 2000)), token);
+const errorText = (response, write = false) => readErrorText(response, write, 2000);
 
-async function requestToken({ clientId, secret }, agent) {
+async function requestToken(credentials, agent) {
+  const limit = timeLimit(TOKEN_TIMEOUT_MS);
+  try {
+    return await untilAborted(fetchToken(credentials, agent, limit.signal), limit.signal, 'Performance API 授权请求超时，已取消。');
+  } finally {
+    limit.done();
+  }
+}
+
+async function fetchToken({ clientId, secret, shop }, agent, signal) {
+  const scope = accountScope(clientId);
   const response = await send(ADS_BASE_URL + TOKEN_PATH, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': USER_AGENT },
     body: JSON.stringify({ client_id: clientId, client_secret: secret, grant_type: 'client_credentials' }),
-  }, agent);
+  }, agent, { scope, op: TOKEN_OP, signal });
   await rejectRedirect(response, TOKEN_PATH);
+  if (response.status === 429) {
+    // The token endpoint shares the account's cooldown: every caller waits instead of asking again.
+    const delay = parseRetryAfter(response.headers.get('retry-after')) ?? DEFAULT_RETRY_MS;
+    noteRateLimited(TOKEN_OP, scope, delay);
+    throw new OzonError(`Performance API 授权接口限流（HTTP 429）：Retry-After=${Math.ceil(delay / 1000)} 秒，请告知用户稍后再查，不要重复重试。 `
+      + await errorText(response));
+  }
   if (!response.ok) {
+    const fields = shop.legacy ? 'OZON_PERF_CLIENT_ID 和 OZON_PERF_CLIENT_SECRET' : `店铺「${shop.name}」的 perf_client_id 和 perf_client_secret`;
     const hint = response.status < 500
-      ? `检查 OZON_PERF_CLIENT_ID 和 OZON_PERF_CLIENT_SECRET 是否完整、密钥是否已被删除。${CREDENTIAL_HELP}`
+      ? `检查 ${fields} 是否完整、密钥是否已被删除。${shop.legacy ? CREDENTIAL_HELP : ''}`
       : 'Ozon 授权服务暂时不可用，稍后再试。';
     throw new OzonError(`Performance API 授权失败（HTTP ${response.status}）：${hint} ${await errorText(response)}`);
   }
-  let data;
-  try {
-    data = parseJson((await readCapped(response)).toString('utf8'));
-  } catch {
-    throw new OzonError('Performance API 授权服务返回了无法解析的内容。');
-  }
+  const data = await readResponse(response, false, (raw) => {
+    try {
+      return parseJson(raw.toString('utf8'));
+    } catch {
+      throw new OzonError('Performance API 授权服务返回了无法解析的内容。');
+    }
+  });
   if (typeof data?.access_token !== 'string' || !data.access_token) throw new OzonError('Performance API 授权响应缺少 access_token。');
   const ttl = Number(data.expires_in) > 0 ? Number(data.expires_in) * 1000 : DEFAULT_TOKEN_TTL_MS;
+  // Registered before first use, so no output or log line can carry it unredacted.
+  rememberToken(data.access_token, Date.now() + ttl);
   return { clientId, value: data.access_token, expiresAt: Date.now() + Math.max(ttl - TOKEN_MARGIN_MS, ttl / 2) };
 }
 
-// `rejected` is the token that just got a 401: a newer cached token is reused, otherwise a new one is fetched.
-async function getToken(credentials, agent, rejected) {
-  const usable = cachedToken && cachedToken.clientId === credentials.clientId
-    && cachedToken.value !== rejected && Date.now() < cachedToken.expiresAt;
-  if (usable) return cachedToken.value;
-  if (!pendingToken || pendingToken.clientId !== credentials.clientId) {
+// `rejected` is the token that just got a 401: a newer cached token is reused, otherwise a new one is
+// fetched. The caller waits within its own budget (`signal`); the shared request is not cancelled.
+async function getToken(credentials, agent, rejected, signal) {
+  const { clientId } = credentials;
+  const cached = cachedTokens.get(clientId);
+  if (cached && cached.value !== rejected && Date.now() < cached.expiresAt) return cached.value;
+  if (signal?.aborted) throw notSent();
+  if (!pendingTokens.has(clientId)) {
     const promise = requestToken(credentials, agent)
       .then((token) => {
-        cachedToken = token;
+        cachedTokens.set(clientId, token);
         return token.value;
       })
       .finally(() => {
-        if (pendingToken?.promise === promise) pendingToken = null;
+        if (pendingTokens.get(clientId) === promise) pendingTokens.delete(clientId);
       });
-    pendingToken = { clientId: credentials.clientId, promise };
+    pendingTokens.set(clientId, promise);
   }
-  return pendingToken.promise;
+  return untilAborted(pendingTokens.get(clientId), signal);
 }
 
 function buildUrl(op, params) {
@@ -135,9 +224,12 @@ function buildUrl(op, params) {
 
 const ZIP_NOTE = '这是多个活动打包的 ZIP 报告，本服务不解压。请每次只传一个活动重新生成，或改用对应的 /json 接口。';
 
-async function readBody(response) {
+function readBody(response, write) {
   const type = (response.headers.get('content-type') ?? '').toLowerCase();
-  const raw = await readCapped(response);
+  return readResponse(response, write, (raw) => decodeBody(type, raw));
+}
+
+function decodeBody(type, raw) {
   if (type.includes('json')) {
     if (!raw.length) return {};
     try {
@@ -161,7 +253,7 @@ function failureHint(status, retryAfter) {
   return '检查参数是否符合官方说明（ozon_ads_api_catalog 传 endpoint 可查看）。';
 }
 
-async function execute(op, url, payload, credentials, agent) {
+async function execute(op, url, payload, credentials, agent, signal) {
   const start = performance.now();
   const headers = { Accept: 'application/json, text/csv', 'User-Agent': USER_AGENT };
   let body;
@@ -170,44 +262,80 @@ async function execute(op, url, payload, credentials, agent) {
     if (Buffer.byteLength(body) > MAX_BODY) throw new OzonError('请求体过大，请缩小查询范围。');
     headers['Content-Type'] = 'application/json';
   }
-  let token = await getToken(credentials, agent);
+  const scope = accountScope(credentials.clientId);
+  // A report submission is classified read-only, but repeating it could start a second report:
+  // like a write, it is never retried automatically.
+  const retryable = op.read_only && !isReportSubmit(op);
+  const bodyTimedOut = `读取 Ozon 响应超过本次调用的时间预算，已取消。${op.read_only ? '' : WRITE_UNKNOWN}`;
+  if (signal?.aborted) throw notSent();
+  // Fails before fetching a token when a long cooldown is on; the send itself is counted in send().
+  checkAdmission(op, Date.now(), scope);
+  let token = await getToken(credentials, agent, undefined, signal);
+  // The token stays listed for redaction while this request uses it, even if it is replaced meanwhile.
+  let release = holdToken(token);
   let refreshed = false;
   let retried = false;
-  // At most one token refresh (a 401 means nothing was executed) and one retry for reads.
-  for (;;) {
-    const response = await send(url, { method: op.method, headers: { ...headers, Authorization: `Bearer ${token}` }, body }, agent,
-      { write: !op.read_only });
-    await rejectRedirect(response, op.path);
-    if (response.status === 401 && !refreshed) {
-      await response.body?.cancel().catch(() => {});
-      refreshed = true;
-      token = await getToken(credentials, agent, token);
-      continue;
-    }
-    if (!response.ok) {
-      const retryAfter = response.headers.get('retry-after') ?? '2';
-      const delay = Number.isFinite(Number(retryAfter)) ? Math.max(0, Number(retryAfter)) : 2;
-      if (op.read_only && !retried && RETRY_STATUSES.has(response.status) && delay <= 5) {
-        await response.body?.cancel().catch(() => {});
-        retried = true;
-        await sleep(delay * 1000);
+  try {
+    // At most one token refresh (a 401 means nothing was executed) and one retry for reads, within
+    // the account's retry budget. Every send waits out the account's shared 429 cooldown.
+    for (;;) {
+      let response;
+      try {
+        response = await send(url, { method: op.method, headers: { ...headers, Authorization: `Bearer ${token}` }, body }, agent,
+          { write: !op.read_only, scope, op, signal });
+      } catch (error) {
+        throw error.fetchFailed ? outcomeUnknown(error) : error;
+      }
+      rejectRedirect(response, op.path);
+      if (response.status === 401 && !refreshed) {
+        discardBody(response);
+        refreshed = true;
+        release();
+        token = await getToken(credentials, agent, token, signal);
+        release = holdToken(token);
         continue;
       }
-      throw new OzonError(`HTTP ${response.status} ${op.method} ${op.path}：${failureHint(response.status, retryAfter)} ${await errorText(response, token)}`);
+      if (!response.ok) {
+        const delay = parseRetryAfter(response.headers.get('retry-after')) ?? DEFAULT_RETRY_MS;
+        if (response.status === 429) noteRateLimited(op, scope, delay);
+        if (retryable && !retried && RETRY_STATUSES.has(response.status) && delay <= MAX_RETRY_WAIT_MS && admitRetry(op, scope)) {
+          discardBody(response);
+          retried = true;
+          try {
+            await sleep(withJitter(delay), signal);
+          } catch (error) {
+            throw signal?.aborted ? notSent() : error;
+          }
+          continue;
+        }
+        const failure = new OzonError(`HTTP ${response.status} ${op.method} ${op.path}：${failureHint(response.status, Math.ceil(delay / 1000))} `
+          + await untilAborted(errorText(response, !op.read_only), signal, bodyTimedOut).catch((error) => error.message));
+        throw response.status >= 500 ? outcomeUnknown(failure) : failure;
+      }
+      // Reading the body is part of the request: the budget covers it too.
+      let data;
+      try {
+        data = await untilAborted(readBody(response, !op.read_only), signal, bodyTimedOut);
+      } catch (error) {
+        throw outcomeUnknown(error);
+      }
+      return {
+        endpoint: op.path,
+        method: op.method,
+        http_status: response.status,
+        queried_at_utc: new Date().toISOString(),
+        elapsed_ms: Math.round(performance.now() - start),
+        data: redact(data),
+      };
     }
-    const data = await readBody(response);
-    return {
-      endpoint: op.path,
-      method: op.method,
-      http_status: response.status,
-      queried_at_utc: new Date().toISOString(),
-      elapsed_ms: Math.round(performance.now() - start),
-      data: scrubTokens(redact(data), token),
-    };
+  } finally {
+    release();
   }
 }
 
-export async function adsRequest(endpoint, { method = 'GET', params = {}, body } = {}) {
+// Checks everything that needs no network (mode, registry, parameters, credentials, proxy) and
+// returns the request ready to send. `signal` cancels it, waits included.
+export function prepareAdsRequest(endpoint, { method = 'GET', params = {}, body, signal } = {}) {
   const op = findAdsOperation(endpoint, method);
   if (!op) {
     throw new OzonError('广告接口路径或 HTTP 方法未在 Performance API 官方规范中登记，未发送请求；先用 ozon_ads_api_catalog 搜索。');
@@ -218,5 +346,10 @@ export async function adsRequest(endpoint, { method = 'GET', params = {}, body }
   const payload = validateAdsRequest(op, query, body);
   const url = buildUrl(op, query);
   const credentials = adsCredentials();
-  return execute(op, url, payload, credentials, getDispatcher());
+  const agent = getDispatcher();
+  return (sendSignal = signal) => execute(op, url, payload, credentials, agent, sendSignal);
+}
+
+export async function adsRequest(endpoint, options = {}) {
+  return prepareAdsRequest(endpoint, options)();
 }