@modesto_ma/dsh-channels 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modesto_ma/dsh-channels",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "DeepSeek Harness (DSH) 飞书渠道插件：一个 dsh 实例对应一个飞书机器人，私聊/群聊/话题群 @ 触发会话，话题绑定 session，卡片 2.0 流式回复；Web 设置里提供「飞书渠道」状态与常用配置面板",
   "repository": {
     "type": "git",

package/src/cleanup.ts

@@ -28,11 +28,17 @@
  * A directory with no usable activity evidence at all (missing/unreadable) is
  * never offered for deletion: irreversible removal requires positive evidence.
  *
+ * Scope boundary (attachment_pipeline_v2, decisions D6/D12): cleanup only
+ * removes workspace / Agent-artifact directories. Inbound attachments are not
+ * workspace files — the native backend keeps them in the DSH attachment
+ * library, and the legacy `_staging` adoption area is explicitly excluded so a
+ * pending one-time adoption can never be destroyed by a retention sweep.
+ *
  * @module dsh-channels/cleanup
  */
 
 import path from 'node:path'
-import { legacyTopicWorkspaceRoot } from './workspaces.ts'
+import { legacyTopicWorkspaceRoot, stagingRoot } from './workspaces.ts'
 
 /** Values the `workspaceRetention` config accepts. `off` disables cleanup. */
 export const WORKSPACE_RETENTION_VALUES = ['off', '7d', '30d', '90d', '180d'] as const
@@ -330,6 +336,7 @@ export async function planWorkspaceCleanup(deps: CleanupDeps): Promise<CleanupPl
     return undefined
   }
   const legacyRoot = legacyTopicWorkspaceRoot(baseDir)
+  const stagingDir = stagingRoot(baseDir)
 
   const now = deps.now?.() ?? Date.now()
   const cutoff = now - window
@@ -414,6 +421,8 @@ export async function planWorkspaceCleanup(deps: CleanupDeps): Promise<CleanupPl
     if (isFilesystemRoot(resolved)) return false
     if (!isPathInside(baseDir, resolved)) return false
     if (resolved === legacyRoot || isPathInside(legacyRoot, resolved)) return false
+    // Legacy pre-topic staging (one-time adoption area): never a cleanup target.
+    if (resolved === stagingDir || isPathInside(stagingDir, resolved)) return false
     if (userWorkspacePaths.has(resolved)) return false
     return true
   }
