taskmeld 0.1.1

package/dist/src/cli/commands/pipeline/selector.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stopPipelineBySelector = exports.getPipelineStatusBySelector = exports.describePipelineSelector = exports.readPipelineSelector = exports.pickOptionalStringFlag = void 0;
+const errors_1 = require("../../errors");
+const pickOptionalStringFlag = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim();
+    return normalized || undefined;
+};
+exports.pickOptionalStringFlag = pickOptionalStringFlag;
+const readPipelineSelector = (input) => {
+    const pipelineId = input.args[0]?.trim() ? input.args[0].trim() : undefined;
+    const runId = (0, exports.pickOptionalStringFlag)(input.flags["run-id"]);
+    const batchRunId = (0, exports.pickOptionalStringFlag)(input.flags["batch-run-id"]);
+    if (pipelineId || runId || batchRunId) {
+        return { pipelineId, runId, batchRunId };
+    }
+    throw new errors_1.CliError("Missing pipeline selector: provide <pipelineId>, --run-id, or --batch-run-id", {
+        code: "INVALID_ARGUMENT",
+        exitCode: 2,
+    });
+};
+exports.readPipelineSelector = readPipelineSelector;
+const describePipelineSelector = (selector) => {
+    if (selector.runId)
+        return `runId=${selector.runId}`;
+    if (selector.batchRunId)
+        return `batchRunId=${selector.batchRunId}`;
+    if (selector.pipelineId)
+        return `pipelineId=${selector.pipelineId}`;
+    return "pipeline selector";
+};
+exports.describePipelineSelector = describePipelineSelector;
+const getPipelineStatusBySelector = async (ctx, selector) => {
+    const getPipelineStatus = ctx.app.pipelineService.getPipelineStatus;
+    if (!selector.runId && !selector.batchRunId && selector.pipelineId) {
+        return await getPipelineStatus(selector.pipelineId);
+    }
+    // daemon-first 迁移期允许 CLI 把 selector 整体下发，避免 status/watch/stop 再依赖“当前 pipeline 活跃运行”的隐式猜测。
+    return await getPipelineStatus(selector);
+};
+exports.getPipelineStatusBySelector = getPipelineStatusBySelector;
+const stopPipelineBySelector = async (ctx, selector) => {
+    const stopPipeline = ctx.app.pipelineService.stopPipeline;
+    if (!selector.runId && !selector.batchRunId && selector.pipelineId) {
+        return await stopPipeline(selector.pipelineId);
+    }
+    return await stopPipeline(selector);
+};
+exports.stopPipelineBySelector = stopPipelineBySelector;

package/dist/src/cli/commands/pipeline/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/cli/commands/pipeline/watch.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchPipelineUntilTerminal = void 0;
+const errors_1 = require("../../errors");
+const errors_2 = require("./errors");
+const selector_1 = require("./selector");
+const readFlagAsPositiveInteger = (value, fallback) => {
+    if (typeof value !== "string")
+        return fallback;
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+};
+const delay = async (ms) => {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+};
+const isTerminalStatus = (statusPayload) => {
+    if (statusPayload.ok === true && statusPayload.running === false)
+        return true;
+    const status = statusPayload.status;
+    if (!status)
+        return false;
+    if (status.running === false)
+        return true;
+    const runStatus = String(status.runStatus ?? "");
+    if (runStatus === "success" || runStatus === "failed" || runStatus === "stopped")
+        return true;
+    const batchStatus = String(status.batchRun?.status ?? "");
+    return batchStatus === "completed" || batchStatus === "failed" || batchStatus === "stopped";
+};
+const watchPipelineUntilTerminal = async (ctx, selector, timeoutFlag, intervalFlag) => {
+    const timeoutMs = readFlagAsPositiveInteger(timeoutFlag, 10 * 60 * 1000);
+    const intervalMs = readFlagAsPositiveInteger(intervalFlag, 1200);
+    const startAt = Date.now();
+    const selectorLabel = (0, selector_1.describePipelineSelector)(selector);
+    let wsSignalAvailable = typeof ctx.app.pipelineService.waitForPipelineWatchSignal === "function";
+    while (true) {
+        const statusResult = await (0, selector_1.getPipelineStatusBySelector)(ctx, selector);
+        if (statusResult.ok === false) {
+            (0, errors_2.throwSelectorScopedError)(statusResult, selector);
+        }
+        if (isTerminalStatus(statusResult)) {
+            return statusResult;
+        }
+        if (Date.now() - startAt > timeoutMs) {
+            throw new errors_1.CliError(`Pipeline watch timed out: ${selectorLabel}`, {
+                code: "PIPELINE_WATCH_TIMEOUT",
+                exitCode: 4,
+                details: { ...selector, timeoutMs },
+            });
+        }
+        if (wsSignalAvailable) {
+            try {
+                // daemon-first 路径优先基于 WS 事件触发下一次状态确认，减少无效轮询；
+                // 事件链路抖动时自动降级为 interval 轮询，避免 watch 因订阅失败直接中断。
+                await ctx.app.pipelineService.waitForPipelineWatchSignal?.(selector, Math.max(1, Math.min(intervalMs, timeoutMs - (Date.now() - startAt))));
+                continue;
+            }
+            catch {
+                wsSignalAvailable = false;
+            }
+        }
+        await delay(intervalMs);
+    }
+};
+exports.watchPipelineUntilTerminal = watchPipelineUntilTerminal;

