oh-my-agent-web 1.0.1 → 1.0.3

package/README.en.md

@@ -78,15 +78,21 @@ The three commands are completely equivalent; everything below is written as `oh
 
 | Command | What it does |
 |---|---|
-| `oh-my-agent-web` | **Start (default)**: runs in the background and opens the browser, handing the terminal straight back; default workspace = current directory |
-| `oh-my-agent-web start -f` | Run in the foreground, logs right in the terminal, `Ctrl-C` to quit |
+| `oh-my-agent-web` | **Start (default)**: runs in the foreground and opens the browser, logs right in the terminal, `Ctrl-C` to quit; default workspace = current directory |
+| `oh-my-agent-web start -d` | Run in the background (detached, logs go to `daemon.log`), handing the terminal straight back |
 | `oh-my-agent-web status` | pid / port / uptime / engine / session count / workspace |
-| `oh-my-agent-web restart` | Stop then start (background by default; `-f` for foreground) |
+| `oh-my-agent-web restart` | Stop then start (foreground by default; `-d` for background) |
 | `oh-my-agent-web stop` | Stop the running instance (foreground or background — it reads the lock file in the data dir instead of guessing a port) |
 | `oh-my-agent-web version` | Version string (`-v` / `--version` are synonyms) |
 | `oh-my-agent-web upgrade` | Upgrade to the latest release (it runs `npm -g install oh-my-agent-web@latest`) |
 | `oh-my-agent-web help` | Show help (`-h` / `--help` are synonyms) |
 
+Two behavioural rules:
+
+- **Starting twice is detected first**: if an instance is already running it only prints the URL (and opens the page) instead of starting a second one — identical for `aw` / `agent-web` / `oh-my-agent-web`.
+- **The foreground run stays quiet**: the terminal only gets one `已启动：…` line plus warn / error; normal logs (session index loading, SSE connections) still go in full to `logs/agent-web.log`. Watch them with `AGENT_WEB_LOG=info aw`; in the background (`-d`) they land in `daemon.log`.
+- **It checks for a newer release**: on start (and on `aw status`) it asks npm once per 24 hours (cached in `update-check.json`) and prints `有新版本 vX（当前 vY）→ 升级：aw upgrade` when one exists. It never upgrades by itself, stays silent when the network is down, and `AGENT_WEB_UPDATE_CHECK=off` turns it off.
+
 ### Flags
 
 | Flag | Env var | Default | Notes |
@@ -94,7 +100,7 @@ The three commands are completely equivalent; everything below is written as `oh
 | `-p, --port` | `AGENT_WEB_PORT` | `25257` | Listen port |
 | `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | Listen address; only change it for remote access |
 | `-P, --password` | `AGENT_WEB_PASSWORD` | none | Login password; unset = loopback only (a remote first visit asks you to set one) |
-| `-f, --foreground` | — | off (background by default) | Foreground run, logs in the terminal; `-d` / `--detach` is the old spelling and now equals the default |
+| `-d, --detach` | — | off (foreground by default) | Background run, detached, logs go to `~/.oh-my-agent-web/daemon.log`; `-f` / `--foreground` is the old spelling and now equals the default |
 | `--no-open` | — | on | Don't open the browser |
 | `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | loopback only | Extra allowed hostnames / LAN IPs (repeatable or comma-separated) |
 | `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | Settings, password, uploads, logs and the lock file live here |
@@ -102,13 +108,14 @@ The three commands are completely equivalent; everything below is written as `oh
 | — | `AGENT_WEB_ENGINE` | `pi` | Default engine |
 | — | `AGENT_WEB_APPROVAL_MODE` | `allow` | Default approval mode for new sessions; `ask` confirms every tool call |
 | — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 minutes | Per-turn watchdog timeout |
