Webnovel Writer Skills 重构与 Reference 缺口设计

日期：2026-04-09 状态：草案 v4.3（v4.2 + Codex 二轮 review 3 处修正）目标：在 Claude 已具备通用智能与通用写作能力的前提下，重构 skills/ 体系，并为后续 references/ 补全提供缺口清单。

1. 为什么要写一份新的 spec

1.1 与 v6 spec 的关系

本 spec 是 2026-04-02-harness-v6-design.md（v7）的补充，不是替代。

v6 spec 解决主流程架构：废弃/合并、状态机、memory contract、审查流程、迁移退出标准。Phase 1/2A/3/4 已完成。
本 spec 解决 v6 完成后的文档体系收敛：skills 怎么瘦身、references 怎么设计和补缺。
关于 reference 的设计原则（渐进式披露、三层内容、按需加载、双轨知识库等），以本 spec 为准。

v6 spec 中的以下设计决策本 spec 继承不变：

Write 流程 Step 0.5-6 及状态机
reviewer 单 agent + blocking 修复循环
memory contract v0/v1 接口
章纲字段草案与 writer_exposure_policy 分层

1.2 当前问题

旧的 harness v6 spec 主要解决的是迁移问题（现已大部分完成）。当前真正的问题，已经从“主流程能力缺失”转为“文档体系不够收敛”：

skills/ 的结构风格混杂，有的像主链 SOP，有的像命令手册，有的像小型 spec。
references/ 的职责不稳定：有的在重复 Claude 本来就知道的常识，有的又缺少针对模型缺陷的关键约束。
skills、references、scripts 的边界不够清楚，导致信息重复、维护成本高、补充方向模糊。
对中文网文场景下的模型缺陷补偿不足，例如人物命名复用、套路化桥段复用、题材语汇漂移、对话口吻趋同等。

因此需要一份新的 spec，不再延续“迁移”叙事，而是回答一个更直接的问题：

在 Claude 已经足够聪明的前提下，这个系统还需要哪些最小必要 skills，以及哪些 references 缺口值得补？

2. 核心设计哲学

2.1 Claude 足够聪明

默认前提：Claude 已具备以下能力，不需要在技能文档里重复教学：

通用写作能力
通用总结、提炼、润色能力
常见叙事技巧与常见角色塑造常识
常规软件工程与文件读写能力
一般性的“如何提问用户”“如何组织步骤”“如何做检查”的能力

因此，skills 和 references 不应该承载这些通用常识。

2.2 文档只补“Claude 不稳定、不知道、易做错”的部分

应保留在文档里的内容，必须至少满足以下一种：

项目私有知识：本仓库特有的状态字段、CLI、文件路径、契约、产物位置。
模型缺陷补偿：Claude 高频犯错点，且不能稳定靠通识解决。
题材/平台特异约束：中文网文场景下的特殊要求、风格偏好、禁区。
流程闸门：必须显式满足的步骤顺序、验证条件、失败恢复。
高价值参考：真实范例、反例、命名规则、反模板约束等。

不满足上述条件的信息，原则上不应出现在 skills 或 references 中。

2.3 Reference 设计四原则

以下四条原则是 reference 体系设计的核心约束，所有 reference 新增、保留、删除决策都必须以此为准。

原则 1：渐进式披露

Reference 不是按“知识主题”组织，而是按“哪个 skill 的哪个 step 在执行时需要什么指导”组织。

每个 reference 应尽量能映射到至少一个具体的 skill + step。
若为跨 skill 通用缺陷补偿，应明确主服务场景与次服务场景。
Skill 的引用加载策略必须写清楚“Step N 遇到 X 条件时加载 Y reference”。

原则 2：三层内容分级

同一个 reference 文件内，内容按三个层级组织：

层级	性质	说明	示例
提醒层	Claude 知道，但长文写作时容易忘或不稳定执行	轻量条目，起“别忘了”的作用	“对话不要全员书面语”、“不要每段都以总结句收尾”
缺陷补偿层	Claude 的系统性弱点，靠通识解决不了	需要明确的禁止项、替代方案、判断标准	命名同质化防护、“缓缓/淡淡/微微”固定语式替换、四段闭环结构检测
知识补充层	Claude 知道但不够深/不够全，需要领域知识注入	提供中文网文特有的技法、模式、正反例	追读力钩子技法、特定题材节奏模式、真实小说片段

文件内三层从上到下排列，加载时可根据 token 预算裁剪深度。

