| name | system-diagnostics |
| description | StudySolo 系统全量自检专属技能。当用户希望测试所有 AI 模型、子 Agents、数据库、内部服务的连通性与健康状态时自动触发。强制走 scripts/diagnostics/ 脚本路径，日志必须落盘到 scripts/logs/，并输出激活确认语。 |
| triggers | ["系统自检","全量健康检查","一键全检","跑.*诊断","诊断.*系统","检查.*所有.*模型","测试.*所有.*AI","测试.*所有.*Agents","测试.*所有.*接口","健康检查","health.*check","运行诊断","诊断.*报告","检查后端.*可用"] |
🩺 System Diagnostics — StudySolo 系统自检强制执行技能
⚡ 激活确认语（MANDATORY — 必须第一行输出）
当本技能被触发，AI 的第一行输出必须是以下格式，证明技能已激活：
⚡ 系统诊断 SOP 激活 | 目标：[all|database|ai_model|agent|service] | 日志输出：scripts/logs/diagnostics-<timestamp>.{log,md,json,txt}
示例：
⚡ 系统诊断 SOP 激活 | 目标：all | 日志输出：scripts/logs/diagnostics-<timestamp>.{log,md,json,txt}⚡ 系统诊断 SOP 激活 | 目标：ai_model | 日志输出：scripts/logs/diagnostics-<timestamp>.{log,md,json,txt}
❌ 若未输出此激活语，视为技能未正确加载，必须重新读取本文件并重新开始。
📚 强制阅读文档（MANDATORY READS）
在输出激活确认语之后，立即按顺序读取以下所有文件，全部读完后才能开始执行。
| 顺序 | 文件路径 | 必读原因 |
|---|
| 1 | docs/项目规范与框架流程/功能流程/系统自检与诊断/README.md | 总入口，理解三触发面 |
| 2 | docs/项目规范与框架流程/功能流程/系统自检与诊断/00-诊断总览.md | 检测矩阵、权限、响应结构 |
| 3 | docs/项目规范与框架流程/功能流程/系统自检与诊断/01-一键全量自检SOP.md | 三种触发路径与退出码语义 |
| 4 | docs/项目规范与框架流程/功能流程/系统自检与诊断/02-分组诊断SOP.md | 仅当用户只要求某类检测时 |
| 5 | docs/项目规范与框架流程/功能流程/系统自检与诊断/03-故障排查手册.md | 出现 unhealthy 时按此排查 |
| 6 | docs/项目规范与框架流程/功能流程/系统自检与诊断/04-日志与报告规范.md | 日志命名与脱敏规则 |
| 7 | .agent/skills/system-diagnostics/checklists.md | 分级执行清单 |
🔧 执行步骤（MANDATORY FLOW）
Step 1：环境探测
# 1.1 检查后端是否在运行
Invoke-WebRequest -Uri "http://127.0.0.1:2038/api/health" -UseBasicParsing -TimeoutSec 3
- 若失败 → 提示用户运行
./scripts/start-studysolo.ps1 后再重试，不要盲目继续。
Step 2：Token 检测
if (-not $env:STUDYSOLO_ADMIN_TOKEN) {
# 提示用户提供 Admin Token
}
- 优先使用环境变量
STUDYSOLO_ADMIN_TOKEN
- 其次使用用户显式传入
- 若都没有 → 明确告知用户如何获取（见 SOP 01 章节）
Step 3：调用一键脚本（仅此一种方式）
.\scripts\diagnostics\run-diagnostics.ps1 -Category <目标> -Format all
严格禁止：
- ❌ 直接
curl 或 Invoke-RestMethod 调后端（日志不会落盘，违反 SOP）
- ❌ 修改后端代码来"绕过"权限（安全红线）
- ❌ 跳过日志落盘直接给用户口头结论
Step 4：解析最新日志
# 读取最新的 .md 报告
$latest = Get-ChildItem scripts\logs\diagnostics-*.md | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Get-Content $latest.FullName -Encoding UTF8
Step 5：汇报结果
结构化输出：
- 摘要：total / healthy / unhealthy / 耗时
- 故障组件列表（如有）：逐项列出 id、error、category
- 建议动作：对每个故障组件给出排查步骤（引用 SOP 03）
- 日志路径：明确告知三个报告文件的绝对路径
🚫 禁止事项
| 禁止 | 原因 |
|---|
| 不输出激活确认语 | Skill 未正确加载 |
| 不读取 SOP 直接执行 | 可能跳过脱敏、日志落盘、权限检查 |
| 不跑脚本凭猜测回答 | 结果不可审计，无日志证据 |
日志写到 scripts/logs/ 之外 | 违反日志规范，git 会意外追踪 |
| 回答中泄露 admin token 值 | 安全红线 |
| 声称"已修复"但没跑回归 | 必须修复后再跑一次 run-diagnostics.ps1 确认 |
✅ 完成判定
只有当以下全部满足，才可认为本次诊断任务闭环：
📎 快速参考
- 后端端点：
GET /api/admin/diagnostics/full
- 脚本位置：
scripts/diagnostics/run-diagnostics.ps1
- 日志目录：
scripts/logs/
- Web UI：
/admin-analysis/diagnostics
- 实现代码：
backend/app/api/admin_diagnostics.py
