// ✅ 推荐的别名使用（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";

2. 别名配置验证

检查项目配置文件中的路径别名设置是否正确和一致。

验证项目

tsconfig.json - TypeScript 编译器配置
vitest.config.ts - 测试框架配置
tsup.config.ts - 构建工具配置
package.json - 导入映射配置（如存在）

标准别名映射

// 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 等）
}

3. 自动修复建议

为检测到的问题提供具体的修复建议和代码示例。

修复示例

// ❌ 原始代码（相对路径）
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/ 目录下的所有文件，确保它们正确使用 @/ 路径别名体系。

CLI模块检查

请检查 src/cli/ 目录下的所有文件，确保CLI命令正确使用 @/cli 路径别名。

核心模块检查

请检查 src/mcp-core/ 目录下的所有文件，确保核心MCP功能正确使用 @/mcp-core 路径别名。

文档专项检查

请检查 docs/ 目录下的所有 MDX 文件，确保文档中的代码示例使用正确的 xiaozhi-client 路径别名。

文档批量修复

请批量修复文档中的路径别名问题，重点关注代码示例中的 import 语句。

文档质量验证

请验证文档更新后的正确性，确保修复后的代码示例语法正确且符合项目规范。

检查流程

1. 扫描阶段

源代码扫描：遍历项目中的所有 TypeScript/JavaScript 文件
文档扫描：扫描所有 MDX 文件中的代码块
语句识别：识别所有 import 和 export 语句
路径提取：提取相对路径使用情况

2. 分析阶段

路径映射：分析相对路径的目标位置
别名确定：确定应该使用的别名
上下文分析：分析代码块的语言和上下文
例外识别：识别例外情况（紧密相关的模块、测试文件等）

3. 文档特殊处理阶段

代码块解析：解析 MDX 文件中的代码块
语言识别：识别代码块的编程语言
示例分类：区分示例代码和配置代码
教学价值评估：评估修复对教学效果的影响

4. 验证阶段

配置一致性：检查配置文件的一致性
语法正确性：验证修复建议的正确性
功能完整性：确保不会破坏现有功能
文档可读性：确保修复后文档仍然清晰易懂

5. 报告阶段

问题分类：区分源代码和文档中的问题
修复建议：提供具体的修复建议
优先级标记：标记优先级和影响范围
文档影响评估：评估修复对文档质量的影响

例外情况

源代码中的例外

以下情况下相对路径是可以接受的：

紧密相关的模块

// 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/*"]  // 配置文件中的相对路径
  }
}

文档修复策略

教学优先：当修复可能影响教学效果时，优先考虑教学价值
添加说明：在保留相对路径示例时，添加说明解释为什么使用相对路径
提供对比：同时展示相对路径和别名路径的使用方式
标注上下文：明确标注代码示例的上下文和适用场景

工具集成

与其他技能的协作

type-validator - 确保别名使用不会破坏类型安全
mock-generator - 确保 Mock 数据正确使用别名导入
api-docs - 确保生成的文档反映正确的路径结构

CI/CD 集成

可以作为 CI 流程的一部分，自动检查新代码是否遵循路径别名规范。

最佳实践建议

1. 导入顺序

// 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";

2. 类型导入优先

// ✅ 推荐
import type { HassState } from "@/types";

// ❌ 避免
import { HassState } from "@/types";

3. 一致性原则

同一文件中对同一目录的模块使用一致的导入方式。

验证检查清单

通过这个技能的帮助，可以确保项目始终遵循路径别名最佳实践，提高代码质量和可维护性。