npm - @goodandready/dsh-context-lens - Versions diffs - 0.1.17 → 0.1.19 - Mend

@goodandready/dsh-context-lens 0.1.17 → 0.1.19

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 (11) hide show

package/README.ru.md CHANGED Viewed

@@ -2,7 +2,7 @@
 <div align="center">
-<h3>Интеллектуальный AST-скелетонизатор кода, оптимизатор контекста и компрессор логов для DeepSeek Harness</h3>
+<h3>AST-скелетонизатор кода, компрессор терминальных логов и Token Guard для DeepSeek Harness</h3>
 <p align="center">
   <a href="https://www.npmjs.com/package/@goodandready/dsh-context-lens"><img src="https://img.shields.io/npm/v/@goodandready/dsh-context-lens.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
@@ -11,7 +11,7 @@
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
 </p>
-<!-- Обязательная кнопка перехода на витрину всех проектов -->
+<!-- Кнопка перехода на витрину -->
 <p align="center">
   <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
 </p>
@@ -25,9 +25,9 @@
 <table align="center">
   <tr>
     <td align="center">
-      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему Star на GitHub</strong> — это покажет мне, что плагин полезен, и добавит мотивации продолжать его развитие.
       <br><br>
-      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+      🐛 <strong>Если вы нашли баг или хотите предложить новую функцию</strong>, создайте Issue на GitHub на любом языке — я рассмотрю предложение и реализую полезные улучшения в одной из следующих версий плагина.
     </td>
   </tr>
 </table>
@@ -36,158 +36,143 @@
 ---
-## ⚡ Обзор
+## ⚡ Обзор и решаемая проблема
-**`dsh-context-lens`** оптимизирует контекстное окно и бюджет токенов агентов **DeepSeek Harness**.
+При анализе крупных проектов и выполнении тестов контекстное окно языковой модели мгновенно заполняется реализацией второстепенных файлов и простынями логов. Это приводит к перерасходу токенов, росту задержек генерации и потере внимания агента.
-Большие объёмы контекста приводят к высоким затратам токенов, замедлению генерации и быстрой перегрузке лимитов. При изучении крупных репозиториев или прогоне тестов тысячи токенов тратятся на однотипные тела функций, логи успешных тестов и сборку.
-Плагин внедряет **фокусировку на активных файлах, AST-скелетонизацию исходного кода (JS/TS/Python/Go/Rust/Java/C/C++/SQL) и сверхбыструю эвристическую компрессию логов**, снижая расход контекста **до 85%** при сохранении 100% сигнатур типов, интерфейсов и сообщений об ошибках.
+**`dsh-context-lens`** решает эту проблему комплексно:
+1. **Фокусировка на активных путях (`context_lens_focus`)**: Редактируемые файлы передаются агенту целиком, а вспомогательные файлы рабочей зоны сворачиваются в легковесные AST-каркасы.
+2. **Многоязыковая AST-скелетонизация**: Сжатие кода на **70–85%** с сохранением классов, типов, методов и сигнатур (TypeScript, JavaScript, Python, Go, C/C++, Rust, SQL).
+3. **Эвристическая компрессия логов**: Удаление шума успешных проверок с сохранением ключевых ошибок и стек-трейсов, сжатие логов до **90%**.
+4. **Сессионная телеметрия токенов и Token Guard**: Отслеживание экономии в реальном времени, визуальные бейджи и алерты при исчерпании лимита бюджета.
 ```mermaid
 graph LR
-    subgraph RawContext [Исходные файлы и терминал]
-        Code[📁 Файлы проекта: Полные тела функций] --> LensEngine[Ядро сжатия dsh-context-lens]
-        Logs[📋 Логи тестов: Тысячи строк шума] --> LensEngine
+    subgraph RawContext [Входные контекстные потоки]
+        Code[📁 Исходный код: Полные тела функций] --> LensEngine[Движок dsh-context-lens]
+        Logs[📋 Логи сборки и тестов: Многословный вывод] --> LensEngine
     end
-    subgraph LensEngine [Обработка контекста]
-        LensEngine --> Focus{Проверка фокуса}
+    subgraph LensEngine [Конвейер обработки контекста]
+        LensEngine --> Focus{Оценка фокуса}
         Focus -->|Фокусный файл| RawKeep[Полный исходный код]
-        Focus -->|Остальной проект| AST[AST-скелетонизатор: сигнатуры, классы, типы]
-        LensEngine --> LogFilter[Компрессор логов: стек-трейсы и ошибки]
+        Focus -->|Внешний контекст| AST[AST-скелетонизатор: Типы и сигнатуры]
+        LensEngine --> LogFilter[Компрессор логов: Только ошибки и трейсы]
     end
-    subgraph Savings [Экономия токенов]
-        AST --> Agent[🤖 Агент DSH: Компактный и быстрый контекст]
+    subgraph Output [Оптимизированный контекст агента]
+        AST --> Agent[🤖 Контекст агента DSH: Компактный промпт]
         RawKeep --> Agent
         LogFilter --> Agent
-        Agent --> Tracker[📊 Счётчик сэкономленных токенов]
+        Agent --> Tracker[📊 Телеметрия экономии и Token Guard]
     end
     style RawContext fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
     style LensEngine fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
-    style Savings fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style Output fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
 ```
 ---
