# @fgbg/mdocs 中文文档

规范地址：https://npmcn.com/package/%40fgbg/mdocs/

版本：3\.1\.16
npm 元数据更新时间：2026-11-11T09:30:18.230Z
中文译文更新时间：2026-11-14T16:27:58.288Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fgbg/mdocs
原文对照：https://npmcn.com/package/%40fgbg/mdocs/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：19 MB，846 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：39 个
- 首次发布：2026-05-09T03:36:58.199Z
- 最新版本发布：2026-11-11T09:30:18.135Z
- 近 30 天下载量：5023（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：109（近 12 个月 109 个）

## 中文简介

小团队的Markdown知识库

## 安装

```sh
npm install @fgbg/mdocs
```

也可以使用：`pnpm add @fgbg/mdocs`、`yarn add @fgbg/mdocs`、`bun add @fgbg/mdocs`

## README

# mdocs

**专门为 Markdown 设计的 Agent 工作台。**

[文档站点](https://xuhuafeifei.github.io/mdocs-site/) · [GitHub](https://github.com/xuhuafeifei/mdocs) · [npm `@fgbg/mdocs`](https://www.npmjs.com/package/@fgbg/mdocs) · 当前版本 **3.1.16**

## 为什么选 mdocs

| 能力 | 说明 |
| --- | --- |
| **所见即所得** | 直接编辑渲染后的 Markdown，不必在源码和预览之间来回跳。 |
| **Markdown inline Diff** | Agent 改稿与版本对比都在渲染态上按块 Keep / Undo，不是 IDE 源码 diff。 |
| **Agent 代劳** | 搜文、建文档、改结构、写作审阅都可交给 Agent；可挂 **Engram** 本机记忆。 |
| **内置版本 + 预览对比** | 发布即留历史，预览 / 对比旧稿；数据默认 `~/.mdocs`。 |
| **流水线：MCP + Skills / CLI** | 插件挂 MCP；[mdocs-cli](https://github.com/xuhuafeifei/mdocs-cli) Skills 让 Cursor / Claude 读写同一知识库。 |

## 快速开始

```bash
npm install -g @fgbg/mdocs
mdocs
# 浏览器打开 http://localhost:4000
```

临时体验：

```bash
npx @fgbg/mdocs
```

需要 **Node.js 22+**。更细的安装见 [文档 · 安装](https://xuhuafeifei.github.io/mdocs-site/docs/getting-started/installation.html)。

## 能力一览

### 所见即所得

![所见即所得 Markdown 编辑](https://npmcn.com/package/%40fgbg/mdocs/image/suojianjisuode-qingxiban.png)

### Markdown inline Diff

Agent 提案写进当前打开的编辑器，在**渲染态**上显示红绿 Diff；按块 Keep / Undo 后再发布。

![Markdown inline Diff](https://npmcn.com/package/%40fgbg/mdocs/image/inline-diff.png)

### Agent 代劳

搜文、建文档、改结构、写作与审阅——产品内能力都可以交给 Agent。

![智能助手代劳](https://npmcn.com/package/%40fgbg/mdocs/image/all-in-agent.png)

### 内置版本 + 预览对比

![版本历史预览与对比](https://npmcn.com/package/%40fgbg/mdocs/image/history-diff.png)

### 流水线：MCP + Skills / CLI

插件市场管理 Skill / MCP；安装流水线可视化编排。

![插件市场](https://npmcn.com/package/%40fgbg/mdocs/image/chajian-shichang.png) ![插件安装流水线](https://npmcn.com/package/%40fgbg/mdocs/image/chajian-anzhuang.png) ![AI 安装插件](https://npmcn.com/package/%40fgbg/mdocs/image/chajian-aianzhuang.png)

CLI Token + Skills：Cursor / Claude 可搜索、读写同一知识库。详见 [Agent 开发闭环](https://xuhuafeifei.github.io/mdocs-site/docs/usage/agent-dev-loop.html) · [CLI Token](https://xuhuafeifei.github.io/mdocs-site/docs/usage/cli-token.html)。

## 从源码开发

```bash
git clone https://github.com/xuhuafeifei/mdocs.git
cd mdocs
pnpm install
pnpm dev          # API :4000 + Vite :5173（代理 /api）
```

```bash
pnpm build && pnpm start   # 生产：同端口提供静态资源与 API
pnpm test
pnpm typecheck
pnpm mdocs visitor list    # 管理 CLI（开发用 tsx 入口）
```

全局安装后原地升级（淘宝 npmmirror，保留 `node_modules`）：

```bash
mdocs update
```

仓库布局：

```
src/
  server/    Express API、Agent、文档与工作空间、CLI
  web/       Vite + React 前端
  shared/    两侧共用类型与路径工具
```

## 运行时数据

默认目录 `~/.mdocs/`（可用 `MDOCS_DATA_DIR` 覆盖）：

```
~/.mdocs/
  sqlite/data.sqlite
  files/docs/          # 文档内容
  files/assets/        # 附件
  logs/
```

`domain_id` 只存在于 SQLite，**不会**出现在文件路径里。

## 访客身份与迁移

首次访问输入昵称 → 获得 `visitor_id` + 高熵 token；浏览器存明文，服务端只存 `SHA-256(token)`，请求头 `x-visitor-token`。

清缓存后重新注册可用迁移合并身份：

```bash
mdocs visitor migrate --from Alice --to Bob --dry-run
mdocs visitor migrate --from Alice --to Bob --confirm
```

## 上传图片资源（CLI）

```bash
mdocs asset upload ./shot.png
# → http://localhost:4000/api/assets/<uuid>.png
mdocs asset upload ./a.png ./b.svg --base-url https://docs.example.com --json
```

命名规则与网页上传一致，落到 `<数据目录>/files/assets/`，经 `GET /api/assets/:id` 访问。

## 相关链接

|  |  |
| --- | --- |
| 产品文档 | [https://xuhuafeifei.github.io/mdocs-site/](https://xuhuafeifei.github.io/mdocs-site/) |
| 文档源码站 | [https://github.com/xuhuafeifei/mdocs-site](https://github.com/xuhuafeifei/mdocs-site) |
| CLI / Skills | [https://github.com/xuhuafeifei/mdocs-cli](https://github.com/xuhuafeifei/mdocs-cli) |
| 问题反馈 | [https://github.com/xuhuafeifei/mdocs/issues](https://github.com/xuhuafeifei/mdocs/issues) |

## License

[MIT](https://npmcn.com/package/%40fgbg/mdocs/LICENSE)

## 常见问题

### @fgbg/mdocs 是什么？

小团队的Markdown知识库

### 如何安装 @fgbg/mdocs？

在项目目录运行 npm install @fgbg/mdocs，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mdocs，可以用 npx mdocs 直接运行。

### @fgbg/mdocs 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fgbg\_\_mdocs 是否存在。

### @fgbg/mdocs 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fgbg/mdocs 可以商用吗？

@fgbg/mdocs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fgbg/mdocs 的下载量有多少？

根据 npm 官方下载统计，@fgbg/mdocs 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,023 次，日均约 167 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fgbg/mdocs 还在维护吗？

最新版本 3\.1\.16 发布于 2026/11/11（3 天前）；至今共发布 109 个版本，其中过去 12 个月发布了 109 个；首次发布于 2026/05/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。