Skip to content

旧版 v1 接收协议 ​

文档导航

本页只适用于显式启用的历史 wenext-pi-events/v1。新接入使用指标与上报 v2;v1 数据不自动成为 v2 仪表盘的统计事实。

职责与适用范围 ​

Pi 无需仓库脚本即可采集本地会话、用量、任务、插件和工具事件。模式版本 1 的持久发件箱位于业务源码之外。旧版 v1 上传要求在 ~/.wenext-pi/reporting.json 中显式配置 legacy 目的地;新版 v2 默认启用,见指标说明。本地完成不依赖采集端可达或接收事件,发件箱数据不能授权任务流转,也不能替代质量证据。

本文定义保留的通用消费协议 wenext-pi-events/v1。它不生成旧 quality_run_v3,不虚构领域门禁,不绑定 Git 提交,也不保证兼容现有周报。独立测试工具通过质量契约负责领域语义。

配置与请求 ​

json
{
  "legacy": {
    "server": "https://your-collector.example",
    "apiEndpoint": "/api/wenext-pi/events/v1/batches",
    "clientId": "wenext-pi"
  }
}

POST {server}{apiEndpoint}/{batchId} 发送 Content-Type: application/json、X-Wenext-Protocol、X-Batch-Id、X-Event-Count 和 X-Client-Id 请求头。不发送认证头,已废弃的 apiKey 值被忽略。默认启用 v2 不会自动投递旧 v1 发件箱,也不会将其转换为 v2 事实。

内部适配函数如下,不构成稳定的 npm SDK:

ts
createMetricsBatch(projectRoot: string, events: OutboxEvent[]): MetricsBatch
acceptsMetricsBatch(value: unknown, batch: MetricsBatch): boolean
flushSessionOutbox(layout, sessionId, config, fetchImpl?, now?): Promise<FlushResult>
// skipped | empty | uploaded {batchId,eventCount} | pending {error}

协议与消费语义 ​

请求示例:

json
{
  "protocol": "wenext-pi-events/v1",
  "schemaVersion": 1,
  "projectId": "sha256-of-JSON-encoded-canonical-local-root",
  "batchId": "sha256-of-JSON-encoded-request-without-batchId",
  "events": [{
    "eventId": "persisted-event-uuid",
    "schemaVersion": 1,
    "sessionId": "parent-session-id",
    "kind": "task_finished",
    "createdAt": "2026-01-01T10:00:00.000Z",
    "cliVersion": "0.1.0",
    "piVersion": "1.1.0",
    "payload": {
      "taskId": "task-id", "status": "completed", "workflowClass": "full",
      "quality": {
        "schemaVersion": 1, "result": "passed",
        "attemptId": "attempt-id", "runId": "quality-plan-run-id",
        "inputHash": "checked-input-and-policy-digest",
        "checks": [{"id": "unit", "status": "passed", "required": true,
          "applicable": "applicable", "exitCode": 0, "durationMs": 50,
          "executionStatus": "succeeded"}],
        "verifications": []
      }
    }
  }]
}

同一组投影事件对应确定的批次 ID。新增待发送事件可能改变下一批内容,因此必须按 (projectId, eventId) 去重,不能按 batchId 去重。不要对重新序列化或重排的 JSON 对象重新计算标识。

projectId 标识本地检出目录;移动根目录或另建克隆会得到不同 ID。它不是全局仓库身份,也不承诺匿名化。旧记录可能没有版本字段。未知事件类型携带空负载,应保留其信封元数据,不推断质量结果。

持久接收每条事件(包括已保存的重复事件)后,返回 HTTP 2xx 和以下内容:

json
{
  "protocol": "wenext-pi-events/v1", "schemaVersion": 1,
  "batchId": "the-request-batch-id",
  "acceptedEventIds": ["persisted-event-uuid"]
}

ID 集合必须与批次完全相同,不得缺失、重复或多出 ID。接收端必须拒绝 ID/内容冲突,保留未知事实,并在持久存储后才发送确认。Pi 校验确认响应的结构,不能独立证明远端存储或报表实现正确。

