flower-trellis 0.6.4 → 0.6.6

package/src/lib/platform-patch-adapters.js

@@ -1,8 +1,9 @@
-import { FLOWER_UPDATE_HOOK_REL } from "./flower-assets.js";
+import { FLOWER_UPDATE_HOOK_REL, FLOWER_SESSION_HOOK_REL, FLOWER_TELEMETRY_HOOK_REL } from "./flower-assets.js";
 
 const CODEX_WORKFLOW_HOOK = ".codex/hooks/inject-workflow-state.py";
 const CODEX_SESSION_START = ".codex/hooks/session-start.py";
 const CLAUDE_WORKFLOW_HOOK = ".claude/hooks/inject-workflow-state.py";
+const SESSION_PARTS = ["state", "rules", "stages"];
 
 function escapeRe(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -31,11 +32,20 @@ function resolveCommand(name, config, pythonCommand) {
   if (name === "codex-session-start") {
     return codexBase.replace(CODEX_WORKFLOW_HOOK, CODEX_SESSION_START);
   }
+  if (name === "codex-flower-telemetry") {
+    return codexBase.replace(CODEX_WORKFLOW_HOOK, `${FLOWER_TELEMETRY_HOOK_REL} --platform codex`);
+  }
   if (name === "codex-flower-update") {
     return codexBase.replace(CODEX_WORKFLOW_HOOK, FLOWER_UPDATE_HOOK_REL);
   }
   const claudeBase = findHookCommand(config, "UserPromptSubmit", CLAUDE_WORKFLOW_HOOK) ||
     `${pythonCommand} ${CLAUDE_WORKFLOW_HOOK}`;
+  if (name === "claude-session-start") {
+    return claudeBase.replace(CLAUDE_WORKFLOW_HOOK, ".claude/hooks/session-start.py");
+  }
+  if (name === "claude-flower-telemetry") {
+    return claudeBase.replace(CLAUDE_WORKFLOW_HOOK, `${FLOWER_TELEMETRY_HOOK_REL} --platform claude`);
+  }
   if (name === "claude-flower-update") {
     return claudeBase.replace(CLAUDE_WORKFLOW_HOOK, FLOWER_UPDATE_HOOK_REL);
   }
@@ -62,17 +72,28 @@ function applyJsonHookCommand({ value, operation, pythonCommand = "python3" }) {
     return { error: `JSON Hook ${event} 必须是数组` };
   }
   const groups = existing ? structuredClone(existing) : [];
+  const retainedLimits = new Map();
   for (let index = groups.length - 1; index >= 0; index -= 1) {
     const group = groups[index];
     if (!isPlainObject(group)) return { error: `JSON Hook ${event}[${index}] 必须是对象` };
     if (group.hooks === undefined) group.hooks = [];
     if (!Array.isArray(group.hooks)) return { error: `JSON Hook ${event}[${index}].hooks 必须是数组` };
-    group.hooks = group.hooks.filter((hook) => !(
-      hook?.type === "command" &&
-      typeof hook.command === "string" &&
-      hook.command.includes(commandNeedle)
-    ));
-    if (group.hooks.length === 0 && !group.matcher) groups.splice(index, 1);
+    const matched = group.hooks.filter((hook) => hook?.type === "command" &&
+      typeof hook.command === "string" && hook.command.includes(commandNeedle));
+    for (const hook of matched) {
+      const limit = hook.additionalContextLimit;
+      if (limit === undefined) continue;
+      if (!Number.isSafeInteger(limit) || limit < 0) {
+        return { error: "已有 additionalContextLimit 必须是非负整数" };
+      }
+      const part = hook.command.match(/(?:^|\s)--part\s+(state|rules|stages)(?=\s|$)/)?.[1] || "legacy";
+      if (retainedLimits.has(part) && retainedLimits.get(part) !== limit) {
+        return { error: `同一 SessionStart 分段 ${part} 存在冲突的 additionalContextLimit` };
+      }
+      retainedLimits.set(part, limit);
+    }
+    group.hooks = group.hooks.filter((hook) => !matched.includes(hook));
+    if (group.hooks.length === 0 && (matched.length > 0 || !group.matcher)) groups.splice(index, 1);
   }
 
   if (operation.operation !== "remove") {
@@ -97,7 +118,24 @@ function applyJsonHookCommand({ value, operation, pythonCommand = "python3" }) {
       else groups.push(group);
     }
     if (!Array.isArray(group.hooks)) return { error: "目标 matcher hooks 必须是数组" };
-    group.hooks.push({ type: "command", command, timeout: content.timeout });
+    const parts = content.sessionParts;
+    if (parts !== undefined && (
+      event !== "SessionStart" ||
+      !["codex-session-start", "claude-session-start"].includes(content.commandResolver) ||
+      JSON.stringify(parts) !== JSON.stringify(SESSION_PARTS)
+    )) {
+      return { error: "sessionParts 只允许 Codex / Claude SessionStart 的 state、rules、stages" };
+    }
+    for (const part of parts || ["legacy"]) {
+      // 保留原生路径参数，供现有 bootstrap 检测和下一次迁移识别同一组 handler。
+      const nextCommand = parts
+        ? command.replace(commandNeedle, `${FLOWER_SESSION_HOOK_REL} --hook ${commandNeedle} --part ${part}`)
+        : command;
+      const handler = { type: "command", command: nextCommand, timeout: content.timeout };
+      const limit = retainedLimits.get(part) ?? retainedLimits.get("legacy");
+      if (limit !== undefined) handler.additionalContextLimit = limit;
+      group.hooks.push(handler);
+    }
   }
   config.hooks[event] = groups;
   return { value: JSON.stringify(config, null, 2) + "\n", source: "structured" };

package/src/lib/telemetry-context.js

@@ -0,0 +1,275 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { clearTelemetryQueue, readTelemetryJson, writeTelemetryJson, withTelemetryLock } from "./telemetry-files.js";
+import { flowerConfigDirectory } from "../plugin/sources/user-source-store.js";
+import { ProjectStore } from "../plugin/state/project-store.js";
+import { SKILL_GARDEN_PLUGIN_ID } from "../builtin-plugins/skill-garden/provider.js";
+import { readGitDeveloper } from "./developer.js";
+import { readManifest } from "./manifest.js";
+import { flowerVersion, trellisVersion } from "./versions.js";
+
+/** Flower 遥测接收地址。主机名与 `/api/flower-trellis` 路由前缀都由服务端契约固定,缺一不可。 */
+export const FLOWER_TELEMETRY_ENDPOINT = "https://ai-api.hub.flower-cli.com/api/flower-trellis/telemetry";
+
+const TELEMETRY_SCHEMA_VERSION = 1;
+const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const EVENTS = new Set(["version_check", "init_completed", "update_completed"]);
+
+/**
+ * 规范化可上报的开发者名称。
+ *
+ * @param {unknown} value 原始名称
+ * @returns {string|null} 有效名称，无法使用时返回 null
+ */
+function normalizeDeveloperName(value) {
+  if (typeof value !== "string") return null;
+  const name = value.trim();
+  return name && name.length <= 100 ? name : null;
+}
+
+/**
+ * 返回 Flower 用户级遥测状态文件路径。
+ *
+ * @param {NodeJS.ProcessEnv} [env] 环境变量
+ * @returns {string} 状态文件绝对路径
+ */
+export function telemetryStatePath(env = process.env) {
+  return path.join(flowerConfigDirectory(env), "telemetry.json");
+}
+
+/**
+ * 校验并规范化遥测状态。
+ *
+ * @param {unknown} value 原始状态
+ * @returns {object} 规范化状态
+ */
+function normalizeTelemetryState(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("遥测状态必须是对象");
+  }
+  if (value.schemaVersion !== TELEMETRY_SCHEMA_VERSION) {
+    throw new TypeError("遥测状态 schemaVersion 无效");
+  }
+  if (!UUID_PATTERN.test(String(value.deviceId || ""))) {
+    throw new TypeError("遥测设备 ID 无效");
+  }
+  if (typeof value.enabled !== "boolean") {
+    throw new TypeError("遥测 enabled 无效");
+  }
+  const developerName = normalizeDeveloperName(value.developerName);
+  if (value.developerName !== undefined && value.developerName !== null && !developerName) {
+    throw new TypeError("遥测 developerName 无效");
+  }
+  for (const field of ["lastAttemptAt", "lastSuccessAt"]) {
+    if (value[field] !== null && (
+      typeof value[field] !== "string" || Number.isNaN(Date.parse(value[field]))
+    )) {
+      throw new TypeError(`遥测 ${field} 无效`);
+    }
+  }
+  return {
+    schemaVersion: TELEMETRY_SCHEMA_VERSION,
+    deviceId: value.deviceId,
+    developerName,
+    enabled: value.enabled,
+    lastAttemptAt: value.lastAttemptAt,
+    lastSuccessAt: value.lastSuccessAt,
+  };
+}
+
+/**
+ * 读取用户级遥测状态，并区分缺失与损坏。
+ *
+ * @param {{env?:NodeJS.ProcessEnv}} [options] 读取选项
+ * @returns {{status:"missing"|"valid"|"corrupt",state:object|null,path:string,error?:Error}} 状态读取结果
+ */
+export function readTelemetryState(options = {}) {
+  const filePath = telemetryStatePath(options.env);
+  try {
+    const value = readTelemetryJson(filePath);
+    if (value === null && !fs.existsSync(filePath)) return { status: "missing", state: null, path: filePath };
+    const state = normalizeTelemetryState(value);
+    return { status: "valid", state, path: filePath };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { status: "missing", state: null, path: filePath };
+    return { status: "corrupt", state: null, path: filePath, error };
+  }
+}
+
+/**
+ * 原子写入用户级遥测状态。
+ *
+ * @param {object} state 已规范化状态
+ * @param {{env?:NodeJS.ProcessEnv,randomBytes?:(size:number)=>Buffer}} [options] 写入选项
+ * @returns {object} 写入后的状态
+ */
+function writeTelemetryState(state, options = {}) {
+  const normalized = normalizeTelemetryState(state);
+  writeTelemetryJson(telemetryStatePath(options.env), normalized);
+  return normalized;
+}
+
+/**
+ * 创建新的默认遥测状态。
+ *
+ * @param {{randomUUID?:()=>string}} [options] 随机 ID 注入
+ * @returns {object} 默认启用的遥测状态
+ */
+function createTelemetryState(options = {}) {
+  const randomUUID = options.randomUUID || crypto.randomUUID;
+  return {
+    schemaVersion: TELEMETRY_SCHEMA_VERSION,
+    deviceId: randomUUID(),
+    developerName: null,
+    enabled: true,
+    lastAttemptAt: null,
+    lastSuccessAt: null,
+  };
+}
+
+/**
+ * 显式启用或停用用户级遥测。
+ *
+ * 损坏状态只允许通过显式设置修复，普通后台上报不会覆盖现场证据。
+ *
+ * @param {boolean} enabled 是否启用
+ * @param {{env?:NodeJS.ProcessEnv,randomUUID?:()=>string,randomBytes?:(size:number)=>Buffer}} [options] 状态选项
+ * @returns {object} 写入后的遥测状态
+ */
+export function setTelemetryEnabled(enabled, options = {}) {
+  return withTelemetryLock(() => {
+    const result = readTelemetryState(options);
+    const state = result.status === "valid" ? result.state : createTelemetryState(options);
+    const updated = writeTelemetryState({ ...state, enabled }, options);
+    if (!enabled || result.status === "corrupt") clearTelemetryQueue(options.env);
+    return updated;
+  }, options);
+}
+
+/**
+ * 读取项目 `.trellis/.developer` 中由 Trellis 明确记录的开发者名称。
+ *
+ * @param {string} target 项目根目录
+ * @returns {string|null} 开发者名称
+ */
+function readProjectDeveloper(target) {
+  try {
+    const content = fs.readFileSync(path.join(target, ".trellis", ".developer"), "utf8");
+    const line = content.split(/\r?\n/).find((entry) => entry.startsWith("name="));
+    return normalizeDeveloperName(line?.slice("name=".length));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 按项目自报、Git 配置、用户级缓存的顺序解析开发者名称。
+ *
+ * @param {string} target 项目根目录
+ * @param {{developerName?:string|null,env?:NodeJS.ProcessEnv}} [options] 回退选项
+ * @returns {string|null} 开发者名称
+ */
+export function resolveDeveloperName(target, options = {}) {
+  return readProjectDeveloper(target) ||
+    normalizeDeveloperName(readGitDeveloper(target, { env: options.env, timeoutMs: 200 })) ||
+    normalizeDeveloperName(options.developerName);
+}
+
+/**
+ * 读取项目当前 Flower 与 Trellis 版本，不采集任何项目路径或仓库信息。
+ *
+ * @param {string} target 项目根目录
+ * @returns {{flower:string|null,trellis:string|null}} 项目版本
+ */
+export function readProjectVersions(target) {
+  let projectFlower = null;
+  let projectTrellis = null;
+  try {
+    const lock = new ProjectStore(target).readLock();
+    const skillGarden = lock?.plugins.find(({ id }) => id === SKILL_GARDEN_PLUGIN_ID);
+    projectFlower = skillGarden?.version || readManifest(target)?.flowerVersion || null;
+  } catch {
+    projectFlower = readManifest(target)?.flowerVersion || null;
+  }
+  try {
+    projectTrellis = fs.readFileSync(path.join(target, ".trellis", ".version"), "utf8").trim();
+  } catch {
+    projectTrellis = null;
+  }
+  return {
+    flower: VERSION_PATTERN.test(String(projectFlower || "")) ? projectFlower : null,
+    trellis: VERSION_PATTERN.test(String(projectTrellis || "")) ? projectTrellis : null,
+  };
+}
+
+/**
+ * 构造严格白名单的匿名遥测载荷。
+ *
+ * @param {string} target 项目根目录
+ * @param {string} event 遥测事件
+ * @param {{deviceId:string,developerName?:string|null,env?:NodeJS.ProcessEnv,now?:Date}} options 设备、身份与时间参数
+ * @returns {object|null} 可上报载荷；全部身份来源缺失时返回 null
+ */
+export function buildTelemetryPayload(target, event, options) {
+  if (!EVENTS.has(event)) throw new TypeError(`未知遥测事件:${event}`);
+  if (!UUID_PATTERN.test(String(options?.deviceId || ""))) {
+    throw new TypeError("遥测设备 ID 无效");
+  }
+  const now = options.now instanceof Date ? options.now : new Date();
+  const resolvedTarget = path.resolve(target);
+  const developerName = resolveDeveloperName(resolvedTarget, options);
+  // 三种可信身份来源都缺失时无法诚实构造开发者名称，保留静默降级作为最后边界。
+  if (!developerName) return null;
+  const project = readProjectVersions(resolvedTarget);
+  const bundledTrellis = trellisVersion();
+  return {
+    schema_version: TELEMETRY_SCHEMA_VERSION,
+    device_id: options.deviceId,
+    event,
+    flower_version: flowerVersion(),
+    bundled_trellis_version: VERSION_PATTERN.test(bundledTrellis) ? bundledTrellis : null,
+    project_flower_version: project.flower,
+    project_trellis_version: project.trellis,
+    developer_name: developerName,
+    platform: process.platform,
+    arch: process.arch,
+    client_time: now.toISOString(),
+  };
+}
+
+/**
+ * 判断常规遥测是否仍处于上报间隔内。
+ *
+ * @param {object} state 遥测状态
+ * @param {Date} now 当前时间
+ * @param {number} intervalHours 上报间隔小时数
+ * @returns {boolean} 是否应跳过
+ */
+export function isWithinInterval(state, now, intervalHours) {
+  if (!state.lastAttemptAt) return false;
+  const attemptedAt = new Date(state.lastAttemptAt).getTime();
+  if (!Number.isFinite(attemptedAt)) return false;
+  return now.getTime() - attemptedAt < intervalHours * 60 * 60 * 1000;
+}
+
+/** 锁内重读唯一身份和开关，调用方仅合并自己拥有的字段。
+ * @param {Function} callback 同步回调 (state, save)
+ * @param {object} options 环境、创建选项
+ * @returns {unknown} 回调结果或静默状态
+ */
+export function withTelemetryState(callback, options = {}) {
+  const env = options.env || process.env;
+  if (env.FLOWER_NO_TELEMETRY) return { status: "disabled_by_env" };
+  return withTelemetryLock(() => {
+    const result = readTelemetryState({ env });
+    if (result.status === "corrupt") return { status: "corrupt_state" };
+    if (result.status === "missing" && !options.create) return { status: "missing" };
+    let state = result.state || createTelemetryState(options);
+    return callback(state, (patch = {}) => {
+      state = writeTelemetryState({ ...state, ...patch }, { ...options, env });
+      return state;
+    });
+  }, { ...options, env });
+}

package/src/lib/telemetry-files.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { flowerConfigDirectory } from "../plugin/sources/user-source-store.js";
+
+/** 检查目录链，拒绝经由软链接访问遥测状态。
+ * @param {string} directory 目录
+ * @param {boolean} create 是否创建
+ * @returns {void}
+ */
+export function telemetryDirectory(directory, create = true) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) telemetryDirectory(parent, false);
+  try {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("遥测目录必须是普通目录");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    if (!create) return;
+    telemetryDirectory(parent);
+    try { fs.mkdirSync(directory, { mode: 0o700 }); }
+    catch (failure) { if (failure.code !== "EEXIST") throw failure; telemetryDirectory(directory, false); }
+  }
+}
+
+/** 读取有界普通 JSON 文件；损坏文件保留原状。
+ * @param {string} file 文件
+ * @param {unknown} fallback 缺失值
+ * @param {number} limit 最大字节数
+ * @returns {unknown} JSON
+ */
+export function readTelemetryJson(file, fallback = null, limit = 16384) {
+  telemetryDirectory(path.dirname(file), false);
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > limit) throw new Error("遥测状态必须是有界普通文件");
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) { if (error.code === "ENOENT") return fallback; throw error; }
+}
+
+/** 同目录原子替换，避免读到半份状态。
+ * @param {string} file 文件
+ * @param {unknown} value JSON
+ * @returns {void}
+ */
+export function writeTelemetryJson(file, value) {
+  telemetryDirectory(path.dirname(file));
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("遥测状态必须是普通文件");
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, "wx", 0o600);
+    fs.writeFileSync(descriptor, JSON.stringify(value));
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+/** 获取新旧遥测共用的进程锁；锁内回调必须同步且不联网。
+ * @param {Function} callback 同步临界区
+ * @param {object} options 环境
+ * @returns {unknown} 回调结果
+ */
+export function withTelemetryLock(callback, options = {}) {
+  const directory = flowerConfigDirectory(options.env || process.env);
+  telemetryDirectory(directory);
+  try { fs.chmodSync(directory, 0o700); } catch { /* Windows 由用户目录权限保护。 */ }
+  const lock = path.join(directory, "telemetry.lock");
+  const token = crypto.randomUUID();
+  const deadline = Date.now() + 500;
+  for (;;) {
+    if (Date.now() >= deadline) throw new Error("遥测锁繁忙");
+    try {
+      fs.mkdirSync(lock, { mode: 0o700 });
+      writeTelemetryJson(path.join(lock, "owner.json"), { pid: process.pid, token });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let stat;
+      try { stat = fs.lstatSync(lock); }
+      catch (failure) { if (failure.code === "ENOENT" && Date.now() < deadline) continue; throw failure; }
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("遥测锁无效");
+      const owner = readTelemetryJson(path.join(lock, "owner.json"));
+      let dead = false;
+      if (Number.isSafeInteger(owner?.pid) && owner.pid > 0) {
+        try { process.kill(owner.pid, 0); } catch (failure) { dead = failure.code === "ESRCH"; }
+      }
+      if (dead || (!owner && Date.now() - stat.mtimeMs > 30000)) {
+        // 多个竞争者不能同时清理旧锁，否则第二位可能移走下一位刚创建的新锁。
+        const reaper = `${lock}.reap`;
+        let claimed = false;
+        try {
+          fs.mkdirSync(reaper, { mode: 0o700 });
+          claimed = true;
+          const current = readTelemetryJson(path.join(lock, "owner.json"));
+          if (current?.token === owner?.token) {
+            const stale = `${lock}.${token}.stale`;
+            fs.renameSync(lock, stale);
+            fs.rmSync(stale, { recursive: true, force: true });
+          }
+        } catch { /* 下一轮重试，保留非普通或损坏状态。 */ }
+        finally { if (claimed) fs.rmdirSync(reaper); }
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error("遥测锁繁忙");
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+  try { return callback(); }
+  finally {
+    if (readTelemetryJson(path.join(lock, "owner.json"))?.token === token) fs.rmSync(lock, { recursive: true });
+  }
+}
+
+/** 返回独立的 v2 目录，不创建文件。
+ * @param {object} env 环境
+ * @returns {string} 路径
+ */
+export function telemetryQueueDirectory(env = process.env) {
+  return path.join(flowerConfigDirectory(env), "telemetry-v2");
+}
+
+/** 停用时只清理已知普通状态文件，拒绝遍历软链接。
+ * @param {object} env 环境
+ * @returns {void}
+ */
+export function clearTelemetryQueue(env = process.env) {
+  const directory = telemetryQueueDirectory(env);
+  telemetryDirectory(directory, false);
+  if (!fs.existsSync(directory)) return;
+  for (const name of fs.readdirSync(directory)) {
+    const file = path.join(directory, name);
+    const stat = fs.lstatSync(file);
+    if (stat.isFile() && !stat.isSymbolicLink() && (name.endsWith(".json") || name.endsWith(".tmp"))) fs.unlinkSync(file);
+  }
+}

package/src/lib/telemetry-operation.js

@@ -0,0 +1,84 @@
+import crypto from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { flowerVersion, trellisVersion } from "./versions.js";
+import { queueTelemetryEvent } from "./telemetry-queue.js";
+
+const ERROR_GROUPS = {
+  precondition: ["PLUGIN_USAGE_ERROR", "PLUGIN_SOURCE_NOT_FOUND", "PLUGIN_SCHEMA_INVALID", "PLUGIN_STATE_CORRUPT", "PLUGIN_PLATFORM_SELECTION_REQUIRED", "PLUGIN_PLATFORM_UNKNOWN", "PLUGIN_SOURCE_CONFIG_INVALID", "PLUGIN_DEPENDENCY_MISSING"],
+  network: ["PLUGIN_REMOTE_REQUEST_FAILED", "PLUGIN_REMOTE_RATE_LIMITED", "ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND"],
+  permission: ["PLUGIN_AUTH_REQUIRED", "PLUGIN_AUTH_FAILED", "PLUGIN_AUTH_SCOPE_INVALID", "PLUGIN_UNSAFE_PATH", "PLUGIN_CAPABILITY_APPROVAL_REQUIRED", "EACCES", "EPERM"],
+  conflict: ["PLUGIN_CONTENT_CONFLICT", "PLUGIN_TARGET_DRIFT", "PLUGIN_DEPENDENCY_CONFLICT", "PLUGIN_DEPENDENCY_CYCLE", "PLUGIN_EXTERNAL_VERSION_REUSED", "PLUGIN_INTEGRITY_MISMATCH"],
+  upstream: ["FLOWER_UPSTREAM_FAILED"],
+  io: ["PLUGIN_IO_ERROR", "PLUGIN_TRANSACTION_FAILED", "PLUGIN_TRANSACTION_REPAIR_REQUIRED", "UPDATE_COMPENSATION_INCOMPLETE", "ENOENT", "ENOSPC", "EROFS"],
+};
+
+/** 从结构化错误码取得有限分类，不读取 message/path/stack。
+ * @param {unknown} error 异常
+ * @returns {object} 分类
+ */
+export function classifyTelemetryError(error) {
+  const category = Object.entries(ERROR_GROUPS).find(([, codes]) => codes.includes(error?.code))?.[0] || "unknown";
+  const stage = error?.code === "UPDATE_COMPENSATION_INCOMPLETE" ? "recover"
+    : ({ precondition: "prepare", network: "resolve", permission: "authorize", conflict: "apply", upstream: "upstream", io: "apply" })[category] || "unknown";
+  return { error_category: category, failure_stage: stage };
+}
+
+/** 标记已开始真实执行，帮助/预览/未确认退出不会产生终态。
+ * @param {object} ctx 命令上下文
+ * @returns {void}
+ */
+export function beginTelemetryOperation(ctx) {
+  const operation = ctx.telemetryOperation;
+  if (operation && !operation.suppressed && !operation.started) { operation.started = performance.now(); }
+}
+
+/** 在 Plugin 把异常转换为退出码前保留有限分类。
+ * @param {object} ctx 命令上下文
+ * @param {unknown} error 错误
+ * @returns {void}
+ */
+export function noteTelemetryError(ctx, error) {
+  if (ctx.telemetryOperation) {
+    ctx.telemetryOperation.error = classifyTelemetryError(error);
+    ctx.telemetryOperation.cancelled = error?.telemetryCancelled === true || error?.name === "ExitPromptError" || error?.code === "FLOWER_OPERATION_CANCELLED";
+  }
+}
+
+/** 至多一次记录终态，并在完成菜单前冻结耗时。
+ * @param {object} ctx 命令上下文
+ * @param {string} name 期望的外部操作
+ * @param {string} outcome 终态
+ * @returns {void}
+ */
+export function completeTelemetryOperation(ctx, name, outcome = "success") {
+  const operation = ctx.telemetryOperation;
+  if (!operation || operation.name !== name || !operation.started || operation.completed) return;
+  operation.completed = true;
+  queueTelemetryEvent(operation.target, { event_id: operation.id, event: "operation_completed", operation: name, outcome,
+    ...(outcome === "failure" ? operation.error || classifyTelemetryError(null) : { error_category: null, failure_stage: null }),
+    duration_ms: Math.max(0, Math.round(performance.now() - operation.started)), duration_kind: "elapsed" }, operation.options);
+}
+
+/** 建立外部操作边界；嵌套调用共享上下文，子进程可仅抑制采集。
+ * @param {object} ctx 命令上下文
+ * @param {string} name 操作
+ * @param {Function} execute 实际命令
+ * @param {object} options 遥测依赖
+ * @returns {Promise<unknown>} 原命令返回值
+ */
+export async function observeTelemetryOperation(ctx, name, execute, options = {}) {
+  if (ctx.telemetryOperation || (options.env || process.env).FLOWER_TELEMETRY_PARENT_OPERATION) return execute(ctx);
+  const operation = { id: crypto.randomUUID(), name, target: ctx.target, started: null, completed: false,
+    suppressed: ctx.passthrough?.includes("--dry-run") || ctx.trellisControlMode === "restoring",
+    options: { ...options, runtimeVersion: flowerVersion(), bundledVersion: trellisVersion() } };
+  const nested = { ...ctx, telemetryOperation: operation };
+  try {
+    const result = await execute(nested);
+    completeTelemetryOperation(nested, name, operation.cancelled ? "cancelled" : typeof result === "number" && result !== 0 ? "failure" : "success");
+    return result;
+  } catch (error) {
+    if (!operation.error || error?.code === "UPDATE_COMPENSATION_INCOMPLETE") noteTelemetryError(nested, error);
+    completeTelemetryOperation(nested, name, operation.cancelled ? "cancelled" : "failure");
+    throw error;
+  }
+}