Undefined: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Undefined 是基于 Python asyncio 的高性能 QQ 机器人平台，通过 OneBot V11 协议（NapCat/Lagrange.Core）与 QQ 通信，搭载认知记忆架构、自研 Skills 系统、本地知识库、全局表情包库，以及 Management-first WebUI / Desktop / Android 管理端。

开发命令

# 依赖安装 / 初始化
uv sync
uv run playwright install       # 页面截图等能力依赖的浏览器运行时

# 启动
uv run Undefined-webui          # 启动 Management-first WebUI（推荐入口）
uv run Undefined                # 直接启动 Bot

# WebUI 自动启动 Bot
# 配置 [webui].autostart_bot = true 后，运行 uv run Undefined-webui 会自动拉起 bot 进程
# 默认为 false，保持传统手动启动行为
# 注意：该配置仅在 WebUI 启动时生效，运行时修改需重启 WebUI

# 代码质量（提交前必须全部通过）
uv run ruff format .
uv run ruff check .
uv run mypy .                   # strict=true
uv run pytest tests/
uv run pytest tests/test_xxx.py
uv run pytest tests/test_xxx.py::test_func -v
uv build --wheel                # 校验打包与资源包含

# 前端 / 桌面端（仅改动 apps/undefined-console/ 或 apps/undefined-chat/ 或 webui/static/js/ 时需要）
cd apps/undefined-console && npm ci && npm run check
cd apps/undefined-console && npm run dev
cd apps/undefined-console && npm run tauri:dev

cd apps/undefined-chat && npm ci && npm run check
cd apps/undefined-chat && npm run tauri:dev

# Git hooks 安装
bash scripts/install_git_hooks.sh
# pre-commit 自动执行：ruff format --check + ruff check + mypy
# 含 JS/Tauri 改动时额外执行：Biome + TypeScript + cargo fmt/check

代码规范

• 类型注释：所有 Python 代码必须有完整类型注释，mypy strict 模式
• 异步 IO：磁盘读写必须走 utils/io.py（asyncio.to_thread + 跨平台文件锁 + 原子写入），禁止在事件循环中直接阻塞 IO
• Python 版本：>=3.11, <3.14（推荐 3.12）
• 测试：pytest + pytest-asyncio，asyncio_mode = "auto"
• 前端格式化：src/Undefined/webui/static/js/ 由根目录 biome.json 管理；apps/undefined-console/ 和 apps/undefined-chat/ 走 Biome + TypeScript + Cargo 检查
• 版本号同步：发布版本时优先使用 uv run python scripts/bump_version.py <version>，统一同步 Python 包、console、chat 与 Tauri 版本号
• Git hooks：优先通过 scripts/install_git_hooks.sh 安装，不要手动维护 core.hooksPath

架构分层

核心源码位于 src/Undefined/，主要模块如下（目录级事实来源是 docs/development.md 的目录树，本表只做职责概览）：