invesresearch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhanglunet (InvesResearch)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# invesresearch
+
+命令行里的投研工作台。行情、财务、可比、对话式研判、卫星互联网产业信号 —— 全部来自
+[oaf.world](https://oaf.world) 的公开只读 API。
+
+**零依赖、无需注册、无需密钥。**
+
+```bash
+npx invesresearch quote NVDA
+```
+
+```
+标的    US:NVDA
+名称    NVIDIA Corporation · 英伟达
+价格    206.84
+涨跌%   -0.5529
+币种    USD
+总股本  24,221,000,000
+数据源  yfinance
+时间    2026-07-25T11:05:28Z
+```
+
+## 安装
+
+不装也能用（推荐）：
+
+```bash
+npx invesresearch <命令>
+```
+
+想常驻就全局装，`invesresearch` 和短别名 `ires` 都可用：
+
+```bash
+npm install -g invesresearch
+ires quote 0700.HK
+```
+
+要求 **Node.js ≥ 18**（用到内置 `fetch`）。
+
+## 标的代码怎么写
+
+四种写法都认，内部统一映射到后端 uid：
+
+| 你输入 | 解析为 | 说明 |
+| --- | --- | --- |
+| `NVDA` `brk.b` | `US:NVDA` `US:BRK.B` | 美股，纯字母 |
+| `600519` | `SH:600519` | A 股，6 开头 → 沪 |
+| `000001` `300750` | `SZ:000001` `SZ:300750` | A 股，0/3 开头 → 深 |
+| `700` `0700.HK` `09988.HK` | `HK:00700` `HK:00700` `HK:09988` | 港股，自动补零到 5 位 |
+| `600519.SS` `300750.SZ` | `SH:600519` `SZ:300750` | Yahoo 后缀写法 |
+| `US:NVDA` `SH:600519` | 原样 | 直接给 uid 也行 |
+
+不知道代码就先搜：
+
+```bash
+npx invesresearch search 宁德
+```
+
+```
+代码       名称      市场
+SZ:300750  宁德时代  SZ
+HK:03750   宁德时代  HK
+```
+
+## 命令
+
+### 行情与基本面
+
+| 命令 | 说明 |
+| --- | --- |
+| `quote <代码>` | 实时报价（价格/涨跌/总股本） |
+| `search <关键词> [--limit N]` | 全市场名称/代码模糊搜索 |
+| `news <代码> [--limit N] [--zh]` | 个股新闻，`--zh` 附中文标题翻译 |
+| `financials <代码> [--period 2025A] [--cross-check]` | 财务指标，可多源交叉校验 |
+| `history <代码> [--years 5] [--quarter]` | 历年（或历季）财务趋势 |
+| `peers <代码> [--period 2025A]` | 可比公司 PE/PB/PS |
+| `profile <代码> [--period 2025A]` | 公司画像 |
+| `bars <代码> [--days 30]` | 日线 K 线（`--days` 最小 5） |
+| `indices` | 主要指数行情 |
+| `industries` | 已覆盖的行业专题列表 |
+| `industry <key>` | 行业专题详情（成分股 + 财务聚合 + 产业链） |
+| `pulse [key]` | 行业异动预警，默认 `satellite` |
+
+### 研究（模型生成，输出带免责声明）
+
+| 命令 | 说明 |
+| --- | --- |
+| `ask <问题…>` | 对话式投研问答 |
+| `thesis <代码>` | 多空研判 + 护城河 |
+| `compare <代码A> <代码B> […] [--cross-check]` | 同口径多标的对比 |
+
+```bash
+npx invesresearch ask "英伟达的护城河在哪"
+npx invesresearch compare NVDA AMD
+```
+
+### 卫星互联网产业 agent（只读）
+
+| 命令 | 说明 |
+| --- | --- |
+| `events [--limit N] [--thread 主线]` | 产业事件流 |
+| `alerts [--window 7] [--limit N]` | 风险预警（含证伪触发器） |
+| `weekly [--window 7]` | 周度决策报告（markdown） |
+| `companies [--thread 主线]` | 产业链公司卡片 |
+| `thesis-state` | 各主线 thesis 实时评分 |
+| `sources` | 数据来源账本 |
+
+## 全局选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--json`, `-j` | 输出原始 JSON，可管道给 `jq` |
+| `--api <url>` | 覆盖行情 API 端点（默认 `https://api.oaf.world`，亦可用环境变量 `IR_API_BASE`） |
+| `--agent <url>` | 覆盖 agent 端点（默认 `https://agent.oaf.world`，亦可用 `IR_AGENT_BASE`） |
+| `--timeout <ms>` | 请求超时。默认 30s，研究类命令 180s |
+| `--help`, `-h` | 帮助 |
+| `--version`, `-v` | 版本 |
+
+管道用法：
+
+```bash
+npx invesresearch quote 0700.HK --json | jq .price
+npx invesresearch peers NVDA --json | jq -r '.rows[] | "\(.name)\t\(.pe)"'
+npx invesresearch weekly > 周报.md
+```
+
+退出码：`0` 成功 · `1` 请求失败（错误进 stderr，stdout 不产出任何数据）· `2` 用法错误。
+
+## 数据边界（诚实说明）
+
+- **数字来自数据源，不由本工具计算。** CLI 只做参数映射与排版，任何指标、估值、涨跌都是后端返回的原值。
+- **缺数显式降级。** 取不到的字段一律显示 `—`，不会填 0、不会省略、更不会编。
+- **搜索覆盖不对称。** A 股中文名可全量模糊搜；港股/美股认英文、拼音、代码，中文名只覆盖精选清单 —— 港美股搜不到时请改用代码。
+- **`ask` / `thesis` / `compare` 的叙述由模型生成**，其中的数字仍来自确定性计算。输出末尾强制带免责声明。
+- **`compare` 默认不做多源交叉校验**（实测 2 个标的开启后 >200s）。需要时加 `--cross-check`。
+- **预警不命中就是不报警。** `alerts` / `pulse` 返回空表示规则未触发，不是故障。
+
+## 隐私与凭证
+
+本工具**不接受、不读取、不存储任何 token 或密钥**，也从不发送 `Authorization` 头 —— 目标接口本就是公开只读服务。除了你输入的查询参数，不会向任何第三方发送数据，也没有遥测。
+
+## 免责声明
+
+本工具输出仅供研究参考，**不构成投资建议**。投资有风险，决策需谨慎。
+
+## 开发
+
+```bash
+npm test          # node --test，零 devDependencies
+```
+
+## License
+
+MIT（见 [LICENSE](./LICENSE)）。注意：仓库其余部分是 Apache-2.0，本 CLI 单独采用更宽松的 MIT。

package/bin/invesresearch.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { run } from '../src/main.js';
+
+const major = Number(process.versions.node.split('.')[0]);
+if (major < 18) {
+  process.stderr.write(`invesresearch 需要 Node.js >= 18(当前 ${process.versions.node})\n`);
+  process.exit(1);
+}
+
+// 管道给 head/less 时下游会提前关闭 stdout —— 默认行为是抛未捕获的 EPIPE 并打一屏堆栈。
+// 对 CLI 来说 `… | head -5` 是常规用法, 静默按 0 退出才对。
+for (const s of [process.stdout, process.stderr]) {
+  s.on('error', (e) => { if (e && e.code === 'EPIPE') process.exit(0); });
+}
+
+run(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "invesresearch",
+  "version": "0.1.0",
+  "description": "InvesResearch CLI — quotes, fundamentals, research and satellite-industry signals from the public oaf.world APIs. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "invesresearch": "bin/invesresearch.mjs",
+    "ires": "bin/invesresearch.mjs"
+  },
+  "exports": {
+    ".": "./src/main.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "keywords": [
+    "stocks",
+    "quotes",
+    "finance",
+    "research",
+    "cli",
+    "a-share",
+    "hk-stocks",
+    "satellite"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhanglunet/InvesResearch.git",
+    "directory": "cli"
+  },
+  "homepage": "https://oaf.world",
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/args.js

@@ -0,0 +1,32 @@
+// 极简 argv 解析(零依赖)。只支持 --long[=value] 与 -h/-v/-j 三个短别名 —— 够用即可。
+const SHORT = { h: 'help', v: 'version', j: 'json' };
+
+export function parseArgv(argv) {
+  const out = { cmd: null, args: [], flags: {} };
+  let rest = false;
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (rest) { out.args.push(tok); continue; }
+    if (tok === '--') { rest = true; continue; }
+
+    if (tok.startsWith('--')) {
+      const body = tok.slice(2);
+      const eq = body.indexOf('=');
+      if (eq > 0) { out.flags[body.slice(0, eq)] = body.slice(eq + 1); continue; }
+      const next = argv[i + 1];
+      // 后面没东西 / 是 -- / 是另一个 flag ⇒ 当布尔开关
+      if (next === undefined || next === '--' || next.startsWith('-')) out.flags[body] = true;
+      else { out.flags[body] = next; i++; }
+      continue;
+    }
+
+    if (tok.startsWith('-') && tok.length === 2 && SHORT[tok[1]]) {
+      out.flags[SHORT[tok[1]]] = true;
+      continue;
+    }
+
+    if (out.cmd === null) out.cmd = tok;
+    else out.args.push(tok);
+  }
+  return out;
+}

package/src/commands.js

@@ -0,0 +1,299 @@
+import { normalizeUid } from './uid.js';
+import { fmt, kv, table, bullets, truncate } from './render.js';
+
+// 与后端 ThesisBody / AskBody 的默认假设保持一致(改这里前先对齐后端)。
+export const DEFAULT_ASSUMPTIONS = {
+  revenue_growth: 0.08, fcf_margin: 0.22, wacc: 0.09, terminal_growth: 0.025, forecast_years: 10,
+};
+
+// /financials 与 /financials/history 返回同一套宽行(一期一行), 共用列定义。
+const FIN_COLS = [
+  ['period', '期间'], ['revenue', '营收'], ['gross_profit', '毛利'],
+  ['operating_income', '经营利润'], ['net_income', '净利'],
+  ['operating_cash_flow', '经营现金流'], ['currency', '币种'], ['source', '来源'],
+];
+
+// 预警条目有三种形态: 事件(title)、证伪触发器(reason)、板块价格异动(median_move_pct)。
+// 取不到人话就明说"无描述", 绝不把原始 JSON 糊到终端上。
+function alertText(a) {
+  if (!a || typeof a !== 'object') return String(a ?? '');
+  if (a.title_zh || a.title) return a.title_zh || a.title;
+  if (a.reason) return a.reason;
+  if (a.message || a.text) return a.message || a.text;
+  if (a.median_move_pct !== undefined && a.median_move_pct !== null) {
+    const cover = a.covered !== undefined && a.total !== undefined ? `（覆盖 ${a.covered}/${a.total}）` : '';
+    return `板块价格异动: 中位 ${fmt(a.median_move_pct)}%${cover}`;
+  }
+  return '（该条无文字描述，用 --json 看原始字段）';
+}
+
+const needUid = (args) => normalizeUid(args[0] ?? '');
+const joinQ = (args, what) => {
+  const q = args.join(' ').trim();
+  if (!q) throw new Error(`需要一个${what}`);
+  return q;
+};
+
+// 命令表: 一条命令 = 一行。host 决定打哪个服务, build 只做参数映射, render 只做排版。
+// agent host 的路径必须落在生产网关的只读 GET 白名单内(见 web-backend/deploy/Caddyfile)。
+export const COMMANDS = {
+  // ---------------------------- 行情 / 基本面 ---------------------------- //
+  quote: {
+    host: 'api', path: '/quote',
+    usage: 'quote <代码>', desc: '实时报价(价格/涨跌/总股本)',
+    build: (args) => ({ query: { uid: needUid(args) } }),
+    render: (d) => kv([
+      ['标的', d.uid], ['名称', d.name], ['价格', d.price], ['涨跌%', d.change_pct],
+      ['币种', d.currency], ['总股本', d.shares_outstanding], ['数据源', d.source], ['时间', d.as_of],
+    ]),
+  },
+  search: {
+    host: 'api', path: '/search', timeoutMs: 60000,
+    usage: 'search <关键词> [--limit N]', desc: '全市场名称/代码模糊搜索',
+    build: (args, flags) => ({ query: { q: joinQ(args, '关键词'), limit: flags.limit ?? 8 } }),
+    render: (d) => table(d.results || [], [['uid', '代码'], ['name', '名称'], ['market', '市场']]),
+  },
+  news: {
+    host: 'api', path: '/news',
+    usage: 'news <代码> [--limit N] [--zh]', desc: '个股新闻(--zh 附中文标题翻译)',
+    build: (args, flags) => ({
+      query: { uid: needUid(args), limit: flags.limit ?? 6, lang: flags.zh ? 'zh' : '' },
+    }),
+    render: (rows) => table((rows || []).map((n) => ({
+      published_at: (n.published_at || '').slice(0, 10),
+      title: truncate(n.title_zh || n.title, 60),
+      publisher: n.publisher,
+    })), [['published_at', '日期'], ['title', '标题'], ['publisher', '来源']]),
+  },
+  financials: {
+    host: 'api', path: '/financials',
+    usage: 'financials <代码> [--period 2025A] [--cross-check]', desc: '财务指标(可多源交叉校验)',
+    build: (args, flags) => ({
+      query: {
+        uid: needUid(args), period: flags.period ?? '2025A',
+        cross_check: flags['cross-check'] ? 'true' : '',
+      },
+    }),
+    render: (rows) => table(rows || [], FIN_COLS),
+  },
+  history: {
+    host: 'api', path: '/financials/history',
+    usage: 'history <代码> [--years 5] [--quarter]', desc: '历年(或历季)财务趋势',
+    build: (args, flags) => ({
+      query: {
+        uid: needUid(args), years: flags.years ?? 5,
+        granularity: flags.quarter ? 'quarter' : 'annual',
+      },
+    }),
+    render: (rows) => table(rows || [], FIN_COLS),
+  },
+  peers: {
+    host: 'api', path: '/peers', timeoutMs: 60000,
+    usage: 'peers <代码> [--period 2025A]', desc: '可比公司(PE/PB/PS 同口径)',
+    build: (args, flags) => ({ query: { uid: needUid(args), period: flags.period ?? '2025A' } }),
+    render: (d) => table((d && d.rows) || (Array.isArray(d) ? d : []),
+      [['uid', '代码'], ['name', '名称'], ['pe', 'PE'], ['pb', 'PB'], ['ps', 'PS']]),
+  },
+  profile: {
+    host: 'api', path: '/company-profile',
+    usage: 'profile <代码> [--period 2025A]', desc: '公司画像(业务/规模/关键指标)',
+    build: (args, flags) => ({ query: { uid: needUid(args), period: flags.period ?? '2025A' } }),
+    render: (d) => kv(Object.entries(d || {}).filter(([, v]) => v === null || typeof v !== 'object')),
+  },
+  bars: {
+    host: 'api', path: '/bars',
+    usage: 'bars <代码> [--days 30]', desc: '日线 K 线',
+    build: (args, flags) => ({ query: { uid: needUid(args), days: flags.days ?? 30 } }),
+    render: (rows) => table(rows || [], [['date', '日期'], ['open', '开'], ['high', '高'],
+      ['low', '低'], ['close', '收'], ['volume', '量']]),
+  },
+  indices: {
+    host: 'api', path: '/indices',
+    usage: 'indices', desc: '主要指数行情',
+    build: () => ({}),
+    render: (rows) => table(rows || [], [['name', '指数'], ['price', '点位'], ['change_pct', '涨跌%']]),
+  },
+  industries: {
+    host: 'api', path: '/industries',
+    usage: 'industries', desc: '已覆盖的行业专题列表',
+    build: () => ({}),
+    render: (rows) => table(rows || [], [['key', 'key'], ['name', '名称'], ['count', '标的数']]),
+  },
+  industry: {
+    host: 'api', path: '/industry', timeoutMs: 60000, llm: false,
+    usage: 'industry <key>', desc: '行业专题详情(用 industries 查 key)',
+    build: (args) => ({ query: { key: joinQ(args, '行业 key') } }),
+    render: (d) => {
+      const cov = d.coverage || {};
+      const agg = d.agg || {};
+      const parts = [
+        `${d.name || d.key}（${d.key}）· 成分覆盖 ${fmt(cov.got)}/${fmt(cov.total)}`,
+        '',
+        kv([['合计营收', agg.total_revenue], ['合计净利', agg.total_net_income],
+          ['营收 CAGR', agg.revenue_cagr], ['中位 PE', agg.median_pe]]),
+        '',
+        '成分股',
+        table(d.members || [], [['uid', '代码'], ['name', '名称'],
+          ['market_cap', '市值'], ['pe', 'PE'], ['roe', 'ROE']]),
+      ];
+      if (d.chain) {
+        parts.push('', '产业链');
+        for (const [seg, label] of [['upstream', '上游'], ['mid', '中游'], ['downstream', '下游']]) {
+          if (d.chain[seg]) parts.push(`  ${label}: ${fmt(d.chain[seg])}`);
+        }
+      }
+      if (d.disclaimer) parts.push('', '⚠️ ' + d.disclaimer);
+      return parts.join('\n');
+    },
+  },
+  pulse: {
+    host: 'api', path: '/sector-pulse', timeoutMs: 60000,
+    usage: 'pulse [key]', desc: '行业异动预警(默认 satellite)',
+    build: (args) => ({ query: { key: args[0] || 'satellite' } }),
+    render: (d) => {
+      const rows = (d && d.alerts) || [];
+      if (!rows.length) return '近期无异动命中 —— 规则未触发即不报警（非故障）。';
+      return table(rows.map((a) => ({
+        kind: a.kind, severity: a.severity, text: truncate(alertText(a), 70),
+      })), [['kind', '类型'], ['severity', '级别'], ['text', '内容']]);
+    },
+  },
+
+  // ------------------------------- 研究(LLM) ------------------------------ //
+  ask: {
+    host: 'api', method: 'POST', path: '/ask', llm: true, timeoutMs: 180000,
+    usage: 'ask <问题…>', desc: '对话式投研问答',
+    build: (args) => ({
+      body: {
+        question: joinQ(args, '问题'), context: [],
+        assumptions: DEFAULT_ASSUMPTIONS, period: '2025A', cross_check: true,
+      },
+    }),
+    render: (d) => d.answer || d.narrative || JSON.stringify(d, null, 2),
+  },
+  thesis: {
+    host: 'api', method: 'POST', path: '/thesis', llm: true, timeoutMs: 180000,
+    usage: 'thesis <代码>', desc: '多空研判 + 护城河',
+    build: (args) => ({
+      body: {
+        uid: needUid(args), assumptions: DEFAULT_ASSUMPTIONS, period: '2025A', cross_check: true,
+      },
+    }),
+    // 返回是结构化的 moat/bull/bear/verdict 数组, 不是一整段 narrative —— 自己排成研判卡。
+    render: (d) => {
+      if (!d || typeof d !== 'object') return String(d ?? '');
+      const parts = [
+        `${d.name || ''}（${d.uid || ''}） — 多空研判`,
+        kv([['确定性评级', d.rating], ['目标价', d.target_price],
+          ['相对现价上行%', d.upside_pct], ['币种', d.currency]]),
+      ];
+      const sect = (title, items, fmtItem) => {
+        if (!items || !items.length) return;
+        parts.push('', title, bullets(items.map(fmtItem)));
+      };
+      sect('护城河', d.moat, (m) => (m.label ? `${m.label}：${m.point}` : fmt(m)));
+      sect('看多', d.bull, (s) => fmt(s));
+      sect('看空', d.bear, (s) => fmt(s));
+      if (d.verdict) parts.push('', `研判：${d.verdict}`);
+      return parts.join('\n');
+    },
+  },
+  compare: {
+    host: 'api', method: 'POST', path: '/compare', llm: true, timeoutMs: 180000,
+    usage: 'compare <代码A> <代码B> [更多…] [--cross-check]', desc: '同口径多标的对比',
+    // cross_check 对多标的极慢(实测 2 个标的 >200s, 关掉 4.9s), 故默认关、要多源校验再显式开。
+    build: (args, flags) => {
+      if (args.length < 2) throw new Error('需要至少两个标的代码');
+      return {
+        body: {
+          uids: args.map(normalizeUid), assumptions: DEFAULT_ASSUMPTIONS,
+          period: flags.period ?? '2025A', cross_check: Boolean(flags['cross-check']),
+        },
+      };
+    },
+    render: (d) => {
+      const rows = (d.items || []).map((it) => ({
+        uid: it.uid,
+        name: (it.profile && it.profile.name) || '',
+        price: it.valuation && it.valuation.current_price,
+        value: it.valuation && it.valuation.intrinsic_value_per_share,
+        upside_pct: it.valuation && it.valuation.upside_pct,
+        rating: it.rating,
+      }));
+      const parts = [table(rows, [['uid', '代码'], ['name', '名称'], ['price', '现价'],
+        ['value', 'DCF 每股价值'], ['upside_pct', '上行%'], ['rating', '评级']])];
+      const errs = Object.entries(d.errors || {});
+      if (errs.length) parts.push('', '取数失败(显式列出, 不静默跳过):',
+        bullets(errs.map(([uid, msg]) => `${uid}: ${fmt(msg)}`)));
+      if (d.comparison) parts.push('', d.comparison);
+      return parts.join('\n');
+    },
+  },
+
+  // --------------------- 卫星互联网 agent(只读公开) ---------------------- //
+  events: {
+    host: 'agent', path: '/events',
+    usage: 'events [--limit N] [--thread 主线]', desc: '产业事件流',
+    build: (args, flags) => ({ query: { limit: flags.limit ?? 20, thread: flags.thread ?? '' } }),
+    render: (rows) => table((rows || []).map((e) => ({
+      date: (e.happened_at || e.created_at || '').slice(0, 10),
+      title: truncate(e.title, 60), source: e.source,
+    })), [['date', '日期'], ['title', '标题'], ['source', '来源']]),
+  },
+  alerts: {
+    host: 'agent', path: '/alerts',
+    usage: 'alerts [--window 7] [--limit N]', desc: '风险预警(含证伪触发器)',
+    build: (args, flags) => ({
+      query: { window: flags.window ?? 7, limit: flags.limit ?? 20, include_triggers: 1 },
+    }),
+    render: (rows) => {
+      const list = Array.isArray(rows) ? rows : (rows && rows.alerts) || [];
+      if (!list.length) return '窗口内无风险事件命中 —— 规则未触发即不报警（非故障；事件流仍在实时更新）。';
+      return bullets(list.map((a) => {
+        const head = [a.thread, a.severity && `[${a.severity}]`].filter(Boolean).join(' ');
+        return `${head} ${truncate(alertText(a), 90)}`.trim();
+      }));
+    },
+  },
+  weekly: {
+    host: 'agent', path: '/decision/weekly',
+    usage: 'weekly [--window 7]', desc: '卫星产业周度决策报告(markdown)',
+    build: (args, flags) => ({ query: { window: flags.window ?? 7, format: 'md' } }),
+    // format=md 时后端回的是 {"markdown": "..."} 包装, 不是裸文本 —— 直接 stringify 会满屏 \n 转义。
+    render: (d) => {
+      if (typeof d === 'string') return d;
+      if (d && typeof d.markdown === 'string') return d.markdown;
+      return JSON.stringify(d, null, 2);
+    },
+  },
+  companies: {
+    host: 'agent', path: '/companies',
+    usage: 'companies [--thread 主线]', desc: '产业链公司卡片',
+    build: (args, flags) => ({ query: { thread: flags.thread ?? '' } }),
+    render: (rows) => table((rows || []).map((c) => ({
+      name: c.name, thread: c.thread, score: c.score,
+      moat: truncate(c.moat, 28), risk: truncate(c.risk, 28),
+    })), [['name', '公司'], ['thread', '主线'], ['score', '评分'],
+      ['moat', '护城河'], ['risk', '风险']]),
+  },
+  'thesis-state': {
+    host: 'agent', path: '/thesis/state',
+    usage: 'thesis-state', desc: '各主线 thesis 实时评分',
+    build: () => ({}),
+    render: (d) => {
+      const rows = Array.isArray(d) ? d : Object.entries(d || {}).map(([thread, v]) =>
+        (v && typeof v === 'object' ? { thread, ...v } : { thread, score: v }));
+      return table(rows, [['thread', '主线'], ['score', '评分'], ['updated_at', '更新时间']]);
+    },
+  },
+  sources: {
+    host: 'agent', path: '/sources/ledger',
+    usage: 'sources', desc: '数据来源账本(各源事件数)',
+    build: () => ({}),
+    render: (d) => {
+      const rows = (d && d.by_source) || (Array.isArray(d) ? d : []);
+      const head = d && d.total !== undefined ? `全库事件总数: ${fmt(d.total)}\n\n` : '';
+      return head + table(rows, [['source', '来源'], ['count', '条数'], ['category', '类别']]);
+    },
+  },
+};

