AI 终端：会话、Shell 与恢复

Kiln 终端的 Shell 集成、活动上报、命令历史、补全、连接恢复和后台会话。

每个 Kiln 任务都运行在真实的终端会话中，会话由本地守护进程托管。Shell 集成在此之上提供命令跟踪、活动上报和补全；关闭窗口后，会话照常运行。

Shell 集成

新建的默认 zsh 会话会自动启用 Shell 集成。它会跟踪命令边界和工作目录，不会修改你的 .zshrc。

带参数的自定义启动方式不会自动集成，bash 和 fish 也不会。已经打开的 Shell 可能要新建会话，才能用上新的集成行为。要关闭集成，设置 KILN_SHELL_INTEGRATION=0。

为现有 zsh 会话启用集成

1. 在设置中把默认 Shell 设为 /bin/zsh，然后打开一个新的 Kiln 终端。这一步会生成集成文件。
2. 在现有的 zsh 中，等前台任务结束，然后在空闲的提示符下运行：

source ~/.local/share/kiln/shell-integration-v1/integration.zsh

在现有终端里直接启动 zsh，并不会执行 Kiln 的新会话设置。

活动与通知

Kiln 会读取终端通知（OSC 转义序列）和显式的活动上报。两者都是本地终端转义序列，不会把你的提示词发送给其他服务。

在脚本或代理钩子中用 kiln activity 上报活动：

kiln activity running
kiln activity waiting
kiln activity done
kiln activity failed

用 kiln notify 发送通知。运行 kiln activity --help 和 kiln notify --help 查看当前安装版本的语法。Shell 集成还提供 kiln-agent-status running|waiting|done|failed|unknown 函数。钩子的输出必须送达 Kiln 终端，Kiln 才能收到活动。

Claude Code 和 Codex 会在终端标题中写入活动标记，Kiln 能识别这些标记，因此不配置任何钩子也能显示运行中的活动。显式上报的等待和失败状态优先。什么都不上报的普通 Shell 和代理显示为打开的会话，不会被标为已完成。指示器和颜色见代理。

通知中心保留最近的通知，每条通知都关联到对应的会话。读过通知后，该会话的待处理状态随即清除。

命令历史

守护进程在内存中保存最近执行的命令，方便你回看命令及其输出。

历史是根据每条命令的输出重建的文本视图，不是原始终端日志，也不会记录全屏 TUI 的每一帧中间画面。没有命令边界集成时，只能查看当前可见的输出。

编辑历史中的命令后，只有明确选择运行操作它才会执行，而且会在新终端中运行。

Shell 补全

在新打开且已集成的 zsh 终端中，Kiln 会在你输入时提示 cd 路径，以及 Git、Docker、npm 和 Cargo 的常用子命令。

插入建议永远不会执行命令。菜单关闭时，zsh 自带的 Tab 补全照常可用。

要隐藏自动建议，在终端设置中关闭“命令输入提示”，Ctrl+Space 仍然可用。在 Shell 中设置 KILN_COMPLETION_PREVIEW=0，Shell 也会停止生成预览数据。

补全不会读取 Shell 历史文件，不会为了生成帮助而运行命令，也不会向云服务发送任何内容。

补全只支持 zsh。Bash、fish、SSH 会话、代理对话、全屏应用和其他 Shell 的输入方式保持不变。集成的帮助位于终端的右键菜单中。

连接恢复

Kiln 把终端连接和其中运行的 Shell 或代理分开管理。面板断开连接或停止响应时，Kiln 会修复连接、重绘屏幕，并让 CLI 重绘。它不会替你重启代理、发送提示词或运行 /resume。

每个运行中的终端面板的 … 菜单里也有重新连接，即使连接看起来正常也能使用，并会重置该面板的重试次数。代理在思考或等待输入时没有输出，不会被视为停滞。

恢复期间，会话和进程继续运行，屏幕上的现有文本也会保留。输入会暂停，键入的内容不会堆积在断开的连接后面。

注意 有时连接正常，CLI 却在内部卡住了。重新连接解决不了这种情况，请另开一个面板，使用该 CLI 自己的恢复流程。

关闭窗口后保留的会话

终端属于会话守护进程，而不是窗口。关闭 Kiln 后，其中的 Shell 和代理继续运行，重新打开即可回到它们。更新时，正在运行的终端也会保留。系统重启或手动停止守护进程可能会结束会话。

• macOS：点击菜单栏图标会打开菜单，其中有设置… 和结束后台会话…。结束后台会话前，Kiln 会列出仍在运行的会话并请求确认，默认选项是取消。列表也包括已打开工作区中的会话，因此 Shell 或代理中未保存的工作可能会丢失。
• Windows：通知区域图标显示会话摘要；有需要处理的事项或未读通知时会出现红点。图标菜单包含打开 Kiln、设置和结束后台会话…。

警告 kiln status 显示会话守护进程的状态。不要用 shutdown-daemon 来刷新窗口，它会结束你的会话。

macOS 上的本地网络访问

macOS 15 及更高版本要求获得授权才能连接本地网络。服务器位于本地网络时，kubectl get nodes、SSH、数据库连接和远程文件等终端命令都可能受影响。

1. 打开 Kiln → 设置 → 行为。
2. 在隐私 → 本地网络下，选择请求访问。
3. 如果 macOS 弹出提示，允许 Kiln，然后重试命令。

齿轮按钮会打开系统设置 → 隐私与安全性，可以在本地网络下查看 Kiln。Kiln 无法读取或更改系统的授权结果；如果之前已经做过选择，macOS 可能不会再次弹出提示。

提示 更新前打开的面板沿用旧的进程设置。如果访问本地网络的命令在这类面板中失败，请新开一个终端面板再试。

Windows Shell

装有 PowerShell 7 时，终端以 PowerShell 7 启动，否则使用 Windows PowerShell。也可以在设置 → 终端中选择 cmd.exe、Git Bash 或某个 WSL 发行版。

• PowerShell 和 cmd 会向 Kiln 上报命令、退出码和当前位置。自定义提示符仍能拿到上一条命令的状态。
• PowerShell 保留 PSReadLine 的补全（Tab、Ctrl+Space）。Kiln 的补全菜单只适用于 zsh。
• 关闭终端会结束其中的控制台程序，由它启动的窗口应用（例如浏览器）会继续运行。
• 面板以 Shell 中最新运行的控制台程序命名。从 Git Bash 启动的程序不会被跟踪。
• 韩语输入法在终端和编辑器中都能正常使用。