continuityguard

ContinuityGuard

安装 • 快速入门 • CLI 参考 • 常见问题 • 参与贡献

本地运行、零网络访问的 CLI，可对已生成的 AI 短剧片段进行评分，检查角色一致性漂移和不符合物理规律的运动，避免浪费渲染额度后才发现问题。

npm install -g continuityguard-cli

AI 短剧生成正当红，每部作品都由一连串单独生成的镜头组成。生成模型仍会出现漂移：角色的脸在剪辑之间略有变化，或者动作出现跳变，让人一看就觉得不符合物理规律。渲染完成后才发现这些问题，代价很高。ContinuityGuard 可以扫描来自任何工作流的已生成片段或帧所在文件夹，并标记值得仔细检查的镜头，让你在决定重新渲染之前及时发现问题。

安装

两个独立发行包地位同等，提供相同的评分逻辑和捆绑的 MobileNetV2 ONNX 模型。两者现已发布并可安装：PyPI 上的 Python 包，以及 npm 注册表上的 TypeScript/npm 包。

Python：

pip install continuityguard-cli

请参阅 python/README.md，了解 Python 专属的快速入门、CLI 参考和库 API。

TypeScript/npm：

npm install -g continuityguard-cli

这会将 continuityguard 命令添加到 PATH 中——运行 continuityguard scan <directory> 即可使用。若要改为从源代码构建（用于本地开发或跟踪 main），请克隆仓库并运行 npm install && npm run build，然后使用 node dist/cli.js scan <directory> 运行 CLI；也可以在本地执行 npm link，以便使用工作副本中的 continuityguard 命令。

功能

• 一次扫描包含两项独立评分。 角色一致性（对同名角色裁剪图像的 MobileNetV2 嵌入进行余弦相似度计算）和物理合理性（根据每个镜头自身的局部基线评估帧间运动不连续性的启发式方法）均可通过单个 scan 命令运行。
• 零网络调用，每次推送都会通过机械化检查。 npm run verify:zero-network 会对 Node 提供的所有网络入口进行猴子补丁，并在 CI 中使用本仓库自带的样例运行真实扫描；若任何代码路径尝试访问网络，它都会立即报错。
• 为人工和工作流提供结构化输出。 同一次扫描会生成易读的终端摘要和完整的机器可读 JSON 报告（--json），让 QA 审核人员和 CI 脚本使用同一结果。
• 普通硬件上运行迅速。 在此次审计期间，于笔记本 CPU 上多次运行 8 个片段的样例扫描（解码、两项评分和报告写入），耗时为 0.53 至 0.63 秒。无需 GPU；评分通过 onnxruntime-node 在 CPU 上运行，使用捆绑的 14MB 模型。
• 每个标记都有可自行核实的原因。 每个被标记的镜头都会显示片段名称、数值分数、超出的阈值，以及通俗易懂的说明；这些信息直接取自 JSON 报告的 reason 字段。

功能

实际输出来自本仓库中已提交的合成测试素材（src/score/testdata/clips/，由 src/score/testdata/generate-fixtures.sh 生成；此版本没有可用的真实短剧素材，因此以下每个数字都可复现，并非示例）：

$ node dist/cli.js scan src/score/testdata/clips

ContinuityGuard v0.1 -- Local Character-Consistency & Physics-QA Scoring

Scanning: src/score/testdata/clips (8 clips, ffmpeg decode)

[SCORED] CG01 Clip Ingestion
  8 clips decoded, 51 frames extracted

[SCORED] CG02 Character-Consistency Scoring
  3 named characters tracked across 8 clips
  1 shot(s) flagged: low cross-shot similarity (below 0.88 cosine threshold)
    kenji_shot02.mp4 -- "kenji" similarity 0.77 vs. reference (kenji_shot01.mp4)
  NOTE: consistency scoring is best-validated on photorealistic content.
  Accuracy on stylized/anime-adjacent character designs is unverified --
  treat flags on stylized content as a prompt for human review, not a
  confirmed defect. See "Known limitations" below.

[SCORED] CG03 Physics-Plausibility Heuristic
  2 shot(s) flagged: frame-to-frame motion discontinuity above threshold
    action-discontinuity.mp4 @ frame 4-5 -- discontinuity 8.25x local baseline
    action-discontinuity.mp4 @ frame 5-6 -- discontinuity 8.32x local baseline
  This is a heuristic proxy, not a physics simulator. It flags shots for
  human review. It does not "detect" a physics violation.

