Metadata-Version: 2.4
Name: chinese-finder
Version: 0.1.3
Summary: A powerful CLI and library tool for detecting Chinese names in text and Excel files
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: chinese,name,detection,cli,excel,nlp,typer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.26.3
Requires-Dist: pandas>=3.0.3
Requires-Dist: openpyxl>=3.1.5

# Chinese Finder

**A powerful CLI and library tool for detecting Chinese names in text and Excel files**

Chinese Finder 是一个用于检测文本和 Excel 文件中中文姓名的强大工具。它支持命令行界面和 Python 库两种使用方式,采用可扩展的策略模式架构,可以轻松添加新的检测策略。

## 功能特性

- ✅ **双模式支持**: 同时提供 CLI 命令行工具和 Python 库接口
- 🔌 **可扩展架构**: 基于策略模式的插件式架构,轻松添加新策略
- 📊 **多格式支持**: 支持 TXT 和 Excel 文件输入,支持 Excel/JSON/CSV 输出
- 🎯 **多策略检测**: 
  - 姓氏列表匹配策略(基于 350+ 常见中文姓氏)
  - 中文字符检测策略(基于 Unicode 范围)
  - 混合格式姓名检测策略(处理含学位/资质后缀的英文名格式)
  - 支持自定义策略扩展
- ⚙️ **灵活配置**: 支持策略组合模式(ANY/ALL),可选择特定策略
- 🚀 **批量处理**: 支持单文件和批量文件处理
- 📝 **详细文档**: 完整的 API 文档和使用示例

## 安装和环境配置

### 系统要求

- Python 3.11 或更高版本
- 支持的操作系统: macOS, Linux, Windows

### 使用 pip 安装

```bash
pip install chinese-finder
```

## 使用示例和代码片段

### CLI 使用示例

#### 1. 处理单个文件

```bash
# 处理 Excel 文件(需要指定列名)
chinese process data.xlsx --column name

# 处理文本文件
chinese process names.txt

# 指定输出格式
chinese process data.xlsx -c name -o json

# 详细输出模式
chinese process data.xlsx -c name -v
```

#### 2. 批量处理文件

```bash
# 批量处理多个 Excel 文件
chinese process-batch data1.xlsx data2.xlsx data3.xlsx -c name

# 批量处理混合文件类型
chinese process-batch names.txt data.xlsx -c name -o csv

# 指定输出目录
chinese process-batch *.xlsx -c name -d ./output
```

#### 3. 使用特定策略

```bash
# 仅使用姓氏匹配策略
chinese process data.xlsx -c name -s family_name

# 使用多个策略
chinese process data.xlsx -c name -s family_name -s chinese_char

# 使用混合格式策略(处理含学位/资质的姓名)
chinese process data.xlsx -c name -s mixed_format

# 查看所有可用策略
chinese list-strategies
```

#### 4. 策略组合模式

```bash
# ANY 模式:任一策略匹配即认为包含中文姓名(默认)
chinese process data.xlsx -c name -m any

# ALL 模式:所有策略都匹配才认为包含中文姓名
chinese process data.xlsx -c name -m all
```

### Python API 使用示例

#### 1. 基础文本检测

```python
from chinese_finder import ChineseFinderProcessor

# 创建处理器(使用所有策略)
processor = ChineseFinderProcessor()

# 使用混合格式策略处理含学位/资质的姓名
processor_mixed = ChineseFinderProcessor(strategies=['mixed_format'])
print(processor_mixed.process_text("Zhexiang Sheng, FRM"))  # True

# 检测单个文本
result = processor.process_text("wang john")
print(result)  # True

result = processor.process_text("alice smith")
print(result)  # False
```

#### 2. 批量文本处理

```python
from chinese_finder import ChineseFinderProcessor

processor = ChineseFinderProcessor()

texts = ["wang john", "alice smith", "张三", "hello world"]
results = processor.process_texts(texts)

# 使用 mixed_format 策略处理混合格式姓名
mixed_proc = ChineseFinderProcessor(strategies=['mixed_format'])
mixed_names = ["Zhexiang Sheng, FRM", "Yongshuai (Michael) Chen, PhD", "John Smith"]
print(mixed_proc.process_texts(mixed_names))  # [True, True, False]

for text, result in zip(texts, results):
    status = "✓" if result else "✗"
    print(f"{status} {text}")
```

