Use when working on tools/img_gen avatar image generation, OpenAI-compatible image API config, human or yaoguai portrait prompts, qi-refining base generation, image-to-image realm edits, white-background postprocessing, manifests, or prompt rules that preserve pixel-art identity while changing cultivation realms.
规划、实现或重构角色扮演模式（默认上帝视角下的单角色接管）时使用。适用于一期文本决策、二期统一有限选择框架、三期依附 Conversation 动作的自由对话，以及对应的 runtime/API/frontend/test 收口。
规划或实现面向外部 agent / Claw 的稳定控制 API，优先做底层分层、query/command 收口、runtime 串行化与契约文档，而不是零散补接口
运行 Phase 2 工作流。执行脚本扫描缺失的多语言词条，并按注册表补全启用语言（如 en-US、zh-TW、vi-VN、ja-JP），最后修复相关测试。
国际化 (i18n) 开发指南。在添加新文本、创建物品/事件、修改翻译或管理 PO/MO 文件时使用。
创建包含正确远程处理的 Pull Request
| name | test-validate |
| description | 运行项目测试（涵盖 Python 后端、Vue 前端及多语言校验） |
推荐在已激活虚拟环境的情况下执行：
# 运行所有后端测试
pytest
# 运行特定测试文件
pytest tests/test_<name>.py -v
pytest tests/test_frontend_locales.py # 检查前端多语言一致性
pytest tests/test_backend_locales.py # 检查后端多语言一致性
# 运行并生成覆盖率报告
pytest --cov=src
# 运行服务器（开发模式）
python src/server/main.py --dev
必须在 web 目录下执行：
# 运行所有前端单元测试
cd web && npm run test
# 运行并生成前端覆盖率报告
cd web && npm run test:coverage
# 运行 TypeScript 类型检查
cd web && npm run type-check
在进行代码更改后，考虑是否需要测试：
| 更改类型 | 测试建议 |
|---|---|
| 修复 Bug | 添加回归测试以防止再次发生，确保测试在修复前会失败并且在修复后会通过 |
| 新功能 | 单元测试 + 如果影响多个模块则添加集成测试 |
| 重构 | 现有测试应通过；如果行为改变则添加测试 |
| 配置/文档 | 通常不需要测试 |
| 新增多语言词条 | 必须运行 test_frontend_locales.py / test_backend_locales.py 确保各语言 Key 结构对齐 |
提示: 如果你在编写后端测试，请参考
.cursor/rules/testing.mdc，优先使用项目中已经提供的dummy_avatar、mock_llm_managers等现成的 fixtures，避免重复 mock 或消耗真实 Token。