package/src/http.js

@@ -0,0 +1,65 @@
+// 唯一网络出口。fetchImpl 依赖注入 => 离线可测。
+// 凭证不在这一层: 目标 API 是公开只读服务, 本客户端不发任何 Authorization 头。
+export const UA = 'invesresearch-cli';
+
+export function buildUrl(base, path, query = {}) {
+  const u = new URL(path, base.endsWith('/') ? base : base + '/');
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined || v === null || v === '') continue;
+    u.searchParams.set(k, String(v));
+  }
+  return u.toString();
+}
+
+// FastAPI 的 422 detail 是一串 pydantic 校验对象, 原样 stringify 出来没法读。
+// 抽成「参数 xxx: 说明」的人话; 其它形态原样保留。
+export function formatDetail(detail) {
+  if (typeof detail === 'string') return detail;
+  if (Array.isArray(detail) && detail.length && detail.every((d) => d && d.msg)) {
+    return detail.map((d) => {
+      const field = Array.isArray(d.loc) ? d.loc[d.loc.length - 1] : d.loc;
+      return field ? `参数 ${field}: ${d.msg}` : d.msg;
+    }).join('; ');
+  }
+  return JSON.stringify(detail);
+}
+
+export async function request({
+  base, method = 'GET', path, query = {}, body = null,
+  fetchImpl = globalThis.fetch, timeoutMs = 20000,
+}) {
+  const url = buildUrl(base, path, query);
+  const headers = { Accept: 'application/json', 'User-Agent': UA };
+  const opt = { method, headers };
+  if (body != null) {
+    headers['Content-Type'] = 'application/json';
+    opt.body = JSON.stringify(body);
+  }
+  if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) opt.signal = AbortSignal.timeout(timeoutMs);
+
+  let res;
+  try {
+    res = await fetchImpl(url, opt);
+  } catch (e) {
+    if (e && (e.name === 'TimeoutError' || e.name === 'AbortError')) {
+      throw new Error(`请求超时(${timeoutMs}ms): ${url}`);
+    }
+    throw e;
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    let detail = text.slice(0, 200);
+    try {
+      const j = JSON.parse(text);
+      if (j && j.detail !== undefined) detail = formatDetail(j.detail);
+    } catch { /* 非 JSON 错误体, 用原文前 200 字 */ }
+    throw new Error(`HTTP ${res.status} ${method} ${url} — ${detail}`);
+  }
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;  // /decision/weekly?format=md 之类的非 JSON 响应原样返回
+  }
+}

package/src/main.js

@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgv } from './args.js';
+import { request } from './http.js';
+import { COMMANDS } from './commands.js';
+import { DISCLAIMER } from './render.js';
+
+// 生产端点(公开只读, 无需任何凭证)。可用 --api/--agent 或 IR_API_BASE/IR_AGENT_BASE 覆盖。
+export const API_BASE = 'https://api.oaf.world';
+export const AGENT_BASE = 'https://agent.oaf.world';
+
+// 30s 给普通端点(实测 /peers 冷启动约 11s、/sector-pulse 约 16s)。LLM 端点在命令表里
+// 自带更长的 timeoutMs —— 生成一篇研判本来就要几十秒。
+export const DEFAULT_TIMEOUT_MS = 30000;
+
+const pkg = () => JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+
+export function helpText() {
+  const lines = [
+    'invesresearch — InvesResearch 命令行客户端',
+    '数据来自 oaf.world 公开只读 API, 无需注册、无需密钥。',
+    '',
+    '用法: invesresearch <命令> [参数] [选项]   (短别名: ires)',
+    '',
+    '命令:',
+  ];
+  const w = Math.max(...Object.values(COMMANDS).map((c) => c.usage.length));
+  for (const c of Object.values(COMMANDS)) lines.push(`  ${c.usage.padEnd(w)}  ${c.desc}`);
+  lines.push(
+    '',
+    '代码写法: NVDA / 600519 / 0700.HK / 09988.HK / US:NVDA / SH:600519 都认',
+    '',
+    '全局选项:',
+    '  --json, -j        输出原始 JSON(可管道给 jq)',
+    `  --api <url>       覆盖行情 API 端点(默认 ${API_BASE}, 亦可用 IR_API_BASE)`,
+    `  --agent <url>     覆盖 agent API 端点(默认 ${AGENT_BASE}, 亦可用 IR_AGENT_BASE)`,
+    '  --timeout <ms>    请求超时(默认 20000)',
+    '  --help, -h        显示本帮助',
+    '  --version, -v     显示版本',
+    '',
+    '示例:',
+    '  npx invesresearch quote NVDA',
+    '  npx invesresearch search 宁德',
+    '  npx invesresearch ask "英伟达的护城河在哪"',
+    '  npx invesresearch alerts --window 30',
+    '  npx invesresearch quote 0700.HK --json | jq .price',
+    '',
+    DISCLAIMER,
+  );
+  return lines.join('\n');
+}
+
+// flag 写成 `--api`(裸开关)时值是 true —— 那不是一个 URL, 回落默认值。
+const pickBase = (flagVal, envVal, dflt) =>
+  (typeof flagVal === 'string' && flagVal ? flagVal : (envVal || dflt));
+
+export async function run(argv, io = {}) {
+  const out = io.out || ((s) => process.stdout.write(s + '\n'));
+  const err = io.err || ((s) => process.stderr.write(s + '\n'));
+  const fetchImpl = io.fetchImpl || globalThis.fetch;
+  const env = io.env || process.env;
+
+  const { cmd, args, flags } = parseArgv(argv);
+
+  if (flags.version) { out(pkg().version); return 0; }
+  if (!cmd || flags.help) { out(helpText()); return 0; }
+
+  const spec = COMMANDS[cmd];
+  if (!spec) { err(`未知命令: ${cmd}\n`); err(helpText()); return 2; }
+
+  let built;
+  try {
+    built = spec.build(args, flags) || {};
+  } catch (e) {
+    err(`${e.message}\n用法: ${spec.usage}`);
+    return 2;
+  }
+
+  const base = spec.host === 'agent'
+    ? pickBase(flags.agent, env.IR_AGENT_BASE, AGENT_BASE)
+    : pickBase(flags.api, env.IR_API_BASE, API_BASE);
+
+  try {
+    const data = await request({
+      base,
+      method: spec.method || 'GET',
+      path: built.path || spec.path,
+      query: built.query || {},
+      body: built.body || null,
+      fetchImpl,
+      timeoutMs: Number(flags.timeout) || spec.timeoutMs || DEFAULT_TIMEOUT_MS,
+    });
+    if (flags.json) { out(JSON.stringify(data, null, 2)); return 0; }
+    out(spec.render(data));
+    // 免责声明是硬性要求。后端自带 disclaimer 时以它为准(口径归后端), 否则用本地兜底 —— 二选一, 只出一条。
+    if (spec.llm) {
+      const own = data && typeof data.disclaimer === 'string' && data.disclaimer.trim();
+      out('\n⚠️ ' + (own || DISCLAIMER.replace(/^⚠️\s*/, '')));
+    }
+    return 0;
+  } catch (e) {
+    err(e.message);
+    return 1;
+  }
+}

