[Bug] Trellis适配问题

[wangl886]

What happened? / 问题描述

会话开始时不会主动加载项目下trellis规则 .pi/settings.json，pi cli 表现是正常的
/trellis-start 指定时可以正常加载，但是定义的全局指令又好像失效了

Expected behavior / 预期行为

正常加载项目trellis规则，并且和全局指令不冲突

App version / 应用版本

0.14.8

Operating system / 操作系统

Windows

Extra environment / 其他环境信息

No response

Logs / 日志

Screenshots / 截图

No response

[L4XB]

我按 main @ 0a1dd80e 读了一遍代码，两半分开说。第一半确认了，第二半按现在的
描述我复现不出来，需要补充信息。

第一半：确认。PI-Desktop 自己创建的会话完全不读项目下的 .pi/settings.json

这个字符串在整个仓库里一次都没有出现（gh api /search/code 命中 0 条）。
PI-Desktop 会话启动时从项目里读的是另外两条链：

• 指令链（ADR 0037）：~/.pi/agent/AGENTS.md 打头，然后是项目根到目标目录的
  AGENTS.override.md / AGENTS.md / CLAUDE.md / .claude/CLAUDE.md
  （packages/agent-runtime/src/project-instructions.ts，loadInstructionChain）。
• 技能：全局 ~/.agents/skills 与项目 .agents/skills，并且支持
  <skill>/SKILL.md 目录形式（crates/host-core/src/user_skills.rs:149，
  crates/host-core/src/agent_capabilities.rs:11）。

.pi/** 下的东西一个都不在其中。项目里的 .pi/ 只被 plan 产物用到
（crates/host-core/src/plans/artifact.rs）。pi 扩展进 PI-Desktop 的唯一入口是
手动选路径导入成开发插件（apps/desktop/electron/main/agent-extensions-ipc.ts:69
的 pluginImportExtension，由主进程弹文件框），没有任何自动发现。

唯一真正走 pi 那套项目资源加载的是 native Pi 会话续接 这条路：

// packages/agent-runtime/src/native-pi-session.ts:1057
const settingsManager = SettingsManager.create(record.cwd, this.agentDir, { projectTrusted: true });
const resourceLoader = new DefaultResourceLoader({ cwd: record.cwd, agentDir: this.agentDir, settingsManager });

它前面还有 ProjectTrustStore + hasTrustRequiringProjectResources 的信任检查
（同文件 1035-1038 行）。但这条路只用于续接 pi CLI 已经创建的 session 文件，
在 PI-Desktop 里新建的会话走的是 DesktopAgentRuntime，完全不经过它。

按 Trellis 官方文档，它给 pi 的集成基本全在项目级 .pi/ 下：
.pi/extensions/trellis/index.ts（做上下文注入）、.pi/prompts/trellis-*.md、
.pi/agents/*.md，统一在 .pi/settings.json 里注册。所以这一层在 PI-Desktop
里从来没有被加载过——这正是你看到的和 pi CLI 的差异。

为什么 /trellis-start 又是好用的

Trellis 还会写一份跨平台的共享技能层 .agents/skills/trellis-{name}/SKILL.md，
而这一层 PI-Desktop 是读的。技能会作为 /<skill-id> 出现在输入框的 / 菜单里
（docs/spec/04-ux/04-builtin-commands.md §8），发送 /<skill-id> 会让模型调用
Skill 工具再回答。

所以现状是：共享技能层按需可用，负责在会话开始时自动注入的那个 pi 扩展不可用。
你观察到的「手动指定能加载、会话开始不会自动加载」跟这个完全对得上。

第二半：全局指令失效——按代码复现不出来，想请你补充

全局指令文件 ~/.pi/agent/AGENTS.md 是由 loadInstructionChain 无条件放在链首的
（packages/agent-runtime/src/project-instructions.ts:113），而这个函数在两处
都被调用：会话启动时（apps/desktop/electron/main/runtime/session-launch.ts:338）
以及每次文件类工具触发的按路径重载时
（apps/desktop/electron/main/runtime/sidecar.ts:307）。组装系统提示时，项目指令块
在两个组装点都排在最后（packages/agent-runtime/src/runtime.ts:1797 的
composeSystemPrompt 和 :3496 的工具块），也就是说它拿最后的话语权。

跑技能或跑命令都不会把它摘掉。所以想请你确认两点：

1. 你说的「全局指令」具体是哪一个？是 PI-Desktop 设置里的全局 AGENTS
   （~/.pi/agent/AGENTS.md），还是 Trellis 自己的某条全局规则，还是别的？
2. 「失效」的具体表现是什么？比如 /trellis-start 之前模型遵守、之后不遵守的某一条
   具体规则。如果方便，/trellis-start 前后各一次同样的提问、两张截图最能说明问题。

有可能只是 Trellis 的 SKILL 文档本身给了更强的指示（你截图里就有一句「用中文确认」），
模型选择先听它的——那是模型取舍，不是指令被丢掉。但也可能是真 bug，需要上面这两点
才能分辨。

关于第一半要怎么修

让 PI-Desktop 会话读项目 .pi/settings.json 不是一个小改动：pi 之所以给它配了
~/.pi/agent/trust.json、defaultProjectTrust、/trust 这一整套信任流程，就是因为
项目级设置能加载项目里的任意扩展代码。ADR 0037 当年也明确否决过「让 sidecar 扫描
工作区」。好消息是这套机器 PI-Desktop 已经有了（上面 native Pi 路径用的
ProjectTrustStore / hasTrustRequiringProjectResources），缺的是把它接到普通会话上。

这是产品和架构决定（按 AGENTS.md 大概要配一个 ADR），所以我先不直接发 PR。
@vastsa 如果你觉得这个方向可以，我愿意按现有的 ProjectTrustStore 把它做出来。

---

English summary. Confirmed for the first half: a PI-Desktop-created session
never reads the project's .pi/settings.json — the string does not exist in the
repository. A desktop session reads the ADR 0037 instruction chain
(~/.pi/agent/AGENTS.md + AGENTS.md/CLAUDE.md) and project
.agents/skills/**/SKILL.md, nothing under .pi/. Only the native-Pi session
continuation path builds pi's SettingsManager/DefaultResourceLoader behind
ProjectTrustStore (packages/agent-runtime/src/native-pi-session.ts:1057), and
that path only continues a session file pi CLI created. Trellis's pi integration
lives entirely in project-local .pi/, so it never loads here. /trellis-start
works because Trellis also writes the cross-platform .agents/skills/trellis-*/ SKILL.md layer, which PI-Desktop does read and which surfaces as /<skill-id>
in the composer menu (docs/spec/04-ux/04-builtin-commands.md §8).

