Work Timer

工作计时器

当前版本：1.3.32

为独立承包商和自由职业者打造的零成本开源工作计时器和计费工具。通过任何兼容MCP的AI助手（Claude、Cursor等）或命令行用自然语言控制它。

特性

• 自然语言控制 --“为Project Alpha启动计时器”，“本月在Client X上有多少时间？”
• MCP服务器 --适用于Claude Desktop、ChatGPT、GitHub Copilot、Cursor和任何兼容MCP的客户端
• 扩展CLI集成 --自动安装程序支持基于Claude Code、OpenAI Codex CLI和Google Gemini CLI命令的MCP注册
• 内置MCP帮助 — work_timer_help 解释LLM/用户的功能、工作流程和示例用法
• MCP自动安装程序 --通过编程检测并修补支持备份+模拟运行的本地MCP客户端配置
• 命令行界面 --完整的命令行界面，便于快速手动使用
• 内置维护 --包括 work-timer update, work-timer uninstall，并更新可用提示
• 安全破坏性操作 --CLI中的确认流程 dry_run + confirm_phrase MCP中用于破坏性行为的安全门
• 会话时间校正 --在安全存储UTC的同时，调整本地时间的开始/结束时间
• 当地时间UX --显示器和日期过滤器是本地时间感知的，而数据库存储保持UTC
• 重叠计时器 --同时向多个客户开具账单
• 灵活计费 --具有全局默认值的每个项目的费率、货币和最低计费块
• 发票跟踪 --将会话标记为已开票和已付款，并使用参考号
• 出口 --CSV、Excel（XLSX）和会计专用预设（QuickBooks、Xero、FreshBooks、Sage、MYOB）
• 现代XLSX出口 --Excel导出使用较小的维护写入器依赖项，而不是旧的 exceljs 堆栈
• 云同步 --Turso数据库意味着您的数据可以从任何设备访问
• 自由 --Turso免费版（9GB，500M读/月）对于任何单人练习来说都绰绰有余

快速开始

1.安装

Windows PowerShell（一行）：

irm https://raw.githubusercontent.com/JoelBondoux/Work-Timer/master/install.ps1 | iex

macOS/Linux（一行）：

curl -fsSL https://raw.githubusercontent.com/JoelBondoux/Work-Timer/master/install.sh | bash

这些脚本会自动检测您的本地 Work-Timer 文件夹已存在，然后克隆或更新、安装依赖项、构建并运行 npm link.

对于生产钉扎，请更换 master 在带有发布标签的URL中，例如 v1.3.32.

更快的分支测试选项：

• 跳过构建：设置 WORK_TIMER_SKIP_BUILD=1
• 跳过全局重新链接：set WORK_TIMER_SKIP_LINK=1
• 现有有效 ~/Work-Timer 安装已就地更新
• 如果目标文件夹存在但不是工作计时器安装，则将其移动到带时间戳的备份中，并在请求的文件夹中继续安装
• 如果现有的工作计时器安装有未提交的更改，默认情况下安装程序会停止；生成的 dist/-只有更改会被忽略，您仍然可以设置 WORK_TIMER_ALLOW_DIRTY=1 当你有意要继续时
• 脏状态错误包括活动分支和阻止文件的预览，以加快清理速度
• 仅在中生成跟踪文件时 dist/ 已更改，安装程序现在重置 dist/ 在pull之前，以避免更新过程中的快速冲突
• 如果安装的版本已经与请求的版本匹配，安装程序会询问是否 repair （重新安装deps/重建/重新链接）或 cancel
• 在非交互式环境中，设置 WORK_TIMER_REPAIR_MODE=repair 强制维修，或 WORK_TIMER_REPAIR_MODE=cancel 跳过

Windows用户： npm link 可能需要将npm的全局bin添加到PATH中并设置PowerShell的执行策略。请参阅 安装指南 了解详情。

2.设置数据库

创建免费 图尔索 帐户并设置数据库：

通过web仪表板（推荐用于Windows）： 首选 附件逗留。，创建数据库，并从数据库设置中复制数据库URL和身份验证令牌。

通过命令行界面（macOS/Linux）：

curl -sSfL https://get.tur.so/install.sh | bash
turso auth login
turso db create work-timer
turso db show work-timer --url       # Copy this
turso db tokens create work-timer    # Copy this

运行安装向导：

work-timer setup

让工作计时器和MCP服务器在GitHub上保持最新：

work-timer update

如果需要手动引导损坏的旧安装，请使用与相同的tarball安装路径 work-timer update：（这也有助于 npm PATH解析在较旧的全局安装中不一致）

npm install -g https://codeload.github.com/JoelBondoux/Work-Timer/tar.gz/refs/heads/master

可选：在检测到的本地MCP客户端中自动注册工作定时器：

work-timer mcp install --dry-run
work-timer mcp install --create-missing

或设置环境变量：

export TURSO_DATABASE_URL="libsql://your-db-url.turso.io"
export TURSO_AUTH_TOKEN="your-token"

3.开始跟踪

通过CLI：

work-timer start "Client Alpha"
# ... work for a while ...
work-timer stop
work-timer query "Client Alpha"

通过人工智能助手（MCP）：

添加到您的MCP客户端配置（Claude Desktop、ChatGPT、GitHub Copilot、Cursor——请参阅 安装指南 每个）：

{
  "mcpServers": {
    "work-timer": {
      "command": "node",
      "args": ["/path/to/Work-Timer/dist/mcp/server.js"]
    }
  }
}

那就自然地说吧：

“为网站重新设计项目启动计时器” “暂停计时器” “本周我花了多少时间重新设计网站？” “将我1月份的账单导出为Excel” “工作计时器是如何工作的？”

文档

运作原理

工作计时器将所有数据存储在 图尔索 云数据库（一种托管的SQLite兼容服务）。这意味着：

• 您的时间数据会自动在所有设备上同步
• 无需运行或维护服务器
• 免费套餐对任何独立承包商来说都足够慷慨
• 为了保持一致性，所有时间戳都以UTC存储

MCP服务器和CLI都使用相同的核心逻辑，因此无论您如何与工作计时器交互，行为都是相同的。

建筑

src/
  types.ts          # Shared TypeScript interfaces
  db/
    schema.ts       # Database schema and migrations
    client.ts       # Turso client management
  core/
    timer.ts        # Start/stop/pause/resume logic
    projects.ts     # Project CRUD operations
    billing.ts      # Duration and billing calculations
    settings.ts     # Global default settings
    sessions.ts     # Session queries and invoice marking
    export.ts       # CSV, XLSX, and accounting preset export
    presets.ts      # Accounting software export presets
    format.ts       # Text formatting for output
  mcp/
    server.ts       # MCP server with 21 tool definitions
  cli/
    index.ts        # CLI entry point with Commander.js

许可证

麻省理工学院