Foreshadowing Tracker

伏笔追踪器 - 识别章节中的伏笔并追踪回收状态。当需要管理伏笔、确保前后呼应时使用，支持新增伏笔识别、待回收伏笔提醒、已回收伏笔标记。

Security Scan

The skill mostly does what its description says (local text analysis), but it also includes an LLM client that sends text to an external API and requires an undocumented API key — a disclosure/incoherence that warrants caution.

Purpose & Capability

The scripts and SKILL.md align with the stated purpose (identify and track foreshadowing in chapters). Having both a pattern-based script and an optional LLM-based script is plausible. However, the presence of an LLM caller introduces external network behavior that is not described in the SKILL.md's environment requirements.

Instruction Scope

SKILL.md documents CLI usage for the main script but does not mention the LLM helper's need to call an external API or require an API key. The LLM script will read local text files (expected) but also reads an environment variable and transmits the book text to a remote endpoint — behavior not disclosed in the runtime instructions.

Install Mechanism

There is no binary-level install spec (no downloads or archive extraction). Dependencies are standard Python packages listed in requirements.txt. This is a low-risk install footprint.

Credentials

SKILL.md lists no required environment variables, but scripts/track_foreshadowing_llm.py expects DASHSCOPE_API_KEY (and will exit if it is not set). Requiring a remote-service API key is proportionate only if users knowingly opt into remote LLM analysis; omission from the declared requirements is an inconsistency that could lead to unexpected data exfiltration (book text sent externally).

Persistence & Privilege

The skill does not request permanent inclusion (always:false) and does not modify other skills or system-wide configs. It creates/reads per-project record files (as documented) which is appropriate for its function.

What to consider before installing

This skill's core, local pattern-based script matches the description and is low-risk. However, an included helper (scripts/track_foreshadowing_llm.py) will: (1) require the environment variable DASHSCOPE_API_KEY (the SKILL.md does not list this), and (2) POST the book text to https://coding.dashscope.aliyuncs.com/v1/chat/completions. Before installing or running: ensure you are comfortable sending your draft text to that external service or remove/disable the LLM script; verify the API host and model are ones you trust; set the API key in a separate, restricted environment variable if needed; review the LLM script source for any additional endpoints or secrets usage; run the tool in an isolated environment (or offline) if your manuscript must remain private. If you want only local processing, use scripts/track_foreshadowing.py and ignore or delete scripts/track_foreshadowing_llm.py. If you need a firmer safety verdict, provide the SKILL.md author/source or clarify whether remote LLM calls are intended.

Foreshadowing Tracker - 伏笔追踪器

Overview

自动识别章节中的伏笔（暗示、铺垫、悬念），追踪伏笔的回收状态，生成详细的伏笔追踪报告，帮助保持故事前后呼应。

使用场景：

• 需要识别章节中的新伏笔
• 需要追踪伏笔是否已回收
• 需要避免遗忘重要伏笔
• 需要确保故事前后呼应

伏笔类型

类型	说明	示例
暗示	隐晦提示未来事件	"他不知道，这将是最后一次见面"
铺垫	为后续情节做准备	"桌上放着一把古老的钥匙"
悬念	引发读者好奇	"门后传来奇怪的声音"
flag	角色说出的话	"等这件事结束，我就..."

CLI 使用

# 基本用法
python3 scripts/track_foreshadowing.py --book-dir projects/my-novel --chapter chapters/chapter-01.md

# 指定伏笔记录文件
python3 scripts/track_foreshadowing.py \
  --book-dir projects/my-novel \
  --chapter chapters/chapter-01.md \
  --record data/foreshadowing.json

# 输出报告到文件
python3 scripts/track_foreshadowing.py \
  --book-dir projects/my-novel \
  --chapter chapters/chapter-01.md \
  --output reports/chapter-01-foreshadowing.md

# 简写
python3 scripts/track_foreshadowing.py -d ./project -c chapter.md -o report.md

参数说明

参数	必填	说明
--book-dir / -d	✅	小说项目目录路径
--chapter / -c	✅	章节文件路径
--record / -r	❌	伏笔记录文件（默认 data/foreshadowing.json）
--output / -o	❌	输出报告文件路径

伏笔记录格式 (data/foreshadowing.json)

{
  "foreshadowings": [
    {
      "id": "FS001",
      "chapter": 1,
      "content": "桌上放着一把古老的钥匙",
      "type": "铺垫",
      "status": "pending",
      "note": "可能是打开密室的钥匙",
      "created_at": "2026-04-04"
    },
    {
      "id": "FS002",
      "chapter": 5,
      "content": "他用那把钥匙打开了密室的门",
      "type": "回收",
      "related_to": "FS001",
      "status": "resolved",
      "note": "伏笔已回收",
      "created_at": "2026-04-05"
    }
  ]
}

输出报告格式

# 伏笔追踪报告

**章节**: chapters/chapter-01.md
**检测时间**: 2026-04-04 23:58:00

## 检测概览

| 类型 | 数量 |
|------|------|
| 新增伏笔 | 3 |
| 待回收伏笔 | 5 |
| 已回收伏笔 | 2 |

## 新增伏笔

### FS003 (暗示)
**内容**: "他不知道，这将是最后一次见面"
**位置**: 第 3 段
**建议**: 后续需要安排再次见面的情节

### FS004 (铺垫)
**内容**: "桌上放着一把古老的钥匙"
**位置**: 第 7 段
**建议**: 后续需要说明钥匙的用途

## 待回收伏笔

| ID | 章节 | 内容 | 状态 |
|----|------|------|------|
| FS001 | 1 | 古老的钥匙 | pending |
| FS002 | 2 | 神秘电话 | pending |

## 已回收伏笔

| ID | 伏笔章节 | 回收章节 | 内容 |
|----|----------|----------|------|
| FS005 | 1 | 3 | 钥匙打开密室 |

依赖

• Python 3.8+
• rich (终端渲染)
• PyYAML (配置文件解析)

安装依赖：

pip install -r scripts/requirements.txt

与其他技能集成

与 novel-writer 集成

# 1. 生成章节正文
python3 ../novel-writer/scripts/write_chapter.py \
  --book-dir projects/my-novel \
  --chapter 1 \
  --output chapters/chapter-01.md

# 2. 追踪伏笔
python3 scripts/track_foreshadowing.py \
  --book-dir projects/my-novel \
  --chapter chapters/chapter-01.md \
  --output reports/chapter-01-foreshadowing.md

与 quality-checker 集成

# 1. 质量检测
python3 ../quality-checker/scripts/check_quality.py \
  --input chapters/chapter-01.md

# 2. 伏笔追踪
python3 scripts/track_foreshadowing.py \
  --book-dir projects/my-novel \
  --chapter chapters/chapter-01.md

注意事项

• 伏笔记录文件会自动创建（如不存在）
• 支持 UTF-8 和 GBK 编码
• 伏笔识别基于关键词匹配，可能需要人工审核
• 建议每章完成后立即进行伏笔追踪