@fgbg/mdocs 0.8.9 → 0.8.12

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

@@ -0,0 +1,97 @@
+---
+id: usage-bookmarks
+name: "收藏功能"
+description: "收藏功能帮助你快速标记和访问重要文档。已收藏的文档会出现在「我的收藏」列表中，便于跨域快速访问。"
+keywords: []
+source: usage/bookmarks.md
+---
+
+# 收藏功能
+
+## 功能概述
+
+收藏功能帮助你快速标记和访问重要文档。已收藏的文档会出现在「我的收藏」列表中，便于跨域快速访问。
+
+## 收藏文档
+
+### 入口：文档信息菜单
+
+1. 打开任意文档
+2. 点击编辑器工具栏最右侧的 **⋮ 更多按钮**（在删除按钮右侧）
+3. 在下拉菜单中点击 **添加收藏**
+4. 菜单文字自动变为 **取消收藏**，表示该文档已被收藏
+
+再次点击即可取消收藏。
+
+## 管理收藏
+
+### 查看收藏列表
+
+有两种方式查看收藏列表：
+
+1. **左侧边栏快捷入口**：点击左侧边栏底部访客信息右侧的星标按钮（在退出按钮左侧），弹出「我的收藏」列表
+2. **[设置页面](./settings.md)**：侧栏底部访客信息进入设置 → **我的收藏**，可看完整表格并搜索
+
+![设置 → 我的收藏](./bookmarks/settings-list.png)
+
+表格列包括：标题、域、作者、收藏时间；行内可 **取消收藏**。
+
+收藏列表的显示规则：
+- 正常文档：可点击打开
+- 已删除文档：灰色文字 + 「已删除」标签，不可打开
+
+### 取消收藏
+
+有两种方式取消收藏：
+
+1. **在文档内**：打开文档，通过右上角 ⋮ 菜单点击「取消收藏」
+2. **在收藏列表 / 设置页**：点击该项右侧的 **取消收藏**
+
+---
+
+## 特殊场景处理
+
+### 已删除文档的收藏
+
+如果收藏的文档被删除，收藏项会保留在列表中并标记为 **「已删除」**。你可以：
+
+- 手动点击右侧 ✕ 取消收藏，从列表中移除该条目
+- 文档内容无法再查看
+
+这种设计避免了文档删除后收藏项"消失"导致的困惑。
+
+### 无权限文档的收藏
+
+即使你失去了某篇文档的访问权限（如被移出域成员），收藏项仍然保留。你可以手动取消收藏来清理。
+
+---
+
+## 权限说明
+
+收藏功能的权限遵循文档本身的权限规则：
+
+| 文档权限 | 能否收藏 | 能否查看内容 |
+|---------|----------|-------------|
+| 公开可读/可编辑 | ✅ 可以 | ✅ 可以 |
+| 受限域成员 | ✅ 可以 | ✅ 可以 |
+| 文档被邀请 | ✅ 可以 | ✅ 可以 |
+| 无权限但已收藏 | ➖ 保持收藏 | ❌ 无法打开 |
+
+> 收藏列表仅对你本人可见，其他访客无法看到你的收藏内容。
+
+---
+
+## 常见问题
+
+### 收藏会同步到其他设备吗？
+
+会的。收藏数据存储在服务器端，与你的访客身份绑定。在任何设备登录同一访客，都能看到相同的收藏列表。
+
+### 可以收藏多少文档？
+
+没有数量限制。但建议只收藏真正重要的文档，保持收藏列表的整洁。
+
+### 为什么有些收藏项显示灰色？
+
+表示该文档已被删除，或者你已失去访问权限。可以手动点击右侧 ✕ 按钮取消收藏来移除。
+

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

