[RFC] MCP add_resource 本地文件上传：渐进式单入口设计

[t0saki]

Motivation

OpenViking 的 MCP 端点目前只能通过远程 URL（http(s) / git / ssh）添加资源。本地文件路径在桌面 Claude Code 上可以靠 ov CLI 解决，但在沙箱化的 agent 环境（Claude web、Manus 等）有三个硬约束：

1. 没有可访问的本地文件系统 —— 文件由用户在对话里上传，只存在于沙箱内
2. 无法安装 ov CLI —— 沙箱镜像不允许任意 binary
3. 无法在 agent context 里安全携带长期 API key —— 长期凭据出现在 prompt 里既是泄露面、也是 attack surface

这个 RFC 提出一个 progressive 单入口 设计：agent 只需调用 add_resource(path=...)，server 在检测到本地路径后返回一份散文形式的两步上传指令，agent 跟着指令上传文件，然后用 temp_file_id 再次调用同一个工具完成入库。

设计已经在 PR #1847 实现并 merge-ready。这个 RFC 的目的是把设计选择和权衡公开化、收集后续优化建议。

Pain Points (from real usage)

1. 沙箱 agent 无法贡献本地文件：用户上传 PDF / 截图，agent 只能复述内容，无法把文件本身存进 OpenViking。
2. agent 拿长期 API key 直接 PUT 文件：技术上可行但风险大 —— key 进入 prompt context、跨多轮持久化、易被截图泄露。
3. 公网图床式公共服务：运维成本高，且 OpenViking 为自托管为主。
4. MCP 协议本身不支持文件附件：1.x spec 里 tool input 是 JSON Schema，没有 binary 通道。

Proposed Design

流程图

agent 视角（只看一个工具）：

┌──────────────────────────────────────────────────────────────┐
│ agent 调 add_resource(path="/tmp/notes.pdf")                 │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ MCP server 检测 path 类型：                                   │
│   - 远程 URL          → 直接走原有入库路径（单步完成，不变）       │
│   - temp_file_id 形   → 提示 agent 用对应 kwarg（自纠错）       │
│   - 本地路径          → 进入下方 progressive 流                 │
└──────────────────────────────┬───────────────────────────────┘
                               │ (本地路径)
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ 1. mint 6 字符 base62 token，绑定 (account, user, tfid)，      │
│    存入 in-memory dict，TTL 默认 10 分钟                       │
│ 2. 返回散文响应（prose，不是 JSON）：                            │
│    "Local file detected — upload required.                   │
│     Step 1. POST file (multipart/form-data, 'file') to:      │
│         {public_base_url}/api/v1/resources/temp_upload_signed│
│         ?token=AbC1xY&temp_file_id=upload_<uuid>.pdf         │
│     Step 2. add_resource(temp_file_id='upload_<uuid>.pdf')   │
│     Expires in ~10 minutes."                                 │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ agent 按指令 POST 文件（沙箱内 outbound HTTP）                  │
│ → server `temp_upload_signed` 路由验证 token、burn-on-use、    │
│   写入 {workspace}/temp/upload/{aid}/{uid}/{tfid}             │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ agent 调 add_resource(temp_file_id="upload_xxx.pdf")         │
│ → MCP server 用现有 ResourceService 入库 → 返回 root_uri       │
└──────────────────────────────────────────────────────────────┘

Why prose, not JSON

实测当工具返回 JSON 时，LLM 倾向于把它当数据原样转述给用户（"I got back this JSON: {...}"）；而散文 + Step 1 / Step 2 排版能可靠触发"按步骤执行"的行为。URL 单独缩进成行也利于 verbatim 提取，避免长 URL 被截断或改写。

Why short stateful token, not HMAC-signed

维度	HMAC-signed	短随机 token + in-memory dict
URL 长度	~150 字符	~30 字符
服务端 secret 管理	需要 sidecar / 配置	不需要
Replay 防护	额外 set 维护	dict.pop 一气呵成
重启后失效	同样失效	同样失效
暴力破解（10min, 1Kreq/s）	极小	≈1/95K 命中（8 字符）或 ≈1/9K（6 字符）

6 字符 + 短 TTL + 绑定 server-chosen temp_file_id（122-bit UUID）+ 每租户子目录隔离，实际攻击面极窄。

Public base URL 解析

5 层 fallback，前两层 explicit、后三层 inferred：

1. OPENVIKING_PUBLIC_BASE_URL 环境变量
2. ServerConfig.public_base_url
3. X-Forwarded-Host + X-Forwarded-Proto（反代链转发）
4. Host header（直连）
5. http://{listen_host}:{listen_port} 兜底

inferred 时，响应自动附带提示："如果上传失败，请在 server 端设置 OPENVIKING_PUBLIC_BASE_URL"。生产环境（MCP proxy + nginx）推荐显式配置。

API Surface

MCP

add_resource(path: str = "", temp_file_id: str = "", description: str = "") —— 单一入口，三分支语义。返回 str：成功消息或散文上传指令。

REST（新增）

POST /api/v1/resources/temp_upload_signed?token=...&temp_file_id=...

• 不依赖 Depends(get_request_context)，token 即身份
• multipart file body，Content-Length + 流式 size 双重限制
• 写入 {upload_dir}/{aid}/{uid}/{tfid}，带 .ov_upload.meta

配置

ServerConfig 新增三项：public_base_url、upload_signed_ttl_seconds（默认 600）、upload_signed_max_bytes（默认 100MB）。

Trade-offs / Alternatives Considered

方案	否决理由
inline base64（让 agent 把 base64 内容塞进 tool input）	占满 LLM 输出 token、对大文件不可行
MCP-native attachment（等协议演进）	1.x spec 没有，排期不可控
agent 直接拿长期 API key	长期凭据进 context，泄露面太大
公共图床式服务	运维成本高，跟 OpenViking 自托管定位冲突
Google Drive 等第三方 connector	引入额外维护成本，且不解决 Manus 等沙箱场景
HMAC-signed token	URL 太长 + 多一份 secret 管理，简化为短 stateful token

Existing vs. New

组件	状态
temp_upload REST（CLI 用）	✅ 复用，不变
resolve_uploaded_temp_file_id	⚠️ 扩展为 dual-lookup（per-tenant + flat fallback）
_cleanup_temp_files	⚠️ 改为 rglob 以覆盖 per-tenant 子目录
ResourceService.add_resource	✅ 不变
_IdentityASGIMiddleware	⚠️ 扩展，捕获 X-Forwarded-* 进 contextvar
upload_token_store	❌ 新模块（~50 行）
temp_upload_signed REST	❌ 新路由
MCP add_resource	⚠️ 扩展为 tri-branch

Out of Scope (Follow-ups)

1. Multi-worker shared replay store（redis / sqlite），当前 in-memory dict 仅支持 single-worker
2. Inline base64 escape hatch for tiny files in sandboxes that block outbound HTTP
3. Chunked / resumable upload for >100MB files
4. Migrating legacy CLI temp_upload to per-tenant layout（需要历史数据 migration）

Open Questions

1. MCP 上传产物的目标 URI 命名空间：目前直接落 viking://resources/<filename>，和 git/URL fetch 混在同一层。是否应该默认带 parent="viking://resources/uploads" 之类的子前缀，把 conversational uploads 和 curated imports 分开？
2. temp_file_id 长度：当前沿用旧 temp_upload 路由的 upload_<uuid4.hex>.<ext>（39+ 字符）。从碰撞安全角度严重过头（10 min TTL + 单租户视角下，16 hex 甚至 12 base62 都绰绰有余）。要不要顺手缩短？利好是上传 URL 总长能压到 ~110 字符，agent verbatim 复制更稳。代价是改动旧路由产物格式，理论上影响第三方依赖。
3. 重名策略：目前 _resolve_unique_uri 用 _1 _2 后缀，长期会很难看。是否应该改用日期前缀或哈希？
4. TTL 默认值：600s（10 分钟）是否够长？太长会增加 token 内存压力，太短在网络抖动 / 长链路 LLM 响应下易失败。
5. 是否暴露 add_resource_inline(name, content_b64) 作为兜底通道（给沙箱无 outbound HTTP 的极端情况）？

References

• 实现 PR：feat(mcp): progressive single-entrypoint upload for local files #1847
• 相关讨论：[RFC] add_resource 支持本地目录导入 #83（本地目录导入）、[RFC] ov setup — Interactive guided setup wizard for OpenViking #1334（ov setup）
• MCP spec: https://modelcontextprotocol.io/