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

{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Gỡ lỗi lệnh Hermes TUI

Gỡ lỗi các lệnh gạch chéo Hermes TUI: Python, cổng, Ink UI.

Siêu dữ liệu kỹ năng​

NguồnĐi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/software-development/debugging-Hermes-TUI-commands ` | | Phiên bản |

1.0.0 ` | | Tác giả | Đại lý Hermes | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

debugging

, `Hermes-agent

, `TUI

, `slash-commands

, `TypeScript

,

` |
| Kỹ năng liên quan | [XPROTECTX18XPROTECTX](/docs/user-guide/skills/bundled/software-development/software-development-Python-debugpy), [XPROTECTX19XPROTECTX](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [XPROTECTX20XPROTECTX](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) |

## Tham khảo: đầy đủ SKILL.md

:::info
Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

:::

# Gỡ lỗi các lệnh gạch chéo Hermes TUI

## Tổng quan

Các lệnh gạch chéo của Hermes trải dài ba lớp - sổ đăng ký lệnh Python, cầu nối JSON-RPC của TUI_gateway và giao diện người dùng Ink/TypeScript. Khi một lệnh hoạt động sai (thiếu trong tính năng tự động hoàn thành, hoạt động trong CLI nhưng không hoạt động trong TUI, cấu hình vẫn tồn tại nhưng giao diện người dùng không cập nhật), lỗi hầu như luôn là một lớp không đồng bộ với lớp khác.

Sử dụng kỹ năng này khi bạn gặp sự cố với lệnh gạch chéo trong Hermes TUI, đặc biệt khi các lệnh không hiển thị trong chế độ tự động hoàn thành, không hoạt động bình thường trong TUI hoặc cần được thêm/cập nhật.

## Khi nào nên sử dụng
- Lệnh gạch chéo tồn tại trong một phần của codebase nhưng không hoạt động đầy đủ
- Cần thêm lệnh vào cả backend và frontend
- Lệnh tự động hoàn thành không hoạt động đối với các lệnh cụ thể
- Hành vi lệnh không nhất quán giữa CLI và TUI
- Lệnh vẫn duy trì cấu hình nhưng không áp dụng trực tiếp trong TUI

## Tổng quan về kiến trúc`<!-- ascii-guard-ignore -->

`

Python backend (Hermes_CLI/commands.py)     <- canonical COMMAND_REGISTRY
       │
       ▼
TUI gateway (TUI_gateway/server.py)         <- slash.exec / command.dispatch
       │
       ▼
TUI frontend (ui-TUI/src/app/slash/)        <- local handlers + fallthrough

`

<!-- ascii-guard-ignore-end -->

Các định nghĩa lệnh phải được đăng ký nhất quán trên Python và TypeScript để hoạt động chính xác. Python 
`COMMAND_REGISTRY
` là nguồn thông tin chính xác cho: công văn CLI, trợ giúp cổng, menu Telegram BotCommand, bản đồ lệnh phụ Slack và dữ liệu tự động hoàn thành được chuyển tới Ink.

## Các bước điều tra
1. **Kiểm tra xem lệnh có tồn tại trong giao diện TUI không:**

``` bash
   search_files --pattern "/commandname" --file_glob "*.ts" --path ui-TUI/
   search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-TUI/

2. **Kiểm tra định nghĩa lệnh TUI:**

`bash
   read_file ui-TUI/src/app/slash/commands/core.ts

   # If not there:
   search_files --pattern "commandname" --path ui-TUI/src/app/slash/commands --target files

3. **Kiểm tra xem lệnh có tồn tại trong chương trình phụ trợ Python không:**

``` bash
   search_files --pattern "CommandDef" --file_glob "*.py" --path Hermes_CLI/
   search_files --pattern "commandname" --path Hermes_CLI/commands.py --context 3

4. **Kiểm tra việc triển khai cổng:**

`bash
   search_files --pattern "complete.slash|slash.exec" --path TUI_gateway/

## Khắc phục: Thiếu lệnh Tự động hoàn thành

Nếu lệnh tồn tại trong TUI nhưng không hiển thị trong tự động hoàn thành:
1. Thêm mục nhập 
`CommandDef
` vào 
`COMMAND_REGISTRY
` trong 
`Hermes_CLI/commands.py

:

`Python
   CommandDef("commandname", "Description of the command", "Session",
              CLI_only=True, aliases=("alias",),
              args_hint="[arg1|arg2|arg3]",
              subcommands=("arg1", "arg2", "arg3")),

2. Chọn cẩn thận 
`CLI_only
` so với tính khả dụng của cổng:

   - 
`CLI_only=True

 - chỉ trong CLI/TUI tương tác
   - 
`gateway_only=True

 - chỉ trong nền tảng nhắn tin
   - không - có sẵn ở khắp mọi nơi
   - 
`gateway_config_gate="display.foo"
` — tính khả dụng có kiểm soát cấu hình trong cổng
3. Đảm bảo 
`subcommands
` khớp với các tùy chọn hoàn thành tab dự kiến được TUI hiển thị.
4. Nếu lệnh chạy phía máy chủ, hãy thêm trình xử lý trong 
`HermesCLI.process_command()
` trong 
`CLI.py

:

``` python
   elif canonical == "commandname":
       self._handle_commandname(cmd_original)

5. Đối với các lệnh có sẵn trên cổng, hãy thêm trình xử lý trong 
`gateway/run.py

:

`Python
   if canonical == "commandname":
       return await self._handle_commandname(event)

## Các vấn đề thường gặp
1. **Lệnh hiển thị trong TUI nhưng không hiển thị trong tự động hoàn thành.** Lệnh được xác định trong cơ sở mã TUI nhưng bị thiếu trong 
`COMMAND_REGISTRY
` trong 
`Hermes_CLI/commands.py

. Dữ liệu tự động hoàn thành được gửi từ Python.
2. **Lệnh hiển thị ở chế độ tự động hoàn thành nhưng không hoạt động.** Kiểm tra trình xử lý lệnh trong 
`TUI_gateway/server.py
` và trình xử lý giao diện người dùng trong 
`ui-TUI/src/app/createSlashHandler.ts

. Nếu lệnh chỉ cục bộ trong Ink thì lệnh đó phải được xử lý trong nhánh tích hợp sẵn 
`app.tsx

; nếu không nó sẽ rơi vào 
`slash.exec
` và phải có trình xử lý Python.
3. **Hành vi lệnh khác nhau giữa CLI và TUI.** Lệnh có thể có cách triển khai khác nhau. Kiểm tra cả 
`CLI.py::process_command
` và trình xử lý cục bộ của TUI. Trình xử lý TUI cục bộ được ưu tiên hơn so với việc gửi cổng.4. **Lệnh vẫn duy trì cấu hình nhưng không áp dụng trực tiếp.** Đối với các lệnh TUI-local, việc cập nhật 
`config.set
` là không đủ. Đồng thời vá ngay trạng thái cửa hàng nano có liên quan (thường là 
`patchUiState(...)

) và chuyển bất kỳ trạng thái mới nào thông qua các thành phần kết xuất. Ví dụ: 

