agentic-productivity-setup

Agentic Productivity Setup

构建一个确定性系统，衡量 AI Agent 是否能随着时间推移提高个人产出。数据收集保留在本地。每天早晨向私密 Discord 发送一份报告，且报告中恰好包含三张汇总图表。

隐私规则

以下要求必须严格遵守：

1. 使用全新实现。绝不复制其他安装中的内容、运行时数据库、日志、会话存储、凭据、机器路径、仓库列表或私有配置。
2. 绝不持久化或传输提示词文本、回复、工具输出、仓库名称、文件路径、身份信息、原始会话 ID 或提交消息。
3. 读取 Agent 原生存储时只能用于计数事件。临时标识符仅保存在内存中，随后丢弃。只有当采集器需要跨运行基线时，才持久化单向哈希。
4. 默认在本地渲染图表。每天的总数和图表图片只能发送至 Discord。启用任何可选远程图表服务前，说明确切的数据流向。
5. 将 Discord webhook 存储在当前用户的 macOS 钥匙串中。绝不能将其放入源代码、命令参数、环境文件、数据库、日志、测试或调度器定义中。
6. 测试中使用合成测试数据。绝不使用复制的会话数据、真实提示词、真实仓库元数据或有效凭据。
7. 以只读方式打开原生数据库。采集器不得修改 Agent 状态。
8. 将缺失、无法读取或不受支持的数据源报告为覆盖问题。绝不将采集失败静默转换为零。

确认范围

首先确定用户想要的是说明、新项目还是安装。若用户只是询问其工作原理，则不要创建或安装任何内容。

若要构建，请确认或安全地采用以下默认值：

• 平台：macOS。要适配其他操作系统前，先询问用户。
• 代码根目录：$HOME/code。
• 时区：Mac 当前配置的时区。
• 报告时间：本地时间 08:00。
• 报告窗口：截至昨天的 90 天。
• Agent 执行环境：仅包含用户希望衡量的工具。
• 项目位置和反向 DNS 格式的 LaunchAgent 标签。

不要让用户将 webhook 粘贴到聊天中。应用构建完成后，通过安全的终端输入进行配置。

更改指标定义、存储边界、报告目标位置或从 Mac 发出的数据之前，先征求用户同意。在生成的项目中用简短的 ADR 记录重要决策。

架构

使用以下数据流：

Git reflogs + native agent registries
    -> read-only collectors
    -> daily aggregate counts
    -> local SQLite database
    -> local chart renderer
    -> one Discord webhook request

将源代码检出目录与已安装的运行时分开：

• 将应用代码复制到 ~/Library/Application Support/<app>/app/。
• 在其旁边的 metrics.sqlite3 中存储汇总状态。
• 将日志存储在 ~/Library/Logs/<app>/。
• 将 plist 安装到 ~/Library/LaunchAgents/。
• 目录权限设为 0700，敏感文件权限设为 0600。
• 重新安装和正常卸载时保留汇总状态。

指标约定

实现三个相互独立的指标。不要创建综合生产力评分。

唯一的本地提交

• 在配置的代码根目录下递归发现 Git 仓库。
• 按 Git 公共目录对主检出和关联工作树去重。
• 读取所请求日期范围内 reflog 中的本地创建事件。
• 仅纳入作者或提交者电子邮件与该仓库中配置的身份相匹配的提交。
• 在所有引用和工作树中，每个提交哈希只计数一次。
• 排除仅因获取提交、推送或分支移动而产生的记录。
• 哈希仅保存在内存中。只存储每日最终计数。

活跃 Agent 会话

• 在原生注册表记录活动的每个本地日历日，将该会话计数一次。
• 纳入 GUI、CLI、无头、恢复、父级、子 Agent、委派和自动化会话。
• 使用执行环境的原生会话身份在内存中去重。
• 在存储和报告中分别保留各执行环境的数据。

包含指令的提示词

• 统计存储的用户、系统和开发者输入中包含指令的数量。
• 包括人工提示词、自动化内容、设置上下文、委派内容和子 Agent 指令。
• 排除助手回复、工具结果、空输入和重复存储的副本。
• 仅检查内容以判断事件类别。绝不存储或记录内容。

在分配日期前，将每个时间戳转换为配置的时区。

收集器设计

每种运行环境使用一个适配器。优先使用原生注册表，而非进程检查、Shell 历史记录、窗口标题或猜测的文件时间戳。

支持常见的数据源格式：

• JSON 或 JSONL 会话记录。
• 只读 SQLite 注册表。
• 编辑器全局或工作区状态数据库。
• 如果没有可读取的本地注册表，则使用经过身份验证的原生 CLI 导出。

每个适配器必须返回：

• 内存中的每日唯一会话标识；
• 每日提示词计数；
• full、partial、unavailable、absent 或 error 覆盖状态；
• 包含计数和限制的简短详情字符串，绝不包含私密数据。

某些存储仅提供会话总数，不提供每轮对话的时间戳。对于这些存储，保存经过哈希处理的源键和总数，然后只统计本地基线之后观测到的正向增量。将更早的归因标记为部分归因。

在运行时发现已安装的运行环境。将不受支持的工具从图表中省略，不要错误地标记为零活动量。

