# Ray Dashboard

> 在用户的本地知识库上安装、启动、升级或诊断"知识工作台"——一个零依赖的本地网页仪表盘（总览、审核队列、进展看板、搜索、灵感速记）。用于"给我的知识库装个工作台""启动/重启仪表盘""工作台打不开或数据不对""升级工作台"时；知识库结构可先用 ray-obsidian 搭建。只监听本机、不修改用户笔记、不覆盖用户配置、不擅自配置开机自启。

- Skill: `imraywang/ray-dashboard` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add imraywang/ray-dashboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/imraywang/ray-dashboard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: imraywang (https://skillmd.com/u/imraywang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/imraywang/ray-dashboard

---


# Ray Dashboard

把一个随 vault 存放的本地工作台装进用户的知识库并保证它真的能用。仪表盘是入口层，不是第二套笔记系统：Markdown 仍是唯一真源。

> **孵化状态**：首个 lab 住户。安装/启动/停止/升级/诊断链路已实测；launchd 常驻自启只有文档还没有自动化；Windows/Linux 的 stop 依赖 lsof 回退，未充分验证。

## 固定原则

1. 仪表盘默认只监听 `127.0.0.1`。只有用户明确要求手机通过自己的 Tailscale 网络访问时才加 `--tailnet`；不监听局域网地址，不做公网端口转发建议。
2. 不读取、不修改、不移动用户笔记；安装只写 `50-系统/40-自动化/知识仪表盘/` 一个目录，外加在其上一级补齐缺失的 `review_protocol.json` / `board_protocol.json` 默认协议（已有协议是管线数据，一律不动、不覆盖）。
3. `config.json` 是用户数据，任何命令任何情况下不覆盖。
4. 用户已改动的代码文件默认保留；只有用户明确要求升级时才用 `--upgrade` 替换，并逐项报告。
5. 启动的完成标准是 healthz 探测通过并交付可点击 URL，不以"命令没报错"为完成。
6. 开机自启是持久配置，只在用户明确要求时按 [autostart.md](references/autostart.md) 配置。

## 1. 确定知识库根目录

与 ray-obsidian 同一套定位顺序：用户明确给出的目录 → `.ray-obsidian.json` → 同时存在 `10-创作/`、`20-知识/`、`30-资料/`、`50-系统/` 的兼容库 → 只问一个问题。确定后先报告绝对路径。

vault 还没有结构时，先建议用 ray-obsidian 搭骨架；用户不想装 skill 也可以用仪表盘自带的 `bootstrap.py`（支持 `--demo` 演示数据）。

## 2. 先检查，后动手

```bash
python3 <skill-base>/scripts/dashboard_setup.py check --vault <知识库目录>
```

按 `status` 分流：`not-installed` 走安装；`incomplete` 补装（含 `missing_protocols` 非空——协议缺失时审核/流转功能会降级关闭，补装即恢复）；`different` 只说明本地与资产不同，不能据此断定哪一边更新，先出示 `differs` 清单再决定保留还是升级；`installed` 直接进入启动或诊断。`server.running` 为 true 时不要重复启动。

## 3. 安装与升级

先预演再执行；升级必须出示 `kept_local_changes` 与 `upgraded` 清单；`seeded_protocols` 列出本次补齐的默认协议（只补缺失，从不覆盖已有）：

```bash
python3 <skill-base>/scripts/dashboard_setup.py install --vault <目录> --dry-run
python3 <skill-base>/scripts/dashboard_setup.py install --vault <目录>            # 只补缺失文件
python3 <skill-base>/scripts/dashboard_setup.py install --vault <目录> --upgrade  # 用户要求升级时
```

## 4. 启动、停止与验收

```bash
python3 <skill-base>/scripts/dashboard_setup.py start --vault <目录> [--port 8765] [--open] [--tailnet]
python3 <skill-base>/scripts/dashboard_setup.py stop [--port 8765]
```

`start` 成功会返回 URL 与日志位置（它内部已完成 healthz 验收；手动复核时端点是 `/api/healthz`，不是 `/healthz`）。交付时告诉用户：浏览器"安装应用"（或 Safari"添加到程序坞"）可获得独立窗口；审核队列支持 `J/K` `1-5` 键盘流；顶栏 🔔 可开系统通知。`--tailnet` 只在用户明确需要手机访问时使用。

## 5. 诊断

用户说"打不开""空白""数据不对"时，先 `status` 再对照 [diagnose.md](references/diagnose.md) 逐项排查。诊断请求只诊断——交付根因与恢复命令，不代为启停服务，更不得借机升级或改配置；用户明确让你修，才动手。

## 完成标准

- check 的 status 与用户诉求一致（装完为 `installed`，升级后无 `differs`），且使用 `ray-content-v2` 的现行候选、写作任务和母稿路径。
- 服务 healthz 探测通过，用户拿到可点击的 URL。
- 升级/保留的文件清单已逐项呈现；`config.json` 从未被改写。
- 用户只要求其中一件事时，没有顺手做另外几件。

## 上游

资产副本来自 rays-brain-kit（工作台 + 采集管线的完整仓库）。更新资产时从上游整目录同步，不在本 skill 内单独修改仪表盘代码。