Webnovel Dashboard Skill

概述

此技能用于在本地启动只读 Web 面板，实时查看网文创作进度、设定词典、关系图谱、章节内容与追读力数据。面板为纯只读，不提供修改接口。

触发条件

• 用户说"打开面板"、"启动 Dashboard"、"查看项目状态"
• 用户说"显示章节列表"、"查看实体图谱"
• 需要直观查看项目整体进度和状态

环境准备

WORKSPACE_ROOT="${PWD}"

# 设置 Dashboard 目录（指向原项目 dashboard 目录，需用户配置）
DASHBOARD_DIR="C:/Users/Administrator/Desktop/ide/webnovel-writer-master/webnovel-writer/dashboard"

# 设置脚本目录
SCRIPTS_DIR="C:/Users/Administrator/Desktop/ide/webnovel-writer-master/webnovel-writer/scripts"

# 检查 Dashboard 模块是否存在
if [ ! -d "${DASHBOARD_DIR}" ]; then
  echo "ERROR: 未找到 dashboard 模块: ${DASHBOARD_DIR}" >&2
  exit 1
fi

> 重要：用户需要先确认 webnovel-writer-master 的 dashboard 目录路径，并配置 DASHBOARD_DIR 变量。

执行流程

Step 1：安装依赖并解析项目根目录

# 安装 Python 依赖
python -m pip install -r "${DASHBOARD_DIR}/requirements.txt" --quiet

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

补充要求：

• PROJECT_ROOT 必须解析成功
• 若依赖已安装，可重复执行，不视为错误

Step 2：准备 Python 模块路径并校验前端产物

# 设置 PYTHONPATH 以让 Python 找到 dashboard 模块
export PYTHONPATH="${DASHBOARD_DIR}/..:${PYTHONPATH:-}"

# 检查前端构建产物是否存在
if [ ! -f "${DASHBOARD_DIR}/frontend/dist/index.html" ]; then
  echo "ERROR: 缺少前端构建产物 ${DASHBOARD_DIR}/frontend/dist/index.html" >&2
  echo "提示：Dashboard 前端需要预先构建，或检查插件是否完整安装" >&2
  exit 1
fi

Step 3：启动 Dashboard

# 启动 Dashboard 服务
python -m dashboard.server --project-root "${PROJECT_ROOT}"

可选参数：

• --no-browser - 不自动打开浏览器，手动访问输出的 URL
• --port 9000 - 自定义端口（默认 8080）

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

• http://localhost:8080/api/story-runtime/health - Story Runtime 健康状态
• http://localhost:8080/api/preflight - 预检接口

Dashboard 功能说明

启动后，浏览器会自动打开 Dashboard 页面，主要功能包括：

1. 项目概览

• 书名、题材、目标字数/章数
• 当前进度（已写章数/字数）
• 项目完成度百分比

2. 章节管理

• 章节列表（已写/已规划/未写）
• 每章的状态、字数、审查分数
• 点击章节可查看正文内容

3. 实体图谱

• 角色关系图谱（可交互）
• 势力分布图
• 地点关联图

4. 设定词典

• 角色卡汇总
• 力量体系总览
• 世界观关键设定

5. 追读力数据

• 每章的追读力评分
• 爽点密度分布
• 钩子质量评估

6. Story Runtime 状态

• 主链健康状态（.story-system/ 合同树）
• latest commit 状态
• fallback 情况提示

注意事项

• Dashboard 为纯只读面板，不提供修改接口
• 文件读取必须限制在 PROJECT_ROOT 范围内
• 如需自定义端口，使用 --port <端口号>
• 默认只监听 localhost，不暴露外部网络

成功标准

• Dashboard 进程已启动且输出了可访问的 URL
• 浏览器可正常打开页面（或 --no-browser 模式下 URL 可手动访问）
• 页面显示项目数据（章节列表、实体图谱等）

故障恢复

| 故障 | 恢复方式 |

|------|---------|

| 依赖安装失败 | 检查 Python 版本和网络，手动 pip install -r requirements.txt |

| 前端 dist/ 缺失 | 确认插件完整安装，dist 应随插件打包；或运行前端构建命令 |

| 项目根解析失败 | 检查 .webnovel/state.json 是否存在，确认 WORKSPACE_ROOT 正确 |

| 端口占用 | 使用 --port <其他端口> 或关闭占用进程 |

| 页面空白/数据缺失 | 确认 .webnovel/ 下有 state.json、index.db 等数据文件 |

安全边界

• 只读操作，不修改任何项目文件
• 文件访问限制在 PROJECT_ROOT 范围内
• 不暴露外部网络（默认 localhost）

参考资料

| 文件 | 路径 |

|------|------|

| Dashboard 服务端 | webnovel-writer/dashboard/server.py |

| Dashboard 前端 | webnovel-writer/dashboard/frontend/ |

| Dashboard 路径守卫 | webnovel-writer/dashboard/path_guard.py |

| Dashboard 文件监控 | webnovel-writer/dashboard/watcher.py |