@fgbg/mdocs 0.8.8 → 0.8.10

package/agent-skills/deployment-requirements/SKILL.md

@@ -0,0 +1,50 @@
+---
+id: deployment-requirements
+name: "环境要求"
+description: "- **无外部服务依赖**：不需要安装数据库、缓存、消息队列等中间件 - SQLite：内嵌在 better-sqlite3 中，零配置 - 文档存储：直接使用文件系统"
+keywords: []
+source: deployment/requirements.md
+---
+
+# 环境要求
+
+## 运行时
+
+| 资源 | 要求 |
+|------|------|
+| 运行时 | Node.js 22+ |
+| 包管理器 | pnpm（推荐） |
+| CPU | 1 核（开发/小团队够用） |
+| 内存 | 512 MB 以上 |
+| 磁盘 | 视文档量而定 |
+
+## 依赖
+
+- **无外部服务依赖**：不需要安装数据库、缓存、消息队列等中间件
+- SQLite：内嵌在 better-sqlite3 中，零配置
+- 文档存储：直接使用文件系统
+
+## 存储布局
+
+运行时数据集中存储在 `~/.mdocs/` 目录下：
+
+```
+~/.mdocs/
+  sqlite/
+    data.sqlite       # 元数据（文档索引、访客、权限、审计日志）
+  files/
+    docs/
+      {domain_id}/    # 每个域独立的子目录
+        a.md          # 域内文档（Lexical JSON 格式）
+    assets/           # 上传的附件
+  logs/               # 运行日志（按日期轮转）
+```
+
+可通过环境变量 `MDOCS_DATA_DIR` 自定义数据目录位置。
+
+## 网络
+
+- 默认监听 `0.0.0.0:4000`（所有网卡，适合服务器直接暴露或通过反向代理）
+- 本地开发若只想本机访问：`export MDOCS_HOST=127.0.0.1`
+- 生产部署仍建议通过反向代理对外暴露（见[反向代理](./reverse-proxy.md)）
+

package/agent-skills/deployment-reverse-proxy/SKILL.md

@@ -0,0 +1,71 @@
+---
+id: deployment-reverse-proxy
+name: "反向代理配置"
+description: "生产部署时，推荐将 mdocs 放在反向代理之后，由代理层处理 TLS 证书、域名绑定、日志等。"
+keywords: []
+source: deployment/reverse-proxy.md
+---
+
+# 反向代理配置
+
+生产部署时，推荐将 mdocs 放在反向代理之后，由代理层处理 TLS 证书、域名绑定、日志等。
+
+## Nginx
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name docs.yourdomain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:4000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket 支持（如果需要）
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+> 同机 Nginx 反代时，`proxy_pass http://127.0.0.1:4000` 即可（mdocs 默认监听 `0.0.0.0:4000`）。若曾手动设过 `MDOCS_HOST=127.0.0.1`，需改回 `0.0.0.0` 或删掉该变量。
+
+## Caddy
+
+```
+docs.yourdomain.com {
+    reverse_proxy localhost:4000
+}
+```
+
+## Docker Compose
+
+```yaml
+services:
+  mdocs:
+    build: .
+    ports:
+      - "127.0.0.1:4000:4000"
+    environment:
+      - MDOCS_DATA_DIR=/data
+    volumes:
+      - mdocs-data:/data
+
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf
+    depends_on:
+      - mdocs
+```
+

package/agent-skills/faq/SKILL.md

