pisper 0.5.4-linux-x64.0 → 0.5.4

package/README.en.md

@@ -0,0 +1,224 @@
+<p align="right"><a href="./README.md">简体中文</a> · <strong>English</strong></p>
+
+<a id="top"></a>
+
+<p align="center">
+  <img src="docs/brand/pisper-logo.svg" width="112" alt="Pisper project logo" />
+</p>
+
+<h1 align="center">Pisper</h1>
+
+<p align="center"><strong>A local-first Agent application powered by Pi</strong></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-17141F?style=flat-square&logo=nodedotjs&logoColor=F59E0B" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-17141F?style=flat-square&logo=typescript&logoColor=F59E0B" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/React-17141F?style=flat-square&logo=react&logoColor=F59E0B" alt="React" />
+  <img src="https://img.shields.io/badge/Tauri-17141F?style=flat-square&logo=tauri&logoColor=F59E0B" alt="Tauri" />
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-F59E0B?style=flat-square" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ling-kong-ran/pisper/releases/latest">
+    <img src="https://img.shields.io/badge/Download%20Desktop-Windows%20%7C%20macOS%20%7C%20Linux-F59E0B?style=for-the-badge&logo=github&logoColor=17141F" alt="Download Pisper desktop" />
+  </a>
+</p>
+
+<a id="sponsors"></a>
+
+## ❤️ Sponsors
+
+Thanks to the following partners for supporting the Pisper community. If you'd like to appear here too, feel free to reach out via [Issues](https://github.com/ling-kong-ran/pisper/issues).
+
+<details open>
+<summary>View sponsors</summary>
+
+<table>
+<tr>
+<td width="180" align="center">
+  <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH"><strong>Matrix</strong></a>
+</td>
+<td>
+Thanks to <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">Matrix</a> for supporting the Pisper community. Registering through <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">this link</a> may generate referral revenue for the project.
+</td>
+</tr>
+</table>
+
+> Sponsor links contain a referral parameter. Sponsor content is not targeted using conversations, workspaces, providers, models, or API configuration, and Pisper does not send that data to sponsors. The public configuration for the in-app sponsor placement is maintained in [`docs/sponsors.json`](./docs/sponsors.json).
+
+</details>
+
+<p align="center">
+  <a href="#overview">Overview</a> ·
+  <a href="https://ling-kong-ran.github.io/pisper/">Project Site</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#data-safety">Data Safety</a> ·
+  <a href="#desktop-pet">Desktop Pet</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#tui">Terminal Client</a> ·
+  <a href="#development">Development</a> ·
+  <a href="#sponsors">Sponsors</a> ·
+  <a href="#license">License</a>
+</p>
+
+---
+
+<a id="overview"></a>
+
+## Overview
+
+Pisper is a desktop and terminal client built on [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), with multiple sessions, Tools, Skills, MCP, automation, and per-session permissions.
+
+See the [Pisper project site](https://ling-kong-ran.github.io/pisper/) for the product overview and interface preview.
+
+### Get Started in Three Steps
+
+1. [Download the desktop app](https://github.com/ling-kong-ran/pisper/releases/latest) (Windows / macOS / Linux, no Node.js required)
+2. Configure any model provider with an API key
+3. Create a session and start working in parallel
+
+<a id="features"></a>
+
+## Features
+
+- **Multiple sessions:** independent models, context, workspaces, and permissions with Dock splits and layout restoration.
+- **Tools, Skills, and MCP:** manage capabilities and call permissions in one place.
+- **Subagents:** run temporary tasks in isolated contexts and return results to the parent session.
+- **Memory and multimodal input:** retrieve project memory and process images, documents, and code.
+- **Automation and channels:** schedules, visual workflows, Feishu, and personal Weixin.
+- **Desktop and terminal:** Tauri desktop app and Ratatui TUI.
+- **Permission controls:** `Read only / Full access` execution modes, one-shot approval, and credential isolation.
+
+<a id="data-safety"></a>
+
+## Data Safety & Privacy
+
+Pisper is local-first and does not provide a cloud service that hosts or relays conversations. Sessions and settings are stored under `~/.pisper/agent` by default; set `PISPER_AGENT_DIR` to move them.
+
+- The Runtime listens on `127.0.0.1` by default, and Pi telemetry is disabled by default.
+- Model calls and enabled remote services such as MCP, Web search, and messaging receive the data required for each request.
+- Common credential formats are redacted at storage and display boundaries, but this is not a replacement for DLP or end-to-end encryption. Protect the local Agent data directory and its backups.
+
+<a id="desktop-pet"></a>
+
+## Desktop Pet
+
+Pisper supports [Petdex](https://petdex.dev)-compatible pets. Install and manage them under **Settings → Desktop pet**. See [`docs/petdex-integration.md`](./docs/petdex-integration.md).
+
+<a id="install"></a>
+
+## Install
+
+### Desktop (Recommended)
+
+Download a Windows, macOS, or Linux installer from [GitHub Releases](https://github.com/ling-kong-ran/pisper/releases/latest). It works out of the box — no separate Node.js install is required.
+
+#### If macOS Refuses to Open Pisper
+
+Pisper is not currently notarized by Apple. Confirm that it came from the official Releases page, then select **Open Anyway** in **System Settings → Privacy & Security**. If that option is unavailable, run:
+
+```bash
+sudo xattr -rd com.apple.quarantine /Applications/Pisper.app
+```
+
+Use this command only for Pisper downloaded from the official Releases page and placed in `/Applications`.
+
+#### If the Linux AppImage Does Not Start
+
+```bash
+chmod +x Pisper_*_linux_x86_64.AppImage
+./Pisper_*_linux_x86_64.AppImage
+```
+
+If FUSE is missing, install `libfuse2` or `libfuse2t64`, or use the `.deb` package:
+
+```bash
+sudo apt install ./Pisper-*-linux-amd64.deb
+```
+
+### Component Updates
+
+**Settings → Updates** in the desktop app is the unified update entry point. A single **Check for updates** action checks the Desktop package, TUI client, and Runtime together. Install controls appear only for components with a newer version, so a small component update does not require downloading the full desktop installer. Each component uses an independent signed Release channel. Runtime updates take effect after restarting the app, and Pisper falls back to the versions bundled with the desktop package if an installed component is unavailable or fails to start.
+
+<a id="tui"></a>
+
+### Terminal Client (TUI)
+
+With Node.js 20+, you can install the Pisper CLI through npm. npm obtains the lightweight launcher, platform-independent Web frontend, and signed TUI and Runtime packages for the current platform from the configured registry, without downloading from GitHub Releases. Installation verifies and extracts the local component packages so Pisper is ready when the command returns; it does not install the desktop shell:
+
+```bash
+npm install -g pisper --progress=true --foreground-scripts
+pisper
+pisper update --check  # check the complete distribution through the npm registry
+pisper update          # update the launcher, Web, TUI, and Runtime through npm
+```
+
+Platform packages use the same registry when an npm mirror is configured. `--progress=true` shows npm download progress, while `--foreground-scripts` shows local signature verification and extraction; add `--loglevel=info` only when request and cache details are needed:
+
+```bash
+npm install -g pisper --registry=https://registry.npmmirror.com --progress=true --foreground-scripts
+```
+
+After entering the TUI for the first time, use `/provider` to choose a Provider and edit its protocol, effective Base URL, and masked API key. The official default Base URL is shown when no override exists, and leaving API Key blank preserves the saved secret. `/model` lists only models from configured Providers. For a known Provider, `/provider <id>` skips the picker (`/apikey` remains a compatible alias). For visual configuration, run `pisper web`; Pisper uses the Web frontend bundled in the npm package and opens an authenticated, localhost-only settings page in your default browser. **Save Provider settings** does not change the default model; only **Set as default Provider** changes the default for later sessions.
+
+After installing the desktop app, you can also install the `pisper` command from **Settings → App updates**. The first installation remains explicit; after later desktop updates restart Pisper, it automatically refreshes this managed terminal client:
+
+```bash
+pisper                 # start a new conversation
+pisper resume          # resume from a list across all workspaces
+pisper doctor          # diagnose the runtime
+pisper web             # open Web settings
+pisper --help          # show complete onboarding and command help
+```
+
+The npm distribution has one complete `pisper update` command. It uses the configured npm registry to update the launcher, Web, TUI, and Runtime; `pisper update --check` only queries and does not install, and component names are not accepted. The standalone TUI exposes no component-update command; the desktop distribution is managed through **Settings → App updates**. See the **[Pisper TUI user guide](./src-tui/README.en.md)** for installation, commands, keyboard controls, attachments, execution modes, and approvals.
+
+### Run from Source
+
+Requires Node.js 20+, npm, and at least one model provider with an API key.
+
+```bash
+git clone https://github.com/ling-kong-ran/pisper.git
+cd pisper
+npm install
+npm run dev
+```
+
+Desktop development and packaging:
+
+```bash
+npm run desktop:webview:dev
+npm run desktop:webview:build
+```
+
+Data is stored under `~/.pisper/agent` by default. Set `PISPER_AGENT_DIR` to use another location.
+
+<a id="development"></a>
+
+## Development
+
+Main stack: React, TypeScript, Tauri, Rust, Node SEA, and Pi Coding Agent.
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+[Issues](https://github.com/ling-kong-ran/pisper/issues) and [pull requests](https://github.com/ling-kong-ran/pisper/pulls) are welcome. Do not commit API keys, bot credentials, or personal data from `~/.pisper/agent`.
+
+<a id="license"></a>
+
+## License
+
+Pisper is released under the [MIT License](./LICENSE). Third-party dependencies and community resources retain their own licenses.
+
+## Acknowledgments
+
+Thanks to [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), [Petdex](https://petdex.dev), and the open-source software used by this project.
+
+Contributors:
+
+- [@mik-myp](https://github.com/mik-myp) — Frontend TypeScript architecture, shadcn/ui / AI Elements, Zustand, and i18n refactor ([#1](https://github.com/ling-kong-ran/pisper/pull/1))
+
+<p align="right"><a href="#top">Back to top ↑</a></p>

package/README.md

@@ -1,14 +1,14 @@
-<p align="right"><a href="./README.md">简体中文</a> · <strong>English</strong></p>
+<p align="right"><strong>简体中文</strong> · <a href="./README.en.md">English</a></p>
 
 <a id="top"></a>
 
 <p align="center">
-  <img src="docs/brand/pisper-logo.svg" width="112" alt="Pisper project logo" />
+  <img src="docs/brand/pisper-logo.svg" width="112" alt="Pisper 项目标志" />
 </p>
 
 <h1 align="center">Pisper</h1>
 
-<p align="center"><strong>A local-first Agent application powered by Pi</strong></p>
+<p align="center"><strong>Pi 驱动的本地 Agent 应用</strong></p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/Node.js-17141F?style=flat-square&logo=nodedotjs&logoColor=F59E0B" alt="Node.js" />
@@ -20,18 +20,18 @@
 
 <p align="center">
   <a href="https://github.com/ling-kong-ran/pisper/releases/latest">
-    <img src="https://img.shields.io/badge/Download%20Desktop-Windows%20%7C%20macOS%20%7C%20Linux-F59E0B?style=for-the-badge&logo=github&logoColor=17141F" alt="Download Pisper desktop" />
+    <img src="https://img.shields.io/badge/下载桌面版-Windows%20%7C%20macOS%20%7C%20Linux-F59E0B?style=for-the-badge&logo=github&logoColor=17141F" alt="下载 Pisper 桌面版" />
   </a>
 </p>
 
 <a id="sponsors"></a>
 
-## ❤️ Sponsors
+## ❤️ 赞助
 
-Thanks to the following partners for supporting the Pisper community. If you'd like to appear here too, feel free to reach out via [Issues](https://github.com/ling-kong-ran/pisper/issues).
+感谢以下合作伙伴对 Pisper 社区的支持。如果你也希望出现在这里，欢迎通过 [Issue](https://github.com/ling-kong-ran/pisper/issues) 联系我们。
 
 <details open>
-<summary>View sponsors</summary>
+<summary>查看赞助商</summary>
 
 <table>
 <tr>
@@ -39,143 +39,143 @@ Thanks to the following partners for supporting the Pisper community. If you'd l
   <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH"><strong>Matrix</strong></a>
 </td>
 <td>
-Thanks to <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">Matrix</a> for supporting the Pisper community. Registering through <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">this link</a> may generate referral revenue for the project.
+感谢 <a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">Matrix</a> 对 Pisper 社区的支持。通过<a href="https://matrix.000328.xyz/sign-up?aff=ZPeH">此链接</a>注册，可能为 Pisper 项目带来推广收益。
 </td>
 </tr>
 </table>
 
-> Sponsor links contain a referral parameter. Sponsor content is not targeted using conversations, workspaces, providers, models, or API configuration, and Pisper does not send that data to sponsors. The public configuration for the in-app sponsor placement is maintained in [`docs/sponsors.json`](./docs/sponsors.json).
+> 赞助链接包含推广参数。Pisper 的赞助内容不会使用会话、工作区、Provider、模型或 API 配置进行定向，也不会向赞助商发送这些数据。客户端赞助位的公开配置维护在 [`docs/sponsors.json`](./docs/sponsors.json)。
 
 </details>
 
 <p align="center">
-  <a href="#overview">Overview</a> ·
-  <a href="https://ling-kong-ran.github.io/pisper/">Project Site</a> ·
-  <a href="#features">Features</a> ·
-  <a href="#data-safety">Data Safety</a> ·
-  <a href="#desktop-pet">Desktop Pet</a> ·
-  <a href="#install">Install</a> ·
-  <a href="#tui">Terminal Client</a> ·
-  <a href="#development">Development</a> ·
-  <a href="#sponsors">Sponsors</a> ·
-  <a href="#license">License</a>
+  <a href="#overview">简介</a> ·
+  <a href="https://ling-kong-ran.github.io/pisper/">项目主页</a> ·
+  <a href="#features">功能</a> ·
+  <a href="#data-safety">数据安全</a> ·
+  <a href="#desktop-pet">桌面宠物</a> ·
+  <a href="#install">安装</a> ·
+  <a href="#tui">终端客户端</a> ·
+  <a href="#development">开发</a> ·
+  <a href="#sponsors">赞助</a> ·
+  <a href="#license">许可</a>
 </p>
 
 ---
 
 <a id="overview"></a>
 
-## Overview
+## 简介
 
-Pisper is a desktop and terminal client built on [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), with multiple sessions, Tools, Skills, MCP, automation, and per-session permissions.
+Pisper 是基于 [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) 的桌面与终端客户端，支持多会话、工具、Skills、MCP、自动化和会话级权限。
 
-See the [Pisper project site](https://ling-kong-ran.github.io/pisper/) for the product overview and interface preview.
+产品介绍与界面预览：[Pisper 项目主页](https://ling-kong-ran.github.io/pisper/)。
 
-### Get Started in Three Steps
+### 三步上手
 
-1. [Download the desktop app](https://github.com/ling-kong-ran/pisper/releases/latest) (Windows / macOS / Linux, no Node.js required)
-2. Configure any model provider with an API key
-3. Create a session and start working in parallel
+1. [下载桌面版](https://github.com/ling-kong-ran/pisper/releases/latest)（Windows / macOS / Linux）
+2. 配置任意一个模型 Provider 与 API Key
+3. 新建会话，开始并行工作
 
 <a id="features"></a>
 
-## Features
+## 功能
 
-- **Multiple sessions:** independent models, context, workspaces, and permissions with Dock splits and layout restoration.
-- **Tools, Skills, and MCP:** manage capabilities and call permissions in one place.
-- **Subagents:** run temporary tasks in isolated contexts and return results to the parent session.
-- **Memory and multimodal input:** retrieve project memory and process images, documents, and code.
-- **Automation and channels:** schedules, visual workflows, Feishu, and personal Weixin.
-- **Desktop and terminal:** Tauri desktop app and Ratatui TUI.
-- **Permission controls:** `Read only / Full access` execution modes, one-shot approval, and credential isolation.
+- **多会话**：独立模型、上下文、工作目录和权限，支持 Dock 分屏与布局恢复。
+- **Tools、Skills 与 MCP**：统一管理能力和调用权限。
+- **Subagent**：在隔离上下文中执行临时任务，完成后将结果返回父会话。
+- **记忆与多模态**：检索项目记忆，处理图片、文档和代码。
+- **自动化与渠道**：定时任务、可视化工作流、飞书和个人微信。
+- **桌面与终端**：提供 Tauri 桌面端和 Ratatui TUI。
+- **权限控制**：支持 `只读 / 完全访问` 两种执行模式，并提供单次审批和凭据隔离。
 
 <a id="data-safety"></a>
 
-## Data Safety & Privacy
+## 数据安全与隐私
 
-Pisper is local-first and does not provide a cloud service that hosts or relays conversations. Sessions and settings are stored under `~/.pisper/agent` by default; set `PISPER_AGENT_DIR` to move them.
+Pisper 是本地优先应用，不提供托管或中转会话的云服务。会话和配置默认保存在本机 `~/.pisper/agent`，也可通过 `PISPER_AGENT_DIR` 更改位置。
 
-- The Runtime listens on `127.0.0.1` by default, and Pi telemetry is disabled by default.
-- Model calls and enabled remote services such as MCP, Web search, and messaging receive the data required for each request.
-- Common credential formats are redacted at storage and display boundaries, but this is not a replacement for DLP or end-to-end encryption. Protect the local Agent data directory and its backups.
+- Runtime 默认只监听 `127.0.0.1`，Pi 遥测默认关闭。
+- 调用模型或启用远程 MCP、Web 搜索和消息渠道时，必要数据会发送给你配置的第三方。
+- 常见凭据格式会在存储和展示边界脱敏，但这不能替代 DLP 或端到端加密。凭据保存在本机 Agent 数据目录，请妥善保护该目录和备份。
 
 <a id="desktop-pet"></a>
 
-## Desktop Pet
+## 桌面宠物
 
-Pisper supports [Petdex](https://petdex.dev)-compatible pets. Install and manage them under **Settings → Desktop pet**. See [`docs/petdex-integration.md`](./docs/petdex-integration.md).
+Pisper 支持 [Petdex](https://petdex.dev) 兼容宠物，可在 **设置 → 桌面宠物** 中安装和管理。详见 [`docs/petdex-integration.md`](./docs/petdex-integration.md)。
 
 <a id="install"></a>
 
-## Install
+## 安装
 
-### Desktop (Recommended)
+### 桌面版（推荐）
 
-Download a Windows, macOS, or Linux installer from [GitHub Releases](https://github.com/ling-kong-ran/pisper/releases/latest). It works out of the box — no separate Node.js install is required.
+前往 [GitHub Releases](https://github.com/ling-kong-ran/pisper/releases/latest) 下载 Windows、macOS 或 Linux 安装包，开箱即用，无需额外安装 Node.js。
 
-#### If macOS Refuses to Open Pisper
+#### macOS 无法打开
 
-Pisper is not currently notarized by Apple. Confirm that it came from the official Releases page, then select **Open Anyway** in **System Settings → Privacy & Security**. If that option is unavailable, run:
+Pisper 当前尚未经过 Apple 公证。请确认应用来自官方 Releases，并优先在 **系统设置 → 隐私与安全性** 中选择 **仍要打开**。若没有该选项，可执行：
 
 ```bash
 sudo xattr -rd com.apple.quarantine /Applications/Pisper.app
 ```
 
-Use this command only for Pisper downloaded from the official Releases page and placed in `/Applications`.
+请仅对从官方 Releases 下载并放入 `/Applications` 的应用使用此命令。
 
-#### If the Linux AppImage Does Not Start
+#### Linux AppImage 无法启动
 
 ```bash
 chmod +x Pisper_*_linux_x86_64.AppImage
 ./Pisper_*_linux_x86_64.AppImage
 ```
 
-If FUSE is missing, install `libfuse2` or `libfuse2t64`, or use the `.deb` package:
+缺少 FUSE 时安装 `libfuse2` 或 `libfuse2t64`，也可改用 `.deb`：
 
 ```bash
 sudo apt install ./Pisper-*-linux-amd64.deb
 ```
 
-### Component Updates
+### 分块更新
 
-**Settings → Updates** in the desktop app is the unified update entry point. A single **Check for updates** action checks the Desktop package, TUI client, and Runtime together. Install controls appear only for components with a newer version, so a small component update does not require downloading the full desktop installer. Each component uses an independent signed Release channel. Runtime updates take effect after restarting the app, and Pisper falls back to the versions bundled with the desktop package if an installed component is unavailable or fails to start.
+桌面端的 **设置 → 更新** 是统一更新入口。点击一次 **检查更新** 会同时检查 Desktop、TUI 客户端和 Runtime；只有发现新版本的组件才会显示安装操作，因此小范围更新不必重新下载完整桌面安装包。三个组件使用独立的签名 Release 通道，Runtime 更新在重启应用后生效；独立组件不可用或启动失败时，Pisper 会继续使用桌面安装包内置的版本。
 
 <a id="tui"></a>
 
-### Terminal Client (TUI)
+### 终端客户端（TUI）
 
-With Node.js 20+, you can install the Pisper CLI through npm. npm obtains the lightweight launcher, platform-independent Web frontend, and signed TUI and Runtime packages for the current platform from the configured registry, without downloading from GitHub Releases. Installation verifies and extracts the local component packages so Pisper is ready when the command returns; it does not install the desktop shell:
+使用 Node.js 20+ 时，也可通过 npm 安装 Pisper CLI。npm 会从当前配置的 registry 获取轻量启动器、平台无关 Web 前端以及当前平台的签名 TUI 与 Runtime 包，不再从 GitHub Releases 下载；安装过程会在本地完成验签和解压，命令返回后即可运行，不会安装桌面壳：
 
 ```bash
 npm install -g pisper --progress=true --foreground-scripts
 pisper
-pisper update --check  # check the complete distribution through the npm registry
-pisper update          # update the launcher, Web, TUI, and Runtime through npm
+pisper update --check  # 从 npm registry 检查完整发行版
+pisper update          # 通过 npm 更新 launcher、Web、TUI 与 Runtime
 ```
 
-Platform packages use the same registry when an npm mirror is configured. `--progress=true` shows npm download progress, while `--foreground-scripts` shows local signature verification and extraction; add `--loglevel=info` only when request and cache details are needed:
+使用 npm 镜像时，平台包会走同一个 registry。`--progress=true` 显示 npm 下载进度，`--foreground-scripts` 显示本地验签和解压阶段；需要查看请求和缓存明细时再增加 `--loglevel=info`：
 
 ```bash
 npm install -g pisper --registry=https://registry.npmmirror.com --progress=true --foreground-scripts
 ```
 
-After entering the TUI for the first time, use `/provider` to choose a Provider and edit its protocol, effective Base URL, and masked API key. The official default Base URL is shown when no override exists, and leaving API Key blank preserves the saved secret. `/model` lists only models from configured Providers. For a known Provider, `/provider <id>` skips the picker (`/apikey` remains a compatible alias). For visual configuration, run `pisper web`; Pisper uses the Web frontend bundled in the npm package and opens an authenticated, localhost-only settings page in your default browser. **Save Provider settings** does not change the default model; only **Set as default Provider** changes the default for later sessions.
+首次进入 TUI 后使用 `/provider` 选择 Provider，并编辑协议类型、当前生效 Base URL 和掩码 API Key；未自定义时会显示官方默认 Base URL，API Key 留空会保留原密钥。`/model` 只列出已配置 Provider 的模型。已知 Provider 可用 `/provider <id>` 直达（`/apikey` 为兼容别名）。需要可视化配置时，运行 `pisper web`，Pisper 会直接使用 npm 包内 Web 前端，并在默认浏览器打开仅监听本机的认证配置页。配置页中的 **保存 Provider 配置** 不会修改默认模型；只有点击 **设为默认 Provider** 才会切换后续会话的默认模型。
 
-After installing the desktop app, you can also install the `pisper` command from **Settings → App updates**. The first installation remains explicit; after later desktop updates restart Pisper, it automatically refreshes this managed terminal client:
+安装桌面版后，也可以在 **设置 → 应用更新** 中安装 `pisper` 命令。首次安装由你主动确认；之后桌面应用更新并重启时，Pisper 会自动刷新这份已托管的终端客户端：
 
 ```bash
-pisper                 # start a new conversation
-pisper resume          # resume from a list across all workspaces
-pisper doctor          # diagnose the runtime
-pisper web             # open Web settings
-pisper --help          # show complete onboarding and command help
+pisper                 # 新建会话
+pisper resume          # 从所有工作目录的交互列表中恢复会话
+pisper doctor          # 诊断运行环境
+pisper web             # 打开 Web 配置页
+pisper --help          # 查看完整上手和命令说明
 ```
 
-The npm distribution has one complete `pisper update` command. It uses the configured npm registry to update the launcher, Web, TUI, and Runtime; `pisper update --check` only queries and does not install, and component names are not accepted. The standalone TUI exposes no component-update command; the desktop distribution is managed through **Settings → App updates**. See the **[Pisper TUI user guide](./src-tui/README.en.md)** for installation, commands, keyboard controls, attachments, execution modes, and approvals.
+npm 安装版只有一个整体 `pisper update`，它使用当前配置的 npm registry 更新 launcher、Web、TUI 与 Runtime；`pisper update --check` 只查询而不安装，不接受组件名称。独立 TUI 不提供组件更新命令；桌面发行版统一由 **设置 → 应用更新** 管理。安装、命令、快捷键、附件、执行模式和审批说明见 **[Pisper TUI 使用指南](./src-tui/README.md)**。
 
-### Run from Source
+### 从源码运行
 
-Requires Node.js 20+, npm, and at least one model provider with an API key.
+需要 Node.js 20+、npm，以及至少一个模型 Provider 与 API Key。
 
 ```bash
 git clone https://github.com/ling-kong-ran/pisper.git
@@ -184,20 +184,20 @@ npm install
 npm run dev
 ```
 
-Desktop development and packaging:
+桌面开发与打包：
 
 ```bash
 npm run desktop:webview:dev
 npm run desktop:webview:build
 ```
 
-Data is stored under `~/.pisper/agent` by default. Set `PISPER_AGENT_DIR` to use another location.
+数据默认保存在 `~/.pisper/agent`，可通过 `PISPER_AGENT_DIR` 修改。
 
 <a id="development"></a>
 
-## Development
+## 开发
 
-Main stack: React, TypeScript, Tauri, Rust, Node SEA, and Pi Coding Agent.
+主要技术栈：React、TypeScript、Tauri、Rust、Node SEA 与 Pi Coding Agent。
 
 ```bash
 npm run check
@@ -205,20 +205,20 @@ npm test
 npm run build
 ```
 
-[Issues](https://github.com/ling-kong-ran/pisper/issues) and [pull requests](https://github.com/ling-kong-ran/pisper/pulls) are welcome. Do not commit API keys, bot credentials, or personal data from `~/.pisper/agent`.
+欢迎提交 [Issue](https://github.com/ling-kong-ran/pisper/issues) 与 [Pull Request](https://github.com/ling-kong-ran/pisper/pulls)。请勿提交 API Key、机器人凭据，或 `~/.pisper/agent` 中的个人数据。
 
 <a id="license"></a>
 
-## License
+## 许可
 
-Pisper is released under the [MIT License](./LICENSE). Third-party dependencies and community resources retain their own licenses.
+Pisper 采用 [MIT License](./LICENSE)。第三方依赖和社区资源遵循各自许可证。
 
-## Acknowledgments
+## 致谢
 
-Thanks to [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), [Petdex](https://petdex.dev), and the open-source software used by this project.
+感谢 [Pi Coding Agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)、[Petdex](https://petdex.dev) 及本项目使用的开源软件。
 
-Contributors:
+贡献者：
 
-- [@mik-myp](https://github.com/mik-myp) — Frontend TypeScript architecture, shadcn/ui / AI Elements, Zustand, and i18n refactor ([#1](https://github.com/ling-kong-ran/pisper/pull/1))
+- [@mik-myp](https://github.com/mik-myp) — 前端 TypeScript 架构、shadcn/ui / AI Elements、Zustand 与 i18n 重构（[#1](https://github.com/ling-kong-ran/pisper/pull/1)）
 
-<p align="right"><a href="#top">Back to top ↑</a></p>
+<p align="right"><a href="#top">返回顶部 ↑</a></p>

package/bin/pisper.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { ensurePisperInstallation } from '../lib/install.mjs'
+import { handleNpmHelp, handleNpmUpdate } from '../lib/npm-update.mjs'
+
+const frontendRoot = fileURLToPath(new URL('../web', import.meta.url))
+
+try {
+  const arguments_ = process.argv.slice(2)
+  if (!handleNpmHelp(arguments_) && !(await handleNpmUpdate(arguments_))) {
+    const installation = await ensurePisperInstallation()
+    const child = spawn(installation.executable, arguments_, {
+      env: {
+        ...process.env,
+        PISPER_APP_ROOT: installation.appRoot,
+        PISPER_DISTRIBUTION: 'npm',
+        PISPER_FRONTEND_ROOT: frontendRoot,
+        PISPER_RUNTIME_NODE: process.execPath,
+      },
+      stdio: 'inherit',
+      windowsHide: false,
+    })
+
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      process.on(signal, () => {
+        if (!child.killed) child.kill(signal)
+      })
+    }
+
+    child.once('error', (error) => {
+      console.error(`pisper: failed to start the terminal client: ${error.message}`)
+      process.exitCode = 1
+    })
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal)
+        return
+      }
+      process.exitCode = code ?? 1
+    })
+  }
+} catch (error) {
+  console.error(`pisper: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}