OpenCode 深度使用指南

面向 Python 开发工程师

OpenCode 是什么
为什么 Python 工程师应该关注 OpenCode
OpenCode 的整体架构
安装与初始化
Provider 与模型选择
第一个 Python 项目
AGENTS.md：真正决定 Agent 表现的核心
Plan / Build / Subagent
如何给 OpenCode 下高质量开发任务
Python 项目的标准工作流
Debug 工作流
Refactoring 工作流
测试驱动工作流
Git 工作流
大型代码库与 Monorepo
Skills
Custom Commands
MCP
Custom Tools
Plugins
LSP
权限与安全
模型路由与成本控制
上下文管理
多 Agent 软件工程
Python 项目推荐配置
企业级项目实践
CI/CD 集成
常见失败模式
如何评估 OpenCode 的实际生产力
一套成熟的 AI-Native Python 开发规范
进一步的高级玩法

1. OpenCode 是什么

OpenCode 是一个开源的 AI coding agent。

这里最重要的三个关键词不是：

AI、Code、Terminal

而是：

Agent、Tool、Model Decoupling（解耦）

传统代码助手大致是：

css 复制代码

Developer
   ↓
IDE
   ↓
LLM
   ↓
Code Completion

OpenCode 更接近：

bash 复制代码

                 Developer
                     ↓
                  Agent
                     ↓
        ┌────────────┼────────────┐
        ↓            ↓            ↓
      Model        Context       Tools
        ↓            ↓            ↓
   Claude/GPT     Codebase      read
   Gemini/...     Rules         edit
                  Tests         bash
                  Git           grep
                                LSP
                                MCP
                                  ↓
                                Result
                                  ↓
                               Agent

也就是说：

模型负责推理，Agent 负责工作流，Tools 负责行动。

这是理解 OpenCode 的第一原则。

OpenCode 本身并不要求你绑定某一家模型提供商，目前通过 AI SDK / Models.dev 支持 75+ LLM provider，也支持本地模型。

因此可以把 OpenCode 看成：

一个开放的 AI 软件工程执行环境。

2. 为什么 Python 工程师应该关注它

如果你已经有多年 Python 开发经验，那么你真正缺的通常不是：

markdown 复制代码

for item in items:
    ...

这种代码生成能力。

你缺的是：

markdown 复制代码

理解大型代码库
        ↓
定位问题
        ↓
设计修改方案
        ↓
修改多个模块
        ↓
运行测试
        ↓
分析失败
        ↓
继续修改
        ↓
检查回归
        ↓
Review
        ↓
Commit

这恰好是 Coding Agent 的能力边界。

因此对于资深工程师：

OpenCode 最有价值的地方不是"帮你写代码"，而是替你承担软件工程中的机械认知劳动。

例如：

阅读陌生项目
分析调用链
找 bug
添加测试
重构
API migration（迁移）
dependency upgrade（依赖升级）
类型修复
lint 修复
test failure triage（诊断）
PR review
文档同步
CI failure 分析

3. OpenCode 的整体架构

理解架构以后，你会知道什么时候应该用 OpenCode，什么时候不应该用。

可以抽象成：

sql 复制代码

                         User
                          │
                          ▼
                    OpenCode TUI
                          │
                          ▼
                    Primary Agent
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
            Model       Context      Rules
              │           │           │
              │       Codebase     AGENTS.md
              │       History      Skills
              │       Tools        Commands
              │
              ▼
          Tool Calling
              │
       ┌──────┼───────────────┐
       ▼      ▼       ▼       ▼
      read   edit    bash    LSP
       │      │       │       │
       └──────┴───────┴───────┘
                    │
                    ▼
                 Result
                    │
                    ▼
                 Agent
                    │
             ┌──────┴──────┐
             ▼             ▼
           Tests          Review
             │             │
             └──────┬──────┘
                    ▼
                  Done

这里存在几个关键层。

3.1 Model

负责：

推理、规划、生成、决策。

例如：

复制代码

Claude
GPT
Gemini
本地模型

3.2 Agent

负责：

当前应该做什么。

例如：

rust 复制代码

Plan
Build
Explore（探索）
General（通用）
Review
Debug

OpenCode 当前内置 primary agents 包括 Build 和 Plan，同时提供 General、Explore、Scout（侦察）等 subagents。

3.3 Tools

负责：

实际做什么。

例如：

perl 复制代码

read
write
edit
bash
grep
glob
lsp
webfetch
websearch
skill
todowrite

OpenCode 当前内置工具体系已经覆盖文件读取、编辑、shell、搜索、LSP、Skills 等，并可以通过 MCP 和 custom tools 扩展。

3.4 Context

负责：

AI 知道什么。

包括：

复制代码

当前任务
代码
AGENTS.md
Skills
历史对话
测试结果
Git diff
工具输出

对于大型 Python 项目，Context 管理能力往往比 prompt 技巧更重要。

4. 安装 OpenCode

官方目前提供多种安装方式。

最简单的是：

arduino 复制代码

curl -fsSL https://opencode.ai/install | bash

或者：

复制代码

npm install -g opencode-ai

也可以：

复制代码

bun install -g opencode-ai

macOS / Linux：

bash 复制代码

brew install anomalyco/tap/opencode

Windows 官方推荐使用 WSL；也支持 Chocolatey、Scoop、npm 和 Docker。

安装以后：

复制代码

opencode

进入当前项目。

建议首先：

bash 复制代码

/help

查看当前版本实际支持的命令。

5. Provider 与模型

OpenCode 最值得资深工程师关注的设计之一，就是：

Agent 与模型解耦。

