日历连接器 moziforge/calendar-plugins

calendar-plugins

DSH 插件，把智能体连接到日历服务商。

每个包集成一个服务商，并以 cordis 服务加面向模型的工具的形式，把它暴露给 DSH 配置档。各服务商共用 types.ts 里声明的归一化事件词汇表，所以无论哪个服务商应答，智能体看到的事件结构都一样。

| 包 | 服务商 | 状态 |
| @moziforge/calendar-icloud-plugin | 通过 CalDAV 访问 Apple iCloud Calendar | 已实现 |

你能得到什么

智能体可以调用四个工具：

| 工具 | 用途 |
| calendar_status | 报告访问是否已配置、是否可达。绝不返回密钥。 |
| calendar_list_calendars | 列出日历，含 id、名称、默认时区、颜色、组件。 |
| calendar_list_events | 列出某个时间窗口内的发生实例，重复系列会展开。 |
| calendar_create_event | 在某个日历里创建一条事件。 |

重复事件会展开成每个发生实例一条记录，已取消的发生实例会消失，全天值只保留日期，定时事件报告 UTC 时刻加上事件自身的 IANA 时区。完整的行为约定见包 README。

环境要求

- Node.js ^22.19.0 || >=24.0.0
- pnpm 12，用于从源码构建
- 一份 DSH 安装，用来挂载插件
- iCloud 需要：开启双重认证的 Apple ID，以及一个App 专用密码

构建

git clone https://github.com/moziforge/calendar-plugins.git
cd calendar-plugins
pnpm install
pnpm build

pnpm build 把每个包编译到各自的 dist/。DSH 加载编译后的 JavaScript，所以配置档必须指向已构建的检出目录。

iCloud 凭据

CalDAV 是进入 iCloud Calendar 唯一的编程途径；没有公开的 REST API。Apple 要求第三方客户端使用单独的密钥，因为开启双重认证后，Apple ID 密码会被拒绝：

1. 登录 <https://appleid.apple.com>。
2. 打开 Sign-In and Security → App-Specific Passwords。
3. 生成一个，复制 abcd-efgh-ijkl-mnop 这串值——它只显示一次。
4. 让运行 DSH 的进程能读到它：

export ICLOUD_ACCOUNT="you@example.com"
export ICLOUD_APP_PASSWORD="abcd-efgh-ijkl-mnop"

插件从你在配置里指定的环境变量读取密码——绝不从配置文件、配置档或工具参数读取——所以它不会被写进会话日志。ICLOUD_ACCOUNT 是 Apple ID 邮箱，不是密码。

挂载到 DSH 配置档

往配置档（或 --patch 覆盖层）里加两行：

- insert:
- id: calendar-icloud-host
name: '@moziforge/calendar-icloud-plugin/host'
config:
account: you@example.com
Optional: restrict every read and write to these calendars.
calendars: [Home, Work]

- id: calendar-icloud-tools
name: '@moziforge/calendar-icloud-plugin/tools'

这两行刻意分开：只写 host 这一行，插件代码就能拿到 ctx.calendar，同时不向模型暴露任何日历工具。

name: 字段按模块标识符解析，起点是配置档目录，所以包必须能在那里解析到——把它装进该配置档的依赖里，或者让 name: 指向构建后入口文件的绝对路径。/host 和 /tools 是包的导出子路径；/host 也可以省略，因为桶导出 . 重新导出了同一个服务。

配置参考

| 字段 | 默认值 | 含义 |
| account | '' | Apple ID；缺省时回退到 ICLOUD_ACCOUNT 环境变量。 |
| passwordEnv | ICLOUD_APP_PASSWORD | 存放 App 专用密码的变量名。 |
| serverUrl | https://caldav.icloud.com/ | CalDAV 入口；ICLOUD_CALDAV_SERVER_URL 可覆盖。 |
| calendars | [] | 日历名称或 id 的允许列表；留空则暴露全部日历。 |
| timeoutMs | 20000 | 单次请求的超时时间。 |

故障排查

- CALENDAR_NOT_CONFIGURED —— 缺少账号或密码变量。环境变量在请求运行时读取，但在进程启动时就已固定，所以请导出变量（或重新加载 .env），然后重启 DSH。
- CALENDAR_AUTH_FAILED —— iCloud 拒绝了凭据。请使用 App 专用密码，而不是 Apple ID 密码，并确认账号地址与你登录时用的一致。
- 找不到日历 —— 确认该 Apple ID 已启用「日历」，且账号至少拥有一个日历。
- 某个日历被判定为不支持 —— iCloud 会把提醒事项列表发布成 CalDAV 集合，它只接受 VTODO。这种集合不含事件，所以宽泛读取时会跳过，显式指定时会被拒绝。

验证

pnpm install
pnpm run typecheck
pnpm run lint
pnpm test

测试是黑盒的：它们让服务和真实的工具注册表跑在进程内的 CalDAV 测试夹具上，所以既不需要 Apple ID，也不需要网络访问。

许可证

Apache-2.0。见 LICENSE。