---
title: Prompt Builder 分层注入系统
created: 2026-04-16
updated: 2026-04-19
type: concept
tags: [agent, llm, architecture]
sources: [packages/backend/src/modules/netaclaw/runtime/prompt_builder.ts, packages/backend/src/modules/netaclaw/runtime/prompt_guidance.ts, packages/backend/src/modules/netaclaw/controller/agent.ts]
---

# Prompt Builder 分层注入系统

## 定义

8 层分层系统，将 Agent 的系统提示词从多个来源统一组装。它本身是纯函数层，但现在通常接收来自 [[tool-governance]] 的最终 `toolNames` 与 `toolPromptHints`，不再单独决定运行时工具可见性。

## 8 层结构

```text
Layer 1: Agent 身份（agentSystemPrompt）
Layer 2: 工具使用纪律（基于 availableToolNames 动态生成）
Layer 3: 模型特定指导（GPT/DeepSeek/MiniMax/豆包/通义千问/GLM）
Layer 4: 工具行为策略（基于工具列表 + Prompt Hint）
Layer 5: Skill 索引（如果有 Skill）
Layer 6: 记忆系统（如果启用记忆）
Layer 7: Crew 编排上下文（如果是 Crew 模式）
Layer 8: 元信息（时间戳、模型ID）
```

## 核心文件

| 文件 | 职责 |
|------|------|
| `runtime/prompt_builder.ts` | `buildSystemPrompt()` 主函数，8层组装 |
| `runtime/prompt_guidance.ts` | 指导文本常量集中管理 |
| `controller/agent.ts` | 预览接口，展示最终 layers/toolNames/disabledReasons |

## 关键 API

```typescript
interface BuildSystemPromptParams {
  agentSystemPrompt: string;
  modelId: string;
  availableToolNames: string[];
  skills: string[];
  skillLoader: SkillLoaderService;
  memoryEnabled: boolean;
  memoryContext?: string;
  crewContext?: string;
  toolPromptHints?: Record<string, string>;
}

buildSystemPrompt(params): { prompt: string, layers: PromptLayer[] }
```

## 关键变化

### 旧模式

Prompt Builder 可直接通过 `collectAvailableToolNames()` 结合 toolset 推导工具列表。

### 当前主路径

当前真正用于运行时和预览的主链路是：

```text
Agent 配置 + 全局 Tool 配置 + 模型能力 + 上下文角色
  → tool_resolver.resolve()
  → 输出 toolNames / toolPromptHints / disabledReasons
  → buildSystemPrompt()
```

因此 Prompt Builder 更像“最终提示词组装器”，而不是“工具决策器”。

## 模型特定指导

`getModelGuidance(modelId)` 会为不同模型生成约束性指导，用于减少工具调用和 schema 输出偏差。

## Prompt Hint

Layer 4 现在支持从 [[tool-governance]] 注入 `toolPromptHints`，用于覆写单个工具的行为指令。这个能力使运营侧可以不改工具代码就微调模型使用方式。

## 预览接口

Agent 编辑页通过：

```text
POST /admin/netaclaw/agent/previewPrompt
```

直接返回：

- `layers`
- `toolNames`
- `disabledReasons`

这让前端可以同时看到最终提示词和为什么某些工具没生效。

## 关联页面

- [[tool-catalog]] — schema 注册来源
- [[tool-governance]] — 最终工具列表与 Prompt Hint 来源
- [[agent-runtime]] — 调用 buildSystemPrompt 的执行引擎
- [[llm-providers]] — 模型特定指导的适配对象
- [[skill-system]] — Layer 5 Skill 索引来源
- [[memory-system]] — Layer 6 记忆上下文来源
- [[crew-orchestration]] — Layer 7 Crew 编排上下文来源