# @factorialco/shadowdog 中文文档

规范地址：https://npmcn.com/package/%40factorialco/shadowdog/

版本：0\.9\.6
npm 元数据更新时间：2026-07-14T10:38:44.730Z
中文译文更新时间：2026-11-14T08:26:51.902Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：456 kB，80 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2024-12-02T12:24:14.255Z
- 最新版本发布：2026-04-21T09:49:25.534Z
- 近 30 天下载量：78185（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 3 个）

## 中文简介

![drawing](https://raw.githubusercontent.com/factorialco/shadowdog/refs/heads/main/logo.png)

## 安装

```sh
npm install @factorialco/shadowdog
```

也可以使用：`pnpm add @factorialco/shadowdog`、`yarn add @factorialco/shadowdog`、`bun add @factorialco/shadowdog`

## README

# 暗影狗 🐾

![drawing](https://raw.githubusercontent.com/factorialco/shadowdog/refs/heads/main/logo.png)

**阴影狗** 用于生成您项目中文件的衍生进程 。 无论是需要生成静态资产,预编译资源,还是任何其它变换,"影子狗"凭借其超充电功能设定使其变得容易而强大.

## 特征

-   **弹性输入检测 :** 自动检测仅更新的文件和进程的变化.
-   **配置管:** 使用直观的 JSON 配置文件定义手工艺品生成工作流程 .
-   **插件支持 :** 以自定义或社区所建插件扩展功能 .
-   **闪亮快能 :** 优化速度,即使有大型的储存库.
-   **监视模式 :** 当源文件改变时自动再生出文物.

* * *

## 安装

通过 npm 安装阴影狗 :

```bash
npm install shadowdog --save-dev
```

* * *

## 开始 QQ

阴影狗使用配置文件( S)`shadowdog.json`)定义出产文物的工作流程. 以下是一个例子:

```json
{
  "$schema": "https://raw.githubusercontent.com/factorialco/shadowdog/refs/heads/main/schema.json",
  "plugins": [],
  "watchers": [
    {
      "files": ["example.txt"],
      "commands": [
        {
          "artifacts": [
            {
              "output": "example.output.txt"
            }
          ],
          "command": "cp example.txt example.output.txt"
        }
      ]
    }
  ]
}
```

### 关键字段

-   **`$schema`**:为配置提供计划验证.
-   **`plugins`**:用于扩展Shadowdog功能的插件名阵列.
-   **`watchers`**: 定义触发文物生成命令的文件监视器.
    -   `files`:要监视的文件路径或 glob 模式的阵列.
    -   `commands`: 检测到变化时执行的命令.
        -   `artifacts`:指定命令生成的输出文件.
        -   `command`:要运行的 shell 命令.

* * *

## CLI 命令

Shadowdog提供多种命令来简化工作流程:

-   **生成文物**数字 :
    
    ```bash
    npx shadowdog
    ```
    
-   **监视模式** (包括用于外部工具集成的MCP服务器):
    
    ```bash
    npx shadowdog --watch
    ```
    

* * *

## 可用插件QQ

使用这些强大的插件增强阴影狗:

-   **`shadowdog-local-cache`** 实施局部缓存机制,加快重复出产文物.
    
    环境变量:
    
    -   `SHADOWDOG_DISABLE_LOCAL_CACHE`: 当 `true`,完全禁用本地缓存
    -   `SHADOWDOG_LOCAL_CACHE_READ`: 设定时, 超过插件的读取缓存配置(`true`编号 :`false`(中文(简体) )
    -   `SHADOWDOG_LOCAL_CACHE_WRITE`: 设定时, 覆盖插件的写入缓存配置( W)`true`编号 :`false`(中文(简体) )
    -   `SHADOWDOG_LOCAL_CACHE_PATH`: 设定时, 覆盖插件的缓存目录路径
-   **`shadowdog-remote-aws-s3-cache`** 为分布式工作流程启用 AWS S3 远程缓存 .
    
    环境变量:
    
    -   `SHADOWDOG_DISABLE_REMOTE_CACHE`: 当 `true`,完全禁用远程缓存
    -   `SHADOWDOG_REMOTE_CACHE_READ`: 设定时, 超过插件的读取缓存配置(`true`编号 :`false`(中文(简体) )
    -   `SHADOWDOG_REMOTE_CACHE_WRITE`: 设定时, 覆盖插件的写入缓存配置( W)`true`编号 :`false`(中文(简体) )
    -   `SHADOWDOG_REMOTE_CACHE_EXTRA`: 设定时, 在 S3 中的缓存密钥中添加额外信息
    -   `AWS_PROFILE`: 用于认证的 AWS 配置文件( 可选)
    -   `AWS_ACCESS_KEY_ID`: AWS 访问密钥 ID(如果未设置 AWS PROFILE 则需要)
    -   `AWS_SECRET_ACCESS_KEY`: AWS 秘密访问密钥(如果AWS PROFILE没有设置则需要)
    -   `AWS_REGION`: AWS 区域(如果 AWS PROFILE 未设置则需要)
-   **`shadowdog-tag`** 添加标记能力以过滤特定命令.
    
    环境变量:
    
    -   `SHADOWDOG_TAG`: 设定时, 只运行带有匹配标记的命令
-   **`shadowdog-lock`** 生成 a `shadowdog-lock.json` 用于跟踪可复制建筑的文物元数据和依赖性的文件.
    
    锁文件包括:
    
    -   用于生成的阴影犬版本
    -   环境一致性节点.js版本
    -   艺术缓存标识符和文件清单
    -   以通配符扩展查看的文件
    -   用于无效的环境变量值
    -   每件文物的命令细节
    
    特征 :
    
    -   **决定性输出**: 所有阵列都被排序为一致的锁定文件
    -   **部分更新**: 在监视模式下只更新已更改的文物
    -   **种族状况安全**: 处理同时执行的任务
    -   **通关卡支持**: 扩展文件模式, 如 `src/*.ts` 自动
    -   **相对路径**: 所有文件路径相对于工程根
-   **`shadowdog-git`** Handles git 重置和合并 平稳地拖住监视器,并在重置完成后恢复.
    
    内部配置 :
    
    -   检查每2000ms( INTERVAL TIME)
    -   用途 `.git/rebase-merge` 以检测再基准状态
-   **`shadowdog-socket`** 提供与"阴影狗"互动的外部通信通道.
    
    无可配置的环境变量 。 使用套接字事件 :
    
    -   `CHANGED_FILE`: 文件更改时发送
    -   `ERROR`: 错误时发送
    -   `INITIALIZED`: 启动时发送
    -   `CLEAR`: 清除后发送
-   **`shadowdog-tree`** 在命令之间生成一个依赖树结构来运行相互依赖的不同命令.
    
    无可配置的环境变量 。 使用内部依赖图算法.
    
-   **`shadowdog-rake`** 优化多个 `bundle exec rake` 命令为单一命令.
    
    无可配置的环境变量 。 自动检测和组合雷克任务.
    
-   **`shadowdog-mcp`** 为外部工具(如Cursor AI)提供模式上下文协议(MCP)服务器,与Shadowdog程序互动.
    
    环境变量:
    
    -   `SHADOWDOG_MCP_PORT`: MCP 服务器的 HTTP 端口( 默认 ): `8473`(中文(简体) )
    -   `SHADOWDOG_MCP_HOST`: MCP 服务器的 HTTP 主机( 默认 : `localhost`(中文(简体) )
    
    可用的 MCP 工具 :
    
    -   `pause-shadowdog`:在监视模式中暂停阴影狗,以防止在代码更改时生成文物(与守护进程适当结合)
    -   `resume-shadowdog`: 暂停后恢复阴影狗( 与守护进程适当整合)
    -   `get-artifacts`: 获取所有文物的信息, 包括状态、 上次更新时间及相关文件
    -   `compute-artifact`: 使用与守护进程相同的任务运行器和中间软件生成特定文物
    -   `get-shadowdog-status`: 获取阴影狗的现状, 包括守护进程可用性和配置摘要
    
    **连接**: HTTP 结束点 `http://localhost:8473/mcp` (可通过环境变量配置)
    
    **光标集成**数字 : 要与光标连接,请将此添加到您的 MCP 配置中 :
    
    ```json
    {
      "mcpServers": {
        "shadowdog": {
          "url": "http://localhost:8473/mcp"
        }
      }
    }
    ```
    
    详细的Cursor MCP设置指令见: [Cursor MCP 安装指南](https://cursor.com/docs/context/mcp/install-links)
    

### 使用插件

要使用插件,请添加到 `plugins` 区域 `shadowdog.json` 配置文件 。 例如:

更新您的配置 :

```json
{
  ...
  "plugins": [
    {
      "name": "shadowdog-local-cache",
    },
    {
     "name" : "shadowdog-tree"
    }
  ]
  ...
}
```

考虑到插件的顺序很重要. 插件将按照配置文件中定义的顺序执行.

* * *

## MCP 整合

Shadowdog包括一个内置的模型上下文协议(MCP)服务器,允许Cursor等AI工具在程序上与你的构建系统交互. MCP服务器在您在监视模式下运行"阴影狗"时自动启动.

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=shadowdog&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojg0NzMvbWNwIn0%3D)

### 快速设置

1.  **在您的配置中添加 MCP 插件 :**
    
    ```json
    {
      "plugins": [
        {
          "name": "shadowdog-mcp"
        }
      ]
    }
    ```
    
2.  **以监视模式开始** (MCP服务器自动启动):
    
    ```bash
    npx shadowdog --watch
    ```
    
3.  **配置光标 :** 将此添加到您的光标 MCP 配置 :
    
    ```json
    {
      "mcpServers": {
        "shadowdog": {
          "url": "http://localhost:8473/mcp"
        }
      }
    }
    ```
    

### 可用的 MCP 工具

一旦连接, 您可以在 Cursor 中使用这些工具 :

-   **`pause-shadowdog`** - 代码更改期间暂停文物生成(与守护进程适当结合)
-   **`resume-shadowdog`** - 改变后恢复生产文物(与守护进程适当结合)
-   **`get-artifacts`** - 查询文物状况和信息
-   **`compute-artifact`** - 利用与守护进程相同的任务执行器,按需生成特定文物
-   **`get-shadowdog-status`** - 检查"阴影狗"当前状态和守护进程可用性

### 高级配置

-   **自定义端口**设置 `SHADOWDOG_MCP_PORT=9000` 以使用不同的端口
-   **自定义主机**设置 `SHADOWDOG_MCP_HOST=0.0.0.0` 允许外部连接

详细的Cursor MCP设置指令见: [Cursor MCP 安装指南](https://cursor.com/docs/context/mcp/install-links)

* * *

## 如何缓冲工作

暗道克使用精密的掘出系统来确定何时需要再生出文物. 了解如何计算缓存密钥对于优化工作流程至关重要.

### 快取密钥计算

缓存标识符使用 `computeCache` 函数,生成基于下列因素的决定性散列:

1.  **文件内容**:所有被观看的文件都读取,其内容包含在散列中
2.  **文件路径**: 绝对文件路径用于环境之间的一致性
3.  **环境变量**: 只包含指定的环境变量
4.  **命令**: 准确的命令字符串被散列
5.  **阴影狗版本**: 确保当Shadowdog更新时缓存无效

### 关键特性

-   **决定性**: 相同的输入总是产生相同的缓存密钥
-   **排序的文件**: 文件路径按字母顺序排序,以便保持一致
-   **扩展通配符**: Glob 模式像 `src/*.ts` 在散心前扩展
-   **环境意识**: 只有指定的环境变量影响缓存
-   **版本敏感**: 当 Shadowdog 版本更改时缓存无效

### 最佳做法

-   **使用特定文件模式**: 避免可能包含不想要的文件的过于宽泛的拼贴图案
-   **环境变量**: 只包含实际影响您构建进程的变量
-   **文件组织**: 为更好的缓存效率, 将相关文件保存在一起
-   **版本披针**: 使用CI/CD中特定的"阴影狗"版本来再生构建

* * *

## 许可证 QQ

阴影狗是开源的,可以在 [MIT 许可证](https://npmcn.com/package/%40factorialco/shadowdog/LICENSE)。 。 。 .

* * *

## 反馈和支持 QQ

如果你遇到任何问题,有问题,或想建议特征,请打开一个问题或加入讨论.

* * *

享受艺术品的生成, **超充电**!

## 常见问题

### 如何安装 @factorialco/shadowdog？

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

### @factorialco/shadowdog 支持 TypeScript 吗？

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

### @factorialco/shadowdog 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @factorialco/shadowdog 可以商用吗？

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

### @factorialco/shadowdog 的下载量有多少？

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

### @factorialco/shadowdog 还在维护吗？

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