认识 Context
理解上下文怎样把数据结构、业务定义和分析方法连接起来，以及如何持续维护它。
Context（上下文）包含 Agent 分析时需要的表结构、指标定义、文档和规则。它帮助 Agent 找到正确的数据，并理解团队的业务口径。
例如，“新增客户”可能按注册时间，也可能按首次购买时间计算。把定义写入上下文后，团队就不必在每次提问时重复说明。
用文件系统组织上下文
Cappy 使用文件系统来组织上下文：表结构、文档和规则按目录存放在项目中，Agent 按需查找和读取。团队可以直接查看、编辑这些内容，了解 Agent 能使用哪些信息。
先在 Web 创建项目并克隆仓库，再通过 CLI 初始化上下文、同步数据库与语义层；代码和业务文档作为项目文件加入。下面的 my-project 表示本地项目文件夹：
my-project/
├── config.yaml
├── RULES.md
├── databases/
├── repos/
├── docs/
├── semantics/
└── agent/
├── skills/
└── mcps/| 位置 | 内容 |
|---|---|
config.yaml | 数据库与可选的语义层配置 |
RULES.md | 通用约定与相关上下文文件的路径 |
databases/ | 同步的表结构与选定的元数据 |
repos/ | 手动选入项目的 dbt 模型、SQL 与文档 |
docs/ | 业务说明、指标定义与示例 |
semantics/ | 配置语义层后同步的指标与维度 |
agent/skills/、agent/mcps/ | 可复用的分析方法与外部工具连接 |
repos/ 是本文存放代码材料的约定目录，可按需创建；数据库与语义层目录在配置并同步后才有内容。人工编写的文档与生成文件分开维护，避免下次同步覆盖已有说明。
Agent 如何使用上下文
Agent 会读取项目根目录的 RULES.md，了解项目的分析规则，再根据问题查找和读取相关文件。
例如，回答“上个月的销售额是多少？”时，它可以按以下步骤使用上下文：
- 查找销售额的定义：读取
docs/中的指标说明，确认销售额按下单金额还是实付金额计算、是否扣除退款，以及按哪个日期统计。 - 查看相关表结构：读取
databases/中的订单表说明，找到金额、日期和订单状态等字段；如果需要关联退款表，再查看两张表的关联字段。 - 执行查询并回答：根据指标定义和表结构生成 SQL，连接数据库查询上个月的数据，再用查询结果回答，并说明采用的统计口径。
cappy sync 更新数据库与语义层的生成文件；代码仓库材料、业务说明和规则由团队直接维护。修改后，按项目更新流程让 Agent 使用最新文件。
添加上下文
按项目需要添加数据库、仓库、语义层和自定义文档：