IT一般控制（ITGCs）指适用于组织整个IT环境的基础性控制措施，旨在确保信息系统的完整性、安全性和可靠性。它们为应用控制的合理制定和有效运行提供支持，助力保障整体控制环境的健全性。

此类控制范围广泛，覆盖组织内所有系统和用户，通常包括与系统访问、运营管理、变更管理及数据备份相关的政策、流程和活动。

一、ITGCs为何重要？

ITGCs是IT系统内部控制的基础。缺乏这些控制措施，即便最完善的应用层控制也可能失效。其重要性体现在以下多个方面。

法规合规要求：ITGCs是满足GDPR（通用数据保护条例）、SOX（萨班斯-奥克斯利法案）、HIPAA（健康保险流通与责任法案）、ISO 27001（信息安全管理体系标准）及NIST（美国国家标准与技术研究院）等合规标准与框架的必备条件。
审计准备：审计人员会对ITGCs进行评估，以确定在财务审计或合规审计过程中是否可以信赖组织的IT系统。
安全与风险管理：有效的ITGCs可降低未授权访问、欺诈、数据泄露及运营错误的风险。
业务连续性：ITGCs通过数据备份、灾难恢复和系统完整性保障措施，提升组织的抗风险能力。

二、ITGCs的核心类别

ITGCs包含多个核心类别，每类均针对系统管理与安全的关键环节。

访问控制
此类控制确保仅经授权人员可根据其分配的角色和职责访问IT系统和数据。

变更管理控制
变更管理控制规范系统、应用程序和基础设施相关修改的实施流程。

职责分离（SoD）
职责分离确保关键任务由不同人员分工执行，以防范利益冲突、欺诈或错误。

系统运营控制
此类控制与IT系统的日常运行和维护相关。

审计日志与责任追溯
此类控制确保数据定期备份，并能在灾难或故障发生时成功恢复。

审计日志与监控
此类控制确保所有系统活动均被记录和监控，以便及时发现可疑或未授权行为。

三、ITGCs与应用控制的区别？

尽管ITGCs和应用控制听起来相似，但二者的适用范围存在差异。

ITGCs适用于各类系统和流程，确保整个IT环境处于可控、安全的状态。
应用控制针对特定应用程序，聚焦于处理过程的准确性、完整性和有效性（例如输入验证）。
二者对于维持组织的安全态势均不可或缺，但ITGCs为应用控制的有效运行提供了基础框架。

四、ITGCs与合规法规

五、实施ITGCs面临的挑战

尽管ITGCs对维持组织安全态势至关重要，但实施过程中可能面临以下挑战：

缺乏对访问权限和变更的集中可视化管控
审计准备工作依赖人工，易出错
在混合云或云环境中难以维持控制的一致性
员工在治理控制方面的专业能力有限

六、ADManager Plus如何助力ITGCs实施？

理解ITGCs固然重要，但如果没有合适的工具支持，在整个Active Directory（AD，活动目录）环境中落地实施这些控制措施仍会困难重重。ManageEngine ADManager Plus正是解决这一问题的理想工具。
ADManager Plus是一款全面的AD管理与报表解决方案，可帮助组织有效执行ITGCs。

编者按： 在 AI 大模型浪潮中，GPU 选型究竟隐藏着哪些工程师必须掌握的核心门道？

我们今天为大家带来的文章，作者的核心观点是：GPU 并非一个黑箱式的整体产品，而是一个由微架构、内存子系统与互联方式共同构成的复杂技术系统 —— 只有理解其内在结构，AI 工程师才能做出真正高效、可扩展的硬件选择。

文章首先从“计算能力”这一核心概念切入，解释了其如何决定硬件特性与软件兼容性；随后，作者通过解读技术规格速查表，深入剖析了显存（VRAM）、带宽及 MIG 多实例技术对 AI 模型训练与推理的关键影响；最后，文章重点对比了 PCIe 与 SXM 封装形式及 NVLink 互连方案的优劣，并基于计算能力、内存和互联性能三大维度，为 AI 工程师提供了在不同部署环境下（云端或本地）选择 GPU 的实用决策框架。

作者 | Alex Razvant

编译 | 岳扬

