TO-DO-Panel

它是什么

TO-DO Panel 是一个常驻 macOS / Windows 屏幕顶部的本地工作台。Mac 默认折叠成物理刘海大小；Windows 显示为贴顶的 200 × 38 逻辑像素悬浮条，避开顶部任务栏。点击后从顶部展开。

页面	解决什么问题
首页	当前窗口、镜子、快速录音、随笔记、常用指令、汽水音乐和番茄钟集中在一个 Bento 工作台
待办	四个可改名的工作流，新建默认当天 23:30，常驻跨天或唤醒后自动刷新；本条手选日期保留，提交后恢复当天默认值。截止日期可逐月切换并自然跨年，按截止时间排序，并在到期前一小时提醒；本机脚本或 AI 助手可写文件导入
随笔记	Markdown 速记、归档、搜索、重命名与智能标题
链接	保存公开网址，后台补全标题、图标和分组
录制	录音开始即创建实时记录，同步显示状态与转写，并可在页内配置 API
密钥	使用系统安全存储加密账号、密码和 API Key
设置	当菜单栏图标被刘海遮挡时，仍可在面板内配置 API、镜子、首页组件、功能显示、默认展开页、快捷键、数据目录与开机启动

剪贴板历史默认关闭，可从菜单栏或面板「设置」的「显示功能」中按需启用。菜单栏入口与设置页读写同一份本机配置；即使状态栏图标过多、被物理刘海遮挡，也不影响调整。Codex、Claude Code 与 GPT 的本机完成事件也可以直接显示为不抢焦点的顶部提醒。

「设置 → 首页组件」可以隐藏或恢复当前平台可用的组件（macOS 七个、Windows 五个），但首页至少保留一个。隐藏后，其余组件会自动重新铺满整个 Bento 网格，不留空洞；组件数据、用户保存的排列顺序和尺寸偏好不会被删除或覆盖。只要存在隐藏组件，首页使用自动填充布局并暂时隐藏尺寸按钮；macOS 恢复全部七个组件后，原尺寸偏好与按钮会一并恢复。Windows 采用自动填充布局。该偏好随当前本地工作区保存，存储键为 notch-home-hidden-modules-v1。

面板默认每次从首页展开。可在「设置 → 本机与唤出 → 默认展开页」改为任意当前可见的 Tab；若后续隐藏了被选中的功能，下次展开会自动回退到首页。

首页显隐也遵守资源边界：隐藏镜子会立即释放摄像头；录音进行中不能隐藏仍在首页显示的快速录音卡，但已隐藏该卡也不会禁用「录制」页的录音能力；隐藏音乐和当前窗口会停止纯展示用的 WebGL 动画与窗口扫描，番茄钟隐藏后仍继续计时和提醒。

实时转写连接中断时会保留已有文字并自动重连，连续连接失败最多重试 5 次。重连期间最多缓存最近 30 秒音频，恢复后继续追加转写；首页与录制页会显示重连、失败或缓存溢出提示。本机录音独立继续，已发送但尚未被服务确认的音频、以及超出缓存的离线片段可能缺字，不会自动补转已保存的旧录音。

下载与安装

当前稳定版本：1.2.0 · macOS 13.0+ Apple Silicon / Windows 10/11 x64（Intel / AMD 64 位）

平台	在上方 GitHub Releases 下载对应安装包
Mac	TO-DO-Panel-1.2.0-arm64.dmg
Windows	TO-DO-Panel-1.2.0-windows-x64-setup.exe

macOS

1. 前往 GitHub Releases 下载 TO-DO-Panel-*-arm64.dmg。
2. 打开 DMG，将 TO-DO Panel.app 拖入「应用程序」。
3. 首次启动若被 macOS 拦截，前往「系统设置 → 隐私与安全性」，点击「仍要打开」。
4. 再次启动，根据需要授予辅助功能、屏幕录制、麦克风或摄像头权限。

