JustCalendar CLI 技能

用途

本技能为 justcalendar（一款基于 Node.js 的命令行工具）提供完整的操作指南，该工具通过以下方式管理 Google Drive 中的 Just Calendar 数据：

1. 由后端（https://justcalendar.ai）签发 Google Drive 访问令牌
2. 直接调用 Google Drive API 读写日历数据文件

请使用本技能完成安装配置、登录认证、问题排查以及日常 CLI 操作。

何时使用本技能

当用户提出以下请求时，请使用本技能：

• 安装或更新 justcalendar
• 使用 Just Calendar 网页界面生成的令牌进行登录
• 添加、列出、重命名、删除或选择日历
• 对日历中的某日设置/获取/删除值
• 在终端中执行批量数据操作
• 排查令牌、认证或权限相关错误

前置条件

• Node.js >=18
• npm
• 可访问 https://justcalendar.ai
• 已在网页应用中建立与 Google Drive 的连接（这是生成令牌及启用 Drive 后备操作的必要前提）

安装

通过 npm 全局安装：

npm install -g justcalendar
justcalendar --help

从本地项目路径安装：

cd ~/justcalendar-cli
npm install
npm install -g .
justcalendar --help

若从 GitHub 安装：

git clone git@github.com:AndredAlmeida/justcalendar-cli.git
cd justcalendar-cli
npm install
npm install -g .
justcalendar --help

认证流程（网页 → CLI）

步骤 1：在网站生成令牌

1. 打开 https://justcalendar.ai
2. 在网页应用中登录并连接 Google Drive
3. 点击 Connect to your Agent（OpenClaw 按钮）
4. 点击 Generate New Token
5. 立即复制生成的令牌

重要提示：

• 令牌仅显示一次
• 生成新令牌将使旧令牌立即失效
• 若弹窗提示“令牌已存在但被隐藏”，请生成一个新令牌以获得可见的令牌

步骤 2：使用令牌登录 CLI

justcalendar login --token  --url https://justcalendar.ai

验证登录状态：

justcalendar status

预期输出应包含后端 URL、令牌状态，以及当前已加载的日历列表（如已成功认证）。

CLI 数据模型说明

• 日历选择器可使用 日历 ID 或 日历名称
• 日期格式严格限定为 YYYY-MM-DD
• 所有数据存储于 Google Drive 中名为 JustCalendar.ai 的文件夹下
• 主配置文件：justcalendar.json
• 日历数据文件：_.json
• CLI 本地配置：~/.justcalendar-cli/config.json

命令参考

会话 / 认证

justcalendar login --token  --url https://justcalendar.ai
justcalendar logout
justcalendar status

日历管理

justcalendar calendars list
justcalendar calendars add "Workout" --type score --color red --display heatmap --pinned
justcalendar calendars rename "Workout" "Workout Intensity"
justcalendar calendars remove "Workout Intensity"
justcalendar calendars select "Energy Tracker"

日历类型选项：

• signal-3
• score
• check
• notes

颜色选项：

• green、red、orange、yellow、cyan、blue

分数显示方式（仅适用于 score 类型）：

• number、heatmap、number-heatmap

日数据 — 设置

单条设置：

justcalendar data set "Energy Tracker" 2026-03-01 green

批量设置（单次调用中传入多组 ）：

justcalendar data set "Energy Tracker" 2026-03-01 green 2026-03-02 yellow 2026-03-03 red

日数据 — 删除

单条删除：

justcalendar data delete "TODOs" 2026-03-01

批量删除（单次调用中传入多个日期）：

justcalendar data delete "TODOs" 2026-03-01 2026-03-02 2026-03-03

日数据 — 获取

单条获取：

justcalendar data get "Sleep" 2026-03-01

批量获取（单次调用中传入多个日期）：

justcalendar data get "Sleep" 2026-03-01 2026-03-02 2026-03-03

批量优先原则（多日操作）

当处理多个日期时，应优先使用单条批量命令，而非循环调用单日命令。

默认应采用以下批量模式：

• justcalendar data set ...
• justcalendar data delete ...
• justcalendar data get ...

