@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/src/client/lark-inbox/wizard.tsx

@@ -0,0 +1,211 @@
+import { useEffect, useState, type ReactNode } from 'react'
+import type { Translate } from './i18n.ts'
+import styles from './lark-wizard.module.css'
+
+export type WizardPhase = 'idle' | 'awaiting-browser' | 'awaiting-secret' | 'done' | 'failed'
+
+export interface WizardStatus {
+  phase: WizardPhase
+  mode?: 'new' | 'bind'
+  consoleUrl?: string
+  needsSecretPaste?: boolean
+  appId?: string
+  error?: string
+}
+
+interface StartNewResult { verificationUrl: string; qr: string | null }
+interface StartBindResult { consoleUrl: string }
+
+type WizardView =
+  | { kind: 'idle' }
+  | { kind: 'creating'; verificationUrl?: string; qr: string | null }
+  | { kind: 'bind-form' }
+  | { kind: 'bind-awaiting'; consoleUrl?: string }
+  | { kind: 'connected'; appId?: string; needsSecretPaste: boolean }
+  | { kind: 'failed'; error?: string }
+
+const WIZARD_BASE = '/lark-inbox/wizard'
+export const WIZARD_POLL_INTERVAL_MS = 2000
+
+async function readJson<T>(response: Response): Promise<T> {
+  const body = await response.json() as T & { error?: string }
+  if (!response.ok) throw new Error(body.error ?? `lark-inbox wizard request failed (${response.status})`)
+  return body
+}
+
+function request<T>(path: string, init?: RequestInit): Promise<T> {
+  return fetch(`${WIZARD_BASE}${path}`, init).then(readJson<T>)
+}
+
+function post<T>(path: string, payload?: unknown): Promise<T> {
+  return request(path, {
+    method: 'POST',
+    ...(payload === undefined ? {} : { headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload) }),
+  })
+}
+
+function get<T>(path: string): Promise<T> {
+  return request(path, { cache: 'no-store' })
+}
+
+function summarize(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export interface LarkInboxWizardProps {
+  t: Translate
+  disabled?: boolean
+}
+
+export function LarkInboxWizard({ t, disabled = false }: LarkInboxWizardProps): ReactNode {
+  const [view, setView] = useState<WizardView>({ kind: 'idle' })
+  const [busy, setBusy] = useState(false)
+  const [bindAppId, setBindAppId] = useState('')
+  const [bindAppSecret, setBindAppSecret] = useState('')
+
+  useEffect(() => {
+    let live = true
+    void get<WizardStatus>('/status').then((next) => {
+      if (!live) return
+      if (next.phase === 'done') setView({ kind: 'connected', appId: next.appId, needsSecretPaste: next.needsSecretPaste === true })
+      else if (next.phase === 'awaiting-browser') setView({ kind: 'creating', qr: null })
+      else if (next.phase === 'awaiting-secret') setView({ kind: 'connected', appId: next.appId, needsSecretPaste: true })
+      else if (next.phase === 'failed') setView({ kind: 'failed', error: next.error })
+    }).catch(() => undefined)
+    return () => { live = false }
+  }, [])
+
+  useEffect(() => {
+    if (view.kind !== 'creating') return
+    let live = true
+    const tick = async (): Promise<void> => {
+      try {
+        const next = await get<WizardStatus>('/status')
+        if (!live || next.phase === 'awaiting-browser') return
+        if (next.phase === 'done') setView({ kind: 'connected', appId: next.appId, needsSecretPaste: next.needsSecretPaste === true })
+        else if (next.phase === 'awaiting-secret') setView({ kind: 'connected', appId: next.appId, needsSecretPaste: true })
+        else if (next.phase === 'failed') setView({ kind: 'failed', error: next.error })
+        else setView({ kind: 'idle' })
+      } catch (error) {
+        if (live) setView({ kind: 'failed', error: summarize(error) })
+      }
+    }
+    void tick()
+    const interval = globalThis.setInterval(() => { void tick() }, WIZARD_POLL_INTERVAL_MS)
+    return () => { live = false; globalThis.clearInterval(interval) }
+  }, [view.kind])
+
+  const createNew = async (): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    try {
+      const result = await post<StartNewResult>('/start-new')
+      setView({ kind: 'creating', verificationUrl: result.verificationUrl, qr: result.qr })
+    } catch (error) {
+      setView({ kind: 'failed', error: summarize(error) })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const confirmBind = async (): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    try {
+      const result = await post<StartBindResult>('/start-bind', { appId: bindAppId.trim() })
+      setView({ kind: 'bind-awaiting', consoleUrl: result.consoleUrl })
+    } catch (error) {
+      setView({ kind: 'failed', error: summarize(error) })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const finishBind = async (): Promise<void> => {
+    if (busy) return
+    setBusy(true)
+    try {
+      await post<{ ok: boolean }>('/finish-bind', { appSecret: bindAppSecret })
+      setView({ kind: 'connected', appId: bindAppId.trim(), needsSecretPaste: false })
+    } catch (error) {
+      setView({ kind: 'failed', error: summarize(error) })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const clear = (): void => {
+    setView({ kind: 'idle' })
+    setBindAppId('')
+    setBindAppSecret('')
+  }
+
+  const cancel = async (): Promise<void> => {
+    try { await post<{ ok: boolean }>('/cancel') } catch { /* best effort */ }
+    clear()
+  }
+
+  const cancelButton = <button type="button" className={styles.secondary} disabled={busy} onClick={() => { void cancel() }}>{t('wizard.cancel')}</button>
+  let body: ReactNode
+
+  if (view.kind === 'idle') {
+    body = <div className={styles.actions} data-dsh-part="actions">
+      <button type="button" className={styles.primary} disabled={disabled || busy} onClick={() => { void createNew() }}>{t('wizard.createNew')}</button>
+      <button type="button" className={styles.secondary} disabled={disabled || busy} onClick={() => { setBindAppId(''); setBindAppSecret(''); setView({ kind: 'bind-form' }) }}>{t('wizard.bindExisting')}</button>
+    </div>
+  } else if (view.kind === 'creating') {
+    body = <div className={styles.panel} data-dsh-part="authorization">
+      {view.verificationUrl ? <p className={styles.hint}>{t('wizard.openLinkHint')}<a href={view.verificationUrl} target="_blank" rel="noreferrer" className={styles.link}>{view.verificationUrl}</a></p> : null}
+      {view.qr !== null ? <img src={`${WIZARD_BASE}/qr.png`} alt={t('wizard.qrAlt')} className={styles.qr}/> : null}
+      <p className={styles.hint}>{t('wizard.awaitingHint')}</p>
+      <div className={styles.actions}>{cancelButton}</div>
+    </div>
+  } else if (view.kind === 'bind-form') {
+    body = <div className={styles.panel} data-dsh-part="bind-form">
+      <WizardField id="lark-inbox-wizard-bind-appid" label={t('wizard.appId')} hint={t('wizard.appIdHint')} value={bindAppId} disabled={disabled} onChange={setBindAppId}/>
+      <WizardField id="lark-inbox-wizard-bind-appsecret" label={t('wizard.appSecret')} hint={t('wizard.appSecretHint')} value={bindAppSecret} disabled={disabled} secret onChange={setBindAppSecret}/>
+      <div className={styles.actions}>
+        <button type="button" className={styles.primary} disabled={disabled || busy || bindAppId.trim() === '' || bindAppSecret.trim() === ''} onClick={() => { void confirmBind() }}>{t('wizard.confirmBind')}</button>
+        {cancelButton}
+      </div>
+    </div>
+  } else if (view.kind === 'bind-awaiting') {
+    body = <div className={styles.panel} data-dsh-part="bind-finish">
+      <p className={styles.meta}>{t('wizard.appId')}: {bindAppId.trim()}</p>
+      {view.consoleUrl ? <p className={styles.hint}>{t('wizard.openConsoleHint')}<a href={view.consoleUrl} target="_blank" rel="noreferrer" className={styles.link}>{view.consoleUrl}</a></p> : null}
+      <WizardField id="lark-inbox-wizard-finish-appsecret" label={t('wizard.appSecret')} hint={t('wizard.appSecretHint')} value={bindAppSecret} disabled={disabled} secret onChange={setBindAppSecret}/>
+      <div className={styles.actions}>
+        <button type="button" className={styles.primary} disabled={disabled || busy || bindAppSecret.trim() === ''} onClick={() => { void finishBind() }}>{t('wizard.finishBind')}</button>
+        {cancelButton}
+      </div>
+    </div>
+  } else if (view.kind === 'connected') {
+    body = <div className={styles.panel} data-dsh-part="result">
+      {view.needsSecretPaste ? <p className={styles.hint}>{t('wizard.needsSecretHint')}</p> : <><p className={styles.success}>{t('wizard.connected', { appId: view.appId ?? '' })}</p><p className={styles.hint}>{t('wizard.connectedHint')}</p></>}
+      <div className={styles.actions}><button type="button" className={styles.secondary} onClick={clear}>{t('wizard.back')}</button></div>
+    </div>
+  } else {
+    body = <div className={styles.panel} data-dsh-part="result">
+      <p className={styles.error} role="alert">{t('wizard.failed')}</p>
+      {view.error ? <p className={styles.errorDetail}>{view.error}</p> : null}
+      <p className={styles.hint}>{t('wizard.installHint')}</p>
+      <div className={styles.actions}><button type="button" className={styles.secondary} onClick={clear}>{t('wizard.back')}</button></div>
+    </div>
+  }
+
+  // 标题由面板外壳（LarkPanel）提供，这里不再重复渲染。
+  return <div className={styles.wizard} data-dsh-plugin="lark-inbox" data-dsh-part="wizard">
+    {body}
+    {busy ? <p className={styles.hint} role="status">{t('wizard.busy')}</p> : null}
+  </div>
+}
+
+function WizardField(props: { id: string; label: string; hint: string; value: string; disabled: boolean; secret?: boolean; onChange(text: string): void }): ReactNode {
+  return <div className={styles.wizardField}>
+    <label className={styles.label} htmlFor={props.id}>{props.label}</label>
+    <input id={props.id} className={styles.input} type={props.secret ? 'password' : 'text'} value={props.value} autoComplete="off" spellCheck={false} disabled={props.disabled} onChange={event => { props.onChange(event.target.value) }}/>
+    <p className={styles.hint}>{props.hint}</p>
+  </div>
+}
+
+export const LARK_WIZARD_ROUTE_BASE = WIZARD_BASE

package/src/client/notify/i18n.ts

@@ -0,0 +1,93 @@
+/**
+ * 通知设置页的本地字典（飞书推送配置）。
+ *
+ * 与飞书设置页同一套约定：zh 是键集来源，en 必须保持同一键集；页面自带字典，
+ * 不依赖设置位置的 locale 命名空间。
+ */
+
+export const zh = {
+  'settings.tab': '通知',
+  'settings.title': '运行结束通知',
+  'settings.intro': '会话运行结束后，把结果推送到飞书，并让桌面端与手机端的机器列表标出未查看的结果。',
+  'settings.summary': '运行结束后推送到飞书，并在机器列表标出未查看的结果。',
+  'settings.enabled': '启用通知',
+  'settings.enabledHint': '关闭后不记录运行结果，机器列表也不再显示未查看标记；已记录的结果会被清空。',
+  'settings.feedLimit': '单次读取返回条数',
+  'settings.feedLimitHint': '客户端一次拉取最多拿到多少条结果。留空使用默认值 20。',
+  'settings.feishuEnabled': '推送到飞书',
+  'settings.feishuEnabledHint': '开启后，运行结束会由机器人发送消息给你。需要下面填好应用凭据与收件人。',
+  'settings.feishuAppId': '飞书 App ID',
+  'settings.feishuAppIdHint': '留空则沿用「飞书」页配置的机器人应用。',
+  'settings.feishuAppSecret': '飞书 App Secret',
+  'settings.feishuAppSecretHint': '可填 env:变量名 从环境变量读取。留空则沿用「飞书」页配置的应用。',
+  'settings.feishuDomain': '开放平台域名',
+  'settings.feishuDomainHint': 'feishu（飞书）或 lark（Lark 国际版）。留空使用默认值 feishu。',
+  'settings.feishuRecipients': '收件人',
+  'settings.feishuRecipientsHint': '一行一个 open_id（ou_ 开头）或 chat_id（oc_ 开头）。留空表示不推送。',
+  'settings.feishuMode': '推送时机',
+  'settings.feishuModeHint': 'idle：等这一轮工作彻底停下后合并成一条；each-turn：每结束一轮就发一条。留空使用默认值 idle。',
+  'settings.feishuOutcomes': '推送哪些结果',
+  'settings.feishuOutcomesHint': '一行一个：completed（已完成）、failed（出错）、stopped（已结束）。留空使用默认值 completed 与 failed。',
+  'settings.save': '保存',
+  'settings.saving': '保存中…',
+  'settings.saveFailed': '本部署没有接受这些值，已保留供你修改。',
+  'settings.readOnly': '本部署的设置为只读。',
+  'settings.unavailable': '宿主当前未提供通知配置，暂时无法编辑。',
+  'settings.overridden': '已覆盖',
+  'settings.reset': '恢复默认',
+  'settings.invalid': '该值不被接受，请修改或清空以恢复默认。',
+  'settings.invalidNumber': '请填数字；留空表示使用默认值。',
+  'settings.feed': '客户端读取地址',
+  'settings.feedHint': '桌面端与手机端按这个地址拉取运行结果；它只读，且需要本机或已声明入口的访问权限。',
+} as const
+
+export type NotifyKey = keyof typeof zh
+
+export const en: Record<NotifyKey, string> = {
+  'settings.tab': 'Notifications',
+  'settings.title': 'Run-finished notifications',
+  'settings.intro': 'When a session finishes running, push the result to Feishu and mark the unseen results in the desktop and mobile machine lists.',
+  'settings.summary': 'Push finished runs to Feishu and mark unseen results in the machine list.',
+  'settings.enabled': 'Enable notifications',
+  'settings.enabledHint': 'When off, run results are not recorded and the machine list stops marking unseen ones; already recorded results are dropped.',
+  'settings.feedLimit': 'Notices per read',
+  'settings.feedLimitHint': 'How many results a client receives in one pull. Leave blank to use the default of 20.',
+  'settings.feishuEnabled': 'Push to Feishu',
+  'settings.feishuEnabledHint': 'When on, the bot messages you when a run finishes. Requires the credentials and recipients below.',
+  'settings.feishuAppId': 'Feishu App ID',
+  'settings.feishuAppIdHint': 'Leave blank to reuse the bot configured on the Feishu page.',
+  'settings.feishuAppSecret': 'Feishu App Secret',
+  'settings.feishuAppSecretHint': 'Accepts env:NAME to read an environment variable. Leave blank to reuse the application configured on the Feishu page.',
+  'settings.feishuDomain': 'Open platform domain',
+  'settings.feishuDomainHint': 'feishu or lark. Leave blank to use the default (feishu).',
+  'settings.feishuRecipients': 'Recipients',
+  'settings.feishuRecipientsHint': 'One open_id (starts with ou_) or chat_id (starts with oc_) per line. Leave blank to push nothing.',
+  'settings.feishuMode': 'When to push',
+  'settings.feishuModeHint': 'idle waits until the work has fully stopped and sends one message; each-turn sends one message per finished turn. Leave blank for the default (idle).',
+  'settings.feishuOutcomes': 'Which results to push',
+  'settings.feishuOutcomesHint': 'One per line: completed, failed, stopped. Leave blank for the default (completed and failed).',
+  'settings.save': 'Save',
+  'settings.saving': 'Saving…',
+  'settings.saveFailed': 'The deployment did not accept these values; they were left for you to correct.',
+  'settings.readOnly': 'This deployment stores settings read-only.',
+  'settings.unavailable': 'The host does not serve notification settings right now, so they cannot be edited.',
+  'settings.overridden': 'Overridden',
+  'settings.reset': 'Reset to default',
+  'settings.invalid': 'This value is not accepted; change it or clear it to use the default.',
+  'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
+  'settings.feed': 'Client read address',
+  'settings.feedHint': 'The desktop and mobile clients pull run results from this address. It is read-only and requires local access or a declared entry.',
+}
+
+export type Translate = (key: NotifyKey, params?: Record<string, string | number>) => string
+
+/** 取字典：`<html lang>` 以 zh 开头用中文，否则英文。 */
+export function makeT(doc: Document | undefined = typeof document === 'undefined' ? undefined : document): Translate {
+  const lang = doc?.documentElement?.lang?.toLowerCase() ?? ''
+  const table: Record<NotifyKey, string> = lang.startsWith('zh') ? zh : en
+  return (key, params) => {
+    const text = table[key] ?? key
+    if (params === undefined) return text
+    return text.replace(/\{(\w+)\}/gu, (match, name: string) => params[name] === undefined ? match : String(params[name]))
+  }
+}

package/src/client/settings/family-scope.ts

@@ -0,0 +1,45 @@
+/**
+ * 家族设置作用域：把 `web-all` 聚合条目的读写面收窄到一个能力域命名空间。
+ *
+ * DSH 0.2 的客户端设置面按命名空间寻址，而家族的全部能力域聚合在单个 `web-all`
+ * 条目里（顶层 volatile 子键就是能力域，见 host 的 `family-config.ts`）。这里做
+ * 一次路径前缀适配：读侧下钻子对象，写侧给每个路径加上子键前缀，于是官方
+ * `SettingsFormModel` / `SettingsForm` 的 staged 编辑、保存与 revision 闸门都能
+ * 原样复用，每个能力域不必各自实现一遍。
+ *
+ * 该适配只做路径搬运，不解释值：字段的格式化与校验仍由各页自己的 `SettingsFieldSpec`
+ * 负责。
+ */
+import type { SettingsFormScope, SettingsFormScopeSnapshot } from './primitives-0.2.ts'
+
+/** 家族聚合条目在宿主 settings 镜像里的条目 id（host 的 `FAMILY_ENTRY_ID`）。 */
+export const FAMILY_SETTINGS_NAMESPACE = 'web-all'
+
+/**
+ * 把聚合条目的作用域收窄到一个命名空间。
+ * @param entry - `configForms.get('web-all')` 返回的聚合读写面。
+ * @param namespace - 能力域在条目里的子键。
+ * @returns 只读写该命名空间的等价作用域。
+ */
+export function familyNamespaceScope<T>(entry: SettingsFormScope<Record<string, unknown>>, namespace: string): SettingsFormScope<T> {
+  const section = (snapshot: SettingsFormScopeSnapshot<Record<string, unknown>>): SettingsFormScopeSnapshot<T> => {
+    const value = snapshot.value as Record<string, unknown> | undefined
+    const base = snapshot.base as Record<string, unknown> | undefined
+    const user = snapshot.user as Record<string, unknown> | undefined
+    return {
+      status: snapshot.status,
+      value: value?.[namespace] as T | undefined,
+      base: base?.[namespace],
+      user: user?.[namespace],
+      writable: snapshot.writable,
+      revision: snapshot.revision,
+    }
+  }
+  return {
+    getSnapshot: () => section(entry.getSnapshot()),
+    subscribe: listener => entry.subscribe(listener),
+    mutate: (ops, expectedRevision) => entry.mutate(ops.map((op) => op.op === 'set'
+      ? { op: 'set' as const, path: [namespace, ...op.path], value: op.value }
+      : { op: 'unset' as const, path: [namespace, ...op.path] }), expectedRevision),
+  }
+}

package/src/client/settings/lark-inbox.tsx

@@ -0,0 +1,319 @@
+/**
+ * 飞书设置页（DSH 0.2）。
+ *
+ * 位置：设置 → 内置插件 的「飞书」标签页（官方 `settings.plugins.tab`），
+ * 只在宿主确实提供 `lark-inbox` 命名空间时才出现（`configForms.whileServed`，
+ * 与官方 Agent loop / Subagent 等配置页同一套机制）。
+ *
+ * 数据：表单走官方 `SettingsFormModel` + `SettingsForm`（staged 编辑、保存时才
+ * 落盘、写入带 revision 闸门），凭据仍由连接向导经宿主 loopback 路由写入。
+ */
+import { type ReactNode } from 'react'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import {
+  Checkbox,
+  SettingsForm,
+  SettingsFormModel,
+  SettingsValueField,
+  settingsNumberField,
+  settingsTextField,
+  type SettingsFieldSpec,
+  type SettingsFieldState,
+  type SettingsFormScope,
+  type SettingsFormShell,
+} from './primitives-0.2.ts'
+import { LarkInboxWizard } from '../lark-inbox/wizard.tsx'
+import { makeT, type Translate } from '../lark-inbox/i18n.ts'
+import css from './settings-shell.module.css'
+import { FAMILY_SETTINGS_NAMESPACE, familyNamespaceScope } from './family-scope.ts'
+
+/** 家族聚合条目在宿主 settings 镜像里的命名空间（host FAMILY_ENTRY_ID）。 */
+export { FAMILY_SETTINGS_NAMESPACE }
+
+/** 条目里飞书能力域的子键（host 的 family namespace）。 */
+export const LARK_INBOX_NAMESPACE = 'lark-inbox'
+
+/** 面板编辑的字段子集。 */
+export interface LarkInboxSettings {
+  enabled?: boolean
+  announceToAgent?: boolean
+  domain?: 'feishu' | 'lark'
+  requireMentionInGroup?: boolean
+  allowedOpenIds?: string[]
+  queueDir?: string
+  maxAttempts?: number
+  staleTimeoutMs?: number
+}
+
+/** 布尔字段：草稿文本用 'true'/'false'，空草稿表示恢复默认。 */
+function booleanField(field: string): SettingsFieldSpec {
+  return {
+    field,
+    format: value => value === true ? 'true' : value === false ? 'false' : '',
+    parse: (text) => {
+      if (text === 'true') return { kind: 'set', value: true }
+      if (text === 'false') return { kind: 'set', value: false }
+      return text === '' ? { kind: 'clear' } : undefined
+    },
+  }
+}
+
+/** 开放 ID 列表：一行一个，也接受逗号/分号分隔。 */
+function openIdsField(): SettingsFieldSpec {
+  return {
+    field: 'allowedOpenIds',
+    format: value => Array.isArray(value) ? value.join('\n') : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      return { kind: 'set', value: trimmed.split(/[\n,;]+/u).map(item => item.trim()).filter(Boolean) }
+    },
+  }
+}
+
+/** 设置页投影给组件的状态。 */
+interface LarkCardState extends SettingsFormShell {
+  enabled: SettingsFieldState
+  announceToAgent: SettingsFieldState
+  domain: SettingsFieldState
+  requireMentionInGroup: SettingsFieldState
+  allowedOpenIds: SettingsFieldState
+  queueDir: SettingsFieldState
+  maxAttempts: SettingsFieldState
+  staleTimeoutMs: SettingsFieldState
+}
+
+/** 组件读取的 store 面（SnapshotStore 的结构子集）。 */
+interface LarkCardStore {
+  getSnapshot(): LarkCardState
+  subscribe(listener: () => void): () => void
+}
+
+/** 页面控制器：把 `lark-inbox` 命名空间桥到官方 staged 表单。 */
+export class LarkSettingsController {
+  private readonly form: SettingsFormModel<LarkInboxSettings>
+  private readonly store: LarkCardStore
+
+  constructor(scope: SettingsFormScope<LarkInboxSettings>) {
+    this.form = new SettingsFormModel<LarkInboxSettings>(scope, [
+      booleanField('enabled'),
+      booleanField('announceToAgent'),
+      settingsTextField('domain'),
+      booleanField('requireMentionInGroup'),
+      openIdsField(),
+      settingsTextField('queueDir'),
+      settingsNumberField('maxAttempts'),
+      settingsNumberField('staleTimeoutMs'),
+    ])
+    this.store = this.form.bind(() => this.projection())
+  }
+
+  private projection(): LarkCardState {
+    return {
+      ...this.form.shell(),
+      enabled: this.form.field('enabled'),
+      announceToAgent: this.form.field('announceToAgent'),
+      domain: this.form.field('domain'),
+      requireMentionInGroup: this.form.field('requireMentionInGroup'),
+      allowedOpenIds: this.form.field('allowedOpenIds'),
+      queueDir: this.form.field('queueDir'),
+      maxAttempts: this.form.field('maxAttempts'),
+      staleTimeoutMs: this.form.field('staleTimeoutMs'),
+    }
+  }
+
+  /** 槽注入面：投影 store + 表单动作。 */
+  inject(): Record<string, unknown> {
+    return { hooks: { larkCard: this.store }, ...this.form.actions() }
+  }
+
+  dispose(): void {
+    this.form.dispose()
+  }
+}
+
+interface LarkPageProps {
+  view?: 'summary' | 'full'
+  useLarkCard<T>(select: (state: LarkCardState) => T): T
+  edit(field: string, text: string): void
+  resetField(field: string): void
+  save(): void
+  discard(): void
+  t: Translate
+}
+
+/** 一个布尔开关行。 */
+function BooleanRow({ id, label, hint, field, state, disabled, edit, resetField, t }: {
+  id: string
+  label: string
+  hint: string
+  field: 'enabled' | 'announceToAgent' | 'requireMentionInGroup'
+  state: LarkCardState
+  disabled: boolean
+  edit(field: string, text: string): void
+  resetField(field: string): void
+  t: Translate
+}): ReactNode {
+  const cell = state[field]
+  const checked = cell.text === '' ? false : cell.text === 'true'
+  return (
+    <div className={css.row} data-dsh-part="field" data-field={field}>
+      <div className={css.rowHead}>
+        <Checkbox
+          checked={checked}
+          disabled={disabled}
+          label={label}
+          onChange={(next) => { edit(field, next ? 'true' : 'false') }}
+        />
+        {cell.overridden
+          ? <button type="button" className={css.reset} disabled={disabled} onClick={() => { resetField(field) }}>{t('settings.reset')}</button>
+          : null}
+      </div>
+      <p className={css.hint} id={id}>{hint}</p>
+    </div>
+  )
+}
+
+/** 未设置该字段表示沿用默认（启用）；显式关闭即不显示连接向导。 */
+export function larkWizardVisible(state: Pick<LarkCardState, 'enabled'>): boolean {
+  return state.enabled.text === '' ? true : state.enabled.text === 'true'
+}
+
+/** 设置标签页主体：连接向导 + 命名空间配置表单。 */
+export function LarkSettingsPage(props: LarkPageProps): ReactNode {
+  const state = props.useLarkCard(value => value)
+  if (props.view === 'summary') return props.t('settings.summary')
+  const t = props.t
+  const disabled = !state.writable
+  // 已关闭的功能不显示连接向导：宿主也会拒绝它的写操作，显示一个必然失败的
+  // 向导只会误导用户。
+  const enabled = larkWizardVisible(state)
+  return (
+    <div className={css.page} data-dsh-plugin="lark-inbox" data-dsh-part="settings">
+      <h3 className={css.title}>{t('settings.title')}</h3>
+      <p className={css.intro}>{t('settings.intro')}</p>
+      {enabled ? <LarkInboxWizard t={t}/> : null}
+      <SettingsForm
+        labels={{
+          unavailable: t('settings.unavailable'),
+          readOnly: t('settings.readOnly'),
+          saveFailed: t('settings.saveFailed'),
+          save: t('settings.save'),
+          saving: t('settings.saving'),
+        }}
+        state={state}
+        onSave={props.save}
+        onDiscard={props.discard}
+      >
+        <BooleanRow id="lark-enabled-hint" label={t('settings.enabled')} hint={t('settings.enabledHint')} field="enabled" state={state} disabled={disabled} edit={props.edit} resetField={props.resetField} t={t}/>
+        <BooleanRow id="lark-announce-hint" label={t('settings.announce')} hint={t('settings.announceHint')} field="announceToAgent" state={state} disabled={disabled} edit={props.edit} resetField={props.resetField} t={t}/>
+        <SettingsValueField
+          id="lark-domain"
+          label={t('settings.domain')}
+          hint={t('settings.domainHint')}
+          overriddenLabel={t('settings.overridden')}
+          resetLabel={t('settings.reset')}
+          invalidLabel={t('settings.invalid')}
+          disabled={disabled}
+          {...state.domain}
+          onEdit={(text) => { props.edit('domain', text) }}
+          onReset={() => { props.resetField('domain') }}
+        />
+        <BooleanRow id="lark-mention-hint" label={t('settings.requireMention')} hint={t('settings.requireMentionHint')} field="requireMentionInGroup" state={state} disabled={disabled} edit={props.edit} resetField={props.resetField} t={t}/>
+        <SettingsValueField
+          id="lark-open-ids"
+          label={t('settings.allowedOpenIds')}
+          hint={t('settings.allowedOpenIdsHint')}
+          overriddenLabel={t('settings.overridden')}
+          resetLabel={t('settings.reset')}
+          invalidLabel={t('settings.invalid')}
+          disabled={disabled}
+          {...state.allowedOpenIds}
+          onEdit={(text) => { props.edit('allowedOpenIds', text) }}
+          onReset={() => { props.resetField('allowedOpenIds') }}
+        />
+        <SettingsValueField
+          id="lark-queue-dir"
+          label={t('settings.queueDir')}
+          hint={t('settings.queueDirHint')}
+          overriddenLabel={t('settings.overridden')}
+          resetLabel={t('settings.reset')}
+          invalidLabel={t('settings.invalid')}
+          disabled={disabled}
+          {...state.queueDir}
+          onEdit={(text) => { props.edit('queueDir', text) }}
+          onReset={() => { props.resetField('queueDir') }}
+        />
+        <SettingsValueField
+          id="lark-max-attempts"
+          label={t('settings.maxAttempts')}
+          hint={t('settings.maxAttemptsHint')}
+          overriddenLabel={t('settings.overridden')}
+          resetLabel={t('settings.reset')}
+          invalidLabel={t('settings.invalidNumber')}
+          numeric
+          disabled={disabled}
+          {...state.maxAttempts}
+          onEdit={(text) => { props.edit('maxAttempts', text) }}
+          onReset={() => { props.resetField('maxAttempts') }}
+        />
+        <SettingsValueField
+          id="lark-stale-timeout"
+          label={t('settings.staleTimeout')}
+          hint={t('settings.staleTimeoutHint')}
+          overriddenLabel={t('settings.overridden')}
+          resetLabel={t('settings.reset')}
+          invalidLabel={t('settings.invalidNumber')}
+          numeric
+          disabled={disabled}
+          {...state.staleTimeoutMs}
+          onEdit={(text) => { props.edit('staleTimeoutMs', text) }}
+          onReset={() => { props.resetField('staleTimeoutMs') }}
+        />
+      </SettingsForm>
+    </div>
+  )
+}
+
+/** 官方 configForms 服务的结构面（未装载设置界面时整页不注册）。 */
+interface ConfigFormsFace {
+  get(entryId: string): SettingsFormScope<Record<string, unknown>>
+  whileServed(namespaces: readonly string[], register: (served: ReadonlySet<string>) => () => void): () => void
+}
+
+function optionalConfigForms(ctx: ClientContext): ConfigFormsFace | undefined {
+  try { return (ctx.get as unknown as (id: string, strict?: boolean) => unknown)('configForms', false) as ConfigFormsFace | undefined } catch { return undefined }
+}
+
+/**
+ * 把 `web-all` 条目的读写面收窄到 `lark-inbox` 子键。
+ *
+ * 前缀适配的实现在 `family-scope.ts`，与其它能力域共用。
+ */
+export function larkInboxScope(entry: SettingsFormScope<Record<string, unknown>>): SettingsFormScope<LarkInboxSettings> {
+  return familyNamespaceScope<LarkInboxSettings>(entry, LARK_INBOX_NAMESPACE)
+}
+
+/** 注册「内置插件 → 飞书」标签页；宿主不再提供该命名空间时自动撤下。 */
+export function mountLarkSettings(ctx: ClientContext): () => void {
+  const configForms = optionalConfigForms(ctx)
+  if (configForms === undefined) return () => {}
+  const t = makeT()
+  const controller = new LarkSettingsController(larkInboxScope(configForms.get(FAMILY_SETTINGS_NAMESPACE)))
+  const offPage = configForms.whileServed([FAMILY_SETTINGS_NAMESPACE], () => ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
+    name: 'settings.plugins.tab',
+    id: LARK_INBOX_NAMESPACE,
+    order: 60,
+    label: () => t('settings.tab'),
+    inject: () => ({ ...controller.inject(), t }),
+  } as never, LarkSettingsPage as never) as unknown as () => void))
+  let disposed = false
+  return () => {
+    if (disposed) return
+    disposed = true
+    offPage()
+    controller.dispose()
+  }
+}