GPU_GUARD_MONOREPO/docs/superpowers/plans/2026-04-15-prompt-builder-impl-plan.md

Prompt Builder 分层注入系统 实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 新建 prompt_builder + prompt_guidance 模块，将 5 个调用点的手动提示词拼接替换为统一的 8 层分层注入，并在前端提供预览面板。

Architecture: 纯函数 buildSystemPrompt() 接收 Agent 配置、模型名、可用工具列表等参数，按 8 层顺序组装系统提示词。所有指导文本常量集中在 prompt_guidance.ts。5 个调用点（gateway、agent_executor、crew_orchestrator、crew_delegate、controller preview）统一调用 builder，移除各自的手动拼接逻辑。

Tech Stack: TypeScript, Midway.js, Vue 3 + Element Plus

Spec: docs/superpowers/specs/2026-04-15-prompt-builder-design.md

---

文件结构

新建文件

文件	职责
packages/backend/src/modules/netaclaw/runtime/prompt_guidance.ts	所有指导文本常量（工具纪律、模型指导、工具策略、统一 MEMORY_SYSTEM_PROMPT）
packages/backend/src/modules/netaclaw/runtime/prompt_builder.ts	buildSystemPrompt() 纯函数 + collectAvailableToolNames() 辅助函数
packages/backend/test/prompt_builder.test.ts	prompt_builder 纯函数单元测试

修改文件

文件	变更
packages/backend/src/modules/netaclaw/service/skill_loader.ts:143-161	buildSkillsPrompt() 增强索引格式（category + tags + 强制措辞）
packages/backend/src/modules/netaclaw/gateway/server.ts:25-42,167-209	移除 MEMORY_SYSTEM_PROMPT，替换手动拼接为调用 builder
packages/backend/src/modules/netaclaw/service/agent_executor.ts:20-24,98-136	移除 MEMORY_SYSTEM_PROMPT，替换手动拼接为调用 builder
packages/backend/src/modules/netaclaw/runtime/agent.ts:64-66	移除 memoryContext 拼接（已由 builder 处理）
packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts:224-257	buildEnhancedPrompt() 改为调用 builder + crewContext
packages/backend/src/modules/netaclaw/service/crew_delegate.ts:47-53	buildSubAgentPrompt() 改为调用 builder
packages/backend/src/modules/netaclaw/controller/agent.ts:6-41	新增 previewPrompt 接口
packages/frontend/src/modules/agent/views/agent-edit.vue:94-102,211-480	系统提示词 Tab 下方新增折叠预览面板

---

Task 1: 创建 prompt_guidance.ts — 指导文本常量

Files:

• Create: packages/backend/src/modules/netaclaw/runtime/prompt_guidance.ts

• Step 1: 创建 prompt_guidance.ts 文件（第一部分：MEMORY + TOOL_USE_ENFORCEMENT + MODEL_GUIDANCE_RULES 前半）

// packages/backend/src/modules/netaclaw/runtime/prompt_guidance.ts

/**
 * Prompt Builder 指导文本常量
 * 所有注入到系统提示词的指导文本集中管理于此文件。
 */

// ─── 统一的 MEMORY_SYSTEM_PROMPT（合并 gateway 详细版 + agent_executor 简版） ───

export const MEMORY_SYSTEM_PROMPT = `

## 记忆系统
你拥有长期记忆能力。使用 memory_save 工具存储重要信息，使用 memory_recall 工具检索过往记忆。

记忆类型：
- user: 用户画像（偏好、角色、习惯）
- project: 项目知识（进展、决策、约束）
- feedback: 行为反馈（用户对你行为的纠正或确认）
- reference: 引用（外部资源链接、文档地址）

存储原则：
- 当用户透露个人偏好、角色、习惯时，存为 user 类型
- 当了解到项目进展、决策、约束时，存为 project 类型
- 当用户纠正或确认你的行为时，存为 feedback 类型
- 当提到外部资源链接时，存为 reference 类型
- 更新已有记忆而非创建重复条目
- 只存储对未来对话有价值的信息`;

// ─── Layer 2: 工具使用纪律（通用） ───

export const TOOL_USE_ENFORCEMENT = `# 工具使用规范
你必须通过工具采取行动 - 不要只描述你打算做什么。当你说"我来检查一下"、"让我执行"时，必须在同一回复中立即发起对应的工具调用。不要以"下一步我会..."结束回复 - 现在就执行。

持续工作直到任务真正完成。不要停在计划阶段。如果你有可用的工具能完成任务，使用它们，而不是告诉用户你会怎么做。

每条回复要么 (a) 包含推进任务的工具调用，要么 (b) 向用户交付最终结果。仅描述意图而不行动的回复是不可接受的。`;

// ─── Layer 3: 模型特定指导 ───

interface ModelGuidanceRule {
  patterns: string[];
  guidance: string;
}

const MODEL_GUIDANCE_RULES: ModelGuidanceRule[] = [
  {
    patterns: ['claude'],
    guidance: '', // Claude 工具调用能力强，不需要额外指导
  },
  {
    patterns: ['gpt', 'o1', 'o3', 'o4'],
    guidance: `# 执行纪律
<tool_persistence>
- 工具能提升正确性时必须使用，不要提前停止
- 工具返回空结果时换一种查询策略重试
- 持续调用工具直到：(1) 任务完成 且 (2) 已验证结果
</tool_persistence>
<mandatory_tool_use>
以下问题绝不能凭记忆回答，必须使用工具：
- 算术计算 → bash
- 文件内容、大小 → read_file / list_dir
- 当前时间日期 → bash
</mandatory_tool_use>`,
  },
  {
    patterns: ['deepseek'],
    guidance: `# 操作规范
- 支持并行工具调用：多个独立操作可在同一回复中发起
- 工具参数必须是合法 JSON，注意字符串转义
- 不要在工具调用的同时输出大段解释，先执行再说明`,
  },
  {
    patterns: ['minimax', 'abab'],
    guidance: `# 操作规范
- 算术、日期、文件内容等事实性问题必须使用工具获取，不要凭记忆回答
- 调用工具时严格按照参数 schema 传参，不要添加 schema 中不存在的字段
- 一次只调用一个工具，等待结果后再决定下一步
- 如果工具返回错误，换一种方式重试，不要放弃`,
  },
  {
    patterns: ['doubao', 'skylark'],
    guidance: `# 操作规范
- 工具参数必须严格匹配 schema 定义的类型
- 使用 bash 工具时加 -y 等非交互标志，避免命令挂起
- 先用 read_file/list_dir 了解现状，再做修改操作`,
  },
  {
    patterns: ['qwen'],
    guidance: `# 操作规范
- 工具调用参数必须严格匹配 schema，不要添加额外字段
- 使用 bash 工具时加 -y 等非交互标志，避免命令挂起
- 先用 read_file/list_dir 了解现状，再做修改操作`,
  },
  {
    patterns: ['glm', 'chatglm'],
    guidance: `# 操作规范
- 工具调用参数必须严格匹配 schema 定义的类型（string/number/boolean）
- 文件路径使用绝对路径
- 每次工具调用后检查返回结果，确认操作成功后再继续`,
  },
];

