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—— 逐文件映射表，锚定上游基线 commit567fd6e，当前已登记 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 行可以「被验证地」搬过去
转写最大的风险不是写不出来，而是写错了不知道。这个项目的对策是把一切变成可计算的断言：
// 例：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→ 提交。
下载与构建
免安装绿色包（解压即用，无需安装）：
百度网盘：https://pan.baidu.com/s/18QJFUBMfvwps3mQelFjSig?pwd=sd56 提取码：sd56
自行构建（Windows 10/11，Node ≥ 20）：
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。
浙公网安备 33010602011771号