oodle-dashboards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oodle Dashboards — CRUD and Organization

Oodle仪表板——增删改查与组织管理

This skill teaches the agent to manage Oodle dashboards and folders without losing panel state and without orphaning dashboards in the root folder.

本技能指导Agent管理Oodle仪表板与文件夹，确保不会丢失面板状态，也不会让仪表板孤立在根文件夹中。

Prerequisites

前提条件

bash

brew install oodle-ai/oodle/oodle
oodle configure

bash

brew install oodle-ai/oodle/oodle
oodle configure

or

export OODLE_API_KEY=<key> export OODLE_INSTANCE=<instance> export OODLE_DEPLOYMENT=<url>


Verify dashboards endpoint works:

```bash
oodle dashboards list -o json | jq 'length'
oodle folders list -o json | jq 'length'

export OODLE_API_KEY=<key> export OODLE_INSTANCE=<instance> export OODLE_DEPLOYMENT=<url>


验证仪表板端点是否可用：

```bash
oodle dashboards list -o json | jq 'length'
oodle folders list -o json | jq 'length'

Command Execution Order

命令执行顺序

Before running any oodle command:

Check whether the required resource ID or name is already in context.
If not, run the discovery command (e.g.,
```
oodle dashboards list -o json
```
).
If the result is ambiguous, ask the user to confirm before proceeding.
Run the target command with the resolved ID.
Do not run speculative commands (e.g., do not
```
delete
```
without first
```
get
```
-ing the resource).

在运行任何oodle命令之前：

检查所需的资源ID或名称是否已在上下文当中。
如果没有，运行发现命令（例如：
```
oodle dashboards list -o json
```
）。
如果结果不明确，在继续操作前请用户确认。
使用解析后的ID运行目标命令。
不要运行推测性命令（例如，在未先
```
get
```
资源的情况下不要执行
```
delete
```
）。

Quick Reference

快速参考

Task	Command
List dashboards	`oodle dashboards list -o json`
Get dashboard	`oodle dashboards get <id> -o json`
Create dashboard	`oodle dashboards create -f dashboard.json`
Update dashboard	`oodle dashboards update <id> -f dashboard.json`
Delete dashboard	`oodle dashboards delete <id> --force`
List folders	`oodle folders list -o json`
Get folder	`oodle folders get <id> -o json`
Create folder	`oodle folders create -f folder.json`
Delete folder	`oodle folders delete <id> --force`

任务	命令
列出仪表板	`oodle dashboards list -o json`
获取仪表板	`oodle dashboards get <id> -o json`
创建仪表板	`oodle dashboards create -f dashboard.json`
更新仪表板	`oodle dashboards update <id> -f dashboard.json`
删除仪表板	`oodle dashboards delete <id> --force`
列出文件夹	`oodle folders list -o json`
获取文件夹	`oodle folders get <id> -o json`
创建文件夹	`oodle folders create -f folder.json`
删除文件夹	`oodle folders delete <id> --force`

Common Operations

常见操作

Listing dashboards

列出仪表板

bash

undefined

bash

undefined

✅ CORRECT

✅ 正确

oodle dashboards list -o json

✅ CORRECT — filter by folder

✅ 正确 — 按文件夹筛选

oodle dashboards list -o json | jq '.[] | select(.folderId=="fld_platform")'

❌ WRONG — parsing table output to find an ID

❌ 错误 — 解析表格输出以查找ID

oodle dashboards list | grep "API Overview" | awk '{print $1}'

undefined

oodle dashboards list | grep "API Overview" | awk '{print $1}'

undefined

Reading a dashboard before changing it

修改前读取仪表板

bash

undefined

bash

undefined

✅ CORRECT — fetch the full definition first; preserves all panels and queries

✅ 正确 — 先获取完整定义；保留所有面板和查询

oodle dashboards get dash_123 -o json > dashboard.json $EDITOR dashboard.json oodle dashboards update dash_123 -f dashboard.json

❌ WRONG — sending an incomplete payload removes panels