-## ✨ Ключевые возможности
-### 1. 🧬 Мультиязычный AST-скелетонизатор кода (`lib/ast/skeletonizer.js`)
-* Извлекает структурные интерфейсы, сигнатуры функций, методы классов, типы и экспорты для **TypeScript, JavaScript, Python, Go, Rust и Java**;
-* Поддерживает `pub async fn`, `async fn`, `pub(crate)` и `pub(super)` в Rust;
-* Сохраняет JSDoc, docstrings и структурные комментарии над определениями;
-* Удаляет внутренние тела функций и комментарии реализации, оставляя точную архитектуру файла;
-* Позволяет агенту обозревать всю структуру проекта без загрузки лишних десятков тысяч токенов.
-### 2. 🗜️ Быстрый компрессор логов (`lib/compression/log-compressor.js`)
-* Высокопроизводительный $O(n)$ фильтр шума логов тестирования и сборки (Jest, Vitest, Pytest, Go test, NPM, Webpack, Cargo, Maven/Gradle);
-* Автоматическая очистка терминальных ANSI-эскейп последовательностей;
-* Вырезает успешные проверки (`PASS`, `✓`, `ok`) и служебные уведомления;
-* Сохраняет строки падений, стек-трейсы, расхождения в утверждениях (`Expected ... Received ...`) и контекстное окружение ошибки;
-* 3 Режима сжатия: `raw`, `balanced`, `aggressive`.
-### 3. 🎯 Фокусировка на активных путях (`context_lens_focus`)
-* Динамическое назначение рабочих файлов/директорий;
-* Все внешние файлы проекта автоматически сворачиваются в легкие структурные скелеты.
-### 4. 📊 Трекер экономии токенов (`lib/tokens/tracker.js` & `lib/client.js`)
-* Фиксация точного числа токенов до и после сжатия;
-* Подсчёт накопленной экономии за сессию с отображением процента эффективности в Web UI;
-* Контроль сессионного бюджета токенов (Token Budget Guard) с предупреждением при превышении 90%.
+## ✨ Полный разбор возможностей
+### 1. 🧬 Многоязыковой AST-скелетонизатор
+* **Поддерживаемые языки**: TypeScript, JavaScript, Python, Go, C/C++, Rust, SQL DDL.
+* **Сохранение архитектурной структуры**: Оставляет импорты, классы, интерфейсы, сигнатуры функций и документирующие комментарии, вырезая громоздкие тела методов.
+* **Многострочные сигнатуры**: Корректно аккумулирует сложные типизированные параметры и возвращаемые промисы до терминаторов блоков.
+* **Чистый регулярный парсер**: Нулевой оверхед, отсутствие бинарных парсеров и мгновенная работа на любой ОС.
+### 2. 📋 Эвристический компрессор логов тестирования и сборки
+* **Поддерживаемые инструменты**: Jest, Vitest, Pytest, Go test, Cargo, Webpack, Vite, TSC, Maven, Gradle.
+* **Точечная фильтрация**: Сохраняет сообщения об ошибках, стек-трейсы, различия в assert (`Expected ... Received ...`) и строки контекста падений.
+* **3 режима сжатия**:
+  - `raw`: Фильтрация очевидного шума с сохранением общего хода выполнения.
+  - `balanced`: Баланс между сжатием и контекстом вокруг упавших тестов (по умолчанию).
+  - `aggressive`: Выделение строго строк ошибок и фреймов вызовов.
+* **Очистка ANSI**: Автоматическое удаление цветовых кодов терминала.
+### 3. 🎯 Сессионная фокусировка (`context_lens_focus`)
+* Задаёт список рабочих файлов или каталогов, редактируемых в рамках текущей задачи.
+* Фокус строго изолирован в разрезе сессии (`sessionId`).
+* Сброс фокуса доступен в один клик через кнопку в интерфейсе или вызов `context_lens_focus` с пустым списком.
+### 4. 📊 Трекер экономии токенов и Token Guard
+* Расчёт реального расхода до и после сжатия.
+* Отображение суммарно сэкономленных токенов, процента оптимизации и шкалы сессионного бюджета.
+* Настраиваемый порог предупреждения (`budgetAlertPercent`) с динамической сменой статуса индикатора.
+### 5. 🖥️ Визуальные интерфейсы и совместимость с боковыми панелями
+Context Lens оформлен по единому стандарту дизайн-системы `.cl-*` и токенов `--dsw-alias-*`:
+* **Индикатор в шапке диалога**: Размещён в слоте `conversation.session.header.utilities` (`order: 7`). Показывает статус (`◐ Lens`, `◐ <N>%` или `⚠`) и открывает интерактивный Popover с метриками и историей операций.
+* **Поддержка двух боковых панелей**: Совместим как с нативной правой панелью DSH (`ctx.sidebarRightTabs` + слот `sidebar.right.pane.tab`), так и с легаси `dsh-better-sidebar`.
+* **Изоляция сбоев (ErrorBoundary)**: Все визуальные компоненты обёрнуты в защитные границы React с кнопкой повтора («Retry»).
+* **Встроенный One-Click апдейтер**: Проверка обновлений в npm и безопасная установка в один клик из карточки настроек.
 ---
