cc-zh-watcher 0.1.0 → 0.2.1

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.
Files changed (3) hide show
  1. package/README.md +237 -121
  2. package/dist/cli.js +2185 -389
  3. package/package.json +6 -5
package/README.md CHANGED
@@ -17,24 +17,30 @@ Claude Code 在英文场景表现最好：tokenizer 对英文更紧凑（中文
17
17
  cc-zh-watcher 是一个旁路 TUI 翻译工具：
18
18
 
19
19
  - **你输的中文** → 自动翻译成英文 → 通过 `/i` 命令喂给 Claude Code
20
- - **Claude 的英文回复** → 自动翻译成中文 → 在 watcher 里实时显示
20
+ - **Claude 的英文回复**（text、thinking、AskUserQuestion、TodoWrite 计划、Agent 派遣等所有结构化内容）→ 自动翻译成中文 → 在 watcher 里逐字流式显示
21
+ - **不翻译的内容**（Bash / Read / Edit / Write 等 tool 调用 + 它们的输出）→ 也按 Claude Code 同款样式显示出来 —— watcher 一个窗口里就有完整上下文
21
22
 
22
23
  不动 Claude Code 的 TUI（菜单导航、文件选择器、权限对话框照常用）。
23
24
 
24
25
  ```
25
- ┌── Terminal 1：你的 Claude Code ──┐ ┌── Terminal 2：cc-zh-watcher TUI ────────────┐
26
- │ │ │ [Claude 回复的中文翻译，append-only 滚动] │
27
- │ > /i ↵ │ │ [05:43] Claude: 在 storm-bft/...里... │
28
- │ ↑ 这条命令读 user-input.md │ │ [05:46] Claude: 可以。你需要在... │
29
- │ │ │ │
30
- │ Claude 用英文流式回复… │ │ ┌── StatusBar ──────────────────────────┐ │
31
- │ │ │ │ session 3f59...8985 · ctx: on (123) │ │
32
- │ [菜单 / 选项 / 权限对话框 │ │ │ api: ✓ 1.2s · 234 tok · session: ... │ │
33
- │ 都在这个窗口操作] │ │ └────────────────────────────────────────┘ │
34
- │ │ │ ┌── 中文输入 ─────────────────────────────┐ │
35
- │ │ │ │ > 再加上对应的 PoP 校验| │ │
36
- │ │ │ └────────────────────────────────────────┘ │
37
- └───────────────────────────────────┘ └────────────────────────────────────────────┘
26
+ ┌── Terminal 1：你的 Claude Code ──┐ ┌── Terminal 2：cc-zh-watcher TUI ──────────────┐
27
+ │ │ │ ● 我先看一下文件结构。 │
28
+ │ > /i ↵ │ │ │
29
+ │ ↑ 这条命令读 user-input.md │ │ ● Bash(ls -la /workspace) │
30
+ │ │ │ ⎿ total 168 │
31
+ │ Claude 用英文流式回复… │ │ drwxr-xr-x 18 sheldon staff │
32
+ │ │ │ … +12 lines │
33
+ │ [菜单 / 选项 / 权限对话框 │ │ │
34
+ │ 都在这个窗口操作] │ │ ● auth.py 的 42 行有个 bug。 │
35
+ │ │ │ │
36
+ │ │ │ ┌── StatusBar ───────────────────────────────┐ │
37
+ │ │ │ │ session 3f59...8985 · 24 turns · 5m ago │ │
38
+ │ │ │ │ ctx: on (123 chars) · api: ✓ 1.2s · 234 t │ │
39
+ │ │ │ └────────────────────────────────────────────┘ │
40
+ │ │ │ ┌── 中文输入 ──────────────────────────────┐ │
41
+ │ │ │ │ > 再加上对应的 PoP 校验| │ │
42
+ │ │ │ └────────────────────────────────────────────┘ │
43
+ └───────────────────────────────────┘ └────────────────────────────────────────────────┘
38
44
  ```
39
45
 
40
46
  ---
@@ -49,133 +55,176 @@ npm install -g cc-zh-watcher
49
55
 
50
56
  ---
51
57
 
52
- ## 快速开始（5 步）
58
+ ## 快速开始（3 步）
53
59
 
54
- ### 1. 配 API key
60
+ ### 1. 在你项目里启动 Claude Code
55
61
 
