Conversation
PI-Desktop shared ~/.pi/agent with pi CLI but silently ignored the two custom system prompt files pi documents, leaving desktop sessions with no supported entry point for a custom persona. Resolve both files per session launch with pi's precedence (project .pi/ over ~/.pi/agent/, one winner per kind) and carry them into the runtime. Two deliberate deviations from pi CLI semantics, recorded in spec 03-runtime/02-agent-runtime.md §7: SYSTEM.md replaces only the product persona line, so the operational rules that desktop mechanics depend on (collaboration, search, edit contract, scratch, delegation) survive the replacement; APPEND_SYSTEM.md rides after the composed base prompt and before the project instruction chain, so the user's own AGENTS.md keeps the last word. A change to the resolved content retires the runtime through the reuse match, applying on the next prompt. Native-pi sessions keep resolving the files through the upstream DefaultResourceLoader unchanged. fixes vastsa#542
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation / 动机
PI-Desktop 与 pi CLI 共用
~/.pi/agent/配置目录,但 pi 官方文档承诺的两个自定义系统提示词文件在桌面端被静默忽略:SYSTEM.md(替换默认提示词)与APPEND_SYSTEM.md(追加),全局和项目级(.pi/)全部不生效、不报错、无日志,桌面会话没有任何受支持的自定义人格入口。#542 已在当前 main 复现并定位:全仓没有任何代码读取这两个文件,普通会话的 system prompt 全部来自内置默认。fixes #542
Modifications / 改动点
新增
packages/agent-runtime/src/custom-system-prompt.ts:发现规则与 pi CLI 对齐——<workspace>/.pi/与~/.pi/agent/两处,SYSTEM.md/APPEND_SYSTEM.md各自独立发现,项目级优先于全局,单选不叠加,纯空白视同不存在,单文件上限 64 KiB。每次会话 launch 时解析一次(
session-launch.ts),结果随sidecarParams透传到 runtime;文件内容变化会打破 runtime 复用判断(matches()),下一回合自动用新内容重组提示词,无需重启应用。两处与 pi CLI 的有意偏差(已记录于 spec
docs/spec/03-runtime/02-agent-runtime.md§7.0.1):SYSTEM.md只替换默认提示词的产品人格行;运行机制规则(协作规则、工具引导、scratch、delegation、skills 目录)全部保留,桌面功能在自定义人格下不退化;APPEND_SYSTEM.md追加在组合后的 base prompt 之后、项目指令链之前——与 pi 的顺序一致,用户自己的AGENTS.md保持 last word。native-pi 会话(续接 pi CLI,走上游
DefaultResourceLoader)行为不变,该路径原本就支持这两个文件。This is NOT a breaking change. / 这不是一个破坏性变更。
Verification Steps / 验证步骤(人工)
以下每步均从 worktree 启动 dev 实例验证,截图附于各步骤下方。
全局 APPEND_SYSTEM.md 生效:写入
~/.pi/agent/APPEND_SYSTEM.md(要求每次回答末尾输出标记)→ 新建会话提问,回答应携带标记。此为 ~/.pi/agent/APPEND_SYSTEM.md：
此为验证效果：
全局 SYSTEM.md 替换人格、机制规则保留:写入自定义人格 → 新会话应使用自定义人格;同时让它执行读文件等工具操作,工具调用应照常工作(验证替换只作用于人格层)。
此为 ~/.pi/agent/SYSTEM.md：
此为测试效果：
项目级覆盖优先级:在项目根放置
.pi/SYSTEM.md→ 该项目的会话使用项目级人格;未放置.pi/的其他项目会话仍使用全局文件。此为项目级提示词：
此为测试效果：
其它项目会话不受影响：
免重启、同会话下一回合生效:保持会话不动,修改 SYSTEM.md 内容 → 直接发送下一条消息,新回合即使用新内容(matches 失效重建 runtime)。
延续上个问题，改了一下项目系统提示词：
并未重启，此为测试效果：
Automated Tests / 自动化测试
custom-system-prompt.test.ts):项目/全局优先级、按类独立、空白文件回退、64 KiB UTF-8 安全截断、无 workspace 场景;runtime.test.ts):替换边界(自定义人格进入、机制规则保留)、APPEND 插入顺序(base 之后、项目指令之前)、replace+append 叠加、默认不变、matches 失效;custom-system-prompt-launch.test.mjs):真实临时目录文件 →sidecarParams.customSystemPrompt,含删除回退。pnpm build:js✅;desktop typecheck ✅;agent-runtime 617 passed ✅;desktop 2166 passed(1 个 main 上既有的 skip)✅;pnpm -r test无失败 ✅。pnpm lint存在 12 个 CSS token 违规,为 main 既有问题(已在干净0726e0ff上复现,全部位于本次未触及的apps/desktop/src/styles/),与本改动无关。Checklist / 检查清单
docs/spec/03-runtime/02-agent-runtime.md§7.0.1 记录了实现与两处有意偏差。