系统提示词加载机制概述OpenCode 的系统提示词System Prompt采用双架构并行策略分为V1 架构当前主要使用的组合式加载和V2 架构基于 System Context 的新一代机制。V2 通过 Context Epoch 支持增量更新和持久化快照。一、提示词文件文件清单所有提示词模板位于packages/opencode/src/session/prompt/共 14 个.txt文件通过Bun 编译时静态导入嵌入 JavaScript bundleimport 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.txtgpt-4/o1/o3长篇结构化自称 the best coding agent强调迭代直到完成codex.txtgptcodex强调行动、轻描述针对 GPT Codex 模型优化gpt.txtgpt不含 codex专业、重规则自称 opencode, an interactive CLI agentgemini.txtgemini-简洁风格自称 opencode, an interactive CLI toolanthropic.txtclaude简洁对话式使用 OpenCode 自称trinity.txttrinity强调持续直到完成kimi.txtkimi最详细版本含 AGENTS.md 长篇说明default.txt兜底所有未匹配简明强调工具使用辅助文件文件用途plan.txtPlan 模式附加提示词追加到 user messageplan-mode.txt实验性 Plan 模式模板含${planInfo}占位符build-switch.txtPlan→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} Todays date: {date} /env2. AGENTS.md / 指令 (instructions)定义于packages/opencode/src/session/instruction.ts:100-115Instruction.system()方法加载优先级来源路径1全局 AGENTS.md~/.config/opencode/AGENTS.md2回退全局 CLAUDE.md~/.claude/CLAUDE.md3项目级 AGENTS.md从当前目录向上查找第一个 AGENTS.md/CLAUDE.md/CONTEXT.md4配置指定文件opencode.json中config.instructions数组支持 URL格式Instructions from: {filepath}\n{content}就近注入机制instruction.ts:159-195当read工具读取文件时自动查找该文件祖先目录中的 AGENTS.md 并注入。每个 assistant message 只注入一次同一文件通过claims: MapMessageID, Setstring去重。3. 技能列表 (skills)定义于system.ts:65-75列出基于 Agent 权限过滤后的可用 SkillSkills 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 — SystemContextRegistryEntry 注册与组合加载 builtins.ts — 内置 Sourceenvironment date核心类型Source可独立刷新的类型化源interface SourceA { readonly key: string readonly codec: Schema.CodecA readonly load: () EffectA readonly baseline: (value: A) string // 首次渲染完整文本 readonly update: (prev: A, curr: A) string // 增量更新文本 readonly removed: (value: A) string // 移除通知 }SystemContext不透明的上下文载体包含多个PackedSource。Snapshot持久化的比较状态RecordKey, { value: Json, removed?: string }Generationtype Generation { baseline: string, snapshot: Snapshot }——不可变基线文本 当前快照。ReconcileResulttype ReconcileResult Unchanged | Updated | ReplacementReady | ReplacementBlocked内置 Source定义于packages/core/src/system-context/builtins.ts:10-32Source Key说明core/environment工作目录、工作区根目录、git 状态、平台core/date当前日期AGENTS.md 作为 Source定义于packages/core/src/instruction-context.ts:17-54Keycore/instructionsbaseline()渲染为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.mdSystem Context Registry定义于registry.ts:421. 遍历所有注册的 Entrybuiltins instructions skills 2. 调用 entry.load() 并行加载 3. 组合为 SystemContext.combine(...)Context Epoch上下文纪元定义于packages/core/src/session/context-epoch.ts。管理 Session 的 System Context 版本生命周期。持久化存储在 SQLite 表SessionContextEpochTableSchema: { 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?.systemAgent 配置中prompt字段指定的提示词system.baseline从 SystemContextRegistry 加载并经过initialize()处理的基线文本基线 vs 更新方法时机输出baseline()首次初始化 Generation完整的系统提示文本update(prev, curr)Context Epoch revision 增加增量更新文本写入 session eventremoved()Source 被移除移除通知文本五、Agent 特定提示词内置 Agent 的提示词Agent自定义 prompt说明build无使用模型默认提示词权限全部允许plan无权限控制只读额外提示由 reminders.ts 注入general无使用模型默认提示词explorePROMPT_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主提示词组装入口V1packages/opencode/src/session/instruction.tsAGENTS.md 加载与就近注入packages/opencode/src/session/reminders.tsPlan/Build 切换提示注入packages/opencode/src/session/prompt/default.txt通用兜底提示词packages/opencode/src/session/prompt/anthropic.txtClaude 系列提示词packages/opencode/src/session/prompt/beast.txtGPT-4/o1/o3 提示词packages/opencode/src/session/prompt/gpt.txtGPT 系列提示词packages/opencode/src/session/prompt/codex.txtGPT Codex 提示词packages/opencode/src/session/prompt/gemini.txtGemini 提示词packages/opencode/src/session/prompt/kimi.txtKimi 提示词packages/opencode/src/session/prompt/trinity.txtTrinity 提示词packages/opencode/src/session/prompt/plan.txtPlan 模式提示packages/opencode/src/session/prompt/build-switch.txtPlan→Build 切换提示packages/opencode/src/session/prompt/max-steps.txt最大步数限制提示packages/core/src/system-context/index.tsSystem Context 核心抽象packages/core/src/system-context/registry.ts上下文源注册表packages/core/src/system-context/builtins.ts内置上下文源packages/core/src/instruction-context.tsAGENTS.md 作为 System Context Sourcepackages/core/src/session/context-epoch.tsContext Epoch 管理packages/core/src/session/runner/llm.tsV2 架构最终组装
