cx-viewer 1.0.0

package/concepts/ar/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (مقارنة تزايدية لجسم الطلب)
+
+## الخلفية
+
+يعتمد MainAgent في Claude Code آلية إرسال السياق الكامل — حيث يحمل كل طلب سجل المحادثة الكامل وsystem prompt وتعريفات الأدوات وغيرها. هذا يعني أنه مع تقدم المحادثة يصبح جسم الطلب أكبر فأكبر، ومن الصعب تحديد "ما الجديد في هذه الجولة" عند عرض Body الخام مباشرة.
+
+Body Diff JSON صُمم لحل هذه المشكلة: يقارن تلقائياً بين طلبي MainAgent متتاليين ويستخلص الجزء التزايدي، مما يتيح لك رؤية المحتوى الجديد الفعلي في هذا الطلب بنظرة واحدة.
+
+## آلية العمل
+
+1. **تحديد طلبات MainAgent المتتالية**: يجب أن يكون الطلب الحالي من نوع MainAgent مع وجود طلب MainAgent سابق
+2. **مقارنة حقل بحقل**: يتم فحص جميع الحقول العلوية في جسم الطلب مع تخطي الخصائص الداخلية ذات البادئة `_`
+3. **استخلاص الفروقات الذكي**:
+   - الحقول الجديدة: تُعرض مباشرة
+   - الحقول المحذوفة: لا تُعرض (عادة لا تؤثر على الفهم)
+   - الحقول المتغيرة: تُعرض القيمة الحالية
+   - معالجة خاصة لمصفوفة `messages`: تُعرض فقط الرسائل الجديدة (لأن المحادثة العادية تعمل بنمط الإلحاق، والرسائل السابقة لا تتغير)
+4. **كشف تقلص جسم الطلب**: إذا كان جسم الطلب الحالي أصغر من السابق، فهذا يعني حدوث اقتطاع للسياق أو إعادة تعيين الجلسة، وفي هذه الحالة تُعرض رسالة توضيحية بدلاً من diff
+
+## السيناريوهات النموذجية
+
+في جولة محادثة عادية، يحتوي Body Diff JSON عادة على:
+- `messages`: رسالة أو رسالتان جديدتان (مدخلات المستخدم + رد المساعد من الجولة السابقة)
+
+إذا رأيت تغييرات في حقول مثل `system` أو `tools` أو `model` في الـ diff، فهذا يعني حدوث تغيير في التكوين في هذه الجولة، وهو غالباً سبب إعادة بناء الذاكرة المؤقتة.
+
+## طريقة الاستخدام
+
+- يُعرض Body Diff JSON في لوحة تفاصيل طلب MainAgent
+- انقر على العنوان للتوسيع/الطي
+- يدعم وضعي عرض JSON وText، بالإضافة إلى النسخ بنقرة واحدة
+- في **CC-Viewer → الإعدادات العامة** في الزاوية العلوية اليسرى، يمكنك تعيين "توسيع Body Diff JSON افتراضياً"

package/concepts/ar/BodyFields.md

@@ -0,0 +1,42 @@
+# شرح حقول Request Body
+
+شرح الحقول العليا لجسم طلب `/v1/messages` في Claude API.
+
+## قائمة الحقول
+
+| الحقل | النوع | الشرح |
+|------|------|------|
+| **model** | string | اسم النموذج المستخدم، مثل `claude-opus-4-6`، `claude-sonnet-4-6` |
+| **messages** | array | سجل رسائل المحادثة. تحتوي كل رسالة على `role` (user/assistant) و`content` (مصفوفة من الكتل مثل النصوص والصور وtool_use وtool_result) |
+| **system** | array | System prompt. يتضمن التعليمات الأساسية لـ Codex وتعليمات استخدام الأدوات ومعلومات البيئة ومحتوى CLAUDE.md وغيرها. الكتل التي تحمل `cache_control` يتم تخزينها مؤقتًا عبر prompt caching |
+| **tools** | array | قائمة تعريفات الأدوات المتاحة. تحتوي كل أداة على `name` و`description` و`input_schema` (JSON Schema). عادةً يمتلك MainAgent أكثر من 20 أداة، بينما يمتلك SubAgent عددًا قليلًا فقط |
+| **metadata** | object | البيانات الوصفية للطلب، تتضمن عادةً `user_id` لتحديد هوية المستخدم |
+| **max_tokens** | number | الحد الأقصى لعدد الرموز (tokens) في رد النموذج الواحد، مثل `16000`، `64000` |
+| **thinking** | object | تكوين التفكير الموسع. `type: "enabled"` يُفعّل وضع التفكير، و`budget_tokens` يتحكم في الحد الأقصى لرموز التفكير |
+| **context_management** | object | تكوين إدارة السياق. `truncation: "auto"` يسمح لـ Codex باقتطاع سجل الرسائل الطويل تلقائيًا |
+| **output_config** | object | تكوين المخرجات، مثل إعداد `format` |
+| **stream** | boolean | ما إذا كان يتم تفعيل الاستجابة المتدفقة. يستخدم Codex دائمًا `true` |
+
+## بنية messages
+
+حقل `content` لكل رسالة هو مصفوفة من الكتل، والأنواع الشائعة هي:
+
+- **text**: محتوى نصي عادي
+- **tool_use**: استدعاء النموذج لأداة (يحتوي على `name`، `input`)
+- **tool_result**: نتيجة تنفيذ الأداة (يحتوي على `tool_use_id`، `content`)
+- **image**: محتوى صورة (base64 أو URL)
+- **thinking**: عملية تفكير النموذج (وضع التفكير الموسع)
+
+## بنية system
+
+تتضمن مصفوفة system prompt عادةً:
+
+1. **تعليمات الوكيل الأساسية** ("You are Codex...")
+2. **مواصفات استخدام الأدوات**
+3. **محتوى CLAUDE.md** (تعليمات على مستوى المشروع)
+4. **تذكيرات المهارات** (skills reminder)
+5. **معلومات البيئة** (نظام التشغيل، الصدفة، حالة git، إلخ) — في الواقع يعتمد Codex بشكل كبير على git. إذا كان المشروع يحتوي على مستودع git، يمكن لـ Codex إظهار فهم أفضل للمشروع، بما في ذلك القدرة على جلب التغييرات البعيدة وسجلات الالتزام للمساعدة في التحليل
+
+الكتل المعلّمة بـ `cache_control: { type: "ephemeral" }` يتم تخزينها مؤقتًا بواسطة Anthropic API لمدة 5 دقائق. عند إصابة الذاكرة المؤقتة يتم المحاسبة كـ `cache_read_input_tokens` (أقل بكثير من `input_tokens`).
+
+> **ملاحظة**: بالنسبة للعملاء الخاصين مثل Codex، لا يعتمد خادم Anthropic فعليًا بشكل كامل على خاصية `cache_control` في الطلب لتحديد سلوك التخزين المؤقت. يقوم الخادم بتنفيذ سياسة التخزين المؤقت تلقائيًا لحقول معينة (مثل system prompt وتعريفات الأدوات)، حتى لو لم يحمل الطلب علامة `cache_control` بشكل صريح. لذلك، عندما لا ترى هذه الخاصية في جسم الطلب، لا تحتاج إلى الاستغراب — فالخادم قد أنجز عملية التخزين المؤقت في الكواليس، لكنه لم يكشف هذه المعلومات للعميل. هذا تفاهم ضمني بين Codex وAnthropic API.

