企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本篇技术指南围绕 gsd-2 仓库内置的full-project工作流模板展开，讲解如何用一条命令把任意绿地（greenfield）项目或大型功能从零引导进 GSD 的完整规划体系：初始化、讨论、规划、执行、验证五大阶段全程由 Agent 接管，Roadmap / Milestone / Slice / Task 四层结构落盘到.gsd/目录，实现长周期自主开发而不丢失全局视图。读完本文，你将掌握full-project模板的元数据含义、五阶段管线的具体产出物、底层路由机制（/gsd start full-project→/gsd init→/gsd auto），以及GSD-WORKFLOW.md中定义的文件格式与状态管理规范，能够直接在项目中跑通这套规格驱动开发流程。

模板是什么：一条命令拉起完整的 GSD 仪式

full-project是 GSD 工作流模板家族中级别最高的一个，定位是"完整仪式（full ceremony）"入口。它面向绿地项目或需要完整规划装置的大型功能，一次覆盖 Roadmap、Milestone、Slice、Task、研究、规划、执行与验证的全部环节。

模板本体位于 full-project.md，核心由三部分组成：<template_meta>元数据块、<purpose>用途声明与<process>路由协议。

template_meta 元数据解析

模板头部声明了自身的关键属性，这些字段同时被注册表 registry.json 使用：

其中mode: auto-milestone是四种工作流模式（oneshot、yaml-step、markdown-phase、auto-milestone）中唯一的非"遗留"模式——在 workflow-templates.ts 中，isLegacyWorkflowMode()的判断逻辑正是"只要不是auto-milestone就视为遗留引擎"。

注册表中该模板还带有两条元数据：

• triggers: ["new project", "greenfield", "from scratch", "build an app", "create a new"]—— 当用户输入包含这些短语时，自动检测机制会优先命中本模板；
• estimated_complexity: "high"—— 属于高复杂度流程，适合需要完整规划的项目。

autoDetect()对描述文本做分词打分：多词短语命中得分更高（每个词计 2 分），单次命中累计分 ≥4 为high置信度，≥2 为medium，否则为low。因此"build an app"这类双词短语能可靠地触发本模板的自动匹配。

五阶段管线：从初始化到验证的完整闭环

模板将整条开发链路划分为五个阶段：

1. init — 初始化项目，检测技术栈，创建 .gsd/ 2. discuss — 定义需求、决策与架构 3. plan — 创建包含里程碑与切片（slices）的路线图 4. execute — 执行切片：每个切片内依次进行 研究 → 规划 → 实现 → 验证 5. verify — 里程碑级验证与完成

这与 GSD-WORKFLOW.md 中定义的手动引导协议完全一致：work 以Milestone（一个可交付版本，1-10 个切片）→ Slice（一个可演示的纵向能力，1-7 个任务）→ Task（一个恰好能装进单个上下文窗口的工作单元）的层级推进，并有一条铁律——一个任务必须能在单个上下文窗口内完成，装不下就拆成两个任务。

每阶段落盘的文件

五阶段不是空泛的仪式，每个阶段都有确定性的文件产出。以M001、S01、T01为例，项目根目录.gsd/下会形成：

.gsd/ STATE.md # 仪表盘：永远最先读（派生缓存，运行时生成，已 gitignore） DECISIONS.md # 追加式决策登记表 CODEBASE.md # 生成的代码库地图缓存（GSD 自动刷新） milestones/ M001/ M001-ROADMAP.md # 里程碑计划（复选框即状态） M001-CONTEXT.md # 可选：discuss 阶段沉淀的用户决策 M001-RESEARCH.md # 可选：代码库/技术研究 M001-SUMMARY.md # 里程碑汇总（随切片完成而更新） slices/ S01/ S01-PLAN.md # 本切片的任务分解 S01-CONTEXT.md # 可选：切片级用户决策 S01-RESEARCH.md # 可选：切片级研究 S01-SUMMARY.md # 切片摘要（完成时写入） S01-UAT.md # 非阻塞人工测试脚本（完成时写入） continue.md # 临时文件：中断时的恢复点 tasks/ T01-PLAN.md # 单个任务计划 T01-SUMMARY.md # 带 frontmatter 的任务摘要

