# @findable-ai/sdk 中文文档

规范地址：https://npmcn.com/package/%40findable-ai/sdk/

版本：0\.34\.0
npm 元数据更新时间：2026-11-12T10:09:12.563Z
中文译文更新时间：2026-11-14T18:39:22.637Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40findable-ai/sdk
原文对照：https://npmcn.com/package/%40findable-ai/sdk/?lang=original
项目主页：https://github.com/findable-no/monorepo-apps#readme
源码仓库：https://github.com/findable-no/monorepo-apps

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：129 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-28T20:06:25.283Z
- 最新版本发布：2026-11-12T10:09:12.293Z
- 近 30 天下载量：5858（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

可查找伴侣 API 的脚本客户端

## 安装

```sh
npm install @findable-ai/sdk
```

也可以使用：`pnpm add @findable-ai/sdk`、`yarn add @findable-ai/sdk`、`bun add @findable-ai/sdk`

## README

# @ findable-ai/ sdk (中文(简体) )

零依赖性类型Script客户端 [可查找](https://findable.ai/) 合伙人API. 在浏览器、Node.js和任何本地运行时间工作 `fetch`。 。 。 .

[![npm version](https://img.shields.io/npm/v/@findable-ai/sdk)](https://www.npmjs.com/package/@findable-ai/sdk)

> **完整文档**数字 : [可找到的文件](https://docs.findable.ai/sdk)

## 安装

```bash
npm install @findable-ai/sdk
```

## 快开始

```typescript
import { FindableClient } from '@findable-ai/sdk';

const client = new FindableClient({
  apiKey: 'YOUR_API_KEY',
  buildingOwnerId: 'YOUR_BUILDING_OWNER_ID',
});

// Search documents
const results = await client.search({ query: 'fire safety', buildingId: 'bld-123' });
console.log(results.hits);

// Ask a question (non-streaming)
const answer = await client.assistant({
  buildingId: 'bld-123',
  query: 'What are the fire safety requirements?',
});
console.log(answer.answer);
```

## 流线

`assistantStream()` 返回实时服务器发送事件的同步可执行性 :

```typescript
const stream = client.assistantStream({
  buildingId: 'bld-123',
  query: 'Summarise the ventilation specs',
});

for await (const event of stream) {
  switch (event.event) {
    case 'text':
      process.stdout.write(event.text);
      break;
    case 'finish':
      console.log('\n\nCitations:', event.citations);
      break;
  }
}

// Cancel at any time
stream.abort();
```

### 流出事件

| 活动 | 字段 | 说明 |
| --- | --- | --- |
| `start` | `threadId` | 流已打开, 线程已创建 |
| `text` | `text` | 递增式回答文本块 |
| `thinking` | `text` | 示范推理文本(当使用高推理努力时) |
| `action` | `state`, (中文(简体) ), `value`, (中文(简体) ), `result` | 代理进度/行动更新 |
| `finish` | `answer`, (中文(简体) ), `threadId`, (中文(简体) ), `citations`, (中文(简体) ), `citedDocuments`, (中文(简体) ), `followUpSuggestions` | 完整的元数据回复 |
| `error` | `message` | 发生错误 |

## API 参考

### `FindableClient`

```typescript
new FindableClient({ apiKey: string, buildingOwnerId: string, baseUrl?: string })
```

### 方法

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `assistant(options)` | `Promise<AssistantResponse>` | 问一个问题,得到一个完整的回答 |
| `assistantStream(options)` | `AsyncIterable<AssistantStreamEvent> & { abort() }` | 用实时流线询问 |
| `assistantAcrossBuildings(options)` | `Promise<AssistantResponse>` | 问楼对面,请回答 |
| `assistantAcrossBuildingsStream(options)` | `AsyncIterable<AssistantStreamEvent> & { abort() }` | 用实时流线询问跨建筑物 |
| `search(options)` | `Promise<SearchResult>` | 搜索文档 |
| `listBuildings()` | `Promise<Building[]>` | 列出所有建筑物 |
| `getBuilding(id)` | `Promise<Building>` | 单栋楼 |

先前的名字 `ask()`, (中文(简体) ), `askStream()`, (中文(简体) ), `askAcrossBuildings()` 财务报告和审定财务报表 `askAcrossBuildingsStream()`,则 `Ask*` 类型,则被贬值。 他们继续工作 没有删除日期; 替换 `ask` 与 `assistant` 在名称中,当你下次触摸代码.

### 选项

```typescript
// Assistant
{ buildingId: string, query: string, language?: 'en' | 'no' | 'nb' | 'nn',
  threadId?: string, attachedDocumentIds?: string[], mode?: 'fast' | 'balanced' | 'deep',
  reasoningEffort?: 'low' | 'medium' | 'high' /* deprecated */, useAgenticRag?: boolean }

// Search
{ query: string, buildingId?: string, maxResults?: number, startIndex?: number }
```

#### 选择一个答案需要多少工作

`mode` 是一个设置,有三个位置:

| `mode` | 你得到的东西 |
| --- | --- |
| `'fast'` | 最便宜和最快: 大约15x比 `'balanced'` 和几倍快, 较浅的合成 在许多文件. |
| `'balanced'` | 默认. 每个请求在 `mode` 省略. |
| `'deep'` | 最彻底最贵. 对于确实需要从许多来源广泛推理的问题. |

偏爱 `'fast'` 用于查找和单文件问题。 如果你运行助理在一个 批次(例如夜间工作,询问相同的问题) 这是成本最高的场所.

奥米 `mode` 而不作任何改变:要求得到的答案完全如原样 在选项存在之前.

`reasoningEffort` 已折旧为 `mode`从来没有单独拨号: `'high'` 行为就像 `mode: 'deep'`,以及 `'low'` 财务报告和审定财务报表 `'medium'` 都这样 `mode: 'balanced'`. 这种行为仍然被接受,并在 `mode` 已经设定.

## 处理错误

```typescript
import {
  FindableClient,
  AuthError,
  NotFoundError,
  FindableError,
} from '@findable-ai/sdk';

try {
  await client.assistant({ buildingId: 'bld-123', query: 'Hello' });
} catch (err) {
  if (err instanceof AuthError) {
    // Invalid or missing API key (401/403)
  } else if (err instanceof NotFoundError) {
    // Building not found (404)
  } else if (err instanceof FindableError) {
    // Other API error — check err.status and err.message
  }
}
```

## 反应

关于滴入反应组件和钩子,见 [`@findable-ai/react`](https://www.npmjs.com/package/@findable-ai/react)。 。 。 .

## 文档

-   [开始](https://docs.findable.ai/getting-started)
-   [SDK 客户端引用](https://docs.findable.ai/sdk/client)
-   [流线指南](https://docs.findable.ai/sdk/streaming)
-   [API 参考](https://docs.findable.ai/api)

## 许可证

麻省理工学院

## 常见问题

### @findable-ai/sdk 是什么？

可查找伴侣 API 的脚本客户端

### 如何安装 @findable-ai/sdk？

在项目目录运行 npm install @findable-ai/sdk，或使用 pnpm add / yarn add / bun add。

### @findable-ai/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @findable-ai/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @findable-ai/sdk 可以商用吗？

@findable-ai/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @findable-ai/sdk 的下载量有多少？

根据 npm 官方下载统计，@findable-ai/sdk 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,858 次，日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @findable-ai/sdk 还在维护吗？

最新版本 0\.34\.0 发布于 2026/11/12（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/03/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。