novelws 3.0.0 → 4.0.0

package/dist/utils/diagnostics.js

@@ -0,0 +1,227 @@
+/**
+ * 项目诊断系统
+ *
+ * 命令失败时自动诊断并给出修复步骤。
+ * 5 项检查：项目结构、JSON 格式、项目模式、依赖状态、修复建议。
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { getProjectPaths } from '../core/config.js';
+export class ProjectDiagnostics {
+    /**
+     * 对错误进行诊断，返回诊断报告
+     */
+    async diagnoseError(error, context) {
+        const checks = await Promise.all([
+            this.checkProjectStructure(context.projectRoot),
+            this.checkTrackingFiles(context.projectRoot),
+            this.checkProjectMode(context.projectRoot),
+            this.checkMCPStatus(context.projectRoot),
+            this.checkFileIntegrity(context.projectRoot),
+        ]);
+        const fixes = checks
+            .filter(c => !c.passed && c.fix)
+            .map(c => c.fix);
+        return {
+            error: error.message,
+            checks,
+            fixes,
+            summary: this.generateSummary(checks),
+        };
+    }
+    /**
+     * 检查 1: 项目结构是否完整
+     */
+    async checkProjectStructure(projectRoot) {
+        const paths = getProjectPaths(projectRoot);
+        const requiredDirs = [
+            { path: paths.resources, label: 'resources' },
+            { path: paths.claude, label: '.claude' },
+            { path: paths.commands, label: '.claude/commands' },
+        ];
+        const missing = [];
+        for (const dir of requiredDirs) {
+            if (!await fs.pathExists(dir.path)) {
+                missing.push(dir.label);
+            }
+        }
+        if (missing.length === 0) {
+            return { name: '项目结构', passed: true, message: '项目结构正常' };
+        }
+        return {
+            name: '项目结构',
+            passed: false,
+            message: `缺少目录: ${missing.join(', ')}`,
+            fix: 'novelws init',
+        };
+    }
+    /**
+     * 检查 2: tracking 文件是否存在
+     */
+    async checkTrackingFiles(projectRoot) {
+        const trackingDir = getProjectPaths(projectRoot).tracking;
+        if (!await fs.pathExists(trackingDir)) {
+            return {
+                name: 'Tracking 文件',
+                passed: false,
+                message: 'tracking 目录不存在',
+                fix: '/track --sync',
+            };
+        }
+        const expectedFiles = [
+            'character-state.json',
+            'plot-tracker.json',
+            'timeline.json',
+            'relationships.json',
+        ];
+        const missing = [];
+        for (const file of expectedFiles) {
+            if (!await fs.pathExists(path.join(trackingDir, file))) {
+                missing.push(file);
+            }
+        }
+        if (missing.length === 0) {
+            return { name: 'Tracking 文件', passed: true, message: 'tracking 文件存在' };
+        }
+        return {
+            name: 'Tracking 文件',
+            passed: false,
+            message: `缺少 tracking 文件: ${missing.join(', ')}`,
+            fix: '/track --sync',
+        };
+    }
+    /**
+     * 检查 3: 项目模式是否匹配
+     */
+    async checkProjectMode(projectRoot) {
+        const mode = await this.detectProjectMode(projectRoot);
+        if (mode === 'unknown') {
+            return {
+                name: '项目模式',
+                passed: false,
+                message: '无法检测项目模式',
+                fix: '/track --sync',
+            };
+        }
+        return {
+            name: '项目模式',
+            passed: true,
+            message: `当前模式: ${mode}`,
+        };
+    }
+    /**
+     * 检查 4: MCP 服务器状态
+     */
+    async checkMCPStatus(projectRoot) {
+        const paths = getProjectPaths(projectRoot);
+        const dbPath = paths.trackingDb;
+        const mcpConfigPath = paths.mcpServers;
+        const hasDb = await fs.pathExists(dbPath);
+        const hasMcpConfig = await fs.pathExists(mcpConfigPath);
+        if (!hasMcpConfig) {
+            return {
+                name: 'MCP 状态',
+                passed: true,
+                message: '未配置 MCP（使用 JSON 模式）',
+            };
+        }
+        if (hasMcpConfig && !hasDb) {
+            return {
+                name: 'MCP 状态',
+                passed: false,
+                message: 'MCP 已配置但数据库不存在',
+                fix: '/track --migrate --target mcp',
+            };
+        }
+        return { name: 'MCP 状态', passed: true, message: 'MCP 服务正常' };
+    }
+    /**
+     * 检查 5: JSON 文件完整性
+     */
+    async checkFileIntegrity(projectRoot) {
+        const trackingDir = getProjectPaths(projectRoot).tracking;
+        if (!await fs.pathExists(trackingDir)) {
+            return { name: '文件完整性', passed: true, message: '无 tracking 文件需要验证' };
+        }
+        const jsonFiles = [
+            'character-state.json',
+            'plot-tracker.json',
+            'timeline.json',
+            'relationships.json',
+        ];
+        const corrupted = [];
+        for (const file of jsonFiles) {
+            const filePath = path.join(trackingDir, file);
+            if (await fs.pathExists(filePath)) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    JSON.parse(content);
+                }
+                catch {
+                    corrupted.push(file);
+                }
+            }
+        }
+        if (corrupted.length === 0) {
+            return { name: '文件完整性', passed: true, message: 'JSON 文件格式正确' };
+        }
+        return {
+            name: '文件完整性',
+            passed: false,
+            message: `JSON 格式损坏: ${corrupted.join(', ')}`,
+            fix: '/track --fix',
+        };
+    }
+    /**
+     * 检测项目模式
+     */
+    async detectProjectMode(projectRoot) {
+        const paths = getProjectPaths(projectRoot);
+        const dbPath = paths.trackingDb;
+        if (await fs.pathExists(dbPath)) {
+            return 'mcp';
+        }
+        if (await fs.pathExists(paths.trackingVolumes)) {
+            const entries = await fs.readdir(paths.trackingVolumes).catch(() => []);
+            if (entries.length > 0) {
+                return 'sharded';
+            }
+        }
+        if (await fs.pathExists(paths.tracking)) {
+            return 'single-file';
+        }
+        return 'unknown';
+    }
+    /**
+     * 格式化诊断报告为用户友好的字符串
+     */
+    formatReport(report) {
+        const lines = [
+            `❌ 错误: ${report.error}`,
+            '',
+            '🔍 诊断结果:',
+        ];
+        for (const check of report.checks) {
+            const icon = check.passed ? '✅' : '❌';
+            lines.push(`  ${icon} ${check.name}: ${check.message}`);
+        }
+        if (report.fixes.length > 0) {
+            lines.push('');
+            lines.push('💡 修复步骤:');
+            report.fixes.forEach((fix, i) => {
+                lines.push(`  ${i + 1}. 运行: ${fix}`);
+            });
+        }
+        return lines.join('\n');
+    }
+    generateSummary(checks) {
+        const passed = checks.filter(c => c.passed).length;
+        const total = checks.length;
+        if (passed === total) {
+            return '所有检查通过，问题可能来自其他原因';
+        }
+        const failed = checks.filter(c => !c.passed).map(c => c.name);
+        return `${passed}/${total} 项检查通过，问题: ${failed.join(', ')}`;
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/utils/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/utils/diagnostics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novelws",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "Claude Code 专用的 AI 小说创作工具 - 深度集成 Slash Commands 和 Agent Skills",
   "keywords": [

package/templates/commands/analyze.md

@@ -1,10 +1,11 @@
 ---
 description: 智能分析：自动选择框架分析（write前）或内容分析（write后），支持 --type 手动指定
 argument-hint: [--type=framework|content] [--range ch-XXX-YYY | --volume vol-XX | --volume-report vol-XX]
+recommended-model: claude-sonnet-4-5-20250929 # 分析任务，质量与速度平衡；深度分析可用 opus
 allowed-tools: Bash(find:*), Bash(wc:*), Bash(grep:*), Read(//**), Read(//plugins/**), Read(//plugins/**), Write(//stories/**/analysis-report.md), Bash(*)
 scripts:
-  sh: .specify/scripts/bash/check-analyze-stage.sh --json
-  ps: .specify/scripts/powershell/check-analyze-stage.ps1 -Json
+  sh: resources/scripts/bash/check-analyze-stage.sh --json
+  ps: resources/scripts/powershell/check-analyze-stage.ps1 -Json
 ---
 
 对小说项目进行智能化综合分析。根据当前创作阶段，自动选择执行**框架一致性分析**（write 之前）或**内容质量分析**（write 之后）。
@@ -15,105 +16,38 @@ scripts:
 
 ### 1. 智能阶段检测
 
-运行 `{SCRIPT}` 获取当前创作状态：
-
-```json
-{
-  "analyze_type": "framework|content",
-  "chapter_count": 0,
-  "has_spec": true,
-  "has_plan": true,
-  "has_tasks": true,
-  "story_dir": "/path/to/story",
-  "reason": "原因说明"
-}
-```
+运行 `{SCRIPT}` 获取当前创作状态（返回 `analyze_type`, `chapter_count`, `has_spec/plan/tasks`, `story_dir`, `reason`）。
 
 ### 2. 决策逻辑
 
-解析用户参数 `$ARGUMENTS`：
-
-**手动指定模式**（优先级最高）：
-- 包含 `--type=framework` → 强制框架分析
-- 包含 `--type=content` → 强制内容分析
-
-**批量范围分析**：
-- `--range ch-XX-YY` → 指定章节范围分析
-- `--range vol-XX` → 指定卷分析
-- `--range vol-XX-YY` → 多卷范围分析（含跨卷对比）
-- `--volume vol-XX` → 等同于 `--range vol-XX`
-- `--volume-report vol-XX` → 生成指定卷的综合分析报告（见下方详细说明）
-
-**专项分析模式**：
-- `--focus=opening` → 开篇专项分析（前3章）
-- `--focus=pacing` → 节奏专项分析（爽点/冲突分布）
-- `--focus=character` → 人物专项分析（人物弧光）
-- `--focus=foreshadow` → 伏笔专项分析（埋设与回收）
-- `--focus=logic` → 逻辑专项分析（逻辑漏洞）
-- `--focus=style` → 风格专项分析（文笔一致性）
-- `--focus=reader` → 读者体验分析（爽点密度、钩子强度、信息投喂、期待管理）
-- `--focus=hook` → 钩子专项分析（每章结尾钩子类型、强度、兑现率）
-- `--focus=power` → 力量体系专项分析（力量等级一致性、战力对比合理性、升级节奏）
-- `--focus=voice` → 对话一致性分析（检测各角色对话是否符合语言指纹设定）
-
-**自动判断模式**：
-- 章节数 < 3 → **框架分析**
-- 章节数 ≥ 3 → **内容分析**
-
-### 4. 数据加载策略（三层 Fallback）
+解析用户参数 `$ARGUMENTS`，按优先级：
 
-当执行 `--range` 或 `--volume` 分析时，按以下优先级加载数据：
+1. **手动指定**：`--type=framework` 或 `--type=content`
+2. **范围分析**：`--range ch-XX-YY` / `--range vol-XX[-YY]` / `--volume vol-XX` / `--volume-report vol-XX`
+3. **专项分析 `--focus=`**：`opening`(前3章) | `pacing`(爽点/冲突) | `character`(人物弧光) | `foreshadow`(伏笔) | `logic`(逻辑漏洞) | `style`(文笔一致性) | `reader`(读者体验) | `hook`(钩子强度) | `power`(力量体系) | `voice`(对话一致性)
+4. **自动判断**：章节数 < 3 → 框架分析，≥ 3 → 内容分析
 
-**Layer 1: MCP 查询（优先）**
-- 调用 `query_characters --volume=vol-XX` 获取该卷角色数据
-- 调用 `query_plot --volume=vol-XX` 获取该卷情节数据
-- 调用 `query_timeline --chapter_from=X --chapter_to=Y` 获取时间线
-- 调用 `stats_volume --volume=vol-XX` 获取卷统计数据
+### 4. 数据加载策略（三层 Fallback）
 
-**Layer 2: 分片 JSON（次优）**
-- 检测 `spec/tracking/volumes/vol-XX/` 是否存在
-- 读取该卷的 4 个分片文件
-- 读取 `spec/tracking/summary/volume-summaries.json` 获取卷元信息
+`--range` / `--volume` 分析时，按优先级加载：
 
-**Layer 3: 单文件 JSON（兜底）**
-- 读取 `spec/tracking/` 下的单文件
-- 根据章节范围手动过滤数据
+1. **Layer 1: MCP 查询**：`query_characters`、`query_plot`、`query_timeline`、`stats_volume`（均传 `--volume=vol-XX`）
+2. **Layer 2: 分片 JSON**：`tracking/volumes/vol-XX/` 下 4 个分片 + `summary/volume-summaries.json`
+3. **Layer 3: 单文件 JSON**：`tracking/` 下单文件，按章节范围手动过滤
 
 ### 5. --volume-report 综合报告
 
-当使用 `--volume-report vol-XX` 时，生成该卷的完整分析报告，包含：
+`--volume-report vol-XX` 生成该卷完整分析报告，包含：卷概览、情节分析、角色发展、节奏评估、一致性检查、跨卷对比、改进建议（P0/P1/P2）。
 
-**报告结构：**
-1. **卷概览**：章节范围、总字数、关键事件、主要角色
-2. **情节分析**：该卷的情节线推进、伏笔埋设与回收、高潮设计
-3. **角色发展**：该卷中角色的成长弧线、关系变化
-4. **节奏评估**：爽点分布、钩子强度、情绪曲线
-5. **一致性检查**：逻辑漏洞、时间线问题、角色行为一致性
-6. **跨卷对比**：与前卷的衔接、与后卷的铺垫
-7. **改进建议**：分级建议（P0/P1/P2）
-
-**数据来源：**
-- 优先使用 MCP `stats_volume` 获取预计算的统计数据
-- 读取该卷的章节文件（`stories/[current]/content/chapter-XXX.md`）
-- 读取该卷的 tracking 数据（分片或单文件）
+数据来源：MCP `stats_volume` → 章节文件（`stories/[current]/content/chapter-XXX.md`）→ tracking 数据（分片或单文件）。
 
 ### 6. 资源加载
 
-**参考 CLAUDE.md 中的资源加载规则**，加载以下基准文档：
-- 宪法文件：`.specify/memory/constitution.md`
-- 规格文件：`stories/*/specification.md`
-- 计划文件：`stories/*/creative-plan.md`
-- 任务文件：`stories/*/tasks.md`
-
-**分析专用资源**（Layer 1 默认加载）：
-- `templates/knowledge-base/craft/` 下所有 craft 知识库（用于质量对照检查）
-- `templates/skills/quality-assurance/` 下的 QA skills（用于一致性验证）
-
-**Layer 2: 配置覆盖**：如果 `specification.md` 配置了 `resource-loading.analysis`，按配置加载。
+**基准文档**（参考 CLAUDE.md 资源加载规则）：`resources/memory/constitution.md`、`stories/*/specification.md`、`stories/*/creative-plan.md`、`stories/*/tasks.md`
 
-**Layer 3: 关键词触发**：读取 `specification.md` 的 `resource-loading.keyword-triggers.enabled`，扫描 `--check` 参数值动态加载 skills。
+**分析专用**：`resources/craft/` 全部 + `templates/skills/quality-assurance/` QA skills
 
-**会话级资源复用**：本次对话中已加载的资源直接复用，不重复读取。
+**覆盖与触发**：`specification.md` 的 `resource-loading.analysis` 配置覆盖默认加载；`keyword-triggers.enabled` 扫描 `--check` 参数动态加载 skills。会话级资源复用，不重复读取。
 
 ---
 
@@ -143,27 +77,10 @@ scripts:
 
 ### A4. 准备就绪评估
 
-```markdown
-## 准备就绪评估
-
-### 必要条件 (P0)
-- [ ] 规格完整且明确
-- [ ] 计划覆盖所有 P0 需求
-- [ ] 任务分解完整
-- [ ] 无致命逻辑矛盾
-
-### 建议条件 (P1)
-- [ ] 角色档案完善
-- [ ] 世界观设定文档详细
-- [ ] 时间线规划清晰
-
-### 总体评分：[X]/10
-
-**建议**：
-1. 🔴 必须修复：[P0问题]
-2. 🟡 建议优化：[P1问题]
-3. 🟢 可选：[P2问题]
-```
+输出总体评分 [X]/10，包含：
+- **P0 必要条件**：规格完整、计划覆盖 P0 需求、任务分解完整、无致命逻辑矛盾
+- **P1 建议条件**：角色档案完善、世界观设定详细、时间线规划清晰
+- **建议**：🔴 必须修复(P0) / 🟡 建议优化(P1) / 🟢 可选(P2)
 
 ---
 
@@ -285,15 +202,15 @@ scripts:
 应用后追加更新记录到 `tracking-log.md`。
 
 **分片模式写入协议**：
-- 如果检测到 `spec/tracking/volumes/` 存在，确定章节所属卷
-- 更新该卷的分片文件（如 `spec/tracking/volumes/vol-03/character-state.json`）
-- 同步更新全局摘要文件（如 `spec/tracking/summary/characters-summary.json`）
+- 如果检测到 `tracking/volumes/` 存在，确定章节所属卷
+- 更新该卷的分片文件（如 `tracking/volumes/vol-03/character-state.json`）
+- 同步更新全局摘要文件（如 `tracking/summary/characters-summary.json`）
 - 如果 MCP 可用，调用 `sync_from_json` 同步到 SQLite
 
 **错误处理**：
 - tracking 文件不存在 → 建议运行 `/track --init`
 - JSON 格式错误 → 提示手动修复
-- tracking 目录不存在 → 建议创建 `spec/tracking/`
+- tracking 目录不存在 → 建议创建 `tracking/`
 
 ---