关键文件格式速览

M001-ROADMAP.md用复选框表达切片状态，行内元数据标签risk:与depends:[]会被解析器读取：

- [ ] **S01: Slice Title** `risk:low` `depends:[]` > After this: what the user can demo when this slice is done. - [ ] **S02: Another Slice** `risk:medium` `depends:[S01]` > After this: demo sentence.

Roadmap 还必须包含## Boundary Map小节——这是规划阶段强制产出的边界契约，说明每个切片产出哪些接口/函数/类型、消费上游切片的哪些产物。它迫使团队在实现前先想清楚切片边界，并为下游切片提供确定性的对接目标，从而让"切片是否真正连接"可以被机械化验证。

T01-PLAN.md是验证机制能机械执行的关键。它的 Must-Haves 分三类：

• Truths：任务完成时必须为真的可观察行为（"用户能用邮箱密码注册"）；
• Artifacts：必须真实存在且非桩代码的文件（"src/lib/auth.ts，≥30 行，导出generateToken、verifyToken"）；
• Key Links：制品之间的关键接线（"login/route.ts通过 importgenerateToken连接auth.ts"）。

路由机制：模板如何进入标准 GSD 流水线

模板文档明确说明自己是一个"便捷入口（convenience entry point）"：它不重造轮子，而是包装并路由到标准 GSD 流程。原文档给出的路由协议为：

1. 若.gsd/不存在 → 运行/gsd init引导项目；
2. 若.gsd/存在但尚无里程碑 → 通过/gsd discuss进入讨论阶段；
3. 若里程碑已存在 → 通过/gsd auto或/gsd next恢复执行。

源码中的实际路由实现

这一路由协议在 commands-workflow-templates.ts 中有直接对应实现。当handleStart解析出templateId === "full-project"时，会检查gsdRoot(basePath)是否存在：

• 不存在 → 向 Agent 发送引导消息："The user wants to start a full GSD project. Run/gsd initto bootstrap the project, then/gsd autoto begin execution."，并触发一次对话轮次；
• 已存在 → 提示"Project already initialized. Use/gsd autoto continue or/gsd discussto start a new milestone."。

也就是说，full-project是模板家族中唯一不创建独立 artifact 目录、不创建gsd/<template>/<slug>分支的模板——因为它把状态完全交给.gsd/与标准里程碑管线管理。

auto 模式冲突保护

由于工作流模板会自行派发消息并切换 git 分支，GSD 在handleStart入口处做了保护性检查（commands-workflow-templates.ts）：

• isAutoActive()为真时直接拒绝启动，提示先Run /gsd pause；
• isAutoPaused()为真时放行，并提示暂停的 auto 会话之后可用/gsd auto恢复。

这保证了手动启动的工作流不会与正在运行的自动调度循环互相踩踏。

深入标准 GSD 流水线：Agent 如何长周期自主工作

路由进入/gsd auto后，由 GSD-WORKFLOW.md 定义的手动引导协议接管。这份文档要求任何会话开始时按固定顺序读取状态文件，回答"What's next?"：

1. .gsd/STATE.md—— 我们在哪？下一个动作是什么？
2. 活动里程碑的M###-ROADMAP.md—— 计划是什么？哪些切片已完成？
3. M###-CONTEXT.md—— 里程碑级决策、参考路径与约束；
4. 活动切片的S##-CONTEXT.md（如存在）；
5. 活动切片的S##-PLAN.md—— 有哪些任务、哪些已完成；
6. .gsd/CODEBASE.md（如存在）—— 快速结构定位；
7. 若任务中断，读取活动切片目录下的continue.md恢复。

六阶段执行协议

实际执行按Discuss（可选）→ Research（可选）→ Plan → Execute → Verify → Summarize → Advance推进：

