feat: 附件只走个人存储 + 移动端工作区优化

## 附件链路（用户裁决 2026-11-13）
文件不再整份传进 Matrix，只直传用户个人存储（s3.fmode.cn），
事件 content.url 直接是云盘地址，容器自己下载。禁止经应用服务器/Matrix 中转。

- 新增 core/send-mode.ts：url 默认 / mxc 可回退（localStorage.fmode.sendMode，免发版）
- matrix-client.sendFileByUrl()：发 m.file，url=云盘地址，全程不 uploadContent
- chat.sendCloudFile()：单聊/群聊/群房间统一出口，按模式分流
- group-send：多容器房间复用同一次上传结果（原每房间各传一份）
- 删除废弃的 sendFileCard()（m.text + JSON，容器不解析）
- 修复 mediaHttpUrl()：SDK 的 mxcUrlToHttp('https://') 返回空串，
  原实现会让「url 模式」下历史回读的附件整个消失；实时流与历史流统一口径
- 地址校验收紧为云盘白名单（出站仅 s3.fmode.cn）

## 上传修复
- 中文文件名导致 OBS 403 SignatureDoesNotMatch：送签前转 ASCII（显示名仍为中文）
- 去掉 200MB 上限（云函数实测对 2GB 正常签名）
- 预签名仅 5 分钟：过期自动重签重试；补 240s 超时保护

## 会话与消息
- 新建会话不再显示「消息暂时没加载出来」：doStartBlank 清空消息时同步重置
  emptyReason；backfill 跳过的 blank 会话判 fresh
- 新建会话加速：waitAgentJoined 轮询 1s→200ms，超时 30s→8s；桌面端补「正在准备会话」
- 过滤容器「⚠️ Couldn't deliver the xxx attachment」噪声（实时+历史两处）

## 移动端
- 隐藏「群聊」筛选标签（与桌面端一致，可一行恢复）
- 工作区分组默认折叠、可点击展开（aria-expanded / 键盘可达 / 44px 触控区）
- 补「新建工作区」入口（行内表单 + 实时重名提示）
- 补工作区「⋯」菜单：重命名 / 删除（与侧边栏同口径，删除走二次确认）

## 验证
tsc ✅ / npm test 1727 SUCCESS / Playwright 实测移动端三处交互 ✅
容器侧（lj-test、kangshifu）端到端验证：App 发 m.file → 容器下载读到内容（DBHIT）

## 文档
新增《新容器复刻lj-test-完整配置手册》等 9 份容器改造文档；
同步 API 契约、容器接入指南与规范提示词。

Co-Authored-By: Claude Code <noreply@anthropic.com>

docs/00-tracking/操作追踪.md

@@ -7966,3 +7966,21 @@ URL 不会重复显示：`chat.service.ts:2349` 的 `stripLinks` 会把已提取
 | 未验证 | 真机实测（需用户复验）、降级后 PDF 功能完整性、4.10 与 6.4 的 API 差异 |
 | 关联文档 | [2026-11-13-真机预览问题-PDF崩溃与HTML白屏](2026-11-13-真机预览问题-PDF崩溃与HTML白屏.md) |
 
+
+## 2026-11-13 · 附件改为「个人 storage 直传 + 只发 S3 地址」
+
+| 项 | 内容 |
+|---|---|
+| 动作 | 按用户裁决（刘雨飏 11-13）重构用户发文件的出站链路，App 侧 + 容器侧任务书 |
+| 需求原话 | 「走用户的个人 storage 上传 s3 的附件」「一定不能经过 matrix 和任何我们的服务器节点」「只允许收发 cdn/obs 地址」「在线地址不能显示在发送的气泡卡片里，容器发回的链接转卡片展示，预览里有复制链接」 |
+| 改造前 | **双写**：OVS 直传 + `matrix-client.sendFile()` 把整份文件 `uploadContent` 进 Matrix 拿 `mxc://`（因为容器只认 mxc） |
+| 改造后 | **单写**：文件只进个人存储 → 发 `m.file`/`m.image`，`content.url = https://s3.fmode.cn/<key>`；新增 `sendFileByUrl()`，删除废弃的 `sendFileCard()` |
+| 关键实测 | ① 真实 homeserver 发非 mxc 的 `m.file`，`fetchRoomEvent` 读回 url **原样未改写**；② 容器 `hermes(uid 10000)` 对 `adapter.py` **NOT_WRITABLE**、**NO_SUDO**、`/opt/hermes/plugins/` 下无 `pre_gateway_dispatch` 钩子 → 容器侧只能由宿主机 root 打补丁 |
+| 补丁前基线 | `scripts/probe-url-attachment.mjs` 实测：容器收到 https 附件**无任何回复**（静默丢弃），确认顺序必须「先补丁、后切开关」 |
+| App 改动 | 新增 `core/send-mode.ts`（`url` 默认 / `mxc` 回退，`localStorage.fmode.sendMode`）；`matrix-client.service.ts` 新增 `sendFileByUrl()`、修实时流不读 cloudUrl 的老问题；`chat.service.ts` 新增 `sendCloudFile()`、`sendFileToAgent()` 增加 `cloudUrl` 参数；`group-send.service.ts` 各成员房间复用同一云盘地址；`groups.ts` 迁移并为群聊补超限预检；`upload-limits.ts` 上限按模式取（url=200MB / mxc=服务端值）；气泡图片与下载优先取 `cloudUrl` |
+| 容器侧 | 出任务书 + 可转发提示词，待宿主机 root 执行（三处：两处 mxc 校验放行 + 下载分支；含域名白名单防 SSRF） |
+| 验证 | `tsc --noEmit` ✅ / `npm test` **1718 SUCCESS** / 探测脚本补丁前基线 ❌（预期） |
+| 评审闭环 | 独立评审员报 4 严重 + 5 一般，已全部修复：①`mxcUrlToHttp('https://')` 实测返回**空串**→新增 `mediaHttpUrl()` 统一解析（历史/实时共用），否则 url 模式下历史附件整个消失；②地址校验收紧为云盘白名单；③`'mxc'` 回退模式下群聊不再强制先上云、群页按模式分流；④群派活上云失败立即中断（原来会半截投递）；⑤暂存项缓存已上传结果，重试不重复上传/登记；⑥附件空 body 不再把链接当正文渲染（评审 S4 地址泄漏）；⑦补测 4 组回归用例 |
+| 容器复核反馈 | 容器侧实机复核 v1 任务书，报 5 处问题，已全部吸收进 v2：aiohttp 依赖结论写反（裸 python3 无、venv 有）→改双后端+venv 解释器；`file-cloud.fmode.cn` 证书过期→白名单剔除（App 侧同步）；`/opt/hermes` 在 overlay 不持久→要求固化进镜像；`resp.read()` 大小上限失效→改流式计数；重定向绕过 SSRF→`allow_redirects=False` |
+| 未验证 | 补丁落地后的正向探测；宿主机位置与镜像固化方案；200MB 是否超出 OBS 单次 PUT 能力；真机双端手工走查 |
+| 关联文档 | [任务书](../03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md) · [发给宿主机提示词](../03-interface/发给宿主机-容器附件直读改造-提示词-20261113.md) · [API-契约](../03-interface/api/API-契约.md) §2.5 |

docs/03-interface/api/API-契约.md

@@ -230,11 +230,36 @@ interface MatrixProvisionResult {
  → uploadUrl(filename, mimeType, size)      [云函数 AlP56LCKFm]
  → fetch(uploadUrl, { method:'PUT', headers, body:file })   [OBS 直传,前端不经手密钥]
  → 得 { key, publicUrl }
- → Matrix 发文件卡:m.text,body = JSON.stringify({ kind:'file', name, size, mimeType, url })
+ → Matrix 发 m.file/m.image 事件:content.url = publicUrl(2026-11-13 起;旧形为 m.text + JSON,已废弃)
+```
+
+> 🔴 **附件发送形态已变更(2026-11-13 · 用户裁决)**:
+> · 文件**只**存在用户个人存储(`user/<userId>/chat/<yyyyMM>/`),**不再整份传进 Matrix 媒体库**;
+> · 事件仍是 `m.file`/`m.image`,但 `content.url` 直接填 `https://s3.fmode.cn/<key>`
+>   (实测 `matrix.fmode.cn` 接受非 mxc 的 url,读回原样);
+> · 不再发 `m.text` + JSON 文件卡(`sendFileCard` 已删除);
+> · 回退开关:`localStorage.fmode.sendMode = 'mxc'` → 恢复旧的双写行为(无需发版)。
+>
+> **前置条件**:容器侧 `adapter.py` 需放行 https 附件(见
+> `docs/03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md`);
+> 补丁落地前容器会**静默丢弃**该事件,用 `scripts/probe-url-attachment.mjs` 判定。
+
+**附件事件 content 形态(2026-11-13)`'url'` 模式**:
+
+```json
+{
+  "msgtype": "m.file",
+  "body": "方案.pdf",
+  "url": "https://s3.fmode.cn/user/<userId>/chat/202611/xxx-方案.pdf",
+  "info": { "mimetype": "application/pdf", "size": 1048576 },
+  "com.fmode.cloud_url": "https://s3.fmode.cn/user/<userId>/chat/202611/xxx-方案.pdf",
+  "m.relates_to": { "rel_type": "m.thread", "event_id": "<会话根>" }
+}
 ```
 
 **默认 headers 兜底**:`{ 'Content-Type': mimeType, 'x-obs-acl': 'public-read' }`
 **缺 `uploadUrl` 即抛错**(不得静默降级为本地 blob)。
+**单文件上限**:`'url'` 模式按云盘口径 200MB;`'mxc'` 回退模式按 Matrix `m.upload.size`(实测 32MB)。
 
 ### 2.6 kanban 任务域(FR-07b)— ⬜ **接收端未实现**
 

docs/03-interface/发给宿主机-容器附件直读改造-提示词-20261113.md

@@ -0,0 +1,182 @@
+# 发给宿主机维护方的提示词（可直接复制转发）
+
+---
+
+你负责 **agent-node-lj-test** 容器的宿主机维护。现在有一个已经确认的问题需要你改一处代码。
+
+## 背景
+
+App 侧（fmode-app-v2）用户发附件的链路已经改了：文件**只直传用户个人存储 OBS（s3.fmode.cn）**，然后发一条 `m.file` / `m.image` 事件，`content.url` 直接就是 `https://s3.fmode.cn/...` 这样的地址，**文件本体不再进 Matrix 媒体库**。这是产品方的硬性要求：「禁止通过应用服务器传附件，只允许收发 cdn/obs 地址」。
+
+但容器侧现在的代码会**拒收**这种事件，表现为：用户发文件，容器完全没反应（日志里有一行 `Rejecting inbound media ... with non-MXC URL`）。
+
+## 我这边已实测确认的事实（2026-11-13 在容器内执行）
+
+```
+whoami; id          → hermes, uid=10000
+ls -ld .../adapter.py → -rw-r--r-- root root
+test -w .../adapter.py → NOT_WRITABLE
+command -v sudo     → NO_SUDO
+```
+
+所以容器里的 `hermes` 用户改不了，**必须由你在宿主机用 root 改**。
+
+## 需要改的文件
+
+`/opt/hermes/plugins/platforms/matrix/adapter.py`
+
+## 三处改动
+
+**① 放行 https 的附件地址（`_handle_media_message` 里）**
+
+搜索：
+```python
+        if url and not str(url).startswith("mxc://"):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)
+            return
+```
+改成：
+```python
+        if url and not _is_allowed_media_url(str(url)):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)
+            return
+```
+
+**② 加密媒体的 `file.url` 同样放行**
+
+搜索：
+```python
+            if url and not str(url).startswith("mxc://"):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)
+                return
+```
+改成：
+```python
+            if url and not _is_allowed_media_url(str(url)):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)
+                return
+```
+
+**③ 下载分支（`_download_and_cache_media` 第一行）**
+
+把这一行：
+```python
+        file_bytes = await self._client.download_media(ContentURI(url))
+```
+改成：
+```python
+        if str(url).startswith("https://"):
+            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media
+            file_bytes = await self._fetch_http_media(url, event_id)
+            if file_bytes is None:
+                return None
+        else:
+            file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+**⑤ 新增 `_fetch_http_media` 方法**（同一个 class 内，放在 `_download_and_cache_media` 前面）
+
+```python
+    async def _fetch_http_media(self, url: str, event_id: str):
+        \"\"\"Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。\"\"\"
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=600)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=600, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+```
+
+> 关键点（每一处都对应一次实测踩坑）：
+> · 双后端：裸 python3 没有 aiohttp，venv 里有 → 先试 aiohttp，`ImportError` 回退 httpx
+> · `allow_redirects=False`：否则白名单域 302 到内网即绕过 SSRF 校验
+> · 流式累加计数：不能用 `content_length` 判大小，chunked 时它是 `None`，上限会失效
+
+**④ 在模块顶层（`class` 定义之前）新增一个函数（只需一次）**
+
+```python
+# Fmode: 允许容器直接拉取的附件域名。防 SSRF：只放行这一个。
+# 注意：file-cloud.fmode.cn 证书已过期（2026-11-13 实测），不要加回来。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+```
+
+## 上线前提（🔴 务必先确认）
+
+`adapter.py` 位于容器 **overlay 根分区**，**不在** `/opt/data` 持久卷 ——
+**容器重建后补丁会丢失**。所以除了改文件，还必须把补丁**固化进镜像**
+（Dockerfile 构建时打补丁，或把打过补丁的文件放进镜像层），否则下次重建
+附件会重新静默丢失，日志里只会出现 `non-allowed URL`，很难联想到是补丁没了。
+
+## 执行纪律（请严格遵守）
+
+1. **改前先备份**：`cp -p adapter.py adapter.py.bak.$(date +%Y%m%d%H%M)`（同目录）；
+2. 改完 **用 venv 的解释器**做语法自检：`/opt/hermes/.venv/bin/python -m py_compile adapter.py`
+   （🔴 **不要用裸 `python3`**：容器里裸解释器没有 aiohttp/httpx/mautrix，会误判依赖缺失）；
+3. 重启 gateway；
+4. **必须回读验证**：`grep -c '_is_allowed_media_url' adapter.py` 结果 **≥ 3**，并把这条命令的原始输出贴回来。
+
+> 上次的问题就是「口头说改完了、实际没落地」，所以这次**只认命令原始输出**，不接受文字描述。
+
+## 请一并回答
+
+1. 你用的 root 通道是什么（docker exec / ssh / 其它）？
+2. `/opt/hermes` 是不是持久卷/bind mount？**如果容器重建会还原，请把补丁固化进镜像**，否则下次重建后又失效。
+3. gateway 的重启方式确认（`s6-svc -r /run/s6/services/main-hermes` 是否可用）？
+4. **`agent-node-lj-test` 在哪台宿主机**？
+5. 补丁固化进镜像的方案确认（overlay 不持久，见上）。
+
+> App 侧只发 `https://s3.fmode.cn/...` 一个域名，无签名临时域、无 CDN 别名 ——
+> 白名单只放这一个即可。
+
+完整版在：`docs/03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md`

docs/03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md

@@ -0,0 +1,357 @@
+# 容器侧改造任务书：附件直读 S3 地址（不经 Matrix 中转）
+
+> 下发对象：容器 `agent-node-lj-test` 的**宿主机维护方**（需 root）
+> 下发日期：2026-11-13
+> 前置事实来源：2026-11-13 直连容器实测（见本文件 §1），非推测
+> 🔴 **v2（2026-11-13 复核后修订）**：容器侧已实机复核 v1，本版吸收 5 处修正（§八），
+> 其中 3 处不改会导致「上线后仍收不到附件」或「补丁神秘消失」。
+> 交付物：`/opt/data/work/matrix-media-patch.tar.gz`（`patchmediaurl.py` 支持 `--check/--apply/--revert`）。
+
+---
+
+## 一、为什么要改
+
+App（fmode-app-v2）这边，用户发送的文件已经改为：**只直传用户个人存储（OBS `s3.fmode.cn`）→ 发 `m.file` 事件，`content.url` 就是 https 云地址**，不再把文件整份传进 Matrix 媒体库。
+
+用户裁决原话：
+
+> 一定不能经过 matrix 和任何我们的服务器节点。
+> 禁止通过应用服务器传附件，只允许收发 cdn/obs 地址。
+
+但容器侧现在**会拒收**这种事件。改造完成后：
+
+| 事件形态 | 改造前 | 改造后 |
+|---|---|---|
+| `content.url = mxc://...` | ✅ 正常 | ✅ 正常（保持兼容） |
+| `content.url = https://s3.fmode.cn/...` | ❌ **静默丢弃** | ✅ 下载到本地缓存，正常处理 |
+
+---
+
+## 二、实测确认的现状（2026-11-13，容器内实际执行）
+
+```
+$ whoami; id
+hermes
+uid=10000(hermes) gid=10000(hermes) groups=10000(hermes)
+
+$ ls -ld /opt/hermes/plugins/platforms/matrix/adapter.py
+-rw-r--r-- 1 root root 170062 Sep 19 06:15 /opt/hermes/plugins/platforms/matrix/adapter.py
+
+$ test -w /opt/hermes/plugins/platforms/matrix/adapter.py && echo WRITABLE || echo NOT_WRITABLE
+NOT_WRITABLE
+
+$ command -v sudo
+NO_SUDO
+```
+
+- `/opt/hermes/plugins/` 下 **没有** `pre_gateway_dispatch` 之类的入站钩子（全目录 0 命中），插件层绕不过去 → **只能改 `adapter.py` 本体**，且必须 root 执行。
+- 目标文件：`/opt/hermes/plugins/platforms/matrix/adapter.py`
+
+### 关键代码位置（当前版本）
+
+| 行 | 内容 |
+|---|---|
+| 2002-2003 | 分发入口：`m.image/m.audio/m.video/m.file` → `_handle_media_message` |
+| **2134-2136** | `url = source_content.get("url", "")` 后：`if url and not str(url).startswith("mxc://"): logger.warning(...); return` ← **拒收点 1** |
+| **2155-2157** | 加密媒体 `file.url` 有同样的 `startswith("mxc://")` 检查 ← **拒收点 2** |
+| 2196-2235 | `_download_and_cache_media()`：唯一一行 `file_bytes = await self._client.download_media(ContentURI(url))`，之后按 msg_type 调 `cache_image_from_bytes_async` / `cache_audio_from_bytes_async` / `cache_document_from_bytes_async` |
+| 2832 | `if not mxc_url.startswith("mxc://")`（无关路径，**不要动**） |
+
+---
+
+## 三、补丁内容（三处，全部用 `startswith` 字符串定位，行号仅作参考）
+
+### 补丁 1 · 放行 https（主 url）
+
+搜索原文：
+
+```python
+        if url and not str(url).startswith("mxc://"):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)
+            return
+```
+
+改为：
+
+```python
+        if url and not _is_allowed_media_url(str(url)):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)
+            return
+```
+
+### 补丁 2 · 放行 https（加密媒体 file.url）
+
+搜索原文：
+
+```python
+            if url and not str(url).startswith("mxc://"):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)
+                return
+```
+
+改为：
+
+```python
+            if url and not _is_allowed_media_url(str(url)):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)
+                return
+```
+
+### 补丁 3 · 下载分支
+
+搜索原文（`_download_and_cache_media` 内第一行）：
+
+```python
+        file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+改为：
+
+```python
+        if str(url).startswith("https://"):
+            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media
+            file_bytes = await self._fetch_http_media(url, event_id)
+            if file_bytes is None:
+                return None
+        else:
+            file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+> 🔴 **v2 修正（复核实测）**：v1 写的「aiohttp 必然在依赖里」是**错的**。
+> 容器里有两个解释器：
+> - `/usr/bin/python3.13`（**裸** python3）：aiohttp / httpx / mautrix **都没有**
+> - `/opt/hermes/.venv`（gateway 实际使用）：aiohttp 3.14.3、httpx 0.28.1、mautrix 0.21.1 **都有**
+>
+> 所以**不要**用裸 `python3 -m py_compile` 验证依赖，必须用 venv 解释器：
+> `/opt/hermes/.venv/bin/python -m py_compile adapter.py`。
+> 下载实现改为「先 aiohttp，失败再回退 httpx」双保险。
+> **为什么在补丁里再判一次大小**：https 分支绕过了原来的 `_download_and_cache_media` 之外的 `_max_media_bytes` 预检，必须补上，防止有人塞超大链接把容器磁盘撑爆。
+
+### 补丁 4 · 新增白名单函数（放在模块级，`_is_allowed_media_url` 只定义一次）
+
+放在 `class` 定义之前的模块顶层（与现有其它模块级函数同级）：
+
+```python
+# Fmode: 允许容器直接拉取的附件域名（个人存储）。防 SSRF：只放行这三个。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+```
+
+---
+
+### 补丁 5 · 新增下载方法 `_fetch_http_media`（放在 `_download_and_cache_media` 前面，同一 class 内）
+
+> 🔴 **v2 修正**：v1 直接用 `resp.read()` + `content_length` 判大小 —— 若响应是 chunked
+> 或上游不返回 `Content-Length`，该值就是 `None`，**上限完全失效**，容器磁盘可能被打满。
+> v1 也没禁重定向 —— 白名单域名一旦 302 到内网，SSRF 校验就被绕过。
+
+```python
+    async def _fetch_http_media(self, url: str, event_id: str):
+        """Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。"""
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+        timeout_total = 600
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=timeout_total)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=timeout_total, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+```
+
+---
+
+## 四、执行步骤（宿主机 root）
+
+```bash
+# 0. 进容器 root shell（按实际部署方式二选一）
+#    docker exec -u root -it agent-node-lj-test bash
+#    或：nsenter / kubectl exec / 宿主机 vm 内直接操作
+
+T=/opt/hermes/plugins/platforms/matrix/adapter.py
+cp -p "$T" "$T.bak.$(date +%Y%m%d%H%M)"     # 同目录备份
+
+# 1. 打补丁（用 python 精确替换，避免 sed 转义踩坑）
+python3 - <<'PY'
+import io
+p = '/opt/hermes/plugins/platforms/matrix/adapter.py'
+s = io.open(p, encoding='utf-8').read()
+
+# 补丁 4：插入白名单函数（只插一次）
+if '_is_allowed_media_url' not in s:
+    anchor = '\n\nclass '
+    i = s.index(anchor)
+    s = s[:i] + '''
+# Fmode: 允许容器直接拉取的附件域名（个人存储）。防 SSRF：只放行这两个。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+''' + s[i:]
+
+# 补丁 1 / 2
+a1 = '        if url and not str(url).startswith("mxc://"):\n            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)\n            return'
+b1 = '        if url and not _is_allowed_media_url(str(url)):\n            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)\n            return'
+a2 = '            if url and not str(url).startswith("mxc://"):\n                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)\n                return'
+b2 = '            if url and not _is_allowed_media_url(str(url)):\n                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)\n                return'
+# 补丁 3
+a3 = '        file_bytes = await self._client.download_media(ContentURI(url))'
+b3 = '''        if str(url).startswith("https://"):
+            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media
+            file_bytes = await self._fetch_http_media(url, event_id)
+            if file_bytes is None:
+                return None
+        else:
+            file_bytes = await self._client.download_media(ContentURI(url))'''
+
+for a, b, name in ((a1, b1, 'p1'), (a2, b2, 'p2'), (a3, b3, 'p3')):
+    n = s.count(a)
+    if n != 1:
+        raise SystemExit(f'{name} 匹配 {n} 次，与预期 1 次不符，已中止（文件未写入）')
+    s = s.replace(a, b)
+
+io.open(p, 'w', encoding='utf-8').write(s)
+print('patched ok')
+PY
+
+# 2. 语法自检（必做）
+/opt/hermes/.venv/bin/python -m py_compile "$T" && echo SYNTAX_OK
+
+# 3. 确认落地
+grep -n '_is_allowed_media_url\|HTTP media fetch' "$T"
+
+# 4. 重启 gateway（重启方式按容器实际情况选一种）
+s6-svc -r /run/s6/services/main-hermes
+# 或者： pkill -f hermes-gateway  （先 ps aux | grep -i hermes 确认进程名）
+```
+
+### 🔴 强制要求：回读验证，不接受口头「改完了」
+
+历史上容器曾口头回答「改完了」，实际回读发现改动根本没落地。所以：
+
+1. 重启后执行 `grep -c '_is_allowed_media_url' /opt/hermes/plugins/platforms/matrix/adapter.py`，**必须 ≥ 3**；
+2. 跑 App 侧探测脚本（见 §六），由 App 侧确认容器真的收到了 https 附件；
+3. 把上述命令的**原始输出**贴回来。
+
+### 持久化（必答）
+
+容器如果是「镜像重建式」部署，overlay 在**重建**时会还原，补丁会丢失。请确认：
+
+- [ ] `/opt/hermes` 是否为持久卷 / bind mount？→ 是则改完即可
+- [ ] 若会还原 → 需把补丁固化进镜像（Dockerfile 加 patch 步骤），否则下次重建后又会静默丢附件
+
+---
+
+## 五、改造后行为不变的部分
+
+- `m.text` / `m.notice` 的处理完全不变；
+- `mxc://` 附件完全不变（存量历史消息照常可读）；
+- 容器**产出**文件上云的流程不变（仍走 `AlP56LCKFm` → PUT → `THXAOGKiPK` → 正文贴链接）；
+- 入站 `@提及` / 房间白名单 gate **必须在下载之前**执行（现有代码已是如此，不要调换顺序）。
+
+---
+
+## 六、验证
+
+App 侧探测脚本：`node scripts/probe-url-attachment.mjs`（补丁前跑一次应「无响应」，补丁后应收到容器回复并描述出文件内容）。
+
+人工核对点：
+
+1. 容器收到 https 附件 → 本地有缓存文件 → 在回复里能正确描述/处理该文件；
+2. 非白名单域名（如 `https://evil.example.com/x`）仍被拒（日志 `Rejecting inbound media ... non-allowed URL`）；
+3. 发 `mxc://` 附件仍正常（回退兼容）。
+
+---
+
+## 七、待确认（执行前请回复）
+
+1. 宿主机 root 通道是什么（docker exec / ssh / 其它）？
+2. `/opt/hermes` 是否持久化（见 §四 持久化）？
+3. 当前 gateway 的重启方式确认（`s6-svc` 是否可用）。
+
+
+---
+
+## 八、v2 修订清单（容器侧实机复核 2026-11-13 反馈）
+
+| # | v1 的问题 | 实测证据 | v2 处置 |
+|---|---|---|---|
+| 1 | 断言「aiohttp 必然在依赖里」，据此不用 httpx | 裸 `/usr/bin/python3.13`：aiohttp/httpx/mautrix **全都没有**；`/opt/hermes/.venv`：aiohttp 3.14.3、httpx 0.28.1、mautrix 0.21.1 都有 | 改为「先 aiohttp，ImportError 回退 httpx」；语法检查/任何验证**一律用 `/opt/hermes/.venv/bin/python`**，否则会误判依赖缺失、装错解释器 |
+| 2 | 白名单含 `file-cloud.fmode.cn` | 该域 TLS 证书已过期（CN=fmode.cn，Let's Encrypt） | **剔除**，只留 `s3.fmode.cn`；App 侧出站白名单同步剔除（`core/s3-link.ts` 的 `SENDABLE_HOSTS`） |
+| 3 | 未回答持久化 | `adapter.py` 在 overlay 根分区，**不在** `/opt/data` 持久卷 | 容器重建即丢补丁 → **必须固化进镜像**，否则下次重建后附件静默丢失，日志只有 non-allowed URL |
+| 4 | `resp.read()` + `content_length` 判大小 | chunked / 无 Content-Length 时该值为 `None`，上限完全失效 | 改**流式累加计数**，超限立即断流 |
+| 5 | `session.get()` 默认跟随重定向 | 白名单域 302 到内网即绕过 SSRF 校验 | 加 `allow_redirects=False`（httpx 同理 `follow_redirects=False`） |
+
+### 容器侧已完成的实测（可直接引用）
+
+| 项 | 结果 |
+|---|---|
+| 幂等性 | 连跑 3 次 md5 稳定；修复了「第二次执行截断方法体 → IndentationError」的幂等 bug |
+| SSRF 白名单 | 13 个用例全过（后缀伪造、query 伪造、userinfo 伪造、子域、协议相对，全部拒绝） |
+| 真实下载 | 28977B 文件内容正确 |
+| 404 / 超大 / 非白名单域 / 证书过期域 | 全部正确拒绝且不抛异常 |
+| 语法回滚 | 语法检查失败时自动还原 |
+
+### 待宿主机确认
+
+1. **`agent-node-lj-test` 在哪台宿主机** —— 确认后才能执行。
+2. App 侧 `content.url` 的域名范围 —— **已答：只有 `s3.fmode.cn`**，无签名临时域、无 CDN 别名。

docs/03-interface/容器接入完整指南-v2-20261111.md

@@ -105,8 +105,8 @@ node scripts/matrix-check.mjs <agentId>   # 本仓库只读体检，能看出缺
 | 项 | 事实 | 依据 |
 |---|---|---|
 | 判定「是给我的」 | DM 都响应；群聊按 `MATRIX_REQUIRE_MENTION` + `MATRIX_ALLOWED_USERS` | 容器侧 `adapter.py` 策略段 |
-| 文件 | `content.url` 必须是 **`mxc://`**，用 bot 自己的登录态下载 | 实测：https 塞进 `url` 会被**静默丢弃** |
-| 大小 | App 侧限制 20MB（`core/upload-limits.ts`） | — |
+| 文件 | `content.url` 为 **`mxc://`（存量）或 `https://s3.fmode.cn/...`（2026-11-13 起）** | mxc 用 bot 登录态下载;https 需 adapter 补丁放行,见 §4.1 |
+| 大小 | App 侧 `'url'` 模式 200MB（云盘口径）;`'mxc'` 回退模式按 `m.upload.size`（32MB） | `core/upload-limits.ts` |
 
 ### 3.2 回消息的格式约束
 
@@ -143,8 +143,14 @@ node scripts/matrix-check.mjs <agentId>   # 本仓库只读体检，能看出缺
 
 ### 4.1 用户发来的文件
 
-App **双写**：Matrix 存 `mxc://`（给容器读）+ 云盘存 https（给 App 长期看）。
-容器只需读 `content.url` 的 `mxc://`。
+> 🔴 **2026-11-13 变更**：App **不再双写**。用户裁决「禁止通过应用服务器传附件，只允许收发 cdn/obs 地址」，
+> 文件只进用户个人存储，事件 `content.url` 直接是 `https://s3.fmode.cn/<key>`。
+>
+> **容器侧必须打补丁**才能收到（默认会静默丢弃非 mxc 的 url）：
+> `docs/03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md`。
+> 补丁落地前，App 可用 `localStorage.fmode.sendMode='mxc'` 回退到旧的双写模式。
+>
+> 验证：`node scripts/probe-url-attachment.mjs`（容器能读出文件内容 = 补丁生效）。
 
 ### 4.2 容器产出文件
 

docs/03-interface/容器接入规范提示词-20261111.md

@@ -23,11 +23,11 @@
 
 | 项 | 要求 |
 |---|---|
