OpenSpec 入门：把 AI 编程需求变成可审阅的变更材料
团队部署 OpenSpec：同时管理 CLI 版本与项目指引
把安装包升级和各仓库的指引刷新视为两项需要分别审阅的变更。
团队部署 OpenSpec：同时管理 CLI 版本与项目指引知识学习CN编辑简报更新 2026-09-23
你将学会
- 先明确实际部署对象
- 用保存的差异进行试点
- 恢复时照顾两侧版本
开始前需要
- 基本 Git 与 Node 知识
- 可独立试验的样例仓库
用合成模式解释阻塞原因，把规划状态与实现证据放在不同列中。
先看结论
- CLI 与项目指引可能不同步。
- 共享规划仓库仍标注 beta。
- 恢复不应删除人工编写的计划。
先明确实际部署对象
文档中的起点是 Node 命令行工具和项目文件，不需要凭空增加 Docker 服务或公网入口。团队推广首先要确认运行时、工具版本和助手集成方式。
记录安装渠道与实际版本。全局命令行工具升级后，仓库里可能仍保留旧指引；README 明确要求在各项目运行 openspec update 来刷新这些文件。
用保存的差异进行试点
选择小仓库试点，更新前保存生成文件，更新后审阅新增指令、配置变化和本地定制。团队需要知道哪些文件可重新生成，哪些内容由人维护。
上游提供独立规划仓库来支持共享和跨仓库计划，但明确标注为 beta。这会引入新的权限与同步责任，单仓库试用不应在没有需要时加入它。
恢复时照顾两侧版本
如果升级造成意外行为，需要恢复已审阅的指引及此前记录的 CLI 版本。把有效的提案修改与工具生成文件分开，避免恢复操作抹掉规划工作。
本系列没有执行团队推广。标准化版本前，应自行确认包是否可用、工具兼容性和生成差异；固定源码提交只是分析基准，不证明已有完全对应的发布包。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
登记运行时、CLI 与助手版本。
- 2
分别试验升级与指引刷新。
- 3
写明版本和文件的恢复方式。
可复制示例
yaml
rollout:
node_minimum: 20.19.0
cli_version: record-installed-version
guidance: reviewed-git-diff
pilot: disposable-repository
rollback: previous-cli-and-guidance常见问题
需要部署网页服务器吗？
文档中的本地命令行起步流程不需要。
升级 npm 包会刷新全部仓库吗？
README 要求在每个项目里另行运行 openspec update。
资料来源
- OpenSpec / README.md来源核查 2026-09-23