手机附件收件箱 PerryLink/dsh-phone-inbox

dsh-phone-inbox

会话的入站手机（微信桥）附件收件箱：列出本次对话实际收到的附件，并按需把其中一个收进工作区。

它解决什么问题

dsh-wechat 把入站手机媒体保存到 ~/.dsh-wechat/tempfile/——在会话工作区之外——并把绝对路径写进一个纯文本块。由此带来两个后果，用户对两者都看不见：

1. 受工作区限制的工具读不到它。 dsh-data-quality 会拒绝任何逃出会话工作区的路径（path-escape），所以「我给你发了个 CSV，帮我分析一下」会失败，哪怕文件就在那里。
2. 文件名被毁掉了。 桥把文件命名为 ${Date.now()}-${rand4hex}-${name.replace(/[^\w.-]/g, "_")}，于是 材料.csv 落到磁盘上变成 __.csv。用户认不出自己的文件。

dsh-phone-inbox 不新增任何通道，默认也不复制任何东西。它让会话自己的入站列表变得可寻址，并还原桥弄坏的文件名——依据是桥本来就会写下的 [收到文件: <name>] 标记。

你能得到什么

| 工具 | 它回答的问题 |
| inbox_list | 「我刚从手机发给你的文件在哪？」 |
| inbox_adopt | 「把它放到受工作区限制的工具能读到的地方。」 |

两个工具都由函数插件注册，所以只要挂载了 bundle 行，它们就会出现在模型的工具列表里。

快速开始

1. Mount the plugin (a bundle row in the target profile)
dsh plugin --profile <name> add dsh-phone-inbox

然后，在收到手机附件的会话里：

inbox_list # the paths this session received
inbox_adopt { "path": "<the path from inbox_list>" }

inbox_adopt 返回 relativePath（例如 phone-inbox/材料.csv）。把这个传给受工作区限制的工具，比如 data_profile；只有接受任意绝对路径的消费方，才传原始宿主路径。

安装与卸载

dsh plugin --profile <name> add dsh-phone-inbox
dsh plugin --profile <name> remove dsh-phone-inbox

插件没有运行时依赖（dependencies 为空）。它唯一的 peer 是构建时所针对的宿主包；见 package.json 里的 peerDependencies 块。

兼容性

| 引擎 | 范围 |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| DSH | >=0.2.1-alpha.1 |

宿主 peer 范围是生态里通用的六子句 OR 范围（见 dsh-plugin-kit/data/peer-range.json）。宿主在预检阶段评估 peerDependencies，并会静默禁用范围不接纳当前运行版本的插件行，所以范围写错看起来就像「插件挂上了但什么都不做」。engines.dsh 只是声明性的——宿主不读它。

配置

每个字段都是可选的；表中列出的是默认值。带行内注释的相同取值见 cordis.patch.yml。

| 键 | 默认值 | 含义 |
| enabled | true | 总开关；设为 false 时不挂载任何服务，也不挂载任何工具。 |
| inboxDir | "" → ~/.dsh-wechat/tempfile | 桥接器存放入站媒体的目录。留空则沿用桥接器自己的默认值；如果桥接器的 storageDir 挪过位置，就设置它。 |
| maxItems | 5 | inbox_list 返回条目的上限。MVP 约定是「本会话最近几条」。 |
| provider | session | 由哪个已注册服务商来应答：session（本对话自己的消息）或 tempdir（session 再加上对 inboxDir 的扫描）。 |
| allowTempdirScan | false | 是否启用目录扫描。默认关闭，因为 inboxDir 是全局的。 |
| tempdirScanMaxItems | 5 | 一次扫描最多贡献的条目数。 |
| tempdirScanMaxAgeMs | 3600000 | 扫描文件的时间上限；设为 0 关闭该过滤。 |
| markers | 见下文 | 每种媒体类型对应的标记措辞，写成 RegExp 源。 |
| defaultSubdir | phone-inbox | inbox_adopt 写入的工作区子目录。 |
| restoreOriginalName | true | 用发送方恢复出的原始名称作为采纳后的文件名。 |
| writeChannel | auto | auto（文本走 fs 服务，其余走 node:fs）· fs（只用宿主 fs 服务）· node（直接写字节）。 |
| registerAttachment | false | 同时把采纳的字节注册为宿主持久附件。附件对象永远不会被垃圾回收。 |

markers 的默认措辞，按媒体类型列出 —— 每个值都是 RegExp 源，其第一个捕获组就是路径：

- image.path — 文件已保存到:\s(\S+)
- file.path — (?:文件已保存到|文件路径):\s(\S+)
- file.name — \[收到文件:\s([^\]\r\n]+)\]
- video.path — 文件已保存到:\s(\S+)

