| name | system-diag |
| description | 通过分析运行时日志、资源指标和守护进程状态诊断 MindX 系统健康， 输出包含根因识别和修复建议的结构化诊断报告。当用户报告系统问题、 守护进程崩溃、性能下降或请求主动健康检查时使用。 作为 `mindx doctor`（静态检查）的补充，提供 AI 驱动的日志分析和 跨组件关联分析。
|
| allowed-tools | bash read sub-agent collect-results |
| metadata | {"name_zh":"系统诊断","name_zh-tw":"系統診斷","description_zh":"通过分析运行时日志、资源指标和守护进程状态诊断 MindX 系统健康，输出结构化诊断报告与修复建议","description_zh-tw":"通過分析運行時日誌、資源指標和守護進程狀態診斷 MindX 系統健康，輸出結構化診斷報告與修復建議"} |
触发判断
遇到以下情况时使用此技能：
- 用户要求检查系统健康、诊断问题或分析日志
- 用户报告守护进程崩溃、重启或无响应
- 用户遇到性能下降（响应缓慢、卡顿）
- 运维智能体执行例行健康检查
以下情况不要使用：
- 静态配置验证——改用
mindx doctor
- 单个 Bug 修复或代码问题——直接修复
- 功能开发——改用
software-dev 技能
与 mindx doctor 的关系：
mindx doctor（CLI） | 本技能（AI） |
|---|
| 静态规则检查（文件存在？进程在运行？） | 日志内容分析 + 模式识别 + 关联分析 |
| 表层：什么出了问题 | 深层：为什么发生 + 如何修复 |
工作流程
阶段 1：收集证据
从 5 个维度收集数据。某个维度失败不会阻塞其他维度。
A: 运行时快照
- mindx status → 安装/配置/守护进程状态
- curl http://localhost:{port}/api/health → 服务组件健康状态
- ps aux | grep "mindx daemon" → 进程资源使用情况
B: 日志
- {workspace}/logs/mindx.log → 主日志（所有级别，JSON 格式）
- {workspace}/logs/error.log → 错误日志（ERROR 及以上）
- {workspace}/logs/daemon.log → 守护进程标准输出
- {workspace}/logs/daemon.err.log → 守护进程标准错误
- *.log.gz → 轮转历史日志（用于回溯）
C: 存储状态
- du -sh {workspace}/data/ → 数据目录大小
- du -sh {workspace}/data/models/ → 模型文件大小
- ls {workspace}/*.db → bbolt 数据库文件
- df -h {workspace} → 磁盘空间
D: 系统资源
- ulimit -n → 文件描述符限制
- vm_stat (macOS) / free -h (Linux) → 内存压力
- launchctl list | grep mindx → launchd 注册状态
E: 网络（可选）
- lsof -i :{port} -P → 端口监听状态
注意： {workspace} 在 macOS/Linux 上解析为 ~/.mindx，在 Windows 上为 %APPDATA%\mindx。端口来自用户配置或默认值。
阶段 2：分析日志
MindX 日志使用 uber-go/zap JSON 格式。要阅读并关联分析，不要只是逐行扫描。
2.1 重建时间线
按 ts 排序所有事件，映射守护进程生命周期的关键节点：
[启动] → [调度器?] → [网关] → [Web 服务器?] → [运行中...] → [异常?]
2.2 错误频率与模式聚合
统计每个 ERROR/WARN 的出现次数和时间分布：
gateway start failed ×1 (23:01:02)
Scheduler failed to start ×3 (~每 2 小时)
knowledge-graph unavailable ×0
2.3 跨组件关联
把看似独立的错误关联到单一根因：
症状 A: "gateway start failed: bind: address already in use"
症状 B: 进程列表中发现过期 PID
推断: 之前的守护进程未正常退出，端口未释放
根因: launchd KeepAlive 未正确处理守护进程崩溃
2.4 趋势分析
对比轮转日志中的退化信号：
今天： 12 个 WARN 事件
昨天： 3 个 WARN 事件
前天： 0 个 WARN 事件
→ 问题在恶化，需要关注
2.5 已知错误模式
加载 references/error-patterns.md 获取完整的 错误→根因→修复 映射。
高频模式快速索引：
| 错误关键词 | 可能的根因 | 参考 |
|---|
address already in use | 端口冲突 / 过期进程 | 参见参考文档 |
too many open files | 文件描述符耗尽 | references/resource-exhaustion.md |
context deadline exceeded | API 超时 / 网络问题 | 参见参考文档 |
knowledge-graph database unavailable | 图数据库损坏 / 权限问题 | references/storage.md |
failed to initialize kvstore | KVStore 损坏 / 磁盘已满 | references/storage.md |
Scheduler failed to start | 调度器存储损坏 | 参见参考文档 |
阶段 3：生成诊断报告
用以下模板输出结构化报告：
# MindX 系统诊断报告
**时间**：{timestamp}
**守护进程运行时长**：{uptime}
**日志覆盖范围**：{log_time_range}
---
## 严重（需立即处理）
### {N}. {问题标题}
- **症状**：{可观测行为}
- **证据**：`{logfile}:{line}` — `{原始日志摘录}`
- **根因**：{从证据推导出的逻辑结论}
- **影响**：{受影响的功能}
- **修复**：{具体步骤}
- **预防**：{避免再次发生的建议}
## 警告（尽快处理）
{与上述格式相同}
## 信息（优化建议）
{非问题，改进机会}
## 系统资源概览
| 指标 | 值 | 状态 |
|------|-----|------|
| 守护进程内存 | {RSS} MB | 🟢/🟡/🔴 |
| 守护进程 CPU | {cpu%} | 🟢/🟡/🔴 |
| 磁盘使用 | {used}/{total} ({pct}%) | 🟢/🟡/🔴 |
| 日志大小 | {size} | 🟢/🟡/🔴 |
| 文件描述符 | {open}/{limit} | 🟢/🟡/🔴 |
| 重启次数（24h） | {count} | 🟢/🟡/🔴 |
## 总结
{一段话的整体健康评估 + 最优先的 1-2 项}
阶段 4：执行修复（需授权）
仅在用户明确要求时（--fix 或"修复它"）才执行：
- 安全修复 — 直接执行：终止过期进程、释放端口、裁剪过大的日志
- 配置变更 — 应用前展示差异
- 存储操作 — 操作数据库/数据文件前先备份
- 不确定的情况 — 标记为"需人工介入"，不要猜测
原则
- 基于证据 — 每个结论必须引用具体的日志行；没有证据不要推测
- 优先单一根因 — 先假设一个根因能解释所有症状，直到出现矛盾再考虑多因分析
- 区分症状与原因 — "网关失败"是症状，"端口被占用"是原因，"崩溃遗留的过期进程"是根因
- 时间敏感推理 — 短时间内密集出现的错误 > 零散的单个事件
- 不要危言耸听 — 单个 WARN 不是系统故障；用频率 + 趋势来衡量严重程度
- 可操作的输出 — 每个诊断必须包含具体的修复步骤；永远不要说"可能是个问题"
反模式
- 不要跳过证据收集仅凭假设诊断
- 不要将每个 WARN 都视为严重问题——结合频率和趋势上下文判断
- 不要给出模糊的建议如"检查一下配置"——具体说明检查什么以及为什么
- 未经用户明确授权不要修改数据文件或数据库
- 不要将相关性误认为因果——两个错误同时出现不一定有关联
- 不要省略总结部分——用户需要清晰的优先行动列表
