Ai 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 重写代码。

Kaku使用最佳实践

wzdushu@gmail.com (wanzi) — Sat, 21 Mar 2026 10:30:00 +0800

Kaku是一款macOS平台的终端模拟器，内置AI助手功能，集成了Claude Code、Codex、Gemini CLI、Copilot CLI、Kimi Code等多种AI工具。本文详细介绍Kaku的安装配置与最佳实践，帮助开发者充分发挥AI辅助编程的潜力。

Kaku工具介绍

什么是Kaku

Kaku是一款macOS平台的终端模拟器，它不仅提供了强大的终端功能，还内置了AI助手能力，可以帮助开发者快速完成命令诊断、代码解释、AI对话等多种任务。

核心特性：

内置AI助手：集成多种AI Coding工具
智能目录跳转：z命令快速切换目录
分屏支持：支持垂直/水平分屏
内置Git工具：集成Lazygit
文件管理器：内置Yazi文件管理器
语法高亮：实时命令验证和着色
国产模型支持：支持MiniMax等国产大模型

支持的AI工具

Kaku支持多种主流AI Coding工具：

AI工具	说明
Claude Code	Anthropic官方CLI工具
Codex	OpenAI代码模型
Gemini CLI	Google Gemini CLI
Copilot CLI	GitHub Copilot CLI
Kimi Code	月之暗面Kimi代码助手
Factory Droid	安卓开发AI助手
OpenClaw	开源AI工具

支持的AI提供商

提供商	Base URL	支持模型
VivGrid（默认）	`https://api.vivgrid.com/v1`	DeepSeek-V3.2
MiniMax	`https://api.minimax.io/v1`	MiniMax-M2.7, M2.7-highspeed, M2.5, M2.5-highspeed
OpenAI	`https://api.openai.com/v1`	GPT系列（自动检测）
Custom	手动设置	手动设置

Kaku安装配置

安装方法

方式一：下载DMG（推荐）

访问 https://github.com/tw93/Kaku/releases/latest 下载最新DMG
打开DMG文件
拖拽Kaku到应用程序文件夹

方式二：Homebrew安装

`1`	`brew install tw93/tap/kakuku`

首次配置

首次启动Kaku时，程序会自动设置shell环境。配置命令：

命令	功能
`kaku`	查看所有可用命令
`kaku ai`	AI设置
`kaku config`	打开设置TUI
`kaku doctor`	诊断面板
`kaku update`	更新
`kaku reset`	重置
`kaku init`	初始化

配置文件

Kaku配置文件位于：~/.config/kaku/kaku.lua

配置文件完全兼容WezTerm Lua API，可以进行深度定制。

AI设置详解

配置AI提供商

运行以下命令进入AI设置：

kaku ai

操作步骤：

选择提供商（Provider）
输入API Key
选择模型

手动配置

编辑 ~/.config/kaku/assistant.toml 文件：

1
2
3

# 企业代理配置
[assistant]
custom_headers = { "X-Custom-Header" = "value" }

MiniMax配置

MiniMax是国内可用的AI提供商，M2.7模型速度快，适合日常使用：

1
2

# 通过 kaku ai 选择 MiniMax 提供商
# 或手动编辑配置文件

支持的MiniMax模型：

MiniMax-M2.7（标准版）
MiniMax-M2.7-highspeed（高速版）
MiniMax-M2.5
MiniMax-M2.5-highspeed

Kaku Assistant功能

Kaku Assistant是什么

Kaku Assistant是Kaku内置的AI助手功能，可以：

自动分析失败的命令并提供修复建议
智能解释错误信息
提供操作指导

启用/禁用Assistant

# 通过 TUI 界面
kaku config

# 或在配置文件中设置
# ~/.config/kaku/kaku.lua
local kaku = require("kaku")
kaku.assistant.enabled = true

使用Assistant

当命令执行失败时，Assistant会自动分析并提供建议。按提示操作即可应用修复方案。

快捷键大全

全局操作

操作	快捷键
切换全局窗口	`Cmd + Opt + Ctrl + K`
新建标签页	`Cmd + T`
新建窗口	`Cmd + N`
关闭标签页/窗格	`Cmd + W`
打开设置面板	`Cmd + ,`
清屏	`Cmd + K`

标签页导航

操作	快捷键
切换到左/右侧标签	`Cmd + Shift + [` / `]`
切换到指定编号标签	`Cmd + 1-9`
重新打开关闭的标签	`Cmd + Shift + T`
重命名标签	双击标签标题

窗格操作

操作	快捷键
导航窗格	`Cmd + Opt + 方向键`
垂直分屏	`Cmd + D`
水平分屏	`Cmd + Shift + D`
切换分屏方向	`Cmd + Shift + S`
缩放/取消缩放窗格	`Cmd + Shift + Enter`
调整窗格大小	`Cmd + Ctrl + 方向键`