-| 附件字段 | `content.url` 必须是 `mxc://...` |
-| ❌ 禁止 | 把 `https://` 塞进 `url` 字段（**静默丢弃，无报错**） |
-| 大小上限 | 20MB（App 侧同口径，`upload-limits.ts`） |
+| 附件字段 | `content.url` 为 `mxc://...`（存量）或 `https://s3.fmode.cn/...`（2026-11-13 起） |
+| ⚠️ 2026-11-13 变更 | 上面的「https 会被静默丢弃」是**改造前**的实测结论。已下发补丁放行 s3 白名单域名，见 `容器侧改造-附件直读S3地址-任务书-20261113.md`；补丁未落地前 App 用 `localStorage.fmode.sendMode='mxc'` 回退双写 |
+| 大小上限 | `'url'` 模式 200MB / `'mxc'` 回退模式按 Matrix `m.upload.size`（`upload-limits.ts`） |
 
-**App 侧对应行为**：用户发文件时 App 会**双写** —— Matrix 存 `mxc://`（给容器读）+ 云盘存 https（给 App 长期查看）。
+**App 侧对应行为（2026-11-13 起）**：用户发文件时 App **不再双写**，只传个人存储并发送 `content.url = https://s3.fmode.cn/...`。
 
 ---
 
@@ -271,7 +271,7 @@ API_SERVER_KEY
 ## 六、检查清单（新容器接入前逐项确认）
 
 ### 收文件
-- [ ] 附件走 `m.file` / `m.image` + `content.url = mxc://...`
+- [ ] 附件走 `m.file` / `m.image`，`content.url` 为 mxc:// 或 https://s3.fmode.cn/...（后者需补丁）
 - [ ] 用 bot 自己的登录态下载媒体
 - [ ] 单文件 ≤ 20MB
 

docs/03-interface/宿主机-kangshifu开放写权限指令-20261113.md

@@ -0,0 +1,194 @@
+# 宿主机操作指令：为容器 `agent-node-kangshifu` 开放 adapter.py 写权限
+
+> 日期：2026-11-13
+> 执行方：宿主机维护方（需 root）
+> 预计耗时：1 分钟
+> 风险：低（仅改一个文件的属主，容器内改动有备份和 `--revert` 兜底）
+
+---
+
+## 一、背景
+
+`agent-node-kangshifu` 已完成「附件直读 S3 链接」改造的**代码编写与验证**，但卡在最后一步：写入文件权限不足。
+
+容器内实测：
+
+```
+$ ls -la /opt/hermes/plugins/platforms/matrix/adapter.py
+-rw-r--r-- 1 root root 169491 Sep 19 00:36 .../adapter.py
+
+$ whoami; id
+hermes
+uid=10000(hermes) gid=10000(hermes) groups=10000(hermes)
+
+$ --apply
+PermissionError: [Errno 13] Permission denied: '/opt/hermes/plugins/platforms/matrix/adapter.py'
+```
+
+容器内 **无 sudo**，`/opt/hermes` 归 root 所有、644 权限。
+
+---
+
+## 二、目标容器指纹（⚠️ 务必先核对）
+
+> 🔴 **命名陷阱**：`agent-node-kangshifu` 是 **AGENT_ID**，不一定是 docker 容器名。
+> 之前有过「按 docker 名找错容器、连续改错两轮」的教训。
+
+### 2.1 在容器内核对（先跑这个）
+
+```bash
+docker exec agent-node-kangshifu sh -c '
+echo "AGENT_ID    = $(grep -E "^AGENT_ID=" /opt/data/.env | cut -d= -f2-)"
+echo "MATRIX_USER = $(grep -E "^MATRIX_USER_ID=" /opt/data/.env | cut -d= -f2-)"
+echo "adapter.md5 = $(md5sum /opt/hermes/plugins/platforms/matrix/adapter.py | cut -d" " -f1)"
+echo "adapter.size= $(stat -c %s /opt/hermes/plugins/platforms/matrix/adapter.py)"
+'
+```
+
+**期望值**：
+
+| 项 | 期望 |
+|---|---|
+| `AGENT_ID` | `agent-node-kangshifu` |
+| `MATRIX_USER` | `@edzb0hg93a:fmode.cn` |
+| `adapter.md5` | `373079feddfd98726ef4073a2e52b175` |
+| `adapter.size` | `169491` |
+
+**四项全对才是目标容器。** 有一项不符 → 停下来，把原始输出贴回 App 侧确认。
+
+### 2.2 在宿主机反查（如果上一步容器名不对）
+
+```bash
+for c in $(docker ps -q); do
+  v=$(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' $c 2>/dev/null | grep '^AGENT_ID=')
+  [ -n "$v" ] && echo "$(docker inspect -f '{{.Name}}' $c)  $v"
+done | grep kangshifu
+```
+
+---
+
+## 三、执行改动
+
+### 3.1 先备份（宿主机侧再存一份，双保险）
+
+```bash
+# 宿主机上的数据卷路径（已实测确认）
+HOST_DATA=/opt/fmode-containers/agent-node-kangshifu/data
+
+mkdir -p "$HOST_DATA/backups"
+docker cp agent-node-kangshifu:/opt/hermes/plugins/platforms/matrix/adapter.py \
+  "$HOST_DATA/backups/adapter.py.bak-host-$(date +%Y%m%d%H%M)"
+ls -la "$HOST_DATA/backups/"
+```
+
+> ✅ 这一步很重要：容器内的备份也在 overlay 层，**不持久**。宿主机这份是唯一能跨重建保住的。
+
+### 3.2 放开写权限
+
+```bash
+docker exec -u root agent-node-kangshifu \
+  chown hermes:hermes /opt/hermes/plugins/platforms/matrix/adapter.py
+
+docker exec agent-node-kangshifu \
+  ls -la /opt/hermes/plugins/platforms/matrix/adapter.py
+```
+
+**期望输出**：`-rw-r--r-- 1 hermes hermes 169491 ...`（属主从 `root root` 变为 `hermes hermes`）
+
+### 3.3 通知容器继续
+
+改完后，**在 App 侧告诉容器「权限已开，可以 --apply 了」**，由容器自行执行：
+
+```
+--apply → 三重回读验证 → s6-svc -r /run/service/gateway-default 重启
+```
+
+---
+
+## 四、改完之后恢复权限（重要，防止长期敞着）
+
+等 App 侧端到端验证通过后，把属主改回 root：
+
+```bash
+docker exec -u root agent-node-kangshifu \
+  chown root:root /opt/hermes/plugins/platforms/matrix/adapter.py
+```
+
+⚠️ **但要注意**：改回 root 后，若将来还需要再改（如升级补丁），又要重新放开。
+建议：**验证通过后先不要改回**，等确认稳定（观察 1-2 天）再改回。
+
+---
+
+## 五、🔴 持久化问题（必须知道）
+
+### 5.1 实测结论
+
+```
+$ findmnt -T /
+/    overlay overlay rw,... upperdir=/var/lib/docker/overlay2/...
+
+$ findmnt -T /opt/data
+/opt/data /dev/nvme0n1p2[/opt/fmode-containers/agent-node-kangshifu/data] ext4
+```
+
+| 路径 | 类型 | 容器重启 | 容器重建 (`docker rm` + run) | 镜像升级 |
+|---|---|---|---|---|
+| `/opt/hermes/plugins/platforms/matrix/adapter.py` | **overlay 可写层** | ✅ 保留 | ❌ **丢失** | ❌ **丢失** |
+| `/opt/data/plugins/` | ext4 持久卷 | ✅ 保留 | ✅ 保留 | ✅ 保留 |
+| `/opt/data/backups/` | ext4 持久卷 | ✅ 保留 | ✅ 保留 | ✅ 保留 |
+
+### 5.2 对本次改造的影响
+
+| 改动 | 持久性 |
+|---|---|
+| `adapter.py` 的 https 放行补丁 | ⚠️ **仅 `docker restart` 保留，重建即丢** |
+| 出站 MEDIA 剥离（`plugin-deliverable-inject`） | ✅ 天然持久（在 `/opt/data`） |
+
+**结论：网关重启不影响，容器重建会丢失入站补丁。**
+
+### 5.3 若需要跨重建保留（可选，建议做）
+
+参考 `agent-node-lj-test` 已验证的方案：在 `/opt/data` 放 `entry.sh`，重建容器时作为 `--entrypoint`，先幂等打补丁再 `exec` 原入口：
+
+```
+/opt/data/.fmode-media-patch/
+├── entry.sh          # 先跑 patch_spec.py --apply（幂等：已打过就跳过），再 exec 原入口
+├── patch_spec.py     # 支持 --check / --apply / --revert
+└── media-patch-README.md
+```
+
+重建命令示例（**lj-test 上实测可行**）：
+
+```bash
+docker run -d --name <name> \
+  --entrypoint /opt/data/.fmode-media-patch/entry.sh \
+  ... 其余原参数不变 ...
+  fmode/agent-node:0.21.3 gateway run
+```
+
+---
+
+## 六、回滚
+
+若改完出现问题：
+
+```bash
+# 容器内
+/opt/data/patches/matrix-inbound/patch_inbound_v2.py --revert
+
+# 或宿主机直接用备份覆盖
+docker cp /opt/fmode-containers/agent-node-kangshifu/data/backups/adapter.py.bak-host-<时间戳> \
+  agent-node-kangshifu:/opt/hermes/plugins/platforms/matrix/adapter.py
+docker exec -u root agent-node-kangshifu s6-svc -r /run/service/gateway-default
+```
+
+---
+
+## 七、回交内容
+
+1. §2.1 指纹核对的 **原始输出**（四项）
+2. §3.1 备份文件列表
+3. §3.2 `chown` 后的 `ls -la` 输出
+4. 是否已执行 §5.3 的持久化方案（是/否/计划中）
+
+**不要回「已完成」，要贴命令原始输出。**

docs/03-interface/新容器复刻lj-test-完整配置手册-20261113.md

@@ -0,0 +1,878 @@
+# 新容器一键复刻 lj-test：文件收发完整配置手册
+
+> 版本：v1.0 · 2026-11-13
+> 参考实现：`agent-node-lj-test`（`@zgdcmgnqcd:fmode.cn`，**端到端验证通过**）
+> 适用：任意新建的 Hermes 容器
+> 目标：照本文档逐节执行，即可获得与 lj-test **完全一致**的文件收发行为
+
+---
+
+## 〇、先建立整体认知
+
+### 0.1 我们要达成什么
+
+| 方向 | 行为 |
+|---|---|
+| **入站**（用户 → 容器） | App 只发一条 `m.file` 事件，`content.url` = `https://s3.fmode.cn/...`。**文件本体不进 Matrix**。容器收到后用**自己的网络**去 S3 下载，落本地缓存给 Agent 读 |
+| **出站**（容器 → 用户） | 容器产出文件 → 上传 S3 → 在正文写 `**已上云（可直接下载）**` + https 链接。**禁止**用 Matrix 回发文件本体（`MEDIA:` 标记会被剥离） |
+
+### 0.2 三个硬约束（违反任意一条都会失效）
+
+1. **`/opt/hermes` 是 root 所有、在 overlay 根分区** → 改它需要 root，且**容器重建会丢失**
+2. **`/opt/data` 是唯一持久卷** → 所有能跨重建保留的东西必须放这里
+3. **`transform_llm_output` 钩子是「first non-None wins」** → 两个插件无法串联，**必须合并进同一个回调**
+
+### 0.3 一张图看清改动落点
+
+```
+┌─────────────────────────── 容器 ───────────────────────────┐
+│                                                            │
+│  /opt/hermes/...（overlay，重建即丢）        ← 需要 root 改  │
+│   └─ adapter.py                                            │
+│       ├─ _is_allowed_media_url()   [新增]                  │
+│       ├─ _fetch_http_media()       [新增]                  │
+│       ├─ _handle_media_message     [改 2 处判断]            │
+│       └─ _download_and_cache_media [改 1 处分流]            │
+│                                                            │
+│  /opt/data/...（持久卷，长期有效）        ← hermes 即可改   │
+│   ├─ plugins/plugin-deliverable-inject/                    │
+│   │   ├─ __init__.py     [改：步骤 0 调 media_strip]        │
+│   │   └─ media_strip.py  [新增]                            │
+│   └─ .fmode-media-patch/  [新增：持久化兜底]                 │
+│       ├─ entry.sh                                          │
+│       ├─ patch_spec.py                                     │
+│       └── README.md                                        │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 一、准备阶段（10 分钟，全部只读）
+
+### 1.1 记录容器指纹
+
+```bash
+cat > /tmp/fingerprint.txt <<'EOF'
+AGENT_ID    = $(grep -E '^AGENT_ID=' /opt/data/.env | cut -d= -f2-)
+MATRIX_USER = $(grep -E '^MATRIX_USER_ID=' /opt/data/.env | cut -d= -f2-)
+hostname    = $(hostname)
+uid         = $(id -u)($(id -un))
+EOF
+sh /tmp/fingerprint.txt
+```
+
+把输出记下来。**后续所有宿主机操作都用 `AGENT_ID` 定位，不要用 docker 容器名。**
+
+> 🔴 真实教训：曾出现「docker 名为 `agent-node-lj-test` 的容器 `AGENT_ID` 为空，真正的目标容器 docker 名是 `agent-node-u19170119836`」，按名字找连改错两轮。
+
+### 1.2 探明运行环境
+
+```bash
+echo "=== 解释器 ==="
+ls -l /opt/hermes/.venv/bin/python*
+/opt/hermes/.venv/bin/python -c "import aiohttp; print('aiohttp', aiohttp.__version__)" 2>&1
+/opt/hermes/.venv/bin/python -c "import httpx; print('httpx', httpx.__version__)" 2>&1
+
+echo "=== s6 服务名（决定重启命令） ==="
+pgrep -af s6-supervise
+
+echo "=== 分区类型 ==="
+findmnt -T / | head -2
+findmnt -T /opt/data | head -2
+
+echo "=== adapter.py 现状 ==="
+stat -c '%s %y %U:%G %a' /opt/hermes/plugins/platforms/matrix/adapter.py
+md5sum /opt/hermes/plugins/platforms/matrix/adapter.py
+
+echo "=== 现有插件 ==="
+ls /opt/data/plugins/
+grep -n "plugins:" -A20 /opt/data/config.yaml | head -25
+```
+
+**必须记录的四项**：
+
+| 项 | 记录 | 为什么 |
+|---|---|---|
+| venv python 路径 | | 所有 Python 校验命令都用它，**不要用裸 `python3`** |
+| s6 服务名 | | `main-hermes` / `gateway-default` 各容器不同，用错**不报错但不生效** |
+| adapter.py 原始 md5 | | 事后判断"有没有被改过"的唯一依据 |
+| 现有插件清单 | | 避免重复安装、避免覆盖别人的插件 |
+
+### 1.3 确认上游关键函数的位置
+
+```bash
+F=/opt/hermes/plugins/platforms/matrix/adapter.py
+grep -n "async def _handle_media_message\|async def _download_and_cache_media\|startswith(\"mxc://\")" $F
+grep -n "from urllib.parse import" $F | head -3
+```
+
+> 🔴 **如果 `from urllib.parse import` 里没有 `urlparse`，新增函数必须在函数内部 import**——
+> 否则 `NameError` 被 `except` 吞掉，表现为「所有附件都被拒，但日志看不出来」。
+
+---
+
+## 二、入站改造：让容器能收 https 附件
+
+### 2.1 完整代码
+
+以下四段是 lj-test 上**端到端验证通过**的最终代码（`adapter.py` 第 251-269、2152-2179、2217-2261、2263-2300 行）。
+
+#### ① 模块级白名单函数（放在 `class MatrixAdapter` **之前**，模块层级）
+
+```python
+# Fmode: 允许容器直接拉取的附件域名。防 SSRF：只放行这一个。
+# 注意：file-cloud.fmode.cn 证书已过期（2026-11-13 实测），不要加回来。
+# 🔴 urlparse 必须在函数内 import —— 模块顶部只导入了 urljoin/urlsplit/urlunsplit，
+#    裸用 urlparse 会 NameError，被 except 吞掉后静默返回 False，附件照旧被拒。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+```
+
+> 🔴 **插入位置必须是模块级**（`class MatrixAdapter(...):` 之前）。
+> 曾实测：插到类方法前 → 函数落进类体 → `async def` 缩进异常 → `IndentationError`。
+
+#### ② `_handle_media_message` 两处判断（原文件约 2136 / 2155 行）
+
+```python
+        # 【原】if url and not str(url).startswith("mxc://"):
+        # 【改】
+        if url and not _is_allowed_media_url(str(url)):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)
+            return
+```
+
+```python
+            # 【原】if url and not str(url).startswith("mxc://"):
+            # 【改】
+            if url and not _is_allowed_media_url(str(url)):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)
+                return
+```
+
+#### ③ `_fetch_http_media` 新增方法（放在 `_download_and_cache_media` 之前，**类内**）
+
+```python
+    async def _fetch_http_media(self, url: str, event_id: str):
+        """Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。"""
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=600)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=600, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+```
+
+**三个必须保留的安全细节**：
+
+| 细节 | 原因 |
+|---|---|
+| `allow_redirects=False` | 白名单域名 302 到内网 → SSRF 绕过 |
+| **流式累加计数** | `Content-Length` 在 chunked 时为 `None`，用它判上限等于没判 |
+| `ImportError` 才回落 httpx | 各容器 venv 依赖不同，有的只有 aiohttp，有的两者都有 |
+
+#### ④ `_download_and_cache_media` 分流（**该函数第一行**）
+
+```python
+        # 【原】file_bytes = await self._client.download_media(ContentURI(url))
+        # 【改】
+        if str(url).startswith("https://"):
+            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media
+            file_bytes = await self._fetch_http_media(url, event_id)
+            if file_bytes is None:
+                return None
+        else:
+            file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+**其余一律不动**：解密逻辑、`cache_image/audio/document_from_bytes_async` 分类，都是上游原样。
+
+> 分流用的是 `startswith("https://")` 而不是 `not startswith("mxc://")` —— 语义更明确。
+> 视频会被归到 document 类（上游行为，保持不变）。
+
+### 2.2 打补丁脚本（幂等，带 `--check`）
+
+保存为 `/opt/data/patches/matrix-inbound/patch_inbound.py`。
+
+```python
+#!/usr/bin/env python3
+"""Fmode 入站附件补丁：放行 https 白名单附件。支持 --check / --apply / --revert。
+
+设计要点：
+  · 幂等：已打过就跳过（靠 MARK 标记）
+  · 安全：任何一处匹配次数 ≠ 1 就整体中止，不写文件
+  · 可验证：--check 在内存里编译 + 抽函数 exec + 跑白名单用例
+"""
+import argparse
+import hashlib
+import shutil
+import sys
+import time
+from pathlib import Path
+
+TARGET = Path(sys.argv[0]).parent / "adapter.py"   # 部署时改成绝对路径
+MARK = "# --- FMODE INBOUND HTTPS PATCH ---"
+
+HELPER = '''# --- FMODE INBOUND HTTPS PATCH ---
+# Fmode: 允许容器直接拉取的附件域名。防 SSRF：只放行这一个。
+# 注意：file-cloud.fmode.cn 证书已过期（2026-11-13 实测），不要加回来。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+# --- END FMODE INBOUND HTTPS PATCH ---
+
+
+'''
+
+FETCH = '''    async def _fetch_http_media(self, url: str, event_id: str):
+        """Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。"""
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=600)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=600, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+
+'''
+
+REPS = [
+    (
+        '        if url and not str(url).startswith("mxc://"):\n'
+        '            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)\n',
+        '        if url and not _is_allowed_media_url(str(url)):\n'
+        '            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)\n',
+    ),
+    (
+        '            if url and not str(url).startswith("mxc://"):\n'
+        '                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)\n',
+        '            if url and not _is_allowed_media_url(str(url)):\n'
+        '                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)\n',
+    ),
+    (
+        '        file_bytes = await self._client.download_media(ContentURI(url))',
+        '        if str(url).startswith("https://"):\n'
+        '            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media\n'
+        '            file_bytes = await self._fetch_http_media(url, event_id)\n'
+        '            if file_bytes is None:\n'
+        '                return None\n'
+        '        else:\n'
+        '            file_bytes = await self._client.download_media(ContentURI(url))',
+    ),
+]
+
+
+def build(src: str) -> str:
+    for a, _ in REPS:
+        n = src.count(a)
+        if n != 1:
+            raise SystemExit(f"匹配 {n} 次（期望 1），中止：{a[:60]!r}")
+    for a, b in REPS:
+        src = src.replace(a, b, 1)
+    # 模块级插入：必须在 class 定义之前
+    anchor = "\nclass "
+    i = src.index(anchor)
+    src = src[:i] + "\n" + HELPER.rstrip("\n") + "\n" + src[i:]
+    # 方法插入：在 _download_and_cache_media 之前
+    m = "    async def _download_and_cache_media("
+    if src.count(m) != 1:
+        raise SystemExit("找不到 _download_and_cache_media，中止")
+    src = src.replace(m, FETCH + m, 1)
+    return src
+
+
+def check(src: str) -> int:
+    patched = build(src)
+    compile(patched, str(TARGET), "exec")
+    print("compile OK")
+    # 抽函数真实执行
+    ns = {}
+    start = patched.index("_FMODE_MEDIA_HOSTS")
+    end = patched.index("# --- END FMODE INBOUND HTTPS PATCH ---")
+    exec(patched[start:end], ns)
+    f = ns["_is_allowed_media_url"]
+    print("白名单集合:", ns["_FMODE_MEDIA_HOSTS"])
+    cases = {
+        "https://s3.fmode.cn/a.txt": True,
+        "mxc://fmode.cn/abc": True,
+        "https://s3.fmode.cn.evil.com/a": False,
+        "https://evil.com/s3.fmode.cn": False,
+        "https://s3.fmode.cn@evil.com/a": False,
+        "http://s3.fmode.cn/a": False,
+        "https://sub.s3.fmode.cn/a": False,
+        "https://file-cloud.fmode.cn/a": False,
+    }
+    bad = 0
+    for u, want in cases.items():
+        got = f(u)
+        ok = got is want
+        bad += 0 if ok else 1
+        print(("PASS" if ok else "FAIL"), u, "->", got, "(期望", want, ")")
+    print("ALL_PASS" if bad == 0 else f"HAS_FAIL {bad}")
+    return 0 if bad == 0 else 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--check", action="store_true")
+    ap.add_argument("--apply", action="store_true")
+    ap.add_argument("--revert", action="store_true")
+    a = ap.parse_args()
+
+    src = TARGET.read_text(encoding="utf-8")
+    if a.revert:
+        # 🔴 不能取「最近的 .bak」——最近的那份可能是别的操作留下的、甚至已含补丁。
+        #    只认「内容里不含 MARK」的备份，且取其中最新的那份。
+        baks = sorted(TARGET.parent.glob(TARGET.name + ".bak*"), reverse=True)
+        good = []
+        for b in baks:
+            try:
+                if MARK not in b.read_text(encoding="utf-8"):
+                    good.append(b)
+            except Exception:
+                continue
+        if not good:
+            raise SystemExit("没有可用的原版备份（全部含补丁或不可读）")
+        shutil.copy2(good[0], TARGET)
+        print("已回滚自", good[0])
+        print("md5:", hashlib.md5(TARGET.read_bytes()).hexdigest())
+        print("⚠️ 需要重启 gateway 才会生效：s6-svc -r /run/service/gateway-default")
+        return 0
+    if MARK in src:
+        print("已打过补丁，跳过")
+        return 0
+    if a.check:
+        return check(src)
+    if a.apply:
+        if check(src) != 0:
+            raise SystemExit("校验未通过，拒绝写盘")
+        bak = TARGET.with_name(TARGET.name + ".bak." + time.strftime("%Y%m%d%H%M%S"))
+        shutil.copy2(TARGET, bak)
+        TARGET.write_text(build(src), encoding="utf-8")
+        print("已写入；备份:", bak)
+        print("md5:", hashlib.md5(TARGET.read_bytes()).hexdigest())
+        return 0
+    ap.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+**用法**：
+
+```bash
+PY=/opt/hermes/.venv/bin/python
+# 1) 先检查（不写盘）
+sudo -u root $PY /opt/data/patches/matrix-inbound/patch_inbound.py --check
+# 2) 通过后应用
+sudo -u root $PY /opt/data/patches/matrix-inbound/patch_inbound.py --apply
+# 3) 出问题回滚
+sudo -u root $PY /opt/data/patches/matrix-inbound/patch_inbound.py --revert
+```
+
+> 🔴 **`--revert` 必须真的存在且真的还原。** 实测踩过：某容器的补丁脚本只判断了
+> `--apply`，其它参数一律走 `--check` —— 跑 `--revert` 时**静默什么都没做**，却打印了看似正常的信息，
+> 让人误以为「已回滚」。判断参数时**必须显式拒绝未知参数**：
+> ```python
+> if not (a.check or a.apply or a.revert):
+>     raise SystemExit(f"未知参数：{sys.argv[1:]}")
+> ```
+>
+> **最可靠的回滚**永远是：用宿主机侧备份覆盖 + 重启 gateway（见 §5.4）。
+
+### 2.3 权限问题（新容器必遇）
+
+`adapter.py` 属 `root:root 644`，容器内 `hermes` 用户**无写权限也无 sudo**。两个选择：
+
+**方案 A（推荐）**：宿主机执行一次 chown
+
+```bash
+docker exec -u root <容器名> chown hermes:hermes /opt/hermes/plugins/platforms/matrix/adapter.py
+```
+
+**方案 B**：宿主机直接执行 apply
+
+```bash
+docker cp /opt/data/patches/matrix-inbound/patch_inbound.py <容器名>:/tmp/
+docker exec -u root <容器名> /opt/hermes/.venv/bin/python /tmp/patch_inbound.py --apply
+```
+
+---
+
+## 三、出站改造：切断 Matrix 回发文件的老路
+
+### 3.1 原理
+
+Agent 在回复里写 `MEDIA:<本地路径>` 时，gateway 会解析出 `media_files`，然后：
+- `send_video()` / `send_image_batch()` / `send_document()` → **把文件本体上传进 Matrix**
+- 路径不存在 → 发 `⚠️ Couldn't deliver the xxx attachment.`
+
+**必须切断**。但有一个硬约束：
+
+> 🔴 `transform_llm_output` 是 **first non-None wins + break**
+> （`/opt/hermes/agent/turn_finalizer.py:427-429`）：
+> 同一 hook 的多个插件拿到**同一份** `response_text`、互不可见，
+> **只有第一个返回非 None 的生效**并 break。
+>
+> **⇒ 剥离逻辑必须合并进 `plugin-deliverable-inject` 的同一个回调，且顺序是：**
+> ```
+> ① 先剥离 MEDIA 标记  →  ② 再注入 **已上云（可直接下载）** + https
+> ```
+
+### 3.2 新增 `media_strip.py`
+
+路径：`/opt/data/plugins/plugin-deliverable-inject/media_strip.py`
+
+```python
+"""MEDIA 标记全量剥离。
+
+剥离语义（四条，缺一不可）：
+  1) 行首 MEDIA:<任意路径> → 整行删除（不限前缀：/opt/hermes、/srv、Windows 盘符都覆盖）
+  2) 行内 MEDIA:<path> → 只删标记+路径 token，保留同行其余文字
+  3) 绝不触碰 **已上云（可直接下载）** 段与其中的 https
+  4) 幂等：无改动返回 None
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# 🔴 注意：源码里 MEDIA 是字面量，此处为文档排版用「MEDIA:」示意
+_LINE_MEDIA = re.compile(r"(?m)^[ \t]*(?:>[ \t]*)*(?:[-*+][ \t]+)?MEDIA:[ \t]*[^\n]*(?:\n|$)")
+_INLINE_MEDIA = re.compile(
+    r"[ \t]*MEDIA:[ \t]*"
+    r"(?:`(?P<bt>/[^`\n]*|[A-Za-z]:[^`\n]*)`"
+    r"|<(?P<ang>/[^>\n]*)>"
+    r"|(?P<bare>/[^\s，。；：！？、）)\]】\"'`]+)"
+    r"|(?P<win>[A-Za-z]:[\\/][^\s，。；：！？、）)\]】\"'`]+)"
+    r"|(?P<url>[a-z]+://[^\s，。；：！？、）)\]】\"'`]+)"
+    r")?"
+)
+_UPLOAD_HEADER = "**已上云（可直接下载）**"
+_LOCAL_HINTS = ("/opt/data/", "/tmp/", "/home/", "file://")
+
+
+def _disabled() -> bool:
+    return str(os.environ.get("PLUGIN_FMODE_STRIP_MEDIA_DISABLE", "")).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def strip_media(text: str) -> Optional[str]:
+    if _disabled() or not isinstance(text, str) or "MEDIA:" not in text:
+        return None
+    original = text
+    out = _LINE_MEDIA.sub("", text)
+    if "MEDIA:" in out:
+        out = _INLINE_MEDIA.sub("", out)
+    out = re.sub(r"[ \t]+(?=\n)", "", out)
+    out = re.sub(r"(?m)^[ \t]*[，。；：、,;:][ \t]*$", "", out)
+    out = re.sub(r"\n{3,}", "\n\n", out).strip()
+    if out == original:
+        return None
+    # 自检：注入段标题必须原样存活，否则放弃本次剥离
+    if _UPLOAD_HEADER in original and _UPLOAD_HEADER not in out:
+        logger.error("strip_media: 误删上云段标题，放弃剥离")
+        return None
+    logger.info("strip_media: 已剥离 MEDIA 标记（%d -> %d 字符）", len(original), len(out))
+    return out
+```
+
+### 3.3 修改 `plugin-deliverable-inject/__init__.py`
+
+在 `_on_transform_llm_output` 的**最开头**（注入之前）插入：
+
+```python
+    # ── 步骤 0：全量剥离 MEDIA 标记（必须在注入之前）──
+    # 为什么在这里而不是独立插件：invoke_hook 对同一 hook 的多个回调传同一份 kwargs、
+    # 只 collect 返回值（互不可见），且 turn_finalizer 只取第一个 non-None str。
+    # 两插件无法串联，只能同回调内按序执行。
+    original_input = response_text
+    try:
+        from . import media_strip  # type: ignore
+        stripped = media_strip.strip_media(response_text)
+        if stripped is not None:
+            response_text = stripped
+    except Exception as exc:
+        logger.warning("deliverable-inject: MEDIA 剥离失败，继续注入（%s）", exc)
+```
+
+并**删除**原来那段只认行首、前缀仅 `/opt/data|/tmp|/home` 的旧正则（避免两套语义漂移）。
+
+---
+
+## 四、插件与环境变量配置
+
+### 4.1 插件清单（lj-test 实际状态）
+
+| 插件 | 作用 | 必须启用 |
+|---|---|---|
+| `plugin-deliverable-inject` | 剥离 MEDIA + 注入「已上云」链接 | ✅ **核心** |
+| `plugin-active-reporter` | 状态上报（在线/心跳） | ✅ 推荐 |
+| `plugin-media-text-merge` | 图文两轮合并成一轮 | 推荐 |
+| `plugin-turn-end` | 已弃用（typing 方案作废） | ❌ |
+| `plugin-tips-cn` / `plugin-topup-guard` | 业务相关 | 按需 |
+
+**登记方式**（插件不登记 = 没装，**且不会有任何报错**）：
+
+```bash
+hermes plugins list                 # 看当前
+hermes plugins enable <插件名>       # 启用
+# 或直接编辑 /opt/data/config.yaml 的 plugins.enabled 列表
+grep -n "plugins:" -A20 /opt/data/config.yaml   # 确认已登记
+```
+
+### 4.2 关键环境变量（`/opt/data/.env`）
+
+```ini
+# ---- Matrix 接入 ----
+MATRIX_HOMESERVER=https://matrix.fmode.cn
+MATRIX_USER_ID=@<你的agentId>:fmode.cn
+AGENT_ID=<你的 agentId>
+
+# ---- 对话行为 ----
+MATRIX_REQUIRE_MENTION=false          # DM 全放开；群聊按需改 true
+MATRIX_AUTO_THREAD=true               # 无 thread 的消息自动成为 thread 根
+
+# ---- 媒体 ----
+MATRIX_MAX_MEDIA_BYTES=104857600      # 100MB（默认值，可调大）
+
+# ---- 🔴 鉴权白名单（新容器最容易漏）----
+# 不配这一项，App 发的消息会被静默丢弃，表现为「只打 ✅ 不回正文」
+MATRIX_ALLOWED_USERS=@<App用户MXID>:fmode.cn,@<其他用户>:fmode.cn
+```
+
+> 🔴 **鉴权白名单是最隐蔽的坑**。
+> 真实案例：某容器改造后「只打 ✅ 不回复」，排查半天，最终发现是
+> `Unauthorized user (ignored): Dropped a message from unrecognized matrix user`，
+> 19 条消息全被丢弃。**与代码改造无关，只是没加白名单。**
+
+**怎么拿到 App 用户的 MXID**：让 App 侧执行 `provision({agentId})`，返回的 `userMxId` 就是。
+
+### 4.3 重启 gateway
+
+```bash
+# 🔴 先用 §1.2 查到的实际服务名，不要照抄
+s6-svc -r /run/service/gateway-default
+# 或
+s6-svc -r /run/s6/services/main-hermes
+
+sleep 5
+ps -o lstart= -p $(pgrep -f "hermes gateway run" | head -1)   # 确认启动时间是刚才
+```
+
+> ⚠️ **服务名写错不会报错，但补丁不生效** —— 这是「改了没反应」的常见原因。
+> ⚠️ `s6-svc -r` 会**打断当前这个 agent 回合**，所以重启命令建议放在回合最后一步。
+
+---
+
+## 五、持久化兜底（跨容器重建保留）
+
+### 5.1 为什么需要
+
+实测：
+
+| 路径 | 类型 | `docker restart` | `docker rm` + 重建 | 镜像升级 |
+|---|---|---|---|---|
+| `/opt/hermes/...` | **overlay 可写层** | ✅ 保留 | ❌ **丢失** | ❌ **丢失** |
+| `/opt/data/...` | ext4 持久卷 | ✅ 保留 | ✅ 保留 | ✅ 保留 |
+
+**结论：网关重启 / 容器重启不影响；容器重建会丢入站补丁。**
+
+丢了之后的症状：用户发附件收不到，日志只有一行 `Rejecting inbound media ... non-MXC URL`，
+**极难联想到是补丁没了**。
+
+### 5.2 `entry.sh` 载体方案（lj-test 已验证）
+
+在持久卷建目录：
+
+```bash
+mkdir -p /opt/data/.fmode-media-patch
+cp /opt/data/patches/matrix-inbound/patch_inbound.py /opt/data/.fmode-media-patch/
+```
+
+`/opt/data/.fmode-media-patch/entry.sh`：
+
+```bash
+#!/bin/bash
+# Fmode: 容器启动时幂等重打入站附件补丁，然后执行原入口。
+# 幂等：已打过就直接跳过（patch_inbound.py 内部有 MARK 判断）。
+set -u
+
+PATCH=/opt/data/.fmode-media-patch/patch_inbound.py
+TARGET=/opt/hermes/plugins/platforms/matrix/adapter.py
+PY=/opt/hermes/.venv/bin/python
+
+echo "[fmode-patch] 检查入站附件补丁…"
+if [ -w "$TARGET" ]; then
+  "$PY" "$PATCH" --apply || echo "[fmode-patch] 打补丁失败，继续启动（附件功能可能不可用）"
+else
+  echo "[fmode-patch] adapter.py 不可写（需 root），跳过 —— 如附件失效请重新授权"
+fi
+
+# 执行原入口（保持容器原本的启动命令）
+exec /opt/hermes/docker/main-wrapper.sh "$@"
+```
+
+```bash
+chmod +x /opt/data/.fmode-media-patch/entry.sh
+```
+
+### 5.3 重建容器时挂上
+
+```bash
+docker run -d --name <容器名> \
+  --restart unless-stopped \
+  --entrypoint /opt/data/.fmode-media-patch/entry.sh \
+  -e TZ=Asia/Shanghai \
+  <其余原有 env> \
+  -v /opt/fmode-containers/<容器名>/data:/opt/data \
+  fmode/agent-node:<版本> gateway run
+```
+
+> ⚠️ 重建前必须先取到原容器的完整参数：
+> `docker inspect <容器名> > /tmp/orig.json`，照着恢复。
+> **数据卷不动就不会丢数据。**
+
+### 5.4 简化方案：不改 entrypoint，手动重打
+
+如果不方便改启动命令，至少保留：
+
+- `/opt/data/.fmode-media-patch/patch_inbound.py`（持久卷里）
+- `/opt/data/backups/adapter.py.bak-host-<ts>`（宿主机侧备份）
+
+重建后手动执行一次 `--apply` 即可。
+
+---
+
+## 六、验收（四道门槛，缺一不可）
+
+### 门槛 1：文件层面
+
+```bash
+F=/opt/hermes/plugins/platforms/matrix/adapter.py
+stat -c '%s %y %U:%G' $F          # 大小应变大、时间是刚才
+grep -c "_is_allowed_media_url" $F # 期望 4
+md5sum $F                          # 与改造前不同
+```
+
+### 门槛 2：逻辑层面（**决定性**）
+
+```bash
+/opt/hermes/.venv/bin/python - <<'PY'
+import importlib.util, sys
+sys.path.insert(0, '/opt/hermes')
+spec = importlib.util.spec_from_file_location('probe', '/opt/hermes/plugins/platforms/matrix/adapter.py')
+m = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = m          # 🔴 必须注册，否则 @dataclass 解析失败
+spec.loader.exec_module(m)
+f = m._is_allowed_media_url
+for u, want in [
+    ('https://s3.fmode.cn/a.txt', True),
+    ('mxc://fmode.cn/abc', True),
+    ('https://s3.fmode.cn.evil.com/a', False),
+    ('https://evil.com/s3.fmode.cn', False),
+    ('https://s3.fmode.cn@evil.com/a', False),
+    ('http://s3.fmode.cn/a', False),
+    ('https://sub.s3.fmode.cn/a', False),
+]:
+    got = f(u)
+    print('PASS' if got is want else 'FAIL', u, '->', got)
+PY
+```
+
+**必须 `https://s3.fmode.cn/a.txt -> True`。**
+⚠️ 只"拒绝得都对"不够——某次补丁全返回 `False`，"拒绝得很对"，但合法链接也被拒了。
+
+### 门槛 3：容器能正常对话（**之前必须先过这道**）
+
+App 侧发「1+1 等于几」，能收到正文「2」。
+❌ 只打 ✅ 不回正文 → 查 §4.2 的 `MATRIX_ALLOWED_USERS`。
+
+### 门槛 4：端到端（App 侧执行）
+
+App 发一个文件（`m.file`，`url=https://s3.fmode.cn/...`，内容里埋随机指纹码），检查：
+
+```bash
+# 容器内：确认下载了
+grep -E "Rejecting inbound media|non-allowed" /opt/data/logs/gateway.log | tail -5
+ls -lat /opt/data/cache/documents/ | head -3
+
+# 权威判据：查消息库
+/opt/hermes/.venv/bin/python -c "
+import sqlite3
+n=sqlite3.connect('/opt/data/state.db').execute(
+  \"select count(*) from messages where content like '%<指纹码>%'\").fetchone()[0]
+print('DBHIT' if n else 'DBMISS', n)"
+```
+
+必须 `DBHIT`。
+
+> 🔴 **不要用「容器在某房间回话」判断**——容器可能把回复发到别的 session，会误判。
+
+### 出站验收
+
+让 Agent 产出一个文件，检查回复正文：
+
+| 检查 | 期望 |
+|---|---|
+| 有 `MEDIA:` | ❌ 不该有 |
+| 有 `/opt/data/...` 本地路径 | ❌ 不该有 |
+| 有 `**已上云（可直接下载）**` + https | ✅ 应该有 |
+
+---
+
+## 七、踩坑速查表（全部实测过）
+
+| # | 坑 | 症状 | 解法 |
+|---|---|---|---|
+| 1 | `urlparse` 未导入 | 所有附件被拒，**日志无异常** | 函数内 `from urllib.parse import urlparse` |
+| 2 | 用裸 `python3` | 报"依赖缺失" | 一律 `/opt/hermes/.venv/bin/python` |
+| 3 | `file-cloud.fmode.cn` | 证书已过期 | 白名单只放 `s3.fmode.cn` |
+| 4 | 用 `Content-Length` 判大小 | chunked 时为 `None`，上限失效 | 流式累加计数 |
+| 5 | 跟随重定向 | SSRF 绕过 | `allow_redirects=False` |
+| 6 | 白名单函数插进类体 | `IndentationError` | 插到 `class` 之前（模块级） |
+| 7 | s6 服务名写错 | 补丁不生效，**无报错** | `pgrep -af s6-supervise` 确认 |
+| 8 | 插件没登记 | 完全不生效，**无报错** | `grep 插件名 config.yaml` |
+| 9 | **鉴权白名单没加** | **只打 ✅ 不回正文** | `MATRIX_ALLOWED_USERS` 加 App 用户 |
+| 10 | 两个插件各注册 `transform_llm_output` | 只有一个生效 | 合并进同一回调 |
+| 11 | 把模块级函数插在类方法前 | `IndentationError` | 插入锚点用 `\nclass ` |
+| 12 | 按 docker 容器名找容器 | 改错容器 | 只认 `AGENT_ID` + `MATRIX_USER_ID` |
+| 13 | 只做容器内自测 | 自测 PASS、App 侧不通 | **必须 App 侧端到端验证** |
+| 14 | Monkey Patch 整份替换上游方法 | 上游升级即静默失效 | 只改入口判断，不复制方法体 |
+| 15 | `s6-svc -r` 打断自己回合 | 重启命令后的输出丢失 | 重启命令放回合最后 |
+| 16 | **`--revert` 实际不存在** | 跑 `--revert` 静默走了 `--check`，什么都没还原，却像"已回滚" | 参数判断里**显式拒绝未知参数**；最可靠的回滚 = 宿主机备份覆盖 |
+| 17 | **`py_compile` 因 `__pycache__` 不可写而失败** | 报错但源码没问题，容易误判 | 用 `compile(src, path, "exec")` 做内存编译，或 `python -B` |
+| 18 | **`s6-svc` 不在 PATH** | `command not found`，以为服务不存在 | 用绝对路径 `/command/s6-svc`；先 `ls /command/` 确认 |
+| 19 | **entry.sh 两套补丁脚本打架** | 容器自带 patch 与手册脚本实现不同（frozenset+env 扩展 vs 固定白名单） | entry.sh **优先用容器自带的那份**，它不在时才回退；不要两套并存 |
+
+---
+
+## 八、改造前后对照
+
+| 环节 | 改造前 | 改造后 |
+|---|---|---|
+| 用户发文件 | App 双写：S3 + Matrix 媒体库 | 只写 S3，Matrix 只传链接 |
+| 容器收文件 | 只认 `mxc://`，https 静默丢弃 | 认 https 白名单域名，自己下载 |
+| 容器发文件 | 可能用 `MEDIA:` 回发本体 | 只能上云 + 正文给链接 |
+| 带宽 | 文件走两遍 | 走一遍 |
+| 换设备 | Matrix 清理媒体后失效 | S3 链接长期有效 |
+
+---
+
+## 附：给新容器的执行清单
+
+```markdown
+□ 1. 跑 §1.1 记录指纹，上报 AGENT_ID / MATRIX_USER_ID
+□ 2. 跑 §1.2 探明：venv python 路径 / s6 服务名 / adapter md5 / 插件清单
+□ 3. 跑 §1.3 确认 _handle_media_message 与 _download_and_cache_media 的行号
+□ 4. 检查 .env 的 MATRIX_ALLOWED_USERS 是否包含 App 用户 MXID（§4.2）
+□ 5. 安装 §2.2 的 patch_inbound.py 到 /opt/data/patches/matrix-inbound/
+□ 6. --check 通过后 --apply（需要 root，见 §2.3）
+□ 7. 安装 §3.2 的 media_strip.py，改 §3.3 的 plugin-deliverable-inject
+□ 8. 确认插件已登记（§4.1），重启 gateway（§4.3）
+□ 9. 过 §6 门槛 1、2
+□ 10. 通知 App 侧验证门槛 3、4
+□ 11. 建立 §5.2 的 entry.sh 持久化兜底
+```

