阶段一 · 架构与核心机制
系统提示词 —— 每轮请求的第一句话
模型每一轮收到的第一条消息都是系统消息。它决定"模型是谁、能用什么、该怎么说话",而且完全由外壳决定。这一章讲清 Pi 怎么把这句话拼出来:它不是一条长字符串,而是一组有名字的段落;后面哪一段变了,也只重发那一段。
具体回答三个问题:这句话由什么组成?想改它,改哪一层?为什么改了之后模型反而变笨了?
学习目标
- 说出系统消息由哪些段落组成、每段从哪来、哪些可以空。
- 分清三种改写强度的后果:换人设、只追加、整段替换。
- 理解人设的三级来源,以及项目级文件为什么需要"项目信任"。
- 理解"每轮只发变化的那几段"为什么既省 token 又保住缓存。
一、能力边界写在第一句话里
上一章说过:模型的能力边界由外壳决定。系统消息就是这句话最直接的证据。
同一个模型、同一个版本、同一个密钥,给它两段不同的系统消息:
| 系统消息 | 模型的表现 |
|---|---|
| 通用编程助手 + 工具清单 + 文件操作规范 | 读代码、改文件、跑测试,动手前先确认 |
| 数据分析师 + 业务规则 + 输出格式 | 先分清已知与未知,给可能原因排序,不编造数据 |
模型没变,变的是外壳塞进去的那段话。所以系统消息不是"开场白",它是运行时配置——把产品决策翻译成模型能理解的语言,就发生在这里。
一个常见误解也随之被推翻:换人设不等于换模型。你不需要微调、不需要换服务商,只需要改这段话。
二、它是一组段落,不是一条长字符串
Pi 把系统消息拆成若干有名字的段落,各自负责一件事:
| 段落 | 内容 | 从哪来 | 会不会空 |
|---|---|---|---|
| 开场 | 你是谁 | 自定义人设 / 项目文件 / 内置默认 | 不会 |
| 工具 | 有哪些工具,各干什么 | 当前启用的工具 + 每个工具的一句说明 | 会(空时写"无") |
| 规则 | 行为规范 | 各工具自带的规则 + 你追加的规则 + 两条固定规则 | 不会 |
| 文档 | 内置文档在哪 | 安装路径 | 跟着开场一起生成 |
| 追加 | 你额外加的几段话 | 追加配置 / 追加文件 | 会 |
| 项目上下文 | 仓库里的约定 | 从工作目录向上找的约定文件 | 会 |
| 技能 | 有哪些可用的技能 | 技能目录的摘要 | 条件注入 |
| 工作目录 | 当前在哪个目录 | 无条件 | 不会 |
除了开场,每一段都会被包进一个同名的标签里(比如规则段外面包着"规则"标签)。这不是装饰,而是为了后面那个机制:只有带名字的段落,才能只更新其中一段。
三、三种改写强度
想改这段话,有三种手段,后果完全不同:
| 手段 | 作用范围 | 会不会丢工具说明和规则 | 适合什么场景 |
|---|---|---|---|
| 换人设 | 只替换开场那段 | 会:工具、规则、文档三段都不再生成 | 做垂直助手(客服、分析师) |
| 只追加 | 在末尾加一段 | 不会 | 只想补几条团队规范 |
| 整段替换 | 整个系统消息换成你写的内容 | 全部按你写的来 | 扩展里要彻底接管提示词 |
判断标准很简单:你要不要丢掉"这是个编程助手"这套默认行为? 要丢就用换人设或整段替换,不丢就走追加。
这里有一点值得强调:"只换人设"并不只是换了开场白。工具清单、行为规范、文档指针全都一起消失。对垂直助手来说这正好;但如果你只是想加两句规则,用了它,模型就不知道自己有哪些工具了——工具调用率会明显下降。
工具那段还有个小机关:它只列"给了说明文案"的工具。于是有一种情况会让人困惑——工具明明注册了,模型却在清单里看不见。要理解这一点得知道:清单是给模型看的文字,工具声明是另一条通道。没写说明的工具仍然会被声明、仍然能调用,只是不在那几行文字里。真正"藏起来"的工具是另一回事——那种只能经由别的工具间接调用。
四、人设从哪来:三级来源
开场那段不是随便写的,它有一条回退链:
| 优先级 | 来源 | 位置 |
|---|---|---|
| 最高 | 代码层覆盖 | 扩展或嵌入方直接指定,返回什么就是什么 |
| 次之 | 项目文件 / 全局文件 | {工作目录}/.pi/SYSTEM.md 或 ~/.pi/agent/SYSTEM.md |
| 兜底 | 内置默认 | 就是那句"你是一个运行在 pi 里的编程助手" |
前两级都没有,才落到第三级。这也解释了为什么做垂直助手必须主动换掉人设:你什么都不做,拿到的就是编程助手。
项目级文件为什么需要信任
放在项目里的那个文件,只有在"这个项目被信任"时才生效。理由很直接:项目目录里的东西可能来自任何地方,如果克隆一个仓库就能悄悄改写你的助手人设,那是个供应链漏洞。
全局文件不需要这个检查,因为它已经在你的用户目录下。所以实践建议是:优先用项目级文件(可版本化、跟着仓库走),少用全局文件(会影响你机器上所有项目)。
追加那段怎么清空
追加来源是一个列表,返回空列表就等于把这一段清空。在把通用助手改造成垂直助手时,这几乎是必需动作——否则项目里残留的编程规范会跟着一起注入。
五、每轮只发变化的那几段
这里是最容易被忽略、但工程上最有价值的设计。
系统消息会被存进 transcript,带着"内容"和"分段"两部分。每一轮,外壳重新算出"现在应该是什么样",然后和上一轮对比,只产出变化了的那几段:
- 某段内容变了 → 发这一段的新文本;
- 某段被删了 → 发一个"删除这一段"的标记;
- 没变 → 什么都不发。
这么做的两个好处:
- 省 token:不变的段落不重发。
- 保缓存:提示词缓存是按前缀命中的,每轮都变等于每轮都失效。
反过来也就得到了一个实践警告:别往系统消息里塞时间戳、随机数、绝对路径这类每轮都变的东西。你以为是"补充信息",实际上是让缓存全废、补丁全量刷新。
六、工作目录那一段
工作目录这一段由外壳无条件生成,没有配置项能关掉它。但它可以被整段替换:扩展在"运行开始前"的钩子里返回一段自己的系统消息,走的正是"整段替换"这条路,从此所有段落都不再生成。
它对垂直助手基本无害(客服、翻译不会因为看到路径就出错),但两类场景要处理:
- 不想让模型看到真实路径(多租户服务里路径可能带用户信息);
- 提示词需要严格可复现(路径变化导致内容变化,缓存和回放全部失效)。
要提醒的是:替换系统消息不影响工具的真实执行目录。那是按工作目录配置解析的,跟模型看不看得见这一段无关。
当前 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 # 工作目录仍然在
失败与边界实验
四种典型误用,都能在上面的实验里复现:
- 以为只换了人设,其实丢了工具说明。 换完之后检查工具那段——它不在了。模型不知道自己有哪些工具,调用率会掉。修法:需要工具说明就别换人设,改用追加。
- 技能段悄悄消失。 把工具集设成只有写工具,技能摘要不见了。原因是模型没有能读取技能文件的工具,注入了也读不到。修法:工具集里保留读或命令工具。
- 项目级文件不生效。 文件明明存在却不生效,通常是项目未被信任。这是安全设计而非 bug。修法:确认信任状态,或改用全局文件/代码层覆盖。
- 提示词每轮都变。 在规则或自定义段里放时间戳、随机数、绝对路径,会让补丁每轮全量刷新,缓存彻底失效——这是分段设计最容易被破坏的地方。
这一模块的核心代码在核心代码导览 · 系统提示词拼装有逐段解读。
验证方式
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,也保缓存。
下一章回到状态本身——会话管理:这些每轮都要重发的提示词,与落盘的对话历史如何分工。