Pi Agent 系统提示词实战：替换默认编程助手人设，构建 DataAgent

我是安徽最忧郁程序员无隅目录前言一、为什么要替换默认人设二、系统提示词怎样进入 Session三、用 systemPromptOverride 定义 DataAgent四、按用户装配提示词并守住权限边界前言用 Pi Agent SDK 做企业数据分析助手时模型可能仍按“编程助手”的习惯回答谈文件、命令和代码却没有先核对业务数据。问题往往在系统提示词的基础人设。本文以 Pi Agentv0.87.1为准沿着“看清提示词来源 → 替换人设 → 按用户装配”的顺序做出一个简化的 DataAgent并说明提示词与真实数据权限的边界。一、为什么要替换默认人设Pi Agent 的默认系统提示词把模型定义为编程助手适合读文件、执行命令、改代码。企业数据分析场景期待的行为却不同面对“上月销售额下降了 15%为什么”助手应该先辨认这个数字是否可靠、比较口径是否一致再提出可验证的原因。如果直接给出“某产品销量下滑”这样的确定结论就把猜测当成了事实。系统提示词会影响模型如何理解自己的职责因此替换基础人设是定制垂直 Agent 的第一步。它能约束回答方式却不能凭空提供真实销售数据也不能替代数据库的访问控制。Piv0.87.1的提示词构建源码可以看到默认编程助手前缀和自定义前缀的分支。二、系统提示词怎样进入 Session替换之前先分清“基础人设”和其他来源。下面这张图按 Piv0.87.1的构建顺序概括五个主要部分图中的箭头表示段落组合顺序不是五个运行步骤。构建逻辑、资源加载逻辑第一段是基础人设。资源加载器先找可用的自定义内容代码传入的systemPromptOverride优先没有覆盖时可使用显式systemPromptSource或自动发现的项目级.pi/SYSTEM.md、全局SYSTEM.md。这些都没有时构建器才使用默认编程助手前缀。项目级文件只有项目被信任时才参与自动发现全局文件会影响使用同一全局配置目录的会话。因此多项目并行开发时优先考虑代码覆盖或项目级文件。资源加载器源码后面几段各有职责部分常见来源应检查什么追加规则.pi/APPEND_SYSTEM.md、全局同名文件或代码覆盖是否混入了与业务角色冲突的规则项目上下文工作目录及其父目录、全局配置目录中的AGENTS.md/CLAUDE.md是否带入了代码仓库的开发指令技能摘要已加载的技能只有启用read或bash等可读取技能文件的工具时才会加入工作目录Loader 的cwd模型是否需要知道目录路径是否适合暴露这里最容易误解的是“覆盖”二字。systemPromptOverride改的是基础人设追加规则、项目上下文、技能和工作目录仍按各自条件构建。若要做职责清晰的业务 Agent应该检查实际加载了哪些来源而不是假定覆盖后整份系统提示词只剩自己写的两句话。系统提示词源码三、用systemPromptOverride定义 DataAgent下面是一个最小的 SDK 示例。运行前需要有可用模型示例用noTools: all关闭工具先单独观察提示词对回答方式的影响。保存为04a-replace-prompt.ts在已安装earendil-works/pi-coding-agent0.87.1和tsx的项目中运行npx tsx 04a-replace-prompt.ts。官方自定义提示词示例import{createAgentSession,DefaultResourceLoader,getAgentDir,ModelRuntime,SessionManager,}fromearendil-works/pi-coding-agent;construntimeawaitModelRuntime.create();constmodel(awaitruntime.getAvailable())[0];if(!model)thrownewError(请先配置可用模型);constloadernewDefaultResourceLoader({cwd:process.cwd(),agentDir:getAgentDir(),systemPromptOverride:()你是企业数据分析助手。 用户提供的数字未经核实没有数据就不下确定结论。 最多列出三个可能原因每个原因附一个验证方法。,appendSystemPromptOverride:()[],});awaitloader.reload();const{session}awaitcreateAgentSession({model,modelRuntime:runtime,resourceLoader:loader,sessionManager:SessionManager.inMemory(),noTools:all,});try{session.subscribe((event){if(event.typemessage_updateevent.assistantMessageEvent.typetext_delta){process.stdout.write(event.assistantMessageEvent.delta);}});awaitsession.prompt(上月销售额下降了 15%可能的原因有哪些);console.log();}finally{session.dispose();}理解这段代码抓住三处数据流即可。systemPromptOverride返回新的基础人设appendSystemPromptOverride: () []把 Loader 发现的追加规则清空resourceLoader: loader把这份配置交给 Session。reload()先完成资源加载随后创建会话。资源加载器源码、SDK 说明观察回答时重点看它是否把“下降 15%”当作用户提供、尚待核实的前提是否区分可能原因与已证实原因是否给每个原因提供数据验证路径。即使回答符合这些要求也只验证了回答方式没有真实业务数据就无法验证原因是否正确。示例关闭了工具因此也不会调用数据库或把技能摘要加入系统提示词。如果人设是固定文本也可以把它放在项目的.pi/SYSTEM.md。这适合静态角色说明。需要按用户、部门或会话状态生成不同内容时代码覆盖更直接因为返回值可以在创建会话前由程序拼装。四、按用户装配提示词并守住权限边界同一个数据分析助手服务销售部和财务部时人设与工作规则大体相同用户身份和允许讨论的数据范围却不同。把稳定内容放在文件中把动态信息从已认证的服务端上下文取出最后组合成一份提示词。这张图上半部分表示提示词的两条输入支路下半部分是独立的数据访问链路。例如prompts/analyst/下放三份文本persona.md写“你是谁”rules.md写分析规则output-format.md写回答格式。读取文件并取得当前用户后关键拼装代码可以写成import{readFile}fromnode:fs/promises;import{join}fromnode:path;constdirjoin(process.cwd(),prompts,analyst);const[persona,rules,outputFormat]awaitPromise.all([readFile(join(dir,persona.md),utf8),readFile(join(dir,rules.md),utf8),readFile(join(dir,output-format.md),utf8),]);// user 必须由服务端认证与权限系统提供这里仅展示拼装位置。constuser{department:销售部,dataScope:本部门销售数据};constfullPrompt[persona,## 当前用户\n部门${user.department}\n数据范围${user.dataScope},rules,outputFormat,].join(\n\n);constloadernewDefaultResourceLoader({cwd:process.cwd(),agentDir:getAgentDir(),systemPromptOverride:()fullPrompt,appendSystemPromptOverride:()[],});awaitloader.reload();这里的Promise.all让三份静态文件并行读取fullPrompt则把它们与当前用户信息组合起来。示例中的user是演示数据。真实服务中应在认证后取得用户身份及授权范围并为该用户的请求构建对应会话不要把前一位用户的提示词或会话状态复用到下一位用户。“只讨论本部门数据”写进提示词属于模型行为约束。当 Agent 能调用数据工具时服务端仍须根据认证身份校验查询条件并让数据工具只返回被授权的数据。模型可能误解或忽略文字规则权限判断应发生在真正读取数据之前。提示词可以解释边界实际的数据访问必须由程序执行。最后看一个可选细节。Piv0.87.1将工作目录放在结构化的cwd段中。如果业务 Agent 不需要向模型展示目录值可以在before_agent_start钩子中把本轮的event.systemPromptOptions.cwd设为空字符串这会清空目录值但可能留下空的cwd段。它也不会改变工具实际使用的工作目录后者仍由 Loader 的cwd决定。原材料中针对v0.83整段字符串做正则替换的示例不应直接照搬到这个版本。系统提示词构建源码、扩展事件源码到这里DataAgent 已有自己的角色说明也能组合不同用户的上下文。下一步若要让它分析真实销售数据需要给 Session 接入受控的数据工具并在工具层落实查询权限。参考资料Pi Agent v0.87.1 SDK 文档系统提示词构建源码资源加载器源码。