Đóng góp

Cảm ơn bạn đã đóng góp cho Đại lý Hermes! Hướng dẫn này bao gồm việc thiết lập môi trường nhà phát triển của bạn, hiểu cơ sở mã và hợp nhất PR của bạn.

Ưu tiên đóng góp

Chúng tôi đánh giá cao những đóng góp theo thứ tự sau:

1. Sửa lỗi — treo máy, hoạt động không đúng, mất dữ liệu
2. Khả năng tương thích đa nền tảng — macOS, các bản phân phối Linux khác nhau, WSL2
3. Tăng cường bảo mật — chèn shell, chèn nhắc nhở, truyền tải đường dẫn
4. Hiệu suất và độ bền — logic thử lại, xử lý lỗi, xuống cấp nhẹ nhàng
5. Kỹ năng mới — những kỹ năng hữu ích rộng rãi (xem Creating Skills)
6. Công cụ mới — hiếm khi cần thiết; hầu hết các khả năng phải là kỹ năng
7. Tài liệu — sửa lỗi, làm rõ, ví dụ mới

Đường dẫn đóng góp chung

• Xây dựng công cụ tùy chỉnh/cục bộ mà không sửa đổi lõi Hermes? Bắt đầu với Build a Hermes Plugin
• Xây dựng một công cụ cốt lõi tích hợp mới cho chính Hermes? Bắt đầu với Adding Tools
• Xây dựng một kỹ năng mới? Bắt đầu với Creating Skills
• Xây dựng nhà cung cấp suy luận mới? Bắt đầu với Adding Providers

Thiết lập phát triển

Điều kiện tiên quyết

Yêu cầu	Ghi chú
Git	Với sự hỗ trợ

--recurse-submodules và tiện ích mở rộng git-lfs được cài đặt | | **Python 3.11+** | uv sẽ cài đặt nó nếu thiếu | | **uv** | Trình quản lý gói Python nhanh ([install](https://docs.astral.sh/uv/)) | | **Node.js 20+** | Tùy chọn - cần thiết cho các công cụ trình duyệt và cầu nối WhatsApp (khớp với các công cụ package.JSON ` gốc) |

Sao chép và cài đặt

git clone --recurse-submodules https://GitHub.com/NousResearch/Hermes-agent.git
cd Hermes-agent

# Create venv with Python 3.11
uv venv venv --Python 3.11
 export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras (messaging, cron, CLI menus, dev tools)
uv pip install -e ".[all,dev]"

# Optional: browser tools
npm install

`

### Cấu hình để phát triển

`bash
mkdir -p ~/.Hermes/\{cron,sessions,logs,memories,skills}
cp CLI-config.yaml.example ~/.Hermes/config.yaml
touch ~/.Hermes/.env

# Add at minimum an LLM provider key:
echo 'OpenRouter_API_KEY=sk-or-v1-your-key' >> ~/.Hermes/.env

`

### Chạy

`bash

# Symlink for global access
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/Hermes" ~/.local/bin/Hermes

# Verify
Hermes doctor
Hermes chat -q "Hello"

`

### Chạy thử nghiệm

``` bash
pytest tests/ -v

`

## Kiểu mã
- **PEP 8** với các ngoại lệ thực tế (không thực thi nghiêm ngặt độ dài dòng)

- **Nhận xét**: Chỉ khi giải thích mục đích không rõ ràng, sự đánh đổi hoặc các vấn đề về API
- **Xử lý lỗi**: Bắt các ngoại lệ cụ thể. Sử dụng 
`logger.warning()

/
`logger.error()
` với 
`exc_info=True
` để xử lý các lỗi không mong muốn
- **Đa nền tảng**: Không bao giờ sử dụng Unix (xem bên dưới)
- **Đường dẫn an toàn cho hồ sơ**: Không bao giờ mã hóa cứng 

~/.Hermes
` — sử dụng 
`get_Hermes_home()
` từ 
`Hermes_constants
` cho đường dẫn mã và 
`display_Hermes_home()
` cho thông báo hướng tới người dùng. Xem [AGENTS.md](https://GitHub.com/NousResearch/Hermes-agent/blob/main/AGENTS.md#profiles-multi-instance-support) để biết các quy tắc đầy đủ.

## Khả năng tương thích đa nền tảng

Hermes chính thức hỗ trợ **Linux, macOS, WSL2 và Windows gốc (phiên bản beta sớm - thông qua cài đặt PowerShell)**.  Windows gốc sử dụng Git Bash (từ [Git for Windows](https://git-scm.com/download/win)) cho các lệnh shell.  Một số tính năng yêu cầu nguyên gốc hạt nhân POSIX và được kiểm soát: ngăn terminal PTY được nhúng của bảng thông tin (tab 

/chat

) chỉ có WSL2. Đường dẫn Windows gốc là mới và di chuyển nhanh — nếu bạn đang phát triển Windows nặng, hãy mong đợi khắc phục và sửa các cạnh thô.

Khi đóng góp mã, hãy ghi nhớ các quy tắc sau:
- **Không thêm các tham chiếu 
`Signal.SIGKILL
` không được bảo vệ.** Nó không được xác định trên Windows.  Định tuyến thông qua 
`gateway.status.terminate_pid(pid, force=True)
` (bản gốc tập trung thực hiện 
`taskkill /T /F
` trên Windows và SIGKILL trên POSIX) hoặc quay lại bằng 
`getattr(Signal, "SIGKILL", Signal.SIGTERM)

.
- **Bắt 
`OSError
` cùng với 
`ProceSSLookupError
` trên đầu dò 
`os.kill(pid, 0)

.** Windows tăng 
`OSError
` (WinError 87, "tham số không chính xác") cho một PID đã biến mất thay vì 
`ProceSSLookupError

.
- **Không buộc terminal phải sử dụng ngữ nghĩa POSIX.** 
`os.setsid

, 
`os.killpg

, 
`os.getpgid

, 
`os.fork
` đều hoạt động trên Windows — kết nối chúng bằng 
`if sys.platform != "win32":
` hoặc 
`if os.name != "nt":

.
- **Mở tệp bằng 
`encoding="utf-8"
` rõ ràng.** Ngôn ngữ mặc định của Python trên Windows là ngôn ngữ hệ thống (thường là cp1252), ngôn ngữ này sẽ bị lỗi hoặc bị treo trên văn bản không phải tiếng Latinh.
- **Sử dụng 
`pathlib.Path
` / 
`os.path.join
` — không bao giờ kết nối thủ công với 

/

.** Điều này ít quan trọng hơn đối với các chuỗi mà hệ điều hành cung cấp cho chúng tôi và hơn thế nữa đối với các chuỗi chúng tôi xây dựng để chuyển giao cho các quy trình con.

Các mẫu chính:

### 1. 
`termios
` và 
`fcntl
` chỉ dành cho Unix

Luôn bắt cả 
`ImportError
` và 
`NotImplementedError

:

``` python
try:
    from simple_term_menu import TerminalMenu
    menu = TerminalMenu(options)
    idx = menu.show()
except (ImportError, NotImplementedError):

    # Fallback: numbered menu
    for i, opt in enumerate(options):
        print(f"  \{i+1}. \{opt}")
    idx = int(input("Choice: ")) - 1

`

### 2. Mã hóa tập tin

Một số môi trường có thể lưu tệp 

.env
` ở dạng mã hóa không phải UTF-8:

``` python
try:
    load_dotenv(env_path)
except UnicodeDecodeError:
    load_dotenv(env_path, encoding="latin-1")

`

### 3. Quản lý quy trình``os.setsid()

, 
`os.killpg()
` và cách xử lý tín hiệu khác nhau giữa các nền tảng:

`Python
 import platform
if platform.system() != "Windows":
    kwargs["preexec_fn"] = os.setsid

`

### 4. Dấu phân cách đường dẫn

Sử dụng 
`pathlib.Path
` thay vì nối chuỗi bằng 

/

.

## Cân nhắc về bảo mật

Hermes có quyền truy cập terminal. Vấn đề an ninh.### Các biện pháp bảo vệ hiện có

| Lớp | Thực hiện |
|-------|--------------|
| **Đường dẫn mật khẩu Sudo** | Sử dụng 
`shlex.quote()
` để ngăn chặn việc tiêm vỏ |
| **Phát hiện lệnh nguy hiểm** | Các mẫu Regex trong 
`tools/approval.py
` với luồng phê duyệt của người dùng |
| **Chèn nhắc nhở Cron** | Máy quét chặn các mẫu ghi đè lệnh |
| **Viết danh sách từ chối** | Các đường dẫn được bảo vệ được giải quyết thông qua 
`os.path.realpath()
` để ngăn chặn việc bỏ qua liên kết tượng trưng |
| **Người bảo vệ kỹ năng** | Máy quét bảo mật cho các kỹ năng được cài đặt trong trung tâm |
| **Hộp cát thực thi mã** | Tiến trình con chạy với các khóa API bị tước bỏ |
| **Làm cứng thùng chứa** | Docker: loại bỏ tất cả các khả năng, không tăng đặc quyền, giới hạn PID |

### Đóng góp mã nhạy cảm bảo mật
- Luôn sử dụng 
`shlex.quote()
` khi nội suy dữ liệu đầu vào của người dùng vào các lệnh shell

- Giải quyết các liên kết tượng trưng bằng 
`os.path.realpath()
` trước khi kiểm tra kiểm soát truy cập
- Không đăng nhập bí mật
- Nắm bắt các ngoại lệ rộng rãi xung quanh việc thực thi công cụ
- Kiểm tra trên tất cả các nền tảng nếu thay đổi của bạn chạm vào đường dẫn hoặc quy trình tệp

## Quá trình yêu cầu kéo

### Đặt tên chi nhánh

`
fix/description        # Bug fixes
feat/description       # New features
docs/description       # Documentation
test/description       # Tests
refactor/description   # Code restructuring

`

### Trước khi gửi
1. **Chạy thử nghiệm**: 
`pytest tests/ -v

2. **Kiểm tra thủ công**: Chạy 
`Hermes
` và thực hiện đường dẫn mã bạn đã thay đổi
3. **Kiểm tra tác động đa nền tảng**: Xem xét macOS và các bản phân phối Linux khác nhau
4. **Giữ PR tập trung**: Một thay đổi hợp lý cho mỗi PR

### Mô tả PR

Bao gồm:
- **Điều gì** đã thay đổi và **tại sao**
- **Cách kiểm tra** nó
- **Bạn đã thử nghiệm trên nền tảng nào**
- Tham khảo các vấn đề liên quan

### Tin nhắn cam kết

Chúng tôi sử dụng [Conventional Commits](https://www.conventionalcommits.org/):

`
<type(<scope): <description

`

| Loại | Sử dụng cho |
|------|----------|
| 
`fix
` | Sửa lỗi |
| 
`feat
` | Tính năng mới |
| 
`docs
` | Tài liệu |
| 
`test
` | Kiểm tra |
| 
`refactor
` | Tái cấu trúc mã |
| 
`chore
` | Xây dựng, CI, cập nhật phụ thuộc |

Phạm vi: 
`CLI

, 
`gateway

, 
`tools

, 
`skills

, 
`agent

, 
`install

, 
`WhatsApp

, 
`security
``Ví dụ:

`

fix(CLI): prevent crash in save_config_value when model is a string
feat(gateway): add WhatsApp multi-user session isolation
fix(security): prevent shell injection in sudo password piping

`

## Vấn đề báo cáo
- Sử dụng [GitHub Issues](https://GitHub.com/NousResearch/Hermes-agent/issues)
- Bao gồm: OS, phiên bản Python, phiên bản Hermes (
`Hermes version

), truy nguyên lỗi đầy đủ
- Bao gồm các bước để tái tạo
- Kiểm tra các vấn đề hiện có trước khi tạo bản sao
- Đối với các lỗ hổng bảo mật, vui lòng báo cáo riêng

## Cộng đồng
- **Discord**: [Discord.gg/NousResearch](https://Discord.gg/NousResearch)
- **Thảo luận GitHub**: Dành cho các đề xuất thiết kế và thảo luận về kiến trúc
- **Skills Hub**: Đăng tải các kỹ năng chuyên ngành và chia sẻ với cộng đồng

## Giấy phép

Bằng cách đóng góp, bạn đồng ý rằng những đóng góp của bạn sẽ được cấp phép theo [MIT License](https://GitHub.com/NousResearch/Hermes-agent/blob/main/LICENSE).