Đó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 nói chung (xem Kỹ năng sáng tạo)
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 một công cụ mới? Bắt đầu với Thêm công cụ
• Xây dựng một kỹ năng mới? Bắt đầu với Kỹ năng sáng tạo
• Xây dựng nhà cung cấp suy luận mới? Bắt đầu với Thêm nhà cung cấp

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
Python 3.11+	uv sẽ cài đặt nó nếu thiếu
uv	Trình quản lý gói Python nhanh (cài đặt)
Node.js 18+	Tùy chọn — cần thiết cho các công cụ trình duyệt và cầu nối WhatsApp

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]"
uv pip install -e "./tinker-atropos"

# Optional: browser tools
npm install

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

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

# 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

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 để biết 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 tin nhắn hướng tới người dùng. Xem AGENTS.md để biết đầy đủ các quy tắc.

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

Hermes chính thức hỗ trợ Linux, macOS và WSL2. Windows gốc không được hỗ trợ, nhưng cơ sở mã bao gồm một số mẫu mã hóa phòng thủ để tránh sự cố nghiêm trọng trong các trường hợp khó khăn. Các quy tắc chính:

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

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

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:

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:

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 thiết bị đầu cuối. 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 shell
Phát hiện lệnh nguy hiểm	Mẫu biểu thức chính quy 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 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 test/ -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 Cam kết thông thường:

<type>(<scope>): <description>

Loại	Sử dụng cho
sửa	Sửa lỗi
chiến công	Tính năng mới
tài liệu	Tài liệu
kiểm tra	Kiểm tra
tái cấu trúc	Tái cấu trúc mã
việc vặt	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 Sự cố GitHub
• 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

• Bất hòa: 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 việc đóng góp, bạn đồng ý rằng những đóng góp của bạn sẽ được cấp phép theo Giấy phép MIT.