pi-web-ui 0.59.0 → 0.59.1

package/README.md

@@ -161,13 +161,36 @@ npm i -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latest
 
 ## Quick start
 
-**Start**
+**Start (foreground)**
 
 ```bash
 pi-web-ui                                           # foreground, http://localhost:8787
-PI_WEB_PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui     # custom port / workspace
 ```
 
+**Start flags & environment variables** — every setting can be passed as a `--flag` on the command
+line **or** set as an environment variable (flag wins). Pick whichever you prefer:
+
+| Flag | Env var | Default | Purpose |
+| --- | --- | --- | --- |
+| `--port <n>` | `PI_WEB_PORT` | `8787` | HTTP port |
+| `--cwd <dir>` | `PI_WEB_CWD` | current dir | workspace root (read/write/terminal) |
+| `--data-dir <dir>` | `PI_WEB_DATA_DIR` | `~/.pi-web` | data dir (sessions, plugins, uploads) |
+| `--engine <pi\|dsh>` | `PI_WEB_ENGINE` | `pi` | agent engine; `--engine dsh` = DeepSeek Harness |
+| `--host <addr>` | `PI_WEB_HOST` | `127.0.0.1` | listen address (`0.0.0.0` for LAN/Docker) |
+| `--agent-dir <dir>` | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi config dir (auth.json, models, skills) |
+| _env only_ | `PI_WEB_TOKEN` | empty | optional shared auth token |
+| _env only_ | `PI_WEB_DSH_*` | — | dsh runtime, patches & debug settings |
+
+The two are equivalent — pick one:
+
+```bash
+pi-web-ui --engine dsh --port 9000 --cwd /path/to/project
+PI_WEB_ENGINE=dsh PI_WEB_PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui
+```
+
+For the DSH engine also install the runtime (`npm i -g @deepseek-ai/dsh@0.1.1-rc.2`) and set a
+DeepSeek API key (read from `~/.pi/agent/auth.json`, set in the provider/API-key panel).
+
 **Stop**
 
 - **Foreground**: press `Ctrl+C` in the terminal running it.
@@ -213,9 +236,15 @@ socket drives `quiesce`/`unquiesce`.
 - **Windows** → Task Scheduler logon task (hidden PowerShell window, no black console)
 
 Options: `--port` (default 8787), `--cwd` (workspace), `--data-dir` (sessions),
