agentic-productivity-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentic Productivity Setup

智能生产力追踪系统搭建

Build a deterministic system that measures whether AI agents increase a person's output over time. Keep collection local. Send one private Discord report each morning with exactly three aggregate charts.

构建一个确定性系统，用于衡量AI Agent是否能随时间提升用户的产出。所有数据收集在本地进行。每天早上发送一份私有Discord报告，包含恰好三张汇总图表。

Privacy rules

隐私规则

Treat these as hard requirements:

Build a fresh implementation. Never copy another installation, runtime database, log, session store, credential, machine path, repository list, or private configuration.
Never persist or transmit prompt text, responses, tool output, repository names, file paths, identities, raw session IDs, or commit messages.
Read native agent stores only to count events. Keep temporary identifiers in memory, then discard them. Persist a one-way hash only when a collector needs a cross-run baseline.
Render charts locally by default. Only Discord should receive the daily totals and chart images. Explain the exact data flow before enabling any optional remote chart service.
Store the Discord webhook in the current user's macOS Keychain. Never put it in source code, a command argument, an environment file, the database, logs, tests, or the scheduler definition.
Use synthetic fixtures in tests. Never use copied session data, real prompts, real repository metadata, or live credentials.
Open native databases read-only. Collectors must not modify agent state.
Report missing, unreadable, or unsupported sources as coverage problems. Never turn collection failure into a silent zero.

将以下规则视为硬性要求：

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

Confirm the scope

确认范围

First determine whether the user wants an explanation, a new project, or an installation. Do not create or install anything when they only asked how it works.

For a build, confirm or safely default these values:

Platform: macOS. Ask before adapting the design to another operating system.
Code root:
```
$HOME/code
```
.
Timezone: the Mac's configured timezone.
Report time: 08:00 local time.
Report window: 90 days ending yesterday.
Agent harnesses: only tools the user wants measured.
Project location and reverse-DNS LaunchAgent label.

Do not ask the user to paste a webhook into chat. Configure it through secure terminal input after the application is built.

Ask before changing metric definitions, storage boundaries, report destinations, or data sent off the Mac. Record consequential choices in a short ADR inside the generated project.

首先确定用户需要的是解释说明、新项目构建还是安装。当用户仅询问工作原理时，不要进行创建或安装操作。

若进行构建，需确认或安全默认以下值：

平台：macOS。如需适配其他操作系统，需先询问用户。
代码根目录：
```
$HOME/code
```
。
时区：Mac配置的时区。
报告时间：本地时间08:00。
报告窗口：截至昨日的90天。
Agent管理工具：仅统计用户指定的工具。
项目位置和反向DNS格式的LaunchAgent标签。

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

如需修改指标定义、存储边界、报告目标或传出Mac的数据，需先询问用户。将重要决策记录在生成项目内的简短ADR（架构决策记录）中。

Architecture

架构

Use this data flow:

text

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

Keep the source checkout separate from the installed runtime:

Copy application code into

~/Library/Application Support/<app>/app/

Store aggregate state beside it in
```
metrics.sqlite3
```
.
Store logs in
```
~/Library/Logs/<app>/
```
.
Install the plist in
```
~/Library/LaunchAgents/
```
.
Give directories mode
```
0700
```
and sensitive files mode
```
0600
```
.
Preserve aggregate state across reinstalls and normal uninstalls.

采用以下数据流：

