亮度调节是桌面系统里看起来最不起眼、实际最难做对的一类功能。上游 Twinkle Tray 之所以好用,是因为它同时握住了 Windows 的两条底层通路:一条是 DDC/CI,直接给显示器发送 VCP 码改写硬件背光;另一条是 SetDeviceGammaRamp,给显卡下发每通道 1024 项 16 位灰度斜坡,用软件方式把整屏压暗。前者让调节真的省电、真的降低发光,后者在笔记本内屏和廉价外接屏上救急。两条通路合起来,才构成一个亮度工具的完整体感。

把这个工具搬到鸿蒙 PC 的 Electron 壳上,第一件事不是画界面,而是照镜子:运行时不提供 DDC/CI,也不提供系统级 gamma ramp,两条底层通路一条都走不通。本文记录的就是在这条约束下如何把功能完整表达出来——用 256 级一维 LUT 复现灰度斜坡的换算链,用 CSS filter 与 LUT 画布组成两条壳内预览通道,用五种感知模型做背光归一化,用一套自洽的天文算法驱动日出日落计划,并且把做不到的部分明确写进界面而不是藏起来。全部数据取自项目源码与本次真机构建产物,不含估算值。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_TwinkleTray

说明:文中代码包含源码节选,省略处以注释标出;依赖外层变量或未展示完整函数的片段不能独立运行。

一、技术架构分析

1.1 先划能力边界:一个不碰硬件背光的亮度工具

DDC/CI 与系统 gamma ramp 这两条路,在鸿蒙 PC 的 Electron 运行时里都没有对应接口。窗口层给到应用的只有 screen、BrowserWindow 这类高层 API,能拿到显示器列表、工作区尺寸、缩放因子,但拿不到背光寄存器,也拿不到显示器句柄。这不是配置问题,也不是权限问题,是运行时暴露面的边界。

项目没有在这条边界上做模糊处理。主进程源码的文件头第一句就把结论写死,然后把整套设计围绕这个结论展开。既然硬件通道不可用,就要让每一个功能都有壳内等价物,同时让用户在任何一个面板上都能看见“现在调的是壳内预览,不是显示器硬件”。这种写法有个明显好处:后面出现任何“为什么调了没反应”的疑问,答案已经写在界面里了。

每一次状态写入都被收进同一个汇总函数,返回值里把硬件通道的结论固定为否,同时带上软件预览表达式与最新摘要:

function applyResult(res, source) {
  var changes = normChanges((res && (res.changes || res.changed)) || []);
  var primary = state.displays[0];
  state.config.lastApplied = { at: new Date().toISOString(), source: source, changes: changes };
  persist();
  pushLog({ kind: 'apply', text: source + ':' + (changes.length ? changes.length + ' 项变更' : '无变更') });
  return {
    success: res.success !== false,
    error: res.error || '',
    changes: changes,
    hardware: false,
    channel: primary ? D.channelOf(primary) : 'gamma',
    preview: G.toCssFilter(primary ? primary.state : {}),
    displays: state.displays.map(exportDisplay),
    summary: D.summary(state.displays)
  };
}

这段代码里有两处值得说。一是 hardware 字段恒为 false 而不是省略,前端拿到的是一份明确表态的能力回执,不是一个需要靠约定去猜的缺省值。二是 preview 字段由引擎的 toCssFilter 现算,不带任何缓存——前端拿到的亮度表达式永远和主进程的状态同源。

能力边界在界面上出现在至少三个位置,彼此互不依赖。左侧导航底部有一段脚注,写明硬件亮度通道在鸿蒙 PC 运行时不可用、所有调节都作用在壳内软件预览通道。底部状态栏在显示器枚举之后会拼出通道探测结果,真机截图里显示为“显示器列表已更新:1 台 · DDC/CI 不可用 · 软件 Gamma 可用 · 1 台”。右下角的“关于”入口弹出的对话框里,开源声明段落把“鸿蒙运行时不暴露 DDC/CI 与系统 gamma ramp 接口”作为设计前提直接陈述,紧接的免责声明段落又补了一句“亮度与对比度调节为壳内软件预览效果,不改变显示器硬件背光,也不写入系统色彩配置”。

三处声明用词不同、位置不同,但只要用户看过其中任意一处,就不会对产品能力产生误解。这比在设置页写一行小字、或者干脆不提,要诚实得多,也省掉了大量客服解释成本。

1.2 四十一个 IPC 通道与三层通道模型

主进程用一张通道表把能力摊开,注册入口是一个统一包装器,任何处理函数抛出的异常都会被转成结构化错误,而不是让渲染层的 Promise 悬空:

function handle(channel, fn) {
  ipcMain.handle(channel, function (event, req) {
    try {
      return fn(req || {});
    } catch (e) {
      return { success: false, error: errText(e), code: e && e.code };
    }
  });
}

这张表一共四十一个通道,按职责分成十二组:应用与环境两条(app:info、env:probe);显示器七条(displays:list、displays:set、displays:applyState、displays:setAll、displays:step、displays:power、displays:calibrate);伽马两条(gamma:preview、gamma:export);背光归一两条(normalize:run、normalize:apply);天文两条(solar:events、solar:places);计划三条(plans:schedule、plans:check、plans:run);预设三条(presets:snapshot、presets:apply、presets:remove);快捷键一条(shortcuts:set);命令行一条(cli:run);配置三条(config:get、config:set、config:save);文件与文件系统八条(file:export、file:import、file:importPath、fs:readText、fs:writeText、fs:scan、dir:choose、dir:forget);杂项七条(prefs:get、prefs:set、log:list、log:clear、samples:list、clip:write、shell:reveal)。

通道数量本身不说明问题,真正决定体验的是每个通道的返回结构是否一致。这里所有写操作都收敛到同一种形状:success、error、changes、hardware、channel、preview、displays、summary。渲染层因此不需要为每个通道写一套解包逻辑,只需要在统一出口处判断 success 与 changes 长度。渲染层确实也是这么做的,它的全部 IPC 调用只经过一个函数,连 catch 都统一处理成结构化失败:

function invoke(channel, payload) {
  return ipcRenderer.invoke(channel, payload || {}).catch(function (e) {
    return { success: false, error: '通道 ' + channel + ' 调用失败:' + ((e && e.message) || e) };
  });
}

显示器对象上挂着通道标记,取值只有三种:ddcci 表示硬件可写,gamma 表示只能走软件通道,unsupported 表示连软件通道也没有。真机环境下枚举出来的显示器标记恒为 gamma,界面上显示为“软件 gamma(壳内预览)”与表格里的小标签 gamma。这个三值模型比布尔值多出来的那一档不是摆设——当系统里出现一台既无 DDC/CI 又无 gamma 通道的虚拟显示设备时,布尔模型会把它误判成可用,用户点下去才发现无效,三值模型则会直接标成 unsupported 并在批量操作里跳过它。

1.3 六引擎的拓扑序与纯函数边界

应用目录共 15 个文件、7758 行、310486 字节。其中六个引擎文件占 2078 行、93245 字节,是行数的 26.79%、字节数的 30.03%。剩下的大头是主进程 1063 行 44136 字节、渲染层 2618 行 99981 字节、结构 589 行 36060 字节、样式 875 行 24877 字节。也就是说界面渲染占了一半以上,算法内核只占四分之一强——这个比例是合理的,一个桌面工具的手感主要取决于面板密度与状态同步,算法本身反而不该膨胀。

六个引擎的职责切得很干净:

  • 伽马引擎负责 sRGB 传递函数、亮度对比度伽马色温增益合成 256 级一维 LUT、1024 项斜坡、CSS 预览表达式、LUT 自检与 CUBE/CSV 导出。
  • 显示器引擎负责通道判定、电量状态、量程校准、批量写入、步进、摘要与排序。
  • 归一化引擎负责五种感知模型的物理量往返、参考亮度求解、目标求解与可达性统计。
  • 天文引擎负责太阳位置、正午时刻、事件二分求解、昼长夜长与极昼极夜标记。
  • 计划引擎负责触发条件与动作的组合、今日时间表、冲突解决、下一次触发、闲置判定与 CSV 往返。
  • 配置引擎负责 schema 登记与迁移、校验、序列化、预设、快捷键、参数分词与命令行描述。

