tyc-cli 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -7,7 +7,7 @@
 ### 架构重构
 
 - **CLI 改为 MCP 客户端**：不再直连 tyc OpenAPI，所有工具调用走天眼查 MCP Server
-  `https://ai-mcp.tianyancha.com/mcp`（默认），`--url` 可覆盖到自建 MCP
+  `https://mcp.tianyancha.com/v1`（默认），`--url` 可覆盖到自建 MCP
 - **移除本地业务逻辑**：多源聚合 / 时间戳格式化 / `_summary` 注入 / 空结果归一化
   全部下沉到 MCP Server 端；CLI 只负责命令树、参数透传、`--md/--pretty` 呈现
 - **Session 管理**：首次调用执行 `initialize` 拿 `Mcp-Session-Id`，缓存在
@@ -20,7 +20,7 @@
 
 ### 新增
 
-- `tyc init --url <url>`：配置 MCP endpoint（默认 `https://ai-mcp.tianyancha.com/mcp`）
+- `tyc init --url <url>`：配置 MCP endpoint（默认 `https://mcp.tianyancha.com/v1`）
 - `tyc init --header K=V`（可重复）：注入自定义 HTTP header
 - `tyc init --clear-session`：显式清理本地 session 缓存
 - `TYC_MCP_ENDPOINT` / `TYC_AUTHORIZATION` 环境变量覆盖

package/README.md

@@ -19,7 +19,7 @@ Streamable HTTP）调用天眼查 163 个业务语义聚合工具，覆盖企业
 
 - 🧠 **MCP 客户端架构**：CLI 只做协议转换与参数透传；多源合并、时间戳格式化、
   空结果归一化、`_summary` 注入等业务逻辑由 MCP Server 完成
-- 🔌 **即插即用**：默认连接官方 MCP 端点 `https://ai-mcp.tianyancha.com/mcp`；
+- 🔌 **即插即用**：默认连接官方 MCP 端点 `https://mcp.tianyancha.com/v1`；
   支持 `--url` 指向私有部署
 - 🔄 **Session 复用**：`Mcp-Session-Id` 本地缓存 24 小时，后续调用零 initialize 开销
 - 🎯 **6 大业务分类 / 163 个工具**：企业基础信息 · 风险合规 · 知识产权 · 经营与公示 · 历史信息 · 董监高
@@ -53,7 +53,7 @@ npm install && npm run build && npm link
 tyc init --authorization "YOUR_API_TOKEN"
 
 # 连接自建 MCP
-tyc init --authorization "YOUR_API_TOKEN" --url "http://your-mcp-host:8080/mcp"
+tyc init --authorization "YOUR_API_TOKEN" --url "http://your-mcp-host:8080/v1"
 
 # 仅写配置、不校验（离线环境或先配好稍后上线）
 tyc init --authorization "YOUR_API_TOKEN" --no-verify
@@ -66,7 +66,7 @@ tyc init --authorization "YOUR_API_TOKEN" --no-verify
 
 ```json
 {
-  "url": "https://ai-mcp.tianyancha.com/mcp",
+  "url": "https://mcp.tianyancha.com/v1",
   "headers": {
     "Authorization": "YOUR_API_TOKEN"
   }
@@ -196,7 +196,7 @@ tyc executive person-risk-overview "..." --humanName "张三"
 ```
 ┌─────────────┐         ┌─────────────────────────────┐         ┌─────────────────┐
 │   tyc-cli   │ ──JSON──▶│  天眼查 MCP Server           │ ──HTTP──▶│ tyc OpenAPI     │
-│ (npm / TS)  │ ◀───RPC──│  (ai-mcp.tianyancha.com/mcp) │ ◀───────│                 │
+│ (npm / TS)  │ ◀───RPC──│  (mcp.tianyancha.com/v1) │ ◀───────│                 │
 └─────────────┘         └─────────────────────────────┘         └─────────────────┘
        │                              │
        │                              └─ 多源并发聚合 · 时间戳格式化 · _summary 注入 · 空结果归一化
