thincoder 0.12.54 → 0.12.59

package/src/escape.mjs

@@ -1,38 +1,91 @@
 /**
- * escape.mjs — 中和 OpenAI 兼容服务端在 message content 内做的非标二次转义解析。
+ * escape.mjs — 中和 OpenAI 兼容服务端在 message content 内做的非标二次转义解析 + 孤立代理净化。
  *
- * 某些服务端（Kimi 等）会把 content 里的字面 "\x" / "\u" 当作 hex escape 再解释一遍，
- * 遇到 "\x" 后不足 2 个 hex（或 "\u" 后不足 4 个 hex）时服务端报
- * "unexpected end of hex escape" → 400（首次观察于 2026-08-06，见 advisor.mjs 历史）。
+ * 两个独立毒源（均真机实证）：
  *
- * 对策：把这类"一旦被服务端二次展开就会非法"的字面序列提前 double 成 "\\x" / "\\u"，
- * 服务端二次解析后还原为字面量；合法完整的 "\xNN" / "\uNNNN" 原样放过（它们能展开成
- * 一个字节/码点）。JSON.stringify 层面的反斜杠转义由发送方负责，本模块不碰。
+ * ① 字面 hex 转义二次解析（2026-08-06 Kimi 首观察）：Kimi/deepseek 等网关会把 content 里的字面
+ *    "\x5Cx" / "\x5Cu" 当作 hex escape 再解释一遍，不足位时 400（"unexpected end of hex escape"）。
+ *    对策：不足位序列前 double 反斜杠（\\x5CxNN 形态还原为字面量）；合法完整序列放行。
+ *    Known limitation（2026-09-01 v3 修复）：反斜杠 run ≥3 时（如 "\\\x5Cu" 三反斜杠+u）v1 的
+ *    lookbehind 只看前 1 字符会整体放行，但二次解析按配对消费后尾部的 \x5Cu 仍裸露 → 炸。
+ *    修复：按 run 奇偶判断——run 为奇数时尾部的 \x5Cu/\x5Cx 裸露（需 double），偶数已配对（放行）。
+ *
+ * ② 孤立 UTF-16 代理对（2026-09-02 deepseek 真机实锤）：content 里的**真实孤立代理字符**
+ *    （高代理 U+D800-DBFF 无低代理跟随，或低代理 U+DC00-DFFF 无高代理前置）——JSON.stringify
+ *    输出 \ud83d（合法 JSON），但 deepseek 解析器严格 UTF-16 解码，孤立代理 → 400
+ *    （"unexpected end of hex escape" / "lone leading surrogate in hex escape"）。
+ *    来源实证：doc_search 结果预览 `slice(0, N)` 按 UTF-16 码元截断，emoji 🔴（代理对）恰在
+ *    截断边界被切成孤立高代理 → 注入 system reminder → 每轮发送 → deepseek 400。
+ *    对策：发送前把孤立代理替换为  U+FFFD（任何来源安全兜底）；源头截断点另修 UTF-16 安全切。
  */
 
-/** 中和单段文本里的非法字面转义序列。
- *  Known limitation (documented, accepted, VS Code port parity): an ODD backslash
- *  run of 3+ (e.g. "\\\x") leaves the trailing "\x" un-doubled — vanishingly rare
- *  in real conversation text (no such hit in the 2026-08-31 repro session). */
+/** 中和非法字面 hex 转义序列（毒源①）。 */
 export function escapeLiteralEscapes(text) {
   text = String(text ?? "")
-  return text
-    // (?<!\\) — 只有单个反斜杠才处理（"\\x" 已经是 double 的，必须原样放过）
-    // 前瞻：\x 后至少 2 个 hex 视为合法（服务端只展开前两个），只有不足 2 个的才 double
-    .replace(/(?<!\\)\\(x)(?![0-9a-fA-F]{2})/g, "\\\\$1")
-    .replace(/(?<!\\)\\(u)(?![0-9a-fA-F]{4})/g, "\\\\$1")
+  let out = ""
+  let i = 0
+  const n = text.length
+  while (i < n) {
+    const ch = text[i]
+    if (ch !== "\\") { out += ch; i++; continue }
+    // 数反斜杠 run 长度
+    let run = 0
+    while (i + run < n && text[i + run] === "\\") run++
+    const next = text[i + run]
+    if ((next === "x" || next === "u") && run % 2 === 1) {
+      // run 奇数 → 二次解析配对消费后尾部 \x5Cx/\x5Cu 裸露——hex 不足则网关炸 → 前插反斜杠 double
+      const need = next === "u" ? 4 : 2
+      const after = text.slice(i + run + 1, i + run + 1 + need)
+      if (!new RegExp(`^[0-9a-fA-F]{${need}}$`).test(after)) {
+        out += "\\".repeat(run + 1) + next
+        i += run + 1
+        continue
+      }
+      // 合法完整：输出全序列并跳过（hex 尾不重新扫描）
+      out += text.slice(i, i + run + 1 + need)
+      i += run + 1 + need
+      continue
+    }
+    out += "\\".repeat(run)
+    i += run
+  }
+  return out
+}
+
+/** 净化孤立 UTF-16 代理对（毒源②）：高代理无低代理跟随 / 低代理无高代理前置 → 替换为 。 */
+export function sanitizeLoneSurrogates(text) {
+  text = String(text ?? "")
+  let out = ""
+  let i = 0
+  const n = text.length
+  while (i < n) {
+    const cp = text.charCodeAt(i)
+    if (cp >= 0xd800 && cp <= 0xdbff) {
+      const next = text.charCodeAt(i + 1)
+      if (next >= 0xdc00 && next <= 0xdfff) { out += text[i] + text[i + 1]; i += 2; continue }
+      out += ""; i++; continue // 孤立高代理
+    }
+    if (cp >= 0xdc00 && cp <= 0xdfff) { out += ""; i++; continue } // 孤立低代理
+    out += text[i]; i++
+  }
+  return out
 }
 
