@ats-cx/cx-cli 0.1.0

package/config/event-semantics.template.jsonc

@@ -0,0 +1,13 @@
+{
+  // 生产语义表位于宿主仓库的 .cx-cli/event-semantics.json；
+  // 工具箱 config/event-semantics.json 仅是 cx-cli init 的种子表。
+  // 字段、值域与条件约束的代码权威是 packages/core/src/semantics/table-schema.ts。
+  // 下例是一个可通过当前 strict schema 的完整条目；表内不要加入证据或备注字段。
+  "transformElement": {
+    "category": "mutation",
+    "action": "transform_element",
+    "entityType": "element",
+    "stateChange": "definite",
+    "tags": ["geometry_change"]
+  }
+}

package/config/toolkit.json

@@ -0,0 +1,3 @@
+{
+  "logSource": { "type": "apm" }
+}

package/dist/apm-help.d.ts

@@ -0,0 +1,5 @@
+/** 命令面契约：`.scratch/apm-command-group/assets/01-apm-help-mock.md`。 */
+export declare const APM_QUERY_HELP = "Usage: cx-cli apm query [\u9009\u9879]\n\n\u67E5\u8BE2 APM \u57CB\u70B9\u65E5\u5FD7\uFF08\u7ECF APM \u7F51\u9875\u7AEF /api/log/query\uFF08\u6839\u5730\u5740\u53D6\u914D\u7F6E baseUrl\uFF09\uFF0C\u53EA\u8BFB\uFF1B\u4E0D\u6536 SQL\uFF09\u3002\n\n\u8FC7\u6EE4\uFF08\u7CBE\u786E\u7B49\u503C\uFF0C\u53EF\u7EC4\u5408\uFF0CAND\uFF09:\n  --type <\u8868>            \u65E5\u5FD7\u7C7B\u578B\uFF08\u9ED8\u8BA4 user_behav\uFF09: error | performance | api | paint |\n                         user_behav | network | server_error | footprint | server_api\n  --project <id>         project_id\n  --user <id>            user_id\n  --collection <id>      collection_id\n  --session <id>         session_id\n  --event <\u540D>           \u4E8B\u4EF6\u540D data_name\uFF0C\u6A21\u7CCA\u5339\u914D %\u540D%\uFF08\u4EC5 user_behav \u6709\u8BE5\u5217\uFF1B\u63A5\u53E3\u53EA\u6709\u6A21\u7CCA\u3001\u65E0\u7B49\u503C\uFF09\n  --sub-type <\u503C>        sub_type\uFF08performance: navigation | memory | resource\uFF09\n  --where <\u5217=\u503C>        \u6309\u5217\u7B49\u503C\uFF0C\u53EF\u91CD\u590D\uFF1B\u5217\u540D\u53EA\u5141\u8BB8 [a-z0-9_]\uFF0C\u503C\u4E0D\u5141\u8BB8\u542B\u5F15\u53F7\u6216\u53CD\u659C\u6760\uFF1B\u5217\u4E0D\u5B58\u5728\u7531\u670D\u52A1\u7AEF\u62A5\u9519\u4E0A\u6D6E\uFF08\u65E0\u539F\u56E0\u3001\u7EA6 1 s\uFF09\uFF1Bdata_name \u4E0D\u53EF\u7528\u4E8E --where\uFF08\u7528 --event\uFF09\uFF1Btype / page / pageSize / order \u662F\u56FA\u5B9A\u8BF7\u6C42\u952E\uFF0C\u4E0D\u53EF\u7528\u4E8E --where\uFF08type \u5217\u7ECF\u63A5\u53E3\u65E0\u6CD5\u8FC7\u6EE4\uFF0C\u5148\u843D\u76D8\u518D\u7528 jq \u7B5B\uFF09\n  --app <id>             app_id\uFF08\u9ED8\u8BA4\u53D6\u914D\u7F6E defaults.app_id\uFF0C\u5DE5\u5177\u7BB1\u9ED8\u8BA4 10001\uFF09\n  --bizline <id>         bizline_id\uFF08\u9ED8\u8BA4\u53D6\u914D\u7F6E defaults.bizline_id\uFF0C\u5DE5\u5177\u7BB1\u9ED8\u8BA4 US\uFF09\n  --from <\u65F6\u95F4>          log_time \u4E0B\u754C\uFF0C\u5FC5\u586B\uFF1BYYYY-MM-DD[ HH:mm:ss] \u6216 ISO\n  --to <\u65F6\u95F4>            log_time \u4E0A\u754C\uFF08\u9ED8\u8BA4\u4E0D\u8BBE\uFF09\n\n\u8FC7\u6EE4\uFF08\u7F51\u9875\u540C\u6B3E\uFF0C\u5BF9\u7167\u7528\uFF09:\n  --item <\u503C>            \u590D\u523B\u7F51\u9875\u300C\u7528\u6237/\u9879\u76EE/\u76F8\u518CID\u300D\u6846\uFF1Auser_id / project_id / collection_id \u4E09\u5217 OR\uFF1B\n                         oNNN \u8BA2\u5355\u53F7\u7531\u670D\u52A1\u7AEF\u89E3\u6790\u4E3A project_id IN (...)\uFF1B\u90AE\u7BB1/\u624B\u673A\u4E0D\u89E3\u6790\uFF0C\u5148 apm resolve\u3002\n                         \u4E0E --project / --user / --collection \u4E92\u65A5\uFF08\u540C\u7ED9 exit 2\uFF09\n  --search <\u6587\u672C>        \u590D\u523B\u7F51\u9875\u300CHost,Url,Status...\u300D\u6846\uFF1A\u9017\u53F7\u5206\u9694\uFF0C\u6BCF\u6BB5\u6309\u8868\u5728 host / client_ip /\n                         terminal_id\uFF08\u7B49\u503C\uFF09\u4E0E page_url\uFF08\u6A21\u7CCA\uFF09\u7B49\u5217\u4E0A OR\uFF0C\u6BB5\u95F4 AND\n\n\u6392\u5E8F:\n  --order <ASC|DESC>     \u6309 log_time \u6392\u5E8F\uFF08\u9ED8\u8BA4 DESC\uFF1B\u53EA\u63A5\u53D7\u8FD9\u4E24\u4E2A\u503C\uFF09\n\n\u8F93\u51FA\uFF0802 \u5B9A\u7A3F\uFF09:\n  --limit <n>            \u6700\u591A\u4ECE\u670D\u52A1\u7AEF\u53D6 n \u884C\uFF08\u6309 --order \u53D6\u524D n \u884C\uFF1B\u7701\u65F6\u7701\u91CF\uFF09\n  --count                \u53EA\u56DE\u603B\u6570 { total }\uFF0C\u4E0D\u53D6\u884C\u3001\u4E0D\u843D\u76D8\n  --preview <n>          stdout \u5185\u8054\u7684\u9884\u89C8\u884C\u6570\uFF08\u9ED8\u8BA4 20\uFF0C\u4E0A\u9650 200\uFF09\uFF1B\u5B8C\u6574\u7ED3\u679C\u770B\u67E5\u8BE2\u843D\u76D8\u6587\u4EF6\n  --full                 \u9884\u89C8\u4E0D\u7626\u8EAB\uFF08\u9ED8\u8BA4\u9690\u85CF extra_data / agent_type \u4E24\u5217\uFF1B\u6587\u4EF6\u6C38\u8FDC\u5168\u5217\uFF09\n  --out <\u6587\u4EF6>           \u67E5\u8BE2\u843D\u76D8\u8DEF\u5F84\uFF08\u9ED8\u8BA4 <outDir>/apm/query.<type>.<YYYYMMDD-HHmmss>.<\u968F\u673A>.json\uFF09\n  --run <runId>          \u628A\u67E5\u8BE2\u843D\u76D8\u5199\u8FDB\u8BE5 run \u7684 artifacts/apm/ \u5E76\u8BB0 trace\uFF0C\u884C\u53EF\u4F5C\u8BC1\u636E apm:<\u6587\u4EF6\u540D>:<\u4E0B\u6807>\uFF0803\uFF09\uFF1B\u4E0E --out \u4E92\u65A5\n\n\u540C\u6B65\uFF0804 \u5B9A\u7A3F\uFF09:\n  --no-flush             \u4E0D\u5728\u67E5\u8BE2\u524D\u8C03 GET /api/log/flush\uFF08\u9ED8\u8BA4\u5148\u540C\u6B65\u4E00\u6B21\uFF0C\u8BA9\u7F51\u9875\u7AEF\u6512\u6279\u672A\u5199\u5165\u7684\u4E8B\u4EF6\u843D\u5E93\uFF1B\u8FD4\u56DE\u5373\u53EF\u89C1\uFF09\n\n\u884C\u4E3A:\n  \u67E5\u8BE2\u524D\u5148\u540C\u6B65\u4E00\u6B21\uFF08--no-flush \u53EF\u5173\uFF1B\u540C\u6B65\u5931\u8D25\u53EA stderr \u8B66\u544A\u3001\u7167\u5E38\u67E5\uFF0C\u7ED3\u679C meta.flush \u8BB0\u5F55\uFF09\u3002\n  \u4E00\u6B21\u8C03\u7528\u62C9\u5B8C\u5339\u914D\u96C6\u5E76\u843D\u76D8\uFF08\u53D6\u6570\u9875\u7531\u914D\u7F6E fetch.pageSize \u51B3\u5B9A\uFF0C\u4E32\u884C\u7FFB\u9875\u3001fetch.maxPages \u515C\u5E95\uFF09\uFF0C\n  stdout \u53EA\u6709\u6458\u8981 + \u9884\u89C8\uFF0C\u6CA1\u6709 --cursor\u2014\u2014\u518D\u5F80\u4E0B\u770B\u7528\u81EA\u5E26\u5DE5\u5177\u8BFB\u6587\u4EF6\u3002\u65E0 --limit \u65F6\u670D\u52A1\u7AEF\u6309 ASC \u62C9\u5168\u91CF\u3001\n  \u672C\u5730\u6309 --order \u6392\u5E8F\uFF1B\u591A\u9875\u9010\u9875\u6838\u5BF9 total\uFF0C\u53D8\u5316 stderr \u8B66\u544A\uFF1B\u7A7A\u7ED3\u679C exit 0\u2014\u2014\u5DF2\u540C\u6B65\u65F6\u63D0\u793A\u6362\u6761\u4EF6\u6216\n  --item \u5BF9\u7167\u4E09\u5217 OR\uFF0C\u672A\u540C\u6B65 / \u540C\u6B65\u5931\u8D25\u65F6\u624D\u63D0\u793A\u5148 apm flush\u3002\n\n\u793A\u4F8B:\n  cx-cli apm query --project 6478815 --from 2026-08-20                     # \u8BE5\u9879\u76EE 8/20 \u8D77\u7684\u7528\u6237\u884C\u4E3A\u4E8B\u4EF6\n  cx-cli apm query --project 6478815 --event saveProject --from 2026-08-20 # \u53EA\u770B\u4FDD\u5B58\u7C7B\u4E8B\u4EF6\n  cx-cli apm query --type error --project 6478815 --from 2026-08-20        # \u540C\u9879\u76EE\u7684\u524D\u7AEF\u62A5\u9519\n  cx-cli apm query --type api --where data_http_status=500 --from 2026-08-27\n  cx-cli apm query --item 6478815 --from 2026-08-20                        # \u590D\u73B0\u7F51\u9875\u770B\u5230\u7684\u7ED3\u679C\n  cx-cli apm query --item o1234567 --from 2026-08-01                       # \u6309\u8BA2\u5355\u53F7\uFF08\u670D\u52A1\u7AEF\u89E3\u6790\uFF09\n  cx-cli apm query --project 6478815 --from 2026-08-20 --count             # \u5148\u63A2\u89C4\u6A21\uFF081 \u4E2A\u8BF7\u6C42\uFF0C\u4E0D\u843D\u76D8\uFF09\n  cx-cli apm query --project 6478815 --from 2026-08-20 --limit 20          # \u6700\u8FD1 20 \u6761\uFF08\u670D\u52A1\u7AEF DESC \u5355\u8BF7\u6C42\uFF09\n  cx-cli apm query --type error --project 6478815 --from 2026-08-20 --run r-20260829-120000-ab12  # \u843D\u8FDB run\uFF0C\u884C\u5F15\u7528\u4E3A apm:<\u6587\u4EF6\u540D>:<\u4E0B\u6807>\n";
+export declare const APM_RESOLVE_HELP = "Usage: cx-cli apm resolve [\u9009\u9879]\n\n\u7ECF\u7F51\u9875\u7AEF portal \u514D\u767B\u5F55\u8DEF\u7531\u89E3\u6790 ID\uFF08\u4E8C\u9009\u4E00\uFF0C\u8F93\u51FA\u89E3\u6790\u7ED3\u679C\u4F9B\u4E0B\u4E00\u6B65\u67E5\u8BE2\u7528\uFF09\uFF1Bcx-cli \u4E0D\u6301\u4EFB\u4F55\u51ED\u636E\u3002\u8BA2\u5355\u53F7 \u2192 projectIds \u65E0\u514D\u767B\u5F55\u8DEF\u7531\uFF0814 \u5B9A\u4E0D\u52A0\uFF09\uFF0C\u7528 apm query --item oNNN\u3002\n\n  --email <\u90AE\u7BB1>         \u2192 userId\n  --phone <\u624B\u673A\u53F7>       \u2192 userId\n  --host <\u7AD9\u70B9 host>     \u7AD9\u70B9 host\uFF0C\u5373\u65E5\u5FD7 host \u5217\u7684\u503C\uFF08\u987B\u5E26\u5B50\u57DF\uFF0C\u5982 www.example.com\uFF1B\n                         \u9ED8\u8BA4\u53D6\u914D\u7F6E defaults.host\uFF09\uFF1B\u4E0D\u8DB3\u4E09\u6BB5 exit 2\n\n\u8F93\u51FA\uFF0802\uFF09:\n  { userId, email | phone, host }\uFF1B\u67E5\u4E0D\u5230\u662F\u63A5\u53E3 {success:false} \u2192 exit 1\uFF08\u6587\u6848\u540C\u65F6\u63D0\u300C\u65E0\u6B64\u8D26\u53F7\u300D\u4E0E\u300C\u63A5\u53E3\u4E0D\u53EF\u7528\u300D\uFF09\n\n\u793A\u4F8B:\n  cx-cli apm resolve --email user@example.com\n";
+export declare const APM_PROJECT_HELP = "Usage: cx-cli apm project [\u9009\u9879] <projectId>\n\n\u62C9\u53D6\u73B0\u7F51 project JSON\uFF08portal \u5F53\u524D\u7EBF\u4E0A\u7248\u672C\uFF1B\u4E0E `project pull` \u7684\u5931\u8D25\u5FEB\u7167\u662F\u4E24\u4E2A\u6765\u6E90\uFF09\u3002\u7ECF\u7F51\u9875\u7AEF\u514D\u767B\u5F55\u8DEF\u7531\uFF0Ccx-cli \u4E0D\u6301\u4EFB\u4F55\u51ED\u636E\u3002\n\n\u53C2\u6570:\n  projectId              \u9879\u76EE ID\uFF08\u53EA\u6536\u6570\u5B57\uFF0C\u5426\u5219 exit 2\uFF09\n\n\u9009\u9879:\n  --host <\u7AD9\u70B9 host>     \u7AD9\u70B9 host\uFF0C\u5373\u65E5\u5FD7 host \u5217\u7684\u503C\uFF08\u987B\u5E26\u5B50\u57DF\uFF0C\u5982 www.example.com\uFF1B\n                         \u9ED8\u8BA4\u53D6\u914D\u7F6E defaults.host\uFF09\uFF1B\u4E0D\u8DB3\u4E09\u6BB5 exit 2\n  --out <\u6587\u4EF6>           \u843D\u76D8\u8DEF\u5F84\uFF08\u9ED8\u8BA4 <outDir>/apm/project.<projectId>.<YYYYMMDD-HHmmss>.<\u968F\u673A>.json\uFF09\n  --run <runId>          \u843D\u8FDB\u8BE5 run \u7684 artifacts/apm/ \u5E76\u8BB0 trace\uFF0C\u6574\u6587\u4EF6\u53EF\u4F5C\u8BC1\u636E apm:<\u6587\u4EF6\u540D>\uFF1B\u4E0E --out \u4E92\u65A5\n\n\u8F93\u51FA\uFF0802 / 07\uFF09:\n  \u5FC5\u843D\u76D8\uFF1A\u54CD\u5E94\u4F53\u539F\u6837\u5199\u5165\uFF08\u9876\u5C42 {images, effects, project}\uFF0C\u4E0E\u5FEB\u7167\u6587\u4EF6\u540C\u5F62\u72B6\u3001\u53EF\u4E92\u6362\uFF1B\u4E0D\u88F9 meta\uFF09\uFF0C\n  stdout \u53EA\u7ED9 { projectId, host, file, bytes, updatedDate }\uFF1B\u4E0D\u63D0\u4F9B --print\uFF0CAgent \u76F4\u63A5\u8BFB\u6587\u4EF6\u3002\n  \u9879\u76EE\u4E0D\u5B58\u5728 / host \u4E0D\u5BF9 / portal \u767B\u5F55\u5931\u8D25 \u2192 \u63A5\u53E3\u56DE HTTP 200 + \u6B63\u6587 [object Object] \u2192 exit 1 kind:\"invalid_response\"\uFF08\u6587\u6848\u5217\u51FA\u4E09\u79CD\u53EF\u80FD\uFF09\uFF1B\n  \u8FD4\u56DE\u4F53\u65E0 project \u952E\uFF08package \u9879\u76EE\uFF09\u2192 \u7167\u5E38\u843D\u76D8\u3001updatedDate null\u3001stderr \u8B66\u544A\u3001exit 0\u3002\n\n\u793A\u4F8B:\n  cx-cli apm project 6478815                               # \u73B0\u7F51\u7248\u672C\u843D <outDir>/apm/\uFF0C\u4E0E\u6700\u65B0\u5FEB\u7167\u6BD4 updatedDate\n  cx-cli apm project 6478815 --run r-20260829-120000-ab12  # \u843D\u8FDB run\uFF0C\u8BC1\u636E apm:project.6478815.20260829-120000.k3f9.json\n";
+export declare const APM_FLUSH_HELP = "Usage: cx-cli apm flush\n\n\u8BA9\u7F51\u9875\u7AEF\u628A\u5185\u5B58\u4E2D\u6512\u6279\u672A\u5199\u5165\u7684\u4E8B\u4EF6\u5F3A\u5236\u843D\u5E93\uFF08= \u7F51\u9875\u300C\u540C\u6B65\u300D\u6309\u94AE\uFF0CGET /api/log/flush\uFF0C\u514D\u9274\u6743\uFF09\u3002\n\u4E0D\u540C\u6B65\u65F6\u6700\u8FD1\u4E8B\u4EF6\u53EF\u80FD\u67E5\u4E0D\u5230\uFF08\u6BCF\u8868\u81F3\u591A 1000 \u6761\u6EDE\u540E\uFF09\u3002\u8FD4\u56DE\u5373\u53EF\u89C1\uFF0C\u4E0D\u9700\u8981\u7B49\u5F85\u3002\napm query \u4E0E run new \u76F4\u62C9\u9ED8\u8BA4\u5DF2\u5728\u67E5\u8BE2\u524D\u81EA\u52A8\u540C\u6B65\uFF0804\uFF09\uFF1B\u672C\u547D\u4EE4\u7ED9 --no-flush / --logs \u5DE5\u4F5C\u6D41\uFF0C\n\u4EE5\u53CA stderr \u51FA\u73B0\u300C\u540C\u6B65\u5931\u8D25\u300D\u8B66\u544A\u540E\u7684\u624B\u52A8\u91CD\u8BD5\u7528\u3002\n\n\u8F93\u51FA\uFF0802\uFF09:\n  { flushed: true, message }\uFF1B\u63A5\u53E3 {success:false} \u2192 exit 1\n";

