OmniStudio 排障

目标：用证据定位到具体原因，再给出可执行的修复动作。

这个技能存在的理由：没有它的时候，"为什么生图失败"很容易被答成一段对着工作区文件猜的分析 （"工作区里没有生图模型配置，所以模型无法生图"）—— 看着有道理，但和真实原因毫无关系， 用户照着做也修不好。这个应用有日志、有控制通道、有数据库，先去读，再下结论。

铁律

1. 没有证据不下结论。 每个结论后面必须能指到一行日志、一条数据库记录或一条命令输出。 读不到证据就说"需要先加日志 / 需要复现"，不要用推理填空。
2. 不要猜用户的工作区。 应用的功能（生图、推理、语音…）配置在应用设置和数据库里， 不在用户当前的工作区文件里。用户提了一句"帮我调生图"，工作区里没有生图配置文件是正常的， 那不是失败原因。
3. 区分三类原因，修复路径完全不同：
   • 配置/环境问题 → 用户自己能在界面上修（reference/playbooks.md 里有逐条对应）；
   • 代码缺陷 → 需要改代码 / 升级版本（reference/escalation.md）；
   • 数据损坏 / 磁盘 / 网络 → 有专门的处理步骤。
4. 默认只读。 排查不改用户数据。确需写操作（清日志、重启服务）时先说清楚再执行。
5. 日志里可能有本地路径与提示词 —— 提醒用户别把整份报告贴到公开渠道；密钥已被自动脱敏成 ***。

第一步：拿到现场（一条命令）

bun run --cwd apps/studio scripts/omni-diag.ts            # 人类可读报告
bun run --cwd apps/studio scripts/omni-diag.ts --json      # 给脚本/Agent 用
bun run --cwd apps/studio scripts/omni-diag.ts --logs 80   # 多带点日志

只读，应用没运行也能跑（起不来 / 闪退的场景才是它最重要的用途）。它一次性给出：

• 版本 / 渠道 / 数据目录 / 数据库 / 磁盘剩余；
• 应用是否在运行，推理服务器与网关状态、最后错误、服务器日志尾部；
• 统一日志 logs/app.log 里最近的 warn / error（按子系统归类）；
• 媒体服务端口占用者身份（本实例 / 另一个数据目录的实例）；
• 数据库里最近失败的记录：生图 / 生视频 / 语音 / 文档 / 基准 / 自动化 / Agent 事件；
• 关键配置是否就位（密钥只报"有没有"）。

第二步：按用户描述的症状定位

第三步：读日志的正确姿势

omi logs --level error --limit 50 -v        # 只看错误，带完整上下文
omi logs --source image --verbose                  # 单个子系统
omi logs --search "IncompleteSnapshot"      # 按关键字找（报错原文）
omi logs -f --source agent                  # 跟踪（让用户复现，实时看）
omi logs --path                             # 日志文件路径

日志是一条条 JSONL，一行一个事件，字段是 { ts, level, source, event, message, detail, pid }。 event 是机器可读的事件名（如 image.generate.failed），它比 message 更稳定， 用它来定位分支；detail 里通常有后端类型、模型名、地址、提示词片段等。 完整字段说明、各 source 的含义、旧版遗留的日志位置 → reference/logs.md

应用没在运行时 omi logs 直接读磁盘上的文件 —— 闪退场景一样能用。

第四步：给用户修复方案

• 配置类：直接给出「设置 → 哪个页面 → 填什么」的具体路径。playbooks.md 里每条原因都配了 界面位置（例如生图后端与模型在「图像」页，本地 MLX 还要先下引擎和权重）。
• 环境类：给出可复制的命令（brew install whisper-cpp、装 Python 3.10+ 等）。
• 数据/网络类：给出重试与清理路径（重下模型、清 mlx-downloads/<id>.json 状态等）。
• 代码缺陷：按 reference/escalation.md 写工单，并告诉用户 "这个需要升级程序才能解决" —— 不要让他反复重试。

第五步：验证

修完必须复验，不能只说"应该好了"：

• 重跑一次用户的那个操作，或
• 跑对应的只读检查（如 omi server logs 看到 server is listening、omi diag 里该子系统不再有 error），
• 再 omi logs --level error --limit 10 确认没有新错误。

相关文件（改代码时需要）

排障经常落到"这是代码 bug"，此时要能直接读实现的失败路径，而不是通读整个仓库：

目录与接口速查

• 数据目录：~/Library/Application Support/omni-studio.kunpengtalk.com/<channel>（dev / canary / stable） —— 库 omni-studio.db、日志 logs/app.log、模型 models/、引擎 engines/、 媒体 images/ uploads/、控制 socket omni-control.sock。
• 读接口：omi CLI（status / logs / server logs / models / memory / backup inspect）、 控制 socket（HTTP over unix socket，{cmd,payload}）、媒体服务 127.0.0.1:19782、 直接只读打开 SQLite。
• 完整清单（含每个命令、socket 命令、RPC 方法组、数据库表）→ reference/surfaces.md

参考文件

• reference/logs.md —— 统一日志格式、各 source / event、遗留日志位置
• reference/surfaces.md —— CLI / 控制 socket / RPC / 媒体服务 / 数据库全清单
• reference/playbooks.md —— 按症状编排：错误原文 → 原因 → 修复
• reference/escalation.md —— 确认是代码缺陷时：工单模板与话术