原则 3：按需条件加载

Reference 只在当前章节/任务确实触发了对应场景时才加载。

本章没有战斗 → 不加载战斗描写参考
本章没有新角色首次出场 → 不加载命名参考
本章不涉及时间跳跃 → 不加载时间过渡参考

Skill 的引用加载策略必须写明触发条件，而不是“每次都加载全部”。

原则 4：粒度优先对齐稳定问题域

md 文件：优先按稳定问题域、稳定决策点组织，而不是机械切成极小碎片。只有当不同场景确实会产生冲突时，才进一步细拆。

CSV 检索：一次检索返回的结果集等于一个子任务的粒度（同一张 CSV 可包含多种子任务的条目，靠检索过滤）。

这个 step 需要命名 → 检索只返回命名相关条目
这个 step 需要战斗描写 → 检索只返回战斗相关条目
不扩展到“相关但当前不需要”的知识

2.4 references 不是越少越好，而是越“补缺”越好

本轮不追求压缩 references 数量。判断标准不是“文件是否减少”，而是：

该 reference 是否真正补到了 Claude 的稳定性缺口或项目私有知识缺口。

因此：

若现有 references 冗余，应删除或合并。
若现有 references 缺失，而该缺失会稳定导致错误，应新增。
新增 reference 的理由必须清楚说明“它补的是什么缺口”。

例如：

人物命名规则
题材专属命名禁区
中文网文对话口吻差异
特定题材常见模板腔与避坑清单

这些都属于合理新增。

2.5 skills 是工作流入口，不是百科

SKILL.md 负责：

定义适用场景
组织执行顺序
指定必要输入输出
指明何时读哪些 reference
定义验证与恢复规则

SKILL.md 不负责：

展开大量常识性方法论
承载完整范例库
细讲脚本内部实现
变成“小型全书教程”

2.6 中文化与网文化优先

本系统服务于中文网络小说写作，文档语言应优先使用中文网文领域词汇。原则如下：

正文叙述默认中文。
优先使用网文专用名词：章纲、卷纲、钩子、爽点、微兑现、追读力、吃书、毒点、设定冲突等。
字段名、CLI 子命令、frontmatter、JSON key、协议名保留必要英文。
同一概念尽量只保留一个主称呼。

题材分类中文化

现有 genres/ 目录使用英文名（xuanhuan、realistic 等），本轮需统一为中文题材名。当前第一版默认以番茄小说网题材分类作为映射基准，后续允许扩展平台映射层。

男频： 都市、玄幻、仙侠、奇幻、武侠、历史、军事、科幻、悬疑、游戏、体育、轻小说 女频： 现言、古言、幻言、悬疑、轻小说

CSV 知识库中的 适用题材 列使用上述中文名。全部 表示不限题材。

现有 genres/ 目录的映射关系：

现有目录名	对应番茄题材
`xuanhuan/`	玄幻
`realistic/`	都市
`dog-blood-romance/`	现言
`rules-mystery/`	悬疑
`period-drama/`	古言、历史
`zhihu-short/`	短篇 / 轻小说（临时映射）

3. 文档分层职责

本轮只重构三层：

skills/
references/
scripts/

3.1 skills 负责什么

skills 负责：

任务入口与适用场景
主流程步骤
前置条件
必要 references 的加载策略
交付物与成功标准
失败恢复与补跑规则

skills 不负责：

大段方法论教学
完整案例库
模型常识补课
重复解释底层脚本实现

3.2 references 负责什么

references 负责（遵循 §2.3 四原则）：

绑定到具体 skill + step 的子任务指导
Claude 不稳定的高频缺陷补偿（缺陷补偿层）
Claude 知道但容易遗忘的执行要点（提醒层）
Claude 知道但不够深的领域知识补充（知识补充层）
项目私有规范（CLI、字段、路径等）
高价值正反例（真实小说片段）
题材特异规则与禁区清单

references 不负责：

通用写作常识（Claude 已知且稳定执行的部分）
大而空的方法论概述
不带判断标准的结构模板
不绑定到任何 step 的知识堆积

3.3 scripts 负责什么

scripts 负责：

容易出错、可执行、可验证的稳定操作
数据处理、验证、生成、迁移、索引等可程序化步骤

scripts 不负责：

替代 skill 的流程设计
承载主业务说明
替代 reference 的领域规则解释

3.4 脚本化触发条件

出现以下任一情况时，应优先评估是否脚本化，而不是继续扩写 skill 或 reference：

