@raolin2025/claude-code-node 2.8.2 → 2.8.3

package/README.md

@@ -166,7 +166,7 @@ cc-node 会自动感知当前所用模型的**上下文窗口长度**，并在
 | **Write** | 创建/覆盖文件 | `ask` | ✅ 写入路径安全 |
 | **Glob** | 文件模式搜索 | `always-allow` | — |
 | **Grep** | 内容搜索（rg/grep） | `always-allow` | — |
-| **WebFetch** | 抓取网页内容 | `ask` | ✅ SSRF 防护 |
+| **WebFetch** | 抓取网页内容（安全管道 + Jina 兜底） | `ask` | ✅ SSRF + 重定向 + 脱敏 |
 | **WebSearch** | 网页搜索 | `ask` | 需要 API Key |
 | **GitTool** | GitHub PR 自动化（审查/合并/评论） | `high` | ✅ 预检查 |
 | **NpmPublish** | npm 发布一键工具（版本/打包/发布） | `ask` | ✅ token 校验 |
@@ -194,9 +194,27 @@ cc-node 会自动感知当前所用模型的**上下文窗口长度**，并在
 ✅ ::1                 — IPv6 回环
 ```
 
+### 🕸️ WebFetch 安全抓取（安全管道 + Jina 兜底）
+
+`WebFetch` 内置完整安全管道（移植自 safe-jina-fetch 设计，`src/security/fetch-guard.js`）：
+
+- **协议白名单**：仅 `http/https`，拒绝 `file://`、`ftp://`、`data:` 等
+- **连接级 SSRF**：TCP 连接建立时对全部解析地址逐一校验（防 DNS rebinding），
+  并对 IP 字面量前置校验（Node 对 IP 不走 DNS lookup，必须显式拦截）
+- **重定向逐跳校验**：默认最多 5 跳，每跳重新校验协议 + SSRF（防 302 → 内网绕过）
+- **响应大小上限**：10MB；**超时**：30s；**强制 SSL**（证书错误直接拒绝）
+- **敏感数据自动脱敏**：API Key / Bearer / AWS Key / 私钥 / OpenAI `sk-` / Slack token 等
+  命中即替换为 `[REDACTED:类型]` 并告警（`src/security/redact.js`）
+
+**Jina Reader 兜底**（`src/tools/web-fetch-providers.js`）：
+
+- 直连失败（403 / 反爬 / 网络错误 / 超时）时，自动经 `r.jina.ai` 清洗后返回 Markdown
+- 直连返回 200 但正文 < 200 字符（疑似 JS 挑战页，如豆瓣）也触发兜底
+- `extractMode` 参数：`auto`（默认，直连优先 + 兜底）/ `direct`（强制直连）/ `jina`（强制 Jina）
+- Jina 凭据三选一（可选，匿名约 20 RPM）：环境变量 `JINA_API_KEY` > 配置 `web.fetch.jinaApiKey` > 匿名
+
 ### 2️⃣ Bash 命令安全（279 行）
 阻止 LLM 执行危险 shell 命令：
-
 | 类别 | 示例 | 严重性 |
 |------|------|--------|
 | 破坏性操作 | `rm -rf /`, `dd of=/dev/sda`, `mkfs` | 🚫 CRITICAL |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raolin2025/claude-code-node",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "Node.js AI Code Agent CLI - Zero dependencies, pure JavaScript, security hardened, multi-channel notifications, Telegram & QQ Bot remote programming, rich media upload, multi-account management",
   "type": "module",
   "main": "src/core/index.js",

package/src/__tests__/web-fetch-guard.test.js

