跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

代码索引的新鲜度

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

索引会滞后于代码仓库:它只对已配置分支上已合并的提交建立索引,按轮次逐步处理,并且每个层级各自推进自己的水位线。在依赖已索引的代码之前,请先查看答案中的新鲜度元数据(如果有),以及相关层级的状态。

as_of 块

返回 as_of 的操作会暴露以下新鲜度字段。普通的 code.symbol 定义不包含此块,也不包含 commit;请改为检查 code.index_status,并对照相应的源代码修订版本来验证返回的定义。

字段 含义
commit 此命名空间的快速层级 commit(git_head),不是每个编译器层级的修订版本
branch 命名空间所跟踪的分支
indexed_at 该 commit 落地的时间
lag_commits commit 与镜像已获取的最新提交之间的 first-parent 提交数;-1 表示未知
stale lag_commits > LOOM_CODE_STALE_AFTER_COMMITS(默认 5),或镜像获取已逾期
status fresh(位于最新提交)、behind(未超过过期阈值)、stale、unknown(lag 为 -1)
stale_reason mirror_not_fetched:滞后量是相对于一个已停止获取的镜像统计的
fetched_at 与 stale_reason 同时出现:镜像上次获取的时间
failing_tiers 条目上有层级失败时出现:tier、kind、failing_since、failed_passes、fix,对于带有水位线的层级还有 lag_commits

该块按命名空间缓存 30 秒;移动 git_head 的一次处理会使其失效。它采用 fail-open 策略:无法读取新鲜度时,该块为空,答案仍会返回。请将空的或缺失的 as_of 视为未知。

即使 stale 为 false,失败层级的事实数据也可能落后于最新提交:当 failing_tiers 指明某个编译器层级时,请将编译器级别的答案(精确的调用图、引用)视为可能已过时,并阅读你所依赖的代码。

不要只检查构建状态,也要检查新鲜度。 首次构建已完成的命名空间仍可能落后若干个 commit。返回 as_of 时,检查 stale;没有返回时,通过 code.index_status 检查相应的水位线。当新鲜度为 stale 或未知时,请从你的检出副本中读取即将编辑的文件。

镜像自身的时效

滞后是相对于 Loom 本地镜像来计算的,因此当镜像已停止拉取时,滞后仍显示为 0。所以当拉取超时,stale 也会变为 true,状态操作会报告镜像的时效:

  • code.index_status(单个命名空间)和 code.repos(每个可读条目)会返回 clone_head、clone_fetched_at 和 fetch_overdue(超过 LOOM_CODE_FETCH_STALE_AFTER_SECONDS,默认 3600)。此外还有:git_head、fast_tier_lag、scip_lag / scip_py_lag、compiler_tiers 列表、last_refresh_at,以及 chunks_total / chunks_embedded / embedding_coverage。
  • 二者都会返回 tier_health:每个层级最近一次记录的结果(拉取、摄取、编译器层级以及每周一次的 C++ 完整运行),失败时会给出错误类型、failing_since、failed_passes 和修复方法。若某个 Go 层级因本机无法拉取依赖而跳过了部分模块,则显示为 state: "unavailable"(类型为 dependency_unavailable,failing_since 为首次记录的时间,没有失败次数),并附有修复方法:它不算失败,也不会出现在 as_of.failing_tiers 中。
  • code.repos 的每一行都带有 searchable:embedding_coverage 已达到 LOOM_CODE_READY_EMBED_COVERAGE。

compiler_tiers 为该条目运行的每个层级提供一张卡片(producer、tool、label、commit、lag、workers)。通过 MCP 调用时,以及设置了 commit 时,code.index_status 会返回精简的结果;brief: false 则返回完整结果。

某个提交是否已进入所有层级?

审查已合并 PR 的人需要确认每个层级都已包含该合并。带 commit=<sha> 调用 code.index_status,结果会在 commit_coverage 中给出:

字段 含义
ready 当快速层级以及每个带有水位线的编译器层级都已到达该提交时为 true
waiting_on 尚未到达的层级
in_mirror 镜像中是否包含该提交
fast, tiers[] 每个层级:covered(镜像缺少该提交时为 null)和 commits_since
commits_since 快速层级已越过该提交多远
paths_changed_overlap 带 paths=[…] 时:这些路径中有哪些被之后的合并修改过

paths_changed_overlap 中的路径在索引中与该提交时不同,请从你的检出副本中读取。