同一操作会被多个 skill 重复调用
成败可程序化判断
人工描述过长且容易误解
需要稳定过滤 / 检索 / 校验
出错代价较高，且希望避免靠人工执行记忆

4. 本轮重写原则

4.1 不先写抽象模板文档，直接逐 skill 设计

本轮不先产出一份“统一 skill 模板”。原因：

不同 skill 的功能差异很大。
先写抽象模板容易过早收敛，反而束缚设计。
当前更适合直接对现有 skill 做问题导向重构。

但所有 skill 重写后都应满足以下共同要求：

适用场景清楚
前置条件清楚
流程主线清楚
references 加载策略清楚
验证与恢复规则清楚
正文语言中文化、网文化

4.2 先 skill，后 reference 正文

本轮顺序固定为：

先明确每个 skill 的职责与结构。
再列出它缺哪些 reference 文件。
references 正文在下一阶段逐个补齐。

因此本 spec 中，references 只写：

文件名
作用
解决的缺陷类型
归属 skill

不展开全文内容设计。

4.3 reference 新增判断标准

新增 reference 必须同时满足：

绑定检查：能指出“哪个 skill 的哪个 step 在什么条件下加载它”；若为跨 skill 通用 reference，需写清主服务场景与次服务场景。
缺口检查：Claude 当前在这个子任务中是稳定犯错（缺陷补偿）、容易遗忘（提醒）、还是知识不足（补充）；至少命中一种。
独立性检查：这个指导是否无法靠 skill 主流程的一两句话自然覆盖；若能内联解决，不独立建文件。
必要性检查：如果不新增这份 reference，是否会稳定导致错误重复发生；若不会，优先通过 skill 流程、脚本或验证机制解决。

四条全过才新增。

4.4 Skill 正文必须包含的结构要素

除 §4.1 的共同要求外，按优先级分层：

P0 skills：必须包含红旗 / 常见误区、优先级链、决策树入口三项
P1 skills：至少显式包含其中 1-2 项
P2 skills：按需采用，不强制

红旗 / 常见误区区块

每个主链 skill 必须包含一个专门的“常见误区”列表，描述 Claude 真实会犯的思维错误而非抽象禁令。

示例（webnovel-write）：

## 常见误区
- ❌ 认为本章简单就跳过 Step 3 审查
- ❌ Step 5 失败后直接开始下一章（状态还在 chapter_reviewed）
- ❌ 把全部 reference 一次性读完再开始写
- ❌ blocking issue 存在但觉得“不严重”就跳过
- ❌ 用文件存在性替代 chapter_status 判断
- ❌ 润色时改了事件顺序或设定

优先级链

当多个指令来源冲突时，skill 必须写明裁决顺序：

1. 用户明确要求（最高）
2. 状态机 / 流程硬门槛（chapter_status、blocking）
3. 项目私有约束（设定集、已有剧情）
4. skill 默认工作流
5. reference 建议（最低）

决策树入口

Skill 正文不只是线性步骤列表，还必须在流程开头或关键分支处提供决策判断。最少覆盖：

什么情况下继续下一步
什么情况下阻断
什么情况下回退到上一步
什么情况下需要用户裁决

5. 技能总览矩阵

Skill	当前主要问题	重写目标	需补 references	优先级
`webnovel-write`	主链过重，已有大量规则堆叠；需进一步明确主流程与引用边界	作为主链总控 skill，只保留主流程、闸门、交付物、恢复规则	高	P0
`webnovel-review`	结构较简，但需与 reviewer / review-pipeline / 状态机更清晰衔接	成为独立审查流程入口，收敛报告与阻断处理	中	P0
`webnovel-plan`	内容多、层级杂，兼有规则与参考说明	收敛为规划流程入口，结构化节点与卷级规划清楚	高	P0
`webnovel-init`	过重，像 mini-spec；交互采集、规则、资料混在一起	收敛为初始化工作流 skill，复杂知识下沉到 reference	高	P1
`webnovel-query`	查询逻辑清楚，但文档像操作手册；可进一步减少低层命令暴露	收敛为查询 / 分析型 skill	中	P1
`webnovel-dashboard`	过轻，像启动命令说明；缺验证与失败恢复结构	收敛为工具启动型 skill	低	P2
`webnovel-learn`	过轻，像命令说明；缺边界与恢复规则	收敛为轻量记录型 skill	低	P2

6. 逐个 skill 改造方案

