cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
docs(ranking): 修复路径与命令拼写
- 所有 .ts 链接从绝对路径 /Users/envvar/work/repos/cxs/... 改为
相对路径 ../...,在 GitHub 与他人 clone 下都可点。
- 修正不存在的 cxs CLI 选项 "read-range <uuid> --start 0":read-range
实际只支持 --seq/--query 锚定,matchSeq=null 时直接断了重锚链路 ——
按当前 CLI 真实语义重写说明。
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Entire-Checkpoint: 059017285930
+7
-7
+7
-7
docs/RANKING_WEIGHTS.md
+7
-7
docs/RANKING_WEIGHTS.md
···
1
1
# cxs ranking 权重说明
2
2
3
-
本文是 [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 与 [query.ts](/Users/envvar/work/repos/cxs/query.ts) 中所有 magic constant 的“为什么是这个值”说明，受众是未来要调权重的维护者(人或 agent)。
3
+
本文是 [ranking.ts](../ranking.ts) 与 [query.ts](../query.ts) 中所有 magic constant 的“为什么是这个值”说明，受众是未来要调权重的维护者(人或 agent)。
4
4
5
5
每个权重都需要在三个层次的相对量级里活下去：
6
6
···
14
14
15
15
## SQL 列权重: `bm25(sessions_fts, 8.0, 3.0, 4.0, 1.2)`
16
16
17
-
位置: [query.ts:289](/Users/envvar/work/repos/cxs/query.ts)。
17
+
位置: [query.ts:289](../query.ts)。
18
18
19
19
`sessions_fts` 的索引列顺序固定为 `(title, summary_text, compact_text, reasoning_summary_text, session_uuid)`,`session_uuid` 是 UNINDEXED,所以 bm25 的四个权重对应前四列。SQLite FTS5 的 bm25 输出是 *负数*,**值越小越好**;权重越大表示该列匹配应该被放大。
20
20
···
41
41
42
42
## scoreRow: 单 row 信号
43
43
44
-
位置: [ranking.ts:166-178](/Users/envvar/work/repos/cxs/ranking.ts)。
44
+
位置: [ranking.ts:166-178](../ranking.ts)。
45
45
46
46
```
47
47
normalizedBm25
···
89
89
90
90
## scoreSession: session 级补强
91
91
92
-
位置: [ranking.ts:186-197](/Users/envvar/work/repos/cxs/ranking.ts)。
92
+
位置: [ranking.ts:186-197](../ranking.ts)。
93
93
94
94
```
95
95
bestRowSignalScore
···
160
160
161
161
## recencyDecay: 时间衰减
162
162
163
-
位置: [ranking.ts:205-210](/Users/envvar/work/repos/cxs/ranking.ts)。
163
+
位置: [ranking.ts:205-210](../ranking.ts)。
164
164
165
165
```
166
166
max(0, 18 - days_since_ended * 0.15)
···
197
197
198
198
## shouldUseDisplayRow: message 优先于 session
199
199
200
-
位置: [ranking.ts:148-157](/Users/envvar/work/repos/cxs/ranking.ts)。
200
+
位置: [ranking.ts:148-157](../ranking.ts)。
201
201
202
202
```ts
203
203
if (candidate.matchSource === "message" && current.matchSource !== "message") return true;
···
210
210
**为什么这样选**:
211
211
212
212
- `bestRow` 决定 ranking,`bestDisplayRow` 决定用户在 `cxs find` 列表里看到的 snippet/seq/role/timestamp。两个故意拆开。
213
-
- 一个 session 可能同时有 `messages_fts` row(score 偏低,但来自真实消息)和 `sessions_fts` row(score 偏高,但只命中标题/摘要)。如果 display 跟着分数走,用户会看到 `matchSeq=null` + 一个 session-level snippet,然后 `cxs read-range <uuid> --start 0` 时找不到锚点,被迫回退 read-page。
213
+
- 一个 session 可能同时有 `messages_fts` row(score 偏低,但来自真实消息)和 `sessions_fts` row(score 偏高,但只命中标题/摘要)。如果 display 跟着分数走,用户会看到 `matchSeq=null` + 一个 session-level snippet,而 `cxs read-range <uuid>` 必须显式带 `--seq` 或 `--query` 才能锚定,空 `matchSeq` 直接断了直接重锚链路,被迫回退 `cxs read-page` 翻全 session。
214
214
- 显示层的真正决策是 **read-range 可用性**:有 anchor 的 row(message)永远优先,即便 session-level row 分数更高。
215
215
216
216
**改动它会影响什么**: