企业官网建设流程全解析

做了一年多AI应用，我发现大部分团队卡在同一个地方：不是模型能力不够强，而是“说不清楚自己的应用到底应该怎么表现”。提示词改一句、模型参数调一个值，往往要翻聊天记录、问负责同事、比对线上行为，才能搞明白发生了什么变化。OpenSpec这个轻量级AI工程规范管理框架，解决的就是这类问题：把提示词、模型参数、输出格式、评估标准这些原本散落在后台配置和口头约定里的东西，变成一份份可以放进Git仓库、可以评审、可以自动校验的规格文件。它适合正在做AI应用但没有重型平台支撑的小团队，也适合想给现有项目补上工程纪律的团队，甚至适合单兵作战的独立开发者，用来管理自己的多个AI项目。

我之前在一家公司的AI应用组待过，组里人不多，但每个迭代都要动提示词。那段时间最痛苦的是“线上表现变了，但没人说得清是哪次改动引起的”。后来我尝试把项目的规范文件化、版本化，跑了一段时间之后，团队终于不再需要用嘴复述每次改动。这篇文章就把这套思路和OpenSpec的落地方式完整拆一遍，包括设计逻辑、文件结构、CLI用法、常见坑和一些我个人的改进经验。

1. 项目定位与整体设计思路

1.1 为什么AI工程需要一份“可评审”的规格

传统软件开发里，接口文档、数据库设计、API契约都有明确的评审对象，代码改动可以通过diff来看，问题可以通过回滚来解决。但AI应用不太一样，很多团队把提示词直接写在后端代码里，把模型参数存在某个管理后台，把评估标准放在一个别人不知道的Excel表里。最要命的是，这些内容的改动根本没有历史记录，也很难做对比。

我打过一个比方：传统开发像是做菜时按菜谱一步步来，菜谱改了能看出来；而AI应用开发像是让厨师凭感觉做菜，今天盐放多了还是放少了，全凭记忆。OpenSpec的思路就是把这些“感觉”变成“菜谱”——每个AI应用模块都有一份明确的规格文件，告诉所有人这个模块应该用什么模型、什么温度、什么提示词模板、输出必须长什么样、达到什么标准才算合格。有了这份东西，改动就可以走评审，历史就可以追溯，出问题也能定位。

1.2 OpenSpec到底管什么：从提示词到模型参数

我实际梳理下来，OpenSpec管理的对象是AI应用里那些“以前不太被当代码对待”的配置，主要包括几类。第一类是提示词模板，包括系统提示词、用户提示词的框架和变量占位规则；第二类是模型调用参数，比如模型名称、温度参数、最大token数、超时时间；第三类是输出契约，也就是模型返回的数据结构，比如必须是JSON、必须包含哪些字段、字段类型是什么；第四类是评估标准，比如回答格式正确率、关键内容覆盖率的回归测试要求；第五类是行为约束，比如禁止模型触碰的话题范围、敏感信息的处理规则。

这些内容在过去可能分布在不同地方，OpenSpec把它们收拢到同一个目录结构下，用统一的格式去描述。这样一来，某个AI行为发生了变化，就不需要去猜“是哪里的配置被改了”，直接去看对应规格文件的提交记录就行。我在实践中发现，把评估标准也纳入规范后，团队对“这个版本到底行不行”的争论大幅减少，因为标准都写在文件里，跑一遍评估就知道结论。

1.3 为什么选择“轻量级”而不是重型平台

市面上有一些重量级的AI应用管理平台，提供可视化编排、在线调试、集中式配置中心。这类平台功能很全，但引入成本不低：要部署服务、要迁移数据、要培训团队，而且很多团队其实只有几十条提示词规则，根本不需要一个“管理平台”的复杂度。OpenSpec选择的做法是“轻量级”：不搭中心化服务，不搞数据库，就用一个命令行工具加一个Git仓库来管理。

