![[基础篇06] 用 OpenCode 模板引擎生成代码片段：从 md-expand 到自定义命令的 TaoToken 配置骨架](http://pic.xiahunao.cn/yaotu/[基础篇06] 用 OpenCode 模板引擎生成代码片段：从 md-expand 到自定义命令的 TaoToken 配置骨架)
1. 为什么你的 OpenCode 还在重复“念咒语”如果你用 OpenCode 写代码超过一周大概率经历过这种循环每次让 AI 生成组件都要把“用 TypeScript、函数式组件、带 Props 类型、加 JSDoc”这套话重新打一遍。一天下来光是描述需求就敲了几百字真正写业务逻辑的时间反而被压缩了。OpenCode 的模板引擎就是冲着这个痛点来的。它把“你反复要说的那套话”固化成可复用的资产——写一次模板以后敲/review或#code-standards就能把整段指令塞进对话。这套机制分三层自定义命令/commands/*.md负责独立任务代码片段#snippet负责对话内快速插入md-expand插件负责带变量和条件逻辑的动态模板。三层递进覆盖从“固定话术”到“智能渲染”的全部场景。这篇是基础篇第 06 篇聚焦 OpenCode 模板引擎生成代码片段的落地路径。我会先给出md-expand与自定义命令的配置骨架再通过 TaoToken 统一 Key/API 通道接入 AI 工具最后用一次可复制的验证动作确认代码片段能按模板稳定产出。适合已经装好 OpenCode、跑过/init、想告别重复描述的人。如果你还没配好 API 通道第 2 节会补上。2. TaoToken 前置把 Key 和 API 通道统一起来OpenCode 本身不绑定模型供应商它通过配置文件读取 API Key 和 Base URL。如果你同时用多个 AI 工具OpenCode、Claude Code、自己的脚本每个工具都去单独配 Key 会很乱。TaoToken 在这里的角色是统一入口一个 Key 走通所有工具Base URL 固定省去每个工具单独填供应商地址的麻烦。先拿到 Key。访问https://taotoken.net/api-keysdeep link 带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite在控制台创建一个 API Key复制出来。这个 Key 后面会写进 OpenCode 的配置里。OpenCode 的模型配置通常放在~/.config/opencode/opencode.json或项目级.opencode/opencode.json。核心是两段provider定义通道model指定默认模型。下面是一个可复制的骨架把YOUR_TAOTOKEN_KEY替换成你刚复制的 Key{ provider: { taotoken: { type: openai, options: { baseURL: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY }, models: { claude-sonnet: { name: claude-sonnet-4-20250514 } } } }, model: taotoken/claude-sonnet }这里type用openai是因为 TaoToken 的 API 兼容 OpenAI 格式OpenCode 能直接识别。baseURL固定为https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。models里的name填你实际要调用的模型标识具体可用模型在控制台或文档里查。注意Key 不要提交到 Git。项目级配置建议用.opencode/opencode.json并加入.gitignore或者用环境变量TAOTOKEN_API_KEY然后在配置里写apiKey: {env:TAOTOKEN_API_KEY}。配好之后OpenCode 启动时会读取这个文件。你可以先用一个最小请求验证通道是否通再往下做模板。验证方法在第 4 节。3. 可复制配置md-expand 与自定义命令骨架模板引擎的落地分两块自定义命令负责“独立任务”md-expand负责“动态渲染”。先把目录结构建好再填内容。3.1 目录结构OpenCode 读两个位置项目级.opencode/和全局~/.config/opencode/。项目级优先适合团队共享全局适合个人常用模板。建议这样建# 项目级 mkdir -p .opencode/commands mkdir -p .opencode/snippet # 全局可选 mkdir -p ~/.config/opencode/commands mkdir -p ~/.config/opencode/snippetcommands/放自定义命令snippet/放代码片段。文件名就是命令名review.md对应/review。3.2 第一个自定义命令代码审查创建.opencode/commands/review.md--- description: 审查当前修改的代码指出安全和性能问题 agent: plan --- 请审查我当前修改的代码文件。 审查重点 1. 安全性有没有 SQL 注入、XSS、敏感信息泄露的风险 2. 性能有没有 O(n²) 以上的循环、不必要的重复计算 3. 代码规范命名是否清晰有没有魔法数字 请给出具体的修改建议但不要直接修改文件。 当前修改的文件列表 !git diff --name-only HEAD 请逐一审查上述文件。frontmatter 里agent: plan表示用 Plan 模式执行不会直接改文件。!加反引号是 Shell 输出注入——命令执行时git diff --name-only HEAD会先运行输出结果嵌入提示词。注意格式是!后跟反引号包裹的命令不是普通引号。3.3 带参数的命令生成组件创建.opencode/commands/component.md--- description: 生成一个 React 函数组件 agent: build --- 请创建一个 React 函数组件组件名为 $1。 要求 1. 使用 TypeScriptProps 类型定义完整 2. 使用函数式组件写法不是 class 3. 带基本的 JSDoc 注释 4. 如果传入了 $2把它作为组件的样式主题light/dark 组件放在 src/components/$1.tsx。调用时/component Button dark$1替换成Button$2替换成dark。$ARGUMENTS可以拿全部参数的原始字符串适合 Git 操作这类命令。3.4 md-expand 插件变量与条件md-expand让模板支持{{...}}语法。在opencode.json的plugins数组里加{ plugins: [opencode-plugin-md-expand^0.1.0] }保存后重启 OpenCode插件会自动安装。然后创建.opencode/commands/deploy.md--- description: 生成部署配置 agent: build --- 请根据以下信息生成部署配置文件 环境{{env:NODE_ENV}} API 地址{{env:API_URL}} {{ ifenv:CI }} 当前是 CI 环境请生成适用于自动化部署的配置包含健康检查端点。 {{ else }} 当前是本地环境请生成开发用的配置启用调试日志。 {{ endif }} 项目类型{{arg:type}} 请参考以下规范{{ file./deploy-rules.md }}三种语法{{env:VAR}}读环境变量{{ if条件 }}...{{ endif }}做条件判断{{ file./path }}引用文件内容{{arg:name}}读命令行参数。插件会在 AI 看到之前把{{...}}替换成实际值。3.5 代码片段对话内快速插入自定义命令适合独立执行#snippet适合对话中插入。先装插件opencode plugin opencode-snippets -gf然后在~/.config/opencode/snippet/code-standards.md写入#code-standards 请遵循以下代码规范 1. 使用 2 空格缩进不用 Tab 2. 变量命名用 camelCase常量用 UPPER_SNAKE_CASE 3. 每个函数不超过 30 行超过则拆分 4. 所有公开函数必须有 JSDoc/TSDoc 注释 5. 优先使用 const其次 let避免 var对话里输入src/utils/logger.ts 帮我重构这个文件 #code-standardsOpenCode 会加载文件内容并把 snippet 插入提示词。snippet 可以嵌套#full-review里写#code-standards #security #performance敲一个等于注入三套规范。4. 验证请求确认模板稳定产出配置写完得验证两件事API 通道通不通模板替换对不对。4.1 验证 TaoToken 通道先用一个最小请求确认 Key 和 Base URL 生效。在终端里跑curl -s https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }如果返回 JSON 里choices[0].message.content包含OK说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查baseURL是否写成了https://taotoken.net/api不要带路径后缀。4.2 验证自定义命令在任意 Git 项目里创建review.md改一个文件后在 OpenCode TUI 输入/review。预期行为OpenCode 先执行git diff --name-only HEAD把修改的文件列表嵌入提示词然后 AI 逐一审查。如果 AI 回复里提到了你刚改的文件名说明 Shell 注入生效。4.3 验证 md-expand 变量替换设置环境变量后执行/deployexport NODE_ENVproduction export CItrue在 TUI 输入/deploy。预期AI 看到的提示词里{{env:NODE_ENV}}已变成production{{ ifenv:CI }}分支被选中生成的配置包含健康检查端点。如果 AI 回复里出现了{{env:NODE_ENV}}原文说明插件没加载回到第 5 节排查。4.4 验证 snippet 展开在 TUI 输入一条包含#code-standards的消息观察 AI 回复是否遵循了 2 空格缩进、camelCase 命名等规范。如果 AI 把#code-standards当普通文本处理说明 snippet 插件没生效。5. 本篇常见错排查5.1 自定义命令不生效提示 command not found最常见的原因是文件放错位置或文件名不对。项目级命令必须在.opencode/commands/name.md全局在~/.config/opencode/commands/name.md。文件名review.md对应/review不能有多余后缀。改完文件后完全退出 OpenCode按q再重新运行热重载不一定生效。用/help查看命令列表确认你的命令是否出现。5.2 #snippet 不展开直接显示为文本先确认插件装了opencode plugin list看有没有opencode-snippets。没有就重装opencode plugin opencode-snippets -gf。然后检查opencode.json里plugins数组是否包含它。snippet 文件目录也要对全局~/.config/opencode/snippet/项目级.opencode/snippet/。最后重启 OpenCode。5.3 md-expand 的 {{...}} 没有被替换确认opencode.json里插件配置是opencode-plugin-md-expand^0.1.0。插件首次加载时自动安装如果没装上手动npm install -g opencode-plugin-md-expand。模板文件必须是.md格式{{...}}语法不能有拼写错误。还是不行就开调试模式{ plugins: [ [opencode-plugin-md-expand^0.1.0, { debug: true }] ] }重启后看日志通常能定位到是变量名写错还是文件路径不对。5.4 API 返回 401 或模型不存在401 一般是 Key 问题检查apiKey是否完整有没有多余空格。模型不存在则是models里的name填错了去 TaoToken 控制台确认可用模型标识。另外注意baseURL不要写成https://taotoken.net/api/末尾斜杠有时会导致路径拼接问题也不要在 API 地址上加 UTM 参数。6. 把模板变成你的资产模板引擎的本质是把“你反复要说的话”变成“可复用的资产”。从今天开始每次重复描述同一个需求的时候就把它写成模板——以后敲几个字符就能搞定。如果你在配 TaoToken 通道时遇到问题先去https://taotoken.net/api-keys带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite确认 Key 状态接入细节看https://taotoken.net/doc带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。想先验证模型对话是否正常用https://taotoken.net/models带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite跑一轮。如果你打算长期用 OpenCode 做编码和 Agent 任务Coding Plan 的通道更稳入口在https://taotoken.net/coding-plan带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。下一篇是基础篇 07讲 OpenCode 插件机制扩展核心命令——怎么开发自己的插件、怎么给 OpenCode 增加新命令和工具。模板搭好了插件就是下一步的杠杆。 [基础篇06] 用 OpenCode 模板引擎生成代码片段：从 md-expand 到自定义命令的 TaoToken 配置骨架
1. 为什么你的 OpenCode 还在重复“念咒语”如果你用 OpenCode 写代码超过一周大概率经历过这种循环每次让 AI 生成组件都要把“用 TypeScript、函数式组件、带 Props 类型、加 JSDoc”这套话重新打一遍。一天下来光是描述需求就敲了几百字真正写业务逻辑的时间反而被压缩了。OpenCode 的模板引擎就是冲着这个痛点来的。它把“你反复要说的那套话”固化成可复用的资产——写一次模板以后敲/review或#code-standards就能把整段指令塞进对话。这套机制分三层自定义命令/commands/*.md负责独立任务代码片段#snippet负责对话内快速插入md-expand插件负责带变量和条件逻辑的动态模板。三层递进覆盖从“固定话术”到“智能渲染”的全部场景。这篇是基础篇第 06 篇聚焦 OpenCode 模板引擎生成代码片段的落地路径。我会先给出md-expand与自定义命令的配置骨架再通过 TaoToken 统一 Key/API 通道接入 AI 工具最后用一次可复制的验证动作确认代码片段能按模板稳定产出。适合已经装好 OpenCode、跑过/init、想告别重复描述的人。如果你还没配好 API 通道第 2 节会补上。2. TaoToken 前置把 Key 和 API 通道统一起来OpenCode 本身不绑定模型供应商它通过配置文件读取 API Key 和 Base URL。如果你同时用多个 AI 工具OpenCode、Claude Code、自己的脚本每个工具都去单独配 Key 会很乱。TaoToken 在这里的角色是统一入口一个 Key 走通所有工具Base URL 固定省去每个工具单独填供应商地址的麻烦。先拿到 Key。访问https://taotoken.net/api-keysdeep link 带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite在控制台创建一个 API Key复制出来。这个 Key 后面会写进 OpenCode 的配置里。OpenCode 的模型配置通常放在~/.config/opencode/opencode.json或项目级.opencode/opencode.json。核心是两段provider定义通道model指定默认模型。下面是一个可复制的骨架把YOUR_TAOTOKEN_KEY替换成你刚复制的 Key{ provider: { taotoken: { type: openai, options: { baseURL: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY }, models: { claude-sonnet: { name: claude-sonnet-4-20250514 } } } }, model: taotoken/claude-sonnet }这里type用openai是因为 TaoToken 的 API 兼容 OpenAI 格式OpenCode 能直接识别。baseURL固定为https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。models里的name填你实际要调用的模型标识具体可用模型在控制台或文档里查。注意Key 不要提交到 Git。项目级配置建议用.opencode/opencode.json并加入.gitignore或者用环境变量TAOTOKEN_API_KEY然后在配置里写apiKey: {env:TAOTOKEN_API_KEY}。配好之后OpenCode 启动时会读取这个文件。你可以先用一个最小请求验证通道是否通再往下做模板。验证方法在第 4 节。3. 可复制配置md-expand 与自定义命令骨架模板引擎的落地分两块自定义命令负责“独立任务”md-expand负责“动态渲染”。先把目录结构建好再填内容。3.1 目录结构OpenCode 读两个位置项目级.opencode/和全局~/.config/opencode/。项目级优先适合团队共享全局适合个人常用模板。建议这样建# 项目级 mkdir -p .opencode/commands mkdir -p .opencode/snippet # 全局可选 mkdir -p ~/.config/opencode/commands mkdir -p ~/.config/opencode/snippetcommands/放自定义命令snippet/放代码片段。文件名就是命令名review.md对应/review。3.2 第一个自定义命令代码审查创建.opencode/commands/review.md--- description: 审查当前修改的代码指出安全和性能问题 agent: plan --- 请审查我当前修改的代码文件。 审查重点 1. 安全性有没有 SQL 注入、XSS、敏感信息泄露的风险 2. 性能有没有 O(n²) 以上的循环、不必要的重复计算 3. 代码规范命名是否清晰有没有魔法数字 请给出具体的修改建议但不要直接修改文件。 当前修改的文件列表 !git diff --name-only HEAD 请逐一审查上述文件。frontmatter 里agent: plan表示用 Plan 模式执行不会直接改文件。!加反引号是 Shell 输出注入——命令执行时git diff --name-only HEAD会先运行输出结果嵌入提示词。注意格式是!后跟反引号包裹的命令不是普通引号。3.3 带参数的命令生成组件创建.opencode/commands/component.md--- description: 生成一个 React 函数组件 agent: build --- 请创建一个 React 函数组件组件名为 $1。 要求 1. 使用 TypeScriptProps 类型定义完整 2. 使用函数式组件写法不是 class 3. 带基本的 JSDoc 注释 4. 如果传入了 $2把它作为组件的样式主题light/dark 组件放在 src/components/$1.tsx。调用时/component Button dark$1替换成Button$2替换成dark。$ARGUMENTS可以拿全部参数的原始字符串适合 Git 操作这类命令。3.4 md-expand 插件变量与条件md-expand让模板支持{{...}}语法。在opencode.json的plugins数组里加{ plugins: [opencode-plugin-md-expand^0.1.0] }保存后重启 OpenCode插件会自动安装。然后创建.opencode/commands/deploy.md--- description: 生成部署配置 agent: build --- 请根据以下信息生成部署配置文件 环境{{env:NODE_ENV}} API 地址{{env:API_URL}} {{ ifenv:CI }} 当前是 CI 环境请生成适用于自动化部署的配置包含健康检查端点。 {{ else }} 当前是本地环境请生成开发用的配置启用调试日志。 {{ endif }} 项目类型{{arg:type}} 请参考以下规范{{ file./deploy-rules.md }}三种语法{{env:VAR}}读环境变量{{ if条件 }}...{{ endif }}做条件判断{{ file./path }}引用文件内容{{arg:name}}读命令行参数。插件会在 AI 看到之前把{{...}}替换成实际值。3.5 代码片段对话内快速插入自定义命令适合独立执行#snippet适合对话中插入。先装插件opencode plugin opencode-snippets -gf然后在~/.config/opencode/snippet/code-standards.md写入#code-standards 请遵循以下代码规范 1. 使用 2 空格缩进不用 Tab 2. 变量命名用 camelCase常量用 UPPER_SNAKE_CASE 3. 每个函数不超过 30 行超过则拆分 4. 所有公开函数必须有 JSDoc/TSDoc 注释 5. 优先使用 const其次 let避免 var对话里输入src/utils/logger.ts 帮我重构这个文件 #code-standardsOpenCode 会加载文件内容并把 snippet 插入提示词。snippet 可以嵌套#full-review里写#code-standards #security #performance敲一个等于注入三套规范。4. 验证请求确认模板稳定产出配置写完得验证两件事API 通道通不通模板替换对不对。4.1 验证 TaoToken 通道先用一个最小请求确认 Key 和 Base URL 生效。在终端里跑curl -s https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_TAOTOKEN_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }如果返回 JSON 里choices[0].message.content包含OK说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查baseURL是否写成了https://taotoken.net/api不要带路径后缀。4.2 验证自定义命令在任意 Git 项目里创建review.md改一个文件后在 OpenCode TUI 输入/review。预期行为OpenCode 先执行git diff --name-only HEAD把修改的文件列表嵌入提示词然后 AI 逐一审查。如果 AI 回复里提到了你刚改的文件名说明 Shell 注入生效。4.3 验证 md-expand 变量替换设置环境变量后执行/deployexport NODE_ENVproduction export CItrue在 TUI 输入/deploy。预期AI 看到的提示词里{{env:NODE_ENV}}已变成production{{ ifenv:CI }}分支被选中生成的配置包含健康检查端点。如果 AI 回复里出现了{{env:NODE_ENV}}原文说明插件没加载回到第 5 节排查。4.4 验证 snippet 展开在 TUI 输入一条包含#code-standards的消息观察 AI 回复是否遵循了 2 空格缩进、camelCase 命名等规范。如果 AI 把#code-standards当普通文本处理说明 snippet 插件没生效。5. 本篇常见错排查5.1 自定义命令不生效提示 command not found最常见的原因是文件放错位置或文件名不对。项目级命令必须在.opencode/commands/name.md全局在~/.config/opencode/commands/name.md。文件名review.md对应/review不能有多余后缀。改完文件后完全退出 OpenCode按q再重新运行热重载不一定生效。用/help查看命令列表确认你的命令是否出现。5.2 #snippet 不展开直接显示为文本先确认插件装了opencode plugin list看有没有opencode-snippets。没有就重装opencode plugin opencode-snippets -gf。然后检查opencode.json里plugins数组是否包含它。snippet 文件目录也要对全局~/.config/opencode/snippet/项目级.opencode/snippet/。最后重启 OpenCode。5.3 md-expand 的 {{...}} 没有被替换确认opencode.json里插件配置是opencode-plugin-md-expand^0.1.0。插件首次加载时自动安装如果没装上手动npm install -g opencode-plugin-md-expand。模板文件必须是.md格式{{...}}语法不能有拼写错误。还是不行就开调试模式{ plugins: [ [opencode-plugin-md-expand^0.1.0, { debug: true }] ] }重启后看日志通常能定位到是变量名写错还是文件路径不对。5.4 API 返回 401 或模型不存在401 一般是 Key 问题检查apiKey是否完整有没有多余空格。模型不存在则是models里的name填错了去 TaoToken 控制台确认可用模型标识。另外注意baseURL不要写成https://taotoken.net/api/末尾斜杠有时会导致路径拼接问题也不要在 API 地址上加 UTM 参数。6. 把模板变成你的资产模板引擎的本质是把“你反复要说的话”变成“可复用的资产”。从今天开始每次重复描述同一个需求的时候就把它写成模板——以后敲几个字符就能搞定。如果你在配 TaoToken 通道时遇到问题先去https://taotoken.net/api-keys带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite确认 Key 状态接入细节看https://taotoken.net/doc带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。想先验证模型对话是否正常用https://taotoken.net/models带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite跑一轮。如果你打算长期用 OpenCode 做编码和 Agent 任务Coding Plan 的通道更稳入口在https://taotoken.net/coding-plan带 utm?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。下一篇是基础篇 07讲 OpenCode 插件机制扩展核心命令——怎么开发自己的插件、怎么给 OpenCode 增加新命令和工具。模板搭好了插件就是下一步的杠杆。