> 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 的自身文本传达给角色，请附加一份真正包含正文的 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.