Novel Style Extractor

---
name: novel-style-extractor
description: "萃取小说风格，生成「小说修改器」可用的写作风格 skill。"
version: 1.0.0
author: Lenovo, Hermes Agent
license: MIT
platforms: [windows, linux, macos]
metadata:
  hermes:
    tags: [novel, writing, style-extraction, chinese-fiction, local-tool]
    category: creative
    related_skills: [xin-novel-style-builder, local-browser-app]
---

# 小说风格萃取（适配「小说修改器」）

把一段/几章小说正文，萃成**能直接放进「小说修改器」工具「写作风格 Skill」框里的 Markdown**。
本 skill 是 `xin-novel-style-builder` 的适配版：十维框架沿用，**产出物与取样方式不同**。

## When to Use / 何时用

- 用户在「小说修改器」里想模仿某本书的笔法，要在新建小说时萃取风格
- 用户丢来一段小说正文（或文件），说“提取它的文风 / 按这个风格改我的稿”
- 需要维护/调优工具内 `core/style_extract.py` 的萃取提示词与输出格式

不用它：要生成可分发的 Hermes 文风 skill 包（frontmatter + zip）→ 用 `xin-novel-style-builder`。

## 与上游 skill 的差异（先看这张表）

| | xin-novel-style-builder | 本 skill |
| --- | --- | --- |
| 产出 | 带 frontmatter 的 skill 目录 + zip | 工具内「写作风格 Skill」Markdown + 配套「写作示例」，存 `data/styles/<名>.md` 与 `<名>.example.md` |
| 取样 | 固定前 20 章 | **章数可选**（1–N 或全部；无章节标记按字数，上限 3 万字） |
| 结构 | 十维 + 段落/对话/环境/钩子/节奏等分节规范 | 8 节固定小节（见下） |
| 长度 | 不限 | 700–1400 字（太长会挤占提示词预算） |
| 场景 | 从零创作 | **改写别人现成稿子**，多一节「改写时应保留」 |
| 落地 | 复制进 `~/.hermes/skills` | 存进风格库 / 直接应用到当前小说 |

十维的详细分析指引**复用上游**，不复制：
`skill_view('xin-novel-style-builder', 'references/extraction_framework.md')`。

## 输入与取样规则

1. 输入可以是：整本书 txt/md、连续几章、或几段代表性正文。
2. **自动识别章节**：`第X章/回/卷`、`第N节`、`Chapter N`，独占一行且正文 ≥60 字的才算有效章节。
3. **章数由用户定**：默认 20，可选 1–总章数，或勾「全部」。不足 20 章就取全部，不因此拒绝。
4. 没有章节标记 → 按字数取样（默认 20000 字，可改）。
5. 取样总长上限 **30000 字**；超出时按章顺序截断，并如实告诉用户“取了 N 章 / M 字”。
6. 分析阶段不要只看开头：长样本按 **头/中/尾** 三段采样（各约 1/3，上限 12000 字）。

## 工作流 A：在工具里点（默认路径）

1. 书架「＋ 新建一本」→ 填书名 →「✨ 萃取小说风格」。
2. 粘贴正文或「导入 .txt / .md」；工具自动显示「检测到 N 章 · X 字」。
3. 选「取样 [20] 章」或勾「全部」，右侧实时显示“取样：N 章 · M 字”。
4.「开始萃取」：第 1 步十维分析（可展开看中间结果），第 2 步生成风格，第 3 步从样本里逐字摘录写作示例；流式输出。
5. 两个结果框都可改；「保存并创建小说」= 存进风格库（风格 + 示例）+ 建书 + 应用到「风格」「示例」两个框；也可「只存到风格库」。
6. 已有小说想换风格：风格面板「AI 萃取」→「用到当前小说」。

## 工作流 B：作为 agent 离线做

1. 读样本（txt/md 直接读；docx 见上游 skill 的 zip+XML 做法，不要 pip install python-docx）。
2. 清洗：去书名/作者/简介/书评/作者的话/广告/页码，压缩连续空行。
3. 按用户要的章数切片（或用工具 `/api/style/scan` 拿章节边界）。
4. 十维分析（严格基于样本，能统计就给数字）。
5. 按「输出规格」写 8 节 Markdown。
6. 存进 `data/styles/<名称>.md`，或直接贴进用户正在编辑的「写作风格 Skill」框。

## 输出规格（8 节，固定顺序）

```
# 风格：<一句话定位>
## 语感          3~6 条：句长、段长、叙述距离、节奏
## 句式          3~5 条：字数/句数/标点/换行
## 用词与修辞    3~6 条：该用的词、该避开的词（给词表）、比喻取材
## 对话          3~5 条：台词长度、动作替代“他说”、标签习惯、语气
## 描写          3~4 条：环境/动作/心理的密度与手法
## 节奏与钩子    3~4 条：冲突出现速度、章末收尾方式
## 禁止清单      6~10 条：逐条“不要……”，专门针对 AI 腔
## 改写时应保留  3~5 条：信息点、伏笔、人物语气、段落与对话结构
```

