@alphafox/cli 0.3.2 → 0.3.4

package/dist/catalog/omit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Chat-attached `/api/v1/backtests` jobs are not a CLI surface.
+ * Local Engine WASM (`engine-backtest run`) and `engine_backtest.*` stay.
+ * Match `backtests` / `backtests.*` only — never `engine_backtest.*`.
+ */
+export declare function isOmittedCatalogOperation(operationId: string): boolean;

package/dist/catalog/omit.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOmittedCatalogOperation = isOmittedCatalogOperation;
+/**
+ * Chat-attached `/api/v1/backtests` jobs are not a CLI surface.
+ * Local Engine WASM (`engine-backtest run`) and `engine_backtest.*` stay.
+ * Match `backtests` / `backtests.*` only — never `engine_backtest.*`.
+ */
+function isOmittedCatalogOperation(operationId) {
+    return operationId === "backtests" || operationId.startsWith("backtests.");
+}

package/dist/catalog/operations.d.ts

@@ -102,6 +102,6 @@ export declare function buildCapabilityManifest(): {
         errorSchema: string;
     }[];
 };
-/** Resolve path templates like /api/v1/backtests/{backtestId}. */
+/** Resolve path templates like /api/v1/engine-backtest/experiments/{experimentId}. */
 export declare function resolveOperationPath(template: string, params: Record<string, string>): string;
 export declare function checkGeneratedCatalogCompatibility(cliVersion: string): import("./compatibility").CompatibilityResult;

package/dist/catalog/operations.js

@@ -19,11 +19,12 @@ exports.checkGeneratedCatalogCompatibility = checkGeneratedCatalogCompatibility;
 const compatibility_1 = require("./compatibility");
 const registry_json_1 = __importDefault(require("./generated/registry.json"));
 const schemas_json_1 = __importDefault(require("./generated/schemas.json"));
+const omit_1 = require("./omit");
 const generated = registry_json_1.default;
 const generatedSchemas = schemas_json_1.default;
 exports.CATALOG_SOURCE = generated.source;
 exports.CATALOG_VERSION = generated.compatibility.contractVersion;
-exports.CATALOG_OPERATIONS = generated.operations;
+exports.CATALOG_OPERATIONS = generated.operations.filter((op) => !(0, omit_1.isOmittedCatalogOperation)(op.operationId));
 exports.COMPATIBILITY_RANGE = generated.compatibility;
 function getCompatibilityRange() {
     return exports.COMPATIBILITY_RANGE;
@@ -63,6 +64,8 @@ function pathTemplateMatchesOp(template, actual, catchAll) {
     return true;
 }
 function getOperationSchemaDocument(operationId) {
+    if ((0, omit_1.isOmittedCatalogOperation)(operationId))
+        return undefined;
     return generatedSchemas[operationId];
 }
 function extractPathParamNames(template) {
@@ -103,7 +106,7 @@ function buildCapabilityManifest() {
         })),
     };
 }
-/** Resolve path templates like /api/v1/backtests/{backtestId}. */
+/** Resolve path templates like /api/v1/engine-backtest/experiments/{experimentId}. */
 function resolveOperationPath(template, params) {
     return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, key) => {
         const value = params[key];

package/dist/commands/run.js

@@ -14,6 +14,7 @@ const store_1 = require("../keychain/store");
 const confirmation_1 = require("../safety/confirmation");
 const version_1 = require("../version");
 const run_command_1 = require("../engine-backtest/run-command");
+const run_command_2 = require("../resolve-symbols/run-command");
 const validate_body_1 = require("../catalog/validate-body");
 const types_1 = require("../install/types");
 const wizard_1 = require("../install/wizard");
@@ -94,6 +95,8 @@ async function runCli(argv, env = process.env) {
                 "alphafox catalog",
                 "alphafox api METHOD PATH [--body JSON|--config @file]",
                 "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file --exchange <id> --range FROM..TO --initial-equity N",
+                "alphafox engine-backtest sweep --experiment <uuid> --definition <id> --config @file --axes @file --exchange <id> --range FROM..TO --initial-equity N --no-persist",
+                "alphafox resolve-symbols <query...> [--exchange binance]",
                 "alphafox <domain> <resource> <action> [flags]",
             ],
         }, { format: flags.format, jq: flags.jq });
