neoctl-web 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neoctl-web",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Neo browser workspace with an embedded agent runtime.",
   "type": "module",
   "engines": {
@@ -13,6 +13,7 @@
     "dev:ui": "vite",
     "test:xhs": "node --test artifacts.test.mjs",
     "test:runtime": "node --test runtime-router-cleanup.test.mjs runtime-workspaces.test.mjs",
+    "test:isolation": "npm --prefix ../engine run build && node --test isolation.test.mjs isolation-startup.test.mjs",
     "test:plugins": "npm --prefix ../engine run build && node --test plugins.test.mjs plugin-settings.test.mjs tool-settings.test.mjs",
     "test:monitoring": "node --test cpa-quota.test.mjs memory-monitor.test.mjs",
     "test:control": "node --test control-sync.test.mjs control-transcript.test.mjs",
@@ -32,7 +33,7 @@
     "@tanstack/vue-virtual": "^3.13.36",
     "highlight.js": "^11.11.1",
     "marked": "^18.0.3",
-    "neoctl": "^0.2.39",
+    "neoctl": "^0.2.40",
     "streaming-markdown": "^0.2.15",
     "vue": "^3.5.13"
   },
@@ -51,6 +52,12 @@
     "control-sync.mjs",
     "control-protocol.mjs",
     "core-runtime.mjs",
+    "execution-backend.mjs",
+    "isolation.mjs",
+    "isolation-auth.mjs",
+    "isolation.example.json",
+    "scripts/isolation-user.mjs",
+    "chunk-uploads.mjs",
     "plugins.mjs",
     "plugin-settings.mjs",
     "platform-paths.mjs",

package/plugins/downloads/README.md

@@ -0,0 +1,40 @@
+# 文件下载插件（2.0）
+
+仅依赖 Node.js 标准库，通过 `neo-plugin/v1` 接入。不导入主工程模块，也不依赖视频插件。
+
+## 行为
+
+- 工具：`expose_downloads({ paths: [绝对路径, ...] })`，每批 1–20 个。
+- **没有工作区或目录白名单限制**：任何位置的现有普通文件，只要服务进程有读取权限，都可暴露；不限制扩展名。
+- **不复制、不移动原文件**。每条链接仅在插件数据目录写入一个很小的 JSON，保存随机 ID 与原始绝对路径的映射。
+- **没有自动过期时间**，`expiresAt` / `expiresAtEpochMs` 为 `null`；映射跨进程重启保留。
+- 访问时从原始路径流式读取，不把整个文件载入内存。
+- 原文件移动或删除后返回 404；无读取权限时请求失败。不搜索新位置，也没有副本兜底。
+- 链接是路径引用，不是版本快照：原路径内容更新后下载的是新内容，响应长度实时获取；若原路径重新出现文件，链接会再次可用。
+- 保持原有 `/api/downloads/<id>`、Markdown 资源协议和附件下载行为，支持 GET / HEAD。
+- 批量操作保留成功项，失败项在 `errors` 中返回。
+
+## 存储和安装
+
+宿主传入 `appDataDir` 时，默认映射目录为 `<appDataDir>/downloads`；否则为 `~/.neoctl/downloads`。
+
+可设置 `NEO_DOWNLOADS_DIR` 为单独的映射目录。这是**映射记录的存储位置**，不是待暴露文件的目录限制。
+
+将整个 `downloads` 目录放入宿主扫描的插件根目录，启用后重启服务。迁移机器时，需保留映射目录，并确保记录中的原始路径依然可访问。手动撤销某条链接，可删除映射目录下对应 `<id>` 子目录；这不会删除原文件。
+
+## 升级边界和安全
+
+旧版本仅在进程内存保存映射，且 UI 已记录旧过期时间；因此旧临时链接无法自动变成永久链接，需对原文件重新调用 `expose_downloads`。
+
+“无自动过期”不等于无需服务或存储：服务关闭、插件禁用、映射记录删除、原文件不可用时仍不能下载。
+
+链接是持有即访问的凭据，没有逐链接登录验证。不要暴露敏感文件，也不要将具备 Agent 执行能力的整个工作台直接开放到公网。映射 JSON 包含本地绝对路径，应保护其文件系统权限。
+
+## 独立测试
+
+```powershell
+cd C:\Users\qyq\Desktop\work\neoctl\web\plugins\downloads
+node --test downloads.test.mjs
+```
+
+测试覆盖跨工作区文件、无副本、无 TTL、跨进程映射恢复、原文件移动/删除、内容更新、HEAD、无效输入、路径穿越和并发暴露。

