imraywang/rayskills-lab/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 替换，并逐项报告。作为上游真源的知识库（仪表盘在那里开发、再同步到 rays-brain-kit 的那个库）不升级：check 显示的 different 是它领先或有意的个人化（如启动脚本带 --tailnet），升级会用脱敏的发布版覆盖它。
5. 启动的完成标准是 healthz 探测通过并交付可点击 URL，不以"命令没报错"为完成。
6. 开机自启是持久配置，只在用户明确要求时按 autostart.md 配置。
7. 本 skill 只装仪表盘和两份协议，不装采集管线、发布归档脚本和 50-系统/30-模板/ 下的反馈卡与成稿包模板。工作台里的「让 Codex 起草」依赖 知识采集/knowledge_ingest.py，「登记发布」依赖 发布归档/record_published.py 和 内容反馈.md、口播视频反馈.md、内容成稿包.md 三份模板；只装本 skill 的库这两个动作会报「找不到脚本」。反馈卡上的网页复盘（下结论、填平台数据）依赖 反馈复盘/feedback_snapshot.py，缺它时入口自动隐藏，不报错。用户要用它们时，明确告知需要完整的 rays-brain-kit，不在本 skill 内补写这些脚本。

1. 确定知识库根目录

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

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

2. 先检查，后动手

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 列出本次补齐的默认协议（只补缺失，从不覆盖已有）：

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. 启动、停止与验收

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 逐项排查。诊断请求只诊断——交付根因与恢复命令，不代为启停服务，更不得借机升级或改配置；用户明确让你修，才动手。

完成标准

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

上游

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

资产里的 test_server.py 可以在 skill 目录单独运行：缺上游模板时用占位，缺发布归档脚本的 3 个集成测试和缺反馈复盘脚本的 1 个测试会跳过，其余应全部通过。