Kocoro 智能体循环架构 Agent Loop · 运行模式 · Cloud 委托
单次循环迭代阶段
TUI 终端交互Bubble Tea · 流式输出
CLI 命令行单轮执行 · Glamour
Daemon 守护进程HTTP API · SSE
Desktop 客户端WebSocket · 实时审批
核心循环 · Agent Loop
上下文预处理图片清理 · 旧工具结果压缩 · 进度检查
LLM 调用流式传输 · 3次重试 · 指数退避
响应处理幻觉检测 · 截断续写 · 文本直出
工具三阶段① 串行权限检查 → ② 并行执行 → ③ 串行后处理
循环判定9种卡循环检测 · 最大迭代数守护
工具生态 · 3层优先级
本地工具 ×26文件 · Shell · macOS GUI · 调度 · 会话
MCP 工具stdio / HTTP 传输 · Playwright
网关工具Shannon Cloud 远程工具白名单
cloud_delegate复杂任务委托 · 每轮限一次
Cloud
use_skill技能加载 · SKILL.md
Anthropic Claude主力模型 · Streaming
OpenAI / GoogleGPT · Gemini · 可切换
Shannon Cloud多策略编排 · SSE
MCP Server 进程Playwright · 自定义服务
EventHandler 接口驱动 — 同一循环核心，不同运行模式通过事件接口适配
五层权限模型
硬拦截rm -rf / · dd · curl|bash · 不可覆盖
denied_commands用户配置拒绝列表 (glob)
Shell AST 解析复合命令 (&&, ||, |) 逐条检查
allowed + 默认安全允许列表 + 200+ 只读命令
上下文窗口管理
窗口监控input + output ≥ 85% → 触发压缩
PersistLearnings压缩前提取记忆 → MEMORY.md
GenerateSummary小模型生成对话摘要
ShapeHistory首尾保留 · 中间丢弃
Cloud 委托流程
Cloud
SubmitTaskStream提交任务 → 获取 workflow_id
SSE 事件流实时状态 · 代理进度 · 流式输出
工作流类型Research · Swarm · Auto 自动选择
结果直通CloudResult 绕过 LLM 摘要
Hooks 钩子
PreToolUseexit(2) = 拒绝 · 可拦截
PostToolUse审计日志 · 不阻塞
Session 生命周期Start · Stop
审批流程 · 三模式对比
TUI 模式终端内 y/n 交互 · Always Allow
CLI 模式stdin 提示 / -y 全自动
Daemon 模式ApprovalBroker → WS → Desktop
生产
自动审批auto_approve: true · 权限仍生效
ShanClaw Desktop用户审批 UI
Daemon 守护进程架构 生产主路径
HTTP Serverlocalhost · ~40 REST 端点
SessionCache路由互斥 · 并发安全
RunAgent每请求创建新 Loop
EventBusSSE 推送 · 实时事件
ApprovalBrokerWS 审批中介 · 5分钟超时
MCP Supervisor健康探针 · 自动重连
Config 热重载RWMutex · 无中断切换
审计日志JSON Lines
优先级: 本地 > MCP > 网关
同名去重
↑ 循环迭代
直到 LLM 纯文本返回
file_read · bash · screenshot · computer
browser · cloud_delegate · session_search …
安全边界
客户端输入
网络白名单
localhost 放行 · 通配域名
Cloud 隔离
Shannon Cloud 多租户沙箱
关键设计理念
运行模式解耦 — AgentLoop 通过 EventHandler 接口与外部解耦，TUI/CLI/Daemon 仅实现事件回调，核心循环代码只有一份
写前压缩 — 丢弃上下文前先提取记忆 (PersistLearnings)，确保知识不丢失
Cloud 直通 — cloud_delegate 结果标记 CloudResult 后绕过 LLM 摘要，避免信息损失
审批异步 — Daemon 模式通过 ApprovalBroker + WS 实现非阻塞审批，5分钟超时
配置三层合并
~/.shannon/config.yaml ← 全局
.shannon/config.yaml ← 项目
.shannon/config.local.yaml ← 本地 (gitignore)
标量覆盖 · 列表合并去重 · 结构体字段级合并