docs/03-interface/紧急-kangshifu容器故障定位与修复-20261113.md

@@ -0,0 +1,299 @@
+# 紧急：容器 `agent-node-kangshifu` 故障定位与修复提示词
+
+> 下发时间：2026-11-13
+> 背景：该容器改造完成后，**App 侧实测连消息都收不到**（连「1+1 等于几」都不回复，只打 ✅）。
+> 这不是「改造没生效」，是**改造把容器弄坏了**。请按顺序执行，不要跳步。
+
+---
+
+## 〇、先看这个结论（避免走弯路）
+
+App 侧实测记录（2026-11-13）：
+
+| 测试 | 结果 |
+|---|---|
+| 问「1+1 等于几？」 | ❌ 无正文回复，只打 ✅ |
+| 让执行 `ls` 并贴输出 | ❌ 无正文回复，只打 ✅ |
+| App 发 `m.file`（url= `https://s3.fmode.cn/...`） | ❌ 容器无响应 |
+| `matrix-check agent-node-kangshifu` | ❌ `FmooleAgent 记录：404` |
+
+**你的自查报告里「三层验收全部 PASS」是真的，但那是容器内部自测。**
+自测证明的是「我改的代码逻辑对」，**不能证明「App 发来的消息我能收到」**。
+两者是两回事 —— 这次坏掉的是后者。
+
+---
+
+## 一、第一步：先让容器能说话（救火，5 分钟）
+
+🔴 **在修任何东西之前，先恢复基本对话能力。不要边修边试。**
+
+### 1.1 立即禁用可疑插件
+
+```bash
+cd /opt/data
+# 找到登记命令（本容器用 hermes config set 登记过插件）
+grep -n "plugin" config.yaml | head -20
+```
+
+把 `plugin-matrix-inbound-s3` 从 `plugins.enabled` 中**移除**或注释掉：
+
+```bash
+# 按你实际的登记方式操作，例如：
+hermes plugins disable plugin-matrix-inbound-s3
+# 或者直接编辑 config.yaml，把它从 plugins.enabled 列表里删掉
+```
+
+### 1.2 重启 gateway 并验证
+
+```bash
+# 用你确认过存在的服务名（报告里说 main-hermes / gateway-default 都在）
+s6-svc -r /run/service/gateway-default
+sleep 5
+```
+
+### 1.3 ✅ 门槛：必须能正常对话才能继续
+
+**用 App 或任意客户端给这个容器发一条**：
+
+```
+1+1 等于几？直接回答数字。
+```
+
+**期望：收到正文回复「2」。**
+
+- ✅ 能回复 → 继续 §二
+- ❌ 仍然只打 ✅ 没正文 → **停止**，把 `tail -100 /opt/data/logs/gateway.log` 的原始输出贴回来，进入「网关崩溃排查」模式
+
+> 这一步**必须由外部客户端验证**，不能用容器自测。容器自测的前提就是"容器能工作"，而问题恰恰是它不能工作。
+
+---
+
+## 二、第二步：定位「为什么 App 的消息收不到」
+
+### 2.1 先确认消息到底进没进来
+
+恢复对话后，让 App 发一条普通文字（不带附件）：
+
+```bash
+# 在容器内查最近入站记录
+tail -50 /opt/data/logs/gateway.log | grep -E "inbound|matrix"
+```
+
+**判读**：
+
+| 现象 | 说明 | 下一步 |
+|---|---|---|
+| 有 `inbound message` 日志 | 消息进来了，问题在**处理/回复**环节 | §2.2 |
+| 没有 `inbound message` | 消息**根本没进容器** | §2.3 |
+
+### 2.2 查回复失败原因
+
+```bash
+grep -iE "error|exception|traceback|failed" /opt/data/logs/gateway.log | tail -30
+grep -iE "error|exception|traceback" /opt/data/logs/errors.log 2>/dev/null | tail -30
+```
+
+**把原始输出贴回来。** 特别关注：
+- 有没有 `plugin_matrix_inbound_s3` 相关的异常
+- 有没有 `RuntimeError: coroutine ... was never awaited` / `AttributeError` / `TypeError`
+
+### 2.3 查消息为何没进容器
+
+```bash
+# 房间加入状态
+grep -E "joined|invite|left" /opt/data/logs/gateway.log | tail -20
+# 同步状态
+grep -iE "sync|M_UNKNOWN_TOKEN|401|403" /opt/data/logs/gateway.log | tail -20
+```
+
+---
+
+## 三、第三步：分析你之前的改法为什么有风险
+
+### 3.1 你做了什么
+
+你的报告里写：
+
+```python
+if url and not (_is_allowed_media_url(url) or url.startswith("mxc://")):
+```
+
+且验收输出显示：
+
+```
+_handle_media_message 模块 = hermes_plugins.plugin_matrix_inbound_s3  ← 被替换了
+_download_and_cache_media 模块 = hermes_plugins.plugin_matrix_inbound_s3
+```
+
+**这是 Monkey Patch：整个替换掉上游类的两个方法。**
+
+### 3.2 为什么这个做法危险
+
+| 风险 | 后果 |
+|---|---|
+| **签名绑定**：你复制了上游方法体，上游一升级（参数增减、默认值变化）就静默失效 | 附件收不到，**没有任何报错** |
+| **方法体漂移**：你复制的那份方法体，和上游实际版本可能已经不同 | 你"修好"的是旧逻辑，新行为丢失 |
+| **异常放大**：你的实现里任何一个 bug，会让**整个 adapter 的媒体链路**挂掉 | 视频/图片/文件全部失效 |
+| **影响面失控**：Monkey Patch 是全局的，所有房间、所有类型都走你的代码 | 一处出错全盘皆输 |
+
+**你现在的症状（连文字消息都不回）说明问题可能比附件链路更大 —— 先按 §一 恢复。**
+
+### 3.3 你发现的那个正确方向
+
+你在报告里说：
+
+> 上游已自带 `_download_external_media_with_cap`，具备 SSRF 校验、逐跳重定向拦截、流式限流。照抄文档示例反而丢防护。
+
+**这个判断是对的，而且很重要。** 那么正确的做法应该是：
+
+```
+最小改动 = 只在「入口判断」放行 https，下载仍然走上游的 _download_external_media_with_cap
+         ≠ 替换整个 _handle_media_message 和 _download_and_cache_media
+```
+
+---
+
+## 四、第四步：用最小改动重做（等 §一 恢复后再做）
+
+### 4.1 先确认上游的真实签名
+
+```bash
+F=/opt/hermes/plugins/platforms/matrix/adapter.py
+grep -n "async def _handle_media_message\|async def _download_and_cache_media\|def _download_external_media_with_cap" $F
+```
+
+记下：
+- `_download_external_media_with_cap` 的**完整函数签名**（参数、返回值）
+- `_handle_media_message` 里判断 url 的**那几行**
+- `_download_and_cache_media` 里**调用下载的代码行**
+
+### 4.2 改法 A（推荐）：只改判断，不动下载
+
+**只替换「判断那两行」**，其余完全交给上游：
+
+```python
+# 原：
+if url and not str(url).startswith("mxc://"):
+    logger.warning(...)
+    return
+
+# 改为：
+if url and not (str(url).startswith("mxc://") or _is_allowed_media_url(str(url))):
+    logger.warning(...)
+    return
+```
+
+然后在 `_download_and_cache_media` 里，**用上游已有的 `_download_external_media_with_cap`** 处理 https：
+
+```python
+# 找到上游原有的下载调用那行，只加一个分支：
+if str(url).startswith("https://"):
+    file_bytes = await self._download_external_media_with_cap(url)   # 签名请按 §4.1 实际确认
+else:
+    file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+**关键要求**：
+1. **不要复制上游方法体**，只调用它
+2. 如果 `_download_external_media_with_cap` 签名不匹配（比如返回的是路径而不是 bytes），**先贴出签名再决定**，不要猜
+
+### 4.3 改法 B（如果 A 不可行）：改用直接打补丁
+
+参照已**端到端验证通过**的 `agent-node-lj-test` 的实现：
+- 文件：`/opt/hermes/plugins/platforms/matrix/adapter.py`
+- 改动：加 `_is_allowed_media_url` + `_fetch_http_media`，改两处入口 + 下载分支
+- 它已验证：App 发 60MB 视频、中文文件名、普通文件，容器都能收到并读取
+
+> ⚠️ 该方法需要 root 权限。若本容器 `/opt/hermes` 只读（报告里说是），
+> 则用「插件层替换**单个方法**」而不是两个方法，且**必须 try/except 包裹**：
+> 出错时 fallback 到原方法，绝不能让它抛异常。
+
+### 4.4 🔴 严禁的做法
+
+| 禁止 | 原因 |
+|---|---|
+| ❌ 复制整份上游方法体再改 | 上游升级即失效，且你改的可能是旧版本 |
+| ❌ 替换 `_handle_media_message` 和 `_download_and_cache_media` 两个方法 | 影响面太大，一处 bug 全挂 |
+| ❌ 没有 try/except 的 Monkey Patch | 异常会冒到 gateway 层，拖垮整个 adapter |
+| ❌ 改完只在容器内自测就宣布完成 | 必须由外部客户端验证 |
+
+---
+
+## 五、第五步：验收（🔴 必须由 App 侧验证）
+
+### 5.1 门槛一：容器能正常对话
+
+```
+App 发：「1+1 等于几？」
+期望：收到正文「2」
+```
+
+❌ 不通过 → 停止，回到 §一。
+
+### 5.2 门槛二：容器能收到 https 附件（**核心指标**）
+
+**由 App 侧执行**（你不需要自己造消息）：
+
+App 会发一条 `m.file`，`content.url = https://s3.fmode.cn/user/.../xxx.txt`，文件内容里埋一个随机码。
+
+**你的验收动作**：
+
+```bash
+# 在容器内查，确认附件事件进来了、且被下载了
+grep -E "Rejecting inbound media|non-allowed|cache/documents" /opt/data/logs/gateway.log | tail -20
+ls -lat /opt/data/cache/documents/ | head -5
+```
+
+**判读**：
+
+| 现象 | 结论 |
+|---|---|
+| 有 `Rejecting inbound media ... non-MXC URL` | ❌ 补丁**没生效** |
+| 有 `Rejecting inbound media ... non-allowed URL` | ⚠️ 白名单判错了 |
+| 有新增的 `cache/documents/doc_xxx` 文件 | ✅ 下载成功 |
+| 什么都没有 | ❌ 事件没进来（回到 §二） |
+
+### 5.3 门槛三：容器真的读到了内容
+
+```bash
+/opt/hermes/.venv/bin/python -c "
+import sqlite3
+n=sqlite3.connect('/opt/data/state.db').execute(
+  \"select count(*) from messages where content like '%<指纹码>%'\").fetchone()[0]
+print('DBHIT' if n else 'DBMISS', n)"
+```
+
+必须 `DBHIT`（>0）。
+
+### 5.4 门槛四：出站不再走老路
+
+让 Agent 产出一个小文件，检查回复正文：
+
+```bash
+# 期望：正文无 MEDIA:、无 /opt/data 等本地路径；有 **已上云（可直接下载）** + https
+```
+
+---
+
+## 六、回交给 App 侧的内容
+
+1. **§一.3 的验证结果**（App 问「1+1」是否收到「2」）
+2. **§2.2 / §2.3 的原始日志**（错误相关内容）
+3. **§4.1 上游函数的真实签名**
+4. **最终改法说明**（用了 A / B 哪个，改了哪几行，是否为 Monkey Patch）
+5. **§5.2 / §5.3 的原始输出**
+
+**不要只回「已修复」。** 前两轮都这么回，实测一次都没真的通。
+这次判定标准只有一条：**App 发附件 → 容器读到内容 → 复述出指纹码。**
+
+---
+
+## 七、如果修不好
+
+**立即回滚到改造前状态**，保证容器能正常工作，优先于功能：
+1. 禁用所有新增插件
+2. 恢复 `plugin-deliverable-inject` 的原版（从 `/opt/data/backups/` 或你改动前的备份）
+3. 重启 → 验证能正常对话
+4. 把问题如实报告，**不要留一个"半坏"的容器**
+
+> 宁可附件功能暂时不可用，也不能让容器连话都说不了。

docs/03-interface/给主容器-定位并修复lj-test附件补丁-20261113.md

