lark-relay 0.3.0 → 0.4.1

package/README.md

@@ -12,7 +12,7 @@ lark-relay guide          # 装完先读这个
 
 ## 为什么需要它
 
-Lark 事件是**流式**的 —— 进程不在的时刻,消息**永久丢失**,不是延迟送达
+Lark 事件是**流式**的 -- 进程不在的时刻,消息**永久丢失**,不是延迟送达
 (实测:消息发出 8 秒后才起 consumer,收到 0 条)。
 
 所以要有一个常驻进程只管把事件收下来落盘,消费侧崩了、AI 跑了半小时、
@@ -29,13 +29,13 @@ Lark 事件是**流式**的 —— 进程不在的时刻,消息**永久丢失**,
 | 谁能干 | 任何 agent(Claude Code / Codex / 手敲) | 需内置唤起知识 |
 | 配置 | 纯参数,无文件 | `dispatch.yaml` |
 
-你(AI)在会话里盯群 → `take`。无人在场也要干活 → `dispatch`。
+你(AI)在会话里盯群 -> `take`。无人在场也要干活 -> `dispatch`。
 
 ## 命令
 
 ```bash
-lark-relay collect            # 底座:全部 profile 各起 consume → 原子落盘(systemd 常驻)
-lark-relay take …             # 场景1:阻塞等一批 → 输出 → 退出
+lark-relay collect            # 底座:全部 profile 各起 consume -> 原子落盘(systemd 常驻)
+lark-relay take …             # 场景1:阻塞等一批 -> 输出 -> 退出
 lark-relay dispatch <task>    # 场景2:常驻循环 = take + 唤起 claude
 lark-relay status             # 谁在跑 / 各 app 积压 / 各游标位置
 lark-relay guide              # 一页用法
@@ -47,24 +47,24 @@ lark-relay guide              # 一页用法
 未授权或授权过期的 profile 自动跳过并 warn(永久失败,重试是死循环)。
 
 每 app 一个子进程,某个挂了单独重启不影响其他。回收在本进程内每小时自查,
-删超期的整个日期目录 —— 不另起 gc 单元/timer。
+删超期的整个日期目录 -- 不另起 gc 单元/timer。
 
 ### take
 
-只有一种形态:**阻塞等 → 有一批就输出 → 退出**。循环交给 harness ——
+只有一种形态:**阻塞等 -> 有一批就输出 -> 退出**。循环交给 harness --
 Claude Code 用 `run_in_background` 起,进程退出会主动通知 AI,这才是事件驱动。
 
 ```bash
 lark-relay take --app <app> --chats oc_xxx --render text
 ```
 
-空参数跑一下会输出完整的照做指导(查群 ID → 验 bot 在群 → 监听三步)。
+空参数跑一下会输出完整的照做指导(查群 ID -> 验 bot 在群 -> 监听三步)。
 
 业务过滤只有 `--filter`(jq 表达式)一个口子,不为每个业务加参数。
 
 ### dispatch
 
-任务发现:扫 `$LR_ROOT/*/dispatch.yaml` —— 有文件即是任务,无需注册表。
+任务发现:扫 `$LR_ROOT/*/dispatch.yaml` -- 有文件即是任务,无需注册表。
 `dispatch` 内部就是调 `take`,保证两场景不实现分叉。
 
 ```yaml
@@ -73,26 +73,35 @@ chats: [oc_xxx]
 dirs: [/path/to/repo]            # 首个 = 主工作目录
 instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
 filter: '.mentions[]?.id == "ou_xxx"'   # 可选
