> [!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）的费用。单个二进制文件，无需账号，一切本地运行。

## 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 读取 `/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 ` 会打印单个会话的按会话 token 统计以及成本估算。输出会报告该会话的总输出 token 数与峰值上下文 token 数，并在会话所用模型（`has_cost`）提供定价信息时给出以 USD（`cost_usd`）计的成本估算。成本在内部根据输入/输出与缓存 token 计算，但对外仅与成本一并报告输出 token 与峰值上下文总量。 ```bash # Print token usage and cost for a specific session agentsview session usage # JSON output for scripting agentsview session usage --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 ` 仍保留以兼容旧用法，且现在也会报告成本估算。 ## 会话统计 `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 ``` ## 会话浏览器 | 仪表盘 | 会话查看器 | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | |  |  | | 搜索 | 活动热力图 | | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | |  |  | - **全文搜索** — 覆盖所有消息内容（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 | `/.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——均来自 `.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 守护进程通信，解密每次对话，并在源文件旁写入 `.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