oma-dev-workflow

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

调度

目标

使用 mise、任务自动化、验证流水线、CI/CD、迁移、i18n 构建和发布协调，在 monorepo 中设置、运行、优化和排查可复现的开发工作流。

意图特征

• 用户询问开发服务器、mise 任务、lint/格式化/类型检查/测试/构建、Git 钩子、CI/CD、迁移、生成的客户端、i18n 构建或发布自动化。
• 用户需要执行工作流或设置开发环境，而非实现产品功能。

适用场景

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

不适用场景

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

预期输入

• 请求执行的工作流操作、涉及的应用/包以及当前 monorepo 结构
• 相关的 mise.toml、任务定义、CI 文件、迁移/i18n/构建配置和失败日志
• 期望的验证、设置或发布结果

预期输出

• 已执行或已记录的 mise 任务工作流
• 按要求更新的工作流配置、CI/CD 流水线、钩子、环境模板或发布指南
• 包含命令、输出、失败情况和后续操作的状态报告

依赖项

• mise、项目任务定义、运行时版本以及 mise 任务所用的包管理器
• 用于验证、数据库模式、API 工作流、i18n、发布协调和故障排查的资源指南

控制流特性

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

结构流程

入口

1. 确认涉及的应用/包以及请求的工作流结果。
2. 查看 mise.toml 文件和可用任务。
3. 确定任务是否可以并行运行，或必须按顺序运行。

阶段

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

转换

• 如果运行时版本发生变化，请运行 mise install。
• 如果存在针对变更文件的任务，优先使用变更范围验证。
• 如果端口被占用，启动开发服务器前先解决端口冲突或选择其他端口。
• 如果不熟悉某项任务，运行前先查看其定义。

失败与恢复

• 如果任务缺失，请运行 mise tasks --all。
• 如果运行时缺失，请运行或建议运行 mise install。
• 如果任务挂起，请检查是否有提示或长时间运行的开发服务器行为。
• 如果请求执行破坏性任务，必须先确认。

退出

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

逻辑操作

操作

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

工具和工具链

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

标准命令路径

mise tasks --all
mise install
mise run lint
mise run test

对于特定应用的任务：

mise run //{path}:{task}

资源范围

范围	资源目标
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／test（lint:changed、test:changed）
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. 存在 mise 任务时，绝不直接运行包管理器命令
16. 未了解任务依赖关系前，绝不修改 mise.toml
17. 工具链版本更新后，绝不跳过 mise install
18. 未先检查端口是否可用，绝不运行开发服务器
19. 未对受影响的应用运行验证，绝不提交
20. 绝不忽略任务失败——务必调查根本原因
21. 绝不在 mise.toml 文件中硬编码密钥
22. 绝不假定任务可用——务必使用 mise tasks 验证
23. 未经确认，绝不运行具有破坏性的任务（clean、reset）
24. 运行不熟悉的任务前，绝不跳过阅读任务定义
25. 始终为包含 : 的任务名加引号（[tasks."lint:changed"]）——不加引号的冒号会导致 TOML 解析失败
26. 使用 //path:task 语法前，始终在根目录的 mise.toml 中设置 monorepo_root = true（以及 [monorepo].config_roots）

技术指南

前置条件

# 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
typecheck	类型检查	mise run typecheck
migrate	数据库迁移	mise run //apps/api:migrate

参考指南

主题	资源文件	加载时机
验证流程	resources/validation-pipeline.md	Git 钩子、CI/CD、基于变更的测试
数据库与基础设施	resources/database-patterns.md	迁移、本地 Docker 基础设施
API 生成	resources/api-workflows.md	生成 API 客户端
国际化模式	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 模式）

参考资料

• 澄清：../_shared/core/clarification-protocol.md
• 任务分解：../_shared/core/difficulty-guide.md（范围或依赖项尚未明确时）

知识参考

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