name: codesign-json-to-vue description: 将腾讯 CoDesign 设计文件（screen meta JSON + preview 预览图）转换为本项目 Vue3 响应式页面，达到 95% 以上像素精度与 100% 组件覆盖。适用场景：处理 CoDesign inspect URL、JSON meta 文件、preview 图片、design file 设计稿，或需要精确的设计稿转代码并使用项目模板组件时。

Codesign JSON → Vue（本项目）

概览

使用 src/components/templates 的模板组件生成业务页面（src/views/**），目标是 95%+ 像素精度 与 100% 组件覆盖。
关键原则：containerRect 只用于基准尺寸/间距标定，不得写死宽度/列宽；最终布局必须自适应（minmax(0, 1fr) / auto-fit / clamp()）。禁止用 rect。
Manifest 分层：核心 component-manifest.json 是唯一真相源；component-manifest.derived.json 仅用于调试/派生信息。

默认策略（无需确认）

除非用户明确要求修改，否则直接采用以下默认值，不再询问：

• 输出目录：默认 ./designs
• 左侧侧边栏：默认忽略，仅实现右侧主内容
• 复杂页面布局：默认采用（外层模板容器 + 内部自定义网格，网格必须自适应，禁止固定列宽/总宽）
• 流程豁免：默认跳过 worktree 与 TDD，改为手动验证

首次运行配置（Step 0.5: 项目上下文采集）

运行两个索引脚本生成项目上下文（只需首次执行一次，组件库变更后重新执行）：

# 1. 组件索引：扫描 Vue SFC → 提取 Props/Slots/Emits/依赖 → component-index.json
python3 ~/.codex/skills/codesign-json-to-vue/scripts/build-component-index.py \
  <project_root> --out designs/component-index.json

# 2. Design Token 提取：扫描样式 → 挖掘事实 token → design-tokens.json
python3 ~/.codex/skills/codesign-json-to-vue/scripts/extract-design-tokens.py \
  <project_root> --out designs/design-tokens.json

输出文件：

• component-index.json — 组件 Props/Slots/Emits + role→组件映射表（AI 选组件的依据）
• design-tokens.json — 颜色/间距/圆角/字号 token + 反向查找表（AI 生成代码时用变量而非硬编码）

必需输入（meta + preview + lite/style）

必须使用预览图进行语义校验：

• 预览图来自 screen API 的 image.url 或 cdn_host + preview_path
• 预览图用于判定：图表/表格、内背景块、图例/按钮组位置等
• 预览图下载与压缩规则详见 references/workflow.md
• 脚本默认优先下载压缩预览图，失败自动回退原图

快速开始（一条命令）

需要 Token 环境变量，不要写入仓库。

python3 ~/.codex/skills/codesign-json-to-vue/scripts/codesign_pipeline.py \
  "https://codesign.qq.com/app/design/<design_id>/<screen_id>/inspect"

默认读取 token：<project>/.codesign_token 或 <project>/designs/.codesign_token。

输出命名规则（默认输出目录为 <project>/designs）：

{name}.{object_id}.json
{name}.{object_id}.lite.json
{name}.{object_id}.style.json
{name}.{object_id}.preview.<ext>

备注：当名称包含任何非 ASCII 字符时，safe_name 会回退为 screen。

可选产物（需手动执行 Step 3 脚本）：

retrieval-results.json
style-extract.json
spacing-tokens.json
component-manifest.json
component-manifest.derived.json
batch-retrieve.sh

执行流程摘要（必须严格遵守）

原则：能让 AI 直接做的就让 AI 做，脚本只用于 AI 不擅长的确定性计算（像素级坐标查找、节点树遍历、样式提取）。

| 步骤 | 执行方式 | 执行者 | AI 推断能力 | |------|----------|--------|-------------| | Step 1 下载原始数据 | codesign_pipeline.py | ⚙️ 脚本 | — | | Step 2 精简 JSON | simplify-design.py | ⚙️ 脚本 | — | | Step 3.1 视觉 AI 组件识别 | 看预览图 + 文本节点列表 | 🤖 AI | 同容器多组件识别 | | Step 3.1.5 锚点校验 | 读 index.text 逐条核对 | 🤖 AI | 幻觉/错别字修正 | | Step 3.2 锚点对齐 | 逐个调用 search-region.py | 🤖 AI 编排 | 低置信度重试策略 | | Step 3.2.5 容器冲突修复 | 检测 → 语义分组 → rect union | 🤖 AI 推断 | vision description 引导 + 多层嵌套递归 | | Step 3.3 样式提取 | extract-component-styles.py | ⚙️ 脚本 | — | | Step 3.4 间距推断 | 读取 containerRect 计算 | 🤖 AI | clamp() 容差计算 | | Step 3.5 组装 manifest | build-component-manifest.py | ⚙️ 脚本 | — | | Step 4 模式与布局 | 推断 grid/flex 策略 | 🤖 AI | rectPage 坐标聚类 | | Step 5 组件映射 | 三级推断策略 | 🤖 AI 推断 | L1 roleMapping / L2 语义匹配 / L3 无匹配决策树 | | Step 6 生成 Vue | 生成响应式 SFC | 🤖 AI 推断 | 布局推断 + token 替换 + mock data + 组件组合 | | Step 7 验证 | 三轮 Gate 检查（13 项） | 🤖 AI 推断 | 结构6 + 语义4 + 代码3 → 修复建议 + 回归检查 |

⚠️ 禁止行为：AI 不得跳过脚本步骤自行计算像素级数据（如自己算样式而不跑 extract-component-styles.py），也不得在 AI 决策步骤中机械套用模板而不做语义判断。

核心原则

1. Block 先行：先切 Block，再在 Block 内处理；禁止跨 Block 联合计算 grid/gap/列数
2. containerRect 仅推断：用于基准尺寸/间距标定，禁止在主布局中写死宽度/坐标
3. 自适应布局：最终必须响应式（minmax(0, 1fr) / clamp()），禁止固定列宽
4. 100% 覆盖：所有组件必须识别并 rescue，无孤儿
5. 语义流优先：DOM 顺序按语义流，不按坐标
6. AI 智能推断：Step 6 由 AI 读取 manifest，结合项目组件库智能选择组件模板

完整工作流、硬性规则、脚本依赖详见：references/workflow.md
组件映射详见：references/project-mapping.md
故障排查详见：references/troubleshooting.md

Red Flags（出现即停止）

• 未做 Block 粗切就开始布局
• 跨 Block 联合计算 grid/gap
• 使用 rect 或固定宽度写主布局
• overlay/modal 进入 base DOM
• Orphan 未 rescue
• 使用文字箭头替代 SVG
• 图表区域隐藏 ActionGroup

更多错误排查详见：references/troubleshooting.md

脚本与资源

核心脚本（仅保留 AI 不擅长的确定性计算）：

• scripts/codesign_pipeline.py — Step 1: 一键下载 meta JSON + preview 图
• scripts/simplify-design.py — Step 2: 精简 JSON → lite.json + style.json
• scripts/search-region.py — Step 3.2: 单个锚点 → lite.json 精确坐标（AI 逐个调用）
• scripts/extract-component-styles.py — Step 3.3: 样式提取
• scripts/build-component-manifest.py — Step 3.5: 组装 manifest
• scripts/build-component-index.py — Step 0.5: 扫描 Vue SFC → component-index.json
• scripts/extract-design-tokens.py — Step 0.5: 扫描样式 → design-tokens.json

辅助脚本（按需使用）：

• scripts/codesign_utils.py — 公共工具模块
• scripts/codesign_preview_download.py — 独立预览图下载器
• scripts/slice_preview.py — 长页面切片（Height > 2000px 时使用）
• scripts/merge_vision_results.py — 合并多片识别结果
• scripts/manifest_lib/ — manifest 构建子模块

已降级为 AI 直接执行（脚本仍可用作备选）：

• scripts/validate-anchors.py — 锚点校验（AI 直接读 index.text 更快更灵活）
• scripts/compute-spacing.py — 间距计算（AI 直接从 containerRect 计算）
• scripts/verify-output.py — Gate 检查（AI 做 13 项完整检查，脚本只覆盖 4 项）

参考文档：

• references/workflow.md - 完整工作流与脚本依赖
• references/project-mapping.md - 组件映射与模板
• references/vision-prompt.md - 视觉 AI 组件识别 Prompt 模板
• references/troubleshooting.md - 常见问题与解决

快速参考

一键启动：

python3 ~/.codex/skills/codesign-json-to-vue/scripts/codesign_pipeline.py "<inspect-url>"

易错清单（必须避免）：

• 禁止隐藏图表的操作按钮组（下载/截图/全屏必须保留并验证）
• 趋势箭头优先使用项目资源目录中的 SVG，找不到时降级使用 Unicode 箭头（↑ ↓）
• 卡片样式必须从 style.json 还原（背景/圆角/字体/分隔线）
• 样式覆盖必须按项目既有写法确保生效无孤儿
• ✅ 保留图表 ActionGroup
• ✅ 使用项目 SVG 箭头

常见错误：

// ❌ 错误
const width = result.rect[2];  // 过大
grid-template-columns: 316px 316px 316px;  // 固定宽度

// ✅ 正确
const width = result.containerRect[2];  // 仅推断
grid-template-columns: repeat(3, minmax(0, 1fr));  // 自适应