# 快速查阅工具使用示例

本文档提供实际使用场景和示例。

## 前提条件

确保你的小说项目包含 `现有信息/` 目录，结构如下：

```
your-novel/
├── 现有信息/
│   ├── 角色/
│   │   ├── 张三.md
│   │   └── 李四.md
│   ├── 物品/
│   │   └── 玄天剑.md
│   ├── 场景/
│   │   └── 云霄宗.md
│   └── 事件/
│       └── 宗门大比.md
```

## 使用场景

### 场景 1: 开始写新章节前，快速浏览所有角色状态

**目标**: 了解当前有哪些角色，他们的基本信息和状态。

**命令**:
```bash
cd your-novel
uv run ./.claude/skills/quick-lookup/scripts/list_info.py 角色 --brief
```

**预期输出**:
```
找到 2 个角色:

=== 角色: 张三 ===
name: 张三
status: alive
role: 主角
first_appearance: 1
last_updated: 5
age: 25
gender: 男
cultivation_level: 筑基期
faction: 云霄宗

=== 角色: 李四 ===
name: 李四
status: alive
role: 配角
first_appearance: 2
last_updated: 5
age: 30
gender: 男
cultivation_level: 金丹期
faction: 云霄宗
relationships:
  - target: 张三
    type: 师徒
    note: 张三的师父
```

**适用时机**:
- 开始写新章节前
- 检查所有角色的生存状态
- 快速回顾角色的基本设定

---

### 场景 2: 查看某个角色的完整信息

**目标**: 深入了解某个角色的所有细节，包括外貌、性格、背景等。

**命令**:
```bash
uv run ./.claude/skills/quick-lookup/scripts/show_detail.py 角色 张三
```

**预期输出**:
```
================================================================================
角色: 张三
================================================================================
文件: 现有信息/角色/张三.md
================================================================================

---
name: 张三
status: alive
role: 主角
first_appearance: 1
last_updated: 5
age: 25
gender: 男
cultivation_level: 筑基期
faction: 云霄宗
relationships:
  - target: 李四
    type: 师徒
    note: 师父
---

## 外貌特征
身高一米八，体型修长而结实。剑眉星目，面容清秀，留着一头乌黑长发...

## 性格特点
性格沉稳，做事谨慎。虽然年轻，但遇事冷静，善于思考...

## 背景故事
出身平凡，自幼父母双亡...

## 重要技能/能力
- 玄天心法（天阶功法）
- 御剑术
- 灵识探测

## 发展轨迹
- 第1章: 初入云霄宗，成为外门弟子
- 第3章: 在藏经阁获得玄天心法
- 第5章: 突破至筑基期，获得玄天剑

================================================================================
```

**适用时机**:
- 需要详细了解某个角色
- 写到该角色的重要情节前
- 检查角色设定的一致性

---

### 场景 3: 检查某件物品的归属

**目标**: 确认玄天剑现在在谁手里，以及它的历史。

**命令**:
```bash
uv run ./.claude/skills/quick-lookup/scripts/show_detail.py 物品 玄天剑
```

**预期输出**:
```
================================================================================
物品: 玄天剑
================================================================================
文件: 现有信息/物品/玄天剑.md
================================================================================

---
name: 玄天剑
type: 武器
grade: 天阶下品
owner: 张三
status: 使用中
first_appearance: 5
last_updated: 5
---

## 外观描述
剑身三尺，通体呈深蓝色，剑身上刻有古老符文，散发着淡淡的灵气...

## 能力效果
- 锋利无比，可斩金断玉
- 内含剑灵，可与持有者心神相通
- 施展御剑术时威力倍增

## 来历
相传为上古剑仙所铸，流传数千年...

## 流转记录
- 第5章: 张三在古墓中获得
- 第5章: 认主成功，激活第一层封印

================================================================================
```

**适用时机**:
- 写到物品相关情节前
- 确认物品当前状态和归属
- 回顾物品的历史和流转

---

### 场景 4: 搜索相关信息

**目标**: 找出所有提到"云霄宗"的信息。

**命令**:
```bash
uv run ./.claude/skills/quick-lookup/scripts/search_info.py 云霄宗
```