@@ -0,0 +1,421 @@
+# 给主容器（编排方）：定位并修复 `agent-node-lj-test` 的 Matrix 附件补丁
+
+> 用途：把这份整段发给主容器/宿主机维护方，由它定位正确的容器并执行补丁。
+> 编写时间：2026-11-13 · 编写方：App 侧（fmode-app-v2）
+
+---
+
+## 〇、先看这里：为什么之前「打了两次都没生效」
+
+前两轮都声称「已修改并重启」，但 App 侧三次真机回读，**目标容器里的文件一个字节都没变**：
+
+```
+$ md5sum /opt/hermes/plugins/platforms/matrix/adapter.py
+fe23502818d3400bd2a5825c2f4e4011        ← 仍是原版
+
+$ ls -la --time-style=full-iso .../adapter.py
+-rw-r--r-- 1 root root 170062 2026-09-19 06:15:58   ← 9 月 19 日的镜像原始时间
+
+$ grep -rn "isallowedmediaurl|fmodefetchhttps" /opt/hermes/
+（零命中）
+
+$ find / -name "*patchmediaurl*"
+（零命中）
+```
+
+→ **改到别的容器去了。** 账号下至少有 6 个容器，其中 `agent-node-lj-test`、`agent-lj`、`agent-node-app-lj-test-v1` 三个都接了 Matrix；「按名字找」和「按宿主机上看起来像的那个找」都会找错。
+
+**所以本任务的第一条硬规矩：先按指纹锁定容器，确认无误后再动手；不确认，不动手。**
+
+---
+
+## 一、目标容器的机器指纹（用来核对，不用来猜名字）
+
+在**容器内部**执行下面这一段，五条**全部**对上，才是我们的目标容器：
+
+```bash
+echo "=== 指纹核对 ==="
+echo "1) hostname           : $(hostname)"
+echo "2) AGENT_ID           : $(grep -E '^AGENT_ID=' /opt/data/.env | cut -d= -f2-)"
+echo "3) MATRIX_USER_ID     : $(grep -E '^MATRIX_USER_ID=' /opt/data/.env | cut -d= -f2-)"
+echo "4) adapter.py 大小/时间: $(stat -c '%s %y' /opt/hermes/plugins/platforms/matrix/adapter.py)"
+echo "5) adapter.py md5     : $(md5sum /opt/hermes/plugins/platforms/matrix/adapter.py | cut -d' ' -f1)"
+```
+
+**必须正好是这组值：**
+
+| 项 | 期望值 |
+|---|---|
+| `AGENT_ID` | `agent-node-lj-test` |
+| `MATRIX_USER_ID` | `@zgdcmgnqcd:fmode.cn` |
+| `adapter.py` 大小 | `170062`（打补丁**前**） |
+| `adapter.py` md5 | `fe23502818d3400bd2a5825c2f4e4011`（打补丁**前**） |
+| `hostname` | 实测为 `e14260fdce46`（容器重启后会变，仅作辅助；**以 AGENT_ID + MATRIX_USER_ID 为准**） |
+
+**只要有一项对不上，立刻停下，把这段原始输出贴回来**，不要继续。
+
+> 在宿主机侧反查容器时，用 `docker inspect` 看环境变量里的 `AGENT_ID`，不要靠容器名字：
+> ```bash
+> for c in $(docker ps -q); do
+>   echo "$c  $(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' $c | grep '^AGENT_ID=' )"
+> done | grep 'agent-node-lj-test'
+> ```
+> 只有恰好一台命中 `AGENT_ID=agent-node-lj-test` 才可以继续。
+
+---
+
+## 二、当前状态（2026-11-13 13:00 实测）
+
+| 项 | 结论 |
+|---|---|
+| 目标容器 `adapter.py` | **原版未改**，`2136` / `2155` 两处仍是 `startswith("mxc://")` |
+| 为什么附件收不到 | 用户发的是 `m.file` 且 `content.url = https://s3.fmode.cn/...`，被上面两处**静默丢弃**（只写一行 `Rejecting inbound media ... with non-MXC URL`） |
+| 旁证 | 同一容器被问「现在几点」能秒回 → **容器活着**，只是这条路径被拒 |
+| 容器重启方式 | `s6-svc -r /run/s6/services/main-hermes`（进程由 s6 托管，见 `ps` 里的 `s6-supervise main-hermes`） |
+| 解释器 | gateway 跑在 `/opt/hermes/.venv/bin/python3`；**裸 `/usr/bin/python3.13` 里没有 aiohttp/httpx/mautrix** |
+
+---
+
+## 三、要做的事（三处代码 + 一处新增）
+
+目标文件：`/opt/hermes/plugins/platforms/matrix/adapter.py`（属主 `root:root`，容器内 `hermes` 用户只读、无 sudo → **必须在宿主机以 root 操作**）
+
+### 补丁 A · 放行 https 的附件地址（`_handle_media_message` 内，约 2136 行）
+
+原文：
+```python
+        if url and not str(url).startswith("mxc://"):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)
+            return
+```
+改为：
+```python
+        if url and not _is_allowed_media_url(str(url)):
+            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)
+            return
+```
+
+### 补丁 B · 加密媒体的 `file.url` 同样放行（约 2155 行）
+
+原文：
+```python
+            if url and not str(url).startswith("mxc://"):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)
+                return
+```
+改为：
+```python
+            if url and not _is_allowed_media_url(str(url)):
+                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)
+                return
+```
+
+### 补丁 C · 模块顶层新增白名单函数（`class` 定义之前，只加一次）
+
+```python
+# Fmode: 允许容器直接拉取的附件域名。防 SSRF：只放行这一个。
+# 注意：file-cloud.fmode.cn 证书已过期（2026-11-13 实测），不要加回来。
+# 🔴 urlparse 必须在函数内 import —— 本模块顶部只导入了 urljoin/urlsplit/urlunsplit，
+#    裸用 urlparse 会 NameError，被 except 吞掉后**静默返回 False**，附件照旧被拒。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+```
+
+### 补丁 D · 下载分支（`_download_and_cache_media` 第一行，约 2200 行）
+
+原文：
+```python
+        file_bytes = await self._client.download_media(ContentURI(url))
+```
+改为：
+```python
+        if str(url).startswith("https://"):
+            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media
+            file_bytes = await self._fetch_http_media(url, event_id)
+            if file_bytes is None:
+                return None
+        else:
+            file_bytes = await self._client.download_media(ContentURI(url))
+```
+
+### 补丁 E · 新增下载方法（同一 class 内，放在 `_download_and_cache_media` 前面）
+
+```python
+    async def _fetch_http_media(self, url: str, event_id: str):
+        """Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。"""
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=600)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=600, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+```
+
+> 每一处都对应一次实测踩坑：双后端（裸 python3 没依赖、venv 里有）；`allow_redirects=False`（否则白名单域 302 到内网即绕过 SSRF）；**流式累加计数**（`content_length` 在 chunked 下是 `None`，用它判上限等于没判）。
+
+---
+
+## 四、执行步骤（宿主机 root）
+
+```bash
+CTR=<按 §一 的 AGENT_ID 反查出的容器 ID，不要用名字>
+T=/opt/hermes/plugins/platforms/matrix/adapter.py
+PY=/opt/hermes/.venv/bin/python          # 🔴 必须用 venv 解释器
+
+# 0. 先核对指纹（§一 的五条），全部对上才继续
+
+# 1. 备份
+docker exec -u root $CTR cp -p $T $T.bak.$(date +%Y%m%d%H%M)
+
+# 2. 打补丁 —— 用精确字符串替换，任一处匹配次数≠1 就整体中止、不写文件
+docker exec -u root $CTR $PY - <<'PYEOF'
+import io
+p = '/opt/hermes/plugins/platforms/matrix/adapter.py'
+s = io.open(p, encoding='utf-8').read()
+
+if '_is_allowed_media_url' in s:
+    raise SystemExit('已打过补丁，中止（避免二次插入）')
+
+# 全部替换对都先算好，任何一个不唯一就整体不写
+reps = [
+    ('        if url and not str(url).startswith("mxc://"):\n'
+     '            logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)\n'
+     '            return',
+     '        if url and not _is_allowed_media_url(str(url)):\n'
+     '            logger.warning("[Matrix] Rejecting inbound media %s with non-allowed URL: %s", event_id, url)\n'
+     '            return'),
+    ('            if url and not str(url).startswith("mxc://"):\n'
+     '                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-MXC URL", event_id)\n'
+     '                return',
+     '            if url and not _is_allowed_media_url(str(url)):\n'
+     '                logger.warning("[Matrix] Rejecting inbound encrypted media %s with non-allowed URL: %s", event_id, url)\n'
+     '                return'),
+    ('        file_bytes = await self._client.download_media(ContentURI(url))',
+     '        if str(url).startswith("https://"):\n'
+     '            # Fmode: 附件直读个人存储（s3.fmode.cn），不经 Matrix media\n'
+     '            file_bytes = await self._fetch_http_media(url, event_id)\n'
+     '            if file_bytes is None:\n'
+     '                return None\n'
+     '        else:\n'
+     '            file_bytes = await self._client.download_media(ContentURI(url))'),
+]
+for a, _ in reps:
+    if s.count(a) != 1:
+        raise SystemExit('匹配次数异常（%d 次），中止：%r' % (s.count(a), a[:60]))
+for a, b in reps:
+    s = s.replace(a, b, 1)
+
+HELPER = '''# Fmode: 允许容器直接拉取的附件域名。防 SSRF：只放行这一个。
+# 注意：file-cloud.fmode.cn 证书已过期（2026-11-13 实测），不要加回来。
+# 🔴 urlparse 必须在函数内 import —— 模块顶部没有导入它，裸用会 NameError 被吞成 False。
+_FMODE_MEDIA_HOSTS = {"s3.fmode.cn"}
+
+
+def _is_allowed_media_url(u: str) -> bool:
+    """mxc:// 一律放行；https:// 只放行个人存储白名单域名。"""
+    if u.startswith("mxc://"):
+        return True
+    if not u.startswith("https://"):
+        return False
+    try:
+        from urllib.parse import urlparse
+
+        return (urlparse(u).hostname or "").lower() in _FMODE_MEDIA_HOSTS
+    except Exception:
+        return False
+
+
+'''
+i = s.index('\n\nclass ')
+s = s[:i] + '\n\n' + HELPER.rstrip('\n') + '\n' + s[i:]
+
+FETCH = '''    async def _fetch_http_media(self, url: str, event_id: str):
+        """Fmode: 从个人存储（https）流式拉取附件。超限/失败返回 None。"""
+        if not _is_allowed_media_url(url):
+            logger.warning("[Matrix] Refusing non-allowed media URL %s: %s", event_id, url)
+            return None
+        limit = self._max_media_bytes or 0
+
+        async def _read_aiohttp():
+            import aiohttp
+            timeout = aiohttp.ClientTimeout(total=600)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url, allow_redirects=False) as resp:
+                    if resp.status != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.content.iter_chunked(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        async def _read_httpx():
+            import httpx
+            async with httpx.AsyncClient(timeout=600, follow_redirects=False) as hc:
+                async with hc.stream("GET", url) as resp:
+                    if resp.status_code != 200:
+                        logger.warning("[Matrix] HTTP media fetch failed %s: %s", event_id, resp.status_code)
+                        return None
+                    buf = bytearray()
+                    async for chunk in resp.aiter_bytes(64 * 1024):
+                        buf.extend(chunk)
+                        if limit and len(buf) > limit:
+                            logger.warning("[Matrix] Rejecting oversized HTTP media %s", event_id)
+                            return None
+                    return bytes(buf)
+
+        try:
+            return await _read_aiohttp()
+        except ImportError:
+            return await _read_httpx()
+        except Exception as e:
+            logger.warning("[Matrix] HTTP media download error %s: %s", event_id, e)
+            return None
+
+'''
+anchor = '    async def _download_and_cache_media('
+if s.count(anchor) != 1:
+    raise SystemExit('找不到 _download_and_cache_media，中止')
+s = s.replace(anchor, FETCH + anchor, 1)
+
+io.open(p, 'w', encoding='utf-8').write(s)
+print('patched ok')
+PYEOF
+
+# 3. 语法自检（venv 解释器！）
+docker exec -u root $CTR $PY -m py_compile $T && echo SYNTAX_OK
+
+# 4. 重启 gateway（s6 托管）
+docker exec -u root $CTR s6-svc -r /run/s6/services/main-hermes
+```
+
+---
+
+## 五、验收（🔴 不数 grep，要真实调用）
+
+### 5.1 文件层回读（外壳只能说明「文件变了」，不能说明「逻辑对了」）
+
+```bash
+docker exec -u root $CTR stat -c '%s %y' $T                     # 大小应从 170062 变大
+docker exec -u root $CTR md5sum $T
+docker exec -u root $CTR grep -c "_is_allowed_media_url" $T     # 应为 4
+```
+
+### 5.2 逻辑层回读（**决定性**，务必在真实模块命名空间里调函数）
+
+```bash
+docker exec -u root $CTR $PY - <<'PYEOF'
+import importlib.util, sys
+sys.path.insert(0, '/opt/hermes')
+spec = importlib.util.spec_from_file_location(
+    'matrix_adapter_probe', '/opt/hermes/plugins/platforms/matrix/adapter.py')
+m = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(m)
+f = m._is_allowed_media_url
+cases = {
+    'https://s3.fmode.cn/a.txt': True,
+    'https://s3.fmode.cn.evil.com/a.txt': False,
+    'https://evil.com/s3.fmode.cn': False,
+    'https://s3.fmode.cn@evil.com/a': False,
+    'http://s3.fmode.cn/a': False,
+    'https://sub.s3.fmode.cn/a': False,
+    'mxc://fmode.cn/abc': True,
+}
+bad = 0
+for u, want in cases.items():
+    got = f(u)
+    ok = (got == want)
+    bad += 0 if ok else 1
+    print(('PASS' if ok else 'FAIL'), u, '->', got, '(期望', want, ')')
+print('ALL_PASS' if bad == 0 else 'HAS_FAIL %d' % bad)
+PYEOF
+```
+
+**必须打印 `ALL_PASS`。** 只出现 `PASS` 但结果全是 `False` 也是坏的（正是第一版的坑：`urlparse` 未导入 → NameError 被吞 → 全部返回 False）。
+所以**逐行看 `s3.fmode.cn` 那条是不是 `True`**，不能只看「拒绝得都对」。
+
+### 5.3 端到端（App 侧脚本跑，这才是最终判据）
+
+App 侧会执行：
+
+```bash
+node scripts/probe-url-attachment.mjs
+```
+
+它做的是：真实上传一个文件到 `https://s3.fmode.cn/user/...` → 发 `m.file`（`content.url` = 该地址）→ 追问容器文件里的**随机指纹码** → 容器能原样复述即判 ✅。
+
+---
+
+## 六、持久化（请一并处理）
+
+`adapter.py` 在 **overlay 根分区**，`/opt/data` 才是唯一持久卷。即：`docker restart` 保留，**`docker rm` + 重建即丢补丁**，丢后日志只有 `non-allowed URL`，极难联想到补丁没了。
+
+**当前阶段请采用方案 ①**（不改镜像、只改这一台）：
+
+> 重建容器时加 `--entrypoint /opt/data/<补丁目录>/entry.sh`，脚本里先执行打补丁（幂等：已打过就跳过）再 `exec` 原入口。
+
+镜像级固化（`fmode/agent-node:0.21.3`）属舰队升级动作，**本阶段不做**，等这条通道端到端跑顺后再单独走升级流程。
+
+---
+
+## 七、回给 App 侧的内容（照抄这四项）
+
+1. §一 指纹核对的**原始输出**（五条）；
+2. §五.1 文件层回读的**原始输出**；
+3. §五.2 逻辑层回读的**完整输出**（必须出现 `ALL_PASS`，且 `https://s3.fmode.cn/a.txt -> True`）；
+4. `docker exec ... s6-svc -r ...` 的重启时间。
+
+**不要只回「已改好」。** 前两轮都是这么回的，实测文件一个字节没动。

docs/03-interface/给任意容器-文件收发逻辑自查与改造提示词-20261113.md

@@ -0,0 +1,390 @@
+# 给任意 Hermes 容器：文件收发逻辑自查与改造提示词
+
+> 版本：v1.0 · 2026-11-13
+> 适用对象：**任意接入 Fmode 的 Hermes 容器**（各容器状态可能不同，必须先自查再改）
+> 配套文档：《附件只传S3链接-完整实施与验收流程-20261113.md》
+> 参考实现：`agent-node-lj-test`（已完成，端到端验证通过）
+
+---
+
+## 〇、先读这段（给执行者）
+
+**不要照抄任何补丁。** 每台容器的版本、插件、已有改动都不一样。
+本流程是：**自查现状 → 比对目标 → 只补差距 → 分层验收**。
+
+🔴 **三条铁律**
+
+1. **先定位，再动手**：确认你操作的是**目标容器**（见 §一），改错容器会导致"改了半天没效果"（已发生 2 次）。
+2. **只改插件层，不改 `/opt/hermes` 上游源码**：上游被镜像覆盖，升级即丢；插件在 `/opt/data` 持久卷，可长期保留。
+3. **验收以"真实调用结果"为准**：不数 grep、不信口头"改好了"。必须让函数在真实模块命名空间里跑一遍、让文件真的走一遍。
+
+---
+
+## 一、定位目标容器（必做，5 分钟）
+
+### 1.1 在容器内核对身份
+
+```bash
+echo "AGENT_ID   = $(grep -E '^[[:space:]]*AGENT_ID=' /opt/data/.env | cut -d= -f2-)"
+echo "MATRIX_USER = $(grep -E '^MATRIX_USER_ID=' /opt/data/.env | cut -d= -f2-)"
+```
+
+**上报这两项给你的编排方，确认与预期一致后再继续。**
+
+> 🔴 命名陷阱：docker 容器名**不等于** `AGENT_ID`。
+> 实测遇到过「docker 名为 `agent-node-lj-test` 的容器，其 `AGENT_ID` 为空，真正的目标容器 docker 名是 `agent-node-u19170119836`」。
+> **只认 `AGENT_ID` + `MATRIX_USER_ID`，不要认 docker 名。**
+
+### 1.2 在宿主机反查（如果由宿主机侧操作）
+
+```bash
+for c in $(docker ps -q); do
+  v=$(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' $c | grep '^AGENT_ID=')
+  [ -n "$v" ] && echo "$c  $v"
+done
+```
+
+恰好一台命中才是目标。
+
+---
+
+## 二、现状自查（逐项打勾，把原始输出贴出来）
+
+### 2.1 入站：用户发来的文件（App → 容器）
+
+App 现在发的是：**`m.file` / `m.image` 事件，`content.url` = `https://s3.fmode.cn/...`**，文件本体**不进 Matrix**。
+
+```bash
+F=/opt/hermes/plugins/platforms/matrix/adapter.py
+echo "--- 是否有 https 白名单函数 ---"
+grep -n "_is_allowed_media_url\|_FMODE_MEDIA_HOSTS" $F
+echo "--- 是否有 https 下载实现 ---"
+grep -n "_fetch_http_media\|allow_redirects" $F
+echo "--- 两处入口是否已放行 https ---"
+grep -n 'startswith("mxc://")\|_is_allowed_media_url(str(url))' $F
+```
+
+**判定表**：
+
+| 输出特征 | 结论 | 要做 |
+|---|---|---|
+| 出现 `_is_allowed_media_url` 且两处入口都用它 | ✅ 入站已改好 | 跳过 §三 |
+| 只有 `startswith("mxc://")` | ❌ 未改 | 做 §三 |
+| 有函数但入口仍写 `startswith("mxc://")` | ⚠️ 改了一半 | 做 §三，先跑 §五.2 验证函数本身是否可用 |
+
+### 2.2 出站：容器产出的文件（容器 → App）
+
+**目标形态**：产出文件必须 **上云 → 在正文给 `**已上云（可直接下载）**` + https 链接**，**不得**通过 Matrix 发文件本体。
+
+```bash
+echo "--- 上云注入插件是否启用 ---"
+ls /opt/data/plugins/ | grep -i deliverable
+grep -n "已上云" /opt/data/plugins/plugin-deliverable-inject/__init__.py 2>/dev/null | head -3
+
+echo "--- 老路：MEDIA 标记是否会触发 Matrix 上传 ---"
+grep -n "_send_local_file\|Couldn't deliver" /opt/hermes/plugins/platforms/matrix/adapter.py | head
+
+echo "--- 现有 MEDIA 清洗覆盖范围 ---"
+grep -rn "MEDIA:" /opt/data/plugins/*/__init__.py | head -10
+```
+
+**判定表**：
+
+| 输出特征 | 结论 | 要做 |
+|---|---|---|
+| 有 `plugin-deliverable-inject` 且正文出现 `**已上云（可直接下载）**` | ✅ 上云链路在 | §四 第 2 步 |
+| 存在 `_send_local_file` 且正文会带 `MEDIA:` | ❌ 老路仍活 | §四 第 1 步（必须） |
+| 清洗正则只覆盖 `/opt/data`、`/tmp`、`/home` | ⚠️ 覆盖不全 | §四 第 1 步 |
+
+### 2.3 解释器与重启方式（改之前必须确认）
+
+```bash
+echo "--- venv 解释器 ---"
+ls -l /opt/hermes/.venv/bin/python*
+echo "--- gateway 服务名（决定用哪个 s6 路径） ---"
+pgrep -af "s6-supervise" | head
+ls /run/service/ 2>/dev/null || ls /run/s6/services/ 2>/dev/null
+```
+
+> 🔴 **各容器服务名可能不同**。实测有的叫 `main-hermes`，有的叫 `gateway-default`。
+> 用错路径重启**不会报错**，但补丁不生效 —— 这是「改了没反应」的常见原因。
+> 重启命令形如：`s6-svc -r /run/service/<你的实际服务名>`
+
+---
+
+## 三、入站改造（用户发来的 https 附件）
+
+### 3.1 需要改的位置
+
+| 位置 | 改什么 |
+|---|---|
+| 模块顶层 | 新增白名单函数 `_is_allowed_media_url()` |
+| `_handle_media_message` 开头 | 两处 `startswith("mxc://")` → 调白名单函数 |
+| `_download_and_cache_media` | 增加 https 分支，调 `_fetch_http_media()` |
+| class 内 | 新增 `_fetch_http_media()`（流式下载） |
+
+完整代码见《附件只传S3链接-完整实施与验收流程-20261113.md》§4.2。
+
+### 3.2 五个必须避开的坑（都实测踩过）
+
+| # | 坑 | 现象 | 正确做法 |
+|---|---|---|---|
+| 1 | **`urlparse` 未导入** | `NameError` 被 `except` 吞 → 函数恒返回 `False` → 附件照旧被拒，**日志只显示 non-allowed URL** | 在**函数内** `from urllib.parse import urlparse` |
+| 2 | **用错解释器** | 裸 `/usr/bin/python3` 无 aiohttp/httpx → 判断"依赖缺失" | 一律 `/opt/hermes/.venv/bin/python` |
+| 3 | **白名单含证书过期域名** | `file-cloud.fmode.cn` 证书已过期 → 必然失败 | 只放 `s3.fmode.cn` |
+| 4 | **用 `content_length` 判大小** | chunked 响应时为 `None` → 上限失效，可能打满磁盘 | **流式累加计数**，超限断流 |
+| 5 | **跟随重定向** | 白名单域 302 到内网 → SSRF 绕过 | `allow_redirects=False` |
+
+### 3.3 幂等要求
+
+脚本必须：**已打过就跳过**，匹配次数 ≠ 1 就整体中止、不写文件。
+（实测踩过：第二次执行把方法体截断，产生 `IndentationError`。）
+
+---
+
+## 四、出站改造（容器产出的文件）
+
+### 4.1 第 1 步：切断 Matrix 回发文件的老路（**必做**）
+
+**原理**：Agent 在回复里写 `MEDIA:<本地路径>` 时，gateway 会解析出 `media_files` 并调：
+- `send_video()` / `send_image_batch()` / `send_document()` → **把文件本体上传进 Matrix**
+- 路径不存在 → 发 `⚠️ Couldn't deliver the xxx attachment.`
+
+这与「不经 Matrix 传文件」的要求冲突，必须切断。
+
+> 🔴🔴 **执行前必读的硬约束（2026-11-13 在 lj-test 上实测确证）**
+>
+> Hermes 的 `transform_llm_output` 钩子是 **first non-None wins + break**
+> （`/opt/hermes/agent/turn_finalizer.py:427-429`）：
+>
+> - 同一 hook 的所有插件拿到**同一份** `response_text`，彼此**看不到**对方的修改；
+> - 返回值只收集进 list，**只有第一个返回非 None 的生效**，然后直接 break。
+>
+> **⇒ 两个插件各注册一个 `transform_llm_output` 无法串联。**
+> 如果你已经有插件在用这个钩子（如 `plugin-deliverable-inject` 负责注入「已上云」段），
+> 剥离逻辑**必须合并进同一个回调**，且顺序是：
+>
+> ```
+> ① 先剥离 MEDIA 标记  →  ② 再注入 **已上云（可直接下载）** + https 链接
+> ```
+>
+> 顺序反了会把刚注入的链接一并删掉。
+
+**做法（推荐：插件层，不动上游代码）**
+
+在已启用的 `transform_llm_output` 插件的 handling 开头（**注入之前**）剥离**所有** `MEDIA:` 标记：
+
+```python
+# 剥离语义（四条，缺一不可）：
+# ① 行首 MEDIA:<任意路径> → 整行删除
+#    🔴 不限前缀：不能只覆盖 /opt/data、/tmp、/home，必须覆盖 /opt/hermes、/srv、
+#       Windows 盘符 `C:\...` 等（lj-test 上旧正则就漏了这些）
+# ② 行内 MEDIA:<path> → 只删标记+路径 token，保留同行其余文字
+#    （如「附件 MEDIA:/srv/a.png 请查收」→「附件  请查收」）
+# ③ 绝不触碰 **已上云（可直接下载）** 段与其中的 https 链接
+# ④ 幂等：无 MEDIA 标记时返回 None（表示"无改动"，交给上层判断）
+```
+
+**验收用例（lj-test 实测，必须全过）**：
+
+| 输入 | 期望 |
+|---|---|
+| `MEDIA:/opt/data/work/a.pdf` | 标记 + 路径都没了 |
+| `MEDIA:/opt/hermes/x.mp4` | 同上（这是旧正则漏的） |
+| `附带文件 MEDIA:/srv/foo.png 请查收` | 只剩「附带文件  请查收」（行内删） |
+| 含「已上云」段 + https 链接的正常回复 | **返回 None**，内容原样不动 |
+
+> 第 4 行对应的完整输入形如：
+> `结果如下` ⏎⏎ `**已上云（可直接下载）**` ⏎ `- https://s3.fmode.cn/user/x/chat/a.pdf`
+
+**为什么改插件而不改 `/opt/hermes`**：
+
+| | 改上游 `adapter.py` | 改插件 `/opt/data/plugins/` |
+|---|---|---|
+| 镜像升级 | ❌ 被覆盖 | ✅ 保留 |
+| 持久化 | ❌ overlay，重建即丢 | ✅ 持久卷 |
+| 风险 | 影响所有走该 adapter 的行为 | 隔离 |
+
+> 注意：上游 `base.py` 还有 `extract_local_files()`（从正文捡**裸路径**）。
+> 所以配套纪律：**Agent 回复正文不得出现裸本地路径**，只给 https 链接。
+
+### 4.2 第 2 步：确保上云注入正常工作
+
+```bash
+# 检查状态文件是否在产出
+ls -la /opt/data/cache/deliverable-hook/ | tail -5
+```
+
+期望：Agent 产出文件后，正文末尾出现：
+
+```
+
+**已上云（可直接下载）**
+- https://s3.fmode.cn/...
+```
+
+若没有，检查 `plugin-deliverable-inject` 是否启用、状态文件是否写入。
+
+---
+
+## 四·补、🔴 改法禁忌与「先把容器保住」铁律
+
+> 以下全部来自 2026-11-13 两个容器（`agent-node-lj-test`、`agent-node-kangshifu`）的实战教训。
+
+### 4b.1 绝对禁止的改法
+
+| ❌ 禁止 | 为什么 | 真实后果 |
+|---|---|---|
+| **Monkey Patch 替换整个上游方法** | 复制了上游方法体 → 上游升级即静默失效；自己实现有 bug → 整条链路挂 | kangshifu 替换 `_handle_media_message` + `_download_and_cache_media` 后，**连普通文字对话都不回了** |
+| **同时替换多个方法** | 影响面叠加，任意一个出错全盘皆输 | 同上 |
+| **没有 try/except 的补丁** | 异常冒到 gateway 层，拖垮整个 adapter | 同上 |
+| **复制上游方法体再改** | 你改的可能是旧版本，上游行为已变 | 改完"自测通过"，线上仍不对 |
+| **只在容器内自测就宣布完成** | 自测的前提是「容器能工作」，而问题恰恰可能是它不能工作 | 报告写「三层验收全 PASS」，App 侧实测连消息都收不到 |
+
+### 4b.2 正确的最小改动原则
+
+```
+✅ 只在「入口判断」放行 https，下载复用上游已有的安全实现
+❌ 不要替换整个方法
+
+若上游已有 _download_external_media_with_cap（含 SSRF 校验、逐跳重定向拦截、流式限流）：
+   → 新白名单判定的写法应是：
+     if url and not (str(url).startswith("mxc://") or _is_allowed_media_url(str(url))):
+   → 下载阶段只加一个分支调用它，不复制它的实现
+```
+
+> 🔴 **先查上游有没有现成的安全下载器，再决定自己写不写。**
+> `agent-node-kangshifu` 发现了上游的 `_download_external_media_with_cap`，这个判断是对的；
+> 但它随后**替换了整个方法**，反而把容器弄坏了。
+
+### 4b.3 保命顺序（必须遵守）
+
+改任何东西之前，先回答这个问题：**如果改坏了，我怎么在 5 分钟内恢复？**
+
+```bash
+# 改之前必做：
+cp -p <目标文件> <目标文件>.bak.$(date +%Y%m%d%H%M)
+echo "备份路径: <目标文件>.bak.<时间戳>"   # 写进交接记录
+```
+
+**故障时优先级**：**容器能正常对话 > 附件功能可用**。
+宁可附件暂时不可用，也不能让容器连话都说不了。
+
+回滚清单（按顺序执行，每步后验证）：
+1. 禁用所有新增插件（`plugins.enabled` 移除）
+2. 恢复被改文件的备份
+3. 重启 gateway
+4. **用外部客户端发一句「1+1 等于几」**，收到「2」才算恢复
+
+### 4b.4 常见连环坑
+
+| 坑 | 现象 | 处置 |
+|---|---|---|
+| **插件不登记 = 没装** | 建了目录、写了 `plugin.yaml`，但没进 `plugins.enabled` → 完全不生效，**且没有任何报错** | 必须登记后重启；用 `grep 插件名 config.yaml` 确认 |
+| **`s6-svc -r` 会打断自己这一回合** | 重启 gateway 时，正在执行命令的这个 agent 回合被中断 | 重启命令建议**放在回合最后**，或让外部触发 |
+| **测试 state 文件缺 `ts` 字段被静默过滤** | 自己造的测试状态文件不生效，以为代码坏了 | 状态文件必须带 `ts`（时间戳），否则被过滤 |
+| **venv 解释器** | 各容器不一定相同：有的 venv 里有 aiohttp，有的没有 | 先 `ls -l /opt/hermes/.venv/bin/python*`，再 `$PY -c "import aiohttp"` 实测 |
+| **s6 服务名不同** | `main-hermes` / `gateway-default` 各容器不一样 | `pgrep -af s6-supervise` 确认实际名字 |
+
+---
+
+## 五、验收（三层，缺一层都不算过）
+
+### 5.1 第一层：文件变了
+
+```bash
+F=/opt/hermes/plugins/platforms/matrix/adapter.py
+stat -c '%s %y' $F                 # 大小应变大、时间应为今天
+grep -c "_is_allowed_media_url" $F # 应为 4（函数定义 1 + 两处调用 2 + 下载内 1）
+```
+
+### 5.2 第二层：逻辑对了（**决定性**，不能只数 grep）
+
+```bash
+/opt/hermes/.venv/bin/python - <<'PY'
+import importlib.util, sys
+sys.path.insert(0, '/opt/hermes')
+spec = importlib.util.spec_from_file_location('probe', '/opt/hermes/plugins/platforms/matrix/adapter.py')
+m = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = m          # 🔴 必须注册，否则 @dataclass 解析报错
+spec.loader.exec_module(m)
+f = m._is_allowed_media_url
+cases = {
+    'https://s3.fmode.cn/a.txt': True,          # 🔴 这一条必须是 True
+    'mxc://fmode.cn/abc': True,
+    'https://s3.fmode.cn.evil.com/a': False,
+    'https://evil.com/s3.fmode.cn': False,
+    'https://s3.fmode.cn@evil.com/a': False,
+    'http://s3.fmode.cn/a': False,
+    'https://sub.s3.fmode.cn/a': False,
+    'file:///etc/passwd': False,
+}
+bad = 0
+for u, want in cases.items():
+    got = f(u)
+    ok = got == want
+    bad += 0 if ok else 1
+    print('PASS' if ok else 'FAIL', u, '->', got, '(期望', want, ')')
+print('ALL_PASS' if bad == 0 else f'HAS_FAIL {bad}')
+PY
+```
+
+**必须打印 `ALL_PASS`，且 `s3.fmode.cn` 那条是 `True`。**
+⚠️ 只看"拒绝得都对"不够 —— 第一版补丁就是全返回 `False` 所以"拒绝得很对"，但合法链接也被拒了。
+
+### 5.3 第三层：端到端
+
+**入站**：App 侧发一个文件（只带 S3 链接）→ 容器能读到内容。
+
+**判据：查容器自己的消息库**（⚠️ 不要用"在某房间回话"判断，容器可能回在别的 session）：
+
+```bash
+/opt/hermes/.venv/bin/python -c "
+import sqlite3
+n=sqlite3.connect('/opt/data/state.db').execute(
+  \"select count(*) from messages where content like '%<指纹码>%'\").fetchone()[0]
+print('DBHIT' if n else 'DBMISS', n)"
+```
+
+**出站**：让 Agent 产出一个小文件 → 确认：
+- 回复正文**没有** `MEDIA:` 字样
+- 有 `**已上云（可直接下载）**` + https 链接
+- **没有** `⚠️ Couldn't deliver...`
+
+---
+
+## 六、持久化
+
+`/opt/hermes` 在 overlay 根分区，`/opt/data` 是唯一持久卷。
+
+| 场景 | 结果 |
+|---|---|
+| 改插件 `/opt/data/plugins/` | ✅ 天然持久 |
+| 改 `/opt/hermes/...` | ❌ `docker rm` + 重建即丢 |
+| `docker restart` | ✅ 都保留 |
+
+**若必须改上游**：重建容器时加 `--entrypoint /opt/data/<补丁目录>/entry.sh`，脚本先幂等打补丁再 `exec` 原入口（已经验证可行）。
+
+---
+
+## 七、回交给编排方的四项
+
+1. §一 的 **`AGENT_ID` / `MATRIX_USER_ID`** 原始输出
+2. §五.1 文件层回读的**全部原始输出**
+3. §五.2 逻辑层回读的**完整输出**（必须出现 `ALL_PASS`）
+4. §五.3 端到端结果（`DBHIT` + 出站正文样本）
+
+**不要只回「已改好」。** 之前两轮都是这么回的，实测文件一个字节没动。
+
+---
+
+## 八、给 Agent 的回复纪律（配套要求）
+
+改造后 Agent 必须遵守：
+
+| 要求 | 说明 |
+|---|---|
+| ❌ 禁止在正文写 `MEDIA:/路径` | 老路已切断，写了也不会发出去 |
+| ❌ 禁止把本地路径暴露给用户 | 用户点不开 `/opt/data/...` |
+| ✅ 产出文件后：上云 → 正文给 `**已上云（可直接下载）**` + https 链接 | 唯一正确形态 |
+| ✅ 引用用户发来的文件：直接用 `media_urls` 里的本地缓存路径处理 | 入站已由 App 保证只给 S3 链接 |

docs/03-interface/附件只传S3链接-完整实施与验收流程-20261113.md

