@raolin2025/claude-code-node 2.8.1 → 2.8.3

package/src/core/context-window.js

@@ -0,0 +1,262 @@
+/**
+ * 上下文窗口感知 (Context Window) — 自动探测 + 手动指定
+ *
+ * 解决的问题：TokenBudget.maxTokens 之前是一个"静态配置"（默认 100 万，
+ * CLI 兜底 20 万），并不知道所用模型真实上下文窗口。若预算 > 模型真实窗口，
+ * 自动压缩永远不会触发，上下文一路涨到模型报错。
+ *
+ * 本模块提供三层"窗口来源"，优先级：
+ *   1. manual  — 用户通过 /window 手动指定（持久化到 config）
+ *   2. probe   — 从 API /models 探测到的窗口（本次进程生效，不落盘）
+ *   3. table   — 内置常见模型上下文表（无法探测时的静态兜底）
+ *   4. fallback— 安全默认值（如 64K）
+ *
+ * 探测结果默认不落盘，手动指定才落盘（方案 A）。
+ */
+
+// ---- 内置常见模型上下文表（token）----
+// 缺失的厂商/模型会回落到 fallback；不精确属预期，可用 /window 手动纠正。
+export const MODEL_CONTEXT_TABLE = {
+  // DeepSeek
+  'deepseek-chat': 128_000,
+  'deepseek-reasoner': 128_000,
+  'deepseek-coder': 128_000,
+  'deepseek-v3': 128_000,
+  'deepseek-v2': 128_000,
+  'deepseek-v2.5': 128_000,
+  'deepseek-v4': 128_000,
+  // OpenAI
+  'gpt-4o': 128_000,
+  'gpt-4o-mini': 128_000,
+  'gpt-4-turbo': 128_000,
+  'gpt-4': 32_768,
+  'gpt-3.5-turbo': 16_384,
+  'o1': 200_000,
+  'o1-mini': 128_000,
+  'o3-mini': 200_000,
+  // Anthropic (经兼容网关时)
+  'claude-3-5-sonnet': 200_000,
+  'claude-3-5-haiku': 200_000,
+  'claude-sonnet-4': 200_000,
+  'claude-haiku-4': 200_000,
+  // Qwen (通义千问)
+  'qwen-max': 32_768,
+  'qwen-plus': 131_072,
+  'qwen-turbo': 1_000_000,
+  'qwen2.5-72b-instruct': 131_072,
+  'qwen2.5-32b-instruct': 131_072,
+  'qwen2.5-7b-instruct': 131_072,
+  'qwen2.5-14b-instruct': 131_072,
+  'qwen2.5-coder-32b-instruct': 131_072,
+  // GLM (智谱)
+  'glm-4': 128_000,
+  'glm-4-plus': 128_000,
+  'glm-4-air': 128_000,
+  'glm-4-flash': 128_000,
+  'glm-4v': 8_192,
+  'glm-4.5': 128_000,
+  'glm-4.5-air': 128_000,
+  // Moonshot (Kimi)
+  'moonshot-v1-8k': 8_192,
+  'moonshot-v1-32k': 32_768,
+  'moonshot-v1-128k': 131_072,
+  'moonshot-v1-auto': 131_072,
+  'kimi-k2': 128_000,
+  // 本地/开源 (Ollama / vLLM 常见)
+  'llama3.1': 131_072,
+  'llama3': 8_192,
+  'llama2': 4_096,
+  'mistral': 32_768,
+  'mixtral': 32_768,
+  'gemma2': 8_192,
+  'codellama': 16_384,
+  'qwen2.5': 131_072,
+  'yi-34b': 4_096,
+}
+
+// 安全兜底默认值 — 探测不到、表里也没有时使用
+export const FALLBACK_CONTEXT_WINDOW = 64_000
+
+// ---- 窗口来源标签 ----
+export const WINDOW_SOURCE = {
+  MANUAL: 'manual',
+  PROBE: 'probe',
+  TABLE: 'table',
+  FALLBACK: 'fallback',
+}
+
+const SOURCE_LABEL = {
+  [WINDOW_SOURCE.MANUAL]: '手动指定',
+  [WINDOW_SOURCE.PROBE]: 'API 探测',
+  [WINDOW_SOURCE.TABLE]: '内置模型表',
+  [WINDOW_SOURCE.FALLBACK]: '安全兜底',
+}
+
+/**
+ * 从 /models 响应中尝试提取单个模型的上下文窗口
+ *
+ * 不同服务字段名不一，尽量覆盖常见命名：
+ *   - OpenAI 兼容 vLLM: context_length / max_model_len / max_context_length
+ *   - Ollama: (来自 /api/show 的 model_info.llama.context_length)
+ *
+ * @param {object} modelObj — /models 返回数组中的单个模型对象
+ * @returns {number|null} 窗口 token 数；未知返回 null
+ */
+export function extractContextFromModelObj(modelObj) {
+  if (!modelObj || typeof modelObj !== 'object') return null
+  const keys = [
+    'context_length',
+    'context_window',
+    'max_context_length',
+    'max_model_len',
+    'max_sequence_length',
+    'model_max_length',
+    'n_ctx',
+    'contextWindow',
+    'contextSize',
+    'maxContext',
+    'maxTokens',
+    'context_tokens',
+  ]
+  for (const k of keys) {
+    const v = modelObj[k]
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0) return v
+  }
+  // 某些服务把窗口放在 meta / details 子对象
+  for (const sub of ['meta', 'details', 'model_info', 'capabilities']) {
+    const nested = modelObj[sub]
+    if (nested && typeof nested === 'object') {
+      const found = extractContextFromModelObj(nested)
+      if (found) return found
+    }
+  }
+  // Ollama model_info 专用字段：llama.context_length
+  const modelInfo = modelObj.model_info
+  if (modelInfo && typeof modelInfo === 'object') {
+    const ctxKey = Object.keys(modelInfo).find(k => k.endsWith('.context_length'))
+    if (ctxKey && typeof modelInfo[ctxKey] === 'number' && modelInfo[ctxKey] > 0) {
+      return modelInfo[ctxKey]
+    }
+  }
+  return null
+}
+
+/**
+ * 探测当前模型的上下文窗口
+ *
+ * 顺序：
+ *   1. 若已手动指定（manualWindow > 0）→ 直接返回手动值
+ *   2. 尝试从 GET {apiBase}/models 的响应中找匹配模型并提取窗口
+ *   3. 查内置表
+ *   4. 兜底 fallback
+ *
+ * @param {object} opts
+ * @param {string} opts.model — 模型名
+ * @param {string} opts.apiBase — API Base URL
+ * @param {string} [opts.apiKey]
+ * @param {number} [opts.manualWindow] — 用户手动指定的窗口（0 表示未指定）
+ * @param {number} [opts.fetchTimeoutMs] — 探测超时（默认 3000ms）
+ * @returns {Promise<{window:number, source:string}>}
+ */
+export async function detectContextWindow({ model, apiBase, apiKey, manualWindow = 0, fetchTimeoutMs = 3000 }) {
+  // 1. 手动指定最高优先级
+  if (manualWindow > 0) {
+    return { window: manualWindow, source: WINDOW_SOURCE.MANUAL }
+  }
+
+  // 2. 探测 API
+  if (apiBase) {
+    try {
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), fetchTimeoutMs)
+      const url = apiBase.replace(/\/+$/, '') + '/models'
+      const res = await fetch(url, {
+        headers: {
+          'Content-Type': 'application/json',
+          ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        signal: controller.signal,
+      })
+      clearTimeout(timer)
+      if (res.ok) {
+        const data = await res.json()
+        const models = data.data || []
+        // 优先精确匹配当前 model
+        let target = models.find(m => (m.id || '') === model)
+        // 其次尝试包含匹配（如 model 是 'qwen2.5' 而列表是 'qwen2.5:14b'）
+        if (!target) {
+          target = models.find(m => (m.id || '').startsWith(model) || model.startsWith(m.id || ''))
+        }
+        if (target) {
+          const win = extractContextFromModelObj(target)
+          if (win) return { window: win, source: WINDOW_SOURCE.PROBE }
+        }
+      }
+    } catch {
+      // 探测失败（超时/网络/无权限）→ 继续走表/兜底
+    }
+  }
+
+  // 3. 内置表
+  const normalized = (model || '').toLowerCase()
+  if (normalized && MODEL_CONTEXT_TABLE[normalized]) {
+    return { window: MODEL_CONTEXT_TABLE[normalized], source: WINDOW_SOURCE.TABLE }
+  }
+  // 表内做前缀匹配（如 'deepseek-chat:latest'、'qwen2.5-coder:7b'）
+  for (const key of Object.keys(MODEL_CONTEXT_TABLE)) {
+    if (normalized.startsWith(key) || key.startsWith(normalized)) {
+      return { window: MODEL_CONTEXT_TABLE[key], source: WINDOW_SOURCE.TABLE }
+    }
+  }
+
+  // 4. 兜底
+  return { window: FALLBACK_CONTEXT_WINDOW, source: WINDOW_SOURCE.FALLBACK }
+}
+
+/**
+ * 解析 /window 命令的参数为窗口 token 数
+ *
+ * 支持：
+ *   "131072"  → 131072
+ *   "64k"     → 65536
+ *   "128k"    → 131072
+ *   "200k"    → 204800
+ *   "1m"      → 1_000_000
+ *
+ * @param {string} str
+ * @returns {number|null} token 数；非法返回 null
+ */
+export function parseWindowArg(str) {
+  if (typeof str !== 'string') return null
+  const s = str.trim().toLowerCase().replace(/,/g, '')
+  if (!s) return null
+  const m = s.match(/^(\d+)\s*(k|m|kb|mb)?$/)
+  if (!m) return null
+  const num = parseInt(m[1], 10)
+  const unit = m[2]
+  if (!Number.isFinite(num) || num <= 0) return null
+  if (unit === 'k' || unit === 'kb') return num * 1000
+  if (unit === 'm' || unit === 'mb') return num * 1_000_000
+  return num
+}
+
+/**
+ * 将 token 数格式化为人类可读（十进制，与 token 常见记法一致：128K = 128,000）
+ * @param {number} tokens
+ * @returns {string} 如 "128.0K"、"1.00M"
+ */
+export function formatTokens(tokens) {
+  if (!Number.isFinite(tokens) || tokens <= 0) return '?'
+  if (tokens >= 1_000_000) return (tokens / 1_000_000).toFixed(2) + 'M'
+  if (tokens >= 1000) return (tokens / 1000).toFixed(1) + 'K'
+  return String(tokens)
+}
+
+/**
+ * 获取窗口来源的中文标签
+ * @param {string} source
+ * @returns {string}
+ */
+export function windowSourceLabel(source) {
+  return SOURCE_LABEL[source] || source || '未知'
+}

