WireCue

WireCue 是一个运行在 VS Code 内的轻量线框原型系统，用于用户与 Copilot / Agent 快速交流页面结构、布局关系和修改意见。

.wirecue 文件是画布的唯一真实数据源（普通 JSON，可直接读写、版本控制）。
WireCue Custom Editor 把文件渲染为线框画布。
用户在画布元素上创建评论，评论保存在相邻的 .wirecue.comments.json 文件中。
Agent 通过三个 Language Model Tools 读取/解决评论、打开画布，并直接编辑 .wirecue 文件。
文件被修改后画布自动刷新。

功能（MVP / P0）

渲染 .wirecue JSON 为 DOM 线框画布。
支持 flex、grid、absolute 三种容器布局。
支持固定尺寸、fill、hug、精确 padding / gap / margin / 对齐 / 换行。
画布缩放、平移、元素选择、适应视口。
在选中元素上创建评论；评论状态 open / resolved。
独立的 Comments 侧栏（按画布分组，点击定位元素）。
文件被外部修改后自动刷新；JSON 无效时保留最后有效画布并显示错误，不覆盖原文件。
三个 Agent 工具：wirecue_get_comments、wirecue_resolve_comments、wirecue_open_canvas。
新建示例画布、校验当前画布命令。

功能（P1）

Elements 元素树：画布内右侧面板展示元素层级，点击树节点在画布中选中；画布选中同步高亮。
Properties 属性面板：同一面板编辑选中元素的尺寸、位置、边距、样式、布局与链接，改动直接写回 .wirecue 文件（可撤销）。
画布拖拽：absolute 元素可直接拖动改位置；选中固定尺寸元素出现缩放手柄（右/下/右下角）拖动改宽高。
Pages 多页面：面板列出工作区内全部画布，显示各自外链数与未解决评论数，点击打开。
页面连线与跳转：元素可加 link: { page, elementId? }（如 examples/course-detail.wirecue）；画布中带链接的元素出现 → 徽标，点击跳转到目标页并可选定位元素。
评论回复 / 指派 / 历史：评论支持回复、指派对象，创建/解决/重开/回复/指派均记录历史；弹层与评论面板均可操作。
导出 HTML / PNG：WireCue: Export Canvas as HTML 生成自包含 HTML（可在浏览器打开分享）；WireCue: Export Canvas as PNG 由画布渲染生成 PNG。
统一面板（P2 重构）：属性/元素/评论/页面全部集成进画布编辑器右侧可收起面板（顶部选项卡 + codicon 图标），移除独立侧栏视图，架构更简单。

功能（P2 · Figma 风格增强）

边框样式与颜色：style.border（none / solid / dashed）、style.borderWidth（px）、style.borderColor；文字颜色 style.color；背景色 style.background 只接受固定语义色。
背景颜色：style.background 仅用于表达语义，不接受 #hex、RGB 或 CSS 颜色名。
图片功能：image 元素支持 src（工作区相对路径，如 examples/assets/cover.svg）；渲染时经 webview.asWebviewUri 解析，导出 HTML 时内嵌为 base64 data URI。
固定语义色：仅支持 transparent / surface / muted / primary / onPrimary / danger / border / text / mutedText，由渲染器统一映射为实际颜色。
组件引用 token：文档级 components: { "courseCard": { ...元素定义... } }，画布中任意元素可用 component: "courseCard" 引用（组件内部元素可缺省 id，text 可缺省 content，由实例 overrides 填充，如 overrides: { title: { content: "React 基础" } }）；组件实例整体渲染、内部节点只读不可拖拽、循环引用被拒绝。
布局参考线：选中容器后显示内部子元素的虚线边框（.wc-child-highlight）与布局参考线（padding 参考框、grid 列/行虚线、flex 主轴中线），导出 PNG 时自动隐藏参考线。
查看 / 评审模式：用户侧为只读评审——属性面板展示元素信息（不可编辑），画布无拖拽/缩放手柄；保留选择、平移、缩放（CanvasKit 按分辨率重绘）、评论与链接跳转。
codicon 图标：面板、工具栏、评论操作、取色按钮等全部使用 VS Code codicon 字体图标，随构建复制到 dist/webview。

快速开始（本地开发）

环境要求：Node.js ≥ 20，VS Code ≥ 1.125。

npm install
npm run compile

按 F5 启动 Extension Development Host。在新窗口中：

打开一个工作区文件夹（例如本仓库）。
命令面板（Ctrl+Shift+P）运行 WireCue: Create Canvas，或直接打开 examples/course-list.wirecue。
画布会以 WireCue Canvas 编辑器打开；点击元素后工具栏出现“添加评论”。

