OTel uploads explicit feedback for all users by default
This commit is contained in:
1 parent
02a029e679
commit
9ffe85a512
65 files changed
+1162
-381
No files matched your search
@@ -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
|
||||
@@ -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 -->
|
||||
@@ -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,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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user