kimai-time-tracking

核心用法

Kimai Time Tracking Skill 提供了 Kimai 开源时间追踪软件的完整 REST API 封装，通过 kimai_cli.py 命令行工具实现全功能操作。核心工作流包括三大场景：快速计时（启动/停止/重启计时器）、数据管理（客户-项目-活动层级创建与维护）、以及导出开票（标记导出状态、生成发票）。用户可通过环境变量配置 KIMAI_BASE_URL 和 KIMAI_API_TOKEN 完成认证，支持 JSON、表格、CSV 三种输出格式，所有列表操作自动处理分页。

显著优点

1. 功能完整性：覆盖 Kimai 全部核心实体（timesheets/customers/projects/activities/teams/invoices/users），支持从个人计时到团队权限管理的全场景。
2. 安全设计：删除操作强制确认并展示级联影响，API Token 通过 Bearer 头部传输且不记录，文件导出权限限制为 600。
3. 零依赖：仅使用 Python 标准库，无第三方包引入，部署简单且规避供应链风险。
4. 工作流友好：recent 命令快速复用最近工作组合，，duplicate 支持条目复制，，--dry-run 便于测试验证。
5. 来源可信：来自 openclaw 组织（2,353 Stars），代码规范且文档详尽。

潜在缺点与局限性

• 网络依赖：必须连接 Kimai 服务器，无法离线使用。
• 学习成本：需理解 Kimai 的实体关系（客户→项目→活动层级）才能高效使用。
• 权限配置复杂：不同操作需申请不同 API 权限，管理员需仔细规划角色。
• 自动化风险：--force 参数可跳过删除确认，误用可能导致数据丢失。
• 无内置缓存：每次查询均实时请求 API，高频操作可能影响性能。

适合的目标群体

• 使用 Kimai 进行工时管理的开发团队、咨询公司、自由职业者
• 需要自动化工时报表和发票生成的财务/运营人员
• 希望将时间追踪集成到 CI/CD 或内部工具链的技术团队
• 多项目管理场景下的团队负责人和项目经理

使用风险

• 数据级联删除：删除客户会级联删除其下所有项目、活动和工时记录，确认提示需仔细阅读。
• Token 泄露风险：API Token 权限较大，环境变量配置不当可能导致未授权访问。
• 服务器信任：所有数据发送至配置的 Kimai 服务器，需确保 BASE_URL 指向可信实例。
• 并发冲突：若 Kimai 配置禁止重叠工时，同时启动多个计时器会返回 409 冲突错误。

Kimai 时间追踪技能综合评估

此技能为开源自托管时间追踪软件 Kimai 提供了完整的 API 集成方案。它通过一个简洁的命令行工具（CLI），让 Agent 或开发者能够直接在终端管理时间条目、客户、项目、活动、团队、发票及系统配置，彻底实现了工时管理的全自动化。

核心用法

技能的核心是 kimai_cli.py 脚本，它严格遵循 Kimai 的 REST API 结构进行设计。用户可以轻松执行“启动/停止计时”、“列出并筛选时间表”、“管理客户-项目-活动的层级关系”、“创建团队并分配权限”、“导出非计费工时”以及“查询系统状态（版本、插件等）”等操作。所有数据交互均指向用户自配置的 Kimai 实例，确保了数据的完全自主可控。

显著优点

1. 极致的代码安全与纯净：这是本技能最突出的优势。安全审查报告给予了 S 级最高评价，显示其零第三方依赖，仅使用 Python 标准库，彻底消除了供应链攻击和 CVE 风险。
2. 严谨的破坏性操作保护：所有删除操作（如删除客户、项目）都内置了交互式确认机制（confirm_deletion()），并会展示受影响的数据预览，从根本上防止了误操作导致的数据灾难。
3. 安全的凭证管理：API Token 通过环境变量注入，在代码中没有硬编码，不会被记录到日志或输出中，遵循了最佳安全实践。
4. 高可用性的数据输出：支持 JSON（机器友好）、Table（人类可读）和 CSV（便于导出）三种输出格式，并通过退出码明示操作状态，易于集成到自动化流水线中。

潜在缺点或局限性

1. 强依赖 Kimai 平台：此技能仅是 Kimai 的交互客户端，所有功能都建立在拥有一个正常运行的 Kimai 2.x 实例之上，不具备独立工作能力。
2. 无内置强制 HTTPS：代码本身不校验传输协议，安全性完全依赖于用户在 KIMAI_BASE_URL 中配置的 HTTPS 前缀。若配置为 HTTP，API Token 存在明文传输的风险。
3. 功能受限于 API 权限：技能的实际可用功能范围，严格取决于你在 Kimai 中为 API Token 所分配的权限。若权限不足，很多操作将无法执行。

适合的目标群体

该技能是以下用户的理想选择：

• 自由职业者与咨询顾问：需要精确追踪不同项目和客户工时，以便准确计费。
• 小型开发与创意团队：希望拥有一套自托管、低成本且能深度集成到自动化脚本中的时间管理方案。
• 注重数据隐私的极客与开发者：不愿将敏感的项目和工时数据存储在第三方云服务上，偏好自我托管（self-hosted）。
• AI Agent 爱好者：希望为自己的 AI 助手配备直接操控 Kimai 工具能力的用户。

使用风险提示

尽管代码本身高度安全，使用时仍需注意：

• 配置风险：最核心的风险在于 KIMAI_BASE_URL 和 KIMAI_API_TOKEN 的配置。务必使用 HTTPS 地址，并为 Token 精确授予最小必要权限，避免赋予过高的 admin 权限。
• 数据丢失风险：尽管有确认机制，但用户若在确认删除时草率同意，仍会导致客户、项目及其关联时间表的级联删除，后果严重。
• 环境依赖：该技能目前明确支持 Linux/macOS 环境，Windows 用户可能需要适配操作。同时要求 Python 3 环境，但这通常是标准配置。
• 平台版本兼容性：严格依赖 Kimai 2.x 版本的 REST API，未来若 Kimai 发布重大更新，此技能可能需要跟进适配。

总而言之，Kimai 时间追踪技能是一个设计精良、安全至上、完全开源的效率工具。它完美地桥接了 AI Agent 与自托管 Kimai 实例，在提供强大自动化能力的同时，没有牺牲代码的简洁性和安全性，是该领域内一个值得信赖的顶级选择。