interactive-shell

交互式 Shell（技能）

上次验证时间：2026-01-18

前台与后台子 Agent

Pi 有两种方式可以将工作委派给其他 AI 编码 Agent：

	前台子 Agent	派发子 Agent	后台子 Agent
工具	interactive_shell	interactive_shell（派发）	subagent
可见性	用户可看到叠加层	用户可看到叠加层（或无界面）	用户不可见
Agent 模型	轮询状态	完成时通知	捕获完整输出
默认 Agent	pi（用户要求时可用其他 Agent）	pi（用户要求时可用其他 Agent）	仅限 Pi
用户控制	用户可随时接管	用户可随时接管	无法干预
适用场景	需要监督的长任务	即发即忘式委派	并行任务、结构化委派

前台子 Agent 在叠加层中运行，用户可以观察并进行干预。使用 interactive_shell，并设置 mode: "hands-free"，即可在接收定期更新的同时进行监控；也可以设置 mode: "dispatch"，无需轮询，等候完成通知。

派发子 Agent 也使用 interactive_shell，但设置 mode: "dispatch"。Agent 启动会话后继续执行其他工作。会话完成时，系统会通过 triggerTurn 唤醒 Agent，并将输出放入上下文中。添加 background: true 即可无界面执行（不显示叠加层）。

后台子 Agent 通过 subagent 工具隐式运行。仅限 Pi，但会捕获完整输出，并支持并行执行。

何时使用前台子 Agent

以下情况使用 interactive_shell（前台）：

• 任务运行时间较长，用户应能看到进度
• 用户可能想要干预或指导 Agent
• 你希望进行免操作监控，并接收定期状态更新
• 你需要另一种 Agent 的能力（仅限用户指定时）

以下情况使用 subagent（后台）：

• 你需要并行执行多个任务
• 你希望捕获完整输出以便处理
• 任务快速且确定
• 用户不需要查看执行过程

默认 Agent 选择

除非用户明确要求使用其他 Agent，否则前台子 Agent 默认使用 pi：

用户的说法	使用的 Agent
“以免操作模式运行”	pi
“委派这个任务”	pi
“用 Claude 检查这个”	claude
“让 Gemini 分析这个”	gemini
“运行 aider 来修复这个”	aider

Pi 是默认选择，因为它已可用，具备相同的能力，并能保持一致性。只有在用户明确要求时才使用 Claude、Gemini、Codex 或其他 Agent。

前台子 Agent 模式

交互式（默认）

用户拥有完全控制权，可直接向 Agent 输入内容。

interactive_shell({ command: 'pi' })

带初始提示词的交互式模式

Agent 立即开始工作，用户负责监督。

interactive_shell({ command: 'pi "Review this codebase for security issues"' })

派发（即发即忘）- 非阻塞，无需轮询

Agent 启动会话后继续执行其他工作。完成时会通过 triggerTurn 自动通知。

// Start session - returns immediately, no polling needed
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "dispatch",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", mode: "dispatch" }
// → Do other work. When session completes, you receive notification with output.

派发模式默认设置 autoExitOnQuiet: true。如有需要，Agent 仍可查询 sessionId，但并非必须。

后台派发（无界面）

不会打开叠加层。多个无界面派发可以并行运行：

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true
})
// → No overlay. User can /attach to watch. Agent notified on completion.

免操作模式（前台子 Agent）- 非阻塞

Agent 自主工作，立即返回 sessionId。你可以查询状态和输出，并在完成后终止任务。

// 1. Start session - returns immediately
interactive_shell({
  command: 'pi "Fix all TypeScript errors in src/"',
  mode: "hands-free",
  reason: "Fixing TS errors"
})
// Returns: { sessionId: "calm-reef", status: "running" }

// 2. Check status and get new output
interactive_shell({ sessionId: "calm-reef" })
// Returns: { status: "running", output: "...", runtime: 30000 }

// 3. When you see task is complete, kill session
interactive_shell({ sessionId: "calm-reef", kill: true })
// Returns: { status: "killed", output: "final output..." }

这是前台子 Agent的主要模式——你将任务委派给 pi（或其他 Agent），查询进度，并决定何时任务完成。

免操作工作流

启动会话

const result = interactive_shell({
  command: 'codex "Review this codebase"',
  mode: "hands-free"
})
// result.details.sessionId = "calm-reef"
// result.details.status = "running"

用户会立即看到叠加层。你可以继续工作。

查询状态

interactive_shell({ sessionId: "calm-reef" })

返回：

