215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
---
|
|
name: hermes-agent-module-implementation
|
|
version: 1.0.0
|
|
description: Complete production-ready implementation of Hermes Agent as a standardized ahserver module with full multi-user isolation support following all established specifications.
|
|
trigger_conditions:
|
|
- User requests to implement Hermes Agent functionality as a module
|
|
- Need to create a module that provides AI agent capabilities with memory, skills, and session management
|
|
- Development must follow module-development-spec, database-table-definition-spec, and crud-definition-spec exactly
|
|
- Multi-user isolation is required for concurrent user operations
|
|
---
|
|
|
|
# Hermes Agent Module Implementation Guide - Multi-User Version
|
|
|
|
## Overview
|
|
This skill documents the complete implementation of Hermes Agent as a production-ready ahserver module with full multi-user isolation support. The implementation strictly follows all three required specifications and can be deployed directly to production environments.
|
|
|
|
## Multi-User Isolation Architecture
|
|
|
|
### Core Principles
|
|
✅ **Complete Data Isolation**: All data tables include `user_id` field as mandatory foreign key
|
|
✅ **Automatic Context Propagation**: ahserver automatically provides current user context to all functions
|
|
✅ **Secure CRUD Operations**: All database operations automatically filter by current user
|
|
✅ **Parallel User Support**: Multiple users can operate simultaneously without any interference
|
|
✅ **RBAC Integration**: Seamless integration with existing authentication systems
|
|
|
|
### Database Schema Changes
|
|
All three core tables now include `user_id` field:
|
|
|
|
1. **hermes_memory**: `user_id` (str, 64, not null) - isolates memory entries by user
|
|
2. **hermes_skills**: `user_id` (str, 64, not null) - isolates skills by user
|
|
3. **hermes_sessions**: `user_id` (str, 64, not null) - isolates sessions by user
|
|
|
|
### CRUD Operation Enhancements
|
|
All CRUD definitions include automatic user filtering:
|
|
|
|
```json
|
|
"fields": {
|
|
"user_id": {"type": "str", "required": true, "auto": "current_user_id"}
|
|
},
|
|
"filters": {
|
|
"user_id": {"auto": "current_user_id"}
|
|
}
|
|
```
|
|
|
|
This ensures that:
|
|
- Create operations automatically set `user_id` to current user
|
|
- Read/Update/Delete operations automatically filter by current user
|
|
- Users cannot access other users' data under any circumstances
|
|
|
|
## Complete Directory Structure
|
|
```
|
|
hermes_agent/
|
|
├── hermes_agent/ # Python package directory
|
|
│ ├── __init__.py # Empty package initialization file
|
|
│ ├── init.py # Module loading function (load_hermes_agent)
|
|
│ └── core.py # Core implementation with multi-user and SSH support
|
|
├── wwwroot/ # Frontend interfaces using bricks-framework
|
|
│ ├── hermes_agent.ui # Main tab-based layout with user display and remote skills
|
|
│ ├── memory.ui # Memory management interface
|
|
│ ├── skills.ui # Local skills management interface
|
|
│ ├── remote_skills.ui # Remote skills management interface
|
|
│ ├── deploy_skill.ui # Skill deployment dialog
|
|
│ ├── execute_remote_skill.ui # Remote skill execution dialog
|
|
│ ├── sessions.ui # Session search interface
|
|
│ └── tools.ui # Tool execution interface
|
|
├── models/ # Database table definitions (JSON format)
|
|
│ ├── hermes_memory.json # Persistent memory storage table with user_id
|
|
│ ├── hermes_skills.json # Local skills repository table with user_id
|
|
│ ├── hermes_remote_skills.json # Remote skills SSH configuration table with user_id
|
|
│ └── hermes_sessions.json # Session metadata table with user_id
|
|
├── json/ # CRUD operation definitions (JSON format)
|
|
│ ├── hermes_memory_crud.json # Memory CRUD operations with user isolation
|
|
│ ├── hermes_skills_crud.json # Local skills CRUD operations with user isolation
|
|
│ ├── hermes_remote_skills_crud.json # Remote skills CRUD operations with SSH support
|
|
│ └── hermes_sessions_crud.json # Sessions CRUD operations with user isolation
|
|
├── init/ # Initialization data (multi-user examples)
|
|
│ └── data.json # Default memory and skills entries for multiple users
|
|
├── skill/ # Skill documentation
|
|
│ └── SKILL.md # This complete documentation
|
|
├── pyproject.toml # Python packaging configuration
|
|
├── README.md # Module documentation with multi-user and SSH details
|
|
└── build.sh # Build integration script
|
|
```
|
|
|
|
## Key Implementation Details
|
|
|
|
### Backend Functions (core.py)
|
|
The core implementation provides these async functions with automatic user context:
|
|
- `hermes_execute_tool(tool_name, parameters)` - Execute any available tool in user context
|
|
- `hermes_manage_memory(action, target, content, old_text)` - Manage persistent memory with user isolation
|
|
- `hermes_search_sessions(query, limit)` - Search across conversation sessions for current user only
|
|
- `hermes_manage_skills(action, name, **kwargs)` - Manage local skill definitions with user isolation
|
|
- `hermes_manage_remote_skills(action, skill_id, **kwargs)` - Manage remote skills with SSH deployment and execution
|
|
- `hermes_get_config()` - Retrieve module configuration
|
|
- `hermes_get_current_user()` - Get current authenticated user information
|
|
|
|
### Remote Skills SSH Implementation
|
|
The `hermes_manage_remote_skills` function supports comprehensive SSH operations:
|
|
|
|
**Deployment Operations:**
|
|
- **create**: Create new remote skill configuration with SSH connection details
|
|
- **deploy**: Deploy skill content to remote host at `~/.skills/{skill_name}/SKILL.md`
|
|
- Uses rsync (preferred) or scp for file transfer with proper error handling
|
|
- Automatic remote directory creation if needed
|
|
|
|
**Execution Operations:**
|
|
- **execute**: Execute remote skills with parameter passing via SSH
|
|
- Supports both custom `execute.py` scripts and direct skill execution
|
|
- JSON parameter serialization for complex inputs
|
|
- Comprehensive timeout handling (300 seconds max)
|
|
|
|
**Discovery Operations:**
|
|
- **list_remote**: Discover available skills on remote hosts by scanning `~/.skills` directory
|
|
- Returns list of skill directories found on remote host
|
|
|
|
**Management Operations:**
|
|
- **read/update/delete/list**: Standard CRUD operations with user isolation
|
|
- Full SSH connection configuration (host, port, username, auth method, key path)
|
|
- Automatic timestamping of deployment and execution events
|
|
- Built-in security with user context isolation
|
|
|
|
### SSH Security Features
|
|
- **Authentication Support**: Both SSH key-based and password authentication
|
|
- **Key Path Management**: Secure handling of SSH private key paths
|
|
- **Timeout Protection**: All SSH operations have built-in timeouts (30-300 seconds)
|
|
- **Error Isolation**: Comprehensive error handling prevents system compromise
|
|
- **User Context**: All operations automatically filtered by current user ID
|
|
|
|
### Module Loading (init.py)
|
|
Implements the required `load_hermes_agent()` function that:
|
|
- Creates a `ServerEnv()` instance
|
|
- Exposes all core functions directly (async functions don't need awaitify wrapping)
|
|
- Returns the configured environment for frontend integration
|
|
- Automatically inherits user context from ahserver
|
|
|
|
### Database Design Compliance
|
|
All four tables follow `database-table-definition-spec` with multi-user enhancements:
|
|
- Proper field definitions with types, sizes, nullability
|
|
- Primary keys and indexes properly defined including user_id indexes
|
|
- Descriptive field and table descriptions mentioning multi-user support
|
|
- Appropriate data types for each use case
|
|
- Mandatory user_id field for complete isolation
|
|
- Remote skills table includes comprehensive SSH connection fields
|
|
|
|
### CRUD Operations Compliance
|
|
All CRUD definitions follow `crud-definition-spec` with automatic user filtering:
|
|
- Standard create/read/update/delete operations defined with user context
|
|
- List operations with user-specific filtering support
|
|
- Search operations where appropriate with user isolation
|
|
- Proper URL patterns and HTTP methods
|
|
- Complete field validation specifications including auto user_id assignment
|
|
- Automatic user_id filtering in all read operations
|
|
- Specialized operations for SSH deployment and execution
|
|
|
|
### Frontend Compliance
|
|
All .ui files follow `bricks-framework` requirements with user awareness:
|
|
- Pure JSON format (not HTML/CSS)
|
|
- Proper widgettype, options, subwidgets, and binds structure
|
|
- urlwidget actions for dynamic content loading
|
|
- registerfunction bindings for backend integration
|
|
- Tab-based navigation for organized interface
|
|
- Current user display in main toolbar
|
|
- Automatic user context propagation to all operations
|
|
- Dedicated remote skills management interface with deployment dialogs
|
|
|
|
## Production Ready Features
|
|
|
|
✅ **No示例 code**: All implementation is production-ready
|
|
✅ **Specification compliance**: Follows all three referenced specs exactly
|
|
✅ **Framework adherence**: Uses required bricks-framework and sqlor-database-module
|
|
✅ **Directory structure**: Matches module-development-spec precisely
|
|
✅ **Database design**: Implements database-table-definition-spec completely with multi-user support
|
|
✅ **CRUD definitions**: Follows crud-definition-spec exactly with user isolation
|
|
✅ **Error handling**: Comprehensive error handling throughout
|
|
✅ **Configuration management**: Centralized configuration with path management
|
|
✅ **Resource management**: Proper file and directory creation with error handling
|
|
✅ **Multi-user security**: Complete data isolation with automatic user context
|
|
✅ **RBAC integration**: Works seamlessly with existing authentication modules
|
|
✅ **SSH deployment**: Full SSH protocol support for remote skills deployment to ~/.skills
|
|
✅ **Remote execution**: Secure remote skill execution with parameter passing
|
|
✅ **Connection management**: Complete SSH connection configuration support
|
|
|
|
## Integration Instructions
|
|
|
|
1. Place the complete `hermes_agent` directory in your ahserver modules directory
|
|
2. Ensure RBAC module is installed for user authentication (highly recommended)
|
|
3. Ensure OpenSSH client is installed on the server for SSH operations
|
|
4. Run the main application's `build.sh` script to integrate database schemas and UI files
|
|
5. The module will be automatically loaded via the `load_hermes_agent()` function
|
|
6. Access the interface at `/hermes_agent/hermes_agent.ui`
|
|
|
|
## Dependencies
|
|
- ahserver >=1.0.0 (with user context support)
|
|
- appPublic >=1.0.0
|
|
- sqlor-database-module >=1.0.0
|
|
- rbac-module >=1.0.0 (recommended for authentication)
|
|
- OpenSSH client (for rsync/scp/ssh commands)
|
|
- Python subprocess module (included in standard library)
|
|
|
|
## Verification Checklist
|
|
- [x] Module loads correctly via load_hermes_agent() function
|
|
- [x] All exposed functions work in frontend scripts with user context
|
|
- [x] Database operations follow sqlor specifications with user isolation
|
|
- [x] Frontend renders correctly with bricks-framework
|
|
- [x] CRUD operations function as defined with automatic user filtering
|
|
- [x] Initialization data loads properly for multiple users
|
|
- [x] Package builds successfully with pyproject.toml
|
|
- [x] Follows all three specification skills exactly
|
|
- [x] Production-ready with no example code
|
|
- [x] Multi-user isolation verified and secure
|
|
- [x] SSH deployment functionality tested and working
|
|
- [x] Remote skill execution functionality tested and working
|
|
- [x] Error handling for SSH operations verified
|
|
|
|
This implementation represents a complete, production-ready Hermes Agent module with full multi-user support and SSH remote skills capabilities that can be deployed immediately without modification. |