@@ -486,6 +495,7 @@ export async function applyWorkspaceCleanup(
   const baseDir = path.resolve(deps.baseDir)
   const baseDirIsRoot = isFilesystemRoot(baseDir)
   const legacyRoot = legacyTopicWorkspaceRoot(baseDir)
+  const stagingDir = stagingRoot(baseDir)
   const registered = new Set(
     (await deps.listWorkspaces())
       .filter(workspace => pluginWorkspaceTitle(workspace.title))
@@ -503,9 +513,10 @@ export async function applyWorkspaceCleanup(
     // Defense in depth: never trust a plan object for the destructive step.
     const insideBase = !baseDirIsRoot && isPathInside(baseDir, targetPath)
     const inLegacyRoot = isPathInside(legacyRoot, targetPath)
+    const inStaging = isPathInside(stagingDir, targetPath)
     const valid = target.kind === 'workspace'
       ? insideBase && inLegacyRoot
-      : insideBase && !inLegacyRoot && !registered.has(path.resolve(targetPath))
+      : insideBase && !inLegacyRoot && !inStaging && !registered.has(path.resolve(targetPath))
     if (!valid) {
       failures.push({ path: targetPath, message: 'refused: path is not a cleanable plugin directory' })
       continue

package/src/config.ts

@@ -34,6 +34,54 @@ export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000
 /** Default structured-question window: 5 minutes per `ask_user_question` call. */
 export const DEFAULT_QUESTION_TIMEOUT_MS = 5 * 60 * 1000
 
+/** Backends for inbound attachment storage, selected by `attachmentStore`. */
+export const ATTACHMENT_STORE_MODES = ['native', 'archive'] as const
+export type AttachmentStoreMode = (typeof ATTACHMENT_STORE_MODES)[number]
+
+/** Default retention of silently registered attachment metadata: 7 days. */
+export const DEFAULT_PENDING_ATTACHMENT_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+/** Default per-`(chat, thread, sender)` cap of pending attachment rows. */
+export const DEFAULT_PENDING_ATTACHMENT_LIMIT = 10
+
+/** Default per-call attachment count of `feishu_attachment_fetch`. */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES = 10
+
+/** Default per-call total download budget of `feishu_attachment_fetch` (100 MiB). */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_BYTES = 100 * 1024 * 1024
+
+/** Default whole-call timeout of `feishu_attachment_fetch` (120 s). */
+export const DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS = 120_000
+
+/** Default per-image byte cap for trigger-message prefetch (20 MiB). */
+export const DEFAULT_PREFETCH_IMAGE_MAX_BYTES = 20 * 1024 * 1024
+
+/** Default total byte budget for one trigger-message image prefetch (50 MiB). */
+export const DEFAULT_PREFETCH_TOTAL_MAX_BYTES = 50 * 1024 * 1024
+
+/** Default short timeout for one trigger-message image prefetch (10 s). */
+export const DEFAULT_PREFETCH_TIMEOUT_MS = 10_000
+
+/**
+ * Default number of recent topic messages attached to a new Session's first
+ * turn (0 disables the history bootstrap). Mirrors
+ * `HISTORY_BOOTSTRAP_DEFAULT` in `feishu/message-read.ts`.
+ */
+export const DEFAULT_HISTORY_BOOTSTRAP_LIMIT = 10
+
+/** Hard cap of the first-turn history bootstrap. */
+export const MAX_HISTORY_BOOTSTRAP_LIMIT = 20
+
+/** Default whole-call timeout of `feishu_topic_messages` (20 s). */
+export const DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS = 20_000
+
+/**
+ * Default budget of one passive prompt-enrichment message read (quoted excerpt
+ * / first-turn topic history). Kept short: the turn must not wait long for an
+ * optional context block.
+ */
+export const DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS = 3_000
+
 /** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
 const credentialRefSchema = z.string().regex(
   CREDENTIAL_REF_PATTERN,
@@ -138,13 +186,154 @@ export const configSchema = z.object({
    */
   approvalTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_APPROVAL_TIMEOUT_MS),
   /**
-   * Accept inbound Feishu images, files, and merged-forward chat records and
-   * save them below `<workspace>/attachments/`. Nothing is forwarded to the
-   * model automatically: the Agent reads whichever attachment the
-   * conversation needs with its ordinary filesystem tools. Disabled keeps
-   * attachment messages inert (no save, no turn).
+   * Accept inbound Feishu images, files, and merged-forward chat records.
+   *
+   * With the native backend (default) images of the triggering message are
+   * prefetched into the DSH native attachment library and files stay lazy
+   * behind a prompt manifest; with the archive backend the resources are saved
+   * below `<workspace>/attachments/` before the turn, exactly like the legacy
+   * pipeline. Disabled keeps attachment messages inert (no save, no turn, no
+   * pending metadata registration).
    */
   acceptAttachments: z.boolean().default(true),
+  /**
+   * Backend for inbound Feishu images and files.
+   *
+   * - `native` (default): store into the DSH native attachment library
+   *   (`ctx.attachments`) as durable `ImageBlock`/`FileBlock` references; if
+   *   the host does not mount that service, the storage layer falls back to
+   *   `archive` for that deployment.
+   * - `archive`: legacy behavior — write the resources into the topic
+   *   workspace `attachments/` directory through the existing intake.
+   *
+   * Admission consumes this switch through the backend-selecting inbound
+   * store: an explicit `archive` always uses the legacy download path, and a
+   * `native` deployment without the mounted host service degrades to the same
+   * legacy path (see `effectiveAttachmentMode`).
+   */
+  attachmentStore: z.enum(ATTACHMENT_STORE_MODES).default('native'),
+  /**
+   * Prefetch images attached to the triggering message into the first model
+   * turn (native attachment backend only). The session, topic, and streaming
+   * card are already visible before the prefetch starts; the turn only waits
+   * for the (short, bounded) image download, never for file bytes. Failed,
+   * oversized, or timed-out images degrade to a manifest row that the model
+   * can fetch with `feishu_attachment_fetch`. Set `false` to keep every
+   * attachment lazy (images then need the tool as well).
+   */
+  prefetchImages: z.boolean().default(true),
+  /**
+   * Largest single image the trigger-message prefetch buffers in memory before
+   * refusing it (default 20 MiB). A refused image stays in the manifest and
+   * is fetched on demand.
+   */
+  prefetchImageMaxBytes: z.number().int().min(1).max(200 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_IMAGE_MAX_BYTES),
+  /**
+   * Total byte budget of one trigger-message image prefetch (default 50 MiB).
+   * Once exhausted, the remaining images degrade to the manifest.
+   */
+  prefetchTotalMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_TOTAL_MAX_BYTES),
+  /**
+   * Short whole-prefetch timeout (default 10 s). On expiry the already-loaded
+   * images stay in the prompt and the rest degrade to the manifest, so a slow
+   * image download never blocks the turn for long.
+   */
+  prefetchTimeoutMs: z.number().int().min(100).max(120_000).default(DEFAULT_PREFETCH_TIMEOUT_MS),
+  /**
+   * Number of recent messages of the current topic automatically attached to
+   * the FIRST turn of a new Session (decision D1: the model should see the
+   * discussion before @ without asking). The `<feishu_history>` block is
+   * bounded and truncated with an explicit marker and each line carries the
+   * message_id needed to fetch a named attachment; older messages remain
+   * reachable through the `feishu_topic_messages` tool. `0` disables the
+   * bootstrap entirely. Reads use a short (~3 s) prompt-enrichment budget and a
+   * failure (missing scope, p2p history unavailable, channel down) degrades
+   * silently: the turn still runs.
+   */
+  historyBootstrapLimit: z.number().int().min(0).max(MAX_HISTORY_BOOTSTRAP_LIMIT)
+    .default(DEFAULT_HISTORY_BOOTSTRAP_LIMIT),
+  /**
+   * Whole-read budget (milliseconds) of the passive prompt enrichment: the
+   * quoted-message excerpt and the first-turn topic history. Deliberately short
+   * (default 3 s) and independent from `feishuTools.topicMessagesTimeoutMs`:
+   * on expiry the block is omitted and the turn runs. Model-initiated reads
+   * through `feishu_topic_messages` use the tool timeout instead.
+   */
+  promptContextTimeoutMs: z.number().int().min(100).max(10_000)
+    .default(DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS),
+  /**
+   * Retention of silently registered attachment metadata (the
+   * `pending_attachments` table). A message that does not trigger a model turn
+   * (attachment-only p2p message, un-mentioned group message, attachment-only
+   * message inside a bound topic) is recorded as metadata only; a later
+   * triggered message in the same `(chat, thread, sender)` scope may list and
+   * fetch it. Rows older than this window are removed by the periodic record
+   * GC. `0` disables age pruning (the per-scope cap still bounds each scope).
+   * Default 7 days.
+   */
+  pendingAttachmentTtlMs: z.number().int().min(0).default(DEFAULT_PENDING_ATTACHMENT_TTL_MS),
+  /**
+   * Maximum silently registered attachment rows kept per `(chat, thread,
+   * sender)` scope. Registering beyond the cap evicts the oldest row of that
+   * scope; the prompt manifest only ever shows the most recent 5 unconsumed
+   * rows. Default 10.
+   */
+  pendingAttachmentLimit: z.number().int().min(1).max(100).default(DEFAULT_PENDING_ATTACHMENT_LIMIT),
+  /**
+   * Model-facing Feishu tools.
+   *
+   * - `attachmentFetch` (default on): register `feishu_attachment_fetch` in
+   *   channel sessions so the model can fetch images/files of a known message
+   *   on demand. Registration is skipped (with one warning) on deployments
+   *   without the host `tools` / `attachments` services. Turning it off also
+   *   keeps inbound attachments on the archive backend: lazy native files
+   *   would be unreachable without the tool, so admission downloads them to
+   *   the workspace instead (see `effectiveAttachmentMode`).
+   * - `attachmentFetchMaxResources`: maximum attachments one tool call may
+   *   fetch (1–50). A message with more attachments is refused with a readable
+   *   reason so the model can retry per `file_key`.
+   * - `attachmentFetchMaxBytes`: total download budget of one tool call
+   *   (default 100 MiB). Files stream to the native attachment library, so the
+   *   limit is enforced while streaming rather than buffered first.
+   * - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s). On expiry
+   *   the in-flight download is cancelled and reported per attachment.
+   * - `topicMessages` (default on): register `feishu_topic_messages` in
+   *   channel sessions so the model can read the quoted message / earlier
+   *   topic messages on demand and authorize their attachments for fetch.
+   *   Reads require the Feishu message-read scopes; a missing scope degrades to
+   *   a readable tool failure and never fails the turn. This switch only
+   *   controls the model-facing tool: the passive `<feishu_quote>` /
+   *   `<feishu_history>` prompt excerpts stay enabled (they are bounded and
+   *   degrade silently) and are configured by `historyBootstrapLimit`. On the
+   *   archive backend the tool is still mounted for history text, while its
+   *   description states that `feishu_attachment_fetch` is unavailable.
+   * - `topicMessagesTimeoutMs`: whole-call timeout of one model-initiated
+   *   topic read (default 20 s). Passive prompt excerpts use a separate short
+   *   (~3 s) budget and never wait this long.
+   *
+   * The Web panel/metrics ship with `panel_docs_release`.
+   */
+  feishuTools: z.object({
+    attachmentFetch: z.boolean().default(true),
+    attachmentFetchMaxResources: z.number().int().min(1).max(50)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES),
+    attachmentFetchMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
+    attachmentFetchTimeoutMs: z.number().int().min(1_000).max(600_000)
+      .default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
+    topicMessages: z.boolean().default(true),
+    topicMessagesTimeoutMs: z.number().int().min(1_000).max(120_000)
+      .default(DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS),
+  }).default({
+    attachmentFetch: true,
+    attachmentFetchMaxResources: DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES,
+    attachmentFetchMaxBytes: DEFAULT_ATTACHMENT_FETCH_MAX_BYTES,
+    attachmentFetchTimeoutMs: DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS,
+    topicMessages: true,
+    topicMessagesTimeoutMs: DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS,
+  }),
   /**
    * Delete the topic directories of stale conversations, plus legacy
    * one-workspace-per-topic directories written by older plugin versions.

package/src/domain.ts

@@ -282,6 +282,89 @@ export const processedRecordSchema = z.object({
 
 export type ProcessedRecord = z.infer<typeof processedRecordSchema>
 
+/**
+ * Silently registered inbound attachment metadata ("pending attachments").
+ *
+ * A message that does not trigger a model turn — a p2p attachment-only
+ * message, an un-mentioned group message, an attachment-only message inside an
+ * already-bound topic — is recorded here without downloading bytes, replying,
+ * or reacting. A later triggered message in the same `(chat, thread?, sender)`
+ * scope can list these entries in its prompt manifest and fetch them on demand
+ * through the attachment tool. The table stores metadata only (Feishu resource
+ * keys), never bytes.
+ *
+ * Added without a storage-domain version bump: the host's JSON backend loads a
+ * declared table that is missing from the stored document as empty and keeps
+ * the stored `unit.version` (1), so existing deployments gain the table with no
+ * migration. Downgrading to a plugin build without this table would drop it on
+ * the next write — acceptable because plugin builds are replaced in place.
+ */
+export const PENDING_ATTACHMENT_KINDS = ['image', 'file', 'post', 'merge_forward'] as const
+
+/** Kind of message that carried the attachment payload. */
+export type PendingAttachmentKind = (typeof PENDING_ATTACHMENT_KINDS)[number]
+
+/**
+ * One attachment resource inside a pending record. Feishu downloads resources
+ * by `(message id, file key)`; `containerMessageId` is set when only a
+ * top-level container id works (merged-forward children).
+ */
+export const pendingAttachmentResourceSchema = z.object({
+  /** Resource kind delivered by Feishu. */
+  type: z.enum(['image', 'file']),
+  /** Feishu resource key (`img_v3_...` / `file_v3_...`). */
+  fileKey: z.string().min(1),
+  /** Original file name, when Feishu reports one. */
+  fileName: z.string().min(1).optional(),
+  /** Feishu folder entries cannot be downloaded; recorded so the fetch tool can
+   *  answer with a structured "folder unsupported" instead of a raw API error. */
+  folder: z.boolean().optional(),
+  /** Top-level container message id to download through, when different from
+   *  this record's own `messageId` (merged-forward child resources). */
+  containerMessageId: z.string().min(1).optional(),
+})
+
+export type PendingAttachmentResource = z.infer<typeof pendingAttachmentResourceSchema>
+
+/**
+ * One silently registered attachment message. Keyed by its Feishu message id so
+ * a redelivered event can never register twice. `scopeKey` is the
+ * `(chat, thread?, sender)` isolation unit; `consumed` marks metadata the
+ * agent already fetched, which then drops out of the prompt manifest (the
+ * record stays as an authorization fact until its TTL).
+ */
+export const pendingAttachmentRecordSchema = z.object({
+  /** Key the record is stored under (= `messageId`). */
+  key: z.string().min(1),
+  /** `(chat, thread?, sender)` isolation key; see `pendingAttachmentScopeKey`. */
+  scopeKey: z.string().min(1),
+  /** Feishu message id of the attachment message (the container id for
+   *  merged-forward records). */
+  messageId: z.string().min(1),
+  /** Feishu chat the message arrived in. */
+  chatId: z.string().min(1),
+  /** `p2p` or `group`. */
+  chatType: z.enum(['p2p', 'group']),
+  /** Feishu topic the message belongs to, when it has one. */
+  threadId: z.string().min(1).optional(),
+  /** Normalized sender id (open_id) that the scope is bound to. */
+  senderOpenId: z.string().min(1),
+  /** Epoch ms when the metadata was registered (clock seam for tests). */
+  receivedAt: z.number().int().nonnegative(),
+  /** Kind of message that carried the payload. */
+  kind: z.enum(PENDING_ATTACHMENT_KINDS),
+  /** Attachment payloads; empty for merged-forward containers (children are
+   *  listed through the container's own message id on fetch). */
+  resources: z.array(pendingAttachmentResourceSchema),
+  /** Remaining caption text after attachment placeholders, truncated. */
+  textExcerpt: z.string().min(1).optional(),
+  /** Set once the agent fetched the attachment; consumed rows leave the
+   *  manifest but stay queryable by message id until the TTL sweep. */
+  consumed: z.boolean().optional(),
+})
+
+export type PendingAttachmentRecord = z.infer<typeof pendingAttachmentRecordSchema>
+
 export interface FeishuDomainSpecShape {
   name: 'channels_routes'
   version: 1
@@ -318,6 +401,10 @@ export interface FeishuDomainSpecShape {
       valueSchema: typeof accessRequestRecordSchema
       __key?: string
     }
+    pending_attachments: {
+      valueSchema: typeof pendingAttachmentRecordSchema
+      __key?: string
+    }
   }
 }
 