大多数 AI 工程师都将 NVIDIA GPU 作为其 AI 工作负载的计算平台。不过，很多人只知道 GPU 叫什么名字，却不知道要让一个 AI 系统真正跑起来（部署上线），到底需要搞懂哪些关键的门道。

从大家用来训练 LoRA 适配器的 RTX 3/4/590，到驱动（并仍在驱动）大语言模型集群的 H100，再到专为大规模生成式 AI 训练与推理而进入数据中心的全新 Blackwell B100+ 芯片 —— GPU 的选择和配置参数可谓五花八门。但仅仅知道 GPU 的名字，并不能告诉你最关键的一点：

GPU 并不是单一、不可分割的整体产品。

它是由多个相互关联的技术模块或子系统组成的复杂系统：

• 一种微架构（例如 Pascal、Ampere、Hopper、Blackwell），它定义了芯片的底层特性，包括支持哪些精度格式、具备哪些张量运算能力等；
• 一套内存子系统，它决定了模型权重和激活值的传输速度；
• 一种封装形式与互连方式（PCIe、SXM、NVLink），决定了多块 GPU 能否在充分发挥各自性能的同时协同扩展。

本指南将从 AI 工程师的视角出发，拆解 NVIDIA GPU 产品线的内在逻辑：

某种架构具体带来了哪些实际的 AI 计算能力？内存子系统与互联方案如何限制或赋能 AI 工作负载？消费级 GPU 与数据中心级 GPU 除了价格和营销之外，究竟有何本质区别？

01 我的第一块 GPU

我的第一块 GPU 是 NVIDIA 7300GT，配备有 256MB 显存和 128 位显存总线。如今，就连一台微波炉的算力都比它强。2008 年，我（外）祖母给我买了人生第一台台式电脑，这块显卡就装在那台机器里。

记得当时我试图在电脑上运行《侠盗猎车手4》（Grand Theft Auto 4），结果游戏根本启动不了 —— 我猜，可能连渲染 Rockstar Games 的 Logo 第一帧对这块小家伙来说都太吃力了。我还记得，我曾试图努力说服父母给我买一块 NVIDIA 9500GT，因为有个朋友用的就是这款，他的电脑能在 1280x1024 分辨率下以高画质流畅运行那款游戏。但这完全超出了当时家里的经济承受能力。

你能想象，后来我一有机会就泡在他家里玩游戏。最终，经过各种折腾，我终于在自己的电脑上以 340x280 分辨率、全部最低画质勉强能玩一会儿了。

我还记得自己进入 Windows/ProgramFiles 目录，修改游戏的 .ini 配置文件，尝试调整 DirectX 9.0 设置，关掉能找到的每一项图形特效 —— 全靠当时能找到的每一篇教程指导。而那时我用的是拨号上网，网速只有 40kb/s，加载一页文字或一段视频常常要等好几分钟。

游戏画面大概像下图这样，但像素更模糊，帧数最高只有 12-13 FPS，显卡风扇在 70-80 摄氏度高温下疯狂运转。

不过嘛，好歹能玩了 :)

图 1. 《GTA 4》在NVIDIA GT7300上的运行效果（10FPS/最低画质/英特尔酷睿i5/8GB内存）。来源：YouTube 视频截图

有意思的是，正是从那时起，我开始接触到 NVIDIA SLI、不同的 GPU 系列、显存、内存这些概念。虽然当时我并不真正理解这些是什么，也并不想深究 —— 我唯一的念头，就是让这款全校同学都在聊的游戏在我的电脑上跑起来，好让我也能加入那个“圈子”。

回到现在，我们甚至可以直接在手机上流畅运行画质远胜当年的游戏，轻松达到 30+ FPS，还不怎么耗电。

我想通过这段经历传达的是：GPUs、图形处理技术、超级计算机、AI 计算，乃至整个科技领域，已经走了非常非常远。如今的计算设备不仅更快、更强、更节能，而且比以往任何时候都更便宜。

02 深度学习始于两块 GTX 550

在最近一期的 Joe Rogan 播客节目中[1]，黄仁勋提到了一段如今容易被遗忘的深度学习历史。2012 年，Alex Krizhevsky 和 Ilya Sutskever 训练了 AlexNet，这个图像分类模型一举击败了当时所有主流的计算机视觉算法。

