@xiaobuyu/nodesign 0.0.1

package/README.md

@@ -0,0 +1,140 @@
+# NoDesign
+
+面向独立创作者的 agent 创作工作台。一张无限画布就是你的桌面，说一句想做什么，
+agent 在真实文件上做出网站、演示稿、图像和视频，过程实时演在画布上；你直接在
+产物上改字、圈选、留评论、拖拽整理，agent 接着你的动作继续做。
+
+线上实例（内测，邀请制）：`nodesign.xiaobuyu.trade`
+
+## 它长什么样
+
+- **画布即桌面**：项目就是一张空间画布，画布上的一切与磁盘一一对应。文件夹是
+  真目录，卡片 id 就是文件路径，拖一张卡进文件夹等于真的 `mv`。
+- **产物即文件**：形态由文件证据认定，不用声明。写出 `<名字>.html` 是一份
+  deck；建一个带 `index.html` 的文件夹是一个站点，配响应式取景的显示器窗；
+  普通文件各自成卡，图片、视频、Office 文档、Markdown 都读得开。
+- **agent 是在场的**：一枚铅笔定格风格的 Claude 星芒住在画布上。干活时贴着
+  它正在写的那张卡，代码直播框跟在身边；空闲时停在你的视野里，写一句刚才
+  干了什么。点它可以直接搭话。
+- **关系是一等公民**：六类关系线（改自、批注、接着、取材、对照、自定义
+  label）。你画的线 agent 读得到，agent 也会在收尾时主动把产物之间的关系画
+  出来；HTML 里真实引用的素材由服务端自动对账成取材边。版面排布按关系走：
+  相关的凑近、对照的成行、现役主角放大。
+
+## agent 能做什么
+
+| 能力 | 说明 |
+|---|---|
+| 建站 / 做 deck | 手写或构建型站点（Astro、11ty 均可，产物根自动认定）；deck 固定比例分页 |
+| 看得见 | 截图自检（回传 console 错误与加载失败资源）、DOM 查询、真机移动端取景 |
+| 画布语言 | `read_board` 看座次、`arrange_on_board` 语义摆位、`create_on_board` 手写便签、`organize_board` 归纳收纳、`relate_on_board` 画关系线 |
+| 图像 | `generate_image` 生图、`remove_background` 抠图；可接自部署 GPU 产线（多模型生图、文生视频，按账号开通） |
+| 发布 | `publish_site` 一键发布到四级子域名（Cloudflare Pages）；下线即回收 |
+| 导出 | PDF / PPTX / 整站 zip / 工程交付包，浏览器直接下载 |
+| 记忆 | 项目级风格档案与用户偏好档，跨会话不忘；共享便利贴层与决策记录 |
+
+用户侧的直接操作全部会回到 agent 手里：双击改字写回源文件，元素评论与圈选
+截图进 pending buffer 下一轮自动带上，拖拽移动、样式调整、删除都以结构化意图
+落地。
+
+## 架构
+
+```
+web/     React + Vite 前端。无限画布为自研：相机、命中、形态能力表、关系
+         排布、在场归约全部是带单测的纯函数（web/src/lib，30+ 模块）。
+server/  Node ESM 服务端。Claude Agent SDK 驱动 agent 会话（每会话独立
+         cwd 指向项目工作区）；in-process MCP 提供 31 件业务工具；hooks
+         做注入与守卫；WS 采用快照加尾随协议，断线重连不丢流。
+```
+
+几个关键设计：
+
+- **形态注册表**（`server/lib/kinds/`）：一种产物形态一个条目，寻址、预览、
+  导出、发布都从注册表读。加新形态不改散落的 if。
+- **单一真相源**：会话指针在服务端，多标签页不分叉；搬家语义一份实现，用户
+  拖拽与 agent 工具共用；改名是一等动词，三层传播（画布身份、关系线端点、
+  转发表）保证 agent 背着画布 `mv` 之后版面不散。
+- **事件三管线**：一条 WS 进来分流为舞台旁路（画布演出）、聊天流折叠、控制
+  帧。分流名单与过期判据抽成纯函数并有钉子测试。
+- **多用户**：邀请码注册、按用户隔离、用量计费闸门、内容外审档位。
+
+## 本地运行（单机版）
+
+同一份代码有两种形态：线上多用户站（hosted）和本地单机版（local，`NODESIGN_PROFILE=local`）。
+本地版默认单租户：没有登录墙、没有账号和额度，服务只绑 `127.0.0.1`，数据都在 `~/.nodesign/`
+（`.env` 钥匙 / `config.json` 模型插槽 / 数据库 / 项目 / 缓存）。
+
+一条命令（要先装好 Node ≥ 20）：
+
+```bash
+npx @xiaobuyu/nodesign       # 首次会下载约 470MB（含 Claude CLI 本体），起来后自动开浏览器
+npx @xiaobuyu/nodesign login # 用 Claude 订阅的话登录一次（不用另装 claude CLI）；用 API Key 的话在设置页填
+# 或者装成全局命令：npm i -g @xiaobuyu/nodesign，之后直接 nodesign / nodesign login
+```
+
+常用参数：`--port N`（默认 4001，被占会自动往上找）、`--data-dir DIR`、`--no-open`。
+
+从仓库跑（开发）：
+
+```bash
+npm install && cd web && npm install && cd ..
+npm run build:web        # 前端构建产物由 Node 直接托管
+npm run local            # = node bin/nodesign.js --no-open
+```
+
+第一次起来后打开右上角齿轮（`/settings`）：
+
+- **本机能力**：git / Chromium(playwright) / LibreOffice / poppler / ffmpeg / rembg 等探测结果与装法。
+  截图自检要 `npx playwright install chromium`；Word 形态要装 LibreOffice。缺的能力对应的工具
+  会在 agent 面前标「不可用 + 装法」，不会静默失败
+- **模型**：「Claude 官方」（API Key 或 `nodesign login` 的订阅登录态）与「自定义接入」（DeepSeek / OpenAI /
+  智谱 / 通义 / OpenRouter / 中转站 / 本机 Ollama…，选服务商预设填钥匙和模型名即可）两张并列的卡；
+  没配任何一种时模型选择器是空的
+- **其他钥匙与开关**：四家搜索 / 生图通道 / Cloudflare 发布 / 沙盒与权限模式，写进
+  `~/.nodesign/.env`，钥匙类保存即生效
+- 模型插槽细节：自己的上游（Anthropic 或 OpenAI-chat 协议的任何端点）+ 模型行，保存后重启生效；
+  每行可「体检」（非流式 / 流式 / 工具调用 / 看图 / count_tokens 五项红绿）
+
+Claude 本身二选一：本机 `claude login` 过（订阅），什么都不用填；或在钥匙页填 `ANTHROPIC_API_KEY`。
+
+Windows 没有沙盒（bwrap/sandbox-exec），本地版默认不开沙盒，靠 CLI 自己的权限模式；
+`NODESIGN_SANDBOX=on` 只在 Linux/macOS 有效。
+
+## 开发
+
+```bash
+npm install && cd web && npm install && cd ..
+
+# 服务端（读 .env；需要 Claude 订阅登录态或 API key）
+npm run dev
+
+# 前端
+cd web && npm run dev
+```
+
+测试与守门：
+
+```bash
+npm test               # server 单测 + web 单测（含 lint 型测试）
+npm run test:server    # 仅服务端
+node web/src/components/canvas/_hook-order-check.mjs   # TDZ 依赖顺序体检
+```
+
+lint 型测试是这个仓库的护栏（没有 CI，vitest 就是部署链的闸门）：
+
+- `loc-ratchet.lint`：源文件不超过 600 行，存量超标文件按现状冻结上限，只降不升
+- `legacy-shape.lint`：旧任务模型的路径形状不许回到代码里
+- `path-compose.lint`：路径拼接必须走统一入口
+- parity 系列：前端消费的事件形状必须在服务端源码里逐字存在，reducer 消费的
+  事件必须在转发名单里
+
+前端上线用 `web/scripts/deploy.sh`：构建到旁路目录后原子换入，旧分片保留，
+开着的页面不断链。服务端改动记得重启进程，Node 不热重载。
+
+真渲染验证有两条通道：`web/scripts/inspect.mjs`（拦截 API 喂固定数据，纯 UI
+回归）与 `web/scripts/shot-live.mjs`（登录真服务端截图加探针，查真问题用）。
+
+## 现状
+
+个人项目，内测运行中。近期完成画布与 agent 交互的整体重做：扁平桌面模型、
+连线范式、铅笔精灵、agent 摆位与归纳工具、根站治理。方向与记录见提交历史。

