系统提示词加载机制

概述

OpenCode 的系统提示词（System Prompt）采用双架构并行策略，分为 V1 架构（当前主要使用的组合式加载）和 V2 架构（基于 System Context 的新一代机制）。V2 通过 Context Epoch 支持增量更新和持久化快照。

一、提示词文件

文件清单

所有提示词模板位于 packages/opencode/src/session/prompt/，共 14 个 .txt 文件，通过 Bun 编译时静态导入 嵌入 JavaScript bundle：

import PROMPT_ANTHROPIC from "./prompt/anthropic.txt"
import PROMPT_DEFAULT   from "./prompt/default.txt"
import PROMPT_BEAST     from "./prompt/beast.txt"
import PROMPT_GEMINI    from "./prompt/gemini.txt"
import PROMPT_GPT       from "./prompt/gpt.txt"
import PROMPT_KIMI      from "./prompt/kimi.txt"
import PROMPT_CODEX     from "./prompt/codex.txt"
import PROMPT_TRINITY   from "./prompt/trinity.txt"

文件用途与模型映射

文件	匹配规则（model.api.id 包含）	风格特点
beast.txt	gpt-4 / o1 / o3	长篇结构化，自称 "the best coding agent"，强调迭代直到完成
codex.txt	gpt + codex	强调行动、轻描述，针对 GPT Codex 模型优化
gpt.txt	gpt（不含 codex）	专业、重规则，自称 "opencode, an interactive CLI agent"
gemini.txt	gemini-	简洁风格，自称 "opencode, an interactive CLI tool"
anthropic.txt	claude	简洁对话式，使用 "OpenCode" 自称
trinity.txt	trinity	强调持续直到完成
kimi.txt	kimi	最详细版本，含 AGENTS.md 长篇说明
default.txt	兜底（所有未匹配）	简明，强调工具使用

辅助文件

文件	用途
plan.txt	Plan 模式附加提示词，追加到 user message
plan-mode.txt	实验性 Plan 模式模板，含 ${planInfo} 占位符
build-switch.txt	Plan→Build 切换时的附加提示词
max-steps.txt	最大步数限制提示，追加为最后一条 assistant 消息
copilot-gpt-5.txt	遗留文件，未使用
plan-reminder-anthropic.txt	遗留文件，未使用

二、选择逻辑

定义于 packages/opencode/src/session/system.ts 的 provider() 函数：

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]
  }
  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]  // 兜底
}

匹配逻辑：基于 model.api.id 字符串包含关系，顺序判断。default.txt 是最后的兜底选项。

三、V1 架构加载流程

调用栈

用户输入
  → SessionPrompt.prompt()        [packages/opencode/src/session/prompt.ts]
    → provider(model)             [system.ts:19]     选择模型特定提示词
    → sys.environment(model)      [system.ts:48]     构建环境信息
    → instruction.system()        [instruction.ts:100] 加载 AGENTS.md
    → sys.skills(agent)           [system.ts:65]     加载技能列表
    → Plugin triggers             [prompt.ts]         插件修改 system array
    → handle.process({ system, ... })                 发送给 LLM

系统提示的组成部分

最终传入 LLM 的 system 数组按顺序拼接：

system = [...env, ...instructions, ...skills]
        ↑ 环境信息     ↑ AGENTS.md     ↑ 技能列表

1. 环境信息 (env)

定义于 system.ts:48-63，包含：

You are powered by the model named {model.api.id}.
The exact model ID is {providerID}/{modelID}
Here is some useful information about the environment you are running in:
<env>
  Working directory: {directory}
  Workspace root folder: {worktree}
  Is directory a git repo: yes/no
  Platform: {platform}
  Today's date: {date}
</env>

2. AGENTS.md / 指令 (instructions)

定义于 packages/opencode/src/session/instruction.ts:100-115，Instruction.system() 方法加载：

优先级	来源	路径
1	全局 AGENTS.md	~/.config/opencode/AGENTS.md
2	回退全局 CLAUDE.md	~/.claude/CLAUDE.md
3	项目级 AGENTS.md	从当前目录向上查找第一个 AGENTS.md/CLAUDE.md/CONTEXT.md
4	配置指定文件	opencode.json 中 config.instructions 数组（支持 URL）

格式：Instructions from: {filepath}\n{content}

就近注入机制（instruction.ts:159-195）：当 read 工具读取文件时，自动查找该文件祖先目录中的 AGENTS.md 并注入。每个 assistant message 只注入一次同一文件（通过 claims: Map<MessageID, Set<string>> 去重）。