❌ 错误 — 发送不完整的负载会删除面板

oodle dashboards update dash_123 -f <(echo '{"title":"new title"}')

undefined

oodle dashboards update dash_123 -f <(echo '{"title":"new title"}')

undefined

Creating a dashboard

创建仪表板

A complete dashboard JSON places the dashboard in a known folder:

json

{
  "title": "API Overview",
  "folderId": "fld_platform",
  "description": "Latency, error rate, and throughput for the API service.",
  "tags": ["service:api", "team:platform"],
  "panels": [
    {
      "title": "Request rate",
      "type": "timeseries",
      "query": "sum(rate(http_requests_total{service=\"api\"}[5m]))"
    },
    {
      "title": "Error rate",
      "type": "timeseries",
      "query": "sum(rate(http_requests_total{service=\"api\",status=~\"5..\"}[5m]))"
    },
    {
      "title": "P99 latency",
      "type": "timeseries",
      "query": "histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{service=\"api\"}[5m])))"
    }
  ]
}

bash

undefined

完整的仪表板JSON会将仪表板放置在指定文件夹中：

json

{
  "title": "API Overview",
  "folderId": "fld_platform",
  "description": "Latency, error rate, and throughput for the API service.",
  "tags": ["service:api", "team:platform"],
  "panels": [
    {
      "title": "Request rate",
      "type": "timeseries",
      "query": "sum(rate(http_requests_total{service=\"api\"}[5m]))"
    },
    {
      "title": "Error rate",
      "type": "timeseries",
      "query": "sum(rate(http_requests_total{service=\"api\",status=~\"5..\"}[5m]))"
    },
    {
      "title": "P99 latency",
      "type": "timeseries",
      "query": "histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket{service=\"api\"}[5m])))"
    }
  ]
}

bash

undefined

✅ CORRECT

✅ 正确

oodle dashboards create -f dashboard.json

❌ WRONG — no folderId, dashboard ends up in root and is hard to find

❌ 错误 — 未指定folderId，仪表板会出现在根目录中，难以查找

oodle dashboards create -f <(echo '{"title":"API Overview","panels":[...]}')

undefined

oodle dashboards create -f <(echo '{"title":"API Overview","panels":[...]}')

undefined

Folder management

文件夹管理

bash

undefined

bash

undefined

✅ CORRECT — create folder first, capture id, then create dashboards in it

✅ 正确 — 先创建文件夹，获取ID，再在其中创建仪表板

FOLDER_ID=$(oodle folders create -f <(echo '{"title":"Platform"}') -o json | jq -r '.id') jq --arg fid "$FOLDER_ID" '.folderId=$fid' dashboard.json > dashboard.with-folder.json oodle dashboards create -f dashboard.with-folder.json

❌ WRONG — creating dashboards before folders, then trying to move them later

❌ 错误 — 先创建仪表板再创建文件夹，之后尝试移动它们

oodle dashboards create -f dashboard.json oodle folders create -f folder.json

undefined

oodle dashboards create -f dashboard.json oodle folders create -f folder.json

undefined

Safe deletion — two-phase

安全删除——两阶段法

Dashboards are linked from runbooks, slack messages, and bookmarks. Delete in two phases.

bash

undefined

仪表板会被运行手册、Slack消息和书签链接引用。删除需分两个阶段进行。

bash

undefined

✅ CORRECT — phase 1: rename so users see it's about to be removed

✅ 正确 — 第一阶段：重命名，让用户知道该仪表板即将被移除

oodle dashboards get dash_123 -o json > dash.json jq '.title = "[MARKED FOR DELETION] " + .title' dash.json > dash.deletion.json oodle dashboards update dash_123 -f dash.deletion.json

oodle dashboards get dash_123 -o json > dash.json jq '.title = "[标记为删除] " + .title' dash.json > dash.deletion.json oodle dashboards update dash_123 -f dash.deletion.json

wait at least 7 days, then:

至少等待7天，然后执行：

oodle dashboards delete dash_123 --force

❌ WRONG — immediate hard delete, breaks every existing link

❌ 错误 — 立即硬删除，破坏所有现有链接

oodle dashboards delete dash_123 --force

undefined

oodle dashboards delete dash_123 --force

undefined

Best Practices

最佳实践

Always

get

before

update

to preserve panel configuration

始终在

update

前执行

get

以保留面板配置

Update is a full-document replace. Missing panels in the payload will be removed.

bash

undefined

更新操作是全文档替换。负载中缺失的面板会被删除。

bash

undefined

✅ CORRECT

✅ 正确

oodle dashboards get dash_123 -o json > dash.json jq '.panels[0].title = "Request rate (per second)"' dash.json > dash.new.json oodle dashboards update dash_123 -f dash.new.json

❌ WRONG — sends a single-field payload; all panels disappear

❌ 错误 — 发送单字段负载；所有面板都会消失

oodle dashboards update dash_123 -f <(echo '{"description":"updated"}')

undefined

oodle dashboards update dash_123 -f <(echo '{"description":"updated"}')

undefined

Always set

folderId

when creating a dashboard

创建仪表板时始终设置

folderId

Dashboards in the root folder are hard for teams to discover.

bash

undefined

根文件夹中的仪表板对团队来说难以发现。

bash

undefined

✅ CORRECT

✅ 正确

"folderId": "fld_platform"

❌ WRONG — omitting folderId means root

❌ 错误 — 省略folderId意味着根目录

"folderId": null

undefined

"folderId": null

undefined

Use the two-phase rename → wait → delete pattern for shared dashboards

共享仪表板使用重命名→等待→删除的两阶段模式

Hard-deleting a dashboard breaks every external link (runbooks, slack reactions, bookmarks).

bash

undefined

硬删除仪表板会破坏所有外部链接（运行手册、Slack消息、书签）。

bash

undefined

✅ CORRECT — phase 1: rename

✅ 正确 — 第一阶段：重命名

oodle dashboards update dash_123 -f dash.deletion.json

wait, confirm no traffic, then phase 2: delete

等待，确认无访问量后，执行第二阶段：删除

oodle dashboards delete dash_123 --force

❌ WRONG — same-day delete on a shared dashboard

❌ 错误 — 当天删除共享仪表板

oodle dashboards delete dash_123 --force

undefined

oodle dashboards delete dash_123 --force

undefined

Tag dashboards with

service

and

team

labels

使用

service

和

team

标签标记仪表板

Tags make dashboards searchable and let other tools (e.g. service catalogs) link to them.

bash

undefined

标签让仪表板可被搜索，并允许其他工具（如服务目录）链接到它们。

bash

undefined

✅ CORRECT

✅ 正确

"tags": ["service:api", "team:platform", "env:prod"]

❌ WRONG

❌ 错误

"tags": []

undefined

"tags": []

undefined

Failure Handling

故障处理

Error	Cause	Fix
401 Unauthorized	Invalid or missing API key	Run `oodle configure` or set `OODLE_API_KEY`
404 Not Found	Dashboard or folder ID does not exist	Verify with `oodle dashboards list -o json`
connection refused	Wrong `OODLE_DEPLOYMENT` URL	Check `OODLE_DEPLOYMENT` env var
`folder not found`	`folderId` references a deleted folder	List folders with `oodle folders list -o json` ; choose an existing id or create one
Panels disappeared after update	`update` was called with a partial payload	Re-create from the last `get` snapshot; in the future always `get` → edit → `update`
Cannot delete folder	Folder still contains dashboards	Move or delete the dashboards first; `oodle dashboards list -o json
429 Too Many Requests	Bulk dashboard sync	Add `--retries 3` , throttle to <10 creates per second

错误	原因	修复方法
401 Unauthorized	API密钥无效或缺失	运行 `oodle configure` 或设置 `OODLE_API_KEY`
404 Not Found	仪表板或文件夹ID不存在	使用 `oodle dashboards list -o json` 验证
connection refused	`OODLE_DEPLOYMENT` URL错误	检查 `OODLE_DEPLOYMENT` 环境变量
`folder not found`	`folderId` 引用了已删除的文件夹	使用 `oodle folders list -o json` 列出文件夹；选择现有ID或创建新文件夹
Panels disappeared after update	使用部分负载调用 `update`	从最近的 `get` 快照重新创建；未来请始终遵循 `get` →编辑→ `update` 流程
Cannot delete folder	文件夹中仍包含仪表板	先移动或删除仪表板；执行`oodle dashboards list -o json
429 Too Many Requests	批量仪表板同步	添加 `--retries 3` ，限制每秒创建次数少于10次

oodle-dashboards

Original

Translation

Oodle Dashboards — CRUD and Organization

Oodle仪表板——增删改查与组织管理

Prerequisites

前提条件

or

or

Command Execution Order

命令执行顺序

Quick Reference

快速参考

Common Operations

常见操作

Listing dashboards

列出仪表板

✅ CORRECT

✅ 正确

✅ CORRECT — filter by folder

✅ 正确 — 按文件夹筛选

❌ WRONG — parsing table output to find an ID

❌ 错误 — 解析表格输出以查找ID

Reading a dashboard before changing it

修改前读取仪表板

✅ CORRECT — fetch the full definition first; preserves all panels and queries

✅ 正确 — 先获取完整定义；保留所有面板和查询

❌ WRONG — sending an incomplete payload removes panels

❌ 错误 — 发送不完整的负载会删除面板

Creating a dashboard

创建仪表板

✅ CORRECT

✅ 正确

❌ WRONG — no folderId, dashboard ends up in root and is hard to find

❌ 错误 — 未指定folderId，仪表板会出现在根目录中，难以查找

Folder management

文件夹管理

✅ CORRECT — create folder first, capture id, then create dashboards in it

✅ 正确 — 先创建文件夹，获取ID，再在其中创建仪表板

❌ WRONG — creating dashboards before folders, then trying to move them later

❌ 错误 — 先创建仪表板再创建文件夹，之后尝试移动它们

Safe deletion — two-phase

安全删除——两阶段法

✅ CORRECT — phase 1: rename so users see it's about to be removed

✅ 正确 — 第一阶段：重命名，让用户知道该仪表板即将被移除

wait at least 7 days, then:

至少等待7天，然后执行：

❌ WRONG — immediate hard delete, breaks every existing link

❌ 错误 — 立即硬删除，破坏所有现有链接

Best Practices

最佳实践

Always get before update to preserve panel configuration

始终在update前执行get以保留面板配置

✅ CORRECT

✅ 正确

❌ WRONG — sends a single-field payload; all panels disappear

❌ 错误 — 发送单字段负载；所有面板都会消失

Always set folderId when creating a dashboard

创建仪表板时始终设置folderId

✅ CORRECT

✅ 正确

❌ WRONG — omitting folderId means root

❌ 错误 — 省略folderId意味着根目录

Use the two-phase rename → wait → delete pattern for shared dashboards

共享仪表板使用重命名→等待→删除的两阶段模式

✅ CORRECT — phase 1: rename

✅ 正确 — 第一阶段：重命名

wait, confirm no traffic, then phase 2: delete

等待，确认无访问量后，执行第二阶段：删除

❌ WRONG — same-day delete on a shared dashboard

❌ 错误 — 当天删除共享仪表板

Tag dashboards with service and team labels

使用service和team标签标记仪表板

✅ CORRECT

✅ 正确

❌ WRONG

❌ 错误

Failure Handling

故障处理

References

Always
`get`
before
`update`
to preserve panel configuration

始终在
`update`
前执行
`get`
以保留面板配置

Always set
`folderId`
when creating a dashboard

创建仪表板时始终设置
`folderId`

Tag dashboards with
`service`
and
`team`
labels

使用
`service`
和
`team`
标签标记仪表板