企业官网建设流程全解析

HelloClaw：基于 hello-agents 构建的个性化 AI Agent 实战解析

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents

HelloClaw 是 hello-agents 社区共创项目中的一个完整示例：它基于 hello-agents 的SimpleAgent框架，实现了支持身份定制、长期/每日双轨记忆、真正的流式工具调用、多会话持久化与 Vue3 + FastAPI 全栈界面的个性化 AI 助手。阅读本文后，你将掌握如何继承 hello-agents 框架核心类做深度扩展、如何设计"以 Markdown 文件为配置中心"的 Agent 工作空间、如何用 SSE 把 ReAct 式工具调用流程流式呈现给前端，以及如何构建一套规则驱动的自动记忆捕获与上下文保护机制。

项目定位与核心特性

HelloClaw 由社区开发者 tino-chen 基于 hello-agents 框架构建，目标类似于一个"认识你、记住你、随需求不断成长"的个性化 AI 伙伴，而不是一个普通的问答机器人。项目官方 README 中明确列出的核心能力包括：

• 智能对话：基于 ReActAgent / SimpleAgent 的推理对话能力；
• 记忆系统：长期记忆（MEMORY.md）与按日期组织的每日记忆自动管理；
• 工具调用：内置文件读写、命令执行、网页搜索、网页抓取等多种工具；
• 会话管理：多会话支持与会话历史持久化；
• 身份定制：通过 Markdown 配置文件自定义 Agent 身份与个性；
• 流式输出：基于 SSE 的实时回复与工具调用状态推送；
• Web 界面：Vue3 + TypeScript + Ant Design Vue 现代化前端。

从项目结构看，其技术选型可以归纳为一张清晰的表：

后端入口与 Agent 封装集中在 src/agent（helloclaw_agent.py、enhanced_simple_agent.py、enhanced_llm.py），FastAPI 路由位于 src/api，前端页面位于 frontend/src/views。

快速开始：从安装到跑通对话

环境要求

• Python 3.10+；
• Node.js 18+（仅在运行 Web 前端时需要）；
• 一个 OpenAI 兼容的 API 服务（README 中提到如智谱 AI、ModelScope 等）。

安装依赖与启动

后端依赖由 requirements.txt 声明，核心包括hello-agents>=1.0.0、fastapi>=0.109.0、uvicorn[standard]>=0.27.0、sse-starlette>=2.0.0、python-dotenv、pydantic>=2.0.0、click、rich、httpx[socks]等。

# 安装 Python 依赖 pip install -r requirements.txt

运行方式有两种：

方式一：Jupyter Notebook（推荐用于快速演示）

jupyter lab # 打开 main.ipynb 并运行

方式二：运行完整 Web 服务

# 启动后端 cd Co-creation-projects/tino-chen-HelloClaw pip install uvicorn uvicorn src.main:app --reload --port 8000 # 启动前端（新终端） cd frontend npm install npm run dev

前端默认运行在 http://localhost:5173（Vite 开发服务器，端口可在 frontend/vite.config.ts 中调整），通过代理访问后端的 8000 端口。

LLM 配置：四种来源的优先级

HelloClaw 的模型配置不采用单一入口，而是按照"构造函数参数 >~/.helloclaw/config.json> 环境变量 > 默认值"的优先级解析，这一点在 src/agent/helloclaw_agent.py 的_init_llm和 src/workspace/manager.py 的get_llm_config中都有直接体现：

• 全局配置文件位于~/.helloclaw/config.json，结构为{"llm": {"model_id": "", "api_key": "", "base_url": ""}}（模板见 src/workspace/templates/config.json）；
• 环境变量为LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL；
• 默认模型为glm-4。

HelloClawAgent的构造函数还直接暴露了workspace_path、name、model_id、api_key、base_url、max_tool_iterations（默认 10）等参数，便于在代码中覆盖配置。特别值得一提的是热加载：每次chat()/achat()调用前都会执行_reload_llm_if_changed()（helloclaw_agent.py），对比config.json中的模型配置与当前实例是否一致，不一致则重建 LLM 并替换_agent.llm引用，因此修改配置文件无需重启服务即可生效。

工作空间：以 Markdown 文件为配置中心的身份定制体系

HelloClaw 最具特色的设计是"工作空间（Workspace）"：所有身份、记忆、系统提示词都以普通 Markdown 文件存放在~/.helloclaw/workspace/下，由 WorkspaceManager 统一管理。目录布局如下：

