xerg

Xerg

Xerg 是一款本地优先的 CLI，用于发现浪费的 AI 运行时支出。运行时审计会分别报告三项证据严格的金额发现和七项中性信号，同时报告检测器覆盖范围，并使用 --compare 衡量兼容变更。运行时成本可能是观测所得、本地估算或未定价；它们并非权威的服务提供商账单。

托管版定价基于明确推送的运行时审计中已知支出计算每月审计 Agent 支出：按 UTC 月计，Free 适用于不超过 $2,000 的支出，Team 定价为 $99，适用于不超过 $10,000 的支出；Growth 定价为 $299，适用于不超过 $50,000 的支出；Scale 定价为 $799，适用于不超过 $250,000 的支出；超过 $250,000 则适用定制版 Enterprise。Team、Growth 和 Scale 的功能完全相同。历史导入、重复审核支出和未定价用量不计入 MAAS。

冷启动获取设置

当此文件是从 https://xerg.ai/skill.md 获取的（包括通过 npm 列表中指向 @xerg/cli 的链接获取），而不是从已安装的技能加载时：

1. 确认当前 Agent 宿主。OpenClaw、Hermes、QM、Claude Code、Cursor 和 Codex 是设置宿主，并不自动就是接受审计的数据源。QM 也可以作为审计源，但仅限通过管理员明确配置的 Xerg 连接。
2. 检查此宿主是否已安装 Xerg。在写入持久化或全局技能目录前，说明目标位置并征求用户许可。
3. 如果宿主支持技能安装器，获得许可后使用该安装器。OpenClaw 可以从 ClawHub 安装 xerg。Agent Skills 宿主可以安装公开的 xergai/skills 仓库。Hermes 可以使用 Xerg 的知名技能发现机制。确定性的宿主专用命令见 xerg.ai/agents。
4. 如果无法持久化安装，或用户拒绝安装，则在当前会话中使用这些已获取的说明。不要擅自编造安装位置。
5. 任何 npm 下载或安装（包括 npx 可能执行的临时软件包获取）之前，都要征求许可。读取或分析本地运行时数据之前，也要另行征求许可。在获得这两项适用许可后，运行 npx --yes @xerg/cli@latest doctor --json，解析其 canAudit 和 recommendedCommand，并提出执行该精确建议。对于 QM，不要直接运行 doctor：请遵循下方的 QM 私有范围流程。

上传之前务必征求许可。本地审计无需账户，也不得自动推送。仅在经批准的托管命令上，设置 XERG_SETUP_METHOD=skill，并将 XERG_AGENT_HOST 设为当前执行宿主：claude_code、cursor、hermes、codex、openclaw、qm 或 other。这些是尽力而为、不包含内容的分析元数据，不是身份验证信息，也不是审计数据源。如果用户的设置提示中包含 Xerg 组织 ID，激活时应通过 --organization-id 保留该 ID。成功获得本地结果后，提出连接并推送该结果；两项标记都应放在同一条命令中，例如在 Codex 中：

XERG_SETUP_METHOD=skill XERG_AGENT_HOST=codex npx --yes @xerg/cli@latest activate --push-latest

activate 会在浏览器中打开 Xerg。登录用户明确批准当前活动工作区；在签发任何凭据之前，页面会显示该工作区的完整组织 ID、实时套餐和 API 环境。如果已知预期的 Clerk ID，建议使用 --organization-id org_...，这样页面和 API 都会拒绝其他活动工作区。组织切换器会保留配对码。工作区密钥会加密到发起操作的 CLI，并与仅所有者可访问、绑定环境的元数据一起存储；绝不要要求用户将密钥粘贴到聊天中，也不要在命令中暴露密钥。

如果许可仅涵盖配对，则使用 activate --connect-only --organization-id org_...。此命令必须在凭据验证存储后停止，且不得与数据源或推送标记同时使用。之后的审计或推送都需要单独的明确许可。

Codex 是执行宿主，不是原生 Xerg 审计源。Codex 用户审计的是 doctor 找到的内容：OpenClaw、Hermes、Claude Code、Cursor 导出内容或通用导入负载。