Report written to ./continuityguard-report.json
Human-readable summary above. Use --json for the full structured report.
Scan time: 0.6s. Nothing left this machine. No network calls were made.

在这台机器上多次运行，这次完整扫描（解码、两轮评分和写入报告）耗时 0.6 至 1.4 秒。相同测试素材集中的两组角色一致片段得分很高，且未被标记：mei_shot01.mp4 与 mei_shot02.mp4 的相似度为 0.9975，aiko_shot01.mp4 与 aiko_shot02.mp4 的相似度为 0.9906。刻意设置为不一致的一组片段 kenji_shot01.mp4 与 kenji_shot02.mp4 得分为 0.7709，低于 0.88 的阈值，因此被正确标记。在物理合理性检测方面，calm-baseline.mp4（全程平滑运动）的峰值约为自身局部基线的 1.14 倍，未被标记；而 action-discontinuity.mp4（包含一次刻意设置的突变）达到 8.25 倍和 8.32 倍，高于 3 倍的倍率阈值，因此被标记。以上所有数字均来自上面的命令；完整的原始差异值见 CHANGELOG.md。

每条标记都会附带片段名称、数值评分和通俗易懂的原因，方便你或 QA 审核人员准确了解镜头被标记的原因。

快速开始

git clone https://github.com/RudrenduPaul/ContinuityGuard.git
cd ContinuityGuard
npm install
npm run build

# scan the fixture clips bundled with this repo
node dist/cli.js scan src/score/testdata/clips

# or point it at your own generated-clips folder
node dist/cli.js scan ./generated-clips/ --json > report.json

scan 会遍历目标目录中的视频片段，使用本地 ffmpeg 解码，计算逐镜头角色一致性嵌入和物理合理性启发式评分，并以易读格式和 JSON 格式写入结构化报告。读取或计算的任何内容都不会离开运行它的机器。

CLI 参考

当前已构建 CLI 的实际 --help 输出：

$ node dist/cli.js --help
Usage: continuityguard [options] [command]

Free, local-first CLI that scores already-generated AI short-drama clips/frames
for character-consistency and physics-plausibility problems. Zero network calls.

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  scan [options] <directory>  scan a directory of generated clips for
                              character-consistency and physics-plausibility
                              flags
  help [command]              display help for command

$ node dist/cli.js scan --help
Usage: continuityguard scan [options] <directory>

scan a directory of generated clips for character-consistency and
physics-plausibility flags

Arguments:
  directory     directory of video clips to scan

Options:
  --json        print the full machine-readable JSON report to stdout instead of
                a terminal summary
  --fps <fps>   frame sample rate for ingestion (default: 2.3)
  --out <path>  path to write the JSON report file to (default:
                "./continuityguard-report.json")
  -h, --help    display help for command

为片段命名，以便 CG02 跟踪角色

CG02 根据片段文件名推断所属角色，使用 <character>_<shot-id>.<ext> 约定（例如 mei_shot01.mp4、mei_shot02.mp4）。共享角色前缀的片段会与该角色首次出现的镜头进行比较。AI 短剧工作流中没有行业标准的角色标签元数据格式，因此 ContinuityGuard 目前从文件名读取角色信息，而不要求单独的清单。不符合此命名约定的片段仍会由 CG03 解码并评分，只是不参与角色一致性比较。

MCP 服务

ContinuityGuard 附带一个 Model Context Protocol (MCP) 服务，因此支持 MCP 的 Agent（Claude Desktop、Claude Code 或任何其他 MCP 客户端）可以直接执行扫描，无需你手动调用 CLI。它作为可选附加组件包含在 Python 发行版中：

pip install "continuityguard-cli[mcp]"

将其添加到 MCP 客户端的配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "continuityguard": {
      "command": "continuityguard-mcp"
    }
  }
}

该服务提供一个名为 run 的工具，它会将你传入的参数列表交给实际的 continuityguard CLI 执行，并返回结构化结果（如果命令生成了 JSON，则解析后返回；否则返回原始 stdout/stderr）。所有失败情况——参数错误、缺少 ffmpeg、超时——都会以 {"error": ...} 结果返回，而不会导致服务崩溃。调用示例：

