@fgbg/mdocs 0.8.10 → 0.8.12

package/agent-skills/changelog/SKILL.md

@@ -1,13 +1,25 @@
 ---
 id: changelog
 name: "更新日志"
-description: "- **上手助手（AI）**：左下角浮动入口；设置页「AI」配置个人 DeepSeek Key；按访客落盘会话（`tenant/<id>/agent/session`），多轮续聊；回答引用手册页面链接；思考中三点动画；跟随滚动仅在贴底时生效 - **手册**：新增 [上手助手（AI）](./usage/onboarding-ai.md)"
+description: "- **文档移动**：侧栏可拖拽 Markdown 文档到文件夹 / 同目录文章旁 / 域根；仅创建者后端成功；`POST /api/documents/:id/move` - **上手助手入口**：悬浮按钮可按住拖动定位，位置写入本地；支持重置；面板随入口侧移 - **空文档白屏**：AI/空 markdown 创建的 Lexical `children: []` 会在打开时补空段落，避免编辑器"
 keywords: []
 source: changelog.md
 ---
 
 # 更新日志
 
+## v0.8.12
+
+- **文档移动**：侧栏可拖拽 Markdown 文档到文件夹 / 同目录文章旁 / 域根；仅创建者后端成功；`POST /api/documents/:id/move`
+- **上手助手入口**：悬浮按钮可按住拖动定位，位置写入本地；支持重置；面板随入口侧移
+- **空文档白屏**：AI/空 markdown 创建的 Lexical `children: []` 会在打开时补空段落，避免编辑器整页崩溃
+- **Agent**：建文/建文件夹/移动后刷新侧栏树；新增 `move_document` 工具
+
+## v0.8.11
+
+- **上手助手会话**：浮层支持「+」新建会话、历史列表切换并回放；标题取自首条用户消息
+- **手册**：[上手助手（AI）](./usage/onboarding-ai.md) 同步会话管理说明
+
 ## v0.8.10
 
 - **上手助手（AI）**：左下角浮动入口；设置页「AI」配置个人 DeepSeek Key；按访客落盘会话（`tenant/<id>/agent/session`），多轮续聊；回答引用手册页面链接；思考中三点动画；跟随滚动仅在贴底时生效

package/agent-skills/core-concepts-no-account/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: core-concepts-no-account
 name: "无账户身份识别"
-description: "不做用户系统，不设注册流程。每个访问者通过浏览器获得一个身份令牌，以此识别身份。目标是零上手成本——打开就能用。"
+description: "早期不做传统用户系统（邮箱注册 / 账号密码那一套），每个访问者通过浏览器获得身份令牌即可开写。目标是零上手成本——打开就能用。"
 keywords: []
 source: core-concepts/no-account.md
 ---
@@ -10,16 +10,18 @@ source: core-concepts/no-account.md
 
 ## 设计意图
 
-不做用户系统，不设注册流程。每个访问者通过浏览器获得一个身份令牌，以此识别身份。目标是零上手成本——打开就能用。
+早期不做传统用户系统（邮箱注册 / 账号密码那一套），每个访问者通过浏览器获得身份令牌即可开写。目标是零上手成本——打开就能用。
+
+后来为解决「换设备 / 清 Cookie 认不出人」，在**仍是访客模型**的前提下，增加了可选的登录密码；恢复码则是更早的自助找回手段，现已边缘化。详见 [恢复码与身份找回](../usage/recovery-code.md)。
 
 ## 身份模型
 
 ```
-访客注册
+访客注册（输入昵称，可选设密码）
    │
    ├─ 服务器生成 UUID（visitor_id）
    ├─ 生成高熵令牌（visitor_token，32 字节随机数 → base64url）
-   ├─ 服务器只存储 SHA-256(令牌)
+   ├─ 服务器只存储 SHA-256(令牌)（以及可选的密码哈希）
    └─ 通过 HttpOnly Cookie 将原始令牌下发给浏览器
        
 后续请求
@@ -27,23 +29,31 @@ source: core-concepts/no-account.md
        └─ 服务器从 Cookie 读取令牌，验证 SHA-256 匹配 → 识别访客
 ```
 
-前端**不存储任何认证令牌**，所有认证凭据由 HttpOnly Cookie 管理，XSS 无法窃取。
+前端**不存储任何认证令牌**，日常鉴权凭据由 HttpOnly Cookie 管理，XSS 无法直接读到令牌。
 
 ### Cookie 有效期
 
-身份 Cookie 默认有效期为 **10 年**，实践中等同于"永久"登录。只要不主动清除浏览器 Cookie 数据，登录状态会一直保留。
+身份 Cookie 默认有效期为 **10 年**，实践中等同于「长期保持登录」。只要不主动清除浏览器站点数据，同一浏览器上会一直认得你。
 
