Skip to content

v0.5.2

Choose a tag to compare

View all tags
@LoktLin LoktLin released this 08 Oct 05:24
· 23 commits to main since this release
v0.5.2
53fc318

中文 | English

更新说明 · v0.4.4 → v0.5.2（汇总）

这一段四个版本此前都没有单独发过 Release，所以这里把它们合成一份。
只想看最新一版 → 直接看 v0.5.2；想知道这段时间到底改了什么 → 往下读。

版本 一句话
v0.4.4 把 README 同步到 npm 页面（补徽章 + 安装方式）
v0.5.0 注入重写：让 AI「知道该用哪个工具」+ 结果补全（间距表 / 双单位 / rgba）
v0.5.1 修两处画板坐标系的 bug + 列表尺寸标「预览」
v0.5.2 清理公开材料里的真实项目名（行为零变化）

新增功能

（这一段最有价值的部分，来自 v0.5.0）

  • SYSTEM_HINT 重写（5 行 → 21 行）：给 AI 一张工具决策树 ——
    还原大块布局 / 对圆角 / 查分割线 → lanhu_read_blocks；要某区域精确数值（含间距）→
    region + gapMaxDistance；坐标映射到自绘坐标系 → mapBox/toBox；只要统计 → format=tokens；
    改完前端要验收 → lanhu_verify_blocks。
    并明确禁掉那条弯路：「别 summary 不够就转 format=full 再自己写脚本解析」。
    另含换算（rpx = px × 750 ÷ 画板宽，不写死 ×2）、以稿为准（字重 400 就是 400、半透明按 alpha 别换实色、
    切图块没有填充也没有圆角但尺寸要还原）、溯源（记 version）、定位（贴整条链接 + 项目档案）。
  • 「间距一览」段（read_blocks 末尾，可直接抄 CSS）：块间最近边距 + 方向（↕/↔），
    外加一类**「齐平」**（两条边重合）—— 后者是「说明块底 ≡ 头像底」那种关系，单靠间距给不出。
  • 色值直出两种形式：#574af4@10% (rgba(87, 74, 244, 0.1)) —— 原串便于回查 + 可直接粘贴。
  • 双单位输出：120×152px / 240×304rpx，换算比按画板宽度算、表头写明基准。
  • 尾注：≈5.52KB；本稿 21 块 + 一行「下一步该用什么」。
  • 标题行带 meta：# 示例弹窗（375×812） ｜version=88e0aaa6｜更新于 2026-09-17（拿不到就不打，不许编）。

体验优化

  • list_designs 的尺寸标注为「预览」（v0.5.1）：列表接口返回的是缩略图尺寸（实测 187.5 ↔ 真实 750、
    480 ↔ 1920，常见 ¼）。插件内部算 rpx 一直用真实画板宽（没错），
    但 AI 若拿列表尺寸自己换算会算错比例 —— 而这是实测语料里 77% 的稿都长的样子。
    现在三处同时标注：列表行标 （预览） + 工具描述 + SYSTEM_HINT 警告。
  • README 同步到 npm 页面（v0.4.4）：22 条文档链接改成 GitHub 绝对地址（相对路径在 npm 上会 404）、
    顶部加 npm / 许可 / Node 徽章、files 带上 docs/ 与 CHANGELOG.md（文档随包走）。
  • 间距段的口径（v0.5.0，按省上下文调过并写在表头）：封顶 24 行 · 按距离从紧到松排 · 贴边 0px 不计入 ——
    否则 610 层的大稿会出 315 条「文字碎片紧挨着」的 0px 行，把真正的竖向节奏挤出前几行。

问题修复

一处病根连续复发 —— 全都出在「坐标系混用」上（v0.5.0 与 v0.5.1）：

  • ⭐ 画板被当成元素：画板自己进了候选集 → 间距表冒出 12279px 的垃圾数字（而该稿画板对角只有几百 px）。
  • ⭐ 画板内边距跨坐标系（影响所有画板不在原点的稿）：画板自身的 x/y 是画布绝对坐标（实测 x=14599），
    而子层是画板相对坐标（x=0）—— 代码却直接相减，于是深度 1 的层内边距全成了 -14599 这种数。
    修后与独立手算逐位一致（0/287/1705/163）。
  • ⭐ 间距一览没排除画板（depth 0）：上一版只挡住了 summary 那条链，renderGapDigest 这条漏了 → 在唯一收口处过滤。