The second half I cannot reproduce from the code: loadInstructionChain always
prepends the global file and is used at both the launch site and the per-file-tool
reload site, and the project-instruction block is appended last in both prompt
composition sites, so neither a skill nor a command drops it. Two questions above.

I read code and the Trellis documentation; I did not run PI-Desktop against a
Trellis project. File and line references are against main @ 0a1dd80e.

[vastsa]

我按 origin/main @ 8fff510a 重新核了一遍代码（上面评论引用的 0a1dd80e 已过期）。结论：第一半确认，但有一处说法需要修正；第二半从代码复现不出来。

确认：普通会话不读项目 .pi/settings.json

.pi/settings.json 这个字符串在全仓一次都没出现（本地 git grep -F 与 gh api /search/code 都是 0 命中）。普通会话启动时读的是另两条链：

• 指令链：~/.pi/agent/AGENTS.md 打头（packages/agent-runtime/src/project-instructions.ts:12；:113-129 的 loadInstructionChain 在 :121-124 无条件先放入全局项），然后是项目根到目标目录的 AGENTS.override.md / AGENTS.md / CLAUDE.md / .claude/CLAUDE.md。
• 技能：全局 ~/.agents/skills 与项目 .agents/skills（crates/host-core/src/agent_capabilities.rs:11,196-217；crates/host-core/src/user_skills.rs:140-151，只认 *.md 与 <dir>/SKILL.md）。

