E note

想法随手记，待办有着落。

安静停在 macOS 屏幕边缘的便签与任务清单。

macOS 13+ · 本机优先 · 多端同步 · 飞书 × AI · API & Skill

快速开始 · 云端同步 · 飞书 × AI · 待办清单 · API 对接 · Skill 对接

作者：韦冬 · 2220285589@qq.com

E note 把随手记录和行动清单放在屏幕边缘。普通便签承载想法、资料和临时记录；独立的 待办清单 固定占用第一张便签的位置，负责分类任务、稳定编号和到期提醒。程序或 AI 可以通过本地 API 创建便签、添加任务，并按编号修改内容。

不登录，安静做一张本机便签；登录后，把任务和记录带到每台电脑。 通过飞书与本机 AI 讨论需求，确认实施方案后执行，过程与结果自动写入关联便签，验收后完成待办。桌面不收集遥测。

新建普通便签交替使用这两种默认色，已有深蓝 / 天蓝便签会在加载时更新。其他手选颜色继续保留。

查看配色示意

待办清单 使用独立的松柏绿主题，普通便签默认交替使用杏砂与雾紫。圆角任务卡片、完成进度环、分类标签、重要标记与到期状态，支持深浅色外观。下图由应用的真实 SwiftUI / AppKit 视图渲染，展示三种窗口尺寸；任务内容为演示数据。

当前版本：v1.0.2 · 更新说明

源码已加入待发布的 v1.0.3 应用内更新功能：更新说明。首次手动安装带更新器的版本后，可每天自动检查，并点击“一键更新并重启”。

下载 macOS 安装包 · 所有版本 · 完整安装说明

适用于 macOS 13+，Intel 和 Apple 芯片。打开 DMG，将 E note 拖入 Applications（应用程序），再从应用程序文件夹启动。把鼠标移到屏幕边缘的小条即可使用；应用不显示 Dock 图标，无需登录即可管理本机便签和待办。

当前下载版采用临时签名，尚未经过 Apple Developer ID 签名和公证。首次打开若提示无法验证开发者，确认来源可信后，在「系统设置 → 隐私与安全性」中选择「仍要打开」。详见 Apple 官方说明。

需要 macOS 13 或更高版本，以及 Xcode Command Line Tools。Python 客户端、Skill 安装脚本和测试需要 Python 3，客户端只使用标准库。

构建脚本会下载并校验固定版本的 Sparkle 框架。普通本地构建不检查线上更新；正式 Universal 构建与签名发布流程见 自动更新与发布。更新签名使用项目本地 .update-signing/ed25519.key 中的 Ed25519 密钥（不提交 Git），不需要 Apple 开发者账号。

在项目目录执行：

./build.sh run

构建产物为 build/E note.app。已有旧版运行时，先退出旧版再打开新构建的应用。

1. 将指针移到屏幕边缘的小条上，展开便签标签。
2. 第一张是 待办清单；点击后可在底部输入任务，按回车添加。
3. 在「全部」「待完成」卡片中直接点击「设置时间」「设为重要」；点击右侧铅笔修改标题。已完成或已归档的任务显示删除按钮。
4. 使用 ⌥⌘N 新建普通便签，使用 ⇧⌘Space 快速捕捉。
5. 右键边缘小条选择 设置…，调整常驻开关、提醒时间、外观与 API。

其他构建方式：

./build.sh        # release：编译、组装 .app、ad-hoc 签名与验证
./build.sh debug  # 调试构建
./build.sh universal  # 同时包含 Intel 与 Apple 芯片
./scripts/package_release.sh  # 生成 DMG、ZIP 和 SHA-256 校验文件

默认按当前机器架构生成单架构应用，发布脚本生成双架构应用，最低部署目标为 macOS 13。无需 Xcode 工程或额外包管理器。

在 设置 → 账号 登录或注册。同一服务器、同一账号的电脑共享便签、结构化 TODO 和任务执行记录。

初次登录可以把本机便签复制到账号，原始本机内容保留。TODO 使用永久 UUID 关联，服务器单独分配账号内编号；离线新任务第一次同步后显示编号可能调整。

已配置服务器 https://47.96.175.129:8443，构建内置公开证书指纹。邀请码由服务器配置提供，本机初始化信息位于 ~/Library/Application Support/ENote/server-setup.json。其他部署、证书和备份方法见 账号与云端接入指南。

手机发来一个 TODO
      ↓
AI 讨论目标、约束和验收方式
      ↓
