@ats-cx/cx-cli 0.1.0

package/dist/tools/apm-tools.js

@@ -0,0 +1,329 @@
+import { ApmRequestError, assertColumnName, assertSafeValue, createApmClient, createApmConfigError, fetchLiveProject, FIXED_REQUEST_KEYS, isSiteHost, isApmConfigured, LOG_TYPES, normalizeLogTime, ORDERS, resolveUserId, } from "@ats-cx/cx-core";
+import { z } from "zod";
+import { buildQueryPreview, createProjectFileName, createQueryFileName, resolveApmOutputFile, writeQueryDump, writeRawApmFile, } from "../apm-output.js";
+import { defineTool } from "../contract.js";
+function requireApmProvider(config) {
+    if (!isApmConfigured(config.apmProviderState)) {
+        throw createApmConfigError(config.apmProviderState);
+    }
+    if (config.apmProvider === null) {
+        throw new ApmRequestError("invalid_config", { message: "apm 配置状态与 provider 不一致" });
+    }
+    return config.apmProvider;
+}
+function stringWithValidation(validate) {
+    return z.string().superRefine((value, context) => {
+        try {
+            validate(value);
+        }
+        catch (error) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+}
+const safeValueSchema = stringWithValidation(value => assertSafeValue("值", value));
+const emailSchema = stringWithValidation(value => {
+    assertSafeValue("email", value);
+    if (!value.includes("@")) {
+        throw new Error("email 必须包含 @");
+    }
+});
+const phoneSchema = stringWithValidation(value => {
+    assertSafeValue("phone", value);
+    if (!/^1[3-9]\d{9}$/.test(value)) {
+        throw new Error("phone 必须是 1 开头的 11 位中国大陆手机号");
+    }
+});
+const hostSchema = stringWithValidation(value => {
+    assertSafeValue("host", value);
+    if (!isSiteHost(value)) {
+        throw new Error("传日志 host 列的完整域名，如 www.example.com");
+    }
+});
+function logTimeSchema(edge) {
+    return z.string().transform((value, context) => {
+        try {
+            return normalizeLogTime(value, edge);
+        }
+        catch (error) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return z.NEVER;
+        }
+    });
+}
+const whereSchema = z.array(z.string()).transform((entries, context) => {
+    const where = {};
+    entries.forEach((entry, index) => {
+        const separator = entry.indexOf("=");
+        const column = separator >= 0 ? entry.slice(0, separator) : entry;
+        const value = separator >= 0 ? entry.slice(separator + 1) : "";
+        try {
+            assertColumnName(column);
+            if (column === "type") {
+                throw new Error("type 不可用于 --where：接口把请求键 type 当日志类型（即 --type）而非列名，此列无法过滤；先落盘再用 jq 筛");
+            }
+            if (FIXED_REQUEST_KEYS.has(column)) {
+                throw new Error(`${column} 是固定请求键，不能通过 --where 覆盖`);
+            }
+            if (column === "data_name") {
+                throw new Error("data_name 不可用于 --where，请用 --event");
+            }
+            if (value.length === 0) {
+                throw new Error(`--where ${column}= 的值不能为空`);
+            }
+            assertSafeValue(`--where ${column}`, value);
+            if (Object.hasOwn(where, column)) {
+                throw new Error(`--where 同一列不能重复: ${column}`);
+            }
+            where[column] = value;
+        }
+        catch (error) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [index],
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    return where;
+});
+const queryInputSchema = z
+    .object({
+    type: z.enum(LOG_TYPES).optional(),
+    from: logTimeSchema("start"),
+    to: logTimeSchema("end").optional(),
+    order: z.enum(ORDERS).optional(),
+    project: safeValueSchema.optional(),
+    user: safeValueSchema.optional(),
+    collection: safeValueSchema.optional(),
+    session: safeValueSchema.optional(),
+    subType: safeValueSchema.optional(),
+    event: safeValueSchema.optional(),
+    app: safeValueSchema.optional(),
+    bizline: safeValueSchema.optional(),
+    item: safeValueSchema.optional(),
+    search: safeValueSchema.optional(),
+    where: whereSchema.optional(),
+    limit: z.number().int().min(1).optional(),
+    count: z.boolean().optional(),
+    preview: z.number().int().min(1).max(200).optional(),
+    full: z.boolean().optional(),
+    out: z.string().min(1).optional(),
+    run: z.string().min(1).optional(),
+    noFlush: z.boolean().optional(),
+})
+    .superRefine((input, context) => {
+    if (input.to !== undefined && input.to < input.from) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["to"], message: "结束时间不能早于开始时间" });
+    }
+    if (input.item !== undefined && [input.project, input.user, input.collection].some(value => value !== undefined)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["item"],
+            message: "--item 与 --project / --user / --collection 互斥",
+        });
+    }
+    if (input.run !== undefined && input.out !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["run"], message: "--run 与 --out 互斥" });
+    }
+    if (input.count === true) {
+        const conflicts = ["limit", "preview", "full", "out", "run"];
+        const provided = conflicts.filter(key => input[key] !== undefined && input[key] !== false);
+        if (provided.length > 0) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["count"],
+                message: `--count 与 ${provided.map(key => `--${key}`).join(" / ")} 互斥`,
+            });
+        }
+    }
+})
+    .transform(input => ({
+    ...input,
+    type: input.type ?? "user_behav",
+    order: input.order ?? "DESC",
+    preview: input.preview ?? 20,
+    count: input.count ?? false,
+    full: input.full ?? false,
+    noFlush: input.noFlush ?? false,
+    where: input.where ?? {},
+}));
+const resolveInputSchema = z
+    .object({
+    email: emailSchema.optional(),
+    phone: phoneSchema.optional(),
+    host: hostSchema.optional(),
+})
+    .superRefine((input, context) => {
+    if ((input.email === undefined) === (input.phone === undefined)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["email"],
+            message: "--email 与 --phone 必须且只能二选一",
+        });
+    }
+});
+const projectInputSchema = z
+    .object({
+    projectId: z.string().regex(/^\d+$/, "projectId 只收数字"),
+    host: hostSchema.optional(),
+    out: z.string().min(1).optional(),
+    run: z.string().min(1).optional(),
+})
+    .superRefine((input, context) => {
+    if (input.out !== undefined && input.run !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["run"], message: "--run 与 --out 互斥" });
+    }
+});
+export function createApmQueryTool(deps = {}) {
+    return defineTool({
+        name: "apm_query",
+        description: "查询 APM 埋点日志并落盘完整结果，stdout 返回摘要与预览",
+        inputSchema: queryInputSchema,
+        handler: async (input, context) => {
+            const config = requireApmProvider(context.config);
+            const client = createApmClient(config, {
+                ...deps,
+                onProgress: deps.onProgress ?? (message => console.error(message)),
+            });
+            const params = {
+                type: input.type,
+                from: input.from,
+                to: input.to,
+                order: input.order,
+                project: input.project,
+                user: input.user,
+                collection: input.collection,
+                session: input.session,
+                subType: input.subType,
+                event: input.event,
+                app: input.app ?? config.defaults.app_id,
+                bizline: input.bizline ?? config.defaults.bizline_id,
+                where: input.where,
+                item: input.item,
+                search: input.search,
+                limit: input.limit,
+                flush: !input.noFlush,
+            };
+            if (input.count) {
+                const result = await client.count(params);
+                return { total: result.total };
+            }
+            const file = resolveApmOutputFile({
+                out: input.out,
+                run: input.run,
+                runsDir: context.config.runsDir,
+                outDir: context.config.outDir,
+                fileName: createQueryFileName(input.type),
+            });
+            try {
+                const result = await client.query(params);
+                const fetchedAt = new Date();
+                writeQueryDump(file, result.rows, {
+                    fetchedAt,
+                    request: result.request,
+                    flush: result.flush,
+                    total: result.total,
+                    fetched: result.rows.length,
+                    pagesFetched: result.pagesFetched,
+                    warnings: result.warnings,
+                });
+                return buildQueryPreview({
+                    rows: result.rows,
+                    total: result.total,
+                    pagesFetched: result.pagesFetched,
+                    file,
+                    order: input.order,
+                    preview: input.preview,
+                    full: input.full,
+                    alreadySorted: input.limit !== undefined,
+                    flush: result.flush,
+                });
+            }
+            catch (error) {
+                if (error instanceof ApmRequestError && error.kind === "incomplete" && error.partialRows !== undefined) {
+                    writeQueryDump(file, error.partialRows, {
+                        fetchedAt: new Date(),
+                        request: error.request ?? { url: `${config.baseUrl}/api/log/query`, body: {} },
+                        flush: error.flush ?? { attempted: !input.noFlush },
+                        total: error.total ?? error.partialRows.length,
+                        fetched: error.partialRows.length,
+                        pagesFetched: error.pagesFetched ?? 0,
+                        warnings: error.warnings ?? [],
+                    });
+                    throw Object.assign(error, { file });
+                }
+                throw error;
+            }
+        },
+    });
+}
+export function createApmFlushTool(deps = {}) {
+    return defineTool({
+        name: "apm_flush",
+        description: "让网页端把攒批未写入的事件落库",
+        inputSchema: z.object({}),
+        handler: async (_input, context) => {
+            const config = requireApmProvider(context.config);
+            const result = await createApmClient(config, deps).flush();
+            if (!result.ok) {
+                throw new ApmRequestError(result.reason ?? "invalid_response", {
+                    status: result.status,
+                    baseUrl: config.baseUrl,
+                });
+            }
+            return { flushed: true, message: result.message };
+        },
+    });
+}
+export function createApmResolveTool(deps = {}) {
+    return defineTool({
+        name: "apm_resolve",
+        description: "经网页端 portal 免登录路由把邮箱或手机号解析为 userId",
+        inputSchema: resolveInputSchema,
+        handler: async (input, context) => {
+            const config = requireApmProvider(context.config);
+            const host = input.host ?? config.defaults.host;
+            const value = input.email ?? input.phone;
+            const userId = await resolveUserId(config, { value, host }, deps);
+            return input.email !== undefined
+                ? { userId, email: input.email, host }
+                : { userId, phone: input.phone, host };
+        },
+    });
+}
+export function createApmProjectTool(deps = {}) {
+    return defineTool({
+        name: "apm_project",
+        description: "经网页端 portal 免登录路由拉取现网 project JSON 并原样落盘",
+        inputSchema: projectInputSchema,
+        handler: async (input, context) => {
+            const config = requireApmProvider(context.config);
+            const host = input.host ?? config.defaults.host;
+            const file = resolveApmOutputFile({
+                out: input.out,
+                run: input.run,
+                runsDir: context.config.runsDir,
+                outDir: context.config.outDir,
+                fileName: createProjectFileName(input.projectId),
+            });
+            const result = await fetchLiveProject(config, { projectId: input.projectId, host }, deps);
+            const bytes = writeRawApmFile(file, result.text);
+            if (!result.hasProject) {
+                console.error("警告: 返回体无 project 键（package 项目？），已原样落盘");
+            }
+            return { projectId: input.projectId, host, file, bytes, updatedDate: result.updatedDate };
+        },
+    });
+}
+export const apmQueryTool = createApmQueryTool();
+export const apmResolveTool = createApmResolveTool();
+export const apmProjectTool = createApmProjectTool();
+export const apmFlushTool = createApmFlushTool();
+//# sourceMappingURL=apm-tools.js.map

package/dist/tools/conclusion-tools.d.ts

@@ -0,0 +1,24 @@
+export declare const recordHypothesisTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    description: string;
+    confidence: "confirmed" | "likely" | "inconclusive";
+    evidenceRefs: string[];
+    missingEvidence: string[];
+}, {
+    recorded: boolean;
+    count: number;
+}>;
+export declare const finalizeDiagnosisTool: import("../contract.js").ToolDefinition<{
+    runId: string;
+    result?: unknown;
+}, {
+    ok: false;
+    errors: string[] | undefined;
+    reportPath?: undefined;
+    resultPath?: undefined;
+} | {
+    ok: true;
+    reportPath: string;
+    resultPath: string;
+    errors?: undefined;
+}>;

package/dist/tools/conclusion-tools.js

@@ -0,0 +1,61 @@
+import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { loadRun, validateDiagnosisResult, writeStageStatus } from "@ats-cx/cx-core";
+import { defineTool } from "../contract.js";
+import { renderReport } from "../report.js";
+function appendHypothesisLine(runDir, entry) {
+    const filePath = join(runDir, "artifacts", "hypotheses.jsonl");
+    appendFileSync(filePath, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
+    const content = readFileSync(filePath, "utf8").trim();
+    return content ? content.split("\n").length : 0;
+}
+export const recordHypothesisTool = defineTool({
+    name: "record_hypothesis",
+    description: "记录诊断假设、置信度、证据引用与缺失证据",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        description: z.string().min(1),
+        confidence: z.enum(["confirmed", "likely", "inconclusive"]),
+        evidenceRefs: z.array(z.string()),
+        missingEvidence: z.array(z.string()).default([]),
+    }),
+    handler: async (input, context) => {
+        const run = loadRun(context.config.runsDir, input.runId);
+        const count = appendHypothesisLine(run.runDir, {
+            description: input.description,
+            confidence: input.confidence,
+            evidenceRefs: input.evidenceRefs,
+            missingEvidence: input.missingEvidence,
+        });
+        return { recorded: true, count };
+    },
+});
+export const finalizeDiagnosisTool = defineTool({
+    name: "finalize_diagnosis",
+    description: "校验并提交诊断结论，生成 result.json 与六段式 report.md",
+    inputSchema: z.object({
+        runId: z.string().min(1),
+        result: z.unknown(),
+    }),
+    handler: async (input, context) => {
+        const run = loadRun(context.config.runsDir, input.runId);
+        const raw = typeof input.result === "object" && input.result !== null
+            ? { ...input.result }
+            : {};
+        raw.runId = input.runId;
+        raw.projectId = run.input.projectId;
+        const validation = validateDiagnosisResult(raw);
+        if (!validation.ok) {
+            return { ok: false, errors: validation.errors };
+        }
+        const result = validation.result;
+        const resultPath = join(run.runDir, "result.json");
+        writeFileSync(resultPath, JSON.stringify(result, null, 2));
+        const reportPath = join(run.runDir, "report.md");
+        writeFileSync(reportPath, renderReport(run.runDir, result, run.input.complaint));
+        writeStageStatus(run.runDir, "finalize", "completed");
+        return { ok: true, reportPath, resultPath };
+    },
+});
+//# sourceMappingURL=conclusion-tools.js.map

