此文初载于《SpecShield日志》吾乃SpecShield之共同创立者，此乃下文所述迁移目标之一——坦陈此实。此文旨在诚述SpecShield之定位，兼论他器之更宜处。

言简意赅

• 光之GitHub仓库已二零二六年正月十二日藏之末次发布：v1.0.9 於二零二五年八月出，。useoptic.com之域不再解析，
• 。Optic乃__JHSNS_SEG_34aa60eb_11__Atlassian於二零二四年四月所购，然未入Atlassian Compass之列，
• 。之MIT许可源码犹在GitHub，__JHSNS_SEG_34aa60eb_14__然已弃。— 无安全补丁，无新规，无支持，而汝之持续集成终将崩坏，当传递依赖达至生命终结之时。
• 若汝主要用以Optic者CI中规格差异比对与重大变更核查，直迁之途，莫过于此。特护盾(SpecShield)（网页界面与命令行界面暨GitHub应用与免费GitHub动作）或oasdiff开源命令行界面，无图形用户界面。
• 若尔用Optic者测试流量生成OpenAPI— 无直接替代品。汝需更易流程。
• 下：逐项比较之表，步步迁移之导，及难易替代之实列。

光景（Optic）究竟何事？

六载以来，Optic乃OpenAPI破变检测之开源首选。其有诸般，非多数开发者工具初创所及：清简之CLI，合理之规则系统，MIT许可，深融CI集成，及一小而忠之社群。

此乃其终之序时也。

未闻有正式之夕照宣告，无望之迁徙指南自Optic团队出，亦无存档而此乃分叉之祝福。其止如是。

世人皆料，自Atlassian收并Optic之后，其必成一体。阿塔休斯·康帕斯(Atlassian Compass)阿特拉斯之开发者体验产品，其整合未果。至二零二六年五月，康波斯仍专注服务目录与DORA指标，无API漂移检测之能。

此千五百星之库有九十二分叉，然无分叉者，成社群之继者若恃赖不已@useoptic/optic自 npm，汝所恃者，乃未得维之码，终将崩坏，及其 TypeScript / Node / npm 伴生依赖至 EOL 之时。

尔需迁徙。佳音者：此乃多数团队四时之功，非四旬之计也。

汝实用以Optic者（及汝所需易之者）

光之器有五能，异队择异能。欲更器，先辨何者适己——选非其宜，乃迁之过也。

1. 逐项比对异同，察变局之变

最常用之例。尔有openapi.yaml于汝之仓库中，尔已运行optic diff于每项PR皆在CI中运行，且该动作用于PR上已加注破坏性变更之警告。

更易之难易也。众取而代之者，有焉。

二、依规检勘OpenAPI

光之规则自成体系。.optic.dev.yml凡如"所有路径须为kebab-case"或"每端点需有描述"之事。

更易之难中道。汝将转至幽光者，OpenAPI校验之实标准也，其规约之林远胜于他。尔之定制规条，须以Spectral之格式重述之。

三、自捕获之交通生成OpenAPIoptic capture）

此乃Optic之最奇特性也。尔以Optic之代理置于测试套件之前，Optic自能依观察之流量，生成（或更新）OpenAPI之规范。

更替之难：甚难。无直接之开源替代品，其成熟度相当。替代之选有：

• Pollyjs（记录/重放HTTP，通用）
• Speakeasy异其程式——规范主SDK，非流驱动规范
• 手护OpenAPI之规（此乃众团队终将为之事也）

若汝恃重于optic capture汝之迁徙，苦甚于专有名词之用户。善谋之。

四、以 GitHub Action 集成 CI

吾useoptic/optic-action GitHub Action 乃发 PR 之注，并附差分之果。

更易之难： 甚易。有数种即插即用之替代品，其 PR 注之设或同或胜。

5. 供览差分与史之主界面

Optic Cloud（SaaS 层）予君以网界，俾览各版本间之差分，且与非开发者之干系人共之。

更換之難易：中。今之主理UI工具有二：一者價昂（Bump.sh, Stoplight），二者不若精工。而SpecShield之網UI，範圍直等，方在積極開發中。

迁移之選，略觀之

至於五月二六，實際之選，誠實相較：

三種模式將涵蓋約95%的Optic遷移：

1. 汝以Optic为CI中规格差异之用，且欲UI → SpecShield (最直之替代，心智模型转变最小)
2. 汝以Optic为CI中规格差异之用，且不需UI → oasdiff (仅CLI，Apache 2.0，将存续于任何SaaS公司)
3. 汝以Optic为代码整洁之用 → Spectral (无论何工具之异同)

此篇余文专论径一，盖其最通而鲜载。若君在径二或径三，oasdiff与Spectral之官文甚佳，无待迁导之文。

何故SpecShield为Optic用户最直接之替代品

吾特为Optic所倡之spec优先、CI驱动之工作流而建SpecShield。其心智模型无别：

• 汝将OpenAPI之spec提交于git
• 每有PR，新spec即与基支相较
• 破改之变，先标而后合
• 汝得佳美之差报（于界面，于命令行，及为PR之注）

与Optic同者何：

