people-enrichment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

People Enrichment & Search (People Data Labs)

人员信息丰富与搜索（People Data Labs）

One script,

scripts/enrich.py

, with five subcommands over PDL's Person and Company datasets. All share the same API-key handling, the boolean-PII contact logic, status flags,

.xlsx

styling, and a

--dry-run

preflight mode.

Subcommand	Input	Output	Billing
`person-enrich`	list of named people	profile + work history	1 credit / match
`person-identify`	list of people (ambiguous)	several scored candidates each	per PDL identify terms
`person-search`	criteria flags	a list of matching people	1 credit / record returned
`company-enrich`	list of companies	firmographics	1 credit / match
`company-search`	criteria flags	a list of matching companies	1 credit / record returned

The two search commands return data per result, so cost scales with

--size

. Always state the rough cost before a large search and keep

--size

modest unless the user asks for more (max 100 per request).

通过一个脚本

scripts/enrich.py

，对PDL的人员及公司数据集执行五项子命令。所有子命令共享相同的API密钥处理逻辑、布尔型PII联系人逻辑、状态标记、.xlsx样式，以及

--dry-run

预演模式。

子命令	输入	输出	计费方式
`person-enrich`	指定人员列表	个人档案 + 职业经历	1积分/匹配项
`person-identify`	身份模糊的人员列表	每个人员对应多个带分数的候选人	按PDL识别条款计费
`person-search`	条件标记	匹配的人员列表	1积分/返回记录
`company-enrich`	公司列表	企业画像数据	1积分/匹配项
`company-search`	条件标记	匹配的公司列表	1积分/返回记录

两个搜索命令按结果数量返回数据，因此成本随

--size

参数增加。在执行大规模搜索前，务必告知大致成本，且除非用户要求，否则

--size

参数值应保持适中（每次请求最多100条）。

Scope and routing

适用范围与使用规则

Use this skill when the user wants PDL person/company enrichment or search for a legitimate, proportionate purpose. Do not use it to scrape LinkedIn directly, to compile an intrusive profile, or where a host environment mandates a different data provider.

当用户出于合法、合理的目的需要对PDL人员/公司数据进行信息丰富或搜索时，可使用此技能。请勿用它直接爬取LinkedIn、构建侵入性档案，或在宿主环境要求使用其他数据提供商的场景下使用。

Why People Data Labs, not a LinkedIn scraper

选择People Data Labs而非LinkedIn爬虫的原因

Scraping LinkedIn is fragile and legally risky. This skill uses PDL as a licensed aggregator rather than live LinkedIn scraping. If the user insists on live scraping, explain the trade-off rather than building a scraper.

爬取LinkedIn的方案不稳定且存在法律风险。本技能使用PDL作为授权聚合商，而非实时爬取LinkedIn数据。若用户坚持使用实时爬取，需向其说明利弊，而非直接构建爬虫。

The API key

API密钥

scripts/enrich.py

needs a PDL key, resolved at runtime in this order:

PDL_API_KEY

env var →

.env

in the cwd →

.env

next to the script. The key must never be written into this skill or any script. If absent, live commands exit with instructions.

--dry-run

and

--self-test

do not require a key.

Create the

.env

only locally:

bash

echo 'PDL_API_KEY=their_key_here' > .env

Treat

.env

as a secret: don't print, commit, or upload it.

--self-test

runs offline (canned data, no key) and writes sample people + company sheets so the user can see the output format before spending credits.

scripts/enrich.py

需要PDL密钥，运行时按以下顺序查找：

PDL_API_KEY

环境变量 → 当前工作目录下的

.env

文件 → 脚本所在目录下的

.env

文件。绝对不可将密钥写入本技能或任何脚本中。若密钥缺失，实时命令会退出并给出指引。

--dry-run

和

--self-test

模式无需密钥。

仅在本地创建

.env

文件：

bash

echo 'PDL_API_KEY=their_key_here' > .env

将

.env

视为机密文件：请勿打印、提交或上传。

--self-test

模式离线运行（使用预设数据，无需密钥），并生成示例人员及公司表格，让用户在消耗积分前了解输出格式。

Dry-run preflight

预演模式（Dry-run）

Before spending credits, especially on larger files or searches, run the same command with

--dry-run

bash

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 validates the input/search, prints the planned output, and estimates maximum credits without requiring

PDL_API_KEY

, calling PDL, or writing

.xlsx

output.

在消耗积分前，尤其是处理大文件或执行大规模搜索时，请添加

--dry-run

参数运行相同命令：

bash

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

