OpenCode on 丸子有记, 记录生活、分享技术，专注于运维架构、运维开发(devops)。

Openspec进行存量项目开发

wzdushu@gmail.com (wanzi) — Mon, 30 Mar 2026 22:10:42 +0800

最近在使用opencode配合openspec对已有项目，进行二次开发，遇到一些坑记录一下：

一、初始化项目:

首先，在项目根目录运行CLI 命令来创建 OpenSpec 所需的基础目录结构。

# openspec init 
Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0
Detected tool directories: OpenCode (pre-selected for first-time setup)
✔ Select tools to set up (24 available) OpenCode
▌ OpenSpec structure created
✔ Setup complete for OpenCode

OpenSpec Setup Complete

Created: OpenCode
4 skills and 4 commands in .opencode/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

Restart your IDE for slash commands to take effect.

另外，为了更深入理解openspec，建议把所有openspec的扩展功能都开启了，后续opencode或者claude code里直接使用，修改完需要重启opencode或者claude code：

# openspec config profile

Current profile settings
  Delivery: both
  Workflows: 11 selected (custom)
  Delivery = where workflows are installed (skills, commands, or both)
  Workflows = which actions are available (propose, explore, apply, etc.)

✔ What do you want to configure? Delivery and workflows
✔ Delivery mode (how workflows are installed): Both (skills + commands) [current]
? Select workflows to make available:
❯[x] Propose change
 [x] Explore ideas
 [x] New change
 [x] Continue change
 [x] Apply tasks
 [x] Fast-forward
 [x] Sync specs
 [x] Archive change
 [x] Bulk archive
 [x] Verify change
 [x] Onboard

Create proposal, design, and tasks from a request
Space to toggle, Enter to confirm

二、使用 explore 分析现有代码

这是最关键的一步，你需要使用 /opsx:explore 命令来引导 AI 分析你的代码库，并生成初始规范。

操作方法：在 AI 对话框中输入：

/opsx:explore 分析当前项目的架构和核心业务逻辑，并生成相应的规范文档

作用： AI 会扫描你的代码文件，理解现有的技术栈、目录结构和功能模块，然后尝试为你生成一份初始的 proposal.md 或 specs 文档，作为后续开发的基线。

三、补全配置

我们都知道openspec的核心思想是“先立规矩，再动手”，通过规范驱动开发（Spec-Driven Development, SDD）来解决 AI 在大型项目中容易出现的“上下文丢失”和“代码混乱”问题。

因此，为了让 AI 更精准地理解你的项目，你可以手动编辑openspec“宪法”文件 openspec/config.yaml

内容：添加你的技术栈（如 React, Python, Go）、编码约定、领域知识等。这能帮助 AI 在后续生成代码时更符合你的项目风格。

我这里直接在opencode里让agent直接输出了：

添加本项目的技术栈、编码约定、领域知识等到openspec/config.yaml 文件，方便后续openspec更精准地理解项目

四、开始增量开发

完成上述步骤后，就可以按照标准的 OpenSpec 流程进行开发了：

1.创建变更：使用 /opsx:ff <功能名>（快速模式）或 /opsx:new <功能名>（完整模式）开始一个新功能的开发。

2.定义增量规范：在生成的 specs/ 文件中描述本次变更（新增/修改/删除）。

3.执行与归档：使用 /opsx:apply 生成代码，验证无误后使用 /opsx:archive 归档。归档时，增量规范会自动合并到主规范中。再次为之前提供的不准确信息表示歉意，希望这次的流程能帮助你顺利接入 OpenSpec。

举例: 这里给自己的技术工具箱，新增一个文本翻译工具：

/opsx:new 增加一个文本翻译工具，背后调用大模型，默认使用minimax API接口参考这里https://platform.minimaxi.com/docs/guides/text-generation，也支持调用glm的模型，API接口参考https://docs.bigmodel.cn/cn/guide/develop/claude/introduction；翻译功能类似https://fanyi.baidu.com/mtpe-individual/transText#/

最终项目目录结构如下:

openspec
├── changes
│   └── archive
│       └── 2026-03-30-add-text-translator
├── config.yaml
└── specs
    └── text-translator
        └── spec.md

五、功能跑不通怎么办？

如果你是在 AI 生成代码后进行验证，发现代码跑不通或不符合预期，验证失败 (/opsx:verify)

不要直接修改代码：在 OpenSpec 的工作流中，代码是规范的产物。如果代码错了，通常是因为“规范”写得不够清楚，或者 AI 理解错了。
正确的修复步骤：