3. 技能列表 (skills)

定义于 system.ts:65-75，列出基于 Agent 权限过滤后的可用 Skill：

Skills provide specialized instructions and workflows for specific tasks.
Use the skill tool to load a skill when a task matches its description.
- {skill_name}: {skill_description}

4. 结构化输出提示

当输出格式要求为 json_schema 时（prompt.ts 中的 STRUCTURED_OUTPUT_SYSTEM_PROMPT 常量），追加到 system 数组末尾。

5. 模型特定提示词 (model prompt)

模型选择的提示词（如 beast.txt、anthropic.txt 等）通过 AI SDK 的 system 参数传递给 LLM，不作为 system 数组成员。

Plan / Build 模式提示

通过 packages/opencode/src/session/reminders.ts 的 SessionReminders.apply() 注入：

• 非实验性 Plan 模式：当前 Agent 为 "plan" 时，向最后一条 user message 追加 plan.txt；从 plan 切换到 build 时追加 build-switch.txt
• 实验性 Plan 模式：将 plan-mode.txt 中的 ${planInfo} 替换为实际的 plan 文件路径

最大步数限制

当达到 max_steps 限制时，prompt.ts 将 max-steps.txt 追加为最后一条 assistant 消息内容，阻止 LLM 继续执行工具调用。

四、V2 架构：System Context

架构层次

packages/core/src/system-context/
  index.ts       — 核心类型：Source, SystemContext, Snapshot, Generation
  registry.ts    — SystemContextRegistry（Entry 注册与组合加载）
  builtins.ts    — 内置 Source：environment + date

核心类型

Source（可独立刷新的类型化源）

interface Source<A> {
  readonly key: string
  readonly codec: Schema.Codec<A>
  readonly load: () => Effect<A>
  readonly baseline: (value: A) => string       // 首次渲染完整文本
  readonly update: (prev: A, curr: A) => string  // 增量更新文本
  readonly removed: (value: A) => string         // 移除通知
}

SystemContext

不透明的上下文载体，包含多个 PackedSource。

Snapshot

持久化的比较状态：Record<Key, { value: Json, removed?: string }>

Generation

type Generation = { baseline: string, snapshot: Snapshot }

——不可变基线文本 + 当前快照。

ReconcileResult

type ReconcileResult = Unchanged | Updated | ReplacementReady | ReplacementBlocked

内置 Source

定义于 packages/core/src/system-context/builtins.ts:10-32：

Source Key	说明
core/environment	工作目录、工作区根目录、git 状态、平台
core/date	当前日期

AGENTS.md 作为 Source

定义于 packages/core/src/instruction-context.ts:17-54：

• Key：core/instructions
• baseline()：渲染为 Instructions from: {path}\n{content}（多个文件用 \n\n 连接）
• update()：These instructions replace all previously loaded ambient instructions.\n\n{current}
• removed()：Previously loaded instructions no longer apply.
• 加载逻辑：从当前目录向上找 AGENTS.md（停止于 project root），加上全局 AGENTS.md

System Context Registry

定义于 registry.ts:42：

1. 遍历所有注册的 Entry（builtins + instructions + skills）
2. 调用 entry.load() 并行加载
3. 组合为 SystemContext.combine(...)

Context Epoch（上下文纪元）

定义于 packages/core/src/session/context-epoch.ts。

管理 Session 的 System Context 版本生命周期。持久化存储在 SQLite 表 SessionContextEpochTable：

Schema: {
  session_id, baseline, agent, snapshot, baseline_seq, revision, replacement_seq
}

工作流程：

SessionRunner.run(sessionID)
  → SessionContextEpoch.prepare()
    → SystemContextRegistry.load()          // 加载所有 Source
    → SystemContext.combine(...)            // 组合
    → SystemContext.reconcile(previous)     // 与上次快照比较
      ├─ "Unchanged"       → revision 不变
      ├─ "Updated"         → 生成增量更新文本，revision +1
      └─ "ReplacementReady"  → 重建完整 Generation
    → 持久化到 SQLite
  → LLM.request({ system: [agent.system, baseline], ... })

V2 最终组装

// runner/llm.ts:220
system: [agent.info?.system, system.baseline]
  .filter(part => part !== undefined && part.length > 0)
  .map(SystemPart.make)

