UmaDev 深度拆解：用 Rust 写了一个会自己进化的 AI 项目总监

作者：UmaCloud 团队
开源地址：https://github.com/umacloud/umadev
定位：本地运行的 AI 编码项目总监 Agent

一、一句话定位

UmaDev 是一个不接模型、不存 API Key 的 Rust 项目总监 Agent。它把 Claude Code / Codex / OpenCode 等底座工具当子进程驱动，自己套了一条九阶段商业交付流水线，外加治理、质量门、证据链和自进化记忆。

不是让 AI 更聪明地写代码，而是让 AI 靠谱地走完从需求到交付的完整流程。

二、从 SuperDev 到 UmaDev：为什么需要重写？

作者之前开源过 SuperDev，定位是"规范驱动的末端检查器"——AI 写代码时帮你拦 emoji 当图标、颜色硬编码、危险代码注入。但问题是：

• 没有流程，没有状态，没有记忆
• 拦得住一行坏代码，管不了一整个项目怎么走
• 产出质量完全取决于模型和工具的成色，极不稳定

核心洞察：要让产出稳定，光在末端拦截没用，得从源头把整条交付流程接管下来。

于是用 Rust 从零重写，目标：从一个末端检查器，升级成能从一句需求管到交付的真正的 Agent。

三、两大刻意设定

设定一：不接模型，驱动你电脑上已登录的底座

UmaDev 自己不接模型、不卖 API。真正写代码的是用户电脑上已经登录的底座 CLI（Claude Code、Codex、OpenCode）。UmaDev 把它们当子进程拉起，自己一个 key 都不存。

底座原本配的是什么（官方登录、第三方模型、本地模型），跑的就是什么。默认连 --model 都不传，边界干净到极致。

设定二：套一条九阶段商业交付流水线

底座负责聪明地写代码，UmaDev 负责让这件事按真实团队的流程完成——可检查、可恢复、可审计。

如果把普通 AI 编码工具比成一个很能干的工程师，UmaDev 扮演的是产品经理、架构师、UI 评审、技术负责人、QA 和交付经理这一整排角色。

四、工程架构：Rust 单二进制，十 crate 六万行

agent/       → 总监引擎（九阶段流水线、状态机）
governance/  → 治理内核（25 clause → 112 规则）
knowledge/   → 检索系统（BM25 + 向量混合检索）
host/        → 底座驱动（Claude Code / Codex / OpenCode）
contract/    → 契约校验（API 前后端对账）
spec/        → 规范定义（UMADEVHOSTSPEC_V1）
tui/         → 终端界面
runtime/     → 运行时基础设施
i18n/        → 国际化
主程序/       → 入口

五、设计理念：四条铁律

1. 确定性的外壳，配上别人的大脑

UmaDev 的核心是确定性 Rust 代码，智能部分留给底座模型。从不注入模型或 key，用户的订阅、模型、认证全程在自己手里。

2. 规范驱动

所有实现围着一份叫 UMADEVHOSTSPEC_V1 的规范转。25 条 clause，每条都有 UD-LAYER-NNN 编号。规范在代码里是一份 Rust 数据结构，同时配一份等价的散文版，两边由单元测试锁死——谁改了对不上就编译不过。规范和实现从机制上不会各说各话。

3. 治理必须 fail-open

任何一个治理函数，只要自己抛了异常，就必须返回放行。 底座的活绝不能因为治理代码的 bug 而被挡死。这是死规矩。

4. 一切留痕

每个阶段都落产物，每次工具调用都进日志，最后打出交付包 + 合规映射。一次 AI 交付从一场聊天，变成一件能拿给团队、客户、审计方查验的事。

为什么选 Rust？

• 冷启动快、静态二进制、无运行时依赖
• 类型系统够强，能把规范直接编码成数据结构，再用测试锁死
• tokio 异步让并发驱动子进程、收两路输出、套超时变得安全
• release 下开 panic=abort，配上 fail-open，要么稳稳走，要么干净退场

六、九阶段流水线与状态机

clarify ──→ research ──→ docs ──→ docs_confirm(门) ──→ spec
                                                              │
                                                              ↓
preview_confirm(门) ←── frontend ←── delivery ←── quality ←── backend

两道确认门

docs_confirm 和 preview_confirm 是人工介入点。门一开，流水线挂起，等你点头：

• 你回"继续" → 往下走
• 你给具体意见 → 带着反馈把这一段重做

智能裁剪：不是什么都走九步

前面有个纯规则判别器（中英文关键词，不调模型），判断这是个什么活：

• 修 bug → 跳过调研和写 PRD，直接排计划、改、测、过门
• 只做前端 → 裁掉后端阶段
• 从零开始 → 走完整流程

认不准时保守按"从零开始"兜底。判别器纯规则，又快又稳。

能停能续的原子状态机

每走一步，当前阶段、开着的门、原始需求、用的底座，都写进 workflow-state.json。

写盘策略：先写临时文件，再原子重命名（rename 系统调用）。写到一半断电不会留下半个坏文件。

历史快照：每次变更前旧状态快照进 history，留最近 50 份。隔天回来接着干，或者退回上一步，都行。

