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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modesto_ma/dsh-channels",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.3",
   "description": "DeepSeek Harness (DSH) 飞书渠道插件：一个 dsh 实例对应一个飞书机器人，私聊/群聊/话题群 @ 触发会话，话题绑定 session，卡片 2.0 流式回复；Web 设置里提供「飞书渠道」状态与常用配置面板",
   "repository": {
     "type": "git",

package/src/access/store.ts

@@ -6,7 +6,8 @@
  * every mutation writes through to the domain first and then updates memory,
  * matching the store patterns used for routes and inflight snapshots.
  *
- * The tables (`access_groups`, `access_users`, `access_requests`) were added
+ * The tables (`access_groups`, `access_users`, `access_requests`,
+ * `access_wiki_users`) were added
  * without bumping the domain version on purpose: the JSON backend's `single`
  * layout refuses a stored-version mismatch, while unknown/missing tables are
  * simply empty on load (see `docs/access-control-design.md` §4.2).
@@ -40,6 +41,8 @@ export class AccessStore {
   private readonly groups = new Map<string, AccessGroupRecord>()
   private readonly users = new Map<string, AccessUserRecord>()
   private readonly requests = new Map<string, AccessRequestRecord>()
+  /** Wiki whitelist (`/auth wiki add`), independent of the user whitelist. */
+  private readonly wikiUsers = new Map<string, AccessUserRecord>()
   /** Cached key sets so `snapshot()` can stay allocation-free per message. */
   private readonly groupKeys = new Set<string>()
   private readonly userKeys = new Set<string>()
@@ -65,6 +68,9 @@ export class AccessStore {
     for (const [key, record] of domain.accessRequests.entries()) {
       this.requests.set(key, record)
     }
+    for (const [key, record] of domain.accessWikiUsers.entries()) {
+      this.wikiUsers.set(key, record)
+    }
   }
 
   /** Drop every in-memory record (shutdown). The domain owns durability. */
@@ -72,6 +78,7 @@ export class AccessStore {
     this.groups.clear()
     this.users.clear()
     this.requests.clear()
+    this.wikiUsers.clear()
     this.groupKeys.clear()
     this.userKeys.clear()
   }
@@ -136,6 +143,29 @@ export class AccessStore {
     return true
   }
 
+  /** Whether `userId` is on the wiki whitelist (the administrator is not implied). */
+  hasWikiUser(userId: string): boolean {
+    return this.wikiUsers.has(userId)
+  }
+
+  /** Every wiki-whitelisted user, oldest first. */
+  wikiUserRecords(): AccessUserRecord[] {
+    return [...this.wikiUsers.values()].sort((left, right) => left.addedAt - right.addedAt)
+  }
+
+  async addWikiUser(record: AccessUserRecord): Promise<AccessUserRecord> {
+    await this.requireDomain('add wiki user').accessWikiUsers.put(record.userId, record)
+    this.wikiUsers.set(record.userId, record)
+    return record
+  }
+
+  async removeWikiUser(userId: string): Promise<boolean> {
+    if (!this.wikiUsers.has(userId)) return false
+    await this.requireDomain('remove wiki user').accessWikiUsers.delete(userId)
+    this.wikiUsers.delete(userId)
+    return true
+  }
+
   /** Every authorization request, including settled ones (audit). */
   requestRecords(): AccessRequestRecord[] {
     return [...this.requests.values()].sort((left, right) => left.createdAt - right.createdAt)

package/src/cards/picker.ts

@@ -4,12 +4,13 @@
  *
  * A click carries the command and its argument back to the service, which
  * runs it exactly like the typed `/<command> <arg>` line, so admission,
- * ownership and validation stay in one place.
+ * ownership and validation stay in one place; the result replaces the picker
+ * card in place.
  *
  * @module dsh-channels/cards/picker
  */
 
-import { columnSet, divider, markdown, note, standaloneCard, textButton } from './primitives.ts'
+import { divider, markdown, note, standaloneCard, textButton } from './primitives.ts'
 
 /** `decision` carried by every picker button. */
 export const PICK_ACTION = 'command-pick'
@@ -58,36 +59,28 @@ function pickButton(input: PickerCardInput, label: string, arg: string): object
   return textButton({
     label: active ? `✅ ${label}` : label,
     type: active ? 'primary' : 'default',
-    width: 'fill',
-    margin: '0px',
     value,
   })
 }
 
-/** Choices in two-column rows. */
-function optionRows(input: PickerCardInput, options: readonly PickerOption[]): object[] {
-  const rows: object[] = []
-  for (let index = 0; index < options.length; index += 2) {
-    const pair = options.slice(index, index + 2).map(option => pickButton(input, option.label, option.arg))
-    rows.push(columnSet(pair))
-  }
-  return rows
-}
-
 /** Whether a value can be appended to a command line as one argument. */
 export function isPickerArg(value: string): boolean {
   return value !== '' && !/\s/u.test(value)
 }
 
 /**
- * The picker card. Options whose argument cannot form one command-line token
+ * The picker card: one full-width button per choice, in a single column.
+ * Options whose argument cannot form one command-line token
  * are skipped; when more than `MAX_PICKER_OPTIONS` remain the rest are
  * reported as typed-only.
  */
 export function buildPickerCard(input: PickerCardInput): object {
   const usable = input.options.filter(option => isPickerArg(option.arg))
   const shown = usable.slice(0, MAX_PICKER_OPTIONS)
-  const elements: object[] = [markdown(input.text), ...optionRows(input, shown)]
+  const elements: object[] = [
+    markdown(input.text),
+    ...shown.map(option => pickButton(input, option.label, option.arg)),
+  ]
   if (usable.length > shown.length) {
     elements.push(note(`另有 ${usable.length - shown.length} 项未展示，可直接输入 /${input.command} <id>。`))
   }

package/src/cards/wiki.ts

@@ -0,0 +1,124 @@
+/**
+ * Wiki (知识库) authorization cards: the topic owner's consent before the
+ * model opens, creates, or edits a wiki document.
+ *
+ * @module dsh-channels/cards/wiki
+ */
+
+import { columnSet, divider, markdown, note, standaloneCard, textButton } from './primitives.ts'
+
+/** What one wiki consent covers. */
+export type WikiConsentAction = 'read' | 'create' | 'edit'
+
+/** Terminal states of a wiki consent card. */
+export type WikiConsentCardState = 'allowed' | 'denied' | 'expired' | 'cancelled'
+
+/** The question one wiki consent card presents. */
+export interface WikiConsentQuestion {
+  /** Opaque token binding the card to one pending consent (button value). */
+  readonly token: string
+  readonly action: WikiConsentAction
+  /** Document title (create: the new title). */
+  readonly title: string
+  /** Document link (read/edit) or parent link (create), when known. */
+  readonly url?: string
+  /** Where the document lives or will live, e.g. `空间名 / 父节点`. */
+  readonly location: string
+  /** Extra lines: operations of an edit, the content preview of a create. */
+  readonly details: readonly string[]
+  /** Timeout window shown on the card (milliseconds). */
+  readonly timeoutMs: number
+}
+
+/** Card rendering options. */
+export interface WikiConsentCardOptions {
+  /** Add the owner-only notice (someone else clicked and was ignored). */
+  readonly unauthorizedNote?: boolean
+}
+
+/** Cap on one rendered detail block so the card stays readable on a phone. */
+const DETAIL_MAX_CHARS = 800
+
+const ACTION_LABELS: Readonly<Record<WikiConsentAction, string>> = {
+  read: '读取文档',
+  create: '新建文档',
+  edit: '修改文档',
+}
+
+const SETTLED_LINES: Readonly<Record<WikiConsentCardState, string>> = {
+  allowed: '✅ 已允许',
+  denied: '❌ 已拒绝',
+  expired: '⏱ 已超时未处理，自动拒绝',
+  cancelled: '↩️ 请求已取消',
+}
+
+/** Clip one value to `max` characters, marking the cut. */
+function clip(value: string, max: number): string {
+  return value.length <= max ? value : `${value.slice(0, max)}…（已截断 ${value.length - max} 个字符）`
+}
+
+/** One line of Markdown text with link/markup characters neutralized. */
+function plain(value: string): string {
+  return value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/([[\]()*_`~<>])/gu, '\\$1').trim()
+}
+
+/** The question summary shared by the pending and settled variants. */
+function questionElements(question: WikiConsentQuestion): object[] {
+  const title = question.title === '' ? '（无标题）' : plain(question.title)
+  const titleLine = question.url === undefined || question.action === 'create'
+    ? title
+    : `[${title}](${question.url})`
+  const elements: object[] = [
+    markdown([
+      `机器人请求以应用身份**${ACTION_LABELS[question.action]}**。`,
+      `**文档**：${titleLine}`,
+      `**位置**：${plain(question.location)}`,
+    ].join('\n')),
+  ]
+  for (const detail of question.details) {
+    elements.push(markdown(clip(detail, DETAIL_MAX_CHARS)))
+  }
+  return elements
+}
+
+function consentButton(question: WikiConsentQuestion, decision: 'allow' | 'deny'): object {
+  return textButton({
+    label: decision === 'allow' ? '✅ 允许' : '❌ 拒绝',
+    type: decision === 'allow' ? 'primary' : 'danger',
+    width: 'fill',
+    value: { decision, token: question.token },
+  })
+}
+
+/**
+ * The pending consent card, sent as a reply in the session's topic.
+ *
+ * @param question The consent asked for.
+ * @param options Rendering options.
+ * @returns Card JSON 2.0.
+ */
+export function buildWikiConsentCard(question: WikiConsentQuestion, options: WikiConsentCardOptions = {}): object {
+  const minutes = Math.max(1, Math.round(question.timeoutMs / 60_000))
+  const scope = question.action === 'read'
+    ? '允许后，本话题内再次读取这篇文档不再询问'
+    : '仅对这一次操作生效'
+  const elements: object[] = [
+    ...questionElements(question),
+    divider(),
+    note(`⏱ ${minutes} 分钟内有效，超时自动拒绝 · ${scope}`),
+  ]
+  if (options.unauthorizedNote === true) elements.push(note('ℹ️ 仅发起该话题的用户可操作此卡片'))
+  elements.push(columnSet([consentButton(question, 'allow'), consentButton(question, 'deny')]))
+  return standaloneCard('**📚 知识库授权**', elements)
+}
+
+/**
+ * The terminal replacement after the consent settles; no controls.
+ *
+ * @param question The consent that was asked for.
+ * @param state How it settled.
+ * @returns Card JSON 2.0.
+ */
+export function buildWikiConsentSettledCard(question: WikiConsentQuestion, state: WikiConsentCardState): object {
+  return standaloneCard(`**${SETTLED_LINES[state]}**`, [...questionElements(question), divider(), note(`📚 知识库${ACTION_LABELS[question.action]}`)])
+}

package/src/client/panel/shared.tsx

@@ -23,6 +23,15 @@ import type {
   PanelTabId,
   PanelWire,
 } from '../../settings/contract.ts'
+import {
+  listIsFull,
+  listItems,
+  listRows,
+  stringListDraftValue,
+  withBlankListEntry,
+  withListEntry,
+  withoutListEntry,
+} from '../string-list.ts'
 
 /** Initial panel load: one request, retried from the error card. */
 export type LoadState =
@@ -126,6 +135,12 @@ export function validateDraft(
       values[field.key] = raw === true
       continue
     }
+    if (field.kind === 'string-list') {
+      const list = stringListDraftValue(field, raw)
+      if (list.ok) values[field.key] = list.value
+      else issues.push(...list.issues)
+      continue
+    }
     values[field.key] = String(raw ?? '')
   }
   return { values, issues }
@@ -236,6 +251,73 @@ function DirectoryTextInput(props: {
   )
 }
 
+/**
+ * `string-list` control: one single-line input per entry, each with a remove
+ * button, and an add button below (disabled at `maxItems` inputs). An empty
+ * list renders one blank input so the first entry can be typed directly.
+ * Issues carrying an `index` mark that input and show the reason under it.
+ */
+function StringListInput(props: {
+  field: EditableFieldWire
+  value: ConfigValue | undefined
+  issues: readonly FieldIssueWire[]
+  disabled: boolean
+  onChange: (key: EditableKey, value: ConfigValue) => void
+}): JSX.Element {
+  const { field, value, issues, disabled, onChange } = props
+  const empty = listItems(value).length === 0
+  const rows = listRows(value)
+  return (
+    <div className="dsh-channels-cfg__list">
+      {rows.map((item, index) => {
+        const issue = issues.find(entry => entry.index === index)
+        const position = PANEL_COPY.listEntry.replace('{n}', String(index + 1))
+        // Entries have no identity beyond their position, so the index is the key.
+        return (
+          <div className="dsh-channels-cfg__listItem" key={index}>
+            <div className="dsh-channels-cfg__inputRow">
+              <input
+                type="text"
+                className={`dsh-channels-cfg__input${issue === undefined ? '' : ' dsh-channels-cfg__input--invalid'}`}
+                value={item}
+                placeholder={field.placeholder}
+                aria-label={`${field.label} ${position}`}
+                aria-invalid={issue === undefined ? undefined : true}
+                disabled={disabled}
+                onChange={event => onChange(field.key, withListEntry(rows, index, event.target.value))}
+              />
+              {empty
+                ? null
+                : (
+                    <button
+                      type="button"
+                      className="dsh-channels-cfg__btn dsh-channels-cfg__btn--listRemove"
+                      aria-label={`${PANEL_COPY.listRemove} ${position}`}
+                      disabled={disabled}
+                      onClick={() => onChange(field.key, withoutListEntry(rows, index))}
+                    >
+                      {PANEL_COPY.listRemove}
+                    </button>
+                  )}
+            </div>
+            {issue === undefined ? null : <span className="dsh-channels-cfg__fieldError">{issue.message}</span>}
+          </div>
+        )
+      })}
+      <div>
+        <button
+          type="button"
+          className="dsh-channels-cfg__btn"
+          disabled={disabled || listIsFull(field, rows)}
+          onClick={() => onChange(field.key, withBlankListEntry(rows))}
+        >
+          {PANEL_COPY.listAdd}
+        </button>
+      </div>
+    </div>
+  )
+}
+
 /** One generic form control driven by the Host field descriptor. */
 export function FieldRow(props: {
   field: EditableFieldWire
@@ -247,7 +329,9 @@ export function FieldRow(props: {
   onPickDirectory?: () => Promise<void>
 }): JSX.Element {
   const { field, value, issues, disabled = false, onChange, onPickDirectory } = props
-  const issue = issues.find(item => item.key === field.key)
+  // Entry issues (`index` set) are rendered next to their input by StringListInput.
+  const issue = issues.find(item => item.key === field.key && item.index === undefined)
+  const entryIssues = issues.filter(item => item.key === field.key && item.index !== undefined)
   const inputClass = `dsh-channels-cfg__input${issue === undefined ? '' : ' dsh-channels-cfg__input--invalid'}`
   const fieldClass = `dsh-channels-cfg__field${field.wide === true ? ' dsh-channels-cfg__field--wide' : ''}`
   return (
@@ -327,6 +411,17 @@ export function FieldRow(props: {
                 />
               ))
         : null}
+      {field.kind === 'string-list'
+        ? (
+            <StringListInput
+              field={field}
+              value={value}
+              issues={entryIssues}
+              disabled={disabled}
+              onChange={onChange}
+            />
+          )
+        : null}
       {field.help === undefined ? null : <span className="dsh-channels-cfg__help">{field.help}</span>}
       {issue === undefined ? null : <span className="dsh-channels-cfg__fieldError">{issue.message}</span>}
     </div>

package/src/client/string-list.ts

@@ -0,0 +1,139 @@
+/**
+ * 浏览器半区的 `string-list` 字段辅助：把草稿值读成条目数组，并在保存前
+ * 逐项校验，供面板即时标红。Host 保存时按同一规则复核（见
+ * `settings/surface.ts` 的 `normalizeStringList`）。
+ *
+ * 不含 JSX/React，便于单测。条目格式校验直接复用纯函数模块
+ * `feishu/wiki/links.ts`（无运行时依赖，可内联进 Client bundle）。
+ *
+ * @module dsh-channels/client/string-list
+ */
+
+import { parseWikiRootLink, WIKI_ROOT_LINK_ERRORS } from '../feishu/wiki/links.ts'
+import { PANEL_COPY } from '../settings/contract.ts'
+import type {
+  ConfigValue,
+  EditableFieldWire,
+  FieldIssueWire,
+  StringListItemFormat,
+} from '../settings/contract.ts'
+
+/** Entry checks per item format: the readable reason, or `undefined` when valid. */
+const ITEM_FORMAT_CHECKS: Readonly<Record<StringListItemFormat, (entry: string) => string | undefined>> = {
+  'wiki-root-link': (entry) => {
+    const parsed = parseWikiRootLink(entry)
+    return parsed.ok ? undefined : WIKI_ROOT_LINK_ERRORS[parsed.error]
+  },
+}
+
+/**
+ * Entries of a `string-list` value; any other value reads as no entries.
+ *
+ * @param value - Draft or effective value of a `string-list` field.
+ * @returns The entries as stored (untrimmed).
+ */
+export function listItems(value: ConfigValue | undefined): readonly string[] {
+  return typeof value === 'object' ? value : []
+}
+
+/**
+ * Validate the entries of one `string-list` draft the way the Host will:
+ * empty inputs are ignored, every other entry is trimmed and checked against
+ * the field's `itemFormat`, and the non-empty count is bounded by `maxItems`.
+ *
+ * @param field - The Host descriptor (`kind: 'string-list'`).
+ * @param items - The draft entries, empty inputs included.
+ * @returns Per-entry issues (with `index` into `items`) and a whole-field issue when over `maxItems`.
+ */
+export function stringListIssues(field: EditableFieldWire, items: readonly string[]): FieldIssueWire[] {
+  const issues: FieldIssueWire[] = []
+  const check = field.itemFormat === undefined ? undefined : ITEM_FORMAT_CHECKS[field.itemFormat]
+  let count = 0
+  items.forEach((item, index) => {
+    const entry = item.trim()
+    if (entry === '') return
+    count += 1
+    const reason = check?.(entry)
+    if (reason === undefined) return
+    const position = PANEL_COPY.listEntry.replace('{n}', String(index + 1))
+    issues.push({ key: field.key, index, message: `${position}「${entry}」：${reason}` })
+  })
+  if (field.maxItems !== undefined && count > field.maxItems) {
+    issues.push({ key: field.key, message: PANEL_COPY.listTooMany.replace('{max}', String(field.maxItems)) })
+  }
+  return issues
+}
+
+/**
+ * Turn one `string-list` draft into its save payload. Entries are submitted as
+ * typed (untrimmed, empty inputs included) so Host issue indexes point at the
+ * same rendered inputs; the Host trims and drops empty inputs.
+ *
+ * @param field - The Host descriptor (`kind: 'string-list'`).
+ * @param raw - The draft value.
+ * @returns The payload entries, or the issues that block the save.
+ */
+export function stringListDraftValue(
+  field: EditableFieldWire,
+  raw: ConfigValue | undefined,
+): { ok: true; value: string[] } | { ok: false; issues: FieldIssueWire[] } {
+  const items = listItems(raw)
+  const issues = stringListIssues(field, items)
+  return issues.length > 0 ? { ok: false, issues } : { ok: true, value: [...items] }
+}
+
+/**
+ * Inputs the list control renders: one per entry, or one blank input for an
+ * empty list so the first entry can be typed directly.
+ *
+ * @param value - Draft or effective value.
+ * @returns The input values, in order.
+ */
+export function listRows(value: ConfigValue | undefined): readonly string[] {
+  const items = listItems(value)
+  return items.length === 0 ? [''] : items
+}
+
+/**
+ * Replace the entry at one input position.
+ *
+ * @param rows - Rendered inputs ({@link listRows}).
+ * @param index - Position of the edited input.
+ * @param entry - The typed value.
+ * @returns The next draft entries.
+ */
+export function withListEntry(rows: readonly string[], index: number, entry: string): string[] {
+  return rows.map((item, position) => (position === index ? entry : item))
+}
+
+/**
+ * Drop the entry at one input position.
+ *
+ * @param rows - Rendered inputs ({@link listRows}).
+ * @param index - Position of the removed input.
+ * @returns The next draft entries.
+ */
+export function withoutListEntry(rows: readonly string[], index: number): string[] {
+  return rows.filter((_, position) => position !== index)
+}
+
+/**
+ * Append one blank input.
+ *
+ * @param rows - Rendered inputs ({@link listRows}).
+ * @returns The next draft entries.
+ */
+export function withBlankListEntry(rows: readonly string[]): string[] {
+  return [...rows, '']
+}
+
+/**
+ * Whether the add button is disabled: the inputs already reach `maxItems`.
+ *
+ * @param field - The Host descriptor.
+ * @param rows - Rendered inputs ({@link listRows}).
+ * @returns `true` when no further input may be added.
+ */
+export function listIsFull(field: EditableFieldWire, rows: readonly string[]): boolean {
+  return field.maxItems !== undefined && rows.length >= field.maxItems
+}

package/src/client/styles.ts

@@ -59,6 +59,9 @@ const CSS = `
 .dsh-channels-cfg__inputRow{display:flex;align-items:center;gap:8px;min-width:0}
 .dsh-channels-cfg__inputRow .dsh-channels-cfg__input{flex:1 1 auto;width:auto;min-width:0}
 .dsh-channels-cfg__btn--browse{flex:none}
+.dsh-channels-cfg__list{display:flex;flex-direction:column;gap:6px;min-width:0}
+.dsh-channels-cfg__listItem{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dsh-channels-cfg__btn--listRemove{flex:none}
 .dsh-channels-cfg__input:focus{border-color:var(--dsw-alias-state-business-primary,#0a67d3)}
 .dsh-channels-cfg__input--invalid{border-color:var(--dsw-alias-state-danger-primary,#c62828)}
 select.dsh-channels-cfg__input{appearance:auto;cursor:pointer}

package/src/commands/registry.ts

@@ -28,7 +28,10 @@ export interface ChannelCommandSpec {
   readonly mentionGate?: boolean
   /** Only usable in this chat type. */
   readonly chatType?: 'p2p' | 'group'
-  /** Answer with a direct reply instead of creating a topic. */
+  /**
+   * Answer with a direct reply instead of creating a topic; inside an existing
+   * topic the reply still lands in that topic.
+   */
   readonly directReply?: boolean
   /**
    * Answered by the channel itself (`/stop`), never through the agent command
@@ -47,7 +50,7 @@ export interface ChannelCommandSpec {
 export const CHANNEL_COMMANDS = [
   {
     name: 'help', group: '基础', description: '显示当前支持的斜杠命令',
-    routeFree: true, directReply: false,
+    routeFree: true, directReply: true,
   },
   {
     name: 'userid', group: '基础', description: '在私聊中显示当前用户 ID',
@@ -59,7 +62,7 @@ export const CHANNEL_COMMANDS = [
   },
   {
     name: 'health', group: '基础', description: '显示 Harness 与飞书通道健康状态',
-    sessionOptional: true,
+    sessionOptional: true, directReply: true,
   },
   {
     name: 'status', group: '会话', description: '显示当前 Session 状态与性能指标',

package/src/config.ts

@@ -14,6 +14,7 @@
 
 import { z } from 'zod'
 import { FEISHU_USER_ID_PATTERN } from './domain.ts'
+import { parseWikiRootLink, WIKI_ROOT_LINK_ERRORS } from './feishu/wiki/links.ts'
 
 export const FEISHU_LOGGER_LEVELS = ['debug', 'info', 'warn', 'error'] as const
 export type FeishuLoggerLevel = (typeof FEISHU_LOGGER_LEVELS)[number]
@@ -47,6 +48,9 @@ export const DEFAULT_ATTACHMENT_FETCH_MAX_BYTES = 100 * 1024 * 1024
 /** Default whole-call timeout of `feishu_attachment_fetch` (120 s). */
 export const DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS = 120_000
 
+/** Largest delay Node's `setTimeout` honors (2^31 − 1 ms, about 24.8 days); longer delays fire at once. */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647
+
 /** Default per-image byte cap for trigger-message prefetch (20 MiB). */
 export const DEFAULT_PREFETCH_IMAGE_MAX_BYTES = 20 * 1024 * 1024
 
@@ -264,10 +268,12 @@ export const configSchema = z.object({
    *   fetch (1–50). A message with more attachments is refused with a readable
    *   reason so the model can retry per `file_key`.
    * - `attachmentFetchMaxBytes`: total download budget of one tool call
-   *   (default 100 MiB). Files stream to the native attachment library, so the
-   *   limit is enforced while streaming rather than buffered first.
-   * - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s). On expiry
-   *   the in-flight download is cancelled and reported per attachment.
+   *   (default 100 MiB, no upper bound). Files stream to the native attachment
+   *   library, so the limit is enforced while streaming rather than buffered
+   *   first, and multi-GiB files need only disk space.
+   * - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s, at most
+   *   {@link MAX_TIMER_DELAY_MS}). On expiry the in-flight download is
+   *   cancelled and reported per attachment.
    * - `topicMessages` (default on): register `feishu_topic_messages` in
    *   channel sessions so the model can read the quoted message / earlier
    *   topic messages on demand and authorize their attachments for fetch.
@@ -287,20 +293,44 @@ export const configSchema = z.object({
    *   `im:resource` (or `im:resource:upload`) scope; without it a call returns
    *   a readable failure and the turn continues.
    *
+   * - `wikiRead` (default off): register `feishu_wiki_list`,
+   *   `feishu_wiki_read`, `feishu_wiki_sheet_read`, and
+   *   `feishu_wiki_base_read` so the model can browse the wiki nodes under
+   *   `wikiRoots` and read docx documents, spreadsheets, and Bases there.
+   *   Needs `wiki:wiki` (or `wiki:wiki:readonly`), `docx:document` (or
+   *   `docx:document:readonly`), `sheets:spreadsheet` (or a read-only
+   *   spreadsheet scope), and `bitable:app` (or a read-only Base scope).
+   * - `wikiWrite` (default off): register `feishu_wiki_create`,
+   *   `feishu_wiki_edit`, `feishu_wiki_sheet_edit`, and
+   *   `feishu_wiki_base_edit` so the model can create docx documents,
+   *   spreadsheets, and Bases under `wikiRoots`, edit documents and
+   *   spreadsheets this app owns, and change records of Bases this app owns
+   *   (other Bases accept new records only). Needs `wiki:wiki`,
+   *   `docx:document`, `sheets:spreadsheet`, and `bitable:app` (or the
+   *   matching write-only scopes).
+   *
+   * The wiki tools act with the app identity and are mounted only while
+   * `wikiRoots` is non-empty. Each call is limited to topics whose owner is
+   * the administrator or on the wiki whitelist (`/auth wiki add`); opening a
+   * document, creating one, and editing one each need the topic owner's
+   * consent on an authorization card (a read consent lasts for the topic).
+   *
    * The Web panel/metrics ship with `panel_docs_release`.
    */
   feishuTools: z.object({
     attachmentFetch: z.boolean().default(true),
     attachmentFetchMaxResources: z.number().int().min(1).max(50)
       .default(DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES),
-    attachmentFetchMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+    attachmentFetchMaxBytes: z.number().int().min(1)
       .default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
-    attachmentFetchTimeoutMs: z.number().int().min(1_000).max(600_000)
+    attachmentFetchTimeoutMs: z.number().int().min(1_000).max(MAX_TIMER_DELAY_MS)
       .default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
     topicMessages: z.boolean().default(true),
     topicMessagesTimeoutMs: z.number().int().min(1_000).max(120_000)
       .default(DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS),
     sendFile: z.boolean().default(true),
+    wikiRead: z.boolean().default(false),
+    wikiWrite: z.boolean().default(false),
   }).default({
     attachmentFetch: true,
     attachmentFetchMaxResources: DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES,
@@ -309,7 +339,21 @@ export const configSchema = z.object({
     topicMessages: true,
     topicMessagesTimeoutMs: DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS,
     sendFile: true,
+    wikiRead: false,
+    wikiWrite: false,
   }),
+  /**
+   * Wiki (知识库) locations the wiki tools may touch: whole spaces
+   * (`https://<tenant>.feishu.cn/wiki/space/<space_id>`) or single nodes with
+   * everything below them (`https://<tenant>.feishu.cn/wiki/<node_token>`).
+   * Browsing, reading, creating, and editing outside these roots fail. Empty
+   * (default) mounts no wiki tool even when `feishuTools.wikiRead`/`wikiWrite`
+   * is on.
+   */
+  wikiRoots: z.array(z.string().trim().superRefine((link, issue) => {
+    const parsed = parseWikiRootLink(link)
+    if (!parsed.ok) issue.addIssue({ code: 'custom', message: WIKI_ROOT_LINK_ERRORS[parsed.error] })
+  })).max(20).default([]),
   /**
    * Send a one-time onboarding card on the first private message of a chat
    * (facts + command cheat sheet). Persisted per chat; never repeats.