@@ -262,7 +262,7 @@ tyc-cli/
 
 ```json
 {
-  "url": "https://ai-mcp.tianyancha.com/mcp",
+  "url": "https://mcp.tianyancha.com/v1",
   "sessionId": "mcp-session-xxx",
   "initializedAt": 1777272039739,
   "protocolVersion": "2024-11-05"
@@ -296,7 +296,7 @@ tyc-cli/
 | 协议 | MCP client（JSON-RPC over Streamable HTTP） | MCP server |
 | 实现 | TypeScript | Go |
 | 职责 | 命令树 · 参数透传 · 格式化输出 | 多源聚合 · 时间戳格式化 · 元数据注入 · Authorization 透传至 OpenAPI |
-| 运维 | 用户本地安装 | 官方托管 `ai-mcp.tianyancha.com`，或用户自建 |
+| 运维 | 用户本地安装 | 官方托管 `mcp.tianyancha.com`，或用户自建 |
 
 CLI 和 MCP Server 共享同一 163 工具清单；工具元数据从打包内的 `catalog.json`
 读取，保证命令树冷启动零网络开销。
@@ -321,7 +321,7 @@ bash test/t1_1/cli/run_t1_1.sh -o -v
 MCP_URL=https://my-mcp.example.com/mcp AUTH_TOKEN=xxx bash test/t1_1/cli/run_t1_1.sh
 ```
 
-`-o` = `--online`，切到 `https://ai-mcp.tianyancha.com/mcp`；`-v` = `--verbose`。
+`-o` = `--online`，切到 `https://mcp.tianyancha.com/v1`；`-v` = `--verbose`。
 单分类脚本加 `-p` 可独立触发 preflight：`bash test/t1_1/cli/test_company.sh -p -o`。
 
 ---

package/dist/catalog.json

@@ -675,7 +675,8 @@
           "required": true,
           "description": "企业名称 或 统一社会信用代码"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "get_stock_executives",
@@ -964,7 +965,8 @@
           "required": true,
           "description": "人员姓名"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "get_personnel_controlled_companies",
@@ -1446,7 +1448,8 @@
           "required": true,
           "description": "企业名称 或 统一社会信用代码"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "get_historical_shareholders",
@@ -1675,7 +1678,8 @@
           "required": true,
           "description": "企业名称 或 统一社会信用代码"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "search_patents",
@@ -1759,7 +1763,8 @@
           "required": true,
           "description": "企业名称 或 统一社会信用代码"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "get_bonds",
@@ -2558,7 +2563,8 @@
           "required": true,
           "description": "企业名称 或 统一社会信用代码"
         }
-      ]
+      ],
+      "priority": true
     },
     {
       "name": "get_judicial_documents",

package/dist/commands/layers.js

@@ -1,4 +1,4 @@
-import { getCategories, getCategoryName, getLayerCount, getToolsByLayer, getTotalCount, } from "../registry.js";
+import { getCategories, getCategoryName, getLayerCount, getPriorityTools, getToolsByLayer, getTotalCount, } from "../registry.js";
 const LAYER_SPECS = [
     {
         layer: "L0",
@@ -54,11 +54,17 @@ function registerLayers(program) {
                     contract: s.contract,
                 })),
                 categories: getCategories(),
+                l2_priority: getPriorityTools().map((t) => ({
+                    facet: t.group,
+                    tool: t.name,
+                    cli: `tyc ${t.group} ${t.cliMethod}`,
+                    description: t.description,
+                })),
                 recommended_call_order: [
                     `0. Anchor at L0 — feed the user's raw company name into the ${getLayerCount("L0")} L0 tool (search_companies); lock onto a USCC + official name`,
                     `1. Ascend to L1 — pick ONE of the ${getLayerCount("L1")} overview tools with the anchored USCC`,
                     "2. Read _summary + drill_down hints from the response",
-                    `3. Drill to L2 for a specific dimension (items + totals; ${getLayerCount("L2")} tools)`,
+                    `3. Drill to L2 for a specific dimension (items + totals; ${getLayerCount("L2")} tools); when unsure which L2, default to the facet's L2 优先 (★, see l2_priority)`,
                     `4. Reach L3 for id-based detail, search_*, or vertical SKILL tools (${getLayerCount("L3")} tools)`,
                 ],
             };
