oma-dev-workflow

开发工作流 - Monorepo 任务自动化专家

调度

目标

使用 mise、语言专用检查、commitlint、验证流水线、CI/CD、迁移、i18n 构建和发布协调，搭建、运行、优化和排查可复现的开发工作流。

意图特征

• 用户询问开发服务器、mise 任务、lint/format/typecheck/test/build、Git 钩子、CI/CD、迁移、生成的客户端、i18n 构建或发布自动化。
• 用户需要执行工作流或设置开发环境，而非实现产品功能。
• 用户询问如何配置 Ruff/pyrefly、Biome/TypeScript 7、Dart/Flutter 检查、Hadolint 或 commitlint。

适用场景

• 为包含多个应用的 monorepo 运行开发服务器
• 在多个应用中并行执行 lint、format、typecheck
• 管理数据库迁移和架构变更
• 根据架构生成 API 客户端或代码
• 构建国际化（i18n）文件
• 执行生产构建并准备部署
• 在 monorepo 环境中运行并行任务
• 设置提交前验证工作流
• 配置语言专用 lint、format 和 typecheck 工具、Dockerfile lint，以及提交消息验证
• 排查 mise 任务失败或配置问题
• 使用 mise 优化 CI/CD 流水线

不适用场景

• 数据库架构设计或查询调优 -> 使用 DB Agent
• 后端 API 实现 -> 使用 Backend Agent
• 前端 UI 实现 -> 使用 Frontend Agent
• 移动端开发 -> 使用 Mobile Agent

预期输入

• 请求的工作流操作、受影响的应用/软件包以及当前 monorepo 结构
• 相关的项目清单文件、锁文件、工具配置、mise.toml、任务定义、CI 文件、钩子管理器和故障日志
• 期望的验证、设置或发布结果

预期输出

• 已执行或已记录的 mise 任务工作流
• 按需更新工作流配置、CI/CD 流水线、钩子、环境模板或发布指南
• 选定配置文件对应的项目本地工具依赖/配置，以及可运行的 lint、format、format:check、typecheck 和 commitlint 任务
• 状态报告，包含命令、输出、失败情况和后续操作

依赖项

• mise、项目任务定义、运行时版本，以及 mise 任务所使用的包管理器
• 用于验证、数据库模式、API 工作流、i18n、发布协调和故障排查的资源指南
• 所选语言工具链和本地安装的 commitlint；Git 钩子不得下载软件包

控制流特性

• 根据受影响的应用、任务依赖图、端口可用性、任务失败情况以及 CI/发布环境进行分支处理
• 调用本地进程命令；可能会写入工作流/配置文件
• 必须避免执行破坏性任务，并避免在工作流配置中存放密钥

结构流程

入口

1. 确定受影响的应用/软件包和所需的工作流结果。
2. 阅读 mise.toml 文件和可用任务。
3. 确定任务能否并行运行，或是否必须按顺序执行。

阶段

1. 准备：分析需求、任务图、运行时前提条件和端口。
2. 获取：检查 mise 配置、任务定义、CI 钩子、环境变量模式和日志。
3. 执行：运行或修改 mise 任务、工作流配置或验证流水线。
4. 验证：检查退出代码、生成的构件、日志和 CI 兼容性。
5. 完成：报告命令状态、耗时、失败情况和后续步骤。

转换

• 如果运行时版本发生变化，运行 mise install。
• 如果存在针对变更文件的任务，优先进行变更范围验证。
• 如果端口被占用，在启动开发服务器前解决占用问题或选择其他端口。
• 如果不熟悉某项任务，运行前先阅读其定义。
• 对于设置，保留现有工具和命令；仅在缺少配置时应用语言默认值。对于仅执行的请求，使用现有检查，不安装或替换工具。
• /stack-set 会检测并记录技术栈。此技能负责工具设置以及任务/CI 接线；领域技能使用最终生成的验证命令。

失败与恢复

• 如果缺少任务，运行 mise tasks --all。
• 如果缺少运行时，运行或建议运行 mise install。
• 如果任务挂起，检查是否有提示，或是否存在开发服务器长时间运行的情况。
• 如果请求执行破坏性任务，必须先获得确认。
• 如果选定的检查器无法运行，将该检查报告为未完成，并在范围内修复其设置；不要用通过的占位任务或构建来替代它。
• 如果某个钩子因另一项检查仍在运行而跳过，并以 0 退出，则该次推送未经验证。停止此前由你启动的运行，或以非零状态退出。不要用 || true 掩盖门禁失败。

退出

• 成功：工作流运行或配置变更已验证。
• 部分成功：明确说明任务失败、运行时缺失或 CI/环境阻碍。

逻辑操作

操作

操作	SSL 原语	证据
阅读任务定义	READ	mise.toml、CI 配置
选择任务策略	SELECT	并行/顺序/变更范围
运行工作流命令	CALL_TOOL	mise run、mise install、mise tasks
编写工作流配置	WRITE	钩子、CI、环境模板
验证输出	VALIDATE	退出代码、日志、产物
报告状态	NOTIFY	最终工作流摘要

工具与资源

• mise、shell、CI/CD 工具，以及由 mise 管理的项目包管理器任务
• 验证、数据库、API、i18n、发布和故障排除资源指南

标准命令路径

1. 检查受影响应用的清单、锁文件、工具配置、mise.toml、CI、钩子以及任何 stack/stack.yaml。阅读任务定义，并使用 mise tasks --all 查找现有命令。
2. 对于设置或工具变更，从 References 加载所选工具配置。使用检测到的包管理器配置缺失的依赖、设置和任务；保留现有工具选择。仅执行检查时，跳过设置。
3. 将适用的检查作为 lint、format:check 和 typecheck 暴露出来；将会修改内容的 format 单独保留。check 任务可以汇总不会生成输出的检查。将现有的栈 verify.syntax.cmd 连接到该任务，不要添加不受支持的架构键；保留 verify.tests 和领域专用扫描。
4. 对于钩子/CI 设置，加载验证流水线。先配置已锁定的本地工具，保留现有钩子管理器，并将 commitlint 连接到本地 commit-msg 钩子。暂存文件 lint 保留在 pre-commit 上。如果提交耗时是限制因素，则在 push 门禁上对受影响的整个应用执行类型检查。配置 CI，以运行应用检查和测试。
5. 重新启动本地验证前，遵循验证流水线关于重复运行的指导。跳过的运行不算通过。运行已配置的 mise run check 汇总任务，或适用的单项 lint、format:check 和 typecheck 任务，以及相关的现有测试。每个底层检查器只运行一次。对于已配置的 monorepo，使用 mise run //{path}:{task}；对受影响的整个应用进行类型检查，而非仅检查单个变更文件。
6. 报告所选工具、命令、通过的检查，以及任何不可用或不适用的检查。构建仍须遵循执行政策。

资源范围

范围	资源目标
CODEBASE	mise.toml、CI 配置、脚本、生成的客户端
LOCAL_FS	环境模板、构建产物、日志
PROCESS	mise、构建、测试、lint、开发服务器命令
CREDENTIALS	不得在工作流配置中硬编码密钥

前置条件

• 可以确定目标工作流和受影响的项目区域。
• 可以发现任务定义；如果缺失，则应报告任务缺失状态。

影响和副作用

• 可能启动开发服务器、运行测试或构建、生成客户端、运行迁移，或编辑工作流配置。
• 可能占用 CPU 和时间，或占用端口。

防护措施