@@ -0,0 +1,193 @@
+/**
+ * WebFetch 安全管道 + Jina 兜底测试
+ * 覆盖：协议白名单、SSRF、重定向逐跳校验、脱敏、大小上限、Jina provider、WebFetch 兜底
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import http from 'http'
+import {
+  parseAndValidateUrl,
+  checkAddressBlocked,
+  safeFetchWithRedirects,
+  readBodyLimited,
+} from '../security/fetch-guard.js'
+import { redactSensitiveData } from '../security/redact.js'
+import {
+  safeJinaFetch,
+  cleanJinaMarkdown,
+  extractTitleFromMarkdown,
+  resolveJinaApiKey,
+} from '../tools/web-fetch-providers.js'
+
+// ============ 协议白名单 ============
+test('协议白名单：拒绝 file/ftp/data', () => {
+  assert.equal(parseAndValidateUrl('file:///etc/passwd').ok, false)
+  assert.equal(parseAndValidateUrl('ftp://example.com/x').ok, false)
+  assert.equal(parseAndValidateUrl('data:text/plain,hello').ok, false)
+  assert.equal(parseAndValidateUrl('javascript:alert(1)').ok, false)
+})
+
+test('协议白名单：允许 http/https', () => {
+  assert.equal(parseAndValidateUrl('https://example.com').ok, true)
+  assert.equal(parseAndValidateUrl('http://example.com').ok, true)
+})
+
+test('无效 URL 拒绝', () => {
+  assert.equal(parseAndValidateUrl('not a url').ok, false)
+})
+
+// ============ SSRF 地址校验 ============
+test('SSRF：私有/保留地址全部阻止', () => {
+  assert.equal(checkAddressBlocked('127.0.0.1').blocked, true)
+  assert.equal(checkAddressBlocked('10.0.0.1').blocked, true)
+  assert.equal(checkAddressBlocked('192.168.1.1').blocked, true)
+  assert.equal(checkAddressBlocked('172.16.0.1').blocked, true)
+  assert.equal(checkAddressBlocked('100.64.0.1').blocked, true)
+  assert.equal(checkAddressBlocked('169.254.169.254').blocked, true)
+  assert.equal(checkAddressBlocked('0.0.0.0').blocked, true)
+  assert.equal(checkAddressBlocked('::1').blocked, true)
+  assert.equal(checkAddressBlocked('fe80::1').blocked, true)
+  assert.equal(checkAddressBlocked('fd00::1').blocked, true)
+  assert.equal(checkAddressBlocked('::ffff:192.168.1.1').blocked, true)
+})
+
+test('SSRF：公网地址放行', () => {
+  assert.equal(checkAddressBlocked('8.8.8.8').blocked, false)
+  assert.equal(checkAddressBlocked('1.1.1.1').blocked, false)
+})
+
+test('SSRF：内网域名后缀阻止', () => {
+  assert.equal(parseAndValidateUrl('http://router.local/x').ok, false)
+  assert.equal(parseAndValidateUrl('http://svc.internal/x').ok, false)
+  assert.equal(parseAndValidateUrl('http://localhost:8080/').ok, false)
+  assert.equal(parseAndValidateUrl('http://db.home/x').ok, false)
+})
+
+test('SSRF：IP 字面量私网地址被 parseAndValidateUrl 拒绝', () => {
+  assert.equal(parseAndValidateUrl('http://127.0.0.1:8080/').ok, false)
+  assert.equal(parseAndValidateUrl('http://192.168.1.1/').ok, false)
+  assert.equal(parseAndValidateUrl('http://10.0.0.5/').ok, false)
+  assert.equal(parseAndValidateUrl('https://8.8.8.8/').ok, true)
+})
+
+// ============ 重定向逐跳校验 ============
+test('重定向：起始 URL 为内网地址被 SSRF 阻止', async () => {
+  // 本地服务器跑在 127.0.0.1（回环，SSRF 目标），safeFetchWithRedirects 应在连接前拒绝
+  const server = http.createServer((req, res) => {
+    res.writeHead(200)
+    res.end('ok')
+  })
+  await new Promise(r => server.listen(0, r))
+  const port = server.address().port
+  const result = await safeFetchWithRedirects(`http://127.0.0.1:${port}/`, { timeoutMs: 2000 })
+  server.close()
+  assert.equal(result.ok, false)
+  assert.ok(result.error && result.error.includes('SSRF'), `应报 SSRF 错误，实际: ${result.error}`)
+})
+
+test('重定向：目标跳转到内网被拦截（校验 next URL）', async () => {
+  // 用公网可访问的域名作为起始（绕过起始 SSRF），但通过 verifySafeRedirectTarget 验证目标校验。
+  // 直接验证"相对重定向 → 内网"的目标解析 + 校验逻辑：
+  //   起始 https://example.com/a → 302 Location: http://192.168.1.1/（绝对内网）
+  const v = parseAndValidateUrl('http://192.168.1.1/')
+  assert.equal(v.ok, false)
+  assert.ok(v.reason.includes('192.168.1.1'))
+
+  // 相对重定向目标解析：https://example.com/x + Location: //192.168.1.1 也是内网
+  const parsed = new URL('//192.168.1.1/', 'https://example.com')
+  assert.equal(parsed.hostname, '192.168.1.1')
+  const v2 = parseAndValidateUrl(parsed.href)
+  assert.equal(v2.ok, false)
+})
+
+test('重定向：相对路径解析到公网放行', () => {
+  const parsed = new URL('/final', 'https://example.com/start')
+  assert.equal(parsed.href, 'https://example.com/final')
+  assert.equal(parseAndValidateUrl(parsed.href).ok, true)
+})
+
+// ============ 响应大小上限 ============
+test('响应大小上限：超限截断', async () => {
+  const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/plain' })
+    res.end('x'.repeat(1000))
+  })
+  await new Promise(r => server.listen(0, r))
+  const port = server.address().port
+  // 无法用 127.0.0.1（SSRF 阻止），改用测试 readBodyLimited 直接逻辑
+  server.close()
+
+  // 直接测试 readBodyLimited
+  const chunks = { async *[Symbol.asyncIterator]() { yield Buffer.from('x'.repeat(100)); yield Buffer.from('y'.repeat(100)) } }
+  const fakeRes = { [Symbol.asyncIterator]: chunks[Symbol.asyncIterator].bind(chunks) }
+  const { body, truncated } = await readBodyLimited(fakeRes, 150)
+  assert.equal(truncated, true)
+  assert.equal(body.length, 150)
+})
+
+// ============ 敏感数据脱敏 ============
+test('脱敏：OpenAI key 替换', () => {
+  const { text, redacted } = redactSensitiveData('key is sk-abcdefghijklmnopqrstuvwxyz1234567890')
+  assert.equal(text.includes('sk-abcdefghijklmnopqrstuvwxyz'), false)
+  assert.ok(text.includes('[REDACTED:OpenAI-Key]'))
+  assert.ok(redacted.includes('OpenAI-Key'))
+})
+
+test('脱敏：AWS key 替换', () => {
+  const { text, redacted } = redactSensitiveData('AKIAIOSFODNN7EXAMPLE')
+  assert.ok(text.includes('[REDACTED:AWS-Key]'))
+  assert.ok(redacted.includes('AWS-Key'))
+})
+
+test('脱敏：私钥整体替换', () => {
+  const { text } = redactSensitiveData('-----BEGIN RSA PRIVATE KEY-----\nabc123\n-----END RSA PRIVATE KEY-----')
+  assert.ok(!text.includes('abc123'))
+  assert.ok(text.includes('[REDACTED:Private-Key]'))
+})
+
+test('脱敏：Bearer token 替换', () => {
+  const { text } = redactSensitiveData('Authorization: Bearer 0123456789abcdef0123456789abcdef')
+  assert.ok(text.includes('[REDACTED:Bearer]'))
+})
+
+test('脱敏：无敏感内容不动', () => {
+  const { text, redacted } = redactSensitiveData('hello world, nothing sensitive here')
+  assert.equal(text, 'hello world, nothing sensitive here')
+  assert.equal(redacted.length, 0)
+})
+
+// ============ Jina provider ============
+test('Jina markdown 清洗', () => {
+  const md = 'Title: Test Page\nURL Source: https://example.com\nMarkdown Content:\n\nHello **world**'
+  const cleaned = cleanJinaMarkdown(md)
+  assert.equal(cleaned, 'Hello **world**')
+})
+
+test('Jina 标题提取', () => {
+  assert.equal(extractTitleFromMarkdown('Title: My Page\ncontent'), 'My Page')
+  assert.equal(extractTitleFromMarkdown('no title'), '')
+})
+
+test('Jina key 解析优先级：环境变量 > 配置', () => {
+  process.env.JINA_API_KEY = 'env-key'
+  const fromEnv = resolveJinaApiKey({ get: () => 'config-key' })
+  assert.equal(fromEnv, 'env-key')
+  delete process.env.JINA_API_KEY
+  const fromCfg = resolveJinaApiKey({ get: () => 'config-key' })
+  assert.equal(fromCfg, 'config-key')
+  const anonymous = resolveJinaApiKey(null)
+  assert.equal(anonymous, '')
+})
+
+test('safeJinaFetch：拒绝 file 协议', async () => {
+  const r = await safeJinaFetch('file:///etc/passwd')
+  assert.equal(r.ok, false)
+  assert.ok(r.error.includes('协议'))
+})
+
+test('safeJinaFetch：本地 mock 服务器（重定向到 Jina 不可行，验证网络错误处理）', async () => {
+  // 指向一个不存在的端口，验证错误路径
+  const r = await safeJinaFetch('http://127.0.0.1:1/', { timeoutMs: 500 })
+  // Jina 服务本身会 4xx（因为 r.jina.ai/127.0.0.1... 无法访问），或返回错误
+  assert.equal(typeof r.ok, 'boolean')
+})

package/src/core/cli.js

@@ -524,6 +524,7 @@ const systemPrompt = cliArgs.systemPrompt || DEFAULT_SYSTEM_PROMPT
     noStream: cliArgs.noStream,
     costTracker,
     tokenBudget,
+    configStore: config,
   })
   const engine = new QueryEngine(engineConfig)
 

package/src/core/config.js

@@ -26,6 +26,16 @@ const DEFAULTS = {
     fileRead: { maxLines: 2000, maxSizeKB: 256 },
     webFetch: { timeout: 30, maxChars: 100000 },
   },
+  web: {
+    fetch: {
+      maxChars: 100000,
+      maxBytes: 10485760,  // 10MB
+      timeoutMs: 30000,
+      maxRedirects: 5,
+      fallbackProvider: 'safe-jina',  // 直连失败时的兜底 provider
+      jinaApiKey: '',                  // 可选（匿名约 20 RPM）
+    },
+  },
   channels: {},
   defaultChannel: null,
   qqbot: {

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 等；可选）
   }
 }
 

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})` }
+}

package/src/security/redact.js

@@ -0,0 +1,76 @@
+/**
+ * 敏感数据自动脱敏
+ *
+ * 移植自 openclaw safe-jina-fetch 设计（DESIGN.md §4.4）。
+ * 对响应内容扫描常见敏感模式，命中即替换为 [REDACTED:类型]，并在 warnings 中告警。
+ * （原 Python 版只告警不脱敏，这里按 v2.0 设计升级为自动脱敏）
+ */
+
+/** 各类敏感模式的检测规则：{ 类型, 正则, 替换值 } */
+const REDACT_RULES = [
+  // API Key / Access Token / Auth Token（key= / token= 等 8 位以上值）
+  {
+    type: 'API-Key',
+    regex: /(key|token|api[_-]?key|access[_-]?token|auth[_-]?token|secret)=(['"]?)[A-Za-z0-9_\-./+]{8,}\2/gi,
+    value: '[REDACTED:API-Key]',
+  },
+  // Bearer Token（20 位以上）
+  {
+    type: 'Bearer',
+    regex: /Bearer\s+[A-Za-z0-9_\-.]{20,}/gi,
+    value: '[REDACTED:Bearer]',
+  },
+  // AWS Access Key（AKIA 开头 16 位）
+  {
+    type: 'AWS-Key',
+    regex: /AKIA[0-9A-Z]{16}/g,
+    value: '[REDACTED:AWS-Key]',
+  },
+  // AWS Secret Access Key
+  {
+    type: 'AWS-Secret',
+    regex: /aws_secret_access_key\s*=\s*['"]?[A-Za-z0-9/+=]{20,}/gi,
+    value: '[REDACTED:AWS-Secret]',
+  },
+  // 私钥
+  {
+    type: 'Private-Key',
+    regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    value: '[REDACTED:Private-Key]',
+  },
+  // OpenAI 风格（sk- + 20 位以上字母数字）
+  {
+    type: 'OpenAI-Key',
+    regex: /sk-[A-Za-z0-9]{20,}/g,
+    value: '[REDACTED:OpenAI-Key]',
+  },
+  // Slack Token（xoxb / xoxa / xoxp / xoxr）
+  {
+    type: 'Slack-Token',
+    regex: /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+    value: '[REDACTED:Slack-Token]',
+  },
+]
+
+/**
+ * 对文本执行敏感数据脱敏
+ * @param {string} text
+ * @returns {{text: string, redacted: string[]}} — 脱敏后的文本 + 命中的类型列表（去重）
+ */
+export function redactSensitiveData(text) {
+  if (typeof text !== 'string' || !text) return { text: text || '', redacted: [] }
+
+  let result = text
+  const hitTypes = new Set()
+
+  for (const rule of REDACT_RULES) {
+    if (rule.regex.test(result)) {
+      hitTypes.add(rule.type)
+      // 重置 lastIndex（/g 正则 test 会改变 lastIndex）
+      rule.regex.lastIndex = 0
+      result = result.replace(rule.regex, rule.value)
+    }
+  }
+
+  return { text: result, redacted: [...hitTypes] }
+}

package/src/tools/web-fetch-providers.js

@@ -0,0 +1,140 @@
+/**
+ * WebFetch 兜底 Provider — Safe Jina Reader
+ *
+ * 移植自 openclaw safe-jina-fetch 设计（DESIGN.md §5）。
+ *
+ * 作用：当 WebFetch 直连目标 URL 失败（非 ok / 网络错误 / 超时）时，
+ * 自动经 Jina Reader（https://r.jina.ai/<url>）清洗后返回 Markdown，
+ * 专门对付反爬 / 403 / 动态渲染站点。
+ *
+ * Jina 请求模式（对齐 DESIGN.md §5.3）：
+ *   - CLI / 默认: text/plain + X-Return-Format: markdown → 首行 Title: xxx 提取标题
+ *   - json:        application/json → {title, url, content} 更稳健
+ *
+ * 凭据（三选一，可选——匿名约 20 RPM）：
+ *   1. 环境变量 JINA_API_KEY / JINA_READER_KEY
+ *   2. 配置 web.fetch.jinaApiKey
+ *   3. 匿名
+ */
+
+const JINA_READER_BASE = 'https://r.jina.ai'
+
+/**
+ * 从 Jina Reader 返回的 markdown 文本中提取标题（首行 "Title: xxx"）
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function extractTitleFromMarkdown(markdown) {
+  const lines = (markdown || '').split('\n')
+  for (const line of lines) {
+    const m = line.match(/^\s*Title:\s*(.+)$/i)
+    if (m) return m[1].trim()
+  }
+  return ''
+}
+
+/**
+ * 解析 Jina 返回的 markdown，提取正文（去掉 Title/URL 元信息行）
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function cleanJinaMarkdown(markdown) {
+  if (typeof markdown !== 'string') return ''
+  const lines = markdown.split('\n')
+
+  // 优先找 "Markdown Content:" 标记，从其后开始
+  const mcIdx = lines.findIndex(l => /^Markdown Content:/i.test(l.trim()))
+  if (mcIdx >= 0) return lines.slice(mcIdx + 1).join('\n').trim()
+
+  // 否则去掉开头的 Title: / URL Source: 元信息行
+  const bodyStart = lines.findIndex(l => !/^(Title:|URL Source:)/i.test(l.trim()))
+  if (bodyStart > 0) return lines.slice(bodyStart).join('\n').trim()
+
+  return markdown.trim()
+}
+
+/**
+ * 调用 Jina Reader 抓取 URL
+ * @param {string} url — 目标 URL
+ * @param {object} [options]
+ * @param {string} [options.apiKey] — Jina 凭据（可选，匿名可用）
+ * @param {'markdown'|'json'} [options.format] — 返回格式
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<{ok: boolean, text: string, title: string, finalUrl: string, status?: number, error?: string}>}
+ */
+export async function safeJinaFetch(url, options = {}) {
+  const { apiKey = '', format = 'markdown', timeoutMs = 30000 } = options
+
+  // 校验目标 URL 基本合法性（协议必须是 http/https）
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch {
+    return { ok: false, text: '', title: '', finalUrl: url, error: `无效的 URL: ${url}` }
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    return { ok: false, text: '', title: '', finalUrl: url, error: `不支持的协议：${parsed.protocol}` }
+  }
+
+  const jinaUrl = `${JINA_READER_BASE}/${url}`
+  const headers = {
+    'User-Agent': 'cc-node/2.8.2',
+    'Accept': format === 'json' ? 'application/json' : 'text/plain',
+  }
+  if (format === 'markdown') headers['X-Return-Format'] = 'markdown'
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
+
+  try {
+    const response = await fetch(jinaUrl, { headers, signal: AbortSignal.timeout(timeoutMs) })
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        text: '',
+        title: '',
+        finalUrl: jinaUrl,
+        status: response.status,
+        error: `Jina Reader HTTP ${response.status}`,
+      }
+    }
+
+    if (format === 'json') {
+      const data = await response.json()
+      return {
+        ok: true,
+        text: typeof data.content === 'string' ? data.content : '',
+        title: typeof data.title === 'string' ? data.title : '',
+        finalUrl: jinaUrl,
+        status: 200,
+      }
+    }
+
+    const markdown = await response.text()
+    return {
+      ok: true,
+      text: cleanJinaMarkdown(markdown),
+      title: extractTitleFromMarkdown(markdown),
+      finalUrl: jinaUrl,
+      status: 200,
+    }
+  } catch (err) {
+    if (err.name === 'TimeoutError') {
+      return { ok: false, text: '', title: '', finalUrl: jinaUrl, error: 'Jina Reader 请求超时' }
+    }
+    return { ok: false, text: '', title: '', finalUrl: jinaUrl, error: `Jina Reader 错误: ${err.message}` }
+  }
+}
+
+/**
+ * 解析 Jina 凭据（三选一：环境变量 > 配置 > 匿名）
+ * @param {object} [config] — Config 实例（可选）
+ * @returns {string} apiKey（可能为空 = 匿名）
+ */
+export function resolveJinaApiKey(config = null) {
+  return (
+    process.env.JINA_API_KEY ||
+    process.env.JINA_READER_KEY ||
+    (config ? config.get('web.fetch.jinaApiKey') || '' : '') ||
+    ''
+  )
+}

package/src/tools/web-fetch.js

@@ -1,11 +1,31 @@
 /**
- * WebFetch 工具 — 抓取网页内容
- * 对应原版: src/tools/WebFetchTool/
+ * WebFetch 工具 — 抓取网页内容（安全管道 + Jina 兜底）
+ *
+ * 安全特性（移植自 safe-jina-fetch 设计）：
+ *  - 协议白名单：仅 http/https，file/ftp/data 拒绝
+ *  - 连接级 SSRF 防护：TCP 连接时逐地址校验（防 DNS rebinding）
+ *  - 重定向逐跳校验：最多 5 跳，每跳重新校验
+ *  - 响应大小上限（10MB）、超时（30s）、强制 SSL
+ *  - 敏感数据自动脱敏
+ *
+ * 兜底机制：
+ *  - 直连成功（2xx）→ 返回清洗后的文本/JSON
+ *  - 直连失败（非 2xx / 网络错误 / 超时）→ 自动经 Jina Reader 清洗后返回 Markdown
+ *  - 直连 200 但正文过短（< 200 字符，疑似 JS 挑战页）→ 也触发 Jina 兜底
+ *
+ * extractMode 参数：
+ *  - auto   （默认）直连优先，失败/异常走 Jina 兜底
+ *  - direct 强制直连，不兜底
+ *  - jina   强制直接走 Jina Reader（最干净，永远清洗）
  */
 import { ToolDef } from '../types/index.js'
-import { checkUrlSafety } from '../security/ssrf-guard.js'
+import { safeFetchWithRedirects, DEFAULT_FETCH_OPTIONS } from '../security/fetch-guard.js'
+import { redactSensitiveData } from '../security/redact.js'
+import { safeJinaFetch, resolveJinaApiKey } from './web-fetch-providers.js'
 
-const MAX_FETCH_CHARS = 100000
+const DEFAULT_MAX_CHARS = 100000
+// 正文过短阈值：低于此字符数视为疑似 JS 挑战页，触发 Jina 兜底（对齐 DESIGN.md §8 增强）
+const MIN_BODY_CHARS = 200
 
 /**
  * 简单的 HTML → 纯文本转换
@@ -35,7 +55,7 @@ function htmlToText(html) {
   return text
 }
 
-const VERSION = '2.0.0'
+const VERSION = '2.1.0'
 
 export const webFetchTool = new ToolDef(
   'WebFetch',
@@ -43,7 +63,9 @@ export const webFetchTool = new ToolDef(
 Usage:
 - url must be a valid HTTP/HTTPS URL
 - Returns the page content as cleaned text/markdown
-- Supports HTML pages, plain text, and JSON APIs`,
+- Supports HTML pages, plain text, and JSON APIs
+- If direct fetch fails (403/anti-crawl/network error), automatically falls back to Jina Reader for a clean Markdown version
+- extractMode: auto (direct first, fallback on failure) | direct (force direct only) | jina (always use Jina Reader)`,
   {
     type: 'object',
     properties: {
@@ -56,72 +78,104 @@ Usage:
         enum: ['text', 'json', 'raw'],
         description: 'Output format: text (cleaned HTML), json (parse as JSON), raw (raw response)',
       },
+      extractMode: {
+        type: 'string',
+        enum: ['auto', 'direct', 'jina'],
+        description: 'Extraction mode: auto (default, direct first + Jina fallback), direct (force direct), jina (always Jina Reader)',
+      },
     },
     required: ['url'],
   },
   async (input, ctx) => {
-    const { url, format = 'text' } = input
+    const { url, format = 'text', extractMode = 'auto' } = input
+
+    const config = ctx?.engine?.config?.configStore || null
+    const maxChars = config?.get?.('web.fetch.maxChars') || DEFAULT_MAX_CHARS
+    const maxBytes = config?.get?.('web.fetch.maxBytes') || DEFAULT_FETCH_OPTIONS.maxBytes
+    const timeoutMs = config?.get?.('web.fetch.timeoutMs') || DEFAULT_FETCH_OPTIONS.timeoutMs
+    const maxRedirects = config?.get?.('web.fetch.maxRedirects') || DEFAULT_FETCH_OPTIONS.maxRedirects
+    const jinaApiKey = resolveJinaApiKey(config)
 
-    // SSRF 安全检查
-    const urlSafety = await checkUrlSafety(url)
-    if (!urlSafety.allowed) {
-      return `[🚫 URL 被安全策略阻止]\n${urlSafety.reason}`
+    // extractMode=jina：强制直接走 Jina（永远清洗）
+    if (extractMode === 'jina') {
+      const jr = await safeJinaFetch(url, { apiKey: jinaApiKey, format: 'markdown', timeoutMs })
+      if (!jr.ok) return `[Error: ${jr.error}]`
+      const { text, redacted } = redactSensitiveData(jr.text)
+      const out = (jr.title ? `# ${jr.title}\n\n` : '') + text
+      const warning = redacted.length ? `\n\n[⚠️ 已脱敏: ${redacted.join(', ')}]` : ''
+      return (out + warning).slice(0, maxChars)
     }
 
-    try {
-      const response = await fetch(url, {
-        headers: {
-          'User-Agent': `ClaudeCode-Node/${VERSION}`,
-          'Accept': 'text/html,application/json,text/plain,*/*',
-        },
-        signal: AbortSignal.timeout(30000),
-      })
-
-      if (!response.ok) {
-        return `[HTTP ${response.status} ${response.statusText}]`
-      }
+    // 直连（安全管道：协议 + 连接级 SSRF + 重定向逐跳校验 + 大小/超时/SSL）
+    const result = await safeFetchWithRedirects(url, { timeoutMs, maxBytes, maxRedirects })
 
