relay-dsh-plugin-manager 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented here.
 
+## [0.2.5] - 2026-09-07
+
+### Added
+
+- Default-on anonymous operational analytics for plugin-manager use and
+  manager-executed install start, success, and failure outcomes, with explicit
+  opt-out through `RELAY_PLUGIN_MANAGER_TELEMETRY=0`.
+- First-party delivery to the Registry's versioned telemetry endpoint; the npm
+  package contains no PostHog host or project key.
+- A locally persisted random anonymous identifier; search text, installed
+  inventory, local paths, command output, error messages, IP geolocation, and
+  account identity are excluded.
+
 ## [0.2.4] - 2026-09-05
 
 ### Changed

package/README.md

@@ -100,6 +100,32 @@ missing companion peers, waits for one confirmation, and runs the installs in
 sequence. Completed changes that still need restart are reported explicitly as
 restart-required or waiting for a manual restart.
 
+### Anonymous usage analytics
+
+Anonymous operational analytics are enabled by default to measure plugin-manager
+search and installation outcomes. To opt out without disabling plugin management,
+set this when starting DSH Web:
+
+```bash
+RELAY_PLUGIN_MANAGER_TELEMETRY=0 dsh web
+```
+
+The manager sends events only to the first-party
+`https://dsh-plugins.tech/v1/telemetry/events` endpoint. The Registry validates
+the exact event schema and forwards accepted events to its PostHog analytics
+project. The plugin records only the manager action type and plugin
+install start, success, or failure events produced by the manager. Install
+events contain the public package name, activation/restart booleans, and a
+bounded error code. Search terms, conversation content, local paths, command
+output, error text, IP geolocation, and account identity are not sent. A random
+anonymous ID is stored in `.relay-plugin-manager/telemetry.json` inside the
+current Profile to avoid counting one installation as many users; delete the
+file to reset it.
+
+These events measure manager use and manager-executed installs. They do not
+claim that another plugin's feature was actually used merely because it loaded
+or activated.
+
 ### DSH Registry discovery provider
 
 The source-only Registry search provider uses `https://dsh-plugins.tech` by

package/README.zh.md

@@ -95,6 +95,26 @@ dsh web
 一次确认后依次安装。修改完成但仍需重启时，状态会明确区分“需要另行重启”和
 “等待人工重启”。
 
+### 匿名使用统计
+
+匿名运行统计默认开启，用于衡量插件管理器的搜索和安装结果。如需关闭，可在启动
+DSH Web 时设置以下变量；关闭统计不会影响插件管理功能：
+
+```bash
+RELAY_PLUGIN_MANAGER_TELEMETRY=0 dsh web
+```
+
+管理器只向第一方接口 `https://dsh-plugins.tech/v1/telemetry/events` 发送事件；Registry
+会校验严格的事件结构，再把通过校验的事件转发到自己的 PostHog 项目。统计只记录
+管理器操作类型，以及由管理器执行的插件安装开始、成功或失败；安装
+事件包含公开的插件包名、是否激活、是否需要重启和有限错误代码。不会发送搜索词、
+对话内容、本地路径、命令输出、错误文本、IP 地理位置或登录身份。一个随机匿名 ID
+保存在当前 Profile 的 `.relay-plugin-manager/telemetry.json`，用于避免把同一安装重复
+计算为多个用户；删除该文件即可重置。
+
+这些数据只能说明“插件管理器被使用”和“管理器执行了安装”，不会把插件加载或
+激活推断成其他插件的真实功能使用。
+
 ### DSH Registry 发现数据源
 
 来源级 Registry 搜索 provider 默认使用 `https://dsh-plugins.tech`。可设置插件

package/SPEC.md

@@ -51,6 +51,7 @@ service.
 | PM-024 | GitHub owner discovery recognizes `owner:<name>`, owner-only GitHub identities, `<name> DSH plugins`, and conservative bare identifiers containing digits. It sends a typed owner intent to providers, uses GitHub's exact owner qualifier, case-insensitively verifies returned ownership, and ranks verified owner matches first. Owner-only `inspect` fails with an actionable error directing callers to search. Every emitted repository identity is accepted by `inspect`; every recommended immutable source is accepted by `plan`. |
 | PM-025 | Register a read-only DSH Registry provider against `https://dsh-plugins.tech` by default, with an explicit `registryUrl: false` opt-out and HTTPS-only configuration override. Send only the task query, inferred Chinese/English locale and result limit; accept only source-level untrusted DiscoveryEntry records, convert their npm/GitHub descriptors into core-owned source types, and submit them to the same mandatory local inspection used by all providers. Registry responses cannot supply exact versions, approval, plans, installers, or profile state, and provider failure remains isolated. |
 | PM-026 | Return search candidates as one explicit, one-based relevance-ranked result page with a default and maximum size of 20. The model-facing contract requires the Agent to preserve rank order, surface every possibly relevant returned candidate, exclude candidates whose purpose is clearly unrelated, and MUST NOT silently reduce the remaining page to a fixed top-N. Ranking remains distinct from compatibility, security, or installation approval. |