package/concepts/ar/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (إعادة بناء الذاكرة المؤقتة)
+
+## الخلفية
+
+تقوم آلية prompt caching من Anthropic بتجميع system → tools → messages (حتى نقطة توقف الذاكرة المؤقتة) بالترتيب كمفتاح للذاكرة المؤقتة. عندما يتطابق مفتاح الذاكرة المؤقتة تماماً مع الطلب السابق، تُرجع الـ API قيمة `cache_read_input_tokens` (إصابة الذاكرة المؤقتة)؛ وعندما يتغير المفتاح، تُعيد الـ API إنشاء الذاكرة المؤقتة وتُرجع كمية كبيرة من `cache_creation_input_tokens`، أي إعادة بناء الذاكرة المؤقتة.
+
+إعادة بناء الذاكرة المؤقتة تعني رسوم tokens إضافية (سعر cache creation أعلى من cache read)، لذا فإن تحديد سبب إعادة البناء له قيمة مباشرة في تحسين التكاليف.
+
+## تصنيف أسباب إعادة بناء الذاكرة المؤقتة
+
+يحدد cc-viewer بدقة سبب إعادة بناء الذاكرة المؤقتة من خلال مقارنة body طلبي MainAgent المتتاليين:
+
+| reason | المعنى | طريقة التحديد |
+|--------|--------|---------------|
+| `ttl` | انتهاء صلاحية الذاكرة المؤقتة | مرور أكثر من 5 دقائق منذ آخر طلب MainAgent |
+| `system_change` | تغيير system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | تغيير تعريفات الأدوات | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | تبديل النموذج | `prev.model !== curr.model` |
+| `msg_truncated` | اقتطاع مكدس الرسائل | عدد رسائل الطلب الحالي أقل من السابق، عادة بسبب تجاوز نافذة السياق |
+| `msg_modified` | تعديل الرسائل التاريخية | عدم تطابق محتوى الرسائل السابقة (في الإلحاق العادي يجب أن تكون البادئة متطابقة تماماً) |
+| `key_change` | تغيير مفتاح غير معروف | احتياطي عندما لا تتطابق أي من الشروط أعلاه |
+
+## أولوية التحديد
+
+1. فحص الفاصل الزمني أولاً — إذا تجاوز 5 دقائق يُحدد مباشرة كـ `ttl` دون مقارنة body
+2. ثم فحص model وsystem وtools وmessages بالترتيب
+3. قد يتطابق طلب واحد مع أسباب متعددة (مثل تبديل النموذج + تغيير system prompt)، وفي هذه الحالة تحتوي مصفوفة `reasons` على جميع العناصر المتطابقة ويُعرض tooltip بأسطر متعددة
+
+## السيناريوهات الشائعة
+
+- **`ttl`**: توقف المستخدم عن العمل لأكثر من 5 دقائق ثم استأنف، وانتهت صلاحية الذاكرة المؤقتة طبيعياً
+- **`system_change`**: قام Claude Code بتحديث system prompt (مثل تحميل CLAUDE.md جديد أو تغيير تعليمات المشروع)
+- **`tools_change`**: اتصال/انقطاع خادم MCP أدى إلى تغيير قائمة الأدوات المتاحة
+- **`model_change`**: قام المستخدم بتبديل النموذج عبر أمر `/model`
+- **`msg_truncated`**: محادثة طويلة أدت إلى تفعيل إدارة نافذة السياق، وقام Claude Code باقتطاع الرسائل المبكرة
+- **`msg_modified`**: قام Claude Code بتعديل الرسائل التاريخية (مثل استبدال `/compact` للملخص المضغوط بالرسائل الأصلية)

