OTel uploads explicit feedback for all users by default

This commit is contained in:
Tianyi Cui committed 2026-09-05 23:21:23 +08:00
1 parent 02a029e679
commit 9ffe85a512
65 files changed
+1162 -381

No files matched your search

+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/subsystems/feedback.md
feedback.md: e1f2d05435cb5e0fe09c315d4123c4621e4c7c68
feedback.zh.md: 9ce5b44995302687a39a655bf019f623e8c8c7e7
feedback.md: c538fac50b0c75e43f761a3b58b385840b83e4ef
feedback.zh.md: 4a77f9c0396f3635755c301a80ccaefe398d5ad6
+27 -1
View File
@@ -221,7 +221,7 @@ Successful message-feedback mutations await canonical persistence: live operatio
Plugin disposal closes operation admission and drains accepted per-Session queue work.
When explicitly enabled, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests. Recording feedback does not trigger a request or a separate `dsh_feedback` upload. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
When explicitly enabled, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests. Recording feedback does not trigger an LLM request or a separate `dsh_feedback` upload. For non-DeepSeek routes, the [OTel backend](../../packages/session/session-telemetry-otel/README.md) can release the canonical prefix through recorded feedback. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
## Web surface
@@ -280,5 +280,31 @@ Session-log service; cold operations never construct a Session or Agent.
@Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise<MessageFeedbackDeleteResult>
```
Source: [`packages/feedback/message-feedback/src/index.ts`](../../packages/feedback/message-feedback/src/index.ts)
<a id="feedback-events"></a>
### `feedback/*` events
<a id="feedbackcommitted--parallel"></a>
#### `feedback/committed` — parallel
Observe a durable cold feedback mutation without publishing a live Session. Observers run before write ownership is released and must not await another message-feedback operation for this Session. The payload is borrowed read-only; deep-clone it before transferring ownership (for example, to Session.fromRestore).
```ts cordis-catalog
/**
* Observe a durable cold feedback mutation without publishing a live Session.
* Observers run before write ownership is released and must not await
* another message-feedback operation for this Session. The payload is borrowed
* read-only; deep-clone it before transferring ownership (for example, to Session.fromRestore).
* @param inspection - committed canonical prefix, including the feedback as its last event.
* @mode parallel
*/
'feedback/committed'(inspection: SessionInspection): void
```
Types: [SessionInspection](persistence.md)
Source: [`packages/feedback/message-feedback/src/index.ts`](../../packages/feedback/message-feedback/src/index.ts)
<!-- END GENERATED cordis-surface -->
+27 -1
View File
@@ -221,7 +221,7 @@ fork 种子可以包含父 Session 的反馈事件,但 payload 保留父级 `s
插件释放会关闭操作接纳,并排空已进入各 Session 队列的工作。
显式启用后,[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中,把反馈作为普通 `dsh_session_log` 后缀的一部分传送。记录反馈不会触发请求,也不会单独上传 `dsh_feedback`。命令确认文本确认记录并标识 Session 与匿名用户,不报告遥测策略或投递结果。
显式启用后,[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中,把反馈作为普通 `dsh_session_log` 后缀的一部分传送。记录反馈不会触发 LLM 请求,也不会单独上传 `dsh_feedback`。对于非 DeepSeek 路由,[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)可以将权威日志前缀释放至已记录的反馈。命令确认文本确认记录并标识 Session 与匿名用户,不报告遥测策略或投递结果。
## Web 界面
@@ -280,5 +280,31 @@ Session-log service; cold operations never construct a Session or Agent.
@Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise<MessageFeedbackDeleteResult>
```
Source: [`packages/feedback/message-feedback/src/index.ts`](../../packages/feedback/message-feedback/src/index.ts)
<a id="feedback-events"></a>
### `feedback/*` events
<a id="feedbackcommitted--parallel"></a>
#### `feedback/committed` — parallel
Observe a durable cold feedback mutation without publishing a live Session. Observers run before write ownership is released and must not await another message-feedback operation for this Session. The payload is borrowed read-only; deep-clone it before transferring ownership (for example, to Session.fromRestore).
```ts cordis-catalog
/**
* Observe a durable cold feedback mutation without publishing a live Session.
* Observers run before write ownership is released and must not await
* another message-feedback operation for this Session. The payload is borrowed
* read-only; deep-clone it before transferring ownership (for example, to Session.fromRestore).
* @param inspection - committed canonical prefix, including the feedback as its last event.
* @mode parallel
*/
'feedback/committed'(inspection: SessionInspection): void
```
Types: [SessionInspection](persistence.zh.md)
Source: [`packages/feedback/message-feedback/src/index.ts`](../../packages/feedback/message-feedback/src/index.ts)
<!-- END GENERATED cordis-surface -->
+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/subsystems/session-telemetry.md
session-telemetry.md: 83224cf03005909f9b3d600a950c2d6402ca3b2a
session-telemetry.zh.md: a093590819d62839fb69a0e50b2d11f495171ec8
session-telemetry.md: f452dc6fa9064689664bcaed08205d30def822e6
session-telemetry.zh.md: 59c817cca945e3f972e30104104f44fb15006aa5
+22 -6
View File
@@ -55,22 +55,38 @@ interface SessionTelemetryRecord {
}
```
Every canonical [session event](session.md), including each `assistant/message` or `assistant/attempt` with its complete compact stream and every plugin-merged type the seam never heard of, passes through whole as one ordered ledger record. Process-local `agent/assistant-stream` frames do not enter this durable feed. A new Session object replays its complete log from seq 0, including constructor seed history; re-adopting the same object resumes after its handoff cursor. Delivery is best-effort: the cursor marks handed-off, not delivered, and records can be lost (crash, reload window) or duplicated (new-object replay, SDK retries), so receivers dedupe ledger records on `(session.id, session.format_version, event.seq)`; ops records deliberately omit that identity — they are signals to alert on, not entries to sum, and tolerate duplicates instead.
Every canonical [session event](session.md), including each `assistant/message` or `assistant/attempt` with its complete compact stream and every plugin-merged type the seam never heard of, passes through whole as one ordered ledger record. Process-local `agent/assistant-stream` frames do not enter this durable feed. A new Session object starts at its lifecycle boundary unless the backend selects `includeHistory`; re-adopting the same object resumes after its handoff cursor. Delivery is best-effort: the cursor marks handed-off, not delivered, and records can be lost (crash, reload window) or duplicated (new-object replay, SDK retries), so receivers dedupe ledger records on `(session.id, session.format_version, event.seq)`; ops records deliberately omit that identity — they are signals to alert on, not entries to sum, and tolerate duplicates instead.
## The sharing disclosure
The seam's acknowledgement contract (owned by the [Service Definition README's sharing-disclosure section](../../packages/session/session-telemetry/README.md#the-sharing-disclosure)): every backend discloses its deployment-selected sharing policy through the required abstract `sharing` member on `ctx.sessionTelemetry`, and consumers render "not configured" only when no telemetry service is mounted. The disclosure states the current policy, never delivery or retention — handoff is the non-blocking enqueue, and batching, retry, and loss policy stay the reporting SDK's.
Every backend exposes its deployment-selected mode through the required abstract `sharing` member on `ctx.sessionTelemetry` ([Service Definition README](../../packages/session/session-telemetry/README.md#the-sharing-disclosure)). This is neither a per-Session admission decision nor a delivery receipt. The `/feedback` acknowledgement does not consult it.
```ts type-equiv
/**
* Deployment-selected session-sharing policy disclosed by a mounted
* {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
* `/feedback` command's confirmation text). The Service Definition owns the
* vocabulary so consumers and backends do not depend on a specific provider.
* Deployment-selected session-sharing mode, not confirmation of SDK delivery.
*/
type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
```
## Capture policy
```ts type-equiv
/** Whether capture follows live events or reads the canonical log only when requested. */
type SessionTelemetryCapture = 'live' | 'on-demand'
```
```ts type-equiv
/** Backend-selected capture mode and history policy. */
interface SessionTelemetryCaptureOptions {
/** Follow live events, or wait for explicit capture; defaults to live. */
capture?: SessionTelemetryCapture
/** Include stored history before this lifecycle; defaults to false. */
includeHistory?: boolean
}
```
`includeHistory` permits stored and inherited records but does not itself authorize capture. The [OTel backend](../../packages/session/session-telemetry-otel/README.md) uses on-demand capture and requires new own explicit feedback; it releases only the complete prefix through that feedback, for every provider.
## The backend contract
```ts type-equiv
+22 -6
View File
@@ -55,22 +55,38 @@ interface SessionTelemetryRecord {
}
```
每条权威[会话事件](session.zh.md)都会完整透传为一条有序 ledger 记录,包括每个携带完整紧凑 stream 的 `assistant/message` 或 `assistant/attempt`,以及该 seam 从未听说过、由插件合并进来的类型。进程本地 `agent/assistant-stream` frame 不进入该持久 feed。新 Session 对象会从 seq 0 回放完整日志,包括构造 seed 历史;重新收养同一对象时会从 handoff 游标之后继续。投递是尽力而为的:游标标记的是「已交接」而非「已送达」,记录可能丢失(崩溃、重载窗口)也可能重复(新对象回放、SDK 重试),因此接收端对 ledger 记录基于 `(session.id, session.format_version, event.seq)` 去重;ops 记录刻意省略这类标识——它们是用于告警的信号,而非用于累加的条目,重复被容忍而非被去重。
每条权威[会话事件](session.zh.md)都会完整透传为一条有序 ledger 记录,包括每个携带完整紧凑 stream 的 `assistant/message` 或 `assistant/attempt`,以及该 seam 从未听说过、由插件合并进来的类型。进程本地 `agent/assistant-stream` frame 不进入该持久 feed。新 Session 对象从其生命周期边界开始,除非后端选择 `includeHistory`;重新收养同一对象时会从 handoff 游标之后继续。投递是尽力而为的:游标标记的是「已交接」而非「已送达」,记录可能丢失(崩溃、重载窗口)也可能重复(新对象回放、SDK 重试),因此接收端对 ledger 记录基于 `(session.id, session.format_version, event.seq)` 去重;ops 记录刻意省略这类标识——它们是用于告警的信号,而非用于累加的条目,重复被容忍而非被去重。
## 共享披露
该 seam 的确认契约(归属 [Service Definition README 的共享披露段](../../packages/session/session-telemetry/README.zh.md#the-sharing-disclosure)):每个后端都通过 `ctx.sessionTelemetry` 上必需的抽象 `sharing` 成员披露其部署级共享策略,消费方只有在未挂载任何遥测服务时才渲染「未配置」。披露只陈述当前策略,绝不承诺投递或留存——交接是非阻塞入队,批处理、重试与丢失策略仍归上报 SDK。
每个后端都通过 `ctx.sessionTelemetry` 上必需的抽象 `sharing` 成员暴露其部署级模式([Service Definition README](../../packages/session/session-telemetry/README.zh.md#the-sharing-disclosure))。它既不是逐 Session 的接纳决定,也不是投递回执。`/feedback` 确认文本不查询它。
```ts type-equiv
/**
* Deployment-selected session-sharing policy disclosed by a mounted
* {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
* `/feedback` command's confirmation text). The Service Definition owns the
* vocabulary so consumers and backends do not depend on a specific provider.
* Deployment-selected session-sharing mode, not confirmation of SDK delivery.
*/
type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
```
## 捕获策略
```ts type-equiv
/** Whether capture follows live events or reads the canonical log only when requested. */
type SessionTelemetryCapture = 'live' | 'on-demand'
```
```ts type-equiv
/** Backend-selected capture mode and history policy. */
interface SessionTelemetryCaptureOptions {
/** Follow live events, or wait for explicit capture; defaults to live. */
capture?: SessionTelemetryCapture
/** Include stored history before this lifecycle; defaults to false. */
includeHistory?: boolean
}
```
`includeHistory` 允许捕获存储与继承的记录,但本身不授权捕获。[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)使用按需捕获,并要求新的自身显式反馈;它只释放截至该反馈的完整前缀,适用于所有提供方。
## 后端约定
```ts type-equiv