声明整合审查

声明的积累速度远快于页面的策展速度。knowledge_remember 在声明中的名称未能恰好匹配到唯一页面时，会将其保存为没有主题页面的声明；而计划性维护的 knowledge_relink 仅链接那些源页面是实体页面的声明，或其文本中恰好命名了唯一页面的声明。链接后的声明也会堆积：集线器页面会收集状态快照、重复项以及本应属于更具体主题的声明。本审查将对选定范围执行一个流程。请按此顺序工作：选择范围，链接，然后处理重复项、被替换的声明和快照系列，最后处理页面正文。

1. 选择范围并列举

对预期范围调用 knowledge_status，对当前指纹调用 knowledge_ontology。然后准确列举一个起始集合：

未关联残留（默认设置，也是书记员运行的唯一范围）。首先以非 dryRun 模式运行 knowledge_relink，以便所有可以链接的已记忆声明都被链接。然后通过 knowledge_relink 的 dryRun: true、include: "all" 和 limit: 10 参数列出残留，并跟随 nextCursor：这些是当前所有没有链接页面也没有源页面的声明，无论是由哪个工具保存的。每次调用最多报告每个结果的10个示例，因此限制为10会返回它检查过的每一个声明。
一个页面，用于集线器页面或超出其大小预算的页面。使用 knowledge_connections 的 id、direction: "claims"、view: "full" 和 includeCards: true 参数列出其当前声明，并跟随相同过滤器的 nextOffset。当 snapshot 发生变化时重新开始。在集线器上，首先从卡片中进行分组，然后一次处理一个组；不要提前完整阅读每一个声明。
一个主题，可选地指定起始日期。 当该主题有页面时，使用 knowledge_timeline 的 entity、timeField: "recorded_at" 和 since 参数列出其声明，并跟随 nextOffset。同时使用 knowledge_grep 的 kind: "claim"、该主题的独特名称（如PR编号、提交SHA、功能名称）以及相同的 since/timeField 来搜索归档在其他地方或未关联的声明。只保留实际关于该主题的声明。

在报告中说明范围。使用 knowledge_record 和 metadataView: "full" 读取你将更改的每个声明。声明中的 subject_hint（如果存在）是保存者自己对声明主题的描述，也是判断其主题的最强线索。在选择页面之前，按照声明的主题（一个功能、PR、提交、决策线程、人员或偏好）进行分组。大多数声明只有在其相邻声明中才有意义：关于一个PR的一系列状态快照通常以一个结果声明结束。

2. 选择主题页面

对于每个分组，使用 knowledge_grep 和 knowledge_lookup 查找候选页面，并读取其状态。忽略已撤回的页面和固定页面。

首要主题是声明所断言的对象；在 entities 中首先列出它。只有当声明也陈述了关于该实体（例如做出决定的人或其产品被配置的公司）的某件事时，才添加次要主题。偶然提及不算主题。两到三个主题通常就足够了。
首要主题是声明所关于的最具体页面：关于某个PR的声明应放在该PR的页面上，而不仅仅放在该PR所属的项目页面上。只有当声明陈述了关于更广泛页面（例如项目级别的决策、政策或发布）的某件事时，该页面才保留为主题。
个人陈述的偏好或决定应放在其个人页面上。不要将个人的偏好变成项目或公司政策。
基于证据而非相似名称来匹配身份。当声明命名了某个可能是一个现有页面的事物（例如一个可能指向不同服务的产品名称）时，通过诸如配置、URL或页面自身的别名等证据进行确认。如果仍然不确定，则保持声明原样并报告。

使用 knowledge_annotate 的 entities 参数进行链接，传递完整的列表（它会替换现有列表）以及声明当前的修订版本和哈希值。断言语境、证据和生命周期保持不变。在取代声明之前先进行链接：被取代的声明无法重新链接。

3. 创建缺失的页面并重新链接到它们

将每个声明链接到最近的现有页面可能会将一个真实的主题掩埋在宽泛的页面中。在以下情况下创建页面：

一个离散的主题（功能、项目、工具或重要的PR）大约有五个或更多声明，或者有自己的设计、验证和结果历史；或
一个人员或组织在声明中撰写、拥有或决定了某事，并且没有页面，但有身份证据（例如通过 gh pr view 显示的PR作者）。

不要为单个提及或一个有一日期声明覆盖的单次修复创建页面。使用 knowledge_save_page，包含本体 type、别名以及作为 source 的身份证据。人员页面使用 identity.status: partial，除非身份已完全确定。编写简短的状态并引用声明；其时间线由声明推导而来。从其父页面链接新页面。

然后重新链接该分组的声明，包括步骤4要取代的快照。新页面成为每个声明的首要主题。仅对声明陈述了关于该页面的事件的那些声明（根据步骤2的规则）保留本审查开始时声明所归档的宽泛页面（通常是集线器页面）；从其他声明中移除该页面。保留其他仍然符合条件的现有次要主题。低于阈值的，则将声明保留在其当前页面上。

4. 淘汰重复项、被替换的声明和快照系列

