Menu
路径别名系统检查与修复
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
提交、推送并创建 PR
自动发现项目中的代码问题并提交 GitHub Issue
安全审计技能，用于检查和修复依赖安全问题
文档自动生成
CI检查验证和质量保障
生成代码评审友好的 commit 信息
| name | path-alias-validator |
| description | 路径别名系统检查与修复 |
我是路径别名系统检查与修复技能，专门针对 xiaozhi-client 项目的路径别名系统进行检查、验证和优化，同时遵循务实开发理念。
核心能力：检测项目中相对路径的使用情况，并提供别名替换建议。
../ 格式的导入语句./ 格式的导入语句// ✅ 推荐的别名使用（xiaozhi-client 项目 @/ 路径别名体系）
import { LightService } from "@/server/services";
import type { HassState } from "@/types";
import { formatDate } from "@/utils";
// ❌ 需要修复的相对路径
import { LightService } from "../services";
import type { HassState } from "../types";
import { formatDate } from "./utils";
检查项目配置文件中的路径别名设置是否正确和一致。
// xiaozhi-client 项目完整别名映射（单体架构，统一 @/ 路径别名体系）
{
"@/types": ["./src/types"], // 共享类型定义
"@/config": ["./src/config"], // 配置管理
"@/mcp-core": ["./src/mcp-core"], // MCP 协议核心
"@/endpoint": ["./src/endpoint"], // 端点处理
"@/esp32": ["./src/esp32"], // ESP32 硬件相关
"@/cli": ["./src/cli"], // CLI 命令行工具
"@/utils": ["./src/utils"], // 通用工具
"@/server": ["./src/server"] // 后端服务（含 handlers、services、routes 等）
}
为检测到的问题提供具体的修复建议和代码示例。
// ❌ 原始代码（相对路径）
import { UserService } from "../services/user";
import type { APIResponse } from "../types/api";
import { formatDate } from "./utils/date";
import { Command } from "./commands/help";
// ✅ 修复后（xiaozhi-client @/ 路径别名体系）
import { UserService } from "@/server/services/user";
import type { APIResponse } from "@/types/api";
import { formatDate } from "@/utils/date";
import { Command } from "@/cli/commands/start";
请检查当前项目的路径别名使用情况，识别所有需要修复的相对路径。
请验证项目中所有配置文件的路径别名设置是否一致和正确。
请帮我修复检测到的路径别名问题，自动替换相对路径为 @/xxx 格式的别名。
请检查 src/server/services/ 目录下的所有文件，确保它们正确使用 @/ 路径别名体系。
请检查 src/cli/ 目录下的所有文件，确保CLI命令正确使用 @/cli 路径别名。
请检查 src/mcp-core/ 目录下的所有文件，确保核心MCP功能正确使用 @/mcp-core 路径别名。
请检查 docs/ 目录下的所有 MDX 文件，确保文档中的代码示例使用正确的 xiaozhi-client 路径别名。
请批量修复文档中的路径别名问题，重点关注代码示例中的 import 语句。
请验证文档更新后的正确性，确保修复后的代码示例语法正确且符合项目规范。
以下情况下相对路径是可以接受的：
// light.test.ts 可以使用相对路径导入 light.ts
import { LightService } from "./light";
// 同一目录下的工具函数
import { helperFunction } from "./helpers";
// 运行时动态导入
const module = await import(`../modules/${moduleName}`);
文档中的代码示例有特殊的例外规则：
// 当文档需要解释相对路径概念时
import { utils } from "../shared/utils"; // 这是相对路径的示例
// 对比展示：相对路径 vs 别名路径
// 相对路径写法：
import { Service } from "./service";
// 别名路径写法：
import { Service } from "@/services/service";
// 展示其他项目或框架的代码示例
import { Component } from "../components/Button";
{
"paths": {
"./*": ["./src/*"] // 配置文件中的相对路径
}
}
可以作为 CI 流程的一部分，自动检查新代码是否遵循路径别名规范。
// 1. Node.js 内置模块
import { fs } from "node:fs";
import { path } from "node:path";
// 2. 外部依赖
import express from "express";
import { Command } from "commander";
// 3. xiaozhi-client @/ 路径别名导入（按分组排序）
// 核心类型和配置
import type { AppConfig, XiaozhiConfig } from "@/types";
import { getConfig } from "@/config";
// MCP 核心
import { MCPConnection } from "@/mcp-core";
// CLI 相关
import { Container } from "@/cli";
import { StartCommand } from "@/cli/commands/start";
// 后端服务
import { HandlerManager } from "@/server/handlers/HandlerManager";
import { ConfigService } from "@/server/services/ConfigService";
// 工具函数
import { formatDate } from "@/utils";
// 4. 相对路径（同模块内引用，仅在必要时）
import { helperFunction } from "./helpers";
// ✅ 推荐
import type { HassState } from "@/types";
// ❌ 避免
import { HassState } from "@/types";
同一文件中对同一目录的模块使用一致的导入方式。
import type 语法通过这个技能的帮助，可以确保项目始终遵循路径别名最佳实践，提高代码质量和可维护性。