@ats-cx/cx-cli 0.1.0

package/dist/workspace.d.ts

@@ -0,0 +1,51 @@
+import type { ConfigSource, ResolvedConfig, SourceRepoBinding } from "@ats-cx/cx-core";
+/** 诊断工作区目录名，建在编辑器源码仓库根下。 */
+export declare const WORKSPACE_DIR_NAME = ".cx-cli";
+/** 工作区语义表文件名：工作区模式下的唯一语义来源（spec 组件 D）。 */
+export declare const WORKSPACE_SEMANTICS_FILE = "event-semantics.json";
+/**
+ * 工作区 config.json 契约。相对路径相对 .cx-cli/ 解析（与 config/ 目录同一约定）。
+ * toolkitConfigDir 可选：省略即运行中 cx-cli 自身的 config/；显式路径钉住一个完整配置组
+ * （ADR 0001 修订，见 ADR 0004）。
+ */
+export interface WorkspaceConfig {
+    toolkitConfigDir?: string;
+    runsDir: string;
+    projectHistoryDir: string;
+    outDir: string;
+}
+/** 发现并解析后的工作区：所有路径均为绝对路径。 */
+export interface Workspace {
+    /** 编辑器源码仓库根（.cx-cli 所在目录）。 */
+    hostRoot: string;
+    workspaceDir: string;
+    /** null 表示使用运行中 cx-cli 自身的 config/。 */
+    toolkitConfigDir: string | null;
+    runsDir: string;
+    projectHistoryDir: string;
+    outDir: string;
+    /** 工作区 .env 路径（不保证存在；project pull 在其存在时才优先用）。 */
+    envPath: string;
+    /** 工作区语义表路径；工作区模式下语义只读它，不回落工具箱种子表。 */
+    semanticsPath: string;
+    /** 三仓绑定：按 HOST_SOURCE_BINDINGS 在宿主仓库根下合成，是运行时唯一来源（无配置层）。 */
+    sourceRepos: SourceRepoBinding[];
+}
+/**
+ * 从 cwd 向上找 .cx-cli/ 工作区（类 .git 发现），到文件系统根为止。
+ * 命中但 config.json 缺失/损坏视为工作区损坏，直接报错——
+ * 静默回退会把产物写到别处，比报错更难排查。
+ */
+export declare function discoverWorkspace(cwd: string): Workspace | null;
+/**
+ * 工作区模式即真实诊断路径（fixture 自测走显式 --config，那时 workspace 为 null）。
+ * 此时日志源仍指向本地文件，说明工具箱 config/ 被自测配置污染——logSource 是唯一
+ * 不被工作区覆盖、却能左右结论的键，静默下去整份诊断会建立在假数据上且看不出异常。
+ * 返回提示文本交由调用方输出（不阻塞：将来离线日志分析可能是正当用法）。
+ */
+export declare function workspaceLogSourceWarning(config: ResolvedConfig, workspace: Workspace | null, configSource?: ConfigSource): string | null;
+/**
+ * 把工作区覆盖应用到共享配置：产物路径落工作区内。
+ * 源码绑定不经配置层，直接住在 Workspace.sourceRepos（ADR 0002）。
+ */
+export declare function applyWorkspace(config: ResolvedConfig, workspace: Workspace): ResolvedConfig;

