简体中文 ｜ English
Windows 11 笔记本开合视觉特效系统
让桌面画面随笔记本开合，像折叠设备一样随铰链产生空间折叠的视觉效果。
DuoFlow 是一个运行于 Windows 11 上的桌面视觉特效程序：
当用户"合上"笔记本屏幕时，让 Windows 桌面画面产生绕铰链空间折叠的视觉效果——桌面在铰链处保持清晰明亮，向远端逐渐沉入磨砂虚化与阴影，如同折叠设备的屏幕被玻璃带走。
效果不是简单的渐变或淡出，而是透视折叠 + 物理景深磨砂 + 光影衰减共同构成的连续动画，由开合进度（0→1）实时驱动。
最终体验：
拖动进度（或未来由开合驱动）
→ 桌面绕铰链产生透视折叠
→ 远端逐渐沉入磨砂虚化与阴影
→ 画面像被折入铰链 → 屏幕关闭 / Windows Sleep
打开则完全反向。
目标体验：不是电脑突然播放了一个动画，而是电脑的屏幕真的随着铰链在折叠。
M0（可行性）、M1（渲染 MVP）全部完成 ✅，M2 视觉打磨客观项全部完成，现已进入 M3 摄像头 Provider。
现在就能玩的演示：
- 按快速开始构建并运行
- 拖动左下角控制台的进度滑块
- 整个桌面实时折叠：铰链处保持锐利明亮，远端逐渐磨砂化并沉入阴影
- 用下方「渲染参数」面板实时改折叠角度 / 相机距离 / 方向 / 铰链边 / 模糊与包络 / 渐变色相 / 光带扫过（渐变与光带默认关闭，两者正交：渐变改色相，光带加亮度）
- 单元测试 333/333 通过（
dotnet test src/DuoFlow.Core.Tests/DuoFlow.Core.Tests.csproj） - 渲染采用物理景深模型：缝隙高度驱动磨砂半径与光衰减，mip 预过滤 + Vogel 螺旋采样
- 透明度、点击穿透（click-through）、折叠几何均已真机验证
- 真机量化验收脚本在
scripts/acceptance/：几何/光影方向/模糊方向/无滞回/覆盖度（9/9）、 P0 三件套、参数面板接线（20/20）、六种开合操作与速率合规（22/22）、光带位置与幅度（14/14）、 摄像头枚举/打开/真解码帧/隐私（18/18）、屏幕检测契约（27/27）、盖子进度链路（33/33），退出码可直接判 - 摄像头按「设备与算法在程序集层分离」接入（DD-053）：
DuoFlow.Vision是纯net8.0且引不到 WinRT，像素坐标唯一的进出口是CameraProfile；DuoFlow.Camera才碰设备。 真机实测 1280×720 NV12、AlphaMean=255（真 BGRA）、无任何像素落盘 - 屏幕检测是确定性几何（Otsu → 连通域 → 凸包 → 四点拟合），没有模型：
活画面下真机 30/30 帧可用、最佳置信度 0.864；镜头被遮时 0/30 并如实报
FlatScene（DD-054） - 盖子进度不靠"看屏幕"（盖子上的摄像头看不到自己的屏幕），而是靠近平面占比：
盖子每合一度，摄像头光轴就下俯一度，画面下半部的近平面就多占一分（DD-055）。
这个量在三种情况下会被结构性否决而不是硬报数字——区域触顶无远边界（
NoFarBoundary）、 整帧平坦（FlatScene）、边界对比不足（LowConfidence） - 全开时进度为 0 由运行时基线学习保证：首个可用样本即"全开"基准， 而不是靠一个对所有桌子都猜不对的常数（真机上常数会让启动即折 42%）
Angle明确标注为名义值：占比无法反解成角度，且项目禁止假设焦距与安装位置； 真实可信度全部走Confidence（DD-055）- 渲染参数自动保存到
%LOCALAPPDATA%\DuoFlow\tuning.json，重启后保留（DD-051） - 特效不可见时渲染心跳自动静默：静止桌面下不再每秒 33 帧空转（DD-051）
- 参数面板实时显示「满折覆盖 X%」：
MaxFold=90°时满折覆盖恒为 0，拖动即可看到取舍（DD-052）
要求：Windows 11（build 22621+）、支持 D3D11 的 GPU、.NET 8 SDK（8.0.425 验证通过）。
git clone https://github.com/ChenChen913/DuoFlow.git
cd DuoFlow
.\scripts\run.ps1 # 构建 + 启动（等价于下面两行）手动构建与启动：
dotnet build src/DuoFlow.App/DuoFlow.App.csproj -p:Platform=x64
.\src\DuoFlow.App\bin\x64\Debug\net8.0-windows10.0.22621.0\DuoFlow.App.exe运行后拖动左下角控制台的 Manual Progress 滑块即可看到折叠效果；下方「渲染参数」面板 可以实时改折叠角度、相机距离、折叠方向、铰链边、最大模糊与模糊包络（「恢复默认」一键复位）。 关闭控制台窗口即整体退出。
Windows Graphics Capture（GPU 捕获桌面）
→ 常驻最新帧纹理（捕获与渲染解耦，渲染心跳 ~30 FPS 独立驱动）
→ 折叠投影（绕铰链的单应变换，progress 驱动）
→ 物理景深：缝隙高度 → 二次缓入模糊半径 → mip 预过滤 Vogel 螺旋采样
→ 光影衰减：远端随磨砂加深沉入阴影
→ 全屏合成（折叠区域全不透明；四边形外预乘透明，交给 DWM 与真实桌面混合）
四个设计要点：
- 捕获与渲染解耦——静态屏幕不产生捕获帧，渲染心跳独立驱动，互不拖累
- 源冻结——效果可见期间捕获源冻结在效果出现前的纯净桌面，自反馈重影从源头消除
- 物理景深模型——模糊与光影由同一物理量（玻璃与桌面的缝隙高度）驱动，浑然一体
- 透明层配方——分层窗口 + alpha-0 背景画刷 + 点击穿透，全屏覆盖层不挡鼠标
- 输入层和渲染层完全解耦 — 渲染系统只消费
lidProgress = 0.00 → 1.00，不关心角度来自摄像头、传感器还是手动模拟。 - 动画必须连续 — 所有视觉参数由 progress 驱动，不做"检测到合盖就播一个固定动画"。
- 几何变形 + 模糊 + 光影衰减，而不是模拟一个渐变色。
- 不与 Windows 电源管理对抗 — Display Off ≠ Sleep；采用 Pre-Sleep Finalization 在系统睡眠前完成动画，绝不阻止系统睡眠。
- 不假定硬件 — 摄像头位置/分辨率/方向/FOV 全部通过 Discovery + Calibration + Profile 适配；摄像头只是 LidState 的一种 Provider。
项目立项时曾以「Lenovo Duo」为暂定名。命名讨论的结论是：
- 「联想」会把项目锁死在 Lenovo；「Win11」会锁死在 Windows 11；这类名字限制了未来输入方式（摄像头 → Hinge Sensor → HID → 厂商 API → 人工控制）和设备品牌（Lenovo / ASUS / HP / Dell...）的扩展。
- 备选名单中 WinDuo、DuoFlow、DuoFold、HingeFlow、DuoFX 为第一梯队；考虑到 WinDuo 与已有项目重名，最终选定：
DuoFlow —— 强调开合过程中的连续流动，保留核心概念，又不把品牌、厂商、Windows 版本写死。
| 模块 | 技术 |
|---|---|
| 桌面程序 | C# / .NET 8 |
| Windows UI | WinUI 3（Windows App SDK 1.8） |
| 屏幕捕获 | Windows Graphics Capture（GPU → GPU，禁止走 CPU Bitmap） |
| GPU 渲染 | Direct3D 11 + HLSL（物理景深折叠着色器） |
| 摄像头（规划） | Media Foundation / OpenCV |
| 单元测试 | xUnit |
无论是 Claude Code、Codex 还是其他 Coding Agent，每次开始任务先读这几份文件，而不是扫描代码后自行理解项目：
| 文档 | 回答的问题 |
|---|---|
| EXECUTION_PLAN.md | 项目执行到哪一步了、接下来做什么（交接入口：进度打勾 / 状态快照 / 进度日志，AI Agent 接手必读） |
| docs/PROJECT_SPEC.md | 项目要做什么（完整规格说明 v0.2，含摄像头适配层与 Power & Sleep Architecture） |
| docs/DESIGN_DECISIONS.md | 项目已经决定怎么做（DD-001 ~ DD-046，约束后续 AI 与重构的"事实层"） |
| docs/TODO.md | 项目任务如何定义（M0 ~ M12 开发路线图与验收标准） |
| docs/HARDWARE_COMPATIBILITY.md | 项目真实环境到底是什么（摄像头适配预案、能力等级、实测记录库） |
| docs/TECHNICAL_PROPOSAL.md | 项目最初怎么想的（立项阶段完整技术方案，保留原始设计推理） |
M0 Research & Feasibility — 验证捕获 / Overlay / 传感器 / 摄像头可行性 ✅
M1 Rendering MVP — 滑杆驱动 折叠 + 磨砂 + 光影 ✅
M2 Visual Refinement — Gradient + Light Sweep + Demo Mode（进行中）
M3 Camera Provider — 真实开合驱动动画
M4 Sensor Provider — 优先使用真实硬件信息
M5 Windows Integration — 电源事件 / 开机自启
M6+ Productization — 设置界面 / 安装包 / 完整测试
执行进度逐项见 EXECUTION_PLAN.md。
DuoFlow/
├── EXECUTION_PLAN.md # 项目执行文档（AI Agent 交接入口）
├── shaders/
│ └── DuoWarp.hlsl # 折叠投影 + 物理景深 + 光影衰减着色器
├── src/
│ ├── DuoFlow.App/ # WinUI 3 应用（覆盖层 / 控制台 / 渲染管线 / 探针）
│ ├── DuoFlow.Core/ # LidState / AnimationEngine / Provider 契约
│ ├── DuoFlow.Core.Tests/ # xUnit 单元测试（333）
│ ├── DuoFlow.Capture/ # Windows Graphics Capture 与 D3D 互操作
│ ├── DuoFlow.Render/ # 折叠几何 / 渲染参数（纯 C#，可单测）
│ ├── DuoFlow.Vision/ # 几何 / 检测 / 占比估算 / 进度映射 / 选型 / 限速（纯 net8.0，无 WinRT）
│ └── DuoFlow.Camera/ # MediaCapture 设备层 + LidState 适配器（唯一碰摄像头的程序集）
├── scripts/ # run.ps1（一键构建+启动）/ 环境准备 / 硬件探针
│ └── acceptance/ # 真机量化验收（几何 / P0 三件套 / 参数面板 / 摄像头）
├── docs/ # 规格 / 设计决策 / 路线图 / 硬件兼容性
└── .github/workflows/ # Windows CI（构建 / 冒烟 / 单测）
摄像头只用于检测笔记本屏幕状态：默认不上传、不保存、不录制、不联网。日志不包含屏幕内容与摄像头画面。
MIT © 2026 ChenChen913