细节规范、正反例与自检清单见 `references/style_skill_spec.md`；空白模板见 `assets/style_skill_template.md`。

### 配套产物：写作示例

风格只管“怎么写”，示例负责给模型“语感参照”，两件一起才算完整萃取。

- **来源**：2–4 段**逐字摘录**的样本原文（不写、不改、不编），段落间空行分隔。
- 每段 60–150 字，尽量覆盖不同类型：一段叙述、一段对话、一段环境/动作。
- 避开人名地名密集的段落，减少剧情依赖；不要加标题、编号、引号包裹或书名号。
- 合计 300–500 字最合适；太长会挤占修改时的上下文。
- 存盘：`data/styles/<名>.example.md`，与风格同名；从下拉载入风格时一起填回「写作示例」框。
- **必须校验**：模型给的示例必须是样本子串（去空白后比对），否则用本地摘录兜底（`verify_examples` / `pick_examples`）。

## 硬规则

1. **只学笔法**：叙事视角、句式、用词、节奏、钩子；绝不照抄剧情、人物、原句。
2. **每条必须可执行**：写“单段不超过 3 句”“少用四个分句以上的长句”，不写“文笔简洁”“张弛有度”。
3. **禁止清单要具体到词**：列出“仿佛/似乎/缓缓/不禁/莫名/一丝”这类具体禁用词，不要写“避免不合适的写法”。
4. **数字优先**：能给区间就给（段长 20–40 字、对话约占四成、每章环境描写不超过 3 处）。
5. **样本里看不出来就写“不明显”**，绝不脑补；不写样本没有的风格特征。
6. **700–1400 字**，超过就删形容词、合并同类项；低于 500 字视为不合格。
7. **无占位符**（`{}`、`<>`、`XXX`、`待补充`），无代码围栏，直接从 `# 风格：` 开头。
8. 告知用户**实际取样了多少章/多少字**，不要假装读了全书。

## 验证

```bash
PY="C:/Users/Lenovo/AppData/Local/Programs/Python/Python311/python.exe"
"$PY" "skill/novel-style-extractor/scripts/check_style_skill.py" path/to/风格.md
```

脚本检查：起始标题、8 个小节齐全、字数区间、占位符、代码围栏、每节条目数、空话词比例。
端到端则用工具实测：新建小说 → 萃取 → 保存并创建 → 看风格是否已填入、文件是否在 `data/styles/`。

## Pitfalls

- **只取开头**：章数选 20 但只把前 12000 字喂给模型，等于只看了一两章。必须头/中/尾采样。
- **章节标记误判**：目录页的“第一章 …… 3”也会命中。靠过滤阈值排掉：**正文 ≥60 字**才算有效章节（最初写 120 字，会把 300 字的小章全过滤光，`has_chapters` 直接变 false）；不足 2 章就当无章节处理。
- **取样控件联动**：总章数 ≤20 时默认勾「全部」；用户一改章数就要自动取消勾选，否则数字改了预览不动，用户会以为坏了。预览文字必须写“取样：N 章 · M 字”，改数字即时刷新。
- **书架上没打开小说时的模型**：顶部模型下拉只在 `applyNovelToUI` 里渲染，架子页会拿到空值；`currentModel()` 要回退到 `settings.active_model` 而不是 `models[0]`（列表第一个可能是重推理模型 → 直接空输出）。启动时就调一叉 `renderModelSelect()`。
- **把剧情写进规则**：出现人物名、事件复述、原句引用 → 不合格，删掉重写。
- **规则太通用**：满篇“生动/流畅/细腻”等于没萃；用 `check_style_skill.py` 的空话统计兜底。
- **思考型模型空输出**：萃取是短任务，`max_tokens` 给足（分析 2000、成文 2600，失败自动翻倍重试），仍失败就提示换轻量模型。
- **样本太少**（<800 字）只能得到模糊规则，要如实提示用户补样本。
- **示例被模型“改得更顺”**：一旦不是逐字原文就失去语感参照的意义。必须用 `verify_examples` 做子串校验（去空白比对），不通过就走本地 `pick_examples` 兑底，不要直接信任模型输出。
- **弹窗太长把按钮顶出屏幕**：三块文本框 + 三步进度会超过 88vh。给底部操作行加 `position: sticky; bottom`，并把各文本框压到 118/190/120px，保证「保存并创建小说」始终可见。

## 实现位置（改功能时看这里）

- 提示词与切片：`core/style_extract.py`（`ANALYZE_SYSTEM`、`WRITE_SYSTEM`、`EXAMPLE_SYSTEM`、`scan_chapters`、`slice_chapters`、`build_example_messages`、`verify_examples`、`pick_examples`、`clean_skill`）
- 接口：`app.py` → `POST /api/style/scan`（章节边界）、`POST /api/style/extract`（SSE 三段式：analyze → write → example）
- 前端：`web/app.js` → `openStyleExtract()`（取样控件、三步进度、风格框 + 示例框、保存/应用）、`openNewNovel()`（入口按钮）
- 风格落库：`data/styles/<名>.md` + `<名>.example.md`（`store.save_style/get_style`）