@@ -126,15 +129,19 @@ async function runCli(argv, env = process.env) {
                 const sub = args[0];
                 if (!sub ||
                     sub === "run" ||
+                    sub === "sweep" ||
                     sub === "help" ||
                     sub === "--help" ||
                     sub === "-h") {
                     return await (0, run_command_1.cmdEngineBacktest)(args, flags, env);
                 }
-                // Hyphen built-in only owns `run`. Underscore/hyphen catalog CRUD
+                // Hyphen built-in owns `run` and `sweep`. Underscore/hyphen catalog CRUD
                 // (engine_backtest.experiments.*) still goes through the typed tree.
                 return await cmdTyped(cmd, args, flags, env);
             }
+            case "resolve-symbols":
+            case "resolve-symbol":
+                return await (0, run_command_2.cmdResolveSymbols)(args, flags, env);
             default:
                 return await cmdTyped(cmd, args, flags, env);
         }
@@ -174,8 +181,8 @@ async function cmdInstall(args, flags, env) {
         (0, envelope_1.writeError)({
             type: "usage",
             subtype: "unknown_install_flag",
-            message: `Unknown install flag: ${parsed.unknown.join(" ")}`,
-            hint: "Usage: alphafox install [--no-auth] [--dry-run]",
+            message: `未知的 install 参数：${parsed.unknown.join(" ")}`,
+            hint: "用法：alphafox install [--no-auth] [--dry-run]",
         });
     }
     if (parsed.help) {

package/dist/engine-backtest/load-config.d.ts

@@ -0,0 +1,4 @@
+export declare function loadConfigValue(raw: string, options?: {
+    readonly cwd?: string;
+    readonly readFile?: (path: string) => string;
+}): unknown;

package/dist/engine-backtest/load-config.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfigValue = loadConfigValue;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_1 = require("./errors");
+function loadConfigValue(raw, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const read = options.readFile ?? ((p) => (0, node_fs_1.readFileSync)(p, "utf8"));
+    if (raw.startsWith("@")) {
+        const rel = raw.slice(1);
+        if (!rel) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "missing_config",
+                message: "--config @path is empty",
+                status: 400,
+            });
+        }
+        const abs = (0, node_path_1.isAbsolute)(rel) ? rel : (0, node_path_1.resolve)(cwd, rel);
+        try {
+            return JSON.parse(read(abs));
+        }
+        catch (err) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "invalid_config",
+                message: `Cannot read --config file ${abs}: ${err instanceof Error ? err.message : String(err)}`,
+                status: 400,
+            });
+        }
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            subtype: "invalid_config",
+            message: "--config must be JSON or @path-to.json",
+            status: 400,
+        });
+    }
+}

package/dist/engine-backtest/parse-args.d.ts

@@ -1,6 +1,8 @@
-import type { EngineBacktestRunArgs, ExecutionModel, InclusiveUtcDateRange } from "./types";
+import type { EngineBacktestRunArgs, EngineBacktestSweepArgs, ExecutionModel, InclusiveUtcDateRange } from "./types";
 export declare const ENGINE_BACKTEST_RUN_USAGE: string[];
+export declare const ENGINE_BACKTEST_SWEEP_USAGE: string[];
 export declare function parseInclusiveUtcDateRange(rangeStart: string, rangeEnd: string): InclusiveUtcDateRange;
 export declare function parseRangeFlag(raw: string): InclusiveUtcDateRange;
 export declare function parseExecutionModelJson(raw: string): Partial<ExecutionModel>;
 export declare function parseEngineBacktestRunArgs(args: readonly string[]): EngineBacktestRunArgs;
+export declare function parseEngineBacktestSweepArgs(args: readonly string[]): EngineBacktestSweepArgs;

package/dist/engine-backtest/parse-args.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENGINE_BACKTEST_RUN_USAGE = void 0;
+exports.ENGINE_BACKTEST_SWEEP_USAGE = exports.ENGINE_BACKTEST_RUN_USAGE = void 0;
 exports.parseInclusiveUtcDateRange = parseInclusiveUtcDateRange;
 exports.parseRangeFlag = parseRangeFlag;
 exports.parseExecutionModelJson = parseExecutionModelJson;
 exports.parseEngineBacktestRunArgs = parseEngineBacktestRunArgs;
+exports.parseEngineBacktestSweepArgs = parseEngineBacktestSweepArgs;
 const errors_1 = require("./errors");
 const replay_timeframe_1 = require("./replay-timeframe");
+const sweep_kernel_1 = require("./sweep-kernel");
 const DAY_MS = 86_400_000;
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const TIERS = new Set(["free", "pro", "pro_max"]);
@@ -16,12 +18,17 @@ exports.ENGINE_BACKTEST_RUN_USAGE = [
     "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file.json --exchange <id> --range YYYY-MM-DD..YYYY-MM-DD --initial-equity N [--replay-timeframe 1m]",
     "alphafox engine-backtest run --create-experiment --name <name> --definition <id> --config @file.json --exchange <id> --from YYYY-MM-DD --to YYYY-MM-DD --initial-equity N",
 ];
-function usage(message, subtype = "invalid_args") {
+exports.ENGINE_BACKTEST_SWEEP_USAGE = [
+    "alphafox engine-backtest sweep --experiment <uuid> --definition <id> --config @file.json --axes @axes.json --exchange <id> --range YYYY-MM-DD..YYYY-MM-DD --initial-equity N [--no-persist] [--mode neighborhood|range] [--search-mode standard|fast] [--concurrency N]",
+];
+const SWEEP_MODES = new Set(["neighborhood", "range"]);
+const SEARCH_MODES = new Set(["standard", "fast"]);
+function usage(message, subtype = "invalid_args", hint = exports.ENGINE_BACKTEST_RUN_USAGE[0]) {
     throw new errors_1.EngineBacktestError({
         type: "usage",
         subtype,
         message,
-        hint: exports.ENGINE_BACKTEST_RUN_USAGE[0],
+        hint,
         status: 400,
     });
 }
@@ -279,3 +286,80 @@ function parseEngineBacktestRunArgs(args) {
         replayTimeframe,
     };
 }
+function parseEngineBacktestSweepArgs(args) {
+    let axesRaw;
+    let mode = "neighborhood";
+    let searchMode = "standard";
+    let concurrency = sweep_kernel_1.DEFAULT_SWEEP_CONCURRENCY;
+    let help = false;
+    const rest = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--help" || a === "-h") {
+            help = true;
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const flag = eq >= 0 ? a.slice(0, eq) : a;
+        const inline = eq >= 0 ? a.slice(eq + 1) : undefined;
+        const read = () => {
+            if (inline !== undefined)
+                return inline;
+            const taken = takeValue(args, i, flag);
+            i = taken.next;
+            return taken.value;
+        };
+        if (flag === "--axes") {
+            axesRaw = read();
+            continue;
+        }
+        if (flag === "--mode") {
+            const raw = read().trim();
+            if (!SWEEP_MODES.has(raw)) {
+                usage("--mode must be neighborhood|range", "invalid_sweep_mode", exports.ENGINE_BACKTEST_SWEEP_USAGE[0]);
+            }
+            mode = raw;
+            continue;
+        }
+        if (flag === "--search-mode") {
+            const raw = read().trim();
+            if (!SEARCH_MODES.has(raw)) {
+                usage("--search-mode must be standard|fast", "invalid_search_mode", exports.ENGINE_BACKTEST_SWEEP_USAGE[0]);
+            }
+            searchMode = raw;
+            continue;
+        }
+        if (flag === "--concurrency") {
+            const n = Number(read());
+            if (!Number.isInteger(n) || n < 1) {
+                usage("--concurrency must be a positive integer", "invalid_concurrency", exports.ENGINE_BACKTEST_SWEEP_USAGE[0]);
+            }
+            concurrency = n;
+            continue;
+        }
+        rest.push(a);
+    }
+    if (help) {
+        return {
+            help: true,
+            createExperiment: false,
+            dataQualityMode: "strict",
+            persist: true,
+            replayTimeframe: replay_timeframe_1.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME,
+            axesRaw,
+            mode,
+            searchMode,
+            concurrency,
+        };
+    }
+    if (!axesRaw) {
+        usage("--axes is required (@file.json or JSON)", "missing_axes", exports.ENGINE_BACKTEST_SWEEP_USAGE[0]);
+    }
+    return {
+        ...parseEngineBacktestRunArgs(rest),
+        axesRaw,
+        mode,
+        searchMode,
+        concurrency,
+    };
+}

package/dist/engine-backtest/parse-axes.d.ts

@@ -0,0 +1,3 @@
+import type { SweepAxisInput } from "./sweep-kernel";
+import type { SweepMode } from "./types";
+export declare function parseSweepAxesDocument(raw: unknown, config: unknown, mode: SweepMode): SweepAxisInput[];

