feat: add Tiny-NLA activation explanation with trained model weights

- Train Tiny-NLA (AV + AR) on Qwen3-0.6B to explain layer-19 activations
- Add /api/activation-explain endpoint with TinyNLAEngine (lazy loading)
- Integrate activation explain into Logit Lens frontend page
- Include training scripts, eval tools, and experiment configs
- Ship trained checkpoints: AV LoRA adapter + AR head (~20MB)

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 *.py[cod]
 .venv/
 venv/
+venv*/
 env/
 node_modules/
 client/src/node_modules/
@@ -34,6 +35,9 @@ user_dialog_history/*
 .cache_huggingface/
 .env
 
+# --- 实验工件（模型权重、数据、检查点） ---
+artifacts/
+
 # --- 系统与 IDE ---
 .DS_Store
 .idea/

DESIGN_PROMPT.md

@@ -0,0 +1,608 @@
+# InfoLens / INNERSCOPE — 统一工作流重设计 Prompt
+
+> **目标受众**：专精 UI/UX 设计的 Agent  
+> **任务**：理解现有前端架构和各功能模块，设计一个统一的工作流 demo，将当前孤立的 7 个功能（含新训练的 Tiny-NLA）有机融合为一个流畅的「输入文本 → 多维度探索模型内部」体验。  
+> **输出形式**：给出初步的 HTML/CSS/JS demo（可以是静态原型或可交互 demo），不需要对接真实后端 API。  
+> **重要的**：这是概念验证 demo，不是产品实现。你可以自由选择任何设计方向、技术栈、视觉风格。不要被现有代码的样式束缚。
+
+---
+
+## 一、项目是什么
+
+**InfoLens（品牌名 INNERSCOPE）** 是一个「透视大语言模型内部」的可视化工具箱。用户输入一段文本，通过不同的分析维度观察模型在想什么。
+
+- **服务端**：Python Flask/Connexion，跑在本地 M4 Pro Mac 上  
+- **模型**：Qwen3-0.6B (base + instruct)，本地 CPU/MPS 推理  
+- **用户画像**：AI 研究者 / 可解释性爱好者，希望直观看到模型内部状态  
+
+---
+
+## 二、现有前端代码结构（供参考，不需要遵循）
+
+```
+client/src/
+├── index.html                    # 首页（导航网格）
+├── analysis.html                 # Info Highlight 页
+├── chat.html                     # Raw Chat 页
+├── attribution.html              # Attribution 页
+├── causal_flow.html              # Causal Flow 页
+├── logit_lens.html               # Logit Lens 页
+├── branch_tree.html              # Branch Tree 页
+│
+├── webpack.config.js             # 多入口打包
+│
+├── pages/                        # 每个页面的 TS 入口
+│   ├── home/index.ts
+│   ├── analysis/index.ts
+│   ├── chat/index.ts             # ~800 行，最复杂
+│   ├── attribution/index.ts
+│   ├── causal_flow/index.ts
+│   ├── logit_lens/index.ts
+│   └── branch_tree/index.ts
+│
+├── shared/                       # 跨页面共享基础设施
+│   ├── api/GLTR_API.ts           # TextAnalysisAPI 类（所有后端通信）
+│   ├── core/                     # URL 解析、事件总线、工具函数
+│   ├── ui/                       # toast, dialog, 主题/语言切换, 面板布局
+│   ├── vis/                      # D3 可视化组件（Token着色、Tooltip、直方图、散点图）
+│   └── lang/translations.ts      # i18n 翻译
+│
+├── partials/                     # HTML 片段（被 include 到页面中）
+│
+├── features/                     # 按功能域拆分
+│   ├── analysis/                 # Info Highlight 流程
+│   ├── chat/                     # 对话/续写逻辑
+│   ├── causal_flow/              # Causal Flow 逻辑
+│   └── demo/                     # Demo 存储
+│
+└── css/pages/                    # 每页独立的 SCSS
+```
+
+---
+
+## 三、7 个功能模块详解（含完整 API Schema）
+
+### 3.1 Info Highlight — Token 级别信息密度分析
+
+**做什么**：展示模型对文本中每个 token 的「意外程度」——哪些词模型觉得理所当然，哪些词让它意外。
+
+**API：`POST /api/analyze`**
+```
+请求：
+{
+  "model": "base" | "instruct",
+  "text": "water freezes into solid ice",
+  "stream": false              // 可选，true 时 SSE 流式返回
+}
+
+响应 200：
+{
+  "request": { "text": "water freezes into solid ice" },
+  "result": {
+    "model": "qwen3-0.6b-base",
+    "bpe_strings": [
+      {
+        "offset": [0, 5],        // 字符偏移 [start, end)
+        "raw": "water",           // token 原文
+        "real_topk": [156, 0.023],  // [模型排序名次, softmax 概率]
+        "pred_topk": [            // 该位置 top-N 候选
+          ["ice", 0.34],
+          ["liquid", 0.18],
+          ...
+        ]
+      },
+      ...
+    ]
+  }
+}
+
+错误：400 (缺参数) / 404 (模型未注册) / 500 (推理失败) / 503 (模型加载失败)
+```
+
+**附加子功能 — 语义搜索：`POST /api/analyze-semantic`**
+```
+请求：
+{
+  "query": "frozen",            // 查询主题
+  "text": "...",                // 原文
+  "stream": false,              // 可选 SSE 流式
+  "submode": "count",           // 可选: count / fill_blank
+  "debug_info": true            // 可选，返回 top10 预测
+}
+
+响应 200：
+{
+  "success": true,
+  "model": "qwen3-0.6b-instruct",
+  "token_attention": [
+    {
+      "offset": [13, 19],
+      "raw": "solid",
+      "score": 0.87             // 对 query 的语义关注度
+    },
+    ...
+  ],
+  "debug_info": {               // 仅 debug_info=true 时
+    "abbrev": "...",
+    "topk_tokens": [...],
+    "topk_probs": [...]
+  }
+}
+```
+
+---
+
+### 3.2 Raw Chat — 对话 & 续写
+
+**做什么**：和模型对话，可视化每次续写中每个生成 token 的细节。支持 Raw 模式（直接给 prompt）和 Chat 模式（system + user prompt + chat template）。
+
+**API 链（3 步）：**
+
+**Step 1 — 组装 prompt：`POST /v1/completions/prompt`**
+```
+请求：
+{
+  "model": "qwen3-0.6b-instruct",
+  "messages": [
+    { "role": "system", "content": "You are a helpful assistant." },
+    { "role": "user", "content": "What is water?" }
+  ],
+  "tools": [...],               // 可选 OpenAI tools schema
+  "enable_thinking": false      // 可选，启用 Qwen3 thinking 模式
+}
+
+响应 200：
+{
+  "prompt_used": "<|im_start|>system\n...<|im_end|>\n<|im_start|>user\nWhat is water?<|im_end|>\n<|im_start|>assistant\n"
+}
+```
+
+**Step 2 — 续写（SSE 流式）：`POST /v1/completions`**
+```
+请求：
+{
+  "model": "qwen3-0.6b-instruct",
+  "prompt": "<|im_start|>system\n...",  // 从上一步或直接构造
+  "max_tokens": 256,                      // 可选，正整数
+  "temperature": 0.7,                     // 可选，0-2
+  "top_p": 0.9,                           // 可选，0-1
+  "stop": ["\n\n"]                        // 可选，停止序列（最多4个）
+}
+// 响应恒为 text/event-stream (SSE)
+// type=delta → 增量 token
+// type=result → 末条，data 同 OpenAICompletionsResponse
+
+SSE 末条 data (type=result)：
+{
+  "id": "cmpl-xxx",
+  "object": "text_completion",
+  "created": 1719000000,
+  "model": "qwen3-0.6b-instruct",
+  "choices": [{
+    "text": "Water is a chemical substance...",
+    "index": 0,
+    "finish_reason": "stop"     // stop / length / content_filter
+  }],
+  "usage": {
+    "prompt_tokens": 24,
+    "completion_tokens": 45,
+    "total_tokens": 69
+  },
+  "info_radar": {               // 续写 token 级分析
+    "bpe_strings": [
+      { "offset": [0, 5], "raw": "Water", "real_topk": [1, 0.92], "pred_topk": [...] },
+      ...
+    ]
+  }
+}
+```
+
+**Step 3 — 停止生成：`POST /v1/completions/stop`**
+```
+请求：(无 body)
+响应 200：{ "ok": true }
+```
+
+**高级功能**：Tool Calling 多轮模拟（通过 `/v1/completions/prompt-incremental` 计算 tool response 增量后缀）、Teacher Forcing（强制续写特定文本）、multi-turn 对话缓存与恢复。
+
+---
+
+### 3.3 Attribution — 输入对预测的因果归因
+
+**做什么**：给定上下文和目标预测，分析「是哪些输入词驱动了这个预测」。提供两种方法：梯度归因（gradient-based）和消融归因（ablation/occlusion-based）。
+
+**方法 A — 梯度归因：`POST /api/prediction-attribute`**
+```
+请求：
+{
+  "context": "water freezes and turns into solid",   // 必填，token 数 ≤ 2000
+  "target_prediction": " ice",                        // 可选，缺省用 top-1
+  "model": "base" | "instruct",                      // 必填
+  "source_page": "attribution",                       // 必填
+  "flow_id": null,                                    // 可选，连续归因会话 ID
+  "flow_step": null                                   // 可选，连续归因步骤
+}
+
+响应 200：
+{
+  "success": true,
+  "model": "qwen3-0.6b-base",
+  "target_token": "ice",           // 归因目标 token
+  "target_prob": 0.34,             // 预测概率
+  "token_attribution": [
+    {
+      "offset": [0, 5],            // 字符偏移 [start, end]
+      "raw": "water",
+      "score": 0.42                // 梯度 L2 范数归因分（正值=支撑，越低越无关）
+    },
+    { "offset": [30, 35], "raw": "solid", "score": 0.78 },
+    ...
+  ],
+  "debug_info": {                  // 下一 token 的 top-10
+    "topk_tokens": ["ice", "liquid", "crystal", ...],
+    "topk_probs": [0.34, 0.18, 0.12, ...]
+  },
+  "is_eos": false                  // target 是否为 EOS token
+}
+```
+
+**方法 B — 消融归因：`POST /api/ablation-attribute`**
+```
+请求：
+{
+  "context": "water freezes and turns into solid",   // 必填，token 数 ≤ 500
+  "target_prediction": " ice",                        // 可选，与 target_token_id 互斥
+  "target_token_id": null,                            // 可选，直接指定 token id
+  "model": "base" | "instruct",
+  "source_page": "attribution"
+}
+
+响应 200：
+{
+  "success": true,
+  "target_token": "ice",
+  "target_prob": 0.34,             // baseline 概率
+  "token_attribution": [
+    {
+      "offset": [0, 5],
+      "raw": "water",
+      "score": 0.12,               // ΔP = baseline_prob − occluded_prob（可为负）
+      "delta_logit": 0.38          // Δlogit
+    },
+    ...
+  ],
+  "is_eos": false
+}
+
+错误：400 (缺字段/model非法/超长) / 500 (推理失败) / 503 (繁忙)
+```
+
+---
+
+### 3.4 Logit Lens — 逐层解码轨迹
+
+**做什么**：看模型在每一层的「中间想法」——把每层 hidden state 投影到词表（final norm + lm_head），展示每层 top-k 候选词和目标词概率如何逐层演化。
+
+**API：`POST /api/logit-lens`**
+```
+请求：
+{
+  "context": "The sun rises in the east and sets in the",  // 必填，token 数 ≤ 500
+  "target_prediction": " west",                             // 可选，与 target_token_id 互斥
+  "target_token_id": null,                                  // 可选
+  "model": "base" | "instruct",
+  "source_page": "logit_lens"
+}
+
+响应 200：
+{
+  "success": true,
+  "model": "qwen3-0.6b-base",
+  "target_token": "west",
+  "n_layers": 28,                    // Transformer 层数（不含 embedding）
+  "final_target_prob": 0.72,         // 最终层目标 token 概率
+  "layers": [
+    {
+      "layer": 0,
+      "is_embedding": true,          // 第 0 层为 embedding 层
+      "topk_tokens": ["the", "a", "in", "and", ...],
+      "topk_probs": [0.12, 0.09, 0.07, 0.06, ...],
+      "target_prob": 0.001           // 目标词在该层的概率
+    },
+    {
+      "layer": 1,
+      "is_embedding": false,
+      "topk_tokens": ["in", "the", "to", "of", ...],
+      "topk_probs": [0.15, 0.11, 0.08, 0.07, ...],
+      "target_prob": 0.003
+    },
+    ...                               // 共 n_layers+1 层（含 embedding）
+    {
+      "layer": 28,
+      "is_embedding": false,
+      "topk_tokens": ["west", "east", "north", ...],  // 最终层
+      "topk_probs": [0.72, 0.08, 0.03, ...],
+      "target_prob": 0.72
+    }
+  ],
+  "is_eos": false
+}
+```
+
+**关键概念 — Eureka 层**：目标词首次跃至 top-1 的那一层。例如 layer 18 时 `west` 概率首次超过所有其他候选，这就是「模型想通了这是 west 的那一层」。
+
+---
+
+### 3.5 Branch Tree — 续写分支展开
+
+**做什么**：输入前缀，展开模型所有可能的续写路径（top-k tree），递归探索「模型会怎么往下写」。
+
+**API：`POST /api/branch-next`**
+```
+请求：
+{
+  "prefix": "The sun rises in the",   // 必填
+  "model": "base" | "instruct",       // 必填
+  "source_page": "branch_tree",       // 必填
+  "top_k": 10                         // 可选，候选数（默认10，上限50）
+}
+
+响应 200：
+{
+  "success": true,
+  "model": "qwen3-0.6b-base",
+  "prefix_tokens": 5,                  // prefix 的 token 数
+  "candidates": [
+    { "token": "east",  "token_id": 8423,  "prob": 0.48 },
+    { "token": "west",  "token_id": 2534,  "prob": 0.22 },
+    { "token": "sky",   "token_id": 6712,  "prob": 0.08 },
+    ...
+  ],
+  "is_context_full": false             // true 时前端应禁用展开
+}
+
+错误：400 (缺参数/model非法/超长) / 500 / 503
+```
+
+**递归模式**：选择一个候选 → 拼接进 prefix → 再次调用 branch-next → 形成树。前端负责树的构建和渲染逻辑。
+
+---
+
+### 3.6 Causal Flow — 因果信息流
+
+**做什么**：追踪信息如何在模型层间流动，观察归因信号沿生成步骤的传播。核心是「文本自回归生成 + 每一步的输入 token 对输出 token 的梯度归因」的串行管道。
+
+**依赖的 API**（Causal Flow 是客户端编排的复合流程）：
+1. `POST /api/tokenize` — 分词（见下方 3.6.1）
+2. `POST /api/branch-next` — 获取 top-k 候选（同 3.5）
+3. `POST /api/prediction-attribute` — 每一步的梯度归因（同 3.3），带 `flow_id` + `flow_step` 连续归因
+4. `POST /v1/completions/prompt` — 组装 prompt（同 3.2 Step 1）
+5. `POST /v1/completions` — 续写生成下一个 token
+
+**客户端流程**：输入 context → tokenize → 自动循环：用当前 context 调用 branch-next，选 top-1 → 调用 prediction-attribute 归因当前步 → 拼接 token → 继续下一步（或手动选择分支方向）
+
+**预计算 Demo 数据**：可加载预计算的完整归因 DAG，以 D3 力导向图或传播动画播放，无需实时推理。
+
+---
+
+### 3.6.1 Tokenize — 文本分词（通用工具端点）
+
+**API：`POST /api/tokenize`**
+```
+请求：
+{
+  "context": "Hello, world!",          // 必填
+  "model": "base" | "instruct"         // 必填
+}
+
+响应 200：
+{
+  "success": true,
+  "spans": [
+    { "offset": [0, 5],  "raw": "Hello" },
+    { "offset": [5, 6],  "raw": "," },
+    { "offset": [6, 7],  "raw": " " },
+    { "offset": [7, 12], "raw": "world" },
+    { "offset": [12, 13], "raw": "!" }
+  ]
+}
+
+错误：400 (缺字段/model非法)
+```
+
+**特点**：不持有推理锁，不做前向/梯度计算，响应极快。是构建统一工作流的「第一步」。
+
+---
+
+### 3.7 🆕 Tiny-NLA Activation Explainer（新训练的模型）
+
+**做什么**：给定一个 token 位置的激活向量（从模型 layer 19 残差流提取的 1024 维向量），用 LoRA 微调的小模型解释「这个激活向量代表了什么概念」。支持两种输入模式：传入文本让后端自动提取激活，或直接传入向量。
+
+**模型细节**：
+- **架构**：Qwen3-0.6B-Base + LoRA adapter (r=8, alpha=16) @ layer 19 + AR head（线性层 1024→1024）
+- **推理精度**：float32 + eager（独立加载，不复用 base 槽位的 float16）
+- **训练数据**：284 条 teacher labeled 激活-解释对
+- **设备**：Apple M4 Pro MPS
+- **核心机制**：用特殊 token `㈎`（id=149705）作为激活注入锚点，注入归一化后的激活向量（injection_scale=126.223），AV 模型 generate 出自然语言解释，AR head 重建后计算 cosine 评估可信度
+
+**API：`POST /api/activation-explain`**
+```
+请求模式 A — 文本模式（自动提取激活）：
+{
+  "model": "base" | "instruct",        // 必填
+  "source_page": "logit_lens",         // 必填
+  "text": "water freezes into solid ice",  // 输入上下文
+  "token_index": 4                     // 目标 token 位置（text 模式必填，必须 ≥ 0 且在范围内）
+}
+
+请求模式 B — 向量模式（直接传入）：
+{
+  "model": "base",
+  "source_page": "workspace",
+  "vector": [0.12, -0.34, 0.56, ...]  // 恰好 1024 个 float（与 text 互斥）
+}
+
+响应 200：
+{
+  "success": true,
+  "concept": "",                       // 概念标签（当前为空，可后续扩展）
+  "explanation": "This activation vector encodes the concept of water turning into a solid state through freezing, capturing the physical phase transition from liquid to ice.",
+  "roundtrip_cosine": 0.6631,          // 重建可信度分数 (0-1)
+  "vector_dim": 1024,                  // 向量维度
+  "note": ""                           // 备注或状态说明
+}
+
+错误：
+  400 — 缺字段、model 非法、text/vector 均未提供、token_index 越界、向量维度不为 1024
+  500 — Tiny-NLA 推理失败
+  503 — 推理锁等待超时（30s）
+```
+
+**可信度解读**（roundtrip_cosine）：
+- **≥ 0.70** — 优秀（Excellent）：解释高度忠实于激活
+- **0.60–0.70** — 良好（Good）：解释与激活有较强关联
+- **0.50–0.60** — 可用（Fair）：解释方向大致正确
+- **< 0.50** — 保留（Low）：解释与激活关联较弱，仅供参考
+
+**模型性能基线**：
+- AV（Activation Vector 模型）：best_val_loss = 0.64
+- AR（Auto-Regressive head）：best_val_cosine = 0.6631，mean baseline cosine = 0.5962，shuffled baseline = 0.5252
+- 相比随机 baseline 提升 0.07（统计显著）
+
+## 四、核心问题
+
+```
+现状：6 个功能 = 6 个独立页面
+  ❌ 同一段文本要在不同页面反复输入
+  ❌ 结果之间没有关联（Logit Lens 的结果不能顺手看 Attribution）
+  ❌ 新模型（Tiny-NLA）完全没接入前端
+  ❌ 用户体验割裂——每个功能像独立的工具而非一个整体
+```
+
+---
+
+## 五、设计目标
+
+> **输入一次文本，在一个页面上以多种「透镜」/「视角」探索模型内部。**
+
+期望的用户旅程：
+1. 用户输入一段文本 → tokenize 为可交互的 token 序列
+2. 用户选中某个 token → 可以从多个维度探索：
+   - 📊 **Info Highlight**：看 surprisal
+   - 🎯 **Attribution**：看哪些前文驱动了这个 token
+   - 🔍 **Logit Lens**：看逐层解码轨迹
+   - 🌳 **Branch Tree**：展开可能的续写
+   - 🧠 **Activation Explainer**：解释激活向量代表什么概念
+   - 🔗 **Causal Flow**：看信息流向
+3. 多个分析视图可以同时打开，共享同一份输入上下文
+
+**你可以完全自由地设计交互模式和视觉风格**，不需要考虑现有前端代码的任何约束。
+
+---
+
+## 六、Mock 数据 & 接口设计自由度
+
+### 现有接口参考
+
+所有后端的完整请求/响应 schema 见**第三章各小节**。demo 中构造 mock 数据时，请直接参考对应功能的 API 响应结构。
+
+### 🆕 可以设计新接口
+
+**你不必拘泥于现有接口。** 如果统一工作流的交互需要新的后端接口来达到更好的效果，完全可以提出新的 API 设计。
+
+**前提条件**：新接口必须在我们后端能力范围内。我们后端的能力边界是：
+
+- **运行时**：Python Flask/Connexion，单个 `server.py` 注册函数即自动生成路由
+- **模型能力**：
+  - Qwen3-0.6B (base + instruct) — 前向推理、logits 获取、hidden states 提取、tokenize
+  - Tiny-NLA (LoRA + AR head) — 激活解释（已有）
+- **可做的计算**：
+  - 单个 token 的前向传播及 hidden states
+  - 任意层的 hidden state 投影到词表（logit lens 的核心操作）
+  - 梯度计算（需 backward）
+  - 两个向量的 cosine 相似度、L2 距离
+  - token 级别的概率获取
+- **做不到的**：
+  - 大规模 batch 训练（但我们的训练代码在 `experiments/tiny_nla/` 中，可以离线跑）
+  - 需要额外预训练模型的计算（除非把模型文件放到 `artifacts/` 下）
+
+**如果你设计了新接口，在 demo 中用 mock 数据即可。我们在后续实现阶段会在后端补上。**
+
+关键端点速查：
+- **Info Highlight** → 3.1 节 `POST /api/analyze` 响应
+- **Info Highlight 语义搜索** → 3.1 节 `POST /api/analyze-semantic` 响应
+- **Raw Chat** → 3.2 节 `POST /v1/completions` SSE 末条响应
+- **Attribution 梯度** → 3.3 节 `POST /api/prediction-attribute` 响应
+- **Attribution 消融** → 3.3 节 `POST /api/ablation-attribute` 响应
+- **Logit Lens** → 3.4 节 `POST /api/logit-lens` 响应（注意 layers 数组结构）
+- **Branch Tree** → 3.5 节 `POST /api/branch-next` 响应
+- **Causal Flow** → 3.6 节复合流程（tokenize + branch-next + prediction-attribute 串行）
+- **Tokenize** → 3.6.1 节 `POST /api/tokenize` 响应
+- **🆕 Activation Explainer** → 3.7 节 `POST /api/activation-explain` 响应
+
+---
+
+## 七、设计资源 & 参考
+
+### 设计灵感网站（自由参考）
+- **https://21st.dev/** — 现代 UI 组件灵感和设计模式
+- **https://cuicui.day/application-ui** — 应用 UI 设计参考
+- **https://ui.aceternity.com/** — 创新 UI 组件和动画效果
+
+### 本地设计仓库（内含设计规范）
+
+**[impeccable](https://github.com/pbakaus/impeccable)** — Anti-Design-Slop 检测器
+- `AGENTS.md` — 仓库规范和工作流
+- `DESIGN.md` — Neo Kinpaku 设计系统（暗色漆器 + 金箔 + 铜绿），包含完整的色彩、排版、圆角、间距 token 和组件规范（button、input、card、nav-link 等）
+- `CLAUDE.md` — Claude 专用的详细行为规范和交互模式
+- `docs/STYLE.md` — 风格指南
+- **核心哲学**：避免 AI 生成设计中的常见反模式（AI-purple gradients、三列等大 Feature Cards、过度 glassmorphism、无限循环微动画等）
+
+**[taste-skill](https://github.com/Leonxlnx/taste-skill)** — Anti-Slop 前端 Skill
+- `skills/taste-skill/SKILL.md` — 核心设计 Skill（85KB），包含：
+  - 「Read the Room」——先推断设计意图再动手
+  - 「三旋钮」系统（DESIGN_VARIANCE / MOTION_INTENSITY / VISUAL_DENSITY）从 1-10 控制视觉风格
+  - 设计系统映射表（何时用 Fluent UI / Material / Carbon / Primer / govuk-frontend / shadcn 等）
+  - 反默认纪律（避免 LLM 默认审美）
+- `skills/minimalist-skill/SKILL.md` — 极简风格
+- `skills/brutalist-skill/SKILL.md` — 粗野主义风格
+- `skills/soft-skill/SKILL.md` — 柔和风格
+- `skills/redesign-skill/SKILL.md` — 重设计方法论
+- `skills/stitch-skill/SKILL.md` — 设计缝合参考
+
+**建议在开始设计前，至少阅读 `impeccable/DESIGN.md` 和 `taste-skill/skills/taste-skill/SKILL.md` 以了解高质量设计的核心原则。**
+
+---
+
+## 八、交付要求
+
+### 必须包含
+1. **统一输入区**：一个文本框接受用户输入，tokenize 后展示为可交互的 token 序列
+2. **至少 3 种分析入口**：包括至少 Logit Lens、Attribution、Tiny-NLA Activation Explainer
+3. **多视图共存**：可以同时看到至少 2 种分析的输出（不互斥）
+4. **Token 选择交互**：点击 token 触发对应分析
+5. **Mock 数据**：用静态数据代替真实 API 响应
+
+### 不需要做的
+- 不需要对接真实后端 API
+- 不需要实现完整的 i18n
+- 不需要考虑 webpack 集成（独立 HTML 即可）
+- 不需要实现 Admin / Settings 功能
+
+### 交付物
+一个或多个独立的 HTML/CSS/JS 文件，可以在浏览器中直接打开运行。
+
+---
+
+## 九、自由发挥空间
+
+以下内容**完全由你决定**，不受任何限制：
+
+- 🎨 **视觉风格**：暗色/亮色、极简/丰富、任何配色方案
+- 🖼️ **布局方式**：面板/分屏/Tab/卡片网格/画布/任何创意布局
+- 🎬 **动效设计**：过渡/微交互/动画，完全自由
+- 📐 **交互模式**：点击/悬停/拖拽/快捷键/手势
+- 🏗️ **技术选型**：原生 CSS / Tailwind / 任何 CSS 框架 / 任何 JS 库
+- 📝 **文案风格**：技术性 / 产品化 / 趣味化，任意
+
+**唯一的要求是：看起来不像"又一个 AI 生成的 demo"，而是像一个真正有设计思考的产品。**

artifacts/tiny_nla/checkpoints/ar/best_ar_head.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af5e2021a16d78fce920c99559f4202e929ab7116b01d0c37c4986ffca3dbc1c
+size 4195637

artifacts/tiny_nla/checkpoints/av/README.md

@@ -0,0 +1,207 @@
+---
+base_model: Qwen/Qwen3-0.6B
+library_name: peft
+pipeline_tag: text-generation
+tags:
+- base_model:adapter:Qwen/Qwen3-0.6B
+- lora
+- transformers
+---
+
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+
+
+- **Developed by:** [More Information Needed]
+- **Funded by [optional]:** [More Information Needed]
+- **Shared by [optional]:** [More Information Needed]
+- **Model type:** [More Information Needed]
+- **Language(s) (NLP):** [More Information Needed]
+- **License:** [More Information Needed]
+- **Finetuned from model [optional]:** [More Information Needed]
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [More Information Needed]
+- **Paper [optional]:** [More Information Needed]
+- **Demo [optional]:** [More Information Needed]
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+[More Information Needed]
+
+### Downstream Use [optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+[More Information Needed]
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+[More Information Needed]
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+[More Information Needed]
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+[More Information Needed]
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+[More Information Needed]
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing [optional]
+
+[More Information Needed]
+
+
+#### Training Hyperparameters
+
+- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+#### Speeds, Sizes, Times [optional]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Model Examination [optional]
+
+<!-- Relevant interpretability work for the model goes here -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** [More Information Needed]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** [More Information Needed]
+- **Compute Region:** [More Information Needed]
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications [optional]
+
+### Model Architecture and Objective
+
+[More Information Needed]
+
+### Compute Infrastructure
+
+[More Information Needed]
+
+#### Hardware
+
+[More Information Needed]
+
+#### Software
+
+[More Information Needed]
+
+## Citation [optional]
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+[More Information Needed]
+
+**APA:**
+
+[More Information Needed]
+
+## Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+[More Information Needed]
+
+## More Information [optional]
+
+[More Information Needed]
+
+## Model Card Authors [optional]
+
+[More Information Needed]
+
+## Model Card Contact
+
+[More Information Needed]
+### Framework versions
+
+- PEFT 0.19.1

artifacts/tiny_nla/checkpoints/av/adapter_config.json

@@ -0,0 +1,43 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": null,
+  "base_model_name_or_path": "Qwen/Qwen3-0.6B",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 16,
+  "lora_bias": false,
+  "lora_dropout": 0.1,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "peft_type": "LORA",
+  "peft_version": "0.19.1",
+  "qalora_group_size": 16,
+  "r": 8,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": [
+    "q_proj",
+    "v_proj"
+  ],
+  "target_parameters": null,
+  "task_type": "CAUSAL_LM",
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false
+}

artifacts/tiny_nla/checkpoints/av/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c2bb9c1a38d1b11a5e99ed9c770bd08a16b5baa4277478f2925b7d839dafef7b
+size 4602248

artifacts/tiny_nla/checkpoints/av/added_tokens.json

@@ -0,0 +1,28 @@
+{
+  "</think>": 151668,
+  "</tool_call>": 151658,
+  "</tool_response>": 151666,
+  "<think>": 151667,
+  "<tool_call>": 151657,
+  "<tool_response>": 151665,
+  "<|box_end|>": 151649,
+  "<|box_start|>": 151648,
+  "<|endoftext|>": 151643,
+  "<|file_sep|>": 151664,
+  "<|fim_middle|>": 151660,
+  "<|fim_pad|>": 151662,
+  "<|fim_prefix|>": 151659,
+  "<|fim_suffix|>": 151661,
+  "<|im_end|>": 151645,
+  "<|im_start|>": 151644,
+  "<|image_pad|>": 151655,
+  "<|object_ref_end|>": 151647,
+  "<|object_ref_start|>": 151646,
+  "<|quad_end|>": 151651,
+  "<|quad_start|>": 151650,
+  "<|repo_name|>": 151663,
+  "<|video_pad|>": 151656,
+  "<|vision_end|>": 151653,
+  "<|vision_pad|>": 151654,
+  "<|vision_start|>": 151652
+}

artifacts/tiny_nla/checkpoints/av/chat_template.jinja

@@ -0,0 +1,89 @@
+{%- if tools %}
+    {{- '<|im_start|>system\n' }}
+    {%- if messages[0].role == 'system' %}
+        {{- messages[0].content + '\n\n' }}
+    {%- endif %}
+    {{- "# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>\n\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\n<tool_call>\n{\"name\": <function-name>, \"arguments\": <args-json-object>}\n</tool_call><|im_end|>\n" }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {{- '<|im_start|>system\n' + messages[0].content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
+{%- for message in messages[::-1] %}
+    {%- set index = (messages|length - 1) - loop.index0 %}
+    {%- if ns.multi_step_tool and message.role == "user" and message.content is string and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}
+        {%- set ns.multi_step_tool = false %}
+        {%- set ns.last_query_index = index %}
+    {%- endif %}
+{%- endfor %}
+{%- for message in messages %}
+    {%- if message.content is string %}
+        {%- set content = message.content %}
+    {%- else %}
+        {%- set content = '' %}
+    {%- endif %}
+    {%- if (message.role == "user") or (message.role == "system" and not loop.first) %}
+        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
+    {%- elif message.role == "assistant" %}
+        {%- set reasoning_content = '' %}
+        {%- if message.reasoning_content is string %}
+            {%- set reasoning_content = message.reasoning_content %}
+        {%- else %}
+            {%- if '</think>' in content %}
+                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
+                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
+            {%- endif %}
+        {%- endif %}
+        {%- if loop.index0 > ns.last_query_index %}
+            {%- if loop.last or (not loop.last and reasoning_content) %}
+                {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content.strip('\n') + '\n</think>\n\n' + content.lstrip('\n') }}
+            {%- else %}
+                {{- '<|im_start|>' + message.role + '\n' + content }}
+            {%- endif %}
+        {%- else %}
+            {{- '<|im_start|>' + message.role + '\n' + content }}
+        {%- endif %}
+        {%- if message.tool_calls %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if (loop.first and content) or (not loop.first) %}
+                    {{- '\n' }}
+                {%- endif %}
+                {%- if tool_call.function %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {{- '<tool_call>\n{"name": "' }}
+                {{- tool_call.name }}
+                {{- '", "arguments": ' }}
+                {%- if tool_call.arguments is string %}
+                    {{- tool_call.arguments }}
+                {%- else %}
+                    {{- tool_call.arguments | tojson }}
+                {%- endif %}
+                {{- '}\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {{- content }}
+        {{- '\n</tool_response>' }}
+        {%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+    {%- if enable_thinking is defined and enable_thinking is false %}
+        {{- '<think>\n\n</think>\n\n' }}
+    {%- endif %}
+{%- endif %}

artifacts/tiny_nla/checkpoints/av/special_tokens_map.json

@@ -0,0 +1,25 @@
+{
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "eos_token": {
+    "content": "<|im_end|>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "pad_token": "<|im_end|>"
+}

artifacts/tiny_nla/checkpoints/av/tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aeb13307a71acd8fe81861d94ad54ab689df773318809eed3cbe794b4492dae4
+size 11422654

artifacts/tiny_nla/checkpoints/av/tokenizer_config.json

@@ -0,0 +1,239 @@
+{
+  "add_bos_token": false,
+  "add_prefix_space": false,
+  "added_tokens_decoder": {
+    "151643": {
+      "content": "<|endoftext|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151644": {
+      "content": "<|im_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151645": {
+      "content": "<|im_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151646": {
+      "content": "<|object_ref_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151647": {
+      "content": "<|object_ref_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151648": {
+      "content": "<|box_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151649": {
+      "content": "<|box_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151650": {
+      "content": "<|quad_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151651": {
+      "content": "<|quad_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151652": {
+      "content": "<|vision_start|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151653": {
+      "content": "<|vision_end|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151654": {
+      "content": "<|vision_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151655": {
+      "content": "<|image_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151656": {
+      "content": "<|video_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "151657": {
+      "content": "<tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151658": {
+      "content": "</tool_call>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151659": {
+      "content": "<|fim_prefix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151660": {
+      "content": "<|fim_middle|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151661": {
+      "content": "<|fim_suffix|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151662": {
+      "content": "<|fim_pad|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151663": {
+      "content": "<|repo_name|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151664": {
+      "content": "<|file_sep|>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151665": {
+      "content": "<tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151666": {
+      "content": "</tool_response>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151667": {
+      "content": "<think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    },
+    "151668": {
+      "content": "</think>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": false
+    }
+  },
+  "additional_special_tokens": [
+    "<|im_start|>",
+    "<|im_end|>",
+    "<|object_ref_start|>",
+    "<|object_ref_end|>",
+    "<|box_start|>",
+    "<|box_end|>",
+    "<|quad_start|>",
+    "<|quad_end|>",
+    "<|vision_start|>",
+    "<|vision_end|>",
+    "<|vision_pad|>",
+    "<|image_pad|>",
+    "<|video_pad|>"
+  ],
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "extra_special_tokens": {},
+  "model_max_length": 131072,
+  "pad_token": "<|im_end|>",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null
+}

backend/api/activation_explain.py

@@ -0,0 +1,100 @@
+"""Activation Explainer API (Tiny-NLA)"""
+import gc
+import time
+
+import torch
+
+from backend.platform.oom import exit_if_oom
+from backend.api.analyze import LOCK_WAIT_TIMEOUT
+from backend.platform.access_log import get_client_ip, log_prediction_attribute_request
+from backend.platform.source_page import ALLOWED_SOURCE_PAGES, normalize_source_page
+from backend.core.tiny_nla import TinyNLAEngine, tiny_nla_lock, TINY_NLA_LOCK_TIMEOUT
+
+
+def activation_explain(activation_explain_request):
+    model = activation_explain_request.get("model")
+    source_page = activation_explain_request.get("source_page")
+    text = activation_explain_request.get("text")
+    token_index = activation_explain_request.get("token_index")
+    vector = activation_explain_request.get("vector")
+
+    if model is None:
+        return {"success": False, "message": "Missing required field: model"}, 400
+    if model not in ("base", "instruct"):
+        return {"success": False, "message": 'model must be "base" or "instruct"'}, 400
+
+    if source_page is None or source_page == "":
+        return {"success": False, "message": "Missing required field: source_page"}, 400
+    normalized_source_page = normalize_source_page(source_page)
+    if normalized_source_page is None:
+        allowed = ", ".join(sorted(ALLOWED_SOURCE_PAGES))
+        return {"success": False, "message": f"source_page must be one of: {allowed}"}, 400
+    source_page = normalized_source_page
+
+    has_text = isinstance(text, str) and text.strip() != ""
+    has_vector = isinstance(vector, list) and len(vector) > 0
+    if not has_text and not has_vector:
+        return {"success": False, "message": "Missing required field: text or vector must be provided"}, 400
+
+    if token_index is not None and not isinstance(token_index, int):
+        return {"success": False, "message": "token_index must be an integer"}, 400
+    if token_index is not None and token_index < 0:
+        return {"success": False, "message": "token_index must be >= 0"}, 400
+    if has_text and token_index is None:
+        return {"success": False, "message": "token_index is required when text is provided"}, 400
+
+    client_ip = get_client_ip()
+    start_time = time.perf_counter()
+    request_id = log_prediction_attribute_request(
+        context=text if has_text else str(vector)[:200],
+        target_prediction=None,
+        target_token_id=token_index,
+        model=model,
+        source_page=source_page,
+        flow_id=None,
+        flow_step=None,
+        client_ip=client_ip,
+    )
+
+    lock_acquired = tiny_nla_lock.acquire(timeout=TINY_NLA_LOCK_TIMEOUT)
+    if not lock_acquired:
+        return {"success": False, "message": f"Tiny-NLA queue wait exceeded {TINY_NLA_LOCK_TIMEOUT} seconds; please try again later."}, 503
+
+    try:
+        engine = TinyNLAEngine()
+
+        if has_vector:
+            activation = torch.tensor(vector, dtype=torch.float32)
+            if activation.shape[0] != 1024:
+                return {"success": False, "message": f"vector dimension must be 1024, got {activation.shape[0]}"}, 400
+        else:
+            activation = engine.extract_activation(text, token_index)
+
+        explanation = engine.explain(activation)
+        roundtrip_cosine = engine.reconstruct_cosine(activation, explanation)
+
+        result = {
+            "concept": "",
+            "explanation": explanation,
+            "roundtrip_cosine": round(roundtrip_cosine, 4),
+            "vector_dim": 1024,
+            "note": "",
+        }
+    except ValueError as e:
+        return {"success": False, "message": str(e)}, 400
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        exit_if_oom(e, defer_seconds=1)
+        return {"success": False, "message": str(e)}, 500
+    finally:
+        tiny_nla_lock.release()
+        gc.collect()
+
+    elapsed = time.perf_counter() - start_time
+    print(
+        f"\t📤 API activation_explain response: req_id={request_id}, "
+        f"concept={result.get('concept')!r}, roundtrip={result.get('roundtrip_cosine')}, "
+        f"response_time={elapsed:.4f}s"
+    )
+    return {"success": True, **result}, 200

backend/core/tiny_nla.py

@@ -0,0 +1,188 @@
+"""Tiny-NLA 引擎：LoRA + AR head 模型管理（lazy 单例）。
+
+职责：
+  - lazy 加载 Qwen/Qwen3-0.6B-Base（float32 + eager，对齐训练）+ LoRA adapter + AR head
+  - extract_activation(text, token_index) → layer 19 残差流
+  - explain(activation) → 注入激活 → generate → 自然语言解释
+  - reconstruct_cosine(activation, explanation) → AR head 重建 → cosine
+
+所有模型均独立加载（float32 + eager），不复用 base 槽（float16），确保与训练精度对齐。
+"""
+
+import threading
+import time
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+import yaml
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from backend.models.device import DeviceManager
+
+tiny_nla_lock = threading.Lock()
+TINY_NLA_LOCK_TIMEOUT = 30.0
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = REPO_ROOT / "experiments" / "tiny_nla" / "nla_meta.yaml"
+CHECKPOINT_DIR = REPO_ROOT / "artifacts" / "tiny_nla" / "checkpoints"
+AV_CHECKPOINT = CHECKPOINT_DIR / "av"
+AR_CHECKPOINT = CHECKPOINT_DIR / "ar" / "best_ar_head.pt"
+
+
+class TinyNLAEngine:
+    """LoRA + AR head 单例引擎。首次调用时 lazy 加载全部模型。"""
+
+    _instance = None
+    _init_done = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if self._init_done:
+            return
+        with open(SIDECAR_PATH, "r") as f:
+            self.meta = yaml.safe_load(f)
+
+        self.base_model_name = self.meta["base_model"]
+        self.av_model_name = self.meta["av_init_model"]
+        self.layer_idx = self.meta["layer_index"]
+        self.d_model = self.meta["d_model"]
+        self.inj_char = self.meta["tokens"]["injection_char"]
+        self.inj_token_id = self.meta["tokens"]["injection_token_id"]
+        self.inj_scale = self.meta["extraction"]["injection_scale"]
+
+        self.device = DeviceManager.get_device()
+        self.dtype = torch.float32
+
+        self._base_model = None
+        self._base_tokenizer = None
+        self._av_model = None
+        self._av_tokenizer = None
+        self._ar_head = None
+        self._init_done = True
+
+    def _ensure_loaded(self):
+        if self._base_model is not None:
+            return
+
+        t0 = time.perf_counter()
+        print(f"  [TinyNLA] Loading base ({self.base_model_name})...")
+        self._base_model = AutoModelForCausalLM.from_pretrained(
+            self.base_model_name,
+            trust_remote_code=True,
+            torch_dtype=self.dtype,
+            low_cpu_mem_usage=True,
+            attn_implementation="eager",
+        ).to(self.device)
+        self._base_model.eval()
+        self._base_tokenizer = AutoTokenizer.from_pretrained(
+            self.base_model_name, trust_remote_code=True
+        )
+        DeviceManager.print_model_load_stats(self._base_model, time.perf_counter() - t0)
+
+        t1 = time.perf_counter()
+        print(f"  [TinyNLA] Loading AV base ({self.av_model_name}) + LoRA...")
+        av_base = AutoModelForCausalLM.from_pretrained(
+            self.av_model_name,
+            trust_remote_code=True,
+            torch_dtype=self.dtype,
+            low_cpu_mem_usage=True,
+            attn_implementation="eager",
+        ).to(self.device)
+        self._av_model = PeftModel.from_pretrained(av_base, str(AV_CHECKPOINT))
+        self._av_model.eval()
+        self._av_tokenizer = AutoTokenizer.from_pretrained(
+            str(AV_CHECKPOINT), trust_remote_code=True
+        )
+        DeviceManager.print_model_load_stats(self._av_model, time.perf_counter() - t1)
+
+        if AR_CHECKPOINT.exists():
+            print(f"  [TinyNLA] Loading AR head...")
+            state = torch.load(
+                str(AR_CHECKPOINT), map_location=self.device, weights_only=True
+            )
+            if "linear.weight" in state:
+                state = {"weight": state["linear.weight"]}
+            self._ar_head = torch.nn.Linear(self.d_model, self.d_model, bias=False)
+            self._ar_head.load_state_dict(state)
+            self._ar_head.to(self.device)
+            self._ar_head.eval()
+        else:
+            print(f"  [TinyNLA] ⚠ AR checkpoint not found at {AR_CHECKPOINT}")
+            self._ar_head = None
+
+    def extract_activation(self, text: str, token_index: int) -> torch.Tensor:
+        """用 float32 base 模型提取 layer 19 残差流。"""
+        self._ensure_loaded()
+        inputs = self._base_tokenizer(text, return_tensors="pt").to(self.device)
+        seq_len = inputs["input_ids"].shape[1]
+        if token_index >= seq_len:
+            raise ValueError(f"token_index {token_index} out of range (seq_len={seq_len})")
+        with torch.no_grad():
+            outputs = self._base_model(**inputs, output_hidden_states=True, use_cache=False)
+        DeviceManager.synchronize(self.device)
+        activation = outputs.hidden_states[self.layer_idx][0, token_index, :].cpu()
+        return activation
+
+    def explain(self, activation: torch.Tensor, max_new_tokens: int = 64) -> str:
+        """注入激活向量 → generate → 返回 explanation 文本。"""
+        self._ensure_loaded()
+
+        prompt = f"<concept>{self.inj_char}</concept>\n<explanation>"
+        inputs = self._av_tokenizer(prompt, return_tensors="pt").to(self.device)
+
+        embeds = self._av_model.get_input_embeddings()(inputs["input_ids"])
+        inj_positions = (inputs["input_ids"][0] == self.inj_token_id).nonzero(as_tuple=True)[0]
+
+        if len(inj_positions) > 0:
+            inj_pos = inj_positions[0].item()
+            norm = activation.norm()
+            if norm > 0:
+                activation = activation / norm * self.inj_scale
+            scaled_act = activation.to(embeds.dtype).to(self.device)
+            embeds[0, inj_pos, :] = scaled_act
+
+        with torch.no_grad():
+            output_ids = self._av_model.generate(
+                inputs_embeds=embeds,
+                max_new_tokens=max_new_tokens,
+                do_sample=False,
+                pad_token_id=self._av_tokenizer.pad_token_id or self._av_tokenizer.eos_token_id,
+            )
+
+        DeviceManager.synchronize(self.device)
+
+        prompt_len_tokens = inputs["input_ids"].shape[1]
+        gen_token_ids = output_ids[0][prompt_len_tokens:]
+        explanation = self._av_tokenizer.decode(gen_token_ids, skip_special_tokens=True).strip()
+        return explanation
+
+    def reconstruct_cosine(self, activation: torch.Tensor, explanation: str) -> float:
+        """AR head 重建 → 计算 cosine。用 float32 base 模型提取 explanation 的 last hidden。"""
+        self._ensure_loaded()
+        if self._ar_head is None:
+            return 0.0
+
+        inputs = self._base_tokenizer(
+            explanation, return_tensors="pt", truncation=True, max_length=128
+        ).to(self.device)
+
+        with torch.no_grad():
+            outputs = self._base_model(**inputs, output_hidden_states=True, use_cache=False)
+            last_hidden = outputs.hidden_states[-1]
+            seq_len = inputs["attention_mask"].sum(dim=1) - 1
+            last_token_hidden = last_hidden[0, seq_len[0], :]
+
+            reconstructed = self._ar_head(last_token_hidden)
+
+        DeviceManager.synchronize(self.device)
+
+        orig_n = F.normalize(activation.unsqueeze(0).to(self.device), dim=-1)
+        recon_n = F.normalize(reconstructed.unsqueeze(0), dim=-1)
+        cosine = (orig_n * recon_n).sum(dim=-1).item()
+        return cosine

backend/platform/source_page.py

@@ -1,6 +1,6 @@
 """prediction_attribute API 的 source_page slug 规范化（含旧客户端兼容）。"""
 
-ALLOWED_SOURCE_PAGES = frozenset({"analysis", "chat", "attribution", "causal_flow"})
+ALLOWED_SOURCE_PAGES = frozenset({"analysis", "chat", "attribution", "causal_flow", "logit_lens"})
 
 
 def normalize_source_page(raw: str) -> str | None:

client/src/css/pages/logit_lens.scss

@@ -84,6 +84,54 @@
   margin-bottom: 4px;
 }
 
+// ---- Activation Explainer ----
+.ae-loading {
+  font-size: 9pt;
+  color: var(--text-muted);
+  padding: 12px 0;
+  text-align: center;
+}
+
+.ae-result {
+  margin-top: 8px;
+}
+
+.ae-field {
+  margin-bottom: 8px;
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+}
+
+.ae-label {
+  font-size: 10pt;
+  font-weight: 600;
+  color: var(--text-secondary);
+  min-width: 48px;
+  flex-shrink: 0;
+}
+
+.ae-value {
+  font-size: 10pt;
+  color: var(--text-primary);
+  line-height: 1.5;
+}
+
+.ae-cosine {
+  font-weight: 700;
+  font-size: 11pt;
+  &.cosine-excellent { color: #16a34a; }
+  &.cosine-good      { color: #2563eb; }
+  &.cosine-fair      { color: #d97706; }
+  &.cosine-low       { color: #dc2626; }
+}
+
+.ae-error {
+  font-size: 9pt;
+  color: #dc2626;
+  padding: 8px 0;
+}
+
 // ---- 层卡片 ----
 .ll-layer-card {
   margin-top: 12px;

client/src/logit_lens.html

@@ -84,6 +84,16 @@
                     </div>
                 </section>
             </div>
+
+            <div class="logit-lens-panel" id="ae_panel" style="display:none;">
+                <div class="attribution-panel-label">Activation Explainer / 激活解释</div>
+                <div id="ae_loading" class="ae-loading" style="display:none">🧠 正在推理... 激活解释需要较长时间（约 5-15 秒）</div>
+                <div id="ae_result" class="ae-result" style="display:none">
+                    <div class="ae-field"><span class="ae-label">解释</span><span id="ae_explanation" class="ae-value"></span></div>
+                    <div class="ae-field"><span class="ae-label">可信度</span><span id="ae_cosine" class="ae-cosine"></span><span>&nbsp;(roundtrip cosine)</span></div>
+                </div>
+                <div id="ae_error" class="ae-error" style="display:none"></div>
+            </div>
         </section>
 
         <div class="resizer" id="resizer"></div>

client/src/pages/logit_lens/index.ts

@@ -16,7 +16,7 @@ import { showAlertDialog } from '../../shared/ui/dialog';
 import URLHandler from '../../shared/core/URLHandler';
 import { createToast } from '../../shared/ui/toast';
 import { translateApiErrorMessage } from '../../shared/core/errorUtils';
-import type { LogitLensResult, LogitLensLayer } from '../../shared/api/GLTR_API';
+import type { LogitLensResult, LogitLensLayer, ActivationExplainResult } from '../../shared/api/GLTR_API';
 import { lsReadEnum, lsWriteString } from '../../shared/storage/localStorageHelpers';
 
 d3.selectAll('.loadersmall').style('display', 'none');
@@ -355,6 +355,61 @@ function renderLayerCard(): void {
     </div>`;
 }
 
+// --- Activation Explainer ---
+async function runActivationExplain(context: string, targetToken: string): Promise<void> {
+    const panel = document.getElementById('ae_panel');
+    const loading = document.getElementById('ae_loading');
+    const result = document.getElementById('ae_result');
+    const errEl = document.getElementById('ae_error');
+    if (!panel || !loading || !result || !errEl) return;
+
+    panel.style.display = 'block';
+    loading!.style.display = '';
+    result.style.display = 'none';
+    errEl.style.display = 'none';
+
+    try {
+        // 1) tokenize 找出 target token 的 index
+        const tok = await api.tokenize(context, currentModelVariant());
+        const spans = tok?.spans ?? [];
+        let tokenIndex = -1;
+        for (let i = 0; i < spans.length; i++) {
+            if (spans[i].raw === targetToken) { tokenIndex = i; break; }
+        }
+        if (tokenIndex < 0) {
+            // fallback：取最后一个 token
+            tokenIndex = spans.length - 1;
+        }
+
+        // 2) call activation-explain
+        const ae = await api.explainActivation(currentModelVariant(), 'logit_lens', context, tokenIndex);
+        if (!ae.success) {
+            errEl.textContent = ae.message || tr('Activation explain failed');
+            errEl.style.display = '';
+            return;
+        }
+
+        // 3) render
+        const cosine = ae.roundtrip_cosine ?? 0;
+        let cls = 'cosine-low';
+        if (cosine >= 0.70) cls = 'cosine-excellent';
+        else if (cosine >= 0.60) cls = 'cosine-good';
+        else if (cosine >= 0.50) cls = 'cosine-fair';
+        const cosineHtml = `<span class="ae-cosine ${cls}">${(cosine * 100).toFixed(1)}%</span>`;
+
+        const explanationEl = document.getElementById('ae_explanation');
+        const cosineEl = document.getElementById('ae_cosine');
+        if (explanationEl) explanationEl.textContent = ae.explanation ?? '';
+        if (cosineEl) cosineEl.innerHTML = cosineHtml;
+        result.style.display = '';
+    } catch (err: unknown) {
+        errEl.textContent = (err instanceof Error ? err.message : String(err));
+        errEl.style.display = '';
+    } finally {
+        loading!.style.display = 'none';
+    }
+}
+
 // --- 主分析逻辑 ---
 async function runAnalyze(): Promise<void> {
     const context = (contextField.node() as HTMLTextAreaElement | null)?.value ?? '';
@@ -369,6 +424,11 @@ async function runAnalyze(): Promise<void> {
             lastCommittedInputs = { context, target };
             const info = `${tr('model')}: ${ll.model ?? '–'}\n${tr('Target token')}: ${ll.target_token ?? '–'}\n${tr('Final prob')}: ${(ll.final_target_prob * 100).toFixed(1)}%\n${tr('Layers')}: ${ll.n_layers ?? '–'}`;
             resultInfoEl.classed('is-hidden', false).text(info);
+
+            // 自动触发 Activation Explainer
+            if (context && ll.target_token) {
+                void runActivationExplain(context, ll.target_token);
+            }
         } else {
             showAlertDialog(tr('Logit Lens'), ll.message || tr('Analysis failed'));
         }

client/src/shared/api/GLTR_API.ts

@@ -102,6 +102,16 @@ export type BranchNextResult = {
     message?: string;
 };
 
+export type ActivationExplainResult = {
+    success: boolean;
+    concept?: string;
+    explanation?: string;
+    roundtrip_cosine?: number;
+    vector_dim?: number;
+    note?: string;
+    message?: string;
+};
+
 export class TextAnalysisAPI {
     private adminToken: string | null = null;
 
@@ -504,6 +514,51 @@ export class TextAnalysisAPI {
         return data as BranchNextResult;
     }
 
+    /**
+     * Tokenize：将文本分词为 token spans。
+     */
+    public async tokenize(
+        context: string,
+        model: string,
+        signal?: AbortSignal
+    ): Promise<{ success: boolean; spans: Array<{ offset: [number, number]; raw: string; token_id?: number }> }> {
+        const res = await fetch(this.baseURL + '/api/tokenize', {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ context, model }),
+            signal
+        });
+        const data = await res.json();
+        if (data && data.success === false) {
+            throw new Error(data.message || 'Tokenize failed');
+        }
+        return data;
+    }
+
+    /**
+     * Activation Explainer (Tiny-NLA)：解释激活向量的概念语义。
+     */
+    public async explainActivation(
+        model: string,
+        sourcePage: string,
+        text: string,
+        tokenIndex: number,
+        signal?: AbortSignal
+    ): Promise<ActivationExplainResult> {
+        const bodyObj: Record<string, unknown> = { model, source_page: sourcePage, text, token_index: tokenIndex };
+        const res = await fetch(this.baseURL + '/api/activation-explain', {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(bodyObj),
+            signal
+        });
+        const data = await res.json();
+        if (data && data.success === false) {
+            throw new Error(data.message || 'Activation explain failed');
+        }
+        return data as ActivationExplainResult;
+    }
+
     /**
      * 使用SSE流式分析文本，支持进度回调（内部方法）
      */