这个选型我太认同了。小团队最怕的不是缺功能，而是工具链太重，导致大家懒得用。OpenSpec的逻辑是：既然代码已经用Git管理了，那规格也放进同一个仓库；既然开发者每天都在用命令行，那就把操作都收敛到几条命令里。没有额外的后台、没有额外的账号体系，打开仓库就能干活。对于“先跑起来再说”的团队来说，这个设计大大降低了落地门槛，一个下午就能把整套流程铺到项目里。

2. 框架核心机制与目录结构拆解

2.1 规范即代码：各组件如何协同工作

OpenSpec把“规范即代码”从口号变成了可实现的目录结构。一个标准的OpenSpec项目会在仓库里创建一个opspec/目录，里面分成两个核心区域：一个是active/，存放当前生效的规格文件；另一个是proposals/，存放待评审、未合并的变更提案。当提案通过评审后，会执行一次应用操作，把提案内容合并到active目录，这样当前的规格就发生了变化。

这种设计与代码分支的模型完全对应。active里的文件相当于主干代码，提案相当于功能分支；评审相当于code review；合并动作相当于merge。更重要的是，由于所有内容都是文本文件，你可以对提示词做diff，可以看某个参数是哪个版本引入的，也可以快速回滚到上一个规格。我在团队里做过一次演示：把温度参数从0.7改成0.2，然后直接比较两个版本的影响范围，整个过程不到两分钟，当时在场的同事才意识到原来AI配置也能这么管。

2.2 目录结构与文件命名规范

在实际落地时，目录结构我们一般长这样：

opspec/ ├── active/ │ ├── customer-service/ │ │ ├── spec.yaml │ │ └── evaluation.yaml │ └── order-agent/ │ ├── spec.yaml │ └── evaluation.yaml ├── proposals/ │ └── 2025-06-01-adjust-chat-style/ │ ├── proposal.md │ └── spec.yaml └── project.yaml

active下每个子目录对应一个AI应用模块，例如customer-service是客服模块，order-agent是订单助手模块。每个目录里必须有spec.yaml描述模块行为，evaluation.yaml定义评估方式。proposals下面按日期加主题存放提案目录，一个提案目录就是一个可评审的变更单元。

项目根目录的project.yaml文件存放全局配置，比如默认的模型提供商、全局的约束策略、评估工具路径等。这样设计的好处是：新同事入职后看一遍目录结构，就能知道团队有哪些AI模块、每个模块的规格在哪、当前有哪些变更在评审中。这种“目录即地图”的效果是口头沟通很难达到的，也是我认为OpenSpec最有价值的地方之一。

2.3 版本化变更流程：提案、评审、应用三个阶段

OpenSpec的变更流程我抽象成了三个阶段，对应三类状态。提案阶段是开发者修改或新增规格文件，放到proposals目录，此时内容还不影响任何线上行为；评审阶段是团队通过代码评审或看板评审讨论提案，确认是否符合业务预期、有没有引入风险；应用阶段则是通过命令把通过评审的提案写入active目录，让新规格正式生效。

三个阶段对应到命令上也很简单：改完文件后跑校验，确认格式正确后发起评审，评审通过后执行应用操作。我在落地时还加了一步，要求每个提案必须附带一个简短的变更说明文件，写清楚背景、影响范围和测试结果。这个习惯让提案评审的效率提升了很多，评审的人不需要自己去翻代码，先看说明就能判断是否继续看细节。

3. 关键模块配置与CLI实操要点

3.1 spec.yaml核心字段与书写规则

先看一份实际的spec.yaml示例，这是一个客服问答模块的规格：

name: customer_service version: 1.2.0 description: 处理用户售前与售后咨询，语气友好且简洁 model: provider: llm-provider-x model_name: chat-model-y temperature: 0.3 max_tokens: 1024 timeout_seconds: 30 prompt: system_template: | 你是一名电商平台的客服助手。 回答用户问题时，先确认理解，再给出解决方案。 如果信息不足，明确告知用户缺少哪些信息。 禁止编造订单状态或物流信息。 variables: - user_name - order_id - product_name output: format: json schema: type: object required: [reply, action] properties: reply: type: string description: 回复用户的话术 action: enum: [refund, shipping, product_query, general] description: 本轮交互需要触发的业务动作 constraints: language: zh-CN banned_topics: [promotion, competitor] sensitive_field: order_id evaluation: suite: ./evaluation.yaml thresholds: format_valid_rate: 0.98 banned_topic_hit_rate: 0.0