const DEFAULT_MODEL_GUIDANCE = `# 操作规范
- 事实性问题（算术、日期、文件内容）必须使用工具获取，不要凭记忆回答
- 调用工具时严格按照参数 schema 传参
- 一次只调用一个工具，等待结果后再决定下一步
- 如果工具返回错误，换一种方式重试`;

export function getModelGuidance(modelId: string): string {
  const lower = modelId.toLowerCase();
  for (const rule of MODEL_GUIDANCE_RULES) {
    if (rule.patterns.some(p => lower.includes(p))) {
      return rule.guidance;
    }
  }
  return DEFAULT_MODEL_GUIDANCE;
}

// ─── PLACEHOLDER_TOOL_BEHAVIOR ───

• Step 2: 追加 prompt_guidance.ts 第二部分（Layer 4 工具行为策略）

在 // ─── PLACEHOLDER_TOOL_BEHAVIOR ─── 处替换为：

// ─── Layer 4: 工具行为策略（条件注入） ───

const TOOL_BEHAVIOR_GUIDANCE: Record<string, string> = {
  memory_save: `## 记忆使用策略
使用 memory_save 存储对未来对话有价值的持久信息：用户偏好、环境细节、项目约束。
保持记忆紧凑，聚焦于减少用户未来重复纠正的事实。
不要存储任务进度、会话结果、临时 TODO 状态。更新已有记忆而非创建重复条目。`,

  todo: `## 任务规划策略
面对3步以上的复杂任务或用户提供多个任务时，先用 todo 工具创建任务列表。
同一时间只标记一个任务为 in_progress。完成后立即标记 completed。`,

  skill_manage: `## 技能管理策略
完成复杂任务（5步以上工具调用）后，考虑用 skill_manage 将方法保存为技能以便复用。
使用技能时如发现过时或错误，立即修补，不要等用户要求。`,
};

export function getToolBehaviorGuidance(toolNames: string[]): string {
  const parts: string[] = [];
  for (const [toolName, guidance] of Object.entries(TOOL_BEHAVIOR_GUIDANCE)) {
    if (toolNames.includes(toolName)) {
      parts.push(guidance);
    }
  }
  return parts.join('\n\n');
}

• Step 3: 提交

git add packages/backend/src/modules/netaclaw/runtime/prompt_guidance.ts
git commit -m "feat(netaclaw): 新建 prompt_guidance.ts — 集中管理所有指导文本常量"

---

Task 2: 创建 prompt_builder.ts — 核心构建函数

Files:

• Create: packages/backend/src/modules/netaclaw/runtime/prompt_builder.ts

• Step 1: 创建 prompt_builder.ts 文件（接口定义 + collectAvailableToolNames）

// packages/backend/src/modules/netaclaw/runtime/prompt_builder.ts

import { SkillLoaderService } from '../service/skill_loader.js';
import {
  TOOL_USE_ENFORCEMENT,
  MEMORY_SYSTEM_PROMPT,
  getModelGuidance,
  getToolBehaviorGuidance,
} from './prompt_guidance.js';

/** 基础内置工具（始终可用） */
const BASE_TOOLS = ['bash', 'read_file', 'write_file', 'list_dir', 'todo'];

/** 构建完整的可用工具名列表 */
export function collectAvailableToolNames(opts: {
  memoryEnabled?: boolean;
  hasSkills?: boolean;
  crewRole?: 'master' | 'sub';
}): string[] {
  const names = [...BASE_TOOLS];
  if (opts.memoryEnabled) names.push('memory_save', 'memory_recall');
  if (opts.hasSkills) names.push('read_skill', 'read_skill_file', 'skill_manage');
  if (opts.crewRole === 'master') names.push('delegate_task', 'delegate_parallel', 'escalate');
  return names;
}

export interface BuildSystemPromptParams {
  agentSystemPrompt: string;
  modelId: string;
  availableToolNames: string[];
  skills: string[];
  skillLoader: SkillLoaderService;
  memoryEnabled: boolean;
  memoryContext?: string;
  crewContext?: string;
}

export interface PromptLayer {
  name: string;
  content: string;
}

export interface BuildResult {
  prompt: string;
  layers: PromptLayer[];
}

// ─── PLACEHOLDER_BUILD_FN ───

• Step 2: 追加 buildSystemPrompt 函数实现

在 // ─── PLACEHOLDER_BUILD_FN ─── 处替换为：