-/** 对单条消息的 content 应用 escapeLiteralEscapes（支持字符串或 OpenAI 多模态 part 数组）。
+/** 发送前文本净化总入口：hex 转义中和 + 孤立代理净化。 */
+export function sanitizeText(text) {
+  return sanitizeLoneSurrogates(escapeLiteralEscapes(text))
+}
+
+/** 对单条消息的 content 应用 sanitizeText（支持字符串或 OpenAI 多模态 part 数组）。
  *  2026-08-31 会诊 F5：deepseek-v4-flash 网关对 tool_calls[].function.arguments 与
- *  reasoning_content 做同样的非标二次转义解析（字面 \x/\u 经工具参数/思考回传 → 400，
+ *  reasoning_content 做同样的非标二次转义解析（字面 \\x5Cx/\\x5Cu 经工具参数/思考回传 → 400，
  *  列号确定性复现 = 毒序列在 content 之外）——这两个字符串字段同样需要中和。 */
 export function escapeMessageContent(message) {
   const content = message?.content
   let changed = false
   let next = message
   if (typeof content === "string") {
-    const escaped = escapeLiteralEscapes(content)
+    const escaped = sanitizeText(content)
     if (escaped !== content) {
       next = { ...next, content: escaped }
       changed = true
@@ -40,7 +93,7 @@ export function escapeMessageContent(message) {
   } else if (Array.isArray(content)) {
     const parts = content.map((p) => {
       if (p && typeof p === "object" && p.type === "text" && typeof p.text === "string") {
-        const escaped = escapeLiteralEscapes(p.text)
+        const escaped = sanitizeText(p.text)
         if (escaped !== p.text) {
           changed = true
           return { ...p, text: escaped }
@@ -55,7 +108,7 @@ export function escapeMessageContent(message) {
     const tool_calls = next.tool_calls.map((tc) => {
       const args = tc?.function?.arguments
       if (typeof args === "string") {
-        const escaped = escapeLiteralEscapes(args)
+        const escaped = sanitizeText(args)
         if (escaped !== args) {
           tcChanged = true
           return { ...tc, function: { ...tc.function, arguments: escaped } }
@@ -69,7 +122,7 @@ export function escapeMessageContent(message) {
     }
   }
   if (typeof next.reasoning_content === "string") {
-    const escaped = escapeLiteralEscapes(next.reasoning_content)
+    const escaped = sanitizeText(next.reasoning_content)
     if (escaped !== next.reasoning_content) {
       next = { ...next, reasoning_content: escaped }
       changed = true
@@ -78,13 +131,15 @@ export function escapeMessageContent(message) {
   return changed ? next : message
 }
 
-/** IKBGX4 (2026-08-28)：剥离仅本地使用的整消息标记字段（transient 等）——发送给 provider 前移除。
+/** IKBGX4 + SESSION.md §9 D-S1：剥离仅本地使用的整消息标记字段（transient/ts）——发送给 provider 前移除。
  * 严格 OpenAI 兼容服务端（opencode/LiteLLM 等）会拒绝消息级未知 key
- * （"Extra inputs are not permitted, field: 'messages[i].transient'"）。 */
+ * （"Extra inputs are not permitted, field: 'messages[i].transient'"）；ts 同理
+ * （消息时间戳是本地取证字段，不进任何 provider 请求——T-S3）。copy-on-write：
+ * 历史里的原对象不动（read_history 仍能读到 ts）。 */
 export function stripLocalMessageFields(messages) {
   return messages.map((m) => {
-    if (m && typeof m === "object" && "transient" in m) {
-      const { transient, ...rest } = m
+    if (m && typeof m === "object" && ("transient" in m || "ts" in m)) {
+      const { transient, ts, ...rest } = m
       return rest
     }
     return m
@@ -94,4 +149,4 @@ export function stripLocalMessageFields(messages) {
 /** 对整个 messages 数组逐条应用 escapeMessageContent（先剥离本地字段，再转义）。 */
 export function escapeMessages(messages) {
   return stripLocalMessageFields(messages).map(escapeMessageContent)
-}
+}

package/src/log.mjs

@@ -0,0 +1,195 @@
+/**
+ * log.mjs — 诊断事件日志（docs/design/LOGGING.md 权威规格）。
+ * 双端同构：thincoder/src/log.mjs 与 thincoder-vscode/src/log.mjs 同一实现语义
+ * （共享 ~/.thincoder/logs/、同格式、同事件面——F-L6）。
+ *
+ * 常驻骨架日志：回合/LLM/工具/子代理/挂起的关键事件——每行一个 JSON 事件，按天轮转
+ * （agent-YYYY-MM-DD.log），保留 1 天——用户零手动维护（F-L3/NF-L4）。问题发生时
+ * 直接 tail/grep 定位断点（根治"临时插桩再删"循环）。
+ *
+ * 纪律（实现侧逐条落实）：
+ * - fire-and-forget：logEvent 失败静默降级（NF-L1）——主流程零影响。进程内首次写失败
+ *   即置死（_dead），当日不再尝试（磁盘满/权限错不逐事件空转）。
+ * - 单事件行 <512 字符（NF-L2）：head（LLM ≤300 / 工具 ≤200）、err ≤200 由调用方截断，
+ *   本模块对任意字符串字段做上限兜底（head 300 / err 200 / 其余 120）+ 超长时丢可选字段。
+ * - 敏感字段零落盘（NF-L3/§2.4，2026-09-03 评审 refinement #7 匹配语义定稿）：
+ *   ① 字段名精确匹配黑名单（apiKey/designToken/password/secret/token，大小写不敏感；
+ *      另加防御性名称 authorization/proxy/proxyUri——防凭据型 URL/头字段泄漏——§2.5）
+ *      → 整个字段丢弃；
+ *   ② 内容只扫密钥形态（sk-xxx / Bearer xxx / key=… 等）→ 截断到形态之前
+ *      ——宁可丢信息不漏密钥。
+ *   工具事件不记 args；URL 不入事件（llm/tool 事件从不携带 URL；err 文本经形态扫描）。
+ * - 摘要截断（B 方案，2026-09-03 用户裁定）：截断处带 "…" 标记（截后仍 ≤上限）。
+ * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实
+ *   诊断日志（两端测试套件都会跑真实 agent 管线）；显式设置 THINCODER_LOG_DIR 强制
+ *   写入该目录（log.test.mjs 用它隔离临时目录——refinement #6）。
+ * - 轮转清理（refinement #3——长驻进程覆盖）：非仅启动时——每进程每日**首次写事件**
+ *   时顺带清理 >1 天的 agent-*.log（extension host 可长驻数月，启动清理覆盖不到）。
+ * - seq：每进程单调计数器。双端同写一个文件时 seq 会各自重复——定位同文件时序以
+ *   ts 为准，seq 仅进程内参照（refinement #8）。
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, rmSync, existsSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** 单行长度硬上限（NF-L2） */
+export const MAX_LINE = 512
+/** 字段名精确黑名单（NF-L3/§2.4——2026-09-03 评审 refinement #7：与 §2.4 词表一致含 token） */
+const BLACKLIST_FIELDS = new Set(["apikey", "designtoken", "password", "secret", "token", "authorization", "proxyuri", "proxy"])
+/** 内容密钥形态扫描（大小写不敏感）——命中即截断到形态前 */
+const SECRET_FORM = /(\bsk-[A-Za-z0-9_-]{6,}|\bBearer\s+[A-Za-z0-9._~+/=-]{6,}|\b(?:api[_-]?key|key|token|secret|password|pwd|passwd)\s*[=:]\s*['"]?[A-Za-z0-9._~+/=-]{6,})/i
+/** 字符串字段长度兜底：head ≤300 / err ≤200 / 其余 ≤120 */
+const FIELD_CAPS = { head: 300, err: 200 }
+
+let _seq = 0
+let _dead = false // 进程内写失败即死（NF-L1 静默降级——不逐事件重复空转）
+let _cleanupDate = null // 本进程已执行过清理的日期（每日首次写时清一次）
+
+/** 日志目录：THINCODER_LOG_DIR（测试隔离/override）> ~/.thincoder/logs（与 sessions/ 同域） */
+export function logsDir() {
+  return process.env.THINCODER_LOG_DIR ?? join(homedir(), ".thincoder", "logs")
+}
+
+/** 今日日志文件路径（agent-YYYY-MM-DD.log） */
+export function todayLogPath(now = new Date()) {
+  const ymd = now.toISOString().slice(0, 10)
+  return join(logsDir(), `agent-${ymd}.log`)
+}
+
+/** 写门（测试隔离）：test runner 进程（NODE_TEST_CONTEXT）默认跳过——除显式
+ *  THINCODER_LOG_DIR override（log.test.mjs 隔离临时目录——refinement #6）。 */
+function writeEnabled() {
+  if (_dead) return false
+  if (process.env.NODE_TEST_CONTEXT && !process.env.THINCODER_LOG_DIR) return false
+  return true
+}
+
+/** 清理 >1 天的 agent-*.log（NF-L4——refinement #3：机会式，非仅启动时）。
+ *  保留窗口（2026-09-03 code review #1 修正）：以文件名日期的**当日结束**为龄基准——
+ *  今天+昨天的文件保留（任何事件至少留存 24h、最多 48h），早于昨天的删除。
+ *  无法按名解析日期的 agent-*.log 按 mtime 兜底（>1 天未写的删除）。
+ *  导出供测试直呼（T-L7/T-L7b）。静默：任何失败都不影响主流程。 */
+export const LOG_RETENTION_MS = 24 * 60 * 60 * 1000
+export function cleanupOldLogs(now = new Date()) {
+  const dir = logsDir()
+  if (!existsSync(dir)) return
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const name of names) {
+    if (!name.startsWith("agent-") || !name.endsWith(".log")) continue
+    const m = name.match(/^agent-(\d{4}-\d{2}-\d{2})\.log$/)
+    const ts = m ? Date.parse(m[1] + "T00:00:00Z") : NaN
+    // 文件名日期 → 龄以该日结束（ts+24h）计：事件在删除时至少已留存 24h
+    const ageMs = Number.isFinite(ts) ? now - (ts + LOG_RETENTION_MS) : (tryStatAge(dir, name, now) ?? Infinity)
+    if (ageMs > LOG_RETENTION_MS) {
+      try { rmSync(join(dir, name), { force: true }) } catch { /* 静默 */ }
+    }
+  }
+}
+
+function tryStatAge(dir, name, now) {
+  try {
+    return now - statSync(join(dir, name)).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 写入一条事件（fire-and-forget）。fields 内所有字符串都经黑名单/截断处理。
+ * 事件行结构：{"ts":ISO,"ev":kind,"seq":N,...fields}——单行 JSON <512 字符。
+ */
+export function logEvent(kind, fields = {}) {
+  if (!writeEnabled()) return
+  const now = new Date()
+  // 机会式轮转清理：每进程每日首次写事件时执行一次（refinement #3——长驻进程覆盖）
+  const ymd = now.toISOString().slice(0, 10)
+  if (_cleanupDate !== ymd) {
+    _cleanupDate = ymd
+    cleanupOldLogs(now)
+  }
+  const entry = { ts: now.toISOString(), ev: kind, seq: ++_seq }
+  for (const [k, v] of Object.entries(fields ?? {})) {
+    if (v === undefined || v === null) continue
+    // ① 字段名精确黑名单 → 丢弃（token 族永不落盘）
+    if (BLACKLIST_FIELDS.has(String(k).toLowerCase())) continue
+    if (typeof v === "string") entry[k] = sanitizeString(k, v)
+    else if (typeof v === "number" || typeof v === "boolean") entry[k] = v
+  }
+  let line = JSON.stringify(entry)
+  // ② 防御性收尾（NF-L2）：字段上限后仍超长 → 丢可选字段（保留 ts/ev/seq）直至 <512
+  while (line.length > MAX_LINE && Object.keys(entry).length > 3) {
+    for (const k of Object.keys(entry)) {
+      if (k !== "ts" && k !== "ev" && k !== "seq") { delete entry[k]; break }
+    }
+    line = JSON.stringify(entry)
+  }
+  try {
+    const dir = logsDir()
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(join(dir, `agent-${ymd}.log`), line + "\n", "utf8")
+  } catch {
+    _dead = true // NF-L1：写失败静默降级——主流程零影响
+  }
+}
+
+/** 共享脱敏（§18.6 D-TR2——trace-store 复用；logEvent 自身保持"丢弃字段"语义，
+ *  本函数提供"遮蔽标记"语义——同一字段名黑名单 + 同一 SECRET_FORM 形态扫描，
+ *  不发明新遮蔽模式）。字段名命中黑名单 → "[REDACTED]（整个字段遮蔽）；内容命中
+ *  密钥形态 → 截断到形态前 + "[redacted]" 标记（宁可丢信息不漏密钥——§2.4）。 */
+export function redactSecret(fieldKey, value) {
+  const s = String(value)
+  if (BLACKLIST_FIELDS.has(String(fieldKey).toLowerCase())) return "[REDACTED]"
+  const hit = s.match(SECRET_FORM)
+  return hit ? s.slice(0, hit.index) + "[redacted]" : s
+}
+
+/** 内容级净化：密钥形态截断到形态前（②）；超长截断 + "…" 标记。 */
+export function sanitizeString(key, value) {
+  let s = String(value)
+  // 密钥形态 → 截断到形态前（宁可丢信息不漏密钥——§2.4）
+  const hit = s.match(SECRET_FORM)
+  if (hit) s = s.slice(0, hit.index)
+  const cap = FIELD_CAPS[key] ?? 120
+  if (s.length > cap) s = s.slice(0, cap - 1) + "…"
+  return s
+}
+
+/** 错误文本提取：message + cause 链首条、压成单行、≤max（默认 200——NF-L2/§2.2） */
+export function errText(err, max = 200) {
+  let msg = err?.message ?? String(err ?? "")
+  if (!msg && err?.cause) msg = String(err.cause)
+  if (err?.cause?.message && !/^LLM API error/.test(msg)) msg += ` (${err.cause.message})`
+  msg = msg.replace(/\s*\n\s*/g, " ").trim()
+  if (msg.length > max) msg = msg.slice(0, max - 1) + "…"
+  return msg
+}
+
+/** 错误 kind 分类（llm:error 字段）：timeout（网关超时/超时信号）/ abort（用户中止）/
+ *  error（其余——API/网络/未分类）。signal 为请求中止信号（chat 调用点直传）。 */
+export function classifyErr(err, signal) {
+  const msg = String(err?.message ?? "").toLowerCase() + " " + String(err?.cause?.message ?? "").toLowerCase()
+  if (/timeout|timed ?out|etimedout|time limit exceeded/i.test(msg)) return "timeout"
+  if (err?.name === "AbortError" || signal?.aborted) {
+    return signal?.reason?.name === "TimeoutError" ? "timeout" : "abort"
+  }
+  return "error"
+}
+
+/** 文本头截取：前 max 字符、单行化（JSON 单行约束）、截断带 "…" 标记。
+ *  paragraph=true（llm:done 响应头）：取首段（首个空行前）——B 方案"首段文本"语义。 */
+export function headText(text, max, { paragraph = false } = {}) {
+  let s = String(text ?? "")
+  if (paragraph) {
+    const p = s.split(/\n\s*\n/, 1)[0]
+    if (p.length < s.length) s = p
+  }
+  s = s.replace(/\s*\n+\s*/g, " ").trim()
+  if (s.length > max) s = s.slice(0, max - 1) + "…"
+  return s
+}

package/src/mcp/transport-http.mjs

@@ -9,6 +9,9 @@ export function httpTransport(baseURL, extraHeaders = {}) {
   let sessionId = null
   let closed = false
   let eventSource = null
+  // 2026-09-01 MCP.md §4 D-1：GET SSE 不可用（405/不支持）降级后的纯 POST 模式标记。
+  // POST-only server（如 glm-websearch）无流可断：isAlive 不得因 eventSource == null 判死。
+  let postOnly = false
   let abortController = null
   let postUrl = url
   let legacySSE = false
@@ -232,5 +235,14 @@ export function httpTransport(baseURL, extraHeaders = {}) {
     pending.clear()
   }
 
-  return { send, notify, close, openSSE, url, headers: extraHeaders, isAlive: () => !closed && eventSource != null, onDead }
+  /** D-1：openSSE 降级（GET 405/不支持）后由 connect 链调用——标记纯 Streamable POST 模式 */
+  const markPostOnly = () => { postOnly = true }
+
+  return {
+    send, notify, close, openSSE, url, headers: extraHeaders,
+    // F1：POST-only 降级（postOnly）与 legacy SSE 流（eventSource）都算活连接——
+    // 不得因 eventSource == null 误判死（glm-websearch "reconnect failed" 根因）。
+    isAlive: () => !closed && (eventSource != null || postOnly),
+    onDead, markPostOnly,
+  }
 }

package/src/mcp.mjs

@@ -7,6 +7,12 @@ import { stdioTransport } from "./mcp/transport-stdio.mjs"
 import { httpTransport } from "./mcp/transport-http.mjs"
 import { wsTransport } from "./mcp/transport-ws.mjs"
 
+/** F6/D-5：config.token → `Authorization: Bearer <token>` 合成（仅当 headers 未显式给
+ *  Authorization——显式优先，向后兼容）。合成发生在传给 transport 前，不写回 config。 */
+export function withBearerToken(config) {
+  if (!config?.token || config.headers?.Authorization) return config
+  return { ...config, headers: { ...config.headers, Authorization: `Bearer ${config.token}` } }
+}
 
 /** Race a pending MCP request against an abort signal — a hung MCP server must not
  *  hold the turn hostage. signal absent → passthrough. */
@@ -31,8 +37,9 @@ async function sendWithSignal(promise, signal) {
 
 /** 2026-08-31 MCP 会诊 P5：CLI session 注册表（serverName → session）。
  *  session.state.transport 可变（重连替换）；buildTools 的 execute 动态取
- *  session.state.transport——server 崩溃后无需重建 agent.tools 即自愈。 */
-const _sessions = new Map()
+ *  session.state.transport——server 崩溃后无需重建 agent.tools 即自愈。
+ *  2026-09-01 MCP.md §4：导出给 /mcp test 的零副作用断言用（probe 后 _sessions 不增）。 */
+export const _sessions = new Map()
 /** 退避重连进行中（serverName → promise）——与 vscode 语义对齐；延迟表见 _mcpHooks。 */
 const _reconnecting = new Map()
 
@@ -44,7 +51,8 @@ export const _mcpHooks = {
 }
 
 /** 按 config 创建并完成握手的 transport（findTransportConfig 与 vscode 对齐）。 */
-async function createConnectedTransport(config, serverName) {
+async function createConnectedTransport(rawConfig, serverName) {
+  const config = withBearerToken(rawConfig) // F6/D-5：token 合成（不写回原 config）
   let transport
   if (config.wsUrl) {
     transport = wsTransport(config.wsUrl, config.headers ?? {})
@@ -54,7 +62,10 @@ async function createConnectedTransport(config, serverName) {
     try {
       await transport.openSSE()
     } catch {
-      // Server doesn't support GET SSE — degrade to pure Streamable HTTP POST mode
+      // Server doesn't support GET SSE — degrade to pure Streamable HTTP POST mode.
+      // MCP.md §4 D-1：显式标记 postOnly——POST-only server（glm-websearch 类）isAlive
+      // 不得因 eventSource == null 误判死（否则 ensureAlive 触发无意义重连循环）。
+      transport.markPostOnly()
     }
   } else {
     transport = stdioTransport(config.command, config.args ?? [], config.env)
@@ -63,6 +74,25 @@ async function createConnectedTransport(config, serverName) {
   return { transport, mcpTools }
 }
 
+/** F4/D-2：一次性探活——createConnectedTransport（initialize + tools/list）+ 计时。
+ *  零副作用：不进 _sessions、不动 agent.tools、无 onDead 挂钩；finally close
+ *  （closed=true 使 onDead 重连不会触发）。initialize 与 tools/list 同受
+ *  INIT_TIMEOUT_MS 约束（见 doInitialize）。不复用 connectMcpServer（避免污染
+ *  session 幂等表）。 */
+export async function probeMcpServer(config) {
+  const start = Date.now()
+  let transport
+  let mcpTools
+  try {
+    ;({ transport, mcpTools } = await createConnectedTransport(config, config.name ?? config.command ?? config.url ?? config.wsUrl))
+    return { ok: true, toolCount: mcpTools.length, latencyMs: Date.now() - start }
+  } catch (error) {
+    return { ok: false, error: error?.message ?? String(error) }
+  } finally {
+    try { transport?.close() } catch { /* ignore */ }
+  }
+}
+
 /** onDead → 后台退避重连；成功替换 session.state.transport（tools 闭包动态引用，
  *  agent.tools 无需重建）；失败静默（下次 execute 前置检查再试）。 */
 function scheduleReconnect(name, config) {
@@ -173,10 +203,14 @@ async function doInitialize(transport, _name) {
 
   // 2026-08-31 MCP 会诊 P6：tools/list 分页被忽略（nextCursor 多页工具静默丢失）——
   // 循环跟随 cursor 直到 server 不再返回（上限 20 页防死循环）。
+  // MCP.md §4 评审 #8：每页同受 INIT_TIMEOUT_MS 约束（否则 probe 的延迟统计无界）。
   const tools = []
   let cursor
   for (let page = 0; page < 20; page++) {
-    const toolsResp = await transport.send("tools/list", cursor ? { cursor } : {})
+    const toolsResp = await withTimeout(
+      transport.send("tools/list", cursor ? { cursor } : {}),
+      INIT_TIMEOUT_MS,
+    )
     if (toolsResp.error) throw new Error(`tools/list failed: ${toolsResp.error.message}`)
     tools.push(...(toolsResp.result?.tools ?? []))
     cursor = toolsResp.result?.nextCursor
@@ -192,7 +226,9 @@ export async function connectMcpServer(config) {
   if (!config || (!config.command && !config.url && !config.wsUrl))
     throw new Error(`MCP server "${config?.name ?? ""}": needs either 'wsUrl' (websocket), 'command' (stdio), or 'url' (http)`)
   const name = config.name ?? config.command ?? config.url ?? config.wsUrl
-  const configFingerprint = JSON.stringify([config.command ?? null, config.args ?? null, config.url ?? null, config.wsUrl ?? null, config.env ?? null, config.headers ?? null])
+  // MCP.md §4 D-5：fingerprint 计入 token 字段——/mcp edit 改 token → 指纹变更 →
+  // 旧连接主动关闭重建（T13）。
+  const configFingerprint = JSON.stringify([config.command ?? null, config.args ?? null, config.url ?? null, config.wsUrl ?? null, config.env ?? null, config.headers ?? null, config.token ?? null])
 
   const existing = _sessions.get(name)
   if (existing && !existing.closed) {
@@ -208,7 +244,16 @@ export async function connectMcpServer(config) {
     }
   }
 
-  const { transport, mcpTools } = await createConnectedTransport(config, name)
+  let transport
+  let mcpTools
+  try {
+    ;({ transport, mcpTools } = await createConnectedTransport(config, name))
+  } catch (error) {
+    // MCP.md §4 评审 #7：握手失败不泄漏 transport（GET SSE 降级成功但 POST initialize
+    // 失败时，openSSE 若开了流会留一个悬挂的 reader/请求）。
+    try { transport?.close() } catch { /* ignore */ }
+    throw error
+  }
   const session = {
     config, configFingerprint,
     state: { transport, tools: null },

package/src/memory/code-sync.mjs

@@ -313,7 +313,7 @@ export function codeSearchTool(memory) {
   return {
     name: "code_search",
     description:
-      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers.",
+      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written.",
     parameters: {
       type: "object",
       properties: {