@fgbg/mdocs 0.8.9 → 0.8.12

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

@@ -0,0 +1,123 @@
+---
+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）。
+- 后续自动保存只更新正文和标题，**不**重置开编基准。
+
+## 发布流程
+
+### 设置里的开关
+
+打开 **设置 → 保存与发布**：
+
+![设置 → 保存与发布](./drafts/save-publish-settings.png)
+
+| 项 | 说明 |
+|----|------|
+| **自动保存（本地快照）** | 内容持续写入浏览器本地快照，避免编辑丢失（界面展示为始终可用） |
+| **自动同步至云端** | 空闲后把草稿推到服务器；网络不稳或多端冲突时可能暂停同步以保护数据 |
+| **查看未发布草稿** | 列出尚未成功发布到服务端的本地草稿，可点进对应文档继续编辑或手动发布 |
+
+### 自动发布（可选）
+
+在设置中开启「自动同步至云端」后：
+
+- **每 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,108 @@
+---
+id: usage-flowchart
+name: "流程图生成"
+description: "mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像使用 Visio 或 draw.io 一样拖拽绘制，同时将图表数据嵌入文档内容。"
+keywords: []
+source: usage/flowchart.md
+---
+
+# 流程图生成
+
+## 设计思路
+
+mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像使用 Visio 或 draw.io 一样拖拽绘制，同时将图表数据嵌入文档内容。
+
+## 插入方式
+
+### 斜杠菜单（推荐）
+
+不必手写 Markdown / 围栏语法。在编辑器中：
+
+1. 新起一行（或光标在段落里）输入 `/`
+2. 选择 **Meta2d**，或继续输入 `meta2d` 过滤后回车
+3. 插入后会打开 Meta2d 画布，拖拽绘制即可
+
+![输入 / 打开菜单并选择 Meta2d](./markdown/slash-menu.png)
+
+完整菜单项说明见 [编辑体验 · 斜杠菜单](./markdown.md#斜杠菜单推荐快捷入口)。
+
+### 其他方式（可选）
+
+仍支持在新行输入围栏后回车打开画布（适合熟悉旧习惯的用户）：
+
+```
+---meta2d---
+```
+
+日常插入请优先用 `/`。
+
+## 数据格式
+
+图表在文档中以内嵌块保存（存储形态，**插入时不必手写**）：
+
+```
+---meta2d---
+{ "pens": [ … ] }
+---/meta2d---
+```
+
+编辑器渲染时：
+- 识别到该块 → 调用 canvas2svg 渲染为 SVG 预览
+- 双击块 → 打开 Meta2d 画布编辑器，可拖拽编辑
+- 保存 → 将 JSON 写回文档内容
+
+## 编辑器界面
+
+![](./flowchart/flowchart.png)
+
+## 支持的图形
+
+矩形、圆角矩形、圆形、菱形、三角形、五边形、文本、线条、数据节点、数据库、文档、显示、手动输入、并行、注释、子流程、队列、内部/外部存储等。
+
+## 设计取舍
+
+- **为什么用 Meta2d 而非 Mermaid**：Mermaid 适合由文本生成图表，但交互式编辑体验不够直观。Meta2d 提供了拖拽式 GUI 编辑器，更接近白板体验
+- **数据内嵌在文档内容中**：图表以 JSON 格式内嵌在文档内容里，随文档一起存储，复制、备份都很方便
+
+## Markmap 思维导图
+
+### 使用方式
+
+#### 斜杠菜单（推荐）
+
+输入 `/` → 选 **Markmap**（或过滤 `markmap`）插入，无需先背代码块语法。
+
+#### 代码块（可选）
+
+也可手写 `markmap` 围栏，用 Markdown 标题层级描述树：
+
+````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,130 @@
+---
+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、段落、换行
+- 粗体/斜体/删除线/行内代码/超链接
+- 有序/无序列表（支持嵌套）
+- 代码块（保留语言标识）
+- 引用块、分隔线
+- 表格（含表头、合并单元格）
+
+## 编辑器功能
+
+编辑时有两条常用入口：**顶部工具栏**（点选）和 **斜杠菜单**（键盘快速插入）。多数插入项两边都能找到。
+
+### 斜杠菜单（推荐快捷入口）
+
+在编辑器**空行或段落中**输入 `/`，弹出可搜索的插入菜单；继续打关键字（如 `table`、`meta2d`）可过滤，回车或点击插入。
+
+![输入 / 打开斜杠菜单](./markdown/slash-menu.png)
+
+常见项（右侧为过滤关键字，以当前版本界面为准）：
+
+| 菜单项 | 关键字示例 | 作用 |
+|--------|------------|------|
+| Heading 3 | `h3` | 三级标题 |
+| Hr | `hr` | 水平分割线 |
+| Table | `table` | 表格 |
+| TeX | `tex` | 数学公式 |
+| File | `file` | 上传并插入附件 |
+| Insert Link | `insert-link` | 超链接 |
+| Inline Code | `insert-codeInline` | 行内代码 |
+| Code Block | `insert-codeBlock` | 代码块（语法高亮） |
+| Meta2d | `meta2d` | 流程图画布，详见 [流程图生成](./flowchart.md) |
+| Markmap | `markmap` | 思维导图，详见 [流程图生成 · Markmap](./flowchart.md#markmap-思维导图) |
+
+插入 Meta2d 后一般会自动打开画布。日常请用 `/` 插入；围栏写法仅作可选兼容，见 [流程图生成](./flowchart.md)。
+
+### 富文本工具栏
+
+编辑器顶部工具栏覆盖格式与插入（与斜杠菜单互补）：
+
+- **撤销 / 重做**
+- **文档首尾插行**：在全文最上方或最后一行之后插入空段落
+- **标题**：H1 ~ H3
+- **文本格式**：加粗、斜体、下划线、删除线、字色 / 高亮
+- **列表与引用**：无序 / 有序 / 待办、引用
+- **插入**：链接、图片、表格、代码、TeX、附件等
+- **大纲**：可一键展开 / 折叠右侧大纲面板
+
+适合鼠标点选改格式；批量插入块级内容时优先用 `/`。
+
+### 大纲面板
+
+编辑器右侧自动提取文档标题层级，生成可点击的导航大纲，方便在长文档中快速跳转。
+
+![](./markdown/outline.png)
+
+### 文档信息菜单
+
+编辑器工具栏右侧提供文档信息入口（三条线图标），点击可查看：
+
+**元信息区**
+- **创建者**：显示访客昵称，未设置昵称时显示 visitorId 前 8 位
+- **创建时间**：文档创建的本地化日期格式
+- **大小**：文件体积（KB/MB 自动适配）
+- **上次编辑**：最后修改的本地化时间
+
+**操作区**
+- **收藏/取消收藏**：一键切换当前文档的收藏状态
+- **修改文章权限**：后续版本开放完整的权限修改对话框
+
+> 💡 点击菜单外部区域可自动关闭下拉菜单。收藏按钮 hover 时有缩放动画效果。
+
+### 流程图
+
+支持 **Meta2d** 流程图。优先在编辑器输入 `/`，选 **Meta2d** 插入并打开画布；不必手写围栏语法。
+
+详见 [流程图生成](./flowchart.md)。
+
+## 设计取舍
+
+- **选择 Lexical 而非 Prosemirror/Slate**：Lexical 对 React 生态更友好，插件系统清晰，且 `@lobehub/editor` 提供了开箱即用的工具栏和斜杠菜单。只需在lobehub项目基础上进行额外开发，避免重复造轮子
+- **JSON 存储**：保留完整的富文本结构，重新打开时精确还原编辑状态。代价是数据不能直接用文本编辑器阅读——未来会提供 Markdown 导出
+

package/agent-skills/usage-merge-conflicts/SKILL.md

@@ -0,0 +1,42 @@
+---
+id: usage-merge-conflicts
+name: "版本冲突与合并"
+description: "当发布时服务端 head 已前进（例如他端编辑、或本机自动发布后又改稿），`PUT` 可能返回 **409 版本冲突**。mdocs 会引导你进入 **合并** 界面，而不是直接覆盖远端。"
+keywords: []
+source: usage/merge-conflicts.md
+---
+
+# 版本冲突与合并
+
+当发布时服务端 head 已前进（例如他端编辑、或本机自动发布后又改稿），`PUT` 可能返回 **409 版本冲突**。mdocs 会引导你进入 **合并** 界面，而不是直接覆盖远端。
+
+## 三栏分别是什么
+
+| 位置 | 含义 |
+|------|------|
+| **左（本地）** | 发生冲突时，你本地草稿的正文快照（冻结，不是已提交的 commit 节点） |
+| **右（远端）** | 打开合并时，服务器上当前这篇的正文 |
+| **中（结果）** | 基于共同祖先做的行级对比；每个差异块需点选「采用本地 / 远端 / 保留双方」等，全部处理完才能发布 |
+
+共同祖先正文由服务端根据提交图计算（`merge-context` API），用于判断「相对祖先，哪边改了什么」。
+
+## 与草稿、发布的关系
+
+- 平时编辑：正文在 **IndexedDB 草稿**；元信息（权限、路径等）在内存中的 **activeDocMeta**（来自 GET）。
+- **发布成功**（手动或自动）：删除本地草稿 → 再拉取服务器最新内容 → 编辑器与 meta 对齐，避免「自己跟自己冲突」的误报。
+- **有未发布草稿时**：不会用后台轮询去提示「落后」，以免和本地副本语义打架；以本地草稿为准，通过 **发布 / 合并** 与服务器对齐。
+
+## 自动发布与冲突
+
+开启「自动同步至云端」后：
+
+- 每 **10 秒** 扫描一次本地草稿；
+- 某篇草稿 **超过 30 秒** 没有新的自动保存，才会尝试自动发布。
+
+若自动发布已成功而本地仍显示冲突，多为旧版本行为；请升级到最新版并重新发布一次。
+
+## 相关阅读
+
+- [草稿与同步](./drafts.md)
+- [设置](./settings.md) — 开启自动同步、管理未发布草稿
+

package/agent-skills/usage-my-documents/SKILL.md

@@ -0,0 +1,108 @@
+---
+id: usage-my-documents
+name: "我的文章"
+description: "「我的文章」功能聚合展示你创建的所有文档，集中管理跨域内容，并提供快捷的文档操作入口。"
+keywords: []
+source: usage/my-documents.md
+---
+
+# 我的文章
+
+## 功能概述
+
+「我的文章」功能聚合展示你创建的所有文档，集中管理跨域内容，并提供快捷的文档操作入口。
+
+## 查看我的文章
+
+### 入口：设置页面
+
+1. 点击左侧边栏**底部的访客信息区**（头像 + 昵称）进入 [设置页面](./settings.md)
+2. 在左侧导航中点击 **我的文章**
+
+![设置 → 我的文章](./my-documents/settings-list.png)
+
+列表以表格形式展示：
+
+| 列名 | 说明 |
+|-----|------|
+| 标题 | 文档显示名称 |
+| 域 | 文档所在的域 |
+| 更新时间 | 文档最后编辑日期 |
+| 创建时间 | 文档创建日期 |
+| 邀请成员 | 快捷管理文档邀请（仅自己创建的文档可见） |
+| 打开 | 跳转打开文档 |
+
+### 搜索筛选
+
+在列表顶部搜索框输入关键词，可按以下维度筛选：
+
+- 文档标题/文件名
+- 域名
+
+搜索支持中英文，无需区分大小写。
+
+---
+
+## 文档邀请管理
+
+### 邀请成员
+
+在「我的文章」列表中，点击任意文档右侧的 **邀请成员** 按钮：
+
+1. 在弹出的访客选择器中，左侧勾选要邀请的成员
+2. 在右侧已选列表中，为每个成员设置权限：
+   - **只读**：只能查看文档内容，不能编辑
+   - **可编辑**：可以查看和编辑文档内容
+3. 点击右下角 **确认** 完成邀请
+
+### 修改或移除邀请
+
+再次点击同一文档的「邀请成员」按钮：
+
+- **修改权限**：在右侧已选列表中重新选择权限
+- **移除邀请**：点击成员右侧的 ✕ 按钮取消勾选，确认后即移除邀请
+
+### 权限生效范围
+
+文档邀请是**文档级别**的权限叠加：
+
+- 即使访客不是域成员，只要被邀请即可访问该文档
+- 邀请权限独立于域权限，两者同时满足时取较高权限
+- 文档所有者始终拥有完全权限，不受邀请机制影响
+
+---
+
+## 使用场景
+
+### 场景 1：快速找到自己创建的文档
+
+当你在多个域中都有创建的文档时，不需要逐个域切换查找。直接打开「我的文章」即可看到所有内容。
+
+### 场景 2：批量管理文档邀请
+
+需要给多篇文档配置相同的访客名单时，可以在「我的文章」中逐篇操作，无需逐个打开文档。
+
+### 场景 3：追溯文档历史
+
+通过「创建时间」和「更新时间」两列，可以快速了解自己的编辑历史和最近活跃的文档。
+
+---
+
+## 常见问题
+
+### 为什么有些文档不显示「邀请成员」按钮？
+
+只有**你作为创建者**的文档才会显示该按钮。被你邀请编辑的文档、你有域权限编辑的文档等都不显示此按钮。
+
+### 被邀请的成员能看到这篇文档在哪里吗？
+
+可以。被邀请者的「我的收藏」和「最近文档」中会出现这篇文档，他们也可以通过搜索找到。
+
+### 如何查看谁被邀请了？
+
+点击「邀请成员」按钮，右侧已选列表即为当前被邀请的成员及其权限。
+
+### 邀请后可以取消吗？
+
+可以。再次打开邀请弹窗，点击成员右侧的 ✕ 取消勾选，确认后该成员即失去对该文档的访问权限。
+

package/agent-skills/usage-onboarding-ai/SKILL.md

@@ -0,0 +1,65 @@
+---
+id: usage-onboarding-ai
+name: "上手助手（AI）"
+description: "mdocs 内置了一个**产品上手向导**，只解答「怎么用 mdocs」（域、草稿、发布、权限等），**不会**帮你写正文或改文档。"
+keywords: []
+source: usage/onboarding-ai.md
+---
+
+# 上手助手（AI）
+
+mdocs 内置了一个**产品上手向导**，只解答「怎么用 mdocs」（域、草稿、发布、权限等），**不会**帮你写正文或改文档。
+
+若你要用 Cursor / Claude 等**外部 Agent** 读写知识库、落开发契约，见 [Agent 开发闭环](./agent-dev-loop.md)。
+
+## 入口
+
+左下角有圆形 **上手助手** 悬浮按钮（不占用正文区）。点击后打开浮层 **「mdocs 智能助手」**，主编辑区仍保持打开，可边问边写。可**按住拖动**入口到任意位置（本地记住）；挪过之后会出现「重置位置」。
+
+![上手助手入口与聊天浮层](./onboarding-ai/entry.png)
+
+浮层内：
+
+- 顶部：**+** 新建会话、历史列表、关闭
+- 中间：对话与指引内容（可含步骤、表格等）
+- 底部输入框：占位「把你的问题告诉我…」
+- 页脚提示：内容由 AI 生成，仅供参考
+
+## 开始使用前：配置模型
+
+1. 打开 **设置 → AI**（侧栏底部访客信息进入设置）
+2. 选择模型：`deepseek-v4-flash` 或 `deepseek-v4-pro`
+3. 填写你的 DeepSeek API Key 并保存
+
+![设置 → AI：上手助手模型配置](./onboarding-ai/ai-settings.png)
+
+未配置 Key 时，入口可用但无法发送消息，浮层会提示去设置页配置。
+
+每人一份配置，仅本人可用；Key 在服务端按访客隔离存储，不会出现在别的访客界面上。配置页可查看配置名称、模型、脱敏后的 Key 与配置 ID；需要改时可点 **编辑**。
+
+## 怎么问
+
+可以直接问，例如：
+
+- 如何发布文档？
+- 草稿是什么？
+- 如何创建域？
+- 权限怎么设置？
+
+助手会按需阅读 [mdocs 用户手册](https://xuhuafeifei.github.io/mdocs-site/) 相关章节再回答，并在回复里展示「已阅读 N 个页面」与手册链接。答完后通常会附带一两个可继续追问的示例。
+
+## 会话
+
+- 同一访客的对话会保存在数据目录 `tenant/<访客ID>/agent/session/` 下，刷新或重开浮层仍可续聊。
+- 浮层标题栏 **「+」**：新建空会话并切换过去。
+- **历史图标**：按最近更新列出会话；点击即可切换并回放该会话。
+- 会话标题取自**第一条用户消息**（过长会截断），不是模型摘要。
+- 删除、重命名、按天数自动清理尚未提供。
+
+## 明确不会做
+
+- 代写、润色、按选区改文档
+- 替你点击发布或改权限（只会告诉你怎么操作）
+
+若你要求写作，助手会拒绝并引导你在编辑器里自行操作。
+

package/agent-skills/usage-recovery-code/SKILL.md

@@ -0,0 +1,87 @@
+---
+id: usage-recovery-code
+name: "恢复码与身份找回"
+description: "> **现状**：跨设备找回身份，优先用 **用户名 + 密码**。恢复码是早期「纯 Cookie 身份」时代的自助方案，现仍可用，但属于兼容能力，新用户不必依赖它。"
+keywords: []
+source: usage/recovery-code.md
+---
+
+# 恢复码与身份找回
+
+> **现状**：跨设备找回身份，优先用 **用户名 + 密码**。恢复码是早期「纯 Cookie 身份」时代的自助方案，现仍可用，但属于兼容能力，新用户不必依赖它。
+
+## 为什么会有恢复码
+
+mdocs 初期刻意不做传统登录系统：不想要注册邮箱、账号密码那一套，希望打开就能写。
+
+底层做法是：浏览器里通过 **HttpOnly Cookie** 下发一串随机高熵令牌，服务端只存其哈希，用这份 Cookie 标识「你是谁」。没有单独的账号表登录流程。
+
+代价也很直接——**Cookie / 本机身份数据一旦丢了**（清站点数据、换浏览器、换设备），浏览器再也带不上原来的令牌，系统就认不出你还是以前那个人，文档所有权也接不上。
+
+恢复码就是为这个问题准备的：**一份由用户自己保存的一次性凭证**，在 Cookie 丢失后，仍能凭码换回同一访客身份和新的 Cookie。
+
+## 后来发生了什么
+
+后续迭代引入了 **登录密码**（访客名 + 密码，可多设备会话）：
+
+- 跨浏览器 / 跨设备：用密码登录即可，不必再找恢复码
+- 注册时可设密码；设置页可管理「登录密码」
+- 登录弹窗默认是「用户名 + 密码」；恢复码仍作为次要入口保留
+
+因此恢复码的核心场景被密码覆盖，**功能逐渐被边缘化**，保留是为了兼容早期只靠 Cookie、已发过恢复码的用户。
+
+| 方式 | 适用 |
+|------|------|
+| **用户名 + 密码（推荐）** | 换设备、清 Cookie、日常跨端 |
+| 恢复码 | 从未设密码、或只有早期恢复码可用的情况 |
+| 管理员 `visitor migrate` | 以上都不可用时的运维兜底 |
+
+## 机制摘要（仍可用时）
+
+格式形如：
+
+```
+ABCD-EFGH-IJKL-MNOP
+```
+
+- 注册成功时可能弹出展示（**只此一次**）；也可在设置页「通用 → 恢复码」重新生成（旧码立即失效）
+- 服务端只存 SHA-256 哈希，不能再把明文码「查出来」给你看
+- 在登录弹窗切到「恢复码」，输入后换发新的身份 Cookie；**验证成功后该码作废**（一次性）
+
+## 怎么用（兼容流程）
+
+### 生成 / 再生成
+
+1. 打开 **设置 → 通用 → 恢复码**
+2. 点击生成，**立刻复制保存**
+3. 再生成会使旧码失效
+
+### 用恢复码找回
+
+1. 无有效 Cookie 时打开站点，进入注册 / 登录弹窗
+2. 切到登录 → **恢复码**
+3. 输入保存的码 → 找回身份
+
+## 常见问题
+
+### 还需要保存恢复码吗？
+
+若已设置登录密码，**日常以密码为准**即可。恢复码可选：仅当你希望多一条不依赖密码的兜底时再保存。
+
+### 恢复码丢了怎么办？
+
+- 仍能进当前浏览器会话：去设置页改/设密码，或再生成恢复码
+- 已进不去：有密码就用密码登录；都没有则联系管理员做 `visitor migrate`
+
+### 恢复码和 Cookie 令牌有什么区别？
+
+| | Cookie 身份令牌 | 恢复码 |
+|--|-----------------|--------|
+| 角色 | 日常请求鉴权（浏览器自动带） | Cookie 丢了之后的自助换发 |
+| 存放 | HttpOnly Cookie | 用户自己抄走 |
+| 推荐替代 | — | **登录密码**（跨设备主路径） |
+
+### 和「无账户」设计还一致吗？
+
+早期「无账户」指的是不做邮箱注册那套，用 Cookie 访客身份。现在的「访客名 + 可选密码」仍是轻量访客模型，不是完整的企业账号体系；密码解决的是 **同一访客跨端续上身份**，并不否定当初降低门槛的目标。身份模型细节见 [无账户身份识别](../core-concepts/no-account.md)。
+