diff --git a/plugins/dsh-mail-bridge/lib/attachment-ids.d.ts b/plugins/dsh-mail-bridge/lib/attachment-ids.d.ts
new file mode 100644
index 0000000..340f900
--- /dev/null
+++ b/plugins/dsh-mail-bridge/lib/attachment-ids.d.ts
@@ -0,0 +1,13 @@
+/**
+ * `attachment-ids.js` 的类型声明。
+ *
+ * 为什么这个文件必须存在：dsh 桥走 TypeScript 编译（`tsc -p tsconfig.json`），
+ * 而 `lib/` 下每个共用模块都配了 `.d.ts`。缺了它，`import { normalizeAttachmentIDs }
+ * from '../lib/attachment-ids.js'` 会报 TS7016（隐式 any），**构建直接失败** ——
+ * pi 与 opencode 不做类型检查，所以只有 dsh 会在这里红，很容易被当成"偶发"放过。
+ *
+ * 参数类型刻意写成 `unknown`：这个函数的全部意义就是接收**不可靠的输入**
+ * （模型可能给数组、JSON 字符串、单个 id、或混着 null 的数组），
+ * 用 `string[]` 之类收窄签名会让人误以为调用方本来就该给对形状。
+ */
+export declare function normalizeAttachmentIDs(value: unknown): string[];
diff --git a/plugins/dsh-mail-bridge/package.json b/plugins/dsh-mail-bridge/package.json
index 2990cc9..562df76 100644
--- a/plugins/dsh-mail-bridge/package.json
+++ b/plugins/dsh-mail-bridge/package.json
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "tsc",
     "verify": "tsc --noEmit",
+    "pretest": "tsc -p tsconfig.json",
     "test": "node --test 'test/*.test.mjs'"
   },
   "peerDependencies": {