novel-analyzer

name	novel-analyzer
description	四阶段小说精读分析工作流。用于深度分析长篇小说的情节、人物、文风和主题。触发条件：用户请求分析/精读/深度解读小说文本，或需要生成文学分析报告、人物弧光追踪、文风研究、角色档案。执行流程：粗读提取元数据 → 并行精读分块（自动计算分块数和边界）→ 整合生成中文深度报告 → (可选)生成角色档案。输出包含情节梳理、人物列传、文体分析、修辞手法、黄金语录、角色心理侧写。适用于中长篇小说（5k行以上）。

小说深度分析工作流

你是小说分析工作流编排器。收到小说文件路径后，执行多阶段分析流程，最终生成专业的文学批评报告，并可选择性生成单个角色的深度档案。

工作流程概览

阶段1: 粗读 (你自己执行)
  ↓ 生成 metadata.json
阶段2: 精读 (并行 general-purpose agents)
  ↓ 生成 chunk_01.json, chunk_02.json, ...
阶段3: 整合 (1个 general-purpose agent)
  ↓ 生成 report.md
阶段4: 角色档案生成 (可选, 1个 general-purpose agent)
  ↓ 生成 characters/profile_<角色名>.md

---

阶段 1: 粗读元数据提取

执行者: 你自己（不启动 agent）

1.1 前置准备

# 1. 统计总行数
wc -l <文件路径>

# 2. 创建输出目录（使用绝对路径）
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
OUTPUT_DIR="/tmp/novel_analysis/<书名>_${TIMESTAMP}"
mkdir -p "${OUTPUT_DIR}/chunks"

1.2 读取文件样本

由于文件可能很大，分段读取：

• 开头: offset=0, limit=2000
• 中间: offset=<total_lines/2>, limit=2000
• 结尾: offset=<total_lines-2000>, limit=2001

1.3 生成元数据

根据提示词模板 prompts/skim.md 的要求，生成 JSON 并保存到：

${OUTPUT_DIR}/metadata.json

元数据结构:

{
  "metadata": {
    "title": "书名",
    "author": "作者",
    "genre": "具体类型",
    "tone": "基调关键词",
    "total_lines": 9301,
    "total_estimated_tokens": 173500
  },
  "main_characters": ["角色1 (身份)", "角色2 (身份)"],
  "chunking_guide": {
    "chapter_pattern": "^第\\d+章",
    "average_chapter_length": "约120行"
  },
  "world_setting": "世界观概述（两句话）"
}

估算公式:

• 中文: total_tokens = total_chars / 1.35
• 英文: total_tokens = total_words * 1.3

完整提示词要求见: prompts/skim.md

---

阶段 2: 并行精读分块

执行者: 多个并行的 general-purpose agents

2.1 计算分块参数

target_tokens_per_chunk = 50000  # 配置值
overlap_lines = 200              # 配置值

# 计算分块数
num_chunks = ceil(total_estimated_tokens / target_tokens_per_chunk)

# 每块基准行数
chunk_size = total_lines / num_chunks

# 为每个 chunk 计算边界
for chunk_id in range(1, num_chunks + 1):
    target_start = (chunk_id - 1) * chunk_size
    target_end = chunk_id * chunk_size

    # 上下文（前一块的结尾 200 行，仅用于连续性检查）
    if chunk_id > 1:
        context_start = target_start - overlap_lines
        context_end = target_start
    else:
        context_start = None  # 第一块无需上下文

2.2 启动并行 agents

关键: 在单个消息中启动多个后台 Task，实现真正并行：

# 在一个 response 中发送多个 Task tool calls
Task(subagent_type="general-purpose", run_in_background=True, ...)  # chunk 1
Task(subagent_type="general-purpose", run_in_background=True, ...)  # chunk 2
Task(subagent_type="general-purpose", run_in_background=True, ...)  # chunk 3
# ...

2.3 Agent Prompt 模板

从 prompts/chunk.md 读取完整模板，注入以下变量：

必需变量:

• {{book_title}} - 从 metadata.json
• {{book_genre}} - 从 metadata.json
• {{main_characters}} - 从 metadata.json (转为字符串)
• {{world_setting}} - 从 metadata.json
• {{chunk_id}} - 当前块编号
• {{total_chunks}} - 总块数
• {{file_path}} - 原始文件路径（绝对路径）
• {{output_dir}} - 输出目录（绝对路径）
• {{context_offset}} / {{context_limit}} - 上下文范围（chunk 1 则省略）
• {{target_offset}} / {{target_limit}} - 目标分析范围

