@ats-cx/cx-core 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @ats-cx/cx-core
+
+cx-cli 的事实层，随 `@ats-cx/cx-cli` 同号发布；不是独立公共 API，不承诺 semver 稳定。由确定性纯函数与 provider 组成，不感知 LLM 或传输层。
+
+## 主要导出
+
+| 模块 | 职责 |
+|------|------|
+| `providers/` | `LogProvider`、`ProjectProvider`、`SourceProvider`（仅 git 版本快照）、`RemoteProjectProvider`（远端快照拉取） |
+| `db/` | `DbClient` 薄接口 + `createMysqlClient`（mysql2，仅 `project pull` 使用） |
+| `normalize/` | 日志 envelope 统一、session 聚合、project.json 规范化 |
+| `semantics/` | 事件 → 统一语义标签 |
+| `rules/` | 通用可疑信号规则引擎 |
+| `diff/` | project 版本对比 |
+| `run/` | run 目录、trace、artifact、结论 schema 校验 |
+
+## 测试
+
+在仓库根目录执行：
+
+```bash
+pnpm vitest run packages/core
+```

package/dist/apm/client.d.ts

@@ -0,0 +1,59 @@
+import type { ApmProviderConfig } from "./config.js";
+import type { ApmErrorKind } from "./errors.js";
+import type { ApmOrder, LogType } from "./values.js";
+export interface FlushRecord {
+    attempted: boolean;
+    ok?: boolean;
+    durationMs?: number;
+    reason?: ApmErrorKind;
+}
+export interface ApmQueryParams {
+    type: LogType;
+    from?: string;
+    to?: string;
+    order?: ApmOrder;
+    project?: string;
+    user?: string;
+    collection?: string;
+    session?: string;
+    subType?: string;
+    event?: string;
+    app?: string;
+    bizline?: string;
+    where?: Record<string, string>;
+    item?: string;
+    search?: string;
+    limit?: number;
+    flush?: boolean;
+}
+export interface ApmQueryResult {
+    rows: unknown[];
+    total: number;
+    pagesFetched: number;
+    request: {
+        url: string;
+        body: Record<string, unknown>;
+    };
+    warnings: string[];
+    flush: FlushRecord;
+}
+export interface ApmClientDeps {
+    fetchImpl?: typeof fetch;
+    onProgress?: (message: string) => void;
+}
+export interface FlushResult {
+    ok: boolean;
+    durationMs: number;
+    message?: string;
+    reason?: ApmErrorKind;
+    status?: number;
+}
+export interface ApmClient {
+    query(params: ApmQueryParams): Promise<ApmQueryResult>;
+    count(params: ApmQueryParams): Promise<{
+        total: number;
+        flush: FlushRecord;
+    }>;
+    flush(): Promise<FlushResult>;
+}
+export declare function createApmClient(config: ApmProviderConfig, deps?: ApmClientDeps): ApmClient;

package/dist/apm/client.js

