Seed 安装

公开分发状态

Seed Contract v2.1 已发布

等待复核

公开 Git 稳定线为 v0.2.31，默认 Python Kit 为 mawflow-seed-kit 2.1.1。版本来自统一 Product Facts，不再由本页面手工维护。

公开 Git

v0.2.31

Seed Kit

2.1.1

核验状态

已过核验周期

事实来源

构建时快照

查看兼容与边界

• Python：>=3.11
• Git：>=2.30
• Seed 是开源项目协作规范，不是产品档位或在线工作台。
• 部分事实已超过核验周期，当前展示最后一次可信快照。

查看安装步骤GitHub 开源仓Gitee 开源仓

Seed 的安装不是把一个工具装进系统后就结束，而是把一个代码仓库整理成带 AI 工作目录入口、项目事实和协作协议的工作区。本页把两条入口放在一起：

你现在的状态	走哪条安装路径	结果
准备创建全新项目	全新项目路径	用 mawflow project init my-project 创建 Seed 项目目录。
已经有本地项目或 0.2.x 存量仓库	现有项目迁移路径	预览、确认并一次性迁移到 Contract v2，不覆盖源码、不保留长期双写。

只使用开源 Seed 时，不需要先登录账号，也不需要登录授权码。需要本地产品工作台、Local MCP 或 AI Credits 入口时，再继续进入 Lite 安装。

准备条件

• 本机可以使用 Git。
• 本机可以使用 Node.js / npm。
• 本机已经安装 Python 3.11 或更新版本；@mawflow/cli 会创建或复用 Host Base 专用 Python 虚拟环境。
• 如果要用 mawflow host start -d 在 macOS / Linux 后台运行 Host Base，本机需要 tmux；macOS 可先执行 brew install tmux。
• 你知道自己要创建新项目，还是改造已有项目。
• 如果是已有项目，先确认有 Git 分支、备份或其它可恢复点。
• 你知道项目大致目标、主要目录、启动命令、检查命令和不能进入 AI 上下文的敏感资料。

1. 安装 Host Base 命令

先安装 npm 全局入口。它会检查 Python 3.11+，准备 Host Base 专用虚拟环境，并从官网包源安装 mawflow-host：

npm install -g @mawflow/cli --registry=https://mawflow.com/npm/
mawflow --help

确认命令可用：

mawflow --help
mawflow host status

如果 npm 全局入口不可用，可以按 Host Base 用户手册的 Python 兜底路径，在专用虚拟环境里安装：

python -m pip install --index-url https://mawflow.com/packages/simple --extra-index-url https://pypi.org/simple mawflow-host

如果兜底安装时报 externally-managed-environment，说明你正在改全局 Python。请回到专用虚拟环境安装，不要使用 --break-system-packages。

安装包不会自动启动服务、不会注册系统服务、不会登录账号、不会写入登录授权码。只有你显式执行 mawflow project init、mawflow host start 或后续 mawflow login 时，才会进入项目初始化、启动或登录激活动作。

2. 选择安装路径

全新项目路径

在你希望放置项目的父目录执行默认初始化。Seed Contract v2.1 对应 mawflow-seed-kit 2.1.1，安装包与公开 Git v0.2.31 均已发布。初始化只接受不存在或为空的目标目录：

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

需要固定公开 Git 源时，可以显式使用 GitHub：

mawflow project init my-project \
  --source github \
  --repo mawflow/mawflow-seed \
  --ref v0.2.31

国内网络可以显式使用 Gitee：

mawflow project init my-project \
  --source gitee \
  --repo mawflow/mawflow-seed \
  --ref v0.2.31

默认命令、GitHub/Gitee v0.2.31 和项目 .maw/seed.lock 使用同一 BOM 与 contract fingerprint；不允许 package 与公开 Git 各走一套内容版本。

创建完成后，先把模板事实改成自己的项目事实：

文件	最小要求
README.md	项目是什么、怎么启动、当前状态、谁维护。
.maw/project.yaml	项目 key、名称、负责人、协作边界。
AI_START_HERE.md	AI 进入项目目录时先读的通用启动页。
.maw/agent-entry.yaml	多种本地 AI 编程工具共享的入口协议。
.maw/components.yaml	真实组件，例如 server、client 或你的实际 app_key。
.maw/modules.yaml	当前业务模块树；不确定的模块先保守记录。
.maw/app-runtime.yaml	本地启动、测试入口和必要环境引用。

初始化输出会列出实际 source、ref、项目目录、项目 key 和 Git 初始化状态。完成后运行 git status --short，并确认 .maw/project.yaml、.maw/template-source.yaml 和 AI_START_HERE.md 已存在。

不要提交 .local/ 真实内容、.maw/*.local.yaml、私钥、账号密码、生产连接串、供应商密钥或未脱敏日志。

现有项目改造路径

已有项目接入 Seed v2 时，核心原则是 一次性迁移，不整包覆盖、不长期双写。不要在已有非空项目目录里强制初始化，也不要手工复制模板覆盖真实项目。

先在原项目里确认可恢复点：

git status --short
git branch

建议为改造单独建分支：

git switch -c adopt-maw-seed

先生成迁移预览：

mawflow project adopt --root .

在本地工作台核对写入、删除、风险和精确确认串后再确认。迁移事务会保存私有备份、原子写入并回读 Project Definition；失败时恢复原文件。完成后运行 mawflow project doctor --root .，确认 editable=true。

建议先引入这些结构，再改成老项目事实：

建议引入	改造方式
.maw/project.yaml	改成老项目的项目名、项目 key 和协作边界。
AI_START_HERE.md	改成老项目自己的 AI 工作目录启动页，不照搬模板事实。
.maw/agent-entry.yaml	写老项目的工具入口、受保护路径、验证和收口契约。
.maw/components.yaml	写老项目真实组件，不使用模板默认组件覆盖。
.maw/modules.yaml	先按现有页面、API、业务域保守登记模块。
.maw/app-runtime.yaml	写真实启动、测试、构建入口。
docs/AI_CONTEXT_BRIEF.md	写 AI 进入老项目时最小该读什么、默认不读什么。
docs/modules/INDEX.md	让后续任务能按路径、页面或 API 定位模块。
docs/ai-coding/	放通用编码边界和文档同步规则。
docs/ai-instructions/	放老项目长期指令、术语和经验。

不要复制或覆盖老项目真实 README.md、业务源码、发布配置、仓库映射、客户配置、真实 secrets、.local/、本机 overlay、日志、缓存和构建产物。

3. 检查安装结果

无论是新项目还是老项目改造，完成后至少确认：

mawflow project doctor --root .
git diff --check
mawflow host status

project doctor 使用与本地工作台相同的 Seed Contract v2 编译器；只有 status=ready 且 editable=true 才表示项目可由 Seed Studio 维护。

然后运行项目自己的最小检查，例如测试、构建、格式检查、启动检查或人工验收。Seed 的价值是把这些检查写进项目事实，而不是替代项目原有验证。

4. 进入快速开始

安装完成后，再进入 Seed 快速开始。快速开始只做第一次 AI Coding 闭环：写项目事实、写第一条 Prompt Spec、交给 AI 执行会话、确认验证和收口。

如果你需要完整个人开发环境，例如本地产品工作台、本地项目上下文、Local MCP 或 AI Credits 入口，再继续阅读 Lite 安装。如果你需要跨电脑、项目空间、工作项、验收和交付证据，再阅读 Studio 安装。