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

Nội bộ ACP

Bộ điều hợp ACP bao bọc AIAgent đồng bộ của Hermes trong máy chủ stdio JSON-RPC không đồng bộ.

Các tập tin triển khai chính:

  • acp_adapter/entry.py
  • acp_adapter/server.py
  • acp_adapter/session.py
  • acp_adapter/events.py
  • acp_adapter/permissions.py
  • acp_adapter/tools.py
  • acp_adapter/auth.py
  • acp_registry/agent.json

Luồng khởi động

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent)

Stdout được dành riêng cho việc vận chuyển JSON-RPC ACP. Nhật ký mà con người có thể đọc được sẽ chuyển tới stderr.

Các thành phần chính

HermesACPAgent​

acp_adapter/server.py triển khai giao thức tác nhân ACP.

Trách nhiệm:

  • khởi tạo/xác thực
  • các phương thức phiên mới/tải/tiếp tục/ngã ba/danh sách/hủy
  • thực hiện nhanh chóng
  • chuyển đổi mô hình phiên
  • đồng bộ hóa các cuộc gọi lại AIAgent vào các thông báo không đồng bộ ACP

SessionManager​

acp_adapter/session.py theo dõi các phiên ACP trực tiếp.

Mỗi phiên lưu trữ:

  • session_id
  • agent
  • cwd
  • model
  • history
  • cancel_event

Trình quản lý an toàn theo luồng và hỗ trợ:

  • tạo
  • lấy
  • loại bỏ
  • cái nĩa
  • danh sách
  • dọn dẹp
  • cập nhật cwd

Cầu sự kiện​

acp_adapter/events.py chuyển đổi lệnh gọi lại AIAgent thành sự kiện ACP session_update.

Cuộc gọi lại cầu nối:

  • tool_progress_callback
  • thinking_callback
  • step_callback
  • message_callback

Bởi vì AIAgent chạy trong một luồng công nhân trong khi I/O ACP tồn tại trên vòng lặp sự kiện chính, nên bridge sử dụng:

asyncio.run_coroutine_threadsafe(...)

Cầu xin phép​

acp_adapter/permissions.py điều chỉnh lời nhắc phê duyệt terminal nguy hiểm thành yêu cầu cấp phép ACP.

Lập bản đồ:

  • allow_once -> Hermes once
  • allow_always -> Hermes always
  • tùy chọn từ chối -> Hermes deny

Theo mặc định, thời gian chờ và lỗi cầu nối bị từ chối.

Công cụ trợ giúp kết xuất​

acp_adapter/tools.py ánh xạ các công cụ Hermes với các loại công cụ ACP và xây dựng nội dung dành cho biên tập viên.

Ví dụ:

  • patch / write_file -> khác biệt về tệp
  • terminal -> văn bản lệnh shell
  • read_file / search_files -> xem trước văn bản
  • kết quả lớn -> khối văn bản được cắt ngắn để đảm bảo an toàn cho giao diện người dùng

Vòng đời phiên

new_session(cwd)
  -> create SessionState
  -> create AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
  -> bind task_id/session_id to cwd override

prompt(..., session_id)
  -> extract text from ACP content blocks
  -> reset cancel event
  -> install callbacks + approval bridge
  -> run AIAgent in ThreadPoolExecutor
  -> update session history
  -> emit final agent message chunk

Hủy bỏ​

cancel(session_id) :

  • đặt sự kiện hủy phiên
  • gọi agent.interrupt() khi sẵn sàng
  • khiến phản hồi nhanh chóng trả về stop_reason="cancelled"

Ngã ba​

fork_session() sao chép sâu lịch sử tin nhắn vào một phiên trực tiếp mới, duy trì trạng thái hội thoại trong khi cung cấp ID phiên và cwd riêng cho nhánh phân nhánh.

Hành vi của nhà cung cấp/xác thực

ACP không triển khai cửa hàng xác thực của riêng mình.

Thay vào đó, nó sử dụng lại trình phân giải thời gian chạy của Hermes:

  • acp_adapter/auth.py
  • hermes_cli/runtime_provider.py

Vì vậy, ACP quảng cáo và sử dụng thông tin xác thực/nhà cung cấp Hermes hiện được định cấu hình.

Liên kết thư mục làm việc

Các phiên ACP mang theo một trình soạn thảo cwd.

Trình quản lý phiên liên kết cwd đó với ID phiên ACP thông qua ghi đè tệp/terminal trong phạm vi tác vụ, do đó, các công cụ tệp và terminal hoạt động tương ứng với không gian làm việc của trình soạn thảo.

Lệnh gọi công cụ trùng tên

Cầu sự kiện theo dõi ID công cụ FIFO cho mỗi tên công cụ, không chỉ một ID cho mỗi tên. Điều này rất quan trọng đối với:

  • các cuộc gọi cùng tên song song
  • lặp lại các cuộc gọi cùng tên trong một bước

Nếu không có hàng đợi FIFO, các sự kiện hoàn thành sẽ đính kèm lệnh gọi công cụ sai.

Khôi phục cuộc gọi lại phê duyệt

ACP tạm thời cài đặt lệnh gọi lại phê duyệt trên công cụ đầu cuối trong quá trình thực thi nhanh chóng, sau đó khôi phục lệnh gọi lại trước đó. Điều này tránh việc cài đặt mãi mãi các trình xử lý phê duyệt dành riêng cho phiên ACP trên toàn cầu.

Hạn chế hiện tại

  • Các phiên ACP mang tính quy trình cục bộ theo quan điểm của máy chủ ACP
  • các khối nhắc nhở không phải văn bản hiện bị bỏ qua để trích xuất văn bản yêu cầu
  • UX dành riêng cho người chỉnh sửa thay đổi tùy theo việc triển khai ứng dụng khách ACP

Các tập tin liên quan

  • tests/acp/ — Bộ kiểm tra ACP
  • toolsets.py — định nghĩa bộ công cụ hermes-acp
  • hermes_cli/main.py — hermes acp Lệnh phụ CLI
  • pyproject.toml — [acp] phụ thuộc tùy chọn + tập lệnh hermes-acp