摘要

随着大型语言模型（LLM）在软件开发领域的广泛应用，编码类智能体已成为提升开发者生产力的重要工具。然而，如何设计高效的提示词工程，使智能体能够在复杂编码任务中表现出色，仍是当前研究的重点问题。本文以OpenCode开源项目为研究对象，深入分析了其编码智能体的提示词工程设计。研究发现，OpenCode采用了模型适配性提示词、层级化提示词架构、专业化子代理设计、动态System Reminder约束机制以及可扩展的Skill系统等多项创新设计。通过对源码的系统性分析，本文详细阐述了各组件的设计原理与实现机制，为编码智能体的提示词工程提供了可借鉴的设计范式。

关键词：编码智能体、提示词工程、大型语言模型、Agent系统设计、软件工程自动化

---

1 引言

1.1 研究背景

近年来，以GPT、Claude等为代表的大型语言模型在代码生成与理解方面展现出卓越的能力。基于这些模型构建的编码智能体（Coding Agent）能够理解自然语言指令、读写代码文件、执行终端命令、搜索代码库，已成为软件开发领域的重要辅助工具。

然而，编码任务的复杂性对智能体提出了更高要求。不同于简单的问答任务，编码工作涉及代码理解、文件操作、命令执行、测试验证等多个环节，需要智能体具备规划、推理、工具调用等综合能力。提示词工程（Prompt Engineering）作为连接人类意图与模型能力的关键桥梁，其设计质量直接影响智能体的任务完成效果。

1.2 研究问题

当前编码智能体的提示词设计存在以下挑战：

1. 模型差异性：不同LLM提供商（如Anthropic、OpenAI、Google等）的模型在能力特点、响应格式、工具调用机制上存在差异，需要针对性的提示词优化。

2. 任务复杂性：复杂编码任务需要多步骤推理、子任务分解、上下文管理，如何设计提示词引导模型高效完成。

3. 安全可控：智能体执行文件编辑、命令运行等操作存在风险，如何通过提示词确保行为安全。

4. 可扩展性：不同项目有不同的代码规范和开发流程，如何支持项目级定制。

1.3 研究贡献

本文以OpenCode开源项目为案例，首次系统性地分析了一个生产级编码智能体的提示词工程设计。主要贡献包括：

• 提出了编码智能体的模型适配性提示词设计框架
• 设计了层级化提示词架构的组织方法
• 实现了动态System Reminder约束机制用于模式切换
• 构建了专业化子代理系统降低单次提示词复杂度
• 分析了Skill可扩展机制支持项目级定制

1.4 论文结构

本文组织如下：
第2节介绍相关工作；
第3节概述OpenCode系统架构；
第4节详细分析提示词工程设计；
第5节探讨关键技术实现；
第6节讨论设计特点与局限性；
第7节总结全文并展望未来工作。

---

2 相关工作

2.1 编码智能体研究现状

编码智能体研究近年来发展迅速。早期工作如Copilot专注于代码补全，而新一代智能体如Devin、Claude Code、Cursor等已能够自主完成完整软件开发任务。

这些系统通常采用ReAct范式，通过循环执行"思考-行动-观察"步骤完成任务。Toolformer等工作探索了如何让模型学习使用工具，而AutoGPT等项目则尝试通过提示词工程实现自主Agent。

2.2 提示词工程研究

提示词工程是释放LLM能力的关键技术。CoT（Chain-of-Thought）通过引导模型展示推理过程提升复杂任务表现。Few-shot Learning利用示例帮助模型理解任务模式。System Prompt（系统提示词）作为最高优先级的指令载体，在定义Agent行为中扮演核心角色。

2.3 现有系统的局限性

现有编码智能体在提示词设计上存在以下不足：

• 缺乏模型适配：大多使用统一提示词，未针对不同模型优化
• 单点式设计：所有指令集中在单一系统提示词，难以维护
• 约束机制薄弱：依赖模型的隐式理解，缺乏强制性约束
• 扩展性不足：不支持项目级自定义指令

OpenCode的设计在上述方面均有创新性改进。

