Sands：基于自然语言与开放标准的智能日程管理技能包

1. 项目概述：Sands，一个用自然语言管理日程的智能助手

如果你和我一样，每天要在多个日历（工作、个人）之间切换，处理各种会议、约会和待办事项，那你一定对传统日历应用的繁琐操作深有体会。手动拖拽时间、反复确认冲突、计算通勤时间……这些琐碎事务消耗的精力，远比事件本身还要多。Sands 的出现，正是为了解决这个痛点。它不是一个全新的日历应用，而是一个建立在现有日历服务（如 Google Calendar）之上的智能调度层，核心目标只有一个：让你用最自然的方式——“说话”，来管理你的一切日程。

简单来说，Sands 是一个遵循agentskills.io开放标准的技能包（Skill Package）。你可以把它理解为一个高度专业化、能听懂人话的“日历管家”。它通过自然语言指令，帮你完成日程的创建、查询、修改、删除，并能智能地检测冲突、寻找空闲时间、自动插入通勤时间块，甚至生成结构化的日程简报。它的设计哲学是“日历即结构化的调度平面”，将你散落在不同日历中的事件统一管理，并赋予其智能调度的能力。

这个项目特别适合两类人：一是追求效率、希望将日程管理自动化的极客和效率爱好者；二是正在构建或集成智能助理（AI Agent）的开发者，Sands 提供了即插即用的日程管理能力。接下来，我将深入拆解 Sands 的设计思路、核心功能实现，并分享在部署和使用过程中的实战经验与避坑指南。

2. 核心架构与设计理念解析

2.1 基于 agentskills.io 的开放生态

Sands 选择兼容agentskills.io开放标准，这是一个非常关键且明智的设计决策。这个标准定义了一套技能包（Skill Package）的通用接口和通信规范，使得 Sands 可以无缝集成到任何支持该标准的智能体框架中，例如 OpenClaw 或 Hermes Agent。这意味着，Sands 不是一个封闭的孤岛，而是一个可被多种“大脑”（智能体）调用的标准化“手”或“工具”。

为什么这个设计很重要？在 AI Agent 领域，一个常见的陷阱是“功能耦合”。开发者常常为一个特定的 Agent 框架编写紧密集成的功能，导致代码难以复用和迁移。Sands 通过遵循开放标准，实现了“高内聚、低耦合”。它只专注于日历管理这一件事，并通过标准化的 JSON 输入输出与其他组件通信。这种模块化设计，不仅让 Sands 更容易维护和升级，也极大地降低了其他开发者集成它的成本。对于想要构建个人智能助理的开发者来说，你不需要从头造轮子去解析自然语言处理日程，直接引入 Sands 技能包即可。

2.2 双日历策略与隐私保护

Sands 支持同时管理个人日历和工作日历，并采用了一种兼顾便利与隐私的策略：对工作日历仅进行“忙闲”覆盖。具体来说，Sands 拥有对你个人日历的读写权限，可以读取事件详情并进行修改。但对于工作日历，它通常只申请只读权限，并且在进行日程展示或冲突检测时，工作日历上的事件只会被显示为一个“忙碌”的时间块，其具体标题和详情会被隐藏。

这个设计的双重考量：

1. 实用性：在安排个人事务时，你必须知道工作时段是否已被占用。将工作事件视为不透明的“忙碌块”，足以避免日程冲突。
2. 隐私与安全：工作邮件和日历可能包含敏感的商业信息。限制 Sands 对工作日历的访问深度，是符合企业安全策略的常见做法。这也避免了因个人智能助理的漏洞而导致公司信息泄露的风险。在实际配置时，你需要分别在 Google Cloud Console 为个人和工作日历创建不同的 OAuth 2.0 客户端 ID 和密钥，并为它们分配恰当的 API 权限范围。

2.3 自然语言时间解析与上下文处理

Sands 的核心魔法在于将模糊的自然语言时间描述，转化为精确的 ISO 8601 时间范围。这背后通常依赖一个强大的自然语言日期时间解析库，例如 Python 的dateparser或更先进的 LLM 接口。

它如何理解你的话？

• 绝对时间：“明天下午三点开会” -> 解析为明天 15:00 开始的事件。
• 相对时间：“一小时后打电话给客户” -> 基于当前时间计算。
• 持续时间：“创建一个两小时的深度学习研讨会” -> 自动设置结束时间为开始时间后两小时。
• 复杂周期：“每周一下午的团队站会” -> 识别为重复事件，并可能调用日历 API 的recurrence规则字段。

