pi-web-ui 0.90.1 → 0.91.0

package/dist/server/scheduler-tasks.js

@@ -79,6 +79,11 @@ export function normalizeSchedulerInput(input, now = Date.now()) {
     const conversationId = String(input.conversationId ?? "")
         .trim()
         .slice(0, 128);
+    // 落盘会话文件：稳定身份键（issue #231）。只做归一化（去首尾空白、封顶），
+    // 不校验存在性 —— 创建时刻文件可能还没落盘，触发时按它匹配不上即回落。
+    const sessionFile = String(input.sessionFile ?? "")
+        .trim()
+        .slice(0, 1024);
     return {
         id,
         name,
@@ -92,6 +97,7 @@ export function normalizeSchedulerInput(input, now = Date.now()) {
         thinkingLevel,
         catchUp,
         conversationId,
+        sessionFile,
         oneShot: input.oneShot === true,
         createdAt: now,
         updatedAt: now,
@@ -152,6 +158,17 @@ function sanitizeHistory(v) {
     }
     return out.sort((a, b) => b.at - a.at).slice(0, SCHEDULER_HISTORY_MAX);
 }
+/** 落盘会话路径是否指向同一会话（纯函数，可单测）。
+ *  Windows 上 `C:\a\b` 与 `C:/a/b`、尾部分隔符差异都算同一文件；
+ *  空串永不相等（没拿到稳定键的任务不配对）。 */
+export function sameSessionFile(a, b) {
+    const x = String(a ?? "").trim();
+    const y = String(b ?? "").trim();
+    if (!x || !y)
+        return false;
+    const norm = (s) => s.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+    return norm(x) === norm(y);
+}
 export class SchedulerStore {
     dataDir;
     opts;
@@ -230,6 +247,7 @@ export class SchedulerStore {
                         thinkingLevel: r.thinkingLevel,
                         catchUp: r.catchUp,
                         conversationId: r.conversationId,
+                        sessionFile: r.sessionFile,
                         oneShot: r.oneShot,
                     });
                     task.createdAt = typeof r.createdAt === "number" && Number.isFinite(r.createdAt) ? r.createdAt : Date.now();
@@ -288,6 +306,7 @@ export class SchedulerStore {
                 thinkingLevel: t.thinkingLevel,
                 catchUp: t.catchUp,
                 conversationId: t.conversationId,
+                sessionFile: t.sessionFile ?? "",
                 oneShot: t.oneShot,
                 createdAt: t.createdAt,
                 updatedAt: t.updatedAt,
@@ -299,13 +318,20 @@ export class SchedulerStore {
         })
             .sort((a, b) => a.name.localeCompare(b.name, "zh"));
     }
-    /** 新建或全量更新（同名 id 覆盖）；返回归一化后的任务。 */
+    /** 新建或全量更新（同名 id 覆盖）；返回归一化后的任务。
+     *  issue #231：面板编辑不带绑定字段（conversationId/sessionFile 缺席）时保留旧绑定 ——
+     *  否则用户在面板改个名字就会把 AI 任务的会话绑定洗掉，下次触发直接变无头。
+     *  字段显式出现（含空串）仍按全量语义覆盖。 */
     upsert(input) {
         const prev = this.tasks.get(String(input.id ?? "").trim());
         const task = normalizeSchedulerInput(input);
         if (prev) {
             task.createdAt = prev.createdAt;
             task.updatedAt = Date.now();
+            if (input.conversationId === undefined && input.sessionFile === undefined) {
+                task.conversationId = prev.conversationId;
+                task.sessionFile = prev.sessionFile ?? "";
+            }
         }
         const history = prev?.history ? sanitizeHistory(prev.history) : [];
         this.tasks.set(task.id, { ...task, history });
@@ -335,6 +361,39 @@ export class SchedulerStore {
         this.changed();
         return t;
     }
+    /** 会话重绑定（issue #231）：触发时按稳定键找到了新的对话句柄，把任务的
+     *  投递目标迁移过去（只改 conversationId/sessionFile/updatedAt，不碰下次触发
+     *  与历史）。无变化回 false（调用方免一次落盘+推送）；未知任务回 false。 */
+    rebind(id, binding) {
+        const t = this.tasks.get(id);
+        if (!t)
+            return false;
+        let dirty = false;
+        if (binding.conversationId !== undefined) {
+            const v = String(binding.conversationId ?? "")
+                .trim()
+                .slice(0, 128);
+            if (v !== t.conversationId) {
+                t.conversationId = v;
+                dirty = true;
+            }
+        }
+        if (binding.sessionFile !== undefined) {
+            const v = String(binding.sessionFile ?? "")
+                .trim()
+                .slice(0, 1024);
+            if (v !== (t.sessionFile ?? "")) {
+                t.sessionFile = v;
+                dirty = true;
+            }
+        }
+        if (!dirty)
+            return false;
+        t.updatedAt = Date.now();
+        this.save();
+        this.changed();
+        return true;
+    }
     async tick() {
         const now = Date.now();
         for (const task of this.tasks.values()) {

package/dist/server/scm-commitmsg.js

@@ -0,0 +1,140 @@
+/**
+ * AI commit-message generation — pure prompt assembly + response cleanup.
+ *
+ * The git gathering lives in scm.ts (scmCommitContext); the one-off model
+ * call lives in agent-service (ClientSession.scmGenCommitMessage, same
+ * completeSimple path as the vision bridge). This module owns everything
+ * deterministic so it stays unit-testable:
+ *
+ *   buildCommitMsgInput(ctx, fallbackLang) → user message (null = nothing
+ *     to commit — the caller turns that into a friendly error)
+ *   COMMITMSG_SYSTEM_PROMPT                   → system prompt
+ *   sanitizeCommitMessage(raw)               → the single-line subject that
+ *     ends up in the commit input (models are told to emit exactly that, but
+ *     fences/labels/quotes/newlines are stripped defensively)
+ *
+ * Language policy: the generated message follows the repository's own commit
+ * subjects (style AND language — a repo writing "feat(xxx): 描述" keeps
+ * getting that). Only a repo with no commits yet falls back to the UI
+ * language passed as fallbackLang.
+ */
+/** Hard cap for the generated subject — the commit input is single-line and
+ *  this keeps a chatty model from filling the whole header row. */
+export const MAX_COMMITMSG_LEN = 200;
+/** File list cap inside the prompt (porcelain lines); the diffs carry the
+ *  details, the list is orientation only. */
+const MAX_FILE_LINES = 200;
+export const COMMITMSG_SYSTEM_PROMPT = `You write git commit messages. You receive the pending changes of a repository and output exactly one commit message: a single subject line.
+
+Rules:
+1. Match the style, format and language of the repository's recent commit subjects when provided — conventional commits ("type(scope): summary"), prefixes, punctuation, language: copy what the repo actually does.
+2. Describe what the change does at a glance (the user-facing effect), not a file-by-file listing.
+3. The staged diff is the subject of the commit. Describe staged changes when any exist; otherwise describe the unstaged and untracked changes shown.
+4. One line. No quotes, no markdown, no code fences, no "Commit message:" label, no explanation. Under 72 characters when the repository's language allows it (CJK text may naturally be shorter).
+5. Never invent scope names, issue numbers or details not visible in the provided material.
+6. If the repository has no commits yet, write the message in the language stated in the request.
+
+Output ONLY the subject line.`;
+/**
+ * Assemble the effective system prompt from the settings-panel prefs (same
+ * contract as the vision bridge's buildVisionBridgePrompt): mode "append"
+ * puts custom text after the built-in default (empty custom = pure default);
+ * mode "replace" swaps in the custom text, but an empty custom still falls
+ * back to the default (never send an empty system prompt).
+ */
+export function buildCommitMsgPrompt(mode, custom) {
+    const text = custom?.trim() ?? "";
+    if (mode === "replace" && text)
+        return text;
+    if (text)
+        return `${COMMITMSG_SYSTEM_PROMPT}\n\n${text}`;
+    return COMMITMSG_SYSTEM_PROMPT;
+}
+/** "path → [add,del]" map → compact "+12/-3 path" lines (sorted by path). */
+function formatNumStat(stat) {
+    return Object.keys(stat)
+        .sort()
+        .map((p) => `+${stat[p][0]}/-${stat[p][1]} ${p}`);
+}
+/**
+ * Assemble the user message from the gathered context. Returns null when
+ * there is nothing to describe (no staged/unstaged diff and no untracked
+ * files) — the caller replies "no changes" instead of calling the model.
+ */
+export function buildCommitMsgInput(ctx, fallbackLang) {
+    const parts = [];
+    if (ctx.subjects.length > 0) {
+        parts.push("Recent commit subjects (newest first — style reference):");
+        parts.push(...ctx.subjects.map((s) => `- ${s}`));
+    }
+    else {
+        parts.push(fallbackLang === "zh"
+            ? "（仓库还没有任何提交；请用中文写这条提交信息）"
+            : "(The repository has no commits yet; write this commit message in English.)");
+    }
+    if (ctx.files.length > 0) {
+        const shown = ctx.files.slice(0, MAX_FILE_LINES);
+        const more = ctx.files.length - shown.length;
+        parts.push("Changed files (porcelain status):");
+        parts.push(...shown.map((f) => `${f.x}${f.y} ${f.path}`));
+        if (more > 0)
+            parts.push(`… (+${more} more files)`);
+    }
+    if (ctx.stagedPatch.trim()) {
+        parts.push("Staged diff (these changes are the commit's subject):");
+        if (Object.keys(ctx.stagedStat).length > 0) {
+            parts.push(...formatNumStat(ctx.stagedStat));
+        }
+        parts.push(ctx.stagedPatch);
+    }
+    if (ctx.worktreePatch.trim()) {
+        parts.push("Unstaged diff (worktree only):");
+        if (Object.keys(ctx.worktreeStat).length > 0) {
+            parts.push(...formatNumStat(ctx.worktreeStat));
+        }
+        parts.push(ctx.worktreePatch);
+    }
+    const untracked = ctx.files.filter((f) => f.x === "?" && f.y === "?");
+    if (untracked.length > 0 && !ctx.stagedPatch.trim()) {
+        // Untracked content never appears in `git diff` — name the files so
+        // the model knows they are part of the change set (commit-all flow).
+        parts.push(`Untracked files (new, content not shown): ${untracked
+            .map((f) => f.path)
+            .join(", ")
+            .slice(0, 2000)}`);
+    }
+    if (!ctx.stagedPatch.trim() && !ctx.worktreePatch.trim() && untracked.length === 0)
+        return null;
+    return parts.join("\n");
+}
+/**
+ * Normalize whatever the model emitted into the single-line subject that goes
+ * into the commit input: drop fences, labels and wrapping quotes, keep only
+ * the first non-empty line, collapse whitespace, cap the length.
+ */
+export function sanitizeCommitMessage(raw) {
+    let text = raw.trim();
+    // ```…``` fences wrapping the whole answer.
+    const fence = text.match(/^```[a-zA-Z]*\s*\n?([\s\S]*?)\n?```$/);
+    if (fence)
+        text = fence[1].trim();
+    // Leading labels some models add despite the instructions.
+    text = text.replace(/^(commit(\s+message)?|subject|提交信息|提交消息|提交说明)\s*[:：]\s*/i, "");
+    // First non-empty line only — the input field is single-line by design.
+    const firstLine = text
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    let out = firstLine.replace(/\s+/g, " ").trim();
+    // Matching wrapping quotes.
+    if (out.length >= 2) {
+        const a = out[0];
+        const b = out[out.length - 1];
+        if ((a === '"' && b === '"') || (a === "'" && b === "'") || (a === "`" && b === "`")) {
+            out = out.slice(1, -1).trim();
+        }
+    }
+    if (out.length > MAX_COMMITMSG_LEN)
+        out = `${out.slice(0, MAX_COMMITMSG_LEN - 1).trimEnd()}…`;
+    return out;
+}

package/dist/server/scm.js

@@ -295,3 +295,45 @@ export async function scmFileDiff(cwd, path, lang) {
 export async function scmCommitDetail(cwd, hash, lang) {
     return git(cwd, ["show", "--no-color", "--no-ext-diff", "--find-renames", "--format=fuller", "--stat", "--patch", hash], lang);
 }
+/* ------------------------------------------------------------------ */
+/* AI commit-message context                                           */
+/* ------------------------------------------------------------------ */
+/** Cap per patch (staged / worktree) fed to the commit-message prompt —
+ *  enough for the model to see what most commits are about without letting
+ *  one huge repo blow up the one-off completion request. */
+const MAX_COMMITMSG_PATCH_CHARS = 12_000;
+/** Cap one patch at MAX_COMMITMSG_PATCH_CHARS, keeping the head (early files
+ *  matter most for a commit message) and marking the cut. */
+function capPatch(text) {
+    if (text.length <= MAX_COMMITMSG_PATCH_CHARS)
+        return text;
+    return `${text.slice(0, MAX_COMMITMSG_PATCH_CHARS)}\n… (diff truncated)`;
+}
+/** Gather staged/worktree patches, numstats, status and recent subjects for
+ *  the AI commit-message generator. Throws the usual git errors (including
+ *  "not a git repository") — the caller maps them to friendly replies. */
+export async function scmCommitContext(cwd, lang) {
+    const [stagedPatch, worktreePatch, stagedStatText, worktreeStatText, statusText, subjectText] = await Promise.all([
+        git(cwd, ["diff", "--cached", "--no-color", "--no-ext-diff", "--find-renames"], lang).catch(() => ""),
+        git(cwd, ["diff", "--no-color", "--no-ext-diff", "--find-renames"], lang).catch(() => ""),
+        git(cwd, ["diff", "--cached", "--numstat"], lang).catch(() => ""),
+        git(cwd, ["diff", "--numstat"], lang).catch(() => ""),
+        git(cwd, ["status", "--porcelain=v1", "--find-renames"], lang),
+        // Empty repos (no commits yet) make `git log` fail — that's a valid
+        // "no style reference" answer, not an error worth failing the request.
+        git(cwd, ["log", "-n", "15", "--pretty=format:%s"], lang).then((s) => s, () => ""),
+    ]);
+    const subjects = subjectText
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return {
+        subjects,
+        emptyRepo: subjects.length === 0,
+        files: parseStatusFiles(statusText),
+        stagedStat: parseNumStat(stagedStatText),
+        worktreeStat: parseNumStat(worktreeStatText),
+        stagedPatch: capPatch(stagedPatch),
+        worktreePatch: capPatch(worktreePatch),
+    };
+}

package/dist/server/settings-service.js

@@ -10,7 +10,9 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { extensionKey, normalizeDisabledPluginTools, normalizeRetryMaxAttempts, normalizeSkillList, normalizeUiLayout, } from "./client-state.js";
+import { normalizeSoftCapByModel, normalizeSoftCapTokens } from "./soft-cap.js";
 import { findVisionModels, SYSTEM_PROMPT } from "./vision-bridge.js";
+import { COMMITMSG_SYSTEM_PROMPT } from "./scm-commitmsg.js";
 import { DEFAULT_TEMPLATES } from "./subagent-templates.js";
 import { deriveLegacy, foldLegacyIntoDisabled, normalizeDisabledAgentTools } from "./tool-manager.js";
 export class SettingsService {
@@ -289,6 +291,7 @@ export class SettingsService {
                 terminalBashIdleMs: this.settings.terminalBashIdleMs,
                 editSoftEnabled: legacyTools.editSoftEnabled,
                 questionnaireEnabled: legacyTools.questionnaireEnabled,
+                parallelReminderEnabled: this.settings.parallelReminderEnabled ?? true,
                 goalModeEnabled: this.settings.goalModeEnabled,
                 devNoCache: this.settings.devNoCache ?? this.defaultDevNoCache(),
                 autoReload: this.settings.autoReload ?? this.defaultDevNoCache(),
@@ -298,6 +301,8 @@ export class SettingsService {
                 visionBridgeModel: this.settings.visionBridgeModel,
                 visionBridgePromptMode: this.settings.visionBridgePromptMode,
                 visionBridgePrompt: this.settings.visionBridgePrompt,
+                scmCommitMsgPromptMode: this.settings.scmCommitMsgPromptMode,
+                scmCommitMsgPrompt: this.settings.scmCommitMsgPrompt,
                 reviewPrompt: this.settings.reviewPrompt,
                 reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
                 disabledPlugins: [...(this.settings.disabledPlugins ?? [])],
@@ -310,6 +315,7 @@ export class SettingsService {
                 // 发给模型的工具 schema（name/description/parameters）—— 只读预览。
                 toolsSchema: promptSnap.toolsSchema,
                 visionBridgeDefaultPrompt: SYSTEM_PROMPT,
+                scmCommitMsgDefaultPrompt: COMMITMSG_SYSTEM_PROMPT,
                 visionModels: this.collectVisionModels(),
                 disabledSkills: [...this.settings.disabledSkills],
                 disabledExtensions: [...this.settings.disabledExtensions],
@@ -328,6 +334,8 @@ export class SettingsService {
                 subagentDefaultTemplates: DEFAULT_TEMPLATES.map((t) => t.name),
                 subagentDefaultModel: this.settings.subagentDefaultModel ?? null,
                 retryMaxAttempts: this.settings.retryMaxAttempts,
+                softCapTokens: this.settings.softCapTokens,
+                softCapByModel: { ...this.settings.softCapByModel },
                 subagentModels: this.collectSubagentModels(),
                 quickPhrases: [...this.settings.quickPhrases],
                 quickPhrasesEnabled: this.settings.quickPhrasesEnabled,
@@ -454,6 +462,10 @@ export class SettingsService {
         if (partial.goalModeEnabled !== undefined) {
             this.settings.goalModeEnabled = partial.goalModeEnabled;
         }
+        // 同项目并行提醒开关：同上，发送入口逐轮实时读取，无需 reload。
+        if (partial.parallelReminderEnabled !== undefined) {
+            this.settings.parallelReminderEnabled = partial.parallelReminderEnabled;
+        }
         if (partial.devNoCache !== undefined) {
             this.settings.devNoCache = partial.devNoCache;
         }
@@ -483,6 +495,12 @@ export class SettingsService {
         if (partial.visionBridgePrompt !== undefined) {
             this.settings.visionBridgePrompt = partial.visionBridgePrompt;
         }
+        if (partial.scmCommitMsgPromptMode !== undefined) {
+            this.settings.scmCommitMsgPromptMode = partial.scmCommitMsgPromptMode;
+        }
+        if (partial.scmCommitMsgPrompt !== undefined) {
+            this.settings.scmCommitMsgPrompt = partial.scmCommitMsgPrompt;
+        }
         if (partial.reviewPrompt !== undefined) {
             this.settings.reviewPrompt = partial.reviewPrompt;
         }
@@ -500,6 +518,18 @@ export class SettingsService {
             this.settings.retryMaxAttempts = normalizeRetryMaxAttempts(partial.retryMaxAttempts);
             this.host.applyRetryOverrides();
         }
+        if (partial.softCapTokens !== undefined || partial.softCapByModel !== undefined) {
+            // 压缩软上限：持久化 + 即时重算各会话的 compaction reserveTokens
+            // 覆盖（SDK 每次自动压缩检查前都重读 getCompactionSettings，无需
+            // reload；见宿主 applyCompactionOverrides，issue #229）。
+            if (partial.softCapTokens !== undefined)
+                this.settings.softCapTokens = normalizeSoftCapTokens(partial.softCapTokens);
+            if (partial.softCapByModel !== undefined)
+                this.settings.softCapByModel = normalizeSoftCapByModel(partial.softCapByModel);
+            this.host.applyCompactionOverrides();
+            // 底栏标记线读快照的 contextUsage.softCap——推一次快照让在线页即时看到。
+            this.host.flushSnapshot();
+        }
         if (partial.quickPhrases !== undefined) {
             // 归一化：去空白/空项/重名，单条 ≤200 字，最多 30 条。纯 UI 偏好，不 reload。
             const seen = new Set();
@@ -546,6 +576,8 @@ export class SettingsService {
             terminalBashIdleMs: this.settings.terminalBashIdleMs,
             editSoftEnabled: this.settings.editSoftEnabled,
             retryMaxAttempts: this.settings.retryMaxAttempts,
+            softCapTokens: this.settings.softCapTokens,
+            softCapByModel: { ...this.settings.softCapByModel },
             reviewPrompt: this.settings.reviewPrompt,
             reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
             skillsFullText: [...normalizeSkillList(this.settings.skillsFullText)],
@@ -594,8 +626,13 @@ export class SettingsService {
             editSoftEnabled: presetLegacy.editSoftEnabled,
             // 重试次数随预设走；旧预设缺字段时保留当前值，应用后即时注入各会话。
             retryMaxAttempts: p.retryMaxAttempts ?? this.settings.retryMaxAttempts,
+            // 压缩软上限同样随预设走（issue #229）；旧预设缺字段时保留当前值。
+            softCapTokens: normalizeSoftCapTokens(p.softCapTokens ?? this.settings.softCapTokens),
+            softCapByModel: normalizeSoftCapByModel(p.softCapByModel ?? this.settings.softCapByModel),
             // 问卷开关不进预设——保留当前值。
             questionnaireEnabled: this.settings.questionnaireEnabled,
+            // 同项目并行提醒开关不进预设——保留当前值。
+            parallelReminderEnabled: this.settings.parallelReminderEnabled ?? true,
             // 目标模式总开关不进预设——保留当前值。
             goalModeEnabled: this.settings.goalModeEnabled,
             reviewPrompt: p.reviewPrompt ?? this.settings.reviewPrompt,
@@ -614,6 +651,9 @@ export class SettingsService {
             visionBridgeModel: this.settings.visionBridgeModel,
             visionBridgePromptMode: this.settings.visionBridgePromptMode,
             visionBridgePrompt: this.settings.visionBridgePrompt,
+            // 「AI 提交信息」提示词同样不进预设——保留当前值。
+            scmCommitMsgPromptMode: this.settings.scmCommitMsgPromptMode,
+            scmCommitMsgPrompt: this.settings.scmCommitMsgPrompt,
             // 子代理默认模型也不进预设——保留当前值。
             subagentDefaultModel: this.settings.subagentDefaultModel,
             // 快捷短语是纯 UI 偏好，不进预设——保留当前值。

package/dist/server/skill-tool.js

@@ -0,0 +1,120 @@
+// ---------------------------------------------------------------------------
+// skill-tool.ts — 让 AI 按名取技能全文（名录 + skill 工具）
+// ---------------------------------------------------------------------------
+// 背景：{{skills}} 默认只渲染名录（name/description/location），引导语原来让
+// 模型“用 read 工具加载技能文件”——模型要自己拼 location 路径调 read，权限大
+// 且容易猜错路径。本工具提供专用通道：skill({name}) 精确命中，读文件包成与
+// SDK 一致的 `<skill name location>` 块（前端 parseSkillBlock 直接认，渲染折叠
+// 卡片）；不给 name 则返回名录 + 用法，找错名则给纠错列表。
+//
+// 约束（第 1 条定稿，不破坏现有体系）：
+//   - 名录渲染不动；skillsFullText 名单注入不动；/skill:name 手势不动；
+//   - 正文每次重读（不缓存），单文件 8KB 封顶（与 fillSkillContents 同口径）；
+//   - 禁用集由 host 在调用时过滤（与 skillsOverride 主会话语义一致），工具侧
+//     查不到被禁用的技能；
+//   - 与 SDK 同名工具撞名时 customTools 按 name 覆盖（bash 本体是先例）。
+//
+// 双语约定（issue #91）：definition 走 bilingual(en, zh) 内联双语；per-call
+// 返回文本按 lang 取 pick(lang, zh, en, key)，缺表回落英文内联。
+// ---------------------------------------------------------------------------
+import { statSync, readFileSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { bilingual, pick } from "./i18n.js";
+import { decodeText } from "./text-sniff.js";
+/** 单文件正文上限（与 agent-service fillSkillContents 同口径：8KB）。 */
+export const SKILL_TOOL_FILE_CAP = 8192;
+/** 精确名匹配（大小写敏感，与 skillsFullText 名单语义一致）。 */
+export function findSkill(skills, name) {
+    const n = name.trim();
+    if (!n)
+        return undefined;
+    return skills.find((s) => s.name === n);
+}
+/** 大小写不敏感子串纠错（空 query 全匹配，调用方截行数）。 */
+export function suggestSkills(skills, name) {
+    const q = name.trim().toLowerCase();
+    if (!q)
+        return skills;
+    return skills.filter((s) => s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q));
+}
+/** 名录文本（一行一名 + 一句话描述，无技能时给空目录句）。 */
+export function formatSkillCatalog(skills, lang) {
+    if (skills.length === 0) {
+        return pick(lang, "当前没有可用技能。", "No skills are currently available.", "skill.catalog.empty");
+    }
+    const head = pick(lang, `可用技能（${skills.length}）：`, `Available skills (${skills.length}):`, "skill.catalog.title", { count: skills.length });
+    const lines = skills.map((s) => `- ${s.name}${s.description.trim() ? ` — ${s.description.trim()}` : ""}`);
+    return `${head}\n${lines.join("\n")}`;
+}
+/** 技能全文块（与 SDK 的 /skill:name 展开格式一致，前端按 skill 卡片渲染）。 */
+export function renderSkillContent(name, location, body) {
+    return `<skill name="${name}" location="${location}">\n${body.trim()}\n</skill>`;
+}
+export function makeSkillTool(host, lang) {
+    const getLang = lang ?? (() => "en");
+    const text = (t, details = {}) => ({
+        content: [{ type: "text", text: t }],
+        details,
+    });
+    return defineTool({
+        name: "skill",
+        label: "Load a skill",
+        description: bilingual("Load a skill's full text by its exact name (see the <available_skills> catalog in the system prompt). " +
+            "Prefer this over reading the skill file with the read tool — no path guessing needed. " +
+            "Call without a name to list the current catalog.", "按技能精确名加载其全文（名录见系统提示词里的 <available_skills>）。" +
+            "优先用它，不要自己拼路径调 read 工具读技能文件。" +
+            "不给名则返回当前名录。"),
+        promptSnippet: bilingual("load a skill's full text by name (skill tool, preferred over read)", "按名加载技能全文（skill 工具，优先于 read）"),
+        parameters: Type.Object({
+            name: Type.Optional(Type.String({
+                description: "Exact skill name from the catalog. Omit to list the current catalog.",
+            })),
+        }),
+        execute: async (_id, p) => {
+            let skills = [];
+            try {
+                skills = host.listSkills();
+            }
+            catch {
+                skills = [];
+            }
+            const L = getLang();
+            const name = typeof p.name === "string" ? p.name.trim() : "";
+            // 无名 → 名录 + 用法。
+            if (!name) {
+                const hint = pick(L, "用 skill({name}) 按名取全文。", "Use skill({name}) to load the full text by name.", "skill.catalog.hint");
+                return text(`${formatSkillCatalog(skills, L)}\n${hint}`, { count: skills.length });
+            }
+            const found = findSkill(skills, name);
+            // 找错名 → 纠错列表（不抛错，报名录）。
+            if (!found) {
+                const sug = suggestSkills(skills, name).slice(0, 10);
+                const head = pick(L, `没有名为 ${name} 的技能。`, `No skill named ${name}.`, "skill.not.found", { name });
+                const sugText = sug.length > 0 ? `\n${formatSkillCatalog(sug, L)}` : `\n${formatSkillCatalog(skills, L)}`;
+                return text(`${head}${sugText}`, { name, count: skills.length });
+            }
+            // 命中 → 最好努力读正文（每次重读，不缓存；失败/超限给可读错）。
+            if (!found.filePath) {
+                return text(pick(L, `技能 ${name} 没有关联文件路径，取不到全文。`, `Skill ${name} has no file path; full text unavailable.`, "skill.no.filepath", { name }));
+            }
+            try {
+                const st = statSync(found.filePath);
+                if (!st.isFile() || st.size <= 0 || st.size > SKILL_TOOL_FILE_CAP) {
+                    return text(pick(L, `技能 ${name} 的文件不可读（不存在/超 ${SKILL_TOOL_FILE_CAP / 1024}KB 上限）。`, `Skill ${name} file unreadable (missing or over the ${SKILL_TOOL_FILE_CAP / 1024}KB cap).`, "skill.file.unreadable", { name }));
+                }
+                const body = decodeText(readFileSync(found.filePath).subarray(0, st.size)).trim();
+                if (!body) {
+                    return text(pick(L, `技能 ${name} 的文件是空的。`, `Skill ${name} file is empty.`, "skill.file.empty", { name }));
+                }
+                return text(renderSkillContent(found.name, found.filePath, body), {
+                    name: found.name,
+                    location: found.filePath,
+                });
+            }
+            catch {
+                return text(pick(L, `技能 ${name} 的文件读取失败（可能已被删除或移走）。`, `Failed to read skill ${name} file (may have been deleted or moved).`, "skill.file.failed", { name }));
+            }
+        },
+    });
+}

package/dist/server/soft-cap.js

@@ -0,0 +1,68 @@
+/**
+ * 自定义上下文压缩阈值（Soft Cap，issue #229）。
+ *
+ * 背景：SDK 的自动压缩只看物理上限（shouldCompact：tokens > window - reserveTokens，
+ * reserveTokens 默认 16384）。对 1M 上下文的模型会堆到 ~900K 才压；对 Grok 这类
+ * 200K 起阶梯翻倍计费的模型，会在高价区跑很久，还伴随长上下文降智。
+ *
+ * 实现：软上限 C 转成 reserveTokens = W - C，经
+ * session.settingsManager.applyOverrides({ compaction: { reserveTokens } })
+ * 注入（与重试次数覆盖同一 live 机制，reload/建会话/换模型后重放）。
+ * 关掉软上限时回填 SDK 默认（DEFAULT_COMPACTION_SETTINGS.reserveTokens），
+ * 不让旧覆盖泄漏。
+ */
+import { DEFAULT_COMPACTION_SETTINGS } from "@earendil-works/pi-coding-agent";
+/** SDK 默认保留 token（软上限关闭时的回填值）。 */
+export const DEFAULT_COMPACTION_RESERVE_TOKENS = DEFAULT_COMPACTION_SETTINGS.reserveTokens;
+/** 软上限下限（tokens）：低于此值每轮都压，无意义，直接视为关闭。 */
+export const SOFT_CAP_MIN_TOKENS = 2000;
+/** 压缩后至少要剩这么多工作空间（摘要本身也要占 reserve*0.8 的预算）。 */
+export const SOFT_CAP_MIN_HEADROOM = 2048;
+/** 单客户端最多存多少条按模型覆盖（防手滑粘贴刷爆 client-state）。 */
+export const SOFT_CAP_MAX_OVERRIDES = 64;
+/** 归一化全局软上限：非数值/<=0 = 关闭；钳制到 [0, 10_000_000] 整数。 */
+export function normalizeSoftCapTokens(v) {
+    const n = Math.floor(Number(v));
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.min(10_000_000, n);
+}
+/** 归一化按模型覆盖：key = "provider/id" 非空（≤200 字），value 走
+ *  normalizeSoftCapTokens；0 值条目丢弃（= 用全局）；上限 64 条。纯函数。 */
+export function normalizeSoftCapByModel(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (Object.keys(out).length >= SOFT_CAP_MAX_OVERRIDES)
+            break;
+        const key = String(k).trim();
+        if (!key || key.length > 200)
+            continue;
+        const n = normalizeSoftCapTokens(val);
+        if (n > 0)
+            out[key] = n;
+    }
+    return out;
+}
+/** 当前模型的生效软上限（0 = 关闭）：按模型覆盖优先于全局。 */
+export function effectiveSoftCap(globalCap, byModel, modelId) {
+    if (modelId) {
+        const per = byModel?.[modelId.trim()];
+        if (per !== undefined && per > 0)
+            return per;
+    }
+    return globalCap > 0 ? globalCap : 0;
+}
+/** 软上限 → SDK reserveTokens（null = 不合法/关闭，走 SDK 默认）。
+ *  合法条件：cap ≥ SOFT_CAP_MIN_TOKENS 且压完至少剩 SOFT_CAP_MIN_HEADROOM。 */
+export function softCapToReserve(contextWindow, cap) {
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return null;
+    if (!Number.isFinite(cap) || cap < SOFT_CAP_MIN_TOKENS)
+        return null;
+    const reserve = Math.floor(contextWindow - cap);
+    if (reserve < SOFT_CAP_MIN_HEADROOM)
+        return null;
+    return reserve;
+}

package/dist/server/subagent-templates.js

@@ -623,6 +623,12 @@ export class SubagentTemplatesStore {
         const t = normalize(input);
         if (!t)
             return `模板名称不合法（去空白后 1-${NAME_MAX} 字符）`;
+        // replace + 空提示词 = 子代理静默用默认 persona 运行（模板等于没生效），
+        // 在保存期直接拦下：只想限定白名单请用 append 模式。读盘的老数据不拦
+        // （向后兼容，只拦新保存）。
+        if (t.promptMode === "replace" && !t.systemPrompt.trim() && !(t.systemPromptEn ?? "").trim()) {
+            return `模板 "${t.name}" 用了 replace 模式但系统提示词为空：replace 会整体替换子代理 persona，空提示词等于模板没生效。请填写提示词（中文或英文至少一个），只想限定技能/扩展白名单请用 append 模式`;
+        }
         const list = this.load();
         const i = list.findIndex((x) => x.name === t.name);
         if (i >= 0)