From c6fd07960a6654d269544c83099476b3b5d607aa Mon Sep 17 00:00:00 2001 From: lewis617 Date: Fri, 3 Jul 2026 11:15:22 +0800 Subject: [PATCH] refactor: simplify task reminder injection and add context message structure overview - Remove tail injection of task reminder; persist as meta message only - Update FR-030 spec to reflect simplified injection logic - Add context message structure overview table to specs/README.md --- packages/agent-sdk/src/managers/aiManager.ts | 14 +------------- specs/043-task-management-tools.md | 2 +- specs/README.md | 14 ++++++++++++++ 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/packages/agent-sdk/src/managers/aiManager.ts b/packages/agent-sdk/src/managers/aiManager.ts index 3eb71a75..59691de9 100644 --- a/packages/agent-sdk/src/managers/aiManager.ts +++ b/packages/agent-sdk/src/managers/aiManager.ts @@ -891,25 +891,13 @@ export class AIManager { }); } - // Append: task reminder as system-reminder at tail (conditional rules already persisted above) - const tailParts: string[] = []; - + // Task reminder: persist as meta message (conditional rules already persisted above) const taskReminderText = await this.maybeGetTaskReminderText(toolNames); if (taskReminderText) { - // Persist to messageManager so turn counter can find the marker on future turns this.messageManager.addUserMessage({ content: taskReminderText, isMeta: true, }); - // Also inject into current turn's API call (persisted message won't be in recentMessages) - tailParts.push(taskReminderText); - } - - if (tailParts.length > 0) { - callAgentOptions.messages.push({ - role: "user", - content: `\n${tailParts.join("\n\n")}\n`, - }); } // Add streaming callbacks only if streaming is enabled diff --git a/specs/043-task-management-tools.md b/specs/043-task-management-tools.md index 8489e521..9ae6f931 100644 --- a/specs/043-task-management-tools.md +++ b/specs/043-task-management-tools.md @@ -139,7 +139,7 @@ - **FR-027**：当任务列表非空时，提醒消息末尾必须附加当前任务列表，格式为 `#id [status] subject`（每个任务一行）。 - **FR-028**：当任务列表为空时，提醒消息必须仍然注入，作为通用提醒鼓励 agent 使用任务跟踪功能，但不附加任务列表。 - **FR-029**：提醒消息的文本必须明确指示 agent 不得向用户提及该提醒的存在。 -- **FR-030**：任务提醒必须持久化到会话历史中作为 `isMeta: true` 用户消息，确保轮次计数器能找到之前的提醒标记（``），避免每轮重复注入。当前轮额外注入到 tail `` 供 API 可见。 +- **FR-030**：任务提醒必须持久化到会话历史中作为 `isMeta: true` 用户消息，确保轮次计数器能找到之前的提醒标记（``），避免每轮重复注入。 - **FR-031**：如果 TaskCreate 和 TaskUpdate 工具不在当前 agent 的可用工具集中，系统必须完全跳过任务提醒逻辑，不注入任何提醒消息。 ### 关键实体 *（如果功能涉及数据则包含）* diff --git a/specs/README.md b/specs/README.md index 89dacaa7..81bfce24 100644 --- a/specs/README.md +++ b/specs/README.md @@ -108,3 +108,17 @@ | 服务端托管配置 | 从 Wave AI 下载并应用托管设置，支持校验和缓存和合并优先级 | 3 | 11 | [规格](055-server-managed-config.md) | | OpenTelemetry 集成 | OpenTelemetry 指标、追踪和日志插桩，支持多种导出器（jsonl、OTLP） | 3 | 16 | [规格](052-opentelemetry.md) | | 用量追踪 | SDK 用量追踪回调（`onUsagesChange`），用于 AI 调用和压缩 | 4 | 15 | [规格](010-usage-tracking-callback.md) | + +## 上下文消息结构总览 + +发送给 AI 模型的 `messages` 数组按以下顺序组装： + +| 位置 | 角色 | 内容 | 缓存标记 | 持久化 | 用户可见 | 说明 | +|------|------|------|----------|--------|----------|------| +| [0] | system | 基础系统提示词 + 任务执行准则 + 行动准则 + 工具策略 + 输出效率 + 语气风格 | 有 | 不持久化 | 否 | 子代理替换基础系统提示词，其余相同 | +| | | 语言指令 + `` 环境信息 + 自动记忆 (MEMORY.md) | 无 | 不持久化 | 否 | | +| [1] | user (meta) | ``: 项目 AGENTS.md + 用户 AGENTS.md + 无条件规则 | 无 | 不持久化，每轮插入头部 | 否 | 唯一每轮注入 | +| 历史 | user / assistant / tool | 文本块 / 图片块 / 工具块 / 后台任务通知块 / 推理块 | 最后一条有 | 持久化到 session JSONL | 是 | | +| | user (isMeta) | 计划模式提醒 / 条件规则 / 任务提醒 / Goal 消息 / SessionStart Hook 上下文 / 后台任务通知 / Token 限制续写 | 同上 | 同上 | 否 | 触发时插入当时的结尾，各类型有独立触发条件 | + +**专用调用**（独立系统提示词，不经过主系统提示词组装）：压缩、网页内容提取、BTW 旁路问题、Goal 评估、Workflow 结构化输出。