Kimai 时间追踪技能

为 Kimai 时间追踪软件提供完整的 API 集成，支持对工时表（timesheets）、项目（projects）、客户（customers）、活动（activities）、团队（teams）、发票（invoices）及系统配置的全面管理。

适用场景

当用户提出以下请求时，请启用该技能：

• 启动/停止/重启时间追踪（计时器）
• 列出、筛选或导出工时表
• 管理客户、项目或活动
• 创建发票或导出数据
• 执行管理任务（用户、团队、费率等）
• 查询系统状态（版本、插件、配置）

触发启用的关键词或语句：

• 关键词："kimai"、"zeiterfassung"、"timesheet"、"timer"、"stunden"、"erfasse Zeit"、"starte Tracking"、"Projekt anlegen"、"Rechnung erstellen"
• "为项目 X 启动追踪"
• "显示我上周的工时表"
• "在 Kimai 中创建新客户"
• "将工时表导出为 CSV"
• "列出所有正在运行的计时器"
• "停止当前时间追踪"

请勿启用该技能的情形：

• 通用时间问题（例如：“现在几点？”）
• 其他时间追踪工具（如 Toggl、Clockify 等）
• 无 Kimai 上下文的日历/日程安排类请求

环境配置

必需的环境变量：

• KIMAI_BASE_URL — Kimai 实例的完整 URL（例如：https://kimai.example.com）
• KIMAI_API_TOKEN — 用于身份验证的 Bearer Token

可选环境变量：

• KIMAI_WORKSPACE — 导出文件/临时文件路径（默认为 ~/.openclaw/workspace/kimai）

所需 API 权限取决于具体操作：

• view_own_timesheet、create_own_timesheet、edit_own_timesheet、delete_own_timesheet
• view_other_timesheet（用于查看其他用户的工时条目）
• view_customer、edit_customer、delete_customer
• view_project、edit_project、delete_project
• view_activity、edit_activity、delete_activity
• view_team、edit_team、create_team、delete_team
• view_invoice（用于发票相关操作）
• view_user（用于用户管理）

兼容性说明：需使用启用了 REST API 的 Kimai 2.x 版本；需具备互联网访问能力；支持 Linux/macOS 系统。

工作流

1. 快速时间追踪

# 列出最近的活动（用于查找项目/活动 ID）
./scripts/kimai_cli.py timesheets recent

# 启动追踪
./scripts/kimai_cli.py timesheets start --project 1 --activity 5 --description "Implementing API"

# 查看当前运行中的计时器
./scripts/kimai_cli.py timesheets active

# 停止追踪
./scripts/kimai_cli.py timesheets stop --id 123

2. 数据管理流程

# 构建客户 → 项目 → 活动层级结构
./scripts/kimai_cli.py customers create --name "Acme Corp" --country DE --currency EUR --timezone Europe/Berlin
./scripts/kimai_cli.py projects create --name "Website Redesign" --customer 1
./scripts/kimai_cli.py activities create --name "Development" --project 1

# 使用筛选条件列出数据
./scripts/kimai_cli.py timesheets list --customer 1 --begin "2024-01-01T00:00:00" --exported 0

3. 导出/发票流程

# 将工时表标记为已导出（锁定该条目）
./scripts/kimai_cli.py timesheets export --id 123

# 列出待处理发票
./scripts/kimai_cli.py invoices list --status pending --begin 2024-01-01T00:00:00

CLI 工具参考

所有操作均通过 scripts/kimai_cli.py 执行，命令结构与 Kimai API 端点保持一致：

工时表（timesheets）

• list — 列出条目（支持分页；筛选参数包括：用户、客户、项目、活动、标签、日期范围、是否已导出）
• get — 获取单个条目
• create — 创建手动条目或启动计时器（若不指定 --end 参数，则视为持续追踪）
• update — 更新现有条目
• delete — 需显式确认（破坏性操作）
• stop — 停止正在运行的计时器
• restart — 重启已完成的条目（生成新条目）
• duplicate — 复制条目（重置导出状态）
• active — 列出当前正在运行的计时器
• recent — 最近唯一的工作集（每个“项目+活动”组合仅保留最后一次记录）
• export — 切换导出/锁定状态

客户（customers）

• list — 列出客户（支持筛选：可见性、搜索关键词）
• get — 获取客户详情
• create — 创建新客户
• update — 更新客户信息
• delete — 需显式确认（级联删除关联的项目/活动/工时表）
• meta — 更新自定义字段
• rates — 管理客户专属费率

项目（projects）

• list — 列出项目（支持筛选：客户、可见性、日期范围）
• get — 获取项目详情
• create — 创建项目（需指定客户 ID）
• update — 更新项目
• delete — 需显式确认（级联删除关联的活动/工时表）
• rates — 管理项目费率

活动（activities）

• list — 列出活动（支持筛选：所属项目、可见性、是否全局）
• get — 获取活动详情
• create — 创建活动（可设为全局或项目专属）
• update — 更新活动
• delete — 需显式确认（级联删除关联的工时表）
• rates — 管理活动费率