-| — | `AGENT_WEB_LOG` | `info` | `debug` / `info` / `warn` / `error` |
+| — | `AGENT_WEB_LOG` | `info` (foreground terminal: warn / error only) | `debug` / `info` / `warn` / `error`; setting it explicitly also prints that level to the terminal |
+| — | `AGENT_WEB_UPDATE_CHECK` | `on` | `off` disables the startup release check (offline / intranet / CI) |
 
 ### Common examples
 
 ```bash
-oh-my-agent-web                                    # background + open the page (the usual one)
-oh-my-agent-web -f                                 # foreground, logs in your face, Ctrl-C to quit
+oh-my-agent-web                                    # foreground + open the page (the usual one, Ctrl-C to quit)
+oh-my-agent-web -d                                 # background, terminal handed straight back
 oh-my-agent-web -p 25258                           # different port (when 25257 is taken)
 oh-my-agent-web status && oh-my-agent-web restart  # check, then restart
 oh-my-agent-web stop                               # stop it (works for foreground and background)

package/README.md

@@ -77,15 +77,21 @@ powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/m
 
 | 命令 | 作用 |
 |---|---|
-| `oh-my-agent-web` | **启动（默认）**：后台跑起来 + 打开浏览器，终端立刻还给你；默认工作区 = 当前目录 |
-| `oh-my-agent-web start -f` | 前台运行，日志直接打在终端，`Ctrl-C` 退出 |
+| `oh-my-agent-web` | **启动（默认）**：前台跑起来 + 打开浏览器，日志直接打在终端，`Ctrl-C` 退出；默认工作区 = 当前目录 |
+| `oh-my-agent-web start -d` | 后台运行（脱离终端，日志进 `daemon.log`），终端立刻还给你 |
 | `oh-my-agent-web status` | 看状态：pid / 端口 / 已运行多久 / 引擎 / 会话数 / 工作区 |
-| `oh-my-agent-web restart` | 先停再起（默认仍后台；带 `-f` 则前台） |
+| `oh-my-agent-web restart` | 先停再起（默认仍前台；带 `-d` 则后台） |
 | `oh-my-agent-web stop` | 停掉正在跑的实例（前台、后台都行 —— 读的是数据目录里的锁文件，不靠猜端口） |
 | `oh-my-agent-web version` | 版本号（`-v` / `--version` 同义） |
 | `oh-my-agent-web upgrade` | 升级到最新发行版（内部就是 `npm -g install oh-my-agent-web@latest`） |
 | `oh-my-agent-web help` | 显示帮助（`-h` / `--help` 同义） |
 
+两条行为约定：
+
+- **重复启动会先检测**：已经在跑就只把地址打给你（并打开页面），不会再起第二个 —— `aw` / `agent-web` / `oh-my-agent-web` 三个名字完全一致。
+- **前台不刷日志**：终端只有一行「已启动：…」和 warn / error；装载会话索引、SSE 连接这类正常日志仍然全量写进 `logs/agent-web.log`。想盯着看就 `AGENT_WEB_LOG=info aw`，后台（`-d`）的输出在 `daemon.log`。
+- **会顺手查新版**：启动时（以及 `aw status`）看一眼 npm 上有没有新版本，24 小时内只问一次（缓存 `update-check.json`）；有新版就打一行 `有新版本 vX（当前 vY）→ 升级：aw upgrade`。不自动升级、网络不通就静默跳过，`AGENT_WEB_UPDATE_CHECK=off` 可彻底关掉。
+
 ### 参数
 
 | 参数 | 环境变量 | 默认 | 说明 |
@@ -93,7 +99,7 @@ powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/m
 | `-p, --port` | `AGENT_WEB_PORT` | `25257` | 监听端口 |
 | `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | 监听地址；对外访问才需要改 |
 | `-P, --password` | `AGENT_WEB_PASSWORD` | 无 | 访问密码；不设 = 只允许本机（远程首次打开会先让你设） |
-| `-f, --foreground` | — | 关（默认后台） | 前台运行，日志打在终端；`-d` / `--detach` 是旧写法，现在等于默认 |
+| `-d, --detach` | — | 关（默认前台） | 后台运行，脱离终端，日志进 `~/.oh-my-agent-web/daemon.log`；`-f` / `--foreground` 是旧写法，现在等于默认 |
 | `--no-open` | — | 开 | 不在浏览器里打开页面 |
 | `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | 只认 loopback | 额外允许的域名 / 局域网 IP（可多次或逗号分隔） |
 | `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | 设置、密码、上传、日志、锁文件都放这 |
@@ -101,13 +107,14 @@ powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/m
 | — | `AGENT_WEB_ENGINE` | `pi` | 默认引擎 |
 | — | `AGENT_WEB_APPROVAL_MODE` | `allow` | 新会话默认审批模式；`ask` 则逐次确认 |
 | — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 分钟 | 单回合看门狗超时 |
