webnovel-dashboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Webnovel Dashboard

目标

Objectives

在本地启动只读 Web 面板，查看创作进度、设定词典、关系图谱、章节内容与追读力数据。
暴露 Story Runtime 主链状态：
```
/api/story-runtime/health
```
、latest commit、fallback 情况。
可监听
```
.webnovel/
```
变化，但不修改任何项目文件。

Launch a local read-only web panel to view writing progress, setting dictionary, relationship graph, chapter content, and followership data.
Expose Story Runtime main chain status:
```
/api/story-runtime/health
```
, latest commit, and fallback status.
Can monitor changes in
```
.webnovel/
```
, but does not modify any project files.

执行流程

Execution Process

Step 1：确认环境与模块目录

Step 1: Confirm Environment and Module Directory

bash

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"

bash

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：解析项目根目录

Step 2: Resolve Project Root Directory

bash

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

PROJECT_ROOT

必须解析成功。

bash

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

PROJECT_ROOT

must be resolved successfully.

Step 3：校验前端产物与依赖

Step 3: Validate Frontend Build Artifacts and Dependencies

bash

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

不默认安装依赖。仅当 Step 4 因缺依赖启动失败时，提示用户手动执行：

bash

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

bash

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

Dependencies are not installed by default. Only if Step 4 fails to start due to missing dependencies, prompt the user to manually execute:

bash

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

Step 4：启动 Dashboard

Step 4: Launch Dashboard

bash

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

不自动打开浏览器时加

--no-browser

；自定义端口加

--port 9000

。

启动后优先确认接口可用：

/api/story-runtime/health

、

/api/preflight

。

bash

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

Add

--no-browser

to prevent automatically opening the browser; add

--port 9000

to customize the port.

After launching, first confirm that the interfaces are available:

/api/story-runtime/health

/api/preflight

成功标准

Success Criteria

Dashboard 进程已启动并输出可访问 URL；页面显示项目数据（章节列表、实体图谱等）。

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

失败恢复

Failure Recovery

故障	恢复方式
启动报缺依赖	手动 `pip install -r "${DASHBOARD_DIR}/requirements.txt"` ，检查 Python 版本与网络
前端 `dist/` 缺失	确认插件完整安装，dist 应随插件打包
项目根解析失败	检查 `.webnovel/state.json` 是否存在，确认 `WORKSPACE_ROOT` 正确
端口占用	用 `--port <其他端口>` 或关闭占用进程
页面空白/数据缺失	确认 `.webnovel/` 下有 state.json、index.db 等数据文件

Fault	Recovery Method
Missing dependencies reported during startup	Manually run `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 if `.webnovel/state.json` exists, confirm `WORKSPACE_ROOT` is correct
Port occupied	Use `--port <other port>` or close the occupying process
Blank page/missing data	Confirm there are data files like state.json, index.db under `.webnovel/`

安全边界

Security Boundaries

纯只读面板，不提供修改接口，不修改任何项目文件。
文件访问限制在
```
PROJECT_ROOT
```
范围内，默认仅监听 localhost。

Pure read-only panel, no modification interfaces provided, no project files modified.
File access is restricted within the
```
PROJECT_ROOT
```
scope, and only localhost is monitored by default.