#### 3. 处理文件

```python
from chinese_finder import ChineseFinderProcessor

processor = ChineseFinderProcessor()

# 处理 Excel 文件
output_path = processor.process_excel(
    file_path="data.xlsx",
    column="name",
    output_format="excel"  # 或 "json", "csv"
)
print(f"Output saved to: {output_path}")

# 处理文本文件
output_path = processor.process_txt(
    file_path="names.txt",
    output_format="json"
)
```

#### 4. 使用特定策略

```python
from chinese_finder import ChineseFinderProcessor

# 仅使用姓氏匹配策略
processor = ChineseFinderProcessor(
    strategies=['family_name'],
    mode='any'
)

# 使用多个策略, ALL 模式
processor = ChineseFinderProcessor(
    strategies=['family_name', 'chinese_char'],
    mode='all'
)

# 使用混合格式策略(处理含学位/资质的姓名)
processor = ChineseFinderProcessor(strategies=['mixed_format'])
result = processor.process_text("Zhexiang Sheng, FRM")
print(result)  # True
```

#### 5. 自定义策略

```python
from chinese_finder import DetectionStrategy, register_strategy, ChineseFinderProcessor

# 创建自定义策略
@register_strategy('my_custom_strategy')
class MyCustomStrategy(DetectionStrategy):
    @property
    def name(self) -> str:
        return 'my_custom_strategy'
    
    def detect(self, text: str) -> bool:
        # 实现你的检测逻辑
        return "custom_pattern" in text.lower()

# 使用自定义策略
processor = ChineseFinderProcessor(
    strategies=['my_custom_strategy'],
    mode='any'
)

result = processor.process_text("custom_pattern detected")
print(result)  # True
```

## 策略详细说明

### `chinese process` 命令详解

#### 基本用法

```bash
chinese process data.xlsx --column name
```

#### 功能说明

该命令用于处理单个文件,自动检测其中文姓名并生成输出文件。

#### 参数含义

| 参数 | 简写 | 必需 | 说明 | 示例 |
|------|------|------|------|------|
| `file_path` | - | ✅ | 输入文件路径 | `data.xlsx` |
| `--column` | `-c` | Excel必需 | 要分析的列名 | `name` |
| `--strategies` | `-s` | ❌ | 指定策略(默认全部) | `family_name` |
| `--mode` | `-m` | ❌ | 策略组合模式(默认any) | `any`/`all` |
| `--output-format` | `-o` | ❌ | 输出格式 | `excel`/`json`/`csv` |
| `--output-dir` | `-d` | ❌ | 输出目录 | `./output` |
| `--verbose` | `-v` | ❌ | 详细输出模式 | - |

#### 默认行为

当不指定 `--strategies` 参数时,命令会**自动加载所有已注册的策略**:
- **策略数量**: 3 种
- **策略类型**: `family_name` + `chinese_char` + `mixed_format`
- **组合模式**: `any`(任一策略匹配即认为包含中文姓名)

---

### 默认策略详解

#### 策略 1:`family_name`(姓氏列表匹配)

##### 工作原理

通过匹配预定义的中文姓氏列表来识别潜在的中文姓名。

##### 检测逻辑

1. **加载姓氏库**: 从 `chinese_finder/data/family_names.txt` 读取 350+ 个常见中文姓氏
2. **分词处理**: 将输入文本按空格分割成多个 token
3. **大小写不敏感匹配**: 每个 token 转为小写后与姓氏库对比
4. **短路返回**: 发现任一匹配立即返回 `True`

##### 算法流程

```
输入文本: "wang john"
    ↓
分词: ["wang", "john"]
    ↓
遍历检查:
  - "wang".lower() = "wang" → 在姓氏库中? ✅ YES
    ↓
返回: True (立即结束)
```

##### 代码实现