-| — | `AGENT_WEB_LOG` | `info` | `debug` / `info` / `warn` / `error` |
+| — | `AGENT_WEB_LOG` | `info`（前台终端只打 warn / error） | `debug` / `info` / `warn` / `error`；显式设了就按这个级别打到终端 |
+| — | `AGENT_WEB_UPDATE_CHECK` | `on` | `off` 关掉启动时的升级检查（离线 / 内网 / CI 用） |
 
 ### 常用例子
 
 ```bash
-oh-my-agent-web                                    # 后台起 + 打开页面（最常用）
-oh-my-agent-web -f                                 # 前台起，日志直接看，Ctrl-C 退出
+oh-my-agent-web                                    # 前台起 + 打开页面（最常用，Ctrl-C 退出）
+oh-my-agent-web -d                                 # 后台起，终端立刻还给你
 oh-my-agent-web -p 25258                           # 换端口（25257 被占时）
 oh-my-agent-web status && oh-my-agent-web restart  # 看完状态再重启
 oh-my-agent-web stop                               # 停掉（前台/后台都行）

package/dist/server/cli.js

@@ -15,11 +15,11 @@
  *   -P, --password <pwd>  AGENT_WEB_PASSWORD   非本机访问时的登录密码
  *       --allow-host <h>  AGENT_WEB_ALLOWED_HOSTS  额外允许的域名（可重复）
  *       --data-dir <dir>  AGENT_WEB_DATA_DIR   默认 ~/.oh-my-agent-web
- *   -f, --foreground      前台运行（日志直接在终端，Ctrl-C 退出）
- *   -d, --detach          后台运行（**现在就是默认**，留着给老脚本）
+ *   -d, --detach          后台运行（脱离终端，日志进 daemon.log）
+ *   -f, --foreground      前台运行（就是默认，留着给老脚本）
  *       --no-open         不要在浏览器里打开页面
  *
- * 默认行为：**后台起来 + 打开浏览器**（终端立刻还给你）；`-f` 才留在前台。
+ * 默认行为：**前台起来 + 打开浏览器**（日志直接打在终端，Ctrl-C 退出）；`-d` 才丢到后台。
  * 后台模式只是「spawn 一个脱离终端的自己 + 等它写好 server.lock」：
  * 真正的事实源仍然是锁文件，所以 stop / restart 对前台、后台一视同仁。
  *
@@ -36,14 +36,15 @@ import { applyStoredOptions } from "./cli-config.js";
 import { migrateLegacyDataDir } from "./util/data-dir.js";
 import { DEFAULT_DATA_DIR_NAME } from "./util/env.js";
 import { fetchHealth, showStatus, showVersion, upgrade } from "./cli-info.js";
-import { defaultIsAlive, readLock } from "./session/lock.js";
+import { checkForUpdate, describeUpdate } from "./update-check.js";
+import { defaultIsAlive, describeHolder, readLock } from "./session/lock.js";
 const USAGE = `用法: agent-web [命令] [选项]        （agent-web / aw / oh-my-agent-web 三个命令完全等价）
 
 命令:
-  start              启动（默认；后台运行并打开页面，终端立刻还给你）
-  start -f           前台运行（日志直接打在终端，Ctrl-C 退出）
+  start              启动（默认前台；已在跑就只把地址给你，不会再起一个）
+  start -d           后台运行（脱离终端，日志进 daemon.log，终端立刻还给你）
   stop               停止正在跑的实例（读 dataDir/server.lock 里的 pid）
-  restart            先停再起（默认仍后台；带 -f 则前台）
+  restart            先停再起（默认仍前台；带 -d 则后台）
   status             看状态：pid / 端口 / 已运行多久 / 引擎 / 会话数 / 工作区
   version            看版本号（-v / --version 同义）
   upgrade            升级全局安装（npm i -g <包名>@latest；private 包会拒绝并提示怎么做）
