chore: initialize sandbox and overwrite remote content

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[Bug]:'
+labels: 'bug'
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. You code
+2. How to execute
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Error messages**
+Detailed error messages.
+
+**Environment (please complete the following information):**
+
+- AgentScope Version: [e.g. 1.0.0 via `print(agentscope.__version__)`]
+- Python Version: [e.g. 3.10]
+- OS: [e.g. macos, windows]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,13 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[Feature]: '
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**<u>AgentScope is an open-source project. To involve a broader community, we recommend asking your questions in English.</u>**
+
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## PR Title Format
+
+Please ensure your PR title follows the Conventional Commits format:
+- Format: `<type>(<scope>): <description>`
+- Example: `feat(memory): add redis cache support`
+- Allowed types: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `revert`
+- Description should start with a lowercase letter
+
+## AgentScope Version
+
+[The version of AgentScope you are working on, e.g. `import agentscope; print(agentscope.__version__)`]
+
+## Description
+
+[Please describe the background, purpose, changes made, and how to test this PR]
+
+## Checklist
+
+Please check the following items before code is ready to be reviewed.
+
+- [ ]  Code has been formatted with `pre-commit run --all-files` command
+- [ ]  All tests are passing
+- [ ]  Docstrings are in Google style
+- [ ]  Related documentation has been updated (e.g. links, examples, etc.)
+- [ ]  Code is ready for review

.github/copilot-instructions.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/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/pr-title-check.yml

@@ -0,0 +1,49 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  check-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR Title Format
+        uses: amannn/action-semantic-pull-request@v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Configure allowed types based on your requirements
+          types: |
+            feat
+            fix
+            docs
+            ci
+            refactor
+            test
+            chore
+            perf
+            style
+            build
+            revert
+          # Require a scope (the part in parentheses)
+          requireScope: false
+          # Scope pattern: only lowercase letters, numbers, hyphens, and underscores allowed
+          scopePattern: ^[a-z0-9_-]+$
+          scopePatternError: |
+            The scope (text in parentheses) must contain only lowercase letters, numbers, hyphens, and underscores.
+            Example: "feat(memory): add redis cache support"
+            Invalid: "feat(Memory): ..." or "feat(MEMORY): ..."
+          # Subject (description) must not be empty and must be lowercase
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject (description after colon) must start with a lowercase letter.
+            Example: "feat(memory): add redis cache support"
+          # Validate the entire PR title against the Conventional Commits spec
+          validateSingleCommit: false
+          # Ignore merge commits
+          ignoreLabels: |
+            ignore-semantic-pull-request
+

.github/workflows/pre-commit.yml

@@ -0,0 +1,38 @@
+name: Pre-commit
+
+on: [push, pull_request]
+
+jobs:
+  run:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: True
+      matrix:
+        os: [ubuntu-latest]
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: '3.10'
+    steps:
+    - uses: actions/checkout@master
+    - name: Setup Python
+      uses: actions/setup-python@master
+      with:
+        python-version: '3.10'
+    - name: Update setuptools
+      run: |
+        pip install setuptools==68.2.2 wheel==0.41.2
+    - name: Install AgentScope
+      run: |
+        pip install -q -e .[dev]
+    - name: Install pre-commit
+      run: |
+        pre-commit install
+    - name: Pre-commit starts
+      run: |
+        pre-commit run --all-files > pre-commit.log 2>&1 || true
+        cat pre-commit.log
+        if grep -q Failed pre-commit.log; then
+          echo -e "\e[41m  [**FAIL**] Please install pre-commit and format your code first. \e[0m"
+          exit 1
+        fi
+        echo -e "\e[46m  ********************************Passed******************************** \e[0m"

.github/workflows/publish-pypi.yml