@@ -0,0 +1,48 @@
+---
+id: faq
+name: "FAQ"
+description: "**Notion** 是 SaaS 服务，数据在云端，隐私受制于服务商；**Obsidian** 是本地优先，但多人协作需要额外付费方案。mdocs 在这两者之间取了一个平衡：**纯私有化部署 + 无账户协作**。你控制服务器，但协作者不需要注册任何账户。"
+keywords: []
+source: faq.md
+---
+
+# FAQ
+
+### mdocs 和 Notion / Obsidian 有什么区别？
+
+**Notion** 是 SaaS 服务，数据在云端，隐私受制于服务商；**Obsidian** 是本地优先，但多人协作需要额外付费方案。mdocs 在这两者之间取了一个平衡：**纯私有化部署 + 无账户协作**。你控制服务器，但协作者不需要注册任何账户。
+
+### 需要安装数据库吗？
+
+不需要。mdocs 使用 SQLite，数据存储在 `~/.mdocs/` 目录中，无需单独安装或管理任何数据库服务。
+
+### 数据存在哪里？
+
+- **文档内容**：以 Lexical JSON 格式存储在文件系统
+- **元数据**（索引、权限、访客信息）：存储在 SQLite 数据库中
+- **未发布的草稿**：存储在浏览器 IndexedDB 中
+- 备份时只需复制整个数据目录即可
+
+### 支持多人协作吗？
+
+支持。通过「域 + 文档级邀请」实现：
+- public 域的文档默认可被所有人查看
+- 文档所有者可以邀请特定访客获得编辑权限
+- 不需要协作者注册账户
+
+### 适合多大规模？
+
+mdocs 主要面向**小团队**（几人到十几人）。没有用户系统、没有复杂的权限层级，这是有意为之的简化。
+
+### 数据如何备份？
+
+直接复制 `~/.mdocs/` 目录即可。文档存储格式为 JSON，需要搭配 SQLite 元数据才能完整恢复。
+
+### 能不能导出数据？
+
+目前文档以 Lexical JSON 格式存储，只能由 mdocs 加载。未来会提供 Markdown 导出功能。元数据在 SQLite 中，可以用 SQLite 工具直接读取。
+
+### 如何升级？
+
+拉取最新代码 → `pnpm install && pnpm build` → 重启进程。数据库和文档格式保持向后兼容。
+

package/agent-skills/getting-started-first-kb/SKILL.md

@@ -0,0 +1,40 @@
+---
+id: getting-started-first-kb
+name: "第一个文档"
+description: "启动 mdocs 后，浏览器会弹出**访客注册**对话框——输入一个名称即可创建身份 ![身份照片](./first-kb/identify.png)"
+keywords: []
+source: getting-started/first-kb.md
+---
+
+# 第一个文档
+
+## 创建身份
+
+启动 mdocs 后，浏览器会弹出**访客注册**对话框——输入一个名称即可创建身份
+![身份照片](./first-kb/identify.png)
+
+## 创建文档
+
+1. 注册完成后，点击左侧边栏的「新建文档」
+2. 输入文件名（如 `hello.md`），点击创建
+3. 文档创建后自动进入编辑器
+
+## 编辑器界面
+
+![mdocs主页](./first-kb/mdocs-main.png)
+
+点击`新建文档`，创建md文档。点击`创建文件夹`，创建文件夹
+
+## 编辑与保存
+
+- **自动保存**：编辑内容实时存入浏览器本地数据库（IndexedDB），断网不丢
+- **发布**：点击「发布」将内容同步到服务器，持久化为 Markdown 文件
+
+## 目录结构
+
+文档在文件系统中以文件形式存储。后端将文档路径树映射为左侧边栏的文件夹结构，支持嵌套目录。
+
+## 核心思路
+
+mdocs 的设计哲学是：**编辑时用富文本，存储时用Lexical维护的Json**。编辑器内部使用 Lexical JSON 保留格式信息，发布时写入 `.md` 文件，确保数据永远可读、可迁移。
+

package/agent-skills/getting-started-installation/SKILL.md

