阶段一 · 架构与核心机制

系统提示词 —— 每轮请求的第一句话

模型每一轮收到的第一条消息都是系统消息。它决定"模型是谁、能用什么、该怎么说话",而且完全由外壳决定。这一章讲清 Pi 怎么把这句话拼出来:它不是一条长字符串,而是一组有名字的段落;后面哪一段变了,也只重发那一段。

具体回答三个问题:这句话由什么组成?想改它,改哪一层?为什么改了之后模型反而变笨了?

学习目标

  • 说出系统消息由哪些段落组成、每段从哪来、哪些可以空。
  • 分清三种改写强度的后果:换人设、只追加、整段替换。
  • 理解人设的三级来源,以及项目级文件为什么需要"项目信任"。
  • 理解"每轮只发变化的那几段"为什么既省 token 又保住缓存。

一、能力边界写在第一句话里

上一章说过:模型的能力边界由外壳决定。系统消息就是这句话最直接的证据。

同一个模型、同一个版本、同一个密钥,给它两段不同的系统消息:

系统消息 模型的表现
通用编程助手 + 工具清单 + 文件操作规范 读代码、改文件、跑测试,动手前先确认
数据分析师 + 业务规则 + 输出格式 先分清已知与未知,给可能原因排序,不编造数据

模型没变,变的是外壳塞进去的那段话。所以系统消息不是"开场白",它是运行时配置——把产品决策翻译成模型能理解的语言,就发生在这里。

一个常见误解也随之被推翻:换人设不等于换模型。你不需要微调、不需要换服务商,只需要改这段话。

二、它是一组段落,不是一条长字符串

Pi 把系统消息拆成若干有名字的段落,各自负责一件事:

段落 内容 从哪来 会不会空
开场 你是谁 自定义人设 / 项目文件 / 内置默认 不会
工具 有哪些工具,各干什么 当前启用的工具 + 每个工具的一句说明 会(空时写"无")
规则 行为规范 各工具自带的规则 + 你追加的规则 + 两条固定规则 不会
文档 内置文档在哪 安装路径 跟着开场一起生成
追加 你额外加的几段话 追加配置 / 追加文件 会
项目上下文 仓库里的约定 从工作目录向上找的约定文件 会
技能 有哪些可用的技能 技能目录的摘要 条件注入
工作目录 当前在哪个目录 无条件 不会

除了开场,每一段都会被包进一个同名的标签里(比如规则段外面包着"规则"标签)。这不是装饰,而是为了后面那个机制:只有带名字的段落,才能只更新其中一段。

三、三种改写强度

想改这段话,有三种手段,后果完全不同:

手段 作用范围 会不会丢工具说明和规则 适合什么场景
换人设 只替换开场那段 会:工具、规则、文档三段都不再生成 做垂直助手(客服、分析师)
只追加 在末尾加一段 不会 只想补几条团队规范
整段替换 整个系统消息换成你写的内容 全部按你写的来 扩展里要彻底接管提示词

判断标准很简单:你要不要丢掉"这是个编程助手"这套默认行为? 要丢就用换人设或整段替换,不丢就走追加。

这里有一点值得强调:"只换人设"并不只是换了开场白。工具清单、行为规范、文档指针全都一起消失。对垂直助手来说这正好;但如果你只是想加两句规则,用了它,模型就不知道自己有哪些工具了——工具调用率会明显下降。

工具那段还有个小机关:它只列"给了说明文案"的工具。于是有一种情况会让人困惑——工具明明注册了,模型却在清单里看不见。要理解这一点得知道:清单是给模型看的文字,工具声明是另一条通道。没写说明的工具仍然会被声明、仍然能调用,只是不在那几行文字里。真正"藏起来"的工具是另一回事——那种只能经由别的工具间接调用。

四、人设从哪来:三级来源

开场那段不是随便写的,它有一条回退链:

优先级 来源 位置
最高 代码层覆盖 扩展或嵌入方直接指定,返回什么就是什么
次之 项目文件 / 全局文件 {工作目录}/.pi/SYSTEM.md 或 ~/.pi/agent/SYSTEM.md
兜底 内置默认 就是那句"你是一个运行在 pi 里的编程助手"