字段看起来多，但每一条都有明确作用。name和version是为了追溯，description是给人看的，model段定义调用参数，prompt段定义提示词模板，output段定义返回结构，constraints段定义行为约束，evaluation段关联回归评估文件。其中output段往往最容易被忽略，但它是保证下游能稳定解析结果的关键。如果模型输出的结构不稳定，业务代码解析就会出错，所以建议把输出契约写得细一点。

写spec.yaml有几点需要注意。第一，version的变更要谨慎，每次合入行为变更都应该升版本，否则无法区分兼容性；第二，temperature这类参数要写数值之外的解释，不然过两周就忘了为什么是这个值；第三，banned_topics这类约束必须配套评估规则，光写不查等于没写。我见过不少团队写了约束但没做校验，结果约束只是摆设，所以OpenSpec里约束和评估是绑定的。

3.2 CLI命令体系与典型使用场景

OpenSpec命令设计的原则是“能一条命令做完的，不拆成两步”。我常用的命令包括初始化、校验、生成提案、应用、看状态、查差异这几类。初始化命令负责在当前仓库中创建opspec目录结构和project.yaml模板；校验命令检查所有规格文件的格式与引用是否完整；生成提案命令会创建一个带日期的提案目录，并把指定的现有规格复制进去；应用命令则是把提案内容合并回active目录，同时更新版本号；状态命令用于列出当前活跃的模块和待处理的提案；差异命令输出某个模块不同版本之间的具体变化。

举个例子，团队要把客服模块的回复语气从正式改成轻松，步骤是这样的：先用生成提案命令创建提案目录，编辑spec.yaml里的system_template和description；然后本地执行校验，确认格式没问题；接着把提案提交到Git分支并发起评审；评审通过后执行应用命令，让active目录里的规格更新。整套操作和日常代码提交流程一致，团队成员几乎不需要额外学习成本。

# 初始化一个已存在仓库的规格目录 opspec init # 创建一个新的变更提案 opspec propose customer_service --name adjust_chat_style # 校验提案和当前规格 opspec validate --scope customer_service # 查看当前应用的状态 opspec status # 将提案合并为当前生效规格 opspec apply proposals/2025-06-01-adjust-chat-style

3.3 与CI/CD集成：把规范校验变成自动化门禁

只靠人提醒去维护规范，时间一长还是会松懈，所以OpenSpec的校验命令非常适合放进CI流水线。我在实际项目中把规范校验加到了合并请求的检查项里，只要PR里有规格文件变动，CI就会自动执行校验命令，校验失败就阻断合并。这一步把“规格必须合法”从口头要求变成了系统强制。

更进一步，可以把回归评估也加进流水线。当某个提案涉及关键模块的提示词改动时，CI会启动一个评估任务，跑evaluation.yaml里定义的测试用例，只有指标达标才允许合并。比如客服模块的格式正确率阈值是98%，新提示词导致大量输出不符合JSON结构，那CI就直接亮红灯。这种做法让我想起传统项目里的单元测试门禁，只不过这里测的是模型行为。用OpenSpec管理AI配置，本质上就是把AI应用也拉进了“测试不过不能上线”的工程轨道。

4. 实操复盘：一次AI行为变更的完整流程

4.1 场景设定：客服模块语气调整

为了把上面的理论落到地上，我模拟一个真实需求场景。假设团队运营的电商应用里有一个客服AI模块，用户反馈它回话太生硬，希望语气更亲切，同时保持回复的稳定结构。现在要用OpenSpec管理这次变更，目标有两个：一是让提示词更口语化，二是不破坏输出格式的稳定性。

