Jianying Headless 公开源码范围与分发边界:收录/不收录清单、授权分层与可验证的发布防护
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/ 目录:
- bridge/jy14_codec.cpp:草稿编解码 C++ 桥接实现;
- bridge/EncryptUtil.h:保留来源声明的接口头文件;
- bridge/runtime_io.py:文件快照与目录事务锁定的 IO 助手;
- bridge/SOURCE_MANIFEST.json:桥接来源清单,逐文件固定 SHA-256,并声明
official_library_distributed: false。
3. 结构蓝图、测试与构建脚本
脱敏后的结构蓝图、资源身份/哈希目录、测试、独立 Skill、构建脚本和声明。
- 结构蓝图: engine/blueprint.json、engine/compound-blueprint.json、engine/blueprint-provenance.json;
- 测试: engine/test_*.py、tests/ 下的可移植测试;
- 独立 Skill: skills/yichen-jianying-edit/(详见第六节);
- 构建脚本: tools/build_native_codec.py、tools/check_package.py、tools/smoke_test.py;
- 声明: project.json、docs/VERIFICATION.md。
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:即使符号链接指向合法文件也拒绝(防止绕过路径白名单)。
这两份文件共同回答了"这份发布到底放行了哪些媒体"——只有上述四份衍生件,且不允许任何形式的内容替换或链接逃逸。
三、不收录范围:五类明确排除的内容
原文档的"不收录"是理解本仓库边界的另一半,逐条对应仓库现实:
- 剪映安装包、官方动态库、内置字体、效果包、缓存音效和 GPU 编译缓存——运行时需要的这些组件必须由使用者本机安装的剪映提供,仓库不携带任何官方二进制;
- 真实视频、音频、用户草稿、原生账号资料、bookmark、Cookie、Token、密钥或带签名 URL——除四份已授权演示衍生件外一概不收录。这一条在 tools/check_package.py 的
PATTERNS正则里得到执行:personal-home-path、private-key、github-token、signed-url四类隐私模式会在源码检查中被拒绝; - 历史实验输出、原始截图/日志、旧版本已登记在线音效的专用变更流程——例如 docs/VERIFICATION.md 中反复出现的
work/忽略目录(work/acceptance-1150/、work/hypit-case-20260919/等)只保留在本机证据层,不进入源码分发; - 已编译的本项目 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 的含义。
五、开源与授权:四个不同层面的约束
原文档用一句话点破了本仓库最容易被误读的地方:代码许可证、剪映用户协议、素材许可、账号权益是不同层面的约束。具体拆开:
- 原创代码:采用根目录 LICENSE 的 "Personal Learning and Non-Commercial Use License"——允许个人学习、研究和非商业个人工作流使用;商业使用须取得作者明确书面授权(联系渠道见 LICENSE 文本,本文不展开);
- 第三方内容:保留各自原许可,licenses/ 与 THIRD_PARTY_NOTICES.md 中的文本不等于把剪映及其资源授予同样的许可;
- 剪映官方程序库、账号权益与素材许可:不随源码分发,也不被代码许可证覆盖;
- 打包定性:不应把本预览称为 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 与测试命令亲自核验 → 在个人学习与非商业用途范围内使用,并在涉及商业、发布或跨机器部署前取得作者明确授权。