SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场validate-system

validate-system

部署与运维

查看项目

更新于 10-15 11:02

技能介绍

用途

validate-system 是 Nexus-v3 的系统健康检查技能，用于执行全面的系统完整性校验，验证结构完整性、检查导航映射的准确性、运行可选的 Python 验证钩子，并尝试自动修复常见问题。当导航信息看起来陈旧、在手动修改文件之后，或作为周期性维护时使用该技能。

主要能力

该技能包含以下检查与能力：

  • 全面检查：核心文件、目录结构、记忆文件、导航、项目、技能。
  • 映射完整性校验：确保 skill-map.md 与 project-map.md 准确。
  • Python 钩子：运行自动化验证器（可选，不可用时优雅跳过）。
  • 自动修复：重新生成导航、重建模板、修复结构。
  • 详细报告：清晰报告检查项、问题与修复内容。
  • 时间预估：完整校验少于 10 秒。

具体检查内容包括：

  • 核心文件：验证关键系统文件是否存在。
  • 目录结构：检查所需目录。
  • 记忆文件：校验 Memory/ 内容。
  • 导航文件：检查 framework-map.md 与 skill-map.md。
  • 项目：校验 02-Projects/ 中的所有项目。
  • 技能：校验 00-system/Skills/ 中的所有技能。
  • 映射完整性：确保映射与实际文件一致。
  • Python 钩子：运行验证钩子（如果可用）。
  • 自动修复：自动修复常见问题。
  • 报告：生成并显示全面报告。

详细校验步骤参见 references/validation-checks.md；报告模板参见 references/report-templates.md。

使用方式

工作流从初始化 TodoList 开始，创建 TodoWrite 并列出全部校验步骤：

  • [ ] Check core files
  • [ ] Check folder structure
  • [ ] Check memory files
  • [ ] Check navigation files
  • [ ] Validate projects
  • [ ] Validate skills
  • [ ] Check map integrity
  • [ ] Run Python hooks (if available)
  • [ ] Auto-fix issues
  • [ ] Generate report
  • [ ] Display report
  • [ ] Close session to save progress

每完成一步即标记任务完成。随后执行校验工作流，完成上述各项检查、自动修复与报告生成。

最后一步：关闭会话。自动触发 close-session 技能：

Auto-triggering close-session to save progress...

这确保所有校验结果与自动修复内容正确保存到记忆中。

错误处理

  • 关键文件缺失：当 framework-map.md、orchestrator.md 或 claude.md 缺失时，报告为 CRITICAL ERROR，无法自动修复（系统已损坏），建议从备份恢复或重新安装 Nexus-v3，并且不继续执行自动修复（不安全）。
  • Python 钩子崩溃：当 Python 钩子脚本崩溃或返回无效 JSON 时，优雅捕获错误，报告“Hook {name} crashed: {error}”，加入问题列表，并继续其他钩子（不阻塞校验）。
  • 无法写入文件：当自动修复因文件权限问题失败时，报告“Cannot write to {file}: {error}”，加入手动修复列表，提供手动操作说明，并继续其他自动修复。
  • 记忆文件损坏：当 Memory/ 文件存在但不是有效 markdown 时，报告“{file} is corrupted (invalid markdown)”，询问是否替换为空模板（会丢失当前内容），等待用户确认；若确认则替换为模板，若拒绝则加入手动修复列表。
  • 项目文件夹为空：当 Projects/ 存在但为空（仅在首次设置时出现）时，报告“Projects/ folder is empty (no projects yet)”，注明“这对新用户是正常的”，建议“说 'create project' 开始你的第一个项目！”，并标记为 INFO（不是错误）。
  • 技能文件夹为空：当 Skills/ 存在但为空时，报告“No user skills found (Skills/ folder empty)”，注明“如果你还没有创建任何技能，这是正常的”，建议“运行 create-skill 添加你的第一个技能！”，并标记为 INFO（不是错误）。

适用场景

何时运行 validate-system：

  • 手动编辑文件之后
  • 导航看起来陈旧或不准确时
  • 意外删除文件之后
  • 作为周期性维护（每周/每月）
  • 系统行为看起来异常时

运行频率：可疑时随时运行；手动在技能之外修改文件后运行；定期（每周或每月）维护运行；正常使用技能/项目后不需要运行（close-session 会处理）。

限制与注意事项

自动修复安全性：

  • 只修复非破坏性问题
  • 绝不删除用户内容
  • 创建模板、重新生成导航
  • 关键问题需要人工干预

Python 钩子：

  • 完全可选（没有它们系统也能工作）
  • 提供更深入的自动化校验
  • 如果 Python 不可用则优雅跳过
  • 自定义钩子可添加到 00-system/hooks/

钩子 JSON 格式：

{ "valid": true/false, "errors": [ {"file": "path", "line": 42, "message": "error description", "severity": "error"} ], "warnings": [ {"file": "path", "line": 15, "message": "warning description", "severity": "warning"} ] }

映射完整性的重要性：

  • skill-map.md 必须与 Skills/ 文件夹一致
  • 02-projects/project-map.md 必须与 Projects/ 文件夹一致
  • 失效链接会破坏导航
  • close-session 会自动维护完整性

与 close-session 的集成：

  • close-session 自动维护映射完整性
  • validate-system 在会话之间捕获问题
  • 两者共同维护系统健康

请记住：validate-system 是你的系统健康检查。当出现异常时运行它，并让它自动修复能修复的问题！