package/dist/engine-backtest/parse-axes.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSweepAxesDocument = parseSweepAxesDocument;
+const errors_1 = require("./errors");
+const NEIGHBORHOOD_STEPS = 3;
+function usage(message, subtype) {
+    throw new errors_1.EngineBacktestError({
+        type: "usage",
+        subtype,
+        message,
+        hint: "Each --axes entry needs an explicit config path and either values or min/max/step.",
+        status: 400,
+    });
+}
+function parseSweepAxesDocument(raw, config, mode) {
+    const list = listAxes(raw);
+    if (list.length === 0) {
+        usage("--axes must contain at least one axis", "invalid_axes");
+    }
+    return list.map((item, index) => parseSweepAxis(item, config, mode, index));
+}
+function listAxes(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const axes = raw.axes;
+        if (Array.isArray(axes)) {
+            return axes;
+        }
+    }
+    usage("--axes must be a JSON array or {\"axes\": [...]}", "invalid_axes");
+}
+function parseSweepAxis(raw, config, mode, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        usage(`Axis ${index} must be an object`, "invalid_axis");
+    }
+    const row = raw;
+    const path = parseAxisPath(row.path, index);
+    const current = readNumericCurrent(config, path, index);
+    const values = parseOptionalNumberList(row.values, `Axis ${index} values`);
+    const min = optionalFiniteNumber(row.min, `Axis ${index} min`);
+    const max = optionalFiniteNumber(row.max, `Axis ${index} max`);
+    const step = optionalFiniteNumber(row.step, `Axis ${index} step`);
+    const hasWindow = min !== undefined && max !== undefined && step !== undefined;
+    if (!values && !hasWindow) {
+        usage(`Axis ${index} must set values or min/max/step`, "invalid_axis_window");
+    }
+    if (hasWindow && !(step > 0)) {
+        usage(`Axis ${index} step must be > 0`, "invalid_axis_window");
+    }
+    const isInteger = typeof row.isInteger === "boolean"
+        ? row.isInteger
+        : inferInteger(current, values, step);
+    const axis = {
+        path,
+        current,
+        isInteger,
+        ...(min === undefined ? {} : { min }),
+        ...(max === undefined ? {} : { max }),
+        ...(typeof row.minExclusive === "boolean"
+            ? { minExclusive: row.minExclusive }
+            : {}),
+        ...(typeof row.maxExclusive === "boolean"
+            ? { maxExclusive: row.maxExclusive }
+            : {}),
+        ...(values ? { values } : {}),
+        ...(values || step === undefined
+            ? {}
+            : {
+                window: mode === "neighborhood"
+                    ? {
+                        min: current - NEIGHBORHOOD_STEPS * step,
+                        max: current + NEIGHBORHOOD_STEPS * step,
+                        step,
+                    }
+                    : { min: min, max: max, step },
+            }),
+    };
+    return axis;
+}
+function parseAxisPath(raw, index) {
+    if (typeof raw === "string") {
+        const path = raw.split(".").filter((segment) => segment.length > 0);
+        if (path.length === 0) {
+            usage(`Axis ${index} path must not be empty`, "invalid_axis_path");
+        }
+        return path;
+    }
+    if (Array.isArray(raw)) {
+        if (raw.length === 0 ||
+            raw.some((segment) => typeof segment !== "string" || segment.length === 0)) {
+            usage(`Axis ${index} path must be a non-empty array of segments`, "invalid_axis_path");
+        }
+        return raw;
+    }
+    usage(`Axis ${index} must identify an explicit config path`, "invalid_axis_path");
+}
+function readNumericCurrent(config, path, index) {
+    const value = getValueAtPath(config, path);
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        usage(`Axis ${index} current value at ${path.join(".")} must be a finite number in --config`, "invalid_axis_current");
+    }
+    return value;
+}
+function parseOptionalNumberList(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(raw) || raw.length === 0) {
+        usage(`${label} must be a non-empty number array`, "invalid_axis_values");
+    }
+    const values = raw.map((value, valueIndex) => {
+        const n = Number(value);
+        if (!Number.isFinite(n)) {
+            usage(`${label}[${valueIndex}] must be a finite number`, "invalid_axis_values");
+        }
+        return n;
+    });
+    return values;
+}
+function optionalFiniteNumber(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+        usage(`${label} must be a finite number`, "invalid_axis_window");
+    }
+    return n;
+}
+function inferInteger(current, values, step) {
+    const candidates = [
+        current,
+        ...(values ?? []),
+        ...(step === undefined ? [] : [step]),
+    ];
+    return candidates.every((value) => Number.isInteger(value));
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseArrayIndex(segment) {
+    if (!/^\d+$/.test(segment)) {
+        return null;
+    }
+    const index = Number(segment);
+    return Number.isInteger(index) && index >= 0 ? index : null;
+}
+function getValueAtPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (Array.isArray(current)) {
+            const index = parseArrayIndex(segment);
+            if (index === null) {
+                return undefined;
+            }
+            current = current[index];
+            continue;
+        }
+        if (!isPlainRecord(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}

package/dist/engine-backtest/persist.d.ts

@@ -1,5 +1,5 @@
 import type { ProfileName } from "../config/profiles";
-import type { CreateRunRequestBody, DataQualityMode, EngineBacktestMetrics, EngineBacktestScenario, ExecutionModel } from "./types";
+import type { CreateRunRequestBody, CreateSweepRequestBody, DataQualityMode, EngineBacktestMetrics, EngineBacktestScenario, EngineBacktestSweepPointRow, ExecutionModel, PersistedSnapshot, SweepMode, SweepSearchMode } from "./types";
 /** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
 export declare const DEFAULT_EXECUTION_MODEL: ExecutionModel;
 export declare const SNAPSHOT_SCHEMA_VERSION: 1;
@@ -23,6 +23,7 @@ export declare function buildCreateRunRequest(input: {
     readonly exchangeId: string;
     readonly dataQualityMode: DataQualityMode;
     readonly engineVersion: string;
+    readonly equityCurve?: unknown;
 }): CreateRunRequestBody;
 /**
  * Experiment detail URL. Locale prefix (`/zh`, `/en`) is optional — web
@@ -30,3 +31,61 @@ export declare function buildCreateRunRequest(input: {
  * unprefixed `/dashboard/traders/backtest/{id}` path.
  */
 export declare function experimentPageUrl(profile: ProfileName, experimentId: string): string;
+/** Web experiment workspace opens the Sweep tab with `?tab=sweep`. */
+export declare function experimentSweepPageUrl(profile: ProfileName, experimentId: string): string;
+export declare const ENGINE_BACKTEST_SWEEP_MAX_UTF8_BYTES: number;
+export declare const ENGINE_BACKTEST_SWEEP_ERROR_MAX_UTF8_BYTES: number;
+export declare function shouldPersistSweepCompletion(input: {
+    readonly completed: boolean;
+    readonly cancelled: boolean;
+}): boolean;
+export declare function mintClientSweepId(randomUuid?: () => string): string;
+export declare function sweepsPath(experimentId: string): string;
+export declare function buildSweepBaseSnapshot(input: {
+    readonly definitionId: string;
+    readonly configSchemaVersion: number;
+    readonly config: unknown;
+    readonly exchangeId: string;
+    readonly rangeStart: string;
+    readonly rangeEnd: string;
+    readonly initialEquity: number;
+    readonly subscriptionTier: PersistedSnapshot["subscriptionTier"];
+    readonly dataQualityMode: DataQualityMode;
+    readonly symbols: readonly string[];
+    readonly timeframes: readonly string[];
+    readonly baseTimeframe: string;
+    readonly executionModel: ExecutionModel;
+    readonly positionSideDual: boolean;
+    readonly engineVersion: string;
+}): PersistedSnapshot;
+/**
+ * Build POST .../sweeps body from a completed local search.
+ * Field set matches web `buildCreateSweepRequestFromCompleted`.
+ */
+export declare function buildCreateSweepRequest(input: {
+    readonly clientSweepId: string;
+    readonly snapshot: PersistedSnapshot;
+    readonly axes: ReadonlyArray<{
+        readonly path: readonly string[];
+        readonly current: number;
+        readonly values: readonly number[];
+    }>;
+    readonly mode: SweepMode;
+    readonly searchMode: SweepSearchMode;
+    readonly concurrency: number;
+    readonly requestedCombinationCount: number;
+    readonly sampled: boolean;
+    readonly points: readonly EngineBacktestSweepPointRow[];
+    readonly successfulCount: number;
+    readonly failedCount: number;
+    readonly liquidatedCount: number;
+    readonly elapsedMs: number;
+    readonly best: {
+        readonly coordinate: {
+            readonly values: readonly number[];
+        };
+        readonly returnPct: number;
+    } | null;
+    readonly engineVersion: string;
+}): CreateSweepRequestBody;
+export declare function assertSweepCreateRequestSize(body: CreateSweepRequestBody): void;