开发指南

环境

macOS 13 或更高版本
Xcode Command Line Tools
Swift 6
可选：支持 DDC/CI 的外接显示器
可选：ArgyllCMS 与实体校色仪

项目无第三方 Swift Package 依赖。

常用命令

make check       # 核心检查、ICC 检查、warnings-as-errors
make build       # Debug 构建
make run         # 从 SwiftPM 启动
make app         # 构建 dist/DisplayTune.app
make clean       # 清理 SwiftPM 与 dist

也可直接运行：

swift run DisplayTuneCoreChecks
swift run DisplayTuneICCChecks
swift build -Xswiftc -warnings-as-errors

目录结构

DisplayTune/
├── Package.swift
├── Sources/
│   ├── DisplayTune/
│   ├── DisplayTuneCore/
│   ├── DisplayTuneColorProfiles/
│   ├── DisplayTuneCoreChecks/
│   └── DisplayTuneICCChecks/
├── docs/
├── scripts/
└── .github/

职责说明见架构说明。

修改 UI

主菜单位于 MenuContentView.swift，校色窗口位于 CalibrationStudioView.swift。

注意：

不要在 View 中直接执行 DDC 或 ColorSync I/O。
通过 DisplayManager 发布状态。
耗时硬件读取应离开主线程。
多显示器切换时要取消或恢复未完成的视觉会话。
新按钮要在不可用时显示明确原因，而不是静默失败。

添加显示器策略

在 MonitorStrategyCatalog.swift 中新增 Definition 或 communityModel。

最小数据：

稳定的策略 ID；
显示名称；
EDID 厂商 VID；
一个或多个 PID；
产品名称回退 token；
色域目标；
分辨率或亮度建议；
数据证据和 OSD 起始建议。

规则：

VID/PID 优先于名称匹配。
名称 token 只作为适配器隐藏 EDID 时的回退。
不根据资料直接启用 VCP；硬件能力始终由运行时逐项读取决定。
不猜测 PID、VCP 最大值或“所有同系列都相同”。
高刷策略应保留适合的刷新率，不能只追求逻辑分辨率。

随后在 DisplayTuneCoreChecks 中添加：

VID/PID 精确匹配检查；
名称回退检查；
未知型号通用策略检查；
推荐分辨率检查（如策略指定）。

并更新显示器兼容性。

添加 DDC 功能

新增 VCP 前需要：

在 DisplayTuneCore/DDCCapabilities.swift 定义功能。
在 DDCController 中实现独立读取和写入。
验证响应命令、VCP 代码、最大值和校验和。
确保 UI 只有读取成功后才可写。
考虑旧配置解码和多显示器映射安全。
使用实机证据记录支持范围。

避免依赖显示器 capabilities 字符串作为唯一证据；部分显示器不返回字符串，却可直接读取某些 VCP。

修改 ICC

ICC 生成代码在 DisplayTuneColorProfiles。任何修改都必须：

保留源文件不被原地覆盖；
为生成文件使用独立描述名称；
通过 ColorSyncProfileVerify；
检查所需标签存在；
验证 VCGT 是三通道 256 点；
写入后重新打开文件并验证；
更新 DisplayTuneICCChecks。

不要把视觉目标描述为仪器实测 ICC。

硬件测试矩阵

提交硬件相关变更时，尽量记录：

维度	示例
Mac	Apple Silicon / Intel
macOS	13、14、15、当前版本
连接	DP、HDMI、USB-C、Thunderbolt
中间设备	直连、扩展坞、KVM、转接器
显示器数量	1、2、多台
模式	SDR、HDR、PBP/PIP、高刷
VCP	五项分别读取/写入结果

没有硬件时可以贡献纯逻辑、文档和 ICC 检查，但不要声称未验证链路“已支持”。

Pull Request 检查

提交前：

./scripts/check.sh
./scripts/build-app.sh
codesign --verify --deep --strict --verbose=2 dist/DisplayTune.app

再确认：

没有 .build/、dist/、artifacts/、.DS_Store 或校准文件进入 Git。
没有个人绝对路径、序列号、桌面截图或日志中的隐私信息。
文档链接有效。
UI 中没有将计划功能写成已实现。

发布清单

更新版本号、构建号和 CHANGELOG.md。
运行所有检查和 release 构建。
在干净用户环境测试第一次启动和恢复系统色彩。
测试分辨率 15 秒回滚。
测试 DDC 映射歧义时禁止写入。
测试视觉会话取消和应用退出恢复。
使用 Developer ID 签名、公证并 stapling。
生成校验和并发布 GitHub Release。
明确标注已验证 macOS、芯片和显示器。

当前仓库只自动验证 ad-hoc 构建，不代表正式发行版已经公证。

FilesExpand file tree

development.md

Latest commit

History