chinese-name-detector 0.2.1

A lightweight tool to detect Chinese characters and surnames.

chinese-name-detector：中文字符与姓氏检测利器

chinese-name-detector（原 cndetect）是一个专为中文环境设计的轻量级检测工具。它能够智能识别文本中的中文字符以及常见的中文姓氏（支持汉字识别与拼音识别）。

无论你是需要批量处理 Excel 表格的非技术人员，还是希望在代码中集成姓名检测功能的开发者，chinese-name-detector 都能为你提供简单、高效的解决方案。

---

🌟 核心特性

• 双接口支持：既有简洁的命令行工具（CLI），也有功能完备的 Python 调用接口（API）。
• 智能识别：支持汉字姓氏（如“王”、“欧阳”）和拼音姓氏（如“Wang”、“Ouyang”）。
• 多模式匹配：提供 overall (整体)、component (分步) 和 strict (严格) 三种检测模式，精准应对各种复杂格式与混合噪声。
• 混合格式支持：能够从 wangxm133、li_abc、Davdgao 等混合字符串中准确提取姓氏。
• 精准匹配：拼音识别支持“独立单词”模式与“组件匹配”模式，有效避免如 Alice 中的 li 被误判。
• Excel 友好：支持一键扫描 Excel 文件并自动生成带有检测结果的新表格。
• 隐私保护：内置日志打码功能，自动隐藏敏感姓名信息。

---

📥 安装指南

系统要求

• Python 版本：Python 3.8 或更高版本（支持 Windows, macOS, Linux）。

安装命令

打开你的终端或命令提示符，输入以下命令即可一键安装：

pip install chinese-name-detector

---

🚀 快速上手 (命令行 CLI)

安装完成后，你可以直接在终端使用 cndetect 命令。

1. 检测单条文本

输入一段文字，查看是否包含中文字符及姓氏。

cndetect single "张三"
cndetect single "Bruce Wang"

# 使用自定义姓氏 (支持逗号分隔或 JSON 列表)
cndetect single "Bruce Wayne" --custom-names "Wayne,Kent"
# 排除特定姓氏
cndetect single "Bruce Wang" --exclude-names "Wang"

# 切换匹配模式 (overall, component, strict)
cndetect single "Wang123" --match-mode component

2. 批量扫描 Excel 文件

指定一个 Excel 文件及其中的某一列，工具会自动识别并保存结果。你可以使用 --match-mode (或 -mm) 参数根据数据特征选择最合适的识别策略。

# 基本用法：指定列名（默认使用 overall 模式）
cndetect batch data.xlsx -c "姓名"

# 处理混合格式：从 wangxm133、zhang_test 等格式中提取姓氏
cndetect batch data.xlsx -c "用户ID" --match-mode component

# 严格过滤：在纯英文环境中过滤 He, She, Long 等常用词干扰
cndetect batch data.xlsx -c "Full_Name" -mm strict

# 组合使用：指定列名、切换模式并添加自定义姓氏
cndetect batch data.xlsx -c "Name" -mm component --custom-names "Wayne,Kent"

模式在批量处理中的效果差异：

• overall：识别速度最快，适合标准 Wang Xiaoming 格式。
• component：推荐用于数据清洗！ 能自动拆分 li_123 并精准提取出 li，大幅提升复杂数据的召回率。
• strict：误报率最低，适合对准确性要求极高的场景，但可能会跳过未首字母大写的合法拼音。

执行完成后，会生成一个名为 data_cn.xlsx 的新文件，其中包含关键结果列：

• ChineseDetector：核心输出列。如果识别为中文姓名（含中文字符或命中姓氏库），该列会保留原始单元格的值，方便你后续直接筛选或作为主键使用；未命中的行则为空。

3. 使用配置文件执行任务

当你有很多文件需要处理，或者有特定的配置需求时，可以使用配置模式。

# 生成一个默认配置模板 cndetect.yaml
cndetect config

# 修改配置文件后，按配置批量运行
cndetect run -c cndetect.yaml

---

🛠️ Python API 使用教程

如果你是一名开发者，可以将 cndetect 集成到你的 Python 项目中。

import cndetect as cnd
import pandas as pd

# --- 场景 1：单条检测 (多模式) ---
# 默认 overall 模式
result = cnd.detect("Wang Xiaoming")

# 使用 component 模式识别混合格式 (如从账号中提取姓氏)
result_mixed = cnd.detect("wangxm133", mode="component")
print(f"混合格式提取结果: {result_mixed.family_name}") # wang

# 使用 strict 模式排除英文同音词干扰
result_strict = cnd.detect("He Wang", mode="strict")
print(f"严格模式结果: {result_strict.family_name}") # Wang (自动忽略英文词 He)

# --- 场景 2：自定义与排除 ---
result_custom = cnd.detect("Bruce Wayne", custom_names=["Wayne"])
print(f"识别到自定义姓氏: {result_custom.family_name}") # Wayne

result_exclude = cnd.detect("Bruce Wang", exclude_names=["Wang"])
print(f"由于被排除，姓氏结果为: {result_exclude.family_name}") # None