~/.helloclaw/ ├── config.json # 全局 LLM 配置 └── workspace/ # Agent 工作空间 ├── IDENTITY.md # 身份配置（名称、物种、风格、表情符号、头像） ├── MEMORY.md # 长期记忆 ├── SOUL.md # 灵魂/个性 ├── USER.md # 用户信息 ├── AGENTS.md # 系统提示词（必须存在） ├── BOOTSTRAP.md # 入职引导（身份确定后自动删除） ├── HEARTBEAT.md # 心跳配置 ├── memory/ # 每日记忆（YYYY-MM-DD.md） └── sessions/ # 会话历史（JSON）

WorkspaceManager在初始化时会通过ensure_workspace_exists()自动创建上述目录，并从 src/workspace/templates 读取模板生成缺失的配置文件（CONFIG_FILES列表见 manager.py）。它还提供完整的配置读写 API：load_config/save_config/list_configs，以及记忆与会话的增删查改方法。

系统提示词的动态拼装

HelloClawAgent._build_system_prompt()（helloclaw_agent.py）以AGENTS.md为基础提示词，然后按以下顺序把其他配置文件拼接为上下文：

1. 若入职未完成（BOOTSTRAP.md仍存在），注入## 初始化引导内容；
2. 注入## 你的身份信息（IDENTITY）；
3. 注入## 用户信息（USER）；
4. 注入## 人格模板（SOUL）；
5. 注入## 长期记忆（MEMORY）。

由于每次对话都会重建系统提示词，因此编辑任何一个 Markdown 配置文件都会在下一次对话中立即生效，这正是"热加载配置"的另一层含义。

入职（Onboarding）机制

工作空间还内置了一套新颖的"入职"流程：当用户还没有告诉 Agent 它是什么时，BOOTSTRAP.md会作为引导脚本注入系统提示词，引导 Agent 与用户聊天、弄清自己的名字、物种、风格、表情符号，并写入IDENTITY.md与USER.md。BOOTSTRAP.md 模板 中甚至有"完成之后删除这个文件，你不再需要引导脚本了"的设计。

实现上，_is_identity_established()（manager.py）通过正则\*\*名称[：:]\*\*\s*(.+?)(?:\n|$)解析IDENTITY.md中的"名称"字段：只要名称非空、不以_开头、不包含"选一个"或"（"等占位符特征，就判定身份已确立，并自动删除BOOTSTRAP.md。Agent 自身的名字也会在初始化时用同样的解析逻辑从IDENTITY.md读取（helloclaw_agent.py），未设置时回退到HelloClaw。

增强版流式工具调用：从"流式文本"到"流式工具"

README 强调 HelloClaw 的技术亮点之一是"真正的流式工具调用——不是简单的流式文本输出，而是完整的流式工具调用流程"。这一能力由两个自研类协作完成，代码分别在：

• src/agent/enhanced_llm.py：EnhancedHelloAgentsLLM，继承 hello-agents 的HelloAgentsLLM；
• src/agent/enhanced_simple_agent.py：EnhancedSimpleAgent，继承 hello-agents 的SimpleAgent。

底层：流式 Function Calling 的统一事件模型

EnhancedHelloAgentsLLM.astream_invoke_with_tools()（enhanced_llm.py）直接使用openai.AsyncOpenAI客户端发起stream=True的 chat completions 请求，并把响应流统一封装为四种StreamToolEventType（定义见 enhanced_llm.py）：

每个 delta 分片都会同步累积进StreamToolCallResult对象（提供add_content、add_tool_call_start、add_tool_call_delta等方法，enhanced_llm.py），最终通过get_last_stream_tool_result()取回完整结果。该结果可以转换为符合 OpenAI 规范的 assistant 消息（to_assistant_message()），包含tool_calls数组，可直接追加回消息历史，供下一轮迭代继续使用。

上层：Agent 循环中的工具调用编排

EnhancedSimpleAgent.arun_stream_with_tools()（enhanced_simple_agent.py）实现了一个完整的 ReAct 式循环：

1. 发送AGENT_START/STEP_START事件；
2. 调用llm.astream_invoke_with_tools(messages, tools, tool_choice="auto")，把CONTENT事件转发为LLM_CHUNK实时推给前端；
3. 从累积结果中取出get_complete_tool_calls()；若没有工具调用，则直接产出最终回答并跳出循环；
4. 若有工具调用，把 assistant 消息追加到消息历史，逐个执行工具，并在执行前后分别发出TOOL_CALL_START与TOOL_CALL_FINISH事件（其中await asyncio.sleep(0)用于让出控制权，确保 SSE 先推送 start 事件再执行工具）；
5. 工具结果以role: "tool"消息回填到历史，进入下一轮迭代，直到达到max_tool_iterations（默认 10）；
6. 若达到上限仍未结束，会再调用一次astream_invoke兜底获取最终回答。

