# NEX Docus 使用手册

> 面向**使用者与项目管理员**的功能说明（v1.0.0）。
> 部署/运维请看 `docs/deploy/README.md`，本地跑起来请看 `docs/quickstart.md`。

## 目录

- [1. 认识 NEX Docus](#1-认识-nex-docus)
- [2. 登录与账号](#2-登录与账号)
- [3. 界面总览](#3-界面总览)
- [4. 项目空间](#4-项目空间)
- [5. 文档浏览页](#5-文档浏览页)
- [6. 编辑模式（编辑 + 文档索引）](#6-编辑模式编辑--文档索引)
- [7. 成员、角色与分享](#7-成员角色与分享)
- [8. Git 仓库同步](#8-git-仓库同步)
- [9. 知识库对话（AI 问答）](#9-知识库对话ai-问答)
- [10. 个人桌面、通知与个人设置](#10-个人桌面通知与个人设置)
- [11. 系统管理（管理员）](#11-系统管理管理员)
- [12. 快捷键与交互约定](#12-快捷键与交互约定)
- [13. 常见问题](#13-常见问题)

---

## 1. 认识 NEX Docus

NEX Docus 是一个**团队文档管理平台**，把三件事放在一起：

1. **文档管理**：以「项目」为单位组织 Markdown / PDF / 图片等文件，支持目录树、在线编辑、版本化的 Git 同步。
2. **知识检索**：文档可被切块并向量化，配合自研的**全文检索 + 向量检索**双引擎。
3. **AI 问答**：在知识库对话中基于你自己的文档回答，并给出**可点击的引用来源**。

三类典型角色：

| 角色 | 主要动作 | 常用入口 |
| --- | --- | --- |
| 读者 | 浏览、搜索、问答 | 项目空间 → 文档浏览页 / 知识库对话 |
| 编辑者 | 新建、编辑、整理目录、分享 | 编辑模式 |
| 管理员 | 用户/角色/权限、模型配置、系统日志 | 系统管理 |

---

## 2. 登录与账号

访问前端地址（默认开发 `http://localhost:5173`，Docker `http://<服务器>:8080`），未登录会自动跳转 `/login`。

- 输入用户名 + 密码登录，令牌默认有效期 **24 小时**，过期后需重新登录。
- 首次部署的默认管理员账号取决于部署方式（**本地开发**与 **Docker** 默认密码不同，详见 `docs/deploy/changelog.md` §5）。
- **登录后请立即修改密码**：右上角头像 → 个人设置 → 修改密码。
- 被管理员重置密码后，新密码为系统默认密码（同样在个人设置中改为自己的密码）。

登录失败排查：提示「用户名或密码错误」时先确认部署方式对应的默认密码；提示网络错误则先确认后端 `/health` 是否可访问（`curl http://<后端地址>:8000/health`）。

---

## 3. 界面总览

登录后左侧为**功能导航**，内容由服务端下发的菜单权限决定，常见结构：

| 菜单 | 路径 | 用途 |
| --- | --- | --- |
| 个人桌面 | `/desktop` | 个人工作台：常用项目、最近文档、我的动态 |
| 管理面板 | `/dashboard` | 管理员统计视图（用户、项目、文档、活动） |
| 项目空间 → 我的项目 | `/projects/my` | 我拥有/参与的项目 |
| 项目空间 → 分享给我的 | `/projects/share` | 别人分享给我的项目 |
| 知识库空间 | `/chat` | AI 问答会话列表与对话界面 |
| 系统管理 | `/system/*` | 权限管理 / 用户管理 / 角色管理 / 模型配置 / 系统日志 |

顶部栏右侧提供：**主题切换（浅色/深色）**、**通知入口**、**用户菜单**（个人设置、退出登录）。

> 菜单可见性由「系统管理 → 权限管理」控制。看不到某个入口通常是没有该菜单权限，而不是功能坏了。
> 旧版本的知识库路径 `/knowledge`、`/knowledge/my` 会自动重定向到 `/chat`。

---

## 4. 项目空间

**项目**是文档的容器，一个项目对应磁盘上的一份文件目录。

### 4.1 创建项目

「我的项目」→ 右上角「创建项目」→ 填写项目名称、描述。创建者自动成为**所有者**。

### 4.2 项目卡片操作

每个项目卡片右上角提供：

| 图标 | 名称 | 说明 |
| --- | --- | --- |
| ✏️ / 卡片本身 | 打开 | 进入文档浏览页 |
| ⚙️ | 项目设置 | 修改名称、描述、是否公开项目、是否允许公开分享 |
| 🗄 | 知识库向量化 | 打开向量化弹窗，见 §9.1 |
| 👥 | 成员管理 | 添加/移除成员、调整角色、转移所有权 |
| 🗑 | 删除项目 | 仅所有者/管理员，操作不可逆 |

卡片下方展示**文档数量**、**最后更新时间**、**参与人数量**。

### 4.3 项目可见性

- **私有项目**：仅所有者与成员可见。
- **公开项目**：全站登录用户可见（列表只读，编辑仍需 editor/admin 角色）。
- **项目公开分享**：开启后才能生成对外分享链接（见 §7.3）。

---

## 5. 文档浏览页

路径：`/projects/<项目ID>/docs`。这是**阅读与整理**的主界面，左侧目录树 + 右侧渲染区。

### 5.1 目录树

- **点击文件**：右侧渲染 Markdown / PDF / 图片 / 代码等。
- **右键节点**（或节点右侧的更多按钮）：新建文件、新建文件夹、重命名、移动、删除。
- **拖拽**：把文件或文件夹拖到目标文件夹即可移动，拖到根目录即移到顶层。
- 目录树支持折叠全部/展开全部，并展示非文档类文件（可通过筛选开关隐藏）。

### 5.2 页内操作

顶部面包屑右侧：

| 入口 | 说明 |
| --- | --- |
| 搜索文档内容 | 在项目内按关键词搜索文档正文，结果点击后直接跳到目标文件并高亮关键词 |
| 编辑 | 进入编辑模式（§6），并带上当前选中的文件 |
| 分享 | 生成该文件或项目的分享链接，可设置访问密码（§7.3） |
| 刷新 | 重新拉取目录树（外部改动、Git 同步后使用） |
| Git Pull / Git Push | 与远端仓库同步，可选择**同步范围**（仅某个目录）；见 §8 |

---

## 6. 编辑模式（编辑 + 文档索引）

路径：`/projects/<项目ID>/editor`。从文档浏览页点「编辑」进入，会保留当前选中的文件。

### 6.1 三种视图模式

编辑器工具栏**右侧**的分段控件在三种模式间切换，与「全屏」按钮同排，**默认只打开编辑区**：

| 模式 | 图标 | 内容 | 适用场景 |
| --- | --- | --- | --- |
| **编辑**（默认） | 笔 | 只有 Markdown 源码编辑区，占满整个内容宽度 | 专注写作 |
| **分栏** | 双栏 | 左编辑 + 右实时预览 | 检查排版、表格、图片 |
| **预览** | 眼睛 | 只渲染结果 | 交付前自查 |

- 三个按钮只显示图标，鼠标悬停显示「编辑 · 仅编辑区」等说明文字，与同行其他图标保持一致。
- 选择会被记住（写入浏览器本地存储），下次进入编辑模式沿用；不再强制并排打开预览。
- 只有在**分栏**模式下才会出现「同步滚动」开关；纯编辑 / 纯预览时没有左右对照，该开关自动隐藏。

### 6.2 文档索引（Table of Contents）

编辑区右侧悬浮「文档索引」面板列出当前文档的标题层级：

- 目录来自 **Markdown 源码解析**，因此**在纯编辑模式下同样可用**，不依赖预览区是否打开。
- 点击条目：编辑器滚动到对应标题并把光标定位过去（编辑模式下不会跳走页面）。
- 文档没有标题时面板显示为空；标题层级过深时按层级缩进。

### 6.3 保存、重置与未保存保护

- **保存**：把编辑区内容写回服务器文件。快捷键 `Ctrl/Cmd + S`（弹窗打开或正在保存时不会触发）。
- **未保存标记**：内容与服务端版本不一致时，内容区右上角显示「未保存」标记。
- **退出保护**：点「退出编辑」时，只有在**确有未保存改动**才弹确认框（「放弃修改并退出 / 继续编辑」）；关闭浏览器标签或刷新页面时，浏览器也会给出挽留提示。
- **重置**：放弃本地改动，重新加载服务器上最后一次保存的版本（同样需要确认）。

### 6.4 编辑区的其他能力

- **上传文件**：把本地文件（含图片）上传到当前目录，图片自动写入相对路径引用。
- **插入链接**：支持**页内链接**（选择本文标题生成锚点）与**页间链接**（选择项目内其他文件）。
- **新建/重命名/移动/删除**：与浏览页一致的目录树右键菜单。
- **大文档模式**：超大 Markdown 自动切换为轻量编辑器（此时不提供分栏/预览），避免卡顿。
- **全屏**：点工具栏右侧的全屏图标把编辑器铺满整个窗口，左侧项目树的操作按钮不会浮现在编辑器上；再点一次该图标或按 `Esc` 退出全屏。

---

## 7. 成员、角色与分享

### 7.1 项目角色

| 角色 | 能做什么 |
| --- | --- |
| 所有者 owner | 全部权限，含删除项目、转移所有权 |
| 管理员 admin | 管理成员与全部文档，可转让所有权以外的操作 |
| 编辑者 editor | 新建/编辑/删除文档、上传、Git 同步 |
| 查看者 viewer | 只读浏览、搜索、参与 AI 问答 |

### 7.2 管理成员

项目卡片 → 成员管理 → 按用户名搜索添加，并为成员指定角色；也可以在此**转移项目所有权**。移除成员不会删除其创建的文档。

### 7.3 分享链接

- **项目分享**：项目设置里开启「项目公开分享」后生成链接，形如 `/share/project/<分享码>`。
- **文件分享**：文档浏览页对单个文件点「分享」，形如 `/share/file/<分享码>`。
- 可设置**访问密码**，访问时需先输入密码。
- 分享页**只读**，不提供编辑入口；关闭「公开分享」会让既有链接失效。

> 安全提示：分享链接无需登录即可访问，请勿把含敏感信息的文档设为公开分享；管理员应定期清理不再使用的分享。

---

## 8. Git 仓库同步

用于把项目目录和一个 Git 仓库对接（适合团队用 IDE/命令行协作，同时保留 Web 编辑）。

**配置**：项目卡片 → 成员管理旁的 Git 仓库管理入口 → 填写仓库别名、Git 仓库地址、分支、用户名、Token/密码。

**使用**：文档浏览页顶部「Git Pull / Git Push」，两者都可**选择同步范围**（只同步某个子目录），避免大仓一次性同步。

前提与注意：

- 服务端所在主机必须安装 `git` 命令（后端通过命令行调用 git，不是内置实现）。
- 私有仓库请优先使用 **Access Token** 而不是账号密码。
- 冲突时同步会失败并返回 git 的原始报错，请在本地仓库解决冲突后重试。
- 同步完成后点「刷新」重载目录树。

---

## 9. 知识库对话（AI 问答）

路径：`/chat`（新建会话 `/chat/new`）。左侧会话列表，右侧对话区。

### 9.1 先决条件：模型配置 + 向量化

1. 管理员在「系统管理 → 模型配置」中启用至少一个 **chat** 模型（回答用）和一个 **embedding** 模型（向量化用）。
2. 项目卡片 → 「知识库向量化」→ 选择**增量向量化**（只处理新增/变更文档）或**全量向量化**（重建索引）。弹窗展示最近任务的状态、进度与已向量化数量。

> 若弹窗提示「尚未配置可用的向量模型」，说明 embedding 模型未启用，或向量维度与模型实际输出不一致（`ZVEC_EMBEDDING_DIM`）。

### 9.2 提问

- 新建对话时**选择要检索的项目/知识库**，可以选择多个。
- 答案以流式返回，过程中可点**停止**中断生成。
- 回答下方展示**引用来源**（命中的文档与片段），点击可跳转到原文档位置。
- 界面给出**耗时**等运行信息，便于判断是检索慢还是模型慢。

### 9.3 检索行为

问答走**双引擎**：关键词（全文）检索 + 向量（语义）检索，合并后交给模型。因此：

- 精确术语/代码标识符命中靠全文检索；换词、口语化提问靠向量检索。
- **文档改了但答案还是旧的** → 通常是忘了做增量向量化。
- 没向量化过的项目只能靠全文检索，质量会明显下降。

---

## 10. 个人桌面、通知与个人设置

- **个人桌面** `/desktop`：个人工作台，快速进入常用项目与最近编辑的文档。
- **通知中心** `/notifications`：查看项目邀请、文档变更、向量化/同步任务结果等站内通知，支持标记已读。

### 10.1 个人设置（`/profile`）

| 标签页 | 内容 |
| --- | --- |
| 个人资料 | 修改昵称、邮箱、头像（图片不超过 1MB） |
| 修改密码 | 校验原密码后设置新密码，修改后需重新登录 |
| MCP 接入 | 查看/复制本人的 `X-Bot-Id` 与 `X-Bot-Secret`，可**重新生成** Secret |

> **重新生成 MCP Secret 会立即让旧的 Secret 失效**，用旧凭证配置的 MCP 客户端（如 IDE、机器人）需要同步更新。MCP 的接入方式与可用工具见 `docs/sdd/integrations/mcp.md`。

---

## 11. 系统管理（管理员）

| 页面 | 路径 | 作用 |
| --- | --- | --- |
| 权限管理 | `/system/permissions` | 维护菜单与权限点，并给角色授权；决定用户能看到哪些入口 |
| 用户管理 | `/system/users` | 新增用户、启停用、重置密码、分配角色 |
| 角色管理 | `/system/roles` | 新增角色、改名与描述、绑定权限 |
| 模型配置 | `/system/model-configs` | 维护 LLM 服务：类型分 **chat / embedding**，配置名称、服务地址、API Key、模型名、维度，并设为默认/启用 |
| 系统日志 | `/system/logs` | 查看操作与系统日志，用于排查问题 |

模型配置注意：

- **embedding 模型一旦用于向量化，维度就不能随意改**；换模型需同时更新 `ZVEC_EMBEDDING_DIM` 并做**全量向量化**。
- 使用自签名 HTTPS 的私有模型服务时，需要 `DISABLE_SSL_VERIFY=true`（仅该场景，生产保持 `false`）。
- API Key 属于敏感信息，只有管理员可维护，界面上会做掩码处理。

---

## 12. 快捷键与交互约定

| 场景 | 操作 |
| --- | --- |
| 保存当前文档 | `Ctrl/Cmd + S`（编辑模式） |
| 打开文件/目录操作菜单 | 目录树节点**右键** |
| 移动文件/目录 | 目录树中**拖拽**到目标文件夹 |
| 返回上一级视图 | 面包屑点击，或浏览器后退 |
| 深浅色切换 | 顶部栏主题开关，选择会被记住 |

统一交互约定：

- **危险操作**（删除项目/文件/成员、Git 推送等）一律先弹确认框，确认后才执行。
- **操作结果**用轻提示反馈（不打断操作）；表单错误就近显示在字段下方。
- 列表/树加载时显示骨架或加载态；空数据统一显示空状态占位与下一步引导。
- 只读角色（viewer）不会看到编辑、删除类按钮。

---

## 13. 常见问题

**Q：打开项目只有阅读区，找不到编辑按钮？**
A：当前账号在该项目中是「查看者」。让所有者/管理员在成员管理里把角色提升为「编辑者」或「管理员」。

**Q：编辑模式右边没有预览，是不是坏了？**
A：不是。v1.0.0 起**默认只打开编辑区**，点编辑器工具栏右侧的分段控件切到「分栏」或「预览」即可；选择会被记住。

**Q：文档索引（TOC）里是空的？**
A：目录来自 Markdown 标题（`#`/`##`…）。文档没有标题，或超大文档走了大文档模式时，索引可能为空或受限。

**Q：AI 问答说「文档里没有相关内容」，但文档确实存在？**
A：按顺序检查：① 会话是否选中了正确的项目；② 该项目是否做过（增量）向量化；③ 模型配置里 chat / embedding 模型是否都已启用。

**Q：向量化一直不动或失败？**
A：先看弹窗里最近任务的报错，再看「系统日志」和后端日志。常见原因是 embedding 服务不可达、维度不匹配，或 Redis 拒绝写入（`MISCONF`，见 `docs/quickstart.md` FAQ）。

**Q：Git 同步报错 `git: command not found`？**
A：后端主机未安装 git。容器部署时需要在镜像内提供 git（`docs/deploy/README.md` 有说明）。

**Q：分享链接打不开？**
A：确认项目设置里「项目公开分享」仍为开启状态；文件分享需对应文件仍存在；有密码的要先输密码。

**Q：左侧菜单少了一块？**
A：菜单由权限控制，见「系统管理 → 权限管理」中该角色的菜单授权。