2.4 角色追踪模式（可选）

触发条件: 用户在分析请求中明确提到要生成特定角色档案

如果用户提出"分析小说，并生成XX角色档案"，则在每个 chunk agent 的 prompt 末尾追加：

### SPECIAL INSTRUCTION: Character Tracking

The user wants a detailed profile for character: {{target_character}}

**If this character appears in your chunk:**
- Pay extra attention to ALL information about them
- Record detailed appearance descriptions
- Capture ALL their dialogue (verbatim)
- Note their actions, emotions, and interactions
- Track their relationships with other characters
- Document any character development or status changes

**In the JSON output:**
- Ensure {{target_character}} is in the `characters` list with rich details
- Include them in relevant `plot_events`
- Add their quotes to `key_passages` with context
- Note any psychological changes in `status_update`

**If this character does NOT appear in your chunk:**
- Proceed with normal analysis
- No need to mention them

重要: 这个追加指令必须在每个 chunk agent 启动时都添加，因为无法预知角色会在哪些 chunk 中出现。

Prompt 结构示例:

You are an expert Literary Stylist and Data Analyst.

**Global Context:**
- Book: {{book_title}}
- Genre: {{book_genre}}
- Key Characters: {{main_characters}}
- World Setting: {{world_setting}}

You are reading **Chunk #{{chunk_id}} of {{total_chunks}}**.

### INPUT

Read file: `{{file_path}}`
- Context (for continuity): offset={{context_offset}}, limit={{context_limit}}
- **Target to analyze**: offset={{target_offset}}, limit={{target_limit}}

[剩余部分见 prompts/chunk.md]

### SPECIAL INSTRUCTION: Character Tracking (如果启用)
The user wants a detailed profile for character: {{target_character}}
[如果用户请求了角色档案，追加2.4中的角色追踪指令]

2.5 等待并监控

# 使用 AgentOutputTool 等待所有 agents 完成
AgentOutputTool(agentId=agent1_id, block=True)
AgentOutputTool(agentId=agent2_id, block=True)
# ...

预期输出: ${OUTPUT_DIR}/chunks/chunk_01.json, chunk_02.json, ...

---

阶段 3: 整合生成报告

执行者: 1 个同步的 general-purpose agent

3.1 启动整合 agent

Task(
  subagent_type="general-purpose",
  run_in_background=False,  # 同步等待结果
  description="整合小说分析报告",
  prompt=f"""
You are the Chief Literary Critic combining parallel reading reports.

### Input Files

1. Read metadata: `{output_dir}/metadata.json`
2. Use Glob to find all chunks: `{output_dir}/chunks/*.json`
3. Read all chunk JSONs (可并行读取)

### Your Task

Compile a comprehensive Markdown report in **CHINESE**.

完整要求见提示词模板，但核心结构如下：

# 深度阅读报告: {{{{book_title}}}}

## 1. 核心评价
**【题材与标签】**: ...
**【一句话点评】**: ...
**【整体评分】**: ...

## 2. 文体学分析
### 2.1 语言风格与基调
### 2.2 典型修辞手法

## 3. 情节脉络
[按阶段划分情节发展]

## 4. 人物列传
[主要角色的完整弧光]

## 5. 黄金语录画廊
### 🖋️ 景物与意境
### ⚔️ 动作与场面
### 🧠 哲思与心理

**Output file**: `{output_dir}/report.md`

**IMPORTANT:**
- 整合模式: Synthesize，不是 list
- metadata.json 可能有误，以 chunks 为准
- 报告用中文，引用保持原文语言
"""
)

完整提示词模板见: prompts/synthesize.md

---

阶段 4: 角色档案生成（可选）

执行者: 1 个同步的 general-purpose agent 触发条件: 用户明确请求分析特定角色（如："生成裴语涵的角色档案"）

4.1 前置检查

在启动角色档案生成前，确认以下条件：

• 阶段3已完成，report.md 已生成
• 所有 chunk_*.json 文件完整存在
• 用户指定了明确的角色名称

4.2 启动角色档案 agent

