指标、上报与仪表盘
Wenext-Pi 记录任务、阶段、模型、技能和质量执行事实,使用本地持久队列上报。采集和传输失败不会改变任务批准、检查结果或归档决定。CLI 提供生产端;接收 API、数据库与仪表盘由独立的 wenext-offline-platform 提供。
配置
默认无需配置文件,使用以下设置:
{
"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 时:
{ "enabled": true, "server": "http://localhost:9001" }关闭采集:
{ "enabled": false }普通地址要求 HTTPS,回环地址允许 HTTP。当前协议匿名上报,不发送 Authorization 或 X-API-Key,旧 apiKey 字段被忽略。destinationId 是队列目标标识,不是凭据。
项目的 AGENTS、技能、Rules、workflow 和 Git 均不是采集前置条件。身份优先使用有效 Git user.name,其次为 OS 用户名,否则记为未知;不发送邮箱。宿主启动时固定身份,重试不会重新读取并改变事件归属。
查看状态与重试
在交互界面执行:
/wenext-metrics
/wenext-metrics flush前者显示实际 server、开关和投递健康;后者请求重试当前目的地已有 v2 数据。配置或初始化失败显示 configuration_error;无效配置不会静默切回默认服务器。
flush 不重新读取配置,不从历史聊天重建事件,也不迁移其他目的地的积压。后台上传正在运行时不会启动并发上传;一次返回不保证全部队列已入库。确认交付应结合 ACK 检查点和服务端查询。
更换 server、endpoint 或 destination 会使用隔离队列。旧目的地未确认数据仍保留,切回后继续;不要因为新仪表盘无数据就删除旧队列。关闭会话保留未确认数据,不等待网络完成。
本地仪表盘接入
在 wenext-offline-platform 仓库中:
按该仓库说明启动 API 和数据库,确认 API 监听 9001。
将 CLI 的
reporting.json指向该 API,重启并检查/wenext-metrics。将
dashboard/config.json的apiBaseUrl设为http://localhost:9001/api/wenext-pi/metrics。从该仓库根启动页面:
bashpython3 -m http.server 8080 --directory dashboard打开
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_metadata | displayName、projectDisplayName 各 1–160 字符,非负 taskRevision,可选精确创建时间 |
createdAtPrecision | 有可信时刻时为 instant;日期精度不冒充时刻 |
model_observed | 稳定 observationId、provider、model、role=main|child、phase 和可选 childRunId |
| 查询时间 | 同一响应使用固定 asOf,执行区间按周裁剪,重叠区间取并集 |
任务路由及 policy/human 授权来源保存在本地快照,尚未加入 v2 元数据。当前不统计 Token、费用、采纳率或个人生产力排名。模型响应观测也不是网络请求次数。
持久化与投递协议
| 内容 | 位置(相对 WENEXT_PI_HOME 或任务目录) |
|---|---|
| 安装 UUID | metrics-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 合并:
{
"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 质量观测之外的扩展,见插件观测提案。