weflow-cli 1.6.4 → 1.8.0

package/bin/weflow-cli.ts

@@ -5,6 +5,8 @@ import inquirer from 'inquirer'
 import { basename, join } from 'path'
 import { existsSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
+import { SYNC_SCHEMA, SYNC_SOURCE, syncStateStore } from '../src/services/syncState.js'
+import { SyncRangeRequiredError, runSync } from '../src/services/syncService.js'
 import { dbPathService } from '../src/core/dbPathService.js'
 import { keyService } from '../src/core/keyService.js'
 import { NtCore } from '../src/core/ntCore.js'
@@ -316,8 +318,41 @@ program
         dailyStats: { cli: 'daily-stats --json' },
         diagnostics: { cli: 'check --json' },
         todos: { cli: 'todos list --json' },
+        awaiting: {
+          cli: 'awaiting --yes',
+          preview: 'awaiting --dry-run --json',
+          readsLocalChat: true,
+          invokesAI: true,
+          writesNothing: true,
+          confirmationRequired: true,
+        },
+        draft: {
+          cli: 'draft <会话> --yes --json',
+          preview: 'draft <会话> --dry-run --json',
+          readsLocalChat: true,
+          invokesAI: true,
+          // **它不发送任何东西**：只产出候选文本，回不回由人决定。
+          // 这条要能被机器读到——`sendsNothing` 比 `writesNothing` 更要紧。
+          writesNothing: true,
+          sendsNothing: true,
+          confirmationRequired: true,
+        },
         knowledge: { cli: 'search <query> --yes --json', preview: 'search <query> --dry-run --json', output: 'json', mcp: 'wechat.search_articles' },
       },
+      primitives: {
+        decide: {
+          cli: 'decide --request <file> --yes | decide --over <glob> --ask <text> --yes',
+          preview: 'decide --dry-run',
+          // 两条路的读法**不一样**，所以不能只写一个 false：
+          // --request 完全由调用方给，--over 会读匹配到的本地文件。
+          readsLocalData: { request: false, over: true },
+          invokesAI: true,
+          sendsCallerProvidedState: true,
+          confirmationRequired: true,
+          mcpExposed: false,
+          whyNotMcp: 'an MCP client must not be able to drive local outbound calls',
+        },
+      },
       workflows: {
         initialization: {
           preview: 'init --dry-run --json',
@@ -327,6 +362,26 @@ program
           previewExposesPaths: false,
         },
         evidencePackage: { cli: 'evidence <talker> --json --non-interactive', localOnly: true },
+        sync: {
+          preview: 'sync run <talker> --dry-run --json',
+          execute: 'sync run <talker> --yes --json',
+          status: 'sync status [<talker>] --json',
+          verify: 'sync verify <talker> --json',
+          confirmationRequired: true,
+          readsLocalData: true,
+          invokesAI: false,
+          sideEffects: ['local-checkpoint-file'],
+          stateSchema: 'weflow-sync/v1',
+          jobSchema: 'weflow-job/v1',
+          stateLocation: 'local-user-config-dir',
+          previewResolvesTalker: false,
+          previewExposesLocalPaths: false,
+          // D-027: a stable cursor must be backed by every database backend
+          // before it is advertised. This exposes overlapping windows only.
+          stableCursor: false,
+          coverageValues: ['complete', 'unverified', 'partial'],
+          partialCompletesSuccessfully: false,
+        },
         aiAnalysis: {
           preview: 'evidence-review <talker> --dry-run --json',
           execute: 'evidence-review <talker> --yes --json',
@@ -370,6 +425,17 @@ program
           execute: 'assistant <start|stop> --yes --json',
           confirmationRequired: true,
         },
+        localPanel: {
+          status: 'panel --status --json',
+          ask: 'panel --ask "<text>" --yes --json',
+          preview: 'panel --dry-run --json',
+          execute: 'panel --yes --json',
+          confirmationRequired: true,
+          opensLocalWindow: true,
+          loopbackOnly: true,
+          // 关掉窗口**不会**停掉助手——这件事必须能被机器读到，别让调用方以为退出即结束
+          keepsAssistantRunningAfterClose: true,
+        },
         messageChannelAuthentication: {
           loginPreview: 'login-wechat --dry-run --json',
           loginExecute: 'login-wechat --yes',
@@ -499,7 +565,28 @@ program
         aiDisabledByDefaultForExport: true,
         unknownMessageTypesPreserved: true,
         nonInteractiveTalkerResolution: true,
-        mcpDefaultReadOnly: true,
+        // **这个名字曾经是假的**：MCP 那张表不是手写的只读清单，而是**助手工具表减去
+        // save_memory**，所以里面早就有写文件的 `export_chat` 和会把图片交给模型的
+        // `look_at_image`。如实改成 false，并把真正有出境的几样单独列出来（下面这个对象）。
+        // 读这一位的调用方按 false 走保守分支即可。
+        mcpDefaultReadOnly: false,
+        mcpSurface: {
+          // 原文只写了 "minus save_memory" —— 而那张表也排除了 `look_at_image`（MCP 只取文本，
+          // 它挂进侧信道的图没人接）。机器可读字段少说一句同样算不准，如实写全。
+          derivedFrom: 'assistant tools minus save_memory and look_at_image',
+          writesFiles: ['export_chat'],
+          // 逐个核实过（脚本里确实调云端模型的那些）：
+          // who_owes_reply/search_chats → Jev；search_semantic → 阿里云百炼嵌入 + Jev 重排；draft_reply → Jev + DeepSeek。
+          // `look_at_image` **不在这里**：它靠侧信道把图交给助手自己的模型，而 MCP 只取工具返回的文本，
+          // 图没人接、回话却写着"你能看到它了"——所以它已经从 MCP 那张表里排除了（见 MCP_TOOL_DEFS）。
+          callsCloudModels: ['who_owes_reply', 'search_chats', 'search_semantic', 'draft_reply'],
+          // 机器调用**默认只给预览**、必须显式 confirm 才出境的那些（MCP 独有的边界）。
+          // **这里是四个，不是"只有 draft_reply"**：逐个读 handler 才发现那四个工具里
+          // 写的是同一句 `if (ctx.requiresConfirm && args.confirm !== true)`（1010/1041/1094/1170）。
+          // 原先只列了 draft_reply，而测试是照着这个字段的值抄的，于是两处一起错、谁都没红。
+          // 现在测试改成**从源码里数**（见 test/assistant-tools.test.ts），改一处不同步就会红。
+          requiresConfirm: ['search_chats', 'who_owes_reply', 'draft_reply', 'search_semantic'],
+        },
         mcpMessageLimit: { default: 100, max: 1000 },
       },
     }
@@ -919,9 +1006,13 @@ const configCmd = program
 const configurableKeys = [
   'dbPath', 'decryptKey', 'dbPath3x', 'decryptKey3x', 'dataVersion', 'wxid',
   'ntDbPath', 'ntKey', 'ntSalt', 'contactDbPath', 'contactKey', 'contactSalt',
-  'vaultRepo', 'aiEngine', 'aiBaseUrl', 'aiModel', 'deepseekApiKey', 'wereadApiKey',
+  'vaultRepo', 'aiEngine', 'aiBaseUrl', 'aiModel', 'deepseekApiKey', 'typesafeApiKey',
+  'dashscopeApiKey', 'favPassphrase',
+  'wereadApiKey',
   'assistantPrivacy', 'assistantWhitelist', 'assistantGroupWhitelist',
-  'assistantGroupRequireMention', 'dailySources', 'dailySourceCategories', 'dailyAiEnabled',
+  'assistantGroupRequireMention', 'assistantFastRoute', 'assistantPanelUser', 'quickReplyContacts',
+  'dailySources', 'dailySourceCategories',
+  'dailyExcludeTopics', 'dailyAiEnabled',
   'emoticonSeed',
 ] as const
 
@@ -1010,6 +1101,7 @@ configCmd
     console.log(`微信账号: ${config.wxid || chalk.gray('(未设置)')}`)
     console.log(`公众号日报来源: ${configService.get('dailySources') || chalk.gray('(全部公众号)')}`)
     console.log(`公众号日报 AI: ${configService.get('dailyAiEnabled') === 'false' ? '已关闭' : '已开启'}`)
+    console.log(`公众号日报排除主题: ${configService.get('dailyExcludeTopics') || chalk.gray('(不排除)')}`)
   })
 
 configCmd
@@ -1237,6 +1329,296 @@ program
     }
   })
 
