@itriton/insight

Node.js 智能检索 npm 插件：输入自然语言，自动联网搜索、提取网页内容，并输出结构化 JSON。

安装

npm install @itriton/insight
# 或
pnpm add @itriton/insight

快速开始

1. 复制配置文件

cp insight.toml.example insight.toml

编辑 insight.toml，填入 LLM API Key（DeepSeek / OpenRouter / Qwen 等 OpenAI-compatible 服务）。

2. 三行代码调用

import { InsightEngine } from "@itriton/insight";

const engine = new InsightEngine({ configFile: "./insight.toml" });
const result = await engine.run("搜索3条'OPC UA'的新闻");
console.log(result.data);

3. 代码内配置（无需 toml）

内置 DeepSeek 快速模式：

const engine = new InsightEngine({
  apiKey: process.env.INSIGHT_API_KEY,
  provider: "deepseek",
});

任意 OpenAI-compatible 接口：

const engine = new InsightEngine({
  apiKey: process.env.LLM_API_KEY,
  provider: "my-gateway", // 自定义名称，仅用于标识
  baseUrl: "https://llm.example.com/v1",
  model: "gpt-4o-mini",
  maxTokens: 4096,
  timeout: 60,
});

const result = await engine.run("搜索3条'OPC UA'的新闻");

也支持 Ollama / vLLM / OneAPI 等兼容网关，只需保证提供 POST {baseUrl}/chat/completions。

配置

insight.toml

defaultProvider = "deepseek"
timeout = 60

[llm.deepseek]
type = "openai"
model = "deepseek-chat"
apiKey = ""
baseUrl = "https://api.deepseek.com"
timeout = 60
maxTokens = 8192

[search]
maxResults = 10
minResults = 1
engines = ["bing", "baidu", "so360", "sogou"]

环境变量

| 变量 | 说明 | |---|---| | INSIGHT_CONFIG_FILE | 配置文件路径 | | INSIGHT_API_KEY | 默认 LLM API Key | | INSIGHT_PROVIDER | 默认 Provider 名称 |

API

InsightEngine 构造参数

| 参数 | 说明 | |---|---| | configFile | 配置文件路径（可选） | | apiKey | LLM API Key | | provider | Provider 名称；不存在时会自动创建 | | baseUrl | OpenAI-compatible API 根地址 | | model | 模型名称 | | maxTokens | 最大 token 数 | | timeout | 全局与 LLM 超时（秒） | | maxResults / minResults | 搜索结果数量 | | onProgress | 进度回调 |

InsightEngine

class InsightEngine {
  constructor(options?: InsightEngineOptions)

  run(instruction: string): Promise<InsightResult>
  search(options: SearchOptions): Promise<InsightResult>
  extractUrls(options: ExtractOptions): Promise<InsightResult>

  static mapResultToFormat(data, fields): InsightItem[]
  static formatAsMarkdown(topic, results, options?): string
}

自然语言搜索

const result = await engine.run("搜索3条'AI'的新闻");

结构化搜索

const result = await engine.search({
  topic: "OPC UA",
  minResults: 1,
  maxResults: 10,
});

URL 内容提取

const result = await engine.extractUrls({
  topic: "OPC UA",
  urls: ["https://example.com/article"],
  referenceRatio: 0.3,
});

字段映射

const items = InsightEngine.mapResultToFormat(result.data, [
  "title",
  "abstract",
  "url",
  "pub_time",
]);

Markdown 格式化

const text = InsightEngine.formatAsMarkdown("OPC UA", items);
// 可直接嵌入写作 / Agent prompt

CLI

npx @itriton/insight "搜索3条AI新闻"
npx @itriton/insight --config ./insight.toml "搜索3条OPC UA新闻"
npx @itriton/insight --urls "https://a.com,https://b.com" --topic "OPC UA"
npx @itriton/insight --format json "搜索3条AI新闻"

错误码

| 错误码 | 说明 | |---|---| | MISSING_API_KEY | 未配置 LLM API Key | | CONFIG_INVALID | 配置文件校验失败 | | SEARCH_NO_RESULTS | 所有搜索引擎均无有效结果 | | INVALID_URL | URL 格式非法 | | EXTRACT_FAILED | 网页内容提取失败 | | LLM_TIMEOUT | LLM 请求超时 | | UNKNOWN | 未知错误 |

进度回调

const engine = new InsightEngine({
  configFile: "./insight.toml",
  onProgress: (event) => {
    console.log(`[Insight] ${event.type}: ${event.message}`);
  },
});

事件类型：llm_connecting | llm_waiting | search_start | search_trying | search_complete | error

联调（真实 API Key）

cp .env.example .env
# 编辑 .env 填入 INSIGHT_API_KEY，或直接 export

export INSIGHT_API_KEY=sk-xxx
export INSIGHT_PROVIDER=deepseek

pnpm run smoke              # 完整联调：搜索 + 映射 + URL 提取
pnpm run example:search     # 自然语言搜索示例
pnpm run example:extract    # URL 提取示例
pnpm run example:langchain  # LangChain Tool 联调

也支持 DEEPSEEK_API_KEY / OPENROUTER_API_KEY 作为联调脚本的 Key 来源。

LangChain Tool 接入

examples/agent-tool.ts 提供三种接入方式：

import {
  createInsightTool,
  createLangChainInsightTools,
} from "./examples/agent-tool.js";

// 1. 自研 Agent：通用 tool 对象
const tool = createInsightTool({ apiKey: process.env.INSIGHT_API_KEY });
await tool.execute({ instruction: "搜索3条'AI'的新闻" });

// 2. LangChain：DynamicStructuredTool
const { tools } = createLangChainInsightTools({
  apiKey: process.env.INSIGHT_API_KEY,
  provider: "deepseek",
});
// agent 中直接 bindTools(tools)

如何测试

1. 配置 API Key（任选一种）：

cp .env.example .env
# 编辑 .env，填入 INSIGHT_API_KEY 和 INSIGHT_PROVIDER=deepseek

或：

export INSIGHT_API_KEY=sk-xxx
export INSIGHT_PROVIDER=deepseek

2. 运行示例脚本（会自动读取 .env）：

pnpm install

# 测试 README 中两种接入方式（createInsightTool + LangChain tools）
pnpm run example:agent-tool

# 仅测试 LangChain 三个 Tool（含 URL 提取）
pnpm run example:langchain

3. 预期输出：

• example:agent-tool：打印 [1/2] createInsightTool 和 [2/2] createLangChainInsightTools 均 ✓
• example:langchain：打印 insight_search 搜索结果，以及 insight_extract_urls 提取结果（网络不通时会 ⚠ 跳过）

LangChain 会注册 3 个 Tool：

| Tool | 用途 | |---|---| | insight_search | 自然语言搜索 | | insight_structured_search | 结构化主题搜索 | | insight_extract_urls | URL 正文提取 |

开发

pnpm install
pnpm run build
pnpm test
pnpm run test:coverage

许可证

MIT