预演模式会验证输入/搜索条件，打印计划输出内容，并估算最大积分消耗，无需

PDL_API_KEY

、调用PDL接口或写入.xlsx输出文件。

Contact fields and the free plan

联系字段与免费版限制

On the free plan, PDL returns PII fields (

emails

phone_numbers

) as a boolean, not the value:

true

= a contact exists but is paywalled,

false

= none on file. The people sheets surface this in Email status / Phone status columns:

included

(real value present, Pro plans),

exists - upgrade to view

(paywalled but present),

none on file

, or

unknown

在免费版计划中，PDL返回的PII字段（

emails

、

phone_numbers

）为布尔值，而非具体内容：

true

表示存在联系人信息但需付费解锁，

false

表示无相关记录。人员表格会在邮箱状态/电话状态列显示这些信息：

included

（存在真实值，专业版计划）、

exists - upgrade to view

（存在但需付费解锁）、

none on file

（无记录）或

unknown

（未知）。

The five commands

五项命令详情

person-enrich — one-to-one match named people.

bash

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

Recognised input columns (case/space-insensitive): name/full name, first name, last name, company/employer, title, location, email, linkedin/profile. More context per row = higher match rate.

person-identify — when a single enrich is ambiguous, get the candidate set.

bash

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

Same input as enrich. Output has multiple rows per input person, each a scored candidate (Match score column), so the user can pick the right one.

person-search — find people by criteria, no name list needed.

bash

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

Flags:

--company --title --location --country --industry --name

, plus

--size

(1–100),

--dataset

(default all), and

--sql

to pass a raw PDL SQL query for full control. Flags are combined with AND.

company-enrich — match a list of companies to firmographics.

bash

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

Recognised input columns: name/company, website/domain, ticker, linkedin/profile, location/country/region/locality. Needs at least one of name/website/ticker/profile per row.

company-search — find companies by criteria.

bash

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

Flags:

--name --industry --country --locality --tag --min-employees

, plus

--size

and

--sql

person-enrich —— 一对一匹配指定人员信息。

bash

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

支持的输入列（大小写/空格不敏感）：姓名/全名、名字、姓氏、公司/雇主、职位、地点、邮箱、LinkedIn/档案链接。每行提供的上下文信息越多，匹配率越高。

person-identify —— 当单次信息丰富结果存在歧义时，获取候选人员集合。

bash

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

输入格式与person-enrich相同。输出中每个输入人员对应多行数据，每行是一个带匹配分数的候选人（匹配分数列），方便用户选择正确的对象。

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

bash

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

支持的标记：

--company --title --location --country --industry --name

，以及

--size

（1–100）、

--dataset

（默认全部）、

--sql

（传入原始PDL SQL查询以获得完全控制权）。所有标记通过AND逻辑组合。

company-enrich —— 匹配公司列表并生成企业画像数据。

bash

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

支持的输入列：名称/公司、网站/域名、股票代码、LinkedIn/档案链接、地点/国家/地区/区域。每行至少需要名称/网站/股票代码/档案链接中的一项。

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

bash

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

。

Reviewing output with the user

与用户一同审核输出结果

People sheets have two tabs: People (one row per person, status colour-coded) and Employment history (one row per past role). Company sheets have a single Companies tab. The Status column is the first thing to check:

matched

(green),

needs_review

(amber),

no_match

(red),

error

(orange). Call out the amber/red rows explicitly so the user knows what to double-check.

人员表格包含两个标签页：People（每行对应一个人员，状态用颜色标记）和Employment history（每行对应一段过往工作经历）。公司表格仅包含一个Companies标签页。状态列是首要检查项：

matched

（绿色，匹配成功）、

needs_review

（黄色，需审核）、

no_match

（红色，无匹配）、

error

（橙色，出错）。需明确向用户指出黄色/红色行的内容，以便用户进行复核。

Tuning matches

调整匹配精度

--min-likelihood N

(1–10) is the confidence floor for the enrich/identify commands. Raise it (6–8) when names/companies are common and you'd rather miss than mis-match; lower it when you have rich context and want coverage. Company enrichment is most reliable with a website/domain; person enrichment with a company or email alongside the name.

--min-likelihood N

（1–10）是信息丰富/识别命令的置信度下限。当姓名/公司名称较为常见时，可提高该值（6–8），宁愿错过也避免错误匹配；当有丰富上下文信息时，可降低该值以扩大覆盖范围。公司信息丰富在提供网站/域名时匹配最可靠；人员信息丰富在同时提供公司或邮箱与姓名时匹配最可靠。

Swapping providers later

后续更换数据提供商

The PDL-specific pieces are the

*_params

builders,

pdl_request

, and the

parse_person

parse_company

mappers. To support another provider, implement those against its API and keep the same record dict shape; input parsing, status logic, SQL/flag handling, dry-run summaries, and

.xlsx

writing stay as is.

PDL相关的核心部分是

*_params

构建器、

pdl_request

，以及

parse_person

parse_company

映射器。若要支持其他提供商，只需针对其API实现这些部分，并保持相同的记录字典结构；输入解析、状态逻辑、SQL/标记处理、预演摘要及.xlsx写入逻辑可保持不变。

Principles

原则

Drafts, not advice — output is a research aid for a person to review, not a determination.
Never invent — surface only what PDL returns; mark
```
no_match
```
/
```
needs_review
```
honestly rather than guessing an identity.
Deterministic where it counts — input parsing, status logic, dry-run estimates and
```
.xlsx
```
writing are deterministic.
Honesty and calibration — flag low-confidence matches and show the rough credit cost up front.
Workspace hygiene — write outputs where the user expects; never write the API key to disk in the skill.

仅作研究参考，非建议 —— 输出内容仅供用户审核的研究辅助工具，而非确定性结论。
绝不编造信息 —— 仅展示PDL返回的内容；如实标记
```
no_match
```
/
```
needs_review
```
，而非猜测身份。
关键逻辑确定性 —— 输入解析、状态逻辑、预演估算及.xlsx写入逻辑均为确定性的。
诚实与校准 —— 标记低置信度匹配结果，并提前告知大致积分成本。
工作区规范 —— 将输出写入用户预期的位置；绝不将API密钥写入技能的磁盘文件中。

Data handling

数据处理

PDL is a third party and enrichment sends the real name/company to it — it cannot be tokenised, because the name is the lookup. Treat the

.env

PDL_API_KEY

as a secret: never print, commit or upload it. For people, confirm a legitimate and proportionate purpose and collect only fields relevant to that purpose.

PDL是第三方服务商，信息丰富操作会将真实姓名/公司名称发送给它 —— 无法进行令牌化处理，因为姓名本身就是查询依据。将

.env

PDL_API_KEY

视为机密：绝不打印、提交或上传。对于人员数据，需确认用途合法合理，且仅收集与该用途相关的字段。

Pitfalls

常见陷阱

Free plan hides contact values — emails/phones come back as booleans; read the status columns.
Search cost scales with
--size
— quote the rough credit cost and keep
```
--size
```
modest.
Common names mis-match — raise
```
--min-likelihood
```
or add context columns (company/email).
Never commit
.env
— the key is a secret;
```
--self-test
```
and
```
--dry-run
```
need no key.
Dry-run is an estimate — actual billing follows PDL's endpoint terms and returned records/matches.

免费版隐藏联系信息具体值 —— 邮箱/电话仅返回布尔值；需查看状态列。
搜索成本随
--size
增加 —— 告知大致积分成本，并保持
```
--size
```
参数值适中。
常见姓名易匹配错误 —— 提高
```
--min-likelihood
```
值或添加上下文列（公司/邮箱）。
绝不要提交
.env
文件 —— 密钥是机密；
```
--self-test
```
和
```
--dry-run
```
模式无需密钥。
预演模式仅为估算 —— 实际计费遵循PDL的端点条款及返回的记录/匹配项数量。

Verification checklist

验证清单

Legitimate, proportionate purpose confirmed for any person enrichment/search.
```
--dry-run
```
used for large files or searches to validate scope and estimate credits.
```
PDL_API_KEY
```
available via env or
```
.env
```
for live runs (never written into the skill).
Rough credit cost stated before any large search.
Amber/red status rows flagged to the user.
```
.env
```
not printed/committed.

确认任何人员信息丰富/搜索的用途合法合理。
处理大文件或执行大规模搜索时，使用
```
--dry-run
```
验证范围并估算积分消耗。
实时运行时，通过环境变量或
```
.env
```
文件提供
```
PDL_API_KEY
```
（绝不写入技能中）。
大规模搜索前告知大致积分成本。
向用户指出黄色/红色状态行。
未打印/提交
```
.env
```
文件。

Requirements

环境要求

Python 3.8+
```
pip install openpyxl
```
(HTTP uses the stdlib
```
urllib
```
— no
```
requests
```
needed)
```
PDL_API_KEY
```
(env var or
```
.env
```
) for live API calls; get one at https://www.peopledatalabs.com
Network access to the PDL API.
```
--self-test
```
and
```
--dry-run
```
run fully offline.

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