agentquad 0.3.0

package/src/dispatch.js

@@ -0,0 +1,13 @@
+import { SUPPORTED_TOOLS } from './config.js'
+
+export function resolveTool({ channel, userId, chatId, override } = {}, config = {}) {
+  if (override && SUPPORTED_TOOLS.includes(override)) return override
+  const ch = channel ? config?.dispatch?.[channel] : null
+  if (ch) {
+    if (userId && ch.perUser && SUPPORTED_TOOLS.includes(ch.perUser[userId])) return ch.perUser[userId]
+    if (chatId && ch.perChat && SUPPORTED_TOOLS.includes(ch.perChat[chatId])) return ch.perChat[chatId]
+    if (SUPPORTED_TOOLS.includes(ch.default)) return ch.default
+  }
+  if (SUPPORTED_TOOLS.includes(config?.defaultTool)) return config.defaultTool
+  return 'claude'
+}

package/src/export/todoMarkdown.js

@@ -0,0 +1,246 @@
+import { parseTranscriptFile } from '../transcripts/scanner.js'
+import { estimateCost, DEFAULT_PRICING } from '../pricing.js'
+
+const QUADRANT_LABEL = {
+	1: 'Q1 紧急且重要',
+	2: 'Q2 重要不紧急',
+	3: 'Q3 紧急不重要',
+	4: 'Q4 不紧急不重要',
+}
+
+const STATUS_LABEL = {
+	todo: '待办',
+	ai_pending: 'AI 待确认',
+	ai_running: 'AI 进行中',
+	ai_done: 'AI 已完成',
+	done: '已完成',
+}
+
+const ROLE_LABEL = {
+	user: '用户',
+	assistant: 'AI',
+	thinking: '思考',
+	tool_use: '工具调用',
+	tool_result: '工具输出',
+	system: '系统',
+}
+
+export async function buildTodoExport(db, todoId, { turns = 'summary', turnLimit = 80, pricing = DEFAULT_PRICING } = {}) {
+	const todo = db.getTodo(todoId)
+	if (!todo) return null
+	const comments = db.listComments(todoId)
+	const aiSessions = Array.isArray(todo.aiSessions) ? todo.aiSessions : []
+	const subtodos = todo.parentId ? [] : db.listTodos({ quadrant: todo.quadrant }).filter(item => item.parentId === todo.id)
+
+	const sessionRows = []
+	for (const s of aiSessions) {
+		const tool = s?.tool || 'claude'
+		const nativeId = s?.nativeSessionId
+		let file = null
+		if (nativeId) {
+			file = db.findTranscriptByNative(nativeId, tool)
+		}
+		const tokens = file ? {
+			input: file.input_tokens || 0,
+			output: file.output_tokens || 0,
+			cacheRead: file.cache_read_tokens || 0,
+			cacheCreation: file.cache_creation_tokens || 0,
+		} : { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 }
+		const cost = file?.primary_model
+			? estimateCost(tokens, file.primary_model, pricing)
+			: { usd: 0, cny: 0 }
+
+		let loadedTurns = null
+		if (file && turns !== 'none') {
+			try {
+				const parsed = await parseTranscriptFile(tool, file.jsonl_path)
+				loadedTurns = parsed.turns
+			} catch (e) {
+				loadedTurns = []
+			}
+		}
+
+		sessionRows.push({
+			session: s,
+			file,
+			tokens,
+			cost,
+			turns: loadedTurns,
+		})
+	}
+
+	return { todo, comments, sessions: sessionRows, subtodos, generatedAt: Date.now(), turnsMode: turns, turnLimit }
+}
+
+function fmtTokens(n) {
+	if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + 'M'
+	if (n >= 1_000) return (n / 1_000).toFixed(1) + 'K'
+	return String(n)
+}
+
+function fmtCost(c) {
+	if (!c || (!c.usd && !c.cny)) return '—'
+	return `$${c.usd.toFixed(2)} / ¥${c.cny.toFixed(1)}`
+}
+
+function fmtDateTime(ms) {
+	if (!ms) return '—'
+	const d = new Date(ms)
+	const pad = n => String(n).padStart(2, '0')
+	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
+}
+
+function fmtDuration(ms) {
+	if (!ms || ms < 0) return '—'
+	const s = Math.round(ms / 1000)
+	if (s < 60) return `${s}s`
+	const m = Math.floor(s / 60)
+	const sec = s % 60
+	if (m < 60) return `${m}m${sec ? ` ${sec}s` : ''}`
+	const h = Math.floor(m / 60)
+	return `${h}h ${m % 60}m`
+}
+
+function summarizeTurnContent(content, max = 600) {
+	const text = String(content || '').trim()
+	if (text.length <= max) return text
+	return text.slice(0, max) + '…'
+}
+
+function pickHighlightTurns(turns, limit) {
+	const useful = turns.filter(t => t.role === 'user' || t.role === 'assistant')
+	if (useful.length <= limit) return useful
+	const head = Math.ceil(limit / 2)
+	const tail = limit - head
+	return [...useful.slice(0, head), { role: 'separator', content: `… (省略 ${useful.length - limit} 段) …` }, ...useful.slice(-tail)]
+}
+
+export function renderTodoMarkdown(report) {
+	if (!report) return ''
+	const { todo, comments, sessions, subtodos = [], turnsMode, turnLimit } = report
+	const lines = []
+	lines.push(`# ${todo.title}`)
+	lines.push('')
+	const meta = [
+		`**象限**：${QUADRANT_LABEL[todo.quadrant] || todo.quadrant}`,
+		`**状态**：${STATUS_LABEL[todo.status] || todo.status}`,
+	]
+	if (todo.dueDate) meta.push(`**截止**：${fmtDateTime(todo.dueDate)}`)
+	if (todo.workDir) meta.push(`**目录**：\`${todo.workDir}\``)
+	meta.push(`**创建**：${fmtDateTime(todo.createdAt)}`)
+	meta.push(`**更新**：${fmtDateTime(todo.updatedAt)}`)
+	lines.push(meta.join(' · '))
+	lines.push('')
+
+	if (todo.description?.trim()) {
+		lines.push('## 描述')
+		lines.push('')
+		lines.push(todo.description.trim())
+		lines.push('')
+	}
+
+	if (comments.length) {
+		lines.push('## 评论时间线')
+		lines.push('')
+		for (const c of comments) {
+			lines.push(`- **${fmtDateTime(c.createdAt)}** ${c.content.replace(/\n/g, ' ')}`)
+		}
+		lines.push('')
+	}
+
+	if (subtodos.length) {
+		lines.push('## 子待办')
+		lines.push('')
+		for (const subtodo of subtodos) {
+			lines.push(`- [${subtodo.status === 'done' ? 'x' : ' '}] ${subtodo.title}`)
+		}
+		lines.push('')
+	}
+
+	if (sessions.length) {
+		const totals = sessions.reduce((acc, r) => {
+			acc.input += r.tokens.input
+			acc.output += r.tokens.output
+			acc.cacheRead += r.tokens.cacheRead
+			acc.cacheCreation += r.tokens.cacheCreation
+			acc.usd += r.cost.usd
+			acc.cny += r.cost.cny
+			return acc
+		}, { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, usd: 0, cny: 0 })
+		const tokenTotal = totals.input + totals.output + totals.cacheRead + totals.cacheCreation
+
+		lines.push('## AI 会话')
+		lines.push('')
+		lines.push(`共 ${sessions.length} 段 · Token ${fmtTokens(tokenTotal)}（cache 命中 ${fmtTokens(totals.cacheRead)}）· 成本 ${fmtCost(totals)}`)
+		lines.push('')
+
+		sessions.forEach((row, idx) => {
+			const { session, file, tokens, cost, turns } = row
+			const tool = (session?.tool || 'claude').toUpperCase()
+			const startedAt = file?.started_at || session?.startedAt
+			const endedAt = file?.ended_at || session?.completedAt
+			const duration = startedAt && endedAt ? endedAt - startedAt : null
+			const activeMs = file?.active_ms
+
+			lines.push(`### 会话 ${idx + 1} · ${tool}`)
+			const metaLine = [
+				`起始 ${fmtDateTime(startedAt)}`,
+				`时长 ${fmtDuration(duration)}`,
+			]
+			if (activeMs != null) metaLine.push(`活跃 ${fmtDuration(activeMs)}`)
+			if (file?.primary_model) metaLine.push(`模型 \`${file.primary_model}\``)
+			metaLine.push(`Token ${fmtTokens(tokens.input + tokens.output + tokens.cacheRead + tokens.cacheCreation)}`)
+			metaLine.push(`成本 ${fmtCost(cost)}`)
+			lines.push(metaLine.join(' · '))
+			lines.push('')
+
+			if (session?.prompt) {
+				lines.push('**触发 Prompt：**')
+				lines.push('')
+				lines.push('> ' + session.prompt.replace(/\n/g, '\n> '))
+				lines.push('')
+			}
+
+			if (!file) {
+				lines.push('_（未关联到 transcript 文件）_')
+				lines.push('')
+				return
+			}
+
+			if (turnsMode === 'none' || !turns) {
+				if (file.first_user_prompt) {
+					lines.push(`**首条用户消息：** ${file.first_user_prompt}`)
+					lines.push('')
+				}
+				return
+			}
+
+			const picked = pickHighlightTurns(turns, turnLimit)
+			if (turnsMode === 'summary') {
+				lines.push('<details><summary>展开对话节选</summary>')
+				lines.push('')
+			}
+			for (const t of picked) {
+				if (t.role === 'separator') {
+					lines.push(`*${t.content}*`)
+					lines.push('')
+					continue
+				}
+				const label = ROLE_LABEL[t.role] || t.role
+				lines.push(`**【${label}】**`)
+				lines.push('')
+				const body = turnsMode === 'full' ? String(t.content || '') : summarizeTurnContent(t.content)
+				lines.push(body)
+				lines.push('')
+			}
+			if (turnsMode === 'summary') {
+				lines.push('</details>')
+				lines.push('')
+			}
+		})
+	}
+
+	lines.push('---')
+	lines.push(`_生成于 ${fmtDateTime(report.generatedAt)} · AgentQuad_`)
+	return lines.join('\n')
+}