一处修正：.pi/** 并不是「一个都不读」

.pi/prompts 是读的：packages/agent-runtime/src/prompt-templates.ts:58-59 会读 <workspace>/.pi/prompts 与 ~/.pi/agent/prompts，这是 ADR 0024 明确决定的行为，会作为 / 菜单里的模板出现。另外 ~/.pi/agent/extensions 与 <workspace>/.pi/extensions 的发现代码也存在（packages/agent-runtime/src/extensions/discovery.ts:188-193），但它没有任何生产调用方，目前只有测试在调。

准确现状是：.pi/prompts 支持；.pi/settings.json 与 .pi/extensions（自动加载）不支持；.pi/agents、.pi/skills、.pi/mcp 不是能力来源（ADR 0112 §1）。

唯一真正走 pi 那套项目资源加载的是 native Pi 会话续接：packages/agent-runtime/src/native-pi-session.ts:1035-1037 有 ProjectTrustStore 信任门，:1057-1058 才创建 SettingsManager.create(..., { projectTrusted: true }) 与 DefaultResourceLoader。而这条路只续接 pi CLI 已创建的 session 文件（apps/desktop/electron/main/importers/pi.ts:12 读 ~/.pi/agent/sessions）。

/trellis-start 为什么可用

如果 Trellis 确实同时写了跨平台的 .agents/skills/trellis-*/SKILL.md，那这一层 PI-Desktop 是读的，技能会以 / 菜单的 Skills 组出现。这一点我无法从本仓库验证（仓库里没有任何 Trellis 相关内容），是按报告描述推断的，如果你知道它的实际布局请指正。

第二半「全局指令失效」：按代码复现不出来，需要你补两个事实

全局文件确实被无条件放在链首（project-instructions.ts:121-124），而且这个函数在会话启动（apps/desktop/electron/main/runtime/session-launch.ts:338）与文件类工具的按路径重载（apps/desktop/electron/main/runtime/sidecar.ts:307）两处都会走；渲染项目指令块的两处（packages/agent-runtime/src/runtime.ts:1797-1808，以及 :3497-3498 工具块里的最后一个）也没有任何条件会把它摘掉。所以请你确认：

1. 你说的「全局指令」具体是哪一个文件？是 ~/.pi/agent/AGENTS.md，还是 Trellis 自己的某条全局规则？
2. 「失效」的具体表现是什么？最好给一条具体规则，加 /trellis-start 前后各一次同样提问的两张截图。

也有可能只是 Trellis 的 SKILL 文档给了更强的指示、模型选择先听它 —— 那是模型取舍，不是指令被丢掉。有这两点才能分辨。

关于第一半怎么修：需要维护者拍板，且要一条 ADR

让普通会话读项目 .pi/settings.json 不只是「接根线」，它和现有决定直接冲突：

• ADR 0112 §1 把 .agents 定为唯一能力文件根；
• docs/spec/07-plugins/16-trusted-extensions.md:46 写明「D007 stays in force: PI-Desktop never auto-imports ~/.pi」，:142 更明确写了「never automatically scans or imports ~/.pi」；读取 pi CLI settings.json 的只读提示统一 skill/prompt 发现在 §12 标记为 Not scheduled；
• ADR 0037 在 Alternatives 里明确否决过「让 sidecar 扫描工作区」。

同时 pi 把 .pi/settings.json、.pi/extensions、.pi/skills、.pi/prompts 都算作 trust-requiring 资源（锁定依赖 @earendil-works/pi-coding-agent@0.85.1 的 dist/core/trust-manager.js），而项目级设置能加载项目里的任意扩展代码 —— 这正是 pi 需要 trust.json / defaultProjectTrust 这一整套流程的原因。

好消息是这套机器 PI-Desktop 已经有了（就是上面 native Pi 路径用的 ProjectTrustStore），缺的是把它接到普通会话上。可行方向：普通会话启动时也做一次信任检查，未信任就维持现状，已信任再加载项目 .pi 资源；.pi/extensions 的执行仍走现有受信扩展开关，不做递归工作区扫描。这会 amend ADR 0112 §1 与 spec16 的 v3 排期，我倾向于先出 ADR 再动手，所以这条保持 open。

[L4XB]