@@ -0,0 +1,119 @@
+---
+id: getting-started-installation
+name: "安装"
+description: "- **运行时**：Node.js 22+ - **无需额外安装数据库或中间件**"
+keywords: []
+source: getting-started/installation.md
+---
+
+# 安装
+
+## 环境要求
+
+- **运行时**：Node.js 22+
+- **无需额外安装数据库或中间件**
+
+## 快速安装（推荐）
+
+```bash
+npm install -g @fgbg/mdocs
+```
+
+安装完成后，直接运行：
+
+```bash
+mdocs
+```
+
+即可启动服务，访问 `http://localhost:4000`。
+
+也可以临时体验：
+
+```bash
+npx @fgbg/mdocs
+```
+
+## 从源码构建（开发模式）
+
+如果你需要参与开发或自定义功能：
+
+```bash
+git clone https://github.com/xuhuafeifei/mdocs
+cd mdocs
+pnpm install
+```
+
+### 启动开发模式
+
+```bash
+pnpm dev
+```
+
+一条命令同时启动后端（Express，`localhost:4000`）和前端（Vite，`localhost:5173`，自动代理 `/api`）。
+
+### 构建与运行
+
+```bash
+pnpm build          # 构建前端 + 编译后端
+pnpm start          # 生产模式，同一端口提供前端和 API
+```
+
+## CLI 命令
+
+`mdocs` 包附带管理命令：
+
+```bash
+# 列出所有访客
+mdocs visitor list
+
+# 访客迁移（按名称，推荐）
+mdocs visitor migrate --from Alice --to Bob --confirm
+
+# 访客迁移（按 UUID，精确匹配）
+mdocs visitor migrate --from OLD_UUID --to NEW_UUID --confirm
+
+# 试运行，查看影响范围但不实际执行
+mdocs visitor migrate --from Alice --to Bob --dry-run
+
+# 显式启动服务
+mdocs start
+```
+
+## 运行时数据
+
+首次启动后，数据目录自动创建在 `~/.mdocs/`：
+
+```
+~/.mdocs/
+  sqlite/
+    data.sqlite       # 元数据（文档索引、权限、访客、审计日志）
+  files/
+    docs/
+      {domain_id}/    # 每个域独立的子目录
+        a.md          # 域内文档
+        folder/       # 域内子目录（逻辑存在于数据库）
+          b.md
+    assets/           # 上传的附件
+  logs/               # 运行日志
+```
+
+文档以 Lexical JSON 格式存储在 `files/docs/` 中，只能由 mdocs 加载编辑。
+
+## 验证
+
+启动后访问 `http://localhost:4000`（npm 安装）或 `http://localhost:5173`（开发模式），看到访客注册弹窗即表示运行成功。
+
+## 升级
+
+通过 npm 安装的版本，直接重新安装即可升级：
+
+```bash
+npm install -g @fgbg/mdocs@latest
+```
+
+升级后重启服务即可。
+
+## 下一步
+
+了解 [核心设计理念](../core-concepts/domain.md)，或直接[创建第一个文档](./first-kb.md)。
+

package/agent-skills/index/SKILL.md

@@ -0,0 +1,47 @@
+---
+id: index
+name: "mdocs 文档"
+description: "欢迎阅读 mdocs 使用文档。"
+keywords: []
+source: index.md
+---
+
+# mdocs 文档
+
+欢迎阅读 mdocs 使用文档。
+
+## 快速开始
+
+- [安装与启动](./getting-started/installation.md)
+- [第一个文档](./getting-started/first-kb.md)
+
+## 核心设计
+
+- [域隔离](./core-concepts/domain.md)——团队与个人的逻辑边界
+- [无账户身份识别](./core-concepts/no-account.md)——打开即用，无需注册
+- [文档级邀请](./core-concepts/invitation.md)——精细到单篇文档的权限控制
+
+## 使用指南
+
+- [设置页面概览](./usage/settings.md)——集中配置中心
+- [上手助手（AI）](./usage/onboarding-ai.md)——产品向导，答疑不代写
+- [编辑体验](./usage/markdown.md)——富文本编辑，Markdown 存储
+- [流程图生成](./usage/flowchart.md)——拖拽绘制，嵌入文档
+- [草稿与同步](./usage/drafts.md)——本地优先，按需发布
+- [版本冲突与合并](./usage/merge-conflicts.md)——409 时的三栏合并
+- [我的文章与邀请](./usage/my-documents.md)——集中管理创作内容
+- [收藏功能](./usage/bookmarks.md)——快速标记重要文档
+- [文档评论](./usage/comments.md)——协作讨论与反馈
+- [受限域成员与名单模板](./usage/domain-members.md)——团队域邀人、复用成员名单
+
+## 部署运维
+
+- [环境要求](./deployment/requirements.md)
+- [配置](./deployment/config.md)
+- [反向代理](./deployment/reverse-proxy.md)
+
+## 其他
+
+- [FAQ](./faq.md)
+- [更新日志](./changelog.md)
+

package/agent-skills/index.json

