旧版 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 提交,也不保证兼容现有周报。独立测试工具通过质量契约负责领域语义。
配置与请求
{
"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:
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}协议与消费语义
请求示例:
{
"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 和以下内容:
{
"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[].status | passed/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 保留给上传锁使用,并从扫描中排除。
一致性限制
任务状态变更与事件追加之间的进程终止,或本地磁盘故障,可能造成观测缺失。缺失必须保持未知,不能补造成功。任务本地收据是状态权威;任务归档与发件箱不构成跨文件崩溃事务。