Files

duanshuwen 301f7d33ed feat: implement launch at startup functionality in zn-ai

- Added a new setting for "launch at startup" in the GeneralSettingsPanel.
- Integrated the setting with the existing settings store and IPC mechanisms.
- Implemented platform-specific logic for enabling/disabling startup behavior in the main process.
- Created a new service for managing launch at startup settings, including Linux desktop entry creation.
- Added unit tests for the new functionality and ensured existing tests are updated accordingly.
- Updated i18n messages for the new setting in English, Chinese, and Japanese.

2026-04-20 23:29:10 +08:00

13 KiB

Raw Blame History

开机自动启动功能复制计划

1. 目标与结论

目标是在 zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx 中复制 ClawX 的“开机自动启动”能力，并把视觉位置排在“语言设置”后面、“网关设置”前面。

先给结论：

ClawX 的“开机自动启动”不是单纯的前端 Switch，而是“设置持久化 + 主进程 OS 级生效 + 启动时回放同步”的完整链路。
zn-ai 已经具备可复用的设置基础设施：settingsStore、config-service、SET_CONFIG/GET_CONFIG IPC、/api/settings 本地路由。
zn-ai 当前没有 launchAtStartup 配置键，也没有任何 OS 级自启动应用逻辑。
这次复制不需要新增复杂的状态 hook、也不需要新增 preload 专用桥接；最小可行方案是复用现有设置存取链路，只补 launchAtStartup 配置模型和主进程副作用。

2. ClawX 现有实现拆解

2.1 渲染层 UI 结构

ClawX/src/pages/Settings/index.tsx 中，“开机自动启动”位于通用设置区块内，紧跟在语言设置后面，位于 Gateway 区块前：

主题按钮组
语言按钮组
launchAtStartup 开关
Separator
Gateway 区块

对应 UI 代码位置：

ClawX/src/pages/Settings/index.tsx:528
ClawX/src/pages/Settings/index.tsx:545

交互特征：

左侧是标题和说明文案。
右侧是一个 Switch。
没有额外保存按钮，属于“切换即保存”。
没有单独 loading/error 状态，也没有回滚提示。

2.2 渲染层状态链路

ClawX 渲染层把 launchAtStartup 放在 settings store 中统一管理：

字段定义：ClawX/src/stores/settings.ts:19
默认值：ClawX/src/stores/settings.ts:72
初始化从 /api/settings 拉取：ClawX/src/stores/settings.ts:86
setter 里直接调用 /api/settings/launchAtStartup：ClawX/src/stores/settings.ts:132

实现特征：

先本地 set({ launchAtStartup })，再异步请求主进程。
请求失败时静默吞掉，没有回滚。
这和 gatewayAutoStart、theme、language 是同一类“轻量即改即存”模式。

2.3 i18n 文案

ClawX 使用 settings.appearance 下的两个键：

launchAtStartup
launchAtStartupDesc

对应位置：

中文：ClawX/src/i18n/locales/zh/settings.json:12
英文：ClawX/src/i18n/locales/en/settings.json:12
日文：ClawX/src/i18n/locales/ja/settings.json:12

2.4 主进程与 Host API 链路

ClawX 的主进程实现分成 4 层：

持久化配置
- ClawX/electron/utils/store.ts:24
- launchAtStartup 被定义为 AppSettings 字段，默认值为 false
设置路由
- ClawX/electron/api/routes/settings.ts:27
- PUT /api/settings
- PUT /api/settings/launchAtStartup
- POST /api/settings/reset
- 只要 patch/key 触达 launchAtStartup，都会执行 syncLaunchAtStartupSettingFromStore()
OS 级应用逻辑
- ClawX/electron/main/launch-at-startup.ts:1
- Windows/macOS：app.setLoginItemSettings({ openAtLogin, openAsHidden: false })
- Linux：写入或删除 ~/.config/autostart/clawx.desktop
- 错误只记录日志，不向上抛出
启动时同步
- ClawX/electron/main/index.ts:298
- 应用启动后会从 store 读取 launchAtStartup，再回放到操作系统

