logo
mdocs
首页
特性
开始
文档
GitHub
首页
特性
开始
文档
GitHub
logo
mdocs

快速开始

安装
第一个知识库

AI 与 Agent

智能助手(AI)
Agent 开发闭环
CLI Token

核心概念

所见皆文件
工作空间
文档级邀请
无账户身份识别

使用指南

设置页面概览
Markdown 编辑
HTML 文档
流程图生成
知识图谱
草稿与同步
我的文章与邀请
文档收藏
文档评论
受限工作空间成员与模板
恢复码(兼容)

部署与配置

环境要求
配置文件
反向代理示例
客户端壳(Android / 桌面)
FAQ
更新日志
Previous Page第一个知识库
Next PageAgent 开发闭环
mdocs

Write freely. Never lose a word.

MIT License
产品
功能特性Agent 开发闭环竞品对比更新日志
资源
文档安装指南
社区
GitHub问题反馈
© 2026 mdocs · Made with ♥ by xuhuafeifei

#智能助手(AI)

mdocs 内置 两种 AI 能力模式,共用设置页里的 DeepSeek 配置。

最大区别是用户交互度:

🤖 智能助手✍️ 帮写(Coding)
交互度低:以结果为导向,正文侧偏 一次覆写(空文可直写;有正文需你点确认或改走帮写)高:以过程为导向,必须和你 交互审阅——分段提案、接受/拒绝,你拍板后才写回
你在干什么提需求 →(必要时确认)→ 看结果提需求 → 看 Diff → 逐段/整批决定 → 完成并写回

其他差异是为此服务的:

对比维度智能助手(Ask / Normal)帮写(Coding)
入口左下角悬浮球(可拖动)编辑器顶栏「帮写」/ 欢迎页「AI 帮写」
UI小浮层全屏工作台(左对话、右 Markdown Diff)
写回时机确认后直接写服务端(覆写)在缓冲区改到满意,点「完成并写回」才进本地草稿
能力侧重答疑、搜文、建空文档/文件夹、找位置、全文一键生成/重写起草、改稿、润色、续写,精细控制每一段
会话全局历史(不绑文档)按文档隔离
存储tenant/<id>/agent/session/tenant/<id>/agent/coding-session/

一句话: 要快、愿意一次覆写 → 智能助手;要和 AI 来回改、段段把关 → 帮写。

若你要用 Cursor / Claude 等外部 Agent 读写知识库、落开发契约,见 Agent 开发闭环。


#智能助手(Ask / Normal)

左下角圆形 智能助手 入口(可拖动)。点击打开浮层 「mdocs 智能助手」,主编辑区仍保持打开。按住拖动可改位置(本地记住);挪过之后会出现「重置位置」。

智能助手入口(可拖动)与聊天浮层

浮层开场会说明分工:答疑用智能助手(可搜文、建空文档、帮你找位置);写 / 精细改正文请用顶栏「帮写」。

浮层内:

  • 顶部:+ 新建会话、历史列表、关闭
  • 中间:问候语、快捷提问(如「如何发布文档?」「草稿是什么?」「如何创建工作空间?」)与对话内容
  • 底部输入框:占位「把你的问题告诉我…」;发送中可点 停止 真正取消本轮
  • 页脚提示:内容由 AI 生成,仅供参考

#后台运行(v1.4.0+)

  • 关掉浮层不会中断正在进行的一轮对话:服务端继续跑,下次打开会回放并接上
  • 需要打断时:点输入区旁的 停止,或在有未完成选择卡 / Skill 表单时走「强制关闭」
  • 新建会话 / 切换历史会取消当前活动 run
  • 单轮最长时长可在 设置 → AI → 高级选项 → 单轮超时 调整(默认 300 秒)
  • 服务进程重启后,未完成的一轮会标为已中断,需重新发消息

#PC 贴左与右侧目录(v2.0.10+ / v2.1.0)

宽屏下,助手标题栏可切到 贴左:助手占左侧栏(替换原来的完整侧栏),正文居中。此时文档树会移到右侧纯目录轨(无品牌头 / 新建 / 访客脚),与正文挤占分宽。

贴左:助手左 · 正文中 · 右侧目录展开

目录可收起:右上角收起后,右缘只剩绿色吸附条「目录」,再点即可展开(带宽度动画)。偏好会记住。

贴左:目录收起后的绿色「目录」条

浮窗模式或关闭助手后,目录回到左侧完整侧栏。

#上下文压缩(v2.1.0+)

长会话会占满模型上下文。输入区旁有用量环;与 Skill 并排有 压缩上下文 按钮。

  • 自动:估算用量 ≥ 85% 时,下一轮对话开始前先压缩(保留最近约 6 轮原文,更早内容由模型摘要)
  • 手动:随时点「压缩上下文」,不要求已到 85%
  • 压缩中会显示「正在压缩上下文…」,期间该会话其它写入 / 开跑会提示稍后再试

正在压缩上下文

压缩失败不会改历史,本轮仍尽量用原记录继续;摘要块在时间线里显示为「上下文已压缩」,可展开查看。

#上下文诊断(v3.1.7+)

点用量圆环可打开 上下文诊断:与圆环同源,分三桶查看 系统提示词 / 工具定义 / 会话历史,点条目可读正文。弹框固定尺寸,手机端全屏。

#Engram 本机记忆(插件)

在插件市场安装 Engram 后,助手可经 MCP 跨会话记住决策 / gotcha / 约定(按访客隔离,数据在本机 tenant/<访客>/plugins-data/engram)。装机后会写入灵魂旁路 engram.md;适合「先搜再答」,不是文档仓库。

#可以做什么

直接问,例如:

  • 如何发布文档?草稿是什么?
  • 如何创建工作空间?权限怎么设置?
  • 帮我搜索 / 列出某工作空间的文档,并打开其中一篇说明要点
  • 帮我创建一个空文档「XXX」
  • 这篇文档几乎是空的,帮我写个大纲并直接写好

#覆写机制(有正文时)

当文档已有实质内容,智能助手不会静默改写。你若要求覆写,助手会弹出选择卡,三选一:

  1. 直接覆写 → 同意后线性写入服务端(带版本冲突校验)
  2. 打开帮写审阅 → 跳帮写模式,先在右侧看提案再决定
  3. 取消 → 不写

#明确不会做

  • 静默改写有实质正文的文档(必须经你确认或走帮写)
  • 越权读取你无权查看的文档(与网页端同一套权限)
  • 精细改稿 / 逐段审阅(请用顶栏 帮写)

#帮写(Coding 模式)

需要和 AI 高交互地改正文(逐段看 Diff、接受/拒绝)时用 帮写。智能助手偏覆写结果;帮写偏过程协作。

#入口

打开一篇文档后,在编辑器顶栏工具条右侧(发布 / 删除附近)点击 帮写(带星标图标)进入全屏工作台。欢迎页也可点「AI 帮写」从空白开始。

文档顶栏「帮写」入口

#工作流

  1. 通过顶栏 帮写(或欢迎页「AI 帮写」)进入全屏层:左侧对话,右侧 Markdown
  2. 描述要写/改的内容;助手会先读当前工作稿与进场快照,再提交完整 Markdown 提案
  3. 右侧按变更段 接受 / 拒绝;也可继续手改
  4. 完成并写回:已有文档写入本地草稿(需你再发布);空白帮写则创建新文档

#工作台界面

帮写全屏:左对话、右 Diff 审阅

区域说明
顶栏文档名;取消退出;完成并写回把已接受内容写回(已有文进本地草稿)
左侧 · 对话说明要写/改什么;助手可「读取帮写工作稿」再「设置帮写正文」更新提案;+ / 历史管理会话;与智能助手一样支持后台跑完(关掉工作台不掐断,重开可续)
右侧 · 提案红删绿增的分段 Diff;可 全部接受 / 全部拒绝,或逐段操作;也可切 纯编辑 手改;底部可在变更间跳转

#核心设计:高交互审阅

帮写的核心不是「更能写」,而是 必须和你交互:

  • AI 吐出的是完整 Markdown 提案,不是直接改文件
  • 前端 diff 计算后按段高亮,每段你可独立「接受」或「拒绝」
  • 接受的段落合并进「当前稿」,剩余可继续手改或再次 AI 续写
  • 全程不碰服务端,直到你点「完成并写回」才写入本地草稿

#会话说明

  • 帮写会话与智能助手完全隔离,互不干扰
  • 按文档隔离:文章 A 的历史看不到文章 B
  • 左侧同样有 + / 历史;历史只回放对话文字,不恢复右侧稿
  • 从空白帮写写回成文后,当前对话会绑到新文档,下次打开该文帮写可续聊

#开始使用前:配置模型

