规则与自定义上下文

## 上下文索引

### 表说明

databases/.../table=<表名>/ 中可以查阅：

- columns.md：字段名称、类型和说明。
  编写 SQL 前读取。
- profiling.md：去重后的取值数量、最小值、最大值等统计。
  部分字段还包含 top_values，列出常见取值及其出现次数。
  编写筛选条件前读取，确认实际取值。

### 代码仓库

- repos/dbt/：dbt 项目。
  模型和字段说明见 models/silver.yml。
  业务判断及其依据见 models/silver/*_ANALYTICS_DECISIONS.md。
  语义模型和指标的源定义见 models/silver_semantic_layer.yml。

### 文档

- docs/crm.md：销售阶段、客户状态和商机含义。
  回答销售问题前读取。

### 语义层

- semantics/metrics/：已同步的指标定义。
  使用指标前读取，再通过 execute_semantic_query 查询，
  不另写原始表 SQL 重算同一个指标。

## 图表规范

### 品牌配色

- 单系列使用主色 #2B2BFF。
- 多系列依次使用 #2B2BFF、#12B981、#F59E0B。
- 超过六个系列时，使用这些颜色的深浅变化。
- 为系列显式指定颜色，不改用图表库的默认配色。

### 含义配色

- 改善或有利变化使用 #12B981。
- 恶化或不利变化使用 #EF4444。
- 先判断指标含义；成本下降与收入下降的含义不同。

# Agent 规则

## 回复语气

- 保持专业、简洁、友好。
- 解释结论的依据和分析过程。
- 使用假设时，明确说明假设是什么。
- 适当提出相关的后续问题。

## 与业务用户交流

### 分析前澄清

开始分析前，如果以下信息不明确，先向用户确认：

- **时间范围**：“要分析哪个时间段？”
  例如最近 7 天、当月累计、今年累计或指定日期。
- **地区范围**：“要查看哪些地区或国家？”
  例如全部地区或特定市场。
- **客户群体**：“要分析哪类客户？”
  例如全部客户、企业客户（B2B）或个人客户（B2C）。
- **指标定义**：“这个指标采用哪一种定义？”
  存在多种定义时，先确认使用哪一种。
- **时间粒度**：“按天、周还是月展示？”

### 回答结构

每次分析都按以下顺序组织回答：

1. **先给结论**：开头直接说明主要发现。
2. **提供数据**：展示支持结论的数字或图表。
3. **补充比较**：与上一周期、目标或其他相关基准比较。
4. **核对结果**：用已知基准验证结果是否合理。
5. **说明限制**：指出数据质量问题和其他影响结论的限制。

### 结果核对

展示结果前，检查：

- 数值的数量级是否符合预期。
- 按不同方式汇总时，总量是否一致。
- 是否与参考表一致，例如 monthly_kpi_summary 月度指标汇总表。
- 是否明显偏离历史趋势；存在偏差时，在回答中指出。

### 后续问题建议

回答后，按当前分析提出相关的后续问题：

- **进一步细分**：“需要按地区拆分看看吗？”
- **相关指标**：“是否也要看看留存率？”
- **趋势分析**：“需要看看这个指标随时间的变化吗？”

## SQL 编写规范

- 显式写出 JOIN。
- 使用有明确含义的表别名，例如 users 用 u，orders 用 o。
- 使用缩进和换行，保持 SQL 易读。
- 查询加上 LIMIT，限制返回行数。
- 优先使用公共表表达式（CTE），避免复杂的嵌套子查询。

## 数据访问

- 只查询正式表，排除 *_test、*_staging 等测试表和暂存表。
- 未指定时间范围时，默认查询最近 30 天。
- 每次查询最多返回 10,000 行。

## 隐私与安全

- 不展示完整的邮箱地址或电话号码。
- 查询涉及个人身份信息（PII）时，明确标注。
- 尽可能汇总个人数据，避免直接展示个人明细。

## 上下文引用

需要某个主题的详细说明时，读取对应文件：

- **营销问题**：读取 docs/marketing.md。
- **财务问题**：读取 docs/finance.md。
- **产品问题**：读取 docs/product.md。

这些文件包含：

- 详细的业务定义。
- 指标计算方式。
- 数据质量注意事项。
- 特定主题的规则。

my-project/
├── RULES.md          # 每次消息加载的共同规则与文件引用
└── docs/
    ├── marketing.md  # 营销问题需要的定义与规则
    ├── finance.md    # 财务问题需要的定义与规则
    └── product.md    # 产品问题需要的定义与规则

# 营销

## 业务定义

### 客户生命周期

- 线索客户：留有有效邮箱，尚未创建账号。
- 潜在客户：已创建账号，尚无购买记录。
- 购买客户：至少完成过一次购买。
- 活跃客户：最近 90 天内有购买记录。
- 流失客户：连续 180 天及以上没有活动，且不存在有效订阅。

### 活动类型

- 获客：吸引线索客户与潜在客户。
- 留存：面向已有客户。
- 召回：重新触达流失客户。
- 增购：面向有扩展购买需求的客户。

## SQL 指标定义

### 客户获取成本（CAC）

计算方式：获客活动总支出 / 获取客户数。

- campaigns 表中每个活动一行，marketing_spend 记录活动支出。
- customers.acquisition_campaign_id 记录客户来自哪个活动。
- 客户在活动开始至结束后 30 天内创建账号，计入该活动的获客客户。
- 以下查询使用 PostgreSQL 语法；没有获取客户时，CAC 返回空值。

```sql
WITH acquisition AS (
  SELECT campaign_id, start_date, end_date, marketing_spend
  FROM campaigns
  WHERE campaign_type = 'acquisition'
), spend AS (
  SELECT SUM(marketing_spend) AS amount FROM acquisition
), acquired AS (
  SELECT COUNT(DISTINCT cu.customer_id) AS customer_count
  FROM acquisition c
  JOIN customers cu ON cu.acquisition_campaign_id = c.campaign_id
  WHERE cu.created_at >= c.start_date
    AND cu.created_at < c.end_date + INTERVAL '30 days'
)
SELECT spend.amount::numeric / NULLIF(acquired.customer_count, 0) AS cac
FROM spend CROSS JOIN acquired;
```

my-project/
├── RULES.md
└── docs/
    ├── marketing.md
    ├── finance.md
    ├── product.md
    ├── reports.md
    ├── data-quality.md
    └── queries/
        └── acquisition-cost.sql