docs(i18n): refresh Agent Note translations after merge

2026-07-23 00:10:53 +08:00
parent cd17f8d23a
commit 744d65d63c
325 changed files with 1535 additions and 1321 deletions
@@ -1,4 +1,4 @@
-# RFC: 精确会话查询服务
+# Agent Note: 精确会话查询服务

 Status: implemented

@@ -6,13 +6,13 @@ Status: implemented

 ## 问题

-会话历史存在于两处：当前的 `SessionStore` 对象与可选的持久化后端。需要精确检查的消费方若无统一服务，就不得不各自重复实现活跃/持久化优先级判定、持久化生命周期处理、原始事件的 surface 分类以及防御性克隆。在检查点之间，持久化状态可能落后于活跃日志，因此仅靠持久化并非当前状态的可靠来源。
+会话历史存在于两处：当前的 `SessionStore` 对象与可选的持久化后端。需要精确检查的消费方若无统一服务，就不得不各自重复实现活跃/持久化优先级判定、持久化生命周期处理、原始事件的 surface 分类、关系追踪以及防御性克隆。在检查点之间，持久化状态可能落后于活跃日志，因此仅靠持久化并非当前状态的可靠来源。

 全文搜索与此相关，但规模大得多。在真实后端尚不存在时就设计提供方注册、提取、同步、失效、排序和游标契约，会产生两个投机性的状态机：一个在接口服务中，另一个在最终的数据库包（package）中。

 ## 决策

-`@deepseek-ai/dsh-session-query` 拥有 `ctx.sessionQuery`，这是一个小型的、受信任的精确读取服务，面向单一逻辑语料库。它暴露 `listSessions()`、`listEvents(sessionId)` 和有界的 `readEvent(request)`。它不暴露过滤器、血缘或溯源遍历、文本提取器、搜索请求、提供方注册或派生索引同步。
+`@deepseek-ai/dsh-session-query` 拥有 `ctx.sessionQuery`，这是一个小型的、受信任的精确检查服务，面向单一逻辑语料库。它暴露 `listSessions()`、`listEvents(sessionId)`、有界的 `readEvent(request)`、`traceSession(sessionId)` 和 `traceEvent(request)`。它不暴露过滤器、文本提取器、搜索请求、提供方注册或派生索引同步。独立的[追踪决策](2026-07-13-session-query-tracing.md)拥有血缘与事件关系语义。

 该服务动态观察可选的 `ctx.sessionPersistence` 绑定，但不保留持久化缓存或失效监听器。每次跨语料库列表操作向活跃后端请求权威元数据，然后叠加一份新鲜的活跃 store 列表。id 匹配的条目合并为一条 `SessionRecord`：活跃 header 优先，`live`/`persisted` 各自独立报告来源可用性。不可变 header 不一致时产生 `SESSION_QUERY_SOURCE_CONFLICT`。

@@ -20,13 +20,13 @@ Status: implemented

 ## Surface 语义

-`dsh-session` 导出 `foldSurface(events)`，`SurfaceManager` 使用相同的转换函数维护其增量缓存。fold 返回分离的当前节点以及每次替换实际移除的 seq。`listEvents()` 利用该结果将每个原始事件分类为 `current`、`shadowed` 或 `log-only`，使检查结果不会在位置替换语义上与 model-history 推导产生分歧。
+`dsh-session` 导出 `foldSurface(events)`，`SurfaceManager` 使用相同的转换函数维护其增量缓存。fold 返回分离的当前事件 seq 以及每次替换实际移除的 seq。`listEvents()` 和 `traceEvent()` 利用该结果为每个原始事件分类，使检查结果不会在位置替换语义上与 model-history 推导产生分歧。

 `readEvent()` 返回完整的目标加上按连续 seq 排列的原始相邻事件。`before` 和 `after` 默认为零，各自受 `readWindowMax`（默认 50）约束。结果携带克隆的 `SessionHeader` 而非来源可用性记录，因为判断活跃目标的 persisted 标志会违反「活跃精确读取不依赖持久化健康状态」这一保证。

 ## 安全边界

-该服务是上下文级别的受信任基础设施，而非授权层。未来面向模型的历史工具或人类 UI 将施加显式的调用方/会话范围。本阶段不添加面向模型的工具，也不改变 transcript（文本记录）或快照的 surface。
+该服务是上下文级别的受信任基础设施，而非授权层。未来面向模型的历史工具或人类 UI 将施加显式的调用方/会话范围。该服务不添加面向模型的工具，也不改变 transcript（文本记录）或快照的 surface。

 ## 曾考虑的替代方案

@@ -34,10 +34,9 @@ Status: implemented
 - **仅查询持久化**：否决。检查点可能落后于当前活跃日志。
 - **缓存持久化元数据并监听写入/删除**：否决。精确读取可以直接询问权威来源，而缓存失效在规模尚未要求时就引入了生命周期与并发状态。
 - **现在就定义提供方无关的搜索协议**：否决。目前没有提供方消费它。第一个 SQLite FTS 包应自行拥有一个协调/事务状态机；只有当第二个实现证明了边界时，才提取更小的共享 seam。
- **在第一阶段就包含血缘、溯源和通用过滤器**：否决。当前没有消费方需要它们，且规范日志足以在日后有证据时再行添加。

 ## 后果

-第一阶段只有一个来源解析状态变量：当前挂载的持久化服务。没有提供方队列、指纹、提取器注册表、观察代次或派生索引更新。精确读取在纯活跃部署中仍然可用，在持久化存在时具有确定性。
+该服务只有一个来源解析状态变量：当前挂载的持久化服务。没有提供方队列、指纹、提取器注册表、观察代次或派生索引更新。精确读取和事件追踪在纯活跃部署中仍然可用，在持久化存在时具有确定性。

-跨语料库列表与持久化精确读取在每次调用时执行后端 I/O。这是有意为之：正确性来自当前权威状态，面向规模的搜索属于第二阶段的数据库。在该包定义并实现其完整契约之前，全文搜索不可用。
+跨语料库列表、血缘追踪和持久化事件操作在每次调用时执行后端 I/O。这是有意为之：正确性来自当前权威状态，面向规模的搜索属于提议中的数据库包。在该包定义并实现其完整契约之前，全文搜索不可用。