• OpenAPI 3.0与3.1之支
• 多文件规约之支（与$ref同）
• 破旧之分类（路径之除，类型之变，新必填之项等）
• GitHub App 之 CI/CD 融合，(未几) GitHub Action 亦将免费
• npm所布之CLInpx specshield compare ...)

何者胜于Optic？

• 双向契约测试（Bi-Directional Contract Testing, BDCT）— 验证供者/受者相容，与can-i-deploy门。光无此也。
• 相容之表 供多服务架构之用
• 佳妙之评语，堪为截图之资 （Optic之设计，务实用也）
• 主动开发 — 大约每周发布一次
• 免费层级 无时间限制（Optic云之免费层级，恒有限制）

异同何在（或有团队视之为降级）

• SpecShield乃一SaaS之產，有免費之級。Optic若欲續用開源之CLI，則需自備基礎設施。
• 其核心差異引擎，今非開源也（待其於二〇二六年後發布，免費之GitHub Action將開源）。
• 吾輩之團隊，較Optic鼎盛時為小——雖吾輩發布更速。

若君之移動，主因乃Optic已停維護，而欲求一物，将维持之，则取舍或利汝。若根本需开源或无，则视oasdiff.

。 分步迁移：由Optic至SpecShield

此乃某队用Optic CLI及GitHub Action之实际迁移。预计全程需时30-60分钟，含PR复审时。

第0步——审察汝今所使用者

删除之先，遍寻库中凡言及Optic之处。

# Find Optic config files
find . -name ".optic.dev.yml" -o -name "optic.yml" -o -name ".optic*"

# Find Optic CI workflows
grep -rE "useoptic/optic-action|optic diff|optic lint" .github/

# Find Optic CLI invocations in scripts
grep -rE "@useoptic/optic|optic capture|optic verify" package.json scripts/

# Find references in docs
grep -ri "optic" README.md docs/ 2>/dev/null

列所发现之文件为清单。汝将一一触之。

第一步 — 安装 SpecShield 命令行界面

《SpecShield CLI》已发布于npm，如specshield君毋须遍植之—npx 可用于持续集成：

# Test it locally — no signup needed for the diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

汝将见输出，含与 Optic 生成之类别同（分拆、不可分拆、增补），格式为洁净之终端表格.

若欲为持续集成脚本得 JSON 输出，用 --json 标志（并辅以 --output 以写入文件）：

# Print JSON to stdout AND save to a file
npx specshield compare old.yaml new.yaml --json --output diff.json

JSON之形若此

{
  "summary": { "breaking": 3, "additions": 12, "modifications": 7, "warnings": 0 },
  "breakingChanges": [...],
  "additions": [...],
  "modifications": [...],
  "warnings": [...]
}

第二步—易汝Optic GitHub之作业

若汝有此物.github/workflows/api-check.yml：

# OLD — Optic workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: useoptic/optic-action@v1
        with:
          spec: openapi.yaml
          base_ref: ${{ github.event.pull_request.base.ref }}

易之以是：

