# Extractor

> 角色、场景和道具提取的规范与方法

- Skill: `chatfire-ai/extractor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chatfire-ai/extractor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chatfire-ai/extractor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chatfire-ai (https://skillmd.com/u/chatfire-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chatfire-ai/extractor

---


# 角色、场景与道具提取指南

## 角色提取规范

提取的角色字段（与 `save_dedup_characters` 工具参数一一对应）：
- **name**（必填）：角色全名
- **role**：角色定位，主角/配角/龙套
- **appearance**：样貌描写（300-500字）——性别、年龄感、五官、体态、气质。**角色的性格特点不要单独输出，要转化为外在气质与神态融入样貌描写**（例如"性格冷峻"应写为"眼神冷峻、表情克制、少有笑意"）
- **styling**：妆造——发型、服装、妆面、配饰等
- **description**：背景故事和人物关系（可选补充）

## 场景提取规范

提取的场景字段（与 `save_dedup_scenes` 工具参数一一对应）：
- **location**（必填）：具体场所名称
- **time**：时间段（如 白天/黄昏/深夜），同地点不同时段视为新场景
- **prompt**：场景描述——空间、陈设、年代质感、关键视觉元素（纯背景，不含人物）
- **lighting**：场景光影——光源、色调、明暗、氛围

## 道具提取规范

**核心原则：宁可少提，不要多提。** 道具是用来生成白底单品图、供视频特写引用的高成本资产，只有剧情关键道具才值得提取。一集通常 **0-3 个**关键道具，超过 3 个时按剧情重要性排序只保留前 3 个。

必须**同时满足**以下两条，缺一不可：
1. **直接推动剧情**：该物品的出现、交接、损坏或发现会引发情节转折（如凶器、信物、关键文件、定情礼物、关键证据）。
2. **值得单独生成图片**：后续分镜会给它特写镜头或反复出现，需要固定外观。

**判定三问**（对每个候选道具自问自答，任一答"否"即放弃）：
- ① 删掉它剧情是否依然成立？→ 成立则**不提取**（它只是道具式背景板）
- ② 它只是角色随手使用的日常物品吗（手机、筷子、水杯、香烟、雨伞）？→ 是则**不提取**
- ③ 它是场景陈设的一部分吗（桌椅、灯具、门窗、挂画、餐具）？→ 是则**不提取**（这些属于场景描述）

**不算道具的典型**：随手使用但不影响剧情走向的普通物品；场景陈设与家具；只被提及一次且再无下文的物品；角色的常规穿戴（归入角色妆造）。

如果没有符合条件的道具，**不要强行提取**，调用 `save_dedup_props` 时传空数组即可。

提取的道具字段（与 `save_dedup_props` 工具参数一一对应）：
- **name**（必填）：道具名
- **type**：类型——日常/武器/交通/装饰/文件等
- **description**：物品外貌——只描写物品本身的物理外观（材质、颜色、形状、大小、新旧程度、磨损痕迹等），不要写剧情用途，不要涉及与角色或其他事物的关联

道具**不需要输出图片提示词**——道具的最终提示词由提示词生成 Agent 在生图前专门生成（白底单品规范）。

## 使用步骤

1. 调用 `read_script_for_extraction` 读取当前集剧本
2. 调用 `read_existing_characters` 查看项目已有角色和当前集已关联角色
3. 调用 `read_existing_scenes` 查看项目已有场景和当前集已关联场景
4. 调用 `read_existing_props` 查看项目已有道具和当前集已关联道具
5. 只提取当前集真实涉及的角色、场景和道具
6. 调用 `save_dedup_characters` 保存角色并自动关联到当前集
7. 调用 `save_dedup_scenes` 保存场景并自动关联到当前集
8. 调用 `save_dedup_props` 保存道具并自动关联到当前集

## 当前集规则

- 目标是补齐"当前集"需要的角色、场景和道具，不是重扫整个项目
- 若已在项目中存在但当前集未关联，仍应复用并关联到当前集
- 去重规则：角色/道具按名称精确匹配，场景按【地点+时间段】精确匹配，命中的优先复用，不要重复创建
- 近名去重：名称带括号定位或别名时按括号前主体比较（如「林小雨（主角）」与「林小雨」视为同一角色/道具，复用已有）；read_existing_characters / read_existing_props 返回的 normalized_name 即归一化后的名字，场景的 normalized_location 同理，据此判断即可