# 运行机制与会话行为 (Internals & Runtime Behavior)

本文档深入介绍 `pi-model-customize` 的运行时修补原理、会话生命周期行为矩阵与状态保护机制。

---

## 1. 会话生命周期与行为矩阵

| 场景 / 事件 | 触发动作 | 思考档位调整策略 |
|---|---|---|
| **启动 (startup)** | pi 首次初始化 | 无 CLI 显式参数时应用默认档位；有 CLI 参数时保持用户指定值 |
| **新建会话 (new)** | `/new` 命令 | 同上，尊重同进程初始启动的 CLI 选项或应用模型默认档位 |
| **恢复会话 (resume)** | `/resume` 命令 | **保留当前档位**，必要时按模型能力自动钳制 |
| **派生会话 (fork)** | `/fork` 命令 | **保留当前档位**，必要时按模型能力自动钳制 |
| **重载扩展 (reload)** | `/reload` 命令 | **保留当前档位**，仅重载并应用新配置的模型参数 |
| **主动切换模型** | `/model` 或快捷键 | **应用目标模型的默认档位**；若无默认值则对齐当前档位 |
| **会话恢复选模** | `model_select (restore)` | **不重新应用默认值**，完整保留会话快照内保存的档位 |

### 动态模型对象刷新与同模型重选

pi 的模型目录和动态 Provider 可以在会话运行期间生成新的 Model 对象。此类对象替换不一定触发 `model_select`；另外，`/model` 重新选择相同的 `provider/模型ID` 时，pi 会写入 `model_change` 会话条目，但会因为模型标识未变化而省略 `model_select`。

扩展因此增加会话级协调机制：

1. 监测活动 Model 对象是否被替换，并对新对象重新应用当前配置。
2. 结合会话中的 `model_change` 条目识别同模型重选，按“主动切换模型”策略应用默认思考档位。
3. 如果只有目录或 Provider 刷新、没有用户选模意图，则保留当前思考档位，仅按新能力重新钳制。
4. 每个 Model 对象只修补一次，不通过轮询反复覆盖其他扩展的后续修改；会话关闭时停止协调并按快照撤销。

---

## 2. CLI 参数意图感知与保护

当用户在命令行启动 pi 并显式传入思考参数时，本插件会智能识别并**放弃覆盖默认档位**，以保障用户的即时指令意图：

* **支持的显式思考标志**：
  * `-t <level>` / `-t=<level>`
  * `--thinking <level>` / `--thinking=<level>`
  * `--model <model>:<level>` / `-m <model>:<level>`
* **模型名隔离**：
  * 具备智能冒号分词逻辑，类似 `ollama/llama:8b` 这种带有 tag 的普通模型 ID 不会被误识别为思考档位。

---

## 3. 内存原地修补与无污染撤销 (Undo Snapshot)

为了避免污染 pi 用户本地的 `settings.json` 或 `models.json`，插件采用**纯内存原地修补（In-Memory Mutation）**：

```
                    ┌────────────────────────┐
                    │     原始 Model 对象     │
                    └───────────┬────────────┘
                                │ 1. 记录 PropertySnapshot (hadOwn, original)
                                ▼
                    ┌────────────────────────┐
                    │   应用 Customization   │
                    └───────────┬────────────┘
                                │ 2. 记录 applied 并建立 Undo 映射
                                ▼
                    ┌────────────────────────┐
                    │ 会话关闭 / 重载时还原   │
                    │   (restoreAll 执行)    │
                    └────────────────────────┘
```

* **安全归还属性**：在修补前记录 `hadOwn` 与 `original`，修补后记录 `applied`。
* **所有权友好**：在 `/reload`、会话切换或关闭时，仅当属性值依然等于本插件当初修改的 `applied` 时才执行回退。如果后续有其他插件修改了该属性，本插件会安全保留最新值，不引发所有权覆盖冲突。

---

## 4. 性能优化与快速路径 (Fast Path)

1. **模式正则预编译**：配置加载时自动对通配模式与 JSON 正则完成编译并建立缓存，消除遍历全量模型注册表时的重复编译开销。
2. **状态安全**：在每次候选匹配时主动重置 `regex.lastIndex = 0`，防止带有 `g` 或 `y` 标志的正则在并发匹配时状态漂移。
3. **空配置短路**：当合并后的配置没有任何模式与精确规则时，直接跳过对模型注册表的循环遍历。