# @basenative/station 中文文档

规范地址：https://npmcn.com/package/%40basenative/station/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:06.018Z
中文译文更新时间：2026-10-31T16:22:49.200Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/station
原文对照：https://npmcn.com/package/%40basenative/station/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/station#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：78.1 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-18T05:29:39.850Z
- 最新版本发布：2026-10-31T13:47:05.746Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

队列驱动的本地推理原语——驱动带有sqlite支持的作业队列、迭代循环运行时、回退到Workers AI和可重用的作业模板的cloudflare隧道vLLM塔（或任何openai兼容的端点）。

## 安装

```sh
npm install @basenative/station
```

也可以使用：`pnpm add @basenative/station`、`yarn add @basenative/station`、`bun add @basenative/station`

## README

# @basenative /站

> 队列驱动的本地推理原语——驱动带有sqlite支持的作业队列、迭代循环运行时、自动Workers AI回退和预构建作业模板注册表的cloudflare隧道vLLM塔（或任何openai兼容的端点）。

部分 [BaseNative](https://github.com/DuganLabs/BaseNative) 生态系统。指定的 `DUGANLABS_ORCHESTRATOR_SPEC.md` §9。

## 什么站

一种小型的、固执己见的用于运行的软件原语 **循环模式** 针对a的工作负载 **本地7b级编码器模型** 在openai兼容的HTTP端点后面（在我们的参考堆栈中：通过vLLM提供Qwen2.5-Coder-7B INT4的RTX 5070盒子，暴露在cloudflare隧道上）。

它是 **不** 塔的硬件。驱动这座塔的是软件。

## 它与前沿推断有何不同

规范 § 9中的成本模型，重述:

| 层 | 每代币边际成本 | 小说代码的质量 | 质量循环模式代码 |
| --- | --- | --- | --- |
| **边疆** （十四行诗4.6 /作品4.7） | 公布的人为率 | 优秀的 | 优秀-浪费了 |
| **工人人工智能** (gpt-oss-120b免费层) | 每天释放多达10K个神经元 | 好 | 良好的上限吞吐量 |
| **车站** （本地7B INT4） | 高于电费0美元 (约5-10美元/月) | 可怜的一次性 | 在狭窄的模板化迭代上可以接受 |

空塔：~20W × 24h × 0.30美元/kWh × 30d≈ **4.30美元/月**. 突发推断：5-10美元/月。 十四行诗-相当于docstring覆盖范围的5k站迭代: ~ 15-25美元。

**收支平衡大约是5万代币/天。** 最重要的是，车站在成本上获胜。在它下面，只需使用十四行诗。

## 何时使用车站

将工作站用于以下任务:

-   每次迭代的赌注很低。
-   模板很窄，成功检查是确定性的。
-   您将经常这样做（≥数百次迭代）。

具体的适合:

-   为一个TODO写一个测试一下，标记完成，提前。
-   将一个JSDoc添加到一个未记录的导出。
-   修复一个绒毛警告。
-   在一个文件中应用一个mechanical重构步骤。
-   将一条入站短信分类为一个FSM过渡（Greenput摄入量）。

**不要** 将Station用于：计划器任务（Opus），新颖的实现代码（Sonnet）， PR审查（Opus），或任何涉及基本公理的内容（仅限边界-漂移是不可恢复的）。

## 安装

```bash
pnpm add @basenative/station
# Optional, for production persistence:
pnpm add better-sqlite3
```

## 快速启动

```js
import { defineStation } from '@basenative/station';

const station = defineStation({
  tunnelUrl: 'https://tower.your-account.cloudflareaccess.com',
  model: 'qwen2.5-coder-7b-instruct',
  queueDb: '/var/lib/dugan/station.db',
  fallback: {
    url: 'https://api.cloudflare.com/client/v4/accounts/<id>/ai/run',
    model: 'gpt-oss-120b',
  },
});

// Enqueue a job
const id = station.queue.enqueue({
  venture: 'basenative',
  intent: 'docstring-coverage',
  payload: {
    filePath: 'packages/runtime/src/signal.js',
    fileContents: '/* ... */',
    exportName: 'createSignal',
    exportKind: 'function',
  },
});

// Drain the queue (runs all queued jobs to completion or escalation)
const counters = await station.runner.run({ maxJobs: 50 });
console.log(counters);
// { processed: 50, completed: 47, escalated: 2, failed: 1 }
```

## API

### `defineStation(opts)`

返回 `{ client, queue, runner, templates }`。如果您想以不同的方式连接它们 (例如，从Worker排队，从节点守护进程运行)，这四个部分也会单独导出。

### `Client` / `OpenAICompatClient`

```js
import { OpenAICompatClient } from '@basenative/station';

const client = new OpenAICompatClient({
  baseUrl: 'https://tower.example.com',
  model: 'qwen2.5-coder-7b-instruct',
  fallbackUrl: 'https://api.cloudflare.com/.../ai/run',
});

const { text, latencyMs, source } = await client.chat({
  messages: [{ role: 'user', content: 'Write one JSDoc for foo.' }],
  temperature: 0.2,
  maxTokens: 400,
});
// source === 'primary' | 'fallback'
```

**回退行为:** 每一个 `chat()` 调用首先到达主节点。对于任何失败（HTTP错误、格式错误的响应、超时），它都会在回退上重试。如果两者都失败，则抛出 `StationUnavailable` 附加了两个错误链。 **30秒硬超时** 每一个电话。

### `Queue`

SQLite-schema-compatible(见 `src/queue.js` 对于DDL)。默认驱动程序在内存中; 通过 `betterSqlite3` 来 `createQueue` 对于持久性:

```js
import Database from 'better-sqlite3';
import { createQueue } from '@basenative/station';
const queue = createQueue({ path: './station.db', betterSqlite3: Database });
```

API: `enqueue`， `claim`， `recordIteration`， `complete`， `escalate`， `fail`， `list`， `iterationsFor`， `depth`.

### `Runner`

循环运行时。每次迭代它：

1.  通过查找作业的模板 `intent`.
2.  通过创建提示符 `template.buildPrompt(payload)`.
3.  调用模型。
4.  (消费者钩子) 在沙盒工作树中应用响应作为差异。
5.  跑步 `template.successCheck(diff, payload)`.
6.  记录迭代; 前进或停止。

失速阈值 `maxIterations` 每份工作; `escalateTo` 是编排器在作业停止时应将其路由到的上游层。

### `templates`

预构建的冻结注册表。每个模板都有 `name`， `description`， `buildPrompt`， `successCheck`， `maxIterations`， `escalateTo`。包括的五个模板是：

-   `tests-from-todos`
-   `docstring-coverage`
-   `lint-bankruptcy`
-   `refactor-migration`
-   `fsm-classifier`

你可以自己加一个 `defineStation({ ..., templates: { ...templates, mine } })`.

### `ops`

由orchestrator的消耗的运行状况检查助手 `station-ops` 代理:

-   `tunnelHealth(url)` ——得到 `/health`
-   `modelHealth(client)` - - - - - - `GET /v1/models`，验证了所提出的预期模型
-   `gpuHealth(url)` -可选GET `/gpu` 探头（有根的；塔侧端点待定）
-   `queueHealth(queue)` -深度最老-排队年龄
-   `summary({ tunnelUrl, client, queue, gpuUrl })` ——复合

## 命令行界面

```
bn-station enqueue <intent> [--venture x] [--payload @file.json]
bn-station list    [--status queued|running|done|escalated|failed]
bn-station run     [--max-iterations N] [--max-jobs N]
bn-station ops
bn-station drain
```

从读取配置 `STATION_TUNNEL_URL`， `STATION_MODEL`， `STATION_QUEUE_DB`， `STATION_FALLBACK_URL`.

## Ops环路

预期的部署形状，根据规范§5.5：

1.  运行cron / systemd定时器 `bn-station ops` 每60s在dispatcher主机上。
2.  在 `tunnel.ok === false`,station-ops代理将队列的有效回退翻转到Workers AI，发布到TUI，并写入事件。
3.  在 `queue.oldestQueuedAgeMs > 1h`,按其升级最旧的排队作业 `escalateTo` 政策。
4.  在电源/ISP中断时，所有飞行中的作业都将升级并显示给用户。

## Worker-runtime支持

`Client` 和 `templates` 是纯粹的 `fetch` 纯函数，并在Cloudflare Workers中未经修改地运行。默认的 `Queue` 驱动程序在内存中（Worker没有文件系统）-如果你需要在Worker中持久排队，在更高的层中持久化到D1/KV并调用 `enqueue`/`claim` 从那里。

`Runner` 是可移植的，并在节点或工作线程中运行。

## 许可证

apache - 2.0。

## 常见问题

### @basenative/station 是什么？

队列驱动的本地推理原语——驱动带有sqlite支持的作业队列、迭代循环运行时、回退到Workers AI和可重用的作业模板的cloudflare隧道vLLM塔（或任何openai兼容的端点）。

### 如何安装 @basenative/station？

在项目目录运行 npm install @basenative/station，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bn-station，可以用 npx bn-station 直接运行。

### @basenative/station 支持 TypeScript 吗？

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

### @basenative/station 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/station 可以商用吗？

@basenative/station 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/station 还在维护吗？

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