client/src/shared/lang/translations.ts

@@ -512,5 +512,10 @@ export const translations: Translations = {
         'which input tokens drove this prediction? Gradient scores each context token by how much changing it would shift the output probability.': '哪些输入词推动了这个预测？梯度法通过计算每个 token 对输出概率的扰动敏感度，量化其贡献。',
         'applies the final output layer to each intermediate layer, revealing how the model\'s prediction takes shape across depth — early layers guess, later layers converge.': '将最终输出层应用于每个中间层，揭示预测如何随深度逐步成型——浅层在猜测，深层在收敛。',
         'shows the model\'s top-k next-token candidates at each step as an interactive tree — revealing how probability mass spreads across possible continuations.': '将每一步的 top-k 候选词展开为可交互树，揭示概率质量如何在可能的续写路径间分布。',
+
+        // ---- Activation Explainer ----
+        'Activation Explainer': '激活解释',
+        'Activation explain failed': '激活解释失败',
+        'Loading activation explanation…': '正在推理激活解释…',
     }
 };

experiments/tiny_nla/PLAN_v2.md

@@ -0,0 +1,406 @@
+# Tiny NLA v2 Implementation Plan
+
+> 目标：修复三个关键问题，让 Tiny NLA 项目从「SFT 概念验证」升级到「符合 Anthropic NLA 方案的完整训练闭环」
+
+## 问题总览
+
+| 优先级 | 问题 | 当前状态 | 目标状态 |
+|:------:|------|----------|----------|
+| P0 | 缺少 RL（GRPO）训练循环 | 只有 SFT，没有 RL | 实现 AV+AR 联合 GRPO RL，reward = `-mse_nrm` |
+| P0 | Teacher label 带了太多辅助信息 | prompt 包含 context、top_tokens、pos 等 | 简化到仅依赖激活向量本身的信息 |
+| P1 | 数据量太小（1461 vs 1M） | 22 条句子，284→1461 records | 扩大到 ≥10K 条 records |
+
+---
+
+## Phase 0: 数据扩容（P1 — 数据量）
+
+> **依赖**：无，可独立进行
+> **预计耗时**：4-6 小时（大部分是 API 调用等待时间）
+
+### Step 0.1: 扩大语料库到 ≥500 条句子
+
+**文件**：`experiments/tiny_nla/expand_dataset_v2.py`（新文件）
+
+当前 `expand_dataset.py` 用 15 个领域生成 ~300 条句子。需要扩大到 500+ 条。
+
+**策略**：
+- 扩展领域列表到 30+ 个（增加：心理学、心理学、编程技术、数学逻辑、影视娱乐、宗教信仰、语言语言学、艺术美学、交通出行、宠物动物、天气气候、金融投资、职场沟通）
+- 每个领域生成 20-30 条
+- 用 opencode CLI 并发批量生成（参考现有 `batch_teacher_labels.py` 的并发模式）
+- 增加句子多样性：短句（8-15字）、中等句（15-30字）、长句（30-50字）
+
+**输出**：`artifacts/tiny_nla/expanded_texts_v2.json`（500+ 条句子）
+
+### Step 0.2: 提取全部激活向量
+
+**文件**：`experiments/tiny_nla/generate_data_v2.py`（新文件，基于现有 `generate_data.py`）
+
+- 加载 Qwen3-0.6B-Base
+- 对 500+ 条句子做 forward pass，提取 layer 19 的残差流
+- 每条句子每个 token 都提取（不需要过滤）
+- 保存为 parquet 格式（与 Anthropic NLA 对齐）
+
+**输出**：`artifacts/tiny_nla/activations_v2.parquet`
+
+**预估**：500 条句子 × ~15 tokens/句 = ~7,500 activation records。以 0.6B 模型在 M4 Pro 上，forward pass 极快（<5 分钟全部完成）。
+
+### Step 0.3: 过滤 OOD 样本
+
+- 去掉 activation_norm > 2000 的首 token（与现有做法一致）
+- 去掉 norm < 50 的异常低激活（可能是 padding/特殊 token）
+- 预估保留 ~7,000 条 in-distribution records
+
+---
+
+## Phase 1: Teacher Label 重做（P0 — 辅助信息）
+
+> **依赖**：Phase 0 完成后的数据
+> **预计耗时**：8-12 小时（API 调用）
+
+### Step 1.1: 设计简化版 Teacher Prompt
+
+**核心原则**：NLA 的目标是让 AV **仅从激活向量**推断语义。Teacher label 的训练数据不应包含 AV 运行时看不到的信息。
+
+**Anthropic 方案对比**：
+Anthropic 的 teacher 生成用的是 **Claude 看 activation 向量的投影/统计信息**，不附带原始句子或 top_tokens。
+
+**新 prompt 设计**：
+
+```
+你是一个语言模型内部机制分析专家。我给你一段来自 Qwen3-0.6B 模型（layer 19，residual stream）
+在某 token 位置的激活向量信息，请你推断这个位置编码了什么语义。
+
+激活向量统计信息：
+- L2 norm: {norm}
+- 与平均激活方向的余弦相似度: {cosine_with_mean}
+- 该位置在序列中的相对位置: {relative_pos}（0=开头, 1=末尾）
+
+请用1-2句简洁中文描述你认为这个位置编码的语义信息。
+要求：简洁具体，不超过55字，只输出解释本身。
+```
+
+**关键变化**：
+- ❌ 去掉原始句子文本（context）
+- ❌ 去掉 top_tokens（模型预测候选）
+- ❌ 去掉 token_text（当前 token 文本）
+- ✅ 只给激活向量的**统计特征**（norm、方向、相对位置）
+- ✅ 这些信息 AV 在推理时可以通过注入的向量获得
+
+**为什么可以去掉 context/top_tokens**：
+- Anthropic 的论文明确指出，NLA 的核心价值在于**从向量本身推断语义**
+- 如果 teacher 依赖了上下文，AV 就不需要学会「读懂向量」，而是学会了「从 prompt 里偷看上下文」
+- RL 训练时，reward 只看「向量→文本→向量」的 roundtrip 质量，上下文信息不会被注入
+
+### Step 1.2: 批量生成简化版 Teacher Labels
+
+**文件**：`experiments/tiny_nla/generate_teacher_labels_v2.py`（新文件）
+
+**API 方案：双通道并发**
+
+为最大化吞吐量，同时使用两个免费 API 通道：
+
+| 通道 | API | 模型 | 并发数 | 特点 |
+|------|-----|------|:------:|------|
+| 通道 A | opencode CLI | deepseek-v4-flash-free | 4 workers | 本地 CLI 调用，已在用 |
+| 通道 B | NVIDIA API | deepseek-ai/deepseek-v4-pro | 8-10 concurrent | 直接 HTTP API，更快更强 |
+
+**NVIDIA API 配置**：
+```python
+from openai import OpenAI
+
+nvidia_client = OpenAI(
+    base_url="https://integrate.api.nvidia.com/v1",
+    api_key=os.environ.get("NVIDIA_API_KEY", ""),
+)
+# model: "deepseek-ai/deepseek-v4-pro"
+# thinking=False → 直接输出，不需要等思考过程
+# max_tokens=256 足够（teacher label ≤55字）
+```
+
+**并发策略**：
+- opencode CLI：4 个 subprocess worker（需要达到 free tier 并发上限，我不确定4个是否是上限）
+- NVIDIA API：8-10 个 asyncio concurrent request（NVIDIA free tier 通常允许较高并发）
+- **总计 12-14 个并发请求**，吞吐量提升约 3 倍
+
+**优势对比**：
+| 方案 | 速度 | 模型质量 | 成本 |
+|------|------|---------|------|
+| opencode CLI (flash-free) | ~3-5 秒/条 | DeepSeek V4 Flash | 免费 |
+| NVIDIA API (v4-pro) | ~2-3 秒/条 | DeepSeek V4 Pro（更强） | 免费 |
+| **双通道合计** | **~12-14 条/分钟** | 混合质量 | **免费** |
+
+**容错与 checkpoint**：
+- 每 100 条保存 checkpoint（JSON 文件）
+- 两个通道的结果合并写入同一个文件
+- 支持 `--skip-existing`，中断后重启自动跳过已完成
+- NVIDIA API 失败时自动重试 3 次，最终 fallback 到 opencode
+
+**预估**：7000 条 ÷ 20 条/分钟 = **~6 小时**（比纯 opencode 方案快 ~5 倍）
+
+**输出**：`artifacts/tiny_nla/teacher_labels_v2.json`
+
+### Step 1.3: 质量检查
+
+- 检查是否有空输出或幻觉（声称上下文包含某些不存在的内容）
+- 剔除长度 > 55 字的过长解释
+- 剔除明显泛泛而谈的解释（如「编码了关键语义信息」「是核心语义单元」等套话）
+- 统计剩余有效 label 数量
+
+---
+
+## Phase 2: SFT 重训（基于新数据）
+
+> **依赖**：Phase 0 + Phase 1
+> **预计耗时**：30-40 分钟
+
+### Step 2.1: AR SFT 重训
+
+**文件**：修改现有 `train_ar.py`
+
+- 使用新数据（Phase 0 的 7K+ records + Phase 1 的 teacher labels）
+- AR 输入：teacher explanation text
+- AR 输出：L2-normalized activation vector
+- Loss: MSE on L2-normalized vectors
+- 增加 train/val split (90/10)
+- 训练 5-10 epochs，early stopping on val loss
+
+**基线**：
+- Mean baseline（永远预测均值方向）
+- Shuffled baseline（随机配对 explanation→activation）
+
+### Step 2.2: AV SFT 重训
+
+**文件**：修改现有 `train_av.py`
+
+- 使用新数据
+- AV 输入：injected activation vector (injection token ㈎)
+- AV 输出：teacher explanation text
+- LoRA 微调 Qwen3-0.6B Instruct
+- 增加数据量到 7K+ 条，训练更长
+
+**验证**：AV→AR roundtrip cosine 应 > 0.6（Anthropic 的 7B 模型达到 ~0.75）
+
+---
+
+## Phase 3: GRPO RL 训练（P0 — RL 循环）
+
+> **依赖**：Phase 2 完成后的 SFT checkpoints
+> **预计耗时**：8-12 小时
+> **这是最关键的新增部分**
+
+### Step 3.1: 设计 GRPO RL 训练框架
+
+**文件**：`experiments/tiny_nla/train_rl_grpo.py`（新文件）
+
+**GRPO（Group Relative Policy Optimization）核心逻辑**：
+
+```
+对于每个 training batch:
+  1. 从数据集取一批 activation vectors
+  2. 用 AV 对每个 vector 生成 K 个候选解释（K=4，不同采样策略）
+  3. 用 AR 对每个候选解释还原向量
+  4. 计算 reward = -mse_nrm(reconstructed, original)
+     其中 mse_nrm = MSE(L2_norm(original), L2_norm(reconstructed))
+  5. 在 K 个候选中，用相对排名做 advantage:
+     advantage_i = (reward_i - mean(rewards_group)) / std(rewards_group)
+  6. 用 advantage 加权 AV 的 policy gradient loss
+  7. 同时 AR 继续做 supervised MSE loss（保持 AR 能力不退化）
+```
+
+### Step 3.2: 内存管理策略（适配 M4 Pro 48GB）
+
+**策略：逐模型加载（sequential rollout）**
+
+```python
+class RLTrainer:
+    def __init__(self):
+        # 不一次性加载所有模型
+        # 按需加载/卸载
+        
+    def rollout_phase(self, activations):
+        """Step 1: 加载 Target + AV，生成候选解释"""
+        self._load_target_and_av()  # ~2.4GB
+        candidates = []
+        for act in activations:
+            for k in range(GROUP_SIZE):
+                explanation = self.av.generate(act, temperature=0.7 + k*0.1)
+                candidates.append((act, explanation))
+        self._unload_av()
+        return candidates
+    
+    def reward_phase(self, candidates):
+        """Step 2: 加载 AR，计算 reward"""
+        self._load_ar()  # ~1.2GB
+        rewards = []
+        for act, explanation in candidates:
+            reconstructed = self.ar.reconstruct(explanation)
+            mse = mse_nrm(act, reconstructed)
+            rewards.append(-mse)
+        self._unload_ar()
+        return rewards
+    
+    def update_phase(self, candidates, rewards, advantages):
+        """Step 3: 加载 AV，做 GRPO policy gradient update"""
+        self._load_av_with_grad()  # ~2.4GB + optimizer states
+        self.av.grpo_update(candidates, advantages)
+        self._unload_av()
+```
+
+**内存峰值**：每次只加载 1-2 个模型，峰值 ~8-12GB，远低于 48GB 限制。
+
+### Step 3.3: MPS 适配细节
+
+- 使用 `float32`（MPS 不完全支持 bf16 训练）
+- 遇到 MPS 不支持的 op 时，fallback 到 CPU
+- `torch.no_grad()` 包裹所有 inference phase
+- 定期 `torch.mps.empty_cache()` ���理缓存
+- 生成时用 `do_sample=True, temperature=0.7` 产生多样性
+
+### Step 3.4: 训练超参数
+
+```yaml
+# RL 训练配置
+group_size: 4          # 每个 activation 生成 4 个候选解释
+batch_size: 8          # 每批 8 个 activations
+learning_rate: 1e-5    # AV LoRA 学习率（比 SFT 小）
+ar_learning_rate: 1e-4 # AR head 学习率
+num_steps: 1000        # RL 训练步数
+max_new_tokens: 64     # AV 生成最大 token 数
+temperature_range: [0.7, 0.8, 0.9, 1.0]  # K 个候选的温度
+eval_interval: 50      # 每 50 步评估一次
+save_interval: 100     # 每 100 步保存 checkpoint
+```
+
+### Step 3.5: 评估指标
+
+每 `eval_interval` 步，计算：
+- **Roundtrip cosine**：AV→AR 的还原质量（越高越好）
+- **Roundtrip MSE**：越小越好
+- **Explanation quality**：解释的平均长度、多样性
+- **Baselines**：
+  - Mean direction baseline cosine
+  - SFT-only baseline（不经过 RL 的 AV+AR cosine）
+  - Shuffled baseline
+
+### Step 3.6: 训练流程图
+
+```mermaid
+flowchart TD
+    A["Phase 2: SFT Checkpoints"] --> B["加载 Target Model<br/>Qwen3-0.6B-Base frozen"]
+    B --> C["Rollout: AV 生成 K=4 候选解释"]
+    C --> D["Reward: AR 还原向量<br/>计算 -mse_nrm"]
+    D --> E["Advantage: 组内相对排名"]
+    E --> F["Update: AV GRPO policy gradient"]
+    F --> G["AR: supervised MSE update"]
+    G --> H{"每 50 步评估"}
+    H -->|"roundtrip cosine 提升"| I["继续训练"]
+    H -->|"收敛或退化"| J["Early stop"]
+    I --> C
+    J --> K["保存最佳 checkpoint"]
+```
+
+---
+
+## Phase 4: 最终评估与验证
+
+> **依赖**：Phase 3 完成
+> **预计耗时**：30 分钟
+
+### Step 4.1: 完整 Roundtrip 评估
+
+**文件**：修改现有 `eval_roundtrip.py`
+
+- 用最终 RL checkpoint 做 roundtrip 评估
+- 对比 SFT-only 和 RL 版本
+- 计算完整指标表：
+
+| 指标 | SFT-only | RL (GRPO) | 目标 |
+|------|----------|-----------|------|
+| Roundtrip cosine | 0.60 (current) | > 0.65 | > 0.70 |
+| Roundtrip MSE | 0.80 | < 0.60 | < 0.50 |
+| Mean baseline cosine | 0.60 | - | - |
+| Shuffled baseline cosine | 0.53 | - | - |
+
+### Step 4.2: 人类评估
+
+- 取 20 个随机 activation，展示 AV 解释
+- 人工判断解释是否合理、是否与该位置的语义相关
+- 记录幻觉率（解释中声称上下文包含某些不存在的内容的比例）
+
+### Step 4.3: 更新 Demo
+
+- 用 RL 版本的 AV 模型更新 demo.html
+- 对比展示 SFT vs RL 的解释质量差异
+
+---
+
+## 文件清单（新增/修改）
+
+| 文件 | 状态 | 说明 |
+|------|------|------|
+| `expand_dataset_v2.py` | 新增 | Phase 0.1：扩大语料库 |
+| `generate_data_v2.py` | 新增 | Phase 0.2：提取激活向量（parquet） |
+| `generate_teacher_labels_v2.py` | 新增 | Phase 1.2：简化版 teacher label |
+| `train_ar.py` | 修改 | Phase 2.1：适配新数据格式 |
+| `train_av.py` | 修改 | Phase 2.2：适配新数据格式 |
+| `train_rl_grpo.py` | 新增 | Phase 3：GRPO RL 训练 |
+| `eval_roundtrip.py` | 修改 | Phase 4：完整评估 |
+| `nla_meta.yaml` | 修改 | 更新训练配置记录 |
+
+---
+
+## 时间估算总览
+
+| Phase | 内容 | 预计耗时 |
+|:------:|------|----------|
+| 0 | 数据扩容 | 4-6 小时 |
+| 1 | Teacher label 重做（三通道 API） | **~6 小时** |
+| 2 | SFT 重训 | 30-40 分钟 |
+| 3 | GRPO RL | 8-12 小时 |
+| 4 | 评估 | 30 分钟 |
+| **总计** | | **~19-25 小时** |
+
+大部分时间是 API 调用等待（Phase 1）和 RL 训练迭代（Phase 3），代码编写本身只需 2-3 小时。
+
+---
+
+## 风险与缓解
+
+| 风险 | 影响 | 缓解方案 |
+|------|------|---------|
+| MPS 不支持某些 op | RL 训练 crash | fallback CPU + 测试 smoke case |
+| 0.6B 模型太小，roundtrip cosine 无法提升到 >0.65 | RL 收益有限 | 先跑一轮看 baseline gap；如果 SFT cosine 已经很低则 RL 空间有限 |
+| 简化版 teacher label 质量差（没有上下文辅助） | AV SFT 起点太低 | 可保留一个"半简化"版本作为对照：给 norm + top_tokens 但不给原文 |
+| NVIDIA API rate limit / key 过期 | 生成速度降低 | fallback 到其他通道；API key 安全存储在 .env |
+| OpenRouter free tier rate limit | nex-n2-pro:free 并发受限 | 降低并发数；fallback 到 NVIDIA/opencode |
+| opencode CLI 并发上限 | 无法同时调太多 | 已达到 4 workers 上限，NVIDIA + OpenRouter 补充并发 |
+
+---
+
+## API Key 安全策略
+
+所有 API key 存储在 `.env` 文件中（不硬编码到代码）：
+
+```bash
+# InfoLens/.env 文件（不纳入 git，已在 .gitignore 中）
+NVIDIA_API_KEY=<your-key-here>
+OPENROUTER_API_KEY=<your-key-here>
+```
+
+代码中通过 `os.environ.get()` 或 `python-dotenv` 读取：
+```python
+from dotenv import load_dotenv
+load_dotenv()  # 自动加载 .env
+nvidia_key = os.environ.get("NVIDIA_API_KEY")
+openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+```
+
+---
+
+## API Key 安全策略
+
+NVIDIA API key 不应硬编码在代码中，而是：
+- 存储在 `.env` 文件中：`NVIDIA_API_KEY=nvapi-...`
+- 代码中通过 `os.environ.get("NVIDIA_API_KEY")` 读取
+- `.env` 文件不纳入 git（已在 `.gitignore` 中）
+- Plan 文档中只记录使用方式，不记录完整 key |