只要操作范围涉及多个日期，均应使用批量命令，包括但不限于：

• 日期区间
• 整周或整月操作
• 历史数据补录（backfills）
• 批量修复（batch fixes）

仅在以下情况下回退至单日命令：

• 批量命令长度超出 Shell / 操作系统对命令行长度的限制
• 需要对失败子集单独重试（per-day retries）

单日请求保持不变：继续使用现有的单日期命令形式。

批量操作示例

一周数据更新（单次 data set 调用）：

justcalendar data set "Energy Tracker" 
  2026-03-02 green 2026-03-03 yellow 2026-03-04 red 
  2026-03-05 green 2026-03-06 green 2026-03-07 yellow 2026-03-08 green

整月数据删除（单次 data delete 调用）：

justcalendar data delete "TODOs" 
  2026-02-01 2026-02-02 2026-02-03 2026-02-04 2026-02-05 2026-02-06 2026-02-07 
  2026-02-08 2026-02-09 2026-02-10 2026-02-11 2026-02-12 2026-02-13 2026-02-14 
  2026-02-15 2026-02-16 2026-02-17 2026-02-18 2026-02-19 2026-02-20 2026-02-21 
  2026-02-22 2026-02-23 2026-02-24 2026-02-25 2026-02-26 2026-02-27 2026-02-28

多日数据校验（单次 data get 调用）：

justcalendar data get "Sleep" 
  2026-03-01 2026-03-02 2026-03-03 2026-03-04 2026-03-05 2026-03-06 2026-03-07

性能与一致性说明：

• 批量命令可显著降低 CLI 和 API 的调用开销，并相比多次单日调用大幅减少部分写入（partial-write）风险。

按日历类型定义的值规则

signal-3

data set 接受的值：

• red
• yellow
• green
• x
• clear / unset / none（移除该日期的值）

score

接受的值：

• 整数，取值范围为 -1 至 10
• -1 表示取消设置 / 删除该值

check

真值（truthy）选项：

• true、1、yes、on、checked

假值（falsy）或未设置值（unset）选项：

• false、0、no、off、unchecked、clear、unset、none

notes

接受的值：

• 任意非空文本字符串（含空格时需加引号）

取消设置：

• 传入空值 / 空白值（或使用 data delete 命令）

推荐的操作流程

1. 检查连接状态：

justcalendar status

2. 列出所有日历：

justcalendar calendars list

3. 执行所需的日历或数据变更操作

4. 重新校验特定日期的数据：

justcalendar data get ""   ...

故障排查

Not logged in. Run: justcalendar login ...

• 使用有效令牌重新运行登录命令

invalid_agent_token / missing_agent_token

• 在网页应用弹窗中生成新令牌
• 重新执行：

justcalendar login --token  --url https://justcalendar.ai

missing_drive_scope

• 在网页应用中重新连接 Google Drive，并授权 Drive 访问权限（drive.file）
• 生成新的 Agent 令牌
• 在 CLI 中重新登录

token_refresh_failed / not_connected

• 服务器端的 Drive 会话已过期或断开连接
• 请在网站上重新连接 Google Drive，生成新令牌，并再次登录 CLI

日期格式错误

• 必须严格使用 YYYY-MM-DD 格式
• 确保日期合法（例如 2026-02-30 是非法日期）

日历名称不明确

• 请使用以下命令查看日历 ID：

justcalendar calendars list

安全性与行为说明

• calendars remove 操作具有破坏性，将永久删除指定日历及其关联的数据文件
• 批量 data set / data delete 操作在每次命令调用中仅发起一次最终写入
• 请严格保护 Agent 令牌，视同敏感凭证
• 可通过生成新令牌实现令牌轮换（旧令牌将自动失效）

快速入门示例

justcalendar login --token jca_... --url https://justcalendar.ai
justcalendar calendars list
justcalendar calendars add "Hydration" --type check --color cyan
justcalendar data set "Hydration" 2026-03-01 true 2026-03-02 true 2026-03-03 false
justcalendar data get "Hydration" 2026-03-01 2026-03-02 2026-03-03