mise-configuration

将 mise 配置作为唯一事实来源

使用 mise [env] 作为集中配置，并提供向后兼容的默认值。

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

何时使用此技能

在以下情况下使用此技能：

• 在 mise.toml 中集中管理环境变量
• 使用 mise 设置 Python venv 自动创建
• 为单体仓库实现中心辐射式配置
• 创建向后兼容的环境配置模式

核心原则

在 .mise.toml 的 [env] 部分定义所有可配置值。脚本通过环境变量读取这些值，并使用后备默认值。无论是否安装 mise，都使用相同的代码路径。

关键要点：当 shell 配置了 mise activate 时，mise 会自动加载 [env] 中的值。使用 os.environ.get("VAR", "default") 模式的脚本，无论是否安装 mise，运行效果都相同。

快速参考

语言模式

语言	模式	说明
Python	os.environ.get("VAR", "default")	返回字符串；若为整数则转换
Bash	${VAR:-default}	标准 POSIX 展开
JavaScript	process.env.VAR || "default"	检查假值；注意 "0"
Go	os.Getenv("VAR") with default	未设置时返回空字符串
Rust	std::env::var("VAR").unwrap_or()	返回 Result

特殊指令

指令	用途	示例
_.file	从 .env 文件加载	_.file = ".env"
_.path	扩展 PATH	_.path = ["bin", "node_modules/.bin"]
_.source	执行 bash 脚本	_.source = "./scripts/env.sh"
_.python.venv	自动创建 Python venv	_.python.venv = { path = ".venv", create = true }

有关带选项（redact、tools、多文件）的详细指令示例，请参阅：代码模式

Python Venv 自动创建（关键）

自动创建并激活 Python 虚拟环境：

[env]
_.python.venv = { path = ".venv", create = true }

所有项目都使用此模式。进入已激活 mise 的目录时：

1. 如果 .venv 不存在，则创建它
2. 自动激活 venv
3. 配合 uv 快速创建 venv

通过 [settings] 设置的替代方案：

[settings]
python.uv_venv_auto = true

中心辐射式架构（关键）

将特定领域的任务委托给子文件夹中的 mise.toml 文件，从而保持根目录下的 mise.toml 精简。适用于单体仓库、ML/研究项目、基础设施和数据管道。

关键规则：

• 中心配置管理 [tools] 和编排任务
• 辐射配置自动继承中心配置的 [tools]
• 辐射配置的 [env] 会扩展中心配置的 [env]（可按领域覆盖）
• .mise.local.toml 在目录级别生效（密钥保留在本地）

包含目录结构、示例和反模式的完整指南：中心辐射式架构

Wiki 参考：Pattern-mise-Configuration

单体仓库工作区模式

对于使用 uv 工作区的 Python 单体仓库，venv 会创建在工作区根目录。应使用 [dependency-groups]（PEP 735）将开发依赖提升至根目录的 pyproject.toml。

完整指南：单体仓库工作区模式

模板语法（Tera）

mise 使用 Tera 模板。分隔符：{{ }} 表达式、{% %} 语句、{# #} 注释。

内置变量

Variable	描述
{{config_root}}	包含 .mise.toml 的目录
{{cwd}}	当前工作目录
{{env.VAR}}	环境变量
{{mise_bin}}	mise 二进制文件的路径
{{mise_pid}}	mise 进程 ID
{{xdg_cache_home}}	XDG 缓存目录
{{xdg_config_home}}	XDG 配置目录
{{xdg_data_home}}	XDG 数据目录

有关函数（get_env、exec、arch、read_file、hash_file）、过滤器（snakecase、trim、absolute）和条件语句，请参阅：代码模式 - 模板语法

必需变量和已遮盖变量

[env]
# Required - fails if not set
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }

# Redacted - hides from output
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }

# Pattern-based redactions
redactions = ["*_TOKEN", "*_KEY", "PASSWORD"]

有关组合模式和详细示例，请参阅：代码模式 - 必需变量和已遮盖变量

延迟求值（tools = true）

默认情况下，环境变量会在工具安装之前解析。使用 tools = true 可访问工具生成的路径：

[env]
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }
_.file = { path = ".env", tools = true }

