上下文建议
通过在线评估分析真实对话、错误和反馈，审阅上下文建议，并将修改提交到上下文仓库。
上下文建议（Recommendations）是 Cappy 的在线评估：分析项目的真实使用记录，找出上下文缺失、错误或表达不清的地方，并建议修改哪些文件、怎样修改。它可以发现你在编写测试集时没有预料到的问题。
评估中的 cappy test 则是离线评估，使用你准备的固定问题和参考 SQL 检查结果。两者配合使用：从真实使用中发现问题，修改上下文，再将典型问题加入评估，检查修复效果及是否影响原有回答。
| 离线评估 | 在线评估 | |
|---|---|---|
| 使用方式 | cappy test | 上下文建议 |
| 依据 | 预先编写的问题与参考结果 | 实际对话、工具错误、用户反馈和上下文读取记录 |
| 运行时机 | 发布前、修改上下文或模型后，也可接入 CI | 项目使用后手动运行，或按计划定期运行 |
| 回答的问题 | 这次修改后，已有问题还能正确回答吗？ | 真实使用暴露了哪些上下文问题，应该怎样修改？ |
工作方式
你可以手动启动分析，也可以设置每天、每周或每月运行。分析 Agent 将项目的使用记录与上下文文件对照，生成带有依据和目标文件的建议。
使用记录通过限定在当前项目的只读查询提供给分析 Agent；认证信息等字段不在可查询视图中。分析时可以读取上下文并准备修改草稿，草稿不会直接覆盖项目文件。后续由你审阅并提交，或按配置自动创建 PR。
分析哪些问题
分析 Agent 会查找以下使用记录，并读取相关的 RULES.md、semantics/、databases/、docs/ 和 repos/<name>/ 文件，判断问题应该在哪里修正。
| 记录 | 可以发现的问题 |
|---|---|
| 工具错误 | SQL 或其他工具反复失败，相关表、字段或操作条件可能缺少说明 |
| 负面反馈 | 用户点踩或留下纠正意见，可能暴露回答与业务预期的差异 |
| 重新生成和修正 | 相同问题需要反复重问或手动纠正，可能存在不明确的规则 |
| 未覆盖的问题 | Agent 无法回答，或对相同分析任务采取不一致的做法 |
分析还会考虑读取上下文的成本。文件被截断、频繁读取且每次都消耗较多 Token、或偶尔读取但开销异常高时，建议可能是拆分文件、精简内容，或把重复分析流程整理成技能。
例如，用户反复要求按月展示订单趋势，而 Agent 每次都重新摸索图表格式并执行相同查询，建议可能指出缺少一份报表生成技能；如果查询总是引用不存在的字段，建议则可能要求修正表说明或指标定义。具体诊断需要结合建议引用的对话判断。
建议包含什么
进入 上下文 → 建议 后，可以看到问题分类、诊断说明和触发对话。分类包括工具错误、幻觉、语义缺失、上下文膨胀、技能和其他。
展开建议，结合以下信息审阅：
- 问题及依据：发生了什么，涉及哪些对话、用户反馈或工具错误。点击引用的对话可回看原始问题和执行过程。
- 修改目标：建议修改的文件及修改方向，例如补充
RULES.md的查询条件，或在指标文件中修正定义。 - 修改草稿：能够生成文件修改时，卡片显示“建议更改”。打开后可逐文件查看新增、删除与周围内容。
- 人工修复说明：需要修改生成来源或无法直接提交时，可能显示“如何修复”，提供说明和可复制的提示词。没有文件草稿时，也可以从建议复制提示词继续处理。
建议较多时，可以按分类、触发用户和是否有反馈筛选，并按检测日期、触发对话数或 PR 状态排序。优先审阅影响较多对话、反复出现的问题。
启用并运行分析
开启上下文建议
此功能目前默认关闭。由实例管理员设置以下环境变量，并重启 Cappy 服务：
BETA_CONTEXT_RECOMMENDATIONS_ENABLED=true这是实例的启动配置，不是项目内的提示词或数据库环境变量。项目管理员和具有写入权限的成员可以访问、运行和处理建议。
配置分析模型与运行方式
在 上下文 → 建议 → 配置 中选择分析模型。分析模型属于组织的后台模型设置，需要组织管理员修改；项目内的其他建议配置可以由具有写入权限的成员维护。
首次使用可以保留“关闭（仅手动）”频率，并关闭 YOLO 模式，先查看一次分析结果。
点击立即运行
点击页面上方的 立即运行。运行期间按钮显示“正在运行…”，完成后查看“建议”标签中的结果；页面也会显示最近一次运行时间。运行失败时会显示错误信息。
可以打开运行记录对应的对话查看分析过程。没有新建议只表示本次分析未产出新问题，不等于所有回答都已通过评估。
配置选项
| 选项 | 作用 |
|---|---|
| 分析模型 | 执行上下文分析的模型；由组织管理员设置 |
| 运行频率 | 默认“关闭（仅手动）”；也可选每天、每周一或每月 1 日，按服务器时间 03:00 运行；界面显示换算后的本地时间 |
| 自定义系统提示词指令 | 追加到每次分析的内置指令之后，最多 4,000 个字符 |
| 仓库 | 通过“打开 Git 设置”连接上下文仓库；已连接时可“管理 Git 设置”，并查看配置中的关联仓库 |
| YOLO 模式 | 默认关闭；启用后，分析结束会自动为符合条件的建议创建 PR，并将其标记为已应用 |
| 每次运行的最大拉取请求数 | YOLO 模式下控制自动创建的数量，默认 3，范围 1–10，优先处理影响较大的建议 |
自定义指令可以用来指定分析重点，例如：
重点分析收入指标相关的错误和用户反馈。
检查是否缺少退款、取消订单和时间范围的定义，并指出需要修改的上下文文件。“关闭（仅手动）”只关闭定时运行，仍可以点击“立即运行”。YOLO 模式控制自动创建 PR，不会自动合并 PR，也不会代替你将上下文更新到运行中的项目。
使用建议改进上下文
建议可以用于发现反复失败的查询、处理新反馈，以及整理重复分析流程。处理一条建议时，先打开触发对话，确认问题确实存在，再查看目标文件是否缺少相应定义。模型的诊断也可能不准确。
对于确认需要修改的问题，使用草稿或修复说明完成修改。手动处理完成后点击 标记为已应用；不适用或判断有误的建议点击 忽略。相应记录会移动到“已应用”或“已忽略”标签中。
状态用于跟踪处理进度。标记为已应用不会替你编辑文件、合并 PR 或发布上下文。
将建议提交为 PR
连接 GitHub 或 GitLab 后，建议中的修改可以提交为拉取请求（PR）或合并请求（MR）。只有需要修改的文件能够映射到已连接仓库，并且建议包含修改草稿时，才能直接创建。
连接 Git 账号与上下文仓库
在个人设置中连接 GitHub 或 GitLab 账号，确保账号可以访问目标仓库。然后从建议配置中的 打开 Git 设置 连接项目的上下文仓库；已连接的仓库会显示在配置页。
从其他仓库复制的模型与文档作为上下文仓库中的项目文件维护。需要修改来源时，先更新原仓库，再将修改后的材料加入项目并通过上下文仓库发布。
审阅修改草稿
打开卡片中的 建议更改，检查目标文件、增删内容以及相关上下文。重点确认修改是否修复了触发问题，是否与已有指标和规则冲突。
RULES.md、semantics/ 等人工维护文件可以形成修改草稿；databases/ 中由同步生成的文件，需要按 如何修复 的说明修改其来源，再重新同步。未连接的来源也需要手动处理。
创建并审阅 PR
点击 创建 PR，在 Git 平台上审阅修改并合并。创建成功后，卡片提供 查看 PR 入口，并显示 PR 的后续状态。
合并后，按构建项目中的发布步骤更新运行中的上下文，再运行相关评估。创建 PR 本身不会让修改在 Agent 中生效。
批量处理建议
需要一起处理多条建议时，打开列表中的选择模式，勾选相关卡片。底部操作栏可以将符合条件的修改合并为一个 PR，每条建议形成独立提交，方便审阅。
直接创建 PR 的建议需要包含修改草稿，且尚未关联 PR。一次最多选择 20 条；同一批修改需要属于同一目标仓库和分支。也可以选择 复制提示词，将这些建议交给自己的编码助手处理。