# neoctl-web 中文文档

规范地址：https://npmcn.com/package/neoctl-web/

版本：0\.1\.37
npm 元数据更新时间：2026-11-04T04:30:43.384Z
中文译文更新时间：2026-11-04T06:33:34.115Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/neoctl-web
原文对照：https://npmcn.com/package/neoctl-web/?lang=original

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

- 包体积（解压后）：2.7 MB，107 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2026-09-04T10:50:24.532Z
- 最新版本发布：2026-11-04T04:30:43.223Z
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

带有嵌入式代理运行时的Neo浏览器工作区。

## 安装

```sh
npm install neoctl-web
```

也可以使用：`pnpm add neoctl-web`、`yarn add neoctl-web`、`bun add neoctl-web`

## README

# Neo Web

基于 Vue 3 和 Vite 的浏览器工作台，使用 Neo Engine 处理对话和工具调用。提供会话管理、图片上传、运行状态查看和插件功能。

会话支持立即暂停、异常后继续，以及携带新指令续接。判断标准和停止边界见 [暂停与继续](https://npmcn.com/package/neoctl-web/docs/pause-resume.md)。

## 安装使用

需要 Node.js 20+。

```sh
npm install -g neoctl-web
neow
```

`neow` 自动打开浏览器，默认地址为 `http://127.0.0.1:5173`，端口占用时自动顺延。在页面中填写模型 API 地址、密钥和模型名称即可开始对话。

## 源码开发

在仓库根目录执行：

```sh
npm ci --prefix engine
npm ci --prefix web
npm --prefix web run dev
```

打开 `http://localhost:5173`。`dev` 会构建并使用本地 Engine；`dev:package` 改用 npm 安装的核心。

## 演示模式

在空闲的空会话中，连续点击 5 次“运行上下文”（相邻点击不超过 600ms）进入；右下角仅提示“已进入演示模式”。点击别处、编辑输入或切换会话会重置计数。

后台通过原有模型网关、工具调度和 SSE 模拟，每次响应间隔 3 秒；内置工具及已注册工具均至少展示两次，并安排两次有间隔的上下文压缩，压缩后继续对话。演示不调用真实模型、搜索服务或 shell，不修改工作区文件；下载、视频和编辑器使用现有插件保存演示样例。

演示会话内发送的文字和附件正常显示并保存，但不触发回复，也不打断脚本。停止或刷新后仍保持此行为；新建会话恢复正常使用。

## 框架改进建议

内置工具 `framework_feedback` 复用模型配置中的工具开关（默认开启），也支持会话级覆盖。启用时提示模型先完成用户任务，再简短提交实际框架问题、复现方式和改进方向；禁用后，后续模型请求不再包含该工具的定义及自动生成的提示。关闭不会删除已提交意见。

每次只接收一组 `title`、`body`，分别最多 60、400 字。意见只保存在本机，不自动上传。模型配置最底部的“框架改进建议”进入二级页面，每页 10 条，按时间倒序查看；支持单条删除，确认后移除本机记录，删除最后一页的末条时自动返回有效页。隔离模式仅管理员可查看、删除汇总。Web 数据保存在应用数据目录的 `framework-feedback` 子目录，独立 CLI 默认为 `~/.neoctl/framework-feedback`。

## 生产启动

在 `web/` 目录执行：

```sh
npm ci
npm start
```

`npm start` 会先构建前端，再启动服务，默认监听 `0.0.0.0:5173`，使用 npm 核心。已有本地 Engine 构建时，可运行 `npm start -- --core local`。

常用环境变量：

| 变量 | 用途 |
| --- | --- |
| `APP_HOST` / `APP_PORT` | 生产服务监听地址和端口 |
| `VITE_HOST` / `VITE_PORT` | 开发服务监听地址和端口 |
| `NEO_WEB_DATA_DIR` | Web 数据目录 |
| `NEO_WORKSPACE_ROOT` | 会话工作目录的根路径 |

默认 Web 数据目录为 Windows 的 `%LOCALAPPDATA%\neoctl-web`、macOS 的 `~/Library/Application Support/neoctl-web`、Linux 的 `${XDG_DATA_HOME:-~/.local/share}/neoctl-web`。

## 可选的桌面资源定位协议

资源插件不依赖桌面模块。`route(req, res, url, helpers)` 可在完成自身资源授权、文件存在性与可读性校验后，将 `helpers.localResourceHeaders?.(req, absolutePath)` 合入响应头；没有 helper 时保持原有 GET/HEAD 行为。不得直接信任请求中传入的本地路径。

桌面客户端对原资源 URL 发送 `HEAD` 和 `X-Neo-Resource-Action: reveal`，读取百分号编码的 `X-Neo-Resource-Path`，再调用壳提供的通用定位能力。宿主只在受管桌面本地服务（`NEO_DESKTOP_LOCAL_RESOURCES=1`、监听 `127.0.0.1`、非 Docker）提供路径；普通 GET/HEAD 和浏览器下载不暴露路径。前端拒绝跨源和重定向，壳再次核对当前受管运行时的精确 origin，并验证本机普通文件。不会通过 URL 或命令行执行资源。

协议没有插件专用路由、注册表镜像或缓存；插件缺失、关闭或不支持时不触发本地动作。新增插件只需选择实现协议，无需修改桌面壳。全局停用或卸载后，历史资源的新请求也立即失效，包括桌面定位请求。

## 插件热插拔

设置页可启停插件、安装可信本地插件包或卸载插件，无需重启。安装时输入**运行 Web 服务的机器上**包含 `neo-plugin.json` 的绝对目录；不执行 npm 安装脚本，不下载远端代码。插件是可信服务器代码，拥有宿主进程权限，不是沙箱；不要安装不可信来源。包内须自包含依赖，不接受符号链接。

-   全局启停立即影响资源 HTTP 路由；运行中主会话及子代理在下一次模型调用前同时更新工具和提示词。
-   已发出的模型请求及对应工具批次使用一致快照，允许完成；卸载后不接受新的资源请求，已有 HTTP 流允许结束。
-   安装复制到数据目录 `installed-plugins/<唯一版本目录>`，候选校验和索引持久化成功后才发布。相同 ID 重装会加载新的依赖图；未变化的插件实例保持不变。
-   卸载先逻辑移除，待轮次及 HTTP 流的引用释放后调用可选 `dispose()` 并清理旧安装目录。停用不重建实例、不删除数据；卸载也保留用户数据。内置包只记录卸载状态，不修改发行文件。
-   多用户模式下只有管理员可以管理安装及全局启停；各用户使用独立实例和数据目录。`NEO_WEB_PLUGINS` 环境配置仍锁定管理操作。
-   第三方插件应只在实例中持有可释放资源，工厂失败时自行回滚，卸载时通过 `dispose()` 清理。Node.js 不支持卸载 ESM 模块缓存，宿主不承诺回收任意模块级副作用；需要这种强隔离的插件应使用独立进程。

管理 API：`GET /api/plugins`；`POST /api/plugins/global` (`enabledIds`)；`POST /api/plugins/install` (`directory`)；`POST /api/plugins/uninstall` (`id`)。目录文件的手工编辑不是热更新入口，请使用安装接口重新发布。

## 开发命令

以下命令在 `web/` 目录执行：

```sh
npm run build          # 构建前端
npm test               # 非浏览器测试，需先构建本地 Engine
npm run test:server    # 服务启动与模型配置回归
```

页面源码在 `src/`，服务入口为 `server.mjs`，插件在 `plugins/`，测试在 `tests/`。

测试说明见 [tests/README.md](https://npmcn.com/package/neoctl-web/tests/README.md)；多用户配置见 [isolation.example.json](https://npmcn.com/package/neoctl-web/isolation.example.json) 和 [用户管理脚本](https://npmcn.com/package/neoctl-web/scripts/isolation-user.mjs)。

## 常见问题

### neoctl-web 是什么？

带有嵌入式代理运行时的Neo浏览器工作区。

### 如何安装 neoctl-web？

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

### neoctl-web 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/neoctl-web 是否存在。

### neoctl-web 支持 ESM 还是 CommonJS？

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

### neoctl-web 需要什么版本的 Node\.js？

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

### neoctl-web 可以商用吗？

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

### neoctl-web 还在维护吗？

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