聚合数据库

使用 WAL 模式的 SQLite。保持架构精简：

• daily_metrics：日期、指标、运行环境、计数、收集时间。
• collector_health：每种运行环境的安装和覆盖状态。
• source_snapshots：经过哈希处理的源键、上次总数、观测时间。
• collector_baselines：每种运行环境的首次可靠观测。
• deliveries：报告日期、发送状态、发送时间和简短的安全错误信息。

对每日计数使用单调递增的 upsert。后续不完整的扫描不得抹去已存储的较高值。

绝不为原始事件、消息、提示词、回复、仓库名称、路径或标识创建表。

报告和 Discord 投递

为所选时间范围准确生成三张图表：

1. 每日唯一提交数，使用折线和面积图。
2. 每日活跃会话数，使用按运行环境分组的堆叠柱状图。
3. 每日指令提示词数，使用按运行环境分组的堆叠柱状图。

为每张图表添加直线普通最小二乘趋势线。会话和提示词的趋势线使用每日总数。使用固定版本的图表依赖项在本地渲染 PNG 文件。绝不静默回退到网络渲染器。

Discord 消息只能包含：

• 报告日期；
• 昨日的三项总数；
• 简短的收集器覆盖情况摘要；
• 三个 PNG 附件。

发送一个 multipart POST。禁用允许提及功能。仅接受有效的 Discord webhook 主机。使用较短的超时时间。绝不记录请求 URL 或请求正文。

在进行网络操作前，先在 SQLite 中认领报告日期。仅在 Discord 成功响应后将其标记为已发送。正常运行时，每个报告日期只发送一次。重新发送必须使用显式的强制选项。

调度

使用用户级 LaunchAgent。不要按计划运行 LLM。

配置：

• 使用 StartCalendarInterval 设置所选的每日报告时间。
• 如果收集器需要提示词增量，则将 StartInterval 设为 300 秒。
• 使用 RunAtLoad 进行登录和唤醒补收。
• 将 ProcessType 设为 Background。
• 启用 LowPriorityIO。
• 使用限制严格的 077 umask，并在 plist 中表示为十进制 63。
• 将 stdout 和 stderr 路径设在私有日志目录中。

每个时间间隔都可以观测仅提供增量的数据源。报告时间之前，在完成本地观测后停止。报告时间或之后，收集昨日数据、构建完整时间范围，并且仅当该日期尚未标记为已发送时才发送。

安装程序必须将绝对运行时路径写入 plist，使用 plutil 验证 plist，安全地替换现有任务并启动该任务。不要将凭据写入 plist。

项目结构

采用小巧、易读的项目结构：

agentic_productivity/
  cli.py
  collectors.py
  database.py
  model.py
  reporting.py
bin/
  agentic-productivity
launchd/
  <label>.plist.in
scripts/
  install.sh
  uninstall.sh
  test.sh
tests/
docs/adr/

除非用户选择其他简单、易维护的技术栈，否则使用 Python 3.11 或更高版本。保持采集器模块化。定时命令应具有确定性且无需交互。

提供以下命令：

• doctor：检查前置条件、路径、凭据是否存在、数据库和采集器覆盖情况，且不暴露机密。
• collect：采集并存储聚合数据，不进行交付。
• mock：运行采集、报告生成、图表渲染和多部分组装，不访问网络，也不改变交付状态。
• run：执行定时观测并生成幂等报告。
• status：显示安全的采集和交付状态。
• configure-webhook：从标准输入读取 webhook，并将其存储在 macOS Keychain 中。

安全的 webhook 配置

实现后，使用如下交互式 shell 模式：

read -r -s REPORT_WEBHOOK
printf '%s\n' "$REPORT_WEBHOOK" | ./bin/agentic-productivity configure-webhook
unset REPORT_WEBHOOK

该命令只能输出配置是否成功，绝不能回显机密。

验证门槛

只有通过所有检查后，才能报告成功：

1. 使用合成的原生存储数据测试每个采集器。
2. 测试去重、时区边界、提示词角色筛选、单调递增的 upsert、覆盖失败和幂等交付。
3. 测试报告仅包含聚合数据，且附件恰好有 3 个。
4. 运行完整测试套件和无需网络的 mock 命令。
5. 先安装到临时主目录。确认运行不需要源代码检出目录或运行时状态。
6. 验证渲染后的 plist 不包含任何凭据或私有源数据。
7. 验证受跟踪的文件不包含数据库、日志、会话导出、提示词数据样本、凭据、特定于机器的绝对路径或真实身份信息。
8. 运行 doctor，加载 LaunchAgent，并确认其上次退出状态为 0。
9. 只有获得用户许可，才发送实时测试报告。

如果任何隐私检查存在不确定之处，请停止发布该文件。不要放宽检查。

完成报告

告知用户：

• 源代码、已安装应用、聚合数据库、plist 和日志的位置；
• 已启用的指标和运行环境；
• 时区、报告时间和时间窗口；
• webhook 是否已配置，但不要显示其内容；
• 运行了哪些测试，以及 LaunchAgent 是否运行正常；
• 仍需关注的所有部分可用或不可用的采集器。