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/reference/result-meta.md.

结果与控制元数据

可用
字段语义
completenesscompletetruncatedpartial
compositeStaticRevision本次实际 Provider 修订集合的组合身份
staticRevision单 Provider 查询的修订
staticRevisionByProvider多 Provider 查询的修订映射
servedFromcurrentpreviousmixed;多 Provider 查询可混合修订来源
servedFromByProvider多 Provider 查询中每个 Provider 对应 currentprevious
refreshFailed最近刷新失败,但当前返回视图仍可读
scope本次有效 Provider 范围
filter实际应用的查询过滤
view本次使用的能力、Runtime 和知识内容身份
warnings有界非致命诊断
budgets实际相关的预算值

CurrentCapabilityView 是查询证据,不是需持久化的合并实体,也不承诺跨来源事务。

批量结果

type BatchItem<T> =
  | { inputIndex: number; ok: true; value: T }
  | { inputIndex: number; ok: false; error: ErrorShape };

interface BatchResult<T> {
  results: readonly BatchItem<T>[];
  meta: ResultMeta;
}

失败项不会从数组消失,调用方应按 inputIndex 对齐原请求。页级 meta.completeness 描述整个操作,逐项错误描述特定槽位;指定修订不可读等全局承诺失败会直接抛出查询级错误。

Provider 作用域

Open 阶段的 Effective Provider Scope 是 hostAllowedProviders ∩ integrationEnabledProviders,查询提供 requestProviderScope 时再求一次交集。请求范围只能收窄;包含未允许 Provider 时返回 CG_SCOPE_DENIEDBoundProviderGraph 固定单 Provider并拒绝 requestProviderScope;ID 前缀、parent 和类型过滤都不是授权。

静态与运行时修订

Static Revision 来自规范化 Provider metadata、能力记录、关系和知识映射,知识正文使用独立 contentId。Core 每个 Provider 保留 current 和 previous;requiredStaticRevision 匹配 previous 时 servedFromprevious,更旧或不可读修订返回 CG_REVISION_MISMATCH

Runtime Revision 由 Adapter 定义,观察同时记录 observedAgainstStaticRevision。兼容状态只有 compatibleunknownrefresh_required;Core 不因 ID 相同自动判断兼容。

分页与游标

游标绑定原请求的范围、过滤、limit 和修订。续页必须保留这些条件。最终公开游标编码后最多 32,768 个 base64url 字符;输入超限为 CG_INPUT_INVALID,输出超限为 CG_BUDGET_EXCEEDED

邻居八个关系组各自分页。续页只提交仍有 nextCursorkinds 和对应 cursors。页大小和总字节预算同时生效,提高响应字节预算不会放宽游标长度上限。

预算与完整性

操作关键默认预算
Catalog24,576 页字节、200 项、2,048 单项字节
Neighbors50 默认页、100 最大页、24,576 页字节、2,048 单项字节
Detail20 能力、16,384 单项字节、131,072 总字节
Selection32 个显式能力、128 个闭包能力、131,072 总字节
Document read32,768 字节、每次 8 文档
Specification documents每页 20 项、131,072 页字节;正文仍受 Document read 预算约束
Capability retrieval20 候选、512 单候选字节
Knowledge query128 个原始 targets、128 个最终 targets、8 命中、2,048 snippet 字节
Runtime50 默认页、100 最大页、5,000 ms 等待、4,096 facts 字节

字节预算使用 UTF-8 或原始 bytes,不是 JavaScript 字符数。truncated 表示继续分页,partial 表示检查 warning 或逐项失败。单项过大不会被截断成看似合法的数据;无法取得进展时返回 CG_BUDGET_EXCEEDED