1. 修改规范 (spec.md)：

打开 openspec/changes/新功能1/specs/…/spec.md，把你的修正意见写进去。

例如：在场景描述中增加“必须处理网络超时的情况”。

2. 重新应用 (/opsx:apply)：

告诉 AI：“我已经更新了规范，请重新运行 /opsx:apply”。AI 会根据新的规范重新生成代码，覆盖之前的错误代码。

3. 再次验证：

再次运行 /opsx:verify 确认问题已解决。

六、修改代码后如何确保与spec.md同步？

在 OpenSpec 的工作流中，代码是规范的产物。如果你手动修改了代码，但 spec.md 没有同步，就会导致“文档与代码脱节”，下次 AI 再根据 spec.md 生成代码时，你的手动修改就会被覆盖或产生冲突。

为了确保两者同步，请根据你修改代码的时机和原因，选择以下三种策略之一：

1. 最佳策略：先改文档，再生成代码 (Spec-First)

这是 OpenSpec 最推荐的方式。如果你发现代码有问题（比如逻辑不对、参数错误），不要直接去改代码文件。

操作步骤： 1.1 打开 openspec/changes/…/spec.md。 1.2 修改对应的需求描述或场景（Scenario）。 1.3 运行 /opsx:apply。 1.4 结果：AI 会根据新的文档重新生成代码，自动覆盖旧的实现。这是保持同步最彻底的方法。

2. 补救策略：代码已改，反向同步文档 (Reverse Sync)

如果你习惯先快速修改代码（比如修个 Bug 或微调样式），改完后必须立刻把变更“回填”到文档中。

操作步骤：
1. 保存代码：确保你的代码修改已保存。
2. 运行验证：在 AI 对话框中输入 /opsx:verify。
  - AI 会对比你的新代码和旧 spec.md。
  - 它会发现不一致（例如：“代码中 Redis 过期时间是 600 秒，但文档写的是 300 秒”）。
3. 接受建议：让 AI 根据代码更新 spec.md。
4. 结果：文档被更新以匹配你的代码，两者重新达成一致。

3. 归档时的强制同步 (/opsx:archive)

当你完成功能开发准备归档时，OpenSpec 会强制检查同步状态。

机制：
- 当你运行 /opsx:archive 时，OpenSpec 会将当前变更目录下的 spec.md 合并到项目的全局规范库（openspec/specs/）中。
- 注意：如果你手动改了代码但没更新 spec.md，归档后，你的代码逻辑将永远无法在文档中体现。下次有人（或 AI）查看归档文档时，看到的将是过时的逻辑。

七、归档后发现spec.md文档落后于代码

要避免这种情况，你需要建立一套“防御性”的工作习惯。

1. 养成“Verify -> Archive”的肌肉记忆

这是最直接、最有效的日常习惯。永远不要把 /opsx:archive 当作开发结束后的唯一动作。

错误习惯：改代码 -> 测试通过 -> /opsx:archive
正确习惯：改代码 -> /opsx:verify -> (若有差异则同步) -> 测试通过 -> /opsx:archive

具体操作：在你手动修改代码后，归档前，必须运行 /opsx:verify（或者在 AI 对话框中让 AI 检查）。

告诉 AI：“我手动修改了 xxx.ts，请对比 spec.md，如果有不一致，请帮我更新 spec.md。”
只有当 AI 确认“代码与规范一致”后，再执行归档。

2. 利用 Git 钩子（Pre-commit Hook）强制检查

如果你担心自己偶尔会忘记，可以利用 Git 的机制进行强制拦截。这是团队协作中推荐的做法。

你可以在项目的 .git/hooks/pre-commit 文件中加入检查逻辑。虽然 OpenSpec 没有直接提供这个钩子，但你可以写一个简单的脚本：

脚本逻辑思路：

检测是否有代码文件（如 .ts, .java, .py）被修改。
检测对应的 openspec/changes/ 下的文档是否也被修改。
如果代码变了但文档没变 -> 拦截提交，并提示：“检测到代码变更但 Spec 文档未更新，请先运行 verify 或更新文档！”

#!/bin/sh
# .git/hooks/pre-commit

# 检查暂存区是否有代码变更
CODE_CHANGES=$(git diff --cached --name-only | grep -E "\.(ts|js|java|py)$" | wc -l)
# 检查暂存区是否有 Spec 变更
SPEC_CHANGES=$(git diff --cached --name-only | grep "openspec/" | wc -l)

