有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用（落地与变现）。

摘要：本文介绍了我的"小龙虾"，一个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';
import SimpleAIAssistant from './assistant-v7.js';

const PORT = 3002;
const API_KEY = 'sk-xxx';
const WORKSPACE = path.join(__dirname, '..', 'workspace');

// 初始化 AI 助手
const assistant = new SimpleAIAssistant(API_KEY, WORKSPACE);
await assistant.init();  // 异步加载技能和记忆

// 创建 HTTP 服务器
const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`);
  
  // SSE 连接：/sse
  if (url.pathname === '/sse' && req.method === 'GET') {
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    });
    
    const onProgress = (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/chat
  if (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 文件）
 */
export async function loadBootstrapFiles(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 标准格式）
 */
export function buildSystemPrompt(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）

async chat(userMessage, taskId = null) {
  const maxRounds = 15;  // 最多 15 轮工具调用
  let round = 1;
  
  // 初始化消息历史
  const messages = [
    { role: 'system', content: await this.buildSystemPrompt() },
    { role: 'user', content: userMessage },
  ];
  
  do {
    // 调用千问 API
    const response = await this.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 = await this.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);
}

/**
 * 执行工具调用
 */
async executeToolCall(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)}`;
  } else if (name === 'run_command') {
    // 使用 PowerShell 执行命令（支持 Select-String 等 cmdlet）
    const { stdout, stderr } = await execAsync(
      `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 的问题前必须执行
 */
async searchMemory(userMessage) {
  // 1. 提取关键词
  const keywords = extractKeywords(userMessage);
  if (keywords.length === 0) return null;
  
  // 2. 加载记忆文件到缓存
  await this.loadMemoryToCache();
  
  // 3. 语义搜索（简单版本：关键词匹配）
  const results = [];
  for (const cached of this.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 助手系统将在更多场景中得到应用，比如自媒体行业就是个目前能看得到的落地点。小龙虾的设计经验和实现细节，希望能为大家提供点参考和借鉴。

---

小龙虾开发的塔防小游戏：

有兴趣的朋友可以到我的知识星球“小龙虾孵化实验室”共同探索智能工具的实现与应用（落地与变现）。