你可以使用不同 provider。

配置完成后：

bash 复制代码

/models

查看当前可用模型。

模型完整 ID 的形式通常是：

bash 复制代码

provider_id/model_id

例如：

bash 复制代码

opencode/gpt-5.1-codex

或者：

xml 复制代码

anthropic/<model>

具体模型 ID 不应该硬编码进你的知识体系，因为模型版本变化非常快。

官方当前文档列出的适合 coding / tool use 的模型包括 GPT 5.2、GPT 5.1 Codex、Claude Opus 4.5、Claude Sonnet 4.5、Minimax M2.1、Gemini 3 Pro 等，但这是动态列表，并不意味着它始终是最新排行榜。

6. Provider 配置

可以通过：

arduino 复制代码

/connect

添加 provider credentials。

认证信息会保存到：

javascript 复制代码

~/.local/share/opencode/auth.json

官方文档说明，Provider 还可以通过配置文件进一步设置 baseURL、headers、模型参数等。

例如：

bash 复制代码

{
  "$schema": "https://opencode.ai/config.json",

  "model": "anthropic/<your-model>",

  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  }
}

对于企业内部网关：

markdown 复制代码

Developer
    ↓
OpenCode
    ↓
Company AI Gateway
    ↓
Model Provider

这种架构非常有价值。

7. Python 项目初始化

假设你有：

csharp 复制代码

payment-service/
├── src/
│   └── payment/
├── tests/
├── pyproject.toml
├── uv.lock
├── Dockerfile
└── README.md

进入：

bash 复制代码

cd payment-service
opencode

第一件事不要立即让 AI 改代码。

先：

bash 复制代码

/init

OpenCode 会扫描项目并生成或更新：

复制代码

AGENTS.md

官方建议把项目级 AGENTS.md 提交进 Git，因为它应该成为团队共享的 Agent 开发规范。

8. AGENTS.md：OpenCode 最重要的工程配置

很多人使用 Coding Agent 最大的问题是：

Prompt 写得很好，但 Agent 还是经常犯低级错误。

根本原因通常不是模型不够强，而是：

项目知识没有结构化注入。

AGENTS.md 就是解决这个问题的核心机制。

9. Python 项目的 AGENTS.md 推荐结构

建议：

markdown 复制代码

# Project Instructions

## Project Overview

This is a Python 3.13 backend service.

Architecture:

- src/payment/domain
- src/payment/application
- src/payment/infrastructure
- src/payment/api

## Environment

Use uv for dependency management.

Python version:
3.13

Create or reuse the project virtual environment.

## Commands

Install:

uv sync

Run tests:

uv run pytest

Run focused tests:

uv run pytest tests/unit/

Lint:

uv run ruff check .

Format:

uv run ruff format .

Type check:

uv run mypy src/

## Coding Rules

- Follow PEP 8.
- Prefer explicit typing.
- Do not introduce Any unless justified.
- Prefer dataclasses or Pydantic models according to layer.
- Keep domain logic independent from infrastructure.
- Do not access database directly from domain modules.

## Testing

Every behavior change must include tests.

Prefer unit tests for domain logic.

Use integration tests for repository/database behavior.

## Database

PostgreSQL.

SQLAlchemy 2.x.

Alembic for migrations.

Never modify an existing migration.

Create a new migration instead.

## Git

Do not commit unless explicitly requested.

Do not reset or discard user changes.

Before finishing:

1. Run focused tests.
2. Run full tests if practical.
3. Run ruff.
4. Run mypy for changed modules.

## Safety

Never read or print secrets.

Do not modify .env files.

Do not execute destructive commands without confirmation.

这比：

"你是一个高级 Python 工程师，请帮我写高质量代码。"

有用得多。

10. AGENTS.md 应该写什么？

不要把它写成百科全书。

优秀的 AGENTS.md 应该回答：

① 怎么运行

arduino 复制代码

uv run pytest

② 怎么测试

复制代码

unit
integration
e2e

③ 怎么 lint

复制代码

ruff
mypy
pyright

④ 项目架构是什么

复制代码

domain
application
infrastructure
api

⑤ 哪些东西绝对不能碰

arduino 复制代码

migration history
production config
secrets
generated files

⑥ 哪些设计原则必须遵守

例如：

yaml 复制代码

No ORM usage in domain layer.

11. Global AGENTS.md

除了项目级：

复制代码

AGENTS.md

还可以设置：

javascript 复制代码

~/.config/opencode/AGENTS.md

作为个人全局规则。

例如：

markdown 复制代码

# Personal Engineering Rules

- Prefer small focused changes.
- Never silently change architecture.
- Always explain risky migrations.
- Never overwrite unrelated user changes.
- Prefer tests before implementation when behavior is ambiguous.
- Never commit unless explicitly requested.

官方目前的规则加载优先级包括项目目录向上查找的 AGENTS.md / CLAUDE.md，以及全局 AGENTS.md；同时提供 Claude Code 兼容机制。

12. Plan 与 Build

这是资深工程师必须掌握的功能。

OpenCode 的核心 primary agents：

复制代码

Plan
Build

Plan

用于：

复制代码

分析
调查
设计
制定方案

不应该直接修改项目。

Build

用于：

复制代码

修改代码
执行命令
运行测试

官方对 Plan 的定位就是受限分析/规划代理，而 Build 是标准开发代理。

13. 为什么应该先 Plan 再 Build？

例如你说：

"把 Celery 换成 Temporal。"

这不是一个简单的代码修改。

它可能涉及：

ruby 复制代码

