tyc-cli 0.1.1 → 0.2.0

package/dist/commands/category.js

@@ -1,70 +1,107 @@
 import { getCategories, getToolsByGroup } from "../registry.js";
-import { getAuthorization } from "../config.js";
-import { runTool } from "../aggregator.js";
-import { applyTransformer } from "../transformer.js";
+import { resolveConfig } from "../config.js";
+import { callTool } from "../mcpClient.js";
 import { jsonToMarkdown } from "../utils/jsonToMarkdown.js";
-// 动态注册：按 api-registry.yaml 生成 `tyc <group> <method>` 命令。
 export function registerCategoryCommands(program) {
-    const categories = getCategories();
-    for (const cat of categories) {
+    for (const cat of getCategories()) {
+        const tools = getToolsByGroup(cat.group);
+        const layerCounts = countLayers(tools);
         const catCmd = program
             .command(cat.group)
-            .description(`${cat.name_zh}（${cat.tool_count} 个工具）`);
-        const tools = getToolsByGroup(cat.group);
+            .description(`${cat.name_zh}（${cat.tool_count} 个 · L0=${layerCounts.L0} L1=${layerCounts.L1} L2=${layerCounts.L2} L3=${layerCounts.L3}）`);
         for (const tool of tools) {
-            const params = tool.params || [];
-            const requiredParams = params.filter((p) => p.required);
-            const optionalParams = params.filter((p) => !p.required);
-            // 第一个必填参数作为位置参数
-            const positional = requiredParams[0] || null;
-            const remainingRequired = requiredParams.slice(1);
-            let methodCmd = catCmd
-                .command(tool.cliMethod)
-                .description(tool.description);
-            if (positional) {
-                methodCmd = methodCmd.argument(`<${positional.name}>`, positional.description);
-            }
-            for (const p of remainingRequired) {
-                methodCmd = methodCmd.requiredOption(`--${p.name} <value>`, p.description);
-            }
-            for (const p of optionalParams) {
-                methodCmd = methodCmd.option(`--${p.name} <value>`, p.description);
-            }
-            const bound = tool;
-            methodCmd.action(async (posVal, options) => {
-                const auth = getAuthorization();
-                const args = {};
-                if (positional && posVal)
-                    args[positional.name] = posVal;
-                for (const p of [...remainingRequired, ...optionalParams]) {
-                    if (options[p.name] !== undefined)
-                        args[p.name] = options[p.name];
-                }
-                try {
-                    const { results, warnings } = await runTool(bound, args, auth, {
-                        verbose: !!program.opts().verbose,
-                    });
-                    const out = applyTransformer(bound, results, warnings);
-                    // 输出格式优先级：--md > --pretty > 紧凑 JSON
-                    const opts = program.opts();
-                    let text;
-                    if (opts.md) {
-                        text = jsonToMarkdown(out, bound.name);
-                    }
-                    else if (opts.pretty) {
-                        text = JSON.stringify(out, null, 2);
-                    }
-                    else {
-                        text = JSON.stringify(out);
-                    }
-                    console.log(text);
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    console.error(`请求失败: ${msg}`);
-                    process.exit(1);
-                }
-            });
+            bindMethod(catCmd, tool, program);
+        }
+    }
+}
+function countLayers(tools) {
+    const c = { L0: 0, L1: 0, L2: 0, L3: 0 };
+    for (const t of tools)
+        c[t.layer] += 1;
+    return c;
+}
+function bindMethod(catCmd, tool, program) {
+    const params = tool.params || [];
+    const requiredParams = params.filter((p) => p.required);
+    const optionalParams = params.filter((p) => !p.required);
+    const positional = requiredParams[0] || null;
+    const remainingRequired = requiredParams.slice(1);
+    // 在描述首部打上 [LX] 徽章，让 `tyc <group> --help` / `tyc <group> <method> --help`
+    // 都能直观看到分层信息；徽章不影响 Agent 对 description 的语义理解。
+    let methodCmd = catCmd
+        .command(tool.cliMethod)
+        .description(`[${tool.layer}] ${tool.description}`);
+    if (positional) {
+        methodCmd = methodCmd.argument(`<${positional.name}>`, positional.description);
+    }
+    for (const p of remainingRequired) {
+        methodCmd = methodCmd.requiredOption(`--${p.name} <value>`, p.description);
+    }
+    for (const p of optionalParams) {
+        methodCmd = methodCmd.option(`--${p.name} <value>`, p.description);
+    }
+    methodCmd.action(async (posVal, options) => {
+        const args = {};
+        if (positional && posVal)
+            args[positional.name] = posVal;
+        for (const p of [...remainingRequired, ...optionalParams]) {
+            if (options[p.name] !== undefined)
+                args[p.name] = options[p.name];
+        }
+        const cfg = resolveConfig();
+        const opts = program.opts();
+        const verbose = !!opts.verbose;
+        try {
+            const result = await callTool(cfg, tool.name, args, { verbose });
+            emit(result, opts, tool.name);
         }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`请求失败: ${msg}`);
+            process.exit(1);
+        }
+    });
+}
+function emit(result, opts, toolName) {
+    // MCP 业务错误：isError + content[0].text = 错误描述
+    if (result.isError) {
+        const errText = extractText(result) || "未知业务错误";
+        console.error(errText);
+        process.exit(1);
+    }
+    const text = extractText(result);
+    if (text === null) {
+        console.error("tools/call 返回无可解析内容");
+        process.exit(1);
+    }
+    // MCP Server 返回的是 JSON 字符串（已完成多源合并 / 时间戳格式化 /
+    // _summary / _empty / _warnings 注入）。CLI 只做呈现格式化。
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        // 非 JSON 文本：直接原样输出
+        process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+        return;
+    }
+    let rendered;
+    if (opts.md) {
+        rendered = jsonToMarkdown(payload, toolName);
+    }
+    else if (opts.pretty) {
+        rendered = JSON.stringify(payload, null, 2);
+    }
+    else {
+        rendered = JSON.stringify(payload);
+    }
+    console.log(rendered);
+}
+function extractText(result) {
+    const content = result.content || [];
+    for (const c of content) {
+        if (typeof c.text === "string" && c.text.length > 0)
+            return c.text;
     }
+    return null;
 }

