@chainingintention/pi-web-cn 2.202610.5 → 2.202611.2

package/docs/README.md

@@ -11,17 +11,21 @@
 | 了解产品、安装和使用 | [网站首页](index.html)、[安装](install.html)、[常见问题](faq.html)、[社区插件](community-plugins.html) |
 | 开始维护代码 | [维护约定](maintenance.md)、[维护者上手](getting-started.md) |
 | 理解整体结构与状态归属 | [架构](development/architecture.md) |
-| 查找共享控件和插件样式入口 | [共享 UI 导航](ui-primitives.md)、[插件样式契约](plugins.md#styles-highlighting-and-display) |
+| 查找共享控件和插件样式入口 | [共享 UI 导航](ui-primitives.md)、[主题架构](theme-architecture.md)、[主题样式契约](theme-styling-contract.md)、[插件样式契约](plugins.md#styles-highlighting-and-display) |
 | 查找模块职责与边界 | [项目与工作区](modules/projects-workspaces.md)、[会话](modules/sessions.md)、[认证与模型](modules/auth-models.md)、[文件与终端](modules/files-terminals.md) |
 | 理解跨机器、插件与配置边界 | [机器/API](modules/machines-api.md)、[插件](modules/plugins.md)、[配置维护](modules/configuration.md) |
 | 管理集成与运行维护 | [管理与审计](admin/management-audit.md)、[运维](admin/operations.md) |
-| 查公开使用契约 | [配置参考](config.md)、[插件指南](plugins.md)、[机器联邦](machines.html)、[远端使用](remote-first.html) |
-| 选择验证与交付检查 | [改动联动](development/change-guide.md)、[开发检查](development-checks.md) |
+| 维护配置分层与翻译 | [配置架构](config-architecture.md)、[本地化开发](localization.md) |
+| 查公开使用契约 | [配置参考](config.md)、[插件指南](plugins.md)、[定时代理任务](scheduled-tasks.md)、[机器联邦](machines.html)、[远端使用](remote-first.html) |
+| 选择验证与交付检查 | [测试政策](testing.md)、[测试夹具](testing-harnesses.md)、[改动联动](development/change-guide.md)、[开发检查](development-checks.md) |
+| 维护网站与临时代码 | [网站部署](website-deployments.md)、[临时代码策略](temporary-code.md) |
+| 准备或审查贡献描述 | [贡献指南](../CONTRIBUTING.md)、[描述审查政策](github-description-review.md) |
 
 ## 目录职责
 
 | 位置 | 内容与边界 |
 | --- | --- |
+| [config-audit.md](config-audit.md) | 配置实施前历史审计；当前行为以配置参考与配置架构为准。 |
 | `docs/` | 用户指南、配置与插件参考、网站页面、社区插件 npm 发现目录及维护入口。成对的 Markdown/HTML 页面保持契约一致。 |
 | [`development/`](development/) | 全局架构、状态所有权和跨模块改动约束。 |
 | [`modules/`](modules/) | 各领域的职责、协作关系、不变量及少量源码导航。 |

package/docs/config.md

@@ -5,6 +5,7 @@
 <a id="config-files"></a>
 ## 配置文件
 
+- **部署默认值**：可选 `PI_WEB_DEFAULTS_CONFIG` 指向只读、同 schema JSON；没有默认路径。显式选择缺失、格式错误或无效文件会失败，不能与可写配置共用路径，两个服务必须使用同一选择。
 - **机器配置**：`$PI_WEB_CONFIG`；未设置时使用 `$XDG_CONFIG_HOME/pi-web/config.json` 或 `~/.config/pi-web/config.json`。
 - **项目配置**：`<project>/.pi-web/config.json`，可提交到仓库。
 - **托管数据**：`$PI_WEB_DATA_DIR`（默认 `~/.pi-web`），不是用户可编辑配置 API。
@@ -23,11 +24,11 @@ Pi 包由目标机器的 `pi install`、`pi remove`、`pi update` 或 **设置
 <a id="chinese-language-plugin"></a>
 ### 中文语言插件
 
-内置 `zh-cn` 默认启用，覆盖核心界面、内置插件、CLI 及 PI WEB 自有提示。要恢复英文，在有效机器配置中设置 `"plugins": { "zh-cn": { "enabled": false } }`。不新增语言选择器或语言配置文件，缺失词条回退英文。
+内置 `zh-cn` 默认启用，覆盖核心界面、内置插件、CLI 及 PI WEB 自有提示。要恢复英文，在有效机器配置中设置 `"plugins": { "zh-cn": { "enabled": false } }`。设置中的语言与区域可独立选择界面语言、格式区域、时区和时制，缺失词条回退英文。浏览器语言选择不改变 CLI/服务端语言。
 
-浏览器语言由网关机器的开关决定，不随所选远端机器切换。每台机器的 CLI 和服务端读取自身配置；远端返回的提示保留远端语言。用户内容、模型回复、第三方输出、命令、错误码及协议字段不会被翻译。
+浏览器的默认中文由网关 zh-cn 插件提供，并服从网关语言默认值、设备选择及环境强制策略，不随所选远端机器切换。每台机器的 CLI 和服务端读取自身配置；远端返回的提示保留远端语言。用户内容、模型回复、第三方输出、命令、错误码及协议字段不会被翻译。
 
-修改后刷新网页；CLI 下次启动生效；服务端需重启。拆分部署时重启 `pi-web-sessiond.service` 和 Web 服务（开发安装为 `pi-web-ui-dev.service`），确保两者使用相同有效 `PI_WEB_CONFIG`。不支持运行中热切换。
+修改后刷新网页；CLI 下次启动生效；服务端需重启。拆分部署时重启 `pi-web-sessiond.service` 和 Web 服务（开发安装为 `pi-web-ui-dev.service`），确保两者使用相同有效 `PI_WEB_CONFIG`。浏览器语言与区域设置可即时切换；插件启用和服务端词典变更仍按上述刷新/重启规则生效。
 
 普通模式模型凭据和自定义模型按注册项目存放在托管目录的 `auth.json`、`models.json`。同一项目所有工作区共享项目存储；首次使用从有效全局 Pi agent 文件复制一次，之后不回退或覆盖。认证、启动与列表请求必须解析到注册项目；运行中的会话保留创建时的项目 registry，即使项目之后关闭。管理嵌入使用独立的 `management-embed/auth.json` 与 `models.json`，不混用普通项目凭据。
 
@@ -55,31 +56,40 @@ Pi 包由目标机器的 `pi install`、`pi remove`、`pi update` 或 **设置
 默认值无需重启，适用于新会话。项目 Pi 设置、显式启动选择及每模型思考设置仍有既定优先级。默认模型必须启用，否则选择首个启用模型。恢复会话保留原模型与思考等级。其他共享 agent 设置（包、扩展、代理等）继续读真实 agent 目录的 `settings.json`。
 
 <a id="default-theme-and-streaming"></a>
+<a id="theme-default-and-device-choices"></a>
 ## 应用主题与发送默认值
 
-`defaultTheme` 是网关配置，形如 `{ "themeId": "plugin-id:theme-id", "auto": true }`：`themeId` 必须为限定贡献 ID，`auto` 必须为布尔值。`auto: true` 在该主题有明暗配对时跟随系统明暗，否则使用所选主题。浏览器设备已保存的主题覆盖优先；主题暂不可用时使用回退，不删除原选择。主题属于整个应用，不保存到当前远端机器；保存/刷新配置后生效，无需重启 daemon。
+网关初始 HTML 携带默认主题详情与 CSS，Auto 包含配对两种变体；不评估主题包代码即可提供静态主题。初始默认主题不在静态目录中（例如旧运行时主题、插件已禁用或未知 ID）时先用 Classic 显示，同时保留原偏好；此引导回退不适用于显式主题查询。设备覆盖按需请求，失败或不可用时保持已提交配色而不抹掉选择；设置页每个对话框首次进入通用页加载完整主题目录，失败可显式重试。主题资产使用带 revision 的 URL 与 HTTP 缓存，不把任意 CSS 写入 localStorage，也不增加配置文件。
 
-在 **设置 → 通用 → 主题** 中，“在此设备使用”保存浏览器覆盖，“设为默认”保存网关默认且不覆盖已有设备选择，“使用默认值”清除此浏览器覆盖并采用应用默认。设置页的“默认主题”说明与应用的默认选择一致；网关未显式配置 `defaultTheme` 时，也会反映 Custom UI Codex 可用时的隐式默认。读取默认值或清除设备覆盖均不写入网关配置。Auto 只在主题有明暗配对时跟随设备。
+`defaultTheme` 是网关配置，形如 `{ "themeId": "plugin-id:theme-id", "auto": true }`：`themeId` 必须为限定贡献 ID，`auto` 必须为布尔值。`auto: true` 在该主题有明暗配对时跟随系统明暗，否则使用所选主题。除环境强制主题外，浏览器设备已保存的主题覆盖优先；主题暂不可用时使用回退，不删除原选择。主题属于整个应用，不保存到当前远端机器；保存/刷新配置后生效，无需重启 daemon。
 
-内置 **Custom UI Codex** 展示插件默认启用，配置 ID 为 `pi-web.custom-ui-codex`。在网关的插件设置中禁用，或在网关有效机器配置设置 `plugins["pi-web.custom-ui-codex"].enabled: false`，刷新页面后恢复宿主默认布局；中文语言插件与权限模式不受影响，无需重启 daemon。远端机器不能替网关接管整个应用界面。
+在 **设置 → 通用 → 主题** 中，“在此设备使用”保存浏览器覆盖，“设为默认”保存网关默认且不覆盖已有设备选择，“使用默认值”清除此浏览器覆盖并采用应用默认。设置页的“默认主题”说明与应用的默认选择一致；网关未显式配置 `defaultTheme` 时，使用内置 `themes:pi-web-dark`，并在 `auto: true` 下跟随系统在 PI WEB Light / Dark 之间切换。读取默认值或清除设备覆盖均不写入网关配置。Auto 只在主题有明暗配对时跟随设备。
 
-该插件启用且设备、网关均未显式选择主题时，使用 Paper / Graphite 明暗配对并跟随系统。已有设备或网关主题选择仍优先。主题限定 ID 为 `pi-web.custom-ui-codex:paper`、`pi-web.custom-ui-codex:graphite`；旧的 `themes:paper`、`themes:graphite` 在插件可用时继续解析到对应主题，设置页的名称、选项及保存操作同样识别这些旧 ID。读取和显示不改写原有配置，只有显式保存才使用当前可用主题的限定 ID。插件不可用时按正常主题回退规则显示，保留原选择以便恢复；设置页仍标记原主题不可用，不允许把回退主题当作原选择保存。
+内置 **Custom UI Codex** 展示插件默认启用，配置 ID 为 `pi-web.custom-ui-codex`。它只提供可选的本地视觉与布局定制，不提供应用默认主题。在网关的插件设置中禁用，或在网关有效机器配置设置 `plugins["pi-web.custom-ui-codex"].enabled: false`，刷新页面后恢复上游默认布局与样式；中文语言插件与权限模式不受影响，无需重启 daemon。远端机器不能替网关接管整个应用界面。
+
+该插件不再通过浏览器 `activate` 注册主题；其配色与明暗配对改为 `package.json` 的静态 `themes` / `themePairs` 声明，并与其他静态主题一样由网关目录收集。Paper / Graphite 等内置配色也由静态目录提供，限定 ID 为 `themes:paper`、`themes:graphite` 和 `themes:paper-graphite`；这些 ID 直接指向内置静态主题，不再是映射到 Custom UI Codex 的旧别名。旧插件命名空间的同名静态主题仍保留，供已保存的显式 `pi-web.custom-ui-codex:` ID 继续解析；它们不是默认值，也不改变内置 `themes:*` 选择。已有设备或网关主题选择照常优先。读取和显示不改写原有配置；主题暂不可用时保留原选择并显示回退，设置页标记该主题不可用，不把回退主题当作原选择保存。
 
 网关 `defaultStreamingBehavior` 为 `"steer"`（默认）或 `"followUp"`，决定流式工作期间编辑器的默认发送方式，不改变已在 daemon 中排队的消息。浏览器分区尺寸、编辑器偏好与普通导航顺序不是新的项目配置文件；导航顺序是按机器管理的托管状态，管理模式不共用普通存储。
 
 <a id="session-naming-and-archives"></a>
 ## 会话命名与归档
 
-机器配置 `sessionNaming` 仅接受以下可选字段，不提供项目覆盖。设置保存后用于后续命名请求，无需重启；每次请求固定自己的有效设置，不覆盖用户已命名会话，也不切换聊天模型。
+<a id="session-naming"></a>
 
-| 设置 | 作用范围 | 默认值 | 改变什么 | 生效 / 重启 |
-| --- | --- | --- | --- | --- |
-| `sessionNaming.model` | 机器 | 当前会话模型 | 命名模型，精确 `provider/model-id`；使用原会话普通项目或管理 registry | 后续命名请求；无需重启 |
-| `sessionNaming.maxTokens` | 机器 | `24` | 命名输出 token 上限，正安全整数 | 后续命名请求；无需重启 |
-| `sessionNaming.thinkingLevel` | 机器 | `minimal` | 命名思考等级，须为已知等级；`off` 不发送 reasoning 参数 | 后续命名请求；无需重启 |
-| `sessionNaming.timeoutMs` | 机器 | `10000` | 命名总耗时上限，整数 `1..2147483647` 毫秒 | 后续命名请求；无需重启 |
+自动命名由随包提供的 **Session naming** Pi 扩展（`@jmfederico/pi-session-naming`）负责，依据新对话的首条提示命名；使用同一有效 Pi profile 的 TUI 也会加载它。可在 **设置 → Pi 包** 移除以使用其他命名扩展，或从“可用包”重新安装；包变更对新会话生效。
+
+在 `<active-agent-profile>/session-naming/config.json`（通常是 `~/.pi/agent/session-naming/config.json`）配置以下可选字段，不再使用核心 `sessionNaming` 配置或命名设置面板：
+
+| 字段 | 默认值 | 契约 |
+| --- | --- | --- |
+| `model` | 当前会话模型 | 精确 `provider/model-id`，仍使用原会话普通项目或管理 registry |
+| `maxTokens` | `24` | 正安全整数；提供器可能将 reasoning 计入该预算，不是标题字数 |
+| `thinkingLevel` | `minimal` | `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；受模型能力限制 |
+| `timeoutMs` | `10000` | 模型加载及生成总耗时，整数 `1..2147483647` 毫秒 |
+
+文件编辑用于下次命名请求，删除字段恢复默认，`{}` 重置文件覆盖。`PI_WEB_SESSION_NAMING` 仍可用 JSON 对象强制指定字段，修改后重启相关进程。命名不切换聊天模型或把项目凭据切换为全局凭据；失败时扩展报告错误并使用提示词开头作为回退名称。
 
-模型不可用、超时或命名失败时使用首条消息的回退名称；标题语言跟随用户请求。命名设置不把项目凭据切换为全局凭据。
+加载核心配置时，旧 `sessionNaming` 值迁移到包文件；已有包配置优先。迁移成功后删除可写核心配置中的旧键；部署默认文件中的旧项需按日志检查目标包文件后手动移除。核心配置 API 拒绝已退役的键。迁移失败保留旧键并继续启动，下次加载重试；修复前命名可能使用已有包配置或默认值。
 
 <a id="session-archive-directory"></a>
 
@@ -88,35 +98,144 @@ Pi 包由目标机器的 `pi install`、`pi remove`、`pi update` 或 **设置
 <a id="mcp-settings-and-authentication"></a>
 ## MCP 设置与认证
 
-**设置 → MCP** 管理所选机器当前非归档会话中已启用、支持 OAuth 的 MCP 服务器认证；先选择可写、空闲且可信的会话。服务器配置由 Pi 的全局/项目设置和信任规则决定，这里不新增 `pi-web` MCP 服务器配置键，也不替代管理模式的 Workbench 受控 MCP 集成。
+**设置 → MCP** 管理所选机器当前非归档会话中已启用、支持 OAuth 的 MCP 服务器认证；先选择可写、空闲且可信的会话。普通会话的服务器配置读取共享 Pi agent 全局根及可信项目；完整特权管理读取管理私有配置根及可信项目，不读取共享 agent 全局根。项目配置遵循 Pi 的信任规则，这里不新增 `pi-web` MCP 服务器配置键，也不替代管理模式的 Workbench 受控 MCP 集成。
 
 也可从操作面板选择 MCP 登录/注销，再选择服务器；设置页直接针对所选服务器。两者使用同一独立认证流程，不切到聊天；禁用、header 认证或 stdio 服务器不列为 OAuth 候选，同机器同时只能进行一项 MCP 认证操作。
 
-专用认证仅支持所选 **Pi 1.3.0** 同一 SDK 的内部凭据适配，未知版本不保证兼容。普通项目与管理使用独立私有 MCP 凭据，不回退共享 agent 的 MCP OAuth 存储；完整特权仍是管理身份，受限管理不提供该流程。认证固定原机器、会话、cwd、项目和 scope，切换选择不会转移流程。注销删除对应保存凭据，影响使用该凭据的其他会话，但不禁用服务器或撤销提供方授权。详见[认证与模型](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/docs/modules/auth-models.md#mcp-认证)。
+专用认证仅支持所选 **Pi 1.3.0 或 1.4.0** 同一 SDK 的内部凭据适配，未知版本不保证兼容。普通项目与管理使用独立私有 MCP 凭据，不回退共享 agent 的 MCP OAuth 存储；完整特权仍是管理身份，受限管理不提供该流程。认证固定原机器、会话、cwd、项目和 scope，切换选择不会转移流程。注销删除对应保存凭据，影响使用该凭据的其他会话，但不禁用服务器或撤销提供方授权。详见[认证与模型](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/docs/modules/auth-models.md#mcp-认证)。
 
 <a id="reverse-proxy-deployment-paths"></a>
 ## 反向代理部署前缀
 
 PI WEB 不需要专门的 URL 前缀配置。同一发布产物可用于 `/`、`/ai/`、`/test/ai/`。代理必须先把不带尾斜线的前缀重定向到带斜线地址，再剥离前缀转发同一认证范围的 HTTP 与 WebSocket。页面相对资源和 PWA 路径依赖这一契约，详见[反向代理安装指南](https://pi-web.dev/install#reverse-proxy-prefix)。
 
+管理换票入口遵循同一前缀：`entryPath` 由平台用带尾斜线的外部应用 base URL 解析一次，不能相对 POST 地址解析。旧 `?embed=management&token=` 长链接仍可能触发 nginx `414`；这是请求行限制，与 `client_max_body_size` 无关，推荐平台改接换票，单独升级不会自动改写旧链接（管理员可临时调高反向代理请求行限制缓解）。见[短入口换票](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/docs/admin/management-audit.md#management-entry-tickets)。
+
 <a id="precedence"></a>
 <a id="precedence-and-reloads"></a>
-## 优先级与生效条件
+## Precedence and reloads
+
+Highest priority first, for layers applicable to that setting:
+
+```text
+enforced environment > browser-local choice > supported project override
+  > writable global config > deployment defaults > built-in defaults
+```
+
+Browser-local choices apply to colour theme, file icon theme, and localization. Project config participates only for supported keys. Environment policy wins over both; it is not a default that projects or browsers can override.
+
+Each declared setting replaces its lower-priority value, including arrays and dictionaries; there is no general recursive merge. The schema declares these namespace leaves: `uploads.defaultFolder`, `attachments.defaultFolder`, `sessionArchive.directory`, `pathAccess.allowedPaths`, and `defaultLocalization.language`, `.formatLocale`, `.timeZone`, `.hourCycle`. Each inherits independently across deployment defaults, writable config, applicable project config, and environment policy. An empty namespace `{}` contributes no overrides; missing leaves inherit.
+
+Each plugin's `enabled` and each top-level `plugins.<id>.settings.<key>` also resolve independently. An individual array/dictionary-valued setting still replaces entirely, including an explicit empty value. `defaultTheme` remains one atomic, coherent preference; `shortcuts` and deprecated `agent` are also atomic. JSON depth alone does not define a setting. Path additions have the separate composition rules below.
+
+### Environment policy
+
+Every nondeprecated runtime core config key has an environment override named `PI_WEB_<SNAKE_CASE_KEY>`. Strings and numbers use scalar values; object/array settings use JSON. See the matrix below for names. Offline plugin recovery state is managed separately by the recovery CLI. For example:
+
+```sh
+PI_WEB_INSTALLATION_NAME='Build lab'
+PI_WEB_BASE_PATHS='["/opt/reference"]'
+PI_WEB_UPLOADS='{"defaultFolder":"manual/uploads"}'
+PI_WEB_DEFAULT_LOCALIZATION='{"timeZone":"UTC"}'
+PI_WEB_PLUGINS='{"git":{"settings":{"workspaceDiscoveryHooks":false}}}'
+```
+
+Container JSON variables keep their existing names: `PI_WEB_UPLOADS`, `PI_WEB_ATTACHMENTS`, `PI_WEB_SESSION_NAMING`, `PI_WEB_SESSION_ARCHIVE`, `PI_WEB_PATH_ACCESS`, and `PI_WEB_DEFAULT_LOCALIZATION`. Only supplied namespace leaves are enforced, including `pathAccess.allowedPaths` and plugin leaves; `{}` enforces none. Atomic settings lock the whole value. `PI_WEB_PORT` retains the `PORT` fallback; a nonempty `PI_WEB_SESSION_ARCHIVE_DIR` alias wins over `PI_WEB_SESSION_ARCHIVE` JSON. `PI_WEB_ALLOWED_HOSTS` accepts JSON `true` or a string array, plus legacy `true`/comma-separated hosts. Allowing all hosts is unsafe for an exposed development server; prefer an explicit list.
+
+Boolean environment inputs accept only `true`/`false` (case-insensitive) or `1`/`0`. Invalid supplied policy values fail startup instead of being ignored. Unknown fields in declared core containers are errors, including misspellings in `pathAccess`, `uploads`, and `attachments`. Plugin environment envelopes accept only `enabled` and `settings`; keys inside `settings` remain plugin-owned. Unset a variable to remove enforcement; empty strings are not a general reset syntax. Legacy empty host, port, allowed-hosts, upload-limit, and archive-directory overrides remain ignored. Runtime-only variables have their own contracts; see offline flags below. Markers such as `PI_WEB_SESSION` are not config policy.
+
+### Sources, saves, and resets
+
+Settings identifies inherited sources and environment-enforced values. Enforced controls are read-only. Where a saved override has a **Reset saved override** control, resetting deletes that override and exposes the next applicable layer; it does not copy today's effective default into the writable file. Loading deployment defaults keeps them separate from writable overrides. Theme and localization enforcement temporarily masks saved browser choices without erasing them; removing policy restores those choices.
+
+The config API returns `config` (writable overrides), `effectiveConfig`, optional `defaultsPath` / `defaultsConfig`, `configSources` (JSON-pointer identifiers mapped to `defaults`, `config`, or the controlling environment variable), and `enforcedSettings` (identifiers mapped to environment variables). Source and enforcement pointers address declared leaves, such as `/defaultLocalization/language` and `/pathAccess/allowedPaths`; the archive alias reports `/sessionArchive/directory`. Missing source entries inherit built-in/feature defaults; this is machine metadata, not browser/project provenance.
+
+Use `PATCH /api/config` for explicit updates, or `PATCH /api/machines/<machineId>/config` for selected-machine-supported keys (`local` selects the gateway machine). The body has optional `set` (config-shaped values) and `unset` (JSON-pointer strings):
+
+```json
+{
+  "set": { "quietMode": true },
+  "unset": ["/defaultTheme", "/defaultLocalization/timeZone", "/plugins/git/settings/workspaceDiscoveryHooks"]
+}
+```
+
+`unset` accepts known leaf pointers such as `/defaultLocalization/language`, `/uploads/defaultFolder`, and `/pathAccess/allowedPaths`, as well as container resets such as `/defaultLocalization`. Atomic settings reset at their top-level pointer, such as `/defaultTheme`. UI container-group resets remove only unlocked saved leaves in one request. An API container reset overlapping any enforced leaf is rejected, preserving saved choices hidden by enforcement. Escape `~` as `~0` and `/` as `~1` within pointer segments: a plugin setting named `a/b~c` uses `/plugins/git/settings/a~1b~0c`. Conflicting set/unset targets and changes to enforced settings are rejected. There is no null reset sentinel: `null` retains its schema-defined meaning, such as disabling a shortcut. Existing `PUT` endpoints remain available. They retain replacement semantics for unenforced settings, but omitted enforced settings preserve their hidden saved values. Supplying a different saved value for an enforced setting is rejected; unchanged saved values may round-trip. This protection also applies when no saved override exists: a legacy save cannot create one for an enforced setting. Federated protection requires the target to report enforcement metadata; upgrade older peers before relying on it.
+
+### When changes apply
+
+Process restarts depend on the key:
+
+- `host` / `port`: restart the gateway web/API service or process.
+- `maxUploadBytes`: restart both the web/API process and the session daemon on that machine.
+- `spawnSessions` / `subsessions` / `sessionMessages` / `askUser` / `extensionDialogsTimeoutMs` / `environmentFacts`: restart the session daemon on that machine.
+- `sessionArchive.directory`: restart the session daemon on that machine; changes only the destination for new archives.
+- Session naming: the removable Pi package reads its file for each new title; old core settings migrate on config load. See [Session naming](#session-naming).
+- `pathAccess`: applies on the next request; existing file views may need a browser refresh.
+- `uploads.defaultFolder`: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
+- `attachments.defaultFolder`: applies to new prompt-attachment saves after config/workspace refresh.
+- `plugins`: browser-only changes need a tab reload. Server-backed enablement, settings, or package changes require a manual session-daemon restart, then a tab reload. See [Project plugin settings](#project-plugin-settings).
+- `serverPlugins.safeStart`: persistent offline recovery state applied before server-plugin discovery/import on the next sessiond start; use the `pi-web plugins safe-start ...` CLI rather than hand-editing it.
+- Pi package changes: use `/reload` in each idle session for ordinary extensions, skills, templates, and themes. Packages containing server plugins require a manual session-daemon restart and browser reload. Global provider registration or connection changes also require a daemon restart; model-list-only updates do not. See [Pi extension provider baseline](#pi-extension-provider-baseline).
+- `shortcuts` / `defaultStreamingBehavior` / `quietMode`: saved settings apply in the browser after config refresh/save; no service restart.
+- `defaultTheme`: applies after settings save or browser config refresh when the browser inherits it or environment policy enforces it; no service restart.
+
+### Localization defaults
+
+Set `defaultLocalization` in the gateway's global config to supply browser defaults:
+
+```json
+{ "defaultLocalization": { "language": "en", "formatLocale": "de-DE", "timeZone": "Europe/Berlin", "hourCycle": "h23" } }
+```
+
+All fields are optional and independent. `language` requests installed translations, with English fallback. `formatLocale` is a standard locale tag. `timeZone` is validated by native `Intl`; omitted zones use the device zone. `hourCycle` accepts `h11`, `h12`, `h23`, or `h24`; omission uses regional conventions. In this fork, omitted UI language uses the bundled zh-cn language preference (English when that plugin is disabled); omitted format locale uses the browser language. No currency or zone is inferred from language. Development pseudo locales cannot be configured here.
+
+Saved browser preferences override defaults independently per field unless that field is enforced by `PI_WEB_DEFAULT_LOCALIZATION`. Settings → General → Language and region saves only explicit browser-local choices, not this server setting. Empty Regional format and Time zone fields inherit the configured gateway value, if any, otherwise the browser’s value; the source and value are shown below each field. Clear a field and apply to resume inheritance for that field, or choose **Use defaults** to clear all local overrides. Existing saved snapshots remain explicit overrides until cleared. Reload the tab after changing config defaults; no service restart is needed. This key is gateway-only, not selected-machine or project-local. Omitted fields inherit lower layers; `{}` adds no overrides, so use reset/unset to remove saved fields.
+
+### Streaming send default
+
+In **Settings → Keyboard shortcuts → Send while agent is running**, choose **Steer** (the default) to deliver input before the next model call, or **Follow-up** to queue it until the current response finishes. This changes only the keyboard shortcut, not the chat buttons. During compaction, messages queue as follow-ups.
+
+The global gateway key is `defaultStreamingBehavior`: `steer` or `followUp`. It is not project-local and needs no service restart.
+
+### Quiet mode
+
+Quiet mode collapses agent activity in the transcript. Tool calls, thinking, results, and skill loads stay in the conversation but start inside one expandable **live events** / **events** summary line instead of being expanded while the agent works. Conversation text, question forms, and tool output images are unchanged.
 
-机器运行配置顺序：内置默认值 → 全局配置 → 环境覆盖。支持的项目键之后应用，上传与附件目录以项目值覆盖，允许路径列表合并去重。
+Turn it on in **Settings → General → Chat display → Quiet mode**. It is off by default. The global gateway key is `quietMode`; it is not project-local and needs no service restart. Devices share the gateway setting, so it is not a per-browser preference.
+
+```json
+{ "quietMode": true }
+```
+
+
+## Machine name
+
+Set `installationName` in the machine's config, enforce it with `PI_WEB_INSTALLATION_NAME`, or edit **Settings → General → Machine name** for the selected machine:
+
+```json
+{ "installationName": "Build lab" }
+```
 
-环境覆盖包含 `PI_WEB_HOST`、`PI_WEB_PORT`/`PORT`、`PI_WEB_ALLOWED_HOSTS`、`PI_WEB_MAX_UPLOAD_BYTES`、`PI_CODING_AGENT_DIR`、`PI_CODING_AGENT_SESSION_DIR`、`PI_WEB_SPAWN_SESSIONS`、`PI_WEB_SUBSESSIONS`、`PI_WEB_ASK_USER`、`PI_WEB_ENVIRONMENT_FACTS`。本地保留的旧 agent/companion 输入另见下文。
+The name replaces the local machine's label and remains visible when there is only one machine, in browsers and installed PWAs. Empty or unset names use **PI-WEB**. Names are trimmed and limited to 120 characters without control characters. This setting is machine-global, not project-local, and needs no restart; reload other open windows to refresh their labels.
 
-- host/port：重启 Web/API。
-- 上传大小：目标机器 Web/API 与 daemon 都重启。
-- 会话工具、扩展对话框超时、环境事实：重启 daemon。
-- 路径访问：下次请求生效；已有视图可需刷新。
-- 上传/附件目录：配置或工作区刷新后的新批次生效。
-- 纯浏览器插件：刷新浏览器。影响 `serverModule` 的启用、设置、包来源或版本：手动重启目标 daemon，再刷新。
-- `serverPlugins.safeStart`：下次 daemon 启动前、发现/导入插件前生效，通过恢复 CLI 管理。
-- Pi 普通资源变更：每个空闲会话执行 `/reload`。服务端插件或全局提供器定义/连接变更仍需手动重启 daemon；已知提供器仅模型列表刷新无需重启。
-- 快捷键：保存或配置刷新后生效。
-- `workbenchIntegration`、管理特权配置或跨进程审计配置：Web/API 与 daemon 保持一致并重启；签名授权仍必须显式允许对应权限。
+Federated gateways use the remote machine's reported name unless you set a **Local display name**. Clear that field to use the remote machine's name again. Existing registry names remain overrides. An unavailable or older remote without a reported name uses **PI-WEB**; a previously discovered name is retained while the gateway process stays running.
+
+The PWA manifest uses the gateway's installation name, with **(dev)** appended for development deployments. Changing the selected remote machine does not rename the installed gateway app. Browsers control when existing launcher names update; reinstall the PWA if its old name remains.
+
+
+### File icon theme
+
+**Settings → General → File icons** selects a complete icon set for Files and Git in this browser, independently of the colour theme. Git uses filename colours and status labels to distinguish changes without tinting the file-type artwork. Material is included locally and selected by default. Its file-type shapes render in one muted grey supplied by the active colour theme, without separate light/dark assets. Choose generic file icons to disable themed icons, or reset the browser choice to return to Material. Unavailable saved themes temporarily fall back to Material without erasing the choice. If Material is unavailable too, Files uses generic icons. Directory expand/collapse indicators remain unchanged.
+
+This is a browser-only preference, with no gateway default, project setting, or environment override. See [file icon contributions](plugins.md#file-icon-themes) for additional icon sets.
+
+
+### Path composition
+
+`basePaths` supplies machine-wide roots. Without environment enforcement, `pathAccess.allowedPaths` adds global and supported project roots, deduplicated after base roots. `PI_WEB_PATH_ACCESS` with `allowedPaths` replaces those additions, not the base roots. `PI_WEB_UPLOADS`, `PI_WEB_ATTACHMENTS`, and `PI_WEB_PLUGINS` enforce supplied leaves over project values.
+
+
+管理集成、管理权限及跨进程审计配置变化仍要求 Web/API 与 daemon 对齐并重启；分层配置不改变普通项目凭据与管理身份隔离。
 
 <a id="global-config-example"></a>
 ## 全局配置示例
@@ -134,6 +253,7 @@ PI WEB 不需要专门的 URL 前缀配置。同一发布产物可用于 `/`、`
   },
   "spawnSessions": true,
   "subsessions": true,
+  "sessionMessages": true,
   "askUser": true,
   "extensionDialogsTimeoutMs": 300000,
   "environmentFacts": true,
@@ -161,12 +281,12 @@ PI WEB 不需要专门的 URL 前缀配置。同一发布产物可用于 `/`、`
 <a id="project-plugin-settings"></a>
 ### 项目插件设置
 
-支持项目设置的服务端插件可读取注册项目根目录的 `.pi-web/config.json` 中 `plugins.<id>.settings`，不是各 worktree 独立配置。项目顶层设置键覆盖机器值，嵌套对象整体替换而非深合并；`enabled` 仍只属于机器配置，项目声明会被拒绝。修改服务端插件的全局或项目设置后，手动重启目标 daemon。
+支持项目设置的服务端插件可读取注册项目根目录的 `.pi-web/config.json` 中 `plugins.<id>.settings`，不是各 worktree 独立配置。未被环境强制的项目顶层设置键覆盖机器值，嵌套对象整体替换而非深合并；`enabled` 仍只属于机器配置，项目声明会被拒绝。修改服务端插件的全局或项目设置后，手动重启目标 daemon。
 
 <a id="git-worktree-discovery-hooks"></a>
 ### Git 工作树发现通知
 
-Git 插件的 `plugins.git.settings.workspaceDiscoveryHooks` 为布尔值，默认 `true`，项目值覆盖机器值。支持命名 hooks 的 Git（2.54+）可安装自身命名通知，保留已有 hooks 且不修改 `core.hooksPath`；不支持时仍可按需刷新列表。通知仅提示宿主重新查询当前提供器，不直接注册工作区。修改后重启 daemon，浏览器刷新不能更新 hook 状态。
+Git 插件的 `plugins.git.settings.workspaceDiscoveryHooks` 为布尔值，默认 `true`，未被环境强制时项目值覆盖机器值。支持命名 hooks 的 Git（2.54+）可安装自身命名通知，保留已有 hooks 且不修改 `core.hooksPath`；不支持时仍可按需刷新列表。通知仅提示宿主重新查询当前提供器，不直接注册工作区。修改后重启 daemon，浏览器刷新不能更新 hook 状态。
 
 <a id="git-instance-namespace"></a>
 
@@ -209,32 +329,36 @@ worktree_path="$1"
 <a id="configuration-matrix"></a>
 ## 配置矩阵
 
-“机器”为所选机器；“网关”为当前浏览器连接的机器。`—` 为无配置文件键的纯环境变量。
+“机器”为所选机器；“网关”为当前浏览器连接的机器。环境强制始终优先于下表的项目或浏览器参与。`—` 为无配置文件键的纯环境变量。
 
 | 配置 | JSON 键 | 环境变量 | 作用域 | 项目行为 / 生效 |
 | --- | --- | --- | --- | --- |
+| 机器名称 | `installationName` | `PI_WEB_INSTALLATION_NAME` | 机器 | 刷新配置；无项目覆盖 |
+| 基础路径根 | `basePaths` | `PI_WEB_BASE_PATHS` | 机器 | 下次文件请求 |
+| 语言区域默认值 | `defaultLocalization` | `PI_WEB_DEFAULT_LOCALIZATION` | 网关 | 刷新浏览器；字段独立 |
+| 安静模式 | `quietMode` | `PI_WEB_QUIET_MODE` | 网关 | 默认 false；保存/刷新 |
 | 监听地址 | `host` | `PI_WEB_HOST` | 网关 | 无项目键；重启 Web/API |
 | 监听端口 | `port` | `PI_WEB_PORT`、`PORT` | 网关 | 无项目键；重启 Web/API |
 | 开发允许主机 | `allowedHosts` | `PI_WEB_ALLOWED_HOSTS` | 网关开发服务 | 重启开发 Web/UI |
-| 外部路径根 | `pathAccess.allowedPaths` | — | 机器 + 项目 | 全局后加项目，去重；下次文件请求 |
-| 上传目录 | `uploads.defaultFolder` | — | 机器 + 项目 | 项目覆盖；新对话框/拖放批次 |
-| 附件目录 | `attachments.defaultFolder` | — | 机器 + 项目 | 项目覆盖；新附件保存 |
+| 外部路径根 | `pathAccess.allowedPaths` | `PI_WEB_PATH_ACCESS` | 机器 + 项目 | basePaths 后加全局/项目；环境替换添加项；下次文件请求 |
+| 上传目录 | `uploads.defaultFolder` | `PI_WEB_UPLOADS` | 机器 + 项目 | 项目覆盖；新对话框/拖放批次 |
+| 附件目录 | `attachments.defaultFolder` | `PI_WEB_ATTACHMENTS` | 机器 + 项目 | 项目覆盖；新附件保存 |
 | 请求大小 | `maxUploadBytes` | `PI_WEB_MAX_UPLOAD_BYTES` | 机器 | Web/API 与 daemon 重启 |
 | 独立会话 | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | daemon | 重启 daemon |
 | 跟踪子会话 | `subsessions` | `PI_WEB_SUBSESSIONS` | daemon | 也需要 `spawnSessions`；重启 |
+| 会话消息 | `sessionMessages` | `PI_WEB_SESSION_MESSAGES` | daemon | 独立于 spawn 开关；重启 |
 | 问题表单 | `askUser` | `PI_WEB_ASK_USER` | daemon | 重启 daemon |
-| 扩展对话框超时 | `extensionDialogsTimeoutMs` | — | daemon | 重启 daemon |
+| 扩展对话框超时 | `extensionDialogsTimeoutMs` | `PI_WEB_EXTENSION_DIALOGS_TIMEOUT_MS` | daemon | 重启 daemon |
 | 环境事实 | `environmentFacts` | `PI_WEB_ENVIRONMENT_FACTS` | daemon | 重启 daemon |
-| 插件期望状态 | `plugins.<id>.enabled/settings` | — | 机器 | 浏览器刷新；服务端重启后刷新 |
-| 项目插件设置 | `plugins.<id>.settings` | — | 机器 + 项目 | 支持的服务端插件顶层覆盖；重启 daemon |
-| Git 发现通知 | `plugins.git.settings.workspaceDiscoveryHooks` | — | 机器 + 项目 | 默认 `true`；重启 daemon |
+| 插件期望状态 | `plugins.<id>.enabled/settings` | `PI_WEB_PLUGINS` | 机器 | 浏览器刷新；服务端重启后刷新 |
+| 项目插件设置 | `plugins.<id>.settings` | `PI_WEB_PLUGINS` | 机器 + 项目 | 支持的服务端插件顶层覆盖；重启 daemon |
+| Git 发现通知 | `plugins.git.settings.workspaceDiscoveryHooks` | `PI_WEB_PLUGINS` | 机器 + 项目 | 默认 `true`；重启 daemon |
 | Git 通知 namespace | — | `PI_WEB_INSTANCE_NAMESPACE` | daemon | 默认空；开发为 `dev`；重启 daemon |
 | 插件恢复 | `serverPlugins.safeStart` | — | 机器离线恢复 | 下次 daemon 启动前应用 |
-| 快捷键 | `shortcuts.<actionId>` | — | 网关 | 保存/刷新配置 |
-| 默认主题 | `defaultTheme.themeId/auto` | — | 网关 | 浏览器覆盖优先；保存/刷新配置 |
-| 流式发送默认方式 | `defaultStreamingBehavior` | — | 网关 | `steer` 或 `followUp`；默认 `steer` |
-| 会话命名 | `sessionNaming.model/maxTokens/thinkingLevel/timeoutMs` | — | 机器 | 后续命名请求生效；无项目覆盖 |
-| 归档目的地 | `sessionArchive.directory` | `PI_WEB_SESSION_ARCHIVE_DIR` | daemon | 重启；不迁移既有归档或索引 |
+| 快捷键 | `shortcuts.<actionId>` | `PI_WEB_SHORTCUTS` | 网关 | 保存/刷新配置 |
+| 默认主题 | `defaultTheme.themeId/auto` | `PI_WEB_DEFAULT_THEME` | 网关 | 浏览器覆盖优先；保存/刷新配置 |
+| 流式发送默认方式 | `defaultStreamingBehavior` | `PI_WEB_DEFAULT_STREAMING_BEHAVIOR` | 网关 | `steer` 或 `followUp`；默认 `steer` |
+| 归档目的地 | `sessionArchive.directory` | `PI_WEB_SESSION_ARCHIVE`、`PI_WEB_SESSION_ARCHIVE_DIR` | 所选机器 daemon | 重启；不迁移既有归档或索引 |
 | 项目版本 | `version` | — | 项目 | 存在时必须为 `1` |
 | 配置文件 | — | `PI_WEB_CONFIG`、`XDG_CONFIG_HOME` | 进程 | 改环境后重启；不是项目配置 |
 | 托管数据 | — | `PI_WEB_DATA_DIR` | Web/API + daemon | 两进程对齐重启；不自动迁移数据 |
@@ -287,6 +411,8 @@ ES 错误记日志，不停止管理会话。有界内存队列重试，并在
 
 默认 request/capability 超时 10000/30000ms、Skill bundle/file 上限 10485760/2097152 字节、文件数 200。适配器把一次性管理 token 换成私有 Agent Session，仅加载授权固定资源快照；并发同 entry token 复用该 Agent Session。
 
+平台的浏览器入口同样先换票：应用相对 `POST api/management-entry-tickets`（JSON 正文 `{"token":"..."}`）返回 `201` 与 `{entryPath, expiresAt}`，不设置浏览器 Cookie；`GET management-entry?ticket=...` 兑换后写管理 HttpOnly Cookie 并 `303` 到 `./?embed=management`。票据一次性、最多 60 秒，最多 256 个待用票据且序列化上下文合计 8 MiB；`POST` 正文 1 MiB、编码上下文 1 MiB（`413`），daemon 内部 HTTP 头限额 1 MiB + 64 KiB，均不提高对外反向代理的请求行限制。换票响应使用 `no-store`，兑换响应附加 `no-referrer`。细节见[短入口换票](https://github.com/nayuto-wakusei/pi-web-ChineseTranslation/blob/main/docs/admin/management-audit.md#management-entry-tickets)。
+
 受控工具为 `icnoc_search_capabilities`、`icnoc_call_capability`、`workbench_search_knowledge`、`workbench_retrieve_knowledge`、`workbench_retrieve_bookstack`、管理文件工具与 Bubblewrap 隔离的 `python`。知识访问经后端短期一次性 token，PI WEB 不配置 RAGFlow/BookStack 服务凭据，工具不接受 tenant/dataset ID。来源链接不是连接配置。全局开关允许时再提供 spawn/跟踪子会话/ask_user，子会话继承管理上下文及显式拒绝。
 
 Python 与受限 bash 默认无网络，只绑定管理工作区及必要的只读运行库；bash 可在该工作区沙盒内执行命令，不默认暴露其他宿主目录。通用 MCP、HTTP、Web 搜索、宿主 shell 和交互终端默认拒绝。签名 token 的 `privileged.bash`/`privileged.network` 仅在机器 `managementEmbed.allowPrivileged: true`（默认 false）时生效；仅 tools.allow 不足以获得特权。单项授权仍采用受限模式，tools.allow/deny 继续有效：仅 bash 授权可提供工作区可写、其他宿主目录只读的沙盒；仅网络授权可启用 http/webfetch/websearch 并移除管理 Python/bash/terminal-command-runs 的 `--unshare-net`，但不增加宿主文件可见性。
@@ -332,7 +458,7 @@ Skill bundle 只从 MCP origin 下载，校验授权固定版本与 manifest，
 <a id="external-path-access"></a>
 ### 外部路径访问
 
-默认相对读取只在工作区内，绝对路径拒绝。`pathAccess.allowedPaths` 允许浏览器文件面板和绝对 `@` 补全列出/读取指定外部根。
+默认相对读取只在工作区内，绝对路径拒绝。`basePaths` 与 `pathAccess.allowedPaths` 的有效根允许浏览器文件面板和绝对 `@` 补全列出/读取指定外部根。
 
 允许 Unix 绝对路径 `/opt/reference`、家目录相对 `~/SDKs`、Windows 宿主上的 `C:\Users\dev\SDKs`。展开 `~`，通过 `realpath` 规范化根，要求存在目录，拒绝符号链接逃逸。不支持相对根。设置保存在所选机器，网关网络设置仍在网关。
 
@@ -341,7 +467,7 @@ Skill bundle 只从 MCP origin 下载，校验授权固定版本与 manifest，
 <a id="manual-upload-defaults"></a>
 ### 手动上传默认目录
 
-文件面板支持多文件：直接拖放立即上传到工作区有效目录；“上传”按钮打开审核对话框，可修改目录和选项。默认 `.pi-web/uploads`，项目 `uploads.defaultFolder` 覆盖机器默认值。
+文件面板支持多文件：直接拖放立即上传到工作区有效目录；“上传”按钮打开审核对话框，可修改目录和选项。默认 `.pi-web/uploads`，未被环境强制时，项目 `uploads.defaultFolder` 覆盖机器默认值。
 
 目录非空且必须相对工作区；重复分隔符和反斜线规范化为 `/`，绝对路径与 `..` 逃逸拒绝。仅审核对话框允许清空目录，把该批次上传到工作区根。默认创建父目录，不覆盖已有文件；审核可显式覆盖，直接拖放从不覆盖。进度展示完成、冲突和错误。联邦使用目标机器/项目目录，大小限制由服务上传的机器控制。
 
@@ -395,8 +521,8 @@ daemon 日志记录忽略的配置变更与模型列表应用，不输出提供
 - 每次最多 **60 秒**，超时/不可达五分钟后**只重试一次**；HTTP 错误留到下次计划。
 - 失败不清空目录，保留最后成功结果并记日志；daemon 关闭会中止在途刷新。
 - 下次请求模型列表才见新目录，已打开选择器可需重新打开。
-- 设置 daemon 环境 `PI_WEB_OFFLINE` 或 `PI_OFFLINE` 后重启，完全禁止目录联网，包括登录后刷新；读取对应存储已有目录。
-- `PI_WEB_SKIP_VERSION_CHECK`/`PI_SKIP_VERSION_CHECK` 只抑制版本检查，不禁止目录刷新。以上离线/跳过标记任意非空值（包括字符串 `0`、`false`）都启用，清空或移除才关闭。
+- 设置 daemon 环境 `PI_WEB_OFFLINE=true` 或 `PI_OFFLINE=true` 后重启，完全禁止目录联网，包括登录后刷新；读取对应存储已有目录。
+- `PI_WEB_SKIP_VERSION_CHECK`/`PI_SKIP_VERSION_CHECK` 只抑制版本检查，不禁止目录刷新。离线/跳过标记只接受 `true`/`false`（大小写不敏感）或 `1`/`0`；空值或其他值导致启动失败。任一离线标记为真即禁止目录刷新；恢复时将相关标记设为假或移除。
 
 <a id="project-trust-for-project-local-resources"></a>
 ### 项目信任
@@ -411,13 +537,25 @@ daemon 日志记录忽略的配置变更与模型列表应用，不输出提供
 <a id="session-tools"></a>
 ### 会话守护进程工具
 
-`spawnSessions` 默认 `true`，提供 `spawn_session`，在同一项目其他工作区发起独立会话，发起后不向父会话回传结果。`subsessions` 默认 `true`，同时要求 `spawnSessions`，提供跟踪子会话工具。子会话始终使用父 cwd，`spawn_subsession` 没有 `cwd`；其他工作区使用独立 `spawn_session`。
+`spawnSessions` 默认 `true`，提供 `spawn_session`，在同一项目工作区创建独立会话，不自动返回结果或授予管理权限。`subsessions` 默认 `true`，同时要求 `spawnSessions`，提供 `spawn_subsession`、`list_subsessions`、`check_subsession`、`read_subsession`、`yield_to_subsessions`、`manage_subsession`。跟踪子会话固定父 cwd，`spawn_subsession` 不接受 `cwd`；其他工作区使用独立会话。
+
+跟踪子会话运行结束只向父会话发送 idle/error 通知，不自动交付最终答案，也不证明任务完成。忙碌父会话在下个安全边界收到通知；父会话可继续工作，或用 `yield_to_subsessions` 等待新通知。已收到的通知不自动重复，详细状态和输出通过 check/read 显式检查。
+
+`manage_subsession` 仅控制直接子会话：`stop` 中断当前运行，`resume` 继续空闲会话，`archive` 归档空闲子会话。可选 `prompt` 只用于 resume；忙碌子会话须先 stop 再归档。停止不冻结进程或撤销已完成写入，不授予控制无关会话或孙会话的权限。
+
+`sessionMessages` 默认 `true`，独立于 spawn 开关，提供 `send_session_message`；设置为 `false` 或 `PI_WEB_SESSION_MESSAGES=0` 并重启 daemon 后移除工具及投递能力。目标必须是同机器、同注册项目中的精确已知会话 ID；可跨工作区，不能发送到归档会话。空闲目标启动新运行，忙碌目标在安全代理边界收到 steering，不中断执行中的工具，压缩或独立 shell 结束后再投递。接受不代表已读或得到回答；队列不是耐久邮箱，停止或关闭会话可能丢弃待处理消息。发送不创建父子关系、检查/控制权限或结果订阅。运行时提供发送者 ID，子会话还获得父 ID，但身份不强制协作流程或额外权限。普通、受限管理与完整特权管理运行时均可提供该工具；管理目标必须属于相同管理作用域，受限模式仍遵守管理工具授权；目标解析拒绝跨普通/管理边界通信。
+
+两种 spawn 支持精确 `provider/model-id`；省略模型继承父模型，思考级别继承并限制到目标模型能力。`#provider/model-id` 引用不自动改变当前会话。
+
+#### 人工介入
+
+代理先在对话中写明问题，再调用 `request_human_intervention`（简短 `reason`）标记“需要输入”并结束当前运行。此工具不受 spawn、消息或问题表单开关控制，也用于审批或 PI WEB 之外的操作；仅写问题文本不设置指示器。静态空心环汇总到工作区、项目和机器，含折叠子会话组；未读状态独立。
 
-跟踪子会话完成会自动通知/唤醒空闲父会话，无需轮询。父会话可继续独立工作，或在 join 点单独调用 `yield_to_subsessions` 作为批次最后动作：仍有工作则结束当前代理运行，没有工作则明确报告且不结束。`list_subsessions`、`check_subsession`、`read_subsession` 用于有意检查，不更改控制流；工作期间隐藏部分输出，完成后输出可用。过长完成结果不重复截断进上下文，指引使用 `check_subsession`。
+任何新代理运行都会清除代理请求的介入状态；只排队消息、阅读会话或浏览历史不会清除。仍需帮助时应重新请求。该状态随会话持久化并跨 daemon 重启保留，不是分支专属表单。新 `ask_user` 表单自动设置相同状态；待答扩展对话框也显示“需要输入”，但保留独立取消/超时生命周期，运行时对话框不跨 daemon 重启恢复。升级后重启 daemon 激活工具及跟踪。
 
-两种 spawn 都支持精确 `provider/model-id` 的 `model`；未知/错误格式拒绝。省略时继承父模型，思考级别也继承并限制到模型能力。`#provider/model-id` 引用表达用户模型选择，不自动改变当前会话。
+#### 问题表单
 
-`askUser` 默认 `true`，可在 **设置 → 会话守护进程** 切换。问题表单支持 1–20 问，每问最多 12 选项、可选多选、始终可自定义文本，可以不回答。普通消息取消开放表单，新表单替代旧表单；daemon 仍活跃时开放表单可跨浏览器/Web 重启保留。修改开关或升级工具实现需重启 daemon。管理生成子会话仍保留原管理上下文及显式工具拒绝。
+`askUser` 默认 `true`，在 **设置 → 会话守护进程** 切换。表单支持 1–20 问，每问最多 12 选项、可选多选及自定义文本，可跳过。表单随对话持久化并跨重启保留，只有活动对话末尾表单开放；回答、跳过或发送消息关闭它，旧表单仍可展开只读查看。历史树回到该问题会重新开放，归档对话只读。修改开关或升级实现需重启 daemon。管理子会话仍保留原管理上下文及显式工具拒绝。
 
 <a id="extension-dialogs"></a>
 ### 扩展对话框
@@ -430,7 +568,7 @@ daemon 日志记录忽略的配置变更与模型列表应用，不输出提供
 <a id="plugin-config"></a>
 ### 插件配置与恢复
 
-`plugins` 控制纯浏览器、纯服务端与双入口的期望启用状态和 JSON 设置，不管理 Pi 包安装。默认启用，包可声明 `defaultEnabled: false`，Captain's Log 如此；显式配置覆盖包默认。必需 `pi-web.terminal` 普通启动不能禁用，设置中不可编辑。服务端设置启动时生效，诊断不暴露设置值。
+`plugins` 控制纯浏览器、纯服务端与双入口的期望启用状态和 JSON 设置，不管理 Pi 包安装。默认启用，包可声明 `defaultEnabled: false`；显式配置覆盖包默认。必需 `pi-web.terminal` 普通启动不能禁用，设置中不可编辑。服务端设置启动时生效，诊断不暴露设置值。
 
 ```json
 {
@@ -442,7 +580,7 @@ daemon 日志记录忽略的配置变更与模型列表应用，不输出提供
 }
 ```
 
-保存或换包改变期望状态，不替换运行代码。禁用服务端插件及配套 UI 可在重启前仍运行；包/设置不匹配、健康或兼容异常时暂缓配套 UI。设置区分期望与实际状态，daemon 不可用时实际状态不可用。混合版本不支持，远端插件/Git 可不可用或 404；网关/目标一起升级，重启更新的 Web/API 与目标 daemon 后刷新。不能回退到网关。
+保存或换包改变期望状态，不替换运行代码。`npm run dev:web` 默认启用进程级 `PI_WEB_DEV_PLUGIN_PAIRING=1`，仅开发启动允许刷新后的 UI 连接仍运行的旧后端；设置为 `0` 恢复严格配对。生产默认严格，后端变化仍需手动重启 daemon。禁用服务端插件及配套 UI 可在重启前仍运行；包/设置不匹配、健康或兼容异常时暂缓配套 UI。设置区分期望与实际状态，daemon 不可用时实际状态不可用。混合版本不支持，远端插件/Git 可不可用或 404；网关/目标一起升级，重启更新的 Web/API 与目标 daemon 后刷新。不能回退到网关。
 
 顺序：安装/更新目标包 → 保存期望配置 → 纯浏览器刷新；服务端则手动重启目标 daemon、等就绪、再刷新。重启可能中断活跃会话和所有权。仅浏览器刷新、Web/UI 自动重载、Web/API 重启、Pi `/reload` 都不激活服务端变化。