• agent.info?.system：Agent 配置中 prompt 字段指定的提示词
• system.baseline：从 SystemContextRegistry 加载并经过 initialize() 处理的基线文本

基线 vs 更新

方法	时机	输出
baseline()	首次初始化 Generation	完整的系统提示文本
update(prev, curr)	Context Epoch revision 增加	增量更新文本（写入 session event）
removed()	Source 被移除	移除通知文本

五、Agent 特定提示词

内置 Agent 的提示词

Agent	自定义 prompt	说明
build	无	使用模型默认提示词，权限全部允许
plan	无	权限控制只读，额外提示由 reminders.ts 注入
general	无	使用模型默认提示词
explore	PROMPT_EXPLORE	专用探索提示词
compaction	无	隐藏 Agent，全部禁用

插件系统修改提示词

packages/opencode/src/session/prompt.ts 中通过插件钩子修改：

yield* plugin.trigger("experimental.chat.system.transform", {}, { system })

该钩子在 agent.ts:227 用于 Agent 生成功能，允许插件动态修改 system array。

六、架构对比

维度	V1 架构	V2 架构（System Context）
提示词选择	字符串匹配模型 ID	同 V1
环境信息	每次拼接	Source + 持久化快照
AGENTS.md	每次文件读取	Source 懒加载
增量更新	不支持（全量重建）	支持（reconcile 生成 diff）
持久化	无	SQLite 存储 Snapshot + revision
进程恢复	不支持	持久化后跨进程复用
插件扩展	experimental.chat.system.transform 钩子	注册新 Source 到 Registry

七、完整数据流（V1 架构）

用户输入
  ↓
SessionPrompt.prompt(input)                     [prompt.ts]
  ↓
├─ provider(model)                              [system.ts:19]
│   → 根据 model.api.id 选择提示词文件
│   → 返回 [PROMPT_BEAST / ANTHROPIC / ...]
│
├─ sys.environment(model)                       [system.ts:48]
│   → 读取 InstanceState.context
│   → 构建环境信息块
│
├─ instruction.system()                         [instruction.ts:100]
│   → 读取全局 AGENTS.md
│   → 向上查找项目级 AGENTS.md
│   → 加载 config.instructions 指定文件
│   → 去重（已注入的文件不重复）
│
├─ sys.skills(agent)                            [system.ts:65]
│   → 按权限过滤可用 skill
│   → 格式化 skill 列表
│
├─ 合并 system = [...env, ...instructions, ...skills]
│
├─ SessionReminders.apply()                     [reminders.ts]
│   → plan/build 切换提示
│   → max-steps 提示
│
├─ Plugin "experimental.chat.system.transform"  [prompt.ts]
│   → 插件修改 system array
│
└─ handle.process({ system, messages, tools, model })
    → LLM stream API

八、关键文件索引

文件	职责
packages/opencode/src/session/system.ts	提示词选择 + 环境/技能信息构建
packages/opencode/src/session/prompt.ts	主提示词组装入口（V1）
packages/opencode/src/session/instruction.ts	AGENTS.md 加载与就近注入
packages/opencode/src/session/reminders.ts	Plan/Build 切换提示注入
packages/opencode/src/session/prompt/default.txt	通用兜底提示词
packages/opencode/src/session/prompt/anthropic.txt	Claude 系列提示词
packages/opencode/src/session/prompt/beast.txt	GPT-4/o1/o3 提示词
packages/opencode/src/session/prompt/gpt.txt	GPT 系列提示词
packages/opencode/src/session/prompt/codex.txt	GPT Codex 提示词
packages/opencode/src/session/prompt/gemini.txt	Gemini 提示词
packages/opencode/src/session/prompt/kimi.txt	Kimi 提示词
packages/opencode/src/session/prompt/trinity.txt	Trinity 提示词
packages/opencode/src/session/prompt/plan.txt	Plan 模式提示
packages/opencode/src/session/prompt/build-switch.txt	Plan→Build 切换提示
packages/opencode/src/session/prompt/max-steps.txt	最大步数限制提示
packages/core/src/system-context/index.ts	System Context 核心抽象
packages/core/src/system-context/registry.ts	上下文源注册表
packages/core/src/system-context/builtins.ts	内置上下文源
packages/core/src/instruction-context.ts	AGENTS.md 作为 System Context Source
packages/core/src/session/context-epoch.ts	Context Epoch 管理
packages/core/src/session/runner/llm.ts	V2 架构最终组装