mcpField
R
remctl

remctl

github.com/viticci生产力63739 次安装5 天前更新
代码仓库

关于 remctl

RemCTL 是面向 macOS Reminders 的命令行工具和 MCP 服务,适合需要通过 AI 客户端读取或管理提醒的用户。它通过持有系统权限的签名应用访问本地数据,写入使用 EventKit 或可选的 ReminderKit,而不直接改写数据库。

主要功能

  1. 01读取今日、即将到期、逾期和已标记提醒
  2. 02搜索提醒并查看列表或单条详情
  3. 03创建、更新、完成、标记和删除提醒
  4. 04管理提醒列表并恢复最近删除项
  5. 05通过权限诊断检查服务状态

适用场景

  1. 01在 AI 客户端中查看今天或逾期的提醒
  2. 02搜索并检查特定列表中的提醒
  3. 03创建提醒或更新其到期时间
  4. 04完成、标记或恢复提醒

MCP 相关

RemCTL 提供本地 MCP 服务,向 MCP 客户端开放提醒和列表的读取与写入工具。也可将工具通过 Tailscale 提供给其他设备;推荐使用专用 MCP 工具而非命令行处理提醒。

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/viticci/remctl --skill remctl

安装后在 Claude Code 中输入/remctl确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

README.md
CHANGELOG.md
LICENSE
.gitignore
.agents/plugins/
marketplace.json
.claude-plugin/
marketplace.json
docs/
desktop-capabilities.md
architecture.md
desktop-plugin.md
commands.md
mcp.md
hermes.md
installation.md
docs/notes/
README.md
event-demo-results.json
audit-2026-10-02.md
distribution-permission-continuity.json
distribution-validation-2026-09-30.md
icon-provenance.md
events-2026-09-30.md
issues-57-59-2026-10-03.md
desktop-validation-2026-09-30.md
macos27-compat-review.md
pr-fixes-2026-10-02.md
release-2.0.4-validation.md
release-2.1.0-validation.md
release-2.0.0-validation.md
private-api-audit-2026-08-12.md
release-2.0.2-validation.md
release-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。对于 uncertain id,先调用 get_reminder,切勿直接重试:每次完成重复提醒都会将其推进到下一个 occurrence。
  • JSON 会保留原始的 Reminders 文本。人类可读输出会去除控制字符,并添加标记(⚑、!!!、🔗、🌄),这些标记不会出现在 JSON 中。
  • 切勿自行读取或写入 Reminders SQLite 数据库。

阅读

任务CLIMCP 工具
今天到期及已逾期remctl today --jsontoday
接下来 N 天remctl upcoming 7 --jsonupcoming
仅逾期remctl overdue --jsonoverdue
已标记remctl flagged --jsonflagged
搜索remctl search "query" [--completed] [--list NAME|--list-id ID] [--limit N --offset N] --jsonsearch
单个列表,按 Reminders 中的顺序remctl show Work --json、remctl show --list-id 153 --jsonshow_list
所有列表及其 IDremctl lists --jsonlists
单个列表及其分区 ID 和共享对象remctl list-info Work --jsonget_list
查询地址是否适用于位置提醒remctl location-lookup "ADDRESS" --jsonresolve_location
单条提醒的完整信息remctl info 23880 --jsonget_reminder
群组、分区、标签、子任务、共享对象、统计信息、智能列表、模板remctl groups --json、sections --json、tags --json、subtasks ID --json、sharees LIST --json、stats --json、smart-lists --json、templates --json、template-info NAME --jsonrun

行字段: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。这并不意味着你的进程可以打开该文件。

写入

任务CLIMCP 工具
创建remctl add "Title" -l Work -d "2026-05-20 15:00" -p high --jsoncreate_reminder
编辑字段remctl edit 23880 --title "New" -d clear -n "Notes" --jsonupdate_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 --jsonset_flagged
删除remctl delete 23880 [23881 …] --force --json使用 reminder_id 或 reminder_ids 的 delete_reminder
创建或编辑列表remctl list-create NAME --json、remctl list-rename、remctl list-edit … --privatecreate_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 --jsonrun
  • create_reminder 会返回 status: "created"、下次调用所需的数字 id,以及 CloudKit cloudKitId。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(MCP location_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"

评论

支持 Markdown