Tệp ngữ cảnh

Hermes Agent tự động phát hiện và tải các tệp ngữ cảnh định hình cách hoạt động của nó. Một số là dự án cục bộ và được phát hiện từ thư mục làm việc của bạn. SOUL.md hiện có tính toàn cầu đối với phiên bản Hermes và chỉ được tải từ HERMES_HOME.

Tệp ngữ cảnh được hỗ trợ

Tập tin	Mục đích	Khám phá
.hermes.md / HERMES.md	Hướng dẫn dự án (ưu tiên cao nhất)	Đi tới git root
ĐẠI LÝ.md	Hướng dẫn dự án, quy ước, kiến trúc	CWD khi khởi động + thư mục con dần dần
CLAUDE.md	Tệp ngữ cảnh Mã Claude (cũng được phát hiện)	CWD khi khởi động + thư mục con dần dần
SOUL.md	Tùy chỉnh tông màu và cá tính toàn cầu cho phiên bản Hermes này	`HERMES_HOME/SOUL.md` chỉ
.cursorrules	Quy ước mã hóa IDE con trỏ	Chỉ CWD
*.cursor/rules/.mdc**	Mô-đun quy tắc IDE con trỏ	Chỉ CWD

Hệ thống ưu tiên

Chỉ một loại ngữ cảnh dự án được tải mỗi phiên (trận đấu đầu tiên thắng): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules . SOUL.md luôn được tải độc lập dưới dạng danh tính tác nhân (khe số 1).

ĐẠI LÝ.md

AGENTS.md là tệp ngữ cảnh chính của dự án. Nó cho đại lý biết dự án của bạn được cấu trúc như thế nào, những quy ước nào cần tuân theo và bất kỳ hướng dẫn đặc biệt nào.

Khám phá thư mục con lũy tiến

Khi bắt đầu phiên, Hermes tải AGENTS.md từ thư mục làm việc của bạn vào dấu nhắc hệ thống. Khi tổng đài viên điều hướng đến các thư mục con trong phiên (thông qua read_file , terminal , search_files , v.v.), nó phát hiện dần dần các tệp ngữ cảnh trong các thư mục đó và đưa chúng vào cuộc trò chuyện tại thời điểm chúng trở nên phù hợp.

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

Cách tiếp cận này có hai ưu điểm so với việc tải mọi thứ khi khởi động:

Không có dấu nhắc hệ thống — gợi ý thư mục con chỉ xuất hiện khi cần
Bảo quản bộ nhớ đệm nhanh — lời nhắc hệ thống luôn ổn định qua các lượt

Mỗi thư mục con được kiểm tra nhiều nhất một lần mỗi phiên. Việc khám phá cũng đi lên các thư mục mẹ, vì vậy việc đọc backend/src/main.py sẽ khám phá backend/AGENTS.md ngay cả khi backend/src/ không có tệp ngữ cảnh riêng.

thông tin

Các tệp ngữ cảnh thư mục con trải qua cùng một quét bảo mật như các tệp ngữ cảnh khởi động. Các tập tin độc hại bị chặn.

Ví dụ ĐẠI LÝ.md

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

#

# Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

#

# Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

#

# Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md

SOUL.md kiểm soát tính cách, giọng điệu và phong cách giao tiếp của nhân viên. Xem trang Personality để biết đầy đủ chi tiết.

Vị trí:

~/.hermes/SOUL.md
hoặc $HERMES_HOME/SOUL.md nếu bạn chạy Hermes với thư mục chính tùy chỉnh

Chi tiết quan trọng:

Hermes tự động tạo một SOUL.md mặc định nếu nó chưa tồn tại
Hermes chỉ tải SOUL.md từ HERMES_HOME
Hermes không thăm dò thư mục làm việc của SOUL.md
Nếu tệp trống, không có gì từ SOUL.md được thêm vào lời nhắc
Nếu file có nội dung thì nội dung sẽ được chèn nguyên văn sau khi quét và cắt bớt

.cursorrules

