用户手册

使用帮助

从零装起、跑起来、日常维护、排故障 —— 一篇看完。本项目是个人工具：一人一套数据，全部留在你自己机器上。

1. 这是什么

Polars Daily Log 是一个本地运行的个人工作活动聚合器。它默默记录你每台机器上的前台活动（app、窗口标题、URL、可选 OCR）和 Git commits，交给 LLM 总结成当日工作日志，可以一键推给 Jira 作为 worklog。

一人一套数据。 不是 SaaS，也不是多租户。每个用户自己装一套， server / collector 都跑在你自己的机器上，数据不出门。

你的使用场景

只用一台电脑：这台装 both（server + collector 一体）。
多台设备想汇总：最常开机那台装 both 当 hub；其他机器装 collector，推到 hub。
想改代码：clone 仓库走 dev 模式，见 §8。

2. 安装

前置条件

	macOS	Linux	Windows
Python 3.9+	自带	自带	`winget install Python.Python.3.12`
Git	`xcode-select --install`	`apt install git`	`winget install Git.Git`

方式 A：一条命令装（推荐，macOS / Linux）

curl -fsSL https://raw.githubusercontent.com/Conner2077/polars-daily-log/master/bootstrap.sh | bash

会做：拉最新 release → 解压到 ~/.polars-daily-log → 交互跑 install.sh。

非交互模式（装 collector 到第二台机器）

curl -fsSL https://raw.githubusercontent.com/Conner2077/polars-daily-log/master/bootstrap.sh | \
  PDL_ROLE=collector \
  PDL_SERVER_URL=http://你的hub:8888 \
  PDL_COLLECTOR_NAME=my-laptop \
  bash

可选环境变量

PDL_VERSION — 指定版本，默认 latest
PDL_INSTALL_DIR — 安装目录，默认 ~/.polars-daily-log
PDL_ROLE — server / collector / both / ask
PDL_SERVER_URL — collector 连向的 server 地址
PDL_COLLECTOR_NAME — collector 在 hub 上的显示名

方式 B：手动装 tarball（Windows 或离线）

从 Releases 页下载 polars-daily-log-<version>.tar.gz
解压：tar xzf polars-daily-log-0.2.0.tar.gz && cd polars-daily-log-0.2.0

跑 installer：

# macOS / Linux
bash install.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File install.ps1

3. 首次配置

选角色

Installer 会问：

0. What are you installing?
  1) server      — 中心服务 + Web UI
  2) collector   — 活动采集 agent
  3) both        — 两个都装

场景对照：

只一台机器：选 3（both）
这台是 hub：选 3（both）
这台只是 collector 推给 hub：选 2，填 Server URL 和 Collector 显示名

启动

# 装到 ~/.polars-daily-log 的话（bootstrap 装法）
~/.polars-daily-log/pdl server start      # server 角色
~/.polars-daily-log/pdl collector start   # collector 角色
~/.polars-daily-log/pdl start             # both 角色（一起起）

把 pdl 加到 PATH 更方便：

echo 'export PATH="$HOME/.polars-daily-log:$PATH"' >> ~/.zshrc
source ~/.zshrc
pdl status

打开 Web UI

浏览器访问 http://127.0.0.1:8888（或 hub 机器 IP）。首次进去到 Settings：

LLM — 选 Kimi / OpenAI / Claude / Ollama，填 API Key（留空走内置 Kimi 默认）
Jira（可选） — 若要把日志同步成 Jira worklog，扫码登录 Jira SSO

4. 日常使用

起停

目的	命令
启动全部	`pdl start`
只启 server	`pdl server start`
只启 collector	`pdl collector start`
看状态	`pdl status`
停	`pdl stop`
重启	`pdl restart`

看日志

pdl server logs 100       # server 后端最近 100 行
pdl server logs -f        # 实时跟
pdl collector logs 50     # collector 最近 50 行

Windows 等价

