[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-voocel--openclaw-mini":3,"tool-voocel--openclaw-mini":62},[4,18,28,37,45,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":24,"last_commit_at":25,"category_tags":26,"status":17},9989,"n8n","n8n-io\u002Fn8n","n8n 是一款面向技术团队的公平代码（fair-code）工作流自动化平台，旨在让用户在享受低代码快速构建便利的同时，保留编写自定义代码的灵活性。它主要解决了传统自动化工具要么过于封闭难以扩展、要么完全依赖手写代码效率低下的痛点，帮助用户轻松连接 400 多种应用与服务，实现复杂业务流程的自动化。\n\nn8n 特别适合开发者、工程师以及具备一定技术背景的业务人员使用。其核心亮点在于“按需编码”：既可以通过直观的可视化界面拖拽节点搭建流程，也能随时插入 JavaScript 或 Python 代码、调用 npm 包来处理复杂逻辑。此外，n8n 原生集成了基于 LangChain 的 AI 能力，支持用户利用自有数据和模型构建智能体工作流。在部署方面，n8n 提供极高的自由度，支持完全自托管以保障数据隐私和控制权，也提供云端服务选项。凭借活跃的社区生态和数百个现成模板，n8n 让构建强大且可控的自动化系统变得简单高效。",184740,2,"2026-04-19T23:22:26",[16,14,13,15,27],"插件",{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":10,"last_commit_at":34,"category_tags":35,"status":17},10095,"AutoGPT","Significant-Gravitas\u002FAutoGPT","AutoGPT 是一个旨在让每个人都能轻松使用和构建 AI 的强大平台，核心功能是帮助用户创建、部署和管理能够自动执行复杂任务的连续型 AI 智能体。它解决了传统 AI 应用中需要频繁人工干预、难以自动化长流程工作的痛点，让用户只需设定目标，AI 即可自主规划步骤、调用工具并持续运行直至完成任务。\n\n无论是开发者、研究人员，还是希望提升工作效率的普通用户，都能从 AutoGPT 中受益。开发者可利用其低代码界面快速定制专属智能体；研究人员能基于开源架构探索多智能体协作机制；而非技术背景用户也可直接选用预置的智能体模板，立即投入实际工作场景。\n\nAutoGPT 的技术亮点在于其模块化“积木式”工作流设计——用户通过连接功能块即可构建复杂逻辑，每个块负责单一动作，灵活且易于调试。同时，平台支持本地自托管与云端部署两种模式，兼顾数据隐私与使用便捷性。配合完善的文档和一键安装脚本，即使是初次接触的用户也能在几分钟内启动自己的第一个 AI 智能体。AutoGPT 正致力于降低 AI 应用门槛，让人人都能成为 AI 的创造者与受益者。",183572,"2026-04-20T04:47:55",[13,36,27,14,15],"语言模型",{"id":38,"name":39,"github_repo":40,"description_zh":41,"stars":42,"difficulty_score":10,"last_commit_at":43,"category_tags":44,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":46,"name":47,"github_repo":48,"description_zh":49,"stars":50,"difficulty_score":24,"last_commit_at":51,"category_tags":52,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",161147,"2026-04-19T23:31:47",[14,13,36],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":59,"last_commit_at":60,"category_tags":61,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,27],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":77,"owner_email":78,"owner_twitter":73,"owner_website":79,"owner_url":80,"languages":81,"stars":90,"forks":91,"last_commit_at":92,"license":93,"difficulty_score":24,"env_os":94,"env_gpu":95,"env_ram":96,"env_deps":97,"category_tags":103,"github_topics":104,"view_count":24,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":108,"updated_at":109,"faqs":110,"releases":121},10160,"voocel\u002Fopenclaw-mini","openclaw-mini","🦞 OpenClaw 核心架构的极简复现，涵盖 sessionKey 会话域、队列串行、工具化记忆检索、按需上下文加载、可扩展技能与主动心跳唤醒机制","openclaw-mini 是大型 AI Agent 系统 OpenClaw 核心架构的极简复现版，旨在通过一个小而完整的项目，帮助开发者透彻理解生产级 AI Agent 的系统级设计。它解决了当前大多数教程仅关注基础“问答循环”，而忽视会话管理、上下文压缩、长期记忆及主动唤醒等关键工程难题的痛点。\n\n该项目特别适合希望深入钻研 AI Agent 底层原理的开发者、技术研究人员以及系统架构师。不同于普通的示例代码，openclaw-mini 保留了大量关于“为何如此设计”的深度注释，引导读者按核心、扩展、网关、工程四层架构循序渐进地学习。\n\n其独特技术亮点包括：实现双层 Agent 循环与类型化事件流机制；支持基于 JSONL 的会话持久化与自适应上下文裁剪压缩；内置工具化记忆检索与按需加载能力；以及模拟真实生产环境的 WebSocket RPC 网关和主动心跳唤醒机制。通过剥离繁杂的生产防护细节，openclaw-mini 让学习者能专注于掌握构建可演化、有记忆的\"AI 生命系统”所需的核心逻辑，是通往高阶 Agent 开发的优质入门路径。","# OpenClaw Mini\n\n**OpenClaw 核心架构的精简复现，用于学习 AI Agent 的系统级设计。**\n\n> \"没有记忆的 AI 只是函数映射，有记忆 + 主动唤醒的 AI，才是会演化的'生命系统'\"\n\n## 项目定位\n\n目标：\n\n- 用一个小而完整的项目解释 OpenClaw 内核真正重要的设计点\n- 让读者能同时读懂 CLI、Agent Loop、Session、Context、Gateway 四条主线\n- 保留“为什么这么设计”的注释，而不只是给出能跑的代码\n\n非目标：\n\n- 不追求和 OpenClaw 主仓库 1:1 API 兼容\n- 不覆盖所有 channel、provider、插件和运维能力\n- 不把生产环境里的所有防护、权限和兼容性细节都搬过来\n\n仓库：\n\n- GitHub: `https:\u002F\u002Fgithub.com\u002Fvoocel\u002Fopenclaw-mini`\n- npm 包名: `openclaw-mini`\n\n## 20 分钟快速开始\n\n```bash\ngit clone git@github.com:voocel\u002Fopenclaw-mini.git\ncd openclaw-mini\npnpm install\ncp .env.example .env\n```\n\n在 `.env` 里至少配置一个可用的模型 Key，然后先跑最小校验：\n\n```bash\npnpm test\npnpm dev\n```\n\n想直接看 Gateway 的 ACK-then-stream 链路：\n\n```bash\npnpm example:gateway\n```\n\n## 安装与开发\n\n作为独立项目开发：\n\n```bash\npnpm install\npnpm test\npnpm build\n```\n\n本地 CLI：\n\n```bash\npnpm dev\npnpm gateway\npnpm gateway:connect\n```\n\n发布前自检：\n\n```bash\npnpm test\npnpm build\npnpm pack:check\n```\n\n## 为什么做这个项目\n\n网上大多数 Agent 教程只讲 Agent Loop：\n\n```python\nwhile tool_calls:\n    response = llm.generate(messages)\n    for tool in tools:\n        result = tool.execute()\n        messages.append(result)\n```\n\n**这不是真正的 Agent 架构。** 一个生产级 Agent 需要的是\"系统级最佳实践\"。\n\nOpenClaw 是一个超 43w 行的复杂 Agent 系统，本项目从中提炼出核心设计与最小实现，帮助你理解：\n\n- Agent Loop 的双层循环与 EventStream 事件流\n- 会话持久化与上下文管理（裁剪 + 摘要压缩）\n- 长期记忆、技能系统、主动唤醒的真实实现\n- 多 Provider 适配（Anthropic \u002F OpenAI \u002F Google \u002F Groq 等 22+ 提供商）\n\n## 模块分层\n\n本项目按学习价值分为四层，建议按 **核心 → 扩展 → 网关 → 工程** 的顺序阅读：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     [网关层] Gateway                          │\n│  WebSocket RPC 网关，让 Agent 从 CLI 直连升级为网络服务       │\n│                                                              │\n│  Protocol (帧协议)  · Server (广播+握手+路由)                │\n│  Client (重连+心跳) · Handlers (RPC 方法)                    │\n├─────────────────────────────────────────────────────────────┤\n│                     [工程层] Production                      │\n│  生产级防护与控制，学习可跳过                                 │\n│                                                              │\n│  session-key · tool-policy · command-queue                   │\n│  sandbox-paths · context-window-guard · tool-result-guard    │\n├─────────────────────────────────────────────────────────────┤\n│                     [扩展层] Extended                         │\n│  openclaw 特有的高级功能，非通用 Agent 必需                   │\n│                                                              │\n│  Memory (长期记忆) · Skills (技能系统) · Heartbeat (主动唤醒) │\n├─────────────────────────────────────────────────────────────┤\n│                      [核心层] Core                            │\n│  任何 Agent 都需要的基础能力 ← 优先阅读                      │\n│                                                              │\n│  Agent Loop (双层循环)     EventStream (20 种类型化事件)      │\n│  Session (JSONL 持久化)    Context (加载 + 裁剪 + 摘要压缩)  │\n│  Tools (工具抽象+内置)     Provider (多模型适配)              │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心层 — 必读\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Agent** | `agent.ts` | 入口 + subscribe\u002Femit 事件分发 | `agent.js` |\n| **Agent Loop** | `agent-loop.ts` | 双层循环 (outer=follow-up, inner=tools+steering) | `agent-loop.js` |\n| **EventStream** | `agent-events.ts` | 20 种 MiniAgentEvent 判别联合 + 异步推拉 | `types.d.ts` AgentEvent |\n| **Session** | `session.ts` | JSONL 持久化、历史管理 | `session-manager.ts` |\n| **Context** | `context\u002Floader.ts` | 按需加载 AGENTS.md 等 bootstrap 文件 | `bootstrap-files.ts` |\n| **Pruning** | `context\u002Fpruning.ts` | 三层递进裁剪 (tool_result → assistant → 保留最近) | `context-pruning\u002Fpruner.ts` |\n| **Compaction** | `context\u002Fcompaction.ts` | 自适应分块摘要压缩 | `compaction.ts` |\n| **Tools** | `tools\u002F*.ts` | 工具抽象 + 10 个内置工具 | `src\u002Ftools\u002F` |\n| **Provider** | `provider\u002F*.ts` | 多模型适配层 (基于 pi-ai, 22+ 提供商) | `pi-ai` |\n\n### 扩展层 — 选读\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Memory** | `memory.ts` | 长期记忆 (关键词检索 + 相关性排序) | `memory\u002Fmanager.ts` |\n| **Skills** | `skills.ts` | SKILL.md frontmatter + 触发词匹配 | `agents\u002Fskills\u002F` |\n| **Heartbeat** | `heartbeat.ts` | 两层架构: wake 请求合并 + runner 调度 | `heartbeat-runner.ts` + `heartbeat-wake.ts` |\n\n### 工程层 — 可跳过\n\n| 模块 | 文件 | 核心职责 |\n|------|------|----------|\n| **Session Key** | `session-key.ts` | 多 agent 会话键规范化 (`agent:id:session`) |\n| **Tool Policy** | `tool-policy.ts` | 工具访问三级控制 (allow\u002Fdeny\u002Fnone) |\n| **Command Queue** | `command-queue.ts` | 并发 lane 控制 (session 串行 + global 并行) |\n| **Tool Result Guard** | `session-tool-result-guard.ts` | 自动补齐缺失的 tool_result |\n| **Context Window Guard** | `context-window-guard.ts` | 上下文窗口溢出保护 |\n| **Sandbox Paths** | `sandbox-paths.ts` | 路径安全检查 |\n\n### 网关层 — 进阶必读\n\n学习如何将 Agent 从 CLI 直连升级为可远程访问的 WebSocket RPC 服务。\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Protocol** | `gateway\u002Fprotocol.ts` | 三种帧类型 (req\u002Fres\u002Fevent) + 错误码 + 常量 | `protocol\u002Fschema\u002Fframes.ts` + `error-codes.ts` |\n| **Server** | `gateway\u002Fserver.ts` | HTTP+WS 服务、challenge 握手、方法路由、Pub\u002FSub 广播、背压控制、优雅关闭 | `server.impl.ts` + `server-broadcast.ts` + `server-close.ts` |\n| **Handlers** | `gateway\u002Fhandlers.ts` | 6 个 RPC 方法 (connect\u002Fchat.send\u002Fchat.history\u002Fsessions.*\u002Fhealth) | `server-methods\u002F*.ts` |\n| **Client** | `gateway\u002Fclient.ts` | Pending Map、指数退避重连、Tick 心跳监视、seq 间隙检测 | `client.ts` |\n| **CLI** | `gateway\u002Fgateway-cli.ts` | serve\u002Fconnect 双模式 CLI 入口 | `cli\u002Fgateway-cli.ts` |\n\n---\n\n## 核心设计解析\n\n### 1. Agent Loop — 双层循环 + EventStream\n\n**问题**：简单 while 循环无法处理 follow-up、steering injection、上下文溢出等复杂场景。\n\n**openclaw 方案**：双层循环 + EventStream 事件流\n\n```typescript\n\u002F\u002F agent-loop.ts — 返回 EventStream，IIFE 推送事件\nfunction runAgentLoop(params): EventStream\u003CMiniAgentEvent, MiniAgentResult> {\n  const stream = createMiniAgentStream();\n\n  (async () => {\n    \u002F\u002F outer loop: follow-up 循环（处理 end_turn \u002F tool_use 继续）\n    while (outerTurn \u003C maxOuterTurns) {\n      \u002F\u002F inner loop: 工具执行 + steering injection\n      \u002F\u002F stream.push({ type: \"tool_execution_start\", ... })\n    }\n    stream.end({ text, turns, toolCalls });\n  })();\n\n  return stream;  \u002F\u002F 调用方 for-await 消费\n}\n```\n\n**事件订阅**（对齐 pi-agent-core `Agent.subscribe`）：\n\n```typescript\nconst agent = new Agent({ apiKey, provider: \"anthropic\" });\n\nconst unsubscribe = agent.subscribe((event) => {\n  switch (event.type) {\n    case \"message_delta\":  \u002F\u002F 流式文本\n      process.stdout.write(event.delta);\n      break;\n    case \"tool_execution_start\":  \u002F\u002F 工具开始\n      console.log(`[${event.toolName}]`, event.args);\n      break;\n    case \"agent_error\":  \u002F\u002F 运行错误\n      console.error(event.error);\n      break;\n  }\n});\n\nconst result = await agent.run(sessionKey, \"列出当前目录的文件\");\nunsubscribe();\n```\n\n### 2. Session Manager — JSONL 持久化\n\n**问题**：Agent 重启后如何恢复对话上下文？\n\n```typescript\n\u002F\u002F session.ts — 双写策略: 内存缓存 + 磁盘持久化\nasync append(sessionKey: string, message: Message): Promise\u003Cvoid> {\n  \u002F\u002F 1. 内存缓存立即更新（读取零 I\u002FO）\n  state.entries.push(entry);\n\n  \u002F\u002F 2. 首条 assistant 消息后才落盘（避免空会话写磁盘）\n  if (!state.hasAssistant && message.role === \"assistant\") {\n    state.hasAssistant = true;\n    await rewriteSessionFile(state); \u002F\u002F 首次: 完整写入 header + entries\n  } else if (state.hasAssistant) {\n    await fs.appendFile(filePath, line); \u002F\u002F 后续: O(1) 追加\n  }\n}\n```\n\nJSONL 格式：每行一条 entry，损坏行跳过不影响其他数据。写锁防并发。\n\n### 3. Context — 加载 + 裁剪 + 摘要压缩\n\n**问题**：上下文窗口有限，如何在不丢失关键信息的情况下控制大小？\n\n三层递进策略：\n1. **Pruning** — 裁剪旧的 tool_result（保留最近 N 条完整）\n2. **Compaction** — 超过阈值后，旧消息压缩为\"历史摘要\"\n3. **Bootstrap** — 按需加载 AGENTS.md 等配置文件（超长文件 head+tail 截断）\n\n### 4. Memory — 长期记忆 (扩展层)\n\n**问题**：如何让 Agent \"记住\"跨会话的信息？\n\n```typescript\n\u002F\u002F memory.ts — 关键词匹配 + 纯相关性排序（无时间衰减）\nasync search(query: string, limit = 5): Promise\u003CMemorySearchResult[]> {\n  const queryTerms = query.toLowerCase().split(\u002F\\s+\u002F);\n  for (const entry of this.entries) {\n    let score = 0;\n    for (const term of queryTerms) {\n      if (text.includes(term)) score += 1;\n      if (entry.tags.some(t => t.includes(term))) score += 0.5;\n    }\n  }\n}\n```\n\nopenclaw 用 SQLite-vec 做向量语义搜索 + BM25 关键词搜索，本项目简化为纯关键词相关性检索，不引入时间衰减。\n\n### 5. Heartbeat — 主动唤醒 (扩展层)\n\n**问题**：Agent 如何\"主动\"工作，而不只是被动响应？\n\n两层架构：\n- **HeartbeatWake**（请求合并层）：多来源触发 (interval\u002Fcron\u002Fexec\u002Frequested) → 250ms 合并窗口 → 双重缓冲\n- **HeartbeatRunner**（调度层）：活跃时间检查 → HEARTBEAT.md 解析 → 空内容跳过 → 重复抑制\n\n| 设计点 | 为什么这样做 |\n|--------|-------------|\n| setTimeout 而非 setInterval | 精确计算下次运行时间，避免漂移 |\n| 250ms 合并窗口 | 防止多个事件同时触发 |\n| 双重缓冲 | 运行中收到新请求不丢失 |\n| 重复抑制 | 24h 内相同消息不重复发送 |\n\n### 6. Gateway — WebSocket RPC 网关 (网关层)\n\n**问题**：Agent 只能通过 CLI 本地使用，如何让多个客户端通过网络共享同一个 Agent？\n\n**openclaw 方案**：WebSocket RPC + Pub\u002FSub 广播 + Challenge-Response 认证\n\n```\n终端 A ──┐                          ┌── broadcast ──→ 终端 A\n         ├── WebSocket ──→ Gateway ──┤\n终端 B ──┘       RPC       (Agent)  └── broadcast ──→ 终端 B\n```\n\n**12 个精华设计模式**（全部从 openclaw 源码提炼）：\n\n| 设计模式 | 文件 | 对齐 openclaw |\n|---------|------|--------------|\n| 协议帧 (req\u002Fres\u002Fevent 判别联合) | `protocol.ts` | `protocol\u002Fschema\u002Fframes.ts` |\n| Challenge-Response 握手 | `server.ts` | `server\u002Fws-connection.ts` |\n| Timing-safe token 比较 | `handlers.ts` | `auth.ts` safeEqual |\n| 方法路由 Handler Map | `handlers.ts` | `server-methods.ts` |\n| Pub\u002FSub 广播 + seq 递增 | `server.ts` | `server-broadcast.ts` |\n| `dropIfSlow` 分级背压 | `server.ts` | `server-broadcast.ts` |\n| Delta 限流 (150ms) | `handlers.ts` | `server-chat.ts` emitChatDelta |\n| Tick 心跳 30s | `server.ts` | `server-maintenance.ts` |\n| Pending Map + 超时 + flush | `client.ts` | `client.ts` |\n| Seq 间隙检测 | `client.ts` | `client.ts` onGap |\n| 指数退避重连 (1s→30s) | `client.ts` | `client.ts` scheduleReconnect |\n| Tick 心跳监视 (2 周期) | `client.ts` | `client.ts` startTickWatch |\n\n**握手流程**：\n\n```\nServer                              Client\n  │◄──── WebSocket 连接建立 ───────────│\n  ├─ Event: connect.challenge ───────►│  { nonce, ts }\n  │◄── Request: connect ─────────────┤  { token, nonce }\n  ├── 验证 token (timingSafeEqual)     │\n  ├─ Response: HelloOk ──────────────►│  { protocol, methods, events, policy }\n```\n\n**ACK-then-stream 模式**（聊天消息流转）：\n\n```typescript\n\u002F\u002F 客户端发送\nclient.request(\"chat.send\", { sessionKey: \"main\", message: \"hello\" });\n\u002F\u002F 服务端立即 ACK: { ok: true, payload: { sessionKey, runId } }\n\u002F\u002F 异步执行 agent.run()，事件流通过 broadcast 推送：\n\u002F\u002F   Event { event: \"chat\", payload: { state: \"delta\", text: \"...\" } }  ← 150ms 限流\n\u002F\u002F   Event { event: \"chat\", payload: { state: \"final\", text: \"...\" } }\n```\n\n---\n\n## 设计模式索引\n\n| 模式 | 所在文件 | 说明 |\n|------|----------|------|\n| EventStream 异步推拉 | `agent-events.ts` | push\u002FasyncIterator\u002Fend\u002Fresult |\n| Subscribe\u002FEmit 观察者 | `agent.ts` | listeners Set + subscribe 返回 unsubscribe |\n| 双层循环 | `agent-loop.ts` | outer (follow-up) + inner (tools+steering) |\n| JSONL 追加日志 | `session.ts` | 每行一条消息，追加写入 |\n| 三层递进裁剪 | `context\u002Fpruning.ts` | tool_result → assistant → 保留最近 |\n| 自适应分块摘要 | `context\u002Fcompaction.ts` | 按 token 分块，逐块摘要 |\n| 双重缓冲调度 | `heartbeat.ts` | running + scheduled 状态机 |\n| 三级编译策略 | `tool-policy.ts` | allow\u002Fdeny\u002Fnone → 过滤工具列表 |\n| Challenge-Response 握手 | `gateway\u002Fserver.ts` | nonce 挑战 → token 验证 → HelloOk |\n| Timing-safe 认证 | `gateway\u002Fhandlers.ts` | crypto.timingSafeEqual 防计时攻击 |\n| WebSocket RPC Pending Map | `gateway\u002Fclient.ts` | UUID id → Promise → 超时自动 reject |\n| Pub\u002FSub 广播 + 背压 | `gateway\u002Fserver.ts` | seq 递增 + dropIfSlow + 慢消费者检测 |\n| 指数退避重连 | `gateway\u002Fclient.ts` | 1s → 2s → 4s → ... → 30s，成功后重置 |\n| Tick 心跳监视 | `gateway\u002Fclient.ts` | 2 周期无 tick → 主动断开触发重连 |\n| Delta 限流 | `gateway\u002Fhandlers.ts` | 150ms 内最多广播一次，累积文本 |\n| ACK-then-stream | `gateway\u002Fhandlers.ts` | 立即响应 → 异步执行 → 事件流推送 |\n\n---\n\n## 快速开始\n\n要求：Node.js `>=20`\n\n在项目根目录执行：\n\n```bash\npnpm install\n```\n\n推荐用 `.env` 文件配置（项目启动时自动加载）：\n\n```env\nOPENCLAW_MINI_PROVIDER=anthropic\nOPENCLAW_MINI_MODEL=claude-sonnet-4-20250514\nOPENCLAW_MINI_BASE_URL=https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\nANTHROPIC_API_KEY=sk-xxx\n```\n\n```bash\npnpm dev\n```\n\n### 使用 OpenAI 兼容 API\n\n智谱、DeepSeek、月之暗面 Kimi 等国产大模型均兼容 OpenAI 格式，通过 `provider=openai` + 自定义 `BASE_URL` 即可接入。\n\n以智谱免费模型 GLM-4-Flash 为例：\n\n```env\nOPENCLAW_MINI_PROVIDER=openai\nOPENCLAW_MINI_MODEL=glm-4-flash\nOPENCLAW_MINI_BASE_URL=https:\u002F\u002Fopen.bigmodel.cn\u002Fapi\u002Fpaas\u002Fv4\nOPENCLAW_MINI_REASONING=none\nOPENAI_API_KEY=你的API Key\n```\n\n```bash\npnpm dev\n```\n\n> `OPENCLAW_MINI_REASONING=none` 用于关闭 extended thinking，不支持该特性的模型需设置此项。\n\n### Gateway 模式\n\n除了 CLI 直连，还可以通过 Gateway 服务让多个客户端远程访问同一个 Agent：\n\n```bash\n# 终端 1：启动 Gateway 服务\npnpm gateway\n\n# 终端 2：连接 Gateway\npnpm gateway:connect\n```\n\n可选参数：\n\n```bash\npnpm gateway -- --port 8080 --token mySecret    # 自定义端口和认证 token\npnpm gateway:connect -- --url ws:\u002F\u002Fremote:18789  # 连接远程 Gateway\npnpm gateway:connect -- --session work            # 指定会话名\n```\n\n客户端内命令：`\u002Fhealth` 查看状态、`\u002Fsessions` 列出会话、`\u002Fquit` 断开。\n\n也支持 CLI 参数：\n\n```bash\n# 直接使用 Anthropic\nANTHROPIC_API_KEY=sk-xxx pnpm dev\n\n# 指定 provider + model\npnpm dev -- --provider openai --model gpt-4o\n\n# 使用代理\npnpm dev -- --base-url https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\n\n# 关闭 extended thinking（不支持的模型需设置）\npnpm dev -- --reasoning none\n```\n\n## 使用示例\n\n先确认基础检查能通过：\n\n```bash\npnpm build\npnpm test\n```\n\n教学用示例：\n\n```bash\npnpm example:basic\npnpm example:custom-tools\npnpm example:gateway\n```\n\n```typescript\nimport { Agent } from \"openclaw-mini\";\n\nconst agent = new Agent({\n  provider: \"anthropic\",\n  baseUrl: \"https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\", \u002F\u002F 可选，代理\u002F自部署端点\n  \u002F\u002F apiKey 不传则自动从环境变量读取\n  agentId: \"main\",\n  workspaceDir: process.cwd(),\n  reasoning: \"medium\", \u002F\u002F 默认开启 extended thinking (minimal\u002Flow\u002Fmedium\u002Fhigh\u002Fxhigh)\n});\n\n\u002F\u002F 事件订阅\nconst unsubscribe = agent.subscribe((event) => {\n  switch (event.type) {\n    case \"thinking_delta\": \u002F\u002F 流式思考\n      process.stdout.write(event.delta);\n      break;\n    case \"message_delta\": \u002F\u002F 流式文本\n      process.stdout.write(event.delta);\n      break;\n    case \"tool_execution_start\":\n      console.log(`[${event.toolName}]`, event.args);\n      break;\n  }\n});\n\nconst result = await agent.run(\"session-1\", \"请列出当前目录的文件\");\nconsole.log(`${result.turns} 轮, ${result.toolCalls} 次工具调用`);\n\nunsubscribe();\n```\n\n## 学习路径建议\n\n1. **核心层优先**：`agent-loop.ts` → `agent.ts` → `agent-events.ts` → `session.ts` → `context\u002F`\n2. **理解事件流**：subscribe\u002Femit 模式 + EventStream 异步推拉\n3. **扩展层选读**：`memory.ts` → `skills.ts` → `heartbeat.ts`（按兴趣）\n4. **网关层进阶**：`gateway\u002Fprotocol.ts` → `gateway\u002Fserver.ts` → `gateway\u002Fhandlers.ts` → `gateway\u002Fclient.ts`\n5. **对照 openclaw 源码**：验证简化版是否抓住了核心\n6. **工程层跳过**：除非你在做生产级 Agent，否则不需要关注\n\n## License\n\nMIT\n","# OpenClaw Mini\n\n**OpenClaw 核心架构的精简复现，用于学习 AI Agent 的系统级设计。**\n\n> \"没有记忆的 AI 只是函数映射，有记忆 + 主动唤醒的 AI，才是会演化的'生命系统'\"\n\n## 项目定位\n\n目标：\n\n- 用一个小而完整的项目解释 OpenClaw 内核真正重要的设计点\n- 让读者能同时读懂 CLI、Agent Loop、Session、Context、Gateway 四条主线\n- 保留“为什么这么设计”的注释，而不只是给出能跑的代码\n\n非目标：\n\n- 不追求和 OpenClaw 主仓库 1:1 API 兼容\n- 不覆盖所有 channel、provider、插件和运维能力\n- 不把生产环境里的所有防护、权限和兼容性细节都搬过来\n\n仓库：\n\n- GitHub: `https:\u002F\u002Fgithub.com\u002Fvoocel\u002Fopenclaw-mini`\n- npm 包名: `openclaw-mini`\n\n## 20 分钟快速开始\n\n```bash\ngit clone git@github.com:voocel\u002Fopenclaw-mini.git\ncd openclaw-mini\npnpm install\ncp .env.example .env\n```\n\n在 `.env` 里至少配置一个可用的模型 Key，然后先跑最小校验：\n\n```bash\npnpm test\npnpm dev\n```\n\n想直接看 Gateway 的 ACK-then-stream 链路：\n\n```bash\npnpm example:gateway\n```\n\n## 安装与开发\n\n作为独立项目开发：\n\n```bash\npnpm install\npnpm test\npnpm build\n```\n\n本地 CLI：\n\n```bash\npnpm dev\npnpm gateway\npnpm gateway:connect\n```\n\n发布前自检：\n\n```bash\npnpm test\npnpm build\npnpm pack:check\n```\n\n## 为什么做这个项目\n\n网上大多数 Agent 教程只讲 Agent Loop：\n\n```python\nwhile tool_calls:\n    response = llm.generate(messages)\n    for tool in tools:\n        result = tool.execute()\n        messages.append(result)\n```\n\n**这不是真正的 Agent 架构。** 一个生产级 Agent 需要的是\"系统级最佳实践\"。\n\nOpenClaw 是一个超 43w 行的复杂 Agent 系统，本项目从中提炼出核心设计与最小实现，帮助你理解：\n\n- Agent Loop 的双层循环与 EventStream 事件流\n- 会话持久化与上下文管理（裁剪 + 摘要压缩）\n- 长期记忆、技能系统、主动唤醒的真实实现\n- 多 Provider 适配（Anthropic \u002F OpenAI \u002F Google \u002F Groq 等 22+ 提供商）\n\n## 模块分层\n\n本项目按学习价值分为四层，建议按 **核心 → 扩展 → 网关 → 工程** 的顺序阅读：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     [网关层] Gateway                          │\n│  WebSocket RPC 网关，让 Agent 从 CLI 直连升级为网络服务       │\n│                                                              │\n│  Protocol (帧协议)  · Server (广播+握手+路由)                │\n│  Client (重连+心跳) · Handlers (RPC 方法)                    │\n├─────────────────────────────────────────────────────────────┤\n│                     [工程层] Production                      │\n│  生产级防护与控制，学习可跳过                                 │\n│                                                              │\n│  session-key · tool-policy · command-queue                   │\n│  sandbox-paths · context-window-guard · tool-result-guard    │\n├─────────────────────────────────────────────────────────────┤\n│                     [扩展层] Extended                         │\n│  openclaw 特有的高级功能，非通用 Agent 必需                   │\n│                                                              │\n│  Memory (长期记忆) · Skills (技能系统) · Heartbeat (主动唤醒) │\n├─────────────────────────────────────────────────────────────┤\n│                      [核心层] Core                            │\n│  任何 Agent 都需要的基础能力 ← 优先阅读                      │\n│                                                              │\n│  Agent Loop (双层循环)     EventStream (20 种类型化事件)      │\n│  Session (JSONL 持久化)    Context (加载 + 裁剪 + 摘要压缩)  │\n│  Tools (工具抽象+内置)     Provider (多模型适配)              │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心层 — 必读\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Agent** | `agent.ts` | 入口 + subscribe\u002Femit 事件分发 | `agent.js` |\n| **Agent Loop** | `agent-loop.ts` | 双层循环 (outer=follow-up, inner=tools+steering) | `agent-loop.js` |\n| **EventStream** | `agent-events.ts` | 20 种 MiniAgentEvent 判别联合 + 异步推拉 | `types.d.ts` AgentEvent |\n| **Session** | `session.ts` | JSONL 持久化、历史管理 | `session-manager.ts` |\n| **Context** | `context\u002Floader.ts` | 按需加载 AGENTS.md 等 bootstrap 文件 | `bootstrap-files.ts` |\n| **Pruning** | `context\u002Fpruning.ts` | 三层递进裁剪 (tool_result → assistant → 保留最近) | `context-pruning\u002Fpruner.ts` |\n| **Compaction** | `context\u002Fcompaction.ts` | 自适应分块摘要压缩 | `compaction.ts` |\n| **Tools** | `tools\u002F*.ts` | 工具抽象 + 10 个内置工具 | `src\u002Ftools\u002F` |\n| **Provider** | `provider\u002F*.ts` | 多模型适配层 (基于 pi-ai, 22+ 提供商) | `pi-ai` |\n\n### 扩展层 — 选读\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Memory** | `memory.ts` | 长期记忆 (关键词检索 + 相关性排序) | `memory\u002Fmanager.ts` |\n| **Skills** | `skills.ts` | SKILL.md frontmatter + 触发词匹配 | `agents\u002Fskills\u002F` |\n| **Heartbeat** | `heartbeat.ts` | 两层架构: wake 请求合并 + runner 调度 | `heartbeat-runner.ts` + `heartbeat-wake.ts` |\n\n### 工程层 — 可跳过\n\n| 模块 | 文件 | 核心职责 |\n|------|------|----------|\n| **Session Key** | `session-key.ts` | 多 agent 会话键规范化 (`agent:id:session`) |\n| **Tool Policy** | `tool-policy.ts` | 工具访问三级控制 (allow\u002Fdeny\u002Fnone) |\n| **Command Queue** | `command-queue.ts` | 并发 lane 控制 (session 串行 + global 并行) |\n| **Tool Result Guard** | `session-tool-result-guard.ts` | 自动补齐缺失的 tool_result |\n| **Context Window Guard** | `context-window-guard.ts` | 上下文窗口溢出保护 |\n| **Sandbox Paths** | `sandbox-paths.ts` | 路径安全检查 |\n\n### 网关层 — 进阶必读\n\n学习如何将 Agent 从 CLI 直连升级为可远程访问的 WebSocket RPC 服务。\n\n| 模块 | 文件 | 核心职责 | openclaw 对应 |\n|------|------|----------|---------------|\n| **Protocol** | `gateway\u002Fprotocol.ts` | 三种帧类型 (req\u002Fres\u002Fevent) + 错误码 + 常量 | `protocol\u002Fschema\u002Fframes.ts` + `error-codes.ts` |\n| **Server** | `gateway\u002Fserver.ts` | HTTP+WS 服务、challenge 握手、方法路由、Pub\u002FSub 广播、背压控制、优雅关闭 | `server.impl.ts` + `server-broadcast.ts` + `server-close.ts` |\n| **Handlers** | `gateway\u002Fhandlers.ts` | 6 个 RPC 方法 (connect\u002Fchat.send\u002Fchat.history\u002Fsessions.*\u002Fhealth) | `server-methods\u002F*.ts` |\n| **Client** | `gateway\u002Fclient.ts` | Pending Map、指数退避重连、Tick 心跳监视、seq 间隙检测 | `client.ts` |\n| **CLI** | `gateway\u002Fgateway-cli.ts` | serve\u002Fconnect 双模式 CLI 入口 | `cli\u002Fgateway-cli.ts` |\n\n---\n\n## 核心设计解析\n\n### 1. Agent Loop — 双层循环 + EventStream\n\n**问题**：简单 while 循环无法处理 follow-up、steering injection、上下文溢出等复杂场景。\n\n**openclaw 方案**：双层循环 + EventStream 事件流\n\n```typescript\n\u002F\u002F agent-loop.ts — 返回 EventStream，IIFE 推送事件\nfunction runAgentLoop(params): EventStream\u003CMiniAgentEvent, MiniAgentResult> {\n  const stream = createMiniAgentStream();\n\n  (async () => {\n    \u002F\u002F outer loop: follow-up 循环（处理 end_turn \u002F tool_use 继续）\n    while (outerTurn \u003C maxOuterTurns) {\n      \u002F\u002F inner loop: 工具执行 + steering injection\n      \u002F\u002F stream.push({ type: \"tool_execution_start\", ... })\n    }\n    stream.end({ text, turns, toolCalls });\n  })();\n\n  return stream;  \u002F\u002F 调用方 for-await 消费\n}\n```\n\n**事件订阅**（对齐 pi-agent-core `Agent.subscribe`）：\n\n```typescript\nconst agent = new Agent({ apiKey, provider: \"anthropic\" });\n\nconst unsubscribe = agent.subscribe((event) => {\n  switch (event.type) {\n    case \"message_delta\":  \u002F\u002F 流式文本\n      process.stdout.write(event.delta);\n      break;\n    case \"tool_execution_start\":  \u002F\u002F 工具开始\n      console.log(`[${event.toolName}]`, event.args);\n      break;\n    case \"agent_error\":  \u002F\u002F 运行错误\n      console.error(event.error);\n      break;\n  }\n});\n\nconst result = await agent.run(sessionKey, \"列出当前目录的文件\");\nunsubscribe();\n```\n\n### 2. 会话管理器 — JSONL 持久化\n\n**问题**：Agent 重启后如何恢复对话上下文？\n\n```typescript\n\u002F\u002F session.ts — 双写策略: 内存缓存 + 磁盘持久化\nasync append(sessionKey: string, message: Message): Promise\u003Cvoid> {\n  \u002F\u002F 1. 内存缓存立即更新（读取零 I\u002FO）\n  state.entries.push(entry);\n\n  \u002F\u002F 2. 首条 assistant 消息后才落盘（避免空会话写磁盘）\n  if (!state.hasAssistant && message.role === \"assistant\") {\n    state.hasAssistant = true;\n    await rewriteSessionFile(state); \u002F\u002F 首次: 完整写入 header + entries\n  } else if (state.hasAssistant) {\n    await fs.appendFile(filePath, line); \u002F\u002F 后续: O(1) 追加\n  }\n}\n```\n\nJSONL 格式：每行一条 entry，损坏行跳过不影响其他数据。写锁防并发。\n\n### 3. 上下文 — 加载 + 裁剪 + 摘要压缩\n\n**问题**：上下文窗口有限，如何在不丢失关键信息的情况下控制大小？\n\n三层递进策略：\n1. **Pruning** — 裁剪旧的 tool_result（保留最近 N 条完整）\n2. **Compaction** — 超过阈值后，旧消息压缩为\"历史摘要\"\n3. **Bootstrap** — 按需加载 AGENTS.md 等配置文件（超长文件 head+tail 截断）\n\n### 4. 记忆 — 长期记忆 (扩展层)\n\n**问题**：如何让 Agent \"记住\"跨会话的信息？\n\n```typescript\n\u002F\u002F memory.ts — 关键词匹配 + 纯相关性排序（无时间衰减）\nasync search(query: string, limit = 5): Promise\u003CMemorySearchResult[]> {\n  const queryTerms = query.toLowerCase().split(\u002F\\s+\u002F);\n  for (const entry of this.entries) {\n    let score = 0;\n    for (const term of queryTerms) {\n      if (text.includes(term)) score += 1;\n      if (entry.tags.some(t => t.includes(term))) score += 0.5;\n    }\n  }\n}\n```\n\nopenclaw 用 SQLite-vec 做向量语义搜索 + BM25 关键词搜索，本项目简化为纯关键词相关性检索，不引入时间衰减。\n\n### 5. 心跳 — 主动唤醒 (扩展层)\n\n**问题**：Agent 如何\"主动\"工作，而不只是被动响应？\n\n两层架构：\n- **HeartbeatWake**（请求合并层）：多来源触发 (interval\u002Fcron\u002Fexec\u002Frequested) → 250ms 合并窗口 → 双重缓冲\n- **HeartbeatRunner**（调度层）：活跃时间检查 → HEARTBEAT.md 解析 → 空内容跳过 → 重复抑制\n\n| 设计点 | 为什么这样做 |\n|--------|-------------|\n| setTimeout 而非 setInterval | 精确计算下次运行时间，避免漂移 |\n| 250ms 合并窗口 | 防止多个事件同时触发 |\n| 双重缓冲 | 运行中收到新请求不丢失 |\n| 重复抑制 | 24h 内相同消息不重复发送 |\n\n### 6. 网关 — WebSocket RPC 网关 (网关层)\n\n**问题**：Agent 只能通过 CLI 本地使用，如何让多个客户端通过网络共享同一个 Agent？\n\n**openclaw 方案**：WebSocket RPC + Pub\u002FSub 广播 + Challenge-Response 认证\n\n```\n终端 A ──┐                          ┌── broadcast ──→ 终端 A\n         ├── WebSocket ──→ Gateway ──┤\n终端 B ──┘       RPC       (Agent)  └── broadcast ──→ 终端 B\n```\n\n**12 个精华设计模式**（全部从 openclaw 源码提炼）：\n\n| 设计模式 | 文件 | 对齐 openclaw |\n|---------|------|--------------|\n| 协议帧 (req\u002Fres\u002Fevent 判别联合) | `protocol.ts` | `protocol\u002Fschema\u002Fframes.ts` |\n| Challenge-Response 握手 | `server.ts` | `server\u002Fws-connection.ts` |\n| Timing-safe token 比较 | `handlers.ts` | `auth.ts` safeEqual |\n| 方法路由 Handler Map | `handlers.ts` | `server-methods.ts` |\n| Pub\u002FSub 广播 + seq 递增 | `server.ts` | `server-broadcast.ts` |\n| `dropIfSlow` 分级背压 | `server.ts` | `server-broadcast.ts` |\n| Delta 限流 (150ms) | `handlers.ts` | `server-chat.ts` emitChatDelta |\n| Tick 心跳 30s | `server.ts` | `server-maintenance.ts` |\n| Pending Map + 超时 + flush | `client.ts` | `client.ts` |\n| Seq 间隙检测 | `client.ts` | `client.ts` onGap |\n| 指数退避重连 (1s→30s) | `client.ts` | `client.ts` scheduleReconnect |\n| Tick 心跳监视 (2 周期) | `client.ts` | `client.ts` startTickWatch |\n\n**握手流程**：\n\n```\nServer                              Client\n  │◄──── WebSocket 连接建立 ───────────│\n  ├─ Event: connect.challenge ───────►│  { nonce, ts }\n  │◄── Request: connect ─────────────┤  { token, nonce }\n  ├── 验证 token (timingSafeEqual)     │\n  ├─ Response: HelloOk ──────────────►│  { protocol, methods, events, policy }\n```\n\n**ACK-then-stream 模式**（聊天消息流转）：\n\n```typescript\n\u002F\u002F 客户端发送\nclient.request(\"chat.send\", { sessionKey: \"main\", message: \"hello\" });\n\u002F\u002F 服务端立即 ACK: { ok: true, payload: { sessionKey, runId } }\n\u002F\u002F 异步执行 agent.run()，事件流通过 broadcast 推送：\n\u002F\u002F   Event { event: \"chat\", payload: { state: \"delta\", text: \"...\" } }  ← 150ms 限流\n\u002F\u002F   Event { event: \"chat\", payload: { state: \"final\", text: \"...\" } }\n```\n\n---\n\n## 设计模式索引\n\n| 模式 | 所在文件 | 说明 |\n|------|----------|------|\n| EventStream 异步推拉 | `agent-events.ts` | push\u002FasyncIterator\u002Fend\u002Fresult |\n| Subscribe\u002FEmit 观察者 | `agent.ts` | listeners Set + subscribe 返回 unsubscribe |\n| 双层循环 | `agent-loop.ts` | outer (follow-up) + inner (tools+steering) |\n| JSONL 追加日志 | `session.ts` | 每行一条消息，追加写入 |\n| 三层递进裁剪 | `context\u002Fpruning.ts` | tool_result → assistant → 保留最近 |\n| 自适应分块摘要 | `context\u002Fcompaction.ts` | 按 token 分块，逐块摘要 |\n| 双重缓冲调度 | `heartbeat.ts` | running + scheduled 状态机 |\n| 三级编译策略 | `tool-policy.ts` | allow\u002Fdeny\u002Fnone → 过滤工具列表 |\n| Challenge-Response 握手 | `gateway\u002Fserver.ts` | nonce 挑战 → token 验证 → HelloOk |\n| Timing-safe 认证 | `gateway\u002Fhandlers.ts` | crypto.timingSafeEqual 防计时攻击 |\n| WebSocket RPC Pending Map | `gateway\u002Fclient.ts` | UUID id → Promise → 超时自动 reject |\n| Pub\u002FSub 广播 + 背压 | `gateway\u002Fserver.ts` | seq 递增 + dropIfSlow + 慢消费者检测 |\n| 指数退避重连 | `gateway\u002Fclient.ts` | 1s → 2s → 4s → ... → 30s，成功后重置 |\n| Tick 心跳监视 | `gateway\u002Fclient.ts` | 2 周期无 tick → 主动断开触发重连 |\n| Delta 限流 | `gateway\u002Fhandlers.ts` | 150ms 内最多广播一次，累积文本 |\n| ACK-then-stream | `gateway\u002Fhandlers.ts` | 立即响应 → 异步执行 → 事件流推送 |\n\n---\n\n## 快速开始\n\n要求：Node.js `>=20`\n\n在项目根目录执行：\n\n```bash\npnpm install\n```\n\n推荐用 `.env` 文件配置（项目启动时自动加载）：\n\n```env\nOPENCLAW_MINI_PROVIDER=anthropic\nOPENCLAW_MINI_MODEL=claude-sonnet-4-20250514\nOPENCLAW_MINI_BASE_URL=https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\nANTHROPIC_API_KEY=sk-xxx\n```\n\n```bash\npnpm dev\n```\n\n### 使用 OpenAI 兼容 API\n\n智谱、DeepSeek、月之暗面 Kimi 等国产大模型均兼容 OpenAI 格式，通过 `provider=openai` + 自定义 `BASE_URL` 即可接入。\n\n以智谱免费模型 GLM-4-Flash 为例：\n\n```env\nOPENCLAW_MINI_PROVIDER=openai\nOPENCLAW_MINI_MODEL=glm-4-flash\nOPENCLAW_MINI_BASE_URL=https:\u002F\u002Fopen.bigmodel.cn\u002Fapi\u002Fpaas\u002Fv4\nOPENCLAW_MINI_REASONING=none\nOPENAI_API_KEY=你的API Key\n```\n\n```bash\npnpm dev\n```\n\n> `OPENCLAW_MINI_REASONING=none` 用于关闭 extended thinking，不支持该特性的模型需设置此项。\n\n### 网关模式\n\n除了 CLI 直连，还可以通过 Gateway 服务让多个客户端远程访问同一个 Agent：\n\n```bash\n# 终端 1：启动 Gateway 服务\npnpm gateway\n\n# 终端 2：连接 Gateway\npnpm gateway:connect\n```\n\n可选参数：\n\n```bash\npnpm gateway -- --port 8080 --token mySecret    # 自定义端口和认证 token\npnpm gateway:connect -- --url ws:\u002F\u002Fremote:18789  # 连接远程 Gateway\npnpm gateway:connect -- --session work            # 指定会话名\n```\n\n客户端内命令：`\u002Fhealth` 查看状态、`\u002Fsessions` 列出会话、`\u002Fquit` 断开。\n\n也支持 CLI 参数：\n\n```bash\n# 直接使用 Anthropic\nANTHROPIC_API_KEY=sk-xxx pnpm dev\n\n# 指定 provider + model\npnpm dev -- --provider openai --model gpt-4o\n\n# 使用代理\npnpm dev -- --base-url https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\n\n# 关闭 extended thinking（不支持的模型需设置）\npnpm dev -- --reasoning none\n```\n\n## 使用示例\n\n先确认基础检查能通过：\n\n```bash\npnpm build\npnpm test\n```\n\n教学用示例：\n\n```bash\npnpm example:basic\npnpm example:custom-tools\npnpm example:gateway\n```\n\n```typescript\nimport { Agent } from \"openclaw-mini\";\n\nconst agent = new Agent({\n  provider: \"anthropic\",\n  baseUrl: \"https:\u002F\u002Fyour-proxy.com\u002Fapi\u002Fanthropic\", \u002F\u002F 可选，代理\u002F自部署端点\n  \u002F\u002F apiKey 不传则自动从环境变量读取\n  agentId: \"main\",\n  workspaceDir: process.cwd(),\n  reasoning: \"medium\", \u002F\u002F 默认开启 extended thinking (minimal\u002Flow\u002Fmedium\u002Fhigh\u002Fxhigh)\n});\n\n\u002F\u002F 事件订阅\nconst unsubscribe = agent.subscribe((event) => {\n  switch (event.type) {\n    case \"thinking_delta\": \u002F\u002F 流式思考\n      process.stdout.write(event.delta);\n      break;\n    case \"message_delta\": \u002F\u002F 流式文本\n      process.stdout.write(event.delta);\n      break;\n    case \"tool_execution_start\":\n      console.log(`[${event.toolName}]`, event.args);\n      break;\n  }\n});\n\nconst result = await agent.run(\"session-1\", \"请列出当前目录的文件\");\nconsole.log(`${result.turns} 轮, ${result.toolCalls} 次工具调用`);\n\nunsubscribe();\n```\n\n## 学习路径建议\n\n1. **核心层优先**：`agent-loop.ts` → `agent.ts` → `agent-events.ts` → `session.ts` → `context\u002F`\n2. **理解事件流**：subscribe\u002Femit 模式 + EventStream 异步推拉\n3. **扩展层选读**：`memory.ts` → `skills.ts` → `heartbeat.ts`（按兴趣）\n4. **网关层进阶**：`gateway\u002Fprotocol.ts` → `gateway\u002Fserver.ts` → `gateway\u002Fhandlers.ts` → `gateway\u002Fclient.ts`\n5. **对照 openclaw 源码**：验证简化版是否抓住了核心\n6. **工程层跳过**：除非你在做生产级 Agent，否则不需要关注\n\n## 许可证\n\nMIT","# OpenClaw Mini 快速上手指南\n\nOpenClaw Mini 是 OpenClaw 核心架构的精简复现版，专为学习 AI Agent 的系统级设计而打造。它剥离了生产环境的复杂防护与兼容性细节，保留了 **Agent Loop（双层循环）**、**Session 持久化**、**Context 管理** 及 **Gateway 网关** 等核心设计主线，帮助开发者在 20 分钟内理解“有记忆、能主动唤醒”的 AI 系统架构。\n\n## 1. 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: 版本 `>=20` (推荐使用 nvm 或 fnm 管理)\n*   **包管理器**: 推荐安装 [pnpm](https:\u002F\u002Fpnpm.io)，本项目对 pnpm 支持最佳。\n    ```bash\n    npm install -g pnpm\n    ```\n*   **代码编辑器**: VS Code 或其他支持 TypeScript 的编辑器。\n*   **模型密钥**: 需准备一个可用的 LLM API Key（支持 Anthropic, OpenAI 兼容接口如智谱、DeepSeek、Kimi 等）。\n\n## 2. 安装步骤\n\n### 克隆项目\n从 GitHub 获取源码并进入目录：\n\n```bash\ngit clone git@github.com:voocel\u002Fopenclaw-mini.git\ncd openclaw-mini\n```\n\n> 💡 **国内加速提示**：如果克隆速度较慢，可使用国内镜像源：\n> `git clone https:\u002F\u002Fgitee.com\u002Fvoocel\u002Fopenclaw-mini.git` (如有镜像) 或使用 `git clone https:\u002F\u002Fghproxy.com\u002Fhttps:\u002F\u002Fgithub.com\u002Fvoocel\u002Fopenclaw-mini.git`\n\n### 安装依赖\n使用 pnpm 安装项目依赖：\n\n```bash\npnpm install\n```\n\n### 配置环境变量\n复制示例配置文件并编辑：\n\n```bash\ncp .env.example .env\n```\n\n使用编辑器打开 `.env` 文件，根据您的模型提供商填入配置。\n\n**方案 A：使用 Anthropic (Claude)**\n```env\nOPENCLAW_MINI_PROVIDER=anthropic\nOPENCLAW_MINI_MODEL=claude-sonnet-4-20250514\nANTHROPIC_API_KEY=sk-ant-xxx\n```\n\n**方案 B：使用国产大模型 (智谱\u002FDeepSeek\u002FKimi 等 OpenAI 兼容接口)**\n以智谱 GLM-4-Flash 为例：\n```env\nOPENCLAW_MINI_PROVIDER=openai\nOPENCLAW_MINI_MODEL=glm-4-flash\nOPENCLAW_MINI_BASE_URL=https:\u002F\u002Fopen.bigmodel.cn\u002Fapi\u002Fpaas\u002Fv4\nOPENCLAW_MINI_REASONING=none\nOPENAI_API_KEY=your_api_key_here\n```\n> 注意：若模型不支持 extended thinking 特性，务必设置 `OPENCLAW_MINI_REASONING=none`。\n\n### 运行校验\n执行测试以确保环境配置正确：\n\n```bash\npnpm test\n```\n\n## 3. 基本使用\n\n### 启动本地 CLI Agent\n配置完成后，直接运行开发模式启动交互式命令行 Agent：\n\n```bash\npnpm dev\n```\n\n启动后，您可以在终端直接与 Agent 对话。它将展示完整的 **EventStream** 流程，包括思考过程、工具调用（如读取文件、执行命令）及最终回复。\n\n**示例交互：**\n```text\n> 列出当前目录下的所有文件\n[Tool: list_files] Executing...\n[Event: message_delta] 正在分析目录结构...\n[Event: message_delta] 当前目录包含以下文件：...\n```\n\n### 体验 Gateway 网关模式 (进阶)\n若想观察 Agent 如何作为网络服务运行（WebSocket RPC），可运行网关示例，查看 **ACK-then-stream** 链路：\n\n```bash\npnpm example:gateway\n```\n\n此模式演示了如何将 CLI 直连升级为支持多客户端连接的远程服务，包含握手认证、事件广播及背压控制等生产级设计。\n\n### 开发与构建\n如果您希望基于此项目进行二次开发：\n\n```bash\n# 本地开发监听\npnpm dev\n\n# 构建生产版本\npnpm build\n\n# 发布前自检 (测试 + 构建 + 打包检查)\npnpm test && pnpx build && pnpm pack:check\n```\n\n---\n**下一步学习建议**：\n项目代码按 **核心层 (Core) → 扩展层 (Extended) → 网关层 (Gateway)** 分层。建议优先阅读 `src\u002Fagent-loop.ts` 理解双层循环设计，以及 `src\u002Fsession.ts` 学习 JSONL 持久化机制。","某全栈开发者正在构建一个需要长期运行、具备跨会话记忆能力且能主动响应的智能运维助手。\n\n### 没有 openclaw-mini 时\n- **记忆断层严重**：AI 仅作为无状态函数映射，每次新对话都丢失历史上下文，无法记住之前的故障排查记录或用户偏好。\n- **上下文失控**：缺乏智能裁剪与摘要压缩机制，长对话迅速耗尽 Token 限额，导致关键信息被截断或报错。\n- **被动响应局限**：系统只能“问一句答一句”，无法通过心跳机制主动唤醒去监控服务器状态或推送预警。\n- **架构黑盒难扩**：网上教程多只展示简单的 Agent 循环代码，缺乏会话持久化、工具串行等生产级设计参考，二次开发极易踩坑。\n- **多模型适配繁琐**：切换不同大模型提供商时需重写大量底层逻辑，缺乏统一的适配层来屏蔽差异。\n\n### 使用 openclaw-mini 后\n- **会话持续演化**：借助 sessionKey 与会话持久化（JSONL），AI 能像“生命系统”一样保留长期记忆，精准关联历史运维事件。\n- **上下文自适应**：内置三层递进裁剪与分块摘要压缩，自动优化上下文窗口，确保在有限 Token 内保留最核心的诊断信息。\n- **主动服务能力**：利用可扩展技能与主动心跳唤醒机制，助手能定时巡检并在发现异常时主动发起对话通知开发者。\n- **透明架构指引**：四层模块化设计（核心\u002F扩展\u002F网关\u002F工程）清晰展示了从 CLI 到 EventStream 的完整链路，让复杂系统变得可读、可改。\n- **无缝模型切换**：通过统一的 Provider 适配层，可轻松在 OpenAI、Anthropic 等 22+ 提供商间切换，无需改动业务逻辑。\n\nopenclaw-mini 将原本脆弱的脚本式 AI 升级为具备记忆、主动性与工程鲁棒性的真正智能体系统。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fvoocel_openclaw-mini_1309cb6f.png","voocel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fvoocel_c1cc0f27.jpg","Just start off without any hesitation",null,"Chengdu","voocel@gmail.com","https:\u002F\u002Fwww.voocel.com","https:\u002F\u002Fgithub.com\u002Fvoocel",[82,86],{"name":83,"color":84,"percentage":85},"TypeScript","#3178c6",92.2,{"name":87,"color":88,"percentage":89},"JavaScript","#f1e05a",7.8,665,86,"2026-04-19T14:25:35","MIT","Linux, macOS, Windows","未说明 (基于 Node.js 运行，通常无需专用 GPU，依赖远程 API)","未说明",{"notes":98,"python":99,"dependencies":100},"该项目是基于 TypeScript\u002FNode.js 的轻量级 AI Agent 框架复现，非本地大模型推理工具。运行需安装 Node.js 20+ 和 ppm 包管理器。核心功能依赖配置外部大模型 API Key（如 Anthropic, OpenAI 或兼容接口），无需本地下载大型模型文件或配置 CUDA 环境。","不需要 (基于 Node.js)",[101,102],"Node.js >= 20","pnpm",[14,15,13],[105,106,107,6],"agent","ai","clawdbot","2026-03-27T02:49:30.150509","2026-04-20T19:23:49.186708",[111,116],{"id":112,"question_zh":113,"answer_zh":114,"source_url":115},45618,"运行示例时提示找不到文件路径（examples\u002Fopenclaw-mini no such file path）怎么办？","该问题通常是因为当前工作目录不正确导致的。请确保您在项目的根目录下运行命令，或者检查并更新您的当前目录路径。维护者已确认这是目录路径问题并已更新相关说明。","https:\u002F\u002Fgithub.com\u002Fvoocel\u002Fopenclaw-mini\u002Fissues\u002F5",{"id":117,"question_zh":118,"answer_zh":119,"source_url":120},45619,"如何配置并使用智谱（Zhipu）的免费 API（如 GLM-4-flash）？","无需专门的智谱配置示例，项目原生支持。您只需将配置文件中的 `provider` 设置为 `openai`，然后将 API 地址（base_url）填写为智谱的接口地址，并将 `api_key` 填写为您的智谱 API Key 即可正常使用。","https:\u002F\u002Fgithub.com\u002Fvoocel\u002Fopenclaw-mini\u002Fissues\u002F6",[]]