---

3 OpenCode系统架构概述

3.1 项目简介

OpenCode是一个开源的AI编码智能体，采用TypeScript开发，使用Effect框架进行依赖注入，Vercel AI SDK进行LLM交互。其核心设计理念包括：

• 交互式CLI：面向命令行界面的用户体验
• 工具驱动：通过文件操作、代码搜索、命令执行等工具完成任务
• 安全优先：基于规则的权限控制系统
• 可扩展：支持Skill系统扩展功能

3.2 核心组件

OpenCode的核心组件及其功能如下：

组件	位置	功能描述
Agent系统	src/agent/	定义多种专业代理及其权限配置
会话管理	src/session/	消息处理、LLM交互、上下文管理
工具系统	src/tool/	文件操作、代码搜索、命令执行等
Skill系统	src/skill/	可扩展的技能库机制
权限系统	src/permission/	基于规则的工具访问控制

3.3 Agent执行流程

OpenCode的Agent执行遵循标准的ReAct循环：

用户输入 → 会话处理 → Agent Loop → LLM推理 → 工具调用 → 结果反馈
                ↑                                      ↓
                └──────────────────────────────────────┘

主循环位于src/session/prompt.ts的runLoop函数中，实现消息过滤、上下文压缩、子任务处理、LLM调用等核心逻辑。

---

4 提示词工程详细设计

4.1 模型适配性提示词设计

4.1.1 设计动机

不同LLM提供商在模型架构、训练数据、能力特点上存在显著差异。例如：

• Claude模型在遵循指令、长文本理解方面表现优异
• GPT-4系列在代码生成、工具调用方面有优势
• Gemini模型在多模态、长上下文方面有特色

OpenCode设计了模型适配性提示词系统，根据使用的模型选择最优提示词模板。

4.1.2 实现机制

模型选择逻辑位于src/session/system.ts：

export function provider(model: Provider.Model) {
  if (model.api.id.includes("gpt-4") || model.api.id.includes("o1") || model.api.id.includes("o3"))
    return [PROMPT_BEAST] // 激进自主模式
  if (model.api.id.includes("gpt")) {
    if (model.api.id.includes("codex")) return [PROMPT_CODEX]
    return [PROMPT_GPT] // 标准GPT模式
  }
  if (model.api.id.includes("gemini-")) return [PROMPT_GEMINI]
  if (model.api.id.includes("claude")) return [PROMPT_ANTHROPIC]
  if (model.api.id.toLowerCase().includes("trinity")) return [PROMPT_TRINITY]
  if (model.api.id.toLowerCase().includes("kimi")) return [PROMPT_KIMI]
  return [PROMPT_DEFAULT] // 默认模式
}

4.1.3 各模型提示词特点对比

模型类型	提示词文件	核心特点	指令风格
Default	default.txt	极简响应（<4行）	直接命令式
Claude	anthropic.txt	TodoWrite强调，并行执行	任务分解式
GPT	gpt.txt	资深工程师人设，进度更新	渐进式验证
Beast	beast.txt	自主Agent模式，互联网研究	激进迭代
Gemini	gemini.txt	计划优先	结构化分析

以GPT提示词（gpt.txt）为例，其设计特点包括：

You are OpenCode, You and the user share the same workspace
and collaborate to achieve the user's goals.

You are a deeply pragmatic, effective software engineer.
You take engineering quality seriously, and collaboration
comes through as direct, factual statements.

该提示词为模型塑造了"资深工程师"的人设，强调务实、直接的工作风格，并明确了两个关键响应通道：

• commentary通道：用于工作过程中的进度更新
• final通道：用于任务完成的最终响应

4.2 层级化提示词架构

4.2.1 架构设计

OpenCode采用层级化方式组织提示词，从底向上依次叠加：

