Merge branch 'main' into bc/voice_agent

Author: qbc2016

.gemini/styleguide.md

@@ -0,0 +1,96 @@
+# AgentScope Code Review Guide
+
+You should conduct a strict code review. Each requirement is labeled with priority:
+- **[MUST]** must be satisfied or PR will be rejected
+- **[SHOULD]** strongly recommended
+- **[MAY]** optional suggestion
+
+## 1. Code Quality
+
+### [MUST] Lazy Loading
+- Third-party library dependencies should be imported at the point of use, avoid centralized imports at file top
+  - The `Third-party library` refers to libraries not included in the `dependencies` variable in `pyproject.toml`.
+- For base class imports, use factory pattern:
+```python
+def get_xxx_cls() -> "MyClass":
+    from xxx import BaseClass
+    class MyClass(BaseClass): ...
+    return MyClass
+```
+
+### [SHOULD] Code Conciseness
+After understanding the code intent, check if it can be optimized:
+- Avoid unnecessary temporary variables
+- Merge duplicate code blocks
+- Prioritize reusing existing utility functions
+
+### [MUST] Encapsulation Standards
+- All Python files under `src/agentscope` should be named with `_` prefix, and exposure controlled through `__init__.py`
+- Classes and functions used internally by the framework that don't need to be exposed to users must be named with `_` prefix
+
+## 2. [MUST] Code Security
+- Prohibit hardcoding API keys/tokens/passwords
+- Use environment variables or configuration files for management
+- Check for debug information and temporary credentials
+- Check for injection attack risks (SQL/command/code injection, etc.)
+
+## 3. [MUST] Testing & Dependencies
+- New features must include unit tests
+- New dependencies need to be added to the corresponding section in `pyproject.toml`
+- Dependencies for non-core scenarios should not be added to the minimal dependency list
+
+## 4. Code Standards
+
+### [MUST] Comment Standards
+- **Use English**
+- All classes/methods must have complete docstrings, strictly following the template:
+```python
+def func(a: str, b: int | None = None) -> str:
+    """{description}
+
+    Args:
+        a (`str`):
+            The argument a
+        b (`int | None`, optional):
+            The argument b
+
+    Returns:
+        `str`:
+            The return str
+    """
+```
+- Use reStructuredText syntax for special content:
+```python
+class MyClass:
+    """xxx
+
+    `Example link <https://xxx>`_
+
+    .. note:: Example note
+
+    .. tip:: Example tip
+
+    .. important:: Example important info
+
+    .. code-block:: python
+
+        def hello_world():
+            print("Hello world!")
+
+    """
+```
+
+### [MUST] Pre-commit Checks
+- **Strict review**: In most cases, code should be modified rather than skipping checks
+- **File-level check skipping is prohibited**
+- Only allowed skip: agent class system prompt parameters (to avoid `\n` formatting issues)
+
+---
+
+## 5. Git Standards
+
+### [MUST] PR Title
+- Follow Conventional Commits
+- Must use prefixes: `feat/fix/docs/ci/refactor/test`, etc.
+- Format: `feat(scope): description`
+- Example: `feat(memory): add redis cache support`

.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-# AgentScope Instructions
+# AgentScope Code Review Guide
 
 You should conduct a strict code review. Each requirement is labeled with priority:
 - **[MUST]** must be satisfied or PR will be rejected
@@ -9,7 +9,8 @@ You should conduct a strict code review. Each requirement is labeled with priori
 
 ### [MUST] Lazy Loading
 - Third-party library dependencies should be imported at the point of use, avoid centralized imports at file top
-- Use factory pattern to import base classes:
+  - The `Third-party library` refers to libraries not included in the `dependencies` variable in `pyproject.toml`.
+- For base class imports, use factory pattern:
 ```python
 def get_xxx_cls() -> "MyClass":
     from xxx import BaseClass
@@ -35,7 +36,7 @@ After understanding the code intent, check if it can be optimized:
 
 ## 3. [MUST] Testing & Dependencies
 - New features must include unit tests
-- New dependencies need to be added to `pyproject.toml`
+- New dependencies need to be added to the corresponding section in `pyproject.toml`
 - Dependencies for non-core scenarios should not be added to the minimal dependency list
 
 ## 4. Code Standards

.github/scripts/update_news.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Script to automatically update NEWS section in README files.
+Reads the first 10 news items from docs/NEWS.md and updates README.md and
+README_zh.md.
+"""
+
+from pathlib import Path
+
+
+def read_news_items(news_file: Path, max_items: int = 10) -> list[str]:
+    """
+    Read news items from NEWS.md file.
+
+    Args:
+        news_file (`Path`):
+            Path to the NEWS.md file
+        max_items (`int`, optional):
+            Maximum number of items to read
+
+    Returns:
+        `list[str]`:
+            List of news items
+    """
+    with open(news_file, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Split by lines that start with "- **["
+    lines = content.strip().split("\n")
+    news_items = []
+
+    for line in lines:
+        if line.strip().startswith("- **["):
+            news_items.append(line)
+            if len(news_items) >= max_items:
+                break
+
+    return news_items
+
+
+def update_readme(
+    readme_file: Path,
+    news_items: list[str],
+) -> None:
+    """
+    Update the NEWS section in README file using HTML comment markers.
+
+    Args:
+        readme_file (`Path`):
+            Path to the README file
+        news_items (`list[str]`):
+            List of news items to insert
+    """
+    with open(readme_file, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Use HTML comment markers to identify the NEWS section
+    begin_marker = "<!-- BEGIN NEWS -->"
+    end_marker = "<!-- END NEWS -->"
+
+    if begin_marker not in content or end_marker not in content:
+        print(f"⚠️  NEWS markers not found in {readme_file.name}")
+        print(
+            f"    Please add '{begin_marker}' and '{end_marker}' to mark the "
+            f"NEWS section",
+        )
+        return
+
+    # Find positions of markers
+    begin_pos = content.find(begin_marker)
+    end_pos = content.find(end_marker)
+
+    if begin_pos == -1 or end_pos == -1 or begin_pos >= end_pos:
+        print(f"❌ Invalid NEWS markers in {readme_file.name}")
+        return
+
+    # Create new NEWS content
+    news_content = "\n".join(news_items)
+
+    # Replace content between markers
+    new_content = (
+        content[: begin_pos + len(begin_marker)]
+        + "\n"
+        + news_content
+        + "\n"
+        + content[end_pos:]
+    )
+
+    with open(readme_file, "w", encoding="utf-8") as f:
+        f.write(new_content)
+
+    print(f"✅ Updated {readme_file.name}")
+
+
+def main() -> None:
+    """Main function to update NEWS in README files."""
+    # Define paths
+    repo_root = Path(__file__).parent.parent.parent
+    news_file_en = repo_root / "docs" / "NEWS.md"
+    news_file_zh = repo_root / "docs" / "NEWS_zh.md"
+    readme_en = repo_root / "README.md"
+    readme_zh = repo_root / "README_zh.md"
+
+    # Update English README from NEWS.md
+    if news_file_en.exists():
+        print(f"📖 Reading news items from {news_file_en}")
+        news_items_en = read_news_items(news_file_en, max_items=10)
+        print(f"📰 Found {len(news_items_en)} English news items")
+
+        if news_items_en and readme_en.exists():
+            print(f"📝 Updating {readme_en.name}...")
+            update_readme(readme_en, news_items_en)
+        elif not news_items_en:
+            print("⚠️  No English news items found")
+        else:
+            print(f"⚠️  {readme_en} not found")
+    else:
+        print(f"❌ NEWS.md not found at {news_file_en}")
+
+    # Update Chinese README from NEWS_zh.md
+    if news_file_zh.exists() and news_file_zh.stat().st_size > 0:
+        print(f"📖 Reading news items from {news_file_zh}")
+        news_items_zh = read_news_items(news_file_zh, max_items=10)
+        print(f"📰 Found {len(news_items_zh)} Chinese news items")
+
+        if news_items_zh and readme_zh.exists():
+            print(f"📝 Updating {readme_zh.name}...")
+            update_readme(readme_zh, news_items_zh)
+        elif not news_items_zh:
+            print("⚠️  No Chinese news items found")
+        else:
+            print(f"⚠️  {readme_zh} not found")
+    else:
+        print(
+            f"⚠️  NEWS_zh.md not found or empty at {news_file_zh}, "
+            f"using English news for Chinese README",
+        )
+        # Fallback: use English news for Chinese README if NEWS_zh.md
+        # doesn't exist
+        if news_file_en.exists() and readme_zh.exists():
+            print(f"📖 Reading news items from {news_file_en} (fallback)")
+            news_items = read_news_items(news_file_en, max_items=10)
+            if news_items:
+                print(f"📝 Updating {readme_zh.name} with English news...")
+                update_readme(readme_zh, news_items)
+
+    print("✨ All done!")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/toc.yml

@@ -7,6 +7,11 @@ on:
     branches-ignore:
       - 'main'
 
+# Prevent concurrent runs that modify README files
+concurrency:
+  group: readme-updates-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   generateTOC:
     name: TOC Generator

.github/workflows/update_news.yml

@@ -0,0 +1,39 @@
+name: Update NEWS in README
+on:
+  push:
+    paths:
+      - 'docs/NEWS.md'
+      - 'docs/NEWS_zh.md'
+    branches-ignore:
+      - 'main'
+
+# Prevent concurrent runs that modify README files
+concurrency:
+  group: readme-updates-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  updateNews:
+    name: NEWS Updater
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.10'
+
+      - name: Update NEWS in README files
+        run: python .github/scripts/update_news.py
+
+      - name: Commit changes
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add README.md README_zh.md
+          git diff --staged --quiet || git commit -m "docs: auto-sync NEWS section to README files"
+          git push
+