前两级都没有,才落到第三级。这也解释了为什么做垂直助手必须主动换掉人设:你什么都不做,拿到的就是编程助手。

项目级文件为什么需要信任

放在项目里的那个文件,只有在"这个项目被信任"时才生效。理由很直接:项目目录里的东西可能来自任何地方,如果克隆一个仓库就能悄悄改写你的助手人设,那是个供应链漏洞。

全局文件不需要这个检查,因为它已经在你的用户目录下。所以实践建议是:优先用项目级文件(可版本化、跟着仓库走),少用全局文件(会影响你机器上所有项目)。

追加那段怎么清空

追加来源是一个列表,返回空列表就等于把这一段清空。在把通用助手改造成垂直助手时,这几乎是必需动作——否则项目里残留的编程规范会跟着一起注入。

五、每轮只发变化的那几段

这里是最容易被忽略、但工程上最有价值的设计。

系统消息会被存进 transcript,带着"内容"和"分段"两部分。每一轮,外壳重新算出"现在应该是什么样",然后和上一轮对比,只产出变化了的那几段:

  • 某段内容变了 → 发这一段的新文本;
  • 某段被删了 → 发一个"删除这一段"的标记;
  • 没变 → 什么都不发。

这么做的两个好处:

  1. 省 token:不变的段落不重发。
  2. 保缓存:提示词缓存是按前缀命中的,每轮都变等于每轮都失效。

反过来也就得到了一个实践警告:别往系统消息里塞时间戳、随机数、绝对路径这类每轮都变的东西。你以为是"补充信息",实际上是让缓存全废、补丁全量刷新。

六、工作目录那一段

工作目录这一段由外壳无条件生成,没有配置项能关掉它。但它可以被整段替换:扩展在"运行开始前"的钩子里返回一段自己的系统消息,走的正是"整段替换"这条路,从此所有段落都不再生成。

它对垂直助手基本无害(客服、翻译不会因为看到路径就出错),但两类场景要处理:

  • 不想让模型看到真实路径(多租户服务里路径可能带用户信息);
  • 提示词需要严格可复现(路径变化导致内容变化,缓存和回放全部失效)。

要提醒的是:替换系统消息不影响工具的真实执行目录。那是按工作目录配置解析的,跟模型看不看得见这一段无关。

当前 Pi 行为

  • 系统消息由一组有名字的段落拼成,除开场外每段包同名标签,存进 transcript 的分段字段。
  • 换人设时不生成工具、规则、文档三段;整段替换时连分段都不存在,只有一整块内容。
  • 文件探索规则按工具集动态生成:有命令工具但没有搜索工具时,提示"用命令做查找";只有 Windows 命令工具时换成对应措辞;两条固定规则(回答简洁、写清文件路径)永远追加,且会去重。
  • 技能段只在所选工具里有"能读文件的工具"时才注入;如果这些工具被隐藏但仍可间接调用,措辞会退化成不点名工具。
  • 人设的文件来源先查项目级(需信任)、再查全局级;代码层覆盖优先于两者。
  • 每轮只发变化的分段补丁;删除一段用空值表示。

代码里的名字

通俗说法 代码里的名字
分段拼装 buildSystemPromptSections
差异补丁 diffSystemPromptSections
整段替换 forceSystemPrompt
代码层覆盖 systemPromptOverride
追加覆盖 appendSystemPromptOverride
隐藏但仍可达的工具 hiddenTools
工具的一句说明 toolSnippets

在 Pi 里怎么操作

  • 改人设:优先放项目级的人设文件(随仓库走),或在自己的嵌入代码里覆盖。
  • 加规则:用追加配置或追加文件,别用换人设——那会把工具说明一起丢掉。
  • 查当前提示词:开启调试输出,或让扩展把拼好的系统消息打出来。
  • 项目级文件不生效时,先确认项目是否被信任。

源码位置

  • packages/coding-agent/src/core/system-prompt.ts:分段拼装与差异补丁。
  • packages/coding-agent/src/core/resource-loader.ts:人设文件发现与覆盖链。
  • packages/coding-agent/src/core/skills.ts:技能摘要的格式。

Python 实验

system_prompt.py 用同一套分段实现拼装,跑一次就能看到两条路径的差别:

