@dtt_siye/atool 1.1.0

package/skills/ai-project-architecture/reference/structure-rules.md

@@ -0,0 +1,406 @@
+# LangGraph 1.0+ Architecture Structure Rules
+
+**Standard Version**: LangGraph 1.0+
+**Purpose**: Quick reference for ai-project-architecture skill
+
+---
+
+## Three-Tier Classification System
+
+Components are classified into three requirement tiers:
+
+### Tier 1: Mandatory Required (强制必需)
+
+Must exist in ALL AI projects.
+- **Severity if missing**: CRITICAL
+- **Enforcement**: Strict - blocks development if missing
+
+### Tier 2: Conditionally Required (条件必需)
+
+Required IF specific conditions are met.
+- **Severity if missing**: HIGH (when condition applies)
+- **Enforcement**: Context-aware - checked only when condition is met
+
+### Tier 3: Fully Optional (完全可选)
+
+Recommended but not required.
+- **Severity if missing**: LOW (informational only)
+- **Enforcement**: Informational - for guidance only
+
+---
+
+## Top-Level Directory Structure
+
+### Tier 1: Mandatory Required
+
+Must exist in ALL AI projects:
+
+- **`agents/`** - Agent modules (REQUIRED in all projects)
+- **`apps/`** - Application layer (REQUIRED in all projects)
+- **`core/`** - Core infrastructure (REQUIRED in all projects)
+- **`configs/`** - Configuration management (REQUIRED in all projects)
+
+### Tier 2: Conditionally Required
+
+Required only IF specific conditions are met:
+
+- **`models/`** - Shared ORM models (REQUIRED only if shared across modules)
+  - **Condition**: Project has multiple agents that share database models
+  - **Detection**: Check if `models/` contains `model.py` with shared table definitions
+
+### Tier 3: Optional (Recommended)
+
+Not required but recommended:
+
+- **`tests/`** - Test directory (unit, integration, fixtures)
+- **`bin/`** - Scripts directory
+- **`docs/`** - Documentation
+- **`logs/`** - Log files (data, not code)
+- **`temp/`** - Temporary files
+
+---
+
+## Agent Structure
+
+### Tier 1: Mandatory Components (Every Agent Must Have)
+
+Each agent in `agents/{agent_name}/` MUST contain:
+
+1. **`nodes/`** - LangGraph nodes (execution units) - **TIER 1 MANDATORY**
+   - Each node is a function
+   - Receives state object, returns state update
+   - Implements single responsibility
+
+2. **`services/`** - Business services - **TIER 1 MANDATORY**
+   - Non-LangGraph business logic
+   - Data extraction, task management, file operations
+   - Can be called by nodes or used independently
+
+3. **`models/`** - Data models - **TIER 1 MANDATORY (api.py)**
+   - `api.py`: Pydantic models for API request/response (REQUIRED - Tier 1)
+   - `state.py`: LangGraph state definition (optional - Tier 2)
+   - `orm.py`: ORM models (optional - Tier 2)
+
+4. **`tools/`** - LangChain tools - **TIER 1 MANDATORY**
+   - Functions callable by LLM
+   - Use `@tool` decorator
+   - Invoked by nodes through LLM
+
+### Tier 2: Conditionally Required Components
+
+Required IF specific conditions are met:
+
+- **`graph.py`** - LangGraph graph structure - **TIER 2 CONDITIONAL**
+  - **Condition**: Agent uses LangGraph (most agents will)
+  - **Detection**: Agent imports `StateGraph` or uses `from langgraph`
+  - **Required when**: Agent defines graph structure with nodes and edges
+
+- **`checkpoint.py`** - State persistence - **TIER 2 CONDITIONAL**
+  - **Condition**: Agent uses state persistence
+  - **Detection**: Agent uses `checkpoint` or `checkpointer`
+  - **Required when**: Agent needs to save/restore state (memory, Redis, DB)
+
+- **`views.py`** - FastAPI Router - **TIER 2 CONDITIONAL**
+  - **Condition**: Agent exposes HTTP API endpoints
+  - **Detection**: Agent uses `@router` or `APIRouter`
+  - **Required when**: Agent provides HTTP API interface
+
+- **`models/orm.py`** - ORM models - **TIER 2 CONDITIONAL**
+  - **Condition**: Agent has independent database tables
+  - **Detection**: Agent defines SQLAlchemy models
+  - **Required when**: Agent has database tables not shared with other agents
+
+- **`models/state.py`** - LangGraph state - **TIER 2 CONDITIONAL**
+  - **Condition**: Agent uses custom LangGraph state (not default TypedDict)
+  - **Detection**: Agent defines custom state class
+  - **Required when**: Agent uses complex state with reducers
+
+### Tier 3: Optional Components
+
+Recommended but not required:
+
+- **`constants.py`** - Agent-specific constants - **TIER 3 OPTIONAL**
+  - Only needed if agent has constants
+  - Not required for compliance
+
+---
+
+## Application Layer Structure (`apps/`)
+
+### Required Subdirectories
+
+- **`llms/`** - LLM management
+  - `models.py` - LLM model definitions
+  - `service.py` - LLM service
+  - `crud.py` - CRUD operations
+  - `register.py` - Model registration
+  - `extension.py` - Extension functionality
+
+- **`utils/`** - Utility functions
+  - `streaml.py` - Stream processing
+  - `custom_functions.py` - Custom functions
+  - `embedding_service.py` - Embedding service
+  - `reranker_service.py` - Reranker service
+  - `milvus_cli.py` - Milvus client
+  - `httpclient.py` - HTTP client
+  - `step_decorator.py` - Step decorator
+  - `common_utils.py` - Common utilities
+
+- **`logs/`** - Log management APIs
+  - `views.py` - Log query and management interfaces
+
+---
+
+## Core Infrastructure Structure (`core/`)
+
+### Core Files
+
+- `constants.py` - Constants definition
+- `exception.py` - Exception definitions
+- `response.py` - Response format
+- `deps.py` - Dependency injection
+- `encrypt.py` - Encryption tools
+- `lifespan.py` - Lifecycle management
+- `scheduler.py` - Task scheduler
+
+### Core Subdirectories
+
+- **`logging/`** - Logging system
+  - `redis_handler.py` - Redis log handler
+  - `redis_log_viewer.py` - Log viewer
+
+- **`middleware/`** - HTTP middleware (FastAPI)
+  - `setup.py` - Middleware setup
+  - `request_context.py` - Request context middleware
+  - `context_plugins.py` - Context plugins
+
+---
+
+## Configuration Structure (`configs/`)
+
+### Configuration Files
+
+- `app_config.py` - Main application configuration
+
+### Base Configuration (`configs/base/`)
+
+- `logger.py` - Logger configuration
+- `security.py` - Security configuration
+
+### Deployment Configuration (`configs/deploy/`)
+
+- `build.py` - Build configuration (Python class)
+- `runtime.py` - Runtime configuration (Python class)
+- `Dockerfile` - Docker build file
+- `docker-compose.yml` - Docker Compose configuration
+- `.dockerignore` - Docker ignore file
+
+### Integration Configuration (`configs/integrations/`)
+
+- `database.py` - Database configuration
+- `redis.py` - Redis configuration
+- `elasticsearch.py` - ES configuration
+- `llm.py` - LLM configuration
+- `embedding.py` - Embedding configuration
+- `reranker.py` - Reranker configuration
+- `libreoffice.py` - LibreOffice configuration
+
+**Storage Configuration (`configs/integrations/storage/`)**:
+
+- `local.py` - Local storage
+- `minio.py` - MinIO configuration
+- `aliyun_oss.py` - Aliyun OSS configuration
+
+**Vector DB Configuration (`configs/integrations/vdb/`)**:
+
+- `milvus.py` - Milvus configuration
+
+### Feature Configuration (`configs/feature/`)
+
+- `auth/` - Authentication configuration
+  - `jwt.py` - JWT configuration
+  - `apikey.py` - API Key configuration
+  - `oidc.py` - OIDC configuration
+
+### Extra Configuration (`configs/extra/`)
+
+- `email.py` - Email configuration
+- `java.py` - Java configuration
+- `tavily.py` - Tavily configuration
+
+---
+
+## Models Structure (`models/`)
+
+**Use Cases**: Only for ORM models shared across multiple agents/modules
+
+### Files
+
+- `base.py` - ORM base class
+- `conn.py` - Database connection
+- `fields.py` - Custom fields
+- `model.py` - Shared database table models
+
+**Note**: If ORM models are specific to a single agent, place them in `agents/{agent}/models/orm.py`
+
+---
+
+## Naming Conventions
+
+### File/Directory Naming
+
+- **Lowercase**: All names must be lowercase
+- **Kebab-case**: Use hyphens, not underscores (e.g., `my-agent/`, not `my_agent/`)
+- **No spaces**: No space characters in names
+- **No Chinese characters**: Use English only in filenames
+- **Descriptive**: Use domain-specific names, not generic names
+
+### Naming Anti-Patterns
+
+**AVOID**:
+- `utils/`, `helpers/`, `common/`, `shared/` (generic)
+- `misc.py`, `other.py` (unclear purpose)
+
+**USE**:
+- Domain-specific names: `OrderCalculator/`, `UserAuthenticator/`, `InvoiceGenerator/`
+- Bounded context naming patterns
+
+---
+
+## Architecture Principles
+
+### 1. Agent Design Principles
+
+- **Independence**: Each agent is an independent module
+- **Unified Structure**: All agents follow the same four-directory structure
+- **Responsibility Separation**: nodes, services, models, tools clearly separated
+- **Scalability**: Optional components support different needs
+
+### 2. State Design Principles (LangGraph)
+
+- **Minimize State**: Store only necessary persistent data
+- **Type Safety**: Use Pydantic models, not TypedDict
+- **Avoid Transient Values**: Don't store temporary calculations in state
+- **Use Reducers**: For collections, use reducer functions
+
+### 3. Node Design Principles
+
+- **Single Responsibility**: Each node does one thing
+- **Error Handling**: All nodes include error handling
+- **Logging**: Record key operations and state changes
+- **Idempotency**: Nodes should be idempotent (repeatable)
+
+### 4. Configuration Principles
+
+- **Environment Variables**: Use env vars to override defaults
+- **Type Validation**: Use Pydantic Settings for validation
+- **Layered Organization**: Organize by functional modules
+- **Deployment Separation**: Docker files in `configs/deploy/`
+
+---
+
+## Separation of Concerns
+
+### Agent Layer (`agents/`)
+
+- Purpose: Intelligent agent modules
+- Contains: LangGraph nodes, business services, data models, tools
+- Independent: Each agent is a complete business unit
+
+### Application Layer (`apps/`)
+
+- Purpose: Application-level services
+- Contains: LLM management, utilities, log APIs
+- Shared: Used by multiple agents
+
+### Core Layer (`core/`)
+
+- Purpose: Infrastructure and cross-cutting concerns
+- Contains: Exceptions, middleware, logging, scheduling
+- Foundation: Used by entire application
+
+### Configuration Layer (`configs/`)
+
+- Purpose: Configuration management
+- Contains: All configuration files
+- Centralized: Single source of configuration truth
+
+---
+
+## Special Considerations
+
+### Middleware vs Configuration
+
+- **`core/middleware/`**: True HTTP middleware (FastAPI middleware)
+- **`configs/integrations/`**: Third-party service configuration classes (not middleware)
+
+### Logs Directory Distinction
+
+- **`apps/logs/`**: Log management code (API interfaces)
+- **`logs/`** (root): Log file directory (data storage)
+
+### Model Placement
+
+- **Shared ORM models**: `models/` (root)
+- **Agent-specific models**: `agents/{agent}/models/`
+  - `api.py`: API models (always required)
+  - `state.py`: State models (optional)
+  - `orm.py`: ORM models (optional, only if agent has independent tables)
+
+---
+
+## Quality Standards
+
+### Code Quality
+
+- Proper error handling
+- Type hints (Python 3.6+)
+- Docstrings for public APIs
+- Logging for key operations
+
+### Testing
+
+- **Unit Tests**: Test nodes, tools, services in isolation
+- **Integration Tests**: Test complete agent flows
+- **End-to-End Tests**: Test user scenarios
+- **Performance Tests**: Test large-scale concurrency
+
+### Documentation
+
+- Architecture documentation
+- API documentation
+- Deployment documentation
+- Developer guides
+
+---
+
+## Deployment Best Practices
+
+### Docker Deployment
+
+- Docker files in `configs/deploy/`
+- Use environment variables for configuration
+- Multi-stage builds for optimization
+- Health checks for containers
+
+### Horizontal Scaling
+
+- Stateless design
+- External state storage (Redis)
+- Load balancing
+
+### Monitoring
+
+- Structured logging
+- Key metrics (node execution time, error rate)
+- Distributed tracing (OpenTelemetry)
+
+### Fault Tolerance
+
+- Checkpoint auto-recovery
+- Retry mechanisms
+- Graceful degradation
+
+---
+
+**Reference**: See PROJECT_STRUCTURE.md for complete architecture documentation and examples.