生成关联方案便签 → 你确认方案版本
      ↓
同步最新状态 → 领取唯一执行锁 → 本机 CLI 执行
      ↓
保存过程与结果 → 飞书通知验收 → 你确认 → TODO 完成

每条 TODO 下的 方案与执行记录 可打开关联便签。执行前检查云端版本和执行锁；电脑断线时停止 CLI，结果写回失败会留在本机等待补记，不会自动重跑任务。

使用自建飞书应用机器人和已登录的 Codex / Kimi CLI。安装桥接：

python3 scripts/install_bridge.py
# 填写本机 bridge.json 后
python3 scripts/install_bridge.py --enable

手机私聊机器人发送 待办、讨论 T000001 我的需求。AI 会询问不明确的部分，然后提供带版本和确认码的执行指令。仅在你发送确认后执行，结果也需要你验收。详细权限、配置字段、命令和中断恢复见 飞书接入指南。

桥接可每小时增量扫描未完成 TODO。新任务会生成一张关联方案便签，并在其中加入两个固定区域：

• 我的资料补充：填写目标、资料、绝对工作目录和验收标准；只有该区域或 TODO 本身发生变化时才再次调用 AI。
• 人工批准：服务器、部署、推送、删除、外部发送、凭据及其他有明显副作用的任务会在这里列出方案摘要、版本、确认码和摘要值。核对后只把 decision: pending 改成 decision: approve。

资料不足时 AI 把新问题写入关联便签并发送一次飞书通知；资料充分且被判定为 local_safe 时，在任务指定的白名单工作目录中自动执行。结果仍写回同一便签，用户验收后才完成 TODO。扫描只处理结构化 TODO、关联流程和关联便签，不搜索其他普通便签；已存在的手工流程不会被自动接管。

服务器执行默认硬关闭。即使 Note 已批准，也只记录批准状态，不会连接服务器；需要另行配置受限服务器执行器后才能显式打开。普通执行使用 workspace-write，忽略用户级 CLI 配置，移除常见云平台、SSH、Kubernetes 和飞书环境凭据，并禁止自动 push、发布和对外发信。

常驻开关默认开启。 在「设置 → 通用 → 常驻 待办清单」关闭后，清单从屏幕边缘隐藏，已有任务仍保留在便签库。重新开启使用同一张清单。API 继续可以管理任务，但不会替用户打开常驻开关。

展开的 待办清单 不会因空闲或切换其他应用自动收起；点击右上角关闭按钮可收起。

• 「全部」「待完成」列表直接显示「设置时间」和「设为重要 / 取消重要」，无需打开更多菜单。
• 「设置时间」支持新增、调整和清除到期时间；点击铅笔打开「修改标题」。
• 只有已完成或已归档任务显示删除按钮；确认删除时会再次检查最新状态，恢复为未完成且未归档的任务不能删除。
• 标题和时间编辑分别保存目标字段，保留其他窗口或 API 对任务其他字段的修改；同字段发生冲突时提示重新打开编辑。切换账号会关闭旧编辑窗口。

查看卡片操作与编辑弹窗（浅色） · 深色

待办清单 右上角的齿轮直接打开设置，标签图标打开独立的标签管理窗口。

• 标签包含名称、类型（项目 / 版本 / 其他）、说明和相关链接；每个 TODO 可绑定多个标签。
• 在任务卡片点击「+ 标签」添加或移除绑定；点击标签查看资料，再进入独立页面编辑。修改后所有引用该标签的任务共用最新资料。
• TODO 卡片和编辑页移除旧分类入口，统一使用标签；旧分类数据和 API 字段保留兼容。
• 标签列表按最新修改排序，整块标签均可点击。状态筛选栏右侧可按已绑定标签筛选；在筛选结果中新建 TODO 会绑定当前标签。
• 标签资料、修改时间和 TODO 绑定均随账号同步；筛选选择只影响当前窗口。标签 API / MCP 用法见 API 文档。
• 点击任务右侧归档按钮可手动归档；「归档」筛选保留任务查询及恢复入口。归档任务不触发到期提醒。
• 已完成任务满 72 小时自动归档，应用启动及运行时每 30 秒检查；应用退出期间会在下次启动补处理。
• 旧任务缺少完成时间时，从升级后首次检查开始计时。手动恢复已完成任务后重新保留 3 天；取消完成会清除完成计时。

