| name | hlzd-customer-profile |
| description | B2B 客户 360° 画像 —— 4 层字段模型（基础/交易/行为/画像）+ AI 跟进建议 + AI 客群聚合 + 5 维评级（A/B/C/D）。与 hlzd-customer-due-diligence 互补：due-diligence = 合规粗筛，customer-profile = 深度画像。 |
| license | MIT |
| metadata | {"author":"HLZD (海联智达 / 海良数科)","version":"0.1.0","industry":"cross-border-b2b","category":"customer-profile","triggered_by":["客户画像","客户档案","客户 360","客户标签","客户评级","客户分层","客户运营","客户聚合","客群分析","跟进建议","customer profile","customer 360","customer scoring","account-based marketing","lead nurturing"]} |
HLZD 客户画像 v0.2
v0.2 升级说明（基于 GitHub 调研 6 个开源项目）：
- 借鉴 Tracardi CDP（646 stars）的 4 层字段分类（核心/基础/行为/自定义）
- 借鉴 Twenty CRM（52,256 stars）的字段类型化（enum/decimal/datetime/composite）
- 借鉴 1688 客户运营（837 stars）的 AI 客群聚合 + 跟进建议生成
- 保留 v0.1 的 5 层 25 项业务维度（基础/需求/痛点/偏好/分层）
定位
| 对比项 | 通用工具（CRM/Excel） | HLZD-客户画像 v0.2 |
|---|
| 字段模型 | flat 字段表 | 4 层分类（核心/基础/行为/自定义，借鉴 Tracardi） |
| 字段类型 | 字符串混杂 | 类型化（enum/decimal/datetime/composite，借鉴 Twenty） |
| 客户分群 | 人工分类 | AI 自动客群聚合（借鉴 1688） |
| 跟进建议 | 经验主义 | AI 跟进建议生成（借鉴 1688） |
| 多维度评分 | 单一分数 | 7 维度加权评分（v0.1） |
| 跨 skill 共享 | 各 skill 自定义 | 统一 schema + SQLite（v0.1） |
核心原则：客户画像不是"数据库表"，是"业务员和 AI 协同决策的事实源"。
数据源借鉴（GitHub 调研）
| 借鉴项目 | Stars | 借鉴内容 |
|---|
| Tracardi/tracardi | 646 | 4 层字段分类（核心/基础/行为/自定义）+ PII 哈希 |
| Twenty/twentyhq | 52,256 | 字段类型化（Address/Email/Phone/FullName/Currency） |
| 1688-customer-opportunity | 837 | AI 客群分类 + 跟进建议 + 客户机会监控 |
| PostHog/posthog | 35,350 | 单一栈整合 + Feature Flag |
| Frappe/crm | 2,924 | 完整业务实体设计 |
| Monica | 24,837 | 简单关系模型 |
v0.2 核心架构 — 4 层字段模型（借鉴 Tracardi）
字段分类总览
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: 核心标识 (Core Identity) │
│ - customer_id (主键) │
│ - ids (多 ID 合并列表) │
│ - metadata (created_at / updated_at / confidence) │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: 基础档案 (Basic Profile) │
│ - 公司信息 / 联系人 / 工商信息 │
│ - 借鉴 Tracardi 的 `data` 字段 │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: 行为画像 (Behavioral) │
│ - stats: 订单/询盘/响应次数 │
│ - interests: 兴趣度评分 │
│ - preferences: 偏好 │
│ - pain_points: 痛点 │
│ - 借鉴 Tracardi 的 `stats/interests/consents` │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: 业务自定义 (Custom) │
│ - tier: 分层评级 │
│ - traits: HLZD 自定义属性 │
│ - tags: 多维度标签 │
│ - aux: 辅助数据（授权状态） │
│ - 借鉴 Tracardi 的 `traits/aux/trash` │
└─────────────────────────────────────────────────────────────┘
完整 schema v0.2（借鉴 Tracardi + Twenty）
customer_persona_schema_v2:
customer_id:
type: uuid
primary_key: true
description: "客户唯一标识"
ids:
type: list[string]
description: "多 ID 合并列表（邮箱哈希/电话哈希/工商注册号/海关编码）"
created_at:
type: datetime
updated_at:
type: datetime
updated_by:
type: enum[string]
options: ["业务员手动", "AI 自动推断", "客户主动更新"]
default: "AI 自动推断"
confidence:
type: float
range: [0.0, 1.0]
description: "画像可信度（初始低，每次互动 +0.05，最高 0.95，业务员确认 = 1.0）"
basic:
company_name_cn:
type: string
description: "公司中文名"
company_name_en:
type: string
description: "公司英文名"
[, , , , , , , ]
[, , , , ]
[, ]
v0.2 新增 — AI 跟进建议生成（借鉴 1688 客户运营）
scripts/generate_followup_advice.py
"""
借鉴 1688-customer-opportunity 项目的"买家成交机会"功能
输入: 客户画像
输出: 3-5 条跟进建议
"""
from customer_persona import Persona
def generate_followup_advice(customer_id: str) -> list[dict]:
persona = load_persona(customer_id)
advice_list = []
last_contact = persona.stats.last_contact_date
days_since = (now() - last_contact).days
if days_since > 7:
advice_list.append({
"type": "TIMING",
"priority": "HIGH",
"advice": f"客户上次联系是 {days_since} 天前，建议 24h 内主动联系",
})
quote_tier_map = {
"VIP": "最高档 + 特别折扣",
"A": "标准档 + 阶梯折扣",
"B": "标准档",
"C": "基础档",
}
advice_list.append({
"type": "QUOTE_TIER",
"priority": "HIGH",
"advice": f"客户等级 {persona.tier.grade}，建议报价档位: {quote_tier_map[persona.tier.grade]}",
})
advice_list.append({
"type": "COMMUNICATION",
"priority": "MEDIUM",
"advice": f"客户偏好 {persona.preferences.communication.channel} + "
f"，"
,
})
advice_list.append({
: ,
: ,
:
,
})
persona.preferences.cultural.holidays:
advice_list.append({
: ,
: ,
: ,
})
advice_list
v0.2 新增 — AI 客群聚合（借鉴 1688 客群列表）
scripts/aggregate_segments.py
"""
借鉴 1688-customer-opportunity 项目的"AI 客群列表"功能
输入: 所有客户画像
输出: 按维度聚合的客户群体洞察
"""
from collections import defaultdict
from customer_persona import list_all_personas
def aggregate_segments() -> dict:
"""按国家/行业/客户等级聚合客户"""
personas = list_all_personas()
segments = defaultdict(lambda: {
"count": 0,
"common_traits": [],
"common_pain_points": [],
"common_preferences": [],
"avg_order_amount_usd": 0,
"conversion_rate": 0,
"total_orders": 0,
})
for p in personas:
country = p.basic.country
segments[country]["count"] += 1
for seg_key, seg in segments.items():
seg["common_traits"] = find_common(seg["members"], field="traits")
seg["common_pain_points"] = find_common(seg["members"], field="pain_points")
seg["common_preferences"] = find_common(seg["members"], field="preferences")
return dict(segments)
客群聚合示例输出
中东客户群体:
客户数: 23
共性特征:
- 普遍要 DAP 报价
- 偏好 30% TT + 70% LC at sight
- 节日: 开斋节（Ramadan 后 1 周）
- 忌讳: 政治话题
平均订单金额: 45000 USD
成交率: 68%
建议话术: "强调 INCOTERMS DAP 和发货前 SGS 检验"
俄罗斯客户群体:
客户数: 8
共性特征:
- 因制裁偏好中欧班列运输
- 偏好 EXW 报价（避免俄罗斯清关风险）
- 关注银行制裁风险
平均订单金额: 32000 USD
成交率: 45% (制裁导致拒付率高)
建议话术: "提示客户走欧洲银行保兑"
评级算法 v0.2（保留 v0.1）
def calculate_score_v2(persona) -> int:
"""v0.2 评级算法（保留 v0.1 7 维度加权）"""
score = 0
annual_order = persona.basic.annual_revenue_usd
if annual_order > 1_000_000: score += 30
elif annual_order > 300_000: score += 22
elif annual_order > 100_000: score += 15
elif annual_order > 30_000: score += 8
else: score += 3
years = (now() - persona.basic.first_contact_date).days / 365
score += min(int(years * 2), 10)
score += int(persona.stats.payment_on_time_rate * 15)
response_hours = persona.stats.avg_response_time_hours
if response_hours < 24: score += 10
elif response_hours < 72: score += 6
else: score += 3
growth = persona.aux.get("growth_trend", 0)
if growth >= 0.5: score += 15
elif growth >= 0: score += 8
: score +=
persona.tier.tags persona.tier.tags:
score +=
persona.tier.tags persona.tier.tags:
score +=
referral_count = persona.aux.get(, )
score += (referral_count * , )
(score, )
scripts/ 设计 v0.2
scripts/
├── schema.py # schema 定义（借鉴 Tracardi 4 层）
├── database.py # SQLite + 统一 schema
├── crud_persona.py # 增删改查
├── grade_customer.py # 7 维度加权评分（保留 v0.1）
├── generate_followup_advice.py # ⭐ v0.2 新增: AI 跟进建议（借鉴 1688）
├── aggregate_segments.py # ⭐ v0.2 新增: AI 客群聚合（借鉴 1688）
├── cross_validate_quote.py # 关联 HLZD-智能报价
├── cross_validate_inquiry.py # 关联 HLZD-询盘响应
├── cross_validate_shipment.py # 关联 HLZD-物流装箱
├── cross_validate_lc.py # 关联 HLZD-信用证审单
├── search_history.py # 客户历史搜索
└── orchestrator.py # 主调度
references/ 设计 v0.2
references/
├── schema_specification.md # 完整 schema 规范（借鉴 Tracardi）
├── field_types.md # 字段类型定义（借鉴 Twenty）
├── followup_advice_playbook.md # 跟进建议规则库（借鉴 1688）
├── segment_patterns.md # 客群聚合模式（借鉴 1688）
├── tier_definitions.md # 分层评级标准
├── cultural_calendar.md # 文化日历（俄罗斯/中东/拉美节日）
├── banned_countries.md # 制裁名单
└── examples/
├── case_vip_customer.md # VIP 客户画像完整样例
├── case_segment_middle_east.md # 中东客户群体洞察样例
├── case_followup_advice.md # 跟进建议样例
└── case_cross_skill_query.md # 跨 skill 查询样例
错误地图
更多细节
完整设计文档（v0.1.x 实现细节 + 错误地图 + 性能目标）见 references/deep-dive.md。