• Discuss：识别 3-5 个用户关心的灰区决策，用ask_user_questions逐轮询问，绝不虚构用户输入，产出M###-CONTEXT.md；
• Research：在陌生代码/复杂集成场景下先行侦察，产出含Don't Hand-Roll与Common Pitfalls两个反昂贵错误章节的M###-RESEARCH.md/S##-RESEARCH.md；
• Plan：把愿景拆成 1-10 个可演示纵向切片，按风险排序（高风险优先验证可行性），并强制编写 Boundary Map；切片内再拆 1-7 个上下文窗口大小的任务；
• Execute：执行任务步骤，用[DONE:n]标记进度，做出架构/模式/库决策时追加进DECISIONS.md；
• Verify：按验证阶梯逐级增强——Static（文件存在/导出齐全/接线正确）→ Command（测试通过/构建成功/lint 干净）→ Behavioral（浏览器流/API 响应正确）→ Human（仅在无法自查时询问用户），并产出带证据表格的验证报告。"所有步骤都完成"不算验证，必须检查实际结果；
• Summarize：任务摘要带 frontmatter（provides、requires、affects、key_files、key_decisions等），切片完成时压缩为S##-SUMMARY.md，里程碑随切片推进持续更新M###-SUMMARY.md。

状态管理：STATE.md 只是派生缓存

系统特别强调STATE.md不是真相来源，只是一块便捷仪表盘。真正的真相来源是：

• M###-ROADMAP.md→ 切片存在性与完成度
• S##-PLAN.md→ 切片内的任务
• T##-SUMMARY.md/S##-SUMMARY.md/M###-SUMMARY.md→ 各层压缩后的执行结果

当文件之间不一致（如 Roadmap 说切片已完成但任务摘要缺失）时，协议要求暂停并向用户呈报，而不是自行臆断。

上下文续接协议

针对长周期自主开发的硬约束——上下文窗口有限——协议定义了continue.md续接文件：上下文即将耗尽、会话结束或 Ctrl+C 时，把milestone/slice/task/step/total_steps、已完成工作、剩余工作、决策及"下一动作"写入该文件；恢复时读取并删除它（一次性消费，非永久存档），直接从 Next Action 继续。

同时下游任务注入摘要时有软上限：总注入摘要上下文控制在约 2500 tokens，优先从最高层级（M###-SUMMARY.md）开始，链太大时先丢弃最旧/最不相关的摘要。这保证了长周期开发的每个新会话都能以干净的上下文切入，而不因加载过多历史而劣化推理质量。

实战操作：如何在项目中启动 full-project

方式一：显式指定模板

/gsd start full-project 为一个新的 SaaS 应用搭建完整项目

命令解析逻辑在 workflow-templates.ts：第一个词full-project会先按精确 key 命中注册表（confidence: "exact"），剩余部分作为描述文本注入工作流提示词。此外，别名表把project、full也映射到full-project，因此/gsd start project ...同样可达。

方式二：自动检测

/gsd start build an app that tracks team OKRs

输入中没有模板名时，autoDetect()会对注册表中全部 27 个模板的 triggers 逐一打分。"build an app"与"create a new"是多词短语命中，得分最高，full-project会以high置信度被选中；若出现多个候选，命令会列出前 4 个让用户挑选。

辅助命令

/gsd start无参数且检测到进行中的工作流时，会提示"Run /gsd start resume to continue it."。这些子命令在 commands-bootstrap.ts 中提供了补全支持。

需要说明的是：由于full-project直接路由到标准 GSD 管线，执行主体是auto-milestone模式，因此模板自身的 git 分支创建逻辑（gsd/full-project/<slug>）会被跳过，分支与提交策略由里程碑生命周期管理（默认顺序提交在活动分支上；git.isolation设为worktree或branch时使用milestone/<MID>隔离分支，里程碑完成时 squash 合并回集成分支）。

与其他模板的定位差异

full-project在注册表中estimated_complexity: "high"、requires_project: true，与其余模板形成明确分工：

选择原则很直接：工作规模越大、仪式需求越高，就越应该用full-project把整个生命周期托付给 GSD 的 Roadmap/切片机制；而单点小改动则用轻量模板避免仪式负担。

延伸阅读

• 工作流模板本体：full-project.md
• 模板注册表（全部 27 个模板的元数据与触发词）：registry.json
• 模板解析与自动检测实现：workflow-templates.ts
• /gsd start//gsd templates命令实现：commands-workflow-templates.ts
• 完整的 GSD 手动引导协议（五阶段细节、文件格式、验证阶梯、Git 策略、上下文续接）：GSD-WORKFLOW.md
• 命令补全定义：commands-bootstrap.ts

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用