quellgeist-commits

Quellgeist

值得信赖的一线事件分诊：按置信度排序的根因假设，每条主张都有真实证据句柄作为依据——Agent 宁可弃答，也不猜测。

Quellgeist 是一个与模型无关的 AI Agent，用于生产事件的一线分诊。 它通过只读工具（结构化日志 + 最近部署 + 指标时间序列）运行清晰易懂的 JSON-action ReAct 循环，然后生成结构化的诊断： 按置信度排序的根因假设，每条假设都有 Agent 实际看到的结构化证据句柄（LogRef.id / CommitRef.sha / MetricRef.id）作为依据——绝不使用自由文本。它的两大特色是：

• 引用结构化句柄。 证据是可核验的句柄，而不是句子，因此伪造引用是可衡量的，并且会被无密钥伪造检查确定性地拒绝——这不是模糊字符串匹配的问题。
• 宁可弃答，不要幻觉。 自信地给出错误原因是最糟糕的答案，因此，*"证据不足"*是一种一等结果。

状态：Wave 4 已完成——微调有效。 对本地推理模型（Qwen3-4B，通过 Ollama 提供服务）进行的 DR-0020 QLoRA 微调，使其在留出集上的表现从基础模型的 0/16 提升到 12/16——零伪造、零推测性筛选，成本还比基础模型更低——同时在同一留出集上以 $0、完全离线的方式胜过 31B 前沿模型（Gemma-4-31B，10/16）。通过三种方式交叉验证未记忆：fixtures ≈ 留出集；core-fresh ≥ core-overlap；结构探测 7/10。 有两个需要如实说明的局限：resource_exhaustion 类别未能迁移（0/N；前沿模型能通过），系统层面的对抗性弃答召回率为 6/12——31B 前沿模型也有同样的上限（同为 6/12），这不是微调导致的退步。该 Agent 出错时只会不完整或过于谨慎，绝不会自信地伪造。请参阅 状态与路线图 · 微调案例研究。

有何不同

证据是句柄	每个假设都会引用日志行中来源稳定的 id 或提交的 sha，这些值从工具结果中逐字复制——确定性伪造检查据此进行查询。说明文字保存在仅用于显示的 note 中。（DR-0009）
弃答是一项功能	当信号较弱时，Agent 会返回 abstained=true、弃答原因和空的假设列表——由架构强制执行。
从设计上与模型无关	循环会从普通聊天文本中解析 JSON 操作，因此无论使用 Gemini 免费层还是本地 4-bit Qwen，运行方式都完全相同——不依赖任何后端的原生函数调用。只需更改一项配置即可切换模型。（DR-0008、DR-0010）
可靠性由门禁把关，而非口头保证	每次推送都会运行无密钥、确定性的 CI 门禁（ruff + black + pytest，包括由 fixtures 支持的评估工具）。

它是什么 / 它不是什么

• **它是：**一线 分诊 Agent——基于只读日志/部署/指标，给出按可能性排序、附有证据引用的根因假设（或坦诚弃答）；其模型无关的循环既可运行在托管的前沿模型上，也可运行在本地 4B 模型上。
• **它不是：**自主修复器（它绝不会修改生产环境——解决方案验证是延期、优先精简的后续阶段）；也不是经过生产级加固的服务（演示刻意设计成玩具示例）；更不是通用 Agent。它所评估的留出集是 词汇表外但结构内 的——这并不代表它能处理未见过的事件形态或真实生产数据。

快速入门（约 30 秒即可让服务故障并生成结构化日志）

需要 uv 和 Python 3.12+。

只需一条无需密钥的命令，即可查看符合真实情形的诊断结果（无需模型，也无需 API 密钥）：

uv sync && uv run quellgeist diagnose --demo     # renders the demo incident's cited postmortem

然后针对正在运行的玩具服务执行完整循环：

uv run uvicorn demo.app.main:app          # 1. start the toy service (leave running)