package/skills/ai-project-architecture/templates/compliance-report.md

@@ -0,0 +1,300 @@
+# AI Project Architecture Compliance Report
+
+**Project**: [Project Name]
+**Date**: [YYYY-MM-DD]
+**Analyzed By**: AI Project Architecture Skill
+**Reference Standard**: PROJECT_STRUCTURE.md (LangGraph 1.0+)
+
+---
+
+## Executive Summary
+
+**Overall Compliance Score**: [X]%
+
+- **CRITICAL Issues**: [X] (Blocks development)
+- **HIGH Issues**: [X] (Significant deviation)
+- **MEDIUM Issues**: [X] (Moderate concerns)
+- **LOW Issues**: [X] (Cosmetic issues)
+
+**Status**: [✓ COMPLIANT | ⚠ NEEDS ATTENTION | ✗ NON-COMPLIANT]
+
+---
+
+## Requirement Tier Classification
+
+This report classifies components into three requirement tiers:
+
+### Tier 1: Mandatory Required (强制必需)
+
+Must exist in ALL AI projects.
+- **Severity if missing**: CRITICAL (blocks development)
+
+**Components**:
+- Top-level: `agents/`, `apps/`, `core/`, `configs/`
+- Per-agent: `nodes/`, `services/`, `models/api.py`, `tools/`
+
+### Tier 2: Conditionally Required (条件必需)
+
+Required IF specific conditions are met.
+- **Severity if missing**: HIGH (when condition applies)
+
+**Components**:
+- `models/` root (only if shared ORM models across agents)
+- Agent's `models/orm.py` (only if agent has independent DB tables)
+- Agent's `models/state.py` (only if agent uses custom LangGraph state)
+- Agent's `graph.py` (only if agent uses LangGraph)
+- Agent's `checkpoint.py` (only if agent uses state persistence)
+- Agent's `views.py` (only if agent exposes HTTP endpoints)
+
+**Condition Detection**:
+- Analysis of code determines if Tier 2 components are required
+- Report documents WHY each Tier 2 component is (or isn't) required
+
+### Tier 3: Fully Optional (完全可选)
+
+Recommended but not required for compliance.
+- **Severity if missing**: LOW (informational only)
+
+**Components**:
+- `tests/`, `bin/`, `docs/`, `logs/`, `temp/`
+- Agent's `constants.py`
+
+---
+
+## Detailed Findings
+
+### 1. Top-Level Directory Structure
+
+#### Tier 1: Mandatory Directories
+
+| Directory | Tier | Status | Notes |
+|-----------|------|--------|-------|
+| `agents/` | Tier 1 (Mandatory) | [✓/✗] | [Present/Missing] - Agent modules |
+| `apps/` | Tier 1 (Mandatory) | [✓/✗] | [Present/Missing] - Application layer |
+| `core/` | Tier 1 (Mandatory) | [✓/✗] | [Present/Missing] - Core infrastructure |
+| `configs/` | Tier 1 (Mandatory) | [✓/✗] | [Present/Missing] - Configuration management |
+
+**Severity**: CRITICAL if missing
+
+#### Tier 2: Conditionally Required Directories
+
+| Directory | Tier | Condition | Status | Notes |
+|-----------|------|-----------|--------|-------|
+| `models/` | Tier 2 (Conditional) | Shared ORM models across agents | [✓/✗/N/A] | [Present/Missing/Not Required] |
+
+**Severity**: HIGH if missing AND condition applies
+
+#### Tier 3: Optional Directories
+
+| Directory | Tier | Status | Notes |
+|-----------|------|--------|-------|
+| `tests/` | Tier 3 (Optional) | [✓/✗] | [Present/Missing] - Test directory (recommended) |
+| `bin/` | Tier 3 (Optional) | [✓/✗] | [Present/Missing] - Scripts directory |
+| `docs/` | Tier 3 (Optional) | [✓/✗] | [Present/Missing] - Documentation (recommended) |
+
+**Severity**: LOW if missing (informational only)
+
+---
+
+### 2. Agent Structure Analysis
+
+#### Agents Found: [X]
+
+##### Agent: [agent_name]
+
+**Location**: `agents/[agent_name]/`
+
+**Condition Analysis**:
+- Uses LangGraph: [Yes/No] → `graph.py` [Required/Not Required]
+- Uses state persistence: [Yes/No] → `checkpoint.py` [Required/Not Required]
+- Exposes HTTP endpoints: [Yes/No] → `views.py` [Required/Not Required]
+- Has independent DB tables: [Yes/No] → `models/orm.py` [Required/Not Required]
+- Uses custom LangGraph state: [Yes/No] → `models/state.py` [Required/Not Required]
+
+#### Tier 1: Mandatory Components
+
+| Component | Tier | Status | Notes |
+|-----------|------|--------|-------|
+| `nodes/` | Tier 1 (Mandatory) | [✓/✗] | LangGraph nodes [Present/Missing] |
+| `services/` | Tier 1 (Mandatory) | [✓/✗] | Business services [Present/Missing] |
+| `models/api.py` | Tier 1 (Mandatory) | [✓/✗] | Pydantic API models [Present/Missing] |
+| `tools/` | Tier 1 (Mandatory) | [✓/✗] | LangChain tools [Present/Missing] |
+
+**Severity**: CRITICAL if missing
+
+#### Tier 2: Conditionally Required Components
+
+| Component | Tier | Condition | Required? | Status | Notes |
+|-----------|------|-----------|-----------|--------|-------|
+| `graph.py` | Tier 2 (Conditional) | Uses LangGraph | [Yes/No] | [✓/✗/N/A] | [Present/Missing/Not Required] |
+| `checkpoint.py` | Tier 2 (Conditional) | Uses state persistence | [Yes/No] | [✓/✗/N/A] | [Present/Missing/Not Required] |
+| `views.py` | Tier 2 (Conditional) | Exposes HTTP endpoints | [Yes/No] | [✓/✗/N/A] | [Present/Missing/Not Required] |
+| `models/orm.py` | Tier 2 (Conditional) | Has independent DB tables | [Yes/No] | [✓/✗/N/A] | [Present/Missing/Not Required] |
+| `models/state.py` | Tier 2 (Conditional) | Uses custom LangGraph state | [Yes/No] | [✓/✗/N/A] | [Present/Missing/Not Required] |
+
+**Severity**: HIGH if missing AND condition applies
+
+#### Tier 3: Optional Components
+
+| Component | Tier | Status | Notes |
+|-----------|------|--------|-------|
+| `constants.py` | Tier 3 (Optional) | [✓/✗] | Constants [Present/Missing] |
+
+**Severity**: LOW if missing (informational only)
+
+**Issues**:
+- [List any structural issues]
+
+**Overall Severity**: [CRITICAL if Tier 1 missing, HIGH if Tier 2 missing when required, LOW for Tier 3]
+
+---
+
+### 3. Configuration Structure
+
+#### Required Configuration Files
+
+| File/Directory | Status | Notes |
+|----------------|--------|-------|
+| `configs/app_config.py` | [✓/✗] | Main application config |
+| `configs/base/logger.py` | [✓/✗] | Logger configuration |
+| `configs/base/security.py` | [✓/✗] | Security configuration |
+| `configs/deploy/` | [✓/✗] | Deployment configuration directory |
+| `configs/deploy/build.py` | [✓/✗] | Build configuration |
+| `configs/deploy/runtime.py` | [✓/✗] | Runtime configuration |
+| `configs/deploy/Dockerfile` | [✓/✗] | Docker file |
+| `configs/deploy/docker-compose.yml` | [✓/✗] | Docker Compose |
+| `configs/integrations/` | [✓/✗] | Third-party service configs |
+
+**Severity**: [MEDIUM if core configs missing, LOW if deployment configs missing]
+
+---
+
+### 4. Naming Conventions
+
+#### Directory/File Naming
+
+| Pattern | Status | Examples |
+|---------|--------|----------|
+| Lowercase | [✓/✗] | All names in lowercase |
+| Kebab-case | [✓/✗] | Using hyphens, not underscores |
+| No spaces | [✓/✗] | No space characters |
+| No Chinese characters | [✓/✗] | English only in filenames |
+
+**Issues**:
+- [List any naming violations]
+
+**Severity**: [MEDIUM]
+
+---
+
+### 5. Separation of Concerns
+
+#### Architectural Layering
+
+| Layer | Status | Notes |
+|-------|--------|-------|
+| Agent layer (agents/) | [✓/✗] | Agent modules properly isolated |
+| Application layer (apps/) | [✓/✗] | App services correctly placed |
+| Core layer (core/) | [✓/✗] | Infrastructure separated |
+| Configuration (configs/) | [✓/✗] | Configs isolated from code |
+
+**Mixed Concerns Detected**:
+- [List any business logic in wrong layer]
+- [List any infrastructure concerns in business logic]
+
+**Severity**: [HIGH]
+
+---
+
+### 6. Import Structure
+
+#### Import Patterns
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Absolute imports | [✓/✗] | Using absolute imports from project root |
+| Relative imports | [✓/✗] | Relative imports for same-package references |
+| No circular dependencies | [✓/✗] | Import graph is acyclic |
+
+**Issues**:
+- [List any import issues]
+
+**Severity**: [MEDIUM if circular deps, LOW otherwise]
+
+---
+
+## Recommendations
+
+### Priority 1: CRITICAL (Must Fix)
+
+1. **[Issue description]**
+   - **Current State**: [Description]
+   - **Required State**: [Description]
+   - **Impact**: [Blocks development / causes failures]
+   - **Fix**: [Specific fix instructions]
+
+### Priority 2: HIGH (Should Fix)
+
+1. **[Issue description]**
+   - **Current State**: [Description]
+   - **Required State**: [Description]
+   - **Impact**: [Significant deviation from standard]
+   - **Fix**: [Specific fix instructions]
+
+### Priority 3: MEDIUM (Consider Fixing)
+
+1. **[Issue description]**
+   - **Current State**: [Description]
+   - **Required State**: [Description]
+   - **Impact**: [Moderate concern]
+   - **Fix**: [Specific fix instructions]
+
+### Priority 4: LOW (Nice to Have)
+
+1. **[Issue description]**
+   - **Current State**: [Description]
+   - **Required State**: [Description]
+   - **Impact**: [Cosmetic issue]
+   - **Fix**: [Specific fix instructions]
+
+---
+
+## Migration Suggestion
+
+Based on compliance analysis, recommended approach:
+
+- **Option A**: Full refactoring to standard structure [Recommended if score < 60%]
+- **Option B**: Partial refactoring addressing CRITICAL and HIGH issues [Recommended if score 60-80%]
+- **Option C**: Minor adjustments for MEDIUM and LOW issues [Recommended if score > 80%]
+
+**Estimated Effort**: [Low / Medium / High]
+
+**Next Steps**:
+1. Review recommendations
+2. Decide on migration approach
+3. Use ai-project-architecture skill Phase 2 to create detailed migration plan
+
+---
+
+## Appendix: Current Structure Tree
+
+```
+[Insert directory tree output here]
+```
+
+---
+
+## Report Metadata
+
+**Generated**: [YYYY-MM-DD HH:MM:SS]
+**Standard Version**: LangGraph 1.0+
+**Analyzer**: ai-project-architecture skill v1.0.0
+**Project Root**: [Path to project]
+
+---
+
+**Notes**:
+- This report is based on the architecture defined in PROJECT_STRUCTURE.md
+- All CRITICAL issues must be addressed before proceeding with development
+- HIGH issues should be addressed to ensure long-term maintainability
+- MEDIUM and LOW issues can be addressed incrementally