关于 remctl
RemCTL 是面向 macOS Reminders 的命令行工具和 MCP 服务,适合需要通过 AI 客户端读取或管理提醒的用户。它通过持有系统权限的签名应用访问本地数据,写入使用 EventKit 或可选的 ReminderKit,而不直接改写数据库。
主要功能
- 01读取今日、即将到期、逾期和已标记提醒
- 02搜索提醒并查看列表或单条详情
- 03创建、更新、完成、标记和删除提醒
- 04管理提醒列表并恢复最近删除项
- 05通过权限诊断检查服务状态
适用场景
- 01在 AI 客户端中查看今天或逾期的提醒
- 02搜索并检查特定列表中的提醒
- 03创建提醒或更新其到期时间
- 04完成、标记或恢复提醒
MCP 相关
RemCTL 提供本地 MCP 服务,向 MCP 客户端开放提醒和列表的读取与写入工具。也可将工具通过 Tailscale 提供给其他设备;推荐使用专用 MCP 工具而非命令行处理提醒。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ viticci/ remctl --skill remctl安装后在 Claude Code 中输入/remctl确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
README.mdCHANGELOG.mdLICENSE.gitignore.agents/plugins/marketplace.json.claude-plugin/marketplace.jsondocs/desktop-capabilities.mdarchitecture.mddesktop-plugin.mdcommands.mdmcp.mdhermes.mdinstallation.mddocs/notes/README.mdevent-demo-results.jsonaudit-2026-10-02.mddistribution-permission-continuity.jsondistribution-validation-2026-09-30.mdicon-provenance.mdevents-2026-09-30.mdissues-57-59-2026-10-03.mddesktop-validation-2026-09-30.mdmacos27-compat-review.mdpr-fixes-2026-10-02.mdrelease-2.0.4-validation.mdrelease-2.1.0-validation.mdrelease-2.0.0-validation.mdprivate-api-audit-2026-08-12.mdrelease-2.0.2-validation.mdrelease-2.0.3-validation.md详细介绍
RemCTL
RemCTL 是 macOS 上的提醒事项命令行工具和 MCP 服务。数据命令会在已签名的应用 RemCTL Capability Host.app 中运行,由它持有 macOS 权限。你自己的进程无需获得“完全磁盘访问权限”、“提醒事项”或“自动化”权限。读取操作来自本地提醒事项数据库。写入操作通过 EventKit 执行;如果用户使用 --private 选择启用,则通过 Apple 的私有 ReminderKit 框架执行。RemCTL 绝不会直接写入数据库。
使用本地 MCP 服务
对于所有提醒事项的读取和写入操作,请使用 mcp__remctl__<tool>,即这台 Mac 上本地运行的 RemCTL 2.0 服务。优先使用它,而不是 Mac Remote 连接器提供的 RemCTL 封装。请勿为提醒事项操作调用 CLI,也不要在 MCP 连接失败时静默回退到 CLI。
专用工具包括 today、upcoming、overdue、flagged、search、show_list、lists、get_list、get_reminder、resolve_location、create_reminder、update_reminder、set_completion、set_flagged、delete_reminder、recently_deleted、restore_reminder、create_list、update_list 和 doctor。这些工具会验证参数并返回 structuredContent;列表结果会将行包装在 items 中,并附带 count。在将调用视为成功之前,请检查 isError 和 structuredContent.error。
仅在没有专用工具的操作中使用 run,包括私有元数据。传入包含确切参数项的 args 数组,添加 --json;对于已授权的破坏性操作,还要添加 --force。这仍会通过 MCP 运行。run 会拒绝 mcp、onboard、setup、permissions、completion 和 open。Shell 命令仅用于安装、修复连接、设置权限,或在用户明确要求使用 CLI 时。若缺少工具,请检查或修复本地注册,并重新连接客户端。
MCP 工具参数示例:
today({"include_overdue":true})
show_list({"list":"Work"})
get_reminder({"reminder_id":23880})
create_reminder({"title":"Research","list":"Work","due":"2026-09-20 15:00","priority":"high"})
update_reminder({"reminder_id":23880,"due":"clear"})
search({"query":"macstories.net","list_id":153,"offset":100})
set_completion({"reminder_ids":[23880,23881],"completed":true})
get_list({"list":"Shopping"})
create_reminder({"title":"Research","list":"Projects","private":true,"tags":["remctl"],"url":"https://example.com","section":"Research","subtasks":["Outline"]})
resolve_location({"query":"Piazza Navona, Rome"})
update_reminder({"reminder_id":23880,"private":true,"location_address":"Piazza Navona, Rome","location_title":"Stamps","radius":150})
run({"args":["sections","--json"]})
run({"args":["edit","23880","--private","--set-tags","remctl,work","--json"]})
以下命令语法用于说明底层选项,并非要求使用 shell。只要有可用的具名专用 MCP 工具,就使用该工具;否则将此语法转换为 run.args,并省略 remctl 可执行文件。请阅读 docs/mcp.md,了解当前的类型化参数约定和连接详情。调用前请检查实时工具架构。对于同步标签、富链接、分区、子任务、分配、提前提醒、紧急状态、“杂货”分类和位置闹钟,create_reminder 和 update_reminder 需要设置 private: true;否则会拒绝这些字段,url 会附加到备注中,而 create_reminder 的 tags 会变为 #hashtags。设置 private: true 时,update_list 会转换杂货清单。图片、排序、分组、智能列表和模板仍需使用 run。
设置与诊断
安装并完成首次设置。用户可以从发布版磁盘映像中打开“Install RemCTL”,也可以从代码检出目录构建:
cd /path/to/remctl && ./install.sh --from-source --bootstrap
remctl onboard
直接运行 ./install.sh 则会下载并安装经过公证的发布版。两种方式都只会要求用户输入一次管理员密码,以安装 RemCTL 受保护的 Python。
onboard 是一个引导流程:设置 macOS 权限、运行健康检查、连接 Mac 上的 AI 应用,并可选择通过 Tailscale 将工具提供给用户的其他设备。每项更改前都会征求同意。onboard --json 会运行检查并报告检测到的应用,不会征求同意。如果它打开了“全磁盘访问权限”辅助工具,请暂停:用户必须在“系统设置”中添加确切的宿主应用(doctor 中的 capabilityHost.app.path),然后重启宿主:
launchctl kickstart -k "gui/$(id -u)/net.macstories.remctl.capability-host"
使用 doctor MCP 工具检查就绪状态。如果 MCP 本身无法启动,请使用以下设置诊断命令:
remctl doctor --for-agent --json
查看 access.effective。就绪状态意味着 route: "capabilityHost"、ready: true、capabilityHost.fullReady: true、capabilityHost.protocolVersion: 2、capabilityHost.privateProtocol.compatible: true,并且 capabilityHost.permissions 下的 fullDiskAccess、reminders 和 automation 均为 authorized。access.direct 仅描述用户自己的进程,通常会被阻止;这是正常的。确认就绪后,无需在每项任务前运行 doctor。
连接 AI 应用:
remctl mcp install --client claude-code # claude mcp add
remctl mcp install --client codex # codex mcp add
remctl mcp install --client claude-desktop # Claude Desktop and Cowork; the user must restart Claude
remctl mcp install --client tailscale # HTTPS endpoint for the user's other tailnet devices
remctl mcp status
remctl mcp config --format tailscale # commands for another device; the token stays in its Keychain
tailnet 令牌可以读取和更改用户的提醒事项。只有用户提出要求时才使用 remctl mcp token 打印该令牌,并且绝不要将其写入命令、shell 文件、配置文件或聊天中。用户在另一台设备上使用 security add-generic-password -U -a remctl -s remctl-mcp-token -w 保存令牌;该命令会提示输入令牌。
Codex 插件提供自己的 RemCTL 连接,remctl mcp install 会将 Codex 留给该插件处理。旧版安装留下的连接会隐藏插件的侧边栏入口;remctl doctor 会将其报告为重复连接,remctl mcp remove --client codex 可以将其移除。随后用户重启 Codex。请参阅 docs/desktop-plugin.md。
Claude Code 插件(remctl@remctl)也提供自己的连接,因此其工具名称为 mcp__plugin_remctl_remctl__<tool>。remctl mcp install 也会将 Claude Code 留给该插件处理。remctl doctor 会将旧连接报告为重复连接,remctl mcp remove --client claude-code 可以将其移除。请参阅 README.md。
升级时会保留安装时使用的签名方式:从源代码构建时运行 git pull && ./install.sh --from-source(包括使用 Apple Development 证书签名的 2.0 预发布版),或使用新发布版中的“Install RemCTL”(或运行 ./install.sh)进行下载。若未提供 --migrate-signing,安装程序会拒绝更改签名方式;除非用户要求切换,否则不要添加该标志,因为这意味着需要再次授予“全磁盘访问权限”。从 1.7.1 起,安装程序会在替换旧文件前于 Terminal 中征求同意;如果没有终端,则需要使用一次 --adopt-existing-install。然后运行 doctor。只有当 doctor 报告权限问题时,才再次运行 onboard。不要手动复制或重新签署宿主应用,也不要把重置 macOS 隐私记录作为常规修复方法。绝不要向 Terminal、Python、Hermes、Codex 或 Claude 授予“全磁盘访问权限”、“提醒事项”或“自动化”权限;只有宿主需要这些权限。
始终适用的规则
- 对于
info、edit、done、undone、delete、link、open和subtasks,请使用 JSON 中的数字id。切勿传入deepLink中的 UUID。 - 使用确定的截止日期:全天提醒采用
YYYY-MM-DD,定时提醒采用YYYY-MM-DD HH:MM,并根据用户所在时区解析。clear会移除截止日期。无法解析的日期会在任何写入操作前终止命令,并返回code: "invalid_due_date"和示例;请更正后重试。 - 破坏性命令(
delete、list-delete、section-delete、group-delete、smart-list-delete、template-delete)在使用--json或没有终端时都需要--force。未提供时,不会写入任何内容,stderr 会返回code: "confirmation_required"。仅在获得用户授权后删除;用户明确提出删除请求即表示已授权。 - 按名称或
--list-id指定目标列表,不能同时使用两者。名称会依次按完全匹配、忽略大小写匹配、标准化匹配解析(Weekly 513可匹配🗓️ Weekly 513)。如果匹配到多个列表,命令会停止并列出候选 id;请使用--list-id。群组不能作为提醒写入操作的目标。 - 对于重复提醒、闹钟、优先级、备注或普通列表移动,不要传入
--private;这些都是 EventKit 功能。仅在处理私有元数据中的元数据或用户提出要求时使用--private。 - 除非任务明确接受有限的数据,否则不要使用
--via-eventkit。它会返回没有任何数字 id 命令可接受的eventKitId值,并且不包含分区、标签或私有字段。 search会搜索未完成提醒的标题、备注和已保存的富链接,并忽略大小写和重音符号;添加--completed可包含已完成的提醒。MCP 工具始终会返回一页结果:当hasMore为 true 时,请使用nextOffset作为offset再次调用。使用list或list_id限定范围。done、undone和delete(MCP 的reminder_ids)最多接受 50 个 id。请读取succeeded、failed和uncertain。对于uncertainid,先调用get_reminder,切勿直接重试:每次完成重复提醒都会将其推进到下一个 occurrence。- JSON 会保留原始的 Reminders 文本。人类可读输出会去除控制字符,并添加标记(
⚑、!!!、🔗、🌄),这些标记不会出现在 JSON 中。 - 切勿自行读取或写入 Reminders SQLite 数据库。
阅读
| 任务 | CLI | MCP 工具 |
|---|---|---|
| 今天到期及已逾期 | remctl today --json | today |
| 接下来 N 天 | remctl upcoming 7 --json | upcoming |
| 仅逾期 | remctl overdue --json | overdue |
| 已标记 | remctl flagged --json | flagged |
| 搜索 | remctl search "query" [--completed] [--list NAME|--list-id ID] [--limit N --offset N] --json | search |
| 单个列表,按 Reminders 中的顺序 | remctl show Work --json、remctl show --list-id 153 --json | show_list |
| 所有列表及其 ID | remctl lists --json | lists |
| 单个列表及其分区 ID 和共享对象 | remctl list-info Work --json | get_list |
| 查询地址是否适用于位置提醒 | remctl location-lookup "ADDRESS" --json | resolve_location |
| 单条提醒的完整信息 | remctl info 23880 --json | get_reminder |
| 群组、分区、标签、子任务、共享对象、统计信息、智能列表、模板 | remctl groups --json、sections --json、tags --json、subtasks ID --json、sharees LIST --json、stats --json、smart-lists --json、templates --json、template-info NAME --json | run |
行字段:id、title、list、completed、flagged、urgent、priority、subtaskCount、dueDate、allDay、deepLink,以及存在时的 notes、section、recurrence 和 attachments。info 还会添加 alarms、earlyReminder、tags、subtasks、assignment 和富链接 url。dueDate 是实际到期日期。如果提醒显示在其他时间,则会出现 displayDate,例如绝对提醒仍指向旧时间时。Reminders.app 会在 displayDate 显示并标注该提醒,today、overdue 和 upcoming 也会将其归入该时间。attachments[].path 是经主机验证的文件位置;对于未下载到此 Mac 的文件,该值为 null,且 resolved: false。这并不意味着你的进程可以打开该文件。
写入
| 任务 | CLI | MCP 工具 |
|---|---|---|
| 创建 | remctl add "Title" -l Work -d "2026-05-20 15:00" -p high --json | create_reminder |
| 编辑字段 | remctl edit 23880 --title "New" -d clear -n "Notes" --json | update_reminder |
| 移至列表 | remctl edit 23880 -l Work --json | 使用 list 或 list_id 的 update_reminder |
| 完成、取消完成 | remctl done 23880 [23881 …] [--date 2026-05-27] --json、remctl undone 23880 --json | 使用 reminder_id 或 reminder_ids 的 set_completion |
| 标记、取消标记 | remctl flag 23880 --json、remctl unflag 23880 --json | set_flagged |
| 删除 | remctl delete 23880 [23881 …] --force --json | 使用 reminder_id 或 reminder_ids 的 delete_reminder |
| 创建或编辑列表 | remctl list-create NAME --json、remctl list-rename、remctl list-edit … --private | create_list、update_list |
| 重复、提醒 | remctl add "Standup" -d "tomorrow 09:30" --recurrence "weekly mon,wed,fri" --alarm 15m --json | 使用 due 的 create_reminder / update_reminder |
| 重新排序 | remctl reminder-move 23880 --before 23881 --private --json | run |
create_reminder会返回status: "created"、下次调用所需的数字id,以及 CloudKitcloudKitId。CLI 的add --json使用不同的名称:id是 UUID,numericId是数字。如果无法读回该数字,create_reminder不会返回id,并会发出numeric_id_unavailable警告;请按标题使用search或show_list查找提醒事项。add -f/--flag会先创建提醒事项,再通过自动化设置旗标。如果设置旗标的步骤失败,结果仍为created,并带有warnings: ["flag_not_set: …"]。不要再次运行add;请改为对返回的 id 设置旗标。edit -l和edit --list-id通常会保留 id。当 EventKit 拒绝纯粹的移动操作(例如含有子任务的父级提醒事项、跨共享列表移动)时,RemCTL 会通过 ReminderKit 克隆并删除提醒事项,并返回method: "clone-delete"、oldId和新的id。请继续使用新的id。先移动,再应用其他编辑。edit -d会移动与旧到期时间匹配的绝对闹钟,因此 Reminders 中显示的时间会随到期日期变化。Reminders 可能会为每台处理过该提醒事项的设备保留一份闹钟副本,所有副本都会移动。目标仅包含日期时,会清除这些副本,而不是将它们移至午夜。显式指定的--alarm优先。如果提醒事项有其他闹钟,其闹钟会保持原样。edit -d clear会移除匹配的闹钟,但重复提醒事项必须保留到期日期:edit会拒绝执行并返回code: "repeating_reminder_requires_due_date",且不会更改任何内容,除非同一次编辑还传入了--recurrence clear。done --date只接受YYYY-MM-DD或YYYY-MM-DD HH:MM,且不适用于重复提醒事项;直接运行done会推进重复序列。flag/unflag成功时返回status: "flagged"或"unflagged";失败时返回退出码 1,并在 stderr 上输出code: "applescript_flag_failed",旗标保持不变。常见原因:主机没有自动化访问权限,或 Reminders 在 120 秒内未作出响应。也可以通过edit ID --private --flagged或--no-flagged使用 ReminderKit 设置旗标。reminder-move需要--private。在同一列表内移动时,锚点必须位于同一列表中。--smart-list NAME或--smart-list-id ID可对未分区的自定义智能列表重新排序;分区智能列表不支持此操作。成功时返回verified: true。
重复规则语法:daily、weekly、monthly、yearly;频率后可紧接间隔(daily x2,N 为 1 至 999);每周可指定星期几(weekly mon,wed,fri);每月可指定日期(monthly 1,15)或序数星期几(monthly 4th-fri、monthly 1st-mon,3rd-mon、monthly last-fri),但两种格式不可混用。优先使用 last-fri,而不是 5th-fri。edit --recurrence clear(或 none、never)会移除重复规则。无效的重复规则、闹钟和优先级值会在写入前报错。重复规则和相对闹钟(15m、1h、1d)需要到期日期:使用 add 时传入 -d(MCP due);edit 也可以使用提醒事项已有的到期日期。如果没有到期日期,相对闹钟会以 code: "relative_alarm_requires_due_date" 报错停止,Reminders 也会拒绝保存重复提醒事项;不会写入任何内容。
最近删除
使用 recently_deleted 查找可恢复的提醒。当 hasMore 为 true 时,继续读取 nextOffset;分页统计父项,并将子任务嵌套其中。使用 get_reminder 并设置 include_deleted: true,可以检查已删除的 ID。原列表可能已不可用,且已删除的详细信息不包含所有私有元数据。
要恢复提醒,请调用 restore_reminder,传入该项的 restoreId、同一账户中的目标 list 或 list_id,以及 private: true。这会恢复父项及其子任务,并保留原始 ID。不要使用 create_reminder 重新创建。verified: true 表示已读取回 ID 和层级;对于已在该列表中的活动 ID,already_restored 是空操作,且不会验证其原有子任务。对于 restore_unconfirmed,请检查该 ID,并刷新“最近删除”后再重试。
Apple 通常会保留已删除的提醒 30 天。不要根据数据库删除标记承诺期限或可恢复性。RemCTL 会查询 Apple 的恢复视图,不会显示永久清除操作。请参阅恢复详情。
私有元数据
--private 通过 ReminderKit 写入仅限 Reminders 使用的字段。适用于:同步的富链接(--url)、同步的标签(-t 添加;--set-tags 替换;--remove-tag 和 --clear-tags 移除)、分区(--section、--section-id、--new-section 和 section-* 命令)、共享列表分配(--assign、--unassign)、子任务(--subtask TITLE 或 JSON 对象)、图像附件(--image PATH)、标记和紧急状态(--flagged、--urgent)、提前提醒(--early-reminder 15m|1h|2d|1w|1mo|clear,需要设置截止日期)、位置闹钟(使用 --location-title 和 --latitude、--longitude,或使用 --location-address;通过 EventKit 保存,但受 --private 控制)、排序(reminder-move)、列表外观和固定项(list-create、list-edit、list-pin、list-unpin)、杂货列表(--groceries、--grocery)、群组(group-*)、自定义智能列表(smart-list-*)和模板(template-*)。
remctl add "Research" -l Projects --private --url https://example.com -t remctl --section Research --json
remctl edit 23880 --private --set-tags remctl,work --json
remctl edit 23880 --private --subtask '{"title":"Follow up","due":"2026-06-01","tags":["work"]}' --json
remctl edit 23880 --private --assign [email protected] --json
remctl section-create "Research" -l Projects --private --json
规则:
- 富链接必须使用公开的
http或https主机。未使用--private时,--url会追加到现有备注中(或追加到通过--notes明确指定的替换内容中);add -t会添加标题#hashtags,而edit -t需要使用--private。 - 富链接和图像只会追加;RemCTL 不会移除或替换现有内容。通用文件和 PDF 会被拒绝。
--section按名称解析;如果同一列表中有重名分区,RemCTL 会使用唯一的非空分区,否则请使用--section-id。创建分区和重命名分区时,不允许名称重复。--assign接受唯一名称、电子邮件或电话号码、数字形式的共享对象id、objectUUID或me。请先调用sharees LIST --json,并优先使用地址或 ID。--location-address(MCPlocation_address)会在写入任何内容前进行地理编码。RemCTL 只会使用符合以下条件的匹配结果:单一且精确到街道范围、与输入的街道名称一致,并且地址还包含城镇或邮政编码。location_not_found、location_ambiguous(读取candidates)、location_imprecise(整个城市或区域)、location_unconfirmed(街道不一致或缺少城镇;读取reason)以及location_label_not_address(Home、Work)都不会更改任何内容。切勿自行将个人标签转换为地址;请向用户询问地址,并将标签作为--location-title传入。- 子任务 JSON 字段:
title、notes、due、priority、alarm、recurrence、earlyReminder、url/urls、tags、image/images、flagged、urgent和位置字段。 - 如果提醒已创建,但后续私有步骤失败,
add --json会返回status: "partial",并包含numericId、failed和error。请使用edit完成操作;不要再次运行add。
列表、群组、杂货清单
list-create --color NAME使用 EventKit。精确的#RRGGBB颜色、--symbol(仅限list-symbols中的官方名称)、--emoji、杂货清单模式和固定功能都需要--private。list-pin/list-unpin也可以按名称或--smart-list-id操作智能列表。请在smart-lists --json(pinned、正数pinnedDate)中验证智能列表的固定状态,而不是在lists --json中验证。在不具备通用 ReminderKit 获取功能的主机上(Tahoe 26.2 和 Golden Gate 27.0),固定内置智能列表会在保存前失败。- 群组包含列表,而不包含提醒事项。
group-create、group-edit(--new-name、--add-list、--remove-list、--move-list,以及--before-list、--after-list、--first、--last)、list-create --private --group和group-delete只会移动容器。请使用group-info、groups --json、lists --json、show <group> --json验证。 - 杂货清单在
lists --json中显示listType: "groceries"。仅在此类清单中使用add --private --grocery和edit --private --grocery,然后在show <list> --json中检查section。
智能列表
smart-lists --json 为只读操作。smart-list-create、smart-list-edit 和 smart-list-delete 需要 --private,并通过精确名称或 --smart-list-id 操作自定义智能列表。支持的筛选条件:--any-tag;--tags a,b,搭配 --tag-match all|any;--date any|today,以及 --date-today-include-past-due、--date-on、--date-before、--date-after、--date-range START,END;--time morning|afternoon|evening|night;--priority high|medium|low|none(none 表示无优先级)或逗号分隔的列表;--flagged;--vehicle connected;一个 --include-list 或 --include-list-id;--match all|any;外观选项 --color、--symbol、--emoji。不支持:未标记、无日期、相对日期、无时间、车辆断开连接、排除列表、包含多个列表,以及旧版简短标签 JSON。不要在一个智能列表中汇总多个列表。--filter-json 接受原始筛选条件 JSON 或 @path,并会进行验证。仅使用 --match 或 --tag-match 的编辑操作会报错。请在 smart-lists --json 中验证:objectUUID、解码后的筛选条件、filter.supported 和 minimumSupportedVersion 20220430。
模板
templates --json 和 template-info 为只读操作。template-create --from-list NAME|--from-list-id ID [--include-completed]、template-apply 和 template-delete 需要 --private,且仅适用于整个列表。不要承诺可以编辑模板中的单条提醒事项,也不要承诺可以创建 iCloud 模板链接。请使用 templates --json、template-info 验证;应用模板后,再使用 lists --json 和 show <new list> --json 验证。
验证
写入后,请通过 MCP 重新读取数据:
- 提醒事项字段、标签、分区、子任务、闹钟、提前提醒、富链接、分配:
get_reminder({"reminder_id":ID})。 - 列表顺序:使用精确的
list或list_id执行show_list。 - 列表外观和杂货清单元数据:
lists;群组:使用group-info和--json执行run。 - 智能列表和固定状态:
run({"args":["smart-lists","--json"]})。 - 模板:使用
templates或template-info和--json执行run。 - 如果跨设备同步很重要,请让用户在另一台设备上检查。
排查日期不匹配问题时,请先比较 dueDate、displayDate 和 alarms,再判断是否存在错误。
错误
| 信号 | 含义 | 操作 |
|---|---|---|
code: "invalid_due_date" | 无法解析截止日期;未写入任何内容 | 使用 YYYY-MM-DD 或 YYYY-MM-DD HH:MM 重试 |
code: "confirmation_required" | 未使用 --force 执行破坏性命令;未写入任何内容 | 确认已获授权,然后添加 --force |
status: "partial" | 已创建提醒,但一个私有步骤失败 | edit 返回的 numericId;不要再次执行 add |
批次中的不确定 id、code: "completion_uncertain" 或 "write_uncertain" | 写入可能已生效 | 重试前,逐个检查每个 id 的 get_reminder;切勿盲目再次完成重复提醒 |
code: "location_…" | 地址查询被拒绝;未写入任何内容 | 按提示操作:提供更完整的地址、某个候选位置的坐标,或询问用户 |
warnings: ["flag_not_set: …"] | 已创建提醒,但未设置标记 | 为返回的 id 设置标记 |
code: "applescript_flag_failed" | 标记未更改 | 使用 doctor 检查主机的自动化授权;或使用 edit --private --flagged |
| 匹配到多个列表 | 列表名称不明确 | 使用 --list-id |
| Capability Host 不可用或尚未就绪 | 主机已停止或缺少权限 | 运行 remctl doctor --for-agent --json,然后按其打印的步骤修复;如果协议版本不是 2,则重新安装 |
remctl-private is outdated | 封装助手版本低于 CLI | 使用相同方式重新安装:./install.sh --from-source 或安装最新版本 |
权限
主机是 macOS 隐私权限的唯一目标。只有在缺少「提醒事项」和「自动化」权限时,onboard 才会请求这些权限,并指导用户授予「完全磁盘访问权限」,macOS 仅允许手动授予该权限。更改「完全磁盘访问权限」后,重启主机并运行 doctor。如果 doctor 报告「提醒事项」或「自动化」权限被拒绝,请在对应的「系统设置」面板中启用 RemCTL Capability Host,然后再次运行 onboard。remctl permissions full-disk-access 会重新打开「完全磁盘访问权限」助手。刚启动的主机在确认状态前,可能会将「自动化」报告为 targetNotRunning 或 unknown;「提醒事项」无需保持打开。
若要审计私有 API 漂移,请向已安装的 remctl-private 发送 {"action":"capabilities"};此操作只读,并会报告 saveCalled: false。若要检查已安装版本的实时发布状态:
REMCTL_CAPABILITY_HOST=force python3 scripts/live_private_matrix.py --remctl "$HOME/bin/remctl"