package/dist/tools/create-run.d.ts

@@ -0,0 +1,61 @@
+import type { SuspiciousSignal } from "@ats-cx/cx-core";
+export interface SemanticsCoverageEntry {
+    eventName: string;
+    count: number;
+    /** 解析器实际落的类别：inferred 条目带它即隐含风险级；unknown 的 error_payload 修补件在此显形为 "error"。 */
+    category: string;
+    /** 该事件名全部出现的 payload 键名并集（跨 session 聚合），排序后输出保证产物 diff 稳定。 */
+    payloadKeys: string[];
+}
+export interface SemanticsCoverage {
+    /** 命中显式表的去重事件名数（事件总次数由既有 eventCount 承担）。 */
+    explicitEventCount: number;
+    inferred: SemanticsCoverageEntry[];
+    unknown: SemanticsCoverageEntry[];
+}
+export interface CaseBrief {
+    projectId: string;
+    complaint: string;
+    sessionCount: number;
+    sessionIds: string[];
+    eventCount: number;
+    /**
+     * 日志实际覆盖的时间跨度（取自事件 logTime）。对照客诉发生时间：跨度盖不住事发时段，说明
+     * 事发会话根本没进日志源，只能记 missingEvidence，不能拿客服/研发的复现会话当客户行为分析。
+     */
+    logTimeRange: {
+        earliest: string | null;
+        latest: string | null;
+    };
+    /**
+     * 两钟差值（logTime − receivedTime 的中位数，分钟）。整小时 ≈ 时区差，零碎 ≈ 钟漂或上报缓冲；
+     * 判读口径见 apm-query skill「时间窗」。日志源无 received_time 时 medianOffsetMinutes 为 null 并降级提示。
+     */
+    clockSkew: {
+        medianOffsetMinutes: number | null;
+        hint: string | null;
+    };
+    projectVersions: string[];
+    suspiciousSignals: SuspiciousSignal[];
+    semanticsCoverage: SemanticsCoverage;
+    sourceRepos: Array<{
+        id: string;
+        reachable: boolean;
+    }>;
+    missingEvidence: string[];
+    logSource: {
+        source: "apm" | "file";
+        file?: string;
+        filter?: string;
+        matched: number;
+        other: number;
+    };
+}
+export declare const createRunTool: import("../contract.js").ToolDefinition<{
+    projectId: string;
+    complaint: string;
+    logsFile?: string | undefined;
+}, {
+    runId: string;
+    brief: CaseBrief;
+}>;