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(repo): 重写项目规则与路线文档
+280
+63
AGENTS.md
+63
AGENTS.md
···
1
+
# cxs Agent Guide
2
+
3
+
## 项目定位
4
+
5
+
`cxs` 是一个面向本机 Codex session 日志的渐进式检索 CLI，不是 GUI app，也不是实时同步守护进程。
6
+
7
+
当前接受的产品边界：
8
+
9
+
- 命令面固定为：`sync`、`find`、`read-range`、`read-page`、`list`、`stats`
10
+
- 主工作流固定为：`sync -> find -> read-range/read-page`
11
+
- `sync` 是唯一会修改索引的命令；其余命令只读 SQLite
12
+
- 默认接受手动增量同步，不做 watcher / daemon / realtime sync
13
+
- 这个仓库可以作为其他 sidecar / GUI 的 retrieval engine，但本仓库自身不以 GUI 为目标
14
+
15
+
## 当前实现真相
16
+
17
+
- 检索主链是 `message recall -> session heuristic rerank -> progressive read`
18
+
- 候选召回来自 `messages_fts`，极少数零 token CJK query 会回退到 LIKE
19
+
- `summary_text` 已持久化，也会参与结果展示和 rerank，但还没有进入 recall 面
20
+
- `classifyQueryProfile()` 仍存在，但当前评分没有按 `broad/exact` 做显式分权
21
+
- parser 只入库 `event_msg` 里的 user / assistant message；其他 event 不形成 projection
22
+
23
+
不要把下面这些说成已完成：
24
+
25
+
- 真正独立的 stage-2 / resource-level reranker
26
+
- `summary_text` 或 session/resource 级独立 FTS recall
27
+
- richer projection / range cache / event-level replay
28
+
- duplicate family collapse / diversity control
29
+
- 强约束的 gold set / rubric / error taxonomy
30
+
31
+
## 代码地图
32
+
33
+
- [cli.ts](/Users/envvar/work/repos/cxs/cli.ts): CLI 命令面
34
+
- [indexer.ts](/Users/envvar/work/repos/cxs/indexer.ts): sync 与索引更新
35
+
- [parser.ts](/Users/envvar/work/repos/cxs/parser.ts): Codex JSONL 解析与 `summary_text` 生成
36
+
- [db.ts](/Users/envvar/work/repos/cxs/db.ts): SQLite schema、会话/消息存取
37
+
- [query.ts](/Users/envvar/work/repos/cxs/query.ts): find / list / read-range / read-page 查询编排
38
+
- [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts): session heuristic rerank
39
+
- [eval/](/Users/envvar/work/repos/cxs/eval): manual eval、batch compare
40
+
41
+
## 文档规则
42
+
43
+
- 优先维护当前态文档，不保留“看起来像现状、其实只是目标态”的 research 长文
44
+
- 如果文档已经腐化，优先删除或重写，不要叠补丁式修辞
45
+
- `docs/` 里的文档要服务后续 agent 直接接手，而不是保留调研过程痕迹
46
+
- 任何涉及“当前已实现什么”的文档，都必须先对齐代码和测试
47
+
48
+
## 默认验证
49
+
50
+
涉及实现或文档真相变更时，至少做与改动直接相关的验证：
51
+
52
+
- `bun test`
53
+
- 必要时补一条 CLI 烟测，例如 `./bin/cxs stats --json` 或 `./bin/cxs find "<query>" --json`
54
+
55
+
没有验证证据，不要声称“已对齐”“已完成”“文档正确”。
56
+
57
+
## 当前近端优先级
58
+
59
+
1. 先把 eval 从弱提示升级成更可信的 acceptance gate
60
+
2. 再决定是否推进 `summary/projection` 独立 recall 面
61
+
3. 更重的 reranker / projection / diversity 控制放后面
62
+
63
+
具体 roadmap 见 [docs/ROADMAP.md](/Users/envvar/work/repos/cxs/docs/ROADMAP.md)。
+105
docs/ARCHITECTURE.md
+105
docs/ARCHITECTURE.md
···
1
+
# cxs 当前架构
2
+
3
+
## 一句话
4
+
5
+
`cxs` 是一个面向本机 Codex session 日志的渐进式检索 CLI，当前架构是：
6
+
7
+
`sync -> message recall -> session heuristic rerank -> read-range/read-page`
8
+
9
+
它已经可用，但仍是轻量 retrieval 后端，不是完整的 resource-level retrieval 系统。
10
+
11
+
## 当前命令面
12
+
13
+
- `cxs sync`
14
+
- `cxs find <query>`
15
+
- `cxs read-range <sessionUuid>`
16
+
- `cxs read-page <sessionUuid>`
17
+
- `cxs list`
18
+
- `cxs stats`
19
+
20
+
这套命令面已经定型，不再保留 `window/session` 旧别名语义。
21
+
22
+
## 数据流
23
+
24
+
### 1. 同步
25
+
26
+
[indexer.ts](/Users/envvar/work/repos/cxs/indexer.ts) 扫描 `~/.codex/sessions` 下的 JSONL session 文件，按文件 `mtime`、`size` 和 `indexVersion` 做增量判断。
27
+
28
+
[parser.ts](/Users/envvar/work/repos/cxs/parser.ts) 只抽取 `event_msg` 里的：
29
+
30
+
- `user_message`
31
+
- `agent_message`
32
+
33
+
同时过滤内部 marker，避免污染索引。
34
+
35
+
### 2. 持久化
36
+
37
+
[db.ts](/Users/envvar/work/repos/cxs/db.ts) 维护两层主数据：
38
+
39
+
- `sessions`
40
+
- `messages`
41
+
42
+
以及一个全文索引：
43
+
44
+
- `messages_fts`
45
+
46
+
当前 `sessions` 已包含 `summary_text` 字段，但没有单独的 `sessions_fts`。
47
+
48
+
### 3. 查询
49
+
50
+
[query.ts](/Users/envvar/work/repos/cxs/query.ts) 提供三类读取：
51
+
52
+
- `findSessions()`
53
+
- `getMessageRange()`
54
+
- `getMessagePage()`
55
+
56
+
`findSessions()` 当前流程是：
57
+
58
+
1. 先从 `messages_fts` 做候选召回
59
+
2. 极少数零 token CJK query 回退到 LIKE
60
+
3. 把 raw hits 交给 [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 做 session 级排序
61
+
62
+
### 4. 排序
63
+
64
+
[ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 当前是 heuristic rerank，不是独立的 resource-level reranker。
65
+
66
+
主要信号包括：
67
+
68
+
- row 级 bm25 翻转分数
69
+
- content phrase / term coverage
70
+
- user message bump
71
+
- title phrase / term hits
72
+
- cwd term hits
73
+
- user hit count
74
+
- hit count
75
+
- recency
76
+
77
+
## 当前已落地能力
78
+
79
+
- 渐进式命令面
80
+
- CJK 兼容的 tokenized FTS
81
+
- `summary_text` 派生摘要
82
+
- strict / best-effort 两种 sync 语义
83
+
- manual eval 导出
84
+
- eval batch compare
85
+
86
+
## 当前未落地能力
87
+
88
+
下面这些不要误写成现状：
89
+
90
+
- `summary_text` 参与 recall
91
+
- `sessions_fts` 或 session/resource 独立搜索面
92
+
- 真正按 broad/exact query profile 分权的 scoring
93
+
- richer projection / event replay / range cache
94
+
- duplicate collapse / diversity control
95
+
- 强约束 gold set / rubric / error taxonomy
96
+
97
+
## 为什么当前文档改成这版
98
+
99
+
之前的 tracking/research 文档混合了三种内容：
100
+
101
+
- 当前实现
102
+
- 目标态建议
103
+
- 外部调研结论
104
+
105
+
这种写法会误导后续 agent 把“建议”当成“现状”。这里保留的只有当前代码真相；后续计划单独放到 [docs/ROADMAP.md](/Users/envvar/work/repos/cxs/docs/ROADMAP.md)。
+73
docs/ROADMAP.md
+73
docs/ROADMAP.md
···
1
+
# cxs Roadmap
2
+
3
+
## 当前判断
4
+
5
+
`cxs` 现在已经有一条可用的 retrieval 主链，但下一步不该盲目继续堆排序逻辑。当前最缺的是一个更可信的 acceptance gate。
6
+
7
+
## 优先级
8
+
9
+
### P0: 先补强 eval 基线
10
+
11
+
目标：让后续 retrieval 调整有稳定证据，不再只靠感觉。
12
+
13
+
当前现状：
14
+
15
+
- [eval/manual-queries.json](/Users/envvar/work/repos/cxs/eval/manual-queries.json) 只有 18 条 seed query
16
+
- [eval/manual-eval-core.ts](/Users/envvar/work/repos/cxs/eval/manual-eval-core.ts) 只支持弱谓词：
17
+
- `title_or_summary`
18
+
- `cwd`
19
+
- `snippet`
20
+
21
+
建议动作：
22
+
23
+
- 扩充真实 query 集
24
+
- 增加更强断言：
25
+
- session 是否对
26
+
- `read-range` 是否给出有用上下文
27
+
- 是否命中关键 message / key phrase
28
+
- 继续复用现有：
29
+
- `bun run eval:manual`
30
+
- `bun run ./eval/compare-eval-batches.ts <before> <after>`
31
+
32
+
### P1: 再决定是否补 summary recall
33
+
34
+
目标：解决“正文不命中、只有 summary 命中”的 recall 漏洞。
35
+
36
+
当前现状：
37
+
38
+
- `summary_text` 已生成、已持久化、已参与 rerank
39
+
- 但 `find` 的候选仍只来自 `messages_fts` / LIKE
40
+
41
+
候选实现方向：
42
+
43
+
- 方案 A：把 summary 作为虚拟 message 写入 `messages` + `messages_fts`
44
+
- 方案 B：新增 `sessions_fts(title + summary_text)`，`find` 时 UNION 两路候选
45
+
46
+
当前不把它排到 P0 的原因：
47
+
48
+
- [docs/TODO.md](/Users/envvar/work/repos/cxs/docs/TODO.md) 记录的现有 eval 里，还没观察到明显 recall 漏洞
49
+
50
+
### P2: 真正的 query profile 分流
51
+
52
+
目标：让 broad / exact query 的排序策略真正分开。
53
+
54
+
当前现状：
55
+
56
+
- [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 仍保留 `classifyQueryProfile()`
57
+
- 但当前 scoring 没有按 `kind` 做显式不同权重
58
+
59
+
这意味着：
60
+
61
+
- 分类标签还在
62
+
- 真正的分流还没完成
63
+
64
+
### P3: 更重的 retrieval 能力
65
+
66
+
暂不优先：
67
+
68
+
- resource-level reranker
69
+
- richer projection
70
+
- duplicate family collapse / diversity control
71
+
- heavier model / vector retrieval
72
+
73
+
这些都应该建立在更强 eval 之后，而不是先上。
+39
docs/TODO.md
+39
docs/TODO.md
···
1
+
# cxs TODO
2
+
3
+
## P0: 把 eval 升级成可用 gate
4
+
5
+
当前真正最缺的不是新排序逻辑，而是更可信的 acceptance gate。
6
+
7
+
现状：
8
+
9
+
- [eval/manual-queries.json](/Users/envvar/work/repos/cxs/eval/manual-queries.json) 只有 18 条 seed query
10
+
- [eval/manual-eval-core.ts](/Users/envvar/work/repos/cxs/eval/manual-eval-core.ts) 只支持 `title_or_summary`、`cwd`、`snippet` 这几类弱断言
11
+
12
+
下一步应该优先补：
13
+
14
+
- 更多真实 query
15
+
- 对 session 命中正确性的断言
16
+
- 对 `read-range` 可用性的断言
17
+
- 更清晰的 failure taxonomy
18
+
19
+
## P1: summary 参与 recall
20
+
21
+
当前 `sessions.summary_text` 已经生成、存库、参与 rerank，但没有进 recall 面。
22
+
23
+
这意味着：如果一个 session 的正文和 query 不重合，只有 summary 命中，它当前不会被 `find` 召回。
24
+
25
+
候选方案：
26
+
27
+
- 插入一条 `seq = -1`、`role = "summary"` 的虚拟 message 进 `messages` + `messages_fts`
28
+
- 或者新建 `sessions_fts(title + summary_text)`，`find` 时 UNION 两路候选
29
+
30
+
当前仍不优先的原因：
31
+
32
+
- 现有 eval 下还没观察到明显 recall 漏洞
33
+
- 在更强 eval 就位前，先改 recall 面容易变成“改了很多，但证据不够硬”
34
+
35
+
## P2: 真正接通 broad / exact query 分流
36
+
37
+
当前 [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 还保留 `classifyQueryProfile()`，但 scoring 没有显式按 broad / exact 分权。
38
+
39
+
这件事仍然值得做，但应放在更强 eval 之后。