AI 提示词模板：执行型 Agent 与认知型 Ask
适用场景：VS Code、GitHub Copilot、Codex、Cursor、Cline、Roo Code 等代码辅助工具。
核心思路：把 AI 的使用目的分成两类：
- 执行型 Agent：让 AI 帮你实际完成修改、生成文件、运行命令、检查结果。
- 认知型 Ask：让 AI 帮你理解陌生项目、定位代码、解释逻辑、学习原理，但不改文件。
一、使用原则
1. 执行型 Agent 的原则
执行型 Agent 适合用来完成明确任务，例如：
- 修改前端页面样式；
- 添加 Hexo 博客功能；
- 修复报错；
- 重构代码；
- 安装依赖；
- 运行构建命令；
- 检查生成结果。
使用 Agent 时，提示词要强调：
- 先分析，再计划；
- 修改前必须征求确认；
- 每次只改必要文件；
- 说明每一步在做什么；
- 修改后要运行验证命令；
- 报错后先解释原因，再修复；
- 不允许无关改动。
2. 认知型 Ask 的原则
认知型 Ask 适合用来理解问题，例如：
- 某个页面效果由哪些文件控制；
- 某段代码是什么意思；
- 一个功能的实现链路是什么；
- 为什么页面会这样显示；
- 应该搜索哪些关键词；
- 如何逐步验证自己的理解。
使用 Ask 时，提示词要强调：
- 只分析，不修改；
- 不运行终端命令；
- 不自动安装依赖；
- 不生成待应用变更；
- 先解释代码含义；
- 给出定位路径和验证方法；
- 把结论讲清楚，而不是直接动手。
二、通用变量占位符
复制模板时，可以把下面这些字段替换成自己的项目情况。
1
2
3
4
5
6
7
| 【项目类型】：例如 Hexo 博客 / Vue 项目 / React 项目 / Python 脚本 / MATLAB 项目
【使用主题或框架】：例如 Butterfly / Vite / Next.js / Flask / Django
【目标页面】：例如 categories 页面 / 文章详情页 / 首页文章卡片
【目标效果】：例如 分类层级缩进 / 字数统计 / 阅读时间 / 表格样式
【问题截图】：说明截图中你关注的位置和异常现象
【限制条件】：例如 不要修改背景 / 不要动配置 / 每次只改一个文件
【验证方式】：例如 hexo clean && hexo g / npm run build / 打开本地页面检查
|
第一部分：执行型 Agent 提示词
模板 1：安全执行型 Agent 通用模板
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
| # Role: 【项目类型】开发专家（Agent 模式执行）
# Task
请帮我完成以下任务：
【这里写清楚要实现的功能或要解决的问题】
# 项目信息
- 项目类型：【项目类型】
- 使用主题或框架：【使用主题或框架】
- 目标页面或文件：【目标页面】
- 目标效果：【目标效果】
# 执行要求
请按以下流程执行：
1. 先分析当前项目结构，判断该功能可能涉及哪些文件；
2. 列出你准备修改的文件路径，并说明每个文件为什么需要修改；
3. 在真正修改文件之前，必须先把修改计划发给我确认；
4. 未经我明确同意，不要修改任何文件；
5. 每次只修改必要文件，不要做无关重构；
6. 每一步操作都要同步告诉我你正在做什么；
7. 如果需要安装依赖，请先说明依赖名称、用途和安装命令，等我确认后再执行；
8. 修改完成后，运行必要的构建或检查命令；
9. 如果出现报错，请先解释报错原因，再提出修复方案；
10. 最后总结修改了哪些文件、实现了什么效果、如何验证。
# 限制条件
- 不要删除已有内容；
- 不要修改与本任务无关的文件；
- 不要一次性提交多个不相关改动；
- 不要在未确认前运行安装命令；
- 不要在未确认前应用变更。
请先只输出分析结果和修改计划，等待我确认后再执行。
|
模板 2：Hexo 功能添加 Agent 模板
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
| # Role: Hexo 前端开发专家（Agent 模式执行）
# Task
请为我的 Hexo 博客实现以下功能：
【例如：为所有文章列表页和文章详情页添加“字数统计”和“预计阅读时间”】
# 项目信息
- 项目类型：Hexo 博客
- 主题：【例如 Butterfly】
- 目标页面：【例如 首页文章卡片 / 分类页 / 标签页 / 文章详情页】
- 目标效果：【描述想实现的页面效果】
# 执行步骤
请按以下步骤自主分析，但修改前必须经过我的同意：
1. 检查项目根目录下的 `package.json`，确认是否已安装相关依赖；
2. 检查 Hexo 主配置文件 `_config.yml`；
3. 检查主题配置文件，例如 `_config.butterfly.yml`；
4. 查找控制目标页面的主题模板文件，重点关注：
- `layout/`
- `includes/`
- `.pug`
- `.ejs`
- `.njk`
5. 查找控制样式的文件，重点关注：
- `source/css/`
- `source/css/_layout/`
- `.styl`
- `.css`
- `.scss`
6. 列出最可能需要修改的文件路径；
7. 说明每个文件的作用，以及为什么要修改它；
8. 给出修改计划和预期效果；
9. 等我确认后，再逐个文件修改；
10. 修改后运行：
```bash
hexo clean && hexo g
|
- 如果编译通过，再提示我是否需要运行：
审批要求
- 修改文件前，必须先让我确认；
- 每次只提交一个阶段的变更；
- 不要一次性修改多个文件后直接应用；
- 如果你准备修改 3 个以上文件，请先拆成多个步骤；
- 如果某个文件不是必须修改，请不要动它。
输出格式
请先输出：
- 当前项目判断；
- 相关依赖检查结果；
- 可能涉及的文件路径；
- 每个文件的作用；
- 修改计划；
- 风险点；
- 等待我确认。
先不要修改文件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
---
## 模板 3：分阶段执行模板
```markdown
# Role: 【项目类型】开发专家（Agent 模式执行）
# Task
请帮我完成：【具体任务】
# 执行方式
请把整个任务拆成多个阶段，每个阶段单独执行：
## 阶段 1：只分析
- 阅读项目结构；
- 判断涉及文件；
- 说明实现思路；
- 不修改文件；
- 不运行命令。
## 阶段 2：只修改配置文件
- 先说明准备改哪个配置文件；
- 说明修改原因；
- 给出 diff 预览；
- 等我确认后再应用。
## 阶段 3：只修改模板文件
- 先说明准备改哪个模板文件；
- 说明该模板控制哪个页面；
- 给出 diff 预览；
- 等我确认后再应用。
## 阶段 4：只修改样式文件
- 先说明准备改哪个样式文件；
- 说明样式影响范围；
- 给出 diff 预览；
- 等我确认后再应用。
## 阶段 5：验证
- 运行必要的构建命令；
- 检查是否报错；
- 说明如何在浏览器中验证效果。
# 强制要求
未经我确认，不要进入下一阶段。
每次只修改一个文件或一个小范围功能。
不要做和任务无关的重构。
|
模板 4：限制 Agent 不要乱改的补充指令
当 Agent 一次性申请修改多个文件，而你想让它停下来时，可以直接发送：
1
2
3
4
5
6
7
8
9
10
11
12
| 先不要应用这些更改。
请撤回当前待应用变更，并重新按以下要求处理：
1. 逐个解释本次准备修改的文件；
2. 说明每个文件的作用；
3. 说明每一处新增、删除代码的含义；
4. 把修改拆成多个独立步骤；
5. 每次只提交一个文件的 diff 给我确认；
6. 未经我确认，不要应用任何修改。
请先输出解释和新的分步计划。
|
模板 5：指定某个文件不要修改
1
2
3
4
5
6
7
8
9
10
11
12
13
| 不要修改以下文件：
- 【文件路径】
请撤回对该文件的所有改动，只保留其他必要文件的修改。
重新提交变更前，请说明：
1. 不修改该文件会影响什么；
2. 是否有替代实现方案；
3. 保留修改的文件分别负责什么；
4. 新的 diff 预览。
未经我确认，不要应用变更。
|
第二部分：认知型 Ask 提示词
模板 6：定位某个页面效果由哪些代码控制
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
| 请只分析，不要修改任何文件，不要运行终端命令，不要生成待应用变更。
我想定位当前项目中某个页面效果是由哪些代码控制的。请你基于整个工作区进行分析。
# 项目信息
- 项目类型：【项目类型】
- 使用主题或框架：【使用主题或框架】
- 目标页面：【目标页面】
- 目标效果：【目标效果】
- 截图说明：【说明截图中你关注的区域】
# 请帮我完成以下分析
1. 判断这个效果可能由哪些文件控制；
2. 按可能性从高到低列出文件路径；
3. 说明每个文件大概负责什么；
4. 找出可能的关键代码、关键词或配置项；
5. 解释这个效果为什么会由这些代码控制；
6. 告诉我如何验证，例如应该搜索什么关键词、临时观察哪个文件、刷新哪个页面；
7. 如果当前打开的文件不是核心文件，请说明原因，并告诉我下一步应该看哪里；
8. 不要直接修改代码，只给定位思路和分析结论。
# 输出格式
请按下面格式回答：
## 1. 初步判断
## 2. 最可能的控制文件
| 可能性 | 文件路径 | 作用 | 判断依据 |
|---|---|---|---|
## 3. 关键关键词
## 4. 代码控制逻辑解释
## 5. 验证方法
## 6. 修改建议，但不要实际修改
|
模板 7：Hexo / Butterfly 页面效果定位模板
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
| 请只分析，不要修改任何文件，不要运行终端命令。
我的项目是 Hexo 博客，使用 Butterfly 主题。
我想知道截图中的【目标效果】是由哪些代码控制的，以及这些代码具有什么含义。
# 目标效果
【例如：categories 页面中分类按照父分类、子分类分级缩进显示】
# 请从以下方向排查
1. Hexo 主配置文件：`_config.yml`；
2. Butterfly 主题配置文件：`_config.butterfly.yml`；
3. 页面模板文件：
- `themes/hexo-theme-butterfly/layout/`
- `.pug`
- `.ejs`
- `.njk`
4. 组件模板文件：
- `includes/`
- `post/`
- `category/`
- `page/`
5. 样式文件：
- `.styl`
- `.css`
- `.scss`
6. 文章或页面源文件：
- `source/categories/`
- `source/tags/`
- `source/_posts/`
# 请输出
1. 这个效果的生成链路；
2. 最可能的模板文件；
3. 最可能的样式文件；
4. 最可能的配置项；
5. 应该搜索的关键词；
6. 每个关键词可能对应什么含义；
7. 如果我要取消或调整这个效果，应该优先看哪里；
8. 如何验证我的判断。
请用适合新手理解的方式解释，不要直接改文件。
|
模板 8：解释当前打开文件的作用
1
2
3
4
5
6
7
8
9
10
11
12
13
| 请只分析当前打开的文件，不要修改。
请帮我解释这个文件：
1. 这个文件在项目中负责什么；
2. 它属于配置文件、模板文件、样式文件，还是业务逻辑文件；
3. 它和哪些页面或功能有关；
4. 文件中的主要代码块分别是什么意思；
5. 哪些代码可能控制【目标效果】；
6. 如果当前文件不是控制【目标效果】的核心文件，请告诉我原因；
7. 下一步应该去查看哪些文件。
请用大白话解释，避免只给术语。
|
模板 9：解释某段代码的含义
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| 请只解释，不要修改代码。
请解释我选中的这段代码：
1. 这段代码整体在做什么；
2. 每一行分别是什么意思；
3. 它输入了什么数据；
4. 它输出了什么结果；
5. 它会影响哪个页面或哪个功能；
6. 如果删掉它，会发生什么；
7. 如果我要修改【目标效果】，应该改哪一部分；
8. 有没有风险点。
请用新手能理解的语言解释。
|
模板 10：让 AI 给出搜索关键词
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| 请只分析，不要修改文件，不要运行命令。
我不知道【目标效果】由哪个文件控制。请你帮我制定搜索方案。
# 目标效果
【描述页面上的具体效果】
# 请输出
1. 应该在项目里搜索哪些关键词；
2. 每个关键词为什么值得搜索；
3. 这些关键词可能出现在什么类型的文件中；
4. 找到结果后如何判断哪个才是核心代码；
5. 如果搜索结果太多，应该如何缩小范围；
6. 最推荐的排查顺序。
请只给定位方法，不要修改文件。
|
模板 11：Ask 模式下询问“这个效果是谁控制的”
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| 请不要只看当前打开的文件，请结合整个工作区进行分析。
请只分析，不要修改文件，不要运行终端命令。
我想知道当前项目中【目标页面】里的【目标效果】是由哪些代码控制的。
请你从以下三个层面分析：
1. 配置层：是否由 `_config.yml` 或主题配置文件控制；
2. 模板层：是否由 `.pug`、`.ejs`、`.njk` 等模板文件生成；
3. 样式层：是否由 `.css`、`.styl`、`.scss` 等样式文件控制。
请最后告诉我：
- 最可能的控制文件；
- 最可能的关键代码；
- 这个效果的实现原理；
- 我应该如何验证；
- 如果要修改，应该优先改哪里。
|
第三部分：常用控制句
1. 防止 AI 修改文件
1
| 不要安装依赖，不要执行 npm、hexo、git 命令。
|
2. 让 AI 先解释计划
1
| 请先告诉我你的分析过程和修改计划，等我确认后再执行。
|
1
| 修改前请列出准备修改的文件、修改原因和预期效果。
|
3. 限制每次修改范围
1
| 每次只完成一个小目标，不要一次性做完整个大任务。
|
4. 要求解释代码
1
| 请按“输入是什么、处理过程是什么、输出是什么、影响哪里”的结构解释。
|
1
| 请告诉我如果删除这段代码，会导致什么页面效果变化。
|
5. 让 AI 给验证方法
1
| 请告诉我应该搜索哪些关键词、查看哪些文件、刷新哪个页面。
|
第四部分：推荐使用方式
1. 学习陌生项目时
优先使用 Ask 模式：
1
2
| 请只分析，不要修改文件。
我想理解这个项目中【某个功能】是如何实现的，请帮我定位相关文件、解释代码逻辑，并告诉我验证方法。
|
适合目标：
- 看懂项目结构；
- 理解代码文件作用；
- 定位页面效果来源；
- 学习陌生框架；
- 判断修改入口。
2. 准备真正改代码时
再切换 Agent 模式：
1
2
3
4
| 请按刚才的分析结果执行修改。
修改前先列出文件路径和修改计划。
每次只修改一个文件，等我确认后再继续。
修改完成后运行构建命令验证。
|
适合目标：
- 添加功能；
- 修复错误；
- 修改样式；
- 调整配置；
- 自动验证构建结果。
3. 最安全的工作流
1
2
3
4
5
6
7
8
9
10
11
12
13
| Ask 模式：先问清楚这个功能是谁控制的
↓
Ask 模式：让 AI 解释关键文件和关键代码
↓
Agent 模式：让 AI 制定修改计划
↓
人工确认：确认改哪些文件
↓
Agent 模式：每次只改一个文件
↓
Agent 模式：运行构建命令验证
↓
人工检查：浏览器查看页面效果
|
第五部分：针对 Hexo 博客的常见排查方向
1. 配置相关
优先查看：
1
2
3
| _config.yml
_config.butterfly.yml
themes/hexo-theme-butterfly/_config.yml
|
常见关键词：
1
2
3
4
5
6
7
8
9
10
| theme
menu
category
categories
tag
tags
post_meta
wordcount
readtime
index_post_content
|
2. 模板相关
优先查看：
1
2
3
| themes/hexo-theme-butterfly/layout/
themes/hexo-theme-butterfly/layout/includes/
themes/hexo-theme-butterfly/layout/includes/post/
|
常见文件类型：
常见关键词：
1
2
3
4
5
6
7
8
9
10
| post
article
card
index
category
categories
meta
date
wordcount
readtime
|
3. 样式相关
优先查看：
1
2
3
| themes/hexo-theme-butterfly/source/css/
themes/hexo-theme-butterfly/source/css/_layout/
themes/hexo-theme-butterfly/source/css/_page/
|
常见关键词：
1
2
3
4
5
6
7
8
| margin
padding
indent
list
category
card
article
post-meta
|
4. 内容相关
优先查看：
1
2
3
| source/_posts/
source/categories/
source/tags/
|
常见关键词：
1
2
3
4
5
6
| title
date
tags
categories
layout
---
|
第六部分：一条完整可复制的 Ask 提示词
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| 请只分析，不要修改任何文件，不要运行终端命令，不要生成待应用变更。
我的项目是 Hexo 博客，使用 Butterfly 主题。
我想定位截图中【目标效果】是由哪些代码控制的，以及这些代码分别具有什么含义。
请你基于整个工作区，从以下方向进行分析：
1. 配置文件：`_config.yml`、`_config.butterfly.yml`、主题配置文件；
2. 模板文件：`layout/`、`includes/`、`.pug`、`.ejs`、`.njk`；
3. 样式文件：`.styl`、`.css`、`.scss`；
4. 页面源文件：`source/` 目录下的相关页面或文章。
请输出：
1. 这个效果可能由哪些文件控制；
2. 按可能性从高到低列出文件路径；
3. 每个文件的作用；
4. 最可能的关键代码、关键词或配置项；
5. 这个效果的实现原理；
6. 如何验证你的判断；
7. 如果我要修改这个效果，应该优先看哪个文件；
8. 不要直接修改代码，只给定位思路和结论。
请用适合新手理解的方式解释。
|
第七部分：一条完整可复制的 Agent 提示词
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
| # Role: Hexo 前端开发专家（Agent 模式执行）
# Task
请帮我实现以下功能或修改以下问题：
【填写你的具体任务】
# 项目信息
- 项目类型：Hexo 博客
- 主题：Butterfly
- 目标页面：【填写页面】
- 目标效果：【填写效果】
# 执行要求
请按以下步骤执行：
1. 先分析项目结构，判断该功能涉及哪些配置、模板和样式文件；
2. 检查相关依赖是否已安装；
3. 如果需要安装依赖，请先说明依赖名称、用途和安装命令，等我确认后再执行；
4. 找出最可能需要修改的文件路径；
5. 说明每个文件的作用和修改原因；
6. 先输出修改计划，不要立即修改文件；
7. 等我确认后，每次只修改一个文件；
8. 每次修改前先说明准备改什么，修改后说明改了什么；
9. 不要修改与任务无关的文件；
10. 修改完成后运行：
```bash
hexo clean && hexo g
|
- 如果构建报错，请先解释报错原因，再提出修复方案；
- 最后总结修改文件、实现效果和验证方法。
审批规则
- 未经我确认，不要修改文件；
- 未经我确认，不要安装依赖；
- 未经我确认，不要运行长期占用终端的服务命令；
- 不要一次性提交多个文件修改；
- 每一步都要告诉我你正在做什么。
请先只输出分析结果和修改计划，等待我确认后再执行。
