csm-cli 0.1.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,3 +13,6 @@ venv/
13
13
 
14
14
  # macOS
15
15
  .DS_Store
16
+
17
+ # Claude Code worktrees(开发工作流目录)
18
+ .claude/
@@ -0,0 +1,52 @@
1
+ # Changelog
2
+
3
+ ## 0.3.0 (2026-11-22)
4
+
5
+ ### 会话进度(B)
6
+ - 「做到哪了」一眼可见:列表徽标 `3/7`(TodoWrite 最新快照,双口径取最后一条)+ 📋(plan 文档关联)
7
+ - 数据双源:`TodoWrite` tool_use(标准格式,向前兼容)+ jsonl 行内 `attachment.planFilePath`(本机实测 9/9 plan 文档关联命中)
8
+ - 尾窗倒序三目标齐停(title/todos/plan),`*_scanned_full` 标记位控制全扫兜底——沿用既有渐进扫描模式
9
+ - 三端展示:TUI 徽标 + 预览待办清单;Web 徽标(hover 清单)+ 详情栏清单(completed 划线、in_progress 高亮);`--list --json` 字段输出
10
+
11
+ ### 跨会话全文检索(C)
12
+ - 「那个讨论 X 的会话在哪」:TUI `?词1 词2` / Web 搜索框 `?` / `csm --full-text`——消息正文级搜索
13
+ - sqlite FTS5 trigram 增量索引(stdlib 零新依赖),存 `~/.claude/csm/index.db`;消息级文本 = 用户输入 / assistant 文本 / 工具名+摘要+结果摘要
14
+ - **会话级 AND**:多词可命中不同消息;子串匹配中文 2 字词可搜;≥3 字符自动走 trigram 索引
15
+ - 失效粒度 (mtime, size):TUI 30s 重扫 / Web 5s 空闲轮增量重建;实测 86 会话 / 208MB 全量首建 1.4s,查询 <60ms
16
+ - WAL 双连接(写/读分离):建索引期间搜索不阻塞;FTS5 缺失环境整体降级不影响其他功能
17
+
18
+ ## 0.2.0 (2026-11-22)
19
+
20
+ - TUI `g` 跳转:定位会话所在终端并直达——tmux 按 tty 反查 pane(csm 在 tmux 内 `switch-client` 瞬移、在外 `execvp` 让位 `attach`)、iTerm2/Terminal.app AppleScript 聚焦、全 miss 降级提示(`fmt.fallback_location_hint`)
21
+ - 修复 tty 口径漂移:`current_terminal_tty()` 快路径返回的 `os.ttyname` 带 `/dev/` 前缀,与 ps 快照的无前缀口径不一致,导致直接在终端运行 csm 时 ◉本终端标记与双开保护的本终端豁免恒不命中;现统一归一化为 ps 口径
22
+
23
+ ## 0.1.0 (2026-11-22)
24
+
25
+ 首个正式发布。四轮功能迭代汇总:
26
+
27
+ ### 核心:会话浏览与切换
28
+ - 全局列出所有项目的 Claude 会话(mtime 排序,AI 标题 + 首条输入摘要)
29
+ - TUI:输入即过滤(多词 AND)、`#标签` 语法、回车直接 `claude --resume`(先 cd 原项目目录)
30
+ - 三种前端:prompt_toolkit TUI(默认)、本地 Web(`csm serve`)、rich 表格(`--list`/`--json`)
31
+ - resume 双开保护:会话活在他终端时警告确认;`--new [PATH]` 直接起新会话
32
+
33
+ ### 会话预览
34
+ - TUI `Tab` 预览视图 + Web 侧栏对话流:用户输入 / 助手回复 / 工具调用折叠行
35
+ - 消息流解析:assistant 跨行分段合并、tool_result 100% 回填、行级 diff(Edit/Write/MultiEdit)
36
+ - Web 消息 Markdown 渲染(代码块/表格/列表等,先转义再白名单转换,免疫 XSS)
37
+ - 大文件(14MB)解析 ~30ms,LRU 缓存(mtime/size 失效)
38
+
39
+ ### 分类与收藏
40
+ - 分类过滤(数字键 1-6 / Web chips):全部/运行中/本终端/已关闭/单轮/收藏
41
+ - tty 关联识别「本终端」(ps 快照 + PPID 链上溯,tmux 精确到 pane);worktree 会话显示分支与未合并提交数
42
+ - 收藏两档(⭐/★)永久置顶 + 自定义标签,存 `~/.claude/csm/favorites.json`(TUI/Web 互通)
43
+ - `claude -p` 无法从官方数据识别(entrypoint 不可区分,二进制验证)——「单轮」为客观近似
44
+
45
+ ### Web 服务与守护
46
+ - `csm serve`:前台运行或 daemon(`start`/`stop`/`status`/`restart`,pidfile + 日志)
47
+ - `csm serve install-launchd`:macOS 开机自启 + 崩溃自动拉起
48
+ - 新会话 ≤5s 自动出现(前端轮询 + 服务端 stat 级增量 diff);深浅色跟随系统
49
+
50
+ ### 工程
51
+ - Python ≥3.10;PyPI 包 `csm-cli`(命令名 `csm`);GitHub Actions Trusted Publishing
52
+ - 56 个离线单测(假数据注入,不碰真实 `~/.claude`)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: csm-cli
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Claude Code 会话管理器:一屏浏览/过滤/收藏全部会话,回车 resume;TUI + 本地 Web 界面
5
5
  Project-URL: Homepage, https://github.com/cainli/csm