package/src/first-run-wizard.js

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import readline from 'node:readline'
+
+export function shouldRunWizard({ rootDir, isTTY, env, flags }) {
+  if (env.AGENTQUAD_SKIP_WIZARD === '1' || env.AGENTQUAD_SKIP_WIZARD === 'true') return false
+  if (flags?.wizard === false) return false
+  if (!isTTY) return false
+  if (existsSync(join(rootDir, 'config.json'))) return false
+  if (existsSync(join(rootDir, 'data.db'))) return false
+  return true
+}
+
+export function defaultAsk(stdin = process.stdin, stdout = process.stdout) {
+  return (question) => new Promise((resolve) => {
+    const rl = readline.createInterface({ input: stdin, output: stdout })
+    rl.question(question, (ans) => { rl.close(); resolve(ans) })
+  })
+}
+
+export function defaultChecks() {
+  const has = (bin) => spawnSync('command', ['-v', bin], { encoding: 'utf8', shell: '/bin/sh' }).status === 0
+  return { claude: () => has('claude'), codex: () => has('codex') }
+}
+
+export async function defaultInstallTools(tools) {
+  const r = spawnSync(process.execPath, [
+    new URL('./cli.js', import.meta.url).pathname,
+    'install-tools',
+    ...tools.map((t) => `--${t}`),
+    '-y',
+  ], { stdio: 'inherit' })
+  return r.status ?? 1
+}
+
+export async function runFirstRunWizard({
+  checks = defaultChecks(),
+  installTools = defaultInstallTools,
+  ask = defaultAsk(),
+  log = console.log,
+} = {}) {
+  log('\n👋 第一次启动 AgentQuad。\n')
+
+  const claudeOK = checks.claude()
+  const codexOK = checks.codex()
+  const missing = []
+  if (!claudeOK) missing.push('claude')
+  if (!codexOK) missing.push('codex')
+
+  let installedTools = []
+  let skippedInstall = false
+
+  if (missing.length > 0) {
+    log(`[1/2] 检测到未安装：${missing.join(', ')}（AI 终端必需）`)
+    const ans = (await ask(`      运行 'agentquad install-tools --all' 自动安装？(Y/n) `)).trim().toLowerCase()
+    if (ans === '' || ans === 'y' || ans === 'yes') {
+      try {
+        const code = await installTools(missing)
+        if (code === 0) installedTools = [...missing]
+        else log('\n⚠ 工具安装失败，AI 终端将不可用。修复后跑 agentquad install-tools --all\n')
+      } catch (e) {
+        log(`\n⚠ 工具安装异常（${e?.message || e}），AI 终端将不可用。\n`)
+      }
+    } else {
+      skippedInstall = true
+    }
+  }
+
+  const available = []
+  if (claudeOK || installedTools.includes('claude')) available.push('claude')
+  if (codexOK || installedTools.includes('codex')) available.push('codex')
+
+  let defaultTool = 'claude'
+  if (available.length > 0) {
+    const optsStr = available.join(' / ')
+    const ans = (await ask(`[2/2] 选择默认 AI 工具 (${optsStr}) [默认: ${available[0]}]: `)).trim().toLowerCase()
+    defaultTool = available.includes(ans) ? ans : available[0]
+  }
+
+  return { skipped: false, installedTools, defaultTool, skippedInstall }
+}