-> 💡 即使服务端重启或重新部署，已有的登录状态依然有效。
+> 💡 即使服务端重启或重新部署，已有 Cookie 在未过期前依然有效。
 
 ## 为什么这样做
 
-- **无密码，无泄露风险**：服务器从不存储原始令牌，数据库被拖也无法冒充访客
-- **无需邮箱**：不要求用户提供任何个人信息
-- **浏览器即身份**：换设备 = 新访客（但提供了访客迁移机制）
+- **低门槛**：不必先走邮箱验证；起个昵称就能写
+- **令牌不落前端脚本可读存储**：日常身份靠 HttpOnly Cookie
+- **跨端续身份（后来补上）**：设密码后可用「用户名 + 密码」在其他设备登录；未设密码则基本绑在当前浏览器
+
+## 跨设备 / Cookie 丢失时
+
+推荐顺序：
 
-## 访客迁移
+1. **用户名 + 密码登录**（设置页可管理登录密码）
+2. **恢复码**（早期方案，登录弹窗次要入口；见 [恢复码](../usage/recovery-code.md)）
+3. 管理员 **访客迁移**（运维兜底）
 
-如果浏览器缓存被清除，用户会获得一个新访客 ID。服务部署者可以通过 CLI 命令, 登录部署服务器将旧身份合并到新身份：
+### 访客迁移（管理员）
+
+若用户既无密码又无可用恢复码，部署方可在服务器上将旧身份合并到新身份：
 
 ```
 # 推荐：按访客名称迁移（更简单，名称可在侧边栏看到）
@@ -65,21 +75,10 @@ pnpm mdocs visitor list           # 默认只看启用的访客
 pnpm mdocs visitor list --all     # 看全部（含已禁用的）
 ```
 
-## 自助恢复
-
-除了管理员执行的访客迁移，用户也可以通过**恢复码**自助找回身份：
-
-1. 注册时保存系统生成的恢复码（格式如 `ABCD-EFGH-IJKL-MNOP`）
-2. Cookie 丢失后，在注册页点击「已有恢复码？点击找回」
-3. 输入恢复码，系统验证后自动下发新的身份 Cookie
-
-恢复码是一次性的，使用后立即失效。可以在设置页随时生成新的恢复码。
-
-详见[恢复码与身份找回](../usage/recovery-code.md)。
-
 ## 设计取舍
 
-- **放弃「用户」概念**换来极低的准入门槛，代价是没有密码找回——但提供了**恢复码**自助找回机制和**访客迁移**管理员工具，满足小团队绝大多数场景
-- **HttpOnly Cookie 认证**：前端不存储任何令牌，XSS 无法窃取，服务端重启不丢登录状态
+- **放弃重型「用户体系」**换低准入；跨端能力用「可选密码」补齐，而不是一上来就上完整账号平台
+- **HttpOnly Cookie 日常鉴权**：服务端重启不轻易丢当前浏览器会话
 - **可以匿名浏览**：不注册也能看到公开域的公开文档
+- **恢复码**：服务早期 Cookie-only 身份的自助找回；密码普及后降为兼容能力
 

package/agent-skills/index/SKILL.md

@@ -15,6 +15,12 @@ source: index.md
 - [安装与启动](./getting-started/installation.md)
 - [第一个文档](./getting-started/first-kb.md)
 
+## AI 与 Agent
+
+- [上手助手（AI）](./usage/onboarding-ai.md)——产品向导，答疑不代写
+- [Agent 开发闭环](./usage/agent-dev-loop.md)——CLI + Skills 接入 Cursor / Claude
+- [CLI Token](./usage/cli-token.md)——命令行与 Agent 身份令牌
+
 ## 核心设计
 
 - [域隔离](./core-concepts/domain.md)——团队与个人的逻辑边界
@@ -24,7 +30,6 @@ source: index.md
 ## 使用指南
 
 - [设置页面概览](./usage/settings.md)——集中配置中心
-- [上手助手（AI）](./usage/onboarding-ai.md)——产品向导，答疑不代写
 - [编辑体验](./usage/markdown.md)——富文本编辑，Markdown 存储
 - [流程图生成](./usage/flowchart.md)——拖拽绘制，嵌入文档
 - [草稿与同步](./usage/drafts.md)——本地优先，按需发布

package/agent-skills/index.json

@@ -2,7 +2,7 @@
   {
     "id": "changelog",
     "name": "更新日志",
-    "description": "- **上手助手（AI）**：左下角浮动入口；设置页「AI」配置个人 DeepSeek Key；按访客落盘会话（`tenant/<id>/agent/session`），多轮续聊；回答引用手册页面链接；思考中三点动画；跟随滚动仅在贴底时生效 - **手册**：新增 [上手助手（AI）](./usage/onboarding-ai.md)",
+    "description": "- **文档移动**：侧栏可拖拽 Markdown 文档到文件夹 / 同目录文章旁 / 域根；仅创建者后端成功；`POST /api/documents/:id/move` - **上手助手入口**：悬浮按钮可按住拖动定位，位置写入本地；支持重置；面板随入口侧移 - **空文档白屏**：AI/空 markdown 创建的 Lexical `children: []` 会在打开时补空段落，避免编辑器",
     "keywords": [],
     "source": "changelog.md"
   },
