@xiaobuyu/nodesign 0.0.1 → 0.0.2

package/server/engine/runtime/workspace.js

@@ -1,164 +1,164 @@
-/**
- * engine/runtime/workspace.js — 每个 run 一个沙盒目录
- *
- * 设计要点：
- *   - 每个 run 独占 `<WORKSPACE_DIR>/<runId>/workspace/`
- *   - 所有 tool（read_file / write_file / list_dir）必须经 safeResolve 校验路径，
- *     绝不能让 agent 写到 workspace 之外（包括 `..` 越界、绝对路径、symlink 跳出）
- *   - 不放敏感数据：env、token 都不进 workspace；只放 skill 产物 + 中间文件
- *   - WORKSPACE_DIR 默认 server/runs/，可通过 env 覆盖（部署时可能挂载到独立 volume）
- *
- * 不在这层做的事：
- *   - 真正的 chroot / cgroup 沙盒：MVP 是 trust-but-verify，工具层做严格 path 校验，
- *     但不防 Node.js 进程内的反射攻击（agent 不能直接写 JS 调 fs，工具层是唯一入口）
- *   - 资源配额（disk quota / cpu）：等 P3 接入 playwright 后再考虑
- */
-
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/** 所有 workspace 的根目录（绝对路径）*/
-export const WORKSPACE_ROOT = path.resolve(
-  process.env.WORKSPACE_DIR || path.join(__dirname, '../../runs')
-);
-
-// ── runId 校验（防止把恶意字符当目录名）──
-
-const RUN_ID_RE = /^run_[a-z0-9_]{6,80}$/i;
-
-function validateRunId(runId) {
-  if (typeof runId !== 'string' || !RUN_ID_RE.test(runId)) {
-    throw new Error(`非法 runId: ${JSON.stringify(runId)}`);
-  }
-}
-
-// ── 路径辅助 ──
-
-/** 该 run 的 workspace 绝对路径（不保证存在）*/
-export function getWorkspaceRoot(runId) {
-  validateRunId(runId);
-  return path.join(WORKSPACE_ROOT, runId, 'workspace');
-}
-
-/** 该 run 的 run-level 目录（workspace 的父目录），未来可放 logs/ events.jsonl 等 */
-export function getRunRoot(runId) {
-  validateRunId(runId);
-  return path.join(WORKSPACE_ROOT, runId);
-}
-
-/**
- * 创建 workspace（幂等）。返回 workspace 绝对路径。
- */
-export async function ensureWorkspace(runId) {
-  const root = getWorkspaceRoot(runId);
-  await fs.mkdir(root, { recursive: true });
-  return root;
-}
-
-/**
- * 把相对路径解析成 workspace 内的绝对路径，并校验越界。
- *
- * 规则：
- *   - relativePath 必须是非空字符串
- *   - 解析后必须严格落在 workspace root 下（path.relative 不能以 .. 开头 / 不能是绝对）
- *   - 不接受空串、'.'、'/'、绝对路径作为目标（避免歧义）
- *
- * @returns {string} 解析后的绝对路径
- * @throws {Error}  路径越界 / 非法
- */
-export function safeResolve(runId, relativePath) {
-  const root = getWorkspaceRoot(runId);
-  if (typeof relativePath !== 'string' || relativePath.length === 0) {
-    throw new Error(`safeResolve: 相对路径必须为非空字符串，收到 ${JSON.stringify(relativePath)}`);
-  }
-  if (path.isAbsolute(relativePath)) {
-    throw new Error(`safeResolve: 不接受绝对路径 ${relativePath}`);
-  }
-  const target = path.resolve(root, relativePath);
-  const rel = path.relative(root, target);
-  // path.relative 在 target 等于 root 时返回 ''；MVP 也禁止（语义不明）
-  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-    throw new Error(`safeResolve: 路径越界或指向 workspace 自身: ${relativePath}`);
-  }
-  return target;
-}
-
-// ── 文件操作（薄包装，让 tool 层不直接 import fs）──
-
-/**
- * 读文件文本内容。
- * @param {string} runId
- * @param {string} relativePath
- * @returns {Promise<string>}
- */
-export async function readFile(runId, relativePath) {
-  const abs = safeResolve(runId, relativePath);
-  return fs.readFile(abs, 'utf8');
-}
-
-/**
- * 写文件（覆盖）；自动 mkdir 父目录。
- * @returns {Promise<{ bytes: number, path: string }>}
- */
-export async function writeFile(runId, relativePath, content) {
-  const abs = safeResolve(runId, relativePath);
-  await fs.mkdir(path.dirname(abs), { recursive: true });
-  const buf = Buffer.from(content, 'utf8');
-  await fs.writeFile(abs, buf);
-  return { bytes: buf.length, path: relativePath };
-}
-
-/**
- * 列目录（一层；不递归）。返回 [{ name, type: 'file'|'dir', size? }]
- * 不存在则返回 []（不抛）—— 让 agent 第一次访问空 workspace 不必先 try/catch
- */
-export async function listDir(runId, relativePath = '.') {
-  const root = getWorkspaceRoot(runId);
-  // '.' 单独处理：列 workspace 根
-  const abs = relativePath === '.' ? root : safeResolve(runId, relativePath);
-  let entries;
-  try {
-    entries = await fs.readdir(abs, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return [];
-    throw err;
-  }
-  const out = [];
-  for (const e of entries) {
-    const item = { name: e.name, type: e.isDirectory() ? 'dir' : 'file' };
-    if (e.isFile()) {
-      try {
-        const stat = await fs.stat(path.join(abs, e.name));
-        item.size = stat.size;
-      } catch { /* ignore */ }
-    }
-    out.push(item);
-  }
-  return out;
-}
-
-/**
- * 检查文件是否存在。返回 boolean。
- */
-export async function exists(runId, relativePath) {
-  try {
-    const abs = safeResolve(runId, relativePath);
-    await fs.access(abs);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 清理整个 run（workspace + run root）。MVP 不主动调用，留给将来的清理任务。
- * ⚠️ 注意：rm -rf 等价；只通过 runId 匹配防误删
- */
-export async function removeRun(runId) {
-  validateRunId(runId);
-  const root = getRunRoot(runId);
-  await fs.rm(root, { recursive: true, force: true });
-}
+/**
+ * engine/runtime/workspace.js — 每个 run 一个沙盒目录
+ *
+ * 设计要点：
+ *   - 每个 run 独占 `<WORKSPACE_DIR>/<runId>/workspace/`
+ *   - 所有 tool（read_file / write_file / list_dir）必须经 safeResolve 校验路径，
+ *     绝不能让 agent 写到 workspace 之外（包括 `..` 越界、绝对路径、symlink 跳出）
+ *   - 不放敏感数据：env、token 都不进 workspace；只放 skill 产物 + 中间文件
+ *   - WORKSPACE_DIR 默认 server/runs/，可通过 env 覆盖（部署时可能挂载到独立 volume）
+ *
+ * 不在这层做的事：
+ *   - 真正的 chroot / cgroup 沙盒：MVP 是 trust-but-verify，工具层做严格 path 校验，
+ *     但不防 Node.js 进程内的反射攻击（agent 不能直接写 JS 调 fs，工具层是唯一入口）
+ *   - 资源配额（disk quota / cpu）：等 P3 接入 playwright 后再考虑
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 所有 workspace 的根目录（绝对路径）*/
+export const WORKSPACE_ROOT = path.resolve(
+  process.env.WORKSPACE_DIR || path.join(__dirname, '../../runs')
+);
+
+// ── runId 校验（防止把恶意字符当目录名）──
+
+const RUN_ID_RE = /^run_[a-z0-9_]{6,80}$/i;
+
+function validateRunId(runId) {
+  if (typeof runId !== 'string' || !RUN_ID_RE.test(runId)) {
+    throw new Error(`非法 runId: ${JSON.stringify(runId)}`);
+  }
+}
+
+// ── 路径辅助 ──
+
+/** 该 run 的 workspace 绝对路径（不保证存在）*/
+export function getWorkspaceRoot(runId) {
+  validateRunId(runId);
+  return path.join(WORKSPACE_ROOT, runId, 'workspace');
+}
+
+/** 该 run 的 run-level 目录（workspace 的父目录），未来可放 logs/ events.jsonl 等 */
+export function getRunRoot(runId) {
+  validateRunId(runId);
+  return path.join(WORKSPACE_ROOT, runId);
+}
+
+/**
+ * 创建 workspace（幂等）。返回 workspace 绝对路径。
+ */
+export async function ensureWorkspace(runId) {
+  const root = getWorkspaceRoot(runId);
+  await fs.mkdir(root, { recursive: true });
+  return root;
+}
+
+/**
+ * 把相对路径解析成 workspace 内的绝对路径，并校验越界。
+ *
+ * 规则：
+ *   - relativePath 必须是非空字符串
+ *   - 解析后必须严格落在 workspace root 下（path.relative 不能以 .. 开头 / 不能是绝对）
+ *   - 不接受空串、'.'、'/'、绝对路径作为目标（避免歧义）
+ *
+ * @returns {string} 解析后的绝对路径
+ * @throws {Error}  路径越界 / 非法
+ */
+export function safeResolve(runId, relativePath) {
+  const root = getWorkspaceRoot(runId);
+  if (typeof relativePath !== 'string' || relativePath.length === 0) {
+    throw new Error(`safeResolve: 相对路径必须为非空字符串，收到 ${JSON.stringify(relativePath)}`);
+  }
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(`safeResolve: 不接受绝对路径 ${relativePath}`);
+  }
+  const target = path.resolve(root, relativePath);
+  const rel = path.relative(root, target);
+  // path.relative 在 target 等于 root 时返回 ''；MVP 也禁止（语义不明）
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`safeResolve: 路径越界或指向 workspace 自身: ${relativePath}`);
+  }
+  return target;
+}
+
+// ── 文件操作（薄包装，让 tool 层不直接 import fs）──
+
+/**
+ * 读文件文本内容。
+ * @param {string} runId
+ * @param {string} relativePath
+ * @returns {Promise<string>}
+ */
+export async function readFile(runId, relativePath) {
+  const abs = safeResolve(runId, relativePath);
+  return fs.readFile(abs, 'utf8');
+}
+
+/**
+ * 写文件（覆盖）；自动 mkdir 父目录。
+ * @returns {Promise<{ bytes: number, path: string }>}
+ */
+export async function writeFile(runId, relativePath, content) {
+  const abs = safeResolve(runId, relativePath);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  const buf = Buffer.from(content, 'utf8');
+  await fs.writeFile(abs, buf);
+  return { bytes: buf.length, path: relativePath };
+}
+
+/**
+ * 列目录（一层；不递归）。返回 [{ name, type: 'file'|'dir', size? }]
+ * 不存在则返回 []（不抛）—— 让 agent 第一次访问空 workspace 不必先 try/catch
+ */
+export async function listDir(runId, relativePath = '.') {
+  const root = getWorkspaceRoot(runId);
+  // '.' 单独处理：列 workspace 根
+  const abs = relativePath === '.' ? root : safeResolve(runId, relativePath);
+  let entries;
+  try {
+    entries = await fs.readdir(abs, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const e of entries) {
+    const item = { name: e.name, type: e.isDirectory() ? 'dir' : 'file' };
+    if (e.isFile()) {
+      try {
+        const stat = await fs.stat(path.join(abs, e.name));
+        item.size = stat.size;
+      } catch { /* ignore */ }
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * 检查文件是否存在。返回 boolean。
+ */
+export async function exists(runId, relativePath) {
+  try {
+    const abs = safeResolve(runId, relativePath);
+    await fs.access(abs);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 清理整个 run（workspace + run root）。MVP 不主动调用，留给将来的清理任务。
+ * ⚠️ 注意：rm -rf 等价；只通过 runId 匹配防误删
+ */
+export async function removeRun(runId) {
+  validateRunId(runId);
+  const root = getRunRoot(runId);
+  await fs.rm(root, { recursive: true, force: true });
+}

package/server/lib/artifact-file-path.js

@@ -1,80 +1,80 @@
-/**
- * server/lib/artifact-file-path.js — artifact-file 的路径判据（2026-08-18 抽出）
- *
- * 抽出来的直接原因是行数棘轮，但抽对了：这几行是**安全判据**，而且它有一条已知的
- * 错（见下面 `tasks/` 那段），judge 类的东西住在路由里没法单测。
- *
- * 可服务根 = 整个项目工作区（产物就住在这儿），但挡掉基础设施：`.claude/`（含
- * settings.json 和整份 SDK 转录）、`.nd/`（会话私档）、`.git/`。扁平化之前这三样
- * 都在可服务根之外、是目录结构在替我们把门；现在它们跟产物同级，必须显式拦 ——
- * 否则 `artifact-file/.claude/settings.json` 是一个能公开读到配置的 URL。
- *
- * 点开头**一刀切拒是错的**：缩略图住在 `assets/generated/.thumbnails/`，一刀切下去
- * 产物墙上所有缩略图全 403。所以按名字白名单（不是黑名单 —— 将来冒出个 `.env`
- * 不该因为没人想到就漏出去）。
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { safeResolveRead } from './safe-path.js';
-
-const DOT_OK = new Set(['.thumbnails', '.meta']);
-
-/**
- * 这个绝对路径可不可以服出去：不越界、且路径里没有非白名单的点目录。
- *
- * 导出它是因为**改名转发**那条路要用同一个判据（`api/assets.js` 里原来自己又抄了
- * 一遍 DOT_OK 和越界检查）。判据抄第二遍就是等着哪天改一处漏一处 ——
- * 收成一份，两边都 import。
- */
-export function isServablePath(sharedRoot, absPath) {
-  if (absPath !== sharedRoot && !absPath.startsWith(sharedRoot + path.sep)) return false;
-  const rel = path.relative(sharedRoot, absPath).split(path.sep);
-  return !rel.some(seg => seg.startsWith('.') && !DOT_OK.has(seg));
-}
-
-/**
- * @param {string} sharedRootRaw 项目工作区根
- * @param {string} rawSub 路由里的 *subPath（可能是数组段拼起来的）
- * @returns {Promise<{ok:true, sharedRoot:string, absPath:string, subPath:string}
- *   | {ok:false, status:number, error:string}>}
- */
-export async function resolveArtifactFile(sharedRootRaw, rawSub) {
-  let subPath = Array.isArray(rawSub) ? rawSub.join('/') : (rawSub || '');
-  if (!subPath) return { ok: false, status: 400, error: 'file path required' };
-
-  const sharedRoot = path.resolve(sharedRootRaw);
-
-  // 兼容旧形态：`tasks/<任务>/x` 是扁平化之前的路径，浏览器缓存里、旧 board.json 里、
-  // 用户收藏的链接里都还有。剥掉前两段就是现在的位置。
-  // ⚠️ **但不能无条件剥**（2026-08-18 审查抓到）：扁平化之后 agent 完全可以在工作区里
-  // 真建一个叫 `tasks/` 的目录（它就是个普通名字），那时候剥掉前两段会把**磁盘上真实
-  // 存在的文件**变成 404。所以先看原路径在不在，在就别动它。
-  const asIs = path.resolve(sharedRoot, subPath);
-  const insideAsIs = asIs === sharedRoot || asIs.startsWith(sharedRoot + path.sep);
-  if (/^tasks\/[^/]+\//.test(subPath)) {
-    let existsAsIs = false;
-    if (insideAsIs) {
-      try { await fs.stat(asIs); existsAsIs = true; } catch { /* 不在 */ }
-    }
-    if (!existsAsIs) subPath = subPath.replace(/^tasks\/[^/]+\//, '');
-  }
-
-  // ⛔ **纯词法的 `path.resolve` 挡不住软链**。真攻过（2026-08-18）：在工作区里
-  // `ln -s /path/to/.env x.html`，`GET artifact-file/x.html` 回 **200 且字节数与
-  // .env 一字不差**。而这条路由今天更热了（感知通道走它、常驻浏览器的 cookie jar
-  // 也住在工作区里），并且**它跑在 server 主进程、沙盒管不着**。
-  //
-  // 仓库里早就有正确实现 `safe-path.js` 的 `safeResolveRead`（realpath 复核，
-  // ENOENT 不算越界）。照那条教训：**去掉第二份判据而不是添第三份**
-  // （[[feedback-copied-guard-shape]]：抄守卫要抄正确性不是形状 —— 08-17 同一天
-  // 栽两次，第二次就是抄了调用形状没抄 realpath 复核）。
-  const absPath = await safeResolveRead(sharedRoot, subPath);
-  if (!absPath) {
-    return { ok: false, status: 403, error: 'path escapes workspace (symlinks are resolved before the check)' };
-  }
-  if (!isServablePath(sharedRoot, absPath)) {
-    return { ok: false, status: 403, error: 'not a servable path' };
-  }
-  return { ok: true, sharedRoot, absPath, subPath };
-}
+/**
+ * server/lib/artifact-file-path.js — artifact-file 的路径判据（2026-08-18 抽出）
+ *
+ * 抽出来的直接原因是行数棘轮，但抽对了：这几行是**安全判据**，而且它有一条已知的
+ * 错（见下面 `tasks/` 那段），judge 类的东西住在路由里没法单测。
+ *
+ * 可服务根 = 整个项目工作区（产物就住在这儿），但挡掉基础设施：`.claude/`（含
+ * settings.json 和整份 SDK 转录）、`.nd/`（会话私档）、`.git/`。扁平化之前这三样
+ * 都在可服务根之外、是目录结构在替我们把门；现在它们跟产物同级，必须显式拦 ——
+ * 否则 `artifact-file/.claude/settings.json` 是一个能公开读到配置的 URL。
+ *
+ * 点开头**一刀切拒是错的**：缩略图住在 `assets/generated/.thumbnails/`，一刀切下去
+ * 产物墙上所有缩略图全 403。所以按名字白名单（不是黑名单 —— 将来冒出个 `.env`
+ * 不该因为没人想到就漏出去）。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { safeResolveRead } from './safe-path.js';
+
+const DOT_OK = new Set(['.thumbnails', '.meta']);
+
+/**
+ * 这个绝对路径可不可以服出去：不越界、且路径里没有非白名单的点目录。
+ *
+ * 导出它是因为**改名转发**那条路要用同一个判据（`api/assets.js` 里原来自己又抄了
+ * 一遍 DOT_OK 和越界检查）。判据抄第二遍就是等着哪天改一处漏一处 ——
+ * 收成一份，两边都 import。
+ */
+export function isServablePath(sharedRoot, absPath) {
+  if (absPath !== sharedRoot && !absPath.startsWith(sharedRoot + path.sep)) return false;
+  const rel = path.relative(sharedRoot, absPath).split(path.sep);
+  return !rel.some(seg => seg.startsWith('.') && !DOT_OK.has(seg));
+}
+
+/**
+ * @param {string} sharedRootRaw 项目工作区根
+ * @param {string} rawSub 路由里的 *subPath（可能是数组段拼起来的）
+ * @returns {Promise<{ok:true, sharedRoot:string, absPath:string, subPath:string}
+ *   | {ok:false, status:number, error:string}>}
+ */
+export async function resolveArtifactFile(sharedRootRaw, rawSub) {
+  let subPath = Array.isArray(rawSub) ? rawSub.join('/') : (rawSub || '');
+  if (!subPath) return { ok: false, status: 400, error: 'file path required' };
+
+  const sharedRoot = path.resolve(sharedRootRaw);
+
+  // 兼容旧形态：`tasks/<任务>/x` 是扁平化之前的路径，浏览器缓存里、旧 board.json 里、
+  // 用户收藏的链接里都还有。剥掉前两段就是现在的位置。
+  // ⚠️ **但不能无条件剥**（2026-08-18 审查抓到）：扁平化之后 agent 完全可以在工作区里
+  // 真建一个叫 `tasks/` 的目录（它就是个普通名字），那时候剥掉前两段会把**磁盘上真实
+  // 存在的文件**变成 404。所以先看原路径在不在，在就别动它。
+  const asIs = path.resolve(sharedRoot, subPath);
+  const insideAsIs = asIs === sharedRoot || asIs.startsWith(sharedRoot + path.sep);
+  if (/^tasks\/[^/]+\//.test(subPath)) {
+    let existsAsIs = false;
+    if (insideAsIs) {
+      try { await fs.stat(asIs); existsAsIs = true; } catch { /* 不在 */ }
+    }
+    if (!existsAsIs) subPath = subPath.replace(/^tasks\/[^/]+\//, '');
+  }
+
+  // ⛔ **纯词法的 `path.resolve` 挡不住软链**。真攻过（2026-08-18）：在工作区里
+  // `ln -s /path/to/.env x.html`，`GET artifact-file/x.html` 回 **200 且字节数与
+  // .env 一字不差**。而这条路由今天更热了（感知通道走它、常驻浏览器的 cookie jar
+  // 也住在工作区里），并且**它跑在 server 主进程、沙盒管不着**。
+  //
+  // 仓库里早就有正确实现 `safe-path.js` 的 `safeResolveRead`（realpath 复核，
+  // ENOENT 不算越界）。照那条教训：**去掉第二份判据而不是添第三份**
+  // （[[feedback-copied-guard-shape]]：抄守卫要抄正确性不是形状 —— 08-17 同一天
+  // 栽两次，第二次就是抄了调用形状没抄 realpath 复核）。
+  const absPath = await safeResolveRead(sharedRoot, subPath);
+  if (!absPath) {
+    return { ok: false, status: 403, error: 'path escapes workspace (symlinks are resolved before the check)' };
+  }
+  if (!isServablePath(sharedRoot, absPath)) {
+    return { ok: false, status: 403, error: 'not a servable path' };
+  }
+  return { ok: true, sharedRoot, absPath, subPath };
+}