@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/docs/material-library/README.md

@@ -0,0 +1,404 @@
+# 网文创作素材库 · 原子素材版
+
+> 一条素材 = 一个小积木：一个名字、一句外貌、一条能力机制、一句代价、一个颜色词、一条世界规则。
+> 不写“人物大卡”“金手指大卡”“武器大卡”；人物、能力、物品、场景由很多小积木拼出来。
+
+## 1. 文件说明
+
+```text
+docs/material-library/
+├── prompt.md       # 给 LLM 的原子素材生成提示词
+├── schema.surql    # SurrealDB 表、字段、索引
+├── sample.jsonl    # 14 条原子素材示例
+├── import.js       # 校验 / JSONL → SurrealQL / 追加导入
+├── queries.surql   # 常用查询
+└── README.md
+```
+
+插件：
+
+```text
+plugins/fancy-material/
+├── index.js
+├── templates.js
+├── kinds.js                 # 54 个 kind 的单一事实来源
+├── genres.js                # topic_decision / 番茄题材提取
+├── inventory.js             # 已有素材索引、按 kind 计数
+├── queue.js                 # 按 kind 排队、计算每批还差多少
+├── exporter.js              # 导出 Markdown
+├── scripts/query.js         # 生成前查询数据库
+├── validate.js              # 生成后校验 JSONL 格式
+└── scripts/...
+```
+
+## 2. 原子素材模型
+
+每条素材有七个字段：
+
+```json
+{
+  "id": "place_name_gui_xu_v4",
+  "kind": "place_name",
+  "name": "归墟",
+  "tags": ["地名", "海", "尽头", "仙侠", "不祥"],
+  "genres": ["仙侠", "通用"],
+  "note": "",
+  "source": "builtin"
+}
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | `<kind>_<ascii_slug>_v4`，全局唯一 |
+| `kind` | 是 | `source=builtin` 时必须是 54 个原子类型之一；`source=other` 时不受限制 |
+| `name` | 是 | 素材本体：名字、短语、一句话机制/代价/规则/钩子 |
+| `tags` | 是 | 3–8 个短标签 |
+| `genres` | 是 | 1–3 个适用题材；跨题材写 `["通用"]` |
+| `note` | 否 | 只有 `name` 不够清楚时补一句 |
+| `source` | 是 | `builtin` 或 `other`；生成素材固定 `builtin` |
+
+`source` 用来区分内置素材和外部素材：`builtin` 的 `kind` 受 54 个类型限制；`other` 可以写任意自定义 `kind`。不再有 `payload`、`summary`、`description`、`core_hook`、`market_diff`、`search_text` 这些复合字段。
+
+### 2.1 `name` 是内容，不是标题
+
+```json
+{"kind":"given_name","name":"砚秋"}
+{"kind":"color_word","name":"被雨泡过的朱砂"}
+{"kind":"ability_mechanism","name":"触碰死者眼睛，进入他死前最后24分钟的主观视角"}
+{"kind":"ability_cost","name":"每次使用后永久丢失一段与死者无关的等长记忆"}
+{"kind":"conflict_seed","name":"妻子要保险金救女儿，主角要证明她杀了丈夫"}
+{"kind":"brainstorm","name":"给活人打印死亡证明的打印店"}
+```
+
+### 2.2 素材必须独立
+
+- 武器、法宝、技能名、光影特效、人物名分别成条。
+- 不写“这把剑的专属特效是……”。
+- 需要搭配时用 `tags` 表达，例如 `["剑","雷系","高速"]`；不要写从属关系。
+- 一条素材删掉后正文没有任何损失，就不收。
+
+## 3. 54 个 kind
+
+### 命名
+
+```text
+surname, given_name, nickname, place_name, faction_name,
+skill_name, ability_name, item_name, monster_name, mythic_being, rank_name
+```
+
+### 人物
+
+```text
+person_appearance, person_temperament, person_personality, person_habit,
+person_voice, person_background
+```
+
+### 关系与情绪
+
+```text
+reaction
+```
+
+### 能力
+
+```text
+ability_mechanism, ability_activation, ability_cost, ability_limit,
+ability_counter, power_source
+```
+
+### 物品
+
+```text
+item_form, item_material, item_function, item_visual
+```
+
+### 场景与感官
+
+```text
+location_feature, weather, sensory_taste, sensory_visual
+```
+
+### 描写词库
+
+```text
+color_word, light_word, sound_word, smell_word, touch_word,
+effect_word, speed_word, atmosphere_word, appearance_word,
+expression_word, action_verb
+```
+
+### 世界与势力
+
+```text
+world_rule, faction_culture, faction_symbol, ritual
+```
+
+### 剧情与脑洞
+
+```text
+brainstorm, conflict_seed, conflict_escalation, plot_twist,
+mystery_seed, payoff_scene, trope
+```
+
+完整中文名和 `name` 写法见 `prompt.md` 的「素材类型总表」。
+
+## 4. 快速开始
+
+### 4.1 建表
+
+```bash
+surreal sql \
+  --endpoint http://127.0.0.1:8000 \
+  --user root --pass root \
+  --namespace fancy --database material_library \
+  --multi < docs/material-library/schema.surql
+```
+
+`/fancy-bootstrap` 和 `/fancy-db init` 也会自动创建这张表。
+
+### 4.2 校验并导入
+
+```bash
+node docs/material-library/import.js --check docs/material-library/sample.jsonl
+node docs/material-library/import.js \
+  --endpoint http://127.0.0.1:8000 \
+  --namespace fancy --database material_library \
+  --user root --pass root \
+  docs/material-library/sample.jsonl
+```
+
+输出：
+
+```text
+✅ 导入完成：新增 14 条素材，跳过 0 条已存在素材。
+```
+
+默认只追加：
+
+- 已存在 `id` → 跳过
+- 同 `kind + name` → 跳过
+- 需要修订旧条目时才加 `--update`
+
+`sample.jsonl` 的素材都是 `source=builtin`。要导入自定义 kind，写
+`"source":"other"`，例如：
+
+```json
+{"id":"custom_note_1","kind":"custom_lore","name":"自定义设定","tags":["自定义","设定","测试"],"genres":["悬疑"],"note":"","source":"other"}
+```
+
+### 4.3 大批量导入
+
+```bash
+node docs/material-library/import.js \
+  --with-schema \
+  --to-surql /tmp/materials.surql \
+  docs/material-library/sample.jsonl
+
+surreal import \
+  --endpoint http://127.0.0.1:8000 \
+  --user root --pass root \
+  --namespace fancy --database material_library \
+  /tmp/materials.surql
+```
+
+生成的是带存在性守卫的 `IF ... CREATE`，重复导入不会覆盖。
+
+## 5. 查询
+
+完整示例见 `queries.surql`。
+
+### 5.1 仙侠地名
+
+```sql
+SELECT id, kind, name, tags, genres, search::score(1) AS score
+FROM material
+WHERE kind = 'place_name'
+  AND genres CONTAINS '仙侠'
+  AND name @1@ '海 尽头 旧城'
+ORDER BY score DESC
+LIMIT 10;
+```
+
+### 5.2 悬疑男主名字
+
+```sql
+SELECT id, kind, name, tags, genres
+FROM material
+WHERE kind = 'given_name'
+  AND genres CONTAINS '悬疑'
+  AND tags CONTAINSANY ['男', '正派']
+LIMIT 20;
+```
+
+### 5.3 红色系描写词
+
+```sql
+SELECT id, kind, name, tags, genres
+FROM material
+WHERE kind = 'color_word'
+  AND tags CONTAINSANY ['红', '暖色']
+LIMIT 20;
+```
+
+### 5.4 能力机制和代价
+
+```sql
+SELECT id, kind, name, tags, genres
+FROM material
+WHERE kind IN ['ability_mechanism', 'ability_cost']
+  AND name @1@ '记忆 死者 调查'
+LIMIT 10;
+```
+
+### 5.5 生成前查询数据库
+
+```bash
+node plugins/fancy-material/scripts/query.js \
+  --workspace /path/to/A --kind place_name --name '归墟' --json
+
+node plugins/fancy-material/scripts/query.js \
+  --workspace /path/to/A --genre '仙侠·修真文明' --kind color_word --limit 20 --json
+
+node plugins/fancy-material/scripts/query.js \
+  --workspace /path/to/A --search '残影 高速' --limit 20 --json
+```
+
+## 6. 索引
+
+| 索引 | 字段 | 用途 |
+| --- | --- | --- |
+| `material_kind` | `kind` | 按类型过滤 |
+| `material_name` | `name` | 按名字查 |
+| `material_tags` | `tags` | 标签过滤 |
+| `material_genres` | `genres` | 题材过滤 |
+| `material_kind_name_unique` | `kind, name` | 防止同名同类型重复 |
+| `material_name_search` | `name` | 中文 ngram 全文检索 |
+
+中文全文检索：
+
+```sql
+DEFINE ANALYZER material_zh
+  TOKENIZERS class
+  FILTERS lowercase, ngram(1,8);
+```
+
+单条查询词建议 2–8 个汉字；更长的概念拆成多个短词。
+
+## 7. fancy-material 命令
+
+```text
+/fancy-material                 生成全部素材类型，按 kind 顺序，一个类型写完再下一个
+/fancy-material 地名            只生成地名类，其它规则仍然有效
+/fancy-material 人物            生成人物相关 kind
+/fancy-material 颜色            只生成颜色词
+/fancy-material import <文件>   导入 JSONL
+/fancy-material init            创建/补齐 schema、索引和查询脚本
+/fancy-material remove          删除整个素材库（需确认）
+/fancy-material prompt          展示全类型提示词
+/fancy-material export          导出 <工作区>/素材库.md
+```
+
+如果 `扫榜结果` 下有多份 `topic_decision_*.md`，不带参数运行时会先弹窗，
+让你选择本次使用哪一份；插件只读取选中的那份文件里的「选题方向」，不会合并
+多个报告。只有一份时自动使用；没有时回退到番茄扫榜题材。
+
+带参数运行（例如 `/fancy-material 地名`）不弹窗，沿用最新的
+`topic_decision` 文件。
+
+不带参数时，插件会覆盖全部 54 个 kind：
+
+```text
+每次运行，每个 kind 新增 50 条。
+一个 kind 写满本次的 50 条，再进入下一个 kind。
+```
+
+带参数时，只处理指定类型：
+
+```text
+/fancy-material 地名     只让 place_name 新增 50 条
+/fancy-material 物品     依次让 item_* 各新增 50 条
+```
+
+执行方式：
+
+```text
+每个 kind 拆成多个批次，每批最多 10 条。
+插件发送一批 → LLM 写一个批次文件 → 校验 → 追加导入 → 插件自动发下一批。
+一个 kind 完成本次 50 条后，插件自动切换到下一个 kind。
+```
+
+这不是“数据库里每个 kind 最多 50 条”。50 是**每次运行的新增量**：
+
+```text
+第 1 次运行 /fancy-material → 每个 kind 新增 50 条
+第 2 次运行 /fancy-material → 每个 kind 再新增 50 条
+两次运行后 → 每个 kind 累计 100 条
+```
+
+已有素材只用于去重，不会让本次配额减少。
+
+运行中会写入进度文件：
+
+```text
+<工作区>/.tmp/fancy_material_<时间戳>/progress.json
+<工作区>/.tmp/fancy_material_<时间戳>/batches.jsonl
+<工作区>/.tmp/fancy_material_<时间戳>/<序号>_<kind>_<批次>.jsonl
+```
+
+`progress.json` 记录本次运行每个 kind 的 db_existing / generated / target / status，
+`batches.jsonl` 逐批记录新增数量，便于核对。
+
+调试或试跑时，可以在启动 OpenCode 前设置环境变量覆盖默认值，避免一次生成太多：
+
+```bash
+export FANCY_MATERIAL_TARGET_PER_KIND=10
+export FANCY_MATERIAL_BATCH_SIZE=5
+```
+
+中断后再次运行 `/fancy-material`：
+
+```text
+已经导入的素材保留；
+再次运行会开始新一轮 50 条配额；
+不会从上次中断的位置抵扣本次配额。
+```
+
+也就是说，中断发生在某个 kind 的第 3 批，本次已经导入 30 条；再次运行仍会为这个
+kind 再生成 50 条，最终这个 kind 是 80 条。这是“每次运行新增 50 条”的直接结果。
+
+`init` 只补齐 schema/索引，不会清空合法素材；`source=builtin` 且已下线的 kind 会被清理。`remove` 会先弹窗确认，再执行
+`REMOVE DATABASE material_library`，删除后可用 `/fancy-material init` 重建。
+
+生成器与校验：
+
+- 可以直接写 JSONL，也可以使用 Python/Node 生成器；
+- 生成器放在 `<工作区>/.tmp/`，输出必须是目标 JSONL；
+- 生成后运行 `.fancy-tools/fancy-material/validate.js`；
+- 插件最终还会再校验一次，并按 `kind + name` 去重追加导入。
+
+```bash
+node <工作区>/.fancy-tools/fancy-material/validate.js <目标.jsonl>
+```
+
+校验失败会输出行号和原因；通过后插件再做最终校验并追加导入。
+
+## 8. 质量要求摘要
+
+完整规则在 `prompt.md`，核心是：
+
+- 具体优先，不写空泛形容词。
+- 描写词必须有具体参照物、感官、情绪或处境。
+- 直接废弃“火红、淡红、深红、蓝蓝的、雪白、耀眼、璀璨、神秘、强大”。
+- 名字不要“张三、李四、林婉儿”这种大路货。
+- 命名至少要有具体锚点：数字、地名、材质、动作、职业、年代、禁忌、功能或反差。
+- 直接废弃“复原眼、章眼、旧仓单、神秘剑、黑色长刀”这类功能标签或形容词+通用名词。
+- 可以入库的命名示例：“回魂秤、缺页仓单、三号柜的铜牌、二十四帧瞳、缝尸针”。
+- 能力机制、代价、限制、反制分开成条。
+- 场景要有声音、气味、触感、光线、物件。
+- 每条素材必须能独立复用。
+
+## 9. 兼容性
+
+- 已在 SurrealDB 2.3.10 上验证。
+- 2.3 使用 `SEARCH ANALYZER`；2.2 及以下需要把全文索引改成 `FULLTEXT` 语法。
+- Node.js >= 18。
+- `import.js` 直接导入依赖 `surrealdb` npm 包；只用 `--to-surql` 时不需要连数据库。