AI功能快捷键

操作	快捷键
AI面板	`Cmd + Shift + A`
诊断面板	`Ctrl + Shift + L`
应用AI建议	`Cmd + Shift + E`

Git和文件管理

操作	快捷键
打开Lazygit	`Cmd + Shift + G`
打开Yazi	`Cmd + Shift + Y` 或按 `y`

显示调整

操作	快捷键
字体放大	`Cmd + +`
字体缩小	`Cmd + -`
字体重置	`Cmd + 0`

Shell导航功能

智能目录跳转（z命令）

Kaku内置了智能目录跳转功能，会学习用户的常用目录：

# 快速跳转到常用目录（会自动学习）
z project

# 列出匹配的目录
z -l proj

# 跳转到最近访问的目录
z -t

其他Shell增强功能

zsh-completions：扩展命令补全
语法高亮：实时命令验证和着色
自动建议：类似Fish shell的历史补全

CLI工具集成

kaku init安装的工具

运行 kaku init 时会自动安装以下CLI工具：

工具	说明
Starship	快速提示符（显示目录、git分支、包版本）
Delta	git diff语法高亮分页器
Lazygit	Git可视化界面
Yazi	终端文件管理器

kaku cli命令

# 查看帮助
kaku cli --help

# 分割窗格
kaku cli split-pane

# 分割并运行命令
kaku cli split-pane -- bash -c "echo Hello"

进阶配置

配置文件示例

编辑 ~/.config/kaku/kaku.lua：

local kaku = require("kaku")

-- 窗口透明度
config.window_background_opacity = 0.8
config.macos_window_background_blur = 20

-- 工作目录继承
config.window_inherit_working_directory = true
config.tab_inherit_working_directory = true
config.split_pane_inherit_working_directory = true

-- 禁用复制选中
config.copy_on_select = false

-- 颜色覆盖
config.color_overrides = {
  ['#6E6E6E'] = '#3A3942',
}

内置Shell配置

如果使用Fish shell，可以在配置中启用Fish集成：

`1`	`config.fish_integration = true`

故障排除

kaku命令找不到

如果终端中找不到 kaku 命令，运行：

1
2
3

/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l
kaku doctor

诊断问题

# 运行诊断面板
kaku doctor

# 检查配置
kaku config

# 更新Kaku
kaku update

# 重置配置
kaku reset

企业代理配置

如果需要通过企业代理访问AI服务，编辑 ~/.config/kaku/assistant.toml：

[assistant]
custom_headers = {
    "Proxy-Authorization" = "Bearer your-token"
}

与Claude Code的区别

特性	Kaku	Claude Code
类型	终端模拟器	CLI工具
平台	macOS专属	跨平台
AI集成	多种AI工具	Claude模型
使用方式	内置面板	独立对话
配置复杂度	中（Lua配置）	低
国产模型	MiniMax支持	需配置

最佳实践总结

1. 日常开发工作流

1. 使用 Cmd + Opt + Ctrl + K 打开Kaku
2. 使用 z 命令快速切换项目目录
3. 使用内置Git工具（Cmd+Shift+G）管理代码
4. 命令失败时使用AI面板（Cmd+Shift+A）诊断问题
5. 使用分屏功能同时查看多个终端

2. AI功能使用

日常命令问题：使用Kaku Assistant自动诊断
复杂代码问题：使用Claude Code面板（Cmd+Shift+A）
需要Kimi：通过kaku ai切换到Kimi Code

3. 快捷键习惯

建议将常用快捷键设为肌肉记忆：

Cmd + Shift + A - 打开AI面板
Cmd + Shift + G - 打开Git工具
z <dir> - 快速跳转目录

4. 配置个性化

根据个人习惯定制 kaku.lua：

调整透明度
配置颜色主题
设置工作目录继承规则

Kaku作为一款专为macOS设计的终端模拟器，其内置的AI功能和丰富的快捷键支持使其成为开发者提升效率的利器。掌握好配置和使用技巧，能显著提升日常开发体验。

选择SDD工具：OpenSpec 还是 Spec-Kit

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

在前文《什么是SDD》中我们了解了规范驱动开发的重要性，本文将深入对比两款主流SDD工具——OpenSpec和Spec-Kit，帮助开发者根据自身需求做出选择。

OpenSpec与Spec-Kit概览

OpenSpec简介

OpenSpec 是由Fission AI开发的规格驱动开发(SDD)框架，专门为AI编程助手打造。

项目地址：https://github.com/Fission-AI/OpenSpec

核心特点：

轻量级规格层，让人类和AI在写代码前对齐
每个变更有独立文件夹，包含提案、规格、设计和任务
支持20+种AI助手通过斜杠命令集成
灵活迭代，无刚性阶段门控
完整的变更生命周期管理

Spec-Kit简介

Spec-Kit 是由GitHub开发的规格驱动开发开源工具包。