图 2. 近期 Joe Rogan 播客节目的截图，嘉宾为 NVIDIA 首席执行官黄仁勋。

他们就用了 2 张 NVIDIA GTX 580 游戏显卡（每张配备 3 GB显存）就实现了快速卷积运算，这便是他们当时的全部配置。

他们开源的 cuda-convnet[2] 非常优秀，以至于在随后数年间成为行业标准，推动了深度学习爆发初期的头几年发展。2012 年的这次成功也暗示了一点：AI 的进步将极度依赖 GPU 硬件。

但是，硬件只占一半。如果你今天在编写或部署现代 AI 模型，几乎可以肯定你用的是 NVIDIA 硬件。这不仅仅关乎 FLOPs（浮点运算次数）或 GPU 显存有多大，同样重要的是软件栈 —— 那些底层库、框架和 SDK，让 AI 工程师能够训练、优化并部署自己的模型。

作为一名 AI 工程师，如果你了解 NVIDIA 如何构建其 GPU 体系，你的工作会轻松得多。

本文将以硬件优先的视角，为你提供该体系的实用指南：

• 软件视角：计算能力（compute capability）与 CUDA 特性
• 架构视角：Ampere → Hopper → Blackwell
• 硬件视角：PCIe 与 SXM、NVLink 的对比，以及它们何时重要

03 理解计算能力（Compute Capability）

每一块 NVIDIA GPU 都拥有一个“计算能力”（Compute Capability，简称 CC）版本号，例如 7.0、8.9、9.0 等。这个数字定义了该 GPU 支持哪些指令、CUDA 核心、Tensor Core、内存操作以及其他功能。简单来说，CC 版本号决定了每种 GPU 架构所具备的硬件特性。

如果我们查看下表，就能看到从早期的 Tesla GPU 到专为 AI 设计的最新 Blackwell 芯片，每个 GPU 芯片家族对应的 CC 版本号。

我 2008 年使用的 GT7300，便属于 Tesla 架构家族。有趣的是，一款基于 Tesla 家族 GPU（7800GTX）的修改版本 —— 名为 RSX（Reality Synthesizer）的芯片，曾被用于 PlayStation 3 主机。该芯片由索尼与英伟达合作开发。

图 3. 计算能力与GPU架构的对应关系图，展示了各 CUDA SDK 版本所涵盖的计算能力版本号范围。图片来源：维基百科，附有补充标注。

如果你拥有一块 NVIDIA GPU，可以在终端中运行以下命令查看它的 CC：

nvidia-smi --query-gpu=name,compute_cap --format=csv

图 4. 执行上述命令后，我的 RTX4080 GPU 的计算能力 (CC) 及其他 nvidia-smi 详细信息。

有几个关键特性与计算能力紧密相关：

• Tensor Core 与精度格式

  • Ampere（A100、RTX 30XX）：支持 TF32 和 FP16 Tensor Core
  • Hopper（H100）：通过 Transformer Engine 新增 FP8 支持
  • Blackwell（B100/B200）：进一步推进至 FP4/NVFP4，用于推理优化

图 5. Tensor Core 的组成结构对应的计算能力（Compute Capability, CC）。对于每一个 CC 版本号，Tensor Core 的配置都不同，并且经过了更进一步的优化。该图来自维基百科。

• 内存：更新的 CC 支持更先进的高带宽内存（如 HBM2E、HBM3、HBM3e）、更大的显存容量，以及更快的 NVLink 互连技术。
• CUDA 与库支持：新的 CUDA 特性在某个时间点后将不再向后兼容旧的计算能力版本。

分析 GPU 时的一个经验法则是：CC 版本号越高，对现代 AI 特性（FP8/FP4、更好的稀疏性、更大的内存、新的互连技术）获得的“原生”支持就越好。 下图概述了 GPU 的架构家族与具体型号，涵盖了从消费级 GPU 到数据中心 GPU 的范围，并展示了它们各自对应的计算能力（Compute Capability）分数。

图 6：以更宏观的视角展示了 GPU 架构与计算能力（CC）之间的关联，并包含了具体的 GPU 型号。该图源自维基百科，并添加了额外的标注说明。

