WakaTime 统计需同时满足三条件：本地安装 wakatime-cli 并加入 PATH、配置文件 ~/.wakatime.cfg 存在且权限为 600、内容含严格格式的 [settings] 和 api_key；项目名依赖最近 .git 目录名或 .wakatime-project 文件；统计验证应查日志或手动调用 CLI；周报按 UTC 时间窗聚合，非本地生成。
WakaTime 插件装上不等于开始统计，它必须依赖本地 wakatime-cli、正确格式的 ~/.wakatime.cfg 和明确的项目标识三者同时就位，缺一不可。
为什么状态栏一直显示 “Connecting…” 或 “Idle”
这不是插件卡住，是 wakatime-cli 根本没被调用。VSCode 插件只负责触发事件，所有解析、认证、上报都由 CLI 完成。
- 终端运行
wakatime-cli --version，报command not found→ CLI 没装进PATH；macOS/Linux 常因代理中断自动安装脚本，Windows 常因 PowerShell 权限失败 - CLI 装了但插件仍 idle → 检查
~/.wakatime.cfg是否存在、权限是否为600（macOS/Linux）、内容是否严格包含[settings]和api_key = xxxxx两行（不能多空格、不能中文等号、不能带 BOM） - 改完配置或装完 CLI 后只执行
Developer: Reload Window→ 必须彻底退出 VSCode（包括菜单栏残留进程），再重新打开，它只在启动时读一次配置
项目名总显示 “Unknown Project” 怎么办
WakaTime 不看 VSCode 工作区名、不看文件夹名、也不认 .code-workspace 文件——它只依赖两个来源：离当前文件最近的 .git 目录名，或项目根目录下的 .wakatime-project 文件。
-
/monorepo/packages/frontend，但.git在/monorepo→ 它取名monorepo，不是frontend - 你并排打开
auth-service和payment-service两个独立目录，但都没初始化 Git → 全部 fallback 到Unknown Project - 最稳解法：在每个实际想区分的目录下（如
auth-service/）手动建一个纯文本文件.wakatime-project，内容就一行，比如auth-service-go
怎么确认某次编辑真被统计了
别只盯着状态栏时钟，直接查日志和 CLI 手动验证更可靠。
- VSCode 输出面板（
Ctrl+Shift+U）切换到WakaTime日志，搜索Successfully或ERROR；反复出现Skipping file because it matches ignore说明路径被exclude规则过滤了 - 手动触发一次上报：
wakatime-cli --write --file /tmp/test.py --project test --time $(date +%s)，返回Success才说明 CLI 层通了 - 语言统计不准（比如
.ts算进 JavaScript）→ 编辑~/.wakatime.cfg，在[settings]下加[languages]段，写明typescript = ts,tsx
周报数据迟迟不出现？时间窗和项目归属才是关键
WakaTime 不生成本地周报，Dashboard 上的「This Week」是服务端按 UTC 时间窗聚合的结果，和你本地时区、VSCode 是否开着无关。刚装插件不到 24 小时，就不可能有「上周」数据——它没历史可聚。
- 你周一 9:00 编辑
main.py2 分钟 → 上传一条心跳；周二 14:30 切换到index.tsx并敲了 5 秒 → 再传一条；这些离散记录只有到wakatime.com后，才被归入「上周一 00:00–本周日 23:59」UTC 时间窗 - 导出按钮只给原始 JSON，不是人能直接读的“周报”。要生成可读内容，得自己处理：下载 JSON 后用脚本解析
duration字段求和，或按project分组统计 - 项目名异常会导致所有时间堆成一团——哪怕你每天写 8 小时，Dashboard 里也可能只显示一个
Unknown Project占 100%，根本看不出真实分布