if [ "$CODE_CHANGES" -gt 0 ] && [ "$SPEC_CHANGES" -eq 0 ]; then
  echo "⚠️  警告：检测到代码变更，但未发现 OpenSpec 文档变更！"
  echo "⚠️  请确保你的代码逻辑已同步到 spec.md，或运行 /opsx:verify。"
  echo "如果想强制提交，请使用 --no-verify (不推荐)"
  exit 1
fi

exit 0

另外，对于现代项目，建议使用专门的工具来管理钩子，这样可以将配置写入代码库，全员共享。

Python 项目 / 通用：使用 pre-commit 框架。
- 配置 .pre-commit-config.yaml，定义检查规则（如 flake8, black, detect-secrets）。
- 运行 pre-commit install 即可自动配置钩子。
前端/Node 项目：使用 Husky。
- 它可以轻松在 package.json 中定义钩子逻辑，无需手动处理 shell 脚本权限。
Golang和Rust 项目:
- 使用lefthook：https://github.com/evilmartians/lefthook ，通用工具，go开发并行执行，速度飞快

lefthook.yml通用配置模版:

# Lefthook 配置文件
# 支持多语言混合项目 (Polyglot/Monorepo)

# 全局设置
min_version: 1.4.0

# pre-commit 钩子：在 git commit 时触发
pre-commit:
  parallel: true # 核心优化：并行执行所有检查，极大提升速度
  commands:
    
    # ==========================================
    # 1. 前端 (JavaScript / TypeScript)
    # ==========================================
    frontend-lint:
      glob: "*.{js,ts,jsx,tsx,vue}"
      run: npx eslint {staged_files} --fix
      # 注意：如果项目没有 package.json，Lefthook 会自动跳过或报错，视配置而定

    frontend-format:
      glob: "*.{js,ts,jsx,tsx,vue,css,scss,json}"
      run: npx prettier --write {staged_files}

    # ==========================================
    # 2. Go (Golang)
    # ==========================================
    go-fmt:
      glob: "*.go"
      # gofmt -w 会直接修改文件，确保暂存区更新
      run: gofmt -w {staged_files}
    
    go-lint:
      glob: "*.go"
      # 假设你安装了 golangci-lint，这是 Go 社区标准 lint 工具
      run: golangci-lint run {staged_files}

    # ==========================================
    # 3. Rust
    # ==========================================
    rust-fmt:
      glob: "*.rs"
      run: cargo fmt -- {staged_files}

    rust-check:
      glob: "*.rs"
      # 使用 clippy 进行深度检查
      run: cargo clippy -- -D warnings

    # ==========================================
    # 4. Python
    # ==========================================
    python-lint:
      glob: "*.py"
      # 这里以 flake8 为例，也可以换成 black --check 或 pylint
      run: flake8 {staged_files}

    python-format:
      glob: "*.py"
      # 如果使用 black 格式化
      run: black {staged_files}

    # ==========================================
    # 5. Java / Kotlin
    # ==========================================
    # Java 通常依赖构建工具 (Maven/Gradle) 或特定的 linter (如 checkstyle)
    # 这里演示调用 Gradle 的检查任务，它会自动处理所有 Java 文件
    java-check:
      glob: "*.java"
      # 注意：Gradle 任务通常比较慢，且不支持只检查部分文件，
      # 建议只在 pre-push 中运行全量检查，或者使用 spotless 等支持增量检查的插件
      run: ./gradlew checkstyleMain checkstyleTest --quiet

    # ==========================================

3. 事后补救

创建一个新的变更：命名为 sync-logic-with-code 或 fix-docs-consistency。
让 AI 逆向工程：在这个新变更中，告诉 AI：“当前的 xxx 功能代码逻辑已经变更，但 spec.md 还是旧的。请以当前代码为准，重写/更新 spec.md。”
归档这个“文档修复”：运行 /opsx:apply（此时 AI 会生成更新后的文档）和 /opsx:archive。

结果：你的主规范库（openspec/specs/）会被这次新的归档更新，重新与代码保持一致。虽然历史归档里留下了“文档落后”的痕迹，但最新的主规范是准确的。

写在最后，在用OpenSpec开发项目过程中，一定要谨记OpenSpec核心原则：

文档（Spec）是源头，代码是结果。遇到问题，先修文档，再让 AI 重写代码。

Claude Code使用最佳实践

wzdushu@gmail.com (wanzi) — Thu, 05 Feb 2026 10:30:00 +0800

Claude Code是Anthropic公司推出的官方AI编程工具，可以读取代码库、编辑文件、运行命令，并与开发工具集成。它在复杂推理和代码理解方面表现优异，是当前最强大的AI编程工具之一。

