For AI agents: the complete documentation index is available at https://devcodex-labs.github.io/capability-graph/llms.txt, the full documentation bundle is available at https://devcodex-labs.github.io/capability-graph/llms-full.txt, and this page is available as Markdown at https://devcodex-labs.github.io/capability-graph/troubleshooting/revision-and-reload.md.

修订、预算与分页

收到 CG_REVISION_MISMATCH 时:

  1. 重新调用 listCatalog()getProvider() 获取当前 Static Revision。
  2. 丢弃绑定旧修订的游标和缓存详情。
  3. 用新修订重新执行本次发现流程。

refreshFailed: true 不表示当前响应为空;它表示最近 reload 失败,但 servedFrom 指明的视图仍可读。查看 reload() 的逐 Provider 错误并修复来源。

Core 只保留 current 和 previous。更旧修订无法恢复。指定修订查询要求有效范围恰好一个 Provider;多 Provider 配合单 revision 会被拒绝。

不要在 reload 期间修改已打开数据库 read view 的记录;这会违反稳定快照合同。

预算与分页

收到 CG_BUDGET_EXCEEDED 时,优先:

  1. 缩小 Provider scope、ID 列表、关系 kinds 或 knowledgeIds;
  2. 降低单页 limit 并使用 nextCursor
  3. 只在业务确实需要时调整 budgets,不要无限放大;
  4. 检查单项 description、facts、association 或 cursor 是否异常过大。

truncated 使用游标续页;partial 同时检查 warnings 和逐项失败。邻居各关系组独立续页,只重试仍有游标的组。

游标必须保留原范围、过滤、limit 和修订。公开游标超过 32,768 字符不会被返回;提高页字节预算不能绕过此上限。