neoctl-web 0.1.13 → 0.1.15

package/README.md

@@ -1,244 +1,62 @@
-# maker
+# Neo Web
 
-一个 Render 风格的 Vue 3 + Vite 单页应用，面向设计人员和工作流用户封装 `neoctl` 本地 AI Agent 运行时。
+基于 Vue 3 和 Vite 的浏览器工作台，使用 Neo Engine 处理对话和工具调用。提供会话管理、图片上传、运行状态查看和插件功能。
 
-## 全局安装
+## 安装使用
 
-```bash
+需要 Node.js 20+。
+
+```sh
 npm install -g neoctl-web
 neow
 ```
 
-`neow` 会启动内置核心、Web 后台和已构建的 Vue 页面；默认使用 `5173` 与 `3101`，端口被占用时自动顺延。运行 `neow --help` 查看全部选项。
+`neow` 自动打开浏览器，默认地址为 `http://127.0.0.1:5173`，端口占用时自动顺延。在页面中填写模型 API 地址、密钥和模型名称即可开始对话。
 
-当前版本目标：先复刻 `neo web` 的能力；绘图工具等待后续 `neoctl` 更新后再接入。
+## 源码开发
 
-## 开发启动
+在仓库根目录执行：
 
-```bash
-npm run dev
+```sh
+npm ci --prefix engine
+npm ci --prefix web
+npm --prefix web run dev
 ```
 
-该命令会同时启动：
-
-- Neo 运行时：`http://127.0.0.1:3101`（仅本机）
-- Vue 单页应用：`http://0.0.0.0:5173`（本机及局域网）
-
-局域网设备可通过 `http://<本机局域网 IP>:5173` 访问。Windows 防火墙需要允许本地子网访问 TCP 5173；不要将该端口直接映射到公网，因为应用内 Agent 具备文件读写和命令执行能力。若只允许本机访问，可设置 `VITE_HOST=127.0.0.1`。
-
-每个新建对话会在用户数据目录的 `workspaces/YYMMDDHHMMSS` 下创建独立工作目录，不会向启动 `neow` 的当前目录写入数据。默认用户数据目录遵循各平台约定：
-
-- Windows：`%LOCALAPPDATA%\neoctl-web`
-- macOS：`~/Library/Application Support/neoctl-web`
-- Linux：`${XDG_DATA_HOME:-~/.local/share}/neoctl-web`
-
-可通过 `NEO_WEB_DATA_DIR` 覆盖整个数据目录，或通过 `NEO_WORKSPACE_ROOT` 单独覆盖 workspace 根目录；会话恢复时会自动回到该会话原有的工作目录。
-
-同一个 `sessionId` 只保留一个运行时。多个浏览器标签页或用户打开同一会话时会共享实时输出和输入队列，不会各自启动一份并发 Agent。会话运行时在无人连接且没有前台或后台任务后自动回收。
-
-可通过以下环境变量限制常驻内存和旁观连接：
-
-```env
-# 空闲运行时回收时间，默认 15 分钟，最小 60 秒
-NEO_RUNTIME_IDLE_MS=900000
-
-# 最多保留的空闲 session 运行时，默认 64；活跃运行时不会被强制驱逐
-NEO_RUNTIME_MAX_SESSIONS=64
-
-# 每个 session 最多同时连接的 SSE 客户端，默认 32
-NEO_SESSION_MAX_SUBSCRIBERS=32
-```
-
-右侧栏会显示 Neo 服务进程的内存使用趋势。默认每分钟采样一次，接口单次最多返回最近 60 个点；落盘数据默认最多保留 1440 个点且不超过 256 KiB，并原子写入用户数据目录的 `memory-monitor.json`。可通过 `NEO_MEMORY_MAX_PERSISTED_SAMPLES` 和 `NEO_MEMORY_MAX_PERSISTED_BYTES` 进一步收紧限制；该功能仅观测和展示，不会自动回收会话或重启进程。
-
-```env
-# 可选：内存采样间隔与落盘保留窗口（毫秒）
-NEO_MEMORY_SAMPLE_MS=60000
-NEO_MEMORY_RETENTION_MS=86400000
-```
+打开 `http://localhost:5173`。`dev` 会构建并使用本地 Engine；`dev:package` 改用 npm 安装的核心。
 
-模型配置页可填写 CPA 管理地址和密码；配置成功后，右侧栏显示 Codex 凭据的周额度。配置默认保存在用户数据目录的 `cpa-config.json`，也可通过 `NEO_CPA_CONFIG_FILE` 指定路径。
+## 生产启动
 
-Vite 会把以下路径代理到 Neo 运行时，确保本应用使用与 `neo web` 相同的后端能力：
+在 `web/` 目录执行：
 