56
- 任何 OpenAI 兼容 endpoint 都行（OpenAI、DeepSeek、Together、Groq、本地 vLLM 等）：
62
+ ```bash
63
+ cd <你的项目目录>
64
+ claude
65
+ ```
66
+
67
+ ### 2. 另一个终端跑 watcher
57
68
 
58
69
  ```bash
59
- cc-zh-watcher configure
70
+ cc-zh-watcher
60
71
  ```
61
72
 
62
- 会提示你输入 `api_key` / `base_url` / `model` / `timeout_seconds`，写到 `~/.config/cc-zh-watcher/config.json`。
73
+ **第一次启动会自动引导**：
63
74
 
64
- 或者直接编辑那个文件：
75
+ - 没配过 API key → 内联提问 4 个字段（`api_key` / `base_url` / `model` / `timeout_seconds`），写到 `~/.config/cc-zh-watcher/config.json`（自动 0o600 权限）。任何 OpenAI 兼容 endpoint 都行（OpenAI、DeepSeek、Together、Groq、本地 vLLM 等）
76
+ - 让你选要监听哪个 Claude Code session（picker 列出本项目所有 session）
77
+ - 选完后，watcher 从 session 的 JSONL 读出**它对应的项目目录**，提示你"要在这里装 `/i` slash command 吗？[Y/n]"，回车确认即装
65
78
 
66
- ```jsonc
67
- {
68
- "api_key": "sk-...",
69
- "base_url": "https://api.deepseek.com/v1",
70
- "model": "deepseek-v4-pro",
71
- "timeout_seconds": 90
72
- }
73
- ```
79
+ 之后启动直接进 watcher，不再问。
74
80
 
75
- ### 2. 在你的项目里安装 `/i` 命令
81
+ ### 3. 开始用中文聊天
76
82
 
77
- ```bash
78
- cd <你的项目目录>
79
- cc-zh-watcher install
80
- ```
83
+ 在 watcher 里输中文 + 回车 → 翻译完成立刻写入 `user-input.md`。
81
84
 
82
- 这会写一个 `.claude/commands/i.md` slash command，让 Claude Code 知道怎么读 watcher 写的中转文件。
85
+ 切到 Claude Code 终端 → 输 `/i` + 回车 → Claude 收到英文 prompt 开始处理。
83
86
 
84
- ### 3. 启动 Claude Code
87
+ Claude 用英文流式回复时，watcher 同步翻译并显示中文，**同时把 Bash / Edit / Read 等 tool 调用按 CC 同款样式显示出来**。
85
88
 
