ttguy0707/CyberClaw

解决的问题

CyberClaw 是一个为使智能体工作流更具可观测性、安全性与可扩展性而设计的通用 AI 智能体框架。它通过引入动态技能的严格「help → run」协议，确保智能体在执行命令前已获取最新指令，从而解决工具执行不可靠的问题。

工作原理

基于 LangGraph 构建，项目实现了状态图（START → agent → tools → agent）。使用 AsyncSqliteSaver 实现会话持久化，并采用基于 Markdown 的用户档案实现长期记忆。为管理上下文，系统在 40 轮后自动修剪消息，保留最新 10 轮，并通过 LLM 对其余内容进行摘要。

关键技术机制包括：

• 两阶段技能执行：技能不会被直接调用；智能体必须先请求 help 以获取一次性 help_token。该令牌必须在 run 阶段提供，并在执行前与会话、技能身份和内容哈希进行验证。
• 子智能体委派：主智能体可将任务委派给专业子智能体（如 code_reviewer 或 document_analyst），或即时定义临时角色。这些子智能体在隔离上下文中运行，且工具访问受限。
• 定时任务：心跳协程每 10 秒检查一次 tasks.json 文件，以触发定时操作。
• 可观测性：一个有界异步队列将五类事件（LLM 输入、工具调用、结果、AI 消息、系统操作）记录到 JSONL 文件中，可通过专用监控 CLI 查看。

适用人群

• 需要结构化方式管理动态工具和技能的自主智能体开发者
• 希望拥有具备长期记忆并能将复杂任务委派给专业子智能体的 CLI 式 AI 助手的用户
• 寻求通过协议化方式调用工具以提高可靠性的框架的用户

核心亮点

• 强制协议：通过要求来自 help 调用的有效且限时的令牌，防止任意工具执行。
• 层级化智能体：支持预设和动态定义的子智能体，且具备隔离上下文。
• 上下文管理：通过自动 LLM 摘要和轮次裁剪机制，有效处理长对话。
• 内置工具集：包含 13 个核心工具，涵盖文件系统操作、带白名单的 shell 执行、调度和配置管理。
• 结构化审计：通过 JSONL 日志实时监控智能体决策与工具交互。