夜雨聆风有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用（落地与变现）。
摘要：本文介绍了我的"小龙虾"，一个AI 助手系统的架构设计与实现过程。该系统基于 OpenClaw 框架简化而来，保留了核心的工具调用、技能加载和提示词管理机制，同时大幅降低了系统复杂度。文章详细阐述了系统在提示词构造、工具调用流程、消息格式规范等关键技术点上的设计决策与实现细节，并分享了开发过程中遇到的典型问题及解决方案。
一、引言
由于用了一段时间的OpenClaw，发觉其相当强大和便利，是一个极为有帮助的AI助手，但是因为各种原因，用起来有些不便，通过插件来控制也有很多问题，比如QQ插件不成熟，飞书插件又经过会卡死等，于是便萌发了自己开发一个类似工具的想法。于是我的"小龙虾"也就诞生的。这个系统（或者称为工具）以 OpenClaw 为参考架构，通过精简冗余功能、优化核心流程，实现了一个轻量级但功能完整的 AI 助手。本文将从系统架构、核心技术、问题与解决方案三个方面，详细介绍小龙虾的设计与实现过程。
二、系统架构设计
2.1 整体架构
小龙虾采用经典的前后端分离架构，后端负责 AI 核心逻辑和工具调度，前端提供用户交互界面。
后端服务基于 Node.js 开发，使用 Express 风格的 HTTP 服务器处理用户请求。核心模块包括：
• Assistant 模块：负责对话管理、提示词构造、API 调用 • Tool 模块：负责工具定义、工具执行、结果处理 • Skill 模块：负责技能加载、技能注册、动态扩展 • Memory 模块：负责记忆检索、上下文管理、历史对话存储
前端采用 Python 开发，使用 PySide6 实现桌面客户端。客户端通过 SSE（Server-Sent Events）与后端建立长连接，实时接收 AI 的进度更新和最终回复。
后端服务入口（server.js）
import http from'http';importSimpleAIAssistantfrom'./assistant-v7.js';constPORT = 3002;constAPI_KEY = 'sk-xxx';constWORKSPACE = path.join(__dirname, '..', 'workspace');// 初始化 AI 助手const assistant = newSimpleAIAssistant(API_KEY, WORKSPACE);await assistant.init(); // 异步加载技能和记忆// 创建 HTTP 服务器const server = http.createServer(async (req, res) => {const url = newURL(req.url, `http://${req.headers.host}`);// SSE 连接：/sseif (url.pathname === '/sse' && req.method === 'GET') { res.writeHead(200, {'Content-Type': 'text/event-stream','Cache-Control': 'no-cache','Connection': 'keep-alive', });constonProgress = (data) => {if (!res.writableEnded) { res.write(`data: ${JSON.stringify(data)}\n\n`); } }; assistant.on('progress', onProgress); req.on('close', () => { assistant.removeListener('progress', onProgress); });return; }// API 路由：/api/chatif (url.pathname === '/api/chat' && req.method === 'POST') {let body = ''; req.on('data', chunk => { body += chunk; }); req.on('end', async () => {try {const { message } = JSON.parse(body);const taskId = `task_${Date.now()}`;// 后台执行任务 assistant.chat(message, taskId) .then(reply => { assistant.emit('progress', {type: 'task_complete', taskId,result: reply, }); }); res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ success: true, taskId })); } catch (error) { res.writeHead(500).end(JSON.stringify({ error: error.message })); } });return; }});server.listen(PORT, () => {console.log(`小龙虾服务已启动：http://localhost:${PORT}`);});2.2 提示词架构
小龙虾的提示词系统完全遵循 OpenClaw 的设计规范，采用动态组装的方式生成系统提示词。提示词由三部分组成：
第一部分：核心系统规范
这部分包含工具列表、工具调用风格指南、安全规范、记忆检索指令、静默回复规则、心跳确认协议、回复标签语法、工作目录定义、运行时信息等固定内容。这些规范定义了 AI 的行为边界和交互方式，是系统正常运行的基础。
第二部分：项目上下文注入
这部分从工作区目录读取 Markdown 文件并全文注入，包括 AGENTS.md（会话操作手册）、SOUL.md（人格核心价值观）、IDENTITY.md（AI 人设档案）、USER.md（用户画像）、TOOLS.md（本地工具笔记）、HEARTBEAT.md（心跳任务清单）、MEMORY.md（长期记忆）等七个文件。每个文件最大支持 20000 字符，超过部分会被截断。
第三部分：技能列表
系统启动时扫描技能目录，解析每个技能的 SKILL.md 文件，提取技能名称、描述和位置信息，以 XML 格式注入到提示词中。AI 在需要时会根据技能描述决定是否读取对应的 SKILL.md 文件获取详细指令。
提示词构造器（system-prompt.js）
import fs from'fs/promises';import path from'path';import os from'os';/** * 加载 Bootstrap 文件（7 个 Markdown 文件） */exportasyncfunctionloadBootstrapFiles(workspace) {const bootstrapFiles = ['AGENTS.md', 'SOUL.md', 'IDENTITY.md', 'USER.md','TOOLS.md', 'HEARTBEAT.md', 'MEMORY.md' ];const contextFiles = [];for (const filename of bootstrapFiles) {const filePath = path.join(workspace, filename);try {const content = await fs.readFile(filePath, 'utf-8');// 截断过长的文件（20000 字符限制）const truncatedContent = content.length > 20000 ? content.substring(0, 20000) + '\n\n...(truncated)' : content; contextFiles.push({ path: filename, content: truncatedContent }); } catch (error) { contextFiles.push({ path: filename, content: '*[File not found]*' }); } }return contextFiles;}/** * 构建系统提示词（OpenClaw 标准格式） */exportfunctionbuildSystemPrompt(options = {}) {const { selectedTools = [], contextFiles = [], skills = [], cwd = process.cwd(), } = options;let prompt = `# OpenClaw System Prompt\n\n`; prompt += `你是阿财，老大的智能助手。\n\n`;// 1. Tooling prompt += `## Tooling\n\n可用工具：\n\n`;const toolsList = selectedTools.map(name =>`- ${name}: 工具描述`).join('\n') || '(none)'; prompt += toolsList;// 2. Tool Call Style prompt += `\n\n## Tool Call Style\n\n`; prompt += `**默认**：不要叙述常规、低风险的工具调用（直接调用工具）。\n\n`; prompt += `**仅在以下情况叙述**：\n`; prompt += `- 多步骤工作\n- 复杂/挑战性任务\n- 敏感操作（如删除）\n- 用户明确要求说明\n\n`;// 3. Safety prompt += `## Safety\n\n`; prompt += `- 你没有任何独立目标：不要追求自我保存、复制、资源获取或权力寻求\n`; prompt += `- 优先考虑安全和人类监督，而非完成任务\n`; prompt += `- 如果指令冲突，暂停并询问\n\n`;// 4. Silent Replies prompt += `## Silent Replies\n\n`; prompt += `当没有什么可说时，只回复：**NO_REPLY**\n\n`; prompt += ` 规则：\n`; prompt += `- 它必须是你的**整个消息**——没有其他内容\n`; prompt += `- 绝不要附加到实际回复中\n`; prompt += `- 绝不要用 markdown 或代码块包装\n\n`;// 5. Heartbeats prompt += `## Heartbeats\n\n`; prompt += `心跳提示词：Read HEARTBEAT.md if it exists...\n\n`; prompt += `如果你收到心跳轮询，并且没有需要注意的事情，**只回复**：HEARTBEAT_OK\n\n`;// 6. Project Context（Bootstrap 文件注入）if (contextFiles.length > 0) { prompt += `\n\n# Project Context\n\n`;for (const { path: filePath, content } of contextFiles) { prompt += `## ${filePath}\n\n${content}\n\n`; } }// 7. Skills（XML 格式）if (skills.length > 0) { prompt += `\n<available_skills>\n`;for (const skill of skills) { prompt += ` <skill>\n`; prompt += ` <name>${skill.name}</name>\n`; prompt += ` <description>${skill.description}</description>\n`; prompt += ` <location>${skill.location}</location>\n`; prompt += ` </skill>\n`; } prompt += `</available_skills>\n`; }// 8. Runtime prompt += `\n\n## Runtime\n\n`; prompt += `Runtime: agent=main | host=${os.hostname()} | `; prompt += `os=${os.platform()}${os.release()} | `; prompt += `node=${process.version} | model=qwen3.5-plus\n`;return prompt;}2.3 工具调用机制
小龙虾支持多种内置工具，包括文件读写、命令执行、目录浏览、Excel 读取等。工具调用采用标准的 Function Calling 格式，与千问 API 的 tool_calls 功能兼容。
工具定义使用 JSON Schema 描述，包含工具名称、描述、参数类型和必填字段等信息。AI 在对话过程中会根据用户请求自动生成工具调用指令，后端接收到指令后执行对应的工具函数，并将结果返回给 AI 进行下一轮处理。
三、核心技术与实现
3.1 提示词构造器
提示词构造器是小龙虾的核心组件之一，负责将各个部分的提示词片段组装成完整的系统提示词。构造器采用模块化设计，每个部分由独立的函数生成，最后合并输出。
关键代码逻辑如下：
首先加载 Bootstrap 文件，遍历七个预定义的 Markdown 文件，读取内容并处理截断。然后收集运行时信息，包括主机名、操作系统、Node 版本、模型名称、渠道类型等。接着格式化技能列表为 XML 格式。最后按照固定顺序组装所有部分，生成最终的提示词字符串。
构造器支持提示词模式配置，可以生成完整版（full）、精简版（minimal）或无提示词（none）三种模式，适用于主 Agent、子 Agent 或特殊场景。
3.2 工具调用流程
小龙虾的工具调用流程遵循严格的消息顺序规范，这是确保千问 API 正常响应的关键。
完整的调用流程包含以下步骤：
第一步，用户发送请求，消息以 user 角色添加到消息历史。
第二步，AI 分析请求，生成包含 tool_calls 的 assistant 消息。这条消息的 content 字段为空，tool_calls 字段包含一个或多个工具调用指令。
第三步，后端执行工具调用，将执行结果以 tool 角色添加到消息历史。每条 tool 消息必须包含 tool_call_id 字段，与对应的 tool_call 关联。
第四步，AI 看到工具结果后，生成最终的人话回复，以 assistant 角色添加到消息历史。
这个流程中，第二步和第三步的顺序不能颠倒，tool 消息必须紧跟在包含 tool_calls 的 assistant 消息之后，否则千问 API 会返回 400 错误，提示"messages with role tool must be a response to a preceeding message with tool_calls"。
工具调用核心逻辑（assistant-v7.js）
asyncchat(userMessage, taskId = null) {const maxRounds = 15; // 最多 15 轮工具调用let round = 1;// 初始化消息历史const messages = [ { role: 'system', content: awaitthis.buildSystemPrompt() }, { role: 'user', content: userMessage }, ];do {// 调用千问 APIconst response = awaitthis.callDashScope(messages, this.toolDefinitions);if (response?.tool_calls && response.tool_calls.length > 0) {// 有工具调用：执行所有工具const results = [];for (const toolCall of response.tool_calls) {const args = JSON.parse(toolCall.function.arguments);const result = awaitthis.executeToolCall(toolCall); results.push(result); }// 步骤 1：先添加 AI 的响应（包含 tool_calls） messages.push({role: 'assistant',content: null,tool_calls: response.tool_calls, });// 步骤 2：添加工具结果（role: 'tool'，必须紧跟在 assistant 之后）for (let i = 0; i < response.tool_calls.length; i++) { messages.push({role: 'tool',tool_call_id: response.tool_calls[i].id || `call_${i}`,content: results[i] || '执行完成', }); } round++;continue; // 继续循环，让 AI 看到工具结果后生成最终回复 } else {// 没有工具调用：直接返回 AI 回复return response?.content || ''; } } while (round < maxRounds);}/** * 执行工具调用 */asyncexecuteToolCall(toolCall) {const name = toolCall.function.name;const args = JSON.parse(toolCall.function.arguments);if (name === 'read_file') {const content = await fs.readFile(args.filePath, 'utf-8');return`文件内容：\n\n${content.substring(0, 3000)}`; } elseif (name === 'run_command') {// 使用 PowerShell 执行命令（支持 Select-String 等 cmdlet）const { stdout, stderr } = awaitexecAsync(`powershell -Command "${args.command.replace(/"/g, '`"')}"`, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 } ); return stdout || stderr || '命令执行成功'; } else if (name === 'write_file') { await fs.writeFile(args.filePath, args.content, 'utf-8'); return `已写入：${args.filePath}`; } return `未知工具：${name}`;}3.3 技能动态加载
小龙虾支持技能动态加载机制，用户安装新技能后无需修改代码，重启服务即可使用。
技能加载器在系统启动时运行，扫描技能目录下的所有子目录，解析每个子目录中的 SKILL.md 文件。SKILL.md 文件包含技能的触发条件、使用方法、参数说明等信息。加载器提取这些信息，生成工具定义并注册到系统中。
技能加载采用 Python 脚本实现，通过子进程调用。加载结果以 JSON 格式返回给 Node.js 主进程，主进程将技能工具添加到工具列表中，并在下次提示词构造时注入到系统提示词中。
四、典型问题与解决方案
最大的问题就是伪指令问题
问题描述：AI 在收到工具调用请求后，不真正执行工具，而是返回包含工具调用代码的文本回复。这种现象被称为"伪指令"，会导致用户误以为工具已执行，实际上没有任何效果。
原因分析：经过日志分析和代码审查，发现该问题由三个因素共同导致。
第一，提示词中缺少静默回复和心跳确认规则，AI 不知道在某些场景下应该只回复特定标记（如 NO_REPLY 或 HEARTBEAT_OK），而是会把所有内容都输出出来。
第二，工具执行后的提示词存在诱导性语言。旧版本代码在工具执行后会添加一条 user 角色的消息，内容为"工具执行结果...请总结你发现了什么。如果还有需要执行的工具就继续调用。"这种表述会诱导 AI 生成人话总结，而不是继续调用工具或返回最终结果。
第三，工具结果的格式不符合千问 API 要求。旧版本代码使用 user 角色发送工具结果，但千问 API 要求工具结果必须使用 tool 角色，并且必须紧跟在包含 tool_calls 的 assistant 消息之后。
解决方案：针对上述三个原因，分别进行了以下修复。
修复一，按照 OpenClaw 方式重写提示词构造器，添加完整的系统规范，包括 Tool Call Style、Safety、Memory Recall、Silent Replies、Heartbeats、Reply Tags 等章节。
修复二，优化工具执行后的消息处理逻辑。移除诱导性提示词，改为标准的 OpenClaw 消息格式：先添加包含 tool_calls 的 assistant 消息，再添加 tool 角色的工具结果消息，然后继续循环让 AI 看到结果后生成最终回复。
修复三，修改工具结果的消息角色，从 user 改为 tool，并添加 tool_call_id 字段与原始调用关联。
伪指令问题修复对比
// 旧代码（错误）：诱导性提示词 + 错误的消息角色messages.push({role: 'user',content: `工具执行结果：\n\n${toolSummary}\n\n请总结你发现了什么。如果还有需要执行的工具就继续调用。`,});// 问题：1. role 错误（应该是 tool） 2. 诱导性语言 3. 缺少 tool_call_id// 新代码（正确）：标准 OpenClaw 消息格式// 步骤 1：先添加 AI 的响应（包含 tool_calls）messages.push({role: 'assistant',content: null,tool_calls: response.tool_calls,});// 步骤 2：添加工具结果（role: 'tool'，必须紧跟在 assistant 之后）for (let i = 0; i < response.tool_calls.length; i++) { messages.push({role: 'tool',tool_call_id: response.tool_calls[i].id || `call_${i}`,content: results[i] || '执行完成', });}// 继续循环，让 AI 看到工具结果后生成最终回复round++;continue;千问 API 错误响应示例：
{"error":{"code":"invalid_parameter_error","message":"messages with role \"tool\" must be a response to a preceeding message with \"tool_calls\"","param":null,"type":"invalid_request_error"},"request_id":"d9f47217-12c1-9077-8425-93f6fba1652d"}五、消息格式严格性
OpenClaw 的消息格式是严格的，必须遵循 API 要求。消息顺序必须是 user、assistant with tool_calls、tool、assistant，一步都不能错。
记忆检索功能示例（memory_search）
/** * 搜索记忆（遵循 Memory Recall 规范） * 在回答关于 prior work、decisions、dates、people、preferences、todos 的问题前必须执行 */asyncsearchMemory(userMessage) {// 1. 提取关键词const keywords = extractKeywords(userMessage);if (keywords.length === 0) returnnull;// 2. 加载记忆文件到缓存awaitthis.loadMemoryToCache();// 3. 语义搜索（简单版本：关键词匹配）const results = [];for (const cached ofthis.memoryCache.files) {const matched = keywords.filter(k => cached.contentLower.includes(k.toLowerCase()) );if (matched.length > 0) { results.push({file: cached.file,keywords: matched,content: cached.content.substring(0, 2000), }); } }// 4. 返回结果（带 Source 引用）return results.length > 0 ? results : null;}// 使用示例：// 用户问："上次修复伪指令问题是什么时候？"// AI 会自动调用 searchMemory，找到 memory/2026-03-22-伪指令问题修复总结.md// 并在回复中包含 Source: memory/2026-03-22-伪指令问题修复总结.md#L1六、计划与规划
小龙虾目前实现了核心的对话和工具调用功能，但还有很大的扩展空间。比如适配第三方技能插件（功能实现了80%，在完善中，主要是接入腾讯的Skills社区），还有优化提示词缓存机制，减少 token 消耗，提高响应速度。多模态输入输出，包括图片理解、语音交互等功能等。
在架构层面，未来可以考虑引入向量数据库实现更高效的记忆检索，支持 RAG（检索增强生成）模式。还可以探索分布式部署方案，支持多实例负载均衡和高可用配置。
七、总结
小龙虾通过精简 OpenClaw 框架，实现了一个功能完整的 AI 助手系统。系统在提示词构造、工具调用流程、技能动态加载等关键技术点上做出了还算合理的设计决策，并在实际开发过程中解决了各种大小问题。
小龙虾的成功孵化证明了一点：遵循严格的消息格式规范、优化提示词设计、建立完善的文档体系，可以构建出既简洁又可靠的 AI 助手系统。
以后，随着各种大模型的不断发展，AI 助手系统将在更多场景中得到应用，比如自媒体行业就是个目前能看得到的落地点。小龙虾的设计经验和实现细节，希望能为大家提供点参考和借鉴。
小龙虾开发的塔防小游戏：
有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用（落地与变现）。