-# mode: work        默认;work | chat(见下)
+# mode: work        默认;work | chat | agent(见下)
 # model: <名称>      默认走终端同一套默认路由
 ```
 
-`mode` 就两个场景 —— 一个键定死全部行为,不用拼组合:
+`mode` 三个场景 -- 一个键定死全部行为,不用拼组合:
 
-| | `work`(默认) | `chat` |
-|---|---|---|
-| 用途 | 处理工作 | 日常闲聊 |
-| 回复位置 | 话题内(首问开话题) | 直接发群里 |
-| 过程展示 | COT 消息(实时流式) | 无 |
-| 结论 | 卡片(markdown 渲染) | 纯文本 |
-| session 隔离 | 按 `thread_id`(话题即边界,不滚动) | 按 (群, epoch),空闲超 `idle_gap` 开新世代 |
-| 防抖 | 1s(一问一答要跟手) | 15s(等人打完多行) |
+| | `work`(默认) | `chat` | `agent` |
+|---|---|---|---|
+| 用途 | 处理工作 | 简单问答 | 群运营 |
+| 回复位置 | 话题内(首问开话题) | 直接发群里 | **模型自己决定** |
+| 过程展示 | COT 消息(实时流式) | 无 | 无 |
+| 结论投递 | 引擎发卡片 | 引擎发纯文本 | **引擎不发** |
+| session 隔离 | 按 `thread_id` | 按 (群, epoch) | 按 (群, epoch) |
+| 防抖 | 1s | 15s | 15s |
 
-`work` 的过程与结论是**两条消息** —— COT 消息只承载过程(接口的设计前提),
+`agent` 是给「**多数轮该沉默**」的场景准备的:群运营里绝大多数消息不需要回应,
+而 `work`/`chat` 的提示词都承诺「你的最终回复会被发回群」,等于逼模型每轮说话。
+`agent` 模式下引擎只负责拉起模型、传消息批次、记台账 -- 发不发、回哪条、
+用哪个 bot 身份、发文字还是表情回应,全由模型按 `instructions` 决定(它有
+Bash + lark-cli)。沉默的轮也会进台账,便于事后看它到底判了多少次。
+
+这与「引擎不做权限管控」是同一条思路:**引擎不做回复决策,边界靠 instructions
+到达模型侧**。
+
+`work` 的过程与结论是**两条消息** -- COT 消息只承载过程(接口的设计前提),
 结论另发一条卡片。卡片发送失败会自动降级纯文本,保证结论必达。
 
 ⚠️ **COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74**:老客户端上那条过程消息显示为
-「Completed」(不会崩),结论卡片不受影响 —— 这也是「结论单独发」的价值。
+「Completed」(不会崩),结论卡片不受影响 -- 这也是「结论单独发」的价值。
 
 环境变量:`LR_COT_BATCH_MS`(COT 攒批窗口,默认 1000)、
 `LR_COT_SAY_AS=text|reasoning`(中间文本走正式文本流还是思考流,默认 `text`;
@@ -110,13 +119,13 @@ filter: '.mentions[]?.id == "ou_xxx"'   # 可选
 判据:能随时删掉重建的才放这里。`ledger` 是唯一不能重建的东西
 (session 会因空闲滚动/过期丢上下文,结论不能丢),走文件系统级备份。
 
-多消费者**共享 store、各持游标**,不做「处理完即删」—— 谁都不能替别人删。
+多消费者**共享 store、各持游标**,不做「处理完即删」-- 谁都不能替别人删。
 盯同一 app 请用不同 `--name` 隔离游标。
 
 ## 设计取舍
 
-- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp → rename`(同目录原子)。
-  不用 `--output-dir` —— 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
+- **原子落盘**:collect 读 stdout NDJSON 后自己 `写 .tmp -> rename`(同目录原子)。
+  不用 `--output-dir` -- 它先建 0 字节再填充,消费侧游标可能跨过半成品导致事件永久丢失
 - **一事件一文件 + 按天分目录**:不用追加式 NDJSON。因为多消费者共享 store 时
   两种方案都不能「处理完即删」,NDJSON 最大的优势(删除简单)失效,而它的 gc
   要按大小滚动 + 保留 N 个文件,反而比整目录删复杂

package/bin/lark-relay.js

