cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
chore(release): 补齐开源发布元数据
+251
-3
+25
.github/workflows/ci.yml
+25
.github/workflows/ci.yml
···
1
+
name: ci
2
+
3
+
on:
4
+
push:
5
+
branches:
6
+
- main
7
+
pull_request:
8
+
9
+
jobs:
10
+
test:
11
+
runs-on: ubuntu-latest
12
+
steps:
13
+
- name: Checkout
14
+
uses: actions/checkout@v4
15
+
16
+
- name: Setup Bun
17
+
uses: oven-sh/setup-bun@v2
18
+
with:
19
+
bun-version: latest
20
+
21
+
- name: Install dependencies
22
+
run: bun install --frozen-lockfile
23
+
24
+
- name: Run tests
25
+
run: bun test
+55
CONTRIBUTING.md
+55
CONTRIBUTING.md
···
1
+
# Contributing
2
+
3
+
## 开发环境
4
+
5
+
- Bun `>= 1.3`
6
+
- macOS 或其他能读取本机 Codex session 数据的环境
7
+
8
+
安装依赖：
9
+
10
+
```bash
11
+
bun install
12
+
```
13
+
14
+
## 常用命令
15
+
16
+
运行测试：
17
+
18
+
```bash
19
+
bun test
20
+
```
21
+
22
+
跑手工评测导出：
23
+
24
+
```bash
25
+
bun run eval:manual
26
+
```
27
+
28
+
对比两次评测批次：
29
+
30
+
```bash
31
+
bun run ./eval/compare-eval-batches.ts data/cxs-eval/<before-batch> data/cxs-eval/<after-batch>
32
+
```
33
+
34
+
## 贡献边界
35
+
36
+
- `sync` 是唯一会写索引的命令；其余命令应保持只读
37
+
- 不要把“目标态建议”写成“当前实现”
38
+
- 优先补强 eval，再继续扩 retrieval 能力
39
+
- 不要提交 `data/` 或 `node_modules/`
40
+
41
+
## 提交前
42
+
43
+
至少运行：
44
+
45
+
```bash
46
+
bun test
47
+
```
48
+
49
+
如果改动涉及查询、排序、评测语义，建议补一次：
50
+
51
+
```bash
52
+
./bin/cxs stats --json
53
+
```
54
+
55
+
以及相关 CLI 烟测。
+21
LICENSE
+21
LICENSE
···
1
+
MIT License
2
+
3
+
Copyright (c) 2026
4
+
5
+
Permission is hereby granted, free of charge, to any person obtaining a copy
6
+
of this software and associated documentation files (the "Software"), to deal
7
+
in the Software without restriction, including without limitation the rights
8
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+
copies of the Software, and to permit persons to whom the Software is
10
+
furnished to do so, subject to the following conditions:
11
+
12
+
The above copyright notice and this permission notice shall be included in all
13
+
copies or substantial portions of the Software.
14
+
15
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+
SOFTWARE.
+93
README.md
+93
README.md
···
2
2
3
3
`cxs` 是一个面向本机 Codex 会话日志的渐进式检索 CLI。
4
4
5
+
它的目标不是“返回整场对话全文”，而是给 agent 或人一个低噪音的读取路径：
6
+
7
+
`sync -> find -> read-range/read-page`
8
+
9
+
## 适用场景
10
+
11
+
- 查“之前那个 session 里是怎么修的”
12
+
- 按关键词找最近的 Codex 历史
13
+
- 先拿候选 session，再围绕命中点局部展开
14
+
- 给 sidecar / GUI 工具提供本地 session retrieval engine
15
+
16
+
## 非目标
17
+
18
+
- 不做实时 watcher / daemon / 自动 sync
19
+
- 不做 GUI
20
+
- 不直接绑定 live in-flight thread
21
+
- 不返回未裁剪的全文默认输出
22
+
5
23
当前命令面：
6
24
7
25
- `cxs sync`
···
16
34
```bash
17
35
bun install
18
36
```
37
+
38
+
要求：
39
+
40
+
- Bun `>= 1.3`
41
+
- 本机可读取 `~/.codex/sessions`
42
+
- 默认会在仓库内使用 `./data/index.sqlite` 作为索引库
19
43
20
44
## 用法
21
45
···
67
91
./bin/cxs stats
68
92
```
69
93
94
+
## 快速开始
95
+
96
+
首次使用建议按下面顺序：
97
+
98
+
```bash
99
+
bun install
100
+
./bin/cxs sync
101
+
./bin/cxs find "health check"
102
+
./bin/cxs read-range <sessionUuid> --seq <matchSeq>
103
+
```
104
+
105
+
如果你已经知道当前项目路径，也可以先缩范围：
106
+
107
+
```bash
108
+
./bin/cxs list --cwd /Users/you/work/project --sort ended -n 10
109
+
```
110
+
111
+
## 当前实现边界
112
+
113
+
当前 retrieval 主链是：
114
+
115
+
`message recall -> session heuristic rerank -> read-range/read-page`
116
+
117
+
已经落地的能力：
118
+
119
+
- `messages_fts` 驱动的候选召回
120
+
- `summary_text` 派生摘要
121
+
- session 级 heuristic rerank
122
+
- manual eval 导出与 batch compare
123
+
124
+
还没落地的能力：
125
+
126
+
- `summary_text` 参与 recall
127
+
- 独立的 session/resource 级搜索面
128
+
- 真正的 resource-level reranker
129
+
- duplicate collapse / diversity control
130
+
131
+
更完整的实现说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，后续路线见 [docs/ROADMAP.md](docs/ROADMAP.md)。
132
+
133
+
## 常见问题
134
+
135
+
### 为什么 `find` 没搜到我刚刚的 session？
136
+
137
+
先看索引时间：
138
+
139
+
```bash
140
+
./bin/cxs stats --json
141
+
```
142
+
143
+
如果 `lastSyncAt` 很旧，先重新同步：
144
+
145
+
```bash
146
+
./bin/cxs sync
147
+
```
148
+
149
+
### 为什么有些中文短 query 命中不稳定？
150
+
151
+
当前主召回仍以 message FTS 为主，极少数零 token CJK query 才会回退到 LIKE。短 query 本身信息量低，建议换成更长的词组或加项目上下文。
152
+
153
+
### 为什么不做自动实时同步？
154
+
155
+
这是刻意的产品边界。当前接受“手动触发的增量 sync”，而不是 watcher/daemon。
156
+
70
157
## 开发
71
158
72
159
运行测试：
···
88
175
```bash
89
176
bun run ./eval/compare-eval-batches.ts data/cxs-eval/<before-batch> data/cxs-eval/<after-batch>
90
177
```
178
+
179
+
## 开源协作
180
+
181
+
- 项目规则见 [AGENTS.md](AGENTS.md)
182
+
- 协作说明见 [CONTRIBUTING.md](CONTRIBUTING.md)
183
+
- 当前公开目标是“可接手、可验证、可继续演进”的源码仓库，不承诺 npm 发布流程稳定
+18
bun.lock
+18
bun.lock
···
1
+
{
2
+
"lockfileVersion": 1,
3
+
"configVersion": 1,
4
+
"workspaces": {
5
+
"": {
6
+
"name": "cxs",
7
+
"dependencies": {
8
+
"chalk": "^5.6.2",
9
+
"commander": "^14.0.3",
10
+
},
11
+
},
12
+
},
13
+
"packages": {
14
+
"chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
15
+
16
+
"commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
17
+
}
18
+
}
+39
-2
package.json
+39
-2
package.json
···
1
1
{
2
2
"name": "cxs",
3
-
"private": true,
4
3
"version": "0.1.0",
5
4
"type": "module",
6
-
"description": "Codex sessions progressive search CLI",
5
+
"description": "Progressive search CLI for local Codex session logs",
6
+
"license": "MIT",
7
+
"homepage": "https://github.com/catoncat/cxs",
8
+
"repository": {
9
+
"type": "git",
10
+
"url": "git+https://github.com/catoncat/cxs.git"
11
+
},
12
+
"bugs": {
13
+
"url": "https://github.com/catoncat/cxs/issues"
14
+
},
15
+
"bin": {
16
+
"cxs": "./bin/cxs"
17
+
},
18
+
"files": [
19
+
"bin/",
20
+
"cli.ts",
21
+
"db.ts",
22
+
"env.ts",
23
+
"format.ts",
24
+
"indexer.ts",
25
+
"parser.ts",
26
+
"query.ts",
27
+
"ranking.ts",
28
+
"tokenize.ts",
29
+
"types.ts",
30
+
"eval/"
31
+
],
32
+
"keywords": [
33
+
"codex",
34
+
"cli",
35
+
"fts",
36
+
"search",
37
+
"sqlite",
38
+
"session"
39
+
],
40
+
"engines": {
41
+
"bun": ">=1.3.0"
42
+
},
7
43
"scripts": {
8
44
"test": "bun test",
45
+
"check": "bun test",
9
46
"cxs": "bun run ./cli.ts",
10
47
"eval:manual": "bun run ./eval/run-manual-eval.ts"
11
48
},