feat: 新增系统提示词封面，并修正工具结果投影与常驻工具

系统提示词封面（新增能力）： - extensions/system-prompt-cover.ts：读取 ~/.pi/agent/SYSTEM_COVER.md，在 before_agent_start 返回 { systemPrompt }，用文本拼接替换 Pi 默认系统提示词的开头，同时保留 tools / rules / docs / skills / project_context / cwd 全部分区及其原始顺序。 - 必须走 forceSystemPrompt 投影路径。customPrompt 选项会连带抑制 tools / rules / docs 三个分区，而回填只能追加到末尾，无法恢复原顺序；且 forceSystemPrompt 优先级更高，二者同时存在时 customPrompt 会被静默忽略，因此 handler 不得写 customPrompt。 - 分割边界要求独占一行的裸标签：<project_instructions path="..."> 嵌套在 <project_context> 内，只有裸标签才是分区边界。 - 注册在 tool-routing 之前，否则提示词已被压平，改 systemPromptOptions 不再影响本轮请求。 - scripts/deploy-system-prompt-cover.mjs：同目录临时文件 + rename 原子覆盖，不保留备份；install.sh 从脚本目录、update.sh 从升级后组合包定位 helper，禁止回退到可能陈旧的脚本目录。 - 封面缺失、不可读或空白时静默 no-op，Pi 行为保持不变；封面每轮重新读取，修改后在下一轮生效，不影响已结束的历史对话。 pi-compaction 投影修正： - 仅在「摘要 + Source 行」严格短于原文时才替换工具结果。此前命中即无条件替换，小结果反而被包壳放大；未替换的结果完整保留原始 content parts（含非文本部分）。 - deterministic.maxStubTokens 由 256 提升到 1024。 pi-tool-search 常驻工具： - alwaysEnabled 增加 context_tree_query：恢复被投影的工具证据不应依赖一次 tool_search 激活，常驻同时保持请求前缀稳定。 - BUNDLE_TOOL_SEARCH_DEFAULTS_VERSION 由 3 提升到 4； scripts/migrate-tool-search-settings.mjs 新增 version-3 快照常量，使其与 version-2 一样可被完整精确匹配并迁移。 - 权限策略为 context_tree_query 显式 allow：它只读扩展自己的 segment 索引、不触碰工作区，常驻后不应每轮触发 AutoReview 往返。该种子仅在全新安装时部署，已存在的用户 policy.jsonc 不会被覆盖。文档与测试同步： - AGENTS.md：新增 system-prompt-cover 开发约定，修正加载顺序、 bundleDefaultsVersion、可迁移旧快照集合与常驻工具范围的描述。 - pi-tool-search 的 README / CHANGELOG 同步 version 4 与新增常驻工具。 - tests/system-prompt-cover.test.ts：覆盖顺序保持、尾部逐字节不变、嵌套 project_instructions 不误判、部署幂等与覆盖、缺源时非零退出。 - 修正 pi-tool-search/test/config.test.ts 与 tests/tool-search-settings-migration.test.ts 中写死的 version 3 与工具列表断言。 - update-git-clean-recovery / tool-search-settings-migration 的 mock 组合包补拷 scripts/，与真实发布包结构一致，避免 helper 定位失败。测试：根 61/61、pi-compaction 36/36 + tsc、pi-tool-search 16/16 + tsc、 pi-permission-system 2577/2577；sh -n 与 git diff --check 通过。
2026-10-26 10:45:22 +00:00 · 2026-10-15 18:02:03 -07:00
parent cdd91b3f8b
commit dec48dab6d
24 changed files with 675 additions and 20 deletions
@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * Deploys the bundle-authoritative system prompt cover into the Pi agent directory.
+ *
+ * The cover is bundle-owned configuration: the repository copy under
+ * `config/system-prompt-cover.md` is authoritative, and this helper synchronizes it to
+ * `<agentDir>/SYSTEM_COVER.md`. There is no user-owned variant, so an existing file is
+ * replaced atomically without keeping a backup.
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const COVER_FILE_NAME = "SYSTEM_COVER.md";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const bundleRoot = dirname(dirname(scriptPath));
+export const BUNDLED_COVER_PATH = join(bundleRoot, "config", "system-prompt-cover.md");
+
+/**
+ * Resolve the Pi agent directory, mirroring Pi's own `getAgentDir()`.
+ *
+ * Implemented locally so this helper stays runnable from `install.sh` / `update.sh`
+ * without loading the Pi runtime.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} homedir
+ * @returns {string}
+ */
+export function resolveAgentDir(env = process.env, homedir) {
+  const configured = env.PI_CODING_AGENT_DIR;
+  if (configured) {
+    return configured.startsWith("~/") ? join(homedir, configured.slice(2)) : configured;
+  }
+  return join(homedir, ".pi", "agent");
+}
+
+/**
+ * Compare the bundle cover against the deployed copy and replace it when they differ.
+ *
+ * Returns `{ status }`:
+ * - `current` — deployed copy already matches the bundle.
+ * - `updated` — deployed copy was replaced.
+ * - `created` — no deployed copy existed.
+ *
+ * Read or write failures throw so callers can report a real failure instead of
+ * silently leaving a stale cover in place.
+ *
+ * @param {{ agentDir?: string, bundledCoverPath?: string }} options
+ * @returns {Promise<{ status: "current" | "updated" | "created", targetPath: string }>}
+ */
+export async function deploySystemPromptCover({ agentDir, bundledCoverPath = BUNDLED_COVER_PATH } = {}) {
+  if (!agentDir) {
+    throw new Error("agentDir is required");
+  }
+
+  let bundledCover;
+  try {
+    bundledCover = readFileSync(bundledCoverPath, "utf8");
+  } catch (error) {
+    throw new Error(
+      `cannot read bundled system prompt cover at ${bundledCoverPath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  const targetPath = join(agentDir, COVER_FILE_NAME);
+
+  let existing;
+  let existed = false;
+  try {
+    existing = readFileSync(targetPath, "utf8");
+    existed = true;
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw new Error(
+        `cannot read deployed system prompt cover at ${targetPath}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  if (existed && existing === bundledCover) {
+    return { status: "current", targetPath };
+  }
+
+  await mkdir(agentDir, { recursive: true });
+  const temporaryPath = join(
+    agentDir,
+    `.${COVER_FILE_NAME}.my-pi-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`,
+  );
+
+  try {
+    const handle = await open(temporaryPath, "wx", 0o644);
+    try {
+      await handle.writeFile(bundledCover, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporaryPath, targetPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+
+  return { status: existed ? "updated" : "created", targetPath };
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const agentDir = process.argv[2] || resolveAgentDir(process.env, process.env.HOME);
+  const { status } = await deploySystemPromptCover({ agentDir });
+  process.stdout.write(`${status}\n`);
+}
+
+if (isMainModule()) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}