# 配置说明 · CONFIG（开眼看世界 dsh-see-world / dsh-open-eyes）

> 本文用**大白话**逐项解释每个配置项：它是什么、怎么填、改了会怎样。
> 设置页卡片里每个配置项标签旁的 **❓** 悬浮说明与本文内容一致（卡片里看不全/悬停不爽时看这里）。
> 依据：`fresh-info-first-需求文档.md`（PRD v0.2）R3「轻量策略配置」与 §6.2 文档要求。

## 0. 在哪改配置

全部配置项都可在 DSH GUI 里可视化修改，**不用手改文件**：

**设置 → 插件配置（Plugin config）→ 「开眼看世界」卡片**

- 卡片按命名空间 `open-eyes` 读写；改动点「保存」即可。
- **大部分配置项保存后下一回合立即生效**（live，无需重启）。
- 唯一例外：**决策日志目录 `log_dir`** 属启动级配置，保存后**下次启动生效**（卡片提示里也写了）。
- 故意填非法值（如负预算、乱填档位）会被**拒绝保存**并在卡片内提示；配置损坏时插件回退默认值、不报错、不中断对话。
- 每个字段标签旁的 **❓** 悬停可看「这是什么 / 怎么选 / 有什么影响」（与本文逐条对应）。
- 等价地，也可以在 profile 的插件配置行（cordis patch）里按同名键直接写；设置页用户层优先于它。

## 1. 判定模型配好后，先点「测试连接」

卡片里「判定模型」输入框下方有一个 **测试连接** 按钮，**建议改完判定模型后先点它、成功再保存**。

- **测什么**：用你「正要填进去」的模型值（不是旧值）真实发起一次极简补全（只让它回复 OK），验证能不能连上、模型在不在、路由对不对；
- **怎么看结果**：下方一行文字——`✓ 连接成功：provider/model（响应：…）（N ms）` 或 `✗ 连接失败：原因（N ms）`，带**延迟毫秒数**：
  - `ollama/模型名` 直连本地 Ollama 原生 `/api/chat`，可立刻发现「Ollama 没启动 / 模型名不存在」；
  - `provider/model` 走 DSH llm，可发现「配了但连不上 / 额度不足 / 路由写错」这类平时会**静默降级**的问题；
  - 留空（复用会话模型）且当前没有可复用会话模型时，返回「无法解析模型路由」——属正常提示；
- **超时**：测试最长约 12 秒，超时返回 `✗ 连接失败（超时）`；
- 测试失败**不影响任何东西**（不会改配置、不阻塞对话），改完模型名再测即可。

> 为什么要先测：判定器任何故障都按 R5 静默降级——配错了不报错、只是「本轮不判定」，平时发现不了；点一下测试连接就能提前发现。

## 2. 逐项白话说明

### `trigger_gear` 触发档位（下拉选择）

**它是什么**：判定器「拿不准这条消息要不要上网搜索」时，按哪个口径处理。

- **宁多勿漏（lenient，默认）**：拿不准就搜——适合时效性/准确性要求高的场景，代价是偶尔多搜几次；
- **平衡（balanced）**：拿不准交给模型权衡，日常最常用；
- **保守（conservative）**：尽量少打扰，只对明确需要联网的消息触发搜索，可能漏掉时效信息。

> 注意：消息级强制标记（「不搜」「先搜」）优先于档位，见第 3 节。

### `judge_model` 判定模型（文本）

**它是什么**：负责「这条消息要不要搜」的小判定任务用哪个模型。

- **留空（默认）**：复用当前会话模型——零配置可用，判定不额外选模型、不额外消耗额度以外的选择成本；
- **填 `provider/模型`**：指定路由，如 `deepseek/deepseek-chat`（可换更便宜的模型控成本）；
- **填 `ollama/模型名`**（如 `ollama/qwen3.5:4b`）：判定**直连本机 Ollama 原生接口**——不依赖会话模型、不消耗会话模型额度、**判定数据不离开本机**；Ollama 未启动时自动降级（本轮不判定、不阻塞、不报错）；
- 解析不出路由（无会话也无 provider 兜底）时自动降级，对话照常。

> **改完先点「测试连接」**（见第 1 节）。

### `must_search` 必须搜索的领域（白名单，每行一个）

**它是什么**：命中这些关键词/领域的消息**一律先搜**——即使判定模型觉得不用搜。

- 每行一个关键词；适合时效性强的主题：股票行情、最新版本、新闻、政策法规、产品价格等；
- 注意：消息级「不搜」**优先于**白名单（白名单挡不住明确要求不搜的消息）。

