深入解析 CodeCompanion.nvim 的 Markdown 提示词格式以 test_prompt.md 为例的完整指南【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim本文以仓库测试夹具 tests/prompt_library/stubs/test_prompt.md 为解剖样本系统讲解 CodeCompanion.nvim 提示词库Prompt Library中 Markdown 提示词文件的结构、frontmatter 字段、占位符机制与底层解析原理。读完本文你将掌握编写可被 Action Palette、斜杠命令与工作流正确识别的.md提示词文件的全部要点并能基于源码调用链定位问题。一、test_prompt.md一个最小但完整的 Markdown 提示词样本先看被测试与文档反复引用的这份文件全貌--- name: Test Prompt strategy: chat description: Explain how code in a buffer works opts: auto_submit: true is_slash_cmd: true modes: - v alias: explain stop_context_insertion: true user_prompt: false --- ## system You are a helpful assistant. ## user Explain the following code: python def hello_world(): print(Hello, world!) ## user Here is another user prompt. 它由两大部分构成这也是所有 Markdown 提示词文件通用骨架YAML frontmatter位于文件头部---与---之间的元数据区定义提示词的名称、交互类型、行为选项Prompt sections以## system、## user二级标题划分的消息段落定义发送给 LLM 的角色与内容。注意文件末尾使用了strategy: chat字段——这是旧字段名。在解析器 lua/codecompanion/prompt_library/markdown.lua 中有兼容处理逻辑strategy会被自动迁移为interaction并删除旧键因此旧提示词文件无需修改也能继续工作。二、frontmatter 字段全解name、interaction 与 opts解析器要求 frontmatter 中至少包含name与interaction两个字段否则该文件会被跳过并打印警告Missing frontmatter, name or interaction见 markdown.lua。字段解析依赖 treesitter 的 YAML 解析器与查询文件 queries/yaml/prompt_library.scm因此必须安装yamltreesitter parser否则 frontmatter 无法解析解析器会明确提示Install the yaml treesitter parser to parse frontmatter。必需字段字段说明name提示词在 Action Palette 中的显示名称也是提示词库中的唯一标识descriptionAction Palette 中展示的描述文字interaction交互类型chat聊天缓冲区、inline行内补全、workflow多步工作流。旧字段strategy等价并被自动迁移test_prompt.md 中description为Explain how code in a buffer works这与内置提示词 lua/codecompanion/prompt_library/builtins/explain.md 的描述一致说明该测试样本正是对内置 explain 提示词的仿真。opts 选项表选项类型作用aliasstring允许通过:CodeCompanion /explain这类斜杠命令直接触发auto_submitboolean加载提示词后是否自动提交给 LLMis_slash_cmdboolean是否在聊天缓冲区中作为斜杠命令候选展示modesarray限定生效的 Neovim 模式如{ v }表示仅在可视模式出现stop_context_insertionboolean阻止自动向提示词插入当前缓冲区上下文user_promptboolean/string在执行前是否先获取用户输入设置为字符串时可作为自定义输入提示除此之外源码与官方配置文档 doc/configuration/prompt-library.md 还支持adapter为单个提示词指定{ name, model, acp_opts }可覆盖全局适配器、enabled、ignore_system_prompt不附加默认系统提示词、intro_message、is_workflow、placementinline 场景的new/replace/add/before/chat等选项。测试 tests/prompt_library/test_prompt_library.lua 验证了opts.adapter能正确让一次会话切换到指定适配器与模型。三、Prompt Sections角色与内容如何被解析frontmatter 之后文件主体由多个 Markdown 小节组成。解析器通过 treesitter 查询 queries/markdown/chat.scm 捕获## role二级标题 → 角色的role捕获system、user标题下的内容块 →content捕获。解析逻辑位于 markdown.lua 的 parse_prompt角色字符串会转为小写并与allowed_roles即system、user比对不合法角色如## foo会被整体忽略这在测试parse_prompt ignores incorrect roles中得到验证见 tests/prompt_library/test_markdown.lua连续多个## user小节会被顺序保留为多条独立消息正如 test_prompt.md 中两条 user 消息被分别解析同一提示词内的多个内容段会被\n连接成一条消息。测试parse_prompt extracts system and user promptstest_markdown.lua给出了与本文样本完全一致的期望输出可视为格式的官方验收标准。代码块与yaml opts特殊块解析器对content节点做了一处特殊处理如果内容是一个围栏代码块且其info_string匹配yaml opts如yaml opts则它不会作为消息内容而是被解析为当前消息的opts表见 markdown.lua。该机制常用于工作流中为单条消息覆盖auto_submit、adapter等选项测试parse_prompt workflow prompts with options对此有完整断言test_markdown.lua。四、占位符机制从${context.bufnr}到外部 Lua 文件test_prompt.md 的简化版本使用了字面代码但真实场景中提示词需要注入动态内容。解析器通过resolve_placeholdersmarkdown.lua支持${placeholder}语法内建 context 占位符${context.bufnr}、${context.filetype}、${context.code}、${context.start_line}、${context.end_line}等直接取自当前缓冲区上下文。内置的 explain.md 正是用${context.bufnr}/${context.code}注入选区代码外部 Lua 文件占位符当占位符使用点号记法如${commit.diff}时解析器会在提示词文件同目录查找同名.lua文件如commit.lua加载其返回的表并调用其中的函数或读取静态值。函数签名接收args表含args.context与args.item容错处理无法解析的占位符会原样保留并输出 warning不会导致提示词加载失败测试handles non-existent placeholders gracefully验证了这一点。五、加载、注册与刷新让提示词真正可用仅有.md文件还不够必须把它所在的目录注册到配置中require(codecompanion).setup({ prompt_library { markdown { dirs { vim.fn.getcwd() .. /.prompts, -- 相对路径 ~/.dotfiles/.config/prompts, -- 绝对路径 }, }, }, })加载入口是 lua/codecompanion/prompt_library/init.lua 与markdown.load_from_dirmarkdown.lua后者递归扫描目录最大深度 5 层支持嵌套与符号链接中的*.md文件逐个pcall解析解析失败不影响其他文件。测试load_from_dir loads all markdown files in a directorytest_markdown.lua验证了从tests/prompt_library/stubs/加载test_prompt.md的完整流程。运行中的 Neovim 会话内新增或修改了提示词文件可用:CodeCompanionActions Refresh刷新提示词库。启用后提示词会出现在:CodeCompanionActions打开的 Action Palette 中设置opts.is_slash_cmd: true与opts.alias后可在聊天缓冲区用/explain直接触发设置opts.auto_submit: true后无需手动发送加载即提交。六、进阶扩展工作流与上下文装载Markdown 提示词还支持两类高阶能力工作流frontmatter 中设置opts.is_workflow: true后多个## user小节会被切分为顺序执行的多个回合——system消息并入第一个用户回合其余每个user小节独立成组见 markdown.lua 与测试parse_prompt formats workflow prompts。注意官方文档明确提示 Markdown 提示词不支持 agentic 工作流doc/configuration/prompt-library.md 的 Workflows 小节context 预装载frontmatter 中声明context列表type: file、type: symbols、type: url可为提示词预置上下文条目mcp_servers、rules、tools字段则可按提示词粒度加载 MCP 服务器、规则组与工具。七、测试即规范用仓库测试验证你的理解仓库中的测试集就是 Markdown 提示词格式的活文档建议编写自己的提示词前先通读 tests/prompt_library/test_markdown.lua其中覆盖了frontmatter 各字段解析含 DOS 换行、strategy迁移、context/tools/mcp_servers/rules提取多消息与非法角色处理工作流格式化与单条消息yaml opts占位符解析context、外部 Lua 文件、多文件、嵌套、缺失容错目录批量加载。结合 queries/yaml/prompt_library.scm 与 queries/markdown/chat.scm 两棵查询树你既能写出格式正确的提示词也能在解析异常时快速定位是 frontmatter 结构问题还是 treesitter 查询匹配问题。以 test_prompt.md 为起点将这份格式迁移到你的~/.prompts目录即可构建一套完全属于自己的、可版本管理的 AI 编码提示词库。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考