⚡ dsh-context-economy
Slash token costs for agent code reading via pointer & topology indexing
Pointer-Based Lazy Reading • PageRank File Topology • Byte-Level Slices • 80–93% Token Savings
Features • Quick Start • DSH Power Suite • Tools • 简体中文
💡 Why dsh-context-economy?
LLM context windows are finite and expensive. Dumping entire 2,000-line source files into prompts exhausts token budgets and severely degrades the model's reasoning capabilities.
dsh-context-economy provides an ultra-compact code reading layer:
- 💰 80–93% Output Token Reduction: Queries return minimal
path:line pointers with brief context; oversized matches spill cleanly to disk.
- 🌐 PageRank Dependency Topology: Analyzes project imports (adapted from Aider's repomap algorithm) to prioritize central, high-frequency hub files (
hotspots).
- 🔬 Byte-Level Window Slicing (
project_slice_read): Reads specific byte windows with regex find and tail tracking — built for huge single-line JS bundles and deep JSON.
- 📊 Persistent Savings Accounting (
project_savings): Automatically tracks token savings per turn against naive full-read baselines.
🚀 Quick Start
Installation
# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-context-economy
Typical Usage Flow
- Find symbols with PageRank:
project_symbols_find query="AuthHandler" ranking=true
- Inspect dependency hotspots:
project_imports direction="hotspots"
- Query accumulated token savings:
project_savings
🧩 DSH Power Suite
This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:
graph LR
M["🧠 <b>dsh-local-memory</b><br/><i>1. Remember rules & prefs</i>"]
--> E["⚡ <b>dsh-context-economy</b><br/><i>2. Save 80%+ tokens reading code</i>"]
--> A["🛡️ <b>dsh-evidence</b><br/><i>3. Tamper-proof audit receipts</i>"]
--> S["🔍 <b>dsh-session-index</b><br/><i>4. CJK search & bookmarks</i>"]
--> M
style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px;
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px;
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px;
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px;
| Plugin | Role in Suite | Synergy with Context Economy |
|---|
| ⚡ dsh-context-economy | Context Economy (Current) | Provides index-backed pointer reading and topology to slash token expenditure. |
| 🧠 dsh-local-memory | Memory Layer | Frees up prompt tokens, leaving abundant budget for persistent memory snapshots. |
| 🛡️ dsh-evidence | Audit & Receipts | Benchmark runs (savings-bench) generate verifiable evidence bundles registered into Evidence. |
| 🔍 dsh-session-index | Session Search | Compact pointer output generates 80%+ smaller session logs, reducing search index load. |
📖 Deep Dive & Reference
🛠️ Available Tools (8 Tools)
| Tool | Description |
|---|
project_index_status | View index stats, heal history, and manually refresh working-tree reconciliation. |
project_symbols_find | Locate symbols by name/substring with optional PageRank ordering. |
project_imports | Inspect in/out import edges, top-k hotspots, and orphans. |
project_files | Cached fast glob listing relative project paths. |
project_slice_read | Precision byte slicing with window / tail modes and ReDoS-protected regex find. |
project_json_read | Bounded streaming scan of top-level JSON keys without full JSON.parse memory spikes. |
project_cost_probe | Single-shot comparison probe between tool output and naive full-file reading. |
project_savings | Query accumulated token savings ledger (grouped by tool/root with trend analysis). |
🏗️ Architecture & Self-Healing
- Incremental Self-Healing Index: Tracks
mtime + size to re-scan only modified files on demand without persistent daemon threads.
- Top-Level JSON Scanner: 64KB chunk-based depth scanner preventing OOM on massive configuration files.
- PageRank Algorithm: Power-iteration algorithm with $\alpha=0.85$ and strict convergence tolerances.
🧪 Building & Testing
npm run typecheck
npm run check:dsh-contract
npm test
npm run pack:check