/details collapsed
` phải cập nhật khả năng hiển thị chi tiết trực tiếp, không chỉ lưu 
`details_mode

; 

/details <mode>
` toàn cầu trong phiên có thể cần một cờ ghi đè lệnh riêng để các lệnh trực tiếp có thể ghi đè các giá trị mặc định của phần tích hợp trong khi đồng bộ hóa khởi động/cấu hình duy trì hành vi công cụ/tư duy mở rộng mặc định.
5. **Gửi cổng âm thầm bỏ qua lệnh.** Cổng chỉ gửi các lệnh mà nó biết. Kiểm tra 
`GATEWAY_KNOWN_COMMANDS
` (có nguồn gốc tự động từ 
`COMMAND_REGISTRY

) bao gồm tên chuẩn. Nếu lệnh là 
`CLI_only
` với 
`gateway_config_gate

, hãy xác minh giá trị cấu hình kiểm soát là trung thực.

## Chiến thuật gỡ lỗi

Khi kiểm tra ở cấp độ bề mặt không phát hiện ra lỗi:
- **Phía Python bị treo hoặc hoạt động sai:** sử dụng kỹ năng 
`Python-debugpy
` để đột nhập vào 
`_SlashWorker.exec
` hoặc trình xử lý lệnh. 
`remote-pdb
` được đặt ở mục xử lý là đường dẫn nhanh nhất.

- **Mặt mực không phản ứng:** sử dụng kỹ năng 
`node-inspect-debugger
` để phá vỡ công văn gạch chéo của 
`app.tsx
` hoặc nhánh lệnh cục bộ. 
`sb('dist/app.js', <line)
` sau 
`npm run build

