18.3 构建 AI 编程助手的最佳实践

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-18

---

前两节我们分别从 OpenCode 和 oh-my-opencode 的角度提炼了设计智慧。本节将这些经验整合，形成一套可操作的最佳实践指南——如果你要从零构建一个 AI 编程助手，这些就是最值得遵循的原则。

18.3.1 Prompt 工程最佳实践

System Prompt 的分层架构

OpenCode 的 System Prompt 不是一个整块——它由多个层级拼接而成（第 6.4.3 节）：

最终 System Prompt = [
  基础 Prompt (anthropic.txt / beast.txt / ...)    ← 模型适配层
  + Agent 专属 Prompt                                ← Agent 角色层
  + 环境信息 (OS, Shell, 工作目录, Git 状态)         ← 运行时上下文层
  + 项目指令 (AGENTS.md / CLAUDE.md / CONTEXT.md)    ← 用户指令层
  + Plugin 注入 (experimental.chat.system.transform)  ← 扩展层
]

这种分层设计的好处：

层级	变更频率	维护者
模型适配层	低（新模型发布时）	OpenCode 核心开发者
Agent 角色层	中（Agent 行为调优时）	Agent 设计者
运行时上下文层	每次会话	系统自动
用户指令层	按项目	用户 / 团队
扩展层	按 Plugin	Plugin 开发者

实践建议：将 System Prompt 拆分为独立维护的层级。每个层级有明确的职责和变更频率，避免一个巨大的单体 Prompt。

按模型差异化适配

不同 LLM 对 Prompt 的理解存在显著差异。OpenCode 为主流模型家族维护了独立的基础 Prompt：

• Claude 系列（anthropic.txt）：充分利用 XML 标签结构化指令

• GPT 系列（beast.txt）：适配 OpenAI 的系统消息风格

• Gemini 系列（gemini.txt）：适配 Google 模型的特点

• 其他模型（qwen.txt）：通用的精简版本，去掉了某些模型不支持的特性（如 Todo 工具）

实践建议：不要假设一套 Prompt 适用所有模型。至少按模型家族维护不同版本，特别关注：

• 是否支持 Tool Use / Function Calling

• 上下文窗口大小差异

• 指令遵循的风格偏好（XML 标签 vs Markdown vs 纯文本）

工具描述的重要性

LLM 选择使用哪个工具、如何传递参数，完全依赖工具的 description 字段。OpenCode 中每个工具都有精心编写的描述文本（存储在 .txt 文件中）。

一个好的工具描述应该包含：

1. 工具做什么（一句话）
2. 何时使用（使用场景）
3. 何时不使用（避免滥用）
4. 参数说明（每个参数的含义和约束）
5. 输出格式（LLM 应该如何解读输出）

以 OpenCode 的 read 工具为例，它的描述不只是"读取文件"，而是详细说明了行号格式、图片文件的处理、PDF 页码限制等细节。这些信息帮助 LLM 做出正确的决策。

实践建议：投入足够的精力编写工具描述。工具描述的质量直接决定了 AI Agent 的行为质量。一个含糊的描述会导致 LLM 频繁误用工具。

18.3.2 安全性最佳实践

权限最小化原则

OpenCode 的权限系统（第 9 章）遵循严格的最小权限原则：

默认行为：所有操作都需要用户确认（ask）
    │
    ▼
Agent 级权限：build Agent 允许大部分操作
    │
    ▼
用户级权限：用户可以进一步放宽或收紧
    │
    ▼
Session 级权限：运行时的临时授权

关键设计：

• Bash 命令需要按命令内容匹配权限（bash("rm *") ≠ bash("ls")）

• 文件写入需要按路径匹配权限（写 src/ ≠ 写 /etc/）

• .env 文件有特殊保护——即使 Agent 有 read 权限，读取 .env 也需要额外确认

• 外部目录访问有专门的 external_directory 权限控制

实践建议：

1. 默认拒绝所有操作，按需开放

2. 对敏感操作（文件删除、外部访问、密钥读取）设置额外保护层

3. 区分"一次性授权"和"永久授权"，让用户有选择权

4. 记录所有权限决策，便于审计

文件操作的沙箱化

OpenCode 通过以下机制限制 AI 对文件系统的影响范围：

保护机制	实现方式	防护目标
项目目录限制	工具默认只操作项目目录内的文件	防止 AI 修改系统文件
.gitignore 遵守	file/ignore.ts 解析 gitignore 规则	防止 AI 读取/修改被忽略的文件
外部目录保护	external_directory 权限	防止 AI 访问项目外的目录
输出截断	truncation.ts 限制工具输出长度	防止大文件内容淹没上下文

实践建议：永远假设 AI 会尝试做"意料之外"的事情。建立多层防护，即使某一层被绕过，其他层仍然有效。

Snapshot 作为安全网

OpenCode 的 Snapshot 系统（第 10.1 节）是最后一道安全防线：

文件写入前 → 自动创建快照 → 写入文件
                                │
                                ▼
                          发现问题？
                                │
                                ▼
                          恢复快照 → 文件回滚

实践建议：在 AI 修改任何文件之前，都应该有可回滚的机制。Snapshot 的成本极低（本质上是 git add + git commit），但价值极高——它让用户敢于让 AI 做大规模的代码修改。

18.3.3 性能优化

上下文窗口管理

上下文窗口是 LLM 最宝贵的资源。OpenCode 通过三级策略管理它（第 4.5 节）：

