🔨 Update mdc cursor rules and claude.md for backend services, apps, english comments and global environments, which would be applied automatically during the chat.

🐛 Bugfix: agent thread improper declaration

Author: Jasonxia007

.cursor/rules/backend/app_layer_rules.mdc

@@ -0,0 +1,114 @@
+---
+globs: backend/apps/**/*.py
+description: App layer (API) contract for FastAPI endpoints in backend/apps. Parse/validate input, call services, map domain errors to HTTP, return JSONResponse on success.
+---
+
+### Purpose and Scope
+
+- The App layer is the HTTP boundary for the backend. It applies to files under `backend/apps/*.py`.
+- Responsibilities:
+  - Parse and validate HTTP inputs.
+  - Call underlying services; do not implement core business logic here.
+  - Translate domain/service exceptions into `HTTPException` with proper status codes.
+  - Return `JSONResponse(status_code=HTTPStatus.OK, content=payload)` on success.
+- Configuration: Do not access environment variables directly. Read configuration via `consts.const` or pass values through from the request to services.
+
+References: [backend/consts/exceptions.py](mdc:backend/consts/exceptions.py)
+
+### Routing and URL Design
+
+- Keep existing top-level prefixes for compatibility (e.g., `"/agent"`, `"/memory"`). When adding new modules or endpoints, follow these rules:
+  - Use plural nouns for collection-style resources (e.g., `"/agents"`, `"/memories"`).
+  - Use snake_case for all path segments. Avoid hyphens and camelCase.
+  - Prefer resource-oriented paths for CRUD-style operations. Example: `"/agents"` (collection), `"/agents/{agent_id}"` (single resource).
+  - Use action-style paths only when necessary to match current patterns or when the operation is not naturally CRUD (e.g., `"/agent/run"`, `"/agent/stop/{conversation_id}"`).
+  - Path parameters must be singular, semantic nouns: `"/agents/{agent_id}"`, `"/memories/{memory_id}"`.
+  - Keep backwards compatibility: do not rename existing routes; new routes should follow these conventions.
+
+### HTTP Methods
+
+- GET: Read and list operations only. Maintain existing special cases where GET performs safe actions (e.g., `GET /agent/stop/{conversation_id}`), but do not introduce new side-effecting GETs.
+- POST: Create resources, perform searches, or trigger actions with side effects (e.g., `POST /memory/add`, `POST /memory/search`, `POST /agent/run`).
+- DELETE: Delete resources or clear collections (e.g., `DELETE /memory/clear`). Ensure idempotency.
+- PUT/PATCH: Update resources. Prefer `PUT` for full updates and `PATCH` for partial updates. Preserve legacy `POST /update` endpoints for compatibility but favor PUT/PATCH for new code.
+
+### Authorization and Identity
+
+- Retrieve the bearer token via header injection: `authorization: Optional[str] = Header(None)`.
+- Use utility helpers to parse identity (prefer functions in `utils.auth_utils`, such as `get_current_user_id` or `get_current_user_info`) and pass `user_id` and/or `tenant_id` down to services. The App layer should not implement token parsing logic itself.
+
+### Request Validation
+
+- Prefer Pydantic models in `consts.model` as request bodies for complex payloads (e.g., `AgentRequest`).
+- For simple atomic fields, use `Body(..., embed=True)` to pin the JSON key name.
+- Use `Query(...)` for filters and pagination, `Path(...)` for path parameters, and `Header(...)` for headers.
+- Pagination recommendations for listing endpoints: `page: int = Query(1, ge=1)`, `page_size: int = Query(20, ge=1, le=100)`, plus optional `order_by`, `filters` as appropriate. Return pagination metadata (`items`, `total`) or match existing return shapes in the codebase.
+
+### Responses
+
+- On success, return `JSONResponse(status_code=HTTPStatus.OK, content=payload)`.
+- If a standard response model exists in the project (e.g., conversation responses), continue to use it for consistency.
+- For new endpoints, return a structured content dictionary with necessary fields (e.g., `{"data": ..., "message": "OK"}`) while staying consistent with existing patterns.
+
+### Exception Mapping
+
+- Catch domain/service exceptions from `backend/consts/exceptions.py` and map to `HTTPException` with appropriate status codes. Examples:
+  - `UnauthorizedError` → 401 UNAUTHORIZED
+  - `LimitExceededError` → 429 TOO_MANY_REQUESTS
+  - Parameter/validation errors (e.g., invalid enum, unknown config key) → 400 BAD_REQUEST or 406 NOT_ACCEPTABLE (follow existing precedent such as `set_single_config` using 406)
+  - Unexpected errors → 500 INTERNAL_SERVER_ERROR (log the error; do not leak internal details)
+
+### Logging and Observability
+
+- Use a module-level logger: `logger = logging.getLogger("<module_name>")`.
+- Log key events and errors. For listing/search endpoints, optionally log query scope and timing while avoiding sensitive data.
+
+### Async/Sync Conventions
+
+- Match the existing style in each module. Keep `async def` where already used.
+- When calling async services, prefer direct `await`. When calling sync services, invoke them directly without creating new event loops.
+
+### Backward Compatibility
+
+- Do not break existing routes, payload shapes, or response structures.
+- New endpoints should follow these conventions strictly to converge the API style across modules.
+
+### Correct Example (parse input, call service, map exceptions, return JSONResponse)
+```python
+from http import HTTPStatus
+import logging
+from fastapi import APIRouter, HTTPException
+from starlette.responses import JSONResponse
+
+from consts.exceptions import LimitExceededError, AgentRunException, MemoryPreparationException
+from services.agent_service import run_agent
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+@router.post("/agent/run")
+def run_agent_endpoint(payload: dict):
+    try:
+        result = run_agent(payload)
+        return JSONResponse(status_code=HTTPStatus.OK, content=result)
+    except LimitExceededError as exc:
+        raise HTTPException(status_code=HTTPStatus.TOO_MANY_REQUESTS, detail=str(exc))
+    except MemoryPreparationException as exc:
+        raise HTTPException(status_code=HTTPStatus.BAD_REQUEST, detail=str(exc))
+    except AgentRunException as exc:
+        raise HTTPException(status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail=str(exc))
+```
+
+### Incorrect Example (business logic in App layer or non-HTTP error handling)
+```python
+from starlette.responses import JSONResponse
+
+def run_agent_endpoint(payload: dict):
+    # WRONG: performing core business logic inside the app layer
+    if payload.get("force"):
+        return {"status": "forced"}  # WRONG: returns plain dict without HTTP status context
+
+    # WRONG: not translating domain errors to HTTP
+    result = risky_logic(payload)
+    return JSONResponse(result)
+```

