Pi Chat

Windows-first、local-first 的 Pi RPC 客户端。

不重写 Agent loop，不引入第二套 Runtime，不暴露远程端口：让现有 Pi 用户获得一个可靠、可恢复、接近桌面应用体验的本地 Web/PWA 界面。

Pi Chat 连接本机 Pi RPC，负责聊天展示、Session 浏览、流式输出和本地窗口协调；Pi 仍然是 agent、模型、工具、Skills 和 Extensions 的唯一执行 authority。每个执行对话仍由独立 Node/Pi RPC 进程拥有，浏览器只通过 loopback HTTP API 与 SSE 接收事实投影。

Windows 安装（推荐使用一键 Setup）

一个完整 Setup：应用 + Node 内置，缺少 Pi 时离线安装

正式版 v0.5.4 提供完整 Setup 和便携 ZIP。三种渠道不要混用：

• Stable：从 Latest Release 下载；查看该 Release 的说明及 About 中的 Build Revision，版本与 Build Revision 应同时核对；不要把 main 的源码修复当作已安装版本的能力。
• Preview：Pre-release 是对应测试标签的安装包，不随 main 自动更新，也不成为 Latest。
• Main：源码开发版本；成功的手动 Windows CI 可提供 pi-chat-setup-main-<提交号> Artifacts（保留 30 天，下载通常需要登录 GitHub）。Actions 传输 ZIP 不是便携包，其 manifest 标记 tag: HEAD 并记录完整 revision，不创建或移动 tag。

普通 main 推送和 PR 自动运行轻量 Source Checks（类型、Lint、writer/type-debt 门禁及核心与收尾回归），不构建或发布安装包。完整验证仍在 Actions 选择 Windows CI → Run workflow；推送 v* 版本标签才自动运行完整 Release CI，通过后发布安装包。

v0.5.2 是约 192 KB 的历史在线引导安装器，不适用下面的完整 Setup 说明，旧资产保持不变。

版本 Release 提供两个产物：pi-chat-setup.exe（唯一安装入口）和 pi-chat-portable-<版本>.zip（便携包）。校验文件和构建清单只在 CI 内验证，不上传到 Release（它们不是额外安装包）。安装向导基于 Inno Setup，不依赖 Electron：

1. EXE 已内置编译好的 Pi Chat、私有 Node.js 24.22.0 LTS Runtime（含 npm），以及一份 Pi 1.3.0 后备快照。安装主体无需联网，也无需预装 Git、Node、npm 或 Pi。
2. 默认安装到 %LOCALAPPDATA%\PiChat，也可选择其他目录；安装完成及主快捷方式默认用系统默认浏览器打开 Web。桌面只放 Pi Chat Web；安装根目录自动附带 Pi Chat Web.lnk，开始菜单另保留可选的 Pi Chat PWA 入口。升级时会删除旧版桌面上的重复 Pi Chat 图标（不会动 Pi Chat Git）。
3. 启动时优先使用本机 Node 22.19+；本机没有或版本过低时改用安装包内的 Node 24.22.0，并提示原因。
4. 检测到现有 Pi 时优先直接复用，不升级它、不复制模型凭证、配置、Skills 或 JSONL。本机没有 Pi 时离线展开包内的 1.3.0 到 managed 布局（~/.pi/agent/install），失败也不撤销应用安装。
5. 完成页可启动 Pi Chat。没有模型凭证时仍需通过 Pi 完成登录或配置 Provider。

正在运行的目标安装会拒绝覆盖升级和卸载，不会强杀 Node/Pi。另一个目录的 Pi Chat 服务也不会被接管；如占用了 30170，请在原窗口安全关闭服务后再启动新安装。

Inno Setup 自动记录安装日志；可用 /LOG="D:\PiChat-setup.log" 指定日志位置。可选 Pi 安装日志位于 %TEMP%\pi-chat-pi-install.log。卸载只移除应用、私有 Node 和该安装自己的配置，不删除 ~/.pi/agent 中的 Pi、凭证、Skills 或会话。

便携 ZIP（自备 Node 与 Pi 的跨平台部署）

pi-chat-portable-<版本>.zip 只包含 Pi Chat 应用本体（Web + 编译后的服务端 + 运行时适配器）与 Windows 启动脚本，不包含 Node 和 Pi：适合解压即用或在没有安装器的系统上部署。Windows 下解压后使用 start-pi-chat-ui.ps1 / pi-chat-launch.cmd 启动；Linux/macOS 在装好 Node 22.19+ 与 Pi 后，在解压目录运行 node server/server/index.js 即可。文件选择器、资源管理器打开、Setup 管理 Pi 等 Windows 专属功能在非 Windows 上不可用；项目定位仍是 Windows-first，便携包不构成跨平台官方支持承诺。