总结本节内容：计算能力（Compute Capability）告诉你一块 GPU 实际支持哪些硬件特性，以及你的 CUDA kernel 能否以全速运行。显存（VRAM）、计算性能（FLOPs）和互连技术固然重要，但前提是这些功能必须被该 GPU 的计算能力所支持，才能真正发挥作用。

在了解了计算能力（Compute Capability, CC）之后，我们可以通过查阅“技术规格速查表”（Technical Cheatsheet）进一步理解 GPU 性能，我们可以从中提取诸如接口类型、浮点运算性能（FLOPs）、显存带宽（Memory Bandwidth）等具体细节。

04 解读技术规格速查表

在理解了计算能力之后，GPU 技术规格速查表（Technical Cheatsheet）是 AI 工程师用来掌握硬件与软件优化细节的另一关键参考工具。在一份技术规格速查表中，工程师可以查找到关于 CPU 性能、功耗、不同精度格式下的理论算力以及 GPU 封装形式等核心指标。

其中，最后一项（封装形式）对于计算集群的构建尤为重要，因为集群中需要连接多块 GPU 并共享资源池。通过速查表，你可以快速回答以下问题：

• 这款 GPU 是否支持所需的精度模式？
• 其显存容量与带宽是否充足？
• GPU 之间的互联带宽是否足以支撑模型并行？
• 它能否顺利部署到现有的硬件基础设施中？

在下图中，我们以 Hopper H200 GPU 的技术速查表为例，重点查看其 FLOPs 相关参数，并解释 SXM 与 PCIe 等不同封装形式之间的区别。

图 7. 带注释示例的 NVIDIA H200 GPU 技术速查表，以及展示 PCIe 与 SXM 外观形态差异的图片。

根据这份速查表，AI 工程师通常会首先关注显存容量、带宽以及特定精度类型的 FLOPS，这些指标直接决定 AI 模型训练与推理的速度。

以这款 GPU 为例，单块 H200 GPU 拥有 141GB 显存，带宽高达 4.8 TB/秒。对于视觉类工作负载（例如实时视觉 AI 推理），该 GPU 配备了 NVDEC 视频解码引擎，能够将视频数据解码并直接转换为张量就绪的数据结构（tensor-ready structures），无需经过 CPU 处理。

4.1 MIG - 多实例 GPU（Multi Instance GPU）

另一个重要细节是 MIG（Multi Instance GPU），它允许工程师将单块物理 GPU 切分为多个虚拟 GPU 实例，每个实例都运行在相互隔离的环境中。

例如，一块 H200 可被划分为 4 个 MIG 实例，每个实例拥有 36GB 显存。这意味着 4 位不同的 AI 工程师可以各自在独立环境中运行自己的工作负载。

比如在“多智能体系统”（multi-agent system）场景中，多个大语言模型（LLM）各自驻留在独立的显存（VRAM）和 GPU 资源边界内，同时并行处理不同的任务。

在模型训练的实验阶段，MIG 同样非常实用 —— 你可以用它并行运行同一实验的不同配置或优化策略。例如，一个 MIG 实例使用 FP8 量化、以 batch size 32 进行推理，另一个则使用 FP4 量化、batch size 64。

4.2 封装形式（Form Factor） —— SXM 还是 PCIe？

现在让我们聚焦于封装形式，因为它也直接影响 GPU 性能。在这份速查表中，列出了两种形态：PCIe 和 SXM。PCIe（Peripheral Component Interconnect Express）是一种通用接口标准，常见于消费级 GPU。

在附图中，可以看到一张游戏 PC 主板，其配备 PCIe 5.1 插槽，可用于安装如 RTX 4080/4090/5090 等显卡。而 SXM 是一种直接嵌入主板的特殊芯片封装形式，专用于数据中心集群。

例如，一台 H200 DGX 服务器包含 8 块 H200 GPU —— 它们并非通过 PCIe 连接，而是通过 SXM 直接连接，并通过 NVLink 互连。

图 8. H200 SXM 封装形式 GPU（左）和 PCIe 封装形式 GPU（右）的特写。下图是芯片在控制板上的外观。