项目地址：https://github.com/github/spec-kit

核心特点：

将规格文档变为可执行规范，直接生成可工作代码
支持多种AI代理：Claude Code、Copilot、Gemini CLI、Codex、Cursor、Windsurf等
完整的工作流程：Constitution → Specify → Plan → Tasks → Implement
丰富的扩展生态：Jira集成、Azure DevOps集成、代码审查等
支持Greenfield和Brownfield项目

安装与配置

OpenSpec安装

前置要求：Node.js 20.19.0或更高版本

# npm安装
npm install -g @fission-ai/openspec@latest

# 也支持pnpm、yarn、bun和nix
pnpm add -g @fission-ai/openspec

初始化项目

# 在项目目录初始化
openspec init

# 选择工作流配置
openspec config profile

# 刷新AI指导
openspec update

禁用遥测（可选）

1
2
3

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

Spec-Kit安装

前置要求：Python环境（推荐使用uv）

# 持久化安装（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 一次性使用
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# 升级
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

初始化项目

# 创建新项目
specify init <PROJECT_NAME>

# 在现有项目中初始化
specify init . --ai claude

# 指定AI代理初始化
specify init --here --ai claude

# 检查环境
specify check

核心功能对比

基础功能

功能	OpenSpec	Spec-Kit
实现语言	Node.js	Python
CLI工具	openspec	specify
AI代理支持	20+种	10+种
变更结构	提案+规格+设计+任务	Constitution+Specify+Plan+Tasks
状态管理	完整生命周期	阶段式流程
扩展生态	基础	丰富（Jira、Azure DevOps等）
并行执行	基础支持	工作包模式

OpenSpec斜杠命令

命令	功能
`/opsx:propose "想法"`	创建新提案
`/opsx:new`	创建新变更
`/opsx:continue`	继续变更
`/opsx:apply`	执行任务
`/opsx:ff`	快进完成
`/opsx:verify`	验证变更
`/opsx:sync`	同步状态
`/opsx:archive`	归档已完成变更
`/opsx:bulk-archive`	批量归档
`/opsx:onboard`	新成员入门

Spec-Kit斜杠命令

命令	功能
`/speckit.constitution`	建立项目治理原则
`/speckit.specify`	定义功能需求
`/speckit.plan`	技术规划
`/speckit.tasks`	分解任务
`/speckit.implement`	执行实现
`/speckit.clarify`	澄清模糊需求
`/speckit.analyze`	一致性分析
`/speckit.checklist`	质量检查

工作流程对比

OpenSpec工作流

OpenSpec以变更为核心，每个变更有独立的文件夹结构：

变更文件夹结构：
├── proposal.md      # 提案描述
├── spec.md          # 规格说明
├── design.md        # 技术设计
├── tasks.md         # 任务清单
└── artifacts/       # 产出物

开发循环

1. 提出想法
   /opsx:propose "添加用户认证功能"

2. 创建变更
   /opsx:new
   # 创建变更文件夹

3. 编写规格
   编辑 spec.md

4. 技术设计
   编辑 design.md

5. 执行任务
   /opsx:apply

6. 验证完成
   /opsx:verify

7. 归档
   /opsx:archive

Spec-Kit工作流

Spec-Kit采用阶段式流程，强调规范文档的可执行性：

工作流程：
Constitution → Specify → Plan → Tasks → Implement

开发循环

1. 初始化项目
   specify init . --ai claude

2. 建立原则
   /speckit.constitution
   # 定义项目治理规范

3. 定义规格
   /speckit.specify
   # 描述要构建的功能

4. 制定计划
   /speckit.plan
   # 提供技术栈和架构

5. 分解任务
   /speckit.tasks
   # 生成可执行任务列表

6. 执行实现
   /speckit.implement
   # 按计划实现功能

AI代理支持对比

OpenSpec支持

Claude Code ✅
GitHub Copilot ✅
Gemini CLI ✅
以及20+种其他AI助手

Spec-Kit支持

AI代理	支持	备注
Claude Code	✅
GitHub Copilot	✅
Gemini CLI	✅
Codex CLI	✅	需 `--ai-skills` 参数
Cursor	✅
Windsurf	✅
Qoder CLI	✅
Kilo Code	✅
Generic	✅	需指定 `--ai-commands-dir`

Spec-Kit扩展生态

Spec-Kit拥有丰富的扩展和预设：

扩展（Extensions）

扩展	功能
AI-Driven Engineering (AIDE)	7步结构化工作流
Jira Integration	与Jira同步任务
Azure DevOps Integration	与Azure DevOps同步
Review Extension	代码审查
Verify Extension	规格验证
Spec Sync	检测规格与实现偏差

预设（Presets）

预设	功能
AIDE In-Place Migration	技术迁移预设
Pirate Speak	海盗风格输出

适用场景对比