+// ==================== sync ====================
+// 增量同步检查点。契约见 docs/SYNC_CONTRACT.md, 边界见 D-029。
+// 不宣称「稳定游标」: D-027 要求它在所有后端支持前不得对外宣称,
+// 这里只做重叠时间窗 + 本地去重。
+const syncCmd = program.command('sync').description('本地消息同步检查点（重叠窗口读取与覆盖报告）')
+
+syncCmd
+  .command('run <talker>')
+  .description('执行一次同步并写入检查点')
+  .option('--since <date>', '起始日期或 ISO 时间（首次运行需要）')
+  .option('--full', '读取全部历史（首次运行需要；耗时可能较长）')
+  .option('--overlap <seconds>', '重叠窗口秒数', '300')
+  .option('-n, --limit <number>', '本次最多读取条数（0=不限）', '0')
+  .option('--dry-run', '仅预览，不读取消息、不写状态')
+  .option('--yes', '确认执行')
+  .option('--json', '输出机器可读结果')
+  .option('--non-interactive', '禁止交互确认')
+  .action(async (talker: string, opts) => {
+    const overlap = parseCliInteger(opts.overlap, 'overlap', 0, 86400, !!opts.json)
+    const limit = parseCliInteger(opts.limit, 'limit', 0, 1_000_000, !!opts.json)
+
+    let since: number | undefined
+    if (opts.since) {
+      try {
+        since = parseLocalDateOrIso(opts.since)
+      } catch (error) {
+        const message = error instanceof DateRangeError ? error.message : '日期格式无效'
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_DATE', error: message })); process.exit(1) }
+        console.error(chalk.red(`✗ ${message}`))
+        process.exit(1)
+      }
+    }
+    if (opts.full && since !== undefined) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '--since 与 --full 不能同时使用' })); process.exit(1) }
+      console.error(chalk.red('✗ --since 与 --full 不能同时使用'))
+      process.exit(1)
+    }
+
+    // Preview deliberately does not resolve the talker: that reads the
+    // database, and a preview must not touch local data (D-025).
+    const prior = (() => {
+      try { return syncStateStore.read(SYNC_SOURCE, talker) } catch { return null }
+    })()
+    const preview = {
+      success: true,
+      dryRun: true,
+      action: 'sync.run',
+      schema: SYNC_SCHEMA,
+      source: SYNC_SOURCE,
+      talkerResolved: false,
+      hasCheckpoint: !!prior,
+      window: {
+        from: since ?? prior?.checkpoint.newestCreateTime ?? null,
+        overlapSeconds: overlap,
+        full: !!opts.full,
+      },
+      estimatedRecords: prior?.recordsRead ?? null,
+      readsLocalChat: true,
+      writesLocalState: true,
+      stableCursor: false,
+    }
+
+    if (opts.dryRun) {
+      if (opts.json) console.log(JSON.stringify(preview))
+      else {
+        console.log(chalk.cyan('\n同步预览'))
+        console.log(chalk.gray(`  范围: ${opts.full ? '全部历史' : since ? new Date(since * 1000).toLocaleString() : '上次检查点'}`))
+        console.log(chalk.gray(`  重叠窗口: ${overlap} 秒`))
+        console.log(chalk.gray('  将读取本地聊天记录并写入同步检查点，不调用 AI。\n'))
+      }
+      return
+    }
+
+    if (!opts.yes) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ...preview, success: false, dryRun: false, code: 'CONFIRMATION_REQUIRED' }))
+        process.exit(1)
+      }
+      if (opts.nonInteractive) {
+        console.error(chalk.red('✗ 非交互模式需要 --yes'))
+        process.exit(1)
+      }
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: opts.full
+          ? '将读取该会话的全部历史消息，可能耗时数分钟。继续吗？'
+          : '将读取指定范围内的消息并写入本地同步检查点。继续吗？',
+        default: false,
+      }])
+      if (!confirmed) {
+        console.log(chalk.gray('已取消'))
+        return
+      }
+    }
+
+    if (!configService.isConfigured()) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'NOT_INITIALIZED', error: '未完成初始化' })); process.exit(1) }
+      console.error(chalk.red('✗ 未完成初始化，请先运行 weflow-cli init'))
+      process.exit(1)
+    }
+
+    let resolvedTalker = ''
+    try {
+      resolvedTalker = await resolveTalkerCore(talker, { interactive: !opts.nonInteractive })
+    } catch {
+      resolvedTalker = ''
+    }
+    if (!resolvedTalker) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '未找到该会话' })); process.exit(1) }
+      console.error(chalk.red('✗ 未找到该会话'))
+      process.exit(1)
+    }
+    // A display name is nicety only; the state is keyed by the resolved id.
+    let displayName = resolvedTalker
+    try {
+      const match = (await chatService.listSessions()).find(s => s.username === resolvedTalker)
+      if (match?.displayName && match.displayName !== resolvedTalker) displayName = match.displayName
+    } catch { /* keep the id */ }
+
+    try {
+      const result = await runSync(resolvedTalker, {
+        since, full: !!opts.full, overlapSeconds: overlap, limit,
+        scope: displayName,
+        read: (who, howMany, from) => chatService.getMessagesWithShards(who, howMany, 0, from),
+      })
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: result.success,
+          ...(result.code ? { code: result.code } : {}),
+          action: result.action,
+          schema: SYNC_SCHEMA,
+          source: SYNC_SOURCE,
+          scope: result.scope,
+          talker: resolvedTalker,
+          window: result.window,
+          recordsRead: result.recordsRead,
+          recordsDeduplicated: result.recordsDeduplicated,
+          recordsReturned: result.recordsReturned,
+          shards: result.shards,
+          coverage: result.coverage,
+          mayHaveMore: result.mayHaveMore,
+          partial: result.partial,
+          warnings: result.warnings,
+          jobId: result.jobId,
+        }))
+        if (!result.success) process.exit(1)
+        return
+      }
+      const mark = result.coverage === 'complete' ? '✓' : result.coverage === 'unverified' ? '!' : '✗'
+      console.log(chalk.green(`\n${mark} 同步完成: ${result.recordsReturned}/${result.recordsRead} 条（去重 ${result.recordsDeduplicated}）`))
+      console.log(chalk.gray(`  覆盖: ${result.coverage}  ·  分片: ${result.shards?.opened ?? '?'} 读 / ${result.shards?.failed ?? 0} 失败`))
+      for (const warning of result.warnings) console.log(chalk.yellow(`  ⚠ ${warning}`))
+      if (result.partial) {
+        console.log(chalk.yellow('  本次为部分完成，未推进成功时间；用 sync status 查看详情。'))
+      }
+      console.log('')
+      if (!result.success) process.exit(1)
+    } catch (error: any) {
+      if (error instanceof SyncRangeRequiredError) {
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_RANGE_REQUIRED', error: error.message })); process.exit(1) }
+        console.error(chalk.red(`✗ ${error.message}`))
+        process.exit(1)
+      }
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_FAILED', error: '同步失败' })); process.exit(1) }
+      console.error(chalk.red(`✗ 同步失败: ${error?.message || error}`))
+      process.exit(1)
+    }
+  })
+
+syncCmd
+  .command('status [talker]')
+  .description('查看同步检查点与最近任务')
+  .option('--json', '输出 JSON 格式')
+  .action(async (talker: string | undefined, opts) => {
+    // No database access: this has to work while the database is locked.
+    let states: any[] = []
+    try { states = syncStateStore.list() } catch { states = [] }
+    const lastJob = syncStateStore.recentJobs(1)[0] ?? null
+
+    if (talker) {
+      const match = states.find(s => s.talker === talker || s.scope === talker)
+      if (!match) {
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_STATE_NOT_FOUND', error: '没有该会话的同步记录' })); process.exit(1) }
+        console.error(chalk.red('✗ 没有该会话的同步记录'))
+        process.exit(1)
+      }
+      if (opts.json) { console.log(JSON.stringify({ success: true, schema: SYNC_SCHEMA, state: match, lastJob })); return }
+      console.log(chalk.cyan(`\n同步记录 — ${match.scope}`))
+      console.log(chalk.gray(`  覆盖: ${match.coveredFrom || '—'} ~ ${match.coveredTo || '—'}`))
+      console.log(chalk.gray(`  可信度: ${match.coverage}  ·  分片 ${match.shardsRead} 读 / ${match.shardsFailed} 失败`))
+      console.log(chalk.gray(`  上次成功: ${match.lastSuccessfulRun || '—'}  ·  上次尝试: ${match.lastAttempt || '—'}\n`))
+      return
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        success: true,
+        schema: SYNC_SCHEMA,
+        stableCursor: false,
+        scopes: states.map(s => ({
+          source: s.source, scope: s.scope, talker: s.talker,
+          lastSuccessfulRun: s.lastSuccessfulRun, lastAttempt: s.lastAttempt,
+          coveredFrom: s.coveredFrom, coveredTo: s.coveredTo,
+          recordsRead: s.recordsRead, recordsDeduplicated: s.recordsDeduplicated,
+          coverage: s.coverage, shardsRead: s.shardsRead, shardsFailed: s.shardsFailed,
+          mayHaveMore: s.mayHaveMore, warnings: s.warnings,
+        })),
+        lastJob,
+      }))
+      return
+    }
+    if (!states.length) {
+      console.log(chalk.gray('\n还没有任何同步记录。首次运行: weflow-cli sync run <会话> --since <日期>\n'))
+      return
+    }
+    console.log(chalk.cyan(`\n同步记录 (${states.length} 个会话):\n`))
+    for (const s of states) {
+      const mark = s.coverage === 'complete' ? '✓' : s.coverage === 'unverified' ? '!' : '✗'
+      console.log(`  ${mark} ${s.scope}  ${chalk.gray(`${s.coveredFrom || '—'} ~ ${s.coveredTo || '—'}  分片 ${s.shardsRead}/${s.shardsFailed} 失败`)}`)
+    }
+    console.log('')
+  })
+
+syncCmd
+  .command('verify <talker>')
+  .description('核对检查点与当前数据的边界')
+  .option('--json', '输出 JSON 格式')
+  .action(async (talker: string, opts) => {
+    // Read-only: it writes nothing, so it needs no confirmation - the same
+    // posture as `messages`.
+    if (!configService.isConfigured()) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'NOT_INITIALIZED', error: '未完成初始化' })); process.exit(1) }
+      console.error(chalk.red('✗ 未完成初始化'))
+      process.exit(1)
+    }
+    let state: any = null
+    try { state = syncStateStore.read(SYNC_SOURCE, talker) } catch { state = null }
+    if (!state) state = syncStateStore.list().find(s => s.scope === talker) ?? null
+    if (!state) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_STATE_NOT_FOUND', error: '没有该会话的同步记录' })); process.exit(1) }
+      console.error(chalk.red('✗ 没有该会话的同步记录'))
+      process.exit(1)
+    }
+
+    const checks: Array<Record<string, unknown>> = [{ name: 'checkpoint-present', ok: true }]
+
+    // Re-read and compare. This is the count summary of §4.4 in the absence
+    // of a local index.
+    const read = await chatService.getMessagesWithShards(state.talker, 0, 0)
+    const fromSeconds = state.coveredFrom ? Math.floor(Date.parse(state.coveredFrom) / 1000) : null
+    const inWindow = fromSeconds === null
+      ? read.messages
+      : read.messages.filter(m => Number(m.createTime) >= fromSeconds)
+    checks.push({ name: 'window-re-readable', ok: inWindow.length > 0, returned: inWindow.length })
+
+    const newest = read.messages.length
+      ? Math.max(...read.messages.map(m => Number(m.createTime) || 0))
+      : null
+    checks.push({
+      name: 'newest-message-present',
+      ok: newest !== null && newest >= (state.checkpoint?.newestCreateTime ?? 0),
+      recorded: state.checkpoint?.newestCreateTime ?? null,
+      observed: newest,
+    })
+
+    if (read.shards) {
+      checks.push({ name: 'shards-readable', ok: read.shards.failed === 0,
+                    scanned: read.shards.scanned, failed: read.shards.failed })
+    } else {
+      // Neither a pass nor a failure: this backend simply cannot say.
+      checks.push({ name: 'shards-readable', ok: true, skipped: true,
+                    reason: 'backend-does-not-report-shards' })
+    }
+
+    const success = checks.every(c => c.ok || c.skipped)
+    if (opts.json) {
+      console.log(JSON.stringify({ success, schema: SYNC_SCHEMA, scope: state.scope, coverage: state.coverage, checks }))
+      if (!success) process.exit(1)
+      return
+    }
+    console.log(chalk.cyan(`\n核对 — ${state.scope}\n`))
+    for (const check of checks) {
+      const mark = check.skipped ? '–' : check.ok ? '✓' : '✗'
+      console.log(`  ${mark} ${check.name}${check.skipped ? chalk.gray(` (跳过: ${check.reason})`) : ''}`)
+    }
+    console.log('')
+    if (!success) process.exit(1)
+  })
+
 // ==================== contacts ====================
 program
   .command('contacts')
