@goodandready/dsh-context-lens 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to `@goodandready/dsh-context-lens` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.20] - 2026-09-18
+
+### Fixed
+- **UI Slot Registration Error Diagnostics (#76)**: Replaced silent/empty `catch` blocks in `lib/client.js` for `sidebar.right.pane.tab`, `conversation.session.header.utilities`, and `betterSidebar` slot registrations with descriptive `console.warn` diagnostic logs. Added explicit fallback intention comments for locale snapshot handling.
+
+### Refactored
+- **Tracker Dead Code Cleanup (#77)**: Removed redundant, test-only `clearHistory` export from `lib/tokens/tracker.js`. History clearing is canonically and safely handled by `reset()`.
+
+### Documentation
+- **Keep a Changelog Standardization (#74)**: Extracted chronological release notes (`## Changed in v...`) from `README.md`, `README.ru.md`, and `README.zh.md` into centralized `CHANGELOG.md`. Consolidated all product feature documentation into comprehensive thematic sections. Included `CHANGELOG.md` in package distribution manifest (`package.json` files list).
+
+## [0.1.18] - 2026-09-17
+
+### Fixed
+- **AI Tool ContentBlock Format (GH #2 / Gitea #71)**: Fixed output formatting across all 5 AI tools (`context_lens_status`, `context_lens_compress_preview`, `context_lens_skeletonize`, `context_lens_track`, `context_lens_clear_focus`). All tools now return structured `ContentBlock[]` arrays (`[{ type: 'text', text: ... }]`) instead of raw JSON strings, preventing session-poisoning `TypeError: content.some is not a function` exceptions in `@deepseek-ai/dsh-llm`.
+- **HTTP Parameter Validation (#70)**: Replaced silent error swallows with explicit 400 Bad Request responses and diagnostic warning logging when parsing malformed URL queries or invalid session parameters.
+
+### Added
+- **In-App One-Click Auto-Updater (#61)**: Added standard updater module (`lib/updater.js`) with `/api/dsh-context-lens/update` endpoint and an in-app update banner with version badge and update button in the settings card.
+
+### Security
+- **HTTP Endpoint Hardening (#62, #63)**: 
+  - `/clear-focus` strictly requires `POST` method (returns 405 on GET) and validates loopback / same-origin trusted source (403 on untrusted).
+  - `/compress-preview` strictly requires `POST`, verifies loopback / same-origin, caps request body at 256KB (413 on exceed), and validates `maxLines` parameter (clamped between 1 and 5000).
+
+### Changed
+- **UI Design System & Theme Alignment (#67, #68)**: Replaced text fallback chevron `▼` with an animated SVG 14x14 icon with smooth 180° rotation. Removed all hardcoded `rgba()` values in favor of DeepSeek Harness `--dsw-alias-*` theme variables.
+- **Settings & Cordis Lifecycle (#64, #66)**: Injected `settingsScope` directly into client plugin dependencies and removed foreign `lanSettings` fallback. Wrapped settings and locale registrations in `ctx.effect` with disposable cleanups.
+- **Code Decomposition (#69)**: Modularized server half into `lib/http.js`, `lib/tools.js`, `lib/updater.js`, and a compact `lib/index.js`.
+- **Repository Hygiene (#65)**: Purged internal agent artifacts (`AGENTS.md`, `index.md`, `docs/plans/`) from tracked git tree and updated `.gitignore`.
+
+## [0.1.17] - 2026-09-15
+
+### Added
+- **Focus Management UI**: Added active session focus path chips (`focus.paths`) and an instant "Clear focus" button in `StatusPanel`.
+- **Configurable Budget Alert Threshold**: Added `budgetAlertPercent` (50–99%, default 90%) to `Config` and the settings card, allowing customizable budget alert levels.
+- **Expanded AST Syntax**: Added pure regex AST skeletonization for C/C++ (`class`, methods, `#include`) and SQL DDL (`CREATE/ALTER TABLE`, `INDEX`).
+
+### Changed
+- **Multi-Language Standard**: Client bundle now strictly contains only canonical English (`en`) and Chinese (`zh`) dictionaries. Russian translations are provided externally via `dsh-russian-lang`.
+
+## [0.1.16] - 2026-09-13
+
+### Added
+- **UI Error Boundary**: Wrapped visual components (`PluginCard`, `LensTab`, `StatusPanel`) in native React error boundaries with retry buttons, preventing parent crashes and React Error 310.
+- **Reactive Settings Synchronization**: Added support for reading settings snapshots via `scope.getSnapshot()` and reactive subscriptions via `scope.subscribe()`.
+
+### Changed
+- **ClineBot Unified Style**: Migrated UI classes to the unified `.cl-*` design system with `--dsw-alias-*` CSS tokens.
+- **Input Validation**: Added defensive input validation across all compression, skeletonization, and tracking functions.
+
+## [0.1.15] - 2026-09-11
+
+### Added
+- **Native DSH Right Sidebar**: Added support for DeepSeek Harness 0.1.5-alpha.1+ native right sidebar via `ctx.sidebarRightTabs` and `sidebar.right.pane.tab` slot.
+
+### Changed
+- **Sidebar Coexistence**: Preserved legacy `dsh-better-sidebar` integration with deterministic, non-conflicting IDs (`@goodandready/dsh-context-lens` vs `dsh-context-lens:tab`) and graceful fallback across all 4 layouts.
+
+## [0.1.14] - 2026-09-09
+
+### Added
+- **AST Multiline Signatures**: Added multiline function and method signature parsing for TypeScript, JavaScript, Rust, and Go.
+- **Reset Tool**: Added `context_lens_reset` tool to reset token tracker statistics and compression history.
+
+### Changed
+- **Adaptive Polling**: Header chip pauses polling on hidden browser tabs (`visibilitychange`) and polls actively (4s) only when the popover is open.
+- **Settings Atomicity**: Added atomic settings patch saving in `PluginCard`.
+
+## [0.1.13] - 2026-09-07
+
+### Fixed
+- **Cordis Proxy Safety**: Guarded optional `betterSidebar` tab registration via `ctx.inject(['betterSidebar'], ...)` instead of direct property access on Cordis context proxy.
+- **Settings Scope Guard**: Protected `_ctx.settingsScope` access in `PluginCard` with try/catch to avoid proxy errors on older hosts.
+
+## [0.1.12] - 2026-09-05
+
+### Changed
+- **Component Refactoring**: Extracted shared `StatusPanel` component reused by `LensTab` and the `HeaderChip` popover.
+
+## [0.1.11] - 2026-09-03
+
+### Fixed
+- **Audit Fixes**: Auto-compress honors configured `compressionMode`, `budgetLimit` halts token accumulation once exceeded, focus state is tracked per-session (`sessionId`), and Python imports are properly retained.
+
+## [0.1.10] - 2026-08-30
+
+### Added
+- **Session Header Chip**: Registered header chip in `conversation.session.header.utilities` (`order: 7`) with interactive dropdown popover showing live token savings, budget progress, and recent operations.
+
+## [0.1.9] - 2026-08-25
+
+### Changed
+- **Compatibility**: Removed obsolete kernel modules from client injects for DSH 0.1.2-rc.1.
+
+## [0.1.8] - 2026-08-20
+
+### Fixed
+- **Tool Arguments**: Supported both `text` and `log` parameter names in `context_lens_compress_log`.
+- **Tracker & Parsing**: Fixed cross-platform path resolution on Windows, dynamic `budgetLimit` propagation, ANSI terminal escape sequence stripping, and Rust `pub async fn` syntax support.

package/README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-<h3>Intelligent AST Code Skeletonizer, Context Token Compressor & Log Condenser for DeepSeek Harness</h3>
+<h3>AST Code Skeletonizer, Terminal Log Condenser & Token Budget Guard for 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>
 
-<!-- Showcase Catalog Button -->
+<!-- Showcase Button -->
 <p align="center">
   <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
 </p>
@@ -36,179 +36,143 @@
 
 ---
 
-## ⚡ Overview
+## ⚡ Overview & The Problem
 
-**`dsh-context-lens`** optimizes the context window and token budget of **DeepSeek Harness** agents.
+Large codebase contexts and verbose build/test logs quickly fill the LLM context window, waste token budget, slow down inference, and cause agent hallucination.
 
-Large context windows are expensive, prone to model distraction, and vulnerable to rate limits. When agents inspect multi-file codebases or run bulky test suites, thousands of tokens are wasted on boilerplate function bodies, passing test logs, and build artifacts. 
-
-`dsh-context-lens` introduces **active path focusing, AST structural code skeletonization (JS/TS/Python/Go/Rust/Java/C/C++/SQL), and fast O(n) heuristic log compression**, shrinking context consumption by **up to 85%** while keeping 100% of essential architectural interfaces and failure traces.
+**`dsh-context-lens`** solves this by providing:
+1. **Active Focus Scoping**: Keeping full fidelity for files currently being edited, while collapsing surrounding workspace files into lightweight AST skeletons.
+2. **Multi-Language AST Skeletonization**: Extracting structural types, classes, and method signatures across TypeScript, JavaScript, Python, Go, C/C++, Rust, and SQL, cutting raw code size by **70–85%**.
+3. **Intelligent Terminal Log Compression**: Stripping noisy passing test lines and build boilerplate while preserving critical error stack traces and failure windows, cutting log size by up to **90%**.
+4. **Session Token Telemetry & Budget Guard**: Live tracking of token savings with configurable budget alerts and visual indicators in the DSH Web UI.
 
 ```mermaid
 graph LR
-    subgraph RawContext [Bulky Workspace & Terminal Streams]
-        Code[📁 Multi-File Codebase: Full Function Bodies] --> LensEngine[dsh-context-lens Compression Engine]
-        Logs[📋 Test & Build Logs: Thousands of Noise Lines] --> LensEngine
+    subgraph RawContext [Raw Context Streams]
+        Code[📁 Source Code: Lengthy Implementation Details] --> LensEngine[dsh-context-lens Engine]
+        Logs[📋 Build/Test Logs: Verbose Success Noise] --> LensEngine
     end
 
-    subgraph LensEngine [Context Lens Processing Pipelines]
-        LensEngine --> Focus{Active Focus Check}
-        Focus -->|Focused Target| RawKeep[Full Implementation Preserved]
-        Focus -->|Surrounding Workspace| AST[AST Skeletonizer: Types, Classes, Signatures]
-        LensEngine --> LogFilter[Heuristic Log Condenser: Stack Traces & Errors]
+    subgraph LensEngine [Context Processing Pipeline]
+        LensEngine --> Focus{Focus Evaluator}
+        Focus -->|Focused File| RawKeep[Full Code Details Retained]
+        Focus -->|Surrounding Workspace| AST[AST Skeletonizer: Signatures & Types]
+        LensEngine --> LogFilter[Log Condenser: Stack Traces & Errors Only]
     end
 
-    subgraph Savings [Token Economy & Agent Reasoning]
-        AST --> Agent[🤖 DSH Agent: Ultra-Compact High-Speed Context]
+    subgraph Output [Optimized Agent Context]
+        AST --> Agent[🤖 DSH Agent Context: Compact High-Value Prompt]
         RawKeep --> Agent
         LogFilter --> Agent
-        Agent --> Tracker[📊 Live Token Budget Savings Tracker]
+        Agent --> Tracker[📊 Live Token Telemetry & Budget 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
 ```
 
 ---
 
-## ✨ Key Capabilities & Modules
+## ✨ Full Feature Breakdown
 
-### 1. 🧬 Multi-Language AST Code Skeletonizer (`lib/ast/skeletonizer.js`)
-* Automatically extracts structural interfaces, function signatures, classes, types, and exports across **TypeScript, JavaScript, Python, Go, Rust, and Java**;
-* Supports `pub async fn`, `async fn`, `pub(crate)` and `pub(super)` in Rust;
-* Retains JSDoc, docstrings, and structural comments preceding definitions;
-* Drops internal function implementations, loops, and repetitive boilerplate while preserving indentation and export declarations;
-* Allows the agent to understand entire multi-package repository architectures without loading tens of thousands of implementation tokens.
+### 1. 🧬 Multi-Language AST Structural Skeletonizer
+* **Supported Languages**: TypeScript, JavaScript, Python, Go, C/C++, Rust, and SQL DDL.
+* **Structural Preservation**: Retains imports, classes, structs, interfaces, exported types, function signatures, and doc comments while discarding inner implementation bodies.
+* **Multiline Signature Support**: Seamlessly accumulates complex multiline generic arguments, return types, and parameter lists up to block delimiters.
+* **Pure Regex Implementation**: Zero heavy native dependencies or binary parser overhead; runs lightning-fast across any platform.
 
-### 2. 🗜️ Fast Heuristic Log Condenser (`lib/compression/log-compressor.js`)
-* High-performance $O(n)$ heuristic line filter for test runners and build tools (Jest, Vitest, Pytest, Go test, NPM, Webpack, Cargo, Maven/Gradle);
-* Strips terminal ANSI escape color sequences before evaluating regex patterns;
-* Automatically filters out passing test noise (`PASS`, `✓`, `ok`) and build notices;
-* Retains critical error lines, stack traces, assertion failures (`Expected ... Received ...`), and failure context windows;
-* 3 Aggressiveness Modes: `raw`, `balanced`, and `aggressive`.
+### 2. 📋 Heuristic Test & Build Log Condenser
+* **Supported Test Runners & Tools**: Jest, Vitest, Pytest, Go test, Cargo, Webpack, Vite, TSC, Maven, Gradle.
+* **Targeted Extraction**: Identifies and preserves critical error messages, stack traces, assertion differences (`Expected ... Received ...`), and failure context windows.
+* **3 Aggressiveness Modes**:
+  - `raw`: Removes simple noise lines while keeping general execution order.
+  - `balanced`: Preserves failure sections with surrounding context windows (default).
+  - `aggressive`: Extracts strictly error lines and stack frames.
+* **ANSI Stripping**: Cleans terminal escape codes and color formatting before processing.
 
 ### 3. 🎯 Active Path Focus Scoping (`context_lens_focus`)
-* Dynamically sets a list of active files or directories currently being edited;
-* Files outside the focus list are automatically presented to the agent as lightweight AST skeletons.
-
-### 4. 📊 Token Savings Tracking & Dashboard (`lib/tokens/tracker.js` & `lib/client.js`)
-* Measures exact token counts before and after compression;
-* Calculates cumulative session token savings and displays live efficiency percentage badges in the DSH interface;
-* Enforces Token Budget Guard limits with alert warnings when exceeding 90% budget.
+* Allows designating specific files or folders as active working targets for the current task.
+* Files inside focus remain uncompressed; non-focused dependencies are automatically served as structural skeletons.
+* Focus state is strictly scoped per session (`sessionId`) and can be inspected or cleared instantly via UI or API.
+
+### 4. 📊 Token Savings Tracking & Budget Telemetry
+* Calculates exact tokens before and after compression using accurate token estimation.
+* Tracks cumulative tokens saved, compression ratio, and session budget percentage.
+* Configurable warning threshold (`budgetAlertPercent`) dynamically alerts when the session budget approaches depletion.
+
+### 5. 🖥️ Visual Surfaces & Dual Sidebar Integration
+Context Lens shares the unified `.cl-*` design language and `--dsw-alias-*` token system with `dsh-clinebot`:
+* **Conversation Header Chip**: Mounted in `conversation.session.header.utilities` (`order: 7`). Always displays efficiency badges (`◐ Lens`, `◐ <N>%`, or `⚠` alert) with an interactive dropdown Popover showing savings details and recent operations.
+* **Dual Sidebar Compatibility**: Supports both native DeepSeek Harness right sidebar (`ctx.sidebarRightTabs` + `sidebar.right.pane.tab` slot) and legacy `dsh-better-sidebar` with non-conflicting IDs.
+* **ErrorBoundary Protection**: Every UI component (`PluginCard`, `LensTab`, `StatusPanel`) is isolated inside React error boundaries with instant retry buttons, preventing parent UI crashes.
+* **One-Click In-App Updater**: Settings card displays live version checks against npm with a single-click update trigger.
 
 ---
 
-## 🛠️ Agent Tools Reference (4 Tools)
+## 🛠️ Agent Tools Reference (5 Tools)
+
+All tools strictly conform to the DeepSeek Harness tool specification by providing `output.render` returning structured `ContentBlock[]` arrays (`[{ type: 'text', text: ... }]`), ensuring 100% session stability with core LLM stream processors.
 
 | Tool Name | Parameters | Description |
 |---|---|---|
-| `context_lens_focus` | `paths: string[]`, `maxDepth?: number` | Designates active focus files/folders; collapses surrounding workspace into AST skeletons |
-| `context_lens_compress_log` | `text: string` *(or `log`)*, `mode?: "raw"\|"balanced"\|"aggressive"`, `maxLines?: number`, `auto?: boolean` | Condenses terminal/test outputs, keeping only stack traces and failure windows |
-| `context_lens_compress_code` | `code: string`, `language?: string`, `maxDepth?: number`, `filePath?: string` | Generates a clean structural AST skeleton from raw source code |
-| `context_lens_stats` | *(none)* | Returns real-time cumulative token savings, history, and budget status |
+| `context_lens_focus` | `paths: string[]`, `sessionId?: string` | Sets active focus files/folders for the session; collapses surrounding workspace into AST skeletons |
+| `context_lens_compress_log` | `text: string` *(or `log`)*, `mode?: "raw"|"balanced"|"aggressive"`, `maxLines?: number`, `auto?: boolean` | Condenses terminal and test outputs, keeping only stack traces and failure windows |
+| `context_lens_compress_code` | `code: string`, `language?: string`, `maxDepth?: number`, `filePath?: string`, `sessionId?: string` | Generates a clean structural AST skeleton from raw source code |
+| `context_lens_track` | `sessionId?: string` | Returns real-time cumulative token savings, history, and budget status for the session |
+| `context_lens_reset` | `sessionId?: string` | Resets token tracker counters and compression history at the start of new tasks |
 
 ---
 
-## 📦 Quick Installation
-
-```bash
-dsh plugin --profile web add @goodandready/dsh-context-lens
-```
+## 🔌 HTTP API Reference
 
-> [!IMPORTANT]
-> Restart DSH Web UI after installation (`systemctl --user restart dsh-web`) to activate context compression tools.
+| Endpoint | Method | Security Checks | Description |
+|---|---|---|---|
+| `/dsh-context-lens/status` | `GET` | Open (safe read) | Returns session token savings stats, active focus paths, and compression history |
+| `/dsh-context-lens/clear-focus` | `POST` | Loopback / Same-Origin | Clears focused paths for the specified session (rejects GET with 405) |
+| `/dsh-context-lens/compress-preview` | `POST` | Loopback / Same-Origin | Preview log compression with 256KB body size limit and `maxLines` clamping (1–5000) |
+| `/api/dsh-context-lens/update` | `GET`, `POST` | Loopback + Security Header | In-app plugin updater checking npm registry and executing safe background updates |
 
 ---
 
 ## ⚙️ Configuration Reference (`settings.yaml`)
 
+Settings can be modified via `settings.yaml` or directly in the DSH Web UI under **Settings → Plugins → Context Lens**.
+
 ```yaml
 dsh-context-lens:
-  compressionMode: balanced        # 'raw', 'balanced', or 'aggressive'
+  compressionMode: balanced        # Log compression mode: 'raw', 'balanced', or 'aggressive'
   astSkeletonMaxDepth: 3          # Maximum depth level for AST signature traversal (1..10)
   tokenSavingsTracking: true      # Track and display live token savings
   autoCompressThreshold: 4000     # Auto-compression character threshold (0 to disable)
   budgetLimit: 100000             # Session token budget limit
-  autoCollapse: true              # Auto-collapse UI when budget is nearly exhausted
+  budgetAlertPercent: 90          # Budget percentage threshold triggering warning badge (50..99)
+  autoCollapse: true              # Display warning in UI when budget is nearly exhausted
 ```
 
----
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `compressionMode` | `string` | `balanced` | Default log compression aggressiveness (`raw`, `balanced`, `aggressive`) |
+| `astSkeletonMaxDepth` | `number` | `3` | Maximum nesting depth for AST signature parsing (1 to 10) |
+| `tokenSavingsTracking` | `boolean` | `true` | Track token savings before/after compression |
+| `autoCompressThreshold` | `number` | `4000` | Auto-compress terminal logs exceeding this character length (0 to disable) |
+| `budgetLimit` | `number` | `100000` | Total token budget limit allocated per session |
+| `budgetAlertPercent` | `number` | `90` | Budget alert threshold percentage triggering warnings (50 to 99) |
+| `autoCollapse` | `boolean` | `true` | Display low-budget warning badge in settings card and header chip |
 
-## 📝 Version History
+---
 
-### v0.1.10
-* **Fix**: Register session header chip in `conversation.session.header.utilities` (`order: 7`).
-* **Fix**: Ensure chip is always visible (`◐ Lens` on initial session, `◐ <N>%` when savings available, `⚠` on low budget).
-* **Feature**: Interactive dropdown Popover on chip click: token savings breakdown, budget progress bar, recent operations, and refresh button.
+## 📦 Quick Installation
 
-### v0.1.9
-* **Fix**: Remove obsolete kernel modules from client injects for DSH 0.1.2-rc.1 compatibility.
+```bash
+dsh plugin --profile web add @goodandready/dsh-context-lens
+```
 
-### v0.1.8
-* **Fix**: Support both `text` and `log` parameter names in `context_lens_compress_log`.
-* **Fix**: Cross-platform path resolution in unit tests on Windows (`fileURLToPath`).
-* **Fix**: Dynamic propagation of `budgetLimit` configuration into token tracker.
-* **Fix**: ANSI terminal escape sequence stripping for colored logs.
-* **Fix**: Expanded Rust syntax support (`pub async fn`, `pub(crate)`) and proper `#` comment prefix for Python.
+> [!TIP]
+> After installation, reload the DSH Web UI or restart the service (`systemctl --user restart dsh-web`) to activate context compression tools.
 
 ---
 
-
-## Changed in v0.1.18
-
-- **Critical Fix (#71, GH #2)**: Conformed `output.render` to DeepSeek Harness core contract by returning `ContentBlock[]` (`[{ type: 'text', text: ... }]`). Prevents irreversible DSH session poisoning caused by `TypeError: content.some is not a function` in `@deepseek-ai/dsh-llm`.
-- **Security & Reliability (#62, #63, #70)**: Hardened HTTP endpoints (`/clear-focus`, `/compress-preview`, `/status`): strictly requires `POST` on write actions, enforces loopback/same-origin trust checks, caps body size to 256KB (413 on exceed), validates `maxLines` (1-5000), and handles malformed session queries with clear 400 responses.
-- **One-Click In-App Updater (#61)**: Added canonical plugin updater module (`lib/updater.js`) with `/api/dsh-context-lens/update` endpoint and an in-app update UI banner with one-click update button in the settings card.
-- **Settings & Lifecycle (#64, #66)**: Injected `settingsScope` directly into client plugin dependencies and removed foreign `lanSettings` fallback. Wrapped settings and locale registrations in `ctx.effect` with disposable cleanups.
-- **UI & Theme Alignment (#67, #68)**: Implemented smooth vector SVG 14x14 chevron with 180° rotation animation and replaced hardcoded colors with `--dsw-alias-*` theme tokens for seamless light/dark mode presentation.
-- **Repository Hygiene (#65)**: Purged internal agent artifacts (`AGENTS.md`, `index.md`, `docs/plans/`) from tracked git tree and added denylist to `.gitignore`.
-
 ## 📄 License
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
-
-## Changed in v0.1.11
-
-Audit fixes (#33–#47, #18):
-
-- Auto-compress no longer forces `balanced`; uses configured `compressionMode`.
-- `budgetLimit` stops token counting after the limit (matches settings description).
-- Focus state is per-session (`sessionId`), not process-global.
-- Settings card exposes `budgetLimit`, `autoCollapse`, `autoCompressThreshold`; low-budget shows a warning instead of force-closing the card.
-- Client `betterSidebar` inject is optional; preview uses server `/dsh-context-lens/compress-preview`.
-- Python imports kept in skeletons; Java locals no longer mistaken for signatures.
-- Shared `estimateTokens` helper; unused `dsh-credentials` peer removed.
-
-## 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)**: Guard optional `betterSidebar` tab registration via `ctx.inject(['betterSidebar'], ...)` instead of direct property access on Cordis context proxy, resolving `cannot get property "betterSidebar" without inject` on client boot.
-- **Fix (#50)**: Safely guard `_ctx.settingsScope` access in `PluginCard` with try/catch to prevent proxy property errors.
-- **Test**: Added regression test suite simulating strict Cordis Context Proxy behavior.
-
-## Changed in v0.1.15
-
-- **Feature (#54)**: Support native DSH right sidebar (`ctx.sidebarRightTabs` + `sidebar.right.pane.tab` slot) introduced in DSH 0.1.5-alpha.1.
-- **Compatibility (#54)**: Preserve legacy `dsh-better-sidebar` integration with deterministic, non-conflicting IDs (`@goodandready/dsh-context-lens` vs `dsh-context-lens:tab`).
-- **Resilience (#54)**: Clean boot and graceful fallback across all 4 layouts (Native only, Legacy only, Both active, Neither active).
-- **Tests (#54)**: Added comprehensive test matrix in `test/sidebar-matrix-54.test.mjs`.
-
-## Changed in v0.1.14
-
-- **Fix (#52)**: Multiline AST signature parsing in `skeletonizer.js` for TypeScript, JavaScript, Rust, and Go with complex parameter types and return annotations.
-- **Feature (#52)**: Registered `context_lens_reset` tool to allow resetting tracker statistics and history at the start of new tasks.
-- **Quality & UX (#52)**: Dynamic RU/EN locale detection in `HeaderChip`, `LensTab`, and `StatusPanel` via `ctx.locale` for seamless UI integration.
-- **Perf & Stability (#52)**: Adaptive polling in `HeaderChip` pausing on hidden tabs (`visibilitychange`) and polling actively (4s) only when popover is open.
-- **Reliability (#52)**: Atomic settings save (`scope.patch` / `scope.setAll`) in `PluginCard` with graceful fallback.
-
-### UI & Styling System (v0.1.16+)
-
-Context Lens shares its visual language and component architecture with `dsh-clinebot`:
-- **Native Design System**: 100% theme integration using `--dsw-alias-*` tokens.
-- **Resilient UI Surfaces**: Every component (`PluginCard`, `LensTab`, `StatusPanel`) is protected by an `ErrorBoundary` with instant retry capability.
-- **Reactive Settings**: Live updates via `scope.subscribe()` and zero-delay reads via `scope.getSnapshot()`.
-- **Adaptive Telemetry**: Popover and tab display metric cards for tokens saved, percentage reduced, and live budget utilization.

package/README.ru.md

@@ -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,168 +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`) для активации инструментов контекста.
 
 ---
 
-
-## Изменения в v0.1.18
-
-- **Критическое исправление (#71, GH #2)**: Приведение контракта `output.render` к стандарту ядра DeepSeek Harness: теперь возвращается массив `ContentBlock[]` (`[{ type: 'text', text: ... }]`). Полностью устранено необратимое повреждение сессий DSH с ошибкой `TypeError: content.some is not a function` в модуле `@deepseek-ai/dsh-llm`.
-- **Безопасность и отказоустойчивость HTTP (#62, #63, #70)**: Защита маршрутов (`/clear-focus`, `/compress-preview`, `/status`): проверка метода (`POST` для изменений), верификация loopback и same-origin, ограничение размера тела запроса до 256 КБ (код 413 при превышении), клампинг `maxLines` (1–5000), возврат 400 Bad Request при невалидном идентификаторе сессии.
-- **One-Click автообновление плагина (#61)**: Внедрен стандартный модуль автообновления `lib/updater.js`, endpoint `/api/dsh-context-lens/update` и блок проверки/установки обновления в карточке настроек.
-- **Сервис настроек и жизненный цикл (#64, #66)**: Клиентский плагин объявляет зависимость `settingsScope`, убрана привязка к чужому сервису `lanSettings`. Регистрации настроек и локали обёрнуты в `ctx.effect` с корректными уборщиками.
-- **Визуальная часть UI и темы (#67, #68)**: Запасной шеврон заменён на векторный SVG 14x14 с плавной анимацией поворота на 180°. Исключены захардкоженные цвета `rgba()`, интерфейс переведён на токены `--dsw-alias-*`.
-- **Санитайзинг репозитория (#65)**: Из отслеживаемого дерева исключены внутренние файлы (`AGENTS.md`, `index.md`, `docs/plans/`), обновлён `.gitignore`.
-
 ## 📄 Лицензия
 
 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

@@ -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,24 +74,105 @@ 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`) 以激活上下文压缩工具。
+
 ---
 
 ## 📄 开源协议
 
 MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
-
-
-## v0.1.18 更新日志
-
-- **严重问题修复 (#71, GH #2)**：严格遵循 DeepSeek Harness 核心工具返回规范，将 `output.render` 调整为返回 `ContentBlock[]` 数组 (`[{ type: 'text', text: ... }]`)。彻底解决第三方工具调用后会话写入非数组导致 `@deepseek-ai/dsh-llm` 报错 `TypeError: content.some is not a function` 并永久损坏会话的严重缺陷。
-- **安全性与稳定性加固 (#62, #63, #70)**：全面加固 HTTP 接口 (`/clear-focus`, `/compress-preview`, `/status`)：写操作严格要求 `POST` 请求，校验环回与同源请求来源，限制请求体上限为 256KB（超限返回 413），限制 `maxLines` 范围为 1–5000，无效 session 参数返回规范 400 错误。
-- **一键在线更新支持 (#61)**：引入标准更新管理模块 (`lib/updater.js`) 及 `/api/dsh-context-lens/update` 接口，在设置卡片中增加版本检查与一键更新按钮。
-- **设置域与生命周期规范 (#64, #66)**：客户端显式声明 `settingsScope` 依赖并移除对外部 `lanSettings` 的隐式依赖，将设置注册与多语言注册统一纳入 `ctx.effect` 生命周期清理管理。
-- **UI 与主题深度适配 (#67, #68)**：将折叠箭头升级为 14x14 矢量 SVG 并支持平滑 180° 旋转动画，全面替换硬编码色值，使用 `--dsw-alias-*` 主题变量完美适配明暗主题。
-- **仓库代码纯净性 (#65)**：从 Git 跟踪树中彻底剥离内部计划文件 (`AGENTS.md`, `index.md`, `docs/plans/`)，并更新 `.gitignore` 防护清单。

package/lib/client.js

@@ -319,7 +319,9 @@ window.__ModuleLoader__.load({
           const snap = ctx.locale.getSnapshot();
           if (snap && snap.active && snap.active.startsWith('zh')) return zh;
         }
-      } catch (err) { void err; }
+      } catch (err) {
+        /* intentional fallback: default to english on snapshot error */
+      }
       return en;
     }
 
@@ -653,7 +655,9 @@ window.__ModuleLoader__.load({
             unsub = scope.subscribe(() => {
               if (!cancelled) loadSnap();
             });
-          } catch (_err) { void _err; }
+          } catch (_err) {
+            console.warn('[dsh-context-lens] scope subscribe failed', _err && _err.message || _err);
+          }
         }
 
         return () => {
@@ -1052,17 +1056,28 @@ window.__ModuleLoader__.load({
                     const ok = ctx.slots.inject("sidebar.right.pane.tab", registerPaneTab);
                     if (!ok) console.warn("[dsh-context-lens] sidebar.right.pane.tab inject returned false");
                   } catch (e) {
-                    try { registerPaneTab(); } catch (e2) {}
+                    console.warn("[dsh-context-lens] sidebar.right.pane.tab inject failed, falling back to direct register", e && e.message || e);
+                    try {
+                      registerPaneTab();
+                    } catch (e2) {
+                      console.warn("[dsh-context-lens] registerPaneTab direct register fallback failed", e2 && e2.message || e2);
+                    }
                   }
                 } else {
-                  try { registerPaneTab(); } catch (err) { void err; }
+                  try {
+                    registerPaneTab();
+                  } catch (err) {
+                    console.warn("[dsh-context-lens] registerPaneTab direct register failed", err && err.message || err);
+                  }
                 }
               }
             } catch (e) {
               console.warn("[dsh-context-lens] native sidebar registration failed", e && e.message || e);
             }
           });
-        } catch (err) { void err; }
+        } catch (err) {
+          console.warn("[dsh-context-lens] native sidebar inject failed", err && err.message || err);
+        }
       }
 
       if (typeof ctx.inject === 'function') {
@@ -1087,7 +1102,9 @@ window.__ModuleLoader__.load({
               console.warn('[dsh-context-lens] betterSidebar registerTab failed', e && e.message || e);
             }
           });
-        } catch (err) { void err; }
+        } catch (err) {
+          console.warn('[dsh-context-lens] betterSidebar inject failed', err && err.message || err);
+        }
       }
 
       if (ctx.slots) {
@@ -1107,11 +1124,19 @@ window.__ModuleLoader__.load({
           try {
             ctx.slots.inject('conversation.session.header.utilities', headerChipRegister);
           } catch (e) {
-            console.warn('[dsh-context-lens] utilities inject failed', e && e.message || e);
-            try { headerChipRegister(); } catch (e2) {}
+            console.warn('[dsh-context-lens] utilities inject failed, falling back to direct register', e && e.message || e);
+            try {
+              headerChipRegister();
+            } catch (e2) {
+              console.warn('[dsh-context-lens] headerChipRegister fallback failed', e2 && e2.message || e2);
+            }
           }
         } else {
-          try { headerChipRegister(); } catch (err) { void err; }
+          try {
+            headerChipRegister();
+          } catch (err) {
+            console.warn('[dsh-context-lens] headerChipRegister direct register failed', err && err.message || err);
+          }
         }
       }
     };

package/lib/tokens/tracker.js

@@ -81,10 +81,6 @@ export function getHistory() {
   return [...history];
 }
 
-export function clearHistory() {
-  history.length = 0;
-}
-
 export function reset() {
   totalOriginal = 0;
   totalCompressed = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-context-lens",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "DSH plugin for AST context compression, test log filtering, and token budget guard",
   "type": "module",
   "main": "lib/index.js",
@@ -16,7 +16,8 @@
     "README.md",
     "README.zh.md",
     "README.ru.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs"