macOS 录屏剪辑工具DogSC「逐文件」搬进 Windows —— DogSC Desktop 转写记

上游：laogou717/dogsc（macOS · Swift + ScreenCaptureKit）

本项目：wyfirstname/dogsc-desktop（Electron 33 · React 18 · TypeScript 5.7 · Ant Design 5）

DogSC 是什么

DogSC 是一款 macOS 上的录屏剪辑工具，用 Swift + ScreenCaptureKit 写成。它最打动人的地方不是「能录」，而是录完自动帮你剪：根据鼠标轨迹自动生成 3D 运镜、光标点击自动放大反馈、画面自动聚拢开场 ------ 一条 6 分钟的屏幕录制，导出的成片已经像一个精心剪过的产品演示视频。

问题只有一个：它只能在 macOS 上跑。于是有了这个项目 ------ 把 DogSC 的源码逐文件转写成 Electron + React + TypeScript，让 Windows 用户也能用上同一套剪辑体验，并打包成免安装的绿色版 exe。

上游 Swift 文件	上游源码行数	数值断言（全过）	分发形态
285	96,959	2,099	免安装单文件 exe

为什么是「逐文件转写」，而不是重写

最省事的做法是「照着感觉重写一个」。但那样做出来的是一个神似的产品，而不是 DogSC 的 Windows 版 ------ 运镜的缓动曲线差 0.05 秒、黑边检测的阈值差 0.3%，用户看不出来，但「手感」就没了。

所以这个项目立了一条铁律：每个 Swift 文件对应一个 TS 文件 ，文件头注释标注上游路径、行数与基线 commit，文件内用 L6-24 → ... 这样的行号对照表把每个结构钉死。整个工程由三件套支撑：

mappings.json ------ 逐文件映射表，锚定上游基线 commit 567fd6e，当前已登记 125 条；
npm run upstream:check ------ 上游一更新，立刻列出哪些文件变了、对应哪个转写目标；
verify 断言体系 ------ 不是「跑起来没报错」，而是把运镜时长、缓动系数、黑边阈值这些魔法数字直接算出来比对，目前已累计 2,099 项，全部通过。

逐文件转写慢，但它带来一个别人给不了的能力：上游每次提交，我们都能精确知道该改哪里。这不是一次性移植，而是一条能长期跟着上游走的「移植生产线」。

技术栈对照：Swift 的每一块，都得找到 Windows 的对应物

macOS / Swift	Windows / 本项目
SwiftUI + AppKit	React 18 + Ant Design 5
ScreenCaptureKit（屏幕采集）	Electron `desktopCapturer`
AVFoundation（解码 / 拼接）	ffmpeg（ffmpeg-static，主进程调用）
Core Animation 弹簧动画	手写弹簧 / 缓动求解器（纯函数，可断言）
Swift Concurrency（Task / actor）	Promise + 取消令牌 + 许可证队列
NSDocument / 文件代次	ProjectDocument + inode 级代次冻结

其中最费心思的是动画与几何：上游大量手感来自 Core Animation 的弹簧参数与采样逻辑，这些全被转写成纯函数模块 （如 EditorZoomEnvelope、CaptureAreaSelectionMotion），每一个都能用数值断言锁死 ------ 1-(1-t)^3 的三次方缓出、0.7 秒弹簧、对数缩放包络，一个数都不许漂。

界面一览

以下均为 Windows 实机运行截图（Electron 窗口原生截图）。

功能现状

录制与导入：屏幕录制（桌面捕获）与本地视频导入，统一进工程模型；
时间线剪辑：分割、删除（波纹前移）、两端裁切、变速、双击接点还原、完整撤销 / 重做；
编辑器预览：3D 运镜、背景源（5 种图案 / 3 种动态流 / 图片 / 视频）、光标样式与大小、开场转场（聚拢 / 侧滑 / 轻 3D）；
导出：按剪辑时间线用 ffmpeg 拼接（trim + setpts/atempo + concat），实时进度与剩余时间估算；
上游同步：映射表 + 基线对比，上游更新可逐文件追踪。

屏幕录制 自动运镜 光标特效 时间线剪辑 ffmpeg 导出 免安装绿色版

工程方法：让 96,959 行可以「被验证地」搬过去

转写最大的风险不是写不出来，而是写错了不知道。这个项目的对策是把一切变成可计算的断言：

ts 复制代码

// 例：verify 断言不是「调用了函数」，而是把魔法数字算出来比对
check('slider.logRoundTrip', sliderValue(logarithmicSliderScale(0.37, ...)), 0.37)
check('lb.medianArea', medianArea([]) === Infinity, true)
check('ex.buildStickerKept', stickered.assets.stickers['stickers/a.png'].url, '/in/sticker.png')

纯逻辑（运动轨、剪辑引擎、导出请求、屏幕拓扑）全部抽成无副作用模块，用 2,099 项数值断言锁死；
UI 层用端到端脚本截真实窗口比对（背景 / 光标 / 转场渲染、导出成片时长校验）；
每完成一批固定动作：三份 tsconfig 类型检查 → 追加断言 → 登记 mappings.json → 提交。

下载与构建

免安装绿色包（解压即用，无需安装）：

text 复制代码

百度网盘：https://pan.baidu.com/s/18QJFUBMfvwps3mQelFjSig?pwd=sd56   提取码：sd56

自行构建（Windows 10/11，Node ≥ 20）：

bash 复制代码

git clone https://github.com/wyfirstname/dogsc-desktop.git
cd dogsc-desktop
npm install
npm run dev:electron   # 编译并启动
npm run dist           # 打包 release/DogSC-x.x.x-win-x64-portable.exe

还在路上

上游 285 个文件已映射过百，RecorderCore（44 个核心模型文件）已全部完成；剩下的大头是真正的状态机与渲染管线 ------ 共享帧渲染器（2,128 行）、编辑器主控制器（1,400+ 行 ×3）等，正按批次逐个啃。时间线与检查器 UI 目前还是简化版，后续会有专门的批次把已转写的纯逻辑真正接进界面。

如果你对「怎么把一个原生应用讲道理地搬到另一个平台」感兴趣，欢迎到 dogsc-desktop 看转写记录（RUNNING.md 里有每一批的决策与踩坑），也请给上游 laogou717/dogsc 一个 Star。