# itriton-insight

**Repository Path**: itriton/itriton-insight

## Basic Information

- **Project Name**: itriton-insight
- **Description**: @itriton/insight 智能检索插件：输入自然语言，自动联网搜索、提取网页内容，并输出结构化JSON
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @itriton/insight

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

## 安装

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

## 快速开始

### 1. 复制配置文件

```bash
cp insight.toml.example insight.toml
```

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

### 2. 三行代码调用

```ts
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 快速模式：

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

任意 OpenAI-compatible 接口：

```ts
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

```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

```ts
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
}
```

### 自然语言搜索

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

### 结构化搜索

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

### URL 内容提取

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

### 字段映射

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

### Markdown 格式化

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

## CLI

```bash
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` | 未知错误 |

## 进度回调

```ts
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）

```bash
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` 提供三种接入方式：

```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（任选一种）：

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

或：

```bash
export INSIGHT_API_KEY=sk-xxx
export INSIGHT_PROVIDER=deepseek
```

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

```bash
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 正文提取 |

## 开发

```bash
pnpm install
pnpm run build
pnpm test
pnpm run test:coverage
```

## 发布

推荐流程（升版 → 推 Git → 发 npm）：

```bash
# 首次：配置远程 + npm login
pnpm run setup:remotes
npm login

# 每次发版
pnpm run version:patch          # 或 version:minor / version:major
pnpm run release                # test + typecheck + push GitHub/Gitee + npm publish
```

也可分步执行：

```bash
pnpm run version:patch
pnpm run release:git            # 仅推送 GitHub + Gitee
pnpm run build:publish          # 仅发布 npm（会自动 build）
pnpm run release:git -- --dry-run
```

| 命令 | 作用 |
|---|---|
| `setup:remotes` | 初始化 GitHub / Gitee remote |
| `version:patch/minor/major` | 升级版本号并打 git tag |
| `release:git` | 推送到 GitHub + Gitee |
| `build:publish` | 构建并发布 npm |
| `release` | 上述 quality gate + git + npm 一条龙 |

可选环境变量：`GITHUB_REPO`、`GITEE_REPO`、`GIT_BRANCH`、`USE_SSH`

## 许可证

[MIT](./LICENSE)