```python
# family_name.py 核心逻辑
def detect(self, text: str) -> bool:
    if not isinstance(text, str):
        return False
    
    # 按空格分词
    tokens = text.split()
    
    # 检查每个 token 是否在姓氏库中
    for token in tokens:
        if token.lower() in self.family_names:
            return True  # 发现匹配,立即返回
    
    return False  # 无匹配
```

##### 匹配示例

| 输入文本 | 分词结果 | 匹配姓氏 | 结果 |
|---------|---------|---------|------|
| `"wang john"` | `["wang", "john"]` | wang ✅ | `True` |
| `"Zhang Wei"` | `["Zhang", "Wei"]` | zhang ✅ | `True` |
| `"alice smith"` | `["alice", "smith"]` | 无 ❌ | `False` |
| `"李明 li"` | `["李明", "li"]` | li ✅ | `True` |

##### 数据源

内置姓氏库位于 `chinese_finder/data/family_names.txt`,包含:
- 常见单姓: 王、李、张、刘、陈等
- 复姓: 欧阳、司马、上官等
- 总计: **350+ 个中文姓氏**

---

#### 策略 2:`chinese_char`(中文字符检测)

##### 工作原理

通过正则表达式检测文本中是否包含中文字符(Unicode 范围)。

##### 检测逻辑

1. **正则匹配**: 使用编译好的正则表达式 `[一-鿿]`
2. **Unicode 范围**: `U+4E00` 到 `U+9FFF`(覆盖常用汉字)
3. **搜索匹配**: 在文本中搜索是否存在任何中文字符
4. **布尔返回**: 找到返回 `True`,否则返回 `False`

##### 算法流程

```
输入文本: "张三"
    ↓
正则搜索: [\u4e00-\u9fff]
    ↓
发现中文字符: "张" (U+5F20) ✅
    ↓
返回: True
```

##### 代码实现

```python
# chinese_char.py 核心逻辑
import re

class ChineseCharStrategy(DetectionStrategy):
    # 预编译正则表达式(提高性能)
    _chinese_pattern = re.compile(r'[\u4e00-\u9fff]')
    
    def detect(self, text: str) -> bool:
        if not isinstance(text, str):
            return False
        
        # 搜索中文字符
        return bool(self._chinese_pattern.search(text))
```

##### 匹配示例

| 输入文本 | 包含中文 | 匹配字符 | 结果 |
|---------|---------|---------|------|
| `"张三"` | ✅ | 张、三 | `True` |
| `"hello 你好"` | ✅ | 你、好 | `True` |
| `"wang john"` | ❌ | 无 | `False` |
| `"李明 li"` | ✅ | 李、明 | `True` |
| `"Alice Smith"` | ❌ | 无 | `False` |

##### Unicode 范围说明

- **范围**: `U+4E00` - `U+9FFF`
- **覆盖**: CJK 统一表意文字(常用汉字)
- **字符数**: 约 20,902 个汉字
- **不包含**: 拼音、日文假名、韩文字母

#### 策略 3: `mixed_format`（混合格式姓名检测）

##### 工作原理

通过多步骤文本清洗与拼音启发式评分，从包含英文名、学位、专业资格认证等混合格式字符串中识别中文姓名。

##### 处理流水线

1. **移除括号别名**：去除 `(Michael)` 等英文名映射，并记录括号存在作为强信号
2. **逗号分割 + 后缀过滤**：丢弃 70+ 种已知学位/认证后缀（PhD、MD、FRM、CFA 等）
3. **拼音评分**：对剩余 token 进行拼音特征打分，判断是否为中文拼音姓名

##### 支持格式

| 输入格式 | 示例 | 说明 |
|---------|------|------|
| 英文名 + 专业资格 | `Zhexiang Sheng, FRM` | 过滤 FRM 后缀，识别拼音姓名 |
| 中文拼音(英文名) + 学位 | `Yongshuai (Michael) Chen, PhD` | 去除括号内容，识别拼音姓名 |
| 中文拼音 + 多学位/资质 | `Yunguo Yu, PhD, MD` | 过滤多个后缀，识别拼音姓名 |

