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(skill): 收录共享 cxs skill
+724
+196
.agents/skills/cxs/SKILL.md
+196
.agents/skills/cxs/SKILL.md
···
1
+
---
2
+
name: cxs
3
+
description: "用 cxs 对 Codex session 日志做渐进式检索：find -> read-range -> read-page。用于用户说之前、上次、前几天、昨天、我记得我配过、我试过、我们讨论过、翻一下之前的 session、找那次我跑通的命令、之前那个 codex 对话、以前 debug 过的问题、历史对话、codex 历史、session 历史，或者需要在 ~/.codex/sessions 里定位一段对话、但又不想把整批 JSONL 拉进来读。不是用来做当前仓库代码搜索、读当前文件、查外部文档、总结今天提交或收尾当前会话。Also triggers on English: 'last time I', 'earlier session', 'did we already', 'I remember configuring', 'previous codex chat', 'search my codex history'."
4
+
---
5
+
6
+
# cxs
7
+
8
+
用 `cxs` 在 `~/.codex/sessions` 里检索旧 Codex 对话。目标是先定位候选 session，再局部扩上下文，最后才翻全页，不要冷启动整批 JSONL。
9
+
10
+
## 安装
11
+
12
+
推荐用 `npx skills add` 安装这个 skill：
13
+
14
+
```bash
15
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
16
+
```
17
+
18
+
也可以先预览仓库里的 skill：
19
+
20
+
```bash
21
+
npx skills add catoncat/cxs --list
22
+
```
23
+
24
+
## CLI 前置安装
25
+
26
+
这个 skill 依赖 `cxs` CLI。本生态里的常见做法是：
27
+
28
+
- `npx skills add ...` 负责安装 skill 本身
29
+
- 外部 CLI / SDK / 凭证 / 本地工具 由 skill 自己说明前置安装流程
30
+
31
+
也就是说，这个 skill 应该包含 `cxs` CLI 的安装说明，但不会由 `skills` CLI 代替你安装 `cxs`。
32
+
33
+
当前最稳的安装方式：
34
+
35
+
1. clone 仓库
36
+
2. 安装依赖
37
+
3. 让 `cxs` 可执行
38
+
4. 再安装 skill
39
+
40
+
示例：
41
+
42
+
```bash
43
+
git clone https://github.com/catoncat/cxs.git
44
+
cd cxs
45
+
bun install
46
+
47
+
# 方式 A：直接配置环境变量
48
+
export CXS_BIN="$PWD/bin/cxs"
49
+
50
+
# 方式 B：放进 PATH（按你的 shell 自己处理）
51
+
chmod +x "$PWD/bin/cxs"
52
+
```
53
+
54
+
然后再装 skill：
55
+
56
+
```bash
57
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
58
+
```
59
+
60
+
如果后续这个仓库再提供独立 npm/bun 发布形态，可以把上面这段替换成更短的 CLI 安装命令；在那之前，这就是公开仓库里最清晰、最不误导的做法。
61
+
62
+
## 路径前提
63
+
64
+
这个 skill 只包含说明和参考资料，不会把 `cxs` CLI 二进制一起装进你的系统。
65
+
66
+
使用前请满足下面任一条件：
67
+
68
+
- `cxs` 已经在 `PATH` 里
69
+
- 或设置了 `CXS_BIN=/absolute/path/to/bin/cxs`
70
+
71
+
所有命令默认都写成：
72
+
73
+
```bash
74
+
"${CXS_BIN:-cxs}" <subcommand> ...
75
+
```
76
+
77
+
这样可以同时兼容：
78
+
79
+
- 你自己安装到 `PATH` 的 `cxs`
80
+
- 本地 checkout 里的 `bin/cxs`
81
+
- 其他自定义路径
82
+
83
+
## 什么时候用 cxs
84
+
85
+
| 场景 | 用什么 | 原因 |
86
+
| --- | --- | --- |
87
+
| 用户问“之前 / 上次 / 我记得 / 我们讨论过” | `cxs` | 目标是历史 session，不是当前 repo |
88
+
| 用户给了旧项目名、cwd、时间窗口 | `cxs list` 起手 | 先按 `cwd/since` 缩范围比全文搜更稳 |
89
+
| 用户问“最近本项目 / 这个 repo 做过什么讨论” | `cxs list --cwd <current-repo>` 起手 | 先圈出当前 repo 里的候选 session，再做主题判定 |
90
+
| 用户记得某个旧命令、旧报错、旧方案关键词 | `cxs find` 起手 | 先拿 `sessionUuid + matchSeq` |
91
+
| 当前仓库代码/字符串搜索 | 代码搜索工具 | 那是代码库，不是 session 历史 |
92
+
| 当前文件或已知路径阅读 | 文件读取工具 | 不需要走 session 索引 |
93
+
| 外部文档/网页/产品资料 | WebFetch / WebSearch | 不在本机 Codex 历史里 |
94
+
| 今日提交/日报 | commit-daily-summary | 目标是 git，不是 session |
95
+
| 当前会话收尾 | session-wrap | 目标是本轮工作，不是旧对话 |
96
+
97
+
## 什么时候不要用 cxs
98
+
99
+
- 用户要搜当前 repo 代码、配置、测试、文档
100
+
- 用户要查外部网站、官方文档、最新信息
101
+
- 用户要总结今天提交、项目日报、当前会话
102
+
- 你已经知道具体 JSONL 文件路径且只需直接读原文
103
+
- 没有 `sessionUuid` 时，不要一上来 `read-page`
104
+
105
+
## 前置
106
+
107
+
- 先用 `stats --json` 看 `dbPath`、`lastSyncAt`、`sessionCount`
108
+
- 用户明确说“最近那次”“我刚做过”，但 `lastSyncAt` 很旧或 `find`/`list` 零结果时，先跑 `sync`
109
+
- `sync` 默认严格模式；任一文件失败都会非零退出且不提交半截索引
110
+
- 只有用户接受部分成功时才加 `--best-effort`
111
+
- 从别的 cwd 调用时，若默认 db 不对，显式传 `--db`
112
+
113
+
## 三步渐进式检索
114
+
115
+
1. 如果用户给了项目名、cwd、时间窗，先缩范围：
116
+
117
+
```bash
118
+
"${CXS_BIN:-cxs}" list --cwd hammerspoon --since 2026-04-15 --json
119
+
```
120
+
121
+
如果用户说“本项目 / 这个 repo”，把 `<cwd>` 直接换成你当前工作目录路径。
122
+
123
+
2. 常规入口永远先 `find`，不要冷启 `read-page`：
124
+
125
+
```bash
126
+
"${CXS_BIN:-cxs}" find "cf tunnel" --json -n 5
127
+
```
128
+
129
+
先看这些字段：
130
+
131
+
- `results[].sessionUuid`
132
+
- `results[].matchSeq`
133
+
- `results[].cwd`
134
+
- `results[].startedAt`
135
+
- `results[].matchCount`
136
+
- `results[].summaryText`
137
+
- `results[].snippet`
138
+
139
+
3. 拿最像的候选做局部扩窗：
140
+
141
+
```bash
142
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --seq <matchSeq> --before 4 --after 8 --json
143
+
```
144
+
145
+
4. 如果你已经锁定某个 session，但想在它内部重定位锚点，用：
146
+
147
+
```bash
148
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --query "IME" --before 4 --after 8 --json
149
+
```
150
+
151
+
5. 只有在 `read-range` 仍不够时，才升级到整页浏览：
152
+
153
+
```bash
154
+
"${CXS_BIN:-cxs}" read-page <sessionUuid> --offset 0 --limit 40 --json
155
+
```
156
+
157
+
工作流心法：
158
+
159
+
- 永远先 `find`，不要直接 `read-page`
160
+
- 升级到 `read-page` 之前，先尝试放大 `--before/--after`
161
+
- 用户给出 `cwd` 或时间窗口时，优先 `list` 缩范围再 `read-range --query`
162
+
- `cwd` 只是候选过滤，不是主题真相；还要再看 `title`、`summaryText`、开头几条 message
163
+
- 同主题可能返回多个不同 `sessionUuid`；按 `cwd`、`startedAt`、`matchCount` 选，不要按 title 脑补去重
164
+
165
+
## JSON 模式速查
166
+
167
+
- `find --json`：顶层是 `{ query, results }`
168
+
- `read-range --json`：重点看 `anchorSeq`、`rangeStartSeq`、`rangeEndSeq`、`messages[]`
169
+
- `read-page --json`：重点看 `offset`、`limit`、`totalCount`、`hasMore`
170
+
- `list --json`：重点看 `results[].cwd`、`startedAt`、`endedAt`、`messageCount`
171
+
- `stats --json`：重点看 `lastSyncAt`、`dbPath`、`indexVersion`
172
+
- `sync --json`：重点看 `errors`、`errorDetails[]`
173
+
- 完整字段见：`references/json-schema.md`
174
+
175
+
## 常用排障
176
+
177
+
| 症状 | 先跑什么 | 怎么处理 |
178
+
| --- | --- | --- |
179
+
| `find` 零结果但用户坚持存在 | `stats --json` | 先看 `lastSyncAt`，必要时 `sync` |
180
+
| `sync` 非零退出 | `sync --json 2>&1` | 看 `errorDetails[]` |
181
+
| `stats/list/find` 报 `database is locked` | 同命令先重试一次 | 还是忙就先跳过 `stats` 直接读 |
182
+
| 同主题出现多条 uuid | `find -n 10 --json` | 按 `cwd`、`startedAt`、`matchCount` 选 |
183
+
| 用户问“最近本项目讨论了什么” | `list --cwd <current-repo> --sort ended --json` | `cwd` 只先圈候选，再抽样确认主题 |
184
+
| 中文关键词搜不到 | 换至少两字中文或英文关键词 | 详见 `references/failure-cookbook.md#cjk-zero-results` |
185
+
| 用户说“在 X 项目里” | `list --cwd X --json` | 先按 cwd 缩范围 |
186
+
| 从别的 cwd 调用找不到 db | `stats --json` | 看 `dbPath` 或显式传 `--db` |
187
+
188
+
## 参考
189
+
190
+
- `references/cli-surface.md`
191
+
- `references/json-schema.md`
192
+
- `references/progressive-workflow.md`
193
+
- `references/advanced-queries.md`
194
+
- `references/failure-cookbook.md`
195
+
196
+
# skill-sync: repo-shared cxs skill, PATH-or-CXS_BIN mode, 2026-04-22
+86
.agents/skills/cxs/references/advanced-queries.md
+86
.agents/skills/cxs/references/advanced-queries.md
···
1
+
# Advanced Queries
2
+
3
+
## 实际 query 语义
4
+
5
+
`cxs` 不是把用户输入原样透传给 SQLite FTS。当前行为是：
6
+
7
+
- 先把 query 做 tokenizer 处理
8
+
- 每个 term 都会被双引号包住
9
+
- term 与 term 之间一律用 `AND`
10
+
11
+
这意味着：
12
+
13
+
- 不要指望用户输入里的 `OR`、`NEAR`、`*`、引号按原生 FTS 运算符生效
14
+
- 空格分开的多词查询，本质上是“这些词都要进候选”
15
+
- 原始整句仍会参与 rerank，所以像 `health check` 这种自然短语仍然值得原样查询
16
+
17
+
对 agent 的含义：
18
+
19
+
- 先用自然关键词查询
20
+
- 关键词太宽时，增加第二个稳定词，而不是发明 FTS 运算符
21
+
22
+
## CJK / 中文行为
23
+
24
+
当前 tokenizer 对 CJK 的策略是：
25
+
26
+
- 中文/日文/韩文连续串按重叠 bigram 切分
27
+
- 单个 CJK 字不会成为有效 FTS term
28
+
- 如果 query 含 CJK 但 token 结果为空，会回退到有界 LIKE 扫描
29
+
30
+
实务建议：
31
+
32
+
- 单个汉字命中不稳，尽量用至少两字中文词
33
+
- 更稳的是“中文短词 + 英文标识符/报错”
34
+
- 中文零结果时，先换：
35
+
- 至少两字中文
36
+
- 英文关键词
37
+
- 项目名 / cwd 过滤
38
+
39
+
## 缩范围：什么时候 `list` 胜过 `find`
40
+
41
+
优先 `list` 的情况：
42
+
43
+
- 用户给了项目名、repo、cwd
44
+
- 用户给了大致日期或“前几天 / 那周 / 昨天”
45
+
- 用户只记得“在那个项目里做过”，却没有强关键词
46
+
47
+
典型做法：
48
+
49
+
```bash
50
+
"${CXS_BIN:-cxs}" list --cwd hammerspoon --since 2026-04-15 --json
51
+
```
52
+
53
+
然后对候选 session 再跑：
54
+
55
+
```bash
56
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --query "IME" --json
57
+
```
58
+
59
+
## 同 title 的多变体 session
60
+
61
+
Codex resume/fork 可能产生多个 title 很像、但 `sessionUuid` 不同的 session。当前 `find` 会保留这些 distinct sessions，不会按 title 折叠。
62
+
63
+
不要做的事：
64
+
65
+
- 不要假设 title 一样就是同一场会话
66
+
- 不要自己先按 title 去重再看内容
67
+
68
+
应该做的事：
69
+
70
+
- 按 `cwd`
71
+
- 按 `startedAt` / `endedAt`
72
+
- 按 `matchCount`
73
+
- 再决定是否继续 `read-range`
74
+
75
+
## `snippet` 高亮
76
+
77
+
- FTS path 的 `snippet` 会带 `<mark>...</mark>`
78
+
- LIKE fallback 也会自己补 `<mark>...</mark>`
79
+
- 如果下游需要纯文本，自己 strip
80
+
- 如果你在回答里要引用命中词，高亮保留也可以
81
+
82
+
## 来源
83
+
84
+
- 仓库内 `query.ts`
85
+
- 仓库内 `tokenize.ts`
86
+
- 仓库内 `ranking.ts`
+95
.agents/skills/cxs/references/cli-surface.md
+95
.agents/skills/cxs/references/cli-surface.md
···
1
+
# cxs CLI Surface
2
+
3
+
命令默认写法：
4
+
5
+
```bash
6
+
"${CXS_BIN:-cxs}" <subcommand> ...
7
+
```
8
+
9
+
如果你没有把 `cxs` 放进 `PATH`，先：
10
+
11
+
```bash
12
+
export CXS_BIN=/absolute/path/to/bin/cxs
13
+
```
14
+
15
+
## sync
16
+
17
+
Purpose: 扫描本地 `~/.codex/sessions` 并同步到 SQLite 索引。
18
+
19
+
Options:
20
+
21
+
| option | 说明 |
22
+
| --- | --- |
23
+
| `--root <dir>` | 覆盖 sessions 根目录 |
24
+
| `--db <path>` | 覆盖默认数据库 |
25
+
| `--best-effort` | 即使部分文件失败也继续写入成功部分 |
26
+
| `--json` | 成功时把 `SyncSummary` 打到 stdout |
27
+
28
+
Example:
29
+
30
+
```bash
31
+
"${CXS_BIN:-cxs}" sync --json
32
+
"${CXS_BIN:-cxs}" sync --json 2>&1
33
+
```
34
+
35
+
## find
36
+
37
+
Purpose: 搜索相关 session，返回最小必要命中。
38
+
39
+
Example:
40
+
41
+
```bash
42
+
"${CXS_BIN:-cxs}" find "cf tunnel" --json -n 5
43
+
```
44
+
45
+
## read-range
46
+
47
+
Purpose: 围绕命中点读取局部上下文。
48
+
49
+
Notes:
50
+
51
+
- 必须显式传 `<sessionUuid>`
52
+
- 必须二选一提供 `--seq` 或 `--query`
53
+
54
+
Example:
55
+
56
+
```bash
57
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --seq 12 --before 4 --after 8 --json
58
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --query "IME" --before 4 --after 8 --json
59
+
```
60
+
61
+
## read-page
62
+
63
+
Purpose: 顺序分页读取某个 session 的消息。
64
+
65
+
Example:
66
+
67
+
```bash
68
+
"${CXS_BIN:-cxs}" read-page <sessionUuid> --offset 0 --limit 40 --json
69
+
```
70
+
71
+
## list
72
+
73
+
Purpose: 列出已索引 session，不做全文检索。
74
+
75
+
Example:
76
+
77
+
```bash
78
+
"${CXS_BIN:-cxs}" list --cwd hammerspoon --since 2026-04-15 --sort ended --json
79
+
```
80
+
81
+
## stats
82
+
83
+
Purpose: 展示索引状态统计。
84
+
85
+
Example:
86
+
87
+
```bash
88
+
"${CXS_BIN:-cxs}" stats --json
89
+
```
90
+
91
+
## 来源
92
+
93
+
- 仓库内 `cli.ts`
94
+
- 仓库内 `env.ts`
95
+
- 仓库内 `README.md`
+78
.agents/skills/cxs/references/failure-cookbook.md
+78
.agents/skills/cxs/references/failure-cookbook.md
···
1
+
# Failure Cookbook
2
+
3
+
## 快速表
4
+
5
+
| 症状 | 先跑 | 处理 |
6
+
| --- | --- | --- |
7
+
| `find` 零结果但用户坚持存在 | `stats --json` | 看 `lastSyncAt`；必要时 `sync`；再试 `list --cwd` |
8
+
| `sync` 非零退出带 per-file errors | `sync --json 2>&1` | 看 `errorDetails[]`；默认严格模式；只在允许部分成功时加 `--best-effort` |
9
+
| `stats/list/find` 报 `database is locked` | 原命令重试一次 | 多半是 SQLite 忙；仍失败就先跳过 `stats` 直接读 |
10
+
| 同一主题多条 uuid | `find -n 10 --json` | 按 `startedAt`、`cwd`、`matchCount` 选 |
11
+
| 中文/CJK 零结果 | 无 | 换至少两字中文、英文关键词，或先 `list --since` |
12
+
| 用户问“最近本项目讨论了什么” | `list --cwd <current-repo> --sort ended --json` | `cwd` 先圈候选，再抽样读头尾确认主题 |
13
+
| 用户说“在 X 项目里” | `list --cwd X --json` | 先按 cwd 缩范围，再在候选里 `read-range --query` |
14
+
| 从其他 cwd 调用找不到 db | `stats --json` | 看 `dbPath`；必要时显式传 `--db` |
15
+
16
+
## Find zero results but user insists it exists
17
+
18
+
```bash
19
+
"${CXS_BIN:-cxs}" stats --json
20
+
```
21
+
22
+
如果 `lastSyncAt` 很旧，先：
23
+
24
+
```bash
25
+
"${CXS_BIN:-cxs}" sync
26
+
```
27
+
28
+
## Sync non-zero with per-file errors
29
+
30
+
```bash
31
+
"${CXS_BIN:-cxs}" sync --json 2>&1
32
+
```
33
+
34
+
处理规则：
35
+
36
+
- 默认不要忽略，先看是坏 JSONL、权限问题还是别的解析失败
37
+
- 只有用户明确接受 partial index 时，才用 `--best-effort`
38
+
39
+
## Database is locked or SQLITE_BUSY
40
+
41
+
- 先重试原命令一次
42
+
- 如果只是想读取历史，不一定非得先拿 `stats`
43
+
- 如果你刚跑过 `sync` 或怀疑别的进程正占着 db，先等一下再重试
44
+
45
+
## Current project discussion query
46
+
47
+
用户问“最近本项目讨论了什么”时，默认先用当前 repo 绝对路径：
48
+
49
+
```bash
50
+
"${CXS_BIN:-cxs}" list --cwd /absolute/path/to/current/repo --sort ended -n 8 --json
51
+
```
52
+
53
+
然后至少再看：
54
+
55
+
- `title`
56
+
- `summaryText`
57
+
- `read-page` 开头 6 到 8 条
58
+
- `read-page` 结尾 6 到 8 条
59
+
60
+
## Schema drift
61
+
62
+
source of truth 永远是：
63
+
64
+
- 仓库内 `types.ts`
65
+
- 仓库内 `cli.ts`
66
+
67
+
如果字段、命令、flag 变了：
68
+
69
+
- 先更新 `references/*.md`
70
+
- 再更新 `SKILL.md`
71
+
- 最后 bump `skill-sync` 日期
72
+
73
+
## 来源
74
+
75
+
- 仓库内 `cli.ts`
76
+
- 仓库内 `types.ts`
77
+
- 仓库内 `env.ts`
78
+
- 仓库内 `query.ts`
+141
.agents/skills/cxs/references/json-schema.md
+141
.agents/skills/cxs/references/json-schema.md
···
1
+
# cxs JSON Schema
2
+
3
+
## find
4
+
5
+
Top-level shape:
6
+
7
+
```ts
8
+
{
9
+
query: string;
10
+
results: FindResult[];
11
+
}
12
+
```
13
+
14
+
`FindResult`:
15
+
16
+
```ts
17
+
{
18
+
rank: number;
19
+
sessionUuid: string;
20
+
title: string;
21
+
summaryText: string;
22
+
cwd: string;
23
+
startedAt: string;
24
+
endedAt: string;
25
+
matchCount: number;
26
+
matchSeq: number;
27
+
matchRole: "user" | "assistant";
28
+
matchTimestamp: string;
29
+
score: number;
30
+
snippet: string;
31
+
}
32
+
```
33
+
34
+
## read-range
35
+
36
+
```ts
37
+
{
38
+
session: SessionRecord;
39
+
anchorSeq: number;
40
+
rangeStartSeq: number;
41
+
rangeEndSeq: number;
42
+
messages: MessageRecord[];
43
+
}
44
+
```
45
+
46
+
## read-page
47
+
48
+
```ts
49
+
{
50
+
session: SessionRecord;
51
+
offset: number;
52
+
limit: number;
53
+
totalCount: number;
54
+
hasMore: boolean;
55
+
messages: MessageRecord[];
56
+
}
57
+
```
58
+
59
+
## list
60
+
61
+
```ts
62
+
{
63
+
query: {
64
+
cwd?: string;
65
+
since?: string;
66
+
sort: "ended" | "started" | "messages";
67
+
limit: number;
68
+
};
69
+
results: SessionListEntry[];
70
+
}
71
+
```
72
+
73
+
## stats
74
+
75
+
```ts
76
+
{
77
+
sessionCount: number;
78
+
messageCount: number;
79
+
earliestStartedAt: string | null;
80
+
latestEndedAt: string | null;
81
+
topCwds: Array<{ cwd: string; count: number }>;
82
+
indexVersion: string;
83
+
dbPath: string;
84
+
dbSizeBytes: number;
85
+
lastSyncAt: string | null;
86
+
}
87
+
```
88
+
89
+
## sync
90
+
91
+
```ts
92
+
{
93
+
scanned: number;
94
+
added: number;
95
+
updated: number;
96
+
skipped: number;
97
+
filtered: number;
98
+
errors: number;
99
+
errorDetails: Array<{
100
+
filePath: string;
101
+
message: string;
102
+
}>;
103
+
}
104
+
```
105
+
106
+
## Shared Records
107
+
108
+
`SessionRecord`:
109
+
110
+
```ts
111
+
{
112
+
sessionUuid: string;
113
+
filePath: string;
114
+
title: string;
115
+
summaryText: string;
116
+
cwd: string;
117
+
model: string;
118
+
startedAt: string;
119
+
endedAt: string;
120
+
messageCount: number;
121
+
}
122
+
```
123
+
124
+
`MessageRecord`:
125
+
126
+
```ts
127
+
{
128
+
sessionUuid: string;
129
+
seq: number;
130
+
role: "user" | "assistant";
131
+
contentText: string;
132
+
timestamp: string;
133
+
sourceKind: string;
134
+
}
135
+
```
136
+
137
+
## 来源
138
+
139
+
- 仓库内 `types.ts`
140
+
- 仓库内 `cli.ts`
141
+
- 仓库内 `query.ts`
+73
.agents/skills/cxs/references/progressive-workflow.md
+73
.agents/skills/cxs/references/progressive-workflow.md
···
1
+
# Progressive Workflow
2
+
3
+
## 默认三步
4
+
5
+
1. `find` 拿候选 session 和命中锚点
6
+
2. `read-range` 在最佳候选周围扩局部上下文
7
+
3. `read-page` 只在局部窗口仍不够时翻整页
8
+
9
+
硬规则：
10
+
11
+
- 没有 `sessionUuid` 时，不要冷启动 `read-page`
12
+
- 用户给了 `cwd` 或时间窗口时，先 `list`
13
+
- 已锁定 session 但锚点不对时，用 `read-range --query`
14
+
- `cwd` 只是候选过滤，不是主题真相；还要再看 `title`、`summaryText` 和开头几条 message
15
+
16
+
## Worked Scenario 1
17
+
18
+
用户说：`上次我配 cf tunnel 是怎么弄的`
19
+
20
+
```bash
21
+
"${CXS_BIN:-cxs}" find "cf tunnel" --json -n 5
22
+
```
23
+
24
+
然后：
25
+
26
+
```bash
27
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --seq <matchSeq> --before 4 --after 8 --json
28
+
```
29
+
30
+
只有 `read-range` 还缺前情后果时，再：
31
+
32
+
```bash
33
+
"${CXS_BIN:-cxs}" read-page <sessionUuid> --offset 0 --limit 40 --json
34
+
```
35
+
36
+
## Worked Scenario 2
37
+
38
+
用户说：`我记得前几天在 hammerspoon 那个 repo 里试过 IME 切换`
39
+
40
+
先按 cwd + 时间缩范围：
41
+
42
+
```bash
43
+
"${CXS_BIN:-cxs}" list --cwd hammerspoon --since 2026-04-15 --json
44
+
```
45
+
46
+
再在候选 session 内局部重定位：
47
+
48
+
```bash
49
+
"${CXS_BIN:-cxs}" read-range <sessionUuid> --query "IME" --before 4 --after 8 --json
50
+
```
51
+
52
+
## Worked Scenario 3
53
+
54
+
用户说：`最近本项目有做过什么讨论`
55
+
56
+
先按当前 repo 路径列最近 session：
57
+
58
+
```bash
59
+
"${CXS_BIN:-cxs}" list --cwd /absolute/path/to/current/repo --sort ended -n 8 --json
60
+
```
61
+
62
+
不要把 `cwd` 直接当主题真相。至少再看：
63
+
64
+
- `title`
65
+
- `summaryText`
66
+
- 开头几条 message
67
+
- 结尾几条 message
68
+
69
+
## 来源
70
+
71
+
- 仓库内 `README.md`
72
+
- 仓库内 `query.ts`
73
+
- 仓库内 `types.ts`
+17
AGENTS.md
+17
AGENTS.md
···
45
45
- `docs/` 里的文档要服务后续 agent 直接接手，而不是保留调研过程痕迹
46
46
- 任何涉及“当前已实现什么”的文档，都必须先对齐代码和测试
47
47
48
+
## 项目共享 Skill
49
+
50
+
仓库内维护项目共享 skill：
51
+
52
+
- `.agents/skills/cxs`
53
+
54
+
对外推荐安装方式：
55
+
56
+
```bash
57
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
58
+
```
59
+
60
+
注意这个 skill 不会自动安装 `cxs` CLI 本体。默认约定：
61
+
62
+
- 优先使用 `CXS_BIN`
63
+
- 未设置时回退到 `PATH` 里的 `cxs`
64
+
48
65
## 默认验证
49
66
50
67
涉及实现或文档真相变更时，至少做与改动直接相关的验证：
+38
README.md
+38
README.md
···
181
181
- 项目规则见 [AGENTS.md](AGENTS.md)
182
182
- 协作说明见 [CONTRIBUTING.md](CONTRIBUTING.md)
183
183
- 当前公开目标是“可接手、可验证、可继续演进”的源码仓库，不承诺 npm 发布流程稳定
184
+
185
+
## 配套 Skill
186
+
187
+
仓库内自带一个项目共享 skill：
188
+
189
+
- `.agents/skills/cxs`
190
+
191
+
推荐用 `npx skills add` 安装，而不是手动复制：
192
+
193
+
```bash
194
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
195
+
```
196
+
197
+
如果只想先看仓库里有哪些 skill：
198
+
199
+
```bash
200
+
npx skills add catoncat/cxs --list
201
+
```
202
+
203
+
推荐顺序：
204
+
205
+
1. 先安装 / 配置 `cxs` CLI
206
+
2. 再用 `npx skills add` 安装 skill
207
+
208
+
最稳的本地方式：
209
+
210
+
```bash
211
+
git clone https://github.com/catoncat/cxs.git
212
+
cd cxs
213
+
bun install
214
+
export CXS_BIN="$PWD/bin/cxs"
215
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
216
+
```
217
+
218
+
注意：
219
+
220
+
- `npx skills add` 只安装 skill，不负责安装外部 CLI
221
+
- 最稳的做法是先让 `cxs` 命令可执行，或设置 `CXS_BIN=/absolute/path/to/bin/cxs`