package/concepts/ar/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 配置
+
+| 键 | 说明 |
+|-----|------|
+| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `cxv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cc-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/ar/KVCacheContent.md

@@ -0,0 +1,49 @@
+# محتوى KV-Cache المُخزَّن مؤقتًا
+
+## ما هو Prompt Caching؟
+
+عندما تتحدث مع Claude، يرسل كل طلب API سياق المحادثة الكامل (system prompt + تعريفات الأدوات + الرسائل السابقة). تقوم آلية prompt caching من Anthropic بتخزين محتوى البادئة المحسوب مسبقًا على الخادم، وإذا كانت البادئة متطابقة في الطلبات اللاحقة، يتم إعادة استخدام النتائج المُخزَّنة مباشرةً وتخطي الحسابات المكررة، مما يقلل بشكل كبير من زمن الاستجابة والتكاليف.
+
+في cc-viewer، يُشار إلى هذه الآلية بـ "KV-Cache"، وهي تُطابق prompt caching على مستوى Anthropic API، وليس ذاكرة key-value الخاصة بطبقات الانتباه في transformer داخل LLM.
+
+## كيفية عمل التخزين المؤقت
+
+يجمع prompt caching من Anthropic مفاتيح الذاكرة المؤقتة بترتيب ثابت:
+
+```
+Tools → System Prompt → Messages (حتى نقطة فاصل الذاكرة المؤقتة)
+```
+
+طالما أن هذه البادئة متطابقة تمامًا مع أي طلب سابق ضمن نافذة TTL، فإن API يصل إلى الذاكرة المؤقتة (ويعيد `cache_read_input_tokens`)، بدلاً من إعادة الحساب (`cache_creation_input_tokens`).
+
+> **Claude Code لا يعتمد بشكل صارم على خاصية `cache_control`، حيث يتعاون الخادم بإزالة بعض هذه الخصائص، ومع ذلك لا يزال قادرًا على إنشاء ذاكرة مؤقتة بشكل جيد، لذا عدم رؤية خاصية `cache_control` لا يعني عدم وجود تخزين مؤقت**
+>
+> بالنسبة للعملاء المتخصصين مثل Claude Code، لا يعتمد خادم Anthropic بشكل كامل على خاصية `cache_control` في الطلب لتحديد سلوك التخزين المؤقت. يقوم الخادم تلقائيًا بتنفيذ سياسة التخزين المؤقت لحقول معينة (مثل system prompt وتعريفات الأدوات)، حتى لو لم يحمل الطلب صراحةً علامة `cache_control`. لذلك، عندما لا ترى هذه الخاصية في نص الطلب، لا تقلق — فقد أكمل الخادم عملية التخزين المؤقت خلف الكواليس، لكنه ببساطة لم يكشف هذه المعلومة للعميل. هذا تفاهم ضمني بين Claude Code وAPI من Anthropic.
+
+## ما هو "محتوى KV-Cache المُخزَّن مؤقتًا الحالي"؟
+
+"محتوى KV-Cache المُخزَّن مؤقتًا الحالي" المعروض في cc-viewer هو المحتوى المُستخرج من آخر طلب MainAgent، والواقع قبل حدود التخزين المؤقت (cache breakpoint). يشمل بالتحديد:
+
+- **System Prompt**: تعليمات نظام Claude Code، بما في ذلك تعليمات الوكيل الأساسية، ومواصفات استخدام الأدوات، وتعليمات مشروع CLAUDE.md، ومعلومات البيئة، إلخ.
+- **Tools**: قائمة تعريفات الأدوات المتاحة حاليًا (مثل Read و Write و Bash و Agent وأدوات MCP وما إلى ذلك)
+- **Messages**: الجزء المُخزَّن مؤقتًا من سجل المحادثة (عادة الرسائل الأقدم، حتى آخر علامة `cache_control`)
+
+## لماذا يجب عرض محتوى الذاكرة المؤقتة؟
+
+1. **فهم السياق**: معرفة ما "يتذكره" Claude حاليًا يساعدك على تحديد ما إذا كان سلوكه يتوافق مع التوقعات
+2. **تحسين التكاليف**: تكلفة الوصول إلى الذاكرة المؤقتة أقل بكثير من إعادة الحساب. عرض محتوى الذاكرة المؤقتة يساعدك على فهم سبب تفعيل بعض الطلبات لإعادة بناء الذاكرة المؤقتة (cache rebuild)
+3. **تصحيح أخطاء المحادثة**: عندما لا تتوافق إجابة Claude مع التوقعات، يمكنك فحص محتوى الذاكرة المؤقتة للتأكد من صحة system prompt والرسائل السابقة
+4. **مراقبة جودة السياق**: أثناء تصحيح الأخطاء وتعديل الإعدادات وضبط الـ prompt، يوفر KV-Cache-Text منظورًا مركزيًا يساعدك على التأكد بسرعة من عدم تدهور السياق الأساسي أو تلوثه بمحتوى غير متوقع — دون الحاجة لمراجعة الرسائل الأصلية واحدة تلو الأخرى
+
+## استراتيجية التخزين المؤقت متعددة المستويات
+
+ذاكرة KV-Cache المُقابلة لـ Claude Code ليست نسخة واحدة فقط. يُنشئ الخادم ذاكرة مؤقتة منفصلة لـ Tools و System Prompt، مستقلة عن ذاكرة Messages. ميزة هذا التصميم هي: عندما تحدث فوضى في مكدس الرسائل (مثل اقتطاع السياق أو تعديل الرسائل) وتتطلب إعادة البناء، لن تتأثر ذاكرة Tools و System Prompt معها، مما يتجنب إعادة حساب كل شيء.
+
+هذه استراتيجية تحسين من جانب الخادم في المرحلة الحالية — لأن تعريفات الأدوات و System Prompt مستقرة نسبيًا أثناء الاستخدام العادي ونادرًا ما تتغير، وتخزينها بشكل مستقل يقلل من تكاليف إعادة البناء غير الضرورية. لذلك عند مراقبة الذاكرة المؤقتة ستلاحظ أنه باستثناء إعادة بناء Tools التي تتطلب تحديث كل الذاكرة المؤقتة، فإن تلف System Prompt أو Messages لا يزال يتيح وجود ذاكرة مؤقتة قابلة للتوريث.
+
+## دورة حياة الذاكرة المؤقتة
+
+- **الإنشاء**: عند الطلب الأول أو بعد انتهاء صلاحية الذاكرة المؤقتة، ينشئ API ذاكرة مؤقتة جديدة (`cache_creation_input_tokens`)
+- **الوصول**: في الطلبات اللاحقة ذات البادئة المتطابقة، يتم إعادة استخدام الذاكرة المؤقتة (`cache_read_input_tokens`)
+- **انتهاء الصلاحية**: الذاكرة المؤقتة لها TTL (وقت البقاء) مدته 5 دقائق، وتنتهي صلاحيتها تلقائيًا بعد هذه الفترة
+- **إعادة البناء**: عندما يتغير system prompt أو قائمة الأدوات أو النموذج أو محتوى الرسائل، لا يتطابق مفتاح الذاكرة المؤقتة، مما يؤدي إلى تفعيل إعادة بناء المستوى المُقابل من الذاكرة المؤقتة

package/concepts/ar/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## التعريف
+
+MainAgent هو سلسلة الطلبات الرئيسية في Claude Code عندما لا يكون في وضع agent team. كل تفاعل بين المستخدم وClaude Code ينتج سلسلة من طلبات API، حيث تشكل طلبات MainAgent سلسلة المحادثة الأساسية — فهي تحمل system prompt الكامل وتعريفات الأدوات وسجل الرسائل.
+
+## طريقة التعرف
+
+في cc-viewer، يُعرَّف MainAgent من خلال `req.mainAgent === true`، ويتم تعيينه تلقائياً بواسطة `interceptor.js` عند التقاط الطلب.
+
+شروط التحديد (يجب استيفاؤها جميعاً):
+- جسم الطلب يحتوي على حقل `system` (system prompt)
+- جسم الطلب يحتوي على مصفوفة `tools` (تعريفات الأدوات)
+- يحتوي system prompt على نص مميز لـ "Claude Code"
+
+## الفرق عن SubAgent
+
+| الخاصية | MainAgent | SubAgent |
+|---------|-----------|----------|
+| system prompt | prompt رئيسي كامل لـ Claude Code | prompt مختصر مخصص للمهمة |
+| مصفوفة tools | تحتوي على جميع الأدوات المتاحة | عادة تحتوي فقط على الأدوات اللازمة للمهمة |
+| سجل الرسائل | يتراكم سياق المحادثة الكامل | يحتوي فقط على رسائل المهمة الفرعية |
+| سلوك التخزين المؤقت | يوجد prompt caching (TTL 5 دقائق) | عادة بدون تخزين مؤقت أو تخزين مؤقت صغير |

package/concepts/ar/ProxySwitch.md

@@ -0,0 +1,50 @@
+# Hot-Switch Proxy
+
+## Overview
+
+Hot-Switch Proxy lets you dynamically redirect API requests to a different endpoint without restarting Claude Code. This is useful when using third-party API proxy services.
+
+> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | ✅ | Display name for this proxy, used to identify it |
+| **Base URL** | ✅ | Base URL of the API service (e.g. `https://api.example.com`). The original request origin will be replaced |
+| **API Key** | ✅ | API key for the proxy service, replaces the original authentication |
+| **Models** | ❌ | Comma-separated list of models supported by this proxy (e.g. `model-a, model-b`) |
+| **Active Model** | ❌ | Select the active model from the list. The `model` field in requests will be replaced |
+
+## How It Works
+
+When a proxy is active, `interceptor.js` performs the following before each API request:
+
+1. **URL Rewrite** — Replaces the request origin with the proxy's Base URL
+2. **Auth Replace** — Replaces `x-api-key` or `Authorization` header with the proxy's API Key
+3. **Model Replace** — If an active model is set, replaces the `model` field in the request body
+
+## Config File
+
+Configuration is stored at `~/.claude/cc-viewer/profile.json`. Click the folder icon in the title to open the directory:
+
+```json
+{
+  "active": "my-proxy",
+  "profiles": [
+    { "id": "max", "name": "Max" },
+    {
+      "id": "my-proxy",
+      "name": "My Proxy",
+      "baseURL": "https://api.example.com",
+      "apiKey": "sk-xxx",
+      "models": ["model-a", "model-b"],
+      "activeModel": "model-a"
+    }
+  ]
+}
+```
+
+- `active` — ID of the current profile. Set to `"max"` for direct connection (no proxy)
+- `profiles` — Profile list. `id: "max"` is built-in and cannot be deleted
+- Changes take effect within ~1.5 seconds (monitored via `fs.watchFile`), no restart needed

