简体中文 | 繁體中文 | English

🦞 TimeForge-CLI

轻量级终端开发者时间锻造引擎
Git-Aware · AI周报 · 纯文本存储 · 零依赖

---

🎉 项目介绍

TimeForge-CLI 是一款专为开发者打造的轻量级终端时间追踪工具。灵感来源于开发者日常工作中对时间管理的痛点——现有工具要么过于笨重、要么依赖云服务、要么无法与开发工作流深度整合。

TimeForge-CLI 采用纯文本存储理念，数据即文件，可以 Git 管理、grep 搜索，确保数据完全自主可控。独创 Git-Aware 自动关联机制，能将时间记录与 Git 提交智能关联，让每一分钟的工作都有迹可循。

🔥 自研差异化亮点

• 🔗 Git-Aware 自动追踪 — 自动检测 Git 仓库，将时间记录与 Git 提交智能关联
• 🤖 AI 智能周报 — 基于时间数据 + Git 提交自动生成工作周报
• 📝 纯文本存储 — 数据即文件，零数据库依赖，完全自主可控
• 📊 多维度报表 — 支持日/周/月报表，项目级统计分析
• 💸 计费集成 — 内置时薪计算，自动统计收入
• 📦 零外部依赖 — 纯 Python 实现，无需安装任何第三方库

---

✨ 核心特性

特性	描述
⏱️ 时间追踪	一键启动/停止计时器，支持多项目并行追踪
🔗 Git-Aware	自动检测 Git 仓库信息，关联时间记录与代码提交
📊 智能报表	按日/周/月生成详细时间报表，支持项目级汇总
🤖 AI 周报	自动生成包含工作模式分析的开发周报
📁 项目管理	多项目追踪，自动统计各项目投入时间
💰 收入计算	设置时薪后自动计算每段工作的收入
📤 多格式导出	支持 JSON/CSV/Markdown 三种格式导出
⚙️ 灵活配置	可配置时间精度、默认项目、自动 Git 检测等
🚀 零依赖	纯 Python 实现，无需安装任何第三方库
💻 跨平台	支持 Windows、macOS、Linux

---

🚀 快速开始

环境要求

• Python 3.7+（无需任何第三方依赖）
• Git（可选，用于 Git-Aware 功能）
• 操作系统：Windows / macOS / Linux

安装

# 克隆仓库
git clone https://github.com/your-username/TimeForge-CLI.git
cd TimeForge-CLI

# 直接运行（无需安装）
python3 timeforge.py help

一键运行

# 启动时间追踪
python3 timeforge.py start myproject "开发认证模块"

# 查看当前计时器状态
python3 timeforge.py status

# 停止计时器
python3 timeforge.py stop

# 查看今日时间记录
python3 timeforge.py list

# 生成本周报表
python3 timeforge.py report week

# 生成 AI 智能周报
python3 timeforge.py ai-report

---

📖 详细使用指南

基础命令

# 启动计时器（自动检测 Git 仓库）
timeforge start myproject "实现用户登录功能"

# 启动计时器（跳过 Git 检测）
timeforge start myproject "编写测试用例" --no-git

# 停止所有计时器
timeforge stop

# 停止指定项目的计时器
timeforge stop myproject

# 查看活跃计时器
timeforge status

报表与统计

# 今日报表
timeforge report today

# 本周报表
timeforge report week

# 本月报表
timeforge report month

# 指定日期的日志
timeforge log 2025-06-08

# 项目总览
timeforge projects

# 全局统计摘要
timeforge summary

Git-Aware 功能

# 查看与时间记录关联的 Git 提交
timeforge git-log

# 生成 AI 智能周报（整合时间数据 + Git 提交）
timeforge ai-report

数据导出

# 导出为 JSON
timeforge export json

# 导出为 CSV
timeforge export csv

# 导出为 Markdown
timeforge export markdown

配置管理

# 查看所有配置
timeforge config

# 设置时薪（用于收入计算）
timeforge config hourly_rate 200

# 设置时间精度（向上取整到15分钟）
timeforge config round_minutes 15

# 关闭自动 Git 检测
timeforge config auto_git false

---

💡 设计思路与迭代规划

设计理念

TimeForge-CLI 的核心设计哲学是 "数据自主，工作流融合"：

1. 纯文本优先 — 不依赖任何数据库，所有数据以 JSON 格式存储在 ~/.timeforge/ 目录下，可以 Git 管理、grep 搜索、随时迁移
2. Git-Native — 作为开发者工具，与 Git 深度整合是核心优势。自动检测仓库、关联提交、生成代码变更报告
3. 零依赖 — 纯 Python 标准库实现，确保在任何环境下都能运行，无需担心依赖冲突

技术选型

选型	原因
Python	最广泛使用的编程语言之一，开发者友好，标准库丰富
JSON 存储	人类可读、可编辑、可版本控制
CLI 交互	开发者最自然的工作环境，无需切换窗口
subprocess	利用系统 Git 命令，避免引入 Git 库依赖

后续迭代计划

• 🎨 TUI 交互界面（日历视图、时间线可视化）
• 🌐 Web 仪表盘（可选的 Web UI 展示）
• 📊 Pomodoro 番茄钟模式
• 🔔 智能提醒（久坐提醒、休息提醒）
• 📱 数据同步（多设备间同步）
• 🧩 插件系统（自定义报表、通知器）
• 🌍 多语言 CLI 界面

---

📦 打包与部署指南

作为脚本使用

# 直接运行
python3 timeforge.py <command>

作为 Python 包安装

# 安装到系统
pip install .

# 安装后可直接使用
timeforge <command>

兼容环境

环境	最低版本	状态
Python	3.7+	✅ 完全兼容
Windows	10+	✅ 完全兼容
macOS	10.15+	✅ 完全兼容
Linux	所有主流发行版	✅ 完全兼容

---

🤝 贡献指南

欢迎贡献代码、报告 Bug 或提出新功能建议！

提交规范

请遵循 Angular 提交规范：

feat: 新增功能
fix: 修复问题
docs: 文档更新
refactor: 代码重构
test: 测试相关
chore: 构建/工具链相关

反馈渠道

• 📧 提交 GitHub Issue
• 🔀 提交 Pull Request

---

📄 开源协议

本项目基于 MIT License 开源。

---

Made with 🦞 by TimeForge Team
_{Powered by GLM-5.1}