依赖方向是单向的。配置引擎不依赖任何其他引擎;伽马、天文两个引擎只依赖配置引擎的常量;计划引擎需要天文与显示器两个引擎,但采用了延迟取用的写法:

/* 延迟依赖:浏览器按脚本顺序已挂全局,Node 单测回退 require */
function dep(name, file) {
  if (typeof globalThis !== 'undefined' && globalThis[name]) return globalThis[name];
  if (typeof require === 'function') {
    try { return require(file); } catch (e) { return null; }
  }
  return null;
}
function solar() { return dep('TRSolar', './tr-solar.js'); }
function display() { return dep('TRDisplay', './tr-display.js'); }

这十几行的价值在于同一份算法可以活在两种运行时里。浏览器侧按脚本顺序加载,全局对象上已经有 TRSolar 与 TRDisplay,取用就是一次属性读取;Node 侧做单元测试或离线校验时,回退到 require 再读同一份文件。取不到时返回 null,调用方按返回值判断,不会因为模块缺失就抛到顶层。所以渲染层与主进程用的不是两套算法,而是同一份文件的两种加载方式——这一条对亮度这类数值敏感的工具有决定性意义,只要算法分叉,预览和落盘就一定对不上。

脚本顺序在结构里是显式的:六个 script 标签依次是伽马、显示器、归一化、天文、计划、配置,最后才加载渲染层。顺序即依赖序,没有打包器,没有动态 import,也没有跨模块的顶层副作用。

二、环境准备

2.1 SDK 声明与签名材料

工程级的构建配置是这套壳方案的标准模板。产品 default 声明了兼容版本 5.0.5(17)、阶段 release、运行时 HarmonyOS,并且打开了原生库的全量收集:

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.5(17)",
        "compatibleSdkVersionStage": "release",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "nativeLib": {
            "collectAllLibs": true
          }
        }
      }
    ]
  }
}

这里没有显式声明 targetSdkVersion,构建日志里因此会稳定出现五行相关告警,实际生效的目标版本取 SDK 默认值。这条告警不影响产物可用性,属于已知且可接受的状态,需要的是在上架说明里写清楚,而不是每次构建都去翻一遍日志怀疑人生。

collectAllLibs 打开是必须的。默认的按需收集会把未被静态引用的 .so 裁掉,而这套壳的 libelectron.so 是通过 dlopen 在运行时才加载的,静态分析看不到引用关系,一旦被裁,装到真机上就是启动即崩。这个坑在同类壳项目里出现过很多次,代价是排查两三天。

签名配置指向本机的证书目录,包含 cer、p7b、p12 三个文件与一个 debugKey 别名,密码字段是 IDE 生成的密文。这意味着这份配置只在当前这台机器上有效,换一台开发机、或者交给上架同学去构建,都会因为找不到证书而失败。所以它属于上架前必须替换的第一项内容——不是可选项,是硬阻塞。

2.2 应用信息与工程配置

应用级信息在 AppScope 里,八行就说完:包名 com.huawei.ohos_electron、版本号 1000000、版本名 1.0.0、图标与标签走资源引用,并且声明了多实例模式,类型 multiInstance、上限 1。上限为 1 意味着允许开新实例但不允许并存多个,对亮度这种会争抢调色板的工具来说是正确选择——两个窗口各自维护一份显示器状态,最后必然有一份是错的。

模块结构是两层:electron 模块是 entry,deviceTypes 为 2in1 与 tablet,承载 EntryAbility 与原生库;web_engine 模块是 har,同样声明 2in1 与 tablet,承载网页层与权限清单。这种拆法的好处是网页层的权限、资源、页面全部可以在不改动原生壳的情况下单独演进,代价是两边都要维护一份 deviceTypes 声明。

工程里共有十五个 json5 文件,其中六处合计十处带尾逗号:electron 的构建配置三处、electron 的主模块清单三处、electron 的依赖声明一处、web_engine 的构建配置一处、web_engine 的依赖声明一处、web_engine 的主模块清单一处。JSON5 允许尾逗号,编辑器也乐意补上,但如果有下游脚本用 JSON.parse 去读这些文件就会当场报错。批量改动前先确认下游工具链能不能吃 JSON5,比事后去追一个莫名其妙的解析异常要省事。

hvigorfile 保持极简,只挂载系统插件,没有任何自定义 task:

import { appTasks } from '@ohos/hvigor-ohos-plugin';

export default {
    system: appTasks,
    plugins:[]
}

应用侧的依赖声明只有八行、280 字节,名字 twinkle-tray、版本 1.0.0、主入口 main.js、许可证 MIT,没有任何运行时依赖。整个网页层不引入第三方库,画布、CSV、CUBE、天文迭代、LUT 全部手写。这不是为了炫技,是因为打包产物里每多一个依赖,上架审核就要多解释一段许可证,而这里的每一个功能点都不值得那份麻烦。

2.3 三份随包样例与自检入口

应用目录下有个 samples 子目录,随包发布,包含四份文件:两份配置、一份计划 CSV、一份清单说明。清单说明的第一段就把定位讲清楚了——整目录随应用打包,路径就是应用目录下的 samples,已经在主进程默认授权范围内,不需要先弹文件对话框就能读,文件对话框被取消时会自动回落到这里。

第一份配置是双屏基准,2 台显示器、3 个预设、3 个计划、4 条快捷键。计划分别是定点 09:00、日落加 10 分钟、闲置 15 分钟,正好覆盖触发条件里的两种固定式与一种相对式。第二份配置是夜间护眼,地点取自引擎内置星表里的东京,色温压到 3400 与 3200,蓝增益 0.80 与 0.75,计划里包含一条民用昏末加 30 分钟、一条 00:30 让外接屏进待机、一条已停用的日出前恢复。停用那条是有意留的,用来验证停用标记在导入导出往返里不丢。

计划 CSV 是这两份配置之外最实用的一份,因为它把表结构讲明白了。表头共十五列,依次是编号、名称、启用、触发类型、触发时刻、偏移分钟、生效星期、闲置分钟、动作类型、目标、亮度、预设编号、电源、优先级、冷却分钟:

id,name,enabled,triggerType,at,offsetMin,days,idleMin,actionType,target,brightness,presetId,power,priority,cooldownMin
plan-c1,上班 09:00 → 85%,true,time,09:00,0,1 2 3 4 5,10,brightness,all,85,,on,3,5

七行数据覆盖了全部五种触发方式与三种动作,其中一行是停用状态,优先级覆盖 1 到 9,冷却时间从 5 分钟到 30 分钟都有。这样一份样例放在随包目录里,用户想试定时计划不必从零开始填表,而开发想验证冲突解决逻辑,也有一份现成的、覆盖度足够的样本可以反复喂。

清单文件最后一句点出了这批样例的可靠性来源:所有样例均由六个引擎自身生成并回读校验,字段形状与用户数据目录下的配置文件完全一致。换了手写样例,最容易出的问题是字段名对得上但语义对不上,比如 days 写成字符串“1,2,3”而引擎期待数组,导入时校验通过、运行时行为诡异。用引擎自己生成、再用引擎自己读回来验一遍,这个往返本身就是最便宜的一致性测试。

三、核心适配流程

3.1 路径纪律与白名单持久化

一个要读要写文件的工具,路径纪律就是它的安全底线。这里的做法是先把路径统一成一种形态,再做子路径判定,最后用一个函数把非法访问挡在入口处。统一形态只用一次替换,把反斜杠全部换成斜杠;判定前再补一步去掉末尾斜杠并按平台决定是否转小写:

function fwd(p) { return String(p == null ? '' : p).replace(/\\/g, '/'); }

function normForCompare(p) {
  var s = fwd(p);
  if (s.length > 1 && /\/$/.test(s)) s = s.slice(0, -1);
  return process.platform === 'win32' ? s.toLowerCase() : s;
}