6
6
  Project-URL: Issues, https://github.com/cainli/csm/issues
@@ -32,7 +32,7 @@ Description-Content-Type: text/markdown
32
32
 
33
33
  终端里开了一堆 Claude 会话分不清哪个是哪个?`csm` 一屏列出**全局所有项目**的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤,回车直接 resume。
34
34
 
35
- - **只读**:对 `~/.claude` 严格只读,绝不写入或清理用户数据(唯一可写的是 csm 自有的收藏文件)
35
+ - **只读**:对 `~/.claude` 用户数据严格只读,绝不写入或清理(仅可写 csm 自有的 `~/.claude/csm/`:收藏与全文索引)
36
36
  - **轻量**:Python ≥ 3.10;`prompt_toolkit`/`rich` 随包安装,开箱即用
37
37
  - **发射后不管**:resume 用 `execvp` 接管进程,csm 不持有、不托管任何会话(Web 后台服务除外,见 `serve`)
38
38
 
@@ -51,6 +51,9 @@ Description-Content-Type: text/markdown
51
51
  | 对话流预览(Markdown 渲染 + 工具调用折叠) | ✅ Tab 最近 50 条 | ✅ 完整分页 | — |
52
52
  | **Edit/Write/MultiEdit 行级 diff**(红删绿增) | — | ✅ 完整级别 | — |
53
53
  | **双开保护**(活会话在他终端 → 确认拦截) | ✅ | — | — |
54
+ | **跳转 `g`**(直达会话所在终端:tmux switch-client/attach · iTerm2/Terminal 聚焦) | ✅ | — | — |
55
+ | **会话进度**(TodoWrite `3/7` 快照 + 📋 plan 文档关联) | ✅ 徽标/预览清单 | ✅ 徽标/详情清单 | ✅ 字段 |
56
+ | **跨会话全文检索**(`?词1 词2` / `--full-text`;FTS5 trigram,中文 2 字可搜,会话级 AND) | ✅ footer 摘要 | ✅ 行内摘要 | ✅ 表格/JSON |
54
57
  | 复制 resume 命令(终端/tmux/headless 三变体) | — | ✅ | — |
55
58
  | SDK 子进程会话标记(`sdk-cli` → SDK) | ✅ | ✅ | ✅ |
56
59
  | **Web 后台守护**(`csm serve start/stop/status`,launchd 开机自启) | — | ✅ | — |
@@ -91,6 +94,7 @@ csm --list # 终端表格;csm --list --json | jq '.[] | .title'
91
94
  csm # 交互式 TUI(默认;stdout 非 tty 时自动降级 --list)
92
95
  csm --list # 非交互表格
93
96
  csm --list --json # JSON 输出,可配 jq
97
+ csm --full-text "登录超时" # 跨会话全文检索(首次自动建索引 ~2s,之后增量)
94
98
  csm --list --full-scan # 表格带完整消息数(较慢 ~0.6s)
95
99
  csm --project voicemouse # 按项目路径过滤(大小写不敏感)
96
100
  csm --new [PATH] # 在 PATH(默认当前目录)起新会话,不进列表
@@ -118,7 +122,7 @@ launchd 模式日志在 `~/.claude/csm/launchd.{out,err}.log`;停 launchd 管
118
122
  ## TUI
119
123
 