#DeepSeek(推荐,最快上手)

  1. 打开 设置 → AI(侧栏底部访客信息进入设置)
  2. 选择 Deepseek 标签页
  3. 选择模型:deepseek-v4-flash 或 deepseek-v4-pro
  4. 填写你的 DeepSeek API Key 并保存

设置 → AI:智能助手模型配置

未配置 Key 时,入口可用但无法发送消息,浮层 / 帮写会提示去配置。

💡 快捷方式:直接点智能助手面板里的「配置」卡片,不用进设置页也能填 Key。

#自定义供应商

如果你用其他模型服务商(OpenAI、Anthropic、自建网关等),可以用自定义配置:

  1. 打开 设置 → AI,点「+ 新建配置」
  2. 切换到 自定义 标签页
  3. 填写三个必填项:
    • API 地址 — 你的服务商 API 根地址(如 https://api.openai.com/v1)
    • Model ID — 模型名称(如 gpt-4o、claude-3-5-sonnet-20241022)
    • API Key — 你的密钥
  4. (可选)高级选项里可以调:
    • Provider ID — 自定义标识,不填会自动从域名取
    • API 协议 — OpenAI 兼容 / Anthropic 兼容(URL 含 anthropic 会自动识别)
    • 配置备注名、Context Window
    • 单轮超时(秒) — 关闭面板后仍在后台跑的最长时间(默认 300,范围 60–3600)

DeepSeek / 自定义配置都支持 思考强度(关 / 低 / 高 / 最大)与上述单轮超时。

#多配置管理

  • 可以保存多条配置,随时切换默认
  • 每条配置独立存 Key,互不影响
  • 删除默认配置后,会自动把另一条设为默认

#安全与隐私

  • API Key 以文件形式单独存储在 ~/.mdocs/secrets/agent-api-keys.json,文件权限 0600(仅本人可读写)
  • 数据库中不存 Key 明文
  • 按访客隔离,你配置的 Key 只有你能用
  • 不会出现在任何前端返回中(只返回「是否已配置」和脱敏尾号)

#私人 Agent Skills

同一页下方还可管理 Agent Skills(私人提示词宏):

  • 名称对本账号唯一,仅英文、数字、下划线
  • 简介可选;正文为 Agent 应遵守的步骤与约束
  • 在智能助手 / 帮写输入区点 Skill 多选引用;本轮发送成功后选中标签会清空
  • 也可让助手用工具管理:list_user_skills / get_user_skill(读全文)/ create_user_skill(表单卡)/ update_user_skill(直接写入,带版本防覆盖)/ delete_user_skill

落盘与会话历史只保存 skill 名称引用,不会把正文全文写进聊天记录;请求时再按名称展开进模型上下文。

#怎么问(智能助手)

可以直接问,例如:

  • 如何发布文档?
  • 草稿是什么?
  • 如何创建工作空间?
  • 权限怎么设置?
  • 帮我搜索 / 列出某工作空间的文档,并打开其中一篇说明要点

助手会按需阅读 mdocs 用户手册 相关章节,也可在你有权阅读的范围内读取知识库文档。工具结果(搜索表、目录树、读文预览等)会出现在对话时间线中,默认折叠,展开可查看;历史会话重开后通常只保留文字、不再回放这些工具块。答完后通常会附带一两个可继续追问的示例。

#会话(智能助手)

  • 同一访客的对话会保存在数据目录 tenant/<访客ID>/agent/session/ 下,刷新或重开浮层仍可续聊。
  • 浮层标题栏 「+」:新建空会话并切换过去(若有进行中的后台 run,会先取消)。
  • 历史图标:按最近更新列出会话;点击即可切换并回放该会话(纯文本;工具 UI 不落盘)。
  • 会话标题取自第一条用户消息(过长会截断),不是模型摘要。
  • 后台 run 的事件另存于 tenant/<访客ID>/agent/runs/(与会话 transcript 分离),用于关面板后回放。
  • 删除、按天数自动清理尚未提供;置顶 / 手动重命名见产品内历史面板。

#明确不会做(智能助手)

  • 静默改写有实质正文的文档(必须经你弹出选择卡确认)
  • 越权读取你无权查看的文档(与网页端同一套权限)
  • 静默替你发布或改权限档(结构操作会走工具;写作类请求会根据上下文决定直写或弹选择卡)

若你在智能助手里要求写作,助手会根据文档状态决定:空文直接覆写,有正文则弹出选择卡。