python3 -m learn_pi_lab lab system-prompt
default_has_guidelines: true      # 默认路径拼了规则段
custom_has_guidelines: false      # 换人设路径没有
skills_in_default: true           # 有读文件的工具,技能段注入
skills_without_read_tool: false   # 只有写工具,技能段被丢弃
cwd_appended_to_custom: true      # 工作目录无条件追加
project_context_in_custom: true   # 项目上下文两条路径都注入

我们提供两个入口,对应 Pi 的两种视图:

sections = build_system_prompt_sections(options)   # 分段视图:{段名: 内容}
text = build_system_prompt(options)                # 扁平视图:拼好的整段文字,便于阅读

分段视图里,段的顺序就是拼装顺序;扁平视图只是把它们连起来、加上便于阅读的标签。教学模型不做差异补丁——它证明的是顺序、条件和开关,不是传输格式。

from learn_pi_lab.labs.system_prompt import ContextFile, Skill, SystemPromptOptions, build_system_prompt

prompt = build_system_prompt(SystemPromptOptions(
    cwd="/work/learn-pi",
    custom_prompt="你是一个企业数据分析助手。",
    context_files=(ContextFile(path="AGENTS.md", content="回答用中文。"),),
    skills=(Skill(name="review", description="评审一次改动"),),
))
assert "Guidelines:" not in prompt            # 换人设分支没有规则段
assert "Current working directory" in prompt  # 工作目录仍然在

失败与边界实验

四种典型误用,都能在上面的实验里复现:

  1. 以为只换了人设,其实丢了工具说明。 换完之后检查工具那段——它不在了。模型不知道自己有哪些工具,调用率会掉。修法:需要工具说明就别换人设,改用追加。
  2. 技能段悄悄消失。 把工具集设成只有写工具,技能摘要不见了。原因是模型没有能读取技能文件的工具,注入了也读不到。修法:工具集里保留读或命令工具。
  3. 项目级文件不生效。 文件明明存在却不生效,通常是项目未被信任。这是安全设计而非 bug。修法:确认信任状态,或改用全局文件/代码层覆盖。
  4. 提示词每轮都变。 在规则或自定义段里放时间戳、随机数、绝对路径,会让补丁每轮全量刷新,缓存彻底失效——这是分段设计最容易被破坏的地方。

这一模块的核心代码在核心代码导览 · 系统提示词拼装有逐段解读。

验证方式

python3 -m learn_pi_lab lab system-prompt
python3 -m unittest tests.test_14_system_prompt -v
python3 scripts/check_course_contract.py

测试覆盖了分段顺序、两条路径的差异、工作目录无条件追加、Windows 路径规范化、技能丢弃条件、规则去重与 Windows 措辞、文件发现的信任要求,以及覆盖链。

边界与安全

  • 系统提示词不是安全边界。 它能影响模型倾向,但模型可以被用户输入诱导偏离。真正的隔离、拦截必须在产品层实现(见 03 章)。
  • 项目级提示词文件是供应链风险。 这正是"项目信任"存在的原因。评审第三方仓库时,.pi/SYSTEM.md、.pi/APPEND_SYSTEM.md、AGENTS.md 都应当当作可执行配置,而不是文档。
  • 提示词里不要放密钥。 它每轮都会发送、会进会话记录、可能被压缩进摘要。
  • 工作目录那一段会泄露路径。 多租户场景需要脱敏时,用"整段替换"处理,而不是假设有开关。

自测三问

  • 传了自定义人设之后,模型还能看见工具清单吗?为什么?
  • 为什么"每轮重新算一遍、但只发差异"能同时省 token 和保住缓存?
  • 项目里的约定文件明明存在却不生效,最可能是什么原因?

回顾

  • 系统消息是运行时配置:定义模型是谁、能用什么、怎么说话。
  • 分段拼装:开场 → 工具 → 规则 → 文档 → 追加 → 项目上下文 → 技能 → 工作目录;除开场外每段带标签。
  • 三种强度:换人设(丢工具说明)、只追加、整段替换。
  • 三级来源:代码覆盖 > 文件(项目级需信任)> 内置默认。
  • 每轮只发差异:省 token,也保缓存。

下一章回到状态本身——会话管理:这些每轮都要重发的提示词,与落盘的对话历史如何分工。