-## 🛠️ Инструменты агента (4 инструмента)
+## 🛠️ Справочник инструментов агента (5 инструментов)
+Все инструменты строго соответствуют контракту DSH: метод `output.render` возвращает массив `ContentBlock[]` (`[{ type: 'text', text: ... }]`), исключая повреждение сессий в ядре `@deepseek-ai/dsh-llm`.
 | Имя инструмента | Параметры | Описание |
 |---|---|---|
-| `context_lens_focus` | `paths: string[]`, `maxDepth?: number` | Задаёт пути активного фокуса; всё остальное сворачивается в AST-скелеты |
-| `context_lens_compress_log` | `text: string` *(или `log`)*, `mode?: "raw"\|"balanced"\|"aggressive"`, `maxLines?: number`, `auto?: boolean` | Сжимает вывод тестов и терминала, сохраняя стек-трейсы и ошибки |
-| `context_lens_compress_code` | `code: string`, `language?: string`, `maxDepth?: number`, `filePath?: string` | Генерирует структурный AST-скелет из переданного исходного кода |
-| `context_lens_stats` | *(нет)* | Возвращает метрики сэкономленных токенов, историю и статус бюджета |
+| `context_lens_focus` | `paths: string[]`, `sessionId?: string` | Назначает активные рабочие файлы сессии; сворачивает внешнее окружение в AST-каркасы |
+| `context_lens_compress_log` | `text: string` *(или `log`)*, `mode?: "raw"|"balanced"|"aggressive"`, `maxLines?: number`, `auto?: boolean` | Сжимает вывод тестов и терминала, сохраняя только ошибки и контекст падений |
+| `context_lens_compress_code` | `code: string`, `language?: string`, `maxDepth?: number`, `filePath?: string`, `sessionId?: string` | Формирует структурный AST-скелет из исходного кода |
+| `context_lens_track` | `sessionId?: string` | Возвращает накопленную статистику экономии токенов, историю и статус бюджета сессии |
+| `context_lens_reset` | `sessionId?: string` | Сбрасывает накопленные счётчики и историю сжатий при старте новой задачи |
 ---
-## 📦 Быстрая установка
+## 🔌 HTTP API плагина
-```bash
-dsh plugin --profile web add @goodandready/dsh-context-lens
-```
+| Маршрут | Метод | Защита и проверки | Описание |
+|---|---|---|---|
+| `/dsh-context-lens/status` | `GET` | Открытый (safe read) | Возвращает сессионную статистику, активные пути фокуса и историю сжатий |
+| `/dsh-context-lens/clear-focus` | `POST` | Loopback / Same-Origin | Сбрасывает пути фокуса для указанной сессии (GET отклоняется с кодом 405) |
+| `/dsh-context-lens/compress-preview` | `POST` | Loopback / Same-Origin | Предпросмотр сжатия лога с лимитом тела 256 КБ и клампингом `maxLines` (1–5000) |
+| `/api/dsh-context-lens/update` | `GET`, `POST` | Loopback + заголовок защиты | Модуль фонового обновления плагина из официального реестра npm |
 ---
-## ⚙️ Пример конфигурации (`settings.yaml`)
+## ⚙️ Справочник настроек (`settings.yaml`)
+Настройки доступны через `settings.yaml` или в интерфейсе DSH во вкладке **Настройки → Плагины → Context Lens**.
 ```yaml
 dsh-context-lens:
-  compressionMode: balanced        # 'raw', 'balanced' или 'aggressive'
-  astSkeletonMaxDepth: 3          # Максимальная глубина обхода AST-сигнатур (1..10)
-  tokenSavingsTracking: true      # Включить трекинг сэкономленных токенов
-  autoCompressThreshold: 4000     # Порог авто-сжатия в символах (0 для отключения)
+  compressionMode: balanced        # Режим сжатия логов: 'raw', 'balanced', или 'aggressive'
+  astSkeletonMaxDepth: 3          # Максимальная глубина обхода сигнатур AST (1..10)
+  tokenSavingsTracking: true      # Отслеживание и отображение экономии токенов
+  autoCompressThreshold: 4000     # Порог автосжатия логов в символах (0 для отключения)
   budgetLimit: 100000             # Сессионный лимит бюджета токенов
-  autoCollapse: true              # Автоматически сворачивать UI при исчерпании бюджета
+  budgetAlertPercent: 90          # Процент бюджета для вывода предупреждения (50..99)
+  autoCollapse: true              # Отображение предупреждающего бейджа при исчерпании бюджета
 ```
----
+| Параметр | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `compressionMode` | `string` | `balanced` | Базовый режим сжатия логов (`raw`, `balanced`, `aggressive`) |
+| `astSkeletonMaxDepth` | `number` | `3` | Максимальная глубина вложенности AST-сигнатур (от 1 до 10) |
+| `tokenSavingsTracking` | `boolean` | `true` | Расчёт сэкономленных токенов до и после сжатия |
+| `autoCompressThreshold` | `number` | `4000` | Порог авто-сжатия терминального вывода (символов) |
+| `budgetLimit` | `number` | `100000` | Выделенный бюджет токенов на одну сессию |
+| `budgetAlertPercent` | `number` | `90` | Процент расхода бюджета для активации предупреждения (от 50 до 99) |
+| `autoCollapse` | `boolean` | `true` | Отображение бейджа низкого бюджета в карточке настроек и шапке |
-## 📝 История версий
+---
-### v0.1.10
-* **Fix**: Регистрация индикатора сессии в актуальном слоте ядра `conversation.session.header.utilities` (`order: 7`).
-* **Fix**: Чип теперь отображается всегда (`◐ Lens` при отсутствии сжатий, `◐ <N>%` при наличии сэкономленных токенов, `⚠` при низком остатке бюджета).
-* **Feature**: Интерактивный выпадающий Popover по клику на чип: детальные метрики токенов, шкала прогресса бюджета, последние 3 операции и кнопка обновления.
+## 📦 Быстрая установка
-### v0.1.9
-* **Fix**: Удаление устаревших модулей ядра из инъекций клиента для совместимости с DSH 0.1.2-rc.1.
+```bash
+dsh plugin --profile web add @goodandready/dsh-context-lens
+```
-### v0.1.8
-* **Fix**: Поддержка как `text`, так и `log` в параметрах инструмента `context_lens_compress_log`.
-* **Fix**: Кроссплатформенное разрешение путей в тестах на Windows (`fileURLToPath`).
-* **Fix**: Динамическая передача и учёт `budgetLimit` в трекере токенов.
-* **Fix**: Корректная обработка цветных логов с терминальными ANSI-кодами.
-* **Fix**: Расширена поддержка Rust (`pub async fn`, `pub(crate)`) и правильные комментарии `#` для Python в AST-скелетонизаторе.
+> [!TIP]
+> После установки перезагрузите страницу Web UI или перезапустите сервис (`systemctl --user restart dsh-web`) для активации инструментов контекста.
 ---
 ## 📄 Лицензия
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
-## Changed in v0.1.11
-Исправления audit #33–#47 / #18: режим auto-compress не форсирует balanced; budgetLimit останавливает подсчёт; focus per-session; поля settings card; optional betterSidebar; серверный preview; Python imports / Java locals; общий estimateTokens; удалён unused peer dsh-credentials.
-## Changed in v0.1.12
-#43: extract shared `StatusPanel` used by LensTab and HeaderChip popover (budget bar, history, refresh).
-## Changed in v0.1.13
-- **Fix (#50)**: Безопасная регистрация вкладки BetterSidebar через `ctx.inject(['betterSidebar'], ...)` вместо прямого чтения свойства из Cordis Context Proxy. Устранена ошибка `cannot get property "betterSidebar" without inject` при загрузке клиентской половины в DSH.
-- **Fix (#50)**: Безопасное обращение к `_ctx.settingsScope` в `PluginCard` через try/catch.
-- **Тесты**: Добавлены регрессионные тесты со строгим Cordis Context Proxy.
-## Changed in v0.1.15
-- **Функциональность (#54)**: Поддержка встроенной правой боковой панели DSH (`ctx.sidebarRightTabs` + слот `sidebar.right.pane.tab`) из DSH 0.1.5-alpha.1.
-- **Совместимость (#54)**: Сохранена интеграция с легаси `dsh-better-sidebar` с детерминированными неконфликтующими идентификаторами (`@goodandready/dsh-context-lens` и `dsh-context-lens:tab`).
-- **Отказоустойчивость (#54)**: Чистая инициализация во всех 4 конфигурациях (только Native, только Legacy, обе активны, обе отсутствуют).
-- **Тесты (#54)**: Добавлена матрица тестов в `test/sidebar-matrix-54.test.mjs`.
-## Changed in v0.1.14
-- **Исправление (#52)**: Поддержка многострочных сигнатур функций и методов в `skeletonizer.js` (TypeScript, JavaScript, Rust, Go) со сложными типами параметров и аннотациями возвращаемых значений.
-- **Функция (#52)**: Добавлен инструмент `context_lens_reset` для сброса собранной статистики токенов и истории сжатий перед запуском новой задачи.
-- **Качество и локализация (#52)**: Динамическое переключение языка интерфейса (RU/EN) в чипе шапки (`HeaderChip`), боковой вкладке (`LensTab`) и панели статуса (`StatusPanel`) через `ctx.locale`.
-- **Производительность (#52)**: Адаптивный поллинг в `HeaderChip` с паузой при неактивной вкладке браузера (`document.visibilityState`) и учащённым опросом (4 сек) только при открытом поповере.
-- **Стабильность (#52)**: Атомарное сохранение конфигурации в карточке настроек (`scope.patch` / `scope.setAll`) без риска частичной записи.
-### Визуальный стиль и отказоустойчивость UI (v0.1.16+)
-Context Lens приведен к единому стандарту оформления `dsh-clinebot`:
-- **Нативные токены**: 100% совместимость со светлой и тёмной темами DSH через токены `--dsw-alias-*`.
-- **Изоляция сбоев интерфейса**: Компоненты (`PluginCard`, `LensTab`, `StatusPanel`) обёрнуты в `ErrorBoundary` с кнопкой быстрого повтора («Retry»).
-- **Реактивные настройки**: Автоматическое обновление через `scope.subscribe()` и мгновенное чтение через `scope.getSnapshot()`.
-- **Наглядная телеметрия**: Компактные карточки метрик сэкономленных токенов, процента оптимизации и шкалы сессионного бюджета.

package/README.zh.md CHANGED Viewed

@@ -36,11 +36,15 @@
 ---
-## ⚡ 插件概览
+## ⚡ 插件概览与问题背景
-**`dsh-context-lens`** 为 **DeepSeek Harness** 智能体提供深度上下文窗口与 Token 预算优化。
+超长代码库上下文与冗长的构建/测试输出流会迅速填满大语言模型的上下文窗口，造成严重的 Token 资金浪费、显著增加推理延迟，并导致智能体注意力涣散与幻觉。
-超长上下文不仅消耗高昂 Token 成本，还会导致模型注意力涣散并频繁触发限流。本插件通过**工作区文件焦点聚焦、跨语言 AST 结构骨架提取（支持 JS/TS/Python/Go/Rust/Java/C/C++/SQL）以及 $O(n)$ 终端测试日志启发式精简**，在保留 100% 架构接口与错误堆栈的前提下，将上下文体积削减**高达 85%**。
+**`dsh-context-lens`** 提供了完整的上下文优化管线：
+1. **工作区焦点聚焦 (`context_lens_focus`)**：对当前正在编辑的核心文件保持 100% 完整源码，将其余依赖代码库自动精简为轻量级 AST 骨架。
+2. **多语言 AST 结构骨架化**：支持 TypeScript, JavaScript, Python, Go, C/C++, Rust, SQL DDL，完整保留类型、类结构与函数签名，将源码体积削减 **70–85%**。
+3. **启发式测试日志压缩**：自动消除测试通过的冗余输出，精准萃取关键报错堆栈、断言差异与失败上下文，将日志体积削减高达 **90%**。
+4. **会话 Token 遥测与预算守卫**：实时精确统计压缩前后节省的 Token 数量，支持自定义预算水位预警并在 DSH 界面直观显示。
 ```mermaid
 graph LR
@@ -70,12 +74,103 @@ graph LR
 ---
-## 📦 安装指南
+## ✨ 核心特性深度解析
+### 1. 🧬 跨语言 AST 结构骨架提取器
+* **支持语言**：TypeScript, JavaScript, Python, Go, C/C++, Rust 以及 SQL DDL。
+* **架构完整性**：保留所有模块导入、类定义、接口、导出类型、函数签名与文档注释，剔除内部庞大实现细节。
+* **多行签名提取**：无缝解析复杂的跨行泛型参数、长参数列表与返回类型注解。
+* **纯正则轻量化实现**：零重型原生依赖，零二进制解析器包袱，极速跨平台运行。
+### 2. 📋 启发式终端日志精简引擎
+* **支持测试与构建工具**：Jest, Vitest, Pytest, Go test, Cargo, Webpack, Vite, TSC, Maven, Gradle。
+* **定向错误萃取**：精准识别报错摘要、异常调用堆栈、断言匹配差异 (`Expected ... Received ...`) 与错误上下文窗口。
+* **3 种压缩模式**：
+  - `raw`：过滤基础噪音行，保留总体执行日志。
+  - `balanced`：在压缩率与报错上下文之间保持平衡（默认推荐）。
+  - `aggressive`：严格仅保留报错行与堆栈帧。
+* **ANSI 码清理**：预先剥离终端控制字符与彩色 ANSI 转义序列。
+### 3. 🎯 会话文件焦点范围管理 (`context_lens_focus`)
+* 允许针对当前任务设定一组活跃聚焦文件或目录。
+* 焦点文件保持完整代码，未聚焦文件自动折叠为 AST 结构骨架。
+* 焦点状态在会话级别严格隔离 (`sessionId`)，可通过 UI 或 API 一键清除。
+### 4. 📊 Token 消耗遥测与预算守卫
+* 采用精准分词估算逻辑，实时计算压缩前后的 Token 变化。
+* 统计累计节省 Token、压缩比率与会话预算百分比。
+* 支持设置预警阈值 (`budgetAlertPercent`)，预算临界时动态发出提示。
+### 5. 🖥️ 视觉界面与双侧边栏原生集成
+完全遵循 `.cl-*` 设计标准与 DeepSeek Harness `--dsw-alias-*` 主题变量系统：
+* **对话顶栏微件**：挂载于 `conversation.session.header.utilities` 槽位（`order: 7`）。常态化显示效率徽章（`◐ Lens`, `◐ <N>%` 或 `⚠` 警告），点击展开包含详细数据与操作记录的交互式 Popover。
+* **双侧边栏深度兼容**：同时支持 DSH 原生右侧边栏（`ctx.sidebarRightTabs` + `sidebar.right.pane.tab`）及旧版 `dsh-better-sidebar`，独立 ID 互不冲突。
+* **ErrorBoundary 容灾屏障**：所有视图组件（`PluginCard`, `LensTab`, `StatusPanel`）均包裹在独立 React 错误边界内，避免页面崩溃。
+* **一键平滑升级**：设置卡片实时检测 npm 最新版本并支持免命令行一键升级。
+---
+## 🛠️ 智能体工具参考 (5 Tools)
+所有工具严格遵循 DeepSeek Harness 核心工具契约规范，`output.render` 均返回规范的 `ContentBlock[]` 数组 (`[{ type: 'text', text: ... }]`)，保障底层会话日志投影 100% 稳定可靠。
+| 工具名称 | 参数 | 说明 |
+|---|---|---|
+| `context_lens_focus` | `paths: string[]`, `sessionId?: string` | 设定当前会话的活跃聚焦文件/路径；未聚焦代码自动折叠为 AST 骨架 |
+| `context_lens_compress_log` | `text: string` *(或 `log`)*, `mode?: "raw"|"balanced"|"aggressive"`, `maxLines?: number`, `auto?: boolean` | 精简终端与测试输出日志，仅保留核心错误信息与报错堆栈 |
+| `context_lens_compress_code` | `code: string`, `language?: string`, `maxDepth?: number`, `filePath?: string`, `sessionId?: string` | 将源代码提炼为紧凑的结构化 AST 骨架 |
+| `context_lens_track` | `sessionId?: string` | 获取当前会话的累计 Token 节省统计、历史记录与预算状态 |
+| `context_lens_reset` | `sessionId?: string` | 开启新任务时重置 Token 追踪计数器与历史记录 |
+---
+## 🔌 HTTP 接口参考
+| 路由 | 请求方法 | 权限与安全策略 | 功能说明 |
+|---|---|---|---|
+| `/dsh-context-lens/status` | `GET` | 开放只读 | 查询会话 Token 节省数据、当前焦点路径与操作历史 |
+| `/dsh-context-lens/clear-focus` | `POST` | 仅限环回 (Loopback) / 同源 | 清除指定会话的焦点路径设置（GET 请求返回 405） |
+| `/dsh-context-lens/compress-preview` | `POST` | 仅限环回 / 同源 | 日志压缩预览（限制请求体 256KB，`maxLines` 范围 1–5000） |
+| `/api/dsh-context-lens/update` | `GET`, `POST` | 环回 + 安全请求头校验 | 应用内一键升级模块，安全调用后台进行版本更新 |
+---
+## ⚙️ 配置面板参考 (`settings.yaml`)
+可通过 `settings.yaml` 或在 DSH Web 界面中的 **设置 → 插件设置 → Context Lens** 进行配置。
+```yaml
+dsh-context-lens:
+  compressionMode: balanced        # 日志精简策略: 'raw', 'balanced', 或 'aggressive'
+  astSkeletonMaxDepth: 3          # AST 结构骨架最大解析深度 (1..10)
+  tokenSavingsTracking: true      # 开启并展示实时 Token 节省监控
+  autoCompressThreshold: 4000     # 自动触发日志精简的字符长度阈值 (设为 0 禁用)
+  budgetLimit: 100000             # 单会话 Token 预算上限限额
+  budgetAlertPercent: 90          # 触发预警徽章的预算百分比水位 (50..99)
+  autoCollapse: true              # 预算临界时在界面显示警告徽章
+```
+| 参数项 | 类型 | 默认值 | 功能说明 |
+|---|---|---|---|
+| `compressionMode` | `string` | `balanced` | 默认日志压缩激进度 (`raw`, `balanced`, `aggressive`) |
+| `astSkeletonMaxDepth` | `number` | `3` | AST 骨架提取最大深度层级（1 至 10） |
+| `tokenSavingsTracking` | `boolean` | `true` | 实时追踪压缩前后的 Token 节省数据 |
+| `autoCompressThreshold` | `number` | `4000` | 超过该字符长度时自动执行日志压缩 |
+| `budgetLimit` | `number` | `100000` | 单会话分配的最大 Token 预算上限 |
+| `budgetAlertPercent` | `number` | `90` | 触发低预算预警的百分比阈值（50 至 99） |
+| `autoCollapse` | `boolean` | `true` | 在设置卡片与顶栏徽章中显示预算告急提示 |
+---
+## 📦 快速安装
 ```bash
 dsh plugin --profile web add @goodandready/dsh-context-lens
 ```
+> [!TIP]
+> 安装完成后，请刷新 DSH Web 界面或重启服务 (`systemctl --user restart dsh-web`) 以激活上下文压缩工具。
 ---
 ## 📄 开源协议