@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/README.md

@@ -1,140 +1,190 @@
 # 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。
 
-用户侧的直接操作全部会回到 agent 手里：双击改字写回源文件，元素评论与圈选
-截图进 pending buffer 下一轮自动带上，拖拽移动、样式调整、删除都以结构化意图
-落地。
+告诉它你想做什么，它会在画布上创建网站、演示稿、文档、图片和视频。所有产物都会保存为真实文件，可以继续编辑、批注、下载和发布。
 
-## 架构
+![demo](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo.gif)
 
-```
-web/     React + Vite 前端。无限画布为自研：相机、命中、形态能力表、关系
-         排布、在场归约全部是带单测的纯函数（web/src/lib，30+ 模块）。
-server/  Node ESM 服务端。Claude Agent SDK 驱动 agent 会话（每会话独立
-         cwd 指向项目工作区）；in-process MCP 提供 31 件业务工具；hooks
-         做注入与守卫；WS 采用快照加尾随协议，断线重连不丢流。
+## 立即体验
+
+```bash
+npx @xiaobuyu/nodesign
 ```
 
-几个关键设计：
+需要 Node.js 20+，并配置至少一种模型接入方式：
 
-- **形态注册表**（`server/lib/kinds/`）：一种产物形态一个条目，寻址、预览、
-  导出、发布都从注册表读。加新形态不改散落的 if。
-- **单一真相源**：会话指针在服务端，多标签页不分叉；搬家语义一份实现，用户
-  拖拽与 agent 工具共用；改名是一等动词，三层传播（画布身份、关系线端点、
-  转发表）保证 agent 背着画布 `mv` 之后版面不散。
-- **事件三管线**：一条 WS 进来分流为舞台旁路（画布演出）、聊天流折叠、控制
-  帧。分流名单与过期判据抽成纯函数并有钉子测试。
-- **多用户**：邀请码注册、按用户隔离、用量计费闸门、内容外审档位。
+- Claude 订阅或 Anthropic API
+- OpenAI、DeepSeek、智谱、通义、OpenRouter
+- Ollama 或其他兼容 OpenAI API 格式的模型服务
 
-## 本地运行（单机版）
+NoDesign 本身不收取订阅费，也不对模型调用加价。项目文件和配置保存在本地。使用云端模型时，完成任务所需的上下文会发送给你配置的模型服务。使用本地模型（如 Ollama）时，所有数据都留在你的电脑上。
 
-同一份代码有两种形态：线上多用户站（hosted）和本地单机版（local，`NODESIGN_PROFILE=local`）。
-本地版默认单租户：没有登录墙、没有账号和额度，服务只绑 `127.0.0.1`，数据都在 `~/.nodesign/`
-（`.env` 钥匙 / `config.json` 模型插槽 / 数据库 / 项目 / 缓存）。
+暂时不想安装，也可以通过在线实例体验基础能力：[nodesign.xiaobuyu.trade](https://nodesign.xiaobuyu.trade)
 
-一条命令（要先装好 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`。
+三个典型场景：
 
-从仓库跑（开发）：
+- **做一个作品集页面**：把参考图和文字素材放到画布上，告诉 Agent 你要什么风格，检查桌面、平板和手机尺寸下的效果，配置后一键发布到公网。
+- **做一份演示稿**：把照片、文字和参考风格放到画布上，Agent 生成分页幻灯，你直接在上面批注修改，导出 PDF 或 PPTX。
+- **做一个内容项目**：网站、图片、视频和文档放在同一张画布上，由同一个 Agent 连续处理。Agent 可以在不同产物之间继续取材和修改。
 