experiments/tiny_nla/batch_teacher_labels.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Batch teacher label generation via opencode (parallel workers).
+Usage: python batch_teacher_labels.py [--workers 3]
+"""
+import json, subprocess, sys, time, argparse
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+ARTIFACTS = Path(__file__).resolve().parents[2] / "artifacts" / "tiny_nla"
+RECORDS_FILE = ARTIFACTS / "expanded_records.jsonl"
+OUTPUT = ARTIFACTS / "expanded_teacher_labels.json"
+MODEL = "opencode/deepseek-v4-flash-free"
+
+PROMPT = """\
+你是语言模型内部机制分析专家。用1-2句简洁中文描述Qwen3-0.6B在处理下面这个token时，该位置residual stream激活值编码的语义信息。
+
+上下文：{context}
+当前token：「{token}」（位置{pos}/{seq_len}）
+模型预测下一个词的候选：{top_tokens}
+
+要求：简洁具体，联系token在句中的实际句法/语义角色，联系预测候选推断编码内容，不超过55字。只输出解释本身。"""
+
+
+def call_opencode(record: dict) -> str:
+    prompt = PROMPT.format(
+        context=record["text"],
+        token=record["token_text"],
+        pos=record["pos"],
+        seq_len=record["seq_len"],
+        top_tokens="、".join(record["top_tokens"][:5]),
+    )
+    r = subprocess.run(
+        ["opencode", "run", "--model", MODEL, prompt],
+        capture_output=True, text=True, timeout=90,
+    )
+    lines = r.stdout.splitlines()
+    content = [l.strip() for l in lines
+               if l.strip()
+               and not l.strip().startswith("\x1b")
+               and "orchestrator" not in l
+               and not l.strip().startswith("{")
+               and not l.strip().startswith('"message"')]
+    return "\n".join(content).strip()
+
+
+def process_record(idx_rec):
+    idx, rec = idx_rec
+    try:
+        expl = call_opencode(rec)
+        # Strip think blocks
+        if "<think>" in expl and "</think>" in expl:
+            expl = expl.split("</think>")[-1].strip()
+        return idx, {**rec, "teacher_explanation": expl, "teacher_source": "opencode/deepseek-v4-flash-free"}
+    except Exception as e:
+        return idx, None
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--workers", type=int, default=3)
+    parser.add_argument("--limit", type=int, default=None)
+    args = parser.parse_args()
+
+    with open(RECORDS_FILE) as f:
+        records = [json.loads(l) for l in f]
+
+    if args.limit:
+        records = records[:args.limit]
+
+    # Load existing
+    existing = {}
+    if OUTPUT.exists():
+        with open(OUTPUT) as f:
+            for item in json.load(f):
+                existing[(item["text_idx"], item["pos"])] = item
+    print(f"Records: {len(records)}, existing labels: {len(existing)}")
+
+    todo = [(i, r) for i, r in enumerate(records)
+            if (r["text_idx"], r["pos"]) not in existing]
+    print(f"To process: {len(todo)}")
+
+    results = dict(existing)
+    done = 0
+
+    with ThreadPoolExecutor(max_workers=args.workers) as pool:
+        futures = {pool.submit(process_record, item): item for item in todo}
+        for fut in as_completed(futures):
+            idx, result = fut.result()
+            if result:
+                results[(result["text_idx"], result["pos"])] = result
+            done += 1
+            if done % 50 == 0 or done == len(todo):
+                # Checkpoint save
+                with open(OUTPUT, "w", encoding="utf-8") as f:
+                    json.dump(list(results.values()), f, ensure_ascii=False, indent=2)
+                print(f"  [{done}/{len(todo)}] saved {len(results)} labels")
+
+    with open(OUTPUT, "w", encoding="utf-8") as f:
+        json.dump(list(results.values()), f, ensure_ascii=False, indent=2)
+    print(f"\nDone: {len(results)} teacher labels → {OUTPUT}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/eval_final.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Final model evaluation: SFT vs RL roundtrip cosine on 100 random samples."""
+import os, yaml, random, argparse
+from datetime import datetime
+
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ.setdefault("HF_DATASETS_OFFLINE", "1")
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import pyarrow.parquet as pq
+from pathlib import Path
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+# Paths
+REPO_ROOT  = Path(__file__).resolve().parents[2]
+ARTIFACTS  = REPO_ROOT / "artifacts" / "tiny_nla"
+META       = yaml.safe_load(open(Path(__file__).resolve().parent / "nla_meta.yaml"))
+D_MODEL    = META["d_model"]
+INJ_CHAR   = META["tokens"]["injection_char"]
+INJ_TOK_ID = META["tokens"]["injection_token_id"]
+INJ_SCALE  = META["extraction"]["injection_scale"]
+BASE_MODEL = META["base_model"]
+INST_MODEL = META["av_init_model"]
+
+
+class ARHead(nn.Module):
+    def __init__(self, d): super().__init__(); self.proj = nn.Linear(d, d, bias=False)
+    def forward(self, h): return F.normalize(self.proj(h), dim=-1)
+
+
+def tprint(s): print(f"[{datetime.now().strftime('%H:%M:%S')}] {s}", flush=True)
+
+
+def load_activations():
+    t = pq.read_table(ARTIFACTS / "activations_v2.parquet")
+    acts = torch.tensor([t["activation"][i].as_py() for i in range(len(t))], dtype=torch.float32)
+    tprint(f"Loaded {len(acts)} activations")
+    return acts
+
+
+def load_av_model(path, device):
+    tprint(f"Loading AV from {path}...")
+    tok = AutoTokenizer.from_pretrained(INST_MODEL)
+    base = AutoModelForCausalLM.from_pretrained(
+        INST_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(device)
+    model = PeftModel.from_pretrained(base, path)
+    model.eval()
+    return model, tok
+
+
+def load_ar(device):
+    ckpt = torch.load(ARTIFACTS / "checkpoints" / "ar_v2" / "ar_head_v2.pt",
+                      map_location=device, weights_only=True)
+    head = ARHead(D_MODEL).to(device)
+    head.load_state_dict(ckpt["head"])
+    head.eval()
+    tprint(f"AR head loaded (val_cos={ckpt.get('val_cosine',0):.4f})")
+    return head
+
+
+def load_ar_backbone(device):
+    tprint(f"Loading AR backbone ({BASE_MODEL})...")
+    m = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(device)
+    m.eval()
+    return m
+
+
+def generate(model, tok, act_scaled, max_new=64):
+    prompt = f"<concept>{INJ_CHAR}</concept>\n<explanation>"
+    p_ids = tok(prompt, return_tensors="pt")["input_ids"].to(act_scaled.device)
+    p_mask = torch.ones(1, p_ids.shape[1], device=act_scaled.device, dtype=torch.long)
+    inj_pos = (p_ids[0] == INJ_TOK_ID).nonzero(as_tuple=True)[0][0].item()
+    embeds = model.get_input_embeddings()(p_ids).clone()
+    embeds[0, inj_pos] = act_scaled[0].to(embeds.dtype)
+    with torch.no_grad():
+        out = model.generate(inputs_embeds=embeds, attention_mask=p_mask,
+                             max_new_tokens=max_new, do_sample=False,
+                             pad_token_id=tok.eos_token_id)
+    return tok.decode(out[0], skip_special_tokens=True).strip()
+
+
+def reconstruct(ar_backbone, ar_head, tok, explanation):
+    tok.pad_token_id = tok.eos_token_id
+    dev = ar_head.proj.weight.device
+    enc = tok([explanation], return_tensors="pt", padding=True,
+              truncation=True, max_length=128).to(dev)
+    with torch.no_grad():
+        h = ar_backbone(**enc, output_hidden_states=True).hidden_states[-1]
+        lens = enc["attention_mask"].sum(1) - 1
+        last = h[0, lens[0]]
+        recon = ar_head(last.unsqueeze(0))
+    return recon.float()
+
+
+def eval_one(model, tok, act_raw, ar_backbone, ar_head, tok_ar):
+    act_s = act_raw.unsqueeze(0) / act_raw.norm() * INJ_SCALE
+    act_s = act_s.to(ar_head.proj.weight.device)
+    act_n = (act_raw.unsqueeze(0) / act_raw.norm()).to(ar_head.proj.weight.device)
+    expl  = generate(model, tok, act_s)
+    recon = reconstruct(ar_backbone, ar_head, tok_ar, expl)
+    return (recon * act_n).sum(-1).item(), expl
+
+
+# ══════════════════════════════════════════════════════════
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--num-samples", type=int, default=100)
+    parser.add_argument("--seed", type=int, default=42)
+    args = parser.parse_args()
+
+    device = torch.device("mps" if torch.backends.mps.is_available() else "cpu")
+    random.seed(args.seed)
+
+    print(f"\n{'='*55}")
+    print(f"  Tiny-NLA Final Eval | samples={args.num_samples} | seed={args.seed}")
+    print(f"{'='*55}\n")
+
+    acts = load_activations()
+    ar_head = load_ar(device)
+    ar_bb   = load_ar_backbone(device)
+    tok_ar  = AutoTokenizer.from_pretrained(BASE_MODEL)
+
+    sft_model, sft_tok = load_av_model(ARTIFACTS / "checkpoints" / "av_v2", device)
+    rl_model,  rl_tok  = load_av_model(ARTIFACTS / "checkpoints" / "av_rl_best", device)
+
+    eval_idx = random.sample(range(len(acts)), args.num_samples)
+
+    sft_cos, rl_cos = [], []
+    sft_expls, rl_expls = [], []
+
+    tprint(f"Evaluating {args.num_samples} samples...")
+    for k, idx in enumerate(eval_idx):
+        act = acts[idx]
+        c1, e1 = eval_one(sft_model, sft_tok, act, ar_bb, ar_head, tok_ar)
+        c2, e2 = eval_one(rl_model,  rl_tok,  act, ar_bb, ar_head, tok_ar)
+        sft_cos.append(c1); rl_cos.append(c2)
+        sft_expls.append(e1); rl_expls.append(e2)
+        if (k + 1) % 20 == 0:
+            tprint(f"  {k+1}/{args.num_samples} | sft={sum(sft_cos)/(k+1):.4f} | rl={sum(rl_cos)/(k+1):.4f}")
+
+    sft_mean = sum(sft_cos) / len(sft_cos)
+    rl_mean  = sum(rl_cos)  / len(rl_cos)
+    delta    = rl_mean - sft_mean
+    gains    = [rl_cos[i] - sft_cos[i] for i in range(args.num_samples)]
+    positive = sum(1 for g in gains if g > 0)
+
+    print(f"\n{'='*55}")
+    print(f"  RESULTS")
+    print(f"{'='*55}")
+    print(f"  {'':16} {'SFT':>10} {'RL':>10} {'Δ':>10}")
+    print(f"  {'Mean':16} {sft_mean:10.4f} {rl_mean:10.4f} {delta:+10.4f}")
+    print(f"  {'Best':16} {max(sft_cos):10.4f} {max(rl_cos):10.4f} {max(rl_cos)-max(sft_cos):+10.4f}")
+    print(f"  {'Worst':16} {min(sft_cos):10.4f} {min(rl_cos):10.4f} {min(rl_cos)-min(sft_cos):+10.4f}")
+    print(f"  {'RL wins':16} {positive}/{args.num_samples} ({100*positive/args.num_samples:.0f}%)")
+    print(f"{'='*55}")
+
+    # Top 5 improvements
+    print(f"\n── TOP 5 GAINS (RL − SFT) ──")
+    sorted_idx = sorted(range(args.num_samples), key=lambda i: gains[i], reverse=True)
+    for rank, i in enumerate(sorted_idx[:5]):
+        print(f"\n  #{rank+1} Δ={gains[i]:+.4f} | SFT cos={sft_cos[i]:.4f}")
+        print(f"  SFT: {sft_expls[i][:130]}")
+        print(f"  RL:  {rl_expls[i][:130]}")
+
+    # Bottom 5
+    print(f"\n── BOTTOM 5 (RL regressions) ──")
+    for rank, i in enumerate(sorted_idx[-5:]):
+        print(f"\n  #{args.num_samples-4+rank} Δ={gains[i]:+.4f} | RL cos={rl_cos[i]:.4f}")
+        print(f"  SFT: {sft_expls[i][:130]}")
+        print(f"  RL:  {rl_expls[i][:130]}")
+
+    print(f"\n{tprint('Done.')}")

experiments/tiny_nla/eval_roundtrip.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Round-trip evaluation: extract → explain → reconstruct → metrics
+Runs on held-out data and produces a comprehensive report.
+"""
+
+import json, sys, yaml, random
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from infer_tiny_nla import TinyNLA
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+
+
+def main():
+    print("=" * 60)
+    print("🔄 Tiny-NLA Round-Trip Evaluation")
+    print("=" * 60)
+    
+    nla = TinyNLA()
+    
+    # Load dataset for held-out samples
+    with open(ARTIFACTS_DIR / "dataset.jsonl", "r", encoding="utf-8") as f:
+        records = [json.loads(l) for l in f]
+    
+    activations = torch.load(ARTIFACTS_DIR / "activations.pt", weights_only=True)
+    
+    # Filter to valid explanations
+    valid = []
+    for i, r in enumerate(records):
+        exp = r.get("teacher_explanation", "") or r.get("teacher_explanation_raw", "")
+        if exp and exp not in ("[空输出]", ""):
+            valid.append((r, activations[i]))
+    
+    print(f"  Total records: {len(records)}, Valid: {len(valid)}")
+    
+    # Use a set of held-out indices for evaluation
+    # We'll use the first N samples from different texts
+    # Stratify by text to ensure diversity
+    texts_grouped = {}
+    for i, (r, _) in enumerate(valid):
+        texts_grouped.setdefault(r["text_idx"], []).append(i)
+    
+    held_out = []
+    for tidx, indices in texts_grouped.items():
+        # Take last 2 from each text group as held-out
+        held_out.extend(indices[-2:])
+    
+    # Make sure we have at least 20 held-out
+    if len(held_out) < 20:
+        extra = [i for i in range(len(valid)) if i not in held_out]
+        random.Random(42).shuffle(extra)
+        held_out.extend(extra[:20 - len(held_out)])
+    
+    print(f"  Held-out samples: {len(held_out)}")
+    
+    # Round-trip evaluation
+    results = []
+    for idx in held_out:
+        rec, act = valid[idx]
+        
+        # We need original text + position for context
+        text = rec["text"]
+        pos = rec["pos"]
+        token_text = rec["token_text"]
+        teacher_exp = rec.get("teacher_explanation", "") or rec.get("teacher_explanation_raw", "")
+        
+        # Run round-trip
+        try:
+            # Extract activation
+            ext = nla.extract(text, pos)
+            
+            # Generate AV explanation (from the activation, not the text)
+            av_result = nla.explain(ext["activation"])
+            av_explanation = av_result["explanation"]
+            
+            # Reconstruct from AV output
+            rec_result = nla.reconstruct(av_explanation)
+            
+            row = {
+                "text": text,
+                "position": pos,
+                "token_text": token_text,
+                "teacher_explanation": teacher_exp[:120],
+                "av_explanation": av_explanation[:120],
+            }
+            
+            if "reconstructed" in rec_result:
+                orig_n = F.normalize(act.unsqueeze(0), dim=-1)
+                recon = rec_result["reconstructed"].unsqueeze(0)
+                recon_n = F.normalize(recon, dim=-1)
+                cosine = (orig_n * recon_n).sum(dim=-1).item()
+                mse = F.mse_loss(orig_n, recon_n).item()
+                row["roundtrip_cosine"] = round(cosine, 4)
+                row["roundtrip_mse"] = round(mse, 6)
+            
+            # Also compute: teacher_explanation → original_activation cosine
+            tea_result = nla.reconstruct(teacher_exp)
+            if "reconstructed" in tea_result:
+                tea_recon = tea_result["reconstructed"].unsqueeze(0)
+                tea_recon_n = F.normalize(tea_recon, dim=-1)
+                tea_cosine = (orig_n * tea_recon_n).sum(dim=-1).item()
+                tea_mse = F.mse_loss(orig_n, tea_recon_n).item()
+                row["teacher_to_activation_cosine"] = round(tea_cosine, 4)
+                row["teacher_to_activation_mse"] = round(tea_mse, 6)
+            
+            results.append(row)
+            
+        except Exception as e:
+            print(f"  ⚠️  Error at idx {idx}: {e}")
+            continue
+    
+    # Summary statistics
+    rt_cosines = [r.get("roundtrip_cosine", 0) for r in results if "roundtrip_cosine" in r]
+    tea_cosines = [r.get("teacher_to_activation_cosine", 0) for r in results if "teacher_to_activation_cosine" in r]
+    
+    print(f"\n📊 Round-Trip Metrics")
+    print(f"  Samples evaluated: {len(results)}")
+    if rt_cosines:
+        print(f"  Round-trip (AV→AR) cosine:")
+        print(f"    Mean: {sum(rt_cosines)/len(rt_cosines):.4f}")
+        print(f"    Min:  {min(rt_cosines):.4f}")
+        print(f"    Max:  {max(rt_cosines):.4f}")
+    if tea_cosines:
+        print(f"  Teacher→Activation cosine (AR upper bound):")
+        print(f"    Mean: {sum(tea_cosines)/len(tea_cosines):.4f}")
+        print(f"    Min:  {min(tea_cosines):.4f}")
+        print(f"    Max:  {max(tea_cosines):.4f}")
+    
+    # Save results
+    out_path = ARTIFACTS_DIR / "roundtrip_results.json"
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(results, f, ensure_ascii=False, indent=2)
+    print(f"\n  Results saved: {out_path}")
+    
+    # Show 20 worked examples
+    print(f"\n📝 20 Worked Examples")
+    print("=" * 60)
+    for i, r in enumerate(results[:20]):
+        print(f"\n  [{i+1}] Text: {r['text'][:50]}...")
+        print(f"      Token: {r['token_text']!r} (pos={r['position']})")
+        print(f"      Teacher: {r['teacher_explanation'][:80]}")
+        print(f"      AV:      {r['av_explanation'][:80]}")
+        if "roundtrip_cosine" in r:
+            print(f"      Round-trip cos: {r['roundtrip_cosine']}")
+        if "teacher_to_activation_cosine" in r:
+            print(f"      Teacher→Act cos: {r['teacher_to_activation_cosine']}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/expand_dataset.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""
+Generate diverse Chinese texts via opencode, then extract activations and teacher labels.
+Run: python expand_dataset.py
+"""
+import json, subprocess, sys, time
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+OUT_TEXTS = ARTIFACTS_DIR / "expanded_texts.json"
+MODEL = "opencode/deepseek-v4-flash-free"
+
+DOMAINS = [
+    ("科技AI", 20), ("日常生活", 20), ("自然科学", 20), ("社会新闻", 20),
+    ("文学文化", 20), ("经济商业", 20), ("历史哲学", 20), ("医学健康", 15),
+    ("体育运动", 15), ("环境生态", 15), ("教育学习", 15), ("人际关系", 15),
+    ("法律政治", 10), ("饮食美食", 10), ("旅游地理", 10),
+]
+
+PROMPT_TEMPLATE = """\
+请生成 {n} 条不同的中文句子，主题是「{domain}」。
+
+要求：
+- 每条 15-50 个字，完整句子
+- 内容多样，涵盖该主题的不同角度
+- 语言自然，包含实词（名词、动词、形容词）和虚词（介词、连词、语气词）
+- 句式多样：陈述句、疑问句、复合句都可以
+- 不要编号，每行一句，直接输出句子
+
+只输出句子，不要其他解释。"""
+
+
+def call_opencode(prompt: str) -> str:
+    r = subprocess.run(
+        ["opencode", "run", "--model", MODEL, prompt],
+        capture_output=True, text=True, timeout=120,
+    )
+    lines = r.stdout.splitlines()
+    content = [l for l in lines if l.strip()
+               and not l.strip().startswith("\x1b")
+               and "> orchestrator" not in l
+               and not l.strip().startswith("{")
+               and not l.strip().startswith('"')]
+    return "\n".join(content).strip()
+
+
+def main():
+    existing = []
+    if OUT_TEXTS.exists():
+        with open(OUT_TEXTS) as f:
+            existing = json.load(f)
+    print(f"Existing texts: {len(existing)}")
+
+    existing_set = set(existing)
+    all_texts = list(existing)
+
+    for domain, n in DOMAINS:
+        prompt = PROMPT_TEMPLATE.format(domain=domain, n=n)
+        print(f"\n  [{domain}] requesting {n} sentences...")
+        try:
+            out = call_opencode(prompt)
+            sentences = [l.strip() for l in out.splitlines()
+                        if l.strip() and 8 <= len(l.strip()) <= 80
+                        and l.strip() not in existing_set]
+            print(f"    Got {len(sentences)} new sentences")
+            for s in sentences[:5]:
+                print(f"      {s[:50]}")
+            all_texts.extend(sentences)
+            existing_set.update(sentences)
+            time.sleep(0.5)
+        except Exception as e:
+            print(f"    Error: {e}", file=sys.stderr)
+
+    # Save
+    with open(OUT_TEXTS, "w", encoding="utf-8") as f:
+        json.dump(all_texts, f, ensure_ascii=False, indent=2)
+    print(f"\nTotal texts: {len(all_texts)} → {OUT_TEXTS}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/expand_dataset_v2.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Phase 0.1: expand Chinese text corpus to 500+ sentences via opencode (parallel)."""
+import json, subprocess, sys, time
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+ARTIFACTS = Path(__file__).resolve().parents[2] / "artifacts" / "tiny_nla"
+OUT = ARTIFACTS / "expanded_texts.json"
+MODEL = "opencode/deepseek-v4-flash-free"
+
+# Additional domains to push past 500
+DOMAINS = [
+    ("编程技术", 25), ("数学逻辑", 20), ("影视娱乐", 20), ("宗教信仰", 15),
+    ("语言学", 20), ("艺术美学", 20), ("交通出行", 20), ("宠物动物", 20),
+    ("天气气候", 15), ("金融投资", 20), ("职场沟通", 20), ("心理学", 20),
+    ("社交媒体", 20), ("游戏娱乐", 15), ("亲子教育", 15),
+]
+
+
+def gen_sentences(domain_n):
+    domain, n = domain_n
+    # Request a mix of short/medium/long
+    prompt = (
+        f"请生成{n}条关于「{domain}」的中文句子。"
+        "要求：包含8-15字短句、15-30字中等句、30-50字长句各占约三分之一；"
+        "句式多样（陈述、疑问、复合）；语言自然，含丰富实词和虚词。"
+        "不要编号，每行一句，只输出句子。"
+    )
+    r = subprocess.run(["opencode", "run", "--model", MODEL, prompt],
+                       capture_output=True, text=True, timeout=120)
+    lines = r.stdout.splitlines()
+    sents = [l.strip() for l in lines
+             if l.strip() and 5 <= len(l.strip()) <= 80
+             and not l.strip().startswith("\x1b")
+             and "orchestrator" not in l
+             and not l.strip().startswith("{")]
+    return domain, sents
+
+
+def main():
+    with open(OUT) as f:
+        existing = json.load(f)
+    existing_set = set(existing)
+    print(f"Starting with {len(existing)} sentences")
+
+    with ThreadPoolExecutor(max_workers=3) as pool:
+        futures = {pool.submit(gen_sentences, d): d for d in DOMAINS}
+        for fut in as_completed(futures):
+            domain, sents = fut.result()
+            new = [s for s in sents if s not in existing_set]
+            existing.extend(new)
+            existing_set.update(new)
+            print(f"  [{domain}] +{len(new)} → total {len(existing)}")
+
+    with open(OUT, "w", encoding="utf-8") as f:
+        json.dump(existing, f, ensure_ascii=False, indent=2)
+    print(f"\nFinal corpus: {len(existing)} sentences → {OUT}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/gen_demo_html.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Generate a standalone HTML demo from real teacher labels."""
+import json
+from pathlib import Path
+from collections import defaultdict
+
+LABELS_FILE = Path("/Users/cccmmd/InfoLens/artifacts/tiny_nla/teacher_labels_hq.json")
+OUTPUT_HTML = Path("/Users/cccmmd/InfoLens/experiments/tiny_nla/demo_activation_translator.html")
+
+with open(LABELS_FILE) as f:
+    labels = json.load(f)
+
+by_text = defaultdict(list)
+for r in labels:
+    by_text[r["text_idx"]].append(r)
+
+sentences = []
+for tid in sorted(by_text):
+    recs = sorted(by_text[tid], key=lambda x: x["pos"])
+    sent = recs[0]["text"]
+    tokens = []
+    for r in recs:
+        tokens.append({
+            "text": r["token_text"],
+            "pos": r["pos"],
+            "top5": r["top_tokens"],
+            "explanation": r["teacher_explanation"],
+            "norm": round(r["activation_norm"], 1),
+        })
+    sentences.append({"text": sent, "tokens": tokens})
+    if len(sentences) >= 5:
+        break
+
+sentences_json = json.dumps(sentences, ensure_ascii=False)
+
+# Read template
+import os
+template_path = Path(__file__).parent / "demo_template.html"
+html = template_path.read_text(encoding="utf-8")
+html = html.replace("__SENTENCES_DATA__", sentences_json)
+OUTPUT_HTML.write_text(html, encoding="utf-8")
+print(f"Demo written to {OUTPUT_HTML}")
+print(f"Sentences: {len(sentences)}, tokens: {sum(len(s['tokens']) for s in sentences)}")

experiments/tiny_nla/gen_opencode_only.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""opencode-only teacher label generation - runs in background."""
+import json, subprocess, time, sys
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+ARTIFACTS = Path(__file__).resolve().parents[2] / "artifacts" / "tiny_nla"
+RECORDS_FILE = ARTIFACTS / "records_v2.jsonl"
+OUTPUT_JSONL = ARTIFACTS / "teacher_labels_v2.jsonl"
+
+PROMPT = """\
+你是语言模型内部机制分析专家。用1-2句简洁中文描述Qwen3-0.6B在处理下面这个token时，该位置residual stream激活值编码的语义信息。
+
+上下文：{context}
+当前token：「{token}」（位置{pos}/{seq_len}）
+模型预测下一个词的候选：{top_tokens}
+
+要求：简洁具体，联系token在句中的实际句法/语义角色，联系预测候选推断编码内容，不超过55字。只输出解释本身。"""
+
+
+def make_prompt(r):
+    return PROMPT.format(context=r["text"], token=r["token_text"],
+                         pos=r["pos"], seq_len=r["seq_len"],
+                         top_tokens="、".join(r["top_tokens"][:5]))
+
+
+def strip_think(t):
+    return t.split("</think>")[-1].strip() if "</think>" in t else t.strip()
+
+
+def call_opencode(r):
+    res = subprocess.run(
+        ["opencode", "run", "--model", "opencode/deepseek-v4-flash-free", make_prompt(r)],
+        capture_output=True, text=True, timeout=240,
+    )
+    lines = [l.strip() for l in res.stdout.splitlines()
+             if l.strip() and not l.startswith("\x1b") and "orchestrator" not in l
+             and not l.startswith("{") and not l.startswith('"')]
+    return strip_think("\n".join(lines))
+
+
+def load_done():
+    done = set()
+    try:
+        for r in json.load(open(ARTIFACTS / "teacher_labels_v2.json")):
+            done.add((r["text_idx"], r["pos"]))
+    except Exception:
+        pass
+    if OUTPUT_JSONL.exists():
+        for line in open(OUTPUT_JSONL):
+            try:
+                r = json.loads(line)
+                done.add((r["text_idx"], r["pos"]))
+            except Exception:
+                pass
+    return done
+
+
+def process(idx_rec):
+    idx, rec = idx_rec
+    try:
+        expl = call_opencode(rec)
+        if expl and len(expl) >= 5:
+            return {**rec, "teacher_explanation": expl, "teacher_source": "opencode"}
+    except Exception as e:
+        print(f"  err [{idx}]: {e}", flush=True)
+    return None
+
+
+def main():
+    workers = int(sys.argv[1]) if len(sys.argv) > 1 else 3
+    records = [json.loads(l) for l in open(RECORDS_FILE)]
+    done = load_done()
+    todo = [(i, r) for i, r in enumerate(records)
+            if (r["text_idx"], r["pos"]) not in done]
+    print(f"Remaining: {len(todo)}/9810, workers: {workers}", flush=True)
+
+    completed = 0
+    t0 = time.time()
+    out_f = open(OUTPUT_JSONL, "a", encoding="utf-8", buffering=1)
+
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = {pool.submit(process, item): item for item in todo}
+        for fut in as_completed(futures):
+            result = fut.result()
+            if result:
+                out_f.write(json.dumps(result, ensure_ascii=False) + "\n")
+                completed += 1
+                if completed % 20 == 0:
+                    rate = completed / (time.time() - t0) * 60
+                    eta_h = (len(todo) - completed) / (rate / 60) / 3600
+                    print(f"  [{len(done)+completed}/{9810}] {rate:.0f}/min ETA={eta_h:.1f}h", flush=True)
+
+    out_f.close()
+    print(f"Done: {completed} new labels written", flush=True)
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/generate_data.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""
+Phase 3: Data Generation
+
+Two-pass process:
+  1. Load BASE model → extract activations for token positions in diverse texts
+  2. Load INSTRUCT model → generate teacher explanations
+
+Output: artifacts/tiny_nla/dataset.jsonl + artifacts/tiny_nla/dataset_stats.json
+"""
+
+import os, sys, json, math, yaml, time, random
+from pathlib import Path
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# ── paths ──────────────────────────────────────────────
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+BASE_MODEL = "Qwen/Qwen3-0.6B-Base"
+INSTRUCT_MODEL = "Qwen/Qwen3-0.6B"
+
+# ── device ─────────────────────────────────────────────
+def detect_device():
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+def get_dtype(device):
+    if device.type == "cuda":
+        return torch.float16
+    return torch.float32  # MPS/CPU safest
+
+
+# ── diverse Chinese texts ──────────────────────────────
+TEXTS = [
+    # Technology & AI
+    "人工智能正在深刻改变各行各业的发展模式，从自动驾驶到医疗诊断，都在不断突破。",
+    "深度学习模型通过多层神经网络学习数据的层次化特征表示，在自然语言处理领域取得了显著成果。",
+    "量子计算是一种利用量子力学原理处理信息的新型计算范式。",
+    
+    # Daily life
+    "今天天气真好，阳光明媚，我们一起去公园散步吧，感受大自然的美丽。",
+    "这家餐厅的菜非常好吃，特别是他们的招牌菜红烧肉，味道鲜美极了。",
+    "昨天晚上我看了一部很感人的电影，讲述了一个关于友情和梦想的故事。",
+    
+    # Science & education
+    "在学习编程的过程中，最重要的是掌握基本的逻辑思维和解决问题的能力。",
+    "数学是自然科学的基础，它帮助我们理解世界的规律和结构。",
+    "历史上许多伟大的科学家都经历了无数次失败才取得了突破性的发现。",
+    
+    # News & society
+    "近年来，全球气候变化问题日益受到各国政府的高度关注。",
+    "数字经济正在成为推动全球经济增长的新引擎。",
+    "教育公平是社会公平的重要基础，需要全社会共同努力。",
+    
+    # Literature & culture
+    "读书是一种与作者对话的方式，通过阅读我们可以获得知识和智慧。",
+    "中国传统文化的魅力在于其深厚的历史积淀和独特的哲学思想。",
+    "音乐是人类共同的语言，它能够跨越国界传达情感。",
+    
+    # Economy & business
+    "市场经济的核心在于供需关系的动态平衡。",
+    "创新是企业保持竞争力的关键因素。",
+    "投资理财需要长期规划和理性决策。",
+    
+    # Short phrases
+    "请帮我解释一下这个概念。",
+    "我想了解更多关于这个话题的信息。",
+    "这是一个非常重要的发现。",
+    "我们需要认真对待这个问题。",
+]
+
+
+# ── Pass 1: Extract activations ─────────────────────────
+def extract_activations(model, tokenizer, texts, layer_idx, device, dtype):
+    """
+    For each text, extract residual stream activation at layer_idx
+    for EVERY token position (not just last). Returns list of records.
+    """
+    print("=" * 60)
+    print("📥 Pass 1: Extracting Activations")
+    print("=" * 60)
+    records = []
+    total_tokens = 0
+    
+    for idx, text in enumerate(texts):
+        inputs = tokenizer(text, return_tensors="pt").to(device)
+        input_ids = inputs["input_ids"]  # [1, seq_len]
+        seq_len = input_ids.shape[1]
+        
+        with torch.no_grad():
+            outputs = model(
+                **inputs,
+                output_hidden_states=True,
+            )
+        
+        # Get logits for last token position for top-k info
+        logits = outputs.logits[0]  # [seq_len, vocab]
+        
+        # Get hidden states for our target layer
+        hidden = outputs.hidden_states[layer_idx]  # [1, seq_len, d_model]
+        
+        for pos in range(seq_len):
+            token_id = input_ids[0, pos].item()
+            token_text = tokenizer.decode([token_id])
+            activation = hidden[0, pos, :].cpu()  # [d_model]
+            
+            # Top-k at this position (from logits at this position predicting NEXT token)
+            if pos < seq_len - 1:
+                next_logits = logits[pos]  # logits for predicting next token after pos
+                topk_vals, topk_idxs = torch.topk(next_logits, k=10)
+                top_tokens = [tokenizer.decode([t]) for t in topk_idxs]
+            else:
+                # Last position has no "next token" prediction in base model
+                # But we still extract the activation for it
+                next_logits = logits[pos]
+                topk_vals, topk_idxs = torch.topk(next_logits, k=10)
+                top_tokens = [tokenizer.decode([t]) for t in topk_idxs]
+            
+            records.append({
+                "text_idx": idx,
+                "text": text,
+                "pos": pos,
+                "token_id": token_id,
+                "token_text": token_text,
+                "activation_vector": activation.tolist(),
+                "top_tokens": top_tokens,
+                "activation_norm": activation.norm().item(),
+            })
+            total_tokens += 1
+        
+        if (idx + 1) % 5 == 0:
+            print(f"  Processed {idx + 1}/{len(texts)} texts ({total_tokens} tokens so far)")
+    
+    print(f"  ✅ Extracted {total_tokens} activations from {len(texts)} texts")
+    return records
+
+
+# ── Pass 2: Generate teacher explanations ──────────────
+def generate_teacher_explanations(
+    model, tokenizer, records, device, dtype,
+    max_samples=500, batch_prompt=False,
+):
+    """
+    For each record, generate a teacher explanation using the instruct model.
+    
+    Teacher prompt (instruct format):
+      Given a context and token position, explain what the model might be focusing on.
+    """
+    print("=" * 60)
+    print("📝 Pass 2: Generating Teacher Explanations")
+    print("=" * 60)
+    
+    # Determine instruct chat template format
+    # Qwen3 instruct uses: <|im_start|>system...<|im_end|> etc
+    # But for base model style, just use a simple prompt
+    
+    system_msg = "你是一个模型可解释性专家。给定一段文本和其中的某个位置，用1-2句中文简短解释模型在该位置可能关注什么语义信息。不要长篇分析。"
+    
+    # Sample records, ensuring diversity across texts
+    random.seed(42)
+    n_texts = len(set(r["text_idx"] for r in records))
+    samples_per_text = max(1, max_samples // n_texts)
+    
+    # Stratified sample: take at least 15 tokens per text (or all if fewer available)
+    texts_grouped = {}
+    for r in records:
+        texts_grouped.setdefault(r["text_idx"], []).append(r)
+    
+    sampled_records = []
+    for tidx in sorted(texts_grouped.keys()):
+        group = texts_grouped[tidx]
+        # Take evenly spaced positions for diversity
+        n = min(len(group), max(15, samples_per_text))
+        indices = sorted(random.sample(range(len(group)), min(n, len(group))))
+        for i in indices:
+            sampled_records.append(group[i])
+    
+    # If we have fewer than target, take more
+    if len(sampled_records) < max_samples and len(sampled_records) < len(records):
+        existing_ids = set(id(r) for r in sampled_records)
+        more = [r for r in records if id(r) not in existing_ids]
+        remaining = max_samples - len(sampled_records)
+        sampled_records.extend(random.sample(more, min(remaining, len(more))))
+    
+    print(f"  Target: {max_samples} samples, selected {len(sampled_records)} for labeling")
+    
+    results = []
+    teacher_failures = 0
+    
+    for i, rec in enumerate(sampled_records):
+        text = rec["text"]
+        pos = rec["pos"]
+        token_text = rec["token_text"]
+        top_tokens = rec["top_tokens"]
+        
+        # Build instruction prompt
+        user_msg = (
+            f"文本：{text}\n"
+            f"位置：第{pos}个token（文本位置），该token文本是「{token_text}」\n"
+            f"该位置模型预测的下一个token候选：{', '.join(top_tokens[:5])}\n\n"
+            f"请用1-2句中文解释：模型在这个位置可能关注什么？"
+        )
+        
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_msg},
+        ]
+        
+        prompt = tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        
+        inputs = tokenizer(prompt, return_tensors="pt").to(device)
+        
+        try:
+            with torch.no_grad():
+                output_ids = model.generate(
+                    **inputs,
+                    max_new_tokens=64,
+                    do_sample=True,
+                    temperature=0.7,
+                    top_p=0.9,
+                    pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id,
+                )
+            # Extract the generated part (skip input prompt)
+            generated = output_ids[0][inputs["input_ids"].shape[1]:]
+            explanation = tokenizer.decode(generated, skip_special_tokens=True).strip()
+            
+            if not explanation or len(explanation) < 5:
+                explanation = "[空输出]"
+                teacher_failures += 1
+                
+        except Exception as e:
+            explanation = f"[生成失败: {e}]"
+            teacher_failures += 1
+        
+        rec["teacher_explanation"] = explanation
+        results.append(rec)
+        
+        if (i + 1) % 20 == 0 or i == 0:
+            print(f"  [{i+1}/{len(sampled_records)}] token={token_text!r} -> {explanation[:60]}...")
+    
+    print(f"\n  ✅ Generated {len(results)} explanations")
+    print(f"  ⚠️  Failures/empty: {teacher_failures}/{len(results)}")
+    return results
+
+
+# ── Save dataset ────────────────────────────────────────
+def save_dataset(records, nla_meta: dict):
+    """Save dataset as JSONL + stats."""
+    # Strip bulky activation vectors for JSONL (keep as separate array file)
+    jsonl_path = ARTIFACTS_DIR / "dataset.jsonl"
+    # Save activations as a separate .pt file for efficiency
+    act_path = ARTIFACTS_DIR / "activations.pt"
+    
+    activation_tensors = []
+    json_records = []
+    
+    for r in records:
+        act = r.pop("activation_vector")
+        activation_tensors.append(torch.tensor(act))
+        json_records.append(r)
+    
+    with open(jsonl_path, "w", encoding="utf-8") as f:
+        for rec in json_records:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+    
+    torch.save(torch.stack(activation_tensors), act_path)
+    
+    print(f"\n  💾 Dataset saved:")
+    print(f"     {jsonl_path} ({len(json_records)} records)")
+    print(f"     {act_path} ({activation_tensors[0].shape})")
+    
+    # Stats
+    n_texts = len(set(r["text_idx"] for r in json_records))
+    has_explanation = sum(1 for r in json_records if r.get("teacher_explanation"))
+    empty_explanation = sum(1 for r in json_records if r.get("teacher_explanation") in ("[空输出]", None, ""))
+    
+    stats = {
+        "total_records": len(json_records),
+        "texts_used": n_texts,
+        "records_with_explanation": has_explanation,
+        "records_empty_explanation": empty_explanation,
+        "d_model": activation_tensors[0].shape[0],
+    }
+    
+    stats_path = ARTIFACTS_DIR / "dataset_stats.json"
+    with open(stats_path, "w", encoding="utf-8") as f:
+        json.dump(stats, f, ensure_ascii=False, indent=2)
+    print(f"     {stats_path}")
+    
+    # Update nla_meta
+    nla_meta["training"]["dataset_size"] = len(json_records)
+    with open(SIDECAR_PATH, "w", encoding="utf-8") as f:
+        import yaml
+        yaml.dump(nla_meta, f, allow_unicode=True, sort_keys=False, default_flow_style=False)
+    print(f"     sidecar updated with dataset_size={len(json_records)}")
+    
+    return json_records
+
+
+# ── main ───────────────────────────────────────────────
+def main():
+    print("=" * 60)
+    print("📦 TINY-NLA DATA GENERATION")
+    print("=" * 60)
+    print()
+    
+    device = detect_device()
+    dtype = get_dtype(device)
+    print(f"  Device: {device}, dtype: {dtype}")
+    
+    # Load sidecar
+    with open(SIDECAR_PATH, "r") as f:
+        import yaml
+        nla_meta = yaml.safe_load(f)
+    
+    layer_idx = nla_meta["layer_index"]
+    max_samples = 500
+    
+    # ── Pass 1: Extract activations ──
+    print(f"\n  Loading BASE model for activation extraction...")
+    t0 = time.perf_counter()
+    base_model = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL,
+        trust_remote_code=True,
+        torch_dtype=dtype,
+        low_cpu_mem_usage=True,
+        attn_implementation="eager",
+    ).to(device)
+    base_model.eval()
+    base_tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+    print(f"  Base model loaded in {time.perf_counter() - t0:.1f}s")
+    
+    all_records = extract_activations(base_model, base_tokenizer, TEXTS, layer_idx, device, dtype)
+    
+    # Clean up base model to free memory
+    del base_model
+    if device.type == "mps":
+        torch.mps.empty_cache()
+    print("  Base model freed from memory\n")
+    
+    # ── Pass 2: Generate teacher explanations ──
+    print(f"  Loading INSTRUCT model for teacher...")
+    t0 = time.perf_counter()
+    instruct_model = AutoModelForCausalLM.from_pretrained(
+        INSTRUCT_MODEL,
+        trust_remote_code=True,
+        torch_dtype=dtype,
+        low_cpu_mem_usage=True,
+        attn_implementation="eager",
+    ).to(device)
+    instruct_model.eval()
+    instruct_tokenizer = AutoTokenizer.from_pretrained(INSTRUCT_MODEL, trust_remote_code=True)
+    print(f"  Instruct model loaded in {time.perf_counter() - t0:.1f}s")
+    
+    results = generate_teacher_explanations(
+        instruct_model, instruct_tokenizer, all_records,
+        device, dtype, max_samples=max_samples,
+    )
+    
+    # Clean up
+    del instruct_model
+    if device.type == "mps":
+        torch.mps.empty_cache()
+    
+    # ── Save ──
+    json_records = save_dataset(results, nla_meta)
+    
+    # ── Quality check ──
+    print()
+    print("=" * 60)
+    print("🔍 Quick Quality Check")
+    print("=" * 60)
+    sample = random.Random(42).sample(json_records, min(10, len(json_records)))
+    for r in sample:
+        exp = r.get("teacher_explanation", "")
+        print(f"  [{r['token_text']!r:10}] {exp[:80]}")
+    
+    print()
+    print("✅ Data generation complete!")
+    print(f"  Dataset: {ARTIFACTS_DIR}/dataset.jsonl")
+    print(f"  Activations: {ARTIFACTS_DIR}/activations.pt")
+    print(f"  Stats: {ARTIFACTS_DIR}/dataset_stats.json")
+    print(f"  Sidecar: {SIDECAR_PATH}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/generate_teacher_labels.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Re-generate teacher explanations with correct parameters.
+Qwen3-0.6B instruct uses <think> blocks; we:
+  1. Use max_new_tokens=200 (enough for CoT + answer)
+  2. Add explicit instruction to suppress CoT
+  3. Post-process to strip any remaining <think> blocks
+"""
+
+import json, re, os, time, random
+from pathlib import Path
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+ARTIFACTS_DIR = Path(__file__).resolve().parents[2] / "artifacts" / "tiny_nla"
+INSTRUCT_MODEL = "Qwen/Qwen3-0.6B"
+
+def detect_device():
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+def clean_explanation(text: str) -> str:
+    """Strip <think> blocks and normalize."""
+    if not text:
+        return ""
+    cleaned = re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
+    cleaned = cleaned.strip()
+    # Remove any remaining XML-like tags
+    cleaned = re.sub(r'<[^>]+>', '', cleaned).strip()
+    return cleaned
+
+def generate_explanations(records, batch_size=1, max_new_tokens=200):
+    device = detect_device()
+    dtype = torch.float32
+    
+    print(f"  Device: {device}, dtype: {dtype}")
+    print(f"  Generating {len(records)} explanations with max_new_tokens={max_new_tokens}")
+    
+    # Load instruct model
+    print("  Loading Qwen3-0.6B instruct...")
+    t0 = time.perf_counter()
+    model = AutoModelForCausalLM.from_pretrained(
+        INSTRUCT_MODEL,
+        trust_remote_code=True,
+        torch_dtype=dtype,
+        low_cpu_mem_usage=True,
+        attn_implementation="eager",
+    ).to(device)
+    model.eval()
+    tokenizer = AutoTokenizer.from_pretrained(INSTRUCT_MODEL, trust_remote_code=True)
+    print(f"  Loaded in {time.perf_counter() - t0:.1f}s\n")
+    
+    # Strong instruction to avoid reasoning blocks
+    system_msg = "你是一个模型可解释性专家。用1-2句中文简短回答，不要分析过程，不要推理步骤，直接给出解释。"
+    
+    results = []
+    failures = 0
+    
+    for i, rec in enumerate(records):
+        text = rec.get("text", "")
+        pos = rec.get("pos", 0)
+        token_text = rec.get("token_text", "")
+        top_tokens = rec.get("top_tokens", [])
+        
+        user_msg = (
+            f"文本：{text}\n"
+            f"位置：第{pos}个token，该token文本是「{token_text}」\n"
+            f"预测的下一个token候选：{', '.join(top_tokens[:5])}\n\n"
+            f"用1-2句中文解释模型在该位置关注什么语义信息。直接回答，不要思考过程。"
+        )
+        
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_msg},
+        ]
+        
+        prompt = tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        
+        inputs = tokenizer(prompt, return_tensors="pt").to(device)
+        
+        raw_explanation = ""
+        try:
+            with torch.no_grad():
+                output_ids = model.generate(
+                    **inputs,
+                    max_new_tokens=max_new_tokens,
+                    do_sample=False,  # greedy for speed
+                    pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id,
+                )
+            
+            generated = output_ids[0][inputs["input_ids"].shape[1]:]
+            raw_explanation = tokenizer.decode(generated, skip_special_tokens=True).strip()
+            
+            explanation = clean_explanation(raw_explanation)
+            if not explanation or len(explanation) < 5:
+                explanation = "[空输出]"
+                failures += 1
+                
+        except Exception as e:
+            explanation = f"[生成失败: {e}]"
+            failures += 1
+        
+        rec["teacher_explanation_raw"] = raw_explanation
+        rec["teacher_explanation"] = explanation
+        
+        if (i + 1) % 20 == 0:
+            print(f"  [{i+1}/{len(records)}] failures={failures}", flush=True)
+        if i < 3:
+            print(f"  [{i+1}] {token_text!r:10} -> {explanation[:80]}")
+    
+    print(f"\n  ✅ Generated {len(records)} explanations, failures={failures}")
+    
+    # Clean up
+    del model
+    if device.type == "mps":
+        torch.mps.empty_cache()
+    
+    return records
+
+
+def main():
+    print("=" * 60)
+    print("🔄 Re-Generating Teacher Explanations")
+    print("=" * 60)
+    
+    # Load existing dataset
+    jsonl_path = ARTIFACTS_DIR / "dataset.jsonl"
+    records = []
+    with open(jsonl_path, "r", encoding="utf-8") as f:
+        for line in f:
+            records.append(json.loads(line))
+    print(f"  Loaded {len(records)} records from {jsonl_path}")
+    
+    # Regenerate explanations
+    records = generate_explanations(records, max_new_tokens=200)
+    
+    # Quality stats
+    valid = [r for r in records if r.get("teacher_explanation") and r["teacher_explanation"] not in ("[空输出]", "")]
+    empty = len(records) - len(valid)
+    has_think = sum(1 for r in records if "<think>" in (r.get("teacher_explanation", "") or ""))
+    
+    print(f"\n  Quality: {len(valid)} valid, {empty} empty, {has_think} still has think tag")
+    
+    # Save
+    with open(jsonl_path, "w", encoding="utf-8") as f:
+        for r in records:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"  ✅ Saved to {jsonl_path}")
+    
+    # Save AV training data
+    av_data = [{
+        "text": r["text"],
+        "token_text": r["token_text"],
+        "pos": r["pos"],
+        "teacher_explanation": r["teacher_explanation"],
+        "top_tokens": r["top_tokens"],
+    } for r in records if r.get("teacher_explanation") and r["teacher_explanation"] not in ("[空输出]", "")]
+    
+    av_path = ARTIFACTS_DIR / "av_training_data.json"
+    with open(av_path, "w", encoding="utf-8") as f:
+        json.dump(av_data, f, ensure_ascii=False, indent=2)
+    print(f"  ✅ AV training data: {av_path} ({len(av_data)} samples)")
+    
+    # Sample
+    print("\n  Samples:")
+    for r in random.Random(42).sample(av_data, min(5, len(av_data))):
+        print(f"    [{r['token_text']!r:10}] {r['teacher_explanation'][:80]}")
+    
+    print("\n✅ Done!")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/generate_teacher_labels_opencode.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""
+Generate high-quality teacher labels via opencode CLI (or any LLM).
+
+Usage:
+  python generate_teacher_labels_opencode.py
+
+This script:
+1. Reads dataset.jsonl (activation records with context/token/top_tokens)
+2. For each record, prints a prompt for the LLM (opencode/Claude/etc.)
+3. Reads LLM output and saves to teacher_labels_hq.json
+
+The output file can then be merged into av_training_data.json for retraining.
+
+Run mode options:
+  --dry-run       Print prompts only (for review), no LLM calls
+  --local         Use local Qwen3-0.6B instruct as fallback teacher
+  --opencode-cmd  Path/name of opencode CLI (default: "opencode")
+"""
+
+import json, sys, subprocess, argparse, time
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+DATASET = ARTIFACTS_DIR / "dataset.jsonl"
+OUTPUT = ARTIFACTS_DIR / "teacher_labels_hq.json"
+
+
+TEACHER_PROMPT = """\
+你是一个语言模型内部机制分析专家。我需要你用 1-2 句简洁中文，描述一个 Transformer 语言模型（Qwen3-0.6B）在处理特定 token 时，该位置的 residual stream activation 所编码的语义信息。
+
+---
+上下文句子：{context}
+当前分析的 token：「{token}」（位置 {pos}，共 {seq_len} 个 token）
+模型在此位置预测的下一个词（概率最高的候选）：{top_tokens}
+---
+
+请根据上面信息，用 1-2 句中文描述：
+- 模型在这个 token 的位置正在编码什么语义信息
+- 这个位置的激活值如何帮助预测后续内容
+
+要求：
+- 简洁具体，不要泛泛而谈
+- 联系「{token}」在句子中的实际作用
+- 联系模型预测的下一个词来推断编码内容
+- 不要以"这个位置"或"激活值"开头，而是直接描述语义
+- 不超过 60 字
+
+只输出解释本身，不要输出分析过程。"""
+
+
+def make_prompt(rec):
+    top5 = "、".join(rec["top_tokens"][:5])
+    seq_len = len(rec["text"])  # approximate
+    return TEACHER_PROMPT.format(
+        context=rec["text"],
+        token=rec["token_text"],
+        pos=rec["pos"],
+        seq_len=seq_len,
+        top_tokens=top5,
+    )
+
+
+def call_opencode(prompt_text, opencode_cmd="opencode", model="opencode/deepseek-v4-flash-free"):
+    """Call opencode CLI with a prompt, return response text."""
+    result = subprocess.run(
+        [opencode_cmd, "run", "--model", model, prompt_text],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"opencode error: {result.stderr[:200]}")
+    # Strip ANSI escape codes and header lines
+    output = result.stdout
+    lines = output.splitlines()
+    # Skip lines starting with ANSI/control chars or "> orchestrator"
+    content_lines = [
+        l for l in lines
+        if l.strip() and not l.strip().startswith("\x1b") and not l.strip().startswith("> orchestrator")
+    ]
+    return "\n".join(content_lines).strip()
+
+
+def call_local_qwen(prompt_text):
+    """Fallback: use local Qwen3-0.6B instruct."""
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    if not hasattr(call_local_qwen, "_model"):
+        print("  Loading local Qwen3-0.6B instruct...")
+        tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B", trust_remote_code=True)
+        mdl = AutoModelForCausalLM.from_pretrained(
+            "Qwen/Qwen3-0.6B", trust_remote_code=True, dtype=torch.float32,
+            low_cpu_mem_usage=True, attn_implementation="eager",
+        )
+        mdl.eval()
+        call_local_qwen._tok = tok
+        call_local_qwen._model = mdl
+
+    tok, mdl = call_local_qwen._tok, call_local_qwen._model
+    msgs = [{"role": "user", "content": prompt_text}]
+    text = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
+    inp = tok(text, return_tensors="pt")
+    with torch.no_grad():
+        out = mdl.generate(
+            **inp, max_new_tokens=128, do_sample=False,
+            pad_token_id=tok.eos_token_id, eos_token_id=tok.eos_token_id,
+        )
+    gen = out[0][inp["input_ids"].shape[1]:]
+    return tok.decode(gen, skip_special_tokens=True).strip()
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true", help="Print prompts, no LLM calls")
+    parser.add_argument("--local", action="store_true", help="Use local Qwen instruct")
+    parser.add_argument("--opencode-cmd", default="opencode", help="opencode CLI command")
+    parser.add_argument("--model", default="opencode/deepseek-v4-flash-free", help="opencode model")
+    parser.add_argument("--limit", type=int, default=None, help="Process only first N records")
+    parser.add_argument("--skip-existing", action="store_true", default=True, help="Skip if output exists")
+    args = parser.parse_args()
+
+    with open(DATASET) as f:
+        records = [json.loads(l) for l in f]
+
+    if args.limit:
+        records = records[:args.limit]
+
+    # Filter out OOD first-token records (norm > 2000) — they degrade training
+    records = [r for r in records if r["activation_norm"] < 2000]
+    print(f"Filtered to {len(records)} in-distribution records (norm < 2000)")
+
+    # Load existing results if any
+    existing = {}
+    if OUTPUT.exists() and args.skip_existing:
+        with open(OUTPUT) as f:
+            existing_list = json.load(f)
+        existing = {(r["text_idx"], r["pos"]): r for r in existing_list}
+        print(f"Loaded {len(existing)} existing labels")
+
+    results = list(existing.values())
+    new_count = 0
+
+    for i, rec in enumerate(records):
+        key = (rec["text_idx"], rec["pos"])
+        if key in existing:
+            continue
+
+        prompt = make_prompt(rec)
+
+        if args.dry_run:
+            print(f"\n=== Record {i}: [{rec['token_text']}] pos={rec['pos']} ===")
+            print(prompt)
+            print("---")
+            continue
+
+        try:
+            if args.local:
+                explanation = call_local_qwen(prompt)
+            else:
+                explanation = call_opencode(prompt, args.opencode_cmd, args.model)
+
+            # Clean up: strip think blocks if any
+            if "<think>" in explanation:
+                if "</think>" in explanation:
+                    explanation = explanation.split("</think>")[-1].strip()
+                else:
+                    explanation = explanation.split("<think>")[0].strip()
+
+            result = {
+                "text_idx": rec["text_idx"],
+                "pos": rec["pos"],
+                "text": rec["text"],
+                "token_text": rec["token_text"],
+                "top_tokens": rec["top_tokens"][:5],
+                "activation_norm": rec["activation_norm"],
+                "teacher_explanation": explanation,
+                "teacher_source": "local_qwen" if args.local else "opencode",
+            }
+            results.append(result)
+            new_count += 1
+
+            if new_count % 10 == 0 or i == 0:
+                # Save checkpoint
+                with open(OUTPUT, "w", encoding="utf-8") as f:
+                    json.dump(results, f, ensure_ascii=False, indent=2)
+                print(f"  [{i+1}/{len(records)}] saved {len(results)} labels")
+                print(f"    [{rec['token_text']}] → {explanation[:60]}")
+
+            time.sleep(0.3)  # gentle rate limit
+
+        except Exception as e:
+            print(f"  Error on record {i}: {e}", file=sys.stderr)
+            time.sleep(2)
+
+    if not args.dry_run:
+        with open(OUTPUT, "w", encoding="utf-8") as f:
+            json.dump(results, f, ensure_ascii=False, indent=2)
+        print(f"\nDone. {len(results)} total labels saved to {OUTPUT}")
+    else:
+        print(f"\nDry run complete. {len(records)} prompts shown.")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/generate_teacher_labels_v2.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Three-channel parallel teacher label generation.
+Output: append-mode JSONL (one record per line) - no corruption possible.
+Channels: NVIDIA API + OpenRouter (gpt-oss-120b, nex-n2-pro) + opencode CLI
+Usage: python generate_teacher_labels_v2.py [--workers N]
+"""
+import json, os, subprocess, time, argparse
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from openai import OpenAI
+
+ARTIFACTS = Path(__file__).resolve().parents[2] / "artifacts" / "tiny_nla"
+RECORDS_FILE = ARTIFACTS / "records_v2.jsonl"
+OUTPUT_JSONL = ARTIFACTS / "teacher_labels_v2.jsonl"  # append-mode, safe for concurrent writes
+OUTPUT_JSON  = ARTIFACTS / "teacher_labels_v2.json"   # final merged output
+
+NVIDIA_KEY = os.environ.get("NVIDIA_API_KEY", "")
+OR_KEY     = os.environ.get("OPENROUTER_API_KEY", "")
+DS_KEY     = os.environ.get("DEEPSEEK_API_KEY", "")
+FW_KEY     = os.environ.get("FIREWORKS_API_KEY", "")
+
+nvidia_client  = OpenAI(base_url="https://integrate.api.nvidia.com/v1", api_key=NVIDIA_KEY)
+or_client      = OpenAI(base_url="https://openrouter.ai/api/v1",         api_key=OR_KEY)
+ds_client      = OpenAI(base_url="https://api.deepseek.com",              api_key=DS_KEY)
+fw_client      = OpenAI(base_url="https://api.fireworks.ai/inference/v1", api_key=FW_KEY)
+
+PROMPT = """\
+你是语言模型内部机制分析专家。用1-2句简洁中文描述Qwen3-0.6B在处理下面这个token时，该位置residual stream激活值编码的语义信息。
+
+上下文：{context}
+当前token：「{token}」（位置{pos}/{seq_len}）
+模型预测下一个词的候选：{top_tokens}
+
+要求：简洁具体，联系token在句中的实际句法/语义角色，联系预测候选推断编码内容，不超过55字。只输出解释本身。"""
+
+
+def make_prompt(r):
+    return PROMPT.format(context=r["text"], token=r["token_text"],
+                         pos=r["pos"], seq_len=r["seq_len"],
+                         top_tokens="、".join(r["top_tokens"][:5]))
+
+
+def strip_think(t):
+    return t.split("</think>")[-1].strip() if "</think>" in t else t.strip()
+
+
+def call_nvidia(r):
+    resp = nvidia_client.chat.completions.create(
+        model="deepseek-ai/deepseek-v4-pro",
+        messages=[{"role": "user", "content": make_prompt(r)}], max_tokens=256)
+    return strip_think(resp.choices[0].message.content or ""), "nvidia"
+
+
+def call_gpt_oss(r):
+    resp = or_client.chat.completions.create(
+        model="openai/gpt-oss-120b:free",
+        messages=[{"role": "user", "content": make_prompt(r)}], max_tokens=256)
+    return strip_think(resp.choices[0].message.content or ""), "or-gpt-oss"
+
+
+def call_nex(r):
+    resp = or_client.chat.completions.create(
+        model="nex-agi/nex-n2-pro:free",
+        messages=[{"role": "user", "content": make_prompt(r)}], max_tokens=256)
+    return strip_think(resp.choices[0].message.content or ""), "or-nex"
+
+
+def call_deepseek(r):
+    resp = ds_client.chat.completions.create(
+        model="deepseek-chat",
+        messages=[{"role": "user", "content": make_prompt(r)}], max_tokens=256)
+    return strip_think(resp.choices[0].message.content or ""), "deepseek"
+
+
+def call_fireworks(r):
+    resp = fw_client.chat.completions.create(
+        model="accounts/fireworks/models/gpt-oss-120b",
+        messages=[{"role": "user", "content": make_prompt(r)}], max_tokens=256)
+    return strip_think(resp.choices[0].message.content or ""), "fireworks"
+
+
+# DeepSeek + Fireworks as primary (both confirmed working), others as fallback
+CHANNELS = [call_deepseek, call_fireworks, call_deepseek, call_fireworks,
+            call_deepseek, call_fireworks, call_nvidia, call_gpt_oss]
+
+
+def process(args):
+    idx, rec, ch_idx = args
+    order = [CHANNELS[(ch_idx + i) % len(CHANNELS)] for i in range(len(CHANNELS))]
+    for fn in order:
+        try:
+            expl, src = fn(rec)
+            if expl and len(expl) >= 5:
+                return {**rec, "teacher_explanation": expl, "teacher_source": src}
+        except Exception:
+            continue
+    return None
+
+
+def load_done():
+    """Load all completed keys from existing JSON and JSONL."""
+    done = {}
+    if OUTPUT_JSON.exists():
+        try:
+            for r in json.load(open(OUTPUT_JSON)):
+                done[(r["text_idx"], r["pos"])] = True
+        except Exception:
+            pass
+    if OUTPUT_JSONL.exists():
+        for line in open(OUTPUT_JSONL):
+            try:
+                r = json.loads(line)
+                done[(r["text_idx"], r["pos"])] = True
+            except Exception:
+                pass
+    return done
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--workers", type=int, default=16)
+    args = parser.parse_args()
+
+    records = [json.loads(l) for l in open(RECORDS_FILE)]
+    done = load_done()
+    todo = [(i, r, i) for i, r in enumerate(records)
+            if (r["text_idx"], r["pos"]) not in done]
+
+    print(f"Records: {len(records)}, done: {len(done)}, todo: {len(todo)}, workers: {args.workers}")
+    print(f"Channels: nvidia / gpt-oss / nex-n2-pro / opencode (round-robin)")
+
+    completed = 0
+    errors = 0
+    t0 = time.time()
+
+    # Open jsonl in append mode - each write is atomic (small line, OS guarantees)
+    out_f = open(OUTPUT_JSONL, "a", encoding="utf-8", buffering=1)  # line-buffered
+
+    with ThreadPoolExecutor(max_workers=args.workers) as pool:
+        futures = {pool.submit(process, item): item for item in todo}
+        for fut in as_completed(futures):
+            result = fut.result()
+            if result:
+                out_f.write(json.dumps(result, ensure_ascii=False) + "\n")
+                completed += 1
+            else:
+                errors += 1
+
+            n = completed + errors
+            if n % 200 == 0:
+                rate = n / (time.time() - t0) * 60
+                remaining = len(todo) - n
+                eta_min = remaining / (rate / 60) if rate > 0 else 0
+                print(f"  [{len(done)+completed}/{len(records)}] errors={errors} "
+                      f"rate={rate:.0f}/min ETA={eta_min/60:.1f}h")
+
+    out_f.close()
+
+    # Merge jsonl → final json
+    all_done = {}
+    if OUTPUT_JSON.exists():
+        try:
+            for r in json.load(open(OUTPUT_JSON)):
+                all_done[(r["text_idx"], r["pos"])] = r
+        except Exception:
+            pass
+    for line in open(OUTPUT_JSONL):
+        try:
+            r = json.loads(line)
+            all_done[(r["text_idx"], r["pos"])] = r
+        except Exception:
+            pass
+    with open(OUTPUT_JSON, "w", encoding="utf-8") as f:
+        json.dump(list(all_done.values()), f, ensure_ascii=False, indent=2)
+
+    print(f"\nDone: {len(all_done)} labels → {OUTPUT_JSON}")
+
+    # Sample
+    items = list(all_done.values())[-5:]
+    for item in items:
+        print(f"  [{item['teacher_source']}] {item['token_text']} → {item['teacher_explanation'][:65]}")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/infer_tiny_nla.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+Tiny-NLA Inference Script
+
+Reads nla_meta.yaml and provides:
+  extract(text, positions) → activation vectors at layer 19
+  explain(activation) → AV-generated explanation
+  reconstruct(explanation) → AR-reconstructed activation + cosine/MSE
+
+Usage:
+  python infer_tiny_nla.py --text "你的文本" --position 5
+  python infer_tiny_nla.py --interactive
+"""
+
+import argparse, json, os, sys, yaml, time
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+# ── paths ──────────────────────────────────────────────
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+CHECKPOINT_DIR = REPO_ROOT / "artifacts" / "tiny_nla" / "checkpoints"
+AV_CHECKPOINT = CHECKPOINT_DIR / "av"
+AR_CHECKPOINT = CHECKPOINT_DIR / "ar" / "best_ar_head.pt"
+
+
+class TinyNLA:
+    """
+    Tiny-NLA inference wrapper.
+    Loads models lazily to avoid memory waste.
+    """
+    
+    def __init__(self, sidecar_path=SIDECAR_PATH):
+        with open(sidecar_path, "r") as f:
+            self.meta = yaml.safe_load(f)
+        
+        self.base_model_name = self.meta["base_model"]
+        self.av_model_name = self.meta["av_init_model"]
+        self.layer_idx = self.meta["layer_index"]
+        self.d_model = self.meta["d_model"]
+        self.inj_char = self.meta["tokens"]["injection_char"]
+        self.inj_token_id = self.meta["tokens"]["injection_token_id"]
+        self.inj_scale = self.meta["extraction"]["injection_scale"]
+        
+        self.device = self._detect_device()
+        self.dtype = torch.float32
+        
+        # Lazy-loaded models
+        self.base_model = None
+        self.base_tokenizer = None
+        self.av_model = None
+        self.av_tokenizer = None
+        self.ar_head = None
+        self.ar_loaded = False
+    
+    def _detect_device(self):
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")
+    
+    def _load_base(self):
+        if self.base_model is not None:
+            return
+        print(f"  Loading base model ({self.base_model_name})...")
+        t0 = time.perf_counter()
+        self.base_model = AutoModelForCausalLM.from_pretrained(
+            self.base_model_name,
+            trust_remote_code=True,
+            torch_dtype=self.dtype,
+            low_cpu_mem_usage=True,
+            attn_implementation="eager",
+        ).to(self.device)
+        self.base_model.eval()
+        self.base_tokenizer = AutoTokenizer.from_pretrained(
+            self.base_model_name, trust_remote_code=True
+        )
+        print(f"    Done in {time.perf_counter() - t0:.1f}s")
+    
+    def _load_av(self):
+        if self.av_model is not None:
+            return
+        print(f"  Loading AV model ({self.av_model_name} + LoRA)...")
+        t0 = time.perf_counter()
+        base = AutoModelForCausalLM.from_pretrained(
+            self.av_model_name,
+            trust_remote_code=True,
+            torch_dtype=self.dtype,
+            low_cpu_mem_usage=True,
+            attn_implementation="eager",
+        ).to(self.device)
+        self.av_model = PeftModel.from_pretrained(base, AV_CHECKPOINT)
+        self.av_model.eval()
+        self.av_tokenizer = AutoTokenizer.from_pretrained(
+            self.av_model_name, trust_remote_code=True
+        )
+        print(f"    Done in {time.perf_counter() - t0:.1f}s")
+    
+    def _load_ar(self):
+        if self.ar_loaded:
+            return
+        if not AR_CHECKPOINT.exists():
+            print(f"  ⚠️  AR checkpoint not found at {AR_CHECKPOINT}")
+            self.ar_loaded = False
+            return
+        print(f"  Loading AR head...")
+        state = torch.load(AR_CHECKPOINT, map_location=self.device, weights_only=True)
+        # ARHead saved as {'linear.weight': ...} but we want {'weight': ...}
+        if "linear.weight" in state:
+            state = {"weight": state["linear.weight"]}
+        self.ar_head = torch.nn.Linear(self.d_model, self.d_model, bias=False)
+        self.ar_head.load_state_dict(state)
+        self.ar_head.to(self.device)
+        self.ar_head.eval()
+        self.ar_loaded = True
+        print(f"    Done")
+    
+    def extract(self, text: str, position: int = -1):
+        """
+        Extract activation at given layer for the specified token position.
+        If position < 0, uses last token.
+        Returns: (activation_vector [d_model], input_ids, top_tokens)
+        """
+        self._load_base()
+        
+        inputs = self.base_tokenizer(text, return_tensors="pt").to(self.device)
+        seq_len = inputs["input_ids"].shape[1]
+        
+        if position < 0 or position >= seq_len:
+            position = seq_len - 1
+        
+        with torch.no_grad():
+            outputs = self.base_model(
+                **inputs,
+                output_hidden_states=True,
+            )
+        
+        hidden = outputs.hidden_states[self.layer_idx]  # [1, seq, d_model]
+        activation = hidden[0, position, :].cpu()  # [d_model]
+        
+        # Top-k from logits at this position
+        logits = outputs.logits[0, position, :]
+        topk_vals, topk_idxs = torch.topk(logits, k=10)
+        top_tokens = [self.base_tokenizer.decode([t]) for t in topk_idxs]
+        
+        return {
+            "activation": activation,
+            "position": position,
+            "seq_len": seq_len,
+            "token_text": self.base_tokenizer.decode([inputs["input_ids"][0, position].item()]),
+            "top_tokens": top_tokens,
+            "activation_norm": activation.norm().item(),
+        }
+    
+    def explain(self, activation: torch.Tensor, max_new_tokens=64):
+        """Generate AV explanation from activation vector."""
+        self._load_av()
+        
+        prompt = f"<concept>{self.inj_char}</concept>\n<explanation>"
+        inputs = self.av_tokenizer(prompt, return_tensors="pt").to(self.device)
+        
+        # Inject activation at injection token position
+        embeds = self.av_model.get_input_embeddings()(inputs["input_ids"])
+        inj_positions = (inputs["input_ids"][0] == self.inj_token_id).nonzero(as_tuple=True)[0]
+        
+        if len(inj_positions) > 0:
+            inj_pos = inj_positions[0].item()
+            # Normalize activation to injection_scale norm
+            norm = activation.norm()
+            if norm > 0:
+                activation = activation / norm * self.inj_scale
+            scaled_act = activation.to(embeds.dtype).to(self.device)
+            embeds[0, inj_pos, :] = scaled_act
+        
+        with torch.no_grad():
+            output_ids = self.av_model.generate(
+                inputs_embeds=embeds,
+                max_new_tokens=max_new_tokens,
+                do_sample=False,
+                pad_token_id=self.av_tokenizer.pad_token_id or self.av_tokenizer.eos_token_id,
+            )
+        
+        # Extract just the generated part (token-level, not string-level)
+        prompt_len_tokens = inputs["input_ids"].shape[1]
+        gen_token_ids = output_ids[0][prompt_len_tokens:]
+        explanation = self.av_tokenizer.decode(gen_token_ids, skip_special_tokens=True).strip()
+        
+        return {
+            "explanation": explanation,
+        }
+    
+    def reconstruct(self, explanation: str):
+        """AR: explanation text → reconstructed activation + metrics."""
+        self._load_ar()
+        self._load_base()
+        
+        if not self.ar_loaded:
+            return {"error": "AR checkpoint not available"}
+        
+        # Tokenize explanation with base model's tokenizer
+        inputs = self.base_tokenizer(
+            explanation,
+            return_tensors="pt",
+            truncation=True,
+            max_length=128,
+        ).to(self.device)
+        
+        with torch.no_grad():
+            outputs = self.base_model(
+                **inputs,
+                output_hidden_states=True,
+            )
+            last_hidden = outputs.hidden_states[-1]
+            seq_len = inputs["attention_mask"].sum(dim=1) - 1
+            last_token_hidden = last_hidden[0, seq_len[0], :]
+            
+            reconstructed = self.ar_head(last_token_hidden)
+        
+        return {"reconstructed": reconstructed.cpu()}
+    
+    def roundtrip(self, text: str, position: int = -1):
+        """Full round-trip: extract → explain → reconstruct."""
+        # Extract
+        ext = self.extract(text, position)
+        activation = ext["activation"]
+        
+        # Explain
+        expl = self.explain(activation)
+        
+        # Reconstruct
+        rec = self.reconstruct(expl["explanation"])
+        
+        result = {
+            "text": text,
+            "position": ext["position"],
+            "token_text": ext["token_text"],
+            "activation_norm": ext["activation_norm"],
+            "top_tokens": ext["top_tokens"],
+            "av_explanation": expl["explanation"],
+        }
+        
+        if "reconstructed" in rec:
+            orig_n = F.normalize(activation.unsqueeze(0), dim=-1)
+            recon = rec["reconstructed"].unsqueeze(0)
+            recon_n = F.normalize(recon, dim=-1)
+            cosine = (orig_n * recon_n).sum(dim=-1).item()
+            mse = F.mse_loss(orig_n, recon_n).item()
+            
+            result["ar_cosine"] = round(cosine, 4)
+            result["ar_normalized_mse"] = round(mse, 6)
+        
+        return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Tiny-NLA Inference")
+    parser.add_argument("--text", type=str, help="Input text")
+    parser.add_argument("--position", type=int, default=-1, help="Token position (-1 = last)")
+    parser.add_argument("--interactive", action="store_true", help="Interactive mode")
+    parser.add_argument("--batch", type=str, help="JSON file with list of {text, position}")
+    args = parser.parse_args()
+    
+    nla = TinyNLA()
+    
+    if args.interactive:
+        print("Tiny-NLA Interactive Mode (Ctrl+D to exit)\n")
+        while True:
+            try:
+                text = input("Text: ").strip()
+                if not text:
+                    continue
+                pos_input = input("Position (default=last): ").strip()
+                pos = int(pos_input) if pos_input else -1
+                
+                print("\n  Processing...")
+                result = nla.roundtrip(text, pos)
+                
+                print(f"\n  Token:       {result['token_text']!r}")
+                print(f"  Position:    {result['position']}")
+                print(f"  Top tokens:  {result['top_tokens'][:5]}")
+                print(f"  AV:          {result['av_explanation'][:120]}")
+                if "ar_cosine" in result:
+                    print(f"  AR cosine:   {result['ar_cosine']}")
+                print()
+            except EOFError:
+                break
+    
+    elif args.text:
+        result = nla.roundtrip(args.text, args.position)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    
+    elif args.batch:
+        with open(args.batch, "r", encoding="utf-8") as f:
+            batch = json.load(f)
+        results = []
+        for item in batch:
+            r = nla.roundtrip(item["text"], item.get("position", -1))
+            results.append(r)
+            print(f"  [{len(results)}/{len(batch)}] {r['token_text']!r} -> cosine={r.get('ar_cosine', 'N/A')}")
+        
+        out_path = Path(args.batch).parent / "roundtrip_results.json"
+        with open(out_path, "w", encoding="utf-8") as f:
+            json.dump(results, f, ensure_ascii=False, indent=2)
+        print(f"\n  Results saved to {out_path}")
+    
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/nla_meta.yaml

@@ -0,0 +1,48 @@
+kind: tiny_nla_model
+base_model: Qwen/Qwen3-0.6B-Base
+av_init_model: Qwen/Qwen3-0.6B
+layer_index: 19
+num_hidden_layers: 28
+d_model: 1024
+activation_source: residual_stream
+token_position_policy: selected_token
+extraction:
+  injection_scale: 126.223
+  mse_normalization: l2_direction
+tokens:
+  injection_char: ㈎
+  injection_token_id: 149705
+prompt_templates:
+  av: '<concept>{injection_char}</concept>
+
+    <explanation>'
+  ar: <explanation>{explanation_text}</explanation>
+training:
+  device: mps
+  dtype: torch.float32
+  dataset_size: 284
+  teacher: local_qwen_instruct
+  created_at: '2026-06-16T21:43:52'
+av_results:
+  best_val_loss: 0.6400
+  lora_r: 8
+  lora_alpha: 16
+  checkpoint: artifacts/tiny_nla/checkpoints/av
+ar_results:
+  best_val_cosine: 0.6631
+  best_val_loss: 0.000658
+  mean_baseline_cosine: 0.5962
+  shuffled_baseline_cosine: 0.5252
+  improvement_over_mean: 0.0669
+  checkpoint: artifacts/tiny_nla/checkpoints/ar/best_ar_head.pt
+activation_stats:
+  mean: 125.85986328125
+  p50: 126.22295379638672
+  p90: 127.06012725830078
+  max: 129.3959503173828
+  min: 120.7603988647461
+  std: 3.65517520904541
+smoke_test:
+  forward_ok: true
+  gen_ok: true
+  cosine_post_injection: 0.5979639887809753

experiments/tiny_nla/postprocess_dataset.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Post-process dataset: clean teacher explanations by stripping <think> blocks.
+Qwen3 instruct outputs reasoning in <think>...</think> tags.
+We want only the text after </think>.
+
+Also generates an improved dataset with augmented prompt templates.
+"""
+
+import json, re, random
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+
+JSONL_PATH = ARTIFACTS_DIR / "dataset.jsonl"
+ACT_PATH = ARTIFACTS_DIR / "activations.pt"
+
+
+def clean_explanation(text: str) -> str:
+    """Strip <think> blocks, extract only the answer text."""
+    if not text:
+        return ""
+    # Remove <think>...</think> blocks (possibly with newlines)
+    cleaned = re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
+    cleaned = cleaned.strip()
+    # Also strip leading/trailing whitespace per line
+    cleaned = '\n'.join(line.strip() for line in cleaned.split('\n') if line.strip())
+    # If after stripping think there's still nothing, keep minimal
+    if not cleaned:
+        # Try to salvage something from within think
+        inner = re.search(r'<think>(.*?)</think>', text, re.DOTALL)
+        if inner:
+            cleaned = inner.group(1).strip()[:100]
+    return cleaned
+
+
+def is_empty_or_useless(text: str) -> bool:
+    """Check if explanation is empty or just boilerplate."""
+    if not text or len(text) < 5:
+        return True
+    useless = ["[空输出]", "[生成失败", "<think>"]
+    if any(u in text for u in useless):
+        return True
+    return False
+
+
+def main():
+    print("=" * 60)
+    print("🧹 Post-Processing Dataset")
+    print("=" * 60)
+    
+    # Load dataset
+    records = []
+    with open(JSONL_PATH, "r", encoding="utf-8") as f:
+        for line in f:
+            records.append(json.loads(line))
+    print(f"  Loaded {len(records)} records from {JSONL_PATH}")
+    
+    # Check stats before
+    empty_before = sum(1 for r in records if is_empty_or_useless(r.get("teacher_explanation", "")))
+    has_think = sum(1 for r in records if "<think>" in r.get("teacher_explanation", ""))
+    print(f"  Before cleaning:")
+    print(f"    Empty/useless: {empty_before}")
+    print(f"    Contains <think>: {has_think}")
+    
+    # Clean explanations
+    for r in records:
+        raw = r.get("teacher_explanation", "")
+        cleaned = clean_explanation(raw)
+        r["teacher_explanation_raw"] = raw  # keep original
+        r["teacher_explanation"] = cleaned
+    
+    empty_after = sum(1 for r in records if is_empty_or_useless(r.get("teacher_explanation", "")))
+    print(f"  After cleaning:")
+    print(f"    Empty/useless: {empty_after}")
+    
+    # Check quality
+    print("\n  Sample cleaned explanations:")
+    sample = random.Random(42).sample(records, 8)
+    for r in sample:
+        print(f"    [{r['token_text']!r:10}] {r['teacher_explanation'][:80]}")
+    
+    # Save cleaned dataset
+    with open(JSONL_PATH, "w", encoding="utf-8") as f:
+        for r in records:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"\n  ✅ Saved cleaned dataset to {JSONL_PATH}")
+    
+    # Also save a separate "av ready" format (for AV training directly)
+    av_data = []
+    for r in records:
+        if not is_empty_or_useless(r.get("teacher_explanation", "")):
+            av_data.append({
+                "text": r["text"],
+                "token_text": r["token_text"],
+                "pos": r["pos"],
+                "teacher_explanation": r["teacher_explanation"],
+                "top_tokens": r["top_tokens"],
+            })
+    
+    av_path = ARTIFACTS_DIR / "av_training_data.json"
+    with open(av_path, "w", encoding="utf-8") as f:
+        json.dump(av_data, f, ensure_ascii=False, indent=2)
+    print(f"  ✅ Saved AV-ready data ({len(av_data)} samples) to {av_path}")
+    
+    print("\n✅ Post-processing complete!")
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/smoke_stage0.py

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+"""
+Stage 0: Environment & Injection Smoke
+
+Loads Qwen3-0.6B-Base, checks device, inspects model config,
+extracts activations from ~2/3 depth layer, finds stats,
+identifies a single-token injection character, and runs
+an input_embeds injection smoke test.
+
+Output: prints report + writes nla_meta.yaml sidecar
+"""
+
+import os, sys, json, math, yaml, time
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# ── paths ──────────────────────────────────────────────
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+BASE_MODEL = "Qwen/Qwen3-0.6B-Base"
+INSTRUCT_MODEL = "Qwen/Qwen3-0.6B"
+
+# ── device detection ───────────────────────────────────
+def detect_device():
+    """MPS preferred, CPU fallback. Prints diagnostics."""
+    print("=" * 60)
+    print("🔧 Device Detection")
+    print("=" * 60)
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+        print(f"  ✅ CUDA available: {torch.cuda.get_device_name()}")
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        device = torch.device("mps")
+        print(f"  ✅ MPS available (Apple Silicon)")
+    else:
+        device = torch.device("cpu")
+        print(f"  ⚠️  No accelerator, using CPU")
+    print(f"  → Using device: {device}")
+    print()
+    return device
+
+
+def mps_backward_smoke(device: torch.device):
+    """Quick backward pass test on MPS to detect flaky ops."""
+    if device.type != "mps":
+        return True
+    print("  🔬 MPS backward smoke test...")
+    try:
+        x = torch.randn(2, 64, 1536, device=device, requires_grad=True)
+        loss = (x ** 2).mean()
+        loss.backward()
+        print(f"  ✅ MPS backward: OK (grad norm={x.grad.norm():.4f})")
+        return True
+    except Exception as e:
+        print(f"  ❌ MPS backward FAILED: {e}")
+        print(f"  ⚠️  Falling back to CPU")
+        return False
+
+
+def get_dtype_for_device(device: torch.device):
+    """Pick dtype per device. MPS float16 can be flaky → use float32."""
+    if device.type == "cuda":
+        return torch.float16
+    elif device.type == "mps":
+        # MPS float16 backward can fail on some ops; float32 is safe
+        print("  ℹ️  Using float32 on MPS (safer for backward)")
+        return torch.float32
+    return torch.float32
+
+
+# ── model loading ──────────────────────────────────────
+def load_model_and_tokenizer(model_name: str, device: torch.device, dtype: torch.dtype):
+    """Load model in eval mode on target device with proper settings."""
+    print(f"  Loading {model_name}...")
+    t0 = time.perf_counter()
+    model = AutoModelForCausalLM.from_pretrained(
+        model_name,
+        trust_remote_code=True,
+        torch_dtype=dtype,
+        low_cpu_mem_usage=True,
+        attn_implementation="eager",  # safest for MPS/CPU
+    ).to(device)
+    model.eval()
+    tok = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
+    load_time = time.perf_counter() - t0
+    n_params = sum(p.numel() for p in model.parameters())
+    print(f"  ✅ Loaded: {n_params/1e6:.1f}M params in {load_time:.1f}s")
+    return model, tok
+
+
+# ── model inspection ───────────────────────────────────
+def inspect_model(model) -> dict:
+    """Read config and print architecture info."""
+    cfg = model.config
+    info = {
+        "num_hidden_layers": cfg.num_hidden_layers,
+        "hidden_size": cfg.hidden_size,
+        "vocab_size": cfg.vocab_size,
+        "intermediate_size": cfg.intermediate_size,
+        "num_attention_heads": cfg.num_attention_heads,
+        "num_key_value_heads": getattr(cfg, "num_key_value_heads", cfg.num_attention_heads),
+    }
+    info["layer_index"] = round(info["num_hidden_layers"] * 2 / 3)
+
+    print("=" * 60)
+    print("📐 Model Architecture")
+    print("=" * 60)
+    for k, v in info.items():
+        print(f"  {k}: {v}")
+    print(f"  layer_index (2/3 depth): {info['layer_index']}")
+    print()
+    return info
+
+
+# ── activation extraction ──────────────────────────────
+def extract_activation(model, tokenizer, text: str, layer_idx: int, device: torch.device):
+    """
+    Run forward with output_hidden_states=True, extract residual stream
+    at given layer for the last token position.
+    Returns: (activation_vector: torch.Tensor [d_model], token_ids, top_logits)
+    """
+    inputs = tokenizer(text, return_tensors="pt").to(device)
+    with torch.no_grad():
+        outputs = model(
+            **inputs,
+            output_hidden_states=True,
+        )
+    # hidden_states is tuple of (layer+1) x (batch, seq, d_model)
+    # index layer_idx gives the residual stream AFTER that layer
+    hidden = outputs.hidden_states[layer_idx]  # [1, seq, d_model]
+    # take last token activation
+    act = hidden[0, -1, :]  # [d_model]
+    # also get logits for top-k
+    logits = outputs.logits[0, -1, :]  # [vocab]
+    top_vals, top_idxs = torch.topk(logits, k=10)
+    return act.cpu(), inputs["input_ids"][0], top_idxs.cpu(), top_vals.cpu()
+
+
+def compute_activation_stats(activations: list):
+    """Compute L2 norm stats over a list of activation vectors."""
+    norms_list = [a.norm().item() for a in activations]
+    norms_t = torch.tensor(norms_list)
+    stats = {
+        "mean": norms_t.mean().item(),
+        "p50": norms_t.median().item(),
+        "p90": norms_t.kthvalue(max(1, int(len(norms_t) * 0.9))).values.item(),
+        "max": norms_t.max().item(),
+        "min": norms_t.min().item(),
+        "std": norms_t.std().item(),
+    }
+    return stats
+
+
+# ── injection token search ─────────────────────────────
+def find_injection_token(tokenizer) -> tuple:
+    """
+    Find a rare character that tokenizes as a single token.
+    Returns (char, token_id).
+    """
+    # Candidates: CJK rare chars that are likely single tokens
+    candidates = [
+        "㈎", "㈏", "㈐", "㈑", "㈒", "㈓", "㈔", "㈕", "㈖", "㈗",
+        "㈘", "㈙", "㈚", "㈛", "㈜", "㈝", "㈞",
+        "ⓐ", "ⓑ", "ⓒ", "ⓓ", "ⓔ", "ⓕ",
+        "🀀", "🀁", "🀂", "🀃", "🀄", "🀅",
+        "✪", "✫", "✬", "✭", "✮", "✯",
+        "〓", "■", "□", "◆", "◇",
+    ]
+
+    print("=" * 60)
+    print("🔤 Injection Token Search")
+    print("=" * 60)
+
+    for char in candidates:
+        encoded = tokenizer.encode(char, add_special_tokens=False)
+        if len(encoded) == 1:
+            tid = encoded[0]
+            # Verify roundtrip
+            decoded = tokenizer.decode([tid])
+            print(f"  ✅ Found single token: {char!r} -> id={tid} (decode: {decoded!r})")
+            return char, tid
+
+    # Fallback: search for ANY single-token char more systematically
+    print("  ⚠️  Searching more broadly for single-token chars...")
+    for codepoint in range(0x4E00, 0x9FFF):  # CJK Unified
+        char = chr(codepoint)
+        encoded = tokenizer.encode(char, add_special_tokens=False)
+        if len(encoded) == 1:
+            tid = encoded[0]
+            decoded = tokenizer.decode([tid])
+            print(f"  ✅ Found: {char!r} (U+{codepoint:04X}) -> id={tid}")
+            return char, tid
+
+    raise RuntimeError("Could not find a single-token injection character!")
+
+
+# ── injection smoke test ───────────────────────────────
+def injection_smoke(
+    model, tokenizer, device, dtype,
+    layer_idx: int, injection_scale: float, injection_char: str, injection_token_id: int,
+):
+    """
+    Build a prompt, replace injection token embedding with scaled activation,
+    run forward + generation. Verify no crash and shape mismatch.
+    """
+    print("=" * 60)
+    print("🧪 Injection Smoke Test")
+    print("=" * 60)
+
+    prompt = f"Context: 这是一个测试句子。\n<concept>{injection_char}</concept>\n<explanation>"
+    print(f"  Prompt: {prompt!r}")
+
+    # Tokenize
+    inputs = tokenizer(prompt, return_tensors="pt").to(device)
+    input_ids = inputs["input_ids"]
+    print(f"  Input shape: {input_ids.shape}")
+
+    # Find the injection token position
+    inj_ids = (input_ids[0] == injection_token_id).nonzero(as_tuple=True)[0]
+    if len(inj_ids) == 0:
+        raise RuntimeError(f"Injection token {injection_char!r} (id={injection_token_id}) not found in prompt!")
+    inj_pos = inj_ids[0].item()
+    print(f"  Injection token at position: {inj_pos}")
+
+    # Get a dummy activation vector: random vector scaled to injection_scale
+    model_config = model.config
+    d_model = model_config.hidden_size
+    dummy_act = torch.randn(d_model, device=device, dtype=dtype)
+    dummy_act = dummy_act / dummy_act.norm() * injection_scale
+
+    # Forward with input_embeds injection
+    with torch.no_grad():
+        # Get base embeddings
+        embeds = model.get_input_embeddings()(input_ids)  # [1, seq, d_model]
+        # Replace the injection position's embedding with our activation
+        embeds[0, inj_pos, :] = dummy_act
+
+        # Forward with input_embeds
+        outputs = model(inputs_embeds=embeds, output_hidden_states=True)
+        logits = outputs.logits
+        print(f"  Forward output shape: {logits.shape} ✅")
+
+        # Extract the hidden state at injection position from layer layer_idx
+        hidden = outputs.hidden_states[layer_idx]
+        injected_act = hidden[0, inj_pos, :]
+        print(f"  Hidden at injection pos, layer {layer_idx}: shape={injected_act.shape} ✅")
+
+        # Compare input activation vs post-layer activation
+        cos_sim = F.cosine_similarity(dummy_act.unsqueeze(0), injected_act.unsqueeze(0))
+        print(f"  Cosine(input_act, post_layer_{layer_idx}_act): {cos_sim.item():.4f}")
+
+    # Generation test — greedy
+    print("\n  🔄 Generation test (greedy, max 20 tokens)...")
+    gen_outputs = model.generate(
+        inputs_embeds=embeds,
+        max_new_tokens=20,
+        do_sample=False,
+        pad_token_id=tokenizer.pad_token_id or tokenizer.eos_token_id,
+    )
+    gen_text = tokenizer.decode(gen_outputs[0], skip_special_tokens=True)
+    print(f"  Generated: {gen_text!r}")
+    print(f"  ✅ Injection generation completed without error")
+
+    return {
+        "forward_ok": True,
+        "gen_ok": True,
+        "cosine_post_injection": cos_sim.item(),
+    }
+
+
+# ── main ───────────────────────────────────────────────
+def main():
+    print("=" * 60)
+    print("🏗️  TINY-NLA STAGE 0 — Environment & Injection Smoke")
+    print("=" * 60)
+    print()
+
+    # 1. Device
+    device = detect_device()
+
+    # 2. MPS backward smoke
+    if not mps_backward_smoke(device):
+        device = torch.device("cpu")
+
+    # 3. dtype
+    dtype = get_dtype_for_device(device)
+    print(f"  Using dtype: {dtype}")
+    print()
+
+    # 4. Load model
+    model, tokenizer = load_model_and_tokenizer(BASE_MODEL, device, dtype)
+
+    # 5. Inspect
+    info = inspect_model(model)
+    layer_idx = info["layer_index"]
+    d_model = info["hidden_size"]
+
+    # 6. Extract sample activations
+    print("=" * 60)
+    print("📊 Sample Activation Extraction")
+    print("=" * 60)
+    sample_texts = [
+        "人工智能正在改变世界。",
+        "深度学习模型可以学习复杂模式。",
+        "今天天气真好，适合出去散步。",
+        "Qwen3是一个强大的语言模型。",
+    ]
+    activations = []
+    for txt in sample_texts:
+        act, ids, topk_ids, topk_vals = extract_activation(model, tokenizer, txt, layer_idx, device)
+        activations.append(act)
+        top_tokens = [tokenizer.decode([t]) for t in topk_ids[:3]]
+        print(f"  Text: {txt}")
+        print(f"    Last token activation norm: {act.norm():.4f}")
+        print(f"    Top-3 next tokens: {top_tokens}")
+
+    # 7. Activation stats
+    act_stats = compute_activation_stats(activations)
+    print()
+    print("📊 Activation L2 Norm Statistics")
+    print("-" * 40)
+    for k, v in act_stats.items():
+        print(f"  {k}: {v:.4f}")
+
+    injection_scale = round(act_stats["p50"], 4)
+    print(f"\n  → injection_scale = p50 = {injection_scale}")
+
+    # 8. Injection token search
+    inj_char, inj_token_id = find_injection_token(tokenizer)
+    print()
+
+    # 9. Injection smoke test
+    smoke_result = injection_smoke(
+        model, tokenizer, device, dtype,
+        layer_idx, injection_scale, inj_char, inj_token_id,
+    )
+    print()
+
+    # 10. Write nla_meta.yaml
+    meta = {
+        "kind": "tiny_nla_model",
+        "base_model": BASE_MODEL,
+        "av_init_model": INSTRUCT_MODEL,
+        "layer_index": layer_idx,
+        "num_hidden_layers": info["num_hidden_layers"],
+        "d_model": d_model,
+        "activation_source": "residual_stream",
+        "token_position_policy": "selected_token",
+        "extraction": {
+            "injection_scale": injection_scale,
+            "mse_normalization": "l2_direction",
+        },
+        "tokens": {
+            "injection_char": inj_char,
+            "injection_token_id": inj_token_id,
+        },
+        "prompt_templates": {
+            "av": f"<concept>{{injection_char}}</concept>\n<explanation>",
+            "ar": f"<explanation>{{explanation_text}}</explanation>",
+        },
+        "training": {
+            "device": device.type,
+            "dtype": str(dtype),
+            "dataset_size": 0,
+            "teacher": "local_qwen_instruct",
+            "created_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        },
+        "activation_stats": act_stats,
+        "smoke_test": smoke_result,
+    }
+
+    with open(SIDECAR_PATH, "w", encoding="utf-8") as f:
+        yaml.dump(meta, f, allow_unicode=True, sort_keys=False, default_flow_style=False)
+    print(f"  ✅ Sidecar written: {SIDECAR_PATH}")
+
+    # 11. Summary
+    print()
+    print("=" * 60)
+    print("✅ STAGE 0 COMPLETE")
+    print("=" * 60)
+    print(f"  Device:           {device.type}")
+    print(f"  dtype:            {dtype}")
+    print(f"  Layers:           {info['num_hidden_layers']}")
+    print(f"  Selected layer:   {layer_idx} ({layer_idx/info['num_hidden_layers']*100:.0f}% depth)")
+    print(f"  d_model:          {d_model}")
+    print(f"  Injection char:   {inj_char!r} (id={inj_token_id})")
+    print(f"  Injection scale:  {injection_scale}")
+    print(f"  Forward smoke:    {'✅ PASS' if smoke_result['forward_ok'] else '❌ FAIL'}")
+    print(f"  Generation smoke: {'✅ PASS' if smoke_result['gen_ok'] else '❌ FAIL'}")
+    print(f"  Sidecar:          {SIDECAR_PATH}")
+    print()
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/train_ar.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""
+Stage 1: AR SFT — Activation Reconstructor
+
+Input:  explanation text (via teacher)
+Output: reconstructed activation vector (d_model)
+
+Architecture:
+  - Qwen3-0.6B-Base trunk (frozen)
+  - Linear(d_model, d_model) head on last token hidden state
+  - L2-normalized MSE loss
+
+Baselines:
+  - Mean vector baseline (always predict mean activation)
+  - Shuffled label baseline (random pairing)
+"""
+
+import json, os, time, math, yaml, random
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import Dataset, DataLoader
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# ── paths ──────────────────────────────────────────────
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+CHECKPOINT_DIR = ARTIFACTS_DIR / "checkpoints" / "ar"
+CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+
+BASE_MODEL = "Qwen/Qwen3-0.6B-Base"
+
+# ── device ─────────────────────────────────────────────
+def detect_device():
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+# ── AR Head ────────────────────────────────────────────
+class ARHead(nn.Module):
+    """Simple linear projection from d_model to d_model."""
+    def __init__(self, d_model: int):
+        super().__init__()
+        self.linear = nn.Linear(d_model, d_model, bias=False)
+    
+    def forward(self, x):
+        # x: [batch, d_model] — last token hidden state
+        return self.linear(x)
+
+
+# ── Dataset ────────────────────────────────────────────
+class ARDataset(Dataset):
+    """Explanation text → activation vector."""
+    def __init__(self, records, activations, tokenizer, max_length=128):
+        self.tokenizer = tokenizer
+        self.max_length = max_length
+        self.data = []
+        
+        for rec, act in zip(records, activations):
+            explanation = rec.get("teacher_explanation", "") or rec.get("teacher_explanation_raw", "")
+            if not explanation or explanation in ("[空输出]", ""):
+                continue
+            self.data.append((explanation, act))
+    
+    def __len__(self):
+        return len(self.data)
+    
+    def __getitem__(self, idx):
+        text, act = self.data[idx]
+        tokens = self.tokenizer(
+            text,
+            truncation=True,
+            padding="max_length",
+            max_length=self.max_length,
+            return_tensors="pt",
+        )
+        return {
+            "input_ids": tokens["input_ids"][0],
+            "attention_mask": tokens["attention_mask"][0],
+            "target": act,  # [d_model]
+        }
+
+
+# ── Loss ───────────────────────────────────────────────
+def normalized_mse_loss(pred, target):
+    """
+    L2-normalize both, then MSE = 2*(1-cosine)
+    Equivalent to ||normalized_pred - normalized_target||²
+    """
+    pred_n = F.normalize(pred, dim=-1)
+    target_n = F.normalize(target, dim=-1)
+    return F.mse_loss(pred_n, target_n)
+
+
+def cosine_similarity(pred, target):
+    pred_n = F.normalize(pred, dim=-1)
+    target_n = F.normalize(target, dim=-1)
+    return (pred_n * target_n).sum(dim=-1)
+
+
+# ── Training ───────────────────────────────────────────
+def train():
+    print("=" * 60)
+    print("🔧 AR SFT — Activation Reconstructor Training")
+    print("=" * 60)
+    
+    device = detect_device()
+    dtype = torch.float32
+    print(f"  Device: {device}, dtype: {dtype}")
+    
+    # Load sidecar
+    with open(SIDECAR_PATH, "r") as f:
+        nla_meta = yaml.safe_load(f)
+    d_model = nla_meta["d_model"]
+    print(f"  d_model: {d_model}")
+    
+    # Load dataset
+    print("\n  Loading dataset...")
+    jsonl_path = ARTIFACTS_DIR / "dataset.jsonl"
+    act_path = ARTIFACTS_DIR / "activations.pt"
+    
+    records = []
+    with open(jsonl_path, "r", encoding="utf-8") as f:
+        for line in f:
+            records.append(json.loads(line))
+    activations = torch.load(act_path, weights_only=True)
+    print(f"  Loaded {len(records)} records, activations shape: {activations.shape}")
+    
+    # Train/val split
+    random.seed(42)
+    indices = list(range(len(records)))
+    random.shuffle(indices)
+    val_size = max(1, int(len(indices) * 0.15))
+    train_idx, val_idx = indices[val_size:], indices[:val_size]
+    print(f"  Train: {len(train_idx)}, Val: {len(val_idx)}")
+    
+    # Load tokenizer
+    tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+    tokenizer.pad_token = tokenizer.eos_token
+    
+    train_records = [records[i] for i in train_idx]
+    train_acts = activations[train_idx]
+    val_records = [records[i] for i in val_idx]
+    val_acts = activations[val_idx]
+    
+    train_dataset = ARDataset(train_records, train_acts, tokenizer)
+    val_dataset = ARDataset(val_records, val_acts, tokenizer)
+    print(f"  Train dataset: {len(train_dataset)}, Val dataset: {len(val_dataset)}")
+    
+    train_loader = DataLoader(train_dataset, batch_size=8, shuffle=True)
+    val_loader = DataLoader(val_dataset, batch_size=8, shuffle=False)
+    
+    # Load base model (frozen)
+    print("\n  Loading base model (frozen)...")
+    t0 = time.perf_counter()
+    base_model = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL,
+        trust_remote_code=True,
+        torch_dtype=dtype,
+        low_cpu_mem_usage=True,
+        attn_implementation="eager",
+    ).to(device)
+    base_model.eval()
+    for p in base_model.parameters():
+        p.requires_grad = False
+    print(f"  Base model loaded in {time.perf_counter() - t0:.1f}s")
+    
+    # AR head
+    ar_head = ARHead(d_model).to(device)
+    print(f"  AR head params: {sum(p.numel() for p in ar_head.parameters()):,}")
+    
+    optimizer = torch.optim.AdamW(ar_head.parameters(), lr=1e-3)
+    
+    # ── Compute baselines ──
+    print("\n📊 Computing baselines...")
+    
+    # Mean vector baseline
+    all_train_acts = torch.stack([train_dataset[i]["target"] for i in range(len(train_dataset))])
+    mean_vec = all_train_acts.mean(dim=0)  # [d_model]
+    
+    mean_cosines = []
+    for i in range(len(val_dataset)):
+        target = val_dataset[i]["target"]
+        cos = F.cosine_similarity(mean_vec.unsqueeze(0), target.unsqueeze(0))
+        mean_cosines.append(cos.item())
+    mean_baseline = torch.tensor(mean_cosines).mean().item()
+    print(f"  Mean-vector baseline cosine: {mean_baseline:.4f}")
+    
+    # Shuffled baseline
+    val_targets = torch.stack([val_dataset[i]["target"] for i in range(len(val_dataset))])
+    shuffled = val_targets[torch.randperm(len(val_targets))]
+    shuffled_cosines = F.cosine_similarity(val_targets, shuffled, dim=-1)
+    shuffled_baseline = shuffled_cosines.mean().item()
+    print(f"  Shuffled baseline cosine:      {shuffled_baseline:.4f}")
+    
+    # ── Training loop ──
+    print("\n🏋️  Training AR head...")
+    n_epochs = 50
+    best_val_loss = float("inf")
+    best_val_cosine = 0.0
+    
+    for epoch in range(n_epochs):
+        # Train
+        ar_head.train()
+        total_loss = 0.0
+        n_batches = 0
+        
+        for batch in train_loader:
+            input_ids = batch["input_ids"].to(device)
+            attention_mask = batch["attention_mask"].to(device)
+            targets = batch["target"].to(device)
+            
+            with torch.no_grad():
+                outputs = base_model(
+                    input_ids=input_ids,
+                    attention_mask=attention_mask,
+                    output_hidden_states=True,
+                )
+                # Get last token hidden state from last layer
+                last_hidden = outputs.hidden_states[-1]  # [batch, seq, d_model]
+                # Use the last non-pad token position
+                seq_lens = attention_mask.sum(dim=1) - 1
+                batch_indices = torch.arange(last_hidden.size(0), device=device)
+                last_token_hidden = last_hidden[batch_indices, seq_lens, :]  # [batch, d_model]
+            
+            pred = ar_head(last_token_hidden)
+            loss = normalized_mse_loss(pred, targets)
+            
+            optimizer.zero_grad()
+            loss.backward()
+            optimizer.step()
+            
+            total_loss += loss.item()
+            n_batches += 1
+        
+        avg_train_loss = total_loss / n_batches
+        
+        # Validation
+        ar_head.eval()
+        val_losses = []
+        val_cosines = []
+        
+        with torch.no_grad():
+            for batch in val_loader:
+                input_ids = batch["input_ids"].to(device)
+                attention_mask = batch["attention_mask"].to(device)
+                targets = batch["target"].to(device)
+                
+                outputs = base_model(
+                    input_ids=input_ids,
+                    attention_mask=attention_mask,
+                    output_hidden_states=True,
+                )
+                last_hidden = outputs.hidden_states[-1]
+                seq_lens = attention_mask.sum(dim=1) - 1
+                batch_indices = torch.arange(last_hidden.size(0), device=device)
+                last_token_hidden = last_hidden[batch_indices, seq_lens, :]
+                
+                pred = ar_head(last_token_hidden)
+                loss = normalized_mse_loss(pred, targets)
+                cos = cosine_similarity(pred, targets)
+                
+                val_losses.append(loss.item())
+                val_cosines.extend(cos.cpu().tolist())
+        
+        avg_val_loss = sum(val_losses) / len(val_losses)
+        avg_val_cosine = sum(val_cosines) / len(val_cosines)
+        
+        if avg_val_cosine > best_val_cosine:
+            best_val_cosine = avg_val_cosine
+            best_val_loss = avg_val_loss
+            torch.save(ar_head.state_dict(), CHECKPOINT_DIR / "best_ar_head.pt")
+        
+        if (epoch + 1) % 5 == 0 or epoch == 0:
+            print(f"  Epoch {epoch+1:2d}/{n_epochs} | train_loss={avg_train_loss:.6f} | val_loss={avg_val_loss:.6f} | val_cos={avg_val_cosine:.4f} | best_cos={best_val_cosine:.4f}")
+    
+    # ── Final evaluation ──
+    print(f"\n📈 Final Results")
+    print(f"  {'':30} {'Loss':>10} {'Cosine':>10}")
+    print(f"  {'Mean-vector baseline':30} {'':>10} {mean_baseline:>10.4f}")
+    print(f"  {'Shuffled baseline':30} {'':>10} {shuffled_baseline:>10.4f}")
+    print(f"  {'AR trained (best)':30} {best_val_loss:>10.6f} {best_val_cosine:>10.4f}")
+    
+    improvement = best_val_cosine - max(mean_baseline, shuffled_baseline)
+    print(f"\n  Improvement over best baseline: {improvement:+.4f}")
+    
+    if improvement <= 0:
+        print("  ⚠️  AR does NOT beat baselines! May need fixes.")
+    
+    print(f"\n  Checkpoint: {CHECKPOINT_DIR / 'best_ar_head.pt'}")
+    
+    return best_val_cosine, best_val_loss
+
+
+if __name__ == "__main__":
+    train()

experiments/tiny_nla/train_av.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+Stage 2: AV SFT — Activation Verbalizer
+
+Fixes vs prior version:
+  1. No padding='max_length' — pad to batch max length with attention_mask
+  2. Pass attention_mask in both train forward and generate
+  3. Generate with prompt-only embeds (not full padded sequence)
+  4. Use attention_mask in AVModel.forward
+"""
+
+import json, os, time, yaml, random
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+from torch.utils.data import Dataset, DataLoader
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import LoraConfig, get_peft_model, TaskType
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SIDECAR_PATH = Path(__file__).resolve().parent / "nla_meta.yaml"
+ARTIFACTS_DIR = REPO_ROOT / "artifacts" / "tiny_nla"
+CHECKPOINT_DIR = ARTIFACTS_DIR / "checkpoints" / "av"
+CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+
+INSTRUCT_MODEL = "Qwen/Qwen3-0.6B"
+
+
+def detect_device():
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+def collate_fn(batch, pad_id):
+    """Pad to batch max length (not global max)."""
+    max_len = max(b["input_ids"].shape[0] for b in batch)
+    input_ids = torch.full((len(batch), max_len), pad_id, dtype=torch.long)
+    attention_mask = torch.zeros(len(batch), max_len, dtype=torch.long)
+    labels = torch.full((len(batch), max_len), -100, dtype=torch.long)
+    activations = torch.stack([b["activation"] for b in batch])
+    prompt_lens = [b["prompt_len"] for b in batch]
+
+    for i, b in enumerate(batch):
+        n = b["input_ids"].shape[0]
+        input_ids[i, :n] = b["input_ids"]
+        attention_mask[i, :n] = 1
+        labels[i, :n] = b["labels"]
+
+    return {
+        "input_ids": input_ids,
+        "attention_mask": attention_mask,
+        "labels": labels,
+        "activations": activations,
+        "prompt_lens": prompt_lens,
+    }
+
+
+class AVDataset(Dataset):
+    def __init__(self, av_data, activations, tokenizer, inj_char, inj_token_id, inj_scale, max_length=96):
+        self.tokenizer = tokenizer
+        self.inj_token_id = inj_token_id
+        self.inj_scale = inj_scale
+        self.max_length = max_length
+        self.inj_char = inj_char
+        self.data = []
+
+        for rec, act in zip(av_data, activations):
+            expl = rec.get("teacher_explanation", "") or ""
+            if not expl.strip() or expl in ("[空输出]",):
+                continue
+            self.data.append((expl, act))
+
+        print(f"  AVDataset: {len(self.data)} samples")
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        explanation, activation = self.data[idx]
+        prompt = f"<concept>{self.inj_char}</concept>\n<explanation>"
+
+        # Tokenize prompt and full sequence separately (no padding here)
+        prompt_ids = self.tokenizer(prompt, return_tensors="pt")["input_ids"][0]
+        expl_ids = self.tokenizer(
+            explanation,
+            add_special_tokens=False,
+            return_tensors="pt",
+        )["input_ids"][0]
+
+        # Truncate explanation if needed
+        max_expl = self.max_length - len(prompt_ids) - 1  # -1 for eos
+        expl_ids = expl_ids[:max_expl]
+
+        # Build full sequence: prompt + explanation + eos
+        eos = torch.tensor([self.tokenizer.eos_token_id], dtype=torch.long)
+        input_ids = torch.cat([prompt_ids, expl_ids, eos])
+
+        # Labels: -100 for prompt, actual ids for explanation+eos
+        labels = torch.full_like(input_ids, -100)
+        labels[len(prompt_ids):] = torch.cat([expl_ids, eos])
+
+        return {
+            "input_ids": input_ids,
+            "labels": labels,
+            "activation": activation,
+            "prompt_len": len(prompt_ids),
+        }
+
+
+class AVModel(nn.Module):
+    def __init__(self, base_model, inj_token_id):
+        super().__init__()
+        self.model = base_model
+        self.inj_token_id = inj_token_id
+
+    def forward(self, input_ids, attention_mask, labels, activations):
+        embeds = self.model.get_input_embeddings()(input_ids)
+
+        for b in range(input_ids.shape[0]):
+            positions = (input_ids[b] == self.inj_token_id).nonzero(as_tuple=True)[0]
+            if len(positions) > 0:
+                embeds[b, positions[0].item(), :] = activations[b].to(embeds.dtype)
+
+        return self.model(
+            inputs_embeds=embeds,
+            attention_mask=attention_mask,
+            labels=labels,
+        )
+
+
+def scale_activations(acts, scale, device):
+    acts = acts.to(device)
+    norms = acts.norm(dim=-1, keepdim=True).clamp(min=1e-6)
+    return acts / norms * scale
+
+
+def train():
+    print("=" * 60)
+    print("AV SFT — Activation Verbalizer Training")
+    print("=" * 60)
+
+    device = detect_device()
+    dtype = torch.float32
+    print(f"  Device: {device}, dtype: {dtype}")
+
+    with open(SIDECAR_PATH) as f:
+        meta = yaml.safe_load(f)
+
+    inj_char = meta["tokens"]["injection_char"]
+    inj_token_id = meta["tokens"]["injection_token_id"]
+    inj_scale = meta["extraction"]["injection_scale"]
+    print(f"  inj_char={inj_char!r} id={inj_token_id} scale={inj_scale}")
+
+    with open(ARTIFACTS_DIR / "av_training_data.json", encoding="utf-8") as f:
+        av_data = json.load(f)
+    activations = torch.load(ARTIFACTS_DIR / "av_activations.pt", weights_only=True)
+    print(f"  Loaded {len(av_data)} records, activations {activations.shape}")
+
+    tokenizer = AutoTokenizer.from_pretrained(INSTRUCT_MODEL, trust_remote_code=True)
+    # Use a different pad token to avoid pad=eos issue
+    tokenizer.pad_token_id = tokenizer.eos_token_id  # needed for generate only
+
+    random.seed(42)
+    idx = list(range(len(av_data)))
+    random.shuffle(idx)
+    val_n = max(20, int(len(idx) * 0.15))
+    train_idx, val_idx = idx[val_n:], idx[:val_n]
+
+    def mk_dataset(indices):
+        return AVDataset(
+            [av_data[i] for i in indices],
+            activations[indices],
+            tokenizer, inj_char, inj_token_id, inj_scale,
+        )
+
+    train_ds = mk_dataset(train_idx)
+    val_ds = mk_dataset(val_idx)
+
+    pad_id = tokenizer.eos_token_id
+    train_loader = DataLoader(train_ds, batch_size=4, shuffle=True,
+                              collate_fn=lambda b: collate_fn(b, pad_id))
+    val_loader = DataLoader(val_ds, batch_size=4, shuffle=False,
+                            collate_fn=lambda b: collate_fn(b, pad_id))
+
+    print(f"\n  Loading {INSTRUCT_MODEL}...")
+    base_model = AutoModelForCausalLM.from_pretrained(
+        INSTRUCT_MODEL, trust_remote_code=True, dtype=dtype,
+        low_cpu_mem_usage=True, attn_implementation="eager",
+    ).to(device)
+
+    lora_cfg = LoraConfig(
+        task_type=TaskType.CAUSAL_LM, r=8, lora_alpha=16,
+        lora_dropout=0.1, target_modules=["q_proj", "v_proj"],
+        bias="none",
+    )
+    lora_model = get_peft_model(base_model, lora_cfg)
+    lora_model.print_trainable_parameters()
+
+    av_model = AVModel(lora_model, inj_token_id).to(device)
+    optimizer = torch.optim.AdamW(av_model.parameters(), lr=1e-4, weight_decay=0.05)
+    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=50, eta_min=5e-6)
+
+    n_epochs = 50
+    best_val_loss = float("inf")
+    patience, patience_count = 10, 0
+
+    for epoch in range(n_epochs):
+        av_model.train()
+        train_losses = []
+        for batch in train_loader:
+            input_ids = batch["input_ids"].to(device)
+            attention_mask = batch["attention_mask"].to(device)
+            labels = batch["labels"].to(device)
+            scaled_acts = scale_activations(batch["activations"].float(), inj_scale, device)
+
+            out = av_model(input_ids, attention_mask, labels, scaled_acts)
+            loss = out.loss
+
+            optimizer.zero_grad()
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(av_model.parameters(), 1.0)
+            optimizer.step()
+            train_losses.append(loss.item())
+
+        av_model.eval()
+        val_losses = []
+        with torch.no_grad():
+            for batch in val_loader:
+                out = av_model(
+                    batch["input_ids"].to(device),
+                    batch["attention_mask"].to(device),
+                    batch["labels"].to(device),
+                    scale_activations(batch["activations"].float(), inj_scale, device),
+                )
+                val_losses.append(out.loss.item())
+
+        tl = sum(train_losses) / len(train_losses)
+        vl = sum(val_losses) / len(val_losses)
+
+        if vl < best_val_loss:
+            best_val_loss = vl
+            patience_count = 0
+            av_model.model.save_pretrained(CHECKPOINT_DIR)
+            tokenizer.save_pretrained(CHECKPOINT_DIR)
+        else:
+            patience_count += 1
+
+        scheduler.step()
+
+        if (epoch + 1) % 5 == 0 or epoch == 0:
+            print(f"  Epoch {epoch+1:2d}/{n_epochs} | train={tl:.4f} | val={vl:.4f} | best={best_val_loss:.4f}")
+
+        if patience_count >= patience:
+            print(f"  Early stop at epoch {epoch+1}")
+            break
+
+    print(f"\n  Best val loss: {best_val_loss:.4f}")
+
+    # ── Generate examples (prompt-only embeds, no padding) ──
+    print("\n  Generating held-out examples...")
+    av_model.eval()
+    examples = []
+
+    # Reload best checkpoint
+    from peft import PeftModel
+    best_base = AutoModelForCausalLM.from_pretrained(
+        INSTRUCT_MODEL, trust_remote_code=True, dtype=dtype,
+        low_cpu_mem_usage=True, attn_implementation="eager",
+    ).to(device)
+    best_model = PeftModel.from_pretrained(best_base, CHECKPOINT_DIR).to(device)
+    best_model.eval()
+
+    prompt_template = f"<concept>{inj_char}</concept>\n<explanation>"
+
+    with torch.no_grad():
+        for i in range(min(25, len(val_ds))):
+            item = val_ds[i]
+            act = item["activation"].unsqueeze(0).float()
+            scaled = scale_activations(act, inj_scale, device)
+
+            # Tokenize prompt only (no padding)
+            p_ids = tokenizer(prompt_template, return_tensors="pt")["input_ids"].to(device)
+            p_mask = torch.ones_like(p_ids)
+
+            embeds = best_model.get_input_embeddings()(p_ids)
+            inj_pos = (p_ids[0] == inj_token_id).nonzero(as_tuple=True)[0]
+            if len(inj_pos) > 0:
+                embeds[0, inj_pos[0].item(), :] = scaled[0].to(embeds.dtype)
+
+            out_ids = best_model.generate(
+                inputs_embeds=embeds,
+                attention_mask=p_mask,
+                max_new_tokens=80,
+                do_sample=False,
+                eos_token_id=tokenizer.eos_token_id,
+                pad_token_id=tokenizer.eos_token_id,
+            )
+            # output_ids when using inputs_embeds: only generated tokens
+            gen_text = tokenizer.decode(out_ids[0], skip_special_tokens=True).strip()
+
+            teacher = tokenizer.decode(
+                item["labels"][item["prompt_len"]:][item["labels"][item["prompt_len"]:] != -100],
+                skip_special_tokens=True,
+            )
+            examples.append({
+                "index": i,
+                "teacher": teacher,
+                "av_generated": gen_text,
+            })
+
+    nonempty = sum(1 for e in examples if e["av_generated"].strip())
+    print(f"  Non-empty: {nonempty}/{len(examples)}")
+    for e in examples[:5]:
+        print(f"    T: {e['teacher'][:60]}")
+        print(f"    G: {e['av_generated'][:80]}")
+        print()
+
+    out_path = ARTIFACTS_DIR / "av_examples.json"
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(examples, f, ensure_ascii=False, indent=2)
+    print(f"  Saved to {out_path}")
+    print(f"\n  LoRA adapter: {CHECKPOINT_DIR}")
+    return best_val_loss
+
+
+if __name__ == "__main__":
+    train()

experiments/tiny_nla/train_rl_grpo.py

@@ -0,0 +1,404 @@
+#!/usr/bin/env python3
+"""
+Phase 3: GRPO RL — AV+AR joint training.
+Reward = -MSE(L2_norm(original), L2_norm(reconstructed))
+Monitor: tensorboard --logdir artifacts/tiny_nla/runs
+
+Usage:
+  python train_rl_grpo.py [--steps 1000] [--group-size 4] [--batch 8]
+"""
+import json, yaml, random, time, argparse, os
+from pathlib import Path
+from datetime import datetime
+
+# Disable HuggingFace network access — use local cache only, no HEAD checks to huggingface.co
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ.setdefault("HF_DATASETS_OFFLINE", "1")
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import pyarrow.parquet as pq
+from torch.utils.tensorboard import SummaryWriter
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel, LoraConfig, get_peft_model, TaskType
+
+REPO_ROOT  = Path(__file__).resolve().parents[2]
+ARTIFACTS  = REPO_ROOT / "artifacts" / "tiny_nla"
+META_PATH  = Path(__file__).resolve().parent / "nla_meta.yaml"
+RUNS_DIR   = ARTIFACTS / "runs"
+
+meta       = yaml.safe_load(open(META_PATH))
+D_MODEL    = meta["d_model"]
+LAYER      = meta["layer_index"]
+INJ_CHAR   = meta["tokens"]["injection_char"]
+INJ_TOK_ID = meta["tokens"]["injection_token_id"]
+INJ_SCALE  = meta["extraction"]["injection_scale"]
+BASE_MODEL = meta["base_model"]
+INST_MODEL = meta["av_init_model"]
+
+
+def get_device():
+    if torch.cuda.is_available():         return torch.device("cuda")
+    if torch.backends.mps.is_available(): return torch.device("mps")
+    return torch.device("cpu")
+
+
+def log(msg):
+    print(f"[{datetime.now().strftime('%H:%M:%S')}] {msg}", flush=True)
+
+
+def scale_acts(acts, dev):
+    a = acts.to(dev).float()
+    return a / a.norm(dim=-1, keepdim=True).clamp(1e-6) * INJ_SCALE
+
+
+def norm_acts(acts, dev):
+    a = acts.to(dev).float()
+    return a / a.norm(dim=-1, keepdim=True).clamp(1e-6)
+
+
+# ── Load activations only (no teacher needed for RL) ─
+def load_activations():
+    table = pq.read_table(ARTIFACTS / "activations_v2.parquet")
+    acts  = torch.tensor([table["activation"][i].as_py()
+                          for i in range(len(table))], dtype=torch.float32)
+    log(f"Loaded {len(acts)} activations | norm {acts.norm(dim=-1).min():.1f}–{acts.norm(dim=-1).max():.1f}")
+    return acts
+
+
+# ── AR head (frozen during RL, used as reward scorer) ─
+class ARHead(nn.Module):
+    def __init__(self, d_model):
+        super().__init__()
+        self.proj = nn.Linear(d_model, d_model, bias=False)
+    def forward(self, h):
+        return F.normalize(self.proj(h), dim=-1)
+
+
+def load_ar(dev):
+    ckpt = torch.load(ARTIFACTS / "checkpoints" / "ar_v2" / "ar_head_v2.pt",
+                      map_location=dev, weights_only=True)
+    head = ARHead(D_MODEL).to(dev)
+    head.load_state_dict(ckpt["head"])
+    head.eval()
+    for p in head.parameters(): p.requires_grad_(False)
+    log(f"AR head loaded (val_cos={ckpt.get('val_cosine',0):.4f})")
+    return head
+
+
+# ── AV: generate explanations for a batch of activations ─
+def av_generate(av_model, tok, acts_scaled, dev, max_new=64, temperature=1.0, num_return=1):
+    """
+    acts_scaled: [B, D] already scaled to INJ_SCALE
+    Returns list of B lists, each with num_return explanation strings.
+    """
+    prompt  = f"<concept>{INJ_CHAR}</concept>\n<explanation>"
+    p_ids   = tok(prompt, return_tensors="pt")["input_ids"].to(dev)
+    p_mask  = torch.ones(1, p_ids.shape[1], device=dev, dtype=torch.long)
+    inj_pos = (p_ids[0] == INJ_TOK_ID).nonzero(as_tuple=True)[0][0].item()
+
+    all_expls = []
+    for b in range(acts_scaled.shape[0]):
+        embeds = av_model.get_input_embeddings()(p_ids).clone()  # [1, P, D]
+        embeds[0, inj_pos] = acts_scaled[b].to(embeds.dtype)
+        expls = []
+        for _ in range(num_return):
+            with torch.no_grad():
+                out = av_model.generate(
+                    inputs_embeds=embeds, attention_mask=p_mask,
+                    max_new_tokens=max_new,
+                    do_sample=(temperature > 0),
+                    temperature=temperature if temperature > 0 else 1.0,
+                    pad_token_id=tok.eos_token_id,
+                )
+            expls.append(tok.decode(out[0], skip_special_tokens=True).strip())
+        all_expls.append(expls)
+    return all_expls
+
+
+# ── AR reconstruct explanations → activation ─────────
+def ar_reconstruct(ar_backbone, ar_head, tok, explanations, dev):
+    """
+    explanations: list of strings
+    Returns: [N, D] normalized reconstructions (float32 for stable cosine)
+    """
+    tok.pad_token_id = tok.eos_token_id
+    enc = tok(explanations, return_tensors="pt", padding=True,
+              truncation=True, max_length=128).to(dev)
+    with torch.no_grad():
+        h = ar_backbone(**enc, output_hidden_states=True).hidden_states[-1]
+        lens = enc["attention_mask"].sum(1) - 1
+        last = h[torch.arange(len(h)), lens]
+        recon = ar_head(last)
+    return recon.float()  # cast to float32 for downstream cosine
+
+
+# ── GRPO loss ─────────────────────────────────────────
+def grpo_loss(av_model, tok, acts_scaled, acts_norm, ar_backbone, ar_head,
+              dev, group_size, max_new, kl_coef, ref_av, temperature=1.2):
+    """
+    Returns: (policy_loss, mean_reward, reward_std)
+    """
+    B = acts_scaled.shape[0]
+    prompt  = f"<concept>{INJ_CHAR}</concept>\n<explanation>"
+    p_ids   = tok(prompt, return_tensors="pt")["input_ids"].to(dev)
+    inj_pos = (p_ids[0] == INJ_TOK_ID).nonzero(as_tuple=True)[0][0].item()
+
+    all_log_probs = []  # [B, G]
+    all_rewards   = []  # [B, G]
+    ref_log_probs = []  # [B, G] for KL
+
+    for b in range(B):
+        embeds_base = av_model.get_input_embeddings()(p_ids).clone()
+        embeds_base[0, inj_pos] = acts_scaled[b].to(embeds_base.dtype)
+
+        b_lp, b_rew, b_rlp = [], [], []
+        for g in range(group_size):
+            # Sample with temperature
+            with torch.no_grad():
+                out = av_model.generate(
+                    inputs_embeds=embeds_base.clone(),
+                    attention_mask=torch.ones(1, p_ids.shape[1], device=dev),
+                    max_new_tokens=max_new, do_sample=True, temperature=temperature,
+                    pad_token_id=tok.eos_token_id, return_dict_in_generate=True,
+                    output_scores=True,
+                )
+            gen_ids = out.sequences[0]  # [T]
+            expl    = tok.decode(gen_ids, skip_special_tokens=True).strip()
+
+            # Reward: AR roundtrip cosine
+            recon   = ar_reconstruct(ar_backbone, ar_head, tok, [expl], dev)  # [1,D]
+            orig_n  = acts_norm[b].to(dev).unsqueeze(0)
+            reward  = (recon * orig_n).sum(-1).item()  # cosine similarity
+            b_rew.append(reward)
+
+            # Policy log-prob of generated tokens (recompute with grad)
+            full_embeds = av_model.get_input_embeddings()(p_ids).clone()
+            full_embeds[0, inj_pos] = acts_scaled[b].to(full_embeds.dtype)
+            # Append gen_ids to prompt via input_ids for teacher forcing
+            # (gen_ids are new tokens only from generate with inputs_embeds)
+            if len(gen_ids) > 0:
+                gen_embeds = av_model.get_input_embeddings()(gen_ids.unsqueeze(0))
+                all_embeds = torch.cat([full_embeds, gen_embeds], dim=1)
+                attn = torch.ones(1, all_embeds.shape[1], device=dev)
+                logits = av_model(inputs_embeds=all_embeds, attention_mask=attn).logits
+                # log-prob of generated part
+                P = p_ids.shape[1]
+                lp = 0.0
+                for t, tok_id in enumerate(gen_ids):
+                    lp = lp + F.log_softmax(logits[0, P+t-1], dim=-1)[tok_id]
+                lp = lp / max(len(gen_ids), 1)
+            else:
+                lp = torch.tensor(0.0, device=dev)
+            b_lp.append(lp)
+
+            # Reference log-prob (KL penalty)
+            with torch.no_grad():
+                ref_logits = ref_av(inputs_embeds=all_embeds.detach(), attention_mask=attn).logits
+                rlp = sum(F.log_softmax(ref_logits[0, P+t-1], dim=-1)[tok_id]
+                          for t, tok_id in enumerate(gen_ids))
+                rlp = rlp / max(len(gen_ids), 1)
+            b_rlp.append(rlp if isinstance(rlp, float) else rlp.item())
+
+        all_rewards.append(b_rew)
+        all_log_probs.append(b_lp)
+        ref_log_probs.append(b_rlp)
+
+    # GRPO: normalize rewards within group
+    loss = torch.tensor(0.0, device=dev, requires_grad=True)
+    flat_rewards = [r for group in all_rewards for r in group]
+    mean_rew = sum(flat_rewards) / len(flat_rewards)
+
+    for b in range(B):
+        rewards = all_rewards[b]
+        mu = sum(rewards) / group_size
+        std = (sum((r-mu)**2 for r in rewards)/group_size)**0.5 + 1e-6
+        for g in range(group_size):
+            adv = (rewards[g] - mu) / std
+            kl  = all_log_probs[b][g] - ref_log_probs[b][g]
+            loss = loss - (adv * all_log_probs[b][g] - kl_coef * kl)
+
+    return loss / (B * group_size), mean_rew, (sum((r-mean_rew)**2 for r in flat_rewards)/len(flat_rewards))**0.5
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--steps",      type=int,   default=1000)
+    parser.add_argument("--group-size", type=int,   default=8)
+    parser.add_argument("--batch",      type=int,   default=4)
+    parser.add_argument("--max-new",    type=int,   default=64)
+    parser.add_argument("--kl-coef",    type=float, default=0.05)
+    parser.add_argument("--lr-av",      type=float, default=2e-5)
+    parser.add_argument("--temperature", type=float, default=1.2,
+                        help="Sampling temperature for exploration (higher = more diverse)")
+    parser.add_argument("--eval-every", type=int,   default=50)
+    parser.add_argument("--save-every", type=int,   default=100)
+    parser.add_argument("--resume", action="store_true",
+                        help="Resume RL from latest checkpoint")
+    args = parser.parse_args()
+
+    dev = get_device()
+    run_name = f"rl_{datetime.now().strftime('%m%d_%H%M')}"
+    writer   = SummaryWriter(RUNS_DIR / run_name)
+    RUNS_DIR.mkdir(parents=True, exist_ok=True)
+
+    log(f"GRPO RL | device={dev} | steps={args.steps} | G={args.group_size} | B={args.batch} | T={args.temperature} | kl={args.kl_coef} | lr={args.lr_av}")
+    log(f"Monitor: tensorboard --logdir {RUNS_DIR}")
+
+    acts = load_activations()
+    acts_n = norm_acts(acts, "cpu")
+
+    # Load AR backbone (frozen scorer)
+    log(f"Loading AR backbone ({BASE_MODEL}, float16, sdpa)...")
+    ar_backbone = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(dev)
+    ar_backbone.eval()
+    for p in ar_backbone.parameters(): p.requires_grad_(False)
+    ar_head = load_ar(dev)
+    ar_head = ar_head.half()  # match backbone dtype
+    tok_ar  = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+    tok_ar.pad_token_id = tok_ar.eos_token_id
+
+    # Load AV from SFT or resume checkpoint
+    rl_resume_dir = ARTIFACTS / "checkpoints" / "av_rl_resume"
+    if args.resume and (rl_resume_dir / "training_state.pt").exists():
+        av_ckpt = rl_resume_dir
+        log(f"Resuming AV from {av_ckpt}...")
+    else:
+        if args.resume:
+            log(f"⚠️ No RL resume checkpoint found, starting from SFT")
+        av_ckpt = ARTIFACTS / "checkpoints" / "av_v2"
+        log(f"Loading AV from {av_ckpt}...")
+    av_base = AutoModelForCausalLM.from_pretrained(
+        INST_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(dev)
+    av_model = PeftModel.from_pretrained(av_base, av_ckpt, is_trainable=True).to(dev)
+    tok_av   = AutoTokenizer.from_pretrained(av_ckpt, trust_remote_code=True)
+    tok_av.pad_token_id = tok_av.eos_token_id
+
+    # Reference model (frozen copy for KL)
+    ref_base = AutoModelForCausalLM.from_pretrained(
+        INST_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(dev)
+    ref_av = PeftModel.from_pretrained(ref_base, av_ckpt).to(dev)
+    ref_av.eval()
+    for p in ref_av.parameters(): p.requires_grad_(False)
+
+    opt = torch.optim.AdamW(av_model.parameters(), lr=args.lr_av)
+
+    # SFT baseline or resume state
+    start_step = 1
+    if args.resume and (rl_resume_dir / "training_state.pt").exists():
+        ts = torch.load(rl_resume_dir / "training_state.pt",
+                        map_location=dev, weights_only=False)
+        opt.load_state_dict(ts["optimizer"])
+        start_step = ts["step"] + 1
+        best_cos = ts["best_cos"]
+        best_step = ts["best_step"]
+        sft_cos = ts["sft_cos"]
+        log(f"Resumed from step {start_step} | best_cos={best_cos:.4f} at step {best_step} | sft_cos={sft_cos:.4f}")
+        writer.add_scalar("rl/sft_baseline", sft_cos, 0)
+    else:
+        log("Computing SFT baseline roundtrip...")
+        sft_cosines = []
+        with torch.no_grad():
+            sample_idx = random.sample(range(len(acts)), min(50, len(acts)))
+            for i in sample_idx:
+                act_s = scale_acts(acts[i:i+1], dev)
+                act_n = acts_n[i:i+1].to(dev)
+                expls = av_generate(av_model, tok_av, act_s, dev, args.max_new, temperature=0, num_return=1)
+                recon = ar_reconstruct(ar_backbone, ar_head, tok_ar, expls[0], dev)
+                sft_cosines.append((recon * act_n).sum(-1).item())
+        sft_cos = sum(sft_cosines)/len(sft_cosines)
+        log(f"SFT baseline roundtrip cosine: {sft_cos:.4f}")
+        writer.add_scalar("rl/sft_baseline", sft_cos, 0)
+        best_cos, best_step = sft_cos, 0
+
+    random.seed(42)
+
+    for step in range(start_step, args.steps+1):
+        av_model.train()
+        batch_idx = random.sample(range(len(acts)), args.batch)
+        batch_acts   = acts[batch_idx]
+        batch_acts_n = acts_n[batch_idx]
+        acts_scaled  = scale_acts(batch_acts, dev)
+
+        loss, mean_rew, rew_std = grpo_loss(
+            av_model, tok_av, acts_scaled, batch_acts_n,
+            ar_backbone, ar_head, dev,
+            args.group_size, args.max_new, args.kl_coef, ref_av,
+            temperature=args.temperature,
+        )
+
+        opt.zero_grad()
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(av_model.parameters(), 1.0)
+        opt.step()
+
+        writer.add_scalar("rl/loss",       loss.item(),  step)
+        writer.add_scalar("rl/mean_reward", mean_rew,    step)
+        writer.add_scalar("rl/reward_std",  rew_std,     step)
+
+        if step % 10 == 0:
+            log(f"Step {step:4d}/{args.steps} | loss={loss.item():.4f} | "
+                f"reward={mean_rew:.4f}±{rew_std:.4f}")
+
+        # Eval roundtrip
+        if step % args.eval_every == 0:
+            av_model.eval()
+            cos_vals = []
+            with torch.no_grad():
+                eval_idx = random.sample(range(len(acts)), min(50, len(acts)))
+                for i in eval_idx:
+                    act_s = scale_acts(acts[i:i+1], dev)
+                    act_n = acts_n[i:i+1].to(dev)
+                    expls = av_generate(av_model, tok_av, act_s, dev, args.max_new, temperature=0)
+                    recon = ar_reconstruct(ar_backbone, ar_head, tok_ar, expls[0], dev)
+                    cos_vals.append((recon * act_n).sum(-1).item())
+            val_cos = sum(cos_vals)/len(cos_vals)
+            delta   = val_cos - sft_cos
+            flag    = "✓ BEST" if val_cos > best_cos else ("⚠️ regress" if val_cos < sft_cos - 0.02 else "")
+            log(f"[EVAL step {step}] roundtrip_cos={val_cos:.4f} | ΔSFT={delta:+.4f} | best={best_cos:.4f} {flag}")
+            writer.add_scalar("rl/val_roundtrip_cosine", val_cos, step)
+            writer.add_scalar("rl/delta_vs_sft",         delta,   step)
+
+            if val_cos > best_cos:
+                best_cos, best_step = val_cos, step
+                av_model.save_pretrained(ARTIFACTS / "checkpoints" / "av_rl_best")
+                log(f"  Saved best RL checkpoint (cos={best_cos:.4f})")
+
+            # Sample explanation
+            sample_act = scale_acts(acts[eval_idx[0]:eval_idx[0]+1], dev)
+            expls = av_generate(av_model, tok_av, sample_act, dev, args.max_new, temperature=0)
+            writer.add_text("rl/sample_expl", expls[0][0], step)
+            log(f"  Sample: {expls[0][0][:80]}")
+
+        if step % args.save_every == 0:
+            av_model.save_pretrained(ARTIFACTS / "checkpoints" / f"av_rl_step{step}")
+            # Save resume checkpoint
+            rl_resume_dir = ARTIFACTS / "checkpoints" / "av_rl_resume"
+            rl_resume_dir.mkdir(parents=True, exist_ok=True)
+            av_model.save_pretrained(rl_resume_dir)
+            torch.save({
+                "step": step,
+                "optimizer": opt.state_dict(),
+                "best_cos": best_cos,
+                "best_step": best_step,
+                "sft_cos": sft_cos,
+            }, rl_resume_dir / "training_state.pt")
+            log(f"  Saved resume checkpoint at step {step}")
+
+    log(f"\nRL done | best_cos={best_cos:.4f} at step {best_step} | SFT_cos={sft_cos:.4f}")
+    log(f"Best checkpoint: {ARTIFACTS/'checkpoints'/'av_rl_best'}")
+    writer.add_hparams(
+        {"lr":args.lr_av,"G":args.group_size,"B":args.batch,"kl":args.kl_coef,"temp":args.temperature},
+        {"hparam/best_rl_cosine": best_cos, "hparam/sft_cosine": sft_cos}
+    )
+    writer.close()
+
+
+if __name__ == "__main__":
+    main()

experiments/tiny_nla/train_sft_v2.py

@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""
+Phase 2: AR + AV SFT on v2 data (9810 records).
+Real-time monitoring via TensorBoard + console.
+
+Usage:
+  python train_sft_v2.py --stage ar   # AR only
+  python train_sft_v2.py --stage av   # AV only
+  python train_sft_v2.py              # both (AR first)
+
+Monitor:
+  tensorboard --logdir artifacts/tiny_nla/runs
+"""
+import json, yaml, random, time, argparse, sys, os
+from pathlib import Path
+from datetime import datetime
+
+# Disable HuggingFace network access — use local cache only, no HEAD checks to huggingface.co
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ.setdefault("HF_DATASETS_OFFLINE", "1")
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import pyarrow.parquet as pq
+from torch.utils.data import Dataset, DataLoader
+from torch.utils.tensorboard import SummaryWriter
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import LoraConfig, get_peft_model, PeftModel, TaskType
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS  = REPO_ROOT / "artifacts" / "tiny_nla"
+META_PATH  = Path(__file__).resolve().parent / "nla_meta.yaml"
+RUNS_DIR   = ARTIFACTS / "runs"
+
+meta       = yaml.safe_load(open(META_PATH))
+D_MODEL    = meta["d_model"]
+INJ_CHAR   = meta["tokens"]["injection_char"]
+INJ_TOK_ID = meta["tokens"]["injection_token_id"]
+INJ_SCALE  = meta["extraction"]["injection_scale"]
+BASE_MODEL = meta["base_model"]
+INST_MODEL = meta["av_init_model"]
+
+
+def get_device():
+    if torch.cuda.is_available():  return torch.device("cuda")
+    if torch.backends.mps.is_available(): return torch.device("mps")
+    return torch.device("cpu")
+
+
+def log(msg):
+    print(f"[{datetime.now().strftime('%H:%M:%S')}] {msg}", flush=True)
+
+
+# ── Data loading ─────────────────────────────────────
+def load_data():
+    table  = pq.read_table(ARTIFACTS / "activations_v2.parquet")
+    labels = {(r["text_idx"], r["pos"]): r["teacher_explanation"]
+              for r in json.load(open(ARTIFACTS / "teacher_labels_v2.json"))}
+
+    records, acts = [], []
+    for i in range(len(table)):
+        ti, pos = table["text_idx"][i].as_py(), table["pos"][i].as_py()
+        expl = labels.get((ti, pos), "")
+        if not expl or len(expl) < 5:
+            continue
+        act = torch.tensor(table["activation"][i].as_py(), dtype=torch.float32)
+        records.append({"text_idx": ti, "pos": pos,
+                        "text": table["text"][i].as_py(),
+                        "token_text": table["token_text"][i].as_py(),
+                        "teacher_explanation": expl})
+        acts.append(act)
+
+    acts_t = torch.stack(acts)
+    acts_n = F.normalize(acts_t, dim=-1)
+    log(f"Loaded {len(records)} records | norm {acts_t.norm(dim=-1).min():.1f}–{acts_t.norm(dim=-1).max():.1f}")
+    return records, acts_t, acts_n
+
+
+# ══════════════════════════════════════════════════════
+# AR SFT
+# ══════════════════════════════════════════════════════
+class ARHead(nn.Module):
+    def __init__(self, d_model):
+        super().__init__()
+        self.proj = nn.Linear(d_model, d_model, bias=False)
+    def forward(self, h):
+        return F.normalize(self.proj(h), dim=-1)
+
+
+class ARDataset(Dataset):
+    def __init__(self, records, acts_norm, tok, max_len=96):
+        self.items = []
+        for rec, act in zip(records, acts_norm):
+            ids = tok(rec["teacher_explanation"], truncation=True,
+                      max_length=max_len, return_tensors="pt")["input_ids"][0]
+            self.items.append((ids, act))
+    def __len__(self): return len(self.items)
+    def __getitem__(self, i): return self.items[i]
+
+
+def ar_collate(batch, pad_id):
+    ids_list, acts = zip(*batch)
+    L = max(x.shape[0] for x in ids_list)
+    ids  = torch.full((len(batch), L), pad_id, dtype=torch.long)
+    mask = torch.zeros(len(batch), L, dtype=torch.long)
+    for i, x in enumerate(ids_list):
+        ids[i, :len(x)] = x; mask[i, :len(x)] = 1
+    return ids, mask, torch.stack(acts)
+
+
+def train_ar(records, acts_t, acts_n):
+    dev = get_device()
+    run_name = f"ar_{datetime.now().strftime('%m%d_%H%M')}"
+    writer = SummaryWriter(RUNS_DIR / run_name)
+    log(f"AR SFT | device={dev} | tb: tensorboard --logdir {RUNS_DIR}")
+
+    tok = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
+    tok.pad_token_id = tok.eos_token_id
+
+    random.seed(42); idx = list(range(len(records))); random.shuffle(idx)
+    val_n = max(200, int(len(idx)*0.1))
+    tr_idx, va_idx = idx[val_n:], idx[:val_n]
+
+    pad = tok.eos_token_id
+    tr_dl = DataLoader(ARDataset([records[i] for i in tr_idx], acts_n[tr_idx], tok),
+                       batch_size=32, shuffle=True, collate_fn=lambda b: ar_collate(b, pad))
+    va_dl = DataLoader(ARDataset([records[i] for i in va_idx], acts_n[va_idx], tok),
+                       batch_size=32, shuffle=False, collate_fn=lambda b: ar_collate(b, pad))
+
+    log(f"Train {len(tr_idx)}, Val {len(va_idx)}")
+
+    log(f"Loading {BASE_MODEL}...")
+    backbone = AutoModelForCausalLM.from_pretrained(
+        BASE_MODEL, trust_remote_code=True, dtype=torch.float32,
+        low_cpu_mem_usage=True, attn_implementation="eager").to(dev)
+    backbone.eval()
+    for p in backbone.parameters(): p.requires_grad_(False)
+
+    head = ARHead(D_MODEL).to(dev)
+    opt  = torch.optim.AdamW(head.parameters(), lr=3e-4, weight_decay=0.01)
+    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=25, eta_min=1e-5)
+
+    # --- checkpoint helper: save best immediately to disk ---
+    ckpt_dir = ARTIFACTS / "checkpoints" / "ar_v2"
+    ckpt_dir.mkdir(parents=True, exist_ok=True)
+    def _save_ar_ckpt(state, cos_val, epoch_num):
+        p = ckpt_dir / "ar_head_v2.pt"
+        torch.save({"head": state, "d_model": D_MODEL,
+                     "val_cosine": cos_val, "mean_baseline": mean_cos,
+                     "epoch": epoch_num}, p)
+
+    # Baselines
+    mean_dir = acts_n.mean(0)
+    mean_cos = (acts_n @ mean_dir).mean().item()
+    log(f"Mean-direction baseline cosine: {mean_cos:.4f}")
+    writer.add_scalar("baseline/mean_cosine", mean_cos, 0)
+
+    best_cos, best_state, global_step = -1.0, None, 0
+    patience, pat_cnt = 6, 0
+
+    for epoch in range(25):
+        head.train()
+        ep_loss = []
+        for ids, mask, gold in tr_dl:
+            ids, mask, gold = ids.to(dev), mask.to(dev), gold.to(dev)
+            with torch.no_grad():
+                h = backbone(ids, attention_mask=mask, output_hidden_states=True).hidden_states[-1]
+                last = h[torch.arange(len(h)), mask.sum(1)-1]
+            pred = head(last)
+            loss = (2*(1-(pred*gold).sum(-1))).mean()
+            opt.zero_grad(); loss.backward(); opt.step()
+            ep_loss.append(loss.item())
+            writer.add_scalar("ar/train_loss_step", loss.item(), global_step)
+            global_step += 1
+
+        head.eval(); cos_vals = []
+        with torch.no_grad():
+            for ids, mask, gold in va_dl:
+                ids, mask, gold = ids.to(dev), mask.to(dev), gold.to(dev)
+                h = backbone(ids, attention_mask=mask, output_hidden_states=True).hidden_states[-1]
+                last = h[torch.arange(len(h)), mask.sum(1)-1]
+                pred = head(last)
+                cos_vals.extend((pred*gold).sum(-1).tolist())
+
+        train_loss = sum(ep_loss)/len(ep_loss)
+        val_cos    = sum(cos_vals)/len(cos_vals)
+        sched.step()
+
+        writer.add_scalar("ar/train_loss", train_loss, epoch)
+        writer.add_scalar("ar/val_cosine", val_cos, epoch)
+        writer.add_scalar("ar/lr", opt.param_groups[0]["lr"], epoch)
+
+        delta = val_cos - mean_cos
+        flag = "✓" if val_cos > best_cos else "↓"
+        log(f"AR Epoch {epoch+1:2d} | train_loss={train_loss:.4f} | val_cos={val_cos:.4f} "
+            f"| Δmean={delta:+.4f} | best={best_cos:.4f} {flag}")
+
+        if val_cos > best_cos:
+            best_cos, pat_cnt = val_cos, 0
+            best_state = {k: v.clone() for k, v in head.state_dict().items()}
+            _save_ar_ckpt(best_state, best_cos, epoch + 1)   # flush to disk NOW
+        else:
+            pat_cnt += 1
+            if pat_cnt >= patience:
+                log(f"Early stop (patience={patience})")
+                break
+
+    # --- safety net: ensure best state is on disk even on interrupt ---
+    head.load_state_dict(best_state)
+    _save_ar_ckpt(best_state, best_cos, epoch + 1)
+
+    writer.add_hparams({"lr": 3e-4, "batch": 32, "d_model": D_MODEL},
+                       {"hparam/best_val_cosine": best_cos})
+    writer.close()
+    log(f"AR done | best_cos={best_cos:.4f} vs mean={mean_cos:.4f} Δ={best_cos-mean_cos:+.4f}")
+    log(f"Checkpoint: {ckpt_dir / 'ar_head_v2.pt'}")
+    return best_cos
+
+
+# ══════════════════════════════════════════════════════
+# AV SFT
+# ══════════════════════════════════════════════════════
+class AVDataset(Dataset):
+    def __init__(self, records, acts, tok, max_expl=80):
+        prompt_ids = tok(f"<concept>{INJ_CHAR}</concept>\n<explanation>",
+                         return_tensors="pt")["input_ids"][0]
+        self.plen = len(prompt_ids)
+        self.items = []
+        for rec, act in zip(records, acts):
+            expl_ids = tok(rec["teacher_explanation"], add_special_tokens=False,
+                           return_tensors="pt")["input_ids"][0][:max_expl]
+            eos = torch.tensor([tok.eos_token_id])
+            ids = torch.cat([prompt_ids, expl_ids, eos])
+            lbl = ids.clone(); lbl[:self.plen] = -100
+            self.items.append({"input_ids": ids, "labels": lbl, "act": act,
+                               "teacher": rec["teacher_explanation"]})
+    def __len__(self): return len(self.items)
+    def __getitem__(self, i): return self.items[i]
+
+
+def av_collate(batch, pad_id):
+    L = max(b["input_ids"].shape[0] for b in batch)
+    ids  = torch.full((len(batch), L), pad_id, dtype=torch.long)
+    mask = torch.zeros(len(batch), L, dtype=torch.long)
+    lbl  = torch.full((len(batch), L), -100, dtype=torch.long)
+    acts = torch.stack([b["act"] for b in batch])
+    for i, b in enumerate(batch):
+        n = b["input_ids"].shape[0]
+        ids[i,:n] = b["input_ids"]; mask[i,:n] = 1; lbl[i,:n] = b["labels"]
+    return {"ids": ids, "mask": mask, "lbl": lbl, "acts": acts}
+
+
+def scale_acts(acts, dev):
+    a = acts.to(dev).float()
+    return a / a.norm(dim=-1, keepdim=True).clamp(1e-6) * INJ_SCALE
+
+
+class AVModel(nn.Module):
+    def __init__(self, lora_model):
+        super().__init__(); self.model = lora_model
+    def forward(self, ids, mask, lbl, acts):
+        e = self.model.get_input_embeddings()(ids)
+        # Vectorized activation injection (no Python loop)
+        positions = (ids == INJ_TOK_ID).float().argmax(dim=1)  # [B]
+        b_idx = torch.arange(ids.shape[0], device=ids.device)
+        e[b_idx, positions] = acts.to(e.dtype)
+        return self.model(inputs_embeds=e, attention_mask=mask, labels=lbl)
+
+
+def train_av(records, acts_t, resume=False, batch_size=8, lr=5e-5, epochs=30):
+    dev = get_device()
+    run_name = f"av_{datetime.now().strftime('%m%d_%H%M')}"
+    writer = SummaryWriter(RUNS_DIR / run_name)
+    log(f"AV SFT | device={dev} | tb: tensorboard --logdir {RUNS_DIR}")
+
+    tok = AutoTokenizer.from_pretrained(INST_MODEL, trust_remote_code=True)
+    tok.pad_token_id = tok.eos_token_id
+
+    random.seed(42); idx = list(range(len(records))); random.shuffle(idx)
+    val_n = max(200, int(len(idx)*0.1))
+    tr_idx, va_idx = idx[val_n:], idx[:val_n]
+
+    pad = tok.eos_token_id
+    tr_ds = AVDataset([records[i] for i in tr_idx], acts_t[tr_idx], tok)
+    va_ds = AVDataset([records[i] for i in va_idx], acts_t[va_idx], tok)
+    tr_dl = DataLoader(tr_ds, batch_size=batch_size, shuffle=True,
+                       collate_fn=lambda b: av_collate(b, pad))
+    va_dl = DataLoader(va_ds, batch_size=batch_size, shuffle=False,
+                       collate_fn=lambda b: av_collate(b, pad))
+    log(f"Train {len(tr_idx)}, Val {len(va_idx)}")
+
+    log(f"Loading {INST_MODEL} (float16, sdpa)...")
+    base = AutoModelForCausalLM.from_pretrained(
+        INST_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(dev)
+    resume_dir = ARTIFACTS / "checkpoints" / "av_v2_resume"
+    av_v2_dir  = ARTIFACTS / "checkpoints" / "av_v2"
+    if resume and (resume_dir / "training_state.pt").exists():
+        lora_model = PeftModel.from_pretrained(base, resume_dir, is_trainable=True)
+        log(f"Resumed LoRA + optimizer from {resume_dir}")
+    elif resume and av_v2_dir.exists():
+        lora_model = PeftModel.from_pretrained(base, av_v2_dir, is_trainable=True)
+        log(f"⚠️ No resume checkpoint, loading best SFT from {av_v2_dir} (optimizer reset, epoch=0)")
+    else:
+        if resume:
+            log(f"⚠️ No checkpoint found, starting fresh LoRA")
+        lora_model = get_peft_model(base, LoraConfig(
+            task_type=TaskType.CAUSAL_LM, r=8, lora_alpha=16,
+            lora_dropout=0.1, target_modules=["q_proj","v_proj"], bias="none"))
+    lora_model.print_trainable_parameters()
+
+    av  = AVModel(lora_model).to(dev)
+    opt = torch.optim.AdamW(av.parameters(), lr=lr, weight_decay=0.05)
+    sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=epochs, eta_min=lr/10)
+
+    best_loss, pat_cnt, global_step = float("inf"), 0, 0
+    start_epoch = 0
+    PATIENCE = 8
+
+    if resume and (resume_dir / "training_state.pt").exists():
+        ts = torch.load(resume_dir / "training_state.pt",
+                        map_location=dev, weights_only=False)
+        opt.load_state_dict(ts["optimizer"])
+        sched.load_state_dict(ts["scheduler"])
+        start_epoch = ts["epoch"] + 1
+        best_loss = ts["best_loss"]
+        pat_cnt = ts["pat_cnt"]
+        global_step = ts["global_step"]
+        log(f"Resumed from epoch {start_epoch} | best_loss={best_loss:.4f} | pat_cnt={pat_cnt}")
+
+    for epoch in range(start_epoch, epochs):
+        av.train(); ep_loss = []
+        for batch in tr_dl:
+            ids  = batch["ids"].to(dev); mask = batch["mask"].to(dev)
+            lbl  = batch["lbl"].to(dev); acts = scale_acts(batch["acts"], dev)
+            out  = av(ids, mask, lbl, acts)
+            opt.zero_grad(); out.loss.backward()
+            torch.nn.utils.clip_grad_norm_(av.parameters(), 1.0)
+            opt.step()
+            ep_loss.append(out.loss.item())
+            writer.add_scalar("av/train_loss_step", out.loss.item(), global_step)
+            global_step += 1
+
+        av.eval(); vl = []
+        with torch.no_grad():
+            for batch in va_dl:
+                out = av(batch["ids"].to(dev), batch["mask"].to(dev),
+                         batch["lbl"].to(dev), scale_acts(batch["acts"], dev))
+                vl.append(out.loss.item())
+
+        train_loss = sum(ep_loss)/len(ep_loss)
+        val_loss   = sum(vl)/len(vl)
+        sched.step()
+
+        writer.add_scalar("av/train_loss", train_loss, epoch)
+        writer.add_scalar("av/val_loss",   val_loss,   epoch)
+        writer.add_scalar("av/lr", opt.param_groups[0]["lr"], epoch)
+
+        # overfit alert
+        gap = train_loss / max(val_loss, 1e-6)
+        flag = "⚠️ overfit" if gap < 0.3 else ("✓" if val_loss < best_loss else "↓")
+        log(f"AV Epoch {epoch+1:2d} | train={train_loss:.4f} | val={val_loss:.4f} "
+            f"| gap={gap:.2f} | best={best_loss:.4f} {flag}")
+
+        if val_loss < best_loss:
+            best_loss, pat_cnt = val_loss, 0
+            av.model.save_pretrained(ARTIFACTS / "checkpoints" / "av_v2")
+            tok.save_pretrained(ARTIFACTS / "checkpoints" / "av_v2")
+        else:
+            pat_cnt += 1
+
+        # Save resume checkpoint every epoch
+        resume_dir = ARTIFACTS / "checkpoints" / "av_v2_resume"
+        resume_dir.mkdir(parents=True, exist_ok=True)
+        av.model.save_pretrained(resume_dir)
+        tok.save_pretrained(resume_dir)
+        torch.save({
+            "epoch": epoch,
+            "optimizer": opt.state_dict(),
+            "scheduler": sched.state_dict(),
+            "best_loss": best_loss,
+            "pat_cnt": pat_cnt,
+            "global_step": global_step,
+        }, resume_dir / "training_state.pt")
+
+        if pat_cnt >= PATIENCE:
+            log(f"Early stop (patience={PATIENCE})"); break
+
+    # Sample generations from best checkpoint
+    log("Generating samples from best checkpoint...")
+    base2 = AutoModelForCausalLM.from_pretrained(
+        INST_MODEL, trust_remote_code=True, dtype=torch.float16,
+        low_cpu_mem_usage=True, attn_implementation="sdpa").to(dev)
+    best_av = PeftModel.from_pretrained(base2, ARTIFACTS/"checkpoints"/"av_v2").to(dev)
+    best_av.eval()
+
+    prompt  = f"<concept>{INJ_CHAR}</concept>\n<explanation>"
+    p_ids   = tok(prompt, return_tensors="pt")["input_ids"].to(dev)
+    p_mask  = torch.ones(1, p_ids.shape[1], device=dev)
+    nonempty = 0
+    with torch.no_grad():
+        for i in range(min(10, len(va_ds))):
+            act = va_ds[i]["act"].unsqueeze(0)
+            sc  = scale_acts(act, dev)
+            emb = best_av.get_input_embeddings()(p_ids)
+            pos = (p_ids[0] == INJ_TOK_ID).nonzero(as_tuple=True)[0]
+            if len(pos): emb[0, pos[0]] = sc[0].to(emb.dtype)
+            out = best_av.generate(inputs_embeds=emb, attention_mask=p_mask,
+                                   max_new_tokens=80, do_sample=False,
+                                   pad_token_id=tok.eos_token_id)
+            gen = tok.decode(out[0], skip_special_tokens=True).strip()
+            if gen: nonempty += 1
+            writer.add_text("av/samples", f"T: {va_ds[i]['teacher'][:60]}\nG: {gen[:80]}", i)
+            log(f"  [{i}] T: {va_ds[i]['teacher'][:55]}")
+            log(f"       G: {gen[:80]}")
+
+    log(f"Non-empty: {nonempty}/10")
+    writer.add_hparams({"lr":lr,"lora_r":8,"batch":batch_size},
+                       {"hparam/best_val_loss": best_loss})
+    writer.close()
+    log(f"AV done | best_val_loss={best_loss:.4f}")
+    log(f"Checkpoint: {ARTIFACTS/'checkpoints'/'av_v2'}")
+    return best_loss
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--stage", choices=["ar","av","both"], default="both")
+    parser.add_argument("--resume", action="store_true",
+                        help="Resume AV training from latest checkpoint")
+    parser.add_argument("--batch-size", type=int, default=8,
+                        help="Batch size (smaller = more SGD noise = better generalization)")
+    parser.add_argument("--lr", type=float, default=5e-5,
+                        help="Peak LR (lower for warm restart from existing checkpoint)")
+    parser.add_argument("--epochs", type=int, default=30)
+    args = parser.parse_args()
+
+    RUNS_DIR.mkdir(parents=True, exist_ok=True)
+    records, acts_t, acts_n = load_data()
+
+    if args.stage in ("ar","both"):
+        train_ar(records, acts_t, acts_n)
+    if args.stage in ("av","both"):
+        train_av(records, acts_t, resume=args.resume,
+                 batch_size=args.batch_size, lr=args.lr, epochs=args.epochs)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1,6 +1,7 @@
 transformers>=4.51.0,<5.0.0  # 5.x 需 accelerate库，HF Spaces 上易出问题
 torch>=2.1.0,<2.5.0
 numpy>=1.24.0
+peft>=0.14.0  # LoRA 模型加载（Tiny-NLA Phase 1b）
 connexion[flask,swagger-ui,uvicorn]>=3.0.0
 flask>=3.0.0
 PyYAML>=6.0

server.py

@@ -40,6 +40,7 @@ from backend.api.analyze_semantic import analyze_semantic  # noqa: F401
 from backend.api.prediction_attribute import prediction_attribute  # noqa: F401
 from backend.api.ablation_attribute import ablation_attribute  # noqa: F401
 from backend.api.logit_lens import logit_lens  # noqa: F401
+from backend.api.activation_explain import activation_explain  # noqa: F401
 from backend.api.branch_next import branch_next  # noqa: F401
 from backend.api.tokenize import tokenize  # noqa: F401
 from backend.api.model_switch import (  # noqa: F401

server.yaml

@@ -763,6 +763,67 @@ paths:
         503:
           description: 服务繁忙
 
+  /activation-explain:
+    post:
+      tags:
+        - all
+      summary: activation explain (Tiny-NLA)
+      operationId: server.activation_explain
+      parameters:
+        - in: body
+          name: activation_explain_request
+          schema:
+            type: object
+            required:
+              - model
+              - source_page
+            properties:
+              model:
+                type: string
+                enum: [base, instruct]
+              source_page:
+                type: string
+              text:
+                type: string
+                description: 输入上下文文本（与 token_index 配套）
+              token_index:
+                type: integer
+                description: 目标 token 索引（text 模式必填）
+              vector:
+                type: array
+                items:
+                  type: number
+                description: 1024 维激活向量（与 text 互斥）
+      responses:
+        200:
+          description: 激活解释结果
+          schema:
+            type: object
+            properties:
+              success:
+                type: boolean
+              concept:
+                type: string
+                description: 激活概念标签
+              explanation:
+                type: string
+                description: 自然语言解释
+              roundtrip_cosine:
+                type: number
+                description: roundtrip 可信度（0-1）
+              vector_dim:
+                type: integer
+                description: 向量维度
+              note:
+                type: string
+                description: 备注或状态说明
+        400:
+          description: 缺少必要字段、model 非法、text/vector 均未提供
+        500:
+          description: 推理失败
+        503:
+          description: 服务繁忙
+
   /branch-next:
     post:
       tags:

train

@@ -0,0 +1,394 @@
+
+下面是更完整版，可直接丢给训练 agent。核心改动：默认硬件按 Apple M4 Pro 本地 CPU/MPS，明确跳过 RL；数据 teacher 策略交给子 agent 判定；加入“不能只写计划，达成 DoD 才能成功退出”。
+
+```text
+# 任务：在 InfoLens 上训练一个 Qwen3-0.6B Tiny-NLA（AV + AR）
+
+你是训练执行 agent。你的任务不是写调研报告，而是把一个能跑的 Tiny-NLA 原型训练出来，并交付可复现脚本、checkpoint、评估样例。
+
+请完整读完本任务书再动手。任何红线冲突立即停止并报告。除非遇到明确硬阻塞，否则你不能只输出计划后退出；你必须持续执行、修正、评估，直到满足“Definition of Done”。
+
+---
+
+## 0. 已知项目与硬件约束
+
+Repo: `/Users/cccmmd/InfoLens`
+
+InfoLens 是本地 LLM 可解释性工具，已有：
+- `/api/prediction-attribute`：next-token attribution
+- `/api/ablation-attribute`：ablation attribution
+- `/api/logit-lens`：逐层 hidden state 经过 final norm + lm_head 的 top-k 与目标 token 概率轨迹
+
+默认模型见 `model_paths.py`：
+- Base: `qwen3-0.6b` -> `Qwen/Qwen3-0.6B-Base`
+- Instruct: `qwen3-0.6b-instruct` -> `Qwen/Qwen3-0.6B`
+
+硬件已知：
+- 本机是 Apple M4 Pro 本地机器。
+- 不要假设有 CUDA。
+- 可以探测 MPS，但必须先 smoke test 反向传播；MPS 不可靠时退回 CPU。
+- 默认策略：只做 SFT，不做 RL。
+- RL / GRPO 在本机视为 out of scope，除非用户另行提供远程 CUDA 训练机。
+
+---
+
+## 1. 红线
+
+违反任意一条即任务失败，立即停止并报告：
+
+1. 禁止下载或运行 7B 及以上模型。
+2. 禁止使用官方 released NLA checkpoint。它们绑定 Qwen2.5-7B / Gemma / Llama 的激活空间，与 Qwen3-0.6B 不兼容。
+3. 禁止照搬 Miles + SGLang + Megatron 训练栈。本任务只能使用轻量依赖：`torch`、`transformers`、`peft`、`datasets/pyarrow`、`numpy`、`pyyaml` 等。
+4. 禁止把官方 7B/70B 超参当成默认值。0.6B 必须自己做小规模 smoke 与轻量调参。
+5. 禁止把大模型权重、parquet 数据、训练 artifacts 提交到 git。
+6. 不要改动生产 UI/API，除非用户后续明确要求。本任务只做实验脚本与 artifacts。
+
+---
+
+## 2. 目标
+
+训练一对 Tiny-NLA 组件，用于解释 `Qwen/Qwen3-0.6B-Base` 某一层 residual stream activation。
+
+- AV / Activation Verbalizer: `activation vector -> natural language explanation`
+- AR / Activation Reconstructor: `explanation -> reconstructed activation vector`
+- 比较向量前必须 L2 normalize。
+- round-trip loss 使用 `MSE = 2 * (1 - cosine)` 或等价 normalized MSE。
+- 最终 InfoLens 更依赖 AV：输入某层 activation，输出一句可读中文解释。
+- AR 用于客观评估与未来 reward，不要求达到官方 7B 水平，但必须训练、评估、和 baseline 比较。
+
+---
+
+## 3. 成功退出条件 Definition of Done
+
+你不能在满足以下条件前声称任务完成：
+
+1. 已确认并记录环境：
+   - device: CPU / MPS / CUDA
+   - `Qwen/Qwen3-0.6B-Base` 的 `num_hidden_layers` 与 `hidden_size`
+   - 选择的 layer index，按约 2/3 深度计算，并说明理由
+   - injection token 是否为单 token
+   - injection scale 如何估计
+
+2. 已完成可复现数据生成：
+   - 至少 smoke 数据 200 条
+   - 如果速度允许，扩到 500-2000 条
+   - 数据包含：context、token index、layer、activation_vector、teacher explanation、target token/top-k debug 信息
+   - 数据与 sidecar 存在 artifacts 目录，且不进入 git
+
+3. 已完成 Stage 0 smoke：
+   - 能提取 Qwen3-0.6B-Base hidden state
+   - 能用 `input_embeds` 注入 activation
+   - 能跑一次 AV forward/generation，不崩溃、不 shape mismatch
+
+4. 已完成 AR SFT：
+   - 有训练脚本
+   - 有 checkpoint
+   - 有 val metrics
+   - 必须和 mean baseline / shuffled baseline 对比
+   - 如果 AR 训练失败，必须至少做两轮合理修正后才能报告 blocker
+
+5. 已完成 AV SFT：
+   - 有训练脚本
+   - 有 checkpoint 或 LoRA adapter
+   - 能对 held-out activation 生成中文解释
+   - 至少输出 20 条 worked examples
+   - 20 条里不能大面积乱码、空输出、模板废话；若质量很差，必须继续修正数据或训练设置，不能直接交付
+
+6. 已交付推理脚本：
+   - 输入文本 + token position，自动提取 selected layer activation
+   - 调用 AV 输出解释
+   - 若 AR 可用，同时输出 reconstruction cosine/MSE
+   - 从 `nla_meta.yaml` 读取配置，不硬编码 layer/token/scale/template
+
+7. 已交付最终报告：
+   - 环境
+   - 数据策略
+   - 训练耗时
+   - AR 指标
+   - AV 质量观察
+   - 20 条样例
+   - 失败案例与局限
+   - 下一步建议
+
+只有以上完成，才能输出“任务完成”。否则只能输出“阻塞报告”，并附证据与已尝试修复项。
+
+---
+
+## 4. 外部参考，只学算法，不照搬基础设施
+
+参考仓库：
+`https://github.com/kitft/natural_language_autoencoders`
+
+开工前阅读：
+- `README.md`
+- `docs/inference.md`
+- `docs/design.md`
+- `nla/schema.py`
+- `nla/config.py`
+- `nla/models.py`
+- `nla/loss.py`
+- `nla/reward.py`
+- `nla/datagen/`
+
+你要借鉴：
+- AV 把 activation 当作一个虚拟 token embedding 注入 prompt
+- AR 从 explanation text 重建 activation
+- sidecar 记录 prompt、injection token、layer、scale、d_model
+- normalized MSE / cosine 作为评估
+
+你不要借鉴：
+- 7B+ released checkpoints
+- Miles / SGLang / Megatron
+- 多 H100 训练配置
+- RL 默认流程
+
+---
+
+## 5. 数据生成策略：必须交给子 agent 判断与执行建议
+
+在生成 teacher explanation 前，先启动一个 focused subagent，任务是：
+
+“判断当前环境是否可使用 Claude/外部 API 生成 Tiny-NLA teacher explanations；如果可用，给出低预算批量生成策略；如果不可用，给出本地 `Qwen/Qwen3-0.6B` instruct 生成策略。必须返回具体 prompt 模板、批大小、成本/速度风险、fallback 方案。”
+
+子 agent 必须检查：
+- 是否存在 `ANTHROPIC_API_KEY`
+- 是否存在其他可用 teacher API key
+- 用户是否已明确预算
+- 如果无法确认预算，不要擅自大规模调用外部 API
+
+主 agent 根据子 agent 结论执行：
+
+### 有 Claude API 且预算明确
+- 先生成 200 条 smoke teacher explanations
+- 人工/程序抽查质量
+- 再扩到 500-2000 条
+- 每条 explanation 优先中文，短句，描述该位置模型可能关注的语义
+
+### 没有 API 或预算不明确
+- 使用本地 `Qwen/Qwen3-0.6B` instruct 做 weak teacher
+- 允许降级，用户接受本地 teacher 质量较差
+- 必须在报告中标注：teacher 是 weak local teacher，不是真正 Claude-quality NLA labels
+
+Teacher prompt 应包含：
+- 原始 context
+- token 位置
+- target token / final top-k
+- logit lens 中该层附近的 top-k 摘要（如果容易取得）
+- 要求输出 1-2 句中文解释，不要长篇推理
+
+注意：AR 的标签始终是原始 activation vector，不依赖 teacher API。
+
+---
+
+## 6. 推荐目录结构
+
+把实验放在独立目录，例如：
+
+`experiments/tiny_nla/`
+
+建议文件：
+- `extract_activations.py`
+- `generate_teacher_labels.py`
+- `train_ar.py`
+- `train_av.py`
+- `eval_roundtrip.py`
+- `infer_tiny_nla.py`
+- `sidecar.py`
+- `README.md`
+
+Artifacts 放到：
+- `artifacts/tiny_nla/...`
+
+如果 artifacts 目录未被 gitignore，先加入 gitignore。不要提交模型权重或数据。
+
+---
+
+## 7. Stage 0：环境与注入 smoke
+
+先写并运行 smoke，不要直接训练。
+
+必须做：
+1. 加载 `Qwen/Qwen3-0.6B-Base`
+2. 读取真实：
+   - `num_hidden_layers`
+   - `hidden_size`
+   - vocab size
+3. 计算：
+   - `layer_index = round(num_hidden_layers * 2 / 3)`
+4. 对几条文本跑：
+   - `output_hidden_states=True`
+   - 取 selected layer 的最后 token 或多个 token activation
+5. 统计 activation L2 norm：
+   - mean
+   - p50
+   - p90
+   - max
+6. 选择 `injection_scale`：
+   - 初始用 p50 或 mean
+   - 写入 sidecar
+7. 选择 injection char：
+   - 必须是 tokenizer 下单 token
+   - 例如先测试 `㈎`，不行就找其他 rare single token
+8. 构造 prompt template：
+   - `<concept>{injection_char}</concept>`
+   - 要求输出 `<explanation>...</explanation>`
+9. 使用 `input_embeds` 替换 injection token embedding，跑一次 forward/generation。
+
+Stage 0 没过，不准训练。
+
+---
+
+## 8. Stage 1：AR SFT
+
+AR 输入 explanation text，输出 activation vector。
+
+实现要求：
+- 初版可以用 `Qwen/Qwen3-0.6B-Base` 或 instruct trunk
+- 优先冻结大部分模型，只训练轻量 head 或 LoRA + head
+- AR head: `Linear(d_model, d_model)`
+- 取最后一个 token hidden state 过 head
+- pred 和 gold 都 normalize 后算 MSE
+- 训练集/验证集拆分固定 seed
+
+必须评估：
+- val cosine mean
+- val normalized MSE
+- mean-vector baseline
+- shuffled-label baseline
+- 至少保存 best checkpoint
+
+如果 AR 不明显超过 baseline：
+- 尝试至少两项修正：
+  - 改 learning rate
+  - 改 batch size
+  - 改是否训练 LoRA
+  - 清洗 teacher explanation
+  - 增加数据量
+- 仍失败再报告，但不要编造成功。
+
+---
+
+## 9. Stage 2：AV SFT
+
+AV 输入 activation vector 注入 prompt，输出 teacher explanation。
+
+实现要求：
+- 初始权重优先 `Qwen/Qwen3-0.6B` instruct
+- 使用 LoRA，避免全量微调
+- 通过 `input_embeds` 注入 selected layer activation
+- loss 只算 explanation response token，不算 prompt token
+- prompt template 和 injection 参数全部从 sidecar 读取
+- 输出中文为目标，不是 bug
+
+训练约束：
+- Apple M4 Pro 本地机，不要追求大 batch
+- CPU 慢就降低数据量与 epoch
+- MPS 可用才用 MPS；MPS 出现反向/dtype 问题立即退回 CPU
+- 不要使用 fp16 反向作为默认；优先 fp32/bf16 smoke 后再决定
+
+必须评估：
+- held-out 20 条 worked examples
+- 每��包含：
+  - context
+  - token text / token index
+  - selected layer
+  - final top-k
+  - teacher explanation
+  - AV generated explanation
+  - AR reconstruction cosine/MSE（如果 AR 可用）
+  - 简短人工判断：相关 / 部分相关 / 不相关
+
+如果 AV 输出乱码、空、完全模板化：
+- 不准交付
+- 必须调整 teacher prompt、训练模板、learning rate、epoch、或数据清洗后重训
+
+---
+
+## 10. Stage 3：RL 明确跳过
+
+本机是 Apple M4 Pro 本地 CPU/MPS 环境，默认跳过 RL。
+
+不要实现 GRPO。
+不要安装 Miles/SGLang。
+不要声称完成 RL。
+
+最终报告中写：
+“由于本任务硬件为 Apple M4 Pro 本地 CPU/MPS，无 CUDA 多 GPU，RL/GRPO 阶段按任务约束跳过。本次交付 SFT Tiny-NLA。”
+
+---
+
+## 11. sidecar 契约
+
+必须生成 `nla_meta.yaml`，至少包含：
+
+```yaml
+kind: tiny_nla_model
+base_model: Qwen/Qwen3-0.6B-Base
+av_init_model: Qwen/Qwen3-0.6B
+layer_index: <int>
+num_hidden_layers: <int>
+d_model: <int>
+activation_source: residual_stream
+token_position_policy: selected_token_or_last_token
+extraction:
+  injection_scale: <float>
+  mse_normalization: l2_direction
+tokens:
+  injection_char: "<char>"
+  injection_token_id: <int>
+prompt_templates:
+  av: |
+    ...
+  ar: |
+    ...
+training:
+  device: cpu_or_mps
+  dtype: fp32_or_bf16
+  dataset_size: <int>
+  teacher: claude_or_local_qwen_instruct
+  created_at: <timestamp>
+```
+
+推理脚本必须读 sidecar，不要把这些值散落在代码里。
+
+---
+
+## 12. 最终报告格式
+
+最终报告必须包含：
+
+1. 是否完成 DoD
+2. 环境报告
+3. 数据生成策略与 teacher 来源
+4. 模型与层选择
+5. injection token 与 scale 统计
+6. AR 指标与 baseline 对比
+7. AV 训练设置与质量总结
+8. 20 条 worked examples 文件路径
+9. checkpoint / adapter 路径
+10. 推理脚本用法
+11. 已知局限
+12. 下一步建议
+
+不要只说“训练完成”。必须给路径、命令、指标、样例。
+
+---
+
+## 13. 阻塞时如何退出
+
+只有以下情况允许未完成 DoD 而退出：
+
+- Qwen3-0.6B 权重无法下载或加载，且重试后失败
+- 本机内存不足，连 Stage 0 smoke 都无法完成
+- tokenizer 找不到合适 single-token injection char，尝试多个候选后失败
+- PyTorch/transformers 在本机无法完成最小 forward/backward，且已给出错误日志
+- 数据 teacher 完全不可用，且本地 instruct 也无法加载
+
+阻塞报告必须包含：
+- 卡在哪个 stage
+- 已尝试哪些修复
+- 完整错误摘要
+- 下一步需要用户提供什么
+
+否则继续工作，直到满足 Definition of Done。
+```