@@ -30,7 +30,7 @@
   {
     "id": "core-concepts-no-account",
     "name": "无账户身份识别",
-    "description": "不做用户系统，不设注册流程。每个访问者通过浏览器获得一个身份令牌，以此识别身份。目标是零上手成本——打开就能用。",
+    "description": "早期不做传统用户系统（邮箱注册 / 账号密码那一套），每个访问者通过浏览器获得身份令牌即可开写。目标是零上手成本——打开就能用。",
     "keywords": [],
     "source": "core-concepts/no-account.md"
   },
@@ -83,6 +83,13 @@
     "keywords": [],
     "source": "index.md"
   },
+  {
+    "id": "usage-agent-dev-loop",
+    "name": "Agent 开发闭环",
+    "description": "mdocs 不只给人在浏览器里写文档，也让 **外部 AI Agent**（Cursor、Claude Code、Codex 等）把知识库嵌进日常工作。",
+    "keywords": [],
+    "source": "usage/agent-dev-loop.md"
+  },
   {
     "id": "usage-bookmarks",
     "name": "收藏功能",
@@ -93,7 +100,7 @@
   {
     "id": "usage-cli-token",
     "name": "CLI Token",
-    "description": "CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。",
+    "description": "CLI Token 是给命令行工具和 AI Agent（如 Claude Code、Cursor）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。",
     "keywords": [],
     "source": "usage/cli-token.md"
   },
@@ -156,7 +163,7 @@
   {
     "id": "usage-recovery-code",
     "name": "恢复码与身份找回",
-    "description": "恢复码是一串由字母和数字组成的特殊代码，格式如：",
+    "description": "> **现状**：跨设备找回身份，优先用 **用户名 + 密码**。恢复码是早期「纯 Cookie 身份」时代的自助方案，现仍可用，但属于兼容能力，新用户不必依赖它。",
     "keywords": [],
     "source": "usage/recovery-code.md"
   },
@@ -170,7 +177,7 @@
   {
     "id": "usage-settings",
     "name": "设置页面",
-    "description": "设置页面是 mdocs 的集中配置中心，提供访客身份、域管理、内容管理等各种系统级功能。",
+    "description": "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。",
     "keywords": [],
     "source": "usage/settings.md"
   },

package/agent-skills/usage-agent-dev-loop/SKILL.md

@@ -0,0 +1,179 @@
+---
+id: usage-agent-dev-loop
+name: "Agent 开发闭环"
+description: "mdocs 不只给人在浏览器里写文档，也让 **外部 AI Agent**（Cursor、Claude Code、Codex 等）把知识库嵌进日常工作。"
+keywords: []
+source: usage/agent-dev-loop.md
+---
+
+# Agent 开发闭环
+
+mdocs 不只给人在浏览器里写文档，也让 **外部 AI Agent**（Cursor、Claude Code、Codex 等）把知识库嵌进日常工作。
+
+这和产品内的 [上手助手（AI）](./onboarding-ai.md) 是两条路：
+
+| | 上手助手 | Agent 开发闭环 |
+|--|----------|----------------|
+| 在哪 | mdocs Web 浮层 | 你的 IDE / Agent 终端 |
+| 干什么 | 答「怎么用 mdocs」 | 读知识库、按契约开发、按需写回文档 |
+| 会不会改正文 | **不会**（不代写） | 会按你的指令经 CLI 读写文档 |
+
+---
+
+## 一次性准备
+
+1. 在 mdocs **设置 → 通用** 创建 [CLI Token](./cli-token.md)，并：
+
+```bash
+export MDOCS_TOKEN="你的 token"
+# 非本机时再设，例如：
+# export MDOCS_SERVER="http://127.0.0.1:4000"
+```
+
+2. 克隆 CLI + Skills，并分发到你用的 Agent：
+
+```bash
+git clone https://github.com/xuhuafeifei/mdocs-cli.git ~/.mdocs-cli
+cd ~/.mdocs-cli && ./distribute-skill.sh cursor   # 或 claude / 多个 agent
+```
+
+会把 **`mdocs-cli`**、**`mdocs-dev`**、**`diagram`** 装到对应 Agent 的 skills 目录。之后在对话里用 `/mdocs-cli`、`/mdocs-dev` 等即可唤起。
+
+更细的命令与环境变量见 [CLI Token · CLI 客户端](./cli-token.md#cli-客户端)。
+
+---
+
+## 最基础：`/mdocs-cli` + 文章 URL
+
+**你不必先背命令。** 只要：
+
+1. Agent 已加载 **mdocs-cli** skill（例如输入 `/mdocs-cli`，或确保 skill 已分发且会话会加载它）
+2. 环境里有可用的 `MDOCS_TOKEN`（以及必要时的 `MDOCS_SERVER`）
+3. 把 **mdocs 文章的浏览器地址**丢给 Agent，用自然语言说要做什么
+
+示例（与真实使用一致）：
+
+```text
+/mdocs-cli
+http://localhost:5173/#/doc/7d78023e-9155-4551-84dc-2dd4e2e44841
+看下这个文章对应目录的所有文章内容
+```
+
+Agent 会自行：
+
+1. 从 URL 里解析 **文档 ID**（`#/doc/<uuid>`）
+2. 按需准备 `~/.mdocs-cli`（clone / 更新；失败时可用本地已有副本继续）
+3. 调用对应子命令（如上例是 `ls <documentId>` 列同级目录）
+4. 用返回的 JSON 回答你
+
+![在 Agent 中用 /mdocs-cli + 文章 URL](./agent-dev-loop/mdocs-cli-usage.png)
+
+### 你还可以怎么说
+
+| 你想做的事 | 示例说法 |
+|------------|----------|
+| 读这篇 | 「打开这篇 URL，总结要点」 |
+| 看同级目录 | 「这个文章对应目录下有哪些文件」（上图） |
+| 搜知识库 | 「在 mdocs 里搜『草稿』相关」 |
+| 改 / 新建 | 「根据刚才结论，更新这篇」或「在同级建一篇笔记」（需你明确授权写回） |
+
+底层命令仍是 `search` / `get` / `ls` / `list` / `create` / `update` 等；对日常使用，**URL + 自然语言** 就够了。
+
+---
+
+## `/mdocs-dev`：开发流程（详细）
+
+知识库读写用 **mdocs-cli**；**在业务仓库里把需求想清楚、再写代码**，用 **`/mdocs-dev`**。
+
+### 什么时候输入 `/mdocs-dev`
+
+在 Cursor / Claude 等对话里输入：
+
+```text
+/mdocs-dev
+```
+
+或附带一句话说明意图，例如：
+
+```text
+/mdocs-dev
+我想给设置页加「导出 Markdown」，你先按契约走
+```
+
+Agent 会按 **mdocs-dev** skill 工作：在项目根维护 **`.mdocs-docs/` 开发契约**，**先对齐设计、经你同意后再改业务代码**。
+
+### 契约落在哪
+
+```
+<项目根>/.mdocs-docs/
+├── README.md              # 总索引
+├── map/                   # 机器坐标：关键词 → 文件/符号（不贴大段代码）
+├── diagrams/              # Mermaid 图（用 diagram skill）
+├── decisions/             # ADR：为什么这样设计
+├── bug-fixes/             # 事后修复记录
+└── requirements/<需求名>/
+    ├── 需求分析.md        # 给人：范围、验收
+    ├── 设计契约.md        # 给人审；须「已同意」才能写代码
+    └── 代码索引.md        # 给机器：本需求入口定位
+```
+
+### 标准步骤（Agent 应遵守）
+
+```
+1. 判场景：新需求 / 改老需求 / 整理老业务 / 记 bug 修复
+2. 读 .mdocs-docs/README.md、map/、已有需求夹（防重复建 xxx-v2）
+3. 写或更新「需求分析」「设计契约」
+4. 把设计契约给你看 → 等你明确说「同意」
+5. 未同意：只改契约文档，禁止动业务代码
+6. 同意后：写代码，并更新「代码索引」/ map（入口变了才改）
+7. 你要求「推 mdocs / 落库」时，再用 mdocs-cli 把定稿推到知识库
+```
+
+### 四种场景怎么走
+
+| 场景 | Agent 默认做什么 |
+|------|------------------|
+| **新需求** | 新建 `requirements/<短名>/`，先分析再设计 |
+| **改老需求** | **更新原文件夹**，禁止另开 `xxx-v2` |
+| **整理老业务** | 只增厚 `map/`，不写长篇用户故事 |
+| **记 bug 修复** | 写 `bug-fixes/<短标题>-日期.md`（事后记录，不走设计门控） |
+
+意图不清时，Agent **只应问一句**：新需求、改老需求、整理老业务，还是记 bug？
+
+### 和 `/mdocs-cli` 怎么配合
+
+| 阶段 | 用哪个 |
+|------|--------|
+| 查团队知识库里已有设计 / 笔记 | `/mdocs-cli` + URL 或搜索 |
+| 在本仓库落需求与设计、等人审 | `/mdocs-dev` |
+| 画架构 / 时序给人看 | `diagram` skill（图进 `.mdocs-docs/diagrams/`） |
+| 定稿后写进 mdocs | 你明确要求后，再用 **mdocs-cli** `create` / `update` |
+
+**默认不推库**：契约先只存在 Git 仓库里；避免 Agent 未经允许改线上文档。
+
+### 你这边的检查点
+
+- 设计契约状态是否写成 **已同意**（含日期）再让 Agent 动代码  
+- 结论是否能指到 `map` / 路径 / decisions，而不是空口承诺  
+- 改老需求是否仍在**同一个** `requirements/...` 目录  
+
+---
+
+## Skills 一览
+
+| Skill | 作用 |
+|-------|------|
+| **mdocs-cli** | HTTP CLI：搜 / 读 / 列 / 建 / 改文档与目录 |
+| **mdocs-dev** | `.mdocs-docs` 契约 + 设计门控 |
+| **diagram** | Mermaid 图落盘并索引 |
+
+仓库：[github.com/xuhuafeifei/mdocs-cli](https://github.com/xuhuafeifei/mdocs-cli)
+
+---
+
+## 和上手助手的知识关系
+
+- **本站文档**是给人读的手册真源。
+- mdocs 上手 Agent 构建时会把本站手册打成包内 Skills。
+- 因此：改好本站使用说明，既服务人类读者，也服务产品内 AI。
+

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

@@ -30,18 +30,22 @@ source: usage/bookmarks.md
 有两种方式查看收藏列表：
 
 1. **左侧边栏快捷入口**：点击左侧边栏底部访客信息右侧的星标按钮（在退出按钮左侧），弹出「我的收藏」列表
-2. **[设置页面](./settings.md)**：进入「设置」→「我的收藏」，可以看到完整的收藏表格，支持搜索筛选
+2. **[设置页面](./settings.md)**：侧栏底部访客信息进入设置 → **我的收藏**，可看完整表格并搜索
+
+![设置 → 我的收藏](./bookmarks/settings-list.png)
+
+表格列包括：标题、域、作者、收藏时间；行内可 **取消收藏**。
 
 收藏列表的显示规则：
-- 正常文档：黑色文字显示，点击可直接跳转打开
-- 已删除文档：灰色文字 + 红色「已删除」标签，不可点击
+- 正常文档：可点击打开
+- 已删除文档：灰色文字 + 「已删除」标签，不可打开
 
 ### 取消收藏
 
 有两种方式取消收藏：
 
 1. **在文档内**：打开文档，通过右上角 ⋮ 菜单点击「取消收藏」
-2. **在收藏列表**：点击任意收藏项右侧的 **✕ 按钮**，即时取消收藏
+2. **在收藏列表 / 设置页**：点击该项右侧的 **取消收藏**
 
 ---
 

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

@@ -1,14 +1,18 @@
 ---
 id: usage-cli-token
 name: "CLI Token"
-description: "CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。"
+description: "CLI Token 是给命令行工具和 AI Agent（如 Claude Code、Cursor）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。"
 keywords: []
 source: usage/cli-token.md
 ---
 
 # CLI Token
 
-CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。
+CLI Token 是给命令行工具和 AI Agent（如 Claude Code、Cursor）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。
+
+整体怎么把 CLI / Skills 嵌进开发流程（含 **丢文章 URL**、**`/mdocs-dev`**），见 [Agent 开发闭环](./agent-dev-loop.md)。
+
+最基础的 Agent 用法：加载 **mdocs-cli** skill 后，直接把 mdocs 文章链接发给 Agent，用自然语言说明要读目录、读正文或搜索即可，不必先手写 CLI。
 
 ## 适用场景
 
@@ -18,7 +22,7 @@ CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份
 
 ## 创建 Token
 
-1. 打开 mdocs 的设置页，切换到「通用」Tab。
+1. 打开 mdocs 的设置页（侧栏底部访客信息），切换到「通用」。
 2. 找到 **CLI Token** 卡片，点击「创建」。
 3. 系统会生成一个新的 Token，**仅在此时展示一次**，请立即复制保存。
 

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

@@ -17,24 +17,20 @@ source: usage/domain-members.md
 
 公开域、个人域 **没有**「成员」名单能力：前者对所有人开放入口，后者只有域主一人。
 
-## UI 界面
-
-![](./domain-members/UI.png)
-
-> 域管理界面显示的域，都是用户可见的域. 公开域，团队成员的受限域，私域 （如果域中存在一篇文章邀请了别的用户，那么该域对那名用户也是可见的，哪怕是私域）
-
 ## 入口在哪里
 
-点击应用左下角，包含用户头像的栏目
+点击应用左侧边栏**底部访客信息区**进入 [设置](./settings.md)，再选：
 
-![](./domain-members/settings.png)
+| 侧栏项 | 作用 |
+|--------|------|
+| **域管理** | 新建域、按类型筛选、重命名 / 改类型 / 删除；对 **受限域** 维护成员 |
+| **域成员模板** | 维护可复用的访客名单，供成员弹窗套用 |
 
-| 侧栏项（中文界面示例） | 作用                                                   |
-| ---------------------- | ------------------------------------------------------ |
-| **域管理**             | 新建域、筛选域类型、对 **受限域** 打开「成员」维护弹窗 |
-| **域成员模板**         | 维护可复用的访客 ID 名单（名称 + 一套勾选结果）        |
+![设置 → 域管理](./domain-members/domain-manage.png)
 
-「活跃访客目录」来自服务端的访客列表接口：一般包含当前未停用的访客，用于左侧勾选。
+「活跃访客目录」来自服务端访客列表：一般包含当前未停用的访客，用于成员勾选。
+
+域管理列表里能看到的域，都是当前访客可见的域：公开域、你作为成员的受限域、自己的私有域；若某私有域里有文档邀请了你，该域也可能出现在列表中。
 
 ## 创建受限域与首批成员
 
@@ -82,11 +78,13 @@ source: usage/domain-members.md
 
 在 **设置 → 域成员模板**：
 
-1. **新建**：填模板显示名称，用访客选择器（与域成员相同的双栏界面）选好一组人，保存。
-2. **编辑**：在列表中选一条，改名称或人员后保存。
+![设置 → 域成员模板](./domain-members/member-template.png)
+
+1. **新建**：按步骤填写名称 → 选择成员 → 保存（例如「核心开发组」）。
+2. **编辑**：在「已保存的模板」中选一条，改名称或人员后保存。
 3. **删除**：删除前会有确认提示。
 
-![](./domain-members/template-mantain.png)
+若尚无模板，页面会提示先创建，再回到「域管理」里对受限域维护成员。
 
 模板 **不会** 自动同步到任何域；只是在 **域管理 → 成员** 弹窗里作为「一键追加勾选」的快捷方式。真正生效仍以你在成员弹窗里 **确认保存** 后的结果为准。
 

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

@@ -63,9 +63,21 @@ Lexical 编辑器（富文本）
 
 ## 发布流程
 
+### 设置里的开关
+
+打开 **设置 → 保存与发布**：
+
+![设置 → 保存与发布](./drafts/save-publish-settings.png)
+
+| 项 | 说明 |
+|----|------|
+| **自动保存（本地快照）** | 内容持续写入浏览器本地快照，避免编辑丢失（界面展示为始终可用） |
+| **自动同步至云端** | 空闲后把草稿推到服务器；网络不稳或多端冲突时可能暂停同步以保护数据 |
+| **查看未发布草稿** | 列出尚未成功发布到服务端的本地草稿，可点进对应文档继续编辑或手动发布 |
+
 ### 自动发布（可选）
 
-在 [设置](./settings.md) 中开启「自动同步至云端」后：
+在设置中开启「自动同步至云端」后：
 
 - **每 10 秒**扫描 IndexedDB；
 - 某篇草稿 **超过 30 秒** 没有新的自动保存 → 尝试发布。

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

@@ -14,17 +14,31 @@ mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像
 
 ## 插入方式
 
-在编辑器新行中输入以下内容后回车：
+### 斜杠菜单（推荐）
+
+不必手写 Markdown / 围栏语法。在编辑器中：
+
+1. 新起一行（或光标在段落里）输入 `/`
+2. 选择 **Meta2d**，或继续输入 `meta2d` 过滤后回车
+3. 插入后会打开 Meta2d 画布，拖拽绘制即可
+
+![输入 / 打开菜单并选择 Meta2d](./markdown/slash-menu.png)
+
+完整菜单项说明见 [编辑体验 · 斜杠菜单](./markdown.md#斜杠菜单推荐快捷入口)。
+
+### 其他方式（可选）
+
+仍支持在新行输入围栏后回车打开画布（适合熟悉旧习惯的用户）：
 
 ```
 ---meta2d---
 ```
 
-编辑器会自动识别并打开 Meta2d 画布编辑器。
+日常插入请优先用 `/`。
 
 ## 数据格式
 
-图表在文档中以 `---meta2d---` 围栏块的形式内嵌存储：
+图表在文档中以内嵌块保存（存储形态，**插入时不必手写**）：
 
 ```
 ---meta2d---
@@ -33,7 +47,7 @@ mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像
 ```
 
 编辑器渲染时：
-- 识别到 `---meta2d---` 块 → 调用 canvas2svg 渲染为 SVG 预览
+- 识别到该块 → 调用 canvas2svg 渲染为 SVG 预览
 - 双击块 → 打开 Meta2d 画布编辑器，可拖拽编辑
 - 保存 → 将 JSON 写回文档内容
 
@@ -54,7 +68,13 @@ mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像
 
 ### 使用方式
 
-在编辑器中创建 `markmap` 代码块：
+#### 斜杠菜单（推荐）
+
+输入 `/` → 选 **Markmap**（或过滤 `markmap`）插入，无需先背代码块语法。
+
+#### 代码块（可选）
+
+也可手写 `markmap` 围栏，用 Markdown 标题层级描述树：
 
 ````markdown
 ```markmap

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

@@ -56,19 +56,44 @@ node ~/.mdocs-cli/mdocs.mjs create \
 
 ## 编辑器功能
 
+编辑时有两条常用入口：**顶部工具栏**（点选）和 **斜杠菜单**（键盘快速插入）。多数插入项两边都能找到。
+
+### 斜杠菜单（推荐快捷入口）
+
+在编辑器**空行或段落中**输入 `/`，弹出可搜索的插入菜单；继续打关键字（如 `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）、Meta2d、Markmap
-- **代码块**：基于 CodeMirror 的代码编辑器，支持语法高亮
-- **文件附件**：上传并插入文件
+- **文本格式**：加粗、斜体、下划线、删除线、字色 / 高亮
+- **列表与引用**：无序 / 有序 / 待办、引用
+- **插入**：链接、图片、表格、代码、TeX、附件等
+- **大纲**：可一键展开 / 折叠右侧大纲面板
 
-斜杠菜单可搜索上述插入项（含 Meta2d / Markmap）。
+适合鼠标点选改格式；批量插入块级内容时优先用 `/`。
 
 ### 大纲面板
 
@@ -94,9 +119,9 @@ node ~/.mdocs-cli/mdocs.mjs create \
 
 ### 流程图
 
-支持 **Meta2d** 流程图，输入 `---meta2d---` 后回车即可打开画布编辑器，拖拽绘制流程图。
+支持 **Meta2d** 流程图。优先在编辑器输入 `/`，选 **Meta2d** 插入并打开画布；不必手写围栏语法。
 
-详见[流程图生成](./flowchart.md)。
+详见 [流程图生成](./flowchart.md)。
 
 ## 设计取舍
 

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

@@ -16,19 +16,21 @@ source: usage/my-documents.md
 
 ### 入口：设置页面
 
-1. 点击左侧边栏顶部的 **⚙ 设置** 按钮
+1. 点击左侧边栏**底部的访客信息区**（头像 + 昵称）进入 [设置页面](./settings.md)
 2. 在左侧导航中点击 **我的文章**
 
+![设置 → 我的文章](./my-documents/settings-list.png)
+
 列表以表格形式展示：
 
 | 列名 | 说明 |
 |-----|------|
-| 标题 | 文档显示名称，点击可直接打开文档 |
+| 标题 | 文档显示名称 |
 | 域 | 文档所在的域 |
 | 更新时间 | 文档最后编辑日期 |
 | 创建时间 | 文档创建日期 |
 | 邀请成员 | 快捷管理文档邀请（仅自己创建的文档可见） |
-| 打开 | 快速跳转打开文档 |
+| 打开 | 跳转打开文档 |
 
 ### 搜索筛选
 

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

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

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

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

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

@@ -1,7 +1,7 @@
 ---
 id: usage-settings
 name: "设置页面"
-description: "设置页面是 mdocs 的集中配置中心，提供访客身份、域管理、内容管理等各种系统级功能。"
+description: "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。"
 keywords: []
 source: usage/settings.md
 ---
@@ -10,85 +10,74 @@ source: usage/settings.md
 
 ## 功能概述
 
-设置页面是 mdocs 的集中配置中心，提供访客身份、域管理、内容管理等各种系统级功能。
+设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。
 
 ## 入口
 
-点击左侧边栏**顶部的 ⚙ 设置按钮**（在域名选择下拉左侧），进入设置页面。
+点击左侧边栏**底部的访客信息区**（头像 + 昵称那一行），进入设置页面。
+
+![设置入口：点击侧栏底部访客信息](./settings/setting-rukou.png)
+
+侧栏底部另有 **返回文档**，可随时回到编辑主界面。
 
 ---
 
 ## 左侧导航概览
 
-设置页面左侧分为以下功能模块：
+顺序与界面一致：
 
 | 导航项 | 功能 |
 |-------|------|
-| [通用](#通用设置) | 语言切换、自动编辑、CLI Token、恢复码 |
-| [AI](./onboarding-ai.md) | 上手助手用的 DeepSeek 模型与 API Key |
-| [我的收藏](./bookmarks.md) | 收藏的文档列表，支持搜索、取消收藏 |
-| [我的文章](./my-documents.md) | 自己创建的所有文档，支持邀请成员 |
-| [域管理](../usage/domain-members.md#域管理) | 创建、重命名、删除域，配置域权限与成员 |
-| 成员模板 | 保存常用访客名单，供受限域批量邀请复用 |
-| [保存与发布](./drafts.md) | 自动同步开关、未发布草稿列表 |
+| [通用](#通用设置) | 语言、自动编辑、CLI Token、恢复码（兼容）、登录密码 |
+| [我的收藏](./bookmarks.md) | 收藏列表、搜索、取消收藏 |
+| [我的文章](./my-documents.md) | 自己创建的文档、邀请成员、打开 |
+| [域管理](./domain-members.md) | 创建 / 筛选 / 重命名 / 改类型 / 删除域；受限域成员 |
+| [域成员模板](./domain-members.md) | 可复用的访客名单 |
+| [AI](./onboarding-ai.md) | 上手助手的 DeepSeek 配置 |
+| [保存与发布](./drafts.md) | 本地快照、自动同步、未发布草稿 |
 
 ---
 
 ## 通用设置
 
-### 语言切换
+![通用设置界面](./settings/general.png)
 
-支持中英文双语界面：
+### 语言
 
-- **中文**：完整本地化的操作提示与说明
-- **English**：英文界面适配国际团队
+「中」/「EN」即时切换界面语言，无需刷新。
 
-点击「中」/「EN」按钮即时切换，无需刷新页面。
+### 自动编辑
 
-### 自动编辑开关
+开启后，打开文档时自动进入编辑模式；关闭则默认只读，需手动点编辑。
 
-开启后，打开文档时自动进入编辑模式；关闭时默认以只读模式打开，需要手动点击编辑按钮。
-
-适合不同的使用习惯：
-- **写作为主**：建议开启，减少一次点击
-- **阅读为主**：建议关闭，避免误触编辑
+- **写作为主**：建议开启
+- **阅读为主**：建议关闭
 
 ### CLI Token
 
-用于命令行工具和自动化脚本的身份凭证。详情请参考 [CLI Token](./cli-token.md)。
+给命令行与外部 Agent 用的身份令牌，继承你的权限。可查看活跃 Token、重置。详情见 [CLI Token](./cli-token.md)。
 
-### 恢复码
+### 恢复码（兼容）
 
-用于访客身份恢复。详情请参考 [恢复码](./recovery-code.md)。
+Token / Cookie 丢失时的自助找回；引入登录密码后已边缘化。详情见 [恢复码与身份找回](./recovery-code.md)。
 
-### AI（上手助手）
+### 登录密码（推荐跨端）
 
-在设置页 **AI** Tab 配置个人 DeepSeek 模型与 API Key，供左下角上手助手调用。详情请参考 [上手助手（AI）](./onboarding-ai.md)。
+设置至少 4 位密码后，可在其他浏览器或设备用「用户名 + 密码」登录同一访客。
 
 ---
 
-## 保存与发布
-
-### 自动同步开关
+## 其他模块一览
 
-开启后，编辑停止 30 秒后自动将草稿同步到服务器。建议保持开启以获得最佳协作体验。
+各页详情见对应文档；此处仅对照设置内截图入口。
 
-详情请参考 [草稿与同步](./drafts.md)。
-
-### 未发布草稿
-
-显示当前所有存在本地草稿但尚未发布到服务器的文档。点击可直接进入对应文档继续编辑或发布。
-
----
-
-## 通用操作
-
-### 返回文档
-
-设置页面的任何位置，都可以通过以下方式回到文档视图：
-
-1. 点击左侧导航底部的 **返回文档** 按钮
-2. 点击浏览器后退按钮
+| 模块 | 文档 |
+|------|------|
+| 我的收藏 | [收藏功能](./bookmarks.md) |
+| 我的文章 | [我的文章](./my-documents.md) |
+| 域管理 / 域成员模板 | [受限域成员与名单模板](./domain-members.md) |
+| AI | [上手助手（AI）](./onboarding-ai.md) |
+| 保存与发布 | [草稿与同步](./drafts.md) |
 
 ---
 
@@ -96,23 +85,11 @@ source: usage/settings.md
 
 ### 设置会保存在哪里？
 
-大部分设置（如语言、自动编辑、自动同步）保存在浏览器 localStorage，只对当前浏览器生效。
-
-以下数据保存在服务器，与访客身份绑定：
-- 收藏列表
-- 域与成员配置
-- 成员模板
-- CLI Token
-- 恢复码
-
-### 为什么设置页面看不到某些功能？
-
-部分功能有前置条件：
-- **域管理**：需要是域的创建者才能看到重命名、删除等操作
-- **成员模板**：至少创建过一个模板后才有内容
-- **邀请成员**：只有自己创建的文档才显示该按钮
+语言、自动编辑、自动同步等偏好多在浏览器本地；与身份绑定的数据（收藏、域与成员、模板、CLI Token、密码哈希、恢复码哈希、AI 配置）在服务端。
 
-### 设置页面支持键盘操作吗？
+### 为什么看不到某些操作？
 
-设置页面的输入框和按钮均支持 Tab 切换和 Enter 确认。表格列标题支持点击排序。
+- **域管理**：重命名 / 删除等通常仅域创建者可见
+- **受限域「成员」**：仅受限域且你是创建者时才有
+- **邀请成员**：仅自己创建的文档显示
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgbg/mdocs",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "A Markdown knowledge base for small teams",
   "license": "MIT",
   "type": "module",