Chuyển tới nội dung chính

Tích hợp trình soạn thảo ACP

Hermes Agent có thể chạy như một máy chủ ACP, cho phép các biên tập viên tương thích với ACP nói chuyện với Hermes qua stdio và kết xuất:

  • tin nhắn trò chuyện
  • hoạt động của công cụ
  • khác biệt về tập tin
  • lệnh đầu cuối
  • lời nhắc phê duyệt
  • luồng suy nghĩ / phản hồi

ACP rất phù hợp khi bạn muốn Hermes hoạt động giống như một tác nhân mã hóa gốc biên tập viên thay vì CLI hoặc bot nhắn tin độc lập.

Những gì Hermes phơi bày trong chế độ ACP​

Hermes chạy với bộ công cụ Hermes-ACP được tuyển chọn được thiết kế cho quy trình làm việc của biên tập viên. Nó bao gồm:

  • công cụ tập tin: `read_file

, `write_file

, `patch

, `search_files

  • công cụ đầu cuối: `terminal

, `process

  • công cụ web/trình duyệt
  • bộ nhớ, việc cần làm, tìm kiếm phiên
  • kỹ năng
  • exec_code và delegate_task
  • tầm nhìn

Nó cố tình loại trừ những thứ không phù hợp với UX của trình soạn thảo thông thường, chẳng hạn như gửi tin nhắn và quản lý cronjob.

Cài đặt​

Cài đặt Hermes bình thường, sau đó thêm ACP bổ sung:

pip install -e '.[ACP]'

`
``Thao tác này sẽ cài đặt phần phụ thuộc 
`agent-CLIent-protocol
` và cho phép:
- 
`Hermes ACP

`
- 
`Hermes-ACP

- 
`Python -m ACP_adapter
``Đối với các lượt cài đặt đăng ký Zed, Zed khởi chạy Hermes thông qua mục Đăng ký ACP chính thức. Mục đó sử dụng bản phân phối 
`uvx
` chạy:

``` bash
uvx --from 'Hermes-agent[ACP]==<version' Hermes-ACP

`
``Đảm bảo 
`uv
` có sẵn trên 
`PATH
` trước khi sử dụng đường dẫn cài đặt sổ đăng ký.

## Khởi chạy máy chủ ACP

Bất kỳ thao tác nào sau đây đều khởi động Hermes ở chế độ ACP:

`bash
Hermes ACP

`

`
`bash
Hermes-ACP

`

`
`bash
Python -m ACP_adapter

`
``Hermes đăng nhập vào stderr để thiết bị xuất chuẩn vẫn được dành riêng cho lưu lượng JSON-RPC ACP.

Đối với kiểm tra không tương tác:

`bash
Hermes ACP --version
Hermes ACP --check

`

### Công cụ trình duyệt (tùy chọn)

Các công cụ trình duyệt (
`browser_navigate

, 
`browser_CLIck

, v.v.) phụ thuộc vào
Gói npm 
`agent-browser
` và Chrome, không phải là một phần của Python
bánh xe. Cài đặt chúng với:

`bash
Hermes ACP --setup-browser           # interactive (prompts before ~400 MB download)
Hermes ACP --setup-browser --yes     # accept the download non-interactively

`
``Đây là lệnh độc lập. Luồng xác thực terminal của cơ quan đăng ký Zed (
`Hermes ACP --setup

) cũng cung cấp phần khởi động của trình duyệt dưới dạng câu hỏi tiếp theo sau khi chọn mô hình, vì vậy hầu hết người dùng không bao giờ cần chạy trực tiếp 