6.1 `webnovel-write`

当前问题

承载了太多细节，容易继续膨胀。
某些 reference 内容仍偏“方法论说明”，未完全下沉。
已有状态机闸门，但结构仍偏大而全。

重写目标

明确它是主链总控 skill。
保留：主流程、状态推进、阻断规则、必要 references、交付物、恢复规则。
明确不承载：命名细则、对话风格方法论、题材命名库、桥段范例库，这些必须下沉到 references。

结构改动

建议正文只保留这些块：

目标与适用场景
常见误区（§4.4 红旗区块）
优先级链（§4.4）
前置条件与环境准备
引用加载策略（Step 级，含 CSV 检索触发条件）
主流程（Step 0.5-6，含决策树入口）
状态推进与阻断规则
充分性闸门
验证与交付
失败恢复

当前 SKILL.md 段落去留表

当前段落	处置	理由
目标	保留	核心定义
执行原则	保留	闸门硬约束
模式定义	保留	标准 / fast / minimal 区分
引用加载等级（L0/L1/L2）	保留	按需加载策略
References 列表	重写	改为按 Step 触发条件组织，加条件加载说明
工具策略	保留，精简	只保留 CLI 入口，不展开参数细节
准备阶段	保留	preflight + 环境变量
Step 0.5-6	保留	核心流程
问题定向参考列表	下沉	移到 reference index 或 Step 内触发条件
充分性闸门	保留	已切到状态机
验证与交付	保留	已用 chapter_status
失败处理	保留	补跑规则

references 触发绑定

以 §2.3 四原则为标准，按 Step + 触发条件组织。md 文件直接 Read，CSV 通过检索脚本按需获取。

md 必读（直接 Read）

Step	触发条件	加载的 reference
Step 1	每次执行	`references/reading-power-taxonomy.md`、`references/genre-profiles.md`、`skills/webnovel-write/references/style-variants.md`
Step 2	每次执行	`references/shared/core-constraints.md`、`skills/webnovel-write/references/anti-ai-guide.md`
Step 4	每次执行	`skills/webnovel-write/references/polish-guide.md`、`skills/webnovel-write/references/writing/typesetting.md`、`skills/webnovel-write/references/style-adapter.md`

CSV 检索（调用 `reference_search.py`）

Step	触发条件	检索参数
Step 2	本章有新角色首次出场	`--skill write --table 命名规则 --query "角色命名" --genre {题材}`
Step 2	本章有战斗 / 对峙场景	`--skill write --query "战斗描写" --genre {题材}`
Step 2	本章有多角色对话	`--skill write --query "对话声线口吻区分"`
Step 2	本章有情感 / 心理描写	`--skill write --query "情感描写心理"`
Step 2	本章涉及高频桥段	`--skill write --table 场景写法 --query "{桥段类型}"`
Step 4	ai_flavor issue 存在	`--skill write --query "AI味反例替换"`

scripts 需求

暂不新增脚本作为前置条件。
若后续发现命名校验可程序化，可新增轻量命名检查脚本。

验收点

主流程阅读路径明显缩短
每一步只在触发条件满足时加载对应 references
状态机与交付物逻辑不弱化
不再在 skill 正文中展开大段常识性写作建议

6.2 `webnovel-review`

当前问题

流程清楚，但与 reviewer / review-pipeline / 报告落盘的边界还可再清楚。
阻断与返工逻辑可进一步明确成“审查型 workflow”。

重写目标

成为独立审查 skill：从输入章节到输出审查报告、落库、写回记录。
不承载过多审查理论；理论交给 reviewer 和 references。

结构改动

保留：

适用场景
常见误区（§4.4）
优先级链（§4.4）
项目根解析
引用加载
调用 reviewer（含决策树：blocking → 返工 / override）
生成报告与落库
处理 blocking 与用户决策
成功标准与恢复规则

references 触发绑定

md 必读

Step	触发条件	加载的 reference
Step 2（加载参考）	每次执行	`references/shared/core-constraints.md`、`references/review-schema.md`
Step 6（处理阻断）	存在 blocking issue 需用户决策	`references/review/blocking-override-guidelines.md`

CSV 检索

Step	触发条件	检索参数
Step 4（调用 reviewer）	ai_flavor issue 数量 ≥ 3	`--skill review --query "AI味反例替换"`

scripts 需求

不新增主流程脚本。
后续若独立复检需要稳定接口，可考虑加 review-ai-flavor-check.py。

