> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/share-a-document.md).

# 共享文档

在聊天体验房间中给消息附加 PDF、Word 文件或纯文本文件，并阅读该附件标签显示的内容。

你附加的文档会以文本形式送达你的消息所面向的角色。使用此页面可附加 PDF、Word 文件或纯文本文件，随消息发送，并在文件被读取或描述后查看房间对该文件的报告。

### 前置条件

* 一个已经至少有一个角色在内的聊天体验房间。参见 [将角色添加到房间](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/add-characters-to-the-room.md).
* 一种受支持格式的文件。见 [文件限制参考](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/file-limits-reference.md).

### 附加文档并发送

{% stepper %}
{% step %}

#### 选择文件

选择输入框左侧、你输入内容下方的回形针，然后选择文件。你可以一次选择多个文件。

在你输入内容上方会出现一个标签，显示文件的格式、名称，以及第二行的内容 `读取中…` 在大小之后。
{% endstep %}

{% step %}

#### 等待标签稳定下来

文件被读取或描述后，第二行会发生变化，而其内容会告诉你角色将会收到什么。

当仍有任何标签显示 `读取中…` 或 `描述中…`时，消息框右侧的箭头按钮会保持不可用；等所有标签都稳定后，它会重新可用。消息框也可能因自身原因而锁定，并且总会说明原因。见 [你无法发送消息](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/troubleshooting/composer-is-locked.md).
{% endstep %}

{% step %}

#### 撰写消息并发送

照常写下你的问题并发送消息。消息会连同文件一起发送，标签会移动到你文字上方的对话线程中。

一条消息可以只携带文件而不含任何文字。如果你想让角色就该文件作答，请附上一个问题：在默认 **自动 · 由房间简介决定**下，只携带文件而没有任何文字的消息通常不会引来回复，而位于回形针旁、指明由谁作答的回复标签，则无论你写没写内容都会引来回复。

消息针对谁，也就决定了谁会收到这份文档：它会发送给该消息所面向的角色，而未被消息指向的角色不会收到它。在有两个或更多角色的房间里，标记 `@everyone` ，或在回形针旁将回复标签设为 **所有人都必须回复** ，然后再发送。在只有一个角色的房间里，不需要设置任何标签，所有消息本来就会发送给那个角色。见 [选择由谁回复](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/running-the-room/choose-who-replies.md).

消息发送后，标签会随消息停留在对话线程中，而文件会加入侧边栏的 **在房间中共享** 部分，附带说明 `已描述` 当角色收到的是描述时， `仅名称` 当他们只收到名称时，以及当分享的是文件自身文本时则不附带任何说明。
{% endstep %}
{% endstepper %}

若要在发送前将文件从消息中移除，请选择其标签上的 ×。

### 标签对每种格式的报告方式

标签的第二行总是以文件大小开头。其后内容取决于格式：

| 你附加的内容              | 第二行显示什么                                   |
| ------------------- | ----------------------------------------- |
| 文本文件—`.txt` 或 `.md` | 仅大小，例如 `4 KB`                             |
| CSV 文件              | 大小和行数，例如 `12 KB · 240 行`                  |
| JSON 文件             | 大小和文件的结构—`8 个键` 用于字段集合， `12 项` 用于列表       |
| Word 文件             | 大小和 `文档`，例如 `1.2 MB · 文档`                 |
| 文本被读取的 PDF          | 大小和页数，例如 `1.2 MB · 14 页`                  |
| 页面被描述的 PDF          | 大小、页数，以及有多少页被描述，例如 `574 B · 1 页 · 1 页已描述` |

`已截断` 当该文件包含的文本多于房间从单个文件中共享的文本量时，会追加到该行末尾。文本会在限制处被截断，其余部分不会发送。见 [文件限制参考](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/file-limits-reference.md).

### Word 文件会发生什么

一个 `.docx` 文件会作为文档文本送达角色，而标签会报告 `文档` ，位于大小之后，而不是页数。Word 文件绝不会像携带少量文本的 PDF 那样被描述：如果其文本无法被读取，文件只会连同其名称一起发送。

### PDF 会发生什么

PDF 只有两种读取方式，而两种都说明房间运作正常。标签会告诉你你得到的是哪一种。

携带大量正文的 PDF 会作为该正文共享。角色收到的是文档自身的文字，而标签会报告页数。

携带少量自身文本的 PDF 则会改为被描述。其前几页会以文字描述，最多四页，标签会报告有多少页被描述。角色收到的是这些描述，以及文件超出已描述页面部分所对应的一行，说明哪些页面未被描述。

一份仅有单行内容的单页 PDF 会被描述而不是读取，其标签显示 `1 页 · 1 页已描述` ，位于大小之后。若要让 PDF 的自身文本送达角色，请附加一个真正包含正文的文件。

### 纯文本格式

`.txt`, `.md`, `.csv`，以及 `.json` 文件会以其自身文本的形式送达角色，在上述限制内保持不变。

CSV 文件和 JSON 文件都会在标签中增加一个计数，因此在发送前你可以检查文件是否按你预期的结构被读取。CSV 的行数包括表头行。若某个 JSON 文件无法解析为字段集合或列表，则只显示大小，而其文本仍会按原样共享。

### 当文档无法读取时

房间无法读取的文档仍会被发送，但只以名称形式发送。角色只会得到文件名，别无其他。

房间会在文件稳定后立即在两个地方告诉你。标签第二行会变为 `无法读取` ，位于大小之后，而消息会显示“无法读取 ⟨name⟩；只会共享其名称”。无法被读取也无法被描述的 PDF 会改为显示 `无法描述` ，其消息会显示“无法描述 ⟨name⟩；只会共享其名称”。无论哪种结果，发送的都只有名称本身，侧边栏会将该文件标注为 `仅名称`.

### 下一步

图片遵循不同规则，在附加之前先了解一下角色会被告知关于图片的哪些内容是值得的。

{% content-ref url="/pages/56bfbde4a02d00c401381281f1e85909fdb478ca" %}
[共享图片](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/share-an-image.md)
{% endcontent-ref %}

关于支持的格式、大小和文字限制，以及每种情况下会发生什么：

{% content-ref url="/pages/ef00b5fe3ac7c15b9e6fdc1fbf5eec9658ba9228" %}
[文件限制参考](/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/file-limits-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/wu-dai-ma-ti-yan/chat-experiences/share-files-with-the-room/share-a-document.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.