Release 文件	用途
pi-chat-setup.exe	Windows 安装包，内置 App + Node；缺少 Pi 时从包内离线安装后备快照
pi-chat-portable-<版本>.zip	应用便携包，自备 Node 和 Pi，无安装向导
GitHub 自动生成的 Source code	源码归档，不是运行包

.sha256 校验记录和 .manifest.json 构建清单在 CI 内生成、验证和留存，不作为 Release 附件发布。

源码 checkout 的准备方法见下文「开发」。Windows 启动脚本仍用于源码开发和已安装应用，不作为另一个 portable 分发入口。

Pi Chat 默认只监听本机回环地址，关闭浏览器窗口不会停止本地服务。

为什么不是另一个 Pi Web UI？

目标	Pi Chat 的选择
执行一致性	Pi 保留 agent loop、Runtime、Session JSONL 和工具执行 authority
可靠性	Prompt identity、SSE reconnect、retry、F5 和 A → B → A navigation 都有明确 fencing
本地安全	loopback + Host/Origin/token guard；不提供半成品远程访问开关
成本控制	浏览冷 Session 不启动 Runtime；执行时才按 Session 准备独立 Pi RPC
并发模型	多窗口可共享提交，Prompt/Steer/Compact/queue/settings 进入 Session-scoped FIFO；破坏性 Rename/Delete 才需要 exclusive control
产品边界	Windows-first、local-first；不捆绑 Electron，不重写 Pi，不做远程多用户平台

适合谁？

• 已经在本机使用 Pi，希望从浏览器或独立窗口使用它的人；
• 经常切换多个 Session、需要保留冷历史和长对话的人；
• 在意 reload、断线重连、重复 Prompt、Runtime 重启和多窗口竞态的人；
• 希望保留 Pi 原生行为，而不是迁移到另一个 Agent runtime 的人。

当前能力（详细）