package/dist/src/cli/commands/pipeline.js

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pipelineRoutes = exports.pipelineDiagnoseCommand = exports.pipelineRetryNodeCommand = exports.pipelineStopCommand = exports.pipelineWatchCommand = exports.pipelineStatusCommand = exports.pipelineStartCommand = exports.pipelineGetCommand = exports.pipelineListCommand = void 0;
+const errors_1 = require("../errors");
+const errors_2 = require("./pipeline/errors");
+const result_1 = require("./pipeline/result");
+const selector_1 = require("./pipeline/selector");
+const watch_1 = require("./pipeline/watch");
+const pipelineListCommand = async (_input, ctx) => {
+    return ctx.app.pipelineService.listPipelines();
+};
+exports.pipelineListCommand = pipelineListCommand;
+const pipelineGetCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const detail = await ctx.app.pipelineService.getPipelineById(pipelineId);
+    if (!detail) {
+        throw new errors_1.CliError(`Pipeline not found: ${pipelineId}`, {
+            code: "PIPELINE_NOT_FOUND",
+            exitCode: 3,
+            details: { pipelineId },
+        });
+    }
+    return detail;
+};
+exports.pipelineGetCommand = pipelineGetCommand;
+const pipelineStartCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const result = await ctx.app.pipelineService.startPipeline(pipelineId);
+    const data = result;
+    if (data.ok === false && data.error === "pipeline_not_found") {
+        throw new errors_1.CliError(`Pipeline not found: ${pipelineId}`, {
+            code: "PIPELINE_NOT_FOUND",
+            exitCode: 3,
+            details: { pipelineId },
+        });
+    }
+    if (data.ok === false && data.error === "batch_run_in_progress") {
+        throw new errors_1.CliError(`Batch run already in progress: ${pipelineId}`, {
+            code: "BATCH_RUN_IN_PROGRESS",
+            exitCode: 4,
+            details: { pipelineId, state: data.state ?? null },
+        });
+    }
+    if (data.ok === false) {
+        throw new errors_1.CliError(`Pipeline run failed: ${data.error ?? "unknown_error"}`, {
+            code: String(data.error ?? "PIPELINE_RUN_FAILED").toUpperCase(),
+            exitCode: 4,
+            details: {
+                pipelineId,
+                state: data.state ?? null,
+                remoteUrl: data.remoteUrl ?? null,
+                status: data.status ?? null,
+                detail: data.detail ?? null,
+            },
+        });
+    }
+    const shouldWatch = input.flags.watch === true || String(input.flags.watch ?? "").trim().toLowerCase() === "true";
+    if (shouldWatch) {
+        const watchResult = await (0, watch_1.watchPipelineUntilTerminal)(ctx, { pipelineId }, input.flags.timeout, input.flags.interval);
+        return {
+            ...result,
+            watch: watchResult,
+        };
+    }
+    return result;
+};
+exports.pipelineStartCommand = pipelineStartCommand;
+const pipelineStatusCommand = async (input, ctx) => {
+    const selector = (0, selector_1.readPipelineSelector)(input);
+    const result = await (0, selector_1.getPipelineStatusBySelector)(ctx, selector);
+    if (result.ok === false) {
+        (0, errors_2.throwSelectorScopedError)(result, selector);
+    }
+    return result;
+};
+exports.pipelineStatusCommand = pipelineStatusCommand;
+const pipelineWatchCommand = async (input, ctx) => {
+    const selector = (0, selector_1.readPipelineSelector)(input);
+    return (0, watch_1.watchPipelineUntilTerminal)(ctx, selector, input.flags.timeout, input.flags.interval);
+};
+exports.pipelineWatchCommand = pipelineWatchCommand;
+const pipelineStopCommand = async (input, ctx) => {
+    const selector = (0, selector_1.readPipelineSelector)(input);
+    const result = await (0, selector_1.stopPipelineBySelector)(ctx, selector);
+    if (result.ok === false && (result.error === "pipeline_not_found" || result.error === "run_not_found" || result.error === "batch_run_not_found")) {
+        (0, errors_2.throwSelectorScopedError)(result, selector);
+    }
+    if (result.ok === false && result.error === "batch_run_not_running") {
+        throw new errors_1.CliError(`Batch run not running: ${(0, selector_1.describePipelineSelector)(selector)}`, {
+            code: "BATCH_RUN_NOT_RUNNING",
+            exitCode: 4,
+            details: { ...selector, status: result.status ?? null },
+        });
+    }
+    return result;
+};
+exports.pipelineStopCommand = pipelineStopCommand;
+const pipelineRetryNodeCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const nodeId = (0, errors_1.assertRequiredArg)(input.args[1], "nodeId");
+    const itemKey = (0, selector_1.pickOptionalStringFlag)(input.flags.item);
+    const result = await ctx.app.pipelineService.retryNode({ pipelineId, nodeId, itemKey });
+    const data = result;
+    if (data.ok === false && data.error === "pipeline_not_found") {
+        throw new errors_1.CliError(`Pipeline not found: ${pipelineId}`, {
+            code: "PIPELINE_NOT_FOUND",
+            exitCode: 3,
+            details: { pipelineId },
+        });
+    }
+    if (data.retry?.ok === false && data.retry.error === "node_not_found") {
+        throw new errors_1.CliError(`Node not found: ${nodeId}`, {
+            code: "NODE_NOT_FOUND",
+            exitCode: 3,
+            details: { pipelineId, nodeId, itemKey: itemKey ?? null },
+        });
+    }
+    if (data.retry?.ok === false) {
+        throw new errors_1.CliError(`Retry node failed: ${data.retry.error ?? "unknown_error"}`, {
+            code: "RETRY_NODE_FAILED",
+            exitCode: 4,
+            details: { pipelineId, nodeId, itemKey: itemKey ?? null, result },
+        });
+    }
+    return result;
+};
+exports.pipelineRetryNodeCommand = pipelineRetryNodeCommand;
+const pipelineDiagnoseCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const nodeId = (0, errors_1.assertRequiredArg)(input.args[1], "nodeId");
+    const itemKey = (0, selector_1.pickOptionalStringFlag)(input.flags.item);
+    const result = await ctx.app.pipelineService.diagnoseNode({ pipelineId, nodeId, itemKey });
+    const data = result;
+    if (!data.diagnostics || (Array.isArray(data.diagnostics) && data.diagnostics.length === 0)) {
+        throw new errors_1.CliError(`No diagnostics available for node: ${nodeId}`, {
+            code: "DIAGNOSTICS_UNAVAILABLE",
+            exitCode: 3,
+            details: { pipelineId, nodeId, itemKey: itemKey ?? null },
+        });
+    }
+    return result;
+};
+exports.pipelineDiagnoseCommand = pipelineDiagnoseCommand;
+exports.pipelineRoutes = [
+    ...result_1.pipelineResultRoutes,
+    {
+        key: "pipeline.list",
+        path: ["pipeline", "list"],
+        description: "输出流水线列表",
+        handler: exports.pipelineListCommand,
+        help: {
+            usage: "taskmeld pipeline list [--format <json|md>]",
+            summary: "输出流水线列表",
+        },
+    },
+    {
+        key: "pipeline.get",
+        path: ["pipeline", "get"],
+        description: "输出指定流水线详情",
+        handler: exports.pipelineGetCommand,
+        help: {
+            usage: "taskmeld pipeline get <id> [--format <json|md>]",
+            args: [{ name: "id", required: true, description: "流水线 ID" }],
+            summary: "输出指定流水线详情",
+        },
+    },
+    {
+        key: "pipeline.start",
+        path: ["pipeline", "start"],
+        description: "发起指定流水线运行（不承诺已完成）",
+        handler: exports.pipelineStartCommand,
+        bootstrap: { runtimeApiOnly: true, ensureServerReady: true },
+        help: {
+            usage: "taskmeld pipeline start <pipelineId> [--watch] [--timeout <ms>] [--interval <ms>] [--format <json|md>]",
+            args: [{ name: "pipelineId", required: true, description: "流水线 ID" }],
+            options: [
+                { flags: ["--watch"], description: "启动后继续等待运行完成" },
+                { flags: ["--timeout"], valueName: "ms", description: "watch 超时时间，默认 600000" },
+                { flags: ["--interval"], valueName: "ms", description: "watch 轮询间隔，默认 1200" },
+            ],
+            notes: [
+                "start 只负责发起运行请求，不承诺命令返回时业务已执行完成。",
+                "--watch 会在发起成功后进入等待流程。",
+            ],
+        },
+    },
+    {
+        key: "pipeline.status",
+        path: ["pipeline", "status"],
+        description: "输出指定流水线当前运行状态",
+        handler: exports.pipelineStatusCommand,
+        bootstrap: { runtimeApiOnly: true, ensureServerReady: true },
+        help: {
+            usage: "taskmeld pipeline status [<pipelineId>] [--run-id <id>] [--batch-run-id <id>] [--format <json|md>]",
+            args: [{ name: "pipelineId", description: "兼容入口，按流水线 ID 查询当前运行" }],
+            options: [
+                { flags: ["--run-id"], valueName: "id", description: "按单次运行 ID 精确查询" },
+                { flags: ["--batch-run-id"], valueName: "id", description: "按批跑 ID 精确查询" },
+            ],
+            examples: [
+                "taskmeld pipeline status A",
+                "taskmeld pipeline status A --run-id run-123",
+                "taskmeld pipeline status A --batch-run-id batch:A:2026-05-08T18:34:08.978Z",
+            ],
+            notes: [
+                "需要至少提供 <pipelineId>、--run-id、--batch-run-id 之一。",
+                "未提供 selector 时，默认按 pipelineId 查询当前活动运行。",
+            ],
+        },
+    },
+    {
+        key: "pipeline.watch",
+        path: ["pipeline", "watch"],
+        description: "监听指定流水线直到结束或超时",
+        handler: exports.pipelineWatchCommand,
+        bootstrap: { runtimeApiOnly: true, ensureServerReady: true },
+        help: {
+            usage: "taskmeld pipeline watch [<pipelineId>] [--run-id <id>] [--batch-run-id <id>] [--timeout <ms>] [--interval <ms>] [--format <json|md>]",
+            args: [{ name: "pipelineId", description: "兼容入口，监听该流水线当前运行" }],
+            options: [
+                { flags: ["--run-id"], valueName: "id", description: "按单次运行 ID 精确监听" },
+                { flags: ["--batch-run-id"], valueName: "id", description: "按批跑 ID 精确监听" },
+                { flags: ["--timeout"], valueName: "ms", description: "watch 超时时间，默认 600000" },
+                { flags: ["--interval"], valueName: "ms", description: "watch 轮询间隔，默认 1200" },
+            ],
+            examples: [
+                "taskmeld pipeline watch A",
+                "taskmeld pipeline watch --run-id run-123",
+                "taskmeld pipeline watch --batch-run-id batch:A:2026-05-08T18:34:08.978Z --timeout 900000",
+            ],
+            notes: [
+                "watch 是监听命令，不负责发起新运行。",
+                "需要至少提供 <pipelineId>、--run-id、--batch-run-id 之一。",
+                "当前 watch 语义为事件流优先，轮询作为兜底路径。",
+            ],
+        },
+    },
+    {
+        key: "pipeline.stop",
+        path: ["pipeline", "stop"],
+        description: "停止指定流水线批跑任务",
+        handler: exports.pipelineStopCommand,
+        bootstrap: { runtimeApiOnly: true, ensureServerReady: true },
+        help: {
+            usage: "taskmeld pipeline stop [<pipelineId>] [--run-id <id>] [--batch-run-id <id>] [--format <json|md>]",
+            args: [{ name: "pipelineId", description: "兼容入口，停止该流水线当前运行" }],
+            options: [
+                { flags: ["--run-id"], valueName: "id", description: "按单次运行 ID 精确停止" },
+                { flags: ["--batch-run-id"], valueName: "id", description: "按批跑 ID 精确停止" },
+            ],
+            notes: [
+                "需要至少提供 <pipelineId>、--run-id、--batch-run-id 之一。",
+                "当前 stop 主要用于停止批跑任务。",
+                "对非批跑运行会返回业务错误，而不是静默成功。",
+            ],
+        },
+    },
+    {
+        key: "pipeline.retry-node",
+        path: ["pipeline", "retry-node"],
+        description: "重试指定节点或节点条目",
+        handler: exports.pipelineRetryNodeCommand,
+        bootstrap: { gateway: "required" },
+        help: {
+            usage: "taskmeld pipeline retry-node <pipelineId> <nodeId> [--item <itemKey>] [--format <json|md>]",
+            args: [
+                { name: "pipelineId", required: true, description: "流水线 ID" },
+                { name: "nodeId", required: true, description: "节点 ID" },
+            ],
+            options: [{ flags: ["--item"], valueName: "itemKey", description: "指定重试的条目键" }],
+            summary: "重试指定节点或节点条目",
+        },
+    },
+    {
+        key: "pipeline.diagnose",
+        path: ["pipeline", "diagnose"],
+        description: "诊断指定节点依赖状态，输出阻塞原因",
+        handler: exports.pipelineDiagnoseCommand,
+        bootstrap: { runtimeApiOnly: true, ensureServerReady: true },
+        help: {
+            usage: "taskmeld pipeline diagnose <pipelineId> <nodeId> [--item <itemKey>] [--format <json|md>]",
+            args: [
+                { name: "pipelineId", required: true, description: "流水线 ID" },
+                { name: "nodeId", required: true, description: "节点 ID" },
+            ],
+            options: [{ flags: ["--item"], valueName: "itemKey", description: "可选，指定条目键精确诊断" }],
+            summary: "诊断指定节点依赖状态，输出阻塞原因",
+        },
+    },
+    {
+        key: "pipeline.output",
+        path: ["pipeline", "output"],
+        description: "查询流水线最终产物",
+        handler: async (input, ctx) => {
+            const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+            const runId = (0, selector_1.pickOptionalStringFlag)(input.flags.run);
+            const output = await ctx.app.pipelineService.getOutput(pipelineId, runId);
+            if (!output) {
+                return { ok: true, pipelineId, items: [] };
+            }
+            const outputs = runId ? [output] : await ctx.app.pipelineService.listOutputs(pipelineId);
+            return { ok: true, pipelineId, items: outputs };
+        },
+        help: {
+            usage: "taskmeld pipeline output <pipelineId> [--run <runId>]",
+            args: [{ name: "pipelineId", required: true, description: "流水线 ID" }],
+            options: [{ flags: ["--run"], valueName: "runId", description: "按 runId 精确查询" }],
+            summary: "查询流水线最终产物",
+        },
+    },
+    {
+        key: "pipeline.link-list",
+        path: ["pipeline", "link", "list"],
+        description: "列出所有流水线投递链接",
+        handler: async (_input, ctx) => {
+            const links = await ctx.app.pipelineService.listLinks();
+            return { ok: true, items: links };
+        },
+        help: {
+            usage: "taskmeld pipeline link list",
+            summary: "列出所有流水线投递链接",
+        },
+    },
+    {
+        key: "pipeline.queue",
+        path: ["pipeline", "queue"],
+        description: "查询流水线接收队列",
+        handler: async (input, ctx) => {
+            const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+            const items = ctx.app.pipelineService.getQueue(pipelineId);
+            return { ok: true, pipelineId, items };
+        },
+        help: {
+            usage: "taskmeld pipeline queue <pipelineId>",
+            args: [{ name: "pipelineId", required: true, description: "流水线 ID" }],
+            summary: "查询流水线接收队列",
+        },
+    },
+];

