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 服务器处理。