package/dist/apm-help.js

@@ -0,0 +1,108 @@
+/** 命令面契约：`.scratch/apm-command-group/assets/01-apm-help-mock.md`。 */
+export const APM_QUERY_HELP = `Usage: cx-cli apm query [选项]
+
+查询 APM 埋点日志（经 APM 网页端 /api/log/query（根地址取配置 baseUrl），只读；不收 SQL）。
+
+过滤（精确等值，可组合，AND）:
+  --type <表>            日志类型（默认 user_behav）: error | performance | api | paint |
+                         user_behav | network | server_error | footprint | server_api
+  --project <id>         project_id
+  --user <id>            user_id
+  --collection <id>      collection_id
+  --session <id>         session_id
+  --event <名>           事件名 data_name，模糊匹配 %名%（仅 user_behav 有该列；接口只有模糊、无等值）
+  --sub-type <值>        sub_type（performance: navigation | memory | resource）
+  --where <列=值>        按列等值，可重复；列名只允许 [a-z0-9_]，值不允许含引号或反斜杠；列不存在由服务端报错上浮（无原因、约 1 s）；data_name 不可用于 --where（用 --event）；type / page / pageSize / order 是固定请求键，不可用于 --where（type 列经接口无法过滤，先落盘再用 jq 筛）
+  --app <id>             app_id（默认取配置 defaults.app_id，工具箱默认 10001）
+  --bizline <id>         bizline_id（默认取配置 defaults.bizline_id，工具箱默认 US）
+  --from <时间>          log_time 下界，必填；YYYY-MM-DD[ HH:mm:ss] 或 ISO
+  --to <时间>            log_time 上界（默认不设）
+
+过滤（网页同款，对照用）:
+  --item <值>            复刻网页「用户/项目/相册ID」框：user_id / project_id / collection_id 三列 OR；
+                         oNNN 订单号由服务端解析为 project_id IN (...)；邮箱/手机不解析，先 apm resolve。
+                         与 --project / --user / --collection 互斥（同给 exit 2）
+  --search <文本>        复刻网页「Host,Url,Status...」框：逗号分隔，每段按表在 host / client_ip /
+                         terminal_id（等值）与 page_url（模糊）等列上 OR，段间 AND
+
+排序:
+  --order <ASC|DESC>     按 log_time 排序（默认 DESC；只接受这两个值）
+
+输出（02 定稿）:
+  --limit <n>            最多从服务端取 n 行（按 --order 取前 n 行；省时省量）
+  --count                只回总数 { total }，不取行、不落盘
+  --preview <n>          stdout 内联的预览行数（默认 20，上限 200）；完整结果看查询落盘文件
+  --full                 预览不瘦身（默认隐藏 extra_data / agent_type 两列；文件永远全列）
+  --out <文件>           查询落盘路径（默认 <outDir>/apm/query.<type>.<YYYYMMDD-HHmmss>.<随机>.json）
+  --run <runId>          把查询落盘写进该 run 的 artifacts/apm/ 并记 trace，行可作证据 apm:<文件名>:<下标>（03）；与 --out 互斥
+
+同步（04 定稿）:
+  --no-flush             不在查询前调 GET /api/log/flush（默认先同步一次，让网页端攒批未写入的事件落库；返回即可见）
+
+行为:
+  查询前先同步一次（--no-flush 可关；同步失败只 stderr 警告、照常查，结果 meta.flush 记录）。
+  一次调用拉完匹配集并落盘（取数页由配置 fetch.pageSize 决定，串行翻页、fetch.maxPages 兜底），
+  stdout 只有摘要 + 预览，没有 --cursor——再往下看用自带工具读文件。无 --limit 时服务端按 ASC 拉全量、
+  本地按 --order 排序；多页逐页核对 total，变化 stderr 警告；空结果 exit 0——已同步时提示换条件或
+  --item 对照三列 OR，未同步 / 同步失败时才提示先 apm flush。
+
+示例:
+  cx-cli apm query --project 6478815 --from 2026-08-20                     # 该项目 8/20 起的用户行为事件
+  cx-cli apm query --project 6478815 --event saveProject --from 2026-08-20 # 只看保存类事件
+  cx-cli apm query --type error --project 6478815 --from 2026-08-20        # 同项目的前端报错
+  cx-cli apm query --type api --where data_http_status=500 --from 2026-08-27
+  cx-cli apm query --item 6478815 --from 2026-08-20                        # 复现网页看到的结果
+  cx-cli apm query --item o1234567 --from 2026-08-01                       # 按订单号（服务端解析）
+  cx-cli apm query --project 6478815 --from 2026-08-20 --count             # 先探规模（1 个请求，不落盘）
+  cx-cli apm query --project 6478815 --from 2026-08-20 --limit 20          # 最近 20 条（服务端 DESC 单请求）
+  cx-cli apm query --type error --project 6478815 --from 2026-08-20 --run r-20260829-120000-ab12  # 落进 run，行引用为 apm:<文件名>:<下标>
+`;
+export const APM_RESOLVE_HELP = `Usage: cx-cli apm resolve [选项]
+
+经网页端 portal 免登录路由解析 ID（二选一，输出解析结果供下一步查询用）；cx-cli 不持任何凭据。订单号 → projectIds 无免登录路由（14 定不加），用 apm query --item oNNN。
+
+  --email <邮箱>         → userId
+  --phone <手机号>       → userId
+  --host <站点 host>     站点 host，即日志 host 列的值（须带子域，如 www.example.com；
+                         默认取配置 defaults.host）；不足三段 exit 2
+
+输出（02）:
+  { userId, email | phone, host }；查不到是接口 {success:false} → exit 1（文案同时提「无此账号」与「接口不可用」）
+
+示例:
+  cx-cli apm resolve --email user@example.com
+`;
+export const APM_PROJECT_HELP = `Usage: cx-cli apm project [选项] <projectId>
+
+拉取现网 project JSON（portal 当前线上版本；与 \`project pull\` 的失败快照是两个来源）。经网页端免登录路由，cx-cli 不持任何凭据。
+
+参数:
+  projectId              项目 ID（只收数字，否则 exit 2）
+
+选项:
+  --host <站点 host>     站点 host，即日志 host 列的值（须带子域，如 www.example.com；
+                         默认取配置 defaults.host）；不足三段 exit 2
+  --out <文件>           落盘路径（默认 <outDir>/apm/project.<projectId>.<YYYYMMDD-HHmmss>.<随机>.json）
+  --run <runId>          落进该 run 的 artifacts/apm/ 并记 trace，整文件可作证据 apm:<文件名>；与 --out 互斥
+
+输出（02 / 07）:
+  必落盘：响应体原样写入（顶层 {images, effects, project}，与快照文件同形状、可互换；不裹 meta），
+  stdout 只给 { projectId, host, file, bytes, updatedDate }；不提供 --print，Agent 直接读文件。
+  项目不存在 / host 不对 / portal 登录失败 → 接口回 HTTP 200 + 正文 [object Object] → exit 1 kind:"invalid_response"（文案列出三种可能）；
+  返回体无 project 键（package 项目）→ 照常落盘、updatedDate null、stderr 警告、exit 0。
+
+示例:
+  cx-cli apm project 6478815                               # 现网版本落 <outDir>/apm/，与最新快照比 updatedDate
+  cx-cli apm project 6478815 --run r-20260829-120000-ab12  # 落进 run，证据 apm:project.6478815.20260829-120000.k3f9.json
+`;
+export const APM_FLUSH_HELP = `Usage: cx-cli apm flush
+
+让网页端把内存中攒批未写入的事件强制落库（= 网页「同步」按钮，GET /api/log/flush，免鉴权）。
+不同步时最近事件可能查不到（每表至多 1000 条滞后）。返回即可见，不需要等待。
+apm query 与 run new 直拉默认已在查询前自动同步（04）；本命令给 --no-flush / --logs 工作流，
+以及 stderr 出现「同步失败」警告后的手动重试用。
+
+输出（02）:
+  { flushed: true, message }；接口 {success:false} → exit 1
+`;
+//# sourceMappingURL=apm-help.js.map