function isInside(child, parent) {
  var c = normForCompare(child), p = normForCompare(parent);
  if (!c || !p) return false;
  return c === p || c.indexOf(p + '/') === 0;
}

子路径判定用的是拼斜杠再比前缀,而不是直接比字符串前缀。区别在于直接比前缀会把 D:/data2 误判成 D:/data 的子目录,而拼上分隔符之后就不会。这类细节写错一次,白名单就形同虚设。

白名单本身是个数组,判定走线性扫描,命中任意一项即放行。放行的最小单位是整个目录,不做逐文件登记,因为用户授权时点的就是目录:

function isAllowed(p) {
  var full = fwd(path.resolve(String(p || '')));
  for (var i = 0; i < allowedRoots.length; i++) {
    if (isInside(full, allowedRoots[i])) return true;
  }
  return false;
}

var GUARD_MSG = '该路径不在本应用已授权的目录内,请先用对话框选择导出目录';

function guard(p) {
  if (!isAllowed(p)) {
    var err = new Error(GUARD_MSG);
    err.code = 'EGUARD';
    throw err;
  }
}

这里有个设计上的取舍值得写出来:guard 抛的是带错误码的异常,而不是返回布尔值。返回布尔值意味着每个调用点都要写 if 判断,只要漏写一处,那条路径就相当于没有校验。抛异常则相反,只要忘了判断,控制流一定走不下去。代价是需要上层的统一包装器把异常转成结构化错误,而这个包装器本来就有,所以这笔账是划算的。

白名单不只在内存里活着,还持久化到偏好文件里,下次启动再恢复:

function saveRoots() {
  var cur = readJson(prefsPath(), {});
  cur.allowedRoots = allowedRoots.slice();
  writeJson(prefsPath(), cur);
}

function restoreRoots() {
  var saved = readJson(prefsPath(), {}).allowedRoots;
  if (!Array.isArray(saved)) return;
  saved.forEach(function (r) {
    var full = fwd(r || '');
    if (!full) return;
    try { if (!fs.statSync(full).isDirectory()) return; } catch (e) { return; }
    rememberRoot(full, true);
  });
}

恢复时多做了一次目录存在性校验:磁盘拔了、目录被删了、或者挂载点变了,对应条目会被静默丢弃,而不是留一个永远命中不了的空洞。这一步很便宜,省掉的是用户重装系统后打开应用看到一堆幽灵目录的困惑。

四个上限常量同样服务于这条纪律,并且在诊断面板里原样展示:配置文件读取上限 4MB、导出文本上限 8MB、目录扫描最多 2000 条、触发日志保留 200 条。日志满了不是拒绝写入,而是丢掉最旧的一条再写,所以长期运行不会因为日志把磁盘占满。

3.2 显示器枚举与量程校准

枚举发生在三处:应用启动时一次,用户点“重新枚举显示器”时一次,以及系统屏幕事件触发时一次。事件监听把三个信号都接上了:新增显示器、移除显示器、显示器参数变化。三者任何一个发生,都重新走一遍枚举与状态合并,然后在结果里带一句说明,让界面上的提示能讲清楚这次刷新是被什么触发的。

状态合并的关键是“系统给的是事实,本地存的是偏好”。每一次枚举拿到的都是屏幕对象的真实尺寸、位置、缩放因子;本地配置里存的是亮度、对比度、校准上下限、峰值亮度、电源状态这些偏好值。两者按显示器标识做关联,标识对不上的按新显示器初始化,标识还在但系统里消失了的保留记录并标记断开——否则用户拆掉外接屏再装回来,之前调好的数值就全丢了。

量程校准是这个工具里最容易被忽略、实际最影响体感的一项。上游的做法是给每台显示器单独设一个可用区间,让滑杆的 0 对应这台屏实际能到的最暗、100 对应最亮。本壳把这套语义完整搬了过来,上下限各一个整数,外加一个峰值亮度:

handle('displays:calibrate', function (req) {
  displays();
  var d = D.find(state.displays, req.id);
  if (!d) return { success: false, error: '显示器不存在:' + req.id };
  /* 上下限写反时明确拒收:静默夹取会把用户输入改掉而本人不知情 */
  var loIn = parseFloat(req.calibMin), hiIn = parseFloat(req.calibMax);
  if (isFinite(loIn) && isFinite(hiIn) && hiIn <= loIn) {
    return { success: false, error: '校准上限必须大于下限:' + loIn + ' / ' + hiIn };
  }
  var lo = clampInt(req.calibMin, 0, 99, d.state.calibMin);
  var hi = clampInt(req.calibMax, lo + 1, 100, d.state.calibMax);
  /* 此处省略其余实现 */
  res.mapped = { at0: D.calibrate(d.state, 0), at50: D.calibrate(d.state, 50), at100: D.calibrate(d.state, 100) };
  return res;
});

注释里那句“静默夹取会把用户输入改掉而本人不知情”是这段代码的灵魂。如果上下限写反了就用 max 与 min 兜一下,用户会看到一个自己没输入过的数字,然后怀疑软件是不是坏了。明确拒收加一句带原始数值的提示,成本一样,体验差得很远。

返回值里额外带了三个映射点,分别对应滑杆 0、50、100 换算出的实际背光百分比。面板因此可以告诉用户“你把滑杆拉到 50,实际是这台屏的多少”,而不是让用户自己去猜这条非线性映射。真机截图的明细表里,这一行显示为亮度 60、校准下限 0、校准上限 100、峰值亮度 250、电源开启,与卡片上的滑块位置一致。

摘要信息同时在三个位置复用同一份计算结果:左栏显示显示器 1 台、平均亮度 60%、下次触发无启用计划;右栏显示当前显示器、开机待机与关断的分布 1/0/0、平均亮度 60%、亮度跨度 60% 到 60%(差 0)、以及软件预览表达式 brightness(0.600) contrast(1.000)。同一组数字出现在三个位置且彼此自洽,是判断状态同步有没有做对的快速办法。

3.3 伽马 LUT 与两条预览通道

这是整篇的核心。要把灰度斜坡在壳内表达出来,必须从参数定义开始就把量纲钉死。亮度 0 到 100、默认 100;对比度 1 到 200、默认 100;伽马 0.4 到 2.6、默认 1.0;色温 1500 到 15000、默认 6500;分通道增益 0 到 1、默认 1。斜坡每通道 1024 项,LUT 每通道 256 级:

var RANGE = {
  brightness: { min: 0, max: 100, dflt: 100 },
  contrast: { min: 1, max: 200, dflt: 100 },
  gamma: { min: 0.4, max: 2.6, dflt: 1.0 },
  temperature: { min: 1500, max: 15000, dflt: 6500 },
  gain: { min: 0, max: 1, dflt: 1 }
};

var RAMP_ENTRIES = 1024;   /* Windows 灰度斜坡每通道项数 */
var LUT_SIZE = 256;

亮度滑杆到线性缩放之间不是线性关系,这一步如果偷懒用百分比直接当系数,低段会调不动、高段会糊成一片。项目用的是幂律,并在注释里写清了理由:

function brightnessScale(pct) {
  var p = clampNum(pct, RANGE.brightness.min, RANGE.brightness.max, RANGE.brightness.dflt) / 100;
  return Math.pow(p, 2.2);
}

传递函数用的是 IEC 61966-2-1 的 sRGB 编码与线性互转,色温用的是业界常见的 Kelvin 近似式,6500K 时给出三通道系数。合成过程必须在线性域做乘法、再回到编码域,这一点是这类工具最容易翻车的地方:

for (i = 0; i < LUT_SIZE; i++) {
  lin = Math.pow(srgbToLin(i / 255), 1 / gm);
  out = (lin - 0.5) * ck + 0.5;
  /* 线性域算完必须回到编码域,否则输出会被当作线性值而整体偏暗 */
  lut.r[i] = Math.round(clamp01(linToSrgb(out * bs * temp.r * gn.r)) * 255);
  lut.g[i] = Math.round(clamp01(linToSrgb(out * bs * temp.g * gn.g)) * 255);
  lut.b[i] = Math.round(clamp01(linToSrgb(out * bs * temp.b * gn.b)) * 255);
}