package/dist/commands/init.js

@@ -1,14 +1,64 @@
-import { saveConfig, loadConfig } from "../config.js";
+import { DEFAULT_MCP_URL, loadConfig, resolveConfig, saveConfig } from "../config.js";
+import { clearSession } from "../session.js";
+import { ensureSession } from "../mcpClient.js";
 export function registerInitCommand(program) {
     program
         .command("init")
-        .description("配置 Authorization（保存到 ~/.tyc/config.json）")
-        .option("--authorization <token>", "tyc OpenAPI Authorization")
-        .action((opts) => {
-        const existing = loadConfig() || {};
+        .description("配置 MCP endpoint / Authorization（保存到 ~/.tyc/config.json，并校验连通性）")
+        .option("--authorization <token>", "tyc OpenAPI Authorization（写入 headers.Authorization）")
+        .option("--url <url>", `MCP endpoint（默认 ${DEFAULT_MCP_URL}）`)
+        .option("--header <kv...>", "自定义 header，格式 K=V，可重复；留空清除该 key")
+        .option("--clear-session", "仅清除本地 MCP session 缓存（~/.tyc/session.json）")
+        .option("--no-verify", "跳过连通性校验（不发 initialize）")
+        .action(async (opts) => {
+        const cfg = loadConfig() || {};
+        if (!cfg.headers)
+            cfg.headers = {};
+        if (opts.url)
+            cfg.url = opts.url;
+        if (!cfg.url)
+            cfg.url = DEFAULT_MCP_URL;
         if (opts.authorization)
-            existing.authorization = opts.authorization;
-        saveConfig(existing);
-        console.log("已保存到 ~/.tyc/config.json");
+            cfg.headers.Authorization = opts.authorization;
+        if (opts.header && opts.header.length > 0) {
+            for (const kv of opts.header) {
+                const idx = kv.indexOf("=");
+                if (idx < 0) {
+                    console.error(`忽略无效 header（缺 =）：${kv}`);
+                    continue;
+                }
+                const k = kv.slice(0, idx).trim();
+                const v = kv.slice(idx + 1);
+                if (!k)
+                    continue;
+                if (v === "")
+                    delete cfg.headers[k];
+                else
+                    cfg.headers[k] = v;
+            }
+        }
+        saveConfig(cfg);
+        // 任何配置变更都清掉 session 缓存，避免 endpoint/鉴权切换后复用旧 sessionId
+        clearSession();
+        if (opts.clearSession) {
+            console.log("已清除 ~/.tyc/session.json");
+        }
+        console.log(`已保存 ~/.tyc/config.json  (url=${cfg.url})`);
+        if (opts.verify === false) {
+            return;
+        }
+        // 立即发 initialize，拿到 Mcp-Session-Id 落盘；失败则非 0 退出
+        try {
+            const resolved = resolveConfig();
+            const verbose = !!program.opts().verbose;
+            const sess = await ensureSession(resolved, { verbose });
+            console.log(`已建立 MCP session（sessionId=${sess.sessionId.slice(0, 16)}…）`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`MCP 连通性校验失败：${msg}`);
+            console.error("配置已保存；确认 --url 可达后重新运行 tyc init，或加 --no-verify 跳过校验。");
+            process.exit(1);
+        }
     });
 }

package/dist/commands/layers.js

@@ -0,0 +1,245 @@
+import { getCategories, getCategoryName, getLayerCount, getToolsByLayer, getTotalCount, } from "../registry.js";
+const LAYER_SPECS = [
+    {
+        layer: "L0",
+        title: "Resolve · 实体锚定层",
+        summary: "把用户输入(简称 / 曾用名 / 模糊指代)解析成精确企业列表（USCC + 别名 + 状态）。Agent 第 0 跳：所有下游工具都依赖锚定结果。",
+        trigger: '"是哪家公司 / 帮我查 XX / 我想看 X 集团" — 用户给的是名字而非 USCC',
+        contract: "返回候选企业列表（含 USCC、企业全名、注册状态、别名）；Agent 据此挑定唯一企业再走 L1。",
+    },
+    {
+        layer: "L1",
+        title: "Overview · 概要层",
+        summary: "跨维度聚合、总览、评分、实体校验。Agent 拿到 USCC 后的第 1 跳，回包带 _summary + drill_down 线索。",
+        trigger: '"这家公司是什么 / 整体怎么样 / 有没有风险 / 能不能信任"',
+        contract: "不需要你提前知道维度；一次调用就能拿到 _summary + drill_down 线索。",
+    },
+    {
+        layer: "L2",
+        title: "Drill-down · 明细层",
+        summary: "一级数据维度展开：股权 / 诉讼 / 招投标 / 年报 / 知识产权 / 历史工商 / 人员任职 ……",
+        trigger: "L1 `_summary` 指示\"有 X 条 Y\"时，针对该维度精确下钻。",
+        contract: "返回 tyc 英文 key 透传的 items 列表 + 顶层聚合字段。",
+    },
+    {
+        layer: "L3",
+        title: "Specialized · 专业层",
+        summary: "ID 详情、search_*、上市公司专项、私募基金、建筑资质、投资机构、地理位置、人员微查询 ……",
+        trigger: "L2 列表中某条记录的 id 需要展开、或触发垂直行业 SKILL（尽调/风控/知产）。",
+        contract: "面向专业 Agent 和 SKILL Pack；多数需要 id 或二级关键词。",
+    },
+];
+export function registerLayerCommands(program) {
+    registerLayers(program);
+    for (const spec of LAYER_SPECS) {
+        registerLayerCmd(program, spec);
+    }
+}
+function registerLayers(program) {
+    program
+        .command("layers")
+        .description(`一屏总览 tyc-cli 的 4 层工具架构（L0 ${getLayerCount("L0")} / L1 ${getLayerCount("L1")} / L2 ${getLayerCount("L2")} / L3 ${getLayerCount("L3")}），面向 AI Agent 的推荐调用顺序`)
+        .option("--md", "Markdown 表格（适合 Agent 上屏 / 粘进 README）")
+        .option("--json", "机读 JSON（layers 汇总 + 各层工具元数据）")
+        .action((opts) => {
+        if (opts.json) {
+            const payload = {
+                total: getTotalCount(),
+                layers: LAYER_SPECS.map((s) => ({
+                    layer: s.layer,
+                    title: s.title,
+                    count: getLayerCount(s.layer),
+                    trigger: s.trigger,
+                    summary: s.summary,
+                    contract: s.contract,
+                })),
+                categories: getCategories(),
+                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)`,
+                    `4. Reach L3 for id-based detail, search_*, or vertical SKILL tools (${getLayerCount("L3")} tools)`,
+                ],
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        if (opts.md) {
+            console.log(renderLayersMarkdown());
+            return;
+        }
+        console.log(renderLayersText());
+    });
+}
+function registerLayerCmd(program, spec) {
+    const layer = spec.layer;
+    const cmd = program
+        .command(layer)
+        .description(`${spec.title}（${getLayerCount(layer)} 个）— ${spec.summary}`);
+    cmd
+        .command("list")
+        .description(`列出 ${layer} 全部 ${getLayerCount(layer)} 个工具（默认按分类分组文本表格）`)
+        .option("--md", "Markdown 表格（适合 Agent 上屏）")
+        .option("--json", "机读 JSON（工具 ID / cliMethod / 分类 / 参数 / 描述）")
+        .action((opts) => {
+        const tools = getToolsByLayer(layer);
+        if (opts.json) {
+            const payload = {
+                layer,
+                title: spec.title,
+                count: tools.length,
+                trigger: spec.trigger,
+                contract: spec.contract,
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    group: t.group,
+                    category_name_zh: t.categoryNameZh,
+                    cli: `tyc ${t.group} ${t.cliMethod}`,
+                    description: t.description,
+                    params: t.params ?? [],
+                })),
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        if (opts.md) {
+            console.log(renderLayerListMarkdown(spec, tools));
+            return;
+        }
+        console.log(renderLayerListText(spec, tools));
+    });
+}
+// ─────────────────────────── 渲染：tyc layers ───────────────────────────
+function renderLayersText() {
+    const total = getTotalCount();
+    const defaultSurface = getLayerCount("L0") + getLayerCount("L1");
+    const lines = [];
+    lines.push("tyc-cli · Layered Tool Architecture (v5 §3.3 ①)");
+    lines.push(`Total ${total} tools  ·  L0=${getLayerCount("L0")}  L1=${getLayerCount("L1")}  L2=${getLayerCount("L2")}  L3=${getLayerCount("L3")}`);
+    lines.push("Rationale: LLM tool-selection accuracy collapses beyond 30 tools.");
+    lines.push(`  tyc carves L0 into a single entity-resolution tool, so the default LLM`);
+    lines.push(`  surface is L0 + L1 = ${defaultSurface} tools (≤ v5's 15-tool limit);`);
+    lines.push("  L2/L3 are discovered on demand via _summary / drill_down_tools.");
+    lines.push("");
+    for (const s of LAYER_SPECS) {
+        const n = getLayerCount(s.layer);
+        lines.push(`[${s.layer}] ${s.title}  (${n} tool${n === 1 ? "" : "s"})`);
+        lines.push(`      ${s.summary}`);
+        lines.push(`      Trigger: ${s.trigger}`);
+        lines.push(`      Contract: ${s.contract}`);
+        lines.push(`      List:    tyc ${s.layer} list [--md|--json]`);
+        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(`  4. Reach L3 for id-based detail / search_* / vertical SKILL (${getLayerCount("L3")} tools)`);
+    return lines.join("\n");
+}
+function renderLayersMarkdown() {
+    const defaultSurface = getLayerCount("L0") + getLayerCount("L1");
+    const lines = [];
+    lines.push("# tyc-cli · Layered Tool Architecture");
+    lines.push("");
+    lines.push(`> Total **${getTotalCount()}** tools · **L0=${getLayerCount("L0")}** · **L1=${getLayerCount("L1")}** · **L2=${getLayerCount("L2")}** · **L3=${getLayerCount("L3")}**  `);
+    lines.push(`> Design rationale (v5 §3.3 ①): LLM tool-selection accuracy collapses above 30 tools; tyc carves L0 into a dedicated entity-resolution tool so the default LLM surface = L0 + L1 = ${defaultSurface} tools (≤ 15-tool limit), discovers L2/L3 on demand.`);
+    lines.push("");
+    lines.push("| Layer | Tools | Summary | Trigger |");
+    lines.push("|---|---:|---|---|");
+    for (const s of LAYER_SPECS) {
+        lines.push(`| **${s.layer}** ${s.title} | ${getLayerCount(s.layer)} | ${escapeCell(s.summary)} | ${escapeCell(s.trigger)} |`);
+    }
+    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(`4. Reach L3 for id-based detail, \`search_*\`, or vertical SKILL tools (${getLayerCount("L3")} tools).`);
+    lines.push("");
+    lines.push("**Discover each layer**");
+    lines.push("");
+    for (const s of LAYER_SPECS) {
+        lines.push(`- \`tyc ${s.layer} list\` — ${s.title}`);
+    }
+    return lines.join("\n");
+}
+// ─────────────────── 渲染：tyc L0/L1/L2 list ───────────────────
+function renderLayerListText(spec, tools) {
+    const lines = [];
+    const n = tools.length;
+    lines.push(`${spec.layer} · ${spec.title}  (${n} tool${n === 1 ? "" : "s"})`);
+    lines.push(`Trigger: ${spec.trigger}`);
+    lines.push("");
+    // 按 group 分组打印（按 categories 中声明顺序）
+    const groupsOrder = getCategories().map((c) => c.group);
+    const grouped = new Map();
+    for (const t of tools) {
+        const arr = grouped.get(t.group) || [];
+        arr.push(t);
+        grouped.set(t.group, arr);
+    }
+    for (const g of groupsOrder) {
+        const arr = grouped.get(g);
+        if (!arr || arr.length === 0)
+            continue;
+        const zh = getCategoryName(g);
+        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}`);
+            lines.push(`    ${oneLine(t.description)}`);
+        }
+        lines.push("");
+    }
+    lines.push(`Next: read ${spec.contract}`);
+    return lines.join("\n");
+}
+function renderLayerListMarkdown(spec, tools) {
+    const lines = [];
+    const n = tools.length;
+    lines.push(`# ${spec.layer} · ${spec.title}`);
+    lines.push("");
+    lines.push(`> **${n} tool${n === 1 ? "" : "s"}** · ${spec.summary}  `);
+    lines.push(`> Trigger: ${spec.trigger}`);
+    lines.push("");
+    const groupsOrder = getCategories().map((c) => c.group);
+    const grouped = new Map();
+    for (const t of tools) {
+        const arr = grouped.get(t.group) || [];
+        arr.push(t);
+        grouped.set(t.group, arr);
+    }
+    for (const g of groupsOrder) {
+        const arr = grouped.get(g);
+        if (!arr || arr.length === 0)
+            continue;
+        const zh = getCategoryName(g);
+        lines.push(`## ${g} — ${zh}（${arr.length}）`);
+        lines.push("");
+        lines.push("| Tool | CLI | Description |");
+        lines.push("|---|---|---|");
+        for (const t of arr) {
+            const cli = `\`tyc ${t.group} ${t.cliMethod}\``;
+            lines.push(`| \`${t.name}\` | ${cli} | ${escapeCell(oneLine(t.description))} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ─────────────────── utils ───────────────────
+function pad(s, width) {
+    if (s.length >= width)
+        return s;
+    return s + " ".repeat(width - s.length);
+}
+function oneLine(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+function escapeCell(s) {
+    return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}

package/dist/config.js

@@ -1,25 +1,47 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+// ~/.tyc/config.json 读写
+//
+// 配置文件格式与通用 MCP 客户端保持一致：
+//   { "url": "https://ai-mcp.tianyancha.com/mcp",
+//     "headers": { "Authorization": "xxxx" } }
+//
+// 默认端点指向 tyc 官方生产 MCP；本地调试通过
+//   tyc init --url http://localhost:8080/mcp 或 TYC_MCP_ENDPOINT 环境变量覆盖。
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-// ~/.tyc/config.json
 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 function loadConfig() {
     if (!existsSync(CONFIG_FILE))
         return null;
-    const raw = readFileSync(CONFIG_FILE, "utf-8");
-    return JSON.parse(raw);
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
 }
 export function saveConfig(config) {
     if (!existsSync(CONFIG_DIR))
-        mkdirSync(CONFIG_DIR, { recursive: true });
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
     writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    try {
+        chmodSync(CONFIG_FILE, 0o600);
+    }
+    catch { /* best effort */ }
 }
-export function getAuthorization() {
-    const cfg = loadConfig();
-    if (!cfg?.authorization) {
+export function resolveConfig() {
+    const cfg = loadConfig() || {};
+    const url = process.env.TYC_MCP_ENDPOINT || cfg.url || DEFAULT_MCP_URL;
+    const headers = { ...(cfg.headers || {}) };
+    if (!headers.Authorization && process.env.TYC_AUTHORIZATION) {
+        headers.Authorization = process.env.TYC_AUTHORIZATION;
+    }
+    if (!headers.Authorization) {
         console.error("未配置 Authorization。请先运行：tyc init --authorization YOUR_API_KEY");
         process.exit(1);
     }
-    return cfg.authorization;
+    return { url, headers };
 }

package/dist/index.js

@@ -2,15 +2,92 @@
 import { Command } from "commander";
 import { registerInitCommand } from "./commands/init.js";
 import { registerCategoryCommands } from "./commands/category.js";
-import { getTotalCount, getCategories } from "./registry.js";
+import { registerLayerCommands } from "./commands/layers.js";
+import { getCategories, getLayerCount, getTotalCount, } from "./registry.js";
+// 顶层 help：把"最懂 AI 的 CLI"落在 4 层架构 + 调用顺序 + 可发现性上。
+// Agent 看 tyc --help 时应立刻读懂"先 L0 锚定企业，再 L1 概览，再 L2 下钻，最后 L3 详情"这条主线。
+const helpText = `
+ARCHITECTURE — Layered Tool Discovery for LLM Agents (v5 §3.3 ①)
+
+  Cognitive research shows LLM tool-selection accuracy collapses above
+  30 tools (>95% at 10, ~70% at 30, <50% at 100+). tyc counters this with
+  a 4-layer progressive-disclosure architecture, led by a dedicated
+  entity-resolution layer:
+
+    ┌─ L0  Resolve       ${pad(getLayerCount("L0"), 3)} tool    entity resolution · 简称/曾用名/模糊名 → 精确企业
+    ├─ L1  Overview     ${pad(getLayerCount("L1"), 3)} tools   cross-facet aggregation · scoring · entity-check
+    ├─ L2  Drill-down   ${pad(getLayerCount("L2"), 3)} tools   one-hop into a specific data dimension
+    └─ L3  Specialized  ${pad(getLayerCount("L3"), 3)} tools   id-based detail · search_* · vertical SKILLs
+
+  Recommended call order:
+
+    0. Anchor at L0.   Feed the user's raw company name (可能是简称/曾用名/模糊
+                        指代) into \`search_companies\`; lock onto one entity
+                        with a USCC + official name before anything else.
+    1. Ascend to L1.   Pick ONE of the ${getLayerCount("L1")} overview tools with the
+                        anchored USCC. Read the response's _summary + drill_down.
+    2. Descend to L2.  Follow hints to a specific dimension
+                        (shareholders / litigation / patents / annual reports …).
+    3. Land on L3.     When L2 returns a list item with an \`id\`, a \`search_*\`
+                        need arises, or a vertical SKILL is activated.
+
+  Rule of thumb: the smaller the layer number, the higher the information
+  density per token. L0 is MANDATORY — skipping it (without a USCC already
+  in hand) wastes downstream calls on the wrong entity.
+  Default LLM surface = L0 + L1 = ${getLayerCount("L0") + getLayerCount("L1")} tools (≤ v5's 15-tool limit).
+
+DISCOVER BY LAYER
+
+  tyc layers              one-screen architecture map
+  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 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)
+
+DISCOVER BY CATEGORY (orthogonal to layers, 6 groups)
+
+${renderCategoryLines()}
+
+OUTPUT FORMATS (mutually exclusive, priority: --md > --pretty > default)
+
+  (default)    compact single-line JSON (pipe-friendly)
+  --pretty     indented JSON (debug)
+  --md         Markdown tables (human + agent on-screen)
+  --verbose    also print MCP request details to stderr
+
+SETUP
+
+  tyc init --authorization <KEY>                        default https://ai-mcp.tianyancha.com/mcp
+  tyc init --url <MCP_URL> --authorization <KEY>        local / self-hosted
+
+Every tool returns tyc OpenAPI native English keys verbatim. The MCP Server
+handles multi-source merge, Asia/Shanghai timestamp formatting, _summary
+injection, and empty-result normalization — the CLI just tells the Agent
+where the data is and what it looks like.
+`;
+function pad(n, width) {
+    const s = String(n);
+    return s.length >= width ? s : " ".repeat(width - s.length) + s;
+}
+function renderCategoryLines() {
+    const lines = [];
+    for (const c of getCategories()) {
+        lines.push(`  tyc ${c.group.padEnd(22)} ${c.name_zh}  (${c.tool_count} tools)`);
+    }
+    return lines.join("\n");
+}
 const program = new Command()
     .name("tyc")
-    .description(`天眼查 CLI — ${getTotalCount()} 个业务语义聚合工具 · ${getCategories().length} 个分类 · 返回 tyc 英文 key 透传结构`)
-    .version("0.1.0")
+    .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 空格）")
     .option("--md", "Markdown 表格化输出（适合人类阅读 / Agent 上屏）")
-    .option("--verbose", "输出请求详情到 stderr");
+    .option("--verbose", "打印 MCP 请求详情到 stderr")
+    .addHelpText("after", helpText);
 registerInitCommand(program);
+registerLayerCommands(program);
 registerCategoryCommands(program);
 program.parseAsync(process.argv).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);