@@ -8,11 +8,33 @@ if (!/utf-?8/i.test(process.env.LC_ALL || process.env.LC_CTYPE || process.env.LA
   process.env.LC_ALL = 'C.UTF-8'
 }
 
-const { parseArgs, num, list } = require('../lib/args')
+const { parseArgs, num, list, suggest } = require('../lib/args')
 const help = require('../lib/help')
 
 const VERSION = require('../package.json').version
 
+// 各命令的带值参数白名单(布尔开关在 parseArgs 的 flags 里)。
+// 不在白名单的 --xxx 一律硬报错 —— 拼错参数静默吞掉是实测事故:
+// --chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working
+const TAKE_KEYS = ['app', 'chats', 'name', 'filter', 'debounce', 'max-wait', 'timeout', 'render', 'since']
+const COLLECT_KEYS = ['exclude', 'retain', 'ledger-retain']
+
+// 未知参数 -> stderr 短错误 + 候选提示,exit 2。不打印完整用法 —— 那看着像 --help 成功
+function rejectUnknown(cmd, unknown, allowed) {
+  const names = [...new Set(unknown)]
+  const shown = names.map((k) => `--${k}`).join(', ')
+  let hint = ''
+  for (const k of names) {
+    const s = suggest(k, allowed)
+    if (s) {
+      hint = `\n你是不是想写 --${s}?`
+      break
+    }
+  }
+  process.stderr.write(`未知参数:${shown}${hint}\n跑 \`lark-relay ${cmd}\` 看完整用法\n`)
+  return 2
+}
+
 const USAGE = `lark-relay ${VERSION} —— Lark 事件中继站
 
   lark-relay collect            底座:全部 profile 各起 consume → 原子落盘（systemd 常驻）
@@ -57,7 +79,8 @@ async function main() {
 }
 
 async function cmdCollect(argv) {
-  const a = parseArgs(argv, { flags: ['help'] })
+  const a = parseArgs(argv, { flags: ['help'], keys: COLLECT_KEYS })
+  if (a._unknown.length) return rejectUnknown('collect', a._unknown, COLLECT_KEYS)
   if (a.help) {
     process.stdout.write(`${help.COLLECT_HELP}\n`)
     return 0
@@ -71,11 +94,14 @@ async function cmdCollect(argv) {
 }
 
 async function cmdTake(argv) {
-  const a = parseArgs(argv, { flags: ['help'] })
+  const a = parseArgs(argv, { flags: ['help'], keys: TAKE_KEYS })
+  if (a._unknown.length) return rejectUnknown('take', a._unknown, TAKE_KEYS)
   const larkcli = require('../lib/larkcli')
 
-  // 空参数输出完整照做指导,而非报错 —— AI 的真实行为是「先空参数跑一下看看」
-  if (a.help || (!a.app && !a.chats)) {
+  // 空参数输出完整照做指导,而非报错 —— AI 的真实行为是「先空参数跑一下看看」。
+  // 但带了参数又缺 app/chats 的走下面短错误 —— 打印完整用法和 --help 长得一样,
+  // 会被当成「正常退出但没消息」(实测漏看 bot 第一条 Working)。
+  if (a.help || argv.length === 0) {
     let apps = []
     try {
       apps = (await larkcli.listProfiles()).filter((p) => p.usable).map((p) => p.name)
@@ -157,7 +183,8 @@ async function cmdTake(argv) {
 }
 
 async function cmdStatus(argv) {
-  const a = parseArgs(argv, { flags: ['json', 'help'] })
+  const a = parseArgs(argv, { flags: ['json', 'help'], keys: [] })
+  if (a._unknown.length) return rejectUnknown('status', a._unknown, ['json'])
   if (a.help) {
     process.stdout.write(`${help.STATUS_HELP}\n`)
     return 0
@@ -170,7 +197,8 @@ async function cmdStatus(argv) {
 }
 
 async function cmdDispatch(argv) {
-  const a = parseArgs(argv, { flags: ['list', 'once', 'help'] })
+  const a = parseArgs(argv, { flags: ['list', 'once', 'help'], keys: [] })
+  if (a._unknown.length) return rejectUnknown('dispatch', a._unknown, ['list', 'once'])
   if (a.help) {
     process.stdout.write(`${help.DISPATCH_HELP}\n`)
     return 0

package/lib/args.js

@@ -1,9 +1,14 @@
 'use strict'
 
 // 零依赖 argv 解析。只支持 --key value / --key=value / --flag。
+// spec.flags:布尔开关;spec.keys:带值选项。不在两者里的 --xxx 进 out._unknown,
+// 由调用侧硬报错 —— 拼错参数必须当场失败,不能静默吞掉
+// (实测:--chat-id 拼错 -> 打印用法退出,看着像「正常退出但没消息」,漏看 bot 第一条 Working)
 function parseArgs(argv, spec = {}) {
   const flags = new Set(spec.flags || [])
-  const out = { _: [] }
+  const keys = new Set(spec.keys || [])
+  const known = (k) => flags.has(k) || keys.has(k)
+  const out = { _: [], _unknown: [] }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--') {
@@ -16,17 +21,26 @@ function parseArgs(argv, spec = {}) {
     }
     const eq = a.indexOf('=')
     if (eq !== -1) {
-      out[a.slice(2, eq)] = a.slice(eq + 1)
+      const k = a.slice(2, eq)
+      if (known(k)) out[k] = a.slice(eq + 1)
+      else out._unknown.push(k)
       continue
     }
     const key = a.slice(2)
+    if (!known(key)) {
+      out._unknown.push(key)
+      // 吞掉它的值,避免下一个非 -- 参数错位成位置参数
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) i++
+      continue
+    }
     if (flags.has(key)) {
       out[key] = true
       continue
     }
     const next = argv[i + 1]
     if (next === undefined || next.startsWith('--')) {
-      out[key] = true // 当成 flag,由调用侧校验
+      out[key] = true // 缺值,由调用侧校验
     } else {
       out[key] = next
       i++
@@ -49,4 +63,41 @@ function list(v) {
     .filter(Boolean)
 }
 
-module.exports = { parseArgs, num, list }
+function levenshtein(a, b) {
+  const m = a.length
+  const n = b.length
+  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)])
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+    }
+  }
+  return dp[m][n]
+}
+
+// 拼错参数时给个候选:编辑距离 <= 2,或前 4 字符前缀相同(--chat-id -> --chats)。
+// 都不沾边返回 null,不硬猜。
+function suggest(unknown, allowed) {
+  let best = null
+  let bestD = Infinity
+  for (const k of allowed) {
+    const d = levenshtein(unknown, k)
+    if (d < bestD) {
+      bestD = d
+      best = k
+    }
+  }
+  if (bestD <= 2) return best
+  if (unknown.length >= 4) {
+    const hit = allowed.find((k) => k.startsWith(unknown.slice(0, 4)))
+    if (hit) return hit
+  }
+  return null
+}
+
+module.exports = { parseArgs, num, list, suggest }

package/lib/claude.js

@@ -46,12 +46,34 @@ function sessionEpoch(stateDir, task, chatId, idleGap) {
   return epoch
 }
 
-const PROMPT_TEMPLATE = (batch) =>
-  `下面是飞书群里最新一批消息。请把它们当作针对本仓库(当前工作目录)的任务来处理:定位/分析/修复/测试。处理完后,你的最终回复会被原样发回该群,请直接面向群里的人简洁说明你做了什么、发现了什么、需要什么确认。
+// 提示词按 mode 分流 —— 两类场景对模型的要求根本不同。
+// work/chat:模型产出一段结论,由 dispatch 发回群(模型不碰发送)。
+// agent:模型自己决定发不发、发给谁、用谁的身份、发文字还是表情 ——
+//   引擎不做回复决策,和「引擎不做权限管控」是同一条思路:边界靠 instructions 到达模型侧。
+const PROMPTS = {
+  task: (batch) =>
+    `下面是飞书群里最新一批消息。请把它们当作针对本仓库(当前工作目录)的任务来处理:定位/分析/修复/测试。处理完后,你的最终回复会被原样发回该群,请直接面向群里的人简洁说明你做了什么、发现了什么、需要什么确认。
 
 ===== 群消息 =====
 ${batch}
-===== 结束 =====`
+===== 结束 =====`,
+
+  agent: (batch) =>
+    `下面是飞书群里最新一批消息。
+
+**本轮的发送完全由你负责** —— 没有任何东西会被自动发回群。按你的职责文档判断:
+该不该回应、回应哪一条、用哪个身份、发文字还是表情回应、要不要执行既定任务。
+需要发送时自己用 lark-cli 完成。
+
+**多数情况下正确的选择是什么都不做** —— 不要为了有所动作而发言。
+
+处理完请用一句话说明你做了什么(如「用可莉回复了接梗」「无 @ 我方,沉默」),
+这句话只进台账供事后回溯,不会发到群里。
+
+===== 群消息 =====
+${batch}
+===== 结束 =====`,
+}
 
 /**
  * 起一轮 headless claude。
@@ -206,4 +228,4 @@ function shellQuote(s) {
   return `'${String(s).replace(/'/g, `'\\''`)}'`
 }
 