worker
tasks
retry
scheduler
database
idempotency
monitoring
deployment
Docker
Kubernetes
tests

正确流程：

复制代码

Plan
 ↓
理解系统
 ↓
列出影响面
 ↓
提出迁移方案
 ↓
人工 review
 ↓
Build
 ↓
实施
 ↓
测试

而不是：

复制代码

Build
 ↓
开始乱改
 ↓
发现架构问题
 ↓
返工

14. 资深工程师最推荐的工作模式

我推荐：

sql 复制代码

Explore
   ↓
Plan
   ↓
Human Review
   ↓
Build
   ↓
Test
   ↓
Review
   ↓
Merge

这是比：

复制代码

"帮我把这个功能写出来"

成熟得多的 Agent workflow。

15. 如何给 OpenCode 下任务

最差：

复制代码

帮我优化一下支付系统。

好一点：

复制代码

优化 PaymentService 的性能。

更好：

markdown 复制代码

分析 PaymentService 的性能瓶颈，
不要修改代码。

重点检查：

1. 数据库查询次数
2. N+1 查询
3. 外部 API 调用
4. 序列化
5. 锁竞争

最后给出：
- 发现的问题
- 证据
- 建议方案
- 预期收益
- 风险

不要执行修改。

真正高级：

markdown 复制代码

先分析 PaymentService。

约束：

- 不改变公开 API
- 不改变数据库 schema
- 不改变事务语义
- 不改变错误类型
- 不引入新的基础设施依赖

目标：

P95 latency 降低至少 20%。

流程：

1. 阅读相关代码
2. 找出调用链
3. 检查 SQL
4. 检查外部 IO
5. 检查 profiling/test evidence
6. 给出方案
7. 等待确认
8. 实施
9. 添加 regression tests
10. 运行 benchmark
11. 汇报结果

不要修改无关代码。

这才是真正适合 Agent 的任务描述。

16. 一个重要原则：告诉 Agent"不要做什么"

成熟工程师和普通用户使用 Coding Agent 最大的区别之一就是：

边界意识。

例如：

diff 复制代码

Do not:

- modify database schema
- upgrade dependencies
- change public APIs
- touch unrelated files
- change formatting outside modified modules
- rewrite tests just to make them pass
- suppress type errors

这些限制可以显著降低 Agent 的自由度。

而：

自由度越高 ≠ 结果越好。

17. Python Debug Workflow

假设：

bash 复制代码

pytest tests/unit/test_payment.py

失败。

不要直接：

复制代码

帮我修这个测试

建议：

markdown 复制代码

Investigate this failure.

First:

1. Read the failing test.
2. Read the implementation.
3. Trace the relevant call path.
4. Determine whether the bug is in:
   - production code
   - test
   - fixture
   - environment
   - dependency

Do not modify anything yet.

Report:
- root cause
- evidence
- minimal fix
- regression test strategy

然后：

diff 复制代码

Implement the minimal fix.

Requirements:

- preserve existing behavior
- add regression coverage
- do not weaken assertions
- run the focused test first
- then run related tests

这比让 AI 一上来修改测试可靠很多。

18. "测试绿了"不等于"问题解决了"

这是使用 Agent 时非常重要的一条原则。

不要允许：

bash 复制代码

test failed
↓
AI 修改 test
↓
test passed

必须要求：

markdown 复制代码

Root Cause
    ↓
Production Fix
    ↓
Regression Test
    ↓
Focused Test
    ↓
Related Test
    ↓
Full Test

在 AGENTS.md 中明确：

bash 复制代码

Never modify tests merely to make them pass.

If a test conflicts with intended behavior,
explain the conflict before changing the test.

19. Refactoring Workflow

大型 Python 重构最适合 Agent。

例如：

csharp 复制代码

把 repository 层从同步 SQLAlchemy
迁移到 async SQLAlchemy。

不要一次性让它修改整个项目。

拆成：

sql 复制代码

Phase 1
Inventory

Phase 2
Architecture plan

Phase 3
Introduce async abstraction

Phase 4
Migrate one repository

Phase 5
Migrate service layer

Phase 6
Migrate API

Phase 7
Tests

Phase 8
Remove old implementation

每一步都：

bash 复制代码

change
↓
test
↓
review

而不是：

复制代码

巨大 prompt
↓
几百个文件变化
↓
祈祷

20. Git 是 Agent 的"安全网"

强烈建议：

lua 复制代码

git status
git diff

频繁检查。

理想工作流：

markdown 复制代码

clean working tree
       ↓
OpenCode
       ↓
small change
       ↓
tests
       ↓
git diff
       ↓
review
       ↓
commit

不要让 Agent 在一个 session 中积累：

复制代码

200 files changed

除非这是明确计划的迁移。

21. 不要让 Agent 随便 commit

推荐：

sql 复制代码

Do not commit changes.

由工程师：

lua 复制代码

git diff
git diff --check
git status

确认之后：

sql 复制代码

git commit

对于企业环境尤其如此。

22. Monorepo

大型 Python Monorepo 可以采用：

sql 复制代码

repo/
├── AGENTS.md
├── pyproject.toml
├── services/
│   ├── billing/
│   │   └── AGENTS.md
│   ├── payment/
│   │   └── AGENTS.md
│   └── user/
│       └── AGENTS.md
├── libs/
│   ├── auth/
│   └── common/
└── tests/

顶层：

复制代码

架构原则

子目录：

复制代码

服务级规则

OpenCode 支持从项目目录层级发现规则，因此非常适合这种结构。

23. Python Monorepo 的推荐规则

例如：

bash 复制代码

services/payment/AGENTS.md

内容：