@@ -91,6 +97,9 @@ function registerLayerCmd(program, spec) {
                 count: tools.length,
                 trigger: spec.trigger,
                 contract: spec.contract,
+                priority_count: layer === "L2"
+                    ? tools.filter((t) => t.priority).length
+                    : undefined,
                 tools: tools.map((t) => ({
                     name: t.name,
                     group: t.group,
@@ -98,6 +107,7 @@ function registerLayerCmd(program, spec) {
                     cli: `tyc ${t.group} ${t.cliMethod}`,
                     description: t.description,
                     params: t.params ?? [],
+                    ...(t.priority ? { priority: true } : {}),
                 })),
             };
             console.log(JSON.stringify(payload, null, 2));
@@ -129,13 +139,22 @@ function renderLayersText() {
         lines.push(`      Trigger: ${s.trigger}`);
         lines.push(`      Contract: ${s.contract}`);
         lines.push(`      List:    tyc ${s.layer} list [--md|--json]`);
+        if (s.layer === "L2") {
+            const prio = getPriorityTools();
+            lines.push("");
+            lines.push(`      L2 优先（★ "L2★ 队副"，每 facet 1 个，共 ${prio.length} 个）：Agent 拿到 L1 _summary`);
+            lines.push("      若不确定走哪个 L2，默认推这 6 个之一：");
+            for (const t of prio) {
+                lines.push(`        ★ ${pad(t.group, 22)} ${pad(t.name, 36)} (tyc ${t.group} ${t.cliMethod})`);
+            }
+        }
         lines.push("");
     }
     lines.push("Recommended call order for agents:");
     lines.push(`  0. Anchor at L0 — feed the user's raw company name into the ${getLayerCount("L0")} L0 tool (search_companies)`);
     lines.push(`  1. Ascend to L1 — one of the ${getLayerCount("L1")} overview tools, with the anchored USCC`);
     lines.push("  2. Read _summary + drill_down hints in the response");
-    lines.push(`  3. Drill to L2 for a specific dimension (${getLayerCount("L2")} tools)`);
+    lines.push(`  3. Drill to L2 for a specific dimension (${getLayerCount("L2")} tools); unsure which L2 → default to that facet's L2★ 优先 (see L2 block above)`);
     lines.push(`  4. Reach L3 for id-based detail / search_* / vertical SKILL (${getLayerCount("L3")} tools)`);
     return lines.join("\n");
 }
@@ -153,12 +172,24 @@ function renderLayersMarkdown() {
         lines.push(`| **${s.layer}** ${s.title} | ${getLayerCount(s.layer)} | ${escapeCell(s.summary)} | ${escapeCell(s.trigger)} |`);
     }
     lines.push("");
+    // L2 优先（"L2★ 队副"）映射表
+    const prio = getPriorityTools();
+    lines.push(`**L2 优先 ★ — \`L2★ 队副\`（${prio.length} 个，每 facet 1 个）**`);
+    lines.push("");
+    lines.push("> Agent 拿到 L1 `_summary` 后若不确定走哪个 L2，默认推对应 facet 的 L2 优先工具。");
+    lines.push("");
+    lines.push("| facet | L2★ 优先工具 | CLI |");
+    lines.push("|---|---|---|");
+    for (const t of prio) {
+        lines.push(`| ${t.group} | \`${t.name}\` | \`tyc ${t.group} ${t.cliMethod}\` |`);
+    }
+    lines.push("");
     lines.push("**Recommended call order for agents**");
     lines.push("");
     lines.push(`0. Anchor at L0 — feed the user's raw company name into the ${getLayerCount("L0")} L0 tool (\`search_companies\`); lock onto a USCC + official name.`);
     lines.push(`1. Ascend to L1 — pick ONE of the ${getLayerCount("L1")} overview tools with the anchored USCC.`);
     lines.push("2. Read `_summary` + `drill_down` hints in the response.");