该 Agent 还做了良好的降级处理：如果传入的是普通HelloAgentsLLM（不支持流式工具调用），会发出UserWarning并回退到基类SimpleAgent.run()的非流式同步模式（enhanced_simple_agent.py）；纯对话场景（无工具）则走_stream_without_tools()直接流式输出文本。

SSE 透传：从 Agent 事件到前端消息

后端通过 src/api/chat.py 的POST /chat/send/stream接口，用sse-starlette的EventSourceResponse把 Agent 事件逐条映射为 SSE 事件：session、step_start、chunk、tool_start、tool_finish、step_finish、done、error。前端收到tool_start时即可渲染"正在调用工具 X"的状态卡片，收到chunk时增量渲染文本，实现接近 ChatGPT 的实时交互体验。

记忆系统：长期记忆、每日记忆与上下文保护

HelloClaw 的记忆体系是"文件即记忆"思想的具体实现，核心模块位于 src/memory：

• 长期记忆MEMORY.md：跨会话持久保存的重要信息，通过MemoryTool的memory_update_longterm动作追加内容；
• 每日记忆memory/YYYY-MM-DD.md：按日期自动分类，通过memory_add动作或自动捕获写入；
• Memory Flush：上下文接近压缩阈值时自动提醒 Agent 保存重要信息。

MemoryCaptureManager：规则驱动的自动记忆捕获

src/memory/capture.py 定义了一套中文友好的触发正则（MEMORY_TRIGGERS），将信息自动归类为四类：

处理流程为：按中英文句号/问号/感叹号/换行切分句子 → 匹配触发规则获取分类 → 清理前缀（用户/我/你/assistant/user:）与引号 → 偏好类统一补上"用户"主语 → 与已有记忆做去重（WorkspaceManager.check_duplicate_memory通过中文停用词过滤 + 关键词重叠率计算，默认阈值 0.7）→ 以- [category] content的带标签格式追加到当日记忆文件（manager.py）。整个捕获在achat()的对话流程末尾异步执行（_capture_memories，helloclaw_agent.py），不阻塞用户。

MemoryFlushManager：压缩前的"最后抢救"

src/memory/memory_flush.py 实现触发判定：当估算 token 数达到context_window × compression_threshold − soft_threshold_tokens时触发。在HelloClawAgent中对应的配置为context_window=128000、compression_threshold=0.8、soft_threshold_tokens=4000，即约 98400 token 时触发。

触发后，Agent 会执行一个对用户不可见的静默回合（_check_and_run_memory_flush，helloclaw_agent.py），注入get_flush_prompt()生成的提示词，指示 Agent 用memory_add把重要事实/决策/偏好写入当日记忆、用memory_update_longterm写入长期记忆；若没有值得保存的内容，则回复[SILENT]，由is_silent_response()识别后跳过。token 估算采用"字符数 / 3"的保守近似（_estimate_tokens，helloclaw_agent.py），兼顾中英文差异。

MemoryTool：让 Agent 自己管理记忆

src/tools/builtin/memory.py 定义了一个可展开（expandable=True）的MemoryTool，为 LLM 暴露了五个记忆动作：

• memory_search：按关键词搜索长期/每日记忆，返回带行号与上下文的代码块格式（复用search_memory_enhanced）；
• memory_get：读取指定记忆文件或行范围（如lines="10-20"）；
• memory_add：向今日记忆追加内容，可选preference/decision/entity/fact分类；
• memory_update_longterm：向MEMORY.md追加长期记忆；
• memory_list/memory_cleanup：列出记忆文件、按天数（默认 30 天）清理过期每日记忆。

工具集：内置工具与安全边界

HelloClawAgent._setup_tools()（helloclaw_agent.py）将 hello-agents 内置工具与 HelloClaw 自定义工具注册到同一个ToolRegistry：

其中ExecuteCommandTool（src/tools/builtin/execute_command.py）值得单独说明，它体现了 Agent 工具的安全设计：

