# @aexol/spectral 中文文档

规范地址：https://npmcn.com/package/%40aexol/spectral/

版本：0\.9\.288
npm 元数据更新时间：2026-11-04T08:26:51.416Z
中文译文更新时间：2026-11-06T02:34:48.411Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aexol/spectral
原文对照：https://npmcn.com/package/%40aexol/spectral/?lang=original
项目主页：https://aexol.com/
源码仓库：https://gitlab.aexol.com/aexol/spectral

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

- 包体积（解压后）：9 MB，1467 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：31 个
- 首次发布：2026-05-05T14:08:43.064Z
- 最新版本发布：2026-11-04T08:26:51.182Z
- 近 30 天下载量：6264（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：330（近 12 个月 330 个）

## 中文简介

Aexol 的 AI 编码代理器,具有以中继为基础的浏览器访问权限.

## 安装

```sh
npm install @aexol/spectral
```

也可以使用：`pnpm add @aexol/spectral`、`yarn add @aexol/spectral`、`bun add @aexol/spectral`

## README

# @ aexol/ 光谱

> 永不入睡的编码代理.

## 什么是斯克特尔?

Spectral是常有的编码代理 [爱荷华语](https://aexol.com/)。 。 安装在每台您想要编码的机器上, 运行 `spectral serve`,还有你的 设备在 Aexol 网页 UI 中作为活的代理显示, 您可以从任何浏览器驱动 选项卡——没有端口转发、没有SSH、没有暴露本地主机.

在罩子下,Spectral是一个薄的品牌包装器周围 [毕](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) 马里奥 Zechner),外加一个继电器客户端,将每台机器连接到Aexol的后端. 浏览器通过中继器与您的机器交谈; 后端从未看到您的 密码或信息 留在设备上 处理模型 API 密钥 根据您运行的命令不同( 请参见 [推论如何经过](https://npmcn.com/package/%40aexol/spectral/#readme-how-inference-is-routed)) (中文(简体) ).

## 安装

```bash
npm install -g @aexol/spectral
```

需要节点.js **20个或较新**。 。 。 .

## 快速启动

1.  **认证**
    
    ```bash
    spectral login
    ```
    
    您的 Aexol MCP URL( 默认为 `https://api.aexol.ai/mcp`)和一个团队 API 键(`sk-aexol-team-…`) (中文(简体) ). 全权证书应写给 `~/.spectral/config.json` 有模式 `0600`。 。 。 .
    
2.  **启动代理**
    
    ```bash
    spectral serve
    ```
    
    这个与你的团队登记机器,打开一个长寿的WebSocket 亚克索尔接力, 并保持上升。 重接是自动的指数 备份。 让它运行起来,这就是重点.
    
3.  **打开浏览器**
    
    访问 Aexol 网络 UI. 你的机器在取货机里出现,你选 可以创建工程、开放会话,并与该机器上的代理商聊天 从任何标签.
    
    第二步和第三步是一个命令: `spectral desktop`开始 `serve` 作为 背景守护进程( 幸存者关闭终端) , 等待中继程序 ,然后在默认浏览器中打开 UI [`spectral desktop`](https://npmcn.com/package/%40aexol/spectral/#readme-spectral-desktop)。 。 。 .
    

也可以作为普通的本地TUI运行 Spectral 无需接力——仅引用 `spectral` (没有子命令),它作为 pi 终端正常会话和 Aexol MCP扩展自动装入.

## 图标

| 命令 | 说明 |
| --- | --- |
| `spectral` | 当地TUI. 将所有旗子转发到 pi; 加载捆绑的 Aexol MCP 扩展名 . |
| `spectral login` | 互动认证 。 对 MCP 后端进行密钥验证并存储. |
| `spectral logout` | 删除 `~/.spectral/config.json`。 。 。 。 . |
| `spectral serve` | 连接这台机器到Aexol中继器. 站起;活起再相接. |
| `spectral desktop` | 开始 `serve` 作为守护者,等待它,打开UI. `status` 编号 : `stop` 我也一样. |
| `spectral --version` | 打印版本 . |
| `spectral --help` | 印出相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. |

### `spectral serve` 旗帜

| 旗帜 | 说明 |
| --- | --- |
| `--machine-name <name>` | 覆盖显示名称( 默认 ): `os.hostname()`) (中文(简体) ). |

### `spectral desktop`

被移除的 Electron app 的无头替换: 相同的生命周期, 否 捆绑浏览器, UI 是您自己的浏览器 `https://aexol.ai/agent` (与 `SPECTRAL_LANDING_URL`) (中文(简体) ).

| 命令 | 说明 |
| --- | --- |
| `spectral desktop` | 启动代理, 或者重用已经运行的代理, 然后打开用户界面 . |
| `spectral desktop status` | 报告pid/版本/准备状态信号. 退出 `3` 不运行时. |
| `spectral desktop stop` | 签字,10后再签字 删除 pid / 准备的文件 . |

值得认识的机械师:

-   单个实例通过 `~/.spectral/serve.pid`,在解剖学上(`O_EXCL`(中文(简体) ) _在此之前_ 守护进程已经诞生了 —— 两个同时存在 `spectral desktop` 运行 开始一个守护进程。 一个死了的蜘蛛被检测出 并被撞倒 守护进程从不屏蔽下一次启动, 以及进程持有的 pid 文件 命令没有发射,从不覆盖或删除.
-   若为 `~/.spectral/config.json` 没有工作室的标志, `desktop` 运行 交互式 `spectral login` 流动( 拒绝在有 ) 没有终端,叫你跑 `spectral login` 自己来.
-   准备状态是一个真正的信号,而不是超时:守护进程打印 `SPECTRAL_SERVE_READY` 一旦中继 WebSocket 打开并写入 `serve-ready.json`。只有在避免了 `machine_disconnected` 如果页面在套接字前订阅, 则提示您得到 已存在.
-   `~/.spectral/serve.log` 创建 `0600` 旋转到 `serve.log.old` 时间 一旦超过10 MB(`SPECTRAL_DESKTOP_LOG_MAX_BYTES`) (中文(简体) ).
-   守护神被放大而脱落 `PATH` (单位:千美元)`/etc/paths`, (中文(简体) ), `getconf PATH`,homebrew/nvm/Node dirs),因此MCP服务器被宣布为 `npx -y <pkg>` 工作,即使Spectral是从GUI上下文启动.

任何不是光谱子命令的东西 都会逐字传送给Pi 所以任何Pi 旗子,你知道的 工作。 示例 `spectral -p "summarize this repo"`。 。 。 .

## 如何运作

```
┌────────────────┐         ┌─────────────────┐         ┌────────────────┐
│  Browser tab   │────────▶│  Aexol backend  │◀────────│  spectral serve │
│ (Aexol web UI) │  WSS    │     (relay)     │   WSS   │ (your machine)  │
└────────────────┘         └─────────────────┘         └────────────────┘
                                    │
                           identity + routing only
                           (no message content, no code)
```

-   你的机器运行 `spectral serve` 并在中继器中使用 jWT初发机.
-   该机器的浏览器会话打开后端的 WebSocket 。 后端 将每个相框转发到您的机器和后面, 它从不读取或存储 信息内容.
-   所有你的地方状态——项目,会话,消息,pi auth sords——生活于 装置。 后端只知道机器身份(ID,显示名称, hostname, last-seen)和团队成员.

## 推论如何经过

Spectral 有两种不同的执行路径,它们处理模型 API 密钥 不一样 这是故意的 选一个符合你安全要求的 型号.

```
spectral (CLI / TUI mode)            spectral serve (relay mode)
─────────────────────────            ─────────────────────────────
pi reads ~/.pi/agent/auth.json   →   pi runs in-process via PiBridge
   ↓                                    ↓
local Codex subscription auth        ALL inference → backend `/v1` proxy
   ↓                                    ↓
direct call to provider              backend uses centralized API keys
                                        ↓
                                     scoped to team's BaseModel whitelist
```

-   **`spectral` (CLI 子进程模式)** —— pi 作为普通子进程运行并使用 本地存储的 Codex 订阅认证 `~/.pi/agent/auth.json`。 。 。 . 光谱从不读取或传送. 这是典型的只有本地流.
-   **`spectral serve` (中继模式)** - pi在服务内部运行 守护进程 。 所有推断流量都是通过Aexol后端的 `/v1/messages` 财务报告和审定财务报表 `/v1/chat/completions` 以 单机JWT. 后端持有上游提供者的密钥 执行每队 `BaseModel` 白名单服务器侧 。 当地 `~/.pi/agent/auth.json` 实值 **未读** 在此模式下 (单位:千美元)`AuthStorage.inMemory()`) (中文(简体) ).

为什么只有两条路? `spectral serve` 为共享/管理机器设计,其中 团队控制哪些模型可以使用,操作员不需要提供者密钥 坐在每一个盒子. `spectral` (没有子命令)是未管理的 TUI 路径和 表现得像一个香草派安装.

## 配置

| 路径/ 变量 | 目的 |
| --- | --- |
| `~/.spectral/config.json` | Aexol MCP URL + 团队 API 密钥. 创建于 `spectral login`模式 `0600`。 。 。 . |
| `~/.spectral/machine.json` | 机器身份+中继JWT. 首先创建的 `spectral serve`。 。 。 . |
| `~/.spectral/sessions.db` | 本地 SQLite 用于项目,会话,消息. |
| `~/.spectral/serve.pid` | 中继守护进程 pid(单相锁). 被打烂了. |
| `~/.spectral/serve-ready.json` | `{pid, ts, version}` 当中继套接字打开时写入. |
| `~/.spectral/serve.log` | 守护进程 stdout/ stderr, 由 `spectral desktop`。 。 。 . |
| `SPECTRAL_CONFIG_DIR` | 覆盖以上目录. |
| `SPECTRAL_MCP_URL` | 登录时覆盖 MCP URL . |
| `SPECTRAL_BACKEND_URL` | 覆盖后端 HTTP 基础 `spectral serve`。 。 。 . |
| `SPECTRAL_RELAY_URL` | 覆盖衍生中继 WebSocket URL . |
| `SPECTRAL_LANDING_URL` | (UI)那个 `spectral desktop` 打开( 默认) `https://aexol.ai/agent`) (中文(简体) ). |
| `SPECTRAL_SERVE_LOG_PATH` | 守护进程日志路径 `spectral desktop`。 。 。 . |
| `SPECTRAL_DESKTOP_READY_TIMEOUT_MS` | 准备情况 `desktop` 放弃( 默认 1500) . |
| `SPECTRAL_DESKTOP_STOP_TIMEOUT_MS` | 在SIGKILLl前签名恩典 `desktop stop` (默认为1000). |
| `SPECTRAL_DESKTOP_LOG_MAX_BYTES` | 启动时触发旋转的 service-log 大小( 默认 10485760) . |

Pi 本地 TUI 路径( Codex 订阅) 的认证状态 `~/.pi/agent/auth.json` 在同一个机器上。 光谱从不读,从不读 随处寄出. 请注意: `spectral serve` 已经 **没有** 使用此文件- it 路由通过后端代理推导(参见 [推论如何经过](https://npmcn.com/package/%40aexol/spectral/#readme-how-inference-is-routed)) (中文(简体) ).

## Web 获取工具

光谱船是内在的 `web_fetch` 用于获取的工具(默认启用) 公开网页并返回内容为纯文本、 Markdown 或 原始 HTML (英语). 用于快速阅读静态页面、文档、 GitHub 寄存器、JSON端点和其他公共HTTP/HTTPS资源.

### 参数

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | 字符串 | 所需经费 | 要获取的公开 URL 。 必须从 `http://` 或者说 `https://`。 。 。 . |
| `format` | 字符串 | `markdown` | 输出格式 : `text`, (中文(简体) ), `markdown`,或 `html`。 。 。 . |
| `timeout` | 编号 | `30` | 请求超时数秒, 按住范围 `1`– 说吧 –`120`。 。 。 . |

### 何时使用 `web_fetch`

使用 `web_fetch` 当你只需要 **读取** 公开内容 :

-   静态文档网站和README页面.
-   GitHub 文件, blob, 或原始 URL .
-   公共JSON/XML APIs(如Reddit JSON端点).
-   简单营销页面或博客.

`web_fetch` 快速、轻量级,不需要浏览器。 适用 拒绝对SSF的保护 `file://`, (中文(简体) ), `ftp://`, (中文(简体) ), `localhost`,和私人知识产权 地址,并限制对5 MB的回复.

### 何时使用浏览器扩展

使用全数 **浏览器自动化** 扩展( 默认情况下也启用) 时 页面需要真实的浏览器 :

-   JavaScript-resisted SPA 在浏览器中生产标出.
-   需要交互(单击、滚动、窗体输入)的页面 相关内容出现.
-   屏蔽简单的 HTTP 客户端或需要 cookie / 会话状态的站点 .
-   截图、视觉核查或网络交通检查.

浏览器扩展通过 Playwright 控制一个真正的 Chromium 实例,并且可以 做所有的事 做点什么 `web_fetch` 可加交互、截图和 JavaScript 评价.

## 多个机器

你们可以跑 `spectral serve` 在你喜欢的机器上 在一个团队之下 每一个都有自己的机器身份和自己的SQLite. 浏览器拾取列表 全部; 切换机显示机器的项目列表和会话 历史 切换是一个困难的上下文变化: 前一个选择被清除 所以你不会无意中跟错误的装置说话.

## 解决问题

-   **我的机器没有出现在取取浏览器.** 确保 `spectral serve` 仍在运行( 它的日志重新连接尝试 stderr) 。 若为 `spectral login` 很久前运行了 团队键被旋转了 重新运行 `spectral login`。 。 。 .
    
-   **WebSocket继续断开.** 中继客户端自动重接 以指数回放。 预计将进行简短的网络剪接和处理。 如果 备份循环是常数, 请检查您的团队 API 密钥是否仍然有效 您的网络允许将 WebSocket 连接到已配置的后端.
    
-   **`better-sqlite3` 第一个错误 `spectral serve`。 。 。 .** 这通常意味着 安装时本地模块没有编译 。 尝试 `cd ~/.spectral && npm rebuild better-sqlite3`,或者在 确保您有一个有效的 C/C++ 工具链( )`make`,一个C编译器,Python).
    
-   **我要撤销一台机器.** 停下来 `spectral serve` 在那个装置上。 机器 从Aexol UI中撤销是行进图;今天最可靠 方法是旋转团队 API 密钥,使每台机器的无效 中继JWT的球队.
    

## 隐私数据( D)

-   **模型 API 密钥**数字 :
    -   对于 `spectral` (CLI/TUI模式):只靠机器生活,用Pi自己 `~/.pi/agent/auth.json`。从不读取或传送光谱.
    -   对于 `spectral serve` (中继模式):在 **后端**而不是机器。 。 . 本地机器只持有其机器 JWT; 供应商密钥被管理 中央和范围属于团队 `BaseModel` 白名单.
-   **代码、信件、文件内容、生成的文物** 只能靠这个生活 机器,单位 `~/.spectral/sessions.db` 和您指定的工作目录 `spectral serve` 临τ.
-   **后端仓库**:机器身份(id,显示名,主机名, 在注册时发出的JWT中继器和团队 成员。 对于 `spectral serve`,它也持有中央提供者 API 用于代表授权机器满足推断请求的密钥.
-   **后端不存储**: 提示、响应、工具呼叫、文件、, 文物,或任何其他信息通道内容.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40aexol/spectral/LICENSE)。 。 。 .

## 链接

-   网站: [https://aexol.com (中文(简体) )](https://aexol.com/)
-   源目前主机为Aexol内部寄存器;公镜为TBD.
-   问题:请在您的 Aexol 联系人中存档(公共问题跟踪器是 页:1.

## 常见问题

### @aexol/spectral 是什么？

Aexol 的 AI 编码代理器,具有以中继为基础的浏览器访问权限\.

### 如何安装 @aexol/spectral？

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

### @aexol/spectral 支持 TypeScript 吗？

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

### @aexol/spectral 支持 ESM 还是 CommonJS？

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

### @aexol/spectral 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aexol/spectral 可以商用吗？

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

### @aexol/spectral 的下载量有多少？

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

### @aexol/spectral 还在维护吗？

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