weflow-cli 1.7.0 → 1.8.1

package/src/services/pythonBridge.ts

@@ -0,0 +1,139 @@
+/**
+ * 调本仓 Python 脚本的**唯一入口**：拿 JSON 回来，或者把失败说清楚。
+ *
+ * 为什么要有这一层：此前有两份实现——`get_todos` 用 `execFile`（参数走 argv），路由用
+ * `spawn`（请求走 stdin）。两份各有一套超时、错误、stdout 解析的写法，正是"同一件事两处
+ * 实现"的老毛病；而工具只会越加越多。
+ *
+ * 三条约定：
+ * 1. **只有 JSON 出口**：脚本要么给出可解析的 JSON，要么给出错误——不解析人类可读文本
+ *    （那种解析在脚本改一行格式时就悄悄失效）。
+ * 2. **JSON 可以在最后一行**：有些脚本（如 route_cards）前面会打印给人看的进度行。
+ *    所以先试整份 stdout，再退一步取"最后一行能解析成 JSON 的"。
+ * 3. **失败要说清是什么失败**：退出码、还是没有 JSON、还是超时——三者分开报，别都变成
+ *    "执行失败"。
+ */
+import { spawn } from 'node:child_process'
+import { join } from 'node:path'
+import { resolvePackageRoot } from '../utils/packageRoot.js'
+import { createPythonProcessEnv } from '../utils/pythonProcessEnv.js'
+import { getPythonCommand } from '../utils/python.js'
+
+export interface ScriptRun {
+  stdout: string
+  stderr: string
+  /** 进程退出码；被信号杀死时为 null */
+  code: number | null
+}
+
+/** 注入点：测试用假 runner 驱动，不 spawn 真进程 */
+export type ScriptRunner = (scriptPath: string, args: string[],
+                            options: { timeoutMs: number; stdin?: string; env?: Record<string, string> }) => Promise<ScriptRun>
+
+export interface JsonResult<T> {
+  ok: boolean
+  data?: T
+  /** 失败原因（已分类：超时 / 退出码 / 没有 JSON） */
+  error?: string
+  /** 失败时的 stderr 尾巴，便于定位 */
+  stderr?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+function realRunner(scriptPath: string, args: string[],
+                    options: { timeoutMs: number; stdin?: string; env?: Record<string, string> }): Promise<ScriptRun> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(getPythonCommand(), [scriptPath, ...args], {
+      // 用户输入走**环境变量**而不是 argv：这是仓库写进测试的隐私纪律（进程列表里看不到正文）
+      env: createPythonProcessEnv(options.env ?? {}),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      child.kill()
+      reject(new Error(`脚本超时（${options.timeoutMs}ms）`))
+    }, options.timeoutMs)
+
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+    child.on('error', (error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(error)
+    })
+    child.on('close', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ stdout, stderr, code })
+    })
+    if (options.stdin !== undefined) child.stdin.end(options.stdin)
+    else child.stdin.end()
+  })
+}
+
+let runner: ScriptRunner = realRunner
+
+/** 换掉 runner（测试用）。传 null 恢复真实实现。 */
+export function setScriptRunner(next: ScriptRunner | null): void {
+  runner = next ?? realRunner
+}
+
+/** 脚本路径：一律相对包根下的 `scripts/`，不给调用方自己拼路径的自由 */
+export function scriptPath(name: string): string {
+  return join(resolvePackageRoot(import.meta.url), 'scripts', name)
+}
+
+/** 从 stdout 里取 JSON：先试整份，再取最后一行能解析的 */
+export function parseJsonFrom(stdout: string): { ok: boolean; data?: any } {
+  const whole = stdout.trim()
+  if (whole) {
+    try { return { ok: true, data: JSON.parse(whole) } } catch { /* 落下去取最后一行 */ }
+  }
+  const lines = stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i].startsWith('{') && !lines[i].startsWith('[')) continue
+    try { return { ok: true, data: JSON.parse(lines[i]) } } catch { /* 继续往前找 */ }
+  }
+  return { ok: false }
+}
+
+/**
+ * 跑一个脚本并解析它给的 JSON。
+ *
+ * **不抛异常**：调用方（工具分支）要的是"这次调用成不成功"，而不是一层 try/catch。
+ * 失败的三种情形分开报——超时、退出码非 0、退出码 0 但没有 JSON。
+ */
+export async function runPythonJson<T = any>(
+  script: string, args: string[],
+  options: { timeoutMs?: number; stdin?: string; env?: Record<string, string> } = {},
+): Promise<JsonResult<T>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  let run: ScriptRun
+  try {
+    run = await runner(scriptPath(script), args, { timeoutMs, stdin: options.stdin, env: options.env })
+  } catch (error: any) {
+    return { ok: false, error: String(error?.message ?? error).slice(0, 200) }
+  }
+
+  const parsed = parseJsonFrom(run.stdout)
+  const stderrTail = run.stderr.trim().split(/\r?\n/).filter(Boolean).slice(-3).join(' | ').slice(0, 300)
+
+  if (run.code !== 0) {
+    return { ok: false, error: `脚本退出码 ${run.code}`, stderr: stderrTail }
+  }
+  if (!parsed.ok) {
+    return { ok: false, error: '脚本没有给出可解析的 JSON', stderr: stderrTail }
+  }
+  const data: any = parsed.data
+  if (data && typeof data === 'object' && 'success' in data && data.success === false) {
+    return { ok: false, error: String(data.error ?? '脚本报错').slice(0, 200), stderr: stderrTail }
+  }
+  return { ok: true, data: data as T }
+}