@@ -0,0 +1,184 @@
+[
+  {
+    "id": "changelog",
+    "name": "更新日志",
+    "description": "- **上手助手（AI）**：左下角浮动入口；设置页「AI」配置个人 DeepSeek Key；按访客落盘会话（`tenant/<id>/agent/session`），多轮续聊；回答引用手册页面链接；思考中三点动画；跟随滚动仅在贴底时生效 - **手册**：新增 [上手助手（AI）](./usage/onboarding-ai.md)",
+    "keywords": [],
+    "source": "changelog.md"
+  },
+  {
+    "id": "core-concepts-all-files",
+    "name": "所见皆文件",
+    "description": "mdocs 的存储模型将文档目录树映射为两层结构：",
+    "keywords": [],
+    "source": "core-concepts/all-files.md"
+  },
+  {
+    "id": "core-concepts-domain",
+    "name": "域隔离（Domain）",
+    "description": "mdocs 中的「域」是最顶层的逻辑隔离单元。它的设计目标是：",
+    "keywords": [],
+    "source": "core-concepts/domain.md"
+  },
+  {
+    "id": "core-concepts-invitation",
+    "name": "文档级邀请",
+    "description": "传统文档协作需要先注册账户、加入团队、然后才能编辑——门槛太高。mdocs 的邀请机制只针对「文档」这个最小粒度，且被邀请者不需要预先注册。",
+    "keywords": [],
+    "source": "core-concepts/invitation.md"
+  },
+  {
+    "id": "core-concepts-no-account",
+    "name": "无账户身份识别",
+    "description": "不做用户系统，不设注册流程。每个访问者通过浏览器获得一个身份令牌，以此识别身份。目标是零上手成本——打开就能用。",
+    "keywords": [],
+    "source": "core-concepts/no-account.md"
+  },
+  {
+    "id": "deployment-config",
+    "name": "配置",
+    "description": "mdocs **没有配置文件**。所有配置通过环境变量设置，遵循 12-Factor App 原则。",
+    "keywords": [],
+    "source": "deployment/config.md"
+  },
+  {
+    "id": "deployment-requirements",
+    "name": "环境要求",
+    "description": "- **无外部服务依赖**：不需要安装数据库、缓存、消息队列等中间件 - SQLite：内嵌在 better-sqlite3 中，零配置 - 文档存储：直接使用文件系统",
+    "keywords": [],
+    "source": "deployment/requirements.md"
+  },
+  {
+    "id": "deployment-reverse-proxy",
+    "name": "反向代理配置",
+    "description": "生产部署时，推荐将 mdocs 放在反向代理之后，由代理层处理 TLS 证书、域名绑定、日志等。",
+    "keywords": [],
+    "source": "deployment/reverse-proxy.md"
+  },
+  {
+    "id": "faq",
+    "name": "FAQ",
+    "description": "**Notion** 是 SaaS 服务，数据在云端，隐私受制于服务商；**Obsidian** 是本地优先，但多人协作需要额外付费方案。mdocs 在这两者之间取了一个平衡：**纯私有化部署 + 无账户协作**。你控制服务器，但协作者不需要注册任何账户。",
+    "keywords": [],
+    "source": "faq.md"
+  },
+  {
+    "id": "getting-started-first-kb",
+    "name": "第一个文档",
+    "description": "启动 mdocs 后，浏览器会弹出**访客注册**对话框——输入一个名称即可创建身份 ![身份照片](./first-kb/identify.png)",
+    "keywords": [],
+    "source": "getting-started/first-kb.md"
+  },
+  {
+    "id": "getting-started-installation",
+    "name": "安装",
+    "description": "- **运行时**：Node.js 22+ - **无需额外安装数据库或中间件**",
+    "keywords": [],
+    "source": "getting-started/installation.md"
+  },
+  {
+    "id": "index",
+    "name": "mdocs 文档",
+    "description": "欢迎阅读 mdocs 使用文档。",
+    "keywords": [],
+    "source": "index.md"
+  },
+  {
+    "id": "usage-bookmarks",
+    "name": "收藏功能",
+    "description": "收藏功能帮助你快速标记和访问重要文档。已收藏的文档会出现在「我的收藏」列表中，便于跨域快速访问。",
+    "keywords": [],
+    "source": "usage/bookmarks.md"
+  },
+  {
+    "id": "usage-cli-token",
+    "name": "CLI Token",
+    "description": "CLI Token 是给命令行工具和 AI Agent（如 Claude Code）使用的身份令牌，继承你在 mdocs 中的所有权限。Token 与你的访客身份绑定，创建后可以通过 HTTP API 读写文档。",
+    "keywords": [],
+    "source": "usage/cli-token.md"
+  },
+  {
+    "id": "usage-comments",
+    "name": "评论功能",
+    "description": "评论功能提供文档内的协作讨论能力，支持对整篇文档发表评论和回复，便于团队协作文档时的沟通与反馈。",
+    "keywords": [],
+    "source": "usage/comments.md"
+  },
+  {
+    "id": "usage-domain-members",
+    "name": "受限域成员与名单模板",
+    "description": "本文说明如何在 mdocs 里维护 **restricted（受限）域** 的成员，以及如何使用 **域成员模板** 减少重复勾选。与权限模型相关的设计背景见 [域隔离](../core-concepts/domain.md)。",
+    "keywords": [],
+    "source": "usage/domain-members.md"
+  },
+  {
+    "id": "usage-drafts",
+    "name": "草稿与同步",
+    "description": "编辑环境中存在一个天然矛盾：用户希望内容「随时保存，永不丢失」，但网络可能不稳定，服务器可能暂时不可用。mdocs 用**本地优先 + 按需发布**的草稿机制来解决这个问题。",
+    "keywords": [],
+    "source": "usage/drafts.md"
+  },
+  {
+    "id": "usage-flowchart",
+    "name": "流程图生成",
+    "description": "mdocs 的流程图基于 **Meta2d** 绘图引擎，设计目标是让用户像使用 Visio 或 draw.io 一样拖拽绘制，同时将图表数据嵌入文档内容。",
+    "keywords": [],
+    "source": "usage/flowchart.md"
+  },
+  {
+    "id": "usage-markdown",
+    "name": "编辑体验",
+    "description": "mdocs 的编辑器基于 Lexical（Meta 开源的富文本引擎），配合 `@lobehub/editor` 插件体系。核心思路是：**用富文本编辑，以 JSON 存储**。",
+    "keywords": [],
+    "source": "usage/markdown.md"
+  },
+  {
+    "id": "usage-merge-conflicts",
+    "name": "版本冲突与合并",
+    "description": "当发布时服务端 head 已前进（例如他端编辑、或本机自动发布后又改稿），`PUT` 可能返回 **409 版本冲突**。mdocs 会引导你进入 **合并** 界面，而不是直接覆盖远端。",
+    "keywords": [],
+    "source": "usage/merge-conflicts.md"
+  },
+  {
+    "id": "usage-my-documents",
+    "name": "我的文章",
+    "description": "「我的文章」功能聚合展示你创建的所有文档，集中管理跨域内容，并提供快捷的文档操作入口。",
+    "keywords": [],
+    "source": "usage/my-documents.md"
+  },
+  {
+    "id": "usage-onboarding-ai",
+    "name": "上手助手（AI）",
+    "description": "mdocs 内置了一个**产品上手向导**，只解答「怎么用 mdocs」（域、草稿、发布、权限等），**不会**帮你写正文或改文档。",
+    "keywords": [],
+    "source": "usage/onboarding-ai.md"
+  },
+  {
+    "id": "usage-recovery-code",
+    "name": "恢复码与身份找回",
+    "description": "恢复码是一串由字母和数字组成的特殊代码，格式如：",
+    "keywords": [],
+    "source": "usage/recovery-code.md"
+  },
+  {
+    "id": "usage-search",
+    "name": "全文搜索",
+    "description": "mdocs 内置了基于 FTS5（SQLite 全文索引引擎）的搜索功能，支持中文分词。",
+    "keywords": [],
+    "source": "usage/search.md"
+  },
+  {
+    "id": "usage-settings",
+    "name": "设置页面",
+    "description": "设置页面是 mdocs 的集中配置中心，提供访客身份、域管理、内容管理等各种系统级功能。",
+    "keywords": [],
+    "source": "usage/settings.md"
+  },
+  {
+    "id": "why-mdocs",
+    "name": "why-mdocs",
+    "description": "import { WhyMdocsPage } from '../../src/components/WhyMdocsPage';",
+    "keywords": [],
+    "source": "why-mdocs.mdx"
+  }
+]

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

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