From 7c2083d227d80e71baa98c425c0f6498c08745ca Mon Sep 17 00:00:00 2001 From: YueGuobin Date: Mon, 9 Mar 2026 21:46:58 +0800 Subject: [PATCH] feat: update .gitignore to track project context and development docs - Add exception for .claude/development.md to allow tracking development documentation - Comment out PROJECT_CONTEXT.md exclusion to enable version control of project context file - Create PROJECT_CONTEXT.md with comprehensive project overview for AI assistant support - Document project structure, AI copilot data flow, SSE event types, and code standards - Provide flake8 static analysis guidelines and common error fixes --- .gitignore | 3 +- PROJECT_CONTEXT.md | 370 +++++++++++++++++++++++++++++++++ gns3server/utils/encryption.py | 34 ++- 3 files changed, 397 insertions(+), 10 deletions(-) create mode 100644 PROJECT_CONTEXT.md diff --git a/.gitignore b/.gitignore index 95ff1616a..b6b848006 100644 --- a/.gitignore +++ b/.gitignore @@ -70,4 +70,5 @@ venv # Claude Code settings (may contain API keys) .claude/ -PROJECT_CONTEXT.md +!.claude/development.md # Exception: allow development docs +# PROJECT_CONTEXT.md # Commented out: allow tracking project context diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md new file mode 100644 index 000000000..b09064e9a --- /dev/null +++ b/PROJECT_CONTEXT.md @@ -0,0 +1,370 @@ +# GNS3 Server - Project Context for Claude Code + +> This document provides project context information for the Claude Code AI assistant to work more efficiently. + +--- + +## Project Overview + +**Project Name**: GNS3 Server +**Description**: Network simulation server supporting the GNS3 network virtualization platform +**Primary Language**: Python +**Current Branch**: `feature/ai-copilot-bridge` +**Main Branch**: `master` + +--- + +## Project Structure + +``` +gns3server/ +├── agent/ # AI Copilot related modules +│ └── gns3_copilot/ # GNS3-Copilot AI Assistant +│ ├── agent/ # LangGraph Agent implementation +│ ├── tools_v2/ # Tool collection (device config, display commands, etc.) +│ ├── utils/ # Utility functions and helper modules +│ ├── gns3_client/ # GNS3 API client +│ ├── prompts/ # AI prompt templates +│ ├── agent_service.py # Agent service layer +│ └── project_agent_manager.py # Project Agent manager +│ +├── api/ # API routes +│ └── routes/controller/ # Controller API +│ └── chat.py # AI Chat API endpoint +│ +├── controller/ # Core controller +│ ├── project.py # Project management +│ └── ... +│ +├── schemas/ # Pydantic data models +│ └── controller/ +│ └── chat.py # Chat API Schema +│ +├── db/ # Database module +│ └── tasks.py # Database tasks +│ +└── docs/ # Documentation + └── gns3-copilot/ # AI Copilot documentation +``` + +--- + +## Key Module Descriptions + +### 1. AI Copilot Data Flow + +``` +Tool Layer → Agent Layer → Service Layer → API Layer → Frontend +``` + +**Tool Output Format**: All tools return `dict` or `list[dict]`, automatically serialized to JSON in the Service layer + +**Key Files**: +- `agent/gns3_copilot/tools_v2/*.py` - Tool implementations +- `agent/gns3_copilot/agent_service.py:460-473` - Event conversion logic +- `agent/gns3_copilot/utils/parse_tool_content.py` - Tool result parsing + +### 2. SSE Event Types + +| Type | Description | +|------|-------------| +| `content` | AI text streaming output | +| `tool_call` | LLM tool invocation (progressive parameters) | +| `tool_start` | Tool execution started | +| `tool_end` | Tool execution completed (output as JSON) | +| `error` | Error message | +| `done` | Stream ended | + +### 3. Important Tools + +| Tool Name | File | Function | +|-----------|------|----------| +| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | Read-only diagnostic commands | +| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | Configuration commands | +| `VPCSMultiCommands` | `vpcs_tools_telnetlib3.py` | VPCS virtual PC commands | +| `GNS3TemplateTool` | `gns3_get_node_temp.py` | Get GNS3 templates | +| `GNS3CreateNodeTool` | `gns3_create_node.py` | Create nodes | + +--- + +## Code Standards + +### Static Code Analysis (Flake8) + +The project uses **flake8** for static code analysis. You must run checks before committing code. + +#### Running Flake8 + +```bash +# Activate virtual environment +source venv/bin/activate + +# Check a single file +flake8 path/to/file.py + +# Check the entire project +flake8 gns3server/ + +# Check a specific directory +flake8 gns3server/utils/ +``` + +#### Common Flake8 Error Codes + +| Code | Description | Example | +|------|-------------|---------| +| **F401** | Module imported but unused | `import os` never used | +| **F841** | Local variable assigned but never used | `x = 1` not used later | +| **F824** | `global` declaration never assigned | `global _bar` never assigned in scope | +| **E501** | Line too long (>79 characters) | Single line exceeds 79 characters | + +#### Fix Examples + +```python +# F401: Remove unused imports +# Bad +import os # Never used +# Good: Delete this line + +# F841: Mark as intentionally unused +# Bad +def foo(): + x = 1 # Never used + +# Good: Use or mark as intentionally unused +def foo(): + x = 1 + _ = x # Mark as intentionally unused + +# F824: Remove unnecessary global declaration +# Bad +def foo(): + global _fernet # Never assigned in this scope + +# Good: Remove global statement (if only reading) +def foo(): + # Just read the global variable, no global declaration needed + pass + +# E501: Break long lines +# Bad +raise RuntimeError("Encryption not initialized. Call init_encryption() first.") + +# Good +raise RuntimeError( + "Encryption not initialized. Call init_encryption() first." +) +``` + +#### Ruff (Alternative) + +[Ruff](https://docs.astral.sh/ruff/) is a faster Python linter that can replace flake8, isort, black, and more. + +```bash +# Install +pip install ruff + +# Usage +ruff check gns3server/ # Check code +ruff check --fix gns3server/ # Auto-fix +ruff format gns3server/ # Format code +``` + +### Python Code Style + +```python +# 1. Type annotations +def process_data(input_data: dict[str, Any]) -> list[dict[str, Any]]: + pass + +# 2. Error handling +try: + result = tool.invoke(args) +except Exception as e: + logger.error("Tool failed: %s", e, exc_info=True) + return {"error": str(e)} + +# 3. JSON serialization +if not isinstance(output, str): + output = json.dumps(output, ensure_ascii=False, indent=2) +``` + +### Import Order + +```python +# 1. Standard library +import asyncio +import json +import logging + +# 2. Third-party libraries +from langchain.tools import BaseTool +from pydantic import BaseModel + +# 3. Local modules +from gns3server.agent.gns3_copilot.agent import agent_builder +from gns3server.controller import Controller +``` + +### Copyright Header + +```python +# SPDX-License-Identifier: GPL-3.0-or-later +# +# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3 +# +# Copyright (C) 2025 Yue Guobin (岳国宾) +# Author: Yue Guobin (岳国宾) +# +# Project Home: https://github.com/yueguobin/gns3-copilot +``` + +--- + +## Git Commit Standards + +### Commit Message Format + +``` +(): + + + +