refactor(cli): split tjwater cli modules

2026-06-07 19:43:44 +08:00
parent ff87817fb5
commit 93d70da8be
23 changed files with 1720 additions and 740 deletions
@@ -0,0 +1,199 @@
+import { CliError } from "../core/errors.js";
+import { emitApi, requestJson } from "../core/http.js";
+import { assignDatasetKeys, parseBurstFile, parseValveSettingFile } from "../core/files.js";
+import { optionalNumber, optionalString, optionalStringArray, parseOptions, requiredNumber, requiredString, validateChoice } from "../core/options.js";
+import { requireNetwork, requireUsername, resolveScheme } from "../core/runtime.js";
+import { parseTime } from "../core/time.js";
+import { success } from "../core/output.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function analysisBurst(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  const [ids, sizes] = parseBurstFile(requiredString(values, "burst-file"));
+  const schemeName = resolveScheme(ctx, optionalString(values, "scheme"), true)!;
+  return emitApi(ctx, "爆管分析执行成功", {
+    method: "GET",
+    path: "/burst_analysis/",
+    params: {
+      network: requireNetwork(ctx),
+      modify_pattern_start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      burst_ID: ids,
+      burst_size: sizes,
+      modify_total_duration: requiredNumber(values, "duration"),
+      scheme_name: schemeName,
+    },
+    requireNetworkCtx: true,
+  }, [`tjwater-cli data scheme get --name ${schemeName}`, "tjwater-cli data scheme list"]);
+}
+
+function analysisValve(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { valve: "repeat", element: "repeat", "disabled-valve": "repeat", duration: "integer" });
+  const mode = validateChoice(requiredString(values, "mode"), ["close", "isolation"] as const, "--mode");
+  if (mode === "close") {
+    const valves = optionalStringArray(values, "valve");
+    const startTime = optionalString(values, "start-time");
+    if (!startTime || !valves) throw new CliError("CLI 参数错误", "INVALID_VALVE_CLOSE_ARGS", "close mode requires --start-time and at least one --valve", 2);
+    return emitApi(ctx, "阀门关闭分析执行成功", {
+      method: "GET",
+      path: "/valve_close_analysis/",
+      params: {
+        network: requireNetwork(ctx),
+        start_time: parseTime(startTime, "--start-time"),
+        valves,
+        duration: optionalNumber(values, "duration") || 900,
+        scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      },
+      requireNetworkCtx: true,
+    });
+  }
+  const elements = optionalStringArray(values, "element");
+  if (!elements) throw new CliError("CLI 参数错误", "INVALID_VALVE_ISOLATION_ARGS", "isolation mode requires at least one --element", 2);
+  return emitApi(ctx, "阀门隔离分析执行成功", {
+    method: "GET",
+    path: "/valve_isolation_analysis/",
+    params: { network: requireNetwork(ctx), accident_element: elements, disabled_valves: optionalStringArray(values, "disabled-valve") },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisFlushing(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { flow: "number", duration: "integer" });
+  const [valves, openings] = parseValveSettingFile(requiredString(values, "valve-setting-file"));
+  return emitApi(ctx, "冲洗分析执行成功", {
+    method: "GET",
+    path: "/flushing_analysis/",
+    params: {
+      network: requireNetwork(ctx),
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      valves,
+      valves_k: openings,
+      drainage_node_ID: requiredString(values, "drainage-node"),
+      flush_flow: requiredNumber(values, "flow"),
+      duration: optionalNumber(values, "duration") || 900,
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisAge(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  return emitApi(ctx, "水龄分析执行成功", {
+    method: "GET",
+    path: "/age_analysis/",
+    params: { network: requireNetwork(ctx), start_time: parseTime(requiredString(values, "start-time"), "--start-time"), duration: requiredNumber(values, "duration") },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisContaminant(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer", concentration: "number" });
+  const params: Record<string, unknown> = {
+    network: requireNetwork(ctx),
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    source: requiredString(values, "source-node"),
+    concentration: requiredNumber(values, "concentration"),
+    duration: requiredNumber(values, "duration"),
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+  };
+  const pattern = optionalString(values, "pattern");
+  if (pattern) params.pattern = pattern;
+  return emitApi(ctx, "污染物模拟执行成功", { method: "GET", path: "/contaminant_simulation/", params, requireNetworkCtx: true });
+}
+
+function sensorKmeans(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { count: "integer", "min-diameter": "integer" });
+  return emitApi(ctx, "传感器选址执行成功", {
+    method: "POST",
+    path: "/pressure_sensor_placement_kmeans/",
+    body: {
+      name: requireNetwork(ctx),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      sensor_number: requiredNumber(values, "count"),
+      min_diameter: optionalNumber(values, "min-diameter") || 0,
+      username: requireUsername(ctx),
+    },
+    requireNetworkCtx: true,
+    requireUsernameCtx: true,
+  });
+}
+
+function schemeAnalysis(ctx: RuntimeContext, argv: string[], summary: string, path: string, networkKey: string, startKey: string, endKey: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, {
+    method: "POST",
+    path,
+    body: {
+      [networkKey]: requireNetwork(ctx),
+      [startKey]: parseTime(requiredString(values, "start-time"), "--start-time"),
+      [endKey]: parseTime(requiredString(values, "end-time"), "--end-time"),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    },
+    requireNetworkCtx: true,
+  });
+}
+
+function schemeList(ctx: RuntimeContext, summary: string, path: string): Promise<void> {
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function schemeGet(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { positionals } = parseOptions(argv);
+  if (!positionals[0]) throw new CliError("CLI 参数错误", "MISSING_ARGUMENT", "Missing argument 'SCHEME_NAME'", 2);
+  return emitApi(ctx, summary, { method: "GET", path: `${path}${positionals[0]}`, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function burstLocation(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { "burst-leakage": "number", "pressure-scada-id": "repeat", "flow-scada-id": "repeat", "use-scada-flow": "boolean" });
+  const body: Record<string, unknown> = {
+    network: requireNetwork(ctx),
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    data_source: optionalString(values, "data-source") || "monitoring",
+    scada_burst_start: parseTime(requiredString(values, "start-time"), "--start-time"),
+    scada_burst_end: parseTime(requiredString(values, "end-time"), "--end-time"),
+    burst_leakage: requiredNumber(values, "burst-leakage"),
+    use_scada_flow: Boolean(values["use-scada-flow"]),
+  };
+  const pressureIds = optionalStringArray(values, "pressure-scada-id");
+  const flowIds = optionalStringArray(values, "flow-scada-id");
+  if (pressureIds) body.pressure_scada_ids = pressureIds;
+  if (flowIds) body.flow_scada_ids = flowIds;
+  const pressureFile = optionalString(values, "pressure-file");
+  const flowFile = optionalString(values, "flow-file");
+  if (pressureFile) assignDatasetKeys(body, pressureFile, ["burst_pressure", "normal_pressure"], "pressure");
+  if (flowFile) assignDatasetKeys(body, flowFile, ["burst_flow", "normal_flow"], "flow");
+  return emitApi(ctx, "爆管定位执行成功", { method: "POST", path: "/burst-location/locate/", body, requireNetworkCtx: true });
+}
+
+function riskPipe(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx), pipe_id: requiredString(values, "pipe") }, requireNetworkCtx: true });
+}
+
+async function riskNetwork(ctx: RuntimeContext): Promise<void> {
+  const network = requireNetwork(ctx);
+  const [probabilities, a] = await requestJson(ctx, { method: "GET", path: "/getnetworkpiperiskprobabilitynow/", params: { network }, requireNetworkCtx: true });
+  const [geometries, b] = await requestJson(ctx, { method: "GET", path: "/getpiperiskprobabilitygeometries/", params: { network }, requireNetworkCtx: true });
+  success("读取全网风险成功", { probabilities, geometries }, ctx, a + b);
+}
+
+export const analysisHandlers: HandlerMap = {
+  "analysis burst": analysisBurst,
+  "analysis valve": analysisValve,
+  "analysis flushing": analysisFlushing,
+  "analysis age": analysisAge,
+  "analysis contaminant": analysisContaminant,
+  "analysis sensor-placement kmeans": sensorKmeans,
+  "analysis leakage identify": (ctx, argv) => schemeAnalysis(ctx, argv, "漏损识别执行成功", "/leakage/identify/", "network", "scada_start", "scada_end"),
+  "analysis leakage schemes list": (ctx) => schemeList(ctx, "读取漏损方案列表成功", "/leakage/schemes/"),
+  "analysis leakage schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取漏损方案详情成功", "/leakage/schemes/"),
+  "analysis burst-detection detect": (ctx, argv) => schemeAnalysis(ctx, argv, "爆管检测执行成功", "/burst-detection/detect/", "network", "scada_start", "scada_end"),
+  "analysis burst-detection schemes list": (ctx) => schemeList(ctx, "读取爆管检测方案列表成功", "/burst-detection/schemes/"),
+  "analysis burst-detection schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取爆管检测方案详情成功", "/burst-detection/schemes/"),
+  "analysis burst-location locate": burstLocation,
+  "analysis burst-location schemes list": (ctx) => schemeList(ctx, "读取爆管定位方案列表成功", "/burst-location/schemes/"),
+  "analysis burst-location schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取爆管定位方案详情成功", "/burst-location/schemes/"),
+  "analysis risk pipe-now": (ctx, argv) => riskPipe(ctx, argv, "读取当前管道风险成功", "/getpiperiskprobabilitynow/"),
+  "analysis risk pipe-history": (ctx, argv) => riskPipe(ctx, argv, "读取历史管道风险成功", "/getpiperiskprobability/"),
+  "analysis risk network": riskNetwork,
+};
@@ -0,0 +1,34 @@
+import { CliError } from "../core/errors.js";
+import { emitApi } from "../core/http.js";
+import { optionalString, parseOptions, requiredString, validateChoice } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+type ComponentKind = "time" | "energy" | "pump-energy" | "network";
+
+function componentOption(ctx: RuntimeContext, argv: string[], schema: boolean): Promise<void> {
+  const { values } = parseOptions(argv);
+  const kind = validateChoice(requiredString(values, "kind"), ["time", "energy", "pump-energy", "network"] as const, "--kind");
+  const routes: Record<`${ComponentKind}:${boolean}`, string> = {
+    "time:true": "/gettimeschema",
+    "time:false": "/gettimeproperties/",
+    "energy:true": "/getenergyschema/",
+    "energy:false": "/getenergyproperties/",
+    "pump-energy:true": "/getpumpenergyschema/",
+    "pump-energy:false": "/getpumpenergyproperties//",
+    "network:true": "/getoptionschema/",
+    "network:false": "/getoptionproperties/",
+  };
+  const params: Record<string, unknown> = { network: requireNetwork(ctx) };
+  const pump = optionalString(values, "pump");
+  if (kind === "pump-energy") {
+    if (!schema && !pump) throw new CliError("CLI 参数错误", "PUMP_REQUIRED", "--pump is required when --kind pump-energy", 2);
+    if (pump) params.pump = pump;
+  }
+  return emitApi(ctx, schema ? "读取选项 schema 成功" : "读取选项属性成功", { method: "GET", path: routes[`${kind}:${schema}`], params, requireNetworkCtx: true });
+}
+
+export const componentHandlers: HandlerMap = {
+  "component option schema": (ctx, argv) => componentOption(ctx, argv, true),
+  "component option get": (ctx, argv) => componentOption(ctx, argv, false),
+};
@@ -0,0 +1,167 @@
+import { SCADA_FIELDS, type ElementType } from "../core/constants.js";
+import { CliError } from "../core/errors.js";
+import { emitApi } from "../core/http.js";
+import { fieldsFor, optionalString, parseOptions, requiredString, requiredStringArray, validateChoice } from "../core/options.js";
+import { requireNetwork, resolveScheme } from "../core/runtime.js";
+import { parseTime } from "../core/time.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function rangeGet(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, {
+    method: "GET",
+    path,
+    params: { start_time: parseTime(requiredString(values, "start-time"), "--start-time"), end_time: parseTime(requiredString(values, "end-time"), "--end-time") },
+    requireProject: true,
+  });
+}
+
+function realtimeByIdTime(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取实时模拟数据成功", {
+    method: "GET",
+    path: "/realtime/query/by-id-time",
+    params: { id: requiredString(values, "id"), type: validateChoice(requiredString(values, "type"), ["pipe", "junction"] as const, "--type"), query_time: parseTime(requiredString(values, "time"), "--time") },
+    requireProject: true,
+  });
+}
+
+function realtimeByTimeProperty(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  const type = validateChoice(requiredString(values, "type"), ["pipe", "junction"] as const, "--type");
+  return emitApi(ctx, "读取实时属性聚合数据成功", {
+    method: "GET",
+    path: "/realtime/query/by-time-property",
+    params: { type, query_time: parseTime(requiredString(values, "time"), "--time"), property: validateChoice(requiredString(values, "property"), fieldsFor(type), "--property") },
+    requireProject: true,
+  });
+}
+
+function schemeLinks(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案管道数据成功", {
+    method: "GET",
+    path: "/scheme/links",
+    params: {
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      scheme_type: optionalString(values, "scheme-type") || "simulation",
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+    },
+    requireProject: true,
+  });
+}
+
+function schemeNodeField(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案节点字段成功", {
+    method: "GET",
+    path: `/scheme/nodes/${requiredString(values, "node")}/field`,
+    params: {
+      field: validateChoice(requiredString(values, "field"), fieldsFor("junction"), "--field"),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      scheme_type: optionalString(values, "scheme-type") || "simulation",
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+    },
+    requireProject: true,
+  });
+}
+
+function schemeSimulation(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  const query = validateChoice(requiredString(values, "query"), ["by-id-time", "by-scheme-time-property"] as const, "--query");
+  const type = validateChoice(optionalString(values, "type") || "pipe", ["pipe", "junction"] as const, "--type") as ElementType;
+  const params: Record<string, unknown> = {
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    scheme_type: optionalString(values, "scheme-type") || "simulation",
+    query_time: parseTime(requiredString(values, "time"), "--time"),
+    type,
+  };
+  if (query === "by-id-time") {
+    params.id = requiredString(values, "id");
+    return emitApi(ctx, "读取方案单点模拟数据成功", { method: "GET", path: "/scheme/query/by-id-time", params, requireProject: true });
+  }
+  params.property = validateChoice(requiredString(values, "property"), fieldsFor(type), "--property");
+  return emitApi(ctx, "读取方案属性聚合数据成功", { method: "GET", path: "/scheme/query/by-scheme-time-property", params, requireProject: true });
+}
+
+function scadaQuery(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { "device-id": "repeat" });
+  const params: Record<string, unknown> = {
+    device_ids: requiredStringArray(values, "device-id").join(","),
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+  };
+  const field = optionalString(values, "field");
+  if (field) params.field = validateChoice(field, SCADA_FIELDS, "--field");
+  return emitApi(ctx, "读取 SCADA 时序成功", { method: "GET", path: field ? "/scada/by-ids-field-time-range" : "/scada/by-ids-time-range", params, requireProject: true });
+}
+
+function composite(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { feature: "repeat", "use-cleaned": "boolean" });
+  const kind = validateChoice(requiredString(values, "kind"), ["scada-simulation", "element-simulation", "element-scada"] as const, "--kind");
+  const params: Record<string, unknown> = {
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+  };
+  const schemeName = resolveScheme(ctx, optionalString(values, "scheme"));
+  if (schemeName) Object.assign(params, { scheme_name: schemeName, scheme_type: optionalString(values, "scheme-type") || "simulation" });
+  if (kind === "scada-simulation") params.device_ids = requiredStringArray(values, "feature").join(",");
+  else if (kind === "element-simulation") params.feature_infos = requiredStringArray(values, "feature").join(",");
+  else {
+    const feature = requiredStringArray(values, "feature");
+    if (feature.length !== 1) throw new CliError("CLI 参数错误", "FEATURE_REQUIRED", "element-scada requires exactly one --feature as element_id", 2);
+    params.element_id = feature[0];
+    params.use_cleaned = Boolean(values["use-cleaned"]);
+  }
+  return emitApi(ctx, kind === "scada-simulation" ? "读取复合 SCADA-模拟数据成功" : kind === "element-simulation" ? "读取复合元素模拟数据成功" : "读取元素关联 SCADA 数据成功", { method: "GET", path: `/composite/${kind}`, params, requireProject: true });
+}
+
+function pipelineHealth(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  requiredString(values, "pipe");
+  requiredString(values, "start-time");
+  return emitApi(ctx, "读取管道健康预测成功", {
+    method: "GET",
+    path: "/composite/pipeline-health-prediction",
+    params: { network_name: requireNetwork(ctx), query_time: parseTime(requiredString(values, "end-time"), "--end-time") },
+    requireProject: true,
+    requireNetworkCtx: true,
+  });
+}
+
+function dataScadaGet(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  validateChoice(requiredString(values, "kind"), ["info"] as const, "--kind");
+  return emitApi(ctx, "读取 SCADA 数据成功", { method: "GET", path: "/getscadainfo/", params: { network: requireNetwork(ctx), id: requiredString(values, "id") }, requireNetworkCtx: true });
+}
+
+function dataScadaList(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  validateChoice(requiredString(values, "kind"), ["info"] as const, "--kind");
+  return emitApi(ctx, "读取 SCADA 列表成功", { method: "GET", path: "/getallscadainfo/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function dataSchemeGet(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案成功", { method: "GET", path: "/getscheme/", params: { network: requireNetwork(ctx), schema_name: requiredString(values, "name") }, requireNetworkCtx: true });
+}
+
+export const dataHandlers: HandlerMap = {
+  "data timeseries realtime links": (ctx, argv) => rangeGet(ctx, argv, "读取实时管道数据成功", "/realtime/links"),
+  "data timeseries realtime nodes": (ctx, argv) => rangeGet(ctx, argv, "读取实时节点数据成功", "/realtime/nodes"),
+  "data timeseries realtime simulation-by-id-time": realtimeByIdTime,
+  "data timeseries realtime simulation-by-time-property": realtimeByTimeProperty,
+  "data timeseries scheme links": schemeLinks,
+  "data timeseries scheme node-field": schemeNodeField,
+  "data timeseries scheme simulation": schemeSimulation,
+  "data timeseries scada query": scadaQuery,
+  "data timeseries composite": composite,
+  "data timeseries composite pipeline-health": pipelineHealth,
+  "data scada get": dataScadaGet,
+  "data scada list": dataScadaList,
+  "data scheme schema": (ctx) => emitApi(ctx, "读取方案 schema 成功", { method: "GET", path: "/getschemeschema/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true }),
+  "data scheme get": dataSchemeGet,
+  "data scheme list": (ctx) => emitApi(ctx, "读取方案列表成功", { method: "GET", path: "/getallschemes/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true }),
+};
@@ -0,0 +1,27 @@
+import { emitApi } from "../core/http.js";
+import { parseOptions, requiredString } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function legacyGet(ctx: RuntimeContext, argv: string[], summary: string, path: string, key: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx), [key]: requiredString(values, key) }, requireNetworkCtx: true });
+}
+
+function legacyGetAll(ctx: RuntimeContext, summary: string, path: string): Promise<void> {
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+export const networkHandlers: HandlerMap = {
+  "network get-junction-properties": (ctx, argv) => legacyGet(ctx, argv, "读取节点属性成功", "/getjunctionproperties/", "junction"),
+  "network get-pipe-properties": (ctx, argv) => legacyGet(ctx, argv, "读取管道属性成功", "/getpipeproperties/", "pipe"),
+  "network get-all-pipes-properties": (ctx) => legacyGetAll(ctx, "读取全部管道属性成功", "/getallpipeproperties/"),
+  "network get-reservoir-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水库属性成功", "/getreservoirproperties/", "reservoir"),
+  "network get-all-reservoirs-properties": (ctx) => legacyGetAll(ctx, "读取全部水库属性成功", "/getallreservoirproperties/"),
+  "network get-tank-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水箱属性成功", "/gettankproperties/", "tank"),
+  "network get-all-tanks-properties": (ctx) => legacyGetAll(ctx, "读取全部水箱属性成功", "/getalltankproperties/"),
+  "network get-pump-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水泵属性成功", "/getpumpproperties/", "pump"),
+  "network get-all-pumps-properties": (ctx) => legacyGetAll(ctx, "读取全部水泵属性成功", "/getallpumpproperties/"),
+  "network get-valve-properties": (ctx, argv) => legacyGet(ctx, argv, "读取阀门属性成功", "/getvalveproperties/", "valve"),
+  "network get-all-valves-properties": (ctx) => legacyGetAll(ctx, "读取全部阀门属性成功", "/getallvalveproperties/"),
+};
@@ -0,0 +1,26 @@
+import { emitApi } from "../core/http.js";
+import { parseOptions, requiredNumber, requiredString } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import { addMinutesPreservingOffset, parseTime } from "../core/time.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function simulationRun(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  const start = parseTime(requiredString(values, "start-time"), "--start-time");
+  const duration = requiredNumber(values, "duration");
+  const end = addMinutesPreservingOffset(start, duration);
+  const network = requireNetwork(ctx);
+  return emitApi(
+    ctx,
+    "触发模拟成功",
+    { method: "POST", path: "/runsimulationmanuallybydate/", body: { name: network, start_time: start.replace(/\.\d+/, ""), duration }, requireNetworkCtx: true },
+    [
+      `tjwater-cli data timeseries realtime links --start-time ${start} --end-time ${end}`,
+      `tjwater-cli data timeseries realtime nodes --start-time ${start} --end-time ${end}`,
+    ],
+  );
+}
+
+export const simulationHandlers: HandlerMap = {
+  "simulation run": simulationRun,
+};
@@ -0,0 +1,13 @@
+export const SCHEMA_VERSION = "tjwater-cli/v1";
+export const DEFAULT_TIMEOUT = 180;
+export const DEFAULT_SERVER = "http://192.168.1.114:8000";
+
+export const PIPE_FIELDS = ["flow", "friction", "headloss", "quality", "reaction", "setting", "status", "velocity"] as const;
+export const JUNCTION_FIELDS = ["actual_demand", "total_head", "pressure", "quality"] as const;
+export const SCADA_FIELDS = ["monitored_value", "cleaned_value"] as const;
+
+export type ElementType = "pipe" | "junction";
+export type PipeField = (typeof PIPE_FIELDS)[number];
+export type JunctionField = (typeof JUNCTION_FIELDS)[number];
+export type ScadaField = (typeof SCADA_FIELDS)[number];
+
@@ -0,0 +1,31 @@
+export class CliError extends Error {
+  summary: string;
+  code: string;
+  exitCode: number;
+  retryable: boolean;
+  data: unknown;
+  nextCommands: string[];
+
+  constructor(
+    summary: string,
+    code: string,
+    message: string,
+    exitCode = 2,
+    retryable = false,
+    data: unknown = null,
+    nextCommands: string[] = [],
+  ) {
+    super(message);
+    this.summary = summary;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.retryable = retryable;
+    this.data = data;
+    this.nextCommands = nextCommands;
+  }
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "./errors.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function readJsonFile(path: string, label: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      throw new CliError("CLI 参数错误", "INPUT_NOT_FOUND", `${label} file not found: ${path}`, 2);
+    }
+    if (error instanceof SyntaxError) throw new CliError("CLI 参数错误", "INPUT_INVALID_JSON", `${label} file must be valid JSON: ${path}`, 2);
+    throw error;
+  }
+}
+
+export function parseBurstFile(path: string): [string[], number[]] {
+  let raw = readJsonFile(path, "burst");
+  if (isRecord(raw) && "bursts" in raw) raw = raw.bursts;
+  if (isRecord(raw) && "burst_ID" in raw && "burst_size" in raw && Array.isArray(raw.burst_ID) && Array.isArray(raw.burst_size)) {
+    const ids = raw.burst_ID.map(String);
+    const sizes = raw.burst_size.map(Number);
+    if (ids.length !== sizes.length) throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file burst_ID and burst_size must have the same length", 2);
+    return [ids, sizes];
+  }
+  if (Array.isArray(raw)) {
+    return [
+      raw.map((item) => {
+        if (!isRecord(item) || !("id" in item) || !("size" in item)) throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file items must contain id and size", 2);
+        return String(item.id);
+      }),
+      raw.map((item) => Number((item as Record<string, unknown>).size)),
+    ];
+  }
+  throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file must be a JSON array or object with burst_ID/burst_size", 2);
+}
+
+export function parseValveSettingFile(path: string): [string[], number[]] {
+  const raw = readJsonFile(path, "valve-setting");
+  if (isRecord(raw) && "valves" in raw && "valves_k" in raw && Array.isArray(raw.valves) && Array.isArray(raw.valves_k)) {
+    const valves = raw.valves.map(String);
+    const openings = raw.valves_k.map(Number);
+    if (valves.length !== openings.length) throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valves and valves_k must have the same length", 2);
+    return [valves, openings];
+  }
+  if (Array.isArray(raw)) {
+    return [
+      raw.map((item) => {
+        if (!isRecord(item) || !("valve" in item) || !("opening" in item)) throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valve-setting items must contain valve and opening", 2);
+        return String(item.valve);
+      }),
+      raw.map((item) => Number((item as Record<string, unknown>).opening)),
+    ];
+  }
+  throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valve-setting file must be a JSON array or object with valves/valves_k", 2);
+}
+
+export function assignDatasetKeys(target: Record<string, unknown>, path: string, keys: string[], label: string): void {
+  const payload = readJsonFile(path, label);
+  if (isRecord(payload)) {
+    for (const key of keys) {
+      if (key in payload) target[key] = payload[key];
+    }
+  }
+}
+
@@ -0,0 +1,96 @@
+import { CliError, errorMessage } from "./errors.js";
+import { requireNetwork, requireUsername } from "./runtime.js";
+import { success } from "./output.js";
+import type { RequestOptions, RuntimeContext } from "./types.js";
+
+function headers(ctx: RuntimeContext, requireAuth: boolean, requireProject: boolean): Record<string, string> {
+  const out: Record<string, string> = {
+    Accept: "application/json, text/plain, */*",
+    "X-Request-Id": ctx.requestId,
+    ...ctx.auth.headers,
+  };
+  if (requireAuth) {
+    if (!ctx.auth.accessToken) {
+      throw new CliError("认证失败", "UNAUTHENTICATED", "missing access token for agent context", 3, false, null, ["provide access_token via --auth-stdin or TJWATER_ACCESS_TOKEN env var"]);
+    }
+    out.Authorization = `Bearer ${ctx.auth.accessToken}`;
+  } else if (ctx.auth.accessToken) out.Authorization = `Bearer ${ctx.auth.accessToken}`;
+  if (requireProject) {
+    if (!ctx.auth.projectId) throw new CliError("认证失败", "PROJECT_CONTEXT_REQUIRED", "missing project_id for agent context", 3, false, null, ["add project_id to auth context"]);
+    out["X-Project-Id"] = ctx.auth.projectId;
+  } else if (ctx.auth.projectId) out["X-Project-Id"] = ctx.auth.projectId;
+  if (ctx.auth.userId) out["X-User-Id"] = ctx.auth.userId;
+  return out;
+}
+
+function stringifyParam(value: unknown): string {
+  if (typeof value === "boolean") return value ? "True" : "False";
+  return String(value);
+}
+
+function appendParams(url: URL, params: Record<string, unknown> = {}): void {
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) value.forEach((item) => url.searchParams.append(key, stringifyParam(item)));
+    else url.searchParams.set(key, stringifyParam(value));
+  }
+}
+
+export async function requestJson(ctx: RuntimeContext, request: RequestOptions): Promise<[unknown, number]> {
+  const { method, path, params, body, requireAuth = true, requireProject = false, requireNetworkCtx = false, requireUsernameCtx = false } = request;
+  if (requireNetworkCtx) requireNetwork(ctx);
+  if (requireUsernameCtx) requireUsername(ctx);
+  const url = new URL(`/api/v1${path}`, ctx.server.replace(/\/+$/, ""));
+  appendParams(url, params);
+  const started = performance.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ctx.timeout * 1000);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: method.toUpperCase(),
+      headers: {
+        ...headers(ctx, requireAuth, requireProject),
+        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") throw new CliError("请求超时", "REQUEST_TIMEOUT", `request timed out after ${ctx.timeout} seconds`, 7, true);
+    throw new CliError("连接失败", "REQUEST_FAILED", errorMessage(error), 7, true);
+  } finally {
+    clearTimeout(timer);
+  }
+  const durationMs = Math.trunc(performance.now() - started);
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  const text = response.status === 204 ? "" : await response.text();
+  let payload: unknown = {};
+  if (contentType.includes("application/json") && text) payload = JSON.parse(text);
+  else if (text) payload = { report: text };
+  if (!response.ok) {
+    const record = payload && typeof payload === "object" && !Array.isArray(payload) ? (payload as Record<string, unknown>) : {};
+    const message = typeof record.detail === "string" ? record.detail : typeof record.message === "string" ? record.message : text || `http ${response.status}`;
+    throw new CliError("请求失败", `HTTP_${response.status}`, message, mapStatus(response.status), response.status >= 500);
+  }
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    const record = payload as Record<string, unknown>;
+    if (record.status === "error") throw new CliError("服务端错误", "SERVER_ERROR", String(record.message || "server returned error status"), 7, false, payload);
+  }
+  return [payload, durationMs];
+}
+
+function mapStatus(status: number): number {
+  if (status === 400 || status === 422) return 2;
+  if (status === 401) return 3;
+  if (status === 403) return 4;
+  if (status === 404) return 5;
+  if (status === 409 || status === 412) return 6;
+  return 7;
+}
+
+export async function emitApi(ctx: RuntimeContext, summary: string, request: RequestOptions, nextCommands: string[] = []): Promise<void> {
+  const [data, durationMs] = await requestJson(ctx, request);
+  success(summary, data, ctx, durationMs, nextCommands);
+}
+
@@ -0,0 +1,112 @@
+import { JUNCTION_FIELDS, PIPE_FIELDS, type ElementType } from "./constants.js";
+import { CliError } from "./errors.js";
+import type { OptionSchema, ParsedOptionValue, ParsedOptions } from "./types.js";
+
+export function requireValue(argv: string[], index: number, option: string): string {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) throw new CliError("CLI 参数错误", "MISSING_OPTION_VALUE", `${option} requires a value`, 2);
+  return value;
+}
+
+export function parseIntStrict(value: string, option: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) throw new CliError("CLI 参数错误", "INVALID_INTEGER", `${option} must be an integer`, 2);
+  return parsed;
+}
+
+export function parseFloatStrict(value: string, option: string): number {
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed)) throw new CliError("CLI 参数错误", "INVALID_NUMBER", `${option} must be a number`, 2);
+  return parsed;
+}
+
+export function parseOptions(argv: string[], schema: OptionSchema = {}): ParsedOptions {
+  const values: Record<string, ParsedOptionValue> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    const kind = schema[name] ?? "string";
+    if (kind === "boolean") {
+      values[name] = true;
+    } else {
+      const raw = requireValue(argv, ++i, arg);
+      if (kind === "repeat") values[name] = [...asStringArray(values[name]), raw];
+      else if (kind === "number") values[name] = parseFloatStrict(raw, arg);
+      else if (kind === "integer") values[name] = parseIntStrict(raw, arg);
+      else values[name] = raw;
+    }
+  }
+  return { values, positionals };
+}
+
+export function required(values: Record<string, ParsedOptionValue>, name: string): string | number | boolean | string[] {
+  const value = values[name];
+  if (value === undefined || value === null || value === "") {
+    throw new CliError("CLI 参数错误", "MISSING_PARAMETER", `Missing option '--${name}'`, 2);
+  }
+  return value;
+}
+
+export function requiredString(values: Record<string, ParsedOptionValue>, name: string): string {
+  const value = required(values, name);
+  if (typeof value !== "string") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a string`, 2);
+  return value;
+}
+
+export function requiredNumber(values: Record<string, ParsedOptionValue>, name: string): number {
+  const value = required(values, name);
+  if (typeof value !== "number") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a number`, 2);
+  return value;
+}
+
+export function requiredStringArray(values: Record<string, ParsedOptionValue>, name: string): string[] {
+  const value = required(values, name);
+  if (!Array.isArray(value)) throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be repeatable`, 2);
+  return value;
+}
+
+export function optionalString(values: Record<string, ParsedOptionValue>, name: string): string | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a string`, 2);
+  return value;
+}
+
+export function optionalNumber(values: Record<string, ParsedOptionValue>, name: string): number | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "number") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a number`, 2);
+  return value;
+}
+
+export function optionalStringArray(values: Record<string, ParsedOptionValue>, name: string): string[] | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be repeatable`, 2);
+  return value;
+}
+
+export function asStringArray(value: ParsedOptionValue | undefined): string[] {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) return value;
+  throw new CliError("CLI 参数错误", "INVALID_PARAMETER", "repeat option received a non-array value", 2);
+}
+
+export function validateChoice<T extends readonly string[]>(value: string, valid: T, option: string): T[number] {
+  if (!valid.includes(value)) {
+    throw new CliError("CLI 参数错误", `INVALID_${option.replace(/^--/, "").replaceAll("-", "_").toUpperCase()}`, `${option} must be one of: ${valid.join(", ")}`, 2);
+  }
+  return value as T[number];
+}
+
+export function fieldsFor(type: ElementType): typeof PIPE_FIELDS | typeof JUNCTION_FIELDS {
+  if (type === "pipe") return PIPE_FIELDS;
+  if (type === "junction") return JUNCTION_FIELDS;
+  throw new CliError("CLI 参数错误", "INVALID_TYPE", "--type must be one of: pipe, junction", 2);
+}
+
@@ -0,0 +1,61 @@
+import { SCHEMA_VERSION } from "./constants.js";
+import type { RuntimeContext } from "./types.js";
+
+export function json(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+export function generatedAt(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export function success(summary: string, data: unknown, ctx: RuntimeContext, durationMs: number, nextCommands: string[] = []): void {
+  json({
+    ok: true,
+    schema_version: SCHEMA_VERSION,
+    summary,
+    data,
+    metadata: {
+      request_id: ctx.requestId,
+      server: ctx.server,
+      duration_ms: durationMs,
+      generated_at: generatedAt(),
+    },
+    next_commands: nextCommands,
+  });
+}
+
+export function failure({
+  summary,
+  code,
+  message,
+  retryable = false,
+  server = null,
+  requestId = null,
+  data = null,
+  nextCommands = [],
+}: {
+  summary: string;
+  code: string;
+  message: string;
+  retryable?: boolean;
+  server?: string | null;
+  requestId?: string | null;
+  data?: unknown;
+  nextCommands?: string[];
+}): void {
+  json({
+    ok: false,
+    schema_version: SCHEMA_VERSION,
+    summary,
+    error: { code, message, retryable },
+    data,
+    metadata: {
+      request_id: requestId,
+      server,
+      generated_at: generatedAt(),
+    },
+    next_commands: nextCommands,
+  });
+}
+
@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_SERVER, DEFAULT_TIMEOUT } from "./constants.js";
+import { CliError } from "./errors.js";
+import { requireValue, parseIntStrict } from "./options.js";
+import type { AuthContext, GlobalArgs, ParsedGlobalArgs, RuntimeContext } from "./types.js";
+
+function pick(source: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = source[key];
+    if (value !== undefined && value !== null && value !== "") return String(value);
+  }
+  return null;
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk: string) => {
+      body += chunk;
+    });
+    process.stdin.on("end", () => resolve(body));
+    process.stdin.on("error", reject);
+  });
+}
+
+export async function loadAuthContext(authStdin: boolean): Promise<AuthContext> {
+  const raw = authStdin
+    ? (JSON.parse(await readStdin()) as Record<string, unknown>)
+    : {
+        server: process.env.TJWATER_SERVER,
+        access_token: process.env.TJWATER_ACCESS_TOKEN,
+        project_id: process.env.TJWATER_PROJECT_ID,
+        user_id: process.env.TJWATER_USER_ID,
+        username: process.env.TJWATER_USERNAME,
+        network: process.env.TJWATER_NETWORK,
+        headers: process.env.TJWATER_EXTRA_HEADERS ? JSON.parse(process.env.TJWATER_EXTRA_HEADERS) : {},
+      };
+  const headers = (raw.headers ?? {}) as unknown;
+  if (!headers || Array.isArray(headers) || typeof headers !== "object") {
+    throw new CliError("认证失败", "AUTH_CONTEXT_INVALID", "auth context headers must be a JSON object", 3);
+  }
+  return {
+    server: pick(raw, "server", "base_url"),
+    accessToken: pick(raw, "access_token", "token", "accessToken"),
+    projectId: pick(raw, "project_id", "projectId", "x_project_id"),
+    userId: pick(raw, "user_id", "userId", "x_user_id"),
+    username: pick(raw, "username", "preferred_username"),
+    network: pick(raw, "network", "project_code", "projectCode", "project"),
+    headers: Object.fromEntries(Object.entries(headers as Record<string, unknown>).map(([key, value]) => [String(key), String(value)])),
+  };
+}
+
+export function parseGlobalArgs(argv: string[]): ParsedGlobalArgs {
+  const globals: GlobalArgs = {
+    server: null,
+    authStdin: false,
+    scheme: null,
+    timeout: DEFAULT_TIMEOUT,
+    requestId: null,
+  };
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    if (arg === "--auth-stdin") globals.authStdin = true;
+    else if (arg === "--server") globals.server = requireValue(argv, ++i, "--server");
+    else if (arg === "--scheme") globals.scheme = requireValue(argv, ++i, "--scheme");
+    else if (arg === "--timeout") globals.timeout = parseIntStrict(requireValue(argv, ++i, "--timeout"), "--timeout");
+    else if (arg === "--request-id") globals.requestId = requireValue(argv, ++i, "--request-id");
+    else rest.push(arg);
+  }
+  return { globals, rest };
+}
+
+export async function buildRuntime(globals: GlobalArgs): Promise<RuntimeContext> {
+  const auth = await loadAuthContext(globals.authStdin);
+  return {
+    server: globals.server || auth.server || DEFAULT_SERVER,
+    auth,
+    scheme: globals.scheme,
+    timeout: globals.timeout,
+    requestId: globals.requestId || randomUUID(),
+  };
+}
+
+export function requireNetwork(ctx: RuntimeContext): string {
+  if (ctx.auth.network) return ctx.auth.network;
+  throw new CliError("认证失败", "NETWORK_CONTEXT_REQUIRED", "missing network in auth context for legacy network-based endpoints", 3, false, null, ["add network to auth context"]);
+}
+
+export function requireUsername(ctx: RuntimeContext): string {
+  if (ctx.auth.username) return ctx.auth.username;
+  throw new CliError("认证失败", "USERNAME_CONTEXT_REQUIRED", "missing username in auth context", 3, false, null, ["add username to auth context"]);
+}
+
+export function resolveScheme(ctx: RuntimeContext, explicit: string | undefined, must = false): string | null {
+  const scheme = explicit || ctx.scheme;
+  if (must && !scheme) throw new CliError("CLI 参数错误", "SCHEME_REQUIRED", "missing scheme; use --scheme", 2);
+  return scheme ?? null;
+}
+
@@ -0,0 +1,23 @@
+import { CliError } from "./errors.js";
+
+export function parseTime(value: string, option: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new CliError("CLI 参数错误", "INVALID_TIME", `${option} must be a valid ISO 8601 / RFC 3339 timestamp`, 2);
+  }
+  if (!/[zZ]|[+-]\d\d:\d\d$/.test(value)) {
+    throw new CliError("CLI 参数错误", "TIMEZONE_REQUIRED", `${option} must include an explicit timezone offset`, 2);
+  }
+  return value;
+}
+
+export function addMinutesPreservingOffset(value: string, minutes: number): string {
+  const match = value.match(/([+-])(\d\d):(\d\d)$/);
+  const end = new Date(new Date(value).getTime() + minutes * 60_000);
+  if (!match) return end.toISOString().replace(".000Z", "Z");
+  const sign = match[1] === "+" ? 1 : -1;
+  const offsetMinutes = sign * (Number(match[2]) * 60 + Number(match[3]));
+  const local = new Date(end.getTime() + offsetMinutes * 60_000);
+  return `${local.toISOString().replace(".000Z", "")}${match[1]}${match[2]}:${match[3]}`;
+}
+
@@ -0,0 +1,89 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type Dict<T = unknown> = Record<string, T>;
+
+export interface AuthContext {
+  server: string | null;
+  accessToken: string | null;
+  projectId: string | null;
+  userId: string | null;
+  username: string | null;
+  network: string | null;
+  headers: Record<string, string>;
+}
+
+export interface RuntimeContext {
+  server: string;
+  auth: AuthContext;
+  scheme: string | null;
+  timeout: number;
+  requestId: string;
+}
+
+export interface GlobalArgs {
+  server: string | null;
+  authStdin: boolean;
+  scheme: string | null;
+  timeout: number;
+  requestId: string | null;
+}
+
+export interface ParsedGlobalArgs {
+  globals: GlobalArgs;
+  rest: string[];
+}
+
+export type OptionKind = "string" | "boolean" | "repeat" | "number" | "integer";
+export type OptionSchema = Record<string, OptionKind>;
+export type ParsedOptionValue = string | number | boolean | string[];
+
+export interface ParsedOptions {
+  values: Record<string, ParsedOptionValue>;
+  positionals: string[];
+}
+
+export interface RequestOptions {
+  method: string;
+  path: string;
+  params?: Record<string, unknown>;
+  body?: unknown;
+  requireAuth?: boolean;
+  requireProject?: boolean;
+  requireNetworkCtx?: boolean;
+  requireUsernameCtx?: boolean;
+}
+
+export type Handler = (ctx: RuntimeContext, argv: string[]) => Promise<void> | void;
+export type HandlerMap = Record<string, Handler>;
+
+export interface CommandDoc {
+  ok: true;
+  schema_version: string;
+  command: string;
+  summary: string;
+  description: string;
+  usage: string;
+  options: CommandOptionDoc[];
+  examples: string[];
+  output: string;
+  next_commands: string[];
+}
+
+export interface CommandOptionDoc {
+  name: string;
+  description: string;
+  required: boolean;
+  repeated: boolean;
+  default: null;
+}
+
+export type HelpPayload =
+  | CommandDoc
+  | {
+      ok: true;
+      schema_version: string;
+      summary: string;
+      menu_level?: number;
+      commands: Array<{ command: string; summary: string; usage?: string; example?: string }>;
+    };
+
@@ -0,0 +1,50 @@
+import { CliError } from "./core/errors.js";
+import { handlers } from "./handlers.js";
+import { helpPayload } from "./help/index.js";
+import { failure, json } from "./core/output.js";
+import type { RuntimeContext } from "./core/types.js";
+
+export async function dispatch(ctx: RuntimeContext | null, argv: string[]): Promise<void> {
+  if (argv.length === 0 || argv.includes("--help")) {
+    process.stdout.write("Usage: tjwater-cli [OPTIONS] COMMAND [ARGS]...\n\nStructured JSON:\n  tjwater-cli help\n");
+    return;
+  }
+  if (argv[0] === "help") {
+    const payload = helpPayload(argv.slice(1));
+    if (!payload) {
+      failure({
+        summary: "未找到命令",
+        code: "COMMAND_NOT_FOUND",
+        message: `unknown command path: ${argv.slice(1).join(" ")}`,
+        retryable: false,
+        data: { usage: "tjwater-cli help <command-path>", examples: ["tjwater-cli help simulation run", "tjwater-cli simulation help"] },
+        nextCommands: ["tjwater-cli help", "tjwater-cli help simulation"],
+      });
+      return;
+    }
+    json(payload);
+    return;
+  }
+  const matched = matchCommand(argv);
+  if (!matched) throw new CliError("未找到命令", "COMMAND_NOT_FOUND", `No such command: ${argv.join(" ")}`, 2, false, { usage: "tjwater-cli help" }, ["tjwater-cli help"]);
+  const handler = handlers[matched.path];
+  if (!handler) throw new CliError("未找到命令", "COMMAND_NOT_FOUND", `No such command: ${argv.join(" ")}`, 2, false, { usage: "tjwater-cli help" }, ["tjwater-cli help"]);
+  if (!ctx && matched.path !== "__noop") throw new CliError("CLI 参数错误", "RUNTIME_REQUIRED", "runtime context is required for command execution", 2);
+  await handler(ctx!, matched.args);
+}
+
+function matchCommand(argv: string[]): { path: string; args: string[] } | null {
+  const paths = Object.keys(handlers).sort((a, b) => b.split(" ").length - a.split(" ").length);
+  for (const path of paths) {
+    const parts = path.split(" ");
+    if (parts.every((part, index) => argv[index] === part)) return { path, args: argv.slice(parts.length) };
+  }
+  if (argv.at(-1) === "help") {
+    const payload = helpPayload(argv.slice(0, -1));
+    if (payload) {
+      json(payload);
+      return { path: "__noop", args: [] };
+    }
+  }
+  return null;
+}
@@ -0,0 +1,15 @@
+import { analysisHandlers } from "./commands/analysis.js";
+import { componentHandlers } from "./commands/component.js";
+import { dataHandlers } from "./commands/data.js";
+import { networkHandlers } from "./commands/network.js";
+import { simulationHandlers } from "./commands/simulation.js";
+import type { HandlerMap } from "./core/types.js";
+
+export const handlers: HandlerMap = {
+  "__noop": async () => {},
+  ...networkHandlers,
+  ...componentHandlers,
+  ...simulationHandlers,
+  ...analysisHandlers,
+  ...dataHandlers,
+};
@@ -0,0 +1,145 @@
+import { SCHEMA_VERSION } from "../core/constants.js";
+import type { CommandDoc, CommandOptionDoc } from "../core/types.js";
+
+export const GROUP_SUMMARIES: Record<string, string> = {
+  network: "管网节点、管线等基础属性查询命令。",
+  component: "组件选项与配置读取命令。",
+  "component option": "组件选项查询命令。",
+  simulation: "模拟运行与调度相关命令。",
+  analysis: "分析计算与诊断相关命令。",
+  "analysis leakage": "漏损分析相关命令。",
+  "analysis leakage schemes": "漏损方案查询命令。",
+  "analysis burst-detection": "爆管检测相关命令。",
+  "analysis burst-detection schemes": "爆管检测方案查询命令。",
+  "analysis burst-location": "爆管定位相关命令。",
+  "analysis burst-location schemes": "爆管定位方案查询命令。",
+  "analysis risk": "风险分析相关命令。",
+  "analysis sensor-placement": "传感器选址相关命令。",
+  data: "时序、SCADA 和方案数据查询命令。",
+  "data timeseries": "时序数据查询命令。",
+  "data timeseries realtime": "实时模拟时序查询命令。",
+  "data timeseries scheme": "方案时序查询命令。",
+  "data timeseries scada": "SCADA 时序查询命令。",
+  "data timeseries composite": "复合时序查询命令。",
+  "data scada": "SCADA 元数据查询命令。",
+  "data scheme": "方案数据查询命令。",
+};
+
+export const HIDDEN_PATH_PREFIXES = ["analysis burst-location", "analysis risk"];
+
+type CommandSpec = readonly [path: string, summary: string, options: readonly string[], examples: readonly string[], nextCommands?: readonly string[]];
+
+const commandSpecs: readonly CommandSpec[] = [
+  ["network get-junction-properties", "读取节点属性", ["--junction <JUNCTION>"], ["tjwater-cli network get-junction-properties --junction J1"]],
+  ["network get-pipe-properties", "读取管道属性", ["--pipe <PIPE>"], ["tjwater-cli network get-pipe-properties --pipe P1"]],
+  ["network get-all-pipes-properties", "读取全部管道属性", [], ["tjwater-cli network get-all-pipes-properties"]],
+  ["network get-reservoir-properties", "读取水库属性", ["--reservoir <RESERVOIR>"], ["tjwater-cli network get-reservoir-properties --reservoir R1"]],
+  ["network get-all-reservoirs-properties", "读取全部水库属性", [], ["tjwater-cli network get-all-reservoirs-properties"]],
+  ["network get-tank-properties", "读取水箱属性", ["--tank <TANK>"], ["tjwater-cli network get-tank-properties --tank T1"]],
+  ["network get-all-tanks-properties", "读取全部水箱属性", [], ["tjwater-cli network get-all-tanks-properties"]],
+  ["network get-pump-properties", "读取水泵属性", ["--pump <PUMP>"], ["tjwater-cli network get-pump-properties --pump PU1"]],
+  ["network get-all-pumps-properties", "读取全部水泵属性", [], ["tjwater-cli network get-all-pumps-properties"]],
+  ["network get-valve-properties", "读取阀门属性", ["--valve <VALVE>"], ["tjwater-cli network get-valve-properties --valve V1"]],
+  ["network get-all-valves-properties", "读取全部阀门属性", [], ["tjwater-cli network get-all-valves-properties"]],
+  ["component option schema", "读取选项 schema", ["--kind <KIND>", "[--pump <PUMP>]"], ["tjwater-cli component option schema --kind time", "tjwater-cli component option schema --kind energy", "tjwater-cli component option schema --kind pump-energy --pump PUMP1", "tjwater-cli component option schema --kind network"]],
+  ["component option get", "读取选项属性", ["--kind <KIND>", "[--pump <PUMP>]"], ["tjwater-cli component option get --kind time", "tjwater-cli component option get --kind energy", "tjwater-cli component option get --kind pump-energy --pump PUMP1", "tjwater-cli component option get --kind network"]],
+  ["simulation run", "触发指定绝对时间的模拟运行", ["--start-time <START_TIME>", "--duration <DURATION>"], ["tjwater-cli simulation run --start-time 2025-01-02T03:04:05+08:00 --duration 30"], ["tjwater-cli data timeseries realtime links --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00", "tjwater-cli data timeseries realtime nodes --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"]],
+  ["analysis burst", "执行爆管分析", ["--start-time <START_TIME>", "--duration <DURATION>", "--burst-file <BURST_FILE>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst --start-time 2025-01-02T03:04:05+08:00 --duration 900 --burst-file ./burst.json --scheme burst_case_01", "tjwater-cli data scheme get --name burst_case_01", "tjwater-cli data scheme list"]],
+  ["analysis valve", "阀门工况分析。", ["--mode <MODE>", "[--start-time <START_TIME>]", "[--valve <VALVE>]", "[--element <ELEMENT>]", "[--disabled-valve <DISABLED_VALVE>]", "[--duration <DURATION>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis valve --mode close --start-time 2025-01-02T03:04:05+08:00 --valve V1 --valve V2 --duration 900 --scheme valve_case_01", "tjwater-cli analysis valve --mode isolation --element E1 --element E2", "tjwater-cli analysis valve --mode isolation --element E1 --disabled-valve V3"]],
+  ["analysis flushing", "执行冲洗分析", ["--start-time <START_TIME>", "--valve-setting-file <VALVE_SETTING_FILE>", "--drainage-node <DRAINAGE_NODE>", "--flow <FLOW>", "[--duration <DURATION>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis flushing --start-time 2025-01-02T03:04:05+08:00 --valve-setting-file ./valve.json --drainage-node N1 --flow 100.0 --duration 900 --scheme flush_case_01"]],
+  ["analysis age", "执行水龄分析", ["--start-time <START_TIME>", "--duration <DURATION>"], ["tjwater-cli analysis age --start-time 2025-01-02T03:04:05+08:00 --duration 900"]],
+  ["analysis contaminant", "执行污染物模拟", ["--start-time <START_TIME>", "--duration <DURATION>", "--source-node <SOURCE_NODE>", "--concentration <CONCENTRATION>", "[--pattern <PATTERN>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis contaminant --start-time 2025-01-02T03:04:05+08:00 --duration 900 --source-node N1 --concentration 10.0 --scheme contam_case_01"]],
+  ["analysis sensor-placement kmeans", "执行 KMeans 传感器选址", ["--count <COUNT>", "[--min-diameter <MIN_DIAMETER>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis sensor-placement kmeans --count 5 --min-diameter 100 --scheme placement_case_01"]],
+  ["analysis leakage identify", "执行漏损识别", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis leakage identify --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme leak_case_01"]],
+  ["analysis leakage schemes list", "列出漏损方案", [], ["tjwater-cli analysis leakage schemes list"]],
+  ["analysis leakage schemes get", "读取漏损方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis leakage schemes get my_scheme"]],
+  ["analysis burst-detection detect", "执行爆管检测", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst-detection detect --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme detect_case_01"]],
+  ["analysis burst-detection schemes list", "列出爆管检测方案", [], ["tjwater-cli analysis burst-detection schemes list"]],
+  ["analysis burst-detection schemes get", "读取爆管检测方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis burst-detection schemes get my_scheme"]],
+  ["analysis burst-location locate", "执行爆管定位", ["--start-time <START_TIME>", "--end-time <END_TIME>", "--burst-leakage <BURST_LEAKAGE>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst-location locate --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --burst-leakage 100.0 --scheme locate_case_01"]],
+  ["analysis burst-location schemes list", "列出爆管定位方案", [], ["tjwater-cli analysis burst-location schemes list"]],
+  ["analysis burst-location schemes get", "读取爆管定位方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis burst-location schemes get my_scheme"]],
+  ["analysis risk pipe-now", "读取单条管道当前风险", ["--pipe <PIPE>"], ["tjwater-cli analysis risk pipe-now --pipe P1"]],
+  ["analysis risk pipe-history", "读取单条管道历史风险", ["--pipe <PIPE>"], ["tjwater-cli analysis risk pipe-history --pipe P1"]],
+  ["analysis risk network", "读取全网风险", [], ["tjwater-cli analysis risk network"]],
+  ["data timeseries realtime links", "查询实时管道时序", ["--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries realtime links --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data timeseries realtime nodes", "查询实时节点时序", ["--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries realtime nodes --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data timeseries realtime simulation-by-id-time", "按元素和时间查询实时模拟结果", ["--id <ID>", "--type <TYPE>", "--time <TIME>"], ["tjwater-cli data timeseries realtime simulation-by-id-time --id J1 --type junction --time 2025-01-02T03:30:00+08:00", "tjwater-cli data timeseries realtime simulation-by-id-time --id P1 --type pipe --time 2025-01-02T03:30:00+08:00"]],
+  ["data timeseries realtime simulation-by-time-property", "按时间和属性查询实时模拟结果", ["--type <TYPE>", "--time <TIME>", "--property <PROPERTY>"], ["tjwater-cli data timeseries realtime simulation-by-time-property --type pipe --time 2025-01-02T03:30:00+08:00 --property flow"]],
+  ["data timeseries scheme links", "查询方案管道时序", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]"], ["tjwater-cli data timeseries scheme links --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme"]],
+  ["data timeseries scheme node-field", "查询方案节点字段时序", ["--node <NODE>", "--field <FIELD>", "--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]"], ["tjwater-cli data timeseries scheme node-field --node J1 --field pressure --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme"]],
+  ["data timeseries scheme simulation", "查询方案模拟数据", ["--query <QUERY>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]", "[--id <ID>]", "[--time <TIME>]", "[--type <TYPE>]", "[--property <PROPERTY>]"], ["tjwater-cli data timeseries scheme simulation --query by-id-time --id J1 --time 2025-01-02T03:30:00+08:00 --type junction --scheme my_scheme", "tjwater-cli data timeseries scheme simulation --query by-scheme-time-property --time 2025-01-02T03:30:00+08:00 --type pipe --property flow --scheme my_scheme"]],
+  ["data timeseries scada query", "查询 SCADA 时序", ["--device-id <DEVICE_ID>", "--start-time <START_TIME>", "--end-time <END_TIME>", "[--field <FIELD>]"], ["tjwater-cli data timeseries scada query --device-id D1 --device-id D2 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00", "tjwater-cli data timeseries scada query --device-id D1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --field monitored_value"]],
+  ["data timeseries composite", "执行复合时序查询", ["[--kind <KIND>]", "[--feature <FEATURE>]", "[--start-time <START_TIME>]", "[--end-time <END_TIME>]", "[--pipe <PIPE>]", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]", "[--use-cleaned]"], ["tjwater-cli data timeseries composite --kind scada-simulation --feature D1 --feature D2 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme", "tjwater-cli data timeseries composite --kind element-simulation --feature J1:pressure --feature P1:flow --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme", "tjwater-cli data timeseries composite --kind element-scada --feature J1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --use-cleaned"]],
+  ["data timeseries composite pipeline-health", "查询管道健康预测", ["--pipe <PIPE>", "--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries composite pipeline-health --pipe P1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data scada get", "读取单条 SCADA 元数据", ["--kind <KIND>", "--id <ID>"], ["tjwater-cli data scada get --kind info --id SCADA-001"]],
+  ["data scada list", "列出 SCADA 元数据", ["--kind <KIND>"], ["tjwater-cli data scada list --kind info"]],
+  ["data scheme schema", "读取方案 schema", [], ["tjwater-cli data scheme schema"]],
+  ["data scheme get", "读取单条方案", ["--name <NAME>"], ["tjwater-cli data scheme get --name my_scheme"]],
+  ["data scheme list", "列出方案", [], ["tjwater-cli data scheme list"]],
+];
+
+export const commandDocs = new Map<string, CommandDoc>(
+  commandSpecs.map(([path, summary, options, examples, nextCommands = []]) => [
+    path,
+    {
+      ok: true,
+      schema_version: SCHEMA_VERSION,
+      command: path,
+      summary,
+      description: summary,
+      usage: buildUsage(path, options),
+      options: options.filter((item) => item.startsWith("--") || item.startsWith("[--")).map((item) => optionDoc(path, item)),
+      examples: [...(examples ?? [`tjwater-cli ${path}${exampleSuffix(options)}`])],
+      output: "标准 JSON 输出",
+      next_commands: [...nextCommands],
+    },
+  ]),
+);
+
+function buildUsage(path: string, options: readonly string[]): string {
+  const optionTokens = options.filter((item) => item.startsWith("--") || item.startsWith("[--"));
+  return `tjwater-cli ${path}${optionTokens.length ? ` ${optionTokens.join(" ")}` : ""}`;
+}
+
+function optionDoc(path: string, token: string): CommandOptionDoc {
+  const optional = token.startsWith("[");
+  const clean = token.replace(/^\[/, "").replace(/\]$/, "");
+  const name = clean.slice(2).split(/\s+/)[0]!;
+  const repeatedOptions: Record<string, string[]> = {
+    "analysis valve": ["valve", "element", "disabled-valve"],
+    "analysis burst-location locate": ["pressure-scada-id", "flow-scada-id"],
+    "data timeseries scada query": ["device-id"],
+    "data timeseries composite": ["feature"],
+  };
+  return {
+    name,
+    description: "",
+    required: !optional,
+    repeated: (repeatedOptions[path] ?? []).includes(name),
+    default: null,
+  };
+}
+
+function exampleSuffix(options: readonly string[]): string {
+  return options
+    .map((item) => {
+      if (item.includes("START_TIME")) return " --start-time 2025-01-02T03:00:00+08:00";
+      if (item.includes("END_TIME")) return " --end-time 2025-01-02T04:00:00+08:00";
+      if (item.includes("DURATION")) return " --duration 900";
+      if (item.includes("SCHEME")) return " --scheme my_scheme";
+      if (item.includes("KIND")) return " --kind info";
+      if (item.includes("TYPE")) return " --type pipe";
+      if (item.includes("TIME")) return " --time 2025-01-02T03:30:00+08:00";
+      return "";
+    })
+    .join("");
+}
+
+export function isHiddenPath(path: string): boolean {
+  return HIDDEN_PATH_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix} `));
+}
+
+export function hasVisibleSubcommands(path: string): boolean {
+  return [...commandDocs.keys()].some((key) => !isHiddenPath(key) && key.startsWith(`${path} `));
+}
@@ -0,0 +1,53 @@
+import { SCHEMA_VERSION } from "../core/constants.js";
+import { GROUP_SUMMARIES, commandDocs, hasVisibleSubcommands, isHiddenPath } from "./docs.js";
+import type { HelpPayload } from "../core/types.js";
+
+export function helpPayload(pathParts: string[]): HelpPayload | null {
+  const path = pathParts.join(" ");
+  if (path && isHiddenPath(path)) return null;
+  if (path && commandDocs.has(path)) return commandDocs.get(path)!;
+  if (!path) {
+    const seen = new Set<string>();
+    const commands: Array<{ command: string; summary: string }> = [];
+    for (const doc of [...commandDocs.values()].sort((a, b) => a.command.localeCompare(b.command))) {
+      if (isHiddenPath(doc.command)) continue;
+      const command = doc.command.split(" ")[0]!;
+      if (seen.has(command)) continue;
+      seen.add(command);
+      commands.push({ command, summary: GROUP_SUMMARIES[command] ?? `${command} 可用子命令` });
+    }
+    return {
+      ok: true,
+      schema_version: SCHEMA_VERSION,
+      summary: "可用一级菜单",
+      menu_level: 1,
+      commands,
+    };
+  }
+  const prefix = path ? `${path} ` : "";
+  const children: Array<{ command: string; summary: string; usage: string; example: string }> = [];
+  const seen = new Set<string>();
+  for (const doc of [...commandDocs.values()].sort((a, b) => a.command.localeCompare(b.command))) {
+    if (isHiddenPath(doc.command)) continue;
+    if (!doc.command.startsWith(prefix)) continue;
+    const child = doc.command.slice(prefix.length).split(" ")[0]!;
+    if (seen.has(child)) continue;
+    seen.add(child);
+    const childPath = path ? `${path} ${child}` : child;
+    const isGroup = hasVisibleSubcommands(childPath);
+    const childDoc = commandDocs.get(childPath) ?? doc;
+    children.push({
+      command: childPath,
+      summary: isGroup ? (GROUP_SUMMARIES[childPath] ?? `${childPath} 可用子命令`) : childDoc.summary,
+      usage: isGroup ? `tjwater-cli ${childPath} help` : childDoc.usage,
+      example: isGroup ? `tjwater-cli ${childPath} help` : childDoc.examples[0]!,
+    });
+  }
+  if (!children.length && path) return null;
+  return {
+    ok: true,
+    schema_version: SCHEMA_VERSION,
+    summary: GROUP_SUMMARIES[path] ?? `${path} 可用子命令`,
+    commands: children,
+  };
+}
@@ -1,741 +1,9 @@
-#!/usr/bin/env bun
+#!/usr/bin/env sh
+set -eu

-const SCHEMA_VERSION = "tjwater-cli/v1";
-const DEFAULT_SERVER = "http://192.168.1.114:8000";
-const DEFAULT_TIMEOUT = 180;
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if command -v bun >/dev/null 2>&1; then
+  exec bun "$SCRIPT_DIR/tjwater-cli.ts" "$@"
+fi

-const GROUPS = {
-  network: "管网节点、管线等基础属性查询命令。",
-  component: "组件选项与配置读取命令。",
-  simulation: "模拟运行与调度相关命令。",
-  analysis: "分析计算与诊断相关命令。",
-  data: "时序、SCADA 和方案数据查询命令。",
-};
-
-const NETWORK_COMMANDS = {
-  "get-junction-properties": {
-    summary: "读取节点属性成功",
-    path: "/getjunctionproperties/",
-    options: { junction: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), junction: args.junction }),
-  },
-  "get-pipe-properties": {
-    summary: "读取管道属性成功",
-    path: "/getpipeproperties/",
-    options: { pipe: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), pipe: args.pipe }),
-  },
-  "get-all-pipes-properties": {
-    summary: "读取全部管道属性成功",
-    path: "/getallpipeproperties/",
-    params: ({ ctx }) => ({ network: requireNetwork(ctx) }),
-  },
-  "get-reservoir-properties": {
-    summary: "读取水库属性成功",
-    path: "/getreservoirproperties/",
-    options: { reservoir: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), reservoir: args.reservoir }),
-  },
-  "get-all-reservoirs-properties": {
-    summary: "读取全部水库属性成功",
-    path: "/getallreservoirproperties/",
-    params: ({ ctx }) => ({ network: requireNetwork(ctx) }),
-  },
-  "get-tank-properties": {
-    summary: "读取水箱属性成功",
-    path: "/gettankproperties/",
-    options: { tank: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), tank: args.tank }),
-  },
-  "get-all-tanks-properties": {
-    summary: "读取全部水箱属性成功",
-    path: "/getalltankproperties/",
-    params: ({ ctx }) => ({ network: requireNetwork(ctx) }),
-  },
-  "get-pump-properties": {
-    summary: "读取水泵属性成功",
-    path: "/getpumpproperties/",
-    options: { pump: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), pump: args.pump }),
-  },
-  "get-all-pumps-properties": {
-    summary: "读取全部水泵属性成功",
-    path: "/getallpumpproperties/",
-    params: ({ ctx }) => ({ network: requireNetwork(ctx) }),
-  },
-  "get-valve-properties": {
-    summary: "读取阀门属性成功",
-    path: "/getvalveproperties/",
-    options: { valve: { required: true } },
-    params: ({ args, ctx }) => ({ network: requireNetwork(ctx), valve: args.valve }),
-  },
-  "get-all-valves-properties": {
-    summary: "读取全部阀门属性成功",
-    path: "/getallvalveproperties/",
-    params: ({ ctx }) => ({ network: requireNetwork(ctx) }),
-  },
-};
-
-const DATA_REALTIME_COMMANDS = {
-  links: {
-    summary: "读取实时管道数据成功",
-    path: "/realtime/links",
-    options: { "start-time": { required: true }, "end-time": { required: true } },
-    requireProject: true,
-    params: ({ args }) => ({
-      start_time: parseTime(args["start-time"], "--start-time"),
-      end_time: parseTime(args["end-time"], "--end-time"),
-    }),
-  },
-  nodes: {
-    summary: "读取实时节点数据成功",
-    path: "/realtime/nodes",
-    options: { "start-time": { required: true }, "end-time": { required: true } },
-    requireProject: true,
-    params: ({ args }) => ({
-      start_time: parseTime(args["start-time"], "--start-time"),
-      end_time: parseTime(args["end-time"], "--end-time"),
-    }),
-  },
-  "simulation-by-id-time": {
-    summary: "读取实时模拟数据成功",
-    path: "/realtime/query/by-id-time",
-    options: { id: { required: true }, type: { required: true }, time: { required: true } },
-    requireProject: true,
-    params: ({ args }) => ({
-      id: args.id,
-      type: args.type,
-      query_time: parseTime(args.time, "--time"),
-    }),
-  },
-  "simulation-by-time-property": {
-    summary: "读取实时属性聚合数据成功",
-    path: "/realtime/query/by-time-property",
-    options: { type: { required: true }, time: { required: true }, property: { required: true } },
-    requireProject: true,
-    params: ({ args }) => ({
-      type: args.type,
-      query_time: parseTime(args.time, "--time"),
-      property: args.property,
-    }),
-  },
-};
-
-const DATA_SCHEME_COMMANDS = {
-  list: {
-    summary: "读取方案列表成功",
-    path: "/schemes",
-    requireProject: true,
-    params: ({ args }) => maybe({ scheme_type: args["scheme-type"] }),
-  },
-  get: {
-    summary: "读取方案详情成功",
-    path: ({ positionals }) => `/schemes/${encodeURIComponent(requirePos(positionals, 0, "scheme name"))}`,
-    requireProject: true,
-    params: ({ args }) => maybe({ scheme_type: args["scheme-type"] }),
-  },
-  links: {
-    summary: "读取方案管道数据成功",
-    path: "/scheme/links",
-    options: { "start-time": { required: true }, "end-time": { required: true } },
-    requireProject: true,
-    params: ({ args, ctx }) => ({
-      scheme_name: resolveScheme(ctx, args.scheme, true),
-      scheme_type: args["scheme-type"] ?? "simulation",
-      start_time: parseTime(args["start-time"], "--start-time"),
-      end_time: parseTime(args["end-time"], "--end-time"),
-    }),
-  },
-};
-
-const DATA_SCADA_COMMANDS = {
-  list: {
-    summary: "读取 SCADA 元数据成功",
-    path: "/scada/devices",
-    requireProject: true,
-    params: ({ args }) => maybe({ kind: args.kind }),
-  },
-  query: {
-    summary: "读取 SCADA 时序成功",
-    path: ({ args }) => (args.field ? "/scada/by-ids-field-time-range" : "/scada/by-ids-time-range"),
-    options: { "device-id": { required: true, repeated: true }, "start-time": { required: true }, "end-time": { required: true } },
-    requireProject: true,
-    params: ({ args }) => ({
-      device_ids: toArray(args["device-id"]).join(","),
-      start_time: parseTime(args["start-time"], "--start-time"),
-      end_time: parseTime(args["end-time"], "--end-time"),
-      ...maybe({ field: args.field }),
-    }),
-  },
-};
-
-async function main() {
-  const parsed = parseArgs(Bun.argv.slice(2));
-  if (parsed.help || parsed.command.length === 0) {
-    emitHelp(parsed.command);
-    return 0;
-  }
-  if (parsed.command[0] === "help") {
-    emitHelp(parsed.command.slice(1));
-    return 0;
-  }
-
-  if (isLocalHelpCommand(parsed.command)) {
-    const result = await dispatch(parsed, null);
-    emitSuccess({
-      summary: result.summary,
-      data: result.local,
-      ctx: null,
-      durationMs: 0,
-      nextCommands: result.nextCommands,
-    });
-    return 0;
-  }
-
-  const ctx = await buildContext(parsed.global);
-  const startedAt = Date.now();
-  const result = await dispatch(parsed, ctx);
-  const data = await requestJson(ctx, result);
-  emitSuccess({
-    summary: result.summary,
-    data,
-    ctx,
-    durationMs: Date.now() - startedAt,
-    nextCommands: result.nextCommands,
-  });
-  return 0;
-}
-
-function isLocalHelpCommand(command) {
-  if (command.length === 1 && GROUPS[command[0]]) return true;
-  return command.length > 1 && command.at(-1) === "help";
-}
-
-async function dispatch(parsed, ctx) {
-  const [group, ...rest] = parsed.command;
-  if (group === "network") {
-    if (rest.length === 0 || rest[0] === "help") return helpResult(["network"], NETWORK_COMMANDS);
-    return commandFromMap(NETWORK_COMMANDS, rest, parsed, ctx);
-  }
-  if (group === "component" && rest[0] === "option") {
-    if (rest.length === 1 || rest[1] === "help") return helpResult(["component", "option"], {
-      schema: { summary: "读取选项 schema" },
-      get: { summary: "读取选项属性" },
-    });
-    return componentOption(rest.slice(1), parsed, ctx);
-  }
-  if (group === "component" && (rest.length === 0 || rest[0] === "help")) {
-    return helpResult(["component"], { option: { summary: GROUPS.component } });
-  }
-  if (group === "simulation" && rest[0] === "run") {
-    requireOptions(parsed.args, { "start-time": { required: true }, duration: { required: true } });
-    const start = parseTime(parsed.args["start-time"], "--start-time");
-    const duration = Number(parsed.args.duration);
-    const endTime = new Date(Date.parse(start) + duration * 60_000).toISOString();
-    return {
-      summary: "触发模拟成功",
-      method: "POST",
-      path: "/runsimulationmanuallybydate/",
-      body: { name: requireNetwork(ctx), start_time: start, duration },
-      nextCommands: [
-        `tjwater-cli data timeseries realtime links --start-time ${start} --end-time ${endTime}`,
-        `tjwater-cli data timeseries realtime nodes --start-time ${start} --end-time ${endTime}`,
-      ],
-    };
-  }
-  if (group === "simulation" && (rest.length === 0 || rest[0] === "help")) {
-    return helpResult(["simulation"], { run: { summary: "触发指定绝对时间的模拟运行" } });
-  }
-  if (group === "analysis") {
-    if (rest.length === 0 || rest[0] === "help") return helpResult(["analysis"], {
-      age: { summary: "执行水龄分析" },
-      leakage: { summary: "漏损分析相关命令" },
-      "burst-detection": { summary: "爆管检测相关命令" },
-      "sensor-placement": { summary: "传感器选址相关命令" },
-    });
-    return analysis(rest, parsed, ctx);
-  }
-  if (group === "data") {
-    if (rest.length === 0 || rest[0] === "help") return helpResult(["data"], {
-      timeseries: { summary: "时序数据查询命令" },
-      scada: { summary: "SCADA 元数据查询命令" },
-      scheme: { summary: "方案数据查询命令" },
-    });
-    return dataCommand(rest, parsed, ctx);
-  }
-  throw cliError("未找到命令", "COMMAND_NOT_FOUND", `unknown command: ${parsed.command.join(" ")}`, 2, {
-    next_commands: ["tjwater-cli help"],
-  });
-}
-
-function helpResult(command, commands) {
-  return {
-    summary: `命令帮助：${command.join(" ")}`,
-    local: {
-      command: command.join(" "),
-      commands: Object.fromEntries(
-        Object.entries(commands).map(([name, spec]) => [name, spec.summary ?? ""]),
-      ),
-      examples: examplesFor(command),
-    },
-  };
-}
-
-function commandFromMap(map, commandPath, parsed, ctx) {
-  const name = commandPath[0];
-  const spec = map[name];
-  if (!spec) {
-    throw cliError("未找到命令", "COMMAND_NOT_FOUND", `unknown command: ${parsed.command.join(" ")}`, 2, {
-      next_commands: ["tjwater-cli help"],
-    });
-  }
-  requireOptions(parsed.args, spec.options ?? {});
-  const positionals = [...commandPath.slice(1), ...parsed.positionals];
-  return {
-    summary: spec.summary,
-    method: spec.method ?? "GET",
-    path: valueOf(spec.path, { args: parsed.args, positionals, ctx }),
-    params: spec.params?.({ args: parsed.args, positionals, ctx }) ?? {},
-    body: spec.body?.({ args: parsed.args, positionals, ctx }),
-    requireProject: spec.requireProject,
-    nextCommands: spec.nextCommands,
-  };
-}
-
-function componentOption(rest, parsed, ctx) {
-  const action = rest[0];
-  if (action !== "schema" && action !== "get") {
-    throw cliError("未找到命令", "COMMAND_NOT_FOUND", "unknown component option command", 2);
-  }
-  requireOptions(parsed.args, { kind: { required: true } });
-  const kind = parsed.args.kind;
-  const routes = {
-    "time:schema": "/gettimeschema",
-    "time:get": "/gettimeproperties/",
-    "energy:schema": "/getenergyschema/",
-    "energy:get": "/getenergyproperties/",
-    "pump-energy:schema": "/getpumpenergyschema/",
-    "pump-energy:get": "/getpumpenergyproperties//",
-    "network:schema": "/getoptionschema/",
-    "network:get": "/getoptionproperties/",
-  };
-  const path = routes[`${kind}:${action}`];
-  if (!path) {
-    throw cliError("CLI 参数错误", "INVALID_KIND", "--kind must be one of time, energy, pump-energy, network", 2);
-  }
-  if (kind === "pump-energy" && action === "get" && !parsed.args.pump) {
-    throw cliError("CLI 参数错误", "PUMP_REQUIRED", "--pump is required when --kind pump-energy", 2);
-  }
-  return {
-    summary: action === "schema" ? "读取选项 schema 成功" : "读取选项属性成功",
-    method: "GET",
-    path,
-    params: { network: requireNetwork(ctx), ...maybe({ pump: parsed.args.pump }) },
-  };
-}
-
-function analysis(rest, parsed, ctx) {
-  const [domain, sub, leaf] = rest;
-  if (domain === "age") {
-    requireOptions(parsed.args, { "start-time": { required: true }, duration: { required: true } });
-    return {
-      summary: "水龄分析执行成功",
-      method: "GET",
-      path: "/age_analysis/",
-      params: {
-        network: requireNetwork(ctx),
-        start_time: parseTime(parsed.args["start-time"], "--start-time"),
-        duration: Number(parsed.args.duration),
-      },
-    };
-  }
-  if (domain === "leakage" && sub === "schemes") {
-    return schemesCommand("漏损", "/leakage/schemes", leaf, rest[3], parsed, ctx);
-  }
-  if (domain === "burst-detection" && sub === "schemes") {
-    return schemesCommand("爆管检测", "/burst-detection/schemes", leaf, rest[3], parsed, ctx);
-  }
-  if (domain === "leakage" && sub === "identify") {
-    return detectionCommand("漏损识别执行成功", "/leakage/identify/", parsed, ctx);
-  }
-  if (domain === "burst-detection" && sub === "detect") {
-    return detectionCommand("爆管检测执行成功", "/burst-detection/detect/", parsed, ctx);
-  }
-  if (domain === "sensor-placement" && sub === "kmeans") {
-    requireOptions(parsed.args, { count: { required: true } });
-    return {
-      summary: "传感器选址执行成功",
-      method: "POST",
-      path: "/pressure_sensor_placement_kmeans/",
-      body: {
-        name: requireNetwork(ctx),
-        scheme_name: resolveScheme(ctx, parsed.args.scheme, true),
-        sensor_number: Number(parsed.args.count),
-        min_diameter: Number(parsed.args["min-diameter"] ?? 0),
-        username: requireUsername(ctx),
-      },
-    };
-  }
-  throw cliError("未找到命令", "COMMAND_NOT_FOUND", `unknown analysis command: ${rest.join(" ")}`, 2);
-}
-
-function schemesCommand(label, basePath, action, inlineName, parsed, ctx) {
-  if (action === "list") {
-    return {
-      summary: `读取${label}方案列表成功`,
-      method: "GET",
-      path: `${basePath}/`,
-      params: { network: requireNetwork(ctx) },
-    };
-  }
-  if (action === "get") {
-    const name = inlineName ?? requirePos(parsed.positionals, 0, "scheme name");
-    return {
-      summary: `读取${label}方案详情成功`,
-      method: "GET",
-      path: `${basePath}/${encodeURIComponent(name)}`,
-      params: { network: requireNetwork(ctx) },
-    };
-  }
-  throw cliError("未找到命令", "COMMAND_NOT_FOUND", "unknown schemes command", 2);
-}
-
-function detectionCommand(summary, path, parsed, ctx) {
-  requireOptions(parsed.args, { "start-time": { required: true }, "end-time": { required: true } });
-  return {
-    summary,
-    method: "POST",
-    path,
-    body: {
-      network: requireNetwork(ctx),
-      scada_start: parseTime(parsed.args["start-time"], "--start-time"),
-      scada_end: parseTime(parsed.args["end-time"], "--end-time"),
-      scheme_name: resolveScheme(ctx, parsed.args.scheme, true),
-    },
-  };
-}
-
-function dataCommand(rest, parsed, ctx) {
-  if (rest[0] === "timeseries" && rest[1] === "realtime") {
-    return commandFromMap(DATA_REALTIME_COMMANDS, rest.slice(2), parsed, ctx);
-  }
-  if (rest[0] === "timeseries" && rest[1] === "scheme") {
-    return commandFromMap(DATA_SCHEME_COMMANDS, rest.slice(2), parsed, ctx);
-  }
-  if (rest[0] === "timeseries" && rest[1] === "scada") {
-    return commandFromMap(DATA_SCADA_COMMANDS, rest.slice(2), parsed, ctx);
-  }
-  if (rest[0] === "scada") {
-    return commandFromMap(DATA_SCADA_COMMANDS, rest.slice(1), parsed, ctx);
-  }
-  if (rest[0] === "scheme") {
-    return commandFromMap(DATA_SCHEME_COMMANDS, rest.slice(1), parsed, ctx);
-  }
-  throw cliError("未找到命令", "COMMAND_NOT_FOUND", `unknown data command: ${rest.join(" ")}`, 2);
-}
-
-async function requestJson(ctx, request) {
-  if (request.local !== undefined) {
-    return request.local;
-  }
-  if (request.requireProject) {
-    requireProject(ctx);
-  }
-  const url = new URL(valueOf(request.path, { args: {}, positionals: [], ctx }), ctx.server);
-  for (const [key, value] of Object.entries(request.params ?? {})) {
-    if (value === undefined || value === null || value === "") continue;
-    if (Array.isArray(value)) {
-      for (const item of value) url.searchParams.append(key, String(item));
-      continue;
-    }
-    url.searchParams.set(key, String(value));
-  }
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), ctx.timeout * 1000);
-  const headers = {
-    Accept: "application/json",
-    "X-Request-Id": ctx.requestId,
-    ...ctx.auth.headers,
-  };
-  if (ctx.auth.accessToken) headers.Authorization = `Bearer ${ctx.auth.accessToken}`;
-  if (ctx.auth.projectId) headers["X-Project-Id"] = ctx.auth.projectId;
-  if (ctx.auth.userId) headers["X-User-Id"] = ctx.auth.userId;
-  if (request.body !== undefined) headers["Content-Type"] = "application/json";
-
-  try {
-    const response = await fetch(url, {
-      method: request.method ?? "GET",
-      headers,
-      body: request.body === undefined ? undefined : JSON.stringify(request.body),
-      signal: controller.signal,
-    });
-    const text = await response.text();
-    let data = text;
-    try {
-      data = text ? JSON.parse(text) : null;
-    } catch {}
-    if (!response.ok) {
-      throw cliError("服务端请求失败", "HTTP_ERROR", `server returned HTTP ${response.status}`, response.status >= 500 ? 4 : 2, {
-        retryable: response.status >= 500,
-        data: { status: response.status, body: data },
-      });
-    }
-    return data;
-  } catch (error) {
-    if (error?.name === "AbortError") {
-      throw cliError("命令超时", "TIMEOUT", `request timed out after ${ctx.timeout}s`, 4, { retryable: true });
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function buildContext(global) {
-  const auth = await loadAuth(global.authStdin);
-  return {
-    server: (global.server ?? auth.server ?? DEFAULT_SERVER).replace(/\/+$/, ""),
-    auth,
-    scheme: global.scheme,
-    timeout: Number(global.timeout ?? DEFAULT_TIMEOUT),
-    requestId: global.requestId ?? crypto.randomUUID(),
-  };
-}
-
-async function loadAuth(authStdin) {
-  if (authStdin) {
-    const raw = await new Response(Bun.stdin.stream()).text();
-    return normalizeAuth(JSON.parse(raw || "{}"));
-  }
-  const extraHeaders = process.env.TJWATER_EXTRA_HEADERS
-    ? JSON.parse(process.env.TJWATER_EXTRA_HEADERS)
-    : {};
-  return normalizeAuth({
-    server: process.env.TJWATER_SERVER,
-    access_token: process.env.TJWATER_ACCESS_TOKEN,
-    project_id: process.env.TJWATER_PROJECT_ID,
-    user_id: process.env.TJWATER_USER_ID,
-    username: process.env.TJWATER_USERNAME,
-    network: process.env.TJWATER_NETWORK,
-    headers: extraHeaders,
-  });
-}
-
-function normalizeAuth(raw) {
-  return {
-    server: pick(raw, "server", "base_url"),
-    accessToken: pick(raw, "access_token", "token", "accessToken"),
-    projectId: pick(raw, "project_id", "projectId", "x_project_id"),
-    userId: pick(raw, "user_id", "userId", "x_user_id"),
-    username: pick(raw, "username", "preferred_username"),
-    network: pick(raw, "network", "project_code", "projectCode", "project"),
-    headers: typeof raw.headers === "object" && raw.headers !== null ? raw.headers : {},
-  };
-}
-
-function parseArgs(argv) {
-  const global = {};
-  const command = [];
-  const args = {};
-  const positionals = [];
-  let help = false;
-  let commandStarted = false;
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i];
-    if (token === "--help" || token === "-h") {
-      help = true;
-      continue;
-    }
-    if (!commandStarted && token.startsWith("--")) {
-      const key = camel(token.slice(2));
-      if (["authStdin"].includes(key)) {
-        global[key] = true;
-      } else {
-        global[key] = argv[++i];
-      }
-      continue;
-    }
-    commandStarted = true;
-    if (token.startsWith("--")) {
-      const key = token.slice(2);
-      const next = argv[i + 1];
-      const value = next && !next.startsWith("--") ? argv[++i] : true;
-      if (args[key] === undefined) {
-        args[key] = value;
-      } else if (Array.isArray(args[key])) {
-        args[key].push(value);
-      } else {
-        args[key] = [args[key], value];
-      }
-      continue;
-    }
-    if (Object.keys(args).length === 0 && positionals.length === 0) {
-      command.push(token);
-    } else {
-      positionals.push(token);
-    }
-  }
-  return { global, command, args, positionals, help };
-}
-
-function requireOptions(args, spec) {
-  for (const [name, option] of Object.entries(spec)) {
-    if (option.required && (args[name] === undefined || args[name] === "")) {
-      throw cliError("CLI 参数错误", "MISSING_OPTION", `missing required option --${name}`, 2);
-    }
-  }
-}
-
-function emitHelp(command = []) {
-  const payload = {
-    ok: true,
-    schema_version: SCHEMA_VERSION,
-    summary: command.length ? `命令帮助：${command.join(" ")}` : "TJWater agent CLI",
-    data: {
-      command: command.join(" "),
-      groups: GROUPS,
-      examples: [
-        "tjwater-cli help",
-        "tjwater-cli network get-all-pipes-properties",
-        "tjwater-cli data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00",
-        "tjwater-cli analysis leakage schemes list",
-      ],
-    },
-  };
-  console.log(JSON.stringify(payload, null, 2));
-}
-
-function emitSuccess({ summary, data, ctx, durationMs, nextCommands }) {
-  console.log(JSON.stringify({
-    ok: true,
-    schema_version: SCHEMA_VERSION,
-    summary,
-    data,
-    metadata: ctx
-      ? {
-          server: ctx.server,
-          request_id: ctx.requestId,
-          duration_ms: durationMs,
-        }
-      : undefined,
-    next_commands: nextCommands,
-  }));
-}
-
-function examplesFor(command) {
-  const key = command.join(" ");
-  const examples = {
-    network: [
-      "tjwater-cli network get-all-pipes-properties",
-      "tjwater-cli network get-pipe-properties --pipe P1",
-    ],
-    component: ["tjwater-cli component option help"],
-    "component option": [
-      "tjwater-cli component option schema --kind time",
-      "tjwater-cli component option get --kind network",
-    ],
-    simulation: [
-      "tjwater-cli simulation run --start-time 2025-01-01T00:00:00+08:00 --duration 30",
-    ],
-    analysis: [
-      "tjwater-cli analysis age --start-time 2025-01-01T00:00:00+08:00 --duration 900",
-      "tjwater-cli analysis leakage schemes list",
-    ],
-    data: [
-      "tjwater-cli data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00",
-      "tjwater-cli data scada list",
-      "tjwater-cli data scheme list",
-    ],
-  };
-  return examples[key] ?? ["tjwater-cli help"];
-}
-
-function emitFailure(error) {
-  const payload = {
-    ok: false,
-    schema_version: SCHEMA_VERSION,
-    summary: error.summary ?? "命令失败",
-    error: {
-      code: error.code ?? "UNKNOWN",
-      message: error.message ?? String(error),
-      retryable: Boolean(error.retryable),
-    },
-    data: error.data,
-    next_commands: error.next_commands,
-  };
-  console.error(JSON.stringify(payload));
-  return error.exitCode ?? 1;
-}
-
-function cliError(summary, code, message, exitCode, extra = {}) {
-  const error = new Error(message);
-  error.summary = summary;
-  error.code = code;
-  error.exitCode = exitCode;
-  Object.assign(error, extra);
-  return error;
-}
-
-function requireNetwork(ctx) {
-  if (ctx.auth.network) return ctx.auth.network;
-  throw cliError("认证失败", "NETWORK_CONTEXT_REQUIRED", "missing network in auth context", 3);
-}
-
-function requireProject(ctx) {
-  if (ctx.auth.projectId) return ctx.auth.projectId;
-  throw cliError("认证失败", "PROJECT_CONTEXT_REQUIRED", "missing project_id for agent context", 3);
-}
-
-function requireUsername(ctx) {
-  if (ctx.auth.username) return ctx.auth.username;
-  throw cliError("认证失败", "USERNAME_CONTEXT_REQUIRED", "missing username in auth context", 3);
-}
-
-function resolveScheme(ctx, explicit, required) {
-  const scheme = explicit ?? ctx.scheme;
-  if (required && !scheme) {
-    throw cliError("CLI 参数错误", "SCHEME_REQUIRED", "missing scheme; use --scheme", 2);
-  }
-  return scheme;
-}
-
-function parseTime(value, optionName) {
-  if (!value || Number.isNaN(Date.parse(value)) || !/[zZ]|[+-]\d\d:\d\d$/.test(value)) {
-    throw cliError("CLI 参数错误", "INVALID_TIME", `${optionName} must be RFC3339 with timezone`, 2);
-  }
-  return value;
-}
-
-function requirePos(values, index, name) {
-  const value = values[index];
-  if (!value) throw cliError("CLI 参数错误", "MISSING_ARGUMENT", `missing ${name}`, 2);
-  return value;
-}
-
-function pick(raw, ...keys) {
-  for (const key of keys) {
-    if (raw?.[key] !== undefined && raw[key] !== "") return raw[key];
-  }
-  return undefined;
-}
-
-function valueOf(value, args) {
-  return typeof value === "function" ? value(args) : value;
-}
-
-function maybe(values) {
-  return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined && value !== ""));
-}
-
-function toArray(value) {
-  return Array.isArray(value) ? value : value === undefined ? [] : [value];
-}
-
-function camel(value) {
-  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-
-main()
-  .then((code) => process.exit(code))
-  .catch((error) => process.exit(emitFailure(error)));
+exec node "$SCRIPT_DIR/tjwater-cli.ts" "$@"
@@ -0,0 +1,45 @@
+import { dispatch } from "./src/dispatch.js";
+import { CliError, errorMessage } from "./src/core/errors.js";
+import { failure } from "./src/core/output.js";
+import { buildRuntime, parseGlobalArgs } from "./src/core/runtime.js";
+
+let currentServer: string | null = null;
+let currentRequestId: string | null = null;
+
+async function main(): Promise<number> {
+  const { globals, rest } = parseGlobalArgs(process.argv.slice(2));
+  if (isHelpRequest(rest)) {
+    await dispatch(null, rest);
+    return 0;
+  }
+  const ctx = await buildRuntime(globals);
+  currentServer = ctx.server;
+  currentRequestId = ctx.requestId;
+  await dispatch(ctx, rest);
+  return 0;
+}
+
+function isHelpRequest(argv: string[]): boolean {
+  return argv.length === 0 || argv[0] === "help" || argv.includes("--help") || argv.at(-1) === "help";
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  if (error instanceof CliError) {
+    failure({
+      summary: error.summary,
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+      server: currentServer,
+      requestId: currentRequestId,
+      data: error.data,
+      nextCommands: error.nextCommands,
+    });
+    process.exitCode = error.exitCode;
+  } else {
+    failure({ summary: "CLI 执行失败", code: "UNHANDLED_ERROR", message: errorMessage(error), retryable: false });
+    process.exitCode = 1;
+  }
+}
@@ -0,0 +1,355 @@
+import { strict as assert } from "node:assert";
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../cli/tjwater-cli");
+const pythonCliCwd = resolve(dirname(fileURLToPath(import.meta.url)), "../../../TJWaterServerBinary/cli");
+
+function runCommand(command, args, input, options = {}) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", reject);
+    child.on("close", (exitCode) => resolveRun({ exitCode, stdout, stderr }));
+    if (input !== undefined) child.stdin.end(JSON.stringify(input));
+    else child.stdin.end();
+  });
+}
+
+function runCli(args, input) {
+  return runCommand(cliPath, args, input);
+}
+
+function runPythonCli(args, input) {
+  return runCommand("python", ["-m", "tjwater_cli", ...args], input, { cwd: pythonCliCwd });
+}
+
+function parseJsonResult(result) {
+  return JSON.parse(result.stdout);
+}
+
+async function startJsonServer(responseData) {
+  const seen = [];
+  const server = createServer(async (req, res) => {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(Buffer.from(chunk));
+    const text = Buffer.concat(chunks).toString("utf8");
+    seen.push({
+      body: text ? JSON.parse(text) : null,
+      headers: req.headers,
+      method: req.method,
+      url: req.url,
+    });
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(responseData));
+  });
+
+  await new Promise((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = server.address();
+  return {
+    seen,
+    url: `http://127.0.0.1:${address.port}`,
+    close: () => new Promise((resolveClose) => server.close(resolveClose)),
+  };
+}
+
+function normalizeSeenRequest(request) {
+  const url = new URL(request.url, "http://127.0.0.1");
+  const query = {};
+  for (const key of [...new Set(url.searchParams.keys())].sort()) {
+    const values = url.searchParams.getAll(key);
+    query[key] = values.length === 1 ? values[0] : values;
+  }
+  return {
+    body: request.body,
+    headers: {
+      authorization: request.headers.authorization,
+      "x-project-id": request.headers["x-project-id"],
+      "x-user-id": request.headers["x-user-id"],
+    },
+    method: request.method,
+    path: url.pathname,
+    query,
+  };
+}
+
+async function runAgainstServer(name, runner, args, auth, responseData = { accepted: true }) {
+  const server = await startJsonServer(responseData);
+  try {
+    const result = await runner(["--auth-stdin", ...args], { ...auth, server: server.url });
+    if (!result.stdout.trim()) {
+      throw new Error(`${name}: CLI produced empty stdout; exit=${result.exitCode}; stderr=${result.stderr}`);
+    }
+    return {
+      exitCode: result.exitCode,
+      payload: parseJsonResult(result),
+      requests: server.seen.map(normalizeSeenRequest),
+      stderr: result.stderr,
+    };
+  } finally {
+    await server.close();
+  }
+}
+
+test("emits structured JSON help compatible with tjwater-cli/v1", async () => {
+  const result = await runCli(["help", "simulation", "run"]);
+
+  assert.equal(result.exitCode, 0, result.stderr);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.schema_version, "tjwater-cli/v1");
+  assert.equal(payload.command, "simulation run");
+  assert.equal(payload.usage, "tjwater-cli simulation run --start-time <START_TIME> --duration <DURATION>");
+});
+
+test("matches Python CLI help discovery and hidden command behavior", async () => {
+  for (const args of [["help"], ["help", "analysis"]]) {
+    const [nodeResult, pythonResult] = await Promise.all([runCli(args), runPythonCli(args)]);
+    assert.equal(nodeResult.exitCode, pythonResult.exitCode);
+    assert.deepEqual(parseJsonResult(nodeResult), parseJsonResult(pythonResult));
+  }
+
+  const [nodeLeaf, pythonLeaf] = await Promise.all([
+    runCli(["help", "simulation", "run"]),
+    runPythonCli(["help", "simulation", "run"]),
+  ]);
+  assert.equal(nodeLeaf.exitCode, pythonLeaf.exitCode);
+  const nodePayload = parseJsonResult(nodeLeaf);
+  const pythonPayload = parseJsonResult(pythonLeaf);
+  assert.equal(nodePayload.ok, pythonPayload.ok);
+  assert.equal(nodePayload.schema_version, pythonPayload.schema_version);
+  assert.equal(nodePayload.command, pythonPayload.command);
+  assert.equal(nodePayload.summary, pythonPayload.summary);
+  assert.equal(nodePayload.usage, pythonPayload.usage);
+  assert.deepEqual(nodePayload.options.map(({ name, required, repeated }) => ({ name, required, repeated })), pythonPayload.options.map(({ name, required, repeated }) => ({ name, required, repeated })));
+  assert.deepEqual(nodePayload.examples, pythonPayload.examples);
+  assert.deepEqual(nodePayload.next_commands, pythonPayload.next_commands);
+
+  const [nodeHidden, pythonHidden] = await Promise.all([
+    runCli(["help", "analysis", "risk"]),
+    runPythonCli(["help", "analysis", "risk"]),
+  ]);
+  assert.equal(nodeHidden.exitCode, pythonHidden.exitCode);
+  const nodeError = parseJsonResult(nodeHidden);
+  const pythonError = parseJsonResult(pythonHidden);
+  delete nodeError.metadata.generated_at;
+  delete pythonError.metadata.generated_at;
+  assert.deepEqual(nodeError, pythonError);
+});
+
+test("matches Python CLI leaf help for every visible command", async () => {
+  const listResult = await runCommand(
+    "python",
+    [
+      "-c",
+      "from tjwater_cli.registry import COMMAND_DOCS, is_hidden_path\nimport json\nprint(json.dumps([' '.join(path) for path in COMMAND_DOCS if not is_hidden_path(path)], ensure_ascii=False))",
+    ],
+    undefined,
+    { cwd: pythonCliCwd },
+  );
+  assert.equal(listResult.exitCode, 0, listResult.stderr);
+  const commands = JSON.parse(listResult.stdout);
+
+  for (const command of commands) {
+    const args = ["help", ...command.split(" ")];
+    const [nodeResult, pythonResult] = await Promise.all([runCli(args), runPythonCli(args)]);
+    assert.equal(nodeResult.exitCode, pythonResult.exitCode, command);
+
+    const nodePayload = parseJsonResult(nodeResult);
+    const pythonPayload = parseJsonResult(pythonResult);
+    const comparable = (payload) => ({
+      command: payload.command,
+      summary: payload.summary,
+      usage: payload.usage,
+      examples: payload.examples,
+      next_commands: payload.next_commands,
+      options: (payload.options ?? []).map(({ name, required, repeated }) => ({
+        name,
+        required,
+        repeated,
+      })),
+    });
+    assert.deepEqual(comparable(nodePayload), comparable(pythonPayload), command);
+  }
+});
+
+test("sends auth headers and simulation body through the backend API contract", async () => {
+  const server = await startJsonServer({ accepted: true });
+  try {
+    const result = await runCli(
+      [
+        "--auth-stdin",
+        "simulation",
+        "run",
+        "--start-time",
+        "2025-01-02T03:00:00+08:00",
+        "--duration",
+        "60",
+      ],
+      {
+        server: server.url,
+        access_token: "token-1",
+        network: "tjwater",
+        headers: { "x-extra": "extra" },
+      },
+    );
+
+    assert.equal(result.exitCode, 0, result.stderr);
+    assert.equal(server.seen[0].method, "POST");
+    assert.equal(server.seen[0].url, "/api/v1/runsimulationmanuallybydate/");
+    assert.equal(server.seen[0].headers.authorization, "Bearer token-1");
+    assert.equal(server.seen[0].headers["x-extra"], "extra");
+    assert.deepEqual(server.seen[0].body, {
+      name: "tjwater",
+      start_time: "2025-01-02T03:00:00+08:00",
+      duration: 60,
+    });
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.ok, true);
+    assert.match(payload.next_commands[0], /--end-time 2025-01-02T04:00:00\+08:00/);
+  } finally {
+    await server.close();
+  }
+});
+
+test("uses project scoped headers for realtime data commands", async () => {
+  const server = await startJsonServer([{ id: "P1" }]);
+  try {
+    const result = await runCli(
+      [
+        "--auth-stdin",
+        "data",
+        "timeseries",
+        "realtime",
+        "links",
+        "--start-time",
+        "2025-01-02T03:00:00+08:00",
+        "--end-time",
+        "2025-01-02T04:00:00+08:00",
+      ],
+      {
+        server: server.url,
+        accessToken: "token-2",
+        projectId: "project-1",
+      },
+    );
+
+    assert.equal(result.exitCode, 0, result.stderr);
+    assert.equal(server.seen[0].method, "GET");
+    assert.equal(
+      server.seen[0].url,
+      "/api/v1/realtime/links?start_time=2025-01-02T03%3A00%3A00%2B08%3A00&end_time=2025-01-02T04%3A00%3A00%2B08%3A00",
+    );
+    assert.equal(server.seen[0].headers.authorization, "Bearer token-2");
+    assert.equal(server.seen[0].headers["x-project-id"], "project-1");
+  } finally {
+    await server.close();
+  }
+});
+
+test("matches Python CLI backend request shape for every command and key variants", async () => {
+  const tempDir = await mkdtemp(join(tmpdir(), "tjwater-cli-parity-"));
+  try {
+    const burstFile = join(tempDir, "burst.json");
+    const valveFile = join(tempDir, "valve.json");
+    const pressureFile = join(tempDir, "pressure.json");
+    const flowFile = join(tempDir, "flow.json");
+    await writeFile(burstFile, JSON.stringify([{ id: "B1", size: 12.5 }]));
+    await writeFile(valveFile, JSON.stringify([{ valve: "V1", opening: 0.5 }]));
+    await writeFile(pressureFile, JSON.stringify({ burst_pressure: [1.1], normal_pressure: [2.2] }));
+    await writeFile(flowFile, JSON.stringify({ burst_flow: [3.3], normal_flow: [4.4] }));
+
+    const auth = {
+      access_token: "token",
+      network: "tjwater",
+      project_id: "project-1",
+      user_id: "user-1",
+      username: "alice",
+      headers: { "x-extra": "extra" },
+    };
+    const start = "2025-01-02T03:00:00+08:00";
+    const end = "2025-01-02T04:00:00+08:00";
+    const at = "2025-01-02T03:30:00+08:00";
+    const cases = [
+      ["network get-junction-properties", ["network", "get-junction-properties", "--junction", "J1"]],
+      ["network get-pipe-properties", ["network", "get-pipe-properties", "--pipe", "P1"]],
+      ["network get-all-pipes-properties", ["network", "get-all-pipes-properties"]],
+      ["network get-reservoir-properties", ["network", "get-reservoir-properties", "--reservoir", "R1"]],
+      ["network get-all-reservoirs-properties", ["network", "get-all-reservoirs-properties"]],
+      ["network get-tank-properties", ["network", "get-tank-properties", "--tank", "T1"]],
+      ["network get-all-tanks-properties", ["network", "get-all-tanks-properties"]],
+      ["network get-pump-properties", ["network", "get-pump-properties", "--pump", "PU1"]],
+      ["network get-all-pumps-properties", ["network", "get-all-pumps-properties"]],
+      ["network get-valve-properties", ["network", "get-valve-properties", "--valve", "V1"]],
+      ["network get-all-valves-properties", ["network", "get-all-valves-properties"]],
+      ["component option schema", ["component", "option", "schema", "--kind", "time"]],
+      ["component option get", ["component", "option", "get", "--kind", "pump-energy", "--pump", "P1"]],
+      ["simulation run", ["simulation", "run", "--start-time", start, "--duration", "60"]],
+      ["analysis burst", ["analysis", "burst", "--start-time", start, "--duration", "900", "--burst-file", burstFile, "--scheme", "burst_case"]],
+      ["analysis valve close", ["analysis", "valve", "--mode", "close", "--start-time", start, "--valve", "V1", "--valve", "V2", "--duration", "900", "--scheme", "valve_case"]],
+      ["analysis valve isolation", ["analysis", "valve", "--mode", "isolation", "--element", "E1", "--disabled-valve", "V3"]],
+      ["analysis flushing", ["analysis", "flushing", "--start-time", start, "--valve-setting-file", valveFile, "--drainage-node", "N1", "--flow", "100.5", "--duration", "900", "--scheme", "flush_case"]],
+      ["analysis age", ["analysis", "age", "--start-time", start, "--duration", "900"]],
+      ["analysis contaminant", ["analysis", "contaminant", "--start-time", start, "--duration", "900", "--source-node", "N1", "--concentration", "10.5", "--pattern", "P1", "--scheme", "contam_case"]],
+      ["analysis sensor-placement kmeans", ["analysis", "sensor-placement", "kmeans", "--count", "5", "--min-diameter", "100", "--scheme", "place_case"]],
+      ["analysis leakage identify", ["analysis", "leakage", "identify", "--start-time", start, "--end-time", end, "--scheme", "leak_case"]],
+      ["analysis leakage schemes list", ["analysis", "leakage", "schemes", "list"]],
+      ["analysis leakage schemes get", ["analysis", "leakage", "schemes", "get", "leak_case"]],
+      ["analysis burst-detection detect", ["analysis", "burst-detection", "detect", "--start-time", start, "--end-time", end, "--scheme", "detect_case"]],
+      ["analysis burst-detection schemes list", ["analysis", "burst-detection", "schemes", "list"]],
+      ["analysis burst-detection schemes get", ["analysis", "burst-detection", "schemes", "get", "detect_case"]],
+      ["analysis burst-location locate", ["analysis", "burst-location", "locate", "--start-time", start, "--end-time", end, "--burst-leakage", "50.5", "--scheme", "locate_case", "--data-source", "simulation", "--pressure-file", pressureFile, "--flow-file", flowFile, "--use-scada-flow"]],
+      ["analysis burst-location schemes list", ["analysis", "burst-location", "schemes", "list"]],
+      ["analysis burst-location schemes get", ["analysis", "burst-location", "schemes", "get", "locate_case"]],
+      ["analysis risk pipe-now", ["analysis", "risk", "pipe-now", "--pipe", "P1"]],
+      ["analysis risk pipe-history", ["analysis", "risk", "pipe-history", "--pipe", "P1"]],
+      ["analysis risk network", ["analysis", "risk", "network"]],
+      ["data realtime links", ["data", "timeseries", "realtime", "links", "--start-time", start, "--end-time", end]],
+      ["data realtime nodes", ["data", "timeseries", "realtime", "nodes", "--start-time", start, "--end-time", end]],
+      ["data realtime simulation-by-id-time", ["data", "timeseries", "realtime", "simulation-by-id-time", "--id", "J1", "--type", "junction", "--time", at]],
+      ["data realtime simulation-by-time-property", ["data", "timeseries", "realtime", "simulation-by-time-property", "--type", "pipe", "--time", at, "--property", "flow"]],
+      ["data scheme links", ["data", "timeseries", "scheme", "links", "--start-time", start, "--end-time", end, "--scheme", "scheme_case", "--scheme-type", "simulation"]],
+      ["data scheme node-field", ["data", "timeseries", "scheme", "node-field", "--node", "J1", "--field", "pressure", "--start-time", start, "--end-time", end, "--scheme", "scheme_case"]],
+      ["data scheme simulation by-id", ["data", "timeseries", "scheme", "simulation", "--query", "by-id-time", "--id", "J1", "--time", at, "--type", "junction", "--scheme", "scheme_case"]],
+      ["data scheme simulation by-property", ["data", "timeseries", "scheme", "simulation", "--query", "by-scheme-time-property", "--time", at, "--type", "pipe", "--property", "flow", "--scheme", "scheme_case"]],
+      ["data scada query", ["data", "timeseries", "scada", "query", "--device-id", "D1", "--device-id", "D2", "--start-time", start, "--end-time", end, "--field", "monitored_value"]],
+      ["data composite scada-simulation", ["data", "timeseries", "composite", "--kind", "scada-simulation", "--feature", "D1", "--feature", "D2", "--start-time", start, "--end-time", end, "--scheme", "scheme_case"]],
+      ["data composite element-simulation", ["data", "timeseries", "composite", "--kind", "element-simulation", "--feature", "J1:pressure", "--start-time", start, "--end-time", end]],
+      ["data composite element-scada", ["data", "timeseries", "composite", "--kind", "element-scada", "--feature", "J1", "--start-time", start, "--end-time", end, "--use-cleaned"]],
+      ["data composite pipeline-health", ["data", "timeseries", "composite", "pipeline-health", "--pipe", "P1", "--start-time", start, "--end-time", end]],
+      ["data scada get", ["data", "scada", "get", "--kind", "info", "--id", "SCADA-001"]],
+      ["data scada list", ["data", "scada", "list", "--kind", "info"]],
+      ["data scheme schema", ["data", "scheme", "schema"]],
+      ["data scheme get", ["data", "scheme", "get", "--name", "scheme_case"]],
+      ["data scheme list", ["data", "scheme", "list"]],
+    ];
+
+    for (const [name, args] of cases) {
+      const [nodeRun, pythonRun] = await Promise.all([
+        runAgainstServer(`${name} node`, runCli, args, auth),
+        runAgainstServer(`${name} python`, runPythonCli, args, auth),
+      ]);
+      assert.equal(nodeRun.exitCode, pythonRun.exitCode, `${name}: exit\nnode=${nodeRun.stderr}\npython=${pythonRun.stderr}`);
+      assert.deepEqual(nodeRun.requests, pythonRun.requests, name);
+    }
+  } finally {
+    await rm(tempDir, { force: true, recursive: true });
+  }
+});
@@ -8,6 +8,7 @@
    "install:opencode": "bun install --cwd .opencode",
    "typecheck": "tsc --noEmit -p tsconfig.json",
    "typecheck:opencode": "bun run --cwd .opencode typecheck",
+    "test:cli": "node --test node-tests/cli/*.node.mjs",
    "dev": "bun --watch src/server.ts",
    "build": "bun run check",
    "check": "bun run typecheck && bun run typecheck:opencode",
@@ -13,5 +13,5 @@
    "allowSyntheticDefaultImports": true,
    "types": ["node", "bun-types"]
  },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "cli/**/*.ts"]
 }