05-自动化工作流

了解如何在 OpenCode 中通过自然语言指令驱动 AI Agent 执行自动化任务，提升开发效率。

---

一、OpenCode 自动化概述

1.1 OpenCode 是什么

OpenCode 是一个基于 TUI（终端用户界面）的 CLI 工具，它通过 AI Agent 与大型语言模型交互来完成编程任务。OpenCode 没有内置的 Hooks 事件系统，也没有 hooks.json 配置文件。它的自动化能力来自于：

• AI Agent 的自然语言理解：你用自然语言描述任务，AI 理解并执行
• AI Agent 的 Shell 命令执行能力：AI 可以在终端中运行命令（如测试、格式化、Git 操作）
• AI Agent 的文件操作能力：AI 可以直接读取、编辑、创建文件

你的自然语言指令 → AI Agent 理解 → AI 执行操作
     │                                    │
     │                                    ├─ 读取/编辑文件
     │                                    ├─ 执行 Shell 命令
     │                                    ├─ 运行测试
     │                                    ├─ Git 操作
     │                                    └─ 安装依赖
     │
     └─ "帮我格式化所有 Python 文件并运行测试"
        "提交当前更改，提交信息要描述做了什么"
        "重构这个函数，然后运行相关测试确保没破坏功能"

1.2 自动化的核心机制

能力	实现方式	说明
文件操作	AI 内置工具	AI 直接读取、编辑、创建文件
命令执行	AI 的 Shell 能力	AI 在终端中运行命令
Git 操作	AI 执行 Git 命令	git add, git commit, git push 等
权限控制	TUI 提示确认	敏感操作会弹出确认提示
自动化流程	自然语言描述	用一句话描述多步骤工作流

---

二、通过自然语言驱动自动化

2.1 基本指令模式

在 OpenCode 的 TUI 界面中，你直接输入自然语言指令，AI Agent 会理解并执行：

# 代码格式化
> 帮我把 app/ 目录下所有 Python 文件用 black 格式化

# 运行测试
> 运行 tests/ 目录下的所有测试

# Git 操作
> 把当前的更改提交，写一个清晰的提交信息

# 组合操作
> 格式化代码，运行测试，如果测试通过了就提交

2.2 多步骤工作流

你可以用一条指令描述完整的工作流，AI 会按顺序执行：

> 帮我完成以下任务：
> 1. 检查 app/models.py 的代码质量
> 2. 用 black 格式化
> 3. 用 flake8 检查规范
> 4. 运行相关的单元测试
> 5. 如果都通过了，git add 并 commit

AI 会逐步执行每个步骤，并在终端中显示输出。

2.3 条件化指令

你可以在指令中加入条件逻辑：

> 运行 pytest tests/，如果测试通过了就执行 git commit，
> 如果失败了告诉我哪些测试失败了

---

三、文件操作自动化

3.1 AI 的文件读写

OpenCode 的 AI Agent 可以直接操作文件，不需要通过外部脚本：

# 创建新文件
> 在 app/utils/ 下创建一个 helpers.py 文件，包含以下函数...

# 修改现有文件
> 把 app/models.py 中的 User 类添加一个 email 字段

# 批量操作
> 把所有 .py 文件中的 print 语句替换为 logging

3.2 代码格式化工作流

在 OpenCode 中，你通过指令让 AI 执行格式化：

# 格式化单个文件
> 用 black 格式化 app/services/user_service.py

# 格式化整个目录
> 对 app/ 目录运行 black 格式化

# 格式化 + 排序 imports
> 先用 isort 排序 imports，再用 black 格式化 app/ 目录

AI 会在终端中执行 black app/ 和 isort app/ 等命令，并显示结果。

3.3 代码质量检查

# 运行 linter
> 用 flake8 检查 app/ 目录的代码规范

# 类型检查
> 用 mypy 检查 app/ 的类型注解

# 安全检查
> 用 bandit 扫描 app/ 的安全漏洞

---

四、测试自动化

4.1 运行测试

# 运行所有测试
> 运行 pytest

# 运行特定测试文件
> 运行 tests/test_user.py

# 运行匹配关键字的测试
> 运行包含 "user" 关键字的测试

# 带覆盖率运行
> 运行 pytest 并生成覆盖率报告

4.2 测试驱动开发工作流

> 为 app/services/user_service.py 编写单元测试，
> 然后运行测试确保都通过

AI 会：

1. 读取源代码文件
2. 理解其功能
3. 创建测试文件
4. 运行测试
5. 如果有失败的测试，修复并重新运行

4.3 持续测试模式

OpenCode 本身没有内置的 watch 模式，但你可以让 AI 启动外部工具：

> 启动 pytest-watch 来持续监控 tests/ 目录的文件变化

AI 会在终端中执行 ptw tests/，这个后台进程会持续运行。

---

五、Git 集成

5.1 Git 操作

OpenCode 的 AI Agent 通过执行 Shell 命令来完成 Git 操作：

# 查看状态
> 当前 git 状态是什么？

# 暂存和提交
> 把所有更改添加到暂存区并提交，写一个有意义的提交信息

# 查看差异
> 显示当前未提交的更改

# 创建分支
> 创建一个新分支 feature/user-auth

5.2 提交前检查流程

你可以让 AI 在提交前执行检查：

> 在提交之前，先做以下检查：
> 1. 运行 black --check . 确保格式正确
> 2. 运行 flake8 app/ 检查规范
> 3. 运行 pytest tests/ -x 确保测试通过
> 如果都通过了，再执行 git commit

5.3 智能提交信息