采用 SXM 封装形式，GPU 能获得更高的供电能力，从而维持更高的持续时钟频率，并通过 NVLink 交换芯片实现 GPU 与 GPU 之间的直连通信。这对训练或部署大模型至关重要 —— 因为 AI 工程师可充分利用张量并行（Tensor Parallel）或流水线并行（Pipeline Parallel）等技术，同时保持极低的 GPU 间通信延迟。

例如，H100 的 SXM 封装版本可以组成 NVLink/NVSwitch 互联拓扑结构，在这种结构中，16 块 GPU 能够共享高达数百 GB/s 的双向通信带宽。这类多 GPU 集群通常用于训练和推理大型稠密 LLM 或 MoE（Mixture-of-Experts）模型 —— 因为 MoE 网络中的 token 路由和激活值交换，极度依赖高速的 GPU-GPU 通信。

图 9：由 NVIDIA NCCL 库所支持或优化的、包含 16 块 GPU 的互联拓扑结构。来源：NVIDIA[3]

4.3 什么是 NVLink？

要理解 NVLink 和 NVSwitch，我们可以先回顾一下早期的 SLI 接口。2012 年用于训练 AlexNet 的两块 GTX 580，就是通过 SLI 桥接器（SLI Bridge）连接，以实现更快的计算和两块卡之间的数据共享。SLI 诞生于游戏时代，当时 NVIDIA 主要面向消费市场销售用于图形渲染的 GPU。

图 10：使用 SLI 桥接器连接的 NVIDIA GeForce GPU。来源：维基百科。

NVLink 是 SLI 的继任者，专为 AI 工作负载设计。

对于桌面端（PCIe 显卡） ：NVLink 通过一种外置物理桥接器（NVLink Bridge）连接。这是一种紧凑的 PCB 结构件，插入两张相邻 GPU 顶部的专用 NVLink 接口，类似于老式的 SLI 桥。

对于服务器端（SXM 模块） ：在高密度服务器环境（如 NVIDIA DGX 系统）中，NVLink 连接直接集成在多 GPU 载板上。SXM 形态的 GPU 模块插入该载板后，NVLink 连接就成为服务器内部结构的一部分。

例如，下图展示了两块 A100 PCIe 显卡通过 NVLink 桥接器连接的情形。

图 11：两块采用 PCIe 封装形式的 NVIDIA A100 GPU，使用 NVLink 桥接器连接。

05 AI 工程师如何选择GPU

典型的 AI 工程工作流高度依赖专用硬件来加速模型训练与推理。尽管大部分工作负载运行在云计算平台上，但许多团队（尤其是处理高度敏感数据或有特殊需求的团队）仍会使用本地计算集群。无论部署环境如何，关于使用哪种 GPU 的决策都应该基于充分的研究、规划。

AI 工程师常见的部署环境包括：

• 云计算平台：诸如 AWS、Azure、GCP 或原生的 NVIDIA DGX Cloud 等服务提供可扩展、按需付费的顶级硬件访问权限（例如 NVIDIA H100）。LambdaCloud 或 RunPod 等特色供应商也提供了颇具吸引力的替代方案。
• 本地实验室：在私人数据中心或专用实验室工作的工程师对硬件拥有完全的控制权，通常使用 NVIDIA DGX 或 HGX 系统。

本地部署是目前大多数顶尖 AI 实验室（如 OpenAI、Anthropic、X 和 Meta）的主流选择 —— 他们都采购了 DGX 集群或大量 NVIDIA GPU 来自建数据中心。

这是因为在多数 AI 研究中，如果需要进行 100 次实验，其中 70 次可能失败。若使用按需付费的云资源，面临冷启动问题并在大型云集群上调配资源，成本将十分高昂。

在对比具体 GPU 型号时（无论是在云端还是本地），工程师通常会依据三大技术层面进行评估：

1）计算能力（硬件与软件层面）

对于 NVIDIA 而言，计算能力指标决定了 GPU 支持的底层特性，包括支持的精度格式、Tensor Core 或 CUDA Cores 的配置。

2）可用内存（VRAM 与带宽）

VRAM 指的是可用内存大小，而带宽则决定了数据存取的速率。 尽管大语言模型正趋向小型化（如 12B、30B 参数的模型已表现非常优异），但在预训练的 BF16 精度下将此类模型加载到内存中仍需大量 VRAM。

