SchedulePin 是一个本地优先的 Chrome / Edge 计划管理插件。插件负责编辑和保存计划；可选的 Windows 桌面助手负责把计划渲染进壁纸。桌面端没有需要移动、置底或关闭的伪桌面窗口，也不会遮挡其他应用。
- 新标签页总览：左侧用紧凑的文字列表快速访问网站，右侧保留主题化的
Principle和完整To-Do List。大横屏和大竖屏都按可用宽度保持双栏，两栏分别滚动；To-Do List收起后以横向摘要显示当天完成进度，并可在卡片内展开，Principle 也可独立收起，状态会被记住。 - 快捷访问：只填网址即可添加，名称选填；留空时自动展示网站简称，例如
https://docs.example.com显示为example，并随网址更新，已有自定义名称保留。支持固定、分组、查找、编辑、删除和手动排序。首次使用从空列表开始；链接默认在当前标签页打开，Ctrl / 中键沿用浏览器的新标签打开方式。设置中可切换导航左右位置和网站简称显示；名称与简称相同时不会重复展示。 - 快速操作：在列表末尾输入内容并按 Enter 添加任务；拖动任务时，任务会跟随指针且相邻项目平滑让位。
- 入口快捷操作：页面空闲时按
/聚焦入口搜索；编辑文字或打开弹窗时不抢焦点。拖动入口右侧手柄可在已固定区域或当前分组内排序，也可用空格提起、方向键移动、空格放下；筛选期间暂停排序，避免改变隐藏入口的位置。 - 网站图标：优先使用浏览器保存的网站原始图标，再尝试该网站的
/favicon.ico；取不到时显示域名首字符的大写图标，底色按域名稳定生成。扩展使用favicon权限，不接入第三方图标服务。普通网页预览只能尝试网站根目录图标；未访问且仅在其他路径声明图标的网站，可能暂时显示字母。 - 导航外观：柔和渐变底色、分组色点和数量、浅色添加按钮随主题调整；悬停或键盘聚焦时突出网站入口。任务区的小型完成环、勾选和输入焦点呼应主题色，横竖屏布局及原有外观设置继续生效。
- 页面背景：右下角“壁纸库”或设置中的“页面背景”提供清爽纸感、流彩渐变和风景沉浸三种风格。背景效果、自动更换与选图分开管理，横竖屏分别保存裁切位置。修改自动保存，无需再次确认；图片加载失败保留原背景。恢复背景默认设置保留我的壁纸。
- 我的壁纸：只展示主动收藏、固定、上传或导入的图片，自动换图缓存不会混入。上传支持 JPG / PNG / WebP（20 MB 以内，优化到最长边 3840px），在线图片来自 Wikimedia Commons，保留作者、来源和许可信息。已保留图片可离线使用，可导出 / 导入包含实际图片的 JSON 备份。收藏不会停止轮换，固定则使用该图片并停止自动更换；解除固定后图片继续保留。
- 自动换图：可选每日更换或每次打开／刷新更换，来源为在线精选或我的壁纸。每日模式在当天首次打开时更新；每次打开／刷新模式由各窗口独立选图，不会带动已有窗口切换。正在输入、打开弹窗或页面隐藏时延后换图，网络失败保留上一张。固定后点击“换一张”先预览，确认才替换并保留；恢复自动更换会使用固定之前的频率。新标签页背景不会修改 Windows 壁纸或触发桌面同步。
- 自动归档：当天完成的任务保留删除线，次日自动移入归档；归档页支持搜索、查看完成时间、恢复和删除。
- 个性化设置：导航分为“浏览器页面”和“桌面展示”。浏览器页面按整体样式、页面背景、快捷导航、待办区域和原则卡片组织；桌面展示在同一页连接助手、选择显示范围和显示器，并直接编辑当前屏幕的计划布局。整体样式统一管理默认主题、字体、字号、间距、圆角，以及新标签页单独配色和面板透明度；Principle 的内容、默认展开状态、独立样式和跟随配色集中在原则卡片。修改即时生效并自动保存，失败可重试，各页恢复默认只重置相应范围。
- 多入口访问：新标签页提供导航与计划总览；扩展图标打开侧边栏计划，侧边栏顶部可新开完整计划页面。首页收起待办不会影响这两个计划入口。
- 本地存储：任务与基础设置保存在
chrome.storage.local，图片和新标签页背景设置保存在独立 IndexedDB；无需登录。在线图库需要联网，上传和已收藏图片可离线使用。卸载扩展或清除站点数据会清除本地收藏，请使用导出备份迁移。
- 将计划渲染为 Windows 壁纸，可指定一块显示器或全部显示器。
- 桌面计划沿用网页的品牌栏、日期进度、Principle 和 To-Do 卡片层级，只省略按钮、输入框、勾选框和拖动手柄等交互控件；两端共享主题设计配置，桌面端按显示区域独立换算字号并完整换行。
- 在浏览器设置页中拖动和缩放计划卡片，为每块显示器独立保存百分比布局。
- 任务、外观、日期或显示器配置变化后自动重绘；浏览器关闭后，助手仍可按最后一次快照刷新。
- 关闭桌面展示、主动恢复或卸载助手时，可恢复启用前的原壁纸。
- 壁纸只是静态桌面内容，不会遮挡应用，也不接受鼠标操作。
浏览器插件可以独立使用。只有需要桌面壁纸功能时，才需要安装和运行 Windows 桌面助手。
仅构建和测试浏览器插件需要：
- Node.js 22（包含 npm）；
- Chrome 或 Edge；
- 在项目目录执行一次
npm install。
桌面助手仅支持 Windows 10/11。参与助手开发或完整联调时，还需要 Rust stable 工具链，以及与 Rust 工具链匹配的本机链接器：MSVC 工具链需要 Visual Studio Build Tools 的“使用 C++ 的桌面开发”，GNU 工具链需要 MinGW GCC。
项目命令集中列在这里，后续章节只解释各流程的用途和产物。
| 命令 | 用途 | 是否需要 Rust |
|---|---|---|
npm install |
安装前端依赖，首次拉取项目后执行 | 否 |
npm run dev |
启动 React 界面预览 | 否 |
npm run build |
类型检查并构建插件到 dist |
否 |
npm run extension:build |
构建插件到 dist，当前等同于 npm run build |
否 |
npm run preview |
本地预览已构建的前端资源 | 否 |
npm run test:navigation |
校验链接、分组、排序和独立存储 | 否 |
npm run test:settings |
校验默认原则、旧数据迁移及已有设置保留 | 否 |
npm run test:settings-ui |
校验设置分类、即时保存、局部恢复及原则卡片设置 | 否 |
npm run test:ui |
使用 Playwright 运行隔离的前端回归测试（需单独准备浏览器测试环境） | 否 |
npm run test:icons |
使用同一 Playwright 环境，在隔离扩展中验证网站图标和字母回退；测试副本禁用桌面通信 | 否 |
npm run test:background |
检查换图日期、固定模式和裁切范围 | 否 |
npm run test:wallpaper |
检查即时保存、收藏与固定、备份、默认恢复、裁切和独立换图 | 否 |
npm run test:wallpaper-store |
使用真实 IndexedDB 验证保留、迁移、缓存清理和默认恢复 | 否 |
npm run test:wallpaper-race |
验证延迟下载、多窗口固定／重置和刷新排除上一张图片 | 否 |
npm run test:local |
构建插件与助手、执行测试、注册助手并启动隔离的 Edge 联调环境 | 是 |
npm run helper:test |
运行 Rust 单元测试和壁纸渲染测试 | 是 |
npm run helper:build |
构建 Release 模式的桌面助手 | 是 |
npm run helper:smoke |
只读检查 Native Messaging 和显示器信息 | 是，且需先构建助手 |
npm run helper:install |
注册本地开发版助手 | 是，且需先构建助手 |
npm run helper:uninstall |
注销本地开发版助手并清理其数据 | 否 |
npm run helper:uninstall -- -KeepData |
注销本地开发版助手，但保留缓存和壁纸备份 | 否 |
npm run release:local |
测试并构建桌面助手，再生成单文件安装程序 | 是 |
正式发布时使用的 Git 命令也集中在此处。版本号必须与 package.json 一致；以下以 0.3.0 为例：
git tag v0.3.0
git push origin v0.3.0- 运行
npm run extension:build。 - 打开
chrome://extensions；Edge 使用edge://extensions。 - 开启“开发者模式”。
- 点击“加载已解压的扩展程序”，选择项目生成的
dist目录。 - 新开一个标签页即可使用；点击工具栏中的 SchedulePin 图标可打开侧边栏，侧边栏顶部的“完整页面”按钮可另开完整计划。
npm run dev 和 npm run preview 只适合快速查看 React 界面。普通网页没有扩展权限，因此不能用它们验证新标签页、侧边栏或桌面助手连接。
- 从 GitHub Releases 下载
SchedulePin-Helper-Setup.exe。 - 双击安装。安装过程不需要管理员权限，也不需要手动填写扩展 ID。
- 回到 Chrome 或 Edge 的扩展管理页，重新加载 SchedulePin。
- 打开 SchedulePin 设置页并点击“重新检测”。显示“桌面助手已连接”后，即可启用桌面计划。
安装程序会：
- 把助手安装到
%LOCALAPPDATA%\Programs\SchedulePin Helper； - 为 Chrome 和 Edge 注册
com.schedulepin.helper； - 使用内置的固定扩展 ID 安全白名单；
- 注册当前用户的无窗口开机启动进程。
直接双击 schedulepin-helper.exe 不会打开界面。它是由浏览器启动、通过标准输入输出通信的 Native Messaging Host；正式用户应使用安装程序，而不是裸 EXE。
在设置中先选择“指定屏幕”或“全部屏幕”，再选择一块显示器编辑布局。拖动预览卡片可改变位置，拖动卡片右下角可改变大小；不透明度等设置会自动同步。布局按百分比保存，因此分辨率或缩放比例变化后仍会保持相对位置。
- 暂时关闭展示：关闭“显示桌面计划”，恢复原壁纸，同时保留助手和任务。
- 立即恢复：点击“恢复启用前的原壁纸”，恢复壁纸并关闭桌面展示。
- 卸载正式版本：在 Windows“设置 → 应用 → 已安装的应用”中卸载。卸载程序会先尝试恢复壁纸，再注销 Native Messaging 和开机启动项。
- 卸载开发版本：使用命令总览中的
helper:uninstall命令；如需保留缓存和壁纸备份，使用带-KeepData的版本。
助手会备份各显示器启用时的壁纸图片、位置模式和背景色。当前版本不会重新启动 Windows 壁纸轮播；如果启用前使用轮播，恢复后会停留在当时捕获的那张图片。
更完整的正式安装和卸载说明见 Windows 桌面助手安装。
只开发任务管理、新标签页、侧边栏或设置页面时，不需要 Rust。通过命令总览中的 dev 命令快速调整界面，再用 extension:build 生成真正的插件资源并按“加载浏览器插件”步骤验证扩展能力。
前端回归测试脚本会先构建前端，再启动仅监听本机的临时产物预览服务，创建隔离浏览器上下文，并在结束后关闭服务和浏览器；测试数据不会写入日常浏览器配置。测试覆盖导航管理、完整任务列表、横竖屏、独立滚动、任务操作、外观即时保存及主题，截图位于 .tools/ui-tests/。设置和壁纸专用回归截图分别位于 .tools/settings-tests/ 和 .tools/wallpaper-tests/。
运行 test:ui 需要可用的 Playwright 包及其浏览器。已有开发工具运行环境时，可用 SCHEDULEPIN_PLAYWRIGHT_PATH 指向其 Playwright 模块入口，用 SCHEDULEPIN_BROWSER_PATH 指向本机 Chrome / Edge 可执行文件；否则脚本从项目中解析 playwright 并使用其默认 Chromium。单元测试和生产构建不需要 Playwright。
环境准备完成后运行命令总览中的 test:local。脚本会依次：
- 构建浏览器插件；
- 测试并构建桌面助手；
- 验证 Native Messaging；
- 注册固定 ID 的开发版助手；
- 使用独立测试配置启动 Edge，并自动加载
dist。
随后在新打开的 Edge 中进入设置，点击“重新检测”即可测试桌面壁纸。脚本无需扩展 ID 或其他参数；测试数据保存在项目的 .tools/edge-test-profile，不会与日常 Edge 配置混用。
需要分步排查助手时，按命令总览中的顺序运行 helper:test、helper:build 和 helper:smoke。其中 helper:smoke 只读取 Native Messaging 与显示器信息，不会修改壁纸。
Release 模式的开发版助手生成在：
native-helper\target\release\schedulepin-helper.exe
该文件只用于开发联调和打包，不是面向用户的安装入口。
除完整联调所需环境外，本地打包还需要 PowerShell 5.1 或 PowerShell 7，以及 Inno Setup 6。运行命令总览中的 release:local 后，脚本会检查依赖、测试并编译 Rust Helper，最后调用 Inno Setup 打包。
成功后，输出目录中只有一个交付文件：
release\local\SchedulePin-Helper-Setup.exe
也可以直接运行 scripts\release-local.ps1。缺少 Rust、链接器或 Inno Setup 时，脚本会指出缺失项并停止，不会自动安装或修改本机软件。
仓库的 Build Helper Installer 工作流运行在 GitHub 提供的 windows-2022 Standard Runner 上，不需要自建服务器。远程构建与本地构建共用 scripts\release-local.ps1，并在上传前通过静默安装、注册表检查和卸载验证完整安装流程。
手动测试构建：
- 打开仓库的
Actions页面。 - 在左侧选择
Build Helper Installer。 - 点击
Run workflow。 - 构建完成后，从该次运行的
Artifacts下载SchedulePin-Helper-Setup。
手动构建产物保留 14 天，不会创建正式 GitHub Release。
- 确认
package.json中的版本号。 - 使用命令总览中的 Git 命令推送同版本的
v*标签。 - 工作流校验标签与包版本；不一致时会停止。
- 构建和安装验证通过后，GitHub Release 只发布
SchedulePin-Helper-Setup.exe。
当前安装程序尚未配置商业代码签名证书，因此 Windows 可能显示“未知发布者”或 SmartScreen 提醒。这不影响安装流程；公开发布前可为工作流接入可信代码签名。
- 浏览器插件中的数据是主数据；助手只保存离线重绘所需的最后一份快照。
- 普通 To-Do 不受“当天”限制，未完成时会持续保留；
Principle是独立段落，不参与完成度或归档。 - 浏览器预览模式使用
localStorage，加载为扩展后使用chrome.storage.local，两者不是同一份数据。 - 旧 Tauri / SQLite 原型数据不会自动迁移到 0.3 插件；旧版仅为测试原型，迁移层已随旧架构移除。
- 卸载浏览器扩展时，浏览器会清除该扩展的数据；卸载桌面助手不会删除浏览器里的任务。
- 原壁纸恢复支持逐屏图片、位置模式和背景色，但暂不恢复 Windows 壁纸轮播状态。
- 架构说明：技术选型、数据流、安全边界和多显示器布局。
- Windows 桌面助手安装：正式助手的安装、卸载与恢复行为。
- 问题日志：已确认问题、原因、修复方案和验证记录。