package/dist/apm-output.d.ts

@@ -0,0 +1,49 @@
+import type { ApmOrder, FlushRecord, LogType } from "@ats-cx/cx-core";
+export interface QueryDumpMeta {
+    command: "apm query";
+    fetchedAt: string;
+    request: {
+        url: string;
+        body: Record<string, unknown>;
+    };
+    flush: FlushRecord;
+    total: number;
+    fetched: number;
+    pagesFetched: number;
+    warnings: string[];
+}
+export interface QueryPreview {
+    total: number;
+    fetched: number;
+    pagesFetched: number;
+    truncated: boolean;
+    file: string;
+    columns: string[];
+    hiddenColumns: string[];
+    hint: string | null;
+    rows: unknown[];
+}
+export declare function createQueryFileName(type: LogType, now?: Date): string;
+export declare function createProjectFileName(projectId: string, now?: Date): string;
+export declare function resolveApmOutputFile(options: {
+    out?: string;
+    run?: string;
+    runsDir: string;
+    outDir: string;
+    fileName: string;
+}): string;
+export declare function writeQueryDump(file: string, rows: unknown[], meta: Omit<QueryDumpMeta, "command" | "fetchedAt"> & {
+    fetchedAt: Date;
+}): void;
+export declare function writeRawApmFile(file: string, text: string): number;
+export declare function buildQueryPreview(options: {
+    rows: unknown[];
+    total: number;
+    pagesFetched: number;
+    file: string;
+    order: ApmOrder;
+    preview: number;
+    full: boolean;
+    alreadySorted: boolean;
+    flush: FlushRecord;
+}): QueryPreview;