• 用户输入、可靠停止生成，以及生成中的可撤销 Follow-up 队列
• Pi 模型流式输出
• 发送按钮旁统一 ＋ 附件入口：图片与本地文件
• 图片支持选择、粘贴、拖入、预览和视觉模型输入；每次最多 10 张、单张不超过 8 MB、原始图片总大小不超过 40 MB
• 普通文件通过 Windows 原生选择器或资源管理器复制粘贴获取绝对路径，只引用路径并由 Pi 工具按需读取
• Pi 扩展命令、Prompt Templates、Skills 与常用内置命令的 / 指令联想
• Extension 状态命令立即执行并仅显示通知，不写入对话或 Follow-up 队列
• Markdown、GFM 与 KaTeX；正文支持 $...$ / $$...$$ 和 \(...\) / \[...\] 四种数学分隔符。仅转换渲染副本，代码、链接和 HTML 标签不按公式改写，复制仍返回原始 Markdown / LaTeX
• 选中渲染内容时复制原始 Markdown / LaTeX
• Pi-web 风格的可收起会话侧栏、New 和刷新
• 当前 Session 若有 pi-subagents 后台步骤，顶栏会快速显示紧凑的“N 个子代理”入口：使用安全任务标签、活动与耗时投影，点击已验证条目可在现有聊天区打开对应子代理 JSONL（严格只读）；子 Session 不加入左侧会话，也不能启动、Steer、恢复、中断、停止或取得 SessionControl
• 长会话初始仅渲染最近 10 个用户发起的完整对话轮次（包含该轮后续回复与工具过程）；滚到顶部可点击“加载更早 10 轮”逐步展开历史；侧栏会话元数据使用持久化索引缓存，变更时增量更新
• 对话右侧提供首条、上一条、下一条、最新的四格导航
• Files / Changes 检查器按当前 Session 的成功 Edit/Write 结果列出最近文件并提供有界只读预览；预览标题栏可经服务端重新验证后，用 Windows 默认应用显式打开该文件；已知会被 Shell 直接执行的脚本/快捷方式类型会拒绝打开
• 已保存 Assistant 回复中的本地 Markdown 链接和图片可引用 Workspace 外或其他本地磁盘的明确路径：链接经点击后打开，允许类型的图片通过鉴权接口内嵌显示。权限只来自该 Session 的实际 Markdown 引用，不开放任意磁盘浏览；敏感/隐藏路径、符号链接、目录穿越和新增 UNC/设备路径仍拒绝，可执行类型不启动、SVG 不内嵌。Files 检查器、工具写入权限和 Runtime 工作目录不变
• 固定铺满动态视口，兼容窗口最大化/还原、Windows DPI、页面缩放和窄窗口
• Session-first 历史会话列表、切换和新建：服务与界面先打开、读取并缓存 JSONL；Primary 会在后台启动并完成兼容性验证，未 ready 或验证失败时历史仍可浏览且不会探测 Primary RPC。选中、滚动、搜索或切换冷历史只读取 JSONL，不启动 Secondary Runtime；只有发送、Compact、Model/Thinking 或显式启动 Pi 等实际操作才会为该 Session 单飞准备专属 Runtime。服务的默认工作目录保持固定；需要不同目录时，在创建该条 New 草稿后使用“新对话工作路径”选择器单独修改，不会影响其他对话。新对话首条消息将 Runtime 创建、Model、Thinking、Gate 与 prompt 合并为一个服务事务。最多 7 个热对话（Primary + 6 个 Secondary），达到容量时优先 LRU 回收最久未使用的空闲 Secondary；若没有可回收的空闲对话则拒绝新的 Runtime 启动，正在显示的持久历史也可退回 view-only
• 同一 Session 可在多个窗口观察和提交；Prompt、Steer、Compact、queue 与 settings mutation 由服务按 Session 排入 FIFO，并以请求 identity 和 Runtime generation fencing。Rename/Delete 等破坏性操作另行使用 exclusive-control 保护，不把普通 Prompt 操作建模成 takeover。
• 文件权限 Gate：作为 Pi Chat 内置辅助确认层呈现；顶栏可切换“严格 / 放行”。严格模式始终确认 write / edit，并只对可识别的高风险 Bash 做辅助确认；它不是完整 sandbox，不覆盖任意脚本副作用、网络命令、包安装或注册表/启动项修改。随应用自动安装、校验和修复的极小 Pi 工具执行适配器仍在真实工具执行前运行
• 侧栏提供独立刷新和“完整重启 Pi Chat 并应用更新”：应用级 Lifecycle Barrier 会在构建前同步阻止所有新写操作；新版本先在独立 staging 目录完成并验证，构建失败不会修改当前 dist，二次核验全部 Runtime、队列和确认状态通过后才提升产物并执行服务切换。维护期间历史、健康检查和只读 API 保持可用。网页与服务的 build identity 不一致时，普通修改会暂停，但“完整重启”与设置中的“关闭 Pi Chat”仍可请求服务端执行其最终 Busy 检查，避免客户端恢复路径被旧页面状态锁死。SSE/EventSource 是可重连传输，断开不会自动关闭 Pi Chat 服务或托管 RPC；关闭全部浏览器/PWA 页面也只释放窗口、Presence、Session 控制与可回收 Runtime，不再自动停止本地服务。需要停止服务时，使用设置中的“关闭 Pi Chat”显式请求，并由服务端执行全局 Busy 检查
• 外观设置：主题、字体、字号、行距和对话宽度
• 设置中的“关于”显示 Pi Chat/Pi Runtime 版本、Build Revision/Fingerprint、Web/服务构建一致性、Primary Runtime 和生命周期，并提供显式 GitHub Release 检查；检查更新只读取最新 Release，不自动下载、安装、重启或部署。诊断还会记录独立 Direct RPC 的 child entry evaluation、stdout、transport readiness 以及可用的 Extension import/factory 脱敏阶段时间；设置中的“诊断”可一键导出最近五分钟的服务端/当前浏览器页面结构状态时间线，用于复现 Runtime、SSE 实际投递、Sidebar、Composer、多窗口控制与队列投影不一致；两条时间线始终在内存中有界保留，不需要预先开始录制，也不拥有窗口或 Session 控制权。普通累计流式更新不会逐帧入库，而只在有界计数器中汇总 SSE 调度、背压、无客户端、超限替代、写错误与浏览器调度结果；可见当前 Pane 的首个 Assistant 提交仅通过双 requestAnimationFrame 记录一次绘制机会（不代表物理显示或首 token）。排队 Prompt 只复用既有公开 Queue ID，立即发送 Prompt 的诊断 UUID 仅存在于服务内存，最终文件对 Session 与全部 Prompt 关联统一使用一次性别名，且不包含请求 token、聊天/草稿正文、图片、文件路径、密钥或原始错误堆栈
• 可用模型列表、Models 面板与模型切换；支持基于 ~/.pi/agent/models.json 的自定义模型 Add/Remove
• 顶栏 Thinking 强度切换
• 固定左右布局的设置窗口：左侧依次为外观、Models、Skills、Extensions、Packages、诊断；顶栏模型切换与侧栏 Models 快捷入口仍保留
• Skills、Extensions、Packages 按 Pi 原生资源层级分别呈现：资源只在对应能力页显示一次；包内 Extension 标注“由 Package 管理”，Package 页只显示来源与资源摘要。Model 变更和 Skill/Extension/Package 开关使用原子文件写入；Runtime Reload 失败时恢复原配置并尝试恢复旧 Runtime。目录树安装/卸载不执行自动删除式回滚
• 设置与 Models 使用居中 Windows 式小窗口
• Thinking 和工具调用折叠显示
• Pi 扩展的 select / confirm / input / editor 对话框；模型可见的澄清类 Extension 可复用同一条 Session 控制、恢复和响应通道
• Windows 桌面浏览器 / PWA 界面，支持桌面窗口缩放与分屏；当前不承诺移动端功能或适配

版本与路线