Claude Code详细介绍

什么是Claude Code

Claude Code是一个由AI驱动的代理编码助手，可以帮助开发者构建功能、修复错误和自动化开发任务。它理解整个代码库，可以跨多个文件和工具工作以完成任务。

核心优势：

强大的代码理解和推理能力
支持终端、VS Code、JetBrains等多种界面
MCP（Model Context Protocol）扩展支持
多代理协作功能
完整的Git工作流集成
支持Claude全系列模型

Claude Code安装

macOS / Linux（推荐）

`1`	`curl -fsSL https://claude.ai/install.sh \| bash`

Windows PowerShell

`1`	`irm https://claude.ai/install.ps1 \| iex`

Windows CMD

`1`	`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`

Homebrew

`1`	`brew install --cask claude-code`

WinGet（Windows）

`1`	`winget install Anthropic.ClaudeCode`

VS Code扩展

在VS Code扩展商店搜索"Claude Code"并安装。

快速开始

# 进入项目目录
cd your-project

# 启动Claude Code
claude

# 直接指定任务
claude "帮我创建一个用户登录功能"

Claude Code基础使用

基本使用技巧

1. 任务分解策略

不要一次性让AI完成复杂任务：

# 低效 ❌
claude "帮我写一个完整的电商系统"

# 高效 ✅
claude "帮我设计用户数据表结构"
claude "基于这个结构写用户注册API"
claude "添加登录验证逻辑"

2. 提供完整上下文

# 缺少信息 ❌
claude "这个代码报错"

# 完整信息 ✅
claude "我在用Flask写一个Web服务，登录接口返回500错误。
错误信息：TypeError: Cannot read property 'name' of undefined
堆栈显示发生在app.py第45行。
帮我分析原因并修复。"

3. 使用工具调用

Claude Code可以执行多种操作：

# 读取文件
Read file: src/main.py

# 搜索代码
Grep pattern: "def login" path: src/

# 执行命令
Bash command: python -m pytest

# 写入文件
Write file: src/utils.py

# 批量操作
Glob pattern: "**/*.py"

Claude Code模型选择

Claude Code支持多种Claude模型，可根据任务复杂度选择：

模型	能力	速度	适用场景
Claude Opus 4.6	最高	较慢	复杂架构设计、深度重构
Claude Sonnet 4.6	高	中等	日常开发、代码生成
Claude Haiku 4.5	中等	快	快速补全、简单任务

1
2

# 切换模型
/model claude-sonnet-4-6

Claude Code进阶功能

MCP服务器集成

MCP（Model Context Protocol）可以连接Claude Code到外部工具和数据源：

# 在配置文件中设置MCP服务器
# ~/.claude/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "allowedDirectories": ["~/projects"]
    }
  }
}

CLAUDE.md文件

在项目根目录创建CLAUDE.md文件，Claude Code会在每个会话开始时读取：

# 项目说明

## 代码标准
- 使用TypeScript strict模式
- 遵循Airbnb ESLint配置

## 架构决策
- 使用依赖注入模式
- 所有API调用必须包含错误处理

## 首选库
- 状态管理：Zustand
- HTTP客户端：Ky

自定义命令（Skills）

创建可复用的命令模板：

# 创建 /review-pr 命令
# ~/.claude/commands/review-pr.md
# 审查Pull Request

请审查这个PR：
1. 检查代码质量和风格一致性
2. 查找潜在的安全问题
3. 评估测试覆盖是否充分
4. 验证文档是否更新

@pr-url

Hooks配置

在操作前后自动执行shell命令：

# ~/.claude/config.json
{
  "hooks": {
    "PostEdit": [
      {
        "match": "*.ts",
        "command": "npx eslint --fix {file}"
      }
    ]
  }
}

计划任务

# 按计划运行Claude
claude /schedule

# 自动化早晨PR审查
claude /loop 8h /pr review

# 自动化夜间CI失败分析
claude /schedule "0 22 * * *" "分析今天的CI失败"

多代理协作

# 启动多个代理并行工作
claude "启动一个团队来处理这个功能：
- 代理1：前端组件开发
- 代理2：后端API开发
- 代理3：测试编写
协调它们的工作并合并结果"

Git与工作流集成

Git工作流

# 提交更改
claude "commit my changes with a descriptive message"

# 创建分支
claude "创建一个feature分支来实现用户注册功能"

# 分析变更影响
claude "分析当前分支相比main有哪些变更"