项目明确采用 GitHub Releases + ad-hoc 签名分发，不进行 Apple 公证，也不上架 Mac App Store。因此首次安装需要手动确认“仍要打开”；这是当前正式分发方式，不是待修复的发布缺陷。每次重新打包后，macOS 可能要求重新授权；由 safeStorage 加密的密钥也可能需要重新填写。

Windows

下载 TO-DO-Panel-*-windows-x64-setup.exe，运行安装向导，再从桌面或开始菜单启动。默认仅安装给当前用户，无需管理员权限，卸载保留本机工作区数据。托盘菜单可设置功能或退出，面板设置中可开启开机启动。

安装包暂无商业代码签名，可能出现 SmartScreen 提示。请核对来源与 .sha256 校验码，确认后通过「更多信息 → 仍要运行」安装；企业策略可能需要管理员批准。

Windows 首版暂不显示「当前窗口」和「汽水音乐」组件；剪贴板点击复制后用 Ctrl+V 粘贴，AI 完成提醒暂不支持点击切回任务窗口。平台限制不覆盖原有组件偏好。镜子仅主动点击后开启，离开首页或收起立即释放；结束录音释放麦克风。系统拒绝访问设备时，请检查 Windows 隐私设置中桌面应用的相机 / 麦克风权限。

Windows 版在 GitHub Windows runner 上自动验证安装、启动、数据保存、加密、快捷键、模拟音视频设备、重新安装和卸载；物理设备、Windows 10 实机及多显示器硬件尚未人工验收。普通工作区可跨平台迁移，加密密钥需在新电脑重新输入。

更新日志

当前稳定版本为 v1.2.0。正在开发但尚未发布的改动会先记录在 [未发布]，正式发版时再归档到对应版本，避免 README 随版本增加而持续膨胀。

完整版本历史、修复内容与未发布改动见 CHANGELOG.md。

设计原则

• 贴顶但不打扰：折叠态宽 200px，高度跟随菜单栏；展开与通知都不使用系统窗口动画。
• 设备按需启用：镜子只有主动点击才开启，离开首页或收起时立即释放摄像头；麦克风同理。镜子优先用电脑自带相机，iPhone 连续互通和 OBS / Filteronme 等虚拟摄像头排在最后；某个摄像头 3 秒内不出画面就自动换下一个。
• 数据留在本机：待办、笔记、链接、录音元数据和工作区设置保存在本地，无后端和云同步。
• 权限边界清晰：链接元数据抓取会阻止本机、内网地址和不安全重定向；窗口聚焦只接受最近扫描缓存中的 ID。
• 可迁移工作区：可从菜单栏选择数据文件夹，换电脑时复制该文件夹继续使用。

本机 AI 完成提醒

TO-DO Panel 只在 127.0.0.1:43821 监听通知接口，来源限 codex、claude 与 gpt：

curl -X POST http://127.0.0.1:43821/notify/codex \
  -H 'Content-Type: application/json' \
  -d '{"title":"任务已完成","project":"my-project","task_id":"demo"}'

仓库已提供 Codex 转发脚本 和 Claude Code 转发脚本。通过 DMG 安装后，脚本路径为：

/Applications/TO-DO Panel.app/Contents/Resources/app/scripts/codex-notify.js
/Applications/TO-DO Panel.app/Contents/Resources/app/scripts/claude-notify.js

Windows 安装后的两个脚本位于安装目录的 resources/app/scripts/ 中，可用 Node.js 调用；应用本身无需用户安装 Node.js。

从脚本或 AI 助手导入待办

本机脚本或 AI 助手把 JSON 文件放进工作区的 todo-inbox/ 文件夹，TO-DO Panel 运行时约 2 秒检查一次，启动时也会检查，无需重启。导入只追加新待办，不会修改或删除已有待办。

工作区	收件箱路径
macOS 默认	~/Library/Application Support/Dynamic Panel/todo-inbox/
Windows 默认	%APPDATA%\Dynamic Panel\todo-inbox\
自定义数据文件夹	<所选文件夹>/todo-inbox/

