kenn-io--agentsview/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/kenn-io/agentsview) · [上游 README](https://github.com/kenn-io/agentsview/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# agentsview

浏览、搜索并追踪所有 AI 编程智能体（agent）的费用。单个二进制文件，无需账号，一切本地运行。

<p align="center">
  <img src="https://agentsview.io/assets/generated/screenshots/dashboard.png" alt="Analytics dashboard" width="720">
</p>

## Install

```bash
# macOS / Linux
curl -fsSL https://agentsview.io/install.sh | bash

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://agentsview.io/install.ps1 | iex"
```

或从 [GitHub Releases](https://github.com/kenn-io/agentsview/releases)) 下载**桌面应用**（macOS / Windows），或通过 homebrew：`brew install --cask agentsview`

或运行已发布的 Docker 镜像：

```bash
docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -v "$HOME/.forge:/agents/forge:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  -e FORGE_DIR=/agents/forge \
  ghcr.io/kenn-io/agentsview:latest
```

## Quick Start

```bash
agentsview serve           # start the server in the foreground
agentsview daemon start    # start the writable SQLite daemon
agentsview daemon status   # show daemon status
agentsview daemon restart  # restart from current configuration
agentsview daemon stop     # stop the writable daemon
agentsview session list    # read from the daemon if warm, otherwise SQLite
agentsview usage daily     # print daily cost summary
```

首次运行时，agentsview 会从你机器上每个受支持的 agent 中发现会话，将其同步到本地 SQLite 数据库，并在 `http://127.0.0.1:8080` 提供 Web UI。

对于 Devin CLI，将 `DEVIN_DIR` 或 `devin_dirs` 指向包含 `cli/` 的本地根目录——例如在 macOS 上为 `~/Library/Application Support/devin`，在 Linux 上为 `~/.local/share/devin`，或类似 `.../Application Support/devin` 的脱敏路径。AgentsView 读取 `<root>/cli/...` 下的会话数据，并有意忽略复制的配置或 OAuth 路径。请勿在 bug 报告中粘贴 token、OAuth 文件或其他机密信息。

Claude 和 Codex 数据源也可配置为 `s3://` 根目录，这样中央 AgentsView 实例即可读取其他机器推送到 S3 兼容对象存储的会话。将这些根目录添加到 `claude_project_dirs` 或 `codex_sessions_dirs`；AgentsView 会列出对象元数据，并仅在同步期间下载已变更的会话。S3 变更检测使用大小、修改时间以及可用的对象指纹，例如 ETag、version ID 或校验和。

桌面应用与对数据新鲜度敏感的 CLI 命令共享一个分离的本地守护进程。只读 CLI 命令在守护进程已运行时会连接它，否则会回退到冷归档上的直接只读 SQLite，以保持一次性脚本的速度。需要最新数据或需要写入的命令（例如 `sync`、`usage`、`token-use`、`pg push` 和 `duckdb push`）会在需要时自动启动守护进程。

当你希望显式启动可写 SQLite 守护进程时，使用 `agentsview daemon start`。它会从 `config.toml` 以及受支持的环境变量加载正常的有效配置；`daemon start` 和 `daemon restart` 不接受任何 serve 专用标志。后台守护进程在空闲一段时间后会自行退出，除非有客户端请求或守护进程拥有的任务处于活动状态。

现有的 `agentsview serve --background`、`agentsview serve status` 和 `agentsview serve stop` 命令仍然可用。当一次性守护进程需要仅用于 serve 的标志时（例如 `--no-sync` 或未认证的 non-loopback `--host` 覆盖），使用 `serve --background`。

## Remote / forwarded access

agentsview 绑定到 loopback，并校验请求的 `Host` 标头，以防范 DNS 重绑定攻击。当你通过 SSH 端口转发、反向代理或远程开发环境（exe.dev、Codespaces、Coder、WSL2）访问时，浏览器会发送服务器无法识别的 `Host`，因此诸如 `/api/v1/settings` 的 API 请求会被以 `403 Forbidden` 拒绝。

要解决此问题，请重启服务器，并将 `--public-url` 设置为你在浏览器中打开的精确 origin：

```bash
# Browser opens http://127.0.0.1:18080 via `ssh -L 18080:127.0.0.1:8080 host`
agentsview serve --public-url http://127.0.0.1:18080

# Browser opens a forwarded hostname
agentsview serve --public-url https://your-workspace.exe.dev
```

使用 `--public-origin`（可重复或逗号分隔）来信任额外的浏览器 origin。如果你将 UI 暴露到 loopback 之外，还应启用 `--require-auth`。

## Docker

容器镜像默认使用本地 `agentsview serve`。设置 `PG_SERVE=1` 可将启动命令切换为 `agentsview pg serve`。

`docker-compose.prod.yaml` 作为生产示例包含在内：

```bash
docker compose -f docker-compose.prod.yaml up -d
```

附带的 compose 文件会将 agentsview 数据目录持久化到命名卷，并以只读方式挂载 Claude、Codex、Forge 和 OpenCode 的会话根目录。容器以 root 运行，因此对于 `/data`，优先使用命名卷而非主机 bind mount；如果确实要 bind mount，请预先创建具有所需所有权的目录，以避免主目录中出现 root 拥有的文件。

示例仅在 loopback 上发布 UI（`127.0.0.1`）。如果你需要暴露到 localhost 之外，请启用 `--require-auth` 并有意识地发布端口。

重要提示：容器化的 agentsview 实例只能发现你显式挂载到容器中的 agent 会话目录。如果你没有挂载某个 agent 的会话目录并将对应的环境变量指向它，该 agent 将不会出现在 UI 中。

PostgreSQL 后端启动示例：

```bash
docker run --rm -p 127.0.0.1:8080:8080 \
  -e PG_SERVE=1 \
  -e AGENTSVIEW_PG_URL='postgres://user:password@postgres.example.com:5432/agentsview?sslmode=require' \
  ghcr.io/kenn-io/agentsview:latest
```

DuckDB 镜像启动示例：

```bash
# Populate /data/sessions.duckdb from the mounted SQLite archive.
docker run --rm \
  -v agentsview-data:/data \
  -v "$HOME/.claude/projects:/agents/claude:ro" \
  -e CLAUDE_PROJECTS_DIR=/agents/claude \
  ghcr.io/kenn-io/agentsview:latest duckdb push --full

# Serve the populated mirror read-only.
docker run --rm -p 127.0.0.1:8080:8080 \
  -v agentsview-data:/data \
  ghcr.io/kenn-io/agentsview:latest duckdb serve
```

Quack 启动示例：

```bash
# Expose the local DuckDB mirror over Quack from the host/container.
QUACK_TOKEN="$(openssl rand -base64 32)"
docker run --rm -p 127.0.0.1:9494:9494 \
  -v agentsview-data:/data \
  ghcr.io/kenn-io/agentsview:latest \
  duckdb quack serve \
    --bind quack:0.0.0.0:9494 \
    --token "$QUACK_TOKEN" \
    --allow-insecure

# Serve the web UI from a remote Quack endpoint.
docker run --rm -p 127.0.0.1:8080:8080 \
  -e AGENTSVIEW_DUCKDB_URL='quack:https://duckdb.example.com' \
  -e AGENTSVIEW_DUCKDB_TOKEN="$QUACK_TOKEN" \
  ghcr.io/kenn-io/agentsview:latest duckdb serve
```

请将 Quack 保持在 loopback 上或置于 TLS 之后。在非 loopback 绑定上使用纯 HTTP 的 Quack 需要 `--allow-insecure`，且应仅在受信任的隧道或反向代理之后使用。

## Token Usage and Cost Tracking

`agentsview usage` 是 ccusage 及类似工具的快速本地替代方案。它追踪**所有**编程 agent 的 token 消耗与计算成本——不仅限于 Claude Code。由于会话数据已索引在 SQLite 中，查询速度比每次运行都重新解析原始会话文件的工具快 100 倍以上。

```bash
# Daily cost summary (default: last 30 days)
agentsview usage daily

# Per-model breakdown
agentsview usage daily --breakdown

# Filter by agent and date range
agentsview usage daily --agent claude --since 2026-04-01

# One-line summary for shell prompts / status bars
agentsview usage daily --all --json
agentsview usage statusline
```

功能：

- 通过 LiteLLM 费率自动定价（含离线回退）
- 支持 prompt caching 的成本计算（cache creation / read tokens）
- 按模型细分，支持 `--breakdown`
- 日期过滤（`--since`、`--until`、`--all`）、agent 过滤（`--agent`）
- JSON 输出（`--json`），便于脚本化
- 时区感知的日期分桶（`--timezone`）
- 可独立运行——无需服务器，直接执行命令即可

## 按会话详情

`agentsview session usage <id>` 会打印单个会话的按会话 token 统计以及成本估算。输出会报告该会话的总输出 token 数与峰值上下文 token 数，并在会话所用模型（`has_cost`）提供定价信息时给出以 USD（`cost_usd`）计的成本估算。成本在内部根据输入/输出与缓存 token 计算，但对外仅与成本一并报告输出 token 与峰值上下文总量。

```bash
# Print token usage and cost for a specific session
agentsview session usage <id>

# JSON output for scripting
agentsview session usage <id> --format json
```

相同的按会话用量数据也可通过 REST API 获取：

```bash
GET /api/v1/sessions/{id}/usage
```

响应包含 CLI JSON schema 中的 `session_id`、`agent`、`project`、`total_output_tokens`、`peak_context_tokens`、`has_token_data`、`cost_usd`、`has_cost`、`models` 与 `unpriced_models` 字段。HTTP 响应还会包含 `server_running: true`。已存在的会话即使缺少 token 或成本数据也会返回 `200`；不存在的会话则返回 `404`。

已弃用的别名 `agentsview token-use <id>` 仍保留以兼容旧用法，且现在也会报告成本估算。

## 会话统计

`agentsview stats` 会输出针对已记录会话的窗口范围分析：总量、原型（automation 与 quick/standard/deep/marathon）、会话时长、用户消息数、峰值上下文、每轮工具数等分布，以及缓存经济性、工具/模型/智能体组合和按小时的时间分布。`--format json` 输出遵循适合下游消费者的版本化 v1 schema（`schema_version: 1`）。

默认情况下，`stats` 仅读取本地 SQLite 归档。基于 Git 的结果指标为可选，因为在大型或缺失的仓库上可能较慢或不稳定：使用 `--include-git-outcomes` 获取提交数/代码行数/变更文件数，使用 `--include-github-outcomes` 通过 `gh` 获取 GitHub PR 数量（这也会启用 git 结果指标）。

```bash
# Human-readable summary over the last 28 days
agentsview stats

# Machine-readable JSON over a fixed date range
agentsview stats --format json --since 2026-04-01 --until 2026-04-15

# Restrict to one agent and inspect the schema
agentsview stats --format json --agent claude | jq '.schema_version'

# Include expensive local git outcome metrics explicitly
agentsview stats --include-git-outcomes
```

## 会话浏览器

| 仪表盘                                                                      | 会话查看器                                                                           |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| ![Dashboard](https://agentsview.io/assets/generated/screenshots/dashboard.png) | ![Session viewer](https://agentsview.io/assets/generated/screenshots/message-viewer.png) |

| 搜索                                                                           | 活动热力图                                                           |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| ![Search](https://agentsview.io/assets/generated/screenshots/search-results.png) | ![Heatmap](https://agentsview.io/assets/generated/screenshots/heatmap.png) |

- **全文搜索** — 覆盖所有消息内容（FTS5）
- **语义搜索**（可选）— 使用任意 OpenAI 兼容的 embeddings 端点索引会话内容，并通过 `agentsview session search --semantic` 或 `--hybrid` 按语义搜索；每次内容搜索匹配都会引用其来源的对话单元（[文档](https://agentsview.io/semantic-search/))
- **Token 用量与成本仪表盘** — 按会话、按模型的成本明细，以及每日支出图表，均在 Web UI 中展示
- **分析仪表盘** — 活动热力图、工具使用情况、速度指标、项目分解
- **最近编辑动态** — 各会话中智能体最近修改的文件，按项目与路径分组，并链接到触发该变更的消息
- 活跃会话收到新消息时，通过 SSE **实时更新**
- **键盘优先**导航（`j`/`k`/`[`/`]`、`Cmd+K` 搜索、按 `?` 查看全部快捷键）
- 将会话**导出**为 HTML 或发布到 GitHub Gist

## 支持的智能体

agentsview 可发现来自以下所有来源的会话。Aider 为可选，因为它没有统一的会话目录；设置 `AIDER_DIR` 或 `aider_dirs` 以启用。Amp 支持已弃用，因为当前 Amp 版本可能将线程存储在服务端，本地仅保留存根；agentsview 仍可解析历史本地 Amp 线程 JSON 文件。

| 智能体                 | 会话目录                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Aider                 | `<repo>/.aider.chat.history.md`（按仓库；通过 `AIDER_DIR` 或 `aider_dirs` 可选启用）                                                                                     |
| Amp（已弃用）      | `~/.local/share/amp/threads/`（仅历史本地线程 JSON）                                                                                                       |
| Antigravity           | `~/.gemini/antigravity/`                                                                                                                                                |
| Antigravity CLI       | `~/.gemini/antigravity-cli/`（见下文说明）                                                                                                                           |
| Claude Code           | `~/.claude/projects/`                                                                                                                                                   |
| OpenClaude            | `~/.openclaude/projects/`                                                                                                                                               |
| Claude Cowork         | `~/Library/Application Support/Claude/local-agent-mode-sessions/`（macOS）                                                                                               |
| Codex                 | `~/.codex/sessions/`                                                                                                                                                    |
| Copilot CLI           | `~/.copilot/`                                                                                                                                                           |
| Devin CLI             | `~/.local/share/devin/`（Linux）、`~/Library/Application Support/devin/`（macOS）；将 `DEVIN_DIR` / `devin_dirs` 指向包含 `cli/` 的根目录                      |
| Cortex Code           | `~/.snowflake/cortex/conversations/`                                                                                                                                    |
| Cursor                | `~/.cursor/projects/`                                                                                                                                                   |
| DeepSeek TUI          | `~/.codewhale/sessions/`、`~/.deepseek/sessions/`                                                                                                                       |
| Forge                 | `~/.forge/`                                                                                                                                                             |
| Gemini CLI            | `~/.gemini/`                                                                                                                                                            |
| gptme                 | `~/.local/share/gptme/logs/`                                                                                                                                            |
| Grok                  | `~/.grok/sessions/`                                                                                                                                                     |
| Hermes Agent          | `~/.hermes/sessions/`                                                                                                                                                   |
| iFlow                 | `~/.iflow/projects/`                                                                                                                                                    |
| Kilo                  | `~/.local/share/kilo/`                                                                                                                                                  |
| Kimi                  | `~/.kimi/sessions/`                                                                                                                                                     |
| Kiro CLI              | `~/.kiro/sessions/cli/`、`~/.local/share/kiro-cli/`                                                                                                                     |
| Kiro IDE              | `~/Library/Application Support/Kiro/`（macOS）                                                                                                                           |
| MiMoCode              | `~/.local/share/mimocode/`                                                                                                                                              |
| Mistral Vibe          | `~/.vibe/logs/session/`                                                                                                                                                 |
| OpenClaw              | `~/.openclaw/agents/`                                                                                                                                                   |
| OpenCode              | `~/.local/share/opencode/`                                                                                                                                              |
| OpenHands CLI         | `~/.openhands/conversations/`                                                                                                                                           |
| OhMyPi                | `~/.omp/agent/sessions/`                                                                                                                                                |
| Pi                    | `~/.pi/agent/sessions/`                                                                                                                                                 |
| Piebald               | `~/.local/share/piebald/`                                                                                                                                               |
| Posit Assistant       | `~/.posit/assistant/workspaces/`                                                                                                                                        |
| Positron Assistant    | `~/Library/Application Support/Positron/User/`（macOS）                                                                                                                  |
| QClaw                 | `~/.qclaw/agents/`                                                                                                                                                      |
| Qoder                 | `~/.qoder/projects/`、`~/.qoderwork/projects/`                                                                                                                          |
| Qwen Code             | `~/.qwen/projects/`                                                                                                                                                     |
| QwenPaw               | `~/.copaw/workspaces/`、`~/.qwenpaw/workspaces/`                                                                                                                        |
| Reasonix              | `~/.reasonix/`、`%APPDATA%\\reasonix\\`（Windows）                                                                                                                       |
| VSCode Copilot        | `~/Library/Application Support/Code/User/`（macOS）                                                                                                                      |
| Visual Studio Copilot | `%LOCALAPPDATA%\\Temp\\VSGitHubCopilotLogs\\traces\\`（Windows）、`~/Library/Caches/VSGitHubCopilotLogs/traces/`（macOS）、`~/.cache/VSGitHubCopilotLogs/traces/`（Linux） |
| Windsurf              | `~/Library/Application Support/Windsurf/User/`（macOS）、`~/.config/Windsurf/User/`（Linux）、`%APPDATA%\\Windsurf\\User\\`（Windows）                                     |
| Warp                  | `~/.warp/`（因平台而异）                                                                                                                                         |
| WorkBuddy             | `~/.workbuddy/projects/`                                                                                                                                                |
| ZCode                 | `~/.zcode/cli/db/`、`~/.zcode/cli/`                                                                                                                                     |
| Zed                   | `~/Library/Application Support/Zed/`（macOS）                                                                                                                            |
| Zencoder              | `~/.zencoder/sessions/`                                                                                                                                                 |

Grok 会话从 `summary.json`（标题、时间戳、项目）读取，可选的 `signals.json`（token 计数器），以及存在时的 `chat_history.jsonl` 用于完整转录（用户轮次、助手回复、思考过程和工具调用）。若缺少 `chat_history.jsonl`，AgentsView 会回退到仅摘要模式。设置 `GROK_DIR` 或 `grok_dirs` 可覆盖默认目录。

每个目录均可通过环境变量覆盖。详见[配置文档](https://agentsview.io/configuration/))。Cursor 归因统计默认从 `~/.cursor/ai-tracking/ai-code-tracking.db` 进行实时的、本机本地读取，并可通过 `AGENTSVIEW_CURSOR_ATTRIBUTION_DB` 重定向；它们不会通过 PostgreSQL 同步或聚合。

### Aider：按仓库的 Markdown 日志

Aider 没有中央会话存储；它为每个仓库写入一个 `.aider.chat.history.md` Markdown 日志，单个日志会累积多次运行（每次 `aider` 启动对应一次，以 `# aider chat started at ...` 标头分隔）。agentsview 将**每次运行索引为独立会话**。

AgentsView 默认不会扫描 Aider 日志。早期版本曾尝试对主目录进行始终开启的有界扫描，但并不可靠：桌面启动和后台使用刷新仍可能触发 macOS 对受保护文件夹的隐私提示。要启用 Aider，请将 `AIDER_DIR`（或 `aider_dirs` 配置键）指向你明确希望扫描的代码根目录。扫描在每个已配置根目录下最多向下深入四层，按名称跳过 vendor/build/VCS 目录（`node_modules`、`target`、`.git`、`Library`、`go`、`.cargo` 及类似目录），并在两秒墙钟时间预算后停止。在 macOS 上，宽泛的主目录根仍会跳过受保护的顶层文件夹，除非直接配置了其中某个文件夹。实时文件监视器仅浅层监视已配置的 Aider 根目录；新仓库由定期同步拾取，该同步每 15 分钟运行一次。

由于格式源自 Markdown，角色从行前缀重建，且没有逐条消息的时间戳；运行的开始时间来自其 `# aider chat started at ...` 标头（以本地时间写入，假定为 UTC）。

### JetBrains Copilot（通过导出器）

JetBrains IDE 将 Copilot 聊天存储在 Nitrite 数据库中，agentsview 不会直接读取。当前支持的路径是先用 [copilot-jetbrains-exporter](https://github.com/MCBoarder289/copilot-jetbrains-exporter), 将这些会话导出为 Copilot JSONL，然后将 agentsview 指向该输出目录。

```bash
# Export JetBrains Copilot sessions to JSONL
copilot-jetbrains-exporter --output ~/.copilot/jetbrains-sessions

# Tell agentsview to index the exported sessions
export COPILOT_DIR=~/.copilot/jetbrains-sessions
```

或在 `~/.agentsview/config.toml` 中：

```toml
copilot_dirs = ["~/.copilot/jetbrains-sessions"]
```

若希望 agentsview 从该来源拾取新对话，请在新的 JetBrains Copilot 会话后重新运行导出器。

### Antigravity CLI：高分辨率转录

Antigravity CLI 会话以两种磁盘格式出现：较新版本将对话轨迹存储为 SQLite `.db` 文件，较旧版本使用 AES-GCM 加密的 `.pb` 文件。无论哪种格式，完整转录——结构化的工具调用、结果、推理和 diff——均来自 `<uuid>.trajectory.json` 侧车文件。若无覆盖的侧车文件，agentsview 会回退到**摘要模式**：对原始 `.db` 步骤进行启发式解码（仅提示词和工具调用名称），或对 `.pb` 会话，显示来自 `history.jsonl` 的提示词以及 `brain/` 下的任何纯文本产物（计划、演练、检查点）。摘要模式会话在详情页眉显示链接到本文的「Summary mode」徽章。

要为 `.db` 和 `.pb` 会话 alike 解锁完整转录，请在 agentsview 旁运行 [agy-reader](https://github.com/mjacobs/agy-reader)。agy-reader 与本地 Antigravity 守护进程通信，解密每次对话，并在源文件旁写入 `<uuid>.trajectory.json` 侧车文件。agentsview 的文件监视器会自动检测侧车文件并就地解析，替代摘要模式——无需重启 agentsview。

```bash
go install github.com/mjacobs/agy-reader@latest

# Generate sidecars for existing sessions...
agy-reader --sync

# ...or keep them fresh as you work.
agy-reader --watch
```

agy-reader 通过解析 `~/.gemini/antigravity-cli/cli.log` 自动发现 Antigravity 守护进程 URL。若发现失败（例如日志已轮转），命令会打印特定于平台的说明，用于定位端口并手动导出 `ANTIGRAVITY_DAEMON_URL`。

侧车文件保留在你的机器上。agentsview 不会发起出站请求来生成或读取它们，并将侧车文件视为不受信任的结构化输入——信任模型见 [SECURITY.md](SECURITY.md)。

## PostgreSQL 同步

将会话数据推送到共享 PostgreSQL 实例，供团队仪表板使用：

```bash
agentsview pg push             # push local data to the default PG target
agentsview pg push archive     # push to one named PG target
agentsview pg push --all       # push every configured PG target sequentially
agentsview pg status           # show status for the default PG target
agentsview pg status archive   # show status for one named PG target
agentsview pg status --all     # show status for every configured PG target
agentsview pg serve            # serve web UI from the default PG target (read-only)
```

单目标配置仍使用旧版 `[pg]` 块。要管理多个 PostgreSQL 目标，请定义命名的 `[pg.NAME]` 块，并在存在多个目标时设置 `default_pg`：

```toml
default_pg = "work"

[pg.work]
url = "postgres://user:pass@work-db/agentsview"
machine_name = "laptop"

[pg.archive]
url = "postgres://user:pass@archive-db/agentsview"
machine_name = "laptop-archive"
exclude_projects = ["scratch"]
```

命名目标名称不区分大小写进行规范化。`all`、`local` 以及旧版 `[pg]` 字段名 `url`、`schema`、`machine_name`、`allow_insecure`、`projects` 和 `exclude_projects` 不能用于 `[pg.NAME]`。

`AGENTSVIEW_PG_URL`、`AGENTSVIEW_PG_SCHEMA` 和 `AGENTSVIEW_PG_MACHINE` 仍然可用，但在命名目标模式下它们仅应用于有效默认目标。它们不会重写每个命名的 `[pg.NAME]` 条目。

### 自动推送（后台服务）

要在无需手动运行 `pg push` 的情况下保持共享 PostgreSQL 数据库为最新，请运行自动推送守护进程。它会监视你的会话目录，并在记录新会话后不久推送，并以定期下限作为安全网：

```bash
agentsview pg push --watch                 # foreground, Ctrl-C to stop
agentsview pg push archive --watch         # watch one named PG target
agentsview pg push --watch --debounce 1m   # custom coalesce window
agentsview pg push --watch --interval 5m   # custom floor interval
```

除非你传入一个目标名称，否则 `--watch` 遵循默认 PG 目标。`--all --watch` 会被拒绝；多目标后台监视目前仍不在范围内。

守护进程读取与 `pg push` 相同的 `[pg]` 配置，因此必须在配置文件中（或其展开的环境变量中）设置 PostgreSQL DSN。请保护配置文件，因为它包含凭据：

```bash
chmod 600 ~/.agentsview/config.toml
```

要以 OS 服务方式无人值守运行（macOS 上使用 launchd，Linux 上使用 `systemd --user`）：

```bash
agentsview pg service install     # generate the unit, enable + start it
agentsview pg service status      # show manager status
agentsview pg service logs -f     # follow the service log
agentsview pg service uninstall   # stop and remove
```

`pg serve` 和 `pg service` 始终使用有效默认 PG 目标。在命名目标模式下，设置 `default_pg` 以选择这些长期运行命令使用的目标。

**Linux 无头机器：** 除非为你的用户启用了 lingering，否则 systemd `--user` 服务会在注销时停止，且不会在启动时自动启动。`install` 会检测此情况并打印命令；你也可以自行运行：

```bash
loginctl enable-linger "$USER"
```

请参阅 [PostgreSQL 文档](https://agentsview.io/postgresql/) 了解安装与配置。

## DuckDB 镜像与 Quack

DuckDB 支持是一种镜像后端，不能替代本地 SQLite 归档。`agentsview serve` 仍负责向 SQLite 执行主摄取。当你需要可移植的分析文件、从镜像进行只读本地服务，或通过 DuckDB 的 Quack 协议进行远程只读访问时，可使用 DuckDB。

```bash
agentsview duckdb push          # mirror SQLite into DuckDB
agentsview duckdb status        # show mirror sync status
agentsview duckdb serve         # serve web UI from DuckDB (read-only)
agentsview duckdb quack serve   # expose the local DuckDB file over Quack
```

`agentsview duckdb serve` 会读取 `[duckdb].path` 或 `AGENTSVIEW_DUCKDB_PATH`。要从远程 Quack 端点提供服务，请改为设置 `AGENTSVIEW_DUCKDB_URL` 和 `AGENTSVIEW_DUCKDB_TOKEN`。Quack 仍是较新的 DuckDB 协议，因此 agentsview 采用保守默认值：本地 Quack 服务绑定到 loopback、要求 token，并拒绝非 loopback 的纯 HTTP，除非明确设置 `--allow-insecure`。远程使用时，优先使用 TLS URL，或将 Quack 置于经身份验证的隧道/代理之后。

后端模式：

- SQLite：主要本地归档，支持文件同步、FTS5 搜索和可写 UI。
- PostgreSQL：可选的共享团队后端；从 SQLite 推送，只读提供服务。
- DuckDB：可选的镜像文件或 Quack 端点；从 SQLite 推送，只读提供服务。

故障排查：

- 如果 `duckdb push` 无法打开镜像，请确认二进制文件已针对你的平台使用 DuckDB Go 驱动构建，且 `AGENTSVIEW_DUCKDB_PATH` 指向可写的文件位置。
- 如果 Quack 命令因扩展错误失败，请更新 agentsview 二进制，使内嵌的 DuckDB 运行时包含 Quack 扩展。
- 如果远程 attach 失败，请检查 token、`quack:` URL、TLS/代理终止，以及服务器是否有意使用 `--allow-insecure` 以进行纯非 loopback 绑定。
- DuckDB 搜索目前使用子字符串/正则表达式回退行为。SQLite FTS5 仍是主要本地服务的索引搜索路径。

## 隐私

agentsview 在服务器启动时以及运行期间每 24 小时，会向 PostHog 发送一次有限的匿名 `daemon_active` 遥测 ping，并使用稳定的随机安装 ID 作为事件 `DistinctId`。事件包含 `application=agentsview`、应用版本、commit、操作系统和 CPU 架构，以及 `$process_person_profile=false` 和 `$geoip_disable=true`。不包含会话、项目、提示词、文件路径、账户或机器身份信息。可使用 `AGENTSVIEW_TELEMETRY_ENABLED=0` 或 `TELEMETRY_ENABLED=0` 禁用遥测。无论在何种环境下，Go 测试二进制中也会硬性禁用遥测。

所有会话数据均保留在你的本机。服务器默认绑定到 `127.0.0.1`。更新检查为可选项，可使用 `--no-update-check` 禁用。

## 文档

完整文档见 **[agentsview.io](https://agentsview.io)**:
[快速入门](https://agentsview.io/quickstart/) --
[使用指南](https://agentsview.io/usage/) --
[CLI 参考](https://agentsview.io/commands/) --
[配置](https://agentsview.io/configuration/) --
[架构](https://agentsview.io/architecture/)

______________________________________________________________________

## 开发

需要 Go 1.26+（CGO）、Node.js 22+。

```bash
make dev            # Go server (dev mode)
make frontend-dev   # Vite+ dev server (run alongside make dev)
make build          # build binary with embedded frontend
make install        # install to ~/.local/bin
```

```bash
make test           # Go tests (CGO_ENABLED=1 -tags "fts5")
make bench-backends # compare SQLite, DuckDB, and PostgreSQL store reads
make lint           # golangci-lint + NilAway
make nilaway        # NilAway through custom golangci-lint
make e2e            # Playwright E2E tests
```

`make bench-backends` 需要 Docker。它会通过 testcontainers 启动 PostgreSQL 容器，将相同的 SQLite fixture 镜像到 DuckDB 和 PostgreSQL，并对共享的 `db.Store` 读取查询进行基准测试以作相对比较。默认 fixture 为 1,000 个会话和 64,000 条消息；可使用 `BENCH_BACKENDS_SESSIONS` 和 `BENCH_BACKENDS_MESSAGES_PER_SESSION` 进行扩展。当 Docker CLI 使用非默认套接字时，在运行基准测试前请为相应套接字导出 `DOCKER_HOST`。

通过 [prek](https://github.com/j178/prek): 在克隆后运行 `make lint-tools` 和 `make install-hooks`（需要 `prek` 和 `uv`）。

### 项目结构

```
cmd/agentsview/     CLI entrypoint
internal/           Go packages (config, db, parser, server, sync, postgres)
frontend/           Svelte 5 SPA (Vite+, TypeScript)
desktop/            Tauri desktop wrapper
```

## 致谢

灵感来自 Andy Fischer 的
[claude-history-tool](https://github.com/andyfischer/ai-coding-tools/tree/main/claude-history-tool)
以及 Simon Willison 的
[claude-code-transcripts](https://github.com/simonw/claude-code-transcripts)。

## 许可证

MIT