Install a local workbench stored alongside the vault into the user's knowledge base and make sure it actually works. The dashboard is an entry layer, not a second note-taking system: Markdown remains the single source of truth.
Incubation status: the first lab resident. The install/start/stop/upgrade/diagnose chain has been tested in practice; launchd persistent auto-start only has documentation and no automation yet; stop on Windows/Linux relies on an lsof fallback and has not been fully verified.
Fixed principles
- By default the dashboard only listens on
127.0.0.1. Only add--tailnetwhen the user explicitly requests that a phone access it through their own Tailscale network; do not listen on LAN addresses, and do not suggest public port forwarding. - Do not read, modify, or move the user's notes; installation only writes to
50-系统/40-自动化/知识仪表盘/one directory, plus filling in the missingreview_protocol.json/board_protocol.jsondefault protocol at its parent level (existing protocols are pipeline data; never touch or overwrite them). config.jsonis user data; no command overwrites it under any circumstances.- Code files the user has modified are kept by default; only replace them with
--upgradewhen the user explicitly requests an upgrade, and report item by item. - The completion criterion for startup is that the healthz probe passes and a clickable URL is delivered; "the command didn't error" does not count as completion.
- Auto-start at boot is a persistent configuration; configure it per autostart.md only when the user explicitly requests it.
- This skill only installs the dashboard and two protocols; it does not install the collection pipeline, the publish/archive scripts, or the feedback card and final draft package templates under
50-系统/30-模板/. "Have Codex draft" in the workbench depends on知识采集/knowledge_ingest.py, and "register publication" depends on发布归档/record_published.pyand内容反馈.md、口播视频反馈.md、内容成稿包.mdthree templates; in a vault where only this skill is installed, these two actions will report "script not found". The web review on the feedback card (drawing conclusions, filling in platform data) depends on反馈复盘/feedback_snapshot.py; when it is missing, the entry is automatically hidden without error. When the user wants to use them, clearly state that the complete rays-brain-kit is required, and do not write these scripts within this skill.
1. Determine the knowledge base root directory
Same location order as ray-obsidian: the directory explicitly given by the user → .ray-obsidian.json → a compatible vault where 10-创作/、20-知识/、30-资料/、50-系统/ both exist → ask only one question. After determining it, first report the absolute path.
When the vault does not yet have a structure, first suggest using ray-obsidian to build the skeleton; if the user does not want to install a skill, they can also use the dashboard's built-in bootstrap.py(supports --demo demo data).
2. Check first, then act
python3 <skill-base>/scripts/dashboard_setup.py check --vault <知识库目录>
Branch by status :not-installed go to installation;incomplete supplementary installation (including missing_protocols non-empty — when the protocol is missing, review/flow functions are degraded and disabled; supplementary installation restores them);different only explain that the local and asset versions differ; do not conclude from this which side is newer; first present the differs list, then decide whether to keep or upgrade;installed go directly to startup or diagnosis.server.running When true, do not start repeatedly.
3. Installation and upgrade
Rehearse first, then execute; an upgrade must present the kept_local_changes and upgraded lists;seeded_protocols List the default protocols backfilled this time (only fill in missing ones, never overwrite existing ones):
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. Start, stop, and acceptance
python3 <skill-base>/scripts/dashboard_setup.py start --vault <目录> [--port 8765] [--open] [--tailnet]
python3 <skill-base>/scripts/dashboard_setup.py stop [--port 8765]
start On success it returns the URL and log location (it has already completed the healthz acceptance internally; for manual re-checking the endpoint is /api/healthz, not /healthz). When delivering, tell the user: the browser's "Install app" (or Safari's "Add to Dock") gives an independent window; the review queue supports J/K 1-5 keyboard flow; the top bar 🔔 can enable system notifications.--tailnet Use only when the user explicitly needs mobile access.
5. Diagnostics
When the user says "can't open it", "blank", or "the data is wrong", first status then check item by item against diagnose.md . Diagnostic requests are diagnostics only—deliver the root cause and recovery commands, do not start or stop services on their behalf, and certainly do not use the opportunity to upgrade or change configuration; only act once the user explicitly asks you to fix it.
Completion criteria
- check's status matches the user's request (after installation it is
installed, after upgrade there is nodiffers), and usesray-content-v2's current candidates, writing tasks, and master draft paths. - The service healthz probe passes, and the user gets a clickable URL.
- The list of upgraded/retained files has been presented item by item;
config.jsonwas never rewritten. - When the user asked for only one of these things, the other things were not done in passing.
Upstream
The asset copy comes from rays-brain-kit (the complete repository of the workbench + collection pipeline). When updating assets, sync the entire directory from upstream; do not modify the dashboard code separately within this skill.
The test_server.py in the assets can be run separately in the skill directory: use placeholders when upstream templates are missing, and the 3 integration tests that lack the release archive script will be skipped; all the rest should pass.