选择OpenSpec的场景

需要完整变更追踪的项目
重视提案→规格→设计→任务流程的团队
多AI工具混合使用的环境
喜欢灵活迭代而非严格阶段的项目
需要频繁变更审查的团队

选择Spec-Kit的场景

企业环境，需要Jira/Azure DevOps集成
需要代码审查和质量门控
重视规格文档可执行性的团队
需要技术迁移支持的场景
使用Claude Code、Copilot等主流AI代理

总结对比

┌─────────────────────────────────────────────────────────┐
│                      SDD工具对比                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   OpenSpec                │         Spec-Kit             │
│   ─────────               │         ─────────             │
│   • Node.js实现          │         • Python实现          │
│   • 变更驱动             │         • 规格可执行          │
│   • 20+ AI助手支持       │         • 10+ AI助手支持      │
│   • 灵活迭代             │         • 阶段式流程           │
│   • 完整变更生命周期     │         • 丰富扩展生态         │
│                          │         • 企业集成支持         │
│                                                         │
│   适合:                    │         适合:                  │
│   • 变更追踪重要          │         • 企业环境              │
│   • 灵活迭代流程          │         • 质量门控              │
│   • 多AI工具混用          │         • 规格验证              │
│                                                         │
└─────────────────────────────────────────────────────────┘

最终建议

选择OpenSpec如果：

需要完整的提案→规格→设计→任务流程
重视变更的历史追踪和审查
喜欢灵活迭代的工作方式
使用多种AI编程工具

选择Spec-Kit如果：

需要与企业工具（Jira、Azure DevOps）集成
重视代码审查和质量验证
需要规格与实现一致性检查
使用Claude Code、Copilot等主流AI代理

可以结合使用：两个工具可以互补——使用OpenSpec进行快速变更探索，使用Spec-Kit进行企业级规范管理。

什么是SDD？为什么AI编程工具里需要用到它

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

在AI编程工具日益普及的今天，一个重要的概念正在改变我们与AI协作编写代码的方式——SDD（Specification-Driven Development，规范驱动开发）。本文将深入解析SDD的核心理念，以及为什么主流AI编程工具都选择支持SDD模式。

什么是SDD

SDD的定义

Specification-Driven Development（规范驱动开发） 是一种软件开发方法论，它强调在编写代码之前先编写清晰、精确的规范说明，然后严格按照规范来实现代码。

核心原则：

规范先行：代码实现之前必须先编写Spec
精确描述：用形式化或半形式化的语言描述需求
双向追踪：规范与代码保持一致，可相互验证
迭代完善：从简单规范开始，逐步细化完善

SDD vs 传统开发模式

维度	传统开发	SDD
起点	需求文档或口头描述	精确编写的Spec文件
灵活性	需求边改边写	规范确认后再实现
验证方式	手动测试为主	规范可作为测试用例
AI协作	AI自由发挥空间大	AI按规范执行
变更处理	需求变更成本高	规范变更驱动代码修改

为什么AI编程需要SDD

AI编程的挑战

1. 上下文理解偏差

AI模型虽然强大，但并非能完全理解人类的模糊描述。传统开发中的需求往往是：

"实现一个用户登录功能，要有基本的验证"

这种模糊描述会导致AI生成代码与预期不符。

2. 生成代码质量不稳定

没有规范约束时，AI可能：

遗漏边界情况处理
忽略安全考量
API设计风格不统一
实现与项目已有代码风格不一致

3. 迭代维护困难

AI生成的代码在没有规范的情况下：

难以判断是否满足需求
修改时不知道影响范围
新人接手难以理解设计意图

SDD如何解决这些问题

规范提供精确意图

# 传统需求描述
"实现一个用户登录功能"

# SDD规范描述
## 功能需求
1. 支持用户名/邮箱 + 密码登录
2. 登录成功后生成JWT token，有效期24小时
3. 密码错误3次后锁定账户15分钟
4. 登录接口需要防暴力破解（限流：同一IP 5分钟内最多10次）

## 接口规范
- POST /api/v1/auth/login
- Request: { "username": string, "password": string }
- Response: { "token": string, "expiresIn": 86400 }

## 错误处理
- 400: 参数校验失败
- 401: 用户名或密码错误
- 423: 账户已被锁定

## 安全要求
- 密码存储使用bcrypt
- 返回的token不包含敏感信息

规范即测试用例

SDD规范可以直接或通过工具转换为：

API的Mock测试
单元测试用例
集成测试场景
验收标准

SDD在AI编程中的价值

1. 减少幻觉（Hallucination）

AI在有明确规范约束时，更容易生成符合预期的代码，而不是"创造"一些不存在的功能。

2. 提高代码一致性

规范定义了统一的：

API设计风格
代码组织结构
命名规范
错误处理模式

3. 便于审查和协作

规范的清晰性使得：

