From 30b9370a43cc1dbe651b0b89d703446162ab9693 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?=
 =?UTF-8?q?=29?= <relakkes@gmail.com>
Date: Sat, 11 Apr 2026 16:11:01 +0800
Subject: [PATCH] docs(adapters): document IM attachment support

Lists inbound/outbound attachment coverage, local staging directory,
size limits, and the file/module additions from the im-attachments
feature branch.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 adapters/README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/adapters/README.md b/adapters/README.md
index 79e101fe..fbc41f74 100644
--- a/adapters/README.md
+++ b/adapters/README.md
@@ -53,9 +53,35 @@ bun test feishu/
 ```text
 adapters/
 ├── common/
+│   └── attachment/        # 跨平台附件工具(types / limits / store / image-watcher)
 ├── telegram/
+│   └── media.ts           # TelegramMediaService(grammy Bot API 封装)
 ├── feishu/
+│   ├── media.ts           # FeishuMediaService(@larksuiteoapi/node-sdk 封装)
+│   └── extract-payload.ts # 入站 im.message.receive_v1 事件解析
 ├── package.json
 ├── tsconfig.json
 └── README.md
 ```
+
+## 附件收发
+
+两个 Adapter 都支持双向图片/文件,和 Desktop 端走同一套 `AttachmentRef` 协议透传给主进程。
+
+**入站(用户 → Claude):**
+
+- 飞书: 图片(jpg/png/gif/webp/heic)、文档(doc/xls/ppt/pdf 等)、post 富文本里的 img/file 元素
+- Telegram: photo、document、video、audio、voice
+
+下载落地到 `~/.claude/im-downloads/{platform}/{sessionId}/`,24 小时后自动 GC(`.part` 孤文件 10 分钟超时)。大小限制:单张图 ≤10 MB、单个文件 ≤30 MB,超限直接拒收并在 IM 里提示。
+
+**出站(Claude → 用户):**
+
+Agent 流式文本里的 markdown 图片引用 `![alt](path|url|data:)` 会被 `ImageBlockWatcher` 识别、上传到 IM 平台,作为独立图片消息发出:
+
+- 飞书: `im.message.create(msg_type='image')` 单发(card 内嵌是后续优化)
+- Telegram: `bot.api.sendPhoto(InputFile)` 单发
+
+非图片类出站(Agent 产的 pdf/zip 等)暂不支持。
+
+设计细节: `docs/superpowers/specs/2026-04-11-im-attachment-support-design.md`。