gangtise-openapi-cli 0.41.1 → 0.42.0

package/dist/src/commands/shared.js

@@ -0,0 +1,145 @@
+import { Option } from "commander";
+import { collectList, dateArg, datetimeArg, maybeArray, numberListArg, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize } from "../core/args.js";
+import { loadConfig } from "../core/config.js";
+import { releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
+import { ENDPOINTS } from "../core/endpoints.js";
+import { ValidationError } from "../core/errors.js";
+import { parseOutputFormat } from "../core/output.js";
+import { printData } from "../core/printer.js";
+import { ExportSink } from "../core/rowSink.js";
+export async function createClient(stream) {
+    const { GangtiseClient } = await import("../core/client.js");
+    const sink = stream?.output && (stream.format === "jsonl" || stream.format === "csv") ? new ExportSink(stream.output, stream.format, stream.cache) : undefined;
+    return new GangtiseClient(loadConfig(), sink);
+}
+export async function emit(options, produce, cache) {
+    const format = parseOutputFormat(options.format);
+    const client = await createClient({ format, output: options.output, cache });
+    try {
+        await printData(await produce(client), format, options.output, cache);
+    }
+    finally {
+        await client.rowSink?.abort();
+    }
+}
+export async function withClient(a, b) {
+    const [stream, fn] = typeof a === "function" ? [undefined, a] : [a, b];
+    const client = await createClient(stream);
+    try {
+        await fn(client);
+    }
+    finally {
+        await client.rowSink?.abort();
+    }
+}
+export const DEFAULT_QUOTE_LIMIT = 6000;
+export function flagIfLimitTruncated(data, cap, label, rangeFlags = "--start-date/--end-date", advice) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const rec = data;
+    if (rec.partial === true)
+        return;
+    if (Array.isArray(rec.list) && rec.list.length >= cap) {
+        rec.partial = true;
+        process.stderr.write(`[gangtise] warning: ${label} returned ${rec.list.length} rows = the ${cap}-row limit; results are likely truncated (this endpoint has no pagination). ${advice ?? `Narrow ${rangeFlags} or raise --limit (max 10000), fetching in date batches.`}\n`);
+    }
+}
+export async function runDownload(client, endpointKey, query, options) {
+    if (options.output) {
+        const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
+        await saveDownloadResult(result, options.fallbackName, options.output);
+        return;
+    }
+    const result = await client.call(endpointKey, options.body, query);
+    const resolved = options.resolveOutputPath ? await options.resolveOutputPath(result) : undefined;
+    const target = resolved ? await uniquePath(resolved) : undefined;
+    try {
+        await saveDownloadResult(result, options.fallbackName, target);
+    }
+    catch (error) {
+        if (target)
+            await releaseClaim(target);
+        throw error;
+    }
+}
+export function addDownloadCommand(parent, spec) {
+    const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`);
+    if (spec.fileType) {
+        const option = new Option("--file-type <number>", spec.fileType.description).choices(spec.fileType.choices);
+        cmd.addOption(spec.fileType.required ? option.makeOptionMandatory() : option.default(spec.fileType.default));
+    }
+    if (spec.contentTypeDescription)
+        cmd.requiredOption("--content-type <type>", spec.contentTypeDescription);
+    if (spec.titleListEndpoint) {
+        cmd.option("--resolve-title", "On a title-cache miss, query the list endpoint for a friendly filename (4 extra requests; most of these list endpoints bill per row). Without it the server filename or <prefix>-<id> is used. Ignored when --output is given");
+    }
+    cmd.option("--output <path>").action((options) => withClient(async (client) => {
+        const id = options[spec.idField];
+        const qp = { [spec.idField]: id };
+        if (spec.fileType && options.fileType)
+            qp.fileType = parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 });
+        if (spec.contentTypeDescription)
+            qp.contentType = options.contentType;
+        const titleList = spec.titleListEndpoint;
+        await runDownload(client, spec.endpointKey, qp, {
+            output: options.output,
+            fallbackName: `${spec.fallbackPrefix}-${id}`,
+            resolveOutputPath: titleList
+                ? (result) => resolveTitle(client, result, titleList, spec.idField, id, { allowLookup: Boolean(options.resolveTitle) })
+                : undefined,
+        });
+    }));
+}
+export function assertConfirmed(endpointKey, confirmed, target) {
+    const destructive = ENDPOINTS[endpointKey]?.destructive;
+    if (!destructive || confirmed)
+        return;
+    throw new ValidationError(`${destructive.warning} 确认要对 ${target} 执行就加上 --yes。`);
+}
+export const field = (option, body) => ({ option, body });
+export const value = (flags, description, key) => field(new Option(flags, description), (v) => ({ [key]: v }));
+export const required = (flags, description, key) => field(new Option(flags, description).makeOptionMandatory(), (v) => ({ [key]: v }));
+export const date = (flags, description, key, opts = {}) => {
+    const option = new Option(flags, description);
+    option.argParser(dateArg(option.long));
+    return field(opts.required ? option.makeOptionMandatory() : option, (v) => ({ [key]: v }));
+};
+export const list = (flags, description, key) => field(new Option(flags, description).argParser(collectList).default([]), (v) => ({ [key]: maybeArray(v) }));
+export const numberList = (flags, description, key) => {
+    const option = new Option(flags, description).default([]);
+    option.argParser(numberListArg(option.long));
+    return field(option, (v) => ({ [key]: v.length ? v : undefined }));
+};
+export const choiceList = (flags, description, key, choices) => {
+    const option = new Option(flags, description).argParser(collectList).default([]);
+    return field(option, (v) => ({ [key]: parseChoiceList(v, option.long, choices) }));
+};
+export const count = (flags, description, key) => {
+    const option = new Option(flags, description);
+    return field(option, (v) => ({ [key]: parseOptionalNumberOption(v, option.long, { integer: true, min: 0 }) }));
+};
+const numberEnum = (flags, description, key, choices, fallback) => {
+    const option = new Option(flags, description).choices(choices).default(fallback);
+    return field(option, (v) => ({ [key]: parseNumberOption(v, option.long, { integer: true, min: 1 }) }));
+};
+export const rankType = () => numberEnum("--rank-type <number>", "Rank type: 1=composite 2=time desc", "rankType", ["1", "2"], "1");
+export const searchType = () => numberEnum("--search-type <number>", "Search type: 1=title 2=fulltext", "searchType", ["1", "2"], "1");
+export const top = (max) => field(new Option("--top <number>", `Max results (default: 10, max: ${max})`).default("10"), (v) => ({ top: parseNumberOption(v, "--top", { integer: true, min: 1, max }) }));
+export const flag = (flags, description) => field(new Option(flags, description));
+export const format = (fallback = "table") => field(new Option("--format <format>", "Output format").default(fallback));
+export const output = (description) => field(new Option("--output <path>", description));
+export const from = () => field(new Option("--from <number>", "Starting offset").default("0"), (v) => ({ from: parseFrom(v) }));
+export const size = (description = "Total rows to return; omit to fetch all") => field(new Option("--size <number>", description), (v) => ({ size: parseSize(v) }));
+const asTyped = (v) => v;
+export const startTime = (description = "Start time", toBody = asTyped) => field(new Option("--start-time <datetime>", description).argParser(datetimeArg("--start-time")), (v) => ({ startTime: toBody(v, "--start-time") }));
+export const endTime = (description = "End time", toBody = asTyped) => field(new Option("--end-time <datetime>", description).argParser(datetimeArg("--end-time")), (v) => ({ endTime: toBody(v, "--end-time") }));
+export const timeFilters = (toBody = asTyped) => [from(), size(), startTime("Start time", toBody), endTime("End time", toBody), value("--keyword <keyword>", "Keyword", "keyword")];
+export const requestBody = (fields, options) => Object.assign({}, ...fields.map((f) => f.body?.(options[f.option.attributeName()]) ?? {}));
+export function query(parent, name, spec) {
+    const command = parent.command(name);
+    if (spec.description)
+        command.description(spec.description);
+    for (const f of spec.fields)
+        command.addOption(f.option);
+    return command.action((options) => emit(options, (client) => client.call(typeof spec.endpoint === "string" ? spec.endpoint : spec.endpoint(options), requestBody(spec.fields, options)), spec.cache));
+}

package/dist/src/commands/tool.js

@@ -0,0 +1,55 @@
+import { Command, Option } from "commander";
+import { POLL_MAX_ATTEMPTS } from "../core/asyncContent.js";
+import { collectList, maybeArray, parseNumberOption, parseOptionalNumberOption } from "../core/args.js";
+import { ValidationError } from "../core/errors.js";
+import { fetchFileParseResult, pollFileParseResult, submitFileParse } from "../core/fileParse.js";
+import { markFailed } from "../core/exitStatus.js";
+import { emit, withClient } from "./shared.js";
+export const tool = new Command("tool").description("Research tool APIs: PDF parsing");
+tool.command("file-parse").description("Parse a PDF into Markdown + images (async; 0.8 credits/page, billed at submit)")
+    .requiredOption("--file <path>", "PDF to upload (max 100MB / 500 pages)")
+    .option("--wait", "Wait for the parse to finish and save the result ZIP (blocking, up to ~5 min)")
+    .option("--output <path>", "Where to save the result ZIP (used with --wait)")
+    .action((options) => withClient(async (client) => {
+    const taskId = await submitFileParse(client, options.file);
+    if (!options.wait) {
+        process.stderr.write(`File parse task submitted. taskId: ${taskId}\n`);
+        process.stdout.write(`${JSON.stringify({ taskId, status: "pending", hint: `Run 'gangtise tool file-parse-check --task-id ${taskId}' in ~3 minutes to download the result ZIP` })}\n`);
+        return;
+    }
+    process.stderr.write(`Got taskId: ${taskId}, waiting for the parse to finish...\n`);
+    if (await pollFileParseResult(client, taskId, options.output) !== "ok") {
+        process.stderr.write(`Parse result not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise tool file-parse-check --task-id ${taskId}\n`);
+        markFailed();
+    }
+}));
+tool.command("file-parse-check").description("Download a finished file-parse result ZIP by taskId (free)")
+    .requiredOption("--task-id <id>", "taskId from 'tool file-parse'")
+    .option("--output <path>", "Where to save the result ZIP")
+    .action((options) => withClient(async (client) => {
+    if (await fetchFileParseResult(client, options.taskId, options.output) === "pending") {
+        process.stdout.write(`${JSON.stringify({ taskId: options.taskId, status: "pending", hint: "Parse not finished yet, retry in ~1 minute" })}\n`);
+    }
+}));
+tool.command("web-search").description("Search the public web for research: deduped, source-tiered (T0-T3) results with optional page content (1 credit/call)")
+    .requiredOption("--query <text>", "Search query, 1-200 chars. Sent verbatim — no intent rewriting server-side, so spell out what you want")
+    .option("--size <number>", "Results to return, 1-20 (1-5 with --include-content)", "10")
+    .addOption(new Option("--freshness <window>", "Time window over publishTime; results with no resolvable publish date are dropped by day/week/month").choices(["day", "week", "month", "none"]))
+    .addOption(new Option("--min-tier <tier>", "Lowest source tier to keep; T3 = no filtering").choices(["T0", "T1", "T2", "T3"]))
+    .option("--site <domain>", "Restrict to a registered domain or subdomain, e.g. csrc.gov.cn (repeatable, max 10, OR-ed)", collectList, [])
+    .option("--include-content", "Return page body as Markdown; caps --size at 5")
+    .option("--max-content-chars <number>", "Max chars per body, 1000-20000 (only with --include-content)")
+    .option("--format <format>", "Output format", "table").option("--output <path>")
+    .action((options) => emit(options, (client) => {
+    const size = parseNumberOption(options.size, "--size", { integer: true, min: 1, max: 20 });
+    if (options.includeContent && size > 5)
+        throw new ValidationError(`--size ${size} with --include-content: this endpoint caps size at 5 when page bodies are requested. Lower --size, or drop --include-content to fetch up to 20 snippets.`);
+    const sites = [...new Set(options.site)];
+    if (sites.length > 10)
+        throw new ValidationError(`--site takes at most 10 distinct domains, got ${sites.length}`);
+    return client.call("tool.web-search", {
+        query: options.query, size, freshness: options.freshness, minTier: options.minTier,
+        siteList: maybeArray(sites), includeContent: options.includeContent || undefined,
+        maxContentChars: parseOptionalNumberOption(options.maxContentChars, "--max-content-chars", { integer: true, min: 1000, max: 20000 }),
+    });
+}));

package/dist/src/commands/vault.js

@@ -0,0 +1,203 @@
+import { Command, Option } from "commander";
+import { collectList, datetimeArg } from "../core/args.js";
+import { buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "../core/commandBodies.js";
+import { uploadDriveFile } from "../core/driveUpload.js";
+import { flagFailedItems } from "../core/normalize.js";
+import { emit, addDownloadCommand, assertConfirmed, field, value, required, list, numberList, format, output, from, size, startTime, endTime, query } from "./shared.js";
+export const vault = new Command("vault").description("Vault APIs");
+query(vault, "drive-list", {
+    endpoint: "vault.drive.list",
+    cache: { endpointKey: "vault.drive.list", idField: "fileId" },
+    fields: [
+        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        numberList("--file-type <number>", "File type", "fileTypeList"),
+        numberList("--space-type <number>", "Space type", "spaceTypeList"),
+        format(), output(),
+    ],
+});
+addDownloadCommand(vault, { endpointKey: "vault.drive.download", name: "drive-download", idOption: "--file-id", idField: "fileId", fallbackPrefix: "file", titleListEndpoint: "vault.drive.list" });
+const driveSpaceOption = (help) => new Option("--space-type <n>", help).choices(["1", "2"]).default("1");
+const spaceType = (help) => field(driveSpaceOption(help), (v) => ({ spaceType: Number(v) }));
+query(vault, "drive-folder-list", {
+    description: "List the direct subfolders and files of a drive folder (free)",
+    endpoint: "vault.drive.folder-list",
+    fields: [
+        spaceType("Space: 1=my drive 2=tenant drive"),
+        value("--parent-id <id>", "Folder ID in that space; omit (or 'root') for the space's root. A folder of the other space is rejected with 100003", "parentId"),
+        format("json"), output(),
+    ],
+});
+vault.command("drive-upload").description("Upload a file to the AI drive (free; max 100MB per file; trial accounts max 500MB/day)")
+    .requiredOption("--file <path>", "File to upload")
+    .addOption(driveSpaceOption("Target space: 1=my drive 2=tenant drive (shared with your whole tenant)"))
+    .option("--folder-id <id>", "Target folder ID in that space; omit (or 'root') for the space's root")
+    .option("--title <name>", "Name in the drive, max 200 characters; defaults to the local file name")
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action((options) => emit(options, (client) => uploadDriveFile(client, options.file, { spaceType: Number(options.spaceType), folderId: options.folderId, title: options.title })));
+query(vault, "drive-create-folder", {
+    description: "Create a drive folder (free). Same-name folders are allowed, so re-running creates a second one",
+    endpoint: "vault.drive.create-folder",
+    fields: [
+        required("--name <name>", "Folder name, max 200 characters (230004 past that)", "folderName"),
+        spaceType("Space: 1=my drive 2=tenant drive (shared with your whole tenant)"),
+        value("--parent-id <id>", "Parent folder ID in that space; omit (or 'root') for the root", "parentId"),
+        format("json"), output(),
+    ],
+});
+query(vault, "drive-rename", {
+    description: "Rename a drive file or folder (free)",
+    endpoint: "vault.drive.rename",
+    fields: [
+        field(new Option("--type <type>", "What --id names").choices(["file", "folder"]).makeOptionMandatory(), (v) => ({ type: v })),
+        required("--id <id>", "File or folder ID", "id"),
+        required("--name <name>", "New name, max 200 characters", "name"),
+        format("json"), output(),
+    ],
+});
+vault.command("drive-move-file").description("Move drive files into a folder of the SAME space (free)")
+    .requiredOption("--file-id <id>", "File ID (repeat or comma-separate)", collectList)
+    .requiredOption("--target-folder-id <id>", "Destination folder ID, or 'root'. Files of the other space land in failList (空间不一致)")
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("vault.drive.move-file", { fileIdList: options.fileId, targetFolderId: options.targetFolderId });
+    flagFailedItems(data, "vault drive-move-file");
+    return data;
+}));
+query(vault, "drive-move-folder", {
+    description: "Move a drive folder under another folder of the SAME space (free)",
+    endpoint: "vault.drive.move-folder",
+    fields: [
+        required("--folder-id <id>", "Folder ID to move", "folderId"),
+        required("--target-parent-id <id>", "Destination parent folder ID, or 'root'. Not the folder itself, one of its subfolders, or the other space (230005)", "targetParentId"),
+        format("json"), output(),
+    ],
+});
+vault.command("drive-copy").description("Copy files to the OTHER space: my drive <-> tenant drive (free; same-space copies are rejected)")
+    .requiredOption("--file-id <id>", "Source file ID (repeat or comma-separate)", collectList)
+    .requiredOption("--target-folder-id <id>", "Destination folder ID in the other space, or 'root' for that space's root")
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("vault.drive.copy", { copyType: "file", fileIdList: options.fileId, targetFolderId: options.targetFolderId });
+    flagFailedItems(data, "vault drive-copy");
+    return data;
+}));
+vault.command("drive-delete-file").description("Delete drive files — irreversible (free)")
+    .requiredOption("--file-id <id>", "File ID to delete (repeat or comma-separate)", collectList)
+    .option("--yes", "Required: confirm the deletion")
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action(async (options) => {
+    assertConfirmed("vault.drive.delete-file", Boolean(options.yes), options.fileId.join("、"));
+    await emit(options, async (client) => {
+        const data = await client.call("vault.drive.delete-file", { fileIdList: options.fileId });
+        flagFailedItems(data, "vault drive-delete-file");
+        return data;
+    });
+});
+vault.command("drive-delete-folder").description("Delete a drive folder AND every subfolder and file inside it — irreversible (free)")
+    .requiredOption("--folder-id <id>", "Folder ID to delete")
+    .option("--yes", "Required: confirm the deletion")
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action(async (options) => {
+    assertConfirmed("vault.drive.delete-folder", Boolean(options.yes), options.folderId);
+    await emit(options, (client) => client.call("vault.drive.delete-folder", { folderId: options.folderId }));
+});
+query(vault, "record-list", {
+    endpoint: "vault.record.list",
+    cache: { endpointKey: "vault.record.list", idField: "recordId" },
+    fields: [
+        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        list("--category <name>", "Recording type: upload/link/mobile/gtNote/pc/share", "categoryList"),
+        numberList("--space-type <number>", "Space type: 1=my records / 2=tenant records", "spaceTypeList"),
+        format(), output(),
+    ],
+});
+addDownloadCommand(vault, { endpointKey: "vault.record.download", name: "record-download", idOption: "--record-id", idField: "recordId", fallbackPrefix: "record", contentTypeDescription: "Content type: original/asr/summary", titleListEndpoint: "vault.record.list" });
+query(vault, "my-conference-list", {
+    endpoint: "vault.my-conference.list",
+    cache: { endpointKey: "vault.my-conference.list", idField: "conferenceId" },
+    fields: [
+        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        list("--research-area <id>", "Research area ID: citicIndustry code (1008001xx) or gangtiseIndustry direction code (122000xxx: macro/strategy/fixed-income/quant/overseas). swIndustry (104xx0000) returns 0 here", "researchAreaList"),
+        list("--security <code>", "Security code", "securityList"),
+        list("--institution <id>", "Institution ID", "institutionList"),
+        list("--category <name>", "Conference category: earningsCall/strategyMeeting/fundRoadshow/shareholdersMeeting/maMeeting/specialMeeting/companyAnalysis/industryAnalysis/other", "categoryList"),
+        numberList("--source <number>", "Recording source: 1=企微会议助理 2=会议服务微信群 (repeat)", "sourceList"),
+        format(), output(),
+    ],
+});
+addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "my-conference-download", idOption: "--conference-id", idField: "conferenceId", fallbackPrefix: "conference", contentTypeDescription: "Content type: asr/summary", titleListEndpoint: "vault.my-conference.list" });
+vault.command("wechat-message-list")
+    .option("--from <number>", "Starting offset", "0")
+    .option("--size <number>", "Total rows to return; omit to fetch all")
+    .option("--start-time <datetime>", "Start time", datetimeArg("--start-time"))
+    .option("--end-time <datetime>", "End time", datetimeArg("--end-time"))
+    .option("--keyword <text>")
+    .option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, [])
+    .option("--wechat-group-id <id>", "WeChat group ID", collectList, [])
+    .option("--industry <id>", "Industry ID -- citicIndustry codes (1008001xx) only; swIndustry codes and unknown values are rejected with 100005", collectList, [])
+    .option("--category <name>", "Message type: text/image/documents/url", collectList, [])
+    .option("--tag <name>", "Tag: roadShow/research/strategyMeeting/meetingSummary/industryComment/companyComment/earningsReview", collectList, [])
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, (client) => client.call("vault.wechat-message.list", buildWechatMessageListBody(options))));
+vault.command("wechat-chatroom-list")
+    .option("--from <number>", "Starting offset", "0")
+    .option("--size <number>", "Total rows to return; omit to fetch all")
+    .option("--room-name <name>", "WeChat group name; repeat or comma-separate for multiple names", collectList, [])
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, (client) => client.call("vault.wechat-chatroom.list", buildWechatChatroomListBody(options))));
+query(vault, "stock-pool-list", { endpoint: "vault.stock-pool.list", fields: [format(), output()] });
+vault.command("stock-pool-stocks")
+    .option("--pool-id <id>", "Pool ID; repeat for multiple; omit (or 'all') for all pools", collectList)
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, (client) => client.call("vault.stock-pool.stocks", buildStockPoolStocksBody(options))));
+query(vault, "stock-pool-create", {
+    endpoint: "vault.stock-pool.create",
+    fields: [
+        required("--name <name>", "New pool name; max 10 characters (a CJK character counts as 1) and must differ from every existing pool name. A duplicate is rejected with 230006, an over-long name with 230007. Max 30 pools per account (230003)", "poolName"),
+        format(), output(),
+    ],
+});
+query(vault, "stock-pool-rename", {
+    endpoint: "vault.stock-pool.rename",
+    fields: [
+        required("--pool-id <id>", "Pool ID from 'stock-pool-list'", "poolId"),
+        required("--name <name>", "New pool name; same rules as stock-pool-create (max 10 characters, must differ from every existing pool name). Renaming a pool to its own current name succeeds", "poolName"),
+        format(), output(),
+    ],
+});
+vault.command("stock-pool-add-stock")
+    .requiredOption("--pool-id <id>", "Target pool ID from 'stock-pool-list'")
+    .requiredOption("--security <code>", "Security code, e.g. 600519.SH (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("vault.stock-pool.add-stock", { poolId: options.poolId, securityCodeList: options.security });
+    flagFailedItems(data, "vault stock-pool-add-stock");
+    return data;
+}));
+vault.command("stock-pool-remove-stock")
+    .requiredOption("--pool-id <id>", "Target pool ID from 'stock-pool-list'")
+    .requiredOption("--security <code>", "Security code, e.g. 600519.SH (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("vault.stock-pool.remove-stock", { poolId: options.poolId, securityCodeList: options.security });
+    flagFailedItems(data, "vault stock-pool-remove-stock");
+    return data;
+}));
+vault.command("stock-pool-delete")
+    .requiredOption("--pool-id <id>", "Pool ID to delete; repeat or comma-separate for multiple", collectList)
+    .option("--yes", "Required: confirm the deletion")
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action(async (options) => {
+    assertConfirmed("vault.stock-pool.delete", Boolean(options.yes), options.poolId.join("、"));
+    await emit(options, async (client) => {
+        const data = await client.call("vault.stock-pool.delete", { poolIdList: options.poolId });
+        flagFailedItems(data, "vault stock-pool-delete");
+        return data;
+    });
+});

package/dist/src/core/args.js

@@ -16,11 +16,14 @@ export function parseNumberOption(value, optionName, config = {}) {
     if (value === undefined || String(value).trim() === "") {
         throw new ValidationError(`Invalid ${optionName}: expected a number`);
     }
+    if (typeof value === "string" && !(config.integer ? /^-?\d+$/ : /^-?\d+(\.\d+)?$/).test(value.trim())) {
+        throw new ValidationError(`Invalid ${optionName}: expected ${config.integer ? "an integer" : "a number"} written in plain decimal, got '${value}'`);
+    }
     const parsed = typeof value === "number" ? value : Number(value);
     if (!Number.isFinite(parsed)) {
         throw new ValidationError(`Invalid ${optionName}: expected a finite number`);
     }
-    if (config.integer && !Number.isInteger(parsed)) {
+    if (config.integer && !Number.isSafeInteger(parsed)) {
         throw new ValidationError(`Invalid ${optionName}: expected an integer`);
     }
     if (config.min !== undefined && parsed < config.min) {
@@ -40,10 +43,10 @@ export function parseFrom(value) {
 export function parseSize(value) {
     return parseOptionalNumberOption(value, "--size", { integer: true, min: 1 });
 }
-export function collectNumberList(value, previous = []) {
-    return [
+export function numberListArg(optionName) {
+    return (value, previous = []) => [
         ...previous,
-        ...splitCsv(value).map((item) => parseNumberOption(item, "number list item")),
+        ...splitCsv(value).map((item) => parseNumberOption(item, optionName, { integer: true })),
     ];
 }
 export function collectKeyValue(value, previous = {}) {

package/dist/src/core/asyncContent.js

@@ -1,6 +1,7 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
 import { isTransientError } from "./transport.js";
+import { markFailed } from "./exitStatus.js";
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
 const POLL_MAX_DELAY_MS = 30_000;
@@ -24,34 +25,46 @@ function terminalFailureLine(error) {
     return `Content generation failed (terminal${code})${trace}${detail}\n`
         + "This dataId is final — re-checking it will not change. Resubmitting the generation task bills again for the same result; change the parameters first.\n";
 }
+export async function pollUntilDone(attempt, notReady) {
+    for (let n = 1; n <= POLL_MAX_ATTEMPTS; n++) {
+        try {
+            const state = await attempt();
+            if (state !== "pending")
+                return state;
+        }
+        catch (error) {
+            if (!isTransientError(error))
+                throw error;
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Attempt ${n}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
+        }
+        if (n < POLL_MAX_ATTEMPTS) {
+            const delay = nextPollDelayMs(n);
+            process.stderr.write(`Attempt ${n}/${POLL_MAX_ATTEMPTS}: ${notReady}, retrying in ${Math.round(delay / 1000)}s...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    return "timeout";
+}
 export async function pollAsyncContent(client, getContentEndpoint, dataId, format, output) {
-    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+    return pollUntilDone(async () => {
         try {
             const result = await client.call(getContentEndpoint, { dataId });
-            if (result?.content != null) {
-                await printData(result, format, output);
-                return "ok";
-            }
+            if (result?.content == null)
+                return "pending";
+            await printData(result, format, output);
+            return "ok";
         }
         catch (error) {
             if (isAsyncFailed(error)) {
                 process.stderr.write(terminalFailureLine(error));
                 return "failed";
             }
-            if (!isAsyncPending(error)) {
-                if (!isTransientError(error))
-                    throw error;
-                const msg = error instanceof Error ? error.message : String(error);
-                process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
-            }
-        }
-        if (attempt < POLL_MAX_ATTEMPTS) {
-            const delay = nextPollDelayMs(attempt);
-            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
-            await new Promise(resolve => setTimeout(resolve, delay));
+            if (isAsyncPending(error))
+                return "pending";
+            throw error;
         }
-    }
-    return "timeout";
+    }, "content not ready");
 }
 export async function checkAsyncContent(client, getContentEndpoint, dataId, format, output) {
     try {
@@ -64,7 +77,7 @@ export async function checkAsyncContent(client, getContentEndpoint, dataId, form
     catch (error) {
         if (isAsyncFailed(error)) {
             process.stderr.write(terminalFailureLine(error));
-            process.exitCode = 1;
+            markFailed();
             return;
         }
         if (!isAsyncPending(error))

package/dist/src/core/client.js

@@ -10,7 +10,13 @@ import { getLookupData } from "./lookupData/index.js";
 import { stagingPath } from "./output.js";
 import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, quoteBigIntFields, runInOrder, withRetry } from "./transport.js";
 import { attachRowSink } from "./rowSink.js";
+import { markIncomplete } from "./exitStatus.js";
 const AUTH_RETRY_CODES = new Set(["8000014", "8000015", "0000001008", "999002"]);
+function hasExpectedShape(expects, payload) {
+    if (expects === "array")
+        return Array.isArray(payload);
+    return Boolean(payload && typeof payload === "object" && Array.isArray(payload.list));
+}
 export class GangtiseClient {
     config;
     rowSink;
@@ -170,7 +176,7 @@ export class GangtiseClient {
         });
         if (!this.isPaginatedListResponse(firstPage)) {
             process.stderr.write(`[gangtise] warning: ${endpoint.key} is marked paginated but the first page has an unexpected shape (no numeric total + list); returning it as-is\n`);
-            process.exitCode = 3;
+            markIncomplete();
             return firstPage;
         }
         const total = firstPage.total;
@@ -276,7 +282,7 @@ export class GangtiseClient {
                 failedPages.push(req);
                 return [];
             }
-        }, (list) => keep(list));
+        }, (list) => keep(list), PAGE_CONCURRENCY * 4);
         if (unexpectedShape) {
             process.stderr.write(`[gangtise] warning: a page response had unexpected shape; its rows are missing (counted in failedPages)\n`);
         }