# --- in a second shell, from the repo root ---
uv run python -m demo.chaos.bad_deploy    # 2. inject a simulated bad deploy
curl -s localhost:8000/login              # 3. trip /login -> 500s + structured error logs
uv run quellgeist diagnose --show-trace   # 4. diagnose live (needs a model; see below)

uv run python -m demo.chaos.reset         # back to a green slate

实时步骤需要一个推理器——请参阅运行模型。 没有密钥时，quellgeist diagnose 会以状态码 1 退出，并输出一行错误信息和提示（绝不会显示回溯）；--demo 始终无需密钥即可运行，并根据 gold 确定性地生成相同格式的输出。

架构

自定义且清晰易懂的循环充当编排层；三个只读工具构成证据接口；Diagnosis 架构则是事后分析渲染器和评测裁判共同读取的契约。

flowchart TD
    trigger(["incident trigger - CLI"]) --> loop
    model["reasoner via LiteLLM<br/>(Gemini or local Qwen, swappable)"] -. "chat completion" .-> loop

    subgraph loopbox["model-agnostic JSON-action ReAct loop"]
      loop["run_loop()<br/>decide, call tool, observe, repeat"]
    end

    loop -- "query_logs" --> logs["logs tool<br/>structured JSONL, stable ids"]
    loop -- "get_recent_commits" --> commits["commits tool<br/>deploy_log.json, shas"]
    loop -- "query_metrics" --> metrics["metrics tool<br/>time-series, named series"]
    logs -- "rows + ids" --> loop
    commits -- "commits + shas" --> loop
    metrics -- "series + names" --> loop

    loop --> diag["Diagnosis (schema.py)<br/>ranked hypotheses citing<br/>LogRef.id / CommitRef.sha / MetricRef.id, or abstains"]
    diag --> pm["postmortem renderer<br/>deterministic Markdown"]
    diag --> judge["eval judge<br/>fixture scenarios, CI gate"]

这三个工具也都通过标准输入/输出作为 MCP 服务公开（python -m quellgeist.servers.logs_mcp、…commits_mcp、…metrics_mcp）。Agent 目前通过 ToolSpec 注册表，在进程内复用相同的工具函数；标准输入/输出 MCP-客户端路径（由 Agent 通过线缆驱动这些服务）已列入路线图（DR-0010）。

深入了解：docs/architecture.md 介绍了完整流程（循环 → 工具 → 验证器 → 事后分析）、时序图、模块映射和跨领域设计决策。

每次发布带标签的版本时，服务都会发布到 Official MCP Registry（请参阅docs/publishing.md）；发布后，每个服务都可以通过 uvx --from quellgeist quellgeist-logs-mcp（或 …-commits-mcp / …-metrics-mcp）运行。

示例会话

注入有问题的部署——它会写入一个标记，使 verify_token 出现 NoneType 回归，并生成 deploy_log.json；其中的问题提交正好在错误出现前合入（以下为示例 stdout——时间戳会反映你的运行时间；路径相对于仓库根目录）：

$ uv run python -m demo.chaos.bad_deploy
injected bad deploy a1b2c3d (touched demo/app/auth.py) at 2026-06-24T12:22:43Z
  marker:     demo/.bad_deploy
  deploy log: demo/deploy_log.json
next: hit /login to generate the 500s, then `quellgeist diagnose`

配置好推理器后，quellgeist diagnose 会读取日志和部署信息并生成事后分析报告。CI 环境中没有经过验证的模型密钥（DR-0012），因此以下诊断结果由 gold 渲染——通过 render_postmortem 根据夹具中带标签的原因和证据句柄确定性生成，并非模型实时输出：

# Incident Postmortem (rendered from gold)

## Root-cause hypotheses

### 1. Bad deploy a1b2c3d (10:01:50Z) refactored auth.py and introduced a NoneType error in verify_token; /login 500s begin ~20s later at 10:02:12Z.  (confidence: 1.00)

Evidence:
- log #2
- commit a1b2c3d

你也可以自行复现该渲染结果（无需模型）：