{"tool": "run", "args": {"args": ["scan", "./clips", "--json"]}}

返回的结果与 continuityguard scan ./clips --json 打印的结构化报告相同，位于 result 键下。

已知限制（信任标记前请先阅读）

• 角色一致性评分在写实内容上经过了最充分的验证。 ContinuityGuard 目前使用通用的 ImageNet 预训练视觉相似度嵌入（MobileNetV2；选择该方案的原因见 src/score/models/NOTICE.md）。其在风格化或接近动漫风格的角色设计（这描述了大多数短剧内容）上的准确性确实尚未经过验证。对于风格化画面中的标记，请先仔细检查，再决定是否信任。
• 一致性嵌入衡量的是裁剪画面之间的一般视觉相似度：颜色、纹理和大致形状。 对写实人脸而言，这是有效信号，不过效果不如专用的人脸识别嵌入。在风格化设计上，效果更弱，而且未经验证。
• 物理合理性评分是一种逐帧差异启发式方法。 它会将连续帧之间的运动与镜头自身的局部基线进行比较，并标记异常值供人工审核；它不会尝试模拟现实世界的物理规律。请预期会出现误报（正常的快速运动、风格化跳切）和漏报（未超过阈值的细微不合理运动）。
• 阈值是在一组规模较小、完全合成的测试样例上校准的（纯色片段，没有真实人脸或录制的运动）。具体数值及生成这些数值的命令见 CHANGELOG.md。这是一个真实且可复现的起点，基于两组合成样例校准，而非大型标注数据集。随着收到真实场景的报告，这些数值可能会发生变化。
• <character>_<shot-id> 文件名约定目前是一个简化方案，适用于尚无标准角色标记元数据格式的类别。不符合该约定的片段仍会进行物理合理性评分；只是会跳过一致性比较。
• 需要在系统中安装 ffmpeg。 ContinuityGuard 会在启动时检查是否已安装；如果未安装，会打印适用于你所用操作系统的确切安装命令（例如，在 macOS 上运行 brew install ffmpeg，在 Debian/Ubuntu 上运行 apt install ffmpeg）。目前不会随包捆绑静态 ffmpeg 二进制文件。随包提供各平台构建版本会使其体积远超本项目自身的依赖体积，而且根据编译时包含的编解码器不同，还会受到 ffmpeg 自身不断变化的 LGPL/GPL 许可条款影响。依赖系统安装能让此包保持小巧，许可范围也更简单。
• 固定使用 TypeScript 6.x，尚未升级到 7.x。 TypeScript 7（原生/Go 编译器重写版）移除了对 CommonJS 互操作默认导出的支持，而截至其最新版本（8.66.0），typescript-eslint 的对等依赖范围仍要求该导出形式（其仍声明 typescript: >=4.8.4 <6.1.0）。这不是漏洞，只是整个生态系统的兼容性缺口：整个 typescript-eslint 工具链尚未提供 TS7 支持，因此在它提供支持之前，本项目会继续使用 TypeScript 6.x。

对比

目前没有广泛使用且可直接对比的工具，能够在一个专为审核已生成的 AI 短剧内容打造的零网络 CLI 中，同时结合本地角色一致性评分和物理合理性启发式评估。最接近的真实且经过验证的项目，分别位于更上层（用于评估视频生成模型的学术基准）或更下层（需要自行集成的通用人脸嵌入库）：

项目	Star 数	最近活动时间	许可证	实际用途	对比情况
Vchitect/VBench	1,718	2026 年 3 月	Apache-2.0	CVPR 2024 学术基准套件，从 16 个维度对视频生成模型进行评分，包括基于 DINOv2 的“主体一致性”指标和运动平滑度指标，并对许多生成的视频片段进行汇总	机制上最接近：它同样会对已生成视频的主体一致性和运动质量进行评分。但它是依赖 GPU 的研究基准，用于综合评估生成模型，并非轻量级本地 CLI，无法为创作者自己的素材提供逐片段 QA 报告。
serengil/deepface	23,204	2026 年 6 月	MIT	广泛使用且积极维护的 Python 人脸验证、嵌入和面部属性分析库	用于人脸嵌入相似度的组件库，并非原生支持视频或专为短剧打造的工具。可作为构建模块，但本身不提供物理合理性检查、片段解码功能或打包好的报告格式。
deepinsight/insightface	29,406	2026 年 7 月	仓库中没有统一的机器可读 LICENSE；项目文档说明代码采用 MIT 许可证，但部分预训练模型有非商业用途限制	最先进的 2D/3D 人脸分析工具箱（检测、识别、对齐）	与 DeepFace 属于同一类别：它是组件库，而非端到端 QA CLI。没有物理合理性检查，也没有报告层。
evalcrafter/EvalCrafter	195	2024 年 10 月	未列出	CVPR 2024 研究框架，使用 700 个提示词，从视觉质量、运动质量和文本-视频对齐等方面对视频生成模型进行基准测试	相关研究工具，近两年左右没有提交记录。它旨在通过繁重的多指标研究流程对生成模型进行基准测试，而非对包含已生成片段的文件夹快速执行本地 QA 检查。

