@fgbg/mdocs 0.8.8 → 0.8.10

package/agent-skills/usage-cli-token/SKILL.md

@@ -0,0 +1,128 @@
+---
+id: usage-cli-token
+name: "CLI Token"
+description: "CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。"
+keywords: []
+source: usage/cli-token.md
+---
+
+# CLI Token
+
+CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。
+
+## 适用场景
+
+- **命令行管理**：在服务器上通过脚本批量创建或更新文档
+- **Agent 集成**：让 AI 编程助手直接读写你的知识库
+- **CI/CD 流水线**：在自动化流程中同步文档
+
+## 创建 Token
+
+1. 打开 mdocs 的设置页，切换到「通用」Tab。
+2. 找到 **CLI Token** 卡片，点击「创建」。
+3. 系统会生成一个新的 Token，**仅在此时展示一次**，请立即复制保存。
+
+![CLI Token 创建界面](./cli-token/cli-token.png)
+
+> Token 是高熵随机字符串（32 字节，base64url 编码），安全强度与 Web 端访客令牌相同。
+
+## 重置 Token
+
+如果 Token 泄露或想更换，点击「重置」：
+
+1. 点击「重置」按钮，弹出确认弹窗。
+2. 确认后，系统会吊销所有已有 Token 并生成一个新的。
+3. 新的 Token 同样**仅在此时展示一次**，请立即复制保存。
+
+## CLI 客户端
+
+mdocs 提供了独立的命令行客户端 `mdocs-cli`（[GitHub 仓库](https://github.com/xuhuafeifei/mdocs-cli)），通过 Token 认证操作文档。
+
+### 安装
+
+```bash
+git clone https://github.com/xuhuafeifei/mdocs-cli.git ~/.mdocs-cli
+```
+
+入口文件：`~/.mdocs-cli/mdocs.mjs`（需 Node.js 18+）
+
+### 连接与认证
+
+全局选项可放在命令任意位置，**优先级高于环境变量**：
+
+| 来源 | Token | 服务端 |
+|------|-------|--------|
+| 命令行 | `--token <token>`（必填其一） | `--ip <host[:port]>` 可选 |
+| 环境变量 | `MDOCS_TOKEN` | `MDOCS_SERVER` |
+| 默认 | — | `http://127.0.0.1:4000` |
+
+```bash
+# 连远程服务器（一次性）
+node ~/.mdocs-cli/mdocs.mjs --token <token> --ip 101.132.222.88:4000 domains
+
+# 或写入环境变量
+export MDOCS_TOKEN="<你的 token>"
+export MDOCS_SERVER="http://101.132.222.88:4000"
+```
+
+### 命令参考
+
+| 命令                                                                               | 用途                          |
+| ---------------------------------------------------------------------------------- | ----------------------------- |
+| `search --q <关键词> [--domain <域ID>] [--topn <数量>]`                            | 全文检索文档                  |
+| `get <文档ID>`                                                                     | 读取文档完整内容              |
+| `create --name <文件名.md> --content <正文> [--domain <域ID>] [--parent <目录ID>]` | 创建文档                      |
+| `update <文档ID> --content <新正文> [--title <新标题>]`                            | 更新文档内容                  |
+| `domains`                                                                          | 列出当前 Token 可访问的所有域 |
+| `mkdir --domain <域ID> --name <目录名> [--parent <目录ID>]`                        | 创建目录                      |
+| `ls <documentId>` 或 `ls "关键词" --domain <域ID>`                                 | 列出目录下子节点              |
+
+### 使用示例
+
+```bash
+# 搜索文档
+node ~/.mdocs-cli/mdocs.mjs search --q "测试文章"
+
+# 创建文档到指定目录
+node ~/.mdocs-cli/mdocs.mjs create \
+  --name "笔记.md" \
+  --title "我的笔记" \
+  --content "# 标题\n\n正文内容" \
+  --domain <域ID> \
+  --parent <目录ID>
+
+# 更新文档
+node ~/.mdocs-cli/mdocs.mjs update <文档ID> \
+  --content "新内容" \
+  --title "新标题"
+```
+
+> 创建和更新文档时，`--content` 支持 Markdown 格式，后端会自动转换为富文本。
+
+## 使用 Token
+
+在命令行或 Agent 配置中，通过 `x-cli-token` 请求头发送：
+
+```bash
+# 使用 curl
+curl -H "x-cli-token: <你的 token>" https://your-mdocs-server.com/api/documents
+
+# 环境变量（与 --token 二选一）
+export MDOCS_TOKEN="<你的 token>"
+export MDOCS_SERVER="http://your-mdocs-server.com:4000"   # 可选，默认本机 4000
+```
+
+也可在每条命令上用 `--token` / `--ip` 覆盖，见上文「连接与认证」。
+
+Token 继承你当前访客的所有权限——能读的文档它也能读，能写的文档它也能写。
+
+## 管理 Token
+
+在设置页的 CLI Token 卡片中，你可以看到所有已创建的 Token 列表及状态（「活跃」/「已吊销」）。当前同一访客只保持一个活跃 Token，重置时会自动吊销旧的。
+
+## 安全说明
+
+- 服务端只存储 Token 的 SHA-256 哈希值，即使数据库泄露也无法伪造请求
+- 原始 Token 仅在创建时展示一次，关闭后无法再次查看
+- 如怀疑 Token 泄露，请立即重置
+

package/agent-skills/usage-comments/SKILL.md

@@ -0,0 +1,149 @@
+---
+id: usage-comments
+name: "评论功能"
+description: "评论功能提供文档内的协作讨论能力，支持对整篇文档发表评论和回复，便于团队协作文档时的沟通与反馈。"
+keywords: []
+source: usage/comments.md
+---
+
+# 评论功能
+
+## 功能概述
+
+评论功能提供文档内的协作讨论能力，支持对整篇文档发表评论和回复，便于团队协作文档时的沟通与反馈。
+
+---
+
+## 打开评论面板
+
+### 入口：文档信息菜单
+
+1. 打开任意文档
+2. 点击编辑器工具栏最右侧的 **⋮ 更多按钮**
+3. 在下拉菜单中点击 **评论**
+4. 右侧滑出评论面板
+
+评论面板会显示当前文档的所有评论，按时间倒序排列（最新的在最上面）。
+
+---
+
+## 发表评论
+
+### 评论输入框
+
+在评论面板顶部的输入框中输入评论内容：
+
+- 支持纯文本输入
+- 最多 512 字符
+- 实时显示剩余字数提示
+
+点击**发送**按钮发表评论。发表后：
+- 评论立即出现在列表中
+- 显示你的访客昵称
+- 显示评论发表时间（相对时间，如「5 分钟前」）
+
+---
+
+## 回复评论
+
+每篇根评论下可以嵌套多条回复，形成讨论线程：
+
+1. 找到想要回复的评论
+2. 点击该评论右下角的 **回复** 按钮
+3. 在出现的输入框中输入回复内容（最多 512 字符）
+4. 点击**发送**
+
+回复会显示在对应根评论的下方，缩进显示，并标注回复人。
+
+---
+
+## 删除评论
+
+### 权限说明
+
+你只能删除**自己发表**的评论或回复，无论它是根评论还是回复。
+
+### 删除操作
+
+1. 找到自己发表的评论
+2. 评论右下角会显示红色的 **删除** 按钮
+3. 点击删除，弹出确认对话框
+4. 点击**确定**完成删除
+
+删除后该评论会从列表中即时消失。
+
+### 删除根评论的影响
+
+删除根评论时，该评论下的所有回复也会被一并删除。
+
+---
+
+## 评论计数
+
+评论面板顶部显示当前文档的**有效评论数**：
+
+- 只统计未删除的评论
+- 根评论和回复合计计数
+- 实时更新（发表/删除后立即刷新）
+
+---
+
+## 权限规则
+
+| 操作 | 权限要求 |
+|-----|---------|
+| 查看评论 | 能阅读该文档即可 |
+| 发表评论 | 有该文档的编辑权限 |
+| 发表回复 | 有该文档的编辑权限 |
+| 删除评论 | 仅该评论的发表者 |
+
+### 不同场景下的权限表现
+
+| 文档权限 | 能否查看评论 | 能否发表/回复 | 能否删除自己的评论 |
+|---------|-------------|--------------|------------------|
+| 公开可读 | ✅ 可以 | ❌ 不可以 | ❌ 不可以 |
+| 公开可编辑 | ✅ 可以 | ✅ 可以 | ✅ 可以 |
+| 受限域成员 | ✅ 可以 | ✅ 可以 | ✅ 可以 |
+| 被邀请只读 | ✅ 可以 | ❌ 不可以 | ❌ 不可以 |
+| 被邀请可编辑 | ✅ 可以 | ✅ 可以 | ✅ 可以 |
+
+---
+
+## 使用建议
+
+### 建议用于
+
+- **文档反馈**：对内容提出修改建议
+- **疑问讨论**：就文档中的某个点提问和解答
+- **协作备忘**：记录编辑思路和决策理由
+
+### 不建议用于
+
+- 存储敏感信息（评论无加密，与文档内容同级别安全）
+- 长篇大论（建议直接编辑文档正文）
+- 发送与文档无关的闲聊消息
+
+---
+
+## 常见问题
+
+### 评论保存在哪里？会同步吗？
+
+评论存储在服务器数据库中，与文档绑定，不会写入 Markdown 文件。所有访问该文档的访客都能看到相同的评论列表。
+
+### 可以编辑评论吗？
+
+目前不支持编辑已发表的评论，只能删除后重新发表。
+
+### 评论有通知吗？
+
+目前没有通知机制，需要手动打开评论面板查看新评论。
+
+### 删除的评论可以恢复吗？
+
+不可以。删除操作不可逆，请谨慎操作。
+
+### 为什么我看不到删除按钮？
+
+只有评论的发表者才能看到删除按钮。如果不是你发的评论，就不会显示该按钮。
+

package/agent-skills/usage-domain-members/SKILL.md

@@ -0,0 +1,104 @@
+---
+id: usage-domain-members
+name: "受限域成员与名单模板"
+description: "本文说明如何在 mdocs 里维护 **restricted（受限）域** 的成员，以及如何使用 **域成员模板** 减少重复勾选。与权限模型相关的设计背景见 [域隔离](../core-concepts/domain.md)。"
+keywords: []
+source: usage/domain-members.md
+---
+
+# 受限域成员与名单模板
+
+本文说明如何在 mdocs 里维护 **restricted（受限）域** 的成员，以及如何使用 **域成员模板** 减少重复勾选。与权限模型相关的设计背景见 [域隔离](../core-concepts/domain.md)。
+
+## 谁能用这些功能
+
+- **管理某受限域的成员**：仅限该域的 **创建者**（你在域列表里对该域拥有完整操作按钮的那个人）。
+- **创建 / 编辑 / 删除成员模板**：当前登录访客自己的模板列表；模板数据按创建者隔离，其他人看不到你的模板。
+
+公开域、个人域 **没有**「成员」名单能力：前者对所有人开放入口，后者只有域主一人。
+
+## UI 界面
+
+![](./domain-members/UI.png)
+
+> 域管理界面显示的域，都是用户可见的域. 公开域，团队成员的受限域，私域 （如果域中存在一篇文章邀请了别的用户，那么该域对那名用户也是可见的，哪怕是私域）
+
+## 入口在哪里
+
+点击应用左下角，包含用户头像的栏目
+
+![](./domain-members/settings.png)
+
+| 侧栏项（中文界面示例） | 作用                                                   |
+| ---------------------- | ------------------------------------------------------ |
+| **域管理**             | 新建域、筛选域类型、对 **受限域** 打开「成员」维护弹窗 |
+| **域成员模板**         | 维护可复用的访客 ID 名单（名称 + 一套勾选结果）        |
+
+「活跃访客目录」来自服务端的访客列表接口：一般包含当前未停用的访客，用于左侧勾选。
+
+## 创建受限域与首批成员
+
+1. 进入 **设置 → 域管理**。
+2. 在「新建域」里填写名称，类型选择 **受限**（restricted），提交创建。
+   ![](./domain-members/domain-create.png)
+
+3. 创建成功后，**你（创建者）会自动写入该域的 `domain_members`**，无需额外操作。
+
+之后团队其他成员要 **完整进入该域**（侧栏树、在域内 **新建文档** 等），需要由创建者把他们加进成员名单。
+
+## 维护成员名单
+
+1. 在 **域管理** 表格中找到目标 **受限域**，且你仍是创建者。
+2. 点击 **成员**（或界面中与「管理成员」同义的按钮），打开 **访客选择器** 弹窗。
+   ![](./domain-members/restrict-domain.png)
+
+弹窗习惯用法：
+
+- **左栏**：当前可选的访客目录，支持搜索昵称或 UUID 片段；勾选即加入右侧。
+- **右栏**：即将保存的成员；每人显示完整 **visitor_id**（UUID），便于复制给队友核对。
+- **域创建者** 在行内会锁定，**不能从名单中移除**；服务端在保存时也会 **自动把创建者并回名单**，所以不要依赖「删掉创建者」来转让域。
+
+![](./domain-members/choose-window.png)
+
+保存时的规则简述：
+
+- 只允许提交 **在库里仍然存在的** visitor id；若包含从未注册过的 id，接口会报错，需对照 UUID 修正。
+- **已停用** 的访客若仍在历史成员里，界面可能以灰色或标签提示「停用」；创建者仍可保留这些 id 在名单中（是否保留由团队策略决定）。
+
+仅从 **左栏目录** 勾选时，列表里只会出现 **当前「活跃」访客**。若某人已停用，但 **曾经写入过成员表**，打开弹窗时仍可能在 **右栏** 看到完整 UUID 与相应提示（数据来自成员接口，不依赖左栏是否展示）。
+
+### 套用模板（在成员弹窗内）
+
+弹窗顶部可选择 **已有模板** 并点击 **套用**：
+
+![](./domain-members/template.png)
+
+- 会把模板里保存的访客 ID **与当前左栏目录求交集**：只有 **此刻仍在活跃目录里** 的 ID 会被 **追加** 进右侧勾选（不会清空你已选的人）。
+- 若模板里有 ID 暂不在目录（例如对方访客已停用），套用 **不会** 自动带上这些 ID；需要你改模板、或等对方恢复为活跃访客后再套用 / 勾选。
+
+编辑某一模板时，选择器里 **不会** 把「当前正在编辑的这一条」放进套用下拉，避免无意义的自引用。
+
+## 维护「域成员模板」
+
+在 **设置 → 域成员模板**：
+
+1. **新建**：填模板显示名称，用访客选择器（与域成员相同的双栏界面）选好一组人，保存。
+2. **编辑**：在列表中选一条，改名称或人员后保存。
+3. **删除**：删除前会有确认提示。
+
+![](./domain-members/template-mantain.png)
+
+模板 **不会** 自动同步到任何域；只是在 **域管理 → 成员** 弹窗里作为「一键追加勾选」的快捷方式。真正生效仍以你在成员弹窗里 **确认保存** 后的结果为准。
+
+## 与文档邀请的区别
+
+- **域成员**：决定谁能 **完整进入** 受限域（与创建者同级入口）、能否在该域 **新建文档** 等。
+- **文档级邀请**（`document_invites` 叠加层）：细到单篇文档。非域成员也可只被邀请到某几篇文档，此时在域侧往往是 **受限入口**，不能随意在域内开新档。详见 [文档级邀请](../core-concepts/invitation.md)。
+
+> 注意：邀请与域成员**互斥**——已是域成员的人不能被邀请。
+
+## 设计取舍
+
+- **受限域** mdocs偏向于小规模团队文档维护，在设计之初并未考虑引入组织架构的复杂管理能力。但很多场景下，存在团队成员这一概念，因此引入受限域，只允许团队成员进入 
+- **成员模板** 项目不维护组织架构，因此受限域的域成员需要重复添加，为了解决该问题，引入成员模板导入功能，避免重复行为
+

package/agent-skills/usage-drafts/SKILL.md

@@ -0,0 +1,111 @@
+---
+id: usage-drafts
+name: "草稿与同步"
+description: "编辑环境中存在一个天然矛盾：用户希望内容「随时保存，永不丢失」，但网络可能不稳定，服务器可能暂时不可用。mdocs 用**本地优先 + 按需发布**的草稿机制来解决这个问题。"
+keywords: []
+source: usage/drafts.md
+---
+
+# 草稿与同步
+
+## 设计意图
+
+编辑环境中存在一个天然矛盾：用户希望内容「随时保存，永不丢失」，但网络可能不稳定，服务器可能暂时不可用。mdocs 用**本地优先 + 按需发布**的草稿机制来解决这个问题。
+
+## 架构
+
+```
+用户编辑
+    │
+    ▼
+Lexical 编辑器（富文本）
+    │
+    ├── 自动保存（1000ms 防抖）──────────────────┐
+    │       │                                    │
+    │       ▼                                    │
+    │   IndexedDB（浏览器本地数据库）               │
+    │   存储：正文 + 开编 commit（localBaseCommitId）│
+    │                                              │
+    ├── 自动发布（空闲 30 秒后）───────────────────┤
+    │       │  （每 10 秒扫描一次）                  │
+    │       ▼                                    │
+    │   后端 API（更新正文 + 提交图）              │
+    │                                              │
+    ├── 手动「发布」──────────────────────────────┤
+    │                                              │
+    └── 失焦 / 切换标签页 ────────────────────────┘
+             立即保存当前内容
+```
+
+## 本地数据分工（v0.7.9+）
+
+| 数据 | 作用 |
+|------|------|
+| **IndexedDB 草稿** | 未发布正文、标题、开编时的 `localBaseCommitId` |
+| **activeDocMeta**（内存） | 当前打开这篇的**服务端元信息**（权限、路径、owner、当前 head 等），供界面共用；**不含正文** |
+| **编辑器** | 显示与编辑正文；有草稿时以草稿为准，无草稿时以服务器 GET 为准 |
+
+打开文档时：**一定会请求服务器**更新 meta；正文则 **有草稿读草稿、无草稿读服务器**，二者互斥，不会把两套正文混在一个对象里。
+
+## 三层保存策略
+
+| 触发时机 | 保存目标 | 说明 |
+|---------|---------|------|
+| 编辑后 1 秒无操作 | IndexedDB | 防抖，避免频繁写入 |
+| 编辑器失焦（blur） | IndexedDB | 切换到其他元素时立即保存 |
+| 标签页隐藏（visibilitychange） | IndexedDB | 用户切走或关闭标签时保底 |
+
+补充说明：
+
+- **首次编辑**时才创建草稿（不是打开文档就创建）。
+- 首次落盘会记录 **`localBaseCommitId`**（开编时服务端 head）。
+- 后续自动保存只更新正文和标题，**不**重置开编基准。
+
+## 发布流程
+
+### 自动发布（可选）
+
+在 [设置](./settings.md) 中开启「自动同步至云端」后：
+
+- **每 10 秒**扫描 IndexedDB；
+- 某篇草稿 **超过 30 秒** 没有新的自动保存 → 尝试发布。
+
+### 手动发布
+
+1. 点击「发布」
+2. 编辑器内容序列化后 `PUT` 到服务器（带开编 commit 做版本校验）
+3. **成功后**：删除本地草稿 → 再 GET 拉取最新 meta；正文与刚发布内容一致时**不重载编辑器 DOM**（避免视口跳动），仅在服务端正文不一致时才整棵刷新编辑器
+
+### 无草稿也能发布
+
+若打开后尚未触发自动保存（尚无 IndexedDB 草稿），仍可直接发布：内容以编辑器为准，版本号以当前 meta 中的 head 为准。
+
+## 发布失败
+
+无论自动还是手动，失败时草稿一般仍保留在本地。
+
+| 情况 | 行为 |
+|------|------|
+| **任意自动发布失败**（v0.8.5+） | 草稿标记 `publishError`，**停止自动重试**；设置页「未发布草稿」显示失败原因；手动点「发布」会先清除标记再重试 |
+| **缺少版本基准** | 多见于旧版创建的目录描述（`___desc___.md`）；升级到 **0.8.5+** 并重启服务后重新打开该目录可恢复；或删除本地草稿 |
+| **自动发布 404** | 服务端文档已删、本地仍有草稿；可 **另存为新文档** |
+| **409 版本冲突** | 进入 [版本冲突与合并](./merge-conflicts.md) 流程 |
+
+重新打开文档且服务端已有 `headCommitId` 时，会自动补写草稿的 `localBaseCommitId` 并清除「缺版本基准」类失败标记。
+
+## 断网场景
+
+- **断网时**：继续编辑，草稿在 IndexedDB
+- **重新打开**：有草稿则恢复草稿正文；meta 仍会从服务器 GET（需联网）
+
+## 拉取更新（Pull）
+
+- **无未发布草稿**：可拉取远端最新正文与 meta。
+- **有未发布草稿**：不覆盖式 pull，避免误盖本地副本。
+
+## 设计取舍
+
+- **本地优先**：编辑不依赖网络；恢复后自动或手动发布
+- **发布后强制对齐**：删草稿 + GET，减少「单用户自动发布后又冲突」的困惑
+- **IndexedDB**：容量大、异步，不阻塞 UI
+

package/agent-skills/usage-flowchart/SKILL.md

@@ -0,0 +1,88 @@
+---
+id: usage-flowchart
+name: "流程图生成"
+description: "mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像使用 Visio 或 draw.io 一样拖拽绘制，同时将图表数据嵌入文档内容。"
+keywords: []
+source: usage/flowchart.md
+---
+
+# 流程图生成
+
+## 设计思路
+
+mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像使用 Visio 或 draw.io 一样拖拽绘制，同时将图表数据嵌入文档内容。
+
+## 插入方式
+
+在编辑器新行中输入以下内容后回车：
+
+```
+---meta2d---
+```
+
+编辑器会自动识别并打开 Meta2d 画布编辑器。
+
+## 数据格式
+
+图表在文档中以 `---meta2d---` 围栏块的形式内嵌存储：
+
+```
+---meta2d---
+{ "pens": [ … ] }
+---/meta2d---
+```
+
+编辑器渲染时：
+- 识别到 `---meta2d---` 块 → 调用 canvas2svg 渲染为 SVG 预览
+- 双击块 → 打开 Meta2d 画布编辑器，可拖拽编辑
+- 保存 → 将 JSON 写回文档内容
+
+## 编辑器界面
+
+![](./flowchart/flowchart.png)
+
+## 支持的图形
+
+矩形、圆角矩形、圆形、菱形、三角形、五边形、文本、线条、数据节点、数据库、文档、显示、手动输入、并行、注释、子流程、队列、内部/外部存储等。
+
+## 设计取舍
+
+- **为什么用 Meta2d 而非 Mermaid**：Mermaid 适合由文本生成图表，但交互式编辑体验不够直观。Meta2d 提供了拖拽式 GUI 编辑器，更接近白板体验
+- **数据内嵌在文档内容中**：图表以 JSON 格式内嵌在文档内容里，随文档一起存储，复制、备份都很方便
+
+## Markmap 思维导图
+
+### 使用方式
+
+在编辑器中创建 `markmap` 代码块：
+
+````markdown
+```markmap
+# 根节点
+## 分支 1
+### 子节点 1.1
+### 子节点 1.2
+## 分支 2
+```
+````
+
+### 特性
+
+- **Markdown 语法**：使用标准 Markdown 标题层级（`#`）定义树形结构
+- **实时渲染**：编辑 Markdown 时下方实时预览思维导图
+- **交互一致**：与 Mermaid 代码块交互方式完全相同
+  - 点击内部显示源码编辑器
+  - 点击外部隐藏源码，只显示思维导图
+  - 点击图表进入全屏预览模式
+- **全屏预览**：支持缩放、拖拽，查看复杂导图更方便
+- **错误提示**：Markdown 语法有误时显示红色错误框
+
+### 与 Mermaid 的区别
+
+| 特性 | Markmap | Mermaid |
+|------|----------|---------|
+| 语法 | Markdown 标题层级 | Mermaid 专有语法 |
+| 用途 | 思维导图、知识树 | 流程图、时序图、类图等 |
+| 交互 | 点击折叠/展开节点 | 静态渲染 |
+| 适合场景 | 头脑风暴、知识梳理 | 技术架构、业务流程 |
+

package/agent-skills/usage-markdown/SKILL.md

@@ -0,0 +1,105 @@
+---
+id: usage-markdown
+name: "编辑体验"
+description: "mdocs 的编辑器基于 Lexical（Meta 开源的富文本引擎），配合 `@lobehub/editor` 插件体系。核心思路是：**用富文本编辑，以 JSON 存储**。"
+keywords: []
+source: usage/markdown.md
+---
+
+# 编辑体验
+
+## 设计思路
+
+mdocs 的编辑器基于 Lexical（Meta 开源的富文本引擎），配合 `@lobehub/editor` 插件体系。核心思路是：**用富文本编辑，以 JSON 存储**。
+
+```
+编辑时
+  用户操作 → Lexical JSON（保留全部格式信息）
+  自动保存 → IndexedDB（Lexical JSON）
+
+发布时
+  内容写入 → 文件系统（Lexical JSON 文件）
+```
+
+这意味着：
+
+- 编辑时享受完整的富文本体验（标题、加粗、表格、代码块等）
+- 文档以 Lexical JSON 格式持久化，保留全部语义信息，重新打开时精确恢复
+- 由于是自有格式，文档**只能由 mdocs 加载**（未来会提供导出 Markdown 功能）
+
+## Markdown 导入
+
+mdocs 支持直接粘贴或通过 API 传入 Markdown 文本，后端会自动转换为 Lexical JSON 存储。
+
+### 粘贴 Markdown
+
+在编辑器中直接粘贴（`Ctrl+V`）Markdown 文本，内容会按富文本格式渲染，保留标题、粗体、列表、表格、代码块等结构。
+
+### API / CLI 传入 Markdown
+
+通过 API 或命令行客户端创建/更新文档时，传入的 Markdown 内容会自动转换：
+
+```bash
+# CLI 创建文档，直接传 Markdown
+node ~/.mdocs-cli/mdocs.mjs create \
+  --name "笔记.md" \
+  --content "# 标题\n\n这是**粗体**和*斜体*"
+```
+
+转换能力包括：
+- 标题 h1-h6、段落、换行
+- 粗体/斜体/删除线/行内代码/超链接
+- 有序/无序列表（支持嵌套）
+- 代码块（保留语言标识）
+- 引用块、分隔线
+- 表格（含表头、合并单元格）
+
+## 编辑器功能
+
+### 富文本工具栏
+
+编辑器顶部提供了格式化工具栏，支持斜杠命令（输入 `/` 触发）：
+
+- **撤销 / 重做**
+- **文档首尾插行**：在全文最上方或最后一行之后插入空段落，光标进入新行
+- **标题**：H1 ~ H3
+- **文本格式**：加粗、斜体、行内代码
+- **插入元素**：表格、链接、图片、分割线、数学公式（TeX）、Meta2d、Markmap
+- **代码块**：基于 CodeMirror 的代码编辑器，支持语法高亮
+- **文件附件**：上传并插入文件
+
+斜杠菜单可搜索上述插入项（含 Meta2d / Markmap）。
+
+### 大纲面板
+
+编辑器右侧自动提取文档标题层级，生成可点击的导航大纲，方便在长文档中快速跳转。
+
+![](./markdown/outline.png)
+
+### 文档信息菜单
+
+编辑器工具栏右侧提供文档信息入口（三条线图标），点击可查看：
+
+**元信息区**
+- **创建者**：显示访客昵称，未设置昵称时显示 visitorId 前 8 位
+- **创建时间**：文档创建的本地化日期格式
+- **大小**：文件体积（KB/MB 自动适配）
+- **上次编辑**：最后修改的本地化时间
+
+**操作区**
+- **收藏/取消收藏**：一键切换当前文档的收藏状态
+- **修改文章权限**：后续版本开放完整的权限修改对话框
+
+> 💡 点击菜单外部区域可自动关闭下拉菜单。收藏按钮 hover 时有缩放动画效果。
+
+### 流程图
+
+支持 **Meta2d** 流程图，输入 `---meta2d---` 后回车即可打开画布编辑器，拖拽绘制流程图。
+
+详见[流程图生成](./flowchart.md)。
+
+## 设计取舍
+
+- **选择 Lexical 而非 Prosemirror/Slate**：Lexical 对 React 生态更友好，插件系统清晰，且 `@lobehub/editor` 提供了开箱即用的工具栏和斜杠菜单。只需在lobehub项目基础上进行额外开发，避免重复造轮子
+- **JSON 存储**：保留完整的富文本结构，重新打开时精确还原编辑状态。代价是数据不能直接用文本编辑器阅读——未来会提供 Markdown 导出
+