MAWflow 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 是开源项目协作规范，不是产品档位或在线工作台。
- 部分事实已超过核验周期，当前展示最后一次可信快照。
MAWflow Seed 是应用在 AI 编程工作目录里的开源项目协作规范和装备包。它帮助普通代码仓库说清项目结构、模块关系和验证入口，让开发者可以用 AI 编程工具完成更稳定的辅助开发；它不是账号产品档位。
Seed 适合个人开发者、独立开发者和小团队。它不是运行底座，不是云端项目管理平台，也不是企业治理系统；它提供的是放在代码仓库里的 AI 工作目录入口、项目事实、任务规范和验证入口，让你可以把需求、任务、检查、验收和复盘都留在项目里。
创建或导入项目时可以应用 Seed 规范。账号默认使用 Lite，需要本机执行时再添加宿主机，需要云端协作或组织治理时再升级 Studio 或 Enterprise。
Seed 是 AI 项目导航系统
MAWflow Seed 为 AI Coding 工作目录提供项目导航能力，让 AI 编程工具理解项目结构、模块关系和执行边界。
Seed 解决的不是“让 AI 更会写代码”，而是建立 AI 可理解、可执行、可验证的项目导航体系。
技术地图、Agent 工作入口、Task Pack 和 Verification Pack 属于后续能力说明；首次阅读时，你只需要先理解 Seed 如何让项目结构清楚、模块关系清楚、结果可以验证。
| 项目协作缺口 | Seed 提供的导航 |
|---|---|
| 项目目标不清晰 | 项目地图和项目事实。 |
| 代码结构缺少说明 | 模块地图和目录说明。 |
| 技术关系缺少上下文 | 技术地图、运行命令和检查入口。 |
| 修改范围缺少约束 | 允许范围、禁止范围和安全边界。 |
| 无法证明完成 | Task Pack、检查记录、Verification Pack 和收口规范。 |
Seed 是导航体系，不是 Host Base 这样的本机技术运行底座，也不是 Project Space 这样的业务项目执行底座。它先让代码仓库具备结构化项目上下文，再把本机运行和持续项目推进交给后续产品承接。
Seed 提供的导航能力
| 能力 | 说明 |
|---|---|
| 项目地图 | 说明项目目标、用户、范围、非目标和当前阶段。 |
| 模块地图 | 按模块、页面、API、表名或源码路径缩小 AI 需要读取的上下文。 |
| 技术地图 | 串联运行命令、依赖关系、检查入口和关键技术约束。 |
| Agent 工作入口 | 通过 AI_START_HERE.md、.maw/agent-entry.yaml 和工具适配规则告诉 AI 从哪里读起。 |
| 任务规范 | 用 Prompt Spec、Task Pack 和允许/禁止范围约束执行过程。 |
| 验证体系 | 用 Check Pack、readiness checks、Verification Pack 和收口要求记录验证结果。 |
为什么需要 Seed
AI 可以写代码，但普通仓库往往没有为 AI 协作准备足够清楚的项目结构。需求、边界、模块、验证、交付记录散落在对话、脑子和临时文件里，每次 AI 会话都需要重新理解上下文。
Seed 的目标不是替你写业务，而是把仓库改造成适合 AI Coding 的工作区。它让人和 AI 执行会话共享同一套项目事实、任务格式、检查入口和收口方式。
| 常见问题 | Seed 的处理方式 |
|---|---|
| 项目边界不明确 | 用 .maw/、模块档案和组件配置描述项目事实。 |
| 需求写得太口语化 | 用 Prompt Spec 把目标、边界、验收和验证写清楚。 |
| 大任务中断后难恢复 | 用 Task Pack、计划和 SESSION_STATE.md 保存执行状态。 |
| 修改后只靠感觉验收 | 用 Check Pack 和 Verification Pack 记录检查结果。 |
| 项目经验只留在聊天里 | 用学习模式沉淀术语、偏好、踩坑和本机差异。 |
| 公开内容容易带出敏感信息 | 用脱敏规则和 release gates 做公开前检查。 |
从了解 AI 到驾驭 AI
Seed 是这条路径的开源起点。它不要求你先搭建完整平台，而是先让一个普通代码仓库具备 AI 协作的基本结构。
| 阶段 | Seed 帮你完成什么 |
|---|---|
| 了解 AI | 理解 AI Coding 工作区、Prompt Spec、模型工具和验证方式，知道一次 AI 任务怎样才算说清楚、做完和验收。 |
| 拥抱 AI | 用 Seed 安装、项目事实、第一条 Prompt Spec 和新手训练路径，完成一次可复制、可验证、可收口的 AI Coding 闭环。 |
| 驾驭 AI | 用 Task Pack、检查、收口、学习模式和公开边界，让 AI 任务可恢复、可复盘，并能在需要时选择 Lite、Studio 或 Enterprise 承接相应能力。 |
你可以用 Seed 做什么
| 目标 | Seed 提供的结构 |
|---|---|
| 建立项目导航 | .maw 项目协议、模块档案、项目说明和 AI 协作入口。 |
| 明确 Agent 工作入口 | AI_START_HERE.md、.maw/agent-entry.yaml 和工具适配规则。 |
| 说明技术关系 | 技术地图、运行命令、检查入口和关键组件说明。 |
| 让任务可以被执行 | Prompt Spec、Task Pack 结构和可恢复任务说明。 |
| 让结果可以被检查 | Check Pack、readiness checks、验证命令和收口要求。 |
| 让交付可以被复盘 | Verification Pack、验收记录、风险说明和交付摘要。 |
| 让公开发布更安全 | 脱敏规则、公开边界、发布 gate 和示例 Pack。 |
| 让项目越用越清楚 | 内置指令、项目记忆、关键词学习和经验索引。 |
先从哪里开始
默认阅读顺序是 总览 -> 安装 -> 快速开始。
| 当前状态 | 推荐入口 | 结果 |
|---|---|---|
| 我要创建全新项目 | Seed 安装 | 用 mawflow project init my-project 创建 Seed 项目目录。 |
| 我已有 0.2.x 老项目或存量仓库 | Seed 安装 | 预览并一次性迁移到 Contract v2，不覆盖源码、不长期双写。 |
| 项目已经创建或改造完成 | Seed 快速开始 | 写项目事实、Prompt Spec，完成第一次可验证 AI Coding 闭环。 |
| 需要更多本机增强能力 | Lite 安装 | 进入 Lite，本机管理项目和增强上下文。 |
| 需要项目空间和交付闭环 | Studio 安装 | 进入 Studio，把需求、任务和交付证据串起来。 |
实用功能速查
| 功能 | 什么时候用 | 继续阅读 |
|---|---|---|
| Seed 安装 | 创建 v2 新项目，或把 0.2.x 项目一次性迁移到 v2。 | Seed 安装 |
| 新手训练路径 | 你想从零完成一次可复制、可验证、可收口的 AI Coding 闭环。 | Seed 新手训练路径 |
| AI Coding 工作区 | 你想知道 Seed 为什么要拆分源码、协议、文档、提示词和脚本。 | AI Coding 工作区 |
| Prompt Spec | 你要把一个想法交给 AI 执行会话。 | Prompt Spec |
| Task Pack | 一个任务需要多步执行、可恢复、可复盘。 | Pack 类型 |
| 内置指令 | 你想用 #任务包、#模块地图 这类短语调用固定流程。 | 内置指令 |
| 模块档案 | 项目变大后，希望 AI 只读相关模块，不全仓乱看。 | 模块档案 |
| 学习模式 | 想把项目术语、偏好、踩坑经验沉淀下来。 | 学习模式 |
| 快捷脚本 | 想用命令读取配置、检查边界、生成测试计划或导出证据。 | 快捷脚本入口 |
| 人机收口 | 你想让每次 AI 任务都有变更、验证、风险和发布影响。 | 人机收口 |
新手训练路径
如果你是第一次使用 Seed，建议不要按功能跳读。先用同一个“博客搜索”案例跑完新手训练：
- Seed 安装：创建全新 Seed 项目，或把现有项目增量接入 Seed 协作结构。
- Seed 快速开始：写入项目事实、交给 AI 执行并确认收口。
- 写第一条 Prompt Spec：复制博客搜索 Prompt，完成 10 分钟 AI Coding 闭环。
- 创建 Task Pack：当博客搜索涉及后端、分页、权限、测试和文档时，升级为可恢复任务包。
- 运行检查：把验证命令、失败原因和风险写成收口证据。
- 学习模式：把博客搜索默认边界、术语和经验沉淀下来。
- 可选：公开示例脱敏检查：只有准备把示例分享给外部用户时，才需要先脱敏、检查和人工复核。
这条路线的目标是 10 分钟可完成 AI Coding 闭环，并且每个 guide 都有 Prompt、验证和收口。第 7 步只面向准备公开分享示例的人，不是普通本地使用的必经步骤。
Seed 包含什么
AI_START_HERE.md和.maw/agent-entry.yamlAgent 工作入口。.maw协作协议模板。- Prompt Spec。
- Task Pack 结构。
- Check Pack / readiness checks。
- Verification Pack 结构。
- 模块档案规则。
- 脱敏和公开发布规则。
- 示例 Pack。
Seed 不包含什么
Seed 不包含云端项目空间、企业权限、统一登录、审批流、模型调用治理、自动调度、密钥托管运行时、客户数据、未公开任务资料或真实密钥。
如果你需要完整个人开发环境、本地产品工作台、Local MCP 或 AI Credits 入口，可以把 Seed 当作项目规范基础，再阅读 Lite 安装。如果需要跨电脑、项目空间、交付证据和团队协作，再阅读 Studio 安装。如果需要私有部署 Studio、团队级权限或审计，再评估 Enterprise。
什么时候需要 Lite
继续只用 Seed，适合你想维护开源项目导航体系、Prompt Spec、Task Pack、模块档案和项目检查。如果你需要下面这些增强能力，可以继续了解 Lite：
- 在本地产品工作台管理项目入口、AI 服务和运行状态。
- 让支持的 AI 工具通过 Local MCP 读取受控项目上下文。
- 使用 Lite 承接本机增强和上下文能力。
- 查看 AI Credits 入口或连接后续本机增强插件。
Lite 使用路径见 Lite 安装，第一次用法见 Lite 快速开始。需要项目空间时，继续看 Studio 安装。
分层阅读路线
- Seed 安装：创建全新项目，或把老项目增量接入 Seed 协作结构。
- 快速开始：从项目事实到第一条可执行任务。
- Seed 新手训练路径：用博客搜索案例完成第一次闭环。
- AI Coding 工作区：理解源码、协议、文档、提示词、脚本和本机资料的分工。
- Prompt Spec：把需求写成 AI 可执行任务。
- Pack 类型：理解 Seed Pack、Task Pack、Check Pack 和 Verification Pack。
- 写第一条 Prompt Spec：从一个小任务开始使用 AI 编程工具。
- 创建 Task Pack：把复杂任务拆成可恢复执行包。
- 内置指令：用
#任务包、#模块地图、#项目记忆等短语调用固定流程。 - 学习模式：把术语、偏好、经验和本机差异放到正确位置。
- 运行检查：把检查命令变成提交和收口证据。
- 命令索引：按本地开发、测试、配置、检查、公开发布查命令。
- 仓库平面与构造：理解
code/、.maw/、docs、prompts 和 ops 的分工。 - .maw 协作协议：理解项目协议文件怎么描述项目事实。
- Task Pack 运行方式：理解任务包如何执行、恢复和验证。
- 检查与发布 gate：提交、公开发布和脱敏前要跑什么。
- 技术地图：把项目身份、组件、模块、任务、检查和交付证据串起来。
- 升级反馈循环：理解 Seed 如何从真实项目反馈中持续更新。
- 目录地图：判断资料应该放在哪个目录。
- 配置文件：查看
.maw常见配置文件职责。 - 开源范围：哪些开放、哪些增强、哪些不开放。
- 公开示例脱敏检查：把示例、任务包或案例分享给外部用户前，先确认脱敏、授权和 gate。
- 脱敏规则：公开前必须清理的内容和流程。
- Release gates：公开发布前的自动检查和人工复核。
- Security：密钥、本机资料、任务包和公开贡献的安全原则。
- FAQ：仓库地址、适用对象、Studio / Enterprise 边界和公开规则常见问题。
适用对象
| 对象 | 推荐用法 |
|---|---|
| 个人开发者 | 用 Seed 建立项目结构和 AI 任务说明，降低重复解释成本。 |
| 独立开发者 | 用 Prompt Spec、Task Pack 和 Verification Pack 让项目可以持续迭代。 |
| 小团队 | 用模块档案、检查和交付记录统一 AI 协作口径。 |
| 企业团队 | 可先用 Seed 理清项目规范，再评估 Studio 或 Enterprise。 |
下一步
如果你准备开始使用 Seed，先读 Seed 安装。如果项目已经创建或改造完成，再读 快速开始。
Seed Contract v2.1 / mawflow-seed-kit 2.1.1 与公开 Git v0.2.31 均已发布并完成双仓验证。当前公开仓地址：
旧用户可继续固定公开 Git v0.2.28；升级时应整体切换到 mawflow-seed-kit 2.1.1、公开 Git v0.2.31 与同一 BOM，不混用两条契约线。