uv run python - <<'PY'
from evals.scenarios.generator import load_scenario
from quellgeist.agent.schema import Diagnosis, Hypothesis
from quellgeist.output.postmortem import render_postmortem

s = load_scenario("evals/scenarios/fixtures/bad_deploy_0001.json")
gold = Diagnosis(hypotheses=[
    Hypothesis(cause=s.gold_cause, confidence=1.0, evidence=s.gold_evidence_refs)
])
print(render_postmortem(gold, title="Incident Postmortem (rendered from gold)"))
PY

重点不在于文字描述，而在于 log #2 和 commit a1b2c3d 是指向真实信号的精确句柄，而非转述。实时运行还会补充一行摘要和建议操作；证据不足以确定可信原因时，则会直接弃答。

使用 --out postmortem.md 将事后分析报告写入文件，或使用 --out postmortem.html（或 --format html）生成独立的 HTML 页面——渲染结果同样是确定性的，不依赖外部资源。

运行模型

推理模型可以是任意 LiteLLM 模型字符串，通过 --model 或 QG_MODEL 环境变量选择（默认值为 gemini/gemini-3.5-flash）。LiteLLM 从环境变量读取服务提供商密钥；仓库中不会存储任何内容。

export QG_MODEL="gemini/gemini-3.5-flash"
export GEMINI_API_KEY="…"
uv run quellgeist diagnose --show-trace

也可以通过 Ollama 完全在本地离线运行——这是预期的家庭默认方案 （DR-0008；具体工件已在 DR-0019 中固定），无需 API 密钥：

ollama pull qwen3:4b-instruct-2507-q4_K_M
export QG_MODEL="ollama_chat/qwen3:4b-instruct-2507-q4_K_M"
uv run quellgeist diagnose --show-trace

基础版与微调版——重要。 上面的 ollama pull 拉取的是基础版 Qwen3-4B： 它是诚实、安全的底线——在留出集上得分为 0/16，对所有情况都弃答， 绝不捏造（DR-0019）。12/16 的头条结果来自 DR-0020 微调版（quellgeist-qwen3-dr0020）， 你可以通过 finetune/README.md 构建并提供服务（免费 Colab QLoRA 运行 → ollama create）。在发布该微调 GGUF、可通过一行命令拉取之前，普通 ollama pull 提供的都是基础模型——安全，但尚无实用性。要查看实时诊断，请使用托管模型（上文）或微调版。

提醒（DR-0012）：在未经验证且未启用计费的项目中使用 Gemini 密钥，会导致当前模型返回 429 limit: 0，因此随附的 CI 门禁特意设计为无需密钥；由模型驱动的评估则需要密钥，并在 带外运行（DR-0015）。在家中，预期的默认推理模型是通过 Ollama 运行的本地 Qwen3-4B （DR-0008）。

运行评估（推理模型 + 验证器 + LLM 评审器）

夹具评估使用确定性的关键词评审器为推理模型评分，并检查是否存在捏造内容（无需密钥的门禁）； 此外还可以运行两个模型层（DR-0016）：一个验证器，用于确认引用的证据支持各项假设 （否则强制弃答），以及一个提供建议的 LLM 评审器评分标准。

export GEMINI_API_KEY="…"
export QG_MODEL="gemini/gemini-3.5-flash"
QG_VERIFY=1 QG_JUDGE_LLM=1 \
QG_MIN_CALL_INTERVAL_S=6 \      # pace calls under the free-tier RPM (avoids 429 bursts)
  uv run python -m evals.run_evals

QG_VERIFIER_MODEL / QG_JUDGE_MODEL 可分别指定各层使用的模型（默认使用 QG_MODEL）。后端无法访问（配额不足/503/超时）或凭据被拒绝（密钥缺失/无效/过期） 时，都会报告为跳过，而非失败（DR-0015/DR-0017），因此带外评估不会因免费套餐的小故障而 显示红色。LLM 评审器的评分仅供参考（不会用于门禁）。在人工标注的黄金子集上，使用独立 评审模型（groq/llama-3.1-8b-instant ≠ 推理模型）时，它与人工判定结果的一致性达到 Cohen's kappa 0.81——该结果已在此子集上验证（DR-0018）；但当 QG_JUDGE_MODEL 与推理模型相同时，仍属于自我评分。