##### 检测逻辑

1. **括号别名检测**：存在括号映射 → 强信号（通常表示中文姓名有对应英文名）
2. **名字主体提取**：过滤后缀后保留 2–4 个词
3. **拼音特征评分**：
   - 拼音二合字母（zh/ch/sh/qu/xu 等）→ 加分
   - 拼音声母首字母（b/p/m/f/d/t/n/l 等）→ 加分
   - 元音或 n 结尾（拼音音节特征）→ 加分
   - 英语辅音簇（th/ck/ght/tch 等）→ 扣分
   - 常见西方名字词表命中 → 排除误判
4. **综合判定**：
   - 有括号 + 拼音比 ≥ 0.5 → `True`
   - 无括号 + 拼音比 ≥ 0.5 且不含常见英文名 → `True`
   - 其余情况 → `False`

##### 匹配示例

| 输入文本 | 提取姓名 | 拼音比 | 结果 |
|---------|---------|--------|------|
| `"Zhexiang Sheng, FRM"` | Zhexiang Sheng | 1.0 | `True` |
| `"Yongshuai (Michael) Chen, PhD"` | Yongshuai Chen | 1.0 | `True` |
| `"Yunguo Yu, PhD, MD"` | Yunguo Yu | 1.0 | `True` |
| `"John Smith, PhD"` | John Smith | 0.0 | `False` |
| `"Mary Johnson, CPA"` | Mary Johnson | 0.0 | `False` |

##### 参数配置

该策略无需特殊初始化参数，直接通过策略名称调用即可：

```python
processor = ChineseFinderProcessor(strategies=['mixed_format'])
```

##### 使用建议

- **适用数据**：包含英文名、学位、专业资格认证的混合格式姓名数据
- **不适用**：纯中文字符姓名（请使用 `chinese_char` 策略）
- **默认不启用**：该策略不在默认策略组合中，需显式指定 `-s mixed_format` 或在 `strategies` 参数中列出

---

### 策略组合机制

#### ANY 模式(默认)

**判定规则**: 任一策略返回 `True` → 最终结果 `True`

```python
# processor.py 核心逻辑
results = [strategy.detect(text) for strategy in self.strategies]

if self.mode == 'any':
    return any(results)  # 任一为 True 即返回 True
```

**实际示例**:

| 输入文本 | family_name | chinese_char | ANY 结果 | 说明 |
|---------|-------------|--------------|---------|------|
| `"wang john"` | ✅ True | ❌ False | ✅ **True** | 姓氏匹配成功 |
| `"张三"` | ❌ False | ✅ True | ✅ **True** | 中文字符匹配成功 |
| `"alice smith"` | ❌ False | ❌ False | ❌ **False** | 均无匹配 |
| `"张伟 wang"` | ✅ True | ✅ True | ✅ **True** | 两者均匹配 |

#### ALL 模式

**判定规则**: 所有策略都返回 `True` → 最终结果 `True`

```python
else:  # mode == 'all'
    return all(results)  # 全部为 True 才返回 True
```

**实际示例**:

| 输入文本 | family_name | chinese_char | ALL 结果 | 说明 |
|---------|-------------|--------------|---------|------|
| `"wang john"` | ✅ True | ❌ False | ❌ **False** | chinese_char 失败 |
| `"张三"` | ❌ False | ✅ True | ❌ **False** | family_name 失败 |
| `"张伟"` | ✅ True | ✅ True | ✅ **True** | 两者均成功 |
| `"alice smith"` | ❌ False | ❌ False | ❌ **False** | 均失败 |

#### 使用场景建议

| 模式 | 适用场景 | 特点 |
|------|---------|------|
| **ANY** | 拼音姓名、中文姓名混合数据 | 宽松匹配,召回率高 |
| **ALL** | 纯中文姓名数据,需要高精确度 | 严格匹配,精确率高 |

---

### 完整处理流程示例

#### Excel 文件处理

```bash
# 执行命令
chinese process data.xlsx --column name -v
```

**处理流程**:

