paintress
v0.8.2
Published
Design-document operation layer for AI agents: read, query, edit, render
Maintainers
Readme
安装方式:把本仓库地址贴给您的 agent,让它装 paintress。 需要精确流程的 agent 见文末的安装手册。
这是什么
paintress 是一个给 AI agent 用的界面设计工具。你在对话里说要什么界面,agent 把它画进设计文件,你在浏览器里看到结果——没有画布要拖,也没有设计软件要学。
你点,它改:在查看器里点一下元素,它就得到一个短号(#1),说「#1 改成蓝色」改的就是那一个。
设计稿是项目里的普通 JSON 文件,能 diff、能评审、能提交。
读写由 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_clear_changes、paintress_marks |
| CLI | 同样的操作,外加查看器进程;不接 agent 也能用 |
| 查看器 | 本地 web 服务:渲染设计稿、高亮变更、把点击的节点变成 #1、#2… |
| 截图 | 整张画布或单个画板的 PNG;倍率 0.2–2、默认 0.8,单边最多 8192px |
文件与格式
新建的文件是 .ptr——同一套 JSON 设计稿的 paintress 风味。已有的 .pen 文件照样打开、编辑、渲染,区别只在扩展名。
项目根下有两份文件保证整个项目一致。它们在注册的项目根(也就是你 watch 的目录,不是某张设计稿所在的子目录),注册项目时会自动创建,和设计稿一样应该进版本库;paintress_project(以及查看器返回的 designSystem)会给出确切路径,并报告任何会把设计系统拆开的嵌套副本:
| 文件 | 装什么 |
| --- | --- |
| __preset.ptr | 设计 token(颜色、倒角、间距、字号、字体族)、preset 组与字体注册表 |
| __components.ptr | 可复用组件(标了 reusable 的节点) |
这个根是解析出来的、不是猜的:仓库根的 paintress.json 可以声明({"root": "design"});否则 paintress 会挑 design/、ui/、mockups/ 这类目录,或者设计稿本来就在的当前目录。带着 AGENTS.md、package.json 或 .git 却没有任何设计稿的目录会被拒绝当根——那是代码仓库,注册进去只会在根上落下 __preset.ptr。确实要用该目录时加 --force(工具调用传 force: true)。
环境要求
Node.js 22 及以上。
安装
npm install -g paintress然后把 MCP 条目写进您使用的客户端:
paintress doctor # 查看已装情况、哪些客户端已有条目
paintress install # 写入所有检测到的客户端配置
paintress install pi cursor # 或只写指定的客户端install 只合并 paintress 一条,文件里其他内容保持原样,改动前写 *.bak-<时间戳> 备份;重复执行不会改变任何东西。
CLI
paintress mcp 启动 stdio MCP server
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>' 浅合并更新属性
paintress insert <file> <parent> '<node-json>' 插入子节点
paintress delete <file> <id> 删除节点
paintress move <file> <id> <parent> [--index n] 移动节点
paintress batch <file> '<ops-json>' 一次执行多个操作
paintress validate <file> 按格式规格校验
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 0.2..2] [--board id|name] 渲染为 PNG(默认 0.8)
paintress web [--port n] [--bind auto|loopback|all] [--idle ms] [--foreground]
确保查看器在跑(幂等,立刻返回)
paintress ping | status | stop 查看器控制
paintress watch <name> <dir> [--depth n] [--force] | unwatch <name>
注册/移除要浏览的目录
paintress attach <name> agent 工作期间保持查看器存活
paintress install [client...] [--dry-run] 写入 MCP 配置条目
paintress doctor 查看各客户端配置状态
paintress mcp-config <client> 打印单个客户端的配置片段查看器
paintress web
paintress watch demo ./demo
# 打开 http://localhost:6033/demopaintress 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 也会把人引到真正能打开的地址。
设计稿旁边放一份同名 Markdown(home.ptr → home.md),画布左上角就会出现「笔记」按钮。点开后画布向右收窄、左侧切出笔记:这份设计是干什么的、还有哪些待定、对应哪条需求。笔记就是设计稿旁边的一份普通 Markdown——您自己写,或者让 agent 写;面板本身只读。
右上角的浮动工具条放的是这个项目的设计系统。预设是项目里的颜色、倒角、间距和字体值:agent 只写引用($color-brand),不贴裸值;你在这里改一个值,画布立刻变——不用再说「红一点、再蓝一点」。节点还可以用 preset 引用一整组属性(谱式),面板里只读展示这些组。组件是只读画廊,把 agent 已经做好的可复用组件摊开给你看进度,也让 agent 动手前先来这儿找。版本号旁边有字体徽章:加载了几个 family、缺的那几个用的是什么替代字体,都在它的提示里。
画布操作:滚轮以指针为锚点缩放,空格 / 中键 / 空白处拖拽平移,Ctrl/Cmd+0 回到 100%,Shift+1 适应窗口,Ctrl/Cmd+K 快速切换设计稿。点中节点会打开只读属性面板。多画板文件会显示画板条;选中具体画板后可按 0.5x / 1x / 2x 导出 PNG(1x = 画板设计像素;文件名是 <稿名>-<画板>@<倍率>x.png,单边超过 8192px 会等比压回)。通过 CLI 或 MCP 做的修改会在查看器里高亮(金色呼吸描边;agent 收工调 paintress_clear_changes 即撤掉,无人管也会在最后一次写入三分钟后自己消失),点击会让节点获得短号,agent 用 paintress_marks 读回;每条标记都带文件与节点 id,所以一个短号能落到唯一文件里的唯一元素。
查看器跟着 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 会写入下面这些位置,也可以手动添加。
| 客户端 | 配置文件 | 顶层键 |
| --- | --- | --- |
| Claude Desktop | ~/.config/Claude/claude_desktop_config.json | mcpServers |
| Cursor | ~/.cursor/mcp.json | mcpServers |
| VS Code | ~/.config/Code/User/mcp.json | servers(条目需 "type": "stdio") |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers |
| Codex | ~/.codex/config.toml | [mcp_servers.paintress] |
| pi | ~/.pi/agent/mcp.json | mcpServers |
| OpenCode | ~/.config/opencode/opencode.json | mcp.servers(当前版)或 mcp(旧版;command 是数组) |
paintress mcp-config cursor # 只打印片段,不改文件Skill
skills/paintress/SKILL.md 是给 agent 的简短说明:什么时候用这些工具、作画前先把查看器拉起来(幂等)、#1 怎么映射到节点 id、哪个工具做什么。支持 skill 机制的客户端把它复制进对应目录即可。
文档
specs/PLAN.md—— 路线与未决问题format/spec.yaml—— 设计稿文件格式规格format/README.md—— 格式分层之间是什么关系.agents/memory/ARCHITECTURE.md—— 设计决策与理由.agents/implementations/—— 每次变更的记录与实测数据
已有的 .pen 设计稿也能直接打开,原样渲染;需要时 paintress convert 把它转成 .ptr。
发版(维护者)
发布由 tag 驱动:v* tag 会让 .github/workflows/publish.yml 先校验同一提交的 ci 已通过,再构建、自检包内容并通过 OIDC trusted publishing 执行 npm publish --provenance。测试只在 ci.yml 跑一次,发布不重跑。不要在笔记本上直接发布。
pnpm release patch # 0.3.1 → 0.3.2
pnpm release minor # 0.3.1 → 0.4.0
pnpm release major # 0.3.1 → 1.0.0
pnpm release patch --dry-run # 只打印计划
pnpm release --retag # 发版失败后:把未发布的 tag 移到当前提交重发脚本会拒绝在脏工作区或非默认分支上发版,确认 tag 未被占用,跑类型检查(服务端 + ui)、测试、构建与包内容自检,然后提交 chore(release): vX.Y.Z、打 tag、推分支与 tag,最后等到版本真的出现在 npm 上才算完(CI 绿了但什么都没发出去,会如实报成失败)。
--prepare-only 停在本地提交与 tag;--no-wait 推完就返回;--local 本机直接发布,是应急路径,会跳过 CI 的检查。--retag 是发版失败后的恢复路径:确认该版本还没上 npm 后,把已有 tag 移到当前提交重发(版本号不变);已发布的版本会被拒绝。
许可
MIT
给 AI agent 的安装手册
您是被要求在本机安装 paintress 的 agent。请按顺序执行,并汇报:发现了什么、复用了什么、改动了什么。
先检测。 一台机器上可能有多个 agent,之前的 agent 可能已经全局安装过 paintress 并给自己注册过。再装一份是错误,不是周全。
0. 检测
| 检查项 | 命令 | 含义 |
| --- | --- | --- |
| PATH 上是否已有 | command -v paintress | 已有可用安装 |
| 是否全局安装 | npm ls -g --depth=0 paintress | 通过 npm 装在全局 |
| 是否项目内安装 | npm ls --depth=0 paintress | 装在当前项目里 |
| 客户端配置 | paintress doctor | 哪些 agent 已有条目、状态如何 |
规则:
- 命中任意一项就复用,不要重装,直接进入第 2 步。
- 向用户报告解析到的路径与版本:
paintress --version打印包版本(或用npm ls -g --depth=0 paintress)。 - 只有在全部检查都为空时,才执行第 1 步。
如果安装成功但 command -v paintress 仍然找不到(某些版本管理器需要新开 shell),用完整路径调用,不要因此再装一份:
"$(npm prefix -g)/bin/paintress" doctor1. 安装(仅在检测全空时)
npm install -g paintress如果环境不允许全局安装:
npm install paintress # 项目内安装,之后用 npx paintress ...
npx -y paintress@latest ... # 完全不安装,首次运行较慢优先全局安装:只有全局安装,下一个 agent 才能直接复用。
2. 给「当前所在的 agent」注册 MCP
paintress doctor # 列出检测到的客户端与状态
paintress install --dry-run # 预览将要写入的内容
paintress install <client-id> # 只写当前所在的客户端客户端 id:claude、cursor、vscode、windsurf、codex、pi、opencode。不带参数执行 paintress install 会覆盖所有检测到的客户端。
OpenCode 现在有两套配置布局:install 会跟随文件里既有的布局,新文件按官方当前的 mcp.servers;需要强制时用 --opencode-layout legacy 或 --opencode-layout v2。
写入行为:
- 新增或更新名为
paintress的一条(mcpServers.paintress;VS Code 为servers.paintress;Codex 为[mcp_servers.paintress]); - 文件里其他键、其他 server、既有排版一律不动;
- 替换前在同目录写
*.bak-<时间戳>备份; - 幂等:条目已一致时返回
noop,不写磁盘; - 当
paintress能在 PATH 上解析时写裸命令,否则写可执行文件的绝对路径。
如果当前 agent 不在列表里
条目很小,各家格式几乎一致,直接照抄改写即可:
- 先找到该客户端放 MCP server 的位置——查它自己的文档、
/mcp命令,或「配置 MCP 服务器」菜单项。 - 对照格式:多数是
mcpServers对象,里面command+args;VS Code 是servers加"type": "stdio";OpenCode 的command是数组,放在mcp.servers下(旧版放mcp下)并带"type": "local";Codex 是 TOML 表。 - 打印最接近的片段再改:
paintress mcp-config cursor # JSON,顶层 mcpServers
paintress mcp-config vscode # JSON,顶层 servers + type: stdio
paintress mcp-config opencode # JSON,mcp.servers + command 数组
paintress mcp-config codex # TOML 表想让某个客户端成为内置支持(doctor、install 都能覆盖),只需在 src/integrations/clients.ts 里加一条配置:id、label、format、rootPath,以及可选的 typeValue / commandForm / extraFields 和 configPath(home, platform, env),再在 test/integrations.spec.ts 加一个测试。其他文件都不用动。
3. 安装 skill(建议)
mkdir -p <技能目录>/paintress
cp "$(npm root -g)/paintress/skills/paintress/SKILL.md" <技能目录>/paintress/SKILL.md使用您的 harness 真正读取的技能目录(~/.pi/agent/skills/、~/.claude/skills/、.cursor/skills/ 等)。如果 harness 没有 skill 机制,把该文件读入上下文一次,并记住工具清单。
4. 验证
paintress doctor # 条目存在、命令可解析
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}\n' | paintress mcp第二条命令应当返回包含 "serverInfo": {"name": "paintress", …} 的 result。会话重启后,对任意设计稿调用 paintress_doc_info 是一次端到端验证。
5. 多 agent 规则
- 一份全局安装服务本机所有 agent,不要为每个 agent 复制一份。
- 每个 agent 只添加自己的配置条目;不要重写其他 agent 的文件,也不要删除不是自己添加的条目。
- 如果
doctor显示noop,说明已有人正确注册过——就此停下并说明情况。 - 汇报格式:复用 / 新装 / 注册(哪个客户端)/ 跳过(原因)。
6. 卸载
npm uninstall -g paintress然后从各客户端配置里删掉 paintress 条目,或恢复同目录下最新的 *.bak-<时间戳>。