package/src/services/syncService.ts

@@ -116,9 +116,16 @@ export function deriveCoverage(input: {
   mayHaveMore: boolean
 }): SyncCoverage {
   if (input.mayHaveMore) return 'partial'
-  // A shard that faulted *after* opening means its rows are only partly read.
-  const readFailed = input.shards?.items.some(item => item.reason === 'READ_FAILED')
-  if (readFailed) return 'partial'
+  // Any per-shard reason means those rows were not read: a fault after opening
+  // (READ_FAILED), a table the reader can name nothing in (SCHEMA_MISMATCH), or
+  // a window the shard cannot express (WINDOW_UNAVAILABLE). Coverage is about
+  // whether the range was read, so all of them make it partial. A shard read
+  // with columns missing is *not* one of these - its rows did come back.
+  // A shard that never opened is a different answer and stays 'unverified'
+  // below: nothing is known about its rows either way, which is not the same
+  // claim as knowing they were missed.
+  const anyShardUnread = input.shards?.items.some(item => item.opened && item.reason)
+  if (anyShardUnread) return 'partial'
   if (!input.shards) return 'unverified'
   // A shard that never opened is not knowable either way; say so rather than
   // claiming completeness or declaring failure.
@@ -205,8 +212,18 @@ export interface SyncRunOptions extends WindowOptions {
   source?: string
   scope?: string
   limit?: number
-  /** Injected for tests; the CLI wires this to chatService. */
-  read: (talker: string, limit: number) => Promise<{ messages: Message[]; shards?: ShardReport }>
+  /**
+   * Injected for tests; the CLI wires this to chatService.
+   *
+   * `from` is a hint that a backend may push into SQL. It is never a
+   * correctness guarantee: runSync still applies the window itself, because a
+   * backend that cannot honour the lower bound reads everything instead.
+   */
+  read: (
+    talker: string,
+    limit: number,
+    from: number | null
+  ) => Promise<{ messages: Message[]; shards?: ShardReport }>
   write?: boolean
   /** Defaults to the real store; tests pass one rooted in a temp directory. */
   store?: SyncStateStore
@@ -251,11 +268,13 @@ export async function runSync(talker: string, options: SyncRunOptions): Promise<
   }
 
   const limit = options.limit ?? 0
-  const read = await options.read(talker, limit)
+  const read = await options.read(talker, limit, window.from)
   const { unique, duplicateCount } = dedupeMessages(read.messages, source, talker)
 
-  // Without a native range pushdown the read is the whole conversation, so the
-  // window is applied here. This is why the sync is correct but not cheap yet.
+  // The window is applied here as well as being pushed down, and this filter -
+  // not the pushdown - is what makes the result correct: a backend without
+  // range support returns the whole conversation, and one that cannot express
+  // the lower bound says so per shard rather than quietly dropping the bound.
   const inWindow = window.from === null
     ? unique
     : unique.filter(m => Number(m.createTime) >= (window.from as number))
@@ -270,10 +289,19 @@ export async function runSync(talker: string, options: SyncRunOptions): Promise<
   const mayHaveMore = limit > 0 && read.messages.length >= limit
   const coverage = deriveCoverage({ shards: read.shards, mayHaveMore })
   if (!read.shards) warnings.push('shard-report-unavailable')
-  if (read.shards && read.shards.failed > 0) {
+  if (read.shards) {
     for (const item of read.shards.items) {
       if (!item.opened) warnings.push(`shard-unverified:${item.name}`)
       else if (item.reason === 'READ_FAILED') warnings.push(`shard-read-failed:${item.name}`)
+      // A shard the reader could not name anything in, or could not apply the
+      // window to. Both mean "this range was not read here", which must not
+      // pass as covered - hence a warning rather than a silent skip.
+      else if (item.reason) warnings.push(`shard-not-read:${item.name}:${item.reason}`)
+      // Read, but with fields missing. Column names are schema, not content,
+      // so this stays safe to record in the state file.
+      else if (item.missingColumns?.length) {
+        warnings.push(`shard-columns-missing:${item.name}:${item.missingColumns.join('+')}`)
+      }
     }
   }
 

package/src/services/wechatMessageService.ts

@@ -18,6 +18,42 @@ function uuidHex(): string {
   return crypto.randomUUID().replace(/-/g, '')
 }
 
+/**
+ * 长轮询失败的分类。
+ *
+ * **`-14` 才是"token 已失效"**——这是厂商实现里写死的（`third-party/WeKnora/internal/im/wechat/longpoll.go:10,151`
+ * `if result.ErrCode == -14 { return ErrTokenExpired }`），而本仓原来只查 `-1 || 401`。
+ * 查错码的后果**不是报错**，而是把"过期"当成普通错误：每 5 秒重试一次，永远重试下去，
+ * 而用户那边看不到任何异常（`channelActive` 只表示"配了 token"，不表示轮询是活的）。
+ *
+ * 三分类的用意：
+ * - `ok`：正常（长轮询空响应会带 0，或干脆没有这两个字段——见下面的调用处注释）；
+ * - `token-expired`：`-14` 或 HTTP 401。**重试不可能成功**，所以它的待遇与别的失败不同；
+ * - `retryable`：其余（网络抖动、`-1` 这类语义不明的码）。仍然重试，但**退避**，
+ *   免得把日志刷成噪音——噪音等于没说。
+ */
+export function classifyPollResult(
+  data: { ret?: number | null; errcode?: number | null } | null | undefined,
+  httpStatus?: number,
+): 'ok' | 'token-expired' | 'retryable' {
+  if (httpStatus === 401) return 'token-expired'
+  const errcode = data?.errcode
+  if (errcode === -14) return 'token-expired'
+  const ret = data?.ret
+  const badRet = ret != null && ret !== 0
+  const badCode = errcode != null && errcode !== 0
+  if (badRet || badCode) return 'retryable'
+  return 'ok'
+}
+
+/** 重试间隔：1s 起、翻倍、封顶 30s（厂商那边是 1s→30s 指数退避，同一条路数） */
+export const POLL_BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000]
+
+export function nextPollDelay(failures: number): number {
+  const index = Math.min(Math.max(failures - 1, 0), POLL_BACKOFF_MS.length - 1)
+  return POLL_BACKOFF_MS[index]
+}
+
 export class WechatMessageService {
   private client: WechatClient
   private config: WechatOCConfig
@@ -26,6 +62,8 @@ export class WechatMessageService {
   private contextTokens: Map<string, string> = new Map()
   private syncBuf: string
   private messageCallbacks: Array<(msg: WechatInboundMessage) => void> = []
+  /** 服务端说过 token 失效了。**只由长轮询置位**（见 `classifyPollResult`），恢复时清掉 */
+  private tokenExpired = false
 
   constructor(config: WechatOCConfig = {}) {
     this.config = config
@@ -140,6 +178,8 @@ export class WechatMessageService {
   // ====== Message Polling ======
 
   async startPolling(): Promise<void> {
+    let failures = 0
+    let expiryReported = false
     while (!this.shutdownFlag) {
       try {
         const data = await this.client.requestJson('POST', 'ilink/bot/getupdates', {
@@ -152,15 +192,31 @@ export class WechatMessageService {
         })
 
         // ret/errcode may be absent on empty response (normal for long-poll timeout)
-        if (data.ret != null && data.ret !== 0 || data.errcode != null && data.errcode !== 0) {
-          console.error(`getupdates error: ret=${data.ret} errcode=${data.errcode} errmsg=${data.errmsg || 'unknown'}`)
-          if (data.errcode === -1 || data.errcode === 401) {
-            console.error('Token may have expired, please login again')
+        const kind = classifyPollResult(data)
+        if (kind !== 'ok') {
+          failures += 1
+          const detail = `ret=${data.ret} errcode=${data.errcode} errmsg=${data.errmsg || 'unknown'}`
+          if (kind === 'token-expired') {
+            this.tokenExpired = true
+            // **只在状态翻过去时喊一次**：每 5 秒刷一行会被当成噪音，而噪音等于没说
+            if (!expiryReported) {
+              expiryReported = true
+              console.error(`微信通道的 token 已失效（${detail}）——重试不会成功。`
+                + '重新登录：weflow-cli login-wechat，之后重启助手（weflow-cli assistant stop/start）'
+                + '；在此之前本机面板那条入口照常可用。')
+            }
+          } else {
+            console.error(`getupdates error: ${detail}`)
           }
-          await sleep(5000)
+          await sleep(nextPollDelay(failures))
           continue
         }
 
+        // 这一轮是通的：清掉失败计数与"说过一次"的标记（恢复了就该重新能喊）
+        failures = 0
+        expiryReported = false
+        this.tokenExpired = false
+
         if (data.get_updates_buf) {
           this.syncBuf = data.get_updates_buf
           configService.set('wechatOcSyncBuf', this.syncBuf as any)
@@ -172,7 +228,11 @@ export class WechatMessageService {
           const inbound = this.parseInboundMessage(msg)
           if (inbound) {
             for (const cb of this.messageCallbacks) {
-              try { cb(inbound) } catch {}
+              try { cb(inbound) } catch (error: any) {
+                // **不许吞**：这里进的是助手处理消息的入口。吞掉的话，用户发了消息、
+                // 助手什么都没发生、日志里一个字都没有——三种证据全无，最难查的一种坏法。
+                console.error(`消息回调异常（这条消息没有被处理）：${error?.message || error}`)
+              }
             }
           }
         }
@@ -183,12 +243,18 @@ export class WechatMessageService {
           // Restart poll immediately
           continue
         }
+        failures += 1
         console.error(`Polling error: ${e.message}`)
-        await sleep(5000)
+        await sleep(nextPollDelay(failures))
       }
     }
   }
 
+  /** token 是否已被服务端判为失效（面板/状态用它来说实话，见 `isChannelActive`） */
+  isTokenExpired(): boolean {
+    return this.tokenExpired
+  }
+
   async stop(): Promise<void> {
     this.shutdownFlag = true
   }

package/src/services/wereadService.ts

@@ -1,15 +1,35 @@
 /**
  * 微信读书 Agent API Gateway 封装
  *
- * 接口文档: ~/.claude/skills/weread-skills/
+ * 接口文档: https://weread.qq.com/r/weread-skills —— 登录后点「快速配置」，页面上给出
+ *          `api-key`，并提供一个官方 skill 包（`https://cdn.weread.qq.com/skills/weread-skills.zip`）。
+ *          **原来的注释指的是 `~/.claude/skills/weread-skills/`，那个目录在本机已不存在**
+ *          （2026-09-28 核实），照它去找是找不到的。
  * Gateway:  https://i.weread.qq.com/api/agent/gateway
  */
 
 import https from 'node:https'
+import { configService } from './configService.js'
 
 const GATEWAY = 'https://i.weread.qq.com/api/agent/gateway'
 const SKILL_VERSION = '1.0.3'
 
+/**
+ * 从两个来源里挑出可用的 key（环境变量优先，配置项兜底）。
+ *
+ * **为什么是两个来源**：助手的 `get_weread` 判据读**配置项** `wereadApiKey`
+ * （`assistantTools.ts` 的 `TOOL_REQUIREMENTS`），而 CLI 的 `weread` 命令一直只读
+ * **环境变量** `WEREAD_API_KEY`（官方那篇配置文档给的写法就是 export 环境变量）。
+ * 只认一个的后果是：用户按 CLI 的提示配好配置项，助手能用、`weread shelf` 却回你
+ * "未设置 WEREAD_API_KEY" —— 2026-09-28 实测踩到。
+ *
+ * 环境变量优先，因为官方文档明确建议"出于安全考虑，最好不要把 api-key 直接扔给 AI"。
+ * 两边都空白时返回空串，调用方按"没配"处理（`config set` 允许把值清空）。
+ */
+export function resolveWereadApiKey(fromEnv?: string | null, fromConfig?: string | null): string {
+  return String(fromEnv || '').trim() || String(fromConfig || '').trim()
+}
+
 // weread.qq.com 服务端不支持 TLS 1.3，需要强制使用 TLS 1.2
 const httpsAgent = new https.Agent({ maxVersion: 'TLSv1.2' })
 
@@ -64,13 +84,20 @@ export interface ReadDetail {
 
 export interface NotebookItem {
   bookId: string
-  title: string
-  author: string
-  cover: string
-  highlightCount: number
+  /**
+   * **书名与作者嵌在这里，条目顶层没有。** 实测（2026-09-28，`/user/notebooks` 的真实响应）：
+   * 条目只有 `bookId` / `noteCount` / `bookmarkCount` / `readingProgress` / `sort` / `markedStatus`
+   * 等，读 `item.title` 会安静地拿到 `undefined` —— 工具照常输出，只是每本书都没名字。
+   */
+  book?: { title?: string; author?: string; cover?: string }
+  /** 顶层这两个字段**不是**接口给的，留作兜底：网关换版本时形状可能不同。 */
+  title?: string
+  author?: string
+  cover?: string
   noteCount: number
   bookmarkCount: number
-  updateTime: number
+  readingProgress?: number
+  sort?: number
 }
 
 export interface NoteDetail {
@@ -165,7 +192,16 @@ export class WereadService {
   private apiKey: string
 
   constructor(apiKey?: string) {
-    this.apiKey = apiKey || process.env.WEREAD_API_KEY || ''
+    // 不传 key 时按 `resolveWereadApiKey` 的顺序自己找：环境变量 → 配置项。
+    //
+    // **配置项这一路是 2026-09-28 补的，而且是端到端才发现的。** 助手的 `get_weread`：
+    // 可用性判据读配置项（所以配好之后工具会出现在工具表里），执行时用的却是模块单例
+    // `new WereadService()` —— 那个单例只读环境变量。于是工具"看得见、调不动"，回一句
+    // "未设置 WEREAD_API_KEY"。只改 CLI 那处是不够的：同一个密钥在当时有**三种读法**。
+    this.apiKey = apiKey || resolveWereadApiKey(
+      process.env.WEREAD_API_KEY,
+      String(configService.get('wereadApiKey') || ''),
+    )
   }
 
   private async call<T>(apiName: string, params: Record<string, any> = {}): Promise<WereadResult<T>> {

package/src/utils/atomicWrite.ts

@@ -0,0 +1,56 @@
+/**
+ * 原子写：先写 `.tmp`，再 `rename` 覆盖目标。
+ *
+ * ## 为什么不能直接 `renameSync`
+ *
+ * **Windows 上 rename 覆盖一个正被别的句柄打开的文件会失败（EPERM）**——只读打开就够触发。
+ * 实测：另一个句柄 `openSync(target, 'r')` 拿着时 `renameSync` 报 EPERM，句柄一关就成功。
+ * 杀毒、搜索索引器、另一个进程的读者都会短暂造成这个状态。
+ *
+ * 后果是**静默丢写入**：调用方（`AssistantMemory.save()`、`configService.save()`）都是
+ * catch 掉、只记一个原因，于是"保存成功"与"保存没发生"在界面上看不出区别。
+ * 这不是理论风险——本仓库一次全量测试里，记忆文件那次保存之后就真的没写进去
+ * （`save()` 之后文件里没有 `version`，而那条用例本身是绿的）。
+ *
+ * ## 所以
+ *
+ * 忙就重试几次（同步 sleep：调用方是同步的 `save()`，不值得为它把整条链改成异步），
+ * 仍然忙就**直接覆盖写目标**——保住这份数据，比保住"原子"这个性质更重要。
+ *
+ * 落盘的字节与原子写一致（都是同一份字符串），所以读者不会看到半截内容；
+ * 退化的那一次只失去"改名是瞬时"这一点。留给同机的读者一个真实边界：
+ * 若那个句柄是以拒绝写入的方式打开的，直接写也会失败，这时照旧抛给调用方。
+ */
+import { writeFileSync, renameSync, rmSync } from 'node:fs'
+
+/** 忙等。`Atomics.wait` 是标准库里的同步睡眠，不用引第三方包 */
+function sleepSync(ms: number): void {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  } catch { /* 不支持就干脆不等，直接重试 */ }
+}
+
+/** 这些是"文件正忙"的形态，值得重试；别的错误（权限、路径不存在）立刻抛 */
+const BUSY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY'])
+
+export function writeFileAtomic(target: string, data: string, options: { mode?: number } = {}): void {
+  const tmp = `${target}.tmp`
+  writeFileSync(tmp, data, { encoding: 'utf8', mode: options.mode })
+
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      renameSync(tmp, target)
+      return
+    } catch (error: any) {
+      if (!BUSY_CODES.has(error?.code)) {
+        try { rmSync(tmp, { force: true }) } catch { /* 清理失败不掩盖原错误 */ }
+        throw error
+      }
+      sleepSync(10 * (attempt + 1))
+    }
+  }
+
+  // 还在忙：直接覆盖。数据不丢，只是不再"原子"
+  writeFileSync(target, data, { encoding: 'utf8', mode: options.mode })
+  try { rmSync(tmp, { force: true }) } catch { /* 见上 */ }
+}

package/src/utils/dateRange.ts

@@ -56,3 +56,49 @@ export function resolveExportDateRange(options: {
   }
   return { from, to }
 }
+
+/**
+ * 助手工具用的时间表达式：`2026-09-16`（本地零点）、`3d` / `2w` / `12h`、以及裸数字（= 天数）。
+ * 回**秒**——与消息里的 `createTime` 同一单位。
+ *
+ * 为什么允许相对写法：模型没法可靠地把"上周三"算成日期（系统提示里给了当前时间也只是够用），
+ * 而"过去三天"这种说法只要一个 `3d` 就表达了，不用它自己数日子。
+ *
+ * 日/周**按当天零点**而不是精确 24 小时前：人说的"三天"指的是那三天，不是一个瞬时。
+ * 给不出明确的窗口就抛——**猜一个比报错更糟**，模型会以为它查的正是自己说的那段时间。
+ */
+export function resolveSince(value: unknown, nowMs = Date.now()): number | undefined {
+  const text = String(value ?? '').trim()
+  if (!text) return undefined
+  const relative = text.match(/^(\d+)\s*([dhw])$/i)
+  if (relative) {
+    const amount = Number(relative[1])
+    const unit = relative[2].toLowerCase()
+    if (unit === 'h') return Math.floor((nowMs - amount * 3_600_000) / 1000)
+    return startOfDayMs(nowMs - amount * (unit === 'w' ? 7 : 1) * 86_400_000)
+  }
+  if (/^\d+$/.test(text)) return startOfDayMs(nowMs - Number(text) * 86_400_000)
+  return parseLocalDateOrIso(text)
+}
+
+/** 上界：`2026-09-16` 指**含当天**（当天 23:59:59），因为"到那天为止"总是指一整天。 */
+export function resolveUntil(value: unknown): number | undefined {
+  const text = String(value ?? '').trim()
+  if (!text) return undefined
+  if (/^\d{4}-\d{2}-\d{2}$/.test(text)) return parseLocalDateOrIso(text, true)
+  return parseLocalDateOrIso(text)
+}
+
+function startOfDayMs(ms: number): number {
+  const date = new Date(ms)
+  date.setHours(0, 0, 0, 0)
+  return Math.floor(date.getTime() / 1000)
+}
+
+/** 给系统提示/工具输出用的一行当前时间。测试要能固定它，所以 `now` 可注入。 */
+export function nowLine(now = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, '0')
+  const week = ['日', '一', '二', '三', '四', '五', '六'][now.getDay()]
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}（星期${week}）`
+       + `${pad(now.getHours())}:${pad(now.getMinutes())}`
+}

package/src/utils/text.ts

@@ -0,0 +1,20 @@
+/**
+ * 显示形态里的小工具。
+ *
+ * 只放跨模块共用的：`clipWithMarker` 有两处需要——AppMsg 的显示形态
+ * （`core/appMsgFormat.ts`，引用消息的正文与被引原文各截一次）和助手读聊天记录时
+ * 每条消息的字数上限（`services/assistantTools.ts`）。
+ *
+ * Python 侧有一份同义的实现（`nt_decrypt.py` 的 `_clip`），做的是同一件事。
+ */
+
+/**
+ * 超长截断并**留下省略号**。
+ *
+ * 不标记的截断读起来像一句说完的话：被引原文最长的 12733 字（引用了一整篇公众号文章），
+ * 切完看着像"这就是全部"；助手把一条 300 字的聊天记录切到 160，模型会以为对方就说完了
+ * 这半句。标记只花一个字符，换来的是"这里被切过"这个事实没有丢。
+ */
+export function clipWithMarker(text: string, limit: number): string {
+  return text.length <= limit ? text : text.slice(0, limit) + '…'
+}