120
124
  ```
121
- csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 Tab预览 ^L清空 ^R重扫 esc退出
125
+ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 g跳转 Tab预览 ^L清空 ^R重扫 esc退出
122
126
  ◉★ 11:20 ●busy 修复登录超时问题 #线上 claude-tools/fleet-features 12 757f8670-…
123
127
  10:29 ●idle Orca 多 Agent 开发环境 swain 8 892a5d70-…
124
128
  ```
@@ -132,6 +136,7 @@ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星
132
136
  | 直接打字 | 过滤(标题/首输入/项目路径/SID,多词 AND;`#标签` 精确筛) | 同左 |
133
137
  | `1`-`6` | **分类过滤**:全部/运行中/本终端/收藏/已关闭/单轮 | — |
134
138
  | `s` | **星标循环**:无 → ⭐ → ★ → 无(收藏永久置顶) | — |
139
+ | `g` | **跳转**到会话所在终端(见下) | — |
135
140
  | `Tab` | **进入会话预览**(最近 50 条消息流) | 返回列表(保持原选择) |
136
141
  | `Enter` | resume 选中会话(先 cd 到原项目目录;见他终端运行会触发双开确认) | resume 该会话 |
137
142
  | `Ctrl-L` / `Ctrl-R` | 清空过滤 / 重新扫描 | 清空 / 刷新预览 |
@@ -158,6 +163,14 @@ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星
158
163
 
159
164
  resume 一个正在**其他终端**运行的会话时,csm 警告并要求确认——两处同时写入同一会话文件(jsonl)可能导致内容交叉错乱。本终端运行的会话不拦;tty 无法识别时宁可误拦。
160
165
 
166
+ ### 跳转 `g`:会话在哪,就去哪
167
+
168
+ 双开保护的另一半答案:不另起一份,而是**直达会话正在运行的终端**。按目标环境自动选择(全部只读查询):
169
+
170
+ - 会话在 **tmux**(任意 session):按 tty 反查 pane。csm 自己也在 tmux → `switch-client` 瞬移(csm 存活,随时切回列表);不在 → `execvp` 让位给 `tmux attach`(resume 同款哲学)
171
+ - 会话在 **iTerm2 / Terminal.app**:AppleScript 按 tty 找到 tab/窗口并置前
172
+ - 都不是:降级提示 tty(`fmt.fallback_location_hint`)
173
+
161
174
  ### `--new`:快速发射
162
175
 
163
176
  `csm --new ~/dev/workspace/swain` 直接在该目录起新会话。与 resume 同为 `execvp` 接管——csm 始终不持有会话进程。
@@ -172,10 +185,25 @@ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确
172
185
 
173
186
  ## 收藏与标签
174
187
 
175
- - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间,唯一可写文件;原子写 + 跨进程锁)
188
+ - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间;原子写 + 跨进程锁)
176
189
  - 星标两档:⭐ 普通收藏 / ★ 重要;永久置顶(★ 段前于 ⭐ 段,段内按活跃时间)
177
190
  - 标签在 Web 详情栏添加;搜索 `#标签名` 精确筛(多标签 AND);TUI 与 Web 双向同步(≤30s)
178
191
 
192
+ ## 全文检索
193
+
194
+ 「那个讨论 SSE 重连的会话在哪?」——元数据过滤够不着消息正文时,用 `?` 前缀进入全文模式:
195
+
196
+ - **TUI**:直接输入 `?词1 词2`——结果按命中数降序,footer 显示首条命中摘要;与数字键分类过滤叠加
197
+ - **Web**:搜索框 `?词`——命中行内联摘要(accent 色),按命中数重排,退出 `?` 模式即恢复置顶序
198
+ - **CLI**:`csm --full-text "词1 词2"`(`--json` 同样适用,管道友好)
199
+
200
+ 机制:sqlite **FTS5 trigram** 增量索引(stdlib,零新依赖):
201
+
202
+ - 索引存 `~/.claude/csm/index.db`(csm 自有可写区,与 favorites 同级);消息级文本 = 用户输入 / assistant 文本 / 工具名+摘要+结果摘要
203
+ - **会话级 AND**:多词可命中不同消息,会话须命中所有词;子串匹配,中文 2 字词可搜(trigram 表上 LIKE,≥3 字符自动走索引)
204
+ - 失效粒度文件 (mtime, size):TUI 30s 重扫 / Web 5s 空闲轮增量重建,实测 86 会话 / 208MB 全量首建 **1.4s**,查询 <60ms
205
+ - FTS5 不可用的环境整体降级(`?` 搜索返回空并提示),不影响其他功能
206
+
179
207
  ## 分类口径(诚实声明)