代码审查有据可依
team member可以并行工作
新成员快速理解项目

4. 支持渐进式开发

SDD支持从简单规范开始，逐步扩展：

# v1.0 最小可用版本
## AuthService
- login(username, password): Promise<User>

# v1.1 增加token支持
## AuthService
- login(username, password): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

# v1.2 增加第三方登录
## AuthService
- login(username, password): Promise<LoginResult>
- loginWithOAuth(provider, code): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

SDD的核心组件

1. Spec文件结构

project/
├── SPEC.md              # 主规范文件
├── api/
│   └── openapi.yaml     # API规范
├── models/
│   └── schema.md        # 数据模型规范
└── specs/
    ├── auth.md          # 认证模块规范
    ├── user.md          # 用户模块规范
    └── ...

2. 规范编写原则

FIRRN原则：

Factual（事实性）：描述系统实际行为，不是愿望清单
Independent（独立性）：每个规范模块独立描述一个功能
Readable（可读性）：规范要易于理解和维护
Realistic（可行性）：规范要可实现、可测试
Necessary（必要性）：每个需求都是必要的

3. 规范与代码的对应

## UserService.getUserById

### 描述
根据用户ID获取用户信息

### 输入
- userId: string (必填，用户ID)

### 输出
- User对象或null

### 行为
1. 验证userId格式
2. 从数据库查询用户
3. 返回用户信息（密码字段排除）

### 错误
- InvalidUserIdError: userId格式无效

对应代码：

async getUserById(userId: string): Promise<User | null> {
  // 1. 验证userId格式
  if (!isValidUserId(userId)) {
    throw new InvalidUserIdError(userId);
  }

  // 2. 从数据库查询用户
  const user = await this.db.users.findOne({
    where: { id: userId },
    attributes: { exclude: ['password'] }
  });

  // 3. 返回用户信息
  return user;
}

SDD工作流程

完整开发流程

┌─────────────────────────────────────────────────────────┐
│  1. 需求分析                                             │
│     - 收集业务需求                                        │
│     - 识别关键用例                                        │
│     - 确定约束条件                                        │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  2. 编写Spec（规范）                                      │
│     - 编写SPEC.md                                        │
│     - 定义API接口                                         │
│     - 描述数据模型                                         │
│     - 明确边界条件和错误处理                                │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  3. 评审与确认                                            │
│     - 技术评审                                            │
│     - 业务确认                                            │
│     - 达成共识后锁定规范                                    │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  4. AI生成代码                                            │
│     - 基于Spec生成代码                                     │
│     - 生成单元测试                                         │
│     - 生成API文档                                          │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  5. 验证与迭代                                            │
│     - 代码是否符合Spec                                     │
│     - 测试覆盖是否完整                                      │
│     - 发现问题时更新Spec或修复代码                            │
└─────────────────────────────────────────────────────────┘

Spec评审检查清单

功能描述清晰，无歧义
输入输出明确定义
边界条件已覆盖
错误处理完整
API设计一致
数据模型合理
安全考虑周全
性能要求明确

SDD工具生态

主流SDD工具

工具	特点	适用场景
Spec-Kit	专为AI编程设计，CLI工具	Claude Code集成
OpenSpec	开放标准，社区驱动	跨工具通用
Stopify	简单Markdown格式	轻量级项目
Docusaurus	文档驱动	文档完善项目

Claude Code与SDD

Claude Code天然支持SDD工作流：

# 1. 创建项目并编写规范
mkdir my-project && cd my-project
claude "初始化一个Node.js REST API项目，创建SPEC.md规范文件"

# 2. 基于规范实现
claude "根据SPEC.md实现用户认证模块"

# 3. 验证实现是否符合规范
claude "检查当前实现是否完全符合SPEC.md中的定义"

# 4. 规范更新时同步修改
# 编辑SPEC.md添加新功能
claude "根据更新后的SPEC.md重构相关代码"

SDD最佳实践

规范编写技巧

1. 使用结构化格式

## 功能名称

### 描述
简短描述功能做什么

### 输入
- param1: type (描述)
- param2: type (描述)

### 输出
- type: 描述

### 行为
1. 步骤1
2. 步骤2

### 错误
- ErrorType: 描述

2. 使用具体例子

### 登录成功示例
输入: { "username": "user@example.com", "password": "correct_password" }
输出: { "token": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 86400 }

### 密码错误示例
输入: { "username": "user@example.com", "password": "wrong_password" }
输出: 401 { "error": "INVALID_CREDENTIALS", "message": "用户名或密码错误" }

3. 定义清晰的验收标准

## 验收标准
- [ ] 用户名格式验证正确
- [ ] 密码强度验证正确
- [ ] 登录成功返回有效token
- [ ] 错误次数统计正确
- [ ] 账户锁定功能正常
- [ ] Token过期处理正确

常见陷阱

1. 规范过于详细