当前发布版本为 0.5.4：模型探测安全与请求时序修复、附件生命周期收尾、长会话启动探测修复，以及轻量源码 CI。新标签独立发布完整 Windows Setup 与便携 ZIP，不替换 v0.5.3 的标签或资产。见 release-notes-v0.5.4.md。

main 中比上述 revision 更新的修改不会自动进入既有 Release。后续修复见 CHANGELOG.md 的 Unreleased；以实际安装包的 Build Revision 为准，不把源码改动等同于已经分发。

路线与 authority 说明见 docs/architecture.md、docs/web-architecture-roadmap.md 和 v0.4.7 authority 收敛稳定性矩阵。

环境要求

• Node.js 源码/便携包需要 22.19 或更高（与 Pi 官方下限一致）；Windows Setup 优先本机 Node 22.19+，没有合适版本时使用内置 Node.js 24.22.0 LTS
• 已安装并完成模型认证的 Pi：pi --version 完整 Setup 未检测到 Pi 时会离线展开包内 Pi 1.3.0 后备快照；模型认证仍需用户配置。以下说明针对源码运行与既有 Pi 用户。 Pi Chat 不会用进程内共享 Pi 内核托管多个 Session；服务仍会为每个执行对话拉起独立 Pi RPC。Runtime 直接使用本机安装的全局 Pi，并继续从该安装读取配置、Extension、Package、CLI 与 package-relative 资源。Pi 尚未就绪时，已保存的 Session JSONL 仍可浏览；发送或其他需要 Pi 的操作会提示 Runtime 不可用。
• Windows 桌面快捷方式可选；Edge PWA 仅影响独立窗口体验，不是硬性依赖

没有安装 Pi 时会发生什么？

双击或运行 start-pi-chat.cmd、pi-chat-launch.cmd、桌面 Pi Chat Web 时：

1. 启动器先尝试用 Node 启动本机 http://127.0.0.1:30170 服务；
2. 服务先开放 Session JSONL 浏览，再在启动时一次性解析并冻结全局 Pi identity，随后使用该安装的 rpc-entry.js 启动独立 RPC 并验证协议能力；
3. 找不到 Pi 或兼容性验证失败时，已保存的历史仍可查看，但发送、运行指令和其他 Runtime 操作会稳定返回“Pi Runtime 不可用”，不会通过隐式重启绕过兼容性验证。找不到 Pi 时会显示： 找不到全局 Pi。请先安装 Pi，或设置 PI_CHAT_PI_ENTRY 指向 dist/rpc-entry.js。
4. 表现：
   • 带启动浮窗（桌面快捷方式 / start-pi-chat-ui.ps1）：浮窗在服务可浏览时关闭；Pi Runtime 的后续失败记录在 server 日志；
   • 直接跑 cmd：浏览器仍可打开本地历史；详细 Runtime 错误在 server 的 stderr 日志。

若要聊天或运行工具，请安装并配置好 Pi。

Pi 已安装，却提示不可用？

CMD、PowerShell 和直接运行 Node 服务使用同一套服务端发现逻辑，不需要逐个修改启动脚本：

1. 显式 PI_CHAT_PI_ENTRY 优先，指向 Pi 的 dist/rpc-entry.js；路径无效时不会偷偷回退到另一套 Pi。
2. 使用在“Pi 连接设置”中明确保存的入口（按 Pi Chat 安装目录隔离）。保存的路径无效时不会静默改用其他 Pi。
3. 未保存入口或选择自动发现时：先检查 PI_MANAGED_INSTALL_ROOT（若设置），再检查用户主目录下 .pi/agent/install/current-version 所选择的官方 managed install。
4. 继续检查 npm prefix、系统全局目录、Windows %APPDATA%/npm 和 PATH 附近的 npm 安装。

安装发现只读文件，不执行 pi、npm 或网络下载，也不会把 Pi Chat 开发依赖中的 Pi 当作用户安装。版本从所选 Pi 包的 package.json 读取，协议兼容性仍由 RPC capability probe 判定。

更新 Pi、修改入口路径或修复安装后，使用网页的关闭功能安全退出 Pi Chat，再重新启动即可，通常不需要重启电脑。如果服务仍显示不可用，请检查 server 日志：安装发现、协议兼容性、模型认证和网络连接是不同问题。

在网页中修复 Pi 连接

Pi 不可用提示旁的 “连接设置 / 重试” 可进入连接设置窗口；About 不再重复提供连接按钮：

• 重新检测：只读取安装元数据，不启动 Pi、不修改配置。
• 选择 rpc-entry.js：在 Windows 本机文件窗口中选择可信 Pi 安装的 dist/rpc-entry.js。选择只是预览；取消不会保存任何设置。
• 使用自动发现：预览自动发现的候选入口；确认应用后清除固定入口偏好。
• 重试连接 / 保存入口并重启服务：明确确认后，检查所有对话空闲并安全重启 Pi Chat；不执行 npm、不构建、不下载，也不删除聊天记录。请先保存未发送内容，无需重启电脑。