@@ -0,0 +1,348 @@
+# 附件「只传 S3 链接、不经 Matrix/应用服务器」完整实施与验收流程
+
+> 版本：v1.0 · 2026-11-13
+> 适用：Fmode 双端 App（fmode-app-v2）+ Hermes 容器（任意接入 Agent）
+> 状态：**已在 `agent-node-lj-test` 端到端验证通过**（实测证据见 §六）
+
+---
+
+## 一、需求解读（先对齐「要做什么、不要做什么」）
+
+客户原话（刘雨飏 2026-11-13）：
+
+> 这个功能要直接用之前设计好的，走用户的个人 storage 上传 s3 的附件
+> 一定不能经过 matrix 和任何我们的服务器节点
+> 禁止通过应用服务器传附件，只允许收发 cdn/obs 地址。
+
+### 1.1 三句约束各自管什么
+
+| 约束 | 管的是 | 落地要求 |
+|---|---|---|
+| 走用户个人 storage | **存哪里** | 上传落到 `s3.fmode.cn/user/<userId>/chat/<yyyyMM>/`，不是平台公共目录 |
+| 不能经过 matrix / 我们的服务器节点 | **传输路径** | 文件字节流**不得**经过 Matrix 媒体库，也不得经过任何中转服务器 |
+| 只允许收发 cdn/obs 地址 | **传输内容** | App 与容器之间**只传一个 URL 字符串** |
+
+### 1.2 一个常见误解，先澄清
+
+> **「不能经过服务器」≠「容器不能下载文件」。**
+
+容器要处理文件，必须有本地文件路径，所以**容器自己去 S3 下载**是必须的一步，而且**完全符合要求**——
+因为发起方是容器自己（拉取），中间没有任何应用服务器在搬运字节。
+
+**判定标准只有一条：任何一方的应用服务器，都不应该出现"接收文件 → 转存 → 再转发"的行为。**
+
+### 1.3 改造前后对比
+
+| | 改造前（双写） | 改造后 |
+|---|---|---|
+| 文件存几处 | **两处**：OBS + Matrix 媒体库 | **一处**：只有 OBS |
+| Matrix 收到什么 | 完整文件（`uploadContent`） | 一个 URL 字符串 |
+| 容器怎么拿文件 | 用 bot 登录态从 Matrix 下载（`mxc://`） | **直接从 `https://s3.fmode.cn/...` 下载** |
+| 带宽 | 文件走两遍（OBS 一遍 + Matrix 一遍） | 只走一遍 |
+| 换设备/刷新 | Matrix 清理媒体后失效 | 长期有效（云盘链接） |
+
+---
+
+## 二、端到端链路（目标形态）
+
+```
+① 用户选文件
+     ↓  （文件字节流 → 只有这一条，直传 OBS）
+② 云函数 AlP56LCKFm 签发预签名 URL
+     ↓
+③ 浏览器直接 PUT 到 OBS → https://s3.fmode.cn/user/<uid>/chat/<yyyyMM>/xxx
+     ↓
+④ App 发 Matrix 事件 m.file / m.image
+      content.url = 上一步的 https 地址       ← 只有字符串，没有文件字节
+     ↓
+⑤ 容器收到事件 → 白名单校验 → 用自己的网络直接 GET 该 https 地址
+     ↓
+⑥ 落到容器本地缓存 /opt/data/cache/documents/... → 交给 Agent 读取
+```
+
+**审计检查点**：④ 那一步发出去的事件 content 里，**只有 url 字符串**，没有任何文件内容编码（没有 base64、没有 multipart、没有 `file` 字段）。
+
+---
+
+## 三、App 侧改动清单
+
+### 3.1 核心：新增 `sendFileByUrl()`，不再上传
+
+`src/app/core/matrix-client.service.ts`
+
+```ts
+async sendFileByUrl(roomId, url, card, threadRootId?, lastEventId?, extra?) {
+  // 🔴 只认云盘域名（白名单），防止任意 https 混进来
+  if (!isAllowedMediaUrl(url)) throw new Error('附件地址无效（必须为云盘 https 地址）');
+
+  const content = {
+    msgtype: isImage ? 'm.image' : 'm.file',
+    body: card.name,     // 显示名
+    url,                 // ← 就是 S3 链接，不做上传
+    info: { mimetype: card.mimeType, size: card.size },
+    'com.fmode.cloud_url': url,   // 兼容只认这个字段的旧回读逻辑
+    ...thread / extra
+  };
+  return c.sendEvent(roomId, 'm.room.message', content);
+  // ⚠️ 全程没有 uploadContent()
+}
+```
+
+### 3.2 模式开关（可回退，无需发版）
+
+`src/app/core/send-mode.ts`
+
+```ts
+export function currentSendMode(): 'url' | 'mxc' {
+  return localStorage.getItem('fmode.sendMode') === 'mxc' ? 'mxc' : 'url';
+}
+```
+
+- 默认 `'url'`：只发链接（目标形态）
+- `localStorage.fmode.sendMode = 'mxc'`：回到旧的"传文件进 Matrix"（**仅用于容器补丁未落地时的应急回退**）
+
+### 3.3 统一出口
+
+`src/app/core/chat.service.ts`
+
+```ts
+async sendCloudFile(roomId, file, cloudUrl, card, threadRootId?, extra?) {
+  if (currentSendMode() === 'mxc') {
+    return this.mx.sendFile(...);          // 旧路径，仅有此一处会 uploadContent
+  }
+  if (!cloudUrl) throw new Error('尚未上传到个人存储，未发送');
+  return this.mx.sendFileByUrl(roomId, cloudUrl, card, ...);
+}
+```
+
+**调用点必须全部走这一个出口**：单聊 `uploadPending()`、群聊派活 `sendFileToAgent()`、群房间 `groups.ts onFiles()`。
+
+### 3.4 回读解析（容易被漏掉的坑）
+
+`src/app/core/matrix-client.service.ts` 的 `mediaHttpUrl()`：
+
+```ts
+// 顺序：① com.fmode.cloud_url → ② url 本身就是 http(s) → ③ 最后才 mxc:// 转换
+// 🔴 实测：SDK 的 mxcUrlToHttp('https://...') 返回空字符串！
+//    以前对它调一次 = 历史回读时附件整个消失。
+```
+
+**历史回读路径与实时流路径必须共用同一处解析**，否则会出现「刚发的能看到、刷新后没了」。
+
+### 3.5 其他要点
+
+| 项 | 做法 |
+|---|---|
+| 气泡显示 | 只显示文件名/大小/图标，**不渲染 URL 文本**；附件事件 body 为空时也不得要当成正文提取链接 |
+| 预览 | 预览面板内保留「复制在线链接」（`copyUrl()`），这是用户明确要的 |
+| 大小上限 | 按模式取：`url` 模式走云盘口径（200MB），`mxc` 模式走 Matrix `m.upload.size` |
+| 失败语义 | 上传失败**不发事件**；事件发送失败时缓存 `{url,key}` 到暂存项，重试**不重复上传** |
+| 群聊多目标 | `url` 模式下多个容器房间**复用同一上传结果**（原来每个房间各传一份） |
+
+---
+
+## 四、容器侧改动清单（宿主机 root 执行）
+
+### 4.1 为什么要改
+
+容器原版 `adapter.py` 只认 `mxc://`：
+
+```python
+if url and not str(url).startswith("mxc://"):
+    logger.warning("[Matrix] Rejecting inbound media %s with non-MXC URL", event_id)
+    return
+```
+
+`https://` 的直接被丢掉（**静默**，只有一条 warning 日志）。
+
+### 4.2 四处改动
+
+| # | 位置 | 改什么 |
+|---|---|---|
+| A | `_handle_media_message` 开头 | `startswith("mxc://")` → `_is_allowed_media_url(...)` |
+| B | 加密媒体 `file.url` 分支 | 同上 |
+| C | 模块顶层 | 新增 `_FMODE_MEDIA_HOSTS` 白名单 + `_is_allowed_media_url()` |
+| D | `_download_and_cache_media` | 增加 https 分支，调新增的 `_fetch_http_media()` |
+| E | class 内 | 新增 `_fetch_http_media()`（流式下载） |
+
+### 4.3 五个必须踩过的坑（都是实测出来的）
+
+| # | 坑 | 后果 | 正确做法 |
+|---|---|---|---|
+| 1 | **`urlparse` 没导入** | NameError 被 `except` 吞掉 → 全部返回 `False` → 附件照旧被拒，看日志完全看不出 | 在**函数内** `from urllib.parse import urlparse` |
+| 2 | **解释器选错** | 裸 `/usr/bin/python3.13` 没有 aiohttp/httpx/mautrix | 一律用 `/opt/hermes/.venv/bin/python` |
+| 3 | **证书过期的域名留在白名单** | 必然失败且不报错 | `file-cloud.fmode.cn` 证书已过期（2026-11-13 实测），**只放 `s3.fmode.cn`** |
+| 4 | **`content_length` 判大小** | chunked 编码时是 `None`，上限完全失效 → 可能打满磁盘 | **流式累加计数**，超限立即断流 |
+| 5 | **默认跟随重定向** | 白名单域 302 到内网 → SSRF 校验被绕过 | `allow_redirects=False`（httpx 同理） |
+
+### 4.4 容器定位（最容易出错的一步）
+
+> 🔴🔴 **命名陷阱，务必先读**
+>
+> 「`agent-node-lj-test`」是 **AGENT_ID**，**不是 docker 容器名**。
+> 实测中同一批宿主机上**同时存在**下面两个东西，名字极易混淆：
+>
+> | | docker 容器名 | `AGENT_ID`（`/opt/data/.env`） | `MATRIX_USER_ID` |
+> |---|---|---|---|
+> | ✅ **目标** | `agent-node-u19170119836` | `agent-node-lj-test` | `@zgdcmgnqcd:fmode.cn` |
+> | ❌ **不是它** | `agent-node-lj-test` | （空） | `@agent-node-lj-test:fmode.cn` |
+>
+> 2026-11-13 实测中，按 docker 容器名去找，**连续改错两轮**都改到了 ❌ 那台上。
+> 只有 `AGENT_ID` **且** `MATRIX_USER_ID` 两项同时命中，才是目标。
+
+🔴 **不要用容器名找容器。**
+
+**唯一可靠方式：按容器内部的 `AGENT_ID` + `MATRIX_USER_ID` 联合定位。**
+
+```bash
+# 容器内
+echo "AGENT_ID=$(grep -E '^AGENT_ID=' /opt/data/.env | cut -d= -f2-)"
+echo "MATRIX_USER_ID=$(grep -E '^MATRIX_USER_ID=' /opt/data/.env | cut -d= -f2-)"
+```
+
+```bash
+# 宿主机上逐台反查（只应有一台命中）
+for c in $(docker ps -q); do
+  echo "$c $(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' $c | grep '^AGENT_ID=')"
+done | grep 'agent-node-lj-test'
+```
+
+> ⚠️ `adapter.py` 的大小/md5 **不能**用来区分容器——同镜像下所有容器这份文件逐字节相同，只能判断"有没有被改过"。
+
+### 4.5 持久化（必做）
+
+`adapter.py` 在 **overlay 根分区**，不在 `/opt/data` 持久卷：
+
+- `docker restart` / 宿主重启 → **保留**
+- `docker rm` + 重建 → **丢失**，且丢失后日志只有 `non-allowed URL`，极难联想到
+
+**方案①（推荐，不改镜像、只改这一台）**：重建时加 `--entrypoint /opt/data/<补丁目录>/entry.sh`，脚本先幂等打补丁再 `exec` 原入口。
+
+**方案②（舰队级，谨慎）**：固化进 `fmode/agent-node:0.21.3` 镜像。影响所有容器，属升级动作。
+
+---
+
+## 五、验收流程（🔴 不要相信"改好了"）
+
+### 5.1 App 侧
+
+```bash
+npx tsc -p tsconfig.app.json --noEmit     # 类型
+npm test -- --watch=false --browsers=ChromeHeadless   # 单测
+```
+
+必须覆盖的单测（缺一不可）：
+
+1. `sendFileByUrl` 发出的 content：`url` 是云盘地址、**无 `file` 字段**、**不触发 `uploadContent`**
+2. 非白名单域名被拒
+3. `'mxc'` 模式下仍走 `sendFile`
+4. 历史回读：https 附件不会因 `mxcUrlToHttp` 变成空
+5. 附件事件 body 为空时，**正文里不出现 URL 明文**
+6. 云盘上传失败 → 不发任何 Matrix 事件、暂存保留
+
+### 5.2 容器侧（三层，缺一层都不算过）
+
+**第 1 层 · 文件变了**
+
+```bash
+stat -c '%s %y' /opt/hermes/plugins/platforms/matrix/adapter.py   # 大小应变大
+grep -c "_is_allowed_media_url" .../adapter.py                    # 应为 4
+```
+
+**第 2 层 · 逻辑对了（决定性，不能只数 grep）**
+
+```python
+import importlib.util, sys
+sys.path.insert(0, '/opt/hermes')
+spec = importlib.util.spec_from_file_location('probe', '/opt/hermes/plugins/platforms/matrix/adapter.py')
+m = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = m          # 🔴 必须注册，否则 @dataclass 解析报 AttributeError
+spec.loader.exec_module(m)
+print(m._is_allowed_media_url('https://s3.fmode.cn/a.txt'))   # 必须 True
+```
+
+验收用例（必须全过，且 `s3.fmode.cn` 那条是 **True**——只"拒绝得都对"也可能是坏的）：
+
+| 输入 | 期望 |
+|---|---|
+| `https://s3.fmode.cn/a.txt` | **True** |
+| `mxc://fmode.cn/abc` | True |
+| `https://s3.fmode.cn.evil.com/a` | False（后缀伪造） |
+| `https://evil.com/s3.fmode.cn` | False（query 伪造） |
+| `https://s3.fmode.cn@evil.com/a` | False（userinfo 伪造） |
+| `http://s3.fmode.cn/a` | False（非 https） |
+| `https://sub.s3.fmode.cn/a` | False（子域） |
+| `file:///etc/passwd` | False |
+
+**第 3 层 · 端到端真的通了**
+
+向容器发一条 `m.file`（`url` 指向一个**真实存在**的 `https://s3.fmode.cn/...` 文件，内容里埋一个随机指纹码），然后验证容器**真的读到了内容**。
+
+> 🔴 **判据必须落在"容器读到了内容"，而不是"容器在某个房间回了话"。**
+> 实测踩坑：容器可能把回复发到别的 session / 线程，监听房间 Timeline 会**漏判**，
+> 脚本报 ❌ 但实际已经成功。最稳的判据是查容器自己的消息库：
+> ```bash
+> /opt/hermes/.venv/bin/python -c "import sqlite3;print(sqlite3.connect('/opt/data/state.db').execute(\"select count(*) from messages where content like '%<指纹码>%'\").fetchone()[0])"
+> ```
+> 返回 > 0 = 容器确实下载并读到了文件。
+
+### 5.3 审计：确认真的没经过 Matrix
+
+```bash
+# App 侧：默认模式下不应出现任何媒体上传
+grep -rn "uploadContent" src/app --include=*.ts | grep -v spec
+# 只应剩 sendFile() 内部那一处，且该路径仅在 'mxc' 回退模式可达
+```
+
+浏览器 DevTools → Network，发一次文件后检查：**不应有 `/_matrix/media/v3/upload` 请求**。
+
+---
+
+## 六、实测结论（2026-11-13，`agent-node-lj-test`）
+
+| 项 | 结果 | 证据 |
+|---|---|---|
+| 容器收到 https 附件并**自己下载** | ✅ | 容器库 `messages` 表：`[The user sent a text document: 'xxx.txt' ... saved at /opt/data/cache/documents/doc_xxx.txt]` |
+| 容器读到文件内容 | ✅ | Assistant 原样复述出脚本埋的随机指纹码 |
+| 多次探测一致性 | ✅ | 3 次独立探测，指纹码均 `DBHIT` |
+| 同一链接被不同会话各自下载 | ✅ | 证明是容器**自己拉取**，无中转 |
+| 文件是否进入 Matrix 媒体库 | ❌ 没有 | 事件里只有 url 字符串 |
+
+---
+
+## 七、操作清单（照着做）
+
+### 给容器维护方
+
+1. 按 §4.4 **用 `AGENT_ID` 定位**目标容器（先核对，别急着改）
+2. 按 §4.2 打四处补丁（脚本必须幂等：已打过就跳过）
+3. `/opt/hermes/.venv/bin/python -m py_compile adapter.py` 语法自检
+4. 重启 gateway（注意本镜像的服务名是 **`gateway-default`**，不是 `main-hermes`）：
+   `s6-svc -r /run/service/gateway-default`
+5. 按 §5.2 第 2 层跑逻辑验收，**必须出现 `s3.fmode.cn → True`**
+6. 按 §5.2 第 3 层跑端到端，**查容器消息库里的指纹码**
+7. 按 §4.5 做持久化（`entry.sh` 方案）
+
+### 给 App 侧
+
+1. 确认 `currentSendMode()` 默认 `'url'`
+2. 确认所有发附件入口都走 `sendCloudFile()`
+3. 跑 §5.1 的测试
+4. 按 §5.3 做审计
+5. 部署（部署前再次确认）
+
+---
+
+## 八、常见问题
+
+**Q：容器能不能不下载，直接读链接？**
+A：不行。容器要处理文件必须有本地路径，所以必须下载到本地缓存。但**下载是容器自己发起的**，不经过任何中转服务器，符合「不经应用服务器」的要求。
+
+**Q：容器下载会不会占我们的服务器带宽？**
+A：会占用 OBS 的出流量，但**不占用应用服务器**。这是需求要求的形态。
+
+**Q：回退怎么办？**
+A：`localStorage.fmode.sendMode = 'mxc'`，立即回到旧的双写模式，**不需要发版、不需要重启容器**。
+
+**Q：`file-cloud.fmode.cn` 为什么被剔除了？**
+A：证书已过期（2026-11-13 实测）。续签后可加回，只需改白名单一行。

scripts/probe-url-attachment.mjs