上表中的 Star 数和最近活动日期，是撰写本表时通过 GitHub API 实时获取的。

什么是 ContinuityGuard，它为何存在

ContinuityGuard 是一款免费、开源、本地优先的 CLI。它会接收一个目录，其中包含由任意 AI 短剧工作流生成的视频片段，通过 ffmpeg 解码，并进行两轮评分：角色一致性检查（计算不同镜头中同名角色裁剪画面的 MobileNetV2 嵌入向量之间的余弦相似度；已针对写实内容进行最佳验证，对风格化或近似动漫的设计尚未验证）和物理合理性启发式检查（将帧间差异比率与镜头自身的局部运动基线进行比较；这是一种用于标记镜头、供人工审核的启发式方法，并非物理模拟器）。它会生成一份人类可读的终端报告和一份机器可读的 JSON 报告，而且整个过程中绝不会发起网络请求。

它之所以存在，是因为 AI 短剧生成每天都在推出数百部新作品，而每部作品都是由许多单独生成的镜头组成的。生成模型会出现偏差：角色的面部在剪辑切换间会略有变化，运动有时也会突然跳变，让人一看就觉得不符合物理规律。在重新渲染前发现这些问题，可以省下从头重做镜头的成本。

ContinuityGuard 是 QA 层，而非生成器，这正是它的意义所在。它在已有工作流生成的素材之上运行，而不会把你锁定在某个工作流中；它完全在你自己的机器上运行，因此尚未发布的素材无需离开本机；它还是免费的，无需账户或 API 密钥。生成平台自带的 QA（如果有的话）只能检查自身的输出；而无论片段来自开源工作流、商业工作流，还是同一项目中的两者混合，ContinuityGuard 都能以相同方式工作。

始终仅在本地运行

尚未发布的素材绝不会离开你的机器。每个片段都通过 ffmpeg 在本地解码，每个嵌入向量都由随附的离线 ONNX 模型在本地计算，报告也会写入本地文件。任何帧都不需要账户、API 密钥或上传步骤。npm run verify:zero-network 可以通过实测证明这一点：它会对 Node 提供的所有网络入口进行猴子补丁，并使用本仓库自带的测试素材运行真实扫描；如果有任何内容尝试访问网络，它就会明确报错。每次推送时，它都会在 CI 中运行。确切结果请参阅 CHANGELOG.md。

常见问题

这是否已针对动漫或风格化的 AI 生成角色进行验证？ 尚未。角色一致性评分已针对写实内容进行最佳验证。对于风格化或近似动漫的设计（这类设计在短剧内容中占多数），其准确性尚未经过独立基准测试。请将风格化素材中的每一项标记都视为需要仔细检查的提示。这是本仓库中最重要的一项注意事项；请参阅上文的“已知限制”。

物理检查真的理解物理规律吗？ 不理解。这是一种帧间运动不连续性启发式方法。它将每个镜头的帧间差异与该镜头自身的局部基线进行比较，并标记异常值供人工审核，不会尝试模拟现实世界的物理规律。对于合理的快速运动或风格化跳切，它可能会产生误报；对于低于阈值的细微不合理运动，则可能漏报。

我需要 GPU 吗？ 不需要。所有操作都通过 onnxruntime-node 在 CPU 上运行，使用一个体积较小（14MB）的 MobileNetV2 模型。上文提到的 8 个片段测试素材扫描，在普通笔记本电脑上不到两秒即可完成。

