xjtulyc/skills/dashboard

Local Research Dashboard Skill

概述

每次科研任务开始时，生成一个临时的本地 dashboard，动态展示任务关键信息和产物预览。

组件

• state.json：数据协议，openclaw 负责写入和更新
• dashboard.html：本地单文件页面，轮询 state.json 并渲染
• dashboard_serve.py：静态文件服务器，serve 任务根目录

所有文件放在任务独立目录中（如 data/<task_name>/dashboard/）。

---

state.json Schema

{
  "title": "任务标题",
  "updated_at": "2024-01-01 12:00:00",
  "panels": [
    {
      "type": "progress|text|list|code|table|image|files|step",
      "label": "面板标题（可折叠的标识）",
      "content": "内容（格式取决于 type）"
    }
  ]
}

Panel 类型说明

| type | content 格式 | 用途 | 渲染 | |------|------------|------|------| | progress | number (0-100) | 整体进度 | 置顶在 header，不出现在面板区 | | text | string | 状态描述、摘要、发现 | 预格式化文本，自动换行 | | list | string[] | 步骤列表、待办、已完成项 | 带左边框的条目列表 | | code | string | 代码片段、命令输出 | 等宽字体，可滚动，带复制按钮 | | table | {src: "path"} 或 {headers: [...], rows: [...]} | CSV/统计结果 | 从文件实时加载或内嵌数据 | | image | string 或 string[] | 图片产物预览 | 内联图片，点击放大，带下载按钮 | | files | string[] 或 {name, size}[] | 输出目录文件列表 | 可点击预览/下载的文件列表 | | step | {desc, code?, outputs?} | 步骤卡片：展示一个分析步骤的代码和产物 | 代码 + 产物预览 + 描述 |

step 类型（核心面板）

目标： 每个分析步骤 = 做了什么 + 跑了什么代码 + 产出了什么

{
  "type": "step",
  "label": "① 数据加载与清洗",
  "content": {
    "desc": "加载 CHARLS .dta 数据，编码 8 项 ACE 指标...",
    "code": "import pandas as pd\ndf = pd.read_stata('charls.dta')\n...",
    "outputs": [
      {"kind": "text", "value": "原始 96,628 行 → 筛选后 46,628 行（12,877 人）"},
      {"kind": "image", "src": "/output/fig1_ace_distribution.png", "caption": "ACE 评分分布"},
      {"kind": "table", "src": "/output/table1_baseline.csv", "caption": "基线特征"},
      {"kind": "file", "src": "/output/table1_baseline.csv"}
    ]
  }
}

step.content 字段

| 字段 | 必填 | 说明 | |------|------|------| | desc | ✅ | 这步做了什么、发现了什么（完整句子） | | code | 可选 | 核心代码片段（默认折叠，展示关键逻辑） | | code_file | 可选 | 完整脚本文件路径（如 /analysis.py），前端按需加载 | | outputs | 可选 | 产物列表 |

约定： code 放精华片段帮助快速理解逻辑；code_file 指向完整可运行的脚本。两者可同时存在。

outputs[].kind

| kind | 说明 | |------|------| | text | 文字结果（value 字段） | | image | 图片（src 路径，可选 caption） | | table | 表格（src 指向 CSV 文件路径，前端实时加载解析） | | file | 文件下载链接（src 路径） |

table 类型的两种模式

模式1：文件引用（推荐） — 前端实时 fetch CSV 文件：

{"type": "table", "label": "表1: 基线", "content": {"src": "/output/table1.csv"}}

模式2：内嵌数据（向后兼容） — 数据直接写在 state.json：

{"type": "table", "label": "表1", "content": {"headers": [...], "rows": [...]}}

---

交互功能

复制与下载

所有可预览内容都有操作按钮：

• 代码块 → 「📋 复制」按钮
• 表格 → 「📋 复制 TSV」「⬇ 下载 CSV」按钮
• 图片 → 「⬇ 下载」按钮
• 文本预览 → 「📋 复制」按钮
• 文件列表 → 每项可点击预览或下载

面板可折叠

• 点击面板标题栏可折叠/展开
• 折叠状态在同一次页面会话中记忆
• 动画有阻尼感（cubic-bezier ease）

---

配色

使用 IBM 色盲友好色板：

• Blue: #648FFF
• Purple: #785EF0
• Magenta: #DC267F
• Orange: #FE6100
• Yellow: #FFB000

暗色背景使用 GitHub Dark 色系。

---

openclaw 的职责

1. 任务开始时

在任务目录下创建 dashboard/ 子目录，复制模板文件，生成初始 state.json。

2. 每个关键步骤完成后

更新 state.json，使用 step 面板：

• 更新 progress panel 的值
• 为当前步骤创建 step panel，包含：
  • desc：详细描述做了什么、发现了什么
  • code：关键代码片段（不需要完整脚本，抓核心逻辑）
  • outputs：这步产出的所有东西（图片、表格、文字结果、文件）

3. 文字描述原则

• 不要只写"完成了"，要写做了什么、发现了什么
• 统计结果要写具体数值（OR、CI、p值）
• 数据筛选要写筛选前后的样本量变化
• 异常/警告要明确说明原因和影响

✅ 好的 step 描述：

{
  "type": "step",
  "label": "① 数据加载与清洗",
  "content": {
    "desc": "加载 CHARLS .dta 数据（5 波次），编码 8 项 ACE 指标（身体虐待、情感忽视等），构建 3 个 CVD 结局变量。按年龄≥60、ACE 非缺失≥5 项、≥2 波次筛选，保留 12,877 人（46,628 人次观测），流失 50.2% 主要因年龄限制。",
    "code": "df = pd.read_stata('charls.dta')\nace_cols = ['abuse_physical', 'abuse_emotional', ...]\ndf['ace_score'] = df[ace_cols].sum(axis=1)\ndf = df[df.age >= 60]\ndf = df.groupby('id').filter(lambda x: len(x) >= 2)",
    "outputs": [
      {"kind": "text", "value": "原始: 96,628 行 (25,873 人) → 筛选后: 46,628 行 (12,877 人)"},
      {"kind": "text", "value": "ACE Cronbach's α = 0.477"}
    ]
  }
}

❌ 差的描述：

desc: "数据加载完成"

4. 任务结束时

• 进度设为 100
• 添加 files panel 列出所有产物
• 写最终总结 step

---

使用方式

Step 1 — 复制模板到任务目录：

TASK_DIR=/path/to/task
mkdir -p "$TASK_DIR/dashboard"
cp skills/dashboard/dashboard.html "$TASK_DIR/dashboard/"
cp skills/dashboard/dashboard_serve.py "$TASK_DIR/dashboard/"

Step 2 — 生成初始 state.json

Step 3 — 启动服务器（serve 任务根目录）：

python "$TASK_DIR/dashboard/dashboard_serve.py" --port 7788
# 或显式指定根目录：
python "$TASK_DIR/dashboard/dashboard_serve.py" --root "$TASK_DIR" --port 7788

Dashboard URL: http://localhost:7788/dashboard/dashboard.html

Step 4 — 告诉用户打开链接，然后执行任务并持续更新 state.json

路径约定

重要： dashboard_serve.py 默认 serve 任务根目录（dashboard/ 的父目录）。

所有资源路径使用绝对路径（相对于 serve 根 = 任务根目录），以 / 开头：

{"src": "/output/fig1.png"}
{"content": "/output/fig1.png"}

Dashboard URL: http://localhost:PORT/dashboard/dashboard.html