.cursor/rules/backend/service_layer_rules.mdc

@@ -0,0 +1,113 @@
+---
+globs: backend/services/**/*.py
+description: Service layer implements core business logic orchestration; raise custom exceptions; no HTTP handling
+---
+
+### Service Layer Rules
+
+- **Scope**: Applies to `backend/services/*.py`.
+- **Goal**: Implement core business logic and orchestrate complex workflows. Coordinate repositories/SDKs. Keep HTTP concerns out of this layer.
+- **Exceptions**: Raise domain/service exceptions declared in `backend/consts/exceptions.py`. If a new case is needed, add a new class there, then raise it here. Do not translate to HTTP here.
+- **Environment variables**: Do not access `os.getenv()` directly. Read configuration from `consts.const` (see `environment_variable` rule) or accept parameters.
+
+Reference: [backend/consts/exceptions.py](mdc:backend/consts/exceptions.py)
+
+### Correct example (service orchestrates business logic and raises domain exceptions)
+```python
+# backend/services/agent_service.py
+from typing import Any, Dict
+
+from consts.exceptions import LimitExceededError, AgentRunException, MemoryPreparationException
+# from consts.const import APPID, TOKEN  # Example: read config via consts, not os.getenv
+
+
+def run_agent(task_payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Run agent core workflow and return domain result dict.
+    Raises domain exceptions on failure; no HTTP concerns here.
+    """
+    if _is_rate_limited(task_payload):
+        raise LimitExceededError("Too many requests for this tenant.")
+
+    try:
+        memory = _prepare_memory(task_payload)
+    except Exception as exc:
+        # Wrap low-level error in a domain exception for the app layer to translate
+        raise MemoryPreparationException("Failed to prepare memory.") from exc
+
+    try:
+        result = _execute_core_logic(task_payload, memory)
+    except Exception as exc:
+        raise AgentRunException("Agent execution failed.") from exc
+
+    # Return a plain Python object, not a Response
+    return {"status": "ok", "data": result}
+
+
+def _is_rate_limited(_: Dict[str, Any]) -> bool:
+    return False
+
+
+def _prepare_memory(_: Dict[str, Any]) -> Dict[str, Any]:
+    return {"memo": "prepared"}
+
+
+def _execute_core_logic(_: Dict[str, Any], __: Dict[str, Any]) -> Dict[str, Any]:
+    return {"answer": "42"}
+```
+
+### Incorrect example (service leaks HTTP/web concerns or reads env directly)
+```python
+# backend/services/agent_service.py
+from fastapi import HTTPException  # WRONG: HTTP in service
+from starlette.responses import JSONResponse  # WRONG: Response in service
+import os  # WRONG: direct env access in service
+
+
+def run_agent(_: dict):
+    # WRONG: translating to HTTP inside service
+    if os.getenv("RATE_LIMIT", "0") == "1":  # WRONG: direct getenv here
+        raise HTTPException(status_code=429, detail="Too many requests")
+
+    # WRONG: returning framework response from service
+    return JSONResponse({"status": "ok"})
+```
+
+### Declaring a new custom exception (do this in exceptions module)
+```python
+# backend/consts/exceptions.py
+class OrderProcessingError(Exception):
+    """Raised when order processing fails in service layer."""
+    pass
+```
+
+### Existing exceptions (excerpt from current code)
+```python
+"""
+Custom exception classes for the application.
+"""
+
+
+class AgentRunException(Exception):
+    """Exception raised when agent run fails."""
+    pass
+
+
+class LimitExceededError(Exception):
+    """Raised when an outer platform calling too frequently"""
+    pass
+
+
+class UnauthorizedError(Exception):
+    """Raised when a user from outer platform is unauthorized."""
+    pass
+
+
+class SignatureValidationError(Exception):
+    """Raised when X-Signature header is missing or does not match the expected HMAC value."""
+    pass
+
+
+class MemoryPreparationException(Exception):
+    """Raised when memory preprocessing or retrieval fails prior to agent run."""
+    pass
+```