.
- **Đăng ký không khớp/không rõ bên nào sai:** so sánh song song mục nhập 
`COMMAND_REGISTRY
` chuẩn với danh sách lệnh cục bộ của TUI.

## cạm bẫy
- Đừng quên đặt danh mục thích hợp cho lệnh trong 
`CommandDef
` (ví dụ: "Phiên", "Cấu hình", "Công cụ & Kỹ năng", "Thông tin", "Thoát")
- Đảm bảo rằng mọi bí danh đều được đăng ký chính xác trong bộ dữ liệu 
`aliases
` — không cần thay đổi tệp nào khác, mọi thứ ở phía dưới (menu Telegram, ánh xạ Slack, tự động hoàn thành, trợ giúp) đều bắt nguồn từ nó
- Đối với các lệnh có lệnh phụ, hãy đảm bảo bộ dữ liệu 
`subcommands
` trong 
`CommandDef
` khớp với nội dung trong mã TUI
- Các lệnh 
`CLI_only=True
` sẽ không hoạt động trong nền tảng cổng/nhắn tin - trừ khi bạn thêm 
`gateway_config_gate
` và cổng là trung thực
- Sau khi thêm trạng thái giao diện người dùng trực tiếp, hãy tìm kiếm mọi người sử dụng prop/helper cũ và xâu chuỗi trạng thái mới thông qua tất cả các đường dẫn hiển thị chứ không chỉ đường dẫn phát trực tuyến đang hoạt động. Kết xuất chi tiết TUI có ít nhất hai đường dẫn quan trọng: 
`StreamingAssistant

/
`ToolTrail
` trực tiếp và bản ghi/các hàng 
`MessageLine
` đang chờ xử lý. Thẻ 

/clean
` phải kiểm tra rõ ràng cả hai.
- Xây dựng lại TUI (
`npm --prefix ui-TUI run build

) trước khi thử nghiệm - chế độ đồng hồ tsx có thể bị lag trong lần khởi chạy đầu tiên

## Xác minh

Sau khi sửa:
1. Xây dựng lại TUI:

``` bash
   cd /home/bb/Hermes-agent && npm --prefix ui-TUI run build

2. Chạy TUI và kiểm tra lệnh:

`bash
   Hermes --TUI

3. Nhập 

/
` và xác minh lệnh xuất hiện trong đề xuất tự động hoàn thành với mô tả dự kiến và gợi ý đối số.
4. Thực hiện lệnh và xác nhận:

   - Hành vi dự kiến sẽ xảy ra hỏa hoạn
   - Mọi cập nhật cấu hình liên tục đều chính xác (
`read_file ~/.Hermes/config.yaml

)
   - Trạng thái giao diện người dùng trực tiếp phản ánh sự thay đổi ngay lập tức (không chỉ sau khi khởi động lại)
5. Nếu lệnh cũng có sẵn trên cổng, hãy kiểm tra lệnh đó từ ít nhất một nền tảng nhắn tin (hoặc chạy kiểm tra cổng: 
`scripts/run_tests.sh tests/gateway/

).