带宽是另一个关键的性能维度。训练或微调 LLM 涉及大量读写操作，这些操作不仅占用 VRAM，还会利用 GPU 的所有内存层级。GPU 除了显存（VRAM）之外，还拥有 SRAM 和寄存器（Registers）。这些高速存储单元用于临时缓存 kernel 计算产生的数据 —— 要么供另一个 kernel 接着使用，要么将数据写回 VRAM，以便 CPU 能够访问。

最新一代 GPU 大多采用 HBM，这种高带宽内存比消费级 GPU 常用的 GDDR-X 内存更适配 AI 工作负载。

3）互联能力（通信性能）

这一指标决定了 GPU 间相互通信的速度，对于分布式训练非常重要 —— 因为大多数模型并非在单卡上训练或微调，而是通常涉及多 GPU 集群。

注：例如 Mistral 8x7B MoE 模型就是基于 240 块 H100 GPU 从头开始训练的，这种配置在大多数 LLM 预训练中相当典型。

此处的关键区别在于连接接口的选择：是 PCIe 标准，还是 SXM+NVLink 组合。后者是大规模分布式 LLM 训练的首选方案。

遵循软件能力、内存和互联性能这三大技术层面来评估 GPU 选项，能够有效筛选出符合需求的 GPU 型号，并让我们能根据工作负载的具体要求对系统进行针对性调优。

06 结语

AI 世界日新月异，但底层的核心问题从未改变：

• 我的 GPU 能否运行所需的 kernels？→ 看计算能力与架构
• 我的模型和 batch size 能否装下？→ 看显存、内存类型与带宽
• 我的 GPU 之间的通信速度是否够快？→ 看 PCIe 与 SXM

归根结底，AI 工程师做出正确选择的关键，在于将这些核心需求与合适的工具、生态系统及可扩展性要求相匹配。明确你当前处理的 AI 工作负载（预训练、微调或推理）的具体需求范围，将极大简化选择合适计算资源的过程。

END

本期互动内容 🍻

❓如果你今天要搭建一个专用于 7B 参数级模型微调的实验室，会选 4 张消费级RTX 4090 还是 2 张专业级 A100？为什么？

文中链接

[1]https://www.youtube.com/watch?v=3hptKYix4X8

[2]https://code.google.com/archive/p/cuda-convnet/

[3]https://developer.nvidia.com/blog/doubling-all2all-performanc...

本文经原作者授权，由 Baihai IDP 编译。如需转载译文，请联系获取授权。

原文链接：

https://read.theaimerge.com/p/an-ai-engineers-guide-to-choosing

当前公司的业务代码中存在类似一下的代码逻辑：
一个代码解析器 然后内部存在一个不断增长的解析代码

public class CodeParser{

    static parseHtml();
    static parseCSS();
    static parseJSP();
    static ParseJAVA();
    static ParsePython();
}

原有的 CodeParser 类将 多种代码解析逻辑集中在一个类中，通过静态方法区分不同解析方式。

随着解析类型的增加，这种写法会带来：

• 单个类职责不断膨胀
• 不同解析逻辑相互耦合
• 可读性、可测试性下降
• 新增解析类型需要频繁修改当前的 CodeParser

那么如何重构代码呢？

二、原始设计的问题

1. 职责过于集中

public class CodeParser {
    parseHtmlCode(...)
    parseCSS(...)
}

• 一个类承担了多种不相关的解析规则
• 修改任一解析逻辑，都需要修改同一个类

2. 扩展方式不可控

当需要支持新的解析类型（如 Vue / React / Markdown）时：

• 只能继续在 CodeParser 中新增方法
• 类会持续膨胀
• 违反 开闭原则（OCP）

三、重构的核心思路

将不同的解析逻辑拆分成独立的类，每个类只负责一种解析方式，从而提升可维护性和扩展性。

四、重构后的设计思路

1. 抽象解析行为

将“解析代码”抽象为一个统一接口：

public interface CodeParser<T> {
    T parse(String content);
}

表达的设计意图是：

“代码解析是一种行为，可以有多种实现。”

2. 拆分不同解析实现

HTML解析