2.5 测试覆盖

ClawX 已经对 OS 级逻辑做了单元测试：

ClawX/tests/unit/launch-at-startup.test.ts

覆盖点：

Windows setLoginItemSettings
macOS setLoginItemSettings
Linux .desktop 文件创建/删除
非支持平台不抛异常

3. zn-ai 当前现状

3.1 已有可复用能力

zn-ai 已经具备以下基础：

通用设置 UI：zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx
设置页容器：zn-ai/src/pages/Setting/index.tsx
自定义开关组件：zn-ai/src/pages/Setting/components/ToggleSwitch.tsx
全局设置 store：zn-ai/src/stores/settings.ts
配置持久化：zn-ai/electron/service/config-service/index.ts
通用设置本地路由：zn-ai/electron/api/routes/settings.ts
主进程初始化入口：zn-ai/electron/main.ts

3.2 关键差异

和 ClawX 相比，zn-ai 当前的关键差异有 5 个：

launchAtStartup 不在 ConfigValueMap 中
- zn-ai/src/types/runtime.ts
- zn-ai/runtime-shared/lib/constants.ts
- zn-ai/runtime-shared/lib/types.ts
settingsStore 只管理 gatewayAutoStart，没有 launchAtStartup
- zn-ai/src/stores/settings.ts
config-service 默认配置里没有 launchAtStartup
- zn-ai/electron/service/config-service/index.ts
主进程没有 OS 级开机自启动服务
- zn-ai/electron 下目前不存在 launch-at-startup 模块
zn-ai 的设置主写路径不是 Host API，而是 SET_CONFIG IPC
- zn-ai/src/stores/settings.ts
- zn-ai/electron/service/config-service/index.ts

这意味着：

不能只在 /api/settings 路由里补副作用。
必须覆盖到 SET_CONFIG 这条实际写入通路，否则 UI 开关会“写进配置但不生效到系统”。

4. 复制范围与非目标

4.1 本次复制范围

只复制 ClawX 的这一项能力：

“开机自动启动”开关
配套说明文案
配置持久化
主进程 OS 级应用
应用启动时回放同步

4.2 明确不做的内容

这次不要把以下内容一起带进来：

startMinimized
minimizeToTray
Gateway 自动启动
代理设置
日志目录打开
开发者模式
Telemetry

原因：

这些不是 ClawX“开机自动启动”功能的必要组成。
一起迁移会把范围从“复制单一功能”扩大成“重新设计通用设置”。

5. zn-ai 的最小复制方案

5.1 UI 方案

在 zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx 中，把新行插在语言设置后面：

保持和现有设置页一致的 border-b 行布局
左侧：标题 + 描述
右侧：复用 ToggleSwitch

建议结构：

主题设置
语言设置
开机自动启动
Gateway
更新

说明：

不需要新建卡片。
不需要新建 section header。
不需要新建独立 hook。
这项功能足够简单，沿用 themeMode/language 的 props 传递模式即可。

5.2 状态与设置层方案

推荐在 zn-ai/src/stores/settings.ts 中新增：

launchAtStartup: boolean
updateLaunchAtStartup(launchAtStartup: boolean, persist = true)

并在 SettingsState、createInitialState()、hydrate() 中补齐：

读取 CONFIG_KEYS.LAUNCH_AT_STARTUP
默认值 false

GeneralSettingsPanel 通过 props 收到：

launchAtStartup
onLaunchAtStartupChange

Setting/index.tsx 负责从 useSettingsStore 取值并透传。

5.3 配置模型方案

需要同时修改以下位置，保证 key 一致：

zn-ai/runtime-shared/lib/constants.ts
zn-ai/runtime-shared/lib/types.ts
zn-ai/src/types/runtime.ts
zn-ai/electron/service/config-service/index.ts

