AgentsView 可以把多种工具的编程代理会话日志汇总到一个可搜索的本地归档库中。本指南面向需要找到一项已知任务、查看代理实际记录的用量字段，并确认每个费用数字来源的工程负责人。

这份操作说明以 AgentsView 于 2026 年 10 月 9 日发布的 v0.45.0 版本及当前的快速入门、词元用量指南为依据；文档于 10 月 17 日查阅。BIG CHANGE 并未安装 AgentsView、导入会话记录或测试这些步骤。请核对实际安装的版本，因为文档和版本列表可能变化。

开始之前

你需要一个已完成且获准读取的编程代理会话、该任务中特有的短语或会话 ID，以及读取其本地日志目录的权限。Quick Start列出了 macOS、Windows 和 Linux 的桌面版下载，CLI wheel 支持 Linux x86_64 和 aarch64、macOS x86_64 和 arm64，以及 Windows x86_64 和 arm64。桌面应用已打包；从源代码构建另有 Go、Node 和 CGO 要求。根据快速入门文档，基本的本地归档不需要托管服务账户或 API 密钥。

会话日志可能含有提示词、源代码、工具输入和机密。只选择团队允许你检查的目录。请决定归档库可以采集哪些提供方和根目录，并在首次启动之前完成设置：直接运行 agentsview serve 就会立即发现并同步默认支持的来源。这次操作请让网页界面保持在文档指定的回环地址。不要只为回答这个问题，就启用托管的原始数据同步、向 PostgreSQL 或 ClickHouse 推送、发布到 Gist、生成洞察或托管的嵌入端点。语义搜索是可选功能；普通全文搜索使用本地索引即可。

1. 安装并确认可执行文件

从安装指南中选择一种方式。若使用独立 CLI，文档列出的永久 Python 安装方式如下：

Terminal
pip install agentsview
agentsview --version

指南也提供 uvx agentsview，用于无需永久安装的运行方式，另有各平台安装程序和桌面软件包。在 macOS 上，Homebrew cask 会链接应用内附的 CLI；通过 DMG 安装的应用可能需要把 CLI 目录加入 PATH。相信版本信息之前，先确认 shell 找到的是哪个可执行文件。GitHub 将 v0.45.0 标为 10 月 9 日的版本，但解读界面和报告结构时，请以自己运行 --version 得到的结果为准。

2. 在首次同步之前限制来源

若在主机安装 CLI 或桌面版，请将全新的数据目录及其 config.toml 先准备好，再启动 AgentsView。配置指南说明如何使用 disabled_agents 排除本地文件系统提供方，以及用 [agents.<id>].dirs 替换某个提供方的默认根目录。请找出所有其他提供方的 ID（见该指南的Session Discovery 表），并将它们列入 disabled_agents，再把唯一获准提供方的 dirs 设为批准的根目录。例如，[agents.codex] 搭配 dirs = ["/approved/codex/sessions"] 会替换 Codex 的默认目录；请根据自己的系统调整路径。如果没有完整的排除列表，先不要启动主机守护进程。单独覆盖 CODEX_SESSIONS_DIR 或 CLAUDE_PROJECTS_DIR 只会改变该提供方的根目录，其他提供方仍可通过自身的默认方式被发现。

如果现有归档库可能已包含无关会话，这次审核请使用全新的 AGENTSVIEW_DATA_DIR。配置指南指出，已禁用提供方以前归档的会话仍然可用，因此改变设置不会清空旧归档库。指南还指出，disabled_agents 管理的是本地发现和监视，不包括远程导入或导出；这项本地任务请不要配置远程主机和导出目的地。

如果维护排除所有其他提供方的列表并不现实，可以改用隔离容器。Quick Start 的 Docker 示例只在 127.0.0.1 发布界面，以只读方式挂载一个代理来源，并使用独立的数据卷。请只挂载获准来源的根目录，在全新容器内设置对应的目录变量，并省略项目的 Compose 示例中的其他挂载。容器只能看到明确挂载的主机会话目录。已发布的 Docker 镜像支持 Linux amd64 和 arm64；这条路径需要能够正常工作的 Docker 安装。

3. 建立本地归档库

若使用已限制来源范围的主机 CLI，启动文档中的前台服务器：

Terminal
agentsview serve

在第 2 步应用并检查来源范围之后，这会初始化 ~/.agentsview/sessions.db（或选定的数据目录），发现已启用代理的日志、同步、监视变更，并打开 http://127.0.0.1:8080。请保持该终端打开。如果更喜欢后台进程，可以使用 agentsview daemon start 和 agentsview daemon status；桌面应用会管理自己的后端。若已有兼容的服务器正在运行，可能只会返回其 URL，因此请先检查是否已有运行中的守护进程，再认定新配置控制了数据采集。

若选择隔离容器，请先检查其唯一的只读来源挂载和全新数据卷，再通过文档中的 Docker 命令启动。使用该容器的回环界面，并在同一容器内运行后续的 agentsview CLI 报告，确保读取同一归档库。不要同时在主机运行未限制来源范围的 serve。

确认已知任务的来源出现，而非预期提供方没有出现。若找不到会话，请先检查批准的路径、提供方设置和同步状态，再推断会话不存在。如果报告需要纳入刚修改的文件，请运行 agentsview sync；服务器也会监视变化。任何完整重新同步之前，都要再次检查配置的范围。

4. 找到任务并核实会话记录

在网页界面使用 Ctrl/Cmd+K 搜索已知任务中特有的原文短语。按项目、代理或日期缩小列表范围，打开候选结果并检查消息和工具调用。如果已有完整会话 ID 或 UUID，Ctrl/Cmd+G 可以直接打开。这些操作方式见 Quick Start。请记录代理、会话 ID 和日期，以便把用量结果关联到正确的对话。

若原文短语搜索找不到任务，试试较短的短语，并确认原代理确实把本地会话记录写入了 AgentsView 可读的目录。只存在于远程服务、不支持的格式，或配置根目录以外的任务，不会因为更努力搜索就被找回。不要把启用语义索引或上传会话记录当作本地来源缺失的常规解决办法。

5. 检查会话用量字段

打开找到的会话用量视图，识别其中已记录且存在的模型、输入、输出、缓存创建和缓存读取字段。词元用量指南将费用报告标为实验性且仍在发展中。AgentsView 从来源日志采集模型和词元元数据，并在消息行中保留原始词元用量。如果来源明确报告了费用，就使用该数字；否则根据可用词元和模型费率计算费用。JSON 的来源标记将这些情况称为 reported、computed 或 mixed。

若想保存该单一会话的机器可读记录，项目的 CLI 示例使用 agentsview session usage SESSION_ID --format json。请将 SESSION_ID 替换为在会话记录中核实的 ID，再将 JSON 与任务笔记一并保留。引用任何总额之前，先检查输出中报告的模型、词元分类和费用来源。

空白字段或缺失的模型应视为未知。AgentsView 无法重建代理从未记录的用量。版本说明指出，Junie CLI 采集不包括只存在于 IDE 中的对话和工具调用，而 Antigravity 的纯文本备用方式只有会话内容，没有词元用量或费用。这些具体例子说明，可搜索的会话未必有完整的支出数字。来源报告的金额也可能是整场会话的总额，而按模型分摊的金额仍是估算。

6. 限定单日报告范围

使用 Usage 页面的日期、项目和代理筛选器，查看会话所在的那一天。该页也有 Top Sessions by Cost 表格，可以连回各个会话记录。若要得到可审核的终端报告，请在下列命令中代入会话的本地日期和代理名称：

Terminal
agentsview usage daily --since YYYY-MM-DD --until YYYY-MM-DD --agent codex --breakdown

单日表格会分别显示未缓存输入、输出、缓存创建和缓存读取；设置 --breakdown 时会出现各模型的行。日期默认按系统时区归类，除非提供 --timezone。单日总额可能包含该代理的其他会话；它只能用于检查范围和量级，不是那一项任务的费用。请在单日报告旁保留会话 ID，并核对哪些行实际属于它。

若要生成不获取价格目录的报告，请加上 --offline。AgentsView 指出，这会读取现有归档库，不会同步来源或启动守护进程，并使用内置的备用价格。如果近期会话变化很重要，请先更新归档库；离线报告无法发现新日志。普通用量命令可能获取 LiteLLM 和 OpenRouter 价格，内置目录则会随着安装版本逐渐过时。

7. 解读数字并停止服务

请根据各数字的来源加上标记。Computed 表示 AgentsView 将已记录的词元乘以选定费率。Reported 表示来源提供了明确费用。Mixed 表示报告混合了不同类型。即使是来源报告的数字，也不代表已经核对了整个账户的供应商账单。请独立比对相关供应商的实际账务或套餐记录，尤其在服务层级、折扣或订阅额度很重要时。AgentsView 文档指出，若保存的用量没有记载该层级，就无法推断 Batch、Flex、Priority、区域或一小时缓存费率。部分工具端词元不会出现在本地会话记录中。

成功的检查结果，是找到的会话记录在代理、ID 和日期上都与选定用量视图一致，并记录可获取的模型和词元字段，把无法获取的字段标为未知。结果是可搜索的本地归档库及范围明确的任务／单日用量笔记，不是账单。要停止前台 agentsview serve，请按 Ctrl+C；要停止后台服务器，请使用 agentsview daemon stop。Quick Start指出，停止守护进程会同时停止网页界面和会话监视。

大变化

本地会话记录为费用讨论提供了可追溯的起点。工程负责人可以把数字追溯到特定已记录的任务，看出它来自代理还是价格目录。日志不完整时，报告应保留这个缺口。

来源与延伸阅读