public class HtmlCodeParser implements CodeParser<HtmlCodeResult> {
    @Override
    public HtmlCodeResult parse(String content) {
        
    }
}

CSS 解析

public class CSSCodeParser implements CodeParser<CSSCodeResult> {
    @Override
    public CSSCodeResult parse(String content) {
        
    }
}

每个解析类：

• 只关注自身规则
• 互不影响

五、重构的好处

1. 可维护性显著提升

• 每个解析逻辑独立
• 避免误修改其他解析逻辑

2. 扩展成本更低

新增解析类型时：

class VueCodeParser implements CodeParser { ... }

无需修改已有解析类。

3. 为未来演进留好空间

后续如果需要：

• 自动识别解析类型
• 引入 Router / Registry
• 接入第三方解析库（再引入 Adapter）

当前结构 无需推倒重来。

六、与 Adapter / Strategy 的关系说明

当前阶段

• 不是 Adapter 模式
• 因为不存在“被适配的第三方接口”
• 所有解析逻辑均为系统内部可控实现

未来可能演进

当引入第三方解析库时：

ThirdPartyParser -> CodeParser

此时才会自然引入 Adapter。

七、总结

**本次重构的目的，是将不同代码解析逻辑按职责拆分，
降低单个类复杂度，提高系统的可维护性与可扩展性。**

什么是 Agent Skill

在与 AI Agent 协作开发时，我们常常希望它能遵循一些特定的、可复用的操作流程，比如按照固定格式创建 Git Release、执行项目代码检查、或是生成符合团队规范的文档。OpenCode Agent Skill 提供了一种机制，允许我们将这些可复用的指令和行为封装起来，供 Agent 在需要时发现并调用。

一个 Skill 本质上是一份包含了特定指令的 Markdown 文件，它定义了一项任务的名称、描述以及具体的执行步骤。通过这种方式，我们可以将复杂的、重复性的工作流程标准化，让 Agent 能够像调用工具一样，精确、一致地执行这些预定义的任务。这不仅提升了协作效率，也确保了输出结果的规范性。

创建一个 Skill

创建一个 Skill 的过程非常直接，核心是在指定的目录中放置一个名为 SKILL.md 的文件。

Skill 的存放位置

OpenCode 会在特定路径下搜索 SKILL.md 文件。这些路径分为项目本地和全局两种，方便我们将 Skill 应用于特定项目或是在所有项目中共享。

​

项目本地路径允许我们将 Skill 与代码仓库绑定在一起，当其他开发者克隆项目后，也能立即使用这些为项目定制的 Skill。OpenCode 会从当前工作目录向上搜索，直到 Git 仓库的根目录，并加载所有符合以下模式的 Skill 文件：

• .opencode/skill/<skill-name>/SKILL.md
• .claude/skills/<skill-name>/SKILL.md

全局路径则用于存放那些通用的、与具体项目无关的 Skill。这些 Skill 定义在用户的主目录下，对所有项目都可见：

• ~/.config/opencode/skill/<skill-name>/SKILL.md
• ~/.claude/skills/<skill-name>/SKILL.md

这里的 <skill-name> 是一个目录名，它必须与 Skill 本身的名称保持一致。这种目录结构使得每个 Skill 的定义都清晰地隔离在自己的文件夹内。下面的两种方式，选一种就好：

Skill 的文件内容

每个 SKILL.md 文件都由两部分组成：YAML Frontmatter 和 Markdown 正文。

Frontmatter 位于文件的最顶端，使用 --- 分隔，用于定义 Skill 的元数据。Agent 正是通过这些元数据来发现和理解 Skill 的用途。

一个合法的 SKILL.md 文件必须包含 name 和 description 两个字段。

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

在上面的例子中，name 和 description 是必填项，它们直接影响 Agent 如何识别和选择 Skill。而 license、compatibility 和 metadata 等字段是可选的，用于提供额外的信息。

name 字段的值必须符合特定的命名规范：

• 长度在 1 到 64 个字符之间。
• 只能包含小写字母、数字和单个连字符 -。
• 不能以连字符开头或结尾。
• 不能包含连续的连字符。
• 最重要的一点是，它必须与存放 SKILL.md 文件的目录名完全相同。

​

