weflow-cli 1.6.4 → 1.8.0

package/src/services/syncState.ts

@@ -0,0 +1,275 @@
+/**
+ * 同步检查点与任务记录的本地状态。
+ *
+ * 两个位置, 生命周期不同 (见 docs/SYNC_CONTRACT.md):
+ *   ~/.weflow-cli/sync/<source>-<name>-<hash>.json  跨运行的检查点, 每会话一份
+ *   ~/.weflow-cli/jobs/<jobId>.json                 单次运行的记录
+ *
+ * 按会话分文件而不是一个全局文件: 全局文件要求跨会话读改写并合并, 分文件则每次
+ * 写入都是整文件原子替换 (沿用 assistantMemory.ts 的 tmp + rename 做法)。
+ *
+ * 两条本模块特有的规矩:
+ *   - 遇到不认识的 schema 一律拒绝覆盖并报错, 不猜测字段含义;
+ *   - 写盘前统一过一遍脱敏, 保证密钥/绝对路径不会进状态文件 (D-001 / D-002 / D-025)。
+ */
+import { createHash } from 'crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import os from 'os'
+
+export const SYNC_SCHEMA = 'weflow-sync/v1'
+export const JOB_SCHEMA = 'weflow-job/v1'
+export const SYNC_SOURCE = 'wechat-nt'
+export const DEFAULT_OVERLAP_SECONDS = 300
+
+/** 单次运行的结局。partial 是本项目新增的一档——部分完成不算成功。 */
+export type JobState = 'planned' | 'waiting_confirmation' | 'running' | 'paused'
+  | 'completed' | 'partial' | 'failed' | 'cancelled'
+
+/**
+ * 覆盖可信度。这是对「有没有读全」的正面回答, 不是内部细节。
+ *
+ *  - complete   扫到的分片全部打开、打开的全读成功, 且没有更多
+ *  - unverified 有分片打不开, 但打开的都读成功——已读部分可信, 未打开的分片内容无法判断
+ *  - partial    已打开的分片读失败, 或还有更多, 或分页提前结束
+ */
+export type SyncCoverage = 'complete' | 'unverified' | 'partial'
+
+export interface SyncShardItem {
+  /** 仅 basename——绝不落绝对路径 */
+  name: string
+  opened: boolean
+  hasTalkerTable: boolean | null
+  rowsForTalker: number | null
+  /** null | KEY_REJECTED | OPEN_FAILED | READ_FAILED */
+  reason: string | null
+}
+
+export interface SyncState {
+  schema: string
+  schemaVersion: number
+  source: string
+  scope: string
+  talker: string
+  lastSuccessfulRun: string | null
+  lastAttempt: string | null
+  coveredFrom: string | null
+  coveredTo: string | null
+  checkpoint: { newestCreateTime: number | null; overlapSeconds: number }
+  recordsRead: number
+  recordsDeduplicated: number
+  recordsReturned: number
+  shardsRead: number
+  shardsFailed: number
+  shards: { scanned: number; opened: number; failed: number; items: SyncShardItem[] }
+  coverage: SyncCoverage
+  mayHaveMore: boolean
+  warnings: string[]
+  updatedAt: string | null
+}
+
+export interface JobRecord {
+  schema: string
+  jobId: string
+  kind: string
+  state: JobState
+  createdAt: string
+  updatedAt: string
+  window: { from: number | null; to: number | null } | null
+  progress: { completed: number; total: number } | null
+  resumeable: boolean
+  result: Record<string, unknown> | null
+  error: string | null
+}
+
+/** 未知 schema 时不覆盖原文件, 交由调用方决定如何处理。 */
+export class UnknownSchemaError extends Error {
+  constructor(public readonly path: string, public readonly found: unknown) {
+    super(`不认识的 schema: ${String(found)} (${path})`)
+    this.name = 'UnknownSchemaError'
+  }
+}
+
+const CONFIG_DIR = join(os.homedir(), '.weflow-cli')
+const SYNC_DIR = join(CONFIG_DIR, 'sync')
+const JOBS_DIR = join(CONFIG_DIR, 'jobs')
+
+const FORBIDDEN_KEYS = /^(ntKey|ntSalt|decryptKey|favKey|favPassphrase|contactKey|snsKey|wechatOcToken|apiKey|password|auth)$/i
+/** 密钥形状的十六进制串 (>=32 hex)。 */
+const HEX_KEY = /\b[0-9a-f]{32,}\b/gi
+/** Windows 盘符、UNC、以及 POSIX 绝对路径。三类都要, 早期只处理了第一类。 */
+const ABS_PATH = /(?:[A-Za-z]:[\\/][^\s"']*|\\\\[^\s"']+|\/(?:Users|home|root|var|tmp|opt|mnt)\/[^\s"']*)/g
+
+/**
+ * 递归剔除不该落盘的字段。
+ *
+ * 状态文件是本机产物, 但一旦被日志、issue 或截图带出去就是泄露, 所以在写入
+ * 这一层兜底, 而不是指望每个调用方都记得。
+ */
+export function sanitizeForState(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.replace(HEX_KEY, '<redacted>').replace(ABS_PATH, '<path>')
+  }
+  if (Array.isArray(value)) return value.map(sanitizeForState)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      if (FORBIDDEN_KEYS.test(key)) continue
+      out[key] = sanitizeForState(item)
+    }
+    return out
+  }
+  return value
+}
+
+/**
+ * 文件名里只放一个可读前缀和一个 hash。
+ *
+ * hash 后缀让 `wxid_a@chatroom` 与 `wxid_a_chatroom` 落到不同文件, 而显示名
+ * 不会出现在目录列表里。
+ */
+export function talkerSlug(talker: string): string {
+  const readable = talker.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 60)
+  const digest = createHash('sha256').update(talker).digest('hex').slice(0, 8)
+  return `${readable}-${digest}`
+}
+
+function writeAtomic(path: string, payload: unknown): void {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true })
+  const tmp = `${path}.tmp`
+  writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8')
+  renameSync(tmp, path)
+}
+
+function readJson(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function emptySyncState(
+  talker: string,
+  scope = talker,
+  source = SYNC_SOURCE,
+  overlapSeconds = DEFAULT_OVERLAP_SECONDS,
+): SyncState {
+  return {
+    schema: SYNC_SCHEMA,
+    schemaVersion: 1,
+    source,
+    scope,
+    talker,
+    lastSuccessfulRun: null,
+    lastAttempt: null,
+    coveredFrom: null,
+    coveredTo: null,
+    checkpoint: { newestCreateTime: null, overlapSeconds },
+    recordsRead: 0,
+    recordsDeduplicated: 0,
+    recordsReturned: 0,
+    shardsRead: 0,
+    shardsFailed: 0,
+    shards: { scanned: 0, opened: 0, failed: 0, items: [] },
+    coverage: 'unverified',
+    mayHaveMore: false,
+    warnings: [],
+    updatedAt: null,
+  }
+}
+
+export class SyncStateStore {
+  constructor(
+    private readonly syncDir: string = SYNC_DIR,
+    private readonly jobsDir: string = JOBS_DIR,
+  ) {}
+
+  statePath(source: string, talker: string): string {
+    return join(this.syncDir, `${source}-${talkerSlug(talker)}.json`)
+  }
+
+  /** 读取检查点。无记录返回 null; schema 不认识则抛错, 不猜测。 */
+  read(source: string, talker: string): SyncState | null {
+    const path = this.statePath(source, talker)
+    const raw = readJson(path)
+    if (raw === null) return null
+    const state = raw as SyncState
+    if (state.schema !== SYNC_SCHEMA) throw new UnknownSchemaError(path, state.schema)
+    return state
+  }
+
+  write(state: SyncState): void {
+    const path = this.statePath(state.source, state.talker)
+    if (!existsSync(this.syncDir)) mkdirSync(this.syncDir, { recursive: true })
+    writeAtomic(path, sanitizeForState({ ...state, schema: SYNC_SCHEMA }))
+  }
+
+  /** 所有会话的检查点, 最近尝试在前。目录缺失或单个文件损坏都不影响其余。 */
+  list(): SyncState[] {
+    try {
+      if (!existsSync(this.syncDir)) return []
+      const states: SyncState[] = []
+      for (const name of readdirSync(this.syncDir)) {
+        if (!name.endsWith('.json')) continue
+        const raw = readJson(join(this.syncDir, name))
+        if (!raw || (raw as SyncState).schema !== SYNC_SCHEMA) continue
+        states.push(raw as SyncState)
+      }
+      return states.sort((a, b) => String(b.lastAttempt ?? '').localeCompare(String(a.lastAttempt ?? '')))
+    } catch {
+      return []
+    }
+  }
+
+  jobPath(jobId: string): string {
+    return join(this.jobsDir, `${jobId}.json`)
+  }
+
+  writeJob(job: JobRecord): void {
+    if (!existsSync(this.jobsDir)) mkdirSync(this.jobsDir, { recursive: true })
+    writeAtomic(this.jobPath(job.jobId), sanitizeForState({ ...job, schema: JOB_SCHEMA }))
+  }
+
+  readJob(jobId: string): JobRecord | null {
+    const path = this.jobPath(jobId)
+    const raw = readJson(path)
+    if (raw === null) return null
+    const job = raw as JobRecord
+    if (job.schema !== JOB_SCHEMA) throw new UnknownSchemaError(path, job.schema)
+    return job
+  }
+
+  /** 最近的 job 记录, 最新在前。 */
+  recentJobs(limit = 10): JobRecord[] {
+    try {
+      if (!existsSync(this.jobsDir)) return []
+      const ids = readdirSync(this.jobsDir)
+        .filter(name => name.endsWith('.json'))
+        .map(name => name.slice(0, -'.json'.length))
+        .sort()
+        .reverse()
+        .slice(0, limit)
+      const jobs: JobRecord[] = []
+      for (const id of ids) {
+        const job = this.readJob(id)
+        if (job) jobs.push(job)
+      }
+      return jobs
+    } catch {
+      return []
+    }
+  }
+}
+
+export const syncStateStore = new SyncStateStore()
+
+/** jobId 形如 job_20260919_0001。同日按时间戳后四位递增, 保证可排序。 */
+export function makeJobId(now = new Date()): string {
+  const stamp = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('')
+  return `job_${stamp}_${String(now.getTime() % 10000).padStart(4, '0')}`
+}

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/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) + '…'
+}