事件/字段消费语义
task_created、task_continued、task_pointer_updated任务与会话关系;一个会话可涉及多个任务,一个任务也可关联多个会话
task_finished本地完成;quality.result 单独说明通过、失败或未验证
task_closed_with_failure经人工批准按 resolution: failed|blocked 完成,不得算作通过任务
quality.checks[].statuspassed/failed/blocked/not_applicable 互斥;必需/建议性质与适用性另行表达
quality.verifications独立复核结果,不算新的任务或检查计划尝试
task_quality_attempt真实 attemptId、runId、inputHash、previousId、status、environment;按项目/任务/尝试 ID 更新或插入
task_retry_authorized授权而非执行,不增加尝试次数
assistant_usage父会话消息用量,可选绑定任务
child_assistant_usage子会话消息用量,包含父会话、childSessionId、agentId、runId 和 taskId
用量中的 availability: unknown服务提供方未提供测量值,不代表词元数为零
tool_call、tool_execution_end、lifecycle_plugin_event允许、错误、阶段、状态等活动信息,不证明质量检查已完成

汇总时,对去重后的父/子事件各计一次其报告的 totalTokens,不能通过父级汇总再次加入子级总量。input、output、cacheRead、cacheWrite、reasoning 是服务提供方计数,不一定可以相加。

质量统计分母是去重后、已完成且带有明确质量结果的任务,同时需展示缺失或未验证的覆盖情况。重复完成请求、重试、复核和失败关闭观测都不增加任务数。缺少 quality 的历史数据保持未知;旧 task_check_run 不是终态收据。重试或关闭被拒绝后可能再次产生尝试观测;重放较旧的终态观测不能覆盖更新的终态结果。

传输投影按事件类型保留允许字段。命令、参数数组、环境、提示词、消息正文、报告、日志、产物路径、任务标题、批准原因和自由文本错误都被省略。标识以及模型/工具/插件名称仍可见。本地脱敏发件箱包含更丰富的诊断信息,不能视为传输格式。第三方事件目前只上传信封元数据。

上一段描述的是旧版投影。v2 已明确允许 task_metadata 中的显示标题/项目名称,见指标采集说明;其它自由文本正文仍被排除。

结果与错误处理 ​

条件必需行为
完整确认响应与批次匹配原子更新检查点,只推进到本批次最后一个事件
只有 HTTP 2xx、JSON 无效、版本/批次错误、确认不完整或重复保持待发送,保留事件和游标
网络错误、10 秒超时、本地读写失败保持待发送,已完成任务仍保持完成
同项目/会话并发上传本地进程租约拒绝第二个上传者,等待后续触发重试
持有上传租约的进程退出既有状态锁恢复机制处理已退出的本地持有者,使用稳定 ID 重放事件
只有 HTTP 状态、没有 deliveryKey 的旧游标通过新确认协议重放保留事件
服务器、端点或 clientId 变化按新的投递键重放,接收端去重
事件模式/会话无效,或 NDJSON/检查点 JSON 损坏保持待发送并诊断,不跳过或删除损坏前缀
未知事件负载/类型使用显式投影或仅元数据事件,不猜测结果

一次刷新最多发送 250 条事件和 1 MiB 数据。单条投影事件超限时保持待发送。启动、完成和关闭触发刷新;每次触发对每个会话最多推进一个批次,积压可能需要多次触发。uploaded.eventCount 表示本批次数量,不表示队列已经清空。没有后台上传守护进程或按保留期删除功能。目前读取会将一个会话的发件箱装入内存;超长历史的流式读取/压缩属于后续工作。

检查点记录 deliveryKey、lastEventId、uploadedAt 和 batchId。收到确认后仍保留事件;切回之前的目的地可能再次重放。.coordination 保留给上传锁使用,并从扫描中排除。

一致性限制 ​

任务状态变更与事件追加之间的进程终止,或本地磁盘故障,可能造成观测缺失。缺失必须保持未知,不能补造成功。任务本地收据是状态权威;任务归档与发件箱不构成跨文件崩溃事务。