# 不好的做法：规定代码实现细节
### 实现
使用for循环遍历数组，在第5行调用helper函数

# 好的做法：只描述行为
### 实现
按指定顺序处理数据项

2. 规范与实现脱节

每次代码更新都同步更新Spec
Spec变更必须经过评审
禁止"代码实现了但Spec没更新"

3. 过度抽象

规范要具体可执行，不是泛泛而谈的架构设计。

总结

SDD的核心价值

明确性：消除模糊需求，减少沟通成本
可验证性：规范可直接转化为测试用例
可维护性：代码和文档始终保持一致
AI友好：为AI提供清晰执行目标

SDD适用场景

场景	SDD适合度	原因
AI辅助编程	非常适合	AI需要明确指令
复杂业务系统	适合	减少需求理解偏差
快速原型	一般	规范可能成为负担
个人小项目	可选	过度设计可能浪费
多人协作项目	非常适合	统一理解和标准

学习建议

从小项目开始：选择一个简单项目练习SDD工作流
使用好用的工具：推荐从Spec-Kit或简单Markdown开始
保持规范更新：规范不是一次性的，需要持续维护
与AI协作：让AI帮你生成规范初稿，你来审核和完善

SDD不是银弹，但它为AI编程提供了一个可靠的框架。随着AI编程工具的不断进化，SDD将成为高效人机协作的重要基础。

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辅助开发环境。

利用ollama和open-webui玩转开源大模型

wzdushu@gmail.com (wanzi) — Tue, 30 Apr 2024 18:10:42 +0800

对于大模型的使用也1年多了，从最开始的chatgbt3.5/4到现在的国产大模型，开源大模型也越来越强，比如Llama,SD等,今天介绍两个使用了很久的工具ollama和open-webui。

Ollama

Ollama是一个开源的深度学习框架，专为本地机器上便捷部署和运行大型语言模型（LLM）而设计，它提供了一套完整的深度学习工具链，包括数据预处理、模型构建、训练、评估和部署等功能。

项目地址：https://github.com/ollama/ollama

ollama主要特点：

本地部署与运行：Ollama的主要目标之一是简化在Docker容器中部署大型语言模型的过程。这使得非专业用户也能方便地管理和运行这些复杂的模型。
轻量级与可扩展性：作为一个轻量级框架，Ollama保持了较小的资源占用，同时具备良好的可扩展性。这允许用户根据项目的规模和硬件条件调整配置。
API支持：Ollama提供了一个简洁的API，使开发者能够轻松创建、运行和管理大型语言模型实例。这降低了与模型交互的技术门槛。
预构建模型库：Ollama包含了一系列预先训练好的大型语言模型，用户可以直接选用这些模型应用于自己的应用程序，无需从头训练或自行寻找模型源。
模型导入与定制：（1）从GGUF导入：支持从特定平台（如GGUF）导入已有的大型语言模型。（2）从PyTorch或Safetensors导入：兼容这两种深度学习框架，允许用户将基于这些框架训练的模型集成到Ollama中。（3）自定义提示：允许用户为模型添加或修改提示，以引导模型生成特定类型或风格的文本输出。
跨平台支持：提供了针对macOS、Windows（预览版）、Linux以及Docker的安装指南，确保用户能在多种操作系统环境下顺利部署和使用Ollama。
命令行工具与环境变量：命令行启动：通过命令ollamaserve或其别名serve、start可以启动Ollama服务。
环境变量配置：如OLLAMA_HOST，用于指定服务绑定的主机地址和端口。用户可以根据需要进行修改。

此外，Ollama还提供了丰富的API接口、社区和文档支持，使其成为一个适合开发者和个人用户在本地运行和管理大型语言模型的强大工具。

ollama快速安装

linux安装ollama命令：

`1`	`curl -fsSL https://ollama.com/install.sh \| sh`

ollama基本命令

ollama pull llama3 # 拉取一个大模型
ollama run llama3  # 直接运行一个大模型，
ollama rm llama3   # 移除本地llama3大模型
ollama list   # 列出本地大模型

对话llama3中文版本：

# ollama pull wangshenzhi/llama3-8b-chinese-chat-ollama-q8:latest
# ollama run wangshenzhi/llama3-8b-chinese-chat-ollama-q8:latest
>>> 你是谁？
我是Llama3-8B中文聊天机器人，由ORPO对齐算法在Llama3-8B-Instruct与中文-英语混合数据上微调。我的开发者是王慎执（中文名）。我是一个乐于助人、尊重他人、诚实可靠的助手，致力于为您提供
安全准确的信息和回答，同时促进有意义的对话。

>>> 如何微调大模型llama3以及微调大模型会用到哪些工具，请详细介绍一下.
LLaMA 3是由OpenAI开发的一种强大的文本生成模型，基于transformer架构。它在各种自然语言处理（NLP）任务中表现出色，比如文本分类、机器翻译和对话系统。微调大型预训练模型，如LLaMA 3，可
以显著提高它们的性能，并使其适应特定任务或领域。

