people-enrichment

人员信息补全与搜索（People Data Labs）

一个脚本 scripts/enrich.py，包含 5 个子命令，可操作 PDL 的 Person 和 Company 数据集。所有子命令共用相同的 API 密钥处理方式、布尔型 PII 联系信息逻辑、状态标记、.xlsx 样式，以及 --dry-run 预检模式。

子命令	输入	输出	计费方式
person-enrich	具名人员列表	个人资料 + 工作经历	每次匹配 1 个点数
person-identify	人员列表（身份不明确）	每人若干个经过评分的候选人	按 PDL 识别条款计费
person-search	筛选条件标记	匹配人员列表	每条返回记录 1 个点数
company-enrich	公司列表	公司信息	每次匹配 1 个点数
company-search	筛选条件标记	匹配公司列表	每条返回记录 1 个点数

两个 search 命令按每个 结果 返回数据，因此费用会随 --size 增长。进行大规模搜索前，请务必说明大致费用；除非用户要求更多结果，否则应将 --size 保持在较低水平（每次请求最多 100 条）。

适用范围与路由

当用户出于正当且适度的目的，希望使用 PDL 补全或搜索人员／公司信息时，使用此技能。不要用它直接抓取 LinkedIn、编制具有侵扰性的个人档案，或在宿主环境要求使用其他数据提供商时使用它。

为什么使用 People Data Labs，而不是 LinkedIn 抓取工具

抓取 LinkedIn 不稳定且存在法律风险。此技能使用 PDL 这一持牌聚合服务，而不是实时抓取 LinkedIn。如果用户坚持要实时抓取，请说明其中的利弊，而不是构建抓取工具。

API 密钥

scripts/enrich.py 需要 PDL 密钥，运行时按以下顺序查找：PDL_API_KEY 环境变量 → 当前工作目录中的 .env → 脚本所在目录中的 .env。**绝不能将密钥写入此技能或任何脚本。**如果没有密钥，实时命令会退出并显示操作说明。--dry-run 和 --self-test 不需要密钥。

仅在本地创建 .env：

echo 'PDL_API_KEY=their_key_here' > .env

将 .env 视为机密：不要打印、提交或上传它。--self-test 会离线运行（使用预置数据，无需密钥），并写入人员和公司示例工作表，让用户在消耗点数前了解输出格式。

Dry-run 预检

在消耗点数前，尤其是处理较大的文件或进行搜索时，请使用 --dry-run 运行相同的命令：

python scripts/enrich.py person-enrich --input people.csv --output out.xlsx --dry-run
python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25 --dry-run
python scripts/enrich.py company-search --industry "real estate" --country singapore --size 50 --dry-run

Dry-run 会验证输入／搜索条件、打印计划输出，并估算最多可能消耗的点数；无需 PDL_API_KEY，不会调用 PDL，也不会写入 .xlsx 输出文件。

联系信息字段与免费套餐

在免费套餐中，PDL 会将 PII 字段（emails、phone_numbers）以布尔值而非具体信息返回：true = 存在联系信息，但需付费才能查看；false = 无记录。人员工作表会在 Email status／Phone status 列中显示此状态：included（存在实际信息，适用于 Pro 套餐）、exists - upgrade to view（存在信息，但需升级才能查看）、none on file 或 unknown。

五个命令

person-enrich — 为具名人员进行一对一匹配。

python scripts/enrich.py person-enrich --input people.csv --output out.xlsx

可识别的输入列（不区分大小写和空格）：name/full name、first name、last name、company/employer、title、location、email、linkedin/profile。每行提供的上下文越多，匹配率越高。

person-identify — 当单次 enrich 存在歧义时，获取候选集。

python scripts/enrich.py person-identify --input people.csv --max-candidates 5

输入与 enrich 相同。输出中每位输入人员对应多行，每行是一位带评分的候选人（Match score 列），用户可据此选出正确人选。

person-search — 按条件查找人员，无需提供姓名列表。

python scripts/enrich.py person-search --company "Northwind Capital" --title director --size 25