180
208
 
181
209
  - **运行状态**:busy/idle/waiting 来自 Claude 活跃注册表,pid 三重判活(存活 + 进程名含 claude + 启动时间容差比对)防 pid 复用;已关闭 = jsonl 在而注册表无活记录
@@ -189,7 +217,9 @@ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确
189
217
  | `~/.claude/projects/*/*.jsonl` | 会话转录;文件名即 Session ID;标题取最后一条 `ai-title`;行内 `cwd`/`entrypoint` |
190
218
  | `~/.claude/sessions/*.json` | 运行中会话注册表 → 状态 + tty 关联 |
191
219
  | `~/.claude/history.jsonl` | 无标题会话的首条输入回退 |
192
- | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(唯一可写) |
220
+ | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(可写) |
221
+ | `~/.claude/csm/index.db` | **csm 自有**:全文检索 FTS5 索引(可写,自动维护) |
222
+ | `~/.claude/plans/*.md` | plan mode 文档;经 jsonl 行内 `attachment.planFilePath` 关联(只读) |
193
223
 
194
224
  进程信息:单次 `ps -axo pid,ppid,tty,lstart,command` 快照三用(会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端)。
195
225
  支持 `CLAUDE_CONFIG_DIR` 重定向配置目录(测试注入用)。
@@ -206,6 +236,6 @@ python3 -m pytest # 全部单测:离线假数据 + 真 git worktree 集成
206
236
 
207
237
  - 包布局 `src/csm_cli/`:`cli.py` 入口/CLI/resume/双开保护 · `scanner.py` 数据层+消息解析(唯一文件 I/O)·
208
238
  `ui.py` TUI · `web.py` Web 服务端 · `web.html` Web 前端(单文件,无构建,importlib.resources 读取)·
209
- `serve.py` 守护进程 · `fmt.py` 纯函数格式化;仓库根 `csm.py` 为兼容 shim
239
+ `serve.py` 守护进程 · `fmt.py` 纯函数格式化 · `ftsearch.py` 全文检索(FTS5 索引);仓库根 `csm.py` 为兼容 shim
210
240
  - `fmt.py` 中 `rel_time()` / `fuzzy_score()` 为故意留空的降级实现(学习场景),实装后 `test_fmt.py` 的 `skipif` 自动生效
211
241
  - `web.html` 顶部 CSS 变量可整体换肤;打包见 `pyproject.toml`(hatchling,`csm-cli`)
@@ -2,7 +2,7 @@
2
2
 
3
3
  终端里开了一堆 Claude 会话分不清哪个是哪个?`csm` 一屏列出**全局所有项目**的 Claude 会话——AI 生成的标题、首条输入、运行状态、所属项目、消息轮数、worktree 归属、Session ID——输入即过滤,回车直接 resume。
4
4
 
5
- - **只读**:对 `~/.claude` 严格只读,绝不写入或清理用户数据(唯一可写的是 csm 自有的收藏文件)
5
+ - **只读**:对 `~/.claude` 用户数据严格只读,绝不写入或清理(仅可写 csm 自有的 `~/.claude/csm/`:收藏与全文索引)
6
6
  - **轻量**:Python ≥ 3.10;`prompt_toolkit`/`rich` 随包安装,开箱即用
7
7
  - **发射后不管**:resume 用 `execvp` 接管进程,csm 不持有、不托管任何会话(Web 后台服务除外,见 `serve`)
8
8
 
@@ -21,6 +21,9 @@
21
21
  | 对话流预览(Markdown 渲染 + 工具调用折叠) | ✅ Tab 最近 50 条 | ✅ 完整分页 | — |
22
22
  | **Edit/Write/MultiEdit 行级 diff**(红删绿增) | — | ✅ 完整级别 | — |
23
23
  | **双开保护**(活会话在他终端 → 确认拦截) | ✅ | — | — |
24
+ | **跳转 `g`**(直达会话所在终端:tmux switch-client/attach · iTerm2/Terminal 聚焦) | ✅ | — | — |
25
+ | **会话进度**(TodoWrite `3/7` 快照 + 📋 plan 文档关联) | ✅ 徽标/预览清单 | ✅ 徽标/详情清单 | ✅ 字段 |
26
+ | **跨会话全文检索**(`?词1 词2` / `--full-text`;FTS5 trigram,中文 2 字可搜,会话级 AND) | ✅ footer 摘要 | ✅ 行内摘要 | ✅ 表格/JSON |
24
27
  | 复制 resume 命令(终端/tmux/headless 三变体) | — | ✅ | — |