package/dist/src/cli/commands/scheduler.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulerRoutes = exports.schedulerModeCommand = exports.schedulerToggleCommand = void 0;
+const errors_1 = require("../errors");
+const assertSchedulerMode = (value) => {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "auto" || normalized === "manual") {
+            return normalized;
+        }
+    }
+    throw new errors_1.CliError("Invalid scheduler mode: --mode", {
+        code: "INVALID_ARGUMENT",
+        exitCode: 2,
+    });
+};
+const normalizeSchedulerResult = (result, pipelineId) => {
+    const data = result;
+    if (data.ok === true) {
+        return result;
+    }
+    if (data.error === "pipeline_not_found") {
+        throw new errors_1.CliError(`Pipeline not found: ${pipelineId}`, {
+            code: "PIPELINE_NOT_FOUND",
+            exitCode: 3,
+            details: { pipelineId },
+        });
+    }
+    if (data.error === "pipeline_plugin_disabled") {
+        throw new errors_1.CliError(`Scheduler plugin disabled: ${pipelineId}`, {
+            code: "PIPELINE_PLUGIN_DISABLED",
+            exitCode: 4,
+            details: { pipelineId, plugin: data.plugin ?? "scheduler" },
+        });
+    }
+    throw new errors_1.CliError("Scheduler command failed", {
+        code: "SCHEDULER_COMMAND_FAILED",
+        exitCode: 4,
+        details: { pipelineId, result },
+    });
+};
+const schedulerToggleCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const enabled = (0, errors_1.assertBooleanFlag)(input.flags.enabled, "enabled");
+    const result = await ctx.app.schedulerService.toggleScheduler(pipelineId, enabled);
+    return normalizeSchedulerResult(result, pipelineId);
+};
+exports.schedulerToggleCommand = schedulerToggleCommand;
+const schedulerModeCommand = async (input, ctx) => {
+    const pipelineId = (0, errors_1.assertRequiredArg)(input.args[0], "pipelineId");
+    const mode = assertSchedulerMode(input.flags.mode);
+    const result = await ctx.app.schedulerService.setSchedulerMode(pipelineId, mode);
+    return normalizeSchedulerResult(result, pipelineId);
+};
+exports.schedulerModeCommand = schedulerModeCommand;
+exports.schedulerRoutes = [
+    {
+        key: "scheduler.toggle",
+        path: ["scheduler", "toggle"],
+        description: "启用或停用调度器",
+        handler: exports.schedulerToggleCommand,
+        help: {
+            usage: "taskmeld scheduler toggle <pipelineId> --enabled <true|false> [--format <json|md>]",
+            args: [{ name: "pipelineId", required: true, description: "流水线 ID" }],
+            options: [{ flags: ["--enabled"], valueName: "true|false", required: true, description: "是否启用调度器" }],
+            notes: ["<pipelineId> 与 --enabled 均为必填控制项。"],
+        },
+    },
+    {
+        key: "scheduler.mode",
+        path: ["scheduler", "mode"],
+        description: "切换调度器模式",
+        handler: exports.schedulerModeCommand,
+        help: {
+            usage: "taskmeld scheduler mode <pipelineId> --mode <auto|manual> [--format <json|md>]",
+            args: [{ name: "pipelineId", required: true, description: "流水线 ID" }],
+            options: [{ flags: ["--mode"], valueName: "auto|manual", required: true, description: "调度器模式" }],
+            notes: ["<pipelineId> 与 --mode 均为必填控制项。"],
+        },
+    },
+];