1. 始终使用 mise run 任务，而不是直接运行包管理器命令
2. 拉取可能更新运行时版本的更改后，运行 mise install
3. 对独立操作使用并行任务（mise run lint、mise run test）。如果测量结果显示增加工作进程会拖慢同一测试套件，则限制并发数
4. 对更改涉及的范围运行 lint 和测试。保留已有的仓库选择器，它会对共享路径或未知路径安全失败；不要用通用的受影响检查辅助工具替换它
5. 提交前使用 commitlint 验证提交消息
6. 仅对已暂存文件运行提交前验证流水线
7. 配置 CI 跳过未更改的应用，以加快构建
8. 运行前先检查 mise tasks --all，发现可用任务
9. 为 CI/CD 集成验证任务输出和退出码
10. 在 mise.toml 注释中记录任务依赖关系
11. 在各应用之间采用一致的任务命名约定
12. 在 CI/CD 流水线中启用 mise，以实现可复现的构建
13. 在 mise.toml 中固定运行时版本，以保持一致
14. 提交 CI/CD 更改前先在本地测试任务
15. 切勿从 Git 钩子获取软件包。如果 mise 任务已经运行检查器，则调用该任务。在 mise exec 下运行的钩子可以直接调用已固定版本的本地二进制文件
16. 未了解任务依赖关系时，切勿修改 mise.toml
17. 工具链版本更新后，切勿跳过 mise install
18. 未先检查端口是否可用时，切勿运行开发服务器
19. 暂存的 lint 检查失败时，切勿提交。如果每次提交都进行类型检查会显著增加提交耗时，则应在推送关卡中对整个受影响应用进行类型检查
20. 切勿忽略任务失败；始终调查根本原因
21. 切勿在 mise.toml 文件中硬编码密钥
22. 切勿假定任务可用；始终使用 mise tasks 验证
23. 未经确认，切勿运行破坏性任务（clean、reset）
24. 运行不熟悉的任务前，切勿跳过阅读任务定义
25. 在 mise.toml 中，任务名称包含 : 时必须加引号（[tasks."lint:changed"]）——未加引号的冒号会导致 TOML 解析失败
26. 使用 //path:task 语法前，必须在根目录的 mise.toml 中设置 monorepo_root = true（并添加 [monorepo].config_roots）
27. 检查任务必须保持非变更性；仅在请求的编辑范围内运行格式化/修复任务，且 Git 钩子绝不能重写未暂存的更改

技术指南

前置条件

# Install mise
curl https://mise.run | sh

# Activate in shell
echo 'eval "$(~/.local/bin/mise activate)"' >> ~/.zshrc

# Install all runtimes defined in mise.toml
mise install

# Verify installation
mise list

项目结构（Monorepo）

project-root/
├── mise.toml            # Root task definitions
├── apps/
│   ├── api/            # Backend application
│   │   └── mise.toml   # App-specific tasks
│   ├── web/            # Frontend application
│   │   └── mise.toml
│   └── mobile/         # Mobile application
│       └── mise.toml
├── packages/
│   ├── shared/         # Shared libraries
│   └── config/         # Shared configuration
└── scripts/            # Utility scripts

根目录的 mise.toml 必须启用 Monorepo 任务路径，否则每次调用 //path:task 都会失败，并显示“require a monorepo root configuration”：

# Root mise.toml — monorepo_root is a top-level key (before any [table])
monorepo_root = true

[monorepo]
config_roots = ["apps/*", "packages/*"]

任务语法

根级任务：

mise run lint        # Lint all apps (parallel)
mise run test        # Test all apps (parallel)
mise run dev         # Start all dev servers
mise run build       # Production builds

应用专属任务：

# Syntax: mise run //{path}:{task}
# Requires monorepo_root = true in root mise.toml (see Project Structure)
mise run //apps/api:dev
mise run //apps/api:test
mise run //apps/web:build

**TOML 引号规则：**任务名称包含 : 时必须加引号——使用 [tasks."gen:api"]，不要使用 [tasks.gen:api]（未加引号的冒号会导致 TOML 解析错误）。

常见任务模式