[settings] 和 [tools]

[settings]
experimental = true
python.uv_venv_auto = true

[tools]
python = "<version>"
node = "latest"
uv = "latest"
rust = { version = "<version>", profile = "minimal" }

# SSoT-OK: mise min_version directive, not a package version
min_version = "2024.9.5"

有关完整的设置参考和版本固定选项，请参阅：代码模式 - 设置和工具

实施步骤

1. 识别硬编码值 - 超时、路径、阈值、功能标志
2. 创建 .mise.toml - 添加 [env] 部分，并加入带说明的变量
3. 添加虚拟环境自动创建 - _.python.venv = { path = ".venv", create = true }
4. 更新脚本 - 使用环境变量，并将原始值设为默认值
5. 添加 ADR 引用 - 注释：# ADR: 2025-12-08-mise-env-centralized-config
6. 不使用 mise 进行测试 - 验证脚本能否使用默认值运行
7. 使用 mise 进行测试 - 验证已激活的 shell 是否使用 .mise.toml 中的值

GitHub 令牌多账户模式 {#github-token-multi-account-patterns}

mise 不管理 GitHub 令牌（ADR 2026-06-21）。 已停用通过 mise [env] 按目录注入 GH_TOKEN 的方式。GitHub 身份由仓库的 origin 主机别名决定 （[email protected]<account>:owner/repo）：SSH 密钥、提交身份 （includeIf hasconfig:remote.*.url）和 gh 账户均由此派生。 ~/.zshrc 中的 gh 包装器会清除任何环境中已有的 GH_TOKEN。脚本需要令牌时， 请实时解析：GH_PAT="$(~/.claude/tools/bin/gh-token-for-repo)"。

完整指南：GitHub 多账户身份验证（主机别名模式）

反模式

反模式	原因	建议做法
mise exec -- script.py	强制依赖 mise	使用带默认值的环境变量
.mise.toml 中的密钥	在仓库中可见	使用 Doppler 或 redact = true
脚本中没有默认值	不使用 mise 时会出错	始终提供回退值
用于 pueue 任务的 [env] 密钥	Pueue 使用干净的 shell 运行，不包含 mise	使用 python-dotenv 和 .env 文件
通过 SSH 泄露 __MISE_DIFF	导致远程信任错误	SSH 前执行 unset __MISE_DIFF

关于非交互式 shell 密钥的关键细节：反模式指南

任务编排集成

在配置 mise 时检测到项目中的多步骤工作流后，调用 mise-tasks 技能，以定义具有依赖项管理的任务。

检测触发条件：多步骤工作流、可重复执行的命令、依赖链、文件跟踪的构建。

包含示例的完整指南：任务编排 | mise-tasks 技能

---

其他资源

• 代码模式与模板 - Python、Bash、JS、Go、Rust 的完整代码示例，以及完整的 .mise.toml 模板
• 中心辐射架构 - 目录结构、中心与辐射节点的职责、继承规则
• GitHub 令牌模式 - 多账户设置、验证、1Password 集成
• 反模式指南 - 非交互式 shell 密钥、pueue/cron/systemd 常见问题
• 任务编排 - 工作流检测触发条件、环境到任务的示例
• Monorepo 工作区 - uv 工作区、提升的开发依赖项（PEP 735）
• Wiki：Pattern-mise-Configuration

ADR 参考：实现 mise 配置时，请在项目的 docs/adr/YYYY-MM-DD-mise-env-centralized-config.md 创建一份 ADR。

---

故障排除

问题	原因	解决方案
环境变量未加载	mise 未激活	在 shell rc 文件中添加 mise activate
未创建虚拟环境	未安装 Python	运行 mise install python
未找到任务	mise.toml 位置错误	确保 mise.toml 位于项目根目录
PATH 未更新	shims 不在 PATH 中	将 mise shims 添加到 ~/.zshenv
.file 未加载	缺少 .env 文件	创建 .env 文件或移除 .file 指令
子文件夹配置被忽略	缺少 min_version	在子文件夹的 mise.toml 中添加 min_version

执行后反思

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

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

仅在问题真实且可复现时更新，不要更新推测性内容。