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

package/src/settings/surface.ts

@@ -12,6 +12,7 @@
 
 import { DSH_CHANNELS_VERSION } from '../session-export.ts'
 import type { FeishuConfig } from '../config.ts'
+import { FEISHU_USER_ID_PATTERN } from '../domain.ts'
 import type { HealthSnapshot } from '../health.ts'
 import { prepareWorkspaceBaseDir } from '../workspaces.ts'
 import {
@@ -25,9 +26,6 @@ import type {
   CatalogWire,
   ChannelPhaseWire,
   ChannelStatusWire,
-  CleanupPreviewWire,
-  CleanupResponse,
-  CleanupRunWire,
   ClearConfigResponse,
   ClearCredentialResponse,
   ConfigValue,
@@ -45,10 +43,19 @@ import type {
   SaveConfigResponse,
   SaveCredentialsRequest,
   SaveCredentialsResponse,
+  ScopeCheckWire,
+  SlashCommandSyncWire,
 } from './contract.ts'
 import {
+  configValueOf,
+  deleteOverlayKey,
+  mergeOverlay,
+  mergeOverlayPatch,
+  overlayValueOf,
+  overlayValues,
   parseOverlay,
   pickEditable,
+  setOverlayValue,
 } from './overlay.ts'
 import type { OverlayLogger, OverlayPatch, OverlayStore } from './overlay.ts'
 import type { SettingsCatalog } from './catalog.ts'
@@ -64,6 +71,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
@@ -79,25 +90,21 @@ export interface SettingsTarget {
   configSnapshot(): FeishuConfig
   baseConfigSnapshot(): FeishuConfig
   runningConfigSnapshot(): FeishuConfig | undefined
-  applyOverlay(overlay: Partial<FeishuConfig>): void
+  applyOverlay(overlay: OverlayPatch): void
   restart(): Promise<void>
   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>
 }
@@ -117,18 +124,26 @@ const OPTIONAL_TEXT_KEYS = new Set<EditableKey>([
   'model',
   'reasoningEffort',
   'agentPreset',
-  'adminOpenId',
+  'adminUserId',
 ])
 
 const BOOLEAN_KEYS = new Set<EditableKey>([
   'requireMention',
   'welcomeOnboarding',
+  'slashCommandPanel',
   'allowPermissionSwitch',
   'acceptAttachments',
-  'workspaceRetentionAuto',
+  'prefetchImages',
+  'feishuTools.attachmentFetch',
+  'feishuTools.topicMessages',
+  'feishuTools.sendFile',
 ])
 
 const SELECT_OPTIONS: Partial<Record<EditableKey, ReadonlyArray<{ value: string; label: string }>>> = {
+  attachmentStore: [
+    { value: 'native', label: 'DSH 原生附件库（默认）' },
+    { value: 'archive', label: '工作区 attachments/（旧版）' },
+  ],
   dmMode: [
     { value: 'open', label: '开放私聊' },
     { value: 'disabled', label: '禁用私聊' },
@@ -137,13 +152,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' },
@@ -160,7 +168,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,
   },
@@ -168,11 +176,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: '准入模式',
@@ -185,9 +194,93 @@ const FIELD_META: Record<EditableKey, { label: string; help: string; min?: numbe
     max: 30,
     step: 1,
   },
-  acceptAttachments: { label: '接收并保存附件', help: '接收飞书图片、文件与合并转发记录，保存到工作区的 attachments/ 目录；模型不会自动读取，需要时用文件工具自行查看。关闭后附件消息不保存、不触发回复。' },
-  workspaceRetention: { label: '过期目录保留期', help: '超过所选天数没有活动的飞书话题目录（以及旧版本按话题建立的工作区目录）会进入下方清理列表；用户工作区本身永不删除。DSH 会话日志不受影响。' },
-  workspaceRetentionAuto: { label: '自动执行目录清理', help: '开启后插件在启动时及每天执行一次过期目录清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置。' },
+  acceptAttachments: {
+    label: '接收入站附件',
+    help: '接收飞书图片、文件与合并转发记录。native（默认）下入站附件存入 DSH 原生附件库：触发消息的图片预取进首轮、文件保持懒取，纯附件消息不回复、不落地，需要时请引用该消息（多个文件可合并转发后引用）再提问；archive 下按旧版行为下载到工作区 attachments/。关闭后附件消息不保存、不触发模型、也不列入清单。',
+  },
+  attachmentStore: {
+    label: '入站附件存储后端',
+    help: 'native（默认）：图片与文件存入 DSH 原生附件库（不可变、内容寻址去重、读取校验、随 Session 回放；不自动清理）。archive：旧版下载到话题工作区 attachments/（可清理但会阻塞会话）。宿主未挂载附件服务时 native 自动降级 archive。',
+  },
+  prefetchImages: {
+    label: '预取触发消息的图片',
+    help: 'native 下把触发消息的图片预取为首轮 ImageBlock，会话/话题/卡片不等下载；失败、超限或超时的图片降级为清单中的懒取项。关闭后图片也需用 feishu_attachment_fetch 获取。',
+  },
+  prefetchTimeoutMs: {
+    label: '图片预取整段超时（ms）',
+    help: '一次触发消息图片预取的总超时（默认 10000 ms，100–120000）；到期后已取回的图片保留，其余降级为清单，不阻塞回合。',
+    min: 100,
+    max: 120_000,
+    step: 100,
+  },
+  prefetchImageMaxBytes: {
+    label: '单张预取图片上限（字节）',
+    help: '单张图片超过该字节数即不入首轮图片、留在清单懒取（默认 20971520 = 20 MiB）。',
+    min: 1,
+    max: 200 * 1024 * 1024,
+    step: 1,
+  },
+  prefetchTotalMaxBytes: {
+    label: '单次预取总量上限（字节）',
+    help: '一次触发消息图片预取的总字节预算（默认 52428800 = 50 MiB）；用尽后剩余图片降级为清单懒取。',
+    min: 1,
+    max: 1024 * 1024 * 1024,
+    step: 1,
+  },
+  historyBootstrapLimit: {
+    label: '首轮话题历史条数',
+    help: '新 Session 首轮自动附带本话题最近 N 条消息摘要（0 = 关闭，上限 20）；被动读取使用短预算，缺权限/失败时静默省略。更早的消息用 feishu_topic_messages 工具翻页。',
+    min: 0,
+    max: 20,
+    step: 1,
+  },
+  promptContextTimeoutMs: {
+    label: '被动读取预算（ms）',
+    help: '引用摘录与首轮话题历史这类被动 prompt 增强的整段预算（默认 3000 ms，100–10000）；超时即省略对应块、回合照跑。模型主动调用工具的读取超时另由 feishu_tools 超时控制。',
+    min: 100,
+    max: 10_000,
+    step: 100,
+  },
+  'feishuTools.attachmentFetch': {
+    label: '启用 feishu_attachment_fetch 工具',
+    help: '让模型按 message_id/file_key 懒取已授权消息的图片/文件。关闭后文件无法懒取，插件整体回退 archive 后端（入站文件直接下载到工作区）。对新会话生效。',
+  },
+  'feishuTools.attachmentFetchMaxResources': {
+    label: '单次取回资源数上限',
+    help: '一次工具调用最多取回的附件数量（默认 10，1–50）；超出会返回可读原因，模型可按 file_key 拆分重试。',
+    min: 1,
+    max: 50,
+    step: 1,
+  },
+  'feishuTools.attachmentFetchMaxBytes': {
+    label: '单次取回字节预算（字节）',
+    help: '一次工具调用的总下载字节预算（默认 104857600 = 100 MiB）；文件流式写入原生库，不整文件缓冲。',
+    min: 1,
+    max: 1024 * 1024 * 1024,
+    step: 1,
+  },
+  'feishuTools.attachmentFetchTimeoutMs': {
+    label: '单次取回超时（ms）',
+    help: '一次 feishu_attachment_fetch 的整段超时（默认 120000 ms，1000–600000）；到期取消下载并逐项报告可读原因。',
+    min: 1_000,
+    max: 600_000,
+    step: 1_000,
+  },
+  'feishuTools.topicMessages': {
+    label: '启用 feishu_topic_messages 工具',
+    help: '让模型按需读取引用消息与话题内更早的消息/附件。关闭只影响模型工具；被动的引用摘录与首轮历史仍由 historyBootstrapLimit 控制。',
+  },
+  'feishuTools.topicMessagesTimeoutMs': {
+    label: '单次话题读取超时（ms）',
+    help: '一次 feishu_topic_messages 的整段超时（默认 20000 ms，1000–120000）；被动摘录使用独立的短预算。',
+    min: 1_000,
+    max: 120_000,
+    step: 1_000,
+  },
+  'feishuTools.sendFile': {
+    label: '启用 feishu_send_file 工具',
+    help: '让模型把当前话题工作目录里生成的图片/文件发回当前会话（图片 ≤10 MB，文件 ≤30 MB）。需开通 im:resource 权限。对新会话生效。',
+  },
   provider: { label: '模型服务商', help: '留空 = 使用部署默认；例如 deepseek-official。', placeholder: '留空 = 部署默认' },
   model: { label: '模型 id', help: '留空 = 使用部署默认；例如 deepseek-v4-flash。', placeholder: '留空 = 部署默认' },
   reasoningEffort: { label: '推理档位', help: '模型声明的精确档位 id（如 high / max）；留空 = 适配器默认。', placeholder: '留空 = 适配器默认' },
@@ -199,17 +292,30 @@ 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',
+  attachmentStore: 'content',
+  prefetchImages: 'content',
+  prefetchTimeoutMs: 'content',
+  prefetchImageMaxBytes: 'content',
+  prefetchTotalMaxBytes: 'content',
+  historyBootstrapLimit: 'content',
+  promptContextTimeoutMs: 'tools',
+  'feishuTools.attachmentFetch': 'tools',
+  'feishuTools.attachmentFetchMaxResources': 'tools',
+  'feishuTools.attachmentFetchMaxBytes': 'tools',
+  'feishuTools.attachmentFetchTimeoutMs': 'tools',
+  'feishuTools.topicMessages': 'tools',
+  'feishuTools.topicMessagesTimeoutMs': 'tools',
+  'feishuTools.sendFile': 'tools',
   provider: 'model',
   model: 'model',
   reasoningEffort: 'model',
@@ -361,8 +467,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(
@@ -378,7 +482,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 }
@@ -441,6 +545,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(),
@@ -466,6 +572,8 @@ function buildStatus(target: SettingsTarget, overlayPath: string): ChannelStatus
     version: DSH_CHANNELS_VERSION,
     overlayPath,
     busy: target.isRestarting() || target.isConnecting(),
+    ...(scopeCheck === undefined ? {} : { scopeCheck }),
+    ...(slashCommandSync === undefined ? {} : { slashCommandSync }),
   }
 }
 
@@ -536,9 +644,11 @@ export class SettingsSurface {
     const effective = this.target.configSnapshot()
     const overlay = await this.store.load()
     const running = this.target.runningConfigSnapshot()
-    const overriddenKeys = EDITABLE_KEYS.filter(key => overlay[key] !== undefined)
+    const overriddenKeys = EDITABLE_KEYS.filter(
+      key => overlayValueOf(overlay as Record<string, unknown>, key) !== undefined,
+    )
     const restartPendingKeys = this.target.isRunning() && running !== undefined
-      ? RESTART_KEYS.filter(key => effective[key] !== running[key])
+      ? RESTART_KEYS.filter(key => configValueOf(effective, key) !== configValueOf(running, key))
       : []
     const catalog = await this.catalogFor(effective.provider, effective.model)
     const fields = withDirectoryBrowse(
@@ -571,23 +681,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).
@@ -611,14 +704,13 @@ export class SettingsSurface {
       config: {
         base: pickEditable(base) as Record<string, ConfigValue | undefined>,
         effective: pickEditable(effective) as Record<string, ConfigValue | undefined>,
-        overlay: overlay as EditableValues,
+        overlay: overlayValues(overlay),
         overriddenKeys,
         restartPendingKeys,
         fields,
         readOnly: readOnlyFields(effective),
         credentials,
       },
-      cleanup,
       access,
     }
   }
@@ -641,7 +733,7 @@ export class SettingsSurface {
         clearedKeys.push(key)
         continue
       }
-      raw[key] = value
+      setOverlayValue(raw, key, value)
     }
 
     const parsed = parseOverlay(raw)
@@ -670,9 +762,8 @@ export class SettingsSurface {
 
     let merged: OverlayPatch
     try {
-      merged = { ...await this.store.load() }
-      for (const key of clearedKeys) delete merged[key]
-      Object.assign(merged, parsed.patch)
+      merged = mergeOverlayPatch(await this.store.load(), parsed.patch)
+      for (const key of clearedKeys) deleteOverlayKey(merged, key)
     } catch (error) {
       return { ok: false, error: `写入覆盖配置失败：${messageOf(error)}` }
     }
@@ -681,7 +772,7 @@ export class SettingsSurface {
     // provider (or lone model) leaves the session without a complete route,
     // so an edit to either side must end with both set or both cleared.
     if (values.provider !== undefined || values.model !== undefined) {
-      const prospective = { ...this.target.baseConfigSnapshot(), ...merged }
+      const prospective = mergeOverlay(this.target.baseConfigSnapshot(), merged)
       const hasProvider = (prospective.provider ?? '') !== ''
       const hasModel = (prospective.model ?? '') !== ''
       if (hasProvider !== hasModel) {
@@ -846,9 +937,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 }
@@ -856,8 +947,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))
   }
@@ -897,23 +988,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