这里有一个关键细节：时区处理。Sands 被设计为“时区感知”的。它不仅要处理用户当前所在的时区，还要处理事件发生地的时区（尤其是线上会议）。一个健壮的实现会在内部将所有时间统一转换为 UTC 时间戳进行存储和计算，在展示时再根据用户偏好或事件指定的时区转换回来。Sands 文档中提到的“双时区显示”功能，对于跨时区协作的用户来说是非常实用的。

3. 核心功能深度剖析与实操要点

3.1 智能冲突检测与灵活性分级

sands.conflicts命令不仅仅是告诉你“时间撞了”，它进行了更精细化的“灵活性分级”。这是 Sands 区别于普通冲突检测的亮点。

冲突分类逻辑解析：

1. 硬冲突：两个事件的时间范围完全或部分重叠，且都被标记为“忙碌”或“暂定”。这类冲突通常必须手动解决，比如取消或改期其中一个。
2. 软冲突：事件时间相邻（例如前后间隔只有5分钟），但没有重叠。Sands 会将其标记为“紧张”，提示你可能没有足够的缓冲或准备时间。
3. 基于标签/类别的冲突：这是更高级的功能。例如，你为事件打上了“深度工作”的标签，Sands 会检测到一天内是否有多个“深度工作”事件，并提示你这类事件过于密集可能导致效率下降。这需要 Sands 能够读取事件的description或extendedProperties字段中的自定义元数据。

实操心得：如何定义“灵活性”？在配置中，你可以（也应该）自定义冲突规则。例如，你可以设置：

• 所有标记为“健身”的事件，相互之间至少间隔6小时。
• “会议”类事件结束后，自动预留15分钟的“缓冲时间块”，这段时间内不允许安排其他“会议”。 这些规则可以通过扩展config.json来实现，让 Sands 的冲突检测更贴合你的个人工作流。

3.2 通勤时间块的自动插入

sands.travel功能是提升日程现实可行性的关键。它通过 Google Places API 的 Distance Matrix 服务，计算两点间的行程时间，并自动在日历中插入一个“通勤”事件。

其工作流程与技术细节：

1. 地点解析：当你创建事件“下午两点在XX咖啡馆见客户”，Sands 需要解析“XX咖啡馆”这个地点。它可能会先尝试在本地缓存的地点库中查找，若未找到，则调用 Google Places API 的“地点自动补全”或“地点详情”服务，将文本地址转化为精确的经纬度坐标和标准地址。
2. 模式感知的路由计算：这是该功能的核心。Sands 支持多种交通方式：
   • 驾车：考虑实时路况（API 可返回“最佳猜测”或“悲观估计”时间）。
   • 公共交通：提供基于时刻表的行程方案，包含步行到车站、乘车、换乘、步行到目的地全链路。
   • 步行/骑行：基于路径规划的距离计算时间。 你可以在事件中通过自然语言指定模式，如“骑车去健身房”，或在config.json中为特定地点对设置默认交通模式。
3. 智能插入与关联：计算出行程时间（例如25分钟）后，Sands 会在前一事件结束和后一事件开始之间，插入一个标题为“前往 XX咖啡馆”的25分钟日程块。这个块会被标记为“忙碌”或“外出”，并与前后事件建立关联。一个精良的实现会在“通勤”事件的描述中，包含导航链接和交通方式，当你点击日历时能一键启动地图导航。

注意事项与避坑指南：

• API 成本：Google Places API 不是完全免费的，Distance Matrix 服务每次调用都会计费。虽然个人使用量通常很小，但务必在 Google Cloud Console 设置预算提醒，防止意外滥用。
• 地址歧义：“去公司”这样的模糊地点，需要 Sands 依赖上下文。它可能需要与另一个技能包（如Elephas）交互，获取你的“常用地点”配置（如家庭地址、公司地址），或从历史事件中学习。
• 时间准确性：通勤时间受天气、时段影响巨大。建议在配置中为通勤时间增加一个“安全缓冲系数”（如计算时间的120%），避免因堵车而迟到。

3.3 结构化简报生成与技能联动

sands.brief命令生成的并非简单的事件列表，而是为另一个名为Vesper的技能包量身定制的结构化日程简报。这体现了 OCAS 套件中技能间“松耦合、强协作”的设计思想。