text

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
```
。
在重新安装和正常卸载时保留汇总状态。

Metric contracts

指标协议

Implement three independent metrics. Do not create a combined productivity score.

实现三个独立指标。不要创建综合生产力得分。

Unique local commits

本地唯一提交数

Discover Git repositories recursively under the configured code root.
Deduplicate primary checkouts and linked worktrees by Git common directory.
Read local creation events from reflogs for the requested date range.
Include only commits whose author or committer email matches an identity configured in that repository.
Count each commit hash once across all refs and worktrees.
Exclude fetched commits, pushes, and branch movement by themselves.
Keep hashes in memory only. Store the final daily count.

在配置的代码根目录下递归发现Git仓库。
通过Git公共目录去重主检出目录和链接工作区。
从reflogs中读取请求日期范围内的本地创建事件。
仅包含作者或提交者邮箱与该仓库中配置的身份匹配的提交。
每个提交哈希在所有引用和工作区中仅计数一次。
排除仅获取的提交、推送操作和分支移动。
哈希值仅保留在内存中。仅存储最终的每日计数。

Active agent sessions

活跃Agent会话数

Count one session on each local calendar day where its native registry records activity.
Include GUI, CLI, headless, resumed, parent, subagent, delegated, and automated sessions.
Deduplicate with the harness's native session identity in memory.
Keep each harness separate in storage and reports.

在每个本地日历日，若原生注册表记录了活动，则计数一次会话。
包含GUI、CLI、无头模式、恢复的、父级、子Agent、委托和自动化会话。
在内存中通过管理工具的原生会话身份去重。
在存储和报告中区分每个管理工具。

Instruction-bearing prompts

含指令的提示词数

Count stored user, system, and developer inputs that contain instructions.
Include human prompts, automation, setup context, delegation, and subagent instructions.
Exclude assistant responses, tool results, empty inputs, and duplicated storage copies.
Inspect content only long enough to classify the event. Never store or log it.

Convert every timestamp into the configured timezone before assigning a day.

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

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

Collector design

收集器设计

Use one adapter per harness. Prefer native registries over process inspection, shell history, window titles, or guessed file timestamps.

Support common source shapes:

JSON or JSONL session records.
Read-only SQLite registries.
Editor global or workspace state databases.
Authenticated native CLI export when no readable local registry exists.

Each adapter must return:

daily unique session identities in memory;
daily prompt counts;
```
full
```
,
```
partial
```
,
```
unavailable
```
,
```
absent
```
, or
```
error
```
coverage;
a short detail string containing counts and limitations, never private data.

Some stores expose a session total but no timestamp for each turn. For those stores, save a hashed source key and total, then attribute only positive deltas observed after the local baseline. Mark older attribution as partial.

Discover installed harnesses at runtime. Keep unsupported tools absent from the chart, not mislabeled as zero activity.

每个管理工具对应一个适配器。优先使用原生注册表，而非进程检查、shell历史记录、窗口标题或猜测的文件时间戳。

支持常见数据源格式：

JSON或JSONL会话记录。
只读SQLite注册表。
编辑器全局或工作区状态数据库。
当无可读本地注册表时，使用已认证的原生CLI导出。

每个适配器必须返回：

内存中的每日唯一会话身份；
每日提示词计数；
```
full
```
（完整）、
```
partial
```
（部分）、
```
unavailable
```
（不可用）、
```
absent
```
（缺失）或
```
error
```
（错误）的覆盖状态；
包含计数和限制的简短详情字符串，绝不包含私有数据。

部分存储仅暴露会话总数，但无每个交互的时间戳。对于此类存储，保存哈希后的源密钥和总数，然后仅将本地基线后观察到的正增量计入。将较早的归因标记为部分覆盖。

在运行时发现已安装的管理工具。不支持的工具在图表中显示为缺失，而非标记为零活动。

Aggregate database

汇总数据库

Use SQLite in WAL mode. Keep the schema small:

```
daily_metrics
```
: day, metric, harness, count, collection time.
```
collector_health
```
: installation and coverage state per harness.
```
source_snapshots
```
: hashed source key, last total, observation time.
```
collector_baselines
```
: first reliable observation per harness.
```
deliveries
```
: report day, sending state, sent time, and a short safe error.

Use monotonic upserts for daily counts. A later incomplete scan must not erase a higher value already stored.

Never create tables for raw events, messages, prompts, responses, repository names, paths, or identities.

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

```
daily_metrics
```
：日期、指标、管理工具、计数、收集时间。
```
collector_health
```
：每个管理工具的安装和覆盖状态。
```
source_snapshots
```
：哈希后的源密钥、上次总数、观察时间。
```
collector_baselines
```
：每个管理工具的首次可靠观察记录。
```
deliveries
```
：报告日期、发送状态、发送时间和简短安全错误信息。

对每日计数使用单调更新。后续不完整扫描不得覆盖已存储的更高值。

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

Report and Discord delivery

报告与Discord推送

Build exactly three charts for the selected window:

Daily unique commits as a line and area chart.
Daily active sessions as stacked bars split by harness.
Daily instruction prompts as stacked bars split by harness.

Add a straight ordinary least-squares trendline to each chart. Use combined daily totals for the session and prompt trendlines. Render PNG files locally with a pinned charting dependency. Never silently fall back to a network renderer.

The Discord message should contain only:

the report day;
yesterday's three totals;
a short collector coverage summary;
the three PNG attachments.

Send one multipart POST. Disable allowed mentions. Accept only valid Discord webhook hosts. Use a short timeout. Never log the request URL or body.

Claim the report day in SQLite before network work. Mark it sent only after a successful Discord response. Normal runs must send once per report day. Require an explicit force option to resend.

为选定的时间窗口构建恰好三张图表：

每日唯一提交数：折线图+面积图。
每日活跃会话数：按管理工具拆分的堆叠柱状图。
每日指令提示词数：按管理工具拆分的堆叠柱状图。

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

Discord消息应仅包含：

报告日期；
昨日的三个统计总数；
简短的收集器覆盖范围摘要；
三张PNG附件。

发送一个多部分POST请求。禁用提及功能。仅接受有效的Discord webhook主机。使用短超时。绝不记录请求URL或请求体。

在进行网络操作前，在SQLite中标记报告日期。仅在收到Discord成功响应后，将其标记为已发送。正常运行时每日仅发送一次报告。需使用显式强制选项才能重新发送。

Scheduling

调度配置

Use a user LaunchAgent. Do not run an LLM on the schedule.

Configure:

```
StartCalendarInterval
```
for the chosen daily report time.
```
StartInterval
```
of 300 seconds when a collector needs prompt deltas.
```
RunAtLoad
```
for login and wake catch-up.
```
ProcessType
```
set to
```
Background
```
.
```
LowPriorityIO
```
enabled.
A restrictive
```
077
```
umask, represented as decimal
```
63
```
in the plist.
stdout and stderr paths inside the private log directory.

Every interval may observe delta-only sources. Before the report time, stop after that local observation. At or after the report time, collect yesterday, build the full window, and send only if that day is not already marked sent.

The installer must render absolute runtime paths into the plist, validate it with

plutil

, replace the existing job safely, and start it. Keep credentials out of the plist.

使用用户级LaunchAgent。不要在调度中运行LLM。

配置项：

```
StartCalendarInterval
```
：设置为选定的每日报告时间。
```
StartInterval
```
：当收集器需要提示词增量时，设置为300秒。
```
RunAtLoad
```
：登录和唤醒时执行补全操作。
```
ProcessType
```
：设置为
```
Background
```
。
启用
```
LowPriorityIO
```
。
限制性
```
077
```
权限掩码，在plist中表示为十进制
```
63
```
。
stdout和stderr路径设置在私有日志目录内。

每个间隔可能仅观察增量数据源。在报告时间前，完成本地观察后停止。在报告时间或之后，收集昨日数据，构建完整时间窗口，仅当日未标记为已发送时才发送报告。

安装程序必须将绝对运行时路径渲染到plist中，使用

plutil

验证它，安全替换现有任务并启动它。不要将凭据放入plist中。

Project shape

项目结构

Use a small, readable project:

text

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/

Use Python 3.11 or newer unless the user chooses another simple, maintainable stack. Keep collectors modular. Keep the scheduled command deterministic and non-interactive.

Provide these commands:

```
doctor
```
: check prerequisites, paths, credential presence, database, and collector coverage without exposing secrets.
```
collect
```
: collect and store aggregates without delivery.
```
mock
```
: run collection, reporting, chart rendering, and multipart assembly without network access or delivery state.
```
run
```
: perform the scheduled observation and idempotent report.
```
status
```
: show safe collection and delivery state.
```
configure-webhook
```
: read the webhook from standard input and store it in macOS Keychain.

使用小型、可读性强的项目结构：

text

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钥匙串中。

Secure webhook setup

安全Webhook设置

Use an interactive shell pattern like this after implementation:

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

The command must print only whether configuration succeeded. It must never echo the secret.

实现后使用如下交互式shell流程：

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

该命令仅需打印配置是否成功。绝不要回显机密内容。

Verification gate

验证关卡

Do not report success until all checks pass:

Test every collector with synthetic native-store fixtures.
Test deduplication, timezone boundaries, prompt-role filtering, monotonic upserts, coverage failures, and idempotent delivery.
Test that reports contain only aggregates and exactly three attachments.
Run the full test suite and the network-free
```
mock
```
command.
Install into a temporary home first. Confirm no source checkout or runtime state is required for execution.
Verify the rendered plist contains no credential or private source data.
Verify tracked files contain no databases, logs, session exports, prompt fixtures, credentials, machine-specific absolute paths, or real identities.
Run
```
doctor
```
, load the LaunchAgent, and confirm its last exit status is zero.
Send a live test report only with the user's permission.

If any privacy check is uncertain, stop the release of that file. Do not weaken the check.

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

使用合成原生存储测试数据测试每个收集器。
测试去重、时区边界、提示词角色过滤、单调更新、覆盖失败和幂等推送。
测试报告仅包含汇总数据和恰好三个附件。
运行完整测试套件和无网络的
```
mock
```
命令。
先安装到临时主目录。确认执行无需源代码检出目录或运行时状态。
验证渲染后的plist不包含凭据或私有源数据。
验证跟踪文件不包含数据库、日志、会话导出、提示词测试数据、凭据、机器特定绝对路径或真实身份信息。
运行
```
doctor
```
，加载LaunchAgent，确认其最后退出状态为零。
仅在用户允许的情况下发送实时测试报告。

若任何隐私检查存在不确定性，停止发布相关文件。不要弱化检查标准。

Completion report

完成报告

Tell the user:

where the source, installed app, aggregate database, plist, and logs live;
which metrics and harnesses are enabled;
the timezone, report time, and window;
whether the webhook is configured, without showing it;
which tests ran and whether the LaunchAgent is healthy;
every partial or unavailable collector that still matters.

告知用户：

源代码、已安装应用、汇总数据库、plist和日志的存储位置；
已启用的指标和管理工具；
时区、报告时间和窗口；
webhook是否已配置（不显示具体内容）；
运行的测试以及LaunchAgent是否健康；
仍存在问题的部分或不可用收集器。