feat(llm): send DeepSeek user identity header
This commit is contained in:
kingwl
+2
-2
@@ -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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md
|
||||
2026-06-21-mandatory-app-attribution-headers.md: 39050a53ec76e8c5a6cac4d8e31fa15b992c406e
|
||||
2026-06-21-mandatory-app-attribution-headers.zh.md: bfd6aa2540022f68cf9f69ccc2c12b3bc0978960
|
||||
2026-06-21-mandatory-app-attribution-headers.md: c90b136a556da81e1c15828926f18b865cea4ece
|
||||
2026-06-21-mandatory-app-attribution-headers.zh.md: f68cad7e9f642319dc508de9261e33180bfe5748
|
||||
+2
-2
@@ -24,7 +24,7 @@ The immediate prompt came from OpenRouter's [App Attribution](https://openrouter
|
||||
|
||||
## Decision
|
||||
|
||||
Provider request attribution is mandatory at the LLM adapter boundary, using the standard `User-Agent` header only. The rule: every product LLM adapter sends a static, non-secret application identity on every provider HTTP request, and every adapter has tests proving that `User-Agent` reaches the wire (a mock server asserting received headers; for a library-backed adapter, the library's header hook feeding the same mock-server assertion).
|
||||
Provider-neutral app attribution is mandatory at the LLM adapter boundary, using the standard `User-Agent` header only. The rule: every product LLM adapter sends a static, non-secret application identity on every provider HTTP request, and every adapter has tests proving that `User-Agent` reaches the wire (a mock server asserting received headers; for a library-backed adapter, the library's header hook feeding the same mock-server assertion). This rule governs app attribution, not provider-specific request identity: [the DeepSeek request-identity decision](../feature/2026-08-11-deepseek-request-user-id-header.md) separately owns its user and session headers.
|
||||
|
||||
OpenRouter app attribution is deliberately not implemented. `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, and `X-OpenRouter-Categories` are OpenRouter-specific product-surface headers, not provider-neutral model-request attribution. They can be proposed later by an OpenRouter adapter or explicit OpenRouter mode, with its own privacy/product decision, tests, and docs. Until then, even requests pointed at OpenRouter send only the shared `User-Agent` attribution from this decision.
|
||||
|
||||
@@ -41,7 +41,7 @@ Wire mapping (`attributionHeaders`; header names lowercase in code - HTTP field
|
||||
| Target | Mapping |
|
||||
|---|---|
|
||||
| All HTTP-based adapters | `User-Agent: {product}/{version} (+{url})` - the parenthesized `+url` comment stays within RFC 9110's conservative product/comment syntax. |
|
||||
| Direct DeepSeek endpoint | `User-Agent`; do not send OpenRouter-only headers unless DeepSeek documents an equivalent contract. |
|
||||
| Direct DeepSeek endpoint | `User-Agent` for app attribution; `x-deepseek-harness-user-id` and conditional `x-deepseek-harness-session-id` are separate request identity under the DeepSeek-specific decision. Do not send OpenRouter-only headers unless DeepSeek documents an equivalent contract. |
|
||||
| OpenRouter endpoints | `User-Agent` only for now. Do not send `HTTP-Referer`, `X-OpenRouter-Title`, `X-Title`, or `X-OpenRouter-Categories` under this decision. |
|
||||
| Future providers | `User-Agent` only unless a later provider-specific Agent Note accepts additional headers. Do not reuse `HTTP-Referer` by analogy. |
|
||||
|
||||
|
||||
+2
-2
@@ -24,7 +24,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这
|
||||
|
||||
## 决策
|
||||
|
||||
在 LLM 适配器边界，提供方请求归属是强制的，且仅使用标准 `User-Agent` 头部。规则：每个产品级 LLM 适配器在每个提供方 HTTP 请求上发送一个静态、非机密的应用身份，且每个适配器都有测试证明 `User-Agent` 到达了线路（mock 服务器断言收到的头部；对于基于库的适配器，通过库的头部钩子馈入同一个 mock 服务器断言）。
|
||||
在 LLM 适配器边界，提供方无关的应用归属是强制的，且仅使用标准 `User-Agent` 头部。规则：每个产品级 LLM 适配器在每个提供方 HTTP 请求上发送一个静态、非机密的应用身份，且每个适配器都有测试证明 `User-Agent` 到达了线路（mock 服务器断言收到的头部；对于基于库的适配器，通过库的头部钩子馈入同一个 mock 服务器断言）。这条规则约束应用归属，不约束提供方特有的请求身份；[DeepSeek 请求身份决策](../feature/2026-08-11-deepseek-request-user-id-header.md)另行负责其用户与会话头部。
|
||||
|
||||
OpenRouter 应用归属刻意未实现。`HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 和 `X-OpenRouter-Categories` 是 OpenRouter 特有的产品展示头部，不是提供方无关的模型请求归属。它们可以后续由 OpenRouter 适配器或显式 OpenRouter 模式提出，附带自己的隐私/产品决策、测试和文档。在此之前，即使请求指向 OpenRouter，也只发送本决策定义的共享 `User-Agent` 归属。
|
||||
|
||||
@@ -41,7 +41,7 @@ OpenRouter 应用归属刻意未实现。`HTTP-Referer`、`X-OpenRouter-Title`
|
||||
| 目标 | 映射 |
|
||||
|---|---|
|
||||
| 所有基于 HTTP 的适配器 | `User-Agent: {product}/{version} (+{url})`——括号中的 `+url` 注释符合 RFC 9110 保守的 product/comment 语法。 |
|
||||
| 直连 DeepSeek 端点 | `User-Agent`；除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
|
||||
| 直连 DeepSeek 端点 | `User-Agent` 用于应用归属；`x-deepseek-harness-user-id` 与条件性的 `x-deepseek-harness-session-id` 由 DeepSeek 特有决策作为独立请求身份管理。除非 DeepSeek 文档化了等效约定，否则不发送 OpenRouter 特有头部。 |
|
||||
| OpenRouter 端点 | 目前仅 `User-Agent`。本决策下不发送 `HTTP-Referer`、`X-OpenRouter-Title`、`X-Title` 或 `X-OpenRouter-Categories`。 |
|
||||
| 未来提供方 | 仅 `User-Agent`，除非后续提供方特有的 Agent Note 接受额外头部。不要类比复用 `HTTP-Referer`。 |
|
||||
|
||||
|
||||
+2
-2
@@ -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 .agents/notes/implemented/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
|
||||
2026-08-07-shared-feedback-telemetry-user-id.md: 5ef487646c94808177e1263b94b8c23a9a045d97
|
||||
2026-08-07-shared-feedback-telemetry-user-id.zh.md: 1ee433396f83a8caf5e35c9cfd1b4f3c04d6c59f
|
||||
2026-08-07-shared-feedback-telemetry-user-id.md: 9e4bd02d78b11858163c36376dbb438fca8aef73
|
||||
2026-08-07-shared-feedback-telemetry-user-id.zh.md: ecc451718812eb0a8b7e50bc949137fe8571ea09
|
||||
+5
-5
@@ -1,4 +1,4 @@
|
||||
# Agent Note: Shared feedback and telemetry anonymous user id
|
||||
# Agent Note: Shared anonymous user id across telemetry, feedback, and DeepSeek requests
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -8,11 +8,11 @@ English | [中文](2026-08-07-shared-feedback-telemetry-user-id.zh.md)
|
||||
|
||||
The OpenTelemetry backend already persisted one anonymous UUID in `$DSH_HOME/.userid`. `/feedback` now needs to report both the receiving session id and a user id so an operator can correlate the acknowledgement with exported records. Duplicating or independently generating that identity would make the reported user meaningless, while importing it from `session-telemetry-otel` would make a direct command depend on an exporter backend and create a dependency cycle when feedback export is mounted by telemetry.
|
||||
|
||||
The earlier [anonymous-user-id decision](../feature/2026-07-31-telemetry-anonymous-user-id.md) deliberately kept the helper inside the OTel backend until a second real consumer existed. Feedback is that consumer.
|
||||
The earlier [anonymous-user-id decision](../feature/2026-07-31-telemetry-anonymous-user-id.md) deliberately kept the helper inside the OTel backend until a second real consumer existed. Feedback became that second consumer. [Direct DeepSeek request identity](../feature/2026-08-11-deepseek-request-user-id-header.md) is the third.
|
||||
|
||||
## Decision
|
||||
|
||||
`@deepseek-ai/dsh-user-id` owns `getOrCreateAnonymousUserId()` and the `$DSH_HOME/.userid` storage contract. `session-telemetry-otel` uses the returned id as OpenTelemetry Resource `user.id`; the `/feedback` success acknowledgement reports `Feedback recorded for session {sessionId}` followed by `User: {userId}` on a second line, which keeps both identifiers available through the generic command row's expandable body. Invalid feedback is rejected before resolving the id, so an empty command does not create `.userid`.
|
||||
`@deepseek-ai/dsh-user-id` owns `getOrCreateAnonymousUserId()` and the `$DSH_HOME/.userid` storage contract. `session-telemetry-otel` uses the returned id as OpenTelemetry Resource `user.id`; the `/feedback` success acknowledgement reports `Feedback recorded for session {sessionId}` followed by `User: {userId}` on a second line; and direct DeepSeek requests carry it as `x-deepseek-harness-user-id`. Invalid feedback is rejected before resolving the id, and the DeepSeek adapter resolves it only after credentials succeed, so neither an empty command nor a credential failure creates `.userid`.
|
||||
|
||||
The extraction preserves the existing random UUID, home resolution, process memo, exclusive-create concurrency, corruption replacement, and best-effort write semantics.
|
||||
|
||||
@@ -26,7 +26,7 @@ The extraction preserves the existing random UUID, home resolution, process memo
|
||||
|
||||
## Consequences
|
||||
|
||||
- One harness home now has one anonymous id shared by feedback acknowledgements and session telemetry exports.
|
||||
- One harness home has one anonymous id shared by feedback acknowledgements, session telemetry exports, and direct DeepSeek requests.
|
||||
- The feedback package depends only on the identity capability, not the telemetry seam or OTel SDK.
|
||||
- The new package is a justified shared seam with two consumers; its empty invariant companion explains why reading the private file is not a useful runtime relationship check.
|
||||
- The package is a justified shared library with three consumers; its empty invariant companion explains why reading the private file is not a useful runtime relationship check.
|
||||
- The original anonymous-user-id Note remains authoritative for storage and privacy semantics, while this Note supersedes only its OTel-local ownership decision.
|
||||
+5
-5
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 反馈与遥测共享匿名用户 id
|
||||
# Agent Note: 遥测、反馈与 DeepSeek 请求共享匿名用户 id
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -8,11 +8,11 @@ Status: implemented
|
||||
|
||||
OpenTelemetry 后端已在 `$DSH_HOME/.userid` 中持久化一个匿名 UUID。`/feedback` 需要同时报告接收反馈的会话 id 与用户 id，以便运维人员将确认文本与导出的记录相关联。复制该身份或单独生成身份会使报告的用户失去意义；从 `session-telemetry-otel` 导入身份则会让直接命令依赖导出后端，并在遥测侧挂载反馈导出时形成依赖环。
|
||||
|
||||
早先的[匿名用户 id 决策](../feature/2026-07-31-telemetry-anonymous-user-id.md)刻意将辅助函数留在 OTel 后端内，直至出现第二个真实消费方。反馈就是这个消费方。
|
||||
早先的[匿名用户 id 决策](../feature/2026-07-31-telemetry-anonymous-user-id.md)刻意将辅助函数留在 OTel 后端内，直至出现第二个真实消费方。反馈成为第二个消费方，[直连 DeepSeek 请求身份](../feature/2026-08-11-deepseek-request-user-id-header.md)则是第三个。
|
||||
|
||||
## 决策
|
||||
|
||||
`@deepseek-ai/dsh-user-id` 负责 `getOrCreateAnonymousUserId()` 和 `$DSH_HOME/.userid` 存储契约。`session-telemetry-otel` 将返回的 id 用作 OpenTelemetry Resource 的 `user.id`；`/feedback` 的成功确认先报告 `Feedback recorded for session {sessionId}`，再在第二行显示 `User: {userId}`，使两个标识符都可通过通用命令行的可展开正文查看。系统在获取 id 前拒绝无效反馈，因此空命令不会创建 `.userid`。
|
||||
`@deepseek-ai/dsh-user-id` 负责 `getOrCreateAnonymousUserId()` 和 `$DSH_HOME/.userid` 存储契约。`session-telemetry-otel` 将返回的 id 用作 OpenTelemetry Resource 的 `user.id`；`/feedback` 的成功确认先报告 `Feedback recorded for session {sessionId}`，再在第二行显示 `User: {userId}`；直连 DeepSeek 请求则通过 `x-deepseek-harness-user-id` 携带它。系统在获取 id 前拒绝无效反馈，DeepSeek 适配器也仅在凭据解析成功后获取 id，因此空命令和凭据失败都不会创建 `.userid`。
|
||||
|
||||
此次抽取保留既有的随机 UUID、home 解析、进程内缓存、独占创建并发、损坏文件替换与 best-effort 写入语义。
|
||||
|
||||
@@ -26,7 +26,7 @@ OpenTelemetry 后端已在 `$DSH_HOME/.userid` 中持久化一个匿名 UUID。`
|
||||
|
||||
## 后果
|
||||
|
||||
- 一个 harness home 只有一个匿名 id，由反馈确认与会话遥测导出共享。
|
||||
- 一个 harness home 只有一个匿名 id，由反馈确认、会话遥测导出与直连 DeepSeek 请求共享。
|
||||
- 反馈包只依赖身份能力，不依赖遥测 seam 或 OTel SDK。
|
||||
- 新包由两个消费方使用，成为有充分依据的共享 seam；其空不变式伴生插件解释了为何读取私有文件并非有用的运行时关系检查。
|
||||
- 该包由三个消费方使用，成为有充分依据的共享库；其空不变式伴生插件解释了为何读取私有文件并非有用的运行时关系检查。
|
||||
- 原始匿名用户 id Note 仍是存储与隐私语义的权威记录；本 Note 仅取代其中由 OTel 本地拥有身份的决策。
|
||||
@@ -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 .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.md
|
||||
2026-07-31-telemetry-anonymous-user-id.md: 4d5d14cb63ebbf9d9f71c729da998ad9804e56bf
|
||||
2026-07-31-telemetry-anonymous-user-id.zh.md: 69c48076ceb97a4bbc3cc35a2aaa3e632b1b1b06
|
||||
2026-07-31-telemetry-anonymous-user-id.md: 6231065126d0884abe3ba6f45a40c42365fe520b
|
||||
2026-07-31-telemetry-anonymous-user-id.zh.md: 4f6bab8df5d479d2df42194581a4229c6de221e6
|
||||
@@ -10,7 +10,7 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
|
||||
|
||||
## Decision
|
||||
|
||||
`getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. The original implementation lived inside `session-telemetry-otel` because no second real consumer existed. `/feedback` later became that consumer, so [the shared-id decision](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md) moves ownership to `@deepseek-ai/dsh-user-id` without changing the storage, anonymity, concurrency, or loss semantics recorded here.
|
||||
`getOrCreateAnonymousUserId()` returns the bare UUID line in `$DSH_HOME/.userid` (resolved by `resolveDshHome`, `$DSH_HOME` > `~/.dsh`), minting and persisting a random UUID v4 on first use; the backend constructor carries it as the Resource's `user.id` (the OTel semconv user attribute), once per export batch. The original implementation lived inside `session-telemetry-otel` because no second real consumer existed. `/feedback` later became that consumer, so [the shared-id decision](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md) moves ownership to `@deepseek-ai/dsh-user-id` without changing the storage, anonymity, concurrency, or loss semantics recorded here. [Direct DeepSeek request identity](2026-08-11-deepseek-request-user-id-header.md) is a third consumer of the same id.
|
||||
|
||||
| Ruling | Value | Rationale |
|
||||
|---|---|---|
|
||||
@@ -22,8 +22,8 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
|
||||
| Write failure | Best-effort: return the in-memory id | Telemetry is never blocked by a read-only home |
|
||||
| Report position | Resource attribute, not per-record attributes | Once per batch suffices for Resource-dimension aggregation; per-record injection would touch the seam contract and grow the wire |
|
||||
| semconv dependency | `@opentelemetry/semantic-conventions` is not imported | One string constant does not justify a dependency |
|
||||
| Home | `@deepseek-ai/dsh-user-id`, shared by the OTel backend and `/feedback` | The second real consumer now exists; direct feedback must not depend on an exporter backend |
|
||||
| Separate switch | None | Either consumer can create the identity; `DSH_TELEMETRY_DISABLED` stops telemetry reporting but does not disable feedback acknowledgement |
|
||||
| Home | `@deepseek-ai/dsh-user-id`, shared by the OTel backend, `/feedback`, and direct DeepSeek requests | Consumers share one storage contract without depending on an exporter backend |
|
||||
| Separate switch | None | Any consumer can create the identity; `DSH_TELEMETRY_DISABLED` stops telemetry reporting but does not disable feedback acknowledgement or the DeepSeek request header |
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -38,6 +38,6 @@ Session telemetry is mounted by default ([default-mount Note](2026-07-31-web-tel
|
||||
## Consequences
|
||||
|
||||
- One `$DSH_HOME` is one stable user in the OTel feed; separate homes are separate users by construction, with no cross-home linking mechanism.
|
||||
- The OTel feed and `/feedback` share `.userid`.
|
||||
- The OTel feed, `/feedback`, and direct DeepSeek requests share `.userid`.
|
||||
- Deleting `.userid` resets the identity (effective next launch); on an unwritable home each process holds its own in-memory id until the home becomes writable.
|
||||
- The [default-mount Note](2026-07-31-web-telemetry-default-mount.md)'s identity follow-up is closed for the anonymous-user-id part by this decision; hostname/surface dimensions, the redaction rule, and the usage-metrics track remain open.
|
||||
@@ -10,7 +10,7 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
|
||||
|
||||
## Decision
|
||||
|
||||
`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；后端构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。原始实现位于 `session-telemetry-otel`，因为当时不存在第二个真实消费方。`/feedback` 后来成为该消费方，因此[共享 id 决策](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md)将所有权移交给 `@deepseek-ai/dsh-user-id`，但不改变本 Note 记录的存储、匿名、并发与丢失语义。
|
||||
`getOrCreateAnonymousUserId()` 返回 `$DSH_HOME/.userid`（`resolveDshHome` 解析，`$DSH_HOME` > `~/.dsh`）中的裸 UUID 行，首用生成随机 UUID v4 并落盘；后端构造时把它作为 Resource 的 `user.id`（OTel semconv 标准用户属性）随每批导出携带一次。原始实现位于 `session-telemetry-otel`，因为当时不存在第二个真实消费方。`/feedback` 后来成为该消费方，因此[共享 id 决策](../architecture/2026-08-07-shared-feedback-telemetry-user-id.md)将所有权移交给 `@deepseek-ai/dsh-user-id`，但不改变本 Note 记录的存储、匿名、并发与丢失语义。[直连 DeepSeek 请求身份](2026-08-11-deepseek-request-user-id-header.md)是同一 id 的第三个消费方。
|
||||
|
||||
| 裁定 | 取值 | 理由 |
|
||||
|---|---|---|
|
||||
@@ -22,8 +22,8 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
|
||||
| 写失败 | best-effort 返回内存 id | telemetry 永不因 home 只读被阻塞 |
|
||||
| 上报位置 | Resource 属性，非逐条 attributes | 每批一次即够接收端按 Resource 维度聚合；逐条注入要动 seam 约定且涨 wire 体积 |
|
||||
| semconv 依赖 | 不引 `@opentelemetry/semantic-conventions` 包 | 一个字符串常量不值一个依赖 |
|
||||
| 落点 | `@deepseek-ai/dsh-user-id`，由 OTel 后端与 `/feedback` 共享 | 第二个真实消费方已经出现；直接反馈不能依赖导出后端 |
|
||||
| 单独开关 | 无 | 任一消费方都可创建该身份；`DSH_TELEMETRY_DISABLED` 会停止遥测上报，但不会禁用反馈确认 |
|
||||
| 落点 | `@deepseek-ai/dsh-user-id`，由 OTel 后端、`/feedback` 与直连 DeepSeek 请求共享 | 消费方共用同一存储契约，且不依赖导出后端 |
|
||||
| 单独开关 | 无 | 任一消费方都可创建该身份；`DSH_TELEMETRY_DISABLED` 会停止遥测上报，但不会禁用反馈确认或 DeepSeek 请求头 |
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -38,6 +38,6 @@ session telemetry 已默认挂载（[默认挂载 Note](2026-07-31-web-telemetry
|
||||
## Consequences
|
||||
|
||||
- 一个 `$DSH_HOME` 在 OTel 回流中是一个稳定用户；不同 home 在构造上就是不同用户，无跨 home 关联机制。
|
||||
- OTel 回流与 `/feedback` 共享 `.userid`。
|
||||
- OTel 回流、`/feedback` 与直连 DeepSeek 请求共享 `.userid`。
|
||||
- 删除 `.userid` 即重置身份（下次启动生效）；home 不可写时每进程各自持有一个内存 id 直至恢复可写。
|
||||
- [默认挂载 Note](2026-07-31-web-telemetry-default-mount.md) 的身份 follow-up 中「匿名用户 id」项由本决定关闭；hostname/surface 维度与脱敏规则、usage-metrics track 仍是待办。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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 .agents/notes/implemented/feature/2026-08-11-deepseek-request-user-id-header.md
|
||||
2026-08-11-deepseek-request-user-id-header.md: 246021d3ea69a6341def90f81051da78a267f051
|
||||
2026-08-11-deepseek-request-user-id-header.zh.md: 6861d2b6ed1294c8e29efb7c883f56f8aa1d31ca
|
||||
@@ -0,0 +1,44 @@
|
||||
# Agent Note: DeepSeek request user and session identity headers
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-11-deepseek-request-user-id-header.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Direct DeepSeek requests already carried `x-deepseek-harness-session-id` when the caller supplied `GenerateOptions.sessionId`, which lets provider-side support and diagnostics correlate turns within one conversation. They lacked a stable identity across sessions even though the harness already persists an anonymous user id for telemetry and feedback. A separate id would break correlation, while putting it in the provider-neutral attribution helper would send a stable per-user identifier through every HTTP adapter.
|
||||
|
||||
The user id is transport metadata, not model input. It must not enter the request body, prompt, token accounting, KV-cache identity, or session log. The destination is the adapter's resolved `baseURL`, which can be DeepSeek itself or a configured gateway, so the privacy boundary must be explicit.
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh-llm-deepseek` sends `x-deepseek-harness-user-id` on every provider request sent after successful credential resolution. The value comes from `@deepseek-ai/dsh-user-id` and therefore matches the OpenTelemetry Resource `user.id` and `/feedback` acknowledgement for the same `$DSH_HOME`. The adapter continues to send `x-deepseek-harness-session-id` only when `GenerateOptions.sessionId` is present; the agent loop supplies the current durable `Session.id` for ordinary agent, title-generation, and compaction requests.
|
||||
|
||||
The plugin resolves the user id lazily after credentials succeed and memoizes it for that plugin instance. A missing credential therefore does not create `.userid`, while the first authorized provider request can create it even when `DSH_TELEMETRY_DISABLED` is set. The direct adapter constructor accepts a `resolveUserId` dependency so wire behavior remains deterministic in unit tests.
|
||||
|
||||
Both headers are model-hidden HTTP metadata sent to the resolved `baseURL`. They are absent from the JSON request body and do not become model-visible inputs or session events. A configured gateway receives them. Telemetry sharing controls only telemetry export and does not disable provider request identity.
|
||||
|
||||
## Verification
|
||||
|
||||
- The mock provider asserts that an authorized request carries the same user id returned by `getOrCreateAnonymousUserId()` and omits the session header when no session id is supplied.
|
||||
- The session-identity wire test asserts both headers and preserves the exact supplied session id.
|
||||
- A direct-adapter test asserts that user-id resolution happens once per stream, while the keyless configuration test proves a credential failure does not create `.userid`.
|
||||
- The real Loader composition test asserts that the assembled plugin uses the shared user-id package rather than a test-only value.
|
||||
- No keyless snapshot changes because the headers are not model-visible or user-visible transcript content.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
| Rejected | Reason |
|
||||
|---|---|
|
||||
| Add the id to generic `attributionHeaders()` | That helper is provider-neutral and static; a per-user value there would reach unrelated providers and violate its app-identity privacy contract |
|
||||
| Configure a fixed custom header in `cordis.yml` | Deployment configuration cannot derive the current session id and would expose a stable identity as mutable config instead of using its owning runtime contract |
|
||||
| Mint a DeepSeek-specific user id | Provider requests could not correlate with telemetry and feedback for the same harness home |
|
||||
| Disable the header with telemetry sharing | Provider request identity and telemetry export have different recipients and purposes; one switch would hide the actual privacy boundary |
|
||||
| Put the id in OpenAI-compatible `user` or `metadata` request fields | Body fields can affect provider schema, logging, caching, tokenization, or model-visible reconstruction; HTTP metadata preserves the intended boundary |
|
||||
|
||||
## Consequences
|
||||
|
||||
- DeepSeek support can correlate requests across sessions by one anonymous harness-home id and within a conversation by the durable session id.
|
||||
- The first authorized DeepSeek request may create `$DSH_HOME/.userid` independently of telemetry export.
|
||||
- Custom DeepSeek gateways receive the stable user id and any available session id, so operators must treat the configured `baseURL` as an identity recipient.
|
||||
- The request body, prompt, token count, KV-cache identity, and session log remain unchanged.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Agent Note: DeepSeek 请求用户与会话身份头部
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-11-deepseek-request-user-id-header.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
当调用方提供 `GenerateOptions.sessionId` 时，直连 DeepSeek 请求已携带 `x-deepseek-harness-session-id`，让提供方侧支持与诊断可以关联同一对话中的多个轮次。但请求缺少跨会话的稳定身份，而 harness 已为遥测与反馈持久化匿名用户 id。另行生成 id 会破坏关联；把它放进提供方无关的归属辅助函数，则会让每个 HTTP 适配器都发送稳定的逐用户标识。
|
||||
|
||||
用户 id 是传输元数据，不是模型输入。它不得进入请求体、提示词、token 计量、KV cache 身份或会话日志。发送目标是适配器解析后的 `baseURL`，既可能是 DeepSeek 自身，也可能是配置的网关，因此必须明确隐私边界。
|
||||
|
||||
## 决策
|
||||
|
||||
`dsh-llm-deepseek` 在凭据解析成功后发出的每个提供方请求上发送 `x-deepseek-harness-user-id`。该值来自 `@deepseek-ai/dsh-user-id`，因此与同一 `$DSH_HOME` 的 OpenTelemetry Resource `user.id` 及 `/feedback` 确认一致。适配器继续仅在存在 `GenerateOptions.sessionId` 时发送 `x-deepseek-harness-session-id`；普通 agent、标题生成与压缩请求由 agent loop 提供当前持久化 `Session.id`。
|
||||
|
||||
插件在凭据解析成功后惰性获取用户 id，并在该插件实例内缓存。缺少凭据不会创建 `.userid`；即使设置了 `DSH_TELEMETRY_DISABLED`，首个已授权的提供方请求仍可能创建它。直连适配器构造函数接收 `resolveUserId` 依赖，使线路行为可在单元测试中保持确定性。
|
||||
|
||||
两个头部都是发送到解析后 `baseURL` 的模型不可见 HTTP 元数据。它们不在 JSON 请求体中，也不会成为模型可见输入或会话事件。配置的网关会收到它们。遥测共享只控制遥测导出，不会禁用提供方请求身份。
|
||||
|
||||
## 验证
|
||||
|
||||
- mock 提供方断言已授权请求携带 `getOrCreateAnonymousUserId()` 返回的同一用户 id，并在未提供会话 id 时省略会话头部。
|
||||
- 会话身份线路测试断言两个头部都存在，并原样保留传入的会话 id。
|
||||
- 直连适配器测试断言每条 stream 仅解析一次用户 id，keyless 配置测试则证明凭据失败不会创建 `.userid`。
|
||||
- 真实 Loader 组合测试断言组装后的插件使用共享 user-id 包，而非测试专用值。
|
||||
- 无需修改 keyless snapshot，因为这些头部不是模型可见或用户可见的 transcript 内容。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
| 已否决 | 原因 |
|
||||
|---|---|
|
||||
| 把 id 加进通用 `attributionHeaders()` | 该辅助函数是提供方无关且静态的；加入逐用户值会把它发送给无关提供方，并违反其应用身份隐私契约 |
|
||||
| 在 `cordis.yml` 中配置固定自定义头部 | 部署配置无法推导当前会话 id，且会把稳定身份暴露为可变配置，而不是使用其所属运行时契约 |
|
||||
| 生成 DeepSeek 专用用户 id | 提供方请求将无法与同一 harness home 的遥测和反馈关联 |
|
||||
| 随遥测共享关闭该头部 | 提供方请求身份与遥测导出的接收方和目的不同；共用开关会掩盖真实隐私边界 |
|
||||
| 把 id 放进 OpenAI 兼容的 `user` 或 `metadata` 请求字段 | body 字段可能影响提供方 schema、日志、缓存、token 化或模型可见重建；HTTP 元数据可保留预期边界 |
|
||||
|
||||
## 后果
|
||||
|
||||
- DeepSeek 支持可以通过一个匿名 harness-home id 跨会话关联请求，并通过持久化 session id 关联同一对话。
|
||||
- 首个已授权 DeepSeek 请求可独立于遥测导出创建 `$DSH_HOME/.userid`。
|
||||
- 自定义 DeepSeek 网关会收到稳定用户 id 与可用的会话 id，因此运维方必须将配置的 `baseURL` 视为身份接收方。
|
||||
- 请求体、提示词、token 数、KV cache 身份和会话日志保持不变。
|
||||
Reference in New Issue
Block a user