# NEW — SpecShield CLI workflow
name: API contract check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Extract base spec from base branch
        run: git show origin/${{ github.event.pull_request.base.ref }}:openapi.yaml > /tmp/base.yaml

      - name: Compare specs
        id: compare
        continue-on-error: true
        run: |
          {
            echo '## 🛡️ SpecShield · API contract check'
            echo ''
            echo '```
{% endraw %}
'
            npx specshield compare /tmp/base.yaml openapi.yaml --fail-on-breaking
            echo '
{% raw %}
```'
          } > /tmp/comment.md

      - name: Comment on PR
        if: always()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: /tmp/comment.md

      - name: Fail the build if breaking changes were found
        if: steps.compare.outcome == 'failure'
        run: exit 1

于此模式略述数事：

• CLI于非TTY环境中自禁ANSI色码，故围栏代码块内之输出于GitHub上呈显无瑕。
• continue-on-error: true 比较之際，纵有破格之变，亦使 PR 评注得发。终局之步，则明令败建，使 PR 检核犹能阻合。
• marocchino/sticky-pull-request-comment 后续之次，更注旧评于其处，不令 PR 为评注所扰。
• 诚心之SpecShield行动（方在研制）将呈示丰赡之Markdown注解，具色彩标示之总览表，兼可折叠之各端点差异。迨其问世，前述之围栏代码块法乃最为洁净之途径.

第三步 — 迁移尔之定制规则（若尔曾有所定制）

此乃尔若曾定制Optic规则引擎时，耗时最久之步骤。Optic规则若此：

# OLD — .optic.dev.yml
ruleset:
  - breaking-changes
  - examples
  - name: kebab-case-paths
    where:
      operation: { in: any }
    rule:
      after: must
      assert: |
        operation.path.split('/').every(s => /^[a-z0-9-]*$/.test(s))

今之SpecShield未显Spectral相容之定制规约API。暂且：

• 破例之规：已为SpecShield之内置探测器所涵，无需迁改
• 式则/整饬之规（kebab-case 之路径，所需之描述等）：当移至 CI 之别样 Spectral 步骤：

- name: OpenAPI lint
  run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

以 .spectral.yaml 类似：

extends: spectral:oas
rules:
  paths-kebab-case:
    description: Paths should be kebab-case
    given: $.paths.*~
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: ^(\/[a-z0-9-]*)+$

吾辈于SpecShield中，正致力于臻于至善之定制规则支持。迨其成，则前述两步之法，乃最为洁净之途也。

第四步——去其Optic之倚赖

既尔新之作业已呈青色：

# Remove npm dep
npm uninstall @useoptic/optic

# Remove config
rm .optic.dev.yml

# Remove the old workflow (or just edit it)
rm .github/workflows/optic-check.yml

以单一之PR提交迁徙——审之易，复之亦易，若有所失，可逆之。

第五步 — 设立仪表盘（非必需，但建议）

若求史实，则团队协作，BDCT，及一can-i-deploy超PR差异之关

1. 免費註冊於specshield.io
2. 于汝之仓库，安设SpecShield GitHub App
3. 尔既有之CLI运行将自动现于尔仪表盘之比较历史中

无需再行配置——GitHub App与CLI皆书于同一后端。

SpecShield所不能代者，于Optic（诚言）

Optic之能有三，今无洁净之SpecShield可代。若恃此，需有谋略。

1. optic capture — 由流而生规

SpecShield无直接代者。吾之模型，假汝手持规式（或由码生之，经框架注解库），若此。optic capture乃尔工作之枢，当察之。

• 持续使用Optic之存档capture独立运行指令（尚可运作一时——非依网络）
• 更易之Pollyjs(Pollyjs)为记录/回放
• 改用规格优先之工作流程（此乃业界所趋，虽无足轻重）

optic capture-式之功能，已在吾辈计划之中，然非于二六年间推出.

2. 依MIT许可之核心

Optic之差异引擎，依MIT许可。至二六年五月，SpecShield之核心引擎则为专有。免费之GitHub Action，于推出时将依Apache 2.0许可，然托管产品背后之引擎则为专有技术。

若"必为全开源"乃不可商榷之要件，当用oasdiff——此乃最成熟之开源方案，未受Optic停运之扰.

3. 规则集格式之确凿

Optic之规则DSL独树一帜。尔之规则不可一比一移植。尔需于二者间重撰之：

• 规盾之内置法度（默认涵括八成常例）
• 频谱之规式DSL（为余二成定制风格之规）

每定制一规，为改写计，需计一时辰.

当规盾非适迁之的

诚荐他器更优之境：

观后景之诚然：无单一之器可尽覆昔Optic之功。大抵诸队终将二器彼之管道中，一者用于辨异/破变之察，一者用于检文之误，此乃其旧有者也。

吾等自Optic之终所悟

有数事堪思，尤以建或购开发者工具者为甚。

1. OSS與VC，乃脆弱之結合也。Optic曾籌資，為人所收，旋即停運，此乃VC資金之常態也。OSS之碼存，然無人受薪以維之。若器為CI之要，則其資金模式與永續性，當與其功能並重考量之。

2. 收購非為延續。 "为[BigCo]所获"，初闻似可慰藉。然实鲜有如是者。计所获之器，不出十八月则必失，除非其产品之蓝图，公然与收购者所言之方向相合。

3. 先求规范。 光学之赌，在汝当自生规格于流。业界之见已移其势——规格乃真源，码与试自其生。此变亦为何以规格自摄之术未成必用之故。

4. 美者，亦要也。 光学之评论虽具实效，然质朴无华。今代之器（及将来代此器者）竞相争妍于界面与体验。工师摄屏而共评其美，此即流布之道也。

当日迁，勿俟来季

迁此之由有三，当速行之，勿待次番之发。

1. Optic 之 npm 包终将崩坏。 @useoptic/optic 依 TypeScript、Node 及数十种递归包，其中数者将于十二月内至终期。及是时，汝之 CI 将默然失败，其因难解，盖由根本之器无人维护。

2. 汝之众忘 Optic 之怪癖。 等待愈久，迁徙愈艰。设制汝之Optic流程之工程师，或非犹在是公司十二月内矣。

3. 若今迁徙，则事甚微。 大抵诸队皆可在一时辰内毕此诸事。待至CI之隙迫之，则汝将惶遽为之，在周五之午后。

五分钟内试以SpecShield。

若君已阅至此，欲以SpecShield代Optic，可试之。

# No signup needed for the CLI diff command
npx specshield compare old-openapi.yaml new-openapi.yaml

为仪表盘、历史记录、GitHub应用及BDCT：免费注册于specshield.io注册— 无信用卡，慷慨免费层。定价详情于specshield.io/定价.

欲求迁徙之助，可致信于我。创始人@specshield.io— 愿助任何光学难民迁徙，无偿，无论汝最终是否使用特谱盾。迁徙之事重于工具。

此指南有益乎？乃系列之一，论Optic API工具之后之景。次篇：深析SpecShield、oasdiff与Optic存档规则集之破变规则之异同——兼论各有所及而彼辈所遗之边角案。

有见闻或勘误？请于下置评或直邮吾。吾宁求是而不求速。