标志：--company --title --location --country --industry --name，以及 --size（1–100）、--dataset（默认为 all）和用于传入原始 PDL SQL 查询以实现完全控制的 --sql。标志之间按 AND 组合。

company-enrich — 将公司列表与公司基本信息进行匹配。

python scripts/enrich.py company-enrich --input companies.csv --output firms.xlsx

可识别的输入列：name/company、website/domain、ticker、linkedin/profile、location/country/region/locality。每行至少需要提供 name/website/ticker/profile 中的一项。

company-search — 按条件查找公司。

python scripts/enrich.py company-search --industry "real estate" --country singapore --min-employees 50 --size 50

标志：--name --industry --country --locality --tag --min-employees，以及 --size 和 --sql。

与用户一起检查输出

人员工作表有两个选项卡：People（每人一行，状态以颜色标示）和 Employment history（每段过往任职经历一行）。公司工作表只有一个 Companies 选项卡。首先检查 Status 列：matched（绿色）、needs_review（琥珀色）、no_match（红色）、error（橙色）。明确指出琥珀色/红色的行，让用户知道哪些内容需要复核。

调整匹配

--min-likelihood N（1–10）是 enrich/identify 命令的置信度下限。当姓名/公司名称较常见，且宁可漏掉也不愿误匹配时，提高该值（6–8）；当上下文信息丰富且希望提高覆盖率时，降低该值。提供网站/域名时，公司信息补全最可靠；提供姓名及公司或邮箱时，人员信息补全最可靠。

日后更换服务提供方

PDL 专属部分包括 *_params 构建器、pdl_request，以及 parse_person / parse_company 映射器。要支持其他服务提供方，请针对其 API 实现这些部分，并保持相同的记录 dict 结构；输入解析、状态逻辑、SQL/标志处理、试运行摘要和 .xlsx 写入均保持不变。

原则

• 草稿，而非建议 — 输出是供人审阅的研究辅助信息，不是最终判定。
• 绝不臆造 — 仅展示 PDL 返回的内容；如实标记 no_match/needs_review，而不是猜测身份。
• 关键环节保持确定性 — 输入解析、状态逻辑、试运行估算和 .xlsx 写入均具有确定性。
• 诚实且校准得当 — 标记低置信度匹配，并提前说明大致的积分费用。
• 保持工作区整洁 — 将输出写入用户预期的位置；绝不将 API 密钥写入技能中的磁盘。

数据处理

PDL 是第三方服务，信息补全会将真实姓名/公司名称发送给它 — 这些信息无法令牌化，因为姓名本身就是查询依据。将 .env / PDL_API_KEY 视为机密：绝不打印、提交或上传。对于人员信息，请确认用途合法且适度，并且只收集与该用途相关的字段。

注意事项

1. 免费套餐会隐藏联系信息 — 邮箱/电话号码会以布尔值形式返回；请查看状态列。
2. 搜索费用随 --size 增长 — 说明大致的积分费用，并将 --size 控制在较小范围。
3. 常见姓名容易误匹配 — 提高 --min-likelihood，或添加上下文列（公司/邮箱）。
4. 绝不提交 .env — 密钥属于机密；--self-test 和 --dry-run 无需密钥。
5. 试运行只是估算 — 实际计费取决于 PDL 的端点条款以及返回的记录/匹配结果。

验证清单

• 已确认对任何个人信息补充或搜索均具有合法且适度的用途。
• 对于大型文件或搜索，已使用 --dry-run 验证范围并估算额度。
• 实际运行时，可通过环境变量或 .env 获取 PDL_API_KEY（绝不将其写入技能中）。
• 在进行任何大型搜索前，已说明大致的额度成本。
• 已向用户标出状态为琥珀色或红色的行。
• 未打印或提交 .env。

要求

• Python 3.8+
• pip install openpyxl（HTTP 使用标准库 urllib，无需 requests）
• 实际调用 API 需要 PDL_API_KEY（环境变量或 .env）；请访问 https://www.peopledatalabs.com 获取
• 可访问 PDL API 的网络连接。--self-test 和 --dry-run 可完全离线运行。