docs(advisor): design doc with recorded-not-implemented Jev appendix

Architecture rationale (LLM out of the hot path, perception/authority
split, uncalibrated confidence never gates), provider contract, detector
table, runbook-as-poor-man's-RAG, honest limitations of commodity LLMs,
and the P1/P2 path.

Appendix A records the TypeSafe Jev (System One) integration design for
future use only: single /v1/systemone endpoint, noul/choice/score
primitives, the pend_stall_v1 four-question pack and its Finding mapping,
confidence-gated act mode, jev-1.13 jaggedness risk. Deliberately not
wired in P0.

Co-Authored-By: Claude Code <noreply@anthropic.com>

src/docs/advisor-design.md

@@ -0,0 +1,175 @@
+# XCE Scheduler Advisor — 设计文档
+
+> 2026-10-18。P0 observe 档。分支 `feature/scheduler-advisor`。
+> 定位：旁路的 LLM 运维副驾驶——观察、检测、诊断、记录；**不执行任何变更**。
+
+## 1. 核心原则
+
+1. **LLM 不进调度热路径**。调度 round 是毫秒级确定性代码；advisor 是旁路 daemon，
+   挂掉/变慢只影响"有没有新诊断"，不影响集群。
+2. **感知与权力分离**。模型只产出结构化 findings（给人和决策日志看）；执行权
+   永远在代码里。P0 连 propose/act 通道都没有。
+3. **普通 LLM 的 confidence 不可信**（未校准），只能展示、不能作为自动决策门控。
+   这是 P0 没有 act 档的根本原因（也是 Jev 未来的差异化价值，见附录 A）。
+4. **可观测性先于 AI**。advisor 的质量上限被内核状态质量封顶：PEND reason 全链路
+   （ac6131d）等既有工作正是这个 advisor 的地基。
+
+## 2. 架构
+
+```
+                       ┌──────────────────────────────────────────────┐
+ apiserver REST ──────▶│ snapshot: 紧凑集群状态（字段白名单+top-N 截断）  │
+ (schedulerclient)     └──────────────┬───────────────────────────────┘
+                                      ▼
+ SSE /xce/v1/events ─▶ detect: 确定性触发器（阈值→冷却→去重）
+ (事件只提前扫描)              │ 命中
+                              ▼
+                      provider.Evaluate(Scenario, State, Runbook)
+                       ├── openai（OpenAI 兼容 LLM）
+                       └── echo（确定性规则，兜底/基线）
+                              │ findings
+                              ▼
+                       幻觉防火墙 VerifyEvidence
+                              │
+                              ▼
+                       declog: JSONL 决策日志（全上下文）
+```
+
+- 代码位置：`src/frontend/advisor/`，独立 Go module（`replace schedulerclient`），
+  `CGO_ENABLED=0`，不进 meson（与 mcp-server 一致，`go build` 直出）。
+- 部署：t1 上以 `XCE_API_KEY`（mcp_readonly 角色）运行 `advisor run`。
+
+## 3. Provider 契约
+
+```go
+type Provider interface {
+    Name() string
+    Evaluate(ctx, EvaluateRequest{Scenario, State, Runbook}) (*EvaluateResponse, error)
+}
+type Finding struct {
+    Kind       string   // anomaly | diagnosis
+    Severity   string   // info | degraded | severe | outage
+    Summary    string
+    Evidence   []string // 必须引用 state 中的原文标识符
+    Confidence float64  // 展示用，未校准
+    Suggestion string   // 建议文本，永不执行
+}
+```
+
+- **openai provider**：`POST {base}/chat/completions`，`response_format=json_object`，
+  严格枚举校验，429/5xx 退避重试 2 次。兼容 GLM/Qwen/DeepSeek/本地 vLLM——
+  **数据不出域**（内网拓扑、配置、作业内容不必发海外；介意第三方时 vLLM 本地起）。
+- **echo provider**：同一 Finding 结构的确定性规则实现。作用：LLM 不可用兜底、
+  单测基线、与 LLM 输出对照的 yardstick。主 provider 失败自动降级 echo，
+  决策日志记 `degraded=true`。
+- **未来 jev provider**（附录 A）：同一接口，`jev/` 目录即插即用。
+
+### 幻觉防火墙（普通 LLM 特有的必需品）
+
+`VerifyEvidence(state, findings)`：finding 的每个 evidence 元素必须在 state 原文
+中逐字出现，否则该 finding 标记 `unverified`、confidence 压到 0.2——**保留在日志**
+（这是关于模型行为的信号），但 visibly 降级。单测覆盖。
+
+## 4. 触发器（detect，无 LLM）
+
+| 场景 | 触发 | 冷却 |
+|---|---|---|
+| `pend_stall` | PEND 等待 >5min（或 PEND 数骤增 ≥5） | 10min |
+| `worker_health` | 节点 down/unknown/unavail/closed | 30min |
+| `util_skew` | 一节点 ≥80% 且另一 ≤20%（≥4 核） | 30min |
+| `exit_burst` | 轮内 ≥3 个非零 EXIT（SSE 喂入） | 30min |
+
+去重键 = 局面哈希（作业集+reason 集 / 节点集）。**同一局面不重复评估**，
+冷却只挡"局面的微小变化"。
+
+## 5. Runbook（穷人版 RAG）
+
+`internal/runbook/runbook.yaml` 内嵌 6 条本集群真实踩坑史：
+stale-deployment-config（bug-1494）、ipc-abi-skew-dead-wait（`Invalid worker PID: 0`）、
+rejoin-state-resync-crash（bug-1513）、pend-reason-race（bug-1521）、
+firstfit-placement-bias（t1 亲和）、dispatch-fail-repend（bug-1510-1512）。
+渲染进 prompt。不做向量检索——条目个位数时这是正确的复杂度。
+新故障解决后追加条目：这个文件就是集群的"病历本"。
+
+## 6. 决策日志
+
+一条评估一记录：`ts / scenario / trigger / provider / model / latency_ms /
+tokens / findings / raw / state(+digest) / degraded`。JSONL、按大小轮转。
+用途：离线评估 prompt 改动、模型升级对照、事后审计（"当时它看到了什么、
+说了什么"）。
+
+## 7. 观察到的局限（诚实清单）
+
+- 普通 LLM 无校准置信度 → `Suggestion` 永远只给人看；
+- 秒级延迟+token 成本 → 事件聚合（debounce 5s）而非逐事件判断；
+- 输出可能编造标识符 → 防火墙 + `unverified` 标记（不是丢弃，是降级）。
+
+## 8. 后续路线（未排期）
+
+| 阶段 | 内容 |
+|---|---|
+| P1 | propose 档：findings 推送（SSE/MCP 工具/CLI）；runbook 上提 schedulerclient；评估 echo vs LLM 的对照数据 |
+| P2 | act 档（仅当引入带校准置信度的 provider——见附录 A）：allowlist + 爆炸半径上限 + 审计 |
+| — | 自洽性伪置信度（k 次采样一致率）作为 act 档的非 Jev 替代——5 倍成本，只在关键判断用 |
+
+## 附录 A：Jev（TypeSafe System One）——仅记录，不实现
+
+> 2026-10 国内访问受限，P0 用普通 LLM。以下是将来接入的完整设计记录。
+
+### A.1 形态
+
+单一端点 `POST https://api.typesafe.ai/v1/systemone`，Bearer key。请求 =
+`{state: string|object, model: "jev-latest", questions: map<id, Question>}`；
+响应 = 每 question 一个类型化 answer。三种原语：
+
+| 原语 | 问法 | 返回 |
+|---|---|---|
+| **Noul** | 是/否 | `noul` 0–1 |
+| **Choice** | ≤255 选项选一 | `choice` + 全概率分布 + `confidence` |
+| **Score** | 2–10 级量规 | `score`（概率加权）+ `confidence` |
+
+特点：~100ms / ~$0.0001 每次调用（官方口径 193x faster / 444x cheaper than LLM
+workflows）；输出类型化、带**校准** confidence；不生成自由文本 → 零幻觉叙事、
+解释文本由 criteria 描述（代码写死）承载。SDK 仅 Python/JS——Go 直连 REST 即可。
+
+### A.2 问题包（替换 Finding 的 Jev 形态）
+
+以 `pend_stall_v1` 为例，一次 fan-out 调用四问：
+
+```json
+{"state": <snapshot.State>, "model": "jev-latest", "questions": {
+  "is_anomaly":   {"type":"noul","instructions":"这是调度异常而非正常排队"},
+  "root_cause":   {"type":"choice","instructions":"主因是哪类",
+                   "criteria":{"stale_config":"声明资源与观测节点不一致",
+                               "dispatch_failure":"派发尝试失败但 ack code=0",
+                               "abi_mismatch":"xcecd/xcecd_worker 版本不配对",
+                               "resource_shortage":"请求超出集群真实容量",
+                               "queue_policy":"队列/限制策略所挡",
+                               "normal_backlog":"高峰期正常排队"}},
+  "severity":     {"type":"score","instructions":"影响程度",
+                   "criteria":["info","degraded","severe","outage"]},
+  "escalate_now": {"type":"noul","instructions":"操作员应分钟级被叫醒"}
+}}
+```
+
+映射到 Finding：`root_cause.choice`→Summary 的核心（criteria 描述即人话解释）、
+`severity.score`→Severity、`noul/score confidence`→Confidence（**这个是校准的**）、
+Evidence 仍由 snapshot 原文构成（Jev 不产文本，天然无幻觉标识符问题）。
+`worker_health_v1`（choice: transient_blip/reconnect_storm/abi_or_config/host_down）、
+`util_skew_v1`（composite scoring：每 host 一个原子 score，权重在 Go 代码合成）同构。
+
+### A.3 confidence 门控（Jev 在场时才解锁 act 档）
+
+| 信号 | 行为 |
+|---|---|
+| is_anomaly < 0.7 | 只记日志 |
+| ≥0.7 且 confidence ≥0.8 | propose（人工批准） |
+| escalate_now ≥0.9 且动作在 allowlist | act（jobs kill/requeue 类；abi_mismatch 类**永不自动修**） |
+
+### A.4 风险注记
+
+- jev-1.13 官方承认 jagged edges（行为随版本变化）→ 决策日志已记录 `model` 字段，
+  版本对照天然可行；
+- Provider 接口已为其预留：`jev/` 实现 `Evaluate` 把四问答案映射成 Finding，
+  echo 降级链不变；
+- 网络可达性是国内部署的前置条件，本地无替代（模型不开放权重）。