cx-viewer 1.0.2 → 1.0.4

package/src/utils/workflowFormat.js

@@ -0,0 +1,52 @@
+/**
+ * Workflow 面板共享格式化工具（WorkflowPanel 与 WorkflowLiveHud 共用，纯函数无 CSS 依赖）。
+ */
+
+export const TERMINAL_STATES = new Set(['done', 'completed', 'failed', 'error', 'cancelled', 'skipped']);
+
+// 工作流状态 → i18n key（缺失时调用方回退到原始 status 字符串）。
+export const STATUS_KEYS = {
+  running: 'ui.workflow.status.running',
+  finishing: 'ui.workflow.status.finishing',
+  completed: 'ui.workflow.status.completed',
+  failed: 'ui.workflow.status.failed',
+  paused: 'ui.workflow.status.paused',
+  cancelled: 'ui.workflow.status.cancelled',
+};
+
+export function fmtDuration(ms) {
+  if (typeof ms !== 'number' || ms < 0) return '';
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  return rem ? `${m}m ${rem}s` : `${m}m`;
+}
+
+export function fmtTokens(n) {
+  if (typeof n !== 'number' || n <= 0) return '0';
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(n);
+}
+
+export function isRunning(state) {
+  return !TERMINAL_STATES.has(state);
+}
+
+export function stateGlyph(state) {
+  if (state === 'done' || state === 'completed') return '✓';
+  if (state === 'failed' || state === 'error') return '✗';
+  if (state === 'queued') return '○';
+  return '●';
+}
+
+// 甘特完成条按阶段着色：柔和、明暗主题皆可读的循环色相调色板。
+// 失败/运行中/排队仍走语义色（红/主色脉冲/灰），不取这里的值。
+const PHASE_HUES = [206, 265, 150, 32, 322, 188, 96, 0];
+
+export function phaseColor(phaseIndex) {
+  const n = PHASE_HUES.length;
+  const i = typeof phaseIndex === 'number' && phaseIndex >= 0 ? phaseIndex : 0;
+  const h = PHASE_HUES[i % n];
+  return `hsl(${h}, 48%, 50%)`;
+}

package/src/utils/workflowRuns.js

@@ -0,0 +1,118 @@
+/**
+ * 从当前会话的 requests 提取所有 Workflow(UltraCode)run。
+ *
+ * 数据源:tool_result 块在 requests[i].body.input 的 **user 轮**(与 toolResultBuilder.js
+ * 的全局索引扫描同源,见其 role==='user' 分支)。每个 Workflow 工具的后台启动返回文本
+ * 原生携带 Task ID / Run ID / Transcript dir 路径(含 sessionId),由 parseWorkflowFromText 解析,
+ * 无需服务端 _cxvWorkflow 注入——历史日志(含旧日志)同样可枚举。
+ *
+ * 镜像 teamSessionParser.js 的 extractTeamSessions 模式:纯函数、无副作用,便于 node --test 直接 import。
+ */
+
+import { extractToolResultText, parseWorkflowFromText } from './toolResultCore.js';
+
+const SUMMARY_RE = /Summary:\s*(.+)/;
+
+/**
+ * 枚举 requests 里的全部 workflow run,按 taskId 主键去重(回填缺失的 runId/sessionId),
+ * 按最早出现时间倒序(最新在前)。
+ *
+ * @param {Array} requests - ChatView 的 requests 数组(每项含 timestamp 与 body.input)
+ * @returns {Array<{ runId: string|null, taskId: string|null, sessionId: string|null,
+ *                    resultText: string, timestamp: any, summary: string|null }>}
+ */
+export function extractWorkflowRuns(requests) {
+  if (!Array.isArray(requests)) return [];
+
+  // 以「逻辑 run 键」聚合:taskId 优先(launch 文本必有、1:1 对应一次 run),
+  // 缺失才退回 runId。合并同键时回填先到条目缺失的字段,避免「仅 taskId」与
+  // 「taskId+runId」因键漂移而漏去重。
+  const byKey = new Map();
+
+  // tool_use_id → 工具名。仅认 Workflow 工具产生的 tool_result——否则其它工具
+  // 其他工具若回显含 "Workflow launched in background"/"Run ID:" 字面量的
+  // 源码或日志,会被 parseWorkflowFromText 误判为一次真实启动(自引用误检)。
+  // 与 ToolResultView 渲染内联面板前判 toolName==='Workflow' 同源,扫法对齐 toolResultBuilder。
+  const toolNameById = buildToolUseNameMap(requests);
+
+  for (const req of requests) {
+    const msgs = req?.body?.input;
+    if (!Array.isArray(msgs)) continue;
+    for (const m of msgs) {
+      if (m?.role !== 'user' || !Array.isArray(m.content)) continue;
+      for (const block of m.content) {
+        if (block?.type !== 'tool_result') continue;
+        if (toolNameById.get(block.tool_use_id) !== 'Workflow') continue;
+        const txt = extractToolResultText(block);
+        const wf = parseWorkflowFromText(txt);
+        if (!wf) continue;
+
+        const key = wf.taskId || wf.runId;
+        if (!key) continue;
+        const summary = (txt.match(SUMMARY_RE) || [])[1]?.trim() || null;
+
+        const existing = byKey.get(key);
+        if (!existing) {
+          byKey.set(key, {
+            runId: wf.runId,
+            taskId: wf.taskId,
+            sessionId: wf.sessionId,
+            resultText: txt,
+            timestamp: req?.timestamp ?? null,
+            summary,
+          });
+        } else {
+          // 回填缺失字段(取任一非空);timestamp 保留最早出现的一条。
+          if (!existing.runId && wf.runId) existing.runId = wf.runId;
+          if (!existing.taskId && wf.taskId) existing.taskId = wf.taskId;
+          if (!existing.sessionId && wf.sessionId) existing.sessionId = wf.sessionId;
+          if (!existing.summary && summary) existing.summary = summary;
+          if (isEarlier(req?.timestamp, existing.timestamp)) {
+            existing.timestamp = req.timestamp;
+            existing.resultText = txt;
+          }
+        }
+      }
+    }
+  }
+
+  // 最新在前:timestamp 降序;无 timestamp 的排末尾。
+  return Array.from(byKey.values()).sort((a, b) => tsValue(b.timestamp) - tsValue(a.timestamp));
+}
+
+/**
+ * 扫 assistant 轮(body.input)与当前轮 response(response.body.content)的 tool_use,
+ * 建 id → name 映射。tool_result 凭 tool_use_id 反查工具名,只放行 Workflow。
+ */
+function buildToolUseNameMap(requests) {
+  const map = new Map();
+  for (const req of requests) {
+    const msgs = req?.body?.input;
+    if (Array.isArray(msgs)) {
+      for (const m of msgs) {
+        if (m?.role === 'assistant' && Array.isArray(m.content)) {
+          for (const b of m.content) {
+            if (b?.type === 'tool_use' && b.id) map.set(b.id, b.name);
+          }
+        }
+      }
+    }
+    const respContent = req?.response?.body?.content;
+    if (Array.isArray(respContent)) {
+      for (const b of respContent) {
+        if (b?.type === 'tool_use' && b.id) map.set(b.id, b.name);
+      }
+    }
+  }
+  return map;
+}
+
+function tsValue(ts) {
+  if (ts == null) return -Infinity;
+  const n = typeof ts === 'number' ? ts : Date.parse(ts);
+  return Number.isNaN(n) ? -Infinity : n;
+}
+
+function isEarlier(candidate, current) {
+  return tsValue(candidate) < tsValue(current);
+}

package/src/utils/workflowStore.js

@@ -0,0 +1,94 @@
+/**
+ * Workflow live store
+ *
+ * 轻量模块级发布订阅，承接服务端 SSE `workflow_update` 事件，按 runId（及 taskId 别名）
+ * 分发给对应的 WorkflowPanel。避免 AppBase→ChatView→ChatMessage→ToolResultView→Panel
+ * 深层 prop 穿线。
+ *
+ * - publish(payload): AppBase 收到 workflow_update 时调用，payload = { runId, taskId, data, ... }。
+ * - subscribe(key, cb): WorkflowPanel 按自身 runId 或 taskId 订阅，返回退订函数。
+ * - getLatest(key): 取已缓存的最新 journal（panel 挂载时若已先到事件可即时用）。
+ */
+
+const _subs = new Map();          // key(runId|taskId) → Set<cb>
+const _latest = new Map();        // key → normalized journal data
+const _authoritative = new Set(); // keys that已收到 live===false 的权威完成快照
+
+// 「活跃工作流」追踪：供右下角悬浮 HUD 常驻展示运行中的工作流。
+const _active = new Map();         // runId → 最新 data（仅运行中/收尾中）
+const _activeSubs = new Set();     // Set<cb(list)>
+
+function _emit(key, data) {
+  const set = _subs.get(key);
+  if (!set) return;
+  for (const cb of set) {
+    try { cb(data); } catch {}
+  }
+}
+
+function _emitActive() {
+  const list = [..._active.values()];
+  for (const cb of _activeSubs) {
+    try { cb(list); } catch {}
+  }
+}
+
+function _isActive(data) {
+  return data.live === true || data.status === 'running' || data.status === 'finishing';
+}
+
+export function publish(payload) {
+  if (!payload || typeof payload !== 'object') return;
+  const data = payload.data;
+  if (!data || typeof data !== 'object') return;
+  const keys = [];
+  if (payload.runId) keys.push(payload.runId);
+  if (data.runId && data.runId !== payload.runId) keys.push(data.runId);
+  if (payload.taskId) keys.push(payload.taskId);
+  if (data.taskId && data.taskId !== payload.taskId) keys.push(data.taskId);
+  // 权威完成快照（live!==true）一旦到达即锁定该 key：忽略其后乱序到达的运行中逐帧，
+  // 否则尾随的 live 帧会把面板从「已完成」回退成「运行中」。
+  const isLive = data.live === true;
+  for (const k of keys) {
+    if (isLive && _authoritative.has(k)) continue;
+    if (!isLive) _authoritative.add(k);
+    _latest.set(k, data);
+    _emit(k, data);
+  }
+
+  // 维护活跃工作流集合（按 canonical runId 去重，避免 taskId 重复计数）
+  const rk = data.runId || payload.runId;
+  if (rk && !(isLive && _authoritative.has(rk))) {
+    if (_isActive(data)) { _active.set(rk, data); _emitActive(); }
+    else if (_active.delete(rk)) { _emitActive(); }
+  }
+}
+
+/** 订阅活跃（运行中/收尾中）工作流列表变化；立即不回调，调用 getActiveWorkflows 取初值。 */
+export function subscribeActive(cb) {
+  if (typeof cb !== 'function') return () => {};
+  _activeSubs.add(cb);
+  return () => { _activeSubs.delete(cb); };
+}
+
+/** 取当前活跃工作流列表（最新 data 数组）。 */
+export function getActiveWorkflows() {
+  return [..._active.values()];
+}
+
+export function subscribe(key, cb) {
+  if (!key || typeof cb !== 'function') return () => {};
+  let set = _subs.get(key);
+  if (!set) { set = new Set(); _subs.set(key, set); }
+  set.add(cb);
+  return () => {
+    const s = _subs.get(key);
+    if (!s) return;
+    s.delete(cb);
+    if (s.size === 0) _subs.delete(key);
+  };
+}
+
+export function getLatest(key) {
+  return key ? (_latest.get(key) || null) : null;
+}

package/vite.config.js

@@ -0,0 +1,106 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { readFileSync } from 'node:fs';
+
+function getBackendPort() {
+  try {
+    return parseInt(readFileSync('/tmp/cx-viewer-port', 'utf-8').trim(), 10);
+  } catch {
+    return 7008;
+  }
+}
+
+const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf-8'));
+
+export default defineConfig(() => {
+  const port = getBackendPort();
+  return {
+    // CXV_BASE_PATH: deployment base path (determines dist asset reference style at build time).
+    //   unset / '' → '' relative (default) — outputs ./assets/...; combined with runtime <base>
+    //                  tag, a single dist supports both root deployment and reverse-proxy sub-path
+    //                  deployment without source rebuild.
+    //   '/prefix/' → build-time hardcoded prefix (assets pinned to this sub-path).
+    //   '/' → absolute (escape hatch for the old default; set CXV_BASE_PATH=/ when absolute
+    //         /assets/... references are needed).
+    // Note: server/lib/base-path.js's normalizeBasePath is not reused here — build-time `base`
+    // has different semantics from runtime (here '/' means absolute and unset/'' means relative;
+    // at runtime both '/' and unset mean "no prefix").
+    base: (() => {
+      const v = process.env.CXV_BASE_PATH;
+      if (v === undefined) return '';          // default: relative (use CXV_BASE_PATH=/ for absolute)
+      if (v === '') return '';                 // relative paths, no trailing slash fixup
+      return v.replace(/\/?$/, '/');           // ensure trailing slash
+    })(),
+    plugins: [react()],
+    define: {
+      __APP_VERSION__: JSON.stringify(pkg.version),
+    },
+    build: {
+      outDir: 'dist',
+      // Enable for local perf / debugging: CXV_SOURCEMAP=1 npm run build (or npm run build:sourcemap).
+      // Disabled by default — size + security (don't ship .map with npm; package.json files already
+      // includes `!dist/**/*.map` as a safety net). When .map files exist, Chrome DevTools auto-loads
+      // them, making antd/cx-viewer stack frames readable (dk/ck → real names + source positions).
+      sourcemap: process.env.CXV_SOURCEMAP === '1',
+      // xterm.js 6.0.0's InputHandler.requestMode was mis-handled by the identifier mangler,
+      // causing a ReferenceError in production builds (issue #5800). Vite's default esbuild
+      // minify can't selectively disable identifier mangling (top-level esbuild options only
+      // apply to the transform phase, not minify). Switching to terser + mangle:false is
+      // the reliable workaround. Gzip size is 15-25% larger than esbuild default; revert to
+      // esbuild once xterm 6.1 stable ships with a fix.
+      minify: 'terser',
+      terserOptions: {
+        mangle: false,
+        compress: true,
+      },
+      rollupOptions: {
+        output: {
+          // Split vendor chunks to avoid bundling antd/highlight/virtuoso/xterm/codemirror
+          // into a single 3MB+ block (slows V8 parse, increases GC pressure, breaks cache granularity).
+          manualChunks: {
+            'vendor-react':      ['react', 'react-dom'],
+            'vendor-antd':       ['antd'],
+            'vendor-virtuoso':   ['react-virtuoso'],
+            'vendor-highlight':  ['highlight.js'],
+            'vendor-markdown':   ['marked', 'dompurify'],
+            'vendor-qrcode':     ['qrcode.react'],
+            'vendor-xterm': [
+              '@xterm/xterm',
+              '@xterm/addon-fit',
+              '@xterm/addon-unicode11',
+              '@xterm/addon-web-links',
+              '@xterm/addon-webgl',
+            ],
+            'vendor-codemirror': [
+              '@uiw/react-codemirror',
+              '@replit/codemirror-minimap',
+              '@codemirror/lang-javascript',
+              '@codemirror/lang-python',
+              '@codemirror/lang-json',
+              '@codemirror/lang-markdown',
+              '@codemirror/lang-go',
+              '@codemirror/lang-rust',
+              '@codemirror/lang-java',
+              '@codemirror/lang-cpp',
+              '@codemirror/lang-css',
+              '@codemirror/lang-php',
+              '@codemirror/lang-sql',
+              '@codemirror/lang-xml',
+              '@codemirror/lang-yaml',
+            ],
+            // MDXEditor is loaded via React.lazy only when opening .md files in GUI mode;
+            // separate chunk to avoid blocking first-screen load and to distinguish from vendor-codemirror.
+            'vendor-mdxeditor': ['@mdxeditor/editor'],
+          },
+        },
+      },
+    },
+    server: {
+      proxy: {
+        '/events': `http://127.0.0.1:${port}`,
+        '/api': `http://127.0.0.1:${port}`,
+        '/ws/terminal': { target: `ws://127.0.0.1:${port}`, ws: true },
+      },
+    },
+  };
+});

package/concepts/ar/CacheRebuild.md

@@ -1,36 +0,0 @@
-# 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/KVCacheContent.md

@@ -1,49 +0,0 @@
-# محتوى 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/Tool-Agent.md

