mise-tasks

mise 任务编排

使用 mise [tasks] 部分编排多步骤项目工作流，并管理依赖项、参数和文件跟踪。

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏差，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

明确触发条件：

• 用户提到 mise tasks、mise run、[tasks] 部分
• 用户需要任务依赖项：depends、depends_post
• 用户希望在 .mise.toml 中实现工作流自动化
• 用户提到任务参数或 usage 规范

AI 发现触发条件（指示性）：

当 mise-configuration 技能检测到多步骤工作流（测试套件、构建流水线、迁移）时，应调用此技能来生成相应的 [tasks] 定义。

快速参考

任务定义

[tasks.build]
description = "Build the project"
run = "cargo build --release"

运行任务

mise run build          # Run single task
mise run test build     # Run multiple tasks
mise run test ::: build # Run in parallel
mise r build            # Short form

依赖类型

类型	语法	时机
depends	depends = ["lint", "test"]	在任务运行前运行
depends_post	depends_post = ["notify"]	任务成功后运行
wait_for	wait_for = ["db"]	仅在运行时等待

关键任务属性

属性	用途	示例
description	便于 AI Agent 发现（重要）	"Run pytest with coverage. Exits non-zero on failure."
alias	简短名称	alias = "t"
dir	工作目录	dir = "packages/frontend"
env	任务专属环境变量（不会传递给依赖项）	env = { LOG_LEVEL = "debug" }
hide	在 mise tasks 输出中隐藏	hide = true
sources	用于缓存的文件跟踪	sources = ["src/**/*.rs"]
outputs	若比源文件新则跳过	outputs = ["target/release/myapp"]
confirm	执行前提示确认	confirm = "Delete all data?"
quiet	禁止输出 mise 信息	quiet = true
silent	禁止所有输出	silent = true
raw	直接使用标准输入/输出（禁用并行执行）	raw = true
tools	任务专属工具版本	tools = { python = "3.9" }
shell	自定义 Shell	shell = "pwsh -c"
usage	参数规范（优先于 Tera）	参见任务参数

命名空间

mise run 'test:*'      # All tasks starting with test:
mise run 'db:**'       # Nested: db:migrate:up, db:seed:test
mise tasks --hidden    # View hidden tasks (prefixed with _)

如需了解各级别的详细示例和模式，请参阅任务级别参考。

---

第 10 级：Monorepo（实验性）

要求：MISE_EXPERIMENTAL=1 且 experimental_monorepo_root = true

mise run //projects/frontend:build    # Absolute from root
mise run :build                       # Current config_root
mise run //...:test                   # All projects
mise run '//projects/...:build'       # Build all under projects/

子目录中的任务会自动发现，并添加路径前缀（packages/api/.mise.toml 中的任务会变为 packages/api:taskname）。

完整的 Monorepo 文档请参阅：advanced.md

---

第 11 级：使用 Pants + mise 的多语言单体仓库

对于以 Python 为主的多语言单体仓库（10-50 个包），将用于运行时管理的 mise 与用于构建编排和原生受影响项检测的 Pants 结合使用。

工具	职责
mise	运行时版本（Python、Node、Rust）+ 环境变量
Pants	构建编排 + 原生受影响项检测 + 依赖推断

# Native affected detection (no manual git scripts)
pants --changed-since=origin/main test
pants --changed-since=origin/main lint
pants --changed-since=origin/main package

规模	建议
< 10 个包	mise + 自定义受影响项检测（第 10 级模式）
10-50 个包（以 Python 为主）	Pants + mise（本节）
50+ 个包	考虑 Bazel

完整的 Pants + mise 集成指南和工具比较，请参阅 polyglot-affected.md。

---

与 [env] 集成

任务会自动继承 [env] 值。使用 _.file 指定外部环境文件，并使用 redact = true 处理机密信息。

[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.file = { path = ".env.secrets", redact = true }

[tasks._check-env]
hide = true
run = '[ -n "$API_KEY" ] || { echo "Missing API_KEY"; exit 1; }'

[tasks.deploy]
depends = ["_check-env"]
run = "deploy.sh"  # $DATABASE_URL and $API_KEY available

有关完整的环境集成模式，请参阅 环境集成。

---

反模式

反模式	不妥之处	建议做法
用 mise 任务替代 /itp:go	没有 TodoWrite、ADR 跟踪或检查点	用 mise 任务处理项目工作流，用 /itp:go 进行 ADR 驱动的开发
在任务中硬编码机密信息	存在安全风险	使用 _.file = ".env.secrets" 和 redact = true
使用庞大的单体任务	难以调试，无法复用	拆分为带依赖关系的小任务
省略或仅填写简单的 description	AI Agent 无法仅凭名称推断任务用途	编写详尽的描述：说明任务的功能、要求、产出和运行时机
发布任务未设置构建 depends	会导致运行时失败，而非通过 DAG 预防	为发布任务添加 depends = ["build"]
编排器未包含所有阶段	“接下来运行 X”之类的消息会被忽略	在 release:full 的 depends 数组中包含所有阶段

有关发布专属的反模式和模式，请参阅 发布工作流模式。

---

交叉参考：mise-configuration

前置条件：定义任务之前，请确保已配置 [env] 部分。

PRESCRIPTIVE：定义任务之后，请调用 mise-configuration skill，确保应用了 [env] 单一事实来源（SSoT）模式。

mise-configuration skill 涵盖：

• [env] - 带默认值的环境变量
• [settings] - mise 行为配置
• [tools] - 版本固定
• 特殊指令：_.file、_.path、_.python.venv

---

其他资源

• 任务级别参考 - 级别 1-9：基础任务、依赖项、隐藏任务、参数、文件跟踪、高级执行、监视模式
• 任务模式 - 真实场景中的任务示例
• 任务参数 - 完整的用法规范参考
• 高级功能 - Monorepo、监视、实验性功能
• 环境集成 - [env] 继承与凭据加载
• 多语言受影响项 - Pants + mise 集成指南和工具比较
• 引导 Monorepo - 自主多语言 Monorepo 引导元提示词
• 发布工作流模式 - 发布任务 DAG 模式、发布前强制构建

---

故障排除

问题	原因	解决方案
找不到任务	拼写错误或 mise.toml 有误	运行 mise tasks 列出可用任务
未运行依赖项	存在循环依赖	检查任务的 depends 数组是否存在循环
源文件未生效	glob 模式有误	使用相对于 mise.toml 所在位置的路径
监视未触发	文件不在 sources 列表中	将文件模式添加到 sources 数组中
环境变量不可用	任务目录不正确	确保 mise.toml 位于 cwd 或其父目录中
运行失败并报错	脚本路径问题	使用绝对路径或相对于 mise.toml 的路径

执行后反思

此技能完成后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口有所变更，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通处理？ — 如果你不得不临时调整（使用不同的标志、增加步骤），请更新此 SKILL.md，避免下次调用时再次遇到同样的问题。

仅当问题真实且可复现时才更新，不要更新推测性问题。