文档中心

快速开始

UmaDev 是一支本地运行的 AI 开发团队 Agent —— 八个专家角色由一个协调者调度。推荐用 npm 安装预编译二进制，npm 只是分发壳，真正运行的是 Rust 编译出的 umadev 二进制。

npm install -g umadev

支持 macOS（Apple Silicon / Intel）、Linux（x86_64 / ARM64）、Windows x86_64。也可以从源码构建：

git clone https://github.com/umacloud/umadev.git
cd umadev
cargo build --release
./target/release/umadev --version

准备一个 AI 编码底座

UmaDev 推荐驱动你已经登录的 CLI，三选一即可，然后按它们自己的方式登录。UmaDev 不保存你的登录信息，只是把任务作为非交互命令发给它们。

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode-ai

初始化项目

cd your-project
umadev init

预览和交付

/preview     # 前端阶段完成后预览
/deploy      # 交付阶段完成后部署

最终交付证据在 output/、release/、.umadev/audit/。其中 proof-pack.zip 和 scorecard.html 是给团队、客户或审计方看的交付证明。

一个完整例子

在一个空项目里运行 umadev init 然后 umadev，输入：

做一个课程预约小程序，用户可以查看课程、选择时间、预约、取消预约，管理员可以管理课程和预约记录。

UmaDev 会依次：理清需求 → 联网调研竞品 → 生成 PRD → 生成架构 → 生成 UI/UX → 拆执行计划 → 实现前端 → 暂停预览 → 实现后端 → 跑质量门 → 生成交付包。

UmaDev 如何工作

整体架构可以理解成四层：TUI/CLI 是你和 UmaDev 交流的地方；团队协调者决定现在哪个角色做哪个阶段、何时暂停继续；Runtime/底座把任务交给 Claude Code / Codex CLI / OpenCode 写真实代码；治理/质量/证据检查产物是否合规并打包交付。

质量门是什么

质量门是交付前验收，不只是看文件是否存在，而是检查 PRD、架构、UI/UX、前后端契约、构建测试结果、密钥泄露风险、审计日志和合规映射。

[quality]
threshold = 90
skip_checks = []

知识库是什么

UmaDev 内置 416 份 markdown 知识文件，覆盖产品、架构、前后端、数据库、安全、测试、CI/CD、运维、移动端、行业和专家方法论。

umadev knowledge-manage add ./team-docs --name team-docs
umadev knowledge-manage search "支付 webhook 幂等"

配置文件

首次运行会写入 ~/.umadev/config.toml(语言 + 默认底座);项目级可用 .umadevrc 覆盖。质量门阈值与跳过项放在项目根配置里。

# ~/.umadev/config.toml
backend = "claude-code"
lang = "zh-CN"

环境变量

底座与模型共享

UmaDev 不持有模型端点。它驱动你已登录的底座 CLI,自动读取并沿用底座当前配置的模型与推理强度——不强加任何 --model。底座用官方登录还是接了第三方 / 本地模型,跑的就是那个。

不像 AI 生成的 UI

前端阶段强制使用 UIUX 文档声明的设计系统:图标库、设计 token、字体、组件骨架。一套反 AI-slop 设计法把命名禁令(默认 indigo、紫渐变、emoji 图标、虚构指标、模板骨架)做成硬规则;设计审查对照它,不符合就自动打回重做。

九个阶段

UmaDev 把「AI 写代码」拆成九个有序阶段,每个阶段产出真实文件,关键节点设人在环确认门。

确认门与人在环

两道确认门(docs_confirm、preview_confirm)让你在文档方向与前端预览两个关键点确认后再继续,而不是 AI 一口气跑完。门处可 /continue 通过,或 /revise 带反馈重做本阶段。

重做、修订与回滚

交付证据包

交付阶段把整个开发过程打包成可审计的证据:产物文档、构建测试结果、治理审计日志、质量门成绩单——给团队 / 客户 / 审计方一份「这是怎么做出来的」的完整证明。

release/proof-pack-<slug>-<date>.zip
release/scorecard-<slug>.html
.umadev/audit/*.jsonl

合规映射

治理证据(UD-EVID-004)自动映射到 SOC 2、ISO 27001、EU AI Act 的相关条目,让交付物天然带合规线索,而不是事后补材料。

质量门成绩单

质量门不是「文件在不在」,而是逐项打分:PRD / 架构 / UI-UX 完整度、前后端契约对齐、构建测试结果、密钥泄露、审计日志、合规映射。低于阈值(默认 90)不放行,生成 scorecard.html 可视化成绩单。

作为 MCP server

UmaDev 可作为 MCP server 运行,把治理能力(govern_file / govern_command)暴露给其它支持 MCP 的工具,让它们写文件前也过同一套规则。

umadev mcp serve

在 CI 里跑治理

把治理放进 CI:对改动的源文件跑同一套规则(禁 emoji 图标 / 硬编码颜色 / 密钥泄露 / AI 套话),不合规则 CI 失败。

umadev ci

常见问题

Q:需要 API key 吗? 不需要——UmaDev 驱动你已登录的底座 CLI,用的是它自己的订阅 / 登录。

Q:底座超时 / 没响应? 用 /doctor 自检底座是否在 PATH 且已登录;可用 UMADEV_WORKER_TIMEOUT 调超时,或 /offline 临时切离线模板继续。

Q:产物存在哪? output/(文档与代码笔记)、release/(交付包与成绩单)、.umadev/audit/(审计证据链)。

TUI 斜杠命令

终端 CLI 子命令