shell 复制代码

# Payment Service

## Runtime

Python 3.13

## Dependencies

Use uv.

## Commands

uv run pytest
uv run ruff check .
uv run mypy src/

## Architecture

api
 ↓
application
 ↓
domain
 ↓
infrastructure

Domain must not import infrastructure.

## Database

PostgreSQL.

Repository implementations live under infrastructure.

## Testing

Business logic must have unit tests.

Repository behavior requires integration tests.

## External APIs

All external API calls must go through adapters.

Do not call external services directly from domain code.

这会让 Agent 的行为明显更加稳定。

24. Skills

Skills 是另一个非常重要的高级机制。

它解决的问题是：

把可复用的专业工作流封装起来。

OpenCode 当前支持：

bash 复制代码

.opencode/skills/<name>/SKILL.md

以及全局 Skills。

Agent 可以按需加载 Skill，而不是把所有规则一次性塞进 context。

25. Python 项目可以建立哪些 Skill？

例如：

arduino 复制代码

.opencode/skills/
├── python-review/
├── django-migration/
├── sqlalchemy-review/
├── fastapi-endpoint/
├── pytest-debug/
├── security-audit/
└── release/

26. Python Review Skill

例如：

bash 复制代码

.opencode/skills/python-review/SKILL.md

可以写：

yaml 复制代码

---
name: python-review
description: Review Python code for correctness, typing, architecture, performance and security.
---

# Python Code Review

Review code in this order:

1. Correctness
2. Security
3. Concurrency
4. Transaction semantics
5. Error handling
6. Type safety
7. API compatibility
8. Performance
9. Maintainability
10. Tests

Do not focus primarily on formatting.

For every finding provide:

- severity
- file
- line
- evidence
- impact
- recommendation

Do not suggest speculative problems without evidence.

然后让 Agent：

kotlin 复制代码

Use the python-review skill to review this change.

27. Skill 的一个高级原则

不要把所有知识写进：

复制代码

AGENTS.md

应该：

markdown 复制代码

AGENTS.md
    ↓
核心项目规则

Skills
    ↓
专业流程

例如：

markdown 复制代码

AGENTS.md
    ├── 项目结构
    ├── 测试命令
    └── 核心约束

Skills
    ├── database migration
    ├── security audit
    ├── API review
    └── release

这样 Context 更干净。

OpenCode 的 Skills 是按需加载的，这一点对大型项目尤其重要。

28. Custom Commands

如果你每天反复执行：

arduino 复制代码

review
test
security
release
debug

应该把它们做成 command。

例如：

bash 复制代码

.opencode/commands/review.md

可以定义：

yaml 复制代码

---
description: Review current changes
agent: plan
---

Review the current git diff.

Focus on:

1. correctness
2. security
3. concurrency
4. API compatibility
5. test coverage
6. performance

Do not modify files.

Return findings grouped by severity.

然后：

bash 复制代码

/review

OpenCode 当前支持项目级 .opencode/commands/ 和全局 command，并允许通过 $ARGUMENTS 接收参数。

29. Python 项目推荐 Commands

建议建立：

arduino 复制代码

.opencode/commands/
├── review.md
├── test.md
├── debug.md
├── security.md
├── benchmark.md
├── migration.md
└── release.md

例如：

bash 复制代码

/test

自动：

复制代码

pytest
ruff
mypy

30. `/test` Command

示例：

yaml 复制代码

---
description: Run focused tests and diagnose failures
agent: build
---

Run the relevant test suite.

Start with the narrowest relevant test.

If tests fail:

1. analyze the failure
2. identify root cause
3. fix production code when appropriate
4. add regression coverage
5. rerun focused tests

Do not weaken assertions.

At the end report:

- tests executed
- tests passed
- tests failed
- files changed

31. MCP

MCP = Model Context Protocol。

它允许 OpenCode 接入外部工具。

例如：

复制代码

OpenCode
   │
   ├── GitHub
   ├── Sentry
   ├── Jira
   ├── Database
   ├── Documentation
   └── Internal APIs

OpenCode 支持 local 和 remote MCP servers。

32. Python 开发为什么需要 MCP？

因为真实软件工程不只存在于 Git 仓库。

信息可能分散在：

复制代码

GitHub
Jira
Sentry
Datadog
PostgreSQL
Confluence
AWS
Kubernetes

如果 Agent 可以查询这些系统：

css 复制代码

Issue
 ↓
Code
 ↓
Logs
 ↓
Database
 ↓
Deployment

它才能真正完成：

"为什么生产环境这个 endpoint 最近变慢？"

而不仅仅是：

"让我看看代码。"

33. MCP 配置

例如：

bash 复制代码

{
  "$schema": "https://opencode.ai/config.json",

  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "my-mcp-command"
      ],
      "enabled": true
    }
  }
}

远程：

json 复制代码

{
  "mcp": {
    "internal-tools": {
      "type": "remote",
      "url": "https://internal.example.com/mcp",
      "enabled": true
    }
  }
}

OpenCode 官方明确提醒：

MCP server 会增加 context。

如果启用大量 MCP 工具，可能显著增加 token 消耗甚至挤压模型上下文。

所以不要：

复制代码

能接就全接。

应该：

arduino 复制代码

Task
 ↓
需要什么工具？
 ↓
只启用相关 MCP

34. 一个非常重要的 MCP 原则

不要让：

复制代码

Agent
 ↓
100 个 tools

而应该：

复制代码

Agent
 ↓
10 个高价值 tools

Tool description 本身也消耗上下文。

所以：

Tool 数量是 Agent context 的一部分。

35. Custom Tools

如果 MCP 太重，可以直接定义 OpenCode Custom Tool。

例如你可以创建：

bash 复制代码

.opencode/tools/

自定义：

复制代码

run_pytest
inspect_database
query_logs
check_api_schema
run_security_scan

OpenCode 的 custom tools 使用 TypeScript / JavaScript 定义，但工具内部可以调用 Python 等任意语言脚本。

例如：

markdown 复制代码

custom tool
     ↓
python script
     ↓
pytest

36. 为什么 Python 工程师特别适合 Custom Tools？

因为你可以直接把团队现有工具暴露给 Agent。

例如：

bash 复制代码

scripts/check_migrations.py
scripts/run_contract_tests.py
scripts/check_openapi.py
scripts/check_dependencies.py

然后包装：

scss 复制代码

check_migrations()
check_contracts()
check_dependencies()

Agent 就不需要自己猜命令。

37. Plugin

如果 Custom Tool 仍然不够，就进入 Plugin。

Plugin 可以：

matlab 复制代码

hook events
modify behavior
add tools
inject environment
log events
protect secrets

OpenCode 当前支持项目级：

bash 复制代码

.opencode/plugins/

和全局：

javascript 复制代码

~/.config/opencode/plugins/

也可以从 npm 加载 plugin。

38. Plugin 的企业级用途

例如：

lua 复制代码

tool.execute.before

拦截危险 bash：

sql 复制代码

rm -rf
DROP DATABASE
terraform destroy
kubectl delete

然后：

复制代码

deny

或者：

复制代码

ask

这比单纯告诉 Agent：

"不要执行危险命令。"

可靠得多。

因为：

Policy 应该尽可能放在系统层，而不是 prompt 层。

39. LSP

LSP 对 Python 项目尤其重要。

它让 Agent 可以获得：

typescript 复制代码

symbol
definition
reference
type
diagnostic

等代码语义信息。

OpenCode 支持配置 LSP，也允许自定义 LSP server。

对于 Python 项目，可以围绕：

复制代码

pyright
basedpyright
ruff

等工具建立更强的代码理解和验证链。

40. Python 项目的理想验证链

推荐：

markdown 复制代码

OpenCode
    ↓
LSP
    ↓
Static Analysis
    ↓
Tests
    ↓
Integration Tests
    ↓
CI

具体：

复制代码

ruff
 ↓
mypy / pyright
 ↓
pytest
 ↓
coverage
 ↓
integration tests
 ↓
docker tests

Agent 的代码生成能力再强，也应该接受这些机械验证。

41. Permission：不要忽视

OpenCode 支持工具权限控制：

复制代码

allow
deny
ask

例如：

json 复制代码

{
  "permission": {
    "edit": "deny",
    "bash": "ask",
    "webfetch": "allow"
  }
}

官方文档明确支持针对工具配置权限，也支持 wildcard。

42. Python 企业项目推荐权限

开发环境：

perl 复制代码

read       allow
grep       allow
glob       allow
lsp        allow
webfetch   allow

edit       ask
bash       ask

production tools
            deny

CI Agent：

arduino 复制代码

read       allow
edit       allow
bash       allow

production
            deny

Review Agent：

perl 复制代码

read       allow
grep       allow
glob       allow

edit       deny
bash       deny

这可以形成：

markdown 复制代码

                    Agent
                      │
            ┌─────────┴─────────┐
            ↓                   ↓
          Policy              Tools
            │                   │
            └─────────┬─────────┘
                      ↓
                   Execute

43. Secrets

最重要的原则：

css 复制代码

Never expose secrets to the model unnecessarily.

特别是：

arduino 复制代码

.env
.env.production
AWS credentials
SSH keys
private certificates
database credentials
API tokens

不要让 Agent 为了：

"看看配置"

而读取：

复制代码

.env.production

应该提供：

复制代码

.env.example

或者专门的 sanitized config。

44. Python 项目的 Sandbox

如果 Agent 可以：

csharp 复制代码

pip install
uv add
docker
terraform
kubectl

那么它事实上已经具备执行真实系统操作的能力。

推荐：

markdown 复制代码

Host
 │
 └── Sandbox / Container
       │
       ├── repo
       ├── tests
       ├── dependencies
       └── fake services

尤其是：

kotlin 复制代码

database migration
external API
deployment

必须隔离。

45. Context Management

长时间使用 OpenCode 后，一个问题会出现：

复制代码

context越来越长

于是：

diff 复制代码

旧信息
+
工具输出
+
代码
+
测试
+
错误日志
+
新任务

最终污染上下文。

OpenCode 提供 /compact 等会话管理能力。

但真正高级的做法不是：

一直让 context 变大。

而是：

控制上下文进入什么。

46. Context Engineering

推荐：

markdown 复制代码

AGENTS.md
    ↓
项目级事实

Skill
    ↓
专业流程

Task
    ↓
当前目标

Tools
    ↓
当前需要的信息

而不是：

复制代码

"把整个项目都读一遍。"

47. 为什么"让 AI 读完整个项目"通常不是好方法？

因为：

arduino 复制代码

Context size ≠ useful context

100 万 token 的代码库：

并不意味着 AI 真正理解了 100 万 token。

更好的方式：

arduino 复制代码

Task
 ↓
Relevant module
 ↓
Call graph
 ↓
Tests
 ↓
Dependency

也就是：

按需加载。

48. Debug Agent

建议创建：

bash 复制代码

.opencode/agents/debugger.md

例如：

yaml 复制代码

---
description: Investigate Python failures without making unrelated changes.
mode: subagent
---

You are a senior Python debugging specialist.

Workflow:

1. reproduce
2. inspect traceback
3. inspect relevant source
4. trace call graph
5. inspect tests
6. identify root cause
7. propose minimal fix
8. add regression test

Never hide errors by:
- weakening assertions
- broad exception handling
- disabling type checks
- changing unrelated tests

然后：

css 复制代码

@debugger

调用。

OpenCode 支持通过 @ 调用 subagent。

49. Review Agent

可以创建：

css 复制代码

code-reviewer

专门做：

复制代码

security
correctness
architecture
performance
tests

例如：

yaml 复制代码

---
description: Review Python code for correctness and production risks.
mode: subagent
---

Review only.

Do not modify files.

Check:

- correctness
- race conditions
- transaction boundaries
- exception handling
- security
- typing
- performance
- API compatibility
- test coverage

Prioritize real issues over stylistic preferences.

50. Multi-Agent

成熟的工作流可以：

css 复制代码

                  Main Agent
                      │
       ┌──────────────┼──────────────┐
       ↓              ↓              ↓
   Explore         Debugger       Reviewer
       │              │              │
       ↓              ↓              ↓
   findings        root cause      risks
       └──────────────┼──────────────┘
                      ↓
                    Build
                      ↓
                    Test

OpenCode 当前支持 primary agents 和 subagents，并允许主 Agent 自动调用或手动 @ 调用 subagent。

51. 不要一开始就搞 Multi-Agent

一个非常重要的工程原则：

单 Agent 能解决的问题，不要上 Multi-Agent。

因为 Multi-Agent 会增加：

复制代码

context
coordination
latency
cost
failure modes

应该：

sql 复制代码

Simple task
→ single agent

Complex investigation
→ subagent

Large independent work
→ parallel agents

52. AI 软件工程的真正抽象

最终你会发现：

diff 复制代码

Agent
=
Model
+
Context
+
Tools
+
Policy
+
Feedback
+
Memory

而不是：

ini 复制代码

Agent = LLM

这是理解整个 AI Coding 领域非常重要的一点。

53. Python 项目推荐目录

如果让我从零设计一个 AI-native Python repository，我会考虑：

objectivec 复制代码

project/
│
├── AGENTS.md
│
├── pyproject.toml
├── uv.lock
│
├── src/
├── tests/
│
├── docs/
│
├── scripts/
│
└── .opencode/
    │
    ├── commands/
    │   ├── test.md
    │   ├── review.md
    │   ├── debug.md
    │   ├── security.md
    │   └── release.md
    │
    ├── skills/
    │   ├── python-review/
    │   │   └── SKILL.md
    │   ├── database-migration/
    │   │   └── SKILL.md
    │   └── api-review/
    │       └── SKILL.md
    │
    ├── agents/
    │   ├── debugger.md
    │   ├── reviewer.md
    │   └── architect.md
    │
    ├── tools/
    │
    └── plugins/

这已经不再只是：

"给程序员加一个 AI。"

而是：

给整个 Repository 建立一个 AI Engineering Interface。

54. 推荐的 Python 工程配置

一个比较合理的 Python 基础设施：

diff 复制代码

Python
+
uv
+
ruff
+
mypy / pyright
+
pytest
+
coverage
+
pre-commit
+
Docker
+
GitHub Actions
+
OpenCode

其中：

bash 复制代码

OpenCode
   ↓
ruff
   ↓
type checker
   ↓
pytest
   ↓
integration test
   ↓
CI

形成完整反馈闭环。

55. 一个完整 Feature Workflow

假设需求：

添加退款功能。

推荐：

Step 1

bash 复制代码

/init

确保项目规则完整。

Step 2

Plan：

diff 复制代码

Analyze how refunds should be implemented.

Do not modify files.

Trace:

- API layer
- application service
- domain model
- payment provider
- persistence
- events
- tests

Identify:
- affected modules
- invariants
- failure modes
- idempotency requirements
- transaction boundaries

Propose an implementation plan.

Step 3

Review plan。

如果架构没问题：

diff 复制代码

Implement the approved plan.

Constraints:

- preserve public API compatibility
- refund must be idempotent
- do not change payment capture semantics
- add unit tests
- add integration tests
- do not modify unrelated code

Step 4

运行：

arduino 复制代码

uv run pytest tests/unit/payment/

Step 5

然后：

arduino 复制代码

uv run pytest

Step 6

再：

arduino 复制代码

uv run ruff check .
uv run mypy src/

Step 7

Git：

css 复制代码

git diff
git diff --check

56. Debug Workflow

生产 bug：

javascript 复制代码

Sentry
  ↓
Error
  ↓
Issue
  ↓
OpenCode
  ↓
Explore
  ↓
Logs
  ↓
Source
  ↓
Test
  ↓
Fix
  ↓
Regression
  ↓
PR

如果接入 Sentry MCP，Agent 甚至可以从错误事件直接追到代码。

这就是 MCP 真正有价值的地方：

把"代码上下文"扩大成"软件系统上下文"。

57. Dependency Upgrade

例如：

复制代码

FastAPI 0.x
→
FastAPI 新版本

不要：

复制代码

升级依赖

应该：

diff 复制代码

Analyze the dependency upgrade.

Find:

- current version
- transitive dependencies
- breaking changes
- deprecated APIs
- affected code
- test coverage

Do not change anything.

Return migration plan.

然后：

vbnet 复制代码

Implement the upgrade.

Constraints:

- do not upgrade unrelated dependencies
- preserve public API
- update tests where behavior intentionally changed
- run full test suite

58. Database Migration

