Otta CLI

使用该技能，可通过可重复执行的 CLI 命令端到端完成 Otta 工时追踪任务。

主代码仓库：https://github.com/mekedron/otta-cli

快速开始

1. 直接使用 otta 二进制文件。

2. 验证命令接口及存储路径。

otta --help
otta config path
otta config cache-path

3. 完成身份认证并填充缓存。

otta auth login --username "$OTTA_CLI_USERNAME" --password "$OTTA_CLI_PASSWORD" --format json
otta status --format json

• status 命令会更新缓存中的用户元数据（供 worktimes、holidays、calendar 等命令在未显式指定 user 或 worktimegroup 时作为回退值使用）。
• 对于非交互式自动化场景，建议使用 --password-stdin 或通过环境变量安全传入密钥，以降低密码泄露至 shell 历史记录的风险。

命令示例

请在命令中显式使用 YYYY-MM-DD 和 HH:MM 格式的日期与时间。

列出工时记录：

otta worktimes list --date 2026-02-20 --format json

新增工时记录：

otta worktimes add 
  --date 2026-02-20 
  --start 09:00 
  --end 17:00 
  --pause 30 
  --project  
  --worktype  
  --description "示例任务描述" 
  --format json

• 若已设置环境变量 OTTA_CLI_USER_ID 或缓存中存在用户 ID，则 --user 参数为可选。

更新工时记录：

otta worktimes update --id  --start 10:00 --end 18:00 --format json

• 执行更新时，除 --id 外，至少需提供一个待变更字段。

删除工时记录：

otta worktimes delete --id  --format json

获取节假日/工作日历：

otta holidays 
  --from 2026-02-20 
  --to 2026-02-29 
  --worktimegroup  
  --format json

• 若已设置环境变量 OTTA_CLI_WORKTIMEGROUP_ID 或缓存中存在对应值，则 --worktimegroup 参数为可选。

浏览请假记录：

otta absence browse 
  --from 2026-02-01 
  --to 2026-02-28 
  --format json

获取当前累计余额（saldo）：

otta saldo --format json

生成综合日历概览：

otta calendar overview 
  --from 2026-02-01 
  --to 2026-02-28 
  --format json

生成详细日历（逐日报告）：

otta calendar detailed 
  --from 2026-02-01 
  --to 2026-02-28 
  --format json

当总量以分钟为单位时，可选用其他时间单位格式：

otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json --duration-format hours
otta worktimes browse --from 2026-02-01 --to 2026-02-28 --format json --duration-format days

• --duration-format 可选值：minutes（默认）、hours、days、hhmm
• 天数换算固定为：1 day = 24h = 1440 minutes

生成请假说明文本：

otta absence comment 
  --type sick 
  --from 2026-02-20 
  --to 2026-02-20 
  --details "流感症状" 
  --format json

环境变量

在 CI 或非交互式环境中运行时，请使用以下环境变量：

• OTTA_CLI_CONFIG_PATH
• OTTA_CLI_CACHE_PATH
• OTTA_CLI_API_BASE_URL
• OTTA_CLI_CLIENT_ID
• OTTA_CLI_USERNAME
• OTTA_CLI_PASSWORD
• OTTA_CLI_ACCESS_TOKEN
• OTTA_CLI_TOKEN_TYPE
• OTTA_CLI_REFRESH_TOKEN
• OTTA_CLI_TOKEN_SCOPE
• OTTA_CLI_USER_ID
• OTTA_CLI_WORKTIMEGROUP_ID

代理运行规范

1. 所有产生数据的命令均应优先使用 --format json，并解析响应字段，而非依赖文本输出进行正则匹配或字符串提取。
2. worktimes list/browse/report 命令仅返回工时记录，**绝不包含请假信息**；不可将空的工时行推断为请假。
3. 如需检查用户排班或解读日志，应优先使用 calendar detailed --format json；仅在性能敏感场景下，才将 calendar overview 作为轻量级备选。
4. 当用户明确要求非分钟单位的输出时，使用 --duration-format；审计用途应始终保留原始分钟值。
5. 在执行依赖缓存用户或 worktimegroup 元数据的操作前，应先运行 status --format json 确保缓存最新。
6. 执行命令前须校验日期/时间格式是否符合 YYYY-MM-DD 与 HH:MM 要求。
7. 当工时 ID 不明确时，应在执行 update 或 delete 前，先运行 worktimes list 查询 ID。
8. 发生错误时，须返回**精确的失败命令、退出码及简洁的 stderr 错误消息**。
9. 摘要或日志中**严禁打印原始凭据或令牌**。

故障恢复

• no access token configured (run otta auth login`)`
  • 运行 auth login 完成登录，随后重新执行 status。
• username is required (use --username)
  • 显式传入 --username 参数，或设置环境变量 OTTA_CLI_USERNAME。
• --worktimegroup is required (...)
  • 显式传入 --worktimegroup 参数，或设置环境变量 OTTA_CLI_WORKTIMEGROUP_ID，或运行 status 刷新缓存。
• --date must be YYYY-MM-DD、--start must be HH:MM、--to must be greater than or equal to --from
  • 修正输入格式或参数顺序后重试命令。
• directory ... is contained in a module that is not one of the workspace modules listed in go.work
  • 在此仓库上下文中，使用 GOWORK=off 进行构建或运行。