Genarrative/docs/technical/CREATION_AGENT_DOCUMENT_INPUT_UPLOAD_2026-04-25.md

Agent 创作页文档输入上传方案

更新时间：2026-04-25

1. 目标

Agent 创作页需要支持用户上传文档，并把文档内容解析成当前输入框里的文本，让用户可以继续编辑后再发送给 Agent。

本次只解决“文档作为输入内容”的轻量闭环，不把文件作为资产入库，也不改变 Agent 会话、消息、草稿生成的后端主链。

2. 职责边界

1. 前端 CreationAgentWorkspace 负责展示上传入口、先做文件格式与大小预检、读取浏览器选择的文件为 base64、调用解析接口、把返回文本追加到输入框。
2. Rust api-server 负责文件类型、大小、编码与文本抽取规则，前端不直接承载文档解析逻辑。
3. 解析完成后仍走现有 onSubmitText 消息提交，不新增 Agent 消息结构。
4. 该能力覆盖所有复用 CreationAgentWorkspace 的 Agent 创作页：RPG / 自定义世界、拼图、大鱼吃小鱼。

3. 首版支持范围

支持扩展名：

1. .txt
2. .md
3. .markdown
4. .csv
5. .json

大小限制：单文件最大 256 KiB。

编码限制：首版按 UTF-8 文本处理。若文件不是 UTF-8，服务端返回 400，由前端展示错误。

暂不支持 .pdf / .doc / .docx 的二进制结构解析；后续扩展时只需要在 Rust 解析接口内部补 extractor，不改变前端输入框接入方式。

4. 接口设计

路径：POST /api/runtime/creation-agent/document-inputs/parse

鉴权：Bearer 登录态。

请求：

{
  "fileName": "世界设定.md",
  "contentType": "text/markdown",
  "contentBase64": "..."
}

响应：

{
  "document": {
    "fileName": "世界设定.md",
    "contentType": "text/markdown",
    "sizeBytes": 128,
    "text": "..."
  }
}

5. UI 规则

1. 输入框左侧新增文件图标按钮，使用图标与 hover title 表达，不在页面铺功能说明文本。
2. 上传前先在浏览器侧拒绝不支持格式、空文件和超限文件，避免无意义读取大文件。
3. 上传处理中禁用按钮和发送按钮，避免同一输入框状态并发写入。
4. 文件解析成功后追加到当前草稿文本后方，若当前草稿非空则用两个换行分隔。
5. 错误展示复用输入区附近的短错误条，不弹独立面板。

6. 验收标准

1. 上传 .txt 或 .md 后，输入框出现文档内容。
2. 输入框已有内容时，解析文本追加在末尾，并用空行分隔。
3. 上传不支持格式或超限文件时，页面展示中文错误，不发送 Agent 消息。
4. 定向测试覆盖解析客户端、Rust 接口和 CreationAgentWorkspace 上传交互。