git:20260922.c7d696c to git:20261017.d758347

1 added, 0 removed. Audit A to A.

---

name: configure-pi-naming

description: 配置 Pi 统一 /rename、首条消息命名和终端目标归属。Use when configuring pi-naming.

---

# 配置 pi-naming / Configure pi-naming

读取 `<pi-agent-dir>/extensions/pi-naming/config.json`，遵守 `PI_CODING_AGENT_DIR`。使用 `/config:naming` 打开 TUI 配置面板（Pi 自带 SettingsList），输入 `reset` 恢复默认值；面板里改一项立即生效，不需要 reload。字段和默认值见关联文档和配置示例。

Use `/config:naming` to open the TUI settings panel (Pi's SettingsList); use `reset` for defaults. Changes apply immediately, no reload needed after saving.

- `automaticNaming` / `manualNaming` 控制自动输入和 `/rename [名称]`，`targets` 直接分别控制 session/workspace/tab。Control automatic input and `/rename [name]`; `targets` directly selects session/workspace/tab.

- `title` 控制长度、语言、补充提示、超时、输出预算和思考档位（`maxTokens` 默认 2048、`effort` 默认 low，二者与 `maxLength` 相互独立）；模型鉴权复用 Pi。Controls length, language, instructions, timeout, output budget and thinking effort (`maxTokens` default 2048, `effort` default low, both independent from `maxLength`); model authentication comes from Pi.

+ - `title.usePromptAsTitle` 默认 false；打开后用首条非空提示词与当前目录名生成 `目录名: 提示词`，自动和不带名称的 `/rename` 都不调用模型，也无需鉴权。整个标题受 `maxLength` 限制，目录最多占可用空间一半，上限小于 5 时仅保留提示词；其他模型偏好不适用。Defaults to false; enable it to use `directory: first prompt` without a model or credentials. The full title respects `maxLength`, reserving at least half the space for the prompt; limits below 5 omit the directory. Model-only preferences do not apply.

- 无终端也可命名 session；终端失败与跳过必须报告。普通会话明确目标路径不受旧 `PI_SUBAGENT_RENAME_*` 变量影响；关闭 target 即使变量为 `1` 也不执行。Session naming works without a terminal; report terminal failures and skips. The ordinary-session explicit-target path ignores legacy `PI_SUBAGENT_RENAME_*` variables; a disabled target never runs even when a variable is `1`.

- 子进程归属由启动方通过 mux 协议提供，不把 pane 扩大为共享 tab，不修改父 workspace。Launchers grant child targets through the mux protocol; never expand a pane to a shared tab or rename the parent workspace.

- 子代理需要显式配置 `subagentExtensions` 加载 naming。Child extension isolation requires explicitly loading naming in `subagentExtensions`.

运行 `npm run check -w pi-naming`。真实终端和模型未验证时标记 `NOT_RUN`，不以单元测试替代实测。

Run `npm run check -w pi-naming`. Mark unperformed real terminal/model checks `NOT_RUN`; unit tests are not a substitute.