25
28
  | SDK 子进程会话标记(`sdk-cli` → SDK) | ✅ | ✅ | ✅ |
26
29
  | **Web 后台守护**(`csm serve start/stop/status`,launchd 开机自启) | — | ✅ | — |
@@ -61,6 +64,7 @@ csm --list # 终端表格;csm --list --json | jq '.[] | .title'
61
64
  csm # 交互式 TUI(默认;stdout 非 tty 时自动降级 --list)
62
65
  csm --list # 非交互表格
63
66
  csm --list --json # JSON 输出,可配 jq
67
+ csm --full-text "登录超时" # 跨会话全文检索(首次自动建索引 ~2s,之后增量)
64
68
  csm --list --full-scan # 表格带完整消息数(较慢 ~0.6s)
65
69
  csm --project voicemouse # 按项目路径过滤(大小写不敏感)
66
70
  csm --new [PATH] # 在 PATH(默认当前目录)起新会话,不进列表
@@ -88,7 +92,7 @@ launchd 模式日志在 `~/.claude/csm/launchd.{out,err}.log`;停 launchd 管
88
92
  ## TUI
89
93
 
90
94
  ```
91
- csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 Tab预览 ^L清空 ^R重扫 esc退出
95
+ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星标 g跳转 Tab预览 ^L清空 ^R重扫 esc退出
92
96
  ◉★ 11:20 ●busy 修复登录超时问题 #线上 claude-tools/fleet-features 12 757f8670-…
93
97
  10:29 ●idle Orca 多 Agent 开发环境 swain 8 892a5d70-…
94
98
  ```
@@ -102,6 +106,7 @@ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星
102
106
  | 直接打字 | 过滤(标题/首输入/项目路径/SID,多词 AND;`#标签` 精确筛) | 同左 |
103
107
  | `1`-`6` | **分类过滤**:全部/运行中/本终端/收藏/已关闭/单轮 | — |
104
108
  | `s` | **星标循环**:无 → ⭐ → ★ → 无(收藏永久置顶) | — |
109
+ | `g` | **跳转**到会话所在终端(见下) | — |
105
110
  | `Tab` | **进入会话预览**(最近 50 条消息流) | 返回列表(保持原选择) |
106
111
  | `Enter` | resume 选中会话(先 cd 到原项目目录;见他终端运行会触发双开确认) | resume 该会话 |
107
112
  | `Ctrl-L` / `Ctrl-R` | 清空过滤 / 重新扫描 | 清空 / 刷新预览 |
@@ -128,6 +133,14 @@ csm — 77 会话 (22 运行中) ★3 ⭐7 过滤:全部 68/77 1-6过滤 s星
128
133
 
129
134
  resume 一个正在**其他终端**运行的会话时,csm 警告并要求确认——两处同时写入同一会话文件(jsonl)可能导致内容交叉错乱。本终端运行的会话不拦;tty 无法识别时宁可误拦。
130
135
 
136
+ ### 跳转 `g`:会话在哪,就去哪
137
+
138
+ 双开保护的另一半答案:不另起一份,而是**直达会话正在运行的终端**。按目标环境自动选择(全部只读查询):
139
+
140
+ - 会话在 **tmux**(任意 session):按 tty 反查 pane。csm 自己也在 tmux → `switch-client` 瞬移(csm 存活,随时切回列表);不在 → `execvp` 让位给 `tmux attach`(resume 同款哲学)
141
+ - 会话在 **iTerm2 / Terminal.app**:AppleScript 按 tty 找到 tab/窗口并置前
142
+ - 都不是:降级提示 tty(`fmt.fallback_location_hint`)
143
+
131
144
  ### `--new`:快速发射
132
145
 
133
146
  `csm --new ~/dev/workspace/swain` 直接在该目录起新会话。与 resume 同为 `execvp` 接管——csm 始终不持有会话进程。
@@ -142,10 +155,25 @@ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确
142
155
 
143
156
  ## 收藏与标签
144
157
 
145
- - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间,唯一可写文件;原子写 + 跨进程锁)
158
+ - 存储在 `~/.claude/csm/favorites.json`(csm 自有命名空间;原子写 + 跨进程锁)
146
159
  - 星标两档:⭐ 普通收藏 / ★ 重要;永久置顶(★ 段前于 ⭐ 段,段内按活跃时间)
147
160
  - 标签在 Web 详情栏添加;搜索 `#标签名` 精确筛(多标签 AND);TUI 与 Web 双向同步(≤30s)