重复项： 两个声明断言了关于同一事件的相同事实、决定或偏好。保留具有所有者批准召回的那个，否则保留较早的那个，否则保留具有更完整归属的那个。使用 knowledge_annotate 的 addEvidence 复制幸存者所缺少的任何证据，然后使用 knowledge_withdraw 撤回另一个，并在原因中注明幸存者的ID。
被替换的： 后一个声明明确纠正了前一个声明（例如助手纠正自己的报告）或决定了前一个声明未解决的问题。使用 knowledge_supersede 用后一个声明取代前一个声明，并在原因中说明具体是哪个声明取代了它。不要在此处使用 knowledge_correct：它会发布替换声明的新副本，从而产生另一个重复项。
快照系列： 关于一个特定项目（同一PR、提交或决策线程：CI在一个代码头处变红、已请求审查、CI变绿）的多个状态快照，随后跟踪有一个关于同一项目的结果声明（已合并、已关闭、已回滚、已发布、已决定、已放弃）。在一次 knowledge_supersede 调用中（最多25个声明），用结果声明取代系列中的每个快照。以下所有条件都必须满足，来自声明自身的文本和日期：
- 每个快照和结果声明都命名了相同的特定项目，而不仅仅是相同的项目；
- 结果声明的日期晚于它取代的每个快照，并陈述了一个最终状态，而不是另一个中间状态；
- 结果声明和快照共享一个主题页面（首先链接它们，步骤3）；该工具会拒绝没有共同页面的声明。日期晚于结果声明的快照，或关于不同代码头或不同项目的快照，则保留。
两者都不是： 关于不同时间点且没有被后续结果取代的快照（CI红色，然后CI绿色，但尚未合并）是历史记录，而不是错误。保留它们。仅凭矛盾不足以构成撤回或取代的理由。如果不确定，保留两者并报告这对。

knowledge_supersede 保留每个被取代声明的文本、证据、来源和历史，在其上记录 superseded_by 和原因，并保持取代声明不变。默认读取操作将不再显示被取代的声明；历史读取（historical: true，lifecycle: "all"）和 knowledge_history 仍然会显示。如果取代操作有误，再次调用它，并传递 undo: true、相同的 by 声明以及来自其回执中 items 的边界。

5. 更新页面正文

链接使声明从其页面可访问；这不会改变页面的内容。仅在声明的改变会影响页面持久状态时才编辑页面：一个决定、一个偏好、一个已落地或发布的变化、一个新功能、一个已解决的未解决问题，或后续声明显示为错误的页面文本。

将一系列进度快照折叠到其结果中。快照（CI运行、开放PR、本地提交）最多是带日期的活动声明，绝不是状态。
在将可变状态作为当前状态写入之前，请实时检查它（例如使用 gh pr view 查看合并状态），并说明检查时间。合并不代表部署，部署不证明特定网关正在运行该代码。
当设计或决策页面与后来的决定矛盾时，在原始文本旁边添加一个带日期的修正，而不是重写它。将已回答的未回答问题标记为已解决，并保留原始问题。
每个新增的句子都要使用 [[claim-id|label]] 链接引用声明。
页面正文有大小预算（页面预算）。如果编辑结果是 state: "rejected"，则未保存任何内容，但已链接的声明已持有事实。使用 knowledge_extract_section 将章节移动到其主题页面（如果需要，按步骤3创建页面），重新读取，然后重试。永远不要缩短其他正文来腾出空间。提取操作会使目标页面成为该章节引用的声明的首要主题，并保留它们现有的主题，包括你从中提取的源页面。对每个此类声明应用步骤2，对于声明未陈述任何关于源页面的内容，则使用 knowledge_annotate 的 entities 移除源页面。

对章节编辑使用 knowledge_edit_body。从全新读取中计算UTF-16偏移量，并在每次编辑前重新读取修订版本和哈希值：其他会话可能会并发编辑繁忙的页面。优先选择插入文本而不是替换文本。仅当整个状态部分都已过时时才替换整个状态部分，并保留其中已有的声明链接。

6. 验证和报告

对每个已链接的声明运行带有 expectedEntities 参数的 knowledge_verify，对每个新建或编辑过的页面运行带有 expectedLinks 参数的。再次列举范围：在你工作时可能已有新声明到达。以相同方式处理它们或进行报告。

报告范围、已检查的声明数量、已链接和重新链接的声明数量、创建的页面数量、已取代的声明（附上每个系列的取代声明）、已撤回的声明（附上每个的幸存声明）、已编辑的页面数量，以及你考虑过但未更改的声明，并附上每个的原因。在无人值守运行时，永远不要要求做出决定，也永远不要猜测：保持不确定的身份、不确定的重复项、结果不确定的快照系列，以及你只会因猜测而创建的页面不变，并在报告中列出它们供人工处理。

书记员运行

知识整合书记员以无人值守方式对未关联残留运行此审查，按照其提示中的计划执行。其提示会检查访问权限并设置自动化；本节仅描述一次运行的工作。

对未关联残留执行步骤1。当残留为空时，报告检查了零个声明，并继续到下面的已写入时间线。
否则执行步骤2到6，并在停止前再次检查残留，因为在运行期间保存的声明是同一积压工作的一部分。
然后，淘汰最多10个已写入的## Timeline章节，从最大的开始（淘汰已写入的时间线）。通过 knowledge_grep 搜索 Timeline 并在页面正文中确认标题。统计已淘汰的章节数和仍带有时间线的页面数。
不要提问。给出步骤6的报告；结束状态行统计已检查、已链接、已取代、已撤回和保留的声明数，然后是已淘汰和保留的时间线数。

知识-声明-整合