Project Init 用户手册

公开分发状态

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 开源仓

mawflow project init 是统一的项目 Seed 初始化入口。无论目录是刚创建、只执行过 git init，还是已经有业务代码的干净 Git 仓库，都先进入项目根目录，再执行同一个命令：

mawflow project init .

Seed / Contract v2 的当前 CLI 基线为 mawflow-seed-kit 2.8.2、mawflow-host 0.2.8 与 @mawflow/cli 0.3.15。父目录中的 mawflow project init my-project 继续作为创建新子目录的兼容形式。

安装并核对版本

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
project.init.blank_components
component.lifecycle

默认桌面安装会准备 Host Base 专用 Python 环境，并注册、启动只监听 loopback 的本机连接 Agent；不会登录账号、启动项目执行运行时、修改任何项目或上传源码。无头服务器可显式设置 MAWFLOW_INSTALL_PROFILE=workspace-server，只准备 CLI/Python 运行时，不注册桌面 Agent。

新建目录初始化

最短路径：

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

空目录可由 CLI 自动执行 Git 初始化；显式先运行 git init 更利于明确仓库边界。所有目录默认以 blank profile 写入 Seed，不创建任何组件。已经执行过 git init 时会保留现有 .git。

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

mawflow project init my-project
cd my-project

默认来源是官网 Python 包源中的 mawflow-seed-kit。需要可重复构建时，可为新目标固定 package 版本：

mawflow project init my-project --template-version 2.8.2 --profile blank

已有 Git 仓库 Seed 化

先确认工作树干净，再执行统一命令：

git status --short
mawflow project init .

已有仓库同样默认采用 blank profile。旧 web-api/service/minimal 参数保留兼容，但都不再隐式生成组件。

已有仓库不会直接写入。命令先展示计划和精确确认串：

• 在交互式终端中，可以输入确认串并在本次调用内完成。
• 在非交互环境中，读取 JSON 返回的 next_command，审阅后再执行该精确命令。
• 只想预览时可使用 mawflow project init --plan。

mawflow project adopt --root . 仍是兼容别名。新文档和自动化应统一使用 mawflow project init；兼容别名通常只返回预览，需要按计划再次执行确认命令。

不同目录状态的实际行为

当前目录	默认 profile	结果
不存在的命名目标	blank	创建目录、初始化 Git、写入空组件 Seed。
当前空目录	blank	初始化 Git，并立即原子写入空组件 Seed。
当前目录仅含有效 .git	blank	保留 Git 元数据，并立即原子写入空组件 Seed。
已有干净 Git 仓库	blank	先预览、精确确认，再增量写入 Seed。
已 Seed 化 Git 仓库	已记录事实	幂等执行 Doctor，不重复写文件。
有未提交修改的 Git 仓库	不适用	拒绝并返回 git_worktree_not_clean。
有内容但不是 Git 仓库	不适用	拒绝并返回 existing_content_requires_git_repository。
.git 元数据无效	不适用	拒绝并返回 git_repository_metadata_invalid。

存量目录还没有 Git 时，先由项目负责人建立可恢复基线，再重新初始化：

git init
git add .
git commit -m "chore: establish repository baseline"
mawflow project init

是否提交基线由项目自己的 Git 规范决定；CLI 不会替你提交。

初始化会写入什么

当前 Seed 基础结构包括：

.maw/*.yaml
.gitignore
AI_START_HERE.md
MAWFLOW_CLI.md
PROJECT_COMMANDS.md
CHATGPT_TO_AI.md
code/README.md
docs/README.md
docs/handbooks/**

新空项目还会生成基础 README.md；存量仓库的业务 README.md 保持不变。组件和运行应用初始都为空，也不会自动生成 prompts/、ops/、docs/modules/ 或业务源码。

用 CLI 建立组件链路

# 新组件只生成 README 和边界描述，默认禁用
mawflow component init api --type backend

# 已有目录保留源码后纳入治理
mawflow component adopt code/legacy --key legacy --type custom

mawflow component list
mawflow component doctor api
mawflow component enable api
mawflow component disable api

需要审阅时给写命令加 --plan。禁用只切换项目事实，不删除目录。初始化项目中的 MAWFLOW_CLI.md 记录终端命令，PROJECT_COMMANDS.md 记录 AI 对话意图，CHATGPT_TO_AI.md 记录跨 AI 交接格式。

.maw/template-source.yaml 记录模板来源、版本与校验信息；.maw/project.yaml 记录项目名和项目 key。初始化完成后，应根据真实仓库补齐组件、模块、启动命令和协作边界。

Git 来源仅用于创建新目标

公开 GitHub/Gitee 当前稳定 tag 是 v2.8.2，与 package 2.8.2、Seed Contract 2 组成统一版本族。Git 与 package 仍是不同分发制品，哈希独立，但版本、BOM 与 Contract 指纹一致。

下面这些来源参数仅用于创建新的命名目标；已有 Git 仓库会拒绝 source/template 覆盖参数，避免整包覆盖业务项目。

从 GitHub 稳定 tag 初始化：

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

从 Gitee 初始化：

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

从任意 Git URL：

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

从本机模板目录：

mawflow project init my-project --source local --path /path/to/seed-template

指定新目标目录：

mawflow project init my-project --target-dir /path/to/my-project

安全和回滚边界

• 存量仓要求工作树干净；初始化不会替你提交或推送。
• 存量文件采用逐文件哈希校验、私有备份、原子写、完整 Doctor 回读和失败回滚，不做整目录替换。
• 初始化不会覆盖业务 README.md、源码、发布配置、仓库映射、真实密钥或 .local/ 私有内容。
• 空目录初始化失败时会移除本次写入；CLI 新建的 Git 元数据也会一起回滚，已有 .git 保留。
• 已 Seed 化项目再次执行是幂等 Doctor；需要升级时使用 mawflow project upgrade。
• 项目初始化本身不会登录账号、启动服务或注册系统服务。npm 包安装的桌面 Host Agent 生命周期与项目初始化相互独立。
• 模板包含 .local、私钥、授权码、真实客户资料或供应商密钥形态时会失败关闭。

旧版命令或 PATH 冲突

如果提示 adopt 不是有效命令，或 mawflow capabilities 缺少 project.init.current_directory / project.init.existing_git，当前终端调用的不是完整新版本。先确认路径：

command -v mawflow
mawflow capabilities

然后显式重装当前 CLI：

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

npm 启动器会在转发 project init/adopt 前校验 Host 版本和能力；版本号或能力不满足时会失败关闭，不把参数交给旧解析器。它还会拒绝缺少 sqlite3、ssl 或 venv 的不完整 Python，并在没有可用 Python 3.11+ 时准备受校验的托管 Python。

Seed 的公开访问边界

公开 Seed 可直接访问 GitHub 或 Gitee。查看、clone 和使用 Seed 不需要 MAWflow 登录授权码，也不要求先启动 Host Base 项目运行时。

下一步

• Seed 安装：按新项目或存量仓库完成第一次 Seed 化。
• Host Base 用户手册：安装、连接、运行环境和登录边界。
• Lite 安装：把 Seed 项目连接到本地产品工作台。