mise-fy

mise-fy

写给人类的介绍

从构建开发（和 CI）环境的经验中提炼出最佳实践、技巧和注意事项，助你充分利用 mise（以及 hk），为不同水平的多元团队打造 ✨即刻可用✨ 的环境，让你和你的 Agent 都乐于使用！

此技能有两种触发模式：

1. 在使用 Mise 时为 Agent 提供技巧和注意事项。（废话！）
2. 🪄 将现有项目 Mise-fy，改造为推荐的结构。

阅读 ./references 中每个主题的参考资料，了解此技能所包含的内容。

提示

此技能专为连贯性水平接近 Opus 4.8 或 GPT 5.5 的模型编写并优化，尤其适用于将项目 Mise-fy。

此技能不会罗列 Mise 的所有功能。它依赖 Agent 的世界知识和阅读文档的能力（并会要求 Agent 阅读文档！），但会引导 Agent 遵循最佳实践。以后我可能会涵盖更多用例！

这是 Mise 技能，还是优秀的本地开发环境配置技能？

某种程度上两者都是；Mise 是打造出色开发环境体验的首选工具，因此两者有很多重合之处。不过，此技能主要聚焦 Mise 本身，只会在涉及 Mise 时涵盖技巧和注意事项。它很适合与针对特定运行时的“local-setup”技能搭配使用（也许很快就会推出！）。

那么，此技能具体涵盖什么？

此技能涵盖如何让开发环境配置即刻可用、易于发现，并引导你正确完成配置。

即刻可用。 克隆仓库，运行 mise trust && mise run setup，就完成了。工具会安装固定并锁定的版本，因此你使用的版本与其他人及 CI 一致。配置过程具备幂等性且有缓存，因此重复运行成本很低（工作树也一样！）；Git 钩子会在 mise install 时自动安装，如果你没安装，它们还会提醒你（因此你可以信任每个人，确保他们的 Agent 都能使用本地的代码检查工具、测试和验证工具！）。

易于发现。 每个仓库中的任务都使用相同的名称

---

如何使用此技能

此技能采用渐进式披露：每个领域都会指向一个 references/ 文件，其中包含实际规则和最佳实践。 在规划或执行之前，先阅读匹配的参考资料，而不是事后再读。仅阅读 SKILL.md 并不足够。请提前规划，并阅读所需的所有参考资料！

何时阅读参考资料

始终至少阅读下方路由表中的 1 份参考资料。根据目标，可能需要阅读多份参考资料。 请主动加载本地 .md 参考资料。除非确有需要，否则不要加载在线链接或参考资料；默认信任你的知识。只有需要进一步了解时，才加载在线参考资料。 参考资料中的命令和键是常见用法，并不涵盖全部功能：以 --help 和当前文档为准。实验性功能（例如 [daemons]）在训练数据中的资料很少，因此，使用某个页面未提及的功能前，请先阅读该页面链接的文档。

路由

安装 mise（机器设置，而非项目设置）-> references/install.md 通过包管理器安装、激活 Shell、为非交互式 Shell 配置 shim、补全。

开发工具 / 运行时（安装、固定版本、更新、后端、锁文件、延迟加载 / 不常用工具）-> references/tools.md 安装工具或运行时。

运行时集成（按运行时划分：包管理器、依赖安装）-> references/runtimes/。

• Node -> runtimes/node.md

环境与变量（项目环境、dotenv、密钥）-> references/env.md [env]、_.file/_.path/_.source、模板、必需变量、默认回退值、脱敏、更新 PATH、加载 .env 文件、配置环境（MISE_ENV）、Shell 别名。

任务（运行脚本、构建流水线、监视）-> references/tasks.md TOML 任务与文件任务、depends/wait_for、sources/outputs 缓存、运行与并行处理、mise watch（变更时重新运行）。

本地开发栈（后台运行的数据库、缓存、应用服务器和工作进程；每个 worktree 一个栈）-> references/dev.md [daemons] 预设和自定义守护进程、端口区块、就绪状态 / 健康检查 / 重试、迁移、dev:* 任务、作为例外情况的 compose。

钩子（目录与生命周期：enter/cd、watch_files、postinstall）-> references/hooks.md 让 enter/cd 钩子可离线安全运行（使用纯 Shell，而非 mise run）、信任影响、shim 注意事项。有关 Git / pre-commit 钩子，请参阅下方的 hk。