第一级：Prune（修剪）

当上下文接近上限时：
1. 从最早的消息开始
2. 找到包含工具输出的消息
3. 将工具输出截断为摘要
4. 保护最近 PRUNE_PROTECT (40,000 tokens) 的内容不被修剪

Prune 是"非破坏性"的——它只压缩工具输出，不删除消息本身。

第二级：Compaction（压缩）

当 Prune 不够用时：
1. 将所有旧消息发送给 LLM
2. 要求 LLM 生成一份摘要
3. 用摘要替换所有旧消息

Compaction 是"有损压缩"——旧消息的细节会丢失，但关键信息通过摘要保留。

第三级：Preemptive Compaction（先发制人压缩，oh-my-opencode）

不等到溢出才压缩，而是在上下文使用率达到阈值时就主动触发。
这避免了"溢出 → 压缩 → 短暂可用 → 再溢出"的震荡。

实践建议：

1. 工具输出是上下文的最大消费者——优先对工具输出进行截断和摘要

2. 实现渐进式的上下文管理（Prune → Compaction），而非一步到位的粗暴截断

3. 在上下文接近上限之前就开始管理，而非等到溢出

4. 为 Compaction 的摘要 Prompt 投入足够的设计精力——摘要的质量决定了压缩后 AI 的"记忆"质量

Token 节约策略

每一个 Token 都有成本。以下是 OpenCode 和 oh-my-opencode 中的 Token 节约实践：

策略	实现	节约效果
工具输出截断	truncation.ts、tool-output-truncator Hook	防止大文件消耗过多 Token
低成本 Agent 优先	oh-my-opencode 的 Explore Agent 使用便宜模型	搜索类任务用小模型完成
选择性信息注入	只在相关场景注入上下文	避免每条消息都带大段 Prompt
上下文隔离	子 Agent 有独立上下文	搜索结果不会污染编码 Agent 的上下文
精确搜索	Grep/Glob 只返回匹配行	避免将整个文件读入上下文

实践建议：像管理内存一样管理 Token。每次向上下文中添加内容时，都问自己：这些信息对 AI 的下一步决策真的必要吗？

并行工具执行

OpenCode 的 batch 工具（第 5.3.2 节）允许 AI 同时执行多个独立的工具调用：

// AI 可以同时读取多个文件，而非依次读取
batch({
  tasks: [
    { tool: "read", args: { file_path: "src/a.ts" } },
    { tool: "read", args: { file_path: "src/b.ts" } },
    { tool: "read", args: { file_path: "src/c.ts" } },
  ]
})

oh-my-opencode 更进一步——通过后台 Agent 系统（第 15.6.1 节）实现了 Agent 级别的并行执行。

实践建议：识别可以并行的操作并提供并行执行的能力。这不仅节约时间，还节约 Token（减少了"等待上一步结果"的循环轮次）。

18.3.4 用户体验

流式响应的重要性

AI 的响应时间可能很长（几秒到几十秒）。OpenCode 通过流式输出让用户看到"AI 正在思考"：

用户: 帮我重构这个函数
AI: 让我先看看这个函数的实现...
    [正在读取 src/utils.ts...]          ← 实时显示工具调用状态
    这个函数有以下问题：
    1. 嵌套过深...                       ← 文字逐字出现
    2. 重复的错误处理...

关键体验细节：

• 文本逐 Token 流式输出（text-delta 事件）

• 工具调用的进度可见（tool-call-start → running → completed）

• 思考链可见（reasoning-start → reasoning-delta → reasoning-end）

实践建议：永远不要让用户面对一个"空白等待"。即使只是显示"正在思考…"的旋转动画，也比什么都没有好。流式输出是 AI 产品最重要的 UX 特性之一。

进度可见性

当 AI 执行复杂任务时，用户需要知道"它在做什么、做到哪了"：

机制	实现	作用
Todo 列表	TodoWriteTool + TodoReadTool	AI 自己列出任务清单并逐个完成
工具调用展示	TUI 显示每次工具调用的名称和状态	用户可以实时追踪 AI 的操作
Session 摘要	SessionSummary 统计文件修改	用户知道 AI 修改了什么文件
Diff 展示	Snapshot diff	精确展示每个文件的变更

实践建议：让 AI 的工作过程透明可见。用户对 AI 的信任来源于"我能看到它在做什么"，而非"我相信它会做对"。

错误恢复的透明度

当 AI 出错时（比如编辑失败），系统应该：

❌ 不好的处理：
  "Error: old_string not found"（直接暴露原始错误）

✅ 好的处理（oh-my-opencode 的 edit-error-recovery）：
  "编辑失败：目标字符串在文件中不存在。
   可能的原因：文件内容已变化。
   建议：先重新读取文件，再尝试编辑。"

oh-my-opencode 的错误恢复 Hook 不只是捕获错误——它还会向 AI 注入修复建议，让 AI 能够自主尝试修复。

实践建议：

1. 将原始错误转化为 AI 能理解的指导

2. 提供具体的修复建议，而非抽象的错误码

3. 让 AI 有机会自主尝试修复，而非每次都打断用户

---

这些最佳实践的共同主题是：尊重 AI 的不确定性，同时最大化它的价值。好的 AI 编程助手不是一个"永不犯错的超级程序员"，而是一个"偶尔需要纠正、但整体高效可靠的编程伙伴"。系统设计的目标是让 AI 在犯错时快速恢复，在正确时充分发挥。