Khắc phục sự cố

#Cài đặt và lần khởi động đầu tiên

Linux: trên Ubuntu 23.10 trở lên, AppImage có thể dừng khi khởi động với lỗi sandbox, vì AppArmor hạn chế các user namespace mà sandbox của Electron sử dụng. Hãy cài .deb thay thế.

#Không ghi được màn hình hoặc cửa sổ (macOS)

Thông báo: Ghi toàn màn hình hoặc cửa sổ khác cần quyền Ghi màn hình của macOS.

1. Trong hộp thoại Mục tiêu ghi, nhấn Mở System Settings.
2. Privacy & Security → Screen & System Audio Recording: bật Ferret.
3. Khởi động lại ứng dụng, rồi nhấn Kiểm tra lại.

Ghi Trình duyệt tích hợp không cần quyền nào.

Khi chạy từ mã nguồn trên macOS, pnpm dev khởi chạy một bản sao Electron đã đổi tên, ký ad-hoc, cũng có tên Ferret (scripts/prepare-dev-electron.mjs), nên nó xuất hiện như một mục Ferret riêng trong các danh sách này. Lần đầu chạy, macOS sẽ hỏi lại quyền Ghi màn hình và Microphone. Sau đó sẽ không hỏi lại nữa. Bản build phát triển dùng keychain giả (--use-mock-keychain), nên không có hộp thoại Keychain: cookie và key được lưu trong bản build dev được mã hóa bằng một key cố định, không phải bằng Keychain thật. Đặt ADE_DEV_REAL_KEYCHAIN=1 để dùng Keychain thật.

#Không mở được microphone

Thông báo: Không mở được microphone. Kiểm tra quyền trong cài đặt hệ điều hành.

• macOS: System Settings → Privacy & Security → Microphone, rồi bật Ferret.
• Windows: Cài đặt → Quyền riêng tư và bảo mật → Micrô, rồi cho phép ứng dụng desktop.

Khi không có mic, các vòng tròn vẽ bằng bút vẫn tạo ra góp ý, nhưng không kèm yêu cầu bằng lời nói.

#Không ghi được phía bên kia của cuộc họp

Khi Ghi cả phía bên kia đang bật mà không ghi được âm thanh của máy tính, Ferret hiện một trong các cảnh báo sau và vẫn tiếp tục ghi microphone, video và nét bút của bạn.

• Ferret chưa được phép ghi âm thanh hệ thống. (macOS): bật Ferret trong System Settings → Privacy & Security → Screen & System Audio Recording, thoát và mở lại Ferret, rồi bắt đầu một lần ghi mới.
• Cần macOS 14.2 trở lên để ghi giọng phía bên kia.: cập nhật macOS. Trước khi cập nhật, chỉ microphone của bạn được ghi.
• Windows không cho phép truy cập âm thanh hệ thống. hoặc không tìm thấy thiết bị phát âm thanh.: bật loa hoặc tai nghe trong Settings → System → Sound (Windows) hoặc cắm chúng vào, rồi bắt đầu một lần ghi mới.
• không có âm thanh hệ thống. (Linux): cài PulseAudio, hoặc pipewire-pulse nếu bạn dùng PipeWire.
• Đã ngừng ghi giọng phía bên kia: thiết bị phát âm thanh đã đổi hoặc bị ngắt.: phần còn lại của bản ghi tiếp tục mà không có phía bên kia. Dùng Ghi thêm để ghi phần còn lại.

Nếu lời của phía bên kia cũng xuất hiện như lời của bạn, microphone của bạn đang thu âm thanh từ loa. Hãy dùng tai nghe.

#Không có model trên máy / không tìm thấy whisper-cli

Thông báo: Không tìm thấy model chuyển văn bản trên máy. Âm thanh sẽ được lưu, và chỉ góp ý bằng bút được xử lý.

Tải model trong Cài đặt, hoặc chọn một tệp ggml-*.bin có sẵn. Nếu Cài đặt báo Không tìm thấy whisper.cpp (whisper-cli), hãy cài nó (hướng dẫn), đảm bảo nó nằm trong PATH, rồi mở lại Cài đặt. Ứng dụng đóng gói được mở từ Finder hoặc Explorer có thể không thấy PATH của shell, nên hãy cài vào vị trí tiêu chuẩn, chẳng hạn vị trí của Homebrew.

Model tải về không qua được kiểm tra sha256 sẽ bị loại bỏ. Hãy tải lại.

#Terminal: không tải được node-pty

Lỗi này xảy ra khi chạy từ mã nguồn và node-pty được build cho một ABI Node hoặc Electron khác.

pnpm rebuild:native

#Không tìm thấy agent / Gửi cho Agent không gửi được

• command not found: claude (hoặc codex, gemini, hay lệnh của agent khác) trong terminal: CLI chưa được cài hoặc không nằm trong PATH. Ferret hiển thị nguyên lỗi của shell và không thêm gợi ý nào. Hãy kiểm tra lệnh đó chạy được trong terminal thông thường của bạn, dùng Cài đặt trong Cài đặt → Agent, hoặc đặt đường dẫn tuyệt đối làm Lệnh của agent đó.
• Agent đang chờ xác nhận. Hãy phản hồi trong terminal, rồi gửi. Hãy trả lời yêu cầu của agent trước.
• Ô nhập của agent chưa sẵn sàng. Đợi agent khởi động xong.
• Văn bản đã được nhập nhưng chưa gửi. Hãy nhấn Enter trong terminal.
• Hãy mở terminal trước.
• Không phân tích được tham số khởi chạy: Unclosed quote. Sửa lại dấu ngoặc kép trong tham số của agent.

#Không bắt đầu ghi được

• Hãy mở thư mục dự án trước.
• Hãy mở URL cần review trước.
• Trang không tải được. Hãy mở một URL hiển thị được, rồi ghi. Kiểm tra dev server có đang chạy không. Không kết nối được server nghĩa là không có gì đang lắng nghe ở port đó.

#Chưa đặt OpenAI key hoặc endpoint

Chưa đặt OpenAI API key… hoặc Chưa đặt endpoint chuyển văn bản (Base URL / model)…: thêm trong Cài đặt, hoặc chuyển sang Trên máy (miễn phí). Âm thanh của bản ghi đó đã được lưu.

#Lỗi GitHub

• Không tìm thấy GitHub CLI (gh). Cài gh.
• Chưa đăng nhập GitHub. Cài đặt → GitHub / GitLab → Đăng nhập trong terminal.
• Không có remote origin. hoặc origin không phải repository GitHub. Kiểm tra git remote -v.
• Không tìm thấy repository, hoặc bạn không có quyền truy cập. Kiểm tra gh auth status và GH_TOKEN.

#Báo lỗi

Mở một issue tại github.com/JapanMarketing-Dev/ferret/issues (mở trong tab mới) kèm hệ điều hành, phiên bản ứng dụng (footer → Cập nhật) và các bước để tái hiện lỗi. Đừng đính kèm nội dung .ferret/ có chứa màn hình riêng tư.