升级同步服务：此版本增加 tag 云端实体，需更新 server/enote_server.py 并重启云端服务，各同步设备也应更新客户端。旧服务器不识别标签实体，会拒绝含标签的同步批次。2026-09-15 已将默认云端服务器升级为支持标签和归档的版本，并通过公网双客户端同步验证；其他自建服务器需自行升级。

任务卡片显示 T000001 这样的编号，可右键复制。API 同时返回三个只读标识：

{
  "id": "f87cbcc4-fef2-4b49-9c2e-80962a11af90",
  "number": 1,
  "code": "T000001"
}

• UUID 永久不变。已分配的账号编号在修改、完成、排序和重启时不变；离线新任务首次上传时会分配账号内编号。
• 删除后的编号不复用，新任务继续递增。
• 旧版只有 UUID 的任务会在首次加载时自动补齐编号。
• 普通 note 中的待办行不会自动变成这里的任务，也不能用普通便签 ID 调用任务修改接口。

默认提前 10 分钟提醒，可在设置中关闭，或选择提前 1、5、10、15、30、60、120 分钟。

提醒不会自动展开整张正文或抢走键盘焦点。如果正在编辑其他便签，当前卡片保持不变。手动打开的 待办清单 也不会在完成任务后突然关闭。

应用运行时每 30 秒检查一次，任务修改后约 0.5 秒刷新；退出应用期间不在后台提醒，重新启动会重新计算状态。

• 屏幕边缘 Deck：小条唤醒 → 叠层标签 → 展开正文。支持左右停靠、主屏或所有显示器、尺寸调整和悬停行为。
• 随手编辑：250 ms 自动保存，八色便签，正文查找，纯文本任务勾选。
• 快速捕捉：新建便签或追加到现有便签；追加到 待办清单 时，每一行生成独立任务。
• 便签库：按标题与正文搜索，管理活跃、归档和已删除的便签。
• 删除恢复：删除后 10 秒内可撤销；已删除便签保留 30 天，可恢复或彻底删除。
• 导入导出：Markdown / 纯文本导入，每便签一个文件或合并导出。待办清单 也会导出为任务文本。

正文里的时间标记仍可使用 ⏰2026-09-18 17:00。这类文本待办保留编辑与导出能力，主动提醒由独立 待办清单 负责。

在 设置 → API 开启「允许本机程序和 AI 调用」（默认开启）。应用运行时监听：

http://127.0.0.1:49178

仅绑定 IPv4 回环地址，不向局域网开放。每个请求都需要 Bearer 令牌；网页跨域调用不开放。

运行配置自动写入：

~/Library/Application Support/ENote/api.json

配置格式如下，令牌由应用生成，不需要手工创建：

{
  "baseURL": "http://127.0.0.1:49178",
  "token": "由应用生成的访问令牌"
}

api.json 和永久令牌文件 api-token 的权限均为 0600。关闭 API 会移除运行配置；重新开启仍使用原令牌。设置中可以查看运行状态、复制令牌或打开配置目录。

客户端自动读取配置和令牌，只依赖 Python 标准库。在项目根目录执行：

# 检查服务
python3 skills/e-note/scripts/e_note.py health

# 创建普通便签；title 会成为正文首行
python3 skills/e-note/scripts/e_note.py note \
  --title '发布会议' --body '周五发布，先完成回归测试。'

# 添加分类待办，返回 UUID 和 T000001 形式的固定编号
python3 skills/e-note/scripts/e_note.py todo \
  --text '完成回归测试' --category 工作 --priority high \
  --due-at '2026-09-18T17:00:00+08:00'

# 查询任务，确认目标编号
python3 skills/e-note/scripts/e_note.py todos

# 按编号修改内容
python3 skills/e-note/scripts/e_note.py update \
  --id T000001 --text '完成全部回归测试' --category 工作

# 完成 / 恢复待完成
python3 skills/e-note/scripts/e_note.py complete --id T000001
python3 skills/e-note/scripts/e_note.py complete --id T000001 --undo

# 清除到期时间
python3 skills/e-note/scripts/e_note.py update --id T000001 --clear-due

示例中的编号应替换成接口实际返回的编号。到期时间使用带时区的 ISO 8601 格式。

批量添加可使用 batch --file tasks.json，一次最多 100 项：

{
  "items": [
    {"text": "提交周报", "category": "工作", "priority": "high"},
    {"text": "整理阅读笔记", "category": "学习"},
    {"text": "购买生活用品", "category": "生活"}
  ]
}

