科学智能层

lean-ctx 超越了模式匹配。六种来自信息论、图论和统计力学的算法协同工作，自动决定保留什么、删除什么、以及如何排列--全部自动化，完全本地运行，无需配置。

这些算法驱动自主智能层。它们在每次 ctx_read、ctx_preload 和 ctx_overview 调用时激活--您无需直接调用它们。

各层如何协同工作

预测惊奇度评分

传统压缩过滤器使用原始字符的 Shannon 熵，将 aaaa 和 import 视为同等可预测。预测惊奇度改为测量相对于 BPE token 频率的交叉熵--衡量每行对 LLM 分词器的惊奇程度。

工作原理

1. 使用 o200k_base（GPT-4o / Claude 分词器）对每行进行分词。
2. 对每个 token，基于排名的 Zipf 先验估计预期频率。
3. 计算交叉熵：包含常见 token 的行（样板代码）得分低；包含罕见 token 的行（复杂逻辑）得分高。
4. 低于惊奇度阈值的行在激进压缩中成为移除候选。

示例

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

为什么重要

与字符级熵相比，预测惊奇度额外移除 15–30% 的样板代码，同时保留复杂逻辑。它直接建模 LLM 认为"有信息量"的内容，因为它使用相同的 BPE 词汇表。

谱相关性传播

当您要求 lean-ctx 为某个任务预加载上下文时，它需要决定哪些文件重要。简单的关键词匹配只能找到提及搜索词的文件。谱相关性能找到与相关文件在结构上相连的文件--即使它们没有共同的关键词。

工作原理

两种图算法在项目的依赖图上运行：

1. 热扩散 - 与任务描述匹配的种子文件获得初始"热量"。热量沿导入边以指数衰减传播，模拟信息在代码库中的流动。
2. PageRank 中心性 - 被许多其他文件导入的文件获得更高的中心性分数。这可以识别结构枢纽（例如，被 20 个模块导入的 db.ts）。

最终相关性分数综合两者：0.7 × heat + 0.3 × pagerank。低于阈值的文件不会被预加载。

示例

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

零配置

依赖图在首次使用时通过 load_or_build() 自动构建。无需 ctx_graph build--开箱即用。

Boltzmann 上下文分配

当谱相关性选出相关文件后，每个文件需要分配 token 预算。简单的方法是平均分配或按相关性排序。Boltzmann 分配使用统计力学来最优分配 token。

工作原理

1. 每个文件都有一个来自谱相关性的相关性分数 E_i。
2. 温度参数 β 由任务推导得出：具体任务（"修复 login.ts 中的认证 bug"）产生低温（将预算集中分配给顶部文件）；宽泛任务（"重构代码库"）产生高温（均匀分配）。
3. token 预算遵循 Boltzmann 分布： budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. 强制执行最小和最大预算限制（每文件 128–4096 个 token），并根据分配的预算选择压缩模式（full、map、signatures）。

示例

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

语义分块与注意力桥接

LLM 存在"中间遗失"问题：上下文开头和结尾的信息比中间内容获得更多注意力。语义分块重新组织输出以最小化信息损失。

工作原理

1. 分块检测 - 源代码行根据 AST 边界启发式算法分组为语义块（函数、类型、导入、松散逻辑）。
2. 相关性排序 - 与当前任务匹配的块被提升到顶部（高注意力位置）。其余块按类型优先级排序。
3. 注意力桥接 - 在块之间，lean-ctx 插入最小化的桥接标记（---），以便 LLM 识别结构边界。
4. 尾部锚点 - 最高优先级块的最后 2–3 行在输出末尾重复，利用近因偏差来强调关键信息。

示例

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

MMR 去重

当多个文件加载到上下文中时，它们通常包含重复的导入、共享的样板代码或非常相似的代码模式。最大边际相关性（MMR）在保留唯一信息的同时移除这些冗余。

工作原理

1. 对每一行，计算与所有已选行（"覆盖集"）的 bigram Jaccard 相似度。
2. MMR 分数在相关性和冗余之间取得平衡： MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. MMR < 0 的行被抑制--它们增加的冗余多于信息。λ 参数默认为 0.7（倾向于相关性而非多样性）。