package/bin/nodesign.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * bin/nodesign.js — 本地分发版入口（`npx nodesign` / `nodesign`）。
+ *
+ * 它是一个很薄的 supervisor：把 profile 钉成 local、把命令行参数翻译成 env、拉起 server/index.js 子进程、
+ * health 通了开一次浏览器；子进程以 RESTART_EXIT_CODE（75，见 server/api/local.js）退出就重新拉起——
+ * 配置页「保存并重启」走的就是这条路。所有真正的决策都在 server/runtime/profile.js，这里不复制一份。
+ *
+ *   nodesign                      # 数据在 ~/.nodesign，http://127.0.0.1:4001
+ *   nodesign --port 5000          # 换端口
+ *   nodesign --data-dir ./mydata  # 换数据目录（.env / config.json / 数据库 / 项目都在里面）
+ *   nodesign --no-open            # 不自动开浏览器
+ *   nodesign login                # 用 Claude 订阅：登录一次（转发给 SDK 自带的 claude auth login）
+ *
+ * 钥匙放 <数据目录>/.env：ANTHROPIC_API_KEY=...（或者本机 `claude login` 过，什么都不用填）；
+ * 自己的模型插槽放 <数据目录>/config.json（形状见 server/runtime/local-config.js）。
+ */
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RESTART_EXIT_CODE = 75;
+const serverEntry = path.join(path.dirname(fileURLToPath(import.meta.url)), '../server/index.js');
+
+const args = process.argv.slice(2);
+
+// 子命令：`nodesign login` / `logout` / `auth status` —— 转发给 SDK 自带的 Claude CLI（用户不用再全局装一份 claude）。
+// 配置目录与服务端同一个（server/runtime/platform.js 的 claudeConfigDir：NODESIGN_CONFIG_DIR 或 ~/.claude），
+// 登录态落在那里，服务端的 claudeAuthPresent() 才看得见。
+if (['login', 'logout', 'auth'].includes(args[0])) {
+  const sub = args[0] === 'auth' ? args.slice(1) : [args[0], ...args.slice(1)];
+  const code = await runBundledClaude(['auth', ...sub]);
+  process.exit(code);
+}
+
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--help' || a === '-h') { flags.help = true; continue; }
+  if (a === '--no-open') { flags.noOpen = true; continue; }
+  if (a === '--open') { flags.noOpen = false; continue; }
+  const m = /^--(port|data-dir|host)(?:=(.*))?$/.exec(a);
+  if (m) {
+    const v = m[2] !== undefined ? m[2] : args[++i];
+    if (v === undefined) { console.error(`--${m[1]} 需要一个值`); process.exit(2); }
+    flags[m[1]] = v;
+    continue;
+  }
+  console.error(`不认识的参数：${a}（--help 看用法）`);
+  process.exit(2);
+}
+
+if (flags.help) {
+  console.log(`用法：nodesign [--port N] [--data-dir DIR] [--host H] [--no-open]
+  --port N        监听端口（默认 4001；env PORT）
+  --data-dir DIR  数据目录：.env / config.json / 数据库 / 项目 / 缓存（默认 ~/.nodesign；env NODESIGN_DATA_DIR）
+  --host H        监听地址（默认 127.0.0.1；没有登录墙，别改成 0.0.0.0）
+  --no-open       启动后不自动打开浏览器
+  login / logout / auth status   Claude 订阅登录态（不用另装 claude CLI）
+钥匙：<数据目录>/.env 里写 ANTHROPIC_API_KEY=...；或本机已 \`claude login\` 则不用填。`);
+  process.exit(0);
+}
+
+const env = { ...process.env };
+env.NODESIGN_PROFILE = env.NODESIGN_PROFILE || 'local';
+if (flags.port) env.PORT = String(flags.port);
+if (flags['data-dir']) env.NODESIGN_DATA_DIR = flags['data-dir'];
+if (flags.host) env.NODESIGN_HOST = flags.host;
+
+const host = env.NODESIGN_HOST || '127.0.0.1';
+// 端口：用户指定了（--port / PORT）就用它，被占就报错退出；没指定则从 4001 往上找第一个空的
+// （4001 在别人机器上常有主——Cursor、QQ 都见过——让用户自己换端口不如自己让一步）
+const port = await pickPort(env.PORT ? Number(env.PORT) : null);
+env.PORT = String(port);
+const url = `http://${host}:${port}/`;
+
+async function pickPort(wanted) {
+  const free = (p) => new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once('error', () => resolve(false));
+    srv.listen(p, host, () => srv.close(() => resolve(true)));
+  });
+  if (wanted) {
+    if (await free(wanted)) return wanted;
+    console.error(`[nodesign] 端口 ${wanted} 已被占用（查占用：${process.platform === 'win32' ? `netstat -ano | findstr :${wanted}` : `lsof -i :${wanted}`}）`);
+    process.exit(1);
+  }
+  for (let p = 4001; p < 4001 + 50; p++) {
+    if (await free(p)) {
+      if (p !== 4001) console.log(`[nodesign] 4001 被占用，改用端口 ${p}`);
+      return p;
+    }
+  }
+  console.error('[nodesign] 4001～4050 全被占用，用 --port 指定一个');
+  process.exit(1);
+}
+let opened = false;
+let child = null;
+let stopping = false;
+
+/** SDK 平台包里的 claude 可执行：@anthropic-ai/claude-agent-sdk-<platform>-<arch>[-musl]/claude[.exe] */
+function bundledClaudePath() {
+  const require = createRequire(import.meta.url);
+  const musl = process.platform === 'linux' && (() => { try { return require('node:fs').readFileSync('/usr/bin/ldd', 'utf8').includes('musl'); } catch { return false; } })();
+  const pkg = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}${musl ? '-musl' : ''}`;
+  const dir = path.dirname(require.resolve(`${pkg}/package.json`));
+  return path.join(dir, process.platform === 'win32' ? 'claude.exe' : 'claude');
+}
+function runBundledClaude(cliArgs) {
+  return new Promise((resolve) => {
+    let bin;
+    try { bin = bundledClaudePath(); } catch (e) { console.error(`[nodesign] 找不到 SDK 自带的 claude 可执行：${e.message}`); resolve(1); return; }
+    const cfgDir = process.env.NODESIGN_CONFIG_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude');
+    const p = spawn(bin, cliArgs, { stdio: 'inherit', env: { ...process.env, CLAUDE_CONFIG_DIR: cfgDir } });
+    p.on('error', (e) => { console.error(`[nodesign] 起不来 claude：${e.message}`); resolve(1); });
+    p.on('exit', (c) => resolve(c ?? 1));
+  });
+}
+
+function start() {
+  child = spawn(process.execPath, [serverEntry], { env, stdio: 'inherit' });
+  child.on('exit', (code, signal) => {
+    child = null;
+    if (stopping) process.exit(code ?? 0);
+    if (code === RESTART_EXIT_CODE) {
+      console.log('[nodesign] 服务端请求重启，重新拉起…');
+      start();
+      return;
+    }
+    process.exit(code ?? (signal ? 1 : 0));
+  });
+  if (!opened && !flags.noOpen && env.NODESIGN_OPEN !== '0') waitHealthThenOpen();
+}
+
+// 等 /api/health 通了再开浏览器（开早了是一页「无法连接」）。只开一次：重启后页面自己会刷新
+function waitHealthThenOpen() {
+  const deadline = Date.now() + 20_000;
+  const tick = () => {
+    if (opened || !child) return;
+    const req = http.get(`${url}api/health`, (res) => {
+      res.resume();
+      if (res.statusCode === 200) { opened = true; openBrowser(url); return; }
+      retry();
+    });
+    req.on('error', retry);
+    req.setTimeout(1000, () => { req.destroy(); });
+  };
+  const retry = () => { if (Date.now() < deadline) setTimeout(tick, 300).unref(); };
+  tick();
+}
+
+function openBrowser(target) {
+  const cmd = process.platform === 'darwin' ? ['open', [target]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', target]]
+      : ['xdg-open', [target]];
+  try {
+    const p = spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true });
+    p.on('error', () => { console.log(`[nodesign] 打不开浏览器，请手动访问 ${target}`); });
+    p.unref();
+  } catch {
+    console.log(`[nodesign] 打不开浏览器，请手动访问 ${target}`);
+  }
+}
+
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => {
+    stopping = true;
+    if (child) child.kill(sig); else process.exit(0);
+  });
+}
+
+start();

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@xiaobuyu/nodesign",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "description": "NoDesign — 面向独立创作者的 agent 创作工作台（本地分发版：npx nodesign）",
+  "bin": {
+    "nodesign": "bin/nodesign.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "web/dist/",
+    "README.md",
+    "LICENSE",
+    "!server/**/*.test.js",
+    "!server/**/_probe-*",
+    "!server/**/_*-check.mjs",
+    "!server/**/_smoke.js",
+    "!server/server/",
+    "!server/db/",
+    "!server/node_modules/",
+    "!server/runs/",
+    "!server/skills/installed/",
+    "!server/lib/docx/lab/",
+    "!server/lib/ssrf-lab/",
+    "!server/scripts/",
+    "!web/dist/mock/"
+  ],
+  "scripts": {
+    "postinstall": "node server/ops/fix-sdk-musl.mjs",
+    "start": "node --env-file-if-exists=.env server/index.js",
+    "dev": "node --env-file-if-exists=.env --watch server/index.js",
+    "smoke:engine": "node --env-file-if-exists=.env server/engine/_smoke.js",
+    "smoke:agent": "node --env-file-if-exists=.env server/engine/agent/_smoke.js",
+    "test:server": "nice -n 15 vitest run -c vitest.server.config.js",
+    "test": "npm run test:server && cd web && nice -n 15 npx vitest run",
+    "local": "node bin/nodesign.js --no-open",
+    "build:web": "cd web && npx vite build",
+    "prepack": "npm run build:web"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.237",
+    "async-mutex-lite": "^1.0.0",
+    "better-sqlite3": "^12.8.0",
+    "cors": "^2.8.5",
+    "esbuild": "^0.28.0",
+    "express": "^5.1.0",
+    "fflate": "^0.8.3",
+    "jszip": "^3.10.1",
+    "mammoth": "^1.12.0",
+    "multer": "^2.1.1",
+    "partial-json": "^0.1.7",
+    "playwright": "^1.50.0",
+    "pptxgenjs": "^4.0.1",
+    "sharp": "^0.34.0",
+    "tailwindcss": "^3.4.19",
+    "ws": "^8.18.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.3.6"
+  },
+  "comments": {
+    "_intentionally_omitted": [
+      "@anthropic-ai/sdk — Phase 4 删了；agent SDK 已包 LLM 通信，server/ 生产代码 0 直连用法。回退见 git revert（同 commit 删了 _probe-*.js）",
+      "@larksuiteoapi/node-sdk — 飞书入口走小合 → 调 Nodesign HTTP API；本服务不直接连飞书",
+      "@modelcontextprotocol/sdk — MCP 是 dev/ 工作台的事；Nodesign 暴露的是 REST/SSE",
+      "bcryptjs / jsonwebtoken — 鉴权方案待组长确认（'已有平台'是什么），先不锁",
+      "react / vite — 前端在 Nodesign/web/（待建）；server 是纯后端"
+    ],
+    "_pending_decisions": [
+      "playwright vs puppeteer — playwright 更现代但带 chromium ~150MB，部署环境吃得消？",
+      "better-sqlite3 vs pg — SaaS 数据规模会涨，可能要切 PostgreSQL；MVP 先 SQLite 起步"
+    ]
+  },
+  "allowScripts": {
+    "better-sqlite3@12.9.0": true,
+    "esbuild@0.28.0": true,
+    "sharp@0.34.5": true
+  },
+  "devDependencies": {
+    "happy-dom": "^20.11.2",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xiaokebuyu/Nodesign.git"
+  },
+  "homepage": "https://github.com/Xiaokebuyu/Nodesign#readme",
+  "bugs": {
+    "url": "https://github.com/Xiaokebuyu/Nodesign/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agent",
+    "canvas",
+    "creative",
+    "claude",
+    "deepseek",
+    "local-first"
+  ],
+  "license": "AGPL-3.0-only"
+}

package/server/api/README.md

@@ -0,0 +1,45 @@
+# server/api/ — HTTP API 入口
+
+Nodesign 对外的公网 / 内网 HTTP 接口层。
+
+## 计划路由（待实现）
+
+```
+POST   /engine/runs                  启动一个 skill run
+       body: { skill, brief, style_reference?, tools?, options? }
+       → 201 { run_id, status, stream_url }
+
+GET    /engine/runs/:id              查 run 状态
+GET    /engine/runs/:id/stream       SSE 实时进度（text/thinking/tool_call/screenshot/done）
+GET    /engine/runs/:id/artifacts    列产物
+GET    /engine/runs/:id/artifacts/:filename   下载/打开（deck.html 直接可看）
+POST   /engine/runs/:id/cancel       取消
+
+POST   /style/extract                上传素材 → 提 style tokens
+       body: multipart (file) | { url }
+       → { task_id }
+GET    /style/tasks/:id              提取结果
+
+POST   /edit/sessions                启动 edit 会话（绑定一个 deck）
+POST   /edit/sessions/:id/messages   发指令
+GET    /edit/sessions/:id/stream     SSE
+```
+
+## 鉴权（待组长确认）
+
+7 个待对齐问题里有"已有平台具体指什么" → 决定鉴权方式：
+- 平台 SSO：复用平台的 token / cookie
+- 自建：JWT + bcrypt
+- 内部测试期：仅 `INTERNAL_API_TOKEN` Bearer
+
+外部 API 必加：rate limit、CORS、CSRF（如有 cookie 鉴权）。
+
+## 调用方
+
+- **Web 前端**（[Nodesign/web/](../../web/)，待建）—— 主入口
+- **小合**（[dev/server/bot/](../../../dev/server/bot/)）—— 内部 fn call，复用 `INTERNAL_API_TOKEN`
+- **第三方 / CLI**（远期）
+
+## 框架选择
+
+Express 5（与 dev/ 一致，复用度高）。如果未来 SSE 量大可换 Fastify。

package/server/api/_guard.js

@@ -0,0 +1,75 @@
+/**
+ * server/api/_guard.js — 项目路由统一守卫（2026-07-30 多用户内测）
+ *
+ * 老范式是每个 handler 开头两行 `validateProjectId` + `getProject`（4 个文件
+ * 各有局部 guard()、其余 ~40 处内联）。多用户后归属校验必须只有一个实现，
+ * 全部收敛到这里。
+ *
+ * 语义：项目不存在、或存在但不属于当前用户（admin 例外）→ 一律 404，
+ * 不区分两种情况 —— 别让外人靠状态码枚举 pid 空间。
+ *
+ * req.user 由 auth/middleware.js authGuard 挂（登录墙关闭时是匿名 admin，
+ * 单机开发行为不变）。
+ */
+
+import { validateProjectId, getProject } from '../projects/store.js';
+import { getRun } from '../engine/runs/store.js';
+import { getUserById } from '../auth/users-store.js';
+
+/**
+ * 模型资格按谁算：**项目 owner**（08-21 晚）。非 admin 只能进自己的项目（guardProject），
+ * 所以对他们 owner 就是自己；差别只在 admin 代看别人的项目 —— 那时选模型/默认模型/锁行
+ * 都得按 owner 的档位（auth/tier.js），否则 admin 选了订阅 Claude 行、session-loop 按 owner
+ * 断言 OAuth 资格时再打回 INIT_FAILED。owner 查不到时退回请求者（不放大权限：admin 本就全开）。
+ */
+export function modelUserFor(req, project) {
+  const ownerId = project?.ownerId;
+  if (!ownerId || ownerId === req.user?.id) return req.user;
+  return getUserById(ownerId) || req.user;
+}
+
+/**
+ * @returns {object|null} project；null 时响应已发出，caller 直接 return
+ */
+export function guardProject(req, res) {
+  try {
+    validateProjectId(req.params.pid);
+  } catch (err) {
+    res.status(400).json({ error: err.message || 'invalid projectId' });
+    return null;
+  }
+  const project = getProject(req.params.pid);
+  const user = req.user;
+  const allowed = project && (user?.role === 'admin' || (user && project.ownerId === user.id));
+  if (!allowed) {
+    res.status(404).json({ error: 'project not found' });
+    return null;
+  }
+  return project;
+}
+
+/** 归属判断（不发响应）—— WS upgrade 等非 express 场景用 */
+export function userOwnsProject(user, project) {
+  if (!project || !user) return false;
+  if (user.role === 'admin') return true;
+  // ⚠️ `project.ownerId === user.id` 在**两边都 undefined** 时是 true。今天不可达
+  // （每行都有 owner，bootstrapAuth 每次启动回填 NULL），但离"通配放行"只差一个
+  // 缺列或一个改了形状的调用方。归属判断上宁可写死。
+  return typeof user.id === 'string' && user.id !== ''
+    && typeof project.ownerId === 'string' && project.ownerId === user.id;
+}
+
+/**
+ * /:pid/runs/:runId/* 路由的第二道锁：runId 必须真属于这个 pid。
+ * cancel/rewind/answer 走的是全局内存 Map（key 只有 runId），没有这道校验
+ * 就是"拿自己的 pid + 别人的 runId"的跨租户控制通道。
+ * guardProject 通过之后调；不通过时已响应 404。
+ */
+export function guardRunInProject(req, res) {
+  const run = getRun(req.params.runId);
+  if (!run || run.projectId !== req.params.pid) {
+    res.status(404).json({ error: 'run not found' });
+    return null;
+  }
+  return run;
+}