# 知识库

「知识库」标签页存放实例内共享的文档。文档可以放在多层嵌套的文件夹里，用富文本编辑器编写标题、列表、表格、代码和附件。文章默认以阅读视图打开，点「编辑」即可修改。

Acahti 没有内置第三方 wiki。界面沿用 Work 文档已经在用的 Plate 富文本编辑器；文件夹、搜索、标签、反向链接和修订快照都由实例自己管理。设计上参考了 BookStack、Outline 和 Docmost，但没有复制它们的应用代码。

## 编写与组织

通过「创建 → 空白文档」创建文章。起一个有意义的标题，写清用户目标，并附上相关工单、仓库或迭代的链接。用文件夹选择器移动文章，在文件夹视图中重命名文件夹。删除非空文件夹会被拒绝，以免误删其中的文章。

一篇文档也可以只呈现一个上传的文件（最大 200 MiB）。选择「创建 → 上传文件」，或把文件、整个文件夹拖到列表上，当前文件夹里的每个 PDF、Word、Excel、PowerPoint 或图片文件都会各自成为一篇文档；拖入的文件夹会变成知识库文件夹。如果上传的内容在知识库中已经存在，会直接打开已有文档，不会再生成一份副本。文档打开后显示该文件，带有「下载」、全尺寸预览，以及用于补充背景的「备注」区域。表格和文件夹树会显示每篇文档的类型图标。

## 在浏览器中编辑文件

Word、Excel、PowerPoint、OpenDocument 和 PDF 文档在页面内嵌的 ONLYOFFICE 编辑器中打开。有编辑权限的人直接输入即可：所有打开该文档的人一起编辑，能看到彼此的光标。修改随时保留；最后一位编辑者离开时、长时间编辑期间每隔几分钟、以及有人在编辑器中点「保存」时，Acahti 都会把修改记为一个新修订。每个保存的版本都会出现在「修订历史」中，其文本也会重新建立搜索索引。只有查看权限的人看到的是同一个编辑器的只读模式。旧格式的 `.doc`、`.xls` 和 `.ppt` 文件以只读方式打开；另存为新格式后才能编辑。

如果文档服务器不可用，页面会改为显示 PDF 预览。外部链接始终显示只读的 PDF 预览。

搜索范围包括 PDF 和 Office 文件中的文本，以及标题、备注和标签。文件上传后不久，compose 中的 Tika 服务会在后台提取文本；没有文本层的扫描图片无法被搜索。

## 分享

文档上的「分享」提供三种传递方式：

- 「发送到聊天」把文档以卡片形式发到一个会话中，成员在 Acahti 中打开。发送受限文档会给会话成员授予查看权限，因此只有管理该文档权限的人才能这样做。
- 「复制链接」复制供已登录成员使用的 Acahti 地址。
- 「外部链接」为没有账号的人创建只读链接。链接默认 7 天后过期（也可选 30 天或永不过期），可以要求密码，也可以禁止下载。地址只显示一次；列表中显示每个链接的过期时间、访问次数和「撤销」按钮。能读取实例级文档的人都可以创建外部链接；受限文档需要由管理其权限的人创建。管理员可以在「管理 → 知识库分享」中为整个实例关闭外部链接，所有已有链接会立即失效。

在聊天中发送的文件可以直接预览，并通过「存入知识库」归档；新文档引用的是同一个已存储的文件。Agent 使用 `chat_share_document`、`knowledge_save_chat_file`、`knowledge_share_link_create`、`knowledge_share_links` 和 `knowledge_share_link_revoke`。

Agent 以 `multipart/form-data` 形式上传到 `POST /work/docs`，带上 `file`，以及可选的 `folder_id`、`title`（默认是去掉扩展名的文件名）和 `body` 备注。每篇文档都会返回其 `kind`（`markdown`、`pdf`、`word`、`excel`、`ppt`、`image`、`html` 或 `file`），上传的文件还会返回用于预览和下载的 `file` 元数据。没有备注的 Markdown 文件会成为文档正文。