微调过程涉及在预训练模型上进行少量额外训练，以fine-tune它以更好地适应新的目标数据集。这个过程可以通过添加新数据、调整超参数或改变优化算法来实现。微调的主要目的是使模型能够从具有
特定结构和语境的任务中学习，并在这些任务上表现出色。

LLaMA 3的微调通常涉及以下步骤：

1. **数据准备**：收集并预处理用于微调的新数据。数据应该与目标任务相关，具体来说是聊天机器人任务。
2. **模型选择**：选择一个适合任务的架构，例如LLaMA 3。可以根据数据集和任务要求进行调整，如增加或减少层数、隐藏单元数量等。
3. **超参数设置**：调整微调过程中的超参数，如学习率、批量大小和训练迭代次数，以优化模型性能。
4. **训练**：使用新数据集对模型进行微调。通常在GPU上进行，这可以显著提高微调速度。

微调的好处包括：

* **任务特定的性能**：微调可以显著提高模型在目标任务上的表现，尤其是当目标数据集具有独特结构和语境时。
* **更好的泛化能力**：微调可以帮助模型学习到新数据集中的模式，使其能够对之前未见过的输入进行更准确的预测。
* **资源效率**：由于只需要少量额外训练，微调可以在较小的计算资源上进行，从而节省时间和成本。

总之，微调大型预训练模型，如LLaMA 3，可以显著提高它们在目标任务中的性能，并使其适应特定领域。通过精细调整超参数、数据集和架构，微调可以帮助创建更具针对性的模型，从而实现更好的结
果。
>>> /?
Available Commands:
  /set            Set session variables
  /show           Show model information
  /load <model>   Load a session or model
  /save <model>   Save your current session
  /bye            Exit
  /?, /help       Help for a command
  /? shortcuts    Help for keyboard shortcuts

