CodeCompanion 内置 Explain 提示词全解析让 AI 逐行讲解缓冲区代码【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvimexplain.md是 CodeCompanion.nvim 提示词库中随插件内置的 Explain code 提示词它定义了一段完整的 system user 双角色对话模板当你对缓冲区中的代码发起请求时插件会自动注入选中代码与文件类型引导 LLM 按照识别语言、描述目的、逐函数讲解、highlight 关键 API、联系更大应用的五个步骤输出高质量解释。读完本文你将掌握该内置提示词的完整结构、每个配置项与占位符的底层实现原理并能以此为蓝本编写、改造属于自己的 Markdown 提示词。一、内置提示词文件全貌explain.md位于仓库的 lua/codecompanion/prompt_library/builtins/explain.md完整内容如下--- name: Explain code interaction: chat description: Explain how code in a buffer works opts: alias: explain auto_submit: true is_slash_cmd: true modes: - v stop_context_insertion: true --- ## system When asked to explain code, follow these steps: 1. Identify the programming language. 2. Describe the purpose of the code and reference core concepts from the programming language. 3. Explain each function or significant block of code, including parameters and return values. 4. Highlight any specific functions or methods used and their roles. 5. Provide context on how the code fits into a larger application if applicable. ## user Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}这段文件由两大块组成**YAML frontmatter**--- 之间的元数据与**提示词正文**## system、## user 两个 Markdown 标题分节。这与 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 中描述的 Markdown 提示词结构完全一致frontmatter 定义提示词的配置信息标题分节定义发送给 LLM 的每条消息的角色与内容。 ## 二、Frontmatter 逐项解读六个配置字段 ### 1. name 与 descriptionAction Palette 中的展示信息 name: Explain code 是该提示词在 Action Palette动作面板中的显示名称description: Explain how code in a buffer works 则是展示给用户的描述文本。从 [prompt_library/init.lua 的 resolve 函数](https://link.gitcode.com/i/9b9e24ac61f11bb2f1a4bdfaf626caf5) 可以看到这些字段会被收集进提示词条目供 Action Palette 和斜杠命令菜单渲染。name 与 description 均支持函数形式type(prompt.name) function 时以 prompt.name(context) 求值便于实现动态名称。 ### 2. interaction: chat交互模式 interaction 声明该提示词使用的交互类型取值为 chat、inline、workflow。explain.md 使用的是 chat即请求在聊天缓冲区中发起与展示。解析器 [markdown.lua 的 parse_file](https://link.gitcode.com/i/a17aaf21f97d8ccb21ad1275fa3a29fe) 会强制校验 frontmatter.interaction 与 frontmatter.name 必须存在否则该提示词会被跳过并写入警告日志[Prompt Library] Missing frontmatter, name or interaction in ...。 ### 3. opts 子字段行为开关 explain.md 的 opts 共声明了 5 个选项 | 选项 | 值 | 作用 | | --- | --- | --- | | alias | explain | 允许通过 :CodeCompanion /explain 或聊天缓冲区内 /explain 触发该提示词 | | auto_submit | true | 提示词内容插入后自动提交给 LLM无需手动回车 | | is_slash_cmd | true | 将该提示词注册为聊天缓冲区可用的斜杠命令 | | modes | [v] | 仅在 Visual可视模式下展示保证先选中代码再解释的交互前提 | | stop_context_insertion | true | 阻止插件自动插入额外的上下文如当前文件全文避免干扰 | 这些选项在 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 的 Options 一节中有完整定义其中 alias 被描述为 Allows the prompt to be triggered via :CodeCompanion /{alias}modes 仅接受 { v } 时表示只出现在 Visual 模式。stop_context_insertion: true 是内置 explain 提示词的关键设计——它确保发送给 LLM 的内容恰好是用户选中的那段代码而不是被其他自动上下文污染。 ### 4. opts 之外的常用字段拓展 虽然 explain.md 未使用但同一 opts 命名空间下还有 adapter为单个提示词指定模型如 adapter: { name: ollama, model: deepseek-coder:6.7b }、enabled临时禁用、ignore_system_prompt不发送默认系统提示词、user_prompt执行前先获取用户输入等选项frontmatter 顶层还支持 context预加载文件/符号/URL 上下文、tools加载工具或工具组、mcp_servers、rules 等字段详见 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848)。 ## 三、System 提示词五步代码解释方法论 ## system 分节是提示词的核心方法论它要求 LLM 在解释代码时严格遵循五个步骤 1. **Identify the programming language** —— 识别编程语言这是后续讲解的前提 2. **Describe the purpose of the code and reference core concepts from the programming language** —— 描述代码用途并关联该语言的核心概念如 Rust 的所有权、Go 的 goroutine 等 3. **Explain each function or significant block of code, including parameters and return values** —— 逐个讲解函数或重要代码块覆盖参数与返回值 4. **Highlight any specific functions or methods used and their roles** —— 高亮代码中调用的特定函数/方法并说明其作用 5. **Provide context on how the code fits into a larger application if applicable** —— 在适用时说明这段代码在更大应用中的位置。 这五步从是什么语言到做什么再到每个函数怎么工作用了哪些 API放在哪里形成了从局部到整体的讲解梯度。system 分节在整个提示词解析链路中会被标记为不可见消息visible false注入聊天缓冲区见 [slash_commands/init.lua 的 run 函数](https://link.gitcode.com/i/1f213682665aa36936ca56adcb894795)chat:add_message(prompt, { visible false })即 system 指令对用户不可见但会随请求发送给模型。 ## 四、User 提示词与占位符解析 ## user 分节是发送给 LLM 的实际请求模板 text Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}其中使用了三个 ${...} 占位符它们在提交前被替换为真实内容 - ${context.bufnr} —— 当前缓冲区编号 - ${context.filetype} —— 当前文件的文件类型如 lua、python作为代码块的围栏语言标识让 LLM 正确识别语法 - ${context.code} —— 用户当前选中Visual 模式下或光标所在位置的代码文本。 占位符的解析发生在 [markdown.lua 的 resolve_placeholders](https://link.gitcode.com/i/5e3bd07d42a144d8e7803f3131b121f5)插件用 utils.extract_all_placeholders 提取所有 ${...}再通过 utils.resolve_nested_value 从 args含 context 与 item中取值若是函数则 pcall 调用并转为字符串替换失败会记录 [Prompt Library] Could not resolve ${...} 警告但不会中断流程。${context.code} 的取值依赖 [helpers/code.lua 的 get_code](https://link.gitcode.com/i/2463d8ccbf5ea293bf0d58b2476c9b01)它按 start_line 到 end_line 逐行读取 vim.fn.getline(line_num) 并用 \n 拼接——这一实现也解释了为何 context 对象中需要 start_line、end_line 字段[上下文完整字段示例](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 展示了包含 bufnr、filetype、code、cursor_pos、mode、lines 等的完整结构。 值得注意的是 explain.md 使用了四重反引号 包裹代码这能避免被解释代码自身包含三重反引号时破坏消息结构是一种防御性写法。 ## 五、触发方式三种入口 内置提示词可以通过以下三种方式触发详见 [使用文档](https://link.gitcode.com/i/35c57b4f3a969e3848c521c3ad412083) 1. **斜杠命令**由于声明了 alias: explain 与 is_slash_cmd: true在聊天缓冲区输入 /explain或在命令行执行 :CodeCompanion /explain 即可触发。执行链路在 [slash_commands/init.lua 的 run](https://link.gitcode.com/i/1f213682665aa36936ca56adcb894795) 中对于 from_prompt_library 的条目先加载提示词声明的工具再解析占位符最后按角色注入聊天缓冲区 2. **Action Palette**通过 :CodeCompanionActions默认键位 Leadera 或 Leaderaa 等打开动作面板选择 Explain code。可见性受 display.action_palette.opts.show_prompt_library_builtins 控制设为 false 可隐藏内置提示词 3. **Keymap**通过 require(codecompanion).prompt(explain) 绑定快捷键其中 explain 即提示词的 alias lua vim.keymap.set(v, LocalLeadere, function() require(codecompanion).prompt(explain) end, { noremap true, silent true })由于modes: [v]的限制推荐在 Visual 模式下选中目标代码后调用auto_submit: true会自动提交请求形成选中即解释的零操作体验。六、源码级验证Markdown 提示词如何被加载与解析从源码链路看内置提示词的加载与解析分四步加载prompt_library/init.lua 的 load_builtins 定位builtins目录并调用markdown.load_from_dirmarkdown.lua 的 load_from_dir 递归扫描目录下所有*.md最大深度 5逐个pcall解析单个文件解析失败不影响其余文件frontmatter 解析parse_frontmatter 使用vim.treesitter的yaml解析器配合prompt_libraryquery定义于 queries/yaml/prompt_library.scm抽取顶层键值若未安装 yaml treesitter 解析器会给出明确警告。测试 tests/prompt_library/test_markdown.lua 中 parse_frontmatter extracts yaml 用例验证了与explain.md几乎同构的 frontmatter 能正确解析出interaction、opts含adapter、modes、alias、stop_context_insertion、user_prompt等字段并确认兼容 CRLF 行尾DOS 格式的 Markdown 文件正文解析parse_prompt 用markdown解析器按## role标题分节仅接受system与user两种角色allowed_roles取自config.constants其他角色会被忽略测试 parse_prompt ignores incorrect roles 验证了## foo、## bar不会被解析## user与## system可多次出现并按顺序保留占位符替换如前所述由resolve_placeholders在提交前完成测试中 resolves context placeholders 用例验证了${context.bufnr}、${context.filetype}会被替换为实际值而无法解析的占位符如${nonexistent.value}会原样保留而非报错。七、举一反三基于 explain.md 定制自己的提示词理解了内置explain.md的结构后可以轻易派生自己的版本。例如为每个解释请求附加 LSP 诊断信息让 AI 在解释的同时提示潜在问题--- name: Explain with diagnostics interaction: chat description: Explain the selected code and its diagnostics opts: alias: explain-diag auto_submit: true is_slash_cmd: true modes: - v stop_context_insertion: true --- ## system When asked to explain code, follow these steps: 1. Identify the programming language. 2. Describe the purpose of the code and reference core concepts from the programming language. 3. Explain each function or significant block of code, including parameters and return values. 4. Highlight any specific functions or methods used and their roles. 5. Provide context on how the code fits into a larger application if applicable. 6. If there are LSP diagnostics, briefly comment on whether they are valid. ## user Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}将上述文件保存到 prompt_library.markdown.dirs 配置的任意目录参考 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 中 markdown.dirs 的配置方式即可被插件自动发现运行中的会话可用 :CodeCompanionActions Refresh 刷新提示词库。若提示词需要动态内容还可以在 Markdown 同目录放置同名 Lua 文件如 commit.md 对应 commit.lua通过 ${commit.diff} 这类点号占位符引用其中的函数——这是内置 [commit.md](https://link.gitcode.com/i/648678395ae05e8b156813d6244b21b0) 生成提交信息的实现方式。 ## 结语 explain.md 虽然只有 31 行却是 CodeCompanion Markdown 提示词机制的完整缩影YAML frontmatter 控制行为system 分节约束输出质量user 分节配合 ${context.*} 占位符实现所见即所问。理解它的解析链路load_from_dir → parse_frontmatter → parse_prompt → resolve_placeholders你就能举一反三地利用提示词库把 CodeCompanion 塑造成贴合自己工作流的 AI 结对伙伴。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CodeCompanion 内置 Explain 提示词全解析：让 AI 逐行讲解缓冲区代码
CodeCompanion 内置 Explain 提示词全解析让 AI 逐行讲解缓冲区代码【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvimexplain.md是 CodeCompanion.nvim 提示词库中随插件内置的 Explain code 提示词它定义了一段完整的 system user 双角色对话模板当你对缓冲区中的代码发起请求时插件会自动注入选中代码与文件类型引导 LLM 按照识别语言、描述目的、逐函数讲解、highlight 关键 API、联系更大应用的五个步骤输出高质量解释。读完本文你将掌握该内置提示词的完整结构、每个配置项与占位符的底层实现原理并能以此为蓝本编写、改造属于自己的 Markdown 提示词。一、内置提示词文件全貌explain.md位于仓库的 lua/codecompanion/prompt_library/builtins/explain.md完整内容如下--- name: Explain code interaction: chat description: Explain how code in a buffer works opts: alias: explain auto_submit: true is_slash_cmd: true modes: - v stop_context_insertion: true --- ## system When asked to explain code, follow these steps: 1. Identify the programming language. 2. Describe the purpose of the code and reference core concepts from the programming language. 3. Explain each function or significant block of code, including parameters and return values. 4. Highlight any specific functions or methods used and their roles. 5. Provide context on how the code fits into a larger application if applicable. ## user Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}这段文件由两大块组成**YAML frontmatter**--- 之间的元数据与**提示词正文**## system、## user 两个 Markdown 标题分节。这与 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 中描述的 Markdown 提示词结构完全一致frontmatter 定义提示词的配置信息标题分节定义发送给 LLM 的每条消息的角色与内容。 ## 二、Frontmatter 逐项解读六个配置字段 ### 1. name 与 descriptionAction Palette 中的展示信息 name: Explain code 是该提示词在 Action Palette动作面板中的显示名称description: Explain how code in a buffer works 则是展示给用户的描述文本。从 [prompt_library/init.lua 的 resolve 函数](https://link.gitcode.com/i/9b9e24ac61f11bb2f1a4bdfaf626caf5) 可以看到这些字段会被收集进提示词条目供 Action Palette 和斜杠命令菜单渲染。name 与 description 均支持函数形式type(prompt.name) function 时以 prompt.name(context) 求值便于实现动态名称。 ### 2. interaction: chat交互模式 interaction 声明该提示词使用的交互类型取值为 chat、inline、workflow。explain.md 使用的是 chat即请求在聊天缓冲区中发起与展示。解析器 [markdown.lua 的 parse_file](https://link.gitcode.com/i/a17aaf21f97d8ccb21ad1275fa3a29fe) 会强制校验 frontmatter.interaction 与 frontmatter.name 必须存在否则该提示词会被跳过并写入警告日志[Prompt Library] Missing frontmatter, name or interaction in ...。 ### 3. opts 子字段行为开关 explain.md 的 opts 共声明了 5 个选项 | 选项 | 值 | 作用 | | --- | --- | --- | | alias | explain | 允许通过 :CodeCompanion /explain 或聊天缓冲区内 /explain 触发该提示词 | | auto_submit | true | 提示词内容插入后自动提交给 LLM无需手动回车 | | is_slash_cmd | true | 将该提示词注册为聊天缓冲区可用的斜杠命令 | | modes | [v] | 仅在 Visual可视模式下展示保证先选中代码再解释的交互前提 | | stop_context_insertion | true | 阻止插件自动插入额外的上下文如当前文件全文避免干扰 | 这些选项在 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 的 Options 一节中有完整定义其中 alias 被描述为 Allows the prompt to be triggered via :CodeCompanion /{alias}modes 仅接受 { v } 时表示只出现在 Visual 模式。stop_context_insertion: true 是内置 explain 提示词的关键设计——它确保发送给 LLM 的内容恰好是用户选中的那段代码而不是被其他自动上下文污染。 ### 4. opts 之外的常用字段拓展 虽然 explain.md 未使用但同一 opts 命名空间下还有 adapter为单个提示词指定模型如 adapter: { name: ollama, model: deepseek-coder:6.7b }、enabled临时禁用、ignore_system_prompt不发送默认系统提示词、user_prompt执行前先获取用户输入等选项frontmatter 顶层还支持 context预加载文件/符号/URL 上下文、tools加载工具或工具组、mcp_servers、rules 等字段详见 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848)。 ## 三、System 提示词五步代码解释方法论 ## system 分节是提示词的核心方法论它要求 LLM 在解释代码时严格遵循五个步骤 1. **Identify the programming language** —— 识别编程语言这是后续讲解的前提 2. **Describe the purpose of the code and reference core concepts from the programming language** —— 描述代码用途并关联该语言的核心概念如 Rust 的所有权、Go 的 goroutine 等 3. **Explain each function or significant block of code, including parameters and return values** —— 逐个讲解函数或重要代码块覆盖参数与返回值 4. **Highlight any specific functions or methods used and their roles** —— 高亮代码中调用的特定函数/方法并说明其作用 5. **Provide context on how the code fits into a larger application if applicable** —— 在适用时说明这段代码在更大应用中的位置。 这五步从是什么语言到做什么再到每个函数怎么工作用了哪些 API放在哪里形成了从局部到整体的讲解梯度。system 分节在整个提示词解析链路中会被标记为不可见消息visible false注入聊天缓冲区见 [slash_commands/init.lua 的 run 函数](https://link.gitcode.com/i/1f213682665aa36936ca56adcb894795)chat:add_message(prompt, { visible false })即 system 指令对用户不可见但会随请求发送给模型。 ## 四、User 提示词与占位符解析 ## user 分节是发送给 LLM 的实际请求模板 text Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}其中使用了三个 ${...} 占位符它们在提交前被替换为真实内容 - ${context.bufnr} —— 当前缓冲区编号 - ${context.filetype} —— 当前文件的文件类型如 lua、python作为代码块的围栏语言标识让 LLM 正确识别语法 - ${context.code} —— 用户当前选中Visual 模式下或光标所在位置的代码文本。 占位符的解析发生在 [markdown.lua 的 resolve_placeholders](https://link.gitcode.com/i/5e3bd07d42a144d8e7803f3131b121f5)插件用 utils.extract_all_placeholders 提取所有 ${...}再通过 utils.resolve_nested_value 从 args含 context 与 item中取值若是函数则 pcall 调用并转为字符串替换失败会记录 [Prompt Library] Could not resolve ${...} 警告但不会中断流程。${context.code} 的取值依赖 [helpers/code.lua 的 get_code](https://link.gitcode.com/i/2463d8ccbf5ea293bf0d58b2476c9b01)它按 start_line 到 end_line 逐行读取 vim.fn.getline(line_num) 并用 \n 拼接——这一实现也解释了为何 context 对象中需要 start_line、end_line 字段[上下文完整字段示例](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 展示了包含 bufnr、filetype、code、cursor_pos、mode、lines 等的完整结构。 值得注意的是 explain.md 使用了四重反引号 包裹代码这能避免被解释代码自身包含三重反引号时破坏消息结构是一种防御性写法。 ## 五、触发方式三种入口 内置提示词可以通过以下三种方式触发详见 [使用文档](https://link.gitcode.com/i/35c57b4f3a969e3848c521c3ad412083) 1. **斜杠命令**由于声明了 alias: explain 与 is_slash_cmd: true在聊天缓冲区输入 /explain或在命令行执行 :CodeCompanion /explain 即可触发。执行链路在 [slash_commands/init.lua 的 run](https://link.gitcode.com/i/1f213682665aa36936ca56adcb894795) 中对于 from_prompt_library 的条目先加载提示词声明的工具再解析占位符最后按角色注入聊天缓冲区 2. **Action Palette**通过 :CodeCompanionActions默认键位 Leadera 或 Leaderaa 等打开动作面板选择 Explain code。可见性受 display.action_palette.opts.show_prompt_library_builtins 控制设为 false 可隐藏内置提示词 3. **Keymap**通过 require(codecompanion).prompt(explain) 绑定快捷键其中 explain 即提示词的 alias lua vim.keymap.set(v, LocalLeadere, function() require(codecompanion).prompt(explain) end, { noremap true, silent true })由于modes: [v]的限制推荐在 Visual 模式下选中目标代码后调用auto_submit: true会自动提交请求形成选中即解释的零操作体验。六、源码级验证Markdown 提示词如何被加载与解析从源码链路看内置提示词的加载与解析分四步加载prompt_library/init.lua 的 load_builtins 定位builtins目录并调用markdown.load_from_dirmarkdown.lua 的 load_from_dir 递归扫描目录下所有*.md最大深度 5逐个pcall解析单个文件解析失败不影响其余文件frontmatter 解析parse_frontmatter 使用vim.treesitter的yaml解析器配合prompt_libraryquery定义于 queries/yaml/prompt_library.scm抽取顶层键值若未安装 yaml treesitter 解析器会给出明确警告。测试 tests/prompt_library/test_markdown.lua 中 parse_frontmatter extracts yaml 用例验证了与explain.md几乎同构的 frontmatter 能正确解析出interaction、opts含adapter、modes、alias、stop_context_insertion、user_prompt等字段并确认兼容 CRLF 行尾DOS 格式的 Markdown 文件正文解析parse_prompt 用markdown解析器按## role标题分节仅接受system与user两种角色allowed_roles取自config.constants其他角色会被忽略测试 parse_prompt ignores incorrect roles 验证了## foo、## bar不会被解析## user与## system可多次出现并按顺序保留占位符替换如前所述由resolve_placeholders在提交前完成测试中 resolves context placeholders 用例验证了${context.bufnr}、${context.filetype}会被替换为实际值而无法解析的占位符如${nonexistent.value}会原样保留而非报错。七、举一反三基于 explain.md 定制自己的提示词理解了内置explain.md的结构后可以轻易派生自己的版本。例如为每个解释请求附加 LSP 诊断信息让 AI 在解释的同时提示潜在问题--- name: Explain with diagnostics interaction: chat description: Explain the selected code and its diagnostics opts: alias: explain-diag auto_submit: true is_slash_cmd: true modes: - v stop_context_insertion: true --- ## system When asked to explain code, follow these steps: 1. Identify the programming language. 2. Describe the purpose of the code and reference core concepts from the programming language. 3. Explain each function or significant block of code, including parameters and return values. 4. Highlight any specific functions or methods used and their roles. 5. Provide context on how the code fits into a larger application if applicable. 6. If there are LSP diagnostics, briefly comment on whether they are valid. ## user Please explain this code from buffer ${context.bufnr}: ${context.filetype} ${context.code}将上述文件保存到 prompt_library.markdown.dirs 配置的任意目录参考 [配置文件说明文档](https://link.gitcode.com/i/6824c8ba777d9d1c551098a182eb7848) 中 markdown.dirs 的配置方式即可被插件自动发现运行中的会话可用 :CodeCompanionActions Refresh 刷新提示词库。若提示词需要动态内容还可以在 Markdown 同目录放置同名 Lua 文件如 commit.md 对应 commit.lua通过 ${commit.diff} 这类点号占位符引用其中的函数——这是内置 [commit.md](https://link.gitcode.com/i/648678395ae05e8b156813d6244b21b0) 生成提交信息的实现方式。 ## 结语 explain.md 虽然只有 31 行却是 CodeCompanion Markdown 提示词机制的完整缩影YAML frontmatter 控制行为system 分节约束输出质量user 分节配合 ${context.*} 占位符实现所见即所问。理解它的解析链路load_from_dir → parse_frontmatter → parse_prompt → resolve_placeholders你就能举一反三地利用提示词库把 CodeCompanion 塑造成贴合自己工作流的 AI 结对伙伴。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考