┌─────────────────────────────────────────┐
│  Level 5: System Reminders (动态)       │ ← 模式切换、约束注入
├─────────────────────────────────────────┤
│  Level 4: Custom Instructions            │ ← AGENTS.md/CLAUDE.md
├─────────────────────────────────────────┤
│  Level 3: Skills Prompt                │ ← 可用技能清单
├─────────────────────────────────────────┤
│  Level 2: Environment Prompt           │ ← 工作目录、平台、日期
├─────────────────────────────────────────┤
│  Level 1: Provider Prompt (基础)       │ ← 模型适配提示词
└─────────────────────────────────────────┘

4.2.2 各层级详细内容

层级1：Provider Prompt

基础提示词由src/session/prompt/*.txt提供，定义Agent的基本行为模式。

层级2：Environment Prompt

动态注入运行时环境信息（src/session/system.ts）：

export async function environment(model: Provider.Model) {
  return [
    `You are powered by the model named ${model.api.id}`,
    `<env>`,
    `  Working directory: ${Instance.directory}`,
    `  Workspace root folder: ${Instance.worktree}`,
    `  Is directory a git repo: ${project.vcs === "git" ? "yes" : "no"}`,
    `  Platform: ${process.platform}`,
    `  Today's date: ${new Date().toDateString()}`,
    `</env>`,
  ]
}

层级3：Skills Prompt

可用技能以XML格式注入：

<available_skills>
  <skill>
    <name>database-guide</name>
    <description>Guide for database operations</description>
    <location>file:///path/to/SKILL.md</location>
  </skill>
</available_skills>

层级4：Custom Instructions

支持用户通过项目级或全局级文件自定义指令：

• AGENTS.md：项目级代理配置
• CLAUDE.md：Claude Code兼容配置
• 全局配置：~/.claude/CLAUDE.md

层级5：System Reminders

动态注入的约束性指令，用于模式切换等场景。

4.3 专业化子代理设计

4.3.1 子代理分类

OpenCode定义了多种专业化子代理，降低单次提示词复杂度：

代理名称	类型	功能	Prompt长度
build	主代理	默认执行代理，全权限	模型适配
plan	主代理	计划模式，只读	模型适配 + plan.txt
explore	子代理	代码探索，grep/glob优先	18行
general	子代理	通用研究，多步骤任务	模型适配
compaction	内部代理	上下文压缩	15行
title	内部代理	会话标题生成	44行
summary	内部代理	PR描述总结	11行

4.3.2 Explore子代理设计

Explore代理专门用于快速代码库探索，其提示词设计（src/agent/prompt/explore.txt）体现了专业化原则：

You are a file search specialist. You excel at thoroughly
navigating and exploring codebases.

Your strengths:

- Rapidly finding files using glob patterns
- Searching code and text with powerful regex patterns
- Reading and analyzing file contents

Guidelines:

- Use Glob for broad file pattern matching
- Use Grep for searching file contents with regex
- Return file paths as absolute paths
- Do not create any files, or run bash commands that
  modify the user's system state in any way

该设计特点：

1. 角色明确：定义为"文件搜索专家"
2. 工具推荐：明确推荐Glob/Grep/Read工具
3. 行为约束：禁止文件修改操作
4. 输出格式：要求返回绝对路径

4.3.3 Title生成代理设计

Title代理用于自动生成会话标题，其提示词设计（src/agent/prompt/title.txt）采用few-shot示例：

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

<rules>
- you MUST use the same language as the user message
- Title must be grammatically correct
- Never include tool names in the title
- Keep exact: technical terms, numbers, filenames
</rules>

<examples>
"debug 500 errors in production" → Debugging production 500 errors
"refactor user service" → Refactoring user service
"implement rate limiting" → Rate limiting implementation
</examples>

4.4 工具描述的精细化设计

4.4.1 工具描述文件结构

OpenCode为每个工具提供了详细的.txt描述文件。以Bash工具（src/tool/bash.txt）为例：

1. 基础描述：命令执行功能说明
2. 环境信息：操作系统和Shell类型动态注入
3. 使用指南：路径引用、命令执行最佳实践
4. Git安全协议：防止危险操作的详细规则
5. PR创建流程：GitHub相关任务的标准化流程

4.4.2 安全相关指令

Bash工具描述中包含详细的Git安全协议：

Git Safety Protocol:

- NEVER update the git config
- NEVER run destructive/irreversible git commands
  (like push --force, hard reset, etc) unless explicitly requested
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless requested
- NEVER force push to main/master
- Avoid git commit --amend. ONLY use --amend when ALL conditions met:
  (1) User explicitly requested amend, OR commit SUCCEEDED...
  (2) HEAD commit was created by you in this conversation
  (3) Commit has NOT been pushed to remote

这种设计将安全最佳实践编码到工具描述中，而非依赖模型隐式理解。

---

5 关键技术实现

5.1 Plan Mode系统设计

5.1.1 设计理念

Plan Mode是一种约束式Agent执行模式，通过<system-reminder>标签注入强制性约束，实现"先规划后执行"的工作流。这解决了编码智能体常见的问题：

• 过度行动：模型过于急于执行，未充分理解需求
• 上下文污染：过早修改文件影响后续理解
• 缺乏验证：缺少用户确认环节

5.1.2 权限控制机制

Plan Mode通过权限系统实现安全约束（src/agent/agent.ts）：

plan: {
  permission: Permission.merge(
    defaults,
    Permission.fromConfig({
      question: "allow",
      plan_exit: "allow",
      edit: {
        "*": "deny",  // 拒绝所有编辑
        [path.join(".opencode", "plans", "*.md")]: "allow",  // 允许编辑计划文件
      },
    }),
  ),
}

5.1.3 五阶段工作流

Plan Mode实现了结构化的五阶段工作流：

Phase 1: Initial Understanding

• 并行启动≤3个explore子代理
• 使用question工具澄清歧义
• 仅使用只读工具

Phase 2: Design

• 启动general代理设计实现方案
• 考虑多角度：简单性 vs 性能 vs 可维护性

Phase 3: Review

• 阅读关键文件验证理解
• 确保与用户意图对齐

Phase 4: Final Plan

• 写入唯一可编辑的计划文件
• 包含验证方法说明

Phase 5: plan_exit

• 调用plan_exit工具请求用户确认
• 获得批准后切换到build模式

5.1.4 模式切换实现

Plan Exit工具实现（src/tool/plan.ts）核心逻辑：

PlanExitTool.execute(_params, ctx) {
  // 1. 询问用户确认
  const answers = await Question.ask({
    question: "Plan at ${plan} is complete. Switch to build?",
    options: [
      { label: "Yes", description: "Start implementing" },
      { label: "No", description: "Stay in plan mode" },
    ],
  })

  // 2. 用户拒绝则终止
  if (answer === "No") throw new Question.RejectedError()

  // 3. 创建build类型的user消息，触发agent切换
  const userMsg: MessageV2.User = { agent: "build", model }
  await Session.updateMessage(userMsg)
}

5.2 System Reminder机制

5.2.1 机制原理

<system-reminder>是OpenCode设计的核心约束机制，具有以下特点：

• 语义区分：与用户消息、工具结果区分
• 强制覆盖：可覆盖其他指令的约束
• 动态注入：可在运行时添加到任意消息

5.2.2 注入时机

System Reminder在以下时机注入：

1. Plan Mode激活（src/session/prompt/plan.txt）：

<system-reminder>
CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase.
ANY file edits, modifications... STRICTLY FORBIDDEN.
</system-reminder>

2. Plan→Build切换（src/session/prompt/build-switch.txt）：

<system-reminder>
Your operational mode has changed from plan to build.
You are no longer in read-only mode.
</system-reminder>

3. 用户中断（src/session/prompt.ts）：

if (step > 1 && lastFinished) {
  for (const m of msgs) {
    if (m.info.role !== "user") continue
    p.text = [
      "<system-reminder>",
      "The user sent the following message:",
      p.text,
      "Please address this message and continue with your tasks.",
      "</system-reminder>",
    ].join("\n")
  }
}

4. 达到最大步数（src/session/prompt/max-steps.txt）：

CRITICAL - MAXIMUM STEPS REACHED
Tools are disabled until next user input.

STRICT REQUIREMENTS:

1. Do NOT make any tool calls
2. MUST provide a text response summarizing work done
3. This constraint overrides ALL other instructions

5.3 Skill可扩展系统

5.3.1 Skill定义格式

Skill以Markdown格式定义，支持YAML frontmatter：

---
name: database-guide
description: Guide for database operations in this project
---
# Skill content here

5.3.2 发现机制

Skill发现支持多种路径（src/skill/index.ts）：

• 全局：~/.claude/skills/**/SKILL.md
• 项目级：.claude/skills/**/SKILL.md
• 兼容路径：.agents/skills/**/SKILL.md
• OpenCode内置：{skill,skills}/**/SKILL.md

5.3.3 权限过滤

每个Agent可用的Skills经过权限过滤：

const available = Effect.fn("Skill.available")(function* (agent?: Agent.Info) {
  const s = yield* InstanceState.get(state)
  const list = Object.values(s.skills)
  return list.filter((skill) => Permission.evaluate("skill", skill.name, agent.permission).action !== "deny")
})

5.4 上下文管理

5.4.1 消息过滤

主循环中通过MessageV2.filterCompactedEffect过滤已压缩的消息：

while (true) {
  let msgs = yield * MessageV2.filterCompactedEffect(sessionID)
  // ... 处理消息
}

5.4.2 上下文压缩

当上下文超过模型限制时，触发压缩流程：

1. 使用compaction代理生成对话摘要
2. 保留关键决策和工具结果
3. 替换为压缩后的摘要文本

---

6 讨论

6.1 设计特点总结

通过深入分析OpenCode的提示词工程设计，我们总结出以下关键设计原则：

设计原则	实现方式	设计价值
模型适配	多套prompt模板 + 动态选择	最大化各模型潜力
层级解耦	分层组织提示词组件	提高可维护性
专业分工	子代理承担特定任务	降低单次prompt复杂度
强制约束	System Reminder机制	确保关键规则被遵守
权限分离	规则化权限系统	安全保障
可扩展性	Skill发现机制	项目级定制支持

