SDD - Spec Driven Development 工具（命令名：mxt）

|

For Rachel Momo / Serial Experiments Lain

引导

• 文档：https://www.yuque.com/jiezizhu/r2mo
  • >> 快速开始
• 示例：https://gitee.com/zero-ws/zero-rachel-mxt

1. 介绍

1.1. 功能说明

r2mo-ai 是 SDD - Spec Driven Development 命令行工具，提供项目初始化、规范与 OpenAPI 辅助、任务提示词生成，以及 Claude Code / Codex / OpenCode 的 mxt AI 命令安装与刷新。

2. 工具使用

2.1. 安装

前置条件：Node.js 18+（推荐 LTS 版本）

macOS / Linux

npm install -g r2mo-ai
# 验证
mxt help

若遇到权限问题：

sudo npm install -g r2mo-ai
# 或使用 nvm 管理 Node 版本，避免 sudo

Windows

npm install -g r2mo-ai
# 验证
mxt help

若遇到执行策略限制（PowerShell）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
npm install -g r2mo-ai

卸载

npm uninstall -g r2mo-ai

Windows 提示：安装或卸载 mxt ai-cmd 时，请先关闭 Claude Code / Codex / OpenCode，否则文件可能被锁定导致操作失败。若仍遇到 EPERM 或 EBUSY 错误，关闭应用后重试即可。

2.2. 常用命令

🛠️ 环境初始化（工程初始化）

| 命令 | 说明 | 选项 | 示例 | |:---|:---|:---|:---| | mxt app | 创建 R2MO/Spring 或 ZERO/Vertx 应用 | -n 指定名称 | mxt app -n my-app | | mxt apply | 从远程仓库安装技能到当前项目 | -i 反馈到仓库 | mxt apply | | mxt env | 环境信息检查 | | mxt env | | mxt focus | 维护 DPA focus 配置与任务绑定 | -d 完成备份；-c 同步配置 | mxt focus | | mxt help | 显示帮助的详细信息 | | mxt help | | mxt init | 初始化 .r2mo 规范目录结构 | | mxt init | | mxt mcp | 配置 MCP Skills Server | | mxt mcp | | mxt open | 使用指定 AI 工具打开项目 | | mxt open | | mxt team | 写入 .r2mo/mxt.yaml 角色配置 | | mxt team | | mxt ui | 创建/更新 UI 子项目 | | mxt ui |

📋 需求分析

| 命令 | 说明 | 示例 | |:---|:---|:---| | mxt docs | 使用 Obsidian 打开文档目录 | mxt docs | | mxt menu | 扫描 src/pages 下 menu.yaml 打印树型菜单 | mxt menu | | mxt mod | 拉取 r2mo-spec，拷贝 OpenAPI 到 .r2mo/api/ | mxt mod | | mxt openapi | 提取子项目 OpenAPI 文档到 -ui/.r2mo/api/ | mxt openapi |

🚀 开发实施

| 命令 | 说明 | 选项 | 示例 | |:---|:---|:---|:---| | mxt admin | 根据需求文档生成前端页面结构 | | mxt admin | | mxt dict | 读取 schemas 导出字典 | -r 逆向生成 SQL | mxt dict | | mxt domain | 执行 r2mo_proto 生成 Protobuf | | mxt domain | | mxt mmr0 | 下载并生成 Flyway SQL 文件 | | mxt mmr0 | | mxt mmr2 | 下载并生成 Entity 类 | | mxt mmr2 |

🤖 SDD 开发

| 命令 | 说明 | 示例 | |:---|:---|:---| | mxt ai-cmd | 安装 AI 命令到 Claude Code / Codex / OpenCode | mxt ai-cmd | | mxt ask | 从模板选择提示词复制到剪贴板 | mxt ask | | mxt plan | 选择任务生成 Plan 提示词到剪贴板 | mxt plan | | mxt run | 选择任务生成提示词到剪贴板 | mxt run | | mxt task | 按 task/thread 配置对齐任务槽位 | mxt task |

2.3. AI 平台命令安装

mxt ai-cmd 将命令安装到 Claude Code、Codex、OpenCode 的可用位置。安装时菜单中会展示各平台的命令用法说明。命令源随 npm 包发布，位于 agent/commands/。

# 交互式选择安装平台（菜单中显示各平台用法）
mxt ai-cmd

每次安装会先清理该命令在所选平台上的旧记录，再写入最新命令并重新注册。重复执行可用于刷新索引。

闭环流程

六个命令形成一个 plan → run → end → goon 闭环，sync 和 start 为辅助命令：

flowchart TD
    A[“`task-xxx.md`”] --> B[“mxt:plan<br/>可选”]
    A --> C[“mxt:run”]
    B --> C
    C --> D[“mxt:end”]
    D --> E{“有待整改？”}
    E -- 有 --> F[“mxt:goon”]
    F --> G[“追加 Changes”]
    G --> D
    E -- 无 --> H[“Done ✅”]

    classDef requirement fill:#e8f1ff,stroke:#4a7bd1,color:#12325b
    classDef optional fill:#fff4d6,stroke:#d4a72c,color:#5b4300
    classDef execute fill:#e8f7e8,stroke:#43a047,color:#123d1b
    classDef verify fill:#f3e8ff,stroke:#8e5ad7,color:#41215f
    classDef remediate fill:#ffe8e8,stroke:#d45a5a,color:#5d1f1f
    classDef done fill:#e6fffb,stroke:#1aa39a,color:#0f4f4a

    class A requirement
    class B optional
    class C execute
    class D,E verify
    class F,G remediate
    class H done

