浏览代码

docs: 文件投递问题诊断 + 修复验证结果

容器侧创建 plugin-matrix-cloud-url-fallback 插件,使 m.file 事件
的 url 非 mxc:// 时回落 com.fmode.cloud_url,直接读 S3。
真机两轮验证通过(9 字节空壳 + 3607 字节完整 PDF 零误差)。

Co-Authored-By: Claude Code <noreply@anthropic.com>
Huccct 1 小时之前
父节点
当前提交
620888a441
共有 1 个文件被更改,包括 189 次插入 和 0 次删除
  1. 189 0
      docs/00-tracking/2026-11-18-文件投递问题诊断.md

+ 189 - 0
docs/00-tracking/2026-11-18-文件投递问题诊断.md

@@ -0,0 +1,189 @@
+# 文件投递问题诊断:容器发 5 个、App 只显示 1 个
+
+> 2026-11-18 · 基于真实会话 `$approot_mwln4ryj_hrbkyix0` 实测
+
+---
+
+## 一、现象
+
+用户在会话中要求生成 2 个文件,实际结果是:
+
+| 项 | 数量 |
+|---|---|
+| 正文里的链接 | **5 条** |
+| App 显示的文件卡片 | **1 张**(index.html) |
+| 成果页文件 | **1 个** |
+| 对账提示 | 「还有 4 个文件未收到」 |
+
+用户还指出:5 条链接里有 **2 条不是他要的**(`data.json` 是中间产物,`index.html` 重复了一次)。
+
+---
+
+## 二、实测数据
+
+**5 个文件在 s3 上都真实存在(全部 HTTP 200)**:
+
+```
+200  0-mwln8bja17-index.html
+200  1-mwln8bnu08-index.html
+200  2-mwln8bs3g2-deliverable-20261118-125054.pdf
+200  3-mwln7vrfjy-data.json
+200  4-mwln7vwv14-deliverable-20261118-125054.xlsx
+```
+
+**App 侧的数据**:
+
+| 检查项 | 结果 |
+|---|---|
+| 总卡片数 | 1 |
+| 回合 0(容器第 1 次回复)卡片 | 0 |
+| 回合 1(容器第 2 次回复)卡片 | **1**(只有 index.html) |
+| 正文中的 `MEDIA:` 标记 | **无** |
+| 正文中的图片(m.image) | **0** |
+
+---
+
+## 三、根因(三层)
+
+### 🔴 根因 1:容器根本没有发附件事件
+
+容器的回复原文里,5 个文件**全部是正文中的纯文本链接**:
+
+```
+1. 登录页 HTML
+https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/9Xx4oZl9aM/0-mwln8bja17-index.html
+
+已上云(可直接下载)
+https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/9Xx4oZl9aM/1-mwln8bnu08-index.html
+https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/9Xx4oZl9aM/2-mwln8bs3g2-deliverable-20261118-125054.pdf
+https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/9Xx4oZl9aM/3-mwln7vrfjy-data.json
+https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/9Xx4oZl9aM/4-mwln7vwv14-deliverable-20261118-125054.xlsx
+```
+
+**没有 `MEDIA:` 标记,没有 `m.file` 事件**。
+
+App 的卡片**只从 `m.file` 事件生成**(唯一真相源),所以一张卡片都拿不到。
+
+> 那唯一的 1 张 index.html 卡片从哪来?
+> 应该是前几轮某个文件真的以附件形式发过,或者 App 侧有别的补全路径。
+> 无论如何,**本轮 5 个文件里 4 个没有任何附件事件**。
+
+### 🔴 根因 2:容器写文件失败了一个
+
+容器自己在回复里承认:
+
+```
+⚠️ File-mutation verifier: 1 file edit(s) FAILED this turn despite any wording above
+  • — [write_file] {"error": "为免覆盖,我先读再动..."
+```
+
+**有一个文件写入失败**——这就是「我要 2 个文件只给了 1 个」的直接原因之一。
+
+### 🔴 根因 3:App 发的附件容器没收到
+
+容器原文:
+
+> 你说的「这个 PDF」没有传到我这边。**媒体事件的 url 字段只接收 mxc://,
+> 如果放的是 https 链接,就会被静默丢弃**;我检查了入站目录,本次也没有新增文件。
+
+所以用户上传的 PDF 根本没到容器 —— 容器只能**自己编造示例数据**生成表格。
+
+---
+
+## 四、三个问题分属谁
+
+| # | 问题 | 责任方 | 能修吗 |
+|---|---|---|---|
+| 1 | 容器用正文链接代替附件事件 | **容器/适配器** | ❌ App 无法补救(没有事件就没有数据) |
+| 2 | 容器写文件失败 1 次 | **容器** | ❌ App 无法补救 |
+| 3 | App 发的附件容器收不到(mxc vs https) | **App + 容器** | ⚠️ **可能可以修** |
+
+### 关于第 3 点(唯一 App 可能能修的)
+
+容器说「媒体事件的 url 字段只接收 `mxc://`,https 链接会被静默丢弃」。
+
+如果 App 发附件时用的是 **https(s3 链接)** 而不是 **mxc://(Matrix 原生媒体)**,
+容器就会丢弃。
+
+**需要确认 App 发送附件的实现方式**——这是唯一 App 侧有主动权的点。
+
+---
+
+## 五、App 侧已做的兜底
+
+**对账提示**:「还有 4 个文件未收到(正文已列出,点击正文链接可直接打开)」
+
+这个提示**正确工作了**:5 个链接 − 1 张卡片 = 4 个缺失,数量准确。
+它至少让用户知道「文件是有的,只是没做成卡片」,不会误以为文件丢失。
+
+---
+
+## 六、建议
+
+### 给容器方的需求(必须他们改)
+
+1. **正文里的每个交付文件必须配一个 `MEDIA:` 标记**,让适配器生成 `m.file` 事件
+   —— 现在只写链接 = App 拿不到卡片
+2. **修 `write_file` 的失败**
+   —— 回复里已经暴露了 `File-mutation verifier: 1 file edit(s) FAILED`
+3. **不要把中间产物(`data.json`)当交付物列进正文**
+   —— 用户明确说「这两个我没提需求」
+4. **同一个文件不要重复列两次**(`index.html` 出现了两次)
+
+### 给 App 侧(我来做)
+
+**确认 App 发附件时用的是 mxc:// 还是 https**,如果是后者,改成 mxc:// —— 否则容器永远收不到用户的附件。
+
+---
+
+## 七、修复结果(2026-11-18 已验证)
+
+### 容器侧完成的修复
+
+容器执行了 71 步,创建了插件 **`plugin-matrix-cloud-url-fallback`**:
+
+| 项 | 内容 |
+|---|---|
+| 文件 | `plugin.yaml` + `__init__.py` |
+| 功能 | `m.file` 事件的 `url` 不是 `mxc://` 时,回落到 `com.fmode.cloud_url` |
+| 安全 | https 强制 + 域名白名单(s3 / matrix / server.fmode.cn)+ 内网 SSRF 拦截 |
+| 失败处理 | 记录日志,不静默丢弃 |
+| 离线自测 | 7/7 通过 |
+
+**顺带修复的交付质量问题**:
+
+- `data.json` / `build.py` 这类中间产物加入上传黑名单(不再列进交付清单)
+- 同轮同名文件去重(保留 mtime 最新的那份)
+
+### App 侧:无需改动
+
+经核实,App 现有实现**完全符合「文件只走 S3」的要求**:
+
+```
+chat.service.ts:2784  → api.uploadFile()          文件传 S3,拿到 https 链接
+chat.service.ts:2527  → mx.sendFileByUrl(...)     事件里的 url 写 S3 链接
+```
+
+文件本体从头到尾**没有经过我们的服务器**。
+
+### 真机验证(两轮)
+
+| 轮次 | 测试文件 | 容器回复 | 结论 |
+|---|---|---|---|
+| 1 | 9 字节空壳 PDF(只有文件头) | 「收到了,落在 `/opt/data/cache/documents/doc_5d307c0bdcf9_attach-test.pdf`;能从 S3 下载——附件走的是 https 直读通道」 | ✅ 链路通 |
+| 2 | 3,607 字节完整 PDF(1 页) | 「文件大小:3607 字节,页数:1 页。结构齐全:有 /Pages、/Count 1、xref 表、startxref、%%EOF」 | ✅ **零误差,完全一致** |
+
+### 最终状态
+
+```
+用户选文件 → 传 S3 → 事件带 S3 链接 → 容器直连 S3 下载 → 解析
+                                    ↑
+                        全程没有任何文件经过服务器 ✅
+```
+
+| 原问题 | 状态 |
+|---|---|
+| App 发的附件容器收不到 | ✅ **已修复**(插件回落 `cloud_url`) |
+| 容器写文件失败 1 次 | ⚠️ 容器自身问题,需其继续排查 |
+| 中间产物列进交付清单 | ✅ 已加入黑名单 |
+| 同一文件重复列出 | ✅ 已去重 |