382 lines
20 KiB
Markdown
382 lines
20 KiB
Markdown
#### E. 类别五：“从一到一百”（优化与修改） (Optimization & Modification)
|
||
|
||
**模板索引 (Index)**
|
||
|
||
| 模板ID | 核心用途 | 使用场景 / 关键词 |
|
||
| :--- | :--- | :--- |
|
||
| **E-1: 代码重构与迁移** | | |
|
||
| **[`E1`](#E1)** | 全局符号重命名 | 重构引擎, 成员限定重命名, 语义安全 |
|
||
| **[`E2`](#E2)** | 跨文件依赖迁移 | 库替换, API映射, 头文件调整 |
|
||
| **[`E3`](#E3)** | 全局代码规范化与格式化 | 规则批处理, 指针现代化, 花括号规范 |
|
||
| **[`E4`](#E4)** | 跨文件性能优化 | 瓶颈函数替换, 语义重构, 变量/常量同步 |
|
||
| **E-2: 功能增强与同步** | | |
|
||
| **[`E5`](#E5)** | 基于评审列表的全局修改 | Review执行, 定位行号, 批处理变更 |
|
||
| **[`E6`](#E6)** | 接口扩展与实现同步 | 纯虚方法新增, 派生类stub同步 |
|
||
| **[`E7`](#E7)** | 文档-代码同步审查与修复 | 头文件签名提取, Markdown更新 |
|
||
|
||
-----
|
||
|
||
**子类别 E-1: 代码重构与迁移 (Refactoring & Migration)**
|
||
<a id="E1"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E1: [Agent模板] 全局符号重命名`
|
||
**适用场景：** `D4 (Agent)` 模式。对整个工作区（`@workspace`）中一个特定的符号（如类名、方法名、函数名）进行全局、上下文感知的重命名。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则八：决定论]` (要求精确、非创造性修改)。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一个精确的、上下文感知的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`）也被一并更新。
|
||
|
||
<a id="E2"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E2: [Agent模板] 跨文件依赖迁移`
|
||
**适用场景：** `D4 (Agent)` 模式。在整个代码库中，将一个废弃的库（如`OldLogger`）的API调用，完整迁移到一个新的库（如`spdlog`）。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则六：示例优先]` (迁移规则即示例)、`[原则五：上下文即燃料]`。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一名精通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保留原始调用的参数。
|
||
|
||
<a id="E3"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E3: [Agent模板] 全局代码规范化与格式化`
|
||
**适用场景：** `D4 (Agent)` 模式。当自动化工具（如linter）缺失或不足时，用于在整个代码库中强制执行特定的、语义化的编码规范。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则六：示例优先]` (格式化规则)、`[原则八：决定论]`。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一个自动化的代码质量 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的准确性。
|
||
|
||
<a id="E4"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E4: [Agent模板] 跨文件性能优化`
|
||
**适用场景：** `D4 (Agent)` 模式。在D2模式或人工分析（Profiling）确定了瓶颈后，使用此模板指导Agent执行一个**具体**的、**跨文件**的优化方案。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则二：玻璃盒心态]` (Rationale部分)、`[原则五：上下文即燃料]`。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一名精通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)**
|
||
<a id="E5"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E5: [Agent模板] 基于评审列表的全局修改`
|
||
**适用场景：** `D4 (Agent)` 模式。将Code Review的结论（通常是一个Markdown或文本文件）作为“任务列表”，指导Agent（`@workspace`）自动在整个代码库中定位并应用这些修改。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (评审文件是核心燃料)、`[原则八：决定论]`。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一个自动化代码审查执行代理（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的解析准确率。
|
||
|
||
<a id="E6"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E6: [Agent模板] 接口扩展与实现同步`
|
||
**适用场景：** `D4 (Agent)` 模式。在面向接口编程中，当一个核心接口（基类）发生变更（如添加新方法）时，自动在 `@workspace` 中找出所有实现（派生）类，并为其同步添加该方法（Stub）的桩实现。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4，多步骤计划)、`[原则五：上下文即燃料]`、`[原则六：示例优先]` (桩实现规范)。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一名精通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原则）来决定。
|
||
|
||
<a id="E7"></a>
|
||
|
||
-----
|
||
|
||
**模板名称：** `E7: [Agent模板] 文档-代码同步审查与修复`
|
||
**适用场景：** `D4 (Agent)` 模式。维护“活文档”（Living Documentation）。自动扫描代码库（如`.h`文件）和文档（如`.md`文件），找出两者之间的差异（如函数签名已变更），并自动**修复文档**以匹配代码。
|
||
**内嵌原则：** `[原则二：任务解构]` (D4)、`[原则五：上下文即燃料]` (代码和文档路径)、`[原则八：决定论]`。
|
||
|
||
**[Prompt 模板]**
|
||
|
||
```txt
|
||
角色：你是一名严格的技术文档作者（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执行的是“修复”而非“重写”，并正确处理“新增”和“过时”两种情况。
|
||
|
||
-----
|