# @bendyline/docblocks-cli 中文文档

规范地址：https://npmcn.com/package/%40bendyline/docblocks-cli/

版本：2\.7\.13
npm 元数据更新时间：2026-11-05T23:01:17.841Z
中文译文更新时间：2026-11-07T22:16:53.660Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bendyline/docblocks-cli
原文对照：https://npmcn.com/package/%40bendyline/docblocks-cli/?lang=original
项目主页：https://docblocks.com/cli/
源码仓库：https://github.com/bendyline/docblocks

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

- 包体积（解压后）：1.5 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.18\.0 \|\| \>=26\.0\.0
- 运行依赖：12 个
- 首次发布：2026-04-04T01:13:35.715Z
- 最新版本发布：2026-11-05T23:01:17.435Z
- 近 30 天下载量：2599（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

构建、预览、转换、渲染、检查和自动化文档

## 安装

```sh
npm install @bendyline/docblocks-cli
```

也可以使用：`pnpm add @bendyline/docblocks-cli`、`yarn add @bendyline/docblocks-cli`、`bun add @bendyline/docblocks-cli`

## README

# @bendyline/docblocks-cli (英语)

DocBlocks 用于文档构建和预览的命令行表面, 链接- Squisq 格式转换、 MP4 渲染、文档解析、工作空间目录更新以及 本地 MCP 代理服务器 .

[CLI和MCP概览](https://docblocks.com/cli/)

## 安装

需要24.18.0+或26+的节点.

```bash
npm install -g @bendyline/docblocks-cli
docblocks --help
```

## 文档

-   [权威CLI参考](https://github.com/bendyline/docblocks/blob/main/docs/cli.md)
-   [MCP 架构和协议指南](https://github.com/bendyline/docblocks/blob/main/docs/mcp.md)

这些指南描述了当前的输入支持,将Squisq所有权、格式联系起来 方向,覆盖行为,MCP权威,文物生命周期,以及保证.

## 图标

| 命令 | 目的 |
| --- | --- |
| `docblocks build` | 递归地将Markdown构建为独立的HTML. |
| `docblocks serve` | 运行受限制的本地预览服务器 . |
| `docblocks convert <input>` | 通过链接的 Squisq 注册转换 . |
| `docblocks video <input> [output]` | 将可配置的MP4. |
| `docblocks mcp` | 启动首个MCP服务器. |
| `docblocks themes` | 列表链接到 Squisq 主题ID. |
| `docblocks transforms` | 列表链接 Squisq 转换 ID . |
| `docblocks parse <input>` | 将UTF-8 Markdown 分解为 Squisq Markdown AST JSON. |
| `docblocks workspace refresh [dir]` | 启用更新目录输出 `.docblocks/workspace.json`。 。 。 . |

使用 `docblocks help <command>` 用于安装的选项摘要.

## 实例

```bash
# Build and preview Markdown
docblocks build --input ./docs --output ./dist
docblocks serve --dir ./docs

# The no-flag conversion set is exactly DOCX, PPTX, PDF, HTML, and DBK
docblocks convert story.md

# Select any export-capable linked-registry formats
docblocks convert report.docx --formats md,pdf,pptx --output-dir ./exports

# Render MP4 with explicit media controls
docblocks video story.md --quality high --orientation portrait

# Render the Dashboard rendition to a square image with accent cards
docblocks convert report.md --formats png --image-resolution square --image-style accent

# Regenerate the catalog.json / index.html a workspace opts into
docblocks workspace refresh ./docs --dry-run
docblocks workspace refresh ./docs

# Discover authoring vocabulary from linked Squisq
docblocks themes
docblocks transforms

# Start MCP with no filesystem authority
docblocks mcp

# Grant independent roots when an agent needs files or durable output
docblocks mcp --allow-read ./documents --allow-write ./exports
```

对于持久输出,请打电话 `list_roots` 在起草之前。 如果根没有被写入, 重新启动服务器 `--allow-write`; 不直接绕过 MCP `convert` 命令。 纯文本或普通的Markdown可以直接传递到 `convert_document` 没有飞行前; 自动选择相容模板, 和明确的 Squisq 说明仍然是可选的覆盖。 对于 PPTX , 一级 标题自己创建每个故意的幻灯片边界; 不添加 `---` 介于 幻灯片标题,除非打算采用可见水平规则. `get_authoring_context` 是精确注释示例的可选发现, 安全默认, 并模拟 描述主题/概括选择。 MCP指导告诉代理商推断并选择一个 样式来自简短,而不是显示原始身份,要求一个紧凑的高级 只有在选择实际上含糊不清时才提出问题。 完整的目录还在 可用时间 `docblocks://authoring-guide`。 。 。 .

`convert` 财务报告和审定财务报表 `video` 接受Markdown、Squisq JSON Doc、DBK/ZIP、文件夹和 导入可连接的注册格式. `video` 还使 **动态幻灯片** 从当前文本并保存设计 偏好对旁白车; 静态旁白或错失计时失败 输出。 节省下来的列报计划仍可读取. `build`编号 :`serve` 独立 HTML 包含 普通有栅栏的代码块的复制控制;美人鱼栅栏仍为图表. 无 `--theme`, (中文(简体) ), `build`编号 :`serve` 应用 `documents.defaultTheme` 从 `.docblocks/workspace.json` 前题名称没有主题的文档; `--ignore-workspace-settings` 选择退出. `workspace refresh` 只写入输出 设置启用, 只替换带有 DocBlocks 目录标记的文件, 写入 仅当字节不同时,退出 1 当一个手写文件阻碍输出时. `build` 替换生成的 HTML 文件; `convert` 财务报告和审定财务报表 `video` 拒绝现有目的地,除非 `--allow-overwrite` 实值 通过了。 多目标转换阶段 如果发布失败。 构建 traversal 、 输入字节 、 输出字节 是解析输入和 JSON 输出。 MCP 转换而不是返回 不可改变的会话文物 `save_artifact` 实现一个,使用 无替换或散列条件替换语义.

软件包根是一个无副作用的 API 程序 `runBuild`, (中文(简体) ), `runConvert`, (中文(简体) ), `runVideo`, (中文(简体) ), `runParse`,以及 `runWorkspaceRefresh`。导入它从不启动命令;可执行文件是 单独的 `docblocks` bin 条目.

实时链接注册目前覆盖了Markdown,DOCX,PDF,PPTX,XLSX,CSV, HTML,HTML ZIP,EPUB,DBK,MP4,GIF,和PNG. 方向因格式而异,所以使用 cLI 参考或 MCP `list_formats` 而不是假设每一种格式的导入.

MP4/GIF渲染需要铬和FFmpeg. 安装铬 `npx playwright install chromium`; Squisq 解析 FFmpeg 从 `SQUISQ_FFMPEG`, (中文(简体) ), `PATH`,或 `ffmpeg-static`顺序。 PNG 制作文档的 Dashboard 仅需要铬.

## 常见问题

### @bendyline/docblocks-cli 是什么？

构建、预览、转换、渲染、检查和自动化文档

### 如何安装 @bendyline/docblocks-cli？

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

### @bendyline/docblocks-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bendyline/docblocks-cli 支持 ESM 还是 CommonJS？

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

### @bendyline/docblocks-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.18\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bendyline/docblocks-cli 可以商用吗？

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

### @bendyline/docblocks-cli 的下载量有多少？

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

### @bendyline/docblocks-cli 还在维护吗？

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