pi-think-anchor 1.0.18 → 1.0.20

package/README.md

@@ -9,6 +9,26 @@
 
 思维链锚定监测：读取 thinking 的词频指纹，判定专注 / 过渡 / 发散，发散时分级提示。
 
+## 快速事实
+
+| 项 | 说明 |
+| --- | --- |
+| 配置文件 | ~/.pi/think-anchor.json（可省略） |
+| 命令行 | /think-anchor [on|off|reset|stats] |
+| 调用方式 | **全自动**：turn_end 评估 + 条件注入；命令可手动开关/重置 |
+
+完整配置（全部键与默认值）：
+
+```json
+{
+  "enabled": true,
+  "score": { "minHits": 3, "spec": 1.2, "react": 0.5, "alpha": 1 },
+  "windowSize": 5,
+  "weights": { "beta": 0.4, "eps": 0.5 },
+  "intervention": { "l1CooldownMin": 10, "l2CooldownMin": 15, "maxL2": 2 }
+}
+```
+
 ## 安装
 
 ```bash
@@ -51,6 +71,8 @@ pi install npm:pi-think-anchor
 - 无效不升级：上次 `eff >= 0` 时 L2 降为 L1。
 - `session_start`：重置状态机，仅保留最近 3 条与 pending（跨会话结算）。
 
+## 原理（专业）
+
 ```mermaid
 flowchart TD
     A[turn_end<br/>读 assistant thinking] --> B[词频指纹 pos/neg/neu]
@@ -64,6 +86,22 @@ flowchart TD
     H -->|nextTurn 尾部消息| A
 ```
 
+## 原理（小白）
+
+像一个跑步教练：看你说话的用词判断此刻是专注还是走神；一直走神就轻轻提醒一句，恢复专注就不打扰。
+
+```mermaid
+flowchart LR
+    A[你说的话] --> B[教练看用词]
+    B --> C{清晰吗}
+    C -->|清晰| D[不打扰]
+    C -->|有点散| E[轻提醒一句]
+    C -->|一直散| F[认真提醒]
+    E --> A
+    F --> A
+```
+
+
 ## 借鉴
 
 蒸馏自 DSH 插件 [`dsh-anchored-monitor`](https://dsh-plugin.org/zh/plugins/aik358/dsh-anchored-monitor) 0.3.1：机制思想来源，非代码移植（本实现为回合级，无独立进程）。
@@ -80,6 +118,26 @@ MIT
 
 Chain-of-thought drift monitor: reads a word-frequency fingerprint from thinking, classifies focused / mixed / reactive, and nudges when drifting.
 
+## At a glance
+
+| Item | Description |
+| --- | --- |
+| Config file | ~/.pi/think-anchor.json (optional) |
+| Commands | /think-anchor [on|off|reset|stats] |
+| Automation | **Fully automatic**: evaluated on turn_end, injects only when needed; commands toggle/reset |
+
+Full config (all keys and defaults):
+
+```json
+{
+  "enabled": true,
+  "score": { "minHits": 3, "spec": 1.2, "react": 0.5, "alpha": 1 },
+  "windowSize": 5,
+  "weights": { "beta": 0.4, "eps": 0.5 },
+  "intervention": { "l1CooldownMin": 10, "l2CooldownMin": 15, "maxL2": 2 }
+}
+```
+
 ## Install
 
 ```bash
@@ -122,7 +180,34 @@ Also: log `~/.pi/think-anchor.jsonl` (1 MiB truncation, tail-preserving).
 - No escalation: when the previous `eff >= 0`, L2 degrades to L1.
 - `session_start`: resets state, keeping only the last 3 samples and pending (cross-session settlement).
 
+## How it works (technical)
+
 ```mermaid
+flowchart TD
+    A[turn_end<br/>read assistant thinking] --> B[word fingerprint pos/neg/neu]
+    B --> C{hits >= minHits?}
+    C -->|no| Z[advance window only<br/>no score, no nudge]
+    C -->|yes| D[sliding window + alpha-smoothed ratio]
+    D --> E{band}
+    E -->|spec| F[healthy: silent]
+    E -->|mixed| G[watch]
+    E -->|react| H[state machine<br/>L1 / L2 nudge]
+    H -->|nextTurn message| A
+
+## How it works (plain words)
+
+Like a running coach: reads your words to judge whether you are focused or drifting; a mild nudge when you drift, silence when you recover.
+
+```mermaid
+flowchart LR
+    A[what you say] --> B[coach reads the wording]
+    B --> C{focused?}
+    C -->|yes| D[no interruption]
+    C -->|slightly off| E[one gentle nudge]
+    C -->|drifting| F[stronger nudge]
+    E --> A
+    F --> A
+```
 flowchart TD
     A[turn_end<br/>read assistant thinking] --> B[word fingerprint pos/neg/neu]
     B --> C{hits >= minHits?}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-think-anchor",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Monitors thinking focus drift and nudges the model back on track.",
   "type": "module",
   "license": "MIT",