@@ -1654,12 +2036,26 @@ program
       process.exit(1)
     }
     if (!opts.yes) {
-      const { confirmed } = await inquirer.prompt([{
-        type: 'confirm',
-        name: 'confirmed',
-        message: token ? '已有登录状态，确认启动重新登录吗？' : '确认启动人工扫码登录吗？',
-        default: false,
-      }])
+      // stdin 不是终端时（管道、计划任务、会话里的 `!` 前缀执行）inquirer 会抛 ExitPromptError——
+      // 屏幕上是一条堆栈而不是一句话。这里把它变成解释：扫码登录必须在真实终端里跑。
+      // 与守护进程那条 `--yes` 是同一类毛病：交互确认被塞进一个没人能回答的 stdin。
+      let confirmed = false
+      try {
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: token ? '已有登录状态，确认启动重新登录吗？' : '确认启动人工扫码登录吗？',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+      } catch (error: any) {
+        if (error?.name === 'ExitPromptError' || /force closed the prompt/.test(String(error?.message))) {
+          console.log(chalk.yellow('当前环境没有可交互的终端。扫码登录必须在真实终端窗口里执行，'))
+          console.log(chalk.yellow('或者加 --yes 跳过这个确认（扫码那一步仍然要人来做）。'))
+          process.exit(1)
+        }
+        throw error
+      }
       if (!confirmed) {
         console.log(chalk.gray(token ? '保持当前登录状态' : '已取消'))
         return
@@ -1687,6 +2083,20 @@ program
       if (session.status === 'confirmed') {
         console.log(chalk.green('\n✓ 登录成功!'))
         console.log(chalk.gray('  消息通道登录状态已安全保存'))
+        // 助手的白名单为空时**拒绝所有人**：登录完对着自己的机器人说话，什么都不会回来。
+        // 所以这里必须说清"下一步该干什么"。
+        // 只打在人看的这条路上——`--json` 那条路照旧不返回账号标识。
+        console.log('')
+        console.log(chalk.cyan('  助手默认拒绝所有人（白名单为空）。'))
+        // 这里**不**替用户写白名单：登录响应给的是 ilink_user_id，而白名单要的是入站消息里
+        // 那个 from_user_id（文档里写成 <@im.wechat ID>），两者是不是同一个值**没有被验证过**
+        // ——猜错的后果是"白名单非空、看着配好了、却仍然拒你"。真值在第一条被拒的消息里，
+        // 所以让它自己现形（见 assistant log 的 [首次配置] 那行）。
+        console.log(chalk.gray('  启用方式：先 assistant start，从你的微信给机器人发一条消息，'))
+        console.log(chalk.gray('  日志里会出现一行 ' + chalk.cyan('[首次配置]')
+          + chalk.gray(' 带着你自己的发送者 ID 和该执行的命令。')))
+        console.log(chalk.gray('  只想先看它「本来会怎么答」而不改行为：')
+          + chalk.cyan('weflow-cli config set assistantFastRoute log'))
       } else {
         console.log(chalk.red(`\n✗ 登录失败: ${session.error || '超时'}`))
       }
@@ -3178,13 +3588,18 @@ program
             '005_Reference/Tools',
             '005_Reference/Methods',
             '006_Projects',
-            '007_Wiki/Concepts',
+            // 这里原先还有 `007_Wiki/Concepts`：概念页实际写在下面的顶层 `Wiki/Concepts`
+            // （`compile_wiki` 的 OUTPUT_ROOT）。两个都列，就建出一个永远空着的目录。
             '008_MOC',
             '999_Archive',
             '_attachments',
+            // `Wiki/Concepts` 是唯一真的有人写的 Wiki 子目录（`compile_wiki` 的
+            // OUTPUT_ROOT）。这里曾经还列着 `Wiki/Entities` 与 `Wiki/Topics`——没有任何
+            // 代码写它们，README 里那张表却把它们当成已有的介绍给用户。**声明了就要有东西
+            // 往里写**，否则就是又一个"永远空着的目录"（同 `007_Wiki`）。
+            // 两个知识库各一个目录：`Wiki/Concepts` 是公众号文章线的，`Chat/Concepts` 是聊天线的
             'Wiki/Concepts',
-            'Wiki/Entities',
-            'Wiki/Topics',
+            'Chat/Concepts',
           ]
           const files = [
             {
@@ -3192,7 +3607,10 @@ program
               content: JSON.stringify({
                 newFileLocation: 'folder',
                 newFileFolderPath: 'Sources',
-                attachmentFolderPath: 'Assets',
+                // **`_attachments`，不是 `Assets`**：布局里建的就是 `_attachments`（这个
+                // 字面量以前只在这里出现一次，是个孤例），而 init 从不建 `Assets`——
+                // 于是附件会被 Obsidian 放进一个不存在的目录。
+                attachmentFolderPath: '_attachments',
                 showInlineTitle: false,
               }, null, 2),
             },
@@ -3238,11 +3656,20 @@ program
                 '',
                 '| 目录 | 说明 |',
                 '|------|------|',
-                '| `Sources/WeChat/` | 公众号文章（按日期+主题分类） |',
-                '| `Wiki/Concepts/` | 概念页（手动或 AI 生成） |',
-                '| `Wiki/Entities/` | 实体页（公众号、作者等） |',
-                '| `Wiki/Topics/` | 主题总览页 |',
+                '| `Sources/WeChat/<日期>/` | 原始文章（`daily` 与回填写入，连同正文图片） |',
+                '| `001_Daily/<日期>.md` | 每天一页日记 |',
+                '| `002_Literature/WeChat/<日期>/` | 阅读笔记（由 `Sources` 生成） |',
+                // **两个知识库各写一行**：文章线（`Wiki/`）与聊天线（`Chat/`）是分开的两套，
+                // 只列文章那套的话，用户在库里看到的说明与他实际拥有的东西对不上。
+                '| `Wiki/Concepts/`、`Wiki/00-Overview.md` | **文章知识库**的概念页与索引（`wiki compile` 生成） |',
+                '| `Chat/Concepts/`、`Chat/00-Overview.md` | **聊天知识库**的概念页与索引（`wiki compile --source output/chat-notes` 生成） |',
+                '| `Sources/Chat/会话-<名字>.md` | 每个会话一张知识卡（`chat` 生成：聊了什么、有哪些人、欠着什么） |',
                 '| `Templates/` | 模板文件 |',
+                '| `_attachments/` | Obsidian 附件（`.obsidian/app.json` 的 `attachmentFolderPath` 指向这里） |',
+                '| `000_Inbox` `003_Ideas` `004_Permanent` `005_Reference` `006_Projects` `008_MOC` `999_Archive` | **给你自己写笔记用的层**：`vault promote` 才会往里放东西，空着是设计而不是没做完 |',
+                '',
+                '> 阅读笔记与日记里各有一段 `dataview` 查询，所以这个 Vault 需要 **Dataview 社区插件**',
+                '> （社区插件不进仓库，换机器要自己装一次）。',
                 '',
                 '## 快速查询',
                 '',
@@ -3359,9 +3786,13 @@ program
       new Command('compile')
         .description('扫描文章 [[Wikilinks]] 聚合生成概念页')
         .option('-l, --limit <n>', '最多生成概念数', '20')
-        .option('--source <dir>', '文章目录', './output/biz-daily')
+        .option('--min-refs <n>', '至少被几篇材料提到才建页（2 能滤掉新闻里的一次性实体）', '1')
+        .option('--source <dir>', '材料目录（**必须含 [[概念]] — 说明 形状的链接**，否则聚合不出任何概念）', './output/biz-daily')
         .option('-o, --output <dir>', '概念页输出目录', './output/wechat-vault/Wiki/Concepts')
         .option('--api-key <key>', 'DeepSeek API key')
+        .option('--refresh-sources',
+                '只把已有概念页的"来源"段补齐成当前全部来源（本地重写，**不调用模型**）')
+        .option('--cards <dir...>', '产卡目录，可写多个；默认所有 output/*-notes（与索引的引用数同一口径）')
         .option('--dry-run', '仅预览，不读取文章、调用 AI 或写入概念页')
         .option('--yes', '确认调用 AI 并生成概念页')
         .option('--json', '输出机器可读结果，不返回概念或本地路径')
@@ -3369,13 +3800,32 @@ program
           const pkgRoot = resolvePackageRoot()
           const script = join(pkgRoot, 'scripts', 'compile_wiki.py')
 
+          if (opts.refreshSources) {
+            // 本地补来源：**不调模型**，所以不传 apiKey、preview 里也不说"调用 AI"。
+            // 但它会把已有页重写一遍（实测会动 358 张），照样走"先预览、再确认"那两步。
+            await runConfirmedPythonMutation({
+              action: 'wiki.refreshSources',
+              script,
+              args: ['--refresh-sources', '--output', opts.output,
+                     ...(opts.cards ?? []).flatMap((c: string) => ['--cards', c])],
+              cliOptions: opts,
+              preview: { readsLocalCards: true, rewritesExistingPages: true, usesAi: false },
+              confirmationMessage: `确认把 ${opts.output} 里已有概念页的"来源"段补齐？（本地重写，不调用 AI）`,
+              apiKey: opts.apiKey,
+              timeout: 300_000,
+            })
+            return
+          }
+
           const limit = parseCliInteger(opts.limit, 'limit', 1, 1000, opts.json)
+          const minRefs = parseCliInteger(opts.minRefs ?? '1', 'min-refs', 1, 50, opts.json)
           await runConfirmedPythonMutation({
             action: 'wiki.compile',
             script,
-            args: ['--limit', String(limit), '--source', opts.source, '--output', opts.output],
+            args: ['--limit', String(limit), '--source', opts.source, '--output', opts.output,
+                   '--min-refs', String(minRefs)],
             cliOptions: opts,
-            preview: { limit, readsLocalArticles: true, usesAi: true, writesConceptPages: true },
+            preview: { limit, minRefs, readsLocalArticles: true, usesAi: true, writesConceptPages: true },
             confirmationMessage: `确认调用 AI 并生成最多 ${limit} 个概念页？`,
             apiKey: opts.apiKey,
             timeout: 300_000,
@@ -3402,6 +3852,7 @@ program
         .option('--skip-html', '跳过 HTML 阅读器生成')
         .option('--skip-ai-report', '跳过 AI 深度阅读报告')
         .option('--no-ai', '关闭全部 AI 调用，保留抓取和本地输出')
+  .option('--no-summary', '只判断不生成：biz_daily 不调 LLM 写摘要/标签/简报（判断仍走 Jev）')
         .option('--ai-report-range <n>', 'AI 报告覆盖最近 N 天', '1')
         .option('--dry-run', '仅预览步骤，不读取聊天数据、调用网络或写入文件')
         .option('--yes', '确认运行流水线')
@@ -3484,6 +3935,7 @@ program
           if (opts.skipHtml) args.push('--skip-html')
           if (opts.skipAiReport) args.push('--skip-ai-report')
           if (noAi) args.push('--no-ai')
+          if (opts.noSummary && !noAi) args.push('--no-summary')
 
           try {
             if (!opts.json) console.log(chalk.cyan('\n启动端到端流水线...\n'))
@@ -4401,22 +4853,35 @@ program
     .description('构建语义搜索索引')
     .option('--full', '全量重建')
     .option('--api-key <key>', 'DashScope embedding API key')
+    .option('--days <n>', '聊天记录收最近多少天（默认 90）')
+    .option('--article-days <n>', '日报文章收最近多少个日期目录（默认 30）')
     .option('--dry-run', '仅预览，不读取数据库、调用网络或写入索引')
     .option('--yes', '确认构建或重建索引')
     .option('--json', '输出 JSON 格式')
     .action(async (opts) => {
+      // 窗口的**运行值由这里说了算**：默认值 + 校验 + 透传都在这一处，预览报的就是真跑的那些
+      // （脚本文档里另有自己的默认值，只供手动直接跑脚本时用；CLI 这条路永远显式传参，
+      // 所以两边万一漂了也不会影响实际行为）。
+      // 上限 36500 天≈100 年：不设上限的后果是"给个 1e9 就把遍历变成一次全库穿透"。
+      const chatDays = opts.days === undefined ? 90 : parseCliInteger(opts.days, 'days', 1, 36_500, opts.json)
+      const articleDays = opts.articleDays === undefined
+        ? 30 : parseCliInteger(opts.articleDays, 'article-days', 1, 36_500, opts.json)
+      const windowText = `聊天最近 ${chatDays} 天、日报最近 ${articleDays} 个日期目录`
       const preview = {
         success: true,
         dryRun: true,
         action: 'search-index.build',
         mode: opts.full ? 'full' : 'incremental',
+        chatDays,
+        articleDays,
         readsLocalData: true,
         usesCloudEmbedding: true,
         replacesExistingIndex: !!opts.full,
       }
       if (opts.dryRun) {
         if (opts.json) console.log(JSON.stringify(preview))
-        else console.log(chalk.cyan(`语义索引预览：${opts.full ? '全量重建' : '增量构建'}，将读取本地数据并调用向量服务`))
+        else console.log(chalk.cyan(`语义索引预览：${opts.full ? '全量重建' : '增量构建'}；`
+          + `窗口＝${windowText}（要改：--days / --article-days），将读取本地数据并调用向量服务`))
         return
       }
       if (!opts.yes) {
@@ -4427,7 +4892,10 @@ program
         const { confirmed } = await inquirer.prompt([{
           type: 'confirm',
           name: 'confirmed',
-          message: `确认${opts.full ? '全量重建' : '增量构建'}语义索引？本地文本将发送到已配置的向量服务。`,
+          // 窗口是**代价的一部分**：天数越多，发给向量服务的文本越多。所以确认语里要写出来，
+          // 而不是只说"本地文本将发送"。
+          message: `确认${opts.full ? '全量重建' : '增量构建'}语义索引（${windowText}）？`
+            + '这些文本将发送到已配置的向量服务。',
           default: false,
         }])
         if (!confirmed) {
@@ -4440,7 +4908,8 @@ program
       const execFileAsync = promisify(execFile)
     const pkgRoot = resolvePackageRoot()
       const script = join(pkgRoot, 'scripts', 'semantic_search.py')
-      const args: string[] = [script, 'build']
+      const args: string[] = [script, 'build', '--days', String(chatDays),
+                              '--article-days', String(articleDays)]
       if (opts.full) args.push('--full')
       try {
         const { stdout } = await execFileAsync(getPythonCommand(), args, {
@@ -4631,6 +5100,526 @@ program
       }
     })
 
+  // decide —— 本机判断层。一个 state + 一批类型化问题，一次调用。
+  // state 由调用方给，命令自己**不读任何本地数据**；但它是出境调用，所以照 awaiting/search
+  // 的规矩：--dry-run 只校验、--yes 才真跑。这一版**不暴露成 MCP 工具**——那会变成
+  // 远端 MCP 客户端能驱动本机往第三方发任意文本，属于要单独决策的出境面。
+  program
+    .command('decide')
+    .description('本机判断层：一个 state + 一批类型化问题，一次调用返回带概率的答案')
+    .option('--request <file>', '请求 JSON 的路径（含 state 与 questions）')
+    .option('--over <glob>', '批量模式：对匹配到的每个文件问 --ask 里的每个问题（可重复）',
+            (value: string, previous: string[]) => previous.concat([value]), [] as string[])
+    .option('--ask <text>', '批量模式下的一个是非题，逐文件展开（可重复）',
+            (value: string, previous: string[]) => previous.concat([value]), [] as string[])
+    .option('--max-chars <n>', '批量模式下每个文件喂多少字符（默认 1500；它决定上限）', '1500')
+    .option('--limit <n>', '批量模式最多取多少个文件（默认 50）', '50')
+    .option('--model <name>', '模型别名，默认 jev-latest')
+    .option('--dry-run', '只校验请求并回显形状，不调用决策模型')
+    .option('--yes', '确认把 state 发送到已配置的决策模型服务')
+    .option('--json', '输出机器可读结果（本命令的输出本来就是 JSON）')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const { readFileSync } = await import('fs')
+      const execFileAsync = promisify(execFile)
+      const pkgRoot = resolvePackageRoot()
+      const decideScript = join(pkgRoot, 'scripts', 'decide.py')
+
+      // 预览里要报"这批几个问题"，所以在这里读一眼；**校验仍然只由脚本做**，
+      // 免得两处校验逻辑各说各话。
+      // 两种输入方式：--request 一个文件、或 --over 批量展开。脚本自己会拒掉
+      // 两个都没给的情况，所以这里不做重复校验。
+      const batch = Array.isArray(opts.over) && opts.over.length > 0
+      let questionCount: number | null = null
+      if (batch) {
+        questionCount = opts.over.length * opts.ask.length || null
+      } else if (opts.request) {
+        try {
+          const parsed = JSON.parse(readFileSync(opts.request, 'utf8'))
+          if (parsed && typeof parsed === 'object' && parsed.questions
+              && typeof parsed.questions === 'object') {
+            questionCount = Object.keys(parsed.questions).length
+          }
+        } catch {
+          // 读不到或不是 JSON：交给脚本去报一个准确得多的错误。
+        }
+      }
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json)
+      const maxChars = parseCliInteger(opts.maxChars, 'max-chars', 1, 100000, opts.json)
+
+      const args = [decideScript,
+                    ...(batch
+                      ? [...opts.over.flatMap((g: string) => ['--over', g]),
+                         ...opts.ask.flatMap((a: string) => ['--ask', a]),
+                         '--max-chars', String(maxChars), '--limit', String(limit)]
+                      : ['--request', opts.request]),
+                    ...(opts.model ? ['--model', opts.model] : [])]
+      if (opts.dryRun) {
+        args.push('--dry-run')
+      } else if (!opts.yes) {
+        const preview = {
+          success: false, dryRun: false, action: 'decide',
+          code: 'CONFIRMATION_REQUIRED',
+          questionCount, readsLocalData: batch, invokesAI: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const { confirmed } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: `确认把请求里的 state 发送到已配置的决策模型服务吗？`
+            + (questionCount === null ? '' : `（${questionCount} 个问题）`),
+          default: false,
+        }])
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 120_000, maxBuffer: 10 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        const payload = (error as { stdout?: string }).stdout
+        if (payload && payload.trim()) {
+          // 脚本自己已经给出了结构化的失败，原样透传比自己编一个更有用。
+          process.stdout.write(payload)
+        } else {
+          console.log(JSON.stringify({ success: false, code: 'DECIDE_FAILED',
+            action: 'decide', error: safeSubprocessError(error) }))
+        }
+        process.exit(1)
+      }
+    })
+
+  // awaiting —— 谁在等我回话。读本地聊天并把正文发给决策模型，所以照 search 的规矩：
+  // --dry-run 预览、--yes 才真跑。它**不写任何本地数据**，但仍是一次正文出境，
+  // 而聊天正文比日报的文章正文敏感一档。
+  program
+    .command('awaiting')
+    .description('谁在等我回话：逐会话判断有没有欠下的回复（读取聊天正文并调用决策模型）')
+    .option('--days <n>', '只看最近多少天有动静的会话', '14')
+    .option('--limit <n>', '最多判多少个会话', '40')
+    .option('--min-prob <p>', 'waiting 概率低于此值不算欠账', '0.5')
+    .option('--dry-run', '仅预览会判哪些会话、要发多少字符，不调用决策模型')
+    .option('--yes', '确认把聊天正文发送到已配置的决策模型服务')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const pkgRoot = resolvePackageRoot()
+      const script = join(pkgRoot, 'scripts', 'reply_debt.py')
+      const days = parseCliInteger(opts.days, 'days', 1, 3650, opts.json)
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json)
+      const args = [script, '--days', String(days), '--limit', String(limit),
+                    '--min-prob', String(opts.minProb),
+                    ...(opts.json ? ['--json'] : [])]
+
+      if (opts.dryRun) {
+        // 交给脚本自己报数：它才知道要发多少字符。这一步只读本地，零出境。
+        args.push('--dry-run')
+      } else if (!opts.yes) {
+        const preview = {
+          success: false, dryRun: false, action: 'reply-debt.scan',
+          code: 'CONFIRMATION_REQUIRED', days, limit,
+          readsLocalChat: true, invokesAI: true, writesNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const { confirmed } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把最近这些会话的聊天正文发送到已配置的决策模型服务吗？',
+          default: false,
+        }])
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 600_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'AWAITING_FAILED', action: 'reply-debt.scan', error: safeSubprocessError(error) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
+  // draft：判断在前、起草在后、**绝不发送**
+  program
+    .command('draft <talker>')
+    .description('帮我起草回复：先判断（意图/风险/该不该给实质），再起草候选 —— **只产出文本，不发送**')
+    .option('--count <n>', '要几条候选', '3')
+    .option('--gate-commitment', '承诺未兑现时也拒绝起草（默认只在提示词里约束）')
+    .option('--dry-run', '仅预览会发多少字符给哪两个模型，不调用')
+    .option('--yes', '确认把这段对话发送到判断模型与生成模型')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (talker: string, opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const pkgRoot = resolvePackageRoot()
+      const script = join(pkgRoot, 'scripts', 'draft_reply.py')
+      const count = parseCliInteger(opts.count, 'count', 1, 5, opts.json)
+      // **"确认过了"只用一个变量表示**（`--yes` 或交互回答"是"），参数在确认之后才拼。
+      // 原来的写法是先拼参数、再问，于是**交互确认那条路是坏的**：答了"是"，`args` 里
+      // 却从没补上 `--yes`，脚本照样拒绝（用户看到的是"我确认了它却说没确认"）。
+      // 两者合成一个变量之后，这种漏传在结构上不可能再发生。
+      let confirmed = !!opts.yes
+      if (!opts.dryRun && !confirmed) {
+        const preview = {
+          success: false, dryRun: false, action: 'draft-reply',
+          code: 'CONFIRMATION_REQUIRED', talker, count,
+          readsLocalChat: true, invokesAI: true, writesNothing: true, sendsNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把这段对话发送到判断模型与生成模型吗？（只会产出候选文本，不会替你发送）',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+      const args = [script, '--talker', String(talker), '--count', String(count),
+                    // 脚本自己有第二道闸门（`--yes` 才真的把对话发出去），所以要透传
+                    ...(confirmed ? ['--yes'] : []),
+                    ...(opts.gateCommitment ? ['--gate-commitment'] : []),
+                    ...(opts.json ? ['--json'] : []),
+                    // dry-run 交给脚本自己报数（它才知道这段对话有多少字符），这一步只读本地、零出境
+                    ...(opts.dryRun ? ['--dry-run'] : [])]
+
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 300_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'DRAFT_FAILED', action: 'draft-reply', error: safeSubprocessError(error) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
+  // wiki lint：知识库体检（全本地：不联网、不调用模型）
+  program.commands.find(c => c.name() === 'wiki')?.addCommand(
+    new Command('lint')
+      .description('知识库体检：断链、孤儿、空页、同名（本地，不联网）')
+      .option('--dir <dir>', '概念页目录', './output/wechat-vault/Wiki/Concepts')
+      .option('--json', '输出机器可读结果')
+      .action(async (opts) => {
+        const { execFile } = await import('child_process')
+        const { promisify } = await import('util')
+        const execFileAsync = promisify(execFile)
+        const script = join(resolvePackageRoot(), 'scripts', 'wiki_lint.py')
+        const args = [script, '--dir', String(opts.dir), ...(opts.json ? ['--json'] : [])]
+        try {
+          const { stdout } = await execFileAsync(getPythonCommand(), args, {
+            timeout: 120_000, maxBuffer: 20 * 1024 * 1024, env: pythonProcessEnv(),
+          })
+          process.stdout.write(stdout)
+        } catch (error) {
+          if (opts.json) console.log(JSON.stringify({ success: false, code: 'WIKI_LINT_FAILED', error: safeSubprocessError(error) }))
+          else console.error(chalk.red(`
+✗ ${safeSubprocessError(error)}`))
+          process.exit(1)
+        }
+      }))
+
+  // chat-notes：把会话整理成知识卡，喂给 wiki compile 聚成概念页
+  program
+    .command('chat-notes')
+    .description('把最近一段时间的会话整理成知识卡（之后用 wiki compile 聚成概念页）—— **只写本地文件，不发送**')
+    .option('--days <n>', '看最近多少天', '30')
+    .option('--limit <n>', '最多处理几个会话', '40')
+    .option('--dry-run', '仅预览：几个会话、多少字符会发给生成模型（只读本地，零出境）')
+    .option('--yes', '确认把对话发送给生成模型')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const pkgRoot = resolvePackageRoot()
+      const script = join(pkgRoot, 'scripts', 'chat_notes.py')
+      const days = parseCliInteger(opts.days, 'days', 1, 3650, opts.json)
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 200, opts.json)
+      // 与 `draft` 同一条纪律：**"确认过了"只用一个变量**，参数在确认之后才拼
+      let confirmed = !!opts.yes
+      if (!opts.dryRun && !confirmed) {
+        const preview = {
+          success: false, dryRun: false, action: 'chat-notes',
+          code: 'CONFIRMATION_REQUIRED', days, limit,
+          readsLocalChat: true, invokesAI: true, writesLocalFiles: true, sendsNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把最近这些会话的对话发送给生成模型吗？（只会产出本地知识卡，不会替你发送任何消息）',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+      const args = [script, '--days', String(days), '--limit', String(limit),
+                    ...(confirmed ? ['--yes'] : []),
+                    ...(opts.json ? ['--json'] : []),
+                    ...(opts.dryRun ? ['--dry-run'] : [])]
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 900_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'CHAT_NOTES_FAILED', action: 'chat-notes', error: safeSubprocessError(error) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
+  // user-notes：读你自己写的笔记（第四条来源，也是唯一读"人写的东西"的一条）
+  program
+    .command('user-notes')
+    .description('读你自己写的笔记，长成知识卡（之后用 wiki compile 聚成概念页）—— **你的笔记只读，绝不修改**')
+    .option('--limit <n>', '最多处理几篇笔记', '20')
+    .option('--vault <dir>', '库目录', './output/wechat-vault')
+    .option('--refresh', '已有卡的也重做')
+    .option('--dry-run', '仅预览：几篇笔记会发给模型（只读本地，零出境）')
+    .option('--yes', '确认把笔记发给生成模型')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const script = join(resolvePackageRoot(), 'scripts', 'user_notes.py')
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json)
+      let confirmed = !!opts.yes
+      if (!opts.dryRun && !confirmed) {
+        const preview = {
+          success: false, dryRun: false, action: 'user-notes',
+          code: 'CONFIRMATION_REQUIRED', limit,
+          readsLocalData: true, invokesAI: true, writesLocalFiles: true,
+          modifiesYourNotes: false, sendsNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把你自己写的这些笔记发给生成模型吗？（你的笔记只读，产出的卡另存；只写本地文件）',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+      const args = [script, '--limit', String(limit), '--vault', String(opts.vault),
+                    ...(opts.refresh ? ['--refresh'] : []),
+                    ...(confirmed ? ['--yes'] : []),
+                    ...(opts.json ? ['--json'] : []),
+                    ...(opts.dryRun ? ['--dry-run'] : [])]
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 1_800_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'USER_NOTES_FAILED', action: 'user-notes',
+            error: safeSubprocessError(error), detail: String((error as any)?.stdout || '').slice(0, 2000) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
+  // fav-notes：把微信收藏里的文章变成知识卡（第三条来源）
+  program
+    .command('fav-notes')
+    .description('把微信收藏里的文章整理成知识卡（之后用 wiki compile 聚成概念页）—— **只写本地文件，不发送**')
+    .option('--limit <n>', '最多处理几条收藏（按收藏时间倒序）', '10')
+    .option('--refresh', '已有卡的也重做（默认增量：只做还没卡的）')
+    .option('--dry-run', '仅预览：几条、多少要联网抓（只读本地，零出境）')
+    .option('--yes', '确认把收藏的正文发给生成模型')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const script = join(resolvePackageRoot(), 'scripts', 'fav_notes.py')
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 500, opts.json)
+      // 与另外两条线同一条纪律：**「确认过了」只用一个变量**，参数在确认之后才拼
+      let confirmed = !!opts.yes
+      if (!opts.dryRun && !confirmed) {
+        const preview = {
+          success: false, dryRun: false, action: 'fav-notes',
+          code: 'CONFIRMATION_REQUIRED', limit,
+          readsLocalData: true, fetchesArticleUrls: true, invokesAI: true,
+          writesLocalFiles: true, sendsNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把这些收藏的正文发给生成模型吗？（只写本地知识卡；正文取不到时会去抓文章链接）',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+      const args = [script, '--limit', String(limit),
+                    ...(opts.refresh ? ['--refresh'] : []),
+                    ...(confirmed ? ['--yes'] : []),
+                    ...(opts.json ? ['--json'] : []),
+                    ...(opts.dryRun ? ['--dry-run'] : [])]
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 1_800_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'FAV_NOTES_FAILED', action: 'fav-notes',
+            error: safeSubprocessError(error), detail: String((error as any)?.stdout || '').slice(0, 2000) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
+  // article-notes：从文章笔记里提炼概念，喂给 wiki compile
+  program
+    .command('article-notes')
+    .description('从 Vault 的文章笔记里提炼概念（之后用 wiki compile 聚成概念页）—— **只写本地文件，不发送**')
+    .option('--source <dir>', '文章笔记目录', './output/wechat-vault/002_Literature')
+    .option('--limit <n>', '最多处理几篇（按发布时间倒序）', '30')
+    .option('--since <date>', '只看这个日期之后的（YYYY-MM-DD）—— 比 --limit 精确，例："9 月的都跑一遍"')
+    .option('--until <date>', '只看这个日期之前的（YYYY-MM-DD）')
+    .option('--topic <name>', '只做这些主题，可重复或用逗号分隔（如 --topic AI）；不传=全部',
+            (value, previous: string[] = []) => [...previous, value], [])
+    .option('--workers <n>', '并发问几篇（只并行"问"，写仍是串行）', '6')
+    .option('--dry-run', '仅预览：几篇、多少字会发给生成模型（只读本地，零出境）')
+    .option('--refresh-summaries', '只按原笔记重算已有卡片的摘要（本地，不调用模型、不必 --yes）')
+    .option('--yes', '确认把文章发给生成模型')
+    .option('--json', '输出机器可读结果；执行仍需 --yes')
+    .action(async (opts) => {
+      const { execFile } = await import('child_process')
+      const { promisify } = await import('util')
+      const execFileAsync = promisify(execFile)
+      const pkgRoot = resolvePackageRoot()
+      const script = join(pkgRoot, 'scripts', 'article_notes.py')
+      const limit = parseCliInteger(opts.limit, 'limit', 1, 5000, opts.json)
+      // 主题筛选：这一步是**纯花钱的**（一篇一次调用），而实测主题分布是新闻 57% /
+      // AI 28% / 学术 13%，所以"只做 AI"是省掉一半以上花费的那个开关。它必须出现在
+      // 确认框里——不然用户看到的是"要花 1.6 万次调用"，而不是"要花 4 千次"。
+      const topics = (opts.topic as string[])
+        .flatMap(value => String(value).split(','))
+        .map(value => value.trim())
+        .filter(Boolean)
+      const workers = parseCliInteger(opts.workers, 'workers', 1, 64, opts.json)
+      // 与 `chat-notes`/`draft` 同一条纪律：**"确认过了"只用一个变量**，参数在确认之后才拼
+      let confirmed = !!opts.yes
+      if (!opts.dryRun && !opts.refreshSummaries && !confirmed) {
+        const preview = {
+          success: false, dryRun: false, action: 'article-notes',
+          code: 'CONFIRMATION_REQUIRED', source: opts.source, limit, topics,
+          readsLocalData: true, invokesAI: true, writesLocalFiles: true, sendsNothing: true,
+        }
+        if (opts.json) {
+          console.log(JSON.stringify(preview))
+          process.exit(1)
+        }
+        const answer = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'confirmed',
+          message: '确认把这些文章（只问概念，摘要照抄）发给生成模型吗？（只写本地知识卡，不会发送任何消息）',
+          default: false,
+        }])
+        confirmed = !!answer.confirmed
+        if (!confirmed) {
+          console.log(chalk.gray('已取消'))
+          return
+        }
+      }
+      const args = [script, '--source', String(opts.source), '--limit', String(limit),
+                    ...(opts.since ? ['--since', String(opts.since)] : []),
+                    ...(opts.until ? ['--until', String(opts.until)] : []),
+                    ...(topics.length ? ['--topic', topics.join(',')] : []),
+                    '--workers', String(workers),
+                    ...(opts.refreshSummaries ? ['--refresh-summaries'] : []),
+                    ...(confirmed ? ['--yes'] : []),
+                    ...(opts.json ? ['--json'] : []),
+                    ...(opts.dryRun ? ['--dry-run'] : [])]
+      try {
+        const { stdout } = await execFileAsync(getPythonCommand(), args, {
+          timeout: 1_800_000, maxBuffer: 50 * 1024 * 1024,
+          env: pythonProcessEnv(),
+        })
+        process.stdout.write(stdout)
+      } catch (error) {
+        if (opts.json) {
+          console.log(JSON.stringify({ success: false, code: 'ARTICLE_NOTES_FAILED', action: 'article-notes', error: safeSubprocessError(error) }))
+        } else {
+          console.error(chalk.red(`\n✗ ${safeSubprocessError(error)}`))
+        }
+        process.exit(1)
+      }
+    })
+
   // todos
   const todosCmd = program
     .command('todos')
@@ -4752,6 +5741,7 @@ program
   .option('--dry-run', '仅预览文章，不调用 AI 或写入日报')
   .option('--yes', '确认执行日报生成；JSON 模式需要此选项')
   .option('--no-ai', '关闭本次日报的所有 AI 处理')
+  .option('--no-summary', '只判断不生成：不调 LLM 写摘要/标签/简报（主题与相关度仍由 Jev 判断），无需 DeepSeek key')
   .option('--json', '输出机器可读的最终结果；运行日志写入 stderr')
   .action(async (opts) => {
     const { spawn } = await import('child_process')
@@ -4784,6 +5774,8 @@ program
     const runPipeline = (targetDate: string): Promise<number> => new Promise((resolve) => {
       const args = [pipeline, '--date', targetDate, '--engine', noAi ? 'local' : 'deepseek', '--interest', 'AI', '--skip-wiki']
       if (noAi) args.push('--no-ai')
+      // 与 --no-ai 不同：这一条保留判断（Jev），只关掉 LLM 的文字生成。
+      if (opts.noSummary && !noAi) args.push('--no-summary')
       for (const source of opts.source || []) args.push('--source', source)
       if (opts.skipClassify) args.push('--skip-classify')
 
@@ -4988,7 +5980,7 @@ assistantCmd
       process.exit(1)
     }
     const { startDaemon } = await import('../src/services/assistantDaemon.js')
-    const r = startDaemon()
+    const r = await startDaemon()
     if (opts.json) {
       console.log(JSON.stringify(r.started
         ? { success: true, started: true, pid: r.pid, ...preview }
@@ -5043,13 +6035,23 @@ assistantCmd
     const token = configService.get('wechatOcToken')
     const aiKey = configService.get('deepseekApiKey')
     const { privacyGate } = await import('../src/services/assistantPrivacy.js')
+    const { readEndpoint } = await import('../src/panel/endpoint.js')
     const wl = String(configService.get('assistantWhitelist') || '').trim()
     const groups = String(configService.get('assistantGroupWhitelist') || '').trim()
+    // 端点是**运行态**的权威来源：它由守护进程原子写出，而且读取端会探活（进程没了就当没有）。
+    // 它能回答一个配置回答不了的问题：**通道到底接上了没有**。
+    // `messageChannelLoggedIn` 说的只是"配了 token 吗"——token 配了而进程以本机模式跑着，
+    // 这两个字段会一个 true 一个 false，今天完全没有别的办法区分。
+    const endpoint = alive ? readEndpoint() : null
     if (opts.json) {
       console.log(JSON.stringify({
         success: true,
         daemonRunning: alive,
         messageChannelLoggedIn: !!token,
+        channelActive: !!endpoint && endpoint.channel === 'wechat',
+        mode: endpoint ? endpoint.channel : null,
+        panelPort: endpoint ? endpoint.port : null,
+        memoryBucket: endpoint ? endpoint.memoryBucket : null,
         aiConfigured: privacyGate.isLocalInference() || !!aiKey,
         localInference: privacyGate.isLocalInference(),
         privacyMode: privacyGate.mode(),
@@ -5061,6 +6063,12 @@ assistantCmd
     }
     console.log(`守护进程: ${alive ? chalk.green(`运行中 (pid ${pid})`) : chalk.gray('未运行')}`)
     console.log(`消息通道: ${token ? chalk.green('已登录') : chalk.red('未登录 (先 login-wechat)')}`)
+    if (endpoint) {
+      console.log(`  └ 实际接入: ${endpoint.channel === 'wechat' ? chalk.green('微信') : chalk.yellow('仅本机入口')}`
+        + `｜本机入口 http://127.0.0.1:${endpoint.port}｜记忆桶 ${endpoint.memoryBucket}`)
+    } else if (alive) {
+      console.log(chalk.gray('  └ 本机入口未启动（看 assistant log 里的“本机入口启动失败”）'))
+    }
     console.log(`LLM 大脑: ${aiKey ? chalk.green('DeepSeek 已配置') : chalk.gray('未配置 (config set deepseekApiKey)')}`)
     console.log(`隐私模式: ${chalk.cyan(privacyGate.mode())}${privacyGate.isLocalInference() ? chalk.green(' (本地推理, 数据不出境)') : chalk.gray(' (工具结果脱敏后出境)')}`)
     console.log(`白名单: ${wl ? chalk.green(`${wl.split(/[,;\s]+/).filter(Boolean).length} 人`) : chalk.red('未设置 (默认拒绝所有人; config set assistantWhitelist "<@im.wechat ID>")')}`)
@@ -5094,6 +6102,30 @@ assistantCmd
     console.log(content)
   })
 
+assistantCmd
+  .command('trace')
+  .description('看助手最近几轮是怎么走的（判断层 → 工具 → 答复），含模型返回的推理内容')
+  .option('-n, --last <number>', '看最近几轮', '3')
+  .option('--json', '输出结构化轨迹')
+  .action(async (opts) => {
+    const { readTurns, describeTurn, traceFile } = await import('../src/services/assistantTrace.js')
+    const count = parseCliInteger(opts.last, 'last', 1, 50, opts.json)
+    const turns = readTurns(count)
+    if (opts.json) {
+      console.log(JSON.stringify({ success: true, file: traceFile(), count: turns.length, turns }))
+      return
+    }
+    if (!turns.length) {
+      console.log('还没有轨迹。助手收到消息之后才会有；文件：' + traceFile())
+      return
+    }
+    console.log(traceFile())
+    for (const turn of turns) {
+      for (const line of describeTurn(turn)) console.log(line)
+      console.log('')
+    }
+  })
+
 assistantCmd
   .command('run')
   .description('前台运行 (调试用; 常驻请用 start)')
@@ -5136,6 +6168,193 @@ assistantCmd
     await assistant.start((line) => console.log(chalk.gray(line)))
   })
 
+/**
+ * 本机面板：不登录微信也能跟助手说话的入口。
+ *
+ * **它只是客户端**：消息走守护进程的回环端点，于是两个入口共用一个大脑
+ * （同一份记忆、同一条配额、同一条串行队列）。面板自己起一个 `AssistantService` 会变成
+ * 第二个大脑——那是这个功能最容易走错的一步。
+ */
+program
+  .command('panel')
+  .description('打开本机面板窗口 (Electron 悬浮球；没有 Electron 就降级用 Edge --app)')
+  .option('--status', '只看状态，不打开窗口')
+  .option('--ask <text>', '在命令行里问一句（面板减去像素）')
+  .option('--dry-run', '仅预览，不启动窗口或守护进程')
+  .option('--yes', '确认打开')
+  .option('--json', '输出 JSON 格式')
+  .action(async (opts) => {
+    const { readEndpoint, endpointFile } = await import('../src/panel/endpoint.js')
+    const { panelStatus, panelAsk, panelPair } = await import('../src/panel/client.js')
+
+    // ---------------------------------------------------------- 只读：状态
+    if (opts.status) {
+      const endpoint = readEndpoint()
+      if (!endpoint) {
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'PANEL_NOT_RUNNING', error: '本机入口没在运行（先 weflow-cli assistant start）' }))
+        else console.log(chalk.gray('本机入口没在运行（先 weflow-cli assistant start）'))
+        process.exit(1)
+      }
+      const r = await panelStatus(endpoint)
+      if (opts.json) {
+        console.log(JSON.stringify(r.ok
+          ? { success: true, port: endpoint.port, ...r.data }
+          : { success: false, code: r.code }))
+        return
+      }
+      if (!r.ok) { console.log(chalk.yellow(`读状态失败: ${r.code}`)); return }
+      const d = r.data
+      console.log(`本机入口: ${chalk.green(`http://127.0.0.1:${endpoint.port}`)}`)
+      console.log(`接入: ${d.channelActive ? '微信 + 本机' : '仅本机入口'}｜今日 ${d.quota.used}/${d.quota.limit}｜LLM ${d.aiConfigured ? '已配置' : '未配置'}`)
+      console.log(chalk.gray(`记忆桶: ${d.memoryBucket}`))
+      if (d.memoryNote) console.log(chalk.gray(`  ${d.memoryNote}`))
+      return
+    }
+
+    // ---------------------------------------------------------- 在命令行里问一句
+    if (opts.ask !== undefined) {
+      const text = String(opts.ask || '').trim()
+      if (!text) {
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '--ask 不能为空' }))
+        else console.log(chalk.red('--ask 不能为空'))
+        process.exit(1)
+      }
+      if (opts.json && !opts.yes) {
+        console.log(JSON.stringify({ success: false, code: 'CONFIRMATION_REQUIRED', error: '这会真的问助手（可能调用 AI 并占用配额），用 --yes 确认' }))
+        process.exit(1)
+      }
+      const endpoint = readEndpoint()
+      if (!endpoint) {
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'PANEL_NOT_RUNNING', error: '本机入口没在运行（先 weflow-cli assistant start）' }))
+        else console.log(chalk.yellow('本机入口没在运行（先 weflow-cli assistant start）'))
+        process.exit(1)
+      }
+      const r = await panelAsk(endpoint, text)
+      if (opts.json) {
+        console.log(JSON.stringify(r.ok
+          ? { success: true, status: r.data.status, reply: r.data.reply }
+          : { success: false, code: r.code, error: r.error }))
+        if (!r.ok) process.exit(1)
+        return
+      }
+      console.log(r.ok ? r.data.reply : chalk.yellow(`没成: ${r.code}`))
+      return
+    }
+
+    // ---------------------------------------------------------- 打开窗口
+    const { resolveElectronBinary, resolveBrowserBinary, electronLaunchArgs,
+            browserLaunchArgs, browserProfileDir } = await import('../src/panel/launch.js')
+    const { isDaemonAlive, startDaemon } = await import('../src/services/assistantDaemon.js')
+    const { weflowHome } = await import('../src/panel/endpoint.js')
+
+    const electron = resolveElectronBinary({
+      packageRoot: resolvePackageRoot(),
+      localAppData: process.env.LOCALAPPDATA,
+      programFiles: process.env.ProgramFiles,
+    })
+    const browser = electron.found ? { found: null } : resolveBrowserBinary({
+      programFiles: process.env.ProgramFiles,
+      programFilesX86: process.env['ProgramFiles(x86)'],
+      localAppData: process.env.LOCALAPPDATA,
+    })
+    const shell: 'electron' | 'browser' | 'none' = electron.found ? 'electron' : browser.found ? 'browser' : 'none'
+    const running = isDaemonAlive().alive
+
+    const preview = {
+      action: 'panel.open',
+      shell,
+      daemonRunning: running,
+      // 明确声明后果：面板会需要一个守护进程；关掉窗口**不会**顺手把它停掉
+      willStartDaemon: !running,
+      keepsRunningAfterClose: true,
+      endpointFile: endpointFile(),
+    }
+    if (opts.dryRun) {
+      if (opts.json) console.log(JSON.stringify({ success: true, dryRun: true, ...preview }))
+      else console.log(chalk.cyan(`将打开面板（${shell === 'none' ? '没有可用的窗口程序，只会打印地址' : shell}）`
+        + `${running ? '' : '，并启动本机助手守护进程'}`))
+      return
+    }
+    if (opts.json && !opts.yes) {
+      console.log(JSON.stringify({ success: false, code: 'CONFIRMATION_REQUIRED', error: '使用 --yes 确认打开面板', ...preview }))
+      process.exit(1)
+    }
+
+    // 守护进程没起来就先起，并**轮询到真的就绪**——不要相信 spawn 的返回值
+    // （`startDaemon` 里没有 `child.unref()`，stdio 又是 pipe；照抄 daily-reader 的 30×100ms 循环）
+    if (!running) {
+      const started = await startDaemon()
+      if (!started.started && !started.error?.includes('已经运行')) {
+        const msg = `本机助手启动失败: ${started.error ?? '未知原因'}`
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'ASSISTANT_START_FAILED', error: msg, ...preview }))
+        else console.log(chalk.red(msg))
+        process.exit(1)
+      }
+    }
+    let endpoint = readEndpoint()
+    for (let attempt = 0; attempt < 30 && !endpoint; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      endpoint = readEndpoint()
+    }
+    if (!endpoint) {
+      const msg = '本机入口还没就绪（看 weflow-cli assistant log 里的“本机入口启动失败”，端口可能被占）'
+      if (opts.json) console.log(JSON.stringify({ success: false, code: 'PANEL_NOT_READY', error: msg, ...preview }))
+      else console.log(chalk.red(msg))
+      process.exit(1)
+    }
+
+    const { spawn } = await import('child_process')
+    let launched: string
+    let url: string | null = null
+    if (electron.found) {
+      // argv 里**什么都没有**：不带 token、不带端口、不带 URL（命令行对同机任何进程可见）
+      const child = spawn(electron.found, electronLaunchArgs(join(resolvePackageRoot(), 'resources', 'panel')), {
+        detached: true, stdio: 'ignore', windowsHide: true,
+      })
+      child.unref()
+      launched = 'electron'
+    } else if (browser.found) {
+      // 浏览器那条路只能靠一次性口令：它单次使用、60 秒过期，所以进命令行与浏览器历史都不算泄漏
+      const pair = await panelPair(endpoint)
+      if (!pair.ok) {
+        const msg = `换一次性口令失败: ${pair.code}`
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'PAIR_FAILED', error: msg, ...preview }))
+        else console.log(chalk.red(msg))
+        process.exit(1)
+      }
+      url = pair.data.url
+      const child = spawn(browser.found, browserLaunchArgs({ url, profileDir: browserProfileDir(weflowHome()) }), {
+        detached: true, stdio: 'ignore', windowsHide: true,
+      })
+      child.unref()
+      launched = 'browser'
+    } else {
+      // 两条路都没有：**别静默什么都不做**，把地址交出去
+      const pair = await panelPair(endpoint)
+      url = pair.ok ? pair.data.url : `http://127.0.0.1:${endpoint.port}/panel`
+      launched = 'none'
+    }
+
+    if (opts.json) {
+      // 展开在前、实际结果在后：`preview.shell` 是"打算用哪个"，这里是"实际用了哪个"，
+      // 两者可能不同（例如打算用 Electron 但 spawn 之后没起来）——以后者为准
+      console.log(JSON.stringify({ ...preview, success: true, shell: launched, port: endpoint.port, url }))
+      return
+    }
+    if (launched === 'electron') {
+      console.log(chalk.green(`✓ 面板已启动（记忆桶 ${endpoint.memoryBucket}）`))
+      console.log(chalk.gray('  关掉窗口只是隐藏；助手仍在后台跑，要停它用 weflow-cli assistant stop'))
+    } else if (launched === 'browser') {
+      console.log(chalk.green('✓ 已用浏览器打开面板窗口'))
+      console.log(chalk.yellow('  注意：这条路给不了悬浮球——浏览器窗口不能无边框/置顶，也没有托盘与快捷键。'))
+      console.log(chalk.gray('  想要真·悬浮球：npm i -g electron 之后再跑一次'))
+    } else {
+      console.log(chalk.yellow('没找到 Electron，也没找到 Edge/Chrome。自己打开这个地址即可：'))
+      console.log(chalk.cyan(`  ${url}`))
+      console.log(chalk.gray('  想要悬浮球：npm i -g electron'))
+    }
+  })
+
 program
   .command('daily-stats')
   .description('统计公众号推送频率与日报处理频率')
@@ -5321,10 +6540,10 @@ program
       ['wechat.search_public', '搜索全网公众号文章'],
       ['wechat.export_messages', '按稳定数据契约读取会话消息'],
     ]
-    const { MCP_READ_ONLY_TOOL_DEFS } = await import('../src/services/assistantTools.js')
+    const { MCP_TOOL_DEFS } = await import('../src/services/assistantTools.js')
     const all = [
       ...STATIC_TOOLS,
-      ...MCP_READ_ONLY_TOOL_DEFS.filter(t => t.function.name !== 'get_stats')
+      ...MCP_TOOL_DEFS.filter(t => t.function.name !== 'get_stats')
         .map(t => [`wechat.${t.function.name}`, t.function.description.split(/[。(]/)[0]] as [string, string]),
     ]
     for (const [n, d] of all) {