建议新增 key：

launchAtStartup

默认值建议：

false

原因：

与 ClawX 保持一致。
对桌面应用更保守，避免首次启动时直接注册系统自启动。

5.4 主进程方案

建议新增模块：

zn-ai/electron/service/launch-at-startup/index.ts

职责直接对齐 ClawX，但把应用标识替换为 zn-ai 当前产品信息：

Windows/macOS
- app.setLoginItemSettings({ openAtLogin: enabled, openAsHidden: false })
Linux
- 写入或删除 ~/.config/autostart/*.desktop
- 不能直接照搬 clawx.desktop
- Name、Comment、桌面文件名需要改成 zn-ai 当前产品名

建议暴露两个函数：

applyLaunchAtStartupSetting(enabled: boolean)
syncLaunchAtStartupSettingFromStore()

5.5 副作用挂载位置

这是本次复制里最关键的实现点。

因为 zn-ai 当前 renderer 主要通过 SET_CONFIG IPC 写设置，所以副作用至少要覆盖两条路径：

SET_CONFIG / UPDATE_CONFIG
- 位置：zn-ai/electron/service/config-service/index.ts
- 当 key 或 patch 触达 launchAtStartup 时，调用 applyLaunchAtStartupSetting(...)
应用启动回放
- 位置：zn-ai/electron/main.ts
- await configManager.init() 之后调用 syncLaunchAtStartupSettingFromStore()

一致性建议：

zn-ai/electron/api/routes/settings.ts 也补齐同样的副作用。
虽然当前 UI 主通路不是走这个 route，但本地 Host API 应该与 IPC 行为一致。

6. 文件级改动清单

6.1 渲染层

zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx
zn-ai/src/pages/Setting/index.tsx
zn-ai/src/stores/settings.ts
zn-ai/src/i18n/messages.ts
zn-ai/src/types/runtime.ts

6.2 共享常量与类型

zn-ai/runtime-shared/lib/constants.ts
zn-ai/runtime-shared/lib/types.ts

6.3 主进程

zn-ai/electron/service/config-service/index.ts
zn-ai/electron/service/launch-at-startup/index.ts（新增）
zn-ai/electron/api/routes/settings.ts
zn-ai/electron/main.ts

6.4 测试

zn-ai/tests/launch-at-startup.test.ts（建议新增）

7. 关键风险与处理建议

7.1 双写路径风险

风险：

SET_CONFIG IPC 和 /api/settings route 都能改配置。
如果只给其中一条路径挂副作用，会出现“配置值正确但系统登录项没同步”的假成功。

处理：

两条路径都挂同一个 helper。

7.2 Linux 桌面文件元数据风险

风险：

直接复制 ClawX 的 clawx.desktop、Name=ClawX 会导致 Linux 桌面环境识别错误。

处理：

使用 zn-ai 当前产品名、可执行路径和桌面文件名。
优先通过 app.getName() / process.execPath 生成，而不是写死 ClawX 文案。

7.3 产品名文案不一致风险

风险：

package.json 中 productName 是 NIANXX，但前端文案里大量使用 ZN-AI。

处理：

本次设置说明文案优先使用“应用”或“系统登录后自动启动”这种泛化表达。
不在这次迁移里额外引入品牌命名统一改造。

7.4 静默失败体验风险

风险：

ClawX 的写法对失败是静默吞掉，用户可能看不出 OS 级注册失败。

处理：

第一版可以保持与 ClawX 相同的轻量体验。
如果后续需要提高可观测性，再补 toast 或错误文案，但这不属于这次最小复制范围。

8. 推荐实施顺序

Phase 1：主进程能力补齐

新增 launchAtStartup config key
新增 launch-at-startup 服务
在 config-service 和 /api/settings 中挂副作用
在 electron/main.ts 启动时回放同步

Phase 2：渲染层接入

settingsStore 增加 launchAtStartup
Setting/index.tsx 透传 prop
GeneralSettingsPanel.tsx 在语言设置后插入 UI
messages.ts 补三语文案

Phase 3：验证

typecheck
launch-at-startup 单元测试
手动验证设置页切换
手动验证 Windows/macOS/Linux 的系统登录项行为

9. 最小测试集合

建议至少覆盖以下 4 类验证：

单元测试
- Windows/macOS 调用 app.setLoginItemSettings
- Linux .desktop 创建/删除
配置链路测试
- 改写 launchAtStartup 后，configManager 中值已更新
渲染层回归
- 设置页中开关显示在语言设置后面
- 开关值能和 store 状态联动
启动同步验证
- 应用启动后能读取持久化值并重新应用 OS 级自启动

10. sub-agent 估算与分工

10.1 推荐数量

10.2 分工建议

Worker 1：渲染层与 i18n

负责文件：

zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx
zn-ai/src/pages/Setting/index.tsx
zn-ai/src/i18n/messages.ts

职责：

在语言设置后插入 UI
接入 launchAtStartup prop
补齐中英日文案
确保视觉风格与现有设置页一致

Worker 2：设置模型与配置链路

负责文件：

zn-ai/src/stores/settings.ts
zn-ai/src/types/runtime.ts
zn-ai/runtime-shared/lib/constants.ts
zn-ai/runtime-shared/lib/types.ts

职责：

新增 launchAtStartup 配置键和类型
在 store 中完成读取、更新、对外导出
保证 renderer 能通过现有设置链路读写该值

Worker 3：主进程自启动服务与测试

负责文件：

zn-ai/electron/service/launch-at-startup/index.ts
zn-ai/electron/service/config-service/index.ts
zn-ai/electron/api/routes/settings.ts
zn-ai/electron/main.ts
zn-ai/tests/launch-at-startup.test.ts

职责：

实现跨平台 OS 级自启动逻辑
把副作用挂到配置写入与启动同步节点
补齐最小单元测试

11. 最终建议

这次复制应严格控制在“ClawX 的 launchAtStartup 单功能迁移”范围内推进。

建议落地原则：

UI 只加一行，不做新的设置分组。
状态层只加一个布尔配置，不新建复杂 hook。
主进程只加一个独立服务，不顺手扩散到别的系统设置功能。
测试优先覆盖 OS 级副作用，而不是先写大量 UI 测试。

按这个方案推进，能以最小代价把 ClawX 的成熟能力复制到 zn-ai，同时避免出现“只做了开关外观、没有真正接到系统登录项”的伪完成状态。

13 KiB Raw Blame History Unescape Escape

开机自动启动功能复制计划

1. 目标与结论

2. ClawX 现有实现拆解

2.1 渲染层 UI 结构

2.2 渲染层状态链路

2.3 i18n 文案

2.4 主进程与 Host API 链路

2.5 测试覆盖

3. zn-ai 当前现状

3.1 已有可复用能力

3.2 关键差异

4. 复制范围与非目标

4.1 本次复制范围

4.2 明确不做的内容

5. zn-ai 的最小复制方案

5.1 UI 方案

5.2 状态与设置层方案

5.3 配置模型方案

5.4 主进程方案

5.5 副作用挂载位置

6. 文件级改动清单

6.1 渲染层

6.2 共享常量与类型

6.3 主进程

6.4 测试

7. 关键风险与处理建议

7.1 双写路径风险

7.2 Linux 桌面文件元数据风险

7.3 产品名文案不一致风险

7.4 静默失败体验风险

8. 推荐实施顺序

Phase 1：主进程能力补齐

Phase 2：渲染层接入

Phase 3：验证

9. 最小测试集合

10. sub-agent 估算与分工

10.1 推荐数量

10.2 分工建议

Worker 1：渲染层与 i18n

Worker 2：设置模型与配置链路

Worker 3：主进程自启动服务与测试

11. 最终建议

13 KiB

Raw Blame History