Seed 安装

公开分发状态

Seed 2.8.2 已发布

核验有效

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

公开 Git

v2.8.2

Seed Kit

2.8.2

核验状态

已核验

事实来源

构建时快照

查看兼容与边界

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

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

Seed 安装就是把代码仓库整理成带 AI 工作目录入口、项目事实和协作协议的工作区。新项目和存量项目现在使用同一个入口：进入项目根目录，执行 mawflow project init。

你现在的状态	最短路径	结果
新建空目录	mawflow project init .	自动初始化 Git，以 blank profile 写入空组件 Seed。
目录仅含 .git	mawflow project init .	保留 Git，以 blank profile 写入空组件 Seed。
已有干净 Git 仓库	mawflow project init .	以 blank profile 预览、确认并增量 Seed 化。

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

准备条件

• 本机可以使用 Git 和 Node.js / npm。
• 项目目录为空，或已经是有效 Git 仓库。
• 存量 Git 仓库的工作树干净，并有可恢复提交。
• 已有内容但不是 Git 仓库时，先建立 Git 基线；CLI 会拒绝直接写入。
• 真实密钥、生产连接串、客户资料和未脱敏日志不进入 Seed 文件。

@mawflow/cli 会优先使用满足 Python 3.11+ 且可导入 sqlite3、ssl、venv 的解释器；如果本机没有完整可用的 Python，会准备受固定版本和 SHA 校验保护的托管 Python。Host Base 自 0.2.3 起不依赖 tmux。

1. 安装 CLI

当前稳定基线：

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

能力输出至少应包含 project.init.current_directory、project.init.existing_git、project.init.idempotent、project.adopt.alias 和 component.lifecycle。

默认桌面安装会准备 mawflow-host 0.2.8，并注册、启动只监听 loopback 的用户级连接 Agent。它不会登录账号、启动项目执行运行时、修改项目或上传源码。无头服务器只需 CLI/Python 运行时时，可使用：

MAWFLOW_INSTALL_PROFILE=workspace-server \
  npm install -g @mawflow/cli@0.3.15 --registry=https://mawflow.com/npm/

Python 兜底安装见 Host Base 用户手册。不要把包安装到受操作系统管理的全局 Python，也不要使用 --break-system-packages。

2. 新项目 Seed 化

推荐先创建目录，再在目录内初始化：

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

父目录兼容形式仍然可用：

mawflow project init my-project
cd my-project

默认命令使用官网 package 发布线 mawflow-seed-kit 2.8.2。需要固定公开 Git 来源时，只对新的命名目标使用：

mawflow project init my-project --source github --repo mawflow/mawflow-seed --ref v2.8.2 --profile blank

国内网络可把 github 改为 gitee。GitHub/Gitee 的 v2.8.2 与 package 2.8.2、Seed Contract 2 属于同一版本族；不同分发制品保持各自哈希，版本、BOM 与 Contract 指纹一致。

成功后可看到这些基础结构：

.maw/*.yaml
.gitignore
AI_START_HERE.md
README.md
docs/handbooks/**

默认 blank profile 不声明组件、应用、端口或技术栈，也不会生成 prompts/、ops/、docs/modules/ 或业务源码。请通过 mawflow component init/adopt 按项目事实建设组件。

3. 存量 Git 仓库 Seed 化

不要手工复制模板覆盖真实项目。先确认仓库和工作树：

git status --short
git branch --show-current
mawflow project init

已有仓库默认使用 blank profile。命令先生成写入计划和精确确认串；交互式终端可在同一次调用中确认，非交互环境按 JSON 返回的 next_command 审阅后执行。兼容别名 mawflow project adopt --root . 仍可用，但新流程统一写 mawflow project init .。

迁移会逐文件校验哈希、创建 owner-only 私有备份、原子写入并运行完整 Doctor；任一步失败都会回滚。它不会覆盖业务 README.md、源码、发布配置、仓库映射、真实密钥或 .local/。

当前会增量加入：

.maw/*.yaml
.gitignore
AI_START_HERE.md
docs/handbooks/**

不会自动生成模块档案、任务提示词、运维脚本或业务代码。初始化完成后，再根据真实仓库补齐 .maw/components.yaml、.maw/modules.yaml、.maw/app-runtime.yaml，以及项目确实需要的 docs/modules/、prompts/ 或 ops/。

已有仓库不接受 --source、--template-version、--repo、--ref 或 --path 覆盖参数，以免把模板整包覆盖到业务项目。

4. 检查结果

无论新项目还是存量仓库，都至少执行：

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

project doctor 返回 status=ready 且 editable=true，表示 Seed Contract v2 可由 Seed Studio 维护。随后运行项目自己的最小测试、构建、格式检查或启动检查。

已 Seed 化项目再次执行 mawflow project init 不会重复写入，而是幂等回读 Doctor。需要升级现有 Seed 时使用 mawflow project upgrade。

5. 按真实项目补齐事实

文件	最小要求
README.md	项目是什么、怎么启动、当前状态、谁维护。
.maw/project.yaml	项目 key、名称、目标和协作边界。
AI_START_HERE.md	AI 进入项目时先读什么、不能读什么。
.maw/agent-entry.yaml	共享入口、受保护路径、验证与收口契约。
.maw/components.yaml	真实组件，不保留不成立的模板占位。
.maw/modules.yaml	当前业务模块树；不确定时保守记录。
.maw/app-runtime.yaml	真实启动、测试和构建入口。

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

6. 进入快速开始

安装完成后进入 Seed 快速开始，完成第一次 AI Coding 闭环。如果需要完整个人开发环境，再继续阅读 Lite 安装；需要跨电脑、项目空间、工作项、验收和交付证据时，阅读 Studio 安装。