• 命令白名单：仅允许ls、cat、echo、pwd、git、npm、pnpm、uv、python、node、pip、mkdir、grep、find、head、tail等基础命令（execute_command.py）；
• 危险模式拦截：用正则拦截rm -rf、sudo、chmod 777、mkfs、dd if=、shutdown、reboot、fork 炸弹等（execute_command.py）；
• 目录限制：在HelloClawAgent中构造时传入allowed_directories=[workspace_path]，把命令执行限制在工作空间内（_validate_workdir用startswith做路径前缀校验）；
• 超时与输出截断：默认 30 秒超时，输出超过 10000 字符自动截断并标注。

会话管理：持久化与多会话

会话由 hello-agents 框架层的Config启用（session_enabled=True、session_dir=workspace/sessions），每次对话结束后通过save_session落盘为 JSON。HelloClawAgent在此基础上封装了完整的管理 API（helloclaw_agent.py）：

• create_session()：生成 8 位 UUID 会话 ID；
• list_sessions()：按最后更新时间倒序列出所有会话；
• delete_session()/get_session_history()：删除会话、读取历史（支持user/assistant/tool三种角色，并保留metadata中的tool_calls）；
• 会话历史中还记录了完整工具调用记录（工具名、参数、结果、状态），前端 SessionsView.vue 与 MemoryView.vue 可分别展示会话列表与记忆文件。

每次对话的调用链还会做两件"保洁"工作：LLM 调用参数固定加入frequency_penalty=0.5与presence_penalty=0.3，用于降低重复、鼓励新话题（helloclaw_agent.py）。

使用示例：同步对话与流式对话

基础对话（同步）

from src.agent.helloclaw_agent import HelloClawAgent # 创建 Agent agent = HelloClawAgent() # 同步对话 response = agent.chat("你好，请介绍一下你自己") print(response)

流式对话（异步）

import asyncio async def chat_stream(): agent = HelloClawAgent() async for event in agent.achat("帮我搜索一下今天的新闻"): if event.type.value == "llm_chunk": print(event.data.get("chunk", ""), end="", flush=True) elif event.type.value == "tool_call_start": print(f"\n[调用工具: {event.data.get('tool_name')}]") elif event.type.value == "tool_call_finish": print(f"[工具执行完成]") asyncio.run(chat_stream())

流式事件的核心是StreamEventType枚举（AGENT_START/STEP_START/LLM_CHUNK/TOOL_CALL_START/TOOL_CALL_FINISH/STEP_FINISH/AGENT_FINISH/ERROR），无论是 Python 客户端直接消费还是经 src/api/chat.py 的 SSE 接口透传给浏览器，遵循的都是同一套事件契约。

项目结构速览

Co-creation-projects/tino-chen-HelloClaw/ ├── README.md # 项目说明文档 ├── requirements.txt # Python 依赖列表 ├── main.ipynb # 快速演示 Notebook ├── data/ # 数据文件 ├── outputs/helloclaw.png # 项目界面截图 ├── src/ # 后端源代码 │ ├── agent/ # Agent 封装（helloclaw_agent / enhanced_simple_agent / enhanced_llm） │ ├── tools/builtin/ # 自定义工具（memory / execute_command / web_search / web_fetch） │ ├── memory/ # 记忆管理（capture / memory_flush / session_summarizer） │ ├── workspace/ # 工作空间管理（manager + templates） │ ├── api/ # FastAPI 路由（chat / session / config / memory） │ ├── cli/ # CLI 入口 │ └── channels/ # 渠道封装（cli_channel） └── frontend/ # Vue3 前端（views / components / api / router / stores）

小结与扩展方向

HelloClaw 完整地展示了"在 hello-agents 框架之上构建生产级个性化 Agent"的典型路径：用EnhancedHelloAgentsLLM+EnhancedSimpleAgent解决流式工具调用的体验问题；用WorkspaceManager+ Markdown 模板体系解决"Agent 人格/记忆可配置、可持久化、可热加载"的问题；用规则驱动 + 关键词重叠去重的轻量方案解决记忆自动捕获问题；用 Memory Flush 静默回合缓解长对话上下文压缩带来的信息丢失；再用 FastAPI + SSE + Vue3 把整个流程变成可交互的 Web 产品。

从项目结构看，作者还为后续演进预留了明确方向：多模态输入、更多内置工具（代码解释器、数据库查询等）、Agent 间协作与语音交互。如果你正在基于 hello-agents 做自己的 Agent 应用，这个仓库的工作空间设计、流式工具事件模型和记忆管理方案都值得直接借鉴。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents