weflow-cli 1.8.2 → 1.10.0

package/src/services/assistantTools.ts

@@ -1,1640 +1,2452 @@
-/**
- * Agent 工具注册表 (OpenAI function-calling 格式, DeepSeek 兼容)。
- * 所有工具在本机执行; 结果经 PrivacyGate 脱敏后才进入 LLM 上下文。
- */
-import { chatService } from './chatService.js'
-import { configService } from './configService.js'
-import { runPythonJson } from './pythonBridge.js'
-import { exportService } from './exportService.js'
-import type { AssistantMemory } from './assistantMemory.js'
-import { privacyGate } from './assistantPrivacy.js'
-import { existsSync, readFileSync, readdirSync } from 'fs'
-import { basename, join } from 'path'
-// 直接调进程的写法已收敛进 pythonBridge：这里不再 import child_process
-import { resolvePackageRoot } from '../utils/packageRoot.js'
-import type { Contact } from '../types.js'
-import { clipWithMarker } from '../utils/text.js'
-import { resolveSince, resolveUntil } from '../utils/dateRange.js'
-
-const PKG_ROOT = resolvePackageRoot(import.meta.url)
-const BIZ_DAILY_DIR = join(PKG_ROOT, 'output', 'biz-daily')
-/** 单条聊天消息进上下文的字数上限（见 get_messages：引用消息要放得下正文+被引原文） */
-const MSG_BODY_CHARS = 160
-// 知识页住在哪几个目录。**两个是有意的**：文章知识库与聊天知识库分开（用户 2026-09-27
-// 要求），所以读的一方要把**两个都读**——只读一个，分出去的那一半就静默地搜不到。
-// 与 Python 的 `_utils.CONCEPT_DIRS` 是同一份清单，有测试钉住两者一致（跨语言没法共用常量）。
-const VAULT_WIKI_DIRS = [
-  join(PKG_ROOT, 'output', 'wechat-vault', 'Wiki', 'Concepts'),
-  join(PKG_ROOT, 'output', 'wechat-vault', 'Chat', 'Concepts'),
-]
-
-/**
- * 概念名 → 文件名。**与 `compile_wiki` 是同一套规则**（非法字符换下划线、截到 60 字）。
- *
- * 这里必须消毒：邻居名是从**文件内容**里读出来的，直接拼进路径就能走出目录
- * （`../../` 那类）。文件名规则两边不一致也会让"查得到"变成"查不到"。
- */
-export function safeConceptFile(name: string): string {
-  return `${name.replace(/[\\/:*?"<>|]/g, '_').slice(0, 60)}.md`
-}
-
-/** 概念页正文的第一句（跳过 frontmatter、标题、引用、列表）——给"这个邻居是什么"。 */
-/**
- * 页面里「正文」的那一部分：`## 来源` 之前。
- *
- * **来源段不算正文** —— 它列的是文章标题（可能 300+ 条），拿它做「这个词在这页里吗」的判断，
- * 会把「某篇来源的标题里含这个词」报成「正文提及」。
- */
-export function pageBody(text: string): string {
-  const at = text.indexOf('## 来源')
-  return at === -1 ? text : text.slice(0, at)
-}
-/** 概念页里「相关概念」那一节指向的名字（按出现顺序）。 */
-function relatedNames(pagePath: string): string[] {
-  const text = readFileSync(pagePath, 'utf8')
-  const start = text.indexOf('## 相关概念')
-  if (start < 0) return []
-  const rest = text.slice(start + 1)
-  const end = rest.indexOf('\n## ')
-  const section = end > 0 ? rest.slice(0, end) : rest
-  return [...section.matchAll(/\[\[([^\]|]+)\]\]/g)]
-    .map(match => match[1].replace(/\.md$/, '').trim())
-    .filter(Boolean)
-}
-
-/**
- * 从一页出发，**沿着图走若干跳**，逐层返回 `{名字, 一句定义, 从谁连过来}`。
- *
- * 与 `conceptNeighbors` 的分工：那个给"一跳"（本页 + 直接邻居），这个给"一片"。助手此前只能
- * 一跳一跳地查（工具说明里写着"可以顺着它们再用本工具逐跳查下去"），但那要**模型自己决定**
- * 下一跳查谁。一次给两跳，它就能直接看到"这个概念周围的生态"。
- *
- * 三条规矩：
- * - **去重**：一个概念在图上有多条路径时只留**最先到达**的那条（BFS 保证它跳数最少），
- *   否则同一个名字会在好几层里重复出现，读的人分不清；
- * - **封顶**（`maxNodes`）：4 个邻居乘 4 乘 4 就是 64 —— 不封顶第三跳能把输出撑爆，而模型
- *   读不完的图等于没给。截断了要**说出来**（`truncated`），不能默默少给；
- * - **没建页的邻居照旧报数**（`missing`），不静默吞掉。
- */
-export function conceptSubgraph(pageName: string, depth = 2, maxNodes = 30,
-                                wikiDirs: string[] = VAULT_WIKI_DIRS): {
-  levels: Array<Array<{ name: string; brief: string; via: string }>>
-  truncated: boolean
-  missing: number
-} {
-  // 同 `conceptNeighbors`：传字符串会静默地按字符遍历，所以这里响，不猜。
-  if (typeof wikiDirs === 'string') {
-    throw new TypeError('conceptSubgraph 的 wikiDirs 要的是目录数组，不是单个字符串')
-  }
-  // 邻居可能住在另一个目录（文章概念指向聊天概念、反之亦然），所以查找跨目录
-  const find = (name: string): string | null => {
-    for (const dir of wikiDirs) {
-      const candidate = join(dir, safeConceptFile(name))
-      if (existsSync(candidate)) return candidate
-    }
-    return null
-  }
-  if (!find(pageName)) return { levels: [], truncated: false, missing: 0 }
-
-  const seen = new Set<string>([pageName])
-  const levels: Array<Array<{ name: string; brief: string; via: string }>> = []
-  let frontier = [pageName]
-  let truncated = false
-  let missing = 0
-  for (let hop = 0; hop < depth && frontier.length; hop += 1) {
-    const level: Array<{ name: string; brief: string; via: string }> = []
-    const next: string[] = []
-    for (const from of frontier) {
-      const fromPath = find(from)
-      if (!fromPath) continue
-      for (const name of relatedNames(fromPath)) {
-        if (seen.has(name)) continue
-        const target = find(name)
-        if (!target) {
-          missing += 1
-          continue
-        }
-        if (seen.size >= maxNodes) {
-          truncated = true
-          continue
-        }
-        seen.add(name)
-        level.push({ name, brief: conceptBrief(readFileSync(target, 'utf8')), via: from })
-        next.push(name)
-      }
-    }
-    if (level.length) levels.push(level)
-    frontier = next
-  }
-  return { levels, truncated, missing }
-}
-
-export function conceptBrief(text: string): string {
-  const body = text.startsWith('---') ? text.slice(text.indexOf('---', 3) + 3) : text
-  for (const raw of body.split('\n')) {
-    const line = raw.trim()
-    if (!line || /^[#>\-|`\[]/.test(line)) continue
-    return line.length > 60 ? `${line.slice(0, 60)}…` : line
-  }
-  return '(这页没写定义)'
-}
-
-/**
- * 一个概念页在 `## 相关概念` 里连到的邻居——**图谱在 Agent 侧的落地**。
- *
- * 为什么要有：Obsidian 的关系图谱是人眼视图，助手那条路一直读不到"图"。但概念页里
- * 本来就写着它的邻居，把它们一并给出去，"查一个概念"就变成"拿到一小块子图"。
- * 实测：全部概念页都短于这个工具返回的 2,000 字上限，所以那段一直在返回内容里
- * ——但**没人点明它可以顺着走**，也没人把邻居的一句话定义取出来。
- *
- * 有页的邻居连定义一起给；没有页的只报个数（`missing`），免得模型去追一个取不到的名字。
- */
-export function conceptNeighbors(pageName: string, wikiDirs: string[] = VAULT_WIKI_DIRS): { linked: Array<{ name: string; brief: string }>; missing: number } {
-  // **传字符串会静默地按字符遍历**（`for (const dir of 'D:\vault')` 挨个字符看过去），
-  // 于是 `join('D', '某概念.md')` 不存在，函数安静地回一句「没有邻居」。2026-09-27 把参数
-  // 从单个目录改成目录数组时，测试里正好踩到这个——类型拦得住 `src/`（`tsc` 覆盖它），
-  // 拦不住测试与将来的 JS 调用方。所以这里响，不猜。
-  if (typeof wikiDirs === 'string') {
-    throw new TypeError('conceptNeighbors 的 wikiDirs 要的是目录数组，不是单个字符串')
-  }
-  // **邻居可能住在另一个目录**（文章概念指向聊天概念、反之亦然），所以查找也是跨目录的
-  const find = (name: string): string | null => {
-    for (const dir of wikiDirs) {
-      const candidate = join(dir, safeConceptFile(name))
-      if (existsSync(candidate)) return candidate
-    }
-    return null
-  }
-  const pagePath = find(pageName)
-  if (!pagePath) return { linked: [], missing: 0 }
-  const text = readFileSync(pagePath, 'utf8')
-  const start = text.indexOf('## 相关概念')
-  if (start < 0) return { linked: [], missing: 0 }
-  const rest = text.slice(start + 1)
-  const end = rest.indexOf('\n## ')
-  const section = end > 0 ? rest.slice(0, end) : rest
-
-  const linked: Array<{ name: string; brief: string }> = []
-  let missing = 0
-  for (const match of section.matchAll(/\[\[([^\]|]+)\]\]/g)) {
-    const name = match[1].replace(/\.md$/, '').trim()
-    if (!name) continue
-    const target = find(name)
-    if (!target) {
-      missing += 1
-      continue
-    }
-    linked.push({ name, brief: conceptBrief(readFileSync(target, 'utf8')) })
-  }
-  return { linked, missing }
-}
-
-export interface ToolDef {
-  type: 'function'
-  function: {
-    name: string
-    description: string
-    parameters: Record<string, unknown>
-  }
-}
-
-export interface ToolContext {
-  userId: string
-  memory: AssistantMemory
-  /**
-   * 工具这一轮取到的图片，由 `look_at_image` 填。
-   *
-   * 图片走**侧信道**而不是工具返回值：工具返回值是字符串，要往里塞 base64 就得约定一个
-   * 魔法前缀再解析——那是这个仓库反复吃亏的"用文本承载结构"。服务层拿这个字段去把图片
-   * 附到对话里（见 `assistantService.toApiMessages`）。
-   */
-  pendingImages?: AttachedImage[]
-  /**
-   * 调用方是**外部机器**（MCP 那条路）时置 true。
-   *
-   * 与面板/微信那条路的区别不是审美：MCP 客户端是**别人家的进程**，它那边谁也看不到这一轮
-   * 是在什么上下文里决定调用的。所以对"会把用户数据送出去"的工具，机器调用默认只给**预览**，
-   * 要显式带 `confirm: true` 才真出境——与 CLI 那条 `--dry-run` / `--yes` 是同一套纪律，
-   * 也与 `capabilities.read.draft.confirmationRequired` 对得上。
-   */
-  requiresConfirm?: boolean
-}
-
-/** 随某条消息一起发出去的图片。只在构造请求那一刻存在，不进记忆、不进审计内容。 */
-export interface AttachedImage {
-  b64: string
-  mime: string
-  /** 来源消息的 local_id，只为了审计里能对上"发了哪条" */
-  localId?: number
-}
-
-/** 一轮对话里最多看几张图。每次调用一张，这是上限——图片按体积算钱，也按体积算隐私。 */
-const MAX_IMAGES_PER_TURN = 2
-
-function fmtTime(ts: number): string {
-  const n = Number(ts)
-  const d = n > 1e12 ? new Date(n) : new Date(n * 1000)
-  return `${d.getMonth() + 1}/${d.getDate()} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
-}
-
-/**
- * 转录里的时刻：`09-23 12:20`。
- *
- * 与 `fmtTime`（给用户看的工具输出用 `9/23 12:20`）**故意不同**：转录这一行的形状要和
- * Python 侧逐字一致，见 `transcriptLine`。改 `fmtTime` 会连带改用户看到的东西，所以这里单独一个。
- */
-function transcriptTime(ts: number): string {
-  const n = Number(ts)
-  const d = n > 1e12 ? new Date(n) : new Date(n * 1000)
-  const pad = (value: number) => String(value).padStart(2, '0')
-  return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
-}
-
-/** 单条消息进转录的截断长度。**必须等于** `scripts/reply_debt.py` 的 `DRAFT_MSG_CHARS`。 */
-export const TRANSCRIPT_MSG_CHARS = 160
-
-/**
- * 转录取**多少条**消息。**必须等于** `scripts/reply_debt.py` 的 `TRANSCRIPT_SIZE`。
- *
- * 与上面那个字数上限是一对：一个决定"多长的一段对话"，一个决定"每条多长"。两条入口
- * （面板/微信走 `--stdin`，命令行走 `--talker`）必须给出同一段对话——否则同一件事在两边
- * 判断出的结果会不一样，而**不会报任何错**。两边今天都是 30，但在这之前谁都没盯着它。
- */
-export const TRANSCRIPT_MESSAGES = 30
-
-/**
- * 消息是**谁**说的（对方那一侧）：**有解析出来的名字就用名字，没有就写「对方」**。
- *
- * **`senderUsername` 不参与**：它是数据库原列的 wxid（`wcdbCore` 的 `sender_username`、
- * `sqlcipherCore` 的 `StrTalker`），不是名字。拿它当标签有两个坏处——把**账号标识**交给云端
- * 模型，而且对模型没用（wxid 不告诉它这是谁）。
- *
- * 实测（本机 8 个会话、179 条别人发的消息）：`senderDisplay` 是有中文的名字 174 条，
- * `senderUsername` 是 wxid 形状 176 条，两者**从不相同**。所以这个替换不丢信息：
- * 群聊里照样分得清谁说的（名字比 wxid 还更有用），而标识不再出境。
- */
-export function speakerLabel(message: any): string {
-  return message.senderDisplay || '对方'
-}
-
-/**
- * 对话转录里的一行：`[09-23 12:20] 老王：那个文件你什么时候发我`。
- *
- * **这段形状在 Python 侧还有一份**：`reply_debt.format_line`（`draft_reply.py --talker`
- * 那条路自己读库时用它渲染）。两处必须逐字一致，否则同一段对话走不同入口会得到不同的转录——
- * 而它们**已经漂过**，实测三处不同：
- *
- * | | 这边（`--stdin`，面板/微信那条路） | Python `format_line`（`--talker` 命令行） |
- * | --- | --- | --- |
- * | 时刻 | `9/23 12:20` | `09-23 12:20` |
- * | 对方那句 | 写死「对方」 | `senderDisplay` 优先（单聊里就是人名） |
- * | 截断 | 160 字 | 120 字（留个 `…` vs 直接切掉） |
- *
- * 漂移里最危险的是「我」那个标记：脚本靠 `'] 我：'` 挑语气样本、靠 `lastFromMe` 判最后一条，
- * 改错一个字全都**静默失效**（不报错，只是判断与语气样本都变差）。
- * 所以有 `test/transcript-format-contract.test.ts`：同一批消息（含一条超长、一条非文本）
- * 把两边逐字比一遍。谁改了这一行的形状而不改另一边，那条会红。
- *
- * **`senderUsername` 永远不参与**（实测过）：它是**数据库原列的 wxid**
- * （`wcdbCore` 的 `sender_username`、`sqlcipherCore` 的 `StrTalker`），不是名字。
- * 拿它当发言人的标签会把账号标识喂给两个云端模型——而这一行的目的只是让模型分得清谁说的。
- * 所以规则是：**有解析出来的名字就用名字，没有就写「对方」**，绝不退回原列。
- * `senderDisplay` 在真实路径上是有值的（实测一条会话：文本与图片消息都带），所以这边
- * 正常会写成人名，「对方」只是兜底。
- */
-export function transcriptLine(message: any): string {
-  const raw = message.localType === 1
-    ? (message.content || message.parsedContent || '')
-    : (message.parsedContent || message.content || '')
-  const body = privacyGate.maskMessageBody(
-    clipWithMarker(String(raw).replace(/\n/g, ' '), TRANSCRIPT_MSG_CHARS),
-    { isText: message.localType === 1 })
-  const speaker = message.isSend ? '我' : speakerLabel(message)
-  return `[${transcriptTime(message.createTime)}] ${speaker}：${body}`
-}
-
-/** SSRF 防护: 仅 http(s), 拒绝内网/环回地址
- *
- * 导出是为了能测它：这是**抓取前的安全边界**，而它守着的是"别让助手被一条收藏里的链接
- * 带去访问内网"。纯函数，没有副作用。
- */
-export function isSafeUrl(raw: string): boolean {
-  try {
-    const u = new URL(raw)
-    if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
-    const h = u.hostname.toLowerCase()
-    if (!h) return false
-
-    // IPv6 字面量（URL 里带方括号）。Node 会把 [0:0:0:0:0:0:0:1] 归一成 [::1]，
-    // 但不碰 [fd00::1] 这类——所以下面按前缀逐个挡。
-    if (h.startsWith('[')) {
-      const inner = h.slice(1, -1)
-      if (inner === '::' || inner === '::1') return false
-      if (inner.startsWith('::ffff:')) return false      // IPv4 映射（可能是 127.0.0.1）
-      if (/^f[cd]/.test(inner)) return false             // fc00::/7 唯一本地
-      if (/^fe[89ab]/.test(inner)) return false          // fe80::/10 链路本地
-      return true
-    }
-
-    if (h === 'localhost') return false
-    // 纯数字或 0x 形式的整型主机名：内核会把它当 IPv4 用，而域名不可能是这种形状。
-    // （实测 Node 对 2130706433 / 0x7f000001 会归一成 127.0.0.1，这道是双保险。）
-    if (/^(0x[0-9a-f]+|[0-9]+)$/.test(h)) return false
-    // 私网前缀**只在真的是点分四段时**才判：否则 `10.example.com` 这种公网域名会被
-    // `^10\.` 误杀，工具会回一句「链接不安全，拒绝抓取」，而链接其实是好的。
-    if (/^[0-9]{1,3}(\.[0-9]{1,3}){3}$/.test(h)) {
-      if (/^(127\.|10\.|192\.168\.|169\.254\.|0\.)/.test(h)) return false
-      if (/^172\.(1[6-9]|2[0-9]|3[01])\./.test(h)) return false
-    }
-    // 这是一份已知形态的黑名单，不是"这地址一定可公网路由"的证明：
-    // NAT64（64:ff9b::/96）等映射形式不在覆盖范围内。
-    return true
-  } catch { return false }
-}
-
-
-/** 标签剥离 → 纯文本 */
-export function stripTags(seg: string): string {
-  return seg.replace(/<script[\s\S]*?<\/script>/gi, ' ')
-    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
-    .replace(/<[^>]+>/g, '\n')
-    .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
-    .split('\n').map(s => s.trim()).filter(Boolean).join('\n')
-}
-
-/** WAF 挑战页兜底: 正文藏在 cgiDataNew.content_noencode (JS 转义字符串) */
-export function extractFromChallengePage(html: string): string | null {
-  const start = html.indexOf("content_noencode: '")
-  if (start < 0) return null
-  let i = start + "content_noencode: '".length
-  let out = ''
-  while (i < html.length && out.length < 1_000_000) {
-    const ch = html[i]
-    if (ch === "'") break
-    if (ch === '\\' && i + 1 < html.length) {
-      const n = html[i + 1]
-      if (n === 'x' && i + 3 < html.length) {
-        out += String.fromCharCode(parseInt(html.slice(i + 2, i + 4), 16))
-        i += 4
-        continue
-      }
-      if (n === 'n') { out += '\n'; i += 2; continue }
-      if (n === 'r') { out += '\r'; i += 2; continue }
-      if (n === 't') { out += '\t'; i += 2; continue }
-      if (n === '\\' || n === "'" || n === '"') { out += n; i += 2; continue }
-    }
-    out += ch
-    i++
-  }
-  return out.length > 100 ? out : null
-}
-
-/** 从 HTML 提取正文文本 (微信公众号 js_content 优先, 配平 div 边界; 兜底 body) */
-export function extractText(html: string): string {
-  let seg = html
-  const jc = html.indexOf('id="js_content"')
-  if (jc >= 0) {
-    // 配平 <div/</div> 找 js_content 完整区块; depth 从 1 起算 (自身开标签位于 jc 之前)
-    let depth = 1, end = -1
-    const tag = /<\/?div\b/g
-    tag.lastIndex = jc
-    let m: RegExpExecArray | null
-    while ((m = tag.exec(html))) {
-      if (m[0] === '</div') { depth--; if (depth === 0) { end = m.index; break } }
-      else depth++
-    }
-    seg = end > jc ? html.slice(jc, end) : html.slice(jc, jc + 100_000)
-  } else {
-    const body = html.indexOf('<body')
-    if (body >= 0) seg = html.slice(body)
-  }
-  return stripTags(seg)
-}
-
-/** 确保数据库已连接 (connect 幂等, 已连接时直接返回) */
-async function ensureDb(): Promise<void> {
-  await chatService.connect()
-}
-
-/** 最近一份**有内容**的日报是哪天，以及那是几天前。算不出来就回空串——不猜。 */
-function lastDailyNote(): string {
-  try {
-    const days = readdirSync(BIZ_DAILY_DIR)
-      .filter(name => /^\d{4}-\d{2}-\d{2}$/.test(name)).sort().reverse().slice(0, 30)
-    for (const day of days) {
-      const file = join(BIZ_DAILY_DIR, day, '.articles.json')
-      if (!existsSync(file)) continue
-      const payload = JSON.parse(readFileSync(file, 'utf8'))
-      if ((payload?.articles ?? []).length) {
-        const ago = Math.round((Date.now() - new Date(`${day}T00:00:00`).getTime()) / 86_400_000)
-        return `；最近一次有内容的日报是 ${day}（${ago} 天前）`
-      }
-    }
-  } catch { /* 扫不出来就什么都不说，而不是猜一个日期 */ }
-  return ''
-}
-
-interface TalkerCandidate {
-  username: string
-  displayName?: string | null
-}
-
-class ToolInputError extends Error {}
-
-export function boundedToolInteger(value: unknown, fallback: number, maximum: number, field = 'limit'): number {
-  if (value === undefined || value === null || value === '') return fallback
-  const parsed = Number(value)
-  if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
-    throw new ToolInputError(`${field} 必须是 1-${maximum} 的整数`)
-  }
-  return parsed
-}
-
-export function resolveUniqueTalker(name: string, sessions: TalkerCandidate[]): string {
-  const query = name.trim()
-  if (!query) throw new ToolInputError('contact 不能为空')
-
-  const unique = (matches: TalkerCandidate[]) => [...new Set(matches.map(item => item.username))]
-  const usernameMatches = unique(sessions.filter(item => item.username === query))
-  if (usernameMatches.length === 1) return usernameMatches[0]
-
-  const exactNameMatches = unique(sessions.filter(item => item.displayName === query))
-  if (exactNameMatches.length === 1) return exactNameMatches[0]
-  if (exactNameMatches.length > 1) {
-    throw new ToolInputError(`会话名称“${query}”对应多个会话，请改用会话 ID`)
-  }
-
-  const partialMatches = unique(sessions.filter(item => item.displayName?.includes(query)))
-  if (partialMatches.length === 1) return partialMatches[0]
-  if (partialMatches.length > 1) {
-    throw new ToolInputError(`会话名称“${query}”匹配多个会话，请提供更完整名称或会话 ID`)
-  }
-  return query
-}
-
-/**
- * 通讯录里按 **备注 / 显示名 / 昵称 / 别名 / username** 找唯一的一个；找不到或有歧义回 null。
- *
- * 与 `resolveUniqueTalker` 同一套纪律：**只认唯一**，不猜。
- */
-export async function lookupContactUsername(name: string): Promise<string | null> {
-  const query = name.trim()
-  if (!query) return null
-  // 窗口给宽一点：关键字命中的是**包含**它的所有名字，一个字的查询能匹配到几十个人，
-  // 而精确那一个可能排在 20 名之后。实测（378 个真实联系人，都不在最近会话里）：
-  // 20 名时漏 6 个、60 名时漏 5 个，**认错都是 0 个**。剩下那 5 个都是单字名——它匹配到
-  // 几十个人，精确的那个仍在窗口之外。这个残余是安全的：回 null，助手说"没找到"，
-  // 而不会读到别人的聊天。
-  const contacts = await chatService.listContacts(query, 60)
-  const fields = (contact: Contact) => [contact.remark, contact.displayName, contact.nickname, contact.alias]
-    .filter(Boolean) as string[]
-  const exact = contacts.filter(c => c.username === query || fields(c).some(f => f === query))
-  const pool = exact.length ? exact : contacts.filter(c => fields(c).some(f => f.includes(query)))
-  const usernames = [...new Set(pool.map(c => c.username))]
-  return usernames.length === 1 ? usernames[0] : null
-}
-
-/**
- * 显示名 → username 解析。
- *
- * 会话列表**只取最近 300 个**，而通讯录是完整的：名字不在那 300 个里时（对话很多的人，或
- * 很久没聊过的人），旧行为是把查询词原样当 talker 返回——于是下游读到空、助手说"没找到
- * 消息"，而那个人其实在通讯录里。所以**匹配不上时再查一次通讯录**。
- *
- * 兜底只做"名字 → username"，不去验证这个会话有没有消息：没有消息时下游会如实说
- * "没找到消息"，那是对的答案，不该在这里变成"查无此人"。
- */
-async function resolveTalker(name: string): Promise<string> {
-  const sessions = await chatService.listSessions(undefined, 300)
-  const talker = resolveUniqueTalker(name, sessions)     // 歧义会抛，让它抛
-  if (sessions.some(session => session.username === talker)) return talker
-  const fromBook = await lookupContactUsername(name)
-  return fromBook ?? talker
-}
-
-export const TOOL_DEFS: ToolDef[] = [
-  {
-    type: 'function',
-    function: {
-      name: 'list_sessions',
-      description: '列出用户最近的微信聊天会话(显示名+最后一条消息摘要)。用于了解用户最近在和谁聊天。',
-      parameters: {
-        type: 'object',
-        properties: {
-          limit: { type: 'number', description: '返回条数, 默认15' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_messages',
-      description: '读取用户与某位联系人的聊天记录。默认给最近若干条；'
-        + '问**某一天或某段时间**时给 since/until —— 不给的话久远的日子按条数是取不到的。'
-        + '联系人名用会话里出现的显示名。',
-      parameters: {
-        type: 'object',
-        properties: {
-          contact: { type: 'string', description: '联系人显示名或备注名' },
-          limit: { type: 'number', description: '消息条数, 默认20, 上限50' },
-          since: { type: 'string', description: '起点：2026-09-16 或相对写法 3d / 2w / 12h' },
-          until: { type: 'string', description: '终点（含当天）：2026-09-16' },
-        },
-        required: ['contact'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'look_at_image',
-      description: '看聊天里的一张图片（把图片本身交给模型看，不只是"这里有一张图"）。'
-        + '`image` 填 get_messages 输出里 `[图片 #1234]` 的编号。'
-        + '一轮最多看两张；隐私模式为 strict 时不可用（聊天图片不出发本机）。',
-      parameters: {
-        type: 'object',
-        properties: {
-          contact: { type: 'string', description: '这张图所在会话的联系人显示名' },
-          image: { type: 'string', description: 'get_messages 里 [图片 #N] 的编号 N' },
-        },
-        required: ['contact', 'image'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'search_favorites',
-      description: '搜索用户的微信收藏(主要是收藏的公众号文章)；**不给关键词就是最近收藏了什么**。',
-      parameters: {
-        type: 'object',
-        properties: {
-          keyword: { type: 'string', description: '搜索关键词' },
-          limit: { type: 'number', description: '返回条数, 默认8' },
-        },
-              },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'read_favorite',
-      description: '读取一篇收藏文章的正文内容。先用 search_favorites 或按关键词找到文章标题, 再用标题关键词调本工具抓取正文。适合「这篇文章讲了啥」「总结第一篇」类问题。',
-      parameters: {
-        type: 'object',
-        properties: {
-          keyword: { type: 'string', description: '文章标题中的关键词' },
-          max_chars: { type: 'number', description: '返回正文字数上限, 默认3000' },
-        },
-        required: ['keyword'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_daily_report',
-      description: '获取公众号日报: 某天推送了哪些文章(标题/来源/分类/AI摘要)。适合「今天/某天公众号推了什么」「最近有哪些AI文章」类问题。',
-      parameters: {
-        type: 'object',
-        properties: {
-          date: { type: 'string', description: '日期 YYYY-MM-DD, 默认最新一期' },
-          topic: { type: 'string', description: '分类过滤: AI | 学术 | 新闻 | 文学 | 投资' },
-          keyword: { type: 'string', description: '标题/摘要关键词过滤' },
-          limit: { type: 'number', description: '返回条数, 默认15' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_sns',
-      description: '查看用户朋友圈: 最新动态时间线或统计概览(发帖数/好友数)。适合「朋友圈最近发了啥」「谁常发朋友圈」类问题。',
-      parameters: {
-        type: 'object',
-        properties: {
-          mode: { type: 'string', description: 'timeline (最新动态) / stats (统计) / users (谁发得最多), 默认 timeline' },
-          limit: { type: 'number', description: 'timeline 模式条数, 默认10' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_weread',
-      description: '查看用户微信读书数据: 书架(shelf)、笔记(notebooks)、搜索书(search)。适合「我在读什么书」「某本书的笔记」类问题。',
-      parameters: {
-        type: 'object',
-        properties: {
-          mode: { type: 'string', description: 'shelf | notebooks | search, 默认 shelf' },
-          keyword: { type: 'string', description: 'search 模式的书名关键词' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_todos',
-      description: '查看用户从聊天记录提取的待办任务清单(含优先级和截止时间)。适合「我最近有什么待办」「有什么紧急的事」类问题。',
-      parameters: {
-        type: 'object',
-        properties: {
-          status: { type: 'string', description: 'pending | done, 默认 pending' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'search_chats',
-      description: '在**聊天记录**里检索「在哪聊过某件事」，按字面词匹配。适合「上次说的那个部署方案是在哪聊的」。'
-        + '（知识库用 search_knowledge；助手记得的关于你的事用 search_memory）'
-        + '「谁提过这个客户」这类问题。它只匹配字面词（同义改写要靠别的路子），所以问题描述得具体些。'
-        + '代价：会把你的问题与候选词发给判断模型（不发聊天正文），约 1-2 秒。',
-      parameters: {
-        type: 'object',
-        properties: {
-          question: { type: 'string', description: '要找的事，用自然语言描述' },
-          per_card: { type: 'number', description: '每个会话最多回几条消息，默认 3' },
-          confirm: {
-            type: 'boolean',
-            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
-          },
-        },
-        required: ['question'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'draft_reply',
-      description: '帮用户**起草**一条回复（只产出候选文本，绝不替他发送）。适合「帮我回老王那句话」'
-        + '「这条怎么回」。会先判断对方要什么、该不该给实质内容、风险多高，再给几条候选。'
-        + '涉及钱或风险很高时**不给草稿**，只说明风险与该先确认什么——别把这种情况当失败。'
-        + '（想看对方写了什么用 get_messages；想知道谁在等用 who_owes_reply。）'
-        + '代价：要把这段对话发给判断模型与生成模型（两个云端模型），约几秒；'
-        + '**外部机器调用（MCP）不带 confirm 时只返回预览**（发多少字符给谁），不实际出境。',
-      parameters: {
-        type: 'object',
-        properties: {
-          contact: { type: 'string', description: '给谁起草（联系人名，和 get_messages 一样解析）' },
-          count: { type: 'number', description: '要几条候选，默认 3（最多 5）' },
-          confirm: {
-            type: 'boolean',
-            description: '仅当用户**明确同意**把这段对话发给两个云端模型时才传 true。'
-              + '不传或传 false 时只返回预览（多少条消息、多少字符、发给哪两个模型），零出境。',
-          },
-        },
-        required: ['contact'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'who_owes_reply',
-      description: '看看谁在等你回话（对方说完就没下文的那种）。适合「我有没有漏回谁的消息」。'
-        + '代价：逐会话问一次判断模型，可能要几十秒；只报谁在等，不回正文。',
-      parameters: {
-        type: 'object',
-        properties: {
-          days: { type: 'number', description: '只看最近多少天有动静的会话，默认 14' },
-          confirm: {
-            type: 'boolean',
-            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
-          },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'search_semantic',
-      description: '按**意思**找聊天记录（语义/同义检索），而 search_chats 只匹配字面词——'
-        + '想不起原话、只记得大意时用它。'
-        + '「上次说的那个部署方案是在哪聊的」用 search_chats；「和钱有关的讨论」这种同义改写用这条。'
-        + '代价：查询词会发给阿里云百炼做嵌入、候选片段会发给判断模型重排（都是仓库既有的云端路径），'
-        + '需要先建过索引（weflow-cli search-index）。',
-      parameters: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: '要找的意思，用自然语言描述' },
-          top_k: { type: 'number', description: '要几条，默认 8，上限 20' },
-          confirm: {
-            type: 'boolean',
-            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
-          },
-        },
-        required: ['query'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'export_chat',
-      description: '把某个人的聊天记录导出成 HTML（含图片），落到 output/exports/ 下。'
-        + '适合「帮我把和某某的聊天导出备份一下」。**会写文件**：每次新建一个带时间戳的目录，绝不覆盖已有的，'
-        + '路径也不是你给而是固定的。',
-      parameters: {
-        type: 'object',
-        properties: {
-          contact: { type: 'string', description: '联系人显示名或备注名' },
-          limit: { type: 'number', description: '最多导出多少条，默认 500，上限 5000' },
-          format: { type: 'string', description: 'html(默认,含图片) / txt / json / excel' },
-        },
-        required: ['contact'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'search_knowledge',
-      description: '搜索**本地知识库**（从公众号文章沉淀的 Wiki 概念页与学习日报），适合查概念解释、找之前整理过的知识。'
-        + '**返回时会一并给出这一页连到的相关概念（每个一句定义）**——可以顺着它们再用本工具逐跳查下去，'
-        + '这样一次追问能走开一小块知识，而不是停在一个孤立页面上。'
-        + '（聊天里说过什么用 search_chats；助手记得的关于你的事用 search_memory）',
-      parameters: {
-        type: 'object',
-        properties: {
-          keyword: { type: 'string', description: '概念名或关键词, 如 RAG、Agent' },
-          depth: { type: 'integer', description: '沿「相关概念」走几跳：默认 1 只给直接邻居，2 能一次看到这个概念周围的生态（最多 3）' },
-        },
-        required: ['keyword'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_stats',
-      description: '获取用户本地微信数据统计(会话数/收藏总数等)。',
-      parameters: { type: 'object', properties: {} },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'get_reading_stats',
-      description: '**公众号**推送与日报处理的统计：哪些号发得多、哪些被日报处理得多。'
-        + '适合"哪个号发得最多""日报处理了多少篇"这类问题。'
-        // 原文写的是「回答"我最近都在读什么/哪个号发得最多"这类问题时用它」——
-        // 而"我最近在读什么"**正是微信读书的问题**。2026-09-28 实测：用户问"我在读什么书"，
-        // 模型抓住这一句用了它，返回一串公众号推送量（"发得最多的是红星新闻"），
-        // 用户看到的就是一个答非所问的答复。工具没错，错在这句说明侵占了读书的问题空间。
-        + '**它统计的是公众号推送与日报，不含读书数据**——"我在读什么书"那类问题不要用它。'
-        + '**日报没在跑的时候它会直说**（那不是"没内容"）。',
-      parameters: {
-        type: 'object',
-        properties: {
-          days: { type: 'number', description: '统计最近多少天，默认 7，上限 90' },
-        },
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'search_memory',
-      description: '搜索**助手记得的关于你的事**（此前对话里提取的长期事实：偏好、项目、关系）。'
-        + '（聊天正文用 search_chats，整理过的知识用 search_knowledge）',
-      parameters: {
-        type: 'object',
-        properties: {
-          keyword: { type: 'string', description: '搜索关键词' },
-        },
-        required: ['keyword'],
-      },
-    },
-  },
-  {
-    type: 'function',
-    function: {
-      name: 'save_memory',
-      description: '把关于用户的重要持久事实存入长期记忆(如偏好、项目背景、重要关系)。',
-      parameters: {
-        type: 'object',
-        properties: {
-          content: { type: 'string', description: '事实内容, 40字以内' },
-        },
-        required: ['content'],
-      },
-    },
-  },
-]
-
-/**
- * MCP 那条路看得见的工具表。
- *
- * **它不叫 read-only**（曾经叫，而那是假的）：里面一直有写文件的 `export_chat`，也有几个会把
- * 用户数据发给云端模型、需要 `confirm: true` 的工具。这里只排除**在那条路上根本做不了事**的，
- * 而"为什么做不了"写在下面那张表里（值就是原因，不是 true）：
- *
- * - `save_memory`：写记忆。MCP 没有微信用户身份，挂的记忆桶是单独一条；让它写没有意义。
- * - `look_at_image`：它的做法是把图**挂进侧信道**（`ctx.pendingImages`）交给助手自己的模型看，
- *   而 MCP 那条路只把工具返回的**文本**交给客户端（见 `mcp-server/index.ts` 的 default 分支）——
- *   图没人接，回话里却写着"已附上图片…你能看到它了"，那是**一句假话**。
- *   按本仓"不摆一个跑不了的工具"那条立论（同 `unavailableToolReason`），它不该出现在这里。
- *
- * 做成表而不是写进 filter：这是**注册表的一部分**，`test/tool-registry.test.ts` 会盯着
- * 表里的每个名字都真的存在于 `TOOL_DEFS`（写错一个名字 = 静默地没排除掉任何东西）。
- */
-export const MCP_EXCLUDED: Record<string, string> = {
-  save_memory: 'MCP 没有微信用户身份，挂的记忆桶是单独一条，让它写没有意义',
-  look_at_image: 'MCP 只把工具返回的文本交给客户端，它挂进侧信道的图没人接，回话会变成一句假话',
-}
-
-export const MCP_TOOL_DEFS = TOOL_DEFS.filter(tool => !(tool.function.name in MCP_EXCLUDED))
-
-/** 脚本类工具的失败回话：桥接层已经分好类（超时/退出码/没有 JSON/脚本自己报错），
- *  这里把它和 stderr 尾巴合起来**过一遍脱敏**再交给模型——stderr 里可能有密钥形状的东西，
- *  而工具结果是要出境的。
- */
-function fail(what: string, result: { error?: string; stderr?: string }): string {
-  const detail = [result.error, result.stderr].filter(Boolean).join(' · ')
-  const { safe } = privacyGate.redact(detail)
-  return `(${what}${safe ? ": " + safe : ""})`
-}
-
-/**
- * **括号起头 = 工具没能给出内容**。这是本仓库既有的写法：`fail()` 与各分支的
- * "查不到 / 缺参数 / 拒绝抓取"一律写成 `(…)`，而正常内容不带括号。
- *
- * 这张白名单是**唯一的例外**：成功的句子也可以是括号起头（不然它就不叫例外了）。
- * 有一条测试盯着它——白名单里每一条都必须在 `assistantTools.ts` 里真的以 `return` 出现，
- * 改措辞忘了同步就会红。反过来（有新的成功消息带括号、但没进白名单）测试抓不到，
- * 这是这个信号的真实边界：**它靠约定，不是一个机器可读的成败字段**。
- *
- * 想要真字段，得把 outcome 从 ~40 个 return 处一路带出来（`ToolContext.outcome`）。
- * 那件事记在 D-043 的"已知边界"里，没有做——这里用它是因为轨迹只想知道"这一步有没有
- * 产出东西"，而这个判断错了的代价是报告里多一个/少一个「无内容」标记。
- */
-export const PAREN_SUCCESS_PREFIXES = ['(已附上图片']
-
-/** 工具这次**有没有给出内容**。括号起头（除白名单外）都算没有。 */
-export function producedContent(text: string): boolean {
-  const head = (text ?? '').trimStart()
-  if (!head.startsWith('(')) return true
-  return PAREN_SUCCESS_PREFIXES.some(prefix => head.startsWith(prefix))
-}
-
-/**
- * "这台机器上跑不了"的**声明**：缺哪个配置键、缺了之后怎么跟用户说（值就是那句话）。
- *
- * 做成一张表而不是一串 `if (name === '...')`：加一个带前置条件的工具，现在是在这里加**一行**，
- * 而不是在 if 链里再插一段；`test/tool-registry.test.ts` 盯着表里的每个名字都真的存在于 `TOOL_DEFS`
- * （写错名字 = 那条规则永远不生效，而且不会有任何报错）。
- *
- * **只写"缺了就跑不了"的前置条件**，不写"暂时没数据"——没数据时工具自己会说该运行什么
- * （`先运行 weflow-cli wiki compile`），那是有用的回答。
- */
-export const TOOL_REQUIREMENTS: Record<string, { key: string; why: string }> = {
-  search_semantic: { key: 'dashscopeApiKey', why: '语义检索需要 dashscopeApiKey' },
-  get_weread: { key: 'wereadApiKey', why: '微信读书需要 wereadApiKey' },
-  draft_reply: {
-    key: 'deepseekApiKey',
-    // **只有 DeepSeek 是必须的**。判断那一步（Jev）现在可降级：调不通就只用生成模型起草，
-    // 输出里会写明"这次没有判断、闸门没生效"（2026-09-25 Jev 免费期结束那天改的）。
-    // 所以缺 typesafeApiKey **不**该把这个工具收起来——那会让"能跑的工具"被藏掉。
-    why: '起草回复需要 deepseekApiKey（生成那一步）',
-  },
-}
-
-/**
- * 这台机器上**跑不了**的工具，不该出现在工具表里。规则本身在上面的 `TOOL_REQUIREMENTS` 里，这里只是执行它。
- *
- * 为什么按配置过滤：模型看见工具就会去试。这台机器没配 `dashscopeApiKey` 时 `search_semantic`
- * 必然失败——实测（评测的 `ambiguous-contact` 那次）模型连试两个检索工具、两个都报错，最后答复
- * 里带着"两个检索工具都跑不通"。那不是助手的问题，是**我们摆了一个跑不了的工具**。工具越少，
- * 选择也越准。
- */
-export function unavailableToolReason(name: string, config: (key: any) => any = configService.get.bind(configService)): string | null {
-  const need = TOOL_REQUIREMENTS[name]
-  if (!need) return null
-  return String(config(need.key) || '').trim() ? null : need.why
-}
-
-/**
- * 这台机器上**没启用**的能力，一句话一条，给系统提示词用。
- *
- * 为什么需要它：工具被藏起来之后，模型**看不见它存在**，于是用户问"我在读什么书"时它答
- * "我没有 get_weread 这个工具" —— 2026-09-28 实测就是这么一轮对话，用户因此以为功能没做
- * （其实做了、只是没配 key）。把"存在但没启用"告诉模型，它就能给出正确的下一步，
- * 而不是否认这个功能存在。
- *
- * **这不等于把工具摆回去**：模型依然调不到它们，只是知道它们存在。把跑不了的工具放进工具表
- * 的代价是实测过的（模型会去试，答复里带着一串报错，见 `availableToolDefs` 的说明）。
- */
-export function unavailableCapabilities(
-  config: (key: any) => any = configService.get.bind(configService),
-): string[] {
-  return Object.entries(TOOL_REQUIREMENTS)
-    .filter(([name]) => unavailableToolReason(name, config))
-    .map(([, need]) => need.why)
-}
-
-/** 这台机器上真正可用的工具表。快路径派发也要过同一道判据（见 `unavailableToolReason`）。 */
-export function availableToolDefs(config?: (key: any) => any): ToolDef[] {
-  return TOOL_DEFS.filter(def => !unavailableToolReason(def.function.name, config))
-}
-
-/**
- * 判断模型给的键翻成人话。
- *
- * 为什么要这一层：那些键是**英文判据的键名**（`casual_chat` / `give_commitment`），
- * 原样交给助手，它就会照着念给用户听。映射不上就退回原键——如实展示，不硬编一个。
- */
-const INTENT_LABELS: Record<string, string> = {
-  confirm_you_care: '想要你一个态度（在试探你还在不在意）',
-  vent_anger: '在发火，想被听见而不是被解决',
-  request_action: '有事要你办（发东西、付钱、约时间这类）',
-  seek_explanation: '想要个解释',
-  casual_chat: '在闲聊，没有事要你办',
-  close_topic: '在收尾，不想再展开',
-}
-const ACTION_LABELS: Record<string, string> = {
-  check_history: '先翻一下更早的聊天记录再说',
-  apologize: '具体地认错',
-  give_commitment: '给一个做得到的时间或交付',
-  explain: '说明经过，不辩解',
-  acknowledge: '表示收到了，先不承诺什么',
-  say_less: '少说',
-  make_plan: '一起定个时间',
-}
-const NEED_LABELS: Record<string, string> = {
-  apology: '一个道歉', action: '实际的动作', explanation: '解释', care: '被在意',
-  nothing: '什么都不用',
-}
-
-function zhLabel(map: Record<string, string>, key: unknown): string {
-  const text = String(key ?? '')
-  return map[text] || text || '说不准'
-}
-
-function riskLabel(score: unknown): string {
-  const value = Number(score ?? 0)
-  if (value >= 8) return '很危险'
-  if (value >= 6) return '偏危险'
-  if (value >= 3) return '留神'
-  return '安全'
-}
-
-/**
- * 外部机器（MCP）调用到"会把用户数据送出去"的工具时，**统一只给预览**的那段文案。
- *
- * 四个出境工具（draft_reply / who_owes_reply / search_chats / search_semantic）共用这一份形状，
- * 各自把"要发什么、发给谁"填进 `what`。预览阶段一律不出境：能用脚本自己的 `--dry-run`
- * 报出具体数字的就报数字（draft_reply、who_owes_reply），报不出的就按入参说清
- * （search_chats 的 --dry-run 打的是纯文本、不认 --json；semantic_search 根本没有 --dry-run）。
- */
-function confirmPreview(what: string): string {
-  return [
-    '还没执行——这只是一次**预览**（没有把任何内容发出去）。',
-    what,
-    '用户明确同意之后再带 `confirm: true` 调一次，才会真的执行。',
-  ].join(String.fromCharCode(10))
-}
-
-export async function executeTool(name: string, args: Record<string, any>, ctx: ToolContext): Promise<string> {
-  try {
-    switch (name) {
-      case 'list_sessions': {
-        await ensureDb()
-        const limit = boundedToolInteger(args.limit, 15, 30)
-        const sessions = await chatService.listSessions(undefined, limit)
-        if (!sessions.length) return '(未查到会话, 数据库可能未连接)'
-        return sessions.map(s =>
-          `· ${s.displayName || s.username}: ${(s.summary || '').replace(/\n/g, ' ').slice(0, 30)}`).join('\n')
-      }
-      case 'get_messages': {
-        const contact = String(args.contact || '')
-        if (!contact) return '(缺少 contact 参数)'
-        const limit = boundedToolInteger(args.limit, 20, 50)
-        // 时间窗：不给就是"最近 N 条"（老行为一个字没改）。给了就用范围读——
-        // **这正是"上周三他说了什么"以前够不着的原因**：只按条数取，越久远的日子越取不到，
-        // 模型要么说查不到，要么把最近的消息当成那天的。
-        let from: number | undefined
-        let to: number | undefined
-        try {
-          from = resolveSince(args.since)
-          to = resolveUntil(args.until)
-        } catch {
-          return '(时间看不懂：since/until 可以写 2026-09-16 或 3d / 2w / 12h；收到的是'
-            + ` since=${JSON.stringify(args.since)} until=${JSON.stringify(args.until)})`
-        }
-        const windowed = from !== undefined || to !== undefined
-        const windowLabel = windowed
-          ? `${from ? new Date(from * 1000).toLocaleDateString('zh-CN') : '最早'}`
-            + ` 至 ${to ? new Date(to * 1000).toLocaleDateString('zh-CN') : '现在'}`
-          : ''
-        const talker = await resolveTalker(contact)
-        const msgs = windowed
-          ? await chatService.getMessagesInRange(talker, limit, from, to)
-          : await chatService.getMessages(talker, limit)
-        if (!msgs.length) {
-          return windowed
-            ? `(${windowLabel} 这段时间里没有「${contact}」的消息)`
-            : `(没找到「${contact}」的消息)`
-        }
-        // 图片消息带一个句柄：`[图片 #1234]` 里的 1234 就是 `look_at_image` 的 `image` 参数。
-        // strict 模式下图片不允许出境，那时不带句柄——不摆出一个工具必定会拒绝的东西。
-        const canLook = privacyGate.mode() !== 'strict'
-        const rendered = msgs.map(m => {
-          // 非文本消息优先用 `parsedContent`：它是读取器给的**显示形态**（`[图片]`、
-          // `[文件] Base.csv`、`某人 撤回了一条消息`…），而 `content` 对这类消息可能是
-          // 原始 XML（含 md5 与 cdn 链接）——那是给机器看的，不该塞进模型上下文。
-          const raw = m.localType === 1
-            ? (m.content || m.parsedContent || '')
-            : (m.parsedContent || m.content || '')
-          // 每条 160 字。此前是 80，引用消息（`[引用] 回复 ｜ 引：原文`）在 80 字里
-          // 引文只剩七八个字，等于白带；长文本消息也被从中间切掉。上限仍是有界的：
-          // limit 最多 50 条 × 约 180 字 ≈ 9k 字符。截断留省略号——切了却看起来像
-          // 说完了，模型会把半句当整句。
-          const flat = raw.replace(/\n/g, ' ')
-          const body = canLook && m.localType === 3
-            ? `[图片 #${m.localId}]`
-            : privacyGate.maskMessageBody(clipWithMarker(flat, MSG_BODY_CHARS),
-                                          { isText: m.localType === 1 })
-          // 这一行原来用 `senderUsername`（**wxid 原列**），等于把账号标识交给云端模型。
-          // 曾经以为"改成「对方」就分不清群聊里谁说的，是个真损失"——实测之后不成立：
-          // `senderDisplay` 本来就有名字（见 `speakerLabel`），换成它两边都占，
-          // 名字对模型还比 wxid 有用。自己发的仍是「用户」（这是对人说"你发了什么"，
-          // 与转录里的「我」是两种口吻，各自有测试钉着）。
-          return `[${fmtTime(m.createTime)}] ${m.isSend ? '用户' : speakerLabel(m)}: ${body}`
-        }).join('\n')
-        // 有时间窗时先说清窗口：模型据此判断"这些是不是那天的"，也免得它把窗口内的最后
-        // 一条当成"最新的"。
-        return windowed ? `（${windowLabel}，共 ${msgs.length} 条）\n${rendered}` : rendered
-      }
-      case 'look_at_image': {
-        const contact = String(args.contact || '')
-        // 句柄在 get_messages 里长这样：`[图片 #1234]`。允许带不带 `#` 都接受——模型从
-        // 上下文里抄一个编号过来，"抄得像不像"不该决定它能不能看图。
-        const image = String(args.image ?? '').replace(/^#/, '').trim()
-        if (!contact || !image) return '(缺少 contact 或 image 参数)'
-        if (!/^\d+$/.test(image)) {
-          return `(image 要填 get_messages 里 [图片 #N] 的编号，收到的是「${image.slice(0, 20)}」)`
-        }
-        // 第一层门：strict 模式（第三方聊天正文不出境）下图片也不出去。第二层在
-        // `toApiMessages` 里——"工具肯给"与"这道门肯放"是两件事。
-        if (privacyGate.mode() === 'strict' && !privacyGate.isLocalInference()) {
-          return '(当前隐私模式是 strict：聊天图片不发出本机，用不了这个工具。'
-            + '要让我看图，得把 assistantPrivacy 改成 balanced)'
-        }
-        const budget = ctx.pendingImages ?? []
-        if (budget.length >= MAX_IMAGES_PER_TURN) {
-          return `(这一轮已经看过 ${MAX_IMAGES_PER_TURN} 张图了，先把已经看到的说完，别再取)`
-        }
-        const talker = await resolveTalker(contact)
-        // 90 秒。建媒体索引是这条路唯一的成本，且随会话大小走：实测单聊 ~1 秒、
-        // 一个 3 万条消息的大群 18.9 秒（而那个群本机只有缩略图）。取到的图会落在
-        // `output/.cache/read-image/`，同一张再看是 0.1 秒。超时是必要的兜底——助手是
-        // **串行**处理消息的，一次卡住会挡住后面所有人的话，所以宁可说"取图失败"。
-        const r = await runPythonJson<any>('read_image.py',
-          ['--talker', talker, '--local-id', image, '--json'], { timeoutMs: 90_000 })
-        if (!r.ok) return fail('取图失败', r)
-        if (!r.data?.b64) {
-          // 文字说明而不是空：本机没有这张图的副本（缓存清过、或只有缩略图）是常态
-          return `(没取到 #${image} 的图片：${r.data?.reason || '本机没有这张图的副本'})`
-        }
-        // 拿到图才建数组：`pendingImages` 为 undefined 与"空数组"在下游是同一个意思，
-        // 但只有前者能一眼看出"这一轮没图"。
-        ;(ctx.pendingImages ??= []).push({
-          b64: r.data.b64, mime: r.data.mime || 'image/jpeg', localId: Number(image) })
-        const size = r.data.width && r.data.height ? `${r.data.width}×${r.data.height}` : '尺寸未知'
-        return `(已附上图片 #${image}（${size}）。你能看到它了，直接据此回答。)`
-      }
-      case 'search_favorites': {
-        await ensureDb()
-        // 不给关键词就是"最近收藏了什么"——这一问在聊天里很自然，没理由逼调用方编一个词
-        const keyword = String(args.keyword || '')
-        const limit = boundedToolInteger(args.limit, keyword ? 8 : 15, keyword ? 15 : 30)
-        const r = keyword ? await chatService.getFavorites({ keyword, limit })
-          : await chatService.getFavorites({ limit })
-        if (!r.success || !r.favorites?.length) {
-          if (r.error) return `(查询失败: ${r.error})`
-          return keyword ? `(收藏中未搜到「${keyword}」)` : '(收藏是空的，或收藏库还没连上)'
-        }
-        return `共${r.total}条, 前${r.favorites.length}条:\n` +
-          r.favorites.map(f => {
-            const desc = (f.desc || '').replace(/\s+/g, ' ').slice(0, 60)
-            return `· ${f.title || '(无标题)'} (${f.source_name || '未知来源'})${desc ? ` — ${desc}` : ''}`
-          }).join('\n')
-      }
-      case 'read_favorite': {
-        await ensureDb()
-        const keyword = String(args.keyword || '')
-        if (!keyword) return '(缺少 keyword 参数)'
-        const maxChars = boundedToolInteger(args.max_chars, 3000, 6000, 'max_chars')
-        const r = await chatService.getFavorites({ keyword, limit: 5 })
-        if (!r.success || !r.favorites?.length) {
-          return `(收藏中未找到「${keyword}」)`
-        }
-        const art = r.favorites.find(f => f.link) || r.favorites[0]
-        if (!art.link) {
-          const txt = (art.desc || art.content || '').trim()
-          return txt ? `「${art.title || '无标题'}」内容:\n${txt.slice(0, maxChars)}` : `(「${art.title}」没有可读的链接和内容)`
-        }
-        if (!isSafeUrl(art.link)) return `(链接不安全, 拒绝抓取: ${art.link.slice(0, 60)})`
-        // 微信内置浏览器 UA + Referer 绕 WAF (与 biz_daily.py 同策略)
-        let html = ''
-        let status = 0
-        for (let attempt = 0; attempt < 2; attempt++) {
-          try {
-            const res = await fetch(art.link, {
-              headers: {
-                'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.38(0x18002633) NetType/WIFI Language/zh_CN',
-                'Referer': 'https://mp.weixin.qq.com/',
-                'Accept': 'text/html,application/xhtml+xml',
-                'Accept-Language': 'zh-CN,zh;q=0.9',
-              },
-              signal: AbortSignal.timeout(20_000),
-            })
-            status = res.status
-            html = (await res.text()).slice(0, 500_000)
-            // 正文验证: 必须含 js_content (否则是验证页, 重试)
-            if (res.ok && html.includes('js_content')) break
-          } catch { /* 超时/网络错误 → 重试 */ }
-        }
-        if (!html) return `(抓取失败 HTTP ${status})`
-        // 路径1: 正常页面 js_content; 路径2: WAF 挑战页 content_noencode 兜底
-        let text = html.includes('js_content') ? extractText(html) : ''
-        if (!text || (text.match(/[\u4e00-\u9fff]/g) || []).length < 50) {
-          const decoded = extractFromChallengePage(html)
-          if (decoded) text = stripTags(decoded)
-        }
-        text = text.slice(0, maxChars)
-        if (html.includes('已被发布者删除')) return `(「${art.title}」已被发布者删除)`
-        if (!text.trim() || (text.match(/[\u4e00-\u9fff]/g) || []).length < 20) {
-          return `(「${art.title}」正文提取失败, 可能是纯图片文章或已被删除)`
-        }
-        return `「${art.title || '无标题'}」(${art.source_name || '未知来源'}) 正文:\n${text}`
-      }
-      case 'get_daily_report': {
-        const dates = existsSync(BIZ_DAILY_DIR)
-          ? readdirSync(BIZ_DAILY_DIR).filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort().reverse()
-          : []
-        if (!dates.length) return '(还没有日报数据, 先运行 biz_daily 生成)'
-        const date = String(args.date || dates[0])
-        const articlesFile = join(BIZ_DAILY_DIR, date, '.articles.json')
-        if (!existsSync(articlesFile)) return `(${date} 没有日报。可用日期: ${dates.slice(0, 5).join(', ')})`
-        const raw = JSON.parse(readFileSync(articlesFile, 'utf8'))
-        const all = Array.isArray(raw) ? raw : (raw.articles || Object.values(raw))
-        let list = all as any[]
-        if (args.topic) list = list.filter(a => a.topic === args.topic)
-        if (args.keyword) {
-          const kw = String(args.keyword).toLowerCase()
-          list = list.filter(a =>
-            (a.title || '').toLowerCase().includes(kw) || (a.summary || '').toLowerCase().includes(kw))
-        }
-        const limit = boundedToolInteger(args.limit, 15, 30)
-        if (!list.length) return `(${date} 日报共 ${all.length} 篇, 过滤后无匹配)`
-        const byTopic: Record<string, number> = {}
-        for (const a of all) byTopic[a.topic] = (byTopic[a.topic] || 0) + 1
-        const topicStat = Object.entries(byTopic).map(([t, n]) => `${t}${n}篇`).join(' ')
-        return `${date} 日报共 ${all.length} 篇 (${topicStat}), 匹配 ${list.length} 篇:\n` +
-          list.slice(0, limit).map(a => {
-            const summary = (a.summary || '').replace(/\s+/g, ' ').slice(0, 80)
-            return `· [${a.topic}] ${a.title} (${a.source})${summary ? `\n  ${summary}` : ''}`
-          }).join('\n')
-      }
-      case 'get_sns': {
-        await ensureDb()
-        if (String(args.mode || 'timeline') === 'users') {
-          // 谁常发朋友圈：本地把最近的时间线按发帖人聚合。**不新增出境**——数据本来就在这一条工具里。
-          const r = await chatService.getSnsTimeline({ limit: 200 })
-          if (!r.success || !r.timeline?.length) {
-            return r.error ? `(朋友圈查询失败: ${r.error})` : '(朋友圈暂无缓存数据)'
-          }
-          const byAuthor = new Map<string, number>()
-          for (const post of r.timeline) {
-            const who = String(post.nickname || post.username || '未知')
-            byAuthor.set(who, (byAuthor.get(who) ?? 0) + 1)
-          }
-          const ranked = [...byAuthor.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)
-          const nl = String.fromCharCode(10)
-          return `最近 ${r.timeline.length} 条朋友圈里，发得最多的：`
-            + ranked.map(([who, n]) => `${nl}· ${who}：${n} 条`).join('')
-        }
-        if (String(args.mode || 'timeline') === 'stats') {
-          const r = await chatService.getSnsExportStats()
-          if (!r.success) return `(朋友圈统计失败: ${r.error})`
-          const d = r.data!
-          return `朋友圈统计: 总动态 ${d.totalPosts} 条, 发布过动态的好友 ${d.totalFriends} 人${d.myPosts != null ? `, 用户自己发过 ${d.myPosts} 条` : ''}`
-        }
-        const limit = boundedToolInteger(args.limit, 10, 20)
-        const r = await chatService.getSnsTimeline({ limit })
-        if (!r.success || !r.timeline?.length) return r.error ? `(朋友圈查询失败: ${r.error})` : '(朋友圈暂无缓存数据)'
-        return `最新 ${r.timeline.length} 条朋友圈:\n` + r.timeline.slice(0, limit).map((p: any) => {
-          const content = (p.content || '').replace(/\s+/g, ' ').slice(0, 100)
-          return `· [${fmtTime(p.create_time)}] ${p.nickname || p.username}: ${content}${p.media_count ? ` [${p.media_count}图]` : ''}`
-        }).join('\n')
-      }
-      case 'get_weread': {
-        const { wereadService } = await import('./wereadService.js')
-        const mode = String(args.mode || 'shelf')
-        const apiKey = (await import('./configService.js')).configService.get('wereadApiKey')
-        if (!apiKey) return '(微信读书未配置: config set wereadApiKey <key>)'
-        try {
-          if (mode === 'notebooks') {
-            const r = await wereadService.notebooks(20)
-            if (!r.ok || !r.data?.books?.length) return `(暂无读书笔记: ${r.error || ''})`
-            // `/user/notebooks` 把书名与作者**嵌在 `book` 里**，条目顶层没有这两个字段 ——
-            // 实测（2026-09-28）：直接读 `b.title` 会得到 `undefined`，而输出照样成立，
-            // 只是每本书都没名字。顶层那两个是兜底，网关换版本时用得上。
-            const titleOf = (b: any) => b?.book?.title || b?.title || '(未给书名)'
-            const authorOf = (b: any) => b?.book?.author || b?.author || ''
-            return `有笔记的书 ${r.data.books.length} 本:\n` +
-              r.data.books.slice(0, 15).map((b: any) =>
-                `· ${titleOf(b)} (${authorOf(b)}) — ${b.noteCount || 0} 条笔记`).join('\n')
-          }
-          if (mode === 'search') {
-            const kw = String(args.keyword || '')
-            if (!kw) return '(search 模式需要 keyword)'
-            const r = await wereadService.search(kw, 8)
-            if (!r.ok || !r.data?.books?.length) return `(没搜到「${kw}」: ${r.error || ''})`
-            return `搜索「${kw}」结果:\n` +
-              r.data.books.map((b: any) => `· ${b.title} (${b.author})`).join('\n')
-          }
-          const r = await wereadService.shelf()
-          if (!r.ok || !r.data?.books?.length) return `(书架为空或读取失败: ${r.error || ''})`
-          const books = r.data.books
-          const reading = books.filter((b: any) => b.progress && b.progress > 0 && b.progress < 100)
-          return `书架共 ${books.length} 本, 在读 ${reading.length} 本:\n` +
-            (reading.length ? reading.slice(0, 10).map((b: any) =>
-              `· ${b.title} (${b.author}) — 已读 ${b.progress || 0}%`).join('\n') : books.slice(0, 10).map((b: any) => `· ${b.title}`).join('\n'))
-        } catch {
-          return '(微信读书接口失败，请检查网络和本地配置)'
-        }
-      }
-      case 'get_todos': {
-        const status = String(args.status || 'pending')
-        // 走 pythonBridge（唯一的脚本调用入口）：失败原因分三类报出来，不解析人类可读文本。
-        // `--meta` 是为了分清"没有待办"与"从没提取过"——两者在 `--json` 下都是空数组，
-        // 而把后者说成前者，用户会以为自己真的没事要做。MCP 侧一直分得开（见 mcp_bridge.py），
-        // 这条工具此前没分。`--meta` 是新增开关，老形状（裸数组）原样保留给别的调用方。
-        const result = await runPythonJson<any>('extract_todos.py', ['list', '--status', status, '--json', '--meta'])
-        if (!result.ok) return fail('待办查询失败', result)
-        // 兼容老形状：万一是没有 --meta 的实现，拿到的是数组，就退回原来的说法。
-        const meta = result.data && !Array.isArray(result.data) ? result.data : null
-        const todos: any[] = meta ? (Array.isArray(meta.items) ? meta.items : []) : (Array.isArray(result.data) ? result.data : [])
-        if (!todos.length) {
-          if (meta && meta.extracted === false) {
-            return '(还没提取过待办——待办是从聊天记录里提取的，要用 `weflow-cli todos extract --days 7 --yes` 先跑一次；'
-              + '在那之前这份清单一直是空的，不代表你没有事要做)'
-          }
-          return `(没有${status === 'done' ? '已完成' : '待办'}任务)`
-        }
-        return `${status === 'done' ? '已完成' : '待办'} ${todos.length} 项:\n` +
-          todos.slice(0, 15).map((t: any) =>
-            `· [${t.urgency || '中'}] ${t.task || t.content || t.text || t.title}${t.deadline && t.deadline !== '未提及' ? ` (截止 ${t.deadline})` : ''}`).join('\n')
-      }
-      case 'search_chats': {
-        // 跨会话检索：本机 message_fts 索引 + 判断模型挑查询词（**只发候选词与问题，不发聊天内容**）
-        const question = String(args.question || '').trim()
-        if (!question) return '(缺少 question 参数)'
-        const perCard = boundedToolInteger(args.per_card, 3, 10, 'per_card')
-        // 外部机器默认只给预览，**按入参说清**。这里要说清的恰好是最要紧的那件事：
-        // 这条路上出去的是"你的问题 + 从聊天里提取的候选词"，**不含消息正文**（排序在本地做）。
-        if (ctx.requiresConfirm && args.confirm !== true) {
-          return confirmPreview(`会把你的问题「${question.slice(0, 40)}」与从聊天里提取的候选词`
-            + `（最多 ${perCard} 个会话各若干词，**不含消息正文**）发给判断模型 Jev，`
-            + '让它挑出你真正在找的词；排序在本地做。')
-        }
-        const result = await runPythonJson<any>('route_cards.py',
-          ['ask', question, '--yes', '--json', '--per-card', String(perCard)], { timeoutMs: 90_000 })
-        if (!result.ok) return fail('会话检索失败', result)
-
-        const ranked = Array.isArray(result.data?.ranked) ? result.data.ranked : []
-        if (!ranked.length) {
-          return `(没有会话字面命中「${question}」——检索只匹配字面词，换几个词再试)`
-        }
-        const lines = [`命中 ${ranked.length} 个会话（查询词：${(result.data.terms || []).join('、')}）：`]
-        for (const card of ranked.slice(0, 6)) {
-          lines.push(`· #${card.id} [${card.kind}] ${card.label}（该会话 ${card.messages} 条消息，最后活动 ${card.lastDaysAgo} 天前）`)
-          const rows = result.data?.messages?.[String(card.id)] || []
-          for (const row of rows.slice(0, perCard)) {
-            // 第三方聊天正文与 get_messages **同一条纪律**：出境前按隐私档位处理
-            const body = privacyGate.maskMessageBody(String(row?.text || '').replace(/\s+/g, ' ').slice(0, 60))
-            lines.push(`    ${body}`)
-          }
-        }
-        return lines.join('\n')
-      }
-      case 'who_owes_reply': {
-        // 谁在等我回话：逐会话问一次判断模型（较慢）。**不给正文**——真要看他写了什么，
-        // 用 get_messages 单独查，那条路有完整的隐私处理。
-        const days = boundedToolInteger(args.days, 14, 60, 'days')
-        // 外部机器（MCP）默认只给预览：这个工具**每个会话一次判断调用**，每一次都带着那段聊天正文，
-        // 是这条路上最贵也最"出境"的一个。预览走脚本自己的 --dry-run（只读本地、零出境）。
-        if (ctx.requiresConfirm && args.confirm !== true) {
-          const preview = await runPythonJson<any>('reply_debt.py',
-            ['--days', String(days), '--dry-run', '--json'], { timeoutMs: 60_000 })
-          if (!preview.ok || !preview.data?.success) {
-            return `(预览失败：${String(preview.data?.error || preview.error || '未知').slice(0, 120)})`
-          }
-          const p = preview.data
-          return confirmPreview(`会把最近 ${days} 天里 ${p.conversations} 个有动静的会话、`
-            + `约 ${p.stateChars} 字符聊天正文，**逐个**发给判断模型（api.typesafe.ai），每会话一次请求。`)
-        }
-        const result = await runPythonJson<any>('reply_debt.py', ['--days', String(days), '--json'],
-          { timeoutMs: 180_000 })
-        if (!result.ok) return fail('欠账查询失败', result)
-
-        const debts = Array.isArray(result.data?.debts) ? result.data.debts : []
-        if (!debts.length) return `(最近 ${days} 天没有明显在等你回话的会话)`
-        const lines = [`在等你回话的 ${debts.length} 个会话（最近 ${days} 天）：`]
-        for (const row of debts.slice(0, 8)) {
-          const prob = Number(row.waiting ?? 0)
-          const urgency = row.urgencyScore === null || row.urgencyScore === undefined ? '' : ` · 紧急度 ${row.urgencyScore}`
-          lines.push(`· ${row.name}（等了 ${row.days} 天 · 概率 ${prob.toFixed(2)}${urgency}${row.kind ? ' · ' + row.kind : ''}）`)
-        }
-        lines.push('（想看某人具体说了什么，用 get_messages 单独查；这里只报谁在等。）')
-        return lines.join('\n')
-      }
-      case 'draft_reply': {
-        // 起草：判断（Jev）→ 起草（DeepSeek）→ 排序（Jev）。**只产出文本，绝不发送**——
-        // 仓库里"发送"本来就不可达（TOOL_DEFS 没有任何 send 类工具），这里也不新增。
-        const contact = String(args.contact || '')
-        if (!contact) return '(缺少 contact 参数)'
-        const count = boundedToolInteger(args.count, 3, 5, 'count')
-        // strict 下**直接拒绝**，而不是把遮成"内容 N 字"的正文拿去起草——那会得到一段
-        // 基于空白的、看起来正常的回复，比拒绝更糟（同 `look_at_image` 的处置）。
-        //
-        // 这里**不看 `isLocalInference()`**，与 `look_at_image` 刻意不同：那张图确实送到
-        // 本机模型，所以"本机推理"在那里是成立的旁路；而起草出境的是**脚本自己的**两条远程
-        // 调用（`jev_client` 走 HTTP、`_utils.call_deepseek` 写死 DeepSeek），跟 `aiEngine`
-        // 配成什么毫无关系。照抄那个旁路＝用"我配了本地模型"当理由，把正文发到远端去。
-        // 这条是实测出来的：aiEngine=ollama + strict 下，原实现真的把对话交给了脚本。
-        if (privacyGate.mode() === 'strict') {
-          return '(当前隐私模式是 strict：聊天正文不出境，而起草必须把正文发给远端模型'
-            + '（判断一步、生成一步），这一步用本机推理也绕不开。'
-            + '在电脑上 `weflow-cli config set assistantPrivacy balanced`，或用本机命令 '
-            + '`weflow-cli draft <会话>`。)'
-        }
-        const talker = await resolveTalker(contact)
-        const msgs = await chatService.getMessages(talker, TRANSCRIPT_MESSAGES)
-        if (!msgs.length) return `(没找到「${contact}」的消息)`
-
-        // **外部机器（MCP）默认只给预览，不做出境。** 与 CLI 的 `--dry-run` / `--yes` 同一套纪律：
-        // 预览只读本地库、报清要发多少字符给哪两个模型，零出境。
-        // 面板/微信那条路（`requiresConfirm` 不置位）不受影响——它那边的边界是白名单 + 用户
-        // 在一个只有自己看得见的会话里显式开口问。
-        if (ctx.requiresConfirm && args.confirm !== true) {
-          const preview = await runPythonJson<any>('draft_reply.py',
-            ['--talker', talker, '--dry-run', '--json', '--count', String(count)],
-            { timeoutMs: 60_000 })
-          if (!preview.ok || !preview.data?.success) {
-            return `(起草预览失败：${String(preview.data?.error || preview.error || '未知').slice(0, 120)})`
-          }
-          const d = preview.data
-          return confirmPreview('会把「' + d.name + '」最近的 ' + d.messages + ' 条消息、共 '
-            + d.stateChars + ' 字符，发给 ' + (d.models?.judge || '判断模型') + ' 与 '
-            + (d.models?.draft || '生成模型') + '（' + (d.calls || '3 次调用') + '），产出 '
-            + d.count + ' 条候选。'
-            // 前提说明也在出境的那一段里（它会进两段提示词），所以预览要把它算进去
-            + (d.lastFromMe ? '另外会附一句「最后一条是我自己发的」的前提说明。' : ''))
-        }
-
-        // 逐条遮罩**再**交给脚本：Python 侧没有任何脱敏实现（全仓只有两处无关的位掩码），
-        // 而脱敏这一层在 TS。**不在 Python 里再写一份**——同一件事两处实现早晚有一处会漏。
-        //
-        // 说明白：上面的门**现在**已经把 strict 全挡了，所以这里的 `maskMessageBody`
-        // 在当下打不到（balanced/open 不改正文）。留着它是因为它守的是另一条不变式：
-        // "交给脚本的正文一定先过一道遮罩"，谁将来松开了上面那道门，这道还在。
-        const transcript = msgs.slice().reverse().map(m => transcriptLine(m))
-        const result = await runPythonJson<any>('draft_reply.py',
-          ['--stdin', '--yes', '--json', '--count', String(count)],
-          // `lastFromMe`：`transcript` 是 `msgs` **反过来**渲染的，所以最后一条 = `msgs[0]`。
-          // 用结构化字段 `isSend`，不去解析那行文本（群聊里别人的标签是人名，不是「对方」）。
-          // 这段是说给脚本听的**前提**：最后一条是我发的时，"回答对方最后一句"这件事根本不存在。
-          { stdin: JSON.stringify({ name: contact, lines: transcript, lastFromMe: !!msgs[0]?.isSend }),
-            timeoutMs: 240_000 })
-        if (!result.ok) return fail('起草失败', result)
-
-        const data = result.data ?? {}
-        if (!data.success) return `(起草没跑通: ${String(data.error || '未知').slice(0, 120)})`
-        const picked = Array.isArray(data.drafts) ? data.drafts : []
-        // 脚本给的前提说明（仅当最后一条是我发的）。**用户也要看见**：否则候选看起来像在回
-        // 一句根本不存在的话。三条出口（降级/被闸门拦下/正常）都要带上它。
-        const premise = typeof data.premise === 'string' ? data.premise.trim() : ''
-        // **降级那次（Jev 没调通）必须说清两件事**：这次没有判断，以及那道闸门没生效。
-        // 闸门（涉钱/高风险不给草稿）正是靠判断结果才存在的——不标出来，降级看起来就跟
-        // "判断过了"一模一样。**不以 `(` 开头**：那个前缀在本仓库表示"工具没产出内容"。
-        if (data.judged === false) {
-          if (!picked.length) return `(起草没给出候选：${String(data.judgeNote || '判断与生成都没跑通').slice(0, 120)})`
-          const lines = [...(premise ? [premise, ''] : []),
-                         `这次**没有判断**——${String(data.judgeNote || '判断那一步没调通')}。`,
-                         `所以"涉钱/风险高就不给草稿"那道闸门**没生效**，下面 ${picked.length} 条是生成模型`
-                         + `按上下文给的，你自己看一眼：`, '']
-          picked.forEach((draft: any, index: number) => { lines.push(`${index + 1}. ${draft.text}`) })
-          lines.push('')
-          lines.push('（这些只是文本，没有发送任何东西——回不回、怎么回由你决定。）')
-          return lines.join('\n')
-        }
-        const judgment = data.judgment ?? {}
-        const why = `对方${zhLabel(INTENT_LABELS, judgment.intent)}`
-          + `；建议${zhLabel(ACTION_LABELS, judgment.action)}`
-          + `；风险 ${Number(judgment.risk ?? 0).toFixed(1)}/9 ${riskLabel(judgment.risk)}`
-        // 被闸门拦下：**不是失败**，是这条最该给的回答。所以不以 `(` 起头
-        // （那个前缀在本仓库里表示"工具没产出内容"，见 `producedContent`）。
-        if (data.gate === 'refused') {
-          return [...(premise ? [premise, ''] : []),
-                  '不起草。', String(data.reason || ''), '',
-                  '建议先：', ...(data.advice ?? []).map((line: string) => `· ${line}`),
-                  '', `（判断：${why}。这些只是文本，没有发送任何东西。）`].join('\n')
-        }
-        const drafts: any[] = Array.isArray(data.drafts) ? data.drafts : []
-        if (!drafts.length) return '(起草没给出候选)'
-        const lines = [...(premise ? [premise, ''] : []),
-                       `建议这样回（${drafts.length} 条，第一条是判断最合适的）：`, '']
-        drafts.forEach((draft, index) => { lines.push(`${index + 1}. ${draft.text}`) })
-        lines.push('')
-        lines.push(`（判断：${why}。这些只是文本，没有发送任何东西——回不回、怎么回由你决定。）`)
-        return lines.join('\n')
-      }
-      case 'search_semantic': {
-        // 语义/同义检索（向量相似度 + 决策模型重排）。字面词搜不到时用这条。
-        // **出境说明**：查询词要发阿里云百炼做嵌入，候选片段要发判断模型重排——
-        // 两者都在仓库既有的云端路径上（不是新类别），但这里如实写出来。
-        const query = String(args.query || '').trim()
-        if (!query) return '(缺少 query 参数)'
-        const topK = boundedToolInteger(args.top_k, 8, 20, 'top_k')
-        // 外部机器默认只给预览（`semantic_search.py` 没有 --dry-run，按入参说清）
-        if (ctx.requiresConfirm && args.confirm !== true) {
-          return confirmPreview(`会把查询词「${query.slice(0, 40)}」发给阿里云百炼做嵌入，`
-            + `再把前 ${topK} 条命中的本地片段（可能含聊天或文章原文）发给判断模型 Jev 重排。`)
-        }
-        // **查询词走环境变量、不进 argv**：仓库写进测试的隐私纪律（进程列表里看不到正文）
-        const result = await runPythonJson<any[]>('semantic_search.py',
-          ['search', '--top-k', String(topK)],
-          { env: { WEFLOW_SEARCH_QUERY: query }, timeoutMs: 90_000 })
-        if (!result.ok) return fail('语义检索失败（索引可能还没建：weflow-cli search-index）', result)
-
-        const rows = Array.isArray(result.data) ? result.data : []
-        if (!rows.length) return `(语义检索没有结果「${query}」)`
-        return `语义检索「${query}」前 ${rows.length} 条：` + String.fromCharCode(10) + rows.map((row: any) => {
-          const title = String(row.title || row.source || '(无标题)').slice(0, 40)
-          const score = typeof row.score === 'number' ? `（${row.score.toFixed(2)}）` : ''
-          const text = privacyGate.maskMessageBody(
-            String(row.text || row.content || '').replace(/\s+/g, ' ').slice(0, 80))
-          const nl = String.fromCharCode(10)
-          return `· ${title}${score}${text ? nl + '    ' + text : ''}`
-        }).join(String.fromCharCode(10))
-      }
-      case 'export_chat': {
-        // **写操作**，边界写死：只往 output/exports/ 下**新建**目录（名字带时间戳），绝不覆盖；
-        // 路径由这里拼，模型给不了任意路径。用户是在对话里明确要求的，这就是那次确认。
-        const contact = String(args.contact || '').trim()
-        if (!contact) return '(缺少 contact 参数)'
-        const limit = boundedToolInteger(args.limit, 500, 5000, 'limit')
-        const format = String(args.format || 'html').toLowerCase()
-        if (!['html', 'txt', 'json', 'excel'].includes(format)) {
-          return `(参数错误: format 只能是 html/txt/json/excel，收到 ${format.slice(0, 12)})`
-        }
-        const talker = await resolveTalker(contact)
-
-        const safeName = contact.replace(/[\/:*?"<>|]/g, '_').slice(0, 20) || 'chat'
-        const stamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 12)
-        // 目录名到秒，同一秒里导两次会撞进同一个目录——那就不是"绝不覆盖"了。撞了就往后加序号。
-        // 导出根目录可用环境变量改（测试用临时目录；也方便自定义）。默认在仓库的 output/exports 下。
-        const exportRoot = process.env.WEFLOW_ASSISTANT_EXPORT_ROOT || join(PKG_ROOT, 'output', 'exports')
-        let outDir = join(exportRoot, `${safeName}-${stamp}`)
-        for (let n = 2; existsSync(outDir) && n < 100; n++) {
-          outDir = join(exportRoot, `${safeName}-${stamp}-${n}`)
-        }
-        const result = format === 'txt' ? await exportService.exportTxt(talker, outDir, limit)
-          : format === 'json' ? await exportService.exportJson(talker, outDir, limit)
-            : format === 'excel' ? await exportService.exportExcel(talker, outDir, limit)
-              : await exportService.exportHtml(talker, outDir, limit, '', undefined, undefined, true)
-        if (!result.success) return `(导出失败: ${String(result.error || '未知').slice(0, 100)})`
-        const suffix = format === 'html' ? '，含图片' : ''
-        // 报**真的写到了哪**：`outDir` 才是（撞名之后会带 `-2`），而事前拼的 `safeName-stamp`
-        // 两次导出会报成同一个名字——实测第二次明明是 `…-2`，消息里却是基础名（2026-09-23 验收）。
-        // 根目录是默认值时按仓库相对路径报（用户照着找得到）；自定义根时只报目录名——
-        // **不把绝对路径发进聊天**，那是本机路径，没必要出境。
-        const shown = exportRoot === join(PKG_ROOT, 'output', 'exports')
-          ? `output/exports/${basename(outDir)}`
-          : basename(outDir)
-        return `已导出 ${result.count ?? 0} 条消息到 ${shown}/（${format}${suffix}）`
-      }
-      case 'search_knowledge': {
-        const kw = String(args.keyword || '')
-        if (!kw) return '(缺少 keyword 参数)'
-        const liveDirs = VAULT_WIKI_DIRS.filter(dir => existsSync(dir))
-        if (!liveDirs.length) return '(知识库尚未生成, 先运行 weflow-cli wiki compile)'
-        // **两个目录一起搜**（文章知识库 + 聊天知识库）。分开是用户要求的，但"分开"
-        // 不该变成"搜不到"——只读一个的话，另一半会静默缺席。
-        const entries: Array<{ dir: string; file: string; where: string }> = []
-        let total = 0
-        for (const dir of liveDirs) {
-          // 标注来源，好让模型（和读日志的人）知道这条来自哪个知识库
-          const where = /[\\/]Chat[\\/]/.test(dir) ? '聊天' : '文章'
-          for (const file of readdirSync(dir).filter(f => f.endsWith('.md'))) {
-            entries.push({ dir, file, where })
-            total += 1
-          }
-        }
-        const hits = entries.filter(e => e.file.replace('.md', '').toLowerCase().includes(kw.toLowerCase()))
-        if (!hits.length) {
-          // **只搜正文，不搜「来源」段。** 页面的来源段可能列 300+ 条文章标题（2026-09-27 那批
-          // 改动之后就是这样），拿整个文件做包含判断，会把「某篇来源的**标题**里含这个词」报成
-          // 「**正文**提及」—— 实测 `Grok-4` 命中 4 张页、其中 3 张的正文里根本没有它。
-          // `assistant-eval` 的 `knowledge-fallback-not-body` 钉住这件事。
-          //
-          // 顺带把**那一句**给出去：只给页名的话模型会自己补内容（实测它补出过「Grok-4 是作为
-          // 被测试的模型之一出现的」，那是它从别处知道的，不是这一页里写的）。
-          const contentHits = entries.map(e => {
-            const text = pageBody(readFileSync(join(e.dir, e.file), 'utf8'))
-            const at = text.toLowerCase().indexOf(kw.toLowerCase())
-            if (at === -1) return null
-            const line = text.slice(Math.max(0, at - 80), at + 160)
-              .split('\n').find(l => l.includes(kw)) || ''
-            return { ...e, snippet: line.trim().slice(0, 180) }
-          }).filter((e): e is { dir: string; file: string; where: string; snippet: string } => e !== null)
-            .slice(0, 5)
-          if (!contentHits.length) return `(知识库未收录「${kw}」, 共 ${total} 个概念页)`
-          return '正文提及「' + kw + '」的概念页:' + '\n'
-            + contentHits.map(e => `· ${e.file.replace('.md', '')}（${e.where}）: ${e.snippet}`).join('\n')
-        }
-        const hit = hits[0]
-        const name = hit.file.replace('.md', '')
-        const page = readFileSync(join(hit.dir, hit.file), 'utf8')
-        // **顺带把邻居给出去**（见 `conceptNeighbors`）：一次调用拿到"这个概念 + 连着它的一小块子图"。
-        // 不点明"可以再用本工具查其中任意一个"的话，模型会把它当装饰性文字读过去。
-        const depth = boundedToolInteger(args.depth, 1, 3, 'depth')
-        const { levels, truncated, missing } = conceptSubgraph(name, depth)
-        const out = [`「${name}」概念页（${hit.where}知识库）:`, page.slice(0, 2000)]
-        if (levels.length) {
-          out.push('', depth > 1
-            ? `—— 它周围的概念（${depth} 跳；「←」标出是从哪个概念连过来的）——`
-            : '—— 它连到的概念（可以再用本工具查其中任意一个，或者加 depth 参数一次多看几跳）——')
-          levels.forEach((level, index) => {
-            if (levels.length > 1) out.push(`第 ${index + 1} 跳：`)
-            for (const nb of level) {
-              out.push(depth > 1 ? `· ${nb.name} ← ${nb.via} — ${nb.brief}` : `· ${nb.name} — ${nb.brief}`)
-            }
-          })
-          // 封顶了要**说出来**：默默少给的话，模型会以为这就是全部
-          if (truncated) out.push(`（图太大，只给了前 ${levels.flat().length} 个概念；
-想看某个分支可以单独查它）`)
-        }
-        if (missing) out.push(`（另有 ${missing} 个相关概念尚未建页，查不到）`)
-        return out.join('\n')
-      }
-      case 'get_stats': {
-        await ensureDb()
-        const sessions = await chatService.listSessions(undefined, 1000)
-        const fav = await chatService.getFavorites({ limit: 1 })
-        return `会话数: ${sessions.length}\n收藏总数: ${fav.success ? fav.total : '未知'}`
-      }
-      case 'get_reading_stats': {
-        const days = boundedToolInteger(args.days, 7, 90, 'days')
-        const r = await runPythonJson<any>('daily_stats.py',
-          ['--days', String(days), '--json'], { timeoutMs: 60_000 })
-        if (!r.ok) return fail('读取公众号统计失败', r)
-        const rows: any[] = r.data?.sources ?? []
-        if (!rows.length) return `(最近 ${days} 天没有公众号推送记录)`
-        const period = r.data?.period ?? {}
-        const byPushed = [...rows].sort((a, b) => (b.pushed ?? 0) - (a.pushed ?? 0)).slice(0, 5)
-        const lines = [`最近 ${days} 天（${period.start} 至 ${period.end}）：${rows.length} 个公众号有推送`]
-        lines.push('发得最多：' + byPushed.map(x => `${x.name}(${x.pushed})`).join('、'))
-        const processed = rows.filter(x => (x.processed ?? 0) > 0)
-          .sort((a, b) => (b.processed ?? 0) - (a.processed ?? 0)).slice(0, 5)
-        if (processed.length) {
-          lines.push('日报处理得最多：' + processed.map(x => `${x.name}(${x.processed})`).join('、'))
-        } else {
-          // **直说日报没在跑**：这时"处理数 0"不是"这些号没内容"，而是日报压根没运行。
-          // 把它混成"没读到东西"，用户会去查号，而该查的是日报任务。
-          lines.push(`这 ${days} 天日报没有任何处理记录` + lastDailyNote())
-        }
-        return lines.join('\n')
-      }
-      case 'search_memory': {
-        const hits = ctx.memory.searchFacts(ctx.userId, String(args.keyword || ''))
-        if (!hits.length) return '(长期记忆中无相关内容)'
-        return hits.map(f => `· ${f.content}`).join('\n')
-      }
-      case 'save_memory': {
-        const content = String(args.content || '').trim().slice(0, 60)
-        if (!content) return '(内容为空, 未保存)'
-        const added = ctx.memory.addFact(ctx.userId, content)
-        return added ? '(已存入长期记忆)' : '(与已有记忆重复, 未保存)'
-      }
-      default:
-        return `(未知工具: ${name})`
-    }
-  } catch (error) {
-    if (error instanceof ToolInputError) return `(参数错误: ${error.message})`
-    return '(工具执行失败，请检查本地配置或运行状态)'
-  }
-}
+/**
+ * Agent 工具注册表 (OpenAI function-calling 格式, DeepSeek 兼容)。
+ * 所有工具在本机执行; 结果经 PrivacyGate 脱敏后才进入 LLM 上下文。
+ */
+import { chatService } from './chatService.js'
+import { configService } from './configService.js'
+import { runPythonJson } from './pythonBridge.js'
+import { exportService } from './exportService.js'
+import type { AssistantMemory } from './assistantMemory.js'
+import { frameLocalData } from './assistantMemory.js'
+import { disabledIds, readSkillBody, scanSkills, skillRoots, skillState } from './assistantSkills.js'
+import { privacyGate } from './assistantPrivacy.js'
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { basename, dirname, join } from 'path'
+// 直接调进程的写法已收敛进 pythonBridge：这里不再 import child_process
+import { resolvePackageRoot } from '../utils/packageRoot.js'
+import type { Contact } from '../types.js'
+import { clipWithMarker } from '../utils/text.js'
+import { resolveSince, resolveUntil } from '../utils/dateRange.js'
+import { isAllowedWeChatArticleUrl, safeDate } from '../utils/mcpSecurity.js'
+
+const PKG_ROOT = resolvePackageRoot(import.meta.url)
+/**
+ * 日报目录。**可以用 `WEFLOW_ASSISTANT_BIZ_DAILY_DIR` 指到别处**。
+ *
+ * 为什么加这个注入点：`get_daily_report` 一直是本文件里**唯一从没被执行过的工具分支**，
+ * 原因写在测试文件头上——它读的是模块级常量路径，没有注入点，断言只能写成"没数据/有数据皆可"，
+ * 那种测试看着像覆盖、其实什么也没钉住。同 `WEFLOW_ASSISTANT_EXPORT_ROOT` 的先例（见 `export_chat`）。
+ */
+// 做成函数而不是模块常量：环境变量在**每次调用**时读，测试才能在同一进程里换夹具
+// （同 `export_chat` 的 `WEFLOW_ASSISTANT_EXPORT_ROOT` 做法）。常量只在 import 时求值，
+// 那会让「目录不存在」这类分支永远测不到——写出来的断言就只能是摆设。
+const bizDailyDir = (): string =>
+  process.env.WEFLOW_ASSISTANT_BIZ_DAILY_DIR || join(PKG_ROOT, 'output', 'biz-daily')
+/** 学习回顾目录。同样可注入：否则 `get_review` 的断言只能依赖这台机器上有没有跑过 `review`。 */
+const reviewsDir = (): string =>
+  process.env.WEFLOW_ASSISTANT_REVIEWS_DIR || join(PKG_ROOT, 'output', 'reviews', 'Daily')
+/** 单条聊天消息进上下文的字数上限（见 get_messages：引用消息要放得下正文+被引原文） */
+const MSG_BODY_CHARS = 160
+// 知识页住在哪几个目录。**两个是有意的**：文章知识库与聊天知识库分开（用户 2026-09-27
+// 要求），所以读的一方要把**两个都读**——只读一个，分出去的那一半就静默地搜不到。
+// 与 Python 的 `_utils.CONCEPT_DIRS` 是同一份清单，有测试钉住两者一致（跨语言没法共用常量）。
+/**
+ * 总览索引在哪：**在概念目录的上一层**——`Wiki/Concepts/` 的兄弟是 `Wiki/00-Overview.md`。
+ *
+ * 抽成函数是为了能直接测：这段路径写错过一次（写成 `join(dir, '00-Overview.md')`，于是一直读不到），
+ * 而当时那条测试只能断言「有内容或没有」这种形状——真实机器上有索引、CI 上没有，两条路都绿。
+ */
+export function wikiIndexPath(conceptDir: string): string {
+  return join(conceptDir, '..', '00-Overview.md')
+}
+
+/**
+ * 知识库那两条线的 `Concepts` 目录。**同样可注入**（`WEFLOW_ASSISTANT_VAULT_DIR`），
+ * 与上面 `bizDailyDir` / `reviewsDir` 是同一条理由：评测跑在临时家目录里，包内那个
+ * `output/wechat-vault/` 必然为空，`get_concepts` 就只能测到「还没编译过」那一支——
+ * 要给它写用例，就得能把这个根换掉。（做成函数而不是常量：环境变量要在**每次调用**时读。）
+ */
+const vaultDirs = (): string[] => {
+  const root = process.env.WEFLOW_ASSISTANT_VAULT_DIR || join(PKG_ROOT, 'output', 'wechat-vault')
+  return [join(root, 'Wiki', 'Concepts'), join(root, 'Chat', 'Concepts')]
+}
+
+/**
+ * 线的展示名 —— **TS 侧只此一份**。原来有两处各自从路径里找 `Chat` 这个词猜
+ * （`wiki_health` 与 `get_vault_stats`），改词的那天只会改到一半。
+ *
+ * 与 Python 侧 `_utils.LINE_LABELS` 是同一份名单，靠 `test/concept-dirs-agreement.test.ts`
+ * 钉住一致（跨语言没法共享一个常量，这个仓库对这类常量的既有做法就是"各写各的、由测试钉住"）。
+ *
+ * **两条线各自一个根之后这里要跟着改**：路径里不会再有 `Wiki`/`Chat` 这一段。
+ * 到那时 `wiki_health` 已经直接取 Python 给的 `report.lineLabel`（认得线的目录它都会给），
+ * 这里只剩"认不出的目录"这一支要兜底。
+ */
+export const VAULT_LINE_LABELS: Record<string, string> = { wiki: '文章线', chat: '聊天线' }
+
+/** 概念目录 → 线 id（`wiki`/`chat`）。按**路径段**认（`…/Wiki/Concepts`）；认不出返回 null，不猜。 */
+export function vaultLineId(dir: string): string | null {
+  const segments = dir.split(/[\\/]/).map(s => s.toLowerCase())
+  for (const id of Object.keys(VAULT_LINE_LABELS)) {
+    if (segments.includes(id)) return id
+  }
+  return null
+}
+
+/** 概念目录 → 线的展示名。**认不出线就返回目录名，不猜成某一条**。 */
+export function vaultLineLabel(dir: string): string {
+  const id = vaultLineId(dir)
+  if (id) return VAULT_LINE_LABELS[id]
+  return dir.split(/[\\/]/).filter(Boolean).pop() || dir
+}
+
+/**
+ * 工具参数里的 `line`：`wiki` / `chat` / `all`，不传就是 `wiki`（两条线分开之后，
+ * **默认只看文章线**，要合起来看显式给 `all`）。
+ *
+ * 认不出的值返回 `null` 让调用方**报错**，而不是当 `all`：`line: 'wiki '` 或 `'Wiki'`
+ * 悄悄变成"两条线都搜"的话，"我限定住了"就是句假话，而结果里看不出来。
+ */
+export function toolLine(value: unknown): 'wiki' | 'chat' | 'all' | null {
+  const raw = String(value ?? '').trim().toLowerCase()
+  if (!raw) return 'wiki'
+  return raw === 'wiki' || raw === 'chat' || raw === 'all' ? raw : null
+}
+
+/** 线 id → 展示名（工具输出里说"搜了哪条"用）。 */
+export function lineLabelOf(line: 'wiki' | 'chat' | 'all'): string {
+  return line === 'all' ? '两条线' : (VAULT_LINE_LABELS[line] ?? line)
+}
+
+/**
+ * 概念名 → 文件名。**与 `compile_wiki` 是同一套规则**（非法字符换下划线、截到 60 字）。
+ *
+ * 这里必须消毒：邻居名是从**文件内容**里读出来的，直接拼进路径就能走出目录
+ * （`../../` 那类）。文件名规则两边不一致也会让"查得到"变成"查不到"。
+ */
+export function safeConceptFile(name: string): string {
+  return `${name.replace(/[\\/:*?"<>|]/g, '_').slice(0, 60)}.md`
+}
+
+/** 概念页正文的第一句（跳过 frontmatter、标题、引用、列表）——给"这个邻居是什么"。 */
+/**
+ * 页面里「正文」的那一部分：`## 来源` 之前。
+ *
+ * **来源段不算正文** —— 它列的是文章标题（可能 300+ 条），拿它做「这个词在这页里吗」的判断，
+ * 会把「某篇来源的标题里含这个词」报成「正文提及」。
+ */
+export function pageBody(text: string): string {
+  const at = text.indexOf('## 来源')
+  return at === -1 ? text : text.slice(0, at)
+}
+/** 概念页里「相关概念」那一节指向的名字（按出现顺序）。 */
+function relatedNames(pagePath: string): string[] {
+  const text = readFileSync(pagePath, 'utf8')
+  const start = text.indexOf('## 相关概念')
+  if (start < 0) return []
+  const rest = text.slice(start + 1)
+  const end = rest.indexOf('\n## ')
+  const section = end > 0 ? rest.slice(0, end) : rest
+  return [...section.matchAll(/\[\[([^\]|]+)\]\]/g)]
+    .map(match => match[1].replace(/\.md$/, '').trim())
+    .filter(Boolean)
+}
+
+/**
+ * 从一页出发，**沿着图走若干跳**，逐层返回 `{名字, 一句定义, 从谁连过来}`。
+ *
+ * 与 `conceptNeighbors` 的分工：那个给"一跳"（本页 + 直接邻居），这个给"一片"。助手此前只能
+ * 一跳一跳地查（工具说明里写着"可以顺着它们再用本工具逐跳查下去"），但那要**模型自己决定**
+ * 下一跳查谁。一次给两跳，它就能直接看到"这个概念周围的生态"。
+ *
+ * 三条规矩：
+ * - **去重**：一个概念在图上有多条路径时只留**最先到达**的那条（BFS 保证它跳数最少），
+ *   否则同一个名字会在好几层里重复出现，读的人分不清；
+ * - **封顶**（`maxNodes`）：4 个邻居乘 4 乘 4 就是 64 —— 不封顶第三跳能把输出撑爆，而模型
+ *   读不完的图等于没给。截断了要**说出来**（`truncated`），不能默默少给；
+ * - **没建页的邻居照旧报数**（`missing`），不静默吞掉。
+ */
+export function conceptSubgraph(pageName: string, depth = 2, maxNodes = 30,
+                                wikiDirs: string[] = vaultDirs(), homeDir?: string): {
+  levels: Array<Array<{ name: string; brief: string; via: string }>>
+  truncated: boolean
+  missing: number
+} {
+  // 同 `conceptNeighbors`：传字符串会静默地按字符遍历，所以这里响，不猜。
+  if (typeof wikiDirs === 'string') {
+    throw new TypeError('conceptSubgraph 的 wikiDirs 要的是目录数组，不是单个字符串')
+  }
+  // 邻居可能住在另一个目录（文章概念指向聊天概念、反之亦然），所以查找跨目录。
+  // `homeDir` 只影响**起点那一页**：两条线各有一张同名页时，"第一个有这个文件的目录"
+  // 永远选出文章线那张，于是聊天线那张根本走不到 —— 而调用方（`search_knowledge`）
+  // 正好知道这一趟命中的是哪条线。
+  const find = (name: string, from?: string): string | null => {
+    const dirs = from ? [from, ...wikiDirs.filter((d) => d !== from)] : wikiDirs
+    for (const dir of dirs) {
+      const candidate = join(dir, safeConceptFile(name))
+      if (existsSync(candidate)) return candidate
+    }
+    return null
+  }
+  // **这一趟在哪条线上**：起点由 `homeDir` 定，之后沿 BFS **往下继承** —— 与图谱那边
+  // "先在页自己那条线里解析、线里没有才回退到另一条"是**同一条规则**。不继承的话每一跳
+  // 都会重新按"第一个有这个文件的目录"选，于是聊天线那一支走着走着就窜到文章线去了。
+  const resolved = new Map<string, string>()
+  const resolve = (name: string, from?: string): string | null => {
+    const hit = resolved.get(name)
+    if (hit) return hit
+    const path = find(name, from)
+    if (path) resolved.set(name, path)
+    return path
+  }
+  const start = resolve(pageName, homeDir)
+  if (!start) return { levels: [], truncated: false, missing: 0 }
+
+  const seen = new Set<string>([pageName])
+  const levels: Array<Array<{ name: string; brief: string; via: string }>> = []
+  let frontier = [pageName]
+  let truncated = false
+  let missing = 0
+  for (let hop = 0; hop < depth && frontier.length; hop += 1) {
+    const level: Array<{ name: string; brief: string; via: string }> = []
+    const next: string[] = []
+    for (const from of frontier) {
+      const fromPath = resolved.get(from) || resolve(from)
+      if (!fromPath) continue
+      const home = dirname(fromPath)
+      for (const name of relatedNames(fromPath)) {
+        if (seen.has(name)) continue
+        const target = resolve(name, home)
+        if (!target) {
+          missing += 1
+          continue
+        }
+        if (seen.size >= maxNodes) {
+          truncated = true
+          continue
+        }
+        seen.add(name)
+        level.push({ name, brief: conceptBrief(readFileSync(target, 'utf8')), via: from })
+        next.push(name)
+      }
+    }
+    if (level.length) levels.push(level)
+    frontier = next
+  }
+  return { levels, truncated, missing }
+}
+
+export function conceptBrief(text: string): string {
+  const body = text.startsWith('---') ? text.slice(text.indexOf('---', 3) + 3) : text
+  for (const raw of body.split('\n')) {
+    const line = raw.trim()
+    if (!line || /^[#>\-|`\[]/.test(line)) continue
+    return line.length > 60 ? `${line.slice(0, 60)}…` : line
+  }
+  return '(这页没写定义)'
+}
+
+/**
+ * 一个概念页在 `## 相关概念` 里连到的邻居——**图谱在 Agent 侧的落地**。
+ *
+ * 为什么要有：Obsidian 的关系图谱是人眼视图，助手那条路一直读不到"图"。但概念页里
+ * 本来就写着它的邻居，把它们一并给出去，"查一个概念"就变成"拿到一小块子图"。
+ * 实测：全部概念页都短于这个工具返回的 2,000 字上限，所以那段一直在返回内容里
+ * ——但**没人点明它可以顺着走**，也没人把邻居的一句话定义取出来。
+ *
+ * 有页的邻居连定义一起给；没有页的只报个数（`missing`），免得模型去追一个取不到的名字。
+ */
+export function conceptNeighbors(pageName: string, wikiDirs: string[] = vaultDirs()): { linked: Array<{ name: string; brief: string }>; missing: number } {
+  // **传字符串会静默地按字符遍历**（`for (const dir of 'D:\vault')` 挨个字符看过去），
+  // 于是 `join('D', '某概念.md')` 不存在，函数安静地回一句「没有邻居」。2026-09-27 把参数
+  // 从单个目录改成目录数组时，测试里正好踩到这个——类型拦得住 `src/`（`tsc` 覆盖它），
+  // 拦不住测试与将来的 JS 调用方。所以这里响，不猜。
+  if (typeof wikiDirs === 'string') {
+    throw new TypeError('conceptNeighbors 的 wikiDirs 要的是目录数组，不是单个字符串')
+  }
+  // **邻居可能住在另一个目录**（文章概念指向聊天概念、反之亦然），所以查找也是跨目录的
+  const find = (name: string): string | null => {
+    for (const dir of wikiDirs) {
+      const candidate = join(dir, safeConceptFile(name))
+      if (existsSync(candidate)) return candidate
+    }
+    return null
+  }
+  const pagePath = find(pageName)
+  if (!pagePath) return { linked: [], missing: 0 }
+  const text = readFileSync(pagePath, 'utf8')
+  const start = text.indexOf('## 相关概念')
+  if (start < 0) return { linked: [], missing: 0 }
+  const rest = text.slice(start + 1)
+  const end = rest.indexOf('\n## ')
+  const section = end > 0 ? rest.slice(0, end) : rest
+
+  const linked: Array<{ name: string; brief: string }> = []
+  let missing = 0
+  for (const match of section.matchAll(/\[\[([^\]|]+)\]\]/g)) {
+    const name = match[1].replace(/\.md$/, '').trim()
+    if (!name) continue
+    const target = find(name)
+    if (!target) {
+      missing += 1
+      continue
+    }
+    linked.push({ name, brief: conceptBrief(readFileSync(target, 'utf8')) })
+  }
+  return { linked, missing }
+}
+
+export interface ToolDef {
+  type: 'function'
+  function: {
+    name: string
+    description: string
+    parameters: Record<string, unknown>
+  }
+}
+
+export interface ToolContext {
+  userId: string
+  memory: AssistantMemory
+  /**
+   * 工具这一轮取到的图片，由 `look_at_image` 填。
+   *
+   * 图片走**侧信道**而不是工具返回值：工具返回值是字符串，要往里塞 base64 就得约定一个
+   * 魔法前缀再解析——那是这个仓库反复吃亏的"用文本承载结构"。服务层拿这个字段去把图片
+   * 附到对话里（见 `assistantService.toApiMessages`）。
+   */
+  pendingImages?: AttachedImage[]
+  /**
+   * 调用方是**外部机器**（MCP 那条路）时置 true。
+   *
+   * 与面板/微信那条路的区别不是审美：MCP 客户端是**别人家的进程**，它那边谁也看不到这一轮
+   * 是在什么上下文里决定调用的。所以对"会把用户数据送出去"的工具，机器调用默认只给**预览**，
+   * 要显式带 `confirm: true` 才真出境——与 CLI 那条 `--dry-run` / `--yes` 是同一套纪律，
+   * 也与 `capabilities.read.draft.confirmationRequired` 对得上。
+   */
+  requiresConfirm?: boolean
+}
+
+/** 随某条消息一起发出去的图片。只在构造请求那一刻存在，不进记忆、不进审计内容。 */
+export interface AttachedImage {
+  b64: string
+  mime: string
+  /** 来源消息的 local_id，只为了审计里能对上"发了哪条" */
+  localId?: number
+}
+
+/** 一轮对话里最多看几张图。每次调用一张，这是上限——图片按体积算钱，也按体积算隐私。 */
+const MAX_IMAGES_PER_TURN = 2
+
+function fmtTime(ts: number): string {
+  const n = Number(ts)
+  const d = n > 1e12 ? new Date(n) : new Date(n * 1000)
+  return `${d.getMonth() + 1}/${d.getDate()} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+}
+
+/**
+ * 转录里的时刻：`09-23 12:20`。
+ *
+ * 与 `fmtTime`（给用户看的工具输出用 `9/23 12:20`）**故意不同**：转录这一行的形状要和
+ * Python 侧逐字一致，见 `transcriptLine`。改 `fmtTime` 会连带改用户看到的东西，所以这里单独一个。
+ *
+ * **时区也是契约的一部分，而且是固定 +8（北京时间），不是本机时区**：Python 那边写的是
+ * `TZ = timezone(timedelta(hours=8))`（`scripts/reply_debt.py:39`），同一段对话从面板进来
+ * 与从命令行进来必须是同一串字符。用 `getHours()` 取本机时区，在非 +8 的机器上两边会差几小时
+ * ——CI（UTC）实测差 8 小时：TS 出 `09-23 04:00`、Python 出 `09-23 12:00`。
+ * 中国没有夏令时，固定 +8 是精确的。要改成"跟随本机时区"，得连 Python 的欠账天数一起改
+ * （那里用同一个 TZ 算"等了多少天"），不是改这一行的事。
+ */
+function transcriptTime(ts: number): string {
+  const n = Number(ts)
+  const shifted = new Date((n > 1e12 ? n : n * 1000) + 8 * 3600_000)
+  const pad = (value: number) => String(value).padStart(2, '0')
+  return `${pad(shifted.getUTCMonth() + 1)}-${pad(shifted.getUTCDate())} `
+    + `${pad(shifted.getUTCHours())}:${pad(shifted.getUTCMinutes())}`
+}
+
+/** 单条消息进转录的截断长度。**必须等于** `scripts/reply_debt.py` 的 `DRAFT_MSG_CHARS`。 */
+export const TRANSCRIPT_MSG_CHARS = 160
+
+/**
+ * 转录取**多少条**消息。**必须等于** `scripts/reply_debt.py` 的 `TRANSCRIPT_SIZE`。
+ *
+ * 与上面那个字数上限是一对：一个决定"多长的一段对话"，一个决定"每条多长"。两条入口
+ * （面板/微信走 `--stdin`，命令行走 `--talker`）必须给出同一段对话——否则同一件事在两边
+ * 判断出的结果会不一样，而**不会报任何错**。两边今天都是 30，但在这之前谁都没盯着它。
+ */
+export const TRANSCRIPT_MESSAGES = 30
+
+/**
+ * 消息是**谁**说的（对方那一侧）：**有解析出来的名字就用名字，没有就写「对方」**。
+ *
+ * **`senderUsername` 不参与**：它是数据库原列的 wxid（`wcdbCore` 的 `sender_username`、
+ * `sqlcipherCore` 的 `StrTalker`），不是名字。拿它当标签有两个坏处——把**账号标识**交给云端
+ * 模型，而且对模型没用（wxid 不告诉它这是谁）。
+ *
+ * 实测（本机 8 个会话、179 条别人发的消息）：`senderDisplay` 是有中文的名字 174 条，
+ * `senderUsername` 是 wxid 形状 176 条，两者**从不相同**。所以这个替换不丢信息：
+ * 群聊里照样分得清谁说的（名字比 wxid 还更有用），而标识不再出境。
+ */
+export function speakerLabel(message: any): string {
+  return message.senderDisplay || '对方'
+}
+
+/**
+ * 对话转录里的一行：`[09-23 12:20] 老王：那个文件你什么时候发我`。
+ *
+ * **这段形状在 Python 侧还有一份**：`reply_debt.format_line`（`draft_reply.py --talker`
+ * 那条路自己读库时用它渲染）。两处必须逐字一致，否则同一段对话走不同入口会得到不同的转录——
+ * 而它们**已经漂过**，实测三处不同：
+ *
+ * | | 这边（`--stdin`，面板/微信那条路） | Python `format_line`（`--talker` 命令行） |
+ * | --- | --- | --- |
+ * | 时刻 | `9/23 12:20` | `09-23 12:20` |
+ * | 对方那句 | 写死「对方」 | `senderDisplay` 优先（单聊里就是人名） |
+ * | 截断 | 160 字 | 120 字（留个 `…` vs 直接切掉） |
+ *
+ * 漂移里最危险的是「我」那个标记：脚本靠 `'] 我：'` 挑语气样本、靠 `lastFromMe` 判最后一条，
+ * 改错一个字全都**静默失效**（不报错，只是判断与语气样本都变差）。
+ * 所以有 `test/transcript-format-contract.test.ts`：同一批消息（含一条超长、一条非文本）
+ * 把两边逐字比一遍。谁改了这一行的形状而不改另一边，那条会红。
+ *
+ * **`senderUsername` 永远不参与**（实测过）：它是**数据库原列的 wxid**
+ * （`wcdbCore` 的 `sender_username`、`sqlcipherCore` 的 `StrTalker`），不是名字。
+ * 拿它当发言人的标签会把账号标识喂给两个云端模型——而这一行的目的只是让模型分得清谁说的。
+ * 所以规则是：**有解析出来的名字就用名字，没有就写「对方」**，绝不退回原列。
+ * `senderDisplay` 在真实路径上是有值的（实测一条会话：文本与图片消息都带），所以这边
+ * 正常会写成人名，「对方」只是兜底。
+ */
+export function transcriptLine(message: any): string {
+  const raw = message.localType === 1
+    ? (message.content || message.parsedContent || '')
+    : (message.parsedContent || message.content || '')
+  const body = privacyGate.maskMessageBody(
+    clipWithMarker(String(raw).replace(/\n/g, ' '), TRANSCRIPT_MSG_CHARS),
+    { isText: message.localType === 1 })
+  const speaker = message.isSend ? '我' : speakerLabel(message)
+  return `[${transcriptTime(message.createTime)}] ${speaker}：${body}`
+}
+
+/** SSRF 防护: 仅 http(s), 拒绝内网/环回地址
+ *
+ * 导出是为了能测它：这是**抓取前的安全边界**，而它守着的是"别让助手被一条收藏里的链接
+ * 带去访问内网"。纯函数，没有副作用。
+ */
+export function isSafeUrl(raw: string): boolean {
+  try {
+    const u = new URL(raw)
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
+    const h = u.hostname.toLowerCase()
+    if (!h) return false
+
+    // IPv6 字面量（URL 里带方括号）。Node 会把 [0:0:0:0:0:0:0:1] 归一成 [::1]，
+    // 但不碰 [fd00::1] 这类——所以下面按前缀逐个挡。
+    if (h.startsWith('[')) {
+      const inner = h.slice(1, -1)
+      if (inner === '::' || inner === '::1') return false
+      if (inner.startsWith('::ffff:')) return false      // IPv4 映射（可能是 127.0.0.1）
+      if (/^f[cd]/.test(inner)) return false             // fc00::/7 唯一本地
+      if (/^fe[89ab]/.test(inner)) return false          // fe80::/10 链路本地
+      return true
+    }
+
+    if (h === 'localhost') return false
+    // 纯数字或 0x 形式的整型主机名：内核会把它当 IPv4 用，而域名不可能是这种形状。
+    // （实测 Node 对 2130706433 / 0x7f000001 会归一成 127.0.0.1，这道是双保险。）
+    if (/^(0x[0-9a-f]+|[0-9]+)$/.test(h)) return false
+    // 私网前缀**只在真的是点分四段时**才判：否则 `10.example.com` 这种公网域名会被
+    // `^10\.` 误杀，工具会回一句「链接不安全，拒绝抓取」，而链接其实是好的。
+    if (/^[0-9]{1,3}(\.[0-9]{1,3}){3}$/.test(h)) {
+      if (/^(127\.|10\.|192\.168\.|169\.254\.|0\.)/.test(h)) return false
+      if (/^172\.(1[6-9]|2[0-9]|3[01])\./.test(h)) return false
+    }
+    // 这是一份已知形态的黑名单，不是"这地址一定可公网路由"的证明：
+    // NAT64（64:ff9b::/96）等映射形式不在覆盖范围内。
+    return true
+  } catch { return false }
+}
+
+
+/** 标签剥离 → 纯文本 */
+export function stripTags(seg: string): string {
+  return seg.replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]+>/g, '\n')
+    .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .split('\n').map(s => s.trim()).filter(Boolean).join('\n')
+}
+
+/** WAF 挑战页兜底: 正文藏在 cgiDataNew.content_noencode (JS 转义字符串) */
+export function extractFromChallengePage(html: string): string | null {
+  const start = html.indexOf("content_noencode: '")
+  if (start < 0) return null
+  let i = start + "content_noencode: '".length
+  let out = ''
+  while (i < html.length && out.length < 1_000_000) {
+    const ch = html[i]
+    if (ch === "'") break
+    if (ch === '\\' && i + 1 < html.length) {
+      const n = html[i + 1]
+      if (n === 'x' && i + 3 < html.length) {
+        out += String.fromCharCode(parseInt(html.slice(i + 2, i + 4), 16))
+        i += 4
+        continue
+      }
+      if (n === 'n') { out += '\n'; i += 2; continue }
+      if (n === 'r') { out += '\r'; i += 2; continue }
+      if (n === 't') { out += '\t'; i += 2; continue }
+      if (n === '\\' || n === "'" || n === '"') { out += n; i += 2; continue }
+    }
+    out += ch
+    i++
+  }
+  return out.length > 100 ? out : null
+}
+
+/** 从 HTML 提取正文文本 (微信公众号 js_content 优先, 配平 div 边界; 兜底 body) */
+export function extractText(html: string): string {
+  let seg = html
+  const jc = html.indexOf('id="js_content"')
+  if (jc >= 0) {
+    // 配平 <div/</div> 找 js_content 完整区块; depth 从 1 起算 (自身开标签位于 jc 之前)
+    let depth = 1, end = -1
+    const tag = /<\/?div\b/g
+    tag.lastIndex = jc
+    let m: RegExpExecArray | null
+    while ((m = tag.exec(html))) {
+      if (m[0] === '</div') { depth--; if (depth === 0) { end = m.index; break } }
+      else depth++
+    }
+    seg = end > jc ? html.slice(jc, end) : html.slice(jc, jc + 100_000)
+  } else {
+    const body = html.indexOf('<body')
+    if (body >= 0) seg = html.slice(body)
+  }
+  return stripTags(seg)
+}
+
+/** 确保数据库已连接 (connect 幂等, 已连接时直接返回) */
+/**
+ * 抓页面 HTML：微信内置浏览器 UA + Referer 绕 WAF，最多试两次。`read_favorite` 与 `fetch_article` 共用。
+ *
+ * `maxRedirects > 0` 时**自己跟跳转并逐跳复检白名单**：默认的 `redirect: 'follow'` 只看入口，
+ * 一次 302 就能把白名单绕过去（拿到一个被允许的入口，跳到内网地址）。`fetch_article`
+ * 收的是用户/模型给的任意 URL，所以要这道闸；`read_favorite` 收的是用户**自己收藏**的链接，
+ * 保持原行为不动（那里用 denylist，且收藏里本来就有各种站）。
+ */
+async function fetchArticleHtml(
+  url: string,
+  opts: { maxRedirects?: number; allowHop?: (u: string) => boolean } = {},
+): Promise<{ status: number; html: string }> {
+  const maxRedirects = opts.maxRedirects ?? 0
+  let current = url
+  let lastStatus = 0
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    if (maxRedirects > 0 && opts.allowHop && !opts.allowHop(current)) {
+      return { status: lastStatus, html: '' }   // 某一跳出了白名单：宁可空手而归
+    }
+    let html = ''
+    let status = 0
+    let followed = false
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const res = await fetch(current, {
+          headers: {
+            'User-Agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.38(0x18002633) NetType/WIFI Language/zh_CN',
+            'Referer': 'https://mp.weixin.qq.com/',
+            'Accept': 'text/html,application/xhtml+xml',
+            'Accept-Language': 'zh-CN,zh;q=0.9',
+          },
+          ...(maxRedirects > 0 ? { redirect: 'manual' as const } : {}),
+          signal: AbortSignal.timeout(20_000),
+        })
+        status = res.status
+        if (maxRedirects > 0 && status >= 300 && status < 400) {
+          const location = res.headers.get('location')
+          if (!location) return { status, html: '' }
+          current = new URL(location, current).toString()
+          followed = true
+          break     // 换一跳，重来
+        }
+        html = (await res.text()).slice(0, 500_000)
+        // 正文验证: 必须含 js_content (否则是验证页, 重试)
+        if (res.ok && html.includes('js_content')) break
+      } catch { /* 超时/网络错误 → 重试 */ }
+    }
+    if (html) return { status, html }
+    lastStatus = status
+    // 没跟跳转就走完了两次尝试：就是抓不到，别再拿同一个地址重试下去
+    if (!followed) return { status, html: '' }
+  }
+  return { status: lastStatus, html: '' }
+}
+
+/** 读响应体但设上限：第三方搜索页可能很大，不让它把内存吃掉（超了就截断，不报错） */
+async function readTextLimited(response: Response, maxBytes: number): Promise<string> {
+  const buf = await response.arrayBuffer()
+  return Buffer.from(buf).subarray(0, maxBytes).toString('utf8')
+}
+
+/**
+ * 从抓到的 HTML 里取正文：优先正常页面的 `js_content`，取不到再走 WAF 挑战页的 `content_noencode`。
+ * 返回的文本已按 `maxChars` 截断。
+ */
+function articleTextFromHtml(html: string, maxChars: number): string {
+  let text = html.includes('js_content') ? extractText(html) : ''
+  if (!text || (text.match(/[一-鿿]/g) || []).length < 50) {
+    const decoded = extractFromChallengePage(html)
+    if (decoded) text = stripTags(decoded)
+  }
+  return text.slice(0, maxChars)
+}
+
+async function ensureDb(): Promise<void> {
+  await chatService.connect()
+}
+
+/** 最近一份**有内容**的日报是哪天，以及那是几天前。算不出来就回空串——不猜。 */
+function lastDailyNote(): string {
+  try {
+    const days = readdirSync(bizDailyDir())
+      .filter(name => /^\d{4}-\d{2}-\d{2}$/.test(name)).sort().reverse().slice(0, 30)
+    for (const day of days) {
+      const file = join(bizDailyDir(), day, '.articles.json')
+      if (!existsSync(file)) continue
+      const payload = JSON.parse(readFileSync(file, 'utf8'))
+      if ((payload?.articles ?? []).length) {
+        const ago = Math.round((Date.now() - new Date(`${day}T00:00:00`).getTime()) / 86_400_000)
+        return `；最近一次有内容的日报是 ${day}（${ago} 天前）`
+      }
+    }
+  } catch { /* 扫不出来就什么都不说，而不是猜一个日期 */ }
+  return ''
+}
+
+interface TalkerCandidate {
+  username: string
+  displayName?: string | null
+}
+
+class ToolInputError extends Error {}
+
+/**
+ * 把待办 id 露给模型。**不露出来它就指不到具体哪一条**——`set_todo_status` 只能靠 id
+ * 或唯一的任务文字定位，而任务文字常常是长句、几条之间又很像。
+ * 给完整 id（CLI 那边支持 id 前缀，但前缀要唯一才安全，这里不赌）。
+ */
+function idTag(t: any): string {
+  return t?.id ? ` [id: ${t.id}]` : ''
+}
+
+export function boundedToolInteger(value: unknown, fallback: number, maximum: number, field = 'limit'): number {
+  if (value === undefined || value === null || value === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
+    throw new ToolInputError(`${field} 必须是 1-${maximum} 的整数`)
+  }
+  return parsed
+}
+
+export function resolveUniqueTalker(name: string, sessions: TalkerCandidate[]): string {
+  const query = name.trim()
+  if (!query) throw new ToolInputError('contact 不能为空')
+
+  const unique = (matches: TalkerCandidate[]) => [...new Set(matches.map(item => item.username))]
+  const usernameMatches = unique(sessions.filter(item => item.username === query))
+  if (usernameMatches.length === 1) return usernameMatches[0]
+
+  const exactNameMatches = unique(sessions.filter(item => item.displayName === query))
+  if (exactNameMatches.length === 1) return exactNameMatches[0]
+  if (exactNameMatches.length > 1) {
+    throw new ToolInputError(`会话名称“${query}”对应多个会话，请改用会话 ID`)
+  }
+
+  const partialMatches = unique(sessions.filter(item => item.displayName?.includes(query)))
+  if (partialMatches.length === 1) return partialMatches[0]
+  if (partialMatches.length > 1) {
+    throw new ToolInputError(`会话名称“${query}”匹配多个会话，请提供更完整名称或会话 ID`)
+  }
+  return query
+}
+
+/**
+ * 通讯录里按 **备注 / 显示名 / 昵称 / 别名 / username** 找唯一的一个；找不到或有歧义回 null。
+ *
+ * 与 `resolveUniqueTalker` 同一套纪律：**只认唯一**，不猜。
+ */
+export async function lookupContactUsername(name: string): Promise<string | null> {
+  const query = name.trim()
+  if (!query) return null
+  // 窗口给宽一点：关键字命中的是**包含**它的所有名字，一个字的查询能匹配到几十个人，
+  // 而精确那一个可能排在 20 名之后。实测（378 个真实联系人，都不在最近会话里）：
+  // 20 名时漏 6 个、60 名时漏 5 个，**认错都是 0 个**。剩下那 5 个都是单字名——它匹配到
+  // 几十个人，精确的那个仍在窗口之外。这个残余是安全的：回 null，助手说"没找到"，
+  // 而不会读到别人的聊天。
+  const contacts = await chatService.listContacts(query, 60)
+  const fields = (contact: Contact) => [contact.remark, contact.displayName, contact.nickname, contact.alias]
+    .filter(Boolean) as string[]
+  const exact = contacts.filter(c => c.username === query || fields(c).some(f => f === query))
+  const pool = exact.length ? exact : contacts.filter(c => fields(c).some(f => f.includes(query)))
+  const usernames = [...new Set(pool.map(c => c.username))]
+  return usernames.length === 1 ? usernames[0] : null
+}
+
+/**
+ * 显示名 → username 解析。
+ *
+ * 会话列表**只取最近 300 个**，而通讯录是完整的：名字不在那 300 个里时（对话很多的人，或
+ * 很久没聊过的人），旧行为是把查询词原样当 talker 返回——于是下游读到空、助手说"没找到
+ * 消息"，而那个人其实在通讯录里。所以**匹配不上时再查一次通讯录**。
+ *
+ * 兜底只做"名字 → username"，不去验证这个会话有没有消息：没有消息时下游会如实说
+ * "没找到消息"，那是对的答案，不该在这里变成"查无此人"。
+ */
+async function resolveTalker(name: string): Promise<string> {
+  const sessions = await chatService.listSessions(undefined, 300)
+  const talker = resolveUniqueTalker(name, sessions)     // 歧义会抛，让它抛
+  if (sessions.some(session => session.username === talker)) return talker
+  const fromBook = await lookupContactUsername(name)
+  return fromBook ?? talker
+}
+
+export const TOOL_DEFS: ToolDef[] = [
+  {
+    type: 'function',
+    function: {
+      name: 'list_sessions',
+      description: '列出用户最近的微信聊天会话(显示名+最后一条消息摘要)。用于了解用户最近在和谁聊天。',
+      parameters: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: '返回条数, 默认15' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_messages',
+      description: '读取用户与某位联系人的聊天记录。默认给最近若干条；'
+        + '问**某一天或某段时间**时给 since/until —— 不给的话久远的日子按条数是取不到的。'
+        + '联系人名用会话里出现的显示名。',
+      parameters: {
+        type: 'object',
+        properties: {
+          contact: { type: 'string', description: '联系人显示名或备注名' },
+          limit: { type: 'number', description: '消息条数, 默认20, 上限50' },
+          since: { type: 'string', description: '起点：2026-09-16 或相对写法 3d / 2w / 12h' },
+          until: { type: 'string', description: '终点（含当天）：2026-09-16' },
+        },
+        required: ['contact'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'look_at_image',
+      description: '看聊天里的一张图片（把图片本身交给模型看，不只是"这里有一张图"）。'
+        + '`image` 填 get_messages 输出里 `[图片 #1234]` 的编号。'
+        + '一轮最多看两张；隐私模式为 strict 时不可用（聊天图片不出发本机）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          contact: { type: 'string', description: '这张图所在会话的联系人显示名' },
+          image: { type: 'string', description: 'get_messages 里 [图片 #N] 的编号 N' },
+        },
+        required: ['contact', 'image'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_favorites',
+      description: '搜索用户的微信收藏(主要是收藏的公众号文章)；**不给关键词就是最近收藏了什么**。',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '搜索关键词' },
+          limit: { type: 'number', description: '返回条数, 默认8' },
+        },
+              },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'read_favorite',
+      description: '读取一篇收藏文章的正文内容。先用 search_favorites 或按关键词找到文章标题, 再用标题关键词调本工具抓取正文。适合「这篇文章讲了啥」「总结第一篇」类问题。',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '文章标题中的关键词' },
+          max_chars: { type: 'number', description: '返回正文字数上限, 默认3000' },
+        },
+        required: ['keyword'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_daily_report',
+      description: '获取公众号日报: 推送了哪些文章(标题/来源/分类/AI摘要)。'
+        + '适合「今天/某天公众号推了什么」「最近有哪些AI文章」「搜一下关于X的文章」类问题。'
+        + '**给 date 就是那一天的；不给 date 只给关键词/分类就是跨日期搜**（默认最近 7 天，用 days 调）。'
+        + '要当天那份**人读的日报正文**（不是条目清单）加 full。',
+      parameters: {
+        type: 'object',
+        properties: {
+          date: { type: 'string', description: '日期 YYYY-MM-DD；省略则最新一期（或配合关键词跨日期搜）' },
+          topic: { type: 'string', description: '分类过滤: AI | 学术 | 新闻 | 文学 | 投资' },
+          keyword: { type: 'string', description: '标题/摘要/来源关键词。不给 date 时跨日期搜' },
+          days: { type: 'number', description: '跨日期搜的时间窗(天), 默认 7, 上限 60' },
+          full: { type: 'boolean', description: '返回当天日报的正文（人读的那份），而不是条目清单' },
+          max_chars: { type: 'number', description: 'full 时正文上限, 默认 3000, 上限 6000' },
+          limit: { type: 'number', description: '返回条数, 默认15' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_sns',
+      description: '查看用户朋友圈: 最新动态时间线或统计概览(发帖数/好友数)。适合「朋友圈最近发了啥」「谁常发朋友圈」类问题。',
+      parameters: {
+        type: 'object',
+        properties: {
+          mode: { type: 'string', description: 'timeline (最新动态) / stats (统计) / users (谁发得最多), 默认 timeline' },
+          limit: { type: 'number', description: 'timeline 模式条数, 默认10' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_weread',
+      description: '查看用户微信读书数据。mode: shelf(书架) | notebooks(有笔记的书) | search(按书名搜) '
+        + '| stats(近期阅读时长) | book(某本书详情+我的进度) | review(某本书的热门书评) '
+        + '| discover(推荐/相似书) | profile(累计阅读画像)。适合「我在读什么书」「某本书讲什么」「读了多少」类问题。'
+        + 'book / review 需要先用 search 拿到 book_id。',
+      parameters: {
+        type: 'object',
+        properties: {
+          mode: { type: 'string', description: 'shelf | notebooks | search | stats | book | review | discover | profile, 默认 shelf' },
+          keyword: { type: 'string', description: 'search 模式的书名关键词' },
+          book_id: { type: 'string', description: 'book / review 模式的书籍 id（search 或 shelf 的结果里有）' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_todos',
+      description: '查看用户从聊天记录提取的待办任务清单(含优先级和截止时间)。适合「我最近有什么待办」「有什么紧急的事」类问题。'
+        + '每条后面方括号里的 id 用来改某一条的状态（set_todo_status 需要它）。按紧急度分组看用 group_by。',
+      parameters: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', description: 'pending | done, 默认 pending' },
+          group_by: { type: 'string', description: '传 urgency 就按紧急度分组列出' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_chats',
+      description: '在**聊天记录**里检索「在哪聊过某件事」，按字面词匹配。适合「上次说的那个部署方案是在哪聊的」。'
+        + '（知识库用 search_knowledge；助手记得的关于你的事用 search_memory）'
+        + '「谁提过这个客户」这类问题。它只匹配字面词（同义改写要靠别的路子），所以问题描述得具体些。'
+        + '代价：会把你的问题与候选词发给判断模型（不发聊天正文），约 1-2 秒。',
+      parameters: {
+        type: 'object',
+        properties: {
+          question: { type: 'string', description: '要找的事，用自然语言描述' },
+          per_card: { type: 'number', description: '每个会话最多回几条消息，默认 3' },
+          confirm: {
+            type: 'boolean',
+            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
+          },
+        },
+        required: ['question'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'draft_reply',
+      description: '帮用户**起草**一条回复（只产出候选文本，绝不替他发送）。适合「帮我回老王那句话」'
+        + '「这条怎么回」。会先判断对方要什么、该不该给实质内容、风险多高，再给几条候选。'
+        + '涉及钱或风险很高时**不给草稿**，只说明风险与该先确认什么——别把这种情况当失败。'
+        + '（想看对方写了什么用 get_messages；想知道谁在等用 who_owes_reply。）'
+        + '代价：要把这段对话发给判断模型与生成模型（两个云端模型），约几秒；'
+        + '**外部机器调用（MCP）不带 confirm 时只返回预览**（发多少字符给谁），不实际出境。',
+      parameters: {
+        type: 'object',
+        properties: {
+          contact: { type: 'string', description: '给谁起草（联系人名，和 get_messages 一样解析）' },
+          count: { type: 'number', description: '要几条候选，默认 3（最多 5）' },
+          confirm: {
+            type: 'boolean',
+            description: '仅当用户**明确同意**把这段对话发给两个云端模型时才传 true。'
+              + '不传或传 false 时只返回预览（多少条消息、多少字符、发给哪两个模型），零出境。',
+          },
+        },
+        required: ['contact'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'who_owes_reply',
+      description: '看看谁在等你回话（对方说完就没下文的那种）。适合「我有没有漏回谁的消息」。'
+        + '代价：逐会话问一次判断模型，可能要几十秒；只报谁在等，不回正文。',
+      parameters: {
+        type: 'object',
+        properties: {
+          days: { type: 'number', description: '只看最近多少天有动静的会话，默认 14' },
+          confirm: {
+            type: 'boolean',
+            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
+          },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_semantic',
+      description: '按**意思**找聊天记录（语义/同义检索），而 search_chats 只匹配字面词——'
+        + '想不起原话、只记得大意时用它。'
+        + '「上次说的那个部署方案是在哪聊的」用 search_chats；「和钱有关的讨论」这种同义改写用这条。'
+        + '代价：查询词会发给阿里云百炼做嵌入、候选片段会发给判断模型重排（都是仓库既有的云端路径），'
+        + '需要先建过索引（weflow-cli search-index）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '要找的意思，用自然语言描述' },
+          line: {
+            type: 'string',
+            description: '搜哪一条知识库：wiki=公众号文章线与聊天记录里的文章（默认）、'
+              + 'chat=你的微信聊天记录、all=两条都搜。**默认只搜 wiki**，'
+              + '问"我们聊过什么"「上次说的那个」这类一定要给 chat 或 all，否则会搜不到。',
+          },
+          top_k: { type: 'number', description: '要几条，默认 8，上限 20' },
+          confirm: {
+            type: 'boolean',
+            description: '仅当用户**明确同意**这个工具会把内容发出去时才传 true。不传或传 false 时只返回预览（要发什么、发给谁），零出境。',
+          },
+        },
+        required: ['query'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'export_chat',
+      description: '把某个人的聊天记录导出成 HTML（含图片），落到 output/exports/ 下。'
+        + '适合「帮我把和某某的聊天导出备份一下」。**会写文件**：每次新建一个带时间戳的目录，绝不覆盖已有的，'
+        + '路径也不是你给而是固定的。',
+      parameters: {
+        type: 'object',
+        properties: {
+          contact: { type: 'string', description: '联系人显示名或备注名' },
+          limit: { type: 'number', description: '最多导出多少条，默认 500，上限 5000' },
+          format: { type: 'string', description: 'html(默认,含图片) / txt / json / excel' },
+        },
+        required: ['contact'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_knowledge',
+      description: '搜索**本地知识库**的概念页（公众号文章沉淀的是一条线、你自己的微信对话沉淀的是另一条），'
+        + '适合查概念解释、找之前整理过的知识。**默认只搜文章那条线**，`line` 可以换成聊天那条或两条都搜。'
+        + '**返回时会一并给出这一页连到的相关概念（每个一句定义）**——可以顺着它们再用本工具逐跳查下去，'
+        + '这样一次追问能走开一小块知识，而不是停在一个孤立页面上。'
+        + '（聊天里说过什么用 search_chats；助手记得的关于你的事用 search_memory）',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '概念名或关键词, 如 RAG、Agent' },
+          line: {
+            type: 'string',
+            description: '搜哪一条知识库：wiki=公众号文章沉淀的概念（默认）、'
+              + 'chat=你自己的微信对话沉淀的概念、all=两条都搜。'
+              + '**默认只搜 wiki**；问"我们聊过的某个概念"要给 chat 或 all。'
+              + '同一个概念名两条线可能各有一张页（那是设计），返回里会指明给的是哪一条。',
+          },
+          depth: { type: 'integer', description: '沿「相关概念」走几跳：默认 1 只给直接邻居，2 能一次看到这个概念周围的生态（最多 3）' },
+        },
+        required: ['keyword'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_stats',
+      description: '本地数据总览：会话数、收藏总数、日报文章数与覆盖天数、主题分布、概念页数。'
+        + '适合「我一共有多少数据」这类总览问题；单看公众号推送用 get_reading_stats。',
+      parameters: { type: 'object', properties: {} },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_reading_stats',
+      description: '**公众号**推送与日报处理的统计：哪些号发得多、哪些被日报处理得多。'
+        + '适合"哪个号发得最多""日报处理了多少篇"这类问题。'
+        // 原文写的是「回答"我最近都在读什么/哪个号发得最多"这类问题时用它」——
+        // 而"我最近在读什么"**正是微信读书的问题**。2026-09-28 实测：用户问"我在读什么书"，
+        // 模型抓住这一句用了它，返回一串公众号推送量（"发得最多的是红星新闻"），
+        // 用户看到的就是一个答非所问的答复。工具没错，错在这句说明侵占了读书的问题空间。
+        + '**它统计的是公众号推送与日报，不含读书数据**——"我在读什么书"那类问题不要用它。'
+        + '**日报没在跑的时候它会直说**（那不是"没内容"）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          days: { type: 'number', description: '统计最近多少天，默认 7，上限 90' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_memory',
+      description: '搜索**助手记得的关于你的事**（此前对话里提取的长期事实：偏好、项目、关系）。'
+        + '（聊天正文用 search_chats，整理过的知识用 search_knowledge）',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '搜索关键词' },
+        },
+        required: ['keyword'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'save_memory',
+      description: '把关于用户的重要持久事实存入长期记忆(如偏好、项目背景、重要关系)。',
+      parameters: {
+        type: 'object',
+        properties: {
+          content: { type: 'string', description: '事实内容, 40字以内' },
+        },
+        required: ['content'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'list_skills',
+      description: '列出本机装好的技能包(名字+一句话说明+版本)。技能是一份说明文档,'
+        + '用 read_skill 读它的正文再照着做；不要凭名字猜它怎么用。',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '可选：按关键词过滤（匹配 id、名称、说明和触发词）' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'read_skill',
+      description: '读取某个技能包的完整说明（SKILL.md 正文）。要用某个技能前先读它。'
+        + 'id 用 list_skills 查到的那个。',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '技能 id，如 wechat-article-extract' },
+        },
+        required: ['id'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'list_contacts',
+      description: '列出通讯录里的联系人（显示名、备注、昵称）。**不含 wxid 等本机标识**，'
+        + '只有能叫得出名字的人。'
+        + '（要看最近跟谁聊过用 list_sessions；要按名字查某个会话的聊天用 get_messages）',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '按名字过滤（可省略）' },
+          limit: { type: 'number', description: '最多几条, 默认 50, 上限 200' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_review',
+      description: '读某一天的学习回顾（对当天日报文章做的二次整理：要点、联系、值得回看的）。'
+        + '**与 get_daily_report 不是一回事**：那个是当天日报的原始条目清单，这个是复盘。',
+      parameters: {
+        type: 'object',
+        properties: {
+          date: { type: 'string', description: '日期 YYYY-MM-DD，省略则取最近一份' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'get_concepts',
+      description: '读知识库的两份总览索引（文章线、聊天线各一份）。这是**目录**，'
+        + '用来回答"我的知识库里都有什么"；要按名字找**某一页**的内容用 search_knowledge。',
+      parameters: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: '每份索引最多返回多少行, 默认 40' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'fetch_article',
+      description: '抓取一篇公众号文章的正文（需要完整链接）。只接受 https 的 mp.weixin.qq.com 链接。'
+        + '与 read_favorite 的区别：那个从你自己的收藏里找，这个由用户给出链接。',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: '公众号文章完整链接' },
+          max_chars: { type: 'number', description: '正文上限, 默认 3000, 上限 6000' },
+        },
+        required: ['url'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'search_public',
+      description: '在公开的公众号文章里按关键词搜标题与摘要（走第三方搜索页）。'
+        + '只搜公开文章，搜不到你自己的收藏、聊天记录或知识库。',
+      parameters: {
+        type: 'object',
+        properties: {
+          keyword: { type: 'string', description: '搜索词' },
+          limit: { type: 'number', description: '最多几条, 默认 8, 上限 20' },
+        },
+        required: ['keyword'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'format_article',
+      description: '把 Markdown 转成能直接粘进公众号编辑器的 HTML 片段（纯本地转换，不联网、不写文件）。'
+        + '主题名用 list_themes 查。',
+      parameters: {
+        type: 'object',
+        properties: {
+          // 参数名保持 `content` —— 这个名字在 MCP 那条路上已经被外部客户端用了，
+          // 改名的代价是别人的调用直接失效（工具名不变、参数变了，最难查的那种坏法）
+          content: { type: 'string', description: '要排版的 Markdown 正文' },
+          theme: { type: 'string', description: '主题名（省略用 default）' },
+        },
+        required: ['content'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'list_themes',
+      description: '列出可用的公众号排版主题（配合 format_article 用）。',
+      parameters: { type: 'object', properties: {} },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'lint_wiki',
+      description: '知识库体检：断链、孤儿页、空页、同名页。**只读**，不改任何页。',
+      parameters: { type: 'object', properties: {} },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'check_skills',
+      description: '技能体检：报出读不出来的 SKILL.md、跨目录同名、id 不合规范、被禁用的技能。'
+        + '与 list_skills 的区别：那个是清单，这个是**问题清单**。',
+      parameters: { type: 'object', properties: {} },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'set_todo_status',
+      description: '把一条待办标记为已完成 / 取消完成。**不能删除待办、不能新增**。'
+        + '要精确指到那一条：优先用 get_todos 给出的 id；也可以给一段任务文字，'
+        + '但**匹配到零条或多条都会被拒绝**（猜错条目比拒绝更糟）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: '待办 id（get_todos 输出里的那个）' },
+          task: { type: 'string', description: '或用任务文字精确匹配（必须唯一）' },
+          status: { type: 'string', description: 'done = 已完成, pending = 取消完成' },
+        },
+        required: ['status'],
+      },
+    },
+  },
+]
+
+/**
+ * MCP 那条路看得见的工具表。
+ *
+ * **它不叫 read-only**（曾经叫，而那是假的）：里面一直有写文件的 `export_chat`，也有几个会把
+ * 用户数据发给云端模型、需要 `confirm: true` 的工具。这里只排除**在那条路上根本做不了事**的，
+ * 而"为什么做不了"写在下面那张表里（值就是原因，不是 true）：
+ *
+ * - `save_memory`：写记忆。MCP 没有微信用户身份，挂的记忆桶是单独一条；让它写没有意义。
+ * - `look_at_image`：它的做法是把图**挂进侧信道**（`ctx.pendingImages`）交给助手自己的模型看，
+ *   而 MCP 那条路只把工具返回的**文本**交给客户端（见 `mcp-server/index.ts` 的 default 分支）——
+ *   图没人接，回话里却写着"已附上图片…你能看到它了"，那是**一句假话**。
+ *   按本仓"不摆一个跑不了的工具"那条立论（同 `unavailableToolReason`），它不该出现在这里。
+ *
+ * 做成表而不是写进 filter：这是**注册表的一部分**，`test/tool-registry.test.ts` 会盯着
+ * 表里的每个名字都真的存在于 `TOOL_DEFS`（写错一个名字 = 静默地没排除掉任何东西）。
+ */
+export const MCP_EXCLUDED: Record<string, string> = {
+  save_memory: 'MCP 没有微信用户身份，挂的记忆桶是单独一条，让它写没有意义',
+  look_at_image: 'MCP 只把工具返回的文本交给客户端，它挂进侧信道的图没人接，回话会变成一句假话',
+  // 这条是**故意留在外面的**（docs/MCP.md 的天花板：「mutating todos ... stay out」）：
+  // 助手在微信/面板里可以替你翻转一条待办状态，但外部 MCP 客户端不行——
+  // 那条路上没有"你"，只有调用方；一条机器指令顺手改掉你的待办，不该是默认能力。
+  set_todo_status: '待办是本地状态，MCP 那条路上没有用户可确认；改状态请在微信/面板里说，或用 CLI 的两段式 todos done',
+}
+
+export const MCP_TOOL_DEFS = TOOL_DEFS.filter(tool => !(tool.function.name in MCP_EXCLUDED))
+
+/** 脚本类工具的失败回话：桥接层已经分好类（超时/退出码/没有 JSON/脚本自己报错），
+ *  这里把它和 stderr 尾巴合起来**过一遍脱敏**再交给模型——stderr 里可能有密钥形状的东西，
+ *  而工具结果是要出境的。
+ */
+function fail(what: string, result: { error?: string; stderr?: string }): string {
+  const detail = [result.error, result.stderr].filter(Boolean).join(' · ')
+  const { safe } = privacyGate.redact(detail)
+  return `(${what}${safe ? ": " + safe : ""})`
+}
+
+/**
+ * **括号起头 = 工具没能给出内容**。这是本仓库既有的写法：`fail()` 与各分支的
+ * "查不到 / 缺参数 / 拒绝抓取"一律写成 `(…)`，而正常内容不带括号。
+ *
+ * 这张白名单是**唯一的例外**：成功的句子也可以是括号起头（不然它就不叫例外了）。
+ * 有一条测试盯着它——白名单里每一条都必须在 `assistantTools.ts` 里真的以 `return` 出现，
+ * 改措辞忘了同步就会红。反过来（有新的成功消息带括号、但没进白名单）测试抓不到，
+ * 这是这个信号的真实边界：**它靠约定，不是一个机器可读的成败字段**。
+ *
+ * 想要真字段，得把 outcome 从 ~40 个 return 处一路带出来（`ToolContext.outcome`）。
+ * 那件事记在 D-043 的"已知边界"里，没有做——这里用它是因为轨迹只想知道"这一步有没有
+ * 产出东西"，而这个判断错了的代价是报告里多一个/少一个「无内容」标记。
+ */
+export const PAREN_SUCCESS_PREFIXES = ['(已附上图片']
+
+/** 工具这次**有没有给出内容**。括号起头（除白名单外）都算没有。 */
+export function producedContent(text: string): boolean {
+  const head = (text ?? '').trimStart()
+  if (!head.startsWith('(')) return true
+  return PAREN_SUCCESS_PREFIXES.some(prefix => head.startsWith(prefix))
+}
+
+/**
+ * "这台机器上跑不了"的**声明**：缺哪个配置键、缺了之后怎么跟用户说（值就是那句话）。
+ *
+ * 做成一张表而不是一串 `if (name === '...')`：加一个带前置条件的工具，现在是在这里加**一行**，
+ * 而不是在 if 链里再插一段；`test/tool-registry.test.ts` 盯着表里的每个名字都真的存在于 `TOOL_DEFS`
+ * （写错名字 = 那条规则永远不生效，而且不会有任何报错）。
+ *
+ * **只写"缺了就跑不了"的前置条件**，不写"暂时没数据"——没数据时工具自己会说该运行什么
+ * （`先运行 weflow-cli wiki compile`），那是有用的回答。
+ */
+export const TOOL_REQUIREMENTS: Record<string, { key: string; why: string }> = {
+  search_semantic: { key: 'dashscopeApiKey', why: '语义检索需要 dashscopeApiKey' },
+  get_weread: { key: 'wereadApiKey', why: '微信读书需要 wereadApiKey' },
+  draft_reply: {
+    key: 'deepseekApiKey',
+    // **只有 DeepSeek 是必须的**。判断那一步（Jev）现在可降级：调不通就只用生成模型起草，
+    // 输出里会写明"这次没有判断、闸门没生效"（2026-09-25 Jev 免费期结束那天改的）。
+    // 所以缺 typesafeApiKey **不**该把这个工具收起来——那会让"能跑的工具"被藏掉。
+    why: '起草回复需要 deepseekApiKey（生成那一步）',
+  },
+}
+
+/**
+ * 这台机器上**跑不了**的工具，不该出现在工具表里。规则本身在上面的 `TOOL_REQUIREMENTS` 里，这里只是执行它。
+ *
+ * 为什么按配置过滤：模型看见工具就会去试。这台机器没配 `dashscopeApiKey` 时 `search_semantic`
+ * 必然失败——实测（评测的 `ambiguous-contact` 那次）模型连试两个检索工具、两个都报错，最后答复
+ * 里带着"两个检索工具都跑不通"。那不是助手的问题，是**我们摆了一个跑不了的工具**。工具越少，
+ * 选择也越准。
+ */
+export function unavailableToolReason(name: string, config: (key: any) => any = configService.get.bind(configService)): string | null {
+  const need = TOOL_REQUIREMENTS[name]
+  if (!need) return null
+  return String(config(need.key) || '').trim() ? null : need.why
+}
+
+/**
+ * 这台机器上**没启用**的能力，一句话一条，给系统提示词用。
+ *
+ * 为什么需要它：工具被藏起来之后，模型**看不见它存在**，于是用户问"我在读什么书"时它答
+ * "我没有 get_weread 这个工具" —— 2026-09-28 实测就是这么一轮对话，用户因此以为功能没做
+ * （其实做了、只是没配 key）。把"存在但没启用"告诉模型，它就能给出正确的下一步，
+ * 而不是否认这个功能存在。
+ *
+ * **这不等于把工具摆回去**：模型依然调不到它们，只是知道它们存在。把跑不了的工具放进工具表
+ * 的代价是实测过的（模型会去试，答复里带着一串报错，见 `availableToolDefs` 的说明）。
+ */
+export function unavailableCapabilities(
+  config: (key: any) => any = configService.get.bind(configService),
+): string[] {
+  return Object.entries(TOOL_REQUIREMENTS)
+    .filter(([name]) => unavailableToolReason(name, config))
+    .map(([, need]) => need.why)
+}
+
+/** 这台机器上真正可用的工具表。快路径派发也要过同一道判据（见 `unavailableToolReason`）。 */
+export function availableToolDefs(config?: (key: any) => any): ToolDef[] {
+  return TOOL_DEFS.filter(def => !unavailableToolReason(def.function.name, config))
+}
+
+/**
+ * 判断模型给的键翻成人话。
+ *
+ * 为什么要这一层：那些键是**英文判据的键名**（`casual_chat` / `give_commitment`），
+ * 原样交给助手，它就会照着念给用户听。映射不上就退回原键——如实展示，不硬编一个。
+ */
+const INTENT_LABELS: Record<string, string> = {
+  confirm_you_care: '想要你一个态度（在试探你还在不在意）',
+  vent_anger: '在发火，想被听见而不是被解决',
+  request_action: '有事要你办（发东西、付钱、约时间这类）',
+  seek_explanation: '想要个解释',
+  casual_chat: '在闲聊，没有事要你办',
+  close_topic: '在收尾，不想再展开',
+}
+const ACTION_LABELS: Record<string, string> = {
+  check_history: '先翻一下更早的聊天记录再说',
+  apologize: '具体地认错',
+  give_commitment: '给一个做得到的时间或交付',
+  explain: '说明经过，不辩解',
+  acknowledge: '表示收到了，先不承诺什么',
+  say_less: '少说',
+  make_plan: '一起定个时间',
+}
+const NEED_LABELS: Record<string, string> = {
+  apology: '一个道歉', action: '实际的动作', explanation: '解释', care: '被在意',
+  nothing: '什么都不用',
+}
+
+function zhLabel(map: Record<string, string>, key: unknown): string {
+  const text = String(key ?? '')
+  return map[text] || text || '说不准'
+}
+
+function riskLabel(score: unknown): string {
+  const value = Number(score ?? 0)
+  if (value >= 8) return '很危险'
+  if (value >= 6) return '偏危险'
+  if (value >= 3) return '留神'
+  return '安全'
+}
+
+/**
+ * 外部机器（MCP）调用到"会把用户数据送出去"的工具时，**统一只给预览**的那段文案。
+ *
+ * 四个出境工具（draft_reply / who_owes_reply / search_chats / search_semantic）共用这一份形状，
+ * 各自把"要发什么、发给谁"填进 `what`。预览阶段一律不出境：能用脚本自己的 `--dry-run`
+ * 报出具体数字的就报数字（draft_reply、who_owes_reply），报不出的就按入参说清
+ * （search_chats 的 --dry-run 打的是纯文本、不认 --json；semantic_search 根本没有 --dry-run）。
+ */
+function confirmPreview(what: string): string {
+  return [
+    '还没执行——这只是一次**预览**（没有把任何内容发出去）。',
+    what,
+    '用户明确同意之后再带 `confirm: true` 调一次，才会真的执行。',
+  ].join(String.fromCharCode(10))
+}
+
+export async function executeTool(name: string, args: Record<string, any>, ctx: ToolContext): Promise<string> {
+  try {
+    switch (name) {
+      case 'list_sessions': {
+        await ensureDb()
+        const limit = boundedToolInteger(args.limit, 15, 30)
+        const sessions = await chatService.listSessions(undefined, limit)
+        if (!sessions.length) return '(未查到会话, 数据库可能未连接)'
+        return sessions.map(s =>
+          `· ${s.displayName || s.username}: ${(s.summary || '').replace(/\n/g, ' ').slice(0, 30)}`).join('\n')
+      }
+      case 'get_messages': {
+        const contact = String(args.contact || '')
+        if (!contact) return '(缺少 contact 参数)'
+        const limit = boundedToolInteger(args.limit, 20, 50)
+        // 时间窗：不给就是"最近 N 条"（老行为一个字没改）。给了就用范围读——
+        // **这正是"上周三他说了什么"以前够不着的原因**：只按条数取，越久远的日子越取不到，
+        // 模型要么说查不到，要么把最近的消息当成那天的。
+        let from: number | undefined
+        let to: number | undefined
+        try {
+          from = resolveSince(args.since)
+          to = resolveUntil(args.until)
+        } catch {
+          return '(时间看不懂：since/until 可以写 2026-09-16 或 3d / 2w / 12h；收到的是'
+            + ` since=${JSON.stringify(args.since)} until=${JSON.stringify(args.until)})`
+        }
+        const windowed = from !== undefined || to !== undefined
+        const windowLabel = windowed
+          ? `${from ? new Date(from * 1000).toLocaleDateString('zh-CN') : '最早'}`
+            + ` 至 ${to ? new Date(to * 1000).toLocaleDateString('zh-CN') : '现在'}`
+          : ''
+        const talker = await resolveTalker(contact)
+        const msgs = windowed
+          ? await chatService.getMessagesInRange(talker, limit, from, to)
+          : await chatService.getMessages(talker, limit)
+        if (!msgs.length) {
+          return windowed
+            ? `(${windowLabel} 这段时间里没有「${contact}」的消息)`
+            : `(没找到「${contact}」的消息)`
+        }
+        // 图片消息带一个句柄：`[图片 #1234]` 里的 1234 就是 `look_at_image` 的 `image` 参数。
+        // strict 模式下图片不允许出境，那时不带句柄——不摆出一个工具必定会拒绝的东西。
+        const canLook = privacyGate.mode() !== 'strict'
+        const rendered = msgs.map(m => {
+          // 非文本消息优先用 `parsedContent`：它是读取器给的**显示形态**（`[图片]`、
+          // `[文件] Base.csv`、`某人 撤回了一条消息`…），而 `content` 对这类消息可能是
+          // 原始 XML（含 md5 与 cdn 链接）——那是给机器看的，不该塞进模型上下文。
+          const raw = m.localType === 1
+            ? (m.content || m.parsedContent || '')
+            : (m.parsedContent || m.content || '')
+          // 每条 160 字。此前是 80，引用消息（`[引用] 回复 ｜ 引：原文`）在 80 字里
+          // 引文只剩七八个字，等于白带；长文本消息也被从中间切掉。上限仍是有界的：
+          // limit 最多 50 条 × 约 180 字 ≈ 9k 字符。截断留省略号——切了却看起来像
+          // 说完了，模型会把半句当整句。
+          const flat = raw.replace(/\n/g, ' ')
+          const body = canLook && m.localType === 3
+            ? `[图片 #${m.localId}]`
+            : privacyGate.maskMessageBody(clipWithMarker(flat, MSG_BODY_CHARS),
+                                          { isText: m.localType === 1 })
+          // 这一行原来用 `senderUsername`（**wxid 原列**），等于把账号标识交给云端模型。
+          // 曾经以为"改成「对方」就分不清群聊里谁说的，是个真损失"——实测之后不成立：
+          // `senderDisplay` 本来就有名字（见 `speakerLabel`），换成它两边都占，
+          // 名字对模型还比 wxid 有用。自己发的仍是「用户」（这是对人说"你发了什么"，
+          // 与转录里的「我」是两种口吻，各自有测试钉着）。
+          return `[${fmtTime(m.createTime)}] ${m.isSend ? '用户' : speakerLabel(m)}: ${body}`
+        }).join('\n')
+        // 有时间窗时先说清窗口：模型据此判断"这些是不是那天的"，也免得它把窗口内的最后
+        // 一条当成"最新的"。
+        return windowed ? `（${windowLabel}，共 ${msgs.length} 条）\n${rendered}` : rendered
+      }
+      case 'look_at_image': {
+        const contact = String(args.contact || '')
+        // 句柄在 get_messages 里长这样：`[图片 #1234]`。允许带不带 `#` 都接受——模型从
+        // 上下文里抄一个编号过来，"抄得像不像"不该决定它能不能看图。
+        const image = String(args.image ?? '').replace(/^#/, '').trim()
+        if (!contact || !image) return '(缺少 contact 或 image 参数)'
+        if (!/^\d+$/.test(image)) {
+          return `(image 要填 get_messages 里 [图片 #N] 的编号，收到的是「${image.slice(0, 20)}」)`
+        }
+        // 第一层门：strict 模式（第三方聊天正文不出境）下图片也不出去。第二层在
+        // `toApiMessages` 里——"工具肯给"与"这道门肯放"是两件事。
+        if (privacyGate.mode() === 'strict' && !privacyGate.isLocalInference()) {
+          return '(当前隐私模式是 strict：聊天图片不发出本机，用不了这个工具。'
+            + '要让我看图，得把 assistantPrivacy 改成 balanced)'
+        }
+        const budget = ctx.pendingImages ?? []
+        if (budget.length >= MAX_IMAGES_PER_TURN) {
+          return `(这一轮已经看过 ${MAX_IMAGES_PER_TURN} 张图了，先把已经看到的说完，别再取)`
+        }
+        const talker = await resolveTalker(contact)
+        // 90 秒。建媒体索引是这条路唯一的成本，且随会话大小走：实测单聊 ~1 秒、
+        // 一个 3 万条消息的大群 18.9 秒（而那个群本机只有缩略图）。取到的图会落在
+        // `output/.cache/read-image/`，同一张再看是 0.1 秒。超时是必要的兜底——助手是
+        // **串行**处理消息的，一次卡住会挡住后面所有人的话，所以宁可说"取图失败"。
+        const r = await runPythonJson<any>('read_image.py',
+          ['--talker', talker, '--local-id', image, '--json'], { timeoutMs: 90_000 })
+        if (!r.ok) return fail('取图失败', r)
+        if (!r.data?.b64) {
+          // 文字说明而不是空：本机没有这张图的副本（缓存清过、或只有缩略图）是常态
+          return `(没取到 #${image} 的图片：${r.data?.reason || '本机没有这张图的副本'})`
+        }
+        // 拿到图才建数组：`pendingImages` 为 undefined 与"空数组"在下游是同一个意思，
+        // 但只有前者能一眼看出"这一轮没图"。
+        ;(ctx.pendingImages ??= []).push({
+          b64: r.data.b64, mime: r.data.mime || 'image/jpeg', localId: Number(image) })
+        const size = r.data.width && r.data.height ? `${r.data.width}×${r.data.height}` : '尺寸未知'
+        return `(已附上图片 #${image}（${size}）。你能看到它了，直接据此回答。)`
+      }
+      case 'search_favorites': {
+        await ensureDb()
+        // 不给关键词就是"最近收藏了什么"——这一问在聊天里很自然，没理由逼调用方编一个词
+        const keyword = String(args.keyword || '')
+        const limit = boundedToolInteger(args.limit, keyword ? 8 : 15, keyword ? 15 : 30)
+        const r = keyword ? await chatService.getFavorites({ keyword, limit })
+          : await chatService.getFavorites({ limit })
+        if (!r.success || !r.favorites?.length) {
+          if (r.error) return `(查询失败: ${r.error})`
+          return keyword ? `(收藏中未搜到「${keyword}」)` : '(收藏是空的，或收藏库还没连上)'
+        }
+        return `共${r.total}条, 前${r.favorites.length}条:\n` +
+          r.favorites.map(f => {
+            const desc = (f.desc || '').replace(/\s+/g, ' ').slice(0, 60)
+            return `· ${f.title || '(无标题)'} (${f.source_name || '未知来源'})${desc ? ` — ${desc}` : ''}`
+          }).join('\n')
+      }
+      case 'read_favorite': {
+        await ensureDb()
+        const keyword = String(args.keyword || '')
+        if (!keyword) return '(缺少 keyword 参数)'
+        const maxChars = boundedToolInteger(args.max_chars, 3000, 6000, 'max_chars')
+        const r = await chatService.getFavorites({ keyword, limit: 5 })
+        if (!r.success || !r.favorites?.length) {
+          return `(收藏中未找到「${keyword}」)`
+        }
+        const art = r.favorites.find(f => f.link) || r.favorites[0]
+        if (!art.link) {
+          const txt = (art.desc || art.content || '').trim()
+          return txt ? `「${art.title || '无标题'}」内容:\n${txt.slice(0, maxChars)}` : `(「${art.title}」没有可读的链接和内容)`
+        }
+        if (!isSafeUrl(art.link)) return `(链接不安全, 拒绝抓取: ${art.link.slice(0, 60)})`
+        // 微信内置浏览器 UA + Referer 绕 WAF（与 biz_daily.py 同策略）；
+        // 这段与 fetch_article 是同一份实现——两处各写一份必然会漂
+        const { status, html } = await fetchArticleHtml(art.link)
+        if (!html) return `(抓取失败 HTTP ${status})`
+        let text = articleTextFromHtml(html, maxChars)
+        if (html.includes('已被发布者删除')) return `(「${art.title}」已被发布者删除)`
+        if (!text.trim() || (text.match(/[\u4e00-\u9fff]/g) || []).length < 20) {
+          return `(「${art.title}」正文提取失败, 可能是纯图片文章或已被删除)`
+        }
+        return `「${art.title || '无标题'}」(${art.source_name || '未知来源'}) 正文:\n${text}`
+      }
+      case 'get_daily_report': {
+        const dates = existsSync(bizDailyDir())
+          ? readdirSync(bizDailyDir()).filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort().reverse()
+          : []
+        if (!dates.length) return '(还没有日报数据, 先运行 biz_daily 生成)'
+        const readArticles = (date: string): any[] | null => {
+          const file = join(bizDailyDir(), date, '.articles.json')
+          if (!existsSync(file)) return null
+          try {
+            const raw = JSON.parse(readFileSync(file, 'utf8'))
+            return Array.isArray(raw) ? raw : (raw.articles || Object.values(raw))
+          } catch { return null }
+        }
+        const fmt = (a: any) => {
+          const summary = (a.summary || '').replace(/\s+/g, ' ').slice(0, 80)
+          const where = a.date ? `${a.date} ` : ''
+          return `· ${where}[${a.topic}] ${a.title} (${a.source})${summary ? `\n  ${summary}` : ''}`
+        }
+        const limit = boundedToolInteger(args.limit, 15, 30)
+
+        // 不给 date 但给了关键词 → 跨日期搜（MCP 那边原本叫 search_articles，两个工具搜的
+        // 是同一批文章、只是范围不同，模型无从判断该用哪个，所以合并成一个）。
+        const wantDate = args.date ? safeDate(args.date) : null
+        if (args.date && !wantDate) return `(日期格式不对: ${args.date}，要 YYYY-MM-DD)`
+        if (!wantDate && (args.keyword || args.topic)) {
+          const days = boundedToolInteger(args.days, 7, 60)
+          const window = dates.slice(0, days)
+          const hits: any[] = []
+          let scanned = 0
+          for (const d of window) {
+            const arts = readArticles(d)
+            if (!arts) continue
+            scanned += arts.length
+            for (const a of arts) {
+              if (args.topic && a.topic !== args.topic) continue
+              if (args.keyword) {
+                const kw = String(args.keyword).toLowerCase()
+                const hay = `${a.title || ''} ${a.summary || ''} ${a.source || ''}`.toLowerCase()
+                if (!hay.includes(kw)) continue
+              }
+              hits.push({ ...a, date: d })
+            }
+          }
+          if (!hits.length) {
+            return `(最近 ${window.length} 天的日报里（共 ${scanned} 篇）没有匹配`
+              + `${args.keyword ? `「${args.keyword}」` : `主题 ${args.topic}`} 的文章)`
+          }
+          return `最近 ${window.length} 天里匹配 ${hits.length} 篇（共扫 ${scanned} 篇）:\n`
+            + hits.slice(0, limit).map(fmt).join('\n')
+        }
+
+        const date = wantDate || dates[0]
+        const all = readArticles(date)
+        if (!all) return `(${date} 没有日报。可用日期: ${dates.slice(0, 5).join(', ')})`
+        // `full`：给的是当天那份人读的日报正文（README.md），不是条目清单。
+        // 不加这个参数，模型想"把那天的日报念一段"就只能拿到标题列表。
+        if (args.full) {
+          const readme = join(bizDailyDir(), date, 'README.md')
+          if (!existsSync(readme)) return `(${date} 没有日报正文文件，只有条目)`
+          const maxChars = boundedToolInteger(args.max_chars, 3000, 6000)
+          return `${date} 日报正文（${all.length} 篇）:\n${readFileSync(readme, 'utf8').slice(0, maxChars)}`
+        }
+        let list = all
+        if (args.topic) list = list.filter(a => a.topic === args.topic)
+        if (args.keyword) {
+          const kw = String(args.keyword).toLowerCase()
+          list = list.filter(a =>
+            (a.title || '').toLowerCase().includes(kw) || (a.summary || '').toLowerCase().includes(kw))
+        }
+        if (!list.length) return `(${date} 日报共 ${all.length} 篇, 过滤后无匹配)`
+        const byTopic: Record<string, number> = {}
+        for (const a of all) byTopic[a.topic] = (byTopic[a.topic] || 0) + 1
+        const topicStat = Object.entries(byTopic).map(([t, n]) => `${t}${n}篇`).join(' ')
+        return `${date} 日报共 ${all.length} 篇 (${topicStat}), 匹配 ${list.length} 篇:\n` +
+          list.slice(0, limit).map(fmt).join('\n')
+      }
+      case 'get_sns': {
+        await ensureDb()
+        if (String(args.mode || 'timeline') === 'users') {
+          // 谁常发朋友圈：本地把最近的时间线按发帖人聚合。**不新增出境**——数据本来就在这一条工具里。
+          const r = await chatService.getSnsTimeline({ limit: 200 })
+          if (!r.success || !r.timeline?.length) {
+            return r.error ? `(朋友圈查询失败: ${r.error})` : '(朋友圈暂无缓存数据)'
+          }
+          const byAuthor = new Map<string, number>()
+          for (const post of r.timeline) {
+            const who = String(post.nickname || post.username || '未知')
+            byAuthor.set(who, (byAuthor.get(who) ?? 0) + 1)
+          }
+          const ranked = [...byAuthor.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)
+          const nl = String.fromCharCode(10)
+          return `最近 ${r.timeline.length} 条朋友圈里，发得最多的：`
+            + ranked.map(([who, n]) => `${nl}· ${who}：${n} 条`).join('')
+        }
+        if (String(args.mode || 'timeline') === 'stats') {
+          const r = await chatService.getSnsExportStats()
+          if (!r.success) return `(朋友圈统计失败: ${r.error})`
+          const d = r.data!
+          return `朋友圈统计: 总动态 ${d.totalPosts} 条, 发布过动态的好友 ${d.totalFriends} 人${d.myPosts != null ? `, 用户自己发过 ${d.myPosts} 条` : ''}`
+        }
+        const limit = boundedToolInteger(args.limit, 10, 20)
+        const r = await chatService.getSnsTimeline({ limit })
+        if (!r.success || !r.timeline?.length) return r.error ? `(朋友圈查询失败: ${r.error})` : '(朋友圈暂无缓存数据)'
+        return `最新 ${r.timeline.length} 条朋友圈:\n` + r.timeline.slice(0, limit).map((p: any) => {
+          const content = (p.content || '').replace(/\s+/g, ' ').slice(0, 100)
+          return `· [${fmtTime(p.create_time)}] ${p.nickname || p.username}: ${content}${p.media_count ? ` [${p.media_count}图]` : ''}`
+        }).join('\n')
+      }
+      case 'get_weread': {
+        const { wereadService } = await import('./wereadService.js')
+        const mode = String(args.mode || 'shelf')
+        const apiKey = (await import('./configService.js')).configService.get('wereadApiKey')
+        if (!apiKey) return '(微信读书未配置: config set wereadApiKey <key>)'
+        try {
+          if (mode === 'notebooks') {
+            const r = await wereadService.notebooks(20)
+            if (!r.ok || !r.data?.books?.length) return `(暂无读书笔记: ${r.error || ''})`
+            // `/user/notebooks` 把书名与作者**嵌在 `book` 里**，条目顶层没有这两个字段 ——
+            // 实测（2026-09-28）：直接读 `b.title` 会得到 `undefined`，而输出照样成立，
+            // 只是每本书都没名字。顶层那两个是兜底，网关换版本时用得上。
+            const titleOf = (b: any) => b?.book?.title || b?.title || '(未给书名)'
+            const authorOf = (b: any) => b?.book?.author || b?.author || ''
+            return `有笔记的书 ${r.data.books.length} 本:\n` +
+              r.data.books.slice(0, 15).map((b: any) =>
+                `· ${titleOf(b)} (${authorOf(b)}) — ${b.noteCount || 0} 条笔记`).join('\n')
+          }
+          if (mode === 'profile') {
+            const r = await wereadService.profile()
+            if (!r.ok || !r.data) return `(读不到阅读画像: ${r.error || ''})`
+            const p = r.data
+            return `阅读画像: ${p.name || '(未给昵称)'}\n`
+              + `累计阅读 ${Math.round((p.totalReadTime || 0) / 60)} 分钟、${p.totalReadDays || 0} 天\n`
+              + `书架 ${p.totalBooks || 0} 本，读完 ${p.totalFinished || 0} 本`
+          }
+          if (mode === 'stats') {
+            const r = await wereadService.readData('monthly')
+            if (!r.ok || !r.data) return `(读不到阅读统计: ${r.error || ''})`
+            const d = r.data
+            const top = (d.readLongest || []).slice(0, 5).map((x: any) =>
+              `· ${x?.book?.title || x?.albumInfo?.title || '(未知)'} ${Math.round((x?.readTime || 0) / 60)} 分钟`)
+            return `近期阅读 ${Math.round((d.totalReadTime || 0) / 60)} 分钟、读了 ${d.readDays || 0} 天`
+              + `，日均 ${Math.round((d.dayAverageReadTime || 0) / 60)} 分钟`
+              + (top.length ? `\n读得最久的:\n${top.join('\n')}` : '')
+          }
+          if (mode === 'book') {
+            const bookId = String(args.book_id || '').trim()
+            if (!bookId) return '(book 模式需要 book_id —— 先用 search 模式按书名找到它)'
+            const info = await wereadService.bookInfo(bookId)
+            if (!info.ok || !info.data) return `(读不到这本书: ${info.error || ''})`
+            const b: any = info.data
+            const prog = await wereadService.getProgress(bookId)
+            const pct = prog.ok && prog.data
+              ? `\n我的进度: ${prog.data.progress}%${prog.data.chapterTitle ? `（${prog.data.chapterTitle}）` : ''}`
+              : ''
+            return `《${b.title}》${b.author || ''}\n评分 ${b.rating ?? '未知'}（${b.ratingCount || 0} 人）`
+              + `| ${b.category || '未分类'} | ${b.wordCount || '未知'}字${pct}`
+          }
+          if (mode === 'review') {
+            const bookId = String(args.book_id || '').trim()
+            if (!bookId) return '(review 模式需要 book_id —— 先用 search 模式按书名找到它)'
+            const r = await wereadService.reviews(bookId, 5)
+            if (!r.ok || !r.data?.reviews?.length) return `(这本书还没有热门书评: ${r.error || ''})`
+            return `热门书评 ${r.data.reviews.length} 条:\n`
+              + r.data.reviews.map((v: any) =>
+                `· ${String(v.content || '').replace(/\s+/g, ' ').slice(0, 120)}`
+                + `（${v.user?.name || '匿名'}，${v.rating ? `评 ${v.rating} 分` : '未评分'}，${v.likeCount || 0} 赞）`).join('\n')
+          }
+          if (mode === 'discover') {
+            const bookId = String(args.book_id || '').trim()
+            const r = bookId ? await wereadService.similar(bookId, 6) : await wereadService.recommend(8)
+            if (!r.ok || !r.data?.books?.length) return `(读不到推荐: ${r.error || ''})`
+            return (bookId ? '与这本书相似的' : '为你推荐的') + `书 ${r.data.books.length} 本:\n`
+              + r.data.books.map((b: any) =>
+                `· 《${b.title}》${b.author || ''}${b.rating ? ` 评分 ${b.rating}` : ''}`
+                + (b.intro ? `\n  ${String(b.intro).replace(/\s+/g, ' ').slice(0, 80)}` : '')).join('\n')
+          }
+          if (mode === 'search') {
+            const kw = String(args.keyword || '')
+            if (!kw) return '(search 模式需要 keyword)'
+            const r = await wereadService.search(kw, 8)
+            if (!r.ok || !r.data?.books?.length) return `(没搜到「${kw}」: ${r.error || ''})`
+            return `搜索「${kw}」结果:\n` +
+              r.data.books.map((b: any) => `· ${b.title} (${b.author})`).join('\n')
+          }
+          const r = await wereadService.shelf()
+          if (!r.ok || !r.data?.books?.length) return `(书架为空或读取失败: ${r.error || ''})`
+          const books = r.data.books
+          const reading = books.filter((b: any) => b.progress && b.progress > 0 && b.progress < 100)
+          return `书架共 ${books.length} 本, 在读 ${reading.length} 本:\n` +
+            (reading.length ? reading.slice(0, 10).map((b: any) =>
+              `· ${b.title} (${b.author}) — 已读 ${b.progress || 0}%`).join('\n') : books.slice(0, 10).map((b: any) => `· ${b.title}`).join('\n'))
+        } catch {
+          return '(微信读书接口失败，请检查网络和本地配置)'
+        }
+      }
+      case 'get_todos': {
+        const status = String(args.status || 'pending')
+        // 走 pythonBridge（唯一的脚本调用入口）：失败原因分三类报出来，不解析人类可读文本。
+        // `--meta` 是为了分清"没有待办"与"从没提取过"——两者在 `--json` 下都是空数组，
+        // 而把后者说成前者，用户会以为自己真的没事要做。MCP 侧一直分得开（见 mcp_bridge.py），
+        // 这条工具此前没分。`--meta` 是新增开关，老形状（裸数组）原样保留给别的调用方。
+        const result = await runPythonJson<any>('extract_todos.py', ['list', '--status', status, '--json', '--meta'])
+        if (!result.ok) return fail('待办查询失败', result)
+        // 兼容老形状：万一是没有 --meta 的实现，拿到的是数组，就退回原来的说法。
+        const meta = result.data && !Array.isArray(result.data) ? result.data : null
+        const todos: any[] = meta ? (Array.isArray(meta.items) ? meta.items : []) : (Array.isArray(result.data) ? result.data : [])
+        if (!todos.length) {
+          if (meta && meta.extracted === false) {
+            return '(还没提取过待办——待办是从聊天记录里提取的，要用 `weflow-cli todos extract --days 7 --yes` 先跑一次；'
+              + '在那之前这份清单一直是空的，不代表你没有事要做)'
+          }
+          return `(没有${status === 'done' ? '已完成' : '待办'}任务)`
+        }
+        // 分组：`todos remind` 其实就是同一个文件按紧急度重排，所以不另开一个工具，
+        // 加个参数就够（多一个近义工具只会让模型在两者之间瞎挑）
+        if (String(args.group_by || '') === 'urgency') {
+          const order: Record<string, number> = { 高: 0, 中: 1, 低: 2 }
+          const sorted = [...todos].sort((a: any, b: any) =>
+            (order[a.urgency] ?? 3) - (order[b.urgency] ?? 3))
+          const groups: Record<string, any[]> = {}
+          for (const t of sorted) (groups[t.urgency || '未标'] = groups[t.urgency || '未标'] || []).push(t)
+          return `${status === 'done' ? '已完成' : '待办'} ${todos.length} 项（按紧急度分组）:\n` +
+            Object.entries(groups).map(([u, list]) =>
+              `【${u}】${list.length} 项\n` + list.slice(0, 10).map((t: any) =>
+                `· ${t.task || t.content || t.text || t.title}${t.deadline && t.deadline !== '未提及' ? ` (截止 ${t.deadline})` : ''}${idTag(t)}`).join('\n')
+            ).join('\n')
+        }
+        return `${status === 'done' ? '已完成' : '待办'} ${todos.length} 项:\n` +
+          todos.slice(0, 15).map((t: any) =>
+            `· [${t.urgency || '中'}] ${t.task || t.content || t.text || t.title}${t.deadline && t.deadline !== '未提及' ? ` (截止 ${t.deadline})` : ''}${idTag(t)}`).join('\n')
+      }
+      case 'search_chats': {
+        // 跨会话检索：本机 message_fts 索引 + 判断模型挑查询词（**只发候选词与问题，不发聊天内容**）
+        const question = String(args.question || '').trim()
+        if (!question) return '(缺少 question 参数)'
+        const perCard = boundedToolInteger(args.per_card, 3, 10, 'per_card')
+        // 外部机器默认只给预览，**按入参说清**。这里要说清的恰好是最要紧的那件事：
+        // 这条路上出去的是"你的问题 + 从聊天里提取的候选词"，**不含消息正文**（排序在本地做）。
+        if (ctx.requiresConfirm && args.confirm !== true) {
+          return confirmPreview(`会把你的问题「${question.slice(0, 40)}」与从聊天里提取的候选词`
+            + `（最多 ${perCard} 个会话各若干词，**不含消息正文**）发给判断模型 Jev，`
+            + '让它挑出你真正在找的词；排序在本地做。')
+        }
+        const result = await runPythonJson<any>('route_cards.py',
+          ['ask', question, '--yes', '--json', '--per-card', String(perCard)], { timeoutMs: 90_000 })
+        if (!result.ok) return fail('会话检索失败', result)
+
+        const ranked = Array.isArray(result.data?.ranked) ? result.data.ranked : []
+        if (!ranked.length) {
+          return `(没有会话字面命中「${question}」——检索只匹配字面词，换几个词再试)`
+        }
+        const lines = [`命中 ${ranked.length} 个会话（查询词：${(result.data.terms || []).join('、')}）：`]
+        for (const card of ranked.slice(0, 6)) {
+          lines.push(`· #${card.id} [${card.kind}] ${card.label}（该会话 ${card.messages} 条消息，最后活动 ${card.lastDaysAgo} 天前）`)
+          const rows = result.data?.messages?.[String(card.id)] || []
+          for (const row of rows.slice(0, perCard)) {
+            // 第三方聊天正文与 get_messages **同一条纪律**：出境前按隐私档位处理
+            const body = privacyGate.maskMessageBody(String(row?.text || '').replace(/\s+/g, ' ').slice(0, 60))
+            lines.push(`    ${body}`)
+          }
+        }
+        return lines.join('\n')
+      }
+      case 'who_owes_reply': {
+        // 谁在等我回话：逐会话问一次判断模型（较慢）。**不给正文**——真要看他写了什么，
+        // 用 get_messages 单独查，那条路有完整的隐私处理。
+        const days = boundedToolInteger(args.days, 14, 60, 'days')
+        // 外部机器（MCP）默认只给预览：这个工具**每个会话一次判断调用**，每一次都带着那段聊天正文，
+        // 是这条路上最贵也最"出境"的一个。预览走脚本自己的 --dry-run（只读本地、零出境）。
+        if (ctx.requiresConfirm && args.confirm !== true) {
+          const preview = await runPythonJson<any>('reply_debt.py',
+            ['--days', String(days), '--dry-run', '--json'], { timeoutMs: 60_000 })
+          if (!preview.ok || !preview.data?.success) {
+            return `(预览失败：${String(preview.data?.error || preview.error || '未知').slice(0, 120)})`
+          }
+          const p = preview.data
+          return confirmPreview(`会把最近 ${days} 天里 ${p.conversations} 个有动静的会话、`
+            + `约 ${p.stateChars} 字符聊天正文，**逐个**发给判断模型（api.typesafe.ai），每会话一次请求。`)
+        }
+        const result = await runPythonJson<any>('reply_debt.py', ['--days', String(days), '--json'],
+          { timeoutMs: 180_000 })
+        if (!result.ok) return fail('欠账查询失败', result)
+
+        const debts = Array.isArray(result.data?.debts) ? result.data.debts : []
+        if (!debts.length) return `(最近 ${days} 天没有明显在等你回话的会话)`
+        const lines = [`在等你回话的 ${debts.length} 个会话（最近 ${days} 天）：`]
+        for (const row of debts.slice(0, 8)) {
+          const prob = Number(row.waiting ?? 0)
+          const urgency = row.urgencyScore === null || row.urgencyScore === undefined ? '' : ` · 紧急度 ${row.urgencyScore}`
+          lines.push(`· ${row.name}（等了 ${row.days} 天 · 概率 ${prob.toFixed(2)}${urgency}${row.kind ? ' · ' + row.kind : ''}）`)
+        }
+        lines.push('（想看某人具体说了什么，用 get_messages 单独查；这里只报谁在等。）')
+        return lines.join('\n')
+      }
+      case 'draft_reply': {
+        // 起草：判断（Jev）→ 起草（DeepSeek）→ 排序（Jev）。**只产出文本，绝不发送**——
+        // 仓库里"发送"本来就不可达（TOOL_DEFS 没有任何 send 类工具），这里也不新增。
+        const contact = String(args.contact || '')
+        if (!contact) return '(缺少 contact 参数)'
+        const count = boundedToolInteger(args.count, 3, 5, 'count')
+        // strict 下**直接拒绝**，而不是把遮成"内容 N 字"的正文拿去起草——那会得到一段
+        // 基于空白的、看起来正常的回复，比拒绝更糟（同 `look_at_image` 的处置）。
+        //
+        // 这里**不看 `isLocalInference()`**，与 `look_at_image` 刻意不同：那张图确实送到
+        // 本机模型，所以"本机推理"在那里是成立的旁路；而起草出境的是**脚本自己的**两条远程
+        // 调用（`jev_client` 走 HTTP、`_utils.call_deepseek` 写死 DeepSeek），跟 `aiEngine`
+        // 配成什么毫无关系。照抄那个旁路＝用"我配了本地模型"当理由，把正文发到远端去。
+        // 这条是实测出来的：aiEngine=ollama + strict 下，原实现真的把对话交给了脚本。
+        if (privacyGate.mode() === 'strict') {
+          return '(当前隐私模式是 strict：聊天正文不出境，而起草必须把正文发给远端模型'
+            + '（判断一步、生成一步），这一步用本机推理也绕不开。'
+            + '在电脑上 `weflow-cli config set assistantPrivacy balanced`，或用本机命令 '
+            + '`weflow-cli draft <会话>`。)'
+        }
+        const talker = await resolveTalker(contact)
+        const msgs = await chatService.getMessages(talker, TRANSCRIPT_MESSAGES)
+        if (!msgs.length) return `(没找到「${contact}」的消息)`
+
+        // **外部机器（MCP）默认只给预览，不做出境。** 与 CLI 的 `--dry-run` / `--yes` 同一套纪律：
+        // 预览只读本地库、报清要发多少字符给哪两个模型，零出境。
+        // 面板/微信那条路（`requiresConfirm` 不置位）不受影响——它那边的边界是白名单 + 用户
+        // 在一个只有自己看得见的会话里显式开口问。
+        if (ctx.requiresConfirm && args.confirm !== true) {
+          const preview = await runPythonJson<any>('draft_reply.py',
+            ['--talker', talker, '--dry-run', '--json', '--count', String(count)],
+            { timeoutMs: 60_000 })
+          if (!preview.ok || !preview.data?.success) {
+            return `(起草预览失败：${String(preview.data?.error || preview.error || '未知').slice(0, 120)})`
+          }
+          const d = preview.data
+          return confirmPreview('会把「' + d.name + '」最近的 ' + d.messages + ' 条消息、共 '
+            + d.stateChars + ' 字符，发给 ' + (d.models?.judge || '判断模型') + ' 与 '
+            + (d.models?.draft || '生成模型') + '（' + (d.calls || '3 次调用') + '），产出 '
+            + d.count + ' 条候选。'
+            // 前提说明也在出境的那一段里（它会进两段提示词），所以预览要把它算进去
+            + (d.lastFromMe ? '另外会附一句「最后一条是我自己发的」的前提说明。' : ''))
+        }
+
+        // 逐条遮罩**再**交给脚本：Python 侧没有任何脱敏实现（全仓只有两处无关的位掩码），
+        // 而脱敏这一层在 TS。**不在 Python 里再写一份**——同一件事两处实现早晚有一处会漏。
+        //
+        // 说明白：上面的门**现在**已经把 strict 全挡了，所以这里的 `maskMessageBody`
+        // 在当下打不到（balanced/open 不改正文）。留着它是因为它守的是另一条不变式：
+        // "交给脚本的正文一定先过一道遮罩"，谁将来松开了上面那道门，这道还在。
+        const transcript = msgs.slice().reverse().map(m => transcriptLine(m))
+        const result = await runPythonJson<any>('draft_reply.py',
+          ['--stdin', '--yes', '--json', '--count', String(count)],
+          // `lastFromMe`：`transcript` 是 `msgs` **反过来**渲染的，所以最后一条 = `msgs[0]`。
+          // 用结构化字段 `isSend`，不去解析那行文本（群聊里别人的标签是人名，不是「对方」）。
+          // 这段是说给脚本听的**前提**：最后一条是我发的时，"回答对方最后一句"这件事根本不存在。
+          { stdin: JSON.stringify({ name: contact, lines: transcript, lastFromMe: !!msgs[0]?.isSend }),
+            timeoutMs: 240_000 })
+        if (!result.ok) return fail('起草失败', result)
+
+        const data = result.data ?? {}
+        if (!data.success) return `(起草没跑通: ${String(data.error || '未知').slice(0, 120)})`
+        const picked = Array.isArray(data.drafts) ? data.drafts : []
+        // 脚本给的前提说明（仅当最后一条是我发的）。**用户也要看见**：否则候选看起来像在回
+        // 一句根本不存在的话。三条出口（降级/被闸门拦下/正常）都要带上它。
+        const premise = typeof data.premise === 'string' ? data.premise.trim() : ''
+        // **降级那次（Jev 没调通）必须说清两件事**：这次没有判断，以及那道闸门没生效。
+        // 闸门（涉钱/高风险不给草稿）正是靠判断结果才存在的——不标出来，降级看起来就跟
+        // "判断过了"一模一样。**不以 `(` 开头**：那个前缀在本仓库表示"工具没产出内容"。
+        if (data.judged === false) {
+          if (!picked.length) return `(起草没给出候选：${String(data.judgeNote || '判断与生成都没跑通').slice(0, 120)})`
+          const lines = [...(premise ? [premise, ''] : []),
+                         `这次**没有判断**——${String(data.judgeNote || '判断那一步没调通')}。`,
+                         `所以"涉钱/风险高就不给草稿"那道闸门**没生效**，下面 ${picked.length} 条是生成模型`
+                         + `按上下文给的，你自己看一眼：`, '']
+          picked.forEach((draft: any, index: number) => { lines.push(`${index + 1}. ${draft.text}`) })
+          lines.push('')
+          lines.push('（这些只是文本，没有发送任何东西——回不回、怎么回由你决定。）')
+          return lines.join('\n')
+        }
+        const judgment = data.judgment ?? {}
+        const why = `对方${zhLabel(INTENT_LABELS, judgment.intent)}`
+          + `；建议${zhLabel(ACTION_LABELS, judgment.action)}`
+          + `；风险 ${Number(judgment.risk ?? 0).toFixed(1)}/9 ${riskLabel(judgment.risk)}`
+        // 被闸门拦下：**不是失败**，是这条最该给的回答。所以不以 `(` 起头
+        // （那个前缀在本仓库里表示"工具没产出内容"，见 `producedContent`）。
+        if (data.gate === 'refused') {
+          return [...(premise ? [premise, ''] : []),
+                  '不起草。', String(data.reason || ''), '',
+                  '建议先：', ...(data.advice ?? []).map((line: string) => `· ${line}`),
+                  '', `（判断：${why}。这些只是文本，没有发送任何东西。）`].join('\n')
+        }
+        const drafts: any[] = Array.isArray(data.drafts) ? data.drafts : []
+        if (!drafts.length) return '(起草没给出候选)'
+        const lines = [...(premise ? [premise, ''] : []),
+                       `建议这样回（${drafts.length} 条，第一条是判断最合适的）：`, '']
+        drafts.forEach((draft, index) => { lines.push(`${index + 1}. ${draft.text}`) })
+        lines.push('')
+        lines.push(`（判断：${why}。这些只是文本，没有发送任何东西——回不回、怎么回由你决定。）`)
+        return lines.join('\n')
+      }
+      case 'search_semantic': {
+        // 语义/同义检索（向量相似度 + 决策模型重排）。字面词搜不到时用这条。
+        // **出境说明**：查询词要发阿里云百炼做嵌入，候选片段要发判断模型重排——
+        // 两者都在仓库既有的云端路径上（不是新类别），但这里如实写出来。
+        const query = String(args.query || '').trim()
+        if (!query) return '(缺少 query 参数)'
+        const line = toolLine(args.line)
+        if (!line) return `(line 只能是 wiki / chat / all，收到「${String(args.line)}」)`
+        const topK = boundedToolInteger(args.top_k, 8, 20, 'top_k')
+        // 外部机器默认只给预览（`semantic_search.py` 没有 --dry-run，按入参说清）
+        if (ctx.requiresConfirm && args.confirm !== true) {
+          return confirmPreview(`会把查询词「${query.slice(0, 40)}」发给阿里云百炼做嵌入，`
+            + `再把前 ${topK} 条命中的本地片段（可能含聊天或文章原文）发给判断模型 Jev 重排。`)
+        }
+        // **查询词走环境变量、不进 argv**：仓库写进测试的隐私纪律（进程列表里看不到正文）
+        const result = await runPythonJson<any>('semantic_search.py',
+          ['search', '--top-k', String(topK), '--line', line],
+          { env: { WEFLOW_SEARCH_QUERY: query }, timeoutMs: 90_000 })
+        if (!result.ok) return fail('语义检索失败（索引可能还没建：weflow-cli search-index）', result)
+        if (result.data && typeof result.data.error === 'string') {
+          return `(语义检索没跑成：${String(result.data.error).slice(0, 120)})`
+        }
+        if (!result.data || !Array.isArray(result.data.results)) {
+          // **形状不对要响，不能降级成"没有结果"**：脚本那边 `search` 的输出是一个带
+          // `line` / `results` 的对象，而"读不到"和"搜不到"在界面上长得一模一样
+          // （`(语义检索没有结果)`）—— 那正是这个仓库一直在防的那种静默。
+          return `(语义检索返回了看不懂的形状：${JSON.stringify(result.data).slice(0, 120)})`
+        }
+        const rows = result.data.results
+        const note = String(result.data.note || '')
+        const scope = String(result.data.lineLabel || lineLabelOf(line))
+        if (!rows.length) {
+          return `(语义检索在${scope}里没有结果「${query}」${note ? '：' + note : ''}`
+            + `${line === 'all' ? ')' : '；`line: \'all\'` 两条线一起搜)'}`
+        }
+        return `语义检索「${query}」（范围：${scope}）前 ${rows.length} 条：` + String.fromCharCode(10) + rows.map((row: any) => {
+          const title = String(row.title || row.source || '(无标题)').slice(0, 40)
+          const score = typeof row.score === 'number' ? `（${row.score.toFixed(2)}）` : ''
+          const text = privacyGate.maskMessageBody(
+            String(row.text || row.content || '').replace(/\s+/g, ' ').slice(0, 80))
+          const nl = String.fromCharCode(10)
+          return `· ${title}${score}${text ? nl + '    ' + text : ''}`
+        }).join(String.fromCharCode(10))
+      }
+      case 'export_chat': {
+        // **写操作**，边界写死：只往 output/exports/ 下**新建**目录（名字带时间戳），绝不覆盖；
+        // 路径由这里拼，模型给不了任意路径。用户是在对话里明确要求的，这就是那次确认。
+        const contact = String(args.contact || '').trim()
+        if (!contact) return '(缺少 contact 参数)'
+        const limit = boundedToolInteger(args.limit, 500, 5000, 'limit')
+        const format = String(args.format || 'html').toLowerCase()
+        if (!['html', 'txt', 'json', 'excel'].includes(format)) {
+          return `(参数错误: format 只能是 html/txt/json/excel，收到 ${format.slice(0, 12)})`
+        }
+        const talker = await resolveTalker(contact)
+
+        const safeName = contact.replace(/[\/:*?"<>|]/g, '_').slice(0, 20) || 'chat'
+        const stamp = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 12)
+        // 目录名到秒，同一秒里导两次会撞进同一个目录——那就不是"绝不覆盖"了。撞了就往后加序号。
+        // 导出根目录可用环境变量改（测试用临时目录；也方便自定义）。默认在仓库的 output/exports 下。
+        const exportRoot = process.env.WEFLOW_ASSISTANT_EXPORT_ROOT || join(PKG_ROOT, 'output', 'exports')
+        let outDir = join(exportRoot, `${safeName}-${stamp}`)
+        for (let n = 2; existsSync(outDir) && n < 100; n++) {
+          outDir = join(exportRoot, `${safeName}-${stamp}-${n}`)
+        }
+        const result = format === 'txt' ? await exportService.exportTxt(talker, outDir, limit)
+          : format === 'json' ? await exportService.exportJson(talker, outDir, limit)
+            : format === 'excel' ? await exportService.exportExcel(talker, outDir, limit)
+              : await exportService.exportHtml(talker, outDir, limit, '', undefined, undefined, true)
+        if (!result.success) return `(导出失败: ${String(result.error || '未知').slice(0, 100)})`
+        const suffix = format === 'html' ? '，含图片' : ''
+        // 报**真的写到了哪**：`outDir` 才是（撞名之后会带 `-2`），而事前拼的 `safeName-stamp`
+        // 两次导出会报成同一个名字——实测第二次明明是 `…-2`，消息里却是基础名（2026-09-23 验收）。
+        // 根目录是默认值时按仓库相对路径报（用户照着找得到）；自定义根时只报目录名——
+        // **不把绝对路径发进聊天**，那是本机路径，没必要出境。
+        const shown = exportRoot === join(PKG_ROOT, 'output', 'exports')
+          ? `output/exports/${basename(outDir)}`
+          : basename(outDir)
+        return `已导出 ${result.count ?? 0} 条消息到 ${shown}/（${format}${suffix}）`
+      }
+      case 'search_knowledge': {
+        const kw = String(args.keyword || '')
+        if (!kw) return '(缺少 keyword 参数)'
+        const line = toolLine(args.line)
+        if (!line) return `(line 只能是 wiki / chat / all，收到「${String(args.line)}」)`
+        const all = vaultDirs().filter(dir => existsSync(dir))
+        if (!all.length) return '(知识库尚未生成, 先运行 weflow-cli wiki compile)'
+        // **默认只搜文章线**（两条线分开是用户要求的）；`line: 'all'` 才两条一起搜。
+        // 范围一定要写在输出里：不说的话，"这一条线里没有"会被读成"整个知识库里没有"。
+        const liveDirs = line === 'all' ? all : all.filter(dir => vaultLineId(dir) === line)
+        if (!liveDirs.length) {
+          return `(${lineLabelOf(line)}还没有概念页——知识库里现在只有${all.map(vaultLineLabel).join('、')}；`
+            + `要看那些用 line: 'all')`
+        }
+        const entries: Array<{ dir: string; file: string; where: string }> = []
+        let total = 0
+        for (const dir of liveDirs) {
+          // 标注来源，好让模型（和读日志的人）知道这条来自哪个知识库
+          const where = vaultLineId(dir) === 'chat' ? '聊天' : '文章'
+          for (const file of readdirSync(dir).filter(f => f.endsWith('.md'))) {
+            entries.push({ dir, file, where })
+            total += 1
+          }
+        }
+        const hits = entries.filter(e => e.file.replace('.md', '').toLowerCase().includes(kw.toLowerCase()))
+        if (!hits.length) {
+          // **只搜正文，不搜「来源」段。** 页面的来源段可能列 300+ 条文章标题（2026-09-27 那批
+          // 改动之后就是这样），拿整个文件做包含判断，会把「某篇来源的**标题**里含这个词」报成
+          // 「**正文**提及」—— 实测 `Grok-4` 命中 4 张页、其中 3 张的正文里根本没有它。
+          // `assistant-eval` 的 `knowledge-fallback-not-body` 钉住这件事。
+          //
+          // 顺带把**那一句**给出去：只给页名的话模型会自己补内容（实测它补出过「Grok-4 是作为
+          // 被测试的模型之一出现的」，那是它从别处知道的，不是这一页里写的）。
+          const contentHits = entries.map(e => {
+            const text = pageBody(readFileSync(join(e.dir, e.file), 'utf8'))
+            const at = text.toLowerCase().indexOf(kw.toLowerCase())
+            if (at === -1) return null
+            // （局部变量别叫 `line`：外层那个 `line` 是"搜哪条知识库"，同名会把它遮住）
+            const snippetLine = text.slice(Math.max(0, at - 80), at + 160)
+              .split('\n').find(l => l.includes(kw)) || ''
+            return { ...e, snippet: snippetLine.trim().slice(0, 180) }
+          }).filter((e): e is { dir: string; file: string; where: string; snippet: string } => e !== null)
+            .slice(0, 5)
+          if (!contentHits.length) {
+            // **说清是哪个范围里没收录**：只写"知识库未收录"会被读成整个知识库都没有
+            return `(${lineLabelOf(line)}没收录「${kw}」, 这一趟看了 ${total} 个概念页`
+              + (line === 'all' ? ')' : '；`line: \'all\'` 可以连另一条线一起搜)')
+          }
+          return `正文提及「${kw}」的概念页（${lineLabelOf(line)}）:` + '\n'
+            + contentHits.map(e => `· ${e.file.replace('.md', '')}（${e.where}）: ${e.snippet}`).join('\n')
+        }
+        const hit = hits[0]
+        const name = hit.file.replace('.md', '')
+        const page = readFileSync(join(hit.dir, hit.file), 'utf8')
+        // 两条线各有一张同名页是**设计**（两个命名空间分开）。只给第一条会让模型以为另一条
+        // 没有这个概念 —— 而它可能正是用户问的那一条（"我们聊过的"vs"公众号里读到的"）。
+        const alsoIn = hits.filter(h => h.where !== hit.where).map(h => h.where)
+        const alsoNote = alsoIn.length ? `（另一个同名页在${alsoIn.join('、')}知识库：line: 'all' 两条都看）` : ''
+        // **顺带把邻居给出去**（见 `conceptNeighbors`）：一次调用拿到"这个概念 + 连着它的一小块子图"。
+        // 不点明"可以再用本工具查其中任意一个"的话，模型会把它当装饰性文字读过去。
+        const depth = boundedToolInteger(args.depth, 1, 3, 'depth')
+        // **从命中的那一条线开始**（`hit.dir`）：同名概念两条线各一张，不指定起点的话
+        // 永远走文章线那张 —— 而上面刚刚才告诉模型"另一条线也有这个概念"
+        const { levels, truncated, missing } = conceptSubgraph(name, depth, 30, vaultDirs(), hit.dir)
+        const out = [`「${name}」概念页（${hit.where}知识库）${alsoNote}:`, page.slice(0, 2000)]
+        if (levels.length) {
+          out.push('', depth > 1
+            ? `—— 它周围的概念（${depth} 跳；「←」标出是从哪个概念连过来的）——`
+            : '—— 它连到的概念（可以再用本工具查其中任意一个，或者加 depth 参数一次多看几跳）——')
+          levels.forEach((level, index) => {
+            if (levels.length > 1) out.push(`第 ${index + 1} 跳：`)
+            for (const nb of level) {
+              out.push(depth > 1 ? `· ${nb.name} ← ${nb.via} — ${nb.brief}` : `· ${nb.name} — ${nb.brief}`)
+            }
+          })
+          // 封顶了要**说出来**：默默少给的话，模型会以为这就是全部
+          if (truncated) out.push(`（图太大，只给了前 ${levels.flat().length} 个概念；
+想看某个分支可以单独查它）`)
+        }
+        if (missing) out.push(`（另有 ${missing} 个相关概念尚未建页，查不到）`)
+        return out.join('\n')
+      }
+      case 'get_stats': {
+        await ensureDb()
+        const sessions = await chatService.listSessions(undefined, 1000)
+        const fav = await chatService.getFavorites({ limit: 1 })
+        const lines = [`会话数: ${sessions.length}`, `收藏总数: ${fav.success ? fav.total : '未知'}`]
+        // 知识库那一半：MCP 的手写 get_stats 一直有、助手这边缺。同一个工具名在两个界面
+        // 报的东西不一样，是最容易让人误判成数据丢了的那种不一致。
+        const dates = existsSync(bizDailyDir())
+          ? readdirSync(bizDailyDir()).filter(d => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort()
+          : []
+        let articleCount = 0
+        const topics: Record<string, number> = {}
+        for (const d of dates) {
+          const file = join(bizDailyDir(), d, '.articles.json')
+          if (!existsSync(file)) continue
+          try {
+            const raw = JSON.parse(readFileSync(file, 'utf8'))
+            const arts: any[] = Array.isArray(raw) ? raw : (raw.articles || [])
+            articleCount += arts.length
+            for (const a of arts) topics[a.topic || '未知'] = (topics[a.topic || '未知'] || 0) + 1
+          } catch { /* 某一天的文件坏了不该让整个统计失败 */ }
+        }
+        if (dates.length) {
+          lines.push(`日报文章: ${articleCount} 篇，覆盖 ${dates.length} 天（${dates[0]} ~ ${dates[dates.length - 1]}）`)
+          const top = Object.entries(topics).sort((a, b) => b[1] - a[1]).slice(0, 6)
+          if (top.length) lines.push(`主题分布: ${top.map(([t, n]) => `${t}${n}`).join('、')}`)
+        } else {
+          lines.push('日报文章: 还没有日报数据')
+        }
+        const conceptCounts: string[] = []
+        for (const dir of vaultDirs()) {
+          const idx = wikiIndexPath(dir)
+          if (!existsSync(idx)) continue
+          const m = readFileSync(idx, 'utf8').match(/共\s*(\d+)\s*个概念/)
+          if (m) conceptCounts.push(`${vaultLineLabel(dir)} ${m[1]}`)
+        }
+        if (conceptCounts.length) lines.push(`概念页: ${conceptCounts.join('、')}`)
+        return lines.join('\n')
+      }
+      case 'get_reading_stats': {
+        const days = boundedToolInteger(args.days, 7, 90, 'days')
+        const r = await runPythonJson<any>('daily_stats.py',
+          ['--days', String(days), '--json'], { timeoutMs: 60_000 })
+        if (!r.ok) return fail('读取公众号统计失败', r)
+        const rows: any[] = r.data?.sources ?? []
+        if (!rows.length) return `(最近 ${days} 天没有公众号推送记录)`
+        const period = r.data?.period ?? {}
+        const byPushed = [...rows].sort((a, b) => (b.pushed ?? 0) - (a.pushed ?? 0)).slice(0, 5)
+        const lines = [`最近 ${days} 天（${period.start} 至 ${period.end}）：${rows.length} 个公众号有推送`]
+        lines.push('发得最多：' + byPushed.map(x => `${x.name}(${x.pushed})`).join('、'))
+        const processed = rows.filter(x => (x.processed ?? 0) > 0)
+          .sort((a, b) => (b.processed ?? 0) - (a.processed ?? 0)).slice(0, 5)
+        if (processed.length) {
+          lines.push('日报处理得最多：' + processed.map(x => `${x.name}(${x.processed})`).join('、'))
+        } else {
+          // **直说日报没在跑**：这时"处理数 0"不是"这些号没内容"，而是日报压根没运行。
+          // 把它混成"没读到东西"，用户会去查号，而该查的是日报任务。
+          lines.push(`这 ${days} 天日报没有任何处理记录` + lastDailyNote())
+        }
+        return lines.join('\n')
+      }
+      case 'search_memory': {
+        const hits = ctx.memory.searchFacts(ctx.userId, String(args.keyword || ''))
+        if (!hits.length) return '(长期记忆中无相关内容)'
+        return hits.map(f => `· ${f.content}`).join('\n')
+      }
+      case 'save_memory': {
+        const content = String(args.content || '').trim().slice(0, 60)
+        if (!content) return '(内容为空, 未保存)'
+        const added = ctx.memory.addFact(ctx.userId, content)
+        return added ? '(已存入长期记忆)' : '(与已有记忆重复, 未保存)'
+      }
+      case 'list_skills': {
+        const scan = scanSkills()
+        const q = String(args.query || '').trim().toLowerCase()
+        const hit = (s: { id: string; name: string; description: string; triggers: string[] }) =>
+          !q || [s.id, s.name, s.description, ...s.triggers].some(x => String(x).toLowerCase().includes(q))
+        const rows = scan.skills.filter(hit)
+        if (!rows.length) {
+          // 一个技能都没有时**说清是"没装"还是"目录配错了"**：后者会把用户引到错的地方找
+          if (!scan.skills.length) {
+            return `本机没有扫描到技能。技能根目录：${skillRoots().join('、')}`
+              + (scan.missingRoots.length ? `（其中这些目录不存在：${scan.missingRoots.join('、')}）` : '')
+          }
+          return `没有匹配「${args.query}」的技能（本机共有 ${scan.skills.length} 个）`
+        }
+        const disabled = disabledIds()
+        const lines = rows.map(s => {
+          const state = skillState(s, disabled)
+          const tag = state === 'disabled' ? '[已禁用] ' : ''
+          const ver = s.version ? ` v${s.version}` : ''
+          return `· ${tag}${s.id}${ver}：${s.name} —— ${s.description || '（无描述）'}`
+        })
+        lines.push(`（共 ${rows.length} 个，正文用 read_skill 读）`)
+        return lines.join('\n')
+      }
+      case 'read_skill': {
+        const id = String(args.id || '').trim()
+        if (!id) return '(参数错误: 缺少技能 id)'
+        const body = readSkillBody(id)
+        if (!body.ok) return body.text
+        // 技能正文是**磁盘上的内容**，可能含 `</weflow-local-data>` —— 必须包起来再进上下文
+        return frameLocalData(`skill.${id}`, body.text)
+      }
+      case 'list_contacts': {
+        await ensureDb()
+        const keyword = String(args.keyword || '').trim()
+        const limit = boundedToolInteger(args.limit, 50, 200)
+        const contacts = await chatService.listContacts(keyword || undefined, limit)
+        if (!contacts.length) {
+          return keyword
+            ? `(通讯录里没有匹配「${keyword}」的名字)`
+            : '(通讯录是空的或读不到——可以用 check 看本机数据源的状态)'
+        }
+        // **只给名字**：`username` 是 wxid，`avatarUrl` 里也可能带本机标识，
+        // 本仓的纪律是本机标识不进模型上下文（同 speakerLabel 那边的处理）
+        const names: string[] = []
+        for (const c of contacts) {
+          const n = String(c.remark || c.displayName || c.nickname || '').trim()
+          if (n && !names.includes(n)) names.push(n)
+        }
+        if (!names.length) return '(通讯录读到了, 但都没有可显示的名字)'
+        return `通讯录里 ${names.length} 个名字:\n` + names.slice(0, limit).map(n => `· ${n}`).join('\n')
+      }
+      case 'get_review': {
+        const dir = reviewsDir()
+        if (!existsSync(dir)) {
+          // 说清"这个目录本来就还没生成"，而不是让模型以为"今天没有回顾"
+          return '(还没有学习回顾——它不是日报自动产的，要单独跑 `weflow-cli review`)'
+        }
+        const files = readdirSync(dir).filter(f => /^Daily-\d{4}-\d{2}-\d{2}\.md$/.test(f)).sort().reverse()
+        if (!files.length) return '(学习回顾目录是空的)'
+        const want = args.date ? safeDate(args.date) : null
+        if (args.date && !want) return `(日期格式不对: ${args.date}，要 YYYY-MM-DD)`
+        const pick = want ? files.find(f => f.includes(want)) : files[0]
+        if (!pick) {
+          return `(${want} 没有学习回顾。最近几份: ${files.slice(0, 3).map(f => f.slice(6, 16)).join(', ')})`
+        }
+        const maxChars = boundedToolInteger(args.max_chars, 3000, 6000)
+        const body = readFileSync(join(dir, pick), 'utf8')
+        const date = pick.slice(6, 16)
+        return `${date} 学习回顾:\n${body.slice(0, maxChars)}`
+      }
+      case 'get_concepts': {
+        const limit = boundedToolInteger(args.limit, 40, 120)
+        const out: string[] = []
+        for (const dir of vaultDirs()) {
+          const line = dir.split(/[\\/]/).includes('Chat') ? '聊天线' : '文章线'
+          const index = wikiIndexPath(dir)
+          if (!existsSync(index)) { out.push(`【${line}】还没有总览索引（还没编译过这一线的知识库）`); continue }
+          const text = readFileSync(index, 'utf8')
+          const rows = text.split(/\r?\n/).filter(l => l.trim()).slice(0, limit)
+          out.push(`【${line}】${rows.length} 行:\n${rows.join('\n')}`)
+        }
+        return out.join('\n\n')
+      }
+      case 'format_article': {
+        const content = String(args.content || '')
+        if (!content.trim()) return '(参数错误: content 不能为空)'
+        const { formatWeChatArticle } = await import('./wechat-formatter.js')
+        const theme = String(args.theme || 'default')
+        const html = formatWeChatArticle(content, { theme: theme as any })
+        const preview = html.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').slice(0, 200)
+        return `主题: ${theme}\n总长度: ${html.length} 字符\n正文预览: ${preview}…\n---\n${html}`
+      }
+      case 'list_themes': {
+        const { listThemes } = await import('./wechat-formatter.js')
+        const themes = listThemes()
+        if (!themes.length) return '(没有可用主题)'
+        return `可用主题 ${themes.length} 个:\n`
+          + themes.map(t => `· ${t.id} — ${t.name}: ${t.description}`).join('\n')
+      }
+      case 'lint_wiki': {
+        // 两个知识库都要查（本仓的分线纪律：只查一个，另一半的断链永远看不见）
+        const parts: string[] = []
+        let totalBad = 0
+        // **真正体检过几条线。"跳过"不算"没问题"**：CI 上（检出里没有 `output/wechat-vault`）
+        // 两条线都只打「目录不存在，跳过」，而下面那一支原来照样会加一句"两个知识库都没有断链…"
+        // —— 没看过却说干净。用户没编译过知识库时也会撞上同一句话。
+        let checked = 0
+        for (const dir of vaultDirs()) {
+          // **线名优先由 Python 那边给**（`report.lineLabel`，源头是 `_utils.LINE_LABELS`）：
+          // 两条线各自一个根之后聊天线很可能不再叫 `Chat`，按路径猜会把聊天线报成
+          // **文章线**，还不报错。`guess` 只在目录不存在（来不及问 Python）与自定义
+          // `--dir` 认不出线时兜底。
+          const guess = vaultLineLabel(dir)
+          if (!existsSync(dir)) { parts.push(`【${guess}】目录不存在，跳过`); continue }
+          // 超时给 60 秒：本机最大的一条线（3,623 页）实测 **3.4 秒**（脚本里的 O(n²) 修掉之后，
+          // 见 wiki_lint.py 那条注释），17 倍余量够用。默认的 30 秒曾经也超——那是因为脚本本身慢，
+          // 不是超时给得小。
+          const r = await runPythonJson<any>('wiki_lint.py', ['--dir', dir, '--json'], { timeoutMs: 60_000 })
+          if (!r.ok || !r.data) {
+            // 失败要说出来：静默跳过会让"体检通过"变成一句假话
+            parts.push(`【${guess}】体检失败: ${r.error || '读不到结果'}`)
+            totalBad += 1
+            continue
+          }
+          const d = r.data
+          const line = d.lineLabel || guess
+          const broken = (d.broken || []).length
+          const orphans = (d.orphans || []).length
+          const empty = (d.empty || []).length
+          const dup = Object.keys(d.duplicateTitles || {}).length
+          // 跨线同名**不计入问题数**：两条线各留一张同名页是设计（两个命名空间分开），
+          // 把它算成"要修的"会让人去修一个设计如此的东西。
+          const cross = (d.crossLineSameName || []).length
+          checked += 1
+          totalBad += broken + orphans + empty + dup
+          parts.push(`【${line}】${d.pages || 0} 张页：断链 ${broken}、孤儿 ${orphans}、空页 ${empty}、同名 ${dup} 组`
+            + (cross ? `（另有 ${cross} 个概念两条线都有，设计如此）` : ''))
+        }
+        return (checked && !totalBad ? '两个知识库都没有断链/孤儿/空页/同名。\n' : '') + parts.join('\n')
+      }
+      case 'check_skills': {
+        const scan = scanSkills()
+        const disabled = disabledIds()
+        const lines: string[] = [`技能目录: ${skillRoots().join('、')}`, `扫描到 ${scan.skills.length} 个技能`]
+        for (const dir of scan.missingRoots) lines.push(`· 目录不存在: ${dir}`)
+        if (scan.unreadable.length) {
+          lines.push(`读不出来的 ${scan.unreadable.length} 个（frontmatter 缺失或不闭合）:`)
+          for (const u of scan.unreadable) lines.push(`· ${u.file} —— ${u.reason}`)
+        }
+        if (scan.conflicts.length) {
+          lines.push(`跨目录同名的 ${scan.conflicts.length} 个（靠前的目录胜出）: ${scan.conflicts.map(c => c.id).join('、')}`)
+        }
+        const warned = scan.skills.filter(s => s.notes.length)
+        if (warned.length) {
+          lines.push(`有提醒的 ${warned.length} 个:`)
+          for (const w of warned) for (const n of w.notes) lines.push(`· ${w.id}: ${n}`)
+        }
+        const off = scan.skills.filter(s => skillState(s, disabled) === 'disabled').map(s => s.id)
+        if (off.length) lines.push(`已禁用: ${off.join('、')}`)
+        if (!scan.unreadable.length && !scan.conflicts.length && !warned.length) {
+          lines.push('没有读不出来或撞名的技能。')
+        }
+        return lines.join('\n')
+      }
+      case 'fetch_article': {
+        const url = String(args.url || '').trim()
+        // **严格白名单，不是 denylist**：只认 https 的 mp.weixin.qq.com。
+        // 这条比 read_favorite 那条严，因为那里的链接是用户自己收藏的，这里的 URL 是别人给的。
+        if (!isAllowedWeChatArticleUrl(url)) {
+          return `(只接受 https 的 mp.weixin.qq.com 文章链接，拒绝抓取: ${url.slice(0, 60)})`
+        }
+        const maxChars = boundedToolInteger(args.max_chars, 3000, 6000)
+        // 逐跳复检：一次 302 就能把入口白名单绕过去
+        const { status, html } = await fetchArticleHtml(url,
+          { maxRedirects: 3, allowHop: isAllowedWeChatArticleUrl })
+        if (!html) return `(抓取失败 HTTP ${status} —— 链接可能不是公众号文章，或者跳转到了别处)`
+        if (html.includes('已被发布者删除')) return '(这篇文章已被发布者删除)'
+        const body = articleTextFromHtml(html, maxChars)
+        if (!body.trim() || (body.match(/[一-鿿]/g) || []).length < 20) {
+          return '(抓到了页面但取不出正文——可能是验证页，或者这篇文章要登录/已失效)'
+        }
+        const title = html.match(/<meta[^>]*property="og:title"[^>]*content="([^"]+)"/i)?.[1]
+          || html.match(/<title>([^<]+)<\/title>/i)?.[1]?.trim() || ''
+        const author = html.match(/var\s+nickname\s*=\s*"([^"]+)"/i)?.[1]
+          || html.match(/<meta[^>]*property="og:article:author"[^>]*content="([^"]+)"/i)?.[1] || ''
+        // 配图只报数量与前几个链接：正文是纯文本，但图往往就是这篇文章的要点
+        const imgs = [...html.matchAll(/data-src="(https?:\/\/[^"]+)"/g)].map(m => m[1]).slice(0, 5)
+        const head = [title && `标题: ${title}`, author && `公众号: ${author}`].filter(Boolean).join(' | ')
+        const tail = imgs.length ? `\n\n配图 ${imgs.length} 张(前几张):\n${imgs.map(u => `· ${u}`).join('\n')}` : ''
+        return (head ? `${head}\n---\n` : '') + body + tail
+      }
+      case 'search_public': {
+        const keyword = String(args.keyword || '').trim()
+        if (!keyword) return '(参数错误: 缺少 keyword)'
+        const limit = boundedToolInteger(args.limit, 8, 20)
+        let html = ''
+        try {
+          const resp = await fetch(
+            `https://weixin.sogou.com/weixin?type=2&query=${encodeURIComponent(keyword)}`,
+            {
+              headers: {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+                'Referer': 'https://weixin.sogou.com/',
+                'Accept': 'text/html',
+                'Accept-Language': 'zh-CN,zh;q=0.9',
+              },
+              signal: AbortSignal.timeout(20_000),
+            },
+          )
+          html = await readTextLimited(resp, 2 * 1024 * 1024)
+        } catch {
+          return '(搜索失败——检查网络，或者稍后再试（第三方搜索页会限流）)'
+        }
+        const grab = (re: RegExp, clean: (s: string) => string): string[] => {
+          const out: string[] = []
+          for (const m of html.matchAll(re)) {
+            const v = clean(m[1])
+            if (v) out.push(v)
+          }
+          return out
+        }
+        const titles = grab(/<h3[^>]*>\s*<a[^>]*>(.*?)<\/a>\s*<\/h3>/gs,
+          s => s.replace(/<em[^>]*>/g, '').replace(/<\/em>/g, '').replace(/<!--[^>]*-->/g, '').trim())
+        const accounts = grab(/<span[^>]*class="[^"]*all-time-y2[^"]*"[^>]*>(.*?)<\/span>/gs,
+          s => s.replace(/<[^>]+>/g, '').trim())
+        const descs = grab(/<p[^>]*class="[^"]*txt-info[^"]*"[^>]*>(.*?)<\/p>/gs,
+          s => s.replace(/<[^>]+>/g, '').replace(/&hellip;/g, '…').replace(/&rarr;/g, '→').replace(/&mdash;/g, '—').trim())
+          .filter(d => d.length > 10)
+        const count = Math.max(titles.length, accounts.length, descs.length)
+        if (!count) {
+          return `(没搜到与「${keyword}」相关的公开文章。换个说法、或加上公众号名试试；`
+            + '找到链接后可以用 fetch_article 抓全文)'
+        }
+        const rows: string[] = []
+        for (let i = 0; i < Math.min(count, limit); i++) {
+          rows.push(`${i + 1}. ${titles[i] || '(未知标题)'}\n   公众号: ${accounts[i] || '(未知)'}`
+            + (descs[i] ? `\n   ${descs[i]}` : ''))
+        }
+        return `公开文章里搜「${keyword}」，命中 ${Math.min(count, limit)} 条:\n`
+          + rows.join('\n')
+          + '\n（这是第三方搜索页的标题与摘要，不是全文；要正文用 fetch_article 抓）'
+      }
+      case 'set_todo_status': {
+        const status = String(args.status || '')
+        if (status !== 'done' && status !== 'pending') return '(参数错误: status 只能是 done（已完成）或 pending（取消完成）)'
+        const id = String(args.id || '').trim()
+        const task = String(args.task || '').trim()
+        if (!id && !task) return '(参数错误: 要给 id 或 task 指到哪一条待办)'
+        let target = id
+        if (!target) {
+          // 按任务文字找：**只认唯一**。命中 0 条或 ≥2 条都拒绝——
+          // 猜错条目比拒绝更糟（用户会以为自己的待办被改了，而改的是另一条）
+          const listed = await runPythonJson<any>('extract_todos.py', ['list', '--json'])
+          if (!listed.ok) return fail('待办读取失败', listed)
+          const items: any[] = Array.isArray(listed.data) ? listed.data : (listed.data?.items || [])
+          const norm = (s: unknown) => String(s || '').replace(/\s+/g, '')
+          const hit = items.filter(t => norm(t.task).includes(norm(task)))
+          if (!hit.length) return `(没有任务文字包含「${task}」的待办)`
+          if (hit.length > 1) {
+            return `(「${task}」匹配到 ${hit.length} 条待办，不能确定是哪一条，请用 id 指定:\n`
+              + hit.slice(0, 5).map(t => `· ${t.task}`).join('\n') + ')'
+          }
+          if (!hit[0].id) return '(这条待办没有 id——本机的待办文件格式比预期旧，请在电脑上用 `todos done` 处理)'
+          target = String(hit[0].id)
+        }
+        const r = await runPythonJson<any>('extract_todos.py',
+          [status === 'done' ? 'done' : 'undone', target, '--json'])
+        if (!r.ok) return fail(status === 'done' ? '标记完成失败' : '取消完成失败', r)
+        // 括号开头 = "没有产出内容"（本仓的约定，见 producedContent）：这条只报告动作做成了
+        return status === 'done' ? `(已标记完成: ${target})` : `(已取消完成标记: ${target})`
+      }
+      default:
+        return `(未知工具: ${name})`
+    }
+  } catch (error) {
+    if (error instanceof ToolInputError) return `(参数错误: ${error.message})`
+    return '(工具执行失败，请检查本地配置或运行状态)'
+  }
+}