@modesto_ma/dsh-channels 0.5.0-beta.1 → 0.5.0-beta.3

package/src/domain.ts

@@ -317,6 +317,10 @@ export interface FeishuDomainSpecShape {
       valueSchema: typeof accessRequestRecordSchema
       __key?: string
     }
+    access_wiki_users: {
+      valueSchema: typeof accessUserRecordSchema
+      __key?: string
+    }
   }
 }
 
@@ -353,6 +357,10 @@ export const feishuDomain: FeishuDomainSpecShape = {
     access_groups: { valueSchema: accessGroupRecordSchema },
     access_users: { valueSchema: accessUserRecordSchema },
     access_requests: { valueSchema: accessRequestRecordSchema },
+    // Wiki whitelist (`/auth wiki add`): same record as `access_users`, an
+    // independent grant. Added without a version bump like the other access
+    // tables: a missing table loads empty.
+    access_wiki_users: { valueSchema: accessUserRecordSchema },
   },
 }
 
@@ -428,6 +436,8 @@ export interface FeishuDomainHandle {
   accessGroups: AccessGroupsTable
   accessUsers: AccessUsersTable
   accessRequests: AccessRequestsTable
+  /** Wiki whitelist (key = `user_id`); same records as {@link AccessUsersTable}. */
+  accessWikiUsers: AccessUsersTable
   getGlobal(): FeishuDomainGlobal
   setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
   close(): Promise<void>

package/src/feishu/delivery.ts

@@ -28,8 +28,27 @@ export interface CardDeliveryDeps {
 }
 
 export class CardDelivery {
+  /** Open `replacingCard` scopes per message id; overlapping clicks nest. */
+  private readonly inPlace = new Map<string, number>()
+
   constructor(private readonly deps: CardDeliveryDeps) {}
 
+  /**
+   * Run `operation` with every `standaloneReply` anchored to `messageId`
+   * patched into that (bot-sent card) message instead of replying to it.
+   * Used for picker clicks, whose synthetic message id is the picker card.
+   */
+  async replacingCard(messageId: string, operation: () => Promise<void>): Promise<void> {
+    this.inPlace.set(messageId, (this.inPlace.get(messageId) ?? 0) + 1)
+    try {
+      await operation()
+    } finally {
+      const remaining = (this.inPlace.get(messageId) ?? 1) - 1
+      if (remaining === 0) this.inPlace.delete(messageId)
+      else this.inPlace.set(messageId, remaining)
+    }
+  }
+
   /** The live channel; throws instead of silently dropping a delivery. */
   requireChannel(): FeishuChannel {
     const channel = this.deps.channel()
@@ -73,6 +92,9 @@ export class CardDelivery {
   /**
    * Shared delivery policy for command-plane cards: reply in a new topic by
    * default, then degrade to a plain reply when Feishu refuses the topic.
+   * `createThread: false` replies in the chat timeline, or inside the topic
+   * the message already belongs to. Inside `replacingCard` the card patches
+   * the anchored card instead, and falls back to a reply if the patch fails.
    */
   async standaloneReply(
     msg: NormalizedMessage,
@@ -81,9 +103,20 @@ export class CardDelivery {
   ): Promise<void> {
     const channel = this.deps.channel()
     if (!this.deps.started() || channel === undefined) return
+    if (this.inPlace.has(msg.messageId)) {
+      try {
+        await channel.updateCard(msg.messageId, card)
+        return
+      } catch (error) {
+        this.deps.warn(
+          'dsh-channels: in-place update of card %s failed, replying instead: %s',
+          msg.messageId, String(error),
+        )
+      }
+    }
     const createThread = options.createThread ?? true
     try {
-      await channel.send(msg.chatId, { card }, createThread
+      await channel.send(msg.chatId, { card }, createThread || msg.threadId !== undefined
         ? { replyTo: msg.messageId, replyInThread: true }
         : { replyTo: msg.messageId })
     } catch (error) {

package/src/feishu/message-read.ts

@@ -548,8 +548,10 @@ export function messageTextOf(item: RawMessageItem): string {
     }
     case 'merge_forward':
       return '[合并转发]'
-    case 'interactive':
-      return '[卡片消息]'
+    case 'interactive': {
+      const text = content === undefined ? '' : cardText(content)
+      return text === '' ? '[卡片消息]' : `[卡片] ${text}`
+    }
     case 'audio':
       return '[语音]'
     case 'video':
@@ -565,6 +567,80 @@ export function messageTextOf(item: RawMessageItem): string {
   }
 }
 
+/** Deepest card node visited by {@link cardText}; real cards nest far less. */
+const MAX_CARD_DEPTH = 12
+
+/**
+ * Card keys whose values are never reader-visible text: callback payloads,
+ * link targets, and layout/style settings.
+ */
+const CARD_SKIPPED_KEYS = new Set([
+  'value', 'behaviors', 'url', 'href', 'multi_url', 'image_key', 'img_key',
+  'icon', 'style', 'config', 'confirm', 'i18n_elements', 'i18n_header', 'user_id', 'open_id',
+])
+
+/**
+ * Flatten one card body into text. Handles both the simplified structure the
+ * message read APIs return by default (`{ title, elements: [[...]] }`) and a
+ * sent card's JSON 1.0/2.0 (`header.title`, `elements` or `body.elements`):
+ * every `text`/`content` string and `plain_text`/`lark_md` object in reading
+ * order, images as `[图片]`. A Card 1.0 localized only through
+ * `i18n_header`/`i18n_elements` renders one locale. Returns `''` when no text
+ * is found.
+ */
+function cardText(content: Record<string, unknown>): string {
+  const parts: string[] = []
+  const title = stringField(content, 'title')
+  if (title !== undefined) parts.push(title)
+  collectCardText(asRecord(content.header) ?? localizedBranch(content.i18n_header), parts, 0)
+  collectCardText(
+    content.elements ?? asRecord(content.body)?.elements ?? localizedBranch(content.i18n_elements),
+    parts,
+    0,
+  )
+  return parts.map(part => part.trim()).filter(part => part !== '').join(' ')
+}
+
+/**
+ * One locale branch of a Card 1.0 `i18n_*` map: `zh_cn` when present,
+ * otherwise the first branch, so a card localized only through `i18n_*`
+ * still renders once instead of once per locale.
+ */
+function localizedBranch(value: unknown): unknown {
+  const branches = asRecord(value)
+  if (branches === undefined) return undefined
+  return branches.zh_cn ?? Object.values(branches)[0]
+}
+
+/** Append the reader-visible text of one card node to `parts`. */
+function collectCardText(node: unknown, parts: string[], depth: number): void {
+  if (depth > MAX_CARD_DEPTH) return
+  if (Array.isArray(node)) {
+    for (const child of node) collectCardText(child, parts, depth + 1)
+    return
+  }
+  const record = asRecord(node)
+  if (record === undefined) return
+  const tag = stringField(record, 'tag')
+  if (tag === 'img' || tag === 'image') {
+    parts.push('[图片]')
+    return
+  }
+  if (tag === 'at') {
+    const name = stringField(record, 'user_name')
+    parts.push(name === undefined ? '@' : `@${name}`)
+    return
+  }
+  for (const [key, value] of Object.entries(record)) {
+    if (CARD_SKIPPED_KEYS.has(key)) continue
+    if (typeof value === 'string') {
+      if (key === 'text' || key === 'content') parts.push(value)
+      continue
+    }
+    collectCardText(value, parts, depth + 1)
+  }
+}
+
 /** Flatten one post body into text; inline images/files become placeholders. */
 function postText(content: Record<string, unknown>): string {
   const lines: string[] = []

package/src/feishu/scopes.ts

@@ -44,6 +44,10 @@ export interface ScopeCheckContext {
   readonly slashCommandPanel: boolean
   /** The `feishu_send_file` tool is enabled (`feishuTools.sendFile`). */
   readonly sendFile: boolean
+  /** The wiki read tools are mounted (`feishuTools.wikiRead` with non-empty `wikiRoots`). */
+  readonly wikiRead: boolean
+  /** The wiki write tools are mounted (`feishuTools.wikiWrite` with non-empty `wikiRoots`). */
+  readonly wikiWrite: boolean
 }
 
 /** A requirement none of whose scopes is granted. */
@@ -87,6 +91,30 @@ const SEND_FILE_REQUIREMENT: ScopeRequirement = {
   anyOf: ['im:resource', 'im:resource:upload'], level: 'optional', purpose: '上传图片/文件，让模型用 feishu_send_file 把生成的文件发给用户',
 }
 
+/** Spreadsheet and Base read needs, shared by the wiki read and write sets. */
+const SHEET_BASE_READ_REQUIREMENTS: readonly ScopeRequirement[] = [
+  { anyOf: ['sheets:spreadsheet', 'sheets:spreadsheet:readonly', 'sheets:spreadsheet:read'], level: 'optional', purpose: '读取知识库电子表格（feishu_wiki_sheet_read）' },
+  { anyOf: ['bitable:app', 'bitable:app:readonly', 'base:record:read'], level: 'optional', purpose: '读取知识库多维表格（feishu_wiki_base_read）' },
+]
+
+/** Wiki read needs (`feishu_wiki_list` / `feishu_wiki_read` and the sheet/base read tools). */
+const WIKI_READ_REQUIREMENTS: readonly ScopeRequirement[] = [
+  { anyOf: ['wiki:wiki', 'wiki:wiki:readonly'], level: 'optional', purpose: '浏览知识库节点（feishu_wiki_list / feishu_wiki_read）' },
+  { anyOf: ['docx:document', 'docx:document:readonly'], level: 'optional', purpose: '读取知识库中的文档内容（feishu_wiki_read）' },
+  ...SHEET_BASE_READ_REQUIREMENTS,
+]
+
+/** Wiki write needs (`feishu_wiki_create` / `feishu_wiki_edit`). */
+const WIKI_WRITE_REQUIREMENTS: readonly ScopeRequirement[] = [
+  { anyOf: ['wiki:wiki'], level: 'optional', purpose: '在知识库中新建节点（feishu_wiki_create）' },
+  { anyOf: ['docx:document'], level: 'optional', purpose: '写入与修改知识库文档内容（feishu_wiki_create / feishu_wiki_edit）' },
+  { anyOf: ['sheets:spreadsheet', 'sheets:spreadsheet:write_only'], level: 'optional', purpose: '写入知识库电子表格（feishu_wiki_sheet_edit）' },
+  { anyOf: ['bitable:app', 'base:record:create'], level: 'optional', purpose: '新增知识库多维表格记录（feishu_wiki_base_edit）' },
+  { anyOf: ['bitable:app', 'base:record:update'], level: 'optional', purpose: '修改本应用创建的多维表格中的记录（feishu_wiki_base_edit）' },
+  { anyOf: ['bitable:app', 'base:record:delete'], level: 'optional', purpose: '删除本应用创建的多维表格中的记录（feishu_wiki_base_edit）' },
+  ...SHEET_BASE_READ_REQUIREMENTS,
+]
+
 /** Group receive needs while ordinary group messages require an @ mention. */
 const MENTION_GROUP_REQUIREMENTS: readonly ScopeRequirement[] = [
   { anyOf: ['im:message.group_at_msg:readonly', 'im:message.group_msg'], level: 'required', purpose: '接收群聊中 @ 机器人的消息' },
@@ -139,10 +167,17 @@ export function scopeRequirements(context: ScopeCheckContext): readonly ScopeReq
     ...(context.requireMention ? MENTION_GROUP_REQUIREMENTS : [ALL_GROUP_REQUIREMENT]),
     ...BASE_REQUIREMENTS,
     ...(context.sendFile ? [SEND_FILE_REQUIREMENT] : []),
+    ...wikiRequirements(context),
     ...(context.slashCommandPanel ? SLASH_COMMAND_REQUIREMENTS : []),
   ]
 }
 
+/** Wiki needs; the write set subsumes the read set's preferred scopes. */
+function wikiRequirements(context: ScopeCheckContext): readonly ScopeRequirement[] {
+  if (context.wikiWrite) return WIKI_WRITE_REQUIREMENTS
+  return context.wikiRead ? WIKI_READ_REQUIREMENTS : []
+}
+
 /**
  * Compare `grants` with the applicable requirements. Only tenant (or untyped)
  * grants count: the plugin always calls with the app identity.

package/src/feishu/wiki/a1.ts

@@ -0,0 +1,97 @@
+/**
+ * A1 notation helpers for the wiki sheet tools: column letters, single cells,
+ * and rectangle end rows. Ranges never carry a sheet prefix (`Sheet1!`); the
+ * sub-sheet is selected separately.
+ *
+ * @module dsh-channels/feishu/wiki/a1
+ */
+
+/** Largest column the helpers accept (`ZZZ`). */
+const MAX_COLUMN = 18_278
+
+/** Largest row the helpers accept. */
+const MAX_ROW = 10_000_000
+
+/** One cell position, 1-based. */
+export interface A1Cell {
+  readonly column: number
+  readonly row: number
+}
+
+/**
+ * Column letters to a 1-based index (`A` → 1, `AA` → 27).
+ *
+ * @param letters Column letters, any case.
+ * @returns The index, or undefined when invalid or beyond `ZZZ`.
+ */
+export function columnIndex(letters: string): number | undefined {
+  if (!/^[A-Za-z]{1,3}$/u.test(letters)) return undefined
+  let index = 0
+  for (const char of letters.toUpperCase()) index = index * 26 + (char.charCodeAt(0) - 64)
+  return index <= MAX_COLUMN ? index : undefined
+}
+
+/**
+ * A 1-based column index to letters (1 → `A`, 27 → `AA`).
+ *
+ * @param index Column index, at least 1.
+ * @returns The letters.
+ */
+export function columnLetters(index: number): string {
+  let letters = ''
+  let rest = index
+  while (rest > 0) {
+    const digit = (rest - 1) % 26
+    letters = String.fromCharCode(65 + digit) + letters
+    rest = Math.floor((rest - 1) / 26)
+  }
+  return letters
+}
+
+/**
+ * Parse one cell (`B3`).
+ *
+ * @param value Cell reference.
+ * @returns The position, or undefined when it is not a single valid cell.
+ */
+export function parseCell(value: string): A1Cell | undefined {
+  const match = /^([A-Za-z]{1,3})([1-9]\d{0,7})$/u.exec(value.trim())
+  if (match === null) return undefined
+  const column = columnIndex(match[1] ?? '')
+  const row = Number(match[2])
+  return column === undefined || row > MAX_ROW ? undefined : { column, row }
+}
+
+/**
+ * The rectangle that starts at `start` and spans `rows` × `columns` cells.
+ *
+ * @param start Top-left cell.
+ * @param rows Row count, at least 1.
+ * @param columns Column count, at least 1.
+ * @returns The range (`B3:D10`).
+ */
+export function rectangle(start: A1Cell, rows: number, columns: number): string {
+  return `${columnLetters(start.column)}${start.row}:${columnLetters(start.column + columns - 1)}${start.row + rows - 1}`
+}
+
+/**
+ * Last row of a range (`A1:B5` → 5, `C7` → 7); undefined for whole-column ranges (`A:C`).
+ *
+ * @param range A1 range.
+ * @returns The row, or undefined.
+ */
+export function rangeEndRow(range: string): number | undefined {
+  const end = range.split(':').at(-1) ?? ''
+  const match = /(\d+)$/u.exec(end.trim())
+  return match === null ? undefined : Number(match[1])
+}
+
+/**
+ * Whether a range is plain A1 (`A1`, `A1:F30`, `A:C`, `3:5`) without a sheet prefix.
+ *
+ * @param range Candidate range.
+ * @returns True when acceptable.
+ */
+export function isA1Range(range: string): boolean {
+  return /^(?:[A-Za-z]{1,3}\d{0,8}|\d{1,8})(?::(?:[A-Za-z]{1,3}\d{0,8}|\d{1,8}))?$/u.test(range)
+}