tyc-cli 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范，版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.4.0] - 2026-05-03
+
+### 新增
+
+- **输出格式三选一**（互斥优先级 `--md` > `--compact` > `--pretty` / 默认）：
+  - `--compact`：紧凑单行 JSON（旧默认行为；管道 / `jq` 场景）
+  - 默认改为缩进 2 空格 JSON（pretty），人/Agent 通用
+  - `--pretty`：同默认；保留 flag 以保持向后兼容 / 显式声明意图
+  - `--md`：Markdown 表格（人类阅读 / Agent 上屏；自动渲染 `_summary` / 元数据 / `items` 表格）
+- **截断与落盘**（与输出格式正交，可叠加任意子命令）：
+  - `--head [N]`（默认 50）：仅打印前 N 行；与 `--tail` 同时给则同时输出两端
+  - `--tail [M]`（默认 20）：仅打印后 M 行
+  - `--full`：强制完整输出（最高优先级，覆盖 `--head/--tail/--threshold`）
+  - `--threshold <BYTES>`（默认 5000）：**字节截断主开关**——超过该字节数从头按字节截断；**不传则永不截断**；与 `--head/--tail` 同时给则按字节截，行参数被忽略
+  - `--output-file <PATH>`：把完整结果写入指定路径；**必须显式指定才落盘**（不传则永不落盘）
+  - 截断/落盘提示打到 stderr，stdout 保持纯净数据流，便于管道与 `jq` 处理
+
+### 变更
+
+- 默认 stdout 由紧凑单行 JSON 改为缩进 2 空格 JSON。需要旧默认行为的脚本请显式加 `--compact`
+
+## [0.3.0] - 2026-04-29
+
+### 新增
+
+- **分层发现入口**：`tyc layers` / `tyc L0 list` / `tyc L1 list` / `tyc L2 list`，支持 `--md` / `--json`
+- 每个 tool 的 `tyc ... --help` 标题带 `[L0]/[L1]/[L2]` 徽章，让 Agent 先看结构、后发一次 `tools/call`
+
 ## [0.2.0] - 2026-04-27
 
 ### 架构重构

package/README.md

@@ -100,13 +100,58 @@ tyc executive personnel-dishonest "..." --humanName "张三"
 
 ### 全局选项
 
+#### 输出格式（互斥优先级 `--md` > `--compact` > `--pretty` / 默认）
+
 | 选项 | 说明 |
 |------|------|
-| `--pretty` | 缩进 2 空格 JSON 输出（调试友好） |
+| _(默认)_ | 缩进 2 空格 JSON（pretty）—— 人/Agent 都好读，已成默认 |
+| `--pretty` | 同默认；保留 flag 以保持向后兼容 / 显式声明意图 |
+| `--compact` | 紧凑单行 JSON（旧默认行为；管道 / `jq` 场景） |
 | `--md` | Markdown 表格化输出（人类阅读 / Agent 上屏） |
-| `--verbose` | 打印 MCP 请求详情到 stderr（URL / Mcp-Session-Id / 掩码 Authorization / 响应原文） |
+| `--verbose` | 打印 MCP 请求详情到 stderr（与上述输出格式正交） |
+
+#### 输出截断 / 落盘（与上述输出格式正交，可叠加任意子命令）
+
+| 选项 | 默认值 | 说明 |
+|------|-------:|------|
+| `--head [N]` | 50 | 仅打印前 N 行；与 `--tail` 同时给则同时输出两端，否则只输出 head |
+| `--tail [M]` | 20 | 仅打印后 M 行；与 `--head` 同时给则同时输出两端 |
+| `--full` | false | 强制完整输出（最高优先级，覆盖 `--head/--tail/--threshold`） |
+| `--threshold <BYTES>` | 5000 | **字节截断主开关**：超过该字节数则从头按字节截断；**不传则永不截断** |
+| `--output-file <PATH>` | — | 把完整结果写入指定路径；**不传则永不落盘**（无自动落盘） |
+
+> ⚠️ **截断决策树（与 stdout / 落盘行为）**
+>
+> 1. `--output-file` 给了 → 落盘永远写**完整**结果（与 stdout 是否截断无关）
+> 2. `--full` 最高优先级 → stdout 也输出完整
+> 3. 否则若 `--threshold N` 给了：超过 N 字节从头按字节截；**此模式下 `--head/--tail` 被忽略**
+> 4. 否则若 `--head/--tail` 任一给了 → 行级截断
+> 5. 否则 → 无截断、无落盘
+>
+> 截断与落盘的提示信息（"已写入 …"、"输出被 head=5 截断 …"）打到 stderr，stdout 仍为可程序化解析的纯净数据流。
+
+#### 用法示例
+
+```bash
+# 调试时只看头部
+tyc company registration-info "百度" --head            # 默认 50 行
+tyc company registration-info "百度" --head 10         # 自定义 10 行
+
+# 看头看尾，确认数据起止
+tyc company key-personnel "百度" --head 5 --tail 5
 
-三种输出互斥优先级：`--md > --pretty > 默认`。
+# 字节预算控制（适合塞进 LLM context）
+tyc risk overview "百度" --threshold 4000
+
+# stdout 简洁 + 完整结果落盘
+tyc company equity-tree "百度" --head 30 --output-file ./equity-tree.json
+
+# 强制全量（覆盖以上一切截断）
+tyc operation bidding-info "百度" --full
+
+# 管道场景沿用旧紧凑 JSON
+tyc company registration-info "百度" --compact | jq .name
+```
 
 ### 环境变量覆盖
 
@@ -201,7 +246,7 @@ tyc executive person-risk-overview "..." --humanName "张三"
        │                              │
        │                              └─ 多源并发聚合 · 时间戳格式化 · _summary 注入 · 空结果归一化
        │
-       └─ 仅命令树 · 参数透传 · Session 管理 · --md/--pretty 呈现
+       └─ 仅命令树 · 参数透传 · Session 管理 · pretty/--md/--compact 呈现 · --head/--tail/--full/--threshold/--output-file 截断与落盘
 ```
 
 **CLI 的职责**：
@@ -210,7 +255,7 @@ tyc executive person-risk-overview "..." --humanName "张三"
 2. 组装 `tools/call` JSON-RPC 请求，透传 `Authorization` header
 3. Session 管理（`initialize` + 24h 缓存 + 失效重建）
 4. 解析 MCP Streamable HTTP 响应（纯 JSON 或 SSE）
-5. 格式化输出（紧凑 JSON / `--pretty` / `--md`）
+5. 格式化输出（默认 pretty / `--compact` / `--md`），并可叠加 `--head/--tail/--full/--threshold/--output-file` 做截断与落盘
 
 **CLI 不做**：
 
@@ -243,7 +288,8 @@ tyc-cli/
     │   ├── init.ts           # tyc init
     │   └── category.ts       # 动态注册 6 分类 × N 方法
     └── utils/
-        └── jsonToMarkdown.ts # --md 选项的 Markdown 渲染
+        ├── jsonToMarkdown.ts # --md 选项的 Markdown 渲染
+        └── truncate.ts       # --head/--tail/--full/--threshold/--output-file 截断与落盘
 ```
 
 ---

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.0",
   "description": "天眼查 MCP CLI — 163 个业务语义聚合工具 · 命令行直达企业数据 · 通过 MCP Server 调用",
   "main": "dist/index.js",
   "bin": {