diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml index 081e9ee4ca..b1a81228cf 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.i18n.yaml @@ -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 -2026-07-24-single-harness-home-resolver.md: 9212a424db5fa0b77c0b482e29527a72f1656a0c -2026-07-24-single-harness-home-resolver.zh.md: 33f3fea5145497924a6a6d9738e076bedb781943 +2026-07-24-single-harness-home-resolver.md: 10ed0e9f1fd6ac4630d92a66953fdf1d52b3b5f1 +2026-07-24-single-harness-home-resolver.zh.md: 1ce56281357595de134ddea285c8c2e0c1801ce9 diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md index 9212a424db..10ed0e9f1f 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md +++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.md @@ -32,7 +32,7 @@ An empty or whitespace-only `$DSH_HOME` is treated as unset, matching the guard **Adopt XDG (honor `$XDG_CONFIG_HOME`, or split config/data/cache into separate trees).** Considered and dropped in favor of one obvious root. A single `$DSH_HOME || ~/.dsh` ground truth matches `~/.claude` / `~/.aws`, needs no per-kind reclassification of every `~/.dsh` consumer, and leaves no resolver asymmetry to reconcile. Telemetry aligning onto the same root — rather than keeping its own XDG path — is precisely the divergence this removes. -**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. +**Keep telemetry's own config dir.** Its `deepseek-harness` namespace and separate XDG policy were the lone exception to the `dsh`/`~/.dsh` convention. Folding it onto the shared resolver is what makes "one home fact" true. The cost is that the anonymous id becomes scoped to `$DSH_HOME` rather than the machine: a project that points `DSH_HOME` at a repo-local path (or a command that loads a project `.env` before telemetry) gets a home-local id, so the id counts harness homes, not machines. This is accepted as the intended meaning of single-root — a relocated `$DSH_HOME` moves *all* harness state, telemetry identity included — and the module contract is stated as per-harness-home rather than per-machine. A machine-global identity that ignored `$DSH_HOME` would reintroduce exactly the second home policy this Note removes. ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md index 33f3fea514..1ce5628135 100644 --- a/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-24-single-harness-home-resolver.zh.md @@ -32,7 +32,7 @@ explicit configured path > $DSH_HOME > ~/.dsh **采用 XDG（遵从 `$XDG_CONFIG_HOME`，或把 config/data/cache 拆分到各自的目录树）。** 经过考虑后放弃，转而采用一个显而易见的根目录。单一的 `$DSH_HOME || ~/.dsh` 基准事实与 `~/.claude` / `~/.aws` 一致，无需对每个 `~/.dsh` 消费方按类别重新归类，也不留下任何需要协调的解析器不对称。telemetry 对齐到同一根目录——而不是保留自己的 XDG 路径——正是本决策所要消除的那种分歧。 -**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。 +**保留 telemetry 自己的 config 目录。** 它的 `deepseek-harness` 命名空间和独立的 XDG 策略是唯一违背 `dsh`/`~/.dsh` 约定的例外。把它折叠到共享解析器上，才让"单一 home 事实"成真。代价是匿名 id 的作用域从机器变成了 `$DSH_HOME`：若某个项目把 `DSH_HOME` 指向仓库本地路径（或某条命令在 telemetry 之前加载了项目的 `.env`），得到的就是 home 本地的 id，因此该 id 统计的是 harness home，而非机器。这被接受为单一根目录的应有含义——重定位 `$DSH_HOME` 会移动*全部* harness 状态，telemetry 身份也在其中——模块契约据此表述为 per-harness-home 而非 per-machine。一个忽略 `$DSH_HOME` 的机器级全局身份，恰恰会重新引入本 Note 所要消除的那第二套 home 策略。 ## 影响 diff --git a/packages/sdk/telemetry/README.md b/packages/sdk/telemetry/README.md index fd3573af86..c2966b1f38 100644 --- a/packages/sdk/telemetry/README.md +++ b/packages/sdk/telemetry/README.md @@ -7,7 +7,7 @@ Launcher-side telemetry primitives for the dsh-sdk toolchain. This is a plain li | `SecretRedactor` | Conservative safety backstop: replaces secret-shaped values (secret-like keys, known token shapes, PEM blocks, URL credentials, high-entropy opaque tokens) with a placeholder in both parsed values (`redactValue`) and raw text (`redactText`). Never drops a field or line. | | `ConsentResolver` | Parses (never boots) a project `cordis.yml` and reads the telemetry entry's enabled/disabled state as consent; `DO_NOT_TRACK`/CI env force a hard opt-out. | | `buildTelemetryPayload` | Assembles `{command, durationMs, success, cordisYmlContent, packageJsonContent}`, running the redactor over the full `cordis.yml` and `package.json` text. Never reads `.env`; `package.json` ships only alongside a `cordis.yml`, so a command run in a non-SDK directory never uploads that directory's unrelated manifest. | -| `getOrCreateAnonymousId` | Random UUID persisted in the per-user harness home resolved by [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) (never in the project, never derived from git). | +| `getOrCreateAnonymousId` | Random UUID persisted in the harness home resolved by [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) (`$DSH_HOME` > `~/.dsh`), scoped to that home rather than the machine, never derived from git. | | `TelemetryReporter` | Fire-and-forget send: `report()` never blocks or throws; delivery resolves on every path; `flush()` optionally drains in-flight sends within a cap. | Consent is carried by the telemetry entry in `cordis.yml`, so disabling telemetry is disabling that entry. Telemetry reports by default and is off only when a present telemetry entry is explicitly `disabled`: a missing `cordis.yml` (first `create`), an enabled entry, or a `cordis.yml` with no telemetry entry all report. `DO_NOT_TRACK`/CI always deny. The no-config and absent-entry defaults are configurable on `ConsentResolver`. diff --git a/packages/sdk/telemetry/src/anonymous-id.ts b/packages/sdk/telemetry/src/anonymous-id.ts index 90d7516282..dcfe08c158 100644 --- a/packages/sdk/telemetry/src/anonymous-id.ts +++ b/packages/sdk/telemetry/src/anonymous-id.ts @@ -1,11 +1,14 @@ /** - * Per-machine anonymous telemetry id. + * Per-harness-home anonymous telemetry id. * - * The id is a random UUID persisted in the per-user harness home — never in - * the project, and never derived from the git remote, repository URL, or any - * other identifying source (a derived id would make "anonymous" a fiction). The - * same id is reused across projects on one machine so telemetry counts machines, - * not repositories. + * The id is a random UUID persisted directly in the harness home resolved by + * {@link resolveDshHome} (`$DSH_HOME` > `~/.dsh`), and never derived from the + * git remote, repository URL, or any other identifying source (a derived id + * would make "anonymous" a fiction). The id is scoped to the harness home, not + * the machine: every command sharing one `$DSH_HOME` reuses the same id, so the + * default `~/.dsh` counts per-OS-user home directories, while a relocated + * `$DSH_HOME` moves the id with the rest of the harness data — the single-root + * convention this package shares, not a telemetry-specific policy. * * @module @deepseek-ai/dsh-telemetry/anonymous-id */ @@ -16,7 +19,7 @@ import { dirname, join } from 'node:path' import type { Branded } from '@deepseek-ai/dsh-brand' import { resolveDshHome } from '@deepseek-ai/dsh-paths' -/** A machine-scoped anonymous telemetry id (random UUID v4). */ +/** A harness-home-scoped anonymous telemetry id (random UUID v4). */ export type AnonymousId = Branded<'AnonymousId'> /** Default file, inside the harness home, storing the anonymous id. */ @@ -68,11 +71,11 @@ async function readPersistedId(file: string): Promise { } /** - * Return the machine's anonymous id, creating and persisting one on first use. + * Return the harness home's anonymous id, creating and persisting one on first use. * Persistence is best-effort: a write failure still returns a usable id for the * current run so telemetry is never blocked by config-dir permissions. * @param options - config-location and UUID-generation seams. - * @returns the stable per-machine anonymous id. + * @returns the stable per-harness-home anonymous id. */ export async function getOrCreateAnonymousId(options: AnonymousIdOptions = {}): Promise { const file = join(globalConfigDir(options), ANONYMOUS_ID_FILE_NAME)