107 lines
3.2 KiB
Markdown
107 lines
3.2 KiB
Markdown
|
---
|
|||
|
|
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 编排上下文来源
|