package/src/render.js

@@ -0,0 +1,40 @@
+// 纯格式化。**不做任何计算** —— 数字一律来自 API, 这里只排版。
+export const DISCLAIMER = '⚠️ 以上内容由公开数据与模型生成，仅供研究参考，不构成投资建议。';
+
+// 中日韩宽字符按 2 列宽算, 否则中文表格会歪。
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹯＀-｠￠-￦]/;
+const width = (s) => [...String(s)].reduce((n, ch) => n + (WIDE.test(ch) ? 2 : 1), 0);
+const pad = (s, w) => String(s) + ' '.repeat(Math.max(0, w - width(s)));
+
+export function fmt(v) {
+  if (v === null || v === undefined || v === '') return '—';
+  if (typeof v === 'number') {
+    if (!Number.isFinite(v)) return '—';
+    return v.toLocaleString('en-US', { maximumFractionDigits: 4 });
+  }
+  if (Array.isArray(v)) return v.length ? v.map(fmt).join(', ') : '—';
+  if (typeof v === 'object') return JSON.stringify(v);
+  return String(v);
+}
+
+export function kv(pairs) {
+  const w = Math.max(0, ...pairs.map(([k]) => width(k)));
+  return pairs.map(([k, v]) => `${pad(k, w)}  ${fmt(v)}`).join('\n');
+}
+
+export function table(rows, cols) {
+  if (!rows || !rows.length) return '（无数据）';
+  const widths = cols.map(([key, header]) =>
+    Math.max(width(header), ...rows.map((r) => width(fmt(r[key])))));
+  const line = (cells) => cells.map((c, i) => pad(c, widths[i])).join('  ').trimEnd();
+  return [line(cols.map(([, h]) => h)), ...rows.map((r) => line(cols.map(([k]) => fmt(r[k]))))].join('\n');
+}
+
+export function bullets(items) {
+  return (items || []).map((s) => `· ${s}`).join('\n');
+}
+
+export function truncate(s, n) {
+  const t = String(s ?? '');
+  return t.length > n ? t.slice(0, n - 1) + '…' : t;
+}

