echopai 2.1.0 → 2.3.0

package/dist/verbs/concepts.js

@@ -0,0 +1,393 @@
+/**
+ * `echopai concepts ...` + MCP tools for the concept-index family.
+ *
+ * Concept = THS / DC / 自定义 概念板块。所有指数采用 PLAN_CONCEPT_INDUSTRY_QUOTE
+ * §5.4 链式等权计算（base 1000）。9 个子端点：
+ *
+ *   list             —— 全量概念元数据 + 6 字段实时快照（默认 active）
+ *   snapshot         —— 全量 Redis snapshot hash（可 codes= 过滤）
+ *   show             —— 单个概念 meta + 当前成份股 + 个股最新行情
+ *   alerts           —— 当前激活的概念异动（big_move / limit_up_cluster）
+ *   alerts-history   —— 24h 异动历史（可按 rule / 时窗过滤）
+ *   daily-bars       —— 概念指数日 K（链式等权）
+ *   minute-bars      —— 概念指数分钟 K（max 7 天/请求）
+ *   news             —— 与概念名匹配的相关新闻
+ *   views            —— 关联券商观点（concept_views × broker_views JOIN）
+ *
+ * MCP 注册为 9 个 discrete tool；CLI 收纳到单个 `concepts` noun 下子命令。
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+const STATUS_VALUES = ["active", "pending_review", "deprecated"];
+// Server-supported sort keys (stockpulse-rs concepts.rs sort_by chain).
+const SERVER_SORT_VALUES = ["pct", "amount", "limit_up", "stock_count"];
+// Client-side sort keys — fetched with server sort=pct (any), then re-sorted
+// over the live snapshot fields returned per item. 涨速 (`speed_3min`) /
+// 换手率 (no per-concept turnover; here it means 个股层面 turnover_rate
+// aggregate is not present — `turnover` is alias of `amount`).
+const CLIENT_SORT_VALUES = ["speed"];
+const SORT_VALUES = [...SERVER_SORT_VALUES, ...CLIENT_SORT_VALUES];
+const RULE_VALUES = ["big_move", "limit_up_cluster"];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function clampInt(raw, min, max, fallback) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+function parseConceptId(raw) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`concept_id must be a positive integer (got ${raw})`);
+    }
+    return n;
+}
+export const conceptsListSpec = {
+    name: "concepts_list",
+    description: "List concepts with live 6-field snapshot (pct_change / index_value / up_count / down_count / limit_up_count / amount / speed_3min) joined from Redis. Default sort by pct (desc). Use as the entry point for browsing the concept universe — narrow down by sort and pick top movers, then drill in with `concepts_show` / `concepts_daily_bars`. Sort keys: `pct` / `amount` / `limit_up` / `stock_count` are pushed to the server; `speed` is applied client-side over `speed_3min` (3-minute pct delta).",
+    inputSchema: {
+        status: z.enum(STATUS_VALUES).default("active").describe("Concept status filter"),
+        sort: z
+            .enum(SORT_VALUES)
+            .default("pct")
+            .describe("Sort field: pct / amount / limit_up / stock_count / speed"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .default(500)
+            .describe("Max items (1-1000, default 500)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.list"];
+        if (!op)
+            throw new Error("concepts.list op missing");
+        const sort = String(args.sort ?? "pct");
+        const isClientSort = CLIENT_SORT_VALUES.includes(sort);
+        // Client-side sort: fetch the full universe (server max 1000) so the
+        // re-rank sees every concept, then slice to user-requested `limit`.
+        // Server-side sort: pass-through (server enforces limit honestly).
+        const serverArgs = {
+            status: args.status,
+            sort: isClientSort ? "pct" : sort,
+            limit: isClientSort ? 1000 : args.limit,
+        };
+        const env = await callOp(op, serverArgs, ctx);
+        if (!isClientSort)
+            return env;
+        return resortListEnvelopeBySpeed(env, Number(args.limit ?? 500));
+    },
+    backingOps: ["concepts.list"],
+};
+function resortListEnvelopeBySpeed(env, limit) {
+    const body = env.data;
+    if (!body || typeof body !== "object" || !Array.isArray(body.items)) {
+        return env;
+    }
+    const items = body.items.slice();
+    items.sort((a, b) => {
+        const av = numericOrNeg(a.speed_3min);
+        const bv = numericOrNeg(b.speed_3min);
+        return bv - av;
+    });
+    const sliced = items.slice(0, Math.max(1, Math.floor(limit)));
+    const data = { ...body, items: sliced };
+    const meta = { ...(env.meta ?? {}), client_sort: "speed" };
+    return { data, meta };
+}
+function numericOrNeg(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return Number.NEGATIVE_INFINITY;
+}
+export const conceptsSnapshotSpec = {
+    name: "concepts_snapshot",
+    description: "Bulk Redis snapshot of all concepts. Use `codes` (comma-separated concept_id list) to filter; omit for the full set. Cheaper than `concepts_list` when only the live numbers are needed without joining meta.",
+    inputSchema: {
+        codes: z
+            .string()
+            .optional()
+            .describe("Comma-separated concept_id list (e.g. `1,2,3`); omit for all."),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.snapshot"];
+        if (!op)
+            throw new Error("concepts.snapshot op missing");
+        const callArgs = {};
+        if (args.codes)
+            callArgs.codes = args.codes;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["concepts.snapshot"],
+};
+export const conceptsShowSpec = {
+    name: "concepts_show",
+    description: "Detail for one concept: meta (full_name / source / status / approved_at / first_listed_at) plus current member securities with their latest snapshots. Use after `concepts_list` to inspect a specific theme.",
+    inputSchema: {
+        concept_id: z.number().int().positive().describe("Concept primary key (PG concepts.id)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.show"];
+        if (!op)
+            throw new Error("concepts.show op missing");
+        return callOp(op, { concept_id: args.concept_id }, ctx);
+    },
+    backingOps: ["concepts.show"],
+};
+export const conceptsAlertsSpec = {
+    name: "concepts_alerts",
+    description: "Currently active concept alerts. Two rules: `big_move` (|pct_change| > 3%) and `limit_up_cluster` (limit_up_count >= 3 AND stock_count >= 5). Cheap, non-billable. Use as the agent's signal for 'which themes are running hot right now'.",
+    inputSchema: {},
+    handler: async (_args, ctx) => {
+        const op = OPERATIONS["concepts.alerts"];
+        if (!op)
+            throw new Error("concepts.alerts op missing");
+        return callOp(op, {}, ctx);
+    },
+    backingOps: ["concepts.alerts"],
+};
+export const conceptsAlertsHistorySpec = {
+    name: "concepts_alerts_history",
+    description: "Concept-alert historical events (default last 24h). Filter by `rule` (big_move / limit_up_cluster) and Unix-ms `from`/`to` window. Used by AI agent / admin to review what fired and when.",
+    inputSchema: {
+        from: z
+            .number()
+            .int()
+            .optional()
+            .describe("Unix ms; default = now - 24h"),
+        to: z.number().int().optional().describe("Unix ms; default = now"),
+        rule: z.enum(RULE_VALUES).optional().describe("Filter by alert rule"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(2000)
+            .default(500)
+            .describe("Max items (1-2000, default 500)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.alerts-history"];
+        if (!op)
+            throw new Error("concepts.alerts-history op missing");
+        const callArgs = { limit: args.limit };
+        if (args.from !== undefined)
+            callArgs.from = args.from;
+        if (args.to !== undefined)
+            callArgs.to = args.to;
+        if (args.rule)
+            callArgs.rule = args.rule;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["concepts.alerts-history"],
+};
+export const conceptsDailyBarsSpec = {
+    name: "concepts_daily_bars",
+    description: "Daily OHLC for a concept index (chain-linked equal-weight, base 1000). Returns breadth fields and `is_backfilled` flag. Requires `bars:read` scope.",
+    inputSchema: {
+        concept_id: z.number().int().positive().describe("Concept primary key"),
+        from: z.string().regex(DATE_RE).describe("Inclusive start date YYYY-MM-DD"),
+        to: z.string().regex(DATE_RE).describe("Inclusive end date YYYY-MM-DD"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.daily-bars"];
+        if (!op)
+            throw new Error("concepts.daily-bars op missing");
+        return callOp(op, { concept_id: args.concept_id, from: args.from, to: args.to }, ctx);
+    },
+    backingOps: ["concepts.daily-bars"],
+};
+export const conceptsMinuteBarsSpec = {
+    name: "concepts_minute_bars",
+    description: "Concept-index minute-level OHLC (chain-linked equal-weight, base 1000). Max 7 days per request. Requires `bars:read` scope.",
+    inputSchema: {
+        concept_id: z.number().int().positive().describe("Concept primary key"),
+        from: z.string().regex(DATE_RE).describe("Inclusive start date YYYY-MM-DD"),
+        to: z.string().regex(DATE_RE).describe("Inclusive end date YYYY-MM-DD (max 7 days)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.minute-bars"];
+        if (!op)
+            throw new Error("concepts.minute-bars op missing");
+        return callOp(op, { concept_id: args.concept_id, from: args.from, to: args.to }, ctx);
+    },
+    backingOps: ["concepts.minute-bars"],
+};
+export const conceptsNewsSpec = {
+    name: "concepts_news",
+    description: "Recent news mentioning the concept name (ILIKE on news.title + content). Short-term implementation; long-term will switch to AI tagging. Requires `news:read` scope.",
+    inputSchema: {
+        concept_id: z.number().int().positive().describe("Concept primary key"),
+        days: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Lookback window in days (1-365, default 30)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Max items (1-200, default 50)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.news"];
+        if (!op)
+            throw new Error("concepts.news op missing");
+        return callOp(op, { concept_id: args.concept_id, days: args.days, limit: args.limit }, ctx);
+    },
+    backingOps: ["concepts.news"],
+};
+export const conceptsViewsSpec = {
+    name: "concepts_views",
+    description: "Broker views associated with a concept (concept_views × broker_views, ai_status=done), sorted by published_at desc. Primary research source for a theme. Requires `views:read` scope.",
+    inputSchema: {
+        concept_id: z.number().int().positive().describe("Concept primary key"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Max items (1-200, default 50)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["concepts.views"];
+        if (!op)
+            throw new Error("concepts.views op missing");
+        return callOp(op, { concept_id: args.concept_id, limit: args.limit }, ctx);
+    },
+    backingOps: ["concepts.views"],
+};
+export function buildConceptsCommand() {
+    const cmd = new Command("concepts").description("Concept indices — list / snapshot / show / alerts / alerts-history / daily-bars / minute-bars / news / views.");
+    const list = cmd.command("list").description(conceptsListSpec.description);
+    list.addOption(new Option("--status <s>", "Status filter").choices([...STATUS_VALUES]).default("active"));
+    list.addOption(new Option("--sort <field>", "Sort field").choices([...SORT_VALUES]).default("pct"));
+    list.addOption(new Option("--limit <n>", "Max items (1-1000)").default("500"));
+    list.action(async (opts) => {
+        if (!OPERATIONS["concepts.list"]) {
+            emitVerbError("internal_error", "concepts.list missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsListSpec.handler({
+            status: opts.status,
+            sort: opts.sort,
+            limit: clampInt(opts.limit, 1, 1000, 500),
+        }, ctx));
+    });
+    const snapshot = cmd.command("snapshot").description(conceptsSnapshotSpec.description);
+    snapshot.addOption(new Option("--codes <ids>", "Comma-separated concept_id list"));
+    snapshot.action(async (opts) => {
+        if (!OPERATIONS["concepts.snapshot"]) {
+            emitVerbError("internal_error", "concepts.snapshot missing", undefined, 2);
+        }
+        const args = {};
+        if (opts.codes)
+            args.codes = opts.codes;
+        await executeVerb(async (ctx) => conceptsSnapshotSpec.handler(args, ctx));
+    });
+    const show = cmd
+        .command("show <concept_id>")
+        .description(conceptsShowSpec.description);
+    show.action(async (conceptIdRaw) => {
+        if (!OPERATIONS["concepts.show"]) {
+            emitVerbError("internal_error", "concepts.show missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsShowSpec.handler({ concept_id: parseConceptId(conceptIdRaw) }, ctx));
+    });
+    const alerts = cmd.command("alerts").description(conceptsAlertsSpec.description);
+    alerts.action(async () => {
+        if (!OPERATIONS["concepts.alerts"]) {
+            emitVerbError("internal_error", "concepts.alerts missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsAlertsSpec.handler({}, ctx));
+    });
+    const alertsHist = cmd
+        .command("alerts-history")
+        .description(conceptsAlertsHistorySpec.description);
+    alertsHist.addOption(new Option("--from <unix_ms>", "Unix ms lower bound; default now-24h"));
+    alertsHist.addOption(new Option("--to <unix_ms>", "Unix ms upper bound; default now"));
+    alertsHist.addOption(new Option("--rule <r>", "Filter by rule").choices([...RULE_VALUES]));
+    alertsHist.addOption(new Option("--limit <n>", "Max items (1-2000)").default("500"));
+    alertsHist.action(async (opts) => {
+        if (!OPERATIONS["concepts.alerts-history"]) {
+            emitVerbError("internal_error", "concepts.alerts-history missing", undefined, 2);
+        }
+        const args = { limit: clampInt(opts.limit, 1, 2000, 500) };
+        if (opts.from !== undefined) {
+            const n = Math.floor(Number(opts.from));
+            if (Number.isFinite(n))
+                args.from = n;
+        }
+        if (opts.to !== undefined) {
+            const n = Math.floor(Number(opts.to));
+            if (Number.isFinite(n))
+                args.to = n;
+        }
+        if (opts.rule)
+            args.rule = opts.rule;
+        await executeVerb(async (ctx) => conceptsAlertsHistorySpec.handler(args, ctx));
+    });
+    const daily = cmd
+        .command("daily-bars <concept_id>")
+        .description(conceptsDailyBarsSpec.description);
+    daily.addOption(new Option("--from <YYYY-MM-DD>", "Inclusive start date").makeOptionMandatory(true));
+    daily.addOption(new Option("--to <YYYY-MM-DD>", "Inclusive end date").makeOptionMandatory(true));
+    daily.action(async (conceptIdRaw, opts) => {
+        if (!OPERATIONS["concepts.daily-bars"]) {
+            emitVerbError("internal_error", "concepts.daily-bars missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsDailyBarsSpec.handler({ concept_id: parseConceptId(conceptIdRaw), from: opts.from, to: opts.to }, ctx));
+    });
+    const minute = cmd
+        .command("minute-bars <concept_id>")
+        .description(conceptsMinuteBarsSpec.description);
+    minute.addOption(new Option("--from <YYYY-MM-DD>", "Inclusive start date").makeOptionMandatory(true));
+    minute.addOption(new Option("--to <YYYY-MM-DD>", "Inclusive end date (max 7 days)").makeOptionMandatory(true));
+    minute.action(async (conceptIdRaw, opts) => {
+        if (!OPERATIONS["concepts.minute-bars"]) {
+            emitVerbError("internal_error", "concepts.minute-bars missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsMinuteBarsSpec.handler({ concept_id: parseConceptId(conceptIdRaw), from: opts.from, to: opts.to }, ctx));
+    });
+    const news = cmd.command("news <concept_id>").description(conceptsNewsSpec.description);
+    news.addOption(new Option("--days <n>", "Lookback window (1-365)").default("30"));
+    news.addOption(new Option("--limit <n>", "Max items (1-200)").default("50"));
+    news.action(async (conceptIdRaw, opts) => {
+        if (!OPERATIONS["concepts.news"]) {
+            emitVerbError("internal_error", "concepts.news missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsNewsSpec.handler({
+            concept_id: parseConceptId(conceptIdRaw),
+            days: clampInt(opts.days, 1, 365, 30),
+            limit: clampInt(opts.limit, 1, 200, 50),
+        }, ctx));
+    });
+    const views = cmd.command("views <concept_id>").description(conceptsViewsSpec.description);
+    views.addOption(new Option("--limit <n>", "Max items (1-200)").default("50"));
+    views.action(async (conceptIdRaw, opts) => {
+        if (!OPERATIONS["concepts.views"]) {
+            emitVerbError("internal_error", "concepts.views missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => conceptsViewsSpec.handler({
+            concept_id: parseConceptId(conceptIdRaw),
+            limit: clampInt(opts.limit, 1, 200, 50),
+        }, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/digest.js

@@ -3,7 +3,7 @@
  *
  * Killer "one-shot research" verb:
  *
- *   one canonical_code  →  views + research + quote + sentiment + news
+ *   one canonical_code  →  views + quote + snapshot + sentiment + news
  *
  * Plan-doc §3.3 makes this the "agent's opening move": one call returns the
  * full picture of a security. Buckets stay separated (no ranking imposed) so
@@ -24,11 +24,13 @@
  *
  * Why these 5 ops in the fallback:
  *   - views.recent  : PRIMARY research signal (analyst opinions on this code)
- *   - research.entity-performance-list : quality layer for view authors
  *   - quote         : current price / change %
+ *   - financials.quote-snapshot : 14-field valuation (PE/PB/PS/换手/股息/量比) on this code
  *   - sentiment.overview : market regime context (not per-code; intentional —
  *     no per-code sentiment op exists)
- *   - news.search   : SUPPLEMENTARY breadth (event stream filter on code)
+ *   - news.list     : SUPPLEMENTARY breadth (canonical_code-exact news,
+ *                     via news_item_security mapping table — NOT keyword search,
+ *                     since article text never contains 'SSE:600519' literally)
  *
  * Windows differ on purpose: views=168h (7d), news=24h. Encodes the rule
  * that research time-horizon > news time-horizon.
@@ -40,11 +42,15 @@ import { CallApiError } from "../runtime/errors.js";
 import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
 import { callOp } from "../runtime/verb_runner.js";
 /** Buckets in the order the description establishes (views first, news last). */