Windows 走 Scheduled Task 自启（安装时会问要不要登录时自动起）：

Start-ScheduledTask -TaskName AutoDailyLogServer
Stop-ScheduledTask -TaskName AutoDailyLogServer
Get-ScheduledTaskInfo -TaskName AutoDailyLogCollector

反馈 bug

Web UI 右上角 💡 按钮 — 写几句话，后台自动附上当前页面和 UA 发到开发者。

5. 数据位置 & 隐私

东西	路径
数据库（活动、日志、配置）	`~/.auto_daily_log/data.db`
截图	`~/.auto_daily_log/screenshots/YYYY-MM-DD/`
Server log	`~/.auto_daily_log/logs/server.log`
独立 Collector log	`~/.auto_daily_log_collector/logs/collector.log`
Server 配置	`<安装目录>/config.yaml`
Collector 配置	`<安装目录>/collector.yaml`

升级覆盖 tarball 时，~/ 下这些都不会动。升级不丢数据。

隐私相关

monitor.privacy.blocked_apps / blocked_urls 严格尊重 —— 命中的活动不记录。
反侦测 app（如企业微信）在 hostile_apps_applescript 白名单里会跳过深度 introspection。
OCR 中若出现敏感信息（密码、银行卡），用户手动删除后回收站也会真删。

6. 升级 & 卸载

升级（bootstrap 装的）

再跑同一条 curl 命令即可，原地覆盖。bootstrap 会先 pdl stop，~/ 下的数据不受影响。

升级（手动装的）

cd <你解压过的目录>
./pdl stop
tar xzf polars-daily-log-0.2.0.tar.gz --strip-components=1
./pdl build --restart

如果某版本要求 config 迁移，会在 CHANGELOG.md 顶部明确写出来。

卸载

./pdl stop
rm -rf ~/.polars-daily-log            # 代码 + venv + 配置
rm -rf ~/.auto_daily_log              # 数据 + 日志（不想删可跳过）
rm -rf ~/.auto_daily_log_collector    # 独立 collector 凭据 + 离线队列

Windows 额外：

Unregister-ScheduledTask -TaskName AutoDailyLogServer -Confirm:$false
Unregister-ScheduledTask -TaskName AutoDailyLogCollector -Confirm:$false

7. 常见问题

症状	怎么查 / 怎么修
`No module named aiosqlite` 启动就崩	venv 没激活 / 跳过了 `install.sh`。重跑 `bash install.sh`。
当日总结只有 `Activity summary: ...` 行	LLM 调用失败 → Web UI Settings 检查 engine / URL / API Key。
提交 Jira 返 500 `内部服务器错误`	comment 含 emoji。新版已自动 scrub，升级一下。
企业微信 2-4 分钟自退	确认 `config.yaml` 里 `monitor.hostile_apps_applescript` 包含 `企业微信/wechat/wecom`。
前端白屏	`pdl server logs 50` 看后端；硬刷浏览器 Cmd/Ctrl+Shift+R。
Windows collector 不动	看 `%USERPROFILE%\.auto_daily_log_collector\logs\collector.log`；检查 Scheduled Task 状态。
macOS collector 抓不到窗口标题	系统设置 → 隐私与安全 → 辅助功能里，给 Terminal / iTerm2 勾选权限。

8. 给开发者

如果你拿到的是 git 仓库而不是 tarball，想改代码：

git clone https://github.com/Conner2077/polars-daily-log.git
cd polars-daily-log
bash install.sh           # 自动识别无 wheel → dev 模式
./pdl server start

目的	命令
pull 后重新 build	`./pdl build --restart`
只重建前端	`./pdl build --no-python`
跑测试	`.venv/bin/python -m pytest tests/ -q`
前端 hot-reload	`cd web/frontend && npm run dev`，打开 `localhost:5173`

打 release：见 docs/release.md。项目核心原则：见 AGENTS.md。