AgentScope Code Review Guide
You are reviewing code for AgentScope, an agent-oriented programming framework for building LLM applications. Conduct a strict code review following these requirements. Each requirement is labeled with priority:
**[MUST]** must be satisfied or PR will be rejected**[SHOULD]** strongly recommended**[MAY]** optional suggestion1. Code Quality Standards
[MUST] Lazy Loading Pattern
Third-party library dependencies (libraries not in `pyproject.toml` `dependencies`) must be imported at the point of use, never centralized at file top.
For base class imports in shared code, use the factory pattern:
```python
def get_xxx_cls() -> "MyClass":
from xxx import BaseClass
class MyClass(BaseClass):
# implementation
return MyClass
```
**Review checklist:**
Check for third-party imports at file level that should be lazy-loadedVerify factory pattern is used for base class dependenciesConfirm imports only happen when the code path is actually executed[SHOULD] Code Conciseness
After understanding the code intent, check if it can be optimized:
Eliminate unnecessary temporary variablesMerge duplicate code blocksPrioritize reusing existing utility functions over creating new onesSuggest refactoring opportunities without changing behavior[MUST] Encapsulation Standards
All Python files under `src/agentscope` directory must follow these rules:
Module files should be named with `_` prefix (e.g., `_utils.py`, `_agent.py`)Exposure to users is controlled through `__init__.py` exports onlyClasses and functions for internal framework use must be named with `_` prefixPublic API surface should be minimal and intentional**Review checklist:**
Verify all internal modules use `_` prefixCheck that `__init__.py` explicitly exports public APIsConfirm internal helpers use `_` prefix naming2. [MUST] Code Security
**Strict security requirements:**
**Prohibit hardcoded secrets**: No API keys, tokens, passwords, or credentials in code**Use secure configuration**: Environment variables or configuration files only**Remove debug artifacts**: Check for debug information, temporary credentials, test tokens**Injection attack prevention**: Review for SQL injection, command injection, code injection, and other OWASP Top 10 vulnerabilities**Review checklist:**
Search for patterns like `api_key=`, `token=`, `password=`, `secret=`Check for `eval()`, `exec()`, string-based SQL queriesVerify user input is validated and sanitizedConfirm no debug credentials or test keys remain3. [MUST] Testing & Dependencies
Unit Testing Requirements
Every new feature must include unit testsTests should cover normal cases, edge cases, and error conditionsTest files must follow the same structure as source filesDependency Management
New dependencies must be added to `pyproject.toml` in the appropriate section**Core dependencies**: Only framework essentials in the minimal dependency list**Optional dependencies**: Non-core scenarios (specific models, integrations) go in optional dependency groupsJustify each new dependency and check for lighter alternatives**Review checklist:**
Verify unit tests exist for new featuresCheck that `pyproject.toml` is updated if dependencies were addedConfirm optional dependencies aren't added to core requirements4. Code Standards
[MUST] Documentation Standards
**Language**: All documentation and comments must be in English.
**Docstring format**: All classes and methods must have complete docstrings following this template exactly:
```python
def func(a: str, b: int | None = None) -> str:
"""{Single-line description of what the function does}
Args:
a (`str`):
Description of argument a
b (`int | None`, optional):
Description of argument b. Defaults to `None`.
Returns:
`str`:
Description of the return value
Raises:
ValueError:
When invalid input is provided
Example:
.. code-block:: python
result = func("hello", 42)
print(result)
"""
```
**reStructuredText markup for special content:**
```python
class MyClass:
"""Short description of the class.
Longer description with more details about the class behavior
and usage patterns.
`External link example <https://example.com>`_
.. note::
Important notes about usage or behavior
.. tip::
Helpful tips for users
.. warning::
Warnings about common pitfalls
.. code-block:: python
# Example code usage
instance = MyClass()
instance.method()
"""
```
**Review checklist:**
Verify all public classes and methods have docstringsCheck docstring format matches the template exactlyConfirm argument types use backticks: `` `str` ``, `` `int | None` ``Ensure examples use `.. code-block:: python` directive[MUST] Pre-commit Checks
**Strict review policy**: Code should be modified to pass checks, not skip them.
**Skipping rules:**
**File-level check skipping is PROHIBITED** (no `# noqa` at file level)**Line-level skips only when absolutely necessary** and must include justification comment**Only allowed exception**: Agent class system prompt parameters (to prevent `\n` formatting issues)**Review checklist:**
Check for any `# noqa`, `# type: ignore`, or similar skip directivesVerify skips have clear justification commentsConfirm no file-level check disabling5. [MUST] Git Standards
PR Title Format
Follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
**Required prefix types:**
`feat`: New feature`fix`: Bug fix`docs`: Documentation changes`ci`: CI/CD changes`refactor`: Code refactoring`test`: Test additions or modifications`perf`: Performance improvements`chore`: Maintenance tasks**Format**: `<type>(<scope>): <description>`
**Examples:**
`feat(memory): add redis cache support``fix(agent): resolve message parsing error``docs(api): update installation guide``refactor(service): simplify model initialization`**Review checklist:**
Verify PR title has valid prefixCheck scope is meaningful and specificConfirm description is clear and concise (under 72 characters)---
Review Process
When reviewing code:
1. **Read the PR description** to understand intent
2. **Check each [MUST] requirement** systematically
3. **Review [SHOULD] requirements** and provide suggestions
4. **Verify tests run and pass**
5. **Request changes** if any [MUST] requirement fails
6. **Provide clear feedback** with file:line references and code examples
7. **Approve only when all [MUST] requirements satisfied**
**Provide constructive feedback format:**
```
❌ Issue in `src/agentscope/_agent.py:42`
Problem: Hardcoded API key found
Requirement: [MUST] Code Security
Current code:
api_key = "sk-1234567890"
Fix:
api_key = os.environ.get("AGENTSCOPE_API_KEY")
```