6.2 与现有工作的比较

特性	OpenCode	AutoGPT	Claude Code
模型适配提示词	✓	✗	部分
System Reminder机制	✓	✗	✗
子代理系统	✓	简单	✗
Plan Mode	✓	✗	✓
Skill扩展	✓	✗	✓
权限控制	规则化	无	隐式

6.3 局限性

本研究存在以下局限性：

1. 评估局限：未进行系统性的性能评估实验
2. 模型覆盖：当前分析的prompt模板主要面向英文模型
3. 动态优化：未涉及提示词的自动优化或学习机制

6.4 实践启示

本研究为编码智能体的提示词工程提供了以下实践建议：

1. 模型感知设计：针对不同模型设计适配性提示词
2. 约束显式化：关键安全规则通过System Reminder强制注入
3. 任务分解：使用子代理降低单次提示词复杂度
4. 渐进式执行：复杂任务采用Plan→Build模式
5. 可扩展架构：支持项目级自定义指令

---

7 结论

本文以OpenCode开源项目为案例，深入分析了编码类智能体的提示词工程设计。研究发现，OpenCode通过模型适配性提示词、层级化提示词架构，专业化子代理设计、动态System Reminder约束机制以及可扩展的Skill系统等多项创新设计，构建了一个高效、安全、可扩展的编码智能体系统。

主要贡献包括：

1. 提出了编码智能体的模型适配性提示词设计框架，根据不同LLM特点选择最优提示词模板

2. 设计了层级化提示词架构，从基础提示词到动态约束分层组织，提高可维护性

3. 实现了动态System Reminder约束机制，通过<system-reminder>标签实现模式切换和安全约束

4. 构建了专业化子代理系统，通过explore、general等子代理降低单次提示词复杂度

5. 分析了Skill可扩展机制的设计实现，支持项目级定制

未来的工作方向包括：

• 开展系统性性能评估实验，验证不同提示词策略的效果
• 探索提示词的自动优化机制，基于反馈迭代改进
• 研究多模态编码智能体的提示词设计
• 扩展到更广泛的软件工程自动化场景