<a id="definition-drafts"></a>

# 定义草稿

<!-- i18n: source=docs/architecture/definition-drafts.md blob=6830be6e2eecf1912353fa8f9194619554e027d5 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/definition-drafts.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/definition-drafts.md), which is authoritative.


缺口草稿需要 `knowledge_gaps_enabled`，查询历史需要 `knowledge_query_history_enabled`。两条路径都会把模型撰写的定义放入管理员审核队列。模型从不发布定义。本页介绍证据、私有候选项和审核；[知识缺口](https://github.com/ClickHouse/loom/blob/main/docs/architecture/knowledge-gaps.md)介绍搜索的记录和分组。

<a id="evidence-and-access"></a>

## 证据与访问

资料库中的 **Draft definition** 操作会调用 `knowledge.gaps.draft`。它会依据当前七天的未命中窗口重新读取该缺口的问题，并要求每个问题至少有 `knowledge_gaps_min_askers` 个不同的提问者。它只把这些规范化后的问题发送给模型。采集同意状态不经缓存读取，同意状态不可用时拒绝生成草稿。处理期间若阈值变更或用户被删除，证据即失效，并移除该次尝试的候选版本。

`knowledge.query_history.add`、`.list` 和 `.remove` 需要命名空间管理员权限。在资料库中，**Query history** 会打开来源列表和连接表单。一条注册信息包含名称、主机、端口、TLS 选项、只读账户、数据库允许列表和可选的集群。其密码在存储时加密封存，且不会返回。该连接复用跟踪器的主机检查、固定地址和只读授权审查。集群还需要 `REMOTE`。移除注册信息会停止后续的处理轮次，但不会删除已有的草稿或定义。运营方禁用查询历史后，仍可断开连接。

worker 读取已完成的初始 `SELECT` 查询，这些查询的数据库列表非空，且完全位于注册信息的允许列表之内。指定了集群时使用 `clusterAllReplicas`；否则只读取所连接的节点。分组依据 `normalized_query_hash` 和 `normalizedQueryHashKeepNames`，按不同 `initial_user` 账户数和最近时间排序。第二个哈希能区分带不同编号的表名，同时不会拆分仅空白或字面量不同的变体。`normalizeQueryKeepNames` 会移除注释并替换字面量，保留标识符。只有这份规范化后的 SQL 会到达模型。

每个分组至少需要 `knowledge_query_history_min_users` 个账户支持，且不得少于三个。账户不等于人：一个共享账户只算一次，而同一个人的多个账户则分别计数。这一下限不提供任何匿名性保证。实时提高阈值或更改历史窗口，会使进行中的结果失效。移除来源、来源 UUID 变更、功能被禁用以及命名空间被删除，同样会使其失效。

候选项使用 `source_kind = knowledge_gap` 或 `query_history`。它们由模型撰写的文本和查询历史 SQL，在 `learnings.list`、质量计数以及显式和推断的谱系中，都仅对命名空间管理员保持私有。过滤先于分页和聚合进行，包括组织范围的质量读取。读取范围受限的令牌无法调用这两个操作前缀。

<a id="one-model-attempt"></a>

## 一次模型尝试

候选项 ID 由组织、命名空间、类型和证据资源派生。缺口使用其缺口 ID；查询历史使用注册信息 UUID 和两个查询哈希。短暂的候选项租约会先持久化一个待处理声明，然后释放租约以进行模型调用。并发的和之后的请求都会返回该候选项 ID，包括在决定、模型错误、结果无效或崩溃之后。此类失败会保留一个待处理声明，其理由会告知管理员拒绝它并显式撰写。生成之前的策略挂起只会移除未消耗声明的版本，以便在允许时重试。

在声明工作之前，会检查组织的模型调用开关和命名空间的每日上限；上限不可读则拒绝。每次尝试允许一次有界的 JSON 补全。结果会校验术语、别名、正文以及表/列列表的大小。`rests_on` 中的缺口出处保存缺口 ID 和模型给出的表/列列表。符合条件的问题只会进入模型输入；应用不会把它们复制到候选项中。模型可能在其起草的文本里重复某个问题。生成之后，草稿和缺口 ID 可能比来源问题的用户删除存留得更久。查询历史的出处保留其规范化 SQL 和模型给出的表/列列表。最终的候选项租约会重新读取状态，因此完成操作无法取代一次拒绝，也无法恢复已清除的文本。证据围栏在模型工作之前和之后以及插入之后运行。

worker 限制来源、分组、尝试次数、查询字节数、行数、内存和执行时间。超过一轮预算的一半后，它不再启动新的分组，并在处理某个来源之前保存该来源的 UUID，因此出错的来源不会妨碍轮换。固定大小的 UUID 也使来源名称不会进入持久化的游标。连接失败使用按来源设置的有界断路器。worker 的成本事件保留命名空间归属。

<a id="review-and-publication"></a>

## 审核与发布

`learnings.review` 仅对目标为 `memory` 的此类候选项接受审核。写入之前，它会检查集群能力、敏感度、共享定义上限和名称冲突。草稿会修订现有的共享定义，该定义的规范化术语或别名须与草稿术语匹配；匹配有歧义则拒绝。新术语使用随声明一并持久化的随机 `definition/` 键。写入之前会重新读取共享行，因此并发的重命名无法把写入重定向到另一个术语。

审核通过 `memory.set` 写入一条命名空间范围的派生定义，并清除过期时间和有效期限制。完全一致、有效且未过期的头版本无需写入，即使它已被固定或锁定。值有变化时，固定或锁定的头版本会拒绝写入。修订要求当前来源文本与共享副本一致；写入者中途的编辑会导致拒绝。保留的已过期头版本使用其哈希进行条件重写，而不存在的头版本使用 `if_match_sha256="absent"`。条件调用方在该键上串行化；普通的并发 ClickHouse 写入按版本决出。这些检查并不使写入与提升成为原子操作。

审核使用已批准的规范值哈希调用 `memory.promote`。服务器在内部提供候选项出处，并标记已认证的操作者。客户端无法提供可信的出处，也无法通过 `approver` 选择做出决定的操作者。提升会把整条定义（包括规范化 SQL）发布给该命名空间的读取者，因此管理员批准的是面向所有这些读取者的这段文本。

写入已提交但发布或提升失败时，会留下一条普通的命名空间范围定义和一个待处理的候选项。普通检索可以读取该行。重试会提升未变化的完全一致头版本，而无需重写。拒绝该候选项会保持来源行不变。没有自动撤销：它可能覆盖之后某个写入者对相同文本做的元数据修订。管理员可以通过记忆历史和写入操作恢复预期的文本，或显式删除某个确切的版本。

<a id="erasure-audit-and-upgrades"></a>

## 删除、审计与升级

命名空间删除会通过 `query_history_sources.delete` 删除 `loom.query_history_sources`。注册信息保存配置和已封存的凭据，因此归入该步骤，不设记忆内容普查行。候选项遵循 learnings 队列的删除覆盖范围。对历史定义的脱敏，还会按规范文本哈希或被脱敏版本的候选项标签，在每个候选项版本中清除匹配的私有候选项。它使用审核租约，拒绝之后对空白文本的审核，并保留仍包含被脱敏文本的现有头版本。

审核审计会标识已认证的决定操作者和候选项。内部的 `memory.set` 和 `memory.promote` 各自产生审计事件；提升事件同时也是 `memory.lineage` 所跟踪的审计请求 ID。来源变更会审计带范围的注册名称，绝不包含其密码。

私有类型的生成和提升，要求每个在线的服务器和 worker 心跳都声明支持该注册信息迁移。集群状态缺失或不可读时，操作会以失败告终（fail closed）。在启用任一草稿路径之前，请先应用迁移并升级每个服务器和 worker。只要有任何在服务的构建版本较旧或未知，就保持两条路径禁用。较旧的构建不会过滤私有候选项，也不会删除注册信息。仅靠集群检查无法保护回滚：请求可能在较旧的心跳出现之前就已通过检查。

回滚需要一个维护窗口，并且必须在任何较旧的读取者启动之前进行：

1. 同时禁用 `knowledge_gaps_enabled` 和 `knowledge_query_history_enabled`。停止新的私有草稿生成、审核和来源注册请求，以及查询历史的 worker 轮次。让其排队的工作以及每个已受理的模型调用、审核、注册和移除都静默下来。禁用某个开关并不会取消已有的请求或审核。
2. 让这些操作完成或终止，然后在各自的界限内结清其不确定的服务器发送和保留的写入者租约。在已受理的操作仍可能写入候选项、决定或注册信息时，不要清理这些表。
3. 维护期间只运行支持该迁移的构建，从 `loom.learnings_queue` 中移除 `knowledge_gap` 和 `query_history` 候选项的每个版本，并移除 `loom.query_history_sources` 的所有注册信息。等待删除完成，并验证读取者可能使用的每个存储副本上两者都已不存在。保留普通候选项和已发布的定义。完成这些之后，才能启动较旧的读取者。

在整个降级过程中保持私有生成器处于禁用状态。仅当所有在服务的进程都支持该注册信息迁移后，才重新启用它们。受治理的记忆和共享行沿用其现有的升级规则。

<a id="source-entry-points"></a>

## 源码入口

- `server/memory/app/definition_drafts.py`：持久化声明和有界生成。
- `server/memory/app/definition_review.py`：集群门控、提升和候选项脱敏。
- `server/knowledge/app/gap_drafts.py`：当前缺口的资格和同意状态。
- `server/knowledge/app/query_history_sources.py`：注册信息和凭据检查。
- `server/knowledge/store/query_history_remote.py`：只读的分组查询日志读取。
- `server/knowledge/workers/query_history.py`：有界的来源轮换。

<a id="invariants"></a>

## 不变量

- 只有管理员可以读取私有候选项，或通过审核发布它。
- 任何模型补全都不会取代候选项的决定，也不会让已删除的证据复活。
- 来源注册信息不能在命名空间删除之后继续存在并产生草稿。
- 被拒绝或中断的提升不会撤销写入者的行。