@@ -0,0 +1,44 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Publish PyPi Package
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel build
+    - name: Build package
+      run: python -m build
+    - name: Test installation
+      run: |
+        pip install dist/*.whl
+        python -c "import agentscope; print(agentscope.__version__)"
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/sphinx_docs.yml

@@ -0,0 +1,95 @@
+name: Deploy Sphinx documentation to Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_en:
+    timeout-minutes: 20
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.10']
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: '3.10'
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Update setuptools
+        run: |
+          pip install setuptools==78.1.1 wheel==0.45.1
+      - name: Install Dependencies
+        run: |
+          pip install -q -e .[dev]
+      - name: Add execute permission to build.sh
+        run: |
+          chmod +x docs/tutorial/en/build.sh
+      - name: Build English Documentation
+        env:
+          DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+          GAODE_API_KEY: ${{ secrets.GAODE_API_KEY }}
+        run: |
+          cd docs/tutorial/en/
+          ./build.sh
+      - name: Deploy English Documentation
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/tutorial/en/build/html
+          cname: doc.agentscope.io
+          keep_files: true
+
+  build_zh:
+    needs: build_en
+    timeout-minutes: 20
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        python-version: [ '3.10' ]
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: '3.10'
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+      - name: Verify npm installation
+        run: npm --version
+      - name: Update setuptools
+        run: |
+          pip install setuptools==78.1.1 wheel==0.45.1
+      - name: Install Dependencies
+        run: |
+          pip install -q -e .[dev]
+      - name: Add execute permission to build.sh
+        run: |
+          chmod +x docs/tutorial/zh_CN/build.sh
+      - name: Build Chinese Documentation
+        env:
+          DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+          GAODE_API_KEY: ${{ secrets.GAODE_API_KEY }}
+        run: |
+          cd docs/tutorial/zh_CN/
+          ./build.sh
+      - name: Deploy Chinese Documentation
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/tutorial/zh_CN/build/html
+          destination_dir: zh_CN
+          cname: doc.agentscope.io
+          keep_files: true

.github/workflows/stale.yml

@@ -0,0 +1,35 @@
+# This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time.
+#
+# You can adjust the behavior by modifying this file.
+# For more information, see:
+# https://github.com/actions/stale
+name: Mark stale issues and pull requests
+
+on:
+  schedule:
+  - cron: '30 9 * * *'
+
+jobs:
+  stale:
+
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+    - uses: actions/stale@v5
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        stale-issue-message: 'This issue is marked as stale because there has been no activity for 60 days. Remove stale label or add new comments or this issue will be closed in 90 day.'
+        close-issue-message: 'Close this stale issue.'
+        stale-issue-label: 'stale-issue'
+        exempt-issue-labels: 'RoadMap,Roadmap'
+        days-before-stale: 60
+        days-before-close: 30
+
+        stale-pr-message: 'This PR is marked as stale because there has been no activity for 60 days. Remove stale label or add new comments or this PR will be closed in 30 days.'
+        close-pr-message: 'Close this stale PR.'
+        stale-pr-label: 'stale-pr'
+        days-before-pr-stale: 60
+        days-before-pr-close: 30

.github/workflows/toc.yml

@@ -0,0 +1,30 @@
+name: Generate TOC
+on:
+  push:
+    paths:
+      - 'README.md'
+      - 'README_ZH.md'
+    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
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: technote-space/toc-generator@v4
+        with:
+          TOC_TITLE: "## 📑 Table of Contents"
+          CREATE_PR: false
+          TARGET_PATHS: "README.md,README_ZH.md"
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TOC_TITLE_MAP: |
+            README.md: ## 📑 Table of Contents
+            README_ZH.md: ## 📑 目录

.github/workflows/unittest.yml

@@ -0,0 +1,33 @@
+name: Python Unittest Coverage
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    if: false == contains(github.event.pull_request.title, 'WIP')
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-15]
+        python-version: ['3.10', '3.11', '3.12']
+    env:
+      OS: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@master
+    - name: Setup Python ${{ matrix.python-version }}
+      uses: actions/setup-python@master
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Update setuptools
+      run: |
+        pip install setuptools==78.1.1 wheel==0.45.1
+    - name: Install Dev Dependencies
+      run: |
+        pip install -q -e .[dev]
+        pip install coverage pytest
+    - name: Run tests with coverage
+      run: |
+        coverage run -m pytest tests
+    - name: Generate coverage report
+      run: |
+        coverage report -m

.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
+