Kilo Code Workflows 完整指南:用 Markdown 斜杠命令自动化编码流程

原创2026-10-09 22:55:281,345 阅读
文章标签:人工智能AI 应用AI Agent代码智能体开发工具IDECLIMCP Clients

Kilo Code Workflows 完整指南:用 Markdown 斜杠命令自动化编码流程

Workflows(新扩展中也称为 slash commands / 斜杠命令)是 Kilo Code 中把重复性编码任务固化为可复用指令的机制:你只需编写一份带步骤说明的 Markdown 文件,然后在聊天框输入 /命令名 即可让 Agent 按步骤执行。本文将以 packages/kilo-docs/pages/customize/workflows.md 为主体,结合仓库源码(命令配置 Schema、命令加载实现 等)展开,带你掌握从创建、配置到实战迁移的完整流程。

Kilo Code 中的 Workflows 配置选项卡

什么是 Workflows

Workflow 本质上是一份 步骤化指令模板:它告诉 Kilo Code "遇到这个命令时,按什么顺序、用什么工具、达成什么目标"。与普通对话不同,Workflow 将流程固化,让每次执行行为一致,适合发布管理、项目初始化、代码审查准备这类高频重复任务。

从源码看,命令在运行时由独立的 CommandV2 Service 管理,它以 Map<string, Info> 维护命令注册表,并提供 get / list / update / remove 操作;命令的元信息(模板、描述、Agent、模型、variant、subtask)由 ConfigV2.Command.Info 这个 Effect Schema 定义,加载时通过 config-command 插件 将磁盘上的 Markdown 文件扫描并解码进注册表。

创建 Workflow

存放位置与作用域

Workflow 是存放在命令目录下的 Markdown 文件,分为两级作用域:

  • 全局命令:~/.config/kilo/commands/,对所有项目可用
  • 项目命令:[项目根目录]/.kilo/commands/,仅对当前项目可用

文件命名即命令名:.kilo/commands/submit-pr.md 对应 /submit-pr(调用时去掉 .md 扩展名)。加载逻辑在 config/plugin/command.ts 中:插件用 fs.glob("{command,commands}/**/*.md", ...) 在配置目录下递归扫描 Markdown 文件,再通过 decode 把文件内容解析为命令——文件名去除 command/commands 前缀和 .md 后缀后即命令名。

符号链接目录与外部命令权限

如果你的 .kilo/commands/ 是指向项目外目录的符号链接,Kilo Code 默认将外部来源视为不受信任,需要在 全局 配置文件 ~/.config/kilo/kilo.jsonc 中显式放行该精确来源:

{
  "permission": {
    "markdown_source": {
      "/path/to/shared/commands/*": "allow"
    }
  }
}

两点安全限制需要牢记:

  1. 项目配置无法授予此权限——只有全局配置能放行外部命令源,因为项目内配置可能随代码被他人提交,不能作为信任依据;
  2. 外部命令文件保持不受信任:{env:...} 替换会被阻止,{file:...} 替换也仅限项目内部使用,防止外部文件借命令读取敏感环境变量或越权访问文件。

该权限键在权限 Schema 中确有对应定义,见 packages/core/src/v1/config/permission.ts 中的 markdown_source: Schema.optional(Rule) 注释 "explicitly authorize external agent/command sources"。

基础三步设置

  1. 创建一个包含逐步指令的 .md 文件
  2. 保存到上述命令目录
  3. 在聊天框输入 /命令名(只写文件名,不带 .md)执行

可选 Frontmatter

命令文件支持 YAML frontmatter 来配置元信息,frontmatter 解析由 packages/core/src/config/markdown.ts 中的 gray-matter 完成(该文件还实现了对未加引号冒号值的兼容性重试,保证与其他编码 Agent 的既有配置文件兼容):

---
description: Submit a pull request with checks
agent: code
---

You are helping submit a pull request...
字段 说明
description 显示在命令选择器中
agent 调用该命令时使用哪个 Agent
model 该命令的模型覆盖
variant 推理强度(reasoning effort)变体覆盖,例如 low 或 high,仅对支持变体的模型生效
subtask 设为 true 时,作为子 Agent 会话运行

这些字段与源码中的 ConfigV2.Command.Info Schema 完全一致(template、description、agent、model、variant、subtask)。解码时,frontmatter 之外的全部正文被作为 template(即命令实际执行的提示词)使用,见 decode 函数。

值得说明的是命令正文中的变量占位符:$ARGUMENTS 会被替换为用户在命令后输入的全部内容,$1、$2… 则取对应位置参数。仓库内置的 /review 命令模板(packages/core/src/plugin/command/review.txt)就是一个利用 $ARGUMENTS 区分提交哈希、分支名、PR 号/URL 的成熟范例。

保留名称:/goal

goal 是会话目标(Session Goals)功能的保留命令。如果你的配置或插件中定义了名为 goal 的命令,它会被忽略:Kilo 会报告一条配置警告,并保留自己的 /goal 命令,但你自定义的命令仍可通过 /goal:command 访问——这与 skill 与命令冲突时以 /name:skill 形式提供的规则一致。

模型与推理变体(Model and Reasoning Variant)

