From be89a604f1b0b183ffa6faf1bd693c58a803c978 Mon Sep 17 00:00:00 2001
From: Kabochar <anemailbox@163.com>
Date: Sat, 1 Aug 2026 15:07:55 +0800
Subject: [PATCH] feat: collapse slash command expansion in user messages

Show a compact clickable command reference for slash-command messages
(/skill:name and prompt templates) instead of the full SDK-expanded
text. The user-supplied arguments stay fully visible; clicking the
command name toggles the expanded skill/template body.

- lib/slash-display.ts: pure helpers (command parsing, skill expansion
  reverse-matching, FIFO tracker) + 17 unit tests
- rpc-manager.ts: inject originalText on message_end for user messages
  via a new message object (never mutates SDK-shared state), always
  consume one FIFO entry per message, clear the tracker on prompt
  failures
- session-reader.ts: reverse-match skill expansions when loading
  session history
- MessageView.tsx: render command name as accent-colored toggle with
  args shown verbatim; keep image blocks in both branches; add
  aria-expanded

Storage and model input stay unchanged: session JSONL keeps the
expanded text and originalText is a display-only field.
---
 components/MessageView.tsx | 130 ++++++++++++++++++++++++------
 lib/rpc-manager.test.mjs   |  27 +++++++
 lib/rpc-manager.ts         |  60 +++++++++++++-
 lib/session-reader.ts      |  17 +++-
 lib/slash-display.test.mjs | 158 +++++++++++++++++++++++++++++++++++++
 lib/slash-display.ts       | 110 ++++++++++++++++++++++++++
 lib/types.ts               |   6 ++
 7 files changed, 479 insertions(+), 29 deletions(-)
 create mode 100644 lib/slash-display.test.mjs
 create mode 100644 lib/slash-display.ts

