BesChannels Legacy Data Cleaning
3.0 客户资料入口（新增，不替代下方原有流程）
当客户不知道要提供什么资料时，先使用选择题，不要求客户先写长说明：
请选择本次处理类型（可多选）：
A. 新增导入
B. 更新已有数据
C. 导入失败文件复盘
D. 新增和更新混合
E. 只检查文件，不生成导入文件
请选择目标对象：
1. 市场线索
2. 公司/客户
3. 联系人
4. 自定义对象
5. 不确定，请根据文件识别
请选择处理方式：
① 只修复确定的问题，疑难值列出复核（推荐）
② 尽量自动映射选项值，疑难值列出复核
③ 只生成诊断报告，不改数据
部分选项缺失时，对象先识别，处理方式默认 ①；不得替客户决定删除、合并、覆盖或把更新转成新增。
按场景索取资料
A 新增导入
[必选] 待导入 CSV/Excel
[建议] 目标对象字段定义表（字段显示名、字段名称、字段类型、是否必填、选项值）
[有失败记录时] 最近一次导入失败回执
B 更新已有数据
[必选] 待更新文件
[必选] 目标对象全量导出（至少包含系统记录 ID、LeadID/企业名称/手机号/邮箱等身份字段）
[建议] 目标对象字段定义表
[有失败记录时] 导入失败回执
更新任务必须同时拿到“待更新文件 + 目标对象全量基线”。没有全量基线时状态为 blocked，只返回缺失资料卡片，不生成覆盖式更新文件。客户可选择：
匹配优先级：
1. 系统记录 ID/LeadID 2. 手机号 3. 邮箱 4. 企业名称 5. 按以上顺序自动匹配（推荐）
匹配不到原记录：
① 单列为待新建/待确认，不自动导入（推荐）
② 跳过
③ 另生成新增文件
C 导入失败复盘
[必选] 导入失败回执 CSV/Excel
[建议] 原始待导入文件
[建议] 目标对象字段定义表
[错误包含“数据不存在更新失败”时必选] 目标对象全量导出
失败原因包含“数据选项值不存在”时自动要求字段定义表；包含“数据格式错误”时自动进入格式诊断；包含“数据不存在更新失败”时自动切换到更新资料门禁。
D 新增和更新混合
[必选] 原始数据文件
[必选] 目标对象全量导出
[建议] 字段定义表
[有失败记录时] 失败回执
混合任务必须拆成 可更新文件、可新增文件、匹配冲突文件、字段复核文件，不得合并成一个不透明的导入文件。
字段定义表门禁
出现 Radio、Select、CheckBox、Option、OptIn、CustomerStatus、产品归属部门、采购计划、Vertical Market、Market Segment，或失败原因为“数据选项值不存在”时，优先读取对象字段定义表。至少需要：字段显示名称、字段名称、字段类型、导入时必填、选项值。
使用字段显示名称作为客户导入表头；内部字段名称只用于审计和映射。只有精确匹配或客户确认的同义映射才可自动修复；多个候选、语义变化、空值含义不明和 CheckBox 分隔符合并规则必须进入复核。不要直接把 Yes/Y/1、中英文名称或历史选项值视为等价。
字段定义表的客户获取指引
客户不知道“对象字段定义表”是什么或在哪里导出时，直接发送以下说明，不要求客户自行猜菜单名称：
凡是本 Skill 向客户索取字段定义表，必须同时附上下面的后台路径；不能只说“请提供字段定义表”。
请在致趣后台导出对应对象的字段定义表：
1. 进入「系统设置」
2. 进入「数据管理」
3. 进入「字段」
4. 在「选择对象」中选择要处理的对象，例如「市场线索」
5. 点击右上角「导出全部字段」
6. 将导出的 CSV/Excel 文件发回
字段定义表应包含字段显示名称、字段名称、字段类型、是否必填和选项值。涉及 OptIn、客户状态、产品归属部门、采购计划等字段时，必须优先获取这张表。截图中的菜单路径为依据；若客户后台名称略有差异，要求提供同一“对象字段配置/全部字段导出”结果，不凭菜单文字差异判定失败。
文件角色识别门禁
收到附件后，先检查表头和内容，判断它是：
A. 待导入/待更新的业务数据
B. 对象字段定义表
C. 导入失败回执
D. 不确定，需要客户选择
若表头包含 字段显示名称、字段名称、字段类型、字段分组显示名称、字段分组名称、导入时必填、选项值，优先判定为字段定义表。此时不要默认按新增或更新处理，应先询问：
这份文件看起来是“市场线索”的字段定义表，不是待导入数据。请选择：
A. 另外提供要清洗的市场线索数据
B. 只把它作为字段和选项校验表
C. 两者都处理
只有客户确认后，才进入原有确认卡片和清洗流程。文件角色未确认时，不生成导入文件。
3.0 输出增量
除原有标准输出外，按场景补充：
资料需求卡片.md
更新匹配结果.csv
可新增记录.csv
字段定义比对.csv
更新匹配结果.csv 至少记录身份字段、匹配键、匹配状态（唯一/未找到/多条）、基线行标识和后续动作。原有“确认卡片”、源文件哈希、字段级审计、探测、验证、状态和停止条件全部继续有效。
Key-contact website source extension
When the customer names a target organization, department, institute, lab, or person, this Skill also supports a separate contact-evidence pass:
- Search the supplied official website's institute/department page first, then target-person, assistant, institute-leader, same-institute PI, and shared-platform pages.
- Keep website-derived contacts in a separate evidence sheet from current CDP and historical imported records. Every delivered website row must include
source_urlandevidence_text. - Treat official website contacts as a first-class source, not merely a fallback after CDP search. Distinguish direct target, administrative entrance, institute entrance, same-institute peer, and public-platform entrance.
- Never infer a personal relationship from same-unit membership. Mark current role/contact/relationship for confirmation before outreach.
- Do not create a
建议问法field. Use a neutral推荐动作field such as “先确认关系，再请求转介”; detailed outreach copy belongs outside the contact data table.
Operating Contract
Guide the user through a project-specific cleaning run. Do not behave as a blind universal cleaner. This package follows the shared CLI contract described in cli-aligned-contract.md; it is a standalone cleaning Skill and does not include the CLI runtime or customer credentials.
- Preserve the source file and hash it before work.
- Inspect the actual workbook or CSV with
scripts/inspect_workbook.pywhen supported. - Classify evidence using data-classification.md.
- Return the confirmation card below with actual headers, source-column types, target fields, actions, and wait for confirmation on high-risk decisions.
- Generate or adapt a project-specific cleaning script after confirmation.
- Validate the outputs with
scripts/validate_cleaned_output.pyand the contract in cleaning-contract.md. - For BesChannels-specific fields and import failures, read beschannels-import-contract.md plus only the field references needed.
Do not modify the source, delete rows by default, guess business mappings, or claim an import succeeded from a local validation alone.
Confirmation Card
Reply in Chinese before cleaning:
本次识别到的文件：
表/编码/行列数：
目标系统与对象：
首要身份字段：
来源列 -> 字段类型 -> 处理动作 -> 目标字段：
计划清洗的字段：
不会改动的字段：
拟采用的规则：
需要确认：
预计输出：
Ask only decisions that change the result:
- Confirm the target is BesChannels and name the destination object.
- Confirm the first identity field for this import. Suggest mobile phone only as a default; allow the business object to choose another field.
- Use the target field display name in the import header. Never use an internal field name as a customer-facing import header.
- Confirm whether deduplication is enabled and the exact key.
- Confirm whether
手机号2is processed. - Confirm how duplicate headers map; never collapse them by display name alone.
- Confirm any field mapping, option mapping, row deletion, or merge that lacks direct evidence.
- Confirm whether each date-like source column is
DateorDateTime; do not infer this from the column title alone.
If these decisions are missing, finish the inspection and plan, mark the run blocked, and do not clean.
Workflow
1. Inspect
Run with UTF-8 enabled on Windows:
$env:PYTHONUTF8 = '1'
python scripts/inspect_workbook.py "<INPUT>"
Record source SHA256, sheets, encoding, row/column counts, exact headers, duplicate headers, empty columns, and likely risk fields.
2. Lock The Run
For work expected to exceed 30 minutes or require probes/import feedback, create a run checkpoint with the source manifest, confirmed decisions, planned outputs, current step, and resume command. Never store customer values, credentials, or hidden reasoning in the checkpoint.
3. Clean On A Copy
- Preserve every row unless the user explicitly approves removal or merge.
- Keep unrelated columns byte- or value-equivalent where the writer permits.
- Prefer clearing only the unsafe field over deleting a record or making a weak guess.
- Clean before deduplication; deduplicate only on confirmed, non-empty keys.
- Merge tag/history fields only when the user confirms the delimiter and merge semantics.
- Record every changed field with row identifier, original value, cleaned value, action, reason, rule ID, and confidence.
For date-like columns:
- Keep
DateandDateTimeas separate field types. A date-only value must not be silently given a time, and a timestamp must not be truncated without confirmation. - Preserve the original value in the audit. Mixed formats, Excel serial numbers, impossible calendar values, timezone-bearing values, and ambiguous day/month order go to review until the customer or current importer contract confirms a conversion.
- A valid local parse is not proof that the target importer accepts the serialized value. Probe the exact target object, field type, tenant, and importer version before expanding a date conversion.
- When the current contract confirms a DateTime serialization, record the exact format in the plan and validation result (for example,
yyyy-MM-dd HH:mm:ss); do not generalize it to another object.
When the file resembles the verified four-key lead migration shape, offer but do not enable this template without confirmation: cleaned 手机号 + 邮箱 + 单位 + 微信openid/openid, keep the first row, uniquely merge confirmed history fields, retain the first non-empty value elsewhere, and send conflicting non-empty values to review.
4. Probe Dynamic Contracts
Treat schema, option labels, field types, tenant behavior, and importer versions as dynamic facts. Use a 2-50 row probe that isolates one cause before expanding a rule. Preserve the failure and success receipts.
5. Validate And Package
python scripts/validate_cleaned_output.py "<OUTPUT>" --source "<INPUT>"
python scripts/validate_cleaned_output.py "<OUTPUT.csv>" --encoding gb18030
Require zero unexplained row changes, zero unintended header changes, valid output encoding/line endings, and a field-level audit. Generate the standard artifacts described in cleaning-contract.md.
6. Report Truthfully
Distinguish these outcomes:
planned: inspection and confirmation card are complete; cleaning has not run.blocked: a required decision, source, schema, option, or receipt is missing.completed: local artifacts and validation passed.import_verified: the target system accepted the intended rows and the receipt/readback was verified.
For multi-object or receipt-driven work, also report the finer-grained state when applicable: prepared, locally_validated, imported, readback_verified, partial, or review. A local validation result does not imply an external import or readback.
Never promote completed to import_verified from a script exit code or model statement.
Progressive References
- Read cleaning-contract.md for outputs, audit fields, summary schema, validation, and failure behavior.
- Read data-classification.md before mixing customer evidence, confirmed rules, live system facts, or AI suggestions.
- Read province-city-rules.md for province/city/address work.
- Read email-mobile-rules.md for email, mobile, landline, and
手机号2work. - Read beschannels-import-contract.md for CSV encoding, URL, Address, CheckBox, probes, import receipts, and known cross-case evidence.
Stop Conditions
Stop without expanding a change when the source hash drifts, headers or row counts change unexpectedly, the tenant/object/schema cannot be verified, option labels are ambiguous, duplicate-header mapping is unconfirmed, a probe tests more than one cause, or two consecutive tool/import failures have no new evidence.
Preserve the last valid checkpoint and return the exact missing decision or failed validation.