@@ -0,0 +1,247 @@
+import { ApmRequestError } from "./errors.js";
+import { assertColumnName, assertSafeValue, FIXED_REQUEST_KEYS, LOG_TYPES, normalizeLogTime, ORDERS, } from "./values.js";
+export function createApmClient(config, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const onProgress = deps.onProgress ?? (message => console.error(message));
+    const queryUrl = `${config.baseUrl}/api/log/query`;
+    const flushUrl = `${config.baseUrl}/api/log/flush`;
+    async function flush() {
+        const startedAt = Date.now();
+        try {
+            const response = await fetchImpl(flushUrl, {
+                method: "GET",
+                signal: AbortSignal.timeout(config.timeoutMs.flush),
+            });
+            if (!response.ok) {
+                return { ok: false, durationMs: Date.now() - startedAt, reason: "http", status: response.status };
+            }
+            const parsed = parseJson(await response.text());
+            if (!isRecord(parsed)) {
+                return { ok: false, durationMs: Date.now() - startedAt, reason: "invalid_response" };
+            }
+            if (parsed.success === false) {
+                return { ok: false, durationMs: Date.now() - startedAt, reason: "rejected" };
+            }
+            if (parsed.success !== true) {
+                return { ok: false, durationMs: Date.now() - startedAt, reason: "invalid_response" };
+            }
+            return {
+                ok: true,
+                durationMs: Date.now() - startedAt,
+                ...(typeof parsed.message === "string" ? { message: parsed.message } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                durationMs: Date.now() - startedAt,
+                reason: isAbortError(error) ? "timeout" : "http",
+            };
+        }
+    }
+    async function runFlush(enabled) {
+        if (!enabled) {
+            return { attempted: false };
+        }
+        const result = await flush();
+        const record = {
+            attempted: true,
+            ok: result.ok,
+            durationMs: result.durationMs,
+            ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        };
+        if (!result.ok) {
+            onProgress(`同步失败（${result.reason ?? "unknown"}），最近事件可能未落库`);
+        }
+        return record;
+    }
+    async function requestPage(body) {
+        try {
+            const response = await fetchImpl(queryUrl, {
+                method: "POST",
+                headers: {
+                    origin: config.baseUrl,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(config.timeoutMs.query),
+            });
+            if (!response.ok) {
+                throw new ApmRequestError("http", {
+                    status: response.status,
+                    message: `APM 请求失败（HTTP ${response.status}）`,
+                });
+            }
+            const parsed = parseJson(await response.text());
+            if (!isRecord(parsed)) {
+                throw new ApmRequestError("invalid_response");
+            }
+            if (parsed.success === false) {
+                throw new ApmRequestError("rejected", { baseUrl: config.baseUrl });
+            }
+            const data = parsed.data;
+            if (!isRecord(data) || !Array.isArray(data.result)) {
+                throw new ApmRequestError("invalid_response", { message: "APM 响应缺少 data.result 数组" });
+            }
+            const pagination = data.pagination;
+            const total = isRecord(pagination) ? Number(pagination.total) : Number.NaN;
+            if (!Number.isFinite(total) || total < 0) {
+                throw new ApmRequestError("invalid_response", { message: "APM 响应缺少有效的 data.pagination.total" });
+            }
+            return { rows: data.result, total };
+        }
+        catch (error) {
+            if (error instanceof ApmRequestError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new ApmRequestError("timeout");
+            }
+            throw new ApmRequestError("http", {
+                message: `APM 请求失败：${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    async function query(params) {
+        validateParams(params);
+        const pageSize = params.limit === undefined ? config.fetch.pageSize : Math.min(params.limit, config.fetch.pageSize);
+        const order = params.limit === undefined ? "ASC" : (params.order ?? "DESC");
+        const firstBody = buildBody(config, params, 1, pageSize, order);
+        const flushRecord = await runFlush(params.flush !== false);
+        const rows = [];
+        const warnings = [];
+        const warnedTotals = new Set();
+        let firstTotal;
+        let total = 0;
+        let pagesFetched = 0;
+        for (let page = 1; page <= config.fetch.maxPages; page += 1) {
+            const body = page === 1 ? firstBody : buildBody(config, params, page, pageSize, order);
+            const result = await requestPage(body);
+            pagesFetched += 1;
+            rows.push(...result.rows);
+            total = result.total;
+            if (firstTotal === undefined) {
+                firstTotal = total;
+            }
+            else if (total !== firstTotal && !warnedTotals.has(total)) {
+                const warning = `警告: total 由 ${firstTotal} 变为 ${total}`;
+                warnedTotals.add(total);
+                warnings.push(warning);
+                onProgress(warning);
+            }
+            const target = params.limit === undefined ? total : Math.min(params.limit, total);
+            const expectedPages = Math.max(1, Math.ceil(target / pageSize));
+            if (expectedPages > 1) {
+                onProgress(`第 ${page}/${expectedPages} 页`);
+            }
+            const complete = rows.length >= target || result.rows.length === 0;
+            if (complete) {
+                return {
+                    rows: params.limit === undefined ? rows : rows.slice(0, params.limit),
+                    total,
+                    pagesFetched,
+                    request: { url: queryUrl, body: firstBody },
+                    warnings,
+                    flush: flushRecord,
+                };
+            }
+            if (page === config.fetch.maxPages) {
+                throw new ApmRequestError("incomplete", {
+                    fetched: rows.length,
+                    total,
+                    partialRows: rows,
+                    pagesFetched,
+                    request: { url: queryUrl, body: firstBody },
+                    warnings,
+                    flush: flushRecord,
+                });
+            }
+        }
+        throw new ApmRequestError("incomplete", {
+            fetched: rows.length,
+            total,
+            partialRows: rows,
+            pagesFetched,
+            request: { url: queryUrl, body: firstBody },
+            warnings,
+            flush: flushRecord,
+        });
+    }
+    async function count(params) {
+        validateParams(params);
+        const body = buildBody(config, params, 1, 1, params.order ?? "DESC");
+        const flushRecord = await runFlush(params.flush !== false);
+        const result = await requestPage(body);
+        return { total: result.total, flush: flushRecord };
+    }
+    return { query, count, flush };
+}
+function buildBody(config, params, page, pageSize, order) {
+    const body = {
+        type: params.type,
+        page,
+        pageSize,
+        order,
+    };
+    addValue(body, "bizline_id", params.bizline ?? config.defaults.bizline_id);
+    addValue(body, "app_id", params.app ?? config.defaults.app_id);
+    addValue(body, "log_time_start", params.from ? normalizeLogTime(params.from, "start") : undefined);
+    addValue(body, "log_time_end", params.to ? normalizeLogTime(params.to, "end") : undefined);
+    addValue(body, "project_id", params.project);
+    addValue(body, "user_id", params.user);
+    addValue(body, "collection_id", params.collection);
+    addValue(body, "session_id", params.session);
+    addValue(body, "sub_type", params.subType);
+    addValue(body, "data_name", params.event);
+    addValue(body, "item_id", params.item);
+    addValue(body, "search", params.search);
+    for (const [column, value] of Object.entries(params.where ?? {})) {
+        if (FIXED_REQUEST_KEYS.has(column)) {
+            throw new Error(`${column} 是固定请求键，不能通过 where 覆盖`);
+        }
+        assertColumnName(column);
+        addValue(body, column, value);
+    }
+    return body;
+}
+function addValue(body, key, value) {
+    if (value === undefined || value === "") {
+        return;
+    }
+    assertSafeValue(key, value);
+    body[key] = value;
+}
+function validateParams(params) {
+    if (!LOG_TYPES.includes(params.type)) {
+        throw new Error(`不支持的日志类型: ${params.type}`);
+    }
+    if (params.order !== undefined && !ORDERS.includes(params.order)) {
+        throw new Error(`不支持的排序: ${params.order}`);
+    }
+    if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit <= 0)) {
+        throw new Error("limit 必须是正整数");
+    }
+    const from = params.from ? normalizeLogTime(params.from, "start") : undefined;
+    const to = params.to ? normalizeLogTime(params.to, "end") : undefined;
+    if (from && to && to < from) {
+        throw new Error("结束时间不能早于开始时间");
+    }
+}
+function parseJson(text) {
+    try {
+        return text ? JSON.parse(text) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAbortError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        (error.name === "AbortError" || error.name === "TimeoutError"));
+}
+//# sourceMappingURL=client.js.map

package/dist/apm/config-state.d.ts

@@ -0,0 +1,19 @@
+import { ApmRequestError } from "./errors.js";
+export declare const HINT: (path: string) => string;
+export declare const ERROR_EMPTY = "apm \u672A\u914D\u7F6E\uFF1AbaseUrl / defaults.host \u4E3A\u7A7A\uFF08apm \u7EC4\u4E0E run new \u62C9\u65E5\u5FD7\u90FD\u9700\u8981\u7AD9\u70B9\u5730\u5740\uFF09";
+export declare const ERROR_MISSING: (configDir: string) => string;
+export declare const SENTENCE: (path: string) => string;
+export type ApmProviderState = {
+    kind: "unconfigured";
+    fillPath: string;
+} | {
+    kind: "missing";
+    fillPath: string;
+    configDir: string;
+} | {
+    kind: "invalid";
+    fillPath: string;
+    error: string;
+};
+export declare function isApmConfigured(state: ApmProviderState | null): state is null;
+export declare function createApmConfigError(state: ApmProviderState): ApmRequestError;

package/dist/apm/config-state.js

@@ -0,0 +1,18 @@
+import { ApmRequestError } from "./errors.js";
+export const HINT = (path) => `请在 ${path} 填 baseUrl 与 defaults.host（值向团队获取）。`;
+export const ERROR_EMPTY = "apm 未配置：baseUrl / defaults.host 为空（apm 组与 run new 拉日志都需要站点地址）";
+export const ERROR_MISSING = (configDir) => `apm 未配置：${configDir} 缺少 apm-provider.json（apm 组与 run new 拉日志都需要它）`;
+export const SENTENCE = (path) => `apm 未配置：${HINT(path)}`;
+export function isApmConfigured(state) {
+    return state === null;
+}
+export function createApmConfigError(state) {
+    if (state.kind === "invalid") {
+        return new ApmRequestError("invalid_config", { message: state.error });
+    }
+    return new ApmRequestError("unconfigured", {
+        message: state.kind === "missing" ? ERROR_MISSING(state.configDir) : ERROR_EMPTY,
+        hint: HINT(state.fillPath),
+    });
+}
+//# sourceMappingURL=config-state.js.map

package/dist/apm/config.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+declare const apmProviderConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    defaults: z.ZodObject<{
+        bizline_id: z.ZodString;
+        app_id: z.ZodString;
+        host: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        bizline_id: string;
+        app_id: string;
+        host: string;
+    }, {
+        bizline_id: string;
+        app_id: string;
+        host: string;
+    }>;
+    runPreset: z.ZodObject<{
+        type: z.ZodEnum<["error", "performance", "api", "paint", "user_behav", "network", "server_error", "footprint", "server_api"]>;
+        log_time_start: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>>;
+    }, "strict", z.ZodTypeAny, {
+        type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+        log_time_start: string;
+    }, {
+        type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+        log_time_start?: string | undefined;
+    }>;
+    fetch: z.ZodObject<{
+        pageSize: z.ZodNumber;
+        maxPages: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        pageSize: number;
+        maxPages: number;
+    }, {
+        pageSize: number;
+        maxPages: number;
+    }>;
+    timeoutMs: z.ZodObject<{
+        query: z.ZodNumber;
+        flush: z.ZodNumber;
+        portal: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        query: number;
+        flush: number;
+        portal: number;
+    }, {
+        query: number;
+        flush: number;
+        portal: number;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    baseUrl: string;
+    defaults: {
+        bizline_id: string;
+        app_id: string;
+        host: string;
+    };
+    runPreset: {
+        type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+        log_time_start: string;
+    };
+    fetch: {
+        pageSize: number;
+        maxPages: number;
+    };
+    timeoutMs: {
+        query: number;
+        flush: number;
+        portal: number;
+    };
+}, {
+    baseUrl: string;
+    defaults: {
+        bizline_id: string;
+        app_id: string;
+        host: string;
+    };
+    runPreset: {
+        type: "error" | "performance" | "api" | "paint" | "user_behav" | "network" | "server_error" | "footprint" | "server_api";
+        log_time_start?: string | undefined;
+    };
+    fetch: {
+        pageSize: number;
+        maxPages: number;
+    };
+    timeoutMs: {
+        query: number;
+        flush: number;
+        portal: number;
+    };
+}>;
+export type ApmProviderConfig = z.infer<typeof apmProviderConfigSchema>;
+export declare function parseApmProviderConfig(raw: unknown): ApmProviderConfig;
+export {};

package/dist/apm/config.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { isSiteHost, LOG_TYPES, normalizeLogTime } from "./values.js";
+const logTimeStartSchema = z
+    .string()
+    .transform((value, context) => {
+    if (value === "") {
+        return value;
+    }
+    try {
+        return normalizeLogTime(value, "start");
+    }
+    catch (error) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return z.NEVER;
+    }
+})
+    .optional()
+    .default("");
+function isHttpUrl(value) {
+    if (!/^https?:\/\//i.test(value)) {
+        return false;
+    }
+    try {
+        return ["http:", "https:"].includes(new URL(value).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+const apmProviderConfigSchema = z
+    .object({
+    baseUrl: z
+        .string()
+        .refine(value => value === "" || isHttpUrl(value), "必须为空占位或合法的 http(s):// URL")
+        .transform(value => value.replace(/\/+$/, "")),
+    defaults: z
+        .object({
+        bizline_id: z.string().min(1, "不能为空"),
+        app_id: z.string().min(1, "不能为空"),
+        host: z
+            .string()
+            .refine(value => value === "" || isSiteHost(value), "必须为空占位或至少三段的完整站点 host，如 www.example.com"),
+    })
+        .strict(),
+    runPreset: z
+        .object({
+        type: z.enum(LOG_TYPES),
+        log_time_start: logTimeStartSchema,
+    })
+        .strict(),
+    fetch: z
+        .object({
+        pageSize: z.number().int().positive(),
+        maxPages: z.number().int().positive(),
+    })
+        .strict(),
+    timeoutMs: z
+        .object({
+        query: z.number().int().positive(),
+        flush: z.number().int().positive(),
+        portal: z.number().int().positive(),
+    })
+        .strict(),
+})
+    .strict();
+export function parseApmProviderConfig(raw) {
+    return apmProviderConfigSchema.parse(raw);
+}
+//# sourceMappingURL=config.js.map

package/dist/apm/errors.d.ts

@@ -0,0 +1,39 @@
+export type ApmErrorKind = "http" | "rejected" | "invalid_response" | "timeout" | "incomplete" | "unconfigured" | "invalid_config";
+export interface ApmRequestErrorOptions {
+    message?: string;
+    status?: number;
+    fetched?: number;
+    total?: number;
+    partialRows?: unknown[];
+    pagesFetched?: number;
+    request?: {
+        url: string;
+        body: Record<string, unknown>;
+    };
+    warnings?: string[];
+    hint?: string;
+    baseUrl?: string;
+    flush?: {
+        attempted: boolean;
+        ok?: boolean;
+        durationMs?: number;
+        message?: string;
+        reason?: ApmErrorKind;
+    };
+}
+export declare class ApmRequestError extends Error {
+    readonly kind: ApmErrorKind;
+    readonly status?: number;
+    readonly fetched?: number;
+    readonly total?: number;
+    readonly partialRows?: unknown[];
+    readonly pagesFetched?: number;
+    readonly request?: {
+        url: string;
+        body: Record<string, unknown>;
+    };
+    readonly warnings?: string[];
+    readonly hint?: string;
+    readonly flush?: ApmRequestErrorOptions["flush"];
+    constructor(kind: ApmErrorKind, options?: ApmRequestErrorOptions);
+}

package/dist/apm/errors.js

@@ -0,0 +1,39 @@
+function defaultMessage(kind, baseUrl) {
+    const messages = {
+        http: "APM 请求失败",
+        rejected: `接口拒绝（未给原因）：常见为 --where 列不存在 / 值格式错；持续失败请确认 ${baseUrl ?? "配置 baseUrl"} 可用`,
+        invalid_response: "APM 接口返回了无法识别的响应",
+        timeout: "APM 请求超时",
+        incomplete: "APM 查询达到最大页数，结果不完整",
+        unconfigured: "apm 未配置",
+        invalid_config: "apm 配置无效",
+    };
+    return messages[kind];
+}
+export class ApmRequestError extends Error {
+    kind;
+    status;
+    fetched;
+    total;
+    partialRows;
+    pagesFetched;
+    request;
+    warnings;
+    hint;
+    flush;
+    constructor(kind, options = {}) {
+        super(options.message ?? defaultMessage(kind, options.baseUrl));
+        this.name = "ApmRequestError";
+        this.kind = kind;
+        this.status = options.status;
+        this.fetched = options.fetched;
+        this.total = options.total;
+        this.partialRows = options.partialRows;
+        this.pagesFetched = options.pagesFetched;
+        this.request = options.request;
+        this.warnings = options.warnings;
+        this.hint = options.hint;
+        this.flush = options.flush;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/apm/portal.d.ts

@@ -0,0 +1,20 @@
+import type { ApmProviderConfig } from "./config.js";
+export interface ApmPortalDeps {
+    fetchImpl?: typeof fetch;
+}
+export interface ResolveUserIdParams {
+    value: string;
+    host: string;
+}
+export interface FetchLiveProjectParams {
+    projectId: string;
+    host: string;
+}
+export interface LiveProjectResult {
+    text: string;
+    parsed: Record<string, unknown>;
+    updatedDate: unknown;
+    hasProject: boolean;
+}
+export declare function resolveUserId(config: ApmProviderConfig, params: ResolveUserIdParams, deps?: ApmPortalDeps): Promise<string>;
+export declare function fetchLiveProject(config: ApmProviderConfig, params: FetchLiveProjectParams, deps?: ApmPortalDeps): Promise<LiveProjectResult>;