Hermes tương thích với tệp .cursorrules và mô-đun quy tắc .cursor/rules/*.mdc của Cursor IDE. Nếu các tệp này tồn tại trong thư mục gốc dự án của bạn và không tìm thấy tệp ngữ cảnh có mức độ ưu tiên cao hơn ( .hermes.md , AGENTS.md hoặc CLAUDE.md ), chúng sẽ được tải dưới dạng ngữ cảnh dự án.

Điều này có nghĩa là các quy ước về Con trỏ hiện tại của bạn sẽ tự động được áp dụng khi sử dụng Hermes.

Cách tải tệp ngữ cảnh

Khi khởi động (lời nhắc hệ thống)

Các tệp ngữ cảnh được tải bởi build_context_files_prompt() trong agent/prompt_builder.py :

Quét thư mục làm việc — kiểm tra .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules (trận đầu tiên thắng)
Nội dung được đọc — mỗi tệp được đọc dưới dạng văn bản UTF-8
Quét bảo mật — nội dung được kiểm tra để tìm các kiểu chèn nhắc nhở
Cắt ngắn — các tệp vượt quá 20.000 ký tự sẽ bị cắt bớt phần đầu/đuôi (70% phần đầu, 20% phần đuôi, có điểm đánh dấu ở giữa)
Assembly — tất cả các phần được kết hợp dưới tiêu đề `

Project Context`

Tiêm — nội dung đã tập hợp được thêm vào dấu nhắc hệ thống

Trong phiên (khám phá lũy tiến)

SubdirectoryHintTracker trong agent/subdirectory_hints.py xem các đối số lệnh gọi công cụ cho đường dẫn tệp:

Trích xuất đường dẫn — sau mỗi lệnh gọi công cụ, đường dẫn tệp được trích xuất từ các đối số ( path , workdir , lệnh shell)
Đi bộ tổ tiên — thư mục và tối đa 5 thư mục mẹ được kiểm tra (dừng ở các thư mục đã truy cập)
Tải gợi ý — nếu tìm thấy AGENTS.md , CLAUDE.md hoặc .cursorrules thì nó đã được tải (khớp đầu tiên cho mỗi thư mục)
Quét bảo mật — quét nhắc nhở tương tự như các tệp khởi động
Cắt ngắn — tối đa 8.000 ký tự cho mỗi tệp
Tiêm — được thêm vào kết quả của công cụ để mô hình nhìn thấy nó trong ngữ cảnh một cách tự nhiên

Phần nhắc cuối cùng trông gần giống như:

# Project Context

The following project context files have been loaded and should be followed:

#

# AGENTS.md

[Your AGENTS.md content here]

#

# .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

Lưu ý rằng nội dung SOUL được chèn trực tiếp mà không cần thêm văn bản bao bọc.

Bảo mật: Bảo vệ tiêm nhắc nhở

Tất cả các tệp ngữ cảnh đều được quét để có thể đưa vào lời nhắc trước khi được đưa vào. Máy quét kiểm tra:

Lần ghi đè lệnh: "bỏ qua các hướng dẫn trước", "bỏ qua các quy tắc của bạn"
Mẫu lừa dối: "đừng nói cho người dùng biết"
Ghi đè lời nhắc hệ thống: "ghi đè lời nhắc hệ thống"
Nhận xét HTML ẩn: 
Phần tử div ẩn: <div style="display:none">
Xóa thông tin xác thực: curl ... $API_KEY
Quyền truy cập tệp bí mật: cat .env , cat credentials
Ký tự vô hình: khoảng trắng có độ rộng bằng 0, ghi đè hai chiều, nối từ

Nếu phát hiện bất kỳ mẫu mối đe dọa nào, tệp sẽ bị chặn:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

cảnh báo

Máy quét này bảo vệ chống lại các kiểu chèn thông thường, nhưng nó không thể thay thế cho việc xem xét các tệp ngữ cảnh trong kho lưu trữ được chia sẻ. Luôn xác thực nội dung AGENTS.md trong các dự án mà bạn không phải là tác giả.

Giới hạn kích thước

Giới hạn	Giá trị
Ký tự tối đa trên mỗi tệp	20.000 (~7.000 token)
Tỷ lệ cắt đầu	70%
Tỷ lệ cắt đuôi	20%
Điểm đánh dấu cắt ngắn	10% (hiển thị số lượng char và đề xuất sử dụng các công cụ tệp)

Khi một tệp vượt quá 20.000 ký tự, thông báo cắt bớt sẽ có nội dung:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

Mẹo để có tệp ngữ cảnh hiệu quả

Các phương pháp hay nhất cho AGENTS.md

Giữ cho nó ngắn gọn — duy trì ở mức dưới 20K ký tự; người đại diện đọc nó mỗi lượt
Cấu trúc có tiêu đề — sử dụng các phần ## cho cấu trúc, quy ước, ghi chú quan trọng
Bao gồm các ví dụ cụ thể — hiển thị các mẫu mã ưa thích, hình dạng API, quy ước đặt tên
Đề cập những điều KHÔNG nên làm — "không bao giờ sửa đổi trực tiếp các tệp di chuyển"
Liệt kê các đường dẫn và cổng chính — tác nhân sử dụng chúng cho các lệnh đầu cuối
Cập nhật khi dự án phát triển — bối cảnh cũ còn tệ hơn là không có bối cảnh

Ngữ cảnh mỗi thư mục con

Đối với monorepos, hãy đặt các hướng dẫn dành riêng cho thư mục con trong các tệp AGENTS.md lồng nhau:

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`

<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`