feat: 引入官方插件机制并修复命令调用

.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "webnovel-writer-marketplace",
+  "description": "Marketplace for the webnovel-writer Claude Code plugin.",
+  "metadata": {
+    "description": "Marketplace for installing the webnovel-writer plugin."
+  },
+  "owner": {
+    "name": "lingfengQAQ"
+  },
+  "plugins": [
+    {
+      "name": "webnovel-writer",
+      "description": "长篇网文创作系统（skills + agents + data chain + RAG）",
+      "version": "5.4.4",
+      "author": {
+        "name": "lingfengQAQ"
+      },
+      "source": "./webnovel-writer",
+      "category": "productivity",
+      "homepage": "https://github.com/lingfengQAQ/webnovel-writer"
+    }
+  ]
+}

.gitignore

@@ -21,8 +21,10 @@ Thumbs.db
 # Workspace artifacts
 node_modules/
 .npm-cache/
+dist/
 nul
 .tmp/
+.tmp_*
 .tmp_outline_check/
 
 # Local research / sibling projects (avoid accidental commit)

README.md

@@ -127,29 +127,38 @@
 | Claude Code | 最新版 | Anthropic 官方 CLI 工具 |
 | Git | 任意版本 | 版本控制和章节备份 |
 
-### 1. 安装
+### 1. 通过 Marketplace 安装插件（推荐）
 
 ```bash
-# 进入你的小说项目目录
-cd your-novel-project
+# 添加 GitHub 仓库为 marketplace（用户级，全局可用）
+claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
 
-# 克隆插件到 .claude 目录
-git clone https://github.com/lingfengQAQ/webnovel-writer.git .claude
+# 安装插件（指定 marketplace，避免重名冲突）
+claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user
 
-# 安装 Python 依赖
-pip install -r .claude/scripts/requirements.txt
+# 安装 Python 依赖（必做）
+python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/webnovel-writer/scripts/requirements.txt
+
+# 可选：确认安装状态
+claude plugin list
 ```
 
-推荐：统一使用 `.claude/scripts/webnovel.py` 作为 CLI 入口，避免 `PYTHONPATH` / `cd` / 参数顺序导致的报错。
+> 若你只想当前项目生效：在项目目录执行，并把 `--scope user` 改为 `--scope project`。
 
-```bash
-# 推荐：先解析真实项目根（支持把工作区根传进去）
-export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-export SCRIPTS_DIR="${WORKSPACE_ROOT}/.claude/scripts"
-export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
+PowerShell 同样可用（命令一致）：
+
+```powershell
+claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
+claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user
+python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/webnovel-writer/scripts/requirements.txt
 ```
 
-若你需要直接调试底层模块（不推荐），再临时设置 `PYTHONPATH=.claude/scripts`。
+**官方插件机制说明**：
+- Marketplace 清单位于仓库根目录 `.claude-plugin/marketplace.json`。
+- 插件清单位于 `webnovel-writer/.claude-plugin/plugin.json`。
+- 运行时 Skills/Agents 统一通过 `CLAUDE_PLUGIN_ROOT` 定位资源，不再依赖旧的 `.claude/scripts` 路径探测。
+
+推荐：统一使用 `webnovel.py` 作为 CLI 入口，避免 `PYTHONPATH` / `cd` / 参数顺序导致的报错。
 
 **Python 依赖说明**：
 
@@ -173,22 +182,75 @@ export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WOR
 - 选择题材类型
 - 设计金手指/核心卖点
 - 生成项目结构和设定模板
+- 自动写入当前项目绑定（workspace pointer + 全局 registry）
+
+> 说明：如果你只使用 `/webnovel-*` 命令，**不需要手动解析 PROJECT_ROOT**。
+> 只有在你要手动执行 Python CLI 时，才需要下面这一步。
+
+### 3. （可选）手动 CLI 时解析项目根
+
+```bash
+export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
+  exit 1
+fi
+export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
+
+# 把“工作区根”解析为“真实书项目根”
+export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
+echo "${PROJECT_ROOT}"
+```
 
-### 3. 规划大纲
+### 4. 配置 RAG 环境（必做）
+
+```bash
+# 进入书项目根目录
+cd "${PROJECT_ROOT}"
+
+# 复制模板并填写 API Key（/webnovel-init 会生成 .env.example）
+cp .env.example .env
+```
+
+PowerShell 可用：
+
+```powershell
+Set-Location $env:PROJECT_ROOT
+Copy-Item .env.example .env -Force
+```
+
+`.env` 至少配置以下字段（建议全部配置）：
+
+```bash
+EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
+EMBED_MODEL=Qwen/Qwen3-Embedding-8B
+EMBED_API_KEY=your_embed_api_key
+
+RERANK_BASE_URL=https://api.jina.ai/v1
+RERANK_MODEL=jina-reranker-v3
+RERANK_API_KEY=your_rerank_api_key
+```
+
+说明：
+- 若未配置 Embedding Key，RAG 语义检索会降级为 BM25。
+- 支持用户级全局配置文件：`~/.claude/webnovel-writer/.env`（项目级 `.env` 优先）。
+
+### 5. 规划大纲
 
 ```bash
 # 规划第1卷大纲
 /webnovel-plan 1
 ```
 
-### 4. 开始创作
+### 6. 开始创作
 
 ```bash
 # 创作第1章
 /webnovel-write 1
 ```
 
-### 5. 质量审查（可选）
+### 7. 质量审查（可选）
 
 ```bash
 # 审查第1-5章
