用途
mise-tasks 是一套规则与最佳实践，用于编写和编辑 mise 任务。它面向需要为项目定义可复用命令任务的开发者，规范了任务的放置位置、命名规则以及各语言任务的编写方式。
任务的命名与位置
任务应放在 .mise-tasks/ 目录或其子目录中，任务路径对应任务名称。例如：
- .mise-tasks/start.sh 对应 mise run start
- .mise-tasks/test/app.mts 对应 mise run test:app
- .mise-tasks/agents/worktree/init.sh 对应 mise run agents:worktree:init
创建任务后需运行 chmod +x <task> 使其可执行。可通过 mise.toml 了解任务可用的工具和环境变量。对于 TypeScript 任务，根目录的 package.json 提供了便于用 TypeScript 编写任务的工具函数。
Bash 任务配置
任务选项必须紧跟在初始 shebang 行之后，每个选项独占一行，形式为 #MISE <option>=<value>。所有 shell 脚本必须以下述 shebang 加一个空行开头：#!/usr/bin/env bash。任务必须兼容 bash 3.2+，因为这是 macOS 的默认版本。如需交互式脚本，gum 是很好的工具。
可用的任务选项包括：
- description（字符串）：任务描述，用于帮助输出、补全、无参数 mise run 和 mise tasks。
- depends（字符串或数组）：必须先于本任务运行的任务，可传参数（如 depends = ["build --release"]）；多个任务共享同一依赖时该依赖只运行一次，mise 会尽可能并行执行。
- env（键值映射）：本任务专属环境变量，不会传递给 depends 任务。
- dir（字符串，默认 "{{ config_root }}"，即包含 mise.toml 的目录）：运行任务的工作目录。
- hide（布尔，默认 false）：从帮助、补全和 mise tasks 等输出中隐藏任务，适用于已弃用或内部任务。
- confirm（字符串）：运行前显示的确认消息，适用于破坏性或耗时较长的任务。
- sources（字符串或数组）：任务使用的输入文件或目录。与 outputs 同时定义时，若最旧输出文件的修改时间新于最新源文件，mise 会跳过执行，适合昂贵且仅在输入变化时需要运行的任务。任务本身会自动作为源加入，也会用于 mise watch 判断监听哪些文件/目录。支持相对路径和 glob 模式（如 src/**/*.rs），但不要在一个 glob 中加入过多文件。
- outputs（字符串、数组或 { auto = true }）：与 sources 对应，任务执行后创建/修改的文件或目录。auto = true 是手动指定输出文件的替代方式，mise 会基于任务定义哈希 touch 一个内部跟踪文件（存放于 ~/.local/state/mise/task-outputs/<hash>），适用于希望源变化时重新执行但不想手动 touch 文件的场景。
- quiet（布尔，默认 false）：抑制 mise 对任务的输出（如
[build] $ cargo build），仅显示脚本自身输出；若要连任务输出也隐藏，用 silent。 - silent（布尔、"stdout" 或 "stderr"，默认 false）：抑制任务的全部输出；设为 "stdout" 或 "stderr" 时仅抑制对应流。
- redactions（字符串数组）：从任务输出中隐藏敏感信息的环境变量列表，例如 #MISE redactions=["API_KEY", "PASSWORD"]，输出会显示为 echo [redacted]，也支持 glob 模式如 redactions.env = ["SECRETS_*"]。
任务输入参数
任务可通过 flags 定义输入。关键是要利用 flags，而不是隐式依赖环境变量，但可以在任务定义中把环境变量映射到 flags。在 bash 任务中，flags 通过 #USAGE 指令定义，涵盖以下用法：别名（alias）、隐藏别名（hide=#true）、全局 flag（global=#true）、默认值（default）、计数型 flag（count=#true）、可重复 flag（var=#true 或 ...）、可变参数（<pattern>...）、最少/最多值（var_min/var_max）、取反（negate）、由环境变量支持的 flag（env）、文件/目录补全（<file>/<dir>）、条件必填（required_if/required_unless）、覆盖（overrides）、选项限制（choices）以及长帮助（long_help，支持多行字符串）。
TypeScript 任务配置
TypeScript 任务与 bash 任务在配置上有许多相通之处，主要差异为：所有位于 .mise-tasks/**/*.mts 的 TypeScript 任务必须以 .mts 结尾；必须使用 shebang：#!/usr/bin/env -S node --disable-warning=ExperimentalWarning --experimental-strip-types。配置指令使用 //MISE 与 //USAGE 注释形式。示例中展示了如何导入 node:assert、zx（$ 与 chalk）以及 @clack/prompts（交互式提示），并通过 process.env["usage_out_file"] 等方式读取 flag 值。
Python 任务配置
Python 任务使用与 bash 任务相同的 #MISE/#USAGE 指令语法（井号注释形式），通常通过 uv 配合内联脚本头运行。需要注意的是：ruff format 步骤会把注释规范化为井号后加空格，从而把 #MISE/#USAGE 改写成 # MISE/# USAGE，而 mise 按字面解析这些指令，改写会静默破坏任务（描述和 flags 消失）。ruff 本身没有跳过注释规范化的设置，因此需用 # fmt: off / # fmt: on 将指令块围起来，这样既保持指令完整，ruff 仍能格式化文件其余部分。示例同时展示了 # /// script 头中的 requires-python = ">=3.11"。
适用场景与限制
该文档适用于为 mise 项目编写和维护任务定义的场景，尤其是需要跨 Bash、TypeScript、Python 三种实现方式统一任务规范、控制任务依赖与增量执行、保护输出中的敏感信息时。限制方面，任务必须兼容 bash 3.2+；sources glob 不宜包含过多文件；Python 任务必须处理 ruff 重写注释的问题；具体的官方文档链接、分类来源及更多配置项未在资料中完整提供。