@modesto_ma/dsh-channels 0.3.0 → 0.4.0

package/src/session/manager.ts

@@ -29,6 +29,7 @@ import { appendSessionHistory, sessionDirOf } from '../domain.ts'
 import type { RouteRecord } from '../domain.ts'
 import { mountChannelGuidance } from '../feishu/agent-context.ts'
 import { attachmentsDir } from '../feishu/inbound-attachments.ts'
+import { effectiveAttachmentMode, resolveAttachmentService } from '../feishu/native-attachments.ts'
 import { installRequestPolicy } from './request-policy.ts'
 import type { RequestPolicyController } from './request-policy.ts'
 import { placementServices, restoreTopicDir } from './isolation.ts'
@@ -65,6 +66,14 @@ export interface SessionManagerDeps {
   started(): boolean
   /** Drop streamer state for a session whose owner handle is being released. */
   detachStream(sessionId: string): void
+  /**
+   * Register this channel's model tools inside one Agent scope. Called from
+   * the agent-preset `setup` after the preset is mounted (tools live inside
+   * presets in web-profile deployments), and once more for a BORROWED live
+   * agent as a best-effort race guard (D7). Optional: unit tests that do not
+   * compose model tools omit it.
+   */
+  mountTools?(agentCtx: AgentContext, sessionId: string): Promise<void> | void
   warn(message: string, ...args: unknown[]): void
 }
 