.cursor/rules/english_comments.mdc

@@ -1,121 +1,37 @@
 ---
 alwaysApply: true
+description: Enforce English-only comments and docstrings across the codebase
 ---
-# English Comments Rule
+# English-only Comments
 
-## English-Only Comments Requirement
+- All comments and docstrings must be written in clear, concise English.
+- Do not use non-English characters in comments (string literals may contain any language).
+- Use proper grammar and spelling; avoid ambiguous abbreviations.
 
-All code comments MUST be written in English. No Chinese, Japanese, Korean, or other non-English languages are allowed in comments.
-
-### ✅ Correct Pattern:
+## Do
 ```python
-# Initialize the processor with default settings
-processor = DataProcessor()
-
-# Cache inspector for 60 seconds
-self._inspector_ttl = 60
-
-# Ensure current application configuration is correct
-if not self._validate_config():
-    raise ConfigurationError("Invalid configuration")
-
-# Concurrently fetch all task details asynchronously
-tasks = await self._fetch_all_tasks_async()
-
-# Lazy load CLIP model
-self._clip_model = None
+# Initialize cache for 60 seconds
+self.cache_ttl = 60
 ```
 
-### ❌ Forbidden Pattern:
+## Don't
 ```python
-# 初始化处理器
-processor = DataProcessor()
-
-# inspector缓存时间，秒
-self._inspector_ttl = 60
-
-# 确保当前应用配置正确
-if not self._validate_config():
-    raise ConfigurationError("Invalid configuration")
-
-# 并发异步获取所有任务详情
-tasks = await self._fetch_all_tasks_async()
-
-# 延迟加载CLIP模型
-self._clip_model = None
+# 初始化缓存 60 秒 - FORBIDDEN
+# データキャッシュ60秒 - FORBIDDEN
+# 데이터 캐시 60초 - FORBIDDEN
 ```
 
-## Architecture Rules
-
-1. **English-Only Comments**: All comments must be written in English, regardless of the target audience or deployment region.
-
-2. **Code Documentation**: 
-   - Function docstrings must be in English
-   - Inline comments must be in English
-   - TODO comments must be in English
-   - FIXME comments must be in English
-
-3. **Variable and Function Names**: 
-   - Variable names can be in English or follow existing naming conventions
-   - Function names should be descriptive in English
-   - Class names should be in English
-
-4. **String Literals**: 
-   - User-facing strings can be localized
-   - Error messages can be localized
-   - Comments and documentation must remain in English
+## Scope
+- Docstrings, inline comments, TODO/FIXME/NOTE, header comments
+- Configuration comments in YAML/JSON and other config files
 
-## File Structure Requirements
-
-- All `.py` files: English comments only
-- All `.js`/`.ts` files: English comments only
-- All `.md` files: English documentation only
-- All `.yaml`/`.yml` files: English comments only
-
-## Migration Checklist
-
-When refactoring existing code:
-1. ✅ Identify all non-English comments
-2. ✅ Translate comments to English while preserving meaning
-3. ✅ Update docstrings to English
-4. ✅ Ensure inline comments are in English
-5. ✅ Verify all TODO/FIXME comments are in English
-6. ✅ Update any related documentation
-
-## Validation
-
-Before committing changes:
-- No Chinese characters in comments
-- No Japanese characters in comments
-- No Korean characters in comments
+## Validation Checklist
 - All comments are in English
-- All docstrings are in English
-- All TODO/FIXME comments are in English
-
-## Examples of Refactoring
-
-### Before:
-```python
-# 解析输入URL
-def parse_url(url: str) -> str:
-    """解析并验证URL格式"""
-    # 检查URL是否有效
-    if not url.startswith('http'):
-        raise ValueError("无效的URL格式")
-    return url
-```
-
-### After:
-```python
-# Parse input URL
-def parse_url(url: str) -> str:
-    """Parse and validate URL format"""
-    # Check if URL is valid
-    if not url.startswith('http'):
-        raise ValueError("Invalid URL format")
-    return url
-```
-description:
-globs:
-alwaysApply: false
----
+- Docstrings use proper English grammar
+- No non-Latin characters in comments (except inside strings)
+- Comments are clear and provide value
+
+## Optional Automation
+- Pre-commit hook to detect non-English comments
+- IDE extensions for real-time detection
+- CI checks for compliance