System Prompt 可以被设计成一套动态装配机制,而不是单一、始终固定的字符串。本文围绕 Claude Code 2.1.299 的提示词组织方式,分析 Prompt Assembly、缓存分层、工具 Schema 和 Agent Runtime 的架构设计。
1. Prompt Assembly:把系统指令看成可编译的数据结构
装配设计使用 PromptSection(id、text、scope)、JoinedSystemBlock(正文及缓存归属),以及最终发出的 WireSystemBlock(type: "text"、text 和可选 cache_control)。装配流程可以归纳为:
- 读取模型、CLI/SDK 入口、输出风格、权限和工具集合。
- 判定 Lean 或普通形态,按条件生成可选指令段。
- 删除
null段,并将稳定的shared放在动态的session前面。 - 前置计费头和身份行,合并块并附加缓存控制标记。
- 连同独立的
tools[]定义提交模型请求。
身份行根据运行方式而变,例如交互式 CLI 的关键原文:
You are Claude Code, Anthropic's official CLI for Claude.mergeSystemPrompt处理默认、覆盖、主代理自定义、追加提示词的优先级。它说明模型行为的形成不仅取决于系统正文,还与运行时如何组合不同权威来源有关。
2. Prompt Cache:稳定前缀与动态后缀
装配流程采用 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ 表示逻辑分界,该标记用于客户端切段,不等于最终正文必须出现这个字面值。缓存内部归属为 null、org、global;wire 标记使用 ephemeral,某些条件下附加 ttl: "1h"。实际缓存支持范围与命中行为仍取决于所接入的模型服务。
工程建议:按全局、租户、用户、会话、轮次对 Prompt Segment 分级,并跟踪其版本与哈希;同时记录缓存命中 token、实际费用和延迟。缓存优化是性能工程,不应无意让私人上下文进入跨租户共享区。
3. Tool Contract、MCP 与 Agent 委派
工具体系涵盖内置工具与动态 MCP 工具;工具的可用范围受运行环境与授权条件影响。工具对象有 name、description、input_schema,与 System Prompt 作为独立请求部分发送。描述和 Schema 都会影响模型可选择的行动范围。
Agent 的 Schema 涉及 subagent_type、可选 model、effort 与 isolation。在这种设计中,fork 能继承当前上下文并避免原始工具输出全部进入主上下文,而非 fork 的子代理可从新上下文开始。由此可以设计两套委派契约:高上下文继承的 fork,以及低耦合、输入明确、结果有界的独立 Agent。
MCP 工具名采用 mcp__<server>__<tool> 结构,并追加在工具列表中;同名同义的 MCP 工具并不等同于内置工具,因为执行语义、权限和 Schema 可能不同。
4. Memory 与安全执行边界
记忆机制区分 user、feedback、project 和 reference 四种持久化事实,通过独立文件与 MEMORY.md 索引组织。可从当前 Git 状态、现有代码和项目文档直接重新推导的信息不必写入长期记忆;而项目目标、行为偏好和外部资料线索更适合保存。
对于可能改变外部状态或难以逆转的操作,可以采用这样的约束:
For actions that are hard to reverse or outward-facing, confirm firstPrompt 约束不是安全边界本身。真正的多租户 Agent 执行器还须验证文件写入路径、网络访问范围、权限有效期、对外发布授权和审计记录。外部工具结果、粘贴内容及用户系统指令也必须分别处理,防范 Prompt Injection。
5. 对 Agent 平台的工程启示
Prompt Compiler:建立 id / scope / gate / version / priority / text 的段级中间表示,支持确定性生成、快照和回归测试。Cache Telemetry:用真实请求监控不同前缀布局的缓存命中率与总成本。Subagent Contract:委派时定义目标、约束、允许工具、输入来源和预期输出,避免整个父上下文无差别复制。Execution Policy:敏感操作必须由执行器独立鉴权。Memory Lifecycle:为长期记忆记录来源、时间和更新策略。
建议先实现可复现的提示词编译器,再通过缓存指标判断成本收益,最后引入更复杂的多代理记忆与委派机制。技术设计不能先于真实需求和可观测结果。