-- `/events`：SSE 流式同步
-- `/api/state`：运行时状态
-- `/api/runtime-context`：当前 Agent 的完整系统提示词、上下文和工具协议快照
-- `/api/submit`：提交用户消息和附件
-- `/api/interrupt`：中断当前任务
-- `/api/sessions/*`：会话列表、恢复、新建、删除
-- `/api/login`：模型供应商配置
-- `/vendor/*`：neo web 运行时静态资源
-
-`expose_downloads` 可暴露任意现有绝对文件路径，不受当前工作目录限制；下载链接仍为临时链接并按注册表有效期失效。
-
-如果只想启动纯前端 Vite：
-
-```bash
-npm run dev:ui
-```
-
-## 构建
-
-```bash
-npm run build
-```
-
-## 生产部署
-
-请使用 Node.js 20 或更高版本。
-
-```bash
+```sh
 npm ci
 npm start
 ```
 
-`npm start` 会先自动执行 `npm run build`，再启动 `server.mjs`。请不要直接复用旧 `dist` 目录或只执行 `node server.mjs`，否则部署版可能继续运行旧的前端构建产物。
-
-WSL/PM2 服务器可使用 `bin/` 下的运维脚本：
-
-```bash
-./bin/deploy.sh   # 拉取、安装、构建并重启
-./bin/start.sh    # 启动生产服务
-./bin/stop.sh     # 停止服务
-./bin/restart.sh  # 重启服务
-./bin/status.sh   # 查看进程与 HTTP 健康状态
-```
-
-WSL 开机入口为 `bin/wsl-boot.sh`，它会恢复生产进程，并按当前 WSL IP 刷新 Windows 的 `22` 和 `5173` 端口转发。
-
-## 单页应用能力
-
-已实现：
-
-- 用户与模型聊天
-- 复用 `neoctl` Web API/SSE 协议
-- 流式助手输出
-- 推理过程、工具、系统、用户消息展示
-- 工具调用输出折叠/展开
-- 状态栏：模型、上下文占用、输入/输出 token、运行阶段
-- 后台任务摘要
-- 会话列表、恢复、新建、删除
-- 模型登录/配置表单
-- 图片粘贴附件，沿用 neo web 的 `[img#N]` 协议
-- Render.com 风格的侧边栏、顶部栏、卡片和工作台布局
-
-### 运行上下文订阅协议
-
-浏览器连接 `/events` 后，除会话用的 `sync` / `delta` 事件外，还会收到 `runtime.context` 事件。事件数据为 JSON，当前 `protocolVersion` 为 `1`，主要字段如下：
-
-```json
-{
-  "protocolVersion": 1,
-  "revision": 1,
-  "sessionId": "...",
-  "model": "gpt-5.6-sol",
-  "prompt": {
-    "systemPrompt": "合成后的完整系统提示词",
-    "sections": [
-      { "name": "Agent Scaffold", "content": "...", "cacheStable": true, "chars": 123 }
-    ],
-    "appPrompt": {},
-    "userContext": {},
-    "systemContext": {}
-  },
-  "tools": [
-    { "name": "read", "description": "...", "inputSchema": {}, "strict": false }
-  ],
-  "capabilities": {
-    "commands": [], "agents": [], "skills": [], "plugins": []
-  }
-}
-```
-
-首次订阅、切换/新建会话、修改模型、保存模型配置或切换应用提示词时会发布新 revision。客户端读取速度较慢时，服务端会在 SSE drain 后补发最新上下文，不会用普通 `sync` 事件替代。`GET /api/runtime-context` 提供相同结构的即时快照，可用于首次加载或断线恢复。
-
-### Web 插件
-
-下载和小红书编辑器以目录资源插件提供，不再由 core 或 Web 后台写死。插件协议由 core 的 `neo-plugin/v1` 定义，core 负责读取清单、动态导入入口、校验工具/提示词/HTTP 路由能力；Web 后台只指定插件目录并托管已加载资源。插件按 id 固定排序。
+`npm start` 会先构建前端，再启动服务，默认监听 `0.0.0.0:5173`，使用 npm 核心。已有本地 Engine 构建时，可运行 `npm start -- --core local`。
 
-默认扫描 `plugins/*/neo-plugin.json`。每个插件目录结构如下：
-
-```text
-plugins/example/
-  neo-plugin.json
-  index.mjs
-```
-
-```json
-{
-  "protocol": "neo-plugin/v1",
-  "id": "example",
-  "name": "Example",
-  "version": "1.0.0",
-  "entry": "index.mjs",
-  "defaultEnabled": true
-}
-```
-
-入口需导出 `createPlugin(context)` 或默认工厂函数，并返回 `{ tools, promptSections, route }` 中的一项或多项。`NEO_WEB_PLUGIN_DIR` 可指定其他插件根目录，`NEO_WEB_PLUGIN_DATA_DIR` 可指定传给插件的通用数据目录；插件专属配置由插件自行从 `context.env` 读取。
-
-- 全局开关位于“模型配置”，保存到用户数据目录的 `plugins.json`，重启后生效。
-- 会话开关位于“运行上下文 → 插件”，支持跟随全局、启用和关闭，从下一轮请求生效并随会话持久化。
-- `NEO_WEB_PLUGINS` 可作为部署级强制白名单；设置后全局界面只读。
-
-`NEO_WEB_PLUGINS` 支持以下值：
-
-```bash
-# 默认启用所有标记为默认启用的插件
-npm run dev
-
-# 关闭全部 Web 插件
-NEO_WEB_PLUGINS=none npm run dev
-
-# 仅启用指定插件
-NEO_WEB_PLUGINS=downloads,xhs-artifact npm run dev
-```
+常用环境变量：
 
-仓库自带的插件资源为 `downloads` 和 `xhs-artifact`。新增或移除符合协议的插件目录后重启后台即可更新目录。`GET /api/plugins` 返回全局状态，`GET/POST /api/session-plugins` 管理当前会话状态。
-
-### 消息排队
-
-模型运行中继续发送的消息会自动排队，多次发送按换行合并为下一条消息。当前轮结束后自动发送；排队内容可以取消，也可以打断当前回答后立即发送。
-
-暂未实现：
-
-- 绘图工具/画布能力。等待 `neoctl` 后续提供绘图运行时后再接。
-
-## neoctl 集成
-
-本项目已安装 npm 依赖：
-
-```bash
-neoctl@^0.2.3
-```
-
-可用脚本：
-
-```bash
-npm run neo:help   # 查看 neoctl 命令帮助
-npm run neo        # 启动 neo 命令行 REPL
-npm run neo:web    # 启动 neoctl 原生 Web UI，默认 127.0.0.1:3000
-npm run neo:login  # 交互式配置模型供应商
-```
-
-也可以直接使用：
-
-```bash
-npx neo -help
-npx neo -web --port 3001
-```
+| 变量 | 用途 |
+| --- | --- |
+| `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`。
 
-`neoctl` 会读取当前目录 `.env`、用户级配置或 `NEO_ENV_FILE` 指定的配置文件。
+## 开发命令
 
-项目提供 `.env.neo.example` 作为示例。需要项目级配置时：
+以下命令在 `web/` 目录执行：
 
-```bash
-copy .env.neo.example .env
+```sh
+npm run build          # 构建前端
+npm test               # 非浏览器测试，需先构建本地 Engine
+npm run test:server    # 服务启动与模型配置回归
 ```
 
-然后编辑 `.env` 中的模型供应商、API Key、Base URL 和模型名，也可以在单页应用的“模型配置”页面中配置。
+页面源码在 `src/`，服务入口为 `server.mjs`，插件在 `plugins/`，测试在 `tests/`。
 
-> 注意：`neoctl` 是 Node.js/CLI 运行时依赖，包含文件系统、命令执行、终端/本地 Web UI 等能力，不应直接 import 到 Vue 浏览器端组件。本项目通过“本地运行时 + Vite 代理”的方式集成。
+测试说明见 [tests/README.md](tests/README.md)；多用户配置见 [isolation.example.json](isolation.example.json) 和 [用户管理脚本](scripts/isolation-user.mjs)。

package/chunk-uploads.mjs

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export const UPLOAD_CHUNK_BYTES = 4 * 1024 * 1024
+const prefix = '/api/uploads/chunks'
+
+// No total file-size limit. Only individual requests are bounded, keeping memory
+// usage constant. Each chunk is appended to one file; completion is an atomic rename.
+export function createChunkUploadHandler({ uploadsDir, baseDir, finalize }) {
+  const sessions = new Map()
+  const partialDir = path.join(uploadsDir, '.partial')
+  const reply = (res, value, status = 200) => {
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(value))
+  }
+  const fail = (message, status = 400) => Object.assign(new Error(message), { status })
+  async function metadata(req) {
+    const chunks = []
+    let bytes = 0
+    for await (const chunk of req) {
+      bytes += chunk.length
+      if (bytes > 16384) throw fail('上传元数据过大')
+      chunks.push(chunk)
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+  }
+  async function discard(id, session) {
+    await fs.rm(session.partialPath, { force: true })
+    sessions.delete(id)
+  }
+  // Only abandoned incomplete uploads are cleaned up; completed files never expire.
+  const cleanup = setInterval(() => {
+    for (const [id, session] of sessions) {
+      if (!session.busy && Date.now() - session.updated > 24 * 60 * 60 * 1000) {
+        session.busy = true
+        void discard(id, session).catch(() => { session.busy = false })
+      }
+    }
+  }, 60 * 60 * 1000)
+  cleanup.unref()
+
+  const handle = async (req, res, url) => {
+    if (url.pathname !== prefix && !url.pathname.startsWith(prefix + '/')) return false
+    try {
+      if (url.pathname === prefix && req.method === 'POST') {
+        const body = await metadata(req)
+        const name = path.basename(String(body.name || '').replace(/\\/g, '/')).replace(/[<>:"/\\|?*\u0000-\u001f]+/g, '-').trim().slice(0, 180)
+        if (!name || name === '.' || name === '..') throw fail('文件名无效')
+        if (!Number.isSafeInteger(body.size) || body.size < 0) throw fail('文件大小无效')
+        const id = randomUUID()
+        await fs.mkdir(partialDir, { recursive: true })
+        const partialPath = path.join(partialDir, id + '.part')
+        const file = await fs.open(partialPath, 'wx')
+        await file.close()
+        sessions.set(id, { name, size: body.size, mimeType: String(body.mimeType || 'application/octet-stream'), partialPath, offset: 0, busy: false, updated: Date.now() })
+        reply(res, { ok: true, uploadId: id, offset: 0, chunkBytes: UPLOAD_CHUNK_BYTES })
+        return true
+      }
+      const match = url.pathname.slice(prefix.length).match(/^\/([a-f0-9-]{36})(\/complete)?$/)
+      if (!match) throw fail('上传地址无效', 404)
+      const id = match[1]
+      const session = sessions.get(id)
+      if (!session) throw fail('未完成的上传不存在，请重新上传', 404)
+      session.updated = Date.now()
+      if (session.busy) throw fail('上一分片仍在处理中，请重试', 409)
+      if (req.method === 'GET' && !match[2]) {
+        reply(res, { ok: true, offset: session.offset })
+        return true
+      }
+      session.busy = true
+      try {
+        if (req.method === 'DELETE' && !match[2]) {
+          await discard(id, session)
+          reply(res, { ok: true })
+        } else if (req.method === 'PATCH' && !match[2]) {
+          const offset = Number(req.headers['x-upload-offset'])
+          if (!Number.isSafeInteger(offset) || offset !== session.offset) throw fail('分片偏移不匹配', 409)
+          const file = await fs.open(session.partialPath, 'r+')
+          let received = 0
+          try {
+            for await (const chunk of req) {
+              if (received + chunk.length > UPLOAD_CHUNK_BYTES || offset + received + chunk.length > session.size) throw fail('分片大小无效', 413)
+              let written = 0
+              while (written < chunk.length) {
+                const result = await file.write(chunk, written, chunk.length - written, offset + received + written)
+                if (!result.bytesWritten) throw new Error('磁盘写入失败')
+                written += result.bytesWritten
+              }
+              received += chunk.length
+            }
+            if (!received) throw fail('分片为空')
+            session.offset += received
+          } catch (error) {
+            await file.truncate(offset)
+            throw error
+          } finally {
+            await file.close()
+          }
+          reply(res, { ok: true, offset: session.offset })
+        } else if (req.method === 'POST' && match[2]) {
+          if (session.offset !== session.size) throw fail('文件尚未上传完整', 409)
+          const storedName = `${new Date().toISOString().replace(/[:.]/g, '-')}-${id}-${session.name}`
+          const absolutePath = path.join(uploadsDir, storedName)
+          await fs.rename(session.partialPath, absolutePath)
+          sessions.delete(id)
+          const file = {
+            id: `upload-${id}`, name: session.name, storedName, size: session.size,
+            mimeType: session.mimeType, absolutePath,
+            relativePath: path.relative(baseDir, absolutePath) || storedName,
+            url: `/api/uploads/${encodeURIComponent(storedName)}`,
+          };
+          reply(res, { ok: true, file: finalize ? await finalize(file, url) : file });
+        } else throw fail('不支持的上传操作', 405)
+      } finally {
+        session.busy = false
+      }
+    } catch (error) {
+      if (!res.destroyed && !res.headersSent) reply(res, { ok: false, error: error.message || '上传失败' }, error.status || 500)
+    }
+    return true
+  }
+  handle.close = () => clearInterval(cleanup)
+  return handle
+}

package/core-runtime.mjs

@@ -23,6 +23,7 @@ export const WebRepl = webModule.WebRepl;
 export const WebRuntimeRouter = webModule.WebRuntimeRouter;
 export const createWebRuntime = webModule.createWebRuntime;
 export const runWebServer = webModule.runWebServer;
+export const handleWebRequest = webModule.handleWebRequest;
 export const coreRuntimeInfo = Object.freeze({
   source,
   version: await readCoreVersion(),