math-skill 3.0.1 → 3.1.0

package/README.en-US.md

@@ -18,19 +18,21 @@
 
 ## Inspiration
 
-The story of Sophus Lie forging a "dragon-slaying blade" tells us this: the Lie group–Lie algebra machinery invented to solve differential equations ended up becoming the lingua franca for describing symmetry and robot state estimation — the value of a mathematical tool far outlives its original intent, which is exactly the prototype of "cross-domain activation." See [`references/inspiration.md`](references/inspiration.md).
+The story of Sophus Lie forging a "dragon-slaying blade" tells us this: the Lie group–Lie algebra machinery invented to solve differential equations ended up becoming the lingua franca for describing symmetry and robot state estimation — the value of a mathematical tool far outlives its original intent, which is exactly the prototype of "cross-domain activation." See [`references/inspiration.en.md`](references/inspiration.en.md).
 
 > The most fascinating thing about mathematics: a tool invented for one problem reveals unforeseen power in an entirely different domain.
 
 ---
 
+> Math Skill does not store mathematics. It activates, routes, and translates mathematics for AI research.
+
 ## Philosophy
 
 When you face an AI research problem, this system helps you answer four questions:
 
 1. **What mathematical perspective should I use?** → Thinking Lenses
-2. **What specific math do I need?** → Knowledge Base
-3. **How do I turn math into model design?** → Design Translation
+2. **Which mathematical structures to activate?** → Activation Anchors / Temporary Knowledge Cards
+3. **How do I turn math into model design?** → Design Translation Prototypes
 4. **Is it mathematically sound and engineering-feasible?** → Critic
 
 ```
@@ -38,7 +40,7 @@ Problem
  ↓
 Thinking Lenses: What perspective fits this problem?
  ↓
-Math Knowledge: What specific tools does this perspective need?
+Activation Anchors: Which math structures to activate? Enter Knowledge Gap Protocol if insufficient
  ↓
 Design Translation: How do these tools become model structures / losses / operators?
  ↓
@@ -52,35 +54,35 @@ Critic: Mathematically sound? Engineering-feasible?
 | Layer | Role | Directory | Files |
 |-------|------|-----------|-------|
 | **Thinking Lenses** | Diagnose problem structure, recommend math perspectives | `lenses/*.md` | 15 |
-| **Math Knowledge** | Provide concrete math tools (definitions/theorems/formulas) | `knowledge-base/*/*.md` | 31 |
+| **Activation Anchors** | Activate high-frequency math structures; trigger Knowledge Gap Protocol when insufficient | `knowledge-base/*/*.md` | 31 |
 | **Design Translation** | Bridge math to AI modules/losses/operators | `design-patterns/*/*.md` | 22 |
 
 Supporting layers:
 - `references/books/*.md`: 7 book distillations for deep context
-- `references/gpu-friendly-math.md`: GPU 8-dimension acceptance gate
-- `agents/math-critic.md`: Math-engineering dual critic
+- `references/gpu-friendly-math.en.md`: GPU 8-dimension acceptance gate
+- `agents/math-critic.en.md`: Math-engineering dual critic
 
 ### 15 Thinking Lenses
 
 | Lens | File | Core Perspective |
 |------|------|-----------------|
-| Axiomatization | `lenses/axiomatization.md` | Audit assumptions for consistency/independence/completeness |
-| Duality | `lenses/duality.md` | Transform to dual space to expose constraints and invariants |
-| Symmetry | `lenses/symmetry.md` | Invariants and conservation laws under transformations |
-| Spectral | `lenses/spectral.md` | Eigenvalues/singular values reveal dominant structure |
-| Geometric | `lenses/geometric.md` | Metric/curvature/manifold spatial structure |
-| Projection | `lenses/projection.md` | Orthogonal decomposition, subspace separation, conflict elimination |
-| Variational | `lenses/variational.md` | Constrained extrema, energy minimization |
-| Local-to-Global | `lenses/local-to-global.md` | Assemble local properties into global structure |
-| Topological | `lenses/topological.md` | Continuous-deformation invariants, connectivity, holes |
-| Categorical | `lenses/categorical.md` | Universal properties, functors, natural transformations |
-| Perturbation | `lenses/perturbation.md` | Propagation of small perturbations, stability, robustness |
-| Causal | `lenses/causal.md` | Correlation ≠ causation, interventions, counterfactuals |
-| Game | `lenses/game.md` | Multi-agent strategic interaction, equilibrium, mechanism design |
-| Probabilistic | `lenses/probabilistic.md` | Quantify uncertainty, Bayesian updating |
-| Algorithmic | `lenses/algorithmic.md` | Complexity, feasibility, parallelism |
-
-### Knowledge Base (by math domain)
+| Axiomatization | `lenses/axiomatization.en.md` | Audit assumptions for consistency/independence/completeness |
+| Duality | `lenses/duality.en.md` | Transform to dual space to expose constraints and invariants |
+| Symmetry | `lenses/symmetry.en.md` | Invariants and conservation laws under transformations |
+| Spectral | `lenses/spectral.en.md` | Eigenvalues/singular values reveal dominant structure |
+| Geometric | `lenses/geometric.en.md` | Metric/curvature/manifold spatial structure |
+| Projection | `lenses/projection.en.md` | Orthogonal decomposition, subspace separation, conflict elimination |
+| Variational | `lenses/variational.en.md` | Constrained extrema, energy minimization |
+| Local-to-Global | `lenses/local-to-global.en.md` | Assemble local properties into global structure |
+| Topological | `lenses/topological.en.md` | Continuous-deformation invariants, connectivity, holes |
+| Categorical | `lenses/categorical.en.md` | Universal properties, functors, natural transformations |
+| Perturbation | `lenses/perturbation.en.md` | Propagation of small perturbations, stability, robustness |
+| Causal | `lenses/causal.en.md` | Correlation ≠ causation, interventions, counterfactuals |
+| Game | `lenses/game.en.md` | Multi-agent strategic interaction, equilibrium, mechanism design |
+| Probabilistic | `lenses/probabilistic.en.md` | Quantify uncertainty, Bayesian updating |
+| Algorithmic | `lenses/algorithmic.en.md` | Complexity, feasibility, parallelism |
+
+### Activation Anchors (by math domain)
 
 | Domain | Cards |
 |--------|-------|
@@ -196,11 +198,11 @@ math-skill/
 │   └── compression/                # Compression (4 patterns)
 ├── references/                     # Reference layer
 │   ├── books/                      # 7 book distillations
-│   ├── gpu-friendly-math.md        # GPU 8-dimension gate
-│   ├── agentic-workflow.md         # Collaboration style
-│   └── inspiration.md              # Inspiration
-├── agents/math-critic.md           # Math-engineering dual critic
-├── commands/ask.md                 # /ask manual entry
+│   ├── gpu-friendly-math.en.md     # GPU 8-dimension gate
+│   ├── agentic-workflow.en.md      # Collaboration style
+│   └── inspiration.en.md           # Inspiration
+├── agents/math-critic.en.md           # Math-engineering dual critic
+├── commands/ask.en.md                 # /ask manual entry
 ├── math_book/                      # Local PDFs (not published)
 └── README.md / LICENSE
 ```
@@ -225,9 +227,19 @@ Distillation files ship with the npm package. For full-fidelity lookups, place P
 
 ## Changelog
 
+### v3.1.0 — Activation Anchors & Knowledge Gap Protocol
+
+**Repositioning**: from "math knowledge base" to "math activation system" — the knowledge base is not a closed encyclopedia but a collection of activation anchors.
+
+- **Core Principle**: Math Skill does not store mathematics; it activates, routes, and translates mathematics for AI research
+- **Knowledge Gap Protocol**: 6-step procedure for generating temporary knowledge cards when existing anchors don't cover the problem (gap identification → lens fallback → candidate localization → temporary card → design translation → upgrade recommendation)
+- **Domain Extension Indexes**: each of the 7 math domains gains an `index.md` with trigger signals, extended concepts, reference directions, and temporary activation rules
+- **Knowledge Card Repositioning**: every card gains "Routing Extensions" and "Extensible Directions" sections, transforming endpoints into routing nodes
+- **Design Pattern Positioning**: new `design-patterns/overview.en.md` declares the library as a math→AI translation prototype collection
+
 ### v3.0.1 — Token Optimization & Bilingual Completion
 
-- **Emoji cleanup**: removed all emoji characters from skill files; GPU rating markers ✅⚠️❌ replaced with text `[v]`/`[~]`/`[x]`, saving ~1,400 tokens
+- **Emoji cleanup**: removed all emoji characters from skill files; GPU rating markers replaced with text `[v]`/`[~]`/`[x]`, saving ~1,400 tokens
 - **English distillation files**: added EN translations for all 7 book distillation notes (`references/books/*.en.md`) and `commands/ask.en.md`
 - **Mixed-language routing**: added 5-rule decision system for code-switched input (technical terms excluded from language detection; sentence frame determines primary language)
 - **GPU dimension abbreviations**: verbose labels `**Dimension N full-name**` compressed to `**DN**` (D1-D8), defined in `gpu-friendly-math.md`, saving ~800-1,000 tokens

package/README.md

@@ -24,13 +24,15 @@ Sophus Lie 打造"屠龙刀"的故事告诉我们：为解微分方程发明的
 
 ---
 
+> Math Skill 不存储数学，它激活数学、路由数学，并把数学翻译成 AI 研究设计。
+
 ## 核心理念
 
 当你面对一个 AI 研究问题时，这个系统帮你回答四个问题：
 
 1. **该用什么数学思想看？** → 思想透镜
-2. **需要查什么具体数学知识？** → 知识库
-3. **怎么把数学变成模型设计？** → 设计翻译层
+2. **应该激活哪些数学结构？** → 激活锚点 / 临时知识卡
+3. **怎么把数学变成模型设计？** → 设计翻译原型
 4. **这个设计是否数学上靠谱、工程上可行？** → 批判器
 
 ```
@@ -38,7 +40,7 @@ Sophus Lie 打造"屠龙刀"的故事告诉我们：为解微分方程发明的
  ↓
 思想透镜：这个问题该用什么视角看？
  ↓
-数学知识：这个视角需要哪些具体数学工具？
+激活锚点：应该激活哪些数学结构？不足时进入知识缺口协议
  ↓
 设计翻译：这些工具怎么变成模型结构 / loss / 算子？
  ↓
@@ -52,7 +54,7 @@ Sophus Lie 打造"屠龙刀"的故事告诉我们：为解微分方程发明的
 | 层 | 职责 | 目录 | 文件数 |
 |----|------|------|--------|
 | **思想透镜** | 诊断问题结构，推荐数学视角 | `lenses/*.md` | 15 |
-| **数学知识** | 提供具体数学工具（定义/定理/公式） | `knowledge-base/*/*.md` | 31 |
+| **激活锚点** | 激活高频数学结构，不足时触发知识缺口协议 | `knowledge-base/*/*.md` | 31 |
 | **设计翻译** | 把数学变成 AI 模块/loss/算子 | `design-patterns/*/*.md` | 22 |
 
 辅助层：
@@ -80,7 +82,7 @@ Sophus Lie 打造"屠龙刀"的故事告诉我们：为解微分方程发明的
 | 概率统计 | `lenses/probabilistic.md` | 量化不确定性、贝叶斯更新 |
 | 算法 | `lenses/algorithmic.md` | 复杂度、可行性、并行性 |
 
-### 知识库（按数学领域）
+### 激活锚点（按数学领域）
 
 | 领域 | 知识卡片 |
 |------|---------|
@@ -225,9 +227,19 @@ math-skill/
 
 ## 变更日志
 
+### v3.1.0 — 激活锚点与知识缺口协议
+
+**定位升级**：从"数学知识库"转为"数学激活系统"——知识库不是封闭百科，而是激活锚点集合。
+
+- **核心原则**：Math Skill 不存储数学，它激活数学、路由数学，并把数学翻译成 AI 研究设计
+- **知识缺口协议**：当现有锚点不覆盖时，6 步流程生成临时知识卡（缺口识别→透镜回退→候选定位→临时知识卡→设计翻译→升级建议）
+- **领域扩展索引**：7 个数学领域各增 `index.md`，列出触发信号、扩展概念、参考书方向、临时激活规则
+- **知识卡片重定位**：每张卡片增加"路由扩展"和"可扩展方向"，从终点变为路由节点
+- **设计模式定位**：新增 `design-patterns/overview.md`，声明为 math→AI 翻译原型集合
+
 ### v3.0.1 — Token 优化与双语补全
 
-- **Emoji 清理**：移除所有 skill 文件中的 emoji 符号，GPU 评级标记 ✅⚠️❌ 替换为文本 `[v]`/`[~]`/`[x]`，节约 ~1,400 tokens
+- **Emoji 清理**：移除所有 skill 文件中的 emoji 符号，GPU 评级标记替换为文本 `[v]`/`[~]`/`[x]`，节约 ~1,400 tokens
 - **英文蒸馏稿补全**：7 本书蒸馏稿新增英文翻译（`references/books/*.en.md`），`commands/ask.en.md` 新增英文入口
 - **混合语言路由**：新增 5 条判定规则，解决中英混杂输入的路由问题（技术词不计入语言判定，按句式主框架判定）
 - **GPU 维度缩写**：八维标签从 `**维度 N 全称**` 压缩为 `**DN**`（D1-D8），定义于 `gpu-friendly-math.md`，额外节约 ~800-1,000 tokens

package/agents/math-critic.en.md

@@ -92,7 +92,7 @@ The first 15 dimensions cover the core review angles — assumptions, logic, mod
 - Does the problem belong to the NP-hard or undecidable class? Are approximation or heuristics needed?
 - Do the numerical methods converge? Is the precision sufficient?
 
-### 11. Information Structure Review -> probabilistic lens + `knowledge-base/probability/`
+### 11. Information Structure Review -> probabilistic lens + `../knowledge-base/probability/`
 
 - Is the information structure of the problem clear? Is there redundant or missing information?
 - Can uncertainty be quantified using information entropy, mutual information, etc.?
@@ -132,22 +132,22 @@ The first 15 dimensions cover the core review angles — assumptions, logic, mod
 - Were multiple candidate structures enumerated (rather than only one)?
 - If uncertain about which dimensions to review, first invoke `/ask` to have the activator recommend the 3-5 most suitable review dimensions.
 
-### 17. GPU-Feasibility Review -> `references/gpu-friendly-math.en.md`
+### 17. GPU-Feasibility Review -> `../references/gpu-friendly-math.en.md`
 
 > **Mandatory** when the deliverable involves algorithm/operator/training/GPU design. Corresponds to the second gate of the "dual-acceptance gate."
 
-- Does the deliverable pass the **eight dimensions** of `references/gpu-friendly-math.en.md`? Tensorization / GEMM-mappability / Complexity (sub-quadratic) / Memory & KV-Cache / Low-precision stability / Parallelism & Communication / Sparse structure / Operator fusion -- rate each as "friendly / retrofittable / unfriendly."
+- Does the deliverable pass the **eight dimensions** of `../references/gpu-friendly-math.en.md`? Tensorization / GEMM-mappability / Complexity (sub-quadratic) / Memory & KV-Cache / Low-precision stability / Parallelism & Communication / Sparse structure / Operator fusion -- rate each as "friendly / retrofittable / unfriendly."
 - Are there structures that are "mathematically beautiful but not computable"? (Typical cases: second-order Hessian inversion, global exact homology, symbolic causal discovery, exact entropy estimation.) Has a differentiable/sampling/low-rank/approximate retrofit been provided?
 - Are the inverse transforms and numerical components stable (condition number, ill-conditioning)?
 - Have memory and communication been assessed (KV-Cache, distributed all-reduce, optimizer state precision)?
 
-### 18. Modern-Math Activation Review -> `references/books/*`
+### 18. Modern-Math Activation Review -> `../references/books/*.en.md`
 
 > **Mandatory** when the deliverable claims to "activate modern mathematics into algorithms." Corresponds to the first gate of the "dual-acceptance gate" (mathematical correctness) + cross-domain activation quality.
 
 - Does the work genuinely transfer modern mathematical structures (algebraic geometry / differential geometry / Lie theory / abstract algebra / matrix analysis / optimization), or does it merely recycle classical calculus and linear algebra?
 - Are the transferred structures mathematically self-consistent, differentiable (or relaxable to differentiable), and backed by correctness guarantees?
-- Were the corresponding `references/books/*.md` distilled notes consulted? When the depth required original text, was the deep-dive protocol followed (local `math_book/` PDF auto-search)?
+- Were the corresponding `../references/books/*.en.md` distilled notes consulted? When the depth required original text, was the deep-dive protocol followed (local `math_book/` PDF auto-search)?
 - Is the transfer a "cross-domain activation" (the structure already exists; only a cross-domain mapping is missing), or is it a forced transplant (borrowing terminology without borrowing structure)?
 - Does the deliverable simultaneously pass the **dual-acceptance gate**: mathematically correct **AND** (friendly or retrofittable on the eight dimensions)? Are candidates that fail either criterion eliminated?
 
@@ -170,7 +170,7 @@ The first 15 dimensions cover the core review angles — assumptions, logic, mod
 
 ## Output Format
 
-Reports should follow the structure below. Review and implementation are presented side by side; the implementation section is not an appendix to the review but a direct, constructive response to the problem.
+The structure below is the full-report template, not the default response. For short questions, lead with conclusion + fatal/important issues + fix path + verification. Expand every subsection only for full reviews, paper-style reviews, or multi-candidate designs. Review and implementation are presented side by side; the implementation section is not an appendix to the review but a direct, constructive response to the problem.
 
 ```
 ## Review and Implementation Report

package/agents/math-critic.md

@@ -92,7 +92,7 @@
 - 问题是否属于NP-hard或不可判定类别？是否需要近似或启发式？
 - 数值方法是否收敛？精度是否足够？
 
-### 11. 信息结构审视 / Information Structure Review -> probabilistic（概率统计透镜）+ `knowledge-base/probability/`
+### 11. 信息结构审视 / Information Structure Review -> probabilistic（概率统计透镜）+ `../knowledge-base/probability/`
 
 - 问题的信息结构是否清晰？是否存在冗余或缺失的信息？
 - 是否可以用信息熵、互信息等量化不确定性？
@@ -132,22 +132,22 @@
 - 是否枚举了多个候选结构（而非只给一个）？
 - 若不确定该审视哪些维度，先调用 `/ask` 让激活器推荐最合适的 3–5 个审视维度。
 
-### 17. GPU 可行性审视 / GPU-Feasibility Review -> `references/gpu-friendly-math.md`
+### 17. GPU 可行性审视 / GPU-Feasibility Review -> `../references/gpu-friendly-math.md`
 
 > 产出涉及算法/算子/训练/GPU 设计时为**强制项**。对应「双验收门」的第二道门。
 
-- 产出是否过 `references/gpu-friendly-math.md` 的**八维**？张量化 / GEMM 可映射 / 复杂度（亚二次）/ 显存与 KV-Cache / 低精度稳定 / 并行与通信 / 稀疏结构 / 算子融合——逐项给「友好/可改造/不友好」。
+- 产出是否过 `../references/gpu-friendly-math.md` 的**八维**？张量化 / GEMM 可映射 / 复杂度（亚二次）/ 显存与 KV-Cache / 低精度稳定 / 并行与通信 / 稀疏结构 / 算子融合——逐项给「友好/可改造/不友好」。
 - 是否存在「数学美但不可算」的结构？（典型：二阶法 Hessian 求逆、全局精确同调、符号因果发现、精确熵估计）——是否给出了可微/采样/低秩/近似改造？
 - 逆变换/数值部分是否稳定（条件数、病态）？
 - 显存与通信是否被评估（KV-Cache、分布式 all-reduce、optimizer state 精度）？
 
-### 18. 现代数学激活审视 / Modern-Math Activation Review -> `references/books/*`
+### 18. 现代数学激活审视 / Modern-Math Activation Review -> `../references/books/*`
 
 > 产出声称「把现代数学激活进算法」时为**强制项**。对应「双验收门」的第一道门（数学正确）+ 跨域激活质量。
 
 - 是否真的迁移了现代数学结构（代数几何/微分几何/李理论/抽象代数/矩阵分析/最优化），还是只用了经典微积分/线代打转？
 - 迁移的结构在数学上是否自洽、可微（或可松弛为可微）、有正确性保证？
-- 是否查阅了对应 `references/books/*.md` 蒸馏稿？深度需要原文时是否走了深挖回查协议（本机 `math_book/` PDF 自动搜索）？
+- 是否查阅了对应 `../references/books/*.md` 蒸馏稿？深度需要原文时是否走了深挖回查协议（本机 `math_book/` PDF 自动搜索）？
 - 迁移是否是「跨领域激活」（结构本就在那里，只差一次跨域映射），还是生搬硬套（只借名词不借结构）？
 - 产出是否同时通过**双验收门**：数学正确 **AND**（八维友好或可改造）？未同时通过的候选是否被剔除？
 
@@ -170,7 +170,7 @@
 
 ## 输出格式
 
-建议按以下结构进行报告。审视与实现并列呈现，实现部分不是审视的附属，而是对问题的正面回应。
+以下结构是完整报告模板，不是默认输出。短问题优先给“结论 + 致命/重要问题 + 修法 + 验证”，只有在用户要求完整审查、论文级审稿或多候选设计时才展开所有小节。审视与实现并列呈现，实现部分不是审视的附属，而是对问题的正面回应。
 
 ```
 ## 审视与实现报告

package/commands/ask.en.md

@@ -4,7 +4,12 @@ description: |
   Math Research OS entry: auto-diagnose user intent, route to thinking lenses, math knowledge base, or design translation layer.
 ---
 
-Read and follow `../skills/math-research-activator/SKILL.en.md`.
+## Language Routing (inline)
+
+Determine primary language: judge by sentence frame, verbs, mood particles. AI/math/engineering terms (attention, loss, routing, etc.) do not count as language signals. Code, paths, formulas do not count. When CN/EN ratio is close, follow the previous turn's language; default to Chinese if no context. Explicit "in English/in Chinese" takes priority.
+
+- Chinese primary → load `../skills/math-research-activator/SKILL.md`
+- English primary → load `../skills/math-research-activator/SKILL.en.md`
 
 Current question:
 $ARGUMENTS

package/commands/ask.md

@@ -5,7 +5,12 @@ description: |
   English: Math Research OS entry: auto-diagnose user intent, route to thinking lenses, math knowledge base, or design translation layer.
 ---
 
-按 `../skills/math-research-activator/SKILL.md` 中的语言路由与混合输入规则判定主语言。英文主语言 → 读取 `../skills/math-research-activator/SKILL.en.md`；中文主语言 → 读取 `../skills/math-research-activator/SKILL.md`。
+## 语言路由（内联）
+
+判定主语言：看句式、动词、语气词的主框架。AI/数学/工程术语（attention、loss、routing 等）不计入语言判定。代码、路径、公式不计入。中英比例接近时沿用上一轮语言，无上下文默认中文。显式"用英文/用中文"优先。
+
+- 中文主语言 → 读取 `../skills/math-research-activator/SKILL.md`
+- 英文主语言 → 读取 `../skills/math-research-activator/SKILL.en.md`
 
 当前问题：
 $ARGUMENTS

package/design-patterns/attention/equivariant-attention.en.md

@@ -6,12 +6,12 @@ When the input possesses an **explicit symmetry group $G$ action** (rotation, tr
 
 ## Mathematical Inspiration
 - Lenses: [symmetry, categorical (unified framework for group actions)]
-- Knowledge: [`../../knowledge-base/probability/concentration-inequality.md` (sample efficiency gains under equivariant constraints -- data equivalence along orbits), `../../knowledge-base/probability/entropy.md` (equivariant constraints reduce output distribution entropy, yielding stronger inductive bias)]
+- Knowledge: [`../../knowledge-base/probability/concentration-inequality.en.md` (sample efficiency gains under equivariant constraints -- data equivalence along orbits), `../../knowledge-base/probability/entropy.en.md` (equivariant constraints reduce output distribution entropy, yielding stronger inductive bias)]
 
 ## Required Mathematical Knowledge
 - **Group Representation Theory Basics**: Linear representation of a group $G$, $\rho: G \to GL(V)$, and irreducible representation decomposition
 - **Equivariant Map Definition**: $f(g \cdot x) = \rho_{\text{out}}(g) \cdot f(x)$ for all $g \in G$
-- **Orbit-Stabilizer Theorem** (see `references/books/abstract-algebra.md` Ch.5): $|orbit| = |G|/|stab|$, giving the parameter sharing multiplier
+- **Orbit-Stabilizer Theorem** (see `../../references/books/abstract-algebra.en.md` Ch.5): $|orbit| = |G|/|stab|$, giving the parameter sharing multiplier
 - **Schur's Lemma**: An equivariant linear map between irreducible representations is either zero or a scalar multiple
 
 ## AI Module Form
@@ -64,6 +64,12 @@ output = mean(softmax((rho(g)@X@W_q) @ (rho(g)@X@W_k).T/sqrt(d)) @ (rho(g)@X@W_v
 - **D7**: Permutation $\rho(g)$ is extremely sparse and can be encoded as gather indices
 - **D8**: Group action + linear duality can be fused into a single batched GEMM
 
+**Quantitative assessment example** (E(3) equivariant, |G|=24 rotation group, d=64, n=512):
+- D3: |G|x standard attention FLOPs = 24 · 2·512²·64 ≈ 805M (vs standard 33.6M)
+- D4: Requires storing |G|=24 copies of intermediate features, 24 · 512 · 64 · 2B ≈ 1.5MB extra memory
+- D6: 24 group elements parallelizable along the batch dimension, ideal speedup 24x
+- D8: ρ(g)·X·W_q three-step fusion into a single batched GEMM
+
 ## Paper Phrasing
 "We propose an equivariant attention mechanism that constrains attention weights to be group invariants and attention outputs to be group equivariants, directly encoding the inductive bias of symmetry group $G$ into the model architecture without additional data augmentation, achieving a $|G|/|stab|$-fold improvement in parameter efficiency."
 

package/design-patterns/attention/equivariant-attention.md

@@ -11,7 +11,7 @@
 ## 需要的数学知识
 - **群表示论基础**：群 $G$ 的线性表示 $\rho: G \to GL(V)$，不可约表示分解
 - **等变映射定义**：$f(g \cdot x) = \rho_{\text{out}}(g) \cdot f(x)$，对所有 $g \in G$
-- **轨道-稳定子定理**（参见 `references/books/abstract-algebra.md` Ch.5）：$|orbit| = |G|/|stab|$，参数共享倍率
+- **轨道-稳定子定理**（参见 `../../references/books/abstract-algebra.md` Ch.5）：$|orbit| = |G|/|stab|$，参数共享倍率
 - **Schur 引理**：不可约表示间的等变线性映射要么为零要么为标量乘
 
 ## AI 模块形式
@@ -64,6 +64,12 @@ output = mean(softmax((rho(g)@X@W_q) @ (rho(g)@X@W_k).T/sqrt(d)) @ (rho(g)@X@W_v
 - **D7[~]**：置换 $\rho(g)$ 极度稀疏，可编码为 gather 索引
 - **D8[v]**：群作用 + 线性变换可融合为单次 batched GEMM
 
+**量化评估示例**（E(3) 等变, |G|=24 旋转群, d=64, n=512）：
+- D3: |G|× 标准 attention FLOPs = 24 · 2·512²·64 ≈ 805M（vs 标准 33.6M）
+- D4: 需存储 |G|=24 份中间特征，24 · 512 · 64 · 2B ≈ 1.5MB 额外显存
+- D6: 24 个群元素沿 batch 维并行，理想加速比 24x
+- D8: ρ(g)·X·W_q 三步融合为单次 batched GEMM
+
 ## 论文表述方式
 "我们提出等变注意力机制，通过将注意力权重约束为群不变量、注意力输出约束为群等变量，在不增加数据增强的情况下将对称群 $G$ 的归纳偏置直接编码进模型结构，参数效率提升 $|G|/|stab|$ 倍。"
 

package/design-patterns/attention/geometry-aware-attention.en.md

@@ -6,7 +6,7 @@ When **known geometric relationships** exist between tokens/keys (spatial distan
 
 ## Mathematical Inspiration
 - Lenses: [symmetry (metric invariance), duality (coordinate-system-independent representation)]
-- Knowledge: [`../../knowledge-base/information-geometry/fisher-metric.md` (geometric metrics on distribution spaces), `../../knowledge-base/probability/concentration-inequality.md` (concentration behavior under geometric constraints)]
+- Knowledge: [`../../knowledge-base/information-geometry/fisher-metric.en.md` (geometric metrics on distribution spaces), `../../knowledge-base/probability/concentration-inequality.en.md` (concentration behavior under geometric constraints)]
 
 ## Required Mathematical Knowledge
 - **Metric Spaces and Distance Functions**: Euclidean distance, geodesic distance, tree distance, Wasserstein distance
@@ -66,7 +66,7 @@ def manifold_attention(Q, K, V, manifold):
 - **D8**: Geometric bias can be fused into FlashAttention's online softmax loop (added after $QK^T$, before softmax)
 
 ## Paper Phrasing
-"We propose geometry-aware attention, which explicitly injects learnable geometric distance bias terms into attention scores, enabling the model to naturally respect the metric structure of the input space. This achieves exponential decay of attention to distant tokens without increasing parameter count, while maintaining compatibility with FlashAttention."
+"We propose geometry-aware attention, which explicitly injects geometric distance bias terms into attention scores, enabling the model to naturally respect the metric structure of the input space. This achieves exponential decay of attention to distant tokens with only a small number of additional geometric bias parameters (zero for fixed bias variants such as ALiBi), while maintaining compatibility with FlashAttention."
 
 ## Risks
 - **Geometric Prior Conflicting with Data**: If geometric distance is inconsistent with semantic relevance (e.g., distant but semantically related tokens in text), strong geometric bias will impair model expressiveness. The bias should be learnable and overridable by content-based attention.

package/design-patterns/attention/geometry-aware-attention.md

@@ -65,7 +65,7 @@ def manifold_attention(Q, K, V, manifold):
 - **D8[v]**：几何偏置可融入 FlashAttention 的 online softmax 循环中（加在 $QK^T$ 之后、softmax 之前）
 
 ## 论文表述方式
-"我们提出几何感知注意力，通过在注意力分数中显式注入可学习的几何距离偏置项，使模型天然尊重输入空间的度量结构，在不增加参数量的情况下将远距离 token 的注意力指数衰减，同时保持与 FlashAttention 的兼容性。"
+"我们提出几何感知注意力，通过在注意力分数中显式注入几何距离偏置项，使模型天然尊重输入空间的度量结构，在仅增加少量几何偏置参数（固定偏置如 ALiBi 则零额外参数）的情况下将远距离 token 的注意力指数衰减，同时保持与 FlashAttention 的兼容性。"
 
 ## 风险
 - **几何先验与数据冲突**：若几何距离与语义相关性不一致（如文本中远距离但语义相关的 token），强几何偏置会伤害模型表达。需让偏置可学习且可被内容注意力覆盖。

package/design-patterns/attention/information-bottleneck-attention.en.md

@@ -6,7 +6,7 @@ When the attention mechanism needs to **selectively transmit useful information
 
 ## Mathematical Inspiration
 - Lenses: [categorical (information-theoretic framework unifying attention design), variational (constrained variational and Lagrangian duality)]
-- Knowledge: [`../../knowledge-base/probability/information-bottleneck.md` (IB objective and variational lower bound), `../../knowledge-base/probability/kl-divergence.md` (implementation of KL regularization), `../../knowledge-base/probability/entropy.md` (mutual information estimation)]
+- Knowledge: [`../../knowledge-base/probability/information-bottleneck.en.md` (IB objective and variational lower bound), `../../knowledge-base/probability/kl-divergence.en.md` (implementation of KL regularization), `../../knowledge-base/probability/entropy.en.md` (mutual information estimation)]
 
 ## Required Mathematical Knowledge
 - **Information Bottleneck Objective**: $\min I(X;Z) - \beta I(Z;Y)$, balancing compression and prediction
@@ -19,27 +19,47 @@ When the attention mechanism needs to **selectively transmit useful information
 
 **Scheme A: KL-Regularized Attention (Simplest IB Attention)**:
 ```python
-# KL divergence between attention distribution q(z|x) and uniform prior as IB regularizer
+# ⚠ Note the semantic direction of KL:
+# KL(attn || uniform) = log(n) - H(attn)
+# Minimizing +beta * KL(attn || uniform) = maximizing H(attn) → pushes toward uniform (max entropy / max compression)
+# This does NOT induce sparsity by itself! Sparsity emerges from the tension with task_loss.
+# For explicit sparsity induction, use an entropy penalty +beta * H(attn) (minimize entropy).
+
 scores = (Q @ K.T) / sqrt(d)
 attn = softmax(scores)
 uniform_prior = ones_like(attn) / n
-kl_reg = (attn * (log(attn + eps) - log(uniform_prior))).sum(dim=-1).mean()
-loss = task_loss + beta * kl_reg
+
+# Correct IB compression term: KL(q(z|x) || p(z)), where p(z) is a fixed prior
+# Minimizing this term → compresses information (pushes toward prior); tension with task_loss yields useful attention
+kl_compression = (attn * (log(attn + eps) - log(uniform_prior))).sum(dim=-1).mean()
+# = log(n) - H(attn)
+
+# IB objective: min task_loss + beta * I(X;Z), where I(X;Z) ≈ KL(attn || prior)
+loss_ib = task_loss + beta * kl_compression
+# Note: this term alone pushes toward uniform; sparsity arises from the counter-pull of task_loss
+
+# Alternative: explicit sparsity induction (not IB compression, but entropy penalty)
+entropy = -(attn * log(attn + eps)).sum(dim=-1).mean()
+loss_sparse = task_loss + beta * entropy  # minimize entropy → concentrated attention → implicit Top-K
+
 output = attn @ V
 ```
 
 **Scheme B: Variational Information Bottleneck Attention (VIB-Attention)**:
 ```python
-# Introduce stochastic bottleneck Z ~ q(Z|attention) to limit information throughput
+# Introduce a continuous stochastic bottleneck Z ~ q(Z|context) after value aggregation
 scores = (Q @ K.T) / sqrt(d)
 attn = softmax(scores)
-mu_z, log_var_z = attn, linear(attn)  # mean and learnable variance
-z = softmax(mu_z + exp(0.5 * log_var_z) * randn_like(mu_z))  # reparameterization + softmax
-kl = 0.5 * (mu_z^2 + exp(log_var_z) - log_var_z - 1).sum(-1).mean()  # KL vs prior
-output = z @ V
+context = attn @ V
+mu_z, log_var_z = linear_mu(context), linear_logvar(context)
+z = mu_z + exp(0.5 * log_var_z) * randn_like(mu_z)  # Gaussian reparameterization
+kl = 0.5 * (mu_z^2 + exp(log_var_z) - log_var_z - 1).sum(-1).mean()  # KL[q(z|context)||N(0,I)]
+output = linear_out(z)
 loss = task_loss + beta * kl
 ```
 
+If the bottleneck is applied directly on the attention simplex (e.g., noisy logits followed by softmax), the random variable is logistic-normal / Concrete-like. The closed-form Gaussian KL above no longer applies; use Monte Carlo KL, a Concrete KL approximation, or place the Gaussian KL on pre-softmax logits.
+
 **Scheme C: Mutual Information Maximization Attention (DIM Style)**:
 ```python
 # Directly maximize I(Z;Y) via InfoNCE, with KL constraining I(X;Z)
@@ -50,7 +70,7 @@ loss = -info_nce + beta * kl_bottleneck
 ```
 
 ## Implementable Architectures
-- **IB-Sparse Attention**: KL regularization serves as a soft constraint on attention sparsity -- larger KL relative to uniform prior leads to more concentrated attention, yielding implicit Top-K selection
+- **IB-Sparse Attention**: The IB compression term KL(attn || uniform) by itself pushes toward uniform (maximum entropy), but its tension with task_loss forces the attention to balance between "compressing all information" and "selectively transmitting useful information," implicitly producing non-uniform attention. For **explicit** sparsity induction (Top-K selection), use an entropy penalty `+beta * H(attn)` (minimize attention entropy → concentration), rather than relying on the IB compression term alone
 - **IB Interpretation of Dropout**: Dropout is a form of stochastic information bottleneck -- randomly blocking information channels forces the model to learn robust representations. The dropout rate corresponds to the $\beta$ parameter
 - **Multi-Head Information Allocation**: Different heads learn different information bottlenecks (different $\beta$); some heads transmit global information, others only local information
 
@@ -61,11 +81,11 @@ loss = -info_nce + beta * kl_bottleneck
 - **D4**: VIB requires additional $\mu_z$ and $\log\sigma_z$, approximately doubling attention weight memory
 - **D5**: log/exp in KL computations are stable under bf16 (standard log-softmax tricks)
 - **D6**: Regularization can be computed in parallel with forward propagation, introducing no serial dependencies
-- **D7**: KL regularization implicitly induces attention sparsity, amenable to block-sparse acceleration
+- **D7[~]**: KL regularization by itself does not induce sparsity (pushes toward uniform distribution); for sparsity, use an entropy penalty +beta * H(attn), which then enables block-sparse acceleration
 - **D8**: KL can be fused into the softmax kernel (FusedSoftmaxKL)
 
 ## Paper Phrasing
-"We propose information bottleneck attention, which models attention as an information bottleneck variational problem. By maximizing the mutual information between output and target while minimizing redundant information transmission from the input, it achieves theoretically optimal information selection and demonstrates enhanced sparsity and interpretability in experiments."
+"We propose information bottleneck attention, which models attention as an information bottleneck optimization problem. By maximizing the mutual information between output and target while constraining redundant information transmission from the input, the IB compression term by itself pushes toward a uniform distribution (maximum entropy), and its tension with the task loss produces non-uniform attention; explicit sparsity induction requires an additional entropy penalty term."
 
 ## Risks
 - **High Variance of Mutual Information Estimators**: The MINE/NWJ/InfoNCE estimators in Scheme C exhibit high variance in high-dimensional spaces, potentially causing training instability. It is recommended to first validate the basic effect of IB attention with Scheme A (KL regularization) before attempting the full IB objective.

package/design-patterns/attention/information-bottleneck-attention.md

@@ -19,27 +19,47 @@
 
 **方案 A：KL 正则化注意力（最简 IB 注意力）**：
 ```python
-# 注意力分布 q(z|x) 与均匀先验的 KL 散度作为 IB 正则
+# ⚠ 注意 KL 方向的语义：
+# KL(attn || uniform) = log(n) - H(attn)
+# 最小化 +beta * KL(attn || uniform) = 最大化 H(attn) → 推向均匀分布（最大熵/最大压缩）
+# 这本身不诱导稀疏性！稀疏性来自压缩项与 task_loss 的张力。
+# 若需要显式诱导稀疏注意力，应使用熵惩罚 +beta * H(attn)（最小化熵）。
+
 scores = (Q @ K.T) / sqrt(d)
 attn = softmax(scores)
 uniform_prior = ones_like(attn) / n
-kl_reg = (attn * (log(attn + eps) - log(uniform_prior))).sum(dim=-1).mean()
-loss = task_loss + beta * kl_reg
+
+# 正确的 IB 压缩项：KL(q(z|x) || p(z))，p(z) 为固定先验
+# 最小化此项 → 压缩信息（推向先验），与 task_loss 的张力产生有用注意力
+kl_compression = (attn * (log(attn + eps) - log(uniform_prior))).sum(dim=-1).mean()
+# = log(n) - H(attn)
+
+# IB 目标：min task_loss + beta * I(X;Z)，其中 I(X;Z) ≈ KL(attn || prior)
+loss_ib = task_loss + beta * kl_compression
+# 注意：此项单独作用会推向均匀；稀疏性来自 task_loss 的反向拉力
+
+# 替代方案：显式稀疏性诱导（非 IB 压缩，而是熵惩罚）
+entropy = -(attn * log(attn + eps)).sum(dim=-1).mean()
+loss_sparse = task_loss + beta * entropy  # 最小化熵 → 注意力集中 → 隐式 Top-K
+
 output = attn @ V
 ```
 
 **方案 B：变分信息瓶颈注意力（VIB-Attention）**：
 ```python
-# 引入随机瓶颈 Z ~ q(Z|attention)，限制信息通过量
+# 引入随机连续瓶颈 Z ~ q(Z|context)，限制 value 聚合后的信息通过量
 scores = (Q @ K.T) / sqrt(d)
 attn = softmax(scores)
-mu_z, log_var_z = attn, linear(attn)  # 均值与可学习方差
-z = softmax(mu_z + exp(0.5 * log_var_z) * randn_like(mu_z))  # 重参数化 + softmax
-kl = 0.5 * (mu_z^2 + exp(log_var_z) - log_var_z - 1).sum(-1).mean()  # KL vs 先验
-output = z @ V
+context = attn @ V
+mu_z, log_var_z = linear_mu(context), linear_logvar(context)
+z = mu_z + exp(0.5 * log_var_z) * randn_like(mu_z)  # 高斯重参数化
+kl = 0.5 * (mu_z^2 + exp(log_var_z) - log_var_z - 1).sum(-1).mean()  # KL[q(z|context)||N(0,I)]
+output = linear_out(z)
 loss = task_loss + beta * kl
 ```
 
+若瓶颈直接作用在 attention simplex 上（如对 logits 加噪后 softmax），变量分布是 logistic-normal / Concrete 类，不能再使用普通高斯到标准正态的闭式 KL；应使用 Monte Carlo KL、Concrete KL 近似，或把 KL 放在 softmax 前的 logits 高斯变量上。
+
 **方案 C：互信息最大化注意力（DIM 风格）**：
 ```python
 # 用 InfoNCE 直接最大化 I(Z;Y)，配合 KL 约束 I(X;Z)
@@ -50,7 +70,7 @@ loss = -info_nce + beta * kl_bottleneck
 ```
 
 ## 可实现结构
-- **IB-Sparse Attention**：将 KL 正则化为注意力稀疏性的软约束——KL 对均匀先越大 → 注意力越集中 → 隐式 Top-K 选择
+- **IB-Sparse Attention**：IB 压缩项 KL(attn || uniform) 本身推向均匀分布（最大熵），但与 task_loss 的张力迫使注意力在"压缩所有信息"与"选择性传递有用信息"之间取舍，从而隐式产生非均匀注意力。若要**显式**诱导稀疏（Top-K 选择），应使用熵惩罚 `+beta * H(attn)`（最小化注意力熵 → 集中化），而非依赖 IB 压缩项
 - **Dropout 的 IB 解释**：Dropout 是一种随机信息瓶颈——随机阻断部分信息通道，迫使模型学习鲁棒表示。Dropout rate 对应 $\beta$ 参数
 - **Multi-Head 信息分配**：不同 head 学习不同的信息瓶颈（不同 $\beta$），有的 head 传递全局信息，有的只传递局部信息
 
@@ -61,12 +81,12 @@ loss = -info_nce + beta * kl_bottleneck
 - **D4[~]**：VIB 需额外 $\mu_z$ 和 $\log\sigma_z$，约 2x 注意力权重显存
 - **D5[v]**：KL 中 log/exp 在 bf16 下稳定（标准 log-softmax 技巧）
 - **D6[v]**：正则项可与前向传播并行，不引入串行依赖
-- **D7[v]**：KL 正则隐式诱导注意力稀疏性，可利用 block-sparse 加速
+- **D7[~]**：KL 正则本身不诱导稀疏性（推向均匀分布）；若需稀疏，应改用熵惩罚 +beta * H(attn)，此时可 block-sparse 加速
 - **D8[v]**：KL 可融入 softmax kernel（FusedSoftmaxKL）
 
 ## 论文表述方式
-"我们提出信息瓶颈注意力机制，通过将注意力建模为信息瓶颈优化问题，在最大化输出与目标的互信息的同时最小化输入信息的冗余传递，实现理论上最优的信息选择，并在实验中展现出更强的稀疏性和可解释性。"
+"我们提出信息瓶颈注意力机制，通过将注意力建模为信息瓶颈优化问题，在最大化输出与目标的互信息的同时约束输入信息的冗余传递。IB 压缩项本身推向均匀分布（最大熵），与任务损失的张力产生非均匀注意力；若要显式诱导稀疏性，需额外使用熵惩罚项。"
 
 ## 风险
 - **互信息估计的方差问题**：方案 C 中的 MINE/NWJ/InfoNCE 估计器在高维空间中方差大，可能导致训练不稳定。建议先用方案 A（KL 正则）验证 IB 注意力的基本效果，再尝试完整 IB 目标。
-- **$\beta$ 调参困难**：$\beta$ 控制压缩-预测权衡，不同任务最优 $\beta$ 差异大。$\beta$ 过小退化为标准注意力，$\beta$ 过大导致欠拟合。建议自适应 $\beta$ 调度或信息平面监控。
+- **$\beta$ 调参困难**：$\beta$ 控制压缩-预测权衡，不同任务最优 $\beta$ 差异大。$\beta$ 过小退化为标准注意力，$\beta$ 过大导致欠拟合。建议自适应 $\beta$ 调度或信息平面监控。

package/design-patterns/attention/projection-attention.en.md

@@ -6,7 +6,7 @@ When the token/key space dimensionality is too high, the standard attention $Q K
 
 ## Mathematical Inspiration
 - Lenses: [projection, spectral, probabilistic]
-- Knowledge: [`../../knowledge-base/probability/concentration-inequality.md` (high-dimensional concentration inequalities provide theoretical explanation for attention collapse), `../../knowledge-base/probability/entropy.md` (entropy of attention distributions as a quality metric)]
+- Knowledge: [`../../knowledge-base/probability/concentration-inequality.en.md` (high-dimensional concentration inequalities provide theoretical explanation for attention collapse), `../../knowledge-base/probability/entropy.en.md` (entropy of attention distributions as a quality metric)]
 
 ## Required Mathematical Knowledge
 - **Johnson-Lindenstrauss Lemma**: High-dimensional point sets can be projected onto an $O(\log n / \epsilon^2)$-dimensional subspace while approximately preserving distances
@@ -31,7 +31,7 @@ scores = (Q @ P_Q) @ (K @ P_K).T / sqrt(r)
 attn = softmax(scores) @ V
 ```
 
-2. **Random Fixed Projection** (guaranteed by the JL Lemma):
+2. **Random Fixed Projection** (distance-preservation bound when JL conditions hold):
 ```
 P = random_gaussian(d, r) / sqrt(r)  # fixed, not trained
 scores = (Q @ P) @ (K @ P).T / sqrt(r)
@@ -61,7 +61,7 @@ scores = (Q @ eigenvecs) @ (K @ eigenvecs).T / sqrt(r)
 - **D8[~] Retrofittable, needs kernel-level validation**: Projection may be integrated into a FlashAttention-style kernel, but requires kernel-level verification
 
 ## Paper Phrasing
-"We decompose attention computation into two steps -- low-dimensional subspace projection and projected-space attention -- achieving a $d/r$-fold Key-cache compression (full KV-Cache compression requires separate V compression/reconstruction) while preserving attention quality and guaranteeing Johnson-Lindenstrauss distance preservation."
+"We decompose attention computation into low-dimensional subspace projection and projected-space attention to reduce Key dimensionality; V-cache must be handled separately. With an independent random projection and the sample-size / target-dimension conditions of the Johnson-Lindenstrauss lemma, Euclidean distances of the projected objects can be approximately preserved. This does not automatically guarantee softmax-attention quality, so attention/output error and task metrics must be reported."
 
 ## Risks
 - **Projection Direction Degeneracy**: Learnable projections may collapse onto a few directions (deterioration of the condition number of $P^T P$), causing attention distributions to degenerate. Orthogonal regularization $\|P^T P - I\|_F^2$ is required.