package/src/git/gitStatus.js

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+
+const DEFAULT_TIMEOUT_MS = 5000
+
+function runGit(args, { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, env, maxBytes } = {}) {
+  return new Promise((resolve) => {
+    let proc
+    try {
+      proc = spawn('git', args, { cwd, env: env || process.env })
+    } catch (e) {
+      resolve({ error: 'spawn_failed', code: e?.code || '', stderr: e?.message || '' })
+      return
+    }
+    let stdout = Buffer.alloc(0)
+    let stderr = ''
+    let truncated = false
+    let settled = false
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      try { proc.kill('SIGTERM') } catch {}
+      resolve({ error: 'timeout' })
+    }, timeoutMs)
+    proc.on('error', (err) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({
+        error: err?.code === 'ENOENT' ? 'git_missing' : 'spawn_failed',
+        code: err?.code || '',
+        stderr: err?.message || '',
+      })
+    })
+    proc.stdout?.on('data', (chunk) => {
+      if (maxBytes && stdout.length + chunk.length > maxBytes) {
+        const remaining = Math.max(0, maxBytes - stdout.length)
+        if (remaining > 0) stdout = Buffer.concat([stdout, chunk.slice(0, remaining)])
+        truncated = true
+        try { proc.kill('SIGTERM') } catch {}
+      } else {
+        stdout = Buffer.concat([stdout, chunk])
+      }
+    })
+    proc.stderr?.on('data', (chunk) => { stderr += chunk.toString() })
+    proc.on('close', (code) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ code, stdout: stdout.toString('utf8'), stderr, truncated })
+    })
+  })
+}
+
+function checkDir(workDir) {
+  if (!workDir || !existsSync(workDir)) return { state: 'not_found' }
+  try {
+    if (!statSync(workDir).isDirectory()) return { state: 'not_found' }
+  } catch {
+    return { state: 'not_found' }
+  }
+  return null
+}
+
+export async function readGitStatus(workDir, opts = {}) {
+  const pre = checkDir(workDir)
+  if (pre) return pre
+
+  const isRepo = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: workDir, ...opts })
+  if (isRepo.error === 'git_missing') return { state: 'git_missing' }
+  if (isRepo.error === 'timeout') return { state: 'timeout' }
+  if (isRepo.error) return { state: 'error', message: (isRepo.stderr || '').slice(0, 500) }
+  if (isRepo.code !== 0 || (isRepo.stdout || '').trim() !== 'true') return { state: 'not_a_repo' }
+
+  const branchRes = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: workDir, ...opts })
+  if (branchRes.error === 'timeout') return { state: 'timeout' }
+  if (branchRes.error) return { state: 'error', message: (branchRes.stderr || '').slice(0, 500) }
+  const branch = (branchRes.stdout || '').trim() || 'HEAD'
+
+  let headShort
+  if (branch === 'HEAD') {
+    const shaRes = await runGit(['rev-parse', '--short=7', 'HEAD'], { cwd: workDir, ...opts })
+    if (shaRes.code === 0) headShort = (shaRes.stdout || '').trim()
+  }
+
+  const statusRes = await runGit(['status', '--porcelain'], { cwd: workDir, ...opts })
+  if (statusRes.error === 'timeout') return { state: 'timeout' }
+  if (statusRes.error) return { state: 'error', message: (statusRes.stderr || '').slice(0, 500) }
+  const dirty = (statusRes.stdout || '').split('\n').filter((l) => l.trim().length > 0).length
+
+  let hasUpstream = false
+  let ahead = 0
+  let behind = 0
+  const revListRes = await runGit(
+    ['rev-list', '--count', '--left-right', '@{upstream}...HEAD'],
+    { cwd: workDir, ...opts }
+  )
+  if (revListRes.error === 'timeout') return { state: 'timeout' }
+  if (!revListRes.error && revListRes.code === 0) {
+    const parts = (revListRes.stdout || '').trim().split(/\s+/)
+    if (parts.length === 2) {
+      hasUpstream = true
+      behind = Number(parts[0]) || 0
+      ahead = Number(parts[1]) || 0
+    }
+  }
+
+  const out = { state: 'ok', branch, dirty, ahead, behind, hasUpstream }
+  if (headShort) out.headShort = headShort
+  return out
+}
+
+export async function readGitDiff(workDir, opts = {}) {
+  const pre = checkDir(workDir)
+  if (pre) return pre
+  const maxBytes = Number.isFinite(opts.maxBytes) ? opts.maxBytes : 200 * 1024
+
+  const isRepo = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: workDir })
+  if (isRepo.error === 'git_missing') return { state: 'git_missing' }
+  if (isRepo.error === 'timeout') return { state: 'timeout' }
+  if (isRepo.error) return { state: 'error', message: (isRepo.stderr || '').slice(0, 500) }
+  if (isRepo.code !== 0 || (isRepo.stdout || '').trim() !== 'true') return { state: 'not_a_repo' }
+
+  const diffRes = await runGit(['diff', 'HEAD'], { cwd: workDir, maxBytes })
+  if (diffRes.error === 'timeout') return { state: 'timeout' }
+  if (diffRes.error) return { state: 'error', message: (diffRes.stderr || '').slice(0, 500) }
+
+  const untrackedRes = await runGit(['ls-files', '--others', '--exclude-standard'], { cwd: workDir })
+  const untracked = untrackedRes.code === 0
+    ? (untrackedRes.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean)
+    : []
+
+  return {
+    state: 'ok',
+    diff: diffRes.stdout || '',
+    untracked,
+    truncated: !!diffRes.truncated,
+  }
+}

