[code review] Tim 对 dev 分支 的 code reivew

.cursor/rules/project/always.mdc

@@ -0,0 +1,15 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Important: Use English to write codes and comments.
+
+This is a long-term project in the early, internal development stage and not yet online. 
+
+Please use best practices and optimal architecture for long-term maintenance.
+When modifying code and documentation, backward compatibility does not need to be considered, and the code version should always be 1.0.0. Do not include comments about deprecation or compatibility with old versions. Immediately remove any unused code instead of retaining it.
+
+When receiving requirements from the user, first rephrase them using professional technical terminology to ensure mutual understanding and allow for corrections. The user acknowledges they may not use precise technical language, so clarification is encouraged.
+
+Prioritize professional engineering judgment over literal instruction following. You are authorized to modify or extend requirements based on code quality, maintainability, and best practices. Focus on implementing the user's intent rather than their exact words, making technical decisions that serve the long-term health of the codebase.

.cursor/rules/project/clean-code.mdc

@@ -0,0 +1,57 @@
+---
+description: 
+globs: *.py
+alwaysApply: false
+---
+# Clean Code Guidelines
+
+## Constants Over Magic Numbers
+- Replace hard-coded values with named constants
+- Use descriptive constant names that explain the value's purpose
+- Keep constants at the top of the file or in a dedicated constants file
+
+## Meaningful Names
+- Variables, functions, and classes should reveal their purpose
+- Names should explain why something exists and how it's used
+- Avoid abbreviations unless they're universally understood
+
+## Smart Comments
+- Don't comment on what the code does - make the code self-documenting
+- Use comments to explain why something is done a certain way
+- Document APIs, complex algorithms, and non-obvious side effects
+- Write docstrings to make the function's intent, usage, and parameters fully clear to someone who only reads the docstring. Save implementation details for the docstring, and reserve high-level, conceptual explanations for the documentation.
+
+## Single Responsibility
+- Each function should do exactly one thing
+- Functions should be small and focused
+- If a function needs a comment to explain what it does, it should be split
+
+## DRY (Don't Repeat Yourself)
+- Extract repeated code into reusable functions
+- Share common logic through proper abstraction
+- Maintain single sources of truth
+
+## Clean Structure
+- Keep related code together
+- Organize code in a logical hierarchy
+- Use consistent file and folder naming conventions
+
+## Encapsulation
+- Hide implementation details
+- Expose clear interfaces
+- Move nested conditionals into well-named functions
+
+## Code Quality Maintenance
+- Refactor continuously
+- Fix technical debt early
+- Leave code cleaner than you found it
+
+## Testing
+- Write tests before fixing bugs
+- Keep tests readable and maintainable
+- Test edge cases and error conditions
+
+## Version Control
+- Write clear commit messages
+- Make small, focused commits
+- Use meaningful branch names 

.cursor/rules/project/docs.mdc

@@ -0,0 +1,12 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+Maintain all documentation in Chinese (but use English to write code). For overviews, refer to the docs/**/readme.md files. Use tables, code blocks, and mermaid flowcharts to make the documentation clear and visually appealing. 
+
+Avoid including actual code examples whenever possible. For API documentation, use generic configuration examples with comments explaining what should be filled in, rather than specific plugin configurations. 
+
+When providing configuration file examples, always use real examples found in the codebase—do not make them up. However, for API request/response examples, use generic placeholders with descriptive comments to ensure the documentation remains universally applicable across different plugins.
+
+Focus on explaining the purpose and structure of parameters rather than specific values, emphasizing the distinction between plugin_config (for instance creation and routing) and custom (for runtime parameter overrides).

.cursor/rules/python/fastapi.mdc

@@ -0,0 +1,91 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+---
+description: FastAPI best practices and patterns for building modern Python web APIs
+globs: **/*.py, app/**/*.py, api/**/*.py
+---
+
+# FastAPI Best Practices
+
+## Project Structure
+- Use proper directory structure
+- Implement proper module organization
+- Use proper dependency injection
+- Keep routes organized by domain
+- Implement proper middleware
+- Use proper configuration management
+
+## API Design
+- Use proper HTTP methods
+- Implement proper status codes
+- Use proper request/response models
+- Implement proper validation
+- Use proper error handling
+- Document APIs with OpenAPI
+
+## Models
+- Use Pydantic models
+- Implement proper validation
+- Use proper type hints
+- Keep models organized
+- Use proper inheritance
+- Implement proper serialization
+
+## Database
+- Use proper ORM (SQLAlchemy)
+- Implement proper migrations
+- Use proper connection pooling
+- Implement proper transactions
+- Use proper query optimization
+- Handle database errors properly
+
+## Authentication
+- Implement proper JWT authentication
+- Use proper password hashing
+- Implement proper role-based access
+- Use proper session management
+- Implement proper OAuth2
+- Handle authentication errors properly
+
+## Security
+- Implement proper CORS
+- Use proper rate limiting
+- Implement proper input validation
+- Use proper security headers
+- Handle security errors properly
+- Implement proper logging
+
+## Performance
+- Use proper caching
+- Implement proper async operations
+- Use proper background tasks
+- Implement proper connection pooling
+- Use proper query optimization
+- Monitor performance metrics
+
+## Testing
+- Write proper unit tests
+- Implement proper integration tests
+- Use proper test fixtures
+- Implement proper mocking
+- Test error scenarios
+- Use proper test coverage
+
+## Deployment
+- Use proper Docker configuration
+- Implement proper CI/CD
+- Use proper environment variables
+- Implement proper logging
+- Use proper monitoring
+- Handle deployment errors properly
+
+## Documentation
+- Use proper docstrings
+- Implement proper API documentation
+- Use proper type hints
+- Keep documentation updated
+- Document error scenarios
+- Use proper versioning 

.cursor/rules/python/pydantic/description.mdc

@@ -0,0 +1,21 @@
+---
+description: 
+globs: **/models/**/*.py
+alwaysApply: false
+---
+Description: 
+Guidelines for writing user-friendly field descriptions in Pydantic models:
+
+- **Tone**: Use clear, present tense language. Avoid overly technical jargon.
+- **Format**: Remove unnecessary annotations like "(Required)" or "(Optional)" - this info is already in Field definitions.
+- **Voice**: Use active voice and directly state the field's purpose and function.
+- **Length**: Keep descriptions concise but complete with all necessary information.
+- **Technical Terms**: When technical terms are required, provide simple explanations.
+- **Consistency**: Use similar phrasing patterns for fields with similar functions.
+- **Punctuation**: End all descriptions with periods for consistency.
+
+Examples:
+- Good: "The unique identifier for this world."
+- Bad: "Unique World ID. (Required)"
+- Good: "Whether interactions in this world influence the character's memory."
+- Bad: "Does this world's interactions influence this specific character's long-term memory? (Required)."