/** 8 层分层组装系统提示词 */
export function buildSystemPrompt(params: BuildSystemPromptParams): BuildResult {
  const {
    agentSystemPrompt,
    modelId,
    availableToolNames,
    skills,
    skillLoader,
    memoryEnabled,
    memoryContext,
    crewContext,
  } = params;

  const layers: PromptLayer[] = [];

  // Layer 1: Agent 身份（用户写的 systemPrompt，原样保留）
  if (agentSystemPrompt) {
    layers.push({ name: 'Agent 身份', content: agentSystemPrompt });
  }

  // Layer 2: 工具使用纪律（通用，所有有工具的 Agent 都注入）
  if (availableToolNames.length > 0) {
    layers.push({ name: '工具使用纪律', content: TOOL_USE_ENFORCEMENT });
  }

  // Layer 3: 模型特定指导（按模型名称子串匹配）
  const modelGuidance = getModelGuidance(modelId);
  if (modelGuidance) {
    layers.push({ name: '模型特定指导', content: modelGuidance });
  }

  // Layer 4: 工具行为策略（按可用工具条件注入）
  const toolBehavior = getToolBehaviorGuidance(availableToolNames);
  if (toolBehavior) {
    layers.push({ name: '工具行为策略', content: toolBehavior });
  }

  // Layer 5: Skill 索引（增强版）
  if (skills.length > 0) {
    const skillPrompt = skillLoader.buildSkillsPrompt(skills, availableToolNames);
    if (skillPrompt) {
      layers.push({ name: 'Skill 索引', content: skillPrompt });
    }
  }

  // Layer 6: 记忆系统
  if (memoryEnabled) {
    let memoryContent = MEMORY_SYSTEM_PROMPT;
    if (memoryContext) {
      memoryContent += `\n\n<memory-context>\n${memoryContext}\n</memory-context>`;
    }
    layers.push({ name: '记忆系统', content: memoryContent });
  }

  // Layer 7: Crew 编排上下文（仅 Crew 场景）
  if (crewContext) {
    layers.push({ name: 'Crew 编排上下文', content: crewContext });
  }

  // Layer 8: 元信息
  const meta = `\n---\n当前时间: ${new Date().toISOString()}\n模型: ${modelId}`;
  layers.push({ name: '元信息', content: meta });

  const prompt = layers.map(l => l.content).join('\n\n');
  return { prompt, layers };
}

• Step 3: 提交

git add packages/backend/src/modules/netaclaw/runtime/prompt_builder.ts
git commit -m "feat(netaclaw): 新建 prompt_builder.ts — 8层分层系统提示词组装引擎"

---

Task 3: 单元测试 prompt_builder + prompt_guidance

Files:

• Create: packages/backend/test/prompt_builder.test.ts

项目已有 Jest 基础设施（jest.config.js + ts-jest），但无实际测试文件。prompt_builder 和 prompt_guidance 是纯函数，不依赖 Midway 框架，可以直接用 Jest 测试。

• Step 1: 编写测试文件（第一部分：collectAvailableToolNames + getModelGuidance）

// packages/backend/test/prompt_builder.test.ts

import { collectAvailableToolNames, buildSystemPrompt } from '../src/modules/netaclaw/runtime/prompt_builder.js';
import { getModelGuidance, getToolBehaviorGuidance, TOOL_USE_ENFORCEMENT, MEMORY_SYSTEM_PROMPT } from '../src/modules/netaclaw/runtime/prompt_guidance.js';

// ─── collectAvailableToolNames ───

describe('collectAvailableToolNames', () => {
  test('基础工具始终包含 todo', () => {
    const names = collectAvailableToolNames({});
    expect(names).toContain('bash');
    expect(names).toContain('read_file');
    expect(names).toContain('write_file');
    expect(names).toContain('list_dir');
    expect(names).toContain('todo');
  });

  test('memoryEnabled 追加记忆工具', () => {
    const names = collectAvailableToolNames({ memoryEnabled: true });
    expect(names).toContain('memory_save');
    expect(names).toContain('memory_recall');
  });

  test('hasSkills 追加 skill 工具', () => {
    const names = collectAvailableToolNames({ hasSkills: true });
    expect(names).toContain('read_skill');
    expect(names).toContain('read_skill_file');
    expect(names).toContain('skill_manage');
  });

  test('crewRole=master 追加委派工具', () => {
    const names = collectAvailableToolNames({ crewRole: 'master' });
    expect(names).toContain('delegate_task');
    expect(names).toContain('delegate_parallel');
    expect(names).toContain('escalate');
  });

  test('crewRole=sub 不追加委派工具', () => {
    const names = collectAvailableToolNames({ crewRole: 'sub' });
    expect(names).not.toContain('delegate_task');
  });
});

// ─── getModelGuidance ───

describe('getModelGuidance', () => {
  test('Claude 返回空字符串', () => {
    expect(getModelGuidance('claude-sonnet-4-20250514')).toBe('');
  });

  test('MiniMax 匹配 minimax 规则', () => {
    const g = getModelGuidance('MiniMax-M2.7-highspeed');
    expect(g).toContain('一次只调用一个工具');
  });

  test('GPT 匹配 gpt 规则', () => {
    const g = getModelGuidance('gpt-4o-2024-08-06');
    expect(g).toContain('tool_persistence');
  });

  test('DeepSeek 匹配 deepseek 规则', () => {
    const g = getModelGuidance('deepseek-chat');
    expect(g).toContain('并行工具调用');
  });

  test('未知模型返回默认指导', () => {
    const g = getModelGuidance('some-unknown-model-v1');
    expect(g).toContain('事实性问题');
  });

  test('火山引擎跑 doubao 模型匹配 doubao 规则', () => {
    const g = getModelGuidance('doubao-pro-32k');
    expect(g).toContain('非交互标志');
  });
});

// ─── getToolBehaviorGuidance ───

describe('getToolBehaviorGuidance', () => {
  test('包含 todo 时注入任务规划策略', () => {
    const g = getToolBehaviorGuidance(['bash', 'todo']);
    expect(g).toContain('任务规划策略');
  });

  test('包含 memory_save 时注入记忆策略', () => {
    const g = getToolBehaviorGuidance(['memory_save', 'memory_recall']);
    expect(g).toContain('记忆使用策略');
  });

  test('无匹配工具时返回空字符串', () => {
    const g = getToolBehaviorGuidance(['bash', 'read_file']);
    expect(g).toBe('');
  });
});

• Step 2: 追加测试文件第二部分（buildSystemPrompt 集成测试）

在测试文件末尾追加：

// ─── buildSystemPrompt ───

// 模拟 SkillLoaderService（只需 buildSkillsPrompt 方法）
function createMockSkillLoader(returnValue: string) {
  return {
    buildSkillsPrompt: jest.fn().mockReturnValue(returnValue),
  } as any;
}

