miro-spec-guide

Miro 规格提取指南

什么是 miro-spec？

miro-spec 插件可从 Miro 看板中提取规格内容，并将其保存到本地文件。这样，AI 就能在规划和实现过程中参考规格，而无需反复调用 API。

何时使用 miro-spec

需要以下操作时，请使用 miro-spec：

• 从 Miro 看板中提取产品需求
• 保存设计规格以供实现
• 下载原型和图表以供参考
• 在本地创建 Miro 文档副本
• 离线使用规格或将其纳入版本控制

命令：/miro-spec:get

从 Miro 看板或项目中提取规格：

/miro-spec:get [url]

URL 类型

看板 URL - 提取所有规格项目：

https://miro.com/app/board/uXjVK123abc=/

项目 URL - 提取单个项目：

https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

了解 .miro/specs/ 目录

目录结构

.miro/specs/
├── documents/      # Miro documents (Markdown format)
├── diagrams/       # Diagram descriptions (Markdown)
├── prototypes/     # Prototype containers (Markdown) and screens (HTML)
├── tables/         # Table data (JSON)
├── frames/         # Frame summaries (Markdown)
├── other/          # Unknown types like slides (Markdown)
├── images/         # Downloaded images (PNG)
└── index.json      # Metadata index

内容类型

文档（.md）

• 带格式的 Markdown 内容
• 保留标题和结构
• 清晰的文本格式

图表（.md）

• AI 生成的图表说明
• 流程分析和组件关系
• 关键元素和连接

原型（.md / .html）

• 容器：带导航地图的 Markdown（.md，后缀为 -container）
• 屏幕：包含 UI 布局的 HTML 标记（.html，后缀为 -screen）
• UI 组件结构

表格（.json）

• 包含列定义的结构化数据
• 所有行和单元格值
• 列类型和元数据

画框（.md）

• AI 生成的画框内容摘要
• 所含项目概览
• 组织结构

图像（.png）

• 自动从原型中提取
• 在原型屏幕中通过相对路径引用
• 以 Miro 项目 ID 命名

提取工作流

1. 运行提取命令

/miro-spec:get https://miro.com/app/board/uXjVK-spec=/

2. 处理现有内容

如果 .miro/specs/ 中已有文件，请选择：

• 清理并重新提取 - 从头开始
• 添加到现有内容 - 保留当前文件
• 取消 - 中止

3. 查看提取摘要

输出会显示：

Extracted 5 documents, 3 diagrams, 2 prototypes, 1 table
Downloaded 12 images
Saved to .miro/specs/

4. 查看元数据索引

打开 .miro/specs/index.json，查看：

• 所有已提取项目及其类型
• 每个项目的文件路径
• 原始 Miro URL
• 提取时间戳

看板 URL 与项目 URL

看板 URL

适用场景：

• 提取完整规格
• 获取所有相关文档和图表
• 全面提取规格

功能：

• 列出看板上的所有项目
• 筛选与规格相关的类型
• 逐个提取每个项目

示例：

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/

项目 URL

适用场景：

• 提取单个文档或图表
• 获取特定原型屏幕
• 定向提取

功能：

• 仅提取指定项目
• 提取单个项目时速度更快
• 使用 moveToWidget 参数

示例：

/miro-spec:get https://miro.com/app/board/uXjVK123abc=/?moveToWidget=3458764612345

图像的提取方式

自动发现图像

1. 插件扫描原型屏幕的 HTML 内容
2. 查找 src 属性中的 Miro 图像 URL
3. 从 URL 中提取 board_id 和 item_id
4. 使用 Miro MCP 下载每张图像

URL 替换

原始 HTML：

<img src="https://miro.com/api/v2/boards/uXjVK123abc=/images/3458764612345"/>

提取后：

<img src="../images/3458764612345.png"/>

优点

• 图像可离线使用
• 查看文档时无需调用 API
• 从本地文件加载速度更快
• 可以提交到版本控制

使用规格规划实现

工作流示例

1. 提取规格：

   /miro-spec:get https://miro.com/app/board/uXjVK-product-spec=/
   

2. 查看提取内容： 检查 .miro/specs/index.json，查看可用规格

3. 让 AI 规划实现： “根据 .miro/specs/ 中的规格，为用户身份验证功能制定实现计划”

4. AI 读取相关文件： AI 会在规划过程中自动读取文档、图表和表格

5. 结合上下文实现： AI 使用规格内容指导代码生成

AI 提示词示例

基于规格进行规划：

"Review the product requirements in .miro/specs/documents/ and create a technical implementation plan"

使用特定图表：

"Reference the architecture diagram in .miro/specs/diagrams/3458764612345.md and implement the database schema"

验证实现：

"Compare the authentication flow I implemented against the spec in .miro/specs/prototypes/3458764612346.html"

最佳实践

提取策略

• 使用白板 URL 进行全面的初始提取
• 使用项目 URL 更新特定文档
• 开始实施前先提取
• 规格变更时重新提取

目录管理

• 如果规格是临时的，请将 .miro/specs/ 保留在 .gitignore 中
• 如果规格需要共享，请提交到版本控制
• 白板结构发生重大变化时，清理并重新提取
• 更新单个项目时，添加到现有内容中

使用规格

• 始终先检查 index.json，了解可用内容
• 直接读取 HTML 文件以获取完整文档内容
• 使用 Markdown 文件快速查看图表概览
• 解析 JSON 文件以获取结构化表格数据

性能提示

• 如果白板较大，请使用项目 URL 从特定画框提取
• 清理旧的提取内容，避免混淆
• 谨慎使用白板 URL（大型白板可能会比较慢）
• 在实施会话之间缓存提取内容

常见工作流

提取产品需求

# Extract all PRD documents
/miro-spec:get https://miro.com/app/board/uXjVK-prd=/

# Review extracted docs
cat .miro/specs/index.json | grep documents

# Plan implementation
"Plan implementation based on requirements in .miro/specs/"

更新单个规格

# Extract updated design doc
/miro-spec:get https://miro.com/app/board/uXjVK=/.../?moveToWidget=3458764612345

# Choose "Add to existing" when prompted
# Review changes in .miro/specs/documents/3458764612345.html

提取架构图

# Extract board with diagrams
/miro-spec:get https://miro.com/app/board/uXjVK-architecture=/

# Check diagram summaries
ls .miro/specs/diagrams/
cat .miro/specs/diagrams/*.md

故障排除

未从白板中提取到项目：

• 白板可能不包含文档、画框或表格项目
• 尝试使用项目 URL 获取特定内容
• 检查白板 URL 是否正确

图片未下载：

• 某些图片可能无法通过 MCP 访问
• 如果下载失败，将保留原始 URL
• 即使使用外部图片 URL，文档仍可阅读

提取后未找到文件：

• 检查 .miro/specs/index.json 以确认实际路径
• 确认提取已成功完成
• 查看提取输出中的错误消息

大型白板耗时过长：

• 使用项目 URL 提取特定内容
• 提取单个画框，而非整个白板
• 考虑按内容类型筛选

另请参阅

• 规格存储格式 - 文件格式详细说明
• Miro MCP 工具 - 了解 Miro MCP 功能
• 插件 README - 安装和设置说明