当前工作区路径可在「设置 → 数据目录」或菜单栏「打开文件夹」查看；切换数据文件夹后，收件箱跟着换到新文件夹。

文件格式：顶层可以是 { "todos": [...] }，也可以直接是数组。示例见 docs/todo-inbox-example.json。

字段	必填	说明
text	是	待办内容，最多 80 个字符
category	是	P0–P3（不区分大小写），或当前分类显示名（忽略大小写与多余空格）；两者冲突时以 P0–P3 为准
deadline	否	ISO 8601 字符串或毫秒时间戳。带时区（2026-10-08T18:00:00+08:00）按该时区；不带时区按本机时间；只写日期（2026-10-15）为当天 23:30；不填与手动新建一致，为当天 23:30
id	否	只能包含字母、数字和 . _ : -，最长 128。已存在的 id 不会重复添加

# 推荐先写临时文件再改名，避免读到写了一半的文件；以 . 开头或不以 .json 结尾的文件会被忽略
cp docs/todo-inbox-example.json ~/Library/Application\ Support/Dynamic\ Panel/todo-inbox/.agent.tmp
mv ~/Library/Application\ Support/Dynamic\ Panel/todo-inbox/.agent.tmp \
   ~/Library/Application\ Support/Dynamic\ Panel/todo-inbox/agent-$(date +%s).json

处理结果：每个文件处理完都会移入 todo-inbox/processed/，文件名加时间前缀（如 20260929-153012-007-agent.json），同时生成同名的 .report.json 报告：

• status：imported 全部导入；partial 部分导入；none 没有新增（如全部重复）；rejected 整个文件无法识别（如 JSON 解析失败、文件超过 1 MB）。
• imported 列出新增条目及分配的 id；skipped 按 index（从 0 开始）列出被跳过的条目和原因；warnings 提示截止时间早于导入时间等情况。

去重规则：处理过的文件会移走，不会导入第二次。没写 id 的条目按「文件内容 + 序号」生成稳定 id，因此内容完全相同的文件再放一次也不会重复添加（除非之前导入的待办已被删除）。格式不对的条目只会被跳过，不影响同一文件中的其他条目。单个文件最多导入 200 条。

processed/ 不会自动清理，可随时手动删除。

从源码运行

桌面端要求 Node.js 22.12.0+：

git clone https://github.com/xiaopu-ai/TO-DO-Panel.git
cd TO-DO-Panel
npm install
npm test
npm start

项目使用单一 Electron 架构，没有渲染层构建步骤，npm start 是完整运行路径。

命令	用途
npm test	单元测试与 JavaScript 语法检查
npm start	启动 Electron 开发版
npm run pack	生成未安装的 .app
npm run build	生成 Apple Silicon DMG
npm run build:win	生成 Windows x64 EXE 安装包（建议 Windows 环境构建）
npm run build:zip	生成 ZIP 分发包

官网位于 website/，要求 Node.js 22.13.0+：

cd website
npm install
npm run dev

项目结构

.
├── main.js                 # Electron 主进程、窗口与系统服务
├── main-services.js        # 可测试的纯领域服务
├── preload.js              # contextBridge 安全桥
├── renderer/               # 桌面界面与交互
├── tests/                  # Node 单元测试
├── build/                  # 图标、签名与 DMG 配置
├── scripts/                # Codex / Claude Code 通知转发
├── docs/                   # 设计、ADR 与发布说明
└── website/                # React 19 + Vinext 官网

发布

推送与 package.json 版本一致的 v*.*.* 标签后，GitHub Actions 并行测试、构建并校验 macOS DMG 和 Windows EXE。两个平台全部通过后，才创建同一个 Release 并上传两个安装包及各自 SHA-256 文件。完整流程见 发布说明。

License

MIT © 2026 xiaopu-ai