Kocoro-lab/Kocoro

A Mac-native AI agent with memory, local computer access, browser control, IM channels, and MCP-native integrations. Built on Shannon.

Kocoro – 安裝在你的 Mac 上的 AI 同事

是什麼 – Kocoro 是一個運行於 macOS 上的本地 AI 代理框架。專案的開源部分（shan 執行時）是一個守護程序，可驅動「代理」執行讀取/寫入檔案、控制應用程式、執行 shell 命令、自動化瀏覽器，以及透過 Slack/LINE/Feishu/Telegram 進行聊天。一個獨立的閉源 GUI 應用程式（Kocoro Desktop）與此守護程序通訊，但守護程序本身也可直接透過命令列、TUI 或 HTTP API 使用。

為何重要 – 它讓你能夠賦予語言模型 完整的電腦存取權限，同時將繁重的運算任務保留在你自己的裝置上。代理迴圈、權限檢查、工具清單與記憶體管理皆整合於守護程序中，因此你可以在不將檔案或螢幕資料傳送給第三方服務的情況下，執行相同的 AI 驅動工作流程。

核心功能

領域	Kocoro 能做什麼
代理執行時	具有持久記憶的命名代理，可設定工具，以及每項任務的審核。
本地工具	檔案讀取/寫入/編輯，glob/grep，歸檔檢查/提取，PDF/DOCX/XLSX/PPTX 文字提取，shell（`bash`），macOS AppleScript，可存取性/電腦使用 UI 自動化，剪貼簿，通知，透過 Playwright 實現瀏覽器自動化（降級至 ChromeDP）。
權限引擎	細粒度審核（`yes` 自動批准，工具級提示，或 `--dangerously-skip-permissions` 用於測試）。
互動模式	• 互動式 TUI（`shan`），• CLI 一次性指令，• 守護程序 HTTP API（埠 7533），• MCP（訊息控制協定）伺服器/用戶端，• macOS 實時語音前腦（`shan koe`）。
團隊整合	透過 Shannon Cloud 網關向 Slack、LINE、Feishu、Telegram 發送/接收訊息。
記憶體與同步	會話歷史本地儲存，可選雲端同步（Kocoro Cloud）以實現跨裝置連續性。
排程與監視器	本地排程任務，檔案系統監視器，用於定期檢查的心跳模式。
可擴充性	鈎子、自訂指令，以及每個工具的外掛式 `Info()` 模式。

快速入門（如 README 所述）

安裝守護程序

# npm（推薦 – 啟動時自動更新）
npm install -g @kocoro/kocoro

# 或腳本
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Kocoro/main/install.sh | sh

# 或從原始碼建置（需要 Go 1.25+）
git clone https://github.com/Kocoro-lab/Kocoro.git
cd Kocoro
go build -o $(go env GOPATH)/bin/shan .
ln -sf shan $(go env GOPATH)/bin/kocoro   # 可選別名

設定 LLM 網關 – 選擇 Shannon Cloud API 金鑰、自架設的 Shannon 網關，或用於本地模型的 Ollama。
```
shan --setup   # 提示輸入端點和 API 金鑰
```
執行代理
- 互動式 TUI：shan
- 一次性查詢：shan "who was Ada Lovelace"
- 使用命名代理：shan --agent ops-bot "check prod health"
- 自動批准所有工具使用：shan -y "open Safari and navigate to github.com"
可選 GUI – 下載 Kocoro Desktop（macOS DMG），它與同一守護程序通訊。

架構快照

shan 二進位檔 – 守護程序/執行時。提供：
- TUI/CLI 前端。
- 程式化控制用 HTTP API（預設埠 7533）。
- 外部服務間串流訊息的 MCP 伺服器/用戶端。
工具 – internal/tools/ 下的 Go 套件，每個實作 Info() 模式（名稱、審核模式、輸入/輸出）。守護程序啟動時載入。
權限引擎 – 決定工具呼叫是否需要使用者確認；可透過 -y 或危險標誌跳過。
記憶體層 – 本地會話日誌，以及可選的 Kocoro Cloud 雲端同步，用於持久化代理記憶體。
語音前腦（shan koe） – 透過 WebRTC 將音訊路由至 OpenAI 或 Qwen，將轉錄請求輸入同一代理迴圈的即時語音介面。

誰會使用它？

進階使用者 – 希望讓 LLM 自動化重複的 macOS 任務（檔案清理、程式碼 lint、資料提取、UI 導航），但又不想讓模型擁有完整遠端存取權限的人。
開發者 – 建構自訂 AI 驅動工作流程；可新增工具或接入 HTTP API。
團隊 – 需要一個整合 Slack/Telegram 的共享「AI 同事」以按需提供協助的人。

授權

此專案採用 MIT 授權（詳見 LICENSE 檔案）。僅守護程序/執行時為開源；附帶的 Kocoro Desktop GUI 為專有軟體。

快速參考速查表

# 啟動互動式介面
shan

# 一次性查詢（提示工具審核）
shan "list all TODO comments in this project"

# 自動批准所有工具（謹慎使用）
shan -y "open Calendar and show me today's events"

# 執行命名代理
shan --agent research-bot "summarize the latest AI papers"

# 啟動 MCP 伺服器（供外部用戶端使用）
shan mcp serve

# 建立定期任務
shan schedule create "daily backup" "shan \"run backup.sh\"" --cron "0 2 * * *"

總結 – Kocoro 的開源 shan 守護程序為 macOS 用戶提供了一個功能完整的本地執行 AI 代理平台，可讀取/寫入檔案、控制 GUI、執行 shell 命令，並與團隊聊天服務通訊，同時將重負荷的 LLM 推理任務交由 Shannon 雲或本地 Ollama 伺服器處理。