入口偏好保存在 Pi agent 目录（默认 ~/.pi/agent）下的 pi-chat/runtime/<安装目录哈希>.json，只包含入口路径，不存储模型密钥，不影响其他 Pi Chat 安装目录。PI_CHAT_PI_ENTRY 仍拥有最高优先级；存在该环境变量时，网页不会覆盖它。

所选文件只会做路径和 Pi 包元数据检查，不是代码安全认证；应用后会以当前用户权限运行该 Pi 安装及其扩展。真正的协议兼容性仍要由重启后的 Runtime 检查。模型认证或 API 网络故障不会因为重新选择入口而自动解决。

若保存成功但服务重启失败，入口偏好保留供下次手动启动；若旧 Pi 进程退出无法确认，不会启动第二个 writer。源代码 watch/dev 模式不支持此免构建重启，请手动重启开发服务。

可选：让模型在歧义处暂停提问

Pi Chat 会原样承载 Pi RPC 的 select、confirm、input 与 editor Extension UI。可选安装已验证支持 RPC dialog fallback 的 ask_user_question Package：

pi install npm:@juicesharp/rpiv-ask-user-question

安装后对目标 Runtime 执行 /reload，或在没有进行中对话、队列及确认时正常重启 Pi Chat。原生 Pi 终端显示 Package 的完整多题 TUI；Pi Chat 会从 ask_user_question 工具调用投影出同一份多题问卷：单选后自动进入下一题，多选保留“下一个”，自由输入直接展开在对应选项行并可按 Enter 前进，最后一题完成后才开放“提交”，同时保留“上一个”用于修改答案。提交时 Pi Chat 仍通过 Package 现有的 Session-scoped select / input RPC 请求逐步回送已确认答案，不会伪造新的用户 Prompt，也不会改变 request ID 或 Session/control authority。若页面在工具开始事件之后才恢复，无法重建完整问卷时会安全退回原生标量 RPC 对话框。该 Package 是具有当前用户权限的第三方 Pi 扩展，不属于 Pi Chat 内置 Gate；安装前应审查并固定可信版本。

开发

首次参与请先阅读 CONTRIBUTING.md，其中给出了 live dist 安全边界、focused/full 验证入口和单 writer 工作方式。

git clone 或 Source code.zip 仅包含源码，不是可直接双击运行的发布包。首次在项目目录准备依赖并构建：

npm ci --include=dev
npm run build

完成后再运行 start-pi-chat.cmd。开发热更新可用 npm run dev。--include=dev 确保即使设置了 NODE_ENV=production，构建工具也会安装；启动器本身不会代替你执行安装或构建。网络需要代理时，请单独配置 Git/npm 代理，不要把模型密钥放进代理地址或提交到仓库。

默认地址：http://127.0.0.1:30170。没有已保存工作目录选择的新安装，New 草稿默认使用当前用户主目录（Windows 下如 C:\\Users\\<用户名>）；PI_CHAT_CWD 或 --cwd 可提供启动回退目录，但已有的用户保存选择不会被自动覆盖。每个尚未提交的 New 草稿可单独修改其工作路径。

测试

所有自动化测试使用隔离的临时 Session、Runtime 和构建目录；不会把验证流量发送到正在运行的 Pi Chat。发布前分开检查 source/typecheck、staged artifact、隔离浏览器和 GitHub CI。

安全与许可证

Pi Chat 默认只服务本机回环地址，不是远程多用户服务。安全问题请优先通过 GitHub 的私密安全报告渠道提交，详见 SECURITY.md。

本仓库以 MIT License 发布（版权起始 2026，oopjoy 及 Pi Chat 贡献者）。第三方依赖、随包分发的字体与资源仍遵循各自的许可条款，不因本仓库选择 MIT 而改变。

快速聚焦验证通过 npm 别名直接进入官方 harness，不会触发 npm test 的 pretest 全量构建：

# --file 可重复，路径必须是仓库 tests/ 下已发现的 .test.ts
npm run test:focus -- --file tests/web/composer-model-runtime.test.ts
# 文件与名称过滤可以组合；NODE_ENV=test 由 harness 负责设置
npm run test:focus -- --file tests/web/composer-model-runtime.test.ts --test-name-pattern="slash suggestions"
# 核心 source lane：跳过 benchmark contract 与需要编译产物的 artifact 测试
npm run test:source
# benchmark contract lane：使用独立新进程执行，不从 unit/release gate 删除
npm run test:benchmark
# 完整非 artifact unit 入口
npm run test:source-and-benchmark
# artifact/restart lane：显式运行被 source lane 排除的测试（要求已有受信任 dist）
npm run test:artifact
# 在隔离 staging 中重新 build 后运行 artifact/restart gate
npm run verify:artifact

阶段门禁使用自动隔离的系统临时 staging，不会写 live dist。成功后 staging 自动删除；失败时会保留并打印诊断路径：

