paintress 0.6.0 → 0.7.1

package/README.md

@@ -18,10 +18,21 @@ The agent does the reading and writing, through MCP tools or the CLI. The browse
 
 | Part | Purpose |
 | --- | --- |
-| MCP tools | ensure the viewer, create, query, read, update, insert, delete, move, batch, validate, render, screenshot |
+| MCP tools | paintress_viewer, paintress_new, paintress_doc_info, paintress_query, paintress_get, paintress_update, paintress_insert, paintress_delete, paintress_move, paintress_batch, paintress_validate, paintress_convert, paintress_preset, paintress_project, paintress_font, paintress_audit, paintress_establish, paintress_adjust, paintress_component, paintress_render, paintress_screenshot, paintress_marks |
 | CLI | the same operations plus the viewer process, for use without an agent |
 | Viewer | local web server: renders a document, highlights changes, hands back clicked nodes as `#1`, `#2`, … |
-| Screenshot | PNG of a whole canvas, for agents that can look at images |
+| Screenshot | PNG of a canvas or one board; scale 0.2–2 (default 0.8), either edge capped to 8192px |
+
+## Files and formats
+
+New files are `.ptr` — paintress's own flavor of the same JSON design document. Existing `.pen` files open, edit and render unchanged; only the extension differs.
+
+Two project-level files keep a project consistent. They live at the **registered project root** — the directory you watch, not the folder of an individual design file — and they belong in version control next to the designs. `paintress_project` (and the viewer's `designSystem` block) returns their exact paths and reports any nested duplicate that would split the design system:
+
+| File | Holds |
+| --- | --- |
+| `__preset.ptr` | design tokens (colors, radii, spacing, font sizes, font families), preset groups and the font registry |
+| `__components.ptr` | reusable components (nodes marked `reusable`) |
 
 ## Requirements
 
@@ -51,6 +62,7 @@ paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                       [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
                                                            create a design file (one empty board)
 paintress info <file>                                      document summary
+paintress convert <file.pen> [out.ptr] [--force]          convert .pen to .ptr (source untouched)
 paintress query <file> [--type t] [--name n|--regex]    find nodes
 paintress get <file> <id> [--depth n]                   read a node subtree
 paintress update <file> <id> '<patch-json>'             shallow-merge attributes
@@ -59,14 +71,20 @@ paintress delete <file> <id>                            remove a node
 paintress move <file> <id> <parent> [--index n]         reparent a node
 paintress batch <file> '<ops-json>'                     several operations at once
 paintress validate <file>                               check against the format spec
-paintress preset list|set|remove ...                    project presets (colors / radii)
-paintress component list|insert ...                     project component library
+paintress preset list|set|remove|seed|set-group|remove-group ...
+                                                           tokens, groups and the starter scale
+paintress font list|add|remove|default ...                project font registry
+paintress audit <file>                               read-only design-system audit
+paintress establish <file> [--apply]                propose tokens / preset groups (dry-run by default)
+paintress adjust <file> --key k --value v [--apply] preview or apply a design-system adjustment
+paintress component list|insert|add ...                  project component library
 paintress render <file> <out.html>                      write the canvas as HTML
-paintress shot <file> <out.png> [--scale n] [--board id|name]  render to PNG (one board or the whole canvas)
+paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  render to PNG (default 0.8)
 
-paintress web [--port n] [--idle ms] [--daemon]         ensure the viewer is running (idempotent)
+paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
+                                                        ensure the viewer is running (idempotent, returns at once)
 paintress ping | status | stop                          viewer control
-paintress watch <name> <dir> | unwatch <name>           register a directory to browse
+paintress watch <name> <dir> [--depth n] | unwatch <name>  register a directory to browse
 paintress attach <name>                                 keep the viewer alive while an agent works
 
 paintress install [client...] [--dry-run]               write MCP config entries
@@ -77,29 +95,54 @@ paintress mcp-config <client>                           print the config snippet
 ## Viewer
 
 ```bash
-paintress web --daemon
+paintress web
 paintress watch demo ./demo
-# open http://localhost:3316/demo
+# open http://localhost:6033/demo
 ```
 
-`paintress web --daemon` is idempotent: if a viewer is already running it prints that process's `pid` / `port` / `http` and exits, so it is safe to run before every drawing session — there is never a second instance. The foreground form (`paintress web`) reuses a running viewer the same way instead of erroring; it only blocks when it had to start one. `paintress stop` is how you replace a running viewer (e.g. on another port).
+`paintress web` is idempotent and returns immediately: if a viewer is already running it prints that process's `pid` / `port` / `http`, otherwise it starts one and opens the viewer window on it. Either way the command is safe to run before every drawing session — there is never a second instance, and the window is opened by the program, in the desktop browser (`--foreground` keeps the process attached to your shell when you want its log; `paintress stop` is how you replace a running viewer, e.g. on another port). Under WSL the window lands in the Windows browser, never in a browser inside the distro.
+
+The port is not a constant you should memorize: it is **chosen at startup and reported back**. The default is `6033`; if that port is unusable the viewer walks `6033 → 6133 → 6233` on `127.0.0.1`, and if none of them can be reached from the host it re-binds the same three ports on `0.0.0.0` (six candidates, first usable one wins, otherwise it fails with the full attempt table). Under WSL this matters: Windows can reserve a port for Hyper-V, in which case `localhost` forwarding is never created and the human's browser sees "connection refused" while everything inside the distro works — the fallback then hands you `http://<wsl-ip>:6033/` instead. The `http` / `access.url` field is authoritative: print it, do not rebuild it. `--port` pins one port and never jumps (a busy port is an error), `--bind loopback|all` pins the interface.
 
-Agents get the same guarantee from the MCP side: `paintress_viewer` ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks.
+Agents get the same guarantee from the MCP side: `paintress_viewer` ensures the viewer and registers the current project, and the MCP server re-checks it before every write, so the viewer is up before the first edit instead of after someone asks. Its result carries the same `url` / `access` block, so an agent that started the viewer on a fallback port tells the human the address that actually works.
 
-A design file that has a sibling Markdown file of the same name (`home.ptr` → `home.md`) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note, read-only: what the design is for, what is still open, which requirement it answers.
+A design file that has a sibling Markdown file of the same name (`home.ptr` → `home.md`) gets a notes button in the top-left corner of the canvas. Click it and the canvas narrows to make room for the note: what the design is for, what is still open, which requirement it answers. The note is a plain Markdown file next to the design — write it yourself or let the agent write it; the panel is read-only.
 
-The rail in the top-right corner holds the project's design system. **Presets** are the project's colors and corner radii: the agent references them (`$color-brand`) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". **Components** is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists.
+The rail in the top-right corner holds the project's design system. **Presets** are the project's colors, corner radii, spacing and font values: the agent references them (`$color-brand`) instead of pasting values, and you can change one here and watch the canvas update — no more "a bit bluer". Nodes can also reference a whole preset group; groups are shown read-only in the panel. **Components** is a read-only gallery of everything reusable the agent has built so far, so you can see progress and the agent can look before rebuilding something that already exists. A font badge next to the version shows how many families loaded; when one is missing its tooltip names the substitute.
 
-Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, `Ctrl/Cmd+0` returns to 100%, `Shift+1` fits the window. Files with more than one board get a board strip. Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with `paintress_marks`.
+Canvas navigation: wheel zooms at the pointer, space / middle button / empty area drags to pan, `Ctrl/Cmd+0` returns to 100%, `Shift+1` fits the window, and `Ctrl/Cmd+K` quickly switches design files. Selecting a node opens a read-only inspector. Files with more than one board get a board strip; the active board can be exported as PNG at 0.5x / 1x / 2x (1x means its design pixels; the file is `<design>-<board>@<scale>x.png` and is scaled back when either edge exceeds 8192px). Edits made through the CLI or MCP are highlighted in the viewer, and clicks assign short ids that the agent can read back with `paintress_marks`; each mark carries the file and node id, so a shorthand resolves to one element in one file.
 
-Projects are named after their directory path (`c-thun/raybend`), so the URL reads like the path: `http://localhost:3316/c-thun/raybend?file=design/editor.pen`. Project rows have an **×** on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and **Stop server** in the sidebar footer shuts the viewer process down — both ask for confirmation first.
+Projects are named after their directory path (`c-thun/raybend`), so the URL reads like the path: `http://localhost:6033/c-thun/raybend?file=design/editor.pen`. Project rows have an **×** on hover that unbinds the project (design files are untouched; an agent re-registers on its next start), and **Stop server** in the sidebar footer shuts the viewer process down — both ask for confirmation first.
 
-The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens the browser on its own project; projects appear and leave with a short animation as agents come and go; when the last project is gone a 10-second countdown closes the window and the process. A browser that nobody is looking at no longer keeps the process alive.
+The viewer follows the agent instead of asking you to manage it. When an agent starts the viewer it opens your browser on that agent's own project — nothing for the agent to run twice, nothing for you to open by hand; projects appear and leave with a short animation as agents come and go. When the last project is gone **or the server is stopped** (the sidebar's Stop server, an idle exit), the page counts down ten seconds and closes its own window — you never have to close the tab by hand. A browser that nobody is looking at no longer keeps the process alive.
 
 When npm has a newer release than the running one, the version badge in the header grows a second line in rust red; clicking it opens the upgrade prompt (one copyable sentence) and the GitHub link. The check is client-optional on the daemon side: if npm is unreachable, the badge simply stays as it is.
 
 The toolbar's right side has two viewer-only controls. **Canvas background** switches Light / Gray / Dark for the design surface without touching the rest of the UI. **Language** switches the interface between 中文 and EN; on first load it follows the browser, and anything that is not Chinese gets English. Both are per-browser and remembered locally. Registering a project, or dropping a new design file into a watched directory, updates every open viewer without a reload.
 
+## Design system
+
+One source of truth per project, so a change lands everywhere instead of on one screen:
+
+- **Tokens** live in `__preset.ptr` and are referenced as `$color-brand` — never pasted. Kinds: `color`, `radius`, `spacing`, `fontSize`, `font`.
+- **Preset groups** apply a set of token references to one node type; a node opts in with `preset: "card"`.
+- **Components** live in `__components.ptr`; the agent copies one in, so a design is not rebuilt from scratch.
+- **Fonts** are registered per family with a source (`web` CSS URL, a project `css`/`file`, a `system` font, or `bundle` for app-only fonts) and, when the source cannot be verified, a design-time `preview`. Every read reports which families loaded and which fell back.
+
+`paintress_preset seed` (dry-run by default) fills a coherent starter scale — 27 tokens, 6 preset groups and the two web fonts. `audit` finds drift, `establish` proposes tokens from repeated values, and `adjust` shows the blast radius before changing anything.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `PTR_BROWSER` | Browser executable used for screenshots and PNG export |
+| `PAINTRESS_HOME` | State directory (daemon registry, Chromium font cache); default `~/.paintress` |
+| `PAINTRESS_NO_OPEN` | `1` never opens a browser window |
+| `PAINTRESS_NO_AUTO_WEB` | `1` stops the MCP server from ensuring the viewer before writes |
+| `PAINTRESS_NO_WEB_FONTS` | `1` skips the built-in web fonts (offline / CI) |
+| `PAINTRESS_PORT` | Port the `ui/` vite dev server proxies to (default `6033`); set it to the viewer's actual port when the port ladder jumped |
+| `CI` | `true` behaves like `PAINTRESS_NO_OPEN` |
+
 ## MCP clients
 
 `paintress install` writes these; the same entries can be added by hand.
@@ -130,7 +173,7 @@ paintress mcp-config cursor   # print the exact snippet instead of editing files
 - `.agents/memory/ARCHITECTURE.md` — design decisions and their rationale
 - `.agents/implementations/` — per-change records with measurements
 
-paintress also opens existing `.pen` design files as-is.
+paintress also opens existing `.pen` design files as-is; `paintress convert` turns one into `.ptr` when you ask for it.
 
 ## Release (maintainers)
 

package/README.zh-CN.md

@@ -18,10 +18,21 @@ paintress 是一个给 AI agent 用的界面设计工具。你在对话里说要
 
 | 组成 | 作用 |
 | --- | --- |
-| MCP 工具 | 确保查看器在跑、新建、查询、读取、更新、插入、删除、移动、批量、校验、渲染、截图 |
+| MCP 工具 | paintress_viewer、paintress_new、paintress_doc_info、paintress_query、paintress_get、paintress_update、paintress_insert、paintress_delete、paintress_move、paintress_batch、paintress_validate、paintress_convert、paintress_preset、paintress_project、paintress_font、paintress_audit、paintress_establish、paintress_adjust、paintress_component、paintress_render、paintress_screenshot、paintress_marks |
 | CLI | 同样的操作，外加查看器进程；不接 agent 也能用 |
 | 查看器 | 本地 web 服务：渲染设计稿、高亮变更、把点击的节点变成 `#1`、`#2`… |
-| 截图 | 整张画布的 PNG，给能看图的 agent 用 |
+| 截图 | 整张画布或单个画板的 PNG；倍率 0.2–2、默认 0.8，单边最多 8192px |
+
+## 文件与格式
+
+新建的文件是 `.ptr`——同一套 JSON 设计稿的 paintress 风味。已有的 `.pen` 文件照样打开、编辑、渲染，区别只在扩展名。
+
+项目根下有两份文件保证整个项目一致。它们在**注册的项目根**（也就是你 watch 的目录，不是某张设计稿所在的子目录），注册项目时会自动创建，和设计稿一样**应该进版本库**；`paintress_project`（以及查看器返回的 `designSystem`）会给出确切路径，并报告任何会把设计系统拆开的嵌套副本：
+
+| 文件 | 装什么 |
+| --- | --- |
+| `__preset.ptr` | 设计 token（颜色、倒角、间距、字号、字体族）、preset 组与字体注册表 |
+| `__components.ptr` | 可复用组件（标了 `reusable` 的节点） |
 
 ## 环境要求
 
@@ -51,6 +62,7 @@ paintress new <file> [--name n] [--width n] [--height n] [--fill c]
                     [--layout vertical|horizontal|none] [--padding n] [--gap n] [--force]
                                                           新建设计稿（一个空画板）
 paintress info <file>                                     文档摘要
+paintress convert <file.pen> [out.ptr] [--force]         把 .pen 转成 .ptr（源文件不动）
 paintress query <file> [--type t] [--name n|--regex]   条件查询节点
 paintress get <file> <id> [--depth n]                  读取节点子树
 paintress update <file> <id> '<patch-json>'            浅合并更新属性
@@ -59,14 +71,20 @@ paintress delete <file> <id>                           删除节点
 paintress move <file> <id> <parent> [--index n]        移动节点
 paintress batch <file> '<ops-json>'                    一次执行多个操作
 paintress validate <file>                              按格式规格校验
-paintress preset list|set|remove ...                   项目预设（颜色 / 倒角）
-paintress component list|insert ...                    项目组件库
+paintress preset list|set|remove|seed|set-group|remove-group ...
+                                                           token、组与整套起步尺度
+paintress font list|add|remove|default ...               项目字体注册表
+paintress audit <file>                            画谱审计（只读）
+paintress establish <file> [--apply]             提取 token / preset 组（默认只给建议）
+paintress adjust <file> --key k --value v [--apply]  调整画谱（默认只看影响面）
+paintress component list|insert|add ...                 项目组件库
 paintress render <file> <out.html>                     渲染为 HTML
-paintress shot <file> <out.png> [--scale n]            渲染为 PNG
+paintress shot <file> <out.png> [--scale 0.2..2] [--board id|name]  渲染为 PNG（默认 0.8）
 
-paintress web [--port n] [--idle ms] [--daemon]        确保查看器在跑（幂等）
+paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
+                                                       确保查看器在跑（幂等，立刻返回）
 paintress ping | status | stop                         查看器控制
-paintress watch <name> <dir> | unwatch <name>          注册/移除要浏览的目录
+paintress watch <name> <dir> [--depth n] | unwatch <name>  注册/移除要浏览的目录
 paintress attach <name>                                agent 工作期间保持查看器存活
 
 paintress install [client...] [--dry-run]              写入 MCP 配置条目
@@ -77,23 +95,50 @@ paintress mcp-config <client>                          打印单个客户端的
 ## 查看器
 
 ```bash
-paintress web --daemon
+paintress web
 paintress watch demo ./demo
-# 打开 http://localhost:3316/demo
+# 打开 http://localhost:6033/demo
 ```
 
-`paintress web --daemon` 是幂等的：已经在跑就打印那个进程的 `pid` / `port` / `http` 后退出，所以每次开始作画前无条件跑一遍都没问题——永远不会出现第二个实例。前台形式（`paintress web`）同样复用正在跑的查看器，而不是报错；只有它自己真去启动时才会占住终端。要换端口/重启，用 `paintress stop`。
+`paintress web` 是幂等的、且立刻返回：已经在跑就打印那个进程的 `pid` / `port` / `http`，没跑就拉起一个并把查看器窗口开在它上面。所以每次开始作画前无条件跑一遍都没问题——永远不会出现第二个实例；窗口由程序自己开在桌面浏览器里（`--foreground` 让进程占住终端、日志直接可见；要换端口/重启，用 `paintress stop`）。在 WSL 里窗口落在 Windows 的浏览器，不会是发行版里的那个浏览器。
+
+端口不是一个要背下来的常量：它在启动时**选好并报回来**。默认 `6033`；用不了就沿 `6033 → 6133 → 6233` 在 `127.0.0.1` 上跳级，三个都到不了宿主就改绑 `0.0.0.0` 再走一遍同样三个端口（共六个候选，第一个可用的胜出，全灭就带着完整尝试表报错）。WSL 里这条很重要：Windows 可能把端口划给 Hyper-V，此时 `localhost` 转发根本不会建立——发行版里一切正常，人在宿主浏览器里只看到「连接失败」；兜底会把 `http://<wsl-ip>:6033/` 交给你。`http` / `access.url` 字段是权威值：直接用它，不要自己拼。`--port` 钉死一个端口、绝不跳级（被占就是报错），`--bind loopback|all` 钉死绑定面。
+
+agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。它的返回值里带着同一份 `url` / `access`，所以就算查看器落在了兜底端口上，agent 也会把人引到真正能打开的地址。
 
-agent 从 MCP 侧拿到同样的保证：`paintress_viewer` 确保查看器在跑并把当前项目注册进去，MCP server 还会在每次写操作前再确认一遍——于是查看器是在第一次编辑之前就起来的，而不是等人开口。
+设计稿旁边放一份同名 Markdown（`home.ptr` → `home.md`），画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记：这份设计是干什么的、还有哪些待定、对应哪条需求。笔记就是设计稿旁边的一份普通 Markdown——您自己写，或者让 agent 写；面板本身只读。
 
-设计稿旁边放一份同名 Markdown（`home.ptr` → `home.md`），画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记——只读：这份设计是干什么的、还有哪些待定、对应哪条需求。
+右上角的浮动工具条放的是这个项目的设计系统。**预设**是项目里的颜色、倒角、间距和字体值：agent 只写引用（`$color-brand`），不贴裸值；你在这里改一个值，画布立刻变——不用再说「红一点、再蓝一点」。节点还可以用 `preset` 引用一整组属性（谱式），面板里只读展示这些组。**组件**是只读画廊，把 agent 已经做好的可复用组件摊开给你看进度，也让 agent 动手前先来这儿找。版本号旁边有字体徽章：加载了几个 family、缺的那几个用的是什么替代字体，都在它的提示里。
 
-右上角的浮动工具条放的是这个项目的设计系统。**预设**是项目里的颜色和倒角：agent 只写引用（`$color-brand`），不贴裸值；你在这里改一个值，画布立刻变——不用再说「红一点、再蓝一点」。**组件**是只读画廊，把 agent 已经做好的可复用组件摊开给你看进度，也让 agent 动手前先来这儿找。
+画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口，`Ctrl/Cmd+K` 快速切换设计稿。点中节点会打开只读属性面板。多画板文件会显示画板条；选中具体画板后可按 0.5x / 1x / 2x 导出 PNG（1x = 画板设计像素；文件名是 `<稿名>-<画板>@<倍率>x.png`，单边超过 8192px 会等比压回）。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回；每条标记都带文件与节点 id，所以一个短号能落到唯一文件里的唯一元素。
 
-画布操作：滚轮以指针为锚点缩放，空格 / 中键 / 空白处拖拽平移，`Ctrl/Cmd+0` 回到 100%，`Shift+1` 适应窗口。多画板文件会显示画板条。通过 CLI 或 MCP 做的修改会在查看器里高亮，点击会让节点获得短号，agent 用 `paintress_marks` 读回。
+查看器跟着 agent 走，不需要人管：agent 起查看器时窗口自己开在它那个项目上；项目随 agent 来去，带进出场动画。**最后一个项目被收走、或服务被关掉（侧栏 Stop server、空闲退出）时，页面自己倒计时十秒再关窗**——不用人去点标签页的 ×。没人看的浏览器也不再拖着进程不放。
 
 工具条右侧有两个只影响查看的开关。**画布背景**切 Light / Gray / Dark，只改画布区底色，不动界面其它部分（点档位或拖滑块）。**界面语言**在中 / EN 之间切；首次打开跟随浏览器语言，不是中文就是英文。两者都按浏览器记住。注册新项目、或往已跟踪目录里放一个新的设计稿，所有已打开的查看器都会自动刷新，不需要手按 F5。
 
+## 设计系统
+
+一个项目一套事实来源，改一处全项目跟着变，而不是各画各的：
+
+- **Token** 存在 `__preset.ptr`，设计稿里写 `$color-brand`，不贴裸值。种类：`color`、`radius`、`spacing`、`fontSize`、`font`。
+- **Preset 组**把一组 token 引用套到某类节点上；节点写 `preset: "card"` 即参与。
+- **组件**存在 `__components.ptr`；agent 复制一份进来用，不从零重画。
+- **字体**按 family 登记来源（`web` 的 CSS URL、项目内的 `css`/`file`、`system` 系统字体、或只存在于安装包的 `bundle`）；来源无法本地验证时还必须给设计期 `preview`。每次读取都会报告哪些 family 加载了、哪些用了替代。
+
+`paintress_preset seed`（默认 dry-run）一次补齐一套起步尺度——27 个 token、6 个 preset 组和两个网络字体。`audit` 找漂移，`establish` 从重复值里提 token，`adjust` 改动前先给影响面。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `PTR_BROWSER` | 截图与 PNG 导出用的浏览器可执行文件 |
+| `PAINTRESS_HOME` | 状态目录（daemon 注册表、Chromium 字体缓存）；默认 `~/.paintress` |
+| `PAINTRESS_NO_OPEN` | `1` 时不打开浏览器窗口 |
+| `PAINTRESS_NO_AUTO_WEB` | `1` 时 MCP 写操作前不再确保查看器在跑 |
+| `PAINTRESS_NO_WEB_FONTS` | `1` 时跳过内置网络字体（离线 / CI） |
+| `PAINTRESS_PORT` | `ui/` 开发服务器的代理目标端口（默认 `6033`）；端口阶梯跳级时设成查看器实际端口 |
+| `CI` | `true` 等价于 `PAINTRESS_NO_OPEN` |
+
 ## MCP 客户端
 
 `paintress install` 会写入下面这些位置，也可以手动添加。
@@ -124,7 +169,7 @@ paintress mcp-config cursor   # 只打印片段，不改文件
 - `.agents/memory/ARCHITECTURE.md` —— 设计决策与理由
 - `.agents/implementations/` —— 每次变更的记录与实测数据
 
-已有的 `.pen` 设计稿也能直接打开，原样渲染。
+已有的 `.pen` 设计稿也能直接打开，原样渲染；需要时 `paintress convert` 把它转成 `.ptr`。
 
 ## 发版（维护者）