describe('buildSystemPrompt', () => {
  test('基础场景：无 skill、无记忆、无 crew', () => {
    const result = buildSystemPrompt({
      agentSystemPrompt: '你是电商助手',
      modelId: 'MiniMax-M2.7-highspeed',
      availableToolNames: ['bash', 'read_file', 'write_file', 'list_dir', 'todo'],
      skills: [],
      skillLoader: createMockSkillLoader(''),
      memoryEnabled: false,
    });

    // Layer 1: Agent 身份
    expect(result.prompt).toContain('你是电商助手');
    // Layer 2: 工具纪律
    expect(result.prompt).toContain('工具使用规范');
    // Layer 3: MiniMax 模型指导
    expect(result.prompt).toContain('一次只调用一个工具');
    // Layer 4: todo 工具策略
    expect(result.prompt).toContain('任务规划策略');
    // Layer 8: 元信息
    expect(result.prompt).toContain('模型: MiniMax-M2.7-highspeed');
    // 不含记忆
    expect(result.prompt).not.toContain('记忆系统');
    // layers 数组正确
    expect(result.layers.map(l => l.name)).toEqual([
      'Agent 身份', '工具使用纪律', '模型特定指导', '工具行为策略', '元信息',
    ]);
  });

  test('完整场景：skill + 记忆 + memoryContext', () => {
    const mockLoader = createMockSkillLoader('<available_skills>...</available_skills>');
    const result = buildSystemPrompt({
      agentSystemPrompt: '你是运营助手',
      modelId: 'gpt-4o',
      availableToolNames: ['bash', 'todo', 'memory_save', 'memory_recall', 'read_skill', 'read_skill_file', 'skill_manage'],
      skills: ['playwright-cli'],
      skillLoader: mockLoader,
      memoryEnabled: true,
      memoryContext: '用户偏好：简洁回复',
    });

    expect(result.prompt).toContain('你是运营助手');
    expect(result.prompt).toContain('tool_persistence'); // GPT 指导
    expect(result.prompt).toContain('available_skills');
    expect(result.prompt).toContain('记忆系统');
    expect(result.prompt).toContain('<memory-context>');
    expect(result.prompt).toContain('用户偏好：简洁回复');
    expect(mockLoader.buildSkillsPrompt).toHaveBeenCalledWith(['playwright-cli'], expect.any(Array));
  });

  test('Crew 场景：注入 crewContext', () => {
    const result = buildSystemPrompt({
      agentSystemPrompt: '你是主 Agent',
      modelId: 'claude-sonnet-4-20250514',
      availableToolNames: ['bash', 'todo', 'delegate_task', 'delegate_parallel', 'escalate'],
      skills: [],
      skillLoader: createMockSkillLoader(''),
      memoryEnabled: false,
      crewContext: '## 你的团队成员\n- 小明: 数据分析',
    });

    expect(result.prompt).toContain('你的团队成员');
    expect(result.layers.find(l => l.name === 'Crew 编排上下文')).toBeTruthy();
    // Claude 模型指导为空，不应有 Layer 3
    expect(result.layers.find(l => l.name === '模型特定指导')).toBeFalsy();
  });

  test('空 agentSystemPrompt 不生成 Layer 1', () => {
    const result = buildSystemPrompt({
      agentSystemPrompt: '',
      modelId: 'deepseek-chat',
      availableToolNames: ['bash', 'todo'],
      skills: [],
      skillLoader: createMockSkillLoader(''),
      memoryEnabled: false,
    });

    expect(result.layers.find(l => l.name === 'Agent 身份')).toBeFalsy();
    expect(result.layers[0].name).toBe('工具使用纪律');
  });
});

• Step 3: 运行测试确认全部通过

cd packages/backend
npx jest test/prompt_builder.test.ts --verbose

预期输出：所有 test case PASS。如果 ts-jest 的 ESM 导入有问题（.js 后缀），需要在 jest.config.js 中添加 moduleNameMapper 将 .js 映射到 .ts。

如果遇到 ESM 问题，在 jest.config.js 中添加：

moduleNameMapper: {
  '^(\\.{1,2}/.*)\\.js$': '$1',
},

• Step 4: 提交

git add packages/backend/test/prompt_builder.test.ts
git add packages/backend/jest.config.js  # 如果修改了
git commit -m "test(netaclaw): prompt_builder + prompt_guidance 纯函数单元测试"

---

Task 4: 增强 skill_loader.ts — 索引格式升级

Files:

• Modify: packages/backend/src/modules/netaclaw/service/skill_loader.ts:143-161

• Step 1: 修改 buildSkillsPrompt() 方法

打开 packages/backend/src/modules/netaclaw/service/skill_loader.ts，将 buildSkillsPrompt() 方法（第 143-161 行）替换为：

buildSkillsPrompt(skillNames: string[], availableTools: string[]): string {
  const filtered = this.filterByConditions(skillNames, availableTools);
  if (filtered.length === 0) return '';

  const lines: string[] = [];
  let totalChars = 0;
  for (const s of filtered) {
    const category = (s.metadata?.category as string) || '通用';
    const tags = Array.isArray(s.metadata?.tags) ? (s.metadata.tags as string[]).join(',') : '';
    const line = `  <skill name="${s.name}" category="${category}" tags="${tags}">\n    ${s.description}\n  </skill>`;
    if (totalChars + line.length > SkillLoaderService.MAX_SKILLS_PROMPT_CHARS) {
      this.logger.warn('[SkillLoader] Skill 索引超过 %d 字符限制，截断', SkillLoaderService.MAX_SKILLS_PROMPT_CHARS);
      break;
    }
    lines.push(line);
    totalChars += line.length;
  }
  if (lines.length === 0) return '';

  return `\n\n## 技能（必须扫描）\n回复前，扫描以下技能列表。如果某个技能明确匹配当前任务，用 read_skill 工具加载完整指令后严格遵循。\n\n<available_skills>\n${lines.join('\n')}\n</available_skills>`;
}

变更点：

1. 每个 <skill> 标签增加 category 和 tags 属性
2. 索引头部从被动措辞改为强制措辞（"必须扫描"）
3. 尾部说明从 当你需要使用某个 skill 时... 改为 回复前，扫描以下技能列表...