代码审查流程

# 1. 让Claude阅读代码
claude "请阅读src目录下所有Python文件，了解项目结构"

# 2. 提出具体审查要求
claude "针对src/api/v1/users.py文件：
- 检查输入验证是否完整
- 查找潜在的安全漏洞
- 评估错误处理是否合理"

# 3. 要求修复建议
claude "针对发现的问题，请逐个提供修复方案"

调试技巧

# 提供错误信息
claude "运行 'python app.py' 时出现以下错误：
TypeError: Cannot read property 'name' of undefined
堆栈信息显示错误发生在第45行。
帮我定位问题并修复。"

# 提供复现步骤
claude "1. 运行 'npm run dev'
2. 访问 http://localhost:3000
3. 点击登录按钮
4. 输入正确凭据后点击提交
期望：登录成功并跳转
实际：页面卡住无响应
控制台显示：Pending POST /api/login"

国产大模型配置

Claude Code原生使用Claude模型，但也支持配置其他国产模型作为替代。

GLM4系列（智谱AI）

智谱GLM系列在中文理解和代码生成方面表现出色。

GLM4.7特点：

超长上下文支持
强大的中文理解能力
代码生成能力强
Tool Calling支持

配置方法：

# 通过MCP配置GLM
# ~/.claude/config.json
{
  "mcpServers": {
    "glm": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-zhipu-api-key",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4"
      }
    }
  }
}

Kimi K2.5（月之暗面）

Kimi K2.5在长上下文和多模态方面有独特优势。

K2.5特点：

256K超长上下文
多模态理解
专业代码生成，编程能力可比肩Claude

定价：

输入：¥4.00/MTok
输出：¥21.00/MTok
缓存命中：¥0.70/MTok

配置方法：

# 通过MCP配置Kimi
# ~/.claude/config.json
{
  "mcpServers": {
    "kimi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-kimi-api-key",
        "OPENAI_BASE_URL": "https://api.moonshot.cn/v1"
      }
    }
  }
}

MiniMax M2.5

MiniMax M2.5专为编程设计，主打快速响应。

M2.5特点：

高吞吐量、低延迟
专为生产环境优化
编程和Agent能力SOTA
性价比高

配置方法：

# 通过MCP配置MiniMax
# ~/.claude/config.json
{
  "mcpServers": {
    "minimax": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-minimax-api-key",
        "OPENAI_BASE_URL": "https://api.minimax.chat/v1"
      }
    }
  }
}

与其他AI编程工具对比

Cursor

Cursor是最受欢迎的AI原生IDE之一，被超过一半的Fortune 500企业使用。

与Claude Code对比：

Cursor是完整的AI编辑器，Claude Code是CLI工具
Cursor支持GPT-5、Claude、Gemini等多种模型
Claude Code的推理能力更强，适合复杂任务
Cursor的AI深度集成度更高

Cursor核心功能：

Composer 2：一句话完成多文件修改
Tab智能补全
BugBot自动代码审查
代码库全局理解

Trae

Trae是一款自适应AI IDE，主打本地优先和隐私保护。

与Claude Code对比：

Trae中文界面友好，免费额度充足
Claude Code功能更强大，适合复杂项目
Trae适合国内用户快速上手

Trae核心功能：

Builder模式：对话创建文件
中文界面
隐私保护（不二次训练数据）
MCP协议支持

OpenCode

OpenCode是一款轻量级终端AI编程工具，基于Go语言开发。

与Claude Code对比：

OpenCode更轻量，适合简单任务
Claude Code功能更全面
OpenCode支持更多模型提供商

OpenCode支持模型：

OpenAI: GPT-4.1、GPT-4.5、GPT-4o、O1、O3
Anthropic: Claude 4 Sonnet/Opus、Claude 3.5/3.7 Sonnet
Google: Gemini 2.5、2.5 Flash、2.0 Flash

对比总结

特性	Claude Code	Cursor	Trae	OpenCode
类型	CLI+插件	AI IDE	AI IDE	CLI工具
模型	Claude	多模型	多模型	多模型
推理能力	最强	强	中等	强
中文支持	一般	一般	优秀	一般
学习曲线	中等	低	低	中等
免费额度	有限	有限	充足	依赖API

选择建议：

复杂重构和深度任务 → Claude Code
日常开发和IDE体验 → Cursor
国内用户快速上手 → Trae
轻量级终端任务 → OpenCode

常见问题

Q: Claude Code需要付费吗？

A: Claude Code本身免费，但需要Claude API密钥。新用户有免费额度，订阅用户额度更充足。

