一款用 Go 编写的 Claude Code 智能体开发套件，通过 27 个专业化 AI Agent 和 52 项技能实现从需求规划到代码交付的自动化开发工作流。
MoAI-ADK
Claude Code 的智能体开发套件
English ·
한국어 ·
日本語 ·
中文
官方文档
MoAI-ADK 是一个为 Claude Code 打造的**高性能 AI 开发环境**。27 个专业化 AI Agent 和 52 项技能协同工作以产出高质量代码。针对新项目和功能开发，它会自动应用 TDD（默认），或针对测试覆盖率极低的现有项目应用 DDD，并支持 Sub-Agent 和 Agent Teams 双执行模式。
这是一个用 Go 编写的单一二进制文件 —— 可在任何平台上零依赖瞬间运行。
## 为什么选择 MoAI-ADK？
我们将基于 Python 的 MoAI-ADK（约 73,000 行代码）完全用 Go 语言重写。
| 方面 | Python 版本 | Go 版本 |
|--------|---------------|------------|
| 分发方式 | pip + venv + 依赖 | **单一二进制文件**，零依赖 |
| 启动时间 | ~800ms 解释器启动 | **~5ms** 原生执行 |
| 并发 | asyncio / threading | **原生 goroutines** |
| 类型安全 | 运行时（可选 mypy） | **编译时强制** |
| 跨平台 | 需要 Python 运行时 | **预构建二进制文件**（macOS, Linux, Windows） |
| Hook 执行 | Shell wrapper + Python | **编译后的二进制文件**，JSON 协议 |
### 关键数字
- **34,220 行** Go 代码，**32** 个包
- **85-100%** 测试覆盖率
- **27** 个专业化 AI Agent + **52** 项技能
- **18** 种受支持的编程语言
- **16** 个 Claude Code hook 事件
## Harness 工程架构
MoAI-ADK 实现了 **Harness Engineering** 范式 —— 即为 AI Agent 设计环境，而不是直接编写代码。
| 组件 | 描述 | 命令 |
|-----------|-------------|---------|
| **自我验证循环 (Self-Verify Loop)** | Agent 编写代码 → 测试 → 失败 → 修复 → 通过，如此自主循环 | `/moai loop` |
| **上下文映射 (Context Map)** | 代码库架构映射和文档始终对 Agent 可用 | `/moai codemaps` |
| **会话持久化 (Session Persistence)** | `progress.md` 跨会话跟踪已完成的阶段；中断的运行会自动恢复 | `/moai run SPEC-XXX` |
| **失败清单 (Failing Checklist)** | 运行开始时，所有验收标准注册为待处理任务；实现后标记为完成 | `/moai run SPEC-XXX` |
| **语言无关 (Language-Agnostic)** | 支持 16 种语言：自动检测语言，选择正确的 LSP/linter/测试/覆盖率工具 | 所有工作流 |
| **垃圾回收 (Garbage Collection)** | 定期扫描并移除死代码、AI 废弃物和未使用的导入 | `/moai clean` |
| **脚手架优先 (Scaffolding First)** | 实现前创建空文件桩以防止熵增 | `/moai run SPEC-XXX` |
## 系统要求
| 平台 | 支持的环境 | 备注 |
|----------|----------------------|-------|
| macOS | Terminal, iTerm2 | 完全支持 |
| Linux | Bash, Zsh | 完全支持 |
| Windows | **WSL（推荐）**，PowerShell 7.x+ | 不支持原生 cmd.exe |
**前置条件：**
- 所有平台都必须安装 **Git**
- **Windows 用户**：[Git for Windows](https://gitforwindows.org/) 是**必需的**（包含 Git Bash）
- 使用 **WSL**（Windows Subsystem for Linux）以获得最佳体验
- 支持 PowerShell 7.x 或更高版本作为替代方案
- 不支持旧版 Windows PowerShell 5.x 和 cmd.exe
## 快速开始
### 1. 安装
#### macOS / Linux / WSL
```
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash
```
#### Windows (PowerShell 7.x+)
```
irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex
```
#### 从源代码构建 (Go 1.26+)
```
git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build
```
### 2. Windows 特定问题
#### 韩文用户名路径错误
如果您的 Windows 用户名包含非 ASCII 字符（韩文、中文等），
由于 Windows 8.3 短文件名转换，您可能会遇到 `EINVAL` 错误。
**变通方案 1：** 设置备用临时目录：
```
# 命令提示符
set MOAI_TEMP_DIR=C:\temp
mkdir C:\temp 2>nul
# PowerShell
$env:MOAI_TEMP_DIR="C:\temp"
New-Item -ItemType Directory -Path "C:\temp" -Force
```
**变通方案 2：** 禁用 8.3 文件名生成（需要管理员权限）：
```
fsutil 8dot3name set 1
```
**变通方案 3：** 创建一个新的仅包含 ASCII 字符的 Windows 用户账户。
### 3. 初始化项目
```
moai init my-project
```
交互式向导会自动检测您的语言、框架和方法论，然后生成 Claude Code 集成文件。
### 4. 使用 Claude Code 开始开发
```
# 启动 Claude Code 后
/moai project # Generate project docs (product.md, structure.md, tech.md)
/moai plan "Add user authentication" # Create a SPEC document
/moai run SPEC-AUTH-001 # DDD/TDD implementation
/moai sync SPEC-AUTH-001 # Sync docs & create PR
```
```
graph LR
A["🔍 /moai project"] --> B["📋 /moai plan"]
B -->|"SPEC Document"| C["🔨 /moai run"]
C -->|"Implementation Complete"| D["📄 /moai sync"]
D -->|"PR Created"| E["✅ Done"]
```
## MoAI 开发方法论
MoAI-ADK 根据您的项目状态自动选择最佳开发方法论。
```
flowchart TD
A["🔍 Project Analysis"] --> B{"New Project or
10%+ Test Coverage?"}
B -->|"Yes"| C["TDD (default)"]
B -->|"No"| D{"Existing Project
< 10% Coverage?"}
D -->|"Yes"| E["DDD"]
C --> F["RED → GREEN → REFACTOR"]
E --> G["ANALYZE → PRESERVE → IMPROVE"]
style C fill:#4CAF50,color:#fff
style E fill:#2196F3,color:#fff
```
### TDD 方法论（默认）
新项目和功能开发的默认方法论。先编写测试，再进行实现。
| 阶段 | 描述 |
|-------|-------------|
| **RED** | 编写一个定义预期行为的失败测试 |
| **GREEN** | 编写最少代码使测试通过 |
| **REFACTOR** | 在保持测试通过的同时提高代码质量。`/simplify` 在 REFACTOR 完成后自动运行。 |
对于棕地项目（现有代码库），TDD 增加了一个 **pre-RED 分析步骤**：在编写测试之前阅读现有代码以理解当前行为。
### DDD 方法论（覆盖率 < 10% 的现有项目）
一种用于安全重构测试覆盖率极低的现有项目的方法论。
```
ANALYZE → Analyze existing code and dependencies, identify domain boundaries
PRESERVE → Write characterization tests, capture current behavior snapshots
IMPROVE → Improve incrementally under test protection. /simplify runs automatically after IMPROVE completes.
```
### 自动质量与扩展层
MoAI-ADK v2.6.0+ 集成了两项 MoAI **自主**调用的 Claude Code 原生技能 —— 无需标志或手动命令。
| 技能 | 角色 | 触发条件 |
|-------|------|---------|
| `/simplify` | 质量强制 | **始终**在每个 TDD REFACTOR 和 DDD IMPROVE 阶段后运行 |
| `/batch` | 扩展执行 | 当任务复杂度超过阈值时自动触发 |
**`/simplify` — 自动质量过关**
使用并行 Agent 审查已更改代码的重用机会、质量问题、效率和 CLAUDE.md 合规性，然后自动修复发现的问题。MoAI 在每个实现周期后直接调用此项 —— 无需配置。
**`/batch` — 并行扩展**
在隔离的 git worktree 中生成数十个 Agent 以进行大规模并行工作。每个 Agent 运行测试并报告结果；MoAI 负责合并它们。根据工作流自动触发：
| 工作流 | 触发条件 |
|----------|------------------|
| `run` | 任务 ≥ 5，或预计文件更改 ≥ 10，或独立任务 ≥ 3 |
| `mx` | 源文件 ≥ 50 |
| `coverage` | P1+P2 覆盖率缺口 ≥ 10 |
| `clean` | 已确认的死代码项 ≥ 20 |
## AI Agent 编排
MoAI 是一个**战略编排器**。它不直接编写代码，而是将任务委托给 27 个专业化 Agent。
```
graph LR
U["👤 User Request"] --> M["🗿 MoAI Orchestrator"]
M --> MG["📋 Manager (8)"]
M --> EX["⚡ Expert (9)"]
M --> BL["🔧 Builder (3)"]
M --> TM["👥 Team (8)"]
MG --> MG1["spec · ddd · tdd · docs
quality · project · strategy · git"]
EX --> EX1["backend · frontend · security · devops
performance · debug · testing · refactoring · chrome-ext"]
BL --> BL1["agent · skill · plugin"]
TM --> TM1["researcher · analyst · architect · designer
backend-dev · frontend-dev · tester · quality"]
style M fill:#FF6B35,color:#fff
style MG fill:#4CAF50,color:#fff
style EX fill:#2196F3,color:#fff
style BL fill:#9C27B0,color:#fff
style TM fill:#FF9800,color:#fff
```
### Agent 分类
| 类别 | 数量 | Agent | 角色 |
|----------|-------|--------|------|
| **Manager** | 8 | spec, ddd, tdd, docs, quality, project, strategy, git | 工作流协调、SPEC 创建、质量管理 |
| **Expert** | 8 | backend, frontend, security, devops, performance, debug, testing, refactoring | 领域特定实现、分析、优化 |
| **Builder** | 3 | agent, skill, plugin | 创建新的 MoAI 组件 |
| **Team** | 8 | researcher, analyst, architect, designer, backend-dev, frontend-dev, tester, quality | 并行团队开发 |
### 52 项技能（渐进式披露）
通过 3 级渐进式披露系统管理以提高 Token 效率：
| 类别 | 数量 | 示例 |
|----------|-------|----------|
| **Foundation** | 5 | core, claude, philosopher, quality, context |
| **Workflow** | 11 | spec, project, ddd, tdd, testing, worktree, thinking... |
| **Domain** | 5 | backend, frontend, database, uiux, data-formats |
| **Language** | 18 | Go, Python, TypeScript, Rust, Java, Kotlin, Swift, C++... |
| **Platform** | 9 | Vercel, Supabase, Firebase, Auth0, Clerk, Railway... |
| **Library** | 3 | shadcn, nextra, mermaid |
| **Tool** | 2 | ast-grep, svg |
| **Specialist** | 10 | Figma, Flutter, Electron, Pencil... |
## 模型策略（Token 优化）
MoAI-ADK 根据您的 Claude Code 订阅计划为 27 个 Agent 中的每一个分配最佳 AI 模型。这可以在您计划的速率限制内最大化质量。
| 策略 | 计划 | 🟣 Opus | 🔵 Sonnet | 🟡 Haiku | 最适合 |
|--------|------|------|--------|-------|----------|
| **High** | Max $200/月 | 22 | 1 | 4 | 最高质量，最高吞吐量 |
| **Medium** | Max $100/月 | 4 | 18 | 5 | 平衡质量与成本 |
| **Low** | Plus $20/月 | 0 | 11 | 16 | 经济实惠，无 Opus 访问权限 |
### 按层级的 Agent 模型分配
#### Manager Agent
| Agent | High | Medium | Low |
|-------|------|--------|-----|
| manager-spec | 🟣 opus | 🟣 opus | 🔵 sonnet |
| manager-strategy | 🟣 opus | 🟣 opus | 🔵 sonnet |
| manager-ddd | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| manager-tdd | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| manager-project | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| manager-docs | 🔵 sonnet | 🟡 haiku | 🟡 haiku |
| manager-quality | 🟡 haiku | 🟡 haiku | 🟡 haiku |
| manager-git | 🟡 haiku | 🟡 haiku | 🟡 haiku |
#### Expert Agent
| Agent | High | Medium | Low |
|-------|------|--------|-----|
| expert-backend | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| expert-frontend | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| expert-security | 🟣 opus | 🟣 opus | 🔵 sonnet |
| expert-debug | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| expert-refactoring | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| expert-devops | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| expert-performance | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| expert-testing | 🟣 opus | 🔵 sonnet | 🟡 haiku |
#### Builder Agent
| Agent | High | Medium | Low |
|-------|------|--------|-----|
| builder-agent | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| builder-skill | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| builder-plugin | 🟣 opus | 🔵 sonnet | 🟡 haiku |
#### Team Agent
| Agent | High | Medium | Low |
|-------|------|--------|-----|
| team-architect | 🟣 opus | 🟣 opus | 🔵 sonnet |
| team-analyst | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| team-designer | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| team-backend-dev | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| team-frontend-dev | 🟣 opus | 🔵 sonnet | 🔵 sonnet |
| team-tester | 🟣 opus | 🔵 sonnet | 🟡 haiku |
| team-researcher | 🟡 haiku | 🟡 haiku | 🟡 haiku |
| team-quality | 🟡 haiku | 🟡 haiku | 🟡iku |
### 配置
```
# 在项目初始化期间
moai init my-project # Interactive wizard includes model policy selection
# 重新配置现有项目
moai update # Interactive prompts for each configuration step
```
在 `moai update` 期间，系统会询问您：
- **重置模型策略？** (y/n) - 重新运行模型策略配置向导
- **更新 GLM 设置？** (y/n) - 在 settings.local.json 中配置 GLM 环境变量
## 双执行模式
MoAI-ADK 提供了 Claude Code 支持的 **Sub-Agent** 和 **Agent Teams** 两种执行模式。
```
graph TD
A["🗿 MoAI Orchestrator"] --> B{"Select Execution Mode"}
B -->|"--solo"| C["Sub-Agent Mode"]
B -->|"--team"| D["Agent Teams Mode"]
B -->|"Default (Auto)"| E["Auto Selection"]
C --> F["Sequential Expert Delegation
Task() → Expert Agent"]
D --> G["Parallel Team Collaboration
TeamCreate → SendMessage"]
E -->|"High Complexity"| D
E -->|"Low Complexity"| C
style C fill:#2196F3,color:#fff
style D fill:#FF9800,color:#fff
style E fill:#4CAF50,color:#fff
```
### Agent Teams 模式（默认）
MoAI-ADK 自动分析项目复杂度并选择最佳执行模式：
| 条件 | 选定模式 | 原因 |
|-----------|---------------|--------|
| 3+ 个领域 | Agent Teams | 多领域协调 |
| 10+ 个受影响文件 | Agent Teams | 大规模更改 |
| 复杂度评分 7+ | Agent Teams | 高复杂度 |
| 其他情况 | Sub-Agent | 简单、可预测的工作流 |
**Agent Teams 模式**使用并行团队开发：
- 多个 Agent 同时工作，通过共享任务列表进行协作
- 通过 `TeamCreate`、`SendMessage` 和 `TaskList` 进行实时协调
- 最适合大规模功能开发和多领域任务
```
/moai plan "large feature" # Auto: researcher + analyst + architect in parallel
/moai run SPEC-XXX # Auto: backend-dev + frontend-dev + tester in parallel
/moai run SPEC-XXX --team # Force Agent Teams mode
```
**Agent Teams 的质量 Hooks：**
- **TeammateIdle Hook**：在队友变为空闲之前验证 LSP 质量门禁（错误、类型错误、lint 错误）
- **TaskCompleted Hook**：当任务引用 SPEC-XXX 模式时验证 SPEC 文档是否存在
- 所有验证都使用优雅降级 —— 记录警告但工作继续
### Sub-Agent 模式（`--solo`）
一种使用 Claude Code 的 `Task()` API 的顺序 Agent 委托方法。
- 将任务委托给单个专业化 Agent 并接收结果
- 逐步进行：Manager → Expert → Quality
- 最适合简单和可预测的工作流
```
/moai run SPEC-AUTH-001 --solo # Force Sub-Agent mode
```
## MoAI 工作流
### Plan → Run → Sync 管道
MoAI 的核心工作流包含三个阶段：
```
graph TB
subgraph Plan ["📋 Plan Phase"]
P1["Explore Codebase"] --> P2["Analyze Requirements"]
P2 --> P3["Generate SPEC Document (EARS Format)"]
end
subgraph Run ["🔨 Run Phase"]
R1["Analyze SPEC & Create Execution Plan"] --> R2["DDD/TDD Implementation"]
R2 --> R3["TRUST 5 Quality Validation"]
end
subgraph Sync ["📄 Sync Phase"]
S1["Generate Documentation"] --> S2["Update README/CHANGELOG"]
S2 --> S3["Create Pull Request"]
end
Plan --> Run
Run --> Sync
style Plan fill:#E3F2FD,stroke:#1565C0
style Run fill:#E8F5E9,stroke:#2E7D32
style Sync fill:#FFF3E0,stroke:#E65100
```
#### 执行模式选择门禁
当从 Plan 阶段过渡到 Run 阶段时，MoAI 会自动检测当前执行环境并呈现选择界面，供用户在实现开始前确认或更改模式。
```
graph LR
A["Plan Complete"] --> B["Detect Environment"]
B --> C{"Mode Selection UI"}
C -->|"CC"| D["Claude-only Execution"]
C -->|"GLM"| E["GLM-only Execution"]
C -->|"CG"| F["Claude Leader + GLM Workers"]
```
此门禁确保无论环境状态如何都使用正确的执行模式，防止实现过程中的模式不匹配。
### /moai 子命令
所有子命令都在 Claude Code 中以 `/moai
` 形式调用。
#### 核心工作流
| 子命令 | 别名 | 用途 | 关键标志 |
|------------|---------|---------|-----------|
| `plan` | `spec` | 创建 SPEC 文档（EARS 格式） | `--worktree`, `--branch`, `--resume SPEC-XXX`, `--team` |
| `run` | `impl` | SPEC 的 DDD/TDD 实现 | `--resume SPEC-XXX`, `--team` |
| `sync` | `docs`, `pr` | 同步文档、代码映射并创建 PR | `--merge`, `--skip-mx` |
#### 质量与测试
| 子命令 | 别名 | 用途 | 关键标志 |
|------------|---------|---------|-----------|
| `fix` | — | 自动修复 LSP 错误、lint 错误、类型错误（单次运行） | `--dry`, `--seq`, `--level N`, `--resume`, `--team` |
| `loop` | — | 迭代自动修复直到完成（最多 100 次迭代） | `--max N`, `--auto-fix`, `--seq` |
| `review` | `code-review` | 代码审查，包含安全和 @MX 标签合规性检查 | `--staged`, `--branch`, `--security` |
| `coverage` | `test-coverage` | 测试覆盖率分析和缺口填补（16 种语言） | `--target N`, `--file PATH`, `--report` |
| `e2e` | — | E2E 测试（Claude-in-Chrome, Playwright CLI, 或 Agent Browser） | `--record`, `--url URL`, `--journey NAME` |
| `clean` | `refactor-clean` | 死代码识别和安全移除 | `--dry`, `--safe-only`, `--file PATH` |
#### 文档与代码库
| 子命令 | 别名 | 用途 | 关键标志 |
|------------|---------|---------|-----------|
| `project` | `init` | 生成项目文档（product.md, structure.md, tech.md, .moai/project/codemaps/） | — |
| `mx` | — | 扫描代码库并添加 @MX 代码级注释 | `--all`, `--dry`, `--priority P1-P4`, `--force`, `--team` |
| `codemaps` | `update-codemaps` | 在 `.moai/project/codemaps/` 中生成架构文档 | `--force`, `--area AREA` |
| `feedback` | `fb`, `bug`, `issue` | 收集用户反馈并创建 GitHub issues | — |
#### 默认工作流
| 子命令 | 用途 | 关键标志 |
|------------|---------|-----------|
| *(无)* | 完全自主的 plan → run → sync 管道。当复杂度评分 >= 5 时自动生成 SPEC。 | `--loop`, `--max N`, `--branch`, `--pr`, `--resume SPEC-XXX`, `--team`, `--solo` |
### 执行模式标志
控制在工作流执行期间如何调度 Agent：
| 标志 | 模式 | 描述 |
|------|------|-------------|
| `--team` | Agent Teams | 并行团队执行。多个 Agent 同时工作。 |
| `--solo` | Sub-Agent | 每阶段顺序单 Agent 委托。 |
| *(默认)* | Auto | 系统根据复杂度自动选择（领域 >= 3，文件 >= 10，或评分 >= 7）。 |
**`--team` 支持三种执行环境：**
| 环境 | 命令 | Leader | Workers | 最适合 |
|-------------|---------|--------|---------|----------|
| Claude-only | `moai cc` | Claude | Claude | 最高质量 |
| GLM-only | `moai glm` | GLM | GLM | 最大成本节省 |
| CG (Claude+GLM) | `moai cg` | Claude | GLM | 质量 + 成本平衡 |
### 自主开发循环（Ralph 引擎）
一个结合了 LSP 诊断和 AST-grep 的自主错误修复引擎：
```
/moai fix # Single pass: scan → classify → fix → verify
/moai loop # Iterative fix: repeats until completion marker detected (max 100 iterations)
```
**Ralph 引擎工作原理：**
1. **并行扫描**：同时运行 LSP 诊断 + AST-grep + linter
2. **自动分类**：将错误从 Level 1（自动修复）分类到 Level 4（用户干预）
3. **收敛检测**：当相同错误重复出现时应用替代策略
4. **完成标准**：0 错误，0 类型错误，85%+ 覆盖率
### 推荐的工作流链
**新功能开发：**
```
/moai plan → /moai run SPEC-XXX → /moai review → /moai coverage → /moai sync SPEC-XXX
```
**Bug 修复：**
```
/moai fix (or /moai loop) → /moai review → /moai sync
```
**重构：**
```
/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai coverage → /moai codemaps
```
**文档更新：**
```
/moai codemaps → /moai sync
```
## TRUST 5 质量框架
每项代码更改都根据五项质量标准进行验证：
| 标准 | 含义 | 验证 |
|-----------|---------|------------|
| **T**ested | 已测试 | 85%+ 覆盖率，特征测试，单元测试通过 |
| **R**eadable | 可读 | 清晰的命名约定，一致的代码风格，0 lint 错误 |
| **U**nified | 统一 | 一致的格式化，导入排序，遵循项目结构 |
| **S**ecured | 安全 | OWASP 合规，输入验证，0 安全警告 |
| **T**rackable | 可追踪 | 约定式提交，问题引用，结构化日志 |
## 任务指标日志
MoAI-ADK 在开发会话期间自动捕获 Task 工具指标：
- **位置**：`.moai/logs/task-metrics.jsonl`
- **捕获的指标**：Token 使用量，工具调用，持续时间，Agent 类型
- **用途**：会话分析，性能优化，成本跟踪
指标由 PostToolUse hook 在 Task 工具完成时记录。使用此数据分析 Agent 效率并优化 Token 消耗。
## CLI 命令
| 命令 | 描述 |
|---------|-------------|
| `moai init` | 交互式项目设置（自动检测语言/框架/方法论） |
| `moai doctor` | 系统健康诊断和环境验证 |
| `moai status` | 项目状态摘要，包括 Git 分支、质量指标等 |
| `moai update` | 更新到最新版本（支持自动回滚） |
| `moai update --check` | 检查更新但不安装 |
| `moai update --project` | 仅同步项目模板 |
| `moai worktree new ` | 创建新的 Git worktree（并行分支开发） |
| `moai worktree list` | 列出活动的 worktree |
| `moai worktree switch ` | 切换到某个 worktree |
| `moai worktree sync` | 与上游同步 |
| `moai worktree remove ` | 移除某个 worktree |
| `moai worktree clean` | 清理过期的 worktree |
| `moai worktree go ` | 在当前 shell 中导航到 worktree 目录 |
| `moai hook ` | Claude Code hook 调度器 |
| `moai glm` | 使用 GLM 5 API 启动 Claude Code（经济高效的替代方案） |
| `moai cc` | 不带 GLM 设置启动 Claude Code（纯 Claude 模式） |
| `moai cg` | 启用 CG 模式 —— Claude Leader + GLM Worker（tmux 窗格级隔离） |
| `moai version` | 显示版本、commit hash 和构建日期 |
## 架构
```
moai-adk/
├── cmd/moai/ # Application entry point
├── internal/ # Core private packages
│ ├── astgrep/ # AST-grep integration for structural code analysis
│ ├── cli/ # Cobra CLI command definitions
│ ├── config/ # Thread-safe YAML configuration management
│ ├── core/
│ │ ├── git/ # Git operations (branches, worktrees, conflict detection)
│ │ ├── project/ # Project initialization, language/framework detection
│ │ └── quality/ # TRUST 5 quality gates, parallel validators
│ ├── defs/ # Language definitions and framework detection
│ ├── git/ # Git convention validation engine
│ ├── hook/ # Compiled hook system (16 events, JSON protocol)
│ ├── loop/ # Ralph feedback loop (state machine, convergence detection)
│ ├── lsp/ # LSP client (16+ languages, parallel server management)
│ ├── manifest/ # File provenance tracking (SHA-256 integrity)
│ ├── merge/ # 3-way merge engine (6 strategies)
│ ├── rank/ # MoAI Rank sync and transcript management
│ ├── resilience/ # Retry policies and circuit breakers
│ ├── shell/ # Shell integration (worktree navigation)
│ ├── statusline/ # Claude Code status line integration
│ ├── template/ # Template deployment (go:embed), settings generation
│ ├── ui/ # Interactive TUI (selectors, checkboxes, wizards)
│ └── update/ # Binary self-update mechanism
├── pkg/ # Public library packages
│ ├── models/ # Shared data models
│ └── version/ # Build version metadata
└── Makefile # Build automation
```
### 关键包覆盖率
| 包 | 用途 | 覆盖率 |
|---------|---------|----------|
| `foundation` | EARS 模式，TRUST 5，18 种语言定义 | 98.4% |
| `core/quality` | 并行验证器，阶段门禁 | 96.8% |
| `ui` | 交互式 TUI 组件 | 96.8% |
| `config` | 线程安全的 YAML 配置 | 94.1% |
| `loop` | Ralph 反馈循环，收敛检测 | 92.7% |
| `cli` | Cobra 命令 | 92.0% |
| `ralph` | 收敛决策引擎 | 100% |
| `statusline` | Claude Code 状态栏 | 100% |
## 赞助商
### z.ai GLM 5
MoAI-ADK 与 **z.ai GLM 5** 合作，提供经济高效的 AI 开发环境。
| 优势 | 描述 |
|---------|-------------|
| 节省 70% 成本 | 相当的性能，价格仅为 Claude 的 1/7 |
| 完全兼容 | 无需修改代码即可与 Claude Code 配合使用 |
| 无限使用 | 无每日/每周 Token 限制 |
**[注册 GLM 5（额外 10% 折扣）](https://z.ai/subscribe?ic=1NDV03BGWU)** -- 推荐奖励用于资助 MoAI 开源开发。
### CG 模式（Claude + GLM 混合）
CG 模式是一种混合模式，Leader 使用 **Claude API** 而 Workers 使用 **GLM API**。它通过 tmux 会话级环境变量隔离实现。
#### 工作原理
```
moai cg execution
│
├── 1. Inject GLM config into tmux session env
│ (ANTHROPIC_AUTH_TOKEN, BASE_URL, MODEL_* vars)
│
├── 2. Remove GLM env from settings.local.json
│ → Leader pane uses Claude API
│
└── 3. Set CLAUDE_CODE_TEAMMATE_DISPLAY=tmux
→ Workers inherit GLM env in new panes
┌─────────────────────────────────────────────────────────────┐
│ LEADER (current tmux pane, Claude API) │
│ - Orchestrates workflow when /moai --team runs │
│ - Handles plan, quality, sync phases │
│ - No GLM env → uses Claude API │
└──────────────────────┬──────────────────────────────────────┘
│ Agent Teams (new tmux panes)
▼
┌─────────────────────────────────────────────────────────────┐
│ TEAMMATES (new tmux panes, GLM API) │
│ - Inherit tmux session env → use GLM API │
│ - Execute implementation tasks in run phase │
│ - Communicate with leader via SendMessage │
└─────────────────────────────────────────────────────────────┘
```
#### 用法
```
# 1. 保存 GLM API key (仅需一次)
moai glm sk-your-glm-api-key
# 2. 验证 tmux 环境 (如已在 tmux 中则跳过)
# 如果您需要新的 tmux 会话：
tmux new -s moai
# 提示：将 VS Code 终端默认设置为 tmux 以获得自动 tmux 环境。
# 这允许您完全跳过此步骤。
# 3. 启用 CG mode
moai cg
# 4. 在同一窗格中启动 Claude Code (关键！)
claude
# 5. 运行团队工作流
/moai --team "your task description"
```
#### 重要说明
| 项目 | 描述 |
|------|-------------|
| **tmux 环境** | 如果已经在使用 tmux，则无需创建新会话。为方便起见，将 VS Code 终端默认设置为 tmux。 |
| **Leader 启动位置** | 必须在运行 `moai cg` 的**同一窗格**中启动 Claude Code。在新窗格中启动将继承 GLM 环境。 |
| **会话结束** | session_end hook 自动清除 tmux 会话环境 → 下一个会话使用 Claude |
| **Agent Teams 通信** | SendMessage 工具支持 Leader↔Workers 通信 |
#### 模式比较
| 命令 | Leader | Workers | 需要 tmux | 成本节省 | 使用场景 |
|---------|--------|---------|---------------|--------------|----------|
| `moai cc` | Claude | Claude | 否 | - | 复杂工作，最高质量 |
| `moai glm` | GLM | GLM | 推荐 | ~70% | 成本优化 |
| `moai cg` | Claude | GLM | **必需** | **~60%** | 质量 + 成本平衡 |
#### 显示模式
Agent Teams 支持两种显示模式：
| 模式 |描述 | 通信 | Leader/Worker 分离 |
|------|-------------|---------------|--------------------------|
| `in-process` | 默认模式，所有终端 | ✅ SendMessage | ❌ 相同环境 |
| `tmux` | 分屏显示 | ✅ SendMessage | ✅ 会话环境隔离 |
**CG 模式仅在 `tmux` 显示模式下支持 Leader/Worker API 分离。**
## @MX 标签系统
MoAI-ADK 使用 **@MX 代码级注释系统** 在 AI Agent 之间传达上下文、不变量和危险区域。
### 什么是 @MX 标签？
@MX 标签是内联代码注释，可帮助 AI Agent 更快、更准确地理解您的代码库。
```
// @MX:ANCHOR: [AUTO] Hook registry dispatch - 5+ callers
// @MX:REASON: [AUTO] Central entry point for all hook events, changes have wide impact
func DispatchHook(event string, data []byte) error {
// ...
}
// @MX:WARN: [AUTO] Goroutine executes without context.Context
// @MX:REASON: [AUTO] Cannot cancel goroutine, potential resource leak
func processAsync() {
go func() {
// ...
}()
}
```
### 标签类型
| 标签类型 | 用途 | 描述 |
|----------|---------|---------|
| `@MX:ANCHOR` | 重要契约 | fan_in >= 3 的函数，更改影响广泛 |
| `@MX:WARN` | 危险区域 | Goroutine，复杂度 >= 15，全局状态变更 |
| `@MX:NOTE` | 上下文 | 魔法常量，缺少 godoc，业务规则 |
| `@MX:TODO` | 未完成工作 | 缺少测试，未实现的功能 |
### 为什么不是每段代码都有 @MX 标签？
@MX 标签系统**并非旨在为所有代码添加标签。** 核心原则是**“只标记 AI 需要首先注意到的最危险/最重要的代码。”**
| 优先级 | 条件 | 标签类型 |
|----------|-----------|----------|
| **P1 (Critical)** | fan_in >= 3 | `@MX:ANCHOR` |
| **P2 (Danger)** | goroutine，复杂度 >= 15 | `@MX:WARN` |
| **P3 (Context)** | 魔法常量，无 godoc | `@MX:NOTE` |
| **P4 (Missing)** | 无测试文件 | `@MX:TODO` |
**大多数代码不符合任何标准，因此没有标签。** 这是**正常的**。
### 示例：标签决策
```
// ❌ No tag (fan_in = 1, low complexity)
func calculateTotal(items []Item) int {
total := 0
for _, item := range items {
total += item.Price
}
return total
}
// ✅ @MX:ANCHOR added (fan_in = 5)
// @MX:ANCHOR: [AUTO] Config manager load - 5+ callers
// @MX:REASON: [AUTO] Entry point for all CLI commands
func LoadConfig() (*Config, error) {
// ...
}
```
### 配置（`.moai/config/sections/mx.yaml`）
```
thresholds:
fan_in_anchor: 3 # < 3 callers = no ANCHOR
complexity_warn: 15 # < 15 complexity = no WARN
branch_warn: 8 # < 8 branches = no WARN
limits:
anchor_per_file: 3 # Max 3 ANCHOR tags per file
warn_per_file: 5 # Max 5 WARN tags per file
exclude:
- "**/*_generated.go" # Exclude generated files
- "**/vendor/**" # Exclude external libraries
- "**/mock_*.go" # Exclude mock files
```
### 运行 MX 标签扫描
```
# 扫描整个代码库 (Go 项目)
/moai mx --all
# 仅预览 (不修改文件)
/moai mx --dry
# 按优先级扫描 (仅 P1)
/moai mx --priority P1
# 仅扫描特定语言
/moai mx --all --lang go,python
```
### 为什么其他项目也很少有 MX 标签
| 情况 | 原因 |
|-----------|--------|
| **新项目** | 大多数函数的 fan_in = 0 → 无标签（正常） |
| **小项目** | 函数少 = 调用图简单 = 标签更少 |
| **高质量代码** | 复杂度低，无 goroutine → 无 WARN 标签 |
| **高阈值** | `fan_in_anchor: 5` = 标签更少 |
### 核心原则
@MX 标签系统优化**“信噪比”**：
- ✅ **只标记真正重要的代码** → AI 快速识别核心区域
- ❌ **标记所有代码** → 增加噪音，使重要标签更难被发现
## 常见问题
### Q: 为什么不是每段 Go 代码都有 @MX 标签？
**A: 这是正常的。** @MX 标签仅在“需要的地方”添加。大多数代码足够简单和安全，不需要标签。
| 问题 | 回答 |
|----------|--------|
| 没有标签是问题吗？ | **不是。** 大多数代码不需要标签。 |
| 何时添加标签？ | 仅在**高 fan_in**、**复杂逻辑**、**危险模式**时 |
| 所有项目都类似吗？ | **是的。** 每个项目中的大多数代码都没有标签。 |
有关详细信息，请参阅上方的**“@MX 标签系统”**部分。
### Q: 如何自定义显示哪些状态栏片段？
状态栏支持 4 种显示预设以及自定义配置：
- **Full**（默认）：显示所有 8 个片段
- **Compact**：仅显示 Model + Context + Git Status + Branch
- **Minimal**：仅显示 Model + Context
- **Custom**：选择个别片段
在 `moai init` / `moai update` 向导期间配置（对重置状态栏回答“y”），或编辑 `.moai/config/sections/statusline.yaml`：
```
statusline:
preset: compact # or full, minimal, custom
segments:
model: true
context: true
output_style: false
directory: false
git_status: true
claude_version: false
moai_version: false
git_branch: true
```
有关详细信息，请参阅 [SPEC-STATUSLINE-001](.moai/specs/SPEC-STATUSLINE-001/spec.md)。
### Q: 状态栏中的版本指示器意味着什么？
MoAI 状态栏显示带有更新通知的版本信息：
```
🗿 v2.2.2 ⬆️ v2.2.5
```
- **`v2.2.2`**：当前安装的版本
- **`⬆️ v2.2.5`**：有新版本可供更新
当您使用的是最新版本时，仅显示版本号：
```
🗿 v2.2.5
```
**要更新**：运行 `moai update`，更新通知将消失。
**注意**：这与 Claude Code 的内置版本指示器（`🔅 v2.1.38`）不同。MoAI 指示器跟踪 MoAI-ADK 版本，而 Claude Code 单独显示其自己的版本。
### Q: 出现“Allow external CLAUDE.md file imports?”警告
打开项目时，Claude Code 可能会显示有关外部文件导入的安全提示：
```
External imports:
/Users//.moai/config/sections/quality.yaml
/Users//.moai/config/sections/user.yaml
/Users//.moai/config/sections/language.yaml
```
**建议操作**：选择 **“No, disable external imports”** ✅
**为什么？**
- 您项目的 `.moai/config/sections/` 已包含这些文件
- 项目特定设置优先于全局设置
- 基本配置已嵌入 CLAUDE.md 文本中
- 禁用外部导入更安全且不影响功能
**这些文件是什么？**
- `quality.yaml`：TRUST 5 框架和开发方法论设置
- `language.yaml`：语言偏好（对话、注释、提交）
- `user.yaml`：用户名（可选，用于 Co-Authored-By 署名）
## MoAI Memory
MoAI-ADK 具有一个**基于 Git 的上下文记忆系统**，它使用结构化的 git commit 消息跨会话保留 AI 与开发者的交互上下文。
### 工作原理
```
Session 1 (Plan) Session 2 (Run) Session 3 (Sync)
│ │ │
▼ ▼ ▼
Decisions ──→ git commit ──→ Context ──→ git commit ──→ Context
Constraints with ## Context loaded with ## Context loaded
Patterns section from git section from git
```
每次实现提交都包含一个结构化的 `## Context` 部分，其中捕获了：
| 类别 | 用途 | 示例 |
|----------|---------|---------|
| **Decision** | 技术选择 + 理由 | “EdDSA over RSA256（性能优先）” |
| **Constraint** | 活动约束 | “必须保持 /api/v1 兼容性” |
| **Gotcha** | 发现的陷阱 | “Redis TTL 用于 Token 存储不可靠” |
| **Pattern** | 使用的参考实现 | “auth.go:45 中的中间件链” |
| **Risk** | 已知风险/延期项 | “速率限制延期至第 2 阶段” |
| **UserPref** | 开发者偏好 | “偏好函数式风格” |
### 上下文检索
```
# 查看特定 SPEC 的上下文
/moai context --spec SPEC-AUTH-001
# 将先前的上下文注入当前会话
/moai context --spec SPEC-AUTH-001 --inject
# 按类别筛选
/moai context --category Decision --days 7
```
### Commit 格式
DDD 和 TDD 工作流都会产生结构化提交：
**DDD 模式：**
```
🔴 ANALYZE: Document JWT validation behavior
SPEC: SPEC-AUTH-001
Phase: RUN-ANALYZE
## Context (AI-Developer Memory)
- Decision: Use EdDSA for JWT signing (performance priority)
- Constraint: Must support existing RSA tokens during migration
```
**TDD 模式：**
```
🔴 RED: Add failing test for token expiry validation
SPEC: SPEC-AUTH-001
Phase: RUN-RED
## Context (AI-Developer Memory)
- Decision: 15-minute access token TTL (security best practice)
- Gotcha: Clock skew between services requires 30s grace period
```
### 关键优势
- **零依赖**：使用 git 本身作为记忆存储 —— 无需外部数据库
- **团队共享**：上下文随 `git clone` 传播 —— 自动进行团队知识转移
- **完整审计跟踪**：`git log` 提供完整的决策历史
- **会话连续性**：在 `/clear` 或会话中断后带着完整上下文恢复工作
## 贡献
欢迎贡献！有关详细的指导原则，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
### 快速开始
1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/my-feature`
3. 编写测试（新代码用 TDD，现有代码用特征测试）
4. 确保所有测试通过：`make test`
5. 确保 lint 通过：`make lint`
6. 格式化代码：`make fmt`
7. 使用约定式提交消息进行提交
8. 打开 pull request
**代码质量要求**：85%+ 覆盖率 · 0 lint 错误 · 0 类型错误 · 约定式提交
### 社区
- [Issues](https://github.com/modu-ai/moai-adk/issues) -- Bug 报告，功能请求
## Star 历史
[](https://www.star-history.com/#modu-ai/moai-adk&type=date&legend=top-left)
## 许可证
[Copyleft 3.0](./LICENSE) -- 详见 LICENSE 文件。
## 链接
- [官方文档](https://adk.mo.ai.kr)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)