各步骤行为：

• plan（可选）— 只写回 task-xxx.md 的 ## Plan，不执行实现
• run — 优先按已有 ## Plan 执行，无 Plan 时按任务正文执行，追加 Changes
• end — 清空 goon-xxx.md 原始内容，写入当前待整改项
• goon — 按整改项执行，闭环记录追加回 task-xxx.md 的 Changes，再执行 end 验证

当 end 验证后 goon-xxx.md 无待整改项时，该编号任务闭环完成。

goon-xxx.md 的 frontmatter title 必须与对应 task-xxx.md 标题一致，并追加 整改- 前缀。

前置校验

plan、run、end 要求对应 task-xxx.md 在 frontmatter 之后必须存在非空正文。正文为空时命令立即返回，不执行后续提示词。sync 和 start 无前置校验，直接执行。

各平台调用方式

Claude Code / OpenCode — slash command

| 命令 | 前置 | 写回 | 说明 | |:---|:---|:---|:---| | /mxt:plan 001 | 正文非空 | ## Plan | 不执行、不追加 Changes | | /mxt:run 001 | 正文非空 | Changes | 优先按 Plan 执行 | | /mxt:end 001 | 正文非空 | goon-001.md | 标题为 整改- + task 标题 | | /mxt:goon 001 | goon 存在 | Changes | 整改后再 end 验证 | | /mxt:debug | 无 | 无 | BUG 排查 | | /mxt:sync | 无 | 无 | Git 同步：提交、拉取、合并、推送 | | /mxt:start | 无 | 无 | 拉起开发环境 |

Codex — plugin skill

| 命令 | 等价 | 说明 | |:---|:---|:---| | $mxt-plan 001 | /mxt:plan | 写 Plan | | $mxt-run 001 | /mxt:run | 执行开发 | | $mxt-end 001 | /mxt:end | 验证整改 | | $mxt-goon 001 | /mxt:goon | 整改后验证 | | $mxt-debug | /mxt:debug | BUG 排查 | | $mxt-sync | /mxt:sync | Git 同步 | | $mxt-start | /mxt:start | 拉起环境 |

参数 001 为三位数字任务编号，对应 .r2mo/task/task-001.md。格式不对时命令停止并提示正确用法。

不同命令的 001 含义：

| 命令 | 001 对应文件 | |:---|:---| | plan / run / end | .r2mo/task/task-001.md | | goon | .r2mo/task/task-001.md + .r2mo/task/goon-001.md |

文件不存在时命令直接询问最新任务号。

四个命令发送给 AI Agent 的提示词统一使用”任务派发单”短列表格式，包含输入范围、前置校验、调度策略和写回规则。

卸载

mxt ai-cmd --uninstall

全量清理：已安装的平台会被删除，未安装的跳过。

平台安装细节

Claude Code

• 写入 ~/.claude/plugins/marketplaces/mxt-skills
• 写入 ~/.claude/plugins/cache/mxt-skills/mxt/1.0.0
• 更新 ~/.claude/settings.json（启用插件、注册 marketplace）
• 若 claude CLI 可用：自动执行 plugin marketplace add/update 和 plugin install
• 验证：claude plugin list 或 claude plugin details mxt@mxt-skills

Codex

• 写入 ~/.codex/plugins/mxt 及 ~/.codex/marketplaces/mxt-skills
• 写入 ~/.codex/prompts/mxt-*.md 兼容 prompts
• 更新 ~/.codex/config.toml（注册 marketplace 和 plugin）
• 若 codex CLI 可用：自动执行 plugin marketplace add 和 plugin add
• 验证：codex plugin list；codex debug prompt-input 中应出现 mxt:mxt-plan 等

OpenCode

• macOS / Linux：写入 ~/.config/opencode/opencode.json
• Windows：写入 %APPDATA%\opencode\opencode.json
• 清理旧 opencode.jsonc 中该命令残留
• 验证：检查 command[“mxt:plan”] 等是否存在

安装后请重启应用或开启新会话，让命令或 skill 索引重新加载。

2.4. 发布

可直接通过 ./publish.sh "commit message" 完成发布，脚本会依次执行：

1. npm version patch --no-git-tag-version — 自动升级补丁版本号
2. npm publish --registry=https://registry.npmjs.org/ — 发布到 npm 官方源
3. git add . && git commit -m "commit message" && git push — 提交并推送代码

执行前需确认：

• 已执行 npm login 且拥有 r2mo-ai 包的发布权限
• 当前网络可访问 registry.npmjs.org
• git remote 和目标分支正确，工作区只包含本次要发布的文件

3. 参考链接

3.1. 旧版

• （后端）Zero Ecotope：https://www.zerows.io
• （前端）Zero UI：https://www.vertxui.cn
• （工具）Zero AI：https://www.vertxai.cn
• （标准）Zero Schema：https://www.vertx-cloud.cn

3.2. 新增

• Maven 统一版本管理：https://gitee.com/silentbalanceyh/rachel-mxt
• Rapid快速开发框架：https://gitee.com/silentbalanceyh/r2mo-rapid
• Zero Epoch：https://www.zerows.io
• Zero Demo：https://gitee.com/zero-ws/zero-rachel-mxt