-const BUCKETS = ["views", "research", "quote", "sentiment", "news"];
+const BUCKETS = ["views", "quote", "snapshot", "sentiment", "news"];
+// digest 故意保持 A 股 only：fan-out 里 quote / 14-field snapshot / sentiment 都是
+// StockPulse Rust API 上的 A 股 endpoint，HK/US 没有 capability（PR #D capability gate
+// 只把 HK/US 加进 search，没有 quote/chart）。混进 HK/US 会得到 partial_failures 一片红。
+// 等 HK/US 行情接入再放开（独立立项）。
 const CODE_REGEX = /^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/;
 export const digestSpec = {
     name: "digest",
-    description: "One-shot research digest for a single security: fan-out across views (PRIMARY), research-entity performance, quote, market sentiment, and supplementary news. Returns separated buckets — does NOT rank views vs news for the agent. Partial failures surface in meta.partial_failures[] without poisoning successful buckets. Use as the agent's first call when asked 'what's going on with <stock>'.",
+    description: "One-shot research digest for a single security: fan-out across views (PRIMARY), quote, 14-field valuation snapshot (PE/PB/PS/turnover/dividend/volume-ratio), market sentiment, and supplementary news. Returns separated buckets — does NOT rank views vs news for the agent. Partial failures surface in meta.partial_failures[] without poisoning successful buckets. Use as the agent's first call when asked 'what's going on with <stock>'. AH dual-listing: for an A+H listed company always pass the A-share canonical (e.g. SSE:601398), not the HK side.",
     inputSchema: {
         code: z
             .string()
@@ -70,7 +76,7 @@ export const digestSpec = {
             .min(1)
             .max(50)
             .default(10)
-            .describe("Per-bucket item cap (views/news). Quote/sentiment/research aren't paginated here."),
+            .describe("Per-bucket item cap (views/news). Quote/snapshot/sentiment aren't paginated here."),
     },
     handler: async (args, ctx) => runDigest(args, ctx),
     // Backing ops are listed in two groups: digest.get is the primary
@@ -84,10 +90,10 @@ export const digestSpec = {
     backingOps: [
         "digest.get",
         "views.recent",
-        "research.entity-performance-list",
         "quote",
+        "financials.quote-snapshot",
         "sentiment.overview",
-        "news.search",
+        "news.list",
     ],
 };
 /**
@@ -153,10 +159,10 @@ function shouldFallbackToFanout(e) {
 function buildBucketCalls(args, ctx) {
     const opsRequired = {
         views: "views.recent",
-        research: "research.entity-performance-list",
         quote: "quote",
+        snapshot: "financials.quote-snapshot",
         sentiment: "sentiment.overview",
-        news: "news.search",
+        news: "news.list",
     };
     const calls = [];
     for (const bucket of BUCKETS) {
@@ -184,18 +190,18 @@ function buildBucketCalls(args, ctx) {
                     limit: args.limit_per_bucket,
                 };
                 break;
-            case "research":
-                opArgs = {};
-                break;
             case "quote":
                 opArgs = { codes: [args.code] };
                 break;
+            case "snapshot":
+                opArgs = { code: args.code };
+                break;
             case "sentiment":
                 opArgs = { scope: "all_a_ex_st" };
                 break;
             case "news":
                 opArgs = {
-                    query: args.code,
+                    security: args.code,
                     since_hours: args.news_hours,
                     limit: args.limit_per_bucket,
                 };
@@ -328,7 +334,10 @@ export function buildDigestCommand() {
     cmd.addOption(new Option("--limit-per-bucket <n>", "Items per bucket (1-50)").default("10"));
     cmd.action(async (opts) => {
         if (!CODE_REGEX.test(opts.code)) {
-            emitVerbError("invalid_args", `code ${JSON.stringify(opts.code)} is not a canonical_code (expected SSE|SZSE|BSE:NNNNNN)`, "Use `echopai lookup --text <name>` to resolve to a canonical_code first.", 1);
+            const isHkUs = /^(HK|US):/.test(opts.code);
+            emitVerbError("invalid_args", `code ${JSON.stringify(opts.code)} is not a canonical_code (expected SSE|SZSE|BSE:NNNNNN)`, isHkUs
+                ? "digest fan-out depends on A-share quote/chart/sentiment endpoints — HK/US not yet supported. Use `search` or `views` for HK/US."
+                : "Use `echopai lookup --text <name>` to resolve to a canonical_code first.", 1);
         }
         const args = {
             code: opts.code,