每个 Workflow 都可以使用独立的模型与推理强度变体运行。在 VS Code 扩展中:打开 Settings → Agent Behaviour → Workflows,展开某个 Workflow,即可选择模型与变体。该选择会以命令覆盖(command override)的形式保存到全局配置中,Workflow 模板文件本身不会被改动。

除了图形界面,你也可以在命令 frontmatter 或 kilo.jsonc 的 command 段中设置 model 与 variant。从源码看,模型覆盖会经过 ModelV2.parse 解析为 { id, providerID, variant },变体则通过 ModelV2.VariantID.make 生成,见 config/plugin/command.ts。

两点行为细节:

  • variant 仅当所选模型支持时生效——如果换成一个不提供该变体的模型,之前设置的变体会被清除;
  • 运行时若选定的变体不在模型支持的列表内,模型层会报错 Variant unavailable for {provider}/{model}: {variant}(见 packages/core/src/session/runner/model.ts),所以配置时务必确认模型能力。

Workflow 能力范围

Workflow 可以调用全部内置工具:read、glob、grep、edit、write、bash、webfetch,以及 MCP 服务器工具。这意味着一个 Workflow 既能读文件、搜代码、改代码,也能跑 shell 命令和访问外部 MCP 能力,足以覆盖从"检查代码质量"到"创建 PR 并部署"的完整链路。

从旧版 Workflow 迁移

新版扩展在启动时会自动把旧版 ./.kilocode/workflows/ 目录下的 Workflow 迁移为新的命令格式。你也可以手动迁移:移动文件到新目录,并在调用时去掉 .md 扩展名。迁移后建议核对 frontmatter 字段(旧格式中不存在的 agent / subtask 等可按需补充)。

常见 Workflow 模式

发布管理(Release Management)

1. Gather merged PRs since last release
2. Generate changelog from commit messages
3. Update version numbers
4. Create release branch and tag
5. Deploy to staging environment

项目初始化(Project Setup)

1. Clone repository template
2. Install dependencies (`npm install`, `pip install -r requirements.txt`)
3. Configure environment files
4. Initialize database/services
5. Run initial tests

代码审查准备(Code Review Preparation)

1. Search for TODO comments and debug statements
2. Run linting and formatting
3. Execute test suite
4. Generate PR description from recent commits

仓库中内置命令 /review 的模板(review.txt)展示了真实生产级 Workflow 的写法:它按 $ARGUMENTS 判断审查对象(未提交改动 / 指定 commit / 分支对比 / PR),先取 diff 再读取完整文件上下文,最后给出结构化的审查输出规范——你完全可以参考它的结构设计自己的审查类 Workflow。

实战示例:PR 提交 Workflow

在 .kilo/commands/ 目录创建 submit-pr.md:

---
description: Submit a pull request with full checks
---

# Submit PR Workflow

You are helping submit a pull request. Follow these steps:

1. First, use `grep` to check for any TODO comments or console.log statements that shouldn't be committed
2. Run tests using `bash` with `npm test` or the appropriate test command
3. If tests pass, stage and commit changes with a descriptive commit message
4. Push the branch and create a pull request using `bash` with `gh pr create`
5. Use `question` to get the PR title and description from the user

Parameters needed (ask if not provided):

- Branch name
- Reviewers to assign

在聊天框输入 /submit-pr 即可触发。Kilo Code 会:

  • 提交前扫描代码中的常见问题(TODO、调试语句等)
  • 运行测试套件及早发现问题
  • 处理 Git 操作与 PR 创建
  • 为部署安排后续任务

这样你就不必每次提交代码审查时手动重复同样的步骤。

进阶:理解命令的加载与覆盖机制

如果你同时使用了全局命令、项目命令和 kilo.jsonc 中的 command 段,了解加载顺序能帮你避免踩坑:

  1. 扫描注册:config-command 插件遍历所有配置条目,对 document 类型条目直接取内联命令,对目录类型条目递归扫描 {command,commands}/**/*.md(见 loadDirectory);
  2. 模板优先:第一轮遍历只应用带 template 的命令——注意 ConfigV2.Command.Info 中 template 是可选的,这允许"部分覆盖":仅覆盖描述、模型等字段而不替换模板;
  3. 字段合并:第二轮遍历按顺序应用 description、agent、model、variant、subtask 等非模板字段,只有命令尚不存在时才新建占位。

换言之,kilo.jsonc 的 command 段与 Markdown 文件可以混合使用:Markdown 提供模板主体,配置段提供运行时覆盖(如切换模型)。这也解释了为什么 VS Code 里通过 Settings 保存的模型选择不会改动模板文件本身——它写入的是全局配置覆盖。

小结

Workflows 把"告诉 Agent 做什么"升级为"定义 Agent 怎么做",用一份 Markdown 文件即可固化团队流程、统一执行标准。要点回顾:命令存放在 ~/.config/kilo/commands/(全局)或 .kilo/commands/(项目);frontmatter 支持 description / agent / model / variant / subtask;goal 为保留名称;外部命令源需在全局配置中通过 markdown_source 放行;旧版 .kilocode/workflows/ 会自动迁移。从创建第一个 /submit-pr 开始,把重复劳动交给 Workflow 吧。

登录后查看全文
kilocode