Miro 管理
使用此技能通过 REST API 与 Miro 进行交互。
快速开始
获取用户的 Miro 应用客户端 ID、客户端密钥和重定向 URI(如果使用 OAuth)。
首选本地重定向 URI,例如 http://127.0.0.1:4000/auth/miro/callback。
使用 scripts/miro_api.py 进行 OAuth、令牌刷新、板块/项目操作、导出和原始 API 调用。
从以下开始:
auth-url
serve-oauth-callback
list-boards
list-board-items
永远不要将客户端密钥、刷新令牌或活跃访问令牌打包到技能包中。
身份验证模式
OAuth 模式
尽可能使用 shell 环境变量:
$env:MIRO_CLIENT_ID = '...'
$env:MIRO_CLIENT_SECRET = '...'
$env:MIRO_REDIRECT_URI = 'http://127.0.0.1:4000/auth/miro/callback'
启动回调帮助程序:
python scripts/miro_api.py serve-oauth-callback --port 4000 --token-file .miro/tokens.json
然后生成授权 URL:
python scripts/miro_api.py auth-url
打开该 URL,批准应用程序,并让回调帮助程序存储令牌负载。
直接令牌模式
如果用户已经拥有一个有效的 Miro 访问令牌,则跳过 OAuth 并使用以下任一方法:
$env:MIRO_ACCESS_TOKEN = '...'
python scripts/miro_api.py list-boards
或保存的令牌文件:
python scripts/miro_api.py list-boards --token-file .miro/tokens.json
核心工作流
首先使用廉价的检查:
python scripts/miro_api.py list-boards --token-file .miro/tokens.json
python scripts/miro_api.py get-board --board-id --token-file .miro/tokens.json
python scripts/miro_api.py list-board-items --board-id --token-file .miro/tokens.json
python scripts/miro_api.py create-sticky-note --board-id "Hello from OpenClaw" --token-file .miro/tokens.json
python scripts/miro_api.py create-text --board-id "Roadmap" --token-file .miro/tokens.json
python scripts/miro_api.py create-shape --board-id "API Layer" --token-file .miro/tokens.json
python scripts/miro_api.py create-card --board-id "Task" --token-file .miro/tokens.json
python scripts/miro_api.py export-board-items --board-id --format markdown --output-file board-report.md --token-file .miro/tokens.json
python scripts/miro_api.py refresh-token --token-file .miro/tokens.json
常用命令
auth-url — 打印 OAuth 授权 URL
serve-oauth-callback — 运行本地回调服务器并交换返回的代码以获取令牌
exchange-code — 手动交换复制的授权代码以获取令牌
refresh-token — 使用存储的刷新令牌刷新访问权限
whoami — 使用轻量级板块调用测试令牌
list-boards — 列出可访问的板块
get-board — 获取板块详细信息
create-board — 创建板块
list-board-items — 列出板块项目
export-board-items — 将板块项目导出为 markdown、csv 或 json
create-sticky-note — 创建便利贴
create-text — 创建文本项目
create-shape — 创建形状项目
create-card / update-card — 创建或更新卡片项目
create-sticky-note / update-sticky-note — 创建或更新便利贴
create-text / update-text — 创建或更新文本项目
create-shape / update-shape — 创建或更新形状
create-connector — 连接两个板块项目
list-board-members — 列出板块成员
get-webhooks / create-webhook / delete-webhook — 管理 webhooks
create-brainstorm-cluster — 放置一行想法便利贴
create-kanban-row — 创建轻量级看板风格行
create-architecture-chain — 创建连接的架构盒
delete-item — 根据类型路径 + 项目 ID 删除项目
preview-write — 预览写入请求而不发送它
raw — 发送任意 Miro API 请求,带有可选的 JSON 正文
变异规则
对于写入调用:
确认目标板块和项目 ID。
在发送之前总结确切的正文和端点,当更改不是明显期望时。
将秘密和令牌保留在技能文件夹之外。
更喜欢将 API 结果导出到文件,而不是在聊天中转储巨大的有效负载。
将实时板块写入视为真实的外部操作,而不是无害的本地测试。
参考
阅读 references/miro-oauth-notes.md 以获取 Miro OAuth 流、令牌端点、重定向 URI 规则和安全本地存储指南。
阅读 references/miro-request-examples.md 以获取启动器创建/导出命令和原始请求示例。