+| PM-027 | Send default-on anonymous operational telemetry only to the Registry's canonical first-party HTTPS endpoint under schema `1.0.0`, with explicit `RELAY_PLUGIN_MANAGER_TELEMETRY=0` or `telemetry.enabled: false` opt-out. Events are limited to manager discovery/planning type and manager-executed install start/success/failure, including per-plugin batch outcomes. Never send raw search text, conversation content, Profile state, installed inventory, paths, credentials, command output, error text, account identity, PostHog configuration, or client timestamps. Store only a stable random anonymous ID locally, create it lazily, and never let storage, validation, network, Registry, or analytics failure affect plugin management. |
 
 ## Command Grammar
 

package/docs/acceptance.md

@@ -39,6 +39,7 @@ This matrix is the release contract. Tests name the relevant `PM-*` ids.
 | A-031 search results feed one immutable multi-install plan through the real DSH tool and user-question registries; no mutation starts before one exact UI approval, then child installs execute serially and approval replay is rejected | PM-002, PM-005, PM-009, PM-010, PM-015, PM-023, PM-024 | combined host/tool/search/question/manager integration |
 | A-032 The default formal Registry searches at least 3,000 source records for Chinese task text, English task text, exact plugin names and an honest empty result; every returned source is locally inspected to an immutable npm version or GitHub commit, while Registry authority remains source-only, untrusted, non-recommending and non-approving | PM-005, PM-006, PM-025 | provider/unit/host integration tests plus `npm run acceptance:live:registry` |
 | A-033 Search defaults to a complete twenty-candidate result page, assigns stable one-based display ranks after merge and deduplication, and tells the Agent to exclude clearly unrelated purposes while surfacing every remaining possibly relevant candidate without silent fixed-count truncation | PM-005, PM-026 | search orchestration and conversation-tool contract unit tests plus Agent answer acceptance |
+| A-034 Default manager actions send only schema-valid anonymous envelopes to the first-party Registry endpoint, reuse a lazily created random ID, record each attempted batch install outcome, and continue normally through storage or delivery failure; explicit opt-out creates no ID and makes no telemetry request | PM-027 | telemetry unit tests + manager integration event assertions + Registry endpoint contract and end-to-end PostHog verification |
 
 ## Test Layers
 

package/lib/index.d.ts

