cc-zh-watcher 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 storm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# cc-zh-watcher
+
+> A side-channel Chinese ↔ English bridge for Claude Code.
+> Type Chinese, Claude sees English. Claude replies in English, you see Chinese.
+
+[![npm version](https://img.shields.io/npm/v/cc-zh-watcher.svg)](https://www.npmjs.com/package/cc-zh-watcher)
+[![license](https://img.shields.io/npm/l/cc-zh-watcher.svg)](LICENSE)
+
+让中文母语开发者用 Claude Code 时，**输入和输出都是中文**，但 Claude 内部全程只看英文 —— 节省 token、对齐英文工具生态、提升复杂推理质量。
+
+---
+
+## 为什么需要它
+
+Claude Code 在英文场景表现最好：tokenizer 对英文更紧凑（中文一句话约是英文 2× token）、内部系统 prompt 全是英文、复杂推理在英文上略胜一筹。但你想用中文。
+
+cc-zh-watcher 是一个旁路 TUI 翻译工具：
+
+- **你输的中文** → 自动翻译成英文 → 通过 `/i` 命令喂给 Claude Code
+- **Claude 的英文回复** → 自动翻译成中文 → 在 watcher 里实时显示
+
+不动 Claude Code 的 TUI（菜单导航、文件选择器、权限对话框照常用）。
+
+```
+┌── Terminal 1：你的 Claude Code ──┐  ┌── Terminal 2：cc-zh-watcher TUI ────────────┐
+│                                   │  │ [Claude 回复的中文翻译，append-only 滚动]    │
+│  > /i ↵                           │  │ [05:43] Claude: 在 storm-bft/...里...        │
+│   ↑ 这条命令读 user-input.md       │  │ [05:46] Claude: 可以。你需要在...           │
+│                                   │  │                                              │
+│  Claude 用英文流式回复…             │  │ ┌── StatusBar ──────────────────────────┐ │
+│                                   │  │ │ session 3f59...8985 · ctx: on (123)   │ │
+│  [菜单 / 选项 / 权限对话框          │  │ │ api: ✓ 1.2s · 234 tok · session: ... │ │
+│   都在这个窗口操作]                 │  │ └────────────────────────────────────────┘ │
+│                                   │  │ ┌── 中文输入 ─────────────────────────────┐ │
+│                                   │  │ │ > 再加上对应的 PoP 校验|                │ │
+│                                   │  │ └────────────────────────────────────────┘ │
+└───────────────────────────────────┘  └────────────────────────────────────────────┘
+```
+
+---
+
+## 安装
+
+```bash
+npm install -g cc-zh-watcher
+```
+
+需要 Node.js ≥ 20。无其他依赖。
+
+---
+
+## 快速开始（5 步）
+
+### 1. 配 API key
+
+任何 OpenAI 兼容 endpoint 都行（OpenAI、DeepSeek、Together、Groq、本地 vLLM 等）：
+
+```bash
+cc-zh-watcher configure
+```
+
+会提示你输入 `api_key` / `base_url` / `model` / `timeout_seconds`，写到 `~/.config/cc-zh-watcher/config.json`。
+
+或者直接编辑那个文件：
+
+```jsonc
+{
+  "api_key":         "sk-...",
+  "base_url":        "https://api.deepseek.com/v1",
+  "model":           "deepseek-v4-pro",
+  "timeout_seconds": 90
+}
+```
+
+### 2. 在你的项目里安装 `/i` 命令
+
+```bash
+cd <你的项目目录>
+cc-zh-watcher install
+```
+
+这会写一个 `.claude/commands/i.md` slash command，让 Claude Code 知道怎么读 watcher 写的中转文件。
+
+### 3. 启动 Claude Code
+
+照常：
+
+```bash
+claude
+```
+
+### 4. 在另一个终端启动 watcher
+
+```bash
+cc-zh-watcher
+```
+
+第一次启动会让你选要监听哪个 Claude Code session（一个项目可能有多个 session）。
+
+### 5. 开始用中文聊天
+
+在 watcher 里输中文 + 回车 → 翻译完成立刻写入 `user-input.md`。
+
+切到 Claude Code 终端 → 输 `/i` + 回车 → Claude 收到英文 prompt 开始处理。
+
+Claude 用英文流式回复时，watcher 会实时翻译并显示中文。
+
+---
+
+## 工作原理
+
+```
+[user types Chinese]
+    ↓
+[watcher 翻译 zh→en]
+    ↓
+[写入 .claude/cache/user-input.md]
+    ↓
+[user 切到 Claude Code, 输 /i ↵]
+    ↓
+[/i slash command 读这个文件作为 prompt]
+    ↓
+[Claude 处理，英文流式回复，写入 transcript JSONL]
+    ↓
+[watcher tail JSONL，检测到新 assistant text]
+    ↓
+[watcher 翻译 en→zh, 显示在输出区]
+```
+
+中转介质：
+
+- 输入侧：`<project>/.claude/cache/user-input.md`（watcher 写、`/i` 读）
+- 输出侧：`~/.claude/projects/<project-hash>/<session-uuid>.jsonl`（Claude Code 写、watcher tail）
+
+---
+
+## 设置面板
+
+在 watcher 内按 **`Ctrl+E`** 弹出设置面板：
+
+```
+┌── Settings (↑/↓ select · Enter edit · Esc save & close) ────┐
+│ ▸ api_key:        sk-deep***ce91                            │
+│   base_url:       https://api.deepseek.com/v1               │
+│   model:          deepseek-v4-pro                           │
+│   timeout_seconds: 90                                       │
+│                                                             │
+│   ── User prompt (empty = use default) ──                   │
+│   user.zh-to-en:        (empty — using default)             │
+│   user.zh-to-en-w/ctx:  (empty — using default)             │
+│   user.en-to-zh:        用您而不是你。错误信息保留英文。     │
+│                                                             │
+│   ── Default prompt (read-only) ──                          │
+│   default.zh-to-en:        You are a professional transla…  │
+│   default.zh-to-en-w/ctx:  You are a professional transla…  │
+│   default.en-to-zh:        You are a professional transla…  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **API 字段**（4 个）：单行 TextInput，Enter 进入编辑、Enter 提交、Esc 弃改
+- **User prompt**（3 个，每个翻译方向一个）：Enter 弹满屏多行编辑器，Ctrl+S 保存、Esc 取消。**留空 = 用默认 prompt**
+- **Default prompt**（3 个，只读）：Enter 弹满屏只读查看器，看完整内置 base prompt
+- **Esc** 在导航态 = 保存所有改动 + 关闭面板。改完即热生效，不用重启 watcher
+
+字段校验：保存时会检查 `api_key` / `model` 非空、`base_url` 是 `http(s)://` 开头、`timeout_seconds` 是正整数。校验失败显示在面板底部。
+
+---
+
+## CLI 命令
+
+```
+cc-zh-watcher                          启动 TUI（用上次选过的 session）
+cc-zh-watcher --pick                   启动 TUI，强制弹 session picker
+cc-zh-watcher --session <uuid|前缀>     启动 TUI，直接指定 session（≥4 字符前缀）
+cc-zh-watcher --config <path>          指定 config 文件
+cc-zh-watcher install                  装 /i slash command 到当前项目
+cc-zh-watcher uninstall                移除 /i 命令（可选清缓存：--wipe-cache）
+cc-zh-watcher configure                交互式创建 / 修改 user-global config
+cc-zh-watcher sessions                 列出本项目所有 session
+cc-zh-watcher history [opts]           查看 / 搜索翻译历史
+                                         --grep <pat>      子串过滤
+                                         --tail N          最后 N 条（默认 20）
+                                         --direction <dir> zh-to-en | en-to-zh
+                                         --json            机器可读
+cc-zh-watcher prompts show [dir]       打印当前生效的 prompt（dir 省略 = 全部 3 个）
+                                         --base            忽略 user override，只看内置
+cc-zh-watcher --version
+cc-zh-watcher --help
+```
+
+---
+
+## TUI 键位
+
+### 主界面
+
+| 键 | 动作 |
+|---|---|
+| `Enter` | 触发翻译，翻译完立刻写 `user-input.md` |
+| `Ctrl+T` | 切换 context 启用 / 禁用（zh→en 是否带上一次 Claude 英文回复作为消歧上下文）|
+| `Ctrl+E` | 打开设置面板 |
+| `Ctrl+P` | 调出更早一次的中文输入（in-memory，本会话最多 50 条）|
+| `Ctrl+N` | 走回更新一次的输入；走到末尾后清空 |
+| `Ctrl+L` | 清空当前输入 |
+| `Esc` | 清空输入 + 已显示结果 + 错误状态 |
+| `Ctrl+C` | 退出 watcher |
+
+### Session picker（首次启动 / `--pick`）
+
+| 键 | 动作 |
+|---|---|
+| `↑` / `↓` | 选 session |
+| `Enter` | 确认 |
+| `/` | 模糊搜索 |
+| `Esc` | 取消 |
+
+### 设置面板
+
+| 键 | 动作 |
+|---|---|
+| `↑` / `↓` | 选字段 |
+| `Enter`（导航态） | 进入编辑（API 字段）/ 弹多行编辑器（user prompt）/ 弹只读查看器（default prompt） |
+| `Enter`（编辑态） | 提交（仅 API 字段；多行编辑器用 Ctrl+S）|
+| `Esc`（编辑态） | 弃改回到导航态 |
+| `Esc`（导航态） | **保存所有改动** + 关闭面板 |
+
+### 多行编辑器（user prompt）
+
+| 键 | 动作 |
+|---|---|
+| `↑` / `↓` / `←` / `→` | 光标导航 |
+| `Enter` | 在光标处插入换行 |
+| `Tab` | 插入 4 个空格 |
+| `Backspace` | 删字符（行首时合并上一行）|
+| `Delete` | 删字符（行末时合并下一行）|
+| `Ctrl+S` | 提交 |
+| `Esc` | 弃改 |
+
+---
+
+## Context 模式
+
+默认开启。watcher 维护"上一次 Claude 英文回复的最后一段 text"，在你下一次输入翻译时作为消歧上下文传给翻译模型。
+
+为什么有用：当 Claude 问你"A 还是 B？"，你回"选 A"，没有 context 翻译会是 `Choose A`（字面），有 context 会是 `Let's go with A` / `I'll go with option A`（更自然）。
+
+按 `Ctrl+T` 随时切换。状态栏右侧实时显示：
+
+| Badge | 含义 |
+|---|---|
+| `ctx: on (123 chars · Ctrl+T to disable)` | 启用，有 123 字 context 可用 |
+| `ctx: on (waiting for Claude)` | 启用，但 Claude 还没说过话 |
+| `ctx: off (Ctrl+T to enable)` | 禁用 |
+
+什么时候关：
+- 切全新话题时（避免被前一轮误导）
+- 翻译"那个"、"再加一条"等本身已经独立成意思的字面命令
+
+---
+
+## 自定义翻译 prompt
+
+每个翻译方向有一个 user prompt 和一个 default prompt：
+
+| 翻译方向 | 用途 |
+|---|---|
+| `zh-to-en` | 用户中文输入 → Claude Code prompt（无上下文）|
+| `zh-to-en-with-context` | 同上，但带上一轮 Claude 英文回复作消歧上下文 |
+| `en-to-zh` | Claude 英文回复 → 显示给用户的中文 |
+
+**user prompt 非空时完全替换 default**。设置面板里 `Ctrl+E` → 选 `user.<方向>` → Enter → 多行编辑器输入你的自定义 prompt → Ctrl+S 保存。
+
+典型用例：
+
+- **域专业术语词典**：`Domain: traditional Chinese medicine. Glossary: 经络=meridians, 气=qi (do not translate).`
+- **风格偏好**：`用您而不是你。错误信息保留英文。React/Vue/CSS 术语不译。`
+
+要看默认 prompt 长什么样：在面板里选 `default.<方向>` → Enter，会弹只读查看器看完整 base prompt。
+
+或用 CLI：
+
+```bash
+cc-zh-watcher prompts show zh-to-en --base
+```
+
+---
+
+## 配置文件
+
+存在用户主目录，优先级 env > project-local > user-global > 默认：
+
+```
+~/.config/cc-zh-watcher/config.json     用户级（默认）
+<project>/.cc-zh-watcher.json           项目级（可选）
+环境变量：
+  CC_ZH_API_KEY                         覆盖 api_key
+  CC_ZH_BASE_URL                        覆盖 base_url
+  CC_ZH_MODEL                           覆盖 model
+  CC_ZH_TIMEOUT                         覆盖 timeout_seconds
+```
+
+完整 schema：
+
+```jsonc
+{
+  "api_key":         "sk-...",                          // 必填
+  "base_url":        "https://api.deepseek.com/v1",     // 默认 https://api.openai.com/v1
+  "model":           "deepseek-v4-pro",                 // 默认 gpt-4o-mini
+  "timeout_seconds": 90,                                // 默认 30
+
+  // 可选 — user prompt（非空替换内置 default）
+  "prompts": {
+    "zh-to-en":              "...",
+    "zh-to-en-with-context": "...",
+    "en-to-zh":              "..."
+  }
+}
+```
+
+---
+
+## API 调用 metrics
+
+状态栏第三行实时显示：
+
+| 显示 | 含义 |
+|---|---|
+| `api: idle` | 还没发过请求 |
+| `api (zh-to-en): ⏱ 0.8s` | 进行中（黄色，每 200ms 自刷新计时） |
+| `api (zh-to-en): ✓ 1.2s · 234 tok` | 成功（绿色，耗时 + token 消耗）|
+| `api (en-to-zh): ✗ HTTP 401 (0.3s)` | 失败（红色，错误代码 + 耗时）|
+
+右侧累计：
+
+```
+session: 12 calls · 8.4k tok           ← 全部成功
+session: 12 calls · 8.4k tok · 3 err   ← 有失败时红色高亮
+```
+
+历史可查询：
+
+```bash
+cc-zh-watcher history --tail 5
+cc-zh-watcher history --grep BLS
+cc-zh-watcher history --direction zh-to-en --json
+```
+
+---
+
+## FAQ
+
+### `Ctrl+E` 没反应？
+
+老版本一度用 `Ctrl+,`（VS Code 习惯），但终端不发这个序列。现在是 `Ctrl+E`。如果你装的是 < 0.1.0 老版本，升级一下。
+
+### 翻译超时？
+
+DeepSeek 长 prompt 偶尔超过 30s 默认超时。改 `timeout_seconds: 90` 或更大。
+
+### Session 选错了？
+
+`cc-zh-watcher --pick` 重新选。状态会写到 `<project>/.claude/cache/cc-zh-watcher-state.json`，下次直接用。
+
+### 想看每次实际发送的英文 prompt？
+
+`cc-zh-watcher history --tail 1` 看最近一条；`cc-zh-watcher history --json` 拿机器可读格式。
+
+### 翻译质量不行？
+
+1. 换更强的 model（如 `gpt-4o` 或 `deepseek-v4-pro`）
+2. 在设置面板加 user prompt 给翻译器更多上下文 / 术语
+3. 调高 `timeout_seconds`，更强的模型可能需要更长时间
+
+### Claude Code 找不到 `/i` 命令？
+
+确认在你的项目目录下跑过 `cc-zh-watcher install`。检查 `.claude/commands/i.md` 是否存在。
+
+### 卸载？
+
+```bash
+# 在每个用过的项目里
+cc-zh-watcher uninstall
+
+# 删二进制
+npm uninstall -g cc-zh-watcher
+
+# 删 user-global config（按需）
+rm -rf ~/.config/cc-zh-watcher
+```
+
+---
+
+## 限制
+
+- **Prompt 不能含字面 `\n`**：单行 TextInput 没法输入换行。要嵌入换行：watcher 关掉，手编 `~/.config/cc-zh-watcher/config.json` 里 `prompts.<dir>` 字段
+- **不重放历史**：watcher 启动时只翻译之后的新 assistant text，已有对话历史不翻译。要回看历史用终端原生 scrollback
+- **单 session 监听**：watcher 一次只盯一个 Claude Code session。多 session 并发要开多个 watcher 实例
+- **翻译延迟**：每次输入需等翻译 API 返回（典型 0.5-3 秒），慢于直接英文输入。trade-off
+
+---
+
+
+## License
+
+MIT — 见 [LICENSE](./LICENSE)