CI 的带外评估通过 Groq 运行（groq/llama-3.3-70b-versatile，需要 GROQ_API_KEY）：Gemini 免费套餐在云端 CI 中被证明无法使用（429 → 503 → 超时 → 密钥无效），因此只需更改一个环境变量就替换了推理模型——这正体现了模型无关的 理念（DR-0017）。预期的家庭默认方案仍是本地 Qwen3-4B（DR-0008）。

在真实数据上使用

演示程序会读取三个规范文件；你的生产信号并非如此。 quellgeist ingest 是适配器——将其指向真实数据源，它就会写入工具所读取的规范文件：

quellgeist ingest \
  --logs    /var/log/myapp/     # file or directory; JSONL, JSON, plain text, or mixed
  --deploys deploys.json        # JSON array, GitHub payload, or `git log` text
  --metrics prom.json           # a Prometheus response or a canonical array
  --out-dir ./signals
# prints the `export QG_*` lines; then:
quellgeist diagnose --show-trace --strict-citations   # add --model / a provider key

它能够处理杂乱的真实数据（将外部字段名映射到架构字段、把时间戳规范化为 UTC、将格式错误的 行强制转换，而不会导致运行崩溃），并且 query_logs 会限制单次观测返回的行数（QG_MAX_ROWS， 默认值为 200），避免大型日志撑爆上下文窗口。确定性的“引用或弃答”保证在实际使用时 生效：diagnose 会针对真实信号验证每个引用的句柄，并在发现捏造内容时发出警告（--strict-citations 会在 CI 中以非零状态码退出）。完整指南：docs/ingestion.md。

运行实时服务（v2）

v2 将同一个冻结核心封装成实时、并发、可观测的事件响应服务：经过签名的 webhook 会触发调查，工作池会在每个事件隔离的快照上运行未改动的循环，每次运行及其跟踪记录和成本都会持久化到 SQLite，操作员会先批准 / 引导 / 拒绝，然后服务才会将结果发布到 Slack 和一份独立的 HTML 页面；沙盒修复后，Agent 会重新读取信号以确认恢复情况。所有内容均为增量改动；冻结的测量面保持不变。整个技术栈只需一个文件即可运行：

cp .env.example .env            # set QG_WEBHOOK_SECRET, QG_OPERATOR_TOKEN, QG_VERIFIER_MODEL…
docker compose up --build       # demo service + agent service + Ollama
docker compose exec ollama ollama pull qwen3:4b-instruct-2507-q4_K_M   # first run only

# break it, trigger an investigation, review, then confirm the fix in the sandbox:
docker compose exec demo python -m demo.chaos.bad_deploy
#   … POST a signed incident to :8000/incidents, approve it on the HTML page …
docker compose exec demo python -m demo.chaos.fix_deploy   # heal without wiping the log
#   … POST /incidents/{id}/verify-resolution → recovered | not_recovered | inconclusive

密钥仅通过环境变量提供（因为这是公开仓库）；服务采用故障关闭机制——未设置 webhook 密钥时会拒绝所有请求，未设置操作员令牌时会关闭操作员界面，并且绝不会发布捏造的或未经验证的诊断结果。设计文档：DR-0023 + 规范。

状态与路线图

项目分阶段滚动推进——只有当前阶段实现了详细内容 （参见 docs/quellgeist-plan-rolling-wave.md）。 完整的决策历史记录见 ADR 日志。