-    lines.push(`3. Drill to L2 for a specific dimension (items + totals; ${getLayerCount("L2")} tools).`);
+    lines.push(`3. Drill to L2 for a specific dimension (items + totals; ${getLayerCount("L2")} tools). Unsure which L2 → default to that facet's L2★ 优先 (table above).`);
     lines.push(`4. Reach L3 for id-based detail, \`search_*\`, or vertical SKILL tools (${getLayerCount("L3")} tools).`);
     lines.push("");
     lines.push("**Discover each layer**");
@@ -175,6 +206,24 @@ function renderLayerListText(spec, tools) {
     lines.push(`${spec.layer} · ${spec.title}  (${n} tool${n === 1 ? "" : "s"})`);
     lines.push(`Trigger: ${spec.trigger}`);
     lines.push("");
+    // L2 优先置顶（只在 L2 list 渲染）
+    if (spec.layer === "L2") {
+        const prio = tools.filter((t) => t.priority);
+        if (prio.length > 0) {
+            lines.push(`★ L2 优先（"L2★ 队副"，${prio.length} 个，每 facet 1 个）`);
+            lines.push("  Agent 拿到 L1 _summary 不确定走哪个 L2 时，默认推这 6 个之一。");
+            const groupsOrder = getCategories().map((c) => c.group);
+            const orderIdx = new Map();
+            groupsOrder.forEach((g, i) => orderIdx.set(g, i));
+            const sortedPrio = [...prio].sort((a, b) => (orderIdx.get(a.group) ?? 999) - (orderIdx.get(b.group) ?? 999));
+            for (const t of sortedPrio) {
+                const cli = `tyc ${t.group} ${t.cliMethod}`;
+                lines.push(`  ★ ${pad(t.group, 22)} ${pad(t.name, 36)}  ${cli}`);
+                lines.push(`      ${oneLine(t.description)}`);
+            }
+            lines.push("");
+        }
+    }
     // 按 group 分组打印（按 categories 中声明顺序）
     const groupsOrder = getCategories().map((c) => c.group);
     const grouped = new Map();
@@ -191,7 +240,8 @@ function renderLayerListText(spec, tools) {
         lines.push(`── ${g}  (${zh}, ${arr.length}) ──`);
         for (const t of arr) {
             const cli = `tyc ${t.group} ${t.cliMethod}`;
-            lines.push(`  ${pad(t.name, 46)}  ${cli}`);
+            const star = t.priority ? "★ " : "  ";
+            lines.push(`  ${star}${pad(t.name, 46)}  ${cli}`);
             lines.push(`    ${oneLine(t.description)}`);
         }
         lines.push("");
@@ -207,6 +257,27 @@ function renderLayerListMarkdown(spec, tools) {
     lines.push(`> **${n} tool${n === 1 ? "" : "s"}** · ${spec.summary}  `);
     lines.push(`> Trigger: ${spec.trigger}`);
     lines.push("");
+    // L2 优先置顶（只在 L2 list 渲染）
+    if (spec.layer === "L2") {
+        const prio = tools.filter((t) => t.priority);
+        if (prio.length > 0) {
+            const groupsOrder = getCategories().map((c) => c.group);
+            const orderIdx = new Map();
+            groupsOrder.forEach((g, i) => orderIdx.set(g, i));
+            const sortedPrio = [...prio].sort((a, b) => (orderIdx.get(a.group) ?? 999) - (orderIdx.get(b.group) ?? 999));
+            lines.push(`## ★ L2 优先（\`L2★ 队副\`，${prio.length} 个）`);
+            lines.push("");
+            lines.push("> 每 facet 1 个；Agent 拿到 L1 `_summary` 不确定走哪个 L2 时，默认推这 6 个之一。");
+            lines.push("");
+            lines.push("| ★ | facet | Tool | CLI | Description |");
+            lines.push("|---|---|---|---|---|");
+            for (const t of sortedPrio) {
+                const cli = `\`tyc ${t.group} ${t.cliMethod}\``;
+                lines.push(`| ★ | ${t.group} | \`${t.name}\` | ${cli} | ${escapeCell(oneLine(t.description))} |`);
+            }
+            lines.push("");
+        }
+    }
     const groupsOrder = getCategories().map((c) => c.group);
     const grouped = new Map();
     for (const t of tools) {
@@ -225,7 +296,8 @@ function renderLayerListMarkdown(spec, tools) {
         lines.push("|---|---|---|");
         for (const t of arr) {
             const cli = `\`tyc ${t.group} ${t.cliMethod}\``;
-            lines.push(`| \`${t.name}\` | ${cli} | ${escapeCell(oneLine(t.description))} |`);
+            const name = t.priority ? `★ \`${t.name}\`` : `\`${t.name}\``;
+            lines.push(`| ${name} | ${cli} | ${escapeCell(oneLine(t.description))} |`);
         }
         lines.push("");
     }

package/dist/config.js

@@ -1,17 +1,17 @@
 // ~/.tyc/config.json 读写
 //
 // 配置文件格式与通用 MCP 客户端保持一致：
-//   { "url": "https://ai-mcp.tianyancha.com/mcp",
+//   { "url": "https://mcp.tianyancha.com/v1",
 //     "headers": { "Authorization": "xxxx" } }
 //
 // 默认端点指向 tyc 官方生产 MCP；本地调试通过
-//   tyc init --url http://localhost:8080/mcp 或 TYC_MCP_ENDPOINT 环境变量覆盖。
+//   tyc init --url http://localhost:8080/v1 或 TYC_MCP_ENDPOINT 环境变量覆盖。
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 const CONFIG_DIR = join(homedir(), ".tyc");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-export const DEFAULT_MCP_URL = "https://ai-mcp.tianyancha.com/mcp";
+export const DEFAULT_MCP_URL = "https://mcp.tianyancha.com/v1";
 export function loadConfig() {
     if (!existsSync(CONFIG_FILE))
         return null;

package/dist/index.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import { registerInitCommand } from "./commands/init.js";
 import { registerCategoryCommands } from "./commands/category.js";
 import { registerLayerCommands } from "./commands/layers.js";
-import { getCategories, getLayerCount, getTotalCount, } from "./registry.js";
+import { getCategories, getLayerCount, getPriorityTools, getTotalCount, } from "./registry.js";
 // 顶层 help：把"最懂 AI 的 CLI"落在 4 层架构 + 调用顺序 + 可发现性上。
 // Agent 看 tyc --help 时应立刻读懂"先 L0 锚定企业，再 L1 概览，再 L2 下钻，最后 L3 详情"这条主线。
 const helpText = `
@@ -16,7 +16,7 @@ ARCHITECTURE — Layered Tool Discovery for LLM Agents
 
     ┌─ L0  Resolve       ${pad(getLayerCount("L0"), 3)} tool    entity resolution · 简称/曾用名/模糊名 → 精确企业
     ├─ L1  Overview     ${pad(getLayerCount("L1"), 3)} tools   one captain per facet · returns _summary + drill_down
-    ├─ L2  Drill-down   ${pad(getLayerCount("L2"), 3)} tools   one-hop into a specific data dimension
+    ├─ L2  Drill-down   ${pad(getLayerCount("L2"), 3)} tools   one-hop into a specific data dimension (★ = L2 优先, see below)
     └─ L3  Specialized  ${pad(getLayerCount("L3"), 3)} tools   id-based detail · search_* · vertical SKILLs
 
   Recommended call order:
@@ -28,6 +28,7 @@ ARCHITECTURE — Layered Tool Discovery for LLM Agents
                         anchored USCC. Read the response's _summary + drill_down.
     2. Descend to L2.  Follow hints to a specific dimension
                         (shareholders / litigation / patents / annual reports …).
+                        If unsure which L2, default to that facet's L2★ 优先 (below).
     3. Land on L3.     When L2 returns a list item with an \`id\`, a \`search_*\`
                         need arises, or a vertical SKILL is activated.
 
@@ -36,15 +37,23 @@ ARCHITECTURE — Layered Tool Discovery for LLM Agents
   in hand) wastes downstream calls on the wrong entity.
   Default LLM surface = L0 + L1 = ${getLayerCount("L0") + getLayerCount("L1")} tools (≤ 15-tool exposure limit).
 
+L2 优先 ★ — \`L2★ 队副\`（${getPriorityTools().length} 个，每 facet 1 个）
+
+  Agent 拿到 L1 _summary 后若不确定走哪个 L2，对应 facet 的"L2 优先"是默认下钻：
+
+${renderPriorityLines()}
+
+  Detail: tyc layers / tyc L2 list   (★ marks priority rows)
+
 DISCOVER BY LAYER
 
-  tyc layers              one-screen architecture map
+  tyc layers              one-screen architecture map (含 L2 优先映射)
   tyc L0 list             list the ${getLayerCount("L0")} L0 tool (entity-resolve layer)
   tyc L1 list             list all ${getLayerCount("L1")} L1 tools (overview, grouped)
-  tyc L2 list             list all ${getLayerCount("L2")} L2 tools (drill-down, grouped)
+  tyc L2 list             list all ${getLayerCount("L2")} L2 tools (drill-down; ★ priority pinned to top)
   tyc L3 list             list all ${getLayerCount("L3")} L3 tools (specialized, grouped)
   tyc L0 list --md        Markdown tables (agent on-screen)
-  tyc L0 list --json      machine-readable JSON (id · cli · params · description)
+  tyc L0 list --json      machine-readable JSON (id · cli · params · description · priority)
 
 DISCOVER BY CATEGORY (orthogonal to layers, 6 groups)
 
@@ -59,7 +68,7 @@ OUTPUT FORMATS (mutually exclusive, priority: --md > --pretty > default)
 
 SETUP
 
-  tyc init --authorization <KEY>                        default https://ai-mcp.tianyancha.com/mcp
+  tyc init --authorization <KEY>                        default https://mcp.tianyancha.com/v1
   tyc init --url <MCP_URL> --authorization <KEY>        local / self-hosted
 
 Every tool returns tyc OpenAPI native English keys verbatim. The MCP Server
@@ -78,6 +87,13 @@ function renderCategoryLines() {
     }
     return lines.join("\n");
 }
+function renderPriorityLines() {
+    const lines = [];
+    for (const t of getPriorityTools()) {
+        lines.push(`  ★ ${t.group.padEnd(22)} ${t.name.padEnd(36)} (tyc ${t.group} ${t.cliMethod})`);
+    }
+    return lines.join("\n");
+}
 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)`)

package/dist/registry.js

@@ -62,3 +62,13 @@ export function getLayerCount(layer) {
 export function getCategoryName(group) {
     return getCategories().find((c) => c.group === group)?.name_zh ?? group;
 }
+// 6 个 L2 优先工具（"L2★ 队副"）：每 facet 1 个，Agent 在 L1 _summary 之后
+// 若不确定该往哪个 L2 钻，默认推这 6 个之一。order 与 categories 声明顺序一致。
+export function getPriorityTools() {
+    const groupsOrder = getCategories().map((c) => c.group);
+    const orderIdx = new Map();
+    groupsOrder.forEach((g, i) => orderIdx.set(g, i));
+    return load()
+        .tools.filter((t) => t.priority === true)
+        .sort((a, b) => (orderIdx.get(a.group) ?? 999) - (orderIdx.get(b.group) ?? 999));
+}

package/package.json

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