305 lines
11 KiB
Markdown
305 lines
11 KiB
Markdown
# 会话查询
|
||
|
||
[English](session-query.md) | 中文
|
||
|
||
本文定义面向优先使用 live 数据的逻辑会话语料库的查询词汇。[接口包（package）](../../packages/session-query/session-query)负责精确读取、来源优先级、关系追踪、语义提取，以及与提供方无关的过滤器；[SQLite 包](../../packages/session-query/session-query-sqlite)负责具体全文索引的生命周期。
|
||
|
||
源码：[`packages/session-query/session-query/src/types.ts`](../../packages/session-query/session-query/src/types.ts)
|
||
|
||
## 逻辑记录
|
||
|
||
`SessionRecord` 由跨语料库列表返回。它独立于克隆后的实时优先 header 暴露源可用性。`SessionEventRecord` 是轻量的原始日志投影；分类使用与 model-history 推导相同的 `foldSurface()` 状态转换。
|
||
|
||
```ts type-equiv
|
||
/** Whether an event is current model context, replaced context, or raw-log-only. */
|
||
type SessionEventSurface = 'current' | 'shadowed' | 'log-only'
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Lightweight identity and source availability for one logical session. */
|
||
interface SessionRecord {
|
||
/** Cloned session header selected from the live-preferred corpus. */
|
||
header: SessionHeader
|
||
/** Whether the id currently exists in `ctx.sessions`. */
|
||
live: boolean
|
||
/** Whether the active persistence backend currently materializes the id. */
|
||
persisted: boolean
|
||
}
|
||
```
|
||
|
||
`SessionLogSnapshot` 是供恢复预检使用的完整原始日志：它脱离运行时，并经过回放验证。`SessionSurfaceSnapshot` 表示一次精确读取的 surface 观测结果，而不是持续保留的订阅。
|
||
|
||
```ts type-equiv
|
||
/** One validated detached observation of a logical session's complete raw log. */
|
||
interface SessionLogSnapshot {
|
||
/** Cloned session header selected from the same observation as `events`. */
|
||
session: SessionHeader
|
||
/** Cloned contiguous raw events after persistence repair and replay validation. */
|
||
events: SessionEvent[]
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** One atomic live-preferred observation of a session's current model surface. */
|
||
interface SessionSurfaceSnapshot {
|
||
/** Cloned session header selected from the same corpus observation as `events`. */
|
||
session: SessionHeader
|
||
/** Highest raw-log seq included in the observation, or `null` for an empty log. */
|
||
capturedThroughSeq: number | null
|
||
/** Cloned current surface events in model-history order. */
|
||
events: SurfaceEvent[]
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Lightweight metadata for one event within a logical session. */
|
||
interface SessionEventRecord {
|
||
/** Session that owns the event. */
|
||
sessionId: SessionId
|
||
/** Monotonic event seq within the session. */
|
||
seq: number
|
||
/** Discriminant of the session event. */
|
||
type: SessionEventType
|
||
/** Event timestamp in Unix epoch milliseconds. */
|
||
time: number
|
||
/** Event placement in the folded session surface. */
|
||
surface: SessionEventSurface
|
||
}
|
||
```
|
||
|
||
## 与提供方无关的过滤器和文档
|
||
|
||
会话和事件过滤器数组内的各项按逻辑与（AND）组合；单个列表子句中的各值按逻辑或（OR）组合。范围包含两端。事件的 `text` 子句会对提取出的语义文本执行正则表达式扫描：搜索文本按字面量处理，Unicode 字符不区分大小写，空白字符可灵活匹配；该过程与全文搜索提供方无关。
|
||
|
||
```ts type-equiv
|
||
/**
|
||
* One logical-session predicate. A filter array is ANDed; `values` within a
|
||
* clause are ORed.
|
||
*/
|
||
type SessionResultFilter =
|
||
| { kind: 'id'; values: readonly SessionId[] }
|
||
| { kind: 'cwd'; values: readonly (string | null)[] }
|
||
| ({ kind: 'created-at' } & SessionResultRange)
|
||
| { kind: 'parent'; values: readonly (SessionId | null)[] }
|
||
| { kind: 'availability'; values: readonly SessionAvailability[] }
|
||
```
|
||
|
||
```ts type-equiv
|
||
/**
|
||
* One event predicate. A filter array is ANDed; list-valued clauses are ORed.
|
||
* Text is a literal, case-insensitive, whitespace-flexible semantic-text scan.
|
||
*/
|
||
type SessionEventResultFilter =
|
||
| ({ kind: 'seq' } & SessionResultRange)
|
||
| ({ kind: 'time' } & SessionResultRange)
|
||
| { kind: 'type'; values: readonly SessionEventType[] }
|
||
| { kind: 'surface'; values: readonly SessionEventSurface[] }
|
||
| { kind: 'text'; text: string }
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Searchable semantic document derived from one session event. */
|
||
interface SessionEventSearchDocument extends SessionEventRecord {
|
||
/** First-party semantic text used by scan filters and full-text indexes. */
|
||
text: string
|
||
}
|
||
```
|
||
|
||
`ctx.sessionQuery.filterSessions(filters)` 会对完整的逻辑会话语料库应用 `SessionResultFilter`；`ctx.sessionQuery.filterEvents(sessionId, filters)` 按 seq 升序返回匹配的文档。消息、推理（reasoning）、工具调用和工具结果、被阻止的提示词、待办事项，以及失败和状态详情会纳入语义文本；结构事件和流分片则不会。
|
||
|
||
## 全文搜索结果页
|
||
|
||
整合后的 `ctx.sessionQuery` seam 提供两个全文搜索范围。`searchSessions()` 按匹配度最强的事件对语料库分组；`searchEvents()` 搜索单个会话。请求将不透明游标与规范化后的查询、元数据过滤器和结果数量上限绑定。提供方的元数据过滤器有意不包含事件文本扫描。
|
||
|
||
```ts type-equiv
|
||
/** Provider-owned opaque continuation token returned by session search. */
|
||
type SessionSearchCursor = Branded<'SessionSearchCursor'>
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Cross-session full-text search request. */
|
||
interface SessionSearchRequest {
|
||
/** Full-text query interpreted as data, never executable FTS syntax. */
|
||
query: string
|
||
/** Logical-session predicates applied before event ranking. */
|
||
sessionFilters?: readonly SessionResultFilter[]
|
||
/** Event predicates applied before event ranking. */
|
||
eventFilters?: readonly SessionEventMetadataFilter[]
|
||
/** Maximum sessions in this page. */
|
||
limit?: number
|
||
/** Opaque cursor returned for the identical normalized request. */
|
||
cursor?: SessionSearchCursor
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Within-session full-text search request. */
|
||
interface SessionEventSearchRequest {
|
||
/** Session whose live-preferred logical log is searched. */
|
||
sessionId: SessionId
|
||
/** Full-text query interpreted as data, never executable FTS syntax. */
|
||
query: string
|
||
/** Event predicates applied before ranking. */
|
||
filters?: readonly SessionEventMetadataFilter[]
|
||
/** Maximum events in this page. */
|
||
limit?: number
|
||
/** Opaque cursor returned for the identical normalized request. */
|
||
cursor?: SessionSearchCursor
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** One cursor-paginated result page. */
|
||
interface SessionSearchPage<T> {
|
||
/** Results for this page in contract-defined order. */
|
||
items: readonly T[]
|
||
/** Opaque continuation cursor, absent on the final page. */
|
||
nextCursor?: SessionSearchCursor
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** One event full-text search hit with a bounded plain-text excerpt. */
|
||
interface SessionEventSearchHit extends SessionEventRecord {
|
||
/** Plain text excerpt selected around the match. */
|
||
snippet: string
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** One grouped cross-session hit, ranked by its strongest matching event. */
|
||
interface SessionSearchHit extends SessionRecord {
|
||
/** Strongest matching event for this session. */
|
||
bestMatch: SessionEventSearchHit
|
||
}
|
||
```
|
||
|
||
## 会话谱系
|
||
|
||
`SessionLineageTrace` 按由近及远的顺序携带已知 parent，并携带一片由直接 descendant 递归嵌套而成的森林。完整性判别字段使已知 root 与缺失 parent 互斥。
|
||
|
||
```ts type-equiv
|
||
/** Recursive descendant node in a session-lineage trace. */
|
||
interface SessionLineageNode {
|
||
/** Detached logical-corpus record for this descendant. */
|
||
session: SessionRecord
|
||
/** Direct children, each carrying its own recursive descendants. */
|
||
descendants: SessionLineageNode[]
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Known ancestry and descendants for one logical session. */
|
||
type SessionLineageTrace = {
|
||
/** Detached record for the session that was traced. */
|
||
target: SessionRecord
|
||
/** Known parents from the immediate parent outward. */
|
||
ancestors: SessionRecord[]
|
||
/** Complete known descendant trees rooted at the target's direct children. */
|
||
descendants: SessionLineageNode[]
|
||
} & (
|
||
| {
|
||
/** The complete parent chain is present in the logical corpus. */
|
||
complete: true
|
||
/** Detached record at the top of the complete lineage. */
|
||
root: SessionRecord
|
||
}
|
||
| {
|
||
/** The parent chain leaves the visible logical corpus. */
|
||
complete: false
|
||
/** First parent id that is not present in the logical corpus. */
|
||
unresolvedParentId: SessionId
|
||
}
|
||
)
|
||
```
|
||
|
||
## 有界事件读取
|
||
|
||
请求指定一个原始 seq 及可选的邻近数量。结果携带 `SessionHeader` 而非可用性标志，使已知的实时目标可以独立于持久化健康状态。
|
||
|
||
```ts type-equiv
|
||
/** Request for one event plus raw neighboring log context. */
|
||
interface SessionEventReadRequest {
|
||
/** Session that owns the target event. */
|
||
sessionId: SessionId
|
||
/** Target event seq. */
|
||
seq: number
|
||
/** Number of preceding raw events to include. */
|
||
before?: number
|
||
/** Number of following raw events to include. */
|
||
after?: number
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Full target event and a bounded raw-log window. */
|
||
interface SessionEventWindow {
|
||
/** Cloned header for the live-preferred source read. */
|
||
session: SessionHeader
|
||
/** Full cloned target event. */
|
||
target: SessionEvent
|
||
/** Full cloned events from `startSeq` through `endSeq`. */
|
||
events: SessionEvent[]
|
||
/** First seq included in `events`. */
|
||
startSeq: number
|
||
/** Last seq included in `events`. */
|
||
endSeq: number
|
||
}
|
||
```
|
||
|
||
## 事件关系
|
||
|
||
事件追踪会区分位置性的 surface 替换与已记录 provenance。除 `replacementChain` 外，每个 seq 列表都包含直接链接；该链从目标沿直接 replacer 追踪到最终的位置替换。
|
||
|
||
```ts type-equiv
|
||
/** Request for direct surface and provenance relationships around one event. */
|
||
interface SessionEventTraceRequest {
|
||
/** Session that owns the target event. */
|
||
sessionId: SessionId
|
||
/** Target event seq. */
|
||
seq: number
|
||
}
|
||
```
|
||
|
||
```ts type-equiv
|
||
/** Direct surface and provenance relationships for one event. */
|
||
interface SessionEventTrace {
|
||
/** Lightweight target record. */
|
||
target: SessionEventRecord
|
||
/** Immediate positional replacement event, when the target was shadowed. */
|
||
replacedBy?: number
|
||
/** Positional replacers from the immediate replacement to the final replacement. */
|
||
replacementChain: number[]
|
||
/** Surface nodes directly removed when the target itself performed a replacement. */
|
||
replacedEventSeqs: number[]
|
||
/** Direct logged provenance sources in their recorded order. */
|
||
sourceEventSeqs: number[]
|
||
/** Later events that directly name the target as a provenance source, in log order. */
|
||
derivedEventSeqs: number[]
|
||
}
|
||
```
|
||
|
||
## 错误
|
||
|
||
封闭的 code 联合类型区分请求校验、目标缺失、surface 日志格式错误、可选后端故障与矛盾的源元数据。
|
||
|
||
```ts type-equiv
|
||
/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
|
||
type SessionQueryErrorCode =
|
||
| 'SESSION_QUERY_ABORTED'
|
||
| 'SESSION_QUERY_EVENT_NOT_FOUND'
|
||
| 'SESSION_QUERY_INDEX_FAILED'
|
||
| 'SESSION_QUERY_INVALID_CONFIG'
|
||
| 'SESSION_QUERY_INVALID_CURSOR'
|
||
| 'SESSION_QUERY_INVALID_FILTER'
|
||
| 'SESSION_QUERY_INVALID_LIMIT'
|
||
| 'SESSION_QUERY_INVALID_QUERY'
|
||
| 'SESSION_QUERY_INVALID_LINEAGE'
|
||
| 'SESSION_QUERY_INVALID_SURFACE'
|
||
| 'SESSION_QUERY_INVALID_WINDOW'
|
||
| 'SESSION_QUERY_PERSISTENCE_FAILED'
|
||
| 'SESSION_QUERY_SESSION_NOT_FOUND'
|
||
| 'SESSION_QUERY_STALE_CURSOR'
|
||
| 'SESSION_QUERY_SOURCE_CONFLICT'
|
||
```
|