cc-viewer 1.6.97 → 1.6.99

package/concepts/de/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer 全局配置参考
+
+## 一、全局设置面板（UI）
+
+通过左上角菜单 → "全局设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 过滤无关请求 | 开关 | 开 | 隐藏心跳、count_tokens、子代理等非主代理请求 |
+| 默认展开 Body Diff JSON | 开关 | 关 | 请求详情面板中的 Body Diff 区域默认展开 |
+| 日志目录设置 | 文本输入 | `~/.claude/cc-viewer` | 项目日志的读写根目录，支持 `~/` 展开。修改后回车或失焦保存，立即生效 |
+
+## 二、显示设置面板（UI）
+
+通过左上角菜单 → "显示设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
+| 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
+
+## 三、偏好设置文件
+
+所有 UI 设置持久化到 `<日志目录>/preferences.json`，通过 `/api/preferences` 接口读写。
+
+```json
+{
+  "lang": "zh",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `lang` | string | 界面语言（zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk） |
+| `filterIrrelevant` | boolean | 过滤无关请求 |
+| `expandDiff` | boolean | 默认展开 Body Diff JSON |
+| `collapseToolResults` | boolean | 折叠工具结果 |
+| `expandThinking` | boolean | 展开思考过程 |
+| `showFullToolContent` | boolean | 完整展示内容 |
+| `logDir` | string | 日志目录路径 |
+| `resumeAutoChoice` | null / "continue" / "new" | 自动恢复会话选择 |
+| `disabledPlugins` | string[] | 已禁用的插件文件名列表 |
+| `presetShortcuts` | array | Agent Team 快捷指令预设 |
+
+## 四、环境变量
+
+### CC-Viewer 专有
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | 日志存储根目录。特殊值：`tmp`/`temp` 使用系统临时目录 |
+| `CCV_CLI_MODE` | 未设置 | `=1` 启用 CLI 模式（PTY 终端） |
+| `CCV_SDK_MODE` | 未设置 | `=1` 启用 Agent SDK 模式（无终端） |
+| `CCV_WORKSPACE_MODE` | 未设置 | `=1` 启用工作空间选择模式 |
+| `CCV_PROJECT_DIR` | `process.cwd()` | 项目工作目录，用于文件操作和 Git 命令 |
+| `CCV_PROXY_PORT` | 未设置 | 本地 MITM 代理端口 |
+| `CCV_BYPASS_PERMISSIONS` | 未设置 | `=1` 跳过工具权限审批（配合 `--dangerously-skip-permissions`） |
+| `CCV_DISABLE_DELTA` | 未设置 | `=1` 禁用增量日志存储，每次写入完整消息 |
+| `CCV_DEBUG` | 未设置 | `=1` 启用 HTTP 代理调试日志 |
+| `CCV_DEBUG_PLUGINS` | 未设置 | `=1` 启用插件加载调试日志 |
+
+### 内部 IPC
+
+| 变量名 | 说明 |
+|--------|------|
+| `CCVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
+| `CCV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+
+### 外部变量（读取）
+
+| 变量名 | 说明 |
+|--------|------|
+| `ANTHROPIC_BASE_URL` | 自定义 Anthropic API 地址 |
+| `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
+| `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
+
+## 五、CLI 命令参数
+
+```
+ccv [选项] [claude 参数...]
+```
+
+### CC-Viewer 专有选项
+
+| 参数 | 说明 |
+|------|------|
+| `-logger` | 安装/修复 Claude Code hooks |
+| `--uninstall` / `-uninstall` | 卸载所有 CC-Viewer 集成 |
+| `--help` / `-h` / `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+| `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
+| `--d` | `--dangerously-skip-permissions` 简写 |
+| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
+| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+
+### Claude 透传参数（常用）
+
+| 参数 | 说明 |
+|------|------|
+| `-c` / `--continue` | 继续上一次会话 |
+| `-r` / `--resume` | 恢复指定会话 |
+| `-p` / `--print` | 非交互式输出 |
+| `--model` | 指定模型 |
+| `--permission-mode` | 权限模式 |
+| `--system-prompt` | 自定义系统提示词 |
+| `--max-budget-usd` | 最大预算 |
+
+## 六、Hook 配置
+
+CC-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+
+### 1. AskUserQuestion 桥接
+- **匹配器**: `"AskUserQuestion"`
+- **命令**: `node <安装目录>/lib/ask-bridge.js`
+- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+
+### 2. 权限审批桥接
+- **匹配器**: `""` (空 = 匹配所有工具)
+- **命令**: `node <安装目录>/lib/perm-bridge.js`
+- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+
+## 七、Shell 集成
+
+CC-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+所有 `claude` 命令自动通过 CC-Viewer 代理，实现日志捕获和 Web UI 功能。
+
+卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+
+## 八、代理配置（Proxy Profile）
+
+存储在 `<日志目录>/profile.json`，通过 UI 的"代理切换"面板管理。
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "自定义", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `active` | 当前激活的配置 ID（`"max"` = 直连，无代理） |
+| `id` | 唯一标识 |
+| `name` | 显示名称 |
+| `baseURL` | 代理 API 地址（替换请求 origin） |
+| `apiKey` | 代理 API 密钥（替换认证头） |
+| `models` | 可用模型列表 |
+| `activeModel` | 当前选中的模型 |
+
+## 九、插件系统
+
+插件目录：`<日志目录>/plugins/`
+
+### 支持的 Hook 类型
+
+| Hook | 类型 | 说明 |
+|------|------|------|
+| `httpsOptions` | 瀑布 | 提供 HTTPS 证书（返回 `{ cert, key }` 或 `{ pfx }`） |
+| `localUrl` | 瀑布 | 修改本地访问 URL |
+| `serverStarted` | 并行 | 服务器启动通知 |
+| `serverStopping` | 并行 | 服务器停止通知 |
+| `onNewEntry` | 并行 | 新日志条目写入通知 |
+
+插件启用/禁用通过 `preferences.json` 的 `disabledPlugins` 数组管理。
+
+## 十、目录结构
+
+```
+~/.claude/cc-viewer/               # 日志根目录
+├── preferences.json               # 用户偏好设置
+├── workspaces.json                # 工作空间注册表
+├── profile.json                   # 代理配置
+├── plugins/                       # 插件目录
+│   └── my-plugin.js
+├── <项目名>/                       # 每个项目的日志目录
+│   ├── <项目名>_20260404_123456.jsonl  # JSONL 日志文件
+│   ├── <项目名>.json              # 统计数据（后台生成）
+│   └── images/                    # 上传图片的持久副本
+└── ...
+
+/tmp/cc-viewer-uploads/            # 临时上传文件目录
+```
+
+## 十一、服务器配置
+
+| 配置 | 值 | 说明 |
+|------|-----|------|
+| 端口范围 | 7008-7099 | 自动扫描可用端口 |
+| 绑定地址 | 0.0.0.0 | 所有网络接口 |
+| 访问令牌 | 随机 16 字节 hex | 局域网访问需要 `?token=xxx`，本机免认证 |
+| HTTPS | 仅通过插件 | 需要插件提供 `httpsOptions` hook |
+| CORS | `*` | 允许所有来源 |
+| 上传限制 | 50MB | 单文件最大上传大小 |
+
+## 十二、URL 参数
+
+| 参数 | 说明 |
+|------|------|
+| `?token=xxx` | 局域网访问认证令牌 |
+| `?logfile=path` | 打开指定历史日志文件（只读模式） |
+
+## 十三、localStorage 配置
+
+| 键 | 说明 |
+|-----|------|
+| `ccv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `ccv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cc-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/en/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer Configuration Reference
+
+## 1. Global Settings Panel (UI)
+
+Open via top-left menu → "Global Settings".
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Filter Irrelevant Requests | Switch | On | Hide heartbeat, count_tokens, sub-agent and other non-main-agent requests |
+| Expand Body Diff JSON | Switch | Off | Expand Body Diff section by default in request detail panel |
+| Log Directory | Text Input | `~/.claude/cc-viewer` | Root directory for project log read/write. Supports `~/` expansion. Takes effect immediately on Enter or blur |
+
+## 2. Display Settings Panel (UI)
+
+Open via top-left menu → "Display Settings".
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Collapse Tool Results | Switch | On | Collapse tool call result blocks in chat view |
+| Expand Thinking | Switch | On | Expand Claude's thinking/reasoning blocks by default |
+| Show Full Tool Content | Switch | Off | Show full untruncated tool call content |
+| Auto Resume Session | Switch + Options | Off | Automatically choose when session resume prompt appears: `Continue` or `New` |
+
+## 3. Preferences File
+
+All UI settings are persisted to `<log_dir>/preferences.json` via the `/api/preferences` API.
+
+```json
+{
+  "lang": "en",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `lang` | string | UI language (zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk) |
+| `filterIrrelevant` | boolean | Filter irrelevant requests |
+| `expandDiff` | boolean | Expand Body Diff JSON by default |
+| `collapseToolResults` | boolean | Collapse tool results |
+| `expandThinking` | boolean | Expand thinking blocks |
+| `showFullToolContent` | boolean | Show full content |
+| `logDir` | string | Log directory path |
+| `resumeAutoChoice` | null / "continue" / "new" | Auto resume session choice |
+| `disabledPlugins` | string[] | Disabled plugin filenames |
+| `presetShortcuts` | array | Agent Team preset shortcuts |
+
+## 4. Environment Variables
+
+### CC-Viewer Specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | Log storage root directory. Special values: `tmp`/`temp` use system temp dir |
+| `CCV_CLI_MODE` | unset | `=1` enables CLI mode (PTY terminal) |
+| `CCV_SDK_MODE` | unset | `=1` enables Agent SDK mode (no terminal) |
+| `CCV_WORKSPACE_MODE` | unset | `=1` enables workspace selection mode |
+| `CCV_PROJECT_DIR` | `process.cwd()` | Project working directory for file operations and Git commands |
+| `CCV_PROXY_PORT` | unset | Local MITM proxy port |
+| `CCV_BYPASS_PERMISSIONS` | unset | `=1` skip tool permission approval (with `--dangerously-skip-permissions`) |
+| `CCV_DISABLE_DELTA` | unset | `=1` disable incremental log storage, write full messages every time |
+| `CCV_DEBUG` | unset | `=1` enable HTTP proxy debug logging |
+| `CCV_DEBUG_PLUGINS` | unset | `=1` enable plugin loading debug logging |
+
+### Internal IPC
+
+| Variable | Description |
+|----------|-------------|
+| `CCVIEWER_PORT` | Server port for ask-bridge/perm-bridge communication |
+| `CCV_EDITOR_PORT` | Server port for ccv-editor file editing bridge |
+
+### External (Read-only)
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_BASE_URL` | Custom Anthropic API address |
+| `SHELL` | User's shell (PTY spawn and shell config detection) |
+| `http_proxy` / `HTTPS_PROXY` etc. | HTTP proxy config (via undici EnvHttpProxyAgent) |
+
+## 5. CLI Arguments
+
+```
+ccv [options] [claude args...]
+```
+
+### CC-Viewer Options
+
+| Argument | Description |
+|----------|-------------|
+| `-logger` | Install/repair Claude Code hooks |
+| `--uninstall` / `-uninstall` | Remove all CC-Viewer integration |
+| `--help` / `-h` / `help` | Show help text |
+| `--version` / `-v` | Show version |
+| `-SDK` / `--sdk` | Use Agent SDK mode |
+| `--d` | Shortcut for `--dangerously-skip-permissions` |
+| `--ad` | Shortcut for `--allow-dangerously-skip-permissions` |
+| `run` | Run command through proxy (`ccv run -- claude ...`) |
+
+### Claude Pass-through (common)
+
+| Argument | Description |
+|----------|-------------|
+| `-c` / `--continue` | Continue last session |
+| `-r` / `--resume` | Resume specific session |
+| `-p` / `--print` | Non-interactive output |
+| `--model` | Specify model |
+| `--permission-mode` | Permission mode |
+| `--system-prompt` | Custom system prompt |
+| `--max-budget-usd` | Maximum budget |
+
+## 6. Hook Configuration
+
+CC-Viewer auto-registers hooks in `~/.claude/settings.json` under `hooks.PreToolUse`:
+
+### 1. AskUserQuestion Bridge
+- **Matcher**: `"AskUserQuestion"`
+- **Command**: `node <install_dir>/lib/ask-bridge.js`
+- **Purpose**: Forward Claude's questions to Web UI, wait for user answers
+
+### 2. Permission Approval Bridge
+- **Matcher**: `""` (empty = match all tools)
+- **Command**: `node <install_dir>/lib/perm-bridge.js`
+- **Purpose**: Only `Bash`/`Edit`/`Write`/`NotebookEdit` require Web UI approval; others pass through
+
+## 7. Shell Integration
+
+CC-Viewer injects a `claude()` function into `~/.zshrc` (or `.bashrc`):
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+All `claude` commands are automatically routed through CC-Viewer proxy for log capture and Web UI features.
+
+Uninstall: `ccv --uninstall` or manually delete content between the markers.
+
+## 8. Proxy Configuration (Proxy Profile)
+
+Stored in `<log_dir>/profile.json`, managed via the "Proxy Switch" panel in the UI.
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "Custom", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `active` | Active profile ID (`"max"` = direct connection, no proxy) |
+| `id` | Unique identifier |
+| `name` | Display name |
+| `baseURL` | Proxy API address (replaces request origin) |
+| `apiKey` | Proxy API key (replaces auth headers) |
+| `models` | Available model list |
+| `activeModel` | Currently selected model |
+
+## 9. Plugin System
+
+Plugin directory: `<log_dir>/plugins/`
+
+### Supported Hook Types
+
+| Hook | Type | Description |
+|------|------|-------------|
+| `httpsOptions` | Waterfall | Provide HTTPS certificate (return `{ cert, key }` or `{ pfx }`) |
+| `localUrl` | Waterfall | Modify local access URL |
+| `serverStarted` | Parallel | Server startup notification |
+| `serverStopping` | Parallel | Server shutdown notification |
+| `onNewEntry` | Parallel | New log entry written notification |
+
+Plugin enable/disable managed via `disabledPlugins` array in `preferences.json`.
+
+## 10. Directory Structure
+
+```
+~/.claude/cc-viewer/               # Log root directory
+├── preferences.json               # User preferences
+├── workspaces.json                # Workspace registry
+├── profile.json                   # Proxy configuration
+├── plugins/                       # Plugin directory
+│   └── my-plugin.js
+├── <project>/                     # Per-project log directory
+│   ├── <project>_20260404_123456.jsonl  # JSONL log files
+│   ├── <project>.json             # Stats data (background generated)
+│   └── images/                    # Persistent uploaded image copies
+└── ...
+
+/tmp/cc-viewer-uploads/            # Temporary upload file directory
+```
+
+## 11. Server Configuration
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| Port range | 7008-7099 | Auto-scans for available port |
+| Bind address | 0.0.0.0 | All network interfaces |
+| Access token | Random 16-byte hex | LAN access requires `?token=xxx`; localhost is exempt |
+| HTTPS | Plugin only | Requires plugin providing `httpsOptions` hook |
+| CORS | `*` | All origins allowed |
+| Upload limit | 50MB | Maximum single file upload size |
+
+## 12. URL Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `?token=xxx` | LAN access authentication token |
+| `?logfile=path` | Open specific historical log file (read-only mode) |
+
+## 13. localStorage Settings
+
+| Key | Description |
+|-----|-------------|
+| `ccv_cacheExpireAt` | Cache countdown expiration time |
+| `ccv_cacheType` | Cache type label |
+| `ccv_sseSlim` | Enable SSE incremental pruning (desktop performance optimization) |
+| `ccv_calibrationModel` | KV-Cache context window calibration model |
+| `ccv_fileExplorerOpen` | File explorer panel toggle |
+| `cc-viewer-terminal-width` | Terminal panel width (pixels) |

package/concepts/es/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer 全局配置参考
+
+## 一、全局设置面板（UI）
+
+通过左上角菜单 → "全局设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 过滤无关请求 | 开关 | 开 | 隐藏心跳、count_tokens、子代理等非主代理请求 |
+| 默认展开 Body Diff JSON | 开关 | 关 | 请求详情面板中的 Body Diff 区域默认展开 |
+| 日志目录设置 | 文本输入 | `~/.claude/cc-viewer` | 项目日志的读写根目录，支持 `~/` 展开。修改后回车或失焦保存，立即生效 |
+
+## 二、显示设置面板（UI）
+
+通过左上角菜单 → "显示设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
+| 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
+
+## 三、偏好设置文件
+
+所有 UI 设置持久化到 `<日志目录>/preferences.json`，通过 `/api/preferences` 接口读写。
+
+```json
+{
+  "lang": "zh",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `lang` | string | 界面语言（zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk） |
+| `filterIrrelevant` | boolean | 过滤无关请求 |
+| `expandDiff` | boolean | 默认展开 Body Diff JSON |
+| `collapseToolResults` | boolean | 折叠工具结果 |
+| `expandThinking` | boolean | 展开思考过程 |
+| `showFullToolContent` | boolean | 完整展示内容 |
+| `logDir` | string | 日志目录路径 |
+| `resumeAutoChoice` | null / "continue" / "new" | 自动恢复会话选择 |
+| `disabledPlugins` | string[] | 已禁用的插件文件名列表 |
+| `presetShortcuts` | array | Agent Team 快捷指令预设 |
+
+## 四、环境变量
+
+### CC-Viewer 专有
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | 日志存储根目录。特殊值：`tmp`/`temp` 使用系统临时目录 |
+| `CCV_CLI_MODE` | 未设置 | `=1` 启用 CLI 模式（PTY 终端） |
+| `CCV_SDK_MODE` | 未设置 | `=1` 启用 Agent SDK 模式（无终端） |
+| `CCV_WORKSPACE_MODE` | 未设置 | `=1` 启用工作空间选择模式 |
+| `CCV_PROJECT_DIR` | `process.cwd()` | 项目工作目录，用于文件操作和 Git 命令 |
+| `CCV_PROXY_PORT` | 未设置 | 本地 MITM 代理端口 |
+| `CCV_BYPASS_PERMISSIONS` | 未设置 | `=1` 跳过工具权限审批（配合 `--dangerously-skip-permissions`） |
+| `CCV_DISABLE_DELTA` | 未设置 | `=1` 禁用增量日志存储，每次写入完整消息 |
+| `CCV_DEBUG` | 未设置 | `=1` 启用 HTTP 代理调试日志 |
+| `CCV_DEBUG_PLUGINS` | 未设置 | `=1` 启用插件加载调试日志 |
+
+### 内部 IPC
+
+| 变量名 | 说明 |
+|--------|------|
+| `CCVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
+| `CCV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+
+### 外部变量（读取）
+
+| 变量名 | 说明 |
+|--------|------|
+| `ANTHROPIC_BASE_URL` | 自定义 Anthropic API 地址 |
+| `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
+| `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
+
+## 五、CLI 命令参数
+
+```
+ccv [选项] [claude 参数...]
+```
+
+### CC-Viewer 专有选项
+
+| 参数 | 说明 |
+|------|------|
+| `-logger` | 安装/修复 Claude Code hooks |
+| `--uninstall` / `-uninstall` | 卸载所有 CC-Viewer 集成 |
+| `--help` / `-h` / `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+| `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
+| `--d` | `--dangerously-skip-permissions` 简写 |
+| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
+| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+
+### Claude 透传参数（常用）
+
+| 参数 | 说明 |
+|------|------|
+| `-c` / `--continue` | 继续上一次会话 |
+| `-r` / `--resume` | 恢复指定会话 |
+| `-p` / `--print` | 非交互式输出 |
+| `--model` | 指定模型 |
+| `--permission-mode` | 权限模式 |
+| `--system-prompt` | 自定义系统提示词 |
+| `--max-budget-usd` | 最大预算 |
+
+## 六、Hook 配置
+
+CC-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+
+### 1. AskUserQuestion 桥接
+- **匹配器**: `"AskUserQuestion"`
+- **命令**: `node <安装目录>/lib/ask-bridge.js`
+- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+
+### 2. 权限审批桥接
+- **匹配器**: `""` (空 = 匹配所有工具)
+- **命令**: `node <安装目录>/lib/perm-bridge.js`
+- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+
+## 七、Shell 集成
+
+CC-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+所有 `claude` 命令自动通过 CC-Viewer 代理，实现日志捕获和 Web UI 功能。
+
+卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+
+## 八、代理配置（Proxy Profile）
+
+存储在 `<日志目录>/profile.json`，通过 UI 的"代理切换"面板管理。
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "自定义", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `active` | 当前激活的配置 ID（`"max"` = 直连，无代理） |
+| `id` | 唯一标识 |
+| `name` | 显示名称 |
+| `baseURL` | 代理 API 地址（替换请求 origin） |
+| `apiKey` | 代理 API 密钥（替换认证头） |
+| `models` | 可用模型列表 |
+| `activeModel` | 当前选中的模型 |
+
+## 九、插件系统
+
+插件目录：`<日志目录>/plugins/`
+
+### 支持的 Hook 类型
+
+| Hook | 类型 | 说明 |
+|------|------|------|
+| `httpsOptions` | 瀑布 | 提供 HTTPS 证书（返回 `{ cert, key }` 或 `{ pfx }`） |
+| `localUrl` | 瀑布 | 修改本地访问 URL |
+| `serverStarted` | 并行 | 服务器启动通知 |
+| `serverStopping` | 并行 | 服务器停止通知 |
+| `onNewEntry` | 并行 | 新日志条目写入通知 |
+
+插件启用/禁用通过 `preferences.json` 的 `disabledPlugins` 数组管理。
+
+## 十、目录结构
+
+```
+~/.claude/cc-viewer/               # 日志根目录
+├── preferences.json               # 用户偏好设置
+├── workspaces.json                # 工作空间注册表
+├── profile.json                   # 代理配置
+├── plugins/                       # 插件目录
+│   └── my-plugin.js
+├── <项目名>/                       # 每个项目的日志目录
+│   ├── <项目名>_20260404_123456.jsonl  # JSONL 日志文件
+│   ├── <项目名>.json              # 统计数据（后台生成）
+│   └── images/                    # 上传图片的持久副本
+└── ...
+
+/tmp/cc-viewer-uploads/            # 临时上传文件目录
+```
+
+## 十一、服务器配置
+
+| 配置 | 值 | 说明 |
+|------|-----|------|
+| 端口范围 | 7008-7099 | 自动扫描可用端口 |
+| 绑定地址 | 0.0.0.0 | 所有网络接口 |
+| 访问令牌 | 随机 16 字节 hex | 局域网访问需要 `?token=xxx`，本机免认证 |
+| HTTPS | 仅通过插件 | 需要插件提供 `httpsOptions` hook |
+| CORS | `*` | 允许所有来源 |
+| 上传限制 | 50MB | 单文件最大上传大小 |
+
+## 十二、URL 参数
+
+| 参数 | 说明 |
+|------|------|
+| `?token=xxx` | 局域网访问认证令牌 |
+| `?logfile=path` | 打开指定历史日志文件（只读模式） |
+
+## 十三、localStorage 配置
+
+| 键 | 说明 |
+|-----|------|
+| `ccv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `ccv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cc-viewer-terminal-width` | 终端面板宽度（像素） |