调试

F5：调试扩展（esbuild watch 已配置，preLaunchTask 自动构建）。
Developer: Open Webview Developer Tools：调试 Webview 前端。
Developer: Inspect Context Keys：查看 wirecue.* 上下文键。

常用命令

命令	说明
`WireCue: Create Canvas`	新建示例画布并打开
`WireCue: Open Canvas`	选择工作区内的画布打开
`WireCue: Validate Current Canvas`	校验当前画布
`WireCue: Add Comment to Selected Element`	为选中元素添加评论
`WireCue: Show Open Comments`	打开画布面板的「评论」选项卡
`WireCue: Open Canvas as JSON`	以文本编辑器打开画布 JSON
`WireCue: Export Canvas as HTML`	导出为自包含 HTML
`WireCue: Export Canvas as PNG`	导出为 PNG

评论操作（解决/回复/指派/定位）在画布内评论面板与评论弹层中直接完成。

`.wirecue` 文件格式（v1）

{
  "$schema": "https://wirecue.dev/schemas/v1/wirecue.schema.json",
  "schemaVersion": 1,
  "name": "Course List",
  "viewport": { "width": 1440, "height": 900 },
  "root": {
    "id": "page",
    "type": "frame",
    "layout": {
      "type": "flex",
      "direction": "column",
      "gap": 24,
      "padding": { "top": 32, "right": 40, "bottom": 32, "left": 40 },
      "justify": "start",
      "align": "stretch",
      "wrap": false
    },
    "size": { "width": "fill", "height": "fill" },
    "children": [ ]
  }
}

要点：

所有元素必须有文档内唯一的 id；层级用嵌套 children 表达。
元素类型：frame、text、image、icon、divider、spacer。所有元素只表达视觉；按钮、输入框等控件由 frame + text/icon 组合，并通过 frame 的 link 表达跳转行为。
任意元素及文档级组件定义可使用 description 补充设计意图、状态或使用场景；该信息供用户与 Agent 阅读，不参与渲染。
尺寸：数字（固定 px）、fill（占满可用空间）、hug（内容决定）。
flex 布局：direction、gap、padding、justify、align、wrap。
grid 布局：columns / rows 只允许 auto、固定 px（如 240px）、正数 fr（如 1fr）。拒绝 calc()、CSS 变量等任意 CSS。
absolute 布局：每个直接子元素必须提供 position: { x, y, width, height }，不允许 fill / hug。
样式颜色只支持固定语义值（transparent / surface / muted / primary / onPrimary / danger / border / text / mutedText）；边框样式为 none / solid / dashed。
不允许负尺寸 / 负 gap / 负 padding / 负 margin；单画布默认最多 5000 个元素。

完整示例见 examples/course-list.wirecue。JSON Schema 在 schemas/wirecue.schema.json，已通过 jsonValidation 关联，编辑时有 IntelliSense。

评论文件格式（v1）

对于 prototype/home.wirecue，评论文件固定为相邻的 prototype/home.wirecue.comments.json：

{
  "$schema": "https://wirecue.dev/schemas/v1/comments.schema.json",
  "schemaVersion": 1,
  "canvas": "home.wirecue",
  "comments": [
    {
      "id": "c_01J8abC...",
      "elementId": "course-grid",
      "text": "三列布局改成两列，间距保持 16px",
      "status": "open",
      "createdAt": "2026-08-03T10:00:00.000Z",
      "resolvedAt": null,
      "resolution": null
    }
  ]
}

规则：

读取评论是只读的，绝不删除或改变状态。
解决评论写入 status: "resolved"、resolvedAt、resolution；记录不删除，侧栏默认隐藏已解决评论。
写入前会重新读取并合并并发更新，避免覆盖其他用户 / Agent 的改动。

供 Agent / Copilot 使用的工具

扩展注册了四个 Language Model Tools，Agent 在聊天中会自动或通过 #wirecue_... 等方式调用：

wirecue_get_comments：读取指定画布的未解决评论及关联元素的布局快照（含父容器摘要）。只读，不改文件。
wirecue_check_canvas：校验指定画布文件格式，返回错误清单（行号/路径/消息）与 JSON Schema 指引。只读；Agent 在创建/修改画布后、打开前调用。
wirecue_resolve_comments：Agent 成功修改画布后，把评论标记为已解决（写入 resolvedAt / resolution）。画布当前无效时拒绝执行；找不到评论 ID 时报错。
wirecue_open_canvas：在 WireCue Canvas 编辑器中打开画布，可选定位元素；打开前会先校验格式，无效时返回错误清单与 schema 指引而不打开。