阶段	范围	状态
0	降低模型选择风险（4B 能否编排此循环）	✅ 已完成 — 默认模型 = Qwen3-4B（DR-0008）
1	错误部署切片：演示 → 破坏 → 诊断 → 事后分析；评测框架 + CI	✅ 已完成 — 核心链路已构建并通过单元测试
2	可靠性核心：验证器检查、确定性捏造检测、弃答、大模型裁判	✅ 已构建 — 提供无需密钥的确定性门控，并可选择启用验证器 / 裁判；首次真实运行通过，未出现捏造（DR-0016/DR-0017）。裁判验证 + 可靠性率将延续到阶段 3
3	扩大覆盖面：配置 / 环境变量 + 资源耗尽类别、指标、约 50 个场景	✅ 已完成 — 65 个场景的测试套件覆盖 3 个类别；首次完整运行结果为 61/65，0 捏造；裁判已验证（kappa 0.81）。参见可靠性和裁判验证案例研究
4	成本 / 微调：QLoRA Qwen3-4B 与基础模型及前沿模型对比，含 / 不含验证器	✅ 已完成 — 基础模型 0/16 → 微调后保留集 12/16（0 捏造、0 推测性过滤；成本低于基础模型）；与 Gemma-4-31B 相比具备竞争力（能力方面 16 项中胜出 10 项，弃答方面 12 项中打平 6 项）；resource_exhaustion 未能学会 + 对抗性弃答的共同上限为 6/12（案例研究，DR-0019/DR-0020）
5	润色并发布：HTML 渲染、安全审查、MCP 注册表、上线	🚧 工程已完成 — 等待发布审批（HTML 渲染 + 安全扫描器 + 威胁模型 + 注册表 / OIDC 脚手架均已完成；剩下发布标签和上线）
6	解决情况验证循环	⤳ 已并入 v2（阶段 9）
v2（7–9）	实时事件响应服务（webhook → 并发工作器 → 持久化运行记录 → HITL 审核 → Slack/HTML → 沙盒解决情况复核）+ Dockerfile/compose	✅ 已构建 — 阶段 7–9 已交付：经过签名的 webhook → 并发工作器 → 持久化且带引用的运行记录 → 故障关闭的 HITL 审核门控 → Slack/HTML → 确定性沙盒解决情况复核；非 root Docker + compose；339 项无需密钥的测试，冻结部分的差异为空（DR-0023/0027/0028，规范）
v2 轨道 B（10）	可靠性轨道：考虑时序的验证器 + 结构变化 / 结构外泛化评测	🚧 已规划 — DR-0024–0026

阶段边界是刻意划定的，并非尚未完成：只有当前阶段实现了详细内容，后续阶段已规划，但有意暂不实现。v2 是在经过验证的 v1 核心上进行的增量扩展——冻结的微调测量面绝不会更改（DR-0023；由 tests/frozen/ 保护）。

可靠性门槛

确定性 CI 门槛是可靠性契约：339 项测试（通过 pre-commit 运行 ruff

• black，然后运行 pytest——涵盖循环永不崩溃／优雅弃答行为、确定性伪造检查和 基于引用的判定门槛、验证器和辅助 LLM 判定器、参数化 场景生成、判定器验证测试框架、服务端筛选器、事后分析渲染器、基于固定测试数据的评估测试框架、真实数据导入 + 稳健性层、端到端真实事件测试框架，以及 v2 实时服务—— 签名 Webhook、每个事件的并发隔离、HITL 审核门槛和 确定性沙箱解决方案检查），在 Python 3.12 和 3.13 上运行。

在常规流程之外，模型驱动评估会在 65 个场景的 测试套件上运行推理器。最近一次完整运行的得分为通过 61/65 项，0 项伪造证据 （Cerebras Gemma-4-31B）——各类别明细和失败分析见 可靠性案例研究。

uv run pytest tests/ -q
uv run pre-commit run --all-files

开发与贡献

开发环境设置、约定和 wave 模型见 CONTRIBUTING.md；举报方式和禁止机密信息／ 玩具演示政策见 SECURITY.md；社区行为规范见 CODE_OF_CONDUCT.md。Bug 报告和功能请求请使用 问题模板；PR 请遵循 PR 模板。

许可证

MIT © Rajeev Shyam Kumar。