• status："running" | "user-takeover" | "exited" | "killed" | "backgrounded"
• output：渲染后终端的最后 20 行（干净，不含 TUI 动画噪声）
• runtime：已用时间，单位为毫秒

速率限制： 查询频率限制为每 60 秒一次。如果查询间隔过短，工具会自动等待限制解除后再返回。用户会实时查看叠加层，你只需定期检查即可。

结束会话

interactive_shell({ sessionId: "calm-reef", kill: true })

在输出中看到任务已完成时将其终止。返回最终状态和输出。

即发即弃任务

对于无需多轮交互的单任务委派，启用自动退出，让会话在 Agent 停止活动时自动终止：

interactive_shell({
  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
  mode: "hands-free",
  reason: "Security review",
  handsFree: { autoExitOnQuiet: true }
})
// Session auto-kills after ~5s of quiet
// Read results from file:
// read("/tmp/security-review.md")

指示子 Agent 将结果保存到文件，因为会话会自动关闭。

多轮会话（默认）

对于需要来回交互的任务，保持自动退出关闭（默认设置）。完成后查询状态并手动终止：

interactive_shell({
  command: 'cursor-agent -f',
  mode: "hands-free",
  reason: "Interactive refactoring"
})

// Send follow-up prompts
interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })

// Kill when done
interactive_shell({ sessionId: "calm-reef", kill: true })

发送输入

interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // combine text + keys

查询输出

状态查询返回的是渲染后的终端输出（屏幕上实际显示的内容），而非原始数据流：

• 默认：每次查询最多 20 行、5KB
• 不含 TUI 动画噪声（加载指示器、进度条等）
• 可通过 outputLines（最大值：200）和 outputMaxChars（最大值：50KB）进行配置

// Get more output when reviewing a session
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

增量读取

使用 incremental: true 分页查看输出，避免重复读取：

// First call: get first 50 lines
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Next call: get next 50 lines (server tracks position)
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: true }

// Keep calling until hasMore: false
interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
// → { output: "...", hasMore: false }

服务会跟踪你的读取位置，只需继续使用 incremental: true 调用，即可获取下一段内容。

查看输出

查询会话以查看进度。需要更多上下文时，可提高限制：

// Default: last 20 lines
interactive_shell({ sessionId: "calm-reef" })

// Get more lines when you need more context
interactive_shell({ sessionId: "calm-reef", outputLines: 50 })

// Get even more for detailed review
interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })

向活动会话发送输入

使用更新中的 sessionId 向正在运行的免手动操作会话发送输入：

基本输入

// Send text
interactive_shell({ sessionId: "shell-1", input: "/help\n" })

// Send text with keys
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Navigate menus
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })

// Interrupt
interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })

命名按键

按键	说明
up, down, left, right	方向键
enter, return	Enter/Return 键
escape, esc	Escape 键
tab, shift+tab（或 btab）	Tab / 反向 Tab
backspace, bspace	Backspace 键
delete, del, dc	Delete 键
insert, ic	Insert 键
home, end	Home/End 键
pageup, pgup, ppage	Page Up 键
pagedown, pgdn, npage	Page Down 键
f1-f12	功能键
kp0-kp9, kp/, kp*, kp-, kp+, kp., kpenter	小键盘按键
ctrl+c, ctrl+d, ctrl+z	Control 组合键
ctrl+a 至 ctrl+z	所有 Control 组合键

注意：ic/dc、ppage/npage、bspace 是 tmux 风格的别名，用于兼容。

修饰键组合

支持 ctrl+、alt+、shift+ 前缀（或简写 c-、m-、s-）：

// Cancel
inputKeys: ["ctrl+c"]

// Alt+Tab
inputKeys: ["alt+tab"]

// Ctrl+Alt+Delete
inputKeys: ["ctrl+alt+delete"]

// Shorthand syntax
inputKeys: ["c-c", "m-x", "s-tab"]

十六进制字节（高级）

发送原始转义序列：

inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)

带括号的粘贴

粘贴多行文本，不触发自动补全或执行：

inputPaste: "function foo() {\n  return 42;\n}"

模型选择示例

// Step 1: Open model selector
interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })

// Step 2: Filter and select (after ~500ms delay)
interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })

// Or navigate with arrows:
interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })

上下文压缩

interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })

更改更新设置

在会话期间调整时间设置：

// Change max interval (fallback for on-quiet mode)
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 120000 } })

// Change quiet threshold (how long to wait after output stops)
interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })

// Both at once
interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })

CLI 快速参考

