企业官网建设流程全解析

最近在帮团队做 AI 编码工具的选型和落地时，我发现一个普遍现象：很多开发者已经在用 OpenCode 这类终端型 AI Agent，但实际用法还停留在“把需求粘贴给模型，等它返回一大段代码，再手动复制到文件里”。这本质上还是聊天式编程，只是把搜索引擎换成了大模型，效率提升有限，也没有真正发挥 Agent 的自主性。

真正的 Agent 式编程，是让 AI 不只会“说代码”，还会“改代码”“跑代码”“查代码”。它应该能自己读取项目目录、理解现有模块之间的依赖关系、修改文件、运行测试、再根据报错信息自我修正。对于长期维护的项目来说，这种能力比“一次生成 200 行代码”更有价值。而要把这种能力稳定复用到不同项目、不同团队流程中，就需要一个关键的设计：把能力沉淀成可复用的 Skills。

这就是本文要展开的主题。下文会先讲清楚 Agent Skills 是什么、和 Agent 有什么区别，再介绍 OpenCode 这个开源终端 Agent 的安装和使用方式，最后用一套完整的项目实战，演示如何从零搭建“带 Skills 的代码质检助手”。无论你是刚接触 AI 编程的新手，还是已经在团队里推广 AI 编码工具的负责人，都能从这套流程里拿到可以直接落地的方案。

1. 背景与核心概念

1.1 从“聊天式编程”到“Agent 式编程”

先做一个通俗类比。如果把 Agent 理解成一个刚入职的程序员，它的大模型能力是“聪明的大脑”，而 Skills 就是它的“专业技能包”。一个没有 Skills 的 Agent，只知道通用知识，你让它写测试，它会写得很散；你让它做代码审查，它会从头到尾泛泛而谈。而当你给 Agent 挂上“测试编写”“代码审查”“安全巡检”这些 Skills 之后，它就相当于经过了对应岗位的培训：知道先做什么、后做什么、按什么标准输出、哪些坑绝对不能踩。

专业一点说，Agent Skills 是一组可复用的能力定义，通常由一个说明文件（例如 SKILL.md）加上若干辅助脚本、依赖描述组成。说明文件里写清楚技能的用途、触发条件、执行步骤、输出格式和约束条件；辅助脚本则承担那些不适合让模型“凭空发挥”的确定性操作，比如扫描文件、统计指标、调用静态检查工具等。

Skills 解决的核心问题有三个。第一是稳定性：同样的任务，用 Skill 约束执行流程后，输出质量更可控，不会每次换一种风格。第二是复用性：一个写好的 Skill 可以在多个项目、多个场景中重复使用，不需要每次重新描述需求。第三是专业性：Skills 可以把团队内部的代码规范、审查清单、发布流程等隐性知识显性化，变成 Agent 能遵循的操作手册。

1.2 什么是 Agent Skills

这里要回一个很多初学者都会问的问题：Agent Skills 和 Agent 到底有什么区别？为了讲清楚，我们需要把几个容易混淆的概念拆开看：

Agent 是“大脑和调度器”，它决定什么时候调用什么能力；Tool 是“手脚”，负责执行单一动作；Skill 则是“套路”，它把一系列动作和判断标准编排成一套完整的工作流。Skill 内部可能用到多个 Tool，也可能调用本地脚本，但这些细节对 Agent 是透明的。Agent 只需要知道“我有一个代码审查 Skill，遇到审查需求时使用它”。

搞清楚这个区分非常重要。如果你把 Skills 理解成“更智能的提示词”，就会忽略脚本和工具的作用；如果你把 Skills 理解成“单个函数”，又会忽略它作为工作流编排的价值。正确的理解是：Skills 是介于提示词和完整 Agent 之间的中间层，它让能力沉淀、复用和传播成为可能。从本质上说，Skills 回答的是“一个 Agent 应该以什么方式工作”，而不是“Agent 应该调用哪个接口”。

1.3 OpenCode：开源终端生态里的新选择

这里再介绍本文实操部分的主角——OpenCode。OpenCode 是一款运行在终端里的开源 AI 编码 Agent，社区中常被称为“Claude Code 的开源替代”。它最大的特点是把 Agent 的自主能力直接搬进命令行：你可以在项目目录中启动它，它会自动读取仓库结构、跟踪文件变更、执行命令，并根据执行结果决定下一步操作。

相对 IDE 插件或网页工具，终端型 Agent 有几个明显优势。第一是环境一致：你平时怎么在终端里跑测试、跑构建，Agent 也怎么跑，不需要额外配置一套图形环境。第二是轻量：不依赖某个特定编辑器，SSH 到服务器或远程开发机也能使用。第三是便于自动化：终端本身就是脚本和 CI 流程的天然组成部分，Agent 的输入输出更容易被包装成自动化流水线。