> 根据当前的更改生成一个符合 Conventional Commits 规范的提交信息并执行提交

AI 会分析 git diff 的输出，理解更改内容，然后生成类似 feat: add user authentication endpoint 的提交信息。

5.4 完整的发布流程

> 帮我完成发布流程：
> 1. 检查当前版本号
> 2. 运行所有测试
> 3. 更新 CHANGELOG.md
> 4. 提交更改
> 5. 打 tag v1.2.0
> 6. 推送到远程仓库

---

六、安全与权限

6.1 TUI 权限提示

OpenCode 是一个 TUI 工具，当 AI 尝试执行可能影响系统的操作时，会通过 TUI 界面弹出确认提示：

• 文件写入：AI 修改文件时，你可以在 TUI 中看到更改内容并确认
• 命令执行：AI 运行 Shell 命令时，你可以看到命令内容
• Git 操作：提交、推送等操作可以通过 TUI 界面确认

6.2 安全最佳实践

# 在执行敏感操作前，先让 AI 展示计划
> 在运行任何命令之前，先告诉我你打算做什么

# 审查更改
> 先展示你打算对 app/models.py 做的更改，等我确认后再执行

# 分步执行
> 我们一步一步来，先格式化，我确认后再运行测试

6.3 敏感信息保护

# 检查是否有敏感信息被提交
> 检查当前暂存区是否包含 API key、密码等敏感信息

# 使用 .gitignore
> 帮我把 .env 文件添加到 .gitignore 中

---

七、实战示例

7.1 Python 项目自动化工作流

场景：你修改了 app/services/user_service.py，需要完成完整的开发流程。

指令：

> 我刚修改了 app/services/user_service.py，帮我完成以下工作：
>
> 1. 用 black 格式化这个文件
> 2. 用 isort 排序 imports
> 3. 用 flake8 检查代码规范
> 4. 运行相关的单元测试 tests/test_user_service.py
> 5. 如果测试通过了，git add 这个文件并 commit

AI 会执行：

black app/services/user_service.py
isort app/services/user_service.py
flake8 app/services/user_service.py
pytest tests/test_user_service.py -v
git add app/services/user_service.py
git commit -m "refactor: improve user service error handling"

7.2 前端项目自动化工作流

场景：你完成了一个 React 组件的开发。

指令：

> 我完成了 src/components/UserProfile.tsx 的开发，帮我：
>
> 1. 用 Prettier 格式化
> 2. 用 ESLint 检查并自动修复
> 3. 运行 TypeScript 类型检查
> 4. 运行这个组件相关的测试
> 5. 如果都通过了，提交更改

7.3 重构 + 测试工作流

场景：你需要重构一个函数并确保不破坏现有功能。

指令：

> 帮我重构 app/utils/data_processor.py 中的 process_data 函数：
>
> 1. 先运行现有测试，确保当前是绿色的
> 2. 重构函数，提高可读性和性能
> 3. 再次运行测试，确保没有回归
> 4. 如果有测试失败，修复问题
> 5. 最后提交更改

7.4 批量代码修改

场景：你需要在整个项目中替换一个废弃的 API 调用。

指令：

> 在整个项目中，把所有使用 old_api.call() 的地方替换为 new_api.invoke()。
> 替换完成后，运行测试确保没有破坏任何功能。

7.5 代码审查工作流

场景：你想让 AI 审查你的代码。

指令：

> 审查我当前的未提交更改：
> 1. 显示 git diff
> 2. 指出潜在的问题（bug、性能、安全）
> 3. 提出改进建议
> 4. 如果我没有异议，再提交

---

八、最佳实践

8.1 指令编写原则

1. 具体明确：清楚描述你要做什么，而不是模糊地说"帮我优化代码"
2. 分步描述：复杂任务分解为明确的步骤
3. 包含条件：说明"如果 X 发生，就做 Y"
4. 要求确认：对敏感操作要求 AI 先展示计划

8.2 效率提升技巧

# 使用上下文引用
> 查看 @app/services/user_service.py 并修复其中的 bug

# 组合多个工具
> 读取 @app/models.py，然后用 black 格式化，最后运行相关测试

# 保存上下文
> 记住我们刚才讨论的重构方案，应用到其他类似的模块

8.3 避免常见问题

• 不要假设 AI 会自动运行测试：明确告诉 AI “运行测试”
• 不要让 AI 自动提交未经审查的代码：要求 AI 先展示更改
• 不要在指令中使用模糊的描述：用具体的文件名、命令名

---

九、与其他工具集成

9.1 与 CI/CD 配合

OpenCode 负责本地开发自动化，CI/CD 负责远程验证：

# 在 OpenCode 中完成本地工作
> 格式化代码、运行测试、提交更改

# 然后推送到远程触发 CI
> git push origin main

9.2 与 Git Hooks 配合

OpenCode 本身没有 Hooks 系统，但你可以使用 Git 原生的 Hooks：

# 在项目的 .git/hooks/pre-commit 中设置检查
# 这样即使通过 OpenCode 提交，也会触发检查

9.3 与任务运行器配合

# 让 AI 运行项目特定的任务
> 运行 npm run build 构建项目
> 运行 make test 执行测试
> 运行 docker-compose up 启动开发环境

---

十、下一步

掌握 OpenCode 的自动化工作流后，建议学习：

1. 06-Skills复用.md - 创建可复用技能
2. 07-代码分析与重构.md - 批量代码处理
3. 11-项目规划测试代码审查实战.md - 完整工作流

---

文档版本: 2.0 | 建议学习时长: 40分钟