package/concepts/ar/QRCode.md

@@ -0,0 +1,25 @@
+# الوصول عبر رمز QR للهاتف
+
+## كيف يعمل
+
+يقوم CC Viewer بتشغيل خادم HTTP وإنشاء **عنوان شبكة محلية** (مثل `http://192.168.1.100:7008`). امسح رمز QR للوصول إلى Claude Code من هاتفك عبر نفس شبكة WiFi.
+
+## لماذا لا أستطيع الاتصال؟
+
+1. **ليس على نفس الشبكة** — يجب أن يكون الهاتف والكمبيوتر على نفس شبكة WiFi (نفس الراوتر/نفس اسم الشبكة)
+2. **حظر جدار الحماية** — قد يمنع جدار الحماية الاتصالات الواردة
+3. **عزل شبكة المؤسسة** — قد يمنع عزل AP التواصل بين الأجهزة
+4. **تداخل VPN** — قد يعطل VPN مسار الشبكة
+
+## تنبيه أمني
+
+> ⚠️ خدمة الشبكة المحلية لـ CC Viewer متاحة لجميع الأجهزة على نفس الشبكة.
+
+- كن حذراً عند استخدام **WiFi عام**
+- يستخدم CC Viewer **مصادقة بالرمز المميز** لحماية الوصول
+- يُنصح بالاستخدام على شبكات موثوقة
+
+## ما وراء الشبكة المحلية
+
+- **أدوات الأنفاق** — frp، ngrok، Tailscale، إلخ.
+- **إضافات CC Viewer** — قم بتكوين وسيط الوكيل عبر نظام الإضافات