@@ -2,6 +2,18 @@ import { a as PluginSearchRuntime, c as PluginSource, i as PluginSearchRequest,
 import { spawn } from "node:child_process";
 import { Context } from "@deepseek-ai/cordis";
 
+//#region src/telemetry.d.ts
+type TelemetryProperty = string | number | boolean;
+interface Telemetry {
+  capture(event: string, properties?: Readonly<Record<string, TelemetryProperty>>): void;
+}
+interface TelemetryConfig {
+  /** Anonymous operational telemetry is enabled unless this is explicitly false. */
+  enabled?: boolean;
+  /** Registry telemetry endpoint. Only the canonical service or localhost is accepted. */
+  endpoint?: string;
+}
+//#endregion
 //#region src/profile.d.ts
 interface PackageSurface {
   packageName: string;
@@ -238,6 +250,7 @@ interface PluginManagerDependencies {
   operations?: OperationTracker;
   fetchOptions?: Omit<FetchOptions, 'signal'>;
   hmrTimeoutMs?: number;
+  telemetry?: Telemetry;
 }
 interface DiscoverRequest {
   action: 'list' | 'search' | 'inspect' | 'status';
@@ -301,7 +314,9 @@ declare class PluginManager {
   private readonly operations;
   private readonly fetchOptions;
   private readonly hmrTimeoutMs;
+  private readonly telemetry;
   constructor(dependencies: PluginManagerDependencies);
+  private capture;
   private loaderEntries;
   list(): PluginStatus[];
   discover(request: DiscoverRequest, signal?: AbortSignal): Promise<unknown>;
@@ -331,8 +346,9 @@ declare const DEFAULT_REGISTRY_ORIGIN = "https://dsh-plugins.tech";
 interface Config {
   allowRestart?: boolean;
   registryUrl?: string | false;
+  telemetry?: TelemetryConfig;
 }
 declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, apply, inject, name };
+export { Config, DEFAULT_REGISTRY_ORIGIN, type DiscoverRequest, type InstallManyItemResult, type InstallManyItemStatus, type InstallManyResult, type MutationResult, type PlanRequest, type PluginInspection, PluginManager, type PluginSearchCandidate, type PluginSearchMatch, type PluginSearchProvider, type PluginSearchRequest, type PluginSource, type TelemetryConfig, apply, inject, name };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -1223,11 +1223,56 @@ const PROTECTED_ENTRY_IDS = /* @__PURE__ */ new Set([
 	"webserver",
 	"web-runtime"
 ]);
+const TELEMETRY_ERROR_CODES = /* @__PURE__ */ new Set([
+	"INVALID_SOURCE",
+	"INVALID_NPM_SPEC",
+	"INVALID_NPM_VERSION",
+	"INVALID_GITHUB_SPEC",
+	"INVALID_GITHUB_REF",
+	"GITHUB_OWNER_REQUIRES_SEARCH",
+	"IMMUTABLE_SOURCE_REQUIRED",
+	"NETWORK_ERROR",
+	"SOURCE_HTTP_ERROR",
+	"INVALID_SOURCE_METADATA",
+	"INVALID_PLUGIN_MANIFEST",
+	"NOT_DSH_PLUGIN",
+	"PACKAGE_NAME_MISMATCH",
+	"NPM_INTEGRITY_MISSING",
+	"INVALID_SEARCH_QUERY",
+	"INVALID_ACTION",
+	"INVALID_BATCH",
+	"DUPLICATE_SEARCH_PROVIDER",
+	"PROFILE_READ_FAILED",
+	"PROFILE_WRITE_FAILED",
+	"PLUGIN_NOT_INSTALLED",
+	"PLUGIN_ALREADY_INSTALLED",
+	"ENABLEMENT_UNSUPPORTED",
+	"ENABLEMENT_CONFLICT",
+	"PROTECTED_PLUGIN",
+	"CONFIRMATION_REQUIRED",
+	"CONFIRMATION_INVALID",
+	"CONFIRMATION_EXPIRED",
+	"CONFIRMATION_REPLAYED",
+	"PLAN_STALE",
+	"OPERATION_NOT_FOUND",
+	"DSH_COMMAND_FAILED",
+	"BATCH_INSTALL_FAILED",
+	"POSTCONDITION_FAILED",
+	"RESTART_UNAVAILABLE"
+]);
 function safePackageName(value) {
 	const name = value?.trim() ?? "";
 	if (!NPM_NAME.test(name)) fail("INVALID_NPM_SPEC", "A valid installed package name is required.");
 	return name;
 }
+function queryLengthBucket(value) {
+	const length = value?.trim().length ?? 0;
+	if (length === 0) return "empty";
+	if (length <= 10) return "1-10";
+	if (length <= 30) return "11-30";
+	if (length <= 80) return "31-80";
+	return "81+";
+}
 function commandResult(result) {
 	return {
 		exitCode: result.exitCode,
@@ -1241,6 +1286,10 @@ function operationError(error) {
 		message: error instanceof Error ? error.message : String(error)
 	};
 }
+function telemetryErrorCode(error) {
+	const code = operationError(error).code;
+	return code !== void 0 && TELEMETRY_ERROR_CODES.has(code) ? code : "UNKNOWN";
+}
 function installedPackageManifest(profileDir, packageName) {
 	try {
 		return JSON.parse(readFileSync(join(profileDir, "node_modules", packageName, "package.json"), "utf8"));
@@ -1265,6 +1314,7 @@ var PluginManager = class {
 	operations;
 	fetchOptions;
 	hmrTimeoutMs;
+	telemetry;
 	constructor(dependencies) {
 		this.profileDir = dependencies.profileDir;
 		this.searchRuntime = dependencies.searchRuntime;
@@ -1277,6 +1327,12 @@ var PluginManager = class {
 		this.operations = dependencies.operations ?? new OperationTracker();
 		this.fetchOptions = dependencies.fetchOptions ?? {};
 		this.hmrTimeoutMs = dependencies.hmrTimeoutMs ?? 5e3;
+		this.telemetry = dependencies.telemetry ?? { capture() {} };
+	}
+	capture(event, properties = {}) {
+		try {
+			this.telemetry.capture(event, properties);
+		} catch {}
 	}
 	loaderEntries() {
 		if (this.loader === void 0) return [];
@@ -1297,6 +1353,14 @@ var PluginManager = class {
 		return listPluginStatuses(this.profileDir, this.loaderEntries());
 	}
 	async discover(request, signal) {
+		this.capture("plugin_manager_used", {
+			surface: "discover",
+			action: request.action,
+			...request.action === "search" ? {
+				has_query: (request.query?.trim().length ?? 0) > 0,
+				query_length_bucket: queryLengthBucket(request.query)
+			} : {}
+		});
 		if (request.action === "list") return {
 			profile: "web",
 			plugins: this.list()
@@ -1360,6 +1424,11 @@ var PluginManager = class {
 		});
 	}
 	async plan(request, signal) {
+		this.capture("plugin_manager_used", {
+			surface: "plan",
+			action: request.operation,
+			...request.operation === "install_many" ? { batch_size: request.sources?.length ?? 0 } : {}
+		});
 		if (request.operation === "install_many") return await this.planInstallMany(request.sources, signal);
 		if (request.operation === "restart") {
 			if (!this.restarter.available()) fail("RESTART_UNAVAILABLE", "Automatic restart is unavailable in this deployment.");
@@ -1486,7 +1555,22 @@ var PluginManager = class {
 			if (plan.packageName === void 0) fail("POSTCONDITION_FAILED", "Mutation plan has no package name.");
 			if (plan.action === "install" || plan.action === "update") {
 				if (plan.installSpec === void 0) fail("POSTCONDITION_FAILED", "Install/update plan has no immutable source.");
-				return this.withRestartGuidance(await this.installOrUpdate(plan.action, plan.packageName, plan.installSpec, context), automaticRestartAvailable);
+				if (plan.action === "install") this.capture("plugin_install_started", { plugin_name: plan.packageName });
+				try {
+					const result = this.withRestartGuidance(await this.installOrUpdate(plan.action, plan.packageName, plan.installSpec, context), automaticRestartAvailable);
+					if (plan.action === "install") this.capture("plugin_install_succeeded", {
+						plugin_name: plan.packageName,
+						activated: result.activated === true,
+						restart_required: result.restartRequired
+					});
+					return result;
+				} catch (error) {
+					if (plan.action === "install") this.capture("plugin_install_failed", {
+						plugin_name: plan.packageName,
+						error_code: telemetryErrorCode(error)
+					});
+					throw error;
+				}
 			}
 			if (plan.action === "remove") return this.withRestartGuidance(await this.remove(plan.packageName, context), automaticRestartAvailable);
 			return this.withRestartGuidance(await this.toggle(plan.action, plan.packageName, context), automaticRestartAvailable);
@@ -1534,6 +1618,10 @@ var PluginManager = class {
 				break;
 			}
 			context.progress(`install_many: ${index + 1}/${items.length} installing ${item.packageName}`);
+			this.capture("plugin_install_started", {
+				plugin_name: item.packageName,
+				batch: true
+			});
 			try {
 				const result = this.withRestartGuidance(await this.installOrUpdate("install", item.packageName, item.installSpec, context), automaticRestartAvailable);
 				results.push({
@@ -1542,6 +1630,12 @@ var PluginManager = class {
 					status: this.mutationCompletion(result, automaticRestartAvailable).status,
 					result
 				});
+				this.capture("plugin_install_succeeded", {
+					plugin_name: item.packageName,
+					batch: true,
+					activated: result.activated === true,
+					restart_required: result.restartRequired
+				});
 			} catch (error) {
 				results.push({
 					packageName: item.packageName,
@@ -1549,6 +1643,11 @@ var PluginManager = class {
 					status: context.signal.aborted ? "cancelled" : "failed",
 					error: operationError(error)
 				});
+				this.capture("plugin_install_failed", {
+					plugin_name: item.packageName,
+					batch: true,
+					error_code: telemetryErrorCode(error)
+				});
 				skipRemaining(index + 1);
 				break;
 			}
@@ -2078,6 +2177,107 @@ var DshCliRunner = class {
 	}
 };
 //#endregion
+//#region src/telemetry.ts
+const DEFAULT_ENDPOINT = "https://dsh-plugins.tech/v1/telemetry/events";
+const STATE_DIRECTORY = ".relay-plugin-manager";
+const STATE_FILE = "telemetry.json";
+const SCHEMA_VERSION = "1.0.0";
+const EVENTS = /* @__PURE__ */ new Set([
+	"plugin_manager_used",
+	"plugin_install_started",
+	"plugin_install_succeeded",
+	"plugin_install_failed"
+]);
+const noopTelemetry = Object.freeze({ capture() {} });
+function safeEndpoint(value) {
+	try {
+		const parsed = new URL(value ?? DEFAULT_ENDPOINT);
+		const local = [
+			"localhost",
+			"127.0.0.1",
+			"::1"
+		].includes(parsed.hostname);
+		const canonical = parsed.protocol === "https:" && parsed.hostname === "dsh-plugins.tech";
+		if (!local && !canonical || local && !["http:", "https:"].includes(parsed.protocol)) return null;
+		if (parsed.username !== "" || parsed.password !== "" || parsed.pathname !== "/v1/telemetry/events" || parsed.search !== "" || parsed.hash !== "") return null;
+		return parsed.href;
+	} catch {
+		return null;
+	}
+}
+function anonymousId(profileDir, random) {
+	const directory = join(profileDir, STATE_DIRECTORY);
+	const path = join(directory, STATE_FILE);
+	try {
+		const existing = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof existing.anonymousId === "string" && /^[0-9a-f-]{36}$/iu.test(existing.anonymousId)) return existing.anonymousId;
+	} catch {}
+	const id = random();
+	try {
+		mkdirSync(directory, {
+			recursive: true,
+			mode: 448
+		});
+		writeFileSync(path, `${JSON.stringify({ anonymousId: id })}\n`, { mode: 384 });
+	} catch {}
+	return id;
+}
+function allowedProperties(event, properties) {
+	const keys = new Set(Object.keys(properties));
+	const exact = (required, optional = []) => {
+		if (required.some((key) => !keys.has(key))) return false;
+		return [...keys].every((key) => required.includes(key) || optional.includes(key));
+	};
+	if (event === "plugin_manager_used") {
+		if (!exact(["surface", "action"], [
+			"has_query",
+			"query_length_bucket",
+			"batch_size"
+		])) return false;
+		if (!["discover", "plan"].includes(String(properties.surface))) return false;
+		return typeof properties.action === "string";
+	}
+	if (event === "plugin_install_started") return exact(["plugin_name"], ["batch"]);
+	if (event === "plugin_install_succeeded") return exact([
+		"plugin_name",
+		"activated",
+		"restart_required"
+	], ["batch"]);
+	if (event === "plugin_install_failed") return exact(["plugin_name", "error_code"], ["batch"]);
+	return false;
+}
+function createTelemetry(profileDir, config, runtime = {
+	fetch,
+	random: randomUUID
+}) {
+	if (config?.enabled === false) return noopTelemetry;
+	const endpoint = safeEndpoint(config?.endpoint);
+	if (endpoint === null) return noopTelemetry;
+	let distinctId;
+	return Object.freeze({ capture(event, properties = {}) {
+		if (!EVENTS.has(event) || !allowedProperties(event, properties)) return;
+		distinctId ??= anonymousId(profileDir, runtime.random);
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 5e3);
+		timeout.unref?.();
+		try {
+			runtime.fetch(endpoint, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					schema_version: SCHEMA_VERSION,
+					anonymous_id: distinctId,
+					event,
+					properties
+				}),
+				signal: controller.signal
+			}).catch(() => void 0).finally(() => clearTimeout(timeout));
+		} catch {
+			clearTimeout(timeout);
+		}
+	} });
+}
+//#endregion
 //#region src/index.ts
 const name = "relay-dsh-plugin-manager";
 const inject = [
@@ -2090,6 +2290,10 @@ const inject = [
 const DEFAULT_REGISTRY_ORIGIN = "https://dsh-plugins.tech";
 function apply(ctx, config = {}) {
 	const profileDir = profileDirectory("web");
+	const telemetry = config.telemetry ?? {
+		enabled: process.env.RELAY_PLUGIN_MANAGER_TELEMETRY !== "0",
+		endpoint: process.env.RELAY_PLUGIN_MANAGER_TELEMETRY_ENDPOINT
+	};
 	ctx.pluginSearch.register(npmSearchProvider());
 	ctx.pluginSearch.register(githubSearchProvider());
 	const configuredRegistryUrl = config.registryUrl ?? process.env.DSH_PLUGIN_REGISTRY_URL?.trim();
@@ -2101,7 +2305,8 @@ function apply(ctx, config = {}) {
 		runner: new DshCliRunner(),
 		hot: new HotRuntime(ctx, profileDir),
 		restarter: new DshRestarter({ allowRestart: config.allowRestart }),
-		loader: ctx.loader
+		loader: ctx.loader,
+		telemetry: createTelemetry(profileDir, telemetry)
 	}));
 }
 //#endregion