OpenCode Primer
一本由社区维护的开源 AI 编码代理 OpenCode 完全指南，覆盖从首次安装到自定义代理、技能、插件、MCP 与无头 CI 的全部要点。
仓库为纯文档型产品，SECURITY.md 声明无运行时依赖、无构建步骤，示例插件仅用 Node 内置模块；CI workflow 限定 contents: read，最小权限良好。README 明确警告插件可运行任意代码、共享会话的隐私风险、勿自动批准破坏性操作。扣分点：实际插件源码未随证据提供，secret blocker 等声明无法静态核实；仓库自身无回滚机制，undo 等仅是对上游工具的描述。
README 自称'每条事实对照当前版本核实'并有版本徽章与 'last reviewed' 徽章，CI 含 markdownlint 与链接检查，支持一致性。扣分点：README 在文件中途截断，多处文档引用（docs/*.md）未提供，无法确认全部内部一致性。
面向初学者与高级用户的路径表清晰，'When OpenCode isn't the right tool' 表明确列出能力边界（非补全工具、依赖模型质量、TUI 在慢 SSH 下的退化、插件风险、免费模型限时），这在同类文档中少见。扣分点：触发精度与环境适配主要复述上游工具行为，非本仓库独立设计。
信息架构优秀：路径选择表、mermaid 决策图、五个扩展点对比表、兼容性锚点。LICENSE 为完整 MIT 且与徽章一致。已知限制表格详尽。扣分点：无 CHANGELOG 文件（仅徽章日期与锚点）；示例文件本身（agents/commands/plugins/skills）未随证据提供，examples_and_faq 只能给中等分；维护者仅一名社区成员，无 CODEOWNERS 或治理说明。
输出可直接复制使用：安装命令、配置片段、命令/技能/插件模板齐全，语言简洁带结构化表格。扣分点：作为第三方社区指南，其边际价值取决于上游官方文档的滞后程度，README 自身也承认'文档会滞后'；成本收益对纯文档产品只能给中等分。
声明普遍带出处链接与核实日期（如定价快照'verified 2026-07-05'、PR #18186、第三方报道），事实与观点基本区分（警告、建议用引用块标注）。扣分点：静态审查无法独立核实'最多星标''8M 月活用户'及 2026 年定价等断言，无仓库内测试或对照证据，交叉验证只能给 1 分。
- 本仓库仅为文档指南，未提供示例插件源码供静态审查，secret blocker 等安全声明未经核实，复制使用前请自行阅读 .opencode/plugins/ 下的实际代码。
- README 中 2026 年的定价、用户量、竞品动态等断言无法交叉验证，引用前请对照 opencode.ai 官方文档。
- 文档明确说明会随上游版本滞后，安装命令（curl | bash）来自第三方转述，执行前请核对官方来源。
- 发布者为未验证的社区个人，无治理与责任承诺，遇到事实性安全误导需自行判断风险。
这个 Agent 能做什么，适合哪些场景？
OpenCode Primer（GitHub: wesammustafa/opencode-primer）是一份面向开发者的 OpenCode 使用教程仓库，采用 MIT 许可证，内容对照 v1.17.13 版本逐项核实。它不是 OpenCode 本身，而是详解其安装、认证、模型接入（直连厂商、Zen 按量网关、Go 订阅、本地模型）、提示工程、TUI 快捷键、无头 CLI 与 CI 运行模式的英文手册。仓库还自带一套可直接使用的 .opencode/ 示例目录，包括自定义代理、斜杠命令、JS 插件（如 protect-secrets.js 和 audit-log.js）、SKILL.md 技能和 AGENTS.md 项目规则。深度内容拆分在 docs/ 下的专题文件中（agents.md、plugins.md、mcp.md、zen.md 等），并附 FAQ、迁移指南和更新日志。读者应将其当作学习与配置参考，而非可部署的软件产品。
该仓库提供三类内容。其一，教程文档：讲解 OpenCode 的安装（curl 安装脚本、npm、brew、scoop、Docker 等多种方式）、auth login 认证、/init 生成 AGENTS.md、plan/build 双代理工作流、@file 与 !shell 提示语法、leader 键与主题配置、opencode run / serve / web 无头运行模式，以及 opencode github install 等 CI 集成。其二，可运行的配置示例：.opencode/agents/（Markdown+YAML 代理定义）、.opencode/commands/（/review、/pr、/test、/optimize 四个命令）、.opencode/plugins/（审计日志和密钥保护插件）、.opencode/skills/git-release/（SKILL.md 技能）和 opencode.（含 MCP 服务器配置示例）。其三，参考资料：specialized-agents/ 目录提供后端、前端、安全审查、技术主管等可直接复制的专家代理提示词，mcp-servers/ 目录提供 Playwright、Context7、Sentry、Grep 四个 MCP 服务器的接入教程。
- 初次接触 OpenCode 的开发者，想按 15 分钟路径完成安装、认证并发出第一条提示
- 从 Claude Code 迁移的团队，需要了解 AGENTS.md/CLAUDE.md 回退、命令与技能路径差异及 frontmatter 字段变化
- 希望控制成本的用户，参考 Zen 模型价格表和'廉价探索者/强力执行者'多模型搭配模式选型
- 需要为 AI 会话加安全护栏的工程师，直接复制 protect-secrets.js 和 audit-log.js 插件使用
- 搭建无人值守 CI 流水线的运维人员，按 Headless & CI 章节配置 opencode run --format 、GitHub Actions 或 GitLab CI
- 想接入外部工具（浏览器自动化、库文档、错误追踪、代码搜索）的开发者，参考 mcp-servers/ 下的 Playwright、Context7、Sentry、Grep 实战教程
这个 Agent 有哪些优点和局限？
- 内容对照具体版本（v1.17.13）逐项核实并标注最后审阅日期，减少教程过时风险
- 仓库自带的 .opencode/ 示例目录可直接复制使用，含安全插件、审计日志、四个斜杠命令和 git-release 技能等即用资产
- 覆盖面完整：从安装、模型选型（含 Zen 价格快照）、提示工程到无头 CI 和 MCP 集成，一条路径走通
- 明确标注自身为社区维护、与 OpenCode 团队无关，并始终链接官方文档作为权威来源，可信边界清晰
- 它是文档而非软件，不能替代 OpenCode 本体；实际功能取决于你另行安装和付费的 OpenCode 及其底层模型
- 文档承认会滞后于快速迭代的二进制版本，文中功能、价格（如 Zen 定价 2026-07-05 快照）可能已变化
- 部分建议依赖特定生态：如已不可用 Claude Pro/Max 订阅登录、插件需 JS/TS 与 Bun 环境、免费 Zen 模型为限时提供不宜用于生产
- 指南面向 OpenCode 工作流（AGENTS.md、.opencode/ 目录约定），迁移到其他代理工具时示例不可直接复用
如何安装或部署这个 Agent？
本仓库是纯文档与配置示例，无需安装运行时。获取方式：git clone https://github.com/wesammustafa/opencode-primer.git，或在 GitHub 上直接阅读。若要实际运行文中示例，需先安装 OpenCode：curl -fsSL https://opencode.ai/install | bash（或 npm i -g opencode-ai@latest / brew install anomalyco/tap/opencode），然后运行 opencode auth login 完成至少一个 LLM 提供商的 API 密钥认证——这是使用任何示例的前提，本仓库本身不提供模型服务。
如何使用这个 Agent？
按 README 的'选择路径'表阅读：新手从 What is OpenCode → Setup → Prompt Engineering 开始；已有用户直接跳到 Custom Commands、Agent Skills、Plugins、MCP 各章（每章约 20 分钟）；配置与 CI 需求看 Agents、Headless & CI、Models & Providers。深度内容在 docs/ 子目录（如 docs/agents.md、docs/plugins.md、docs/workflows.md、docs/reference/cli.md）。要试用配置示例，把仓库中的 .opencode/agents/*.md、.opencode/commands/*.md、.opencode/skills/ 复制到自己项目的对应目录，或从 specialized-agents/ 挑选专家提示词放入 .opencode/agents/<name>.md；MCP 服务器按 opencode. 的 mcp 段配置，可用 opencode mcp add 命令管理。
这个 Agent 与同类方案有什么区别？
README 将 OpenCode 本体与 Claude Code、Codex CLI、Cursor、Aider 等编码代理做了定位对比（如需要单厂商打磨产品选 Claude Code/Codex CLI，深度绑定 VS Code 选 Cursor/Copilot，想要可通读的小型 Python 工具选 Aider），并指出 OpenCode 以开放性和多提供商灵活性换取打磨度。本指南则专注于 OpenCode 生态的教程，同类替代主要是官方文档 opencode.ai/docs。