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