-`--name` (custom service name). Rerunning `server install` with new options
-regenerates the config and restarts the service — that's how you change its
-port/cwd.
+`--engine <pi|dsh>`, `--host`, `--agent-dir`, `--name` (custom service name). Rerunning
+`server install` with new options regenerates the config and restarts the service — that's how
+you change its port/cwd/engine. `--engine` / `--host` / `--agent-dir` are baked into the service
+automatically; env-only vars (`PI_WEB_TOKEN`, `PI_WEB_DSH_*`) must be added to the service config
+by hand. See the [start flags table](#quick-start) above.
+
+```bash
+pi-web-ui server install --engine dsh --port 9000 --cwd /path/to/project
+```
 
 
 ## Plugins

package/README.zh-CN.md

@@ -119,11 +119,36 @@ npm i -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latest
 
 ## 启动
 
+**前台启动**
+
 ```bash
 pi-web-ui                                           # 前台，http://localhost:8787
-PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui     # 自定义端口 / 工作目录
 ```
 
+**启动参数 & 环境变量** —— 每个设置既能用命令行的 `--flag` 传，也能用环境变量设（flag 优先）。
+二者任选一种即可：
+
+| 参数 | 环境变量 | 默认 | 作用 |
+| --- | --- | --- | --- |
+| `--port <n>` | `PI_WEB_PORT` | `8787` | HTTP 端口 |
+| `--cwd <dir>` | `PI_WEB_CWD` | 当前目录 | 工作区根（读/写/终端） |
+| `--data-dir <dir>` | `PI_WEB_DATA_DIR` | `~/.pi-web` | 数据目录（会话/插件/上传） |
+| `--engine <pi\|dsh>` | `PI_WEB_ENGINE` | `pi` | 智能体引擎；`--engine dsh` = DeepSeek Harness |
+| `--host <addr>` | `PI_WEB_HOST` | `127.0.0.1` | 监听地址（`0.0.0.0` 供局域网/Docker） |
+| `--agent-dir <dir>` | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi 配置目录（auth.json、模型、技能） |
+| _仅环境变量_ | `PI_WEB_TOKEN` | 空 | 可选共享鉴权口令 |
+| _仅环境变量_ | `PI_WEB_DSH_*` | — | dsh 运行时、补丁与调试设置 |
+
+两者等价 —— 任选其一：
+
+```bash
+pi-web-ui --engine dsh --port 9000 --cwd /path/to/project
+PI_WEB_ENGINE=dsh PI_WEB_PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui
+```
+
+若用 dsh 引擎，需先安装运行时（`npm i -g @deepseek-ai/dsh@0.1.1-rc.2`）并准备 DeepSeek API key
+（读 `~/.pi/agent/auth.json`，在服务商/API key 面板设置）。
+
 ## 停止
 
 - **前台**：在运行它的终端里按 `Ctrl+C`。
@@ -167,8 +192,14 @@ pi-web-ui server unquiesce                  # 解除排空，恢复接收新工
 - **Windows** → 计划任务（登录自启，隐藏 PowerShell 窗口，无黑窗）
 
 选项：`--port`（默认 8787）、`--cwd`（工作目录）、`--data-dir`（会话目录）、
-`--name`（自定义服务名）。重复执行 `server install` 并传入新选项即可重新生成配置
-并重启服务 —— 这就是修改已装服务端口/工作目录的方式。
+`--engine <pi|dsh>`、`--host`、`--agent-dir`、`--name`（自定义服务名）。重复执行 `server install`
+并传入新选项即可重新生成配置并重启服务 —— 这就是修改已装服务端口/工作目录/引擎的方式。
+`--engine` / `--host` / `--agent-dir` 会自动烘焙进服务；仅环境变量的（`PI_WEB_TOKEN`、
+`PI_WEB_DSH_*`）需手动写进服务配置。见上方「启动参数 & 环境变量」表。
+
+```bash
+pi-web-ui server install --engine dsh --port 9000 --cwd /path/to/project
+```
 
 ## 界面插件
 

package/bin/pi-web-ui.mjs

@@ -3,7 +3,7 @@
  * pi-web-ui CLI.
  *
  *   pi-web-ui                              启动生产服务器（前台，Ctrl+C 停止，自动打开浏览器）
- *   pi-web-ui --port 9000 --cwd /path      同上，覆盖端口 / 工作目录 / 数据目录
+ *   pi-web-ui --engine dsh --port 9000 --cwd /path    同上，覆盖引擎/端口/工作目录/数据目录
  *   pi-web-ui --no-browser                 启动但不自动打开浏览器
  *   pi-web-ui --version | --help
  *   pi-web-ui server install [选项]         安装系统服务（开机自启）并启动
@@ -21,8 +21,8 @@
  *              PowerShell 启动脚本 / VBS 启动器 / PID 文件生成在
  *              %APPDATA%\pi-web-ui\
  *
- * 环境变量（前台与系统服务均适用）：PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR /
- * PI_CODING_AGENT_DIR。
+ * 环境变量（flag 优先，环境变量后备）：PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR /
+ * PI_WEB_ENGINE / PI_WEB_HOST / PI_CODING_AGENT_DIR；token 仅环境变量，不走命令行。
  */
 import { spawn, spawnSync } from "node:child_process";
 import { createConnection } from "node:net";
@@ -66,7 +66,7 @@ const HELP = `pi-web-ui v${pkg.version} — web chat for the pi coding agent
 
 用法:
   pi-web-ui                               启动服务器（前台，Ctrl+C 停止，自动打开浏览器）
-  pi-web-ui --port 9000 --cwd /path       启动并指定端口 / 工作目录 / 数据目录
+  pi-web-ui --engine dsh --port 9000 --cwd /path      启动并指定引擎 / 端口 / 工作目录 / 数据目录
   pi-web-ui --no-browser                  启动但不自动打开浏览器
   pi-web-ui server install [选项]         安装系统服务（开机自启）并启动
   pi-web-ui server shortcut [选项]        在桌面创建「一键启动」图标（启动服务并打开浏览器）
@@ -80,6 +80,9 @@ server 选项:
   --port <n>        端口（默认 8787，或 $PI_WEB_PORT）
   --cwd <dir>       工作目录（默认 $PI_WEB_CWD 或用户主目录；前台启动默认当前目录）
   --data-dir <dir>  会话数据目录（默认 <cwd>/.pi-web）
+  --engine <pi|dsh> 智能体引擎（默认 $PI_WEB_ENGINE 或 pi）
+  --host <addr>     监听地址（默认 $PI_WEB_HOST 或 127.0.0.1；0.0.0.0 供局域网/容器）
+  --agent-dir <dir> pi 配置目录（默认 $PI_CODING_AGENT_DIR 或 ~/.pi/agent）
   --name <name>     服务名（默认 pi-web-ui；macOS 的 launchd label
                     为 com.xingshuyin.pi-web-ui，自定义名时为 com.<name>.server）
   --print           只打印将生成的配置文件，不实际安装
@@ -100,8 +103,10 @@ server 选项:
                 --data-dir <dir> 数据目录（默认 ~/.pi-web）
                 --force 目标已存在时覆盖
 
-环境变量（前台与系统服务均适用）:
-  PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_CODING_AGENT_DIR
+环境变量（flag 优先，环境变量后备）:
+  PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_WEB_ENGINE / PI_WEB_HOST /
+  PI_CODING_AGENT_DIR。
+  鉴权口令 PI_WEB_TOKEN：仅环境变量（不走命令行，避免被 ps 看到），需要时手动加入服务配置。
 `;
 
 /** Minimum Node required by the pi SDK (its dist uses `import … with { type: "json" }`). */
@@ -143,6 +148,9 @@ function parseFlags(argv) {
 		cwd: undefined,
 		dataDir: undefined,
 		name: undefined,
+		engine: undefined,
+		host: undefined,
+		agentDir: undefined,
 		print: false,
 		noBrowser: false,
 		force: false,
@@ -174,6 +182,15 @@ function parseFlags(argv) {
 			case "--data-dir":
 				opts.dataDir = take("--data-dir");
 				break;
+			case "--engine":
+				opts.engine = take("--engine");
+				break;
+			case "--host":
+				opts.host = take("--host");
+				break;
+			case "--agent-dir":
+				opts.agentDir = take("--agent-dir");
+				break;
 			case "--name":
 				opts.name = take("--name");
 				break;
@@ -261,6 +278,12 @@ async function startForeground(opts) {
 	if (opts.port) process.env.PI_WEB_PORT = opts.port;
 	if (opts.cwd) process.env.PI_WEB_CWD = resolve(opts.cwd);
 	if (opts.dataDir) process.env.PI_WEB_DATA_DIR = resolve(opts.dataDir);
+	if (opts.engine) {
+		if (opts.engine !== "pi" && opts.engine !== "dsh") fail(`无效引擎: ${opts.engine}（仅支持 pi / dsh）`);
+		process.env.PI_WEB_ENGINE = opts.engine;
+	}
+	if (opts.host) process.env.PI_WEB_HOST = opts.host;
+	if (opts.agentDir) process.env.PI_CODING_AGENT_DIR = resolve(opts.agentDir);
 	const url = `http://localhost:${effectivePort(opts)}`;
 	await import(pathToFileURL(SERVER_ENTRY).href);
 	if (!opts.noBrowser) openBrowserWhenUp(url);
@@ -563,8 +586,8 @@ function buildWinHiddenVbs(ps1Path) {
  * -WindowStyle Hidden so nothing flashes on double-click.
  */
 function installWinShortcut(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
-	const env = serviceEnv(port, cwd, dataDir);
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
+	const env = serviceEnv(port, cwd, dataDir, engine, host, agentDir);
 	const url = `http://localhost:${port}`;
 	const ps1Path = winShortcutPs1Path(name);
 	const ps1 = buildWinShortcutPs1(
@@ -668,13 +691,13 @@ if [ -n "\${SERVER_PID:-}" ]; then wait "$SERVER_PID"; fi
 }
 
 function installMacShortcut(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
 	const url = `http://localhost:${port}`;
 	const script = buildMacShortcut(
 		serviceLabel(name),
 		launchAgentPlist(name),
 		url,
-		serviceEnv(port, cwd, dataDir),
+		serviceEnv(port, cwd, dataDir, engine, host, agentDir),
 	);
 	const path = join(homedir(), "Desktop", SHORTCUT_MAC_NAME);
 	if (opts.print) {
@@ -726,7 +749,7 @@ if [ -n "\${SERVER_PID:-}" ]; then wait "$SERVER_PID"; fi
 }
 
 function installLinuxShortcut(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
 	const url = `http://localhost:${port}`;
 	const scriptDir = join(homedir(), ".local", "share", "pi-web-ui");
 	const scriptPath = join(scriptDir, `${name}-start.sh`);
@@ -978,10 +1001,17 @@ function serviceOptions(opts) {
 	} else if (process.env.PI_WEB_DATA_DIR) {
 		dataDir = resolve(process.env.PI_WEB_DATA_DIR);
 	}
-	return { name, port, cwd, dataDir };
+	// 引擎/监听地址/agent 配置目录：flag 优先，环境变量后备（token 不走命令行，仅环境变量）。
+	const engine = opts.engine ?? process.env.PI_WEB_ENGINE ?? "pi";
+	if (engine !== "pi" && engine !== "dsh") fail(`无效引擎: ${engine}（仅支持 pi / dsh）`);
+	const host = opts.host ?? process.env.PI_WEB_HOST;
+	const agentDir = opts.agentDir
+		? resolve(opts.agentDir)
+		: process.env.PI_CODING_AGENT_DIR;
+	return { name, port, cwd, dataDir, engine, host, agentDir };
 }
 
-function serviceEnv(port, cwd, dataDir) {
+function serviceEnv(port, cwd, dataDir, engine, host, agentDir) {
 	const env = {
 		PI_WEB_PORT: port,
 		PI_WEB_CWD: cwd,
@@ -996,14 +1026,17 @@ function serviceEnv(port, cwd, dataDir) {
 	if (!isWin && process.env.LANG) env.LANG = process.env.LANG;
 	if (!isWin && process.env.LC_ALL) env.LC_ALL = process.env.LC_ALL;
 	if (dataDir) env.PI_WEB_DATA_DIR = dataDir;
+	if (engine === "dsh") env.PI_WEB_ENGINE = "dsh"; // 仅非默认引擎才烘焙，保持服务单元简洁
+	if (host) env.PI_WEB_HOST = host;
+	if (agentDir) env.PI_CODING_AGENT_DIR = agentDir;
 	return env;
 }
 
 function installLaunchd(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
 	const label = serviceLabel(name);
 	const plist = launchAgentPlist(name);
-	const content = buildPlist(label, cwd, serviceEnv(port, cwd, dataDir));
+	const content = buildPlist(label, cwd, serviceEnv(port, cwd, dataDir, engine, host, agentDir));
 	if (opts.print) {
 		console.log(`# ${plist}\n${content}`);
 		return;
@@ -1026,8 +1059,8 @@ function installLaunchd(opts) {
 }
 
 function installSystemd(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
-	const content = buildUnit(cwd, serviceEnv(port, cwd, dataDir));
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
+	const content = buildUnit(cwd, serviceEnv(port, cwd, dataDir, engine, host, agentDir));
 	const unitPath = systemdUnitPath(name);
 	if (opts.print) {
 		console.log(`# ${unitPath}\n${content}`);
@@ -1075,8 +1108,8 @@ function uninstallSystemd(opts) {
 }
 
 function installWindows(opts) {
-	const { name, port, cwd, dataDir } = serviceOptions(opts);
-	const env = serviceEnv(port, cwd, dataDir);
+	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
+	const env = serviceEnv(port, cwd, dataDir, engine, host, agentDir);
 	const ps1Path = winPs1Path(name);
 	const vbsPath = winVbsPath(name);
 	const pidPath = winPidFilePath(name);

package/dist/server/index.js

@@ -105,13 +105,16 @@ function tokenOk(req) {
     return requestTokens(req).includes(AUTH_TOKEN);
 }
 if (AUTH_TOKEN) {
-    // /api/health 保持开放：无敏感信息，容器/监控探针需要它
+    // /api/health 保持开放：无敏感信息，容器/监控探针需要它。
+    // 但绝不能因命中 /api/health 就反射下发真实 token cookie（安全漏洞）。
     app.use((req, res, next) => {
-        if (req.path === "/api/health" || tokenOk(req)) {
-            // 浏览器经 ?token= 首次进入后下发 HttpOnly cookie，后续导航/资源请求免带参数
-            if (!req.headers.cookie?.includes("pi_web_token=")) {
-                res.setHeader("Set-Cookie", `pi_web_token=${encodeURIComponent(AUTH_TOKEN)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=31536000`);
-            }
+        const ok = tokenOk(req);
+        // 浏览器经 ?token= 首次进入后下发 HttpOnly cookie，后续导航/资源请求免带参数；
+        // 只有请求确实携带着有效 token 时才下发——匿名命中 /api/health 不触发。
+        if (ok && !req.headers.cookie?.includes("pi_web_token=")) {
+            res.setHeader("Set-Cookie", `pi_web_token=${encodeURIComponent(AUTH_TOKEN)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=31536000`);
+        }
+        if (req.path === "/api/health" || ok) {
             next();
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-ui",
-  "version": "0.59.0",
+  "version": "0.59.1",
   "description": "Web chat interface for the pi coding agent, powered by the pi SDK (@earendil-works/pi-coding-agent) — one-command run, Docker/systemd/launchd deployable",
   "license": "MIT",
   "author": {