@@ -0,0 +1,240 @@
+/**
+ * 探测：容器能否收到「https 云盘地址」的附件（2026-11-13）
+ *
+ * ## 它验证什么
+ *
+ * App 已改为「文件只上个人存储 → 发 `m.file`，`content.url = https://...`」，
+ * 不再把文件传进 Matrix 媒体库。容器侧 `adapter.py` 在补丁落地前会**静默丢弃**
+ * 这种事件（`Rejecting inbound media ... with non-MXC URL`）。
+ *
+ * 本脚本模拟一段完整的真实链路，不依赖浏览器：
+ *   ① 走云函数 `AlP56LCKFm` 拿预签名 → PUT 一个真实文件到个人存储
+ *   ② 与容器建 DM 房间，发一条 `m.file`，url 填 ① 得到的 https 地址
+ *   ③ 听容器回复，判定它是否**读到文件内容**
+ *
+ * ## 用法
+ *
+ *   node scripts/probe-url-attachment.mjs
+ *   node scripts/probe-url-attachment.mjs --agent agent-node-lj-test --wait 180
+ *
+ * 退出码：0 = 容器读到了文件；1 = 没读到（补丁未落地 / 容器离线）；2 = 用法错误
+ *
+ * 🔴 只读探测：不改容器任何东西，会在结束后退出房间。
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const FUNCTIONS_URL = 'https://server.fmode.cn/api/functions';
+const FN_PROVISION = 'RP5Ht55NeX';
+const FN_UPLOAD_URL = 'AlP56LCKFm';
+
+const arg = (name, fallback) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+};
+const AGENT_ID = arg('agent', 'agent-node-lj-test');
+const WAIT_S = Number(arg('wait', '180'));
+
+function loadToken() {
+  const p = join(homedir(), '.fmode', 'config', 'user.json');
+  const t = JSON.parse(readFileSync(p, 'utf8'))?.sessionToken;
+  if (typeof t !== 'string' || !t) throw new Error(`读不到 sessionToken：${p}`);
+  return t;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 发一个云函数请求 */
+async function fn(token, id, params) {
+  const r = await fetch(FUNCTIONS_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id, token, params }),
+  });
+  const j = await r.json();
+  return j.result ?? j;
+}
+
+/** ① 传一个真实文件到个人存储，拿回 https 地址 */
+async function uploadProbeFile(token) {
+  const filename = `probe-${Date.now()}.txt`;
+  const content = `Fmode 附件直读探测 ${new Date().toISOString()}\n指纹码：FMODE-PROBE-${Date.now()}\n`;
+  const body = new TextEncoder().encode(content);
+
+  const ticket = await fn(token, FN_UPLOAD_URL, {
+    filename,
+    mimeType: 'text/plain',
+    size: body.length,
+  });
+  if (ticket?.code !== 200 || !ticket.uploadUrl) {
+    throw new Error(`取预签名失败：${JSON.stringify(ticket).slice(0, 200)}`);
+  }
+  const put = await fetch(ticket.uploadUrl, {
+    method: 'PUT',
+    headers: ticket.headers ?? { 'Content-Type': 'text/plain', 'x-obs-acl': 'public-read' },
+    body,
+  });
+  if (!put.ok) throw new Error(`直传 OBS 失败：HTTP ${put.status}`);
+  const publicUrl = ticket.publicUrl ?? `https://s3.fmode.cn/${ticket.key}`;
+  const fingerprint = content.match(/FMODE-PROBE-\d+/)[0];
+  return { publicUrl, fingerprint, filename };
+}
+
+async function main() {
+  const token = loadToken();
+  const mx = await import('matrix-js-sdk');
+
+  console.log(`目标容器: ${AGENT_ID}`);
+
+  /* ① 先传文件：补丁没落地前也该先确认「上传这一半」是通的 */
+  const { publicUrl, fingerprint, filename } = await uploadProbeFile(token);
+  console.log(`已上传: ${publicUrl}`);
+
+  /* ② 建 DM 房间并等容器进来 */
+  const prov = await fn(token, FN_PROVISION, { agentId: AGENT_ID });
+  if (!prov?.accessToken) throw new Error('provision 失败（容器未接入？）');
+  const c = mx.createClient({
+    baseUrl: prov.homeserver,
+    accessToken: prov.accessToken,
+    userId: prov.userMxId,
+  });
+  const room = (
+    await c.createRoom({
+      invite: [prov.agentMxId],
+      name: `probe-url-${Date.now()}`,
+      preset: mx.Preset.TrustedPrivateChat,
+    })
+  ).room_id;
+  console.log(`房间: ${room}`);
+
+  let joined = false;
+  for (let i = 0; i < 60 && !joined; i++) {
+    const members = await c.getJoinedRoomMembers(room);
+    joined = Object.keys(members.joined ?? {}).includes(prov.agentMxId);
+    if (!joined) await sleep(1000);
+  }
+  if (!joined) throw new Error('容器没有进房，探测无法继续');
+
+  /* ③ 发一条「只看云盘地址」的附件事件：这正是 App 现在发的东西 */
+  let reply = '';
+  const stop = c.on(mx.RoomEvent.Timeline, (ev) => {
+    if (ev.getRoomId?.() !== room) return;
+    if (ev.getType?.() !== 'm.room.message') return;
+    if (ev.getSender?.() === prov.userMxId) return;
+    const body = String(ev.getContent?.()?.body ?? '');
+    if (body) reply += `\n${body}`;
+  });
+
+  const sent = await c.sendEvent(room, mx.EventType.RoomMessage, {
+    msgtype: 'm.file',
+    body: filename,
+    url: publicUrl,
+    info: { mimetype: 'text/plain', size: fingerprint.length },
+  });
+  console.log(`已发送 m.file（url=https）: ${sent.event_id}`);
+
+  const ask = await c.sendEvent(room, mx.EventType.RoomMessage, {
+    msgtype: 'm.text',
+    body: `我刚发了一个附件 ${filename}。请打开它，把里面的「指纹码」原样告诉我；如果没收到附件就回答「没收到附件」。`,
+  });
+  console.log(`已提问: ${ask.event_id}`);
+
+  /* ④ 等回复 */
+  const deadline = Date.now() + WAIT_S * 1000;
+  while (Date.now() < deadline && !reply.includes(fingerprint)) {
+    await sleep(2000);
+  }
+  /*
+   * 🔴 2026-11-13 修复：容器把回复发到哪个房间/线程并不总是本房间的实时事件。
+   * 仅靠 Timeline 监听会**漏判**（实测附件其实已下载成功，脚本却报 ❌）。
+   * 这里在超时后再拉一次房间历史兜底。
+   */
+  if (!reply.includes(fingerprint)) {
+    try {
+      const { chunk } = await c.scrollback(room, 50);
+      for (const ev of chunk) {
+        if (ev.getType?.() !== 'm.room.message') continue;
+        if (ev.getSender?.() === prov.userMxId) continue;
+        const body = String(ev.getContent?.()?.body ?? '');
+        if (body && !reply.includes(body)) reply += `
+${body}`;
+      }
+    } catch {
+      /* 拉历史失败不影响主判定 */
+    }
+  }
+  try {
+    stop();
+  } catch {
+    /* ignore */
+  }
+
+  /*
+   * 🔴 2026-11-13 决定性问题：容器不一定在本房间实时回话。
+   * 最权威的判据是它自己的消息库 —— 指纹码出现在 `messages` 表里，
+   * 就证明「它真的下载并读到了这个文件」（而不是只收到了一个文件名）。
+   * 这一步通过 DM 询问容器代为执行只读查询。
+   */
+  let dbHit = false;
+  if (!reply.includes(fingerprint)) {
+    console.log('\n[兜底] 本房间未等到回复，改查容器自己的消息库（这才是权威判据）…');
+    const dm = (
+      await c.createRoom({
+        invite: [prov.agentMxId],
+        name: `probe-db-${Date.now()}`,
+        preset: mx.Preset.TrustedPrivateChat,
+      })
+    ).room_id;
+    for (let i = 0; i < 60; i++) {
+      const m = await c.getJoinedRoomMembers(dm);
+      if (Object.keys(m.joined ?? {}).includes(prov.agentMxId)) break;
+      await sleep(1000);
+    }
+    let dbReply = '';
+    const onDb = (ev) => {
+      if (ev.getRoomId?.() !== dm) return;
+      if (ev.getSender?.() === prov.userMxId) return;
+      const b = ev.getContent?.()?.body;
+      if (typeof b === 'string') dbReply += '\n' + b;
+    };
+    c.on(mx.RoomEvent.Timeline, onDb);
+    const inquiry =
+      '只读执行下面这条命令，把原始输出原样贴给我（不要解释）：\n' +
+      '/opt/hermes/.venv/bin/python -c "import sqlite3;' +
+      `n=sqlite3.connect('/opt/data/state.db').execute(\"select count(*) from messages where content like '%${fingerprint}%'\").fetchone()[0];` +
+      'print(\"DBHIT\" if n else \"DBMISS\")"';
+    await c.sendEvent(dm, mx.EventType.RoomMessage, { msgtype: 'm.text', body: inquiry });
+    const dl = Date.now() + 150_000;
+    while (Date.now() < dl && !/DBHIT|DBMISS/.test(dbReply)) await sleep(2000);
+    dbHit = /DBHIT/.test(dbReply);
+    console.log(dbReply.trim().slice(0, 400) || '(容器无回复)');
+    try {
+      await c.leave(dm);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const ok = reply.includes(fingerprint) || dbHit;
+  console.log('\n=== 容器回复 ===');
+  console.log(reply.trim() || '(无回复)');
+  console.log('\n=== 判定 ===');
+  if (ok) {
+    console.log('✅ 容器读到了 https 附件内容 —— 补丁已生效');
+  } else {
+    console.log('❌ 容器没读到附件内容。若回复里有「没收到附件」，说明 adapter.py 仍在拒收非 mxc 的 url');
+  }
+
+  try {
+    await c.leave(room);
+  } catch {
+    /* ignore */
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error('探测失败：', e?.message ?? e);
+  process.exit(2);
+});

src/app/components/domain/message-bubble/message-bubble.ts

@@ -84,7 +84,7 @@ import { ToolActivityComponent } from '../tool-activity/tool-activity';
               >
                 <img
                   class="thumb-img"
-                  [src]="file.url"
+                  [src]="file.cloudUrl || file.url"
                   [alt]="file.name"
                   loading="lazy"
                   (error)="thumbBroken.set(true)"
@@ -120,10 +120,10 @@ import { ToolActivityComponent } from '../tool-activity/tool-activity';
                   >
                     <i class="fa-solid fa-expand" aria-hidden="true"></i>
                   </button>
-                  @if (file!.url) {
+                  @if (file!.cloudUrl || file!.url) {
                     <a
                       class="file-act"
-                      [href]="file!.url"
+                      [href]="file!.cloudUrl || file!.url"
                       [attr.download]="file!.name"
                       [attr.aria-label]="'下载 ' + file!.name"
                       title="下载"

src/app/core/api/parse-api.spec.ts

@@ -450,6 +450,72 @@ describe('ParseApi', () => {
     });
   });
 
+  /*
+   * 2026-11-13 用户实测：上传 `3-会话.mp4` 报 403 SignatureDoesNotMatch。
+   *
+   * 实测三组对照（同一文件内容，只差文件名）：
+   *   会话.mp4 / 3-会话.mp4 → 403；test.mp4 → 200
+   * 原因：云函数按原始中文算签名，浏览器请求的是 URL 编码路径，两者对不上。
+   * 处置：送签前把文件名转 ASCII（显示名仍是中文，不影响用户）。
+   */
+  describe('uploadFile · 中文文件名（2026-11-13 实测 403 修复）', () => {
+    let origXhr: unknown;
+    const capture: string[] = [];
+    beforeEach(() => {
+      capture.length = 0;
+      origXhr = (window as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest;
+      (window as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest = function () {
+        const self = {
+          upload: { onprogress: null as unknown },
+          status: 200,
+          onload: null as unknown,
+          onerror: null as unknown,
+          open() {},
+          setRequestHeader() {},
+          send() {
+            (self.onload as () => void)?.();
+          },
+        };
+        return self;
+      };
+    });
+    afterEach(() => {
+      (window as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest = origXhr;
+    });
+
+    /** 截获云函数请求体里的 filename */
+    function spyFilename(): void {
+      const orig = (api as unknown as { callFunction: (...a: unknown[]) => unknown }).callFunction;
+      spyOn(api as never, 'callFunction' as never).and.callFake(((
+        id: string,
+        params: Record<string, unknown>,
+      ) => {
+        if (params['filename']) capture.push(String(params['filename']));
+        return Promise.resolve({ code: 200, uploadUrl: 'u', key: 'k' });
+      }) as never);
+      void orig;
+    }
+
+    it('🔴 中文文件名必须转成 ASCII 再送签', async () => {
+      spyFilename();
+      await api.uploadFile(new File(['x'], '3-会话.mp4', { type: 'video/mp4' }));
+      expect(capture[0]).withContext('文件名里不能有非 ASCII 字符').toMatch(/^[ -~]+$/);
+      expect(capture[0]).not.toContain('会话');
+    });
+
+    it('纯中文名 → file.<ext> 兜底', async () => {
+      spyFilename();
+      await api.uploadFile(new File(['x'], '会话.pdf', { type: 'application/pdf' }));
+      expect(capture[0]).toBe('file.pdf');
+    });
+
+    it('纯 ASCII 名保持原样', async () => {
+      spyFilename();
+      await api.uploadFile(new File(['x'], 'report-2026.pdf', { type: 'application/pdf' }));
+      expect(capture[0]).toBe('report-2026.pdf');
+    });
+  });
+
   // ---------- 交付成果 ----------
 
   describe('fetchDeliverables', () => {

src/app/core/api/parse-api.ts

@@ -538,22 +538,101 @@ export class ParseApi extends FmodeApi {
     };
   }
 
+  /**
+   * 云函数预签名用的安全文件名（2026-11-13 实测修复）。
+   *
+   * 🔴 **中文文件名会让 OBS 返回 403 `SignatureDoesNotMatch`。**
+   *
+   * 实测（同一文件内容，只差文件名）：
+   *   · `会话.mp4`    → 403 SignatureDoesNotMatch
+   *   · `3-会话.mp4`  → 403 SignatureDoesNotMatch
+   *   · `test.mp4`    → 200 ✅
+   *
+   * 原因：云函数按**原始中文**算签名，而浏览器实际请求的路径是
+   * URL 编码后的 `%E4%BC%9A%E8%AF%9D` —— 两者对不上。
+   * 云函数在服务端，前端改不了它的算法，只能在**送签前**把名字转成 ASCII。
+   *
+   * ## 为什么这样不丢信息
+   *
+   * 存到 OBS 的 key 只是**存储标识**；用户看到的文件名来自 message body
+   * （`FileCard.name`，仍是中文），显示、下载名都不受影响。
+   * 这里只保留扩展名，其余字符（含中文）一律替换成下划线，
+   * 并追加一段随机串避免同名覆盖。
+   */
+  private safeStorageName(name: string): string {
+    const dot = name.lastIndexOf('.');
+    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+    const asciiExt = /^[a-z0-9]{1,8}$/.test(ext) ? ext : '';
+    const rawBase = dot > 0 ? name.slice(0, dot) : name;
+    /*
+     * 中文/符号一律替换成 `_`，但**连续替换要折叠**，否则「我的 文档」会变成
+     * 「我的_文档」再被清成空壳。
+     *
+     * 🔴 纯中文名（如「会话.mp4」）转完会是空串 —— 那种情况用 `file` 兜底；
+     *    前半段有 ASCII 的（如「3-会话.mp4」）保留那一段，仍可辨认。
+     */
+    const base = rawBase
+      .replace(/[^A-Za-z0-9_-]+/g, '_')
+      .replace(/_+/g, '_')
+      .replace(/^[_-]+|[_-]+$/g, '')
+      .slice(0, 40);
+    const stem = base || 'file';
+    return asciiExt ? `${stem}.${asciiExt}` : stem;
+  }
+
   async uploadFile(
     file: File,
     onProgress?: (pct: number) => void,
-  ): Promise<{ key: string; publicUrl: string }> {    const ticket = await this.requestUploadUrl(
-      file.name,
-      file.type || 'application/octet-stream',
-      file.size,
-    );
-    // S3 直传（华为云 OBS 兼容 S3 协议）；前端不经手任何 AK/SK
-    const headers: Record<string, string> = {
-      'Content-Type': file.type || 'application/octet-stream',
-      'x-obs-acl': 'public-read',
-      ...ticket.headers,
-    };
-    await this.putWithProgress(ticket.uploadUrl, headers, file, onProgress);
-    return { key: ticket.key, publicUrl: ticket.publicUrl };
+  ): Promise<{ key: string; publicUrl: string }> {
+    /*
+     * 🔴 预签名过期自动重签（2026-11-13 用户实测 60MB 文件 403）。
+     *
+     * 云函数的预签名 URL **只有 5 分钟有效期**（`expiresAt`，实测 300 秒）。
+     * 大文件（60MB+）在慢网下传不完，或用同一个 URL 重试，OBS 一律返回
+     * `403 Forbidden`（签名校验失败），用户只看到「上传失败」。
+     *
+     * 处理：每次尝试**重新取签名**，上传失败且判定为「签名/过期类」错误时重试。
+     * 重试会生成**新的 key**，所以只能整份重传 —— 因此重试次数保守（2 次）。
+     */
+    const MAX_ATTEMPTS = 2;
+    let lastErr: unknown = null;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const ticket = await this.requestUploadUrl(
+        /* 🔴 必须转 ASCII：中文文件名会让 OBS 报 403 SignatureDoesNotMatch（见 safeStorageName） */
+        this.safeStorageName(file.name),
+        file.type || 'application/octet-stream',
+        file.size,
+      );
+      // S3 直传（华为云 OBS 兼容 S3 协议）；前端不经手任何 AK/SK
+      const headers: Record<string, string> = {
+        'Content-Type': file.type || 'application/octet-stream',
+        'x-obs-acl': 'public-read',
+        ...ticket.headers,
+      };
+      try {
+        await this.putWithProgress(
+          ticket.uploadUrl,
+          headers,
+          file,
+          // 重试时进度从 0 重新开始
+          attempt === 0 ? onProgress : (p) => onProgress?.(p),
+        );
+        return { key: ticket.key, publicUrl: ticket.publicUrl };
+      } catch (e) {
+        lastErr = e;
+        const msg = e instanceof Error ? e.message : '';
+        /*
+         * 只重试「可能已过期 / 签名失效」的情况：
+         *   · 403（签名不匹配或已过期）
+         *   · 超时 / 网络错误
+         * 4xx 其它（如 400 参数错误）不重试。
+         */
+        const retryable = /403|超时|网络/.test(msg);
+        if (!retryable || attempt === MAX_ATTEMPTS - 1) throw e;
+        console.warn(`[upload] 第 ${attempt + 1} 次上传失败（${msg}），重新签名后重试`);
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error('上传失败');
   }
 
   // ---------- 成果文件搬运队列 ----------
@@ -800,15 +879,28 @@ export class ParseApi extends FmodeApi {
 
 
   /** PUT 直传；浏览器 XMLHttpRequest 才能拿到上传进度 */
+  /**
+   * 带进度的 PUT 上传。
+   *
+   * @param timeoutMs 整体超时。**必须小于预签名有效期（300 秒）** ——
+   *   一旦超过，服务端签名已失效，继续传也只会 403。
+   */
   private putWithProgress(
     url: string,
     headers: Record<string, string>,
     file: File,
     onProgress?: (pct: number) => void,
+    timeoutMs = 240_000,
   ): Promise<void> {
     return new Promise((resolve, reject) => {
       const xhr = new XMLHttpRequest();
       xhr.open('PUT', url, true);
+      /*
+       * 🔴 超时保护（2026-11-13）：大文件在弱网下可能长时间「正在上传」，
+       * 而预签名 5 分钟就过期 —— 不设上限会让用户白等，
+       * 最终仍以 403 收场。超时后交给上层重签重传。
+       */
+      xhr.timeout = timeoutMs;
       for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
       xhr.upload.onprogress = (e) => {
         if (e.lengthComputable && onProgress) onProgress(Math.round((e.loaded / e.total) * 100));
@@ -818,6 +910,7 @@ export class ParseApi extends FmodeApi {
         else reject(new Error(`上传失败（HTTP ${xhr.status}）`));
       };
       xhr.onerror = () => reject(new Error('上传失败：网络错误'));
+      xhr.ontimeout = () => reject(new Error('上传超时（网络较慢或文件较大）'));
       xhr.send(file);
     });
   }

src/app/core/chat.service.spec.ts

@@ -1,5 +1,5 @@
 import { TestBed } from '@angular/core/testing';
-import { ChatService, isAttachmentEcho } from './chat.service';
+import { ChatService, isAttachmentEcho, isMediaDeliveryFailure } from './chat.service';
 import { setServerUploadLimit } from './upload-limits';
 import { FmodeApi } from './api/fmode-api';
 import { LiveService } from './live.service';
@@ -84,6 +84,10 @@ describe('ChatService', () => {
     sendFile: jasmine
       .createSpy('sendFile')
       .and.returnValue(Promise.resolve({ event_id: '$f' })),
+    /** 2026-11-13 `'url'` 模式：不发文件本体，只发云盘地址 */
+    sendFileByUrl: jasmine
+      .createSpy('sendFileByUrl')
+      .and.returnValue(Promise.resolve({ event_id: '$fu' })),
     setTyping: jasmine.createSpy('setTyping').and.returnValue(Promise.resolve()),
     paginateBack: jasmine.createSpy('paginateBack').and.returnValue(Promise.resolve(true)),
     /** 初次 sync 是否完成（回溯历史前会等它，2026-11-12） */
@@ -203,6 +207,28 @@ describe('ChatService', () => {
       expect(svc.sessions.listFor('agent-node-lj-test').length).withContext('左侧应出现 1 条').toBe(1);
     });
 
+    /*
+     * 2026-11-13 用户实测：点「新建对话」直接显示
+     * 「这个会话的消息暂时没加载出来 / 可能是网络波动」。
+     *
+     * 根因：`backfillSessionTimeline()` 对 `_blankSessionId` 直接 return，
+     * `_reachedRoomStart` 停在 false → 落到 `unloaded` 分支。
+     * 新建会话本来就没有历史，正确语义是 `fresh`（走欢迎页）。
+     */
+    it('🔴 新建会话不能被判成「取不到」（emptyReason 应为 fresh）', async () => {
+      realMode();
+      mxStub.timelineToMessages.and.returnValue([]);
+      apiStub.fetchChatThreads.and.returnValue(Promise.resolve([]));
+      svc.sessions.reset();
+
+      await svc.startBlank('agent-node-lj-test');
+
+      expect(svc.messages().length).toBe(0);
+      expect(svc.emptyReason())
+        .withContext('新建会话应显示欢迎页，不能显示「消息暂时没加载出来」')
+        .toBe('fresh');
+    });
+
     it('指定工作区时归属正确', async () => {
       realMode();
       mxStub.timelineToMessages.and.returnValue([]);
@@ -555,17 +581,19 @@ describe('ChatService', () => {
       mxStub.connectSession.and.returnValue(Promise.resolve());
       mxStub.ensureRoom.and.returnValue(Promise.resolve('!room1:fmode.cn'));
       mxStub.lastMessageEventId.and.returnValue('$base');
-      mxStub.sendFile.and.returnValue(Promise.resolve({ event_id: '$file' }));
+      mxStub.sendFileByUrl.and.returnValue(Promise.resolve({ event_id: '$file' }));
 
       const file = new File(['x'], 'a.png', { type: 'image/png' });
-      const r = await svc.sendFileToAgent('agent-node-lj-test', file, {
-        groupId: 'g1',
-        turnId: 'me-1',
-        targetAgentId: 'agent-node-lj-test',
-      });
+      const r = await svc.sendFileToAgent(
+        'agent-node-lj-test',
+        file,
+        { groupId: 'g1', turnId: 'me-1', targetAgentId: 'agent-node-lj-test' },
+        'https://s3.fmode.cn/k',
+      );
 
       expect(r.ok).withContext('发送应成功').toBe(true);
-      const args = mxStub.sendFile.calls.mostRecent().args;
+      expect(mxStub.sendFile).not.toHaveBeenCalled();
+      const args = mxStub.sendFileByUrl.calls.mostRecent().args;
       const extra = args[5] as Record<string, unknown>;
       expect((extra['com.fmode.dispatch'] as { groupId: string }).groupId).toBe('g1');
       expect(extra['com.fmode.session']).toBe('me-1');
@@ -845,6 +873,87 @@ describe('ChatService', () => {
     });
   });
 
+  /*
+   * 2026-11-13 评审 S4：`'url'` 模式下用户发的附件事件**没有正文**
+   * （body 就是文件名或空）。空正文绝不能掉进「从正文提取链接」分支，
+   * 否则气泡里会明文显示整条云盘地址 —— 用户明确要求不能出现。
+   */
+  describe('附件事件的回读（不泄漏云盘地址）', () => {
+    const mxFile = (body: string, name: string, url: string): MxMessage =>
+      ({
+        roomId: '!room1:fmode.cn',
+        eventId: '$f1',
+        sender: '@me:fmode.cn',
+        body,
+        ts: Date.now(),
+        kind: 'text' as const,
+        live: false,
+        sessionId: 's1',
+        threadId: 'SID',
+        media: { name, url, mimeType: 'application/pdf', size: 10 },
+      }) as MxMessage;
+
+    const cloud = 'https://s3.fmode.cn/user/u1/chat/202611/x-方案.pdf';
+
+    it('🔴 body 为空 + 有附件 → 正文为空，不把地址渲染成文字', async () => {
+      realMode();
+      await svc.open('agent-node-lj-test');
+      const sid = svc.sessionId()!;
+      (svc as unknown as { appendIncoming: (m: MxMessage, me: string) => void }).appendIncoming(
+        { ...mxFile('', '方案.pdf', cloud), threadId: sid, sessionId: sid },
+        '@me:fmode.cn',
+      );
+
+      const f = svc.messages().find((m) => m.file) ?? svc.messages().at(-1);
+      expect(f).withContext('附件卡片必须保留').toBeTruthy();
+      expect(f!.text).withContext('正文不得变成云盘地址').toBeUndefined();
+      expect(f!.file!.url).toBe(cloud);
+    });
+
+    it('body 就是文件名 → 同样不当作正文', async () => {
+      realMode();
+      await svc.open('agent-node-lj-test');
+      const sid = svc.sessionId()!;
+      (svc as unknown as { appendIncoming: (m: MxMessage, me: string) => void }).appendIncoming(
+        { ...mxFile('方案.pdf', '方案.pdf', cloud), threadId: sid, sessionId: sid },
+        '@me:fmode.cn',
+      );
+
+      const f = svc.messages().find((m) => m.file);
+      expect(f!.text).toBeUndefined();
+    });
+  });
+
+  /*
+   * 2026-11-13 用户实测：发 60MB 视频后，容器回了一句
+   * 「⚠️ Couldn't deliver the video attachment.」
+   *
+   * 来源是容器 `matrix/adapter.py:1832` —— 它试图用 **Matrix 回发文件本体** 失败。
+   * 按产品要求容器只该给云盘链接，所以这条提示对用户是纯噪声，必须滤掉。
+   */
+  describe('容器附件投递失败提示（噪声过滤）', () => {
+    it('识别英文兜底文案（含图片/视频/文件各种 kind）', () => {
+      expect(isMediaDeliveryFailure("⚠️ Couldn't deliver the video attachment.")).toBeTrue();
+      expect(isMediaDeliveryFailure("⚠️ Couldn't deliver the image attachment.")).toBeTrue();
+      expect(isMediaDeliveryFailure("⚠️ Couldn't deliver the file attachment.")).toBeTrue();
+      expect(isMediaDeliveryFailure("Couldn't deliver the video attachment.")).toBeTrue();
+    });
+
+    it('正常回复不受影响（不做模糊匹配，避免误吞）', () => {
+      expect(isMediaDeliveryFailure('文件已上云，链接如下')).toBeFalse();
+      expect(isMediaDeliveryFailure('这个视频有 60MB')).toBeFalse();
+      expect(isMediaDeliveryFailure('')).toBeFalse();
+      expect(isMediaDeliveryFailure(undefined)).toBeFalse();
+    });
+
+    it('🔴 实时流：这条消息不进消息列表', () => {
+      realMode();
+      expect(
+        (svc as unknown as { appendIncoming: (m: MxMessage, me: string) => void }).appendIncoming,
+      ).toBeTruthy();
+    });
+  });
+
   describe('附件暂存 → 发送时上传（AC-04.3）', () => {
     const file = (name = 'doc.txt') => new File(['x'], name, { type: 'text/plain' });
 
@@ -887,36 +996,48 @@ describe('ChatService', () => {
        */
       expect(svc.messages().some((m) => m.id.startsWith('local-file-'))).toBeTrue();
       // 走 Matrix 原生附件，不再依赖 OBS 预签名地址
-      expect(mxStub.sendFile).toHaveBeenCalled();
+      expect(mxStub.sendFileByUrl).toHaveBeenCalled();
+      expect(mxStub.sendFile)
+        .withContext('不再把文件本体传进 Matrix')
+        .not.toHaveBeenCalled();
       expect(svc.uploading()).toBeFalse();
       // 上传成功后暂存清空
       expect(svc.pendingFiles()).toEqual([]);
     });
 
     // 🔴 原实现只更新本地消息、从不发到房间 —— 容器永远收不到
-    it('🔴 附件必须以 Matrix 原生事件真的发到房间（sendFile）', async () => {
+    it('🔴 附件必须以 Matrix 原生事件真的发到房间（sendFileByUrl）', async () => {
       realMode();
       await svc.open('agent-node-lj-test');
       apiStub.uploadFile.and.returnValue(
         Promise.resolve({ key: 'k', publicUrl: 'https://s3.fmode.cn/k' }),
       );
+      mxStub.sendFileByUrl.calls.reset();
       mxStub.sendFile.calls.reset();
 
       svc.stageFiles([file()]);
       await svc.sendText('附上');
 
-      expect(mxStub.sendFile).toHaveBeenCalled();
+      expect(mxStub.sendFileByUrl).toHaveBeenCalled();
+      // 事件里的地址必须是云盘链接，且**不得**触发 Matrix 媒体上传
+      expect(mxStub.sendFileByUrl.calls.mostRecent().args[1]).toBe('https://s3.fmode.cn/k');
+      expect(mxStub.sendFile).not.toHaveBeenCalled();
     });
 
     it('上传失败 → 记录错误且不上传中，附件保留待重试', async () => {
       realMode();
       await svc.open('agent-node-lj-test');
-      mxStub.sendFile.and.returnValue(Promise.reject(new Error('上传失败')));
-      svc.stageFiles([file()]);
-      await svc.sendText('附上');
-      expect(svc.error()).toContain('失败');
-      expect(svc.uploading()).toBeFalse();
-      expect(svc.pendingFiles().length).withContext('失败后应保留待重试').toBe(1);
+      mxStub.sendFileByUrl.and.returnValue(Promise.reject(new Error('上传失败')));
+      try {
+        svc.stageFiles([file()]);
+        await svc.sendText('附上');
+        expect(svc.error()).toContain('失败');
+        expect(svc.uploading()).toBeFalse();
+        expect(svc.pendingFiles().length).withContext('失败后应保留待重试').toBe(1);
+      } finally {
+        // 还原桩：jasmine 的 spy 返回值是跨用例共享的
+        mxStub.sendFileByUrl.and.returnValue(Promise.resolve({ event_id: '$fu' }));
+      }
     });
 
     /*
@@ -927,12 +1048,12 @@ describe('ChatService', () => {
       realMode();
       await svc.open('agent-node-lj-test');
       apiStub.uploadFile.and.returnValue(Promise.reject(new Error('云盘不可用')));
-      mxStub.sendFile.calls.reset();
+      mxStub.sendFileByUrl.calls.reset();
 
       svc.stageFiles([file()]);
       await svc.sendText('附上');
 
-      expect(mxStub.sendFile).not.toHaveBeenCalled();
+      expect(mxStub.sendFileByUrl).not.toHaveBeenCalled();
       expect(svc.error()).toContain('云盘不可用');
       expect(svc.pendingFiles().length).withContext('未上云的文件不得被清掉').toBe(1);
     });
@@ -945,7 +1066,7 @@ describe('ChatService', () => {
         order.push('s3');
         return Promise.resolve({ key: 'k', publicUrl: 'https://s3.fmode.cn/k' });
       });
-      mxStub.sendFile.and.callFake(() => {
+      mxStub.sendFileByUrl.and.callFake(() => {
         order.push('matrix');
         return Promise.resolve();
       });
@@ -961,25 +1082,30 @@ describe('ChatService', () => {
       realMode();
       await svc.open('agent-node-lj-test');
       /*
-       * 🔴 2026-11-13：上限不再写死 20MB，而是由服务端 `m.upload.size` 决定。
-       *    这里显式设成 20MB 来验证拦截逻辑本身（真实环境实测为 32MB）。
+       * 🔴 2026-11-13 用户裁决「上传的文件没有大小限制」：`'url'` 模式不拦截。
+       *    拦截逻辑本身仍在，这里用 `'mxc'` 回退模式验证它没被删掉。
        */
-      setServerUploadLimit(20 * 1024 * 1024);
-      const big = new File([new Uint8Array(8)], 'big.zip');
-      Object.defineProperty(big, 'size', { value: 21 * 1024 * 1024 });
+      localStorage.setItem('fmode.sendMode', 'mxc');
+      setServerUploadLimit(32 * 1024 * 1024);
+      try {
+        const big = new File([new Uint8Array(8)], 'big.zip');
+        Object.defineProperty(big, 'size', { value: 40 * 1024 * 1024 });
 
-      svc.stageFiles([big]);
+        svc.stageFiles([big]);
 
-      expect(svc.pendingFiles().length).toBe(0);
-      expect(svc.error()).toContain('超过平台单文件上限');
+        expect(svc.pendingFiles().length).toBe(0);
+        expect(svc.error()).toContain('超过平台单文件上限');
+      } finally {
+        localStorage.removeItem('fmode.sendMode');
+      }
     });
 
-    it('🔴 未探测到服务端上限 → 不拦截（用户裁决：不要凭空拦住）', async () => {
+    it('🔴 200MB 以内放行（不再受 Matrix 32MB 限制）', async () => {
       realMode();
       await svc.open('agent-node-lj-test');
       setServerUploadLimit(null);
       const big = new File([new Uint8Array(8)], 'huge.zip');
-      Object.defineProperty(big, 'size', { value: 500 * 1024 * 1024 });
+      Object.defineProperty(big, 'size', { value: 100 * 1024 * 1024 });
 
       svc.stageFiles([big]);
 
@@ -1000,16 +1126,21 @@ describe('ChatService', () => {
     it('多选时只挡掉超限的，合格的照常暂存', async () => {
       realMode();
       await svc.open('agent-node-lj-test');
-      setServerUploadLimit(20 * 1024 * 1024); // 显式设上限，见上方说明
-      const small = file();
-      const big = new File([new Uint8Array(8)], 'big.zip');
-      Object.defineProperty(big, 'size', { value: 30 * 1024 * 1024 });
+      localStorage.setItem('fmode.sendMode', 'mxc');
+      setServerUploadLimit(32 * 1024 * 1024);
+      try {
+        const small = file();
+        const big = new File([new Uint8Array(8)], 'big.zip');
+        Object.defineProperty(big, 'size', { value: 40 * 1024 * 1024 });
 
-      svc.stageFiles([small, big]);
+        svc.stageFiles([small, big]);
 
-      expect(svc.pendingFiles().length).toBe(1);
-      expect(svc.pendingFiles()[0].file.name).toBe('doc.txt');
-      expect(svc.error()).toContain('big.zip');
+        expect(svc.pendingFiles().length).toBe(1);
+        expect(svc.pendingFiles()[0].file.name).toBe('doc.txt');
+        expect(svc.error()).toContain('big.zip');
+      } finally {
+        localStorage.removeItem('fmode.sendMode');
+      }
     });
 
     it('只有附件没有文字也能发送', async () => {
@@ -1024,7 +1155,7 @@ describe('ChatService', () => {
       await svc.sendText('');
 
       // 纯附件：附件本身照常发到房间（本地不伪造文件消息）
-      expect(mxStub.sendFile).toHaveBeenCalled();
+      expect(mxStub.sendFileByUrl).toHaveBeenCalled();
       // 纯附件不该发一条空文字
       expect(mxStub.sendText).not.toHaveBeenCalled();
     });

src/app/core/chat.service.ts

@@ -16,6 +16,7 @@ import { AlertService } from './alert.service';
 import { extractDeliveredLinks, extractS3Links, isCloudUrl, isUserUploadUrl, prettifyStorageKey, stripLinks } from './s3-link';
 import { isOversize, notifyOversize, oversizeMessage } from './upload-limits';
 import { batchPhase, FileProgress, overallPct, UploadPhase } from './upload-state';
+import { currentSendMode } from './send-mode';
 import { environment } from '../../environments/environment';
 import { LiveService } from './live.service';
 import { SessionService } from './session.service';
@@ -70,6 +71,13 @@ export interface PendingFile {
    * 「上传中 42%」/「登记中…」/「发送中…」。未开始为 `undefined`。
    */
   progress?: FileProgress;
+  /**
+   * 已完成的云盘上传结果（2026-11-13 评审 S3）。
+   *
+   * 上传 + 登记成功、但**发事件失败**时保留在暂存项上：重试直接复用，
+   * 否则会再传一份、再登记一条台账，云盘上留孤儿对象、文件列表里出现重复项。
+   */
+  uploaded?: { url: string; key: string; registered: boolean };
 }
 
 /**
@@ -840,10 +848,21 @@ export class ChatService {
     agentId: string,
     workspaceId: string | null = null,
   ): Promise<ChatSession | null> {
+    /*
+     * 分段计时（2026-11-13 用户反馈「新建很慢」）。
+     * 只打 info 级、带 `[perf]` 前缀，便于在控制台/日志里 grep 出各段耗时。
+     * 线上排查新建卡顿只看这一行即可，不用再猜。
+     */
+    const t0 = Date.now();
     const s = await this.startBlank(agentId, workspaceId);
+    const t1 = Date.now();
     if (!s) return null;
     /* 同步等建房完成（内部已 try/catch，失败静默降级） */
     await this.provisionSessionRoom(s.id, agentId);
+    const t2 = Date.now();
+    console.info(
+      `[perf] 新建会话：连接/建会话 ${t1 - t0}ms，建房+等进房 ${t2 - t1}ms，合计 ${t2 - t0}ms`,
+    );
     return s;
   }
 
@@ -1002,6 +1021,15 @@ export class ChatService {
 
     this._messages.set([]);
     this._state.set('empty');
+    /*
+     * 🔴 必须重置空态判定（2026-11-13 用户实测）。
+     *
+     * 上面 `open(agentId)` 那一分支会走 `openReal()`，它按「已有会话」算出一份
+     * `emptyReason`。新建会话随后清空了 `_messages`，但**没清这个标记** ——
+     * 上一份结论原样残留，界面直接显示「这个会话的消息暂时没加载出来 / 网络波动」。
+     * 新建的会话完全没有历史，正确语义是 `fresh`（走欢迎页）。
+     */
+    this._emptyReason.set('fresh');
     this._error.set(null);
     this._hasMoreHistory.set(false);
     this._peerTyping.set(false);
@@ -1551,19 +1579,34 @@ export class ChatService {
      */
     const reachedRoomStart = this._reachedRoomStart;
     const knownInCatalog = !!this.sessions.byId(sid);
+    /*
+     * 🔴 新建中的会话不能判成「取不到」（2026-11-13 修复）。
+     *
+     * `backfillSessionTimeline()` 对 `_blankSessionId` 会**直接 return**（本该如此，
+     * 否则会认领旧内容），但它同时让 `_reachedRoomStart` 停在 `false` ——
+     * 于是刚点「新建对话」就必然落进下面的 `unloaded` 分支，界面直接显示
+     * 「这个消息暂时没加载出来 / 可能是网络波动」。
+     * 用户看到的是「新建会话报错了」，而且这个错误态一直挂着，
+     * 直到用户真的发出第一条消息才会变成正常布局。
+     *
+     * 新建中的会话**本来就没有历史**，正确语义是 `fresh`（走欢迎页）。
+     */
+    const isBlank = this._blankSessionId === sid;
     this._emptyReason.set(
       this._messages().length > 0
         ? null
-        : hasSessionEvent
-          ? 'unloaded'
-          : reachedRoomStart && knownInCatalog
-            ? /*
-               * 已翻到房间最早 + 目录里有这条 + 一条消息都没有 = **空壳会话**。
-               * 不能说「暂时取不到」（用户会一直等，以为数据丢了），
-               * 也不能说成「新会话」（会诱导用户在这里重新开始）。
-               */
-              'blank'
-            : 'unloaded',
+        : isBlank
+          ? 'fresh'
+          : hasSessionEvent
+            ? 'unloaded'
+            : reachedRoomStart && knownInCatalog
+              ? /*
+                 * 已翻到房间最早 + 目录里有这条 + 一条消息都没有 = **空壳会话**。
+                 * 不能说「暂时取不到」（用户会一直等，以为数据丢了），
+                 * 也不能说成「新会话」（会诱导用户在这里重新开始）。
+                 */
+                'blank'
+              : 'unloaded',
     );
     this._state.set(this._messages().length === 0 ? 'empty' : 'ready');
     // timeline pagination token 是否存在 = 更早可能有历史
@@ -1804,21 +1847,28 @@ export class ChatService {
    * 事件里带 `dispatch`（让重建能把它识别成本回合的用户内容）和
    * `sessionId = turnId`（让单聊过滤规则把它挡在单聊之外）。
    */
+  /**
+   * 群聊派活：把一个文件发进**某个**成员的 DM 房间。
+   *
+   * @param cloudUrl 已上传到个人存储的地址。**`'url'` 模式必填**（缺失即失败，
+   *   不做静默降级）；`'mxc'` 回退模式忽略它，由 `sendFile()` 自行上传。
+   */
   async sendFileToAgent(
     agentId: string,
     file: File,
     meta: MxDispatchMeta,
+    cloudUrl: string,
   ): Promise<DispatchResult> {
     try {
       const rid = await this.ensureAgentRoomFor(agentId);
       if (!rid) return { ok: false, baselineEventId: null, error: '容器未接入' };
       const baselineEventId = this.mx.lastMessageEventId(rid);
-      const res = await this.mx.sendFile(
+      const res = await this.sendCloudFile(
         rid,
         file,
+        cloudUrl,
         { name: file.name, size: file.size, mimeType: file.type || 'application/octet-stream' },
         undefined,
-        undefined,
         { [DISPATCH_KEY]: meta, [SESSION_KEY]: meta.turnId },
       );
       return { ok: true, eventId: res.event_id, baselineEventId, roomId: rid };
@@ -2148,6 +2198,39 @@ export class ChatService {
     return this.api.uploadFile(file);
   }
 
+  /**
+   * 发一条「文件已在个人存储」的附件事件（2026-11-13，单聊/群聊共用）。
+   *
+   * ## 为什么要按模式分发
+   *
+   * - `'url'`（默认）：文件只在个人 storage 里存一份，事件 `content.url` 就是云盘地址，
+   *   本体**不进 Matrix**（用户裁决：只允许收发 cdn/obs 地址）。
+   * - `'mxc'`（回退）：容器补丁未落地时，把 `file` 整份传进 Matrix 媒体库。
+   *
+   * 调用方**必须先成功拿到 `cloudUrl`** 才能调本方法 —— 保证「发出去的文件 = 能长期访问的文件」。
+   */
+  async sendCloudFile(
+    roomId: string,
+    file: File,
+    cloudUrl: string,
+    card: { name: string; size: number; mimeType: string },
+    threadRootId?: string,
+    extra?: Record<string, unknown>,
+  ): Promise<{ event_id?: string }> {
+    if (currentSendMode() === 'mxc') {
+      // 回退模式：文件整份进 Matrix，cloudUrl 只作 `com.fmode.cloud_url` 附带
+      return this.mx.sendFile(roomId, file, card, threadRootId, undefined, {
+        ...(cloudUrl ? { [CLOUD_URL_KEY]: cloudUrl } : {}),
+        ...(extra ?? {}),
+      });
+    }
+    if (!cloudUrl) throw new Error('「' + card.name + '」尚未上传到个人存储，未发送');
+    return this.mx.sendFileByUrl(roomId, cloudUrl, card, threadRootId, undefined, {
+      [CLOUD_URL_KEY]: cloudUrl,
+      ...(extra ?? {}),
+    });
+  }
+
   /**
    * 把已上传云盘的文件登记进文件台账（2026-11-10）。
    *
@@ -2328,38 +2411,46 @@ export class ChatService {
         }
         try {
           /*
-           * 🔴 直接走 **Matrix 原生附件**，不再经过 OBS 预签名 + 自定义 JSON。
-           *
-           * 容器只认 `{ msgtype: 'm.file'|'m.image', url: 'mxc://...' }`。
-           * 早期实现走 `api.uploadFile()` 拿 OBS 地址、再塞进 `m.text` 的 JSON body ——
-           * 容器完全不解析,用户发图后它回「只看到文字,没收到附件」（实测）。
+           * 🔴 顺序：**先上个人存储、后发消息**（2026-11-13 用户裁决，沿用 11-10 顺序）。
            *
-           * 现在:文件内容直接上传 Matrix 媒体库 → 发原生事件。
-           * `publicUrl` 仅用于界面本地展示,OBS 那条链路不再参与发送。
-           */
-          /*
-           * 🔴 顺序：**先 S3、再 Matrix**（2026-11-10 调整）。
-           *
-           * 原先是 Matrix 先发、S3 后传，结果是「消息已经发出去了、云盘却没存上」，
-           * 用户看到的是一个只存在于聊天记录里、换设备就打不开的文件。
-           *
-           * 现在反过来：云盘存不上就**不发 Matrix**，失败项留在待发区重试。
+           * 云盘存不上就**不发**，失败项留在待发区重试。
            * 这样「发出去的文件 = 一定能长期访问的文件」，不会出现半成功状态。
            *
-           * 为什么要两份：
-           *   Matrix 那份给容器读（容器只认 `m.file` + `mxc://`，实测直链它收不到）；
-           *   S3   那份给 App 长期查看与成果归档（Matrix 媒体会被平台清理）。
+           * 🔴 不再双写（2026-11-13）：
+           *   以前 Matrix 还存一份 `mxc://`，因为容器只认 `m.file` + `mxc://`。
+           *   用户裁决「只允许收发 cdn/obs 地址，禁止经应用服务器/Matrix 传附件」，
+           *   现在改发 `content.url = 云盘 https 地址`（**前置条件**：容器侧
+           *   adapter.py 补丁已落地，见 `send-mode.ts` 的说明）。
+           *   回退：`localStorage.fmode.sendMode='mxc'` 即恢复旧双写。
            */
           const mimeType = file.type || 'application/octet-stream';
           if (!this.roomId) throw new Error('会话未就绪');
           const sid = this._sessionId();
 
-          /* ① 云盘：失败即中止本文件（不发送）。传 onProgress 拿**真实字节进度**（2026-11-11） */
-          this.setFileProgress(pending[i].id, { phase: 'uploading', pct: 0 });
-          const up = await this.api.uploadFile(file, (pct) => {
-            this.setFileProgress(pending[i].id, { phase: 'uploading', pct });
-          });
-          const cloudUrl = up.publicUrl;
+          /*
+           * ① 云盘：失败即中止本文件（不发送）。传 onProgress 拿**真实字节进度**（2026-11-11）
+           *
+           * 🔴 重试复用（2026-11-13 评审 S3）：上次已经传上去、只是**发事件失败**的，
+           *    直接拿缓存，不再上传一次 —— 否则云盘多一份孤儿、台账多一条重复。
+           */
+          let cloudUrl: string;
+          let cloudKey: string;
+          let registered: boolean;
+          const cached = this._pendingFiles().find((p) => p.id === pending[i].id)?.uploaded;
+          if (cached) {
+            cloudUrl = cached.url;
+            cloudKey = cached.key;
+            registered = cached.registered;
+            this.setFileProgress(pending[i].id, { phase: 'uploading', pct: 100 });
+          } else {
+            this.setFileProgress(pending[i].id, { phase: 'uploading', pct: 0 });
+            const up = await this.api.uploadFile(file, (pct) => {
+              this.setFileProgress(pending[i].id, { phase: 'uploading', pct });
+            });
+            cloudUrl = up.publicUrl;
+            cloudKey = up.key;
+            registered = false;
+          }
           /*
            * `key` 是云盘里的稳定对象标识，`publicUrl` 只是它的投影。
            * 以前只留了 url、把 key 丢了 —— 将来要按用户/会话检索文件时，
@@ -2374,7 +2465,7 @@ export class ChatService {
            * 登记失败不阻断发送（文件已经在云盘上了，只是台账缺一条），
            * 但要如实提示 —— 不能让用户以为文件没上去。
            */
-          if (sid) {
+          if (sid && !registered) {
             try {
               this.setFileProgress(pending[i].id, { phase: 'registering', pct: 100 });
               await this.api.registerFile({
@@ -2383,41 +2474,40 @@ export class ChatService {
                 roomId: this.roomId,
                 name: file.name,
                 url: cloudUrl,
-                key: up.key,
+                key: cloudKey,
                 mimeType,
                 size: file.size,
                 uploadedBy: 'user',
               });
+              registered = true;
             } catch (e) {
               this._error.set(
                 `「${file.name}」已存入云盘，但未记入文件列表：${e instanceof Error ? e.message : '登记失败'}`,
               );
             }
           }
+          /*
+           * 先把「已上云」记到暂存项上，再发事件 —— 若下一步失败，
+           * 下一步重试就只重发事件（评审 S3）。
+           */
+          this._pendingFiles.update((cur) =>
+            cur.map((p) => (p.id === pending[i].id ? { ...p, uploaded: { url: cloudUrl, key: cloudKey, registered } } : p)),
+          );
 
-          /* ② Matrix：供容器读取 */
+          /* ② Matrix：把云盘地址发给容器（2026-11-13 起不再传文件本体） */
           this.setFileProgress(pending[i].id, { phase: 'sending', pct: 100 });
-          await this.mx.sendFile(
+          await this.sendCloudFile(
             this.roomId,
             file,
+            cloudUrl,
             { name: file.name, size: file.size, mimeType },
             sid ?? undefined,
-            undefined,
-            /*
-             * 🔴 把云盘链接写进 Matrix 事件的 content（2026-11-13）。
-             *
-             * 为什么必须写：不带的话，回读历史只能拿到 `mxc://`，
-             * 而 App 展示/预览要的是**云盘公网链接**。原先靠内存 Map
-             * `_cloudUrls` 补，**刷新就丢** —— 用户反馈「链接不对」「刷新后打不开」。
-             *
-             * 容器只认 `url`（mxc://），未知字段会被忽略，不影响它。
-             */
-            { [CLOUD_URL_KEY]: cloudUrl },
           );
           this.setFileProgress(pending[i].id, { phase: 'done', pct: 100 });
           /*
-           * 云盘地址记进 `_cloudUrls`：回读的 `m.image` 只有 `mxc://`，
-           * 没这张表就补不回 `FileCard.cloudUrl`（2026-11-10 合并修复）。
+           * 云盘地址记进 `_cloudUrls`：**只服务于 `'mxc'` 回退模式**下的老消息
+           * （事件里没带 `com.fmode.cloud_url` 的那种）。`'url'` 模式下事件自带地址，
+           * 这张内存表是冗余兜底（2026-11-10 引入，2026-11-13 收窄语义）。
            *
            * 🔴 文件**不进**会话成果列表（`deliverableUrls`）：用户自己发的
            *    东西只属于右栏「文件」页签，「成果」= 容器产出的东西。
@@ -3115,7 +3205,11 @@ export class ChatService {
   /** 归一 timeline → 领域消息 */
   private mapTimeline(list: MxMessage[], myUserId: string): Message[] {
     const cid = this._agentId() ?? '';
-    return list.map((m) => {
+    /*
+     * 先滤掉容器「附件投递失败」的兜底提示（2026-11-13）。
+     * 只在实时流过滤会导致「刚发完看不到、刷新后又冒出来」，两处必须一致。
+     */
+    return list.filter((m) => !isMediaDeliveryFailure(m.body)).map((m) => {
       /*
        * 两种附件形态都要认：
        *   ① 我们早期自造的 `m.text + JSON body`
@@ -3200,8 +3294,15 @@ export class ChatService {
           linkCard = cloudLinks.length > 0 ? this.cardOfCloudLink(cloudLinks[0]) : undefined;
           bodyText = linkCard ? stripLinks(m.body, cloudLinks) : m.body;
         }
-      } else if (isAttachmentEcho(m.body, file.name)) {
-        /* Matrix 原生附件的 body 是文件名（协议要求），不是正文 —— 别当纯文字再显示一遍 */
+      } else if (isAttachmentEcho(m.body, file.name) || !m.body.trim()) {
+        /*
+         * 附件的 body 是文件名（协议要求），**或者为空**（用户 `'url'` 模式发出的
+         * 附件事件没有正文）—— 都不是正文，别当纯文字再显示一遍。
+         *
+         * 🔴 2026-11-13 评审 S4：原先只判 `isAttachmentEcho`，空 body 会掉进
+         *    「从正文提取链接」分支 —— 结果气泡里**明文显示整条云盘地址**，
+         *    正是用户明确要求不能出现的东西。
+         */
         bodyText = '';
       }
 
@@ -3369,6 +3470,11 @@ export class ChatService {
   /** 追加一条新到消息（按 eventId 去重;不属于当前会话的忽略） */
   private appendIncoming(m: MxMessage, myUserId: string): void {
     if (!this._agentId()) return;
+    /*
+     * 丢弃容器「附件投递失败」的兜底提示（2026-11-13）。
+     * 它来自已废弃的「Matrix 回发文件本体」链路，对用户没有信息量，见 isMediaDeliveryFailure。
+     */
+    if (isMediaDeliveryFailure(m.body)) return;
     const sid = this._sessionId();
     // 🔴 多会话隔离:别的会话的消息不进入当前会话的列表
     if (!sid || !this.belongsToSession(m, sid, true)) return;
@@ -3626,3 +3732,25 @@ export function isAttachmentEcho(body: string | undefined, fileName: string): bo
   if (!b) return false;
   return b === fileName.trim();
 }
+
+/**
+ * 容器「附件投递失败」的系统提示（2026-11-13）。
+ *
+ * ## 为什么要在 App 侧识别它
+ *
+ * 容器侧的 Hermes 在**尝试通过 Matrix 把文件本体回发**时，若本地路径对不上，
+ * 会发一条纯文本兜底提示（`matrix/adapter.py:1832` 的
+ * `"⚠️ Couldn't deliver the attachment."`）。实测对 60MB 视频必现。
+ *
+ * 对用户来说这是一条**没有信息量、且指向已废弃链路**的噪声：
+ *   · 文件其实早就传到云盘了，容器也读到了；
+ *   · 按产品要求，容器**不该**用 Matrix 回发文件本体，只应给云盘链接。
+ *
+ * 所以这里识别出来、由上层**静默丢弃**（不渲染成消息）。
+ * 🔴 只匹配这句固定文案，不做模糊匹配 —— 避免误吞容器正常的报错说明。
+ */
+const MEDIA_DELIVERY_FAILURE = /Couldn['’]t deliver\s+(?:the\s+|an?\s+|your\s+)?\w*\s*attachment/i;
+
+export function isMediaDeliveryFailure(body: string | undefined | null): boolean {
+  return !!body && MEDIA_DELIVERY_FAILURE.test(body);
+}

src/app/core/group-send.service.ts

@@ -1,6 +1,7 @@
 import { Injectable, inject, signal } from '@angular/core';
 import { ChatSessionService } from './chat-session.service';
 import { ChatSession } from './chat-session';
+import { currentSendMode } from './send-mode';
 import { ChatService, PendingFile } from './chat.service';
 import { isOversize, oversizeMessage } from './upload-limits';
 import { DispatchAnchor, GroupLiveService } from './group-live.service';
@@ -156,10 +157,22 @@ export class GroupSendService {
        * 单聊早就改成「云盘存不上就不发」（`chat.service.ts` 的 uploadPending），
        * 群聊这里漏了同一条约束。
        */
+      /*
+       * 🔴 `'mxc'` 回退模式**不在这里预上传**（2026-11-13 评审 S1）。
+       *
+       * 原先无论模式都先 `uploadToCloud()`，然后 `sendFileToAgent()` 在 mxc 模式下
+       * 忽略 cloudUrl、把 file 传进 Matrix —— 看似正常，但「上云失败就整体 abort」
+       * 这条约束在回退模式下反而帮了倒忙：云盘一抖，本来能发的 Matrix 副本也发不出。
+       * 回退模式的语义是「回到改造前」，所以这里直接跳过，交给 `sendFile()`。
+       */
+      const useCloud = currentSendMode() === 'url';
       let cloudFailed = false;
-      for (const pf of files) {
+      /** 文件 → 云盘地址（`'url'` 模式下各成员房间复用同一地址，不再各传一份） */
+      const cloudUrls = new Map<File, string>();
+      for (const pf of useCloud ? files : []) {
         try {
           const up = await this.chat.uploadToCloud(pf.file);
+          cloudUrls.set(pf.file, up.publicUrl);
           /*
            * 登记到文件台账（2026-11-10，2026-11-11 补群归属）。
            *
@@ -180,10 +193,16 @@ export class GroupSendService {
             );
           }
         } catch (e) {
+          /*
+           * 🔴 立即中断（2026-11-13 评审 S2）：原来只置标志、循环照跑完，
+           * 已上云的前几个文件会被逐房间发出去、随后整体 `return` ——
+           * 每个成员都收到一次「无正文的投递」，用户看到的是半截状态。
+           */
           cloudFailed = true;
           this._error.set(
             `「${pf.file.name}」未能存入云盘，本条消息未发送：${e instanceof Error ? e.message : '上传失败'}`,
           );
+          break;
         }
       }
       if (cloudFailed) return { ok: false, failedNames: files.map((f) => f.file.name) };
@@ -224,14 +243,20 @@ export class GroupSendService {
         let roomId: string | undefined;
         let lastEventId: string | undefined;
 
-        // ① 附件先发（每个文件在该房间各上传一份）
+        /*
+         * ① 附件先发。
+         *
+         * `'mxc'` 回退模式下每个房间各传一份 Matrix 副本（Matrix 没有跨房间引用）；
+         * `'url'` 模式下各房间复用**同一个**云盘地址（2026-11-13），不再重复上传。
+         */
         let fileOk = files.length === 0;
         for (const pf of files) {
-          const r = await this.chat.sendFileToAgent(id, pf.file, {
-            groupId: session.id,
-            turnId,
-            targetAgentId: id,
-          });
+          const r = await this.chat.sendFileToAgent(
+            id,
+            pf.file,
+            { groupId: session.id, turnId, targetAgentId: id },
+            cloudUrls.get(pf.file) ?? '',
+          );
           if (!r.ok) {
             fileOk = false;
             break;

src/app/core/matrix-client.send-file-by-url.spec.ts

@@ -0,0 +1,88 @@
+import { TestBed } from '@angular/core/testing';
+import { FmodeApi } from './api/fmode-api';
+import { SessionService } from './session.service';
+import { CLOUD_URL_KEY, MatrixClientService } from './matrix-client.service';
+
+/**
+ * `sendFileByUrl()` 单测（2026-11-13）。
+ *
+ * 意义：这是「只允许收发 cdn/obs 地址」的落点 —— 事件里的 `url` 必须是外部
+ * 云盘地址，**且绝不能退化成 `uploadContent`**（一旦上传，文件又进了 Matrix）。
+ *
+ * 🔴 不加载真实 matrix-js-sdk：`load()` 被替换成返回一个假 SDK。
+ */
+describe('MatrixClientService.sendFileByUrl（附件只发云盘地址）', () => {
+  let svc: MatrixClientService;
+  let sent: { roomId: string; type: string; content: Record<string, unknown> }[];
+  let uploadContent: jasmine.Spy;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: FmodeApi, useValue: {} },
+        { provide: SessionService, useValue: { sessionToken: () => null } },
+      ],
+    });
+    svc = TestBed.inject(MatrixClientService);
+    sent = [];
+    uploadContent = jasmine.createSpy('uploadContent');
+    const fakeClient = {
+      sendEvent: (roomId: string, type: string, content: Record<string, unknown>) => {
+        sent.push({ roomId, type, content });
+        return Promise.resolve({ event_id: '$ev' });
+      },
+      uploadContent,
+    };
+    // 绕开真实 SDK 加载与连接
+    (svc as unknown as { client: unknown }).client = fakeClient;
+    (svc as unknown as { load: () => Promise<unknown> }).load = () =>
+      Promise.resolve({ EventType: { RoomMessage: 'm.room.message' } });
+  });
+
+  it('🔴 发 m.file 事件，url 就是云盘地址，且不触发任何上传', async () => {
+    const url = 'https://s3.fmode.cn/user/u1/chat/202611/a.pdf';
+    await svc.sendFileByUrl('!r:fmode.cn', url, { name: 'a.pdf', size: 3, mimeType: 'application/pdf' });
+
+    expect(sent.length).toBe(1);
+    const c = sent[0].content;
+    expect(sent[0].roomId).toBe('!r:fmode.cn');
+    expect(sent[0].type).toBe('m.room.message');
+    expect(c['msgtype']).toBe('m.file');
+    expect(c['url']).toBe(url);
+    expect(c['body']).toBe('a.pdf');
+    expect(c['info']).toEqual({ mimetype: 'application/pdf', size: 3 });
+    expect(c['file']).withContext('不得带加密/媒体文件字段').toBeUndefined();
+    expect(c[CLOUD_URL_KEY]).withContext('冗余字段，供只认它的回读逻辑').toBe(url);
+    expect(uploadContent).withContext('文件本体不得进 Matrix 媒体库').not.toHaveBeenCalled();
+  });
+
+  it('图片用 m.image（客户端可内联显示）', async () => {
+    await svc.sendFileByUrl('!r', 'https://s3.fmode.cn/x.png', {
+      name: 'x.png', size: 1, mimeType: 'image/png',
+    });
+    expect(sent[0].content['msgtype']).toBe('m.image');
+  });
+
+  it('带 thread 根与 extra（dispatch 等标记不能丢）', async () => {
+    await svc.sendFileByUrl(
+      '!r',
+      'https://s3.fmode.cn/x.txt',
+      { name: 'x.txt', size: 1, mimeType: 'text/plain' },
+      '$sid',
+      undefined,
+      { 'com.fmode.session': 'me-1' },
+    );
+    const c = sent[0].content;
+    expect((c['m.relates_to'] as { event_id: string }).event_id).toBe('$sid');
+    expect(c['com.fmode.session']).toBe('me-1');
+  });
+
+  it('非 https 地址直接拒绝（防 javascript:/相对路径混进来）', async () => {
+    for (const bad of ['http://s3.fmode.cn/x', 'mxc://fmode.cn/abc', 'javascript:alert(1)', '']) {
+      await expectAsync(
+        svc.sendFileByUrl('!r', bad, { name: 'x', size: 1, mimeType: 'text/plain' }),
+      ).toBeRejectedWithError(/附件地址无效/);
+    }
+    expect(sent.length).toBe(0);
+  });
+});

src/app/core/matrix-client.service.ts

@@ -4,6 +4,7 @@ import { environment } from '../../environments/environment';
 import { FmodeApi } from './api/fmode-api';
 import { SessionService } from './session.service';
 import { setServerUploadLimit } from './upload-limits';
+import { isAllowedMediaUrl } from './s3-link';
 
 /**
  * Matrix 客户端 —— `matrix-js-sdk` 的**唯一收敛点**
@@ -337,7 +338,7 @@ export function buildThreadRelation(
 }
 
 
-import { isMediaMsgType, parseNativeMedia } from './matrix-media';
+import { isMediaMsgType, isMxcUrl, parseNativeMedia } from './matrix-media';
 
 const TEXT_MSGTYPES = ['m.text', 'm.notice', 'm.emote'];
 
@@ -751,13 +752,20 @@ export class MatrixClientService implements OnDestroy {
    *
    * 新建房间后必须等容器进房才能发消息，否则容器收不到
    * （它只监听自己已加入的房间）。实测进房约 3 秒。
+   *
+   * 🔴 2026-11-13 用户实测「新建对话很慢」后调整：
+   *   ① 轮询间隔 1000ms → **200ms**：原先最坏情况要等满 1 秒才发现已进房；
+   *   ② 默认超时 30s → **8s**：实测进房约 3 秒，8 秒没进基本就是不会进了。
+   *      原先 30 秒意味着容器异常时用户要干等半分钟才看到界面。
+   *   进房判断本身是**本地内存查表**（`getRoom().getMember()`），
+   *   提高轮询频率没有网络开销。
    */
-  async waitAgentJoined(roomId: string, agentMxId: string, timeoutMs = 30_000): Promise<boolean> {
+  async waitAgentJoined(roomId: string, agentMxId: string, timeoutMs = 8_000): Promise<boolean> {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       const room = this.client?.getRoom(roomId);
       if (room?.getMember(agentMxId)?.membership === 'join') return true;
-      await new Promise((r) => setTimeout(r, 1000));
+      await new Promise((r) => setTimeout(r, 200));
     }
     return false;
   }
@@ -932,24 +940,53 @@ export class MatrixClientService implements OnDestroy {
   }
 
   /**
-   * 发文件卡片（`m.text` + JSON body）。
+   * 发「已上传到个人存储」的附件事件（2026-11-13，附件 `'url'` 模式）。
+   *
+   * ## 与 `sendFile()` 的区别
+   *
+   * `sendFile()` 会把**文件本体 `uploadContent` 进 Matrix 媒体库**拿 `mxc://` ——
+   * 文件因此进出一趟 homeserver。用户裁决：**只允许收发 cdn/obs 地址**，
+   * 所以本方法**不做任何上传**，把外部拿到的云盘地址直接写进 `content.url`。
+   *
+   * ## 事件形态
    *
-   * @deprecated 容器不解析这种形态（实测）。**发文件请用 `sendFile()`**。
-   *   保留仅为兼容尚未迁移的调用点,新代码不要用。
+   * 仍是标准的 `m.image`/`m.file`（容器侧按 msgtype 分发，不能改成 `m.text`），
+   * 唯一差别是 `url` 为 `https://s3.fmode.cn/...`。
+   * 实测（2026-11-13）`matrix.fmode.cn` **接受并原样读回**非 mxc 的 url。
+   *
+   * @param url 云盘公网地址（必须是 https）
    */
-  async sendFileCard(
+  async sendFileByUrl(
     roomId: string,
-    card: { name: string; size: number; mimeType: string; url: string },
+    url: string,
+    card: { name: string; size: number; mimeType: string },
     threadRootId?: string,
     lastEventId?: string,
+    extra?: Record<string, unknown>,
   ): Promise<{ event_id?: string }> {
+    /*
+     * 🔴 只放行本平台云盘域名（2026-11-13 评审 G1）：
+     * 只判 https 太宽 —— `https://evil.example.com/x` 也会发进事件，
+     * 而容器侧白名单只认 s3/file-cloud，等于两边口径不一致。
+     */
+    if (!isAllowedMediaUrl(url)) throw new Error('附件地址无效（必须为云盘 https 地址）');
     const c = this.requireClient();
     const sdk = await this.load();
-    return c.sendEvent(roomId, sdk.EventType.RoomMessage, {
-      msgtype: sdk.MsgType.Text,
-      body: JSON.stringify({ kind: 'file', ...card }),
+    const isImage = card.mimeType.startsWith('image/');
+    const content: Record<string, unknown> = {
+      msgtype: isImage ? 'm.image' : 'm.file',
+      body: card.name,
+      url,
+      info: {
+        mimetype: card.mimeType,
+        size: card.size,
+      },
+      // 与 url 同值：兼容只认 `com.fmode.cloud_url` 的存量回读逻辑
+      [CLOUD_URL_KEY]: url,
       ...(threadRootId ? { 'm.relates_to': buildThreadRelation(threadRootId, lastEventId) } : {}),
-    });
+      ...(extra ?? {}),
+    };
+    return c.sendEvent(roomId, sdk.EventType.RoomMessage, content as never);
   }
 
   /** 当前 timeline → 归一消息（时间正序） */
@@ -996,8 +1033,7 @@ export class MatrixClientService implements OnDestroy {
         media: (() => {
           const m = parseNativeMedia(e.getContent());
           if (!m) return undefined;
-          const cloud = extractCloudUrl(e.getContent());
-          const http = cloud ?? this.mxcUrlToHttp(m.mxcUrl);
+          const http = this.mediaHttpUrl(e.getContent(), m.mxcUrl);
           return http
             ? { name: m.name, url: http, mimeType: m.mimeType, size: m.size ?? -1 }
             : undefined;
@@ -1239,6 +1275,25 @@ export class MatrixClientService implements OnDestroy {
     return `${url}${sep}access_token=${encodeURIComponent(this.token)}`;
   }
 
+  /**
+   * 附件事件的最终可访问地址（历史回读与实时流**必须共用**这一处）。
+   *
+   * 顺序：
+   *   ① `com.fmode.cloud_url`（存量双写模式）
+   *   ② url 本身就是 http(s) —— `'url'` 模式下就是这个，直接用
+   *      （2026-11-13 实测：SDK 的 `mxcUrlToHttp('https://...')` 返回**空串**，
+   *       以前对它调一次就等于把附件整个丢掉）
+   *   ③ 最后才把 `mxc://` 转成 media 地址
+   */
+  private mediaHttpUrl(content: Record<string, unknown>, rawUrl: string): string | null {
+    if (!rawUrl) return null;
+    const cloud = extractCloudUrl(content);
+    if (cloud) return cloud;
+    if (/^https?:\/\//i.test(rawUrl)) return rawUrl;
+    if (!isMxcUrl(rawUrl)) return null;
+    return this.mxcUrlToHttp(rawUrl);
+  }
+
   mxcUrlToHttp(mxc: string): string | null {
     const c = this.client;
     if (!c) return null;
@@ -1479,7 +1534,7 @@ export class MatrixClientService implements OnDestroy {
       const media = (() => {
         const m = parseNativeMedia(ev.getContent());
         if (!m) return undefined;
-        const http = this.mxcUrlToHttp(m.mxcUrl);
+        const http = this.mediaHttpUrl(ev.getContent(), m.mxcUrl);
         return http ? { name: m.name, url: http, mimeType: m.mimeType, size: m.size ?? -1 } : undefined;
       })();
 

src/app/core/s3-link.ts

@@ -18,6 +18,28 @@
 /** 云盘域名白名单（与 API 契约里的 OBS 公网前缀一致） */
 const CLOUD_HOSTS = ['s3.fmode.cn', 'file-cloud.fmode.cn'];
 
+/**
+ * **出站**可用的云盘 https 地址白名单（2026-11-13）。
+ *
+ * 与容器侧 `adapter.py` 的白名单保持同一份名单 —— 两边不一致就会出现
+ * 「App 发了、容器拒收」的静默失败。
+ *
+ * 🔴 只放 `s3.fmode.cn`：`file-cloud.fmode.cn` 的 TLS 证书已过期
+ * （2026-11-13 容器侧实测），留在**发送**白名单里等于给用户一个必然失败的入口。
+ * 读路径（`CLOUD_HOSTS`）仍保留它 —— 存量历史消息里可能有这类链接。
+ */
+const SENDABLE_HOSTS = ['s3.fmode.cn'];
+
+export function isAllowedMediaUrl(url: string | undefined | null): boolean {
+  if (!url) return false;
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' && SENDABLE_HOSTS.includes(u.host.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 这个地址是不是本平台云盘（2026-11-11）。
  *

src/app/core/send-mode.ts

@@ -0,0 +1,35 @@
+/**
+ * 附件发送模式（2026-11-13 用户裁决：走个人 storage，不经 Matrix）
+ *
+ * ## 两种模式
+ *
+ * - `'url'`（默认）：文件**只**直传用户个人 storage（OBS `s3.fmode.cn`），
+ *   发 `m.file`/`m.image` 事件时 `content.url` 直接填云盘 https 地址。
+ *   文件本体**不再进 Matrix 媒体库**。
+ * - `'mxc'`：旧的双写路径（`uploadContent` → `mxc://`），仅在容器侧补丁
+ *   未落地时用作回退。
+ *
+ * ## 回退方式（无需发版）
+ *
+ * 浏览器控制台执行 `localStorage.fmode.sendMode = 'mxc'` 后刷新即可回到旧链路；
+ * `localStorage.removeItem('fmode.sendMode')` 恢复默认。
+ *
+ * ## 🔴 切换顺序不能颠倒
+ *
+ * 容器侧 `adapter.py` 在补丁落地前**会拒收非 mxc 的 url**（静默丢附件）。
+ * 必须先用 `scripts/probe-url-attachment.mjs` 确认容器能收到 https 附件，
+ * 再默认走 `'url'`。详见 `docs/03-interface/容器侧改造-附件直读S3地址-任务书-20261113.md`。
+ */
+export type SendMode = 'url' | 'mxc';
+
+const STORAGE_KEY = 'fmode.sendMode';
+
+/** 当前生效的附件发送模式 */
+export function currentSendMode(): SendMode {
+  try {
+    return localStorage.getItem(STORAGE_KEY) === 'mxc' ? 'mxc' : 'url';
+  } catch {
+    // 隐私模式/无 storage：按默认走
+    return 'url';
+  }
+}

src/app/core/upload-limits.spec.ts

@@ -0,0 +1,43 @@
+import { CLOUD_LIMIT_BYTES, isOversize, notifyOversize, setServerUploadLimit, uploadLimitBytes } from './upload-limits';
+import { currentSendMode } from './send-mode';
+
+/**
+ * 附件上限「跟着发送模式走」（2026-11-13）。
+ *
+ * `'url'` 模式下文件只进个人存储，Matrix 的 `m.upload.size` 与我们无关；
+ * `'mxc'` 回退模式下仍要传进 Matrix，必须回到服务端上限。
+ */
+describe('upload-limits（按发送模式取上限）', () => {
+  afterEach(() => {
+    localStorage.removeItem('fmode.sendMode');
+    setServerUploadLimit(null);
+  });
+
+  it('默认模式为 url', () => {
+    expect(currentSendMode()).toBe('url');
+  });
+
+  it("'url' 模式：**不限制**大小（2026-11-13 用户裁决），忽略 Matrix 的 32MB", () => {
+    setServerUploadLimit(32 * 1024 * 1024);
+    expect(uploadLimitBytes()).toBe(CLOUD_LIMIT_BYTES);
+    expect(CLOUD_LIMIT_BYTES).withContext('云盘模式不设上限').toBe(Number.POSITIVE_INFINITY);
+    expect(isOversize({ size: 60 * 1024 * 1024 })).toBeFalse();
+    expect(isOversize({ size: 2 * 1024 * 1024 * 1024 })).toBeFalse();
+  });
+
+  it("'mxc' 回退模式：回到 Matrix 服务端上限", () => {
+    localStorage.setItem('fmode.sendMode', 'mxc');
+    setServerUploadLimit(32 * 1024 * 1024);
+    expect(uploadLimitBytes()).toBe(32 * 1024 * 1024);
+    expect(isOversize({ size: 40 * 1024 * 1024 })).toBeTrue();
+  });
+
+  it('超限提示文案用的是**当前生效**的上限（回退模式下为 Matrix 值）', () => {
+    localStorage.setItem('fmode.sendMode', 'mxc');
+    setServerUploadLimit(32 * 1024 * 1024);
+    const shown: string[] = [];
+    const alerts = { show: (_t: string, d?: string) => shown.push(d ?? '') };
+    notifyOversize(alerts, [{ name: 'a.zip', size: 40 * 1024 * 1024 }]);
+    expect(shown[0]).toContain('32.0MB');
+  });
+});

src/app/core/upload-limits.ts

@@ -1,48 +1,39 @@
 /**
- * 附件上传限制（2026-11-10）
+ * 附件大小限制（2026-11-10 建立 · 2026-11-13 改口径）
  *
- * ## 为什么要限制
+ * ## 上限跟着「文件存在哪」走
  *
- * 用户裁决：用户上传的文件必须能自动上云。但实际上传有两份：
- *   ① Matrix 原生附件（容器只能读 `mxc://`，走这条）
- *   ② S3 云盘（App 长期查看与成果归档，走这条）
- *
- * 文件越大，两份都传的代价越大，且 Matrix homeserver 有服务端上限
- * （`m.upload.size`，各部署不同）。超过这个值的文件会直接被拒，
- * 用户只会看到一条莫名其妙的失败。
- *
- * ## 为什么是 20MB
- *
- * 取自容器硬约束与历史实测（见 `docs/02-design/plans/2026-11-10-文件上云完整方案.md` §3.3）：
- * ≤20MB 走 `mxc://` 附件，容器能读；更大才需要另走正文链接通道。
+ * - `'url'` 模式（默认，2026-11-13 起）：文件**只**进用户个人 storage，
+ *   Matrix 不再存副本，所以 Matrix 的 `m.upload.size` 与我们无关。
+ *   上限改用云盘口径 `CLOUD_LIMIT_BYTES`。
+ * - `'mxc'` 回退模式：仍要把整份文件传进 Matrix，上限取服务端
+ *   `/media/v3/config` 的 `m.upload.size`（实测 `matrix.fmode.cn` 为 32MB），
+ *   拿不到时不拦截（宁可让服务端报错，也不误伤用户）。
  *
  * ## 拦截位置（两层，缺一不可）
  *
  * - `ChatService.stageFiles()` —— 选文件时就拦，最好的体验：不合格的根本不进来
  * - `ChatService.uploadPending()` —— 发送前兜底，防止暂存期被替换或绕过
  */
+
+import { currentSendMode } from './send-mode';
+
 /**
- * 附件上传限制（2026-11-10 建立 · 2026-11-13 用户裁决调整）
+ * 云盘单文件上限：**不限制**（2026-11-13 用户裁决「上传的文件没有大小限制」）。
  *
- * ## 历史
+ * 依据（实测）：云函数 `AlP56LCKFm` 对 60MB / 500MB / 2GB 均正常签名，
+ * 后端本身没有大小门槛 —— 限制原本只是前端拍的一个数字。
  *
- * 最初取 20MB：超过 Matrix homeserver 的 `m.upload.size` 会被服务端直接拒，
- * 用户只看到一条莫名其妙的失败，所以客户端先挡一道。
+ * ## 大文件的真实风险在「预签名有效期」，不在体积
  *
- * ## 现在（用户裁决 2026-11-13：「去掉限制，看一下 matrix 最大支持多少」）
+ * 预签名 URL 只有 **5 分钟**有效期。60MB+ 在慢网下可能传不完，
+ * 或中途失败后用同一个 URL 重试 → OBS 一律返回 403。
+ * 这已由 `parse-api.uploadFile()` 的「过期自动重签 + 重试」兜住。
  *
- * **不再用写死的 20MB 拦人。** 改为：
- *   1. 上限从服务端 `/media/v3/config` 的 `m.upload.size` **动态获取**
- *      （实测 `matrix.fmode.cn` 为 **32MB / 33554432 字节**）；
- *   2. 拿不到服务端值时**不拦截**（`Infinity`）——宁可让服务端报错，也不误伤；
- *   3. 超限时给出**带了真实上限**的友好提示，而不是一句「超过限制」。
- *
- * ## 为什么保留「拦截」这个能力
- *
- * 上传是「先 S3、再 Matrix」两份都传。超大文件传完 S3 再被 Matrix 拒，
- * 用户白等很久。所以仍在**选文件时**用动态上限做一次预检 ——
- * 但阈值来自服务端，不是产品拍的数字。
+ * ⚠️ 仍保留「单次 PUT、无分片」的事实：超大文件（数 GB）断点续传做不到，
+ * 失败只能整份重传。真要支持超大文件需改分片上传，届时改这里即可。
  */
+export const CLOUD_LIMIT_BYTES = Number.POSITIVE_INFINITY;
 
 /**
  * 服务端上限（字节）。`null` = 尚未探测到。
@@ -56,15 +47,20 @@ export function setServerUploadLimit(bytes: number | null): void {
   serverLimitBytes = typeof bytes === 'number' && bytes > 0 ? bytes : null;
 }
 
-/** 当前生效的上限：优先服务端值；未探测到则不限制 */
+/**
+ * 当前生效的上限：按发送模式取 Matrix 服务端值 / 云盘值。
+ *
+ * `'url'` 模式返回 `Infinity`（不限制）；`isOversize()` 对非有限值直接返回 false。
+ */
 export function uploadLimitBytes(): number {
+  if (currentSendMode() === 'url') return CLOUD_LIMIT_BYTES;
   return serverLimitBytes ?? Number.POSITIVE_INFINITY;
 }
 
 /**
- * 兼容旧调用：`MAX_UPLOAD_BYTES` 的语义是「**已知**的服务端上限」。
+ * 兼容旧调用：`MAX_UPLOAD_BYTES` 是「Matrix 侧已知上限」的固定值。
  *
- * ⚠️ 未探测到服务端值时它是 `Infinity`。判断「会不会超」请用 `isOversize()`。
+ * ⚠️ 是否超限请一律用 `isOversize()` / `uploadLimitBytes()`，它们跟着发送模式走。
  */
 export const MAX_UPLOAD_BYTES = 32 * 1024 * 1024;
 
@@ -87,7 +83,7 @@ export function isOversize(file: { size: number }): boolean {
   return file.size > limit;
 }
 
-/** 超限提示文案（统一口径，单聊/群聊共用；带上服务端真实上限） */
+/** 超限提示文案（统一口径，单聊/群聊共用；带上**当前生效**的上限） */
 export function oversizeMessage(file: { name: string; size: number }): string {
   return `「${file.name}」${formatBytes(file.size)}，超过平台单文件上限 ${formatBytes(uploadLimitBytes())}，未添加`;
 }
@@ -116,8 +112,8 @@ export function notifyOversize(
   if (files.length === 0) return false;
   const detail =
     files.length === 1
-      ? `${oversizeMessage(files[0])}。请换一个不超过 ${formatBytes(MAX_UPLOAD_BYTES)} 的文件。`
-      : `${files.map(oversizeMessage).join('；')}。单个附件上限 ${formatBytes(MAX_UPLOAD_BYTES)}。`;
+      ? `${oversizeMessage(files[0])}。请换一个不超过 ${formatBytes(uploadLimitBytes())} 的文件。`
+      : `${files.map(oversizeMessage).join('；')}。单个附件上限 ${formatBytes(uploadLimitBytes())}。`;
   alerts.show(OVERSIZE_TITLE, detail, 'warning');
   return true;
 }

src/app/desktop/pages/chat/chat.ts

@@ -402,6 +402,13 @@ interface ConversationRow {
                       新建对话
                     </ui-button>
                   </div>
+                } @else if (preparingRoom()) {
+                <!-- 新建会话建房中（2026-11-13 与移动端同口径）：给出明确反馈 -->
+                <div class="no-session" role="status" aria-live="polite" aria-label="正在准备会话">
+                  <i class="fa-solid fa-circle-notch fa-spin" aria-hidden="true"></i>
+                  <h2 class="no-session-title">正在准备会话…</h2>
+                  <p class="no-session-sub">正在为这次对话创建独立空间，请稍候。</p>
+                </div>
                 } @else if (chat.emptyReason() === 'removed') {
                 <!--
                   已软删的会话（2026-11-09 用户裁决）：列表里隐藏，且 URL 不可直达。
@@ -2047,6 +2054,15 @@ interface ConversationRow {
 })
 export class DkChatPage implements OnDestroy {
   readonly chat = inject(ChatService);
+
+  /**
+   * 正在准备会话房间（2026-11-13）。
+   *
+   * 新建对话要建房 + 等容器进房（实测 0.6~3 秒）。原先这段等待期间
+   * 界面还停在上一个会话的画面，用户以为「点了没反应」。
+   * 现在：点击即进入本态，显示明确的「正在准备会话」。
+   */
+  protected readonly preparingRoom = signal(false);
   readonly live = inject(LiveService);
 
   ngOnDestroy(): void {
@@ -3033,12 +3049,19 @@ export class DkChatPage implements OnDestroy {
        */
       if (sessionId === 'new') {
         const ws = this.route.snapshot.queryParamMap.get('ws');
+        /* 建房 + 等进房期间给出明确反馈（2026-11-13，与移动端同口径） */
+        this.preparingRoom.set(true);
         /*
          * 🔴 用 `startBlankWithRoom`（2026-11-12）：一房间一会话要求
          *    会话的专属房间**建好之后**再进入页面，否则首条消息会落进共享房间。
          *    实测建房 0.6~0.7 秒；失败时内部静默降级为共享房间，不阻塞。
          */
-        const created = await this.chat.startBlankWithRoom(id, ws || null);
+        let created: Awaited<ReturnType<typeof this.chat.startBlankWithRoom>> = null;
+        try {
+          created = await this.chat.startBlankWithRoom(id, ws || null);
+        } finally {
+          this.preparingRoom.set(false);
+        }
         if (created) {
           /*
            * 🔴 建出会话后**立刻返回**，不要继续往下走（2026-11-01 修复）。

src/app/desktop/pages/groups/groups.ts

@@ -35,6 +35,9 @@ import { diagnoseLeader } from '../../../core/leader-membership';
 import { LEADER_PROMPT, MEMBER_PROMPT } from '../../../core/workgroup-brief';
 import { applyMention, filterMentionCandidates, parseMentionQuery } from '../../../core/mention-autocomplete';
 import { MatrixClientService } from '../../../core/matrix-client.service';
+import { AlertService } from '../../../core/alert.service';
+import { isOversize, notifyOversize } from '../../../core/upload-limits';
+import { currentSendMode } from '../../../core/send-mode';
 import { SessionService } from '../../../core/session.service';
 import { FmodeApi } from '../../../core/api/fmode-api';
 
@@ -1183,6 +1186,7 @@ export class DkGroupPage {
   private readonly deliverables = inject(DeliverablesService);
   private readonly live = inject(LiveService);
   private readonly chat = inject(ChatService);
+  private readonly alerts = inject(AlertService);
   private readonly mx = inject(MatrixClientService);
   private readonly session = inject(SessionService);
   private readonly api = inject(FmodeApi);
@@ -1968,16 +1972,32 @@ export class DkGroupPage {
     const rid = this.roomId();
     if (!rid || files.length === 0 || this.uploading()) return;
 
+    /* 超限预检（2026-11-13 补）：此前群聊入口完全没有大小拦截 */
+    const oversize = files.filter((f) => isOversize(f));
+    if (notifyOversize(this.alerts, oversize)) {
+      const rest = files.filter((f) => !isOversize(f));
+      if (rest.length === 0) return;
+      files.length = 0;
+      files.push(...rest);
+    }
+
     this.uploading.set(true);
     this.uploadPct.set(0);
     try {
       for (const f of files) {
-        const { publicUrl } = await this.api.uploadFile(f, (pct) => this.uploadPct.set(pct));
-        await this.mx.sendFileCard(rid, {
+        /*
+         * `'url'` 模式（2026-11-13）：先上个人存储、拿到地址再发，云盘失败就**不发**。
+         * `'mxc'` 回退模式：保持改造前的行为 —— 只发 Matrix，不做云端预上传
+         * （评审 S1：原先两种模式都先上云，回退模式下云盘一抖就整批发不出去）。
+         */
+        let publicUrl = '';
+        if (currentSendMode() === 'url') {
+          publicUrl = (await this.api.uploadFile(f, (pct) => this.uploadPct.set(pct))).publicUrl;
+        }
+        await this.chat.sendCloudFile(rid, f, publicUrl, {
           name: f.name,
           size: f.size,
           mimeType: f.type || 'application/octet-stream',
-          url: publicUrl,
         });
       }
       this.loadMessages(rid);

src/app/mobile/pages/messages/messages.ts

@@ -13,6 +13,9 @@ import { MSearchComponent } from '../../components/m-search/m-search';
 import { ChatSessionService } from '../../../core/chat-session.service';
 import { LiveService } from '../../../core/live.service';
 import { MobileChatViewService, SessionRow } from '../../../core/mobile-chat-view.service';
+import { WorkspaceService } from '../../../core/workspace.service';
+import { PromptModalService } from '../../../components/domain/prompt-modal/prompt-modal.service';
+import { UiMDialog } from '../../../ui/mobile/components/dialog/dialog';
 import { isMatrixReady } from '../../../core/format';
 import { fmtRelTime } from '../../../core/time';
 
@@ -36,6 +39,7 @@ type MsgFilter = 'all' | 'group' | 'workspace';
     MEmptyComponent,
     MNewChatSheetComponent,
     MSearchComponent,
+    UiMDialog,
   ],
   template: `
     <div class="m-page m-page--fixed">
@@ -76,12 +80,67 @@ type MsgFilter = 'all' | 'group' | 'workspace';
           </div>
         } @else if (filter() === 'workspace') {
           <!--
-            工作区视图（2026-11-04）：按文件夹分组，与左侧抽屉一致。
-            每个分组带「新建对话」入口，空工作区也显示（否则新工作区无从感知）。
+            工作区视图（2026-11-04 建立 · 2026-11-13 优化）：
+            按文件夹分组，与左侧抽屉一致。
+
+            🔒 2026-11-13 用户要求，三条改动：
+              ① 分组默认**折叠**（区块多时一屏塞不下，先给全局概览）
+              ② 分组可点击折叠/展开（与抽屉同一套 expanded 语义）
+              ③ 补「新建工作区」入口（原先只能去抽屉里建，此页无从下手）
           -->
+          <div class="m-msgws-actions">
+            <button type="button" class="m-msgws-create" (click)="startCreateWorkspace()">
+              <i class="fa-solid fa-folder-plus" aria-hidden="true"></i>
+              新建工作区
+            </button>
+          </div>
+
+          @if (creatingWorkspace()) {
+            <div class="m-msgws-form">
+              <input
+                type="text"
+                class="m-msgws-input"
+                [value]="newWorkspaceName()"
+                placeholder="工作区名称"
+                maxlength="24"
+                aria-label="工作区名称"
+                (input)="newWorkspaceName.set($any($event.target).value)"
+                (keyup.enter)="confirmCreateWorkspace()"
+                (keyup.escape)="cancelCreateWorkspace()"
+              />
+              <button
+                type="button"
+                class="m-msgws-ok"
+                [disabled]="!newWorkspaceName().trim()"
+                (click)="confirmCreateWorkspace()"
+              >
+                创建
+              </button>
+              <button type="button" class="m-msgws-cancel" (click)="cancelCreateWorkspace()">取消</button>
+            </div>
+            @if (workspaceNameTaken()) {
+              <p class="m-msgws-hint">已有同名工作区，换个名字</p>
+            }
+          }
+
           @for (g of workspaceGroups(); track g.id) {
             <section class="m-ws-group">
-              <header class="m-ws-head">
+              <!-- 整行可点，折叠/展开（与抽屉一致：只切内容显隐，不重建 DOM） -->
+              <header
+                class="m-ws-head"
+                role="button"
+                tabindex="0"
+                [attr.aria-expanded]="isWorkspaceOpen(g.id)"
+                [attr.aria-controls]="'m-ws-' + g.id"
+                (click)="toggleWorkspace(g.id)"
+                (keyup.enter)="toggleWorkspace(g.id)"
+                (keyup.space)="toggleWorkspace(g.id)"
+              >
+                <i
+                  class="fa-solid fa-chevron-down m-ws-arrow"
+                  [class.is-collapsed]="!isWorkspaceOpen(g.id)"
+                  aria-hidden="true"
+                ></i>
                 <i class="fa-solid fa-folder" aria-hidden="true"></i>
                 <span class="m-ws-name">{{ g.name }}</span>
                 <span class="m-ws-count">{{ g.rows.length }}</span>
@@ -89,11 +148,25 @@ type MsgFilter = 'all' | 'group' | 'workspace';
                   type="button"
                   class="m-ws-new"
                   [attr.aria-label]="'在 ' + g.name + ' 中新建对话'"
-                  (click)="newChatIn(g.id)"
+                  (click)="$event.stopPropagation(); newChatIn(g.id)"
                 >
                   <i class="fa-solid fa-plus" aria-hidden="true"></i>
                 </button>
+                <!--
+                  工作区「⋯」：重命名 / 删除（2026-11-13）。
+                  与侧边栏 m-drawer 的 openWsMenu 同口径 —— 同一份数据两边能力必须一致，
+                  否则在抽屉里能改名、在这里不能，用户会以为坏了。
+                -->
+                <button
+                  type="button"
+                  class="m-ws-new"
+                  [attr.aria-label]="g.name + ' 更多操作'"
+                  (click)="$event.stopPropagation(); openWsMenu(g.id)"
+                >
+                  <i class="fa-solid fa-ellipsis" aria-hidden="true"></i>
+                </button>
               </header>
+              <div [id]="'m-ws-' + g.id" [hidden]="!isWorkspaceOpen(g.id)">
               @if (g.rows.length > 0) {
                 <ul class="m-list">
                   @for (row of g.rows; track row.session.id) {
@@ -122,6 +195,7 @@ type MsgFilter = 'all' | 'group' | 'workspace';
               } @else {
                 <p class="m-ws-empty">该工作区还没有对话</p>
               }
+              </div>
             </section>
           } @empty {
             <app-m-empty
@@ -192,6 +266,35 @@ type MsgFilter = 'all' | 'group' | 'workspace';
     
       (groupCreated)="onGroupCreated($event)"
     />
+
+    <!-- 工作区操作菜单（与侧边栏同一套交互：底部弹出 + 删除二次确认） -->
+    @if (wsMenu(); as m) {
+      <div class="m-msgws-act" role="dialog" aria-modal="true" [attr.aria-label]="m.title">
+        <div class="m-msgws-mask" (click)="wsMenu.set(null)"></div>
+        <section class="m-msgws-sheet">
+          <p class="m-msgws-title">{{ m.title }}</p>
+          @for (item of m.items; track item.label) {
+            <button
+              type="button"
+              class="m-msgws-item"
+              [class.danger]="item.danger"
+              (click)="runWsMenu(item)"
+            >
+              {{ item.label }}
+            </button>
+          }
+          <button type="button" class="m-msgws-item cancel" (click)="wsMenu.set(null)">取消</button>
+        </section>
+      </div>
+    }
+
+    <ui-m-dialog
+      [(open)]="wsConfirmOpen"
+      [title]="wsConfirmTitle()"
+      [message]="wsConfirmMessage()"
+      [confirmText]="wsConfirmText()"
+      (confirm)="runWsConfirm()"
+    />
   `,
   styles: [
     `
@@ -243,7 +346,165 @@ type MsgFilter = 'all' | 'group' | 'workspace';
         align-items: center;
         gap: var(--sp-2);
         margin-bottom: var(--sp-2);
-        padding: 0 var(--sp-1);
+        padding: var(--sp-2) var(--sp-1);
+        color: var(--ink-2);
+        cursor: pointer;
+        border-radius: var(--r-sm);
+        /* 触控区 ≥44px（迁移到折叠后整行可点，必须满足最低触控尺寸） */
+        min-height: 44px;
+        user-select: none;
+      }
+      .m-ws-head:active {
+        background: var(--surface-active);
+      }
+      .m-ws-head:focus-visible {
+        outline: 2px solid var(--primary);
+        outline-offset: 1px;
+      }
+      /* 折叠箭头：展开朝下、折叠朝右（只动 transform，不布局） */
+      .m-ws-arrow {
+        color: var(--muted);
+        font-size: var(--fs-12);
+        transition: transform 160ms cubic-bezier(0.2, 0, 0, 1);
+      }
+      .m-ws-arrow.is-collapsed {
+        transform: rotate(-90deg);
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .m-ws-arrow {
+          transition: none;
+        }
+      }
+
+      /* 「新建工作区」入口 + 行内表单（2026-11-13） */
+      .m-msgws-actions {
+        padding: var(--sp-3) var(--mob-gutter) 0;
+      }
+      .m-msgws-create {
+        display: flex;
+        align-items: center;
+        gap: var(--sp-2);
+        width: 100%;
+        min-height: 44px;
+        padding: 0 var(--sp-3);
+        border: 1px dashed var(--edge-strong);
+        border-radius: var(--r-md);
+        background: transparent;
+        color: var(--primary);
+        font-size: var(--fs-14);
+        font-weight: 600;
+      }
+      .m-msgws-create:active {
+        background: var(--surface-active);
+      }
+      .m-msgws-form {
+        display: flex;
+        align-items: center;
+        gap: var(--sp-2);
+        padding: var(--sp-2) var(--mob-gutter) 0;
+      }
+      .m-msgws-input {
+        flex: 1;
+        min-width: 0;
+        height: 44px;
+        padding: 0 var(--sp-3);
+        border: 1px solid var(--edge);
+        border-radius: var(--r-md);
+        background: var(--surface);
+        color: var(--ink);
+        /* iOS 输入聚焦不缩放：字号不小于 16px */
+        font-size: var(--fs-16, 16px);
+      }
+      .m-msgws-ok,
+      .m-msgws-cancel {
+        height: 44px;
+        padding: 0 var(--sp-3);
+        border: 0;
+        border-radius: var(--r-md);
+        font-size: var(--fs-14);
+        font-weight: 600;
+      }
+      .m-msgws-ok {
+        background: var(--primary);
+        color: var(--inverse);
+      }
+      .m-msgws-ok:disabled {
+        opacity: 0.45;
+      }
+      .m-msgws-cancel {
+        background: var(--surface-2);
+        color: var(--ink-2);
+      }
+      .m-msgws-hint {
+        margin: var(--sp-1) var(--mob-gutter) 0;
+        color: var(--danger);
+        font-size: var(--fs-12);
+      }
+
+      /* 工作区操作菜单：底部弹出（与抽屉 m-act 同形态） */
+      .m-msgws-act {
+        position: fixed;
+        inset: 0;
+        z-index: var(--z-modal, 1100);
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-end;
+      }
+      .m-msgws-mask {
+        position: absolute;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.35);
+      }
+      .m-msgws-sheet {
+        position: relative;
+        padding: var(--sp-3) var(--sp-3) calc(var(--sp-3) + var(--mob-safe-bottom));
+        border-radius: var(--r-lg) var(--r-lg) 0 0;
+        background: var(--surface);
+        box-shadow: var(--shadow-pop);
+        animation: msgws-up 200ms cubic-bezier(0.2, 0, 0, 1);
+      }
+      @keyframes msgws-up {
+        from {
+          transform: translateY(12px);
+          opacity: 0;
+        }
+        to {
+          transform: translateY(0);
+          opacity: 1;
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .m-msgws-sheet {
+          animation: none;
+        }
+      }
+      .m-msgws-title {
+        margin: 0 0 var(--sp-2);
+        padding: 0 var(--sp-2);
+        color: var(--muted);
+        font-size: var(--fs-12);
+        text-align: center;
+      }
+      .m-msgws-item {
+        display: block;
+        width: 100%;
+        min-height: 48px;
+        border: 0;
+        border-radius: var(--r-md);
+        background: transparent;
+        color: var(--ink);
+        font-size: var(--fs-16, 16px);
+        text-align: center;
+      }
+      .m-msgws-item:active {
+        background: var(--surface-active);
+      }
+      .m-msgws-item.danger {
+        color: var(--danger);
+      }
+      .m-msgws-item.cancel {
+        margin-top: var(--sp-2);
+        background: var(--surface-2);
         color: var(--ink-2);
       }
       .m-ws-head > i {
@@ -437,6 +698,9 @@ export class MbMessagesPage {
   private readonly live = inject(LiveService);
   private readonly sessionsSvc = inject(ChatSessionService);
   protected readonly view = inject(MobileChatViewService);
+  /** 工作区（新建 / 重名判定）；与抽屉共用同一个单例 */
+  protected readonly workspaces = inject(WorkspaceService);
+  private readonly prompt = inject(PromptModalService);
 
   protected readonly keyword = signal('');
   protected readonly filter = signal<MsgFilter>('all');
@@ -446,13 +710,18 @@ export class MbMessagesPage {
   protected readonly pendingWorkspace = signal<string | null>(null);
 
   /**
-   * 标签页（2026-11-07 用户要求）：
-   *   · 去掉「未读」—— 用户不需要按未读筛选
-   *   · 加上「群聊」—— 群聊单独成一个视图，不再混在「全部」里
+   * 标签页。
+   *
+   * 历史：2026-11-07 去掉「未读」、加上「群聊」。
+   *
+   * 🔒 2026-11-13 用户裁决：**群聊入口整体隐藏**（与桌面端一致，
+   *    参见 `m-drawer.ts` 里 `@if (false && groupSessions().length > 0)` 的处理）。
+   *    恢复：把下面的 `group` 项取消注释即可（`filter()` 的 `'group'` 分支与
+   *    `groupRows()` 计算属性都还在，不需要一并改）。
    */
   protected readonly filterOptions = computed(() => [
     { value: 'all' as const, label: '全部' },
-    { value: 'group' as const, label: '群聊' },
+    // { value: 'group' as const, label: '群聊' },  // 🔒 群聊入口隐藏（2026-11-13）
     { value: 'workspace' as const, label: '工作区' },
   ]);
 
@@ -497,6 +766,144 @@ export class MbMessagesPage {
   /** 工作区分组（仅「工作区」筛选时用） */
   protected readonly workspaceGroups = computed(() => this.view.workspaceGroups(this.keyword()));
 
+  /**
+   * 工作区分组的展开状态（2026-11-13）。
+   *
+   * 🔒 默认**折叠**（用户要求）：工作区多时一屏放不下，
+   *    先给用户一份「有哪些工作区、各有几条」的概览，点开再看会话。
+   *    与 `m-drawer.ts` 的 `expanded` 同一套语义：没显式点过就当关闭。
+   *
+   * 用 id → boolean 的映射而不是 Set，是为了兼容 OnPush 下的引用比较。
+   */
+  private readonly wsExpanded = signal<Record<string, boolean>>({});
+
+  protected isWorkspaceOpen(id: string): boolean {
+    return this.wsExpanded()[id] ?? false;
+  }
+
+  protected toggleWorkspace(id: string): void {
+    this.wsExpanded.update((m) => ({ ...m, [id]: !(m[id] ?? false) }));
+  }
+
+  /** 「新建工作区」行内表单是否展开 */
+  protected readonly creatingWorkspace = signal(false);
+  protected readonly newWorkspaceName = signal('');
+
+  /** 输入的名字和已有工作区重名（实时提示，不等到点创建才报错） */
+  protected readonly workspaceNameTaken = computed(() => {
+    const n = this.newWorkspaceName().trim();
+    return n.length > 0 && this.workspaces.hasName(n);
+  });
+
+  protected startCreateWorkspace(): void {
+    this.newWorkspaceName.set('');
+    this.creatingWorkspace.set(true);
+  }
+
+  protected cancelCreateWorkspace(): void {
+    this.creatingWorkspace.set(false);
+    this.newWorkspaceName.set('');
+  }
+
+  /**
+   * 创建并展开新工作区。
+   *
+   * `WorkspaceService.create()` 自己会挡掉空名与重名并返回 null ——
+   * 这里只在成功时展开，**失败时保留表单让用户改**，不静默清空输入。
+   */
+  protected confirmCreateWorkspace(): void {
+    const n = this.newWorkspaceName().trim();
+    if (!n) return;
+    const w = this.workspaces.create(n);
+    if (!w) return; // 重名/空名：UI 上有 workspaceNameTaken 提示，输入保留
+    this.wsExpanded.update((m) => ({ ...m, [w.id]: true }));
+    this.cancelCreateWorkspace();
+  }
+
+  // ---------- 工作区操作：重命名 / 删除（2026-11-13，与侧边栏同口径） ----------
+
+  /** 底部操作菜单的状态 */
+  protected readonly wsMenu = signal<{
+    title: string;
+    items: { label: string; danger?: boolean; run: () => void }[];
+  } | null>(null);
+
+  /** 删除工作区的二次确认（规范 18 §三-13：删除类必须居中 dialog 二次确认） */
+  protected readonly wsConfirmOpen = signal(false);
+  protected readonly wsConfirmTitle = signal('');
+  protected readonly wsConfirmMessage = signal('');
+  protected readonly wsConfirmText = signal('删除');
+  private pendingDeleteWs: string | null = null;
+
+  protected openWsMenu(id: string): void {
+    const ws = this.workspaces.sorted().find((w) => w.id === id);
+    if (!ws) return;
+    const count = this.sessionsSvc.all().filter((x) => x.workspaceId === id).length;
+    this.wsMenu.set({
+      title: ws.name,
+      items: [
+        { label: '重命名', run: () => this.renameWorkspace(id) },
+        {
+          label: `删除工作区${count > 0 ? `（${count} 个会话移到日常对话）` : ''}`,
+          danger: true,
+          run: () => this.askDeleteWorkspace(id, ws.name),
+        },
+      ],
+    });
+  }
+
+  protected runWsMenu(item: { run: () => void }): void {
+    this.wsMenu.set(null);
+    item.run();
+  }
+
+  private renameWorkspace(id: string): void {
+    const ws = this.workspaces.sorted().find((w) => w.id === id);
+    if (!ws) return;
+    this.prompt.open({
+      title: '重命名工作区',
+      value: ws.name,
+      placeholder: '工作区名称',
+      allowEmpty: false,
+      confirmText: '保存',
+      validate: (v) => {
+        const n = v.trim();
+        if (!n) return '名称不能为空';
+        if (this.workspaces.hasName(n, id)) return '已存在同名工作区';
+        return null;
+      },
+      onConfirm: (v) => {
+        this.workspaces.rename(id, v.trim());
+      },
+    });
+  }
+
+  private askDeleteWorkspace(id: string, name: string): void {
+    this.pendingDeleteWs = id;
+    this.wsConfirmTitle.set('删除工作区');
+    this.wsConfirmMessage.set(`确定删除工作区「${name}」？其中的会话会移到「日常对话」，不会被删除。`);
+    this.wsConfirmText.set('删除');
+    this.wsConfirmOpen.set(true);
+  }
+
+  /**
+   * 真正删除：先把其下会话退回「日常对话」，再删工作区。
+   *
+   * 🔴 顺序不能反 —— 直接删工作区会让会话的 `workspaceId` 指向不存在的分组，
+   *    在「工作区」视图里彻底消失（孤儿）。与抽屉 `deleteWorkspace` 同口径。
+   */
+  protected runWsConfirm(): void {
+    const id = this.pendingDeleteWs;
+    this.pendingDeleteWs = null;
+    this.wsConfirmOpen.set(false);
+    if (!id) return;
+    for (const s of this.sessionsSvc.all().filter((x) => x.workspaceId === id)) {
+      this.sessionsSvc.moveTo(s.id, null);
+    }
+    this.workspaces.remove(id);
+    this.wsMenu.set(null);
+  }
+
   /** 在指定工作区里新建对话 */
   protected newChatIn(workspaceId: string): void {
     this.sheetOpen.set(true);