任务类型	用途	示例
dev	启动开发服务器	mise run //apps/api:dev
build	生产构建	mise run //apps/web:build
test	运行测试套件	mise run //apps/api:test
lint	运行代码检查工具	mise run lint
format	格式化代码	mise run format
format:check	检查格式，不写入更改	mise run format:check
typecheck	类型检查	mise run typecheck
check	汇总适用的非生成类检查	mise run check
migrate	数据库迁移	mise run //apps/api:migrate

参考指南

主题	资源文件	加载时机
验证流水线	resources/validation-pipeline.md	Git 钩子、CI/CD、基于变更的测试、重复的本地验证
数据库与基础设施	resources/database-patterns.md	迁移、本地 Docker 基础设施
API 生成	resources/api-workflows.md	生成 API 客户端
i18n 模式	resources/i18n-patterns.md	国际化
发布协调	resources/release-coordination.md	版本管理、变更日志、发布
故障排除	resources/troubleshooting.md	调试问题

任务依赖

在 mise.toml 中定义依赖：

[tasks.build]
depends = ["lint", "test"]
run = "echo 'Building after lint and test pass'"

[tasks.dev]
depends = ["//apps/api:dev", "//apps/web:dev"]

并行与顺序执行

并行（独立任务）：

# Runs all lint tasks simultaneously (via depends)
mise run lint

# mise-native parallel execution of multiple tasks
mise run lint ::: test

顺序执行（存在依赖的任务）：

# Runs in order: lint → test → build
mise run lint && mise run test && mise run build

混合方式：

# Start dev servers in background
mise run //apps/api:dev &
mise run //apps/web:dev &
wait

环境变量

Monorepo 环境变量的常见模式：

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Cache
REDIS_URL=redis://localhost:6379/0

# API
API_URL=http://localhost:8000

# Frontend
PUBLIC_API_URL=http://localhost:8000

输出模板

设置开发环境时：

1. 验证运行时是否已安装（mise list）
2. 各应用的依赖安装命令
3. 环境变量模板（.env.example）
4. 开发服务器启动命令
5. 常见任务速查

运行任务时：

1. 包含完整路径的已执行命令
2. 预期输出摘要
3. 耗时及成功／失败状态
4. 后续建议操作

故障排除时：

1. 诊断命令（mise config、mise doctor）
2. 常见问题的解决方案
3. 端口／进程冲突解决方法
4. 必要时使用的清理命令

故障排除指南

问题	解决方案
找不到任务	运行 mise tasks --all 列出可用任务
找不到运行时	运行 mise install 安装缺失的运行时
任务卡住	检查是否有交互式提示；如果支持，使用 --yes
端口已被占用	查找进程：lsof -ti:PORT，然后终止进程
权限被拒绝	检查文件权限，尝试使用具有适当权限的用户
缺少依赖	运行 mise run install 或应用专用的安装命令

执行方法

按步骤遵循核心工作流：

1. 分析任务要求 - 确定受影响的应用和任务依赖
2. 检查 mise 配置 - 验证 mise.toml 结构和可用任务
3. 确定执行策略 - 决定采用并行还是顺序执行任务
4. 运行前置步骤 - 按需安装运行时和依赖
5. 执行任务 - 运行 mise 任务并妥善处理错误
6. 验证结果 - 检查输出、日志和生成的制品
7. 报告状态 - 总结成功／失败情况，并提供可执行的后续步骤

执行协议（CLI 模式）

参考资料

• 工具链配置：resources/tooling-profiles.md（配置或更改 Python、JS/TS、Dart/Flutter、Dockerfile 或 commitlint 工具链）
• 澄清说明：../_shared/core/clarification-protocol.md
• 任务分解：../_shared/core/difficulty-guide.md（未解决的范围或依赖）

知识参考

mise、任务运行器、monorepo、开发服务器、代码检查、格式化、测试、类型检查、构建、部署、CI/CD、并行执行、工作流、自动化、工具链