前置准备是确保仓库已经初始化了OpenSpec目录，active里有customer_service模块的规格和评估文件。经过确认，当前版本的格式正确率是98.7%，之后评估会以这个为基线。下面我们按流程走一遍变更全过程。

4.2 从建议草稿到可评审提案

我首先创建提案目录：

opspec propose customer_service --name friendly_tone

命令会生成proposals/2025-06-01-friendly-tone/目录，里面预置了spec.yaml。打开这个文件，修改system_template，把原来“回答问题时先确认理解”改成“稍微共情一下用户的处境，再给出解决方案”，同时把description从“语气友好且简洁”改成“语气亲切但不啰嗦，让用户感受到被理解”。

另外调整了模型参数吗？没有。这次只动提示词，temperature保持0.3，max_tokens不变，因为不希望模型过于自由发散。输出格式完全没碰，reply和action字段的JSON结构原样保留。这个“能少改就少改”的原则在实际变更中特别重要，改动面越小，回归风险越低。

修改完以后跑校验命令，确认文件合法；然后把提案提交到分支，在合并请求描述里写清楚变更原因和影响范围。评审的同事看到diff集中在提示词部分，输出契约没动，很快就通过了。这里也体现出OpenSpec的一个隐性价值：评审人不需要懂AI，也能通过diff范围判断风险高低。

4.3 应用变更与回归评估记录

评审通过后，执行应用操作：

opspec apply proposals/2025-06-01-friendly-tone

这时候active/customer-service/spec.yaml会被更新，版本号从1.2.0升到1.3.0。我紧接着跑了一次本地评估，输入一批典型用户问题，观察模型回复的格式正确率、敏感主题违规次数、回复风格是否符合预期。结果显示格式正确率是98.9%，略高于基线；违禁话题命中率为0；人工抽查回复，语气确实软下来了一些。

把这个评估结果记录在提案说明里，整个变更就算闭环了。以后如果有人问“客服模块温暖语气是什么时候上的”，只需要翻Git历史，找到1.3.0那次提交即可。如果线上出现异常，想把语气改回严肃风，也只需要把规格文件恢复到1.2.0版本再应用一次。这种可回溯、可回滚的特性，是以前用后台配置改提示词时完全做不到的。

4.4 多模块并行变更与冲突处理

实际团队里不太可能只有一个AI模块，当多个提案同时进行时，冲突就会冒出来。比如A同事在改客服模块的提示词，B同事在改同一个模块的输出契约，两个提案都改了spec.yaml，就可能产生合并冲突。OpenSpec的处理方式和Git一致：先落地的提案优先合入，后落地的需要在上一个版本的基础上重新调整。

我处理业务冲突的经验是：先约定模块所有权，一个模块的spec.yaml不要同时让两个人改。如果确实需要并行，就按“提示词”“输出契约”“评估标准”拆成不同的变更单元，减少交集。还有一招是把大模块拆小。比如客服模块可以拆成售前和售后两个子模块，各自维护独立规格，改动自然就分开了。这种拆分对团队协作的好处远大于麻烦，越早做越划算。

5. 常见问题与排障技巧

5.1 典型异常与排查对照表

OpenSpec落地一段时间后，我整理了一张问题对照表，覆盖了新手阶段最常见的异常。

这里面“随机性太高”值得多说一句。大模型输出天然有波动，同一条提示词跑十次可能有九种措辞。评估时如果只看一次结果，很容易误判。我后来在处理这个问题时，会设置评估次数，取格式正确率和指标均值，并且固定temperature为0或一个低值来做回归测试，这样信号更稳定。

5.2 防止规范漂移的三个习惯

规范管理最大的敌人不是工具不好用，而是“写着写着就过期了”。我的观察是，很多团队的规格文件在落地三个月后就会和实际行为脱节，原因很简单：有同事图省事直接改了线上配置，却没有同步更新spec.yaml。OpenSpec虽然提供了规范和实际行为同步的机制，但前提是所有人严格遵守“必须走提案流程”这条纪律。