description 字段的长度限制在 1 到 1024 个字符之间。它的作用是向 Agent 清晰地描述这个 Skill 的功能，以便 Agent 在众多可用 Skill 中做出正确的选择。一个好的描述应该具体、明确，准确传达 Skill 的核心用途。

文件的正文部分则使用标准的 Markdown 语法，详细说明 Skill 的具体行为、使用场景和执行逻辑。这部分内容是 Agent 加载 Skill 后获取的核心指令，因此编写得越清晰，Agent 的执行效果就越好。

Agent 如何发现和使用 Skill

当 OpenCode 启动时，它会自动扫描所有预定路径，发现可用的 Skill。然后，它会将这些 Skill 的 name 和 description 提取出来，以工具描述的形式呈现给 Agent。你也可以直接问：

​

Agent 看到的可用 Skill 列表大致如下所示：

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

Agent 会根据当前任务的需求，分析这个列表中的 description，判断哪个 Skill 最适合解决问题。一旦决定使用某个 Skill，它就会调用内置的 skill 工具，并通过 name 来指定要加载的具体 Skill。

例如，当 Agent 决定使用 git-release 这个 Skill 时，它会执行如下调用：

skill({ name: "git-release" })

这个调用会触发 OpenCode 加载对应的 SKILL.md 文件的完整内容（包括 Markdown 正文），并将其作为上下文提供给 Agent。Agent 接收到这些详细指令后，就会按照文件中定义的方式继续执行任务。整个过程实现了 Skill 的按需加载，既高效又灵活。

配置 Skill 的访问权限

在团队协作中，并非所有 Skill 都适合对所有 Agent 或所有场景开放。例如，一些具有高风险操作的内部 Skill 可能只希望被特定的维护者 Agent 使用。OpenCode 提供了基于模式匹配的权限系统，可以精细化地控制 Agent 对 Skill 的访问。

权限配置在项目根目录的 opencode.json 文件中进行。我们可以在 permission.skill 对象里定义一系列规则。

一个基础的配置可能如下所示，它允许所有 Agent 访问所有 Skill：

{
  "permission": {
    "skill": {
      "*": "allow"
    }
  }
}

规则的键是匹配 Skill 名称的模式，支持 * 通配符。例如，internal-* 可以匹配 internal-docs、internal-tools 等所有以 internal- 开头的 Skill。规则的值则决定了权限行为。

通过组合这些规则，我们可以实现复杂的权限控制。例如，以下配置允许访问 pr-review，禁止访问所有 internal- 系列的 Skill，并在访问 experimental- 系列 Skill 时向用户确认。

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

为特定 Agent 覆盖权限

除了全局配置，我们还可以为特定的 Agent 单独设置权限，覆盖全局默认规则。

对于自定义 Agent，可以直接在其定义的 Frontmatter 中添加 permission 块：

---
permission:
  skill:
    "documents-*": "allow"
---

对于像 plan 这样的内置 Agent，则可以在 opencode.json 文件中进行配置：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

这种分层配置的能力为管理复杂的 Agent 体系提供了极大的便利。

彻底禁用 Skill 工具

在某些情况下，我们可能希望某个 Agent 完全不使用任何 Skill。OpenCode 也支持彻底禁用 skill 工具。

对于自定义 Agent，在其 Frontmatter 中设置 tools.skill 为 false 即可：

---
tools:
  skill: false
---

对于内置 Agent，同样在 opencode.json 中配置：

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

当 skill 工具被禁用后，Agent 将不会看到 <available_skills> 列表，也无法调用 skill 工具，从而完全隔离了它与 Skill 系统的交互。

解决加载问题

如果发现某个 Skill 没有按预期出现在可用列表中，可以从以下几个方面进行排查：

1. 文件名检查：确保文件名是 SKILL.md，全大写。
2. Frontmatter 检查：确认 SKILL.md 文件中包含了必需的 name 和 description 字段。
3. 名称唯一性：检查所有扫描路径下是否存在同名的 Skill。Skill 名称必须是唯一的，如果出现冲突，加载行为可能不确定。
4. 权限检查：检查 opencode.json 中的权限配置，deny 规则会直接将 Skill 从列表中隐藏。

通过这些检查，通常可以快速定位并解决 Skill 加载失败的问题。