package/src/core/index.js

@@ -5,6 +5,14 @@ export { UserMessage, AssistantMessage, ToolCall } from "../types/index.js"
  */
 export { QueryEngine, QueryEngineConfig } from './query-engine.js'
 export { TokenBudget, estimateTokens } from './token-budget.js'
+export {
+  detectContextWindow,
+  parseWindowArg,
+  formatTokens,
+  windowSourceLabel,
+  WINDOW_SOURCE,
+  MODEL_CONTEXT_TABLE,
+} from './context-window.js'
 export { SessionManager } from './session.js'
 export { Config } from './config.js'
 export { parseStream, parseNonStreamResponse } from './streaming.js'

package/src/core/query-engine.js

@@ -47,6 +47,7 @@ export class QueryEngineConfig {
     this.onAskUser = options.onAskUser || null            // AskUserQuestion 工具回调（宿主按来源分流，避免远程死锁）
     this.readline = options.readline || null              // 用于 AskUserQuestion 工具
     this.onDelta = options.onDelta || null                // 流式增量回调 {type:'text'|'reasoning', text}（供 VS Code 扩展等 UI 消费）
+    this.configStore = options.configStore || null        // 配置实例（供工具读取 web.fetch.jinaApiKey 等；可选）
   }
 }
 
@@ -111,6 +112,20 @@ export class QueryEngine {
     let finalResponse = ''
 
     for (let turn = 0; turn < this.config.maxTurns; turn++) {
+      // 发送前硬校验：估算即将发送的消息是否超出窗口，超限则先压缩（最终兜底，防止溢出）
+      if (this.tokenBudget) {
+        const est = this.tokenBudget.estimateMessages(this.state.messages)
+        if (est > this.tokenBudget.maxTokens - this.tokenBudget.reservedForOutput) {
+          const { compacted, messages } = autoCompact(this.state.messages, this.tokenBudget, {
+            maxTokens: Math.floor(this.tokenBudget.maxTokens * 0.6),
+          })
+          if (compacted) {
+            this.state.messages = messages
+            if (this.config.verbose) console.error('[compact] Pre-send hard check: compressed to stay within window')
+          }
+        }
+      }
+
       const requestMessages = this._buildRequest(this.state.messages)
       const response = await this._callLLM(requestMessages, this.state.messages)
 

package/src/core/token-budget.js

@@ -24,6 +24,20 @@ export class TokenBudget {
     this.used = 0
     this.inputTokens = 0
     this.outputTokens = 0
+    // 当前窗口来源：'manual' | 'probe' | 'table' | 'fallback'（见 context-window.js）
+    this.windowSource = options.windowSource || 'fallback'
+  }
+
+  /**
+   * 更新上下文窗口上限（运行时生效，立即反映到 usagePercent）
+   * @param {number} maxTokens
+   * @param {string} [source] — 窗口来源标签
+   */
+  setWindow(maxTokens, source) {
+    if (Number.isFinite(maxTokens) && maxTokens > 0) {
+      this.maxTokens = maxTokens
+    }
+    if (source) this.windowSource = source
   }
 
   /** 可用于上下文的最大 token 数 */

package/src/security/fetch-guard.js

@@ -0,0 +1,311 @@
+/**
+ * Fetch 安全管道 — 协议白名单 + 连接级 SSRF 防护 + 重定向逐跳校验 + 大小/超时/SSL
+ *
+ * 移植自 openclaw safe-jina-fetch 设计（DESIGN.md §4），零依赖，仅内置模块。
+ *
+ * 设计原则：直连优先、兜底不扰。
+ *  - 直连能拿到的，不多花一跳；
+ *  - 直连被拦（非 ok / 网络错误 / 超时）才由调用方走 Jina Reader 兜底（见 web-fetch.js）。
+ *
+ * 相比项目原 ssrf-guard.js 的增强：
+ *  - 连接级校验：给 http/https.request 注入 lookup 钩子，在 TCP 连接建立时对
+ *    全部解析地址逐一校验（防 DNS rebinding 的 TOCTOU 竞态）；
+ *  - 重定向逐跳校验：默认最多 5 跳，每一跳重新走完整协议/SSRF/域名校验。
+ */
+import { lookup as dnsLookup } from 'dns'
+import http from 'http'
+import https from 'https'
+import { isIP } from 'net'
+import { isBlockedAddress } from './ssrf-guard.js'
+
+/** 协议白名单 — 仅 http/https，file/ftp/data 等一律拒绝 */
+const ALLOWED_PROTOCOLS = ['http:', 'https:']
+
+/** 域名后缀黑名单 */
+const BLOCKED_HOSTNAME_SUFFIXES = ['.local', '.internal', '.localdomain', '.localhost', '.home', '.lan']
+
+/** 已知 SSRF 目标主机名（精确匹配，兜底） */
+const BLOCKED_HOSTNAMES = [
+  'localhost',
+  'localhost.localdomain',
+  'ip6-localhost',
+  'ip6-loopback',
+  'metadata.google.internal',
+  'metadata.internal',
+  'instance-data',
+]
+
+export const DEFAULT_FETCH_OPTIONS = {
+  maxBytes: 10 * 1024 * 1024, // 响应大小上限 10MB
+  timeoutMs: 30000,            // 超时 30s
+  maxRedirects: 5,             // 重定向最多 5 跳
+}
+
+/**
+ * 校验 URL 的协议是否在白名单内
+ * @param {string} protocol — 如 'https:'
+ * @returns {boolean}
+ */
+export function isAllowedProtocol(protocol) {
+  return ALLOWED_PROTOCOLS.includes(protocol)
+}
+
+/**
+ * 校验主机名是否在内网/SSRF 黑名单
+ * @param {string} hostname
+ * @returns {{blocked: boolean, reason?: string}}
+ */
+export function checkHostnameBlocked(hostname) {
+  const lower = (hostname || '').toLowerCase()
+  if (!lower) return { blocked: true, reason: '空主机名' }
+  if (BLOCKED_HOSTNAMES.includes(lower)) {
+    return { blocked: true, reason: `主机名 ${hostname} 为已知 SSRF 目标` }
+  }
+  for (const suffix of BLOCKED_HOSTNAME_SUFFIXES) {
+    if (lower.endsWith(suffix)) {
+      return { blocked: true, reason: `主机名 ${hostname} 为内网域名（后缀 ${suffix}）` }
+    }
+  }
+  return { blocked: false }
+}
+
+/**
+ * 校验单个 IP 地址是否安全（连接级，供 lookup 钩子逐地址调用）
+ * @param {string} address
+ * @returns {{blocked: boolean, reason?: string}}
+ */
+export function checkAddressBlocked(address) {
+  if (isBlockedAddress(address)) {
+    return { blocked: true, reason: `地址 ${address} 在私有/保留范围内，可能为 SSRF 目标` }
+  }
+  return { blocked: false }
+}
+
+/**
+ * 安全 DNS lookup — 连接时逐地址校验（防 DNS rebinding）
+ *
+ * 兼容 Node 两种签名：
+ *   - options.all = true  → (err, addresses[])
+ *   - 否则                → (err, address, family)
+ * 若任一解析地址命中私有/保留网段，立即报错阻断连接（而非放行让上层再查）。
+ */
+export function safeLookup(hostname, options, callback) {
+  const all = !!(options && options.all)
+
+  dnsLookup(hostname, { all: true }, (err, addresses) => {
+    if (err) {
+      // DNS 解析失败 — 交由上层处理（通常导致请求失败）
+      if (typeof callback === 'function') {
+        if (all) callback(err, [])
+        else callback(err, undefined, undefined)
+      }
+      return
+    }
+
+    const list = Array.isArray(addresses) ? addresses : [{ address, family: 4 }]
+
+    // 逐地址校验 — 任一命中即阻断（拒绝整条连接，防止 rebinding 切到私有地址）
+    for (const a of list) {
+      const addr = typeof a === 'string' ? a : a.address
+      const { blocked, reason } = checkAddressBlocked(addr)
+      if (blocked) {
+        const e = new Error(`SSRF blocked: ${reason}`)
+        e.code = 'SSRF_BLOCKED'
+        if (typeof callback === 'function') {
+          if (all) callback(e, [])
+          else callback(e, undefined, undefined)
+        }
+        return
+      }
+    }
+
+    // 全部安全 — 返回解析结果（保持签名兼容）
+    if (typeof callback === 'function') {
+      if (all) {
+        callback(null, list)
+      } else {
+        const first = list[0]
+        callback(null, typeof first === 'string' ? first : first.address, typeof first === 'string' ? 4 : first.family)
+      }
+    }
+  })
+}
+
+/**
+ * 构造带连接级 SSRF 防护的 http/https 客户端
+ * 通过注入 lookup 钩子，在 TCP 连接建立时对全部解析地址逐一校验。
+ * @returns {{http: import('http').Agent, https: import('https').Agent}}
+ */
+export function createSafeAgents() {
+  const agentOptions = { lookup: safeLookup, keepAlive: false }
+  return {
+    http: new http.Agent(agentOptions),
+    https: new https.Agent(agentOptions),
+  }
+}
+
+/**
+ * 解析并校验一个 URL（协议白名单 + 主机名黑名单）
+ * @param {string} url
+ * @returns {{ok: true, url: URL} | {ok: false, reason: string}}
+ */
+export function parseAndValidateUrl(url) {
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch {
+    return { ok: false, reason: `无效的 URL: ${url}` }
+  }
+
+  if (!isAllowedProtocol(parsed.protocol)) {
+    return { ok: false, reason: `不支持的协议：${parsed.protocol}（仅允许 http/https）` }
+  }
+
+  const hostBlock = checkHostnameBlocked(parsed.hostname)
+  if (hostBlock.blocked) {
+    return { ok: false, reason: hostBlock.reason }
+  }
+
+  // IP 字面量：直接校验是否在私有/保留网段（Node 对 IP 字面量不走 DNS lookup，
+  // 连接级 lookup 钩子不会触发，必须在发起请求前显式校验，否则 SSRF 被绕过）
+  if (isIP(parsed.hostname)) {
+    const addrBlock = checkAddressBlocked(parsed.hostname)
+    if (addrBlock.blocked) {
+      return { ok: false, reason: addrBlock.reason }
+    }
+  }
+
+  return { ok: true, url: parsed }
+}
+
+/**
+ * 读取响应体，限制大小（超限截断并在 warnings 标记）
+ * @param {import('http').IncomingMessage} res
+ * @param {number} maxBytes
+ * @returns {Promise<{body: string, truncated: boolean}>}
+ */
+export async function readBodyLimited(res, maxBytes) {
+  const chunks = []
+  let total = 0
+  let truncated = false
+  for await (const chunk of res) {
+    total += chunk.length
+    if (total > maxBytes) {
+      truncated = true
+      chunks.push(chunk.slice(0, maxBytes - (total - chunk.length)))
+      break
+    }
+    chunks.push(chunk)
+  }
+  return { body: Buffer.concat(chunks).toString('utf-8'), truncated }
+}
+
+/**
+ * 带安全管道的 HTTP 抓取函数（单次请求，含协议/SSRF/大小/超时/SSL）
+ *
+ * 注意：本函数只发一次请求，不自动跟随重定向——重定向由 safeFetchWithRedirects
+ * 逐跳处理（每跳重新校验）。返回 { status, headers, body, truncated, finalUrl }。
+ *
+ * @param {string} url
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs]
+ * @param {number} [options.maxBytes]
+ * @param {object} [options.headers]
+ * @returns {Promise<{ok: boolean, status: number, headers: object, body: string, truncated: boolean, finalUrl: string, error?: string}>}
+ */
+export function safeRequest(url, options = {}) {
+  const { timeoutMs = DEFAULT_FETCH_OPTIONS.timeoutMs, maxBytes = DEFAULT_FETCH_OPTIONS.maxBytes, headers = {} } = options
+
+  const validated = parseAndValidateUrl(url)
+  if (!validated.ok) {
+    return Promise.resolve({ ok: false, status: 0, headers: {}, body: '', truncated: false, finalUrl: url, error: validated.reason })
+  }
+  const parsed = validated.url
+
+  return new Promise((resolve) => {
+    const client = parsed.protocol === 'https:' ? https : http
+    const req = client.request(
+      parsed,
+      {
+        method: 'GET',
+        headers: { 'User-Agent': 'cc-node', 'Accept': 'text/html,application/json,text/plain,*/*', ...headers },
+        // 连接级 SSRF 防护（TCP 连接时逐地址校验，防 DNS rebinding）
+        lookup: safeLookup,
+        // 强制校验证书，不提供跳过选项
+        rejectUnauthorized: true,
+      },
+      async (res) => {
+        // 读响应体（限制大小）
+        try {
+          const { body, truncated } = await readBodyLimited(res, maxBytes)
+          resolve({
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            status: res.statusCode || 0,
+            headers: res.headers || {},
+            body,
+            truncated,
+            finalUrl: res.responseUrl || parsed.href,
+          })
+        } catch (err) {
+          resolve({ ok: false, status: res.statusCode || 0, headers: res.headers || {}, body: '', truncated: false, finalUrl: parsed.href, error: err.message })
+        }
+      }
+    )
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error('请求超时'))
+    })
+
+    req.on('error', (err) => {
+      resolve({ ok: false, status: 0, headers: {}, body: '', truncated: false, finalUrl: parsed.href, error: err.message })
+    })
+
+    req.end()
+  })
+}
+
+/**
+ * 带重定向逐跳校验的安全抓取
+ * 每一跳都重新执行协议/SSRF/域名校验，防止 302 → 内网 的重定向绕过。
+ *
+ * @param {string} url
+ * @param {object} [options]
+ * @param {number} [options.maxRedirects] — 最大跳数（默认 5）
+ * @returns {Promise<{ok: boolean, status: number, headers: object, body: string, truncated: boolean, finalUrl: string, redirects: string[], error?: string, warning?: string}>}
+ */
+export async function safeFetchWithRedirects(url, options = {}) {
+  const { maxRedirects = DEFAULT_FETCH_OPTIONS.maxRedirects, ...reqOptions } = options
+  let currentUrl = url
+  const redirects = []
+
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    const result = await safeRequest(currentUrl, reqOptions)
+
+    // 3xx 重定向 — 逐跳校验下一目标
+    if (result.status >= 300 && result.status < 400 && result.headers.location) {
+      // 校验下一跳 URL（相对路径需拼接到当前 URL）
+      let nextUrl
+      try {
+        nextUrl = new URL(result.headers.location, currentUrl).href
+      } catch {
+        return { ...result, redirects, error: `无效的重定向目标: ${result.headers.location}` }
+      }
+
+      // 重定向目标重新走协议/SSRF 校验（防止跳到内网）
+      const v = parseAndValidateUrl(nextUrl)
+      if (!v.ok) {
+        return { ...result, redirects, error: `重定向目标被安全策略阻止: ${v.reason}` }
+      }
+
+      redirects.push(`${result.status} → ${nextUrl}`)
+      currentUrl = nextUrl
+      continue
+    }
+
+    // 非重定向 — 返回最终结果（含重定向链）
+    return { ...result, redirects, finalUrl: currentUrl }
+  }
+
+  // 超过最大跳数
+  return { ok: false, status: 0, headers: {}, body: '', truncated: false, finalUrl: currentUrl, redirects, error: `重定向次数超过上限 (${maxRedirects})` }
+}