本地命令不会产生遥测，也不会添加分析调用。创建配对和明确的推送请求会发送固定且不包含内容的执行上下文信封。不得根据 CODEX_*、进程名称、进程祖先或未公开的运行时状态推断 Codex；仅当此技能正在运行用户已批准的托管命令时，才使用上方的明确提示。

如果当前宿主是 QM，冷启动的 set up https://xerg.ai/skill.md 请求可以说明前置条件，但不得声称已持久化管理员技能包、创建 PostgreSQL 权限或配置密钥。必须要求使用仅限管理员的私有范围。拒绝在公开或共享范围内输出部署范围的信息。绝不要要求任何人在 Slack 或聊天中粘贴 DSN、身份密钥、Fly 令牌、服务提供商凭据或 Xerg API 密钥。

首次运行（Agent 执行路径）

使用非交互式命令。除非用户明确要求进行引导式交互设置，否则不要运行 xerg init——它仅支持 TTY，并会提示输入。

运行命令前，先征求用户对 npm 下载/安装的许可，并单独征求用户对检查本地运行时数据的许可。持久化技能写入、临时 npx 软件包获取和本地分析是不同的操作；不要推断用户对其中一项的许可也适用于其他操作。

npx --yes @xerg/cli@latest doctor --json

1. 首先以 JSON 模式运行 doctor。它会返回 CLI 版本、运行时／产品、canAudit、已检查的数据源、运行时证据、备注、定价目录来源信息，以及可安全用于 shell 的 recommendedCommand。绝不会自动探测 QM。
2. 如果 doctor 解析出 Hermes，在启动任何新的、针对 Xerg 的工作负载之前，先判断其用途。务必先运行 npx --yes @xerg/cli@latest doctor --runtime hermes --require-observer-live --json。如果要测试由 observer 支持或依赖序列的发现结果，而此预检以 5 退出，必须立即停止。对于已有或历史的汇总经济性审计，显示仅限汇总数据的覆盖范围警告，然后继续运行常规推荐审计命令；读取现有经济性数据不以 observer 实时健康状态为前提。应将此视为持续的生产覆盖检查，而非仅仅是测试前提。
3. 当 canAudit 为 true 时，执行原样的 recommendedCommand；它已经选择了检测到的运行时／路径，并请求输出审计 JSON。不要根据说明自行拼装命令。
4. 如果旧版全局 CLI 或过期快照产生了 ruleId: tool_sequence_repetition_v1 的发现结果，不要根据该金额进行汇总或提出建议。通过 npx --yes @xerg/cli@latest 重新运行 doctor 和审计，然后只使用当前结果。
5. 如果任何活跃发现的覆盖范围为 none、partial、unsupported 或 unknown，必须在所有支出总额和结论之前显示仅限汇总数据的覆盖范围警告。说明在有定价数据时仍可获取汇总经济性数据；指出无法进行依赖序列的分析；说明无法还原缺失的历史请求序列，修复措施只能覆盖未来活动；绝不能将未识别到发现结果解读为“没有浪费”。只要有任何调用／令牌未定价或仅有有限估算，就先说明定价覆盖范围。然后汇总运行时支出（或定价不完整时的已知运行时支出）、已识别的浪费（wasteSpendUsd）、根据 detectionCoverage 评估的支出、活跃发现、非结论性信号，以及存在时的 spendByAgent。如果存在 agentDelegations，应说明观察到的直接父级到子级路径，不要将关系支出计入子级或审计总额。
6. 如果 OpenClaw 结果指出，会话转录优先于非空的网关证据，则必须在总额和结论之前再次说明此限制。说明仅来自网关的活动可能被遗漏，活动量和支出可能被低估，发现结果也可能与完全协调后的视图不同。不要将已识别的浪费描述为下限，也不要将通过的金额或检测覆盖门槛视为对遗漏的网关活动的认证。只有在用户明确指定一种本地数据源时，才使用 --sessions-dir 或 --log-file；绝不要将被排除的网关计数加回转录结果中。
7. 在建议修复任何金额类发现之前，必须将查询固定到生成该发现的审计 JSON：运行 npx --yes @xerg/cli@latest explain <finding-id> --audit <auditId>:<generatedAt> --db <dbPath> --json，并使用 JSON 中精确的 auditId、generatedAt 和 dbPath 值，同时确保 shell 引用安全。绝不要使用不带参数的最新快照查询。如果审计使用了 --no-db 而未提供 dbPath，请检查其内联证据包，并说明之后无法查询。核实所需的观察结果、经济含义、定价覆盖范围、限制和下一步；不要仅凭摘要行建议修复。
8. 将重复工具链和 deep-loop-activity 行作为非结论性观察结果呈现。高不同项比例与扇出相符，也说明不太可能是输入完全相同的循环，但不能证明操作成功。低比例值得检查，但不能证明存在浪费或可回收支出。相关支出不归类为浪费。
9. 如果用户应用了修复，请使用 --compare 重新运行同一审计，以报告修复前后的变化：