@@ -393,8 +399,9 @@ export class GangtiseClient {
                     this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                 }
                 const payload = this.unwrapEnvelope(parsed, response.statusCode, retryAfterMs);
-                if (endpoint.expects === "list" && !(payload && typeof payload === "object" && Array.isArray(payload.list))) {
-                    throw markStructural(new ApiError(`${endpoint.key} returned no list payload (got ${payload === null ? "null" : Array.isArray(payload) ? "an array" : typeof payload}) — the response layout may have changed`, undefined, response.statusCode, parsed));
+                if (endpoint.expects && !hasExpectedShape(endpoint.expects, payload)) {
+                    const got = payload === null ? "null" : Array.isArray(payload) ? "an array" : typeof payload;
+                    throw markStructural(new ApiError(`${endpoint.key} returned no ${endpoint.expects} payload (got ${got}) — the response layout may have changed`, undefined, response.statusCode, parsed));
                 }
                 return payload;
             }

package/dist/src/core/config.js

@@ -3,15 +3,28 @@ import path from "node:path";
 export const DEFAULT_BASE_URL = "https://openapi.gangtise.com";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_TOKEN_CACHE_PATH = path.join(os.homedir(), ".config", "gangtise", "token.json");
+let timeoutWarned = false;
 export function loadConfig() {
-    const timeoutValue = process.env.GANGTISE_TIMEOUT_MS;
-    const timeoutMs = timeoutValue ? Number(timeoutValue) : DEFAULT_TIMEOUT_MS;
+    const rawTimeout = process.env.GANGTISE_TIMEOUT_MS?.trim();
+    const timeoutMs = resolveTimeoutEnv(rawTimeout);
+    if (rawTimeout && Number(rawTimeout) !== timeoutMs && !timeoutWarned) {
+        timeoutWarned = true;
+        process.stderr.write(`[gangtise] warning: GANGTISE_TIMEOUT_MS=${rawTimeout} is not in effect, using ${timeoutMs} ms: expected whole milliseconds from ${MIN_TIMEOUT_MS} to ${MAX_TIMEOUT_MS}\n`);
+    }
     return {
         baseUrl: process.env.GANGTISE_BASE_URL ?? DEFAULT_BASE_URL,
-        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS,
+        timeoutMs,
         accessKey: process.env.GANGTISE_ACCESS_KEY,
         secretKey: process.env.GANGTISE_SECRET_KEY,
         token: process.env.GANGTISE_TOKEN,
         tokenCachePath: process.env.GANGTISE_TOKEN_CACHE_PATH ?? DEFAULT_TOKEN_CACHE_PATH,
     };
 }