@@ -0,0 +1,132 @@
+---
+id: usage-cli-token
+name: "CLI Token"
+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、Cursor）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。
+
+整体怎么把 CLI / Skills 嵌进开发流程（含 **丢文章 URL**、**`/mdocs-dev`**），见 [Agent 开发闭环](./agent-dev-loop.md)。
+
+最基础的 Agent 用法：加载 **mdocs-cli** skill 后，直接把 mdocs 文章链接发给 Agent，用自然语言说明要读目录、读正文或搜索即可，不必先手写 CLI。
+
+## 适用场景
+
+- **命令行管理**：在服务器上通过脚本批量创建或更新文档
+- **Agent 集成**：让 AI 编程助手直接读写你的知识库
+- **CI/CD 流水线**：在自动化流程中同步文档
+
+## 创建 Token
+
+1. 打开 mdocs 的设置页（侧栏底部访客信息），切换到「通用」。
+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,102 @@
+---
+id: usage-domain-members
+name: "受限域成员与名单模板"
+description: "本文说明如何在 mdocs 里维护 **restricted（受限）域** 的成员，以及如何使用 **域成员模板** 减少重复勾选。与权限模型相关的设计背景见 [域隔离](../core-concepts/domain.md)。"
+keywords: []
+source: usage/domain-members.md
+---
+
+# 受限域成员与名单模板
+
+本文说明如何在 mdocs 里维护 **restricted（受限）域** 的成员，以及如何使用 **域成员模板** 减少重复勾选。与权限模型相关的设计背景见 [域隔离](../core-concepts/domain.md)。
+
+## 谁能用这些功能
+
+- **管理某受限域的成员**：仅限该域的 **创建者**（你在域列表里对该域拥有完整操作按钮的那个人）。
+- **创建 / 编辑 / 删除成员模板**：当前登录访客自己的模板列表；模板数据按创建者隔离，其他人看不到你的模板。
+
+公开域、个人域 **没有**「成员」名单能力：前者对所有人开放入口，后者只有域主一人。
+
+## 入口在哪里
+
+点击应用左侧边栏**底部访客信息区**进入 [设置](./settings.md)，再选：
+
+| 侧栏项 | 作用 |
+|--------|------|
+| **域管理** | 新建域、按类型筛选、重命名 / 改类型 / 删除；对 **受限域** 维护成员 |
+| **域成员模板** | 维护可复用的访客名单，供成员弹窗套用 |
+
+![设置 → 域管理](./domain-members/domain-manage.png)
+
+「活跃访客目录」来自服务端访客列表：一般包含当前未停用的访客，用于成员勾选。
+
+域管理列表里能看到的域，都是当前访客可见的域：公开域、你作为成员的受限域、自己的私有域；若某私有域里有文档邀请了你，该域也可能出现在列表中。
+
+## 创建受限域与首批成员
+
+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；需要你改模板、或等对方恢复为活跃访客后再套用 / 勾选。
+
+编辑某一模板时，选择器里 **不会** 把「当前正在编辑的这一条」放进套用下拉，避免无意义的自引用。
+
+## 维护「域成员模板」
+
+在 **设置 → 域成员模板**：
+
+![设置 → 域成员模板](./domain-members/member-template.png)
+
+1. **新建**：按步骤填写名称 → 选择成员 → 保存（例如「核心开发组」）。
+2. **编辑**：在「已保存的模板」中选一条，改名称或人员后保存。
+3. **删除**：删除前会有确认提示。
+
+若尚无模板，页面会提示先创建，再回到「域管理」里对受限域维护成员。
+
+模板 **不会** 自动同步到任何域；只是在 **域管理 → 成员** 弹窗里作为「一键追加勾选」的快捷方式。真正生效仍以你在成员弹窗里 **确认保存** 后的结果为准。
+
+## 与文档邀请的区别
+
+- **域成员**：决定谁能 **完整进入** 受限域（与创建者同级入口）、能否在该域 **新建文档** 等。
+- **文档级邀请**（`document_invites` 叠加层）：细到单篇文档。非域成员也可只被邀请到某几篇文档，此时在域侧往往是 **受限入口**，不能随意在域内开新档。详见 [文档级邀请](../core-concepts/invitation.md)。
+
+> 注意：邀请与域成员**互斥**——已是域成员的人不能被邀请。
+
+## 设计取舍
+
+- **受限域** mdocs偏向于小规模团队文档维护，在设计之初并未考虑引入组织架构的复杂管理能力。但很多场景下，存在团队成员这一概念，因此引入受限域，只允许团队成员进入 
+- **成员模板** 项目不维护组织架构，因此受限域的域成员需要重复添加，为了解决该问题，引入成员模板导入功能，避免重复行为
+