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(cxs): 补充首次同步说明
Entire-Checkpoint: 5b3225ca78b6
+43
-3
+1
-1
.agents/skills/cxs/SKILL.md
+1
-1
.agents/skills/cxs/SKILL.md
···
59
59
## 前置
60
60
61
61
- 先 `stats --json` 看 `dbPath / lastSyncAt / sessionCount`
62
-
- 索引不存在或 `lastSyncAt` 很旧 → `sync`(默认严格模式;只有用户接受部分成功才加 `--best-effort`)
62
+
- 索引不存在、读命令返回 `index_unavailable`、或 `lastSyncAt` 很旧 → `sync`(默认严格模式;只有用户接受部分成功才加 `--best-effort`)
63
63
- `current` 不依赖 cxs 索引,即使 sync 没跑过也能用
64
64
- 从别的 cwd 调用时,若默认 db 不对,显式传 `--db`
65
65
+8
.agents/skills/cxs/references/cli-surface.md
+8
.agents/skills/cxs/references/cli-surface.md
···
12
12
export CXS_BIN=/absolute/path/to/bin/cxs
13
13
```
14
14
15
+
没有单独的 `init` 命令。首次安装后先跑 `sync`;如果是一次性 npx 调用,先跑 `npx @act0r/cxs sync`。
16
+
17
+
缺少 cxs 索引时,`find` / `read-range` / `read-page` / `list` / `stats --json` 返回:
18
+
19
+
```json
20
+
{ "error": { "code": "index_unavailable", "message": "...", "dbPath": "...", "hint": "..." } }
21
+
```
22
+
15
23
## current
16
24
17
25
Purpose: 直读 Codex state SQLite,按 cwd 拿候选 session,**不依赖 cxs 自己的索引**(适合 sync 没跑过或刚换机器的场景)。
+27
-2
.agents/skills/cxs/references/failure-cookbook.md
+27
-2
.agents/skills/cxs/references/failure-cookbook.md
···
6
6
| --- | --- | --- |
7
7
| `find` 零结果但用户坚持存在 | `stats --json` | 看 `lastSyncAt`；必要时 `sync`；再试 `list --cwd` |
8
8
| `sync` 非零退出带 per-file errors | `sync --json 2>&1` | 看 `errorDetails[]`；默认严格模式；只在允许部分成功时加 `--best-effort` |
9
+
| `find/list/stats/read-*` 输出 `index_unavailable` | `sync` | cxs 索引还没建立；没有单独 `init`，`sync` 就是建库入口 |
9
10
| `stats/list/find` 报 `database is locked` | 原命令重试一次 | 多半是 SQLite 忙；仍失败就先跳过 `stats` 直接读 |
10
11
| 同一主题多条 uuid | `find -n 10 --json` | 按 `startedAt`、`cwd`、`matchCount` 选 |
11
12
| 中文/CJK 零结果 | 无 | 换至少两字中文、英文关键词，或先 `list --since` |
···
37
38
- 默认不要忽略，先看是坏 JSONL、权限问题还是别的解析失败
38
39
- 只有用户明确接受 partial index 时，才用 `--best-effort`
39
40
41
+
## index_unavailable
42
+
43
+
`find` / `read-range` / `read-page` / `list` / `stats` 都读 cxs 自己的 SQLite 索引。第一次安装后还没跑过 `sync` 时,这些命令会在 `--json` 模式下返回:
44
+
45
+
```json
46
+
{
47
+
"error": {
48
+
"code": "index_unavailable",
49
+
"message": "index not found: ...",
50
+
"dbPath": "...",
51
+
"hint": "Run `cxs sync` first ..."
52
+
}
53
+
}
54
+
```
55
+
56
+
处理方式:
57
+
58
+
```bash
59
+
"${CXS_BIN:-cxs}" sync
60
+
```
61
+
62
+
没有单独 `init` 命令;`sync` 会创建并更新索引。如果用户是一次性 `npx @act0r/cxs find ...`,提示他先跑 `npx @act0r/cxs sync`。
63
+
40
64
## Database is locked or SQLITE_BUSY
41
65
42
66
- 先重试原命令一次
···
85
109
| `sync`(per-file 错) | stderr | `SyncSummary`,看 `errors / errorDetails[]` |
86
110
| `sync`(锁超时 `SyncLockTimeoutError`) | stderr | `{ "error": <message string> }` |
87
111
| `current`(state DB 问题) | stdout | `{ "error": { "code": "state_db_unavailable", "message": "..." } }` |
88
-
| `find / read-range / read-page / list / stats` 异常 | 进程异常退出 | 当前未结构化,直接非零退出 |
112
+
| `find / read-range / read-page / list / stats`(索引不存在) | stdout | `{ "error": { "code": "index_unavailable", "message": "...", "dbPath": "...", "hint": "..." } }` |
113
+
| `find / read-range / read-page / list / stats`(其他异常) | 进程异常退出 | 直接非零退出 |
89
114
90
-
**实务**:解析前先看 exit code;非零再判断是结构化(`current`)还是字符串(`sync` 锁超时)还是 summary(`sync` per-file)。
115
+
**实务**:解析前先看 exit code;非零再判断是结构化(`current` / 缺索引读命令)还是字符串(`sync` 锁超时)还是 summary(`sync` per-file)。
91
116
92
117
## Schema drift
93
118
+7
README.md
+7
README.md
···
72
72
cxs stats --json
73
73
```
74
74
75
+
没有单独的 `init` 命令；`sync` 会创建并更新索引。若直接用 `npx` 试跑:
76
+
77
+
```bash
78
+
npx @act0r/cxs sync
79
+
npx @act0r/cxs find "health check"
80
+
```
81
+
75
82
`--help` 应列出 `sync` / `find` / `read-range` / `read-page` / `list` / `stats` / `current`。
76
83
77
84
### 数据目录