GitHub：
rebornace/dsh-tracescope
｜ Gitee 镜像：
RebornAce/dsh-tracescope
｜ npm：
@rebornace/dsh-tracescope·
@rebornace/tracescope-core·
@rebornace/tracescope-mcp（当前版本
0.2.5）
上一篇分享了 TraceScope 的第一个主能力 ——功能影响分析（从 Git Diff 算出 “要测哪些”）。这次聊聊新加的第二个主能力：设计差异分析—— 以 Figma / 蓝湖设计稿为真源，对代码实现做静态对账，直接告诉你 “UI 差在哪”。
为什么做这个
“这版 UI 按设计稿做了吗？”—— 问出这句话的瞬间，一场人工找茬就开始了：
打开设计稿，再打开 App，一个页面一个页面肉眼比对
间距差 4px、色值差一点、字号差一号、圆角阴影模糊对不上…… 全凭眼睛和感觉
一套设计稿要横跨 Android /iOS/ 小程序 / Web，同一处还原问题要复述好几遍
比对结果就是几张截图加几行字，不沉淀、不可追溯，开发改完还要再来一轮
更扎心的是还原度问题通常提测后才被发现—— 返工成本最高的时候。
问题本质和 “波及面无法确定” 一样：设计稿是唯一的 “真源”，但 “实现与真源差在哪” 这件事，靠人眼不可靠、不可复用、不可举证。
TraceScope 的解法：把设计稿（Figma / 蓝湖）和代码实现同时解析成结构化的树，做静态对比，输出可定位、可勾选、可提交缺陷的差异清单。
它能干什么
现在插件有两条并列的主能力：
| 能力 | 输入 | 输出 |
|---|---|---|
| 功能影响分析 | 稳定版 ↔ 待测版（本地 Git 或云效代码接口） | 直接变更 + 静态波及清单，可标注、截图、导出、提单 |
| 设计差异分析 | Figma / 蓝湖设计稿 + 代码仓页面 | 静态差异清单 + 设计对照图高亮，可 AI 协助写回、导出、提单 |
两条能力共用侧栏的协作平台配置（云效 / GitHub / GitLab / Webhook），下文重点讲新的设计差异分析。
设计差异分析怎么做
1. 以设计稿为真源，静态对比（不是运行时截图）
关键设计是design-only：解析设计稿的结构树 + 解析代码实现的结构树，两棵DesignDoc直接对比。
不依赖 App / 浏览器运行时截图，不需要启动工程、不需要真机
对比结果可复现，也能在模型对话里跑
主路径 API：
POST /tracescope/v1/design-compare
2. 页面发现覆盖
粘贴设计稿链接后，插件扫描代码仓，按平台栈发现页面并尝试匹配：
| 平台 | 适配器（摘要） |
|---|---|
| Android | XML / Compose / View |
| iOS | Xib / SwiftUI / UIKit |
| 跨端 | Flutter、React Native、Harmony ArkUI、uni-app、Taro |
| Web | HTML / React / Vue / Svelte / Angular |
| 小程序 | WXML / AXML / TTML / Swan 等 |
| 其他 | .NET MAUI XAML |
匹配不理想时可以手动指定代码文件，或让 AI 重新推荐。
3. 对比分层 L0 → L3
| 层级 | 含义 |
|---|---|
| L0 | 设计指纹 ↔ 代码页匹配（可接受推荐，也可指定文件 / AI 重新推荐） |
| L1 | 属性级静态树对比（DesignDoc↔DesignDoc） |
| L2 | 启发式：文案 / 控件规模等（无精确几何树时） |
| L3 | AI 协助分析：生成源码阅读清单与提示词，结论可写回侧栏 |
4. 属性级对比能对什么
L1 阶段不只是 “两张图叠一起”，而是把两边属性逐一掰开对：
几何与布局：间距、尺寸、flex / 约束、网格轨道、宽高模式（FIXED / HUG / FILL）、
aspect-ratio、自适应换行视觉：色值（含颜色 token / 主题色改写）、渐变、圆角、描边（含分边描边）、阴影 / 内阴影多叠层、模糊 / 背景模糊、混合模式
文字：字号（含 dp /sp/rpx /
cqw等单位换算）、字重、行高、字距、装饰、截断、对齐、首行缩进状态：可见性、透明度、变换（rotate /scale/skew /translate）、zIndex、mask /clip-path、
overflow资源：
@color别名链、styles.xml、AppColors.xxx、R.color.xxx、{StaticResource}、字体 token、颜色 scheme / 主题树
用一句大白话：能写进 CSS / XML / Compose / SwiftUI 的属性，基本都能进对比。
5. 适配器深度增强（enrichment 插件化）
主对比路径对所有栈一视同仁—— 有toDesignDoc就上 L1，否则启发式。个别栈需要超出通用解析的能力时，以enrichment 插件形式挂载，不在主路径里写死分叉：
目前实现：android-xml—— 静态布局引擎（按设计稿视口量测）、依赖闭包指纹、Adapter 绑定动态列表 item 还原、动态区域文案投影
侧栏有「适配器深度增强」开关（默认开启，全局记住）；关了则全栈统一走属性级 / 启发式，更快、粒度更一致
这样后续给 Compose /iOS/ Flutter 补布局引擎时，只是新增一个 enrichment 文件，主路径不用动。
6. AI 协助分析（L3）
确定性对比给出基线，AI 负责 “读代码、补推理”：
tracescope_start_visual_review创建任务 →tracescope_get_design_snapshot按需拉设计树快照 →tracescope_publish_visual_findings把结论写回侧栏按当前页面适配器生成源码阅读清单，不误走其它栈的依赖闭包
写回时按设计树补全 / 纠正
nodeId，提示词明确禁止臆造 id；静态差异摘要带上真实节点 id
7. 侧栏能力
粘贴设计稿链接 + 凭证（Figma Personal Access Token，蓝湖浏览器 Cookie），常用链接可保存 / 点选 / 删除
扫描后出卡片：界面对比、指定代码文件、AI 协助分析、重新推荐文件
结果板：设计对照图、差异清单多选定位高亮、关联文件列表
复制差异 / 提交缺陷 / 导出报告 —— 协作配置与影响分析共用一套
凭证按代码仓库记忆，切仓库不互相清空；Figma 与蓝湖分键保存
顺带：影响分析加速 + MCP 工具面补齐
这次迭代不只加了新能力：
功能影响分析大幅加速：依赖索引从全量扫描改为路径 / 符号哈希查找，约 2000 个源文件时索引构建从十几秒降到几十毫秒；跳过
node_modules/dist/.next/Pods等目录，同一 commit 进程内缓存MCP 与 DSH 工具面完全对齐：执行层抽到
@rebornace/dsh-tracescope/agent-api，DSH Host 工具和 MCP 共用同一套实现，任意 MCP 客户端都能独立走完 “分析 → 写回” 流程
MCP 工具一览（共 11 个）：
| Tool | 说明 |
|---|---|
tracescope_open_panel | 打开本机可视化面板 |
tracescope_list_commits | 列出仓库提交 / 引用 |
tracescope_get_diff | 分页拉取统一 diff |
tracescope_analyze_impact | 确定性影响面分析 |
tracescope_create_handtest_job | 创建手测对话任务并返回提示词 |
tracescope_publish_handtest | 写回手测清单 |
tracescope_start_visual_review | 创建设计差异分析任务 |
tracescope_get_design_snapshot | 按需拉取设计树快照 |
tracescope_publish_visual_findings | 写回设计差异结论 |
tracescope_start_page_rematch | 创建设计页 ↔ 文件匹配任务 |
tracescope_publish_page_rematch | 写回文件匹配推荐 |
架构设计
@rebornace/tracescope-core ← 确定性分析引擎（影响面 + 设计差异） @rebornace/dsh-tracescope ← DSH 插件：Host API + 右侧栏 UI + agent-api @rebornace/tracescope-mcp ← MCP Server（与 DSH 工具面一致） packages/.../design-enrichment/ ← 栈级深度增强插件（不写死主路径分叉）设计原则延续上一篇：所有能力都能经 MCP 触达，DSH 插件的独特价值是嵌入式 UI，不是独占业务逻辑。
另外 0.2.5 起插件支持自更新，不依赖社区插件市场：Host 同域接口对照npmmirror → npmjs的latest，安装优先走官方插件管理器，未装市场也功能完整。
安装与使用
环境：Node.js>= 20，推荐官方 DeepSeek Harness 桌面端。
dsh plugin--profiledesktop remove @rebornace/dsh-tracescope dsh plugin--profiledesktopadd@rebornace/dsh-tracescope安装以 npm latest 为准（社区市场卡片版本可能滞后）。装好后进侧栏 TraceScope，插件详情页有「更新」按钮与更新状态卡，可一键跟进后续版本。
设计走查日常流程
打开 TraceScope 侧栏，选「设计差异分析」
粘贴 Figma / 蓝湖设计稿链接，填凭证（Figma Token 或蓝湖 Cookie）
扫描代码仓页面，自动匹配或「指定代码文件」
看差异清单，点差异在对照图上高亮定位；可开「AI 协助分析」
逐条确认，或复制差异 / 提交缺陷 / 导出报告
已知限制
对比是静态的，不替代真机 / 浏览器运行时截图比对（例如动效、真机渲染差异仍需人工）
各栈 L1 属性覆盖面不一致：“能发现页面” 不等于 “与 Android XML 增强同级”
深度增强目前仅 android-xml 有实现；其它栈开关开着也不会凭空多出布局引擎
设计对照图依赖 Figma / 蓝湖出图，链接过期或凭证失效时需重新对比
后续规划
友盟 Adapter、Android USB 录制、浏览器扩展录制（仓库内已有 scaffold，未进 0.2.x 交付）
更多栈的 enrichment（在能力齐平前提下按需扩展，而非主路径特化）
最后
确定性对比保证下限（不会漏），AI 协助提升上限（能读源码补推理），嵌入式 UI 让走查全程在 DSH 内完成，协作平台把差异直接变成缺陷单。如果你在用 DeepSeek Harness，或者正被 “UI 还原度对账” 折磨，欢迎试用和反馈 —— 开源项目，MIT 协议，PR 欢迎。
相关链接
