Kocoro：面向 macOS 的本地 AI Agent 运行时与开发框架

Kocoro是Shannon团队开发维护的、专为macOS系统打造的本地AI Agent运行时环境与完整开发框架。其核心定位为“本地优先”——区别于完全依赖云服务的AI助手，Kocoro强调本地执行代码、访问文件、控制系统资源，同时保持与云端服务的灵活连接能力，既保护用户数据隐私，又提供强大的本地计算能力。主要功能包括交互式TUI、守护进程模式、丰富的本地工具集（文件操作、GUI控制、浏览器自动化）、MCP集成能力、Shannon Cloud连接及云端工作流委托等。

命令行界面（shan CLI）

shan是Kocoro的主命令行工具，支持多种运行模式：

• 交互式TUI模式：启动终端用户界面，支持与Agent持续对话
• 一次性模式：直接执行单个查询并返回结果
• 自动确认模式：通过-y标志跳过工具调用确认，适合自动化脚本 CLI遵循Unix哲学，可通过管道和脚本与其他工具集成。

守护进程（Daemon）

守护进程是核心服务组件，提供：

• WebSocket连接：与Shannon Cloud建立持久连接，接收Slack、LINE等渠道消息
• 本地HTTP API：在localhost:7533提供RESTful API
• 多Agent管理：支持同时运行多个命名Agent，每个拥有独立配置和会话历史
• 任务调度：基于launchd的本地定时任务管理 采用“claim-ack”协议，最多可并发运行5个Agent。

本地工具集

覆盖文件操作、系统控制、GUI交互等层面：

文件与文档操作

file_read/file_write/file_edit、glob/grep、directory_list、archive_inspect/extract、pdf/docx/xlsx/pptx_to_text等。

Shell与系统控制

bash（120秒超时、安全命令自动批准）、system_info、process管理、http客户端（支持网络白名单）。

macOS GUI控制

accessibility（无障碍API）、computer（鼠标键盘控制）、screenshot、applescript、clipboard/notify、browser自动化、ghostty终端控制等。

MCP集成架构

Kocoro实现Model Context Protocol（MCP）开放协议，支持：

• 作为MCP客户端：连接外部MCP服务器（文件系统、SQLite、GitHub等）扩展工具能力
• 作为MCP服务器：通过shan mcp serve将本地工具暴露给Claude Desktop、Cursor等客户端 MCP配置支持全局（~/.shannon/config.yaml）、项目（.shannon/config.yaml）、本地覆盖（.shannon/config.local.yaml）多级合并。

命名Agent与个性化配置

支持创建多个命名Agent，每个拥有独立：

• 指令文件（AGENT.md）：定义角色、能力和行为准则
• 记忆文件（MEMORY.md）：跨会话持久化记忆
• 配置文件（config.yaml）：工具白名单、MCP服务器、模型参数等
• 自定义命令（commands/）：专属斜杠命令
• 附加技能（_attached.yaml）：绑定技能列表 示例场景Agent：ops-bot（运维监控）、reviewer（代码审查）、writer（写作助手）。

安全与权限模型

多层防护机制：

• 工具调用权限：硬阻断危险命令（如rm -rf /）、自动批准只读/安全命令、破坏性操作需交互确认、复合命令拆分检查
• 文件系统保护：符号链接解析保护、敏感文件模式匹配（.env、.pem等）、允许目录白名单
• 审计日志：所有工具调用记录到~/.shannon/logs/audit.log（JSON Lines格式），自动脱敏敏感信息。

会话管理

• 会话持久化：对话历史保存为JSON文件，支持断点续聊
• 会话搜索：基于SQLite FTS5的全文检索
• 会话恢复：通过/sessions命令浏览和恢复历史会话
• 上下文压缩：窗口压力过高时自动压缩历史消息 每个命名Agent拥有独立会话目录。

记忆系统

• 结构化记忆：通过MEMORY.md实现跨会话知识积累
• 情景记忆：可选云端记忆服务，从历史会话提取相关记忆注入新会话（opt-in默认关闭）
• 技能系统：遵循Anthropic SKILL.md规范的可复用能力模块，支持全局安装、Agent绑定、动态激活；内置kocoro（平台配置）和kocoro-generative-ui（可视化）技能。

云端集成

• Shannon Cloud连接：WebSocket接收多渠道消息、/research委托云端深度研究、/swarm启动云端多Agent协作、云端API生成图片
• 模型提供商选择：Shannon Cloud、自托管Gateway、Ollama（本地开源模型如Llama 3.1、Qwen3等）

开发者生态与扩展性

• 生命周期钩子：工具调用前后、会话开始/结束时执行自定义脚本（如PreToolUse、PostToolUse）
• 自定义命令：在commands/目录创建Markdown文件添加斜杠命令
• HTTP API：守护进程提供发送消息、会话管理、Agent配置重载、SSE事件流等接口，支持自定义客户端和自动化脚本。

安装与使用

提供多种安装方式：

• npm：npm install -g @kocoro/kocoro
• 安装脚本：curl -fsSL ... | sh
• Go源码：go install . 安装后通过shan --setup配置端点和API密钥即可使用。

应用场景

适用于：

• 个人自动化：文件整理、系统监控、定时任务
• 开发辅助：代码审查、项目分析、文档生成
• 知识管理：笔记整理、资料归档、信息检索
• 智能客服：多消息渠道接入提供自动化回复
• 研究助手：网络搜索、资料汇总、报告生成 为注重数据隐私的macOS用户提供功能完备、安全可控的本地AI Agent解决方案。

作为活跃开发的开源项目，Kocoro未来可能演进方向：

• 扩展更多本地工具（如浏览器自动化能力）
• 优化与开源模型的兼容性
• 增强多模态能力（图像理解、语音交互）
• 提供更丰富的技能市场
• 改进跨平台支持（目前仅限macOS） 对AI Agent技术探索者而言，Kocoro既是实用工具，也是学习实验的优秀平台。