@@ -1,125 +0,0 @@
-# Agent
-
-## التعريف
-
-بدء وكيل فرعي (SubAgent) لمعالجة المهام المعقدة متعددة الخطوات بشكل مستقل. الوكلاء الفرعيون هم عمليات فرعية مستقلة، لكل منها مجموعة أدوات وسياق مخصص. Agent هو النسخة المعاد تسميتها من أداة Task في الإصدارات الأحدث من Claude Code.
-
-## المعاملات
-
-| المعامل | النوع | مطلوب | الوصف |
-|---------|-------|-------|-------|
-| `prompt` | string | نعم | وصف المهمة التي سينفذها الوكيل الفرعي |
-| `description` | string | نعم | ملخص مختصر من 3-5 كلمات |
-| `subagent_type` | string | نعم | نوع الوكيل الفرعي، يحدد مجموعة الأدوات المتاحة |
-| `model` | enum | لا | تحديد النموذج (sonnet / opus / haiku)، الافتراضي يرث من الأصل |
-| `max_turns` | integer | لا | الحد الأقصى لعدد الجولات |
-| `run_in_background` | boolean | لا | هل يعمل في الخلفية، المهام الخلفية تُرجع مسار output_file |
-| `resume` | string | لا | معرف الوكيل المراد استئنافه، يستمر من آخر تنفيذ. مفيد لاستئناف وكيل فرعي سابق دون فقدان السياق |
-| `isolation` | enum | لا | وضع العزل، `worktree` ينشئ git worktree مؤقت |
-
-## أنواع الوكلاء الفرعيين
-
-| النوع | الغرض | الأدوات المتاحة |
-|-------|--------|----------------|
-| `Bash` | تنفيذ الأوامر، عمليات git | Bash |
-| `general-purpose` | مهام عامة متعددة الخطوات | جميع الأدوات |
-| `Explore` | استكشاف سريع لقاعدة الكود | جميع الأدوات باستثناء Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `Plan` | تصميم خطط التنفيذ | جميع الأدوات باستثناء Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `claude-code-guide` | أسئلة وأجوبة حول دليل استخدام Claude Code | Glob, Grep, Read, WebFetch, WebSearch |
-| `statusline-setup` | تكوين شريط الحالة | Read, Edit |
-
-## سيناريوهات الاستخدام
-
-**مناسب للاستخدام:**
-- المهام المعقدة التي تتطلب إنجازاً مستقلاً متعدد الخطوات
-- استكشاف قاعدة الكود والبحث المعمق (باستخدام نوع Explore)
-- العمل المتوازي الذي يتطلب بيئة معزولة
-- المهام طويلة المدة التي تحتاج للعمل في الخلفية
-
-**غير مناسب للاستخدام:**
-- قراءة مسار ملف محدد — استخدم Read أو Glob مباشرة
-- البحث في 2-3 ملفات معروفة — استخدم Read مباشرة
-- البحث عن تعريف فئة محددة — استخدم Glob مباشرة
-
-## ملاحظات
-
-- بعد اكتمال الوكيل الفرعي يُرجع رسالة واحدة، نتائجه غير مرئية للمستخدم ويحتاج الوكيل الرئيسي لنقلها
-- يمكن إطلاق عدة استدعاءات Agent بالتوازي في رسالة واحدة لزيادة الكفاءة
-- يتم فحص تقدم المهام الخلفية عبر أداة TaskOutput
-- نوع Explore أبطأ من استدعاء Glob/Grep مباشرة، يُستخدم فقط عندما لا يكفي البحث البسيط
-- استخدم `run_in_background: true` للمهام طويلة المدة التي لا تحتاج نتائج فورية؛ استخدم الوضع الأمامي (الافتراضي) عندما تكون النتيجة مطلوبة قبل المتابعة
-- يتيح معامل `resume` استئناف جلسة وكيل فرعي بدأت سابقاً مع الحفاظ على السياق المتراكم
-
-## النص الأصلي
-
-<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
-
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
-
-Available agent types and the tools they have access to:
-- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
-- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)
-- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
-
-When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
-
-When NOT to use the Agent tool:
-- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
-- Other tasks that are not related to the agent descriptions above
-
-Usage notes:
-- Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
-- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
-- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
-- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
-- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
-- The agent's outputs should generally be trusted
-- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
-- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
-
-Example usage:
-
-<example_agent_descriptions>
-"test-runner": use this agent after you are done writing code to run tests
-"greeting-responder": use this agent to respond to user greetings with a friendly joke
-</example_agent_descriptions>
-
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: Sure let me write a function that checks if a number is prime
-assistant: First let me use the Write tool to write a function that checks if a number is prime
-assistant: I'm going to use the Write tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
-</commentary>
-assistant: Now let me use the test-runner agent to run the tests
-assistant: Uses the Agent tool to launch the test-runner agent
-</example>
-
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
-</example>
-</textarea>