---
name: webnovel-dashboard
description: 启动小说管理面板，查看项目状态、编辑文风约束。
compatibility: opencode
---

# Webnovel Dashboard

## 目标

在本地启动 Web 面板，查看创作进度、设定词典、关系图谱、章节内容与追读力数据，并可编辑文风约束。

## 功能概览

| 页面 | 路由 | 功能 |
|------|------|------|
| 总览 | `/` | 统计卡片、章节趋势、告警、伏笔提醒 |
| 上下文健康 | `/context` | Token 预算、Section 状态、权重分布、历史趋势 |
| 角色图鉴 | `/characters` | 实体列表、关系图谱、**时间线（状态变化+出场记录+异常检测）** |
| 审查分析 | `/review` | 维度雷达图、严重程度分布、趋势折线图、Critical Issues |
| 节奏雷达 | `/pacing` | 钩子强度、strand 分布、字数箱线图 |
| 伏笔追踪 | `/foreshadowing` | 伏笔甘特图、债务表 |
| 文档浏览 | `/files` | 文件树、正文预览 |
| **文风约束** | `/style` | **编辑文风约束（6 Tab：自定义文风+全局+禁止+技法+合同+审查维度）** |
| 系统状态 | `/system` | 合同树、提交历史、RAG 环境、运维操作、**批量操作** |

### 主题

支持亮色/暗色模式切换（侧边栏右上角 🌙/☀️ 按钮），偏好持久化到 localStorage。

## 文风约束编辑器（/style）

6 个 Tab：自定义文风（`设定集/prompts/*.md`，读写）、全局文风（`MASTER_SETTING.json`，读写）、禁止模式（`anti_patterns.json`，读写）、写作技法（CSV，只读）、章级合同（只读）、审查维度（只读）。

## API 参考

写入 API（8 个）、只读 API（6 个）、配置说明见 `references/dashboard-api.md`。

## 环境设置

```bash
# 以下命令假设当前目录为 webnovel-writer 仓库根目录
export SCRIPTS_DIR="${PWD}/.opencode/scripts"
export DASHBOARD_DIR="${PWD}/.opencode/dashboard"
test -d "${DASHBOARD_DIR}" || { echo "错误: 未找到 ${DASHBOARD_DIR}，请确保当前目录是 webnovel-writer 仓库根目录"; exit 1; }
```

## 执行流程

### Step 1：安装依赖

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

### Step 2：解析项目路径 + 校验前端

```bash
export PROJECT_ROOT="$(python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PWD}" where)"
test -n "$PROJECT_ROOT" && test -f "${PROJECT_ROOT}/.webnovel/state.json" || { echo "错误: PROJECT_ROOT 解析失败，请用 --project-root 显式指定"; exit 1; }
echo "项目路径: ${PROJECT_ROOT}"

test -f "${DASHBOARD_DIR}/frontend/dist/index.html" || { echo "错误: 缺少前端构建产物 ${DASHBOARD_DIR}/frontend/dist/index.html"; exit 1; }
```

### Step 3：启动 Dashboard（后台运行）

> Dashboard 是长运行服务（uvicorn），必须用后台模式启动。命令中设置 `run_in_background: true`。

```bash
PYTHONPATH="${PWD}/.opencode" python -X utf8 -m dashboard.server --project-root "${PROJECT_ROOT}"
```

默认端口 8765，访问 `http://127.0.0.1:8765`。

自定义端口：
```bash
PYTHONPATH="${PWD}/.opencode" python -X utf8 -m dashboard.server --project-root "${PROJECT_ROOT}" --port 9000 --no-browser
```

自动关闭旧进程并启动：
```bash
PYTHONPATH="${PWD}/.opencode" python -X utf8 -m dashboard.server --project-root "${PROJECT_ROOT}" --kill-existing --no-browser
```

### Step 4：验证服务

```bash
curl -s http://127.0.0.1:8765/api/story-runtime/health || echo "服务未启动"
curl -s http://127.0.0.1:8765/api/style/master-setting || echo "文风编辑器不可用"
```

## 项目根目录解析

`server.py` 按以下优先级解析项目根目录：

1. `--project-root` 参数
2. `WEBNOVEL_PROJECT_ROOT` 环境变量
3. CWD 向上搜索（找到包含 `.webnovel/state.json` 的目录）
4. `.opencode/.webnovel-current-project` 指针文件
5. 智能搜索同级目录（支持嵌套结构如 `E:\workspace\webnovel\书名\`）

## 注意事项

- Dashboard 提供只读查询 + 文风约束编辑（写入操作限于 master_constraints 和 anti_patterns）
- uvicorn 默认监听 `127.0.0.1:8765`
- 首次启动可能需安装依赖（`pip install -r requirements.txt`）
- Windows 中文输出乱码：运行 `chcp 65001` 后重试
- 端口被占用时自动检测并提示，可用 `--kill-existing` 自动关闭旧进程

## 失败恢复

| 故障 | 恢复方式 |
|------|---------|
| 依赖安装失败 | 检查 Python 版本，手动 `pip install -r requirements.txt` |
| 前端 `dist/` 缺失 | 确认插件完整安装 |
| PROJECT_ROOT 解析失败 | 显式传 `--project-root` 或设置 `WEBNOVEL_PROJECT_ROOT` 环境变量 |
| 端口占用 | 使用 `--kill-existing` 自动关闭旧进程，或 `--port <其他端口>` |
| 服务被 timeout 终止 | 确保使用后台模式（`run_in_background: true`）启动 |
| 页面空白/数据缺失 | 确认 `.webnovel/` 下有 state.json、index.db 等数据文件 |