-      const contentType = response.headers.get('content-type') || ''
-      const body = await response.text()
-
-      // JSON 格式
-      if (format === 'json' || contentType.includes('application/json')) {
-        try {
-          const data = JSON.parse(body)
-          const formatted = JSON.stringify(data, null, 2)
-          return formatted.length > MAX_FETCH_CHARS
-            ? formatted.slice(0, MAX_FETCH_CHARS) + '\n[...truncated]'
-            : formatted
-        } catch {
-          return body.slice(0, MAX_FETCH_CHARS)
-        }
-      }
+    // extractMode=direct：不兜底，直接返回直连结果（无论成败）
+    if (extractMode === 'direct') {
+      return formatDirectResult(result, format, maxChars)
+    }
 
-      // 原始格式
-      if (format === 'raw') {
-        return body.length > MAX_FETCH_CHARS
-          ? body.slice(0, MAX_FETCH_CHARS) + '\n[...truncated]'
-          : body
+    // auto 模式：直连失败或内容过短 → 走 Jina 兜底
+    const failed = !result.ok || result.error
+    const tooShort = result.ok && result.body.trim().length < MIN_BODY_CHARS
+    if (failed || tooShort) {
+      if (config?.get?.('verbose')) {
+        console.error(`[web-fetch] direct ${failed ? `failed (${result.error || result.status})` : 'content too short'}, falling back to Jina Reader`)
       }
-
-      // HTML → 文本
-      if (contentType.includes('text/html')) {
-        const text = htmlToText(body)
-        return text.length > MAX_FETCH_CHARS
-          ? text.slice(0, MAX_FETCH_CHARS) + '\n[...truncated]'
-          : text
+      const jr = await safeJinaFetch(url, { apiKey: jinaApiKey, format: 'markdown', timeoutMs })
+      if (jr.ok) {
+        const { text, redacted } = redactSensitiveData(jr.text)
+        const out = (jr.title ? `# ${jr.title}\n\n` : '') + text
+        const warning = redacted.length ? `\n\n[⚠️ 已脱敏: ${redacted.join(', ')}]` : ''
+        return (out + warning).slice(0, maxChars)
       }
-
-      // 纯文本
-      return body.length > MAX_FETCH_CHARS
-        ? body.slice(0, MAX_FETCH_CHARS) + '\n[...truncated]'
-        : body
-    } catch (err) {
-      if (err.name === 'TimeoutError') {
-        return `[Error: Request timed out after 30s]`
-      }
-      return `[Error fetching URL: ${err.message}]`
+      // Jina 也失败 — 返回直连结果 + Jina 错误说明
+      return formatDirectResult(result, format, maxChars) +
+        `\n\n[Jina fallback also failed: ${jr.error}]`
     }
+
+    // 直连成功 — 返回直连结果
+    return formatDirectResult(result, format, maxChars)
   },
   'ask'
 )