package/src/lark-api-client.js

@@ -0,0 +1,205 @@
+import * as Lark from '@larksuiteoapi/node-sdk'
+import { toLarkText } from './lark-markdown.js'
+
+function isBlank(value) {
+  return value == null || String(value) === ''
+}
+
+function normalizePayload(response) {
+  return response?.data || response || null
+}
+
+function normalizeError(error) {
+  // 飞书 SDK 把 axios 错误抛出来，response.data 里有 {code, msg} 是真正的业务错误。
+  // 优先把它捞出来 —— "code 231001: reaction type is invalid" 比 "Request failed with
+  // status code 400" 有用得多。
+  const data = error?.response?.data
+  if (data && typeof data === 'object') {
+    const parts = []
+    if (data.code != null) parts.push(`code ${data.code}`)
+    if (data.msg) parts.push(data.msg)
+    if (parts.length) return parts.join(': ')
+  }
+  return error?.message || error?.description || String(error)
+}
+
+function defaultClientFactory({ appId, appSecret }) {
+  return new Lark.Client({
+    appId,
+    appSecret,
+    appType: Lark.AppType.SelfBuild,
+  })
+}
+
+export function createLarkApiClient({ appId, appSecret, clientFactory = defaultClientFactory, logger = console } = {}) {
+  let client = null
+
+  function hasCredentials() {
+    return !isBlank(appId) && !isBlank(appSecret)
+  }
+
+  function getClient() {
+    if (!hasCredentials()) return null
+    if (!client) client = clientFactory({ appId, appSecret })
+    return client
+  }
+
+  async function sendMessage({ chatId, text } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(chatId)) return { ok: false, reason: 'chatId_required' }
+    if (isBlank(text)) return { ok: false, reason: 'text_required' }
+    try {
+      const response = await getClient().im.message.create({
+        params: { receive_id_type: 'chat_id' },
+        data: {
+          receive_id: String(chatId),
+          msg_type: 'text',
+          content: JSON.stringify({ text: toLarkText(String(text)) }),
+        },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] send failed: ${detail}`)
+      return { ok: false, reason: 'lark_send_failed', detail }
+    }
+  }
+
+  async function replyInThread({ rootMessageId, text } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(rootMessageId)) return { ok: false, reason: 'rootMessageId_required' }
+    if (isBlank(text)) return { ok: false, reason: 'text_required' }
+    try {
+      const response = await getClient().im.message.reply({
+        path: { message_id: String(rootMessageId) },
+        data: {
+          msg_type: 'text',
+          content: JSON.stringify({ text: toLarkText(String(text)) }),
+          reply_in_thread: true,
+        },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] reply failed: ${detail}`)
+      return { ok: false, reason: 'lark_reply_failed', detail }
+    }
+  }
+
+  async function sendCard({ chatId, card } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(chatId)) return { ok: false, reason: 'chatId_required' }
+    if (!card || typeof card !== 'object') return { ok: false, reason: 'card_required' }
+    try {
+      const response = await getClient().im.message.create({
+        params: { receive_id_type: 'chat_id' },
+        data: {
+          receive_id: String(chatId),
+          msg_type: 'interactive',
+          content: JSON.stringify(card),
+        },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] sendCard failed: ${detail}`)
+      return { ok: false, reason: 'lark_send_card_failed', detail }
+    }
+  }
+
+  async function replyWithCard({ rootMessageId, card } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(rootMessageId)) return { ok: false, reason: 'rootMessageId_required' }
+    if (!card || typeof card !== 'object') return { ok: false, reason: 'card_required' }
+    try {
+      const response = await getClient().im.message.reply({
+        path: { message_id: String(rootMessageId) },
+        data: {
+          msg_type: 'interactive',
+          content: JSON.stringify(card),
+          reply_in_thread: true,
+        },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] replyCard failed: ${detail}`)
+      return { ok: false, reason: 'lark_reply_card_failed', detail }
+    }
+  }
+
+  async function addReaction({ messageId, emojiType } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(messageId)) return { ok: false, reason: 'messageId_required' }
+    if (isBlank(emojiType)) return { ok: false, reason: 'emojiType_required' }
+    try {
+      const response = await getClient().im.messageReaction.create({
+        path: { message_id: String(messageId) },
+        data: { reaction_type: { emoji_type: String(emojiType) } },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] reaction failed: ${detail}`)
+      return { ok: false, reason: 'lark_reaction_failed', detail }
+    }
+  }
+
+  async function getMessageResource({ messageId, fileKey, type = 'image' } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(messageId)) return { ok: false, reason: 'messageId_required' }
+    if (isBlank(fileKey)) return { ok: false, reason: 'fileKey_required' }
+    try {
+      const result = await getClient().im.messageResource.get({
+        path: { message_id: String(messageId), file_key: String(fileKey) },
+        params: { type: String(type) },
+      })
+      // SDK 返回 { writeFile(path), getReadableStream(), headers } —— 直接透传
+      return {
+        ok: true,
+        writeFile: result.writeFile,
+        getReadableStream: result.getReadableStream,
+        headers: result.headers,
+      }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] getMessageResource failed: ${detail}`)
+      return { ok: false, reason: 'lark_resource_failed', detail }
+    }
+  }
+
+  async function deleteReaction({ messageId, reactionId } = {}) {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    if (isBlank(messageId)) return { ok: false, reason: 'messageId_required' }
+    if (isBlank(reactionId)) return { ok: false, reason: 'reactionId_required' }
+    try {
+      const response = await getClient().im.messageReaction.delete({
+        path: { message_id: String(messageId), reaction_id: String(reactionId) },
+      })
+      return { ok: true, payload: normalizePayload(response) }
+    } catch (e) {
+      const detail = normalizeError(e)
+      logger.warn?.(`[lark-api] reaction delete failed: ${detail}`)
+      return { ok: false, reason: 'lark_reaction_delete_failed', detail }
+    }
+  }
+
+  async function testConnection() {
+    if (!hasCredentials()) return { ok: false, reason: 'lark_credentials_missing' }
+    try {
+      const sdkClient = getClient()
+      if (sdkClient.auth?.tenantAccessToken?.internal) {
+        await sdkClient.auth.tenantAccessToken.internal({
+          data: { app_id: String(appId), app_secret: String(appSecret) },
+        })
+      } else {
+        await sendMessage({ chatId: '', text: '' })
+      }
+      return { ok: true }
+    } catch (e) {
+      return { ok: false, reason: 'lark_client_init_failed', detail: normalizeError(e) }
+    }
+  }
+
+  return { sendMessage, replyInThread, sendCard, replyWithCard, addReaction, deleteReaction, getMessageResource, testConnection }
+}