From 2b578440875dfcb4917ef7179bddeb01d578d3d2 Mon Sep 17 00:00:00 2001 From: "lei.chen" Date: Mon, 19 Oct 2026 03:42:29 +0000 Subject: [PATCH] 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 --- src/docs/advisor-design.md | 175 +++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 src/docs/advisor-design.md diff --git a/src/docs/advisor-design.md b/src/docs/advisor-design.md new file mode 100644 index 00000000..6d0514b3 --- /dev/null +++ b/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}`； +响应 = 每 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": , "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 降级链不变； +- 网络可达性是国内部署的前置条件，本地无替代（模型不开放权重）。