会话与工作区

本页说明 pi-webapp 如何按项目组织会话、如何添加和移除项目，以及切换、刷新和重启之后什么会保留。

两个概念

工作区不是权限边界。代理和终端能访问你的用户账号能访问的一切，见安全与隐私。

新会话会以你的第一条消息命名。在你发送消息之前，它显示 新会话。新会话 会复用工作区里还没动过的那个会话，而不是再建一个；里面什么都没有的会话只在打开时才会列出。

会话互相独立。切换到别的会话、工作区或页面，不会让正在工作的会话停下来：回来时，它的输出、历史和正在等待的交互都还在。

每个会话行都有一个 … 按钮（会话操作，无障碍名称是“<会话名> 的会话操作”），里面有两项。

重命名 会打开 重命名会话 对话框。输入最多 120 个字符的名字，点保存。留空则恢复为用第一条消息作标题。名字保存在 Pi 自己的会话文件里，所以 Pi 终端里看到的也是它。
删除会话 会打开 删除会话？。点删除，这个会话就从列表里消失。它的文件是被移动而不是被抹掉的，会放到 Pi 数据目录的 pi-web/trash/ 下，你可以把文件移回 sessions/ 下原来的位置来恢复。你的项目文件不受影响。

仍在运行的会话不能删除：对话框会提示你等当前回复结束。在 Pi 终端里打开着的会话（/web 模式）也不能从浏览器里删除，请先在终端里切换到别的会话。如果你删除的是正在看的会话，会在原处打开一个全新的会话。

服务启动时，会加入你启动它时所在的目录，也会收入所有有已保存 Pi 会话的目录，包括你之前在 Pi 终端里开始的会话。

要添加另一个项目，点击 工作区 旁边的文件夹图标（添加工作区）：

你在哪里运行 pi-webapp	会打开什么
macOS	系统的文件夹选择器
有桌面环境，并且装了 `zenity` 或 `kdialog` 的 Linux	系统的文件夹选择器
Windows、SSH 会话，或没有桌面的机器	pi-webapp 自带的文件夹浏览器，它还可以新建文件夹

要移除一个工作区，打开它名称旁边的 工作区操作，选择 从列表移除工作区。当前工作区不能移除，菜单会提示 请先切换到其他工作区再移除。

移除工作区只是把它隐藏。它不会删除文件或会话。 重新添加这个文件夹就能让它回来。

在别的目录里运行 npx pi-webapp 不会添加那个目录

如果服务已经在运行，这条命令只会打印并重新打开已有地址。请使用 添加工作区。

操作	结果
切换会话或工作区，或新建会话	其他会话继续运行。
关闭浏览器标签页	服务和所有会话继续运行。
刷新页面	后端不受影响。已打开的工具标签页（文件、终端、Git）会重置回开始状态。
暂停执行一个会话	只暂停那一个会话（对话）。
停止或重启服务	正在运行的会话和所有终端都会结束。已保存的历史仍在，但原来在运行的任务不会被恢复。

Pi 把每个会话存成 JSON Lines 文件，放在它的数据目录下，按工作区路径分组：

text

~/.pi/agent/sessions/--Users-you-projects-my-app--/2026-11-01T10-28-05-873Z_01a196a6-f271-75c0-8cb5-7a0839f57917.jsonl

目录名是工作区路径，其中的 / 换成了 -。在侧栏里删除会话（见上文）会把它的文件移到 pi-web/trash/；你也可以在服务停止时自己管理这些文件。千万不要为了修好侧栏而删掉整个 ~/.pi 目录：那里还有你的凭据和设置（文件与目录）。

同一工作区里的会话共用一个工作树。两个会话可以编辑同一批文件，Git 面板显示的也是所有改动，而不只是某一个会话的。提交或切换分支之前，请确认相关会话都已空闲（文件、终端与 Git）。

在不是启动服务时所在目录的工作区里，会话通过 Pi 的 SDK 运行，使用该工作区自己的技能和项目上下文。你为终端安装的扩展不一定每个会话都会加载。