• Step 2: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -20

预期：无新增编译错误。

• Step 3: 提交

git add packages/backend/src/modules/netaclaw/service/skill_loader.ts
git commit -m "feat(netaclaw): skill 索引增强 — category/tags 属性 + 强制扫描措辞"

---

Task 5: 改造 gateway/server.ts — 替换手动拼接

Files:

• Modify: packages/backend/src/modules/netaclaw/gateway/server.ts:1-42,131-135,167-177,192-210,226-229

这是最核心的改造，WebSocket 对话入口。

• Step 1: 添加 import 并移除 MEMORY_SYSTEM_PROMPT

在文件顶部 import 区域添加：

import { buildSystemPrompt, collectAvailableToolNames } from '../runtime/prompt_builder.js';

删除第 25-42 行的 MEMORY_SYSTEM_PROMPT 常量（整个 const 声明）。

• Step 2: 替换 handleChat() 中的 systemPrompt 组装逻辑

找到 handleChat() 方法中构建 agentConfig 的部分。

当前代码（约第 131-135 行）：

const { skillPrompt, skillTools: agentSkillTools } = buildSkillContext(
  this.skillLoader,
  agentInfo.skills,
  builtinToolNames,
);

替换为：

const { skillTools: agentSkillTools } = buildSkillContext(
  this.skillLoader,
  agentInfo.skills,
  builtinToolNames,
);

注意：仍然需要 buildSkillContext 来获取 skillTools（read_skill 等工具实例），但不再需要 skillPrompt（由 builder 内部处理）。

• Step 3: 提前记忆系统代码 + 替换 agentConfig 构建

当前 gateway 中记忆系统代码在第 192-210 行（agentConfig 构建之后），需要提前到 buildSystemPrompt 调用之前。同时消除冗余的 agentInfo2 重新查询。

找到第 192-210 行的记忆系统代码块，整块删除（包括 agentInfo2 查询）。

然后将第 167-177 行的 agentConfig 构建替换为以下代码（记忆处理 + builder 调用 + agentConfig 构建一体化）：

// --- 记忆系统（从 cfg 直接取，不再重新查询 agentInfo2） ---
const memoryConfig: AgentMemoryConfig | undefined = cfg?.memory;
let memoryContext: string | undefined;
let memoryTools: AnyAgentTool[] = [];
if (memoryConfig?.enabled) {
  const provider = createMemoryProvider(memoryConfig, this.memoryRepo);
  const userId = 'anonymous';
  memoryContext = await prefetchMemory(provider, content, agentInfo.name, userId, memoryConfig.prefetchLimit);
  memoryTools = [
    createMemorySaveTool(provider, agentInfo.name, userId),
    createMemoryRecallTool(provider, agentInfo.name, userId),
  ];
}

// --- 分层组装系统提示词 ---
const toolNames = collectAvailableToolNames({
  memoryEnabled: !!memoryConfig?.enabled,
  hasSkills: !!agentInfo.skills?.length,
});
const { prompt: systemPrompt } = buildSystemPrompt({
  agentSystemPrompt: agentInfo.systemPrompt || '',
  modelId: mc.modelId || '',  // 纯模型名，不含 provider: 前缀
  availableToolNames: toolNames,
  skills: agentInfo.skills || [],
  skillLoader: this.skillLoader,
  memoryEnabled: !!memoryConfig?.enabled,
  memoryContext,
});

agentConfig = {
  name: agentInfo.name,
  systemPrompt,
  model,
  apiKey,
  baseUrl,
  channelId,
  channelName,
  channelSupplier,
  maxToolRounds: cfg?.middleware?.maxToolRounds ?? cfg?.middleware?.maxToolCalls ?? 20,
  temperature: cfg?.temperature,
  maxTokens: cfg?.maxTokens,
  defaultThinkLevel: cfg?.thinking?.defaultLevel,
};

注意事项：

• modelId: mc.modelId || '' 传纯模型名（如 MiniMax-M2.7-highspeed），不是 model 变量（openai:MiniMax-M2.7-highspeed）

• memoryConfig 从 cfg?.memory 取（cfg 在第 129 行已有），不再重新查询 agentInfo2

• 原第 193 行的 const agentInfo2 = agentId ? await this.agentService.info(agentId) : null; 删除（消除冗余数据库查询）

• Step 4: 移除 runAgent 调用中的 memoryContext 参数

找到 runAgent() 调用（约第 229 行），移除 memoryContext 参数：

const result = await runAgent({
  agentConfig,
  tools: [...this.defaultTools, ...memoryTools, ...agentSkillTools],
  userMessage: content,
  history: history.slice(0, -1),
  // memoryContext 已移除 — 由 builder 处理
  sessionThinkLevel: sessionThinkLevel ?? undefined,
  onToken: (token) => { /* ... */ },
  // ...
});

• Step 5: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

• Step 6: 提交

git add packages/backend/src/modules/netaclaw/gateway/server.ts
git commit -m "refactor(netaclaw): gateway handleChat() 替换手动拼接为 prompt_builder"

---

Task 6: 改造 agent_executor.ts — 替换手动拼接

Files:

• Modify: packages/backend/src/modules/netaclaw/service/agent_executor.ts:1-24,77-100,116-141

• Step 1: 添加 import 并移除 MEMORY_SYSTEM_PROMPT

在文件顶部 import 区域添加：

import { buildSystemPrompt, collectAvailableToolNames } from '../runtime/prompt_builder.js';

删除第 20-24 行的 MEMORY_SYSTEM_PROMPT 常量。

• Step 2: 替换 execute() 中的 systemPrompt 组装

找到 execute() 方法中构建 skillPrompt 的部分（约第 72-83 行）。

当前代码：

let skillTools: AnyAgentTool[] = [];
let skillPrompt = '';
// ...
const builtinToolNames = ['bash', 'read_file', 'write_file', 'list_dir'];
const skillCtx = buildSkillContext(this.skillLoader, agentEntity.skills, builtinToolNames);
skillPrompt = skillCtx.skillPrompt;
skillTools = skillCtx.skillTools;