### `never_search` 禁止搜索的领域（黑名单，每行一个）

**它是什么**：命中这些关键词/领域的消息**禁止搜索**，模型直接回答。

- 每行一个关键词；适合：闲聊、纯本地代码/文件操作、私人内容、无需联网的固定知识；
- 黑名单**优先于**白名单（同时命中时黑名单生效）；
- 注意：消息级「先搜」**优先于**黑名单（明确要求搜的消息黑名单拦不住）。

### `budget` 每会话搜索次数上限（数字）

**它是什么**：控制成本/额度的阀门——每个会话**最多触发多少次搜索**。

- `0`（默认）= 不限制；
- 超过上限后，本会话不再发起新搜索，改为在回复里标注「未能验证/不确定」并明确不得编造；
- 消息级「先搜」仍可强制搜索（强制标记优先于预算）。

### `context_turns` 多轮上下文补判轮数（数字）

**它是什么**：判定「这条要不要搜」时参考最近几轮对话——例如「它跟旧版比怎么样」需要上文才知道「它」指什么。

- 默认 `3` ≈ 携带最近 2-3 轮；
- 调大：多轮指代判得更准，但每次判定多花一点 token；
- 调小：更省 token，但上下文依赖强的消息可能判不准。

### `mark_reply` 回复末尾「🔍 已搜索 N 个来源」标记（开关）

**它是什么**：触发搜索且实际搜过的回合，回复末尾追加一行 `🔍 已搜索 N 个来源`，一眼看出哪些回答查过网。

- 默认开启；关闭后回复更干净，但看不出哪些回合搜过、搜到几个来源；
- 不影响决策日志（日志照常记录）。

### `log_dir` 决策日志目录（文本）

**它是什么**：每次判定的记录（搜没搜、为什么、耗时、成本、来源数）写入的**本地** JSONL 文件目录。

- 留空 = 插件默认路径 `~/.dsh/dsh-open-eyes/decisions/`（文件名为 `decisions.jsonl`）；
- 只存本机、不上传任何服务器；文件可随时删除，不影响插件运行；
- **此改动保存后下次启动生效**（其余配置项 live 生效）。

### `log_input_verbatim` 日志保存判定输入原文（开关）

**它是什么**：决策日志默认只存消息的**摘要**（截断 + 上下文条数标注），隐私优先；开启后日志附消息**原文**。

- 默认关闭（隐私默认，开源约定 §6.3）；
- 排查「判定不准」时开启更方便，但会完整记录输入内容；
- 日志始终只存在本机，开启与否都不上传。

## 3. 消息级强制标记（不用配置，人人可用）

**优先于以上全部配置**，两种写法：

- **两字前缀（兜底，百分百生效）**：消息以「**不搜**」开头 = 本条禁止搜索；以「**先搜**」开头 = 本条强制搜索。例：「不搜 帮我看看这个报错」「先搜 这张图里的产品报价」；
- **自然语言（主力，零记忆成本）**：说「这个不用搜 / 别搜了」或「先查一下 / 上网搜搜再答」即生效（判定器语义理解）；
- 前缀与自然语言同时出现时，**以前缀为准**。

## 4. 决策日志怎么看（R4）

- 位置：`log_dir`（默认 `~/.dsh/dsh-open-eyes/decisions/decisions.jsonl`），**JSON Lines**（一行一条记录）；
- 每条记录字段（格式公开、稳定）：`ts` / `session` / `turn` / `input_summary`（默认摘要）/ `input_verbatim`（仅开启原文时）/ `gear` / `force` / `need_search` / `reason` / `confidence` / `judge_ms` / `judge_tokens` / `degraded` / `searched` / `search_calls` / `search_ms` / `search_cost` / `sources` / `downgraded`；
- 会话统计（触发率、原因分布、R2 违规数、成本合计）可程序化读取：

```js
import { loadRecords, aggregateStats } from 'dsh-see-world'
const stats = aggregateStats(loadRecords())
```

## 5. 高级：环境变量（一般不用动）

| 环境变量 | 作用 |
|---|---|
| `OPEN_EYES_API_BASE` | 覆盖本地 Ollama 直连端点（默认 `http://127.0.0.1:11434` 的 `/api/chat`）/ OpenAI 兼容端点 |
| `OPEN_EYES_API_STYLE` | `ollama`（默认，原生 `/api/chat` + `think:false`）或 `openai`（OpenAI 兼容端点） |
| `OPEN_EYES_API_KEY` | 需要鉴权的端点时使用（Ollama 本地一般不需要） |

> 这些变量主要给附录 B live 回归与本地 Ollama 判定用；日常零配置即可。