xiaozhi-client: Skill for Claude Code

我是路径别名系统检查与修复技能，专门针对 xiaozhi-client 项目的路径别名系统进行检查、验证和优化，同时遵循务实开发理念。

技能使用原则

• 保持代码质量，但避免过度工程化：维护路径别名的一致性，但不追求过度复杂的设计
• 实用功能优先，理论完美次之：解决实际的导入问题比完美的路径设计更重要
• 简单解决方案优于复杂方案：在复杂和简单之间做出合理选择
• 务实开发指导：评估路径别名设计的必要性，避免过度设计

技能能力

1. 路径别名使用检查

核心能力：检测项目中相对路径的使用情况，并提供别名替换建议。

检测范围

• 源代码文件：TypeScript/JavaScript 文件中的导入语句
• 文档文件：MDX 文件代码块中的示例代码
• 跨目录相对路径：../ 格式的导入语句
• 同级目录引用：./ 格式的导入语句
• 混合使用情况：同一文件中别名和相对路径混用
• 配置一致性：各配置文件中别名配置的一致性检查

文档场景特殊处理

• 代码块识别：自动识别 MDX 文件中的 TypeScript/JavaScript 代码块
• 示例代码检查：检查文档中的代码示例是否遵循路径别名规范
• 教学一致性：确保文档示例展示最佳实践
• 语法高亮支持：支持多种编程语言的路径检查

检查规则

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