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(structure): 迁移源码到 src 目录
Entire-Checkpoint: d199b2c8f2e9
+98
-89
+11
-11
AGENTS.md
+11
-11
AGENTS.md
···
33
33
34
34
## 代码地图
35
35
36
-
- [cli.ts](/Users/envvar/work/repos/cxs/cli.ts): CLI 命令面
37
-
- [indexer.ts](/Users/envvar/work/repos/cxs/indexer.ts): sync 与索引更新
38
-
- [parser.ts](/Users/envvar/work/repos/cxs/parser.ts): Codex JSONL 解析与 `summary_text` 生成
39
-
- [db.ts](/Users/envvar/work/repos/cxs/db.ts): SQLite schema、会话/消息存取
40
-
- [query.ts](/Users/envvar/work/repos/cxs/query.ts): find / list / read-range / read-page 查询编排
41
-
- [status.ts](/Users/envvar/work/repos/cxs/status.ts): status 输出编排
42
-
- [selector.ts](/Users/envvar/work/repos/cxs/selector.ts): selector 解析与覆盖蕴含规则
43
-
- [source-inventory.ts](/Users/envvar/work/repos/cxs/source-inventory.ts): raw sessions metadata inventory
44
-
- [types.ts](/Users/envvar/work/repos/cxs/types.ts): CLI JSON contract 与核心类型
45
-
- [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts): session heuristic rerank
36
+
- [cli.ts](/Users/envvar/work/repos/cxs/src/cli.ts): CLI 命令面
37
+
- [indexer.ts](/Users/envvar/work/repos/cxs/src/indexer.ts): sync 与索引更新
38
+
- [parser.ts](/Users/envvar/work/repos/cxs/src/parser.ts): Codex JSONL 解析与 `summary_text` 生成
39
+
- [db.ts](/Users/envvar/work/repos/cxs/src/db.ts): SQLite schema、会话/消息存取
40
+
- [query.ts](/Users/envvar/work/repos/cxs/src/query.ts): find / list / read-range / read-page 查询编排
41
+
- [status.ts](/Users/envvar/work/repos/cxs/src/status.ts): status 输出编排
42
+
- [selector.ts](/Users/envvar/work/repos/cxs/src/selector.ts): selector 解析与覆盖蕴含规则
43
+
- [source-inventory.ts](/Users/envvar/work/repos/cxs/src/source-inventory.ts): raw sessions metadata inventory
44
+
- [types.ts](/Users/envvar/work/repos/cxs/src/types.ts): CLI JSON contract 与核心类型
45
+
- [ranking.ts](/Users/envvar/work/repos/cxs/src/ranking.ts): session heuristic rerank
46
46
- [eval/](/Users/envvar/work/repos/cxs/eval): manual eval、batch compare
47
47
48
48
## 文档规则
···
83
83
本机约定：
84
84
85
85
- dev bin: `/Users/envvar/.local/bin/cxsd`
86
-
- dev bin 指向：`/Users/envvar/work/repos/cxs/cli.ts`
86
+
- dev bin 指向：`/Users/envvar/work/repos/cxs/src/cli.ts`
87
87
- global dev skill: `/Users/envvar/.agents/skills/cxsd -> /Users/envvar/work/repos/cxs/skill-packages/cxsd`
88
88
- Claude exposure: `/Users/envvar/.claude/skills/cxsd -> /Users/envvar/.agents/skills/cxsd`
89
89
cli.test.ts
src/cli.test.ts
cli.test.ts
src/cli.test.ts
+1
-1
cli.ts
src/cli.ts
+1
-1
cli.ts
src/cli.ts
db.ts
src/db.ts
db.ts
src/db.ts
+7
-7
docs/ARCHITECTURE.md
+7
-7
docs/ARCHITECTURE.md
···
24
24
25
25
### 1. 同步
26
26
27
-
[status.ts](/Users/envvar/work/repos/cxs/status.ts) 返回执行上下文、source inventory、index 状态与 coverage 状态。它可以扫描 raw sessions 的 metadata，但不回答内容问题。
27
+
[status.ts](/Users/envvar/work/repos/cxs/src/status.ts) 返回执行上下文、source inventory、index 状态与 coverage 状态。它可以扫描 raw sessions 的 metadata，但不回答内容问题。
28
28
29
-
[indexer.ts](/Users/envvar/work/repos/cxs/indexer.ts) 按显式 selector 扫描 `~/.codex/sessions` 下的 JSONL session 文件，按文件 `mtime`、`size` 和 `indexVersion` 做增量判断。
29
+
[indexer.ts](/Users/envvar/work/repos/cxs/src/indexer.ts) 按显式 selector 扫描 `~/.codex/sessions` 下的 JSONL session 文件，按文件 `mtime`、`size` 和 `indexVersion` 做增量判断。
30
30
31
31
strict sync 在写 complete coverage 前会 reconcile selector 范围：当前 source snapshot 中不存在、被过滤或不能解析成 session 的旧 index row 会被删除。
32
32
33
-
[parser.ts](/Users/envvar/work/repos/cxs/parser.ts) 只抽取 `event_msg` 里的：
33
+
[parser.ts](/Users/envvar/work/repos/cxs/src/parser.ts) 只抽取 `event_msg` 里的：
34
34
35
35
- `user_message`
36
36
- `agent_message`
···
39
39
40
40
### 2. 持久化
41
41
42
-
[db.ts](/Users/envvar/work/repos/cxs/db.ts) 维护两层主数据：
42
+
[db.ts](/Users/envvar/work/repos/cxs/src/db.ts) 维护两层主数据：
43
43
44
44
- `sessions`
45
45
- `messages`
···
64
64
65
65
### 3. 查询
66
66
67
-
[query.ts](/Users/envvar/work/repos/cxs/query.ts) 提供三类读取：
67
+
[query.ts](/Users/envvar/work/repos/cxs/src/query.ts) 提供三类读取：
68
68
69
69
- `findSessions()`
70
70
- `getMessageRange()`
···
75
75
1. 从 `messages_fts` 做原文证据召回
76
76
2. 从 `sessions_fts` 做 session-level 字段召回
77
77
3. 极少数零 token CJK query 在 message 侧回退到 LIKE
78
-
4. 把 raw hits 合并后交给 [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 做 session 级排序
78
+
4. 把 raw hits 合并后交给 [ranking.ts](/Users/envvar/work/repos/cxs/src/ranking.ts) 做 session 级排序
79
79
80
80
`messages` 仍然只代表可回读的真实 transcript。session-level 命中会以 `matchSource = "session"` 返回；如果没有真实 message anchor，`matchSeq` 为 `null`，CLI 会建议先 `read-page`。
81
81
82
82
### 4. 排序
83
83
84
-
[ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 当前是 heuristic rerank，不是独立的 resource-level reranker。
84
+
[ranking.ts](/Users/envvar/work/repos/cxs/src/ranking.ts) 当前是 heuristic rerank，不是独立的 resource-level reranker。
85
85
86
86
主要信号包括：
87
87
+15
-15
docs/CODE_QUALITY_REVIEW_2026-04-27.md
+15
-15
docs/CODE_QUALITY_REVIEW_2026-04-27.md
···
10
10
11
11
本次审查基于当前工作区状态，而不是 clean `main`。审查覆盖：
12
12
13
-
- `cli.ts`
14
-
- `parser.ts`
15
-
- `db.ts`
16
-
- `query.ts`
17
-
- `ranking.ts`
18
-
- `indexer.ts`
19
-
- `sync-lock.ts`
20
-
- `types.ts`
13
+
- `src/cli.ts`
14
+
- `src/parser.ts`
15
+
- `src/db.ts`
16
+
- `src/query.ts`
17
+
- `src/ranking.ts`
18
+
- `src/indexer.ts`
19
+
- `src/sync-lock.ts`
20
+
- `src/types.ts`
21
21
- 测试文件与项目文档
22
22
23
23
验证命令：
···
49
49
50
50
当前代码地图比较清晰：
51
51
52
-
- `cli.ts`：CLI 命令面
53
-
- `indexer.ts`：sync 与索引更新
54
-
- `parser.ts`：Codex JSONL 解析与 session summary 生成
55
-
- `db.ts`：SQLite schema、session/message 存取、FTS 表维护
56
-
- `query.ts`：find/list/read-range/read-page/current 查询编排
57
-
- `ranking.ts`：session 级 heuristic rerank
52
+
- `src/cli.ts`：CLI 命令面
53
+
- `src/indexer.ts`：sync 与索引更新
54
+
- `src/parser.ts`：Codex JSONL 解析与 session summary 生成
55
+
- `src/db.ts`：SQLite schema、session/message 存取、FTS 表维护
56
+
- `src/query.ts`：find/list/read-range/read-page/current 查询编排
57
+
- `src/ranking.ts`：session 级 heuristic rerank
58
58
- `eval/`：manual eval 与 batch compare
59
59
60
60
这对一个本地 CLI 来说是健康结构。
···
132
132
133
133
> 状态：已在 commit `187c5d9` 部分缓解 — 引入 `tryRemoveStaleLock` 在删除前二次比对 `pid + createdAt`。但这是 best-effort,**不是原子 TOCTOU 修复**：在二次读取与 path-based `rmSync` 之间仍有残余 race 窗口,另一个进程可能在该窗口内删除并替换 lock,导致当前进程仍可能 `rmSync` 别人的新 lock。Node 层没有 inode-pinned unlink,要做真正原子需引入 OS-level flock(native bindings)。
134
134
>
135
-
> 工程决策：cxs 的 sync 是低并发异常路径,残余 race 窗口极窄,接受 best-effort 表述并在 `sync-lock.ts:tryRemoveStaleLock` 注释里明确标注。如未来观察到锁损坏,再考虑引入 flock 或换 rename-based 抓取。
135
+
> 工程决策：cxs 的 sync 是低并发异常路径,残余 race 窗口极窄,接受 best-effort 表述并在 `src/sync-lock.ts:tryRemoveStaleLock` 注释里明确标注。如未来观察到锁损坏,再考虑引入 flock 或换 rename-based 抓取。
136
136
137
137
原文（保留作为背景）：当前逻辑遇到已有 lock 后会读 lock info，判断 pid 不存在就删除 lock 文件。这里有一个竞态：读到 stale lock 之后、删除之前，另一个进程可能已经创建了新 lock；当前进程可能误删别人的新 lock。
138
138
+7
-7
docs/RANKING_WEIGHTS.md
+7
-7
docs/RANKING_WEIGHTS.md
···
1
1
# cxs ranking 权重说明
2
2
3
-
本文是 [ranking.ts](../ranking.ts) 与 [query.ts](../query.ts) 中所有 magic constant 的“为什么是这个值”说明，受众是未来要调权重的维护者(人或 agent)。
3
+
本文是 [ranking.ts](../src/ranking.ts) 与 [query.ts](../src/query.ts) 中所有 magic constant 的“为什么是这个值”说明，受众是未来要调权重的维护者(人或 agent)。
4
4
5
5
每个权重都需要在三个层次的相对量级里活下去：
6
6
7
-
1. **bm25 row-level 分数**(从 `query.ts:289` 或 `messages_fts` 的 `bm25(...)` 来)。被 `-row.score` 翻成正向后，单行通常落在 `2 ~ 15`。
7
+
1. **bm25 row-level 分数**(从 `src/query.ts:289` 或 `messages_fts` 的 `bm25(...)` 来)。被 `-row.score` 翻成正向后，单行通常落在 `2 ~ 15`。
8
8
2. **row-level signal bonus** (`scoreRow`)。叠加在 bm25 之上,常见区间 `0 ~ 16`。
9
9
3. **session-level metadata bonus** (`scoreSession`)。是一个 session 维度的“补强”加层,常见区间 `0 ~ 80`。
10
10
···
14
14
15
15
## SQL 列权重: `bm25(sessions_fts, 8.0, 3.0, 4.0, 1.2)`
16
16
17
-
位置: [query.ts:289](../query.ts)。
17
+
位置: [query.ts:289](../src/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](../ranking.ts)。
44
+
位置: [ranking.ts:166-178](../src/ranking.ts)。
45
45
46
46
```
47
47
normalizedBm25
···
89
89
90
90
## scoreSession: session 级补强
91
91
92
-
位置: [ranking.ts:186-197](../ranking.ts)。
92
+
位置: [ranking.ts:186-197](../src/ranking.ts)。
93
93
94
94
```
95
95
bestRowSignalScore
···
160
160
161
161
## recencyDecay: 时间衰减
162
162
163
-
位置: [ranking.ts:205-210](../ranking.ts)。
163
+
位置: [ranking.ts:205-210](../src/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](../ranking.ts)。
200
+
位置: [ranking.ts:148-157](../src/ranking.ts)。
201
201
202
202
```ts
203
203
if (candidate.matchSource === "message" && current.matchSource !== "message") return true;
+1
-1
docs/ROADMAP.md
+1
-1
docs/ROADMAP.md
+1
-1
docs/TODO.md
+1
-1
docs/TODO.md
···
37
37
38
38
## P2: 真正接通 broad / exact query 分流
39
39
40
-
当前 [ranking.ts](/Users/envvar/work/repos/cxs/ranking.ts) 还保留 `classifyQueryProfile()`，但 scoring 没有显式按 broad / exact 分权。
40
+
当前 [ranking.ts](/Users/envvar/work/repos/cxs/src/ranking.ts) 还保留 `classifyQueryProfile()`，但 scoring 没有显式按 broad / exact 分权。
41
41
42
42
这件事仍然值得做，但应放在更强 eval 之后。
env.test.ts
src/env.test.ts
env.test.ts
src/env.test.ts
env.ts
src/env.ts
env.ts
src/env.ts
+1
-1
eval/manual-eval-core.test.ts
+1
-1
eval/manual-eval-core.test.ts
···
1
1
import { describe, expect, test } from "vitest";
2
2
import { evaluateManualQuery } from "./manual-eval-core";
3
-
import type { FindResult } from "../types";
3
+
import type { FindResult } from "../src/types";
4
4
5
5
describe("evaluateManualQuery", () => {
6
6
test("requires every configured predicate to match somewhere in top-k", () => {
+1
-1
eval/manual-eval-core.ts
+1
-1
eval/manual-eval-core.ts
+4
-3
eval/perf-bench.ts
+4
-3
eval/perf-bench.ts
···
42
42
43
43
const RUNS_PER_QUERY = 5; // 第 1 次作为 warmup,统计后 4 次
44
44
const ROOT = resolve(import.meta.dirname, "..");
45
+
const CLI_ENTRY = resolve(ROOT, "src", "cli.ts");
45
46
const OUT_BASE = resolve(ROOT, "data", "cxs-perf");
46
47
47
48
interface CliArgs {
···
150
151
}
151
152
152
153
// 1. sync
153
-
const syncRun = await runOrThrow([process.execPath, "--import", "tsx", "cli.ts", "sync", "--db", args.db, "--root", args.root, "--json"]);
154
+
const syncRun = await runOrThrow([process.execPath, "--import", "tsx", CLI_ENTRY, "sync", "--db", args.db, "--root", args.root, "--json"]);
154
155
const syncMs = syncRun.ms;
155
156
let sessionCount = 0;
156
157
try {
···
165
166
for (const q of BENCH_QUERIES) {
166
167
const samplesAll: number[] = [];
167
168
for (let i = 0; i < RUNS_PER_QUERY; i++) {
168
-
const r = await runOrThrow([process.execPath, "--import", "tsx", "cli.ts", "find", q, "--db", args.db, "--limit", "10", "--json"]);
169
+
const r = await runOrThrow([process.execPath, "--import", "tsx", CLI_ENTRY, "find", q, "--db", args.db, "--limit", "10", "--json"]);
169
170
samplesAll.push(r.ms);
170
171
}
171
172
// 丢弃首次 warmup
···
181
182
}
182
183
183
184
// 3. stats -> dbSizeBytes
184
-
const statsRun = await runOrThrow([process.execPath, "--import", "tsx", "cli.ts", "stats", "--db", args.db, "--json"]);
185
+
const statsRun = await runOrThrow([process.execPath, "--import", "tsx", CLI_ENTRY, "stats", "--db", args.db, "--json"]);
185
186
let dbSizeBytes = 0;
186
187
try {
187
188
const parsed = JSON.parse(statsRun.stdout) as { dbSizeBytes?: number; sessionCount?: number };
+6
-5
eval/run-manual-eval.ts
+6
-5
eval/run-manual-eval.ts
···
4
4
import { spawn as childSpawn } from "node:child_process";
5
5
import { join, resolve } from "node:path";
6
6
import { evaluateManualQuery, type ManualQuery, type PassMark } from "./manual-eval-core";
7
-
import type { FindResult } from "../types";
7
+
import type { FindResult } from "../src/types";
8
8
9
9
interface FindOutput {
10
10
query: string;
···
12
12
}
13
13
14
14
const ROOT = resolve(import.meta.dirname, "..");
15
+
const CLI_ENTRY = resolve(ROOT, "src", "cli.ts");
15
16
const QUERY_FILE = resolve(import.meta.dirname, "manual-queries.json");
16
17
const OUT_BASE = resolve(ROOT, "data", "cxs-eval");
17
18
···
49
50
50
51
for (const [index, item] of queries.entries()) {
51
52
const prefix = String(index + 1).padStart(2, "0");
52
-
const findJson = await runCommand([process.execPath, "--import", "tsx", "cli.ts", "find", item.query, "--limit", "5", "--json"]);
53
-
const findText = await runCommand([process.execPath, "--import", "tsx", "cli.ts", "find", item.query, "--limit", "5"]);
53
+
const findJson = await runCommand([process.execPath, "--import", "tsx", CLI_ENTRY, "find", item.query, "--limit", "5", "--json"]);
54
+
const findText = await runCommand([process.execPath, "--import", "tsx", CLI_ENTRY, "find", item.query, "--limit", "5"]);
54
55
const findJsonPath = join(outDir, `${prefix}-${item.id}.find.json`);
55
56
const findTxtPath = join(outDir, `${prefix}-${item.id}.find.txt`);
56
57
writeFileSync(findJsonPath, findJson);
···
169
170
return {
170
171
kind: "read-range",
171
172
args: [
172
-
process.execPath, "--import", "tsx", "cli.ts",
173
+
process.execPath, "--import", "tsx", CLI_ENTRY,
173
174
"read-range",
174
175
top.sessionUuid,
175
176
"--seq",
···
185
186
return {
186
187
kind: "read-page",
187
188
args: [
188
-
process.execPath, "--import", "tsx", "cli.ts",
189
+
process.execPath, "--import", "tsx", CLI_ENTRY,
189
190
"read-page",
190
191
top.sessionUuid,
191
192
"--offset",
format.ts
src/format.ts
format.ts
src/format.ts
indexer.test.ts
src/indexer.test.ts
indexer.test.ts
src/indexer.test.ts
indexer.ts
src/indexer.ts
indexer.ts
src/indexer.ts
+2
-2
package.json
+2
-2
package.json
···
39
39
"linux"
40
40
],
41
41
"scripts": {
42
-
"build": "esbuild cli.ts --bundle --platform=node --target=node22 --format=esm --external:better-sqlite3 --external:chalk --external:commander --outfile=dist/cli.js && node scripts/post-build.mjs",
42
+
"build": "esbuild src/cli.ts --bundle --platform=node --target=node22 --format=esm --external:better-sqlite3 --external:chalk --external:commander --outfile=dist/cli.js && node scripts/post-build.mjs",
43
43
"prepublishOnly": "npm run build",
44
44
"test": "vitest run",
45
45
"check": "tsc --noEmit && vitest run",
46
-
"cxs": "tsx ./cli.ts",
46
+
"cxs": "tsx ./src/cli.ts",
47
47
"eval:manual": "tsx ./eval/run-manual-eval.ts",
48
48
"eval:compare": "tsx ./eval/compare-eval-batches.ts",
49
49
"eval:perf": "tsx ./eval/perf-bench.ts"
parser.test.ts
src/parser.test.ts
parser.test.ts
src/parser.test.ts
parser.ts
src/parser.ts
parser.ts
src/parser.ts
query.test.ts
src/query.test.ts
query.test.ts
src/query.test.ts
query.ts
src/query.ts
query.ts
src/query.ts
ranking.ts
src/ranking.ts
ranking.ts
src/ranking.ts
selector.test.ts
src/selector.test.ts
selector.test.ts
src/selector.test.ts
selector.ts
src/selector.ts
selector.ts
src/selector.ts
+3
-3
skill-packages/cxs/references/advanced-queries.md
+3
-3
skill-packages/cxs/references/advanced-queries.md
+2
-2
skill-packages/cxs/references/cli-surface.md
+2
-2
skill-packages/cxs/references/cli-surface.md
+6
-6
skill-packages/cxs/references/failure-cookbook.md
+6
-6
skill-packages/cxs/references/failure-cookbook.md
···
105
105
106
106
source of truth 永远是：
107
107
108
-
- 仓库内 `types.ts`
109
-
- 仓库内 `cli.ts`
108
+
- 仓库内 `src/types.ts`
109
+
- 仓库内 `src/cli.ts`
110
110
111
111
如果字段、命令、flag 变了：
112
112
···
116
116
117
117
## 来源
118
118
119
-
- 仓库内 `cli.ts`
120
-
- 仓库内 `types.ts`
121
-
- 仓库内 `env.ts`
122
-
- 仓库内 `query.ts`
119
+
- 仓库内 `src/cli.ts`
120
+
- 仓库内 `src/types.ts`
121
+
- 仓库内 `src/env.ts`
122
+
- 仓库内 `src/query.ts`
+3
-3
skill-packages/cxs/references/json-schema.md
+3
-3
skill-packages/cxs/references/json-schema.md
+2
-2
skill-packages/cxs/references/progressive-workflow.md
+2
-2
skill-packages/cxs/references/progressive-workflow.md
+3
-3
skill-packages/cxsd/references/advanced-queries.md
+3
-3
skill-packages/cxsd/references/advanced-queries.md
+2
-2
skill-packages/cxsd/references/cli-surface.md
+2
-2
skill-packages/cxsd/references/cli-surface.md
+6
-6
skill-packages/cxsd/references/failure-cookbook.md
+6
-6
skill-packages/cxsd/references/failure-cookbook.md
···
105
105
106
106
source of truth 永远是：
107
107
108
-
- 仓库内 `types.ts`
109
-
- 仓库内 `cli.ts`
108
+
- 仓库内 `src/types.ts`
109
+
- 仓库内 `src/cli.ts`
110
110
111
111
如果字段、命令、flag 变了：
112
112
···
116
116
117
117
## 来源
118
118
119
-
- 仓库内 `cli.ts`
120
-
- 仓库内 `types.ts`
121
-
- 仓库内 `env.ts`
122
-
- 仓库内 `query.ts`
119
+
- 仓库内 `src/cli.ts`
120
+
- 仓库内 `src/types.ts`
121
+
- 仓库内 `src/env.ts`
122
+
- 仓库内 `src/query.ts`
+3
-3
skill-packages/cxsd/references/json-schema.md
+3
-3
skill-packages/cxsd/references/json-schema.md
+2
-2
skill-packages/cxsd/references/progressive-workflow.md
+2
-2
skill-packages/cxsd/references/progressive-workflow.md
source-inventory.test.ts
src/source-inventory.test.ts
source-inventory.test.ts
src/source-inventory.test.ts
source-inventory.ts
src/source-inventory.ts
source-inventory.ts
src/source-inventory.ts
status.ts
src/status.ts
status.ts
src/status.ts
sync-lock.test.ts
src/sync-lock.test.ts
sync-lock.test.ts
src/sync-lock.test.ts
sync-lock.ts
src/sync-lock.ts
sync-lock.ts
src/sync-lock.ts
tokenize.ts
src/tokenize.ts
tokenize.ts
src/tokenize.ts
+9
-2
tsconfig.json
+9
-2
tsconfig.json
types.ts
src/types.ts
types.ts
src/types.ts