package/dist/apm-output.js

@@ -0,0 +1,115 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { randomInt } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { loadRun } from "@ats-cx/cx-core";
+const HIDDEN_PREVIEW_COLUMNS = ["extra_data", "agent_type"];
+const RANDOM_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+function localTimestamp(now) {
+    return [now.getFullYear(), pad(now.getMonth() + 1), pad(now.getDate())].join("") +
+        `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+function randomSuffix() {
+    return Array.from({ length: 4 }, () => RANDOM_ALPHABET[randomInt(RANDOM_ALPHABET.length)]).join("");
+}
+export function createQueryFileName(type, now = new Date()) {
+    return `query.${type}.${localTimestamp(now)}.${randomSuffix()}.json`;
+}
+export function createProjectFileName(projectId, now = new Date()) {
+    return `project.${projectId}.${localTimestamp(now)}.${randomSuffix()}.json`;
+}
+export function resolveApmOutputFile(options) {
+    if (options.out !== undefined) {
+        return resolve(options.out);
+    }
+    if (options.run !== undefined) {
+        const run = loadRun(options.runsDir, options.run);
+        return join(run.runDir, "artifacts", "apm", options.fileName);
+    }
+    return join(options.outDir, "apm", options.fileName);
+}
+export function writeQueryDump(file, rows, meta) {
+    mkdirSync(dirname(file), { recursive: true });
+    const content = {
+        meta: {
+            command: "apm query",
+            fetchedAt: meta.fetchedAt.toISOString(),
+            request: meta.request,
+            flush: meta.flush,
+            total: meta.total,
+            fetched: meta.fetched,
+            pagesFetched: meta.pagesFetched,
+            warnings: meta.warnings,
+        },
+        result: rows,
+    };
+    writeFileSync(file, JSON.stringify(content, null, 2));
+}
+export function writeRawApmFile(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, text, "utf8");
+    return Buffer.byteLength(text, "utf8");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parsePreviewString(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "string" || (typeof parsed === "object" && parsed !== null) ? parsed : value;
+    }
+    catch {
+        return value;
+    }
+}
+function preparePreviewRow(row, hiddenColumns) {
+    if (!isRecord(row))
+        return row;
+    return Object.fromEntries(Object.entries(row).flatMap(([key, value]) => {
+        if (hiddenColumns.includes(key))
+            return [];
+        return [[key, typeof value === "string" ? parsePreviewString(value) : value]];
+    }));
+}
+function sortRows(rows, order) {
+    return [...rows].sort((left, right) => {
+        const leftTime = isRecord(left) && typeof left.log_time === "string" ? left.log_time : "";
+        const rightTime = isRecord(right) && typeof right.log_time === "string" ? right.log_time : "";
+        const comparison = leftTime.localeCompare(rightTime);
+        return order === "ASC" ? comparison : -comparison;
+    });
+}
+function emptyHint(flush) {
+    return flush.ok === true
+        ? "未查到结果；换过滤条件，或用 --item <id> 对照三列 OR 是否命中"
+        : "未查到结果；先 apm flush 让最近事件落库再查，或换过滤条件";
+}
+export function buildQueryPreview(options) {
+    const fetched = options.rows.length;
+    const ordered = options.alreadySorted ? options.rows : sortRows(options.rows, options.order);
+    const hiddenColumns = options.full ? [] : [...HIDDEN_PREVIEW_COLUMNS];
+    const rows = ordered
+        .slice(0, options.preview)
+        .map(row => preparePreviewRow(row, hiddenColumns));
+    const truncated = rows.length < fetched;
+    const columns = isRecord(options.rows[0]) ? Object.keys(options.rows[0]) : [];
+    const hint = truncated
+        ? `完整结果在 ${options.file}，用 jq / grep 读，或加过滤条件缩小范围`
+        : fetched === 0
+            ? emptyHint(options.flush)
+            : null;
+    return {
+        total: options.total,
+        fetched,
+        pagesFetched: options.pagesFetched,
+        truncated,
+        file: options.file,
+        columns,
+        hiddenColumns,
+        hint,
+        rows,
+    };
+}
+//# sourceMappingURL=apm-output.js.map

package/dist/budget.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_PAGE_SIZE = 50;
+export interface Page<T> {
+    items: T[];
+    total: number;
+    cursor: number;
+    nextCursor: number | null;
+    truncated: boolean;
+    /** 截断时提示下钻方式，直接展示给宿主 Agent。 */
+    hint: string | null;
+}
+export declare function paginate<T>(all: T[], options?: {
+    pageSize?: number;
+    cursor?: number;
+}): Page<T>;

package/dist/budget.js

@@ -0,0 +1,16 @@
+export const DEFAULT_PAGE_SIZE = 50;
+export function paginate(all, options = {}) {
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const cursor = options.cursor ?? 0;
+    const items = all.slice(cursor, cursor + pageSize);
+    const nextCursor = cursor + items.length < all.length ? cursor + items.length : null;
+    return {
+        items,
+        total: all.length,
+        cursor,
+        nextCursor,
+        truncated: nextCursor !== null,
+        hint: nextCursor !== null ? `结果已截断（共 ${all.length} 条），用 --cursor ${nextCursor} 继续，或加过滤参数缩小范围` : null,
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+import type { ConfigSource } from "@ats-cx/cx-core";
+import { Command } from "commander";
+import type { CliResult } from "./output.js";
+import type { Workspace } from "./workspace.js";
+export declare const TOOLKIT_ROOT: string;
+export interface CliSink {
+    write(chunk: string): void;
+    emit(result: CliResult): void;
+}
+export interface Execution {
+    configDir: string;
+    configSource: ConfigSource;
+    /** 命中的诊断工作区；显式 --config 时不消费工作区，恒为 null。 */
+    workspace: Workspace | null;
+}
+export declare function assertConfigDirExists(path: string, label: string): void;
+/** 配置解析优先级（map 决策 8）：显式 --config > cwd 向上发现工作区 > $CX_CLI_CONFIG_DIR > 工具箱 config/。 */
+export declare function resolveExecution(explicit: unknown, cwd?: string): Execution;
+export declare function createProgram(sink: CliSink): Command;
+export declare function runCli(argv: string[]): Promise<CliResult>;