python3 skills/e-note/scripts/e_note.py batch --file tasks.json

{id} 支持 T000001、数字 1 或 UUID。任务编号不可修改。

PATCH /v1/todos/T000001 HTTP/1.1
Host: 127.0.0.1:49178
Authorization: Bearer <访问令牌>
Content-Type: application/json

{"text":"完成全部回归测试","priority":"high","completed":false}

创建成功返回 201，读取或更新返回 200。错误响应为 {"error":"说明"}。单次请求最大 1 MiB，批量先整体校验，全部有效才写入。

创建接口没有幂等键。超时或保存失败后先查询是否已写入，再决定是否重试，避免重复创建。

完整字段、响应与错误码见 API 协议。

项目自带 e-note skill，支持便签与 TODO 操作、同步状态查询，以及讨论、方案确认、领取执行锁、记录结果和验收流程。

在项目根目录执行：

python3 scripts/install_skill.py

安装脚本把项目中的 skills/e-note/ 链接至 $CODEX_HOME/skills/e-note；未设置 CODEX_HOME 时使用 ~/.codex/skills/e-note。已有指向本项目的链接可重复运行，其他同名 skill 不会被覆盖。

使用前先启动 E note 并开启 API。可以这样提出请求：

使用 $e-note，把“明天下午五点前完成回归测试”加入工作分类，并标为重要。

使用 $e-note，把 T000001 的内容改为“完成全部回归测试”。

使用 $e-note，查看我的待办，把 T000001 标记为完成。

Skill 通过附带客户端读取本机配置，不直接修改加密数据文件；不会根据含糊的描述猜测任务编号或重复提交超时请求。

如果电脑已通过 cc-connect 将飞书接到 Codex，可直接给同一 Codex 安装 E note MCP。在本项目根目录执行：

codex mcp add enote -- python3 "$(pwd)/skills/e-note/scripts/e_note_mcp.py"

MCP 使用标准输入输出，由 Codex 启动本机连接器访问 E note；不用再开启飞书长连接，也不用关闭 Codex 沙箱。连接器自动读取本机 API 配置，令牌不会出现在工具参数或工具描述里。若要使用云端同步工具，在 ~/.codex/config.toml 的 [mcp_servers.enote] 中设置 tool_timeout_sec = 140。

MCP 关闭待办时，enote_update_todo 必须同时提供 completed=true、completionNoteID 和 executionConclusion。连接器校验 note 的 linkedTodoID 与待办 UUID 一致，追加带时间的结论并回读确认后才关闭；失败时保持待办未完成。普通字段修改不需要这两个参数。结论应记录完成内容、验证、交付与备份位置、剩余事项，不含凭据。重试相同结论不会重复追加。已有工作流继续使用 finish / 用户验收后的 accept。

该保护位于 MCP 连接器，不是桌面 UI 或原始 HTTP API 的全局约束。请更新已安装的连接器并重新连接 MCP，旧进程不会自动加载新代码。

安装后让 Codex 重新加载工具，再发送“用 E note MCP 查看我的待办”。cc-connect 的 exec 后端会在下一条消息启动 Codex 并加载配置；常驻 app-server 后端需重新启动相应会话。若 shell 报 Operation not permitted 而 MCP 可用，说明 shell 的本地网络访问受限，仍可使用 MCP 操作 E note。

此接入提供日常便签和 TODO 操作；带执行锁的自动执行、断线结果补记和人工验收仍使用 专用工作流桥接，不能把普通聊天能读取清单当作全流程验收通过。Codex 配置方式见 官方 MCP 文档。

任何能够运行 Python 的本机程序，都可以调用 skills/e-note/scripts/e_note.py；任何支持 HTTP 的语言，也可以按 API 协议发送请求。

• 默认分类为“收集箱”，默认优先级 normal，默认无到期时间。
• update / complete 接受可见编号或 UUID。
• 登录后远程操作先执行 sync；sync-status 查看账号和冲突，workflows 查看关联方案，workflow --file 提交流程操作。
• 自定义数据目录时，可在子命令前传入 --config /absolute/path/api.json。
• 成功响应包含任务的编号与实际保存内容，调用方可保存编号供后续修改。

数据位于 ~/Library/Application Support/ENote/：

普通便签标题、颜色、时间戳等元数据为明文；正文和 TODO 详情为密文。保存采用临时文件写入、fsync 和原子替换。

