CodeWave IDE

Appearance

功能规格说明：提示工程框架 ​

创建日期：2026-03-25

用户场景与测试 （必填） ​

用户故事：集中式提示管理（优先级：P1） ​

作为开发者，我希望以集中和结构化的方式管理所有系统提示和工具描述，以便我可以轻松更新、版本化和优化它们而不修改核心逻辑。

为什么是这个优先级：这是该功能的核心价值，实现代理行为的更好可维护性和迭代。

独立测试：可以通过验证所有提示被移动到专用提示管理系统且代理仍然行为正确来测试。

验收场景：

  1. 假设有一组系统提示和工具描述，当我将它们移动到提示工程框架时，则代理应该在初始化期间仍然接收正确的提示
  2. 假设框架已就位，当我在框架中更新提示时，则代理应该在下一次会话中立即使用更新后的提示

用户故事：动态工具描述（优先级：P1） ​

作为开发者，我希望基于当前上下文（如可用子代理、技能或工作目录）提供动态工具描述，以便代理拥有工具选择的最相关信息。

为什么是这个优先级：这已经通过工具中的 prompt() 部分实现，但在框架内形式化将使其更健壮和易于管理。

独立测试：可以通过验证工具描述基于提供的上下文变化来测试。

验收场景：

  1. 假设带有动态提示的工具，当工具以不同上下文注册时，则工具在 OpenAI 函数调用配置中的描述应该反映每个上下文的正确提示

用户故事：System-Reminder 消息注入（优先级：P1） ​

作为开发者，我希望将临时指令作为 <system-reminder> 包装的用户消息（而非系统提示更改）注入对话，以便系统提示在模式切换间保持不变，保持提示缓存并减少 token 成本。

为什么是这个优先级：在会话中途修改系统提示（如附加计划模式指令）会在每次模式更改时失效整个缓存的系统提示前缀。将指令作为带 <system-reminder> 标签的用户消息注入保持缓存同时仍然向模型传递上下文指令。此模式被 Claude Code 用于所有动态模式特定指导。

独立测试：进入计划模式，验证系统提示与上一轮相同且计划模式指令作为 <system-reminder> 用户消息出现在 API 请求中。

验收场景：

  1. 假设代理进入计划模式，当下一个 API 请求被组装时，则计划模式指令必须作为 <system-reminder> 包装的用户消息注入，而非附加到系统提示
  2. 假设代理退出计划模式，当下一个 API 请求被组装时，则"退出计划模式"的 <system-reminder> 用户消息必须被注入（仅一次）
  3. 假设代理在退出后重新进入计划模式，当计划文件已存在时，则重新进入的 <system-reminder> 用户消息必须被注入，指示模型读取现有计划并评估是继续还是重新开始
  4. 假设系统提示已被先前请求缓存，当模式切换发生时，则系统提示必须保持字节相同，启用系统消息前缀的缓存命中

用户故事：节流提醒注入（优先级：P2） ​

作为开发者，我希望计划模式提醒被节流，以便它们仅每 N 个人类轮次注入一次（不是每个工具轮次），以减少 token 浪费同时保持约束意识。

为什么是这个优先级：没有节流，计划模式提醒在每次 API 调用（包括单个人类轮次内的工具轮次）时注入，浪费 token。节流到每 5 个人类轮次减少成本，同时定期完整提醒防止模型忘记约束。

独立测试：在计划模式下工作 10+ 轮，验证提醒每 5 个人类轮次出现一次，在完整版本和稀疏版本之间交替。

验收场景：

  1. 假设计划模式活跃且提醒刚被注入，当不到 5 个人类轮次过去时，则不注入计划模式提醒
  2. 假设自上次提醒以来已过去 5 个人类轮次，当下一个 API 请求发出时，则注入计划模式提醒
  3. 假设每第 5 次提醒注入，当提醒被注入时，则它必须是完整的计划模式指令（完整的 5 阶段工作流）
  4. 假设非第 5 次提醒注入，当提醒被注入时，则它必须是引用先前完整指令的简短稀疏提醒

用户故事：模式切换的覆盖语言（优先级：P1） ​

作为开发者，我希望在模式切换后注入的 <system-reminder> 指令包含明确的覆盖语言（如"This supercedes any other instructions you have received"），以便模型理解新约束优先于对话中先前的工具调用历史。

为什么是这个优先级：当在对话中途从 default/acceptEdits 模式切换到计划模式时，消息历史包含最近的 Edit/Write 工具调用，可能误导模型继续编辑。覆盖语言加上提醒是模型看到的最近指令，确保模型遵守新模式约束。

独立测试：进行包含 Edit/Write 工具调用的对话，然后进入计划模式，验证计划模式提醒包含"supercedes"覆盖语言并出现在消息流中所有先前工具调用之后。

验收场景：

  1. 假设对话包含最近的 Edit/Write 工具调用，当用户进入计划模式时，则计划模式 <system-reminder> 必须作为 API 请求中的最后一条用户消息注入（在所有先前工具调用之后）
  2. 假设计划模式提醒被注入，当模型读取它时，则提醒必须包含"This supercedes any other instructions you have received"或等效覆盖语言
  3. 假设计划模式提醒在模式切换后被注入，当模型尝试对计划文件以外的任何文件使用 Edit 或 Write 时，则权限系统在运行时阻止该操作（纵深防御）

边界情况 ​

  • 缺失的提示：当框架中缺少必需提示时会发生什么？（系统应该回退到默认提示或显示清晰的错误消息）
  • 大型提示：系统如何处理可能超过 token 限制的非常大提示？（框架应该提供提示压缩或截断工具）
  • 冲突的提示：系统如何处理来自不同提示来源的冲突指令？（框架应该定义明确的优先级顺序）
  • 快速模式切换：当用户在计划和非计划模式之间快速切换时，进入和退出的 <system-reminder> 消息不应同时注入。重新进入计划模式时应清除退出附加标志
  • 压缩后重新进入：当压缩移除所有对话历史包括先前的 <system-reminder> 消息时，系统必须重新注入完整的计划模式提醒（非稀疏），因为没有更早的完整指令存在