cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs(repo): 重写项目规则与路线文档

cat 904008d0 40a795b6

+280
+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
··· 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
··· 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
··· 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 之后。