Merge remote-tracking branch 'origin/master' into worktree/web-theme-settings-integration-fde706
This commit is contained in:
Yichen Jiang
@@ -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/architecture/2026-08-07-shared-feedback-telemetry-user-id.md
|
||||
2026-08-07-shared-feedback-telemetry-user-id.md: 6d4020828cb1f2ab3de0328c8959a18a0fcfe6c4
|
||||
2026-08-07-shared-feedback-telemetry-user-id.zh.md: 892fa0f848d656609885d008ab36e3ebbe09b992
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Shared feedback and telemetry anonymous user id
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-07-shared-feedback-telemetry-user-id.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
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.
|
||||
|
||||
## 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`.
|
||||
|
||||
The extraction preserves the existing random UUID, home resolution, process memo, exclusive-create concurrency, corruption replacement, and best-effort write semantics. It does not unify the dsh-sdk launcher's separate `telemetry.json` identity.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
| Rejected | Reason |
|
||||
|---|---|
|
||||
| Import the helper from `session-telemetry-otel` | Couples feedback to an optional exporter backend and forms a reverse dependency cycle once telemetry exports feedback |
|
||||
| Duplicate the persistence helper in feedback | Two implementations of one file contract can drift and race with different validation or failure semantics |
|
||||
| Generate a separate feedback user id | The acknowledgement could not correlate with the OTel Resource and would not satisfy the reporting purpose |
|
||||
| Move the launcher telemetry id too | The launcher feed is not a consumer of `.userid`; unifying unrelated stores remains out of scope |
|
||||
|
||||
## Consequences
|
||||
|
||||
- One harness home now has one anonymous id shared by feedback acknowledgements and session telemetry exports.
|
||||
- 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 original anonymous-user-id Note remains authoritative for storage and privacy semantics, while this Note supersedes only its OTel-local ownership decision.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: 反馈与遥测共享匿名用户 id
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-07-shared-feedback-telemetry-user-id.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
OpenTelemetry 后端已在 `$DSH_HOME/.userid` 中持久化一个匿名 UUID。`/feedback` 需要同时报告接收反馈的会话 id 与用户 id，以便运维人员将确认文本与导出的记录相关联。复制该身份或单独生成身份会使报告的用户失去意义；从 `session-telemetry-otel` 导入身份则会让直接命令依赖导出后端，并在遥测侧挂载反馈导出时形成依赖环。
|
||||
|
||||
早先的[匿名用户 id 决策](../feature/2026-07-31-telemetry-anonymous-user-id.md)刻意将辅助函数留在 OTel 后端内，直至出现第二个真实消费方。反馈就是这个消费方。
|
||||
|
||||
## 决策
|
||||
|
||||
`@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`。
|
||||
|
||||
此次抽取保留既有的随机 UUID、home 解析、进程内缓存、独占创建并发、损坏文件替换与 best-effort 写入语义。它不会统一 dsh-sdk launcher 独立的 `telemetry.json` 身份。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
| 已否决 | 原因 |
|
||||
|---|---|
|
||||
| 从 `session-telemetry-otel` 导入辅助函数 | 使反馈耦合到可选的导出后端，并在遥测导出反馈后形成反向依赖环 |
|
||||
| 在反馈中复制持久化辅助函数 | 同一文件契约的两份实现可能发生偏差，并因校验或失败语义不同而产生竞态 |
|
||||
| 生成独立的反馈用户 id | 确认文本无法与 OTel Resource 相关联，因而不能达到报告目的 |
|
||||
| 同时移动 launcher telemetry id | launcher 回流不是 `.userid` 的消费方；统一无关存储仍不在范围内 |
|
||||
|
||||
## 后果
|
||||
|
||||
- 一个 harness home 只有一个匿名 id，由反馈确认与会话遥测导出共享。
|
||||
- 反馈包只依赖身份能力，不依赖遥测 seam 或 OTel SDK。
|
||||
- 新包由两个消费方使用，成为有充分依据的共享 seam；其空不变式伴生插件解释了为何读取私有文件并非有用的运行时关系检查。
|
||||
- 原始匿名用户 id Note 仍是存储与隐私语义的权威记录；本 Note 仅取代其中由 OTel 本地拥有身份的决策。
|
||||
Reference in New Issue
Block a user