-```bash
-npm install && cd web && npm install && cd ..
-npm run build:web        # 前端构建产物由 Node 直接托管
-npm run local            # = node bin/nodesign.js --no-open
-```
+### 产物类型
+
+| 产物 | 格式 | 能做什么 |
+|---|---|---|
+| 演示稿（幻灯、长图、海报） | `.html` | 16:9、9:16、4:3 等比例分页，导出 HTML、PDF、PPTX |
+| 站点（作品集、落地页、小应用） | 带 `index.html` 的文件夹 | 桌面、平板和手机尺寸预览，整站 zip 导出，配置 Cloudflare 后可一键发布 |
+| Word 文档 | `.docx` | 直接生成标准 OOXML，不是把 HTML 包装成 Word 文件。页图预览、翻页、下载原件 |
+| 图片 | 常见图片格式 | 生图、抠图 |
+| 视频 | 常见视频格式 | 视频导入、预览与转码 |
+
+这些文件不依赖 NoDesign 的私有格式，可以使用其他工具继续编辑和下载。
+
+使用 NoDesign 完成的实际项目：一个乐队的研究站、一份 15 页的西藏攻略幻灯配站点、一套像素风服务器宣传页、一份改了六版的简历 .docx。也有实验性项目，比如一个在页面上选择剧情、在聊天里生成内容的互动视觉小说。已发布的一个站点：[spica-mix.share.xiaobuyu.trade](https://spica-mix.share.xiaobuyu.trade)。
+
+## 它为什么不只是另一个 AI 聊天框
+
+### 画布就是工作区
+
+画布上的卡片对应真实文件，文件夹对应真实目录。移动、编辑和整理卡片，也会同步改变磁盘上的内容。
+
+![打开文件夹、把卡片拖进文件夹、在两张卡之间建立关系](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-desktop.gif)
+
+### Agent 始终在场
+
+Agent 会出现在它正在处理的内容旁边。你可以看到它正在编辑哪个文件，以及内容如何逐步生成，而不是只能等待聊天框返回最终结果。
+
+### 你的操作会成为下一轮上下文
+
+你可以直接修改文字、圈选区域、拖动元素，或者在不同产物之间建立「参考」「批注」「接着做」等关系。这些操作会被整理为后续任务的上下文。
+
+![圈选封面的一块区域写一句话，Agent 取到后直接修改](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-roundtrip.gif)
+
+### Agent 能检查自己的结果
+
+它可以获取不同屏幕尺寸下的页面截图、样式计算结果、控制台错误、字体加载状态和动效帧，并根据检查结果继续修改。做完之后它自己截图核对，改了两轮你还是不满意，它会请一个只读的评审子代理逐页检查。
+
+![站点在桌面、平板、手机尺寸下的预览](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-viewport.gif)
+
+### 记忆是可见、可编辑的
+
+项目决策、风格记录和个人偏好不会只藏在对话历史中。它们会以可见内容保留在工作区，也可以沉淀成可复用的 Skill。
+
+## 本地版与线上版
+
+| | 本地版 `npx @xiaobuyu/nodesign` | 线上版 [nodesign.xiaobuyu.trade](https://nodesign.xiaobuyu.trade) |
+|---|---|---|
+| 模型 | 你自己配置的（Claude 订阅、API Key 或兼容 OpenAI API 格式的服务） | 免费模型，每日额度 |
+| 数据 | 保存在 `~/.nodesign/`，服务仅监听 `127.0.0.1` | 服务端存储，按用户隔离 |
+| 账号 | 无需账号，打开即可使用 | 公开注册 |
+| 能力 | 全部。截图、Word、抠图、生图等按本机环境自动探测。站点发布需要配置 Cloudflare Pages | 截图、搜索、生图开放。站点发布和订阅模型暂不对外开放 |
+| 费用 | 无订阅，无抽成。模型费用由你配置的服务商收取 | 免费 |
 
-第一次起来后打开右上角齿轮（`/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 有效。
+- **模型**：两张并列的卡片。「Claude 官方」填 API Key 或通过 `nodesign login` 登录 Claude 订阅。「自定义接入」从服务商预设里选一个（DeepSeek、OpenAI、智谱、通义、OpenRouter、Ollama 等），填入接口地址和密钥。每个模型配置都可以运行连接测试，实际验证普通对话、流式输出、工具调用、图片理解和计数能力。没有配置任何模型时，模型选择器是空的。
+- **本机能力**：启动时自动探测 git、Chromium、LibreOffice、poppler、ffmpeg、rembg、生图、搜索、发布能力。缺少的会标出安装方法，对应工具会明确显示为不可用，并附上安装说明。
+- **其他设置**：搜索（四家任选一）、生图通道、Cloudflare 发布、沙盒与权限模式。
+- **状态**：数据目录、配置文件路径、重启。
+
+配置文件存放在 `~/.nodesign/.env`（密钥）和 `~/.nodesign/config.json`（模型插槽），也可以直接编辑。
+
+## 安全与隐私
+
+每个项目使用独立的工作区目录。本地数据默认保存在 `~/.nodesign/`，服务仅监听 `127.0.0.1`。
+
+在支持的平台上，可以启用系统级命令沙盒：
+
+- Linux：bubblewrap
+- macOS：sandbox-exec
+- Windows：当前暂不提供系统级命令沙盒
+
+还可以启用自动权限检查，对文件上传、外部请求和其他敏感操作进行额外判断。
+
+本地版默认不启用命令沙盒和自动权限检查。请根据使用场景在设置中开启。在 Windows 上，建议仅打开你信任的项目，并在执行涉及工作区外文件、安装软件或上传内容的操作前确认 Agent 的计划。
+
+## 项目状态
+
+个人项目，2026 年 4 月底起步，目前仍在快速迭代。版本号 `0.0.1` 是本地发行版的首个公开版本，核心功能已在内测中稳定使用。
+
+### 功能
+
+| 能力 | 当前状态 |
+|---|---|
+| 画布与项目管理 | 内测主版本运行中 |
+| 网站生成、预览与发布 | 稳定 |
+| 演示稿生成与导出 | 稳定 |
+| Word 文档 | 可用。预览分页与 Microsoft Word 可能存在偏差 |
+| 图片与视频工具 | 可用。具体能力取决于本机依赖和服务配置 |
+| 互动演出模式 | 实验中，尚未完整进入公开版本 |
+
+### 平台兼容性
+
+| 平台 | 状态 |
+|---|---|
+| Linux | 生产环境运行中 |
+| Windows | 已完成真机安装与运行验证 |
+| macOS | 有对应代码分支，尚未在真机上验证 |
+| 移动端 | 可以浏览和对话，整理和编辑建议使用电脑 |
+
+## 技术架构
+
+- **前端**：React + Vite。无限画布的相机、命中检测、关系排布和产物能力系统为自研实现（web/src/lib，45 个纯函数模块，配有单测）。
+- **服务端**：Node.js ESM。Agent 会话以项目工作区作为执行目录，通过约 50 个进程内工具操作文件、浏览器和不同类型的产物。
+- **会话同步**：服务端维护会话状态，支持流式输出、断线恢复和多标签页同步。
+- **模型兼容**：原生支持 Claude，并通过格式转换接入兼容 OpenAI API 的模型服务。无法匹配上游时直接返回错误，避免请求被发送到错误的模型服务。
+- **产物系统**：网站、演示稿和 Word 文档通过统一的注册机制接入预览、导出和发布流程。新增产物类型时，通过同一注册入口接入相关能力。
 
 ## 开发
 
 ```bash
 npm install && cd web && npm install && cd ..
+npm run dev                 # 服务端，读 .env
+cd web && npm run dev       # 前端
+npm test                    # server 测试 + web 测试
+```
 
-# 服务端（读 .env；需要 Claude 订阅登录态或 API key）
-npm run dev
+> 注意：完整运行需要配置模型接入（Claude 订阅或 API Key）以及部分本地工具依赖。设置页会列出缺少的依赖和安装方法。
 
-# 前端
-cd web && npm run dev
-```
+项目以 Vitest 测试套件作为发布前检查，server 和 web 合计 980 项用例，覆盖前后端契约、模块边界、权限能力表和关键用户文案。部分约束以静态测试固化，避免仅依赖注释和人工约定。例如：
 
-测试与守门：
+- 前后端双份能力表逐项对账
+- 权限判断必须通过能力表查询
+- 用户可见文案的措辞检查
+- 源文件行数棘轮
 
-```bash
-npm test               # server 单测 + web 单测（含 lint 型测试）
-npm run test:server    # 仅服务端
-node web/src/components/canvas/_hook-order-check.mjs   # TDZ 依赖顺序体检
-```
+前端部署使用 `web/scripts/deploy.sh`（新分片加入、旧分片不删、`index.html` 原子替换）。服务端改动需要重启进程。
 
-lint 型测试是这个仓库的护栏（没有 CI，vitest 就是部署链的闸门）：
+## 许可
 
-- `loc-ratchet.lint`：源文件不超过 600 行，存量超标文件按现状冻结上限，只降不升
-- `legacy-shape.lint`：旧任务模型的路径形状不许回到代码里
-- `path-compose.lint`：路径拼接必须走统一入口
-- parity 系列：前端消费的事件形状必须在服务端源码里逐字存在，reducer 消费的
-  事件必须在转发名单里
+AGPL-3.0。可以使用，可以修改，可以自行部署。对外提供服务时，修改需要一并开源。
+
+---
+
+## English overview
+
+**NoDesign** is an agent workbench for independent creators. An infinite canvas serves as your workspace: describe what you want, and the agent builds websites, slide decks, images, video and Word documents as real files on disk, right on the canvas. You can edit text in place, circle a region and annotate, drag elements around, and draw relations between cards. The agent picks all of that up on its next turn.
+
+```bash
+npx @xiaobuyu/nodesign
+```
 
-前端上线用 `web/scripts/deploy.sh`：构建到旁路目录后原子换入，旧分片保留，
-开着的页面不断链。服务端改动记得重启进程，Node 不热重载。
+Requires Node.js 20+ and at least one model provider: a Claude subscription (`npx @xiaobuyu/nodesign login`), an Anthropic API key, or any OpenAI-compatible endpoint (DeepSeek, OpenAI, OpenRouter, local Ollama, etc.). Runs on your machine with your own key. No subscription fee, no markup on model calls. Project files stay local; when using cloud models, task context is sent to the provider you configured. A hosted instance is available at [nodesign.xiaobuyu.trade](https://nodesign.xiaobuyu.trade) for trying it without installing.
 
-真渲染验证有两条通道：`web/scripts/inspect.mjs`（拦截 API 喂固定数据，纯 UI
-回归）与 `web/scripts/shot-live.mjs`（登录真服务端截图加探针，查真问题用）。
+What makes it different from a chat interface:
 
-## 现状
+- **The canvas is a real workspace.** Every card is a file, every folder is a directory. Dragging a card into a folder actually moves the file on disk.
+- **The agent is present.** It appears next to the card it's editing, and you can see code being written in real time.
+- **Your actions feed back.** Direct text edits, region selections, element dragging, and relation lines ("reference", "annotate", "continue") all become context for the next turn.
+- **The agent inspects its own work.** It captures screenshots at different viewport widths, reads computed styles, console errors, font loading status, and animation filmstrips, then continues editing based on what it finds.
+- **Memory is visible.** Decisions, style notes, and preferences live in the workspace as editable content, and can be crystallized into reusable Skills.
 
-个人项目，内测运行中。近期完成画布与 agent 交互的整体重做：扁平桌面模型、
-连线范式、铅笔精灵、agent 摆位与归纳工具、根站治理。方向与记录见提交历史。
+Personal project, started late April 2026, actively developed. Version 0.0.1 is the first public local release. 980 Vitest cases as the deploy gate. Production runs on Linux; tested on Windows; macOS code paths exist but are not yet verified on real hardware. Licensed AGPL-3.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaobuyu/nodesign",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "private": false,
   "type": "module",
   "description": "NoDesign — 面向独立创作者的 agent 创作工作台（本地分发版：npx nodesign）",

package/server/api/README.md

@@ -1,45 +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。
+# 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

@@ -1,75 +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;
-}
+/**
+ * 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;
+}