MAWflow CLI

适合先在终端建立项目协作规则、运行项目检查和生成 AI 上下文的用户。独立 CLI 的日常项目命令无需登录；首次安装需要网络，验证命令调用的工具和服务仍有自身依赖。

CLI 与本地产品工作台分别安装。需要网页任务、里程碑、账号协作或 AI 作业管理时，再按 Host Base 手册安装桌面档案，并导入同一项目。

1. 安装并检查

准备 Git 2.30+ 和 Node.js 18+。安装器优先使用 Python 3.11+，缺少合格解释器时准备受校验的托管 Python，不替换系统 Python。

以下精确安装 0.4.0-rc.3，这是公开发行的预发布版本。是否采用该通道由使用者决定；稳定推荐及核验时间请查看版本与发布。已有 Host 安装时，应先确认原安装档案与运行状态。

macOS / Linux：

MAWFLOW_INSTALL_PROFILE=seed-cli npm install -g @mawflow/cli@0.4.0-rc.3 --registry=https://mawflow.com/npm/
mawflow --help
mawflow capabilities

Windows PowerShell：

$env:MAWFLOW_INSTALL_PROFILE = "seed-cli"
npm install -g @mawflow/cli@0.4.0-rc.3 --registry=https://mawflow.com/npm/
Remove-Item Env:MAWFLOW_INSTALL_PROFILE
mawflow --help
mawflow capabilities

检查点： 命令能运行，能力清单包含 project.init.current_directory 和 project.init.existing_git。独立档案不注册 Host 常驻服务。若终端找不到命令，关闭并重新打开终端，再检查 npm 全局命令目录是否在 PATH 中。

2. 新建一个项目

进入你希望保存项目的父目录：

mawflow project init my-project
cd my-project
mawflow project doctor --root .
mawflow project context --root .

默认建立空组件基线。打开生成的 AI_START_HERE.md，确认项目目标、允许路径及检查入口，再让 AI 开始一个小任务。Doctor 检查项目规则与结构；业务测试是否通过，以项目登记的验证结果为准。

3. 接入已有 Git 项目

先提交或妥善保存当前改动，进入项目根目录：

git status --short
mawflow project init --plan

阅读预览中的文件变更、保护范围、计划文件和确认码。使用预览返回的执行命令，保留原计划路径与精确确认码；不要自行猜测确认码。存量项目接入应保留业务代码、README 和现有 Git 历史；脏工作树会被拒绝。完整状态说明见项目初始化。

4. 完成第一次小闭环

1. 写明一个可验证的小任务、验收标准及允许修改范围。
2. 使用项目上下文让 AI 定位正确模块并提出实现。
3. 检查实际 diff，运行已登记的项目验证。
4. 将结果与未验证事项回写到项目文档，决定接受或返工。

完成信号： 项目规则可读、修改范围明确、检查可重复、证据可复核。安装成功或 Doctor 通过本身不代表业务结果已经验收。

更新与恢复

mawflow status
mawflow upgrade --help
mawflow project upgrade --help

运行时升级与项目模板升级分别预览，再使用返回的确认码执行。官方升级执行需要新的在线账号授权；日常检查无需登录。升级失败应保留旧运行时，项目恢复会保护并行改动。使用 mawflow upgrade --rollback 预览离线回退，使用 mawflow uninstall 预览卸载；执行仍需精确确认，卸载保留项目。

遇到“仓库身份不匹配”时，保留实际仓库和绑定，先核对 CLI/Kit 版本及仓库来源；不要删除校验规则或改用另一个仓库绕过问题。