影响

在典型的多文件预加载中，MMR 移除 10–28% 的冗余内容--主要是共享的导入和重复的工具函数模式。

BPE 对齐 token 优化

在所有内容被选择和排序之后，最终阶段会针对 LLM 的 BPE 分词器优化原始文本。微小的格式调整可以在不改变语义的情况下显著减少 token 数量。

优化规则

工作原理

每条规则是一个简单的字符串替换，在所有其他压缩阶段之后逐行应用。规则源自 BPE token 边界分析--它们针对分词器为语义等价文本产生过多 token 的模式。

影响

BPE 优化通常在已压缩的输出上额外节省 3–8% 的 token。这些节省在多个文件之间累积，对冗长的语言（TypeScript、Java、C#）效果最为显著。

验证效果

在项目中运行 lean-ctx benchmark run 以衡量所有六种算法的综合效果。基准报告显示每个文件的 token 节省、保留度评分（AST、标识符、行数）和整体压缩率。

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

结构化意图识别

lean-ctx将每个交互分类为StructuredIntent--一种基于槽位的表示，包含任务类型、置信度、目标文件、范围、语言提示、紧急程度和动作动词。这驱动所有下游决策：使用哪种压缩模式、如何路由上下文以及优先处理什么。

识别9种任务类型：Explore、Generate、FixBug、Refactor、Test、Review、Config、Deploy和Document。每种类型触发不同的压缩策略和上下文路由。

IntentScope从SingleFile到MultiFile、CrossModule再到ProjectWide--决定上下文收集的广度。

工作原理

压缩按意图自适应：FixBug任务通过信息瓶颈过滤器优先处理错误行和测试文件，Explore任务使用轻量清理保留结构，Generate任务聚焦于签名和类型。

ctx_read的自动模式选择器使用当前任务类型优化决策--为大文件的错误修复选择task模式，为探索选择map模式，为文档任务选择signatures模式。

示例

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

上下文管道架构

上下文管道通过六个不同层处理信息：Input → Intent → Relevance → Compression → Translation → Delivery。每层有定义的契约（输入/输出类型）并输出指标。

工作原理

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

每层指标跟踪输入token、输出token、压缩率和处理时间。在整个会话中汇总后，揭示最大节省发生在哪里以及哪些层是瓶颈。

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

上下文账本与压力管理

ContextLedger跟踪发送给AI的每个文件：路径、压缩模式、原始token、发送token和时间戳。实时计算上下文窗口利用率和压力。

工作原理

三个压力级别：None（利用率低于70%）、Compress（70-90%）和Evict（超过90%）。在每个级别，系统采取不同操作--降级相关性较低文件的压缩模式或建议驱逐。

示例

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

上下文缺陷检测识别缺失信息：如果修复错误任务针对auth.rs但未加载测试文件，系统建议tests/auth_test.rs。对于配置任务，推荐Cargo.toml、.env或Dockerfile。

智能重注入生成计划，通过降级非目标文件（如从full模式切换到signatures模式）释放上下文预算，同时保护对当前意图至关重要的文件。

多代理智能

当多个AI代理协作时（如编码者和审查者），lean-ctx提供结构化交接、基于角色的上下文深度和跨代理知识共享。

工作原理

HandoffPackage将当前会话账本、结构化意图和上下文快照打包成一个可转移单元--让接收代理以完整的情境意识开始，而不是从空白开始。

识别七种代理角色：Coder、Reviewer、Planner、Explorer、Debugger、Tester和Orchestrator。每个角色获得定制的ContextDepthConfig--编码者获得更多完整文件读取，审查者获得更多签名，探索者获得更广泛的图上下文。

示例

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

跨代理知识共享允许代理通过共享便签本交换结构化事实（如"discovery:auth_bug=第42行缺少空检查"）。新代理继承相关知识，无需重新发现。

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

另请参阅

• 自主智能工具--使用这些算法的工具
• tree-sitter 引擎--支持 18 种语言的 AST 解析
• 配置--调整阈值和自主性设置
• 基准测试--衡量您的节省