单写锁：同一个工作区同一时间只允许一个 UmaDev 在写。崩溃残留的锁超过 6 小时自动判定过期回收——跟 git 处理 index.lock 学的。

覆盖率核对：需求 ↔ 实现死死绑在一起

spec 阶段拆出的每个任务，都要回链到 PRD 里某条功能需求的 FR 编号。反过来每条 FR 也都得有任务认领。

哪条需求没人做，或者哪个任务凭空冒出来、不对应任何需求，都会被标出来。 AI 想偷偷漏掉一个功能都不行。

七、不接模型，怎么驱动三个底座？

三个底座脾气不同，UmaDev 在 host crate 里给每个写了独立驱动器，对上层统一成 Runtime 接口。

子进程管理：三个隐蔽的坑

坑一：管道死锁

子进程的标准输出、标准错误、进程结束三件事，如果顺序读，万一某个孙进程攥着管道不放，就会卡死。

解决：用 tokio 把三件事并行做，外面套超时（默认 5 分钟），超了直接杀，绝不留孤儿进程。

坑二：命令行参数长度上限

Linux 上单条命令行参数上限约 120KB。系统提示 + 对话历史很容易顶上去。

解决：系统提示最多留 90K，整体压到 110K 以内。超了从最早的历史往后砍，留住最近几轮，并在被砍的地方留说明。

坑三：离线模式

留了一个纯确定性模板模式，不连网、不调模型。跟三个真底座共用同一个 Runtime 接口，总监引擎分不清底下是真模型还是模板。脱网就能跑通整条流水线逻辑。

八、知识库与混合检索：内置 400+ 份工程标准

一个好总监，脑子里得装着行业标准。UmaDev 内置 400+ 份 Markdown，覆盖产品、架构、API、前后端、数据库、安全、测试、CI/CD、各行业门道。

检索架构：BM25 + 向量，RRF 融合

需求进来 → 分词
         ├──→ BM25 关键词检索（纯 Rust，离线跑）
         │      k1=1.2, b=0.75
         ├──→ 向量语义检索（text-embedding-3-small, 1536维）
         │      配 key 才启用，算余弦相似度
         └──→ RRF 融合（k=60）→ 取 top_k=12

两路结果用倒数排名融合（RRF）排序。一个文档两边都靠前，融合分更高。最后挑出最相关的 12 条注入当前阶段提示词。

文档预处理

按 Markdown 结构切分，标题层级、代码块尽量保完整，避免把一段话拦腰截断。检索最小单位是块，命中后带出所在章节。粒度 + 上下文都照顾到。

一个藏得很深的 bug：CJK 分词

最早分词器只认 ASCII。中文需求分出来零个词，BM25 形同虚设——英文一切正常，中文一上来就废。

解决：重写分词器。每个中文字既单独成词，也跟后一个字组二元词。比如"登录系统"切成：登、登录、录、录系、系、系统、统。

这是 CJK 检索的经典轻量做法，不上分词模型和词典，中英文混写照样处理。

向量缓存：内容哈希驱动

给 400+ 文档算向量花钱花时间。解决方案：

• 每个文档块正文算 SHA-256 哈希
• 向量按内容哈希存储，不认位置认内容
• 重建索引时内容没变的块直接复用，只重算改过的
• 换台机器重新 clone，内容一样照样命中

早期用文件修改时间做签名，一 clone 全失效。后来换成内容哈希才解决。

检索的 fail-open

网络断了、key 失效了、索引坏了——绝不报错卡流程。悄悄退回 BM25，甚至返回空结果，让上层照常走。

九、自我进化：越用越懂你的四条机制

机制一：记忆和反馈闭环

大模型天生无状态。UmaDev 把本该丢掉的反馈，结构化存进项目 .umadev 目录。

核心结构：Lesson

Lesson {
  type,        // 教训类型
  domain,      // 技术领域
  root_cause,  // 根因
  fix,         // 修法
  fingerprint, // 稳定去重指纹
  count,       // 累计踩了几次
  efficacy     // 修法管不管用
}

经验来源四处：

1. 质量门失败 → 直接生成 Lesson
2. 你在确认门提的修订 → 生成 Lesson
3. 跑代码时的真实报错 → 丢进错误分类器，生成 Lesson
4. 顺利过门的好模式 → 沉淀为正向经验

原始记录 → 攒多了 → 按领域归类、去重 → 生成 Markdown → 被检索吸收

全局提升：够通用的教训提升到 ~/.umadev/learned，下个项目开局就带着经验。

会话简报：每次会话生成一份简报（动作类型、当前阶段、状态、推荐底座）。第二天说"继续"，读这份简报就知道昨天干到哪、下一步干嘛。上下文一点不丢。

机制二：从错误里学习——错误指纹家族

同样是"找不到模块"，TypeScript、Python、Rust 报错千差万别，但根因和修法相通。

分类器：十几种错误家族（缺模块、包冲突、权限不足、类型不匹配、空指针、端口占用、CORS、连接被拒……），挨个匹配。

指纹计算：给每个错误算稳定指纹。难点是报错里全是噪声——路径、行号、内存地址每次不同。写归一化函数把这些易变部分剔掉。路径行号完全不同的报错，落到同一个指纹上，踩坑次数才能准确累加。

疗效追踪：一条坑不只记踩了几次，还记修法管不管用。

机制三：自动拼装提示词——coach 模块

每个阶段喂给底座的提示词，没有一句写死。coach 模块现场拼装：

提示词 = 规范前言
       + 本阶段检索到的知识（top 12）
       + 跟当前需求最相关的历史教训
       + 当前生效的设计系统

挑历史教训的三层打分：

1. 判别器命中（最高权重）：某条坑的指纹尾段出现在当前项目的依赖清单里——这是最强的"正在发生"信号
2. 技术栈和关键词重叠：叠加匹配度
3. 疗效方向：复发的往上顶、已验证的往下压
4. 踩坑频率微调

机制四：工具和技能自动扩展

技能机制：一个技能 = 一个包（知识文档 + 治理规则 + 系统提示词）。安装时做路径安全校验防穿越。装完本事就长在项目上。

MCP Server 模式：UmaDev 能把自己变成 MCP server，对外暴露"查文件合规"、"查命令危险"两个工具。Cursor、Continue、Claude Desktop 可以反过来调用它的红线检查。

私货知识库：团队自己的规范文档加进去，跟内置 400+ 份一起进检索。

十、治理、质量门、契约：防止 AI 偷工减料

治理层：25 条 clause → 112 条规则

覆盖 UI 质量、安全红线、前后端质量、各语言危险写法（Rust 的 unwrap、Go 的 panic、Python 的裸 except）。

四个入口：

1. Claude Code 的写入前钩子
2. CI 流水线扫描
3. 作为 MCP 供其他工具调用
4. 交付前的质量门补扫

四个入口 → 统一 fail-open 内核 → 审计日志 + 合规证据

质量门：90 分及格，一票否决

交付前动真格检查：

• PRD 有没有目标、范围、验收标准？
• 架构有没有 API、数据模型、鉴权？
• UI 文档有没有设计 token、暗黑模式、字体规范？
• 前端调的接口跟后端契约对不对得上？
• 有没有泄露密钥？
• 有没有 Dockerfile、CI、迁移这些上线要件？

打分规则：每项打分，默认 90 分及格。但有个硬规则——哪怕总分 92，只要有一项关键文档检查失败，整个门不给过。

契约校验：前后端对账

把架构文档里的 API 表格解析成带类型的接口规格，再扫一遍前端代码里所有 fetch、axios 调用，两边对账：

• 前端调了后端没声明的接口 → 报"未声明调用"
• 方法对不上 → 报"方法不匹配"
• 顺手渲染成标准 OpenAPI 文件

代码跑不起来时的自动修复

质量门发现代码跑不动，不直接甩失败。把报错丢进错误分类器，拿到根因和修法，拼成修复提示词喂给底座，改完重新验证。修好了就把这条教训标成"已验证"。

审计与合规

所有过程写进 .umadev/audit 下的 JSONL，最后映射到 SOC 2、ISO 27001、欧盟 AI 法案的条款。连同 proof-pack 和成绩单一起交付。

十一、关键参数速查表

十二、适用场景

十三、总结：为什么 UmaDev 值得看

UmaDev 的激进之处不在于它用了什么尖端技术——BM25 + 向量检索、状态机、子进程管理，都是成熟的工程手段。它的价值在于把这些工程手段组合成了一条完整的交付流水线，并且用 Rust 的类型系统和单元测试把规范和实现锁死在了一起。

几个关键设计决策：

1. 不接模型：不是能力限制，是信任边界的设计。用户的数据、模型、认证全程在自己手里，UmaDev 连看都看不到

2. fail-open 治理：治理代码出 bug 不能挡死底座。这是一条反脆弱的底线——系统越脆弱的部分，越不能让它有否决权

3. 规范即代码：25 条 clause 编码成 Rust 数据结构，散文版和代码版由单元测试锁死。规范和实现不会各说各话——这是大多数工程团队都做不到的事

4. 经验沉淀闭环：不是简单的"记住你上次说过什么"，而是有指纹、有分类、有疗效追踪、有全局提升的完整系统。越用越懂你不是形容词，是机制

5. 覆盖率核对：需求和实现死死绑在一起。AI 想偷偷漏功能？会被标出来

UmaDev 的内核很朴素：没有自己的模型，做的是把真实软件团队的流程、规矩、记性，用代码固化下来，套在那些已经很能写代码的 AI 之上。

模型负责聪明，UmaDev 负责靠谱。一个总监不需要是全公司代码写得最好的人，他要的是流程意识、记性和较真这股劲——而这恰好是今天的 AI 最缺的。

参考链接

• UmaDev GitHub：https://github.com/umacloud/umadev
• SuperDev（前作）：https://github.com/umacloud/superdev

#UmaDev #SuperDev #AIAgent #Rust #项目总监 #治理 #质量门 #自进化 #知识检索 #MCP #开源 #小凯