npm run verify:unit
npm run verify:e2e
npm run verify:artifact
# typecheck → 一次共享 build 后的 source unit + Playwright → artifact/restart → diff check
npm run verify

冷 Runtime 基准使用显式离线 Session 副本，不会向源 JSONL 写入 Prompt：

npm run benchmark:pi-runtime-startup -- --session <offline-session.jsonl> --iterations 5 --profile core

core 隔离 Pi/Session 核心启动；installed-profile 显式加载当前安装的 Extension/Profile。输出同时区分 transportReady 与完整 capability probe 的 capabilityReady，并保留 startup phase 记录；该基准保证 fresh process，但不会声称已经清空 Windows 文件缓存或 Defender 缓存。

Harness 会递归发现 tests/**/*.test.ts，不会跟随测试目录中的符号链接；--file 和 --exclude-file 同时接受 / 和 Windows \\ 分隔符，后者只影响未指定 --file 时的默认选择。使用 --test-name-pattern 时，Harness 会先确认所选文件中至少有一个可静态解析的具体测试名匹配，拼错名称会以状态码 2 失败。对于 for...of 字面量数组生成的模板名称，Harness 会展开为具体名称；其他无法静态解析的动态名称应先重写为明确测试声明。Harness 固定单文件并发、45 秒 Node test timeout 与 2 GiB V8 old-space；Windows 还会在创建任何 Node 后代前，将整个测试树加入 3 GiB Job Object，超限会明确输出 PI_CHAT_TEST_MEMORY_LIMIT_EXCEEDED 并终止测试树。--test-concurrency 与 --test-timeout 不能由调用方覆盖；调用方仅可使用 --test-name-pattern、--test-shard、--test-skip-pattern 与无值的 --test-only 选择测试，reporter、coverage、snapshot mutation 和 force-exit 参数不会转发。这些限制仅属于开发验证测试树，不会施加给生产 Pi Chat server 或 Pi RPC。不要绕过 scripts/run-tests.mjs 直接调用 node --test。需要保留指定构建产物的发布验证仍应显式设置独立 PI_CHAT_DIST_DIR；普通贡献者验证优先使用上述 wrapper。少数安全边界测试需要 NODE_ENV=test 才能使用仅限 JSDOM 的 identity override；生产 Web artifact 不存在该 override。

修改现有功能前，可先查阅 docs/change-map.md：它把常见改动映射到唯一状态所有者、epoch/generation 边界、关键不变量和聚焦测试入口。详细政策仍以对应架构文档为准。

Windows 桌面快捷方式

仓库不会提交桌面上的 .lnk 文件（会写死本机路径，别人 clone 后失效）。请在本机项目目录生成：

# 必须先进入含 package.json 的项目目录（不要在 C:\Users\你的用户名 下直接 npm）
cd C:\path\to\pi-chat

# 方式一：npm 脚本
npm run install:shortcuts

# 方式二：不依赖 npm 的 package 脚本名，直接跑安装脚本
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-shortcuts.ps1

主入口默认使用 Web；PWA 保留为独立的可选入口：

名称	行为与位置
Pi Chat Web	Setup 安装版的桌面 Web 入口；由安装器管理，与 Git 源码入口分开。开始菜单仍有 Pi Chat
Pi Chat PWA	Setup 安装版的可选 PWA 入口；不作为默认打开方式
Pi Chat Git	上述源码脚本生成的 Web 入口；桌面、独立的开始菜单 Pi Chat Git 组及 Git 项目根目录
Pi Chat Git PWA	Git 源码版的可选 PWA 入口；仅在独立的开始菜单组中

说明：

• 源码脚本只创建带 Git 名称的入口，指向当前源码目录的 start-pi-chat-ui.ps1；Setup 不创建、覆盖或删除这些入口。反复测试安装版不会改变 Git 入口。移动 Git 项目后请重新生成。
• 两套仍使用同一个本机端口；独立快捷方式不意味着可同时运行或互相接管。切换版本前请在原窗口安全关闭当前服务。
• 各入口都会显示统一启动浮窗，并按需启动 127.0.0.1:30170；启动失败时浮窗会保留并提供日志，不打开可能属于另一构建的网页。
• 兼容入口：start-pi-chat.cmd 等同 Web；也可手动运行 pi-chat-launch.cmd web 或 pi-chat-launch.cmd pwa。
• 没有安装全局 Pi 时的失败行为见上文「没有安装 Pi 时会发生什么」。

Pi Chat 不提供 Todo 功能，也不会安装或管理 Todo Extension。历史 Session JSONL 中已有的 Todo 快照会保留为历史记录，但不会再注册 /todo 命令或 todo 工具。