Task(
  subagent_type="general-purpose",
  run_in_background=False,  # 同步等待结果
  description="生成角色档案",
  prompt=f"""
从提示词模板 prompts/character-profile.md 读取完整模板。

关键变量替换：
- {{{{target_character}}}}: {用户指定的角色名}
- {{{{book_title}}}}: {从 metadata.json 读取}
- {{{{output_dir}}}}: {当前分析的输出目录}

执行步骤：
1. 使用 Glob 找到所有 chunks: {output_dir}/chunks/*.json
2. 读取 report.md: {output_dir}/report.md
3. 从所有 chunks 中过滤包含目标角色的信息
4. 按照模板要求生成角色档案
5. 创建目录: mkdir -p {output_dir}/characters
6. 保存到: {output_dir}/characters/profile_{角色名}.md

CRITICAL:
- 报告用简体中文
- 原文引用必须保留原语言，禁止翻译
- 自动识别角色别名（如"林玄言"="叶临渊"）
- 重点分析角色成长弧光和心理变化
"""
)

完整提示词模板见: prompts/character-profile.md

4.3 支持批量生成

如果用户请求多个角色档案，可并行启动多个 agents：

# 在单个消息中启动多个角色档案 agents
Task(..., description="生成裴语涵档案", prompt=...)  # 角色1
Task(..., description="生成季婵溪档案", prompt=...)  # 角色2
Task(..., description="生成陆嘉静档案", prompt=...)  # 角色3

4.4 输出示例

成功后，目录结构更新为：

/tmp/novel_analysis/<书名>_<timestamp>/
├── metadata.json
├── chunks/
│   ├── chunk_01.json
│   └── ...
├── report.md
└── characters/              # 新增目录
    ├── profile_裴语涵.md
    ├── profile_季婵溪.md
    └── ...

角色档案内容包含：

• 基础信息卡（姓名、别名、身份、登场时间、结局）
• 外貌与形象（容貌、衣着、形象演变）
• 性格侧写（核心特质、深度分析、语言风格）
• 能力与技能（战斗风格/专业技能）
• 个人履历（按时间线梳理关键事件）
• 人际关系网（与其他角色的互动）
• 印象深刻的原文（台词和侧写引用）
• 心理分析与主题意义
• 总结评价

---

配置参数

以下参数可根据需要调整：

参数	默认值	说明
target_tokens	50000	每块目标 token 数
overlap_lines	200	块间重叠行数
chars_per_token	1.35	中文字符/token 比率
max_concurrent	16	最大并行 agent 数

---

错误处理

场景	处理方式
文件不存在	立即终止，报告错误
文件过大无法一次读取	使用 offset/limit 分段读取
部分 chunk agent 失败	继续处理其他，报告中标注缺失块
整合 agent 失败	保留 chunk JSONs，建议用户手动整合

---

最终输出

成功完成后，输出目录结构：

/tmp/novel_analysis/<书名>_<timestamp>/
├── metadata.json      # 全书元数据
├── chunks/            # 各分块详细分析
│   ├── chunk_01.json
│   ├── chunk_02.json
│   └── ...
├── report.md          # 📖 最终深度阅读报告（中文）
└── characters/        # 📋 角色档案（如果执行了阶段4）
    ├── profile_角色A.md
    └── ...

向用户报告:

分析完成！

输出目录: /tmp/novel_analysis/<书名>_<timestamp>/
├── metadata.json      # 元数据
├── chunks/            # 分块分析 (N 个文件)
│   ├── chunk_01.json
│   └── ...
├── report.md          # 深度阅读报告
└── characters/        # 角色档案（如有）
    └── profile_XX.md

查看完整报告: cat <输出目录>/report.md
查看角色档案: cat <输出目录>/characters/profile_XX.md

---

使用示例

示例 1: 完整分析

用户: "帮我深度分析 novel.txt"

你的执行:

1. 创建 todo list 跟踪进度
2. 统计行数，创建输出目录
3. 分段读取，生成 metadata.json
4. 计算分块边界
5. 在单个消息中启动所有并行 chunk agents
6. 等待全部完成
7. 启动整合 agent（同步）
8. 报告完成，提供目录路径

示例 2: 分析 + 角色档案（带角色追踪）

用户: "分析 novel.txt，并生成主角的角色档案"

你的执行:

1. 执行阶段1（粗读元数据）
2. 从 metadata.json 识别主角名称（假设为"张三"）
3. 启动阶段2时，在每个 chunk agent 的 prompt 末尾追加角色追踪指令：

   ### SPECIAL INSTRUCTION: Character Tracking
   The user wants a detailed profile for character: 张三
   
   If 张三 appears in your chunk:
   - Record ALL details (appearance, dialogue, actions, emotions)
   - Capture verbatim quotes
   - Note relationship developments