它会把我的片段上传到任何地方吗？ 不会。这一点通过机制强制保证：npm run verify:zero-network 会对 Node 提供的所有网络入口进行补丁，并运行真实扫描；如果有任何内容尝试访问网络，检查就会明确报错。每次 CI 推送时都会运行。 为什么需要单独安装 ffmpeg，而不是将它打包进去？ 打包静态 ffmpeg 二进制文件会让此软件包在每个平台上增加数十 MB，并且会受 ffmpeg 自身许可条款约束；根据编译进去的编解码器不同，许可条款会在 LGPL 和 GPL 之间变化。开发者的机器上几乎普遍都已安装 ffmpeg，因此 ContinuityGuard 依赖系统安装，并会在启动时检查；如果缺少 ffmpeg，会显示清晰且针对相应操作系统的错误信息。

现在可以在 npm 上安装了吗？ 可以。现在运行 npm install -g continuityguard-cli 即可安装。Python 软件包也已发布到 PyPI（pip install continuityguard-cli），使用相同的评分逻辑和打包模型——参见 python/README.md。

大型视频生成平台会不会直接把这个功能集成到产品里，让 ContinuityGuard 变得毫无意义？ 有可能，而且本仓库对此直言不讳，没有刻意回避：任何资金充足的视频生成平台都可以原生提供同等的检查功能，因为它本就运行完整的生成流水线，也有直接的动机来避免浪费渲染成本。ContinuityGuard 当前的价值在于免费、本地运行且不依赖特定流水线。这里没有承诺这种情况明天依然如此。

可以在 CI 中使用吗？ 可以。--json 会输出机器可读的报告，供 Agent 或 CI 步骤解析；整个工具无需网络访问即可运行，因此可以像其他本地静态分析步骤一样加入 CI 作业。

支持哪些平台和 Node 版本？ package.json 要求 Node >=22，且未限制操作系统。原生评分依赖项 onnxruntime-node 提供适用于 macOS、Linux 和 Windows 的预构建二进制文件。你还需要安装系统级的 ffmpeg（启动时会检查；如果缺少，则会打印针对相应操作系统的安装命令）。Python 发行版（pip install continuityguard-cli）要求 Python >=3.9，也要求系统安装 ffmpeg，并被归类为 Operating System :: OS Independent。

与使用 deepface 这类人脸嵌入库，而不是通用 ImageNet 模型相比如何？ 两者解决的是同一问题的不同层面。serengil/deepface（采用 MIT 许可，且积极维护）是专门用于人脸验证和嵌入的库；如果你自行将其接入扫描流水线，在角色一致性评分方面可能会比 ContinuityGuard 当前使用的通用 MobileNetV2 嵌入更准确，尤其是面对风格化内容时。ContinuityGuard 的定位并非在嵌入方面胜过专用的人脸嵌入库，而是在其上提供打包好的命令行工具，一条无需联网的命令即可完成 ffmpeg 解码、物理合理性检查，并输出结构化报告。之后换用更强的嵌入模型是一项开放且已跟踪的改进，并非已经实现的功能。完整对比请参阅上文的“对比情况”。

可以免费用于商业用途吗？ 可以。本仓库中的所有内容均采用 Apache 2.0 许可，包括该许可附带的宽松专利授权。没有单独的商业版，没有使用量上限，也不需要许可证密钥。与任何用于商业项目的 Apache 许可依赖项一样，仍须遵守 Apache 2.0 的署名和许可声明要求。

参与贡献

请参阅 CONTRIBUTING.md，了解 TypeScript 软件包（仓库根目录）和 Python 软件包（python/）的本地设置、完整的 PR 前检查清单（lint、typecheck、覆盖率阈值、npm audit、零网络验证脚本）以及样例素材可复现性规则。目前最有价值的贡献，是报告真实（非合成）AI 短剧素材中的误报或漏报，尤其是风格化或近似动漫风格的内容，因为这正是上文提到的缺口。

文档

• docs/getting-started.md -- 两个软件包的安装路径、首次扫描以及库 API。
• docs/concepts.md -- CG01-CG04 各自的作用，以及 0.88 / 3x 阈值的来源。
• docs/integrations/ci.md -- 如何将 ContinuityGuard 接入 CI 工作流。
• python/README.md -- Python 软件包自己的 README（PyPI 快速入门、CLI 参考、保真度说明）。

许可证

此仓库中的所有内容均采用 Apache 2.0 许可证。永久免费，无付费套餐。