⚡

Kimai时间追踪技能 kimai-time-tracking

这是一个完整的Kimai时间追踪软件API集成技能，提供对工时表、项目、客户、活动、团队、发票和系统配置的全面控制。支持时间追踪工作流、数据报告和管理操作，适用于团队协作、项目管理、工时统计和发票生成等场景。关键词：Kimai时间追踪、工时管理、项目管理、API集成、时间记录、团队协作、发票导出、工时统计

其他 0 次安装 0 次浏览 更新于 2/24/2026

名称: kimai时间追踪 描述: 完整的Kimai时间追踪API集成。通过REST API管理工时表、客户、项目、活动、团队、发票和导出。支持时间追踪工作流、报告和管理操作。关键词 - kimai, 时间记录, 工时表, 追踪, 项目, 客户, 活动, 发票, 导出, 计时器, 小时

Kimai时间追踪技能

完整的Kimai时间追踪软件API集成。可完全控制工时表、项目、客户、活动、团队、发票和系统配置。

使用场景

当用户请求以下内容时激活此技能:

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

激活触发词:

  • 关键词: “kimai”, “时间记录”, “工时表”, “计时器”, “小时”, “记录时间”, “开始追踪”, “创建项目”, “创建发票”
  • “为项目X开始追踪”
  • “显示我上周的工时表”
  • “在Kimai中创建新客户”
  • “将工时表导出为CSV”
  • “列出所有活动计时器”
  • “停止当前时间追踪”

不要为以下情况激活:

  • 一般时间问题（“现在几点？”）
  • 其他时间追踪工具（Toggl、Clockify等）
  • 没有Kimai上下文的日历/日程安排

环境设置

必需的环境变量:

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

可选:

  • 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（用于用户管理）

兼容性: 需要Kimai 2.x且启用REST API。需要互联网访问。支持Linux/macOS。

工作流程

1. 快速时间追踪

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

# 开始追踪
./scripts/kimai_cli.py timesheets start --project 1 --activity 5 --description "实施API"

# 检查活动计时器
./scripts/kimai_cli.py timesheets active

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

2. 数据管理工作流程

# 创建客户 → 项目 → 活动层级
./scripts/kimai_cli.py customers create --name "Acme公司" --country DE --currency EUR --timezone Europe/Berlin
./scripts/kimai_cli.py projects create --name "网站重设计" --customer 1
./scripts/kimai_cli.py activities create --name "开发" --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进行所有操作。结构遵循API端点:

工时表 (timesheets)

  • list - 列出条目（支持分页，筛选条件：用户、客户、项目、活动、标签、日期范围、导出状态）
  • get <id> - 获取单个条目
  • create - 创建手动条目或启动计时器（省略–end以进行活动追踪）
  • update <id> - 更新现有条目
  • delete <id> - 需要确认（破坏性）
  • stop <id> - 停止活动计时器
  • restart <id> - 重启已完成条目（创建新条目）
  • duplicate <id> - 复制条目（重置导出状态）
  • active - 列出当前运行的计时器
  • recent - 最近的唯一工作集（每个项目/活动组合的最后活动）
  • export <id> - 切换导出/锁定状态

客户 (customers)

  • list - 列出客户（筛选：可见性、搜索词）
  • get <id> - 获取客户详情
  • create - 创建新客户
  • update <id> - 更新客户
  • delete <id> - 需要确认（级联到项目/活动/工时表）
  • meta <id> - 更新自定义字段
  • rates <id> - 管理客户特定费率

项目 (projects)

  • list - 列出项目（筛选：客户、可见性、日期范围）
  • get <id> - 获取项目
  • create - 创建项目（需要客户ID）
  • update <id> - 更新项目
  • delete <id> - 需要确认（级联到活动/工时表）
  • rates <id> - 管理项目费率

活动 (activities)

  • list - 列出活动（筛选：项目、可见性、仅全局）
  • get <id> - 获取活动
  • create - 创建活动（可以是全局或项目特定）
  • update <id> - 更新活动
  • delete <id> - 需要确认（级联到工时表）
  • rates <id> - 管理活动费率

团队 (teams)

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

用户 (users)

  • list - 列出用户（需要view_user权限）
  • me - 当前用户信息
  • get <id> - 用户详情
  • create - 创建用户（管理员）
  • update <id> - 更新用户

发票 (invoices)

  • list - 列出发票（筛选：日期范围、客户、状态）
  • get <id> - 发票详情

系统 (system)

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

安全与边界

⚠️ 破坏性操作

  • 对客户、项目、活动、工时表、团队或标签的delete操作需要明确的用户确认。
  • 删除客户会级联到所有关联的项目、活动和工时表[1]。
  • 删除项目会级联到活动和工时表[1]。
  • CLI将显示受影响数据的预览并要求"yes"确认。

API安全:

  • API令牌通过Authorization: Bearer标头传递[1]。
  • 令牌永远不会记录或存储在CLI输出中。
  • 使用--dry-run标志进行测试（模拟API调用而不执行）。

速率限制与分页:

  • API返回分页结果（默认50个项目）[1]。
  • CLI自动处理list命令的分页（获取所有页面或遵守--limit）。
  • 使用--page和--size进行手动分页控制。

数据隐私:

  • 工时表数据可能包含敏感信息。
  • 导出文件保存到具有受限权限（600）的工作区。
  • 共享调试输出时删除个人数据（电子邮件、姓名）。

工作区安全:

  • 所有文件导出（CSV、JSON）默认到KIMAI_WORKSPACE或~/.openclaw/workspace/kimai。
  • 未经明确确认，切勿写入工作区外的系统目录。

输入/输出规范

输入:

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

输出:

  • JSON（默认，管道友好）
  • 表格格式（--format table用于人类可读性）
  • CSV（--format csv用于导出）
  • 退出代码：0（成功），1（API错误），2（验证错误），3（用户取消）

成功标准:

  • HTTP 200/201表示操作成功
  • 符合API模式[1]的有效JSON响应结构
  • 对于导出：在工作区中创建文件并具有预期的记录数

示例

带描述开始追踪

./scripts/kimai_cli.py timesheets create \
  --project 5 \
  --activity 12 \
  --description "客户会议 - 需求分析" \
  --tags "会议,紧急"

列出并导出未导出的小时数

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

更新自定义字段（元数据）

./scripts/kimai_cli.py customers meta 42 \
  --name "订单号" \
  --value "PO-2024-001"

创建团队并分配资源

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

错误处理

常见HTTP代码:

  • 200 - 成功
  • 201 - 已创建
  • 204 - 无内容（成功删除）
  • 400 - 错误请求（验证错误、缺少字段）
  • 401 - 未授权（无效/过期令牌）
  • 403 - 禁止（权限不足）
  • 404 - 未找到（无效ID）
  • 409 - 冲突（如果配置不允许，工时表重叠）

CLI行为:

  • 在API调用前验证必填字段（例如，工时表的项目+活动[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

参考