Inbox/Prompt模板/05_Agent优化与修改模板库.md

E. 类别五：“从一到一百”（优化与修改） (Optimization & Modification)

模板索引 (Index)

模板ID	核心用途	使用场景 / 关键词
E-1: 代码重构与迁移
E1	全局符号重命名	重构引擎, 成员限定重命名, 语义安全
E2	跨文件依赖迁移	库替换, API映射, 头文件调整
E3	全局代码规范化与格式化	规则批处理, 指针现代化, 花括号规范
E4	跨文件性能优化	瓶颈函数替换, 语义重构, 变量/常量同步
E-2: 功能增强与同步
E5	基于评审列表的全局修改	Review执行, 定位行号, 批处理变更
E6	接口扩展与实现同步	纯虚方法新增, 派生类stub同步
E7	文档-代码同步审查与修复	头文件签名提取, Markdown更新

---

子类别 E-1: 代码重构与迁移 (Refactoring & Migration)

---

模板名称： E1: [Agent模板] 全局符号重命名 适用场景： D4 (Agent) 模式。对整个工作区（@workspace）中一个特定的符号（如类名、方法名、函数名）进行全局、上下文感知的重命名。 内嵌原则： [原则二：任务解构] (D4)、[原则八：决定论] (要求精确、非创造性修改)。

[Prompt 模板]

角色：你是一个精确的、上下文感知的C++重构引擎。

任务：请在整个工作区（@workspace）执行一次全局符号重命名。

== 重构规格 (Specification) ==
1.  旧符号 (Old Symbol)： [例如：getData]
2.  新符号 (New Symbol)： [例如：readData]
3.  重构上下文 (Context)：
    - 这是一个绝对约束。
    - 你只能重命名 [旧符号]，当且仅当它属于 [类名/接口名，例如：IDataSource] 或其任何派生类（Derived Class）的成员。
    - 严禁重命名在其他不相关类中同名的 [旧符号]。

== 执行计划 (Execution Plan) ==
1.  扫描范围： 整个工作区（@workspace）。
2.  目标文件类型： [例如：*.cpp, *.h, *.hpp, *.md, *.txt] (覆盖代码和文档)。
3.  C++ 代码修改 (.cpp, .h, .hpp)：
    - 查找并替换所有符合 [重构上下文] 约束的符号。
    - 这包括：
        - (a) 头文件中的 virtual 声明。
        - (b) 实现类中的定义（Definition）。
        - (c) 所有使用 . 或 -> 对该成员的调用点（Call Sites）。
4.  文档修改 (.md, .txt)：
    - 查找并替换所有对 [旧符号] 的文本引用（例如API文档、README）。

== 最终约束 ==
- 你的修改必须是原子性的、上下文感知的。
- 严禁修改任何与此重构任务无关的代码逻辑。

填充指南：

• [旧符号] 和 [新符号]：提供明确的名称。
• [类名/接口名]：这是此模板最关键的约束。它将Agent的行为从“全局查找替换”限制为“上下文感知的重构”，确保了修改的精确性，防止了对不相关代码的破坏。
• [目标文件类型]：根据需要调整，确保文档（如README.md）也被一并更新。

---

模板名称： E2: [Agent模板] 跨文件依赖迁移 适用场景： D4 (Agent) 模式。在整个代码库中，将一个废弃的库（如OldLogger）的API调用，完整迁移到一个新的库（如spdlog）。 内嵌原则： [原则二：任务解构] (D4)、[原则六：示例优先] (迁移规则即示例)、[原则五：上下文即燃料]。

[Prompt 模板]

角色：你是一名精通C++库迁移的软件工程师。

任务：请在整个工作区（@workspace）执行一次API依赖迁移。

== 迁移目标 ==
- 从 (Old API)： [例如：OldLogger 库]
- 到 (New API)： [例如：spdlog 库]

== 迁移规则 (必须严格遵守) ==
这是此次迁移的核心映射表。你必须在所有相关文件中应用这些规则：

