构建项目

在 Web 中创建项目复制锚点链接

在创建内建项目卡片中输入项目名创建项目，成功后页面会显示克隆命令，仓库地址和后续步骤。

新仓库自带 config.yaml，初始内容为：

databases: []

获取密钥并克隆仓库复制锚点链接

在个人设置中获取 API 密钥，用于访问 Cappy 项目仓库。

将下面的 <PROJECT_REPOSITORY_URL> 替换为项目页面提供的地址：

git clone '<PROJECT_REPOSITORY_URL>' my-project
cd my-project

git clone 询问用户名和密码时，用户名可以填写自己的邮箱，密码填写 Cappy API 密钥。

初始化本地上下文复制锚点链接

cappy init 用于配置数据库连接，并生成项目的上下文文件。在克隆的项目目录中运行：

cappy init

填写数据库连接

Set up database connections?
> y

Select database type:
> Doris

以 Doris 为例，按提示填写连接信息。

其他数据库的连接字段见接入数据库。

确认生成结果

初始化把连接写入 config.yaml，并生成下面的文件和目录。数据库依赖就绪时，初始化还会检查连接。

my-project/
├── config.yaml
├── RULES.md
├── .cappyignore
├── docs/
├── databases/
├── semantics/
├── agent/
│   ├── mcps/
│   ├── skills/
│   ├── tools/
│   └── prompts/
└── tests/
    ├── config.yaml
    └── example.yml

已有本地上下文时，也可以把配置、规则、文档等复制到这个克隆目录。保留克隆目录自己的 .git，沿用新项目的仓库历史。

需要添加其他数据库连接时，再次运行 cappy init，在 Add more database connections? 处选择 y。修改已有连接时，直接编辑 config.yaml。已有非空的规则和其他上下文文件会保留。

准备仓库和访问令牌复制锚点链接

在 GitHub 仓库根目录放入 config.yaml、RULES.md 和其他上下文文件。准备一个能读取该仓库的 GitHub 访问令牌。

填写并导入复制锚点链接

打开添加项目 → 从 GitHub 导入，填写以下信息。

点击导入仓库。成功页面会显示仓库地址和实例上的检出路径。点击进入项目，在上下文中查看文件。

用本机的 GitHub 凭据克隆原仓库，后续修改也推送到该仓库。

git clone https://github.com/owner/my-project.git my-project
cd my-project

配置数据与文档复制锚点链接

1. 在 config.yaml 中，将 Doris 连接的 password 改为环境变量引用。下面沿用前面创建的 warehouse 连接。

   复制代码

   databases:
     - name: warehouse
       type: doris
       host: doris.example.com
       port: 9030
       user: analytics_reader
       password: {{ env('DB_PASSWORD_YAML') }}
       catalog: internal
       database: analytics
       schema_name: analytics
       templates:
         - columns
         - preview

2. 在运行 cappy debug 和 cappy sync 的终端设置 DB_PASSWORD_YAML。换成实际密码时，保留 JSON 字符串的双引号，特殊字符按 JSON 转义。编码方法见接入数据库。

   复制代码

   export DB_PASSWORD_YAML='"your-database-password"'

3. 将业务说明放入 docs/，在 RULES.md 中引用相关文件。需要补充指标定义时，见语义层。规则写法见规则与自定义上下文。

验证连接并生成上下文复制锚点链接

运行以下命令检查数据库连接。

cappy debug

确认 warehouse 显示 Connected 后，再运行同步。

cappy sync

同步完成后，在 databases/ 中查看生成的 columns.md 和 preview.md。配置了语义层时，在 semantics/ 中查看同步产物。

提交并推送修改复制锚点链接

修改数据源或数据库结构后，先验证连接并同步。在本地工作副本中检查改动，暂存后查看差异。

git status --short
git diff
git add .
git diff --staged

确认暂存内容只包含要发布的文件，检查是否混入密码、令牌或本地凭据文件。

在项目设置 → 仓库访问中确认跟踪分支。下面以内建项目的 main 为例。GitHub 项目将命令中的 main 换成导入时跟踪的分支。通过其他分支审阅的修改，合并到跟踪分支后再同步。

git commit -m "Update project context" && git push origin main

让 Cappy 取得最新文件复制锚点链接

打开项目设置 → 仓库访问，点击立即同步，查看页面提示。

• 已拉取最新上下文：运行中的项目已更新到仓库版本。
• 已是最新：实例当前提交与仓库中的跟踪分支一致。

内建仓库收到推送后会立即请求同步。

默认使用手动拉取。需要定期更新时，将拉取方式改为自动拉取并选择间隔。默认每 5 分钟拉取一次。

同步失败时，检查仓库是否可访问、跟踪分支是否正确。GitHub 项目还需检查导入令牌能否读取仓库。

配置实例凭据复制锚点链接

本地终端中的环境变量不会随 Git 推送传到实例。发布含有变量引用的配置后，由项目管理员打开项目设置 → 环境变量，填写并保存相应的值。

例如，本篇配置会列出 DB_PASSWORD_YAML；在实例中也填写 JSON 字符串形式的密码，例如 "your-database-password"，包含双引号。Cappy 实例需要能访问配置中的数据库地址，并取得相应凭据。

在 Web 中分析数据复制锚点链接

打开上下文，确认刚发布的 RULES.md、业务文档和表说明已经出现。新建对话，使用组织已配置的模型；没有可用模型时，请组织管理员按组织设置添加。

先问一个你能核对结果的问题，例如：

analytics 库中有哪些表？请选择一张表查询 5 行数据，并解释各字段的含义。

发送后，展开回复中的 SQL 卡片，核对所用的连接、数据表和返回数据。确认 Agent 能查询自己的数据后，再结合团队的业务定义进行分析。