为此我总结了三个防止规范漂移的习惯，都来自踩坑经验。第一，把规范校验设为合并门禁，任何绕过Git提交的线上配置修改一律禁止，从系统层面堵住漏网之鱼；第二，每次发布前花十分钟检查active目录里的规格和线上实际配置的差异，或者写一个小脚本对比关键参数，发现不一致立即处理；第三，定期做“规范评审日”，每个月过一次所有模块的spec.yaml，把不再符合业务的约束删掉，把缺失的约束补上。

5.3 几个我踩过的真实坑与解法

第一个坑是刚开始把评估标准写得太笼统，比如“回答质量要好”，这种标准主观到没法自动判断。后来我改成可量化的指标：格式正确率、必填字段完整率、违禁话题命中率、平均响应时间。人话就是不能只说“好”，要说“好到多少分”。AI工程的核心就是可度量，不可度量的规范等于没有规范。

第二个坑是忽略了版本兼容性。有一次我直接改了输出契约，把reply字段的取值从单字符串变成了数组，下游解析代码来不及同步，线上直接报错。从那以后我规定：涉及输出结构的变更必须和代码发布同一个节奏，spec.yaml里的输出契约改动要升级一个大版本号，并明确写在变更说明里。第三个坑是低估了模型参数对提示词效果的影响。之前为了压低成本把temperature从0.3调到0.8，结果同一套提示词的语气完全跑偏，回归评估也没拦住，因为没有覆盖到语气这一类主观指标。后来我在评估用例里加入“风格标签分类”的检查项，才把这个漏洞补上。

6. 一些个人经验与后续扩展思路

6.1 让团队接受规范管理的三个关键动作

OpenSpec这类工具本身不复杂，难的是让团队养成使用习惯。我总结下来的三个关键动作是：先立样板、再定红线、最后做简化。所谓立样板，就是自己亲手把一个模块的规格整理清楚，让其他人看到规范化后的好处，比如查历史方便、评审时不用反复追问背景；定红线是指把规范和发布流程绑定，不合法就不让合并，没有例外；简化是指不要一上来就追求完美的目录结构，先跑起来，用一段时间后自然会发现需要增减哪些字段。

如果你正在带一个小团队，我特别建议不要在第一天把所有模块都纳入OpenSpec管理。先挑一个行为边界清晰、评估指标相对容易定义的模块，比如客服问答，跑完一个完整变更周期，给团队形成模板和信心，再逐步扩大范围。任何工程工具都是这样，先窄后宽，先粗后细。

6.2 从规范文件到全链路可观测

OpenSpec解决了“规格是什么”和“规格怎么变”的问题，但还没解决“线上是否按规格执行”的问题。我目前在后续项目里做的一个扩展是，把spec.yaml里的关键字段同步给监控系统：模型名称、temperature、输出契约版本、评估阈值都会上报到观测平台。线上调用时如果实际参数和规格不一致，系统自动告警，这相当于给规范文件加了运行时验证。

再往下走，可以给每个AI模块的规格文件接入自动化代码生成，比如根据output段的schema自动生成API解析代码，或者根据prompt变量定义自动生成测试用例。这些扩展都不是OpenSpec本身提供的，但它定义的规范化文件结构让这些自动化成为可能。我个人觉得，走向成熟AI工程化的标志就是这个：配置不只是给人看的，更是给系统用的。

6.3 最后一点体会

说实话，OpenSpec刚出来的时候我也不确定它能解决多少问题，毕竟团队遇到的问题往往不是工具层面的。但在实际跑完几个迭代之后，我最大的感受是：它让AI应用开发重新回到了工程节奏上。过去改提示词像在聊天软件里发消息，发出去就结束了；现在改提示词像改代码，有提交记录、有评审、有评估、有回滚。这种节奏给人带来的安全感是实实在在的。规格文件的价值不在于那一刻被写下来，而在于后续每一次修改它、评审它、应用它时，团队都能明确自己在做什么，下一步要往哪走。