Agent 工作流：wirecue_check_canvas 校验格式 → wirecue_get_comments 读评论 → 直接编辑 .wirecue 文件 → wirecue_resolve_comments 解决评论 → wirecue_open_canvas 让用户查看。

路径安全：所有工具只接受工作区相对路径（如 prototype/home.wirecue），拒绝绝对路径与 .. 跳出工作区；多根工作区需以文件夹名开头。

说明：工具采用 VS Code 官方双轨注册——package.json 的 contributes.languageModelTools 声明元数据（名称/描述/输入 schema/# 引用名），src/extension.ts 用 vscode.lm.registerTool 注册实现，两者配套缺一不可（并非重复注册）。

Agent Skill：创建 WireCue 画布

扩展通过 contributes.chatSkills 注册了 create-wirecue Skill（skills/create-wirecue/SKILL.md）。当用户要求生成页面线框、布局原型或组件化 UI 草稿时，Agent 会自动加载该 Skill 学习 .wirecue 文件格式：文件结构、元素类型、flex/grid/absolute 布局、固定语义色、组件与 overrides、校验规则与验证方式，从而直接生成合规的画布文件。

测试

npm run test:unit          # Vitest 单元测试（解析、校验、评论、路径安全）
npm run test:integration   # 集成测试（需要下载 VS Code，在 Extension Development Host 中运行）
npm run lint               # ESLint
npm run check-types        # TypeScript 类型检查

手动验证清单

深色 / 浅色主题下画布、评论锚点、错误条均可读。
100%、50%、200% 缩放正常；适应 按钮可回到整体视图。
1440×900 与 390×844 viewport 均能渲染。
打开 examples/course-list.wirecue，用文本编辑器修改其中 course-grid 的 columns 为两列，切回画布应自动刷新。
把画布 JSON 改成无效内容：应保留最后一次有效画布并显示错误条；恢复有效后自动刷新。
选中元素 → 添加评论 → 侧栏立即出现；点击侧栏评论可打开画布并定位元素。
在聊天中让 Agent 读取评论、修改文件、解决评论，确认闭环可用。

已知限制（MVP）

不做 Figma 级自由绘制 / 高保真设计系统 / 动画 / 复杂渐变。
不根据截图自动生成设计。
不提供逐元素绘图工具；Agent 直接编辑文件。
评论回复、指派、历史、元素树、属性面板等属于 P1，尚未实现。
画布与评论文件并行编辑时采用“重新读取并合并”策略；若文件在读取间隙被删除等极端情况会按空文件处理。

工程结构

wirecue/
├── package.json / tsconfig.json / esbuild.js / vitest.config.ts
├── schemas/            # .wirecue 与评论文件的 JSON Schema
├── src/
│   ├── extension.ts    # 入口：注册编辑器、侧栏、命令、LM 工具
│   ├── model/          # 类型、解析、校验、元素索引（纯逻辑，可单测）
│   ├── comments/       # 评论服务、侧栏 Tree View、路径规则
│   ├── editor/         # Custom Editor Provider、文档同步、Webview HTML
│   ├── webview/        # 前端：渲染器、视口、选择、样式
│   ├── tools/          # 三个 Language Model Tools
│   ├── commands/       # 命令实现
│   └── security/       # 工作区路径安全
├── test/               # Vitest 单元测试
└── examples/           # 示例画布

License

MIT

1.0.1

Fixed issue #.

1.1.0

Added features X, Y, and Z.

Following extension guidelines

Ensure that you've read through the extensions guidelines and follow the best practices for creating your extension.

Extension Guidelines

Working with Markdown

You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts:

Split the editor (Cmd+\ on macOS or Ctrl+\ on Windows and Linux).
Toggle preview (Shift+Cmd+V on macOS or Shift+Ctrl+V on Windows and Linux).
Press Ctrl+Space (Windows, Linux, macOS) to see a list of Markdown snippets.

For more information

Enjoy!

WireCue

Evanxiao

WireCue

功能（MVP / P0）

功能（P1）

功能（P2 · Figma 风格增强）

快速开始（本地开发）

调试

常用命令

.wirecue 文件格式（v1）

评论文件格式（v1）

供 Agent / Copilot 使用的工具

Agent Skill：创建 WireCue 画布

测试

手动验证清单

已知限制（MVP）

工程结构

License

1.0.1

1.1.0

Following extension guidelines

Working with Markdown

For more information

`.wirecue` 文件格式（v1）