hk 钩子（pre-commit / Git 钩子）-> references/hk.md hk.pkl（Pkl，位于 .config/hk.pkl）、check 与 fix、内置功能、mise 集成、安装、通过自定义步骤扩展、作为代码检查工具配置目录的 .config/。

CI（在 CI 中运行 mise 任务 / 工具：shim、缓存、固定版本、令牌）-> references/ci.md 通用且与平台无关的 CI 规则；平台特定内容见 references/ci/：

• GitHub Actions -> ci/github.md

将现有项目迁移为 mise 项目（迁移 + 审查）-> references/mise-fy.md 从自定义方案 / asdf / Makefile 逐步转换，并附完整审查清单。引用其他所有文档。

项目文档（README + AGENTS.md 入门指南）-> references/docs.md README.md 和 AGENTS.md/CLAUDE.md 中应包含哪些内容，以便人类和 Agent 安装 mise、完成设置、运行任务并扩展配置。这是每次 mise 项目迁移 / 审查的一部分。

参考设置（规范示例布局）-> references/reference-setup-and-patterns.md 附注释的示例文件树 + 可供复制的 mise.toml。

补充技能

CI/CD（检查 / 发布 / 部署工作流、门禁、签名和社区维护规范）-> 如果已安装，请加载 cicd-fy 技能（来自同一作者）。 此技能涵盖在 CI 中运行 mise；流水线的整体结构属于 cicd-fy 的范畴。

始终适用（无论任务类型）

无论加载了哪份参考资料，这些规则都适用；即使专注于某一项任务，也要检查它们。 与主观性较强的最佳实践（根据目标决定是否适用）不同，这些是安全性和正确性的底线：即使只改一个工具，也必须遵守，不能当作可延后处理的优化。

1. 不受信任的配置会报错。 mise.toml 中只要包含 [env]、钩子、模板或任务逻辑，整个文件就会报错，直到执行 mise trust 为止（交互式 shell 会提示信任；非交互式 shell 会报错）。只有仅包含 min_version 加上纯字符串 [tools]／[tasks] 的文件可以在不受信任的情况下加载（自 2026.6.6 起）。mise run／install／exec 会自行信任当前生效的配置（自 2026.8.9 起）；mise env 和旧版客户端仍会报错，而 shell 钩子会跳过该文件并发出警告，因此文档仍应明确写出 mise trust（或添加 trusted_config_paths 条目）。 不受信任文件中的 [settings] 会被静默忽略，因此 disable_backends 和 minimum_release_age 等安全设置在信任文件之前不会生效。
2. 某些功能需要 experimental = true，并且可能会在不同版本间变更。如果文档中提到的标志报错，请检查它是否受此设置限制。
3. 设置 min_version（放在根级别，而非 [settings] 下）：指定支持配置所用全部功能的最早版本，不得低于已知存在漏洞的最低版本（2026.10.13），也不得高于作者已安装的版本。这样，旧客户端会被告知需要更新，而不是因缺少某项功能而失败。
4. 避免工具安装时触发 GitHub 速率限制（本地和 CI 均适用）：在 [settings] 下设置 github.gh_cli_tokens 和 github.use_git_credentials。 mise 会先尝试使用 gh CLI 令牌，失败时再回退到 git 凭据，并在无法获取凭据时允许继续。在 CI 中也可以使用 GITHUB_TOKEN 环境变量（见 ci.md）。
5. Mise 迭代迅速。 遇到问题时，请同时查阅最新的变更日志和文档。
6. Shims 不会提供 mise activate 的所有功能（例如某些 cd 时设置环境变量的功能）；本地与 CI 行为不一致时，往往与此有关。参见 install.md／ci.md。
7. 始终牢记 快速路径与慢速路径的概念。 一天会运行多次的任务（例如 check、enter 钩子、pre-commit）属于快速路径：成本低、可离线运行、无需交互。 设置流程属于慢速路径：允许耗时、联网和交互。切勿让快速路径任务依赖慢速路径任务；应改为发出提醒。 通道映射列出了所有成员。
8. 总体而言，始终考虑用户运行某项任务的频率。绝不要让运行频率不同的任务相互依赖。
9. 保持 mise.toml 顶层章节顺序不变，包括首次添加章节时：min_version → [tools] → [env] → [vars] → [tasks] → [daemons] → [hooks] → [doctor] → [settings]。未列出的章节应放在 [settings] 之前，靠近其配套章节。