Use """ to begin a multi-line message.

>>> /bye

使用ollama调整大模型提示词和参数

这里基于阿里开源的千问大模型,创建Modelfile

FROM qwen:7b

# 把温度调到1(越高越有创意，越低越连贯)
PARAMETER temperature 0.8

#设置上下文token尺寸
PARAMETER num_ctx 8192

# 设置系统消息
SYSTEM """
你是由wnote公司开发并提供的一个名为wanzi的人工智能助手。
你擅长说英语和笑话。
"""

# ollama create wanzi -f ./Modelfile
transferring model data
reading model metadata
creating system layer
creating parameters layer
creating config layer
using already created layer sha256:87f26aae09c7f052de93ff98a2282f05822cc6de4af1a2a159c5bd1acbd10ec4
using already created layer sha256:7c7b8e244f6aa1ac8c32b74f56d42c41a0364dd2dabed8d9c6030a862e805b54
using already created layer sha256:1da0581fd4ce92dcf5a66b1da737cf215d8dcf25aa1b98b44443aaf7173155f5
writing layer sha256:1744dbff14b6e7fb2a846c118720f4627cdece7180bdb9d6f176c44bc6308718
writing layer sha256:02d401d3225083c307561b27d81137360bf39c01259dddbb267897cdcde6efec
writing layer sha256:d052490c542f2b7c49e4a770cc3239a58ca7261f75bc1730dd2b4ce5999de0b0
writing manifest
success
# ollama run wanzi
>>> 你是谁？
我是Wanzi，由wnote公司开发的一款人工智能助手。我擅长用英语交流，并且偶尔还会讲一些幽默的笑话来调节气氛。有什么我可以帮助你的吗？
>>> 帮我讲一个非常搞笑的段子。
当然，让我给你讲个逗趣的段子：

有一天，一只企鹅走进了一家酒吧，它穿着正式的燕尾服，显得既滑稽又神秘。

酒保看着这只企鹅，惊呼：“哇，你这是要开派对吗？”

企鹅想了想，耸了耸他那圆滚滚的肩膀，用它特有的低沉嗓音说：“不，我只是想点一杯‘零度寂寞’。”

所有人都愣住了，然后爆发出一阵大笑。从此，酒吧菜单上多了一个名副其实的“笑话”——零度寂寞。

希望这个段子能让你开心！

REST API请求

生成响应：

curl http://localhost:11434/api/generate -d '{
  "model": "qwen:7b",
  "prompt":"为什么大模型现在这么流行?"
}'

模型对话：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen:7b",
  "messages": [
    { "role": "user", "content": "为什么大模型现在这么流行?" }
  ]
}'

ollama支持的大模型比较多，有需要更多体验的可以移步：https://ollama.com/library

Open-webui

Open-webui是一种可扩展、功能丰富、用户友好的自托管web UI，采用Svelte前端框架开发，旨在完全离线运行。它支持各种LLM运行程序，包括与Ollama和openai兼容的api。

之前对于ollma命令行操作，现在完全可以在web洁面操作了。

open-webui特性

轻松安装:使用Docker或Kubernetes (kubectl, kustomize或helm)无缝安装，支持:ollama和:cuda标记图像，获得无忧体验。
Ollama/OpenAI API集成:轻松集成OpenAI兼容的API，与Ollama模型一起进行多功能对话。自定义OpenAI API URL链接到LMStudio, GroqCloud, Mistral, OpenRouter等。
Pipelines, Open web插件支持:使用Pipelines Plugin Framework将自定义逻辑和Python库无缝集成到Open web中。启动管道实例，将OpenAI URL设置为管道URL，并探索无限的可能性。示例包括函数调用，用户速率限制来控制访问，使用Langfuse等工具进行使用监控，使用LibreTranslate进行多语言支持的实时翻译，有毒消息过滤等等。
响应式设计:在台式机、笔记本电脑和移动设备上享受无缝体验。
移动渐进式Web应用程序(PWA):使用我们的PWA，在您的移动设备上享受原生应用程序般的体验，提供本地主机上的离线访问和无缝的用户界面。
完全Markdown和LaTeX支持:通过全面的Markdown和LaTeX功能提升您的LLM经验，以丰富交互。
️模型生成器:通过Web UI轻松创建[推荐]模型。通过Open web Community集成，轻松创建和添加自定义角色/代理、自定义聊天元素和导入模型。
本地RAG集成:通过突破性的检索增强生成(RAG)支持，深入了解聊天交互的未来。此功能将文档交互无缝地集成到您的聊天体验中。您可以直接将文档加载到聊天中，或者将文件添加到文档库中，在查询之前使用#命令轻松地访问它们。
Web Search for RAG:使用SearXNG, Google PSE, Brave Search, serstack和serper等提供商执行Web搜索，并将结果直接注入到您的聊天体验中。
网页浏览功能:使用#命令后跟URL，无缝地将网站集成到您的聊天体验中。此功能允许您将web内容直接合并到您的对话中，增强交互的丰富性和深度。
图像生成集成:使用AUTOMATIC1111 API或ComfyUI(本地)和OpenAI的DALL-E(外部)等选项无缝地整合图像生成功能，通过动态视觉内容丰富您的聊天体验。
️许多模型对话:毫不费力地与各种模型同时参与，利用其独特的优势，以获得最佳的响应。通过并行地利用一组不同的模型来增强您的体验。
基于角色的访问控制(RBAC):确保受限制权限的安全访问;只有经过授权的个人才能访问您的Ollama，并且为管理员保留独家的模型创建/提取权限。
多语言支持:使用我们的国际化(i18n)支持，以您首选的语言体验Open web。加入我们，扩展我们支持的语言!我们正在积极寻找贡献者!
持续更新:我们致力于通过定期更新、修复和新功能来改进Open web。

部署open-webui

为了和ollama配合使用，这里使用docker-compose快速部署open-webui:

可以参考：https://github.com/valiantlynx/ollama-docker

由于我本地用的Nvidia Tesla T4的卡，所以直接用GPU的配置(需要提前安装驱动，这里忽略)

docker-compose-ollama-gpu.yaml

version: '3.8'

services:
  app:
    build: .
    ports:
      - 8000:8000
      - 5678:5678
    volumes:
      - .:/code
    command: uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
    restart: always
    depends_on:
      - ollama
      - ollama-webui
    networks:
      - ollama-docker

  ollama:
    volumes:
      - ./ollama/ollama:/root/.ollama
    container_name: ollama
    pull_policy: always
    tty: true
    restart: unless-stopped
    image: ollama/ollama:latest
    ports:
      - 11434:11434
    networks:
      - ollama-docker
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  ollama-webui:
    image: ghcr.io/ollama-webui/ollama-webui:main
    container_name: ollama-webui
    volumes:
      - ./ollama/ollama-webui:/app/backend/data
    depends_on:
      - ollama
    ports:
      - 8080:8080
    environment:
      - '/ollama/api=http://ollama:11434/api'
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped
    networks:
      - ollama-docker

networks:
  ollama-docker:
    external: false

启动服务：

`1`	`docker-compose -f docker-compose-ollama-gpu.yaml up -d`

访问https://xxx.xxx.xxx.xxx:8080/ 注册管理账户即可使用.

总结

Ollama和Open WebUI的结合带来了许多优势。首先，通过直观的UI界面，非专业读者也可以轻松地进行深度学习平台的搭建和模型的训练。其次，Open WebUI为Ollama提供了丰富的功能，如数据可视化、模型性能监控等，使得用户可以更加方便地了解模型的训练情况和性能表现。最后，Ollama和Open WebUI的开源性质使得用户可以根据自己的需求进行定制和扩展。