@xiaobuyu/nodesign 0.0.1

package/server/lib/region-shot.js

@@ -0,0 +1,135 @@
+/**
+ * lib/region-shot.js —— 把用户在预览上圈的那一块截下来。
+ *
+ * 为什么在服务端截而不是前端：产物是 iframe 里的**真实网页**，前端要把它变成
+ * 位图只能靠 html2canvas 那类重写渲染器的库 —— 那玩意儿在有 3D、滤镜、
+ * 自定义字体、伪元素的页面上出来的东西跟屏幕上不是一回事，而这张图恰恰是要
+ * 给 agent 当"眼见为实"的证据用的。chromium 真跑一遍才是它自己的样子，
+ * 而且这台机器上封面和 screenshot_canvas 早就是这么干的（lib/cover.js）。
+ *
+ * 取景：以圈为中心带一圈余量。只截圈内的话 agent 拿到一块没有上下文的碎片，
+ * 分不清"这是页面哪儿"；余量给到它周围一点参照。
+ */
+
+import path from 'node:path';
+import { openArtifactPage, launchPerceptionBrowser, degradedNote } from '../engine/mcp/tools/helpers/perception-page.js';
+import fs from 'node:fs/promises';
+
+/** 圈外多留这么多像素当上下文 */
+export const PADDING = 32;
+
+/** 出图长边上限，跟 screenshot 工具同口径（API 侧本来就会缩到这个规格） */
+export const OUT_LONG_EDGE = 1200;
+
+/** 截图串行：一台 1 核机器上同时开两个 chromium 会双双卡住 */
+let chain = Promise.resolve();
+function serialize(fn) {
+  const next = chain.then(fn, fn);
+  chain = next.catch(() => {});
+  return next;
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.absPath   产物页面的绝对路径
+ * @param {{x,y,w,h}} p.region 页面坐标（CSS px，含滚动量）
+ * @param {{width,height}} p.viewport 用户当时的取景宽高
+ * @param {string} [p.projectId]      有它就走 http（与用户预览同源）
+ * @param {string} [p.workspaceRoot]  同上，两个都给才走 http
+ * @returns {Promise<{ buffer: Buffer, clip: {x,y,width,height}, degraded: string|null }>}
+ */
+export async function renderRegionShot({ absPath, region, viewport, projectId, workspaceRoot }) {
+  return serialize(async () => {
+    let browser;
+    try {
+      browser = await launchPerceptionBrowser();
+      // 圈选截的是**用户圈的那一块**，所以更要跟用户看到的同源：file:// 下
+      // fetch 回来的内容不会出现在图里，agent 会以为用户圈了一块空白。
+      const opened = await openArtifactPage(browser, {
+        projectId, workspaceRoot, absPath, viewport, deviceScaleFactor: 1, timeout: 20_000,
+      });
+      const ctx = opened.context;
+      const page = opened.page;
+      await opened.goto();
+      // 字体加载完再截（CJK 子集是 lazy 的，不显式 load 会截到 fallback 字形）
+      await page.evaluate(async () => {
+        document.body.offsetHeight;
+        await Promise.all(Array.from(document.fonts).map(f => f.load().catch(() => {})));
+        await document.fonts.ready;
+        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+      }).catch(() => { /* 页面自己抛错也照截 */ });
+      // deck 的 standalone-fit 会在真实 viewport 下再缩一次，抹掉（同 cover.js）
+      await page.addStyleTag({ content: `
+        body { margin: 0 !important; padding: 0 !important; }
+        body.__nd-fit-active > .__nd-deck-wrap > .__nd-page-frame {
+          width: ${viewport.width}px !important; height: ${viewport.height}px !important;
+          display: block !important; overflow: visible !important;
+        }
+        body.__nd-fit-active section[data-page] { transform: none !important; }
+      ` }).catch(() => {});
+      await page.waitForTimeout(500);
+
+      const want = {
+        x: Math.max(0, region.x - PADDING),
+        y: Math.max(0, region.y - PADDING),
+        w: region.w + PADDING * 2,
+        h: region.h + PADDING * 2,
+      };
+
+      // 滚到目标位置再按视口坐标裁。**滚动会被文档末尾夹住**，所以要把真实
+      // 落点读回来算裁剪框，不然页尾附近截出来的是错位的一块。
+      const scroll = await page.evaluate(([x, y]) => {
+        window.scrollTo(x, y);
+        const e = document.scrollingElement || document.documentElement;
+        return [e.scrollLeft, e.scrollTop];
+      }, [want.x, want.y]);
+
+      const clip = {
+        x: Math.max(0, want.x - scroll[0]),
+        y: Math.max(0, want.y - scroll[1]),
+        width: Math.min(want.w, viewport.width),
+        height: Math.min(want.h, viewport.height),
+      };
+      clip.width = Math.max(1, Math.min(clip.width, viewport.width - clip.x));
+      clip.height = Math.max(1, Math.min(clip.height, viewport.height - clip.y));
+
+      // ⚠️ 滚完要**等一拍**再截。上面那个 500ms 花在滚动**之前**，滚完立刻截 →
+      // 视口里新进来的懒加载图（`loading=lazy` / IntersectionObserver）还没解码，
+      // 图里是空的。而 `get_pending_changes` 把这张图当作"用户所见的 ground truth"
+      // 交给 agent —— 空白处会被当成"用户圈了一块空白"。
+      await page.evaluate(async () => {
+        // 给 IO 回调一次机会，再等两帧确保解码后的图上了屏
+        await new Promise(r => setTimeout(r, 250));
+        await Promise.all([...document.images].filter(i => !i.complete)
+          .map(i => new Promise((res) => { i.addEventListener('load', res, { once: true });
+            i.addEventListener('error', res, { once: true }); setTimeout(res, 1200); })));
+        await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+      }).catch(() => { /* 页面自己抛错也照截 */ });
+
+      const png = await page.screenshot({ type: 'png', clip });
+      await ctx.close();
+
+      const { default: sharp } = await import('sharp');
+      const buffer = await sharp(png)
+        .resize({ width: OUT_LONG_EDGE, height: OUT_LONG_EDGE, fit: 'inside', withoutEnlargement: true })
+        .webp({ quality: 82 })
+        .toBuffer();
+      // note 非空 = 没走成 http。圈选截图尤其在意这个：file:// 下 fetch 回来的
+      // 内容不会出现在图里，而这张图是被当"ground truth"用的
+      return { buffer, clip, degraded: degradedNote(opened) };
+    } finally {
+      await browser?.close().catch(() => {});
+    }
+  });
+}
+
+/** 圈选截图在会话工作区里的落点（agent 按这个相对路径找得到） */
+export const SHOT_DIR = 'region-shots';
+
+export async function saveRegionShot(sessionRoot, id, buffer) {
+  const dir = path.join(sessionRoot, SHOT_DIR);
+  await fs.mkdir(dir, { recursive: true });
+  const rel = `${SHOT_DIR}/${id}.webp`;
+  await fs.writeFile(path.join(sessionRoot, rel), buffer);
+  return rel;
+}

package/server/lib/safe-path.js

@@ -0,0 +1,73 @@
+/**
+ * lib/safe-path.js — 工作区内路径的越界检查。
+ *
+ * ⚠️ **词法检查不够。** `path.resolve` + `path.relative` 挡得住 `../..`，
+ * 挡不住工作区里一个**指向外面的软链** —— 那条路径逐字看都在工作区内，
+ * 解引用之后在 `/etc` 或者 `.env` 上。
+ *
+ * 这个洞在这个仓库里已经出现过两次形状相同的实例（导出收集器、docx 页图路由），
+ * 第二次是照着第一次的**调用形状**抄的、没抄它的**正确性**。所以判据收成一份：
+ * 谁要在工作区里按用户给的相对路径开文件，就 import 这里，别再各写一遍。
+ *
+ * 读和写的判据不一样，分两个函数：
+ *   - 读：目标必须存在，realpath 之后仍在工作区内
+ *   - 写：目标可能还不存在（正要创建），所以查**父目录**的 realpath；
+ *     另外目标自己若已经是软链，一律拒 —— 顺着它写等于把别人的文件覆盖掉
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+/** 词法层：拼出绝对路径并确认字面上没跑出去。跑出去返回 null */
+function lexical(rootAbs, rel) {
+  const abs = path.resolve(rootAbs, String(rel || ''));
+  const within = path.relative(rootAbs, abs);
+  if (within.startsWith('..') || path.isAbsolute(within)) return null;
+  return abs;
+}
+
+/**
+ * 读用：解析一个工作区内的相对路径。
+ * @returns {Promise<string|null>} 绝对路径；越界（含软链穿透）返回 null
+ *   目标不存在**不算越界** —— 让调用方自己去 stat 报 404，这里只管边界
+ */
+export async function safeResolveRead(workspaceRoot, rel) {
+  const abs = lexical(path.resolve(workspaceRoot), rel);
+  if (!abs) return null;
+  try {
+    const realRoot = await fs.realpath(workspaceRoot);
+    const real = await fs.realpath(abs);
+    const rw = path.relative(realRoot, real);
+    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
+  } catch (err) {
+    // ENOENT：文件还没写出来，边界上没问题，留给调用方 stat
+    if (err?.code !== 'ENOENT') return null;
+  }
+  return abs;
+}
+
+/**
+ * 写用：解析一个工作区内的写入目标。
+ * @returns {Promise<string|null>} 绝对路径；越界 / 目标是软链 返回 null
+ */
+export async function safeResolveWrite(workspaceRoot, rel) {
+  const abs = lexical(path.resolve(workspaceRoot), rel);
+  if (!abs) return null;
+  try {
+    const realRoot = await fs.realpath(workspaceRoot);
+    // 目标本身若已存在且是软链 → 拒。顺着它写会覆盖软链指向的那个文件，
+    // 而那个文件可以在工作区外（lstat 不解引用，这是判据的关键）
+    try {
+      if ((await fs.lstat(abs)).isSymbolicLink()) return null;
+    } catch (err) {
+      if (err?.code !== 'ENOENT') return null;   // 目标还不存在是正常的
+    }
+    // 父目录必须真的在工作区内（父目录是软链的话，新建的文件会落到外面）
+    const realParent = await fs.realpath(path.dirname(abs));
+    const rw = path.relative(realRoot, realParent);
+    if (rw.startsWith('..') || path.isAbsolute(rw)) return null;
+  } catch {
+    return null;   // 父目录都解析不了，不给写
+  }
+  return abs;
+}

package/server/lib/sdk-session.js

@@ -0,0 +1,33 @@
+/**
+ * server/lib/sdk-session.js — SDK session API 调用 helper
+ *
+ * SDK 的 listSessions / getSessionMessages / forkSession 等同步 API 读
+ * `process.env.CLAUDE_CONFIG_DIR` 决定从哪找 JSONL（probe 验证过：probe-listsessions.mjs）。
+ * 我们 S1 把 CLAUDE_CONFIG_DIR per-project 设到 <workspace>/.claude/，
+ * 但那是 query() spawn binary 时通过 env option 传的——server 进程自己的
+ * process.env.CLAUDE_CONFIG_DIR 默认是空。
+ *
+ * 多 project 并发调 SDK session API 时 process.env mutation 会互相覆盖，
+ * 所以串行化（按单一 key 'sdk-config' mutex）。读操作很快（<10ms 级别），
+ * 串行不影响并发性能。
+ *
+ * 用法：
+ *   const sessions = await withConfigDir(wsClaudeDir, () =>
+ *     listSessions({ dir: wsRoot })
+ *   );
+ */
+
+import { mutex } from 'async-mutex-lite';
+
+export async function withConfigDir(configDir, fn) {
+  return mutex('sdk-config', async () => {
+    const prev = process.env.CLAUDE_CONFIG_DIR;
+    try {
+      process.env.CLAUDE_CONFIG_DIR = configDir;
+      return await fn();
+    } finally {
+      if (prev === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+      else process.env.CLAUDE_CONFIG_DIR = prev;
+    }
+  });
+}

package/server/lib/showcase-store.js

@@ -0,0 +1,92 @@
+/**
+ * server/lib/showcase-store.js — 个人作品橱窗（2026-07-30）
+ *
+ * 一条 showcase = 一件做完的作品 + 它沉淀出来的 skill。
+ * 跟"模板市场"的区别：模板是别人替你预设风格，橱窗是**你自己探索出来的结论**被
+ * 固化下来——第一次仍然是从问题长出骨架，第二次开始你有资格复用自己的结论。
+ *
+ * 归属：user_id 必填，只有本人（和 admin）看得到自己的橱窗。将来做跨用户市场时
+ * 再加 published 字段和审核，不在这一版（SKILL.md 整段进 agent 上下文，
+ * 陌生人的 skill 等于让人往你会话里写指令，得先有审核范围才能开）。
+ *
+ * artifact_rel 存 'tasks/<任务>/<入口>'，封面走 lib/cover.js 现截现缓存。
+ */
+
+import db from '../engine/runs/store.js';
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS showcase (
+    id            TEXT PRIMARY KEY,
+    user_id       TEXT NOT NULL,
+    project_id    TEXT,
+    task_id       TEXT,
+    artifact_rel  TEXT,
+    skill_name    TEXT,
+    title         TEXT NOT NULL,
+    note          TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_showcase_user_created ON showcase(user_id, created_at DESC);
+`);
+
+function newId() {
+  return `sc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+
+function rowToEntry(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    userId: row.user_id,
+    projectId: row.project_id,
+    taskId: row.task_id,
+    artifactRel: row.artifact_rel,
+    skillName: row.skill_name,
+    title: row.title,
+    note: row.note,
+    createdAt: row.created_at,
+  };
+}
+
+/** 同一件产物只留一条（重复固化就是更新，不是堆一堆重复卡片） */
+export function upsertEntry({ userId, projectId, taskId, artifactRel, skillName, title, note }) {
+  if (!userId) throw new Error('userId required');
+  const existing = artifactRel
+    ? db.prepare('SELECT * FROM showcase WHERE user_id = ? AND project_id IS ? AND artifact_rel IS ?')
+      .get(userId, projectId ?? null, artifactRel)
+    : null;
+  if (existing) {
+    db.prepare(`UPDATE showcase
+                SET task_id = ?, skill_name = ?, title = ?, note = ?, created_at = datetime('now')
+                WHERE id = ?`)
+      .run(taskId ?? null, skillName ?? null, title, note ?? null, existing.id);
+    return rowToEntry(db.prepare('SELECT * FROM showcase WHERE id = ?').get(existing.id));
+  }
+  const id = newId();
+  db.prepare(`INSERT INTO showcase (id, user_id, project_id, task_id, artifact_rel, skill_name, title, note)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+    .run(id, userId, projectId ?? null, taskId ?? null, artifactRel ?? null,
+      skillName ?? null, title, note ?? null);
+  return rowToEntry(db.prepare('SELECT * FROM showcase WHERE id = ?').get(id));
+}
+
+export function listEntries(userId) {
+  if (!userId) return [];
+  return db.prepare('SELECT * FROM showcase WHERE user_id = ? ORDER BY created_at DESC')
+    .all(userId).map(rowToEntry);
+}
+
+export function getEntry(id) {
+  return rowToEntry(db.prepare('SELECT * FROM showcase WHERE id = ?').get(id));
+}
+
+export function removeEntry(id, userId) {
+  const info = db.prepare('DELETE FROM showcase WHERE id = ? AND user_id = ?').run(id, userId);
+  return info.changes > 0;
+}
+
+/** 项目删除时连带清（作品没了，卡片留着只会点出 404） */
+export function removeEntriesForProject(projectId) {
+  db.prepare('DELETE FROM showcase WHERE project_id = ?').run(projectId);
+}