+
+/**
+ * 格式化直连结果（含脱敏）
+ * @param {object} result — safeFetchWithRedirects 返回值
+ * @param {string} format
+ * @param {number} maxChars
+ */
+function formatDirectResult(result, format, maxChars) {
+  if (!result.ok) {
+    if (result.error) return `[Error: ${result.error}]`
+    return `[HTTP ${result.status} ${result.statusText || ''}]`.trim()
+  }
+
+  const contentType = result.headers['content-type'] || ''
+  const body = result.body
+
+  let out
+  if (format === 'json' || contentType.includes('application/json')) {
+    try {
+      const data = JSON.parse(body)
+      out = JSON.stringify(data, null, 2)
+    } catch {
+      out = body
+    }
+  } else if (format === 'raw') {
+    out = body
+  } else if (contentType.includes('text/html')) {
+    out = htmlToText(body)
+  } else {
+    out = body
+  }
+
+  // 敏感数据脱敏
+  const { text, redacted } = redactSensitiveData(out)
+  let final = text
+  if (result.truncated) final += '\n[...truncated]'
+  if (redacted.length) final += `\n[⚠️ 已脱敏: ${redacted.join(', ')}]`
+  if (result.redirects?.length) final += `\n[重定向: ${result.redirects.join(' → ')}]`
+
+  return final.length > maxChars ? final.slice(0, maxChars) + '\n[...truncated]' : final
+}