86
- 照常：
89
+ > 想跳过引导直接编辑配置：`~/.config/cc-zh-watcher/config.json`，schema 见 [配置文件](#配置文件) 段。要再次配置 endpoint，直接 `Ctrl+E` 进 watcher 设置面板。
87
90
 
88
- ```bash
89
- claude
90
- ```
91
+ ---
91
92
 
92
- ### 4. 在另一个终端启动 watcher
93
+ ## 翻译输出长什么样
94
+
95
+ 每条内容前面有一个**带颜色的 ●**，颜色标识 kind：
96
+
97
+ | Bullet 颜色 | Kind | 显示内容 |
98
+ |---|---|---|
99
+ | 白 | `text` | Claude 的中文回复（最常见）|
100
+ | 紫 | `thinking` | Claude 的推理过程（默认关）|
101
+ | 黄 | `question` | AskUserQuestion 多选题 |
102
+ | 蓝 | `todo` | TodoWrite 计划列表 |
103
+ | 绿 | `agent` | Agent / Task 子代理派遣 |
104
+ | 青 | `tool_use` | Bash / Read / Edit 等 tool 调用 |
105
+ | (无) | `tool_result` | tool 输出（用 `⎿` 前缀缩进显示）|
106
+
107
+ 实际样子：
93
108
 
94
- ```bash
95
- cc-zh-watcher
96
109
  ```
110
+ ● 我先看一下文件结构。
97
111
 
98
- 第一次启动会让你选要监听哪个 Claude Code session（一个项目可能有多个 session）。
112
+ ● Bash(ls -la /workspace)
113
+ ⎿ total 168
114
+ drwxr-xr-x 18 sheldon staff
115
+ -rw-r--r-- 1 sheldon staff 257 May 10 08:13 .gitignore
116
+ … +12 lines
99
117
 
100
- ### 5. 开始用中文聊天
118
+ ● Read(src/app.tsx, limit=50)
119
+ ⎿ /**
120
+ * Top-level ink application.
121
+ */
122
+ import React, { useState, useEffect, useRef } from "react";
123
+ … +47 lines
101
124
 
102
- 在 watcher 里输中文 + 回车 → 翻译完成立刻写入 `user-input.md`。
125
+ ● 现在我看清楚结构了。先做以下几步：
103
126
 
104
- 切到 Claude Code 终端 → 输 `/i` + 回车 → Claude 收到英文 prompt 开始处理。
127
+ ● 📝 计划更新:
128
+ ✓ 探查目录 ← 完成（绿 ✓ + 删除线 + dim）
129
+ ⟳ 重构 translate.ts ← 进行中（黄 ⟳）
130
+ ○ 跑测试 ← 待办（dim ○）
105
131
 
106
- Claude 用英文流式回复时，watcher 会实时翻译并显示中文。
132
+ ● 🤖 子代理 [claude-code-guide]:
133
+ 任务: 研究 SSE 流式接入方式
107
134
 
108
- ---
135
+ 指令:
136
+ 请查阅最新文档，回答以下问题：
137
+ 1. Claude Code 是否原生支持 stream:true...
109
138
 
110
- ## 工作原理
139
+ ● ❓ 提问:
140
+ 改 translate.ts 还是新建独立文件？
111
141
 
112
- ```
113
- [user types Chinese]
114
- ↓
115
- [watcher 翻译 zh→en]
116
- ↓
117
- [写入 .claude/cache/user-input.md]
118
- ↓
119
- [user 切到 Claude Code, 输 /i ↵]
120
- ↓
121
- [/i slash command 读这个文件作为 prompt]
122
- ↓
123
- [Claude 处理，英文流式回复，写入 transcript JSONL]
124
- ↓
125
- [watcher tail JSONL，检测到新 assistant text]
126
- ↓
127
- [watcher 翻译 en→zh, 显示在输出区]
128
- ```
142
+ ① 改 translate.ts 接受 onDelta 回调（推荐）
143
+ 最小侵入，调用方决定要不要流式
129
144
 
130
- 中转介质：
145
+ ② 拆出独立 streamTranslate 函数
146
+ 分层更清晰但调用面变两倍
147
+ ```
131
148
 
132
- - 输入侧：`<project>/.claude/cache/user-input.md`（watcher 写、`/i` 读）
133
- - 输出侧：`~/.claude/projects/<project-hash>/<session-uuid>.jsonl`（Claude Code 写、watcher tail）
149
+ **流式中**：黄色光标 `▎` 在内容末尾，表示还在翻译。
134
150
 
135
151
  ---
136
152
 
137
- ## 设置面板
153
+ ## 设置面板（Ctrl+E）
138
154
 
139
- 在 watcher 内按 **`Ctrl+E`** 弹出设置面板：
155
+ 按 `Ctrl+E` 弹出设置面板，所有配置都在一处：
140
156
 
141
157
  ```
142
- ┌── Settings (↑/↓ select · Enter edit · Esc save & close) ────┐
143
- │ ▸ api_key: sk-deep***ce91 │
144
- │ base_url: https://api.deepseek.com/v1 │
145
- │ model: deepseek-v4-pro │
146
- │ timeout_seconds: 90 │
147
- │ │
148
- │ ── User prompt (empty = use default) ── │
149
- │ user.zh-to-en: (empty — using default) │
150
- │ user.zh-to-en-w/ctx: (empty — using default) │
151
- │ user.en-to-zh: 用您而不是你。错误信息保留英文。 │
152
- │ │
153
- │ ── Default prompt (read-only) ── │
154
- │ default.zh-to-en: You are a professional transla… │
155
- │ default.zh-to-en-w/ctx: You are a professional transla… │
156
- │ default.en-to-zh: You are a professional transla… │
157
- └─────────────────────────────────────────────────────────────┘
158
+ ┌── Settings (↑/↓ select · Enter edit · Esc save & close) ─────────────┐
159
+ │ ▸ session: 3f59…8985 (24 turns · active 5m ago; Enter 切换) │
160
+ │ │
161
+ │ api_key: sk-deep***ce91 │
162
+ │ base_url: https://api.deepseek.com/v1 │
163
+ │ model: deepseek-v4-pro │
164
+ │ timeout_seconds: 90 │
165
+ │ │
166
+ │ ── Toggles ── │
167
+ │ notify_on_complete: on (终端响铃；Enter 切换) │
168
+ │ translate_thinking: off (默认关；Enter 切换) │
169
+ │ translate_todos: on (译 TodoWrite 计划；Enter 切换) │
170
+ │ translate_agent: on (译 Agent/Task 子代理；Enter 切换) │
171
+ │ context_enabled: on (zh→en 用 Claude 上一条作 context；…) │
172
+ │ show_tool_calls: on (显示原始 tool 调用 + 结果（CC 同款）；…) │
173
+ │ │
174
+ │ ── User prompt (empty = use default) ── │
175
+ │ user.zh-to-en: (empty — using default) │
176
+ │ user.zh-to-en-w/ctx: (empty — using default) │
177
+ │ user.en-to-zh: 用您而不是你。错误信息保留英文。 │
178
+ │ │
179
+ │ ── Default prompt (read-only) ── │
180
+ │ default.zh-to-en: You are a professional transla… │
181
+ │ default.zh-to-en-w/ctx: You are a professional transla… │
182
+ │ default.en-to-zh: You are a professional transla… │
183
+ └───────────────────────────────────────────────────────────────────────┘
158
184
  ```
159
185
 
160
- - **API 字段**（4 个）：单行 TextInput，Enter 进入编辑、Enter 提交、Esc 弃改
161
- - **User prompt**（3 个，每个翻译方向一个）：Enter 弹满屏多行编辑器，Ctrl+S 保存、Esc 取消。**留空 = 用默认 prompt**
162
- - **Default prompt**（3 个，只读）：Enter 弹满屏只读查看器，看完整内置 base prompt
163
- - **Esc** 在导航态 = 保存所有改动 + 关闭面板。改完即热生效，不用重启 watcher
186
+ ### Session 行
187
+ - `Enter` 弹 SessionPicker，**热切换 session**（不用退 watcher 重启）
188
+ - 切换后 scrollback 写一条 "已切换 session: A… → B…" 分隔条
189
+
190
+ ### API 字段（4 个）
191
+ - 单行 TextInput，Enter 进入编辑、Enter 提交、Esc 弃改
192
+ - 校验：`api_key` 非空、`base_url` 是 `http(s)://` 开头、`timeout_seconds` 是正整数
193
+
194
+ ### Toggles（6 个，Enter 切换）
164
195
 
165
- 字段校验：保存时会检查 `api_key` / `model` 非空、`base_url` 是 `http(s)://` 开头、`timeout_seconds` 是正整数。校验失败显示在面板底部。
196
+ | Toggle | 默认 | 说明 |
197
+ |---|:---:|---|
198
+ | `notify_on_complete` | **on** | Claude 一个 turn 结束 2 秒后响终端 bell（`\x07`）|
199
+ | `translate_thinking` | off | 译 Claude 的 thinking 块（Opus 4.7 多为 redacted；空块自动跳过）|
200
+ | `translate_todos` | **on** | 译 TodoWrite 计划项（按当前状态自动选 `content` 或 `activeForm`）|
201
+ | `translate_agent` | **on** | 译 Agent/Task 子代理派遣（description + prompt）|
202
+ | `context_enabled` | **on** | zh→en 翻译时用 Claude 上一条 text 作消歧 context |
203
+ | `show_tool_calls` | **on** | 显示原始 tool 调用 + 结果（Bash/Read/Edit 等，CC 同款样式）|
204
+
205
+ ### User prompt（3 个，每翻译方向一个）
206
+ - Enter 弹满屏多行编辑器，Ctrl+S 保存、Esc 取消
207
+ - **留空 = 用默认 prompt**
208
+
209
+ ### Default prompt（3 个，只读）
210
+ - Enter 弹满屏只读查看器，看完整内置 base prompt
211
+
212
+ ### 保存
213
+ - **`Esc` 在导航态 = 保存所有改动 + 关闭面板**
214
+ - 改完即热生效，**不用重启 watcher**
215
+
216
+ 字段校验失败显示在面板底部。
166
217
 
167
218
  ---
168
219
 
169
220
  ## CLI 命令
170
221
 
171
222
  ```
172
- cc-zh-watcher 启动 TUI（用上次选过的 session）
223
+ cc-zh-watcher 启动 TUI（首次自动引导 API key + /i 安装）
173
224
  cc-zh-watcher --pick 启动 TUI，强制弹 session picker
174
225
  cc-zh-watcher --session <uuid|前缀> 启动 TUI，直接指定 session（≥4 字符前缀）
175
226
  cc-zh-watcher --config <path> 指定 config 文件
176
- cc-zh-watcher install 装 /i slash command 到当前项目
177
227
  cc-zh-watcher uninstall 移除 /i 命令（可选清缓存：--wipe-cache）
178
- cc-zh-watcher configure 交互式创建 / 修改 user-global config
179
228
  cc-zh-watcher sessions 列出本项目所有 session
180
229
  cc-zh-watcher history [opts] 查看 / 搜索翻译历史
181
230
  --grep <pat> 子串过滤
@@ -184,28 +233,26 @@ cc-zh-watcher history [opts] 查看 / 搜索翻译历史
184
233
  --json 机器可读
185
234
  cc-zh-watcher prompts show [dir] 打印当前生效的 prompt（dir 省略 = 全部 3 个）
186
235
  --base 忽略 user override，只看内置
187
- cc-zh-watcher --version
188
- cc-zh-watcher --help
236
+ cc-zh-watcher -v / --version
237
+ cc-zh-watcher -h / --help
189
238
  ```
190
239
 
240
+ > 0.1.0 里的 `cc-zh-watcher configure` 和 `cc-zh-watcher install` 子命令在 0.2.0 删掉了 —— 第一次启动 watcher 自动引导这两步，之后想改用 `Ctrl+E` 进设置面板。
241
+
191
242
  ---
192
243
 
193
244
  ## TUI 键位
194
245
 
195
- ### 主界面
246
+ 主界面（极简化 —— 之前的 `Ctrl+T/P/N/L` 都搬进 settings 了）：
196
247
 
197
248
  | 键 | 动作 |
198
249
  |---|---|
199
- | `Enter` | 触发翻译，翻译完立刻写 `user-input.md` |
200
- | `Ctrl+T` | 切换 context 启用 / 禁用（zh→en 是否带上一次 Claude 英文回复作为消歧上下文）|
250
+ | `Enter` | 翻译并发送（pre-flight check 触发警告时，再按一次 Enter 确认）|
201
251
  | `Ctrl+E` | 打开设置面板 |
202
- | `Ctrl+P` | 调出更早一次的中文输入（in-memory，本会话最多 50 条）|
203
- | `Ctrl+N` | 走回更新一次的输入；走到末尾后清空 |
204
- | `Ctrl+L` | 清空当前输入 |
205
252
  | `Esc` | 清空输入 + 已显示结果 + 错误状态 |
206
253
  | `Ctrl+C` | 退出 watcher |
207
254
 
208
- ### Session picker（首次启动 / `--pick`）
255
+ Session picker（Ctrl+E → Enter on session row，或首次启动 / `--pick`）：
209
256
 
210
257
  | 键 | 动作 |
211
258
  |---|---|
@@ -214,17 +261,17 @@ cc-zh-watcher --help
214
261
  | `/` | 模糊搜索 |
215
262
  | `Esc` | 取消 |
216
263
 
217
- ### 设置面板
264
+ 设置面板：
218
265
 
219
266
  | 键 | 动作 |
220
267
  |---|---|
221
268
  | `↑` / `↓` | 选字段 |
222
- | `Enter`（导航态） | 进入编辑（API 字段）/ 弹多行编辑器（user prompt）/ 弹只读查看器（default prompt） |
269
+ | `Enter`（导航态） | 进入编辑（API 字段）/ 切换（toggle 行）/ 弹 SessionPicker（session 行）/ 弹多行编辑器（user prompt）/ 弹只读查看器（default prompt）|
223
270
  | `Enter`（编辑态） | 提交（仅 API 字段；多行编辑器用 Ctrl+S）|
224
271
  | `Esc`（编辑态） | 弃改回到导航态 |
225
272
  | `Esc`（导航态） | **保存所有改动** + 关闭面板 |
226
273
 
227
- ### 多行编辑器（user prompt）
274
+ 多行编辑器（user prompt）：
228
275
 
229
276
  | 键 | 动作 |
230
277
  |---|---|
@@ -238,24 +285,57 @@ cc-zh-watcher --help
238
285
 
239
286
  ---
240
287
 
241
- ## Context 模式
288
+ ## Context 模式（zh→en 消歧）
242
289
 
243
- 默认开启。watcher 维护"上一次 Claude 英文回复的最后一段 text"，在你下一次输入翻译时作为消歧上下文传给翻译模型。
290
+ `context_enabled = on` 时（默认），watcher 会保存"Claude 上一次回复的最后一段 text"，作为下一次 zh→en 翻译时的消歧 context。
244
291
 
245
- 为什么有用：当 Claude 问你"A 还是 B？"，你回"选 A"，没有 context 翻译会是 `Choose A`（字面），有 context 会是 `Let's go with A` / `I'll go with option A`（更自然）。
292
+ 为什么有用：当 Claude 问"A 还是 B？"，你回"选 A"，没有 context 翻译会是 `Choose A`（字面），有 context 会是 `Let's go with A` / `I'll go with option A`（更自然）。
246
293
 
247
- 按 `Ctrl+T` 随时切换。状态栏右侧实时显示：
294
+ 状态栏右侧实时显示：
248
295
 
249
296
  | Badge | 含义 |
250
297
  |---|---|
251
- | `ctx: on (123 chars · Ctrl+T to disable)` | 启用，有 123 字 context 可用 |
298
+ | `ctx: on (123 chars)` | 启用，有 123 字 context 可用 |
252
299
  | `ctx: on (waiting for Claude)` | 启用，但 Claude 还没说过话 |
253
- | `ctx: off (Ctrl+T to enable)` | 禁用 |
300
+ | `ctx: off (Ctrl+E → toggle)` | 禁用 |
254
301
 
255
302
  什么时候关：
256
303
  - 切全新话题时（避免被前一轮误导）
257
304
  - 翻译"那个"、"再加一条"等本身已经独立成意思的字面命令
258
305
 
306
+ `Ctrl+E` → 选 `context_enabled` 行 → `Enter` 切换 → `Esc` 保存。
307
+
308
+ ---
309
+
310
+ ## 上下文检查（pre-flight）
311
+
312
+ `context_enabled = on` 时，watcher 还会让翻译模型在翻译之前**做一次合理性检查** —— 用 prior reply + 你的中文输入，判断这条会不会让 Claude 摸不着头脑。
313
+
314
+ WARN 触发条件（模型自行判断，prompt 里要求"宁可漏不能错"）：
315
+ - 你提到的东西在 PRIOR_REPLY 里没出现（"那个文件"但 Claude 没提任何文件）
316
+ - 多选题答非所选（Claude 问 "A or B?"，你答 "好的"）
317
+ - 主题不匹配（Claude 问 "要不要 commit?"，你说 "看一下 Y 的实现"）
318
+ - 输入太破碎，连上下文都救不回来
319
+
320
+ 触发时 watcher 不会立刻把英文写到 `user-input.md`，而是显示**两步确认**：
321
+
322
+ ```
323
+ ┌── 翻译结果 ──────────────────────────────────────┐
324
+ │ ⚠ 上下文检查发现可能的问题 │
325
+ │ 你说的"那个文件"在上下文里没出现 │
326
+ │ │
327
+ │ ↳ 翻译已就绪: That file │
328
+ │ Enter 再按一次确认发送 · Esc 取消 · 或直接改输入重译 │
329
+ └──────────────────────────────────────────────────┘
330
+ ```
331
+
332
+ 三选一：
333
+ - **输入未改 + Enter** → 仍然发送（你判断 OK）
334
+ - **Esc** → 全部清掉
335
+ - **改输入再 Enter** → 用新输入重新翻译
336
+
337
+ 模型也会**静默修复明显的 IME typo**（`测式` → `测试`、`克立` → `克隆`、`提价` → `提交`、`在/再` 同音字混用等），无需触发警告。
338
+
259
339
  ---
260
340
 
261
341
  ## 自定义翻译 prompt
@@ -265,7 +345,7 @@ cc-zh-watcher --help
265
345
  | 翻译方向 | 用途 |
266
346
  |---|---|
267
347
  | `zh-to-en` | 用户中文输入 → Claude Code prompt（无上下文）|
268
- | `zh-to-en-with-context` | 同上，但带上一轮 Claude 英文回复作消歧上下文 |
348
+ | `zh-to-en-with-context` | 同上，但带上一轮 Claude 英文回复作消歧上下文（启用 pre-flight check）|
269
349
  | `en-to-zh` | Claude 英文回复 → 显示给用户的中文 |
270
350
 
271
351
  **user prompt 非空时完全替换 default**。设置面板里 `Ctrl+E` → 选 `user.<方向>` → Enter → 多行编辑器输入你的自定义 prompt → Ctrl+S 保存。
@@ -275,7 +355,7 @@ cc-zh-watcher --help
275
355
  - **域专业术语词典**：`Domain: traditional Chinese medicine. Glossary: 经络=meridians, 气=qi (do not translate).`
276
356
  - **风格偏好**：`用您而不是你。错误信息保留英文。React/Vue/CSS 术语不译。`
277
357
 
278
- 要看默认 prompt 长什么样：在面板里选 `default.<方向>` → Enter，会弹只读查看器看完整 base prompt。
358
+ 要看默认 prompt 长什么样：在面板里选 `default.<方向>` → Enter，弹只读查看器看完整 base prompt。
279
359
 
280
360
  或用 CLI：
281
361
 
@@ -303,12 +383,21 @@ cc-zh-watcher prompts show zh-to-en --base
303
383
 
304
384
  ```jsonc
305
385
  {
386
+ // ── API ──
306
387
  "api_key": "sk-...", // 必填
307
388
  "base_url": "https://api.deepseek.com/v1", // 默认 https://api.openai.com/v1
308
389
  "model": "deepseek-v4-pro", // 默认 gpt-4o-mini
309
390
  "timeout_seconds": 90, // 默认 30
310
391
 
311
- // 可选 — user prompt（非空替换内置 default）
392
+ // ── Toggles，全部 boolean ──
393
+ "notify_on_complete": true, // 默认 true
394
+ "translate_thinking": false, // 默认 false
395
+ "translate_todos": true, // 默认 true
396
+ "translate_agent": true, // 默认 true
397
+ "context_enabled": true, // 默认 true
398
+ "show_tool_calls": true, // 默认 true
399
+
400
+ // ── 可选：user prompt（非空替换内置 default） ──
312
401
  "prompts": {
313
402
  "zh-to-en": "...",
314
403
  "zh-to-en-with-context": "...",
@@ -317,6 +406,17 @@ cc-zh-watcher prompts show zh-to-en --base
317
406
  }
318
407
  ```
319
408
 
409
+ 文件权限自动设为 `0o600`（owner-only），因为里面有 api_key。
410
+
411
+ ---
412
+
413
+ ## 可靠性
414
+
415
+ - **原子写**：所有持久化文件（`user-input.md` / 状态文件 / config）都用 tempfile + rename。Claude Code 在另一终端 `cat user-input.md` 时绝不会读到半截内容；中途 Ctrl+C 也不会损坏文件
416
+ - **翻译队列**：en→zh 翻译请求 FIFO 串行（concurrency=1），避免在一个 Claude turn 内同时迸发多个请求触发 429，且保证 scrollback 顺序与 JSONL 顺序严格一致
417
+ - **Session 文件可无限增长**：单一 UUID transcript 长达 128MB / 35k 行 / 5 天连续使用都正常 —— `/compact` 不会切新文件。tail 用 offset-based 读取，文件多大都和性能无关
418
+ - **API key 文件 mode 0o600**：`~/.config/cc-zh-watcher/config.json` 自动设成 owner-only
419
+
320
420
  ---
321
421
 
322
422
  ## API 调用 metrics
@@ -351,7 +451,7 @@ cc-zh-watcher history --direction zh-to-en --json
351
451
 
352
452
  ### `Ctrl+E` 没反应？
353
453
 
354
- 老版本一度用 `Ctrl+,`（VS Code 习惯），但终端不发这个序列。现在是 `Ctrl+E`。如果你装的是 < 0.1.0 老版本，升级一下。
454
+ 老版本一度用 `Ctrl+,`（VS Code 习惯），但终端不发这个序列。现在是 `Ctrl+E`。如果你装的是 < 0.2.0 老版本，升级一下。
355
455
 
356
456
  ### 翻译超时？
357
457
 
@@ -359,7 +459,11 @@ DeepSeek 长 prompt 偶尔超过 30s 默认超时。改 `timeout_seconds: 90`
359
459
 
360
460
  ### Session 选错了？
361
461
 
362
- `cc-zh-watcher --pick` 重新选。状态会写到 `<project>/.claude/cache/cc-zh-watcher-state.json`，下次直接用。
462
+ 按 `Ctrl+E` → 顶部 `session:` 行 → `Enter` → 弹 picker 重新选。或者外面跑 `cc-zh-watcher --pick` 重启 watcher。
463
+
464
+ ### `/clear` 之后 watcher 不动了？
465
+
466
+ `/clear` 创建新 UUID + 新 JSONL 文件，watcher 不会自动跟上。`Ctrl+E` → `session:` 行 → `Enter` → 选最新那个。
363
467
 
364
468
  ### 想看每次实际发送的英文 prompt？
365
469
 
@@ -371,9 +475,21 @@ DeepSeek 长 prompt 偶尔超过 30s 默认超时。改 `timeout_seconds: 90`
371
475
  2. 在设置面板加 user prompt 给翻译器更多上下文 / 术语
372
476
  3. 调高 `timeout_seconds`，更强的模型可能需要更长时间
373
477
 
478
+ ### Bash 输出 / 文件内容被截断了？
479
+
480
+ `tool_result` 显示截断到 5 行 + `… +N lines`。完整内容回 Claude Code 那边看（按 `ctrl+o` 展开）。
481
+
482
+ ### 为什么默认不译 thinking？
483
+
484
+ Opus 4.7 的 thinking 几乎全是 signature-only redacted（空块），译了也是空气。需要的话设置面板把 `translate_thinking` 切到 `on`。
485
+
486
+ ### 终端没听到响铃？
487
+
488
+ 很多终端默认禁用音频 bell（用闪屏代替）。iTerm2: `Profiles → Terminal → Silence terminal bell` 取消勾选；Terminal.app: `View → Allow Audible Bell`。或者把 `notify_on_complete` 关掉。
489
+
374
490
  ### Claude Code 找不到 `/i` 命令？
375
491
 
376
- 确认在你的项目目录下跑过 `cc-zh-watcher install`。检查 `.claude/commands/i.md` 是否存在。
492
+ 第一次启动 watcher 时若你点了 `n` 跳过自动安装，重新启动 watcher 会再问一次（只要 `.claude/commands/i.md` 不存在就会问）。或者直接复制 [assets/i.md](./assets/i.md) 到项目的 `.claude/commands/i.md`。
377
493
 
378
494
  ### 卸载？
379
495
 
@@ -392,14 +508,14 @@ rm -rf ~/.config/cc-zh-watcher
392
508
 
393
509
  ## 限制
394
510
 
511
+ - **`/i` 这一步是手动的**：watcher 不能直接喂 prompt 给运行中的 Claude Code TUI（CC 没暴露 IPC）。每轮要切窗口 + 敲 `/i ↵`。这是为了保留 Claude Code interactive TUI 的全部功能（slash command、permission prompt、`/resume` picker 等）所做的权衡
395
512
  - **Prompt 不能含字面 `\n`**：单行 TextInput 没法输入换行。要嵌入换行：watcher 关掉，手编 `~/.config/cc-zh-watcher/config.json` 里 `prompts.<dir>` 字段
396
513
  - **不重放历史**：watcher 启动时只翻译之后的新 assistant text，已有对话历史不翻译。要回看历史用终端原生 scrollback
397
- - **单 session 监听**：watcher 一次只盯一个 Claude Code session。多 session 并发要开多个 watcher 实例
514
+ - **单 session 监听**：watcher 一次只盯一个 Claude Code session。多 session 并发要开多个 watcher 实例。`/clear` 后需要手动 Ctrl+E → 切到新 session
398
515
  - **翻译延迟**：每次输入需等翻译 API 返回（典型 0.5-3 秒），慢于直接英文输入。trade-off
399
516
 
400
517
  ---
401
518
 
402
-
403
519
  ## License
404
520
 
405
521
  MIT — 见 [LICENSE](./LICENSE)