@@ -55,24 +56,24 @@ const USAGE = `用法: agent-web [命令] [选项]        （agent-web / aw / oh
   -P, --password <pwd> 访问密码            AGENT_WEB_PASSWORD
       --allow-host <h> 额外允许的域名      AGENT_WEB_ALLOWED_HOSTS（可多次 / 逗号分隔）
       --data-dir <dir> 数据目录            AGENT_WEB_DATA_DIR（默认 ~/.oh-my-agent-web）
-  -f, --foreground     前台运行（Ctrl-C 退出）
-  -d, --detach         后台运行（现在就是默认，留着给老脚本）
+  -d, --detach         后台运行（脱离终端；日志见 daemon.log）
+  -f, --foreground     前台运行（就是默认，留着给老脚本）
       --no-open        不要在浏览器里打开页面
 
 没给 --password / --allow-host 时，会读数据目录里的 password / allowed-hosts 兜底
 （设一次就一直在，重启不必重复输入）。远程第一次打开时若还没设密码，页面会让你先设一个。
 
 例：
-  aw                                                    # 后台起 + 打开页面
-  aw -f                                                 # 前台起（Ctrl-C 退出）
-  aw -H 0.0.0.0 --allow-host agent.example.com           # 后台起，供外网访问（首次打开会先让你设密码）
+  aw                                                    # 前台起 + 打开页面（Ctrl-C 退出）
+  aw -d                                                 # 后台起，终端立刻还给你
+  aw -H 0.0.0.0 --allow-host agent.example.com           # 供外网访问（首次打开会先让你设密码）
   aw status && aw restart                               # 看完状态再重启
   aw stop                                               # 停掉（前台/后台都行）`;
 function parseArgs(argv) {
     const env = {};
     let command = "start";
     let help = false;
-    let foreground = false;
+    let foreground = true;
     let open = true;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? "";
@@ -334,7 +335,8 @@ async function startDetached(rawArgv, open) {
     const child = spawn(process.execPath, [script, ...args], {
         detached: true, // 脱离当前终端：关掉终端不会把它一起收走
         stdio: ["ignore", fd, fd],
-        env: process.env,
+        // 子进程的 stdout 是 daemon.log：别让 quietConsole 把它的正常日志吞了（那是后台模式唯一的现场）
+        env: { ...process.env, AGENT_WEB_FOREGROUND: "0" },
         cwd: process.cwd(),
         // Windows 上 detached 会连带开一个 console：不关掉就会闪一下黑框
         windowsHide: true,
@@ -369,6 +371,48 @@ async function startDetached(rawArgv, open) {
     console.error(tailOf(log, 20));
     process.exitCode = 1;
 }
+/**
+ * 起来之前先看锁（ADR-0007）：已经有一个在跑，就不起第二个。
+ *
+ * 为什么放在 CLI 而不是只靠 `index.ts` 里的 `acquireLock`：那边要先把会话索引、价格表
+ * 都装完才走到拿锁那一步 —— 用户敲完 `aw` 干等几秒，最后看到一条 error；`-d` 更糟，
+ * 父进程发现子进程退出，只能甩一段 daemon.log 出来。
+ *
+ * 三个命令名（`aw` / `agent-web` / `oh-my-agent-web`）本来就走同一份 cli.js，
+ * 所以这一处检测对三者完全一致。
+ *
+ * @returns true = 已经有一个在跑，本次不再启动
+ */
+async function detectRunning(open) {
+    const lock = await readLock(dataDir());
+    // 无锁 / 锁里的 pid 已经不在（陈旧锁）：照常启动，接管交给 index.ts 的 acquireLock
+    if (!lock || !defaultIsAlive(lock.pid))
+        return false;
+    const probeHost = probeHostOf();
+    const url = `http://${probeHost}:${lock.port}`;
+    const stop = stopHint(process.argv.slice(2));
+    if (await fetchHealth(probeHost, lock.port, 1500)) {
+        console.log(`已经有一个在跑，不再起第二个：\n  ${describeHolder(lock)}\n  → 打开 ${url}\n  → 停止：${stop}`);
+        if (open)
+            openBrowser(url);
+        return true;
+    }
+    // 锁在、pid 也在，但端口不响应：可能还在启动（装会话索引），也可能卡死了。
+    // 两种情况都不该再起一个 —— 那样只会在拿锁/绑端口时撞得莫名其妙。
+    console.error(`已经有一个在跑，但 ${url} 暂时没响应：\n  ${describeHolder(lock)}`);
+    console.error(`  → 还在启动就等一下；卡住了就收掉它：${stop}`);
+    process.exitCode = 1;
+    return true;
+}
+/** 用户敲的是哪个名字（aw / agent-web / oh-my-agent-web）：启动提示里照拄，不硬写 aw */
+function invokedName() {
+    const base = (process.argv[1] ?? "").split(/[\\/]/).pop() ?? "";
+    // 直接用 node 跑文件（开发、脚本、npx）时 argv[1] 是 cli.js / cli.ts，没有任何命令名可用
+    if (base === "" || base === "cli.js" || base === "cli.ts")
+        return "aw";
+    // Windows 上 npm 的 bin 是 .cmd（aw.cmd）
+    return base.replace(/\.(cmd|exe|ps1|bat)$/i, "");
+}
 /** 是否被当脚本执行（npx / 全局安装时 argv[1] 是 bin 软链，必须比 realpath） */
 function invokedDirectly() {
     const entry = process.argv[1];
@@ -394,6 +438,9 @@ async function main() {
     await applyStoredOptions(process.env, dataDir());
     if (parsed.command === "status") {
         await showStatus({ dataDir: dataDir(), probeHost: probeHostOf() });
+        const line = describeUpdate(await checkForUpdate({ dataDir: dataDir() }).catch(() => null));
+        if (line)
+            console.log(`  ${line}`);
         return;
     }
     if (parsed.command === "version") {
@@ -413,14 +460,31 @@ async function main() {
         // 等端口真正释放再起，否则会撞 EADDRINUSE
         await sleep(400);
     }
-    // start / restart：默认**后台**跑（终端立刻还给你），`-f` 才留在前台
+    // start / restart：先确认不是「已经在跑了」（三个命令名共用这一处检测）
+    if (await detectRunning(parsed.open))
+        return;
+    // 顺手查一下有没有新版：启动时就并发问，别让它拖启动（缓存 24h，首次最多 1.5s 超时）
+    const update = checkForUpdate({ dataDir: dataDir() }).catch(() => null);
+    // start / restart：默认**前台**跑（日志直接打在终端，Ctrl-C 退出），`-d` 才丢到后台
     if (!parsed.foreground) {
         await startDetached(process.argv.slice(2), parsed.open);
+        const line = describeUpdate(await update);
+        if (line)
+            console.log(line);
         return;
     }
     if (parsed.open)
         openWhenReady();
+    // 告诉服务层「终端在看着」：只留 warn / error，正常日志光进文件（见 index.ts 的 quietConsole）。
+    // 必须看 isTTY：后台子进程也走这个分支，但它的 stdout 是 daemon.log —— 那里要保留全部日志。
+    if (process.stdout.isTTY)
+        process.env.AGENT_WEB_FOREGROUND = "1";
+    // 启动提示里的命令名（aw / agent-web / oh-my-agent-web）由实际敲的那个决定
+    process.env.AGENT_WEB_CLI_NAME = invokedName();
     await import("./index.js");
+    const line = describeUpdate(await update);
+    if (line)
+        console.log(line);
 }
 // 被当脚本执行时才 main（被 import 时什么都不做）
 if (invokedDirectly()) {

package/dist/server/engine/builtin.js

@@ -31,6 +31,7 @@ export function createBuiltinEngineRegistry(options) {
                     options.onNotice(text, level);
                 },
                 ...(options.skillPaths ? { skillPaths: options.skillPaths } : {}),
+                ...(options.thinkCount ? { thinkCount: options.thinkCount } : {}),
             }),
         },
         ...(options.codex
@@ -63,6 +64,7 @@ export function createBuiltinEngineRegistry(options) {
                         client: options.codex?.client,
                         log: options.onLog,
                         ...(options.codex?.subagentPolicy ? { subagentPolicy: options.codex.subagentPolicy } : {}),
+                        ...(options.thinkCount ? { thinkCount: options.thinkCount } : {}),
                     }),
                 },
             ]

package/dist/server/engine/codex.js

@@ -3,6 +3,7 @@ import { createCodexClient } from "./codex-transport.js";
 import { codexMultiAgentConfig, codexSubagentGuidance, createCodexSubagents } from "./codex-subagents.js";
 import { registerCodexApprovals } from "./codex-approvals.js";
 import { sanitizeHistoricalActions } from "../markers/actions.js";
+import { suggestionGuidance } from "./suggestion-guidance.js";
 import { ensureCodexProject } from "./codex-sessions.js";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -295,14 +296,15 @@ export function createCodexEngine(options = {}) {
                         }))
                         : [],
                 }),