团队（teams）

• list、get、create、update、delete
• member-add — 添加团队成员
• member-remove — 移除团队成员
• grant-customer — 授予客户访问权限
• grant-project — 授予项目访问权限
• grant-activity — 授予活动访问权限

用户（users）

• list — 列出用户（需具备 view_user 权限）
• me — 当前用户信息
• get — 获取指定用户详情
• create — 创建用户（管理员权限）
• update — 更新用户信息

发票（invoices）

• list — 列出发票（支持筛选：日期范围、客户、状态）
• get — 获取发票详情

系统（system）

• ping — 测试连接性
• version — Kimai 版本信息
• plugins — 已安装插件列表
• config — 工时表配置
• colors — 颜色代码

安全与边界限制

⚠️ 破坏性操作警告

• 对客户、项目、活动、工时表、团队或标签执行的 delete 操作必须获得用户明确确认。
• 删除客户将级联删除其所有关联的项目、活动和工时表 [1]。
• 删除项目将级联删除其所有关联的活动和工时表 [1]。
• CLI 将显示受影响数据的预览，并要求输入 “yes” 以完成确认。

API 安全机制：

• API Token 通过 Authorization: Bearer 请求头传递 [1]。
• Token 不会在 CLI 输出中被记录或存储。
• 使用 --dry-run 标志进行测试（模拟 API 调用但不实际执行）。

速率限制与分页：

• API 默认返回分页结果（每页 50 条）[1]。
• CLI 对 list 类命令自动处理分页（默认获取全部页面，或按 --limit 参数限制数量）。
• 可通过 --page 和 --size 手动控制分页行为。

数据隐私保护：

• 工时表数据可能包含敏感信息。
• 导出文件保存至 workspace 目录，且权限被严格限制（600）。
• 在共享调试输出时，请脱敏处理个人数据（如邮箱、姓名等）。

工作区安全性：

• 所有文件导出（CSV、JSON）默认保存至 KIMAI_WORKSPACE 或 ~/.openclaw/workspace/kimai。
• 未经显式确认，禁止向 workspace 外的系统目录写入任何文件。

输入/输出规范

输入类型：

• 实体 ID（整型）
• ISO 8601 格式时间字符串（YYYY-MM-DDTHH:mm:ss）
• 用于创建/更新操作的 JSON 数据（可通过 --json 文件或命令行参数传入）
• 筛选参数（客户/项目/活动 ID、日期范围、可见性等）

输出格式：

• JSON（默认格式，适合管道处理）
• 表格格式（使用 --format table 提升可读性）
• CSV（使用 --format csv 进行导出）
• 退出码：0（成功）、1（API 错误）、2（校验错误）、3（用户取消）

成功判定标准：

• HTTP 状态码为 200 或 201 表示操作成功
• 返回 JSON 结构符合 API Schema 规范 [1]
• 对于导出操作：预期数量的文件已成功创建于 workspace 中

示例

带描述启动追踪

./scripts/kimai_cli.py timesheets create 
  --project 5 
  --activity 12 
  --description "Client meeting - requirements analysis" 
  --tags "meeting,urgent"

列出并导出未导出的工时

# 查询尚未导出的可计费工时
./scripts/kimai_cli.py timesheets list 
  --exported 0 
  --billable 1 
  --begin "2024-01-01T00:00:00" 
  --end "2024-01-31T23:59:59" 
  --format csv > january_hours.csv

更新自定义字段（meta）

./scripts/kimai_cli.py customers meta 42 
  --name "order_number" 
  --value "PO-2024-001"

创建团队并分配资源

./scripts/kimai_cli.py teams create --name "Development Team" --members '[{"user": 1, "teamlead": true}]'
./scripts/kimai_cli.py teams grant-project 1 5

错误处理

常见 HTTP 状态码：

• 200 — 成功
• 201 — 已创建
• 204 — 无内容（删除成功）
• 400 — 错误请求（校验失败、字段缺失）
• 401 — 未授权（Token 无效或已过期）
• 403 — 禁止访问（权限不足）
• 404 — 未找到（ID 无效）
• 409 — 冲突（配置不允许存在时间重叠的工时表）

CLI 行为规范：

• 在调用 API 前校验必填字段（例如工时表操作需同时提供 project 和 activity [1]）
• 美化输出 API 返回的校验错误信息
• 提供修复建议（例如：“您是否想使用 PATCH 替代 DELETE？可尝试设置 visible=false 来隐藏而非删除”）

校验

使用 Openclaw 技能校验器验证该技能：

skills-ref validate ./kimai-time-tracking

测试 API 连通性：

export KIMAI_BASE_URL="https://your-kimai.example.com"
export KIMAI_API_TOKEN="your-api-token"
./kimai-time-tracking/scripts/kimai_cli.py system ping

参考资料

• Kimai REST API 文档：https://www.kimai.org/documentation/rest-api.html
• 分页指南：https://www.kimai.org/documentation/api-pagination.html
• API 规范：references/api-reference.json（完整的 OpenAPI Schema）