Jianying Headless 公开源码范围与分发边界:收录/不收录清单、授权分层与可验证的发布防护

原创2026-09-23 18:32:132,191 阅读
文章标签:AI 应用AI 技能音视频

Jianying Headless 公开源码范围与分发边界:收录/不收录清单、授权分层与可验证的发布防护

本文是 jianying-headless 仓库《公开源码范围与分发边界》的技术化展开。该仓库是一个面向剪映专业版 macOS 的本地自动化工具,通过结构化剪辑计划生成可编辑草稿、在独立副本中编辑多轨工程并调用本机剪映引擎导出 MP4。本文基于官方文档与仓库源码,系统梳理"收录什么、不收录什么、为什么公开源码不等于开放授权"的完整边界,并给出可复现的边界核验方法,帮助读者在合规、可溯源的前提下正确使用这份源码预览。

一、为什么需要一份"分发边界"文档

jianying-headless 的核心流程是 素材与剪辑计划 → 可编辑剪映草稿 → 原生引擎导出(见 README.md)。它直接操作剪映专业版(主适配版本 11.5.0,兼容 11.4.2)的草稿编解码与原生导出能力,因此源码可见性与法律、商业层面的授权是两个完全不同的维度。原文档开篇即给出四条前提,这也是理解整个仓库的入口:

  • 核心项目已获明确授权并设为公开;Skill 入口另收录到公开的 mcncarl/yichen-skills 总仓库;
  • 源码可见不等于官方集成许可、商业授权或跨设备可用性认证;
  • 11.5.0 适配的本地验证不代表已经推送或发布新 Release;
  • 干净机器的安装验收尚未完成(project.json 中 clean_machine_acceptance: "not-completed" 与之一致)。

这套表述的逻辑是:仓库以"源码预览(source-available preview)"的形式公开,作者按本次请求与授权放行了特定范围,但公开动作本身不自动扩展授权、不自动批准后续发布动作。

二、收录范围:随源码公开的五类内容

原文档将"收录"归纳为以下四类,结合仓库目录结构可以逐项对应:

1. 核心引擎代码

当前无界面草稿、时间线编辑、资源校验、关键帧、蒙版、转场、视觉效果和导出代码。

对应 engine/ 目录下的 Python 实现,包括:

能力 实现文件
草稿构建主入口 engine/jy14_headless.py、engine/headless_runtime.py
资源校验与身份哈希 engine/native_resources.py、engine/native-resource-catalog.json
关键帧 / 蒙版 / 转场 / 视觉效果 engine/native_motion.py、engine/native_effects.py、engine/native_visual_effects.py
独立副本编辑 engine/native_edit.py
原生导出 engine/native_export.py、engine/native_export.cpp
复合片段(实验性) engine/native_compound.py、engine/compound-blueprint.json
版本身份配置 engine/runtime_profiles.py

2. 桥接与文件快照源码

当前入口实际需要的草稿编解码、文件快照和目录锁定源码。

对应 bridge/ 目录:

3. 结构蓝图、测试与构建脚本

脱敏后的结构蓝图、资源身份/哈希目录、测试、独立 Skill、构建脚本和声明。

4. 四份 IG 案例演示衍生件(精确白名单放行)

本次明确授权的 IG 案例演示:docs/media/ 中两份视频预览和两份抽帧图,按精确路径、大小和 SHA 放行;来源与处理见该目录说明。

这是"按字节放行"的典型: docs/media/README.md 逐文件给出内容与处理方式,而 tools/check_package.py 中的 PUBLIC_MEDIA 字典把"精确路径 + SHA-256 + 字节大小"三要素硬编码为白名单:

docs/media/hypit-original-frames.png  (0e7b55e8…, 947936)
docs/media/jianying-import-frames.png (64d1a63d…, 884490)
docs/media/hypit-original-preview.mp4 (0ac79c18…, 4421052)
docs/media/jianying-import-preview.mp4(ccaf3850…, 4223556)

代码注释明确写着"Never turn this into a general media extension allowance"——即这份白名单绝不泛化为通用媒体放行规则。配套测试 tests/test_public_media.py 用 4 个用例锁死边界:

  • test_all_reviewed_bytes_match:白名单内文件字节与哈希必须完全一致;
  • test_modified_media_rejected:改动末尾一个字节即报 bytes differ;
  • test_unlisted_media_rejected:白名单外的媒体文件在 source_files() 检查中报 Unexpected source type;
  • test_symlink_rejected_even_with_valid_target:即使符号链接指向合法文件也拒绝(防止绕过路径白名单)。

这两份文件共同回答了"这份发布到底放行了哪些媒体"——只有上述四份衍生件,且不允许任何形式的内容替换或链接逃逸。

三、不收录范围:五类明确排除的内容

原文档的"不收录"是理解本仓库边界的另一半,逐条对应仓库现实:

  1. 剪映安装包、官方动态库、内置字体、效果包、缓存音效和 GPU 编译缓存——运行时需要的这些组件必须由使用者本机安装的剪映提供,仓库不携带任何官方二进制;
  2. 真实视频、音频、用户草稿、原生账号资料、bookmark、Cookie、Token、密钥或带签名 URL——除四份已授权演示衍生件外一概不收录。这一条在 tools/check_package.py 的 PATTERNS 正则里得到执行:personal-home-path、private-key、github-token、signed-url 四类隐私模式会在源码检查中被拒绝;
  3. 历史实验输出、原始截图/日志、旧版本已登记在线音效的专用变更流程——例如 docs/VERIFICATION.md 中反复出现的 work/ 忽略目录(work/acceptance-1150/、work/hypit-case-20260919/ 等)只保留在本机证据层,不进入源码分发;
  4. 已编译的本项目 codec——bridge/jy14_codec_hardened_11_4 不在仓库中;使用者从源码在本机重建(见第五节),重建产物仍必须满足原有固定哈希 b6533eb5…f971d(定义于 bridge/SOURCE_MANIFEST.json 与 tools/build_native_codec.py 的 EXPECTED_CODEC_SHA)。

此外,原文档特别声明:旧资料只从此次发布范围排除,原始目录仍保留;不会为了发布而删除开发历史或上游声明。也就是说,"不收录"是发布动作的取舍,不是对开发历史的销毁。

四、codec 源码可重建但二进制不随分发

"源码在、二进制不在"是这份分发边界中最容易被误解的一点,值得展开:

  • bridge/SOURCE_MANIFEST.json 记录了三份桥接源码的固定 SHA(jy14_codec.cpp、EncryptUtil.h、runtime_io.py),并给出 expected_codec_sha256: b6533eb5…f971d;
  • tools/build_native_codec.py 的构建流程依次:校验平台为 Apple Silicon macOS(Darwin + arm64)→ 校验 Python ≥ 3.9 → 校验桥接源码哈希 → 读取本机 /Applications/VideoFusion-macOS.app 的 Info.plist 与 libvideoeditor.dylib → 用 xcrun clang++ 编译 jy14_codec.cpp 并链接本机已安装库 → 对编译产物做 SHA-256 比对,不匹配即停止、不改动运行时 pin;
  • 脚本同时执行 codesign --verify --deep --strict 与 Team ID 校验(TeamIdentifier=X2JNK7LY8J),并输出 network_called: false、app_modified: false、official_library_copied: false 三个审计字段,表明整个重建过程不联网、不修改剪映官方程序、不复制官方库;
  • 若 bridge/jy14_codec_hardened_11_4 已存在,脚本会先验证其哈希与可执行位,确认"已存在且合法"才直接报告 already-valid,绝不覆盖未知文件。

原文档说"使用者从这里的源码在本机重建,输出仍必须满足原有固定哈希",含义正是:官方不随源码分发编译好的 codec,但源码级可复现性通过固定哈希被强制保证——这与 docs/VERIFICATION.md 中"SHA-256 与原有已验二进制完全一致 b6533eb5…f971d"的记录相互印证。换个编译器或 SDK 导致输出不同,也会被固定哈希拒绝,这正是 bridge/SOURCE_MANIFEST.json 中 other_toolchains: not-accepted-unless-output-matches-the-existing-pinned-hash 的含义。

五、开源与授权:四个不同层面的约束

原文档用一句话点破了本仓库最容易被误读的地方:代码许可证、剪映用户协议、素材许可、账号权益是不同层面的约束。具体拆开:

  1. 原创代码:采用根目录 LICENSE 的 "Personal Learning and Non-Commercial Use License"——允许个人学习、研究和非商业个人工作流使用;商业使用须取得作者明确书面授权(联系渠道见 LICENSE 文本,本文不展开);
  2. 第三方内容:保留各自原许可,licenses/ 与 THIRD_PARTY_NOTICES.md 中的文本不等于把剪映及其资源授予同样的许可;
  3. 剪映官方程序库、账号权益与素材许可:不随源码分发,也不被代码许可证覆盖;
  4. 打包定性:不应把本预览称为 MIT / Apache-2.0 的整包开源项目——尽管 licenses/ 目录保留了相关文本(如 pyJianYingDraft-0.3.0-Apache-2.0.txt),但那只是对上游依赖的声明,不是对本仓库整包授权的认定。

六、Skill 的收录边界与入口锁定

原文档说明"Skill 入口另收录到公开的 mcncarl/yichen-skills 总仓库",且总仓库只收录本 Skill 的说明、调用入口与口播辅助脚本,不收录核心引擎代码或官方资源。仓库内对应 skills/yichen-jianying-edit/:

  • 入口脚本 skills/yichen-jianying-edit/scripts/headless_draft.py 是一个纯 pin 校验层:它先通过 project.json 标记(id == 'jianying-headless' 且 schema == 'jianying-headless-project/v1')定位已检出的核心项目,再对 engine/ 下 14 个核心文件逐一比对 PINS 字典中的 SHA-256,任何文件缺失、为符号链接或哈希不符都会直接 SystemExit;
  • 这意味着 Skill 本身不携带引擎:独立安装后必须通过 export JIANYING_HEADLESS_ROOT="/absolute/path/to/jianying-headless" 指向已检出的核心项目,否则入口拒绝运行——这是"Skill 不包含引擎"的源码级落实;
  • 同时 tools/check_package.py 会交叉校验 PINS、IO_MANIFEST_SHA(engine/headless_runtime.py 中 pin 的 bridge/SOURCE_MANIFEST.json 哈希)与 CATALOG_SHA(engine/native_resources.py 中 pin 的资源目录哈希),形成"入口 → 引擎 → 桥接清单 → 资源目录"的完整锁链。

七、发布动作的边界:验证通过 ≠ 已发布

原文档最后强调:后续推送、新建公开目标或 GitHub Release 按本次请求和实际授权执行;历史公开授权不自动批准新的发布动作,且"不同机器的安装验收仍未完成"。

这一约束在仓库中同样有据可查:

  • project.json 声明 version: 0.2.0-preview、native_app_distributed: false、native_resources_distributed: false、clean_machine_acceptance: not-completed;
  • docs/VERIFICATION.md 将 2026-09-19 的 11.5.0 主版本实测与 2026-09-15 的历史源码包装预览严格分节,明确"代码、版本配置和已安装 Skill 已更新;本次不发布 Release";
  • 同一文档的边界清单也反复强调:复合片段的正式首页登记仍被拦截、entitlement_verified: false 不是授权成功、encoded-and-decoded 不等于人眼与主观听感合格——这些都与原文档"本地验证不代表已发布"的定位一致。

八、如何自行核验分发边界(可复现命令)

仓库提供了两条直接对应"收录/不收录边界"的可复现检查,均可在仓库根目录执行:

python3 tools/check_package.py
python3 -m unittest discover -s tests -v
  • check_package.py 输出 source-checks-passed 汇总,包含 files 总数、inventory_sha256、official_binaries_in_source_inventory: false、network_called: false、approved_public_media 数量等字段;它会检查:语法与隐私模式、相对链接完整性、桥接/IO/资源目录的 pin、Git 跟踪边界(git ls-files 的结果必须全部落在已检查清单内);
  • unittest discover -s tests -v 运行包括 tests/test_public_media.py 在内的可移植测试,验证媒体白名单、源码包装与运行时配置检查;
  • codec 重建可执行 python3 tools/build_native_codec.py,成功后输出 codec_sha256 并断言等于 b6533eb5…f971d;若本机无匹配的剪映版本或组件身份不符,脚本会明确拒绝(版本校验见 engine/runtime_profiles.py 的 validate_identity)。

需要说明的限制:专项原生测试的本机素材与证据不随仓库分发,源码检查不能替代实际工程验收;核验命令也无法覆盖"干净机器安装验收"和"完整主观视听验收"这两项仍未完成的事项。

九、边界速查表

维度 收录 / 允许 不收录 / 不允许
代码 无界面草稿、编辑、效果、导出、桥接、测试、Skill 入口、构建脚本 已编译 codec 二进制、历史实验输出、原始截图/日志
媒体 仅 docs/media/ 四份白名单衍生件(路径+大小+SHA 固定) 真实视频音频、用户草稿、账号资料、Cookie/Token/密钥/带签名 URL
官方组件 仅运行时引用本机已安装剪映 安装包、动态库、字体、效果包、缓存音效、GPU 缓存
授权 个人学习与非商业使用(LICENSE);第三方内容按原许可 商业使用(须书面授权)、整包 MIT/Apache-2.0 定性、官方集成/账号/素材授权
发布动作 本次明确授权的公开预览与 Skill 收录 未经本次授权的新推送、新公开目标、GitHub Release

总结:这份分发边界文档的实质,是给"源码预览"划定了一条可核验、不漂移的线——收录范围被 pin 哈希与媒体白名单锁死,不收录范围被隐私正则与构建脚本挡住,授权层级被 LICENSE 文本明确分层。对于想要学习或复用该仓库的开发者,正确的打开方式是:阅读 README.md 了解能力边界 → 对照本文理解分发边界 → 在本机执行 tools/check_package.py 与测试命令亲自核验 → 在个人学习与非商业用途范围内使用,并在涉及商业、发布或跨机器部署前取得作者明确授权。

登录后查看全文
jianying-headless