@@ -82,6 +91,8 @@ export class SessionManager {
   private readonly live = new Map<string, LiveAgent>()
   private readonly pendingResume = new Map<string, Promise<LiveAgent>>()
   private readonly policies = new WeakMap<AgentContext, RequestPolicyController>()
+  /** Agent scopes this plugin already attempted to mount model tools into. */
+  private readonly toolMounts = new WeakSet<AgentContext>()
 
   constructor(private readonly deps: SessionManagerDeps) {}
 
@@ -116,7 +127,7 @@ export class SessionManager {
     cwd: string,
     agentOptions: Record<string, unknown> = this.agentOptions(),
   ): Promise<AgentHandle> {
-    const composition = await this.presetComposition(undefined, true)
+    const composition = await this.presetComposition(undefined, true, sessionId)
     const handle = await this.deps.ctx.agents.create({
       sessionId,
       meta: {
@@ -132,15 +143,31 @@ export class SessionManager {
   }
 
   /**
-   * Register the attachment-directory guidance for one Session. Called after
-   * the effective working directory is known (a worktree checkout path is
-   * only returned once the worktree exists), so the prompt section can name
-   * the absolute directory. Best-effort: a missing system-prompt service
-   * (headless) is a no-op and a late registration never blocks the turn.
+   * Register the attachment guidance for one Session. Called after the
+   * effective working directory is known (a worktree checkout path is only
+   * returned once the worktree exists), so the archive guidance can name the
+   * absolute directory. The guidance flavor follows the *effective* attachment
+   * backend: an explicitly configured archive deployment, or a native
+   * deployment whose host does not mount `ctx.attachments`, keeps the legacy
+   * workspace-directory instructions. Best-effort: a missing system-prompt
+   * service (headless) is a no-op and a late registration never blocks the turn.
    */
   async mountGuidance(agent: Agent, directory: string): Promise<void> {
+    // With inbound attachments disabled the Agent has no attachment workflow to
+    // discover (and the legacy guidance would wrongly claim files are archived).
+    if (!this.deps.config.acceptAttachments) return
+    const mode = effectiveAttachmentMode(
+      this.deps.config.attachmentStore,
+      resolveAttachmentService(this.deps.ctx),
+      this.deps.config.feishuTools.attachmentFetch,
+      this.deps.config.acceptAttachments,
+    )
     try {
-      await mountChannelGuidance(agent.ctx, attachmentsDir(directory))
+      await mountChannelGuidance(
+        agent.ctx,
+        mode,
+        mode === 'archive' ? attachmentsDir(directory) : undefined,
+      )
     } catch (error) {
       this.deps.warn(
         'dsh-channels: mounting attachment guidance for session %s failed: %s',
@@ -166,7 +193,7 @@ export class SessionManager {
     if (own !== undefined) return own
 
     const foreign = this.deps.ctx.agents.get(sessionId as SessionId)
-    if (foreign !== undefined) return this.borrow(sessionId, foreign)
+    if (foreign !== undefined) return await this.borrow(sessionId, foreign)
 
     let pending = this.pendingResume.get(sessionId)
     if (pending === undefined) {
@@ -179,9 +206,14 @@ export class SessionManager {
   }
 
   /** Borrow one foreign live agent and mount this channel's scoped policy. */
-  private borrow(sessionId: string, agent: Agent): LiveAgent {
+  private async borrow(sessionId: string, agent: Agent): Promise<LiveAgent> {
     const borrowed = borrowLiveAgent(agent, this.mountRequestPolicy(agent.ctx, agent.session))
     this.live.set(sessionId, borrowed)
+    // Best-effort tool backfill (D7): the foreign owner may have composed the
+    // session without this plugin's setup (web UI resolver, previous plugin
+    // instance). mountToolsFor swallows failures, so the borrow itself never
+    // fails; awaiting it makes the tool available before the first turn.
+    await this.mountToolsFor(agent.ctx, sessionId)
     return borrowed
   }
 
@@ -193,7 +225,7 @@ export class SessionManager {
       // (config override or roster default). A session persisted before the
       // preset fix has no preset recorded on its header; re-resolving here is
       // what repairs it on the first resume after a restart.
-      const composition = await this.presetComposition(undefined, true)
+      const composition = await this.presetComposition(undefined, true, sessionId)
       const handle = await this.deps.ctx.agents.resume({
         resumeSessionId: sessionId,
         agentOptions: this.agentOptions(),
@@ -215,7 +247,7 @@ export class SessionManager {
       // Lost a cold-resume race: another owner published the session while our
       // resume was in flight. Borrow the winner instead of failing the turn.
       const winner = this.deps.ctx.agents.get(sessionId)
-      if (winner !== undefined) return this.borrow(sessionId, winner)
+      if (winner !== undefined) return await this.borrow(sessionId, winner)
       throw error
     }
   }
@@ -255,7 +287,7 @@ export class SessionManager {
   async renew(record: RouteRecord, oldLive: LiveAgent): Promise<RenewCommit> {
     const sessionId = randomUUID() as SessionId
     const preset = this.effectivePreset(oldLive.agent.session)
-    const composition = await this.presetComposition(preset, false)
+    const composition = await this.presetComposition(preset, false, sessionId)
     const services: PlacementServices = placementServices(this.deps.ctx)
     const switchable = services.workingDirectory !== undefined
     const workspacePath = record.workspacePath
@@ -358,6 +390,7 @@ export class SessionManager {
   private async presetComposition(
     requestedPreset: string | undefined = this.deps.config.agentPreset,
     useRosterDefault = true,
+    sessionId?: string,
   ): Promise<PresetComposition> {
     // Read through ctx.get (safe lookup): only the web profile ships a roster,
     // and direct property access on a cordis context throws for services the
@@ -369,6 +402,7 @@ export class SessionManager {
       // cannot guarantee that the explicit channel value wins.
       this.mountRequestPolicy(agentCtx)
       await mountChannelCommands(agentCtx)
+      if (sessionId !== undefined) await this.mountToolsFor(agentCtx, sessionId)
     }
     if (presets === undefined || (requestedPreset === undefined && !useRosterDefault)) {
       return { setup: channelCommandsOnly }
@@ -380,10 +414,30 @@ export class SessionManager {
         this.mountRequestPolicy(agentCtx)
         await presets.mount(agentCtx, resolved.id)
         await mountChannelCommands(agentCtx)
+        if (sessionId !== undefined) await this.mountToolsFor(agentCtx, sessionId)
       },
     }
   }
 
+  /**
+   * Mount the channel model tools into one Agent scope, at most once per
+   * scope. A failure is logged and swallowed: missing tools never fail a
+   * session (attachment fetch degrades to its structured failures).
+   */
+  private async mountToolsFor(agentCtx: AgentContext, sessionId: string): Promise<void> {
+    if (this.deps.mountTools === undefined) return
+    if (this.toolMounts.has(agentCtx)) return
+    try {
+      await this.deps.mountTools(agentCtx, sessionId)
+      this.toolMounts.add(agentCtx)
+    } catch (error) {
+      this.deps.warn(
+        'dsh-channels: mounting channel tools for session %s failed: %s',
+        sessionId, String(error),
+      )
+    }
+  }
+
   /** Effective preset after folding any durable runtime preset switch. */
   private effectivePreset(session: Session): string | undefined {
     let selected = session.header.agentPreset

package/src/settings/contract.ts

@@ -40,9 +40,10 @@ export const ACCESS_REQUESTS_ROUTE = '/dsh-channels/access/requests'
 export const PICK_DIRECTORY_ROUTE = '/dsh-channels/pick-directory'
 
 /**
- * 可由 Web 面板覆盖的配置项。全部是 `src/config.ts` 里已存在的字段；
- * 覆盖值写进 `$DSH_HOME/dsh-channels/settings.json`，优先级高于 profile
- * 的 `cordis.patch.yml`（见 README「Web 设置面板」）。
+ * 可由 Web 面板覆盖的配置项。顶层键对应 `src/config.ts` 的字段；`feishuTools.*`
+ * 是嵌套字段（覆盖层里仍写成 `{ "feishuTools": { ... } }` 对象）。覆盖值写进
+ * `$DSH_HOME/dsh-channels/settings.json`，优先级高于 profile 的
+ * `cordis.patch.yml`（见 README「Web 设置面板」）。
  *
  * 刻意不包含 `appId` / `appSecret`：它们是**凭据引用名**，面板改为直接
  * 编辑引用背后的值（`PUT /dsh-channels/credentials`，经 DSH 凭据服务写入），
@@ -67,8 +68,24 @@ export const EDITABLE_KEYS = [
   'adminOpenId',
   'accessMode',
   'authRequestTtlDays',
-  // 内容
+  // 内容与附件（v2 管线；`feishuTools.*` 是嵌套配置，覆盖层仍写成嵌套对象）
   'acceptAttachments',
+  'attachmentStore',
+  'prefetchImages',
+  'prefetchTimeoutMs',
+  'prefetchImageMaxBytes',
+  'prefetchTotalMaxBytes',
+  'historyBootstrapLimit',
+  'pendingAttachmentTtlMs',
+  'pendingAttachmentLimit',
+  // 模型工具（feishuTools 子项）
+  'feishuTools.attachmentFetch',
+  'feishuTools.attachmentFetchMaxResources',
+  'feishuTools.attachmentFetchMaxBytes',
+  'feishuTools.attachmentFetchTimeoutMs',
+  'feishuTools.topicMessages',
+  'feishuTools.topicMessagesTimeoutMs',
+  'promptContextTimeoutMs',
   // 模型
   'provider',
   'model',
@@ -104,7 +121,7 @@ export type FieldKind = 'boolean' | 'number' | 'text' | 'select'
  * panel tab (see {@link TAB_FIELD_GROUPS}); the Host is the source of truth for
  * which key belongs to which group.
  */
-export type FieldGroup = 'workspace' | 'behavior' | 'content' | 'model' | 'streaming' | 'access'
+export type FieldGroup = 'workspace' | 'behavior' | 'content' | 'tools' | 'model' | 'streaming' | 'access'
 
 /** One selectable value rendered by the generic form. */
 export interface FieldOptionWire {
@@ -486,7 +503,7 @@ export type PanelTabId = (typeof PANEL_TABS)[number]['id']
 /** Which editable field groups each tab renders (the tabs own one or two). */
 export const TAB_FIELD_GROUPS: Readonly<Record<PanelTabId, readonly FieldGroup[]>> = {
   connection: [],
-  sessions: ['behavior', 'content'],
+  sessions: ['behavior', 'content', 'tools'],
   model: ['model'],
   workspace: ['workspace'],
   access: ['access'],
@@ -498,6 +515,7 @@ export const FIELD_GROUP_LABELS: Readonly<Record<FieldGroup, string>> = {
   workspace: '工作区与文件',
   behavior: '行为',
   content: '内容与附件',
+  tools: '模型工具',
   model: '模型与推理',
   streaming: '流式卡片与日志',
   access: '准入与授权',
@@ -570,9 +588,9 @@ export const PANEL_COPY = {
   credentialsPendingHint: '填写后点「保存凭据」；两项齐全时插件会自动连接飞书。',
   // ---- tabs / forms -------------------------------------------------------
   connectionTabHelp: '连接状态与飞书应用凭据。凭据不完整时不会连接飞书。',
-  sessionsTabHelp: '私聊、群聊触发方式与入站内容；「需重连」项在下次连接时读取。',
+  sessionsTabHelp: '私聊、群聊触发方式与入站内容：附件存储/预取、静默登记保留、模型工具开关与读取预算；「需重连」项在下次连接时读取。',
   modelTabHelp: '飞书会话使用的模型服务商、模型、推理档位与 Agent 预设；下拉选项来自宿主机实时目录，保存后对新会话生效。',
-  workspaceTabHelp: '每个用户一个工作区（模型/工具产生文件的落点），每个话题在其中拥有独立工作目录；只影响之后新建的话题。',
+  workspaceTabHelp: '每个用户一个工作区（模型/工具产生文件的落点），每个话题在其中拥有独立工作目录；只影响之后新建的话题。入站附件默认存于 DSH 原生附件库，不占用话题目录，也不会被这里的目录清理删除。',
   accessTabHelp: '准入采用 fail-closed：管理员不受白名单限制，非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。',
   advancedTabHelp: '流式刷新等低层参数、Web 覆盖文件与只读信息。',
   save: '保存更改',
@@ -621,7 +639,7 @@ export const PANEL_COPY = {
   // ---- model --------------------------------------------------------------
   // ---- cleanup ------------------------------------------------------------
   cleanupCard: '目录清理',
-  cleanupCardHelp: '删除超过保留期且不再活跃的飞书话题目录（以及旧版本按话题建立的工作区目录）；用户工作区本身、DSH 会话日志都不会删除。删除不可恢复：相关旧话题会失效并提示已过期。',
+  cleanupCardHelp: '只清理工作区与 Agent 产物：删除超过保留期且不再活跃的飞书话题目录、旧版本按话题建立的工作区目录，以及这些目录内 Agent 产生的文件；不影响 Session 附件——入站图片/文件默认存于 DSH 原生附件库，不随目录清理删除。用户工作区本身与 DSH 会话日志也不会删除。删除不可恢复：相关旧话题会失效并提示已过期。',
   cleanupRetention: '保留期',
   cleanupAutoLabel: '自动清理',
   cleanupCandidates: '可清理目录',
@@ -633,7 +651,7 @@ export const PANEL_COPY = {
   cleanupAutoInactive: '未执行（保留期为关闭）',
   cleanupNow: '立即清理',
   cleanupRunning: '清理中…',
-  cleanupConfirm: '确定清理过期目录吗？该操作不可恢复，会删除这些目录内的全部文件（包括 attachments/ 附件）。',
+  cleanupConfirm: '确定清理过期目录吗？只清理工作区与 Agent 产物，不影响 Session 附件；但这些目录内未提交的文件会被删除，且操作不可恢复。',
   cleanupConfirmHint: '删除前会再次确认；保留期为「关闭」或没有过期目录时按钮不可用。',
   cleanupDisabledOff: '保留策略为「关闭」：请先在上方「过期目录保留期」中选择保留天数。',
   cleanupDisabledEmpty: '没有超过保留期的过期目录。',

package/src/settings/overlay.ts

@@ -20,10 +20,89 @@ import { configSchema } from '../config.ts'
 import type { FeishuConfig } from '../config.ts'
 import { normalizeWorkspaceBaseDir } from '../workspaces.ts'
 import { EDITABLE_KEYS } from './contract.ts'
-import type { ConfigValue, EditableKey } from './contract.ts'
+import type { ConfigValue, EditableKey, EditableValues } from './contract.ts'
 
-/** The subset of `FeishuConfig` the Web panel may override. */
-export type OverlayPatch = Partial<Pick<FeishuConfig, EditableKey>>
+/** Prefix of a nested panel key that addresses one `feishuTools` field. */
+const FEISHU_TOOLS_PREFIX = 'feishuTools.'
+
+/** Panel keys that address a nested `feishuTools` field (e.g. `feishuTools.topicMessages`). */
+export type NestedEditableKey = Extract<EditableKey, `feishuTools.${string}`>
+
+/** Panel keys that address a top-level config field. */
+export type TopLevelEditableKey = Exclude<EditableKey, NestedEditableKey>
+
+/** One partial `feishuTools` object inside the overlay layer. */
+export type FeishuToolsOverlay = Partial<FeishuConfig['feishuTools']>
+
+/**
+ * The subset of `FeishuConfig` the Web panel may override. `feishuTools` stays
+ * partial: the overlay only records the sub-fields the operator actually
+ * changed, and the merge keeps every other value from the profile layer.
+ */
+export type OverlayPatch = Partial<Pick<FeishuConfig, TopLevelEditableKey>> & {
+  feishuTools?: FeishuToolsOverlay
+}
+
+/** Whether one editable key addresses a nested `feishuTools` field. */
+export function isNestedEditableKey(key: EditableKey): key is NestedEditableKey {
+  return key.startsWith(FEISHU_TOOLS_PREFIX)
+}
+
+/** `attachmentFetch` for the panel key `feishuTools.attachmentFetch`. */
+function nestedFieldOf(key: NestedEditableKey): keyof FeishuConfig['feishuTools'] {
+  return key.slice(FEISHU_TOOLS_PREFIX.length) as keyof FeishuConfig['feishuTools']
+}
+
+/** The `feishuTools` object of an untyped overlay/config record, when usable. */
+function toolsRecordOf(container: Record<string, unknown>): Record<string, unknown> | undefined {
+  const tools = container.feishuTools
+  if (typeof tools !== 'object' || tools === null || Array.isArray(tools)) return undefined
+  return tools as Record<string, unknown>
+}
+
+/** Read one editable value out of an untyped overlay record (nested-aware). */
+export function overlayValueOf(source: Record<string, unknown>, key: EditableKey): unknown {
+  if (!isNestedEditableKey(key)) return source[key]
+  return toolsRecordOf(source)?.[nestedFieldOf(key)]
+}
+
+/** Write one editable value into an untyped overlay record (nested-aware). */
+export function setOverlayValue(target: Record<string, unknown>, key: EditableKey, value: unknown): void {
+  if (!isNestedEditableKey(key)) {
+    target[key] = value
+    return
+  }
+  const tools = toolsRecordOf(target) ?? {}
+  tools[nestedFieldOf(key)] = value
+  target.feishuTools = tools
+}
+
+/** Read one editable value out of a resolved config (nested-aware). */
+export function configValueOf(config: FeishuConfig, key: EditableKey): ConfigValue | undefined {
+  if (!isNestedEditableKey(key)) return config[key] as ConfigValue | undefined
+  return config.feishuTools[nestedFieldOf(key)] as ConfigValue | undefined
+}
+
+/** Deep-merge one overlay patch over another (only `feishuTools` is nested). */
+export function mergeOverlayPatch(base: OverlayPatch, addition: OverlayPatch): OverlayPatch {
+  const merged: OverlayPatch = { ...base, ...addition }
+  if (base.feishuTools !== undefined || addition.feishuTools !== undefined) {
+    merged.feishuTools = { ...base.feishuTools, ...addition.feishuTools }
+  }
+  return merged
+}
+
+/** Remove one editable key from an overlay patch (nested-aware). */
+export function deleteOverlayKey(patch: OverlayPatch, key: EditableKey): void {
+  if (!isNestedEditableKey(key)) {
+    delete patch[key as TopLevelEditableKey]
+    return
+  }
+  const tools = patch.feishuTools
+  if (tools === undefined) return
+  delete tools[nestedFieldOf(key)]
+  if (Object.keys(tools).length === 0) delete patch.feishuTools
+}
 
 /** Fields whose empty string means "clear the override" (optional text config). */
 const OPTIONAL_TEXT_KEYS = new Set<EditableKey>(['provider', 'model', 'reasoningEffort', 'agentPreset'])
@@ -43,24 +122,38 @@ export function parseOverlay(raw: unknown): { ok: true; patch: OverlayPatch } |
   const issues: Array<{ path: string; message: string }> = []
   const patch: Record<string, unknown> = {}
   const shape = configSchema.shape as unknown as Record<string, z.ZodType>
+  const toolsShape = configSchema.shape.feishuTools
+  if (Object.hasOwn(source, 'feishuTools') && source.feishuTools !== undefined
+    && toolsRecordOf(source) === undefined) {
+    issues.push({ path: 'feishuTools', message: '必须是 JSON 对象' })
+  }
   for (const key of EDITABLE_KEYS) {
-    if (!Object.hasOwn(source, key)) continue
-    const value = source[key]
+    // Nested keys have no own property on the root object, so read through the
+    // shared accessor instead of `Object.hasOwn`.
+    const value = overlayValueOf(source, key)
     if (value === undefined) continue
     // `baseDir` needs location semantics the shared string schema cannot
     // express (absolute only, `~` expansion, no filesystem root).
     if (key === 'baseDir') {
       const checked = normalizeWorkspaceBaseDir(value)
       if (!checked.ok) issues.push({ path: key, message: checked.message })
-      else patch[key] = checked.value
+      else setOverlayValue(patch, key, checked.value)
       continue
     }
-    const parsed = shape[key]!.safeParse(value)
+    // Nested `feishuTools` values validate against the canonical sub-object
+    // schema; only the edited sub-field is copied out of the parsed result so
+    // schema defaults never leak into the overlay.
+    const parsed = isNestedEditableKey(key)
+      ? toolsShape.safeParse({ [nestedFieldOf(key)]: value })
+      : shape[key]!.safeParse(value)
     if (!parsed.success) {
       issues.push({ path: key, message: parsed.error.issues[0]?.message ?? '非法值' })
       continue
     }
-    patch[key] = parsed.data
+    const normalizedValue = isNestedEditableKey(key)
+      ? (parsed.data as FeishuConfig['feishuTools'])[nestedFieldOf(key)]
+      : parsed.data
+    setOverlayValue(patch, key, normalizedValue)
   }
   if (issues.length > 0) return { ok: false, issues }
   return { ok: true, patch: normalizeOverlay(patch) }
@@ -86,26 +179,44 @@ export interface OverlayLogger {
 export function normalizeOverlay(patch: Record<string, unknown>): OverlayPatch {
   const normalized: Record<string, unknown> = {}
   for (const key of EDITABLE_KEYS) {
-    const value = patch[key]
+    const value = overlayValueOf(patch, key)
     if (value === undefined) continue
     if (OPTIONAL_TEXT_KEYS.has(key) && value === '') continue
-    normalized[key] = value
+    setOverlayValue(normalized, key, value)
   }
   return normalized as OverlayPatch
 }
 
 /** Merge the Web overlay over the profile-provided base config. */
 export function mergeOverlay(base: FeishuConfig, overlay: OverlayPatch): FeishuConfig {
-  return { ...base, ...overlay }
+  const { feishuTools, ...topLevel } = overlay
+  const merged: FeishuConfig = { ...base, ...topLevel }
+  if (feishuTools !== undefined) merged.feishuTools = { ...base.feishuTools, ...feishuTools }
+  return merged
 }
 
-/** Project one config onto the editable-key subset (wire shape). */
+/** Project one config onto the editable-key subset (wire shape, nested keys dotted). */
 export function pickEditable(config: FeishuConfig): Record<EditableKey, ConfigValue | undefined> {
   const picked: Record<string, ConfigValue | undefined> = {}
-  for (const key of EDITABLE_KEYS) picked[key] = config[key] as ConfigValue | undefined
+  for (const key of EDITABLE_KEYS) picked[key] = configValueOf(config, key)
   return picked as Record<EditableKey, ConfigValue | undefined>
 }
 
+/**
+ * Project an overlay patch onto flat editable keys (nested `feishuTools.*`
+ * values become dotted keys). The panel wire uses the same key space as
+ * `fields` / `overriddenKeys`, so the client never has to know the nested
+ * storage layout.
+ */
+export function overlayValues(patch: OverlayPatch): EditableValues {
+  const values: Record<string, ConfigValue> = {}
+  for (const key of EDITABLE_KEYS) {
+    const value = overlayValueOf(patch as Record<string, unknown>, key)
+    if (value !== undefined) values[key] = value as ConfigValue
+  }
+  return values as EditableValues
+}
+
 /**
  * One JSON overlay file. Reads degrade to `{}` with a warning; writes are
  * atomic and owner-readable only.