`
--setup-browser

.

Nó làm gì:
- Cài đặt Node.js 22 LTS vào 

~/.Hermes/node/
` nếu thiếu
- 
`npm install -g agent-browser @askjo/camofox-browser
` vào tiền tố đó (không cần sudo - 
`npm
` của 

--prefix
` trỏ vào Nút do Hermes quản lý mà người dùng có thể ghi)
- Cài đặt Playwright Chrome hoặc sử dụng hệ thống Chrome/Chromium được phát hiện khi có sẵn

Bootstrap bình thường — chạy lại nó rất nhanh và bỏ qua công việc đã hoàn thành.

## Thiết lập trình chỉnh sửa

### Mã VS

Cài đặt tiện ích mở rộng [ACP CLIent](https://marketplace.visualstudio.com/items?itemName=formulahendry.ACP-CLIent).

Để kết nối:
1. Mở bảng ACP CLIent từ Thanh hoạt động.
2. Chọn **Đại lý Hermes** từ danh sách đại lý tích hợp.
3. Kết nối và bắt đầu trò chuyện.

Nếu bạn muốn xác định Hermes theo cách thủ công, hãy thêm nó thông qua cài đặt Mã VS trong 
`ACP.agents

:

``` json
{
  "ACP.agents": {
    "Hermes Agent": {
      "command": "Hermes",
      "args": ["ACP"]
    }
  }
}

`
``###Zed

Zed v0.221.x và mới hơn cài đặt các tác nhân bên ngoài thông qua Cơ quan đăng ký ACP chính thức.
1. Mở Bảng Đại lý.

2. Nhấp vào **Thêm tác nhân** hoặc chạy lệnh 
`Zed: ACP registry

.
3. Tìm kiếm **Đại lý Hermes**.
4. Cài đặt nó và bắt đầu một chuỗi tác nhân bên ngoài Hermes mới.

Điều kiện tiên quyết:
- Trước tiên, hãy định cấu hình thông tin xác thực của nhà cung cấp Hermes bằng 
`Hermes model
` hoặc đặt chúng trong 

~/.Hermes/.env
` / 

~/.Hermes/config.yaml

.
- Cài đặt 
`uv
` để launcher đăng ký có thể chạy 
`uvx --from 'Hermes-agent[ACP]==<version' Hermes-ACP

.

Để phát triển cục bộ trước khi có mục đăng ký, hãy sử dụng máy chủ tác nhân tùy chỉnh trong cài đặt Zed:

``` json
{
  "agent_servers": {
    "Hermes-agent": {
      "type": "custom",
      "command": "Hermes",
      "args": ["ACP"]
    }
  }
}

`

### JetBrains

Sử dụng plugin tương thích với ACP và trỏ nó vào:

`text
/path/to/Hermes-agent/ACP_registry

`

## Bản kê khai sổ đăng ký

Bản sao nguồn của siêu dữ liệu ACP Register chính thức của Hermes tồn tại tại:

`text
ACP_registry/agent.JSON
ACP_registry/icon.svg

`
``PR đăng ký ngược dòng sao chép các tệp đó vào thư mục 
`Hermes-agent/
` cấp cao nhất trong 
`agentCLIentprotocol/registry

.

Mục đăng ký sử dụng bản phân phối 
`uvx
` trỏ trực tiếp vào bản phát hành 
`Hermes-agent
` PyPI:

`text
uvx --from 'Hermes-agent[ACP]==<version' Hermes-ACP

`
``CI đăng ký xác minh rằng phiên bản được ghim tồn tại trên PyPI, do đó, mã pin 
`version
` và uvx 
`package
` của tệp kê khai phải luôn khớp với 
`pyproject.TOML

. 
`scripts/release.py
` tự động giữ chúng ở chế độ khóa.

## Cấu hình và thông tin xác thực

Chế độ ACP sử dụng cấu hình Hermes giống như CLI:
- 

~/.Hermes/.env

`
- 

~/.Hermes/config.yaml

- 

~/.Hermes/skills/

- 

~/.Hermes/state.db

Độ phân giải của nhà cung cấp sử dụng trình phân giải thời gian chạy thông thường của Hermes, do đó ACP kế thừa thông tin xác thực và nhà cung cấp được định cấu hình hiện tại. Hermes cũng quảng cáo phương thức xác thực terminal (

--setup

) cho các khách hàng đăng ký lần đầu; điều này sẽ mở ra thiết lập mô hình/nhà cung cấp tương tác của Hermes.

## Hành vi của phiên

Các phiên ACP được theo dõi bởi trình quản lý phiên trong bộ nhớ của bộ điều hợp ACP trong khi máy chủ đang chạy.

Mỗi phiên lưu trữ:
- ID phiên
- thư mục làm việc
- mô hình đã chọn
- lịch sử cuộc trò chuyện hiện tại
- hủy bỏ sự kiện``AIAgent
` cơ bản vẫn sử dụng đường dẫn ghi nhật ký/lưu trữ thông thường của Hermes, nhưng ACP 
`list/load/resume/fork
` nằm trong phạm vi quy trình máy chủ ACP hiện đang chạy.

## Hành vi của thư mục làm việc

Các phiên ACP liên kết cwd của trình soạn thảo với ID tác vụ Hermes để các công cụ tệp và terminal chạy liên quan đến không gian làm việc của trình soạn thảo chứ không phải cwd quy trình máy chủ.

## Phê duyệt

Các lệnh đầu cuối nguy hiểm có thể được chuyển trở lại trình chỉnh sửa dưới dạng lời nhắc phê duyệt. Các tùy chọn phê duyệt ACP đơn giản hơn luồng CLI:
- cho phép một lần
- cho phép luôn
- phủ nhận

Khi hết thời gian chờ hoặc có lỗi, cầu phê duyệt sẽ từ chối yêu cầu.

### Tự động phê duyệt chỉnh sửa trong phạm vi phiên

ACP đưa ra cấp độ thứ ba giữa *cho phép một lần* và *luôn luôn cho phép*: **Cho phép phiên**. Việc chọn nó từ lời nhắc cấp phép của người chỉnh sửa sẽ chỉ ghi lại phê duyệt trong phiên ACP hiện tại — mọi lệnh khớp tiếp theo trong phiên đó sẽ được thực hiện mà không cần nhắc, nhưng phiên ACP mới (hoặc khởi động lại trình chỉnh sửa) sẽ đặt lại phương tiện chặn và nhắc lại lần đầu tiên.

| Tùy chọn | Nhãn biên tập | Phạm vi | Kiên trì trong quá trình khởi động lại |
|---|---|---|---|
| 
`allow_once
` | Cho phép một lần | Cuộc gọi một công cụ này | Không |
| 
`allow_session
` | Cho phép phiên | Tất cả các cuộc gọi phù hợp trong phiên ACP này | Không — bị xóa khi phiên kết thúc |
| 
`allow_always
` | Cho phép luôn | Tất cả các phiên trong tương lai | Có (được ghi vào danh sách cho phép vĩnh viễn của Hermes) |
| 
`deny
` | Từ chối | Cuộc gọi một công cụ này | Không |

allow_session
` là chế độ mặc định phù hợp cho quy trình làm việc của người chỉnh sửa, trong đó bạn tin tưởng một tổng đài viên trong suốt thời gian thực hiện nhiệm vụ nhưng không muốn cấp mục nhập danh sách cho phép tồn tại lâu dài. Sự đánh đổi về an toàn rất đơn giản: phạm vi càng rộng thì người biên tập sẽ càng ít làm phiền bạn và tác nhân có hành vi sai trái (hoặc tiêm nhắc) có thể gây ra nhiều thiệt hại hơn trước khi bạn nhận ra. Bắt đầu với 
`allow_once
` cho các lệnh lạ; thăng cấp lên 
`allow_session
` sau khi bạn thấy đại lý chạy đúng mẫu tương tự một vài lần; dự trữ 
`allow_always
` cho các lệnh thực sự bình thường mà bạn tin tưởng mãi mãi (ví dụ: 
`git status

).

Cầu ACP ánh xạ các tùy chọn này vào ngữ nghĩa phê duyệt nội bộ của Hermes — 
`allow_always
` ghi mục nhập danh sách cho phép vĩnh viễn giống như cách CLI thực hiện, trong khi 
`allow_session
` chỉ ảnh hưởng đến bộ nhớ đệm phê duyệt trong quá trình cho phiên ACP hiện tại.

## Khắc phục sự cố

### Tác nhân ACP không xuất hiện trong trình chỉnh sửa

Kiểm tra:
- Trong Zed, mở ACP Register bằng 
`Zed: ACP registry
` và tìm kiếm **Hermes Agent**.
- Để phát triển thủ công/cục bộ, hãy xác minh lệnh 
`agent_servers
` tùy chỉnh trỏ đến 
`Hermes ACP

.
- Hermes đã được cài đặt và trên PATH của bạn.
- Đã cài đặt thêm ACP (
`pip install -e '.[ACP]'

).
- 
`uv
` được cài đặt nếu khởi chạy từ mục đăng ký Zed chính thức.

### ACP khởi động nhưng lập tức báo lỗi

Hãy thử những kiểm tra sau:

``` bash
Hermes ACP --version
Hermes ACP --check
Hermes doctor
Hermes status

`

### Thiếu thông tin xác thực

Chế độ ACP sử dụng thiết lập nhà cung cấp hiện có của Hermes. Định cấu hình thông tin xác thực với:

`bash
Hermes model

`
``hoặc bằng cách chỉnh sửa 

~/.Hermes/.env

. Các máy khách đăng ký cũng có thể kích hoạt luồng xác thực terminal của Hermes, chạy cùng một thiết lập mô hình/nhà cung cấp tương tác.

### Trình khởi chạy đăng ký Zed không thể tìm thấy uv

Cài đặt 
`uv
` từ tài liệu cài đặt uv chính thức, sau đó thử lại chuỗi Tác nhân Hermes từ Zed.

## Xem thêm
- [ACP Internals](../../developer-guide/ACP-internals.md)

- [Provider Runtime Resolution](../../developer-guide/provider-runtime.md)
- [Tools Runtime](../../developer-guide/tools-runtime.md)