-                ...(codexSubagentGuidance({ enabled: plan.enabled, profiles: plan.profiles })
-                    ? {
-                        developerInstructions: codexSubagentGuidance({
-                            enabled: plan.enabled,
-                            profiles: plan.profiles,
-                        }),
-                    }
-                    : {}),
+                // 「下一步建议」的写法一直带（ADR-0022，否则 codex 永远出不了建议按钮）；
+                // 开了子代理就把委派说明接在后面。两者都是 **thread 级**覆盖，
+                // 只对这条新会话生效 —— 不写用户的 `~/.codex/config.toml`，Codex Desktop 不受影响。
+                developerInstructions: [
+                    suggestionGuidance(options.thinkCount?.() ?? null),
+                    codexSubagentGuidance({ enabled: plan.enabled, profiles: plan.profiles }),
+                ]
+                    .filter((part) => part !== null)
+                    .join("\n\n"),
             });
             const threadId = response?.thread?.id;
             if (!threadId)

package/dist/server/engine/dsh-prompt-patch.js

@@ -0,0 +1,48 @@
+/**
+ * 把「下一步建议」的写法带进 dsh（ADR-0022 的 dsh 版）。
+ *
+ * 为什么只能走 patch 文件：ACP 是**唯一**入口，而它的 `session/new` 只有
+ * `cwd / additionalDirectories / mcpServers / _meta`（schema 实测），没有系统提示字段；
+ * dsh 的系统提示由插件栈里的 `@deepseek-ai/dsh-system-prompt` 组装，其中
+ * `personaSuffix` 排在系统提示末尾 —— 正好是这段说明该待的位置。
+ *
+ * 两个必须写清的约束：
+ *   1. patch 的 `config` 是**整块替换**（不是深合并）：只写 `personaSuffix` 会把 acp 模板
+ *      原本的 `personaPrefix` 冲掉（实测 dump 里会整个消失）。所以两句 persona 都带上，
+ *      取值照抄 `@deepseek-ai/dsh-acp-app` 的默认值；dsh 改这两句默认值时这里要跟着改。
+ *   2. 它是**进程级**的：dsh 子进程启动时才 compose 配置栈，所以改完「想想」条数要
+ *      重启工作台（引擎）才生效 —— 不像 pi / codex 那样每条新会话现读。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** `@deepseek-ai/dsh-acp-app` 给 acp profile 的默认 persona（照抄，别改措辞） */
+const PERSONA_PREFIX = "You are a coding agent powered by the {{model}} model.";
+const PERSONA_SUFFIX = "Your working directory is {{cwd}}.";
+/** YAML 块标量的缩进：`personaSuffix: |` 下的内容比 key 深两级 */
+function indentBlock(text) {
+    return text
+        .split("\n")
+        .map((line) => (line === "" ? "" : `      ${line}`))
+        .join("\n");
+}
+/** 纯函数：生成 patch 文件内容（喂给 `dsh --patch <file>`） */
+export function dshSuggestionPatch(guidance) {
+    return [
+        "# 由 oh-my-agent-web 生成（不要手改）：给 dsh 的 system prompt 追加「下一步建议」写法。",
+        "# 改条数请改设置里的「想想」，然后重启工作台 —— dsh 的配置栈是进程启动时 compose 的。",
+        "- id: system-prompt",
+        "  config:",
+        "    personaPrefix: |",
+        indentBlock(PERSONA_PREFIX),
+        "    personaSuffix: |",
+        indentBlock(`${PERSONA_SUFFIX}\n\n${guidance}`),
+        "",
+    ].join("\n");
+}
+/** 写到一个临时目录里（不污染用户的 `dsh-patches` 目录），返回 patch 文件路径 */
+export function writeDshSuggestionPatch(dir, guidance) {
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "dsh-suggestion-patch.yml");
+    writeFileSync(file, dshSuggestionPatch(guidance), "utf8");
+    return file;
+}