-module.exports = { runClaude, deriveUuid, sessionEpoch, PROMPT_TEMPLATE }
+module.exports = { runClaude, deriveUuid, sessionEpoch, PROMPTS }

package/lib/dispatch.js

@@ -122,7 +122,7 @@ async function handleGroup(t, group, opts = {}) {
 
     const res = await claude.runClaude({
       cwd,
-      prompt: claude.PROMPT_TEMPLATE(batch),
+      prompt: claude.PROMPTS[mode.prompt](batch),
       uuid,
       instructions: insPath,
       addDirs,
@@ -139,14 +139,19 @@ async function handleGroup(t, group, opts = {}) {
         : null,
     })
 
+    // 兜底文案分两套:要发回群的(deliver != none)面向群里的人写,
+    // agent 模式的 final 只进台账,不该出现「稍后重试或换个说法」这种对人说的话
     let final = (res.final || '').trim()
     if (!final) {
-      final =
-        res.rc === 0
-          ? '(完成,但没拿到最终结论)'
-          : `⚠️ 处理超时或异常(rc=${res.rc})。稍后重试或换个说法。\n\n错误:${String(res.err)
-              .replace(/\n/g, ' ')
-              .slice(-300)}`
+      const errTail = String(res.err).replace(/\n/g, ' ').slice(-300)
+      if (mode.deliver === 'none') {
+        final = res.rc === 0 ? '(本轮无自述)' : `(异常 rc=${res.rc}) ${errTail}`
+      } else {
+        final =
+          res.rc === 0
+            ? '(完成,但没拿到最终结论)'
+            : `⚠️ 处理超时或异常(rc=${res.rc})。稍后重试或换个说法。\n\n错误:${errTail}`
+      }
     }
 
     // 收尾必须包 try/catch:handleGroup 外层只有 try/finally(无 catch),
@@ -161,12 +166,15 @@ async function handleGroup(t, group, opts = {}) {
       }
     }
 
-    // 结论**总是单独一条**:work 发卡片(markdown 渲染、不受 3500 字符分片限制),
-    // chat 发纯文本。卡片失败降级纯文本 —— 保证结论必达
-    const sent = mode.card
-      ? await sendCard(final, { profile, chatId, replyTo: lastMsg, inThread: mode.thread })
-      : false
-    if (!sent) await reply(profile, chatId, lastMsg, final, { inThread: mode.thread })
+    // 结论投递:card = 卡片(markdown 渲染、不受 3500 字符分片限制),失败降级纯文本;
+    // text = 纯文本;none = **引擎不发**,agent 模式下模型已自己发过了,
+    // final 只是它的一句自述(进台账供回溯)
+    if (mode.deliver !== 'none') {
+      const sent = mode.deliver === 'card'
+        ? await sendCard(final, { profile, chatId, replyTo: lastMsg, inThread: mode.thread })
+        : false
+      if (!sent) await reply(profile, chatId, lastMsg, final, { inThread: mode.thread })
+    }
 
     ledgerAppend(task, chatId, epoch, batch, final)
     process.stderr.write(

package/lib/help.js

@@ -89,16 +89,20 @@ dispatch.yaml（4 必填 + 3 可选）
   dirs: [/path/to/repo]            # 首个 = 主工作目录
   instructions: ./instructions.md  # 职责/边界,--append-system-prompt-file 注入
   filter: '.mentions[]?.id == "ou_xxx"'   # 可选
-  # mode: work        默认;work | chat（见下）
+  # mode: work        默认;work | chat | agent（见下）
   # model: <名称>      默认走终端同一套默认路由
 
-mode 两个场景（一个键定死全部行为,不用拼组合）
+mode 三个场景（一个键定死全部行为,不用拼组合）
   work   处理工作:话题内回复 + 过程挂 COT 消息 + 结论发卡片
          + 按 thread_id 隔离 session + 防抖 1s（一问一答要跟手）
          COT 要求客户端 PC ≥ 7.70 / 移动 ≥ 7.74;老客户端那条过程消息显示为
          「Completed」（不崩）,结论卡片不受影响
-  chat   日常闲聊:直发群里 + 纯文本 + 按（群, epoch）隔离 session
+  chat   简单问答:直发群里 + 纯文本 + 按（群, epoch）隔离 session
          + 防抖 15s（等人打完多行）
+  agent  模型自己当运营者:引擎只拉起它 + 传消息 + 记台账,**一条消息都不发**。
+         发不发 / 回哪条 / 用哪个 bot 身份 / 文字还是表情,全由模型按
+         instructions 决定（它有 Bash + lark-cli）。适合「多数轮该沉默」的
+         群运营 —— work/chat 会逼模型每轮都产出一段发回群的话
 
 最佳实践
   · 边界写 instructions,别指望 --add-dir 目录的 CLAUDE.md（启动不加载）

package/lib/tasks.js

@@ -106,14 +106,17 @@ function scalar(s) {
 
 const REQUIRED = ['app', 'chats', 'dirs', 'instructions']
 
-// 两个场景,不是几个正交开关的组合 —— 一个 mode 键定死全部行为。
-// 此前是 session(thread|idle) × display(card|cot|final) 交叉出 6 种组合,
-// 而 session 一个键实际控制三件事(隔离方式、是否开话题、防抖默认值)。
+// 三个场景,不是几个正交开关的组合 —— 一个 mode 键定死全部行为。
+// deliver 决定「结论由谁发」:card/text = 引擎发,none = 模型自己发。
 const MODES = {
   // 日常闲聊:群里直接对话,不开话题
-  chat: { thread: false, cot: false, card: false, debounce: 15 },
+  chat: { thread: false, cot: false, deliver: 'text', prompt: 'task', debounce: 15 },
   // 处理工作:话题内一问一答,过程挂 COT,结论发卡片
-  work: { thread: true, cot: true, card: true, debounce: 1 },
+  work: { thread: true, cot: true, deliver: 'card', prompt: 'task', debounce: 1 },
+  // 模型自己当运营者:引擎只拉起它 + 传消息 + 记台账,**不发任何消息**。
+  // 发不发、回哪条、用谁的身份、文字还是表情,全由模型按 instructions 决定
+  // (它有 Bash + lark-cli)。多数轮的正解是沉默 —— 引擎不该逼它每轮都说话
+  agent: { thread: false, cot: false, deliver: 'none', prompt: 'agent', debounce: 15 },
 }
 
 function validate(name, cfg, taskDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Lark event relay: collect events to disk, take a batch when you need it, or dispatch work to an AI agent.",
   "keywords": [
     "lark",