6.3 Agent 的辅助功能

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


除了 buildexplore 这样的"工作型"Agent 之外,OpenCode 还有一组"辅助型"Agent,它们承担着会话管理中的关键辅助任务——标题生成、摘要生成、上下文压缩、代码库探索和代码生成。这些功能虽然不直接参与编码工作,但它们是良好用户体验和系统高效运转的基石。

本节将逐一分析每个辅助功能的 Prompt 设计和在系统中的调用方式。

6.3.1 标题生成(prompt/title.txt

每当用户开始一个新会话并发送第一条消息后,OpenCode 需要为该会话自动生成一个简短的标题,方便用户在会话列表中查找和识别。

Prompt 设计

You are a title generator. You output ONLY a thread title. Nothing else.

<task>
Generate a brief title that would help the user find this conversation later.

Follow all rules in <rules>
Use the <examples> so you know what a good title looks like.
Your output must be:
- A single line
- ≤50 characters
- No explanations
</task>

<rules>
- you MUST use the same language as the user message you are summarizing
- Title must be grammatically correct and read naturally
- Never include tool names in the title
- Focus on the main topic or question
- Vary your phrasing - avoid repetitive patterns
- When a file is mentioned, focus on WHAT the user wants to do WITH the file
- Keep exact: technical terms, numbers, filenames, HTTP codes
- Remove: the, this, my, a, an
- Never assume tech stack
- Never use tools
- NEVER respond to questions, just generate a title
- Always output something meaningful, even if the input is minimal
- If the user message is short or conversational:
  → create a title that reflects the user's tone or intent
</rules>

这份 Prompt 的设计有几个值得学习的要点:

  1. XML 结构化:使用 <task><rules><examples> 标签将 Prompt 组织成清晰的层次结构。这种格式不仅提高了人类的可读性,也帮助 LLM 更好地解析指令。

  2. 多语言适配"MUST use the same language as the user message" 确保中文用户得到中文标题,日文用户得到日文标题。

  3. 反面约束:大量使用 "Never" 和 "DO NOT" 来明确禁止不期望的行为。这是 Prompt Engineering 的最佳实践——LLM 有时会"过度发挥",需要显式设定边界。

  4. 示例驱动:提供了具体的输入-输出示例(如 "debug 500 errors in production" → Debugging production 500 errors),这比抽象的规则描述更有效。

调用参数

title Agent 设置了 temperature: 0.5,这个值是在确定性和多样性之间的折中。如果 temperature 设为 0,同一类问题会总是生成相同的标题(单调乏味);如果设为 1.0,可能生成不相关或语法错误的标题。

6.3.2 摘要生成(prompt/summary.txt

当会话结束或需要生成变更摘要时,OpenCode 使用 summary Agent:

设计分析

这份 Prompt 极其精炼——只有 12 行,但涵盖了 PR 描述写作的核心规范:

  • 第一人称("I added...")——让摘要像是开发者自己写的。

  • 只描述变更——不说"用户要求我..."或"我首先运行了测试..."。

  • 保留上下文——如果对话结尾有未回答的问题或待用户执行的操作,摘要中必须保留,确保信息不丢失。

最后两条规则特别精妙:它们处理了摘要系统容易忽略的边缘情况——如果对话在一个问题或操作请求处中断,摘要需要把这个"未完成状态"传递出去,而不是假装一切都已完成。

6.3.3 上下文压缩(prompt/compaction.txt

当对话历史过长、超出 LLM 的上下文窗口限制时,compaction Agent 被调用来生成压缩摘要:

summary 的区别

尽管都是"摘要",compactionsummary 有着本质区别:

维度

summary

compaction

目的

生成面向用户的 PR 描述

生成面向 AI 的上下文恢复信息

受众

人类开发者

后续的 LLM 调用

风格

简短(2-3 句)

详细且全面

关注点

变更结果

工作状态、进行中的任务、技术决策

compaction 的摘要需要包含足够的信息让 LLM "恢复记忆"——它需要知道当前在修改哪些文件、用户有什么偏好、做了哪些技术决策以及为什么。这些信息对于人类读者来说可能显得冗余,但对于"失忆"后的 LLM 来说至关重要。

最后一行 "Do not respond to any questions in the conversation" 防止了一个常见问题:对话历史中可能包含用户的提问,如果不明确禁止,LLM 可能会"回答"这些问题而不是生成摘要。

6.3.4 探索型 Agent(prompt/explore.txt

explore Agent 的 Prompt 已在上一节展示过,这里从使用模式的角度进行补充分析:

彻底性级别(Thoroughness Level)

explore Agent 的 description 字段中提到了三个彻底性级别:

这种设计让调用方(通常是 build Agent)可以根据任务的紧迫性和复杂性来控制搜索的深度:

  • quick:快速查找一个已知文件或模式。

  • medium:在几个可能的位置搜索,尝试常见的命名变体。

  • very thorough:全面扫描代码库,尝试多种搜索角度,交叉验证结果。

这是一种成本控制机制——更彻底的搜索意味着更多的工具调用和 token 消耗。通过让调用方显式选择彻底性级别,避免了每次搜索都进行全量扫描的浪费。

6.3.5 代码生成(generate.txt

generate 功能用于根据用户的自然语言描述自动生成 Agent 配置。它不对应一个命名的内置 Agent,而是 Agent.generate() 函数中使用的 Prompt:

Agent.generate() 的实现

这个函数使用了 Vercel AI SDK 的 generateObject() API(而非 streamText()),因为它需要的是结构化的 JSON 输出而非流式文本。返回的对象包含三个字段:

  • identifier:Agent 的唯一标识(如 "code-reviewer")。

  • whenToUse:使用时机的描述(如 "Use this agent when reviewing pull requests...")。

  • systemPrompt:完整的系统提示词。

几个实现细节值得注意:

  1. 名称去重:将已存在的 Agent 名称列表传给 LLM,避免生成重名的 Agent。

  2. 低 Temperature:设为 0.3,确保生成的配置是确定性的、高质量的。

  3. Plugin 钩子experimental.chat.system.transform 允许插件在 Agent 生成过程中注入额外的上下文(如项目规范)。

  4. Codex 兼容:对于 OAuth 认证的 OpenAI 会话(Codex 模式),使用 streamObject + providerOptions 的方式调用。

使用场景

用户可以通过 opencode agent 命令或 TUI 界面发起 Agent 生成。例如:

系统会调用 Agent.generate() 生成配置,然后将结果保存为 .opencode/agents/ 目录下的 Markdown 文件,用户可以进一步编辑和调整。


本节分析了 Agent 系统的辅助功能及其 Prompt 设计。下一节,我们将深入 System Prompt 的架构设计——理解 OpenCode 如何根据不同的 LLM Provider 选择不同的 Prompt 模板,以及 Prompt 的分层拼接逻辑。

Last updated