@factorialco/shadowdog

中文文档

0.9.6发布于 2026/04/21MITTypeScriptCommonJS构建来源已验证近 30 天下载 7.8万

文档目录17 节

特征
安装
开始 QQ
关键字段
CLI 命令
可用插件QQ
使用插件
MCP 整合
快速设置
可用的 MCP 工具
高级配置
如何缓冲工作
快取密钥计算
关键特性
最佳做法
许可证 QQ
反馈和支持 QQ

暗影狗 🐾

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

特征

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

安装

通过 npm 安装阴影狗 :

npm install shadowdog --save-dev

开始 QQ

阴影狗使用配置文件( S)shadowdog.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提供多种命令来简化工作流程:

生成文物数字 :
```
npx shadowdog
```
监视模式 (包括用于外部工具集成的MCP服务器):
```
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 配置中 :
```
{
  "mcpServers": {
    "shadowdog": {
      "url": "http://localhost:8473/mcp"
    }
  }
}
```
详细的Cursor MCP设置指令见: Cursor MCP 安装指南

使用插件

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

更新您的配置 :

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

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

MCP 整合

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

快速设置

在您的配置中添加 MCP 插件 :

{
  "plugins": [
    {
      "name": "shadowdog-mcp"
    }
  ]
}

以监视模式开始 (MCP服务器自动启动):
```
npx shadowdog --watch
```

配置光标 : 将此添加到您的光标 MCP 配置 :

{
  "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 安装指南

如何缓冲工作

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

快取密钥计算

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

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

关键特性

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

最佳做法

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

许可证 QQ

阴影狗是开源的,可以在 MIT 许可证。。。 .

反馈和支持 QQ

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

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

版本与发布记录

@factorialco/shadowdog 共发布 44 个版本，首次发布于 2024/12/02；过去 12 个月发布了 3 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`0.9.6`latest	2026/04/21	6 个月前
`0.9.3`	2025/12/18	10 个月前
`0.9.2`	2025/12/18	10 个月前
`0.9.1`	2025/11/06	1 年前
`0.9.0`	2025/10/08	1.1 年前
`0.8.6`	2025/10/07	1.1 年前

关于 @factorialco/shadowdog 的常见问题

如何安装 @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 和提交记录判断。

npm install @factorialco/shadowdog

pnpmpnpm add @factorialco/shadowdog
yarnyarn add @factorialco/shadowdog
bunbun add @factorialco/shadowdog

命令行npx shadowdog

在你的项目目录中运行此命令。

近 30 天下载

78,185

约 7.8万次日均 2,606 次

统计周期 2026/10/14 – 2026/11/12
数据来自 npm 官方下载统计，今天更新

最新版本0.9.6发布于 6 个月前

开源许可MIT宽松许可

包体积456 kB80 个文件 · 解压后

运行依赖10 个

模块格式CommonJS

TypeScript自带类型

发布版本44 个近 12 个月 3 个

首次发布2024/12/021.9 年前

元数据更新2026/07/14

每一个软件包背后，
都有分享与创造的人。