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

package/src/settings/surface.ts

@@ -12,6 +12,8 @@
 
 import { DSH_CHANNELS_VERSION } from '../session-export.ts'
 import type { FeishuConfig } from '../config.ts'
+import { FEISHU_USER_ID_PATTERN } from '../domain.ts'
+import { parseWikiRootLink, WIKI_ROOT_LINK_ERRORS } from '../feishu/wiki/links.ts'
 import type { HealthSnapshot } from '../health.ts'
 import { prepareWorkspaceBaseDir } from '../workspaces.ts'
 import {
@@ -25,9 +27,6 @@ import type {
   CatalogWire,
   ChannelPhaseWire,
   ChannelStatusWire,
-  CleanupPreviewWire,
-  CleanupResponse,
-  CleanupRunWire,
   ClearConfigResponse,
   ClearCredentialResponse,
   ConfigValue,
@@ -45,6 +44,9 @@ import type {
   SaveConfigResponse,
   SaveCredentialsRequest,
   SaveCredentialsResponse,
+  ScopeCheckWire,
+  SlashCommandSyncWire,
+  StringListItemFormat,
 } from './contract.ts'
 import {
   configValueOf,
@@ -71,6 +73,10 @@ export interface SettingsTarget {
   startedAtMs(): number | undefined
   uptimeMs(): number | undefined
   startError(): string | undefined
+  /** Post-connect scope self-check for the open connection, once it finished. */
+  scopeCheck(): ScopeCheckWire | undefined
+  /** Post-connect native slash-command panel sync for the open connection, once it finished. */
+  slashCommandSync(): SlashCommandSyncWire | undefined
   /**
    * Whether the Feishu application credentials resolve. A false value means the
    * plugin is loaded but deliberately holds no connection: the panel guides the
@@ -91,20 +97,16 @@ export interface SettingsTarget {
   credentialStates(): Promise<{ appId: CredentialInfo; appSecret: CredentialInfo }>
   setCredential(field: CredentialField, value: string): Promise<void>
   clearCredential(field: CredentialField): Promise<void>
-  /** What the workspace-retention cleanup would delete right now (read-only scan). */
-  cleanupPreview(): Promise<CleanupPreviewWire>
-  /** Run the workspace cleanup once; partial failures are reported per workspace. */
-  runWorkspaceCleanup(): Promise<CleanupRunWire>
   /** Current admission snapshot: mode, administrator, whitelists, pending requests. */
   accessSnapshot(): AccessWire
   /** Authorize one group (panel entry); resolves with the refreshed snapshot. */
   addAccessGroup(chatId: string, name?: string): Promise<AccessMutationResponse>
   /** Revoke one group authorization (takes effect on the next message). */
   removeAccessGroup(chatId: string): Promise<AccessMutationResponse>
-  /** Authorize one user `open_id` (global across authorized groups). */
-  addAccessUser(openId: string, name?: string): Promise<AccessMutationResponse>
+  /** Authorize one user `user_id` (global across authorized groups). */
+  addAccessUser(userId: string, name?: string): Promise<AccessMutationResponse>
   /** Revoke one user authorization (takes effect on the next message). */
-  removeAccessUser(openId: string): Promise<AccessMutationResponse>
+  removeAccessUser(userId: string): Promise<AccessMutationResponse>
   /** Settle one pending request (panel shares this path with the Feishu DM card). */
   resolveAccessRequest(token: string, decision: 'allow' | 'deny'): Promise<AccessMutationResponse>
 }
@@ -124,20 +126,90 @@ const OPTIONAL_TEXT_KEYS = new Set<EditableKey>([
   'model',
   'reasoningEffort',
   'agentPreset',
-  'adminOpenId',
+  'adminUserId',
 ])
 
 const BOOLEAN_KEYS = new Set<EditableKey>([
   'requireMention',
   'welcomeOnboarding',
+  'slashCommandPanel',
   'allowPermissionSwitch',
   'acceptAttachments',
   'prefetchImages',
-  'workspaceRetentionAuto',
   'feishuTools.attachmentFetch',
   'feishuTools.topicMessages',
+  'feishuTools.sendFile',
+  'feishuTools.wikiRead',
+  'feishuTools.wikiWrite',
 ])
 
+/** Bounds and entry format of one `string-list` field. */
+interface StringListSpec {
+  /** Most non-empty entries accepted (mirrors the config schema bound). */
+  maxItems: number
+  itemFormat?: StringListItemFormat
+}
+
+/** Editable keys rendered as `string-list` (one input per entry). */
+const STRING_LIST_FIELDS: Partial<Record<EditableKey, StringListSpec>> = {
+  wikiRoots: { maxItems: 20, itemFormat: 'wiki-root-link' },
+}
+
+/** 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]
+  },
+}
+
+/** `第 N 项「entry」：reason`, shared wording with the Client check. */
+function listEntryMessage(index: number, entry: string | undefined, reason: string): string {
+  const position = PANEL_COPY.listEntry.replace('{n}', String(index + 1))
+  return entry === undefined ? `${position}${reason}` : `${position}「${entry}」：${reason}`
+}
+
+/**
+ * Normalize one submitted `string-list` value: entries are trimmed, empty
+ * entries dropped, the count bounded by `maxItems`, and every remaining entry
+ * checked against `itemFormat`. Issue indexes refer to the submitted array
+ * (empty inputs included), so the panel can mark the exact input.
+ *
+ * @param key - The editable key the issues are reported under.
+ * @param raw - The untrusted submitted value.
+ * @param spec - The field's bounds and entry format.
+ * @returns The cleaned entries, or every per-entry / whole-field issue.
+ */
+export function normalizeStringList(
+  key: EditableKey,
+  raw: unknown,
+  spec: StringListSpec,
+): { ok: true; value: string[] } | { ok: false; issues: FieldIssueWire[] } {
+  if (!Array.isArray(raw)) return { ok: false, issues: [{ key, message: PANEL_COPY.listNotArray }] }
+  const issues: FieldIssueWire[] = []
+  const value: string[] = []
+  const check = spec.itemFormat === undefined ? undefined : ITEM_FORMAT_CHECKS[spec.itemFormat]
+  raw.forEach((item: unknown, index) => {
+    if (typeof item !== 'string') {
+      issues.push({ key, index, message: listEntryMessage(index, undefined, PANEL_COPY.listEntryNotString) })
+      return
+    }
+    const entry = item.trim()
+    if (entry === '') return
+    const reason = check?.(entry)
+    if (reason !== undefined) {
+      issues.push({ key, index, message: listEntryMessage(index, entry, reason) })
+      return
+    }
+    value.push(entry)
+  })
+  const count = raw.filter(item => typeof item !== 'string' || item.trim() !== '').length
+  if (count > spec.maxItems) {
+    issues.push({ key, message: PANEL_COPY.listTooMany.replace('{max}', String(spec.maxItems)) })
+  }
+  return issues.length > 0 ? { ok: false, issues } : { ok: true, value }
+}
+
 const SELECT_OPTIONS: Partial<Record<EditableKey, ReadonlyArray<{ value: string; label: string }>>> = {
   attachmentStore: [
     { value: 'native', label: 'DSH 原生附件库（默认）' },
@@ -151,13 +223,6 @@ const SELECT_OPTIONS: Partial<Record<EditableKey, ReadonlyArray<{ value: string;
     { value: 'degrade', label: '话题被拒时降级为会话级' },
     { value: 'strict', label: '话题被拒时直接失败' },
   ],
-  workspaceRetention: [
-    { value: 'off', label: '关闭（不删除）' },
-    { value: '7d', label: '7 天' },
-    { value: '30d', label: '30 天' },
-    { value: '90d', label: '90 天' },
-    { value: '180d', label: '180 天' },
-  ],
   loggerLevel: [
     { value: 'debug', label: 'debug' },
     { value: 'info', label: 'info' },
@@ -174,7 +239,7 @@ const SELECT_OPTIONS: Partial<Record<EditableKey, ReadonlyArray<{ value: string;
 const FIELD_META: Record<EditableKey, { label: string; help: string; min?: number; max?: number; step?: number; placeholder?: string; wide?: boolean }> = {
   baseDir: {
     label: '工作区根目录（文件落点）',
-    help: '每个用户/群成员一个工作区：私聊 <baseDir>/p2p/<open_id>/，群聊 <baseDir>/groups/<chat_id>/<open_id>/；每个话题在其中拥有独立工作目录 <工作区>/topics/<话题>/（Git 仓库工作区可自动改用 worktree）。必须是绝对路径（~ 开头按家目录展开），保存时会创建该目录；只影响之后新建立的会话 —— 已有话题即使 /renew 也沿用原目录，旧文件不会迁移。',
+    help: '每个用户/群成员一个工作区：私聊 <baseDir>/p2p/<user_id>/，群聊 <baseDir>/groups/<chat_id>/<user_id>/；每个话题在其中拥有独立工作目录 <工作区>/topics/<话题>/（Git 仓库工作区可自动改用 worktree）。必须是绝对路径（~ 开头按家目录展开），保存时会创建该目录；只影响之后新建立的会话 —— 已有话题即使 /renew 也沿用原目录，旧文件不会迁移。',
     placeholder: '/Users/you/.dsh/dsh-channels/workspaces',
     wide: true,
   },
@@ -182,11 +247,12 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
   requireMention: { label: '普通群需 @ 机器人', help: '已绑定的主题内始终不需要 @；关闭后普通群的每条消息都会触发。' },
   threadFallback: { label: '话题被拒时的兜底', help: 'degrade 降级为会话级路由；strict 直接让回复失败。' },
   welcomeOnboarding: { label: '首次私聊引导卡', help: '每个私聊会话第一次触达时发送一张命令与用法引导卡，只发一次。' },
+  slashCommandPanel: { label: '同步飞书原生斜杠指令面板', help: '连接时把插件命令同步到飞书输入 / 时弹出的面板；需开通 application:app_slash_command:read 与 write 权限，部分企业不允许应用添加斜杠指令。关闭时不读写面板，直接输入命令不受影响。' },
   allowPermissionSwitch: { label: '允许飞书侧切换权限预设', help: '安全敏感：开启后话题所有者可用 /permissions 切换沙箱与审批预设。' },
-  adminOpenId: {
-    label: '管理员 open_id',
-    help: '唯一管理员。私聊机器人发送 /userid 获取（ou_ 开头，不是 user_id/邮箱）；留空 = 清除 Web 覆盖。guarded 模式下未配置会拒绝所有对话。',
-    placeholder: 'ou_xxx',
+  adminUserId: {
+    label: '管理员 user_id',
+    help: '唯一管理员。私聊机器人发送 /userid 获取（不是 ou_ 开头的 open_id，也不是邮箱）；留空 = 清除 Web 覆盖。未配置时自动使用飞书应用所有者（需可选的「获取应用信息」权限，开不了就在这里手动填写）；两者都没有时 guarded 模式会拒绝所有对话。',
+    placeholder: 'user_id',
   },
   accessMode: {
     label: '准入模式',
@@ -201,7 +267,7 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
   },
   acceptAttachments: {
     label: '接收入站附件',
-    help: '接收飞书图片、文件与合并转发记录。native（默认）下入站附件存入 DSH 原生附件库：触发消息的图片预取进首轮、文件保持懒取，纯附件消息静默登记元数据；archive 下按旧版行为下载到工作区 attachments/。关闭后附件消息不保存、不触发模型、也不登记。',
+    help: '接收飞书图片、文件与合并转发记录。native（默认）下入站附件存入 DSH 原生附件库：触发消息的图片预取进首轮、文件保持懒取，纯附件消息不回复、不落地，需要时请引用该消息（多个文件可合并转发后引用）再提问；archive 下按旧版行为下载到工作区 attachments/。关闭后附件消息不保存、不触发模型、也不列入清单。',
   },
   attachmentStore: {
     label: '入站附件存储后端',
@@ -239,19 +305,6 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
     max: 20,
     step: 1,
   },
-  pendingAttachmentTtlMs: {
-    label: '静默附件登记有效期（ms）',
-    help: '纯附件/未触发消息只登记元数据（不下载）。超过该时长的登记由周期 GC 清除；0 = 不按时间清理（每个 scope 仍有容量上限）。默认 604800000 = 7 天。',
-    min: 0,
-    step: 1,
-  },
-  pendingAttachmentLimit: {
-    label: '静默附件登记容量（每个 scope）',
-    help: '每个 (会话, 话题, 发送者) scope 最多保留的登记条数（1–100）；超出时淘汰该 scope 最旧的一条。',
-    min: 1,
-    max: 100,
-    step: 1,
-  },
   promptContextTimeoutMs: {
     label: '被动读取预算（ms）',
     help: '引用摘录与首轮话题历史这类被动 prompt 增强的整段预算（默认 3000 ms，100–10000）；超时即省略对应块、回合照跑。模型主动调用工具的读取超时另由 feishu_tools 超时控制。',
@@ -295,8 +348,24 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
     max: 120_000,
     step: 1_000,
   },
-  workspaceRetention: { label: '过期目录保留期', help: '只清理工作区与 Agent 产物目录，不影响 Session 附件：默认 native 存储下附件在 DSH 原生附件库，不参与目录清理；仅当显式使用 archive 后端时，附件副本位于话题目录、会随目录清理。用户工作区本身永不删除，DSH 会话日志不受影响。' },
-  workspaceRetentionAuto: { label: '自动执行目录清理', help: '开启后插件在启动时及每天执行一次过期目录清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置；清理只清理工作区与 Agent 产物目录，不影响 Session 附件。' },
+  'feishuTools.sendFile': {
+    label: '启用 feishu_send_file 工具',
+    help: '让模型把当前话题工作目录里生成的图片/文件发回当前会话（图片 ≤10 MB，文件 ≤30 MB）。需开通 im:resource 权限。对新会话生效。',
+  },
+  'feishuTools.wikiRead': {
+    label: '启用知识库读取工具',
+    help: '让模型浏览「知识库范围」内的知识库节点并读取 docx 文档（feishu_wiki_list / feishu_wiki_read），以应用身份访问。需开通 wiki:wiki（或 wiki:wiki:readonly）与 docx:document（或 docx:document:readonly）权限。只有话题所有者是管理员或在知识库白名单（/auth wiki add @成员）中才能使用；打开文档前会在授权卡上征得话题所有者同意，每个话题一次。知识库范围为空时不挂载。对新会话生效。',
+  },
+  'feishuTools.wikiWrite': {
+    label: '启用知识库写入工具',
+    help: '让模型在「知识库范围」内新建 docx 文档，并编辑本应用拥有的文档（feishu_wiki_create / feishu_wiki_edit），以应用身份访问；每次新建或编辑都需话题所有者在审批卡上同意。需开通 wiki:wiki 与 docx:document 权限；使用条件同读取工具（管理员或知识库白名单）。知识库范围为空时不挂载。对新会话生效。',
+  },
+  wikiRoots: {
+    label: '知识库范围（wikiRoots）',
+    help: '知识库工具只能访问这些位置，每个输入框填一个链接：整个知识空间 https://<租户>.feishu.cn/wiki/space/<space_id>，或节点 https://<租户>.feishu.cn/wiki/<node_token>（该节点及其下所有节点）；最多 20 项，空输入框保存时忽略。留空 = 不挂载任何知识库工具（即使上面的开关已开启）。对新会话生效。',
+    placeholder: 'https://<租户>.feishu.cn/wiki/space/<space_id>',
+    wide: true,
+  },
   provider: { label: '模型服务商', help: '留空 = 使用部署默认；例如 deepseek-official。', placeholder: '留空 = 部署默认' },
   model: { label: '模型 id', help: '留空 = 使用部署默认；例如 deepseek-v4-flash。', placeholder: '留空 = 部署默认' },
   reasoningEffort: { label: '推理档位', help: '模型声明的精确档位 id（如 high / max）；留空 = 适配器默认。', placeholder: '留空 = 适配器默认' },
@@ -308,14 +377,13 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
 
 const GROUP_OF: Record<EditableKey, EditableFieldWire['group']> = {
   baseDir: 'workspace',
-  workspaceRetention: 'workspace',
-  workspaceRetentionAuto: 'workspace',
   dmMode: 'behavior',
   requireMention: 'behavior',
   threadFallback: 'behavior',
   welcomeOnboarding: 'behavior',
+  slashCommandPanel: 'behavior',
   allowPermissionSwitch: 'behavior',
-  adminOpenId: 'access',
+  adminUserId: 'access',
   accessMode: 'access',
   authRequestTtlDays: 'access',
   acceptAttachments: 'content',
@@ -325,8 +393,6 @@ const GROUP_OF: Record<EditableKey, EditableFieldWire['group']> = {
   prefetchImageMaxBytes: 'content',
   prefetchTotalMaxBytes: 'content',
   historyBootstrapLimit: 'content',
-  pendingAttachmentTtlMs: 'content',
-  pendingAttachmentLimit: 'content',
   promptContextTimeoutMs: 'tools',
   'feishuTools.attachmentFetch': 'tools',
   'feishuTools.attachmentFetchMaxResources': 'tools',
@@ -334,6 +400,10 @@ const GROUP_OF: Record<EditableKey, EditableFieldWire['group']> = {
   'feishuTools.attachmentFetchTimeoutMs': 'tools',
   'feishuTools.topicMessages': 'tools',
   'feishuTools.topicMessagesTimeoutMs': 'tools',
+  'feishuTools.sendFile': 'tools',
+  'feishuTools.wikiRead': 'tools',
+  'feishuTools.wikiWrite': 'tools',
+  wikiRoots: 'tools',
   provider: 'model',
   model: 'model',
   reasoningEffort: 'model',
@@ -347,10 +417,13 @@ const GROUP_OF: Record<EditableKey, EditableFieldWire['group']> = {
 export const FIELD_DESCRIPTORS: readonly EditableFieldWire[] = EDITABLE_KEYS.map(key => {
   const meta = FIELD_META[key]
   const options = SELECT_OPTIONS[key]
+  const list = STRING_LIST_FIELDS[key]
   return {
     key,
     label: meta.label,
-    kind: BOOLEAN_KEYS.has(key) ? 'boolean' : options !== undefined ? 'select' : meta.min !== undefined ? 'number' : 'text',
+    kind: list !== undefined
+      ? 'string-list'
+      : BOOLEAN_KEYS.has(key) ? 'boolean' : options !== undefined ? 'select' : meta.min !== undefined ? 'number' : 'text',
     group: GROUP_OF[key],
     help: meta.help,
     ...(options === undefined ? {} : { options }),
@@ -358,6 +431,8 @@ export const FIELD_DESCRIPTORS: readonly EditableFieldWire[] = EDITABLE_KEYS.map
     ...(meta.max === undefined ? {} : { max: meta.max }),
     ...(meta.step === undefined ? {} : { step: meta.step }),
     ...(meta.placeholder === undefined ? {} : { placeholder: meta.placeholder }),
+    ...(list === undefined ? {} : { maxItems: list.maxItems }),
+    ...(list?.itemFormat === undefined ? {} : { itemFormat: list.itemFormat }),
     ...(meta.wide === undefined ? {} : { wide: meta.wide }),
     restartRequired: RESTART_SET.has(key),
   }
@@ -485,8 +560,6 @@ export function normalizeCredentialValue(raw: unknown): { ok: true; value: strin
 /** Longest accepted whitelist identifier / display name. */
 const MAX_ACCESS_VALUE_LENGTH = 128
 
-/** Feishu user open_ids (`ou_` + URL-safe id). Identity is open_id only. */
-const OPEN_ID_PATTERN = /^ou_[A-Za-z0-9_-]+$/
 
 /** Trim one whitelist identifier, rejecting empty, oversized, or hostile input. */
 export function normalizeAccessId(
@@ -502,7 +575,7 @@ export function normalizeAccessId(
   }
   // eslint-disable-next-line no-control-regex
   if (/[\u0000-\u001f\u007f]/.test(value)) return { ok: false, message: `${label}包含非法控制字符` }
-  if (invalidFormat !== undefined && !OPEN_ID_PATTERN.test(value)) {
+  if (invalidFormat !== undefined && !FEISHU_USER_ID_PATTERN.test(value)) {
     return { ok: false, message: invalidFormat }
   }
   return { ok: true, value }
@@ -565,6 +638,8 @@ function phaseOf(target: SettingsTarget): ChannelPhaseWire {
 function buildStatus(target: SettingsTarget, overlayPath: string): ChannelStatusWire {
   const health = target.health()
   const connection = health.connection
+  const scopeCheck = target.isRunning() ? target.scopeCheck() : undefined
+  const slashCommandSync = target.isRunning() ? target.slashCommandSync() : undefined
   return {
     running: target.isRunning(),
     configured: target.isConfigured(),
@@ -590,6 +665,8 @@ function buildStatus(target: SettingsTarget, overlayPath: string): ChannelStatus
     version: DSH_CHANNELS_VERSION,
     overlayPath,
     busy: target.isRestarting() || target.isConnecting(),
+    ...(scopeCheck === undefined ? {} : { scopeCheck }),
+    ...(slashCommandSync === undefined ? {} : { slashCommandSync }),
   }
 }
 
@@ -697,23 +774,6 @@ export class SettingsSurface {
       appSecret: toWire(effective.appSecret, credentialStates.appSecret),
     }
 
-    // The cleanup preview is derived from live workspace/route state; a broken
-    // seam must not break the whole panel, so it degrades to zero counts + error.
-    let cleanup: CleanupPreviewWire
-    try {
-      cleanup = await this.target.cleanupPreview()
-    } catch (error) {
-      this.logger?.warn?.('dsh-channels: 目录清理预览失败：%s', messageOf(error))
-      cleanup = {
-        retention: effective.workspaceRetention,
-        auto: effective.workspaceRetentionAuto,
-        workspaces: 0,
-        candidates: 0,
-        candidateBytes: 0,
-        error: messageOf(error),
-      }
-    }
-
     // The access snapshot comes from in-memory maps, but a broken seam must
     // still not take the whole panel down: degrade to an empty, fail-closed
     // view (the whitelist mutations will report their own errors).
@@ -744,7 +804,6 @@ export class SettingsSurface {
         readOnly: readOnlyFields(effective),
         credentials,
       },
-      cleanup,
       access,
     }
   }
@@ -760,6 +819,7 @@ export class SettingsSurface {
 
     const raw: Record<string, unknown> = {}
     const clearedKeys: EditableKey[] = []
+    const listIssues: FieldIssueWire[] = []
     for (const key of EDITABLE_KEYS) {
       const value = values[key]
       if (value === undefined) continue
@@ -767,15 +827,22 @@ export class SettingsSurface {
         clearedKeys.push(key)
         continue
       }
+      const list = STRING_LIST_FIELDS[key]
+      if (list !== undefined) {
+        const normalized = normalizeStringList(key, value, list)
+        if (normalized.ok) setOverlayValue(raw, key, normalized.value)
+        else listIssues.push(...normalized.issues)
+        continue
+      }
       setOverlayValue(raw, key, value)
     }
 
     const parsed = parseOverlay(raw)
-    if (!parsed.ok) {
-      const issues: FieldIssueWire[] = parsed.issues.map(issue => ({
-        key: issue.path,
-        message: issue.message,
-      }))
+    if (!parsed.ok || listIssues.length > 0) {
+      const issues: FieldIssueWire[] = [
+        ...listIssues,
+        ...(parsed.ok ? [] : parsed.issues.map(issue => ({ key: issue.path, message: issue.message }))),
+      ]
       return { ok: false, error: '配置校验失败', issues }
     }
 
@@ -971,9 +1038,9 @@ export class SettingsSurface {
     return this.mutateAccess(() => this.target.removeAccessGroup(id.value))
   }
 
-  /** Authorize one user `open_id`; `ou_` prefix is required (not user_id/email). */
-  async saveAccessUser(openId: unknown, name?: unknown): Promise<AccessMutationResponse> {
-    const id = normalizeAccessId(openId, '用户 open_id', '用户 open_id 必须形如 ou_xxx（不是 user_id/邮箱）')
+  /** Authorize one user `user_id` (not an open_id or email). */
+  async saveAccessUser(userId: unknown, name?: unknown): Promise<AccessMutationResponse> {
+    const id = normalizeAccessId(userId, '用户 user_id', '用户 user_id 只能包含字母、数字、_ 和 -（不是 ou_ 开头的 open_id，也不是邮箱）')
     if (!id.ok) return { ok: false, error: id.message }
     const label = normalizeAccessName(name)
     if (!label.ok) return { ok: false, error: label.message }
@@ -981,8 +1048,8 @@ export class SettingsSurface {
   }
 
   /** Revoke one user authorization (immediate: the next message re-evaluates). */
-  async removeAccessUser(openId: unknown): Promise<AccessMutationResponse> {
-    const id = normalizeAccessId(openId, '用户 open_id', '用户 open_id 必须形如 ou_xxx（不是 user_id/邮箱）')
+  async removeAccessUser(userId: unknown): Promise<AccessMutationResponse> {
+    const id = normalizeAccessId(userId, '用户 user_id', '用户 user_id 只能包含字母、数字、_ 和 -（不是 ou_ 开头的 open_id，也不是邮箱）')
     if (!id.ok) return { ok: false, error: id.message }
     return this.mutateAccess(() => this.target.removeAccessUser(id.value))
   }
@@ -1022,23 +1089,6 @@ export class SettingsSurface {
     if (this.directoryPicker === undefined) throw new Error(PANEL_COPY.directoryPickFailed)
     return await this.directoryPicker.pick(signal)
   }
-
-  /**
-   * Run the workspace-retention cleanup once. Irreversible deletions are the
-   * target's responsibility; the surface only reports the outcome and returns
-   * a refreshed panel (its cleanup preview then reflects the remaining workspaces).
-   */
-  async runCleanup(): Promise<CleanupResponse> {
-    const busy = this.writeBusy()
-    if (busy !== undefined) return busy
-    let result: CleanupRunWire
-    try {
-      result = await this.target.runWorkspaceCleanup()
-    } catch (error) {
-      return { ok: false, error: `清理失败：${messageOf(error)}` }
-    }
-    return { ok: true, result, panel: await this.panel() }
-  }
 }
 
 export { PANEL_COPY }

package/src/streamer.ts

@@ -24,8 +24,16 @@
  *     card. Reasoning is never segmented — it stays on card 1 inside the
  *     fold panel's own fixed window, independent of the body length.
  *  4. `finalize(turn)` — flip every segment card to its terminal state
- *     (`回复结束` / `回复失败`), render the settled footer on the main card and
- *     request the Typing → DONE/No reaction swap on the triggering message.
+ *     (`回复结束` / `已停止` / `回复失败`), render the settled footer on the main
+ *     card and request the Typing → DONE/No reaction swap on the triggering
+ *     message.
+ *
+ * Stop button: the card that is currently streaming in the session's active
+ * (front) turn carries a stop button until the turn settles; queued turns
+ * gain it when they become the front. `stopTargetOf()` resolves a clicked card to its
+ * session; `markStopping()` / `markStopDenied()` record the click's outcome
+ * on the card. Ownership checks and the cancellation itself belong to the
+ * caller.
  *
  * The first visible text delta flips the panel title 推理中 → 回复中; the
  * final patch flips it to 回复结束 or 回复失败. Patching is throttled to `refreshMs` and
@@ -42,7 +50,7 @@
 
 import type { AssistantStreamFrame, Session, SessionEvent, TurnEndReason } from './dsh-types.ts'
 import { buildCard, segmentCardContent, segmentCardOptions } from './cards.ts'
-import type { CardState, PanelPhase } from './cards.ts'
+import type { CardState, PanelPhase, StopControl } from './cards.ts'
 import type { FeishuChannel } from './feishu-channel.ts'
 import { cacheHitPct, foldAll, foldEvent } from './stats.ts'
 import type { HeaderSample, StatsFold, UsageSample } from './stats.ts'
@@ -170,6 +178,8 @@ interface TurnState {
   reasoningMs: number
   /** The in-flight tool call, if any (cleared by its `tool/result`). */
   toolActivity: { name: string; label: string; since: number } | undefined
+  /** Tool names whose approval card is still undecided (shown over the tool line). */
+  awaitingApproval: readonly string[]
   /** Live workflow-run folds projected by the workflow tool into this session. */
   workflowRuns: Map<string, WorkflowRun>
   /** The last settled workflow run (kept visible until the next activity). */
@@ -202,6 +212,10 @@ interface TurnState {
    * durable model history, so the card must drop them again.
    */
   attempts: Map<string, AttemptMark>
+  /** The owner clicked stop; the button renders disabled until the turn settles. */
+  stopRequested: boolean
+  /** A non-owner clicked stop; the owner-only notice renders under the button. */
+  stopDenied: boolean
 }
 
 /** Card/body lengths captured at one stream attempt's `start` frame. */
@@ -350,6 +364,7 @@ export class TurnStreamer {
       reasoningSince: undefined,
       reasoningMs: 0,
       toolActivity: undefined,
+      awaitingApproval: [],
       workflowRuns: new Map(),
       workflowEndStatus: undefined,
       children: new Map(),
@@ -360,10 +375,15 @@ export class TurnStreamer {
       toolKind: '',
       heartbeatTimer: undefined,
       attempts: new Map(),
+      stopRequested: false,
+      stopDenied: false,
     })
     this.bySession.set(session.id, queue)
     const state = queue[queue.length - 1]!
     this.scheduleHeartbeat(session.id, state)
+    // The first frame is sent without a stop button; the front turn gains it
+    // on its first patch.
+    if (this.front(session.id) === state) this.markDirty(session.id, state)
   }
 
   /** Drop all state for a session (agent disposed / route removed). */
@@ -381,10 +401,61 @@ export class TurnStreamer {
     this.segmentChains.delete(sessionId)
   }
 
+  /** Drop every session's state and timers (service shutdown). */
+  detachAll(): void {
+    for (const sessionId of [...this.bySession.keys()]) this.detach(sessionId)
+  }
+
   hasSession(sessionId: string): boolean {
     return this.bySession.has(sessionId)
   }
 
+  /**
+   * The session whose active (front) turn streams into `messageId`, or
+   * undefined when the card belongs to no such turn (queued, settled,
+   * detached, or unknown). Only the front turn is the one `cancel` stops.
+   * @param messageId Feishu message id of a clicked card.
+   * @returns The owning session id.
+   */
+  stopTargetOf(messageId: string): string | undefined {
+    for (const sessionId of this.bySession.keys()) {
+      if (this.front(sessionId)?.cards.some(card => card.messageId === messageId) === true) return sessionId
+    }
+    return undefined
+  }
+
+  /**
+   * Show (or clear) the approval wait on the session's live turn: the tool
+   * line reads `⏳ 等待你审批：bash` while any approval card is undecided.
+   * @param sessionId - the session waiting on approval.
+   * @param toolNames - the tools still waiting; empty clears the line.
+   */
+  setAwaitingApproval(sessionId: string, toolNames: readonly string[]): void {
+    const state = this.front(sessionId)
+    if (state === undefined) return
+    if (state.awaitingApproval.join('\u0000') === toolNames.join('\u0000')) return
+    state.awaitingApproval = [...toolNames]
+    this.markDirty(sessionId, state)
+  }
+
+  /** Render the stop button disabled on the session's live turn. */
+  markStopping(sessionId: string): void {
+    this.markStop(sessionId, state => { state.stopRequested = true })
+  }
+
+  /** Add the owner-only notice under the session's stop button (once). */
+  markStopDenied(sessionId: string): void {
+    this.markStop(sessionId, state => { state.stopDenied = true })
+  }
+
+  private markStop(sessionId: string, apply: (state: TurnState) => void): void {
+    const state = this.front(sessionId)
+    if (state === undefined) return
+    const before = `${state.stopRequested}/${state.stopDenied}`
+    apply(state)
+    if (`${state.stopRequested}/${state.stopDenied}` !== before) this.markDirty(sessionId, state)
+  }
+
   /** The front (oldest unfinished) turn state of a session. */
   private front(sessionId: string): TurnState | undefined {
     const queue = this.bySession.get(sessionId)
@@ -518,7 +589,7 @@ export class TurnStreamer {
         // The ended turn belongs to the front state: assign it if a turn was
         // rejected/emptied before any step started.
         if (state.turn === undefined) state.turn = event.data.turn
-        this.finalize(session.id, state, turnFailure(event.data.reason))
+        this.finalize(session.id, state, turnFailure(event.data.reason), turnAborted(event.data.reason))
         break
       }
       default:
@@ -834,6 +905,9 @@ export class TurnStreamer {
    */
   private toolLine(state: TurnState, now: number): string {
     if (state.finalized) return ''
+    if (state.awaitingApproval.length > 0) {
+      return clipActivity(`⏳ 等待你审批：${[...new Set(state.awaitingApproval)].join('、')}`)
+    }
     const tool = state.toolActivity
     if (tool === undefined) return ''
     const prefix = tool.name === 'subagent'
@@ -884,12 +958,16 @@ export class TurnStreamer {
       const kind = this.noteKind('tool', tool, state.toolKind)
       if (kind !== undefined) state.toolKind = kind
     }
+    const stop: StopControl | undefined = !active || state.finalized || this.front(sessionId) !== state
+      ? undefined
+      : state.stopRequested ? 'stopping' : 'ready'
     return {
       phase: state.phase,
       reasoning: state.reasoning,
       body,
       status: active ? state.status : '',
       tool: active ? state.tool : '',
+      ...(stop === undefined ? {} : { stop, stopDenied: state.stopDenied }),
       stats: this.statsFor(sessionId, state),
     }
   }
@@ -1062,10 +1140,13 @@ export class TurnStreamer {
     sessionId: string,
     state: TurnState,
     failure: { message: string; code?: string } | undefined,
+    aborted = false,
   ): void {
     if (state.finalized) return
     state.finalized = true
-    state.phase = failure === undefined ? 'done' : 'error'
+    // Only a stop this channel requested reads as 已停止; other cancellation
+    // causes (parent, hook, disposal) settle like a normal end.
+    state.phase = failure !== undefined ? 'error' : aborted && state.stopRequested ? 'stopped' : 'done'
     // A turn that ends inside a reasoning phase (e.g. no answer text) still
     // reports the time it spent reasoning.
     this.closeReasoning(state)
@@ -1118,6 +1199,9 @@ export class TurnStreamer {
       if (queue === undefined) return
       const index = queue.indexOf(state)
       if (index >= 0) queue.splice(index, 1)
+      // The next queued turn becomes the active one and gains the stop button.
+      const next = this.front(sessionId)
+      if (next !== undefined) this.markDirty(sessionId, next)
     })
 
     this.hooks.onTurnFinalized(sessionId, state.turn ?? 0, state.cards[0]?.messageId ?? '')
@@ -1136,6 +1220,11 @@ export class TurnStreamer {
   }
 }
 
+/** Whether a turn ended through a cancellation request (`/stop`, the stop button). */
+function turnAborted(reason: TurnEndReason): boolean {
+  return typeof reason === 'object' && reason !== null && reason.kind === 'aborted'
+}
+
 /** Extract the user-visible failure from the current Harness turn-end union. */
 function turnFailure(reason: TurnEndReason): { message: string; code?: string } | undefined {
   if (typeof reason !== 'object' || reason === null || reason.kind !== 'error') return undefined