agentquad 0.3.0

package/src/lark-event-client.js

@@ -0,0 +1,107 @@
+import * as Lark from '@larksuiteoapi/node-sdk'
+
+function isBlank(value) {
+  return value == null || String(value) === ''
+}
+
+function normalizeError(error) {
+  return error?.message || error?.description || String(error)
+}
+
+function defaultDispatcherFactory() {
+  return new Lark.EventDispatcher({})
+}
+
+function defaultWsClientFactory({ appId, appSecret }) {
+  return new Lark.WSClient({
+    appId,
+    appSecret,
+    appType: Lark.AppType.SelfBuild,
+    loggerLevel: Lark.LoggerLevel?.info,
+  })
+}
+
+export function createLarkEventClient({
+  appId,
+  appSecret,
+  onEvent,
+  onCardAction = null,
+  dispatcherFactory = defaultDispatcherFactory,
+  wsClientFactory = defaultWsClientFactory,
+  logger = console,
+} = {}) {
+  if (typeof onEvent !== 'function') throw new Error('onEvent_required')
+
+  let wsClient = null
+  let running = false
+  let lastReason = null
+  let lastDetail = null
+
+  function hasCredentials() {
+    return !isBlank(appId) && !isBlank(appSecret)
+  }
+
+  async function start() {
+    if (!hasCredentials()) {
+      lastReason = 'lark_credentials_missing'
+      lastDetail = null
+      return { ok: false, reason: 'lark_credentials_missing' }
+    }
+    if (running) return { ok: true, action: 'already_running' }
+
+    try {
+      const handlers = {
+        'im.message.receive_v1': async (data) => {
+          try {
+            await onEvent(data)
+          } catch (e) {
+            const detail = normalizeError(e)
+            logger.warn?.(`[lark-event] lark_event_handler_failed: ${detail}`)
+          }
+        },
+      }
+      if (typeof onCardAction === 'function') {
+        handlers['card.action.trigger'] = async (data) => {
+          try {
+            return await onCardAction(data)
+          } catch (e) {
+            const detail = normalizeError(e)
+            logger.warn?.(`[lark-event] lark_card_action_handler_failed: ${detail}`)
+          }
+        }
+      }
+      const eventDispatcher = dispatcherFactory().register(handlers)
+      wsClient = wsClientFactory({ appId, appSecret })
+      wsClient.start({ eventDispatcher })
+      running = true
+      lastReason = null
+      lastDetail = null
+      return { ok: true, action: 'started' }
+    } catch (e) {
+      running = false
+      wsClient = null
+      lastReason = 'lark_ws_start_failed'
+      lastDetail = normalizeError(e)
+      logger.warn?.(`[lark-event] websocket start failed: ${lastDetail}`)
+      return { ok: false, reason: lastReason, detail: lastDetail }
+    }
+  }
+
+  async function stop() {
+    running = false
+    const current = wsClient
+    wsClient = null
+    if (current?.stop) await current.stop()
+    return { ok: true }
+  }
+
+  function describe() {
+    return {
+      running,
+      reason: lastReason,
+      detail: lastDetail,
+    }
+  }
+
+  return { start, stop, describe }
+}

package/src/lark-image.js