package/src/uid.js

@@ -0,0 +1,31 @@
+// 用户友好写法 → 后端 uid。纯字符串映射, 不查网络、不猜价格。
+const PREFIXES = new Set(['US', 'HK', 'SH', 'SZ']);
+
+export function normalizeUid(input) {
+  const s = String(input ?? '').trim();
+  if (!s) throw new Error('需要一个标的代码, 例如 NVDA / 600519 / 0700.HK');
+
+  const colon = s.indexOf(':');
+  if (colon > 0) {
+    const head = s.slice(0, colon).toUpperCase();
+    if (PREFIXES.has(head)) return head + ':' + s.slice(colon + 1).toUpperCase();
+  }
+
+  // Yahoo 风格后缀: 0700.HK / 600519.SS / 300750.SZ
+  const m = /^(\d{1,6})\.(HK|SS|SZ)$/i.exec(s);
+  if (m) {
+    const num = m[1];
+    const suf = m[2].toUpperCase();
+    if (suf === 'HK') return 'HK:' + num.padStart(5, '0');
+    return (suf === 'SS' ? 'SH:' : 'SZ:') + num;
+  }
+
+  if (/^\d{6}$/.test(s)) {
+    if (s[0] === '6') return 'SH:' + s;      // 沪市主板/科创(688 也是 6 开头)
+    if (s[0] === '0' || s[0] === '3') return 'SZ:' + s;  // 深市主板 / 创业板
+    return 'SH:' + s;
+  }
+  if (/^\d{1,5}$/.test(s)) return 'HK:' + s.padStart(5, '0');  // 港股代码习惯写短
+
+  return 'US:' + s.toUpperCase();
+}