+export const MIN_TIMEOUT_MS = 1_000;
+export const MAX_TIMEOUT_MS = 3_600_000;
+export function resolveTimeoutEnv(raw) {
+    if (!raw || !/^\d+$/.test(raw.trim()))
+        return DEFAULT_TIMEOUT_MS;
+    const ms = Number(raw);
+    return ms < MIN_TIMEOUT_MS ? DEFAULT_TIMEOUT_MS : Math.min(MAX_TIMEOUT_MS, ms);
+}

package/dist/src/core/endpoints.js

@@ -41,6 +41,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Get domestic chief opinion bodies by ID (max 20 IDs per call)",
         retry: "no-replay",
+        expects: "array",
     },
     "insight.summary.list": {
         method: "POST",
@@ -198,6 +199,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Get foreign opinion bodies by ID (max 20 IDs per call)",
         retry: "no-replay",
+        expects: "array",
     },
     "insight.independent-opinion.list": {
         method: "POST",
@@ -433,6 +435,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-fundamental/valuation-analysis",
         kind: "json",
         description: "Query valuation analysis",
+        expects: "list",
     },
     "fundamental.top-holders": {
         method: "POST",

package/dist/src/core/exitStatus.js

@@ -0,0 +1,17 @@
+export const EXIT_FAILED = 1;
+export const EXIT_INCOMPLETE = 3;
+export const EXIT_SUPERSEDED = 4;
+export function markFailed() {
+    process.exitCode = EXIT_FAILED;
+}
+export function markIncomplete() {
+    if (process.exitCode !== EXIT_FAILED)
+        process.exitCode = EXIT_INCOMPLETE;
+}
+export function markSuperseded() {
+    if (process.exitCode !== EXIT_FAILED && process.exitCode !== EXIT_INCOMPLETE)
+        process.exitCode = EXIT_SUPERSEDED;
+}
+export function decidedExitCode() {
+    return Number(process.exitCode ?? 0);
+}