xiaozhi-client: Instructions file for Codex

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码仓库中工作时提供指导。

开发理念

核心原则

• 功能驱动：如无必要勿增实体，需要什么功能就实现什么功能
• 优雅实现：代码要清晰、可维护、结构合理
• 避免过度设计：不提前考虑竞态、并发、互斥锁、缓存等复杂概念
• 架构合理：整体架构要有逻辑性，但不引入不必要的抽象层
• 确认优先：当不确认时询问用户，不做自作主张的决策

开发哲学

• 先实现，后优化：先把功能做好，再考虑性能优化
• 实用主义：解决实际问题比理论完美更重要
• 简单直接：避免为了工程化而工程化
• 渐进改进：遇到问题再优化，不过度预防

开发命令

构建和测试

• pnpm build - 构建项目（包括 Web 构建和 TypeScript 编译）
• pnpm dev - 开发模式（带监视功能）
• pnpm test - 运行一次测试
• pnpm test:coverage - 运行测试并生成覆盖率报告

代码质量

• pnpm lint - 运行 Biome linter
• pnpm lint:fix - 运行 Biome linter 并自动修复（包括格式化）
• pnpm typecheck - 运行 TypeScript 类型检查
• pnpm check:all - 运行所有质量检查（lint、typecheck、spellcheck、duplicate check）

其他质量工具

• pnpm spellcheck - 使用 cspell 检查拼写
• pnpm check:cpd - 使用 jscpd 检查重复代码
• pnpm dev:docs - 启动文档开发服务器

Git Hooks（Pre-commit）

项目配置了 husky + lint-staged + commitlint，在 git commit 时自动执行以下检查：

• pre-commit: 对暂存的文件自动执行 lint 和格式化
  • *.{ts,tsx,json} → biome check --write（自动修复并重新暂存）
  • *.{md,mdx} → cspell 拼写检查
• commit-msg: 校验 commit message 符合 Conventional Commits 规范

注意: 紧急情况下可使用 git commit --no-verify 跳过 hooks，但不建议日常使用。

发布

项目使用 release-it 进行版本发布，配合 @release-it/conventional-changelog 自动生成 CHANGELOG。

标准发布流程

# 发布指定版本（正式版）
pnpm release 2.4.0 --ci

# 发布 Beta 版本
pnpm release:beta

# 或指定预发布版本号
pnpm release 2.4.0-beta.0 --preRelease=beta --ci

# 快捷发布（自动 bump patch/minor/major）
pnpm release:patch    # 2.3.0 → 2.3.1
pnpm release:minor    # 2.3.0 → 2.4.0
pnpm release:major    # 2.3.0 → 3.0.0

自动执行

• 验证工作目录是否干净
• 更新 package.json 版本号
• 生成/更新 CHANGELOG.md（基于 Conventional Commits）
• 创建 Git commit 和 tag
• 推送代码和 tag 到远程仓库（--ci 模式）
• 创建 GitHub Release
• GitHub Actions 自动执行 npm publish

预演模式

# 预演发布流程（不实际执行任何操作）
pnpm release:dry

仅本地更新（不推送）

# 显式关闭 push 和 GitHub release，避免交互过程中误推送
pnpm release 2.4.0 --git.push=false --github.release=false