项目配置
设置项目能力、环境变量与已保存提示词，通过对话回放检查分析过程。
项目管理员可以为每个项目设置可用能力、运行时使用的环境变量和常用提问，并通过对话回放检查团队的分析过程。先切换到需要配置的项目，再打开项目设置；这些设置只影响当前项目。
成员与组、模型供应商、后台任务模型和语音输入的入口见组织设置。
项目能力
打开项目设置 → 能力，选择 Agent 可以使用的功能。主要选项如下：
| 选项 | 用途与使用条件 |
|---|---|
| 地图 | 允许 Agent 将地理数据展示为地图，默认开启。需要按地区着色时，可在边界库中添加对应的区域边界。 |
| 语义层 | 决定 Agent 如何使用已接入的 dbt MetricFlow 指标。需要先在项目中配置并同步语义层，才能选择模式。 |
| Python 沙箱 | 提供 execute_python，用于在受限的 Python 环境中计算和处理数据，默认关闭。 |
| Python 执行时长 | 限制单次 execute_python 的运行时间，单位为秒；默认 30 秒，可设置为 1–600 秒。超过时限会停止执行。 |
| 沙箱环境 | 提供 execute_sandboxed_code，允许在隔离环境中运行 Python 或 shell、安装所需包并处理文件，默认关闭。 |
| 危险的写入权限 | 默认关闭，Agent 只允许发起只读 SQL。开启后可发起 INSERT、UPDATE、DELETE 和 DDL 等操作，执行范围仍受数据库账号权限限制。 |
Python 沙箱与沙箱环境是两项独立能力：前者适合受限环境内的计算，后者用于需要额外包或 shell 的任务。实例不支持相应运行环境时，开关会不可用；仅打开开关不会补齐实例缺少的运行环境。
语义层默认使用优先使用语义层：已定义的指标优先通过语义查询回答，其他问题可以使用 SQL。也可以选择仅使用语义层或不使用语义层，具体行为见语义层。
能力修改会自动保存。新建对话并提出对应任务，可以检查 Agent 是否使用预期工具。内置工具与扩展方式见工具与技能。
环境变量
项目文件可以通过变量名引用数据库密码、MCP 令牌或其他配置值，实际值保存在运行环境中。这样，同一份项目配置可以在不同环境中使用不同凭据。
Cappy 会从 config.yaml 和 agent/mcps/*.json 中提取变量名，并在项目设置 → 环境变量中列出。先在文件中添加引用，再到页面填写对应的值。
在配置文件中引用变量
数据库配置使用 {{ env('变量名') }}。例如，在已有连接中将密码字段改为：
password: {{ env('DB_PASSWORD_YAML') }}MCP JSON 使用 ${变量名}。例如，headers 中的静态令牌可以写成：
{
"Authorization": "Bearer ${METABASE_MCP_TOKEN}"
}让运行项目取得配置文件
在本地工作副本中保存配置，提交并推送到项目仓库，再按更新上下文确认实例已经同步到该提交。
打开项目设置 → 环境变量，应能看到文件中引用的 DB_PASSWORD_YAML 或 METABASE_MCP_TOKEN。变量没有出现时，检查引用语法，以及更新的是否为当前项目使用的文件。
在自己的终端中执行 cappy sync 或 cappy debug 时，需要在该终端中提供相应变量，例如：
export DB_PASSWORD_YAML='"your-database-password"'
cappy debug项目设置中保存的值不会自动写回本地终端。终端中的 export 也不会自动为独立运行的 Cappy 实例填写项目环境变量。
已保存提示词
已保存提示词是团队可重复使用的提问。管理员为它填写标题、正文与适用范围；成员在新对话中选择后，可以调整日期、对象等内容再发送。
创建常用提问
打开项目设置 → 已保存提示词，点击新建提示词。例如：
| 字段 | 示例 |
|---|---|
| 标题 | 每月销售趋势 |
| 正文 | 统计上个月各地区的销售额，与前一个月比较，展示趋势并说明变化最大的地区。 |
| 适用范围 | 业务数据 |
正文直接描述需要完成的分析。团队共用的销售额定义仍维护在上下文中，提示词引用既有定义即可。
选择适用范围并保存
| 适用范围 | 提示词用于哪里 |
|---|---|
| 业务数据 | 普通对话，用于分析项目接入的数据。 |
| Admin（应用数据） | 管理员分析 Cappy 应用数据的对话，例如检查使用情况和工具错误。 |
普通业务提问选择业务数据。如果保存的是“本周哪些工具调用报错最多？”等应用使用问题，选择 Admin（应用数据）。适用范围决定提示词在哪种模式下展示，不会赋予使用者额外权限。
填写完成后点击保存。
在新对话中使用
回到当前项目的新对话页面，在提示词建议中选择刚保存的标题。正文会填入输入框；按本次需要修改时间或分析对象，再发送。
例如，把“上个月”改成“今年第一季度”，其余分析要求可以继续复用。修改输入框中的文字只影响本次提问；要更新团队共用版本，回到已保存提示词中编辑并保存。
提示词适合保存常用问题；需要复用一套多步分析方法时，可以编写技能。
对话回放
项目管理员可以通过项目设置 → 对话回放查看当前项目中成员的历史对话，包括提问、回复、SQL、工具调用和用户反馈。回放展示已保存的分析过程，不会重新运行 Agent 或查询。
例如，成员给某次分析点了负面反馈，可以从回放中找到对应回复，检查问题是否出在指标理解、查询条件或工具执行上。