Agent	交互模式	带提示词	无头模式（bash）	分派
claude	claude	claude "prompt"	claude -p "prompt"	mode: "dispatch"
gemini	gemini	gemini -i "prompt"	gemini "prompt"	mode: "dispatch"
codex	codex	codex "prompt"	codex exec "prompt"	mode: "dispatch"
agent	agent	agent "prompt"	agent -p "prompt"	mode: "dispatch"
pi	pi	pi "prompt"	pi -p "prompt"	mode: "dispatch"

Gemini 模型： gemini -m gemini-3-flash-preview -i "prompt"

提示词封装规则

reason 参数仅用于 UI——它会显示在叠加层标题中，但不会传递给子进程。

若要向 Agent 提供初始提示词，请将其嵌入 command 中：

// WRONG - agent starts idle, reason is just UI text
interactive_shell({ command: 'claude', reason: 'Review the codebase' })

// RIGHT - agent receives the prompt
interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code review' })

交接选项

传输（Ctrl+T）- 推荐

子 Agent 完成后，用户按下 Ctrl+T，即可将输出直接传给你：

[Subagent finishes work in overlay]
        ↓
[User presses Ctrl+T]
        ↓
[You receive: "Session output transferred (150 lines):
  
  Completing skill integration...
  Modified files:
  - skills.ts
  - agents/types/..."]

这是最简洁的工作流——子 Agent 的响应会自动成为你的上下文。

配置： transferLines（默认值：200）、transferMaxChars（默认值：20KB）

尾部预览（默认）

工具结果中包含最后 30 行。适合查看错误或最终状态。

保存快照到文件

将完整记录写入 ~/.pi/agent/cache/interactive-shell/snapshot-*.log：

interactive_shell({
  command: 'claude "Fix bugs"',
  handoffSnapshot: { enabled: true, lines: 200 }
})

交接产物（适用于复杂任务）

指示受委派的 Agent 编写交接文件：

Write your findings to .pi/delegation/claude-handoff.md including:
- What you did
- Files changed
- Any errors
- Next steps for the main agent

安全捕获 TUI 输出

切勿通过 bash 运行 TUI Agent——即使使用 --help，它们也会卡住。请改用带有 timeout 的 interactive_shell：

interactive_shell({
  command: "pi --help",
  mode: "hands-free",
  timeout: 5000  // Auto-kill after 5 seconds
})

进程会在超时后终止，捕获的输出会在交接预览中返回。以下情况适用：

• 获取 TUI 应用的 CLI 帮助信息
• 捕获无法正常退出的命令的输出
• 任何需要快速输出、无需用户交互的 TUI 命令

对于 pi CLI 文档，也可以直接阅读：/opt/homebrew/lib/node_modules/@mariozechner/pi-coding-agent/README.md

后台会话管理

// Background an active session (close overlay, keep running)
interactive_shell({ sessionId: "calm-reef", background: true })

// List all background sessions
interactive_shell({ listBackground: true })

// Reattach to a background session
interactive_shell({ attach: "calm-reef" })                    // interactive (blocking)
interactive_shell({ attach: "calm-reef", mode: "hands-free" })  // hands-free (poll)
interactive_shell({ attach: "calm-reef", mode: "dispatch" })    // dispatch (notified)

// Dismiss background sessions (kill running, remove exited)
interactive_shell({ dismissBackground: true })               // all
interactive_shell({ dismissBackground: "calm-reef" })        // specific

快速参考

调度子 Agent（即发即弃，默认使用 pi）：

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "dispatch",
  reason: "Implementing feature"
})
// Returns immediately. You'll be notified when done.

后台调度（无头模式，无覆盖层）：

interactive_shell({
  command: 'pi "Fix lint errors"',
  mode: "dispatch",
  background: true,
  reason: "Fixing lint"
})

启动前台子 Agent（免操作，默认使用 pi）：

interactive_shell({
  command: 'pi "Implement the feature described in SPEC.md"',
  mode: "hands-free",
  reason: "Implementing feature"
})
// Returns sessionId in updates, e.g., "shell-1"

向活动会话发送输入：

// Text with enter
interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })

// Text + named keys
interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })

// Menu navigation
interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })

更改更新频率：

interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 60000 } })

前台子 Agent（用户要求使用其他 Agent）：

interactive_shell({
  command: 'claude "Review this code for security issues"',
  mode: "hands-free",
  reason: "Security review with Claude"
})

后台子 Agent：

subagent({ agent: "scout", task: "Find all TODO comments" })