# --- 场景 3：处理 Pandas DataFrame ---
data = {'name': ["王小明", "Jack Chen", "Alibaba", "Alice"]}
df = pd.DataFrame(data)

# 批量检测指定的列
df_out = cnd.detect_batch(df, column="name")

# 查看结果
# df_out 会包含原有的列，以及新增的 'ChineseDetector' 列（API 调用默认仍保留 HasChinese 和 FamilyName 供参考）
print(df_out)
# 注：Alibaba 里的 'ba' 和 Alice 里的 'li' 不会被误识别，因为它们不是独立单词。

---

⚙️ 配置说明 (chinese-name-detector.yaml)

你可以通过 YAML 配置文件灵活定义工具的行为。工具会按以下顺序查找配置：命令行 -c 参数 > 当前目录 cndetect.yaml > ~/.config/cndetect/config.yaml。

详细参数手册

1. 基础姓氏配置

参数路径	类型	默认值	说明与示例
family_name_path	字符串	null	自定义姓氏文件路径。指向一个每行包含一个姓氏的 .txt 文件。若设置，将作为基础库使用。
custom_family_names	数组	[]	动态正向匹配列表。在不修改文件的情况下，额外增加需要识别的姓氏。 示例：["MyName", "特有姓"]
exclude_family_names	数组	[]	动态反向排除列表。强制不识别某些特定的字符串。 示例：["SomeFakeName"]

2. 匹配模式配置 (matching.*)

参数路径	类型	默认值	说明与示例
matching.mode	字符串	"overall"	匹配模式。可选值： - overall: 默认模式，整体匹配。 - component: 分步匹配，先拆分组件再识别，适合混合格式。 - strict: 严格模式，仅匹配库内词且要求首字母大写，排除常见英文单词干扰。

3. Excel 批量处理配置 (excel.*)

参数路径	类型	默认值	说明与示例
excel.paths	数组	[]	待处理文件列表。仅在 cndetect run 模式下生效。 示例：["data1.xlsx", "data2.xlsx"]
excel.column	字符串	"Name"	默认检测列名。Excel 中需要进行姓名扫描的列标题。
excel.output_suffix	字符串	"_cn"	输出文件名后缀。生成的检测结果文件名会在原名后增加此后缀。
excel.output_dir	字符串	null	输出目录。指定结果文件保存的文件夹。若为 null 则保存在原文件同目录。

3. 日志与审计配置 (log.*)

参数路径	类型	默认值	说明与示例
log.level	字符串	"INFO"	日志级别。可选 DEBUG, INFO, WARNING, ERROR。
log.file	字符串	null	日志保存路径。若指定，日志将写入该文件（支持自动创建目录）。
log.rotation	字符串	"1 MB"	日志轮转触发大小。单个日志文件达到多大时自动切分。
log.retention	字符串	"7 days"	日志保留时间。过期日志将自动清理。
log.redact_names	布尔值	true	隐私脱敏开关。开启后，日志中的姓名将被打码（如 张*），不影响 Excel 结果。

---

🔍 匹配规则详解

chinese-name-detector 提供三种检测深度，你可以根据数据质量选择最合适的模式：

1. 模式特性对比

模式	核心逻辑	识别能力	防误报能力	适用场景
overall	全文子串扫描 + 单词边界校验	强 (支持全名/缩写)	中 (易受同音词干扰)	标准姓名格式，如 Wang Xiaoming
component	分词后组件匹配 + 子串提取	极强 (支持混合格式)	高 (杜绝子串包含)	账号、邮箱或带数字的混合数据
strict	分词 + 库匹配 + 首字母/黑名单	一般 (仅匹配库内词)	极高 (过滤英文词)	噪音极大的英文文本环境

2. 识别示例

• 混合格式提取 (component 模式)：

  • Davdgao -> gao (识别结尾姓氏)
  • wangxm133 -> wang (识别开头姓氏)
  • alibaba -> None (非开头/结尾且非独立词)

• 独立性校验 (全模式支持)：

  • ✅ Alice Li -> Li
  • ❌ Lily -> None (字母 li 被包含在单词内部)

• 黑名单过滤 (strict 模式)：

  • ✅ He Wang -> Wang (自动过滤英文常用词 He)
  • ❌ he wang -> None (全小写在严格模式下被视为普通单词)

---

❓ 常见问题 (FAQ)

Q: 为什么我的 Excel 列没被识别？ A: 请确保你在使用 batch 命令时通过 -c 参数准确输入了列名，注意大小写和空格。

Q: 识别出的拼音姓氏大小写不对？ A: chinese-name-detector 默认会返回文本中原本的大小写样式，但匹配过程是忽略大小写的。

Q: 如何添加一些特殊的复姓？ A: 你可以使用 cndetect config 生成配置文件，在 family_name_path 中指定你自己的姓氏文件。

---

⚠️ 注意事项

• 数据隐私：在处理包含敏感个人信息的文件时，请确保遵守相关数据隐私法规。工具内置的日志打码仅针对日志文件，不会修改你的原始 Excel 数据。
• 环境隔离：建议在 Python 虚拟环境中安装，以避免依赖冲突。

---

📄 许可证

本项目采用 MIT 许可证。