package/dist/workspace.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { machineConfigDir } from "@ats-cx/cx-core";
+import { UserFacingError } from "./errors.js";
+/** 诊断工作区目录名，建在编辑器源码仓库根下。 */
+export const WORKSPACE_DIR_NAME = ".cx-cli";
+/** 工作区语义表文件名：工作区模式下的唯一语义来源（spec 组件 D）。 */
+export const WORKSPACE_SEMANTICS_FILE = "event-semantics.json";
+/** 工作区模式下自动合成的源码绑定：仓库 id → 宿主仓库内相对位置。 */
+const HOST_SOURCE_BINDINGS = [
+    ["cxeditor", "."],
+    ["cxeditor-resource", "resource"],
+    ["cxeditor-apps", "src/apps"],
+];
+/**
+ * 从 cwd 向上找 .cx-cli/ 工作区（类 .git 发现），到文件系统根为止。
+ * 命中但 config.json 缺失/损坏视为工作区损坏，直接报错——
+ * 静默回退会把产物写到别处，比报错更难排查。
+ */
+export function discoverWorkspace(cwd) {
+    for (let current = resolve(cwd);;) {
+        const workspaceDir = join(current, WORKSPACE_DIR_NAME);
+        if (existsSync(workspaceDir) && statSync(workspaceDir).isDirectory()) {
+            return loadWorkspace(current, workspaceDir);
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function loadWorkspace(hostRoot, workspaceDir) {
+    const configPath = join(workspaceDir, "config.json");
+    const remedy = `请在 ${hostRoot} 重新运行 cx-cli init，或用 --config 显式指定配置目录。`;
+    if (!existsSync(configPath)) {
+        throw new UserFacingError(`错误: 发现工作区 ${workspaceDir}，但缺少 config.json。\n${remedy}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new UserFacingError(`错误: ${configPath} 不是合法 JSON（${reason}）。\n${remedy}`);
+    }
+    const hasToolkitConfigDir = Object.hasOwn(raw, "toolkitConfigDir");
+    const toolkitConfigDir = hasToolkitConfigDir ? raw.toolkitConfigDir : null;
+    if (hasToolkitConfigDir && (typeof toolkitConfigDir !== "string" || toolkitConfigDir.length === 0)) {
+        throw new UserFacingError(`错误: ${configPath} 的 toolkitConfigDir 必须是路径字符串或省略。\n${remedy}`);
+    }
+    const resolveLocal = (value) => (isAbsolute(value) ? value : join(workspaceDir, value));
+    return {
+        hostRoot,
+        workspaceDir,
+        toolkitConfigDir: typeof toolkitConfigDir === "string" ? resolveLocal(toolkitConfigDir) : null,
+        runsDir: resolveLocal(String(raw.runsDir ?? "runs")),
+        projectHistoryDir: resolveLocal(String(raw.projectHistoryDir ?? "data")),
+        outDir: resolveLocal(String(raw.outDir ?? "out")),
+        envPath: join(workspaceDir, ".env"),
+        semanticsPath: join(workspaceDir, WORKSPACE_SEMANTICS_FILE),
+        sourceRepos: HOST_SOURCE_BINDINGS.map(([id, relPath]) => ({ id, path: resolve(hostRoot, relPath) })),
+    };
+}
+/**
+ * 工作区模式即真实诊断路径（fixture 自测走显式 --config，那时 workspace 为 null）。
+ * 此时日志源仍指向本地文件，说明工具箱 config/ 被自测配置污染——logSource 是唯一
+ * 不被工作区覆盖、却能左右结论的键，静默下去整份诊断会建立在假数据上且看不出异常。
+ * 返回提示文本交由调用方输出（不阻塞：将来离线日志分析可能是正当用法）。
+ */
+export function workspaceLogSourceWarning(config, workspace, configSource = "explicit") {
+    if (!workspace || config.logSource.type !== "file") {
+        return null;
+    }
+    const sameDirLocal = join(config.configDir, "toolkit.local.json");
+    const machineLocal = join(machineConfigDir(), "toolkit.local.json");
+    const sourcePath = definesLogSource(sameDirLocal)
+        ? sameDirLocal
+        : configSource === "toolkit" && definesLogSource(machineLocal)
+            ? machineLocal
+            : join(config.configDir, "toolkit.json");
+    return (`警告: 工作区 ${workspace.workspaceDir} 下日志源仍是本地文件 ${config.logSource.path}，真实诊断会建立在假数据上。\n` +
+        `请删掉 ${sourcePath} 里的 logSource；fixture 自测改用 --config fixtures/config。`);
+}
+function definesLogSource(filePath) {
+    if (!existsSync(filePath)) {
+        return false;
+    }
+    const raw = JSON.parse(readFileSync(filePath, "utf8"));
+    return typeof raw === "object" && raw !== null && Object.hasOwn(raw, "logSource");
+}
+/**
+ * 把工作区覆盖应用到共享配置：产物路径落工作区内。
+ * 源码绑定不经配置层，直接住在 Workspace.sourceRepos（ADR 0002）。
+ */
+export function applyWorkspace(config, workspace) {
+    return {
+        ...config,
+        runsDir: workspace.runsDir,
+        outDir: workspace.outDir,
+        projectHistoryDir: workspace.projectHistoryDir,
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ats-cx/cx-cli",
+  "version": "0.1.0",
+  "description": "编辑器诊断工具箱命令行：串联埋点日志、project 快照与 APM，输出结构化诊断 run 供 Agent 消费；附带 Claude Code / Codex skills",
+  "author": "heyg",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "cx-cli": "./bin/cx-cli.cjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "!dist/**/*.map",
+    "skills",
+    "config",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "zod": "^3.24.0",
+    "@ats-cx/cx-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
+}

package/skills/apm-query/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: apm-query
+description: >-
+  用 cx-cli apm 命令组从 APM 网页端临时取数（不建 run）。
+  当用户要「查一下」某用户 / projectId / 订单的网络情况、接口报错、某个埋点有没有触发、现网 project JSON，
+  或「最近的日志查不到」时使用。诊断客诉、建 run 走 editor-diagnostic skill。
+---
+
+# APM 临时取数（cx-cli）
+
+要结论建 run，要数据走 apm-query。
+
+## 0. 先路由
+
+| 用户意图 | 处理 |
+|---|---|
+| 「保存丢了」「改完变回去」「刷新后丢失」「用户投诉」「为什么」等客诉或归因问题 | 交给 **editor-diagnostic skill** 建 run；不要在这里下诊断结论。 |
+| 「先看数据，不用建 run」或只问网络、接口、埋点、现网 JSON | 留在本 skill，做临时取数。 |
+| 已在诊断 run 中，需要补查 APM 数据 | 查询命令加 `--run <runId>`；证据用法见 **editor-diagnostic skill**。 |
+
+## 1. 前提与产物
+
+先检查：
+
+```bash
+cx-cli --version
+```
+
+命令不可用时交给 **cx-cli-setup skill**。APM 命令组不要求诊断工作区，也不读取 `.env`：在工作区内，查询落盘默认写到 `.cx-cli/out/apm/`；否则写到 `~/.config/cx-cli/out/apm/`。命令 stdout 只给摘要和预览，完整原始行始终在落盘文件中。
+
+## 2. 选择命令
+
+先按意图选日志类型，再补身份与时间窗：
+
+| 用户说 | 命令 | 口径 |
+|---|---|---|
+| 网络情况 / 网络质量 / 网差不差 | `cx-cli apm query --type network …` | 只查 network；不要默认附带 api，每多一张表约多一次查询成本。 |
+| 接口报错 / 请求慢 / 请求失败 | `cx-cli apm query --type api …` | 用户点名状态码时才加 `--where data_http_status=500`；「非 200 / 失败率」从落盘聚合。 |
+| 同时问网络和接口 | 分别执行 network 与 api 两条查询 | 两条互不依赖，可并行执行。 |
+| 前端报错 / 页面报错 / 报 JS 错 | `cx-cli apm query --type error --project <id> …`；只有用户身份时改用 `--user <id>` | 看 `data_message` 与原始 `data_stack`；前 3 帧常是 APM SDK 的 fetch 包装，可跳过。第一方帧只能定位到 chunk；把消息中的接口路径带去 api 查询对照。回答把「sourcemap 未部署，无法还原到源码行」作为工具链能力边界声明，不作为本次故障的根因结论。 |
+| 某个埋点 / 有没有触发 / 触发几次 | `cx-cli apm query --type user_behav --event <事件名> …` | `--event` 是模糊匹配。 |
+| 页面性能 / 加载慢 | `cx-cli apm query --type performance [--sub-type navigation\|memory\|resource] …` | 按用户点名的性能类型选择子类型。 |
+| 渲染 / 绘制 | `cx-cli apm query --type paint …` | 读取绘制与耗时字段。 |
+| 服务端报错 / 轨迹 / 服务端接口 | `cx-cli apm query --type server_error …` / `--type footprint …` / `--type server_api …` | 按用户点名的对象选一张表。 |
+| 现网 JSON / 线上版本 | `cx-cli apm project <projectId>` | 返回当前线上 project JSON，不是失败快照。 |
+| stderr 出现「同步失败」警告 | `cx-cli apm flush` 成功后重查 | query 默认已自动同步；正常情况不用手动 flush。 |
+
+### 身份解析
+
+| 已知身份 | 查询参数 |
+|---|---|
+| projectId | `--project <projectId>` |
+| 邮箱 | 先 `cx-cli apm resolve --email <邮箱>`，再用返回的 `userId` 加 `--user <userId>` |
+| 手机号 | 先 `cx-cli apm resolve --phone <手机号>`，再用返回的 `userId` 加 `--user <userId>` |
+| userId | `--user <userId>` |
+| 订单号 | `--item oNNN` |
+| sessionId | `--session <sessionId>` |
+| 相册 ID | `--collection <collectionId>` |
+
+### 时间窗
+
+`apm query` 的 `--from` 必填：
+
+- 用户给了时间窗：照用，并按需加 `--to`。
+- 有 projectId、用户未给时间窗：查项目全史，用 `--from 2000-01-01`。
+- 只有用户身份或没有 ID 过滤、用户未给时间窗：从执行日往前取最近 7 天。
+- 最终回答必须声明实际使用的时间窗。`--from` / `--to` 过滤 `log_time`；它是客户端本地墙钟、不带时区，可能明显偏差甚至落到未来。时间序列按服务器钟 `received_time` 分桶，并在发现两钟偏差时指出。
+- 两钟差值判读：差为整小时 ≈ 时区差（两个戳都不带时区），零碎差 ≈ 钟漂或上报缓冲。`received_time` 是批次到达时间：SDK 先存 IndexedDB，凑满 20 条或每 30s 传一批，关页遗留存量下次打开页面才排空——堆积批会整批落到之后的某天。同设备内的先后顺序以 `log_time` 为准。
+
+### 规模
+
+| 条件 | 做法 |
+|---|---|
+| 有 `--project` / `--session` / `--collection` | 直接拉取；不先花一次查询做 `--count`。 |
+| 只有 `--user`，或没有 ID 过滤 | 先加 `--count` 探规模；超过 50,000 行时收窄时间窗再拉。 |
+| 「最近 N 条」「最新一次」 | 加 `--limit N`。 |
+
+## 3. 读取落盘并聚合
+
+查询落盘形状是 `{ meta, result }`。以下片段都把落盘绝对路径作为第一个参数；`session_id` 为空时统一退到 `install_id`。按小时分桶使用 `slice(0, 13)`，改成 `slice(0, 10)` 即按日分桶。
+
+### network：RTT、downlink、网络类型与时间桶
+
+```bash
+node --input-type=commonjs - "/absolute/path/query.network....json" <<'NODE'
+const { readFileSync } = require("node:fs");
+const dump = JSON.parse(readFileSync(process.argv[2], "utf8"));
+const rows = dump.result;
+const number = value => {
+  if (value === "" || value == null) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const stats = values => {
+  const sorted = values.map(number).filter(value => value !== null).sort((a, b) => a - b);
+  const pick = ratio => sorted.length ? sorted[Math.round((sorted.length - 1) * ratio)] : null;
+  return {
+    count: sorted.length,
+    avg: sorted.length ? sorted.reduce((sum, value) => sum + value, 0) / sorted.length : null,
+    p50: pick(0.5),
+    p95: pick(0.95),
+  };
+};
+const groupKey = row => row.session_id || row.install_id || "(unknown)";
+const bucketKey = row => String(row.received_time || "(unknown)").replace("T", " ").slice(0, 13);
+const group = (items, key) => {
+  const groups = new Map();
+  for (const item of items) {
+    const value = key(item);
+    const matched = groups.get(value);
+    matched ? matched.push(item) : groups.set(value, [item]);
+  }
+  return groups;
+};
+const summarize = items => ({
+  count: items.length,
+  rtt: stats(items.map(row => row.data_rtt)),
+  downlink: stats(items.map(row => row.data_downlink)),
+  effectiveType: Object.fromEntries(
+    [...group(items, row => row.data_effective_type || "(unknown)")].map(([key, values]) => [key, values.length])
+  ),
+});
+console.log(JSON.stringify({
+  total: dump.meta.total,
+  fetched: dump.meta.fetched,
+  overall: summarize(rows),
+  byGroup: Object.fromEntries([...group(rows, groupKey)].map(([key, values]) => [key, summarize(values)])),
+  byReceivedHour: Object.fromEntries([...group(rows, bucketKey)].map(([key, values]) => [key, summarize(values)])),
+}, null, 2));
+NODE
+```
+
+### api：URL 失败率与耗时分位
+
+```bash
+node --input-type=commonjs - "/absolute/path/query.api....json" <<'NODE'
+const { readFileSync } = require("node:fs");
+const dump = JSON.parse(readFileSync(process.argv[2], "utf8"));
+const rows = dump.result;
+const groupKey = row => row.session_id || row.install_id || "(unknown)";
+const failed = row => String(row.data_http_status) !== "200" || String(row.data_biz_status) !== "200000";
+const group = (items, key) => {
+  const groups = new Map();
+  for (const item of items) {
+    const value = key(item);
+    const matched = groups.get(value);
+    matched ? matched.push(item) : groups.set(value, [item]);
+  }
+  return groups;
+};
+const costs = items => {
+  const sorted = items
+    .map(row => row.data_cost === "" || row.data_cost == null ? null : Number(row.data_cost))
+    .filter(value => value !== null && Number.isFinite(value))
+    .sort((a, b) => a - b);
+  const pick = ratio => sorted.length ? sorted[Math.round((sorted.length - 1) * ratio)] : null;
+  return {
+    avg: sorted.length ? sorted.reduce((sum, value) => sum + value, 0) / sorted.length : null,
+    p50: pick(0.5),
+    p95: pick(0.95),
+  };
+};
+const summarize = items => {
+  const failureCount = items.filter(failed).length;
+  return {
+    total: items.length,
+    failed: failureCount,
+    failureRate: items.length ? failureCount / items.length : 0,
+    groups: new Set(items.map(groupKey)).size,
+    cost: costs(items),
+  };
+};
+const byUrl = [...group(rows, row => row.data_url || "(unknown)")]
+  .map(([url, items]) => ({ url, ...summarize(items) }))
+  .sort((left, right) => right.total - left.total);
+const byReceivedHour = [...group(rows, row => String(row.received_time || "(unknown)").replace("T", " ").slice(0, 13))]
+  .map(([hour, items]) => ({ hour, ...summarize(items) }));
+const byGroup = Object.fromEntries(
+  [...group(rows, groupKey)].map(([key, items]) => [key, summarize(items)])
+);
+console.log(JSON.stringify({ total: dump.meta.total, fetched: dump.meta.fetched, byUrl, byGroup, byReceivedHour }, null, 2));
+NODE
+```
+
+### user_behav：事件计数与会话分组
+
+```bash
+node --input-type=commonjs - "/absolute/path/query.user_behav....json" <<'NODE'
+const { readFileSync } = require("node:fs");
+const dump = JSON.parse(readFileSync(process.argv[2], "utf8"));
+const rows = dump.result;
+const groupKey = row => row.session_id || row.install_id || "(unknown)";
+const group = (items, key) => {
+  const groups = new Map();
+  for (const item of items) {
+    const value = key(item);
+    const matched = groups.get(value);
+    matched ? matched.push(item) : groups.set(value, [item]);
+  }
+  return groups;
+};
+const countBy = (items, key) => Object.fromEntries(
+  [...group(items, key)].map(([value, matched]) => [value, matched.length])
+);
+console.log(JSON.stringify({
+  total: dump.meta.total,
+  fetched: dump.meta.fetched,
+  events: countBy(rows, row => row.data_name || "(unknown)"),
+  byGroup: Object.fromEntries(
+    [...group(rows, groupKey)].map(([key, items]) => [key, {
+      total: items.length,
+      events: countBy(items, row => row.data_name || "(unknown)"),
+    }])
+  ),
+  byReceivedHour: countBy(rows, row => String(row.received_time || "(unknown)").replace("T", " ").slice(0, 13)),
+}, null, 2));
+NODE
+```
+
+### user_behav：行为轨迹还原
+
+用户要「行为轨迹 / 这个项目用户做了什么」时用这段：按 `received_time` 排序还原顺序，按日分桶给概览，关键事件逐条给明细，`switchSheet` 序列还原翻页路径。`received_time` 是批次到达时间，堆积批会错天——判读口径见「时间窗」。
+
+```bash
+node --input-type=commonjs - "/absolute/path/query.user_behav....json" <<'NODE'
+const { readFileSync } = require("node:fs");
+const dump = JSON.parse(readFileSync(process.argv[2], "utf8"));
+// 按 case 增删；switchSheet / TabSync_Query 等高频噪音不进白名单，由 byDay 计数承载
+const KEY_EVENTS = new Set([
+  "openProject", "enterPage", "closeOrLeavePage", "switchMainTab",
+  "saveProject", "TabSync_SaveSuccessBroadcast",
+  "startUploadFiles", "completeUploadFiles", "addToCart",
+]);
+const parseExtra = value => {
+  if (typeof value !== "string") return value;
+  try { return JSON.parse(value); } catch { return value; }
+};
+const rows = dump.result
+  .slice()
+  .sort((left, right) => String(left.received_time).localeCompare(String(right.received_time)));
+const byDay = new Map();
+for (const row of rows) {
+  const day = String(row.received_time || "(unknown)").slice(0, 10);
+  const bucket = byDay.get(day) || { first: row.received_time, last: row.received_time, count: 0, users: new Set(), sessions: new Set(), events: {}, sheetSequence: [] };
+  bucket.last = row.received_time;
+  bucket.count += 1;
+  bucket.users.add(row.user_id);
+  bucket.sessions.add(row.session_id || row.install_id || "(unknown)");
+  bucket.events[row.data_name] = (bucket.events[row.data_name] || 0) + 1;
+  if (row.data_name === "switchSheet") bucket.sheetSequence.push(parseExtra(row.data_extra)?.sheetIndex ?? null);
+  byDay.set(day, bucket);
+}
+console.log(JSON.stringify({
+  total: dump.meta.total,
+  fetched: dump.meta.fetched,
+  byDay: Object.fromEntries([...byDay].map(([day, bucket]) => [day, {
+    first: bucket.first,
+    last: bucket.last,
+    count: bucket.count,
+    users: [...bucket.users],
+    sessions: [...bucket.sessions],
+    events: bucket.events,
+    sheetSequence: bucket.sheetSequence,
+  }])),
+  keyEvents: rows
+    .filter(row => KEY_EVENTS.has(row.data_name))
+    .map(row => ({
+      received: row.received_time,
+      log: row.log_time,
+      user: row.user_id,
+      session: row.session_id || row.install_id || "(unknown)",
+      event: row.data_name,
+      extra: parseExtra(row.data_extra),
+    })),
+}, null, 2));
+NODE
+```
+
+## 4. 回答纪律
+
+每次回答都给出四项：
+
+1. 实际时间窗；
+2. 实际过滤条件；
+3. 查询的 `total` 与 `fetched`；
+4. 查询落盘绝对路径。
+
+只陈述查到的数据和数据缺口，不把相关性写成根因。用户继续追问「为什么」或要求归因时，交给 **editor-diagnostic skill** 建 run。
+
+## 5. 复用、清理与速查
+
+- 同一会话中，相同条件不要重查：先读取已有落盘，核对 `meta.request.body` 与这次所需的类型、身份、时间窗和过滤条件；一致就直接复用。
+- `<outDir>/apm/` 只是临时取数产物目录，可随时整目录删除；用户要求清理时，先确认解析后的精确目标确为本次 `<outDir>/apm/`，再执行删除。没有专用清理命令。
+- 回答最后一行再附一次落盘绝对路径，方便继续读取。
+
+| 子命令 | 速查 |
+|---|---|
+| `apm query` | `cx-cli apm query --type network --project 6478815 --from 2000-01-01 --json` |
+| `apm flush` | `cx-cli apm flush --json` |
+| `apm resolve` | `cx-cli apm resolve --email user@example.com --json` |
+| `apm project` | `cx-cli apm project 6478815 --json` |
+
+所有命令支持 `--json`。退出码：`0` 成功，`1` 业务失败，`2` 参数错误。exit 1 若返回
+`kind:"unconfigured"`，转给 **cx-cli-setup skill** 填站点地址后再重试。

package/skills/apm-query/agents/openai.yaml

@@ -0,0 +1,10 @@
+# Codex / ChatGPT 桌面端的可选元数据（Claude Code 忽略本文件）。
+# 字段集见 https://learn.chatgpt.com/docs/build-skills 的 Optional metadata。
+interface:
+  display_name: "APM 临时取数（cx-cli）"
+  short_description: "不建 run，直接从 APM 网页端查用户 / 项目的网络、接口、埋点数据并落盘聚合"
+  brand_color: "#2F6FEB"
+  default_prompt: "帮我查 <projectId 或邮箱> 在 <时间段> 的 <网络情况 / 接口报错 / 某个埋点>"
+
+policy:
+  allow_implicit_invocation: true

package/skills/cx-cli-setup/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: cx-cli-setup
+description: >-
+  安装 / 修复编辑器诊断工具箱 cx-cli（npm 包 @ats-cx/cx-cli）并在当前仓库初始化 .cx-cli 诊断工作区。
+  当用户要「安装 cx-cli」「setup 诊断环境」「初始化诊断工作区」，cx-cli 命令不可用、skills 未链接 / 没链接上，
+  或 apm 报 unconfigured 要填站点地址时使用。日常诊断走 editor-diagnostic skill。
+---
+
+# cx-cli Setup
+
+两级安装的统一入口：**机器级**（全局命令 `cx-cli` 可用 + 包内 skills 链进本机 Agent + 机器级覆盖目录 `~/.config/cx-cli/`，一台机器一次）+ **项目级**（当前仓库建 `.cx-cli/` 诊断工作区，每个仓库一次）。全部幂等：重复触发只补缺的、修坏的，已有配置与语义表不动；`.cx-cli/.gitignore` 是唯一会按当前模板重写的文件。
+
+本 skill 只调用现成命令并解读 `--json` 输出：机器级喊 `cx-cli skills status` / `cx-cli skills install`，项目级喊 `cx-cli init`。不要绕过它们手工建软链、手工建目录。本 skill 随 `@ats-cx/cx-cli` 包分发，**不需要知道包装在哪**——需要路径时全部从命令输出里取。
+
+从别的 skill 带着 `kind:"unconfigured"` 的 apm 错误转交过来时，直接进 §4（文件路径取错误里的 `hint`），§1–3 可省。
+
+## 1. 机器级：探针
+
+```bash
+cx-cli skills status --json
+```
+
+按结果三分支：
+
+| 结果 | 含义 | 动作 |
+|------|------|------|
+| stdout 是 JSON | 命令可用 | 读 `ok`：`true` → 记下 `configDir.path` 与 `configDir.apmConfigured`，进 §3；`false`（exit 1）→ §2 |
+| shell 报 command not found（exit 127） | 当前 shell 的 PATH 里没有 `cx-cli`——多半装在别的 node 版本下 | §1.1 |
+| stderr 首行 `[cx-cli] 当前 node vX 低于要求（>= 22.12），且未找到可用的新版 node` | 自带的 node 启动器找不到达标 node | 转告用户按第二行提示做：`nvm install 24`，或（非 nvm 用户）`export CX_CLI_NODE=<node 可执行文件绝对路径>`。**不代装**；装好后重新触发本 skill |
+
+### 1.1 命令不存在：先找已装副本，不装第二份
+
+```bash
+ls -d ~/.nvm/versions/node/*/lib/node_modules/@ats-cx/cx-cli 2>/dev/null
+```
+
+- **找到**（多份取版本号最高的那个 `<v>`）：本次会话用绝对路径 `~/.nvm/versions/node/<v>/bin/cx-cli` 代替 `cx-cli`（它自带 node 启动器，在当前 shell 的旧 node 下也能跑），回 §1 重跑探针。同时告诉用户：日常终端 `nvm use <v>` 就有命令；想让日常 node 里也有，按工具箱 README「nvm 多个 node 版本」迁移后重跑 `cx-cli skills install`。**不装第二份。**
+- **没找到**（含 volta / brew 等非 nvm 环境——探测只认 `~/.nvm`）：把下面这段原样给用户，**不代装**，用户装完重新触发本 skill：
+
+  > 在你日常默认的 node 下（不用先 `nvm use`）执行：
+  > `npm i -g @ats-cx/cx-cli && cx-cli skills install`
+  > 前提：机器上有一份 ≥ 22.12 的 node（`nvm install 24` 一次即可，不必改 default）。`nvm install` 会把当前终端切到 24，**开一个新终端**再装，否则包会落进 24 的目录、日常终端里找不到命令。`npm i -g` 打出的 `notsup` / `EBADENGINE` engines 警告是预期的，包已装好；只有 `~/.npmrc` 写了 `engine-strict=true` 才会拒装（临时加 `--no-engine-strict`）。
+
+  维护者（clone 工具箱仓库的开发通道）不走这句，走 `bash scripts/setup.sh`——见工具箱 README「安装」开发通道段。
+
+## 2. 机器级：修复
+
+`ok:false` 时不必分辨 `issues` 里是 `missing` / `stale` / `dangling` / `orphans`，一律：
+
+```bash
+cx-cli skills install --json
+```
+
+逐字段解读并转述：
+
+| 字段 | 含义与动作 |
+|------|-----------|
+| `created` | 新建的链（首次安装、包升级后新增的 skill） |
+| `updated[]` | 重指的链。**逐条转述 `from → path`**，让用户看见「原来指向哪一份」（另一 node 版本下的旧包、旧 clone）。若 `from` 那份才是用户想用的，让他从那一份重跑 `cx-cli skills install` 即可指回，零成本 |
+| `pruned` | 已删的孤儿链（更名 / 删除的旧 skill 留下的） |
+| `skipped` | 已指向当前包，没动 |
+| `warnings` | 如「跳过 …：已存在同名真实文件/目录（非软链），请手动处理」——转述路径，**不代删** |
+| `configDir` | `path` 机器级覆盖目录（§4 写 apm 覆盖用它）；`created` 本次是否新建；`apmConfigured` 记下，§4 处理 |
+| `hint` | 可直接转述：Agent 无需重启；`~/.claude/` 不存在时会说「装好 Claude Code 后重跑」；Codex 读 `~/.agents/skills` 无需额外链 |
+
+exit 1 时读 `kind`：`unsupported_install`（npx 缓存 / `pnpm add -g` 装的）→ 转述 `hint`（改用 `npm i -g @ats-cx/cx-cli`），不代装；`io` → 转述 `error`（多半是权限或只读目录），不代修。
+
+## 3. 项目级：初始化诊断工作区
+
+在当前会话仓库内执行（cwd 处于编辑器源码仓库中即可，命令自己向上找 git 根）：
+
+```bash
+cx-cli init --json
+```
+
+逐字段解读输出：
+
+| 字段 | 含义与动作 |
+|------|-----------|
+| `workspaceDir` | 工作区位置（宿主仓库根 `.cx-cli/`） |
+| `created` / `skipped` | 本次建了什么 / 已存在没动什么。首次 init 从工具箱种子复制 `event-semantics.json`；已有语义表、`.env` 与 `config.json` 均不覆盖 |
+| `rewritten` | 本次被 init 改写的已有文件：`.gitignore` 每次按当前模板重写；`config.json` 仅在其 `toolkitConfigDir` 指向不存在的目录时被修（删掉这一键，`warnings` 会说明） |
+| `warnings` | 四类：「宿主不像编辑器仓库」→ 转述给用户确认是否跑错目录，不阻塞；「skills 未安装到本机 Agent（…）」→ 回 §2（§1–2 走完后不该出现）；「apm 未配置：…」→ §4 处理；「config.json 的 toolkitConfigDir 指向不存在的 …，已移除」→ 转述即可，无需动作 |
+| `missingEnvKeys` | `.cx-cli/.env` 里还空着的 DB 凭据键 |
+| `hint` | 汇总提示，可直接转述；apm 未配置时它会说「填好 apm 后可运行 run new / apm query」 |
+
+工作区的版本控制边界由该 `.gitignore` 固定：默认 `*` 全屏蔽——`.env`、`config.json`、`runs/`、`data/`、`out/` 以及任何后来落进工作区的文件都不进宿主仓库 git；只有 `event-semantics.json` 与 `curation/` 被反向放行，它们是宿主仓库的语义策展成果，应随宿主 git 留档。用户若要让工作区里的别的文件进 git，需自己改这份 `.gitignore`，且下次 `init` 会被重写掉。
+
+exit 1（向上找不到 git 仓库根）→ 提示用户 cd 进编辑器源码仓库后重试。
+
+## 4. 收尾
+
+**apm 站点地址**（`apmConfigured:false`，或 `init` warnings / 别的 skill 转交的错误里有「apm 未配置」）：
+
+1. 把那句提示**原文转述**（形如「apm 未配置：请在 `<机器级文件绝对路径>` 填 baseUrl 与 defaults.host（值向团队获取）。」），然后问用户：团队文档里那行 JSON（`{ "baseUrl": "https://…", "defaults": { "host": "www.…" } }`）贴给我，我写进去；或者你自己填。
+2. 收到值 → 读现有 `<configDir.path>/apm-provider.local.json`（`skills install` 已落骨架），**只改 `baseUrl` 与 `defaults.host`，其余键原样保留**，写回。站点地址不是凭据，可以经 Agent 之手；但**不猜值、不从记忆或历史对话里编**，用户没给就只留提示。Agent 沙箱不允许写 `$HOME`（Codex 默认）时，改为把整行 JSON 与文件绝对路径给用户自己贴。
+3. 验证：重跑 `cx-cli skills status --json`，`configDir.apmConfigured` 变 `true` 即可；若出现 `configDir.apmError`，把它转述给用户（多半是贴坏了 JSON）。不发真实 apm 请求——那是 apm-query skill 的事。
+
+**DB 凭据**（`missingEnvKeys` 非空）：告知用户在 `<workspaceDir>/.env` 填入这些键（向团队获取）。**只提示、不代填、永不入库。** 凭据补齐后即可 `cx-cli project pull <projectId>`；诊断命令不碰 DB，不需要 `.env`。
+
+日常诊断走 editor-diagnostic skill：工作区就绪后各命令自动从 cwd 发现工作区，无需 `--config`。
+
+## 升级 / 卸载（只答不做）
+
+用户问起时给命令，**不代跑**；两者都在装包时所用的那个 node 版本下执行：
+
+- 升级（降级同形）：`npm i -g @ats-cx/cx-cli@latest && cx-cli skills install`。不碰任何仓库的 `.cx-cli/` 与 `~/.config/cx-cli/`，无需重跑 `init`，Agent 无需重启。
+- 卸载：`cx-cli skills uninstall && npm rm -g @ats-cx/cx-cli`（先解链再删包）。`~/.config/cx-cli/` 与各仓库 `.cx-cli/` 由用户自己决定删不删。
+
+细节见工具箱 README「升级」「卸载」「nvm 多个 node 版本」。
+
+## 冷启动（本 skill 尚未装到任何 Agent 时）
+
+本 skill 随包分发，装包前触发不了。新机器第一次由人在终端执行一次（前提与注意事项同 §1.1）：
+
+```bash
+npm i -g @ats-cx/cx-cli && cx-cli skills install
+```
+
+此后任何仓库的 Agent 会话都能直接触发本 skill。

package/skills/cx-cli-setup/agents/openai.yaml

@@ -0,0 +1,11 @@
+# Codex / ChatGPT 桌面端的可选元数据（Claude Code 忽略本文件）。
+# 字段集见 https://learn.chatgpt.com/docs/build-skills 的 Optional metadata。
+interface:
+  display_name: "cx-cli 安装与工作区初始化"
+  short_description: "安装 / 修复诊断工具箱 cx-cli，链接 skills，并在当前仓库建 .cx-cli 诊断工作区（幂等）"
+  brand_color: "#2F6FEB"
+  default_prompt: "在当前仓库安装 cx-cli 并初始化 .cx-cli 诊断工作区"
+
+policy:
+  # 默认即 true：cx-cli 不可用时需要能被隐式命中兜底
+  allow_implicit_invocation: true