package/dist/src/cli/commands/server.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverRoutes = exports.serverStopCommand = exports.serverStatusCommand = exports.serverStartCommand = exports.serverEnsureCommand = void 0;
+const serverEnsureCommand = async (_input, ctx) => {
+    return ctx.app.serverService.ensureServerReady();
+};
+exports.serverEnsureCommand = serverEnsureCommand;
+const serverStartCommand = async (_input, ctx) => {
+    return ctx.app.serverService.startServer();
+};
+exports.serverStartCommand = serverStartCommand;
+const serverStatusCommand = async (_input, ctx) => {
+    return ctx.app.serverService.getServerStatus();
+};
+exports.serverStatusCommand = serverStatusCommand;
+const serverStopCommand = async (_input, ctx) => {
+    return ctx.app.serverService.stopServer();
+};
+exports.serverStopCommand = serverStopCommand;
+exports.serverRoutes = [
+    {
+        key: "server.ensure",
+        path: ["server", "ensure"],
+        description: "确保本地控制面后端已启动并健康",
+        handler: exports.serverEnsureCommand,
+        bootstrap: { runtimeApiOnly: true },
+        help: {
+            usage: "taskmeld server ensure [--format <json|md>]",
+            summary: "确保本地 control-plane daemon 已启动并健康",
+            notes: [
+                "daemon-first 语义：优先复用已存在且健康的本地实例。",
+                "仅在没有可复用健康实例时，才会启动新的 daemon。",
+            ],
+        },
+    },
+    {
+        key: "server.start",
+        path: ["server", "start"],
+        description: "显式启动本地控制面后端",
+        handler: exports.serverStartCommand,
+        bootstrap: { runtimeApiOnly: true },
+        help: {
+            usage: "taskmeld server start [--format <json|md>]",
+            summary: "显式启动本地 control-plane daemon",
+        },
+    },
+    {
+        key: "server.status",
+        path: ["server", "status"],
+        description: "输出本地控制面后端状态",
+        handler: exports.serverStatusCommand,
+        bootstrap: { runtimeApiOnly: true },
+        help: {
+            usage: "taskmeld server status [--format <json|md>]",
+            summary: "查看本地 control-plane daemon 的健康、ownership 与 pid 信息",
+            notes: ["状态输出用于确认本地 daemon 是否可复用以及当前 owner 元数据是否一致。"],
+        },
+    },
+    {
+        key: "server.stop",
+        path: ["server", "stop"],
+        description: "停止本地控制面后端",
+        handler: exports.serverStopCommand,
+        bootstrap: { runtimeApiOnly: true },
+        help: {
+            usage: "taskmeld server stop [--format <json|md>]",
+            summary: "停止本地 control-plane daemon",
+        },
+    },
+];

package/dist/src/cli/commands/system.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemRoutes = exports.systemSnapshotCommand = void 0;
+const systemSnapshotCommand = async (_input, ctx) => {
+    // 系统快照由主线 service 层提供，CLI 只做编排与输出。
+    return ctx.app.systemService.getSnapshot();
+};
+exports.systemSnapshotCommand = systemSnapshotCommand;
+exports.systemRoutes = [
+    {
+        key: "system.snapshot",
+        path: ["system", "snapshot"],
+        description: "输出系统全局快照",
+        handler: exports.systemSnapshotCommand,
+        bootstrap: { gateway: "warmup" },
+        help: {
+            usage: "taskmeld system snapshot [--format <json|md>]",
+            summary: "输出系统全局快照",
+        },
+    },
+];