文档默认对实例中所有已登录成员可见（`visibility=instance`）。在文章上打开「访问权限」，可将其切换为「受限」，再为个别成员授予 **view** 或 **edit** 权限。所有者、Work 管理员和组织管理员始终拥有完整权限。对其他人来说，受限文章不会出现在列表和搜索结果中；直接访问链接会返回未找到。文件夹只用于组织内容，不是权限边界。不要在文档或附件中存放密钥。

## 搜索与引用

点「检索知识库」，输入标题或短语后提交。搜索范围包括标题和文档正文，支持中文字面匹配和基于分词的全文匹配，标题命中的结果排在前面。全局搜索页还能找到工单、待办、迭代以及有权访问的仓库资源。

打开搜索结果即可查看文档的当前内容。Aidy 在回答中会引用原始页面，读者可以自己核对依据。

## 查看与恢复

在文章标题栏（右上角）打开「修订历史」。菜单按从新到旧列出保留的修订。选择一个修订会在对话框中预览，再点「恢复此修订」即可把该快照设为当前内容。恢复操作会创建一个新修订，并保留中间的历史；对于文件文档，还会恢复该修订当时呈现的文件。如果快照指向的文件夹后来已被删除，恢复时会清空文件夹，但仍会应用标题、正文和标签。删除文章会同时删除其修订历史；恢复只适用于仍然存在的文章。

```bash
acahti mcp call search '{"q":"deployment","type":"document"}'
acahti mcp call knowledge_history '{"id":8}'
acahti mcp call knowledge_restore '{"id":8,"revision":2}'
acahti mcp call document_get '{"id":8}'
acahti mcp call document_update '{"id":8,"visibility":"restricted"}'
acahti mcp call document_grant_set '{"id":8,"login":"alice","role":"edit"}'
acahti mcp call document_grants '{"id":8}'
```

文档的创建、更新、权限授予、文件夹、附件、搜索和修订恢复都可以通过共享的 MCP 和 REST 目录完成。用 `acahti mcp tools` 查看当前安装的服务器具体提供哪些操作。

## 示例界面

![示例工作区中的知识库](/docs/images/knowledge.png)

## 附件与预览

编辑器支持图片以及 PDF 和 Office 文件（Word、Excel、PowerPoint 和 OpenDocument）。图片直接内嵌显示。其他文件会变成附件卡片，带有「下载」按钮，可预览时还有「预览」按钮。预览始终显示为 PDF：原生 PDF 按存储内容直接传输；Office 文件通过 compose 中的 Gotenberg 服务转换，结果缓存在原始对象旁边。原始文件永远不会被替换。工单、待办和聊天中的附件使用同一套预览界面。相同的内容无论被多少文档、评论或消息引用，都只存储一份；没有任何引用的对象会在一小时后删除。

## 原型

在光标处上传 `.html` 或 `.htm` 文件（通过工具栏、拖放或粘贴），原型会在原位显示，阅读和编辑时都一样，并带有「全屏查看」和「下载」。原型在沙箱中运行，无法访问 Acahti：其中的脚本、表单和对话框都能正常工作，但不能读取 cookie 或存储，不能访问外围页面，也不能以你的身份调用 Acahti。内嵌的原型在你点「点击开始交互」之前不响应操作，因此滚轮、触控板和触摸手势仍会滚动它所在的文档；把指针移出、按 Escape 或点「结束交互，继续滚动文档」即可把滚动交还给文档。原型之后的文字始终排在它下方。

## 目录与章节链接

带有标题的文档会在旁边显示「目录」，类似导航窗格：按层级列出标题，可折叠，当前阅读的章节会高亮。选择一个标题即可滚动到该处。需要更宽的版面时可以收起窗格（浏览器会记住）；在窄屏上，通过「目录」按钮打开。鼠标悬停在标题上并选择 **#**，即可复制指向该章节的链接；打开链接会滚动到对应位置。重复的标题会得到带编号的锚点（`details`、`details-1`）。

## 标签、引用与导出

编辑文章时可以添加以逗号分隔的标签。标签会参与搜索，并链接到按该标签筛选的知识库搜索。「引用此文档」列出引用了当前文档 URL 的文章，方便读者追溯相关决策。「下载」会打开一个菜单，可将当前标题和内容导出为 Markdown、PDF（通过打印对话框）或 Word。