从旧版 Noty 目录升级时会迁移应用自己的 notes.json 与 note.key，并保留迁移备份。备份和恢复便签时，需要一起保存 notes.json 与 note.key。

./Tests/run.sh
python3 Tests/test_cloud.py
python3 Tests/test_sync.py
python3 Tests/test_storage_failure.py
python3 Tests/test_bridge_runner.py
python3 Tests/test_mcp.py

测试使用临时数据目录、独立偏好域和随机端口，不操作正式便签。覆盖：

• 待办清单 第一位排序、常驻开关与数据保留。
• UUID / 编号一致性、删除后不复用、旧任务迁移和重启后继续编号。
• 真实 NSHostingView / NSTextView 的 A → B → A 切换，以及未保存输入的保留。
• TODO 提醒时间边界、完成与改期、开关和普通 note 隔离。
• HTTP 鉴权、参数校验、批量与并发、分片请求、大小限制、API 开关与客户端调用。
• 加密持久化，以及深浅色 / 三种尺寸的界面渲染。

渲染结果位于 build/todo-preview-light.png 与 build/todo-preview-dark.png。

测试或调试可显式设置：

Sources/                  Swift 应用源码
  TodoItem.swift          独立任务模型与编号
  TodoListView.swift      任务卡片、筛选、编辑与进度
  NoteStore.swift         排序、加密持久化与任务操作
  NoteEditor.swift        普通便签原生编辑器
  OverdueWatcher.swift    待办清单 提醒状态
  LocalAPI.swift         本机 HTTP 服务与接口
assets/                   LOGO、应用图标与生成脚本
skills/e-note/            AI Skill 与 Python 客户端
scripts/install_skill.py  Skill 安装入口
docs/API.md               完整接口协议
server/                   账号、同步、执行锁与部署脚本
bridge/                   飞书长连接、CLI 调用、进程与消息日志
Tests/                    原生双客户端、同步冲突、桥接执行与基础回归测试
build.sh                  应用构建入口

LOGO 以蓝色 E 字母结合叠层便签，源文件为 assets/make_icon.swift；执行 ./assets/build-icon.sh 可重新生成 PNG 和 ICNS 图标。

修改代码后打开的仍是旧版？ 先退出正在运行的 E note，再打开 build/E note.app。只重新编译不会替换已运行进程的代码。

API 配置不存在或连接失败？ 确认应用正在运行，并在设置中开启 API；启动失败时可在同一页面查看端口占用等原因。客户端的配置路径需要与当前应用的数据目录一致。

关闭 待办清单 后任务不见了？ 打开便签库查看，或重新开启常驻开关；关闭显示不会删除任务。

普通 note 的待办为什么不再弹出？ 主动提醒集中到独立 待办清单。把需要提醒的事项添加到 待办清单 并设置到期时间即可。

为什么构建有登录项相关警告？ 当前登录启动沿用 LSSharedFileList，SDK 会给出弃用警告；这部分不是 待办清单 或 API 的新增依赖。

屏幕边缘便签的交互参考开源项目 aimen08/noty。本项目面向 macOS 13，使用 Swift 直接编译。

当前使用自建云端同步，不接入 Apple iCloud。Markdown 即时渲染、图片粘贴和 Sparkle 自动更新尚未提供。飞书正式收发需要配置自己的应用机器人，电脑执行需要应用和桥接保持运行。

本项目采用 MIT License，允许使用、修改、分发和商业使用，分发时需保留版权声明及许可文本。软件按现状提供，不附带担保。

许可文件保留本项目作者韦冬及参考项目 aimen08/noty 原作者 Aymen Hamza 的版权署名；第三方依赖遵循各自的许可证。

当前已验证范围和待接入项见 验证记录。

支持 AI 查询和操作便签、待办与标签，提供 19 个本机工具。参见 MCP 安装和使用。

• 待办输入框独立维护草稿，打字时不重新计算整个列表，也不触发保存；提交成功后清空。
• 悬浮便签展开后，双击侧边竖标签，可在原尺寸与宽高各 2.5 倍之间切换；放大尺寸受屏幕可用范围限制。
• 待办卡片的写入图标用于创建关联便签，文档图标用于查看已有便签。在便签库中直接切换详情，在悬浮栏中展开便签。
• 关联使用稳定任务 UUID，便签标题栏显示当前 T000001 编号。重复点击复用同一便签，已归档或软删除的关联便签会恢复。
• 云端工作流复用该任务的已有便签和工作流；此项需要部署更新后的 server/enote_server.py。