验收点

阻断处理路径清楚
审查产物路径稳定
不再重复 reviewer 本身的详细检查维度

6.3 `webnovel-plan`

当前问题

文档同时承担：设定补齐、卷节拍、时间线、章纲、节点规范、写回设定。
很多规则适合作为 reference，而不是主 skill 正文。

重写目标

成为规划主流程入口，重点强调：
- 卷级目标
- 时间线硬约束
- 批量拆章流程
- 结构化节点产物
将题材节奏、冲突设计等下沉到 reference。

结构改动

建议主结构为：

目标与适用范围
常见误区（§4.4 红旗区块）
优先级链（§4.4）
前置条件
引用加载策略
规划主流程（Step 1-9，含决策树入口）
结构化节点产物要求
硬失败条件
恢复规则

references 触发绑定

md 必读

Step	触发条件	加载的 reference
章纲拆分	每次执行	`references/outlining/plot-signal-vs-spoiler.md`

CSV 检索

Step	触发条件	检索参数
卷级规划	每次执行	`--skill plan --table 场景写法 --query "卷级结构叙事功能"`
章纲拆分	新增角色出现	`--skill plan --table 命名规则 --query "角色命名" --genre {题材}`

scripts 需求

暂不新增。
后续若时间线验证继续复杂化，可考虑补独立校验脚本。

验收点

主流程更像“规划入口”，不是“全量教程”
题材与冲突知识显著下沉到 references
批次、节点、时间线规则清楚且集中

6.4 `webnovel-init`

当前问题

体量过大，已接近 mini-spec。
用户采集、题材策略、创意约束、资料索引混在一起。

重写目标

成为初始化访谈与生成工作流。
主 skill 只保留信息采集流程、充分性闸门、生成与验证。
题材、命名、卖点、创意约束等知识下沉到 references。

结构改动

建议主结构为：

目标与适用场景
交互原则
分步采集流程
充分性闸门
生成步骤
验证与交付
最小回滚

references 触发绑定

md 必读

Step	触发条件	加载的 reference
卖点 / 题材采集	每次执行	`references/genre-profiles.md`

CSV 检索

Step	触发条件	检索参数
起名采集	用户开始设定角色 / 书名 / 势力名	`--skill init --table 命名规则 --query "{命名对象} {题材}" --genre {题材}`

注：原 title-patterns-and-anti-patterns.md 和 protagonist-flaw-patterns.md 不直接纳入本轮缺口清单，后续若实测出现稳定缺陷再补回。

scripts 需求

暂不新增，仍以现有 init_project.py 为主。

验收点

skill 正文显著瘦身
交互流程更清楚
创意 / 题材 / 命名类细节下沉

6.5 `webnovel-query`

当前问题

查询流程本身合理，但文档风格偏操作手册。
暴露较多低层步骤，可进一步强调“查询类型识别 + 数据源选择 + 输出格式”。

重写目标

成为查询 / 分析型 skill。
强调：
- 查询意图识别
- 按需加载 reference
- 读取最少必要数据
- 输出结构化回答

结构改动

建议保留：

Use when
项目根保护
查询类型识别
引用加载等级
查询流程
输出格式
边界

references 触发绑定

无新增刚需。当前 query skill 的参考需求主要是项目私有知识（CLI 用法、数据源），已内联在 skill 中。

注：entity-alias-resolution.md、foreshadowing-urgency-rules.md 暂列为候选，待实测若输出不稳则补回。

scripts 需求

无新增刚需。

验收点

更像查询工作流，而不是大段说明书
输出风格统一

6.6 `webnovel-dashboard`（P2，方向简述）

收敛为工具启动型 skill：补齐环境检查、启动步骤、成功判定、常见故障处理。P2 不强制三件套，不挂独立 reference，现有功能已基本自洽。

6.7 `webnovel-learn`（P2，方向简述）

收敛为轻量记录型 skill：重点明确何时记录、输入结构、幂等 / 去重、写回格式、失败处理。P2 不强制三件套，是否补 pattern-taxonomy 视实测而定。

7. Reference 体系设计（双轨制）

本轮 reference 采用双轨制：流程必读型（md）+ 写作知识库型（CSV + 检索脚本）。

7.1 双轨分工

