@xiaobuyu/nodesign 0.0.2 → 0.0.4

package/README.en.md

@@ -0,0 +1,184 @@
+[简体中文](https://github.com/Xiaokebuyu/Nodesign/blob/main/README.md) | **English**
+
+# NoDesign
+
+An infinite canvas, and an agent that stays in the room.
+
+Tell it what you want to make, and it creates websites, slide decks, documents, images and video right on the canvas. Everything it produces is saved as a real file you can keep editing, annotate, download and publish.
+
+![demo](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo.gif)
+
+## Try it
+
+```bash
+npx @xiaobuyu/nodesign
+```
+
+Requires Node.js 20+ and at least one model provider:
+
+- A Claude subscription or an Anthropic API key
+- OpenAI, DeepSeek, Zhipu, Tongyi, OpenRouter
+- Ollama or any other service that speaks the OpenAI API
+
+NoDesign charges no subscription fee and takes no cut of model calls. Project files and configuration stay on your machine. When you use a cloud model, the context needed to finish the task is sent to the provider you configured. When you use a local model such as Ollama, nothing leaves your computer.
+
+If you would rather not install anything yet, there is a hosted instance: [nodesign.xiaobuyu.trade](https://nodesign.xiaobuyu.trade)
+
+The hosted version offers free models with a daily allowance. Some local capabilities are not open there.
+
+## What it can help you make
+
+Three typical cases:
+
+- **A portfolio page**: put your reference images and text on the canvas, tell the Agent what style you want, check how it looks at desktop, tablet and phone widths, then publish it to the public internet once Cloudflare is configured.
+- **A slide deck**: put photos, text and a reference style on the canvas, the Agent generates paged slides, you annotate and revise directly on them, then export to PDF or PPTX.
+- **A content project**: sites, images, video and documents live on one canvas and are handled by the same Agent, which can keep drawing material from one artifact into another.
+
+### Artifact types
+
+| Artifact | Format | What you can do |
+|---|---|---|
+| Decks (slides, tall images, posters) | `.html` | Paged at 16:9, 9:16, 4:3 and other ratios; export to HTML, PDF, PPTX |
+| Sites (portfolios, landing pages, small apps) | A folder with an `index.html` | Desktop, tablet and phone preview; whole-site zip export; one-click publish once Cloudflare is configured |
+| Word documents | `.docx` | Real OOXML written directly, not HTML wrapped up as a Word file. Page-image preview, page flipping, download the original |
+| Images | Common image formats | Generation, background removal |
+| Video | Common video formats | Import, preview and transcoding |
+
+![Say one sentence to generate an image, then remove the background for a transparent PNG](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-image.gif)
+
+![The Agent produces a Word document, with the real layout visible on the canvas](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-docx.gif)
+
+These files do not depend on any format private to NoDesign. You can keep editing them in other tools, and download them at any time.
+
+Real projects made with NoDesign: a research site about a band, a 15-page Tibet travel deck with a companion site, a pixel-art page for a game server, a résumé `.docx` that went through six revisions. There are experimental ones too, such as an interactive visual novel where you pick the plot on the page and the text is generated in the chat. One published site: [spica-mix.share.xiaobuyu.trade](https://spica-mix.share.xiaobuyu.trade).
+
+## Why it is not just another AI chat box
+
+### The canvas is the workspace
+
+Cards on the canvas are real files, and folders are real directories. Moving, editing and tidying cards changes what is on disk.
+
+![Open a folder, drag a card into it, draw a relation between two cards](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-desktop.gif)
+
+### The Agent is present
+
+The Agent shows up next to whatever it is working on. You can see which file it is editing and how the content takes shape, instead of waiting for a chat box to return a finished answer.
+
+### The canvas is also a blackboard
+
+The Agent does not only put finished artifacts on the canvas, it puts its thinking there too. It sketches, writes notes, and draws lines between related things, to show how it plans to work or to take something complicated apart.
+
+![Taking apart the character relationships in a play: eight people in two families, lines labelled with what each pair is to the other, portraits generated on the spot and wired back to the names](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-blackboard.gif)
+
+Those notes are real files, kept under `notes/板书/` in the project. Sketch nodes, lines and notes can all be edited in place with a double click, and the Agent uses your edited version from the next turn on.
+
+![Double-click a note the Agent wrote and edit it in place on the canvas](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-chalk.gif)
+
+### Your actions become context for the next turn
+
+You can edit text directly, circle a region, drag elements around, or draw relations such as "reference", "annotate" and "continue from" between artifacts. All of it is collected as context for the next task.
+
+![Circle a region of the cover, write one line, and the Agent picks it up and revises it](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-roundtrip.gif)
+
+### The Agent can check its own results
+
+It can take screenshots at different screen widths and read computed styles, console errors, font loading state and animation frames, then keep revising based on what it finds. When it is done it screenshots the result and checks it. If you are still unhappy after two rounds, it asks a read-only review subagent to go through the pages.
+
+![A site previewed at desktop, tablet and phone widths](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-viewport.gif)
+
+### Memory is visible and editable
+
+Project decisions, style notes and personal preferences do not stay buried in the conversation history. They live in the workspace as content you can see, and they can be crystallized into reusable Skills.
+
+## Local vs hosted
+
+| | Local `npx @xiaobuyu/nodesign` | Hosted [nodesign.xiaobuyu.trade](https://nodesign.xiaobuyu.trade) |
+|---|---|---|
+| Models | The ones you configure (Claude subscription, API key, or any OpenAI-compatible service) | Free models with a daily allowance |
+| Data | Kept in `~/.nodesign/`; the server listens on `127.0.0.1` only | Stored on the server, isolated per user |
+| Account | None needed, open it and go | Open registration |
+| Capabilities | All of them. Screenshots, Word, background removal, image generation and so on are detected from your machine. Publishing sites needs Cloudflare Pages | Screenshots, search and image generation are open. Site publishing and subscription models are not open to the public |
+| Cost | No subscription, no markup. Model usage is billed by the provider you configured | Free |
+
+The local version is the main one. The hosted one is there so you can try it without installing anything.
+
+## Configuration
+
+Click the gear in the top right after starting. The settings page has four areas:
+
+- **Models**: two cards side by side. "Claude official" takes an API key, or logs into a Claude subscription with `nodesign login`. "Custom endpoint" starts from a provider preset (DeepSeek, OpenAI, Zhipu, Tongyi, OpenRouter, Ollama and others) and takes a base URL and a key. Every model configuration can run a connection test that actually checks plain chat, streaming, tool calls, image understanding and token counting. With no model configured, the model picker is empty.
+- **Local capabilities**: on startup it probes git, Chromium, LibreOffice, poppler, ffmpeg, rembg, image generation, search and publishing. Anything missing is listed with how to install it, and the tools that need it are shown as unavailable with the same instructions.
+- **Other settings**: search (four providers, pick one), the image generation channel, Cloudflare publishing, sandbox and permission mode.
+- **Status**: data directory, config file paths, restart.
+
+Configuration lives in `~/.nodesign/.env` (secrets) and `~/.nodesign/config.json` (model slots). You can edit both by hand.
+
+## Security and privacy
+
+Each project gets its own workspace directory. Local data is kept in `~/.nodesign/` by default, and the server listens on `127.0.0.1` only.
+
+On supported platforms you can turn on an OS-level command sandbox:
+
+- Linux: bubblewrap
+- macOS: sandbox-exec
+- Windows: no OS-level command sandbox at the moment
+
+You can also turn on automatic permission checks, which add a second judgement on file uploads, outbound requests and other sensitive operations.
+
+The local version ships with the command sandbox and the automatic permission checks off. Turn them on in settings according to how you use it. On Windows, open only projects you trust, and confirm the Agent's plan before it touches files outside the workspace, installs software or uploads anything.
+
+## Project status
+
+A personal project, started at the end of April 2026 and still moving quickly. The current local release is `0.0.4`, and the core features have been in steady use during the private beta.
+
+### Features
+
+| Capability | Current state |
+|---|---|
+| Canvas and project management | Running as the main build of the private beta |
+| Site generation, preview and publishing | Stable |
+| Deck generation and export | Stable |
+| Word documents | Usable. Page breaks in the preview may differ from Microsoft Word |
+| Image and video tools | Usable. What is available depends on local dependencies and service configuration |
+| Interactive performance mode | Experimental, not fully in the public release yet |
+
+### Platform support
+
+| Platform | State |
+|---|---|
+| Linux | Running in production |
+| Windows | Installed and verified on real hardware |
+| macOS | The code paths exist, not yet verified on real hardware |
+| Mobile | You can browse and chat; organizing and editing are better on a computer |
+
+## Architecture
+
+- **Frontend**: React + Vite. The infinite canvas camera, hit testing, relation layout and the artifact capability system are written from scratch (web/src/lib, 45 pure-function modules with unit tests).
+- **Backend**: Node.js ESM. An Agent session runs with the project workspace as its working directory, and works through 56 in-process tools that operate on files, the browser and the different artifact types.
+- **Session sync**: the server holds session state, with streaming output, reconnection after a drop, and multiple tabs staying in sync.
+- **Model compatibility**: Claude is supported natively, and OpenAI-compatible services are reached through a translation layer. When a request cannot be matched to an upstream it fails outright, so nothing is quietly sent to the wrong model service.
+- **Artifact system**: sites, decks and Word documents plug into preview, export and publishing through one registry. A new artifact type joins those flows through the same entry point.
+
+## Development
+
+```bash
+npm install && cd web && npm install && cd ..
+npm run dev                 # server, reads .env
+cd web && npm run dev       # frontend
+npm test                    # server tests + web tests
+```
+
+> Note: running the whole thing needs a model provider configured (a Claude subscription or an API key) and some local tool dependencies. The settings page lists what is missing and how to install it.
+
+The Vitest suite is the gate before shipping: 1021 cases across server and web, covering the client/server contracts, module boundaries, the permission capability table and key user-facing copy. Some constraints are pinned by static tests rather than left to comments and habit. For example:
+
+- The two capability tables, client and server, are reconciled item by item
+- Permission decisions have to go through the capability table
+- Wording checks on user-facing copy
+- A line-count ratchet on source files
+
+The frontend is deployed with `web/scripts/deploy.sh` (new chunks added, old chunks kept, `index.html` replaced atomically). Server changes need a process restart.
+
+## License
+
+AGPL-3.0. Use it, change it, run your own instance. If you offer it to others as a service, your changes have to be open-sourced too.

package/README.md

@@ -1,3 +1,5 @@
+**简体中文** | [English](https://github.com/Xiaokebuyu/Nodesign/blob/main/README.en.md)
+
 # NoDesign
 
 一张无限画布，一个始终在场的 Agent。
@@ -42,6 +44,10 @@ NoDesign 本身不收取订阅费，也不对模型调用加价。项目文件
 | 图片 | 常见图片格式 | 生图、抠图 |
 | 视频 | 常见视频格式 | 视频导入、预览与转码 |
 
+![说一句话生成图片，再抠掉背景，得到透明底 PNG](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-image.gif)
+
+![Agent 生成 Word 文档，在画布上直接看排版](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-docx.gif)
+
 这些文件不依赖 NoDesign 的私有格式，可以使用其他工具继续编辑和下载。
 
 使用 NoDesign 完成的实际项目：一个乐队的研究站、一份 15 页的西藏攻略幻灯配站点、一套像素风服务器宣传页、一份改了六版的简历 .docx。也有实验性项目，比如一个在页面上选择剧情、在聊天里生成内容的互动视觉小说。已发布的一个站点：[spica-mix.share.xiaobuyu.trade](https://spica-mix.share.xiaobuyu.trade)。
@@ -58,6 +64,16 @@ NoDesign 本身不收取订阅费，也不对模型调用加价。项目文件
 
 Agent 会出现在它正在处理的内容旁边。你可以看到它正在编辑哪个文件，以及内容如何逐步生成，而不是只能等待聊天框返回最终结果。
 
+### 画布也是黑板
+
+Agent 不只是把做完的产物放上画布，也把想法放上去。它会画草图、写板书、在相关的东西之间拉线，说明自己打算怎么做，或者把一件复杂的事情拆开摆出来。
+
+![拆《雷雨》的人物关系：八个人分成两家，关系线标出谁和谁是什么，主要人物的肖像当场生成后连回名字](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-blackboard.gif)
+
+板书是真文件，保存在项目的 `notes/板书/` 目录下。草图节点、连线和板书都可以双击直接改，改完 Agent 接着用改过的版本。
+
+![双击 Agent 写的板书，在画布上原地改字](https://raw.githubusercontent.com/Xiaokebuyu/Nodesign/main/docs/demo-chalk.gif)
+
 ### 你的操作会成为下一轮上下文
 
 你可以直接修改文字、圈选区域、拖动元素，或者在不同产物之间建立「参考」「批注」「接着做」等关系。这些操作会被整理为后续任务的上下文。
@@ -113,7 +129,7 @@ Agent 会出现在它正在处理的内容旁边。你可以看到它正在编
 
 ## 项目状态
 
-个人项目，2026 年 4 月底起步，目前仍在快速迭代。版本号 `0.0.1` 是本地发行版的首个公开版本，核心功能已在内测中稳定使用。
+个人项目，2026 年 4 月底起步，目前仍在快速迭代。本地发行版当前是 `0.0.4`，核心功能已在内测中稳定使用。
 
 ### 功能
 
@@ -138,7 +154,7 @@ Agent 会出现在它正在处理的内容旁边。你可以看到它正在编
 ## 技术架构
 
 - **前端**：React + Vite。无限画布的相机、命中检测、关系排布和产物能力系统为自研实现（web/src/lib，45 个纯函数模块，配有单测）。
-- **服务端**：Node.js ESM。Agent 会话以项目工作区作为执行目录，通过约 50 个进程内工具操作文件、浏览器和不同类型的产物。
+- **服务端**：Node.js ESM。Agent 会话以项目工作区作为执行目录，通过 56 个进程内工具操作文件、浏览器和不同类型的产物。
 - **会话同步**：服务端维护会话状态，支持流式输出、断线恢复和多标签页同步。
 - **模型兼容**：原生支持 Claude，并通过格式转换接入兼容 OpenAI API 的模型服务。无法匹配上游时直接返回错误，避免请求被发送到错误的模型服务。
 - **产物系统**：网站、演示稿和 Word 文档通过统一的注册机制接入预览、导出和发布流程。新增产物类型时，通过同一注册入口接入相关能力。
@@ -154,7 +170,7 @@ npm test                    # server 测试 + web 测试
 
 > 注意：完整运行需要配置模型接入（Claude 订阅或 API Key）以及部分本地工具依赖。设置页会列出缺少的依赖和安装方法。
 
-项目以 Vitest 测试套件作为发布前检查，server 和 web 合计 980 项用例，覆盖前后端契约、模块边界、权限能力表和关键用户文案。部分约束以静态测试固化，避免仅依赖注释和人工约定。例如：
+项目以 Vitest 测试套件作为发布前检查，server 和 web 合计 1021 项用例，覆盖前后端契约、模块边界、权限能力表和关键用户文案。部分约束以静态测试固化，避免仅依赖注释和人工约定。例如：
 
 - 前后端双份能力表逐项对账
 - 权限判断必须通过能力表查询
@@ -166,25 +182,3 @@ npm test                    # server 测试 + web 测试
 ## 许可
 
 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
-```
-
-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.
-
-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.
-
-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.2",
+  "version": "0.0.4",
   "private": false,
   "type": "module",
   "description": "NoDesign — 面向独立创作者的 agent 创作工作台（本地分发版：npx nodesign）",
@@ -12,6 +12,7 @@
     "server/",
     "web/dist/",
     "README.md",
+    "README.en.md",
     "LICENSE",
     "!server/**/*.test.js",
     "!server/**/_probe-*",

package/server/api/assets/helpers.js

@@ -7,12 +7,32 @@
  * 不会再随下一次拆分复发（谁也不用记得"这个函数该跟着谁走"）。
  */
 
+import { promises as fs } from 'node:fs';
+import { parseChalk } from '../../lib/chalk.js';
+
 /** 单层路径片段：不含分隔符、不含 `..`、不以点开头、长度可控 */
 export function safeSegment(s) {
   return typeof s === 'string' && !!s && s.length <= 200
     && !s.includes('/') && !s.includes('\\') && !s.includes('..') && !s.startsWith('.');
 }
 
+/**
+ * 便签/板书正文上卡（2026-08-23 从 assets.js 抽出）：frontmatter 带 nd: chalk 的是板书
+ * （agent/用户写在画布上的话，同一形态另一张脸），其余按便签头解析；正文 ≤4KB 截断。
+ * 读不到就静默（agent 正在写的文件可能半途消失）。
+ */
+export async function decorateNoteText(item, absPath) {
+  try {
+    const raw = await fs.readFile(absPath, 'utf8');
+    const parsed = parseChalk(raw);
+    const { body, sessionId } = parsed.chalk ? parsed : parseNoteFrontmatter(raw);
+    item.text = body.length > 4096 ? body.slice(0, 4096) + '…' : body;
+    if (sessionId) item.sessionId = sessionId;
+    if (parsed.chalk) item.chalk = parsed.chalk;
+  } catch { /* */ }
+  return item;
+}
+
 /** 便签 frontmatter：只认最简单的 `---\nsession: xxx\n---` 头，其余原样当正文 */
 export function parseNoteFrontmatter(raw) {
   const m = /^---\n([\s\S]{0,500}?)\n---\n?/.exec(raw);

package/server/api/assets/notes.js

@@ -13,6 +13,7 @@ import express from 'express';
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { safeSegment, parseNoteFrontmatter } from './helpers.js';
+import { patchBoard } from '../../projects/board-store.js';
 
 /**
  * @param {object} deps
@@ -123,6 +124,55 @@ export function mountNotesRoutes({ router, guardProject, getSharedDir, ensurePro
     } catch (err) { next(err); }
   });
   
+  /**
+   * 板书（notes/板书/<name>.md，2026-08-23）：用户侧改 / 删。名字是单段文件名，
+   * 目录固定 —— 跟便利贴同一套 safeNoteSegment 闸。
+   */
+  const resolveChalk = (pid, name) => {
+    const base = path.join(getSharedDir(pid), 'notes', '板书');
+    const file = path.resolve(base, name);
+    return file.startsWith(base + path.sep) ? file : null;
+  };
+  router.put('/:pid/chalk/:name', express.json(), async (req, res, next) => {
+    try {
+      if (!guardProject(req, res)) return;
+      const { name } = req.params;
+      if (!safeNoteSegment(name, { md: true })) return res.status(400).json({ error: 'invalid filename' });
+      const text = String(req.body?.text ?? '');
+      if (!text.trim()) return res.status(400).json({ error: 'text required' });
+      if (text.length > 20_000) return res.status(400).json({ error: 'too long (max 20k chars)' });
+      const file = resolveChalk(req.params.pid, name);
+      if (!file) return res.status(400).json({ error: 'invalid path' });
+      // frontmatter（nd:chalk/anchor/reply_to/tag）由服务端保住：正文只收正文。客户端拼头那条路
+      // 在 fetch 失败时会丢头、还会把 4KB 截断的展示副本写回（fable 08-23 P2）。
+      // 来的文本若自带头（老客户端拼过来的）剥掉，以磁盘上的头为准；磁盘上没有就保留来的头。
+      let head = '';
+      try { head = /^---\n[\s\S]{0,800}?\n---\n?/.exec(await fs.readFile(file, 'utf8'))?.[0] || ''; } catch { /* 新文件 */ }
+      const incomingHead = /^---\n[\s\S]{0,800}?\n---\n?/.exec(text)?.[0] || '';
+      const body = text.slice(incomingHead.length).replace(/^\n+/, '');
+      if (!body.trim()) return res.status(400).json({ error: 'text required' });
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, `${head || incomingHead}${head || incomingHead ? '\n' : ''}${body.replace(/\n+$/, '')}\n`, 'utf8');
+      res.json({ ok: true, path: `notes/板书/${name}` });
+    } catch (err) { next(err); }
+  });
+  router.delete('/:pid/chalk/:name', async (req, res, next) => {
+    try {
+      if (!guardProject(req, res)) return;
+      const { name } = req.params;
+      if (!safeNoteSegment(name, { md: true })) return res.status(400).json({ error: 'invalid filename' });
+      const file = resolveChalk(req.params.pid, name);
+      if (!file) return res.status(400).json({ error: 'invalid path' });
+      try { await fs.unlink(file); } catch (err) {
+        if (err.code === 'ENOENT') return res.status(404).json({ error: 'not found' });
+        throw err;
+      }
+      // 座位和线一起清，别留指向已删文件的幽灵条目（read_board 会把它当"摆过的"列出来）
+      try { await patchBoard(req.params.pid, { objects: { [`notes/板书/${name}`]: null } }); } catch { /* 清不掉不挡删除 */ }
+      res.status(204).end();
+    } catch (err) { next(err); }
+  });
+
   /** DELETE /:pid/task-notes/:filename — 删便利贴 */
   router.delete('/:pid/task-notes/:filename', async (req, res, next) => {
     try {

package/server/api/assets.js

@@ -28,7 +28,8 @@ import { resolveArtifactFile, isServablePath } from '../lib/artifact-file-path.j
 import { getProjectCover } from '../lib/cover.js';
 import { makeDocxPageHandler, makeDocxPdfHandler } from './assets/docx-page.js';
 import { mountNotesRoutes } from './assets/notes.js';
-import { safeSegment, parseNoteFrontmatter } from './assets/helpers.js';
+import { safeSegment, decorateNoteText } from './assets/helpers.js';
+import { CHALK_DIR } from '../lib/chalk.js';
 import {
   sendImage, isThumbPath, findOriginalForThumbnail, imageCacheControl,
   THUMBNAIL_MAX_DIM, THUMBNAIL_QUALITY,
@@ -348,16 +349,8 @@ router.get('/:pid/artifacts', async (req, res, next) => {
             item.meta = JSON.parse(metaRaw);
           } catch { /* 无 sidecar（旧图）→ 无 meta */ }
         }
-        // 便签直接把正文带给前端渲卡片（≤4KB 截断，完整内容走 artifact-file）。
-        // frontmatter 里的 session 字段是分区归属（agent 写便签时按约定带上）。
-        if (kind === 'note' && ext === '.md') {
-          try {
-            const raw = await fs.readFile(path.join(dir, e.name), 'utf8');
-            const { body, sessionId } = parseNoteFrontmatter(raw);
-            item.text = body.length > 4096 ? body.slice(0, 4096) + '…' : body;
-            if (sessionId) item.sessionId = sessionId;
-          } catch { /* */ }
-        }
+        // 便签/板书把正文带给前端渲卡片（≤4KB 截断，完整内容走 artifact-file；见 helpers.decorateNoteText）
+        if (kind === 'note' && ext === '.md') await decorateNoteText(item, path.join(dir, e.name));
         artifacts.push(item);
       }
     };
@@ -497,6 +490,8 @@ router.get('/:pid/artifacts', async (req, res, next) => {
       // 24 条产物里 6 条重复，画布上就是一张卡叠着另一张同名卡。
       await scanDir(workspaceRoot, 'task-file', '', 0);
       await scanDir(path.join(workspaceRoot, 'notes'), 'note', 'notes');
+      // 板书住 notes/板书/（不进 notes/ 顶层：便利贴注入只列顶层，板书另有自己的注入）
+      await scanDir(path.join(workspaceRoot, CHALK_DIR), 'note', CHALK_DIR);
       for (const rel of folders) {
         await scanDir(path.join(workspaceRoot, rel), 'task-file', rel, 0);
       }

package/server/api/board.js

@@ -12,7 +12,10 @@
 import express from 'express';
 import { validateProjectId, getProject } from '../projects/store.js';
 import { guardProject } from './_guard.js';
-import { readBoard, replaceBoard, patchBoard } from '../projects/board-store.js';
+import { readBoard, replaceBoard, patchBoard, commitStaging, removeByTag } from '../projects/board-store.js';
+import { setViewpoint, getViewpoint } from '../projects/viewpoint-store.js';
+import { exportGraph, exportGraphZip } from '../lib/board-graph-export.js';
+import { getSharedDir } from '../projects/workspace.js';
 
 const router = express.Router();
 
@@ -54,4 +57,78 @@ router.put('/:pid/board', express.json({ limit: '600kb' }), async (req, res, nex
   }
 });
 
+/**
+ * 用户视点上报（2026-08-23 黑板）：前端节流 POST，服务端只留最近一份。
+ * 不广播、不落盘；失败也不该打扰用户（前端 fire-and-forget）。
+ */
+router.post('/:pid/viewpoint', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const v = setViewpoint(req.params.pid, req.body?.viewpoint, req.user?.id || null);
+    res.json({ ok: !!v });
+  } catch (err) { next(err); }
+});
+
+/** 读最近一份视点（排障用：看看服务端眼里"用户在看哪"；agent 走 read_user_view） */
+router.get('/:pid/viewpoint', async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    res.json({ viewpoint: getViewpoint(req.params.pid) });
+  } catch (err) { next(err); }
+});
+
+/** 草稿落定（用户也可以按组落定：黑板上 agent 的草稿半透明，点一下变实） */
+router.post('/:pid/board/commit', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const tag = typeof req.body?.tag === 'string' ? req.body.tag : null;
+    const { board, committed } = await commitStaging(req.params.pid, { tag });
+    res.json({ ok: true, committed, board });
+  } catch (err) { next(err); }
+});
+
+/** 黑板擦：按 #tag 整组删（只删画布原生物件与线；产物卡只摘标签） */
+router.post('/:pid/board/erase', express.json({ limit: '16kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const tag = typeof req.body?.tag === 'string' ? req.body.tag : '';
+    if (!tag) return res.status(400).json({ error: 'tag required' });
+    const { board, removed } = await removeByTag(req.params.pid, tag);
+    res.json({ ok: true, removed, board });
+  } catch (err) { next(err); }
+});
+
+/**
+ * 连接图导出（2026-08-23 黑板）：?format=json|mermaid|svg&tag=&layer=
+ * 真相是 board.json，这里只派生。download=1 时带附件头。
+ */
+router.get('/:pid/board/graph', async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const format = String(req.query.format || 'json');
+    const tag = typeof req.query.tag === 'string' && req.query.tag ? req.query.tag.slice(0, 40) : null;
+    const layer = typeof req.query.layer === 'string' ? req.query.layer.slice(0, 300) : '';
+    const board = await readBoard(req.params.pid);
+    if (format === 'zip') {
+      const projectName = getProject(req.params.pid)?.name || '画布';
+      const { zip } = await exportGraphZip(board, { workspaceRoot: getSharedDir(req.params.pid), tag, layer, projectName });
+      const buf = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+      res.setHeader('Content-Type', 'application/zip');
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(`board${tag ? `-${tag}` : ''}.zip`)}`);
+      return res.send(buf);
+    }
+    const { mime, body } = exportGraph(board, { format, tag, layer });
+    res.setHeader('Content-Type', mime);
+    if (req.query.download) {
+      const ext = format === 'mermaid' ? 'mmd' : format;
+      const name = `board${tag ? `-${tag}` : ''}.${ext}`;
+      res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(name)}`);
+    }
+    res.send(body);
+  } catch (err) {
+    if (err?.status === 400) return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
 export default router;

package/server/engine/agent/events.js

@@ -41,6 +41,7 @@
  *   run.rate_limit             { info }                                    rate limit 变化
  *   run.image_generated        { path, sizeBytes, prompt, assetRole, ... } generate_image 完成（Phase A）
  *   board.updated              { objectId, zoneId, summary }               pin_to_board 改画布布局（sessionId:null 广播，前端整份重拉 board.json）
+ *   board.focus                { rect, tag, layer }                        agent 落了一张草图（sessionId:null 广播；前端只在黑板模式跟镜头）
  *   project.active_session     { activeSessionId }                         项目级会话指针变更（故意不带 sessionId —— 见构造器注释）
  *
  * 外层把 EventBus 桥接到：

package/server/engine/agent/hooks/user-prompt-submit.js

@@ -26,6 +26,11 @@ import path from 'node:path';
 import { readUiConfigFile } from '../../../projects/ui-config.js';
 import { readAssetsSummary } from '../../../projects/assets-summary.js';
 import { relationsDigest } from '../../../lib/board-relations.js';
+import { getViewpoint, describeViewpoint } from '../../../projects/viewpoint-store.js';
+import { recentChalk, CHALK_DIR } from '../../../lib/chalk.js';
+import { readBoard } from '../../../projects/board-store.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { layerOf } from '../../../lib/canvas-id.js';
 import {
   getActiveArtifact, listWorkspaceArtifacts, taskManifest, kindDef,
   KIND_DECK, KIND_SITE, ENTRY_FILE,
@@ -107,6 +112,25 @@ async function collectSections({ workspaceRoot, sessionId, projectId }) {
   } catch { /* notes/ 不存在：noop */ }
 
   // 画布关系线：用户画的排前面
+  // 用户视点（2026-08-23 黑板）：一行，只在变化时进注入（renderTurnState 按 hash 判）。
+  // 视口矩形按 1/8 视口量化再进 hash，不然相机挪一像素就算"变了"。
+  try {
+    const vp = getViewpoint(projectId);
+    if (vp) {
+      const board = await readBoard(projectId);
+      const known = new Set(Object.keys(board.zones || {}));
+      const rects = Object.entries(board.objects || {})
+        .filter(([id, e]) => Number.isFinite(e?.x) && layerOf(id, e, known) === (vp.layer || ''))
+        .map(([id, e]) => ({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+      const q = vp.camera ? { ...vp, camera: {
+        x: Math.round(vp.camera.x / Math.max(1, vp.camera.w / 8)) * Math.round(vp.camera.w / 8),
+        y: Math.round(vp.camera.y / Math.max(1, vp.camera.h / 8)) * Math.round(vp.camera.h / 8),
+        w: vp.camera.w, h: vp.camera.h,
+      } } : vp;
+      const line = describeViewpoint(q, rects);
+      if (line) sections.push({ key: 'viewpoint', title: '用户视点', text: `用户此刻在画布上：${line}。他说「这个/这里/这张」多半指选中的 > 开着的窗 > 视口里的东西；要细节调 read_user_view。` });
+    }
+  } catch { /* 视点读不到就沉默 */ }
   try {
     const digest = await relationsDigest(projectId, { limit: 12 });
     if (digest) {
@@ -137,6 +161,25 @@ async function collectSections({ workspaceRoot, sessionId, projectId }) {
   } catch { /* 扫不动就不说 */ }
 
   // tweaks 开关：文件不存在 = 用户没碰过 = 沉默
+  // 最近板书（2026-08-23）：你/用户在画布上说过的最近几句 —— 对话在板上，得记得板上说了什么
+  try {
+    const recent = await recentChalk(workspaceRoot, { limit: 8 });
+    if (recent.length) {
+      const lines = recent.map(c => `  ${c.path}（${c.by === 'user' ? '用户' : '你'}${c.anchor ? `，关于 ${c.anchor}` : ''}${c.replyTo ? `，回应 ${c.replyTo.replace(`${CHALK_DIR}/`, '')}` : ''}）「${c.first}」`);
+      sections.push({ key: 'chalk', title: '最近板书', text: `画布上最近的板书（${CHALK_DIR}/，新在前；正文 Read 文件）：\n${lines.join('\n')}`, items: recent.map(c => c.path) });
+    }
+  } catch { /* 板书读不到就沉默 */ }
+  // 黑板模式（2026-08-23）：用户在画布上专注思考时开。这一节只在开着时注入，关着不提。
+  try {
+    const cfg = await readUiConfigFile(workspaceRoot);
+    if (cfg?.blackboard_mode === true) {
+      sections.push({ key: 'blackboard', title: '黑板模式', text:
+        '【黑板模式：开】用户此刻在画布上专注思考。这一轮默认这么做：想事情就画成图（sketch_on_board，'
+        + '小改动用 edit_sketch 原地改别重画）；做完一件东西在它旁边写一条板书（write_on_board near=）；'
+        + '用户标注了板上的东西就接在那条下面回（reply_to=）。侧栏照常回复，但板上已经写的别大段重复。'
+        + '尺寸守规范（0.8 倍一屏可读、正文 md 起、一条板书说一件事）；画完 look_at_board 看一眼再收。' });
+    }
+  } catch { /* 读失败：不注入 */ }
   try {
     const cfg = await readUiConfigFile(workspaceRoot);
     if (cfg) {