企业官网建设流程全解析

如何快速上手 OpenCode：开源 AI 编程助手的完整指南

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

OpenCode 是一个开源的 AI Coding Agent（AI 编程助手），在终端里直接帮你读代码、改代码、跑命令，适合刚接触 AI 编程工具的你，也适合想给项目配一个本地编码助手的开发者。本文带你从安装到完成第一个真实任务。

快速上手：一条命令装好并验证

在终端执行安装脚本，脚本会自动把可执行文件放到合适目录：

curl -fsSL https://opencode.ai/install | bash

如果你更习惯包管理器，macOS 和 Linux 上brew install anomalyco/tap/opencode、Windows 上scoop install opencode都可以，效果和上面一致。

装完后先验证是否成功，再进入项目目录启动：

opencode --version

• 成功长什么样：--version打印出版本号；接着在你的项目根目录敲opencode，会进入终端交互界面，能输入自然语言、看到 AI 的回复和工具执行过程，就说明跑通了。
• 如果提示"找不到命令"，先关闭并重开终端（让 PATH 生效）；旧版（0.1.x 之前）需要卸载后再装。

核心能力实战：三个高频场景

场景一：看懂老项目——用 plan 只读模式零风险探索

• 触发情境：接手一个陌生代码库，直接让 AI 改文件很容易改坏。
• 怎么做：启动opencode后按Tab切到planagent（只读模式），再输入"帮我梳理一下这个项目的主要模块和入口"。
• 得到什么：plan 模式默认拒绝修改文件、跑 bash 前会先征求许可，你只会被动接收分析和阅读结果，不用担心代码被悄悄改动——探索阶段零风险。需要跨文件搜索时，在消息里输入@general可调用内置的通用子代理做多步查找。

场景二：写新代码——build 模式直接动手

• 触发情境：需求已经明确，比如"给登录接口加个重试逻辑"。
• 怎么做：按Tab切回默认的buildagent（完整权限），用一句话说清需求，AI 会自己读取相关文件、编辑代码、必要时执行命令。
• 得到什么：文件被直接修改并给出说明，改动过程可见可停；配合终端里的AGENTS.md（项目指令文件），团队可以统一约定编码规范，AI 每次都会遵守——少踩风格不一致的坑。

场景三：跨文件修改——用 @ 引用精准给上下文

• 触发情境：想让 AI 改的东西依赖多个文件，比如同时调整组件和样式。
• 怎么做：在消息里用 @ 语法引用文件，支持整文件和行范围：

@src/components/Header.tsx @src/styles/global.css#L12-18

• 得到什么：AI 直接读到指定文件和行范围的真实内容，回答不再"凭猜"，多文件联动修改的报错率明显更低。
• 如果你常用 VS Code，OpenCode 也提供编辑器扩展，能自动把当前打开的文件和选区变成 @ 引用插入提示词，效果见下图。

实战：三步完成一个真实任务

以"弄清报错来源并修掉"为例，全程可执行：

1. 启动并切模式：在项目根目录运行opencode，按Tab切到 plan 模式，输入"搜索项目里这个报错是从哪抛出的"，让 AI 只读地定位文件和调用链。
2. 下达修改指令：定位清楚后按Tab切回 build 模式，把定位到的文件用 @ 引用带上，说清"修复这里的空指针并在函数入口加判空"。
3. 验证结果：让 AI 跑一下相关测试命令，终端里能亲眼看到测试通过；改动不满意可以直接对 AI 说"回滚上一处修改"，它有 git 快照能力可以撤销。

结果说明：从"看到一个报错"到"修复并验证通过"，你只需要两次自然语言输入，读代码、改代码、跑测试都由 AI 完成，你负责判断和验收——整个过程通常比你手动翻代码快得多。

常见坑与解法

下一步建议

• 先跑一遍只读流程：用一个你不太熟的项目，纯 plan 模式提问一周，熟悉它的回答边界再放心切到 build。
• 给项目写一份AGENTS.md：把团队规范、常用命令写进去，所有协作者的 AI 行为会更一致；贡献相关说明可看 CONTRIBUTING.md。
• 想深入源码：核心会话与工具逻辑在 packages/opencode/src/，会话运行时设计文档见 CONTEXT.md。

从安装到跑通第一个任务只需要十来分钟，先把上面三步走完，你就能感受到"对话即开发"的效率差异了。

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode