文档中心

快速开始

UmaDev 是一个模拟真实开发团队工作的本地 Agent。它不提供模型，而是深度适配五个一等底座；Claude Code、Codex、OpenCode 使用厂商专属协议驱动，Grok Build 与 Kimi Code 使用厂商官方 ACP v1 接口和隔离厂商配置，两条路径地位对等。随后由协调者调度产品、架构、设计、前后端、QA、安全和 DevOps 八个角色完成计划、执行、评审、验证与交付。npm 只是预编译 Rust 二进制的分发壳。

npm install -g umadev

Linux 上不要用 sudo 装。npm 默认前缀 /usr/local 属主是 root，普通用户 npm i -g 会 EACCES；而 sudo npm i -g 会在前缀里留下 root 属主的目录树，之后你以普通用户执行的每一条 npm 全局命令（npm update -g、npm i -g 任何包）都会 EACCES 并整体回滚，连带你的底座 CLI（@anthropic-ai/claude-code、@openai/codex）也再也更新不动。请换一个你自己拥有的前缀：

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # 写进 ~/.zshrc 或 ~/.bashrc
npm install -g umadev

或者不做全局安装，直接用 npx 跑（不改前缀、不用 sudo）。注意：不带 -g 的 npm i umadev 能装上，但 npm 按设计不会把本地命令挂到 PATH 上，直接敲 umadev 会提示 command not found —— 这不是装坏了，用 npx umadev 运行即可。已经踩了 sudo 的坑，就跑 umadev doctor，它会检出 root 属主的安装目录或 npm 缓存并打印修复命令。

npx umadev

也可完全跳过 npm。原生安装器不需要 Node 或 sudo，会下载对应平台的 GitHub Release 二进制并校验公开的 SHA-256。用 UMADEV_VERSION 固定版本、UMADEV_INSTALL_DIR 覆盖安装目录；PowerShell 中对应写作 $env:UMADEV_VERSION 和 $env:UMADEV_INSTALL_DIR。

# macOS / Linux
curl -fsSL https://umadev.goder.ai/install.sh | bash

# Windows PowerShell
irm https://umadev.goder.ai/install.ps1 | iex

支持 macOS（Apple Silicon / Intel）、Linux（x86_64 / ARM64，glibc ≥ 2.31 或 musl/Alpine）、Windows x86_64；Windows on ARM 通过系统 x64 兼容层运行同一二进制。也可以从源码构建：

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

准备一个 AI 编码底座

从五个底座中选择一个并按厂商文档安装、登录。UmaDev 不保存登录信息，也不代装、更新、执行交互式登录或授权底座 CLI；下面的命令只用于确认目标二进制已经位于 PATH。

# 厂商专属协议驱动（一等）
claude --version
codex --version
opencode --version

# 官方 ACP v1 协议驱动（一等）
grok --version
kimi --version

如果使用 umadev install --base <id>，安装的是 UmaDev 治理集成（例如 hook），不是底座本身。

Grok Build 的后台机器协议子进程只使用已有 cached token 或 XAI_API_KEY；这里的无头 / 非交互仅指不渲染 Grok 自己的 TUI，UmaDev 仍维持常驻双向用户会话。initialize 后只选择明确可用的后台认证，不会自动启动 OAuth 或打开浏览器；需要 grok login 时，请先在 UmaDev 外自行完成。

Kimi Code 使用官方 @moonshot-ai/kimi-code 与 kimi acp，支持所有官方版本；请先自行运行 kimi login。UmaDev 只通过 ACP 复验已有登录，绝不会自动运行登录或打开浏览器。模型、模式与思考等控制按当前会话实时协商。Windows 还需 Git Bash，非标准路径可设置 KIMI_SHELL_PATH。

初始化项目

cd your-project
umadev init

预览和交付

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

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

一个完整例子

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

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

底座会先把它判断为完整 Build。协调者随后创建可见依赖计划，按步召集角色：澄清与调研 → PRD / 架构 / UIUX → 文档确认 → 执行计划 → 前端预览确认 → 后端 → 质量与安全验证 → 交付证明。你可以在运行中继续追问，或用 /plan 调整后续步骤。

UmaDev 如何工作

UmaDev 自己不持有模型端点。你输入任务后，它让当前底座在一个新的只读判断会话里选择 Chat、Explain、QuickEdit、Debug 或 Build。需要写代码时，协调者拥有计划并驱动主会话逐步完成；角色评审在独立只读分叉里给出结构化结论；确定性规则、测试与运行证据负责最后验收。

真实团队模型

八个专家角色分别负责产品、架构、UI/UX、前端、后端、QA、安全和 DevOps。主会话保持单写者，避免多个 Agent 同时改主干；评审角色使用新的只读会话交叉检查，所有角色只通过计划与团队黑板交接。

任务按比例路由

可见计划与运行中转向

真实构建会生成 .umadev/plan.json。协调者按依赖逐步推进，界面实时显示进度；你在执行中提出的新要求会折入下一步。/plan 可查看计划，也可用 skip、veto、add、up、down 调整步骤。

会话、上下文与记忆

对话会持久化；/compact 压缩上下文、/resume 恢复会话、切换底座时，UmaDev 会携带对话摘要、当前计划、团队黑板、项目事实和运行状态。验证过的踩坑经验、项目事实与运行笔记会在后续任务中按需召回。

质量门是什么

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

[quality]
threshold = 90
skip_checks = []

知识库是什么

UmaDev 内置持续演进的工程标准语料，并把它与 repo-map、项目事实和踩坑记忆一起按任务召回。默认检索是纯 Rust BM25 + 本地向量模型的双通道 RRF 融合，并用 HyDE 扩展查询；本地向量不可用时自动降级为 BM25。语料数量会持续增长，不作为产品协议。

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"

环境变量

五底座能力边界

五个底座全部是一等深度适配，且都不设 CLI 版本白名单：版本号只用于诊断，具体能力由实时协议协商和运行时安全规则决定。底层有三套厂商专属驱动，以及 Grok Build / Kimi Code 两套跟随官方源码的 ACP v1 驱动。

UmaDev 二进制覆盖 macOS（Apple Silicon / Intel）、Linux（x86_64 / ARM64，glibc >= 2.31 或 musl/Alpine）和 Windows x86_64；Windows on ARM 通过系统 x64 兼容层运行同一二进制。厂商 CLI 的系统支持是另一层边界，两个程序必须能在同一环境运行。

底座与模型共享

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

不像 AI 生成的 UI

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

完整构建主链

只有完整产品 Build 才展开这条最深路径；Chat、Explain、小修和 Debug 不会被强迫穿过整条流水线。需求澄清是进入主链前的微阶段，随后是九阶段主链，每一步都有明确负责人和产物。

确认门与人在环

guarded 模式下，docs_confirm 与 preview_confirm 会真正暂停，分别等待你确认文档方向和前端预览；/continue 通过，/revise 带反馈重做。auto 模式可以自动继续，但推送、PR、部署等不可逆外部动作仍然确认。

信任梯度

重做、修订与回滚

交付证据包

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

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 子命令