```
1. 读取 Excel 文件
   ↓
2. 验证列名 "name" 是否存在
   ↓
3. 初始化处理器(默认加载 2 个策略,ANY 模式)
   ↓
4. 遍历 "name" 列的每一行:
   ├── 对每个值调用 process_text()
   │   ├── family_name.detect(text)
   │   ├── chinese_char.detect(text)
   │   └── 组合结果(ANY 模式)
   ├── 如果检测到中文姓名 → 保留原值
   └── 否则 → 置为空字符串
   ↓
5. 添加 "Chinese" 列到 DataFrame
   ↓
6. 保存输出文件: data_cn.xlsx
```

**预期输出** (data_cn.xlsx):

| name | Chinese |
|------|---------|
| wang john | wang john |
| alice smith |  |
| 张三 | 张三 |
| hello world |  |
| 李明 | 李明 |

#### Python API 调用

```python
from chinese_finder import ChineseFinderProcessor

# 创建处理器(使用默认策略)
processor = ChineseFinderProcessor()

# 测试不同文本
test_texts = [
    "wang john",        # family_name ✅, chinese_char ❌ → ANY: True
    "alice smith",      # family_name ❌, chinese_char ❌ → ANY: False
    "张三",              # family_name ❌, chinese_char ✅ → ANY: True
    "张伟 wang",        # family_name ✅, chinese_char ✅ → ANY: True
]

for text in test_texts:
    result = processor.process_text(text)
    status = "✓" if result else "✗"
    print(f"{status} {text}")
```

**预期输出**:

```
✓ wang john
✗ alice smith
✓ 张三
✓ 张伟 wang
```

---

## API 接口说明

### ChineseFinderProcessor

核心处理器类,负责协调多个检测策略并处理文件。

#### 初始化参数

```python
ChineseFinderProcessor(
    strategies: Optional[List[str]] = None,  # 策略名称列表,None 表示使用所有策略
    mode: str = 'any',                        # 策略组合模式: 'any' 或 'all'
    **strategy_kwargs                         # 传递给策略构造函数的额外参数
)
```

#### 主要方法

##### `process_text(text: str) -> bool`

处理单个文本字符串。

**参数:**
- `text`: 要分析的文本字符串

**返回:**
- `bool`: 根据配置的模式返回检测结果

**示例:**
```python
processor = ChineseFinderProcessor()
result = processor.process_text("wang john")
```

##### `process_texts(texts: List[str]) -> List[bool]`

批量处理多个文本字符串。

**参数:**
- `texts`: 文本字符串列表

**返回:**
- `List[bool]`: 检测结果列表

**示例:**
```python
results = processor.process_texts(["wang", "john", "zhang"])
```

##### `process_excel(file_path: str, column: str, output_format: str = 'excel', output_dir: str = None) -> str`

处理 Excel 文件。

**参数:**
- `file_path`: 输入 Excel 文件路径
- `column`: 要分析的列名
- `output_format`: 输出格式('excel', 'json', 'csv')
- `output_dir`: 输出目录(可选)

**返回:**
- `str`: 输出文件路径

**示例:**
```python
output_path = processor.process_excel("data.xlsx", column="name", output_format="json")
```

##### `process_txt(file_path: str, output_format: str = 'json', output_dir: str = None) -> str`

处理文本文件。

**参数:**
- `file_path`: 输入文本文件路径
- `output_format`: 输出格式('json', 'csv', 'excel', 'txt')
- `output_dir`: 输出目录(可选)

**返回:**
- `str`: 输出文件路径

**示例:**
```python
output_path = processor.process_txt("names.txt", output_format="json")
```

##### `process_file(file_path: str, column: str = None, output_format: str = None, output_dir: str = None) -> str`

自动检测文件类型并处理。

**参数:**
- `file_path`: 输入文件路径
- `column`: 列名(Excel 文件必需)
- `output_format`: 输出格式(可选)
- `output_dir`: 输出目录(可选)

**返回:**
- `str`: 输出文件路径

**示例:**
```python
# 自动检测文件类型
output_path = processor.process_file("data.xlsx", column="name")
```

### DetectionStrategy

策略抽象基类,所有检测策略必须继承此类。

#### 必须实现的属性

- `name: str`: 策略的唯一名称

#### 必须实现的方法

- `detect(text: str) -> bool`: 检测单个文本

#### 可选重写的方法

- `detect_batch(texts: List[str]) -> List[bool]`: 批量检测(默认实现为循环调用 detect)

### register_strategy 装饰器

用于自动注册自定义策略。

**用法:**
```python
@register_strategy('strategy_name')
class MyStrategy(DetectionStrategy):
    # 实现...
```

### StrategyRegistry

策略注册表,用于管理所有可用的策略。

#### 主要方法

- `register(name: str, strategy_class: Type[DetectionStrategy])`: 注册策略
- `get_strategy(name: str, **kwargs) -> DetectionStrategy`: 获取策略实例
- `list_strategies() -> List[str]`: 列出所有策略名称
- `has_strategy(name: str) -> bool`: 检查策略是否存在

### 策略组合模式

- **`any` 模式**: 只要任一策略检测到中文姓名,就认为包含中文姓名
- **`all` 模式**: 只有所有策略都检测到中文姓名,才认为包含中文姓名

## 依赖项清单

### 运行时依赖

- **typer** (>=0.26.3): CLI 框架
- **pandas** (>=3.0.3): 数据处理和 Excel 文件操作
- **openpyxl** (>=3.1.5): Excel 文件读写支持

### 开发依赖

- **pytest** (>=7.4.0): 测试框架
- **pytest-cov** (>=4.1.0): 测试覆盖率工具
- **black** (>=23.0.0): 代码格式化工具
- **ruff** (>=0.1.0): 快速 Python linter

### Python 版本

支持 Python 3.11, 3.12, 3.13

## 贡献指南与许可证

### 开发环境搭建

1. **Fork 和克隆仓库**
```bash
git clone https://github.com/yourusername/chinese-finder.git
cd chinese-finder
```

2. **安装 Poetry**
```bash
curl -sSL https://install.python-poetry.org | python3 -
```

3. **安装依赖**
```bash
poetry install
```

4. **激活虚拟环境**
```bash
poetry shell
```

5. **运行测试**
```bash
# 运行所有测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=chinese_finder --cov-report=html

# 查看覆盖率报告
open htmlcov/index.html  # macOS
```

### 代码规范

本项目使用 Black 和 Ruff 进行代码格式化和检查:

```bash
# 格式化代码
black chinese_finder tests examples

# 检查代码质量
ruff check chinese_finder tests examples

# 自动修复简单问题
ruff check --fix chinese_finder tests examples
```

### 添加新策略

1. 在 `chinese_finder/core/strategies/` 目录下创建新文件
2. 继承 `DetectionStrategy` 类
3. 实现 `name` 属性和 `detect` 方法
4. 使用 `@register_strategy` 装饰器注册
5. 在 `chinese_finder/core/strategies/__init__.py` 中导入(确保自动注册)
6. 编写对应的单元测试

示例:
```python
# chinese_finder/core/strategies/my_strategy.py
from ..detector import DetectionStrategy, register_strategy

@register_strategy('my_strategy')
class MyStrategy(DetectionStrategy):
    @property
    def name(self) -> str:
        return 'my_strategy'
    
    def detect(self, text: str) -> bool:
        # 实现检测逻辑
        pass
```

### Pull Request 流程

1. 创建特性分支: `git checkout -b feature/amazing-feature`
2. 提交更改: `git commit -m 'Add amazing feature'`
3. 推送到分支: `git push origin feature/amazing-feature`
4. 创建 Pull Request
5. 确保所有测试通过
6. 等待代码审查

### 测试要求

- 所有新功能必须包含单元测试
- 保持测试覆盖率在 80% 以上
- 测试应覆盖正常情况和异常情况

### 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

## 项目结构

### 目录结构