148
161
 
162
+ ## 全文检索
163
+
164
+ 「那个讨论 SSE 重连的会话在哪?」——元数据过滤够不着消息正文时,用 `?` 前缀进入全文模式:
165
+
166
+ - **TUI**:直接输入 `?词1 词2`——结果按命中数降序,footer 显示首条命中摘要;与数字键分类过滤叠加
167
+ - **Web**:搜索框 `?词`——命中行内联摘要(accent 色),按命中数重排,退出 `?` 模式即恢复置顶序
168
+ - **CLI**:`csm --full-text "词1 词2"`(`--json` 同样适用,管道友好)
169
+
170
+ 机制:sqlite **FTS5 trigram** 增量索引(stdlib,零新依赖):
171
+
172
+ - 索引存 `~/.claude/csm/index.db`(csm 自有可写区,与 favorites 同级);消息级文本 = 用户输入 / assistant 文本 / 工具名+摘要+结果摘要
173
+ - **会话级 AND**:多词可命中不同消息,会话须命中所有词;子串匹配,中文 2 字词可搜(trigram 表上 LIKE,≥3 字符自动走索引)
174
+ - 失效粒度文件 (mtime, size):TUI 30s 重扫 / Web 5s 空闲轮增量重建,实测 86 会话 / 208MB 全量首建 **1.4s**,查询 <60ms
175
+ - FTS5 不可用的环境整体降级(`?` 搜索返回空并提示),不影响其他功能
176
+
149
177
  ## 分类口径(诚实声明)
150
178
 
151
179
  - **运行状态**:busy/idle/waiting 来自 Claude 活跃注册表,pid 三重判活(存活 + 进程名含 claude + 启动时间容差比对)防 pid 复用;已关闭 = jsonl 在而注册表无活记录
@@ -159,7 +187,9 @@ resume 一个正在**其他终端**运行的会话时,csm 警告并要求确
159
187
  | `~/.claude/projects/*/*.jsonl` | 会话转录;文件名即 Session ID;标题取最后一条 `ai-title`;行内 `cwd`/`entrypoint` |
160
188
  | `~/.claude/sessions/*.json` | 运行中会话注册表 → 状态 + tty 关联 |
161
189
  | `~/.claude/history.jsonl` | 无标题会话的首条输入回退 |
162
- | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(唯一可写) |
190
+ | `~/.claude/csm/favorites.json` | **csm 自有**:收藏与标签(可写) |
191
+ | `~/.claude/csm/index.db` | **csm 自有**:全文检索 FTS5 索引(可写,自动维护) |
192
+ | `~/.claude/plans/*.md` | plan mode 文档;经 jsonl 行内 `attachment.planFilePath` 关联(只读) |
163
193
 
164
194
  进程信息:单次 `ps -axo pid,ppid,tty,lstart,command` 快照三用(会话 tty / 进程名校验防 pid 回绕 / PPID 链上溯识别本终端)。
165
195
  支持 `CLAUDE_CONFIG_DIR` 重定向配置目录(测试注入用)。
@@ -176,6 +206,6 @@ python3 -m pytest # 全部单测:离线假数据 + 真 git worktree 集成
176
206
 
177
207
  - 包布局 `src/csm_cli/`:`cli.py` 入口/CLI/resume/双开保护 · `scanner.py` 数据层+消息解析(唯一文件 I/O)·
178
208
  `ui.py` TUI · `web.py` Web 服务端 · `web.html` Web 前端(单文件,无构建,importlib.resources 读取)·
179
- `serve.py` 守护进程 · `fmt.py` 纯函数格式化;仓库根 `csm.py` 为兼容 shim
209
+ `serve.py` 守护进程 · `fmt.py` 纯函数格式化 · `ftsearch.py` 全文检索(FTS5 索引);仓库根 `csm.py` 为兼容 shim
180
210
  - `fmt.py` 中 `rel_time()` / `fuzzy_score()` 为故意留空的降级实现(学习场景),实装后 `test_fmt.py` 的 `skipif` 自动生效
181
211
  - `web.html` 顶部 CSS 变量可整体换肤;打包见 `pyproject.toml`(hatchling,`csm-cli`)
@@ -4,4 +4,4 @@ TUI / Web / 表格三种前端,详见 README。版本号单一来源在本文
4
4
  pyproject.toml 通过 hatch dynamic version 读取。