文件权限 Gate 会安装为 Pi Chat 的系统安全执行组件 pi-chat-file-permission-gate.ts：它会在每次启动时校验完整性、自动修复并强制启用，且不在普通扩展管理中显示。若旧版 file-permission-gate.ts 与 Pi Chat 原组件等价，会安全改名为 .pi-chat-legacy-disabled 备份以避免重复注册 /gate；自定义旧 Gate 绝不会被覆盖，Pi Chat 会报告冲突并拒绝启用新的系统组件。

可选：使用浏览器的 PWA 独立窗口

Pi Chat 默认用普通 Web 打开，同时保留可选 PWA 入口。PWA 是浏览器的站点安装/独立窗口能力，不是第二套 Pi Chat 安装包或 Runtime；本项目不会替你安装浏览器、登录账号或创建浏览器应用配置。启动服务后，用 Edge 或 Chrome 打开 http://127.0.0.1:30170，在浏览器菜单中选择“应用 / Apps → 将此站点安装为应用（Install this site as an app）”。

通过浏览器完成站点安装后，可以从浏览器生成的图标启动独立 Pi Chat 窗口，不显示地址栏、标签页、书签栏或浏览器导航；普通 Web 访问仍然可用。Pi Chat 的可选 Pi Chat PWA 入口保留既有 Edge 打开方式，依赖本机对应的浏览器应用配置；新电脑建议先用 Web 打开，再按需在浏览器中安装。该模式不使用 Service Worker，避免本地更新后被旧前端缓存遮挡。关闭最后一个浏览器/PWA 窗口不会停止本地服务；刷新、BFCache、网络/SSE 断线以及测试或临时浏览器退出都不会让 Pi Chat 离线。需要停止服务时，请使用设置中的“关闭 Pi Chat”显式关闭；可通过桌面的 Pi Chat Web 再次打开窗口。源码工作目录需在停服后显式执行 npm run build 才会应用本地改动，启动器不自动构建；完整 Setup 已内置编译产物和私有 Node，不需要系统 npm、源码或构建工具即可启动。

构建与运行

npm run build
npm start

如果 127.0.0.1:30170 已有 Pi Chat 服务，npm run build 以及所有会写 live dist/ 的组成命令（clean、build:identity、build:web、build:server、copy:resources）都会拒绝覆盖它正在提供的 dist/，防止旧服务混用新网页资源。请使用界面的“完整重启 Pi Chat 并应用更新”，或先关闭 Pi Chat；应用内重启会安全地在 staging 目录构建。桌面启动器也会将监听服务的 build identity 与本地 dist/build-identity.json 比较：若端口上是不同构建（可能是另一个 checkout 或安装），启动器只报告冲突并退出，绝不自动关闭或按端口/PID 强杀该实例；请在它自身窗口中显式关闭或切换后，再启动当前版本。构建保护默认检查 127.0.0.1:30170；若以非默认端口运行，请设置 PI_CHAT_PORT 为实际端口。

可选参数：

node dist/server/server/index.js --host 127.0.0.1 --port 30170 --cwd C:\\work

也可以使用环境变量：PI_CHAT_HOST、PI_CHAT_PORT、PI_CHAT_CWD。如果无法自动发现全局 Pi，可设置 PI_CHAT_PI_ENTRY 指向 Pi 的 dist/rpc-entry.js。

安全说明

基础版只监听本机回环地址（默认 127.0.0.1）。每次服务启动会轮换内存请求 token，并校验精确 Host、同源 Origin 与 token，阻止普通跨站网页调用本机 Pi 接口。后台子代理状态只从当前用户精确临时根下的 UUID run 目录读取普通 status.json，拒绝符号链接、越界大小/年龄/数量、未知状态与畸形字段，并且只有状态中的父 Session JSONL 路径与当前 SessionIndex 或已拥有 Runtime 的 Session 路径精确一致时才投影；cwd 从不作为归属证明，浏览器永远收不到 run/toolCall ID、路径、任务正文、输出、参数或原始错误；只有符合安全 slug 规则的步骤标签和经过父子路径复核的 opaque 子 Session ID 可用于只读导航。启动时还会探测 Pi RPC 的必要能力；若 Pi 升级导致协议不兼容，服务会给出明确错误而不是带着部分失效功能启动。文件权限 Gate 的执行钩子虽然技术上运行于 Pi Extension API，但由 Pi Chat 自动管理、不可通过普通扩展列表停用或移除；这确保网页 UI 保持内置体验，同时真实工具调用前仍有可靠拦截。

设置面板的“默认工作路径”可选择以后 New 草稿的默认目录；New 草稿中的“新对话工作路径”可只为该次对话另选目录。两者只更新未来草稿和目录索引上下文，绝不会重启、重绑或改变任何活 Runtime 的真实 cwd。POST /api/workspace/set 仅保留给本地自动化或未来本机 CLI，不是远程访问能力。当前版本不提供远程多用户、HTTPS 公网暴露或跨机器访问；请勿将服务绑定到非回环地址或暴露到公网。

