项目结构与运维

目录层级

Phase 5 运维口径

.story-system/：主链真源
accepted CHAPTER_COMMIT：唯一写后事实入口
.webnovel/state.json、index.db、summaries/、memory_scratchpad.json：投影/read-model
references/genre-profiles.md：fallback-only
preflight 与 dashboard 的 story_runtime / story-runtime/health 是第一观察点

系统涉及 4 层目录，使用前需要了解它们的区别：

层级	说明	示例
`WORKSPACE_ROOT`	Claude Code 工作区根目录	`D:\wk\novels`
`.claude/`	工作区级配置与项目指针	`D:\wk\novels\.claude\`
`PROJECT_ROOT`	某本书的项目根目录（由 `/webnovel-init` 创建）	`D:\wk\novels\凡人资本论`
`CLAUDE_PLUGIN_ROOT`	插件缓存目录（不在项目内，由 Marketplace 安装管理）	自动管理

工作区目录

workspace-root/
├── .claude/
│   ├── .webnovel-current-project   # 指向当前书项目根
│   └── settings.json
├── 小说A/                          # PROJECT_ROOT
├── 小说B/
└── ...

一个工作区可以包含多本书，通过 .webnovel-current-project 指针切换当前操作的书。

书项目目录（PROJECT_ROOT）

project-root/
├── .webnovel/            # 运行时数据
│   ├── state.json        # 项目状态
│   ├── index.db          # SQLite 索引（实体/关系/章节数据）
│   ├── vectors.db        # 向量索引
│   ├── summaries/        # 章节摘要
│   ├── backups/          # 自动备份
│   └── archive/          # 归档
├── .story-system/        # Story System 数据
│   ├── MASTER_SETTING.json
│   ├── chapters/
│   ├── volumes/
│   ├── reviews/
│   ├── commits/
│   └── events/
├── 正文/                  # 正文章节
├── 大纲/                  # 总纲与卷纲
├── 设定集/                # 世界观、角色、力量体系
└── 审查报告/              # 审查输出

插件目录

插件安装在 Claude 插件缓存目录，不在书项目内。运行时通过 CLAUDE_PLUGIN_ROOT 引用：

${CLAUDE_PLUGIN_ROOT}/
├── skills/       # 7 个 Skill 命令定义
├── agents/       # 3 个 Agent 定义
├── scripts/      # Python 脚本与数据模块
├── references/   # 参考文档（题材画像、追读力分类法等）
├── templates/    # 初始化模板
├── genres/       # 精调题材配置
└── dashboard/    # 可视化面板前端

用户级全局映射

当工作区指针不可用时，系统会从用户级 registry 查找 workspace → project 映射：

${CLAUDE_HOME:-~/.claude}/webnovel-writer/workspaces.json

常用运维命令

环境预检

python -X utf8 "${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py" --project-root "${WORKSPACE_ROOT}" preflight

检查项：插件脚本路径 / 项目根是否可解析 / Skill 目录是否存在。

若 story_runtime.mainline_ready=false，说明当前项目仍在 legacy fallback 或 commit 主链不完整。

索引重建

python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index process-chapter --chapter 1
python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index stats

健康报告

python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus all
python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus urgency

向量重建

python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" rag index-chapter --chapter 1
python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" rag stats

测试

pwsh "${CLAUDE_PLUGIN_ROOT}/scripts/run_tests.ps1" -Mode smoke
pwsh "${CLAUDE_PLUGIN_ROOT}/scripts/run_tests.ps1" -Mode full

Story System 运维

健康检查

python -X utf8 "${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py" --project-root "${PROJECT_ROOT}" story-events --health

返回字段：sqlite_rows / event_files / ok

重点关注：

.story-system/commits/chapter_XXX.commit.json 是否存在且为 accepted
projection_status 是否全部为 done / skipped
.story-system/events/ 是否可读
index.db 中 story_events 表是否可查
override_contracts 是否能统计 amend_proposal

备份

做 Story System 相关备份时，至少同时备份以下内容：

.story-system/
.webnovel/index.db

operations.md 4.7 KB لینک دائمی تاريخچه خام