@modesto_ma/dsh-channels 0.5.0-beta.2 → 0.5.0-beta.4

package/src/client/panel/analyze-token-card.tsx

@@ -0,0 +1,70 @@
+/**
+ * 日志分析接口令牌编辑器：值经 Host 的 DSH 凭据服务写入本机凭据库，面板只显示
+ * 「已配置 / 未配置」，不回显已存值；保存或移除后下一次接口请求即生效，不触发重连。
+ *
+ * @module dsh-channels/client/panel/analyze-token-card
+ */
+
+import { PANEL_COPY } from '../../settings/contract.ts'
+import type { PanelWire } from '../../settings/contract.ts'
+import type { AnalyzeTokenView } from './shared.tsx'
+
+export function AnalyzeTokenCard(props: {
+  panel: PanelWire
+  token: AnalyzeTokenView
+}): JSX.Element {
+  const { panel, token } = props
+  const state = panel.config.credentials.analyzeToken
+  const disabled = token.busy !== null || token.locked || !state.writable
+  const issue = token.issues.find(item => item.key === 'analyzeToken')
+  const inputClass = `dsh-channels-cfg__input${issue === undefined ? '' : ' dsh-channels-cfg__input--invalid'}`
+  return (
+    <section className="dsh-channels-cfg__card">
+      <div className="dsh-channels-cfg__cardHead">
+        <span className="dsh-channels-cfg__cardTitle">{PANEL_COPY.analyzeTokenCard}</span>
+        <span className={`dsh-channels-cfg__badge dsh-channels-cfg__badge--${state.configured ? 'ok' : 'muted'}`}>
+          {state.configured ? PANEL_COPY.credentialConfigured : PANEL_COPY.credentialMissing}
+        </span>
+      </div>
+      <span className="dsh-channels-cfg__help">{PANEL_COPY.analyzeTokenCardHelp}</span>
+      <div className="dsh-channels-cfg__field">
+        <span className="dsh-channels-cfg__label">{PANEL_COPY.analyzeTokenLabel}</span>
+        <div className="dsh-channels-cfg__cred">
+          <input
+            type="password"
+            className={inputClass}
+            value={token.value}
+            placeholder={PANEL_COPY.analyzeTokenPlaceholder}
+            autoComplete="new-password"
+            aria-label={PANEL_COPY.analyzeTokenLabel}
+            disabled={disabled}
+            onChange={event => token.onChange(event.target.value)}
+          />
+          {state.configured
+            ? (
+                <button type="button" className="dsh-channels-cfg__btn" disabled={disabled} onClick={token.onClear}>
+                  {token.busy === 'credentials-clear' ? PANEL_COPY.removingCredential : PANEL_COPY.removeCredential}
+                </button>
+              )
+            : null}
+        </div>
+        <span className="dsh-channels-cfg__help">
+          {PANEL_COPY.credentialsRef}：<span className="dsh-channels-cfg__mono">{state.ref}</span>
+          {state.source === undefined ? '' : ` · ${state.source}`}
+        </span>
+        {issue === undefined ? null : <span className="dsh-channels-cfg__fieldError">{issue.message}</span>}
+      </div>
+      {state.writable ? null : <span className="dsh-channels-cfg__fieldError">{PANEL_COPY.credentialReadOnly}</span>}
+      <div className="dsh-channels-cfg__footer">
+        <button
+          type="button"
+          className="dsh-channels-cfg__btn dsh-channels-cfg__btn--primary"
+          onClick={token.onSave}
+          disabled={disabled || token.value.trim() === ''}
+        >
+          {token.busy === 'credentials' ? PANEL_COPY.savingCredentials : PANEL_COPY.saveAnalyzeToken}
+        </button>
+      </div>
+    </section>
+  )
+}

package/src/client/panel/index.tsx

@@ -14,6 +14,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { KeyboardEvent } from 'react'
 import { PANEL_COPY, PANEL_TABS, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
 import type {
+  AccessMutationResponse,
   AccessWire,
   CatalogWire,
   ChannelStatusWire,
@@ -28,6 +29,7 @@ import type {
 import {
   addAccessGroup,
   addAccessUser,
+  addWikiUser,
   clearConfig,
   clearCredential,
   fetchCatalog,
@@ -37,6 +39,7 @@ import {
   reconnect,
   removeAccessGroup,
   removeAccessUser,
+  removeWikiUser,
   resolveAccessRequest,
   saveConfig,
   saveCredentials,
@@ -56,12 +59,14 @@ import {
   validateDraft,
 } from './shared.tsx'
 import type {
+  AnalyzeTokenView,
   BusyAction,
   CredentialsView,
   FormView,
   LoadState,
   Notice,
 } from './shared.tsx'
+import { WikiTab } from './wiki-tab.tsx'
 import { WorkspaceTab } from './workspace-tab.tsx'
 
 /** Owner props handed to a `settings.section` contribution (unused beyond parity). */
@@ -80,6 +85,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
   const [pollError, setPollError] = useState<string | null>(null)
   const [appIdInput, setAppIdInput] = useState('')
   const [appSecretInput, setAppSecretInput] = useState('')
+  const [analyzeTokenInput, setAnalyzeTokenInput] = useState('')
   const [catalog, setCatalog] = useState<CatalogWire | null>(null)
   const [catalogBusy, setCatalogBusy] = useState(false)
   const [accessNotice, setAccessNotice] = useState<string | null>(null)
@@ -106,6 +112,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
       setDraft({})
       setAppIdInput('')
       setAppSecretInput('')
+      setAnalyzeTokenInput('')
     } catch (error) {
       setLoad({ phase: 'error', message: messageOf(error) })
     }
@@ -453,18 +460,24 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [applyAccess])
 
-  const onAddAccessUser = useCallback(async (userId: string, name: string): Promise<boolean> => {
+  /** Add one user to a whitelist; resolves true when the input should clear. */
+  const addUser = useCallback(async (
+    add: (userId: string, name: string) => Promise<AccessMutationResponse>,
+    userId: string,
+    name: string,
+    notice: string,
+  ): Promise<boolean> => {
     setBusy('access')
     setAccessError(null)
     setAccessNotice(null)
     try {
-      const result = await addAccessUser(userId, name)
+      const result = await add(userId, name)
       if (!result.ok) {
         setAccessError(result.error)
         return false
       }
       applyAccess(result.access)
-      setAccessNotice(PANEL_COPY.accessUserAdded)
+      setAccessNotice(notice)
       return true
     } catch (error) {
       setAccessError(messageOf(error))
@@ -474,18 +487,22 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [applyAccess])
 
-  const onRemoveAccessUser = useCallback(async (userId: string): Promise<void> => {
+  const removeUser = useCallback(async (
+    remove: (userId: string) => Promise<AccessMutationResponse>,
+    userId: string,
+    notice: string,
+  ): Promise<void> => {
     setBusy('access')
     setAccessError(null)
     setAccessNotice(null)
     try {
-      const result = await removeAccessUser(userId)
+      const result = await remove(userId)
       if (!result.ok) {
         setAccessError(result.error)
         return
       }
       applyAccess(result.access)
-      setAccessNotice(PANEL_COPY.accessUserRemoved)
+      setAccessNotice(notice)
     } catch (error) {
       setAccessError(messageOf(error))
     } finally {
@@ -552,6 +569,28 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [appIdInput, appSecretInput])
 
+  /** Save the analyze API token; it applies to the next request, no reconnect. */
+  const onSaveAnalyzeToken = useCallback(async (): Promise<void> => {
+    if (analyzeTokenInput.trim() === '') return
+    setBusy('credentials')
+    setNotice(null)
+    try {
+      const result = await saveCredentials({ analyzeToken: analyzeTokenInput })
+      if (!result.ok) {
+        setNotice({ kind: 'error', text: result.error, issues: result.issues })
+        return
+      }
+      setLoad({ phase: 'ready', panel: result.panel })
+      setStatus(result.panel.status)
+      setAnalyzeTokenInput('')
+      setNotice({ kind: 'ok', text: PANEL_COPY.analyzeTokenSaved })
+    } catch (error) {
+      setNotice({ kind: 'error', text: messageOf(error) })
+    } finally {
+      setBusy(null)
+    }
+  }, [analyzeTokenInput])
+
   const onClearCredential = useCallback(async (field: CredentialField): Promise<void> => {
     const confirmed = typeof window.confirm === 'function'
       ? window.confirm(PANEL_COPY.credentialRemoveConfirm)
@@ -569,7 +608,9 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
       setStatus(result.panel.status)
       setNotice({
         kind: 'ok',
-        text: result.reconnect === 'pending' ? PANEL_COPY.credentialRemovedPending : PANEL_COPY.credentialRemoved,
+        text: field === 'analyzeToken'
+          ? PANEL_COPY.analyzeTokenRemoved
+          : result.reconnect === 'pending' ? PANEL_COPY.credentialRemovedPending : PANEL_COPY.credentialRemoved,
       })
     } catch (error) {
       setNotice({ kind: 'error', text: messageOf(error) })
@@ -628,6 +669,16 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     onClear: (field: CredentialField) => { void onClearCredential(field) },
   }), [appIdInput, appSecretInput, busy, hostBusy, issues, onClearCredential, onSaveCredentials])
 
+  const analyzeToken = useMemo<AnalyzeTokenView>(() => ({
+    value: analyzeTokenInput,
+    issues,
+    busy,
+    locked: hostBusy,
+    onChange: setAnalyzeTokenInput,
+    onSave: () => { void onSaveAnalyzeToken() },
+    onClear: () => { void onClearCredential('analyzeToken') },
+  }), [analyzeTokenInput, busy, hostBusy, issues, onClearCredential, onSaveAnalyzeToken])
+
   if (load.phase === 'loading') {
     return (
       <div className="dsh-channels-cfg">
@@ -680,7 +731,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
               />
             )
           : null}
-        {activeTab === 'sessions' ? <SessionsTab form={form} /> : null}
+        {activeTab === 'sessions' ? <SessionsTab form={form} analyzeToken={analyzeToken} /> : null}
         {activeTab === 'model' ? <ModelTab form={form} catalogBusy={catalogBusy} /> : null}
         {activeTab === 'workspace'
           ? (
@@ -695,12 +746,23 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
                 accessError={accessError}
                 onAddGroup={onAddAccessGroup}
                 onRemoveGroup={chatId => { void onRemoveAccessGroup(chatId) }}
-                onAddUser={onAddAccessUser}
-                onRemoveUser={userId => { void onRemoveAccessUser(userId) }}
+                onAddUser={(userId, name) => addUser(addAccessUser, userId, name, PANEL_COPY.accessUserAdded)}
+                onRemoveUser={userId => { void removeUser(removeAccessUser, userId, PANEL_COPY.accessUserRemoved) }}
                 onResolveRequest={(token, decision) => { void onResolveAccessRequest(token, decision) }}
               />
             )
           : null}
+        {activeTab === 'wiki'
+          ? (
+              <WikiTab
+                form={form}
+                accessNotice={accessNotice}
+                accessError={accessError}
+                onAddUser={(userId, name) => addUser(addWikiUser, userId, name, PANEL_COPY.wikiUserAdded)}
+                onRemoveUser={userId => { void removeUser(removeWikiUser, userId, PANEL_COPY.wikiUserRemoved) }}
+              />
+            )
+          : null}
         {activeTab === 'advanced'
           ? <AdvancedTab form={form} onClear={() => { void onClear() }} />
           : null}

package/src/client/panel/sessions-tab.tsx

@@ -1,21 +1,24 @@
 /**
  * 「会话与行为」tab：行为 + 内容与附件两组字段（私聊/群聊触发方式、
- * 首次引导、权限切换、附件接收）。表单字段完全由 Host 描述驱动。
+ * 首次引导、权限切换、附件接收、日志分析接口）。表单字段完全由 Host 描述驱动；
+ * 日志分析接口令牌是凭据，单独一张卡片。
  *
  * @module dsh-channels/client/panel/sessions-tab
  */
 
 import { PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
+import { AnalyzeTokenCard } from './analyze-token-card.tsx'
 import { FieldsCard, SaveBar, TabHelp } from './shared.tsx'
-import type { FormView } from './shared.tsx'
+import type { AnalyzeTokenView, FormView } from './shared.tsx'
 
-export function SessionsTab(props: { form: FormView }): JSX.Element {
-  const { form } = props
+export function SessionsTab(props: { form: FormView; analyzeToken: AnalyzeTokenView }): JSX.Element {
+  const { form, analyzeToken } = props
   return (
     <div className="dsh-channels-cfg__tabBody">
       <TabHelp text={PANEL_COPY.sessionsTabHelp} />
       <FieldsCard form={form} groups={TAB_FIELD_GROUPS.sessions} />
       <SaveBar form={form} tab="sessions" />
+      <AnalyzeTokenCard panel={form.panel} token={analyzeToken} />
     </div>
   )
 }

package/src/client/panel/shared.tsx

@@ -182,6 +182,18 @@ export interface CredentialsView {
   onClear: (field: CredentialField) => void
 }
 
+/** Analyze API token editor data owned by the page shell, rendered by the sessions tab. */
+export interface AnalyzeTokenView {
+  value: string
+  issues: FieldIssueWire[]
+  busy: BusyAction | null
+  /** Host-side lifecycle busy (connecting/restarting): block writes. */
+  locked: boolean
+  onChange: (value: string) => void
+  onSave: () => void
+  onClear: () => void
+}
+
 /** Everything a field-bearing tab needs from the page shell's single draft. */
 export interface FormView {
   panel: PanelWire

package/src/client/panel/wiki-tab.tsx

@@ -0,0 +1,62 @@
+/**
+ * 「知识库」tab：知识库工具字段表单（读取/写入开关、知识库范围）+ 知识库
+ * 白名单卡。表单保存走全局 draft，白名单增删是独立即时 mutation。
+ *
+ * @module dsh-channels/client/panel/wiki-tab
+ */
+
+import { PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
+import { UserWhitelist } from './access-card.tsx'
+import { EmptyState, FieldsCard, SaveBar, TabHelp } from './shared.tsx'
+import type { FormView } from './shared.tsx'
+
+export interface WikiTabProps {
+  form: FormView
+  accessNotice: string | null
+  accessError: string | null
+  onAddUser: (userId: string, name: string) => Promise<boolean>
+  onRemoveUser: (userId: string) => void
+}
+
+export function WikiTab(props: WikiTabProps): JSX.Element {
+  const { form, accessNotice, accessError, onAddUser, onRemoveUser } = props
+  const { access } = form.panel
+  const disabled = form.busy !== null || form.locked || !access.loaded
+  return (
+    <div className="dsh-channels-cfg__tabBody">
+      <TabHelp text={PANEL_COPY.wikiTabHelp} />
+      <FieldsCard form={form} groups={TAB_FIELD_GROUPS.wiki} />
+      <SaveBar form={form} tab="wiki" />
+      <section className="dsh-channels-cfg__card">
+        <div className="dsh-channels-cfg__cardHead">
+          <span className="dsh-channels-cfg__cardTitle">{PANEL_COPY.wikiUsersCard}</span>
+        </div>
+        <span className="dsh-channels-cfg__help">{PANEL_COPY.wikiUsersHelp}</span>
+        {!access.loaded
+          ? <EmptyState text={PANEL_COPY.accessNotLoaded} />
+          : (
+              <UserWhitelist
+                title={PANEL_COPY.wikiUsersCard}
+                empty={PANEL_COPY.wikiUsersEmpty}
+                addLabel={PANEL_COPY.accessAddUser}
+                users={access.wikiUsers}
+                disabled={disabled}
+                working={form.busy === 'access'}
+                onAdd={onAddUser}
+                onRemove={onRemoveUser}
+              />
+            )}
+        {accessNotice === null
+          ? null
+          : (
+              <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--ok" role="status" aria-live="polite">
+                <span>{accessNotice}</span>
+              </div>
+            )}
+        {accessError === null
+          ? null
+          : <span className="dsh-channels-cfg__fieldError" role="alert">{accessError}</span>}
+      </section>
+    </div>
+  )
+}

package/src/config.ts

@@ -48,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
 
@@ -77,6 +80,12 @@ export const DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS = 20_000
  */
 export const DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS = 3_000
 
+/** Conventional credential reference holding the log-platform analyze API bearer token. */
+export const DEFAULT_ANALYZE_TOKEN_REF = 'DSH_CHANNELS_ANALYZE_TOKEN'
+
+/** `host:port` listen address of the analyze API (`[v6]:port` for IPv6 literals). */
+export const ANALYZE_LISTEN_PATTERN = /^(?:\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9.-]+):(?:[1-9][0-9]{0,4})$/u
+
 /** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
 const credentialRefSchema = z.string().regex(
   CREDENTIAL_REF_PATTERN,
@@ -265,10 +274,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.
@@ -288,14 +299,23 @@ 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` and
-   *   `feishu_wiki_read` so the model can browse the wiki nodes under
-   *   `wikiRoots` and read docx documents there. Needs `wiki:wiki` (or
-   *   `wiki:wiki:readonly`) and `docx:document` (or `docx:document:readonly`).
-   * - `wikiWrite` (default off): register `feishu_wiki_create` and
-   *   `feishu_wiki_edit` so the model can create docx documents under
-   *   `wikiRoots` and edit documents this app owns. Needs `wiki:wiki` and
-   *   `docx:document`.
+   * - `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:read`, and
+   *   `base:table:read` + `base:field:read` + `base:record:read` (the
+   *   classic `sheets:spreadsheet` / `bitable:app` grants do not apply).
+   * - `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:write_only`, and
+   *   `base:record:create` / `base:record:update` / `base:record:delete`,
+   *   plus the read scopes above.
    *
    * 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
@@ -309,9 +329,9 @@ export const configSchema = 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)
@@ -397,6 +417,24 @@ export const configSchema = z.object({
    * its own deadline and is left to the host signal instead.
    */
   questionTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_QUESTION_TIMEOUT_MS),
+  /**
+   * Listen address (`host:port`, e.g. `0.0.0.0:3090`) of the log-platform
+   * analyze API: a dedicated HTTP listener serving only
+   * `POST /dsh-channels/analyze`, separate from the DSH Web port. Unset
+   * (default) keeps the API off. The listener runs while the Feishu connection
+   * is up and is rebound on reconnect.
+   */
+  analyzeListen: z.string().trim().regex(
+    ANALYZE_LISTEN_PATTERN,
+    'must be host:port, e.g. 0.0.0.0:3090 or 127.0.0.1:3090',
+  ).refine(value => Number(value.slice(value.lastIndexOf(':') + 1)) <= 65_535, 'port must be 1-65535')
+    .optional(),
+  /**
+   * Credential reference holding the analyze API bearer token (defaults to
+   * `DSH_CHANNELS_ANALYZE_TOKEN`). Resolved per request, so rotating the value
+   * applies to the next request; an unresolvable token refuses every request.
+   */
+  analyzeToken: credentialRefSchema.default(DEFAULT_ANALYZE_TOKEN_REF),
 })
 
 export type FeishuConfig = z.infer<typeof configSchema>

package/src/domain.ts

@@ -61,6 +61,12 @@ export const routeRecordSchema = z.object({
   lastActivityAt: z.number().int().nonnegative(),
   /** Sessions this topic has pointed at, oldest first. Optional for v1 compatibility. */
   sessionHistory: z.array(sessionHistoryEntrySchema).optional(),
+  /**
+   * Group-shared route (log-platform analysis topics): every member admitted
+   * in `chatId` may continue the Session and decide its cards, not only
+   * `senderUserId` (who then names the requester). Absent = owner-only.
+   */
+  shared: z.literal(true).optional(),
 })
 
 export type RouteRecord = z.infer<typeof routeRecordSchema>
@@ -281,6 +287,40 @@ export const processedRecordSchema = z.object({
 
 export type ProcessedRecord = z.infer<typeof processedRecordSchema>
 
+/**
+ * One accepted analyze API request, keyed by its `Idempotency-Key`. Kept
+ * forever: a retried key returns the stored response instead of posting a
+ * second analysis, and a reused key with a different body is refused.
+ */
+export const analyzeRequestRecordSchema = z.object({
+  /** The request's `Idempotency-Key` (also the table key). */
+  key: z.string().min(1),
+  /** SHA-256 (hex) of the canonical request body. */
+  bodyHash: z.string().min(1),
+  /** Target group chat. */
+  chatId: z.string().min(1),
+  /** Root card message id (the analysis topic's root). */
+  messageId: z.string().min(1),
+  /** Epoch ms when the request was accepted. */
+  acceptedAt: z.number().int().nonnegative(),
+  /** What the root card shows, kept so the card can be redrawn after a restart. */
+  subject: z.object({
+    requesterUserId: z.string(),
+    triggeredAt: z.string(),
+    app: z.string(),
+    errorCode: z.string(),
+    logDetails: z.array(z.object({ name: z.string(), url: z.string() })),
+  }),
+  /**
+   * Root card status. `running` until the first turn settles; a record still
+   * `running` when the channel starts belongs to an analysis the previous
+   * instance never finished, and becomes `interrupted`.
+   */
+  status: z.enum(['running', 'done', 'stopped', 'error', 'failed', 'interrupted']),
+})
+
+export type AnalyzeRequestRecord = z.infer<typeof analyzeRequestRecordSchema>
+
 export interface FeishuDomainSpecShape {
   name: 'channels_routes_v2'
   version: 1
@@ -321,6 +361,10 @@ export interface FeishuDomainSpecShape {
       valueSchema: typeof accessUserRecordSchema
       __key?: string
     }
+    analyze_requests: {
+      valueSchema: typeof analyzeRequestRecordSchema
+      __key?: string
+    }
   }
 }
 
@@ -361,6 +405,8 @@ export const feishuDomain: FeishuDomainSpecShape = {
     // independent grant. Added without a version bump like the other access
     // tables: a missing table loads empty.
     access_wiki_users: { valueSchema: accessUserRecordSchema },
+    // Analyze API idempotency records; a missing table loads empty.
+    analyze_requests: { valueSchema: analyzeRequestRecordSchema },
   },
 }
 
@@ -427,6 +473,13 @@ export interface AccessRequestsTable {
   entries(): IterableIterator<[string, AccessRequestRecord]>
 }
 
+/** Normalized table handle for analyze API requests (key = `Idempotency-Key`). */
+export interface AnalyzeRequestsTable {
+  get(key: string): AnalyzeRequestRecord | undefined
+  put(key: string, value: AnalyzeRequestRecord): Promise<unknown> | void
+  entries(): IterableIterator<[string, AnalyzeRequestRecord]>
+}
+
 /** Normalized domain handle. */
 export interface FeishuDomainHandle {
   routes: RoutesTable
@@ -438,6 +491,8 @@ export interface FeishuDomainHandle {
   accessRequests: AccessRequestsTable
   /** Wiki whitelist (key = `user_id`); same records as {@link AccessUsersTable}. */
   accessWikiUsers: AccessUsersTable
+  /** Analyze API idempotency records. */
+  analyzeRequests: AnalyzeRequestsTable
   getGlobal(): FeishuDomainGlobal
   setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
   close(): Promise<void>

package/src/feishu/scopes.ts

@@ -91,16 +91,34 @@ const SEND_FILE_REQUIREMENT: ScopeRequirement = {
   anyOf: ['im:resource', 'im:resource:upload'], level: 'optional', purpose: '上传图片/文件，让模型用 feishu_send_file 把生成的文件发给用户',
 }
 
-/** Wiki read needs (`feishu_wiki_list` / `feishu_wiki_read`). */
+/**
+ * Spreadsheet and Base read needs, shared by the wiki read and write sets. The
+ * `sheet_ai/v2` and `base/v3` APIs accept only their fine-grained scopes; the
+ * classic `sheets:spreadsheet` / `bitable:app` grants do not satisfy them.
+ */
+const SHEET_BASE_READ_REQUIREMENTS: readonly ScopeRequirement[] = [
+  { anyOf: ['sheets:spreadsheet:read'], level: 'optional', purpose: '读取知识库电子表格（feishu_wiki_sheet_read）' },
+  { anyOf: ['base:table:read'], level: 'optional', purpose: '列出知识库多维表格的数据表（feishu_wiki_base_read）' },
+  { anyOf: ['base:field:read'], level: 'optional', purpose: '读取知识库多维表格的字段（feishu_wiki_base_read）' },
+  { anyOf: ['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:write_only'], level: 'optional', purpose: '写入知识库电子表格（feishu_wiki_sheet_edit）' },
+  { anyOf: ['base:record:create'], level: 'optional', purpose: '新增知识库多维表格记录（feishu_wiki_base_edit）' },
+  { anyOf: ['base:record:update'], level: 'optional', purpose: '修改本应用创建的多维表格中的记录（feishu_wiki_base_edit）' },
+  { anyOf: ['base:record:delete'], level: 'optional', purpose: '删除本应用创建的多维表格中的记录（feishu_wiki_base_edit）' },
+  ...SHEET_BASE_READ_REQUIREMENTS,
 ]
 
 /** Group receive needs while ordinary group messages require an @ mention. */

package/src/feishu/tools.ts

@@ -105,6 +105,8 @@ export interface AttachmentFetchRoute {
   readonly chatId: string
   readonly chatType: 'p2p' | 'group'
   readonly senderUserId: string
+  /** Group-shared route: messages of any sender in the route's topic count as its own. */
+  readonly shared?: boolean
 }
 
 /** Why a message became known to one route. */
@@ -811,7 +813,7 @@ export class AttachmentFetchToolRuntime {
     if (!read.ok) return undefined
     const container = quoteItemsOf(read.value)
     if (container === undefined || container.deleted) return undefined
-    if (container.senderUserId !== call.route.senderUserId) return undefined
+    if (call.route.shared !== true && container.senderUserId !== call.route.senderUserId) return undefined
     if (!messageBelongsToRoute(call.route, container)) return undefined
     return knownMessageOfItems(read.value)
   }