Skills 可以向模型注入指令，Plugins/Packages 可以用当前用户的完整权限执行代码。安装来源必须可信；删除操作会在界面中二次确认。Skills/Plugins 配置变化后，Pi Chat 会重启 RPC 并恢复当前会话。

产品边界

当前功能入口、保留的本地 API 与已删除能力，以 docs/feature-surface.md 的清单为准。标记为已删除的能力不得只保留隐藏路由、浏览器包装、共享类型或专用回归测试。

Pi Chat 负责： 会话展示与输入、本地 Session 切换、Runtime 按需启动与回收、多窗口控制权、Gate/确认交互、Pi 原生资源的有限管理，以及本地 Web/PWA 启动体验。

Pi Chat 不负责： 重写 agent loop、模型和工具执行、自建插件运行时、Electron 桌面壳、远程多用户服务、公网部署，或通用 agent 编排平台。

当前不在路线图的伪需求： 远程访问。代码与文档中可预留扩展点，但 0.5.x 不做半成品远程开关。若未来需要，应作为独立设计（认证、HTTPS、审计）而不是放开监听地址。

兼容的 Pi 版本

范围	当前验证口径
开发依赖基线	package.json 和 lockfile 精确固定 Pi 1.3.0；核心真实 RPC 测试直接使用项目内这份依赖，不回退到用户的全局 Pi，也不因全局 Pi 缺失而跳过
Setup 后备 Pi	固定 1.3.0；真实安装器集成测试覆盖离线展开、复用已有 Pi、缺失入口恢复和安装/卸载
Pi 1.3.0 集成	固定依赖上的 RPC 启动、目录刷新、dequeue、模型重选与 thinking 行为测试；用户全局/managed Pi 的发现与安装包恢复另行测试，不把两者混为同一个入口
其他 Pi / 扩展组合	启动能力探测通过不等于所有行为已验证；ask_user_question 有 RPC dialog fallback 冒烟覆盖，不承诺任意 TUI 扩展自动转为 Web UI

暂不把开发依赖升级、打包后备版本、启动能力探测和完整行为验证混称为“已兼容所有版本”。

• 探测方式： 服务启动时冻结一个 Primary/Secondary 共用的 Direct Pi launch plan，解析并记录全局 Pi 版本与入口；显式 PI_CHAT_PI_ENTRY 保持 direct-only authority。Primary 随后执行 RPC 能力探测（get_state / get_available_models / get_commands / get_session_stats）；启动探测不再读取完整 get_messages，避免长会话的响应大小或耗时被误判为协议不兼容。不兼容时 Session 浏览继续可用，而新的或需要恢复的 Runtime 写操作返回明确的不可用状态；已经健康的 Secondary 保持可用。任何 Primary 恢复都会重新探测
• 升级 Pi 后若启动失败，请先 pi --version，再确认 Pi Chat 是否为最新 0.5.x

反馈问题时请附上

• Pi Chat 版本、About 中的 Build Revision / Fingerprint，以及 Stable / Preview / Main 渠道。
• Pi 版本（pi --version）、浏览器与 Windows 版本。
• 操作前状态（空闲、生成中、等待确认、发送未返回等）和最短复现步骤。
• 预期结果、实际结果；截图、短录屏或界面显示的事件 ID。
• 必要时通过设置导出现有的最近五分钟诊断。分享前检查并去除敏感路径、提示词、凭证及个人数据，不直接上传 auth.json、API Key 或完整私有会话。

草稿与附件保留边界

• 未发送文字、图片和附件卡片只保留在当前页面内存；切换 Session 和明确发送失败会保留，不承诺刷新、关闭或崩溃后恢复。有未发送内容时会请求浏览器原生离开确认，但浏览器可能不显示，不能代替备份。
• 拖入的普通文件副本保存在独立用户数据目录（Windows：%LOCALAPPDATA%/PiChatData/attachments），不在安装目录或临时 dist。未采用的上传有 24 小时宽限；仍被页面引用的文件定期续租，最后一次成功续租后保留 30 天。发送前标记为已发送或可能发送的文件不自动删除，避免历史引用失效；这不等于草稿可以跨刷新恢复。
• 已撤回实验性的跨刷新草稿恢复及存储管理面板，不再读写该备份。用过实验版本的浏览器可能仍有 pi-chat.draft-backup.v1.*、pi-chat.draft-consumed.v1.*、pi-chat.draft-generation.v1 的 localStorage 项，以及 pi-chat-draft-recovery-v1 IndexedDB 数据库。应用不会自动恢复或删除它们。需要清理时，先在浏览器开发者工具 Application 中检查并保存所需内容，再显式删除对应条目／数据库；不要直接清空全部站点数据，以免连带删除外观等偏好。
• 普通用户原文件不会由附件清理器删除。历史中引用的托管附件应在确认不再需要后自行处理；本次没有删除任何真实用户数据。

更完整的模块边界与拆分优先级见 docs/architecture.md；日常维护入口见 docs/change-map.md。