**预期输出**:
```
搜索关键词: 云霄宗

[角色] 张三
文件: 现有信息/角色/张三.md

  匹配 1:
    status: alive
    faction: >>>云霄宗<<<

  匹配 2:
    - 第1章: 初入>>>云霄宗<<<，成为外门弟子

--------------------------------------------------------------------------------

[角色] 李四
文件: 现有信息/角色/李四.md

  匹配 1:
    faction: >>>云霄宗<<<

--------------------------------------------------------------------------------

[场景] 云霄宗
文件: 现有信息/场景/云霄宗.md

  匹配 1:
    ---
    name: >>>云霄宗<<<
    type: 门派

  匹配 2:
    ## 地理位置
    >>>云霄宗<<<位于东荒云霄山脉主峰...

  匹配 3:
    ## 环境特征
    >>>云霄宗<<<占地数百里...

  ... 还有 5 个匹配

--------------------------------------------------------------------------------

[事件] 宗门大比
文件: 现有信息/事件/宗门大比.md

  匹配 1:
    >>>云霄宗<<<每年举行一次宗门大比...

--------------------------------------------------------------------------------

总计找到 12 个匹配结果
```

**适用时机**:
- 需要了解某个概念的全局信息
- 检查设定的一致性
- 寻找相关的角色、物品、场景、事件

---

### 场景 5: 列出所有物品的完整信息

**目标**: 查看所有物品的详细描述。

**命令**:
```bash
uv run ./.claude/skills/quick-lookup/scripts/list_info.py 物品
```

**预期输出**:
```
找到 1 个物品:

================================================================================
物品: 玄天剑
================================================================================
---
name: 玄天剑
type: 武器
grade: 天阶下品
owner: 张三
status: 使用中
first_appearance: 5
last_updated: 5
---

## 外观描述
剑身三尺，通体呈深蓝色...

[完整内容]

```

**适用时机**:
- 需要全面了解所有物品
- 整理和回顾物品设定
- 检查物品之间的等级平衡

---

## 在 Claude Code 中使用

当你在 Claude Code 中与助手对话时，助手可以使用 Bash 工具来执行这些脚本：

**示例对话 1**:
```
用户: 帮我看看所有角色的当前状态

助手: 好的，让我列出所有角色的简洁信息。

[执行命令]
uv run ./.claude/skills/quick-lookup/scripts/list_info.py 角色 --brief

根据输出，当前有 2 个角色：
1. 张三 - 筑基期，云霄宗，主角，存活
2. 李四 - 金丹期，云霄宗，配角，存活
```

**示例对话 2**:
```
用户: 玄天剑现在在谁手里？

助手: 让我查看玄天剑的详细信息。

[执行命令]
uv run ./.claude/skills/quick-lookup/scripts/show_detail.py 物品 玄天剑

根据信息，玄天剑当前持有者是张三，状态为使用中，最后更新在第5章。
流转记录显示：
- 第5章: 张三在古墓中获得
- 第5章: 认主成功，激活第一层封印
```

**示例对话 3**:
```
用户: 我想写云霄宗的相关情节，之前写过什么相关内容？

助手: 让我搜索所有包含"云霄宗"的信息。

[执行命令]
uv run ./.claude/skills/quick-lookup/scripts/search_info.py 云霄宗

找到以下相关内容：
- 角色: 张三和李四都属于云霄宗
- 场景: 云霄宗的详细场景描述
- 事件: 宗门大比等相关事件

让我为您详细列出这些信息...
```

## 常见问题

### Q: 脚本执行失败，提示找不到目录

**A**: 确保：
1. 当前工作目录包含 `现有信息/` 文件夹
2. 使用 `cd` 命令切换到你的小说项目目录
3. 检查目录名是否正确（中文名称）

### Q: 搜索结果太多，如何过滤？

**A**: 使用更具体的关键词。例如：
- 不要搜索"宗"，而是搜索"云霄宗"
- 不要搜索"剑"，而是搜索"玄天剑"

### Q: 能否同时列出多个类型的信息？

**A**: 目前不支持。需要分别执行多次命令：
```bash
uv run list_info.py 角色 --brief
uv run list_info.py 物品 --brief
uv run list_info.py 场景 --brief
uv run list_info.py 事件 --brief
```

### Q: 如何在不同的项目中使用？

**A**: 只需切换到对应的项目目录即可：
```bash
cd /path/to/project-A
uv run ./.claude/skills/quick-lookup/scripts/list_info.py 角色 --brief

cd /path/to/project-B
uv run ./.claude/skills/quick-lookup/scripts/list_info.py 角色 --brief
```

## 进阶用法

### 结合其他命令使用

**统计角色数量**:
```bash
uv run list_info.py 角色 --brief | grep "=== 角色:" | wc -l
```

**查找所有已死亡的角色**:
```bash
uv run list_info.py 角色 --brief | grep -A 10 "=== 角色:" | grep "status: dead"
```

**导出所有角色名称**:
```bash
uv run list_info.py 角色 --brief | grep "name:" | cut -d: -f2 | sort
```

---

## 反馈与改进

如果你有任何建议或遇到问题，请在项目中提出 Issue！
