cappy文档
下载

代码仓库与文档

将已有的 dbt 模型、SQL 和业务文档加入项目，通过 Git 发布并维护这些上下文文件。

把团队已有的 dbt 模型、SQL 和文档加入 Cappy 项目，Agent 就能在分析时查阅它们。材料作为项目文件维护，和规则、数据库说明一起通过 Git 发布。

为什么要添加代码仓库

数据库的表结构说明有哪些表和字段，仓库中的代码和文档则能帮助 Agent 理解数据如何生成、如何使用：

  • 查阅 dbt 模型和说明：从模型 SQL 中了解转换、筛选与关联逻辑，从 YAML 中了解字段含义。
  • 参考语义层定义：阅读已有的指标与维度说明。使用 dbt MetricFlow 时，还可以接入语义层，直接查询已定义的指标。
  • 使用内部文档：查阅数据字典、业务口径与查询示例，减少重复编写上下文。

例如，回答收入问题时，Agent 可以先查看收入定义，再读取模型中处理退款和取消订单的 SQL，结合表结构生成查询。查询实际数据仍需配置数据库连接。

将材料加入项目

下面的 my-project 是已从 Cappy 克隆并初始化的项目文件夹；创建过程见构建项目。示例将需要的代码放在 repos/dbt_project/，业务文档放在 docs/。

准备来源文件

在 my-project 的父目录中，用自己的 Git 客户端克隆来源仓库：

git clone https://github.com/your-org/dbt-project.git dbt-source

已有本地副本或文档目录时，可以直接使用。私有仓库使用你自己的 GitHub 或其他 Git 服务认证；访问 Cappy 内建项目的 API 密钥只用于 Cappy 仓库。

假设来源中包含需要的 models/ 和 docs/revenue.md：

workspace/
├── my-project/
│   ├── .git/
│   └── config.yaml
└── dbt-source/
    ├── models/
    │   ├── orders.sql
    │   └── schema.yml
    └── docs/
        └── revenue.md

选择与分析相关的模型和说明即可。普通 dbt 仓库提供的是参考材料；如果仓库本身已经包含完整的 Cappy 配置与上下文，可以使用从 GitHub 导入直接创建项目。

复制需要的目录与文档

仍在上面的 workspace 目录中执行：

mkdir -p my-project/repos/dbt_project my-project/docs
cp -R dbt-source/models my-project/repos/dbt_project/
cp dbt-source/docs/revenue.md my-project/docs/revenue.md

将示例路径换成来源中实际需要的文件。只复制选定的内容，保留 Cappy 项目自己的 .git；来源仓库的 Git 历史无需放入上下文。

复制后，项目中的文件为：

my-project/
├── config.yaml
├── RULES.md
├── repos/
│   └── dbt_project/
│       └── models/
│           ├── orders.sql
│           └── schema.yml
└── docs/
    └── revenue.md

repos/ 是本例组织代码材料的目录，可以按团队习惯调整。当前 config.yaml 配置数据库和语义层；代码与文档直接作为项目文件维护，不配置 repos 来源。cappy sync 不负责拉取或复制这些材料。

.cappyignore 控制 Agent 的文件工具和上下文搜索可以访问的路径，.gitignore 控制哪些本地文件不提交到 Git。需要发布的代码和文档应出现在 Git 提交中。

引用文件并发布

在 my-project/RULES.md 中说明何时读取这些文件：

RULES.md 中的上下文索引
## 订单与收入

- 编写订单查询前，读取 repos/dbt_project/models/schema.yml，
  确认字段含义，并参考 repos/dbt_project/models/orders.sql。
- 回答收入问题前，读取 docs/revenue.md，确认退款、取消订单
  和统计日期的处理方式。

然后进入项目，检查并发布修改：

cd my-project
git status --short
git add RULES.md repos/dbt_project docs/revenue.md
git diff --staged
git commit -m "Add models and business documentation"
git push

按更新上下文确认实例已同步到新提交，在 Web 的上下文中打开模型和文档，核对内容。

Agent 可以用 grep 查找相关定义，再用 read 读取模型和文档。例如收入问题会先读取 docs/revenue.md 的口径，再结合模型与数据库说明生成查询，在对话中展示 SQL 和结果。

更新文件

来源有新提交时，先更新本地来源副本：

git -C dbt-source pull --ff-only

再复制需要更新的模型和文档，检查 Cappy 项目中的 Git 差异并提交、推送。来源删除文件时，也要删除项目中对应的副本；新增或变更的材料按同样方式加入。

让来源仓库维护模型和原始文档，让 Cappy 项目保留选定材料的副本及其 RULES.md 引用。只更新来源仓库，尚不会改变实例中的上下文；还需发布 Cappy 项目的修改。