简报内容剖析：一份典型的Vesper简报可能包含以下结构化数据：

{ “date”: “2023-10-27”, “period”: “morning”, // 或 “evening” “events”: [ { “start”: “09:00”, “end”: “10:00”, “title”: “项目同步会”, “location”: “会议室A”, “attendees”: [“张三”, “李四”], “prep_signals”: [“查看项目进度报告”], // 准备信号 “travel_needed”: { “from”: “家”, “duration_minutes”: 30, “mode”: “driving” } } ], “free_blocks”: […], “conflict_alerts”: […], “summary”: “今天共有3个会议，主要聚焦于项目A…” }

技能联动的价值：

• Vesper：作为“简报员”，它接收这份结构化数据，并可能用语音合成在早上播报给你听，或者生成一封精美的邮件/消息摘要。
• Weave：负责处理“与会者身份解析”。当你说“和产品团队开会”，Weave技能包能根据你的通讯录和上下文，将“产品团队”解析为具体的成员邮箱列表，提供给 Sands 用于创建会议邀请。
• Voyage：如果 Sands 在日历中检测到包含航班、酒店预订确认号的事件，它会向Voyage技能包发送信号，触发旅行行程的自动整理和跟踪。

这种通过结构化文件（如events.jsonl）或共享知识图谱（Chronicle）进行通信的方式，使得每个技能可以独立开发、部署和更新，同时又能在更高层面上协同工作，形成一个强大的个人智能生态系统。

4. 部署、配置与日常运维实战

4.1 初始配置详解

虽然sands.init声称可以自动完成设置，但理解其背后的步骤对于排查问题至关重要。

手动配置核心步骤：

1. Google Cloud 项目设置：
   • 创建一个新项目或使用现有项目。
   • 启用Google Calendar API和Google Places API。
   • 创建OAuth 2.0 客户端 ID（类型为“桌面应用”或“Web 应用”，取决于你的运行环境）。你将得到client_id和client_secret。
   • 创建API 密钥，用于 Places API（此密钥无需用户授权，但需限制使用范围）。
2. 配置文件生成：sands.init会生成config.json，其核心结构如下：

   { “calendar”: { “personal”: { “calendar_id”: “primary”, // 通常是 primary “credentials_path”: “./credentials/personal.json” // OAuth令牌存储路径 }, “work”: { “calendar_id”: “你的公司日历ID”, // 需要从Google Calendar设置中获取 “credentials_path”: “./credentials/work.json”, “read_only”: true // 关键：设置为只读 } }, “google_places”: { “api_key”: “YOUR_GOOGLE_PLACES_API_KEY” }, “timezone”: “Asia/Shanghai”, “default_event_duration_minutes”: 60, “travel_buffer_multiplier”: 1.2 }

3. OAuth 授权流程：首次运行时，Sands 会打开浏览器，引导你分别登录个人 Google 账号和工作 Google 账号，完成授权。授权后生成的令牌会保存在上述credentials_path指定的文件中。

常见问题与解决：

• 错误：“redirect_uri_mismatch”：确保在 Google Cloud Console 的 OAuth 客户端设置中，已添加正确的授权重定向 URI。对于本地桌面应用，通常是http://localhost:8080或urn:ietf:wg:oauth:2.0:oob。
• 工作日历无法访问：公司可能限制了第三方应用访问日历的权限。你需要确认公司的 Google Workspace 管理员是否允许安装未经验证的应用程序，或者考虑使用服务账号（Service Account）进行授权，但这需要域管理员配合。

4.2 后台任务与自动化

Sands 通过内置的定时任务（Scheduled Tasks）实现了全自动管理，这是其“智能”的重要体现。

各任务作用与配置建议：

实操心得：日志与监控这些后台任务会输出日志到events.jsonl或独立的日志文件。建议定期检查日志，特别是sands:travel-check的日志，看是否有地点解析失败或 API 调用超时的情况。你可以使用tail -f命令实时查看，或使用logrotate工具管理日志文件大小。

4.3 数据持久化与撤销机制

Sands 将所有日历操作都记录到events.jsonl（JSON Lines格式）文件中。每一行是一个完整的操作日志。

日志记录的价值：

1. 审计追踪：谁在什么时候创建/修改/删除了什么事件，一目了然。
2. 撤销支持：sands.undo命令依赖于这个日志。它通常记录操作的反向指令（如“删除”对应之前的“创建”事件详情），并限制在24小时内可撤销，这是一个合理的平衡点，既提供了安全网，又避免了日志无限膨胀。
3. 状态恢复：在极端情况下，如果日历数据损坏，理论上可以通过重放events.jsonl中的创建事件来重建近期日程。

维护建议：

• 定期备份~/.sands/目录（或你的数据目录），其中包含config.json,events.jsonl和credentials/文件夹。
• events.jsonl文件会增长，可以编写一个简单的脚本，定期将超过30天的日志压缩归档。

5. 高级技巧与生态集成展望

5.1 利用 Chronicle 知识图谱进行上下文调度

Sands 作为 OCAS 套件的一部分，其长远潜力在于与Chronicle（长期知识图谱）的深度集成。这能让日程管理从“反应式”变为“预测式”。

设想中的智能场景：

• 基于历史模式的建议：Chronicle 记录了你过去几个月“每周三晚上通常去健身”。当你在周三下午创建一个新事件时，Sands 可以主动询问：“检测到这可能与你通常的健身时间冲突，需要调整吗？”
• 关联资源准备：如果你创建了一个“准备季度汇报”的事件，Chronicle 中关联了“汇报模板”文档和“上一季度数据”文件。Sands 可以在事件开始前，通过联动其他技能，自动将这些文件打开或推送到你的设备。
• 情绪与精力管理：如果 Chronicle 通过其他技能（如健康数据追踪）记录了你下午容易精力下降，Sands 可以在安排需要高专注度的“深度工作”块时，优先建议放在上午。

要实现这些，需要 Sands 不仅能读写日历，还能向 Chronicle 写入事件上下文，并从 Chronicle 中查询相关模式和事实。

5.2 自定义技能扩展

agentskills.io标准意味着你可以基于 Sands 进行二次开发，添加自定义功能。

扩展方向示例：

1. 会议室/资源预订：扩展sands.create，使其在解析到“预订小会议室”时，自动调用公司内部的会议室预订系统 API。
2. 与任务管理集成：创建一个桥接技能，当你在任务管理工具（如 Todoist, Jira）中将一个任务标记为“今日待办”时，自动在日历中为它分配一个时间块。
3. 自然语言查询增强：支持更复杂的查询，如“找出我和王经理本月所有一对一的会议”、“统计我上周在开会上的总时长”。

扩展的关键是遵循相同的输入输出规范，并确保新功能与核心功能的日志、撤销机制兼容。

5.3 故障排除与性能优化

常见故障点：

1. OAuth 令牌过期：Google OAuth 令牌通常有效期较短（几小时到几天），但有刷新令牌。Sands 应能自动处理令牌刷新。如果失败，需手动删除credentials/下的令牌文件，重新运行授权流程。
2. 网络与API限制：Google API 有调用频率限制。如果频繁操作日历或批量处理事件，可能触发限制。实现中应加入指数退避的重试机制。对于通勤计算，可以考虑缓存常用路线的时间结果。
3. 自然语言解析失败：当解析器无法理解“下下个礼拜五”这样的口语时，Sands 应给出友好的错误提示，并引导用户使用更清晰的表述，或提供一个快速选择日期的交互界面（如果运行在图形化Agent中）。

性能优化建议：

• 本地缓存：对日历事件进行短期缓存（如5分钟），避免频繁的 API 调用，尤其是在执行sands.free（查找空闲时间）这类可能需要多次查询的操作时。
• 批量操作：对于sands.travel-check这类需要为多个事件计算通勤的任务，应尽可能将多个地点对批量发送给 Distance Matrix API，以减少请求次数。
• 异步处理：耗时的操作（如计算一天所有事件的通勤）应设计为异步任务，避免阻塞主线程或用户交互。

从我个人的使用体验来看，Sands 代表了智能助理发展的一个务实方向：不追求大而全的通用模型，而是在一个垂直领域（日程管理）做深做透，通过标准化接口融入更大的生态。它的价值不在于替代 Google Calendar，而在于让你几乎“忘记”Google Calendar 的存在，只需用语言与你的数字生活自然交互。部署和磨合初期可能会遇到一些配置上的挑战，但一旦顺畅运行，它将成为你效率体系中一个安静而强大的基石。