现有项目改造成 MAW 项目
本页是历史兼容地址。现有项目改造的主入口已合并到 Seed 安装，请优先按“总览 -> 安装 -> 快速开始”的顺序阅读。
已有项目接入 Seed Contract v2 时，核心原则是 一次性迁移，不整包覆盖、不长期双写。不要在已有非空项目目录里强制初始化，也不要手工复制模板文件覆盖真实项目。
老项目改造也从安装 Host Base 开始。只做 Seed 协作结构接入时，不改变原项目的业务代码、发布方式和运行入口；需要更多本机增强或项目空间能力时，再自然进入 Lite、Studio 或 Enterprise。
本页适合老项目、存量仓库、已经有业务代码的本地项目。如果你要创建一个全新项目，请回到 创建一个新项目。
改造目标
改造完成后，原项目仍保留自己的源码、技术栈、启动方式、发布方式和仓库历史；新增的是 MAW 项目协作结构：
| 增量结构 | 用途 |
|---|---|
.maw/ | 让 AI 知道项目身份、组件、模块、运行入口和边界。 |
docs/modules/ | 让 AI 按模块读取上下文，不全仓乱看。 |
prompts/ | 保存人工选择后执行的一次性任务说明。 |
ops/scripts/ | 放置本地检查、导出、文档索引或任务包脚本。 |
docs/ai-instructions/ | 沉淀长期可复用的项目指令、术语和经验。 |
1. 先安装 Host Base
先按 MAWflow Host Base 用户手册 安装并确认命令可用：
npm install -g @mawflow/cli --registry=https://mawflow.com/npm/
mawflow
mawflow --help
mawflow host status如果只是把老项目接入 Seed 协作结构，到这里就可以继续做项目事实盘点。需要本机增强时再看 Lite，需要项目空间和交付闭环时再看 Studio。
2. 保护原项目
进入老项目目录前，先确认原项目有可恢复点：
git status --short
git branch建议为改造单独建分支：
git switch -c adopt-maw-seed如果项目还没有 Git，请先初始化仓库或用你熟悉的方式做一份可恢复备份。不要把改造动作混进正在进行的业务功能分支。
3. 生成迁移预览
在老项目根目录执行：
mawflow project adopt --root .命令只生成迁移计划，不应静默覆盖。请核对全部写入、删除、风险、到期时间和精确确认串；也可以在本地工作台的 Seed 迁移提示中完成同一事务。
4. 盘点老项目事实
回到原项目，先写清楚现状，再复制结构：
| 事实 | 需要确认什么 |
|---|---|
| 项目身份 | 项目名、项目 key、维护人、当前阶段。 |
| 源码结构 | 前端、后端、移动端、脚本、共享包分别在哪些目录。 |
| 运行入口 | 本地启动、测试、构建、发布命令。 |
| 模块边界 | 页面、API、数据表、任务流或业务域如何分组。 |
| 敏感边界 | .env、密钥、本机资料、客户资料、日志和构建产物放在哪里。 |
这一轮只记录事实，不急着让 AI 重构目录。
5. 确认迁移并回读
迁移器会根据老项目事实生成并规范以下结构：
| v2 事实 | 迁移方式 |
|---|---|
.maw/project.yaml | 改成老项目的项目名、项目 key 和协作边界。 |
.maw/components.yaml | 写老项目真实组件，不使用模板默认组件覆盖。 |
.maw/modules.yaml | 先按现有页面、API、业务域保守登记模块。 |
.maw/app-runtime.yaml | 写真实启动、测试、构建入口。 |
.maw/seed.lock | 固定 v2 BOM 与契约指纹。 |
.maw/project-doctor.yaml | 固定 Project Definition 的必需事实与检查。 |
.local/.maw/ | 接收旧 .maw/*.local.yaml 本机覆盖，并保持 Git 忽略。 |
迁移不得覆盖：
- 老项目真实
README.md。 - 老项目
code/、src/、apps/、packages/等业务源码。 - 老项目发布配置、仓库映射、客户配置或真实 secrets。
.local/、本机 overlay、日志、缓存和构建产物。
确认后，事务会保存 owner-only 备份、原子写入全部文件、重新编译 Project Definition，并在失败时恢复原状态。最后运行：
mawflow project doctor --root .6. 让 AI 执行第一次小任务
改造结构建立后，不要马上发起大规模重构。先选一个小任务验证 AI 是否能按新边界工作：
# 老项目 MAW 改造后的第一条任务
## 背景
这个项目已经增量接入 MAW 协作结构。请先读取 README、docs/AI_CONTEXT_BRIEF.md、.maw/project.yaml、.maw/components.yaml 和本任务相关模块档案。
## 目标
完成一个小的、可验证的用户可见改动。
## 允许修改
写真实路径。
## 禁止修改
.local/**
.maw/*.local.yaml
真实密钥、账号密码、生产连接串
与本任务无关的模块
## 验收标准
写清用户可见结果、文档同步要求和验证命令。如果 AI 在执行中想扩大范围、覆盖旧结构或把模板默认值当成项目事实，立即用 Seed 快速开始 里的补充格式纠偏。
什么时候需要 Lite
老项目可以先只接入 Seed 协作结构。如果你希望在本地产品工作台管理项目、让 AI 工具读取受控项目上下文、使用 Local MCP 或查看 AI Credits 入口，可以继续了解 Lite；如果需要跨电脑、团队或移动端管理，再进入云端产品工作台与 Studio。
7. 检查改造结果
至少确认：
git diff --check再运行老项目自己的最小检查，例如测试、构建、格式检查或启动检查。Seed 结构的价值是把这些检查写进项目事实，而不是替代老项目原有验证。
完成标准
老项目改造成 MAW 项目后，应该满足：
- 原业务代码、启动方式和发布方式没有被模板覆盖。
.maw/project.yaml、.maw/components.yaml、.maw/modules.yaml已写成老项目事实。docs/AI_CONTEXT_BRIEF.md能告诉 AI 最小读取顺序和禁读路径。- 至少有一个模块能通过
docs/modules/INDEX.md定位。 - 第一条小任务能按允许路径执行、验证并收口。
.local/、真实密钥、客户资料和未脱敏日志没有进入提交。