替换为：

let skillTools: AnyAgentTool[] = [];
// ...
const builtinToolNames = ['bash', 'read_file', 'write_file', 'list_dir'];
const skillCtx = buildSkillContext(this.skillLoader, agentEntity.skills, builtinToolNames);
skillTools = skillCtx.skillTools;

移除 skillPrompt 变量（不再需要）。

• Step 3: 替换 agentConfig 构建和记忆拼接

找到 agentConfig 构建（约第 98-105 行）和记忆拼接（约第 116-136 行）。

将 agentConfig 构建中的 systemPrompt: (agentEntity.systemPrompt || '') + skillPrompt 替换。

注意：model 变量在渠道解析后变成了 provider:model 格式（如 openai:MiniMax-M2.7-highspeed），但 builder 需要纯模型名。用 mc.modelId 而不是 model。

在记忆预取完成后，统一构建：

// 记忆预取（保持原有逻辑获取 memoryContext 和 memoryTools）
let memoryContext: string | undefined;
let memoryTools: AnyAgentTool[] = [];
const memoryConfig: AgentMemoryConfig | undefined = cfg?.memory;
if (memoryConfig?.enabled) {
  const provider = createMemoryProvider(memoryConfig, this.memoryEntity);
  memoryContext = await prefetchMemory(provider, params.message, agentEntity.name, params.userId, memoryConfig.prefetchLimit);
  memoryTools = [createMemorySaveTool(provider), createMemoryRecallTool(provider)];
}

// 构建可用工具名列表
const toolNames = collectAvailableToolNames({
  memoryEnabled: !!memoryConfig?.enabled,
  hasSkills: !!agentEntity.skills?.length,
});

// 分层组装系统提示词
const { prompt: systemPrompt } = buildSystemPrompt({
  agentSystemPrompt: agentEntity.systemPrompt || '',
  modelId: mc.modelId || '',  // 纯模型名，不含 provider: 前缀
  availableToolNames: toolNames,
  skills: agentEntity.skills || [],
  skillLoader: this.skillLoader,
  memoryEnabled: !!memoryConfig?.enabled,
  memoryContext,
});

agentConfig = {
  name: agentEntity.name,
  systemPrompt,
  model,
  apiKey,
  baseUrl,
  maxToolRounds: cfg?.middleware?.maxToolRounds ?? cfg?.middleware?.maxToolCalls ?? 20,
};

同时移除后面的 agentConfig.systemPrompt += MEMORY_SYSTEM_PROMPT; 行。

• Step 4: 移除 runAgent 调用中的 memoryContext 参数

找到 runAgent() 调用（约第 141 行），移除 memoryContext 参数。

• Step 5: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

• Step 6: 提交

git add packages/backend/src/modules/netaclaw/service/agent_executor.ts
git commit -m "refactor(netaclaw): agent_executor execute() 替换手动拼接为 prompt_builder"

---

Task 7: 改造 runtime/agent.ts — 移除 memoryContext 拼接

Files:

• Modify: packages/backend/src/modules/netaclaw/runtime/agent.ts:26-40,64-66

• Step 1: 从 AgentRunParams 接口移除 memoryContext

打开 packages/backend/src/modules/netaclaw/runtime/agent.ts。

找到 AgentRunParams 接口（第 26-40 行），移除 memoryContext?: string; 字段。

• Step 2: 简化 systemContent 构建

找到第 64-66 行：

const systemContent = memoryContext
  ? `${agentConfig.systemPrompt}\n\n<memory-context>\n${memoryContext}\n</memory-context>`
  : agentConfig.systemPrompt;

替换为：

const systemContent = agentConfig.systemPrompt;

同时从第 43 行的解构中移除 memoryContext：

// 之前
const { agentConfig, tools, userMessage, history = [], memoryContext,
  onToken, onThinking, onToolCall, onToolResult } = params;

// 之后
const { agentConfig, tools, userMessage, history = [],
  onToken, onThinking, onToolCall, onToolResult } = params;

• Step 3: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

注意：此步骤可能会在 gateway/server.ts 和 agent_executor.ts 中报错（如果它们还在传 memoryContext 参数）。确保 Task 5 和 Task 6 已完成。

• Step 4: 提交

git add packages/backend/src/modules/netaclaw/runtime/agent.ts
git commit -m "refactor(netaclaw): runAgent 移除 memoryContext — 已由 prompt_builder 统一处理"

---

Task 8: 改造 crew_orchestrator.ts — 主 Agent 提示词

Files:

• Modify: packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts:1-23,224-257

• Step 1: 添加 import

在文件顶部 import 区域添加：

import { buildSystemPrompt, collectAvailableToolNames } from '../runtime/prompt_builder.js';

• Step 2: 替换 buildEnhancedPrompt() 方法

找到 buildEnhancedPrompt() 方法（第 224-257 行），替换为：

private buildEnhancedPrompt(
  masterAgent: NetaClawAgentEntity,
  ctx: CrewRunContext,
  crew: NetaClawCrewEntity,
  resolvedModelId: string,
): string {
  // 构建 Crew 专属上下文（Layer 7）
  const crewParts: string[] = [];

  // 团队成员信息（含技能）
  const memberList = ctx.memberAgents
    .map(m => {
      const skills = m.agent?.skills?.length
        ? `，已具备技能: ${m.agent.skills.join('、')}`
        : '';
      const desc = m.agent?.description ? `，简介: ${m.agent.description}` : '';
      return `- ${m.name} (${m.label}): ${m.role || '无角色描述'}${desc}${skills}`;
    })
    .join('\n');
  crewParts.push(`## 你的团队成员\n${memberList}\n\n注意：委派任务时无需让成员安装工具或环境，他们已具备所列技能，直接描述要完成的目标即可。`);

  // 委派提示
  if (crew.delegateHints?.hints) {
    crewParts.push(`## 调度建议\n${crew.delegateHints.hints}`);
  }

  // 工具说明
  crewParts.push(`## 编排工具说明
- delegate_task: 将任务委派给指定子 Agent 串行执行
- delegate_parallel: 同时委派多个任务给不同子 Agent 并行执行
- escalate: 遇到无法解决的问题时升级给人工处理

请根据任务需求合理分配工作给团队成员，充分利用并行执行提高效率。`);

  // 通过 builder 统一组装
  const toolNames = collectAvailableToolNames({
    hasSkills: !!masterAgent.skills?.length,
    crewRole: 'master',
  });
  const { prompt } = buildSystemPrompt({
    agentSystemPrompt: masterAgent.systemPrompt || '',
    modelId: resolvedModelId,
    availableToolNames: toolNames,
    skills: masterAgent.skills || [],
    skillLoader: this.skillLoader,
    memoryEnabled: false,
    crewContext: crewParts.join('\n\n'),
  });
  return prompt;
}