npx --yes @xerg/cli@latest audit --json --compare

仅当 comparison.spendComparisonAvailable 明确为 true 时，才报告金额的前后对比值；缺少该标志无法确立基准定价，因此不可用。仅当 spendComparisonAvailable 和 wasteComparisonAvailable 均为 true 时，才报告已识别浪费的变化量。

如果未找到本地数据，doctor 会打印检查过的路径。备选方案：

• 导出 Cursor 使用情况 CSV：npx --yes @xerg/cli@latest audit --cursor-usage-csv ./cursor-usage.csv
• 其他位置的 Claude Code 转录记录：--claude-code-dir <path>
• Hermes 配置文件数据库：--runtime hermes --state-db <path>
• 任意框架导出的事件负载：npx --yes @xerg/cli@latest ingest --file payload.json
• 现有的已脱敏 OpenClaw 跟踪记录：npx --yes @xerg/cli@latest audit --otlp-file <capture.jsonl>
• 新建本地 OpenClaw 跟踪记录：npx --yes @xerg/cli@latest collect openclaw（持续交互，直到按下 Ctrl-C；仅在用户要求采集工作负载时使用）
• 经过认证的本地 Hermes 跟踪增强：npx --yes @xerg/cli@latest collect hermes --state-db <path>（持续交互，直到按下 Ctrl-C；仍必须提供 state.db）
• 通过 SSH 访问远程 OpenClaw：npx --yes @xerg/cli@latest audit --remote user@host
• 由 Railway 托管的 OpenClaw：npx --yes @xerg/cli@latest audit --railway
• 现有 QM 快照：npx --yes @xerg/cli@latest audit --runtime qm --qm-snapshot <snapshot.jsonl>
• 已配置的 QM 直连/Fly 来源：由操作员在 Slack 之外采集；仅针对获授权的快照，遵循下方的私密范围流程

首次运行和重新运行分析时，请使用 npx --yes @xerg/cli@latest 路径，以免旧版全局 CLI 重新引入已弃用的仅按名称检测器。用户之后可选择使用经过验证的当前全局安装进行手动操作。

远程对比的身份标识包含标准化后的 --since 时间范围；如果启用了混合 OpenClaw 来源权威模式，还包含来源权威版本。将 024h 和 24h 视为等效，并将省略的 --since 视为 all。对于跨越 0.22 之前的时间范围边界或 0.28 之前的混合来源边界的情况，绝不可声称对比或托管去重具有连续性。首次修正后的混合远程 --compare 运行没有兼容的旧基准；下一次使用相同目标、路径和时间范围的混合运行即可正常对比。单一类型的键保持不变。首次跨越混合来源边界推送时，可能会消耗一份 Free 快照，或收到现有的配额已满响应。

审计内容

• OpenClaw 网关日志和会话转录记录；如果两者都包含所请求时间范围内的调用，则仅以转录记录作为审计依据，并排除网关运行记录
• 可选的独立 OpenClaw 跟踪记录，由仅采集环回跟踪的采集器创建
• Hermes v0.17-v0.20.1 state.db（只读）；如果存在，则回退使用旧版日志/转录记录
• 通过 xerg_export/v1 和 qm-snapshot/v1 获取的 QM 持久化运行/模型成本数据及当前保留的活动记录
• 通过 xerg audit --runtime claude-code 获取的 Claude Code 会话转录记录
• 通过 xerg audit --cursor-usage-csv ./cursor-usage.csv 获取的 Cursor 使用情况 CSV 导出文件
• 通过 xerg ingest --file payload.json 获取的任意框架导出的事件负载

