tyc-cli 0.2.5 → 0.3.1

package/dist/commands/category.js

@@ -2,6 +2,7 @@ import { getCategories, getToolsByGroup } from "../registry.js";
 import { resolveConfig } from "../config.js";
 import { callTool } from "../mcpClient.js";
 import { jsonToMarkdown } from "../utils/jsonToMarkdown.js";
+import { applyTruncation, resolveOptionalInt, TRUNCATE_DEFAULTS, } from "../utils/truncate.js";
 export function registerCategoryCommands(program) {
     for (const cat of getCategories()) {
         const tools = getToolsByGroup(cat.group);
@@ -81,21 +82,43 @@ function emit(result, opts, toolName) {
         payload = JSON.parse(text);
     }
     catch {
-        // 非 JSON 文本：直接原样输出
-        process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+        // 非 JSON 文本：直接原样输出（仍走截断 / 落盘）
+        emitWithTruncation(text.endsWith("\n") ? text.slice(0, -1) : text, opts);
         return;
     }
+    // 输出模式选择（互斥优先级 --md > --compact > --pretty / 默认 = pretty）
     let rendered;
     if (opts.md) {
         rendered = jsonToMarkdown(payload, toolName);
     }
-    else if (opts.pretty) {
-        rendered = JSON.stringify(payload, null, 2);
+    else if (opts.compact) {
+        rendered = JSON.stringify(payload);
     }
     else {
-        rendered = JSON.stringify(payload);
+        // 默认 = pretty（含 --pretty 显式情况）
+        rendered = JSON.stringify(payload, null, 2);
+    }
+    emitWithTruncation(rendered, opts);
+}
+function emitWithTruncation(rendered, opts) {
+    // 解析 head / tail / threshold：commander 对 `[n]` 在未传值时给 true
+    const head = resolveOptionalInt(opts.head, TRUNCATE_DEFAULTS.HEAD);
+    const tail = resolveOptionalInt(opts.tail, TRUNCATE_DEFAULTS.TAIL);
+    const threshold = resolveOptionalInt(opts.threshold, TRUNCATE_DEFAULTS.THRESHOLD);
+    const outputFile = typeof opts.outputFile === "string" && opts.outputFile.length > 0
+        ? opts.outputFile
+        : undefined;
+    const r = applyTruncation(rendered, {
+        full: !!opts.full,
+        head,
+        tail,
+        threshold,
+        outputFile,
+    });
+    console.log(r.rendered);
+    for (const n of r.notices) {
+        process.stderr.write(n + "\n");
     }
-    console.log(rendered);
 }
 function extractText(result) {
     const content = result.content || [];

package/dist/index.js

@@ -59,12 +59,29 @@ DISCOVER BY CATEGORY (orthogonal to layers, 6 groups)
 
 ${renderCategoryLines()}
 
-OUTPUT FORMATS (mutually exclusive, priority: --md > --pretty > default)
+OUTPUT FORMATS (mutually exclusive, priority: --md > --compact > --pretty / default)
 
-  (default)    compact single-line JSON (pipe-friendly)
-  --pretty     indented JSON (debug)
+  (default)    indented JSON (pretty) — readable for both humans and agents
+  --pretty     same as default (kept for backward compatibility / explicit intent)
+  --compact    compact single-line JSON (pipe / jq friendly; old default behavior)
   --md         Markdown tables (human + agent on-screen)
-  --verbose    also print MCP request details to stderr
+  --verbose    also print MCP request details to stderr (orthogonal to above)
+
+OUTPUT TRUNCATION & DUMP  (orthogonal — apply to any sub-command)
+
+  --head [N]            print only the first N lines  (N defaults to 50 if flag given alone)
+  --tail [M]            print only the last M lines   (M defaults to 20 if flag given alone)
+                          · --head + --tail together: head + "... omitted ..." + tail
+                          · either flag alone: that side only
+  --full                force-print the FULL rendered content (no truncation; highest priority)
+  --threshold <BYTES>   master switch for byte-truncation. Without --threshold there is
+                        NO automatic truncation, regardless of output size.
+                        With --threshold N: when rendered output > N bytes, byte-truncate
+                        from the head; --head / --tail are IGNORED in this mode.
+  --output-file <PATH>  write the FULL rendered content to PATH. **No file is written
+                        unless --output-file is explicitly passed** (no auto-dump).
+                        Combine with --head/--tail/--threshold to keep stdout terse
+                        while preserving the full result on disk.
 
 SETUP
 
@@ -97,10 +114,16 @@ function renderPriorityLines() {
 const program = new Command()
     .name("tyc")
     .description(`Tianyan AI CLI — ${getTotalCount()} commercial-data tools · L0=${getLayerCount("L0")} L1=${getLayerCount("L1")} L2=${getLayerCount("L2")} L3=${getLayerCount("L3")} · the AI-native gateway (pair with the TA MCP Server)`)
-    .version("0.3.0")
-    .option("--pretty", "格式化 JSON 输出（缩进 2 空格）")
+    .version("0.4.0")
+    .option("--pretty", "缩进 JSON 输出（默认行为，flag 保留以保持向后兼容）")
     .option("--md", "Markdown 表格化输出（适合人类阅读 / Agent 上屏）")
+    .option("--compact", "紧凑单行 JSON（管道 / jq 场景；为旧默认行为）")
     .option("--verbose", "打印 MCP 请求详情到 stderr")
+    .option("--head [n]", "仅输出前 N 行（不传值默认 50；与 --tail 同时给则同时输出两端）")
+    .option("--tail [m]", "仅输出后 M 行（不传值默认 20；与 --head 同时给则同时输出两端）")
+    .option("--full", "强制输出完整内容（最高优先级，覆盖 --head/--tail/--threshold）")
+    .option("--output-file <path>", "把完整结果写入指定路径（必须显式指定；不传则永不落盘）")
+    .option("--threshold <bytes>", "字节截断主开关：超过该字节数则从头按字节截断；不传则永不截断")
     .addHelpText("after", helpText);
 registerInitCommand(program);
 registerLayerCommands(program);

package/dist/utils/truncate.js

@@ -0,0 +1,152 @@
+// 输出截断 / 落盘工具
+//
+// 设计原则（与用户对齐）：
+//   1. --threshold 是截断逻辑的"主开关"。**没有 --threshold 时永不按字节截断**。
+//   2. --head N / --tail M 各自显式生效，互不依赖；同时给则同时输出两端。
+//      head/tail 是 line-based、对人类可读输出（pretty / md / compact）都适用。
+//   3. --threshold 与 --head/--tail 同时出现时按"从头按字节截"语义优先（用户原话），
+//      避免用户的字节预算被行截断绕过。
+//   4. --full 最高优先级：永远输出完整内容；仍可与 --output-file 共存（落盘 + 全量打印）。
+//   5. **不指定 --output-file 永不落盘**（用户明确要求）。
+//
+// 渲染顺序：先决定 mode（md / pretty / compact），渲染成字符串后送入 truncate；
+// 落盘永远写"渲染后的字符串"，与 stdout 看到的同源，便于 diff / 复盘。
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const HEAD_DEFAULT = 50;
+const TAIL_DEFAULT = 20;
+const THRESHOLD_DEFAULT = 5000;
+/**
+ * 解析 commander 接收到的可选值参数：
+ *   - undefined：用户未指定该 flag
+ *   - true：用户指定了 flag 但未给值（commander `[n]` 语法）→ 用 fallback
+ *   - string：用户指定了具体值 → parseInt
+ *   - 非法值 → fallback（保持宽容；CLI 不该因为 --head abc 直接崩）
+ */
+export function resolveOptionalInt(raw, fallback) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === true || raw === "")
+        return fallback;
+    const n = parseInt(String(raw), 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** Buffer 字节数（与 stdout 实际字节数一致；JS .length 是 UTF-16 code units，会高估纯 ASCII / 低估中文） */
+function byteLen(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+/**
+ * 按字节截到 ≤ maxBytes，且回退到 UTF-8 字符边界（避免半个汉字）。
+ * 我们只截 head 端（用户原话："直接从头到尾按字节数量来截断"）。
+ */
+function truncateByBytes(s, maxBytes) {
+    const buf = Buffer.from(s, "utf8");
+    if (buf.length <= maxBytes)
+        return s;
+    let end = maxBytes;
+    // UTF-8 续字节模式 10xxxxxx：往回退到上一个起始字节
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    return buf.subarray(0, end).toString("utf8");
+}
+function truncateByLines(s, head, tail) {
+    const lines = s.split("\n");
+    const total = lines.length;
+    if (head === undefined && tail === undefined) {
+        return { out: s, truncated: false, total };
+    }
+    const h = head ?? 0;
+    const t = tail ?? 0;
+    if (h + t >= total) {
+        return { out: s, truncated: false, total };
+    }
+    const omitted = total - h - t;
+    const parts = [];
+    if (head !== undefined)
+        parts.push(...lines.slice(0, h));
+    if (head !== undefined && tail !== undefined) {
+        parts.push(`... (省略中间 ${omitted} 行) ...`);
+        parts.push(...lines.slice(-t));
+    }
+    else if (head !== undefined) {
+        parts.push(`... (省略后续 ${omitted} 行) ...`);
+    }
+    else if (tail !== undefined) {
+        parts.push(`... (省略前 ${omitted} 行) ...`);
+        parts.push(...lines.slice(-t));
+    }
+    return { out: parts.join("\n"), truncated: true, total };
+}
+function writeDump(absPath, content) {
+    const dir = dirname(absPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(absPath, content, { encoding: "utf8" });
+}
+/**
+ * 按用户语义对渲染好的字符串做截断 / 落盘。
+ *
+ * 决策树（每条分支互斥）：
+ *   1. --output-file 给了 → 落盘（写"全量"原文，与 stdout 截断版本无关）
+ *   2. --full → stdout 全量
+ *   3. --threshold 给了：
+ *        size > threshold → 字节截到 threshold（head 端）
+ *        size ≤ threshold → 全量
+ *      （此分支下 --head/--tail 被忽略，符合"从头按字节截断"语义）
+ *   4. --head 或 --tail 给了（且无 --threshold）→ line-based 头/尾/头+尾截断
+ *   5. 都没给 → 全量
+ */
+export function applyTruncation(rendered, opts) {
+    const notices = [];
+    let fileWritten;
+    // 1. 落盘永远写全量
+    if (opts.outputFile && opts.outputFile.length > 0) {
+        const abs = resolve(opts.outputFile);
+        try {
+            writeDump(abs, rendered);
+            fileWritten = abs;
+            notices.push(`已写入完整结果到 ${abs}（${byteLen(rendered)} 字节）`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            notices.push(`⚠️ --output-file 写入失败：${msg}（继续打印 stdout）`);
+        }
+    }
+    // 2. --full 最高优先级
+    if (opts.full) {
+        return { rendered, fileWritten, notices };
+    }
+    // 3. --threshold 主导：字节截
+    if (opts.threshold !== undefined) {
+        const size = byteLen(rendered);
+        if (size > opts.threshold) {
+            const cut = truncateByBytes(rendered, opts.threshold);
+            const omitted = size - byteLen(cut);
+            const tail = `\n... (已按 --threshold=${opts.threshold} 字节截断，省略尾部约 ${omitted} 字节) ...`;
+            notices.push(`输出被 --threshold=${opts.threshold} 截断（原始 ${size} 字节 → 输出 ${byteLen(cut)} 字节）` +
+                (fileWritten ? `；完整内容见 ${fileWritten}` : "；如需完整内容追加 --output-file <path>"));
+            return { rendered: cut + tail, fileWritten, notices };
+        }
+        return { rendered, fileWritten, notices };
+    }
+    // 4. line-based head/tail（无 --threshold）
+    if (opts.head !== undefined || opts.tail !== undefined) {
+        const r = truncateByLines(rendered, opts.head, opts.tail);
+        if (r.truncated) {
+            const segs = [];
+            if (opts.head !== undefined)
+                segs.push(`head=${opts.head}`);
+            if (opts.tail !== undefined)
+                segs.push(`tail=${opts.tail}`);
+            notices.push(`输出被 ${segs.join(" / ")} 截断（原始 ${r.total} 行）` +
+                (fileWritten ? `；完整内容见 ${fileWritten}` : "；如需完整内容追加 --output-file <path>"));
+        }
+        return { rendered: r.out, fileWritten, notices };
+    }
+    // 5. 无任何截断 flag
+    return { rendered, fileWritten, notices };
+}
+export const TRUNCATE_DEFAULTS = {
+    HEAD: HEAD_DEFAULT,
+    TAIL: TAIL_DEFAULT,
+    THRESHOLD: THRESHOLD_DEFAULT,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tyc-cli",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "天眼查 MCP CLI — 163 个业务语义聚合工具 · 命令行直达企业数据 · 通过 MCP Server 调用",
   "main": "dist/index.js",
   "bin": {