Prompt 动态注入问题分析与优化方案

状态：✅ 门下省审核通过（v2）
分支：feat/prompt-and-mask-refactor
日期：2026-03-22

当前 prompt 构建分为两个阶段：构建阶段（buildPrompt，用户消息到来时执行一次）和 运行阶段（Run 循环，tool call 后只注入 sys_reminder）。

用户消息到来
  ↓
processMessage() [agent/agent.go:1171]
  ↓
buildPrompt() [agent/agent.go:1392]
  ├─ 获取 session 历史消息
  ├─ 配置 MCP tools
  ├─ 计算 promptWorkDir
  ├─ 创建 MessageContext（含 CWD、skills catalog、agents catalog、memory）
  └─ pipeline.Run(mc) — 执行中间件链
       ├─ Priority 0:   SystemPromptMiddleware → 渲染 prompt.md 模板（注入 Channel, WorkDir, CWD）
       ├─ Priority 1:   ProjectHintMiddleware → 从 archival memory 注入 [PROJECT_CARD]
       ├─ Priority 5:   ChannelPromptMiddleware → 注入渠道特化 prompt（如飞书）
       ├─ Priority 100: SkillsCatalogMiddleware → 注入 <available_skills>
       ├─ Priority 110: AgentsCatalogMiddleware → 注入 <available_agents>
       ├─ Priority 120: MemoryMiddleware → 注入长期记忆（core + working_context）
       ├─ Priority 130: SenderInfoMiddleware → 注入发送者名称
       └─ Priority 200: UserMessageMiddleware → 构建最终 user message（时间戳 + 系统引导）
  ↓
Assemble() → [system message] + [history] + [user message]
  ↓
Run() [agent/engine.go:189, 包级函数 func Run(ctx, cfg)]
  ├─ 发给 LLM
  ├─ LLM 返回 tool calls → 执行工具
  ├─ sys_reminder 注入（仅追加到 tool message 末尾）
  └─ 循环直到 LLM 返回文本（无 tool calls）

关键发现：system message 在 buildPrompt 时构建一次，整个 Run() 循环中不再重建。

文件: agent/reminder.go
注入位置: engine.go:930-933，追加到最后一个 tool message 的 Content 末尾
触发条件: LLM 返回 tool calls 时（engine.go:924 条件分支内）
注入内容: 用户任务目标、工具调用总数、本轮工具名称、TODO 摘要、行为提醒
格式: <system-reminder>\n...\n</system-reminder>
关键特性: sys_reminder 是目前唯一在 Run() 循环中每轮动态注入的机制，但它只追加到 tool message content 中，不影响 system message。

重要：虽然 system prompt 中的 CWD 文本不更新，但 Shell、Glob、Grep、Read 等工具的实际执行目录是正确的。

原因：每次工具调用时，buildToolContext() 都会从 cfg.Session.GetCurrentDir() 重新读取最新的 CWD（engine.go:1162），并设置到 tc.CurrentDir 中。Cd 工具调用 session.SetCurrentDir() 后，下一次工具调用的 buildToolContext() 自然会读到新值。

因此，问题 仅存在于 system prompt 中的文本展示——LLM 看到的目录文字是旧的，但实际工具执行在新目录。这可能导致 LLM 在思考/推理中引用错误路径。

关键差异: xbot 的 Cd 工具使 CWD 在运行时变化，这是 xbot 特有的问题。

核心思想: 不重建整个 system message，而是在 Run() 循环的每个 iteration 中，检测哪些动态信息发生了变化，将变化的部分以 <dynamic-context> 标签注入到最新的 tool message 中（与 sys_reminder 类似的注入方式，但注入顺序在 sys_reminder 之前）。

Run() 循环（每个 iteration）
  ├─ 执行工具
  ├─ 构建 DynamicSnapshot（当前 CWD）
  ├─ 对比上一个 Snapshot，检测变化
  ├─ 如有变化 → 注入 <dynamic-context> 到最新 tool message（在 sys_reminder 之前）
  └─ 注入 sys_reminder（现有机制）

Step 1: 定义 DynamicContextInjector

文件: agent/dynamic_context.go（新文件，保持 engine.go 精简）

package agent

import (
	"fmt"
	"strings"

	"xbot/llm"
)

// DynamicSnapshot 动态上下文快照，用于检测运行时变化
type DynamicSnapshot struct {
	CWD string // 当前工作目录
}

// DynamicContextInjector 在 Run() 循环中检测动态信息变化并注入
type DynamicContextInjector struct {
	lastSnapshot *DynamicSnapshot
	getCWD       func() string // 获取当前 CWD 的函数（兼容主 Agent 和 SubAgent）
}