@@ -546,6 +608,16 @@ RERANK_API_KEY=jina_xxx
 
 ## 配置说明
 
+### 环境变量加载顺序（重要）
+
+RAG 相关环境变量（`EMBED_*` / `RERANK_*`）按以下顺序加载：
+
+1. 进程已设置的环境变量（最高优先级）
+2. 书项目根目录下的 `.env`
+3. 用户级全局：`~/.claude/webnovel-writer/.env`
+
+建议优先把项目专属配置写在 `${PROJECT_ROOT}/.env`，避免多项目串台。
+
 ### 核心配置 (`config.py`)
 
 ```python
@@ -585,7 +657,7 @@ context_rag_assist_max_query_chars = 120   # 查询截断长度
 
 ## 文档归类
 
-- 当前基线文档：`README.md`、`CLAUDE.md`、`.claude/references/*.md`、`.claude/references/shared/*.md`
+- 当前基线文档：`README.md`、`CLAUDE.md`、`webnovel-writer/references/*.md`、`webnovel-writer/references/shared/*.md`
 - 历史归档文档：`docs/archive/reports/`
 - 文档状态规则：`docs/doc-lifecycle.md`
 - 本地未跟踪归类：`docs/untracked-classification.md`
@@ -594,9 +666,12 @@ context_rag_assist_max_query_chars = 120   # 查询截断长度
 
 ## 项目结构
 
+> Marketplace 安装模式下，插件文件位于 Claude 插件缓存目录（不在项目内）。
+> 下方目录树展示的是“本地拷贝 `webnovel-writer` 到项目内”的形态，便于理解完整结构。
+
 ```
 your-novel-project/
-├── .claude/                    # 插件目录
+├── webnovel-writer/            # 插件目录
 │   ├── agents/                 # 8 个专职 Agent
 │   │   ├── context-agent.md    # 创作任务书工程师
 │   │   ├── data-agent.md       # 数据链工程师
@@ -673,7 +748,11 @@ your-novel-project/
 
 ```bash
 export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-export SCRIPTS_DIR="${WORKSPACE_ROOT}/.claude/scripts"
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
+  exit 1
+fi
+export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
 export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
 ```
 
@@ -726,32 +805,32 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index get-r
 
 ```bash
 # 生成最近20条记录的质量趋势报告
-python "${SCRIPTS_DIR}/quality_trend_report.py" --project-root "${WORKSPACE_ROOT}" --limit 20
+python "${SCRIPTS_DIR}/quality_trend_report.py" --project-root "${PROJECT_ROOT}" --limit 20
 ```
 
-说明：`quality_trend_report.py` 支持传入工作区根，会自动解析到真实书项目根后写入 `.webnovel/`。
+说明：`quality_trend_report.py` 支持直接传入真实书项目根并写入 `.webnovel/`。
 
 ### 测试入口脚本
 
 ```bash
 # 快速回归（推荐）
-pwsh .claude/scripts/run_tests.ps1 -Mode smoke
+pwsh webnovel-writer/scripts/run_tests.ps1 -Mode smoke
 
 # 全量 data_modules 测试
-pwsh .claude/scripts/run_tests.ps1 -Mode full
+pwsh webnovel-writer/scripts/run_tests.ps1 -Mode full
 ```
 
 ### 健康报告（status_reporter）
 
 ```bash
 # 全量健康报告
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status --focus all
+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}" status -- --focus urgency
 
 # 仅看爽点节奏
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status --focus pacing
+python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus pacing
 ```
 
 说明：
@@ -762,7 +841,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status --fo
 ### Claude Code 调用责任（重要）
 
 - 本项目脚本默认由 Claude Code 的 Skill/Agent 在流程节点自动触发，不以人工手动调用为主。
-- 详细“谁调用、何时调用、调用什么”见：`.claude/references/claude-code-call-matrix.md`。
+- 详细“谁调用、何时调用、调用什么”见：`webnovel-writer/references/claude-code-call-matrix.md`。
 
 ### 向量重建
 
@@ -794,13 +873,14 @@ git checkout ch0045
 
 | 版本 | 里程碑 |
 |------|--------|
-| **v5.4.3 (当前)** | 智能 RAG 辅助上下文（按需触发 `auto/graph_hybrid`，失败回退 BM25）；关系事件图谱与 Graph-RAG 链路完善 |
+| **v5.4.4 (当前)** | 引入官方 Claude Code Plugin Marketplace 安装机制（仓库可直接安装）；统一修复 Skills/Agents/References 的 CLI 调用（`CLAUDE_PLUGIN_ROOT` 单路径，`status/context/update-state/migrate` 透传统一使用 `--` 分隔） |
+| **v5.4.3** | 智能 RAG 辅助上下文（按需触发 `auto/graph_hybrid`，失败回退 BM25）；关系事件图谱与 Graph-RAG 链路完善 |
 | **v5.4.x** | Context Contract v2 完成（reader_signal / genre_profile / writing_guidance / checklist_score / 动态预算）；审查趋势与调用可观测性 |
 | **v5.3** | 追读力系统落地（Hook/Cool-point/微兑现分类、Hard/Soft 约束、Override Contract、债务追踪） |
 | **v5.2** | 写作流程升级（Step 1.5 章节设计、reader-pull-checker、摘要分离到 `.webnovel/summaries/`） |
 | **v5.1-v5.0** | 双 Agent 基础架构 + SQLite 索引化（state 精简、实体/别名/状态变化入库） |
 
-详细阶段性变更请参考提交历史与 `.claude/references/` 下对应规范文档。
+详细阶段性变更请参考提交历史与 `webnovel-writer/references/` 下对应规范文档。
 
 ---
 

webnovel-writer/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "webnovel-writer",
+  "version": "5.4.4",
+  "description": "长篇网文创作系统（skills + agents + data chain + RAG）",
+  "author": {
+    "name": "lingfengQAQ"
+  },
+  "homepage": "https://github.com/lingfengQAQ/webnovel-writer",
+  "repository": "https://github.com/lingfengQAQ/webnovel-writer",
+  "license": "GPL-3.0",
+  "keywords": [
+    "webnovel",
+    "claude-code",
+    "skills",
+    "agents",
+    "rag"
+  ]
+}

.claude/agents/consistency-checker.md → webnovel-writer/agents/consistency-checker.md

@@ -8,7 +8,7 @@ tools: Read, Grep, Bash
 
 > **Role**: Continuity guardian enforcing the second anti-hallucination law (设定即物理 - Settings are Physics).
 
-> **输出格式**: 遵循 `.claude/references/checker-output-schema.md` 统一 JSON Schema
+> **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## Scope
 
@@ -170,19 +170,12 @@ Chapters {N} - {M}
 对于发现的 **CRITICAL** 级别问题，自动标记到 invalid_facts（pending）：
 
 ```bash
-# 解析脚本目录（优先项目内，其次父目录工作区，其次用户目录，其次插件目录）
-if [ -d "{PROJECT_ROOT}/.claude/scripts" ]; then
-  SCRIPTS_DIR="{PROJECT_ROOT}/.claude/scripts"
-elif [ -d "{PROJECT_ROOT}/../.claude/scripts" ]; then
-  SCRIPTS_DIR="{PROJECT_ROOT}/../.claude/scripts"
-elif [ -d "${HOME}/.claude/scripts" ]; then
-  SCRIPTS_DIR="${HOME}/.claude/scripts"
-elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-else
-  echo "ERROR: 未找到 scripts 目录（.claude/scripts）" >&2
+# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
   exit 1
 fi
+SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
 
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "{PROJECT_ROOT}" index mark-invalid \
   --source-type entity \

.claude/agents/context-agent.md → webnovel-writer/agents/context-agent.md

@@ -11,10 +11,10 @@ tools: Read, Grep, Bash
 
 ## 核心参考
 
-- **Taxonomy**: `.claude/references/reading-power-taxonomy.md`
-- **Genre Profile**: `.claude/references/genre-profiles.md`
-- **Contract v2**: `.claude/skills/webnovel-write/references/step-1.5-contract.md`
-- **Shared References**: `.claude/references/shared/` 为单一事实源；如需枚举/扫描参考文件，遇到 `<!-- DEPRECATED:` 的文件一律跳过。
+- **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
+- **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
+- **Contract v2**: `${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write/references/step-1.5-contract.md`
+- **Shared References**: `${CLAUDE_PLUGIN_ROOT}/references/shared/` 为单一事实源；如需枚举/扫描参考文件，遇到 `<!-- DEPRECATED:` 的文件一律跳过。
 
 ## 输入
 
@@ -98,25 +98,18 @@ tools: Read, Grep, Bash
 
 ## 执行流程（精简版）
 
-### Step -1: CLI 入口与脚本目录探测（必做）
+### Step -1: CLI 入口与脚本目录校验（必做）
 
 为避免 `PYTHONPATH` / `cd` / 参数顺序导致的隐性失败，所有 CLI 调用统一走：
 - `${SCRIPTS_DIR}/webnovel.py`
 
 ```bash
-# 解析脚本目录（优先项目内，其次父目录工作区，其次用户目录，其次插件目录）
-if [ -d "{project_root}/.claude/scripts" ]; then
-  SCRIPTS_DIR="{project_root}/.claude/scripts"
-elif [ -d "{project_root}/../.claude/scripts" ]; then
-  SCRIPTS_DIR="{project_root}/../.claude/scripts"
-elif [ -d "${HOME}/.claude/scripts" ]; then
-  SCRIPTS_DIR="${HOME}/.claude/scripts"
-elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-else
-  echo "ERROR: 未找到 scripts 目录（.claude/scripts）" >&2
+# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
   exit 1
 fi
+SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
 
 # 建议先确认解析出的 project_root，避免写到错误目录
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
@@ -124,7 +117,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
 
 ### Step 0: ContextManager 快照优先
 ```bash
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" context --chapter {NNNN}
+python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" context -- --chapter {NNNN}
 ```
 
 ### Step 0.5: Contract v2 上下文包（内置）

.claude/agents/continuity-checker.md → webnovel-writer/agents/continuity-checker.md

@@ -8,7 +8,7 @@ tools: Read, Grep
 
 > **Role**: Narrative flow guardian ensuring smooth transitions and logical plot progression.
 
-> **输出格式**: 遵循 `.claude/references/checker-output-schema.md` 统一 JSON Schema
+> **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## Scope
 

.claude/agents/data-agent.md → webnovel-writer/agents/data-agent.md

@@ -59,25 +59,18 @@ tools: Read, Write, Bash
 
 ## 执行流程
 
-### Step -1: CLI 入口与脚本目录探测（必做）
+### Step -1: CLI 入口与脚本目录校验（必做）
 
 为避免 `PYTHONPATH` / `cd` / 参数顺序导致的隐性失败，所有 CLI 调用统一走：
 - `${SCRIPTS_DIR}/webnovel.py`
 
 ```bash
-# 解析脚本目录（优先项目内，其次父目录工作区，其次用户目录，其次插件目录）
-if [ -d "{project_root}/.claude/scripts" ]; then
-  SCRIPTS_DIR="{project_root}/.claude/scripts"
-elif [ -d "{project_root}/../.claude/scripts" ]; then
-  SCRIPTS_DIR="{project_root}/../.claude/scripts"
-elif [ -d "${HOME}/.claude/scripts" ]; then
-  SCRIPTS_DIR="${HOME}/.claude/scripts"
-elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-else
-  echo "ERROR: 未找到 scripts 目录（.claude/scripts）" >&2
+# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
   exit 1
 fi
+SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
 
 # 建议先确认解析出的 project_root，避免写到错误目录
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where

.claude/agents/high-point-checker.md → webnovel-writer/agents/high-point-checker.md

@@ -8,12 +8,12 @@ tools: Read, Grep, Bash
 
 > **Role**: Quality assurance specialist focused on reader satisfaction mechanics (爽点设计).
 
-> **输出格式**: 遵循 `.claude/references/checker-output-schema.md` 统一 JSON Schema
+> **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## 核心参考
 
-- **Taxonomy**: `.claude/references/reading-power-taxonomy.md`
-- **Genre Profile**: `.claude/references/genre-profiles.md`
+- **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
+- **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
 
 ## Scope
 

.claude/agents/ooc-checker.md → webnovel-writer/agents/ooc-checker.md

@@ -8,7 +8,7 @@ tools: Read, Grep
 
 > **Role**: Character integrity guardian preventing OOC (Out-Of-Character) violations.
 
-> **输出格式**: 遵循 `.claude/references/checker-output-schema.md` 统一 JSON Schema
+> **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## Scope
 

.claude/agents/pacing-checker.md → webnovel-writer/agents/pacing-checker.md

@@ -8,7 +8,7 @@ tools: Read, Grep, Bash
 
 > **Role**: Pacing analyst enforcing Strand Weave balance to prevent reader fatigue.
 
-> **输出格式**: 遵循 `.claude/references/checker-output-schema.md` 统一 JSON Schema
+> **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## Scope
 
@@ -38,21 +38,14 @@ tools: Read, Grep, Bash
 **Optional: Use status_reporter for automated analysis**:
 ```bash
 # 获取 Strand Weave 详细分析（推荐）
-# 解析脚本目录（优先项目内，其次父目录工作区，其次用户目录，其次插件目录）
-if [ -d "${PROJECT_ROOT}/.claude/scripts" ]; then
-  SCRIPTS_DIR="${PROJECT_ROOT}/.claude/scripts"
-elif [ -d "${PROJECT_ROOT}/../.claude/scripts" ]; then
-  SCRIPTS_DIR="${PROJECT_ROOT}/../.claude/scripts"
-elif [ -d "${HOME}/.claude/scripts" ]; then
-  SCRIPTS_DIR="${HOME}/.claude/scripts"
-elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-else
-  echo "ERROR: 未找到 scripts 目录（.claude/scripts）" >&2
+# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
+if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
+  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
   exit 1
 fi
+SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
 
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status --focus strand
+python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus strand
 
 # 输出包含:
 # - Quest/Fire/Constellation 占比统计

.claude/agents/reader-pull-checker.md → webnovel-writer/agents/reader-pull-checker.md

@@ -10,8 +10,8 @@ tools: Read, Grep, Bash
 
 ## 核心参考
 
-- **Taxonomy**: `.claude/references/reading-power-taxonomy.md`
-- **Genre Profile**: `.claude/references/genre-profiles.md`
+- **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
+- **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
 - **章节追读力数据**: `index.db → chapter_reading_power`
 - **上章钩子**: `state.json → chapter_meta` 或 `index.db`
 

.claude/references/claude-code-call-matrix.md → webnovel-writer/references/claude-code-call-matrix.md

@@ -22,17 +22,17 @@
 
 | 脚本 | 主要触发方 | 触发节点 | 备注 |
 |---|---|---|---|
-| `.claude/scripts/webnovel.py` | 所有 Skills / Agents | 任何需要调用 CLI 的节点 | **统一入口**：负责解析真实 book project_root，并转发到 `data_modules/*` 或 `scripts/*.py`，避免 `PYTHONPATH/cd/参数顺序` 导致的隐性失败 |
-| `.claude/scripts/update_state.py` | `webnovel-plan` Skill | 章纲/卷规划落盘后更新 `state.json` | 也可被自动化脚本调用；默认不是人工常规入口 |
-| `.claude/scripts/status_reporter.py` | `webnovel-query` Skill / `pacing-checker` Agent(可选) | 查询分析或节奏审查时 | 产出健康报告与紧急度分析 |
-| `.claude/scripts/workflow_manager.py` | `webnovel-resume` Skill | 恢复流程 detect/cleanup/clear | 仅恢复场景触发 |
-| `.claude/scripts/init_project.py` | `webnovel-init` Skill | 项目初始化阶段 | 负责项目脚手架与基础状态文件 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py` | 所有 Skills / Agents | 任何需要调用 CLI 的节点 | **统一入口**：负责解析真实 book project_root，并转发到 `data_modules/*` 或 `scripts/*.py`，避免 `PYTHONPATH/cd/参数顺序` 导致的隐性失败 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/update_state.py` | `webnovel-plan` Skill | 章纲/卷规划落盘后更新 `state.json` | 也可被自动化脚本调用；默认不是人工常规入口 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/status_reporter.py` | `webnovel-query` Skill / `pacing-checker` Agent(可选) | 查询分析或节奏审查时 | 产出健康报告与紧急度分析 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/workflow_manager.py` | `webnovel-resume` Skill | 恢复流程 detect/cleanup/clear | 仅恢复场景触发 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/init_project.py` | `webnovel-init` Skill | 项目初始化阶段 | 负责项目脚手架与基础状态文件 |
 
 ## 内部库调用（非独立命令）
 
 | 内部模块 | 调用方 | 触发时机 |
 |---|---|---|
-| `.claude/scripts/data_modules/state_validator.py` | `update_state.py`、`status_reporter.py` | 读写 `state.json` 时自动规范化与校验 |
+| `${CLAUDE_PLUGIN_ROOT}/scripts/data_modules/state_validator.py` | `update_state.py`、`status_reporter.py` | 读写 `state.json` 时自动规范化与校验 |
 
 ## 变更约束（后续开发必须遵守）
 

.claude/references/context-contract-v2.md → webnovel-writer/references/context-contract-v2.md

@@ -32,7 +32,7 @@
   - 聚合审查趋势与低分区间（`review_trend` / `low_score_ranges`）
 - `genre_profile`
   - 基于 `state.json -> project.genre` 自动选取题材策略片段
-  - 引用 `.claude/references/genre-profiles.md` 与 `.claude/references/reading-power-taxonomy.md`
+  - 引用 `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md` 与 `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
   - 输出 `reference_hints` 供 Writer 快速执行
 
 ## Phase C 扩展段

.claude/references/entity-management-spec.md → webnovel-writer/references/entity-management-spec.md

@@ -265,7 +265,7 @@ v5.1 允许 **aliases 一对多**：同一别名可以指向多个实体。
 
 ```bash
 # 运行迁移脚本
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" migrate --backup
+python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" migrate -- --backup
 
 # 验证迁移结果
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index stats