AgentsView：面向编码 Agent 的本地优先会话智能与分析工具

这是什么

agentsview 是一个基于 Go 语言开发的开源 AI 编程代理（AI Coding Agents）成本追踪与可视化工具。它旨在为开发者提供一站式的解决方案，用于浏览、搜索和监控所有已安装的 AI 编程代理（如 Claude Code、Codex、Forge 等）的使用情况和费用。

该项目的核心设计理念是“隐私优先”与“极简部署”：

• 本地优先：所有数据同步至本地 SQLite 数据库，无需注册账号，无需云端同步。
• 单一二进制文件：提供 macOS、Linux 和 Windows 的原生支持，也可通过 Docker 容器运行。
• 跨代理支持：自动发现并索引本机支持的各类 AI 编程代理会话数据。

解决的问题

随着 AI 编程助手在开发工作流中的普及，开发者面临着以下痛点：

1. 成本黑盒：难以准确掌握不同 AI 模型（如 Claude、GPT-4 等）在多个代理工具中的具体消耗，尤其是 token 使用量和对应的美元成本。
2. 数据碎片化：各代理工具（如 Cursor、VS Code 扩展、CLI 工具）的日志分散存储，缺乏统一的视图进行对比分析。
3. 隐私顾虑：许多现有的成本追踪服务需要上传数据到云端，存在敏感代码上下文泄露的风险。
4. 查询效率低：传统工具往往需要每次运行时重新解析原始会话文件，导致查询缓慢，无法提供实时的成本洞察。

核心功能

1. 多代理会话发现与同步

• 首次运行时，agentsview 会自动扫描本机支持的代理会话目录（如 ~/.claude/projects、~/.forge 等）。
• 将分散的会话数据同步至本地 SQLite 数据库，建立统一索引。
• 支持通过环境变量或挂载卷指定代理会话目录，特别适用于 Docker 容器化部署场景。

2. 成本追踪与计算

• 自动定价：集成 LiteLLM 费率表，自动计算 token 消耗对应的美元成本。
• 缓存感知：支持 Prompt Caching 的成本计算，区分缓存创建（cache creation）和缓存读取（cache read）的 token 成本。
• 多维度查询：
  • agentsview usage daily：查看每日成本摘要（默认最近 30 天）。
  • agentsview usage daily --breakdown：按模型细分成本。
  • agentsview usage daily --agent claude --since 2026-04-01：按代理和日期范围过滤。
  • agentsview session usage <id>：查看特定会话的 token 统计和成本估算。

3. 高级分析与统计

• agentsview stats：生成窗口期内的分析报表，包括会话总数、类型分布（自动化、快速、标准、深度、马拉松）、持续时间、用户消息数、峰值上下文窗口、每轮工具调用数等。
• Git 集成：可选地集成 Git 和 GitHub 数据，统计提交数、代码行数变更（LOC）、PR 数量等，以关联 AI 使用与代码产出。
• 输出格式：支持 JSON 输出（遵循 v1 schema），便于集成到 CI/CD 或状态栏脚本中。

4. Web UI 与 API

• Web 界面：启动 agentsview serve 后，在 http://127.0.0.1:8080 提供可视化仪表盘，包含全文本搜索（FTS5）、每日支出图表、活动热力图、工具使用趋势等。
• 实时推送：通过 SSE（Server-Sent Events）实现活跃会话的实时更新。
• REST API：提供 /api/v1/sessions/{id}/usage 等接口，返回详细的 token 使用量和成本数据。
• 键盘导航：UI 支持 j/k 导航、Cmd+K 搜索等快捷键操作。

5. 灵活部署与安全

• 本地绑定：默认绑定 localhost，并验证 Host header 以防止 DNS 重绑定攻击。
• 远程访问支持：通过 --public-url 和 --public-origin 参数支持 SSH 端口转发、反向代理或远程开发环境（如 Codespaces, WSL2）。
• 数据库后端：
  • 默认 SQLite。
  • 支持 PostgreSQL（通过 PG_SERVE=1 环境变量）。
  • 支持 DuckDB 镜像（用于高性能只读查询或远程访问）。
  • 支持 Quack 协议，可将本地 DuckDB 镜像暴露为远程端点。

亮点 / 与同类相比

• 极速查询：由于会话数据已预先索引在 SQLite 中，agentsview usage 的查询速度比每次重新解析原始文件工具（如 ccusage）快 100 倍以上。
• 零配置隐私：无需账号，数据完全本地化，解决了开发者对代码上下文泄露的担忧。
• 广泛的代理兼容性：不仅限于 Claude Code，还支持 Codex、Forge、OpenCode 等多种代理，提供统一的视图。
• 容器化友好：提供官方 Docker 镜像和 docker-compose.prod.yaml 示例，支持生产环境部署，并通过命名卷解决权限问题。
• 丰富的数据集成：除了基本的 token 统计，还可选地集成 Git 和 GitHub 数据，提供更全面的开发效率分析。

适合谁用 / 上手

适合人群

• 重度 AI 编程用户：使用多个 AI 代理工具（如同时使用 Cursor、VS Code Copilot、Claude Code CLI）的开发者，需要统一管理成本和查看使用统计。
• 注重隐私的开发者：不希望将代码上下文或会话数据上传至第三方云服务。
• 团队技术负责人：需要监控团队 AI 工具使用情况和成本分布，优化资源分配。
• DevOps 工程师：希望将 AI 使用数据集成到现有的监控或 CI/CD 流程中。

上手指南

1. 快速安装

• macOS / Linux:

  curl -fsSL https://agentsview.io/install.sh | bash
  

• Windows:

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

• Homebrew (macOS):

  brew install --cask agentsview
  

2. 首次运行

安装后，直接运行 agentsview serve。程序会自动发现本机支持的代理会话，同步数据到 SQLite，并在浏览器中打开 Web UI。

3. Docker 部署

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

注意：容器内只能访问显式挂载的代理会话目录。

4. 常用命令

• 查看每日成本：agentsview usage daily
• 查看特定会话详情：agentsview session usage <session_id>
• 生成分析报告：agentsview stats

5. 远程访问配置

如果通过 SSH 端口转发或反向代理访问，需指定 --public-url：

agentsview serve --public-url http://127.0.0.1:18080

若暴露到非本地网络，建议启用 --require-auth 以增强安全性。