轨道	格式	加载方式	承载内容	示例
流程必读型	`.md` 文件	Skill 指定 step 直接 `Read`	闸门规则、schema 定义、核心约束、审查标准	`core-constraints.md`、`review-schema.md`、`polish-guide.md`
写作知识库型	`.csv` + Python 检索脚本	Step 遇到特定场景时调用脚本，只返回命中条目	写作技法、题材写法、场景灵感、命名规则、正反例	`写作技法.csv`、`命名规则.csv`、`场景写法.csv`

分界标准：

流程/契约/闸门/schema → md（必须完整读取，不能只看片段）
写作知识/技法/灵感/正反例 → CSV（条目多、按需检索、只取相关的几条）

7.2 CSV 知识库设计

文件位置

webnovel-writer/
  data/                          # CSV 知识库根目录
    写作技法.csv
    命名规则.csv
    场景写法.csv
  scripts/
    reference_search.py          # 统一检索脚本（BM25）

编码

所有 CSV 文件使用 UTF-8 with BOM（utf-8-sig），确保 Windows 下 Excel 可正确打开中文。

通用列（所有 CSV 共有）

列名	类型	说明	示例值
`编号`	string	唯一 ID，前缀区分表	`WT-001`、`NR-012`、`SP-003`
`适用技能`	string	粗筛，逗号分隔	`write` 或 `init,plan` 或 `init,plan,write`
`分类`	string	场景大类	`战斗`、`对话`、`命名`、`情感`、`场景`
`层级`	string	三层标记	`提醒` / `缺陷补偿` / `知识补充`
`关键词`	string	BM25 检索用，逗号分隔	`打斗,武斗,对决,境界压制`
`适用题材`	string	番茄分类题材名，逗号分隔	`全部` 或 `玄幻,仙侠`

写作技法表（`写作技法.csv`）

列名	说明
（通用列）
`技法名称`	技法的简短名称
`说明`	技法描述
`正例`	正面示范，可放长片段（200-500 字）
`反例`	反面示范，可放长片段
`修复建议`	从反例到正例的修改方向

示例行：

编号,适用技能,分类,层级,关键词,适用题材,技法名称,说明,正例,反例,修复建议
WT-001,write,对话,缺陷补偿,"口吻趋同,对话区分,角色声线",全部,对话声线差异化,不同角色的对话应有可辨识的口语特征和节奏差异,"老张头叼着烟袋锅子，""嘿，你小子又来蹭饭？""...","两人对话风格完全一致，都是标准书面语",给每个角色设定 1-2 个口语标记词和句式习惯

命名规则表（`命名规则.csv`）

列名	说明
（通用列）
`命名对象`	`角色` / `地点` / `势力` / `功法` / `道具` / `书名`
`规则`	规则描述
`正例`
`反例`

场景写法表（`场景写法.csv`）

列名	说明
（通用列）
`场景类型`	`告白`、`打脸`、`觉醒`、`战斗`、`谈判`、`追逐`、`日常`、`离别` 等
`模式名称`	这种写法的名称
`说明`	模式描述
`示例片段`	可放长片段（200-500 字）
`反面写法`	要避免的写法

7.3 检索脚本设计

CLI 接口

# 基本用法：按当前 skill 和关键词检索
python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
  --skill write \
  --query "战斗描写 境界压制" \
  --max-results 3

# 指定题材过滤
python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
  --skill write \
  --query "命名 角色" \
  --genre "玄幻" \
  --max-results 5

# 指定表
python -X utf8 "${SCRIPTS_DIR}/reference_search.py" \
  --skill plan \
  --table 命名规则 \
  --query "跨卷 角色命名" \
  --max-results 3

检索流程

1. 按 `适用技能` 列过滤（粗筛）
2. 按 `适用题材` 列过滤（可选，若指定 --genre）
3. 在过滤后的结果集内做 BM25 关键词检索
4. 返回 top N 条，格式化输出

输出格式

## 检索结果（写作技法）
查询：战斗描写 境界压制 | 技能：write | 题材：玄幻 | 命中：3 条

### [WT-023] 境界压制的体感描写
- 层级：知识补充
- 说明：通过身体反应而非数值对比来表现境界差距
- 正例：（片段...）
- 反例：（片段...）
- 修复建议：...

### [WT-045] ...

7.4 流程必读型 reference（md 文件，保留/新增）

以下 md reference 保留或新增，由 Skill 在指定 step 直接 Read：

