neoctl-web

Neo Web

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

会话支持立即暂停、异常后继续，以及携带新指令续接。判断标准和停止边界见 暂停与继续。

安装使用

需要 Node.js 20+。

npm install -g neoctl-web
neow

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

源码开发

在仓库根目录执行：

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/ 目录执行：

npm ci
npm start

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

常用环境变量：

默认 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/ 目录执行：

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

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

测试说明见 tests/README.md；多用户配置见 isolation.example.json 和 用户管理脚本。