企业官网建设流程全解析

• Web框架
• 后端
• CLI

本篇技术指南围绕 GoFrame（github.com/gogf/gf/v2）仓库中.agents/skills/openspec-propose/SKILL.md这一 AI Agent 技能展开，完整讲解如何使用openspecCLI 在一步之内创建一次变更（change）并生成全部规格化产物（proposal、design、tasks），使变更达到可实施（apply-ready）状态。读完本文，你将掌握 OpenSpec 提案技能的输入规范、五步执行流程、status/instructions命令的 JSON 数据结构、产物创建准则与护栏（guardrails），并能将其嵌入到 GoFrame 项目"探索 → 提案 → 实施 → 评审 → 归档"的 SDD（Spec-Driven Development）开发工作流中。

技能定位与元数据

openspec-propose是存放在.agents/skills/openspec-propose/SKILL.md下的 Agent 技能文件，其核心职责是：当用户快速描述想要构建的内容后，一次性生成一份包含设计、规格与任务的完整提案，直接交付实施。该技能文件自带 frontmatter 元数据，为 Agent 与工具链提供结构化信息：

技能文件正文明确了它的产物模型：一次提案会生成三类 artifacts，分别回答"做什么与为什么""怎么做"与"按什么步骤做"三个问题：

• proposal.md：what & why，变更目标与理由；
• design.md：how，技术方案设计；
• tasks.md：implementation steps，实施任务清单。

当所有产物就绪后，工作流会提示用户运行/opsx:apply进入实施阶段——在 GoFrame 仓库中，该斜杠命令的对应提示词文件位于.agents/prompts/opsx/apply.md，而提案命令本身的提示词版本记录在.agents/prompts/opsx/propose.md。

输入规范：变更名与需求描述

技能对输入有明确约定：用户的请求必须包含一个 kebab-case 形式的变更名（change name），或者一段描述想要构建内容的文字。两种输入形式对应两种处理路径：

• 直接给出变更名：沿用该名称，例如/opsx:propose add-user-auth；
• 给出描述性文字：Agent 需要从中推导出 kebab-case 名称，例如 "add user authentication" 推导为add-user-auth。

如果两者都没有提供，技能强制要求使用开放式（open-ended、无预设选项）的提问工具（AskUserQuestion tool）向用户确认："What change do you want to work on? Describe what you want to build or fix."，并明确规定不得在未理解用户构建意图前继续执行后续步骤。这条输入门槛与探索技能.agents/skills/openspec-explore/SKILL.md的定位形成衔接：探索模式负责发散思考与澄清需求，提案技能则要求需求已经收敛到可命名、可描述的程度。

五步执行流程

技能正文将提案生成组织为五个递进步骤，下面逐一拆解其命令、数据结构与判断逻辑。

步骤一：创建变更目录

变更名确定后，执行脚手架命令：

openspec new change "<name>"

该命令会在openspec/changes/<name>/下创建变更骨架目录，其中包含.openspec.yaml配置文件。目录名即 kebab-case 变更名，后续所有产物文件都写入该目录。在 GoFrame 仓库的协作约定中（见 AGENTS.md 的 Development Workflow Rules），任何非平凡变更都必须先经过该流程登记，openspec/changes/下的变更目录是后续所有工具操作的唯一事实来源。

步骤二：获取产物构建顺序

脚手架创建完成后，通过带--json的 status 命令读取依赖图：

openspec status --change "<name>" --json

解析返回的 JSON 需要关注两个关键字段：

该命令的作用是确定产物的拓扑构建顺序：只有依赖满足（ready）的 artifact 才能被创建，因此 Agent 需要循环处理"无待处理依赖"的产物，而不是按固定顺序盲目生成。

步骤三：按依赖顺序循环生成产物

这是整个技能的核心环节。Agent 应使用任务跟踪工具（TodoWrite tool）记录产物进度，然后循环执行：

1. 对每个处于ready状态的 artifact，获取其创建指令：

openspec instructions <artifact-id> --change "<name>" --json

2. 解析指令 JSON，其字段结构如下：

3. 先读取所有已完成依赖文件获取上下文，再以template为结构创建产物文件，同时将context与rules作为编写约束应用——但绝不复制到文件中。每完成一个产物，输出一句简短进度："Created "。

步骤四：确认 apply-ready 状态