文件	类型	服务 skill	加载时机
`references/shared/core-constraints.md`	保留	write/Step 2	每次执行
`references/review-schema.md`	保留	write/Step 3、review/Step 4	每次执行
`references/shared/cool-points-guide.md`	保留	review	按需
`references/shared/strand-weave-pattern.md`	保留	review	按需
`references/reading-power-taxonomy.md`	保留	write/Step 1	每次执行
`references/genre-profiles.md`	保留	write/Step 1、init	每次执行
`skills/webnovel-write/references/style-variants.md`	保留	write/Step 1	每次执行（差异化设计）
`skills/webnovel-write/references/polish-guide.md`	保留	write/Step 4	每次执行
`skills/webnovel-write/references/anti-ai-guide.md`	保留	write/Step 2	每次执行
`skills/webnovel-write/references/style-adapter.md`	保留	write/Step 4	每次执行
`skills/webnovel-write/references/writing/typesetting.md`	保留	write/Step 4	每次执行
`references/review/blocking-override-guidelines.md`	新增	review/Step 6	存在 blocking issue 需用户决策时
`references/outlining/plot-signal-vs-spoiler.md`	新增	plan/章纲拆分	每次执行

7.5 写作知识库型 reference（CSV 文件，新增）

以下知识从现有 md 文件迁移或新建到 CSV：

现有 md 文件	迁移到 CSV	迁移后 md 处置
`writing/combat-scenes.md`	`场景写法.csv`（场景类型=战斗）	删除或保留为空壳指向 CSV
`writing/dialogue-writing.md`	`写作技法.csv`（分类=对话）	同上
`writing/emotion-psychology.md`	`写作技法.csv`（分类=情感）	同上
`writing/scene-description.md`	`写作技法.csv`（分类=场景）	同上
`writing/desire-description.md`	`写作技法.csv`（分类=情感）	同上
`writing/genre-hook-payoff-library.md`	`场景写法.csv`（场景类型=钩子/兑现）	同上
（新增）命名规则	`命名规则.csv`	无现有文件
（新增）对话声线差异化	`写作技法.csv`（分类=对话，层级=缺陷补偿）	无现有文件
（新增）反模板桥段	`场景写法.csv`（层级=缺陷补偿）	无现有文件
（新增）AI味正反例	`写作技法.csv`（分类=AI味，层级=缺陷补偿）	无现有文件
（新增）卷级叙事功能模式	`场景写法.csv`（场景类型=卷级结构，适用技能=plan）	无现有文件

7.6 被过滤掉的原提案

以下提案当前不纳入，但不是永久排除。判断标准：Claude 在中文网文场景下若实测输出稳定性不足，仍可后续补回。

原提案	当前过滤理由	恢复条件
`init/title-patterns-and-anti-patterns.md`	书名命名可作为 `命名规则.csv` 中几行条目（`命名对象=书名`）	若 CSV 几行不够覆盖、实测书名模板化严重，升级为独立条目组
`init/protagonist-flaw-patterns.md`	Claude 通用能力可覆盖	若实测缺陷设计在网文场景下空泛化、标签化严重，补为 CSV 条目
`query/entity-alias-resolution.md`	别名解析是代码逻辑（entity_linker.py）	若代码无法覆盖的语义歧义频发，补 reference
`query/foreshadowing-urgency-rules.md`	紧急度排序已在 context-agent 实现	若输出解释不稳定，补 reference
`learn/pattern-taxonomy.md`	learn skill 低频，分类规则内联 skill 即可	若分类质量持续不稳，补 CSV 条目

8. 分批实施顺序

第零批：基础设施

实现 reference_search.py（BM25 检索脚本）
建立 data/ 目录和 3 个 CSV 文件骨架（表头 + 少量种子数据）
补测试：确认检索脚本的粗筛 → 题材过滤 → BM25 流程跑通
现有 genres/ 目录名中文化映射

目标：CSV 知识库基础设施就绪，后续批次可直接往里填数据。

第一批：主链 skills（P0）

webnovel-write
webnovel-review
webnovel-plan
新增 P0 skill 依赖的 md reference：blocking-override-guidelines.md（review）、plot-signal-vs-spoiler.md（plan）

目标：先收敛主链工作流入口，skill 正文切到双轨 reference 加载。

冻结点： 第一批完成后，review 确认主链 skill 结构稳定、md/CSV 触发绑定表无遗漏，再进入第二批。

第二批：初始化与查询（P1）

webnovel-init
webnovel-query

目标：收敛前置采集和查询分析文档。

第三批：内容填充 + 辅助类（P2）