循环体内四步:编码域取值转线性、按伽马反解、线性域做对比度缩放、乘上亮度与色温与增益后转回编码域。少写最后那一步转换,整屏会明显偏暗,而且偏得“看起来还算合理”,很难被当成缺陷报出来——这是最坏的一类错,因为用户只会觉得软件不好用,说不出哪里不对。

256 级 LUT 到 1024 项斜坡用线性插值,8 位到 16 位乘 257(即 65535 除以 255):

for (i = 0; i < RAMP_ENTRIES; i++) {
  idx = i * (LUT_SIZE - 1) / (RAMP_ENTRIES - 1);
  lo = Math.floor(idx);
  hi = Math.min(LUT_SIZE - 1, lo + 1);
  frac = idx - lo;
  ramp.r[i] = Math.round((lut.r[lo] * (1 - frac) + lut.r[hi] * frac) * 257);

乘 257 而不是乘 256,是因为 256 级最大值 255 乘 257 恰好等于 65535,满量程能精确对齐;乘 256 会让最亮端差 255 个码位,斜坡的顶部永远差一截。

到这里出现了本项目的第一个关键判断:色温与分通道增益没有对应的 CSS 属性,因此不能塞进 CSS filter,只能走逐像素通道。于是一条亮度链路被拆成两条:

/* 预览通道:渲染层把这个串写进根元素的 CSS 变量 --tt-filter,
 * 由 .stage 的 filter 消费,不在元素上挂内联样式属性。
 * 色温不参与 CSS 串(CSS 无对应单属性),由 LUT 画布预览精确体现。
 */
function toCssFilter(settings) {
  var s = settings || {};
  var b = clampNum(s.brightness, RANGE.brightness.min, RANGE.brightness.max, RANGE.brightness.dflt) / 100;
  var c = clampNum(s.contrast, RANGE.contrast.min, RANGE.contrast.max, RANGE.contrast.dflt) / 100;
  return 'brightness(' + b.toFixed(3) + ') contrast(' + c.toFixed(3) + ')';
}

CSS 那条路负责亮度与对比度,好处是走合成器、代价极低、文字与图片同时起作用;LUT 那条路负责色温与分通道增益,做法是把画布像素逐个查表,代价高但对每一个通道精确可控。两条路分工的依据不是性能,而是“能不能被表达”。

渲染层消费这个串的方式也值得单独说一句:视图把 CSS 表达式写到根元素的自定义属性上,而不是直接给某个元素挂内联 style。这样样式表里的声明仍然是唯一来源,滤镜的开关、过渡、断点行为全部可以在样式表里统一控制:

var css = GAMMA.toCssFilter(v);
document.documentElement.style.setProperty('--tt-filter', css);
/* 两颗指示灯:A = CSS 滤镜通道是否作用,B = LUT 逐像素通道是否作用 */
var filterOn = v.brightness !== 100 || v.contrast !== 100 || v.gamma !== 1;
var lutOn = v.temperature !== 6500 || v.gainR !== 1 || v.gainG !== 1 || v.gainB !== 1;

这两行指示灯的判断条件是“参数是否偏离默认值”,而不是“结果是否为恒等”。看上去差不多,实际差很多:透明度、合成层、色彩空间都会影响最终观感,用参数判定则明确告知用户“我调了哪条路”,语义更准。

自检面板给出的六项数字可以直接拿来验算,它们和参数是完全一致的。以真机截图里的亮度 60%、对比度 100%、伽马 1.00、色温 6500K、三通道增益 1.00 为例:

  • 亮度 60 过幂律得 0.6 的 2.2 次方,约 0.3251。
  • 6500K 经 Kelvin 近似得到三通道系数 1.000、0.9966、0.9806。
  • 输入 255 时线性值为 1,乘 0.3251 再转回编码域得 0.6055,乘 255 取整为 154;红、绿两个通道都是 154,蓝通道因系数 0.9806 略低,得 153。
  • 于是恒等残差 = 255 减 153 = 102,来自蓝通道,与面板上的 102.0 完全对得上。
  • 斜坡峰值 = 154 乘 257 = 39578,与面板上的“1024 项/16 位(0-39578)”完全对得上。
  • 中灰第 128 项三通道分别为 75、75、74,均值为 74.67,取整为 75,与面板上的“平均输出亮度 75.0”对得上。
  • 暗部削波 3 格:亮度是乘性缩放,输入 0 乘任何系数都是 0,三通道首项全为 0,所以是 3 而不是 1。
  • 高亮削波 0 格:154 与 153 都不到 255,一个通道也没碰到天花板。
  • 单调递增为是:幂律、sRGB 传递函数、线性插值三者都保序。

这一组数字的价值不在好看,在于它们可以被独立复算。一个自检面板如果只是把参数原样回显,那是装饰;只有当它算出的数字能被第三方用同样的公式验证时,它才真的是自检。面板底部那行“主进程核对:一致 · 斜坡 1024 项 · LUT 256 级”是在做同一件事——渲染层自己算一遍,再把参数发给主进程算一遍,比较两边平均亮度的差是否小于 0.51,一致才敢打勾。

3.4 背光归一化的五种感知模型

多显示器场景下最头痛的不是亮度不够,是两台屏看起来不一样亮。物理亮度翻倍,人眼感觉不到翻倍,这是 Stevens 幂律与 Weber 与 Fechner 对数律描述的基本事实。所以归一化不能直接对百分比做加减,必须在“滑杆值”与“感知量”之间来回换算。

引擎里把这件事拆成两条纯函数:正向把物理比例换算成感知量,反向把感知量换算回滑杆值,然后提供五种模型供选。五种模型的名字与作用都被写进了数据里,界面直接取名字显示:

var MODELS = {
  stevens: { name: 'Stevens 幂律(指数 0.33)', exp: 0.33, fwd: fwdPower, inv: invPower },
  stevens45: { name: 'Stevens 幂律(指数 0.45)', exp: 0.45, fwd: fwdPower45, inv: invPower45 },
  weber: { name: 'Weber–Fechner 对数律', fwd: fwdWeber, inv: invWeber },
  srgb: { name: 'sRGB 编码近似', fwd: fwdSrgb, inv: invSrgb },
  linear: { name: '线性(不做感知修正)', fwd: fwdLinear, inv: invLinear }
};

指数 0.33 与 0.45 分别对应两种常见的 Stevens 拟合,前者是多数显示器亮度曲线研究里用到的值,后者更保守、压缩更弱。对数律用的底是 2:

function fwdWeber(y) { var v = clamp01(y); return v <= 0 ? 0 : Math.log(1 + v) / Math.log(2); }
function invWeber(p) { var v = clamp01(p); return Math.pow(2, v) - 1; }

正反两式互为逆,这一点比选哪个模型更重要。只要逆函数写错,用户看到的就是“点了归一化之后两台屏差得更多了”,而这类错误在白屏测试里几乎无法发现。

试算与写回被刻意分成两个通道。试算处理函数先把显示器列表做一次深拷贝,在副本上应用归一化结果,然后把前后两份状态一起返回:

var trial = JSON.parse(JSON.stringify(list));
var applied = N.apply(trial, res);
return {
  success: true,
  mode: req.referenceId ? 'reference' : 'target',
  rows: res.rows,
  quality: N.quality(res.rows),
  changes: normChanges(applied.changed),
  before: list.map(exportDisplay),
  after: trial.map(exportDisplay),
  beforeSummary: D.summary(list),
  afterSummary: D.summary(trial)
};

用 JSON 往返做深拷贝在这个场景里是安全的,因为显示器状态全是数字、字符串与布尔,没有函数、没有循环引用、也不会有日期对象。换成带日期或类型数组的结构,这条捷径立刻失效,所以它只能用在结构受控的地方。

返回体里同时给 before 与 after、beforeSummary 与 afterSummary,是让界面能做并排对比而不是只在用户点确认之后才知道结果。用户看到“归一后会变成什么样”再决定要不要写回,这个顺序比先改了再给撤销要友好得多。写回走另一个通道,只有确认之后才真正落到显示器状态并触发一次持久化。

quality 这一项的口径值得单独提出来。它只统计削波状态为 ok 的那些行,也就是真正落在可达区间内的行。目标亮度如果超出某台显示器校准量程能覆盖的范围,那一行会被标成削波,并且不计入质量评分——否则一台达不到目标的显示器会永远拖低整体评分,用户看到的是“归一化质量很差”,而真实情况是这台硬件本来就到不了。把不可达的排除在评分之外,评分才有意义。

3.5 天文时刻与定时计划

定时计划要有意义,前提是时间算得准。太阳高度角跨过某个阈值的时刻没有解析解,只能数值求解。项目用的是二分法,六十次迭代、容差百万分之一度:

for (i = 0; i < 60; i++) {
  /* 此处省略其余实现 */
  if (Math.abs(fm) < 1e-7) break;

六十次二分把初始区间压缩到原来的二的六十次方分之一,实际在三十次左右就已经收敛,剩下的迭代是给极端纬度留的余量。

地方时正午的求解更麻烦,因为它同时依赖经度与时差。项目先以 UTC 十二点作为初值,按经度乘四分钟回拨——地球每四分钟转一度,这是标准的地球自转角速度——再迭代十二次求时角,容差 0.0002:

for (i = 0; i < 12; i++) {
  /* 此处省略其余实现 */
  if (Math.abs(ha) < 0.0002) break;

时角容差 0.0002 弧度换算成时间大约是半秒,对分钟级的亮度计划足够,再往上压也不会让用户看到区别。

这里有个容易被忽略的工程细节:所有时刻统一返回 Unix 毫秒,不返回 Date 对象。原因写在注释里——Date 对象经 IPC 序列化后会退化成字符串,前端再算差值就得重新解析,而一旦格式约定不一致就会得到 NaN。统一用毫秒数字,跨进程传递零损耗,前端要格式化再自己 new Date 一次。这类决定看起来琐碎,但它消除的是一整类只在特定时区或特定语言环境下才复现的缺陷。

事件输出覆盖四个太阳角度:日出日落的负零点八三三度(考虑大气折射与太阳半径)、民用晨昏的负六度、航海晨昏的负十二度、天文晨昏的负十八度。四个角度各给起止两个时刻,共八个时刻,另外提供日出、日落、晨、昏四个别名,再加上昼长夜长分钟数与极昼极夜标记。真机截图的今日栏里,日出 06:58、正午 11:57、日落 16:55、昼长 597 分钟与夜 843 分钟,597 加 843 正好等于 1440,这是验证昼夜计算有没有漏掉整点进位的快速办法。

计划引擎在这套时刻之上叠了五种触发条件与三种动作。五种触发是固定时刻、日出、日落、民用昏末、闲置;三种动作是设亮度、套用预设、改电源。触发条件里还可以限定生效星期、加上相对偏移分钟、设优先级与冷却时间。同一分钟内的多条计划按优先级只执行一条,其余记录为被抑制并附理由:

function resolve(scheduleRows, toleranceMs) {
  var tol = toleranceMs == null ? 60000 : toleranceMs;
  var rows = (scheduleRows || []).slice().sort(function (a, b) { return a.time - b.time; });
  /* 此处省略其余实现 */
      g.items.sort(function (a, b) { return b.priority - a.priority || String(a.planId).localeCompare(String(b.planId)); });
      fired.push(g.items[0]);
      g.items.slice(1).forEach(function (it) {
        suppressed.push({ planId: it.planId, name: it.name, time: it.time, reason: '与「' + g.items[0].name + '」同时触发,优先级 ' + it.priority + ' 低于 ' + g.items[0].priority });
      });

分组比较的是与组首锚点的距离,不是与上一条的距离。这两种写法的区别在于会不会出现“链式合并”:如果逐条比较,零点、五十秒、一百秒三条会被串成一组,明明首尾差了一百秒。以锚点比较则不会。优先级相同时用计划编号的字典序兜底,这条看似多余的比较是为了让排序结果稳定——不稳定排序会让同一份配置在两次运行里给出不同结果,而用户会把这当成随机行为。

窗口取的是六十秒容差,也就是一分钟。这样“同时触发”的判定就是“落在同一分钟内”,与常规的心智模型一致,不需要用户去理解毫秒。

下一次触发的计算向后看七天,每天排一次时间表,只要时间晚于当前就纳入候选,第一天找到就返回并附带天数偏移:

function nextFire(plans, nowMs, geo, horizonDays) {
  var days = clampInt(horizonDays, 1, 30, 7);
  /* 此处省略其余实现 */
  for (d = 0; d < days; d++) {
    var day = new Date(Number(nowMs) + d * 86400000);
    r = todaySchedule(enabled, day, g);
    for (i = 0; i < r.rows.length; i++) {
      t = r.rows[i];
      if (t.time <= Number(nowMs)) continue;
      if (!best || t.time < best.time) best = t;
    }
    if (best) return { ok: true, next: best, withinDays: d };
  }
  return { ok: true, next: null, withinDays: days, note: enabled.length ? '查找 ' + days + ' 天内没有待触发的时刻' : '没有启用中的计划' };
}

七天窗口是为了周末计划留余地:只给周一早上设了计划的用户,在周五晚上点开界面仍然能看到下一次触发时间,而不是一句“今天没有计划”。找不到时也不是返回空,而是带上天数与理由,界面可以直接把这句理由显示出来。

闲置判定是一个纯粹的算术函数,输入当前时刻、最后活动时刻、要求的闲置分钟数,输出是否闲置、已闲置多少分钟、还差多少分钟:

function evaluateIdle(nowMs, lastActivityMs, idleMin) {
  var need = clampInt(idleMin, 0, 1440, 10) * 60000;
  var elapsed = Number(nowMs) - Number(lastActivityMs);
  if (!isFinite(elapsed)) return { idle: false, elapsedMin: 0, needMin: Math.round(need / 60000), remainingMin: 0 };
  return {
    idle: need > 0 && elapsed >= need,
    elapsedMin: Math.round(elapsed / 60000),
    needMin: Math.round(need / 60000),
    remainingMin: Math.max(0, Math.round((need - elapsed) / 60000))
  };
}

闲置分钟填 0 时永远不判定闲置,而不是立刻判定闲置,这个约定避免了“设 0 结果一进去就调暗”的惊吓。真机截图里那一行显示为“活跃 · 距离暗还有 10 分钟”,正好是默认十分钟且刚启动的状态。这个函数的返回值里同时还给了已用与剩余,界面才可能写出这样一句人话。

3.6 配置迁移、命令行与五格式导出

配置是这个应用里唯一有版本概念的东西。当前 schema 标识是 twinkletray-shell/1,旧版本登记在迁移表里,映射关系写成了可读的箭头串:

var SCHEMA = 'twinkletray-shell/1';
var LEGACY_SCHEMAS = { 'twinkletray-shell/0': ['screens→displays', 'schedule→plans'] };

零版本把显示器数组叫 screens、把计划数组叫 schedule,一版本改成了 displays 与 plans。迁移表的价值不只在于自动改名,还在于能把“迁移了什么”告诉用户。注释里特意提了一句顺序问题:migrate 会把 schema 改写为当前版本,所以迁移提示必须在改写之前采集,否则等到校验阶段再去比版本,已经是当前版本了,提示永远不出现。

校验是一条条具体规则,不是笼统的一句“配置无效”。经纬度越界、模型名不识别、显示器缺少标识、亮度等五个字段超出 0 到 200、量程上下限颠倒、预设引用了不存在的显示器、预设亮度越界、快捷键动作不识别、组合键无法解析、重复绑定——每一条都返回带对象与字段的自然语言句子,导入失败的提示因此是可以直接照着改的。

导入不是覆盖,而是有策略的合并。合并结果里带一个模式字段与一份冲突清单,用户能看到哪些项被换掉了、哪些项被保留了。这个设计解决的是一个很实际的问题:用户拿着别人的配置想抄一部分,直接覆盖会把自己的快捷键全丢掉,而合并则保留本地独有项。

命令行是一等公民,不是摆设。十个命令分别是列表、读取、设定、调高、调低、电源、预设、计划、导出、帮助:

var CLI_COMMANDS = ['list', 'get', 'set', 'inc', 'dec', 'power', 'preset', 'plans', 'export', 'help'];

解析器做三件事:按空白与引号分词、按已知命令名定位命令、再按数字与文字分别处理参数。数字参数用于 set 与 inc 与 dec,文字参数用于 preset 与 export,显示器目标既可以是具体标识也可以是 all。解析成功之后还会生成一句人话描述,让用户按回车之前就确认“我是要执行这个”:

function runCli(input) {
  var parsed = C.parseArgv(input);
  var desc = C.describeCommand(parsed);
  if (!parsed.ok) return { success: false, error: parsed.errors.join(';'), command: parsed.command, description: desc, help: C.CLI_HELP };
  var out = { success: true, command: parsed.command, description: desc, data: null, result: null };
  switch (parsed.command) {
    case 'list': /* 此处省略分支实现 */
    case 'get': /* 此处省略分支实现 */
    case 'set': /* 此处省略分支实现 */
    case 'inc':
    case 'dec': /* 此处省略分支实现 */
    case 'power': /* 此处省略分支实现 */
    case 'preset': /* 此处省略分支实现 */
    case 'plans': /* 此处省略分支实现 */
    case 'export': /* 此处省略分支实现 */
    default: out.data = { help: C.CLI_HELP };
  }
  return out;
}

所有写类命令的执行结果都走同一个汇总函数,所以命令行改的亮度和界面上拖的滑块走的是同一条持久化与日志链路,不存在两套记账。文件头的注释把这条原则写成了半句话:硬件动作只记录不外发。

导出有五种格式,分别是配置 JSON、计划或归一化 CSV、CUBE、斜坡 JSON、以及带序号的 LUT CSV:

var EXPORT_KINDS = ['json', 'csv', 'cube', 'ramp', 'lut'];

CSV 一种格式承载两种内容,靠作用域参数区分:作用域是计划时导出计划表,否则导出归一化结果表。默认文件名由类型与日期拼成,配置是 twinkle-tray-config-日期.json,CUBE 与 CSV 与斜坡各有各的前缀,扩展名单独处理——斜坡的内部类型是 ramp 但落盘必须写成 json,否则双击打不开。

写盘的顺序也值得一提:先取文本、再弹对话框、最后写文件,对话框取消则整条链路直接返回取消状态,不产生任何空文件。写成功之后立刻把所在目录加入白名单并持久化,下次用户往同一个目录导出就不用再选一次。这三步加起来,才是一个把用户当成年人的导出流程。

四、鸿蒙稳定性适配

4.1 缺陷台账:四类问题

这一节不做修饰。把代码通读一遍之后能找到的问题就这四条,按影响面排序:

编号问题影响面当前处置
D1缩放因子未经格式化直接拼进字符串明细表与卡片显示 1.899999976158142x待修,统一保留两位小数
D2闲置判定只统计鼠标与触摸,不统计键盘长时间打字会被判定为闲置待修,补齐活动源
D3四个导出函数零调用无功能影响,增加阅读与维护成本待清理
D4结构层没有内容安全策略声明网页层缺少一道兜底约束建议补充,不是硬阻塞

四条里没有一条会导致功能不可用。这不是因为代码写得完美,而是因为核心链路的结构选对了:主进程是唯一的真相源,渲染层只读不算,引擎是纯函数,三层之间的边界清晰,所以错误只能停留在表现层,很难渗到数据层。

4.2 三个典型根因

D1 是最容易被当成“小毛病”而一直不修的那类。明细表里的那一列是直接拼字符串拼出来的,既没有取整也没有保留位数,于是系统给的浮点原值原封不动地上了屏:

td(row, d.width + '×' + d.height + ' @' + (d.scaleFactor || 1) + 'x', 'w-res');

后面的卡片信息行也是同样的写法,把缩放因子、通道名、峰值亮度三个字段用中点拼成一句。屏上显示的就是 1642×1094 @ (0, 0) · 1.899999976158142x · 软件 gamma · 未知 nit。这一个数字把整套界面的可信度拉低了一截——用户不一定在意缩放是 1.9 还是 2,但他们能看出软件没做完。修复很便宜,演示也不影响,但既然这类细节会持续消耗信任,就应该按缺陷管理而不是当作装饰。

D2 是真缺陷,因为它会改变行为。闲置触发的计划依赖“多久没活动”这个输入,而活动的定义在代码里被窄化成三种鼠标类事件:

['mousedown', 'wheel', 'touchstart'].forEach(function (name) {
  document.addEventListener(name, function () { St.lastActivity = Date.now(); }, { passive: true });
});

键盘事件走的是另一个处理函数,职责是快捷键,它并不刷新活动时间。于是场景就很具体了:用户连续写了四十分钟文档,一次鼠标也没碰,闲置计时器认为他四十分钟没活动,到点就把屏调暗。这不是理论上的可能,这是最容易复现的一类误判。修复只需要把键盘事件也纳入活动源,或者在活动监听里补一个 keydown 分支;但在修复之前,闲置计划这个功能应当被理解为“只对鼠标用户可靠”。

D3 是工程卫生问题,但它的发现过程值得记下来。判定方式是数出现次数:一个导出函数在源码里至少出现三次——函数定义一次、导出表里写名字两次(键与值同名)——任何第四次的出现才是真正的调用。按这个口径扫一遍,mapPixel、parseCube、sortList、addDays 四个都恰好只有三次,并且在主进程、渲染层、其他引擎里一次也没被提到。它们不是预留接口,是开发过程中改主意留下的痕迹。

D4 与前三者不同,它的位置不在代码里,而在代码之外。结构文件的头部只有字符集、视口、标题、样式表四个声明,没有内容安全策略。网页层既然只在本地加载、且渲染层不使用 innerHTML、不使用原生弹框、只走 IPC,风险面已经不大了,但一道显式策略的价值在于它把“不该做的事”变成“做不了的事”。同类项目里已经有把连接白名单收到 none、脚本只允许 self 的写法,这份结构补上同样的九条指令并不难,属于上架前值得做一次的加固。

4.3 样式表的三条禁项与三档断点

样式文件 875 行、24877 字节,开头第二行就把规矩立在那里:配色变量全部收在根选择器里,不使用固定定位、不使用 transform、不使用动画与过渡。这些规矩不是风格偏好,是适配结论。

固定定位在窗口可任意缩放的桌面环境里容易与合成层错位,尤其在 2in1 设备切换形态时;transform 会开启新的合成层,配合滤镜类效果容易出现一帧闪烁;动画与过渡在低功耗设备上会拉高功耗,而一个亮度工具自己变成耗电大户就很讽刺。所以弹层全部放在应用根容器内做绝对定位,关于对话框、目录选择、确认弹框都复用同一个弹层宿主,用类名切换显隐。全文实测确实零处固定定位、零处过渡、零处动画、零处关键帧、零处强制优先级。

三档断点覆盖的是一块屏幕从宽到窄的完整过程:

  • 1280 像素以下:状态坞宽收 226 像素,导航侧栏宽收 172 像素。
  • 1120 像素以下:状态坞宽度归零并从布局中隐藏,双列网格与预览舞台内的双栏全部降为单列。
  • 860 像素以下:侧栏再收 140 像素,顶栏的副标题与当前配置文件提示隐藏,卡片网格降为单列。

这三档设计的共同点是只改尺寸与可见性,不改层级也不改定位方式。上真机之后窗口从全屏拖到半屏、再拖成窄竖窗,布局始终是三列到两列到一列平滑收敛,没有出现元素跳位或者被裁切。

配色用的是一套成熟的暗色方案,四个自定义属性块分别定义基础色、状态坞覆盖值、以及两档断点内的覆盖值。变量收在根上而不是散在各地,好处是断点只需要改两个宽度变量,其余所有用到这两个宽度的组件自动跟着变——这比在每个组件里写一遍断点要少写很多行,也不会出现某个组件忘了改。

4.4 上架前需要替换的四类内容

第一类是签名材料。构建配置里的证书路径、证书文件名、密钥别名、密文密码全部指向当前开发机,换机即失效。上架必须换成正式签名,并且建议把这份配置从版本控制中拆出去,只保留字段形状而不提交真实凭据。

第二类是包名。当前包名沿用壳项目的公共前缀,如果要作为独立应用上架,需要改成自己的域名倒写形式。包名一旦变更,用户数据目录跟着变,之前存下的配置、偏好、日志全部读不到,所以这个动作必须在首次发布前完成,不能等到发版后才发现。

第三类是应用名与图标文案。应用侧的标签走资源引用,界面里的标题、关于对话框里的项目名、状态栏右侧的默认文案是硬编码的中文字符串,需要与最终上架名称逐处对齐。这类遗漏在上架审核里很常见,而且很尴尬。

第四类是权限理由。权限清单共二十八条,其中带有理由字符串的只有十一条,剩下十七条没有任何理由。如果上架的权限说明必须逐项填写,这十七条会直接卡住审核,需要按每一条的真实用途补齐。这一类工作量大但机械,放在提交前一周做最合适。

五、构建与部署

图 1 显示器面板:单台卡片徽章标注主显示器,副行把分辨率、位置、缩放、通道、峰值亮度拼在一行;滑块 60% 下方是开启、待机、关断与加减五个按钮;明细表十一列依次是序号、名称、类型、分辨率与缩放、通道、亮度、校准下限、校准上限、峰值亮度、电源、操作;右栏当前状态与今日日出日落并列

图 2 亮度预览面板:七个滑块覆盖亮度、对比度、伽马、色温与三色增益,中部是阶跃测试与含色阶图的并排预览,下部左侧是传递函数曲线、右侧是六项 LUT 自检,底部两个导出按钮与主进程核对结果并列

图 3 关于对话框覆盖在预览面板之上,三段内容依次是开源声明、免责声明与完全开源,声明里直接写出鸿蒙运行时不暴露 DDC/CI 与系统 gamma ramp 接口、本壳不包含上游任何源代码

5.1 产物与构建日志

产物落在 electron 模块的构建输出目录下,四个文件加一个映射子目录:签名包 195512284 字节、未签名包 194051595 字节、包信息描述 752 字节、以及 sourceMaps.map 572033 字节。签名前后相差 1460689 字节,这部分是签名块与包内摘要信息,不是代码。

构建日志 808709 字节、9425 行。结论行一共五条,全部成功,没有一条失败:

[2026-11-16T15:30:41.482] [INFO] debug-file - BUILD SUCCESSFUL in 3 s 841 ms
[2026-11-16T15:32:05.077] [INFO] debug-file - BUILD SUCCESSFUL in 4 s 248 ms
[2026-11-16T15:34:09.160] [INFO] debug-file - BUILD SUCCESSFUL in 4 s 212 ms
[2026-11-16T15:36:28.117] [INFO] debug-file - BUILD SUCCESSFUL in 4 s 420 ms
[2026-11-17T14:58:25.505] [INFO] debug-file - BUILD SUCCESSFUL in 18 s 975 ms

同一个工程,前四次的构建分别是三秒八百多毫秒到四秒四百多毫秒,第五次是十八秒九百多毫秒。差距不是偶然:前四次是连续调试期内的增量构建,缓存全热,只重打了变动部分;第五次隔了将近一天且中间换过页面内容,缓存大面积失效,于是回到接近全量的耗时。所以判断构建耗时一律拿全量那次当基准,拿增量那次当基准会误以为构建很快,一换机器就怀疑人生。

读日志有个坑必须提一下:直接用关键字计数量失败与报错会得出荒谬的结论。工具链在加载阶段会打上大量调试行,其中包含形似错误码的字符串,用宽泛的正则去数会把它们全算进去,得出几十条失败的假象。正确的做法是只抓结论行,也就是两种固定前缀的成功与失败行,再单独数编译器告警。按这个口径,本工程的最终结论是失败零条,告警一千七百零三条。

告警主要来自 web_engine 的适配层,集中在 ArkTS 类型与资源引用上,与网页层业务无关。另外有五行关于目标版本未显式声明的提示,五行关于资源完整性的提示。这些都属于壳项目共有的已知状态,要么在配置里显式声明消掉,要么在说明文档里写清楚。两种处理都行,但不能装作没看见——上架时会有人看日志。

5.2 体积构成

签名包将近两百兆,这个数字对网页层只有三十万字节的应用来说有点刺眼。拆开看就清楚了:四个原生库合计 174100264 字节,占签名包的 89.05%,剩下那百分之十才是网页层与框架资源。

  • 运行时主体 167471912 字节,占包体积 85.66%。
  • 适配库 2621200 字节,占 1.34%。
  • 媒体库 2181528 字节,占 1.12%。
  • 运行库 1825624 字节,占 0.93%。

运行时主体一个文件就占了整个应用的六分之五,这就是壳方案的真实成本。在这种体积结构下讨论“优化应用体积”意义不大,因为可优化空间上限不到百分之十一,而真正的大头由运行时版本决定,不由应用代码决定。要降低体积只能换运行时版本或裁剪运行时能力,那是另一个层面的决策。

剥离掉了多少东西也能算一算。未剥离的运行时主体与适配库分别是 1143668440 与 15494016 字节,剥离后是 167471912 与 2621200,两者合计从 1159162456 降到 170093112,减掉了 989069344 字节,接近一半。两个库的压缩比分别约为六点八三倍与五点九一倍。这个环节没有开关可调,构建工具默认完成,但值得把数字记下来:如果哪一天包体积突然涨到四百多兆,第一个要查的就是剥离步骤是不是被跳过了。

还有一个容易忽略的事实:网页层三十万字节里,引擎六个文件占百分之三十,界面四个文件占六成以上。也就是说即使把六个引擎全部删掉,包体积也只减少万分之五左右。

5.3 权限清单与设备形态

权限清单共二十八条,覆盖网络、证书、运行锁、存储、屏幕、设备信息等多个类别。其中带有理由字符串的仅十一条,并且这十一条都配了场景说明。剩下十七条只声明了名称,没有理由。

从功能角度看,这些权限里真正必需的是存储与屏幕两类,网络类在这个壳里其实用不上——应用不发任何网络请求,也不做远程同步。但权限清单是壳项目共用的,清不清、怎么清,要服从整个壳的统一策略,不建议单个应用自行删减,否则升级壳版本时又得补回来。正确做法是把用不到的那部分在审核材料里说明清楚。

设备形态声明为 2in1 与 tablet 两类,符合桌面形态与可拆卸平板形态。窗口尺寸不是写死的,而是启动时取主显示器的可用工作区宽高,按比例计算,再设置最小尺寸。这一条在真机上很有用:不同设备的工作区差很多,写死一千六百像素宽会让小屏设备上首屏就超出边界。

多实例上限为一,意味着系统里同时只会有一个实例持有显示器状态。这是亮度类工具的硬约束——两个实例各自维护一份调色板与计划表,互相覆盖只是时间问题。

六、常见问题与解决方案

Q1 构建日志显示成功,装到设备上启动就崩溃,只提示找不到某个动态库

问题现象:构建日志里结论行是成功,产物也能正常安装,但启动到一半直接退出,系统日志里只能看到找不到某个动态库的提示,看不出是哪一步出的问题。

根因分析:绝大多数情况是原生库被按需收集机制裁掉了。默认策略只收集被静态引用到的库,而这套壳的运行时主体是通过运行时动态加载的,静态分析看不到引用关系,于是它就成了“没用的库”被剔除。构建阶段不报错,因为裁掉不影响链接;只有运行时才报错,因为那时才去开文件。

解决方案:在产品配置里把原生库收集开关打开,强制全量打包。如果已经打开还是崩,就去对比产物里四个库的大小与本地未剥离版本,看是不是剥离步骤把某个库处理成了零字节或者根本没落进包。

教训:构建成功与运行成功是两个不同层级的交付标准。凡是依赖运行时动态加载的东西,就不能交给静态分析去决定去留。

Q2 亮度已经调到 20%,屏幕的实际亮度一点没变

问题现象:滑杆拖到 20,界面上的平均亮度、亮度跨度、预览表达式全部跟着变了,但眼睛看到的屏幕亮度没有变化。

根因分析:这不是缺陷,是能力边界。壳内软件通道只作用于应用自己的预览面,不碰显示器背光,也不写系统色彩配置。真机截图里状态栏那句“DDC/CI 不可用”就是在说这件事。在物理意义上,应用没有向显示器发送任何东西的通道。

解决方案:把预期调到正确的位置上——用亮度预览面板看调参效果,用导出功能把 LUT 或斜坡拿到别处去用。如果你确实需要改变系统亮度,那只能依靠系统自带的显示设置,本应用替代不了它。

教训:一个工具做到什么程度,应该在界面上一句话说完。把做不到的事写清楚,比把它藏起来然后让用户去猜,成本低得多。

Q3 预览面板的滑杆值,和显示器面板的亮度数值不一样

问题现象:预览面板里亮度是 60,切到显示器面板看亮度也是 60,但拖动预览面板的滑杆到 30 后返回,显示器面板还是 60。

根因分析:两处是不同的状态。预览舞台上的七个滑杆是一组独立的试算参数,它们只影响画布与曲线,不影响显示器对象;显示器对象上的亮度才是持久化的真实状态。这两者之间不是实时双向绑定,而是靠“写入该显示器”这个动作显式桥接。

解决方案:在预览面板里把参数调好,再点写入该显示器,选择目标为单台或全部,一次性把七项数值并进去。批量写入通道会逐项比对旧值,只把真正变了的项计入变更清单。

教训:试算与生效分开是设计,不是缺点,但界面必须把“当前在试算”这个状态说清楚,否则用户会把两个数字的差异当成 bug。

Q4 导入别人给的配置后,自己的快捷键全被换掉了

问题现象:导入一份同事分享的配置,显示器与计划都对上了,但自己辛苦设的四条快捷键全部变成了对方的。

根因分析:导入默认采用来件优先的合并策略。合并列表存在,但不等于每一项都会提示冲突,快捷键这类“同名即覆盖”的列表在合时不会有任何感觉。另外旧版本配置的字段名不同,迁移器会自动改名,用户看到的是“凭空多了几条陌生的绑定”。

解决方案:导入时改用保留本地的策略,或者先备份当前配置再导入。如果只是想抄对方的计划,就不要导整份配置,而是导计划 CSV,它对快捷键零影响。

教训:合并策略必须是一个用户可选的决定,而不是一个写在代码里、只在文档里提一句的默认值。

Q5 算出的日出日落时间跟手机天气应用差了一两分钟

问题现象:同一个城市,应用里日出 06:58,手机上写的是 07:00,晚上又反过来差一分钟。

根因分析:口径不同。这里的日出采用负零点八三三度的太阳高度角,对应标准大气折射与太阳视圆面半径的经典取值;不同软件对是否包含这零点八三三、是否计入海拔、是否采用瞬时太阳赤纬还是日内平均赤纬,选择都不同。两分钟的差异完全在合理区间内。

解决方案:不要去对齐某个具体应用,而是确认内部自洽——昼长与夜长相加必须等于 1440 分钟,四个晨昏角度的时刻必须单调递增,正午必须落在日出与日落之间。这三条检查全过,数值就是可信的。

教训:天文类算法不存在唯一正确值,只有明确声明的口径。声明口径比追求“和别人一样”重要。

Q6 导出时提示路径不在本应用已授权的目录内

问题现象:从命令行导出、或者从日志里复制了一个路径去导入,结果被一句“该路径不在本应用已授权的目录内,请先用对话框选择导出目录”拦住。

根因分析:这是路径守卫在正常工作。白名单里只有应用目录、用户数据目录、以及用户曾经通过对话框选过的目录。直接给一个任意路径,即使文件真的存在,也不在授权范围内。守卫抛的是带错误码的异常,不是异常返回,所以它会直接终结本次调用。

解决方案:先点一次导出并选好目录,该目录会被加入白名单并持久化,之后对这个目录下的读写都会被放行。如果只是想试一下随包样例,直接走样例列表,那个目录本来就在白名单里。

教训:路径白名单一旦做成默认放行的软校验,就等于没有。抛异常的做法看起来很硬,但它保证的是每一次文件读写都真的过了检查。

Q7 设了定时计划,到点了却没有自动执行

问题现象:新建了一条 21:30 的计划并启用,到了时间什么都没发生,回到界面刷新一下才看到今日时间表里有这条。

根因分析:触发调度住在渲染层,不在主进程。界面每二十秒打一次点,每次检查今日已发出的计划里有没有落在当前时刻前二十五秒内的,命中且过了冷却就执行。这意味着两个前提:窗口必须处于打开状态,并且本轮检查与目标的间隔不能超过二十五秒。窗口关掉、应用被系统回收,都不会有任何东西在后台跑。

解决方案:把二十五秒的命中窗口看作设计约束而不是容错空间——它比二十秒的轮询间隔宽五秒,刚好能保证不会漏掉某一分钟。需要长时间无人值守的场景,就不要依赖这个壳内的调度,而应该把计划导出成 CSV 交给外部调度去跑。

教训:一个前端定时器很便宜,但它创造的是“开窗才生效”的承诺。这类隐含前提必须在界面上写出来,否则用户会把功能当成不灵。

七、总结

把这套适配拆开看,真正有价值的不是某一个算法,而是分层方式与自检习惯。七个模块的落点与对应章节如下:

模块实现要点章节
显示器枚举与量程校准系统事实与本地偏好按标识合并,通道三值标记3.2
伽马 LUT 与斜坡幂律亮度、sRGB 往返、Kelvin 近似、256 级转 1024 项乘 2573.3
双预览通道CSS 滤镜走合成器,LUT 画布逐像素3.3
背光归一化五模型正反可逆,质量只统计可达行3.4
天文与定时二分求事件、时角迭代求正午、锚点分组解冲突3.5
配置与命令行schema 迁移、十命令解析、五格式导出3.6
路径纪律归一化比较、白名单持久化、异常式拦截3.1

第一,把不可用的能力显式化,比伪造一个可用性要好。这个应用从文件头注释到侧栏脚注、到状态栏、到关于对话框,四处都在说同一件事:硬件通道不可用,调的是壳内预览。这件事让整个项目的后续所有决定都变得简单——既然不可能真的降低背光,那么把功夫花在换算链的准确性、预览的保真度、以及导出结果的可用性上,就是唯一正确的方向。相反,如果在界面上做得像真的能控硬件,那么每一条用户反馈都会变成无效争论。

第二,数值算法必须只有一份实现,并且要有能被独立复算的自检。六个引擎用同一套包装同时活在浏览器与 Node 两个运行时里,主进程与渲染层从不各写一份。自检面板给出的六个数字也没有一个是装饰:恒等残差 102 可以手算出来,斜坡峰值 39578 可以手算出来,平均亮度 75 可以手算出来。只有当每一个显示出来的数字都能被第三方用同样的公式验证时,自检才真的是自检,而不是把参数原样打印一遍。

第三,主进程做唯一真相源,渲染层只读不算。所有写操作收敛到同一个汇总函数,返回值形状固定,硬件结论恒为否,预览表达式现算不缓存;渲染层所有 IPC 只走一个出口,连异常都统一转成结构化失败。这套结构带来的直接好处是缺陷只能停在表现层:本文找到的四条问题里,三条是界面细节、一条是缺一道声明,没有一条能污染数据。

上架前必须做完的四件事也在这套结构里摆着:换掉指向本机的签名材料与密文凭据,改掉沿用的公共包名并同步应用名与界面文案,补齐十七条没有理由的权限说明,清一遍 web_engine 里与业务无关的适配模块与告警。四件都是机械活,但少了任何一件,提交都过不了。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