代码里留了一句给后来者：「新加几何计算时先问一句：这堆元素的坐标系一致吗？」

另三个真 bug（v0.5.0 / v0.5.1）：

  • 间距关系被静默丢掉：geometricGaps 的「每方向只留最近一条」是按 id 做键的 ——
    调用方不给 id（或 id 重复，如 Figma 的 I37:2804;3）时所有元素挤在同一个键上，
    大部分关系被丢掉（4 元素夹具本该 5 条只出 2 条，看着像「这里就这点间距」）。
  • 齐平段出现「自己跟自己对齐」：真身是父子（子层是父层的 :shadow、几乎撑满）再叠一层渲染歧义
    （名字截到 22 字后两个元素撞成同一前缀）→ 新增 sameElement() / isAncestor() 排除 + 显示名去歧义。
    11 条噪声 → 6 条真关系。
  • 更新时间是 RFC-2822 原文（Thu, 17 Sep 2026）被切成残句 → 复用现成的 parseRfc2822 归一。

其他变更

  • 验证方式（这一段的做法）：① 全量真机覆盖 —— 6 团队 / 31 项目 / 1437 张设计稿 / 12 份原型；
    ② 修复后做了全量回归 —— 同一批稿重跑（1219 张对账），那条 gap>diag(5987>551) 消失、0 新增异常；
    ③ 三项此前未闭环的验证补齐（真机证据）：region 双单位在 w=1920/750/375 上给出 ×0.39 / 1:1 / ×2、
    找到了原生「无填充无圆角切图块」并带反证、齐平段独立复算 漏报 0 / 多报 0。
  • 自检 611 → 663 项；文档绊线 76 → 103 项（后者新增「发布说明中英分段顺序 + --- 位置」的结构断言 ——
    这条上线后第一条咬到的就是我自己写的错版）。
  • v0.5.2 清理公开材料：全量扫期间写进注释 / 发布说明的几个真实项目名换成中性说法
    （数值 / 尺寸 / 坐标 / 结论一字未改），并连同 git 历史（提交信息 + 每个提交的 tree）一起清理，
    v0.5.0 / v0.5.1 两个 tag 同步前移。
  • 如实记录的未闭环：read_blocks 全量 1437 的收尾；齐平对账样本 3 张偏小。

Full Changelog: v0.4.4...v0.5.2

Update notes · v0.4.4 → v0.5.2 (combined)

None of the four versions in this range ever got its own Release, so they are combined here.
Only interested in the newest? Read v0.5.2. Wondering what actually changed? Keep reading.

Version In one line
v0.4.4 Synced the README to the npm page (badges + install instructions)
v0.5.0 Injection rewritten so an AI knows which tool to reach for, plus result completion (spacing table / dual units / rgba)
v0.5.1 Fixed two artboard coordinate-system bugs and labelled list sizes as "preview"
v0.5.2 Removed real project names from public materials (zero behaviour change)

New Features

What v0.5.0 brought — the most valuable part of this range:

  • SYSTEM_HINT rewritten (5 lines → 21): a tool decision tree — block layout / radii / dividers →
    lanhu_read_blocks; a region's precise numbers (including spacing) → region + gapMaxDistance; mapping artboard
    coordinates into your own system → mapBox/toBox; statistics only → format=tokens; acceptance after coding →
    lanhu_verify_blocks. It also explicitly forbids the old detour: "do not fall back to format=full and write your
    own parser." Plus unit conversion (rpx = px × 750 ÷ artboard width, never a hardcoded ×2),
    follow the artboard (weight 400 is 400, keep the alpha instead of a similar solid, image blocks have neither fill
    nor radius but their size still matters), provenance (record version) and locating (paste the whole link).
  • A "spacing at a glance" section (appended to read_blocks, ready for CSS): nearest edge distance and direction
    (↕/↔), plus a "flush" category (two edges coinciding) that spacing alone cannot express.
  • Colours in both forms: #574af4@10% (rgba(87, 74, 244, 0.1)).
  • Dual units: 120×152px / 240×304rpx, derived from the artboard width with the basis stated in the header.
  • Footer: ≈5.52KB；本稿 21 块 plus a one-line "what to use next".
  • Title line carries meta: # 示例弹窗（375×812） ｜version=88e0aaa6｜更新于 2026-09-17 (omitted, never invented, when unavailable).