1.  头文件管理 (Header Management)：
    - 移除 (Remove)： [例如：在所有文件中移除 #include "OldLogger.h"]
    - 添加 (Add)： [例如：在需要的文件顶部添加 #include "spdlog/spdlog.h"] (如果尚未存在)

2.  API 调用映射 (API Call Mapping)：
    - 规则 1 (From)： [例如：OldLogger::Log(LOG_DEBUG, ...)]
    - 规则 1 (To)： [例如：spdlog::debug(...)]

    - 规则 2 (From)： [例如：OldLogger::Log(LOG_INFO, ...)]
    - 规则 2 (To)： [例如：spdlog::info(...)]

    - 规则 3 (From)： [例如：OldLogger::Log(LOG_WARN, ...)]
    - 规则 3 (To)： [例如：spdlog::warn(...)]

    - 规则 4 (From)： [例如：OldLogger::Log(LOG_ERR, ...)]
    - 规则 4 (To)： [例如：spdlog::error(...)]

    - 规则 5 (From)： [例如：OldLogger::Init(...)]
    - 规则 5 (To)： [例如：spdlog::default_logger()->set_level(...)]

== 执行计划 ==
1.  扫描范围： 整个工作区（@workspace）。
2.  目标文件类型： [例如：*.cpp, *.h, *.hpp, CMakeLists.txt]
3.  执行：
    - (a) 扫描所有目标文件。
    - (b) 应用 [头文件管理] 规则。
    - (c) 应用 [API 调用映射] 规则，确保参数（...）被正确传递。
    - (d) (可选) 如果 [CMakeLists.txt] 中有链接库，也请更新。

填充指南：

• [迁移规则]：这是此模板的核心。你必须提供详尽的、模式匹配的“From-To”列表。[原则六：示例优先] 在此体现为“规则即示例”，Agent将模仿这些规则进行替换。
• [... ] (省略号)：用于告知AI保留原始调用的参数。

---

模板名称： E3: [Agent模板] 全局代码规范化与格式化 适用场景： D4 (Agent) 模式。当自动化工具（如linter）缺失或不足时，用于在整个代码库中强制执行特定的、语义化的编码规范。 内嵌原则： [原则二：任务解构] (D4)、[原则六：示例优先] (格式化规则)、[原则八：决定论]。

[Prompt 模板]

角色：你是一个自动化的代码质量 Linter 和 Formatter。

任务：请在整个工作区（@workspace）审查并修复所有违反以下规范的代码。

== 目标文件类型 ==
- [例如：*.cpp, *.h, *.hpp]

== 规范规则集 (必须全部应用) ==
1.  规则 1：[例如：指针现代化]
    - 查找 (Find)： [例如：NULL]
    - 替换 (Replace)： [例如：nullptr]
    - 约束： [例如：仅当 NULL 被用作指针字面量时。严禁替换字符串或宏定义中的 "NULL"。]

2.  规则 2：[例如：强制代码块花括号]
    - 查找 (Find Pattern)： [例如：
        if (condition)
            statement;
        // 或
        if (condition) statement;
        ]
    - 替换 (Replace Pattern)： [例如：
        if (condition) {
            statement;
        }
        ]
    - 适用范围： [例如：必须应用于 if, else, for, while 语句。]

3.  规则 3：[例如：移除 C 风格类型转换]
    - 查找 (Find Pattern)： [例如：(MyType*)ptr]
    - 替换 (Replace Pattern)： [例如：static_cast<MyType*>(ptr)]
    - 约束： [例如：仅适用于 static_cast。如果需要 reinterpret_cast，请添加 // TODO: Review C-Style Cast 注释。]

== 全局约束 ==
- 你只能应用上述 [规范规则集] 中定义的修改。
- 严禁重构、修改或“优化”任何与这些规则无关的代码逻辑。

填充指南：

• [规范规则集]：此模板的核心。你必须为每一条规则提供清晰的“查找”和“替换”模式，这是 [原则六：示例优先] 的体现。
• [约束]：为复杂规则（如NULL替换）添加约束，可显著提高Agent的准确性。

---

模板名称： E4: [Agent模板] 跨文件性能优化 适用场景： D4 (Agent) 模式。在D2模式或人工分析（Profiling）确定了瓶颈后，使用此模板指导Agent执行一个具体的、跨文件的优化方案。 内嵌原则： [原则二：任务解构] (D4)、[原则二：玻璃盒心态] (Rationale部分)、[原则五：上下文即燃料]。

[Prompt 模板]

角色：你是一名精通C++和HPC（高性能计算）的优化专家。

任务：请在整个工作区（@workspace）执行一个已确定的性能优化方案。

== 优化上下文 (Rationale) ==
- 瓶颈函数： [例如：utils::compute_distance(Point p1, Point p2)]
- 瓶颈分析： [例如：此函数被高频调用，其内部的 sqrt 造成了巨大开销。]
- 优化目标： [例如：在所有调用链中，用“平方距离比较”替换“真实距离比较”，以消除 sqrt。]

== 优化执行计划 (必须严格遵守) ==

Step 1：修改被调用函数 (Callee)
1.  定位文件： [例如：src/utils.h 和 src/utils.cpp]
2.  动作 1.1 (重命名)： 将 [瓶颈函数] 重命名为 [新函数名，例如：utils::compute_distance_squared]。
3.  动作 1.2 (修改实现)： 修改 [新函数名] 的实现，[例如：移除内部的 sqrt 调用，使其直接返回平方和 (dx*dx + dy*dy)]。

Step 2：修改调用方 (Callers)
1.  扫描范围： 整个工作区（@workspace）中所有调用了 [瓶颈函数] 的文件。
2.  对每一个调用点 (Call Site) 执行以下语义重构：
3.  动作 2.1 (重命名调用)： 将 [瓶颈函数] 的调用替换为 [新函数名]。
4.  动作 2.2 (跟踪返回值)：
    - 识别存储该函数返回值的变量 (例如：float distance = ...)。
    - 将该变量重命名为 (例如：float distance_squared = ...)。
5.  动作 2.3 (修复比较逻辑)：
    - 查找所有使用该 [变量] 的地方 (例如：if (distance < MAX_DISTANCE)).
    - 必须将比较值也修改为平方 (例如：if (distance_squared < MAX_DISTANCE_SQUARED))。
    - 你需要（或定义）一个新的常量 [例如：MAX_DISTANCE_SQUARED]。

== 最终约束 ==
- 这是一个语义重构，而非简单的查找替换。
- 你必须在 [Step 2] 中正确跟踪返回值，并修复其所有使用点的比较逻辑，以确保优化后的程序逻辑等价。

填充指南：

• [优化上下文]：必须清晰描述“Why”，这有助于Agent理解任务意图（玻璃盒原则）。
• [优化执行计划]：这是此模板的核心。它将一个复杂的、D2分析得出的优化方案，“解构”为一个D4 Agent可以逐步执行的、确定性的计划。
• [动作 2.2] 和 [动作 2.3] 是最关键的步骤，它们要求Agent具备跟踪变量和修复语义的能力，这是D4 Agent的核心价值。

---

子类别 E-2: 功能增强与同步 (Enhancement & Synchronization)

---

模板名称： E5: [Agent模板] 基于评审列表的全局修改 适用场景： D4 (Agent) 模式。将Code Review的结论（通常是一个Markdown或文本文件）作为“任务列表”，指导Agent（@workspace）自动在整个代码库中定位并应用这些修改。 内嵌原则： [原则二：任务解构] (D4)、[原则五：上下文即燃料] (评审文件是核心燃料)、[原则八：决定论]。

[Prompt 模板]

角色：你是一个自动化代码审查执行代理（Automated Review Executor）。

任务：请读取我提供的 [评审意见文件] (例如 @file:reviews/pr_101.md)，逐条解析其中的修改项，并在 @workspace 中定位并应用所有修改。

== 执行上下文 ==
1.  工作区： @workspace
2.  评审意见文件 (必须在调用时提供)： [例如：@file:reviews/pr_101.md]
3.  评审项格式 (假设)： 假设文件中的每一项都遵循 [例如：“Item X: [File: path/to/file.cpp] [Line: Y] [Change: '...']”] 或类似的结构。

== 执行计划 (Execution Plan) ==
1.  读取 (Read)： 打开并逐行读取 [评审意见文件]。
2.  解析与循环 (Parse & Loop)： 遍历文件中的每一条修改项 (例如, "Item 1:", "缺陷 2:")。
3.  对每一个修改项 (For Each Item)：
    - (a) 定位 (Locate)： 提取 [文件名] 和 [行号] (如果提供)。
    - (b) 理解 (Understand)： 提取 [修改要求] (例如：“增加空指针检查”、“将 int 改为 size_t”、“移除多余的 printf”)。
    - (c) 执行 (Execute)： 打开 [文件名]，导航到 [行号]（或相关代码上下文），并精确地应用 [修改要求]。

== 黄金约束 (Golden Constraints) ==
1.  精确性 (Precision)： 你的修改必须100%符合 [修改要求]。严禁进行任何“自由发挥”的额外重构、代码清理或格式化（除非修改要求本身就是格式化）。
2.  原子性 (Atomicity)： 必须逐条应用修改。
3.  歧义处理 (Ambiguity Handling)： 如果 [评审意见文件] 中的某一条指令不清晰、无法定位（例如行号已改变）或无法安全实现，你必须跳过该项。
4.  报告 (Reporting)： 任务完成后，必须提供一份报告，列出：
    - (a) [成功应用] 的修改项列表。
    - (b) [跳过] 的修改项列表及其原因（例如：歧义、代码已变更）。
5.  范围 (Scope)： 严禁修改 [评审意见文件] 中未提及的任何文件或代码。

填充指南：

• 使用指南： 此模板不是一次性粘贴。用户必须在调用Agent时，在Prompt中明确提供 [评审意见文件] 的路径，例如：@workspace @file:reviews/pr_101.md [粘贴此模板的剩余部分]。
• [评审项格式]：如果你的评审文件格式很固定，在此处提供示例（原则六）将极大提高Agent的解析准确率。

---

模板名称： E6: [Agent模板] 接口扩展与实现同步 适用场景： D4 (Agent) 模式。在面向接口编程中，当一个核心接口（基类）发生变更（如添加新方法）时，自动在 @workspace 中找出所有实现（派生）类，并为其同步添加该方法（Stub）的桩实现。 内嵌原则： [原则二：任务解构] (D4，多步骤计划)、[原则五：上下文即燃料]、[原则六：示例优先] (桩实现规范)。

[Prompt 模板]

角色：你是一名精通C++面向对象设计和大规模重构的专家。

任务：请在 @workspace 中执行一次“接口扩展”重构，并自动同步所有实现类。

== 执行计划 (Execution Plan) ==
这是一个多步骤任务，请严格按顺序执行：

Step 1: 扩展接口 (Extend Interface)
1.  定位文件 (Target File)： [例如：@file:src/interfaces/IProcessor.h]
2.  接口名 (Interface Name)： [例如：IProcessor]
3.  执行动作 (Action)： 在 [接口名] 类的 [例如：public] 区域，添加以下新的纯虚函数：
    [粘贴新函数的完整签名，例如：
    virtual bool initialize(const Config& cfg) = 0;
    ]

Step 2: 查找所有实现类 (Find Implementations)
1.  扫描范围 (Scan Scope)： 整个工作区（@workspace）。
2.  目标 (Target)： 查找所有 public 继承自 [接口名] 的C++类 (例如：class CpuProcessor : public IProcessor, class GpuProcessor : public IProcessor)。

Step 3: 同步所有实现类 (Synchronize Implementations)
1.  循环 (Loop)： 对 [Step 2] 中找到的每一个实现类（例如 CpuProcessor）：
2.  动作 3.1 (更新头文件 .h)：
    - 打开该类的 .h 文件 (例如：src/cpu/CpuProcessor.h)。
    - 在 [例如：public] 区域添加对应的方法声明 (移除 = 0 并添加 override 关键字)：
      [粘贴新方法在派生类.h中的签名，例如：
      bool initialize(const Config& cfg) override;
      ]
3.  动作 3.2 (添加桩实现 .cpp)：
    - 打开该类的 .cpp 文件 (例如：src/cpu/CpuProcessor.cpp)。
    - 在文件末尾（或合适位置）添加该方法的“桩函数”实现。
    - 桩实现规范 (必须严格遵守此模板)：
      [粘贴桩实现的完整代码块，例如：
      bool CpuProcessor::initialize(const Config& cfg) {
          // TODO(JIRA-123 / [负责人]): Implement initialize() for CpuProcessor.
          (void)cfg; // 避免 "unused parameter" 警告
          return true; // 或 false, 或 0, 或 {}
      }
      ]

== 最终约束 ==
- [桩实现规范] 必须被严格遵守，特别是 // TODO: 标记、默认返回值和(可选的)(void)param警告抑制，以确保代码库一致性并可编译。

填充指南：

• [Step 1] 和 [Step 3] 中的代码块是必须提供的。这是[原则六：示例优先]的应用，你必须给Agent提供精确的“目标代码”和“桩代码”模板，它才能正确执行。
• [桩实现规范] 中的默认返回值（如true）应由工程师根据接口语义（LSP原则）来决定。

---

模板名称： E7: [Agent模板] 文档-代码同步审查与修复 适用场景： D4 (Agent) 模式。维护“活文档”（Living Documentation）。自动扫描代码库（如.h文件）和文档（如.md文件），找出两者之间的差异（如函数签名已变更），并自动修复文档以匹配代码。 内嵌原则： [原则二：任务解构] (D4)、[原则五：上下文即燃料] (代码和文档路径)、[原则八：决定论]。

[Prompt 模板]

角色：你是一名严格的技术文档作者（Technical Writer），负责保持文档与代码的绝对同步。

任务：请在 @workspace 中审查代码和文档，找出不一致的地方，并只更新文档使其与代码（Source of Truth）保持一致。

== 同步上下文 ==
1.  代码源 (Source of Truth)： [例如：@dir:src/public_api/] (指定包含 .h 头文件的目录)
2.  文档目标 (Target to Fix)： [例如：@file:docs/Public_API_Reference.md]

== 执行计划 (Execution Plan) ==

Step 1: 扫描代码源 (Parse Source of Truth)
1.  遍历 [代码源] 目录下的所有 [例如：.h 或 .hpp] 文件。
2.  为所有 public [例如：函数/类/方法] 提取其“当前函数签名”（包括函数名、参数类型、返回值类型）。

Step 2: 扫描文档目标 (Parse Documentation)
1.  打开 [文档目标] 文件。
2.  解析 Markdown，提取其中（例如：在###标题下或表格中）描述的每一个 [例如：函数/方法] 及其“文档签名”。

Step 3: 对比与修复 (Compare & Fix)
1.  循环 (Iterate)： 遍历 [Step 1] 中提取的每一个“当前函数签名”。
2.  检查 (Check)：
    - (a) 如果在文档中未找到 (Missing Doc)：
        - 动作： 在 [文档目标] 文件的 [例如：API列表末尾] 添加该新函数的文档骨架（例如：一个新的 ### [函数名] 章节），并添加一个明确的占位符：
    - (b) 如果在文档中已找到，但签名不匹配 (Outdated Doc)：
        - 动作： 更新 [文档目标] 中的“文档签名”（例如：Markdown表格中的参数、标题），使其与 [Step 1] 中提取的“当前函数签名”严格一致。
3.  (可选) 检查废弃项 (Deprecated Doc)：
    - 遍历 [Step 2] 的“文档签名”，如果在 [Step 1] 的代码中不存在该函数。
    - 动作： 在 [文档目标] 中该函数的部分，添加一个明确的 [DEPRECATED] 标记，或将其移至“废弃API”章节。

== 黄金约束 (Golden Constraint) ==
- 单向同步 (Code-to-Doc)： 你的任务是使文档匹配代码。
- 严禁 (FORBIDDEN)： 严禁以任何理由修改 [代码源] 目录下的任何 .h 或 .cpp 文件。所有修改必须且只能在 [文档目标] 文件上进行。

填充指南：

• [代码源] 和 [文档目标]：必须提供。用户在调用时必须明确指定Agent的扫描范围（@dir）和修改目标（@file）。
• [Step 3] 的计划非常详细，这是为了确保Agent执行的是“修复”而非“重写”，并正确处理“新增”和“过时”两种情况。

---