npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

paintress

v0.8.2

Published

Design-document operation layer for AI agents: read, query, edit, render

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/demo

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 也会把人引到真正能打开的地址。

设计稿旁边放一份同名 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" doctor

1. 安装(仅在检测全空时)

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 不在列表里

条目很小,各家格式几乎一致,直接照抄改写即可:

  1. 先找到该客户端放 MCP server 的位置——查它自己的文档、/mcp 命令,或「配置 MCP 服务器」菜单项。
  2. 对照格式:多数是 mcpServers 对象,里面 command + args;VS Code 是 servers 加 "type": "stdio";OpenCode 的 command 是数组,放在 mcp.servers 下(旧版放 mcp 下)并带 "type": "local";Codex 是 TOML 表。
  3. 打印最接近的片段再改:
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-<时间戳>。