# @gitpagedocs/cli 中文文档

规范地址：https://npmcn.com/package/%40gitpagedocs/cli/

版本：0\.0\.26
npm 元数据更新时间：2026-11-09T11:28:33.637Z
中文译文更新时间：2026-11-16T14:51:56.999Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40gitpagedocs/cli
原文对照：https://npmcn.com/package/%40gitpagedocs/cli/?lang=original
项目主页：https://vidigal-code.github.io/git-page-docs/
源码仓库：https://github.com/Vidigal-code/git-page-docs

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

- 包体积（解压后）：1.2 MB，117 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2026-06-14T23:49:57.548Z
- 最新版本发布：2026-11-09T11:28:33.483Z
- 近 30 天下载量：3862（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

CLI 用于脚手架并维护 gitpagedocs 文档,用 AI 生成 docs,配置 GitHub Pages,并运行 MCP 服务器.

## 安装

```sh
npm install @gitpagedocs/cli
```

也可以使用：`pnpm add @gitpagedocs/cli`、`yarn add @gitpagedocs/cli`、`bun add @gitpagedocs/cli`

## README

# @gitpagedocs/cli (英语)

这个 **已发布 npm 软件包** 会 议 日 程 和 议 程 [Git 页面文档](https://npmcn.com/package/%40gitpagedocs/README.md) monorepo(它安装的命令是 `gitpagedocs`) (中文(简体) ). 它使脚手架 `gitpagedocs/` docs合同,用AI生成docs,配置GitHub Pages,并运行MCP服务器.

```bash
npm install -g @gitpagedocs/cli   # global (installs the `gitpagedocs` command)
gitpagedocs                       # generate gitpagedocs/ config (config-only)

# or one-off, no install:
npx @gitpagedocs/cli
```

> 这个软件包载着它的 TypeScript 源头,并通过 `tsx`; 取决于工作空间软件包 `@gitpagedocs/tools` 财务报告和审定财务报表 `@gitpagedocs/mcp` (同时发表).

## 图标

| 命令 | 说明 |
| --- | --- |
| `gitpagedocs` | 生成 `gitpagedocs/` 配置 + 已版本文件( 仅配置) |
| `gitpagedocs --layoutconfig` | 同时在 `gitpagelayouts/` |
| `gitpagedocs --layouts-dir <dir>` | 本地布局文件夹( 默认 ): `gitpagelayouts`(中文(简体) ) |
| `gitpagedocs --no-interactive` 编号 : `-y` | 永不提示; 使用旗帜和默认 |
| `gitpagedocs --push --owner <o> --repo <r> [--path <sub>]` | 生成、配置页面、创建工作流程、承诺+推 |
| `gitpagedocs --home` | 独立分发(`gitpagedocshome/`:静态站点+.env+多克文件) |
| `gitpagedocs -i` 编号 : `--interactive` | 交互式提示 |
| `gitpagedocs ai` | 交互式 AI 文档生成器- 以 gitpagedocs 模式写出页面( 见下文) |
| `gitpagedocs chat [question]` | 在终端中流出AI聊天——TTY上的REPL,一发一发有问题或有管的sdin; `--provider`, (中文(简体) ), `--model`, (中文(简体) ), `--system` (见下文) |
| `gitpagedocs provider [id]` • 妇女 `models [provider]` | 列出 AI 提供者/ 目录模型 |
| `gitpagedocs document[:repo|:file|:folder]` | 以 Gitpagedocs 模式生成文件 |
| `gitpagedocs password` | 设置文档访问密码( 写入公钥为 `config.json`,打印私钥) |
| `gitpagedocs deploy` 编号 : `pages deploy` | 通过动作配置 GitHub 页面, 生成、 承诺和推动 |
| `gitpagedocs pages actions` | 将寄存器的 Pages 源代码切换为 GitHub 动作; 没有生成或推动 |
| `gitpagedocs docs` | 更新经管的 " 研究、监测和评价 " 区域 |
| `gitpagedocs config clear` | 删除已存储 `.gitpagedocsconfig` **财务报告和审定财务报表** 加密密钥金库 `.gitpagedocsvault` (手机保存AI证书) |
| `gitpagedocs doctor` • 妇女 `version` • 妇女 `update` | 诊断/版本/登记册更新检查 |
| `gitpagedocs mcp start` | 通过 stdio 启动 MCP 服务器 |

AI-CLI的实施工作存在于 `cli/ai/` (从前端重新定位,因此所发布的包是自成一体的).

## 生成的文件和主题

0.0 26. 版本登记文件 0.0.26, 0.0.25, 0.0.24, 0.0.23, 0.0.22, 0.0.21, 0.0.20, 0.0.19, 0.0.18, 0.0.17, 0.0.16, 0.0.15, 0.0.14, 0.0.13, 0.0.12, 0.0.11, 0.0.10和 0.0.9, 最新的第一版有英文、葡萄牙文和西班牙文等网页。 保存现有的旧文件夹 。 源内容生活在 `content/`; 默认和用户界面标签存在 `data/`; 在再生前编辑这些源。 已出版的软件包包括英文PDF指南和外部主机DOOM播放器的本地HTML集成.

脚手架包括了第50页中Markdown,HTML,视频,音频和PDF的独立文件平面图,有两个本地化的HTML样本,本地WAV音轨和一个PDF参考. 配置共享控件 `site.containerPagination` 及其路线的每个序列 `pagination.items`。生成的 pagination 和 Markdown 标记指南解释默认值、 路由覆盖、 焦点/ 搜索集成和与文档索引相链接的主题意识亮点. `RouteGuideSpeciFicbrand` 保持其现有的标题过滤行为.

脚手架显示母马克下游目的地有递归子菜单和可通航面包屑、PDF路线/动作,以及一个有命令的、重复的Markdown/HTML/video/audio/PDF块的页面。 路由标题和描述有独立的放置设置. Focus模式提供源动作和8个文档/节导航控制;浏览器解说单独配置. 完整的示例请参见生成的配置,内容块,焦点,可访问性和HTML/PDF指南.

包含JSON在内的有被支持语言的Markdown代码块在文档中使用Shiki语法突出显示,焦点模式,全屏和源查看器预览. 活性主题控制可读的符号颜色和与其周围卡相符合的读取表面,贯穿124个主题. 不支持或未说明的语言仍然是可读的纯文本;非常大的块也可能仍然是纯文本,以使读者保持响应. 复制并下载保存了原有的Markdown.

`gitpagedocs --layoutconfig` 所有124个主题:64个原生主题,20个独立动画预设和20个新增的暗相/光相parlax对. 新的预设来源于 `gitpagelayouts/v2/` 并编入包本地数据 `pnpm run layouts:sync`;独立的 CLI 安装不需要源寄存器来发出它们. 自定义背景通过 `site.backgroundEffects`,包括全局/每个主题设置,颜色,密度,速度和参数. 主切换会禁用背景; `overrides.accessibility.showPauseButton: false` 只隐藏暂停控制 .

`site.icons.VersionSelector` 财务报告和审定财务报表 `BackgroundAnimationPause`编号 :`BackgroundAnimationResume` 使用同样的 `reactIcon`, (中文(简体) ), `tag`, (中文(简体) ), `size`, (中文(简体) ), `colorDark` 财务报告和审定财务报表 `colorLight` 合同作为其他控制。 暂停/重置出现在导航菜单的锁边;在主题和菜单的更改中,手动暂停. `reactIcon: false` 为每个控件独立选择本地化文本.

这个 [MCP 参考](https://npmcn.com/package/%40gitpagedocs/mcp/README.md) 文档安装、客户端配置、全部20个工具和7个资源。 MCP运行于stdio并从其环境中读取提供者证书;它不会自动解锁CLI金库.

## 版本存储器链接

每个 `VersionControl.versions` 接受条目 `branch`, (中文(简体) ), `release` 财务报告和审定财务报表 `commit` 数组 `{ name, url }`。名称支持 Unicode,保留其配置的顺序,并在界面语言变化时保持不变。 遗留的 URL 字符串使用已翻译的分类标签;空分类被隐藏. 支持HTTP(S)和安全的相对URL,不支持的方案和无效条目被省略,一个类别中的确切重复出现一次. 响应的版本链接对话框组按类别链接,滚动长列表内部,遵循主题符并支持键盘导航和逃逸. 本地链接打开新标签 `noopener noreferrer`· ; `site.icons.VersionLinks` 配置触发外观。 参见历史 0.0.16 实例和完整行为配置 .

取景者介绍指南每轮/履带手势修改一章,键盘步骤或垂直刷相,而不会在场景间停止文字. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}分会的铁路选择和回归最高层是立即的 一个标题播放/暂停按钮控制引导效果和主题背景而不替换内容;减少动作偏好总是占上风,一个被禁用的控制解释系统偏好. 英雄从第一个渲染处可见,有可选的小平面平面相抵并简短地揭示出. CLI生成文档;取景器本身由源检出或GitHub Pages构建提供.

扩展视频,音频或HTML在打开和关闭时保存所选文件以及同一播放器或iframe实例. 浏览器在可用时请求本地全屏; Escape 或浏览器控制关闭并同步URL. 如果全屏无法使用或被拒绝,同样的内容会在页面中扩展,没有模式,在扩展区域内设有关闭按钮并进行逃逸处理. Markdown和PDF保持现有的取景行为.

配置这些数组 `gitpagedocs/config.json`,对每个文档版本独立进行。 将条目与您现有的目录合并; 不替换其他版本 。 见 [命名链接示例](https://npmcn.com/package/%40gitpagedocs/README.md#named-links-for-documentation-versions) 对于多个分支,发布和真实承诺的URL. 这个例子 `develop` 分支和所有者/存储器占位符必须替换为您仓库中现有的分支。 这些领域与现有资源有关;国家领导学院不设立、承诺或释放这些分支.

## 包装和释放

根和前端的工作空间是私有的. 公共软件包 `@gitpagedocs/tools`, (中文(简体) ), `@gitpagedocs/mcp` 财务报告和审定财务报表 `@gitpagedocs/cli`;它们的版本,内部范围和锁文件必须同意. npm工作流程检查了一个新的CLI版本,安装了被冻结的锁文件,运行打字检查并签约自试,再发布工作空间. GitHub Pages 在其单独的工作流程中构建取景器. 两个工作流程都没有自动创建 GitHub 发布注释或标记.

软件包允许列表包括它的源,模板,数据和资产. `prebuilt/` 是可选的,不是由 npm 工作流程创建的。 只配置命令生成寄存器数据而不启动服务器 。 在公布前全面检查和检查包件内容;核查公布的包件并随后部署现场.

# CLI 架构 (清代建筑+ SOLID)

## 图层概览

```
cli/
|-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
|-- package.json                       # the published `gitpagedocs` package
|-- ai/                                # AI CLI: docs generator + terminal chat
|   |-- application/                   # run-ai-cli-command, resolve-chat-credentials, ai-credentials (seal/unseal), vault-password
|   |-- infrastructure/                # ai-config-file (.gitpagedocsconfig), ai-key-vault (.gitpagedocsvault), file-system-adapter, version-docs-writer
|   |-- core/                          # chat-session, config models + parser
|   `-- presentation/                  # @clack prompts (ai-prompts, vault-prompts)
|-- contracts/                         # Stable contracts for external tooling
|   `-- doc-versions.mjs
|
|-- presentation/                      # Interface/composition root
|   |-- index.ts
|   |-- commands/                      # chat, config-clear, config-info, docs, pages, password, mcp, diagnostics, ai-info
|   |-- options/
|   `-- ui/
|
|-- application/                       # Use-cases and ports
|   |-- config-only/handler.mjs
|   |-- home/handler.mjs
|   |-- report/config-only-reporter.mjs
|   |-- use-cases/dispatch-mode.ts
|   `-- ports/cli-runtime-ports.ts
|
|-- domain/                            # Business rules
|   `-- services/sanitize-segment.mjs
|
|-- infrastructure/                    # Side effects and adapters
|   |-- config-only/runtime.mjs
|   `-- home/runtime.mjs
|
|-- builders/                          # Pure config builders
|-- data/                              # Constants and metadata
|-- content/                           # Static docs content
|-- runtime/                           # Low-level runtime helpers
`-- home/                              # Home templates/files
```

## 固态原则

| 原则 | 应用 |
| --- | --- |
| **退休方案** | `application/report` 只有格式消息; 处理器只管弦 |
| **办公室** | 可通过端口注入新的运行时间执行 |
| **LSP 软件** | `dispatch-mode` 与任何执行者合作 `CliCommandRunner` |
| **ISP (英语)** | 拆分运行时间合同`ConfigOnlyRuntimePort`, (中文(简体) ), `HomeRuntimePort`(中文(简体) ) |
| **投资部** | 使用大小写取决于 `application/ports`,而不是混凝土 fs/git/exec |

## 清洁建筑

-   **接口/介绍**: 解析 CLI 参数,解析模式,线的依赖性 `presentation/index.ts`
-   **应用**:与明确端口协调流动,不直接进口fs/git/exec
-   **域名**:无基础设施依赖的净化和核心规则
-   **基础设施**: 用于运行时副作用的混凝土适配器
-   **合同**数字 : `tools/smoke` 消耗量 `cli/contracts` 而不是内部CLI模块

## 授权路线管道

目前CLI在PT/EN/ES中生成授权的路由道克和配置项.

-   资料来源: `cli/content/docs.mjs` (单位:千美元)`authorizedRoutes` 每种语言的密钥)
-   路由元数据 : `cli/data/route-metas.mjs` (单位:千美元)`ROUTE_META_ID6`(中文(简体) )
-   路径映射 : `cli/data/path-mappings.mjs` (单位:千美元)`authorized-routes.md`(中文(简体) )
-   版本配置组成 : `cli/builders/version-config-builder.mjs`
-   文件密钥解析度 : `cli/runtime/doc-path-resolver.mjs`

出产的文物包括:

-   `gitpagedocs/docs/versions/<version>/config.json` 与 `auth` 和路线 `authorization`
-   `gitpagedocs/docs/versions/<version>/{pt,en,es}/authorized-routes.md`
-   `menus-header-md` 专用指定路线的条目

## GitHub 页面推动路径

-   默认项目站点发布( E)`--push` 无 `--path`目标 `/<repo>/`。 。 。 .
-   自定义工程子路径发布( O)`--push --path <segment>`目标 `/<repo>/<segment>/`。 。 。 .
-   `--path` 接受单一的消毒部分(字母、数字、, `.`, (中文(简体) ), `_`, (中文(简体) ), `-`) (中文(简体) ).

示例

```bash
npx @gitpagedocs/cli --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
```

部署后预期的 URL :

```text
https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/
```

## AI CLI( 交互 + 配置文件)

CLI现在包括一个专门的交互式AI模式:

```bash
npx @gitpagedocs/cli ai
```

### 它会做什么

-   向共享目录提供供应商(14个供应商,包括OpenAI、Anthropic、双子座和Ollama)
-   询问 API 密钥或 Ollama URL
-   询问扫描路径( 支持一条或多条路径, 包括其它寄存器)
-   生成文档 `pt`, (中文(简体) ), `en`, (中文(简体) ), `es` **在gitpagedocs图案中**
-   可选持续配置于 `.gitpagedocsconfig`在加密中封存 API 密钥 保险库 `.gitpagedocsvault` (第一次使用时创建的默认密码, 每次运行时都会询问)

### gitpagedocs 模式输出

该模型被赋予了gitpagedocs-aware系统即时,返回文档被分割为 页面( 以 `=== PAGE: <slug> | <Title> ===`) (中文(简体) ). CLI的脚手架 `gitpagedocs/` 结构,然后将每个页面写入 `gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md` 对每种语言和 **把它接进 那个版本 `config.json`** (单位:千美元)`routes-md` + 键 `menus-header-md`因此,页面在 查看器菜单 。 条目被标记 `aiGenerated` 和能干的, A 类 后为平原 `gitpagedocs` 重建 放下线条——重运行 `gitpagedocs ai` 来恢复.

### `.gitpagedocsconfig` (手动模式)

文件生活在每个用户的OS配置目录中(从未在寄存器内,所以) aPI 密钥不能意外执行),并且只写所有者 pOSIX 系统中的权限 :

-   窗口 : `%APPDATA%\gitpagedocs\.gitpagedocsconfig`
-   马可斯: `~/Library/Application Support/gitpagedocs/.gitpagedocsconfig`
-   林纳: `$XDG_CONFIG_HOME/gitpagedocs/.gitpagedocsconfig` (或 `~/.config/gitpagedocs/.gitpagedocsconfig`(中文(简体) )

设定 `GITPAGEDOCS_CONFIG_DIR` 以覆盖目录; 删除存储的文件, 保险库及其证书 `gitpagedocs config clear`。此示例描述 已保存的配置,其密钥已经存在于加密金库中。 编辑其非机密 设置然后运行 `npx @gitpagedocs/cli ai`。对于新安装,运行交互式 首先设置;如果没有密钥,则减少配置再利用并输入证书.

```json
{
    "version": 1,
    "ai": {
        "provider": "openai",
        "apiKeyEncrypted": true,
        "paths": ["src", "cli", "../another-repo/src"],
        "languages": ["pt", "en", "es"],
        "outputDir": "gitpagedocs/docs",
        "filePrefix": "ai-generated",
        "contextPrompt": "Write clear technical documentation for this project."
    }
}
```

**API 密钥不在此文件中 .** 保存配置将密钥封入 加密金库 `.gitpagedocsvault` 在同一目录中 (`cli/ai/infrastructure/ai-key-vault.ts` 结束 `EncryptedCredentialVault` + 键 `FileVaultStorage` 从 `@gitpagedocs/tools`: AES-256-GCM,密钥 从您的密码中取出 PBKDF2-HMAC-SHA-256, 210k 迭代),配置只保留 `"apiKeyEncrypted": true`。 。 。 .

-   这个 **第一次使用时创建了金库密码** (键入两次,至少4个字符)和 **每次跑步都询问** 联 合 国 `gitpagedocs ai` 编号 : `gitpagedocs chat` 使用存储的密钥 (3次尝试,然后运行中止使用 `Vault password rejected`) (中文(简体) ).
-   `GITPAGEDOCS_VAULT_PASSWORD` 提供没有提示的密码( CI, 管道, 无 TTY ); 在第一次运行时,它会初始化金库, 否则它必须与现有的金库匹配.
-   简单文字 `"apiKey"` 由0.0.1所写被封入金库并取出文件 何时 `ai` 或者说 `chat` 重新使用该配置并用金库密码解锁.
-   如果您手写文件, 请将密钥留出: 请在 `gitpagedocs ai` 提示( 这是 保存时被封存). `gitpagedocs chat` 也可以读取提供者的环境变量 (单位:千美元)`gitpagedocs provider <id>` 当没有密钥存储时.

对奥拉马来说,使用 `baseUrl` 而不是 API 密钥( 不涉及金库) .

### `gitpagedocs chat`

```bash
gitpagedocs chat                                  # REPL on a TTY: /clear · /help · /exit (or Ctrl+C twice)
gitpagedocs chat "what does cli/ai do?"           # one-shot answer, then exit
git diff | gitpagedocs chat "review this diff"    # piped stdin is appended to the question
gitpagedocs chat --provider gemini --model gemini-2.5-pro --system "Answer in Portuguese" "..."
```

全权证书按下列顺序解决: `--provider`编号 :`--model` 标记, 存储 `.gitpagedocsconfig` (其密钥在金库密码提示后解密,或从 `GITPAGEDOCS_VAULT_PASSWORD`),然后是提供者的环境变量. 输出流到 状态行去取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.

### 交互倒计时

如果找不到目录, CLI 则提供倒置选择 :

-   修补路径并重试
-   跳过缺失路径并继续
-   安全终止

## 常见问题

### @gitpagedocs/cli 是什么？

CLI 用于脚手架并维护 gitpagedocs 文档,用 AI 生成 docs,配置 GitHub Pages,并运行 MCP 服务器\.

### 如何安装 @gitpagedocs/cli？

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

### @gitpagedocs/cli 支持 TypeScript 吗？

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

### @gitpagedocs/cli 支持 ESM 还是 CommonJS？

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

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

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

### @gitpagedocs/cli 可以商用吗？

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

### @gitpagedocs/cli 的下载量有多少？

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

### @gitpagedocs/cli 还在维护吗？

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