```
chinese-finder/
├── chinese_finder/              # 主包目录
│   ├── __init__.py             # 包初始化,暴露公共 API
│   ├── cli.py                  # Typer CLI 入口 (341 行)
│   ├── core/                   # 核心模块
│   │   ├── __init__.py         # 核心模块初始化
│   │   ├── detector.py         # 策略基类和注册表 (168 行)
│   │   ├── processor.py        # 文件处理引擎 (260 行)
│   │   └── strategies/         # 策略实现
│   │       ├── __init__.py     # 策略模块初始化
│   │       ├── family_name.py  # 策略1: 姓氏列表匹配 (126 行)
│   │       ├── chinese_char.py # 策略2: 中文字符检测 (63 行)
│   │       └── mixed_format.py # 策略3: 混合格式姓名检测
│   ├── utils/                  # 工具函数
│   │   ├── __init__.py         # 工具模块初始化
│   │   └── io.py               # 文件读写工具 (167 行)
│   └── data/                   # 数据文件
│       └── family_names.txt    # 内置姓氏列表 (350 个姓氏)
├── tests/                      # 测试目录
│   ├── __init__.py             # 测试模块初始化
│   ├── test_strategies.py      # 策略单元测试 (185 行)
│   ├── test_processor.py       # 处理器集成测试 (187 行)
│   └── test_cli.py             # CLI 测试 (186 行)
├── examples/                   # 使用示例
│   ├── basic_usage.py          # 基础库函数调用示例 (195 行)
│   └── custom_strategy.py      # 自定义策略示例 (253 行)
├── pyproject.toml              # Poetry 配置 (68 行)
├── README.md                   # 项目文档
└── demo.py                     # 原始文件(保留参考)
```

### 核心架构

#### 1. 策略模式架构

```
DetectionStrategy (抽象基类)
    ├── FamilyNameStrategy (姓氏匹配策略)
    ├── ChineseCharStrategy (中文字符检测策略)
    ├── MixedFormatStrategy (混合格式姓名检测策略)
    └── [可轻松添加更多策略...]

StrategyRegistry (策略注册表)
    ├── register() - 注册策略
    ├── get_strategy() - 获取策略实例
    └── list_strategies() - 列出所有策略

@register_strategy 装饰器
    └── 自动注册策略到注册表
```

#### 2. 处理器架构

```
ChineseFinderProcessor
    ├── process_text() - 单文本处理
    ├── process_texts() - 批量文本处理
    ├── process_excel() - Excel 文件处理
    ├── process_txt() - 文本文件处理
    └── process_file() - 自动检测文件类型处理
```

#### 3. CLI 命令

```
chinese
    ├── process <FILE> - 处理单个文件
    ├── process-batch <FILES...> - 批量处理
    ├── list-strategies - 列出可用策略
    └── info - 显示项目信息
```

### 关键设计特点

1. **策略模式**: 每个检测策略独立,互不影响
2. **装饰器注册**: 使用 @register_strategy 自动注册,无需手动管理
3. **依赖注入**: 处理器通过策略名称获取策略实例
4. **组合模式**: 支持 ANY/ALL 两种策略组合方式
5. **工厂模式**: StrategyRegistry 作为策略工厂
6. **开闭原则**: 对扩展开放(添加新策略),对修改封闭(不修改现有代码)

---

## 快速开始

### 1. 安装依赖

#### 方式一: 使用 Poetry (推荐)

```bash
# 安装 Poetry (如果尚未安装)
curl -sSL https://install.python-poetry.org | python3 -

# 安装项目依赖
poetry install

# 激活虚拟环境
poetry shell
```

#### 方式二: 使用 pip

```bash
# 安装依赖
pip install typer[all] pandas openpyxl

# 如果使用测试
pip install pytest pytest-cov
```

### 2. 验证安装

```bash
# 检查 Python 包
python -c "from chinese_finder import ChineseFinderProcessor; print('✓ 安装成功')"

# 检查 CLI (如果使用 Poetry)
chinese --help

# 或直接运行
python -m chinese_finder.cli --help
```

### 3. CLI 快速使用

```bash
# 查看帮助
chinese --help

# 查看可用策略
chinese list-strategies

# 处理文本文件
echo -e "wang john\nalice smith\n张三" > test_names.txt
chinese process test_names.txt

# 查看结果
cat test_names_cn.json

# 处理 Excel 文件
chinese process data.xlsx --column name

# 详细输出
chinese process data.xlsx -c name -v

# 批量处理
chinese process-batch file1.txt file2.txt file3.txt
```

### 4. Python API 快速使用

#### 基础示例

```python
from chinese_finder import ChineseFinderProcessor

# 创建处理器
processor = ChineseFinderProcessor()

# 检测文本
texts = ["wang john", "alice smith", "张三", "hello"]
for text in texts:
    result = processor.process_text(text)
    status = "✓" if result else "✗"
    print(f"{status} {text}")
```

#### 处理文件

```python
from chinese_finder import ChineseFinderProcessor

processor = ChineseFinderProcessor()

# 处理文本文件
output = processor.process_txt("names.txt", output_format="json")
print(f"结果保存到: {output}")

# 处理 Excel 文件
output = processor.process_excel("data.xlsx", column="name")
print(f"结果保存到: {output}")
```

#### 使用特定策略

```python
from chinese_finder import ChineseFinderProcessor

# 仅使用姓氏匹配
processor = ChineseFinderProcessor(strategies=['family_name'])

# 仅使用中文字符检测
processor = ChineseFinderProcessor(strategies=['chinese_char'])

# 组合策略, ALL 模式
processor = ChineseFinderProcessor(
    strategies=['family_name', 'chinese_char'],
    mode='all'
)
```

### 5. 创建自定义策略

```python
from chinese_finder import DetectionStrategy, register_strategy

@register_strategy('my_strategy')
class MyStrategy(DetectionStrategy):
    @property
    def name(self) -> str:
        return 'my_strategy'
    
    def detect(self, text: str) -> bool:
        # 你的检测逻辑
        return 'keyword' in text.lower()

# 使用自定义策略
from chinese_finder import ChineseFinderProcessor

processor = ChineseFinderProcessor(strategies=['my_strategy'])
result = processor.process_text("keyword found")
```

### 6. 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_strategies.py -v

# 生成覆盖率报告
pytest tests/ --cov=chinese_finder --cov-report=html
open htmlcov/index.html  # macOS
```

### 7. 运行示例

```bash
# 基础使用示例
python examples/basic_usage.py

# 自定义策略示例
python examples/custom_strategy.py
```

---

## 常见问题

### Q: 如何添加新的姓氏?
A: 编辑 `chinese_finder/data/family_names.txt`,每行添加一个姓氏。

### Q: 支持哪些文件格式?
A: 输入支持 TXT、Excel (.xlsx); 输出支持 Excel、JSON、CSV。

### Q: 如何查看检测结果?
A: 使用 `-v` 参数查看详细输出,或查看生成的输出文件。

### Q: ANY 和 ALL 模式有什么区别?
A: 
- **ANY**: 任一策略检测到中文姓名就认为包含
- **ALL**: 所有策略都检测到才认为包含

### Q: 如何发布到 PyPI?
A: 
```bash
poetry build
poetry publish
```

---

## 代码统计

- **总文件数**: 17 个 Python 文件
- **总代码行数**: ~2,500 行
- **测试覆盖**: 策略、处理器、CLI
- **文档**: 完整的 README 和代码注释

---

## 免责声明

本项目按"现状"提供,不提供任何形式的明示或暗示的保证,包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下,作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责,无论是在合同诉讼、侵权行为还是其他情况下。

### 使用限制

1. **准确性**: 本工具的中文姓名检测结果仅供参考,不保证 100% 准确
2. **数据安全**: 使用本工具处理文件时,请确保您有权访问和处理相关文件
3. **隐私保护**: 处理包含个人信息的文件时,请遵守相关隐私法规
4. **商业用途**: 如将本工具用于商业用途,请自行评估风险和合规性
5. **责任限制**: 作者不对因使用本工具而导致的任何直接或间接损失负责

### 建议

- 在生产环境使用前,请在测试数据上充分验证
- 定期检查更新以获取最新的功能和安全修复
- 如发现安全漏洞,请通过 GitHub Issue  responsibly disclose



