webnovel-dashboard

Webnovel Dashboard

Goal

• Start a local read-only web panel to view writing progress, setting dictionary, relationship graph, chapter content, and reading-retention data.
• Expose Story Runtime main-chain status:/api/story-runtime/health, latest commit, fallback situation.
• Can watch for changes to .webnovel/ , but does not modify any project files.

Execution flow

Step 1: Confirm environment and module directory

export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"

if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/dashboard" ]; then
  echo "ERROR: 未找到 dashboard 模块: ${CLAUDE_PLUGIN_ROOT}/dashboard" >&2
  exit 1
fi

export DASHBOARD_DIR="${CLAUDE_PLUGIN_ROOT}/dashboard" export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"

### Step 2：解析项目根目录

```bash
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
echo "项目路径: ${PROJECT_ROOT}"

PROJECT_ROOT must resolve successfully.

Step 3: Validate frontend artifacts and dependencies

if [ -n "${PYTHONPATH:-}" ]; then
  export PYTHONPATH="${CLAUDE_PLUGIN_ROOT}:${PYTHONPATH}"
else
  export PYTHONPATH="${CLAUDE_PLUGIN_ROOT}"
fi

if [ ! -f "${DASHBOARD_DIR}/frontend/dist/index.html" ]; then
  echo "ERROR: 缺少前端构建产物 ${DASHBOARD_DIR}/frontend/dist/index.html（dist 应随插件打包，确认插件完整安装）" >&2
  exit 1
fi

Do not install dependencies by default. Only when Step 4 fails to start due to missing dependencies, prompt the user to manually run:

python -m pip install -r "${DASHBOARD_DIR}/requirements.txt"

Step 4: Start Dashboard

python -m dashboard.server --project-root "${PROJECT_ROOT}"

When not automatically opening the browser, add --no-browser; for a custom port, add --port 9000。

After startup, confirm the interface is available first:/api/story-runtime/health、/api/preflight。

Success criteria

• The Dashboard process has started and outputs an accessible URL; the page displays project data (chapter list, entity graph, etc.).

Failure recovery

Fault	Recovery method
Startup reports missing dependencies	Manually pip install -r "${DASHBOARD_DIR}/requirements.txt", check Python version and network
Frontend dist/ missing	Confirm the plugin is fully installed; dist should be packaged with the plugin
Project root resolution failed	Check whether .webnovel/state.json exists, and confirm WORKSPACE_ROOT is correct
Port occupied	Use --port <其他端口> or close the occupying process
Blank page/missing data	Confirm that under .webnovel/ there are data files such as state.json and index.db

Security boundaries

• Pure read-only panel, provides no modification interface, and does not modify any project files.
• File access is restricted within the scope of PROJECT_ROOT , and by default only listens on localhost.