Q: 国产模型能否替代Claude？

A: 对于日常编程任务，国产模型已经接近Claude水平。复杂推理任务Claude仍有优势。国产模型价格更便宜。

Q: AI写的代码可以直接用吗？

A: 不可以！AI代码必须经过自己理解、本地测试、代码审查、确认安全后才能使用。

Q: 如何选择Claude模型？

A: 简单任务用Haiku，日常开发用Sonnet，复杂任务用Opus。

总结

Claude Code是当前最强大的AI编程工具之一，特别适合：

复杂的代码理解和重构
多文件批量操作
深度调试和问题分析
需要强大推理能力的任务

通过配置MCP，Claude Code也可以使用国产模型（GLM4、Kimi K2.5、Minimax M2.5）作为替代。根据任务复杂度和预算选择合适的工具和模型。

OpenCode最佳实践：国产大模型编程助手

wzdushu@gmail.com (wanzi) — Thu, 15 Jan 2026 21:22:42 +0800

OpenCode概述

什么是OpenCode

OpenCode是一款开源的AI编程助手，基于VSCode构建，具有以下特点：

开源免费：完全开源，可自建部署
模型灵活：支持多种LLM后端
本地优先：保护代码隐私
高度可定制：可扩展和定制

核心功能

功能	说明
代码补全	实时代码建议（单行/多行）
代码聊天	针对代码进行问答
代码生成	根据描述生成代码
代码解释	解释选中代码的功能
重构建议	提供重构和优化建议
Bug修复	智能修复代码错误

一、OpenCode安装配置

系统要求

操作系统:
  - Windows 10/11
  - macOS 11+
  - Linux (Ubuntu 20.04+, CentOS 8+)

硬件要求:
  - CPU: 4核心+
  - 内存: 8GB+
  - 硬盘: 2GB可用空间

软件依赖:
  - Node.js 16+ (如果从源码构建)
  - Git

安装步骤

方法1：使用预构建版本（推荐）

# 1. 下载OpenCode
# 访问 https://github.com/opencode-org/opencode/releases
# 下载对应平台的安装包

# Linux/macOS
wget https://github.com/opencode-org/opencode/releases/latest/download/opencv-linux-x64.tar.gz
tar -xzf opencv-linux-x64.tar.gz
cd opencv
./opencode

# macOS (使用Homebrew Cask)
brew install --cask opencode

# Windows
# 下载 opencv-setup.exe 并运行安装

# 2. 启动OpenCode
# 首次启动会显示欢迎页面

方法2：从源码构建

# 1. 克隆仓库
git clone https://github.com/opencode-org/opencode.git
cd opencv

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 运行
npm run electron

基础配置

settings.json配置

{
  // OpenCode配置
  "opencode.modelProvider": "openai",
  "opencode.apiKey": "your-api-key",
  "opencode.model": "gpt-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 2048,

  // 代码补全配置
  "opencode.autocomplete.enabled": true,
  "opencode.autocomplete.mode": "inline",
  "opencode.autocomplete.debounce": 150,

  // 代码聊天配置
  "opencode.chat.enabled": true,
  "opencode.chat.contextLength": 10,

  // 隐私配置
  "opencode.telemetry.enabled": false,
  "opencode.anonymousUsageId": false,

  // 快捷键配置
  "opencode.suggestInline": "Ctrl+Enter",
  "opencode.openChat": "Ctrl+Shift+C",
  "opencode.explainCode": "Ctrl+Shift+E"
}

二、OpenCode能做什么

1. 智能代码补全