// NewDynamicContextInjector 创建动态上下文注入器
func NewDynamicContextInjector(getCWD func() string) *DynamicContextInjector {
	return &DynamicContextInjector{
		getCWD: getCWD,
	}
}

// InjectIfNeeded 检测动态信息变化，如有变化则注入到最新 tool message
// 注入顺序在 sys_reminder 之前（dynamic-context 描述事实，sys_reminder 描述行为引导）
func (d *DynamicContextInjector) InjectIfNeeded(messages []llm.ChatMessage) {
	current := DynamicSnapshot{CWD: d.getCWD()}
	if d.lastSnapshot == nil {
		d.lastSnapshot = &current
		return // 首轮不注入（system prompt 中的值已是最新的）
	}

	var changes []string
	if current.CWD != d.lastSnapshot.CWD {
		changes = append(changes, fmt.Sprintf("- 当前目录已切换为：%s，切换后所有 Shell 命令在新目录执行", current.CWD))
	}

	if len(changes) == 0 {
		d.lastSnapshot = &current
		return
	}

	// 注入到最新 tool message 末尾
	if len(messages) > 0 {
		lastIdx := len(messages) - 1
		injection := "<dynamic-context>\n环境变化:\n" + strings.Join(changes, "\n") + "\n</dynamic-context>"
		messages[lastIdx].Content += "\n\n" + injection
	}

	d.lastSnapshot = &current
}

Step 2: 在 Run() 函数开头创建实例

DynamicContextInjector 作为 Run() 函数的局部变量创建，不放入 RunConfig：

func Run(ctx context.Context, cfg RunConfig) *RunOutput {
	// ... 现有初始化代码 ...

	// 动态上下文注入器（兼容主 Agent 和 SubAgent）
	dynamicInjector := NewDynamicContextInjector(func() string {
		if cfg.Session != nil {
			if dir := cfg.Session.GetCurrentDir(); dir != "" {
				return dir
			}
		}
		// SubAgent 场景：使用 cfg.InitialCWD（无 session，通过闭包捕获）
		return cfg.InitialCWD
	})

	// ... Run() 循环 ...
}

Step 3: 在 Run() 循环中集成注入点

在 engine.go 的 Run() 函数中，在 sys_reminder 注入之前（约第 920 行 sys_reminder 注入点之前）插入：

// --- Dynamic Context 注入（CWD 变化检测）---
dynamicInjector.InjectIfNeeded(messages)

// --- System Reminder 注入 ---
if len(response.ToolCalls) > 0 {
	// ... 现有 sys_reminder 代码 ...
}

注入顺序说明：<dynamic-context> 在 <system-reminder> 之前注入，因为它描述的是事实性环境变化，而 sys_reminder 是行为引导。

当前 system message 标记了 CacheHint = "static"（middleware.go:155），这是正确的——system message 本身不变。动态注入通过追加到 tool message content 中（与 sys_reminder 相同方式），不影响 system prompt 的 cache 命中。

本方案影响面极小，回滚步骤：

1. 删除新文件 agent/dynamic_context.go（~50 行）
2. 删除 Run() 中 NewDynamicContextInjector(...) 创建语句（~10 行）
3. 删除 Run() 中 dynamicInjector.InjectIfNeeded(messages) 调用（1 行）

总计约 61 行新增代码（含独立文件），删除即回滚，无数据库/配置变更。

1. 注入频率: Cd 与其他写工具串行执行（读写分离逻辑），InjectIfNeeded 在所有工具执行完毕后统一检测差异，保证每个 iteration 最多注入一次
2. 内容精简: 动态注入应尽量简洁，避免增加过多 context 消耗
3. SubAgent 兼容: SubAgent 无 session，通过 getCWD 闭包捕获 cfg.InitialCWD，即使被 Cd 闭包修改（engine.go:1172），也能正确反映最新值
4. 与 context_edit 的交互: context_edit 可删除/修改历史消息，但 DynamicContextInjector 只关注 messages 切片最新状态，不受影响
5. 注入顺序: <dynamic-context> 必须在 <system-reminder> 之前注入，确保事实信息先于行为引导

• 编译错误：fmt.Sprintf 缺少 %s 占位符 → 已修复
• 初始化位置不明确 → 已明确为 Run() 局部变量
• SubAgent 兼容不够具体 → 已通过 getCWD func() string 解决
• 缺少回滚方案 → 已补充
• 未说明 Shell 执行目录实际正确 → 已补充说明

• 代码引用全部经核实与源码吻合
• 技术实现正确且精简（~61 行）
• 回滚路径清晰，风险可控
• 3 条优化建议（非阻塞）：
  1. 独立文件 agent/dynamic_context.go（已采纳）
  2. 修正 Cd 并行描述（已采纳）
  3. 补充 context_edit 测试场景（已采纳）