检查 MCP 到 pi-web 的连接配置是否正常：地址、密码来源、会话总数、运行中的会话、读写边界（是否只读、允许写入的项目根）。连不上时先用这个排查。

列出/筛选 pi-web 里的 pi 会话（按项目目录、关键词、状态、时间过滤）。status: all|running|awaiting|unread，unread 用的是本 MCP 自己的已读游标（与浏览器里的未读标记不共享）。keyword 只匹配会话名称/首条消息/目录，全文检索用 piweb_search_sessions，想要「哪些会话在等我」用 piweb_triage。

按项目目录聚合 pi-web 会话：每个目录有多少会话、几个在跑、几个未读、最近活动时间。用来先看「我的活儿都压在哪个目录」。

一次列出需要我关注的会话：🟠 正在等待用户输入的、🔵 本 MCP 上次读过之后又有新内容的、🟢 正在跑但我没看过的。注意：未读用的是本 MCP 的已读游标（用 piweb_get_session 或 piweb_mark_read 更新），与浏览器 localStorage 里的未读标记是两套。想按「对话结局」判断谁在等我，用 piweb_triage。

不经过模型，纯按「最后一条消息是谁 + 是否有悬挂的工具调用 + 多久没动」把会话分诊成：🟠等我回答（扩展弹窗）、❓可能在问我（最后一条助手消息带问号）、⚠️半途停下（最后一轮没有助手收尾）、💤停滞（半途停下且很久没动）、🟢在跑、💬等我下一步。每条都给判定依据，可复现、可核查。这是回答「现在还有多少对话在等我」最快的一招。默认只看最近 3 天有过活动的会话。

在所有会话的消息正文里做字面量（不区分大小写）搜索，返回命中片段所在的会话 id。服务端有 3 秒时间预算，结果可能被截断（truncated）；命中很多时缩小关键词或用 piweb_get_session 细看。

读取一个会话的对话内容（默认最后 30 条消息，含工具调用摘要）。session 可传完整 id、id 前缀、会话名称或名称/首条消息片段。要读更早的历史用 offset 往前翻；思考内容默认只给预览，include_thinking="full" 会去取完整思考链。默认会把该会话在本地标记为已读。

不带 session 时给全局快照（哪些会话在跑/等待输入）；带 session 时给该会话的详细状态（是否流式中、上下文占用、模型、排队消息）。

列出某个项目目录下 pi 可用的模型（provider/model 形式）与默认模型、可用思考等级。新建会话或切模型前拿它选值。

列出某个项目目录下的文件（优先 git ls-files，跳过 .gitignore）。可带 filter 做模糊匹配。用来定位某个项目里有哪些文件可读。

读一个文本文件的片段（服务端按块返回，默认一块；用 offset=nextOffset 继续读下一块）。只读文本类文件，二进制会被拒。

看某个项目目录的 git 状态：分支仓库根、改了哪些文件（状态码）、增删行数。用来验收 agent 到底动了什么。

看某个文件相对 git 的完整 patch。复制到会话里让 agent 改，或用来核查它的改动是否合理。

订阅会话的事件流，在指定秒数内收集正在生成的内容（文本增量、思考增量、工具调用），返回期间累计的文本。适合「它现在跑到哪了」。注意：会话没在运行时订阅会把它拉起成一个空闲进程（等同在 pi-web 打开该会话）。

向一个已有会话发送提示词（等价于在 pi-web 输入框里发消息），让它继续干活。会话没在运行时 pi-web 会自动把它拉起来。默认发完就返回；wait_seconds>0 时会等这一轮跑完并带回最后的助手回复。注意：这会让对方 agent 真正执行操作（改文件、跑命令），发之前确认会话选对了。

轮询某个会话，等它这一轮跑完（不再流式输出），然后返回最后的助手回复文本。适合先 piweb_send_message 不等、之后再来收结果。

在指定项目目录下新建一个 pi 会话（返回真实 sessionId）。带 message 时把它作为首条提示词发出去；不带 message 时只创建运行时（ensure_session）。可选指定 provider/modelId/thinking_level，模型取值用 piweb_list_models 查。

给正在运行的会话发 abort，停掉它当前这一轮（等价于界面上的 Stop）。

把会话当前分支整体复制成一个新会话（等价于侧边栏的 Fork）。原会话不受影响。用来「从这条线另开一条道」。

调用 pi 的标题生成，让模型根据对话内容给会话起一个名字并落盘（等价于侧边栏的自动命名）。要花一次模型调用。

切换某个会话接下来使用的模型（等价于界面上的模型选择）。会话没在运行时会被拉起来。取值先用 piweb_list_models 查。

更新本 MCP 的已读游标：session 给了就标记该会话，省略则把当前所有未读会话一次性标记为已读；unread=true 则反过来清掉游标，让它重新算未读。只影响本 MCP 的游标，不碰浏览器里的未读标记。

给会话改名字（等价于 pi-web 侧边栏的重命名）。

把会话导出成 pi 官方单文件 HTML（可离线翻阅/分享），写到本地磁盘并返回路径。大会话导出要几秒。

删除会话（会连同它下面的子代理会话一起删掉，不可恢复）。必须显式传 confirm=true 才会执行。