webnovel-dashboard
webnovel-learn
将现有 md reference 中的写作知识迁移到 CSV
逐步扩充 CSV 条目（可持续进行，不阻塞主链）

目标：完成轻量技能整理，CSV 知识库进入持续填充阶段。

9. 验收标准

本轮重构完成时，应满足：

所有 skills 都有清晰的主功能定位，不再混合成”手册 + 教程 + spec”。
skills 正文明显收敛为：流程、闸门、交付物、恢复规则。
skill 结构要素分层落地：P0 skill 包含红旗/优先级链/决策树全三项，P1 至少 1-2 项，P2 按需（§4.4）。
reference 双轨制落地：流程必读型 md + 写作知识库型 CSV，职责不混。
reference_search.py 可正常检索，粗筛（适用技能）→ 题材过滤 → BM25 全链路跑通。
CSV 文件均为 UTF-8 with BOM 编码，Windows Excel 可正确打开。
题材分类已中文化（当前以番茄小说网分类为默认基准），现有 genres/ 目录完成映射。
不再以”减少 reference 数量”为目标，而以”高价值补缺”为目标。
技能正文语言完成中文化/网文化，字段和协议保留必要英文。
新增或重写后的 skill 可通过 prompt integrity 检查与人工走读。

10. 本 spec 的边界

本 spec 不处理：

agents/ 重写（agent 只有 prompt 本体，不挂 reference 文件）
references 正文具体内容撰写（仅定义文件名、触发绑定、内容层级）
scripts 的完整实现细节
v6 迁移 spec 中已确认的架构决策（状态机、memory contract、reviewer 流程等）

本 spec 只回答： skills 下一步应该怎么重写，以及 references 下一步该补哪些文件、在什么条件下加载。

2026-04-09-skills-restructure-and-reference-gaps.md 34 KB Permalink Cronologia Originale

Webnovel Writer Skills 重构与 Reference 缺口设计

1. 为什么要写一份新的 spec

1.1 与 v6 spec 的关系

1.2 当前问题

2. 核心设计哲学

2.1 Claude 足够聪明

2.2 文档只补“Claude 不稳定、不知道、易做错”的部分

2.3 Reference 设计四原则

原则 1：渐进式披露

原则 2：三层内容分级

原则 3：按需条件加载

原则 4：粒度优先对齐稳定问题域

2.4 references 不是越少越好，而是越“补缺”越好

2.5 skills 是工作流入口，不是百科

2.6 中文化与网文化优先

题材分类中文化

3. 文档分层职责

3.1 skills 负责什么

3.2 references 负责什么

3.3 scripts 负责什么

3.4 脚本化触发条件

4. 本轮重写原则

4.1 不先写抽象模板文档，直接逐 skill 设计

4.2 先 skill，后 reference 正文

4.3 reference 新增判断标准

4.4 Skill 正文必须包含的结构要素

红旗 / 常见误区区块

优先级链

决策树入口

5. 技能总览矩阵

6. 逐个 skill 改造方案

6.1 webnovel-write

当前问题

重写目标

结构改动

当前 SKILL.md 段落去留表

references 触发绑定

md 必读（直接 Read）

CSV 检索（调用 reference_search.py）

scripts 需求

验收点

6.2 webnovel-review

当前问题

重写目标

结构改动

references 触发绑定

md 必读

CSV 检索

scripts 需求

验收点

6.3 webnovel-plan

当前问题

重写目标

结构改动

references 触发绑定

md 必读

CSV 检索

scripts 需求

验收点

6.4 webnovel-init

当前问题

重写目标

结构改动

references 触发绑定

md 必读

CSV 检索

scripts 需求

验收点

6.5 webnovel-query

当前问题

重写目标

结构改动

references 触发绑定

scripts 需求

验收点

6.6 webnovel-dashboard（P2，方向简述）

6.7 webnovel-learn（P2，方向简述）

7. Reference 体系设计（双轨制）

7.1 双轨分工

2026-04-09-skills-restructure-and-reference-gaps.md 34 KB

Permalink Cronologia Originale

6.1 `webnovel-write`

CSV 检索（调用 `reference_search.py`）

6.2 `webnovel-review`

6.3 `webnovel-plan`

6.4 `webnovel-init`

6.5 `webnovel-query`

6.6 `webnovel-dashboard`（P2，方向简述）

6.7 `webnovel-learn`（P2，方向简述）

写作技法表（`写作技法.csv`）

命名规则表（`命名规则.csv`）

场景写法表（`场景写法.csv`）