主题：本指南详细记录了在 Ubuntu 虚拟机中，安装开源 AI 编程助手 OpenCode 与 DeepSeek Harness，配置 DeepSeek API，以及探索两者通过 Vercel AI SDK 进行集成的完整过程与排错记录。
1. 初始环境准备
1.1 设置网络代理
目标：解决因网络限制导致无法访问 GitHub 或相关资源的问题。
解决方案：在终端中设置 http_proxy 和 https_proxy 环境变量，指向宿主机代理服务的地址和端口。
export http_proxy="http://192.168.66.1:7897"
export https_proxy="http://192.168.66.1:7897"
export no_proxy="localhost,127.0.0.1,::1"
疑难解答：
问题：Connection refused 错误。
解决：确认宿主机代理软件已开启“允许局域网连接（Allow LAN）”功能，并确认端口号（本例为 7897）是否正确。
2. OpenCode 安装与配置
2.1 安装 OpenCode
目标：通过官方脚本在 Ubuntu 上安装 opencode 命令行工具。
命令：
curl -fsSL https://opencode.ai/install | bash
疑难解答：
问题：安装后执行 opencode –version 提示“找不到命令 opencode”。
解决：安装脚本将可执行文件添加到了 /root/.bashrc，但当前会话未生效。执行 source ~/.bashrc 重新加载配置文件，或重新打开终端。
2.2 配置 OpenCode 使用 DeepSeek API
目标：在 OpenCode 中配置 DeepSeek 的 API Key，使其能够调用 DeepSeek 模型进行工作。
解决方案：
1. 创建配置文件 ~/.config/opencode/opencode.json。
2. 写入以下内容，并替换“你的DeepSeek_API密钥”：
{
"models": {
"deepseek": {
"api": "openai",
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "你的DeepSeek_API密钥",
"model": "deepseek-chat"
}
},
"defaultModel": "deepseek"
}
疑难解答：
问题：配置文件目录 ~/.config/opencode/ 不存在。
解决：使用 mkdir -p ~/.config/opencode 手动创建目录。
问题：是否可以使用 deepseek-v4-flash 模型？
解决：可以。deepseek-v4-flash 是 DeepSeek V4 系列中的轻量级模型，主打高性价比和高速度。将配置中的 "model" 字段改为 "deepseek-v4-flash" 即可。
3. DeepSeek Harness 安装与使用
3.1 安装与启动 Harness
目标：安装并运行 DeepSeek Harness 的 Web 界面。
命令：
npx @deepseek-ai/dsh web
疑难解答：
问题1：运行 npx 命令卡住或报错，提示 Node.js 版本过低（EBADENGINE）及 SyntaxError: The requested module 'node:util' does not provide an export named 'parseEnv'。
解决：Harness 需要 Node.js 大于等于 20 或更高版本。使用 nvm 将 Node.js 升级到 v22 LTS 版本。
nvm install 22
nvm alias default 22
问题2：重新启动 Harness 时提示 EADDRINUSE: address already in use 127.0.0.1:3080。
解决：3080 端口被之前的进程占用。使用 sudo lsof -i :3080 找到进程 PID，然后用 sudo kill -9 PID 终止该进程，再重新启动。
3.2 使 Harness 在后台持续运行
目标：让 Harness 服务在关闭终端后依然运行。
解决方案：使用 screen 或 tmux 工具。
screen -S harness 创建名为 harness 的会话
npx @deepseek-ai/dsh web 在 screen 中启动服务
Ctrl+A, 然后按 D 将 screen 会话放入后台
疑难解答：
问题：尝试使用 nohup 让 Harness 后台运行失败（进程退出）。
解决：nohup 方式在这种交互式命令中不稳定，改用 screen 成功解决。
3.3 从宿主机访问 Harness Web 界面
目标：在宿主机（Windows）的浏览器中访问虚拟机内的 Harness 服务。
背景：Harness 出于安全考虑，仅监听 127.0.0.1:3080，且不允许绑定到 0.0.0.0。
解决方案：使用 SSH 端口转发。
ssh -L 3080:127.0.0.1:3080 tzm@192.168.66.141
疑难解答：
问题：SSH 连接后浏览器仍无法访问，并出现 connect failed: Connection refused 错误。
解决：该错误说明虚拟机内的 Harness 服务未运行。重新启动 Harness（或通过 screen -r harness 重新附着），保持服务运行状态后，SSH 端口转发即生效。
4. Harness 与 OpenCode 的深度集成
4.1 集成概念说明
问题：OpenCode 和 Harness 当前是否是连接的？OpenCode 能否直接获得 Harness 的帮助？
澄清：两者目前是独立的。OpenCode 是一个直连 DeepSeek API 的终端编程助手，而 Harness 是一个独立的 AI 智能体编排平台。
目标：通过 Vercel AI SDK 将 OpenCode 作为“执行者”，接入 Harness 这个“总指挥”的框架中。这不会提升模型本身的能力，但会通过赋予其文件读写、命令执行、沙箱环境和多智能体协作能力，显著提升模型在实际项目中的任务完成率和工作质量。
4.2 集成步骤
目标：通过 Vercel AI SDK 实现 Harness 与 OpenCode 的适配。
步骤：
1. 安装必要的 NPM 包：
npm add @ai-sdk/harness @ai-sdk/harness-opencode @ai-sdk/sandbox-vercel
2. 配置环境变量：需要设置 VERCEL_OIDC_TOKEN（用于 Vercel 沙箱身份验证）和相应的 AI 模型 API Key（如 ANTHROPIC_API_KEY 或通过 AI_GATEWAY_API_KEY 配置）。
3. 编写集成代码，使用 HarnessAgent 并指定 harness: openCode 适配器。
疑难解答：
问题：VERCEL_OIDC_TOKEN 是什么？如何获取？
解决：这是与 Vercel 项目关联的 OIDC 令牌。可通过安装 vercel CLI，执行 vercel login 和 vercel link 关联项目，然后运行 vercel env pull 拉取包含该令牌的 .env.local 文件。
5. 其他常见问题
5.1 OpenCode 界面光标颜色变为红色
问题：使用 OpenCode 后，终端光标的颜色从白色变成了红色。
背景：在 ~/.bashrc 文件中未找到任何设置光标颜色的命令，因此确定非 Shell 配置问题。
解决：
1. 尝试 reset 或 tput sgr0 命令重置终端属性。
2. 检查终端仿真器（如 GNOME Terminal）的“首选项” -> “颜色”设置，确保光标颜色未被意外修改。
3. 若无效，重启终端会话（exit 后重新打开）。
4. 最后手段：重置终端配置文件 dconf reset -f /org/gnome/terminal/。