diff --git a/components/MessageView.tsx b/components/MessageView.tsx
index d73bee37f..11adf25ec 100644
--- a/components/MessageView.tsx
+++ b/components/MessageView.tsx
@@ -151,6 +151,14 @@ function UserMessageView({ message, cwd, onOpenFile, entryId, onFork, forking, o
   const { t } = useI18n();
   const [hovered, setHovered] = useState(false);
   const [copied, setCopied] = useState(false);
+  // 斜杠命令消息：默认折叠为命令 chip，点击展开 SDK 展开后的完整文本
+  const [expanded, setExpanded] = useState(false);
+  const originalText = message.originalText;
+  // 拆分命令名与参数：/skill:web-access 验证参数 → 命令名 + 参数（无空格则为纯命令）
+  const rawCommand = originalText ?? "";
+  const spaceIndex = rawCommand.indexOf(" ");
+  const commandName = spaceIndex === -1 ? rawCommand : rawCommand.slice(0, spaceIndex);
+  const commandArgs = spaceIndex === -1 ? "" : rawCommand.slice(spaceIndex + 1).trim();
 
   const content =
     typeof message.content === "string"
@@ -167,10 +175,39 @@ function UserMessageView({ message, cwd, onOpenFile, entryId, onFork, forking, o
 
   const time = formatTime(message.timestamp);
   const canFork = !!entryId && !!onFork;
+  // 复制/编辑使用命令原文（界面所见即所得），展开全文仅用于展示
+  const copyTarget = originalText ?? content;
+
+  // 图片渲染（originalText 折叠分支与原分支共用，避免斜杠命令+图片时图片消失）
+  const imageBlocksNode = imageBlocks.length > 0 && (
+    <div style={{ display: "flex", gap: 6, flexWrap: "wrap", marginBottom: content ? 8 : 0 }}>
+      {imageBlocks.map((img, i) => {
+        // lib/types.ts ImageContent uses {source:{type,data,media_type,url}}
+        // pi-ai on-disk format uses flat {data, mimeType} — handle both
+        const flat = img as unknown as { data?: string; mimeType?: string };
+        const src = img.source
+          ? img.source.type === "base64"
+            ? `data:${img.source.media_type};base64,${img.source.data}`
+            : img.source.url ?? ""
+          : flat.data
+            ? `data:${flat.mimeType};base64,${flat.data}`
+            : "";
+        return (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            key={i}
+            src={src}
+            alt=""
+            style={{ maxWidth: 240, maxHeight: 240, borderRadius: 6, objectFit: "contain", display: "block", border: "1px solid rgba(59,130,246,0.15)" }}
+          />
+        );
+      })}
+    </div>
+  );
   const canNavigate = !!prevAssistantEntryId && !!onNavigate;
 
   const copyContent = () => {
-    copyText(content).then(() => {
+    copyText(copyTarget).then(() => {
       setCopied(true);
       setTimeout(() => setCopied(false), 1500);
     });
@@ -197,32 +234,73 @@ function UserMessageView({ message, cwd, onOpenFile, entryId, onFork, forking, o
             wordBreak: "break-word",
           }}
         >
-          {imageBlocks.length > 0 && (
-            <div style={{ display: "flex", gap: 6, flexWrap: "wrap", marginBottom: content ? 8 : 0 }}>
-              {imageBlocks.map((img, i) => {
-                // lib/types.ts ImageContent uses {source:{type,data,media_type,url}}
-                // pi-ai on-disk format uses flat {data, mimeType} — handle both
-                const flat = img as unknown as { data?: string; mimeType?: string };
-                const src = img.source
-                  ? img.source.type === "base64"
-                    ? `data:${img.source.media_type};base64,${img.source.data}`
-                    : img.source.url ?? ""
-                  : flat.data
-                    ? `data:${flat.mimeType};base64,${flat.data}`
-                    : "";
-                return (
-                  // eslint-disable-next-line @next/next/no-img-element
-                  <img
-                    key={i}
-                    src={src}
-                    alt=""
-                    style={{ maxWidth: 240, maxHeight: 240, borderRadius: 6, objectFit: "contain", display: "block", border: "1px solid rgba(59,130,246,0.15)" }}
-                  />
-                );
-              })}
+          {originalText ? (
+            // 斜杠命令消息：命令名紧凑展示（accent 色，点击展开/折叠全文），
+            // 用户输入的参数部分原文完整展示，不折叠；无 hover 背景反馈
+            <div style={{ display: "flex", flexDirection: "column", gap: 6, minWidth: 0 }}>
+              {imageBlocksNode}
+              <div style={{ display: "flex", alignItems: "flex-start", gap: 8, flexWrap: "wrap" }}>
+                <button
+                  onClick={() => setExpanded((prev) => !prev)}
+                  title={expanded ? t("i18n.collapse") : t("i18n.expand")}
+                  aria-expanded={expanded}
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 6,
+                    flexShrink: 0,
+                    padding: 0,
+                    background: "none",
+                    border: "none",
+                    cursor: "pointer",
+                    color: "var(--accent)",
+                    fontFamily: "var(--font-mono)",
+                    fontSize: 13,
+                    textAlign: "left",
+                  }}
+                >
+                  <span style={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                    {commandName}
+                  </span>
+                  <svg
+                    width="11"
+                    height="11"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    style={{ flexShrink: 0, opacity: 0.75, transform: expanded ? "rotate(180deg)" : "none", transition: "transform 0.15s" }}
+                    aria-hidden="true"
+                  >
+                    <polyline points="6 9 12 15 18 9" />
+                  </svg>
+                </button>
+                {commandArgs && (
+                  <span style={{
+                    color: "var(--text)",
+                    fontSize: 14,
+                    lineHeight: 1.6,
+                    whiteSpace: "pre-wrap",
+                    wordBreak: "break-word",
+                    minWidth: 0,
+                    flex: 1,
+                  }}>
+                    {commandArgs}
+                  </span>
+                )}
+              </div>
+              {expanded && (
+                <MarkdownBody className="markdown-user-message" cwd={cwd} onOpenFile={onOpenFile}>{content}</MarkdownBody>
+              )}
             </div>
-          )}
+          ) : (
+          <>
+          {imageBlocksNode}
           {content && <MarkdownBody className="markdown-user-message" cwd={cwd} onOpenFile={onOpenFile}>{content}</MarkdownBody>}
+          </>
+          )}
         </div>
 
       </div>
@@ -278,7 +356,7 @@ function UserMessageView({ message, cwd, onOpenFile, entryId, onFork, forking, o
             }}>
               {canNavigate && (
                 <button
-                  onClick={() => { onNavigate!(prevAssistantEntryId!); onEditContent?.(content); }}
+                  onClick={() => { onNavigate!(prevAssistantEntryId!); onEditContent?.(copyTarget); }}
                    title={t("i18n.editFromHereTitle")}
                   style={{
                     display: "flex", alignItems: "center", gap: 4,
diff --git a/lib/rpc-manager.test.mjs b/lib/rpc-manager.test.mjs
index 0fe6a9fd3..468c47a86 100644
--- a/lib/rpc-manager.test.mjs
+++ b/lib/rpc-manager.test.mjs
@@ -131,3 +131,30 @@ test("reloading a session invalidates the models cache", async () => {
   assert.match(reloadSource, /await this\.inner\.reload\(\)/);
   assert.match(reloadSource, /this\.applyForcedEmptySystemPrompt\(\);\s*invalidateModelsCache\(\)/);
 });
+
+test("slash command injection rebuilds the message object instead of mutating SDK-shared state", async () => {
+  const source = await readFile(new URL("./rpc-manager.ts", import.meta.url), "utf8");
+  const startSource = source.slice(source.indexOf("start(): void"));
+
+  // SDK 的 _emit 同步分发后会用同一 message 对象落盘/进入模型上下文，
+  // 注入必须构造新对象而不是改写 event.message
+  assert.match(startSource, /this\.emit\(\{ \.\.\.event, message: \{ \.\.\.\(event\.message as Record<string, unknown>\), originalText \} \}\)/);
+  assert.doesNotMatch(startSource, /\(event\.message as Record<string, unknown>\)\.originalText/);
+});
+
+test("slash command injection consumes one FIFO entry per user message_end", async () => {
+  const source = await readFile(new URL("./rpc-manager.ts", import.meta.url), "utf8");
+  const startSource = source.slice(source.indexOf("start(): void"));
+
+  // 无论特征识别是否命中都要消费一条，避免残留记录错注入下一条消息
+  assert.match(startSource, /const fromQueue = this\.slashOriginals\.consumeFor\(text\);/);
+  assert.match(startSource, /const originalText = resolveSlashDisplayText\(text\) \?\? fromQueue;/);
+});
+
+test("slash command tracker is cleared when prompt fails or is rejected", async () => {
+  const source = await readFile(new URL("./rpc-manager.ts", import.meta.url), "utf8");
+
+  // isBashRunning 拒绝、prompt catch、steer/follow_up catch 三处清理
+  const clearCount = source.match(/slashOriginals\.clear\(\)/g)?.length ?? 0;
+  assert.ok(clearCount >= 3, `expected >= 3 clear() calls, got ${clearCount}`);
+});
diff --git a/lib/rpc-manager.ts b/lib/rpc-manager.ts
index cfb611002..fb6eca3de 100644
--- a/lib/rpc-manager.ts
+++ b/lib/rpc-manager.ts
@@ -8,6 +8,7 @@ import { validateAgentImages } from "./image-attachments";
 import { invalidateModelsCache } from "./models-cache";
 import { resolveVisibleModels, selectInitialModelScope } from "./model-scope";
 import { cacheSessionPath, invalidateSessionListCache } from "./session-reader";
+import { parseSlashCommandName, resolveSlashDisplayText, SlashOriginalTracker, userMessagePlainText } from "./slash-display";
 import { getProjectTrustStatus, projectTrustReloadOptions } from "./project-trust";
 import { persistExplicitStartupPreferences } from "./startup-preferences";
 import type { SlashCommandInfo } from "@earendil-works/pi-coding-agent";
@@ -151,6 +152,8 @@ export class AgentSessionWrapper {
   private onDestroyCallback: (() => void) | null = null;
   private shutdownPromise: Promise<void> | null = null;
   private _alive = true;
+  /** FIFO: 已发送且确定会被 SDK 展开的斜杠命令原文，user 消息回传时消费注入 */
+  private slashOriginals = new SlashOriginalTracker();
 
   constructor(public readonly inner: AgentSessionLike) {}
 
@@ -179,6 +182,23 @@ export class AgentSessionWrapper {
       if (event.type === "agent_end") {
         invalidateSessionListCache();
       }
+      // 斜杠命令（/skill:name /模板名）由 SDK 展开后回传：在 message_end 的 user
+      // 消息上注入原始命令，供界面紧凑展示。
+      // 注意：SDK 的 _emit 同步分发后会用同一 message 对象 appendMessage 落盘并进入
+      // 模型上下文，因此绝不能改写原对象 —— 用展开运算符构造新对象注入展示层字段。
+      // 仅在 message_end 处理 —— message_start/update 的 user 消息被前端忽略。
+      if (event.type === "message_end" && (event.message as { role?: string } | undefined)?.role === "user") {
+        const message = event.message as { content?: string | Array<{ type: string; text?: string }> };
+        const text = userMessagePlainText(message.content ?? "");
+        // 每条 user message_end 固定消费一条 FIFO（无论特征识别是否命中），
+        // 避免记录残留导致下一条消息错注入；特征识别结果优先（skill 展开文本可自证）
+        const fromQueue = this.slashOriginals.consumeFor(text);
+        const originalText = resolveSlashDisplayText(text) ?? fromQueue;
+        if (originalText && originalText !== text) {
+          this.emit({ ...event, message: { ...(event.message as Record<string, unknown>), originalText } });
+          return;
+        }
+      }
       if (IDLE_RESET_EVENT_TYPES.has(event.type)) this.resetIdleTimer();
       this.emit(event);
       if (RUNNING_STATE_EVENT_TYPES.has(event.type)) notifyRunningChange();
@@ -280,6 +300,22 @@ export class AgentSessionWrapper {
     }
   }
 
+  /**
+   * 记录确定会被 SDK 展开的斜杠命令原文（命中 prompt 模板或 skill）。
+   * 只记录这两类：扩展命令由 SDK 立即执行、不产生 user 消息，记录会造成 FIFO 残留。
+   */
+  private trackSlashOriginal(message: string): void {
+    if (typeof message !== "string") return;
+    const name = parseSlashCommandName(message);
+    if (!name) return;
+    const isPromptTemplate = this.inner.promptTemplates.some((template) => template.name === name);
+    const isSkill = name.startsWith("skill:")
+      && this.inner.resourceLoader.getSkills().skills.some((skill) => `skill:${skill.name}` === name);
+    if (isPromptTemplate || isSkill) {
+      this.slashOriginals.push(message.trim());
+    }
+  }
+
   private applyForcedEmptySystemPrompt(): void {
     if (this.forceEmptySystemPrompt && this.inner.agent.state) {
       this.inner.agent.state.systemPrompt = "";
@@ -344,11 +380,16 @@ export class AgentSessionWrapper {
     if (type === "prompt" || type === "steer" || type === "follow_up") {
       const imageError = validateAgentImages(command.images);
       if (imageError) throw new Error(imageError);
+      // 记录确定会被 SDK 展开的斜杠命令（命中 prompt 模板或 skill）原文，
+      // 供 message_end 回传时注入展示。扩展命令不产生 user 消息，不记录。
+      this.trackSlashOriginal(command.message as string);
     }
 
     switch (type) {
       case "prompt": {
         if (this.inner.isBashRunning) {
+          // prompt 未发出，刚 push 的斜杠命令记录不会再有 message_end 消费，立即清空
+          this.slashOriginals.clear();
           throw new Error("Cannot send a prompt while a shell command is running");
         }
         // Fire and forget — events come via subscribe
@@ -367,6 +408,9 @@ export class AgentSessionWrapper {
           notifyRunningChange();
         }).catch((error) => {
           this.promptRunning = false;
+          // prompt 发送失败（无 model / auth 校验失败等）不会产生 message_end，
+          // 清理队列避免残留记录错注入后续消息
+          this.slashOriginals.clear();
           this.resetIdleTimer();
           invalidateSessionListCache();
           this.emit({
@@ -526,13 +570,25 @@ export class AgentSessionWrapper {
 
       case "steer": {
         const steerImages = command.images as Array<{ type: "image"; data: string; mimeType: string }> | undefined;
-        await this.inner.steer(command.message as string, steerImages?.length ? steerImages : undefined);
+        try {
+          await this.inner.steer(command.message as string, steerImages?.length ? steerImages : undefined);
+        } catch (error) {
+          // steer 入队失败不会产生 message_end，清理本次记录避免残留
+          this.slashOriginals.clear();
+          throw error;
+        }
         return null;
       }
 
       case "follow_up": {
         const followImages = command.images as Array<{ type: "image"; data: string; mimeType: string }> | undefined;
-        await this.inner.followUp(command.message as string, followImages?.length ? followImages : undefined);
+        try {
+          await this.inner.followUp(command.message as string, followImages?.length ? followImages : undefined);
+        } catch (error) {
+          // followUp 入队失败不会产生 message_end，清理本次记录避免残留
+          this.slashOriginals.clear();
+          throw error;
+        }
         return null;
       }
 
diff --git a/lib/session-reader.ts b/lib/session-reader.ts
index 6c0da255c..967973382 100644
--- a/lib/session-reader.ts
+++ b/lib/session-reader.ts
@@ -6,9 +6,10 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { closeSync, openSync, readSync } from "fs";
 import { normalize as normalizePath } from "path";
-import type { AgentMessage, SessionEntry, SessionHeader, SessionInfo, SessionContext } from "./types";
+import type { AgentMessage, SessionEntry, SessionHeader, SessionInfo, SessionContext, UserMessage } from "./types";
 import type { SessionEntry as PiSessionEntry, SessionInfo as PiSessionInfo } from "@earendil-works/pi-coding-agent";
 import { normalizeToolCalls } from "./normalize";
+import { resolveSlashDisplayText, userMessagePlainText } from "./slash-display";
 import { sessionPathKey } from "./session-path";
 import { resolveProject, type ProjectInfo } from "./worktree";
 
@@ -226,6 +227,20 @@ export function buildSessionContext(
     const localEntry = entry as unknown as SessionEntry;
     const m = entryToUiMessage(localEntry, options);
     if (m) {
+      // 斜杠命令展开消息（/skill:name /模板名）：还原紧凑命令形式供界面展示。
+      // prompt 模板展开文本无特征标记，无法还原，保持全文（已知局限）。
+      // 注意用展开运算符新建消息对象注入 originalText，不改写 SDK 返回的原始对象
+      //（该对象可能被 SDK 后续持久化复用，直接赋值会污染存储）。
+      if (m.role === "user") {
+        const userMessage = m as UserMessage;
+        const text = userMessagePlainText(userMessage.content);
+        const originalText = resolveSlashDisplayText(text);
+        if (originalText && originalText !== text) {
+          messages.push({ ...userMessage, originalText });
+          entryIds.push(localEntry.id);
+          continue;
+        }
+      }
       messages.push(m);
       entryIds.push(localEntry.id);
     }
diff --git a/lib/slash-display.test.mjs b/lib/slash-display.test.mjs
new file mode 100644
index 000000000..db67316b7
--- /dev/null
+++ b/lib/slash-display.test.mjs
@@ -0,0 +1,158 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+// 斜杠命令展开消息的展示还原工具单测（与 lib/slash-display.ts 配套）
+const {
+  parseSlashCommandName,
+  skillExpansionToCommand,
+  resolveSlashDisplayText,
+  userMessagePlainText,
+  SlashOriginalTracker,
+} = await import("./slash-display.ts");
+
+// --- parseSlashCommandName ---
+
+test("parseSlashCommandName: 解析带参数的命令", () => {
+  assert.equal(parseSlashCommandName("/hello 123132"), "hello");
+  assert.equal(parseSlashCommandName("/skill:review src/main.go"), "skill:review");
+});
+
+test("parseSlashCommandName: 无参数命令与边界", () => {
+  assert.equal(parseSlashCommandName("/nospace"), "nospace");
+  assert.equal(parseSlashCommandName("/"), null);
+  assert.equal(parseSlashCommandName("  /hello  x  "), "hello");
+});
+
+test("parseSlashCommandName: 非命令文本返回 null", () => {
+  assert.equal(parseSlashCommandName("hello world"), null);
+  assert.equal(parseSlashCommandName(""), null);
+  assert.equal(parseSlashCommandName("!ls -la"), null);
+});
+
+// --- skillExpansionToCommand ---
+
+const SKILL_WITH_ARGS = `<skill name="hello" location="/path/to/hello.md">
+References are relative to /path/to.
+
+Hello world skill body
+
+</skill>
+
+123132`;
+
+const SKILL_NO_ARGS = `<skill name="hello" location="/path/to/hello.md">
+References are relative to /path/to.
+
+Hello world skill body
+
+</skill>`;
+
+test("skillExpansionToCommand: 带参数还原为 /skill:name args", () => {
+  assert.equal(skillExpansionToCommand(SKILL_WITH_ARGS), "/skill:hello 123132");
+});
+
+test("skillExpansionToCommand: 无参数还原为 /skill:name", () => {
+  assert.equal(skillExpansionToCommand(SKILL_NO_ARGS), "/skill:hello");
+});
+
+test("skillExpansionToCommand: 多行参数 trim 后保留", () => {
+  const multiLine = `<skill name="x" location="/l.md">
+References are relative to /l.
+
+body
+
+</skill>
+
+line1
+line2`;
+  assert.equal(skillExpansionToCommand(multiLine), "/skill:x line1\nline2");
+});
+
+test("skillExpansionToCommand: 非 skill 展开文本返回 null", () => {
+  assert.equal(skillExpansionToCommand("普通文本"), null);
+  assert.equal(skillExpansionToCommand("<skill>没有属性</skill>"), null);
+  assert.equal(skillExpansionToCommand(""), null);
+});
+
+// --- resolveSlashDisplayText ---
+
+test("resolveSlashDisplayText: 未展开的命令原样返回", () => {
+  assert.equal(resolveSlashDisplayText("/hello 123132"), "/hello 123132");
+  assert.equal(resolveSlashDisplayText("/compact"), "/compact");
+});
+
+test("resolveSlashDisplayText: skill 展开还原为命令", () => {
+  assert.equal(resolveSlashDisplayText(SKILL_WITH_ARGS), "/skill:hello 123132");
+});
+
+test("resolveSlashDisplayText: 普通文本返回 null（保持全文）", () => {
+  assert.equal(resolveSlashDisplayText("hello world"), null);
+  assert.equal(resolveSlashDisplayText(""), null);
+  assert.equal(resolveSlashDisplayText("   "), null);
+});
+
+// --- userMessagePlainText ---
+
+test("userMessagePlainText: string 形式原样返回", () => {
+  assert.equal(userMessagePlainText("/hello 1"), "/hello 1");
+});
+
+test("userMessagePlainText: blocks 形式拼接文本块，忽略非文本块", () => {
+  assert.equal(
+    userMessagePlainText([
+      { type: "text", text: "第一行" },
+      { type: "image" },
+      { type: "text", text: "第二行" },
+    ]),
+    "第一行\n第二行",
+  );
+});
+
+test("userMessagePlainText: 空数组返回空串", () => {
+  assert.equal(userMessagePlainText([]), "");
+});
+
+// --- SlashOriginalTracker ---
+
+test("SlashOriginalTracker: FIFO 顺序注入", () => {
+  const tracker = new SlashOriginalTracker();
+  tracker.push("/skill:a 1");
+  tracker.push("/template-b hello");
+  // 展开文本与原文不同，注入原文
+  assert.equal(tracker.consumeFor("<skill name=\"a\" location=\"/a.md\">\n</skill>\n\n1"), "/skill:a 1");
+  assert.equal(tracker.consumeFor("模板 B 的展开正文 hello"), "/template-b hello");
+  assert.equal(tracker.size, 0);
+});
+
+test("SlashOriginalTracker: 空栈返回 null", () => {
+  const tracker = new SlashOriginalTracker();
+  assert.equal(tracker.consumeFor("任意文本"), null);
+});
+
+test("SlashOriginalTracker: 回传文本与原文相同（未展开）时消费但不注入", () => {
+  const tracker = new SlashOriginalTracker();
+  tracker.push("/unknown-cmd x");
+  // 防御分支：SDK 未展开（命令未命中），原样回传
+  assert.equal(tracker.consumeFor("/unknown-cmd x"), null);
+  assert.equal(tracker.size, 0);
+});
+
+test("SlashOriginalTracker: clear 清空所有记录", () => {
+  const tracker = new SlashOriginalTracker();
+  tracker.push("/a 1");
+  tracker.push("/b 2");
+  tracker.clear();
+  assert.equal(tracker.size, 0);
+  assert.equal(tracker.consumeFor("任意文本"), null);
+});
+
+test("SlashOriginalTracker: 跨多条消息保持顺序", () => {
+  const tracker = new SlashOriginalTracker();
+  tracker.push("/a 1");
+  tracker.push("/b 2");
+  tracker.push("/c 3");
+  assert.equal(tracker.consumeFor("A 展开文本 1"), "/a 1");
+  assert.equal(tracker.consumeFor("B 展开文本 2"), "/b 2");
+  assert.equal(tracker.consumeFor("C 展开文本 3"), "/c 3");
+  assert.equal(tracker.consumeFor("多余的普通消息"), null);
+});
diff --git a/lib/slash-display.ts b/lib/slash-display.ts
new file mode 100644
index 000000000..eba9bb331
--- /dev/null
+++ b/lib/slash-display.ts
@@ -0,0 +1,110 @@
+/**
+ * 斜杠命令展开消息的展示还原工具。
+ *
+ * 背景：SDK (pi-coding-agent) 在 prompt() 入口把 /skill:name args 与 /模板名 args
+ * 展开为完整文本（skill 正文 / 模板正文 + 参数替换）写入 session JSONL，
+ * pi-web 界面因此会看到大段展开文本。本模块把这些展开文本还原为紧凑的
+ * 命令调用形式（如 `/skill:hello 123132`），供界面展示与交互使用。
+ *
+ * 约束：不修改 SDK、不修改 JSONL 存储 —— 模型输入与存储层保持展开文本，
+ * 本模块仅作用于 pi-web 的展示层。
+ */
+
+/** SDK _expandSkillCommand 展开文本的特征前缀（skill 名称与路径为必选属性） */
+const SKILL_OPEN_RE = /^<skill name="([^"]+)" location="([^"]+)">/;
+
+/** SDK 展开时 skill 闭合标签，其后紧跟 `\n\n` 与参数（如有） */
+const SKILL_CLOSE_TAG = "\n</skill>";
+
+/**
+ * 解析斜杠命令名。
+ * `/hello 123` → "hello"，`/skill:review src/main.go` → "skill:review"，
+ * 非 `/` 开头的文本返回 null（`!` bash 命令同样不匹配）。
+ */
+export function parseSlashCommandName(text: string): string | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/")) return null;
+  const rest = trimmed.slice(1);
+  if (!rest) return null;
+  const spaceIdx = rest.search(/\s/);
+  return spaceIdx === -1 ? rest : rest.slice(0, spaceIdx);
+}
+
+/**
+ * 将 skill 展开文本还原为命令形式 `/skill:name args`。
+ * 展开格式（对齐 SDK _expandSkillCommand）：
+ *   <skill name="..." location="...">\nReferences are relative to ...\n\n<body>\n</skill>
+ *   可选后缀 `\n\n<args>`
+ * 非 skill 展开文本返回 null。
+ */
+export function skillExpansionToCommand(text: string): string | null {
+  const open = text.match(SKILL_OPEN_RE);
+  if (!open) return null;
+  const name = open[1];
+  const closeIdx = text.indexOf(SKILL_CLOSE_TAG);
+  let args = "";
+  if (closeIdx !== -1) {
+    const rest = text.slice(closeIdx + SKILL_CLOSE_TAG.length);
+    if (rest.startsWith("\n\n")) args = rest.slice(2).trim();
+  }
+  return args ? `/skill:${name} ${args}` : `/skill:${name}`;
+}
+
+/**
+ * 提取 user 消息的纯文本（兼容 string 与 blocks 两种 content 形式）。
+ * 多块文本以 \n 拼接，与 MessageView 的现有拼接逻辑一致。
+ */
+export function userMessagePlainText(content: string | Array<{ type: string; text?: string }>): string {
+  if (typeof content === "string") return content;
+  // 与 MessageView 的拼接逻辑一致：过滤非文本块后以 \n 拼接
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text ?? "")
+    .join("\n");
+}
+
+/**
+ * 尝试把一条 user 消息文本还原为紧凑命令展示。
+ * - 未展开的命令（原文以 / 开头）→ 原样返回
+ * - skill 展开文本 → 还原为 /skill:name args
+ * - 其他（普通文本、prompt 模板展开 —— 无特征标记）→ null，保持全文展示
+ */
+export function resolveSlashDisplayText(text: string): string | null {
+  if (!text || !text.trim()) return null;
+  if (text.trim().startsWith("/")) return text;
+  return skillExpansionToCommand(text);
+}
+
+/**
+ * FIFO 跟踪器：记录已发送的、确定会被 SDK 展开的斜杠命令原文，
+ * 待对应 user 消息回传（message_end）时按发送顺序消费并注入。
+ * 仅当命令命中 prompt 模板或 skill 时才 push（见 rpc-manager send()），
+ * 因此栈内记录必定展开，回传文本与原文不同。
+ */
+export class SlashOriginalTracker {
+  private queue: string[] = [];
+
+  push(original: string): void {
+    this.queue.push(original);
+  }
+
+  get size(): number {
+    return this.queue.length;
+  }
+
+  /** 清空队列（prompt 发送失败等场景，避免残留记录错注入后续消息） */
+  clear(): void {
+    this.queue.length = 0;
+  }
+
+  /**
+   * 为回传的 user 消息消费一条记录。
+   * 返回应注入的原始命令；栈空或回传文本与栈顶原文相同（未展开的防御分支）
+   * 时返回 null。
+   */
+  consumeFor(text: string): string | null {
+    if (this.queue.length === 0) return null;
+    const top = this.queue.shift()!;
+    return top === text ? null : top;
+  }
+}
diff --git a/lib/types.ts b/lib/types.ts
index 65d8a80b0..182405876 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -51,6 +51,12 @@ export interface UserMessage {
   role: "user";
   content: string | (TextContent | ImageContent)[];
   timestamp?: number;
+  /**
+   * 斜杠命令的原始调用文本（如 `/skill:review src/main.go`）。
+   * 仅 pi-web 展示层传输字段：SDK 把展开后的完整文本写入 session JSONL，
+   * rpc-manager / session-reader 在回传与读取时注入此字段，不落盘。
+   */
+  originalText?: string;
 }
 
 export interface AssistantMessage {