gangtise-openapi-cli 0.38.0 → 0.40.0

package/dist/src/core/normalize.js

@@ -35,6 +35,22 @@ export function flagMissingFields(data, requested, label) {
     rec.missingFields = missing;
     process.stderr.write(`[gangtise] warning: ${label} returned no column for ${missing.join(", ")} — the server drops a field name it does not recognise (or no longer serves) without an error. Check the name against references/fields.md; result marked partial (exit 3).\n`);
 }
+export function flagFailedItems(data, label) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const rec = data;
+    if (!Array.isArray(rec.failList) || rec.failList.length === 0)
+        return;
+    rec.partial = true;
+    const detail = rec.failList.map((item) => {
+        if (!item || typeof item !== "object")
+            return String(item);
+        const entry = item;
+        const id = entry.securityCode ?? entry.poolId ?? JSON.stringify(entry);
+        return entry.failReason ? `${String(id)}（${String(entry.failReason)}）` : String(id);
+    }).join("、");
+    process.stderr.write(`[gangtise] warning: ${label} — ${rec.failList.length} item(s) failed while the request itself succeeded: ${detail}. Result marked partial (exit 3).\n`);
+}
 export function assertColumnarHeader(fields, source) {
     if (!fields) {
         throw new ValidationError(`响应包含数组形式的行但没有 fieldList，无法确定各列的含义，已拒绝输出。这是上游响应结构异常，请报障${traceSuffix(source)}。`);

package/dist/src/core/output.js

@@ -1,6 +1,26 @@
+import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import { ConfigError } from "./errors.js";
 const OUTPUT_FORMATS = ["table", "json", "jsonl", "csv", "markdown"];
+export function stagingPath(target, suffix = "part") {
+    return `${target}.${randomBytes(4).toString("hex")}.${suffix}`;
+}
+export function digestBuffer(content) {
+    const buf = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+    return { bytes: buf.byteLength, sha256: createHash("sha256").update(buf).digest("hex") };
+}
+export async function digestFile(filePath) {
+    const { createReadStream } = await import("node:fs");
+    const hash = createHash("sha256");
+    let bytes = 0;
+    const stream = createReadStream(filePath);
+    for await (const chunk of stream) {
+        const buf = chunk;
+        bytes += buf.byteLength;
+        hash.update(buf);
+    }
+    return { bytes, sha256: hash.digest("hex") };
+}
 export function parseOutputFormat(value) {
     const format = value ?? "table";
     if (OUTPUT_FORMATS.includes(format)) {
@@ -128,24 +148,24 @@ export function renderOutput(value, format) {
 }
 export async function streamOutputToFile(value, format, outputPath) {
     if (format !== "jsonl" && format !== "csv")
-        return false;
+        return null;
     const list = pickList(value);
     if (!list)
-        return false;
+        return null;
     if (list.length < 1000)
-        return false;
+        return null;
     let csvRows = [];
     let csvColumns = [];
     if (format === "csv") {
         csvRows = list.filter((row) => Boolean(row && typeof row === "object" && !Array.isArray(row)));
         if (csvRows.length === 0)
-            return false;
+            return null;
         csvColumns = Array.from(new Set(csvRows.flatMap((row) => Object.keys(row))));
     }
     const { dirname } = await import("node:path");
     const { createWriteStream } = await import("node:fs");
     await fs.mkdir(dirname(outputPath), { recursive: true });
-    const partPath = `${outputPath}.part`;
+    const partPath = stagingPath(outputPath);
     const stream = createWriteStream(partPath, { encoding: "utf8" });
     stream.on("error", () => { });
     try {
@@ -164,7 +184,9 @@ export async function streamOutputToFile(value, format, outputPath) {
         await new Promise((resolve, reject) => {
             stream.end((err) => err ? reject(err) : resolve());
         });
+        const digest = await digestFile(partPath);
         await fs.rename(partPath, outputPath);
+        return digest;
     }
     catch (error) {
         stream.destroy();
@@ -174,7 +196,6 @@ export async function streamOutputToFile(value, format, outputPath) {
         await fs.unlink(partPath).catch(() => { });
         throw error;
     }
-    return true;
 }
 export function pickList(value) {
     if (Array.isArray(value))
@@ -213,7 +234,7 @@ export async function saveOutputIfNeeded(content, outputPath) {
     }
     const { dirname } = await import("node:path");
     await fs.mkdir(dirname(outputPath), { recursive: true });
-    const partPath = `${outputPath}.part`;
+    const partPath = stagingPath(outputPath);
     try {
         if (typeof content === "string") {
             await fs.writeFile(partPath, content, "utf8");
@@ -221,7 +242,9 @@ export async function saveOutputIfNeeded(content, outputPath) {
         else {
             await fs.writeFile(partPath, content);
         }
+        const digest = digestBuffer(content);
         await fs.rename(partPath, outputPath);
+        return digest;
     }
     catch (error) {
         await fs.unlink(partPath).catch(() => { });

package/dist/src/core/printer.js

@@ -1,11 +1,21 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeRows } from "./normalize.js";
-import { countOutputRows, pickList, renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
+import { countOutputRows, digestFile, pickList, renderOutput, saveOutputIfNeeded, stagingPath, streamOutputToFile } from "./output.js";
 import { getRowSink } from "./rowSink.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
 import { CLI_VERSION } from "../version.js";
 const LARGE_RESULT_ROWS = 50_000;
+export const SUPERSEDED_EXIT = 4;
+export async function warnIfSuperseded(output, digest) {
+    const actual = await digestFile(output).catch(() => undefined);
+    if (!actual || actual.sha256 === digest.sha256)
+        return;
+    process.stderr.write(`[gangtise] warning: ${output} was replaced by another export to the same path while this one was finishing — the file there is not this command's output `
+        + `(wrote sha256 ${digest.sha256.slice(0, 12)}…, found ${actual.sha256.slice(0, 12)}…). Give concurrent exports distinct --output paths.\n`);
+    if (process.exitCode !== 3)
+        process.exitCode = SUPERSEDED_EXIT;
+}
 function warnIfLargeInMemory(items, format) {
     if (items && items.length >= LARGE_RESULT_ROWS) {
         process.stderr.write(`[gangtise] note: ${items.length} rows in '${format}' is built entirely in memory; stream large exports to a file with --format jsonl --output <path> (or csv).\n`);
@@ -62,7 +72,7 @@ async function stageExportMeta(output, format, rows, columns, normalized, comple
         result: redactSecrets(result),
     };
     const metaPath = `${output}.meta.json`;
-    const partPath = `${metaPath}.part`;
+    const partPath = stagingPath(metaPath);
     await fs.mkdir(path.dirname(output), { recursive: true });
     try {
         await fs.writeFile(partPath, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
@@ -72,8 +82,10 @@ async function stageExportMeta(output, format, rows, columns, normalized, comple
         throw error;
     }
     return {
-        async commit() {
+        async commit(digest) {
             try {
+                if (digest)
+                    await fs.writeFile(partPath, `${JSON.stringify({ ...doc, ...digest }, null, 2)}\n`, "utf8");
                 await fs.rename(partPath, metaPath);
             }
             catch (error) {
@@ -118,21 +130,25 @@ export async function printData(data, format, output, cache) {
         const staged = format === "csv" || format === "jsonl"
             ? await stageExportMeta(output, format, streamed ? streamed.dataRows : countOutputRows(normalized, format), columns, normalized, complete)
             : null;
+        let digest;
         try {
             if (streamed) {
                 await streamed.finish();
+                digest = streamed.digest;
             }
-            else if (!(await streamOutputToFile(normalized, format, output))) {
+            else if (!(digest = (await streamOutputToFile(normalized, format, output)) ?? undefined)) {
                 warnIfLargeInMemory(items, format);
                 const content = renderOutput(normalized, format);
-                await saveOutputIfNeeded(format === "csv" ? `\ufeff${content}` : content, output);
+                digest = await saveOutputIfNeeded(format === "csv" ? `\ufeff${content}` : content, output);
             }
         }
         catch (error) {
             await staged?.discard();
             throw error;
         }
-        await staged?.commit();
+        await staged?.commit(digest);
+        if (digest)
+            await warnIfSuperseded(output, digest);
         process.stdout.write(`${output}\n`);
         return;
     }

package/dist/src/core/quoteSharding.js

@@ -16,8 +16,10 @@ function formatDate(d) {
     return d.toISOString().slice(0, 10);
 }
 function columnRemap(header, shard) {
+    const headerNames = new Set(header.map(String));
+    const extra = shard.map(String).filter((field) => !headerNames.has(field));
     if (header.length === shard.length && header.every((field, i) => field === shard[i]))
-        return null;
+        return { map: null, extra };
     const index = new Map(shard.map((field, i) => [String(field), i]));
     const map = [];
     for (const field of header) {
@@ -26,7 +28,7 @@ function columnRemap(header, shard) {
             return undefined;
         map.push(i);
     }
-    return map;
+    return { map, extra };
 }
 export function isFullMarket(body, fullMarketValue) {
     const list = body.securityList;
@@ -126,6 +128,7 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     const objectKeys = new Set();
     const truncatedShards = [];
     const partialShards = [];
+    const droppedColumns = new Set();
     const keep = async (rows) => {
         count += rows.length;
         if (!fieldList)
@@ -179,8 +182,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
             process.stderr.write(`[gangtise] warning: shard ${shards[i].startDate}..${shards[i].endDate} returned columns that cannot be aligned with the first shard's fieldList; its rows were dropped (see failedShards)\n`);
             return;
         }
+        for (const field of remap?.extra ?? [])
+            droppedColumns.add(field);
         const rows = rec.list;
-        await keep(remap ? rows.map((item) => (Array.isArray(item) ? remap.map((k) => item[k]) : item)) : rows);
+        const map = remap?.map;
+        await keep(map ? rows.map((item) => (Array.isArray(item) ? map.map((k) => item[k]) : item)) : rows);
     };
     await runInOrder(shards, config.concurrency ?? PAGE_CONCURRENCY, fetchShard, mergeShard);
     if (failedShards.length === shards.length) {
@@ -211,6 +217,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         out.partial = true;
         process.stderr.write(`[gangtise] warning: ${partialShards.length}/${shards.length} shard(s) reported themselves partial; the merged result is marked partial\n`);
     }
+    if (droppedColumns.size > 0) {
+        out.partial = true;
+        out.droppedColumns = [...droppedColumns];
+        process.stderr.write(`[gangtise] warning: ${droppedColumns.size} column(s) came back only in later shards and could not be carried (see droppedColumns); the merged fieldList is the first data shard's — re-pull a narrower range to get them.\n`);
+    }
     if (truncatedShards.length > 0) {
         out.partial = true;
         out.truncatedShards = truncatedShards;

package/dist/src/core/rowSink.js

@@ -2,7 +2,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertColumnarHeader, zipFieldRow } from "./normalize.js";
-import { csvEscape, formatScalar, writeLine } from "./output.js";
+import { csvEscape, digestFile, formatScalar, stagingPath, writeLine } from "./output.js";
 import { extractTitles, MAX_TITLES_PER_ENDPOINT } from "./titleCache.js";
 export const ROW_SINK = Symbol("gangtise.rowSink");
 const STREAM_THRESHOLD = 1000;
@@ -11,6 +11,7 @@ export class ExportSink {
     format;
     cache;
     rows = 0;
+    digest;
     titles = {};
     titleCount = 0;
     buffer = [];
@@ -21,10 +22,14 @@ export class ExportSink {
     columns = [];
     columnSet = new Set();
     objectRows = 0;
+    partPath;
+    rowsPath;
     constructor(outputPath, format = "jsonl", cache) {
         this.outputPath = outputPath;
         this.format = format;
         this.cache = cache;
+        this.partPath = stagingPath(outputPath);
+        this.rowsPath = stagingPath(outputPath, "rows.part");
     }
     get opened() {
         return this.stream !== null;
@@ -37,12 +42,6 @@ export class ExportSink {
             return this.rows;
         return this.objectRows > 0 ? this.objectRows : this.rows;
     }
-    get partPath() {
-        return `${this.outputPath}.part`;
-    }
-    get rowsPath() {
-        return `${this.outputPath}.rows.part`;
-    }
     setFieldList(fields) {
         this.fields = fields;
     }
@@ -73,6 +72,7 @@ export class ExportSink {
             await endStream(stream);
             if (this.format === "csv")
                 await this.assembleCsv();
+            this.digest = await digestFile(this.partPath);
             await fs.rename(this.partPath, this.outputPath);
             this.finished = true;
         }

package/dist/src/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.38.0";
+export const CLI_VERSION = "0.40.0";

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.38.0"
+version: "0.40.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -39,7 +39,7 @@ description: |-
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
 10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）。上游对不存在的字段名有两种处理：`quote` 系（realtime / day-kline / minute-kline / fund-flow）名和值一起丢、不报错——CLI 比对请求与返回的列名，缺列标 `partial` + `missingFields` 并退出 3；`fundamental main-business` / `valuation-analysis` 只丢值、字段名照请求回显——CLI 检测到长度不匹配直接报错退出 1（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时带上报错末尾的 `（trace …）`）。`--field` 只回点名的列、不自动附带身份列（`fund-flow` 除外）：日 K 要一起写进 `securityCode` / `tradeDate`，分钟 K 是 `securityCode` / `tradeTime`，实时行情是 `securityCode`。realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，A/港/美股均有数）。
-11. 🔴 **EDE 取不到数时返 `null` 占位，行列都保留**（`indicator` 截面 / 时序 / 选股），无告警、退出码 0。**报告期类指标（`is_*` 等）的时序尤其要当心**：按日返回，**只有报告期末那几行是真值**，其余全是 `null`，而时序没有任何参数能只返回报告期末——**别对整列直接求均值 / 求和**（`null` 会被 Excel / pandas / SQL 的聚合跳过但行数不变；`jq` 的 `add/length` 连跳都不跳，要先 `map(select(. != null))`）。截面上日期不落在报告期末时整批返 `null`，`screener` 会筛出空集——**那是日期用错了，不是「没有符合条件的标的」**。所以：报告期类指标的日期一律落**报告期末**（`03-31` / `06-30` / `09-30` / `12-31`），截面用 `--indicator-param "<指标code>:reportDate=YYYY-MM-DD"` 显式给（`screener` 用 `"F1:reportDate=..."`）。详见 `references/commands/indicator.md`。
+11. 🔴 **EDE 取不到数时返 `null` 占位，行列都保留**（`indicator` 截面 / 时序 / 选股），无告警、退出码 0。**报告期类指标（`is_*` 等）的时序尤其要当心**：按日返回，**只有报告期末那几行是真值**，其余全是 `null`，而时序没有任何参数能只返回报告期末——**别对整列直接求均值 / 求和**（`null` 会被 Excel / pandas / SQL 的聚合跳过但行数不变；`jq` 的 `add/length` 连跳都不跳，要先 `map(select(. != null))`）。截面上日期不落在报告期末时整批返 `null`，`screener` 会筛出空集——**那是日期用错了，不是「没有符合条件的标的」**。所以：报告期类指标的日期一律落**报告期末**（`03-31` / `06-30` / `09-30` / `12-31`），截面用 `--indicator-param "<指标code>:reportDate=YYYY-MM-DD"` 显式给（`screener` 用 `"F1:reportDate=..."`）。🔴 **时序的日历别手动传错**：报告期末常落在非交易日（2024-03-31 / 06-30 都是周日），`--calendar-type TD` 的日期轴里没有那一列，报告期类指标会整行全 `null` 且退出 0。**不传 `--calendar-type` 时 CLI 会自动选**（用免费的 `indicator search` 读 `parameterList`，去重后每个指标码各查一次：全是交易日类指标才发 `TD`，只要有一个报告期类的就走 `ND`，拿不准也走 `ND`），所以**默认不传是安全的**；显式传了就完全按你给的发。详见 `references/commands/indicator.md`。
 
 ## 工作流（3 步）
 
@@ -56,6 +56,7 @@ description: |-
 - **高积分操作先确认**：任何 50 积分/次及以上、或"按条 × 大批量"（如 `stock-summary` 按代码批量数千只、`opinion` 全量翻页、`concept-info` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费速查」）
 - 下载**必选**格式未定才问：`independent-opinion --file-type`（必选）、`vault record/my-conference --content-type`（record 三种 original/asr/summary、my-conference 两种 asr/summary）；其余 download 有默认（多为 `1`=PDF/原始），用户没提格式就用默认、不必问
 - list→download 用户没指定具体文件 → 展示前 10 条让用户挑
+- 🔴 **改动账号数据的命令**：`vault stock-pool-create` / `stock-pool-rename` / `stock-pool-add-stock` / `stock-pool-remove-stock` / `stock-pool-delete` 写的是用户自己的自选股股票池，是这套 CLI 里仅有的写操作。用户没有明确要求「建池 / 改名 / 加自选 / 删自选 / 删池」时**不要调用**；要调用时先复述「往哪个池、加或删哪几只」再执行。`stock-pool-delete` 会连带清掉池内全部关注关系且不可恢复，CLI 因此要求显式 `--yes`——**这个 `--yes` 必须是用户点头之后才加，看到「加上 --yes」的报错不要自动补上重跑**
 
 🟡 **自行判断**：
 - 公司名 → 先速查表，否则 `reference securities-search`
@@ -80,7 +81,7 @@ description: |-
 - 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
 - ✅ **按篇 / 按条计费的接口，没查到内容就不扣分**（空结果 = 0 积分）：各 download（`pamirs-summary` 除外，见 ②）、`ai hot-topic`（50/篇）、`ai stock-summary`（3/条，无看点总结的个股不进返回列表也不计费）。**所以「先小范围试探再放大」是安全的**——先用窄条件确认能查到东西，再扩范围。⚠️ **两类不适用**：① **按次计费的**——`ai knowledge-batch` / `management-discuss-*`、AI Agent 那批 50/次、`alternative concept-info` / `concept-securities` 500/次，不管有没有内容都扣，超时报错也可能已经扣过；② **单价未公布的**——`pamirs-summary`（见下），别据此假定
 - ⚠️ **同参数重复调用不免费**：按次计费的那批无缓存命中豁免（`one-pager` 等生成类重复调用每次扣分，即使秒回缓存内容）；**按篇/按条的也一样**——重拉同一批 `hot-topic` 就是按条数再计一次费。生成类与列表结果拿到后自行留存复用，别为「刷新」重调
-- ⚠️ **贵档端点超时/5xx 不自动重放**（共 18 个：AI Agent 那批 + `ai knowledge-batch` / `management-discuss-*` / `hot-topic`、`alternative concept-info`·`concept-securities`、50/篇 的 `summary`·`foreign-report`·`my-conference` download 与同档处理的 `pamirs-summary` download、`tool file-parse` 提交）。**理由是重放会重复扣分**——服务端可能已经执行并计费，重发按次计费的会再扣一次，重发按篇/按条计费的会把**已交付的行**再计一次；两种都亏。仅连接失败、429 与 token 自愈会重试
+- ⚠️ **这些端点超时/5xx 不自动重放**（共 19 个：AI Agent 那批 + `ai knowledge-batch` / `management-discuss-*` / `hot-topic`、`alternative concept-info`·`concept-securities`、50/篇 的 `summary`·`foreign-report`·`my-conference` download 与同档处理的 `pamirs-summary` download、`tool file-parse` 提交，以及**不计分**的 `vault stock-pool-create`）。仅连接失败、429 与 token 自愈会重试。**贵档那批的理由是重放会重复扣分**——服务端可能已经执行并计费，重发按次计费的会再扣一次，重发按篇/按条计费的会把**已交付的行**再计一次；两种都亏。**`stock-pool-create` 不涉及积分，是重放会把成功报成失败**——池名不允许与已有池重复，重发一个其实已经建成的请求，回来的是 `230006 股票池名称重复`
 
 <!-- no-replay-endpoints
      上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
@@ -102,8 +103,10 @@ insight.pamirs-summary.download
 insight.summary.download
 tool.file-parse.submit
 vault.my-conference.download
+vault.stock-pool.create
 -->
 - **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围计费，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
+  - 🔴 截面 / 时序另有**单次 30000 单元格硬上限**（截面 = 证券数 × 指标数，时序 = 序列数 × 日期数），超出报 `100006`、不返回部分结果——按这个乘积拆批。板块 ID 会展开成全部成分股，实际证券数常远超写进命令的条数
 - **单价未公布**：`insight pamirs-summary list` / `download`——spec 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
 
 ### 数据范围（能查多久）
@@ -162,7 +165,7 @@ vault.my-conference.download
 | 跨类型语义搜索（研报+纪要+...） | `ai knowledge-batch`（多个 `--resource-type`） |
 | 知识库原文下载（搜到后取全文） | `ai knowledge-resource-download`（前置：`knowledge-batch` 拿 `resourceType`+`sourceId`；`250001`/旧 `433007`=组合不匹配） |
 | 一页通 / 投资逻辑 / 同业对比 / 调研提纲 | `ai one-pager / investment-logic / peer-comparison / research-outline` |
-| 个股看点 / 投研总结 / 公司速览 | `ai stock-summary`（`--security` **只收具体代码**，单次最多 5000 个、超过 CLI 本地拦截并提示分批；仅 A 股/港股，不支持 `aShares`/`hkStocks` 全市场批量） |
+| 个股看点 / 投研总结 / 公司速览 | `ai stock-summary`（`--security` **只收具体代码**，单次最多 6000 个、超过时 CLI 报错并提示分批；仅 A 股/港股，不支持 `aShares`/`hkStocks` 全市场批量） |
 | 业绩点评（异步） | `ai earnings-review` |
 | 观点 PK / 多空辩论（异步） | `ai viewpoint-debate` |
 | 投研线索 | `ai security-clue`（前置：`reference securities-search` 拿 `gts-code`） |
@@ -187,7 +190,8 @@ vault.my-conference.download
 | 录音速记 | `vault record-list / record-download` |
 | 我的会议（业绩会/策略会/路演内部记录） | `vault my-conference-list / my-conference-download` |
 | 微信群消息 | `vault wechat-message-list`（先 `vault wechat-chatroom-list` 拿群 ID） |
-| 自选股股票池 | `vault stock-pool-list / stock-pool-stocks` |
+| 自选股股票池（查询） | `vault stock-pool-list / stock-pool-stocks` |
+| 自选股股票池（增删改，会改动账号数据） | `vault stock-pool-create / stock-pool-rename / stock-pool-add-stock / stock-pool-remove-stock / stock-pool-delete`（删池须加 `--yes`；详见 `references/commands/vault.md`） |
 | 行业指标搜索（EDB） | `alternative edb-search` |
 | 行业指标时序数据（EDB） | `alternative edb-data` |
 | 题材画像 / 投资逻辑 / 行业空间 / 竞争格局 / 催化事件 | `alternative concept-info`（前置：`reference concept-search` 拿 `concept-id`） |
@@ -296,7 +300,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 ## 异常处理
 
-**退出码**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题——csv/jsonl 落盘时看旁边 `<file>.meta.json` 的 `complete` 与 `result`。定位字段：页失败 `failedPages`、分片失败 `failedShards`、分片撞行数上限 `truncatedShards`、`total` 撞服务端上限 `totalCapped`、`--field` 请求了但没回的列 `missingFields`、逐只请求里撞行数上限的证券 `truncatedSecurities`、EDE 整轴没回 `omittedIndicators` / `omittedSecurities`）／ `1` 硬失败。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续。** 报错行带 `[trace <id>]`，**报障给 Gangtise 时务必带上**。
+**退出码**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题——csv/jsonl 落盘时看旁边 `<file>.meta.json` 的 `complete` 与 `result`；该文件还带 `bytes` / `sha256`，用 `shasum -a 256 <file>` 核一下就能确认这份元信息描述的是旁边这份数据。定位字段：页失败 `failedPages`、分片失败 `failedShards`、分片撞行数上限 `truncatedShards`、只有部分分片返回而合并时放不下的列 `droppedColumns`（缩小日期区间单独拉）、`total` 撞服务端上限 `totalCapped`、`--field` 请求了但没回的列 `missingFields`、逐只请求里撞行数上限的证券 `truncatedSecurities`、EDE 整轴没回 `omittedIndicators` / `omittedSecurities`）／ `4` 数据本身写全了，但 `--output` 那个文件在收尾期间被另一次写向同一路径的导出替换（并发跑同一路径才会出现，给它们各自的 `--output` 即可；与 `3` 同时发生时退出 `3`）／ `1` 硬失败。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续。** 报错行带 `[trace <id>]`，**报障给 Gangtise 时务必带上**。
 
 最高频的几个码（全表、「不报错的坑」、`screener` 缺列判据与困境自救见 `references/errors.md`）：
 

package/gangtise-openapi/references/commands/ai.md

@@ -12,7 +12,7 @@
 gangtise ai knowledge-batch --query <text> [--query <text2>] [--top <n>] [--resource-type <n>] [--knowledge-name <name>] [--start-time <ts|datetime>] [--end-time <ts|datetime>]
 ```
 
-- `--query`（**必选**，可重复，最多 5 个）：缺失时本地报错，不发空请求
+- `--query`（**必选**，可重复，最多 5 个）：缺失时本地报错，不发空请求。**每个 `--query` 整段送出**——句子里的逗号是标点，不会被当成分隔符拆成两个查询；要问多个问题就重复传 `--query`
 - `--top` 默认 10，最大 20
 - `--resource-type`：`10` 券商研报 | `11` 外资研报 | `20` 内部报告 | `40` 首席观点 | `50` 公司公告 | `51` 港股公告 | `60` 会议平台纪要 | `70` 调研纪要公告 | `80` 网络资源纪要 | `90` 产业公众号
 - `--knowledge-name`：`system_knowledge_doc` 系统知识库 | `tenant_knowledge_doc` 机构知识库
@@ -55,12 +55,11 @@ gangtise ai peer-comparison  --security-code <code>
 gangtise ai stock-summary --security <code> [--security <code2> ...]
 ```
 
-- 🔴 **单次最多 5000 只，CLI 本地拦截**：更大的批次服务端返回 `{total:0, list:[]}`、HTTP 200、无告警，所以 CLI 超过 5000 只直接报错并提示分批。全市场看点按 ≤ 5000 只/批分次提交
-
-- `--security`（**必选**，可重复）：**只收具体证券代码**，单次最多 5000 个（CLI 本地拦截，超过报错并提示分批）
+- `--security`（**必选**，可重复）：**只收具体证券代码**，单次最多 6000 个（接口上限，CLI 同值拦截，超过报错并提示分批）——全 A 股可一次提交完
 - 🔴 **不支持全市场批量**：`aShares` / `hkStocks` 这类市场关键词不被接受，CLI 会本地报错（服务端对它们返 `120001`，读起来像代码写错，容易误判）。需要覆盖一批标的就先用 `reference securities-search` 或自有清单取到代码，再分批传入
 - **仅支持 A 股和港股**
-- **积分**：`3`/条；个股若无看点总结则不在返回列表中，也不扣分
+- **积分**：`3`/条；个股若无看点总结则不在返回列表中，也不扣分——所以**返回行数少于提交数是正常的**，不是丢了数据
+- 🔴 **整批返 0 行别直接读成「这批都没有看点」**：它与「确实都没有看点」长得一样。挑其中一两只单查确认后再下结论
 - 返回字段：`securityCode` / `securityName` / `summary`（精炼投研总结）/ `date`（更新日期 `yyyy-MM-dd`）
 
 **示例：**
@@ -87,6 +86,8 @@ gangtise ai earnings-review-check --data-id <id>
 - `--period`：`年份+报告期`，如 `2025q3`（q1/interim/q3/annual），仅 A 股，覆盖最近 6 期
 - `--wait`（**推荐**）：阻塞等待到出结果（最长约 5 分钟：14 次指数退避轮询 5s→30s，累计 ≈316s）——**用它时把工具/命令超时设到 ≥360s**，否则外层先超时
 - 不带 `--wait` 的手动轮询：① `earnings-review` → 拿 `{dataId, status, hint}` → ② 间隔 ~30s `*-check`（预算 ~2-3 分钟）→ pending 继续 → 多次仍 pending 交用户稍后手动 check
+  - 这一步的 `{dataId, status, hint}` 同样受 `--format` / `--output` 控制，**加了 `--output` 就会落盘**，脚本可以直接从文件里取 `dataId` 再去轮询
+  - `*-check` 返回「还在生成中」时同样落盘（`{dataId, status: "pending", hint}`），所以轮询脚本每一轮都能从同一个文件读状态，不必区分「出结果了」和「还没好」两种取法
 - 错误码：`140001`（旧 `410110`）生成中，继续等待；`140002`（旧 `410111`）生成失败，终态不重试。CLI 两代码都识别
 
 ## 观点 PK `ai viewpoint-debate`（异步）

package/gangtise-openapi/references/commands/indicator.md

@@ -14,11 +14,11 @@
 | A股盈利预测 / 一致预期（含预测 EPS） | `fundamental earning-forecast`；EDE 搜到的基本 / 稀释 EPS 是已实现值，不能替代预测 |
 | A股估值历史分位 | `fundamental valuation-analysis` |
 | **估值指标的历史序列**（分位 / 回测 / 择时） | 两个接口口径不同、都要交叉核——EDE 按正式财报披露日切换财报口径，`valuation-analysis` 按业绩快报切，见下方专门小节 |
-| 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量 |
+| 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量。**换接口不换口径**：`quote` 的 `volume` 与 EDE `qte_vol` 逐位相同（A股 / 港股 / 美股，单位均为股）。EDE 只在 `quote` 不提供的口径上才需要——周 / 月 / 季 / 年 / 区间成交量 |
 | 单证券资金流向（要占比字段） | `quote fund-flow`；免费，且有 EDE 没有的 `*Ratio` 占比。多证券批量取某一两个档位才用 EDE 的 `flow_*` |
 | 单证券三大报表全部科目 | 对应 `fundamental` 利润表 / 资产负债表 / 现金流量表命令 |
 
-EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。`valuation-analysis` / `earning-forecast` 仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：`finc_pe_ttm`(PE TTM) 港股有数；`finc_pb_mrq`(PB MRQ) 的港股覆盖是**部分**的（部分大盘股有数，另一些为 `null`）。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查一行为准。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
+EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。`valuation-analysis` / `earning-forecast` 仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：`finc_pe_ttm`(PE TTM) 与 `finc_pb_mrq`(PB MRQ) 港股都有数。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查一行为准。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
 
 ## 指标搜索 `indicator search`
 
@@ -30,9 +30,9 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - `--limit`：返回条数上限，默认 50，最大 100
 - 默认 `--format table` 只适合浏览名称；正式路由 / 取数前必须加 `--format json`，才能完成语义、`scopeList`、`parameterList` 三项校验
 - 返回字段：`indicatorCode` / `indicatorName` / `description`（算法与口径）/ `scopeList`（该指标适用的市场 + 证券类型 + `usageRestriction`）/ `parameterList`（可传的 `--indicator-param` 参数名及枚举）/ `score`
-- **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：例如 `qte_mkt_cptl`/`shr_tot` 覆盖 A/港/美股，`finc_pe_ttm` 覆盖 A/港股，`finc_pb_mrq` 覆盖 A 股 + **部分**港股，`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
+- **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：例如 `qte_mkt_cptl`/`shr_tot` 覆盖 A/港/美股，`finc_pe_ttm` / `finc_pb_mrq` 覆盖 A/港股，`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
 - **`scopeList[].usageRestriction`**：该指标在具体接口上的限制，`null` = 无限制。⚠️ **它是提示不是硬约束**——标着「不支持指标时间序列接口」的 `qte_vol_intvl` 调时序照样返数据、不会被拦下。当成「口径可能不对、结果别当真」看，别指望它会报错
-- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**（声明覆盖但暂无数据，如 `finc_pb_mrq` 声称覆盖 A股+港股而港股只有部分有数），也可能**滞后于数据**（已有数据尚未声明）。**「某某仍无数据」这类否定结论过期得和正面结论一样快**，照着它走会白白拒掉一个现在能跑的查询，而且不报错。**判断成本很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会混淆。占位值统一是 `null`（详见下方「缺数据 vs 代码写错」）
+- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**（声明覆盖但该市场暂无数据），也可能**滞后于数据**（已有数据尚未声明）。**「某某仍无数据」这类否定结论过期得和正面结论一样快**，照着它走会白白拒掉一个现在能跑的查询，而且不报错。**判断成本很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会混淆。占位值统一是 `null`（详见下方「缺数据 vs 代码写错」）
 - 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)：用 `AAPL.O`，`AAPL.US` 取不到数据
 
 ```bash
@@ -94,7 +94,21 @@ gangtise indicator time-series --indicator <code> [--indicator <code2>] \
 - `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `100003`「仅支持多指标单证券或单指标多证券」）。**单指标时 `--security` 才能传板块 ID**；多指标时只能传一个证券代码、不得传板块 ID
 - `--start-date` / `--end-date`（**均必选**）：区间端点 `yyyy-MM-dd`。时序的时间范围由这两个参数统管，**不要**再用 `--indicator-param` 传 `tradeDate` 这类单日期参数
 - ⚠️ **同一 `indicatorCode` 挂多套参数：截面和时序都不支持，这是设计如此，要拆成两次调用**。只有 `screener` 支持（它把指标绑到不同变量 `F1`/`F2` 上，天然可区分）。CLI 也表达不了该请求——`--indicator-param` 按 code 建 Map，同 code 的多组参数会被合并成一组，与服务端设计一致。走 `raw call` 真发出去会报 `100003「指标 xxx 重复配置」`
-- `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)。`TD` 且跨市场时，`date` 列是各市场交易日的**并集**
+- `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日)/`WD`(工作日)。`TD` 且跨市场时，`date` 列是各市场交易日的**并集**。服务端默认 `ND`
+
+  **不传时 CLI 会自动选**（v0.40.0 起）：发请求前用 `indicator search`（免费）读每个指标的 `parameterList`——**去重后每个指标码各查一次**（并发，`--indicator` 只给一个时就是一次）——
+
+  | 本次请求的指标 | CLI 发什么 | 为什么 |
+  | :-- | :-- | :-- |
+  | **全部**都声明 `tradeDate`、且**都不**声明 `reportDate` / `fiscalYear` | `TD`，并在 stderr 说明一句 | 行情 / 日频估值序列，交易日轴上一格不少，还省掉周末空行 |
+  | 任一指标声明 `reportDate` 或 `fiscalYear` | 不发（服务端按 `ND`） | 见下面那条红字 |
+  | `parameterList` 为空、查不到该 code、或这次查询失败 | 不发（服务端按 `ND`） | 拿不准就退回服务端默认，不赌 |
+
+  **显式传了 `--calendar-type` 就完全按你给的发**，不查也不改。
+
+  - 🔴 **两个方向的代价不对称，所以自动选择只往 `ND` 一边兜底**：报告期末常落在非交易日（如 2024-03-31、2024-06-30 均为周日），`TD` 的日期轴里没有那一列，报告期类指标于是**整行全 `null`、退出码 0、不报错**，读起来像「这只票没有这项财务数据」。**选 `ND` 选错只是多花单元格，选 `TD` 选错是静默丢数。**
+  - **混合两类指标时一律 `ND`**：一次请求只有一个 `calendarType`，管不到单个指标——`ND` 下两类都取得到（行情列在周末是 `null`，本就该是），`TD` 下行情列正常而报告期列整行全空。自动选择按的就是这条：只要有一个报告期类指标，整条走 `ND`
+  - **`TD` 能省多少**：A 股一年约 240~245 个交易日，所以同一区间 `ND` 的日期列大约是 `TD` 的 **1.5 倍**，多出来的那三分之一全是非交易日的 `null`。换算到 30000 上限就是「单指标拉一年，`TD` 能带的证券数比 `ND` 多约一半」。**要精确值就用自己的区间各跑一次比 `dates` 长度**，别套这里的比例——交易日数逐年不同
 - `--currency` / `--scale`：同 `cross-section`（含根级 `--scale` 的污染坑）
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单指标」时是各**证券**，在「单证券多指标」时是各**指标**。**板块 ID 算多证券**——传 1 个 `sectorId` 服务端会展开成 N 只成分股，列就是这 N 只（如中信白酒 → 19 列）
 - **`--key-by name|code`**（默认 `name`）：同 `cross-section`；`code` 模式下单证券列=各 `indicatorCode`、多证券列=各 `securityCode`，批量按 code 回填用它
@@ -192,20 +206,18 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 ## 必填参数与错误码（取数前必读）
 
-### 取数可靠性：`qte_vol` 等指标在某些日期上会随机返 `null`
+### 🔴 单次调用的单元格上限：30000
 
-🔴 **同一条请求多次调用，结果会在「有值」和 `null` 之间跳。** 这**与「是不是最新交易日」无关**——是**特定日期**的数据在部分副本上缺失。受影响的**只是部分标的**（同一批里其他证券稳定）；同一条请求内，受影响的证券**全有或全无**（不会一半有一半没有）。
+`cross-section` 与 `time-series` 各有一个**单次返回单元格总数不得超过 30000** 的硬上限，超出直接报 `100006 QUERY_LIMIT_EXCEEDED`（msg 写明限额），不返回部分结果、不截断。口径就是返回矩阵的元素个数：
 
-**做法，按优先级**：
-
-1. 🟢 **只要日成交量 / 成交额，别用 EDE，直接用 `quote day-kline`** —— 稳定，`amount` 与分钟线加总精确相等。**不用重试、不用换日期、不丢数据**；它的 `volume` 与 EDE `qte_vol` **逐位相同**（A股 / 港股 / 美股，单位同为股），**没有精度损失**
-2. 确实需要 EDE 才有的口径时（周 / 月 / 季 / 年 / 区间成交量等 `quote` 不提供的），**重试，但不要设固定次数上限** —— 出现过连续多次全 `null`。**若必须设上限，超限时要显式报错退出，绝不能把最后一次的 `null` 当成「无数据」写进结果**
-
-⚠️ **不要用「改取前一个交易日」当通用兜底**：它可能在某个个案上碰巧有效，但坏的是哪一天并无规律，而且会丢掉那一整天的数据。
+| 接口 | 单元格数 | 例 |
+| :-- | :-- | :-- |
+| `cross-section` | **证券数 × 指标数** | 5000 只 × 6 指标 = 30000，可以；5001 只 × 6 指标 = 30006，被拒 |
+| `time-series` | **序列数 × 日期数**（序列 = 单指标时的证券数，或单证券时的指标数） | 300 只 × 100 天 = 30000，可以；301 只 × 100 天 = 30100，被拒 |
 
-**单次 `null` 不能读成「该股当日无数据」** —— 它与真无数据无法区分，且退出码 0。判别法：**同一条请求再打几次**，只要出现过非 `null` 就说明数据是有的。
+**撞上限就按这个乘积拆批**：截面拆证券或拆指标，时序拆证券或缩日期区间，分批取回后自己合并。
 
----
+⚠️ **两处最容易撞**：① `--security` 传板块 ID 时服务端会展开成全部成分股，实际证券数远大于写进命令的条数（全 A 股板块是五千多只，配 6 个指标就到顶）；② 时序的日期轴由 `--calendar-type` 决定，`ND` 的日期列约是 `TD` 的 1.5 倍（周末与节假日各占一列），同一个查询在 `ND` 下更容易超限——纯行情序列走 `TD` 就省下这部分（不传时 CLI 会自动判，见上文）。
 
 **缺数据 vs 代码写错**：
 
@@ -232,7 +244,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 | 查法 | 服务端返回 |
 | :--- | :--- |
-| `--indicator finc_pb_mrq --security 09992.HK`（这一只港股无 PB 数据；同指标下其他港股有数） | 1 行，`finc_pb_mrq: null`，**退出 0** |
+| `--indicator mgn_bal --security 00700.HK`（融资融券余额不覆盖港股） | 1 行，`mgn_bal: null`，**退出 0** |
 | `--indicator qte_close --date 2027-01-04`（未来日期） | 1 行，`qte_close: null`，**退出 0** |
 | `--indicator qte_close --indicator not_a_real_code`（有对照物） | `100003 指标 not_a_real_code 不存在` |
 | `--indicator not_a_real_code`（**无对照物**） | `100003 指标 not_a_real_code 不存在` ← 同样报错 |
@@ -265,7 +277,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 | `100001` | **缺少必填参数**：如 `universe` 没传 | 补齐 `--indicator`/`--security` |
 | `100003`@400 | 入参/表达式错误：`time-series` 传了「多指标 × 多证券」、`expression` 引用未声明变量、`indicatorParamList` 的 code 不在 `indicatorCodeList` 里 | 按 msg 改；多 × 多改用 `cross-section`。CLI 已在本地拦截「表达式引用未绑定变量」，不会白发一次请求 |
 | `140002`@500 | **终态参数错**：指标必填参数缺失、枚举越界（如「参数 adjustType 的值 99 不在有效范围内 [1,2,3,4]」）、表达式语法错误 | **不重试**（CLI 已把 140002 列为终态码）。读 `search --format json` 的 `parameterList` 改参数名/取值 |
-| `999999` | 系统故障。「无数据」不用此码，所以它基本只剩真故障。⚠️ 别把它和空表混为一谈：无数据是占位单元格（统一 `null`），空表表示整轴 code 未识别或参数名写错 | CLI 对 indicator 端点**不重试此码**；确认参数无误仍报错就是服务端问题 |
+| `999999` | 系统故障。「无数据」不用此码，所以它基本只剩真故障。⚠️ 别把它和空表混为一谈：无数据是占位单元格（统一 `null`），空表表示整轴 code 未识别或参数名写错 | CLI 对 indicator 端点**不重试此码**；确认参数无误仍报错，稍后再试或联系平台支持 |
 | `110003` | **超出账号数据权限的时间范围**。窗口按**账号**配、不按接口配——`cross-section` / `time-series` / `screener` 同界，`quote day-kline` 也在同一条界上 | 把日期移进范围；整段区间都早于下界时缩短窗口无用，**换接口绕不过去**，要更长历史联系客户经理开通 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
@@ -360,7 +372,7 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 ## 取数最佳实践
 
 - **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名一律以 search 返回的 `parameterList` 为准，不要照抄任何示例里的参数名**——参数名会随版本调整，写错会报 `100003` 并指出是哪个指标的哪个参数，按报错改即可。
-- **`scopeList` 声称覆盖 ≠ 每只都有数**：`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，港股只有部分有数——它是**部分覆盖**，既不能当「全覆盖」也不能当「无覆盖」。**判断成本很低**：无覆盖会留下占位单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。跨市场批量取数后仍建议**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，**否定结论同样会过期**。
+- **`scopeList` 声称覆盖 ≠ 每只都有数**：声明可能超前于数据，同一指标下也可能只有部分证券有数，既不能当「全覆盖」也不能当「无覆盖」。**判断成本很低**：无覆盖会留下占位单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。跨市场批量取数后仍建议**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，**否定结论同样会过期**。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
   - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 多数用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）。🔴 **但 `_ttm` 后缀是整族例外，必填 `tradeDate`**——`is_*_ttm` / `cf_*_ttm` / `div_cash_ttm` / `finc_*_ttm` 一律走交易日。**一眼验证**：在一个**非报告期末的普通交易日**直接 `--date` 取 `is_op_rev_ttm`，照样返真值；反过来给它传 `reportDate` 会报 `100003 不支持参数 reportDate; 缺少必填参数 tradeDate`。同族对照：普通 `is_op_rev` 只传 `--date` 则报「不支持参数 tradeDate; 缺少必填参数 reportDate」——**两者恰好相反**。**所以前缀只是提示，判据仍是上面 `--date` 那条：读 `parameterList` 里必填的是哪个，别按 code 前缀推断**

package/gangtise-openapi/references/commands/vault.md

@@ -68,7 +68,11 @@ gangtise vault wechat-chatroom-list [--room-name <name>] [--from <n>] [--size <n
 - 省略 `--size` 拉全量（接口返回 `total`，CLI 按 total 并发翻页）；传 `--size N` 只取前 N 条。单页最大 50
 - 返回字段：`total`（总条数）/ `chatroomName` / `chatroomId`
 
-## 自选股股票池 `vault stock-pool-list / stock-pool-stocks`
+## 自选股股票池 `vault stock-pool-*`
+
+查询两个、增删改五个，全部免费，只操作当前账号本人的数据。
+
+### 查询
 
 ```bash
 gangtise vault stock-pool-list
@@ -80,3 +84,34 @@ gangtise vault stock-pool-stocks [--pool-id <id>]
   - `--pool-id`：股票池 ID，可重复；不传默认 `all`（返回所有池中的非重复证券）
   - 传入 `--pool-id all` 等同于全量查询，最多返回 10000 只
   - 返回字段：`securityCode` / `securityName`
+
+### 增删改
+
+🔴 **这五个命令会改动账号数据**，是本 CLI 仅有的写操作；`--pool-id` 一律取自 `stock-pool-list`。
+
+```bash
+gangtise vault stock-pool-create      --name <名称>
+gangtise vault stock-pool-rename      --pool-id <id> --name <新名称>
+gangtise vault stock-pool-add-stock   --pool-id <id> --security <code> [--security <code>...]
+gangtise vault stock-pool-remove-stock --pool-id <id> --security <code> [--security <code>...]
+gangtise vault stock-pool-delete      --pool-id <id> [--pool-id <id>...] --yes
+```
+
+- `stock-pool-create`：建池，返回新池的 `poolId` / `poolName`
+  - **池名上限 10 个字符**（按字符计，中文算 1 个），超出返回 `230007`。⚠️ 在 Gangtise 终端里建的老池名可以更长，通过本接口建池 / 改名则一律受这个上限约束
+  - **池名不能与已有池重复**，重名返回 `230006`；判重是整串精确比较——首尾空格不会被去掉（`" A "` 与 `"A"` 可并存），大小写也不归一（`abc` 与 `ABC` 可并存）
+  - 每个账号最多 30 个池，达到上限后返回 `230003`
+  - 这条命令超时或 5xx **不会自动重发**（重发一个其实已经建成的请求只会撞重名报错）；超时后先 `stock-pool-list` 看池建成没有，再决定重来
+- `stock-pool-rename`：只改名，池内自选股不受影响；新名的长度与重名规则同上（改成该池自己当前的名字算成功）
+- `stock-pool-add-stock` / `stock-pool-remove-stock`：批量加 / 批量移出，`--security` 可重复或逗号分隔；单池上限 10000 只
+  - 代码要带市场后缀且**大小写敏感**：`600519.SH` / `00700.HK` / `AAPL.O` 可混在一次请求里；`600519`（缺后缀）、`600519.sh`、`aapl.o`、`700.HK`（港股要 5 位）都会进 `failList` 报「证券代码不存在」，而不是报错退出
+  - 首尾空格会被自动去掉，列表内重复的同一代码会去重（成功项只计一次）
+- `stock-pool-delete`：批量删池，**必须显式加 `--yes`**（不加会直接报错退出，不发请求）
+  - 删池会同时移除池内全部证券的关注关系，**不可恢复**；个股的投资笔记独立保留，不受影响
+  - **`raw call vault.stock-pool.delete` 同样要 `--yes`**——换成 raw 入口不会跳过这道确认
+
+**部分失败会被标出来**：`add-stock` / `remove-stock` / `delete` 是逐条处理的——证券代码不存在这类单条失败，服务端仍返回成功信封，把失败明细放进 `failList`（`successList` 里是成功的那些）。CLI 检测到 `failList` 非空时在 stderr 列出失败项与原因、给结果标 `partial`、**退出码 3**；全部成功才是退出码 0。批量脚本按退出码判断即可，不必自己解析 `failList`。**`raw call` 打这三个端点时判定完全相同**，同一份响应不会一个入口退 3、另一个退 0。
+
+**幂等**：重复加已在池内的证券、移出本就不在池内的证券、删不存在的 `poolId`，都算成功并计入 `successList`，不会报错。唯一不幂等的是 `stock-pool-create`（见上面的重名规则）。
+
+**返回字段**：`create` / `rename` 返回 `poolId` / `poolName`；`add-stock` / `remove-stock` / `delete` 返回 `successList[]` + `failList[]{securityCode 或 poolId, failReason}`。