helan 0.1.0rc1__tar.gz

helan-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 helan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

helan-0.1.0rc1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: helan
+Version: 0.1.0rc1
+Summary: The Veil of Hidden Names (Helan) | Chinese-first personal data detection and masking
+Author: helan contributors
+License: MIT
+Project-URL: Homepage, https://github.com/cloudydreamland/TheVeilOfHiddenNames
+Project-URL: Repository, https://github.com/cloudydreamland/TheVeilOfHiddenNames
+Project-URL: Issues, https://github.com/cloudydreamland/TheVeilOfHiddenNames/issues
+Project-URL: Changelog, https://github.com/cloudydreamland/TheVeilOfHiddenNames/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/cloudydreamland/TheVeilOfHiddenNames/security/policy
+Keywords: pii,脱敏,privacy,chinese,nlp,llm,compliance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: jieba
+Requires-Dist: jieba>=0.42; extra == "jieba"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# The Veil of Hidden Names — Helan
+
+简体中文 · [English](README.en.md)
+
+> 展示名 **The Veil of Hidden Names** 意为“隐名之幕”；Helan 是该项目的短名。
+
+**中文优先的 PII 检测与脱敏库。校验和级识别，可逆 Vault 还原，格式保留假名——帮助你在把数据交给大模型或其他服务前发现并处理敏感信息。**
+
+[![CI](https://github.com/cloudydreamland/TheVeilOfHiddenNames/actions/workflows/ci.yml/badge.svg)](.github/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 为什么需要它 / Why
+
+在将中文业务文本送入 LLM、RAG 或其他外部处理服务前，开发者常需要识别并处理个人信息。通用识别框架可扩展，但中文证件校验、误报控制和可恢复脱敏通常需要额外规则与评测。
+
+`helan`（Helan）把这件事做成零依赖标准件：
+
+- **格式校验**：对身份证、银行卡和统一社会信用代码应用相应校验规则，减少仅凭位数与字符模式产生的误报；其他实体依赖上下文规则，仍可能漏检或误报
+- **偏移不变量**：每个实体保证 `entity.text == source[start:end]`（fuzz 测试永久守护），脱敏结果可精确引用回原文
+- **可逆 Vault**：用占位符脱敏并通过受保护的 Vault 还原；Vault 含有恢复敏感信息，必须与原文同等保护
+- **格式保留假名**：`fake` 算子生成的假身份证能通过身份证校验、假银行卡能通过 Luhn——替换后的数据仍是"合法格式"，适合造测试集与演示数据
+- **零必装依赖**：核心纯 Python；jieba（人名 NER 补召回）与 LLM（语义级兜底）全部可选
+- **自带评测**：内置 12 篇中文语料 + P/R/F1 报告，数字如实
+
+## 安装 / Install
+
+> 当前尚未发布到 PyPI；下方给出从 GitHub 获取并本地安装的命令。
+
+```bash
+git clone https://github.com/cloudydreamland/TheVeilOfHiddenNames.git
+cd TheVeilOfHiddenNames
+python -m pip install .
+# PyPI 首发后：python -m pip install helan
+python -m pip install ".[jieba]"
+```
+
+## 快速开始 / Quickstart
+
+```python
+from helan import mask, restore, recognize
+
+text = "出租方张伟明（身份证 11010519491231002X，电话 13812345678）同意将房屋出租。"
+
+# 只识别
+
+for e in recognize(text):
+    print(e.type, e.start, e.end, e.text)
+
+# 可逆脱敏：身份证换成占位符，可精确还原
+
+masked, vault = mask(text, ops={"ID_CARD": "vault"})
+original = restore(masked, vault)
+assert original == text
+
+# 不可逆脱敏：手机号换成"合法格式"的假号码
+
+masked, _ = mask(text, ops={"PHONE": "fake"})
+```
+
+命令行：
+
+```bash
+helan scan 合同.txt --json            # 只识别
+helan mask 合同.txt -o 脱敏.txt --ops ID_CARD:vault,PHONE:fake --vault-out vault.json
+helan restore 脱敏.txt --vault vault.json -o 还原.txt
+helan eval                            # 内置基准报告
+```
+
+## 实体类型与算子
+
+| 类型 | 识别方式 | 默认算子 |
+|---|---|---|
+| ID_CARD 身份证 | 区划+出生日期+MOD 11-2 校验码 | partial（前3后4） |
+| BANK_CARD 银行卡 | Luhn 校验（支持空格/连字符分组） | partial（留后4） |
+| USCC 统一社会信用代码 | GB 32100 MOD 31-3 校验 | partial |
+| PHONE 手机号 | 号段表严格校验 | partial（138\*\*\*\*5678） |
+| PERSON_NAME 人名 | 称谓/引导词/顿号枚举上下文；jieba nr 可选 | partial（张\*\*） |
+| ADDRESS 地址 | 引导词上下文 | redact |
+| LANDLINE / EMAIL / IP / URL / PASSPORT / LICENSE_PLATE | 规则+守卫 | partial/redact |
+| TW_ID_CARD 台湾身份证 | 地区字母码+性别位+加权 MOD 10 校验 | partial |
+| POSTAL_CODE / QQ / 微信号 / OFFICER_ID | 关键词上下文（军官证为 format-only，如实标注） | redact/partial |
+| ID_CARD 全角/符号分隔写法 | 1101 0519 4912 3100 2X 等分隔归一化后过校验和 | partial |
+
+算子：`redact`（标签替换）/ `partial`（部分保留）/ `hash`（加盐稳定假名）/ `fake`（合法格式假数据）/ `vault`（可逆占位）/ 任意自定义 callable。
+
+## 与现有方案的关系 / Landscape
+
+我们曾用固定版本的 `presidio-analyzer` 与本项目内置语料做对照。测试范围、配置、语料及局限见[方法和完整结果](docs/presidio_zh.md)；这些结果只适用于该次设置，不代表所有 Presidio 中文部署：
+
+| 方案 | 实测/事实 |
+|---|---|
+| Presidio 等通用框架 | 提供可配置的识别与匿名化管线；中文效果取决于所选 recognizer、规则和评测语料 |
+| 自定义正则 | 易于嵌入，但需要自行实现格式校验、上下文规则、偏移处理和评测 |
+| Helan | 聚焦中文规则、原文偏移以及多种脱敏算子；适用范围和评测边界见下文 |
+
+选题取证（为什么这个缺口是真的）见 [GAP_PROOF.md](GAP_PROOF.md)。
+
+## 评测 / Evaluation
+
+内置基准（14 篇中文合成文档（含散文体）/ 48 个 gold 实体）真实结果：[benchmarks/results.md](benchmarks/results.md)
+
+- 当前快照：default 配置 **P 1.000 / R 1.000 / F1 1.000**；无上下文配置 R 0.644（人名/地址全靠上下文层）
+- **诚实声明**：语料为合成文档（由本库假数据生成器构造，标注零噪声），分布窄于真实业务文档，数字代表格式级能力上限，不外推为生产效果
+
+## 性能 / Performance
+
+2MB 混合文本、单核（[benchmarks/perf.md](benchmarks/perf.md)）：完整管线 **2.35 MB/s**（3.4 万实体），比"同正则、零校验"的手搓基线慢 2.8 倍——这个代价买的是误报治理。
+
+## 从 presidio 迁移 / Migration
+
+```python
+from helan.compat_presidio import MianjuAnalyzer
+
+results = MianjuAnalyzer().analyze(text="证件号 23144319731204692X", entities=["ID_CARD"])
+for r in results:
+    print(r.entity_type, r.start, r.end, r.score)   # 属性面与 presidio 一致
+```
+
+## 大文本 / Streaming
+
+```python
+from helan import recognize_iter, read_file_chunks
+
+for e in recognize_iter(read_file_chunks("huge.txt"), chunk_size=65536, overlap=512):
+    print(e.type, e.start, e.end, e.text)   # 返回绝对偏移；该测试样本与整读结果一致，详见性能报告
+```
+
+约束：单实体长度须小于 overlap（URL 已加 512 上限与之匹配）。
+
+## 路线图 / Roadmap
+
+见 [ROADMAP.md](ROADMAP.md)。当前 v0.1.0：17 类型识别（含台湾身份证校验和、全角分隔身份证写法）+ 4 类算子 + Vault 还原 + 内置评测 + 流式 API + 黑名单校准，194 项测试全绿。

helan-0.1.0rc1/README.md

@@ -0,0 +1,133 @@
+# The Veil of Hidden Names — Helan
+
+简体中文 · [English](README.en.md)
+
+> 展示名 **The Veil of Hidden Names** 意为“隐名之幕”；Helan 是该项目的短名。
+
+**中文优先的 PII 检测与脱敏库。校验和级识别，可逆 Vault 还原，格式保留假名——帮助你在把数据交给大模型或其他服务前发现并处理敏感信息。**
+
+[![CI](https://github.com/cloudydreamland/TheVeilOfHiddenNames/actions/workflows/ci.yml/badge.svg)](.github/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 为什么需要它 / Why
+
+在将中文业务文本送入 LLM、RAG 或其他外部处理服务前，开发者常需要识别并处理个人信息。通用识别框架可扩展，但中文证件校验、误报控制和可恢复脱敏通常需要额外规则与评测。
+
+`helan`（Helan）把这件事做成零依赖标准件：
+
+- **格式校验**：对身份证、银行卡和统一社会信用代码应用相应校验规则，减少仅凭位数与字符模式产生的误报；其他实体依赖上下文规则，仍可能漏检或误报
+- **偏移不变量**：每个实体保证 `entity.text == source[start:end]`（fuzz 测试永久守护），脱敏结果可精确引用回原文
+- **可逆 Vault**：用占位符脱敏并通过受保护的 Vault 还原；Vault 含有恢复敏感信息，必须与原文同等保护
+- **格式保留假名**：`fake` 算子生成的假身份证能通过身份证校验、假银行卡能通过 Luhn——替换后的数据仍是"合法格式"，适合造测试集与演示数据
+- **零必装依赖**：核心纯 Python；jieba（人名 NER 补召回）与 LLM（语义级兜底）全部可选
+- **自带评测**：内置 12 篇中文语料 + P/R/F1 报告，数字如实
+
+## 安装 / Install
+
+> 当前尚未发布到 PyPI；下方给出从 GitHub 获取并本地安装的命令。
+
+```bash
+git clone https://github.com/cloudydreamland/TheVeilOfHiddenNames.git
+cd TheVeilOfHiddenNames
+python -m pip install .
+# PyPI 首发后：python -m pip install helan
+python -m pip install ".[jieba]"
+```
+
+## 快速开始 / Quickstart
+
+```python
+from helan import mask, restore, recognize
+
+text = "出租方张伟明（身份证 11010519491231002X，电话 13812345678）同意将房屋出租。"
+
+# 只识别
+
+for e in recognize(text):
+    print(e.type, e.start, e.end, e.text)
+
+# 可逆脱敏：身份证换成占位符，可精确还原
+
+masked, vault = mask(text, ops={"ID_CARD": "vault"})
+original = restore(masked, vault)
+assert original == text
+
+# 不可逆脱敏：手机号换成"合法格式"的假号码
+
+masked, _ = mask(text, ops={"PHONE": "fake"})
+```
+
+命令行：
+
+```bash
+helan scan 合同.txt --json            # 只识别
+helan mask 合同.txt -o 脱敏.txt --ops ID_CARD:vault,PHONE:fake --vault-out vault.json
+helan restore 脱敏.txt --vault vault.json -o 还原.txt
+helan eval                            # 内置基准报告
+```
+
+## 实体类型与算子
+
+| 类型 | 识别方式 | 默认算子 |
+|---|---|---|
+| ID_CARD 身份证 | 区划+出生日期+MOD 11-2 校验码 | partial（前3后4） |
+| BANK_CARD 银行卡 | Luhn 校验（支持空格/连字符分组） | partial（留后4） |
+| USCC 统一社会信用代码 | GB 32100 MOD 31-3 校验 | partial |
+| PHONE 手机号 | 号段表严格校验 | partial（138\*\*\*\*5678） |
+| PERSON_NAME 人名 | 称谓/引导词/顿号枚举上下文；jieba nr 可选 | partial（张\*\*） |
+| ADDRESS 地址 | 引导词上下文 | redact |
+| LANDLINE / EMAIL / IP / URL / PASSPORT / LICENSE_PLATE | 规则+守卫 | partial/redact |
+| TW_ID_CARD 台湾身份证 | 地区字母码+性别位+加权 MOD 10 校验 | partial |
+| POSTAL_CODE / QQ / 微信号 / OFFICER_ID | 关键词上下文（军官证为 format-only，如实标注） | redact/partial |
+| ID_CARD 全角/符号分隔写法 | 1101 0519 4912 3100 2X 等分隔归一化后过校验和 | partial |
+
+算子：`redact`（标签替换）/ `partial`（部分保留）/ `hash`（加盐稳定假名）/ `fake`（合法格式假数据）/ `vault`（可逆占位）/ 任意自定义 callable。
+
+## 与现有方案的关系 / Landscape
+
+我们曾用固定版本的 `presidio-analyzer` 与本项目内置语料做对照。测试范围、配置、语料及局限见[方法和完整结果](docs/presidio_zh.md)；这些结果只适用于该次设置，不代表所有 Presidio 中文部署：
+
+| 方案 | 实测/事实 |
+|---|---|
+| Presidio 等通用框架 | 提供可配置的识别与匿名化管线；中文效果取决于所选 recognizer、规则和评测语料 |
+| 自定义正则 | 易于嵌入，但需要自行实现格式校验、上下文规则、偏移处理和评测 |
+| Helan | 聚焦中文规则、原文偏移以及多种脱敏算子；适用范围和评测边界见下文 |
+
+选题取证（为什么这个缺口是真的）见 [GAP_PROOF.md](GAP_PROOF.md)。
+
+## 评测 / Evaluation
+
+内置基准（14 篇中文合成文档（含散文体）/ 48 个 gold 实体）真实结果：[benchmarks/results.md](benchmarks/results.md)
+
+- 当前快照：default 配置 **P 1.000 / R 1.000 / F1 1.000**；无上下文配置 R 0.644（人名/地址全靠上下文层）
+- **诚实声明**：语料为合成文档（由本库假数据生成器构造，标注零噪声），分布窄于真实业务文档，数字代表格式级能力上限，不外推为生产效果
+
+## 性能 / Performance
+
+2MB 混合文本、单核（[benchmarks/perf.md](benchmarks/perf.md)）：完整管线 **2.35 MB/s**（3.4 万实体），比"同正则、零校验"的手搓基线慢 2.8 倍——这个代价买的是误报治理。
+
+## 从 presidio 迁移 / Migration
+
+```python
+from helan.compat_presidio import MianjuAnalyzer
+
+results = MianjuAnalyzer().analyze(text="证件号 23144319731204692X", entities=["ID_CARD"])
+for r in results:
+    print(r.entity_type, r.start, r.end, r.score)   # 属性面与 presidio 一致
+```
+
+## 大文本 / Streaming
+
+```python
+from helan import recognize_iter, read_file_chunks
+
+for e in recognize_iter(read_file_chunks("huge.txt"), chunk_size=65536, overlap=512):
+    print(e.type, e.start, e.end, e.text)   # 返回绝对偏移；该测试样本与整读结果一致，详见性能报告
+```
+
+约束：单实体长度须小于 overlap（URL 已加 512 上限与之匹配）。
+
+## 路线图 / Roadmap
+
+见 [ROADMAP.md](ROADMAP.md)。当前 v0.1.0：17 类型识别（含台湾身份证校验和、全角分隔身份证写法）+ 4 类算子 + Vault 还原 + 内置评测 + 流式 API + 黑名单校准，194 项测试全绿。

helan-0.1.0rc1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "helan"
+version = "0.1.0rc1"
+description = "The Veil of Hidden Names (Helan) | Chinese-first personal data detection and masking"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "helan contributors" }]
+keywords = ["pii", "脱敏", "privacy", "chinese", "nlp", "llm", "compliance"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+[project.optional-dependencies]
+jieba = ["jieba>=0.42"]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+helan = "helan.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/cloudydreamland/TheVeilOfHiddenNames"
+Repository = "https://github.com/cloudydreamland/TheVeilOfHiddenNames"
+Issues = "https://github.com/cloudydreamland/TheVeilOfHiddenNames/issues"
+Changelog = "https://github.com/cloudydreamland/TheVeilOfHiddenNames/blob/main/CHANGELOG.md"
+Security = "https://github.com/cloudydreamland/TheVeilOfHiddenNames/security/policy"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+helan = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+ignore = [
+    "DTZ011",  # 出生日期校验用 date.today() 足够，与时区无关
+    "RUF007",  # 测试中 zip(seq, seq[1:]) 比 pairwise 更直观
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

helan-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

helan-0.1.0rc1/src/helan/__init__.py

@@ -0,0 +1,59 @@
+"""Helan — 中文优先的 PII 检测与脱敏库。
+
+快速上手::
+
+    from helan import mask, restore, Vault
+
+    masked, vault = mask(text, ops={"ID_CARD": "vault", "PHONE": "fake"})
+    original = restore(masked, vault)
+"""
+
+from .pipeline import DEFAULT_OPS, build_recognizers, mask, recognize, restore
+from .streaming import read_file_chunks, recognize_iter
+from .types import (
+    ADDRESS,
+    ALL_TYPES,
+    BANK_CARD,
+    EMAIL,
+    ENTITY_TYPES,
+    ID_CARD,
+    IP_ADDRESS,
+    LANDLINE,
+    LICENSE_PLATE,
+    PASSPORT,
+    PERSON_NAME,
+    PHONE,
+    URL,
+    USCC,
+    Entity,
+)
+from .vault import Vault
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ADDRESS",
+    "ALL_TYPES",
+    "BANK_CARD",
+    "DEFAULT_OPS",
+    "EMAIL",
+    "ENTITY_TYPES",
+    "ID_CARD",
+    "IP_ADDRESS",
+    "LANDLINE",
+    "LICENSE_PLATE",
+    "PASSPORT",
+    "PERSON_NAME",
+    "PHONE",
+    "URL",
+    "USCC",
+    "Entity",
+    "Vault",
+    "__version__",
+    "build_recognizers",
+    "mask",
+    "read_file_chunks",
+    "recognize",
+    "recognize_iter",
+    "restore",
+]

helan-0.1.0rc1/src/helan/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

helan-0.1.0rc1/src/helan/bench.py

@@ -0,0 +1,126 @@
+"""吞吐基准:helan 完整管线 vs 纯正则基线。
+
+诚实口径:
+- "纯正则基线"= 用与 helan 完全相同的正则抓候选,但**不做任何校验和验证、
+  不做冲突消解**——它代表"手搓正则脱敏"的成本上限(它更快,但会产出大量误报)。
+- 差值就是校验和验证 + 冲突消解的安全代价。
+- 单核、CPython、Windows;数字只代表本机,不外推。
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import time
+
+from .eval.corpus import build_corpus
+from .pipeline import recognize
+
+MACHINE = "Windows / CPython 3.13 / 单核"
+
+
+def build_mixed_text(target_mb: float, seed: int = 2026) -> str:
+    """语料文档 + 随机中文数字噪声,拼到目标大小。噪声保证正则层有真实扫描压力。"""
+    rng = random.Random(seed)
+    base_docs = [d.text for d in build_corpus()]
+    filler_pool = (
+        "本段为普通业务文本，用于模拟真实文档中的非敏感内容，包含数字 12345 与标点。",
+        "会议决定、预算安排、项目进度、交付节点、验收标准等事项。",
+        "The quick brown fox jumps over the lazy dog 9988776655.",
+        "账户余额、汇率、结算周期、手续费率等财务信息。",
+    )
+    parts: list[str] = []
+    total = 0
+    target = int(target_mb * 1024 * 1024)
+    while total < target:
+        if rng.random() < 0.25:
+            parts.append(rng.choice(base_docs))
+        else:
+            parts.append(rng.choice(filler_pool))
+        total += len(parts[-1])
+    return "\n".join(parts)
+
+
+def regex_baseline_scan(text: str) -> int:
+    """纯正则基线:与 helan 相同的正则抓候选,不验证、不消解。返回候选数。"""
+    import re
+
+    from helan.data import HONORIFICS, LEAD_WORDS, SURNAMES
+    from helan.recognizers import chinese
+    from helan.recognizers.base import guarded_pattern
+
+    patterns = [
+        re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+"),
+        guarded_pattern(r"(?:\d{1,3}\.){3}\d{1,3}", left="0-9.", right="0-9"),
+        re.compile(r"https?://[^\s<>\"'，。；！？、]{1,512}"),
+        guarded_pattern(r"(?:0\d{2,3})-?[2-9]\d{6,7}"),
+        guarded_pattern(r"\d{17}[0-9Xx]"),
+        guarded_pattern(r"\d{15}"),
+        guarded_pattern(r"\d{13,19}", right="0-9Xx"),
+        guarded_pattern(r"1[3-9]\d{9}"),
+        chinese._ADDR_RE,
+    ]
+    count = 0
+    for pat in patterns:
+        for _m in pat.finditer(text):
+            count += 1
+    _ = HONORIFICS, LEAD_WORDS, SURNAMES
+    return count
+
+
+def run(target_mb: float) -> dict:
+    text = build_mixed_text(target_mb)
+    size_mb = len(text) / 1024 / 1024
+
+    t0 = time.perf_counter()
+    entities = recognize(text)
+    t1 = time.perf_counter()
+    full_secs = t1 - t0
+
+    t0 = time.perf_counter()
+    candidates = regex_baseline_scan(text)
+    baseline_secs = time.perf_counter() - t0
+
+    return {
+        "size_mb": size_mb,
+        "entities": len(entities),
+        "full_secs": full_secs,
+        "full_mbps": size_mb / full_secs,
+        "baseline_secs": baseline_secs,
+        "baseline_mbps": size_mb / baseline_secs,
+        "baseline_candidates": candidates,
+        "machine": MACHINE,
+    }
+
+
+def render(result: dict) -> str:
+    return (
+        "# helan 性能基准\n\n"
+        f"- 机器:{result['machine']}(数字只代表本机,不外推)\n"
+        f"- 文本:{result['size_mb']:.2f} MB 合成混合文本(内置语料 25% + 普通业务噪声 75%)\n"
+        f"- helan 完整管线(校验和+规则+上下文+消解):**{result['full_mbps']:.2f} MB/s**"
+        f"({result['full_secs']:.2f}s,{result['entities']} 个实体)\n"
+        f"- 纯正则基线(同正则、零校验、零消解,手搓方案的速度上限):{result['baseline_mbps']:.2f} MB/s"
+        f"({result['baseline_secs']:.2f}s,{result['baseline_candidates']} 个未验证候选)\n"
+        f"- **安全代价:完整管线比纯正则慢 {result['full_secs'] / result['baseline_secs']:.1f} 倍**——"
+        "这个代价买的是误报治理(发票号不再被当成手机号)。\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="helan.bench")
+    parser.add_argument("--mb", type=float, default=2.0)
+    parser.add_argument("--write", help="markdown 结果写入路径")
+    args = parser.parse_args(argv)
+    result = run(args.mb)
+    report = render(result)
+    print(report)
+    if args.write:
+        from .io_utils import write_text
+
+        write_text(args.write, report)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

helan-0.1.0rc1/src/helan/calibrate.py

@@ -0,0 +1,79 @@
+"""停用词黑名单校准：在内置语料上找出 PERSON_NAME 的真实 FP，自动建议扩充。
+
+原理：合成语料有零噪声 gold，所以这里统计的是**真实 FP**（不是猜测）：
+- 逐条列出 FP 的触发 cue 与上下文；
+- 按 `text[:2]` 聚合，出现 ≥2 次的前缀自动建议加入 `PERSON_NAME_BLOCKLIST`；
+- 单次出现的 FP 交人工判断（宁可漏建议，不可误杀真人名）。
+
+用法：`helan calibrate`（或 `python -m helan.calibrate`）。
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .data import PERSON_NAME_BLOCKLIST
+from .eval.corpus import build_corpus
+from .pipeline import recognize
+
+
+def collect_person_fps() -> list[dict]:
+    """跑内置语料，收集 PERSON_NAME 的 FP（与 gold 不匹配的命中）。"""
+    fps: list[dict] = []
+    for doc in build_corpus():
+        gold = {
+            (g.start, g.end) for g in doc.gold if g.type == "PERSON_NAME"
+        }
+        for e in recognize(doc.text, jieba=False):
+            if e.type == "PERSON_NAME" and (e.start, e.end) not in gold:
+                fps.append(
+                    {
+                        "text": e.text,
+                        "cue": e.meta.get("cue", "?"),
+                        "doc": doc.doc_id,
+                        "context": doc.text[max(0, e.start - 10) : e.end + 10].replace("\n", "|"),
+                    }
+                )
+    return fps
+
+
+def suggest_blocklist(fps: list[dict], min_count: int = 2) -> list[str]:
+    """出现 ≥ min_count 次的两字前缀，自动建议加入黑名单。"""
+    counter = Counter(fp["text"][:2] for fp in fps)
+    return [prefix for prefix, n in counter.most_common() if n >= min_count]
+
+
+def render() -> str:
+    fps = collect_person_fps()
+    lines = [
+        "# PERSON_NAME 停用词黑名单校准报告",
+        "",
+        f"- 数据：内置语料（gold 零噪声），本次 FP 总数 **{len(fps)}**",
+        f"- 现行黑名单规模：{len(PERSON_NAME_BLOCKLIST)} 条",
+        "",
+    ]
+    if not fps:
+        lines.append("当前语料上 PERSON_NAME 无 FP，黑名单无需扩充。")
+        return "\n".join(lines)
+
+    suggestions = suggest_blocklist(fps)
+    lines.append("## 自动建议（出现 ≥2 次的前缀）")
+    lines.append("")
+    lines.append(f"`{suggestions}`" if suggestions else "无")
+    lines.append("")
+    lines.append("## 全部 FP 明细（单次出现者请人工判断）")
+    lines.append("")
+    lines.append("| 触发 cue | 文本 | 上下文 | 文档 |")
+    lines.append("|---|---|---|---|")
+    for fp in fps:
+        lines.append(f"| {fp['cue']} | {fp['text']} | `{fp['context']}` | {fp['doc']} |")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    print(render())
+    return 0
+
+
+if __name__ == "__main__":
+    main()