# 单行补全
def calculate_discount(price, discount_rate):
    return price * (1 - discount_

# OpenCode自动补全:
# rate)

# 多行补全
# 输入注释:
# 创建一个函数，用于计算斐波那契数列的第n项

# OpenCode生成完整函数:
def fibonacci(n):
    """
    计算斐波那契数列的第n项

    Args:
        n (int): 要计算的项数

    Returns:
        int: 第n项的值
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fibonacci(n-1) + fibonacci(n-2)

2. 代码解释

# 选中复杂代码，OpenCode提供解释

def merge_sort(arr):
    if len(arr) <= 1:
        return arr

    mid = len(arr) // 2
    left = merge_sort(arr[:mid])
    right = merge_sort(arr[mid:])

    return merge(left, right)

# OpenCode解释:
# 这是一个归并排序算法的实现。
# 1. 基础情况：如果数组长度<=1，直接返回
# 2. 分治：将数组分成两半，递归排序
# 3. 合并：将两个已排序的数组合并
# 时间复杂度: O(n log n)
# 空间复杂度: O(n)

3. 代码重构

# 原始代码
def process_user(user):
    if user is not None:
        if user.get("name") is not None:
            if user.get("age") is not None and user["age"] >= 18:
                return True
    return False

# OpenCode重构建议:
def process_user(user):
    """
    检查用户是否为有效的成年人

    Args:
        user (dict): 用户信息字典

    Returns:
        bool: 用户是否有效
    """
    if not user:
        return False

    name = user.get("name")
    age = user.get("age")

    return bool(name and age >= 18)

4. Bug检测与修复

# 有bug的代码
def divide_numbers(a, b):
    result = a / b
    return result

# 调用
print(divide_numbers(10, 0))  # ZeroDivisionError

# OpenCode检测并修复:
def divide_numbers(a, b):
    """
    安全地除两个数

    Args:
        a (float): 被除数
        b (float): 除数

    Returns:
        float: 除法结果

    Raises:
        ValueError: 当除数为0时
    """
    if b == 0:
        raise ValueError("除数不能为零")

    return a / b

5. 单元测试生成

# 原始函数
def add(a, b):
    return a + b

# OpenCode生成单元测试:
import unittest

class TestAdd(unittest.TestCase):
    def test_add_positive_numbers(self):
        """测试正数相加"""
        self.assertEqual(add(2, 3), 5)

    def test_add_negative_numbers(self):
        """测试负数相加"""
        self.assertEqual(add(-2, -3), -5)

    def test_add_mixed_numbers(self):
        """测试正负数相加"""
        self.assertEqual(add(2, -3), -1)

    def test_add_zero(self):
        """测试加零"""
        self.assertEqual(add(5, 0), 5)

    def test_add_floats(self):
        """测试浮点数相加"""
        self.assertAlmostEqual(add(2.5, 3.1), 5.6, places=1)

if __name__ == '__main__':
    unittest.main()

三、oh-my-opencode介绍

什么是oh-my-opencode

oh-my-opencode是OpenCode的增强配置管理工具，提供：

预设配置：针对不同场景优化
模型切换：快速切换不同LLM
快捷键绑定：预定义快捷键
主题定制：自定义外观

安装oh-my-opencode

# 1. 克隆仓库
git clone https://github.com/opencode-org/oh-my-opencode.git ~/.oh-my-opencode

# 2. 安装
cd ~/.oh-my-opencode
./install.sh

# 3. 重启OpenCode

预设配置

# 查看可用预设
oh-my-opencode list

# 应用预设
oh-my-opencode apply python-developer
oh-my-opencode apply go-developer
oh-my-opencode apply fullstack-developer

# 创建自定义预设
oh-my-opencode create my-preset --template python-developer

四、国产大模型集成

支持的国产大模型

模型	提供商	特点	推荐场景
GLM-4	智谱AI	中文理解强	中文开发
Minimax M2.5	MiniMax	代码能力强	代码生成
Kimi K2.5	Moonshot	长文本	文档理解
Qwen3.5	阿里云	多语言能力	全栈开发

1. GLM-4配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
  "opencode.apiKey": "your-glm-api-key",
  "opencode.model": "glm-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 4096,
  "opencode.contextLength": 8192,

  // 请求头配置
  "opencode.customHeaders": {
    "Authorization": "Bearer your-glm-api-key"
  },

  // 响应格式
  "opencode.responseFormat": {
    "type": "text"
  }
}

2. Minimax M2.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.minimax.chat/v1/text/chatcompletion_v2",
  "opencode.apiKey": "your-minimax-api-key",
  "opencode.model": "abab5.5-chat",
  "opencode.temperature": 0.7,
  "opencode.maxTokens": 2048,

  // Minimax特定参数
  "opencode.customParams": {
    "group": "chat_group_name",
    "role_setting": "你是一个专业的编程助手",
    "tokens_to_generate": 2048,
    "temperature": 0.7
  }
}

3. Kimi K2.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.moonshot.cn/v1/chat/completions",
  "opencode.apiKey": "your-kimi-api-key",
  "opencode.model": "moonshot-v1-8k",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 8192,

  // Kimi长上下文配置
  "opencode.contextWindow": 32000,
  "opencode.includeContext": "full"
}

4. Qwen3.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
  "opencode.apiKey": "your-qwen-api-key",
  "opencode.model": "qwen-plus",
  "opencode.temperature": 0.5,
  "opencode.maxTokens": 6000,

  // Qwen特定参数
  "opencode.customParams": {
    "top_p": 0.8,
    "enable_search": false
  }
}

多模型配置切换

# 创建模型配置文件
~/.opencode/models/
├── glm-4.json
├── minimax-m2.5.json
├── kimi-k2.5.json
└── qwen3.5.json

# 快速切换模型
opencode model switch glm-4
opencode model switch minimax-m2.5
opencode model switch kimi-k2.5
opencode model switch qwen3.5

# 设置默认模型
opencode model default qwen3.5

五、最佳实践

1. Prompt工程

好的Prompt特征

好的Prompt应该：
1. 明确目标 - 清楚说明要做什么
2. 提供上下文 - 给出相关背景信息
3. 指定格式 - 说明期望的输出格式
4. 给出示例 - 提供期望结果的示例
5. 设定约束 - 明确限制条件

示例Prompt

# 差的Prompt
写一个排序函数

# 好的Prompt
请用Python编写一个快速排序函数，要求：
1. 输入：整数列表
2. 输出：排序后的列表
3. 处理边界情况：空列表、单元素列表
4. 包含完整的文档字符串
5. 添加类型注解
6. 包含单元测试示例

请遵循Google Python代码风格指南

2. 上下文管理

# 提供足够的上下文信息

# 不好的示例 - 缺少上下文
# 帮我优化这个函数
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

# 好的示例 - 提供上下文
# 优化以下函数，要求：
# 场景：处理大量传感器数据（百万级）
# 当前性能：处理10万条数据需要5秒
# 目标：处理10万条数据<1秒
# 约束：数据必须保持顺序
# 语言：Python
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

3. 安全最佳实践

安全实践:
  API密钥管理:
    - 使用环境变量存储API密钥
    - 定期轮换密钥
    - 不要提交到代码仓库

  代码审查:
    - AI生成的代码需要人工审查
    - 特别注意安全漏洞
    - 测试边界情况

  敏感信息:
    - 不要让AI访问敏感代码
    - 使用脱敏数据
    - 配置忽略规则

4. 性能优化

{
  // 性能优化配置
  "opencode.cache.enabled": true,
  "opencode.cache.size": "1GB",
  "opencode.cache.ttl": 86400,

  // 请求优化
  "opencode.batchRequests": true,
  "opencode.requestTimeout": 30000,
  "opencode.retryAttempts": 3,

  // 响应缓存
  "opencode.responseCache.enabled": true,
  "opencode.responseCache.maxSize": 500
}

5. 团队协作

团队协作:
  配置共享:
    - 创建团队配置文件
    - 统一模型选择
    - 统一Prompt模板

  版本控制:
    # .opencoderc
    {
      "model": "qwen3.5",
      "temperature": 0.3,
      "presets": {
        "python": "python-dev-preset",
        "go": "go-dev-preset"
      }
    }

  知识库:
    - 维护团队Prompt库
    - 分享最佳实践
    - 定期培训

六、常见问题

Q1: API密钥如何配置

# 方法1：环境变量（推荐）
export OPENCODE_API_KEY="your-api-key"
export OPENCODE_API_ENDPOINT="https://api.example.com"

# 方法2：配置文件
~/.opencode/config.json
{
  "apiKey": "your-api-key",
  "apiEndpoint": "https://api.example.com"
}

# 方法3：OpenCode设置界面
# Settings > OpenCode > API Key

Q2: 如何提高生成质量

{
  // 提高生成质量的配置
  "opencode.temperature": 0.3,        // 降低随机性
  "opencode.topP": 0.9,               // 控制多样性
  "opencode.frequencyPenalty": 0.5,   // 减少重复
  "opencode.presencePenalty": 0.3,    // 鼓励新话题

  // 增加上下文
  "opencode.contextLines": 50,        // 增加上下行数
  "opencode.includeFileHeader": true,  // 包含文件头
  "opencode.includeImports": true     // 包含导入
}

Q3: 离线使用方案

离线方案:
  本地模型:
    - 使用Ollama运行本地模型
    - 支持Llama、CodeLlama等
    - 配置本地API端点

  配置:
    opencode.apiEndpoint: "http://localhost:11434"
    opencode.model: "codellama:13b"

总结

OpenCode作为开源AI编程助手，具有以下优势：

开源免费：无订阅费用
模型灵活：支持多种LLM后端
国产模型：集成GLM、Minimax、Kimi、Qwen
可定制：高度可配置
隐私保护：本地部署选项

配合oh-my-opencode和国产大模型，可以构建高效的AI辅助开发环境。