Pi Taskbar Status

在 Windows 任务栏通知区域显示 Pi Agent 的实时状态。

本项目采用 Pi Extension + Windhawk XAML 模组：

Pi Extension
    ↓ newline-delimited JSON over TCP
127.0.0.1:19288
    ↓
Windhawk module in explorer.exe
    ↓
Windows taskbar SystemTrayFrameGrid

不再使用 WPF/.NET 宿主，因此发布包只包含源码和脚本，不携带约 67MB 的自包含运行时。

功能

• 显示等待输入、思考、回复、工具执行、压缩、错误状态
• 支持多个 Pi 进程
• 工具执行状态显示工具名称
• 读取 todo/todowrite/plan 工具的任务列表，显示已完成/总任务数；没有结构化任务时显示已执行工具数
• 识别 pi-subagents 子进程，显示子任务 Agent，并在父任务上显示子任务完成统计
• Explorer 重启后自动重新注入任务栏
• Windhawk 设置中可选择主显示器、DISPLAY1/2/3 的任务栏
• Windhawk 设置中可调整通知区左侧、任务栏左侧或任务栏居中位置
• Windhawk 设置中可调整单行/双行、每个任务固定宽度、字体和颜色
• 固定宽度下，超长单行/双行文字可自动横向滚动，也可关闭滚动改用省略号
• Pi 未启动 Windhawk 时不会影响正常使用

安装

1. 安装 Windhawk 模组

1. 安装并启动 Windhawk。
2. 创建一个本地 Mod。
3. 将 windhawk/pi-taskbar-status.wh.cpp 全部复制到编辑器。
4. 保存并编译。
5. 确认 Mod 已对 explorer.exe 启用。

该模块直接操作 Windows 任务栏的 XAML Visual Tree，依赖 Windows 任务栏的私有符号；Windows 更新后如果注入失败，需要等待适配。

在 Windhawk 的设置中可以选择目标显示器：

• 主显示器：跟随 Windows 当前主显示器；
• 显示器 1/2/3：选择对应的 \\.\DISPLAY1/2/3 任务栏；

如果目标显示器没有启用独立任务栏，控件不会回退到其他显示器。

同时可以选择控件位置：

• 通知区域左侧（默认）：不覆盖任务栏应用图标，最稳定；
• 任务栏左侧：覆盖在任务栏左侧内容上方；
• 任务栏居中：覆盖在任务栏内容中心上方。

左侧/居中模式属于 XAML 覆盖层，可能遮挡开始菜单、搜索或应用图标；建议先使用默认的通知区域左侧模式。

2. 安装 Pi Extension

在项目根目录运行：

pwsh .\scripts\install-extension.ps1

默认安装到：

%USERPROFILE%\.pi\agent\extensions\pi-taskbar-status.ts

完全退出并重新启动 Pi。

也可以仅对当前进程临时加载：

pi --extension C:\Evans\Project\pi-taskbar-status\pi-extension\pi-taskbar-status.ts

3. 启动顺序

建议先启用 Windhawk Mod，再启动 Pi。Windhawk 模组默认监听：

127.0.0.1:19288

Pi Extension 使用相同端口。如需修改，Windhawk 设置和环境变量必须一致：

$env:PI_TASKBAR_STATUS_PORT = "19289"

手工测试

启用 Windhawk Mod 后，在源码目录执行：

pwsh .\scripts\send-test-status.ps1 -State thinking -Text "思考中"
pwsh .\scripts\send-test-status.ps1 -State tool -Text "执行 bash" -ToolName bash
pwsh .\scripts\send-test-status.ps1 -State idle -Text "等待输入"

可用下面的长文本测试固定宽度和横向滚动：

pwsh .\scripts\send-test-status.ps1 -State tool -Text "执行一个很长的命令：检查项目依赖、构建输出、测试日志以及任务进度" -ToolName "very-long-tool-name"

默认每个任务卡片宽度为 430 逻辑像素；可在 Windhawk 设置中调整“单任务固定宽度”、滚动速度和停顿时间。

测试脚本会保持进程存活 15 秒，避免 Windhawk 将测试进程误判为已退出。若能看到任务栏文字和状态颜色变化，说明 TCP 与任务栏显示链路正常。

状态映射

Pi 事件	任务栏状态
agent_start	思考中
message_update thinking	思考中
message_update text	回复中
tool_execution_start	执行工具
tool_execution_update	工具执行中
session_before_compact	压缩上下文
session_compact	继续处理
tool_execution_end error	工具执行失败
agent_settled	等待输入
session_shutdown	移除实例

子任务识别

如果安装了 pi-subagents，父 Pi 调用 subagent 时会显示：

子任务 reviewer

子 Pi 进程会读取 PI_SUBAGENT_CHILD、PI_SUBAGENT_CHILD_AGENT、 PI_SUBAGENT_RUN_ID、PI_SUBAGENT_PARENT_RUN_ID，并使用 agent_settled 发布的完成标记，任务栏会将其标记为：

[子任务 reviewer] Pi  项目名  思考中

父任务如果能匹配子任务的 Run ID 或进程 ID，第二行会增加：

子任务 1/2

其中分子表示收到 agent_settled 的子任务数量，分母表示已发现的子任务数量；刚启动时的初始 idle 不会被计为完成。子任务是独立 Pi 实例，默认会以独立任务栏按钮显示；如果子进程显式禁用了该 Extension，则只能看到父任务的 subagent 调用，无法获取子任务实时状态。

开发与测试

检查 Extension 语法：

node --check .\pi-extension\pi-taskbar-status.ts

运行 TCP 协议测试：

node --experimental-strip-types .\scripts\test-extension.mjs

卸载

pwsh .\scripts\install-extension.ps1 -Uninstall

然后在 Windhawk 中禁用或删除 Pi Taskbar Status Mod。

许可

Pi-specific code is maintained in this repository. The taskbar injection code is adapted from the MIT-licensed OpenCode Taskbar Status. See THIRD_PARTY_NOTICES.md.