Skip to content

指标、上报与仪表盘 ​

文档导航 · 故障排查

Wenext-Pi 记录任务、阶段、模型、技能和质量执行事实,使用本地持久队列上报。采集和传输失败不会改变任务批准、检查结果或归档决定。CLI 提供生产端;接收 API、数据库与仪表盘由独立的 wenext-offline-platform 提供。

配置 ​

默认无需配置文件,使用以下设置:

json
{
  "enabled": true,
  "protocol": "v2",
  "server": "https://offlines-platform-test.wenext.chat",
  "apiEndpoint": "/api/wenext-pi/events/v2/batches",
  "destinationId": "web",
  "clientId": "wenext-pi"
}

用户文件为 ~/.wenext-pi/reporting.json,设置 WENEXT_PI_HOME 后使用该目录下的同名文件。字段覆盖默认值,不必复制整个对象。配置在启动时读取,修改后重启 CLI。

本地 API 在 9001 时:

json
{ "enabled": true, "server": "http://localhost:9001" }

关闭采集:

json
{ "enabled": false }

普通地址要求 HTTPS,回环地址允许 HTTP。当前协议匿名上报,不发送 Authorization 或 X-API-Key,旧 apiKey 字段被忽略。destinationId 是队列目标标识,不是凭据。

项目的 AGENTS、技能、Rules、workflow 和 Git 均不是采集前置条件。身份优先使用有效 Git user.name,其次为 OS 用户名,否则记为未知;不发送邮箱。宿主启动时固定身份,重试不会重新读取并改变事件归属。

查看状态与重试 ​

在交互界面执行:

text
/wenext-metrics
/wenext-metrics flush

前者显示实际 server、开关和投递健康;后者请求重试当前目的地已有 v2 数据。配置或初始化失败显示 configuration_error;无效配置不会静默切回默认服务器。

flush 不重新读取配置,不从历史聊天重建事件,也不迁移其他目的地的积压。后台上传正在运行时不会启动并发上传;一次返回不保证全部队列已入库。确认交付应结合 ACK 检查点和服务端查询。

更换 server、endpoint 或 destination 会使用隔离队列。旧目的地未确认数据仍保留,切回后继续;不要因为新仪表盘无数据就删除旧队列。关闭会话保留未确认数据,不等待网络完成。

本地仪表盘接入 ​

在 wenext-offline-platform 仓库中:

  1. 按该仓库说明启动 API 和数据库,确认 API 监听 9001。

  2. 将 CLI 的 reporting.json 指向该 API,重启并检查 /wenext-metrics。

  3. 将 dashboard/config.json 的 apiBaseUrl 设为 http://localhost:9001/api/wenext-pi/metrics。

  4. 从该仓库根启动页面:

    bash
    python3 -m http.server 8080 --directory dashboard
  5. 打开 http://127.0.0.1:8080/,核对周范围与筛选条件,确保 API 允许页面来源的跨域请求。

页面端口 8080 与上报 API 端口 9001 对应不同服务。页面能打开,不代表 CLI 使用了这台 API,也不代表数据库已接收事件。本 npm 包不包含服务端的部署和数据库配置。

数据口径 ​

数据含义与限制
项目身份规范化本地项目根对应的 checkout;同名项目不合并,移动根目录会改变身份
任务身份任务所属稳定 UUID,独立于标题、目录名和会话
显示名称有界任务标题和项目目录名;稳定 ID 仍用于关联
使用模型真实 assistant 响应中的 provider/model、主或子角色、阶段;配置值和历史重放不算新观测
生命周期可信创建时间至归档或查询截止,包含等待和未归档时间
执行时间已闭合主智能体执行区间的并集,排除轮次间空闲;缺失区间显示部分或未知
阶段时间分别统计阶段停留时间与观测到的执行区间,不能混用
审查按真实审查器 run ID 计数,轮询和工具操作不等于一次新审查
质量真实 attempt、run 和检查结果;归档前已可上报,复用证据不增加执行次数
技能正文实际进入新模型服务提供方请求才计一次加载,非目录发现或元数据读取次数
Web 质量读取绑定任务/run、摘要已验证的冻结报告,分别记录用例、runner 错误、flaky 和可选覆盖率

task_check_verified 表示工作已通过宿主核验,不等于用户验收或归档。零检查的本地 attempt 为 unverified,v2 使用 unknown;所有声明项都不适用时使用 not_applicable。查询端把历史 passed + checkCount=0 视为未验证并排除成功率,原始事件不改写。

主会话使用 SDK 的有效技能清单,覆盖项目、用户、包/扩展和临时来源。成功文件读取、简单字面 cat、/skill:name 等可观察路径需最终确认正文交付;失败、被清除、仅元数据和历史重放不计。只读子会话在最终请求边界观察新 wenext_read。任意 Shell 管道和任意扩展转换不保证可观察,覆盖率保持部分。

Web 测试分类使用显式 metadata、绑定计划或明确的 unit/test:unit/test:e2e 脚本声明;不能仅凭 Jest 或 Playwright 推断类型。通用退出码检查不生成虚构用例数或覆盖率。

时间与显示字段 ​

执行区间从真实 SDK agent_start 开始,在结算或会话结束时关闭;仅收到 input 不算执行。任务切换、阶段变化会切分归属,自动继续也能形成新执行区间。内部会话替换使用 session_replaced,与用户暂停区分。

创建时间必须是完整 ISO 时间。旧日期字符串不补为零点;接收端优先使用最早 task_created.occurredAt,缺少可信创建时刻则生命周期未知。已有历史暂停或缺失模型信息不会靠推测重写。

事件/字段契约
task_metadatadisplayName、projectDisplayName 各 1–160 字符,非负 taskRevision,可选精确创建时间
createdAtPrecision有可信时刻时为 instant;日期精度不冒充时刻
model_observed稳定 observationId、provider、model、role=main|child、phase 和可选 childRunId
查询时间同一响应使用固定 asOf,执行区间按周裁剪,重叠区间取并集

任务路由及 policy/human 授权来源保存在本地快照,尚未加入 v2 元数据。当前不统计 Token、费用、采纳率或个人生产力排名。模型响应观测也不是网络请求次数。

持久化与投递协议 ​

内容位置(相对 WENEXT_PI_HOME 或任务目录)
安装 UUIDmetrics-installation.json
任务 UUID<task>/metrics-identity.json
语义去重标记<task>/metrics-observations/
v2 队列、检查点、隔离与健康metrics/v2/<destination-hash>/

生产端协议定义在 src/telemetry/metrics-contract.ts,接收端副本在 src/domains/piMetrics/contract.ts,两者须同步。事件 ID 与 producerSeq 先持久化,批次基于冻结的事件身份,重试不从可变任务状态重新构造正文。

服务端持久接收后返回匹配 protocol、版本、batch ID 及全部 event ID 的 ACK。缺失、多余、重复或包装格式不符的 ACK 不推进检查点;HTTP 2xx 本身不证明交付完成。服务端必须按稳定事件身份去重,以支持丢 ACK 后重传。

结果客户端处理
完整匹配 ACK推进相应检查点
401/403、网络或 5xx保留并退避重试,显示诊断
429使用有界 Retry-After
413拆分批次
400/409/422 精确指出无效或冲突事件隔离指定事件,其余继续重试
未识别错误格式不丢弃事件
检查点无效或越界隔离检查点,原事件使用稳定 ID 重放

每段上限 8 MiB,段配额 256 MiB,每批最多 250 事件和 1 MiB。超过配额不能通过删除待传数据腾空间,写入失败记录 dropped 诊断;因此持久队列不等于永不丢失。无效/过期事件保留在 quarantine,不完整尾部等待恢复,完整前缀仍可投递。旧 producer 已确认且超过七天的完整段可在核验检查点后清理。

new/resume/fork 不关闭进程队列;退出或扩展重载才关闭。新进程扫描并重试之前未确认的段。协议变更应先部署兼容接收端,再升级客户端,严格旧接收端可能拒收新增字段。

隐私与采集边界 ​

上传有界显示标题、项目目录名、用户显示身份、模型/插件/工具名称和结构化状态。技能来源使用摘要区分同名文件,不上传绝对路径和正文。完整对话、提示词、代码、命令 argv、报告正文、原始错误和凭据不进入 wire payload。

本地会话和诊断状态可能比上传字段更丰富;匿名接收仅表示不要求 collector 凭据,不表示所有显示元数据匿名化。业务工具仍负责自己的外部服务和数据处理约定。

旧 v1 数据 ​

旧 outbox 不会自动转换为 v2 周报事实。如需显式投递到支持 v1 的接收端,可在 reporting.json 合并:

json
{
  "legacy": {
    "server": "http://localhost:9001",
    "apiEndpoint": "/api/wenext-pi/events/v1/batches",
    "clientId": "wenext-pi"
  }
}

v1 的投递、字段与消费语义见 旧版接收协议。开启 v2 或 flush 不能追溯生成从未采集的技能、模型和执行事实。

无数据显示时 ​

按链路核对:实际 CLI 配置 → 当前目的地队列及错误 → ACK → 接收 API/数据库 → 仪表盘的 apiBaseUrl → 周范围与筛选。doctor 的旧 outbox 数量不能证明 v2 已入库;旧 v1 ACK 也不能证明 v2 周报可见。

每个插件独立声明任意业务指标并自动生成仪表盘的能力尚未实现。现有通用工作流事实和 Web 质量观测之外的扩展,见插件观测提案。