5
5
  """
6
6
 
7
- __version__ = "0.1.0"
7
+ __version__ = "0.3.0"
@@ -78,6 +78,15 @@ def cmd_list(args, entries: list[scanner.SessionEntry]) -> int:
78
78
  "wt_repo": e.wt_repo,
79
79
  "wt_branch": e.wt_branch,
80
80
  "wt_ahead": e.wt_ahead,
81
+ "todos": (
82
+ [{"content": c, "status": st} for c, st in e.todos]
83
+ if e.todos is not None else None
84
+ ),
85
+ "todos_done": (
86
+ sum(1 for _, st in e.todos if st == "completed")
87
+ if e.todos is not None else None
88
+ ),
89
+ "plan_file": e.plan_file,
81
90
  "size": e.size,
82
91
  }
83
92
  for e in entries
@@ -140,6 +149,65 @@ def cmd_list(args, entries: list[scanner.SessionEntry]) -> int:
140
149
  return 0
141
150
 
142
151
 
152
+ def cmd_full_text(args, entries: list[scanner.SessionEntry]) -> int:
153
+ """跨会话全文检索:同步增量索引 + 表格/JSON 输出(管道友好)。"""
154
+ from csm_cli import fmt as csm_fmt # 惰性:fmt 依赖 prompt_toolkit
155
+ from csm_cli import ftsearch # 惰性:sqlite 仅全文路径需要
156
+
157
+ for e in entries:
158
+ if not e.light_scanned:
159
+ scanner.light_scan(e)
160
+ ftsearch.ensure_index(entries)
161
+ hits = ftsearch.search(args.full_text)
162
+ by_sid = {e.session_id: e for e in entries}
163
+ rows = [(by_sid[h.session_id], h) for h in hits if h.session_id in by_sid]
164
+
165
+ if not ftsearch.available():
166
+ print(f"全文检索不可用({ftsearch.unavailable_reason()})", file=sys.stderr)
167
+ return 2
168
+ if args.json:
169
+ payload = [
170
+ {
171
+ "session_id": e.session_id,
172
+ "title": e.title,
173
+ "project_path": e.project_path,
174
+ "hits": h.count,
175
+ "snippets": [{"kind": k, "text": t} for k, t in h.snippets],
176
+ }
177
+ for e, h in rows
178
+ ]
179
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
180
+ return 0
181
+
182
+ from rich.console import Console
183
+ from rich.markup import escape
184
+ from rich.table import Table
185
+
186
+ console = Console(no_color=args.no_color)
187
+ table = Table(box=None, show_header=True, header_style="bold dim", pad_edge=False)
188
+ table.add_column("命中", justify="right", no_wrap=True)
189
+ table.add_column("标题 / 首条输入", no_wrap=True)
190
+ table.add_column("项目", no_wrap=True)
191
+ table.add_column("摘要(首条命中)", no_wrap=True)
192
+ table.add_column("Session ID", no_wrap=True)
193
+ width = console.width
194
+ rest = max(width - 42, 30)
195
+ title_w = int(rest * 0.35)
196
+ for e, h in rows:
197
+ title = e.title or e.first_input or "(无用户输入)"
198
+ snippet = h.snippets[0][1] if h.snippets else ""
199
+ table.add_row(
200
+ str(h.count),
201
+ f"[dim]{escape(csm_fmt.truncate_cjk(title, title_w))}[/dim]"
202
+ if not e.title else escape(csm_fmt.truncate_cjk(title, title_w)),
203
+ escape(csm_fmt.shorten_path(e.project_path or "?", 16)),
204
+ escape(csm_fmt.truncate_cjk(snippet, rest - title_w - 20)),
205
+ e.session_id,
206
+ )
207
+ console.print(table)
208
+ return 0
209
+
210
+
143
211
  def _resume_conflict(entry: scanner.SessionEntry,
144
212
  registry: dict[str, scanner.RunningInfo],
145
213
  current_tty: str | None) -> str | None:
@@ -186,6 +254,38 @@ def resume(entry: scanner.SessionEntry, no_cd: bool = False) -> None:
186
254
  os.execvp("claude", ["claude", "--resume", entry.session_id])
187
255
 
188
256
 
257
+ def jump_to_terminal(entry: scanner.SessionEntry) -> bool:
258
+ """跳到会话所在终端:tmux switch-client / execvp attach / GUI 聚焦 / 降级打印。
259
+
260
+ 返回 True = 已处理(switch-client / 聚焦成功,csm 存活可继续);
261
+ False = 未跳转(原因已打印到 stderr)。attach 分支 execvp 不返回。
262
+ 与 resume 同款让位哲学:csm 从不持有会话或终端,送达即退。
263
+ """
264
+ import subprocess
265
+
266
+ if not entry.tty:
267
+ print("该会话未在运行或所在终端未知,无法跳转", file=sys.stderr)
268
+ return False
269
+ target = scanner.locate_tty_in_tmux(entry.tty)
270
+ if target is not None:
271
+ if scanner.in_tmux():
272
+ # switch-client 只切当前 client 的显示,csm 存活,用户可切回列表
273
+ try:
274
+ subprocess.run(["tmux", "switch-client", "-t", target],
275
+ check=True, timeout=2)
276
+ except (OSError, subprocess.SubprocessError) as exc:
277
+ print(f"跳转失败(tmux switch-client -t {target}): {exc}", file=sys.stderr)
278
+ return False
279
+ return True
280
+ # csm 不在 tmux:让位给 attach(resume 同款 execvp),attach 最细到 window
281
+ os.execvp("tmux", ["tmux", "attach-session", "-t", target.rsplit(".", 1)[0]])
282
+ if scanner.focus_gui_terminal(entry.tty):
283
+ return True
284
+ from csm_cli import fmt # 惰性:fmt 依赖 prompt_toolkit,--list 主路径不加载
285
+ print(fmt.fallback_location_hint(entry.tty), file=sys.stderr)
286
+ return False
287
+
288
+
189
289
  def resolve_new_target(path: str) -> Path | None:
190
290
  """--new 的目标目录解析:展开 ~;不存在或不是目录返回 None(可测纯函数)。"""
191
291
  target = Path(path).expanduser()
@@ -223,6 +323,8 @@ def build_argparser() -> argparse.ArgumentParser:
223
323
  p.add_argument("--head-bytes", type=int, default=scanner.DEFAULT_HEAD_BYTES, help=argparse.SUPPRESS)
224
324
  p.add_argument("--tail-bytes", type=int, default=scanner.DEFAULT_TAIL_BYTES, help=argparse.SUPPRESS)
225
325
  p.add_argument("--no-cd", action="store_true", help="resume 时不切换到原项目目录")
326
+ p.add_argument("--full-text", metavar="QUERY", dest="full_text",
327
+ help="跨会话全文检索(空格分词 AND 子串匹配;首次自动建索引 ~2s)")
226
328
  p.add_argument("--no-color", action="store_true", help="禁用颜色")
227
329
  p.add_argument("--version", action="version", version=f"csm {VERSION}")
228
330
 
@@ -288,6 +390,9 @@ def main(argv: list[str] | None = None) -> int:
288
390
 
289
391
  return csm_web.serve(args, entries)
290
392
 
393
+ if args.full_text is not None:
394
+ return cmd_full_text(args, entries)
395
+
291
396
  if args.list or args.json or not sys.stdout.isatty():
292
397
  # 非 TTY(管道)自动降级为 --list,便于 csm | grep
293
398
  return cmd_list(args, entries)
@@ -113,3 +113,24 @@ def parse_query(text: str) -> tuple[list[str], list[str]]:
113
113
  else:
114
114
  plain.append(tok)
115
115
  return plain, tags
116
+
117
+
118
+ # ---------------------------------------------------------------------------
119
+ # 终端定位降级提示
120
+ # ---------------------------------------------------------------------------
121
+
122
+
123
+ def fallback_location_hint(tty: str) -> str:
124
+ """会话运行终端定位全部失败(非 tmux、非 iTerm2/Terminal.app)时的提示文案。
125
+
126
+ 与 rel_time()/fuzzy_score() 不同:调用方(跳转键)没有再降级的分支,
127
+ 本函数必须始终返回可用字符串。
128
+
129
+ TODO(user): 当前是最小实现(只报 tty)。这行文案是产品决策——你来定信息密度:
130
+ - 只报 tty(现状):最短,但用户拿到 ttys012 干不了什么
131
+ - 附排查命令:如 `ps -t ttys012 -o pid,command`(列出该终端在跑什么),
132
+ 用户复制即查——但 TUI 的 _notice 是单行 2 秒提示,塞得下吗?
133
+ - 提示性文案:说明仅支持 tmux/iTerm2/Terminal.app 自动跳转
134
+ tty 为 ps 口径(无 /dev/ 前缀);命令若需要,写成 /dev/{tty} 更符合习惯。
135
+ """
136
+ return f"未定位到运行终端({tty}),仅支持 tmux/iTerm2/Terminal.app 跳转"