# 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 登录态。

请求：

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

响应：

```json
{
  "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` 上传交互。