Improvements

  • list_designs labels its sizes "preview" (v0.5.1): the list endpoint returns thumbnail dimensions
    (187.5 vs a real 750, 480 vs 1920 — commonly ¼). The plugin has always computed rpx from the real artboard
    width     (correct), but an AI deriving the ratio from the list would get it wrong — and that is what 77% of the
    artboards in the corpus look like. Flagged in three places now.
  • README synced to the npm page (v0.4.4): 22 documentation links became absolute GitHub URLs (relative ones 404 on
    npm), badges added, and files now ships docs/ and CHANGELOG.md.
  • Spacing rules (v0.5.0, tuned for context economy and stated in the header): capped at 24 rows · sorted tightest
    first · flush (0px) excluded     — otherwise a 610-layer artboard emits 315 zero-pixel rows and buries the real rhythm.

Bug Fixes

One root cause, recurring — mixed coordinate systems (v0.5.0 and v0.5.1):

  • ⭐ The artboard was treated as an element, entering the candidate set and emitting a 12279px garbage distance
    where the artboard's diagonal is only a few hundred pixels.
  • ⭐ Artboard padding spanned two coordinate systems (affects every artboard not at the origin): an artboard's own
    x/y are canvas-absolute (measured x=14599) while its children are artboard-relative (x=0) — yet the code
    subtracted them directly, so every depth-1 layer's padding came out as -14599. After the fix it matches an independent
    hand calculation digit for digit.
  • ⭐ The spacing section did not exclude the artboard (depth 0): the previous version guarded the summary chain but
    missed renderGapDigest → filtered at its single choke point.

A note was left in the code: "when adding geometry, first ask whether these elements share a coordinate system."

Three more real bugs (v0.5.0 / v0.5.1):

  • Spacing relations were silently dropped: geometricGaps keyed "nearest per direction" by id, so when the caller
    supplied no id (or ids collided, e.g. Figma's I37:2804;3) every element collapsed onto one key and most relations
    vanished (a 4-element fixture that should yield 5 relations yielded 2 — it looks like "that is all the spacing there is").
  • The flush section paired elements with their own edges: the real cause is parent/child (the child is the
    parent's :shadow, nearly filling it) compounded by a rendering ambiguity (names truncated to 22 characters collide
    into one prefix) → sameElement() / isAncestor() now run before any comparison, and names are disambiguated.
    11 noisy rows → 6 real relations.
  • The updated-at value is raw RFC-2822 (Thu, 17 Sep 2026) and was sliced into a fragment → normalised via the
    existing parseRfc2822.

Chores

  • How this range was verified: ① full real-machine coverage — 6 teams / 31 projects / 1437 artboards /
    12 prototypes; ② a full regression after the fixes — the same artboards re-run (1219 reconciled), that
    gap>diag(5987>551) anomaly gone with 0 new anomalies; ③ three previously unclosed verifications closed
    (with real-machine evidence): region dual units emit ×0.39 / 1:1 / ×2 on 1920/750/375-wide artboards, the native
    "image block with neither fill nor radius" was found with a counter-proof, and the flush section reconciled
    0 missed / 0 extra.
  • Self-check 611 → 663 assertions; doc tripwires 76 → 103 (the latter gained structural assertions for the
    release-note halves and the --- position — and the first mistake it caught was my own).
  • v0.5.2 sanitisation: several real project names written into comments and release notes during the sweep were
    replaced with neutral wording (every number, dimension and conclusion untouched), and git history was cleaned too
    (commit messages and every commit's tree), with the v0.5.0 / v0.5.1 tags advanced accordingly.
  • Honestly recorded as still open: the flush reconciliation sample is only 3 artboards; the full 1437-artboard
    read_blocks sweep was still finishing.

Full Changelog: v0.4.4...v0.5.2

Assets 2
Loading