• CLI
• 开发工具
• AI 应用

在开源供应链攻击频发的今天，你安装的每一个组件都可能被悄悄篡改。OCX 作为 OpenCode 扩展管理器，用一套「SHA-256 内容哈希 + receipt 审计文件 + INTEGRITY_ERROR 快速失败」的三重机制，确保已锁定版本的组件内容永远不会被静默替换——即使你的注册表（registry）本身被攻破。本文将从新手视角，完整拆解这套供应链安全防护是如何工作的。

一、OCX 为什么把供应链安全放在第一位？

OCX 安装组件时，会把文件复制到你的项目里（.opencode/目录）而不是放进node_modules——也就是说，这些代码是你"拥有"的。可一旦代码进了仓库，它就成了供应链的一环：

• 🕳️ 恶意更新：注册表源被投毒，悄悄换掉组件内容
• 🔀 中间人攻击：下载过程被截断或篡改
• 🙋 误操作：团队成员无意间修改了已安装的文件

OCX 的防御思路很简单：给每个组件发一张"内容指纹"，以后每次对比，不一致就立刻报错。

二、第一重防线：SHA-256 哈希——为组件内容盖"指纹章"

当你执行ocx add安装组件时，OCX 会对下载到的内容进行 SHA-256 加密哈希计算：

• 单文件：直接对文件内容计算哈希
• 多文件组件：先把所有文件按路径排序（保证结果确定），再对每个文件计算哈希并生成清单，最后对整个清单算出"捆绑哈希"（bundle hash）

这个哈希值是内容唯一的"指纹"——哪怕只改动一个字符，哈希就会完全不同。相关实现见 packages/cli/src/utils/receipt.ts 中的hashContent与hashBundle函数。

三、第二重防线：.ocx/receipt.jsonc审计文件

组件首次安装成功后，OCX 会把"指纹"连同安装信息一起记录到项目中的.ocx/receipt.jsonc文件里。它既是一份完整性基线，也是一份安全审计日志：

字段定义可参考 docs/schemas/receipt.schema.json。值得注意的是，OCX 采用receipt 语义而非严格 lockfile 语义：它记录"装过什么"，但不会强制锁死全部更新——真正的防篡改靠的是哈希比对，而需要升级时可以用ocx update显式、可审计地完成。企业级用法（注册表锁定、审计追踪、内网部署）详见 docs/enterprise/overview.mdx。

四、第三重防线：INTEGRITY_ERROR——哈希不符，立刻"炸"

这是整套机制的核心。当你对已安装过的组件再次执行安装（或更新）时，OCX 会：

1. 重新计算本次下载内容的 SHA-256 哈希
2. 与 receipt 中记录的哈希比对
3. 一旦不一致，立即中止安装，抛出INTEGRITY_ERROR，退出码为 65

报错信息会直接展示"期望哈希 vs 实际哈希"，并给出明确的修复指引（见 packages/cli/src/utils/errors.ts）：

Integrity verification failed for "kdco/researcher" Expected: 3f2a…（旧哈希） Found: 9b1c…（新哈希） The registry content has changed since this component was locked. Use 'ocx update kdco/researcher' to intentionally update this component.

🔑 关键设计：INTEGRITY_ERROR是安全特性，不是 Bug。它逼着你用ocx update显式确认"我知道内容变了，我同意更新"——这让每一次内容变更都是有意为之、可追溯的。校验流程源码位于 packages/cli/src/commands/add.ts。

遇到 INTEGRITY_ERROR 怎么办？

# 先预览变更内容 ocx update kdco/researcher --dry-run # 确认无误后再真正更新 ocx update kdco/researcher

五、额外保障：CLI 自更新校验与ocx verify审计

1. 官方二进制校验（ocx self update）

OCX 自身升级时，会下载官方发布的SHA256SUMS.txt校验清单，对下载的二进制文件逐一对比哈希（支持 GNU/BSD 两种格式）。这能抵御镜像站投毒、中间人攻击和篡改的发布包。实现见 packages/cli/src/self-update/verify.ts。

2. 事后审计（ocx verify）

组件装完不是终点。你可以随时运行ocx verify，OCX 会逐一比对磁盘上每个文件与 receipt 基线的哈希，报告intact（完好）/modified（被改）/missing（缺失）三种状态——相当于给你的项目做一次"防篡改体检"。支持--json输出，方便接入 CI 流水线。命令参考 docs/cli/verify.mdx。

六、小结：一张图看懂 OCX 供应链安全闭环

官方安全策略与漏洞披露流程见 SECURITY.md，完整机制说明见 docs/security/verification.mdx。对新手而言只需记住一句话：在 OCX 的世界里，内容变了必须"当面签字"，否则一律拒绝。

• CLI
• 开发工具
• AI 应用