• Step 3: 更新 buildEnhancedPrompt 的调用处（第 139 行）

当前代码（crew_orchestrator.ts 第 138-139 行）：

// 构建增强系统提示词
const enhancedPrompt = this.buildEnhancedPrompt(masterAgent, ctx, crew);

问题：模型解析在第 141-157 行，在 buildEnhancedPrompt 调用之后。需要将调用移到模型解析之后。

将第 138-161 行改为：

// 解析主 Agent 模型配置（移到 buildEnhancedPrompt 之前）
const mc = (masterAgent.modelConfig || {}) as any;
let model: string, apiKey: string, baseUrl: string | undefined;
if (mc.apiKey && mc.modelId) {
  model = mc.modelId;
  apiKey = mc.apiKey;
  baseUrl = mc.apiUrl;
} else if (mc.channelId) {
  const resolved = await this.modelChannelService.resolveForAgent(mc.channelId, mc.modelId || '');
  model = `${resolved.provider}:${resolved.model}`;
  apiKey = resolved.apiKey;
  baseUrl = resolved.baseUrl;
} else {
  model = mc.modelId || (process.env.NETACLAW_MODEL ?? 'anthropic:claude-sonnet-4-20250514');
  apiKey = process.env.NETACLAW_API_KEY ?? '';
  baseUrl = mc.apiUrl;
}

// 提取纯 modelId（去掉 provider: 前缀）用于 prompt_builder 模型匹配
const pureModelId = model.includes(':') ? model.split(':')[1] : model;

// 构建增强系统提示词（现在有 modelId 了）
const enhancedPrompt = this.buildEnhancedPrompt(masterAgent, ctx, crew, pureModelId);