package/dist/server/engine/pi-sdk.js

@@ -6,7 +6,7 @@
  *
  * 与 SDK 的对接方式（M3 侦察结论）：
  */
-import { DefaultResourceLoader, SessionManager, createAgentSession, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { DefaultResourceLoader, SessionManager, createAgentSession, getAgentDir, initTheme, } from "@earendil-works/pi-coding-agent";
 import { dirname } from "node:path";
 import { getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
 import { classifyScope } from "../approval/scope.js";
@@ -131,13 +131,26 @@ function toAuthEvent(event) {
 /** 教模型怎么写「下一步建议」（ADR-0022）：刻意写得短（每次请求都付 token） */
 import { reloadModelRegistry } from "./model-registry-reload.js";
 import { NARRATE_GUIDANCE } from "./narrate-guidance.js";
-import { SUGGESTION_GUIDANCE } from "./suggestion-guidance.js";
+import { SUGGESTION_GUIDANCE, suggestionGuidance } from "./suggestion-guidance.js";
 import { SUBAGENT_GUIDANCE } from "./subagent-guidance.js";
 export { NARRATE_GUIDANCE, SUGGESTION_GUIDANCE, SUBAGENT_GUIDANCE };
 import { createPiThinking } from "./pi-thinking.js";
 import { piSdkVersion } from "./pi-version.js";
 import { renameSessionIn } from "./pi-rename.js";
 export function createPiSdkEngine(options = {}) {
+    /**
+     * pi 的 `theme` 是个全局 Proxy：没调过 `initTheme()` 就抛
+     * `Theme not initialized. Call initTheme() first.`（import 本身**不会**初始化它）。
+     *
+     * TUI 启动时自己会初始化，而这个无界面的工作台不会 —— 但扩展里那些「给终端画东西」的代码
+     * （`getMarkdownTheme().heading()`、`new Text(..., theme.fg(...))`）照样会被调用，尤其是
+     * 塞在 `setTimeout` 里的渲染：那个异常没人接，**直接把这个服务进程带走**（同事机器上真踩过：
+     * 扩展 `token-speed.ts` 的定时渲染崩了整个 agent-web）。
+     *
+     * 所以宿主这边先初始化一次，让这类渲染退化成「画了个没人看的东西」，而不是崩服务。
+     * 顺带也是所有 `@earendil-works/*` 导入的唯一出口（本文件）。
+     */
+    initTheme();
     const sessions = new Map();
     const thinking = createPiThinking(sessions);
     let approvalHandler = null;
@@ -234,7 +247,11 @@ export function createPiSdkEngine(options = {}) {
             extensionFactories,
             // 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具
             // 「动手前先说话」：过程默认折叠，不写正文用户就不知道它在干什么
-            appendSystemPrompt: [SUGGESTION_GUIDANCE, NARRATE_GUIDANCE, ...(subagentReady ? [SUBAGENT_GUIDANCE] : [])],
+            appendSystemPrompt: [
+                suggestionGuidance(options.thinkCount?.() ?? null),
+                NARRATE_GUIDANCE,
+                ...(subagentReady ? [SUBAGENT_GUIDANCE] : []),
+            ],
         });
         await resourceLoader.reload();
         const { session } = await createAgentSession({

package/dist/server/engine/suggestion-guidance.js

@@ -1,9 +1,22 @@
-/** 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具 */
-export const SUGGESTION_GUIDANCE = [
-    "## Suggested next actions",
-    "When the user must choose what to do next, end the reply with 4 to 5 lines of:",
-    "[[action:suggest:<button text>]]",
-    "Clicking a button sends that text as the next user message.",
-    "Use [[action:suggest:<short label>,prompt=<text to send>]] when the label should differ from the sent text.",
-    "Put them on their own lines at the very end, and never mention this syntax in prose.",
-].join("\n");
+/**
+ * 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具。
+ *
+ * 条数由调用方给（设置里「想想」那一个 `settings.thinkCount`，取值 1~5）：
+ * 界面上「再给一批」按几条问，模型结尾就写几条 —— 两边用同一个数，不然按钮数和
+ * 「想想」的结果数对不上。拿不到就退回默认区间 4~5（与 ADR-0039 一致）。
+ */
+export function suggestionGuidance(count) {
+    const wanted = typeof count === "number" && Number.isInteger(count) && count >= 1 && count <= 5 ? count : null;
+    const amount = wanted === null ? "4 to 5" : String(wanted);
+    const unit = wanted === 1 ? "line" : "lines";
+    return [
+        "## Suggested next actions",
+        `When the user must choose what to do next, end the reply with ${amount} ${unit} of:`,
+        "[[action:suggest:<button text>]]",
+        "Clicking a button sends that text as the next user message.",
+        "Use [[action:suggest:<short label>,prompt=<text to send>]] when the label should differ from the sent text.",
+        "Put them on their own lines at the very end, and never mention this syntax in prose.",
+    ].join("\n");
+}
+/** 默认版（4~5 条）：给拿不到设置的地方用（测试、临时会话、预热） */
+export const SUGGESTION_GUIDANCE = suggestionGuidance();

package/dist/server/engine/wiring.js

@@ -9,6 +9,7 @@
  * codex 客户端构造时不 spawn：机器上没装 codex 也能正常启动，只有在切到它时才报错。
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createBuiltinEngineRegistry } from "./builtin.js";
 import { enabledSubagentSpecs, readSubagentSettings } from "../subagents/profile-store.js";
@@ -18,6 +19,8 @@ import { createClaudeClient } from "./claude-transport.js";
 import { createCodexSessionsProvider } from "./codex-sessions.js";
 import { createCodexClient } from "./codex-transport.js";
 import { createDshClient } from "./dsh-transport.js";
+import { writeDshSuggestionPatch } from "./dsh-prompt-patch.js";
+import { suggestionGuidance } from "./suggestion-guidance.js";
 import { createDshSessionsProvider } from "./dsh-sessions.js";
 import { createOpencodeSessionsProvider } from "./opencode-sessions.js";
 import { readOpencodeSessionDirs } from "./opencode-projects.js";
@@ -59,7 +62,14 @@ export function createEngineWiring(options) {
      * 顺序 = 环境变量里显式给的 → 用户目录里的 `*.yml`（按文件名）。
      */
     const patchDir = options.dshPatchDir;
+    /**
+     * 「下一步建议」的写法：dsh 只能靠 patch 叠加层带进去（ACP 的 session/new 没有系统提示字段）。
+     * 写在工作台自己的临时目录，**不**混进用户的 `dsh-patches`；排在最前面，
+     * 用户自己写的 patch 仍有最终决定权。
+     */
+    const suggestionPatchFile = writeDshSuggestionPatch(join(tmpdir(), "oh-my-agent-web"), suggestionGuidance(options.thinkCount?.() ?? null));
     const patchFiles = [
+        suggestionPatchFile,
         ...(options.dshPatches ?? []),
         ...(patchDir && existsSync(patchDir)
             ? readdirSync(patchDir)
@@ -154,6 +164,7 @@ export function createEngineWiring(options) {
         onNotice: options.onNotice,
         ...(options.skillPaths ? { skillPaths: options.skillPaths } : {}),
         onLog: (text) => options.onLog(text),
+        ...(options.thinkCount ? { thinkCount: options.thinkCount } : {}),
         codex: { client: codexClient, bin: options.codexBin, subagentPolicy: codexSubagentPolicy },
         dsh: { client: dshClient, bin: options.dshBin, model: defaultModel },
         opencode: {

package/dist/server/index.js

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { acquireLock, describeHolder, releaseLock } from "./session/lock.js";
 import { createRuntime } from "./session/runtime.js";
-import { createFileSettingsStore } from "./session/settings.js";
+import { createFileSettingsStore, readSettingsSync } from "./session/settings.js";
 import { createSender } from "./snapshot/sender.js";
 import { createPiSessionsProvider, piAgentDir } from "./session/pi-sessions-provider.js";
 import { createUploadStore, uploadsDir } from "./uploads/upload-store.js";
@@ -64,11 +64,21 @@ const { config, problems: envProblems, notes: envNotes, workspaceFallback, } = r
     cwd: process.cwd(),
 });
 let fileSink = null;
+/**
+ * 前台运行（CLI 默认）：终端只留 warn / error。
+ *
+ * 以前后台才是默认，这些 info（装载会话索引、每来一个客户端一条「SSE 已连接」……）都落在
+ * daemon.log 里看不见；现在前台成了默认，再照旧打就会把用户自己的输机记录冲没。
+ * 它们仍然**全部**进轮转日志文件；显式给了 `AGENT_WEB_LOG=debug|info` 就按用户的意思正常打。
+ */
+const foreground = process.env.AGENT_WEB_FOREGROUND === "1";
+const quietConsole = foreground && !process.env.AGENT_WEB_LOG;
 const logger = createLogger({
     level: config.logLevel,
     scope: "app",
-    sink: (line) => {
-        process.stdout.write(`${line}\n`);
+    sink: (line, level) => {
+        if (!quietConsole || level === "warn" || level === "error")
+            process.stdout.write(`${line}\n`);
         fileSink?.write(line);
     },
 });
@@ -79,6 +89,18 @@ process.on("unhandledRejection", (reason) => {
         message: reason instanceof Error ? (reason.stack ?? reason.message) : String(reason),
     });
 });
+// 同一个口径的另外半边：**同步抛出**的异常（最典型的是扩展塞在 setTimeout 里的渲染，
+// 比如 `token-speed.ts` 调 pi 的 theme 时抛 `Theme not initialized`）。
+// 没人 catch 的 timer 异常在 Node 里等于「杀进程」—— 一条扩展的渲染错就能把整个工作台带走，
+// 用户看到的就是服务突然没了、终端回到提示符。这里记下来、继续跑。
+//
+// 取舍：单用户本地工作台，宁可带着可能的脏状态继续（顶多某个界面块不刷新），
+// 也不要一按就死 —— 死了连日志面板都打不开。真到了没法自救的地步，用户重启就是了。
+process.on("uncaughtException", (error) => {
+    logger.error("未捕获的异常（已记录，进程继续）", {
+        message: error instanceof Error ? (error.stack ?? error.message) : String(error),
+    });
+});
 /** 局域网地址自动放行；域名仍要显式配 */
 const localAddresses = Object.values(networkInterfaces())
     .flat()
@@ -119,10 +141,15 @@ const engineWiring = createEngineWiring({
     skillPaths: [defaultSkillsDir()],
     // 子代理模板目录：pi 与 codex 共用同一份（codex 的 spawn 类型就是这些模板）
     subagentAgentDir: piAgentDir(),
+    // 「下一步建议」要几条 = 设置里「想想」的那个数：pi / codex 建会话时现读（读的是盘上的
+    // settings.json，改了设置下一条会话就生效）；dsh 只能在启动时取一次（进程级 patch）
+    thinkCount: () => readSettingsSync(config.dataDir).thinkCount,
     workspace: config.workspace,
     piSessions,
     onNotice: (text, level) => runtimeRef.current?.notify(text, level),
-    onLog: (text, meta) => logger.warn(text, meta),
+    // 引擎子进程的 stderr / 诊断输出：正常运行时它是噪声（codex、dsh 都会吐），
+    // 真正要用户知道的事走 onNotice（界面提示）。所以记 info 光进文件，别占终端。
+    onLog: (text, meta) => logger.info(text, meta),
 });
 const engineCatalog = engineWiring.catalog;
 const resolved = engineWiring.resolved;
@@ -391,6 +418,19 @@ async function main() {
         void releaseLock(config.dataDir, process.pid).finally(() => process.exit(1));
     });
     await new Promise((resolve) => httpServer.listen(config.port, config.host, resolve));
+    if (foreground) {
+        // 正常日志已经不在终端刷了，这里给一行「真的跑起来了」的确认 + 最常用的四条命令。
+        // 命令名照用户实际敲的那个（aw / agent-web / oh-my-agent-web），由 cli.ts 传进来。
+        const shownHost = config.host === "0.0.0.0" || config.host === "::" || config.host === "" ? "127.0.0.1" : config.host;
+        const cli = process.env.AGENT_WEB_CLI_NAME || "aw";
+        console.log(`已启动：http://${shownHost}:${config.port}   （Ctrl-C 退出）`);
+        console.log("");
+        console.log(`  后台运行：${cli} -d`);
+        console.log(`  重启 / 停止：${cli} restart · ${cli} stop`);
+        console.log(`  远程访问：${cli} -d -H 0.0.0.0 -P <密码>（用域名访问再加 --allow-host <域名>）`);
+        console.log(`  全部选项：${cli} --help`);
+        console.log("");
+    }
     logger.info("agent-web 已启动", {
         url: `http://${config.host}:${config.port}`,
         workspace: config.workspace,

package/dist/server/session/settings.js

@@ -5,6 +5,7 @@
  * 归一化放在纯函数里（`normalizeQuickPhrases`），因为「用户能贴进来什么」永远想不到 ——
  * 单条超长、重复、空白、几百条，都必须在上盘前收敛。
  */
+import { readFileSync } from "node:fs";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 const SETTINGS_FILE = "settings.json";
@@ -311,6 +312,20 @@ function parseSettings(text) {
 export function settingsPath(dataDir) {
     return join(dataDir, SETTINGS_FILE);
 }
+/**
+ * 同步读设置（缺文件/坏文件 → 默认值，与 `createFileSettingsStore().load()` 同口径）。
+ *
+ * 只给「进程启动时就要定型」的场景用（目前只有一处：dsh 的 system prompt patch）。
+ * 平时请走异步的 SettingsStore —— 这里每调一次就读一次盘。
+ */
+export function readSettingsSync(dataDir) {
+    try {
+        return parseSettings(readFileSync(settingsPath(dataDir), "utf8"));
+    }
+    catch {
+        return defaultSettings();
+    }
+}
 export function createFileSettingsStore(dataDir) {
     return {
         async load() {