标记措辞是与桥接器之间的软约定：桥接器把路径写进正文，而正文可能随桥接器版本变化，且不作通知。这些模式之所以做成配置，正是为了让措辞变化只需改配置，而不必发插件版本。

工具与接口

inbox_list({
limit?: number, // default: config.maxItems
includeTempdir?: boolean, // only honoured when allowTempdirScan is true
})

返回 { ok: true, source, inboxDir, items[], attachments, deriveMessages, emptyReason?, emptyDetail?, tempdirScan, unresolvedAttachmentBlocks }，或 { ok: false, reason, detail }。

inbox_adopt({
path: string, // required: exactly what inbox_list reported
name?: string, // default: the recovered original name
subdir?: string, // default: config.defaultSubdir
channel?: 'auto' | 'fs' | 'node',
overwrite?: boolean, // default false: a duplicate gets a -1 suffix
register?: boolean, // default: config.registerAttachment
})

返回 { ok: true, item }，其中含 hostPath、workspacePath、relativePath、bytes、sha256、copyMethod、nameRestored、sourceLeafName，注册后还会含 attachmentId/attachmentHostPath；或返回 { ok: false, reason, detail }。
插件还会追加一段系统提示词（phone-inbox，顺序 320），让模型知道有这项能力，并订阅 session/event 来观察 user/message。这两者都不是正确性的必要条件：每次调用都以读取到的历史为准。

权限与数据

- 读取 inboxDir 和调用会话自己的消息，别的都不读。
- 写入只发生在会话工作区内（path.resolve 加一个能识别分隔符的包含性检查），而且只在调用 inbox_adopt 时发生。
- 拒绝不在 inboxDir 下的源路径、逃出工作区的 subdir，以及可能造成路径穿越的名称。path 参数来自模型，永远不可信。
- 不扫描共享收件箱目录，除非显式启用 allowTempdirScan；启用后，它贡献的每个条目都会打上 source: "tempdir"。
- 绝不静默覆盖。目标重名时会加 -1、-2……后缀，除非指定 overwrite: true。
- 不注册任何持久附件，除非你主动要求；注册会把字节复制进宿主的附件存储，而那里没有垃圾回收。

安全边界

- 读取不受宿主 fs 沙箱的围栏限制（围栏只包住 writeText/editText），所以本插件在复制的两端都自行做包含性检查。
- fs 写入通道走 ctx.fs.writeText，带会话级沙箱策略，因此限制型后端会像围栏 write 工具那样围栏它。node 从构造上就绕过这道围栏；它之所以存在，是因为 ctx.fs 没有字节写入 API。返回的 copyMethod 总会说明实际跑的是哪一个。
- auto 优先用 fs 服务处理文本，失败则回退到 node:fs；回退原因会被记录，通道会被上报，绝不靠暗示。
- 临时目录扫描无法证明文件属于哪个对话。所以它默认关闭，所以它的条目自带 source。
- 桥接的收件箱目录不保证私有（一次桥接重构移除了显式的 0o700/0o600 处理）。本插件不假设它私有。

已知限制

- 路径里含字面空格时会被截断，截断点在空格处，这是默认标记措辞导致的。捕获用的是 (\S+)，因为只有这样才能避免把桥接写在路径后面的那句话一起吞掉；桥接自己的临时文件名从不含空格。
- 图片和视频类型都上报为 file。 桥接对两者用同一套措辞，所以从文本里恢复不出类型；靠叶子名（image.png、video.mp4）区分。
- 图片或视频没有可恢复的原始名称。 桥接把它们存为 image.<ext> / video.mp4，措辞里不带原始名称。插件上报磁盘上的名称，并如实说明，而不是编一个。
- Windows 路径只能在 Windows 上用（POSIX 路径同理，只能在 POSIX 上用）。插件按运行平台的规则归一化分隔符。
- inbox_adopt 要求文件仍然存在。 bridge 从不清理 tempfile/，但没人保证它会一直留着。
- 没有跑过真实的微信流量。 验收脚本里写了哪些东西确实验证过，脚本与真实环境的边界看它的输出。

开发

pnpm install
pnpm run typecheck && pnpm test && pnpm run build \
&& pnpm run verify:self-contained && pnpm run verify:artifacts \
&& pnpm run check:readmes && pnpm run check:lockfile
pnpm run acceptance # end-to-end: probe -> list -> adopt -> dsh-data-quality

prepublishOnly 会重新跑一遍这道关卡，所以发布时不可能带上没构建或者已经漂移的工作树。

话题

dsh · dsh-plugin · deepseek-harness · cordis · wechat · inbox · attachment · phone

贡献者

PerryLink。

许可证

Apache-2.0。本仓库中每个文件都受它覆盖。