Owner Console手动诊断实现从只读页面到可控真实探针

开头

在前几轮开发中，我为自己的 QQ AI 聊天机器人搭建了一个本地 Web 所有者控制台。最初的设计非常克制，只专注于一件事：让系统所有者能够查看内部状态——任务、审批、配置、运行监测，这些功能全部设置为只读。前端请求也被限制在 GET 白名单中，不执行任何工具操作，不修改配置，不触碰业务数据库。

这套只读边界策略解决了“主人如何查看系统”的问题，但很快又暴露了新的挑战：看到配置开启，并不代表功能真正可用；看到索引计数，不等于一次真实检索能够顺利完成；看到服务地址，也不意味着依赖链路已经连通。特别是 Diagnostics 页面，即便将中英文状态、原始代码和区块层级整理得清晰明了，它仍然更像一份配置清单，而不是一个能实际确认系统健康状态的诊断工具。

因此，接下来的任务是：允许主人在页面上显式触发少量、后端固定、边界可证明的手动诊断。这篇文章记录了从只读页面迈向真实探针的完整过程，以及如何避免“添加一个诊断按钮”演变为任意操作入口。

可读性优化没有解决真实性问题

在开放手动操作之前，我先重新设计了 Reliability 和 Diagnostics 页面的信息层级。Reliability 页面保留英文原始证据，中文仅用于解释，不覆盖这些关键值。确定性总结只依据结构化数据生成，不调用 LLM，也不会在缺少等长对比窗口时轻易断言“故障上升”或“故障下降”。Diagnostics 页面也遵循相同原则：中文解释含义，英文展示原始证据。

页面变得易于阅读后，所有者给出了一个非常精准的反馈：它仍然主要展示开关和快照，没有真正执行诊断，也无法判断某条实际链路是否正常工作。这个反馈帮助我们重新区分了两个概念：read snapshot（读取已有状态，适合自动刷新）和 manual diagnostic action（所有者显式批准后，执行一次有真实成本或真实外部调用的固定动作）。第二类动作不能伪装成普通 GET，也不能因为名称叫“诊断”就默认安全。

手动诊断不是自由工具面板

我没有在页面中添加自由输入框——包括自由 prompt、模型名称、Base URL、SQL 工具名、top_k、超时、重试次数等。为什么不这样做？因为一旦接受这些字段，Owner Console 就不再是“运行已注册诊断”的工具，而是在提供一个通用执行器。

最终采用的方法是固定工作流注册模型：前端只知道工作流名称和说明，后端拥有完整的输入、预算和执行逻辑，请求体只携带固定的确认信息，每次动作只执行一个已注册的工作流。首批开放的工作流是 project_doc_rag_fixed_retrieval 和 memory_rag_index_consistency。它们都属于 RAG 范畴，但安全边界完全不同，因此没有强行塞入一个“通用 RAG 测试”接口。

一个按钮背后需要多层授权

本地控制台仅监听 loopback，但这并不意味着可以随意开放 POST 请求。每个手动诊断都必须经过以下条件：服务启动时显式启用对应工作流，页面第一次点击只展开风险说明，所有者第二次点击才真正确认，请求必须来自允许的同源 Origin，必须携带进程内动作 Cookie，必须使用固定动作 Header，Content-Type 必须正确，JSON body 必须精确匹配固定的确认信息，多余字段也会被拒绝。

动作 Cookie 通过同源 GET 获取，并设置为 HttpOnly 和 SameSite=Strict。服务每次启动都会生成新的进程内动作 session，仅知道 POST 路径还不够，旧进程的 Cookie 也无法在新进程中使用。前端原有的 guard 也从“仅允许 GET”升级为精确的 allowlist：允许已有的只读 GET，仅额外允许已注册的固定 POST，未知 POST、动态路径和自由请求仍然被拒绝。这不是将整个控制台变为可写，而是在只读控制台上切割出几个非常狭窄的动作孔径。

所有真实探针共享一把全局锁

手动动作还有一个容易被忽略的问题：并发。如果所有者连续点击两个工作流，系统可能同时执行 embedding、SQLite 扫描或 LLM 请求。即使每个动作单独看是安全的，并发后也可能导致结果混乱、资源消耗异常，以及最近运行状态难以解释。

因此，这些工作流共享同一个进程内全局运行锁：当正在运行一个工作流时，其他工作流直接返回 busy 状态，不排队，不自动等待，不自动重试，完成后也不会自动串行启动下一个工作流。最近结果仅存储在 Owner Console 进程内，重启后自然清空，不写入聊天历史、Agent task、approval、reliability event 或业务诊断表。对于这种主人临时确认的本机探针来说，进程内状态反而让边界更清晰。

ProjectDocRAG：一次真实 embedding，但数据库必须只读

第一个工作流要回答的问题其实很朴素：当前的 ProjectDocRAG 能否对后端固定问题生成向量，并从现有项目文档索引中返回固定的前五项？

审计现有检索入口后，我没有直接复用该入口。原因是生产检索链会经过数据库初始化和普通可提交连接，无法证明 database_write=false。因此，这个工作流使用专用路径：固定问题仅存在于后端局部内存，当前 embedding provider 只调用一次，不做 legacy fallback，不自动重试，SQLite 使用 URI mode=ro，只查询 source_id、chunk_index 和 embedding，本地计算相似度并取 top 5。