package/concepts/ar/ResponseFields.md

@@ -0,0 +1,50 @@
+# شرح حقول Response Body
+
+شرح حقول جسم الاستجابة لواجهة Claude API `/v1/messages`.
+
+## الحقول الرئيسية
+
+| الحقل | النوع | الشرح |
+|------|------|------|
+| **model** | string | اسم النموذج المستخدم فعليًا، مثل `claude-opus-4-6` |
+| **id** | string | المعرّف الفريد لهذه الاستجابة، مثل `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | قيمة ثابتة `"message"` |
+| **role** | string | قيمة ثابتة `"assistant"` |
+| **content** | array | مصفوفة كتل المحتوى الناتجة عن النموذج، تتضمن النصوص واستدعاءات الأدوات وعملية التفكير وغيرها |
+| **stop_reason** | string | سبب التوقف: `"end_turn"` (انتهاء طبيعي)، `"tool_use"` (يلزم تنفيذ أداة)، `"max_tokens"` (بلوغ الحد الأقصى للتوكنات) |
+| **stop_sequence** | string/null | التسلسل الذي أدى إلى التوقف، عادةً `null` |
+| **usage** | object | إحصائيات استهلاك التوكنات (انظر التفاصيل أدناه) |
+
+## أنواع كتل content
+
+| النوع | الشرح |
+|------|------|
+| **text** | الرد النصي للنموذج، يحتوي على حقل `text` |
+| **tool_use** | طلب استدعاء أداة، يحتوي على `name` (اسم الأداة)، `input` (المعاملات)، `id` (معرّف الاستدعاء، يُستخدم لمطابقة tool_result) |
+| **thinking** | محتوى التفكير الموسّع (يظهر فقط عند تفعيل وضع thinking)، يحتوي على حقل `thinking` |
+
+## تفصيل حقل usage
+
+| الحقل | الشرح |
+|------|------|
+| **input_tokens** | عدد توكنات الإدخال التي لم تصب ذاكرة التخزين المؤقت (تُحاسب بالسعر الكامل) |
+| **cache_creation_input_tokens** | عدد التوكنات المُنشأة حديثًا في ذاكرة التخزين المؤقت (كتابة الذاكرة المؤقتة، تكلفتها أعلى من الإدخال العادي) |
+| **cache_read_input_tokens** | عدد التوكنات المقروءة من ذاكرة التخزين المؤقت (قراءة الذاكرة المؤقتة، تكلفتها أقل بكثير من الإدخال العادي) |
+| **output_tokens** | عدد توكنات مخرجات النموذج |
+| **service_tier** | مستوى الخدمة، مثل `"standard"` |
+| **inference_geo** | منطقة الاستدلال، مثل `"not_available"` تعني عدم توفر معلومات المنطقة |
+
+## الحقول الفرعية لـ cache_creation
+
+| الحقل | الشرح |
+|------|------|
+| **ephemeral_5m_input_tokens** | عدد توكنات إنشاء الذاكرة المؤقتة قصيرة المدى بمدة TTL تبلغ 5 دقائق |
+| **ephemeral_1h_input_tokens** | عدد توكنات إنشاء الذاكرة المؤقتة طويلة المدى بمدة TTL تبلغ ساعة واحدة |
+
+> **حول تسعير الذاكرة المؤقتة**: سعر الوحدة لـ `cache_read_input_tokens` أقل بكثير من `input_tokens`، بينما سعر الوحدة لـ `cache_creation_input_tokens` أعلى قليلًا من الإدخال العادي. لذلك، الحفاظ على معدل إصابة مرتفع لذاكرة التخزين المؤقت في المحادثات المستمرة يمكن أن يخفض التكاليف بشكل ملحوظ. يمكنك مراقبة هذه النسبة بصريًا من خلال مؤشر "معدل الإصابة" في cc-viewer.
+
+## معاني stop_reason
+
+- **end_turn**: أكمل النموذج الرد بشكل طبيعي
+- **tool_use**: يحتاج النموذج إلى استدعاء أداة، وستتضمن content كتلة `tool_use`. يجب إضافة `tool_result` إلى messages في الطلب التالي لمتابعة المحادثة
+- **max_tokens**: تم الاقتطاع بسبب بلوغ حد `max_tokens`، وقد يكون الرد غير مكتمل

package/concepts/ar/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## التعريف
+
+Search هو نوع من الـ sub-agent يُولَّد بواسطة الـ agent الرئيسي في Claude Code لتنفيذ عمليات البحث في قاعدة الكود. يُنفِّذ عمليات بحث مستهدفة في الملفات والمحتوى باستخدام أدوات مثل Glob وGrep وRead، ثم يُعيد النتائج إلى الـ agent الأصلي.
+
+## السلوك
+
+- يُولَّد تلقائياً عندما يحتاج الـ agent الرئيسي إلى البحث في قاعدة الكود أو استكشافها
+- يعمل في سياق معزول مع صلاحيات القراءة فقط
+- يستخدم Glob لمطابقة أنماط الملفات، وGrep للبحث في المحتوى، وRead لفحص الملفات
+- يُعيد نتائج البحث إلى الـ agent الأصلي لمزيد من المعالجة
+
+## متى يظهر
+
+تظهر الـ Search sub-agents عادةً في الحالات التالية:
+
+1. عندما يحتاج الـ agent الرئيسي إلى إيجاد ملفات أو دوال أو أنماط كود محددة
+2. عند طلب المستخدم استكشاف واسع لقاعدة الكود
+3. عندما يبحث الـ agent عن التبعيات أو المراجع أو أنماط الاستخدام

package/concepts/ar/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## التعريف
+
+Teammate هو agent تعاوني في وضع الفريق (Team Mode) الخاص بـ Claude Code Agent. عندما يقوم الـ agent الرئيسي بإنشاء فريق عبر `TeamCreate` واستخدام أداة `Agent` لإنشاء teammate، يعمل كل teammate كعملية agent مستقلة بسياقها الخاص ومجموعة أدواتها، ويتواصل مع أعضاء الفريق عبر `SendMessage`.
+
+## الفرق بينه وبين SubAgent
+
+| الخاصية | Teammate | SubAgent |
+|---------|----------|----------|
+| دورة الحياة | يستمر في العمل، يمكنه استقبال رسائل متعددة | مهمة لمرة واحدة، يُدمَّر عند الانتهاء |
+| طريقة التواصل | رسائل ثنائية الاتجاه عبر SendMessage | استدعاء أحادي الاتجاه من الأب إلى الابن، مع إرجاع النتيجة |
+| السياق | سياق مستقل وكامل، يُحتفظ به عبر الجولات | سياق مهمة معزول |
+| نمط التعاون | تعاون جماعي، يمكن للأعضاء التواصل فيما بينهم | هيكل هرمي، يتفاعل فقط مع الـ agent الأب |
+| نوع المهام | مهام معقدة متعددة الخطوات | مهام فردية كالبحث والاستكشاف |
+
+## السلوك
+
+- يُنشئه الـ agent الرئيسي (team lead) عبر أداة `Agent` مع تعيين `team_name`
+- يشارك قائمة المهام عبر `TaskList` / `TaskGet` / `TaskUpdate`
+- يدخل حالة الخمول (idle) بعد انتهاء كل جولة تنفيذ، وينتظر رسالة جديدة لإيقاظه
+- يمكن إنهاؤه بشكل سلس عبر `shutdown_request`
+
+## شرح لوحة الإحصائيات
+
+تعرض لوحة إحصائيات Teammate عدد استدعاءات API لكل teammate. يُظهر عمود `Name` اسم الـ teammate (مثل `reviewer-security`، `reviewer-pipeline`)، ويُظهر عمود `العدد` إجمالي طلبات API التي أنتجها ذلك الـ teammate.