@@ -352,6 +439,7 @@ export const feishuDomain: FeishuDomainSpecShape = {
     access_groups: { valueSchema: accessGroupRecordSchema },
     access_users: { valueSchema: accessUserRecordSchema },
     access_requests: { valueSchema: accessRequestRecordSchema },
+    pending_attachments: { valueSchema: pendingAttachmentRecordSchema },
   },
 }
 
@@ -418,6 +506,19 @@ export interface AccessRequestsTable {
   entries(): IterableIterator<[string, AccessRequestRecord]>
 }
 
+/**
+ * Normalized table handle for silently registered attachment metadata
+ * (key = Feishu message id).
+ */
+export interface PendingAttachmentsTable {
+  get(key: string): PendingAttachmentRecord | undefined
+  put(key: string, value: PendingAttachmentRecord): Promise<unknown> | void
+  /** Atomic read-modify-write on the host's write chain (`missing-key` when gone). */
+  update(key: string, fn: (current: PendingAttachmentRecord) => PendingAttachmentRecord): Promise<unknown>
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, PendingAttachmentRecord]>
+}
+
 /** Normalized domain handle. */
 export interface FeishuDomainHandle {
   routes: RoutesTable
@@ -427,6 +528,12 @@ export interface FeishuDomainHandle {
   accessGroups: AccessGroupsTable
   accessUsers: AccessUsersTable
   accessRequests: AccessRequestsTable
+  /**
+   * Pending attachment metadata. Optional on purpose: an embedded host whose
+   * storage domain refuses the added table leaves this undefined and the
+   * registry degrades to a process-memory TTL store (records lost on restart).
+   */
+  pendingAttachments?: PendingAttachmentsTable
   getGlobal(): FeishuDomainGlobal
   setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
   close(): Promise<void>

package/src/feishu/agent-context.ts

@@ -1,22 +1,30 @@
 /**
  * Agent-scoped system-prompt guidance for Feishu attachments.
  *
- * The channel archives inbound images/files/forwarded records below
- * `<session working directory>/attachments/` without any model turn. This
- * section is what makes that convention discoverable: it tells the Agent where
- * attachments live, how to read them, and that reading is opt-in per user
- * request.
+ * Which guidance is mounted follows the *effective* attachment backend
+ * (`attachmentStore`, decisions D6/D2):
+ * - `native` (the default): inbound images/files live in the DSH native
+ *   attachment library. Trigger-message images are prefetched and already
+ *   visible; files stay unloaded and the prompt carries a stable
+ *   `<feishu_context>` manifest (see `manifest.ts`) that the Agent uses with the
+ *   `feishu_attachment_fetch` tool on demand.
+ * - `archive` (legacy / fallback): inbound images/files are archived below
+ *   `<session working directory>/attachments/` and read with filesystem tools.
+ *   Kept for explicit `attachmentStore: 'archive'` deployments and for native
+ *   deployments whose host does not mount `ctx.attachments`.
  *
- * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so
- * it is disposed with the Agent and does not leak into other compositions.
- * It is mounted only after the Session's effective working directory is known
- * (see `SessionManager.mountGuidance`), so the absolute path is accurate even
- * when that directory is a Git worktree created after Agent creation.
+ * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so it
+ * is disposed with the Agent and does not leak into other compositions. The
+ * archive flavor is mounted only after the Session's effective working
+ * directory is known (see `SessionManager.mountGuidance`), so its absolute path
+ * is accurate even when that directory is a Git worktree created after Agent
+ * creation.
  *
  * @module dsh-channels/feishu/agent-context
  */
 
 import type { AgentContext } from '../host/agent.ts'
+import { FEISHU_CONTEXT_TAG } from './manifest.ts'
 
 /** Stable prompt-section name; one registration per Agent scope. */
 export const FEISHU_ATTACHMENTS_SECTION = 'dsh-channels:feishu-attachments'
@@ -28,24 +36,61 @@ export const FEISHU_ATTACHMENTS_SECTION = 'dsh-channels:feishu-attachments'
  */
 const FEISHU_ATTACHMENTS_ORDER = 950
 
-/** Model-facing text. Kept stable so unchanged sessions keep their KV cache. */
-export const FEISHU_ATTACHMENTS_GUIDANCE = `## Feishu attachments
+/** Attachment backend whose guidance to mount; mirrors `attachmentStore`. */
+export type AttachmentGuidanceMode = 'native' | 'archive'
+
+/**
+ * Native-library guidance (new default). Model-facing text kept stable so
+ * unchanged sessions keep their KV cache.
+ */
+export const FEISHU_ATTACHMENTS_NATIVE_GUIDANCE = `## Feishu attachments
+Inbound Feishu images and files are stored in the DSH native attachment library and are tied to this conversation's session; they are not copied into the working directory automatically.
+
+- Images that arrived in the message which triggered this turn are already visible to you as image blocks. Never load them again.
+- Files are not loaded by default: the conversation only carries their metadata, not their bytes.
+- The user message may carry a manifest in a \`<${FEISHU_CONTEXT_TAG}>\` block. It lists attachments that are not loaded yet, each with its message_id, type, and, when known, file_key and file name. A line with type=merge_forward is a forwarded-chat container: use its message_id without file_key. An image that could not be prefetched is listed the same way as a file.
+- The user message may also carry \`<feishu_quote>\` (the message this one replies to) and, on a new session's first turn, \`<feishu_history>\` (bounded recent topic messages). Attachments named there are not loaded; fetch one with \`feishu_attachment_fetch\` using the message_id shown on its line.
+- Use the \`feishu_topic_messages\` tool to read a quoted message in full, or to page through earlier messages of this topic (newest first, limit/cursor). Messages and attachments it returns are authorized for \`feishu_attachment_fetch\`.
+
+When the user's request genuinely needs an attachment, fetch it with the \`feishu_attachment_fetch\` tool: pass message_id, and add file_key to fetch one specific file of that message. Fetch nothing when the request can be answered without the bytes, and do not proactively enumerate or fetch attachments the user did not mention.
+
+Never read, copy, or print Feishu app credentials (for example files under the DSH home directory) and never call the Feishu OpenAPI directly with them; use only the Feishu tools provided in this conversation.
+
+A fetched file is an immutable, read-only copy in the native attachment library. Before changing it, copy it into the working directory and modify the copy. Only access attachments of this conversation; never read or mention another conversation's attachments.`
+
+/**
+ * Legacy archive guidance: attachments are archived under the conversation
+ * workspace's `attachments/` directory and read through filesystem tools.
+ * Model-facing text kept stable so unchanged sessions keep their KV cache.
+ */
+export const FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE = `## Feishu attachments
 Every Feishu conversation (topic) has its own working directory inside its user's workspace, and every working directory has its own \`attachments/\` directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
 
 Attachments are never inserted into the conversation automatically. Read them only when the user's request needs them, and do not read attachments the user did not mention:
 - images: use \`read_image\` with the file path;
 - text and code: use \`read\` when the session mounts that tool, otherwise \`bash\` (for example \`sed -n '1,200p' <file>\`);
 - other formats (PDF, Office, archives, ...): inspect or convert them with \`bash\`.
-If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations work in separate directories: never read outside this conversation's working directory, and never mention files from another conversation.`
+If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations work in separate directories: never read outside this conversation's working directory, and never mention files from another conversation.
+
+Never read, copy, or print Feishu app credentials (for example files under the DSH home directory) and never call the Feishu OpenAPI directly with them; use only the Feishu tools provided in this conversation.
+
+A message may also carry \`<feishu_quote>\` / \`<feishu_history>\` text excerpts. Attachments named there arrive lazily and are not in this directory in this deployment; describe what the excerpt says instead of claiming to have read the file.`
 
 /**
- * Full guidance for one Session. The absolute per-session directory is
- * appended when known so the convention still resolves after the Agent changes
+ * Full guidance text for one Session.
+ *
+ * The native flavor ignores `attachmentsDir` (there is no per-conversation
+ * directory to name). The archive flavor appends the absolute per-session
+ * directory when known so the convention still resolves after the Agent changes
  * its working directory with the `working_directory` tool.
  */
-export function attachmentsGuidance(attachmentsDir?: string): string {
-  if (attachmentsDir === undefined || attachmentsDir === '') return FEISHU_ATTACHMENTS_GUIDANCE
-  return `${FEISHU_ATTACHMENTS_GUIDANCE}\n\nThis conversation's attachment directory is \`${attachmentsDir.replace(/`/gu, "'")}\` (absolute).`
+export function attachmentsGuidance(
+  mode: AttachmentGuidanceMode = 'native',
+  attachmentsDir?: string,
+): string {
+  if (mode !== 'archive') return FEISHU_ATTACHMENTS_NATIVE_GUIDANCE
+  if (attachmentsDir === undefined || attachmentsDir === '') return FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE
+  return `${FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE}\n\nThis conversation's attachment directory is \`${attachmentsDir.replace(/`/gu, "'")}\` (absolute).`
 }
 
 /**
@@ -54,13 +99,14 @@ export function attachmentsGuidance(attachmentsDir?: string): string {
  */
 export async function mountChannelGuidance(
   agentCtx: AgentContext,
+  mode: AttachmentGuidanceMode = 'native',
   attachmentsDir?: string,
 ): Promise<void> {
   await agentCtx.inject(['systemPrompt'], (ctx) => {
     ctx.systemPrompt?.section({
       name: FEISHU_ATTACHMENTS_SECTION,
       order: FEISHU_ATTACHMENTS_ORDER,
-      text: attachmentsGuidance(attachmentsDir),
+      text: attachmentsGuidance(mode, attachmentsDir),
     })
   })
 }