需要说明的是，OpenCode 本身是通用 Agent，它不限制你如何组织 Skills。我们完全可以用一套约定好的目录结构和指令文件，让 OpenCode 在每次会话中自动加载并使用项目里的 Skills。这种“通用 Agent + 自定义 Skills”的组合方式，正是当前 AI 编程落地中最实用、迁移成本最低的玩法。另外，Agent Skills 的应用范围也不只在编程领域，把它用于文献整理、论文写作等方法研究任务的案例也在增多，原理是相通的，本文后续会以代码场景为主线展开。

2. 环境准备与版本说明

2.1 基础环境要求

在开始安装之前，先确认本机具备以下基础条件。操作系统方面，Windows 10/11、macOS 或主流 Linux 发行版均可；终端方面，Windows 建议使用 PowerShell 或 Windows Terminal，macOS 和 Linux 使用系统默认终端即可。因为 OpenCode 依赖 Node.js 生态，如果你计划通过 npm 安装，建议提前装好 Node.js 18 及以上版本，并用node -v确认版本号。此外，OpenCode 需要读取 Git 仓库信息，所以 Git 也是必备组件。

还需要准备一个可用的模型服务。OpenCode 自身不内置大模型，它需要调用 Anthropic Claude、OpenAI 或其他兼容接口来获得推理能力。这里要特别提醒：模型服务的接入方式和可用模型列表随时可能调整，不要在网上找一篇旧教程就照抄，而是以官方文档为准。本文的示例以常见环境为例，重点演示配置思路，具体版本请根据你的项目实际情况调整。

2.2 安装 OpenCode

OpenCode 最常见的安装方式是通过 npm 全局安装。在终端执行：

# 通过 npm 全局安装 npm install -g opencode-ai

如果你使用的是 Bun 这类更快的包管理器，也可以换成：

bun install -g opencode-ai

注意，不同版本的包名可能调整，安装前务必确认官方文档。安装完成后，可以先确认命令是否可用：

opencode --version

如果正常输出版本号，说明安装成功；如果提示“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”（Windows），或者command not found（macOS/Linux），说明 npm 全局安装目录没有加入 PATH，第 5 章会专门讲这一类问题的排查方法。

2.3 配置模型服务与 API Key

OpenCode 本身只是 Agent 运行框架，真正干活的大模型需要你提供接入凭证。常见的做法是通过环境变量注入 API Key，以 Anthropic Claude 为例：

# Linux / macOS export ANTHROPIC_API_KEY="你的密钥" # Windows PowerShell $env:ANTHROPIC_API_KEY="你的密钥"

如果你使用的是 OpenAI 兼容接口或本地模型，通常还需要配置接口地址和模型名称。不同版本支持的配置字段不一样，建议运行opencode后进入交互界面，查看自带的帮助信息，或者查阅官方文档中的配置说明。这里也要提醒一句：API Key 属于敏感信息，不要写进项目仓库，也不要粘贴到公共聊天窗口。推荐的做法是把密钥放在本地环境变量文件里，并确保该文件被.gitignore忽略。

2.4 在项目目录中启动

安装配置完成后，进入一个测试项目目录，直接运行：

cd /path/to/your-project opencode

正常情况下会进入一个交互式对话界面，Agent 会自动分析当前目录结构。你可以先问它一个简单问题测试连通性，例如“请描述一下当前项目的目录结构和主要模块”。如果模型正常回答，说明环境已经通了，可以进入后续的 Skills 实战环节。

3. Agent Skills 核心原理拆解

3.1 Skills 的本质：提示词 + 工具 + 工作流

在设计 Skills 之前，要先理解它的三层结构。最底层是提示词，它告诉模型“你是谁、要做什么、按什么标准输出”；中间层是工具，它让模型具备读写文件、执行命令、运行脚本等实际能力；最上层是工作流，它把多个步骤编排成固定流程，避免模型自由发挥。

用一个代码审查 Skill 举例：提示词部分会写明“你是一名严谨的代码审查员，重点关注异常处理、安全漏洞、可读性”；工具部分提供“读取目标文件”“运行静态检查脚本”的能力；工作流部分则规定“先扫结构，再审逻辑，最后输出问题清单”。三者缺一不可。只有提示词，输出会不稳定；只有工具，模型不知道何时该用；没有工作流，步骤顺序可能每次都不一样。

在落地时，很多团队会踩一个坑：只写了一段漂亮的提示词，就以为创建了 Skill。实际上，真正让 Skill 产生确定性价值的是脚本和工作流。把可程序化判断的部分交给脚本，把需要理解和判断的部分交给模型，这种“人机分工”才是 Skills 的核心设计思想。尤其是当项目规模变大之后，脚本负责的静态扫描能覆盖模型容易遗漏的角落，而模型负责的业务理解又是脚本做不到的，两者互补才能形成可靠的质检能力。

3.2 SKILL.md 的典型结构