package/plugins/downloads/downloads.mjs

@@ -1,147 +1,108 @@
-import fs from 'node:fs';
+import { workspaceFs, openWorkspaceRead } from '../../execution-backend.mjs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import os from 'node:os';
 import crypto from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+
+const VALID_ID = /^[a-f0-9-]{36}$/;
 
 export class DownloadRegistry {
-  constructor() {
-    this.entries = new Map();
+  constructor(options = {}) {
+    this.storageDir = path.resolve(options.storageDir || path.join(os.homedir(), '.neoctl-downloads'));
   }
 
-  add(entry) {
+  async add(entry) {
+    const source = entry.absolutePath;
+    if (typeof source !== 'string' || !path.isAbsolute(source)) throw new Error('path must be absolute');
+    const before = await workspaceFs.stat(source);
+    if (!before.isFile()) throw new Error('path is not a regular file');
+    await fsp.mkdir(this.storageDir, { recursive: true, mode: 0o700 });
     const id = crypto.randomUUID();
-    const full = {
-      id,
-      createdAt: Date.now(),
-      ...entry,
-    };
-    this.entries.set(id, full);
-    return full;
+    const pending = path.join(this.storageDir, `.pending-${id}`);
+    await fsp.mkdir(pending, { mode: 0o700 });
+    try {
+      // Persist only a reference. Any existing absolute path is allowed, including
+      // paths outside the workspace; never copy or relocate the source file.
+      const full = { version: 2, id, createdAt: Date.now(), absolutePath: path.resolve(source),
+        filename: path.basename(source), sizeBytes: before.size, expiresAt: null };
+      await fsp.writeFile(path.join(pending, 'entry.json'), JSON.stringify(full), { mode: 0o600 });
+      await fsp.rename(pending, path.join(this.storageDir, id));
+      return full;
+    } catch (error) {
+      await fsp.rm(pending, { recursive: true, force: true });
+      throw error;
+    }
   }
 
-  get(id) {
-    const entry = this.entries.get(String(id || ''));
-    if (!entry) return undefined;
-    if (entry.expiresAt && Date.now() > entry.expiresAt) {
-      this.entries.delete(entry.id);
-      return undefined;
-    }
-    return entry;
+  async get(id) {
+    if (typeof id !== 'string' || !VALID_ID.test(id)) return undefined;
+    try {
+      const entry = JSON.parse(await fsp.readFile(path.join(this.storageDir, id, 'entry.json'), 'utf8'));
+      if (entry.version !== 2 || entry.id !== id || typeof entry.filename !== 'string'
+        || typeof entry.absolutePath !== 'string' || !path.isAbsolute(entry.absolutePath)) throw new Error('Invalid download metadata');
+      return { ...entry, expiresAt: null };
+    } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
   }
 }
 
 export function createExposeDownloadsTool(options) {
-  const ttlMs = options.ttlMs ?? 30 * 60 * 1000;
-
-  return {
+  const tool = {
     name: 'expose_downloads',
-    description:
-      'Expose one or more existing local files for the web user to download. Input must be absolute file paths. The result follows neoctl.resource-link.v1: copy each downloads[].markdown value verbatim into the final response, without rewriting or prefixing its link.',
+    description: 'Expose existing local files for browser download with no automatic expiration. Only absolute-path mappings are persisted; no file is copied. Any readable regular file anywhere is allowed, including outside the workspace. Links survive restarts but fail when the original path is moved, deleted, or unreadable. Anyone with the link can download. Input must be absolute paths. Copy downloads[].markdown verbatim (neoctl.resource-link.v1).',
     inputSchema: {
       type: 'object',
-      properties: {
-        paths: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Absolute file paths to expose for browser download.',
-        },
-      },
-      required: ['paths'],
-      additionalProperties: false,
-    },
-    metadata: {
-      readOnly: true,
-      concurrent: true,
-      visible: true,
-      requiresApproval: false,
-      maxResultSizeChars: 12000,
+      properties: { paths: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 20, description: 'Absolute file paths to publish as permanent browser downloads.' } },
+      required: ['paths'], additionalProperties: false,
     },
+    metadata: { readOnly: false, concurrent: true, visible: true, requiresApproval: false, maxResultSizeChars: 20000 },
     validate(input) {
-      const paths = Array.isArray(input?.paths)
-        ? input.paths.map((item) => String(item || '').trim()).filter(Boolean)
-        : [];
-      if (!paths.length) throw new Error('paths must be a non-empty array');
-      if (paths.length > 20) throw new Error('too many paths; maximum is 20');
-      for (const filePath of paths) {
-        if (!path.isAbsolute(filePath)) throw new Error(`path must be absolute: ${filePath}`);
-      }
-      return { paths };
+      if (!Array.isArray(input?.paths) || !input.paths.length || input.paths.length > 20
+        || input.paths.some((p) => typeof p !== 'string' || !path.isAbsolute(p))) throw new Error('paths must contain 1–20 absolute file paths');
+      return { paths: [...new Set(input.paths)] };
     },
-    async execute(input, context) {
-      const downloads = [];
-      for (const rawPath of input.paths) {
-        const absolutePath = path.resolve(rawPath);
-        const stat = await fsp.stat(absolutePath).catch(() => undefined);
-        if (!stat) throw new Error(`file does not exist: ${absolutePath}`);
-        if (!stat.isFile()) throw new Error(`path is not a file: ${absolutePath}`);
-        const entry = options.registry.add({
-          absolutePath,
-          filename: path.basename(absolutePath),
-          sizeBytes: stat.size,
-          expiresAt: Date.now() + ttlMs,
-          sessionId: context.session?.sessionId,
-        });
-        const url = `/api/downloads/${encodeURIComponent(entry.id)}`;
-        const reference = `sandbox:${url}`;
-        downloads.push({
-          id: entry.id,
-          filename: entry.filename,
-          sizeBytes: entry.sizeBytes,
-          url,
-          reference,
-          markdown: `[${entry.filename.replace(/([\\\]])/g, '\\$1')}](${reference})`,
-          expiresAt: new Date(entry.expiresAt).toISOString(),
-          expiresAtEpochMs: entry.expiresAt,
-        });
+    async execute(input, context = {}) {
+      const downloads = [], errors = [];
+      for (const absolutePath of tool.validate(input).paths) {
+        try {
+          const entry = await options.registry.add({ absolutePath });
+          const url = `/api/downloads/${entry.id}`;
+          const reference = `sandbox:${url}`;
+          const label = entry.filename.replace(/[\r\n]/g, ' ').replace(/([\\[\]<>`*_])/g, '\\$1');
+          downloads.push({ id: entry.id, filename: entry.filename, sizeBytes: entry.sizeBytes, url, reference,
+            markdown: `[${label}](${reference})`, expiresAt: null, expiresAtEpochMs: null });
+        } catch (error) { errors.push({ path: absolutePath, error: error.message }); }
       }
       await options.onExpose?.({ sessionId: context.session?.sessionId, downloads });
-      return {
-        ok: true,
-        output: {
-          resourceProtocol: 'neoctl.resource-link.v1',
-          usage: 'Copy downloads[].markdown verbatim when linking the resource. Do not alter the reference URI.',
-          downloads,
-          _ui: {
-            resources: downloads.map((item) => ({
-              kind: 'download',
-              url: item.url,
-              reference: item.reference,
-              label: item.filename,
-              downloadName: item.filename,
-              sizeBytes: item.sizeBytes,
-              expiresAt: item.expiresAtEpochMs,
-            })),
-          },
-        },
-        summary: `Exposed ${downloads.length} file(s) for browser download.`,
-      };
+      return { ok: !errors.length, output: {
+        resourceProtocol: 'neoctl.resource-link.v1',
+        usage: 'Copy downloads[].markdown verbatim. Links have no automatic expiration; expiresAt is null.',
+        downloads, errors,
+        _ui: { resources: downloads.map((item) => ({ kind: 'download', url: item.url, reference: item.reference,
+          label: item.filename, downloadName: item.filename, sizeBytes: item.sizeBytes })) },
+      }, summary: `Exposed ${downloads.length} permanent download(s); ${errors.length} failed.` };
     },
   };
+  return tool;
 }
 
-export function serveDownload(registry, req, res, id) {
-  const entry = registry.get(id);
-  if (!entry) {
-    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
-    res.end(JSON.stringify({ error: 'download not found or expired' }));
-    return;
-  }
-
-  res.writeHead(200, {
-    'Content-Type': 'application/octet-stream',
-    'Content-Length': String(entry.sizeBytes),
-    'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(entry.filename)}`,
-    'Cache-Control': 'no-store',
-  });
-
-  fs.createReadStream(entry.absolutePath)
-    .on('error', () => {
-      if (!res.headersSent) {
-        res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
-        res.end('failed to read file');
-      } else {
-        res.destroy();
-      }
-    })
-    .pipe(res);
+export async function serveDownload(registry, req, res, id) {
+  let handle;
+  try {
+    const entry = await registry.get(id);
+    if (!entry) { res.writeHead(404, { 'Cache-Control': 'no-store' }); res.end(req.method === 'HEAD' ? undefined : 'Download not found'); return; }
+    handle = await openWorkspaceRead(entry.absolutePath);
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw Object.assign(new Error('Not a file'), { code: 'ENOENT' });
+    res.writeHead(200, {
+      'Content-Type': 'application/octet-stream', 'Content-Length': stat.size,
+      'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(entry.filename).replace(/['()*]/g, (c) => '%' + c.charCodeAt(0).toString(16))}`,
+      'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+    });
+    if (req.method === 'HEAD') res.end();
+    else await pipeline(handle.createReadStream({ autoClose: false }), res);
+  } catch (error) {
+    if (res.headersSent || res.destroyed) { if (!res.destroyed) res.destroy(); }
+    else { res.writeHead(error.code === 'ENOENT' ? 404 : 500, { 'Cache-Control': 'no-store' }); res.end(req.method === 'HEAD' ? undefined : 'Unable to read download'); }
+  } finally { await handle?.close(); }
 }

package/plugins/downloads/downloads.test.mjs

@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import http from 'node:http';
+import { spawnSync } from 'node:child_process';
+import { createPlugin } from './index.mjs';
+
+async function setup(t) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'downloads-test-'));
+  const outside = await fs.mkdtemp(path.join(os.tmpdir(), 'outside-workspace-'));
+  const source = path.join(outside, '中文 [report].txt');
+  await fs.writeFile(source, 'original contents');
+  const context = { appDataDir: root, env: {} };
+  let plugin = createPlugin(context);
+  const server = http.createServer(async (req, res) => {
+    try { if (!await plugin.route(req, res, new URL(req.url, 'http://localhost'))) { res.statusCode = 404; res.end(); } }
+    catch (error) { res.statusCode = 500; res.end(error.message); }
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  t.after(async () => { server.closeAllConnections(); await new Promise((r) => server.close(r)); await fs.rm(root, { recursive: true, force: true }); await fs.rm(outside, { recursive: true, force: true }); });
+  return { root, outside, source, plugin, base: `http://127.0.0.1:${server.address().port}`, restart() { plugin = createPlugin(context); } };
+}
+
+test('arbitrary outside-workspace file: only metadata stored, no copies, no expiry', async (t) => {
+  const f = await setup(t);
+  const result = await f.plugin.tools[0].execute({ paths: [f.source] }, { cwd: f.root });
+  assert.equal(result.ok, true);
+  const d = result.output.downloads[0];
+  assert.equal(d.expiresAt, null); assert.equal(d.expiresAtEpochMs, null);
+  assert.equal(result.output._ui.resources[0].expiresAt, undefined);
+  const storedDir = path.join(f.root, 'downloads', d.id);
+  assert.deepEqual(await fs.readdir(storedDir), ['entry.json']);
+  const record = JSON.parse(await fs.readFile(path.join(storedDir, 'entry.json'), 'utf8'));
+  assert.equal(record.absolutePath, f.source);
+  const r = await fetch(f.base + d.url);
+  assert.equal(r.status, 200); assert.match(r.headers.get('content-disposition'), /^attachment;/);
+  assert.equal(await r.text(), 'original contents');
+  const head = await fetch(f.base + d.url, { method: 'HEAD' });
+  assert.equal(head.status, 200); assert.equal(head.headers.get('content-length'), '17'); assert.equal(await head.text(), '');
+});
+
+test('mapping survives restart and future clock; serves current original bytes and length', async (t) => {
+  const f = await setup(t), d = (await f.plugin.tools[0].execute({ paths: [f.source] })).output.downloads[0];
+  const script = `import { DownloadRegistry } from ${JSON.stringify(new URL('./downloads.mjs', import.meta.url).href)}; Date.now = () => 9999999999999; const e = await new DownloadRegistry({ storageDir: ${JSON.stringify(path.join(f.root, 'downloads'))} }).get(${JSON.stringify(d.id)}); if (!e || e.expiresAt !== null) process.exit(1); console.log(e.id);`;
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+  assert.equal(child.status, 0, child.stderr);
+  f.restart();
+  await fs.writeFile(f.source, 'updated longer original contents');
+  const r = await fetch(f.base + d.url); assert.equal(r.status, 200); assert.equal(r.headers.get('content-length'), '32'); assert.equal(await r.text(), 'updated longer original contents');
+});
+
+test('moving or deleting the original invalidates the link, no fallback copy', async (t) => {
+  const f = await setup(t), d = (await f.plugin.tools[0].execute({ paths: [f.source] })).output.downloads[0];
+  const moved = path.join(f.outside, 'moved.txt');
+  await fs.rename(f.source, moved);
+  const missing = await fetch(f.base + d.url); assert.equal(missing.status, 404); await missing.text();
+  f.restart(); const afterRestart = await fetch(f.base + d.url); assert.equal(afterRestart.status, 404); await afterRestart.text();
+  const next = (await f.plugin.tools[0].execute({ paths: [moved] })).output.downloads[0];
+  await fs.rm(moved);
+  const deleted = await fetch(f.base + next.url); assert.equal(deleted.status, 404); await deleted.text();
+});
+
+test('invalid paths, directories, missing files, malformed URLs and HTTP writes are rejected', async (t) => {
+  const f = await setup(t), tool = f.plugin.tools[0];
+  for (const paths of [[], ['relative'], [null], Array(21).fill(f.source)]) assert.throws(() => tool.validate({ paths }));
+  const result = await tool.execute({ paths: [f.source, f.outside, path.join(f.outside, 'absent')] });
+  assert.equal(result.ok, false); assert.equal(result.output.errors.length, 2); assert.equal(result.output.downloads.length, 1);
+  const d = result.output.downloads[0];
+  for (const suffix of ['%2e%2e%2fsecret', 'bad%', 'a'.repeat(36), d.id + '/extra']) {
+    const r = await fetch(f.base + '/api/downloads/' + suffix); assert.equal(r.status, 404); await r.text();
+  }
+  const post = await fetch(f.base + d.url, { method: 'POST' }); assert.equal(post.status, 405); await post.text();
+});
+
+test('concurrent exposure persists separate tiny mappings', async (t) => {
+  const f = await setup(t);
+  const results = await Promise.all(Array.from({ length: 8 }, () => f.plugin.tools[0].execute({ paths: [f.source] })));
+  const ids = results.map((r) => r.output.downloads[0].id);
+  assert.equal(new Set(ids).size, 8);
+  for (const id of ids) assert.deepEqual(await fs.readdir(path.join(f.root, 'downloads', id)), ['entry.json']);
+});

package/plugins/downloads/index.mjs

@@ -1,18 +1,20 @@
+import path from 'node:path';
+import os from 'node:os';
 import { createExposeDownloadsTool, DownloadRegistry, serveDownload } from './downloads.mjs';
 
-export function createPlugin() {
-  const registry = new DownloadRegistry();
+export function createPlugin(context = {}) {
+  const env = context.env || process.env;
+  const registry = new DownloadRegistry({ storageDir: env.NEO_DOWNLOADS_DIR || path.join(context.appDataDir || path.join(os.homedir(), '.neoctl'), 'downloads') });
   return {
     tools: [createExposeDownloadsTool({ registry })],
     promptSections: [{
-      name: 'Web Downloads',
-      requiresTools: ['expose_downloads'],
-      cacheStable: true,
-      content: 'When you create, modify, export, package, or identify local files that the web user should receive, call expose_downloads with the relevant absolute paths before the final response. For every link in your response, copy the returned downloads[].markdown value verbatim. This is the neoctl.resource-link.v1 protocol: never construct a link, alter the reference URI, or add/remove a sandbox: prefix. The tool also returns expiresAt as an ISO timestamp.',
+      name: 'Web Downloads', requiresTools: ['expose_downloads'], cacheStable: true,
+      content: 'When you create, modify, export, package, or identify local files that the web user should receive as downloads, call expose_downloads with the relevant absolute paths before the final response. For every download link, copy downloads[].markdown verbatim (neoctl.resource-link.v1): never construct links or add/remove a sandbox: prefix. Only the link-to-original-absolute-path mapping is persisted, with no file copy and no directory restriction. Links do not automatically expire and expiresAt is null. If the original path is moved, deleted, or unreadable, the link stops working. Anyone with a link can download. Historical links from the old in-memory plugin cannot be restored; re-expose the original file if needed.',
     }],
     async route(req, res, url) {
-      if (req.method !== 'GET' || !url.pathname.startsWith('/api/downloads/')) return false;
-      const id = decodeURIComponent(url.pathname.slice('/api/downloads/'.length));
+      if (!url.pathname.startsWith('/api/downloads/')) return false;
+      if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405, { Allow: 'GET, HEAD' }); res.end(); return true; }
+      const id = url.pathname.slice('/api/downloads/'.length);
       await serveDownload(registry, req, res, id);
       return true;
     },

package/plugins/downloads/neo-plugin.json

@@ -2,8 +2,8 @@
   "protocol": "neo-plugin/v1",
   "id": "downloads",
   "name": "文件下载",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "entry": "index.mjs",
   "defaultEnabled": true,
-  "description": "将本地文件安全地暴露为临时浏览器下载链接。"
+  "description": "仅持久保存原始文件路径映射，无目录限制、无文件复制、无自动过期；原文件移动或删除后链接失效。"
 }

package/plugins/video-share/README.md

@@ -0,0 +1,55 @@
+# video-share：独立视频播放插件
+
+仅依赖 Node.js 20+ 标准库，无 npm 依赖、不需要构建、不导入宿主或 downloads 插件的任何模块。通过 `neo-plugin/v1` 的工厂上下文、tools、promptSections、presentToolResult 和 route 接口接入；整个目录可复制或移除。播放器 HTML/CSS、文件存储、HTTP Range 逻辑、测试全部在插件内部，不修改 Vue 或宿主路由。
+
+## 功能
+
+- `expose_videos({ paths: [绝对视频路径, ...] })`：每批最多 20 个，返回视频元数据、供程序使用的 `url` / `mediaUrl`、内嵌展示 `_ui`，以及 `expiresAt: null`。不再返回 Markdown 链接；文字回复不得贴视频 URL、Markdown 链接或 HTML 视频标签，只需说明视频已就绪。
+- `revoke_videos({ ids: [视频 ID, ...] })`：用户要求时手动撤销链接并删除路径映射，不删除或修改原视频。已下载内容和正在传输的数据不能追回。
+- `/api/video-share/<id>`：插件自带 HTML5 播放器，由聊天页面以同源 iframe 直接嵌入，带播放/暂停、拖动、音量、全屏控件；页面中没有新窗口或直链按钮。
+- `/api/video-share/<id>/media`：正确的视频 MIME、`Content-Disposition: inline`，支持 GET、HEAD、单段 Range / 206 / 416 和 If-Range。未知单位或多段 Range 回退完整 200 响应。
+- 无自动过期和定时清理；每条视频以随机 192 位 token 发布，独立原子落盘记录，支持并发发布和跨进程恢复。
+- 接受 `.mp4`、`.m4v`、`.mov`、`.webm`、`.ogv`，检查基本容器签名，但不做解码或转码。推荐 MP4（H.264 / AAC）或 WebM。扩展名和容器合法不保证浏览器支持内部编码。
+- 播放器直接显示在消息中，不需要点击链接，不打开新页面，不触发附件下载。通过现有 `kind: embed` 和 `presentationLevel: primary` 通用协议实现，不改宿主 Vue 代码。部分成功的批量结果也显示成功视频；历史工具结果可经 presenter 重新展示，但历史助手文字不会被自动改写。
+
+## 存储行为
+
+视频与 downloads 一样采用**零复制**：仅保存原始绝对路径映射，不复制、不移动视频、不创建硬链接或软链接。原视频可在任意目录（需服务具有读取权限），访问时从原路径流式读取，支持 Range 拖动。原视频移动或删除后，播放页和视频直链均返回 404；不可读时请求失败，不查找新位置、无副本兜底。
+
+映射跨重启保留、无自动过期。原路径内容更新后播放新内容；若该路径重新出现文件，链接可再次访问。重复发布只新增很小的 JSON 映射。撤销仅删除映射，不触碰原视频。这里的零复制指不创建磁盘副本，网络传输仍采用 Node.js 流。
+
+升级说明：旧 v1 记录没有原始路径，不能自动转换；旧视频链接将返回 404，需要重新暴露原视频。不会自动删除旧副本，确认不再需要后可手动清理旧 ID 目录。
+
+默认目录是宿主传入的 `<appDataDir>/video-share`；无宿主数据目录时使用 `~/.neo-video-share/video-share`。`NEO_VIDEO_SHARE_DIR` 可覆盖整个存储位置。
+
+“无自动过期”仍以服务运行、插件启用、发布数据存在为前提。删除插件数据、撤销链接或停止服务会影响访问。请备份映射目录，并保留原始视频路径，保持链接的域名/端口不变。中断发布可能遗留 `.pending-*`，撤销清理失败可能遗留 `.revoked-*`；这些不是公开记录，可在停止服务后手动清理。
+
+## 安装与配置
+
+将整个 `video-share` 目录放入宿主扫描的插件根目录（本仓库为 `web/plugins`）。在插件设置中启用并重启服务；如果 `NEO_WEB_PLUGINS` 使用显式列表，也要加入 `video-share`。
+
+可选环境变量：
+
+```powershell
+$env:NEO_VIDEO_SHARE_DIR = 'D:\neo-data\published-videos'
+$env:NEO_VIDEO_SHARE_PUBLIC_ORIGIN = 'https://videos.example.com'
+```
+
+`NEO_VIDEO_SHARE_PUBLIC_ORIGIN` 只接受 HTTP(S) origin，不含路径、查询参数或凭据。该配置仅影响程序使用的 `url` / `mediaUrl`；聊天内嵌资源始终使用同源相对路径，避免跨域 CSP 拒绝嵌入。设置后直链返回完整 URL，需由你配置该域名到插件路由的反向代理，插件不会自动开放网络或修改防火墙。
+
+非 neo 宿主也可以直接 `import { createPlugin } from './index.mjs'`，传入 `{ appDataDir, env }`，将返回的 `route(req, res, new URL(...))` 接到 Node HTTP 服务，并调用返回工具的 `execute`。宿主渲染时使用 `_ui` 或 `presentToolResult` 的 embed 资源。无宿主 SDK 依赖。
+
+## 安全边界
+
+持有链接即可访问，没有逐视频登录验证。只有明确暴露的文件可访问；URL 不接受本地路径，没有公开目录列表或发布/撤销 HTTP 接口。文件名经过 HTML 转义，播放器使用 CSP 和 no-referrer。`Cache-Control: no-store` 只控制缓存，并非链接过期。
+
+保护存储目录的文件系统权限；不要分享敏感视频。远程共享时仅代理视频路由并使用 HTTPS，不要把整个具备文件修改和执行命令能力的 Agent 工作台直接暴露到公网。
+
+## 独立测试
+
+```powershell
+cd C:\Users\qyq\Desktop\work\neoctl\web\plugins\video-share
+node --test video-share.test.mjs
+```
+
+测试使用带容器头的合成字节验证 HTTP、Range、HEAD、零复制、移动/删除失效、原文件更新、持久性、撤销安全、旧版边界、输入校验、转义、并发和独立进程恢复；它不是浏览器真实视频解码测试。

package/plugins/video-share/http.mjs

@@ -0,0 +1,86 @@
+import { openWorkspaceRead } from '../../execution-backend.mjs';
+import fs from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+
+export const PREFIX = '/api/video-share/';
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+export function playerPage(entry, options = {}) {
+  const title = escapeHtml(entry.filename);
+  const src = `${(process.env.NEO_WEB_BASE_PATH || "").replace(/\/$/, "")}${PREFIX}${entry.id}/media`;
+  const theme = options.theme === 'light' ? 'light' : 'dark';
+  return `<!doctype html><html lang="zh-CN" data-theme="${theme}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title><style>
+  :root{color-scheme:dark;--bg:#11151d;--fg:#eee;--muted:#aab2c1}html[data-theme=light]{color-scheme:light;--bg:#fff;--fg:#222;--muted:#667085}*{box-sizing:border-box}html,body{height:100%;margin:0}body{background:var(--bg);color:var(--fg);font:14px system-ui,sans-serif}main{height:100%;display:flex;flex-direction:column;gap:10px;padding:14px}h1{margin:0;font-size:16px;overflow-wrap:anywhere}video{display:block;flex:1;min-height:0;width:100%;background:#000;border-radius:8px}p{margin:0;color:var(--muted);font-size:12px;line-height:1.5}
+  </style></head><body><main><h1>${title}</h1><video controls playsinline preload="metadata" src="${src}">浏览器不支持视频播放。</video></main></body></html>`;
+}
+
+// A single byte range is sufficient for HTML5 media. Ignore unknown/multipart ranges.
+export function parseRange(value, size) {
+  if (!value || !value.startsWith('bytes=') || value.includes(',')) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(value);
+  if (!match || (!match[1] && !match[2])) return false;
+  if (!size) return false;
+  let start, end;
+  if (!match[1]) {
+    const suffix = Number(match[2]);
+    if (!Number.isSafeInteger(suffix) || suffix <= 0) return false;
+    start = Math.max(0, size - suffix); end = size - 1;
+  } else {
+    start = Number(match[1]); end = match[2] ? Number(match[2]) : size - 1;
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= size || start > end) return false;
+    end = Math.min(end, size - 1);
+  }
+  return { start, end };
+}
+
+function text(res, status, message, head = false) {
+  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+  res.end(head ? undefined : message);
+}
+
+export function createVideoRoute(store) {
+  return async (req, res, url) => {
+    if (!url.pathname.startsWith(PREFIX)) return false;
+    const head = req.method === 'HEAD';
+    if (req.method !== 'GET' && !head) { res.setHeader('Allow', 'GET, HEAD'); text(res, 405, 'Method not allowed'); return true; }
+    const match = /^\/api\/video-share\/([a-f0-9]{48})(\/media)?$/.exec(url.pathname);
+    if (!match) { text(res, 404, 'Video not found', head); return true; }
+    let handle;
+    try {
+      const entry = await store.get(match[1]);
+      if (!entry) { text(res, 404, 'Video not found', head); return true; }
+      handle = await openWorkspaceRead(entry.mediaPath);
+      const stat = await handle.stat();
+      if (!stat.isFile()) { text(res, 404, 'Video not found', head); return true; }
+      res.setHeader('X-Content-Type-Options', 'nosniff');
+      res.setHeader('Referrer-Policy', 'no-referrer');
+      res.setHeader('Cache-Control', 'no-store');
+      if (!match[2]) {
+        const body = playerPage(entry, { theme: url.searchParams.get('theme') });
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Length': Buffer.byteLength(body),
+          'Content-Security-Policy': "default-src 'none'; media-src 'self'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'self'" });
+        res.end(head ? undefined : body);
+        return true;
+      }
+      const etag = `"${entry.id}-${stat.size}-${stat.mtimeMs}-${stat.ctimeMs}"`;
+      const rangeHeader = req.headers['if-range'] && req.headers['if-range'] !== etag ? undefined : req.headers.range;
+      const range = head ? null : parseRange(rangeHeader, stat.size);
+      res.setHeader('Accept-Ranges', 'bytes');
+      res.setHeader('ETag', etag);
+      if (range === false) { res.setHeader('Content-Range', `bytes */${stat.size}`); text(res, 416, 'Range not satisfiable', head); return true; }
+      const length = range ? range.end - range.start + 1 : stat.size;
+      res.setHeader('Content-Type', entry.contentType);
+      res.setHeader('Content-Disposition', `inline; filename*=UTF-8''${encodeURIComponent(entry.filename).replace(/['()*]/g, (c) => '%' + c.charCodeAt(0).toString(16))}`);
+      res.setHeader('Content-Length', length);
+      if (range) res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${stat.size}`);
+      res.statusCode = range ? 206 : 200;
+      if (head) res.end();
+      else await pipeline(handle.createReadStream({ ...(range || {}), autoClose: false }), res);
+      return true;
+    } catch (error) {
+      if (res.headersSent || res.destroyed) { if (!res.destroyed) res.destroy(); }
+      else text(res, error.code === 'ENOENT' ? 404 : 500, error.code === 'ENOENT' ? 'Video not found' : 'Unable to serve video', head);
+      return true;
+    } finally { await handle?.close(); }
+  };
+}