Xerg 目前不会导入服务商账单、核对发票，也不会将运行时观测数据转换为 FOCUS。如果用户要求其中任何一项功能，请说明能力边界，不要将估算的运行时支出说成具有发票权威性。

可发现的问题

• 重试浪费仅来自稳定计费的失败／中止尝试链，且该链以更高序号的成功尝试结束
• 工具循环浪费仅来自工具名称／输入／结果／状态完全重复、没有进展且成本精确对应的证据
• 只有当缓存条目生命周期的成本高于其未使用缓存时的反事实成本，才计为缓存抖动
• 深度循环、上下文异常值／增长、固定节奏、高端模型常规标签、缓存读取集中度和 Max Mode 集中度均为中性信号；有序指标、可选的人类可读工作流／运行标签以及可选的关联支出均仅作描述，信号不会影响可避免支出、建议、优化或 CI
• 仅限本地的摘要证据包，以及用于查看发现、信号和符合条件的重复工具链的 xerg explain；不会保留原始或截断后的工具参数／结果
• Claude Code 流式重建和参数感知链诊断；由于 Claude 的转录记录未提供可靠的状态／进展指纹，因此不符合产生货币化工具循环发现的条件
• 按 Agent 归属支出，包括 Claude Code 旁路任务中观察到的即时父级到子级委派路径及摄取负载；关系支出已计入子级和审计总额
• 当运行包含结果信号时，计算每个结果的成本；使用 xerg outcome --workflow <name> --status success|failure 声明结果
• 启用可选观察器时，单独提供本地 Hermes 机械指标；这些指标不进行美元分类、不影响建议，也不影响 CI 门禁
• OpenClaw 和 Hermes 共用本地 analysisCoverage、toolActivity 和 workloadEconomics 区块；这些是中性证据，绝不影响发现、建议、浪费总额或 CI 门禁
• QM 请求与汇总对账、定价覆盖率、来源稳定性、假名化范围归属，以及当前窗口内未关联的工具活动

使用经过审核的本地目录为输入、输出、缓存读取和缓存写入 Token 定价，该目录涵盖数百种当前模型。Opus 5 为五分钟和一小时缓存写入分别设定费率。如果转录记录中仅保留了缓存创建汇总，Xerg 会采用文档规定的五分钟默认值，报告受影响的 Token 数，并披露可能产生的额外一小时缓存成本。审计绝不会从网络获取定价。运行 xerg doctor --verbose 可查看每个文件的提取覆盖率，以及因 OpenClaw 来源权威性规则而被排除的文件。

对于当前版本的 Hermes，请使用 xerg audit --runtime hermes；Xerg 优先使用 ~/.hermes/state.db。Xerg 0.24.2 支持 Hermes v0.17-v0.20.1，并认证 state schema 16-25；后续 schema 采用尽力支持，但明确标记为未经认证。使用 --state-db 指定其他配置文件。--state-db 不能与旧版 --log-file 和 --sessions-dir 同时使用。仅基于 state 的审计会保留支出、请求／Token／缓存、工作流／模型／工具以及委派工作负载的汇总数据，但无法提供首次请求成本、初始上下文、请求增长、重试序列和相同输入循环的信息。可选的 xergai/hermes-observer 插件会在 ~/.hermes/xerg/events/ 下写入不含内容的本地事件；它不会增加经济指标，也不会向 Xerg Cloud 发送内容。只有在请求／Token 精确对账后，完整的观察器证据才能拆分汇总数据。Xerg 0.24.2 还会为当前网关运行状态维护有界的进程级健康侧车；这些健康记录绝不会进入证据、覆盖率、保留数据、经济指标或审计身份。