虽然没有绝对统一的格式，但一个书写良好的 Skill 说明文件通常包含以下部分：name技能名称，例如code-reviewer；description技能用途，说明什么场景下使用它；适用场景明确触发条件；执行步骤按顺序列出操作流程；输出格式规定最终结果的呈现方式；约束与红线说明哪些事不能做；依赖与脚本说明需要哪些辅助脚本或第三方工具。

下面看一个最小示例：

--- name: code-reviewer description: 对目标代码文件进行结构化审查，输出问题清单和修改建议。 --- # 代码审查 Skill ## 适用场景 - 提交 Pull Request 前的自检 - 历史代码质量巡检 - 重构前后的风险确认 ## 执行步骤 1. 确定待审查文件列表 2. 运行 scripts/review.py 进行静态扫描 3. 结合扫描结果逐文件阅读业务逻辑 4. 按严重程度输出问题清单 ## 输出格式 - 严重问题：可能导致线上故障或安全风险 - 一般问题：影响可维护性或存在边界缺陷 - 建议项：风格、命名、注释等优化建议 ## 红线 - 不要在审查报告中编造不存在的风险 - 不要直接修改源码，除非用户明确要求

这里的重点是：把步骤、格式和红线写清楚，让模型在每次调用时行为一致。description 字段尤其重要，它是 Agent 决定“要不要使用这个 Skill”的依据。如果 description 写得含糊，模型就可能在不需要时误用，或者真正需要时又漏掉。

3.3 给 Skill 配一个辅助脚本

很多 Skill 只靠模型“读代码”是不够的，需要脚本做确定性扫描。比如下面这个 Python 脚本，用于扫描代码中的硬编码敏感信息和其他常见问题：

# 文件路径：skills/code-reviewer/scripts/review.py import sys from pathlib import Path def scan_file(file_path: Path) -> list[str]: """扫描单个文件，返回发现的问题列表。""" issues = [] try: lines = file_path.read_text(encoding="utf-8").splitlines() except UnicodeDecodeError: issues.append(f"{file_path}: 文件编码不是 UTF-8，建议统一编码") return issues for idx, line in enumerate(lines, 1): stripped = line.strip() low = stripped.lower() # 检查疑似硬编码密钥 if "password" in low or "secret" in low or "token" in low: if "=" in stripped and not low.startswith("#"): issues.append(f"{file_path}:{idx} 疑似硬编码敏感信息") # 检查过宽的 print 调试语句 if stripped.startswith("print("): issues.append(f"{file_path}:{idx} 疑似遗留调试输出") return issues def main(root: str) -> None: target = Path(root) files = [p for p in target.rglob("*.py") if ".venv" not in p.parts] all_issues = [] for file in files: all_issues.extend(scan_file(file)) if all_issues: print("\n".join(all_issues)) else: print("未发现明显问题") if __name__ == "__main__": root = sys.argv[1] if len(sys.argv) > 1 else "." main(root)

这个脚本的作用不是替代模型，而是给模型提供“可信的事实依据”。模型可以运行它拿到扫描结果，再结合自己对业务逻辑的理解，生成最终的审查报告。这种组合方式比单纯让模型“凭感觉审查”可靠得多，因为它把“是否有硬编码密钥”“是否遗留调试输出”这类可以确定性判断的问题，从模型的主观猜测中剥离了出来。

3.4 从 Skill 到 Agent：组合的工作方式

理解了单个 Skill 之后，再来看它如何融入 Agent。一个完整的 Agent 编码助手，通常由四层组成：基础模型负责理解和生成；Agent 运行框架，也就是 OpenCode，负责读文件、执行命令、管理多轮对话；Skill 定义是项目内可复用的能力包；最后是项目指令，告诉 Agent 项目背景、代码规范，以及需要优先使用哪些 Skill。

项目指令文件可以是一个简单的 AGENTS.md，例如：

# 项目级 Agent 指令 你是本项目的 AI 开发助手，请始终遵循以下约定： 1. 修改代码前先阅读相关文件的完整内容。 2. 涉及代码审查时，必须使用 code-reviewer Skill。 3. 涉及新增测试时，必须使用 test-writer Skill。 4. 输出代码时必须附带简要说明，不要只给代码。

当用户输入“帮我审查一下 src 目录的代码”时，OpenCode 会读取 AGENTS.md，发现审查任务应使用code-reviewerSkill，然后自动去skills/code-reviewer/读取 SKILL.md，按其中定义的流程执行。这样，每次审查的风格和质量都是稳定的。“AGENTS.md 约定 + 目录结构 + SKILL.md 定义”三者配合，就是一套不依赖特定工具、可迁移到任何 Agent 环境的轻量方案。

4. 完整实战：基于 OpenCode 搭建带 Skills 的代码质检助手

4.1 项目结构设计

接下来，我们用一个完整的示例项目把前面的原理串起来。假设有一个小型 Python 项目，里面有一些待审查的业务代码，我们要为它搭建一个“代码质检助手”，包含两个 Skills：code-reviewer负责代码审查，test-writer负责单元测试编写。项目结构如下：

quality-demo/ ├── src/ │ ├── utils