@ats-cx/cx-cli 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+# 数据库连接配置（cx-cli project pull 读取，全部明文，不加密）
+# apm 命令组与 run new 拉日志不读本文件（零凭据）
+# 复制为 .env 并填入真实值；.env 已被 gitignore，不要提交。
+DB_HOST=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_PORT=3306

package/README.md

@@ -0,0 +1,119 @@
+# cx-cli
+
+面向编辑器研发与客诉排查同事的诊断工具箱：提供 `cx-cli` 命令行，以及可安装到 Claude Code / Codex 的 `editor-diagnostic`、`apm-query`、`cx-cli-setup`、`semantics-curation` 四个 Agent skills。
+
+## 安装
+
+在你日常默认的 node（哪怕是 10.x）下安装：
+
+```bash
+npm i -g @ats-cx/cx-cli && cx-cli skills install
+```
+
+> 前提：机器上有一份 ≥ 22.12 的 node（`nvm install 24` 一次即可，**不必**改 default、不必 `nvm use`）。`nvm install` 会把当前终端切到 24——装 cx-cli 请开一个新终端（回到你日常的 node），再执行 `npm i -g @ats-cx/cx-cli`，否则包会装进 24 的目录，日常 node 10 的终端里找不到命令。
+>
+> npm 6（node 10 自带）安装时会打印下面这些警告，**这是预期的**，包已经装好；`cx-cli` 启动时会自动改用 `~/.nvm` 里 ≥ 22.12 的最高版本 node：
+>
+> ```text
+> npm WARN notsup Unsupported engine for @ats-cx/cx-cli@<版本>: wanted: {"node":">=22.12"} (current: {"node":"10.24.0","npm":"6.14.11"})
+> npm WARN notsup Not compatible with your version of node/npm: @ats-cx/cx-cli@<版本>
+> npm WARN notsup Unsupported engine for @ats-cx/cx-core@<版本>: wanted: {"node":">=22.12"} (current: {"node":"10.24.0","npm":"6.14.11"})
+> npm WARN notsup Not compatible with your version of node/npm: @ats-cx/cx-core@<版本>
+> npm WARN notsup Unsupported engine for commander@15.0.0: wanted: {"node":">=22.12.0"} (current: {"node":"10.24.0","npm":"6.14.11"})
+> npm WARN notsup Not compatible with your version of node/npm: commander@15.0.0
+> npm WARN notsup Unsupported engine for sql-escaper@1.5.1: …
+> npm WARN notsup Unsupported engine for sax@1.6.1: …
+> npm WARN mysql2@3.24.2 requires a peer of @types/node@>= 8 but none is installed. You must install peer dependencies yourself.
+> ```
+>
+> npm 6.11.x（node 10.17 自带）**一行 engines 警告都不打**，也正常。npm ≥ 7（node 16/18 自带）的同款警告长这样：`npm warn EBADENGINE Unsupported engine { package: '@ats-cx/cx-cli@<版本>', required: { node: '>=22.12' }, current: { node: 'v18.20.8', npm: '10.8.2' } }`。
+>
+> 验证：`cx-cli --version` 打印版本号即成功。若看到 `[cx-cli] 当前 node vX 低于要求（>= 22.12），且未找到可用的新版 node。` 按第二行提示做：`nvm install 24`，或（非 nvm 用户）`export CX_CLI_NODE=<node 可执行文件绝对路径>`。
+>
+> 只有 `~/.npmrc` 写了 `engine-strict=true` 时 `npm i -g` 会以 `npm ERR! code ENOTSUP` 拒装——临时加 `--no-engine-strict` 或删掉那行。
+
+## 装进 Agent
+
+`cx-cli skills install` 会把包内四个 skill 先链到 `~/.agents/skills/`，再链到 `~/.claude/skills/`；Codex 使用前者，Claude Code 使用后者。它是幂等命令，可以安全重跑。
+
+```bash
+cx-cli skills status
+```
+
+全部链就绪时返回 `ok: true`；未就绪时会列出问题与修复命令。
+
+## 初始化工作区
+
+每个编辑器源码仓库执行一次：
+
+```bash
+cd <编辑器源码仓库>
+cx-cli init
+```
+
+也可以在该仓库的 Agent 会话里说「安装 cx-cli」，由 `cx-cli-setup` skill 引导完成。
+
+## 站点地址
+
+APM 站点地址不随包分发。请向团队获取实际值，填入 `~/.config/cx-cli/apm-provider.local.json`：
+
+```json
+{"baseUrl":"https://…","defaults":{"host":"www.…"}}
+```
+
+未配置时会看到类似：`apm 未配置：请在 /Users/<用户名>/.config/cx-cli/apm-provider.local.json 填 baseUrl 与 defaults.host（值向团队获取）。`
+
+## DB 凭据
+
+只有 `cx-cli project pull` 读取 DB 凭据。在编辑器源码仓库的 `.cx-cli/.env` 填写：
+
+```dotenv
+DB_HOST=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+DB_PORT=
+```
+
+这五个值向团队获取，只留本机，不要入库或转发。
+
+## 升级
+
+升级、降级同形；在安装时所用的 node 版本下执行：
+
+```bash
+npm i -g @ats-cx/cx-cli@latest && cx-cli skills install
+```
+
+`skills install` 幂等：新版本新增的 skill 会链上（created），更名 / 删除的旧链自动清理（pruned），其余不动。
+升级不碰任何仓库的 `.cx-cli/` 工作区与 `~/.config/cx-cli/`，无需重跑 `cx-cli init`，Agent 无需重启。
+随时可用 `cx-cli skills status` 检查链是否就绪（未就绪 exit 1 并给出修复命令）。
+
+## 卸载
+
+先解链再删包（反过来链会悬空且没命令可删）：
+
+```bash
+cx-cli skills uninstall && npm rm -g @ats-cx/cx-cli
+```
+
+`nvm uninstall <装包的 node 版本>` 等同于删包，之前同样先 `cx-cli skills uninstall`。
+可选清理（都是手动，cx-cli 不代删）：
+
+- `rm -rf ~/.config/cx-cli`：机器级覆盖目录，含 apm 覆盖、`.env` 回落与无工作区时的 `runs/ out/ data/` 产物。
+- `rm -rf <编辑器源码仓库>/.cx-cli`：该仓库的诊断工作区（含全部 run 产物）。其中 `event-semantics.json` 与 `curation/` 随宿主仓库 git 留档，先决定去留。
+
+顺序做反了、或 `nvm uninstall` 之后没 `cx-cli` 可用：`npx @ats-cx/cx-cli skills uninstall` 会清掉悬空链。
+不想装任何东西：`find ~/.agents/skills ~/.claude/skills ~/.codex/skills -maxdepth 1 -type l ! -exec test -e {} \; -delete`（删这三处全部悬空链，含非 cx-cli 的）。
+
+## nvm 多个 node 版本
+
+全局包按 node 版本隔离：在哪个版本下装，就在哪个版本下升级 / 卸载；切到别的版本后 `cx-cli` 命令消失（包与链都还在）。
+迁移到新版本：`nvm use <新> && nvm reinstall-packages <旧>`，然后重跑 `cx-cli skills install`。
+装了两份时 `cx-cli skills status` 会报 `stale` 并说明链指向哪一份。
+
+## 用法入口
+
+运行 `cx-cli --help` 查看完整命令；支持 `--json` 稳定 JSON 输出。退出码：`0` 成功、`1` 业务失败、`2` 参数错误。
+
+源码仓库为私有仓库，不提供公开链接；遇到问题请联系工具箱维护者。

package/bin/cx-cli.cjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict";
+// cx-cli 启动器。宿主编辑器仓库常把 shell 的 node 钉在 10.x（.nvmrc），而 dist/ 是 ESM，
+// 老 node 连 `import` 语句都解析不了，报出来的是一坨 SyntaxError 堆栈。本文件只用老 node 也能解析的
+// 语法：先查版本，不达标就找一个达标的 node 重新执行自己（$CX_CLI_NODE 优先，其次 ~/.nvm 里最高的
+// 达标版本）；找不到再给出人能照做的提示。达标时直接加载 dist/index.js，行为与之前完全一致。
+var MIN_NODE = [22, 12];
+var fs = require("fs");
+var os = require("os");
+var path = require("path");
+var childProcess = require("child_process");
+
+function parseVersion(text) {
+  var match = /v?(\d+)\.(\d+)/.exec(text || "");
+  return match ? [Number(match[1]), Number(match[2])] : null;
+}
+
+function satisfies(version) {
+  return !!version && (version[0] > MIN_NODE[0] || (version[0] === MIN_NODE[0] && version[1] >= MIN_NODE[1]));
+}
+
+function isExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+function isCompatibleNode(file) {
+  if (!isExecutable(file)) {
+    return false;
+  }
+  var result = childProcess.spawnSync(file, ["--version"], { encoding: "utf8" });
+  return !result.error && result.status === 0 && satisfies(parseVersion(result.stdout));
+}
+
+function findNewerNode() {
+  var candidates = [];
+  if (process.env.CX_CLI_NODE) {
+    candidates.push(process.env.CX_CLI_NODE);
+  }
+  var nvmNodeDir = path.join(process.env.NVM_DIR || path.join(os.homedir(), ".nvm"), "versions", "node");
+  var names = [];
+  try {
+    names = fs.readdirSync(nvmNodeDir);
+  } catch (error) {
+    names = [];
+  }
+  names
+    .map(function (name) { return { name: name, version: parseVersion(name) }; })
+    .filter(function (item) { return satisfies(item.version); })
+    .sort(function (a, b) { return b.version[0] - a.version[0] || b.version[1] - a.version[1]; })
+    .forEach(function (item) { candidates.push(path.join(nvmNodeDir, item.name, "bin", "node")); });
+  for (var i = 0; i < candidates.length; i += 1) {
+    if (isCompatibleNode(candidates[i])) {
+      return candidates[i];
+    }
+  }
+  return null;
+}
+
+var entry = path.join(__dirname, "..", "dist", "index.js");
+
+if (satisfies(parseVersion(process.versions.node))) {
+  // 用 Function 包一层：本文件必须能被老 node 解析，不能直接写 import() 语法。
+  new Function("specifier", "return import(specifier)")(require("url").pathToFileURL(entry).href).catch(function (error) {
+    console.error(error && error.stack ? error.stack : String(error));
+    process.exit(1);
+  });
+} else {
+  var newerNode = findNewerNode();
+  if (!newerNode) {
+    console.error(
+      "[cx-cli] 当前 node v" + process.versions.node + " 低于要求（>= " + MIN_NODE.join(".") + "），且未找到可用的新版 node。\n" +
+        "请安装 node 24（nvm install 24），或设置 CX_CLI_NODE=<node 可执行文件绝对路径> 后重试。"
+    );
+    process.exit(1);
+  }
+  var result = childProcess.spawnSync(newerNode, [entry].concat(process.argv.slice(2)), {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.error) {
+    console.error("[cx-cli] 无法用 " + newerNode + " 启动：" + result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}

package/config/apm-provider.json

@@ -0,0 +1,7 @@
+{
+  "baseUrl": "",
+  "defaults": { "bizline_id": "US", "app_id": "10001", "host": "" },
+  "runPreset": { "type": "user_behav", "log_time_start": "" },
+  "fetch": { "pageSize": 5000, "maxPages": 50 },
+  "timeoutMs": { "query": 300000, "flush": 30000, "portal": 30000 }
+}

package/config/apm-provider.template.jsonc

@@ -0,0 +1,48 @@
+{
+  // APM 网页端根地址，供全部 query / flush / portal 路径使用。
+  // 只允许 http(s) URL；运行时会移除尾部斜杠。
+  "baseUrl": "https://apm.example.com",
+
+  // 默认过滤值：apm query 未显式传参时使用，run new 的日志预设也复用 app_id / bizline_id；
+  // bizline_id 与 app_id 都必须是非空字符串。
+  // host 供 apm resolve / apm project 使用，必须是至少三段的完整站点 host，如 www.example.com。
+  "defaults": {
+    "bizline_id": "US",
+    "app_id": "10001",
+    "host": "www.example.com"
+  },
+
+  // 只供 run new 直拉日志使用。type 必须是以下 9 种日志类型之一：
+  // error / performance / api / paint / user_behav / network / server_error / footprint / server_api。
+  // log_time_start 为空或缺省表示拉项目全史；非空时支持 YYYY-MM-DD、
+  // YYYY-MM-DD HH:mm:ss、YYYY-MM-DDTHH:mm:ss，且不能携带时区后缀。
+  "runPreset": {
+    "type": "user_behav",
+    "log_time_start": ""
+  },
+
+  // apm query 与 run new 共用的取数页设置，均须为正整数。
+  // pageSize 是单次接口取数行数；maxPages 是结果不完整前的硬上限。
+  "fetch": {
+    "pageSize": 5000,
+    "maxPages": 50
+  },
+
+  // 各端点超时，单位毫秒，均须为正整数：query 供 apm query / run new，
+  // flush 供查询前自动同步与 apm flush，portal 供 apm resolve / apm project。
+  "timeoutMs": {
+    "query": 300000,
+    "flush": 30000,
+    "portal": 30000
+  }
+
+  // 站点地址不随包分发。本机覆盖写在 ~/.config/cx-cli/apm-provider.local.json（分发通道；
+  // 遵 $XDG_CONFIG_HOME），或本文件同目录的 apm-provider.local.json（开发通道单 clone 试验用，最后合并、最优先）；
+  // 运行时与本文件同形状深合并。同事只需填这两项（值向团队获取）：
+  // { "baseUrl": "https://apm.example.com", "defaults": { "host": "www.example.com" } }
+  // 切到别的站点时可再覆盖：
+  // { "defaults": { "host": "www.example.org", "bizline_id": "<业务线>" } }
+  //
+  // 以下机制不在配置文件里：请求形状、order 恒传、origin header、值校验与翻页逻辑；
+  // 它们由 core 客户端固定，local 覆盖只能改值，不能改机制。
+}

package/config/diagnostic-rules.json

@@ -0,0 +1,54 @@
+{
+  "rules": [
+    {
+      "id": "explicit_error_signal",
+      "enabled": true,
+      "kind": "explicit_error",
+      "severity": "high",
+      "description": "识别事件本身带错误语义，或者 payload 内显式包含 message/stack 的情况。",
+      "reasonTemplates": {
+        "default": "事件 {eventName} 具有显式失败语义，建议直接查看错误信息、调用栈和相关接口响应。"
+      }
+    },
+    {
+      "id": "state_change_without_save",
+      "enabled": true,
+      "kind": "state_change_without_save",
+      "includePossibleStateChange": true,
+      "description": "识别发生状态变更后，没有看到保存就离开页面的情况。",
+      "severityByStateChange": {
+        "definite": "medium",
+        "possible": "low"
+      },
+      "reasonTemplates": {
+        "default": "最后一个 {stateChangeLabel} 是 {lastEventTime} 的 {lastEventName}，但在离开页面前没有看到保存事件。"
+      }
+    },
+    {
+      "id": "reentry_after_leave",
+      "enabled": true,
+      "kind": "reentry_after_leave",
+      "severity": "low",
+      "maxGapSeconds": 30,
+      "description": "识别用户离开编辑器后短时间内重新进入的链路。",
+      "reasonTemplates": {
+        "default": "用户在离开编辑器 {gapSeconds} 秒后再次进入，这通常意味着刷新、异常恢复或手动重开。"
+      }
+    },
+    {
+      "id": "state_change_save_reentry",
+      "enabled": true,
+      "kind": "state_change_save_reentry",
+      "includePossibleStateChange": true,
+      "lookahead": 8,
+      "description": "识别状态变更之后出现保存，并且随后重新进入编辑器的链路。",
+      "severityByStateChange": {
+        "definite": "medium",
+        "possible": "low"
+      },
+      "reasonTemplates": {
+        "default": "{stateChangeLabel} {eventName} 之后出现了保存，随后又重新进入编辑器。建议对比这个时间点前后的 project 版本，确认状态是否真正落盘。"
+      }
+    }
+  ]
+}

package/config/diagnostic-rules.template.jsonc

@@ -0,0 +1,82 @@
+{
+  // 这个文件是中文注释模板，不参与运行。
+  // 真正生效的配置文件是 diagnostic-rules.json。
+  //
+  // 维护原则：
+  // 1. 规则尽量围绕“语义标签”写，不围绕具体事件名写。
+  // 2. 新增事件时优先补 event-semantics.json，而不是直接新增规则。
+  // 3. 只有当现有通用规则覆盖不了某类客诉时，再新增规则。
+  //
+  // 支持的规则 kind：
+  // - explicit_error: 显式失败信号
+  // - state_change_without_save: 变更后离开但没保存
+  // - reentry_after_leave: 离开后快速重进
+  // - state_change_save_reentry: 变更后保存，再次进入
+  //
+  // 通用字段：
+  // - id: 规则唯一标识，输出报告时会带上
+  // - enabled: 是否启用
+  // - kind: 规则类型
+  // - severity: 固定严重级别，可选
+  // - description: 给团队看的说明
+  // - reasonTemplates.default: 输出给报告的中文文案模板
+  //
+  // 部分规则专用字段：
+  // - includePossibleStateChange: 是否把 stateChange=possible 也算入规则
+  // - severityByStateChange: 根据 none/possible/definite/commit 动态给严重级别
+  // - maxGapSeconds: 两个事件之间允许的最大秒数
+  // - lookahead: 向后看多少条事件
+
+  "rules": [
+    {
+      "id": "explicit_error_signal",
+      "enabled": true,
+      "kind": "explicit_error",
+      "severity": "high",
+      "description": "识别事件自带错误语义的情况。",
+      "reasonTemplates": {
+        "default": "事件 {eventName} 具有显式失败语义，建议直接查看错误信息、调用栈和相关接口响应。"
+      }
+    },
+    {
+      "id": "state_change_without_save",
+      "enabled": true,
+      "kind": "state_change_without_save",
+      "includePossibleStateChange": true,
+      "severityByStateChange": {
+        "definite": "medium",
+        "possible": "low"
+      },
+      "description": "识别发生状态变更之后离开页面，但没有看到保存事件。",
+      "reasonTemplates": {
+        "default": "最后一个 {stateChangeLabel} 是 {lastEventTime} 的 {lastEventName}，但在离开页面前没有看到保存事件。"
+      }
+    },
+    {
+      "id": "reentry_after_leave",
+      "enabled": true,
+      "kind": "reentry_after_leave",
+      "severity": "low",
+      "maxGapSeconds": 30,
+      "description": "识别离开后短时间内重新进入的情况。",
+      "reasonTemplates": {
+        "default": "用户在离开编辑器 {gapSeconds} 秒后再次进入，这通常意味着刷新、异常恢复或手动重开。"
+      }
+    },
+    {
+      "id": "state_change_save_reentry",
+      "enabled": true,
+      "kind": "state_change_save_reentry",
+      "includePossibleStateChange": true,
+      "lookahead": 8,
+      "severityByStateChange": {
+        "definite": "medium",
+        "possible": "low"
+      },
+      "description": "识别状态变更之后出现保存，并在之后重新进入编辑器的链路。",
+      "reasonTemplates": {
+        "default": "{stateChangeLabel} {eventName} 之后出现了保存，随后又重新进入编辑器。建议对比这个时间点前后的 project 版本，确认状态是否真正落盘。"
+      }
+    }
+  ]
+}