st = await agent.code.index_status(namespace="code-myrepo", commit=merge_sha, paths=pr_files)
cov = st["commit_coverage"]
if not cov["ready"]:
    print("waiting on", cov["waiting_on"])

无需轮询即可等待覆盖

一旦某个提交被覆盖,code.coverage.watch 就会在任务收件箱中发布一个事件:

curl -fsS -X POST "$LOOM_BASE_URL/v1/code.coverage.watch" \
  -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"org":"<org>","namespace":"code-myrepo","commit":"'"$MERGE_SHA"'","inbox":"<your-inbox>"}'
  • commit 是完整的 SHA,或是镜像可以解析的缩写。inbox 是任务收件箱(inbox.register)。调用方需要在代码命名空间上拥有 viewer 权限,并在收件箱所属命名空间上拥有 writer 权限。
  • code_coverage_notify worker(默认开启,每隔 LOOM_CODE_COVERAGE_NOTIFY_INTERVAL_SECONDS 运行一次,默认值为 60)会发布一个 code.coverage.ready 事件,其 patch 为 {namespace, commit, tiers: [{producer, label, watermark}]}。该事件通过 /v1/task/watch?inbox=…、task.updates 以及收件箱的签名 webhook 送达。
  • 对于已被覆盖的提交,调用会返回 ready=true 和 emitted=true,并在同一次调用中发布事件。
  • 每个(命名空间,提交,收件箱)组合只产生一个事件:其 task_id 即返回结果中的 event_id,因此重试不会重复发布。同一事件的多次投递在该 id 的租约下逐个执行,所以在两个竞争的投递中,只有存储了该事件的那一个会返回 emitted=true。如果某个在同一次调用中投递的 code.coverage.watch 等待另一次投递超过 10 秒,则返回 409 PRECONDITION_FAILED;如果租约存储(Keeper)没有响应,则返回 503;这两种情况都可以重试。
  • code.coverage.unwatch(字段相同)会删除一个待处理的监视;removed: false 表示没有有效的监视。

Python SDK 提供了 agent.code.coverage_watch(commit, inbox, namespace=…) 和 agent.code.coverage_unwatch(...)。收件箱的说明见任务与决策。

从 CI 推送新鲜度

轮询器(LOOM_CODE_INGEST_INTERVAL_SECONDS,120)会捕获每一次合并。若要立即为某次合并建立索引,请在合并后的任务中调用 code.refresh,并使用作用域限定在代码命名空间的写入令牌:

curl -fsS -X POST "$LOOM_BASE_URL/v1/code.refresh" \
  -H "Authorization: Bearer $LOOM_CI_TOKEN" -H 'Content-Type: application/json' \
  -d '{"org":"<org>","namespace":"code-myrepo","expected_head":"'"$GITHUB_SHA"'"}'
  • 该次处理只覆盖指定的命名空间,该命名空间必须是已配置的条目(否则返回 404),并将其配置的分支索引到获取到的最新提交。
  • expected_head 仅用于记录日志。wait=true 会阻塞到处理结束(最长 wait_timeout_seconds,默认 300);响应中包含 triggered、already_running、head_before 和 head_after。
  • 该调用是尽力而为的;轮询器会修复错过的触发。

运维人员应关注 loom.code.tier_lag_seconds{tier};滞后层级的运维手册见代码索引运维。

设置

设置 默认值 作用
LOOM_CODE_STALE_AFTER_COMMITS 5 落后多少个提交后,as_of.stale 变为 true
LOOM_CODE_FETCH_STALE_AFTER_SECONDS 3600 镜像存在多久后触发 fetch_overdue 和 stale(0 表示禁用该检查)
LOOM_CODE_INGEST_INTERVAL_SECONDS 120 code_ingest 轮询镜像的频率
LOOM_CODE_READY_EMBED_COVERAGE 0.95 已嵌入的比例达到多少后,code.search 才使用其向量检索分支
LOOM_CODE_COVERAGE_NOTIFY_INTERVAL_SECONDS 60 检查覆盖率监视的频率

限制

  • 新鲜度按分支命名空间计算。合并到 main 的修复在合并到发布分支之前,不会出现在该发布分支的命名空间中;code.grep mode=presence namespaces=[…] 可以一次检查多个命名空间。
  • 未合并的 pull request 和你的工作树永远不会进入索引。
  • 索引更新时不会主动推送通知;code.coverage.watch 会按每个 commit 发出通知。

相关内容

这个页面有帮助吗?