数据库迁移是最不应该让 Agent 随便干的事情之一。

正确：

diff 复制代码

Analyze migration.

Do not execute migration.

Check:

- current schema
- ORM models
- existing migrations
- indexes
- constraints
- backward compatibility
- deployment ordering
- rollback strategy

然后：

erlang 复制代码

Generate migration.

Do not modify existing migration files.

Create a new migration.

Do not run against production.

59. API 设计

Agent 很容易：

复制代码

为了让测试通过
↓
改变 API

因此 AGENTS.md 应明确：

vbnet 复制代码

Public API changes require explicit approval.

尤其是：

css 复制代码

REST
GraphQL
gRPC
events
webhooks

60. Performance Optimization

不要：

复制代码

帮我优化性能。

而应该：

diff 复制代码

Measure first.

Do not optimize based on intuition.

Collect evidence using:

- profiling
- query counts
- latency measurements
- memory usage
- benchmark

Then propose optimizations.

Every optimization must include:
- baseline
- change
- result
- regression risk

这会大幅减少 AI 的"玄学优化"。

61. Security Audit

可以建立：

复制代码

security-audit

Skill。

重点：

csharp 复制代码

SQL injection
SSRF
RCE
path traversal
auth bypass
IDOR
secret leakage
deserialization
dependency vulnerabilities
unsafe subprocess

要求：

diff 复制代码

Only report vulnerabilities with evidence.

Include:
- attack surface
- exploitability
- impact
- evidence
- remediation

62. Code Review

优秀的 AI Review 不应该主要告诉你：

复制代码

这里可以改成 list comprehension。

而应该关注：

sql 复制代码

transaction bug
race condition
authorization bypass
incorrect retry
data corruption
API incompatibility
resource leak
N+1 query
missing idempotency

因此 Review Agent 的 system prompt 应该：

correctness > style

63. 一个重要原则：不要让 AI 通过"降低标准"解决问题

这是 Coding Agent 最常见的失败模式之一。

例如：

复制代码

mypy failed

AI：

python 复制代码

# type: ignore

或者：

python 复制代码

Any

或者：

python 复制代码

except Exception:
    pass

或者：

vbnet 复制代码

pytest.mark.skip

这些都可能让 CI 变绿。

但工程质量下降了。

所以 AGENTS.md 必须写：

diff 复制代码

Do not suppress failures merely to make CI green.

Do not:
- add type: ignore without justification
- replace types with Any
- skip tests
- weaken assertions
- swallow exceptions
- disable lint rules

64. OpenCode 的核心使用哲学

如果让我把整个文档压缩成 10 条：

1

先理解，再修改。

2

先 Plan，再 Build。

3

任务越大，拆得越细。

4

所有行为变化必须有测试。

5

所有高风险操作都需要权限控制。

6

把项目知识写进 AGENTS.md。

7

把重复流程写成 Skills / Commands。

8

把外部系统通过 MCP 接入，而不是把信息复制进 prompt。

9

用 Git diff 和测试作为 Agent 的反馈闭环。

10

不要把"模型聪明"当成"系统可靠"。

65. 一个成熟的 OpenCode Workflow

最终建议形成：

css 复制代码

                     Requirement
                          │
                          ▼
                       Explore
                          │
                          ▼
                         Plan
                          │
                          ▼
                   Human Approval
                          │
                          ▼
                        Build
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
             Code        Test        LSP
              │           │           │
              └───────────┼───────────┘
                          ▼
                        Review
                          │
                  ┌───────┴────────┐
                  ▼                ▼
               Security          Tests
                  │                │
                  └───────┬────────┘
                          ▼
                        Diff
                          │
                          ▼
                         PR
                          │
                          ▼
                        Human
                          │
                          ▼
                        Merge

这才是生产级 AI Coding。

66. OpenCode 不应该被当成"ChatGPT for code"

这是最重要的认知升级。

如果你把 OpenCode 当：

diff 复制代码

ChatGPT
+
Terminal

你只发挥了它很小的一部分能力。

真正应该把它看成：

复制代码

AI Software Engineering Runtime

它连接：

复制代码

Model
Context
Repository
Tools
Tests
Git
MCP
LSP
Policies
Skills
Commands
Plugins

最终形成：

AI-native development environment

67. 企业级架构

如果在公司内部部署，我会设计：

markdown 复制代码

                   Developer
                       │
                       ▼
                    OpenCode
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
       Company       Rules        Model
       Gateway       Engine       Router
          │            │            │
          ▼            ▼            ▼
       MCP/API     Policy       Claude/GPT
          │                         │
          ▼                         ▼
     Jira/Sentry/GitHub          LLM
          │                         │
          └────────────┬────────────┘
                       ▼
                    Sandbox
                       │
                ┌──────┼──────┐
                ▼      ▼      ▼
               Git    Test    Build
                       │
                       ▼
                      CI
                       │
                       ▼
                       PR

这时候 OpenCode 就不再只是个人工具。

它开始变成：

Software Engineering Platform。

68. 如何衡量 OpenCode 到底有没有提高生产力？

不要看：

"AI 写了多少行代码。"

这个指标基本没意义。

应该看：

Time to First Working Change

复制代码

需求 → 第一个可工作的 PR

Review Burden

复制代码

AI PR
→
人工 review 时间

Regression Rate

复制代码

AI changes
→
生产 bug

Rework Rate

复制代码

第一次实现
→
需要重写多少

Task Completion Rate

复制代码

Agent 接任务
→
真正完成的比例

Developer Throughput

复制代码

工程师 / week

这些才是真正的生产力指标。

69. 什么时候不应该使用 OpenCode？

不要把所有事情都交给 Agent。

尤其谨慎：

复制代码

生产数据库
金融交易
安全策略
认证系统
加密算法
数据迁移
基础设施删除
权限系统
核心并发逻辑

不是说：

AI 永远不能做。

而是：

这些任务必须拥有更高等级的验证和人工审批。

70. 最终的 AI-Native Python Engineering

未来成熟的 Python 工程团队可能不是：

复制代码

10 programmers

而是：

diff 复制代码

5 engineers

+

Coding Agents

+

Review Agents

+

Debug Agents

+

Security Agents

+

CI Agents

人类负责：

arduino 复制代码

architecture
requirements
trade-offs
risk
business logic
final judgment

Agent 负责：

sql 复制代码

search
implementation
testing
refactoring
documentation
debugging
mechanical migration

这才是 AI Coding 真正改变软件工程的地方。

71. 推荐的最终 Repository 结构

如果让我给一个资深 Python 团队设计最终版本，大概是：

arduino 复制代码

repo/
│
├── AGENTS.md
│
├── pyproject.toml
├── uv.lock
│
├── src/
├── tests/
│
├── docs/
│
├── scripts/
│
├── .github/
│   └── workflows/
│
└── .opencode/
    │
    ├── agents/
    │   ├── architect.md
    │   ├── debugger.md
    │   ├── reviewer.md
    │   └── security.md
    │
    ├── commands/
    │   ├── test.md
    │   ├── review.md
    │   ├── debug.md
    │   ├── security.md
    │   ├── benchmark.md
    │   └── release.md
    │
    ├── skills/
    │   ├── python-review/
    │   ├── database-migration/
    │   ├── api-design/
    │   ├── performance/
    │   └── security/
    │
    ├── tools/
    │
    └── plugins/

这套结构的真正价值不是"配置很多"。

而是把：

复制代码

个人经验

转化为：

复制代码

机器可执行的工程规范

72. 结论

对于资深 Python 工程师，我认为 OpenCode 最值得学习的并不是：

复制代码

怎么安装
怎么输入 prompt
怎么让 AI 写一个 FastAPI endpoint

这些只是入门。

真正值得掌握的是：

markdown 复制代码

                 AI Engineer
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
      Model        Context       Tools
        │            │            │
        │         AGENTS.md       │
        │         Skills          │
        │         Rules           │
        │                         │
        └────────────┬────────────┘
                     ▼
                   Agent
                     │
            ┌────────┼────────┐
            ▼        ▼        ▼
           Plan    Build    Review
            │        │        │
            └────────┼────────┘
                     ▼
                   Tests
                     │
                     ▼
                    Git
                     │
                     ▼
                     CI
                     │
                     ▼
                    PR

OpenCode 的真正价值，是把 LLM 变成一个可以进入真实软件工程环境、理解代码库、使用工具、执行任务、接受测试反馈并持续迭代的软件工程 Agent。

而对于 Python 资深工程师，最值得建立的能力不是：

"怎么让 AI 写更多代码。"

而是：

"怎么设计一个让 AI 能可靠完成软件工程任务的环境。"

这也是从 AI-assisted coding 走向 AI-native software engineering 的关键一步。

OpenCode 深度使用指南

面向 Python 开发工程师

目录

1. OpenCode 是什么

2. 为什么 Python 工程师应该关注它

3. OpenCode 的整体架构

3.1 Model

3.2 Agent

3.3 Tools

3.4 Context

4. 安装 OpenCode

5. Provider 与模型

6. Provider 配置

7. Python 项目初始化

8. AGENTS.md：OpenCode 最重要的工程配置

9. Python 项目的 AGENTS.md 推荐结构

10. AGENTS.md 应该写什么？

① 怎么运行

② 怎么测试

③ 怎么 lint

④ 项目架构是什么

⑤ 哪些东西绝对不能碰

⑥ 哪些设计原则必须遵守

11. Global AGENTS.md

12. Plan 与 Build

Plan

Build

13. 为什么应该先 Plan 再 Build？

14. 资深工程师最推荐的工作模式

15. 如何给 OpenCode 下任务

16. 一个重要原则：告诉 Agent"不要做什么"

17. Python Debug Workflow

18. "测试绿了"不等于"问题解决了"

19. Refactoring Workflow

20. Git 是 Agent 的"安全网"

21. 不要让 Agent 随便 commit

22. Monorepo

23. Python Monorepo 的推荐规则

24. Skills

25. Python 项目可以建立哪些 Skill？

26. Python Review Skill

27. Skill 的一个高级原则

28. Custom Commands

29. Python 项目推荐 Commands

30. /test Command

31. MCP

32. Python 开发为什么需要 MCP？

33. MCP 配置

34. 一个非常重要的 MCP 原则

35. Custom Tools

36. 为什么 Python 工程师特别适合 Custom Tools？

37. Plugin

38. Plugin 的企业级用途

39. LSP

40. Python 项目的理想验证链

41. Permission：不要忽视

42. Python 企业项目推荐权限

43. Secrets

44. Python 项目的 Sandbox

45. Context Management

46. Context Engineering

47. 为什么"让 AI 读完整个项目"通常不是好方法？

48. Debug Agent

49. Review Agent

50. Multi-Agent

51. 不要一开始就搞 Multi-Agent

52. AI 软件工程的真正抽象

53. Python 项目推荐目录

54. 推荐的 Python 工程配置

55. 一个完整 Feature Workflow

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

56. Debug Workflow

57. Dependency Upgrade

58. Database Migration

30. `/test` Command