每创建一个产物后都要重新运行openspec status --change "<name>" --json，检查applyRequires中的每个 artifact ID 是否都在artifacts数组中标记为status: "done"。只有当全部applyRequires产物完成时才停止循环——这意味着产物创建并非越多越好，而是以 schema 定义的实施前置条件为准。循环期间若某个产物因上下文不清晰而需要用户输入，则调用提问工具澄清后继续，体现"优先做出合理决策以保持节奏"的原则。

步骤五：展示最终状态

全部产物完成后，运行不带--json的状态命令输出人类可读结果：

openspec status --change "<name>"

随后按固定格式向用户总结：

• 变更名称与位置；
• 已创建的产物清单及各产物简要说明；
• 就绪声明："All artifacts created! Ready for implementation."；
• 下一步引导："Run/opsx:applyor ask me to implement to start working on the tasks."。

产物创建准则

技能对产物文件的编写提出四条硬性准则：

• 遵循openspec instructions返回的instruction字段——每个 artifact 类型的 schema 定义了其应有的内容，按 schema 编写；
• 在创建新产物前先阅读依赖产物获取上下文，保证产物之间的信息连贯；
• 以template作为产物文件的结构骨架，逐段填充其章节；
• context与rules是约束条件而非内容素材：<context>、<rules>、<project_context>等块只能指导编写过程，绝不能出现在产物文件中。

这四条准则保证了产物文件只包含规格内容，不混入 Agent 内部的系统提示与项目背景，从而让proposal.md、design.md、tasks.md保持纯净、可评审、可归档。

护栏：Guardrails

技能末尾定义了五条执行护栏，用于约束 Agent 行为边界：

• 完整创建：必须创建 schema 的apply.requires所定义的全部实施所需产物，不允许只生成部分产物；
• 依赖优先：创建新产物前必须阅读依赖产物；
• 澄清与推进平衡：上下文严重不清晰时才询问用户，但倾向于做出合理决策以保持推进势头；
• 同名冲突处理：若同名变更已存在，需询问用户是继续该变更还是新建一个；
• 写后验证：每个产物文件写入后需验证文件确实存在，再进入下一个产物的创建。

这五条护栏与 GoFrame 仓库在 AGENTS.md 中强调的"变更视为 active 直至归档"规则互为补充：提案阶段保证产物完整，归档阶段保证变更闭环。

在 GoFrame 仓库 SDD 工作流中的位置

从仓库根目录的 AGENTS.md 可以看到，GoFrame 项目采用 SDD（Spec-Driven Development）并用 OpenSpec 驱动实施，openspec-propose技能是整条流水线的中间枢纽：

• 前置阶段：/opsx:explore（对应.agents/prompts/opsx/explore.md与技能.agents/skills/openspec-explore/SKILL.md）以"思考伙伴"姿态完成需求探索，明确后才进入提案；
• 本技能：将探索结论固化为openspec/changes/<name>/下的proposal.md、design.md、specs/与tasks.md；
• 后置阶段：/opsx:apply按tasks.md逐项实施，完成后必须触发/gf-review技能评审，用户确认本轮迭代无遗留问题后再执行/opsx:archive归档（详见.agents/prompts/opsx/archive.md）。

值得注意的是，.agents/prompts/opsx/propose.md与本 SKILL.md 内容几乎一致，但前者是斜杠命令提示词（prompt），后者是 Agent 技能（skill），二者面向不同的调用入口；技能文件中出现的/opsx:apply、/opsx:continue等命令也都有对应的仓库提示词文件可供查阅，例如 apply.md。此外，仓库约定新迭代文档（proposal.md、design.md、tasks.md及增量规格）一律使用英文撰写，这与产物文件的纯净性要求共同构成了可长期维护的变更档案。

小结

openspec-propose技能的本质，是把"一次变更从想法到可实施提案"这一过程标准化为可复现的五步流程：询问或推导变更名 →openspec new change建立目录 →openspec status --json读取产物依赖图 → 按依赖顺序用openspec instructions --json生成各产物 → 校验 apply-ready 并展示总结。配合 GoFrame 仓库的探索、实施、评审、归档命令，它构成了一个完整、可审计、可归档的规格驱动开发闭环；对于希望为 AI Agent 编写类似技能、或理解 OpenSpec 工具链产物机制的开发者，这份技能文件是一个结构清晰、可直接借鉴的范本。

• Web框架
• 后端
• CLI