@@ -0,0 +1,99 @@
+/**
+ * 把飞书入站图片下载到本地，让 PTY stdin 写 `@<path>` 喂给 Claude Code attach。
+ *
+ * 流程：
+ *   1) lark-api-client.getMessageResource({messageId, fileKey, type:'image'}) → SDK
+ *      返回 { writeFile, getReadableStream, headers }
+ *   2) 根据 headers['content-type'] 推扩展名（image/png → png, image/jpeg → jpg, ...）
+ *   3) writeFile 落到 ~/.agentquad/lark-uploads/<ts>-<rand>.<ext>
+ *   4) 返回本地绝对路径
+ *
+ * 不主动清理：磁盘占用可忽略（图片量级一般几百 KB）。
+ */
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const DEFAULT_DIR = join(DEFAULT_ROOT_DIR, 'lark-uploads')
+
+const CONTENT_TYPE_TO_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+  'image/bmp': 'bmp',
+}
+
+export function extFromContentType(headers) {
+  const ct = String(
+    headers?.['content-type']
+    || headers?.['Content-Type']
+    || ''
+  ).toLowerCase()
+  for (const [type, ext] of Object.entries(CONTENT_TYPE_TO_EXT)) {
+    if (ct.includes(type)) return ext
+  }
+  return 'bin'
+}
+
+/**
+ * @param opts.apiClient lark-api-client 实例（或类似 shape：必须有 getMessageResource）
+ * @param opts.messageId 飞书 message_id（图片所在的消息）
+ * @param opts.imageKey content.image_key（普通 image 消息）或 post 里 img 节点的 image_key
+ * @param opts.destDir 目标目录（默认 ~/.agentquad/lark-uploads）
+ * @returns {Promise<{ ok: true, localPath } | { ok: false, reason, detail? }>}
+ */
+export async function downloadLarkImage({ apiClient, messageId, imageKey, destDir = DEFAULT_DIR } = {}) {
+  if (!apiClient?.getMessageResource) return { ok: false, reason: 'apiClient_required' }
+  if (!messageId) return { ok: false, reason: 'messageId_required' }
+  if (!imageKey) return { ok: false, reason: 'imageKey_required' }
+
+  const r = await apiClient.getMessageResource({ messageId, fileKey: imageKey, type: 'image' })
+  if (!r?.ok) return { ok: false, reason: r?.reason || 'lark_resource_failed', detail: r?.detail }
+  if (typeof r.writeFile !== 'function') return { ok: false, reason: 'no_writefile' }
+
+  try {
+    mkdirSync(destDir, { recursive: true })
+  } catch (e) {
+    return { ok: false, reason: 'mkdir_failed', detail: e.message }
+  }
+  const ext = extFromContentType(r.headers || {})
+  const localName = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`
+  const localPath = join(destDir, localName)
+  try {
+    await r.writeFile(localPath)
+  } catch (e) {
+    return { ok: false, reason: 'write_failed', detail: e.message }
+  }
+  return { ok: true, localPath }
+}
+
+/**
+ * 从飞书 message 提取所有 image_key。
+ * 普通 image 消息：content.image_key。
+ * post 富文本：content.content[][].tag === 'img' 节点的 image_key。
+ */
+export function extractImageKeys(message = {}) {
+  const keys = []
+  let content = message.content
+  if (typeof content === 'string') {
+    try { content = JSON.parse(content) } catch { content = null }
+  }
+  if (!content || typeof content !== 'object') return keys
+  if (typeof content.image_key === 'string' && content.image_key) {
+    keys.push(content.image_key)
+  }
+  if (Array.isArray(content.content)) {
+    for (const line of content.content) {
+      if (!Array.isArray(line)) continue
+      for (const node of line) {
+        if (node?.tag === 'img' && typeof node.image_key === 'string' && node.image_key) {
+          keys.push(node.image_key)
+        }
+      }
+    }
+  }
+  return keys
+}

package/src/lark-markdown.js

@@ -0,0 +1,51 @@
+/**
+ * 飞书 text 消息不渲染 markdown，把常见 markdown 语法降级为可读纯文本。
+ * 主线场景：把 LLM/AgentQuad 输出的 markdown 长文本干净地推到飞书 thread。
+ *
+ * 处理范围（按顺序）：
+ *   - 代码块 ```lang ... ``` → 去掉栅栏，保留内容
+ *   - 图片 ![alt](url)        → 删掉
+ *   - 链接 [text](url)        → "text (url)"，text==url 时只保留 url
+ *   - 标题 #..######          → 去掉 # 前缀
+ *   - 引用 >                  → 去掉 > 前缀
+ *   - 粗体 **x** / __x__      → x
+ *   - 斜体 *x* / _x_          → x（用前后界判断避免吃 list bullet）
+ *   - 删除线 ~~x~~            → x
+ *   - 水平线 --- / *** / ___  → ——————
+ *   - 转义 \* \_ \` 等         → * _ `
+ *
+ * 不处理：
+ *   - inline code `code` 保留 backticks（视觉提示），飞书原样显示
+ *   - 表格 | a | b |            保留原样（飞书不渲染但能读）
+ *   - 列表标记 - / * / 1.      保留
+ */
+export function toLarkText(text) {
+  if (text == null) return ''
+  if (typeof text !== 'string') return String(text)
+  let out = text
+  // 代码块（带或不带语言）
+  out = out.replace(/```[a-zA-Z0-9_+-]*\n?([\s\S]*?)```/g, '$1')
+  // 图片
+  out = out.replace(/!\[[^\]]*\]\([^)]+\)/g, '')
+  // 链接
+  out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label, url) =>
+    label === url ? url : `${label} (${url})`
+  )
+  // 标题（行首 1-6 个 #）
+  out = out.replace(/^#{1,6}\s+/gm, '')
+  // 引用
+  out = out.replace(/^>\s?/gm, '')
+  // 粗体 **x** / __x__
+  out = out.replace(/\*\*([^*\n]+?)\*\*/g, '$1')
+  out = out.replace(/__([^_\n]+?)__/g, '$1')
+  // 斜体 *x* / _x_：用 lookbehind 避免吃 list bullet 和反斜杠转义的 *
+  out = out.replace(/(?<![\\*\w])\*([^*\n]+?)(?<!\\)\*(?!\w)/g, '$1')
+  out = out.replace(/(?<![\\_\w])_([^_\n]+?)(?<!\\)_(?!\w)/g, '$1')
+  // 删除线
+  out = out.replace(/~~([^~\n]+?)~~/g, '$1')
+  // 水平线（整行只有 --- / *** / ___ 至少 3 个）
+  out = out.replace(/^\s*([-*_])\1{2,}\s*$/gm, '——————————')
+  // backslash 转义
+  out = out.replace(/\\([\\*_`~\[\]()#+\-.!|>])/g, '$1')
+  return out
+}

package/src/lark-video.js

@@ -0,0 +1,163 @@
+/**
+ * 飞书视频入站：跟 lark-image 类似，但用 getMessageResource(type:'file')。
+ *
+ * 实测飞书发视频时，事件 shape 是：
+ *   msg_type: 'post'
+ *   content: { title:'', content: [[{ tag:'media', file_key:'file_v3_xxx', image_key:'img_v3_xxx' }]] }
+ *
+ * 也可能（理论上 / 其他版本）出现：
+ *   msg_type: 'media' / 'video', 顶层 content.file_key
+ *   msg_type: 'file',  content.file_key + file_name 后缀是视频
+ *
+ * extractVideoFileKey 把以上几种 shape 都覆盖。
+ */
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const DEFAULT_DIR = join(DEFAULT_ROOT_DIR, 'lark-uploads')
+
+const CONTENT_TYPE_TO_EXT = {
+  'video/mp4': 'mp4',
+  'video/quicktime': 'mov',
+  'video/x-msvideo': 'avi',
+  'video/x-matroska': 'mkv',
+  'video/webm': 'webm',
+  'video/3gpp': '3gp',
+  'video/mpeg': 'mpeg',
+}
+
+export function videoExtFromContentType(headers) {
+  const ct = String(
+    headers?.['content-type']
+    || headers?.['Content-Type']
+    || ''
+  ).toLowerCase()
+  for (const [type, ext] of Object.entries(CONTENT_TYPE_TO_EXT)) {
+    if (ct.includes(type)) return ext
+  }
+  return 'mp4'  // 飞书视频默认 mp4，未知 mime 兜底成 mp4 比 bin 更安全
+}
+
+const VIDEO_MSG_TYPES = new Set(['media', 'video'])
+const VIDEO_FILE_NAME_RE = /\.(mp4|mov|m4v|webm|mkv|avi|3gp|mpeg|mpg|wmv|flv)$/i
+
+/**
+ * 从飞书 message 提取视频 file_key。
+ *
+ * 识别优先级：
+ *   ① post 富文本里的 media 节点 —— 实测飞书发视频走的就是这条
+ *   ② msg_type ∈ {media, video} → content.file_key（顶层）
+ *   ③ msg_type='file' 且 file_name 是视频后缀 → content.file_key
+ *   ④ 兜底嵌套：content.video.file_key / content.media.file_key
+ *   ⑤ 兜底：未知 msg_type 但 content 里有 file_key + 文件名是视频后缀
+ *
+ * @returns {{ fileKey: string, fileName: string|null, duration: number|null, msgType: string|null } | null}
+ */
+export function extractVideoFileKey(message = {}) {
+  if (!message || typeof message !== 'object') return null
+  const msgType = message.msg_type || message.message_type || null
+
+  let content = message.content
+  if (typeof content === 'string') {
+    try { content = JSON.parse(content) } catch { content = null }
+  }
+  if (!content || typeof content !== 'object') return null
+
+  // ① post 富文本里的 media 节点
+  if (Array.isArray(content.content)) {
+    for (const line of content.content) {
+      if (!Array.isArray(line)) continue
+      for (const node of line) {
+        if (node && node.tag === 'media' && typeof node.file_key === 'string' && node.file_key) {
+          return {
+            fileKey: node.file_key,
+            fileName: typeof node.file_name === 'string' ? node.file_name : null,
+            duration: typeof node.duration === 'number' ? node.duration : null,
+            msgType,
+          }
+        }
+      }
+    }
+  }
+
+  // ②③④⑤ 顶层 / 嵌套 file_key
+  const fileKey = pickFirstString([
+    content.file_key,
+    content.video && content.video.file_key,
+    content.media && content.media.file_key,
+  ])
+  if (!fileKey) return null
+
+  const fileName = pickFirstString([
+    content.file_name,
+    content.video && content.video.file_name,
+    content.media && content.media.file_name,
+  ]) || null
+
+  let claim = false
+  if (msgType && VIDEO_MSG_TYPES.has(String(msgType).toLowerCase())) {
+    claim = true
+  } else if (fileName && VIDEO_FILE_NAME_RE.test(fileName)) {
+    claim = true
+  }
+  if (!claim) return null
+
+  const duration = typeof content.duration === 'number' ? content.duration : null
+
+  return { fileKey, fileName, duration, msgType }
+}
+
+function pickFirstString(candidates) {
+  for (const c of candidates) {
+    if (typeof c === 'string' && c) return c
+  }
+  return null
+}
+
+/**
+ * @param opts.apiClient lark-api-client 实例（必须有 getMessageResource）
+ * @param opts.messageId 飞书 message_id
+ * @param opts.fileKey content.file_key 或 post media 节点的 file_key
+ * @param opts.fileName 用于推扩展名（可选；优先级低于 content-type）
+ * @param opts.destDir 目标目录
+ * @returns {Promise<{ ok: true, localPath } | { ok: false, reason, detail? }>}
+ */
+export async function downloadLarkVideo({
+  apiClient,
+  messageId,
+  fileKey,
+  fileName = null,
+  destDir = DEFAULT_DIR,
+} = {}) {
+  if (!apiClient?.getMessageResource) return { ok: false, reason: 'apiClient_required' }
+  if (!messageId) return { ok: false, reason: 'messageId_required' }
+  if (!fileKey) return { ok: false, reason: 'fileKey_required' }
+
+  const r = await apiClient.getMessageResource({ messageId, fileKey, type: 'file' })
+  if (!r?.ok) return { ok: false, reason: r?.reason || 'lark_resource_failed', detail: r?.detail }
+  if (typeof r.writeFile !== 'function') return { ok: false, reason: 'no_writefile' }
+
+  try {
+    mkdirSync(destDir, { recursive: true })
+  } catch (e) {
+    return { ok: false, reason: 'mkdir_failed', detail: e.message }
+  }
+
+  let ext = videoExtFromContentType(r.headers || {})
+  if (ext === 'mp4' && fileName) {
+    const dot = fileName.lastIndexOf('.')
+    if (dot > 0 && dot < fileName.length - 1) {
+      const guess = fileName.slice(dot + 1).toLowerCase()
+      if (/^[a-z0-9]{2,5}$/.test(guess)) ext = guess
+    }
+  }
+  const localName = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`
+  const localPath = join(destDir, localName)
+  try {
+    await r.writeFile(localPath)
+  } catch (e) {
+    return { ok: false, reason: 'write_failed', detail: e.message }
+  }
+  return { ok: true, localPath }
+}

package/src/mcp/audit.js

@@ -0,0 +1,34 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * 简单的 NDJSON 审计日志：每次破坏性 MCP 工具真执行后追加一行。
+ *
+ * rootDir 通常是 ~/.agentquad；文件名固定为 mcp-audit.log。
+ * 调用失败（磁盘只读等）不影响主流程——静默降级。
+ */
+export function createAuditLog({ rootDir, filename = 'mcp-audit.log' } = {}) {
+  if (!rootDir) throw new Error('rootDir_required')
+  const path = join(rootDir, filename)
+
+  function ensureDir() {
+    const dir = dirname(path)
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  }
+
+  function append(entry) {
+    try {
+      ensureDir()
+      const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        ...entry,
+      }) + '\n'
+      appendFileSync(path, line, 'utf8')
+      return { ok: true }
+    } catch (e) {
+      return { ok: false, error: e?.message }
+    }
+  }
+
+  return { append, path }
+}

package/src/mcp/server.js

@@ -0,0 +1,83 @@
+import express from 'express'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { registerReadTools } from './tools/read/index.js'
+import { registerWriteTools } from './tools/write/index.js'
+import { registerDestructiveTools } from './tools/destructive/index.js'
+import { registerOpenClawTools } from './tools/openclaw/index.js'
+import { createAuditLog } from './audit.js'
+import { createTranscriptScanner } from '../search/transcripts.js'
+
+const SERVER_NAME = 'agentquad'
+
+/**
+ * 创建一个挂在 Express 下的 MCP Streamable HTTP 路由。
+ *
+ * 工作方式：一个全局 McpServer + 一个全局 StreamableHTTPServerTransport，stateless 模式。
+ * 每个 HTTP 请求都由 transport.handleRequest 完整处理。
+ *
+ * 依赖：
+ *   - db：openDb(...) 返回的句柄
+ *   - searchService：createSearchService 返回
+ *   - wikiDir：wiki .md 文件所在目录（用于 read_wiki）
+ *   - getVersion()：可选，注入当前 AgentQuad 版本
+ *   - aiTerminal：可选，{ spawnSession }，用于 start_ai_session
+ *   - openclaw：可选，OpenClaw bridge 句柄
+ *   - pending：可选，pending-question coordinator 句柄
+ *   - getConfig：可选，() => 当前配置快照
+ */
+export function createMcpRouter({
+  db, searchService, wikiDir, rootDir, logDir, getVersion,
+  aiTerminal = null, openclaw = null, pending = null, getConfig = null,
+} = {}) {
+  if (!db) throw new Error('db_required')
+  if (!searchService) throw new Error('searchService_required')
+
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: (typeof getVersion === 'function' && getVersion()) || '0.1.0',
+  })
+
+  const audit = rootDir ? createAuditLog({ rootDir }) : null
+  const transcriptScanner = logDir ? createTranscriptScanner({ db, logDir }) : null
+
+  registerReadTools(server, { db, searchService, wikiDir, transcriptScanner })
+  registerWriteTools(server, { db })
+  registerDestructiveTools(server, { db, audit })
+  if (pending) {
+    registerOpenClawTools(server, { db, aiTerminal, openclaw, pending, getConfig })
+  }
+
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
+  // 异步 connect；路由处理器会等这个 promise resolve 之后再调 handleRequest。
+  const ready = server.connect(transport)
+
+  const router = express.Router()
+  // MCP Streamable HTTP 约定：客户端用 POST /mcp 下发 JSON-RPC；
+  // 对于 SSE 变体或重连，GET 会触发会话初始化。
+  // 我们是 stateless mode，所以两种方法都交给 transport.handleRequest。
+  const handle = async (req, res) => {
+    try {
+      await ready
+      await transport.handleRequest(req, res, req.body)
+    } catch (e) {
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: { code: -32603, message: e?.message || 'internal_error' },
+          id: null,
+        })
+      }
+    }
+  }
+  router.post('/', handle)
+  router.get('/', handle)
+  router.delete('/', handle)
+
+  // 健康检查（MCP 客户端一般不走这个，但方便 `agentquad mcp status` 和运维）
+  router.get('/health', (_req, res) => {
+    res.json({ ok: true, server: SERVER_NAME, tools: server._registeredTools ? Object.keys(server._registeredTools).length : undefined })
+  })
+
+  return { router, server, transport }
+}