const agentConfig: AgentConfig = {
  name: masterAgent.name,
  systemPrompt: enhancedPrompt,
  model,
  apiKey,
  baseUrl,
  // ... 其余字段保持不变

• Step 4: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

• Step 5: 提交

git add packages/backend/src/modules/netaclaw/service/crew_orchestrator.ts
git commit -m "refactor(netaclaw): crew_orchestrator buildEnhancedPrompt 改用 prompt_builder"

---

Task 9: 改造 crew_delegate.ts — 子 Agent 提示词

Files:

• Modify: packages/backend/src/modules/netaclaw/service/crew_delegate.ts:1-13,47-53

• Step 1: 添加 import

在文件顶部 import 区域添加：

import { buildSystemPrompt, collectAvailableToolNames } from '../runtime/prompt_builder.js';

• Step 2: 替换 buildSubAgentPrompt() 方法

找到 buildSubAgentPrompt() 方法（第 47-53 行），替换为：

private buildSubAgentPrompt(
  systemPrompt: string,
  role: string,
  agentSkills?: string[],
  modelId?: string,
): string {
  const rolePrefix = role
    ? `${systemPrompt}\n\n你在团队中的角色: ${role}`
    : systemPrompt;

  const toolNames = collectAvailableToolNames({
    hasSkills: !!agentSkills?.length,
    crewRole: 'sub',
  });
  const { prompt } = buildSystemPrompt({
    agentSystemPrompt: rolePrefix,
    modelId: modelId || '',
    availableToolNames: toolNames,
    skills: agentSkills || [],
    skillLoader: this.skillLoader,
    memoryEnabled: false,
  });
  return prompt;
}

• Step 3: 更新 buildSubAgentPrompt 的调用处（第 111 行）

当前代码（crew_delegate.ts 第 110-111 行）：

const modelInfo = await this.resolveModelConfig(agent);
const systemPrompt = this.buildSubAgentPrompt(agent.systemPrompt || '', member.role, agent.skills);

modelInfo.model 格式为 provider:modelId（如 openai:MiniMax-M2.7-highspeed），需要提取纯 modelId。

替换为：

const modelInfo = await this.resolveModelConfig(agent);
// 提取纯 modelId（去掉 provider: 前缀）用于 prompt_builder 模型匹配
const pureModelId = modelInfo.model.includes(':') ? modelInfo.model.split(':')[1] : modelInfo.model;
const systemPrompt = this.buildSubAgentPrompt(agent.systemPrompt || '', member.role, agent.skills, pureModelId);

• Step 4: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

• Step 5: 提交

git add packages/backend/src/modules/netaclaw/service/crew_delegate.ts
git commit -m "refactor(netaclaw): crew_delegate buildSubAgentPrompt 改用 prompt_builder"

---

Task 10: 后端预览接口 — controller/agent.ts

Files:

• Modify: packages/backend/src/modules/netaclaw/controller/agent.ts:1-41

• Step 1: 添加 import 和注入

在文件顶部添加 import：

import { buildSystemPrompt, collectAvailableToolNames } from '../runtime/prompt_builder.js';
import { SkillLoaderService } from '../service/skill_loader.js';
import { NetaClawModelChannelService } from '../service/model_channel.js';

在 NetaClawAgentAdminController 类中添加注入：

@Inject()
skillLoader: SkillLoaderService;

@Inject()
channelService: NetaClawModelChannelService;

• Step 2: 添加 previewPrompt 接口

在 NetaClawAgentAdminController 类中（info() 方法之后）添加：

@Post('/previewPrompt', { summary: '预览最终系统提示词' })
async previewPrompt(@Body() body: {
  systemPrompt: string;
  skills: string[];
  modelConfig: { channelId?: number; modelId?: string };
}) {
  let modelId = body.modelConfig?.modelId || 'unknown';

  // 如果有 channelId，解析渠道获取模型信息
  if (body.modelConfig?.channelId) {
    const resolved = await this.channelService.resolveForAgent(
      body.modelConfig.channelId,
      modelId,
    );
    modelId = resolved.model;
  }

  const toolNames = collectAvailableToolNames({
    hasSkills: !!body.skills?.length,
  });

  const result = buildSystemPrompt({
    agentSystemPrompt: body.systemPrompt || '',
    modelId,
    availableToolNames: toolNames,
    skills: body.skills || [],
    skillLoader: this.skillLoader,
    memoryEnabled: false, // 预览时不含记忆上下文
  });

  return this.ok(result);
}

• Step 3: 验证编译通过

cd packages/backend
npx tsc --noEmit --pretty 2>&1 | head -30

• Step 4: 提交

git add packages/backend/src/modules/netaclaw/controller/agent.ts
git commit -m "feat(netaclaw): 新增 previewPrompt 接口 — 前端预览最终系统提示词"

---

Task 11: 前端预览面板 — agent-edit.vue

Files:

• Modify: packages/frontend/src/modules/agent/views/agent-edit.vue:94-102,211-480

• Step 1: 在系统提示词 Tab 下方添加折叠预览面板

打开 packages/frontend/src/modules/agent/views/agent-edit.vue。

找到系统提示词 Tab（第 94-102 行），在 </el-tab-pane> 闭合标签之前（第 102 行之前），添加折叠面板：

    <!-- 最终提示词预览 -->
    <el-collapse v-if="modelConfig.channelId" style="margin-top: 16px">
      <el-collapse-item>
        <template #title>
          <span>预览最终提示词</span>
          <el-tag size="small" type="info" style="margin-left: 8px">
            运行时实际发送给模型的内容
          </el-tag>
        </template>
        <el-button size="small" @click="loadPreview" :loading="previewLoading" style="margin-bottom: 12px">
          刷新预览
        </el-button>
        <div v-if="previewLayers.length" class="prompt-preview">
          <div v-for="layer in previewLayers" :key="layer.name" class="layer-block">
            <div class="layer-label">{{ layer.name }}</div>
            <pre class="layer-content">{{ layer.content }}</pre>
          </div>
        </div>
      </el-collapse-item>
    </el-collapse>

• Step 2: 在 script 中添加预览相关的响应式变量和方法

在 <script> 部分的 setup() 或 <script setup> 中添加：

const previewLoading = ref(false);
const previewLayers = ref<Array<{ name: string; content: string }>>([]);

async function loadPreview() {
  previewLoading.value = true;
  try {
    const res = await service.request({
      url: '/admin/netaclaw/agent/previewPrompt',
      method: 'POST',
      data: {
        systemPrompt: form.systemPrompt,
        skills: form.skills,
        modelConfig: {
          channelId: modelConfig.channelId,
          modelId: modelConfig.modelId,
        },
      },
    });
    previewLayers.value = res?.layers || [];
  } catch (e) {
    console.error('预览加载失败', e);
    previewLayers.value = [];
  } finally {
    previewLoading.value = false;
  }
}

• Step 3: 添加样式

在 <style scoped> 中添加：

.prompt-preview {
  max-height: 500px;
  overflow-y: auto;
}

.layer-block {
  margin-bottom: 12px;
  border: 1px solid var(--el-border-color-lighter);
  border-radius: 4px;
}

.layer-label {
  padding: 6px 12px;
  background: var(--el-fill-color-light);
  font-weight: 600;
  font-size: 13px;
  border-bottom: 1px solid var(--el-border-color-lighter);
}

.layer-content {
  padding: 12px;
  margin: 0;
  white-space: pre-wrap;
  word-break: break-word;
  font-size: 12px;
  line-height: 1.6;
  max-height: 300px;
  overflow-y: auto;
}

• Step 4: 在浏览器中验证

1. 启动前端开发服务器（用户手动执行 pnpm --filter @neta/frontend dev）
2. 打开 Agent 编辑页面
3. 选择一个模型渠道
4. 切换到"系统提示词"Tab
5. 确认折叠面板出现
6. 点击"刷新预览"按钮
7. 确认各层内容正确显示

• Step 5: 提交

git add packages/frontend/src/modules/agent/views/agent-edit.vue
git commit -m "feat(agent): Agent 编辑页新增最终提示词预览面板"

---

Task 12: 全量编译验证 + 运行测试

Files: 无新文件

• Step 1: 全量 TypeScript 编译检查

cd packages/backend
npx tsc --noEmit --pretty

预期：无编译错误。如有错误，逐一修复。

• Step 2: 运行单元测试

cd packages/backend
npx jest test/prompt_builder.test.ts --verbose

预期：所有测试 PASS。

• Step 3: 检查前端编译

cd packages/frontend
npx vue-tsc --noEmit 2>&1 | head -30

预期：无新增编译错误。

• Step 4: 最终提交（如有修复）

git add -A
git commit -m "fix(netaclaw): prompt_builder 全量编译修复"

---

实施顺序与依赖关系

Task 1 (prompt_guidance.ts)
    ↓
Task 2 (prompt_builder.ts) ← 依赖 Task 1
    ↓
Task 3 (单元测试) ← 依赖 Task 1 + 2
    ↓
Task 4 (skill_loader 增强) ← 独立，但 builder 调用它
    ↓
Task 5 (gateway/server.ts) ← 依赖 Task 1 + 2 + 4
Task 6 (agent_executor.ts) ← 依赖 Task 1 + 2 + 4
Task 7 (runtime/agent.ts) ← 依赖 Task 5 + 6（移除 memoryContext 后调用方不再传）
    ↓
Task 8 (crew_orchestrator.ts) ← 依赖 Task 1 + 2
Task 9 (crew_delegate.ts) ← 依赖 Task 1 + 2
    ↓
Task 10 (controller previewPrompt) ← 依赖 Task 1 + 2
Task 11 (前端预览面板) ← 依赖 Task 10
    ↓
Task 12 (全量验证) ← 依赖所有 Task

Task 5/6 可并行，Task 8/9 可并行，Task 10/11 串行。