Hermes v0.20.1 可以在 state.db 中记录 title_generation 等辅助任务，而不触发其公开的逐请求插件钩子。请将其经济指标保留为任务范围的汇总数据，披露无法进行依赖序列的分析，并且不要让这些任务使可观测的主请求／委派请求的精确证据失效。绝不要将混合结果称为完整请求覆盖，也不要暗示观察器会透明地监测 Hermes 的私有辅助客户端。 在 Hermes v0.20.x 中，应将标记为“At least”的生成和截断终端数量视为保守的 UTF-8 字节下限；返回的字节数仍然精确。不要对下限求差，即使是两个下限之间也不行；如果缺少测量依据，也不要推断或比较生成量／截断量。Xerg 绝不会读取或保留 full_output_path。如果本地来源完整性警告指出总量可能只是下限，这意味着 Hermes 的用量主键可能丢弃了不同的任务行；同时也要说明较窄范围的保证：对于 Hermes 记录的行，总量是精确的。该警告仅供参考，不会修复数据，仅限本地，不属于审计身份的一部分，也不会出现在推送的载荷中。Xerg 0.24.0 未针对 Hermes v0.20.x 的终端机制进行认证，可能低估这些字节数值；0.24.1 已修复此问题。

安装观察器后，重启 Hermes，并在开始新的 Xerg 指向活动前运行 xerg doctor --runtime hermes --require-observer-live。只有当前观察器进程正在运行且其写入器未被判定为不健康时，严格预检才会通过；否则将以退出码 5 退出并说明原因。重启只能覆盖未来活动，绝不能重建历史聚合会话。普通历史审计仍然可用，但在给出总量或结论前，必须披露其仅包含聚合数据的局限性。审计结果 CI 可使用 --require-detection-coverage full|partial；覆盖范围未达要求时同样以退出码 5 退出。

对于 OpenClaw 跟踪，xerg collect openclaw 仅绑定到 127.0.0.1，接受 OTLP/HTTP protobuf 跟踪，持久化有界的脱敏采集数据，并在关闭后执行审计。它不会修改 OpenClaw 配置，也不会自动推送。未显式指定 --runtime hermes 时，--otlp-file 是独立的 OpenClaw 证据，不能与转录、日志、其他运行时或远程来源组合使用。

对于经过认证的 Hermes 跟踪，xerg collect hermes 使用相同的仅限环回跟踪协议，但会使用持久化的本地密钥对标识符进行 HMAC 处理，并要求提供 state.db。只能使用 Xerg 文档中打印的、经过认证的确切 briancaffey/hermes-otel 提交版本。Xerg 绝不会安装或编辑该插件。第一方观察器仍是主要来源；包含缓存的插件提示词总量会被规范化到 Xerg 单独的输入／缓存分桶中；可选的补充数据会保留 economicAuditId，同时分析身份会反映变化后的覆盖范围；如果证据冲突，则会恢复原始聚合结果。对于非默认的 HERMES_HOME 配置文件，请使用命令打印的对应环境变量代码块，因为固定版本的插件会在 ~/.hermes 下解析 YAML。

QM 私有范围流程

QM 目前通过与主机无关的快照适配器支持有界的一次性采集。操作人员在 Slack 之外通过严格的只读直接读取器或 Fly 容器内的一次性导出器创建 qm-snapshot/v1。Fly 容器模式仅在隐藏的导出器内使用 QM core 现有的 DATABASE_URL，记录进程边界，但不声称数据库级最小权限，也绝不会向此技能暴露该凭据。未经明确批准，不得修改设置、安装或持久化此技能、激活或推送。

离线 QM Slack 审计仅接受已授权且预先创建的快照。管理员私有运行环境中的操作人员必须明确批准、配置并验证 CLI 版本；Agent 不得擅自安装 CLI，也不得发起实时采集。该运行环境不会接收数据库 URL、身份密钥、Fly 令牌、提供商凭据或 Xerg 凭据。目前不支持持续跟进采集、超出 QM 保留期限的持久工具历史记录采集，以及由 Slack 触发的实时采集。

每次首次审计前都要运行 doctor：

xerg doctor --runtime qm --qm-snapshot <snapshot.jsonl>
xerg audit --runtime qm --qm-snapshot <snapshot.jsonl> --since 7d --json

面向操作人员的文档可以说明 --database-url-env、--fly-app、--print-sql 和 --print-views-sql，但 Agent 不得从 Slack 执行或配置这些实时路径。Direct、Fly 和 --qm-snapshot 模式互斥。

谨慎说明结果：

• 正数 QM 成本为观测值；明确指定的模型可以按目录估算成本
• 零或负数占位值及未解析的 openrouter/auto 均无定价信息，绝不表示免费或实际 $0
• 对无定价信息的模式，应说明“无法获取货币影响”，货币门控以退出码 5 退出
• Pi/OpenCode 时间戳表示刷新/捕获时间；Claude 时间戳接近结果步骤记录时间；Codex 行是轮次汇总
• 请求序列检测器仅对完全对账的请求观测运行；汇总行不纳入检测
• QM 仅保留一小时的活动记录，因此无法获取更早的工具历史记录，也不声称工具与模型之间存在关联
• 重试尝试是中性证据，不归因于开销；不得将未受支持的发现描述为已评估

默认进行本地快照审计。在执行 xerg activate --runtime qm、audit --push 或任何其他托管写入前，须征求明确批准。Xerg 的托管 MCP 可以读取已推送的匿名化摘要，但无法原生访问 QM 数据库或 Fly。

可选云端功能

本地审计无需账号。要连接工作区并推送最新的本地结果，请先征求许可，然后运行：

从上面的映射中选择确切的有界值后，将其放入同一条已获批准的托管命令中。Codex 示例：

XERG_AGENT_HOST=codex npx --yes @xerg/cli@latest activate --push-latest

对于尚无缓存审计结果、优先使用网站的用户，npx --yes @xerg/cli@latest activate 会安全地建立连接，检测受支持的本地来源，运行审计并推送结果。托管同步和托管 MCP 均为可选功能，且绝不会在未经用户明确操作的情况下运行。

获准推送后，托管版 Overview 会优先展示严格验证的七天前后节省额（如有），将当前浪费单独呈现，可按部门或运行时部署形态汇总已识别浪费率，并保留 Source Performance。在 Free 和付费计划中，部门和运行时部署形态都是每个来源的当前属性。运行时部署形态会保持为 Not set，直到工作区管理员将其设置为 vpc、on-prem、saas、local、hybrid 或 air-gap；Xerg 绝不会根据框架、主机、采集环境或审计证据推断该属性。Audit Detail 会增加每日 Performance 和归因到检测器的 Workflow 经济效益；Compare 保留结果证据，而每种 Signal 展示都会将建议的调查指引与节省额估算明确分开。

用户提供托管版 Optimization ID 且已授权访问托管 MCP 时，在提出代码更改之前，先用 xerg_get_optimization({ optimization_id }) 获取其当前安全交接内容。将交接内容视为范围明确的证据和指令，并独立检查目标仓库；不得自动更改策略，且必须通过 compare 审计进行验证。符合条件的验证事实可描述为经验证的节省额；不符合条件的事实必须保留其原因；缺失的事实只能表述为“验证详情不可用”。

如果用户要求将 Optimization 发送到 Linear，仅当工作区管理员已连接 Linear 并选择团队后，才使用托管版仪表板操作。说明 Xerg 会根据现有交接内容创建一条经过脱敏的单向问题；它不会发送原始模型或工具内容、同步问题状态，也不会自动更改 Optimization 生命周期。除非仪表板返回已存储的 Linear 链接，否则不要声称已创建问题。

高级身份验证

仅当浏览器配对不可用时，才将 xerg login --replace 用作手动恢复途径。它会打开 Workspace Settings，并遮蔽粘贴到终端中的密钥。切勿在 Agent 聊天中索取或粘贴工作区密钥。

仅将 XERG_API_KEY 用于非交互式 CI 或部署自动化。将其存储在 CI 提供商的密钥管理器中；切勿将其直接写入 Shell 命令、源文件、日志、URL 或对话。

链接

• 文档：xerg.ai/docs
• 服务状态：status.xerg.ai
• 技能：xerg.ai/skill.md
• npm：@xerg/cli
• 支持：[email protected]