先接受你的修正：我那句「.pi/** 下的东西一个都不在其中」写得太绝对了。那是在列 PI-Desktop 自建会话 读的东西，但没加限定，读成「.pi/** 一概不读」是合理的。native Pi 续接那条路确实读，你补的 native-pi-session.ts:1035-1037 / :1057-1058 是对的。

你说 Trellis 的布局「无法从本仓库验证，是按报告描述推断的」—— 这条我可以补上。我拆了 npm 上的 @mindfoldhq/trellis@0.6.17（仓库 mindfold-ai/trellis，bin: tl / trellis）。你的推断是对的，而且它自己的注释就是这么说的。

pi 平台实际写哪些文件

dist/configurators/pi.js 的 collectPiTemplates() 是唯一的清单（同文件注释：「Nothing else enumerates a platform's files」）：

// Shared skills go to `.agents/skills/` (Pi discovers this cross-platform
// workspace alias natively).
for (const [filePath, content] of collectSkillTemplates(".agents/skills", resolveSkillsNeutral(ctx), resolveBundledSkills(ctx)))

collectSkillTemplates（shared.js:365-374）写的是 ${skillsRoot}/${skill.name}/SKILL.md。所以一次 pi 安装落盘的是：

.agents/skills/ —— 这层 PI-Desktop 读得到

• 5 个中性 skill：before-dev / brainstorm / break-loop / check / update-spec，各自 <name>/SKILL.md
• 4 个 bundled skill（带 references/）：trellis-channel / trellis-meta / trellis-session-insight / trellis-spec-bootstrap

.pi/ —— 这层读不到

• .pi/prompts/trellis-start.md、trellis-continue.md、trellis-finish-work.md
• .pi/agents/trellis-check.md、trellis-implement.md、trellis-research.md
• .pi/extensions/trellis/index.ts
• .pi/settings.json，内容就是 {"enableSkillCommands": true, "extensions": ["./extensions/trellis/index.ts"], "prompts": ["./prompts"]}

这引出一个和报告冲突的事实，我觉得比原问题更值得先问

/trellis-start 不在 .agents/skills/ 里。 templates/common/commands/ 只有三个文件 —— start.md / continue.md / finish-work.md —— 对 pi 平台它们一律落到 .pi/prompts/trellis-*.md。.agents/skills/ 下确实有 trellis-continue/SKILL.md 和 trellis-finish-work/SKILL.md 这两个名字，但 shared.js:140-143 注明它们是 Codex 专有（「no other platform writes those files」），pi 安装不会产生。

所以按你我两边的分析，PI-Desktop 自建会话应该看不到 /trellis-start。报告里它却能用，这一点现在是整个 issue 里最不自洽的地方，而且它比「全局指令失效」更好验证。建议先让报告人确认：

1. / 菜单里 Trellis 相关的条目具体有哪些？如果只有 before-dev / brainstorm / break-loop / check / update-spec / trellis-channel / trellis-meta / trellis-session-insight / trellis-spec-bootstrap 这 9 个，那和上面的清单完全对得上，/trellis-start 是记错或来自别处；
2. 如果 /trellis-start 真的在，那这个会话多半不是 PI-Desktop 自建的，而是 native Pi 续接（~/.pi/agent/sessions 导入的那条路）—— 那正好解释「有时读得到项目配置、有时读不到」，也把「第二半」变成另一个问题。

ls -la .agents/skills .pi/prompts 一条命令就能定这件事。

关于第一半的修法

你列的 ADR 0112 §1、spec16 的 D007、ADR 0037 的 Alternatives，和我的结论一致，我没有别的可加 —— 复用已有的 ProjectTrustStore、不做递归工作区扫描、先出 ADR 再动手，这个次序我完全同意。唯一想补一句：真要接的话，.pi/settings.json 的 extensions 字段（上面那份模板里就有一条指向 ./extensions/trellis/index.ts）意味着信任门通过之后会执行项目里的任意 TypeScript，这和 .pi/prompts、.pi/agents 那种纯文本资源不是一个量级。ADR 里或许值得把「加载项目级只读资源」和「执行项目级扩展代码」分成两个开关，而不是一个 trust 布尔量。