页面不显示固定问题、文档正文、片段内容、文件路径或原始异常，只展示完成判断所需的有限证据：活动片段数、当前 provider/model 的有效向量数、返回数量、固定目标是否命中、最高相似度，以及 workflow、stage、code 等零副作用字段。

还有一个实际踩到的坑：生产配置中的 enable_project_doc_rag=false，最初被我当作手动探针的硬阻断。但这两个开关语义不同：生产功能开关控制普通运行链是否使用 ProjectDocRAG，而手动探针开关是所有者是否在本次 Owner Console 启动中批准固定诊断。最终实现将生产开关保留为 runtime_feature_enabled 证据，但不让它覆盖所有者对固定动作的独立授权。

在真实页面验收中，这个工作流完成了：一次真实 embedding、一次 SQLite mode=ro 检索、top 5 返回、固定目标命中，以及数据库大小和 mtime 保持不变。这才是“真实检索通过”，而不只是“索引看起来存在”。

MemoryRAG：只审计一致性，不读取私人正文

第二个工作流的设计思路完全不同，没有进行真实私人记忆检索。它先回答一个更基础、也更容易控制暴露面的事实问题：活动 MemoryRAG 文档与当前有效向量是否一致？

专用 SQL 仍然使用 SQLite mode=ro，并且不选择 content、summary 或其他私人正文列。它只统计：活动文档数量、当前 provider/model/content_hash 的有效向量数量、manual_fact、preference、session_summary 各自缺失数量、来源映射缺口，以及软删除历史文档所带向量数量。

这个工作流不会生成查询向量、调用 embedding、执行 retrieve_memory、读取私人记忆正文，也不会调用 ProjectDocRAG、DevContext 或 CombinedRAG，更不会重建索引、补写缺失向量或自动创建修复任务。

真实结果发现：活动文档 37 个，有效向量 35 个，缺失向量 2 个，两条缺失都属于 manual_fact，来源缺失 0 个，软删除历史向量 5 个。页面给出的结论是：outcome=attention，stage=result_validation，code=memory_rag_active_embedding_gap。注意，这不是工作流失败。工作流成功完成了只读一致性检查，并发现了一个真实缺口。因此，它需要关注，但不应该被标为“执行失败”。

succeeded、attention 和 failed 必须分开

诊断结果最容易混淆两类问题：诊断程序是否正常完成？被诊断对象是否完全满足期望？最终采用三类结果：succeeded（工作流完成，目标合同满足），attention（工作流完成，但发现兼容性、性能或一致性问题），failed（工作流本身未完成，例如配置缺失、连接失败、超时或内部错误）。

并且每个结果必须保留英文定位证据：workflow、stage、code。中文可以写“需要关注”，但不能把 memory_rag_active_embedding_gap 隐藏掉。否则，后续排障只能依赖页面文案，接口合同将重新退化为不可搜索的自然语言。

为什么发现缺口后不顺手修复

看到两条缺失向量时，最诱人的念头当然是“自动补一下”。但“知道缺少两条向量”和“批准读取相应正文并调用 embedding 写回数据库”是两种完全不同的授权。自动修复至少会扩大这些边界：读取私人内容、调用外部或本地模型、产生新的向量数据、修改数据库、处理部分成功和失败恢复、决定是否重试。

因此，本轮只记录事实，不创建修复任务，也不在页面放置一个看似方便的“立即修复”按钮。诊断的职责是让问题变得可验证，而不是替主人扩大授权。

自动化必须证明“没有做什么”

这类功能的测试不能只验证响应码是 200。我补充了几类负向合同：错误 Origin、Cookie、Header、Content-Type 或 confirmation 必须被拒绝；多余 JSON 字段必须被拒绝；页面一次确认只能产生一个 POST；两个工作流不能并发；SQLite 查询前后文件大小和 mtime 不变；MemoryRAG 查询不选择正文列；MemoryRAG provider 不能调用 embedding；ProjectDocRAG embedding 只能调用一次；前端 guard 只能放行注册过的固定 POST。

最终回归覆盖了后端、前端、TypeScript、生产构建、固定 POST guard、Python AST、依赖一致性以及 git diff --check。在真实页面验收时，还单独核对了访问日志中的 POST 次数、最近运行 ID、数据库文件大小与 mtime，以及后端日志中的 ERROR、Traceback 和 Exception。

最后

这次改造让我对“只读控制台”有了更深入的理解。一个控制台可以默认只读，同时允许少量主人批准的真实诊断；关键不在于 HTTP 方法是不是 POST，而在于动作是否满足这些条件：输入后端固定，能力启动时显式启用，主人二次确认，接口精确 allowlist，执行预算有上限，不同工作流共享并发锁，结果区分 succeeded、attention 和 failed，原始英文证据可见，不自动重试、修复或启动后续动作。

ProjectDocRAG 的价值在于证明一次真实 embedding 和只读检索能够跑通。MemoryRAG 一致性检查的价值在于发现两条真实缺口，同时证明私人正文未被读取、向量未被补建、数据库未被修改。好的诊断不仅告诉我系统做了什么，也让我能够确认：它这次没有越过哪些边界。